\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename python.info
@documentencoding UTF-8
@ifinfo
@*Generated by Sphinx 8.2.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.16.0a0, Μαΐου 10, 2026

Author name not set

Copyright @copyright{} 2001 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{13e}
@menu
* Τι νέο υπάρχει στην Python:: 
* Οδηγός εκμάθησης Python:: 
* Ρύθμιση και Χρήση της Python:: 
* Εγχειρίδιο Αναφοράς της Γλώσσας Python:: 
* The Python Standard Library:: 
* Επέκταση και Ενσωμάτωση του Διερμηνέα της Python:: 
* Python/C API reference manual:: 
* Installing Python modules:: 
* Python HOWTOs:: 
* Συχνές Ερωτήσεις για την Python:: 
* Deprecations:: 
* Γλωσσάρι:: 
* Σχετικά με την τεκμηρίωση:: 
* Αντιμετώπιση Σφαλμάτων:: 
* Copyright:: 
* Ιστορία και Άδεια:: 
* Ευρετήριο Μονάδων της Python:: 
* Ευρετήριο:: 

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

Τι νέο υπάρχει στην Python

* What’s new in Python 3.16: What’s new in Python 3 16. 
* What’s new in Python 3.15: What’s new in Python 3 15. 
* What’s new in Python 3.14: What’s new in Python 3 14. 
* 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. 
* What’s New In Python 3.11: What’s New In Python 3 11. 
* What’s New In Python 3.10: What’s New In Python 3 10. 
* What’s New In Python 3.9: What’s New In Python 3 9. 
* What’s New In Python 3.8: What’s New In 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. 
* What’s New In Python 3.5: What’s New In Python 3 5. 
* What’s New In Python 3.4: What’s New In Python 3 4. 
* What’s New In Python 3.3: What’s New In Python 3 3. 
* What’s New In Python 3.2: What’s New In Python 3 2. 
* What’s New In Python 3.1: What’s New In Python 3 1. 
* What’s New In Python 3.0: What’s New In Python 3 0. 
* What’s New in Python 2.7: What’s New in Python 2 7. 
* What’s New in Python 2.6: What’s New in Python 2 6. 
* What’s New in Python 2.5: What’s New in Python 2 5. 
* What’s New in Python 2.4: What’s New in Python 2 4. 
* What’s New in Python 2.3: What’s New in Python 2 3. 
* What’s New in Python 2.2: What’s New in Python 2 2. 
* What’s New in Python 2.1: What’s New in Python 2 1. 
* What’s New in Python 2.0: What’s New in Python 2 0. 
* Changelog:: 

What’s new in Python 3.16

* Summary — release highlights:: 
* New features:: 
* Other language changes:: 
* New modules:: 
* Improved modules:: 
* Optimizations:: 
* Removed:: 
* Deprecated:: 
* Porting to Python 3.16: Porting to Python 3 16. 
* Build changes:: 
* C API changes:: 

Improved modules

* module_name:: 

Optimizations

* module_name: module_name<2>. 

Removed

* annotationlib:: 
* functools:: 
* symtable:: 
* sysconfig:: 

C API changes

* New features: New features<2>. 
* Porting to Python 3.16: Porting to Python 3 16<2>. 
* Deprecated C APIs:: 
* Removed C APIs:: 

What’s new in Python 3.15

* Summary – Release highlights:: 
* New features: New features<3>. 
* Other language changes: Other language changes<2>. 
* Default interactive shell:: 
* New modules: New modules<2>. 
* Improved modules: Improved modules<2>. 
* Optimizations: Optimizations<2>. 
* Removed: Removed<2>. 
* Deprecated: Deprecated<2>. 
* C API changes: C API changes<2>. 
* Build changes: Build changes<2>. 
* Porting to Python 3.15: Porting to Python 3 15. 

New features

* PEP 810; Explicit lazy imports: PEP 810 Explicit lazy imports. 
* PEP 814; Add frozendict built-in type: PEP 814 Add frozendict built-in type. 
* PEP 661; Add sentinel built-in type: PEP 661 Add sentinel built-in type. 
* PEP 799; A dedicated profiling package: PEP 799 A dedicated profiling package. 
* Tachyon; High frequency statistical sampling profiler: Tachyon High frequency statistical sampling profiler. 
* PEP 831; Frame pointers enabled by default: PEP 831 Frame pointers enabled by default. 
* PEP 798; Unpacking in comprehensions: PEP 798 Unpacking in comprehensions. 
* PEP 829; Package startup configuration files: PEP 829 Package startup configuration files. 
* PEP 803 – Stable ABI for free-threaded builds:: 
* PEP 788; Protecting the C API from interpreter finalization: PEP 788 Protecting the C API from interpreter finalization. 
* Improved error messages:: 

New modules

* math.integer: math integer. 

Improved modules

* argparse:: 
* array:: 
* ast:: 
* asyncio:: 
* base64:: 
* binascii:: 
* calendar:: 
* collections:: 
* concurrent.futures: concurrent futures. 
* contextlib:: 
* dataclasses:: 
* dbm:: 
* difflib:: 
* email:: 
* faulthandler:: 
* functools: functools<2>. 
* gc:: 
* hashlib:: 
* http.client: http client. 
* http.server: http server. 
* inspect:: 
* json:: 
* locale:: 
* math:: 
* mimetypes:: 
* mmap:: 
* os:: 
* os.path: os path. 
* pdb:: 
* pickle:: 
* pickletools:: 
* pprint:: 
* re:: 
* resource:: 
* shelve:: 
* socket:: 
* sqlite3:: 
* ssl:: 
* subprocess:: 
* symtable: symtable<2>. 
* sys:: 
* sys.monitoring: sys monitoring. 
* tarfile:: 
* threading:: 
* timeit:: 
* tkinter:: 
* tokenize:: 
* tomllib:: 
* types:: 
* typing:: 
* unicodedata:: 
* unittest:: 
* urllib.parse: urllib parse. 
* venv:: 
* warnings:: 
* wave:: 
* webbrowser:: 
* xml:: 
* xml.parsers.expat: xml parsers expat. 
* zlib:: 

Optimizations

* base64 & binascii:: 
* csv:: 
* Upgraded JIT compiler:: 

Removed

* ast: ast<2>. 
* collections.abc: collections abc. 
* ctypes:: 
* datetime:: 
* glob:: 
* http.server: http server<2>. 
* importlib.resources: importlib resources. 
* pathlib:: 
* platform:: 
* sre_*:: 
* sysconfig: sysconfig<2>. 
* threading: threading<2>. 
* types: types<2>. 
* typing: typing<2>. 
* wave: wave<2>. 
* zipimport:: 

Deprecated

* New deprecations:: 
* Pending removal in Python 3.16: Pending removal in Python 3 16. 
* Pending removal in Python 3.17: Pending removal in Python 3 17. 
* Pending removal in Python 3.18: Pending removal in Python 3 18. 
* Pending removal in Python 3.19: Pending removal in Python 3 19. 
* Pending removal in Python 3.20: Pending removal in Python 3 20. 
* Pending removal in future versions:: 
* Soft deprecations:: 

C API changes

* New features: New features<4>. 
* Changed C APIs:: 
* Removed C APIs: Removed C APIs<2>. 
* Deprecated C APIs: Deprecated C APIs<2>. 

What’s new in Python 3.14

* Summary – Release highlights: Summary – Release highlights<2>. 
* New features: New features<5>. 
* Other language changes: Other language changes<3>. 
* New modules: New modules<3>. 
* Improved modules: Improved modules<3>. 
* Optimizations: Optimizations<3>. 
* Removed: Removed<3>. 
* Deprecated: Deprecated<3>. 
* CPython bytecode changes:: 
* C API changes: C API changes<3>. 
* Build changes: Build changes<3>. 
* Porting to Python 3.14: Porting to Python 3 14. 
* Notable changes in 3.14.5: Notable changes in 3 14 5. 

New features

* PEP 649 & PEP 749; Deferred evaluation of annotations: PEP 649 & PEP 749 Deferred evaluation of annotations. 
* PEP 734; Multiple interpreters in the standard library: PEP 734 Multiple interpreters in the standard library. 
* PEP 750; Template string literals: PEP 750 Template string literals. 
* PEP 768; Safe external debugger interface: PEP 768 Safe external debugger interface. 
* A new type of interpreter:: 
* Free-threaded mode improvements:: 
* Improved error messages: Improved error messages<2>. 
* PEP 784; Zstandard support in the standard library: PEP 784 Zstandard support in the standard library. 
* Asyncio introspection capabilities:: 
* Concurrent safe warnings control:: 

Other language changes

* Built-ins:: 
* Command line and environment:: 
* PEP 758; Allow except and except* expressions without brackets: PEP 758 Allow except and except* expressions without brackets. 
* PEP 765; Control flow in finally blocks: PEP 765 Control flow in finally blocks. 
* Garbage collection:: 
* Default interactive shell: Default interactive shell<2>. 

Improved modules

* argparse: argparse<2>. 
* ast: ast<3>. 
* asyncio: asyncio<2>. 
* calendar: calendar<2>. 
* concurrent.futures: concurrent futures<2>. 
* configparser:: 
* contextvars:: 
* ctypes: ctypes<2>. 
* curses:: 
* datetime: datetime<2>. 
* decimal:: 
* difflib: difflib<2>. 
* dis:: 
* errno:: 
* faulthandler: faulthandler<2>. 
* fnmatch:: 
* fractions:: 
* functools: functools<3>. 
* getopt:: 
* getpass:: 
* graphlib:: 
* heapq:: 
* hmac:: 
* http:: 
* imaplib:: 
* inspect: inspect<2>. 
* io:: 
* json: json<2>. 
* linecache:: 
* logging.handlers: logging handlers. 
* math: math<2>. 
* mimetypes: mimetypes<2>. 
* multiprocessing:: 
* operator:: 
* os: os<2>. 
* os.path: os path<2>. 
* pathlib: pathlib<2>. 
* pdb: pdb<2>. 
* pickle: pickle<2>. 
* platform: platform<2>. 
* pydoc:: 
* re: re<2>. 
* socket: socket<2>. 
* ssl: ssl<2>. 
* struct:: 
* symtable: symtable<3>. 
* sys: sys<2>. 
* sys.monitoring: sys monitoring<2>. 
* sysconfig: sysconfig<3>. 
* tarfile: tarfile<2>. 
* threading: threading<3>. 
* tkinter: tkinter<2>. 
* turtle:: 
* types: types<3>. 
* typing: typing<3>. 
* unicodedata: unicodedata<2>. 
* unittest: unittest<2>. 
* urllib:: 
* uuid:: 
* webbrowser: webbrowser<2>. 
* zipfile:: 

Optimizations

* asyncio: asyncio<3>. 
* base64: base64<2>. 
* bdb:: 
* difflib: difflib<3>. 
* gc: gc<2>. 
* io: io<2>. 
* pathlib: pathlib<3>. 
* pdb: pdb<3>. 
* textwrap:: 
* uuid: uuid<2>. 
* zlib: zlib<2>. 

Removed

* argparse: argparse<3>. 
* ast: ast<4>. 
* asyncio: asyncio<4>. 
* email: email<2>. 
* importlib.abc: importlib abc. 
* itertools:: 
* pathlib: pathlib<4>. 
* pkgutil:: 
* pty:: 
* sqlite3: sqlite3<2>. 
* urllib: urllib<2>. 

Deprecated

* New deprecations: New deprecations<2>. 
* Pending removal in Python 3.15: Pending removal in Python 3 15. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<2>. 
* Pending removal in Python 3.17: Pending removal in Python 3 17<2>. 
* Pending removal in Python 3.18: Pending removal in Python 3 18<2>. 
* Pending removal in Python 3.19: Pending removal in Python 3 19<2>. 
* Pending removal in Python 3.20: Pending removal in Python 3 20<2>. 
* Pending removal in future versions: Pending removal in future versions<2>. 

CPython bytecode changes

* Pseudo-instructions:: 

C API changes

* Python configuration C API:: 
* New features in the C API:: 
* Limited C API changes:: 
* Removed C APIs: Removed C APIs<3>. 
* Deprecated C APIs: Deprecated C APIs<3>. 

Deprecated C APIs

* Pending removal in Python 3.15: Pending removal in Python 3 15<2>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<3>. 
* Pending removal in Python 3.18: Pending removal in Python 3 18<3>. 
* Pending removal in future versions: Pending removal in future versions<3>. 

Build changes

* build-details.json: build-details json. 
* Discontinuation of PGP signatures:: 
* Free-threaded Python is officially supported:: 
* Binary releases for the experimental just-in-time compiler:: 

Porting to Python 3.14

* Changes in the Python API:: 
* Changes in annotations (PEP 649 and PEP 749): Changes in annotations PEP 649 and PEP 749. 
* Changes in the C API:: 

Changes in annotations (PEP 649 and PEP 749)

* Implications for annotated code:: 
* Implications for readers of __annotations__:: 
* Related changes:: 
* from __future__ import annotations:: 

Notable changes in 3.14.5

* gc: gc<3>. 

What’s New In Python 3.13

* Summary – Release Highlights:: 
* New Features:: 
* Other Language Changes:: 
* New Modules:: 
* Improved Modules:: 
* Optimizations: Optimizations<4>. 
* Removed Modules And APIs:: 
* New Deprecations:: 
* CPython Bytecode Changes:: 
* C API Changes:: 
* Build Changes:: 
* Porting to Python 3.13: Porting to Python 3 13. 
* Regression Test Changes:: 

New Features

* A better interactive interpreter:: 
* Improved error messages: Improved error messages<3>. 
* 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:: 

Improved Modules

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

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<3>. 
* importlib.metadata: importlib metadata. 
* locale: locale<2>. 
* opcode:: 
* optparse:: 
* pathlib: pathlib<6>. 
* re: re<4>. 
* tkinter.tix: tkinter tix. 
* turtle: turtle<2>. 
* typing: typing<5>. 
* unittest: unittest<3>. 
* urllib: urllib<3>. 
* webbrowser: webbrowser<3>. 

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<3>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<4>. 
* Pending removal in Python 3.17: Pending removal in Python 3 17<3>. 
* Pending removal in Python 3.18: Pending removal in Python 3 18<4>. 
* Pending removal in Python 3.19: Pending removal in Python 3 19<3>. 
* Pending removal in Python 3.20: Pending removal in Python 3 20<3>. 
* Pending removal in future versions: Pending removal in future versions<4>. 

C API Changes

* New Features: New Features<2>. 
* Changed C APIs: Changed C APIs<2>. 
* Limited C API Changes:: 
* Removed C APIs: Removed C APIs<4>. 
* Deprecated C APIs: Deprecated C APIs<4>. 

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<4>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<5>. 
* Pending removal in Python 3.18: Pending removal in Python 3 18<5>. 
* Pending removal in future versions: Pending removal in future versions<5>. 

Porting to Python 3.13

* Changes in the Python API: Changes in the Python API<2>. 
* Changes in the C API: Changes in the C API<2>. 

What’s New In Python 3.12

* Summary – Release highlights: Summary – Release highlights<3>. 
* New Features: New Features<3>. 
* New Features Related to Type Hints:: 
* Other Language Changes: Other Language Changes<2>. 
* New Modules: New Modules<2>. 
* Improved Modules: Improved Modules<2>. 
* Optimizations: Optimizations<5>. 
* CPython bytecode changes: CPython bytecode changes<2>. 
* Demos and Tools:: 
* Deprecated: Deprecated<4>. 
* Removed: Removed<4>. 
* Porting to Python 3.12: Porting to Python 3 12. 
* Build Changes: Build Changes<2>. 
* C API Changes: C API Changes<2>. 

New Features

* 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:: 

New Features Related to Type Hints

* 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. 

Improved Modules

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

Deprecated

* 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<5>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<6>. 
* Pending removal in Python 3.17: Pending removal in Python 3 17<4>. 
* Pending removal in Python 3.19: Pending removal in Python 3 19<4>. 
* Pending removal in Python 3.20: Pending removal in Python 3 20<4>. 
* Pending removal in future versions: Pending removal in future versions<6>. 

Removed

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

Porting to Python 3.12

* Changes in the Python API: Changes in the Python API<3>. 

C API Changes

* New Features: New Features<4>. 
* Porting to Python 3.12: Porting to Python 3 12<2>. 
* Deprecated: Deprecated<5>. 
* Removed: Removed<5>. 

Deprecated

* 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<6>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<7>. 
* Pending removal in future versions: Pending removal in future versions<7>. 

What’s New In Python 3.11

* Summary – Release highlights: Summary – Release highlights<4>. 
* New Features: New Features<5>. 
* New Features Related to Type Hints: New Features Related to Type Hints<2>. 
* Other Language Changes: Other Language Changes<3>. 
* Other CPython Implementation Changes:: 
* New Modules: New Modules<3>. 
* Improved Modules: Improved Modules<3>. 
* Optimizations: Optimizations<6>. 
* Faster CPython:: 
* CPython bytecode changes: CPython bytecode changes<3>. 
* Deprecated: Deprecated<6>. 
* Pending Removal in Python 3.12: Pending Removal in Python 3 12. 
* Removed: Removed<6>. 
* Porting to Python 3.11: Porting to Python 3 11. 
* Build Changes: Build Changes<3>. 
* C API Changes: C API Changes<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. 

New Features

* PEP 657; Fine-grained error locations in tracebacks: PEP 657 Fine-grained error locations in tracebacks. 
* PEP 654; Exception Groups and except*: PEP 654 Exception Groups and except*. 
* PEP 678; Exceptions can be enriched with notes: PEP 678 Exceptions can be enriched with notes. 
* Windows py.exe launcher improvements: Windows py exe launcher improvements. 

New Features Related to Type Hints

* 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:: 

Improved Modules

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

Faster CPython

* Faster Startup:: 
* Faster Runtime:: 
* Misc:: 
* FAQ:: 
* About:: 

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?:: 

CPython bytecode changes

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

Deprecated

* Language/Builtins:: 
* Modules:: 
* Standard Library:: 

C API Changes

* New Features: New Features<6>. 
* Porting to Python 3.11: Porting to Python 3 11<2>. 
* Deprecated: Deprecated<7>. 
* Pending Removal in Python 3.12: Pending Removal in Python 3 12<2>. 
* Removed: Removed<7>. 

Notable changes in 3.11.4

* tarfile: tarfile<3>. 

Notable changes in 3.11.5

* OpenSSL:: 

What’s New In Python 3.10

* Summary – Release highlights: Summary – Release highlights<5>. 
* New Features: New Features<7>. 
* New Features Related to Type Hints: New Features Related to Type Hints<3>. 
* Other Language Changes: Other Language Changes<4>. 
* New Modules: New Modules<4>. 
* Improved Modules: Improved Modules<4>. 
* Optimizations: Optimizations<7>. 
* Deprecated: Deprecated<8>. 
* Removed: Removed<8>. 
* Porting to Python 3.10: Porting to Python 3 10. 
* CPython bytecode changes: CPython bytecode changes<4>. 
* Build Changes: Build Changes<4>. 
* C API Changes: C API Changes<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. 

New Features

* Parenthesized context managers:: 
* Better error messages:: 
* PEP 626; Precise line numbers for debugging and other tools: PEP 626 Precise line numbers for debugging and other tools. 
* PEP 634; Structural Pattern Matching: PEP 634 Structural Pattern Matching. 
* Optional EncodingWarning and encoding="locale" option:: 

Better error messages

* SyntaxErrors:: 
* IndentationErrors:: 
* AttributeErrors:: 
* NameErrors:: 

PEP 634: Structural Pattern Matching

* Syntax and operations:: 
* Declarative approach:: 
* Simple pattern; match to a literal: Simple pattern match to a literal. 
* Patterns with a literal and variable:: 
* Patterns and classes:: 
* Nested patterns:: 
* Complex patterns and the wildcard:: 
* Guard:: 
* Other Key Features:: 

Simple pattern: match to a literal

* Behavior without the wildcard:: 

Patterns and classes

* Patterns with positional parameters:: 

New Features Related to Type Hints

* PEP 604; New Type Union Operator: PEP 604 New Type Union Operator. 
* PEP 612; Parameter Specification Variables: PEP 612 Parameter Specification Variables. 
* PEP 613; TypeAlias: PEP 613 TypeAlias. 
* PEP 647; User-Defined Type Guards: PEP 647 User-Defined Type Guards. 

Improved Modules

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

dataclasses

* __slots__:: 
* Keyword-only fields:: 

Porting to Python 3.10

* Changes in the Python syntax:: 
* Changes in the Python API: Changes in the Python API<4>. 
* Changes in the C API: Changes in the C API<3>. 

C API Changes

* PEP 652; Maintaining the Stable ABI: PEP 652 Maintaining the Stable ABI. 
* New Features: New Features<8>. 
* Porting to Python 3.10: Porting to Python 3 10<2>. 
* Deprecated: Deprecated<9>. 
* Removed: Removed<9>. 

Notable changes in 3.10.12

* tarfile: tarfile<4>. 

What’s New In Python 3.9

* Summary – Release highlights: Summary – Release highlights<6>. 
* You should check for DeprecationWarning in your code:: 
* New Features: New Features<9>. 
* Other Language Changes: Other Language Changes<5>. 
* New Modules: New Modules<5>. 
* Improved Modules: Improved Modules<5>. 
* Optimizations: Optimizations<8>. 
* Deprecated: Deprecated<10>. 
* Removed: Removed<10>. 
* Porting to Python 3.9: Porting to Python 3 9. 
* Build Changes: Build Changes<5>. 
* C API Changes: C API Changes<5>. 
* Notable changes in Python 3.9.1: Notable changes in Python 3 9 1. 
* Notable changes in Python 3.9.2: Notable changes in 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. 

New Features

* Dictionary Merge & Update Operators:: 
* New String Methods to Remove Prefixes and Suffixes:: 
* Type Hinting Generics in Standard Collections:: 
* New Parser:: 

New Modules

* zoneinfo:: 
* graphlib: graphlib<2>. 

Improved Modules

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

Porting to Python 3.9

* Changes in the Python API: Changes in the Python API<5>. 
* Changes in the C API: Changes in the C API<4>. 
* CPython bytecode changes: CPython bytecode changes<5>. 

C API Changes

* New Features: New Features<10>. 
* Porting to Python 3.9: Porting to Python 3 9<2>. 
* Removed: Removed<11>. 

Notable changes in Python 3.9.1

* typing: typing<10>. 
* macOS 11.0 (Big Sur) and Apple Silicon Mac support: macOS 11 0 Big Sur and Apple Silicon Mac support. 

Notable changes in Python 3.9.2

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

Notable changes in Python 3.9.5

* urllib.parse: urllib parse<4>. 

Notable changes in 3.9.17

* tarfile: tarfile<5>. 

What’s New In Python 3.8

* Summary – Release highlights: Summary – Release highlights<7>. 
* New Features: New Features<11>. 
* Other Language Changes: Other Language Changes<6>. 
* New Modules: New Modules<6>. 
* Improved Modules: Improved Modules<6>. 
* Optimizations: Optimizations<9>. 
* Build and C API Changes:: 
* Deprecated: Deprecated<11>. 
* 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. 

New Features

* Assignment expressions:: 
* 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:: 

Improved Modules

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

Porting to Python 3.8

* Changes in Python behavior:: 
* Changes in the Python API: Changes in the Python API<6>. 
* Changes in the C API: Changes in the C API<5>. 
* CPython bytecode changes: CPython bytecode changes<6>. 
* Demos and Tools: Demos and Tools<2>. 

Notable changes in Python 3.8.10

* macOS 11.0 (Big Sur) and Apple Silicon Mac support: macOS 11 0 Big Sur and Apple Silicon Mac support<2>. 

Notable changes in Python 3.8.10

* urllib.parse: urllib parse<5>. 

Notable changes in Python 3.8.12

* Changes in the Python API: Changes in the Python API<7>. 

Notable changes in 3.8.17

* tarfile: tarfile<7>. 

What’s New In Python 3.7

* Summary – Release Highlights: Summary – Release Highlights<2>. 
* New Features: New Features<12>. 
* Other Language Changes: Other Language Changes<7>. 
* New Modules: New Modules<7>. 
* Improved Modules: Improved Modules<7>. 
* C API Changes: C API Changes<6>. 
* Build Changes: Build Changes<6>. 
* Optimizations: Optimizations<10>. 
* Other CPython Implementation Changes: Other CPython Implementation Changes<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. 

New Features

* 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. 

New Modules

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

Improved Modules

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

Deprecated Python modules, functions and methods

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

Porting to Python 3.7

* Changes in Python Behavior:: 
* Changes in the Python API: Changes in the Python API<8>. 
* Changes in the C API: Changes in the C API<6>. 
* CPython bytecode changes: CPython bytecode changes<7>. 
* Windows-only Changes: Windows-only Changes<2>. 
* Other CPython implementation changes:: 

What’s New In Python 3.6

* Summary – Release highlights: Summary – Release highlights<8>. 
* New Features: New Features<13>. 
* Other Language Changes: Other Language Changes<8>. 
* New Modules: New Modules<8>. 
* Improved Modules: Improved Modules<8>. 
* Optimizations: Optimizations<11>. 
* Build and C API Changes: Build and C API Changes<2>. 
* Other Improvements:: 
* Deprecated: Deprecated<12>. 
* Removed: Removed<12>. 
* 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. 

New Features

* 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:: 

New Modules

* secrets:: 

Improved Modules

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

Deprecated

* New Keywords:: 
* Deprecated Python behavior:: 
* Deprecated Python modules@comma{} functions and methods: Deprecated Python modules functions and methods<2>. 
* xml: xml<7>. 
* 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<5>. 
* distutils: distutils<6>. 
* grp:: 
* importlib: importlib<7>. 
* os: os<11>. 
* re: re<8>. 
* ssl: ssl<10>. 
* tkinter: tkinter<9>. 
* venv: venv<7>. 

Removed

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

Porting to Python 3.6

* Changes in “python” Command Behavior:: 
* Changes in the Python API: Changes in the Python API<9>. 
* Changes in the C API: Changes in the C API<7>. 
* CPython bytecode changes: CPython bytecode changes<8>. 

Notable changes in Python 3.6.2

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

What’s New In Python 3.5

* Summary – Release highlights: Summary – Release highlights<9>. 
* New Features: New Features<14>. 
* Other Language Changes: Other Language Changes<9>. 
* New Modules: New Modules<9>. 
* Improved Modules: Improved Modules<9>. 
* Other module-level changes:: 
* Optimizations: Optimizations<12>. 
* Build and C API Changes: Build and C API Changes<3>. 
* Deprecated: Deprecated<13>. 
* Removed: Removed<13>. 
* Porting to Python 3.5: Porting to Python 3 5. 
* Notable changes in Python 3.5.4: Notable changes in Python 3 5 4. 

New Features

* 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 – a better and faster directory iterator: PEP 471 - os scandir function – 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; Elimination of PYO files: PEP 488 Elimination of PYO files. 
* PEP 489; Multi-phase extension module initialization: PEP 489 Multi-phase extension module initialization. 

New Modules

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

Improved Modules

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

ssl

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

Deprecated

* New Keywords: New Keywords<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>. 

Removed

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

Porting to Python 3.5

* Changes in Python behavior: Changes in Python behavior<2>. 
* Changes in the Python API: Changes in the Python API<10>. 
* Changes in the C API: Changes in the C API<8>. 

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>. 

What’s New In Python 3.4

* Summary – Release Highlights: Summary – Release Highlights<3>. 
* New Features: New Features<15>. 
* New Modules: New Modules<10>. 
* Improved Modules: Improved Modules<10>. 
* CPython Implementation Changes:: 
* Deprecated: Deprecated<14>. 
* Removed: Removed<14>. 
* Porting to Python 3.4: Porting to Python 3 4. 
* Changed in 3.4.3: Changed in 3 4 3. 

New Features

* 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. 
* Other Language Changes: Other Language Changes<10>. 

PEP 453: Explicit Bootstrapping of PIP in Python Installations

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

New Modules

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

Improved Modules

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

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:: 
* Other Improvements: Other Improvements<2>. 
* Significant Optimizations:: 

Deprecated

* Deprecations in the Python API:: 
* Deprecated Features:: 

Removed

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

Porting to Python 3.4

* Changes in “python” Command Behavior: Changes in “python” Command Behavior<2>. 
* Changes in the Python API: Changes in the Python API<11>. 
* Changes in the C API: Changes in the C API<9>. 

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. 

What’s New In Python 3.3

* Summary – Release highlights: Summary – Release highlights<10>. 
* 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:: 
* Other Language Changes: Other Language Changes<11>. 
* A Finer-Grained Import Lock:: 
* Builtin functions and types:: 
* New Modules: New Modules<11>. 
* Improved Modules: Improved Modules<11>. 
* Optimizations: Optimizations<13>. 
* Build and C API Changes: Build and C API Changes<4>. 
* Deprecated: Deprecated<15>. 
* Porting to Python 3.3: Porting to Python 3 3. 

PEP 3118: New memoryview implementation and buffer protocol documentation

* Features:: 
* 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:: 

New Modules

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

Improved Modules

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

decimal

* Features: Features<2>. 
* API changes: API changes<2>. 

email

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

Deprecated

* 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>. 
* Deprecated features:: 

Porting to Python 3.3

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

What’s New In 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. 
* Other Language Changes: Other Language Changes<12>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules. 
* Multi-threading:: 
* Optimizations: Optimizations<14>. 
* Unicode:: 
* Codecs:: 
* Documentation:: 
* IDLE:: 
* Code Repository:: 
* Build and C API Changes: Build and C API Changes<5>. 
* Porting to Python 3.2: Porting to Python 3 2. 

New, Improved, and Deprecated Modules

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

What’s New In 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. 
* Other Language Changes: Other Language Changes<13>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules<2>. 
* Optimizations: Optimizations<15>. 
* IDLE: IDLE<2>. 
* Build and C API Changes: Build and C API Changes<6>. 
* Porting to Python 3.1: Porting to Python 3 1. 

What’s New In 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>. 
* Performance:: 
* Porting To Python 3.0: Porting To 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:: 

What’s New in 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. 
* Other Language Changes: Other Language Changes<14>. 
* New and Improved Modules:: 
* Build and C API Changes: Build and C API Changes<8>. 
* Other Changes and Fixes:: 
* Porting to Python 2.7: Porting to Python 2 7. 
* New Features Added to Python 2.7 Maintenance Releases: New Features Added to Python 2 7 Maintenance Releases. 
* Acknowledgements:: 

Other Language Changes

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

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. 
* Updated module; ElementTree 1.3: Updated module 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>. 

What’s New in 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. 
* Other Language Changes: Other Language Changes<15>. 
* New and Improved Modules: New and Improved Modules<2>. 
* Deprecations and Removals:: 
* Build and C API Changes: Build and C API Changes<9>. 
* Porting to Python 2.6: Porting to Python 2 6. 
* Acknowledgements: Acknowledgements<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

* Writing Context Managers:: 
* The contextlib module:: 

PEP 3141: A Type Hierarchy for Numbers

* The fractions Module:: 

Other Language Changes

* Optimizations: Optimizations<17>. 
* 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. 

What’s New in Python 2.5

* PEP 308; Conditional Expressions: PEP 308 Conditional Expressions. 
* PEP 309; Partial Function Application: PEP 309 Partial Function Application. 
* 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. 
* Other Language Changes: Other Language Changes<16>. 
* New@comma{} Improved@comma{} and Removed Modules: New Improved and Removed Modules. 
* Build and C API Changes: Build and C API Changes<10>. 
* Porting to Python 2.5: Porting to Python 2 5. 
* Acknowledgements: Acknowledgements<3>. 

PEP 343: The “with” statement

* Writing Context Managers: Writing Context Managers<2>. 
* The contextlib module: The contextlib module<2>. 

Other Language Changes

* Interactive Interpreter Changes:: 
* Optimizations: Optimizations<18>. 

New, Improved, and Removed Modules

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

Build and C API Changes

* Port-Specific Changes:: 

What’s New in 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. 
* Other Language Changes: Other Language Changes<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>. 
* Porting to Python 2.4: Porting to Python 2 4. 
* Acknowledgements: Acknowledgements<4>. 

PEP 327: Decimal Data Type

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

Other Language Changes

* Optimizations: Optimizations<19>. 

New, Improved, and Deprecated Modules

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

Build and C API Changes

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

What’s New in Python 2.3

* PEP 218; A Standard Set Datatype: PEP 218 A Standard Set Datatype. 
* PEP 255; Simple Generators: PEP 255 Simple Generators. 
* 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; A Boolean Type: PEP 285 A Boolean Type. 
* 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:: 
* Other Language Changes: Other Language Changes<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>. 
* Other Changes and Fixes: Other Changes and Fixes<2>. 
* Porting to Python 2.3: Porting to Python 2 3. 
* Acknowledgements: Acknowledgements<5>. 

Other Language Changes

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

New, Improved, and Deprecated Modules

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

Build and C API Changes

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

What’s New in Python 2.2

* Introduction:: 
* PEPs 252 and 253; Type and Class Changes: PEPs 252 and 253 Type and Class Changes. 
* PEP 234; Iterators: PEP 234 Iterators. 
* PEP 255; Simple Generators: PEP 255 Simple Generators<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:: 
* Other Changes and Fixes: Other Changes and Fixes<3>. 
* Acknowledgements: Acknowledgements<6>. 

PEPs 252 and 253: Type and Class Changes

* Old and New Classes:: 
* Descriptors:: 
* Multiple Inheritance; The Diamond Rule: Multiple Inheritance The Diamond Rule. 
* Attribute Access:: 
* Related Links:: 

What’s New in Python 2.1

* Introduction: Introduction<2>. 
* PEP 227; Nested Scopes: PEP 227 Nested Scopes<2>. 
* PEP 236; __future__ Directives: PEP 236 __future__ Directives. 
* 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; Function Attributes: PEP 232 Function Attributes. 
* 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>. 
* Other Changes and Fixes: Other Changes and Fixes<4>. 
* Acknowledgements: Acknowledgements<7>. 

What’s New in Python 2.0

* Introduction: Introduction<3>. 
* What About Python 1.6?: What About Python 1 6?. 
* New Development Process:: 
* Unicode: Unicode<2>. 
* List Comprehensions:: 
* Augmented Assignment:: 
* String Methods:: 
* 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. 
* XML Modules:: 
* Module changes:: 
* New modules: New modules<4>. 
* IDLE Improvements:: 
* Deleted and Deprecated Modules:: 
* Acknowledgements: Acknowledgements<8>. 

Other Core Changes

* Minor Language Changes:: 
* Changes to Built-in Functions:: 

XML Modules

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

Changelog

* Python next:: 
* Python 3.15.0 beta 1: Python 3 15 0 beta 1. 
* Python 3.15.0 alpha 8: Python 3 15 0 alpha 8. 
* Python 3.15.0 alpha 7: Python 3 15 0 alpha 7. 
* Python 3.15.0 alpha 6: Python 3 15 0 alpha 6. 
* Python 3.15.0 alpha 5: Python 3 15 0 alpha 5. 
* Python 3.15.0 alpha 4: Python 3 15 0 alpha 4. 
* Python 3.15.0 alpha 3: Python 3 15 0 alpha 3. 
* Python 3.15.0 alpha 2: Python 3 15 0 alpha 2. 
* Python 3.15.0 alpha 1: Python 3 15 0 alpha 1. 
* Python 3.14.0 beta 1: Python 3 14 0 beta 1. 
* Python 3.14.0 alpha 7: Python 3 14 0 alpha 7. 
* Python 3.14.0 alpha 6: Python 3 14 0 alpha 6. 
* Python 3.14.0 alpha 5: Python 3 14 0 alpha 5. 
* Python 3.14.0 alpha 4: Python 3 14 0 alpha 4. 
* Python 3.14.0 alpha 3: Python 3 14 0 alpha 3. 
* Python 3.14.0 alpha 2: Python 3 14 0 alpha 2. 
* Python 3.14.0 alpha 1: Python 3 14 0 alpha 1. 
* 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

* Security:: 
* Library:: 
* Core and Builtins:: 

Python 3.15.0 beta 1

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

Python 3.15.0 alpha 8

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

Python 3.15.0 alpha 7

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

Python 3.15.0 alpha 6

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

Python 3.15.0 alpha 5

* Windows: Windows<5>. 
* Tools/Demos: Tools/Demos<2>. 
* Tests: Tests<5>. 
* Library: Library<6>. 
* Documentation: Documentation<5>. 
* Core and Builtins: Core and Builtins<6>. 
* C API: C API<5>. 

Python 3.15.0 alpha 4

* Tests: Tests<6>. 
* Library: Library<7>. 
* Core and Builtins: Core and Builtins<7>. 

Python 3.15.0 alpha 3

* Tools/Demos: Tools/Demos<3>. 
* Tests: Tests<7>. 
* Security: Security<6>. 
* Library: Library<8>. 
* Documentation: Documentation<6>. 
* Core and Builtins: Core and Builtins<8>. 
* C API: C API<6>. 
* Build: Build<5>. 

Python 3.15.0 alpha 2

* Windows: Windows<6>. 
* Tools/Demos: Tools/Demos<4>. 
* Tests: Tests<8>. 
* Security: Security<7>. 
* Library: Library<9>. 
* Core and Builtins: Core and Builtins<9>. 
* Library: Library<10>. 
* Core and Builtins: Core and Builtins<10>. 
* Library: Library<11>. 
* Core and Builtins: Core and Builtins<11>. 
* Library: Library<12>. 
* Core and Builtins: Core and Builtins<12>. 
* Library: Library<13>. 
* Core and Builtins: Core and Builtins<13>. 
* Library: Library<14>. 
* Core and Builtins: Core and Builtins<14>. 
* C API: C API<7>. 
* Build: Build<6>. 

Python 3.15.0 alpha 1

* macOS: macOS<4>. 
* Windows: Windows<7>. 
* Tools/Demos: Tools/Demos<5>. 
* Tests: Tests<9>. 
* Security: Security<8>. 
* Library: Library<15>. 
* IDLE: IDLE<5>. 
* Documentation: Documentation<7>. 
* Core and Builtins: Core and Builtins<15>. 
* Library: Library<16>. 
* Core and Builtins: Core and Builtins<16>. 
* Library: Library<17>. 
* Core and Builtins: Core and Builtins<17>. 
* Library: Library<18>. 
* Core and Builtins: Core and Builtins<18>. 
* Library: Library<19>. 
* Core and Builtins: Core and Builtins<19>. 
* Library: Library<20>. 
* Core and Builtins: Core and Builtins<20>. 
* Library: Library<21>. 
* Core and Builtins: Core and Builtins<21>. 
* Library: Library<22>. 
* Core and Builtins: Core and Builtins<22>. 
* Library: Library<23>. 
* Core and Builtins: Core and Builtins<23>. 
* Library: Library<24>. 
* Core and Builtins: Core and Builtins<24>. 
* Library: Library<25>. 
* Core and Builtins: Core and Builtins<25>. 
* Library: Library<26>. 
* Core and Builtins: Core and Builtins<26>. 
* Library: Library<27>. 
* Core and Builtins: Core and Builtins<27>. 
* Library: Library<28>. 
* Core and Builtins: Core and Builtins<28>. 
* C API: C API<8>. 
* Build: Build<7>. 

Python 3.14.0 beta 1

* Windows: Windows<8>. 
* Tools/Demos: Tools/Demos<6>. 
* Tests: Tests<10>. 
* Security: Security<9>. 
* Library: Library<29>. 
* IDLE: IDLE<6>. 
* Documentation: Documentation<8>. 
* Core and Builtins: Core and Builtins<29>. 
* Library: Library<30>. 
* Core and Builtins: Core and Builtins<30>. 
* Library: Library<31>. 
* Core and Builtins: Core and Builtins<31>. 
* Library: Library<32>. 
* C API: C API<9>. 
* Build: Build<8>. 

Python 3.14.0 alpha 7

* macOS: macOS<5>. 
* Windows: Windows<9>. 
* Tools/Demos: Tools/Demos<7>. 
* Tests: Tests<11>. 
* Security: Security<10>. 
* Library: Library<33>. 
* Documentation: Documentation<9>. 
* Core and Builtins: Core and Builtins<32>. 
* Library: Library<34>. 
* Core and Builtins: Core and Builtins<33>. 
* C API: C API<10>. 
* Build: Build<9>. 

Python 3.14.0 alpha 6

* macOS: macOS<6>. 
* Windows: Windows<10>. 
* Tools/Demos: Tools/Demos<8>. 
* Tests: Tests<12>. 
* Security: Security<11>. 
* Library: Library<35>. 
* Documentation: Documentation<10>. 
* Core and Builtins: Core and Builtins<34>. 
* Library: Library<36>. 
* Core and Builtins: Core and Builtins<35>. 
* Library: Library<37>. 
* Core and Builtins: Core and Builtins<36>. 
* C API: C API<11>. 
* Build: Build<10>. 

Python 3.14.0 alpha 5

* macOS: macOS<7>. 
* Tools/Demos: Tools/Demos<9>. 
* Tests: Tests<13>. 
* Security: Security<12>. 
* Library: Library<38>. 
* IDLE: IDLE<7>. 
* Documentation: Documentation<11>. 
* Core and Builtins: Core and Builtins<37>. 
* Library: Library<39>. 
* Core and Builtins: Core and Builtins<38>. 
* Library: Library<40>. 
* Core and Builtins: Core and Builtins<39>. 
* Library: Library<41>. 
* C API: C API<12>. 
* Build: Build<11>. 

Python 3.14.0 alpha 4

* macOS: macOS<8>. 
* Tools/Demos: Tools/Demos<10>. 
* Tests: Tests<14>. 
* Library: Library<42>. 
* Core and Builtins: Core and Builtins<40>. 
* Library: Library<43>. 
* Core and Builtins: Core and Builtins<41>. 
* Library: Library<44>. 
* Core and Builtins: Core and Builtins<42>. 
* C API: C API<13>. 
* Build: Build<12>. 

Python 3.14.0 alpha 3

* Windows: Windows<11>. 
* Tools/Demos: Tools/Demos<11>. 
* Tests: Tests<15>. 
* Security: Security<13>. 
* Library: Library<45>. 
* Documentation: Documentation<12>. 
* Core and Builtins: Core and Builtins<43>. 
* Library: Library<46>. 
* Core and Builtins: Core and Builtins<44>. 
* C API: C API<14>. 
* Build: Build<13>. 

Python 3.14.0 alpha 2

* Windows: Windows<12>. 
* Tools/Demos: Tools/Demos<12>. 
* Tests: Tests<16>. 
* Security: Security<14>. 
* Library: Library<47>. 
* Documentation: Documentation<13>. 
* Core and Builtins: Core and Builtins<45>. 
* Library: Library<48>. 
* Core and Builtins: Core and Builtins<46>. 
* Library: Library<49>. 
* Core and Builtins: Core and Builtins<47>. 
* Library: Library<50>. 
* C API: C API<15>. 
* Build: Build<14>. 

Python 3.14.0 alpha 1

* macOS: macOS<9>. 
* Windows: Windows<13>. 
* Tools/Demos: Tools/Demos<13>. 
* Tests: Tests<17>. 
* Security: Security<15>. 
* Library: Library<51>. 
* IDLE: IDLE<8>. 
* Documentation: Documentation<14>. 
* Core and Builtins: Core and Builtins<48>. 
* Library: Library<52>. 
* Core and Builtins: Core and Builtins<49>. 
* Library: Library<53>. 
* Core and Builtins: Core and Builtins<50>. 
* Library: Library<54>. 
* Core and Builtins: Core and Builtins<51>. 
* Library: Library<55>. 
* Core and Builtins: Core and Builtins<52>. 
* Library: Library<56>. 
* Core and Builtins: Core and Builtins<53>. 
* Library: Library<57>. 
* Core and Builtins: Core and Builtins<54>. 
* Library: Library<58>. 
* Core and Builtins: Core and Builtins<55>. 
* C API: C API<16>. 
* Build: Build<15>. 

Python 3.13.0 beta 1

* Security: Security<16>. 
* Core and Builtins: Core and Builtins<56>. 
* Library: Library<59>. 
* Core and Builtins: Core and Builtins<57>. 
* Library: Library<60>. 
* Documentation: Documentation<15>. 
* Build: Build<16>. 
* Windows: Windows<14>. 
* macOS: macOS<10>. 
* IDLE: IDLE<9>. 
* C API: C API<17>. 

Python 3.13.0 alpha 6

* Core and Builtins: Core and Builtins<58>. 
* Library: Library<61>. 
* Core and Builtins: Core and Builtins<59>. 
* Library: Library<62>. 
* Documentation: Documentation<16>. 
* Tests: Tests<18>. 
* Build: Build<17>. 
* Windows: Windows<15>. 
* C API: C API<18>. 

Python 3.13.0 alpha 5

* Security: Security<17>. 
* Core and Builtins: Core and Builtins<60>. 
* Library: Library<63>. 
* Core and Builtins: Core and Builtins<61>. 
* Library: Library<64>. 
* Core and Builtins: Core and Builtins<62>. 
* Library: Library<65>. 
* Documentation: Documentation<17>. 
* Tests: Tests<19>. 
* Build: Build<18>. 
* Windows: Windows<16>. 
* macOS: macOS<11>. 
* IDLE: IDLE<10>. 
* Tools/Demos: Tools/Demos<14>. 
* C API: C API<19>. 

Python 3.13.0 alpha 4

* Security: Security<18>. 
* Core and Builtins: Core and Builtins<63>. 
* Library: Library<66>. 
* Documentation: Documentation<18>. 
* Tests: Tests<20>. 
* Build: Build<19>. 
* Windows: Windows<17>. 
* macOS: macOS<12>. 
* IDLE: IDLE<11>. 
* Tools/Demos: Tools/Demos<15>. 
* C API: C API<20>. 

Python 3.13.0 alpha 3

* Security: Security<19>. 
* Core and Builtins: Core and Builtins<64>. 
* Library: Library<67>. 
* Documentation: Documentation<19>. 
* Tests: Tests<21>. 
* Build: Build<20>. 
* Windows: Windows<18>. 
* macOS: macOS<13>. 
* IDLE: IDLE<12>. 
* C API: C API<21>. 

Python 3.13.0 alpha 2

* Core and Builtins: Core and Builtins<65>. 
* Library: Library<68>. 
* Tests: Tests<22>. 
* Build: Build<21>. 
* Windows: Windows<19>. 
* macOS: macOS<14>. 
* IDLE: IDLE<13>. 
* Tools/Demos: Tools/Demos<16>. 
* C API: C API<22>. 

Python 3.13.0 alpha 1

* Security: Security<20>. 
* Core and Builtins: Core and Builtins<66>. 
* Library: Library<69>. 
* Documentation: Documentation<20>. 
* Tests: Tests<23>. 
* Build: Build<22>. 
* Windows: Windows<20>. 
* macOS: macOS<15>. 
* IDLE: IDLE<14>. 
* Tools/Demos: Tools/Demos<17>. 
* C API: C API<23>. 

Python 3.12.0 beta 1

* Security: Security<21>. 
* Library: Library<70>. 
* Core and Builtins: Core and Builtins<67>. 
* Library: Library<71>. 
* Core and Builtins: Core and Builtins<68>. 
* Library: Library<72>. 
* Documentation: Documentation<21>. 
* Tests: Tests<24>. 
* Build: Build<23>. 
* Windows: Windows<21>. 
* macOS: macOS<16>. 
* IDLE: IDLE<15>. 
* Tools/Demos: Tools/Demos<18>. 
* C API: C API<24>. 

Python 3.12.0 alpha 7

* Core and Builtins: Core and Builtins<69>. 
* Library: Library<73>. 
* Core and Builtins: Core and Builtins<70>. 
* Build: Build<24>. 
* Core and Builtins: Core and Builtins<71>. 
* Library: Library<74>. 
* Documentation: Documentation<22>. 
* Tests: Tests<25>. 
* Build: Build<25>. 
* Windows: Windows<22>. 
* Tools/Demos: Tools/Demos<19>. 
* C API: C API<25>. 

Python 3.12.0 alpha 6

* Security: Security<22>. 
* Core and Builtins: Core and Builtins<72>. 
* Library: Library<75>. 
* Documentation: Documentation<23>. 
* Tests: Tests<26>. 
* Build: Build<26>. 
* Windows: Windows<23>. 
* macOS: macOS<17>. 
* C API: C API<26>. 

Python 3.12.0 alpha 5

* Security: Security<23>. 
* Core and Builtins: Core and Builtins<73>. 
* Library: Library<76>. 
* Documentation: Documentation<24>. 
* Tests: Tests<27>. 
* Build: Build<27>. 
* Windows: Windows<24>. 

Python 3.12.0 alpha 4

* Core and Builtins: Core and Builtins<74>. 
* Library: Library<77>. 
* Core and Builtins: Core and Builtins<75>. 
* Library: Library<78>. 
* Core and Builtins: Core and Builtins<76>. 
* Library: Library<79>. 
* Documentation: Documentation<25>. 
* Tests: Tests<28>. 
* Build: Build<28>. 
* Windows: Windows<25>. 
* macOS: macOS<18>. 
* Tools/Demos: Tools/Demos<20>. 
* C API: C API<27>. 

Python 3.12.0 alpha 3

* Security: Security<24>. 
* Core and Builtins: Core and Builtins<77>. 
* Library: Library<80>. 
* Core and Builtins: Core and Builtins<78>. 
* Library: Library<81>. 
* Documentation: Documentation<26>. 
* Tests: Tests<29>. 
* Build: Build<29>. 
* Windows: Windows<26>. 
* macOS: macOS<19>. 
* Tools/Demos: Tools/Demos<21>. 
* C API: C API<28>. 

Python 3.12.0 alpha 2

* Security: Security<25>. 
* Core and Builtins: Core and Builtins<79>. 
* Build: Build<30>. 
* Core and Builtins: Core and Builtins<80>. 
* Library: Library<82>. 
* Documentation: Documentation<27>. 
* Tests: Tests<30>. 
* Build: Build<31>. 
* Windows: Windows<27>. 
* macOS: macOS<20>. 
* C API: C API<29>. 

Python 3.12.0 alpha 1

* Security: Security<26>. 
* Core and Builtins: Core and Builtins<81>. 
* Library: Library<83>. 
* Core and Builtins: Core and Builtins<82>. 
* Library: Library<84>. 
* Core and Builtins: Core and Builtins<83>. 
* Library: Library<85>. 
* Core and Builtins: Core and Builtins<84>. 
* Library: Library<86>. 
* Core and Builtins: Core and Builtins<85>. 
* Library: Library<87>. 
* Core and Builtins: Core and Builtins<86>. 
* Library: Library<88>. 
* Core and Builtins: Core and Builtins<87>. 
* Library: Library<89>. 
* Core and Builtins: Core and Builtins<88>. 
* Library: Library<90>. 
* Core and Builtins: Core and Builtins<89>. 
* Library: Library<91>. 
* Core and Builtins: Core and Builtins<90>. 
* Library: Library<92>. 
* Documentation: Documentation<28>. 
* Tests: Tests<31>. 
* Build: Build<32>. 
* Windows: Windows<28>. 
* macOS: macOS<21>. 
* IDLE: IDLE<16>. 
* Tools/Demos: Tools/Demos<22>. 
* C API: C API<30>. 

Python 3.11.0 beta 1

* Security: Security<27>. 
* Core and Builtins: Core and Builtins<91>. 
* Library: Library<93>. 
* Core and Builtins: Core and Builtins<92>. 
* Build: Build<33>. 
* Core and Builtins: Core and Builtins<93>. 
* Library: Library<94>. 
* Documentation: Documentation<29>. 
* Tests: Tests<32>. 
* Build: Build<34>. 
* Windows: Windows<29>. 
* macOS: macOS<22>. 
* Tools/Demos: Tools/Demos<23>. 
* C API: C API<31>. 

Python 3.11.0 alpha 7

* Core and Builtins: Core and Builtins<94>. 
* Library: Library<95>. 
* Core and Builtins: Core and Builtins<95>. 
* Library: Library<96>. 
* Core and Builtins: Core and Builtins<96>. 
* Library: Library<97>. 
* Documentation: Documentation<30>. 
* Tests: Tests<33>. 
* Build: Build<35>. 
* Windows: Windows<30>. 
* macOS: macOS<23>. 
* Tools/Demos: Tools/Demos<24>. 
* C API: C API<32>. 

Python 3.11.0 alpha 6

* Core and Builtins: Core and Builtins<97>. 
* Library: Library<98>. 
* Core and Builtins: Core and Builtins<98>. 
* Library: Library<99>. 
* Core and Builtins: Core and Builtins<99>. 
* Library: Library<100>. 
* Core and Builtins: Core and Builtins<100>. 
* Library: Library<101>. 
* Documentation: Documentation<31>. 
* Tests: Tests<34>. 
* Build: Build<36>. 
* Windows: Windows<31>. 
* IDLE: IDLE<17>. 
* C API: C API<33>. 

Python 3.11.0 alpha 5

* Core and Builtins: Core and Builtins<101>. 
* Library: Library<102>. 
* Core and Builtins: Core and Builtins<102>. 
* Library: Library<103>. 
* Build: Build<37>. 
* Core and Builtins: Core and Builtins<103>. 
* Library: Library<104>. 
* Documentation: Documentation<32>. 
* Tests: Tests<35>. 
* Build: Build<38>. 
* Windows: Windows<32>. 
* macOS: macOS<24>. 
* IDLE: IDLE<18>. 
* C API: C API<34>. 

Python 3.11.0 alpha 4

* Core and Builtins: Core and Builtins<104>. 
* Library: Library<105>. 
* Core and Builtins: Core and Builtins<105>. 
* Library: Library<106>. 
* Core and Builtins: Core and Builtins<106>. 
* Library: Library<107>. 
* Core and Builtins: Core and Builtins<107>. 
* Library: Library<108>. 
* Documentation: Documentation<33>. 
* Tests: Tests<36>. 
* Build: Build<39>. 
* Windows: Windows<33>. 
* macOS: macOS<25>. 
* C API: C API<35>. 

Python 3.11.0 alpha 3

* Core and Builtins: Core and Builtins<108>. 
* Library: Library<109>. 
* Core and Builtins: Core and Builtins<109>. 
* Library: Library<110>. 
* Documentation: Documentation<34>. 
* Tests: Tests<37>. 
* Build: Build<40>. 
* Windows: Windows<34>. 
* macOS: macOS<26>. 
* C API: C API<36>. 

Python 3.11.0 alpha 2

* Core and Builtins: Core and Builtins<110>. 
* Library: Library<111>. 
* Documentation: Documentation<35>. 
* Tests: Tests<38>. 
* Build: Build<41>. 
* Windows: Windows<35>. 
* macOS: macOS<27>. 
* IDLE: IDLE<19>. 
* C API: C API<37>. 

Python 3.11.0 alpha 1

* Security: Security<28>. 
* Core and Builtins: Core and Builtins<111>. 
* Library: Library<112>. 
* Core and Builtins: Core and Builtins<112>. 
* Library: Library<113>. 
* Core and Builtins: Core and Builtins<113>. 
* Library: Library<114>. 
* Core and Builtins: Core and Builtins<114>. 
* Library: Library<115>. 
* Core and Builtins: Core and Builtins<115>. 
* Library: Library<116>. 
* Core and Builtins: Core and Builtins<116>. 
* Library: Library<117>. 
* Core and Builtins: Core and Builtins<117>. 
* Library: Library<118>. 
* Core and Builtins: Core and Builtins<118>. 
* Library: Library<119>. 
* Core and Builtins: Core and Builtins<119>. 
* Library: Library<120>. 
* Core and Builtins: Core and Builtins<120>. 
* Library: Library<121>. 
* Documentation: Documentation<36>. 
* Tests: Tests<39>. 
* Build: Build<42>. 
* Windows: Windows<36>. 
* macOS: macOS<28>. 
* IDLE: IDLE<20>. 
* Tools/Demos: Tools/Demos<25>. 
* C API: C API<38>. 

Python 3.10.0 beta 1

* Security: Security<29>. 
* Core and Builtins: Core and Builtins<121>. 
* Library: Library<122>. 
* Core and Builtins: Core and Builtins<122>. 
* Library: Library<123>. 
* Core and Builtins: Core and Builtins<123>. 
* Library: Library<124>. 
* Documentation: Documentation<37>. 
* Tests: Tests<40>. 
* Build: Build<43>. 
* Windows: Windows<37>. 
* macOS: macOS<29>. 
* IDLE: IDLE<21>. 
* C API: C API<39>. 

Python 3.10.0 alpha 7

* Security: Security<30>. 
* Core and Builtins: Core and Builtins<124>. 
* Library: Library<125>. 
* Core and Builtins: Core and Builtins<125>. 
* Library: Library<126>. 
* Documentation: Documentation<38>. 
* Tests: Tests<41>. 
* Build: Build<44>. 
* Windows: Windows<38>. 
* IDLE: IDLE<22>. 
* C API: C API<40>. 

Python 3.10.0 alpha 6

* Security: Security<31>. 
* Core and Builtins: Core and Builtins<126>. 
* Library: Library<127>. 
* Core and Builtins: Core and Builtins<127>. 
* Library: Library<128>. 
* Core and Builtins: Core and Builtins<128>. 
* Library: Library<129>. 
* Documentation: Documentation<39>. 
* Tests: Tests<42>. 
* Build: Build<45>. 
* Windows: Windows<39>. 
* macOS: macOS<30>. 
* IDLE: IDLE<23>. 
* C API: C API<41>. 

Python 3.10.0 alpha 5

* Security: Security<32>. 
* Core and Builtins: Core and Builtins<129>. 
* Library: Library<130>. 
* Core and Builtins: Core and Builtins<130>. 
* Library: Library<131>. 
* Documentation: Documentation<40>. 
* Tests: Tests<43>. 
* Build: Build<46>. 
* Windows: Windows<40>. 
* macOS: macOS<31>. 
* IDLE: IDLE<24>. 
* C API: C API<42>. 

Python 3.10.0 alpha 4

* Core and Builtins: Core and Builtins<131>. 
* Library: Library<132>. 
* Core and Builtins: Core and Builtins<132>. 
* Library: Library<133>. 
* Core and Builtins: Core and Builtins<133>. 
* Library: Library<134>. 
* Documentation: Documentation<41>. 
* Tests: Tests<44>. 
* Build: Build<47>. 
* macOS: macOS<32>. 
* Tools/Demos: Tools/Demos<26>. 
* C API: C API<43>. 

Python 3.10.0 alpha 3

* Security: Security<33>. 
* Core and Builtins: Core and Builtins<134>. 
* Library: Library<135>. 
* Core and Builtins: Core and Builtins<135>. 
* Library: Library<136>. 
* Core and Builtins: Core and Builtins<136>. 
* Library: Library<137>. 
* Core and Builtins: Core and Builtins<137>. 
* Library: Library<138>. 
* Documentation: Documentation<42>. 
* Tests: Tests<45>. 
* Build: Build<48>. 
* Windows: Windows<41>. 
* macOS: macOS<33>. 
* IDLE: IDLE<25>. 
* Tools/Demos: Tools/Demos<27>. 
* C API: C API<44>. 

Python 3.10.0 alpha 2

* Security: Security<34>. 
* Core and Builtins: Core and Builtins<138>. 
* Library: Library<139>. 
* Core and Builtins: Core and Builtins<139>. 
* Library: Library<140>. 
* Documentation: Documentation<43>. 
* Tests: Tests<46>. 
* Build: Build<49>. 
* Windows: Windows<42>. 
* macOS: macOS<34>. 
* IDLE: IDLE<26>. 
* C API: C API<45>. 

Python 3.10.0 alpha 1

* Security: Security<35>. 
* Core and Builtins: Core and Builtins<140>. 
* Library: Library<141>. 
* Core and Builtins: Core and Builtins<141>. 
* Library: Library<142>. 
* Core and Builtins: Core and Builtins<142>. 
* Library: Library<143>. 
* Core and Builtins: Core and Builtins<143>. 
* Library: Library<144>. 
* Core and Builtins: Core and Builtins<144>. 
* Library: Library<145>. 
* Core and Builtins: Core and Builtins<145>. 
* Library: Library<146>. 
* Core and Builtins: Core and Builtins<146>. 
* Library: Library<147>. 
* Core and Builtins: Core and Builtins<147>. 
* Library: Library<148>. 
* Core and Builtins: Core and Builtins<148>. 
* Library: Library<149>. 
* Core and Builtins: Core and Builtins<149>. 
* Library: Library<150>. 
* Core and Builtins: Core and Builtins<150>. 
* Library: Library<151>. 
* Core and Builtins: Core and Builtins<151>. 
* Library: Library<152>. 
* Core and Builtins: Core and Builtins<152>. 
* Library: Library<153>. 
* Core and Builtins: Core and Builtins<153>. 
* Library: Library<154>. 
* Core and Builtins: Core and Builtins<154>. 
* Library: Library<155>. 
* Documentation: Documentation<44>. 
* Tests: Tests<47>. 
* Build: Build<50>. 
* Windows: Windows<43>. 
* macOS: macOS<35>. 
* IDLE: IDLE<27>. 
* C API: C API<46>. 

Python 3.9.0 beta 1

* Security: Security<36>. 
* Core and Builtins: Core and Builtins<155>. 
* Library: Library<156>. 
* Documentation: Documentation<45>. 
* Tests: Tests<48>. 
* Build: Build<51>. 
* Windows: Windows<44>. 
* macOS: macOS<36>. 
* Tools/Demos: Tools/Demos<28>. 
* C API: C API<47>. 

Python 3.9.0 alpha 6

* Security: Security<37>. 
* Core and Builtins: Core and Builtins<156>. 
* Library: Library<157>. 
* Documentation: Documentation<46>. 
* Tests: Tests<49>. 
* Build: Build<52>. 
* Windows: Windows<45>. 
* macOS: macOS<37>. 
* IDLE: IDLE<28>. 
* Tools/Demos: Tools/Demos<29>. 
* C API: C API<48>. 

Python 3.9.0 alpha 5

* Security: Security<38>. 
* Core and Builtins: Core and Builtins<157>. 
* Library: Library<158>. 
* Documentation: Documentation<47>. 
* Tests: Tests<50>. 
* Build: Build<53>. 
* Windows: Windows<46>. 
* macOS: macOS<38>. 
* IDLE: IDLE<29>. 
* Tools/Demos: Tools/Demos<30>. 
* C API: C API<49>. 

Python 3.9.0 alpha 4

* Security: Security<39>. 
* Core and Builtins: Core and Builtins<158>. 
* Library: Library<159>. 
* Documentation: Documentation<48>. 
* Tests: Tests<51>. 
* Build: Build<54>. 
* Windows: Windows<47>. 
* IDLE: IDLE<30>. 
* C API: C API<50>. 

Python 3.9.0 alpha 3

* Core and Builtins: Core and Builtins<159>. 
* Library: Library<160>. 
* Documentation: Documentation<49>. 
* Build: Build<55>. 
* IDLE: IDLE<31>. 
* C API: C API<51>. 

Python 3.9.0 alpha 2

* Security: Security<40>. 
* Core and Builtins: Core and Builtins<160>. 
* Library: Library<161>. 
* Documentation: Documentation<50>. 
* Tests: Tests<52>. 
* Build: Build<56>. 
* Windows: Windows<48>. 
* macOS: macOS<39>. 
* IDLE: IDLE<32>. 
* C API: C API<52>. 

Python 3.9.0 alpha 1

* Security: Security<41>. 
* Core and Builtins: Core and Builtins<161>. 
* Library: Library<162>. 
* Documentation: Documentation<51>. 
* Tests: Tests<53>. 
* Build: Build<57>. 
* Windows: Windows<49>. 
* macOS: macOS<40>. 
* IDLE: IDLE<33>. 
* Tools/Demos: Tools/Demos<31>. 
* C API: C API<53>. 

Python 3.8.0 beta 1

* Security: Security<42>. 
* Core and Builtins: Core and Builtins<162>. 
* Library: Library<163>. 
* Documentation: Documentation<52>. 
* Tests: Tests<54>. 
* Build: Build<58>. 
* Windows: Windows<50>. 
* macOS: macOS<41>. 
* IDLE: IDLE<34>. 
* Tools/Demos: Tools/Demos<32>. 
* C API: C API<54>. 

Python 3.8.0 alpha 4

* Security: Security<43>. 
* Core and Builtins: Core and Builtins<163>. 
* Library: Library<164>. 
* Documentation: Documentation<53>. 
* Tests: Tests<55>. 
* Build: Build<59>. 
* Windows: Windows<51>. 
* macOS: macOS<42>. 
* IDLE: IDLE<35>. 
* Tools/Demos: Tools/Demos<33>. 
* C API: C API<55>. 

Python 3.8.0 alpha 3

* Security: Security<44>. 
* Core and Builtins: Core and Builtins<164>. 
* Library: Library<165>. 
* Documentation: Documentation<54>. 
* Tests: Tests<56>. 
* Build: Build<60>. 
* Windows: Windows<52>. 
* IDLE: IDLE<36>. 
* Tools/Demos: Tools/Demos<34>. 
* C API: C API<56>. 

Python 3.8.0 alpha 2

* Core and Builtins: Core and Builtins<165>. 
* Library: Library<166>. 
* Documentation: Documentation<55>. 
* Tests: Tests<57>. 
* Windows: Windows<53>. 
* IDLE: IDLE<37>. 

Python 3.8.0 alpha 1

* Security: Security<45>. 
* Core and Builtins: Core and Builtins<166>. 
* Library: Library<167>. 
* Documentation: Documentation<56>. 
* Tests: Tests<58>. 
* Build: Build<61>. 
* Windows: Windows<54>. 
* macOS: macOS<43>. 
* IDLE: IDLE<38>. 
* Tools/Demos: Tools/Demos<35>. 
* C API: C API<57>. 

Python 3.7.0 final

* Library: Library<168>. 
* C API: C API<58>. 

Python 3.7.0 release candidate 1

* Core and Builtins: Core and Builtins<167>. 
* Library: Library<169>. 
* Documentation: Documentation<57>. 
* Build: Build<62>. 
* Windows: Windows<55>. 
* IDLE: IDLE<39>. 

Python 3.7.0 beta 5

* Core and Builtins: Core and Builtins<168>. 
* Library: Library<170>. 
* Documentation: Documentation<58>. 
* Tests: Tests<59>. 
* Build: Build<63>. 
* macOS: macOS<44>. 
* IDLE: IDLE<40>. 

Python 3.7.0 beta 4

* Core and Builtins: Core and Builtins<169>. 
* Library: Library<171>. 
* Documentation: Documentation<59>. 
* Tests: Tests<60>. 
* Build: Build<64>. 
* Windows: Windows<56>. 
* macOS: macOS<45>. 
* IDLE: IDLE<41>. 
* Tools/Demos: Tools/Demos<36>. 

Python 3.7.0 beta 3

* Security: Security<46>. 
* Core and Builtins: Core and Builtins<170>. 
* Library: Library<172>. 
* Documentation: Documentation<60>. 
* Tests: Tests<61>. 
* Build: Build<65>. 
* Windows: Windows<57>. 
* macOS: macOS<46>. 
* IDLE: IDLE<42>. 
* Tools/Demos: Tools/Demos<37>. 
* C API: C API<59>. 

Python 3.7.0 beta 2

* Security: Security<47>. 
* Core and Builtins: Core and Builtins<171>. 
* Library: Library<173>. 
* Documentation: Documentation<61>. 
* Tests: Tests<62>. 
* Build: Build<66>. 
* Windows: Windows<58>. 
* macOS: macOS<47>. 
* IDLE: IDLE<43>. 
* Tools/Demos: Tools/Demos<38>. 

Python 3.7.0 beta 1

* Core and Builtins: Core and Builtins<172>. 
* Library: Library<174>. 
* Documentation: Documentation<62>. 
* Tests: Tests<63>. 
* Build: Build<67>. 
* Windows: Windows<59>. 
* macOS: macOS<48>. 
* C API: C API<60>. 

Python 3.7.0 alpha 4

* Core and Builtins: Core and Builtins<173>. 
* Library: Library<175>. 
* Documentation: Documentation<63>. 
* Tests: Tests<64>. 
* Windows: Windows<60>. 
* Tools/Demos: Tools/Demos<39>. 
* C API: C API<61>. 

Python 3.7.0 alpha 3

* Core and Builtins: Core and Builtins<174>. 
* Library: Library<176>. 
* Documentation: Documentation<64>. 
* Tests: Tests<65>. 
* Build: Build<68>. 
* Windows: Windows<61>. 
* macOS: macOS<49>. 
* IDLE: IDLE<44>. 
* Tools/Demos: Tools/Demos<40>. 
* C API: C API<62>. 

Python 3.7.0 alpha 2

* Core and Builtins: Core and Builtins<175>. 
* Library: Library<177>. 
* Documentation: Documentation<65>. 
* Build: Build<69>. 
* IDLE: IDLE<45>. 
* C API: C API<63>. 

Python 3.7.0 alpha 1

* Security: Security<48>. 
* Core and Builtins: Core and Builtins<176>. 
* Library: Library<178>. 
* Documentation: Documentation<66>. 
* Tests: Tests<66>. 
* Build: Build<70>. 
* Windows: Windows<62>. 
* IDLE: IDLE<46>. 
* Tools/Demos: Tools/Demos<41>. 
* C API: C API<64>. 

Python 3.6.6 release candidate 1

* Core and Builtins: Core and Builtins<177>. 
* Library: Library<179>. 
* Documentation: Documentation<67>. 
* Tests: Tests<67>. 
* Build: Build<71>. 
* Windows: Windows<63>. 
* macOS: macOS<50>. 
* IDLE: IDLE<47>. 
* Tools/Demos: Tools/Demos<42>. 
* C API: C API<65>. 

Python 3.6.5 final

* Tests: Tests<68>. 
* Build: Build<72>. 

Python 3.6.5 release candidate 1

* Security: Security<49>. 
* Core and Builtins: Core and Builtins<178>. 
* Library: Library<180>. 
* Documentation: Documentation<68>. 
* Tests: Tests<69>. 
* Build: Build<73>. 
* Windows: Windows<64>. 
* macOS: macOS<51>. 
* IDLE: IDLE<48>. 
* Tools/Demos: Tools/Demos<43>. 
* C API: C API<66>. 

Python 3.6.4 release candidate 1

* Core and Builtins: Core and Builtins<179>. 
* Library: Library<181>. 
* Documentation: Documentation<69>. 
* Tests: Tests<70>. 
* Build: Build<74>. 
* Windows: Windows<65>. 
* macOS: macOS<52>. 
* IDLE: IDLE<49>. 
* Tools/Demos: Tools/Demos<44>. 
* C API: C API<67>. 

Python 3.6.3 final

* Library: Library<182>. 
* Build: Build<75>. 

Python 3.6.3 release candidate 1

* Security: Security<50>. 
* Core and Builtins: Core and Builtins<180>. 
* Library: Library<183>. 
* Documentation: Documentation<70>. 
* Tests: Tests<71>. 
* Build: Build<76>. 
* Windows: Windows<66>. 
* IDLE: IDLE<50>. 
* Tools/Demos: Tools/Demos<45>. 

Python 3.6.2 release candidate 2

* Security: Security<51>. 

Python 3.6.2 release candidate 1

* Security: Security<52>. 
* Core and Builtins: Core and Builtins<181>. 
* Library: Library<184>. 
* IDLE: IDLE<51>. 
* C API: C API<68>. 
* Build: Build<77>. 
* Documentation: Documentation<71>. 
* Tools/Demos: Tools/Demos<46>. 
* Tests: Tests<72>. 
* Windows: Windows<67>. 

Python 3.6.1 final

* Core and Builtins: Core and Builtins<182>. 
* Build: Build<78>. 

Python 3.6.1 release candidate 1

* Core and Builtins: Core and Builtins<183>. 
* Library: Library<185>. 
* IDLE: IDLE<52>. 
* Windows: Windows<68>. 
* C API: C API<69>. 
* Documentation: Documentation<72>. 
* Tests: Tests<73>. 
* Build: Build<79>. 

Python 3.6.0 release candidate 2

* Core and Builtins: Core and Builtins<184>. 
* Tools/Demos: Tools/Demos<47>. 
* Windows: Windows<69>. 
* Build: Build<80>. 

Python 3.6.0 release candidate 1

* Core and Builtins: Core and Builtins<185>. 
* Library: Library<186>. 
* C API: C API<70>. 
* Documentation: Documentation<73>. 
* Tools/Demos: Tools/Demos<48>. 

Python 3.6.0 beta 4

* Core and Builtins: Core and Builtins<186>. 
* Library: Library<187>. 
* Documentation: Documentation<74>. 
* Tests: Tests<74>. 
* Build: Build<81>. 

Python 3.6.0 beta 3

* Core and Builtins: Core and Builtins<187>. 
* Library: Library<188>. 
* Windows: Windows<70>. 
* Build: Build<82>. 
* Tests: Tests<75>. 

Python 3.6.0 beta 2

* Core and Builtins: Core and Builtins<188>. 
* Library: Library<189>. 
* Windows: Windows<71>. 
* C API: C API<71>. 
* Build: Build<83>. 
* Tests: Tests<76>. 

Python 3.6.0 beta 1

* Core and Builtins: Core and Builtins<189>. 
* Library: Library<190>. 
* IDLE: IDLE<53>. 
* C API: C API<72>. 
* Tests: Tests<77>. 
* Build: Build<84>. 
* Tools/Demos: Tools/Demos<49>. 
* Windows: Windows<72>. 

Python 3.6.0 alpha 4

* Core and Builtins: Core and Builtins<190>. 
* Library: Library<191>. 
* IDLE: IDLE<54>. 
* Tests: Tests<78>. 
* Windows: Windows<73>. 
* Build: Build<85>. 

Python 3.6.0 alpha 3

* Security: Security<53>. 
* Core and Builtins: Core and Builtins<191>. 
* Library: Library<192>. 
* IDLE: IDLE<55>. 
* C API: C API<73>. 
* Build: Build<86>. 
* Tools/Demos: Tools/Demos<50>. 
* Documentation: Documentation<75>. 
* Tests: Tests<79>. 

Python 3.6.0 alpha 2

* Security: Security<54>. 
* Core and Builtins: Core and Builtins<192>. 
* Library: Library<193>. 
* IDLE: IDLE<56>. 
* Documentation: Documentation<76>. 
* Tests: Tests<80>. 
* Windows: Windows<74>. 
* Build: Build<87>. 
* C API: C API<74>. 
* Tools/Demos: Tools/Demos<51>. 

Python 3.6.0 alpha 1

* Security: Security<55>. 
* Core and Builtins: Core and Builtins<193>. 
* Library: Library<194>. 
* IDLE: IDLE<57>. 
* Documentation: Documentation<77>. 
* Tests: Tests<81>. 
* Build: Build<88>. 
* Windows: Windows<75>. 
* Tools/Demos: Tools/Demos<52>. 
* C API: C API<75>. 

Python 3.5.5 release candidate 1

* Security: Security<56>. 
* Core and Builtins: Core and Builtins<194>. 
* Library: Library<195>. 

Python 3.5.4 final

* Library: Library<196>. 

Python 3.5.4 release candidate 1

* Security: Security<57>. 
* Core and Builtins: Core and Builtins<195>. 
* Library: Library<197>. 
* Documentation: Documentation<78>. 
* Tests: Tests<82>. 
* Build: Build<89>. 
* Windows: Windows<76>. 
* C API: C API<76>. 

Python 3.5.3 release candidate 1

* Security: Security<58>. 
* Core and Builtins: Core and Builtins<196>. 
* Library: Library<198>. 
* IDLE: IDLE<58>. 
* C API: C API<77>. 
* Documentation: Documentation<79>. 
* Tests: Tests<83>. 
* Tools/Demos: Tools/Demos<53>. 
* Windows: Windows<77>. 
* Build: Build<90>. 

Python 3.5.2 final

* Core and Builtins: Core and Builtins<197>. 
* Tests: Tests<84>. 
* IDLE: IDLE<59>. 

Python 3.5.2 release candidate 1

* Security: Security<59>. 
* Core and Builtins: Core and Builtins<198>. 
* Library: Library<199>. 
* IDLE: IDLE<60>. 
* Documentation: Documentation<80>. 
* Tests: Tests<85>. 
* Build: Build<91>. 
* Windows: Windows<78>. 
* Tools/Demos: Tools/Demos<54>. 

Python 3.5.1 final

* Core and Builtins: Core and Builtins<199>. 
* Windows: Windows<79>. 

Python 3.5.1 release candidate 1

* Core and Builtins: Core and Builtins<200>. 
* Library: Library<200>. 
* IDLE: IDLE<61>. 
* Documentation: Documentation<81>. 
* Tests: Tests<86>. 
* Build: Build<92>. 
* Windows: Windows<80>. 
* Tools/Demos: Tools/Demos<55>. 

Python 3.5.0 final

* Build: Build<93>. 

Python 3.5.0 release candidate 4

* Library: Library<201>. 
* Build: Build<94>. 

Python 3.5.0 release candidate 3

* Core and Builtins: Core and Builtins<201>. 
* Library: Library<202>. 

Python 3.5.0 release candidate 2

* Core and Builtins: Core and Builtins<202>. 
* Library: Library<203>. 

Python 3.5.0 release candidate 1

* Core and Builtins: Core and Builtins<203>. 
* Library: Library<204>. 
* IDLE: IDLE<62>. 
* Documentation: Documentation<82>. 
* Tests: Tests<87>. 

Python 3.5.0 beta 4

* Core and Builtins: Core and Builtins<204>. 
* Library: Library<205>. 
* Build: Build<95>. 

Python 3.5.0 beta 3

* Core and Builtins: Core and Builtins<205>. 
* Library: Library<206>. 
* Tests: Tests<88>. 
* Documentation: Documentation<83>. 
* Build: Build<96>. 

Python 3.5.0 beta 2

* Core and Builtins: Core and Builtins<206>. 
* Library: Library<207>. 

Python 3.5.0 beta 1

* Core and Builtins: Core and Builtins<207>. 
* Library: Library<208>. 
* IDLE: IDLE<63>. 
* Tests: Tests<89>. 
* Documentation: Documentation<84>. 
* Tools/Demos: Tools/Demos<56>. 

Python 3.5.0 alpha 4

* Core and Builtins: Core and Builtins<208>. 
* Library: Library<209>. 
* Build: Build<97>. 
* Tests: Tests<90>. 
* Tools/Demos: Tools/Demos<57>. 
* C API: C API<78>. 

Python 3.5.0 alpha 3

* Core and Builtins: Core and Builtins<209>. 
* Library: Library<210>. 
* Build: Build<98>. 
* Tests: Tests<91>. 
* Tools/Demos: Tools/Demos<58>. 

Python 3.5.0 alpha 2

* Core and Builtins: Core and Builtins<210>. 
* Library: Library<211>. 
* Build: Build<99>. 
* C API: C API<79>. 
* Windows: Windows<81>. 

Python 3.5.0 alpha 1

* Core and Builtins: Core and Builtins<211>. 
* Library: Library<212>. 
* IDLE: IDLE<64>. 
* Build: Build<100>. 
* C API: C API<80>. 
* Documentation: Documentation<85>. 
* Tests: Tests<92>. 
* Tools/Demos: Tools/Demos<59>. 
* Windows: Windows<82>. 

Οδηγός εκμάθησης Python

* Ανοίγοντας την όρεξή σας:: 
* Χρησιμοποιώντας τον Interpreter της Python:: 
* Μία Άτυπη Εισαγωγή στην Python:: 
* Περισσότερα εργαλεία Ελέγχου Ροής:: 
* Δομές Δεδομένων:: 
* Modules: Modules<2>. 
* Είσοδος και Έξοδος:: 
* Σφάλματα και Εξαιρέσεις:: 
* Κλάσεις:: 
* Brief tour of the standard library:: 
* Brief tour of the standard library — part II:: 
* Εικονικά Περιβάλλοντα και πακέτα:: 
* Και τώρα τι;:: 
* Διαδραστική Επεξεργασία Input και Αντικατάσταση Ιστορικού:: 
* Αριθμητική Κινητής Υποδιαστολής; Ζητήματα και Περιορισμοί: Αριθμητική Κινητής Υποδιαστολής Ζητήματα και Περιορισμοί. 
* Παράρτημα:: 

Χρησιμοποιώντας τον Interpreter της Python

* Κάνοντας invoke τον Interpreter:: 
* Ο Interpreter και το Περιβάλλον του:: 

Κάνοντας invoke τον Interpreter

* Εισαγωγή Ορίσματος:: 
* Interactive Λειτουργία:: 

Ο Interpreter και το Περιβάλλον του

* Κωδικοποίηση Πηγαίου Κώδικα:: 

Μία Άτυπη Εισαγωγή στην Python

* Χρησιμοποιώντας την Python ως Αριθμομηχανή:: 
* Πρώτα Βήματα Προς Τον Προγραμματισμό:: 

Χρησιμοποιώντας την Python ως Αριθμομηχανή

* Αριθμοί:: 
* Κείμενο:: 
* Λίστες:: 

Περισσότερα εργαλεία Ελέγχου Ροής

* Προτάσεις if:: 
* Προτάσεις for:: 
* Η συνάρτηση range(): Η συνάρτηση range. 
* break και continue Προτάσεις:: 
* else Ρήτρες στους βρόχους:: 
* Προτάσεις pass:: 
* Προτάσεις match:: 
* Καθορισμός Συναρτήσεων:: 
* Περισσότερο για τον Καθορισμό Συναρτήσεων:: 
* Intermezzo; Στυλ Κώδικα: Intermezzo Στυλ Κώδικα. 

Περισσότερο για τον Καθορισμό Συναρτήσεων

* Προεπιλεγμένες Τιμές Ορίσματος:: 
* Ορίσματα Keyword:: 
* Ειδικές παράμετροι:: 
* Λίστες Αυθαίρετων Ορισμάτων:: 
* Unpacking Λίστες Ορισμάτων:: 
* Εκφράσεις Lambda:: 
* Συμβολοσειρές Τεκμηρίωσης:: 
* Annotations Συναρτήσεων:: 

Ειδικές παράμετροι

* Παράμετροι Θέσης ή Keyword:: 
* Παράμετροι Μόνο-Θέσης:: 
* Ορίσματα μόνο Keyword:: 
* Παραδείγματα Συναρτήσεων:: 
* Ανακεφαλαίωση:: 

Δομές Δεδομένων

* Περισσότερα για τις Λίστες:: 
* Η δήλωση del:: 
* Πλειάδες (Tuples) και Ακολουθίες: Πλειάδες Tuples και Ακολουθίες. 
* Σύνολα (Sets): Σύνολα Sets. 
* Λεξικά (Dictionaries): Λεξικά Dictionaries. 
* Τεχνικές Looping:: 
* Περισσότερα για τις συνθήκες:: 
* Σύγκριση ακολουθιών και άλλων τύπων:: 

Περισσότερα για τις Λίστες

* Χρήστη Λιστών ως Στοίβες (Stacks): Χρήστη Λιστών ως Στοίβες Stacks. 
* Χρήση λιστών ως Ουρές (Queues): Χρήση λιστών ως Ουρές Queues. 
* Comprehensions Λίστας:: 
* Comprehensions Ένθετων Λιστών:: 
* Unpacking in Lists and List Comprehensions:: 

Modules

* Περισσότερα για τα Modules:: 
* Standard Modules:: 
* Η συνάρτηση dir(): Η συνάρτηση dir. 
* Πακέτα:: 

Περισσότερα για τα Modules

* Εκτέλεση modules ως scripts:: 
* Το Search Path του Module:: 
* «Compiled» Python αρχεία:: 

Πακέτα

* Εισάγοντας * από ένα Πακέτο:: 
* Intra-package αναφορές:: 
* Πακέτα σε Πολλαπλούς Καταλόγους:: 

Είσοδος και Έξοδος

* Ομορφότερη Μορφοποίηση Εξόδου:: 
* Ανάγνωση και Εγγραφή Αρχείων:: 

Ομορφότερη Μορφοποίηση Εξόδου

* Μορφοποιημένα String Literals:: 
* Η μέθοδος String format(): Η μέθοδος String format. 
* Χειροκίνητη Μορφοποίηση Συμβολοσειρών:: 
* Παλιά μορφοποίηση συμβολοσειράς:: 

Ανάγνωση και Εγγραφή Αρχείων

* Μέθοδοι Αντικειμένων Αρχείων:: 
* Αποθήκευση δομημένων δεδομένων με json:: 

Σφάλματα και Εξαιρέσεις

* Syntax Errors (Συντακτικά Σφάλματα): Syntax Errors Συντακτικά Σφάλματα. 
* Exceptions (Εξαιρέσεις): Exceptions Εξαιρέσεις. 
* Διαχείριση Εξαιρέσεων:: 
* Raising Εξαιρέσεων:: 
* Αλυσιδωτές Εξαιρέσεις:: 
* Εξαιρέσεις που καθορίζονται από το χρήστη:: 
* Καθορισμός ενεργειών καθαρισμού:: 
* Προκαθορισμένες ενέργειες καθαρισμού:: 
* Raising και Χειρισμός Πολλαπλών Άσχετων Εξαιρέσεων:: 
* Εμπλουτίζοντας τις Εξαιρέσεις με Σημειώσεις:: 

Κλάσεις

* Λίγα λόγια για Ονόματα και Αντικείμενα:: 
* Εμβέλεια και Πεδία Ονομάτων στην Python:: 
* Μια πρώτη ματιά στις Κλάσεις:: 
* Τυχαίες Παρατηρήσεις:: 
* Κληρονομικότητα:: 
* Ιδιωτικές Μεταβλητές:: 
* Μικροπράγματα:: 
* Επαναλήπτες:: 
* Γεννήτορες (Generators): Γεννήτορες Generators. 
* Εκφράσεις Γεννήτορων:: 

Εμβέλεια και Πεδία Ονομάτων στην Python

* Παράδειγμα Εμβέλειας και Χώρων Ονομάτων:: 

Μια πρώτη ματιά στις Κλάσεις

* Σύνταξη Ορισμού Κλάσης:: 
* Αντικείμενα Κλάσης:: 
* Αντικείμενα Στιγμιοτύπων:: 
* Αντικείμενα Μεθόδου:: 
* Μεταβλητές Κλάσης και Στιγμιότυπου:: 

Κληρονομικότητα

* Πολλαπλή Κληρονομικότητα:: 

Brief tour of the standard library

* Operating system interface:: 
* File wildcards:: 
* Command-line arguments:: 
* Error output redirection and program termination:: 
* String pattern matching:: 
* Μαθηματικά:: 
* Internet access:: 
* Dates and times:: 
* Data compression:: 
* Performance measurement:: 
* Quality control:: 
* Batteries included:: 

Brief tour of the standard library — part II

* Output formatting:: 
* Templating:: 
* Working with binary data record layouts:: 
* Multi-threading: Multi-threading<2>. 
* Logging:: 
* Weak references:: 
* Tools for working with lists:: 
* Decimal floating-point arithmetic:: 

Εικονικά Περιβάλλοντα και πακέτα

* Εισαγωγή:: 
* Δημιουργία εικονικών περιβάλλοντων:: 
* Διαχείριση Πακέτων με το pip:: 

Διαδραστική Επεξεργασία Input και Αντικατάσταση Ιστορικού

* Συμπλήρωση Tab και Επεξεργασία Ιστορικού:: 
* Εναλλακτικές λύσεις για τον Διαδραστικό Interpreter:: 

Αριθμητική Κινητής Υποδιαστολής:  Ζητήματα και Περιορισμοί

* Σφάλμα Αναπαράστασης:: 

Παράρτημα

* Διαδραστική Λειτουργία:: 

Διαδραστική Λειτουργία

* Διαχείριση Σφαλμάτων:: 
* Εκτελέσιμα Python Scripts:: 
* Το διαδραστικό αρχείο εκκίνησης:: 
* Τα Modules Προσαρμογής:: 

Ρύθμιση και Χρήση της Python

* Command line and environment: Command line and environment<2>. 
* Χρήση της Python σε πλατφόρμες Unix:: 
* Configure Python:: 
* Χρησιμοποιώντας Python στα Windows:: 
* Χρησιμοποιώντας Python σε macOS:: 
* Χρήση της Python σε Android:: 
* Χρήση Python σε iOS:: 
* Επεξεργαστές Κειμένου και IDEs:: 

Command line and environment

* Command line:: 
* Environment variables:: 

Command line

* Interface options:: 
* Generic options:: 
* Miscellaneous options:: 
* Controlling color:: 

Environment variables

* Debug-mode variables:: 

Χρήση της Python σε πλατφόρμες Unix

* Λήψη και εγκατάσταση της πιο πρόσφατης έκδοσης Python:: 
* Μεταγλώττιση της Python:: 
* Διαδρομές και αρχεία που σχετίζονται με την Python:: 
* Διάφορα:: 
* Custom OpenSSL:: 

Λήψη και εγκατάσταση της πιο πρόσφατης έκδοσης Python

* Σε Linux:: 
* Σε FreeBSD και OpenBSD:: 

Σε Linux

* Εγκατάσταση του IDLE:: 

Configure Python

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

Build Requirements

* Requirements for optional modules:: 

Generated files

* configure script:: 

Configure Options

* General Options:: 
* C compiler options:: 
* Linker options:: 
* Options for third-party dependencies:: 
* WebAssembly Options:: 
* Install Options:: 
* Performance options:: 
* Python Debug Build:: 
* 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 ci:: 
* make buildbottest:: 
* make regen-all:: 

Compiler and linker flags

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

Χρησιμοποιώντας Python στα Windows

* Διαχειριστής εγκατάστασης Python:: 
* Το ενσωματωμένο πακέτο:: 
* Τα πακέτα nuget.org: Τα πακέτα nuget org. 
* Εναλλακτικά πακέτα:: 
* Υποστηριζόμενες εκδόσεις των Windows:: 
* Αφαίρεση του περιορισμού MAX_PATH:: 
* Λειτουργία UTF-8:: 
* Εύρεση modules:: 
* Πρόσθετα modules:: 
* Μεταγλώττιση Python στα Windows:: 
* Το πλήρες πρόγραμμα εγκατάστασης:: 
* Το πρόγραμμα εκκίνησης Python για Windows (Απαρχαιωμένο): Το πρόγραμμα εκκίνησης Python για Windows Απαρχαιωμένο. 

Διαχειριστής εγκατάστασης Python

* Εγκατάσταση:: 
* Βασική χρήση:: 
* Εντολή βοήθειας:: 
* Καταχώριση χρόνων εκτέλεσης:: 
* Εγκαθιστώντας χρόνους εκτέλεσης:: 
* Εγκαταστάσεις εκτός σύνδεσης:: 
* Απεγκατάσταση χρόνων εκτέλεσης:: 
* Διαμόρφωση:: 
* Γραμμές Shebang:: 
* Προχωρημένη εγκατάσταση:: 
* Διαχειριστική διαμόρφωση:: 
* Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα:: 
* Index signatures:: 
* Αντιμετώπιση προβλημάτων:: 

Το ενσωματωμένο πακέτο

* Εφαρμογή Python:: 
* Ενσωμάτωση Python:: 

Τα πακέτα nuget.org

* Πακέτα με ελεύθερα νήματα:: 

Πρόσθετα modules

* PyWin32:: 
* cx_Freeze:: 

Το πλήρες πρόγραμμα εγκατάστασης

* Βήματα Εγκατάστασης:: 
* Αφαίρεση του περιορισμού MAX_PATH: Αφαίρεση του περιορισμού MAX_PATH<2>. 
* Εγκατάσταση χωρίς περιβάλλον διεπαφής χρήστη:: 
* Εγκατάσταση χωρίς λήψη:: 
* Τροποποίηση εγκατάστασης:: 
* Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα: Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα<2>. 

Το πρόγραμμα εκκίνησης Python για Windows (Απαρχαιωμένο)

* Ξεκινώντας:: 
* Γραμμές Shebang: Γραμμές Shebang<2>. 
* Ορίσματα στις γραμμές shebang:: 
* Προσαρμογή:: 
* Διαγνωστικά:: 
* Dry run:: 
* Εγκατάσταση κατ” απαίτηση:: 
* Επιστρεφόμενοι κωδικοί:: 

Ξεκινώντας

* Από τη γραμμή εντολών:: 
* Εικονικά Περιβάλλοντα:: 
* Από ένα script:: 
* Από συσχετίσεις αρχείων:: 

Προσαρμογή

* Προσαρμογή μέσω αρχείων INI:: 
* Προσαρμογή προεπιλεγμένων εκδόσεων Python:: 

Χρησιμοποιώντας Python σε macOS

* Χρησιμοποιώντας Python για macOS από το python.org: Χρησιμοποιώντας Python για macOS από το python org. 
* Εναλλακτικές Διανομές:: 
* Εγκατάσταση πρόσθετων πακέτων Python:: 
* Προγραμματισμός GUI:: 
* Προχωρημένα θέματα:: 
* Άλλοι πόροι:: 

Χρησιμοποιώντας Python για macOS από το python.org

* Βήματα εγκατάστασης:: 
* Πώς να εκτελέσετε ένα σενάριο Python:: 

Προχωρημένα θέματα

* Εγκατάσταση εκδόσεων Free-threaded:: 
* Εγκατάσταση χρησιμοποιώντας τη γραμμή εντολών:: 
* Διανομή εφαρμογών Python:: 
* Συμμόρφωση App Store:: 

Χρήση της Python σε Android

* Προσθήκη της Python σε μια εφαρμογή Android:: 
* Δημιουργία ενός πακέτου Python για Android:: 

Χρήση Python σε iOS

* Python κατά τον χρόνο εκτέλεσης σε iOS:: 
* Εγκατάσταση της Python σε iOS:: 
* Συμμόρφωση με το App Store:: 

Python κατά τον χρόνο εκτέλεσης σε iOS

* Συμβατότητα έκδοσης iOS:: 
* Αναγνώριση πλατφόρμας:: 
* Διαθεσιμότητα τυπικής βιβλιοθήκης:: 
* Δυαδικά modules επέκτασης:: 
* Δυαδικά αρχεία προσομοίωσης μεταγλωττιστή:: 

Εγκατάσταση της Python σε iOS

* Εργαλεία για την κατασκευή εφαρμογών iOS:: 
* Προσθήκη Python σε ένα έργο iOS:: 
* Δοκιμή ενός πακέτου Python:: 

Συμμόρφωση με το App Store

* Κώδικας ασύμβατος με την τυπική βιβλιοθήκη:: 
* Δηλώσεις απορρήτου:: 

Επεξεργαστές Κειμένου και IDEs

* IDLE — Επεξεργαστής και shell της Python:: 
* Άλλοι Επεξεργαστές Κειμένου και IDEs:: 

Εγχειρίδιο Αναφοράς της Γλώσσας Python

* Εισαγωγή: Εισαγωγή<2>. 
* Λεξική ανάλυση:: 
* Μοντέλο Δεδομένων:: 
* Μοντέλο εκτέλεσης:: 
* Το σύστημα εισαγωγής:: 
* Expressions:: 
* Απλές εντολές:: 
* Compound statements:: 
* Συστατικά ανωτάτου επιπέδου:: 
* Πλήρης προδιαγραφή γραμματικής:: 

Εισαγωγή

* Εναλλακτικές Υλοποιήσεις:: 
* Σημειογραφία:: 

Σημειογραφία

* Λεξικοί και Συντακτικοί ορισμοί:: 

Λεξική ανάλυση

* Δομή γραμμών:: 
* Άλλα tokens:: 
* Ονόματα (αναγνωριστικά και λέξεις-κλειδιά): Ονόματα αναγνωριστικά και λέξεις-κλειδιά. 
* Λεκτικά:: 
* Λεκτικά συμβολοσειράς και Bytes:: 
* Αριθμητικά λεκτικά:: 
* Τελεστές και οριοθέτες:: 

Δομή γραμμών

* Λογικές γραμμές:: 
* Φυσικές γραμμές:: 
* Σχόλια:: 
* Δηλώσεις κωδικοποίησης:: 
* Ρητή συνένωση γραμμών:: 
* Έμμεση συνένωση γραμμών:: 
* Κενές γραμμές:: 
* Εσοχή:: 
* Κενοί χαρακτήρες μεταξύ των tokens:: 
* Δείκτης τέλους:: 

Ονόματα (αναγνωριστικά και λέξεις-κλειδιά)

* Λέξεις-κλειδιά:: 
* Ήπιες λέξεις-κλειδιά:: 
* Δεσμευμένες κλάσεις αναγνωριστικών:: 
* Μη-ASCII χαρακτήρες στα ονόματα:: 

Λεκτικά συμβολοσειράς και Bytes

* Συμβολοσειρές τριπλού εισαγωγικού:: 
* Προθέματα συμβολοσειράς:: 
* Τυπική γραμματική:: 
* Ακολουθίες διαφυγής:: 
* Λεκτικά bytes:: 
* Λεκτικά raw συμβολοσειράς:: 
* f-strings:: 
* t-strings:: 
* Formal grammar for f-strings:: 

Ακολουθίες διαφυγής

* Αγνοημένο τέλος γραμμής:: 
* Χαρακτήρες με διαφυγή:: 
* Οκταδικός χαρακτήρας:: 
* Δεκαεξαδικός χαρακτήρας:: 
* Ονοματισμένος χαρακτήρας Unicode:: 
* Δεκαεξαδικοί χαρακτήρες Unicode:: 
* Μη αναγνωρισμένες ακολουθίες διαφυγής:: 

Αριθμητικά λεκτικά

* Λεκτικά ακεραίων:: 
* Λεκτικά κινητής υποδιαστολής:: 
* Λεκτικά φανταστικών:: 

Μοντέλο Δεδομένων

* Αντικείμενα@comma{} τιμές και τύποι: Αντικείμενα τιμές και τύποι. 
* Η τυπική ιεραρχία τύπου:: 
* Ειδικά ονόματα μεθόδων:: 
* Coroutines:: 

Η τυπική ιεραρχία τύπου

* None:: 
* NotImplemented:: 
* Ellipsis:: 
* numbers.Number: numbers Number. 
* Ακολουθίες:: 
* Σύνολο τύπων:: 
* Αντιστοιχίσεις:: 
* Τύποι με δυνατότητα κλήσης:: 
* Modules: Modules<3>. 
* Προσαρμοσμένες κλάσεις:: 
* Στιγμιότυπα κλάσης:: 
* Αντικείμενα εισόδου/εξόδου (γνωστά και ως αντικείμενα αρχείου): Αντικείμενα εισόδου/εξόδου γνωστά και ως αντικείμενα αρχείου. 
* Εσωτερικοί τύποι:: 

numbers.Number

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

Ακολουθίες

* Αμετάβλητες ακολουθίες:: 
* Μεταβλητές ακολουθίες:: 

Αντιστοιχίσεις

* Λεξικά:: 

Τύποι με δυνατότητα κλήσης

* Συναρτήσεις που ορίζονται από τον χρήστη:: 
* Μέθοδοι Στιγμιοτύπου:: 
* Generator Συναρτήσεις:: 
* Coroutine συναρτήσεις:: 
* Asynchronous generator συναρτήσεις:: 
* Ενσωματωμένες συναρτήσεις:: 
* Ενσωματωμένες μεθόδους:: 
* Κλάσεις: Κλάσεις<2>. 
* Στιγμιότυπα Κλάσης:: 

Συναρτήσεις που ορίζονται από τον χρήστη

* Ειδικά χαρακτηριστικά μόνο για ανάγνωση:: 
* Ειδικά εγγράψιμα χαρακτηριστικά:: 

Modules

* Χαρακτηριστικά που σχετίζονται με εισαγωγή σε αντικείμενα modules:: 
* Άλλα εγγράφως χαρακτηριστικά σε αντικείμενα μονάδων:: 
* Λεξικά Modules:: 

Προσαρμοσμένες κλάσεις

* Ειδικά χαρακτηριστικά:: 
* Ειδικές μέθοδοι:: 

Στιγμιότυπα κλάσης

* Ειδικά χαρακτηριστικά: Ειδικά χαρακτηριστικά<2>. 

Εσωτερικοί τύποι

* Αντικείμενα κώδικα:: 
* Πλαίσιο αντικειμένων:: 
* Αντικείμενα ανίχνευσης:: 
* Αντικείμενα τμηματοποίησης:: 
* Αντικείμενα στατικών μεθόδων:: 
* Αντικείμενα μεθόδων κλάσεων:: 

Αντικείμενα κώδικα

* Ειδικά χαρακτηριστικά μόνο για ανάγνωση: Ειδικά χαρακτηριστικά μόνο για ανάγνωση<2>. 
* Μέθοδοι σε αντικείμενα κώδικα:: 

Πλαίσιο αντικειμένων

* Ειδικά χαρακτηριστικά μόνο για ανάγνωση: Ειδικά χαρακτηριστικά μόνο για ανάγνωση<3>. 
* Ειδικά εγγράψιμα χαρακτηριστικά: Ειδικά εγγράψιμα χαρακτηριστικά<2>. 
* Μέθοδοι αντικειμένων πλαισίου:: 

Ειδικά ονόματα μεθόδων

* Βασική προσαρμογή:: 
* Προσαρμογή πρόσβασης χαρακτηριστικών:: 
* Προσαρμογή δημιουργίας κλάσης:: 
* Προσαρμογή ελέγχων παρουσίας και υποκλάσης:: 
* Εξομοίωση γενικών τύπων:: 
* Εξομοίωση αντικειμένων με δυνατότητα κλήσης:: 
* Εξομοίωση τύπων κοντέινερ:: 
* Εξομοίωση αριθμητικών τύπων:: 
* Με τους Διαχειριστές Περιβάλλοντος Δήλωσης:: 
* Προσαρμογή ορισμάτων θέσης στην αντιστοίχιση προτύπων κλάσης:: 
* Εξομοίωση τύπων buffer:: 
* Annotations:: 
* Αναζήτηση ειδικής μεθόδου:: 

Προσαρμογή πρόσβασης χαρακτηριστικών

* Προσαρμογή πρόσβασης χαρακτηριστικών module:: 
* Υλοποίηση Περιγραφέων:: 
* Κλήση Descriptors:: 
* __slots__: __slots__<2>. 

Προσαρμογή δημιουργίας κλάσης

* Μετα-κλάσεις:: 
* Επίλυση εγγραφών MRO:: 
* Προσδιορισμός της κατάλληλης μετακλάσης:: 
* Προετοιμασία του χώρου ονομάτων της κλάσης:: 
* Εκτέλεση του σώματος της κλάσης:: 
* Δημιουργία αντικειμένου κλάσης:: 
* Χρήσεις για μετακλάσεις:: 

Εξομοίωση γενικών τύπων

* Ο σκοπός του __class_getitem__:: 
* __class_getitem__ έναντι __getitem__:: 

Coroutines

* Awaitable Αντικείμενα:: 
* Coroutine Αντικείμενα:: 
* Ασύγχρονοι Iterators:: 
* Ασύγχρονοι Διαχειριστές Περιβάλλοντος:: 

Μοντέλο εκτέλεσης

* Δομή ενός προγράμματος:: 
* Ονομασία και σύνδεση:: 
* Εξαιρέσεις:: 
* Συστατικά χρόνου εκτέλεσης:: 

Ονομασία και σύνδεση

* Σύνδεση ονομάτων:: 
* Επίλυση ονομάτων:: 
* Σημειογραφία πεδία:: 
* Καθυστερημένη εκτίμηση:: 
* Ενσωματωμένες συναρτήσεις και περιορισμένη εκτέλεση:: 
* Αλληλεπίδραση με δυναμικές λειτουργίες:: 

Συστατικά χρόνου εκτέλεσης

* Γενικό μοντέλο υπολογισμού:: 
* Μοντέλο χρόνου εκτέλεσης της Python:: 

Το σύστημα εισαγωγής

* importlib: importlib<10>. 
* Πακέτα: Πακέτα<2>. 
* Αναζήτηση:: 
* Φόρτωση:: 
* Finder βασισμένος στη διαδρομή:: 
* Αντικατάσταση του τυπικού συστήματος εισαγωγής:: 
* Σχετικές εισαγωγές σε πακέτα:: 
* Ειδικές περιπτώσεις για το __main__:: 
* Αναφορές:: 

Πακέτα

* Κανονικά πακέτα:: 
* Namespace πακέτα:: 

Αναζήτηση

* Η προσωρινή μνήμη του module:: 
* Finders και loaders:: 
* Εισαγωγή hooks:: 
* Το meta path:: 

Φόρτωση

* Loaders:: 
* Submodules:: 
* Module specs:: 
* Χαρακτηριστικά __path__ στα modules:: 
* Reprs των modules:: 
* Ακύρωση cached bytecode:: 

Finder βασισμένος στη διαδρομή

* Finders καταχώρησης διαδρομής (Path entry finders): Finders καταχώρησης διαδρομής Path entry finders. 
* Πρωτόκολλο path entry finder:: 

Ειδικές περιπτώσεις για το __main__

* __main__.__spec__: __main__ __spec__. 

Expressions

* Arithmetic conversions:: 
* Atoms:: 
* Primaries:: 
* Await expression:: 
* The power operator:: 
* Unary arithmetic and bitwise operations:: 
* Binary arithmetic operations:: 
* Shifting operations:: 
* Binary bitwise operations:: 
* Comparisons:: 
* Boolean operations:: 
* Assignment expressions: Assignment expressions<2>. 
* Conditional expressions:: 
* Lambdas:: 
* Expression lists:: 
* Evaluation order:: 
* Operator precedence:: 

Atoms

* Built-in constants:: 
* Identifiers (Names): Identifiers Names. 
* Literals:: 
* Parenthesized forms:: 
* Displays for lists@comma{} sets and dictionaries: Displays for lists sets and dictionaries. 
* List displays:: 
* Set displays:: 
* Dictionary displays:: 
* Generator expressions:: 
* Yield expressions:: 

Identifiers (Names)

* Private name mangling:: 

Literals

* Literals and object identity:: 
* String literal concatenation:: 

Yield expressions

* Generator-iterator methods:: 
* Examples:: 
* Asynchronous generator functions:: 
* Asynchronous generator-iterator methods:: 

Primaries

* Attribute references:: 
* Subscriptions and slicings:: 
* Calls:: 

Subscriptions and slicings

* Slicings:: 
* Comma-separated subscripts:: 
* «Starred» subscriptions:: 
* Formal subscription grammar:: 

Comparisons

* Value comparisons:: 
* Membership test operations:: 
* Identity comparisons:: 

Απλές εντολές

* Εντολές έκφρασης:: 
* Εντολές ανάθεσης:: 
* Η εντολή assert:: 
* Η έκφραση pass:: 
* Η εντολή del:: 
* Η εντολή return:: 
* Η εντολή yield:: 
* Η εντολή raise:: 
* Η εντολή break:: 
* Η εντολή continue:: 
* Η εντολή import:: 
* Η εντολή global:: 
* Η εντολή nonlocal:: 
* Η εντολή type:: 

Εντολές ανάθεσης

* Επαυξημένες εντολές ανάθεσης:: 
* Εντολές ανάθεσης με σχολιασμό:: 

Η εντολή import

* Lazy imports:: 
* Μελλοντικές δηλώσεις:: 

Lazy imports

* Compatibility via __lazy_modules__:: 

Compound statements

* The if statement:: 
* The while statement:: 
* The for statement:: 
* The try statement:: 
* The with statement:: 
* The match statement:: 
* Function definitions:: 
* Class definitions:: 
* Coroutines: Coroutines<2>. 
* Type parameter lists:: 
* Annotations: Annotations<2>. 

The try statement

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

The match statement

* Overview:: 
* Guards:: 
* Irrefutable Case Blocks:: 
* Patterns:: 

Patterns

* OR Patterns:: 
* AS Patterns:: 
* Literal Patterns:: 
* Capture Patterns:: 
* Wildcard Patterns:: 
* Value Patterns:: 
* Group Patterns:: 
* Sequence Patterns:: 
* Mapping Patterns:: 
* Class Patterns:: 

Class definitions

* Multiple inheritance:: 

Coroutines

* Coroutine function definition:: 
* The async for statement:: 
* The async with statement:: 

Type parameter lists

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

Συστατικά ανωτάτου επιπέδου

* Πλήρη προγράμματα Python:: 
* Είσοδος από αρχείο:: 
* Διαδραστική είσοδος:: 
* Είσοδος έκφρασης:: 

The Python Standard Library

* Introduction: Introduction<4>. 
* Ενσωματωμένες (Built-in) Συναρτήσεις: Ενσωματωμένες Built-in Συναρτήσεις. 
* Built-in Constants:: 
* Τύποι Built-in:: 
* Built-in Exceptions:: 
* Thread Safety Guarantees:: 
* Text Processing Services:: 
* Υπηρεσίες Δυαδικών Δεδομένων:: 
* Data Types:: 
* Αριθμητικά και Μαθηματικά Modules:: 
* Functional Programming Modules:: 
* File and Directory Access:: 
* Data Persistence:: 
* Data Compression and Archiving:: 
* File Formats:: 
* Cryptographic Services:: 
* Generic Operating System Services:: 
* Command-line interface libraries:: 
* Concurrent Execution:: 
* Networking and Interprocess Communication:: 
* Internet Data Handling:: 
* Structured Markup Processing Tools:: 
* Πρωτόκολλα Internet και Υποστήριξη:: 
* Multimedia Services:: 
* Internationalization:: 
* Γραφικές επαφές χρηστών με το Tk:: 
* Εργαλεία Ανάπτυξης:: 
* Debugging and profiling:: 
* Software Packaging and Distribution:: 
* Python Runtime Services:: 
* Custom Python Interpreters:: 
* Importing Modules:: 
* Python Language Services:: 
* MS Windows Specific Services:: 
* Unix-specific services:: 
* Command-line interface (Διεπαφή Γραμμής Εντολών) (CLI) για modules: Command-line interface Διεπαφή Γραμμής Εντολών CLI για modules. 
* Superseded modules:: 
* Removed Modules:: 
* Security Considerations: Security Considerations<3>. 

Introduction

* Notes on availability:: 

Notes on availability

* WebAssembly platforms:: 
* Mobile platforms:: 

Built-in Constants

* Constants added by the site module:: 

Τύποι Built-in

* Έλεγχος Έγκυρης Τιμής:: 
* Λογικές (Boolean) Πράξεις — and@comma{} or@comma{} not: Λογικές Boolean Πράξεις — and or not. 
* Συγκρίσεις:: 
* Αριμθητικοί Τύποι — int@comma{} float@comma{} complex: Αριμθητικοί Τύποι — int float complex. 
* Τύπος Boolean - bool:: 
* Τύποι Iterator:: 
* Τύποι Ακολουθίας (Sequence) — list@comma{} tuple@comma{} range: Τύποι Ακολουθίας Sequence — list tuple range. 
* Σύνοψη μεθόδων τύπου κειμένου και δυαδική ακολουθίας:: 
* Τύπος Ακολουθίας (Sequence) Κειμένου — str: Τύπος Ακολουθίας Sequence Κειμένου — str. 
* Τύποι δυαδικής ακολουθίας — bytes@comma{} bytearray@comma{} memoryview: Τύποι δυαδικής ακολουθίας — bytes bytearray memoryview. 
* Τύποι Συνόλου (Set) — set@comma{} frozenset: Τύποι Συνόλου Set — set frozenset. 
* Mapping types — dict@comma{} frozendict: Mapping types — dict frozendict. 
* Τύποι Διαχείρισης Περιεχομένου:: 
* Τύποι Annotation τύπου — Generic Alias@comma{} Union: Τύποι Annotation τύπου — Generic Alias Union. 
* Άλλοι Ενσωματωμένοι (built-in) Τύποι: Άλλοι Ενσωματωμένοι built-in Τύποι. 
* Ειδικά Χαρακτηριστικά:: 
* Περιορισμός μήκους μετατροπής συμβολοσειράς ακέραιου αριθμού:: 

Αριμθητικοί Τύποι — int, float, complex

* Bitwise Πράξεις σε Ακέραιους Τύπους:: 
* Περαιτέρω Μέθοδοι των Ακέραιων Τύπων:: 
* Περαιτέρω Μέθοδοι για Float:: 
* Περαιτέρω Μέθοδοι για Μιγαδικούς:: 
* Κατακερματισμός των αριθμητικών τύπων:: 

Τύποι Iterator

* Τύποι Generator:: 

Τύποι Ακολουθίας (Sequence) — list, tuple, range

* Κοινές Λειτουργίες Ακολουθιών (Sequences): Κοινές Λειτουργίες Ακολουθιών Sequences. 
* Τύποι Αμετάβλητων Ακολουθιών (Sequences): Τύποι Αμετάβλητων Ακολουθιών Sequences. 
* Τύποι Μεταβλητών Ακολουθιών (Sequences): Τύποι Μεταβλητών Ακολουθιών Sequences. 
* Λίστες: Λίστες<2>. 
* Πλειάδες (Tuples): Πλειάδες Tuples. 
* Εύρη (Ranges): Εύρη Ranges. 

Τύπος Ακολουθίας (Sequence) Κειμένου — str

* Μέθοδοι Συμβολοσειράς (String): Μέθοδοι Συμβολοσειράς String. 
* Διαμορφωμένες Κυριολεκτικές Συμβολοσειρές (f-strings): Διαμορφωμένες Κυριολεκτικές Συμβολοσειρές f-strings. 
* Template String Literals (t-strings): Template String Literals t-strings. 
* printf-style String Formatting:: 

Διαμορφωμένες Κυριολεκτικές Συμβολοσειρές (f-strings)

* Debug specifier:: 
* Conversion specifier:: 
* Format specifier:: 

Τύποι δυαδικής ακολουθίας — bytes, bytearray, memoryview

* Αντικείμενα Bytes:: 
* Αντικείμενα Bytearray:: 
* Λειτουργίες Bytes και Bytearray:: 
* Μορφοποίηση Bytes τύπου printf:: 
* Όψεις Μνήμης:: 

Mapping types — dict, frozendict

* Αντικείμενα όψης λεξικού:: 
* Frozen dictionaries:: 

Τύποι Annotation τύπου — Generic Alias, Union

* Τύπος Generic Alias:: 
* Τύπος Ένωσης:: 

Τύπος Generic Alias

* Τυπικές Γενικές Κλάσεις:: 
* Ειδικά Χαρακτηριστικά αντικειμένων GenericAlias:: 

Άλλοι Ενσωματωμένοι (built-in) Τύποι

* Modules: Modules<4>. 
* Κλάσεις και Στιγμιότυπα Κλάσης:: 
* Συναρτήσεις:: 
* Μέθοδοι:: 
* Αντικείμενα Κώδικα:: 
* Τύποι Αντικειμένων:: 
* Το Αντικείμενο Null:: 
* Το αντικείμενο Ellipsis:: 
* Το NotImplemented Αντικείμενο:: 
* Εσωτερικά Αντικείμενα:: 

Περιορισμός μήκους μετατροπής συμβολοσειράς ακέραιου αριθμού

* Επηρεασμένα APIs:: 
* Διαμόρφωση ορίου:: 
* Προτεινόμενη διαμόρφωση:: 

Built-in Exceptions

* Exception context:: 
* Inheriting from built-in exceptions:: 
* Base classes:: 
* Concrete exceptions:: 
* Warnings:: 
* Exception groups:: 
* Exception hierarchy:: 

Concrete exceptions

* OS exceptions:: 

Thread Safety Guarantees

* Thread safety levels:: 
* Thread safety for list objects:: 
* Thread safety for dict objects:: 
* Thread safety for set objects:: 
* Thread safety for bytearray objects:: 
* Thread safety for memoryview objects:: 

Thread safety levels

* Incompatible:: 
* Compatible:: 
* Safe on distinct objects:: 
* Safe on shared objects:: 
* Atomic:: 

Text Processing Services

* string — Common string operations:: 
* string.templatelib — Support for template string literals: string templatelib — Support for template string literals. 
* re — Regular expression operations:: 
* difflib — Helpers for computing deltas:: 
* textwrap — Περιτύλιγμα και γέμισμα κειμένου:: 
* unicodedata — Unicode Database:: 
* stringprep — Internet String Preparation:: 
* readline — GNU readline interface:: 
* rlcompleter — Completion function for GNU readline:: 

string — Common string operations

* String constants:: 
* Custom string formatting:: 
* Format string syntax:: 
* Template strings ($-strings): Template strings $-strings. 
* Helper functions:: 

Format string syntax

* Format specification mini-language:: 
* Format examples:: 

string.templatelib — Support for template string literals

* Template strings:: 
* Types:: 
* Helper functions: Helper functions<2>. 

re — Regular expression operations

* Regular expression syntax:: 
* Module contents:: 
* Regular expression objects:: 
* Match objects:: 
* Regular expression examples:: 

Module contents

* Flags:: 
* Functions:: 
* Exceptions:: 

Regular expression examples

* Checking for a pair:: 
* Simulating scanf(): Simulating scanf. 
* search() vs. prefixmatch(): search vs prefixmatch. 
* prefixmatch() vs. match(): prefixmatch vs match. 
* Making a phonebook:: 
* Text munging:: 
* Finding all adverbs:: 
* Finding all adverbs and their positions:: 
* Raw string notation:: 
* Writing a tokenizer:: 

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

* Init file:: 
* Line buffer:: 
* History file:: 
* History list:: 
* Startup hooks:: 
* Completion:: 
* Example:: 

Υπηρεσίες Δυαδικών Δεδομένων

* struct — Ερμηνεία bytes ως πακετοποιημένα δυαδικά δεδομένα:: 
* codecs — Codec registry and base classes:: 

struct — Ερμηνεία bytes ως πακετοποιημένα δυαδικά δεδομένα

* Συναρτήσεις και εξαιρέσεις:: 
* Συμβολοσειρές μορφοποίησης:: 
* Εφαρμογές:: 
* Κλάσεις: Κλάσεις<3>. 

Συμβολοσειρές μορφοποίησης

* Διάταξη Byte@comma{} Μέγεθος και Στοίχιση: Διάταξη Byte Μέγεθος και Στοίχιση. 
* Χαρακτήρες μορφής:: 
* Παραδείγματα:: 

Εφαρμογές

* Native Μορφές:: 
* Τυπικές μορφές:: 

codecs — Codec registry and base classes

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

Codec Base Classes

* Error Handlers:: 
* 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:: 
* Standalone Codec Functions:: 
* Text Transforms:: 

Data Types

* datetime — Basic date and time types:: 
* zoneinfo — IANA time zone support:: 
* calendar — General calendar-related functions:: 
* collections — Container datatypes:: 
* collections.abc — Αφηρημένες Βασικές Κλάσεις για Containers: collections abc — Αφηρημένες Βασικές Κλάσεις για Containers. 
* heapq — Heap queue algorithm:: 
* bisect — Array bisection algorithm:: 
* array — Efficient arrays of numeric values:: 
* weakref — Weak references:: 
* types — Δημιουργία δυναμικών τύπων και ονόματα για ενσωματωμένους τύπους:: 
* copy — Shallow and deep copy operations:: 
* pprint — Data pretty printer:: 
* reprlib — Alternate repr() implementation: reprlib — Alternate repr implementation. 
* enum — Support for enumerations:: 
* graphlib — Functionality to operate with graph-like structures:: 

datetime — Basic date and time types

* Aware and naive objects:: 
* Constants:: 
* Available types:: 
* timedelta objects:: 
* date objects:: 
* datetime objects:: 
* time objects:: 
* tzinfo objects:: 
* timezone objects:: 
* strftime() and strptime() behavior: strftime and strptime behavior. 

Available types

* Common properties:: 
* Determining if an object is aware or naive:: 

timedelta objects

* Examples of usage; timedelta: Examples of usage timedelta. 

date objects

* Examples of usage; date: Examples of usage date. 

datetime objects

* Examples of usage; datetime: Examples of usage datetime. 

time objects

* Examples of usage; time: Examples of usage time. 

strftime() and strptime() behavior

* strftime() and strptime() format codes: strftime and strptime format codes. 
* Technical detail:: 

zoneinfo — IANA time zone support

* Using ZoneInfo:: 
* Data sources:: 
* The ZoneInfo class:: 
* Functions: Functions<2>. 
* Globals:: 
* Exceptions and warnings:: 

Data sources

* Configuring the data sources:: 

Configuring the data sources

* Compile-time configuration:: 
* Environment configuration:: 
* Runtime configuration:: 

The ZoneInfo class

* String representations:: 
* Pickle serialization:: 

calendar — General calendar-related functions

* Command-line usage:: 

collections — Container datatypes

* ChainMap objects:: 
* Counter objects:: 
* deque objects:: 
* defaultdict objects:: 
* namedtuple() Factory Function for Tuples with Named Fields: namedtuple Factory Function for Tuples with Named Fields. 
* OrderedDict objects:: 
* UserDict objects:: 
* UserList objects:: 
* UserString objects:: 

ChainMap objects

* ChainMap Examples and Recipes:: 

deque objects

* deque Recipes:: 

defaultdict objects

* defaultdict Examples:: 

OrderedDict objects

* OrderedDict Examples and Recipes:: 

collections.abc — Αφηρημένες Βασικές Κλάσεις για Containers

* Αφηρημένες Βασικές Κλάσεις Συλλογών:: 
* Αφηρημένες Βασικές Κλάσεις Συλλογών – Αναλυτικές Περιγραφές:: 
* Παραδείγματα και Συνταγές:: 

heapq — Heap queue algorithm

* Basic Examples:: 
* Other Applications:: 
* Priority Queue Implementation Notes:: 
* Theory:: 

bisect — Array bisection algorithm

* Performance Notes:: 
* Searching Sorted Lists:: 
* Examples: Examples<2>. 

weakref — Weak references

* Weak Reference Objects:: 
* Example: Example<2>. 
* Finalizer Objects:: 
* Comparing finalizers with __del__() methods: Comparing finalizers with __del__ methods. 

types — Δημιουργία δυναμικών τύπων και ονόματα για ενσωματωμένους τύπους

* Δημιουργία Δυναμικών Τύπων:: 
* Τυπικοί Τύποι Διερμηνέα:: 
* Πρόσθετες βοηθητικές κλάσεις και συναρτήσεις:: 
* Βοηθητικές Συναρτήσεις Coroutine:: 

pprint — Data pretty printer

* Functions: Functions<3>. 
* PrettyPrinter objects:: 
* Example: Example<3>. 

reprlib — Alternate repr() implementation

* Repr Objects:: 
* Subclassing Repr Objects:: 

enum — Support for enumerations

* Module contents: Module contents<2>. 
* Data types:: 
* Utilities and decorators:: 
* Notes:: 

Data types

* Supported __dunder__ names:: 
* Supported _sunder_ names:: 

graphlib — Functionality to operate with graph-like structures

* Exceptions: Exceptions<2>. 

Αριθμητικά και Μαθηματικά Modules

* numbers — Numeric abstract base classes:: 
* math — Mathematical functions:: 
* math.integer — integer-specific mathematics functions: math integer — integer-specific mathematics functions. 
* cmath — Mathematical functions for complex numbers:: 
* decimal — Decimal fixed-point and floating-point arithmetic:: 
* fractions — Rational numbers:: 
* random — Δημιουργία ψευδοτυχαίων αριθμών:: 
* statistics — Mathematical statistics functions:: 

numbers — Numeric abstract base classes

* The numeric tower:: 
* Notes for type implementers:: 

Notes for type implementers

* Adding More Numeric ABCs:: 
* Implementing the arithmetic operations:: 

math — Mathematical functions

* Floating point arithmetic:: 
* Floating point manipulation functions:: 
* Power@comma{} exponential and logarithmic functions: Power exponential and logarithmic functions. 
* Summation and product functions:: 
* Angular conversion:: 
* Trigonometric functions:: 
* Hyperbolic functions:: 
* Special functions:: 
* Number-theoretic functions:: 
* Constants: Constants<2>. 

cmath — Mathematical functions for complex numbers

* Conversions to and from polar coordinates:: 
* Power and logarithmic functions:: 
* Trigonometric functions: Trigonometric functions<2>. 
* Hyperbolic functions: Hyperbolic functions<2>. 
* Classification functions:: 
* Constants: Constants<3>. 

decimal — Decimal fixed-point and floating-point arithmetic

* Quick-start tutorial:: 
* Decimal objects:: 
* Context objects:: 
* Constants: Constants<4>. 
* Rounding modes:: 
* Signals:: 
* Floating-point notes:: 
* Working with threads:: 
* Recipes:: 
* Decimal FAQ:: 

Decimal objects

* Logical operands:: 

Floating-point notes

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

random — Δημιουργία ψευδοτυχαίων αριθμών

* Συναρτήσεις καταγραφής:: 
* Συναρτήσεις για bytes:: 
* Συναρτήσεις για ακέραιους:: 
* Συναρτήσεις για ακολουθίες:: 
* Διακριτές κατανομές:: 
* Πραγματικές κατανομές:: 
* Εναλλακτική Γεννήτρια:: 
* Σημειώσεις για την Αναπαραγωγιμότητα:: 
* Παραδείγματα: Παραδείγματα<2>. 
* Συνταγές:: 
* Χρήση από τη γραμμή εντολών:: 
* Παράδειγμα από τη γραμμή εντολών:: 

statistics — Mathematical statistics functions

* Averages and measures of central location:: 
* Measures of spread:: 
* Statistics for relations between two inputs:: 
* Function details:: 
* Exceptions: Exceptions<3>. 
* NormalDist objects:: 
* Examples and Recipes:: 

Examples and Recipes

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

Functional Programming Modules

* itertools — Functions creating iterators for efficient looping:: 
* functools — Higher-order functions and operations on callable objects:: 
* operator — Standard operators as functions:: 

itertools — Functions creating iterators for efficient looping

* Itertool Functions:: 
* Itertools Recipes:: 

functools — Higher-order functions and operations on callable objects

* partial Objects:: 

operator — Standard operators as functions

* Mapping Operators to Functions:: 
* In-place Operators:: 

File and Directory Access

* pathlib — Object-oriented filesystem paths:: 
* os.path — Common pathname manipulations: os path — Common pathname manipulations. 
* stat — Interpreting stat() results: stat — Interpreting stat results. 
* filecmp — File and Directory Comparisons:: 
* tempfile — Generate temporary files and directories:: 
* glob — Unix style pathname pattern expansion:: 
* fnmatch — Unix filename pattern matching:: 
* linecache — Random access to text lines:: 
* shutil — High-level file operations:: 

pathlib — Object-oriented filesystem paths

* Basic use:: 
* Exceptions: Exceptions<4>. 
* Pure paths:: 
* Concrete paths:: 
* Pattern language:: 
* Comparison to the glob module:: 
* Comparison to the os and os.path modules: Comparison to the os and os path modules. 
* Protocols:: 

Pure paths

* General properties:: 
* Operators:: 
* Accessing individual parts:: 
* Methods and properties:: 

Concrete paths

* Parsing and generating URIs:: 
* Expanding and resolving paths:: 
* Querying file type and status:: 
* Reading and writing files:: 
* Reading directories:: 
* Creating files and directories:: 
* Copying@comma{} moving and deleting: Copying moving and deleting. 
* Permissions and ownership:: 

Comparison to the os and os.path modules

* Corresponding tools:: 

filecmp — File and Directory Comparisons

* The dircmp class:: 

tempfile — Generate temporary files and directories

* Examples: Examples<3>. 
* Deprecated functions and variables:: 

glob — Unix style pathname pattern expansion

* Examples: Examples<4>. 

shutil — High-level file operations

* Directory and files operations:: 
* Archiving operations:: 
* Querying the size of the output terminal:: 

Directory and files operations

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

Archiving operations

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

Data Persistence

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

pickle — Python object serialization

* Relationship to other Python modules:: 
* Data stream format:: 
* Module Interface:: 
* What can be pickled and unpickled?:: 
* Pickling Class Instances:: 
* Custom Reduction for Types@comma{} Functions@comma{} and Other Objects: Custom Reduction for Types Functions and Other Objects. 
* Out-of-band Buffers:: 
* Restricting Globals:: 
* Performance: Performance<2>. 
* Examples: Examples<5>. 
* Command-line interface:: 

Relationship to other Python modules

* Comparison with marshal:: 
* Comparison with json:: 

Pickling Class Instances

* Persistence of External Objects:: 
* Dispatch Tables:: 
* Handling Stateful Objects:: 

Out-of-band Buffers

* Provider API:: 
* Consumer API:: 
* Example: Example<4>. 

copyreg — Register pickle support functions

* Example: Example<5>. 

shelve — Python object persistence

* Restrictions:: 
* Example: Example<6>. 
* Exceptions: Exceptions<5>. 

dbm — Interfaces to Unix «databases»

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

sqlite3 — DB-API 2.0 interface for SQLite databases

* Tutorial:: 
* Reference:: 
* How-to guides:: 
* Explanation:: 

Reference

* Module functions:: 
* Module constants:: 
* Connection objects:: 
* Cursor objects:: 
* Row objects:: 
* Blob objects:: 
* PrepareProtocol objects:: 
* Exceptions: Exceptions<6>. 
* SQLite and Python types:: 
* Default adapters and converters (deprecated): Default adapters and converters deprecated. 
* Command-line interface: Command-line interface<2>. 

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:: 

Data Compression and Archiving

* The compression package:: 
* compression.zstd — Compression compatible with the Zstandard format: compression zstd — Compression compatible with the Zstandard format. 
* zlib — Compression compatible with gzip:: 
* gzip — Υποστήριξη για αρχεία gzip:: 
* bz2 — Support for bzip2 compression:: 
* lzma — Compression using the LZMA algorithm:: 
* zipfile — Work with ZIP archives:: 
* tarfile — Read and write tar archive files:: 

compression.zstd — Compression compatible with the Zstandard format

* Exceptions: Exceptions<7>. 
* Reading and writing compressed files:: 
* Compressing and decompressing data in memory:: 
* Zstandard dictionaries:: 
* Advanced parameter control:: 
* Miscellaneous:: 
* Examples: Examples<6>. 

gzip — Υποστήριξη για αρχεία gzip

* Παραδείγματα χρήσης:: 
* Διεπαφή Γραμμής Εντολών:: 

Διεπαφή Γραμμής Εντολών

* Επιλογές γραμμής εντολών:: 

bz2 — Support for bzip2 compression

* (De)compression of files: De compression of files. 
* Incremental (de)compression: Incremental de compression. 
* One-shot (de)compression: One-shot de compression. 
* Examples of usage:: 

lzma — Compression using the LZMA algorithm

* Reading and writing compressed files: Reading and writing compressed files<2>. 
* Compressing and decompressing data in memory: Compressing and decompressing data in memory<2>. 
* Miscellaneous: Miscellaneous<2>. 
* Specifying custom filter chains:: 
* Examples: Examples<7>. 

zipfile — Work with ZIP archives

* ZipFile objects:: 
* Path objects:: 
* PyZipFile objects:: 
* ZipInfo objects:: 
* Command-line interface: Command-line interface<3>. 
* Decompression pitfalls:: 

Command-line interface

* Command-line options:: 

Decompression pitfalls

* From file itself:: 
* File system limitations:: 
* Resources limitations:: 
* Interruption:: 
* Default behaviors of extraction:: 

tarfile — Read and write tar archive files

* TarFile Objects:: 
* TarInfo Objects:: 
* Extraction filters:: 
* Command-Line Interface:: 
* Examples: Examples<8>. 
* Supported tar formats:: 
* Unicode issues:: 

Extraction filters

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

Command-Line Interface

* Command-line options: Command-line options<2>. 

Examples

* Reading examples:: 
* Writing examples:: 

File Formats

* csv — Ανάγνωση και Εγγραφή Αρχείων CSV:: 
* configparser — Configuration file parser:: 
* tomllib — Parse TOML files:: 
* netrc — netrc file processing:: 
* plistlib — Generate and parse Apple .plist files: plistlib — Generate and parse Apple plist files. 

csv — Ανάγνωση και Εγγραφή Αρχείων CSV

* Περιεχόμενα του Module:: 
* Διάλεκτοι και Παράμετροι Μορφοποίησης:: 
* Αντικείμενα Αναγνώστη:: 
* Αντικείμενα Εγγραφέα:: 
* Παραδείγματα: Παραδείγματα<3>. 

configparser — Configuration file parser

* Quick Start:: 
* Supported Datatypes:: 
* Fallback Values:: 
* Supported INI File Structure:: 
* Unnamed Sections:: 
* Interpolation of values:: 
* Mapping Protocol Access:: 
* Customizing Parser Behaviour:: 
* Legacy API Examples:: 
* ConfigParser Objects:: 
* RawConfigParser Objects:: 
* Exceptions: Exceptions<8>. 

tomllib — Parse TOML files

* Examples: Examples<9>. 
* Conversion Table:: 

netrc — netrc file processing

* netrc Objects:: 

plistlib — Generate and parse Apple .plist files

* Examples: Examples<10>. 

Cryptographic Services

* hashlib — Secure hashes and message digests:: 
* hmac — Keyed-Hashing for Message Authentication:: 
* secrets — Generate secure random numbers for managing secrets:: 

hashlib — Secure hashes and message digests

* Hash algorithms:: 
* Usage:: 
* Constructors:: 
* Attributes:: 
* Hash Objects:: 
* SHAKE variable length digests:: 
* File hashing:: 
* Key derivation:: 
* BLAKE2:: 

BLAKE2

* Creating hash objects:: 
* Constants: Constants<5>. 
* Examples: Examples<11>. 
* Credits:: 

Examples

* Simple hashing:: 
* Using different digest sizes:: 
* Keyed hashing:: 
* Randomized hashing:: 
* Personalization:: 
* Tree mode:: 

secrets — Generate secure random numbers for managing secrets

* Random numbers:: 
* Generating tokens:: 
* Other functions:: 
* Recipes and best practices:: 

Generating tokens

* How many bytes should tokens use?:: 

Generic Operating System Services

* os — Miscellaneous operating system interfaces:: 
* io — Core tools for working with streams:: 
* time — Πρόσβαση και μετατροπές χρόνου:: 
* logging — Logging facility for Python:: 
* logging.config — Logging configuration: logging config — Logging configuration. 
* logging.handlers — Logging handlers: logging handlers — Logging handlers. 
* platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας:: 
* errno — Standard errno system symbols:: 
* ctypes — A foreign function library for Python:: 

os — Miscellaneous operating system interfaces

* File Names@comma{} Command Line Arguments@comma{} and Environment Variables: File Names Command Line Arguments and Environment Variables. 
* Python UTF-8 Mode:: 
* Process Parameters:: 
* File Object Creation:: 
* File Descriptor Operations:: 
* Files and Directories:: 
* Process Management:: 
* Interface to the scheduler:: 
* Miscellaneous System Information:: 
* Random numbers: Random numbers<2>. 

File Descriptor Operations

* Querying the size of a terminal:: 
* Inheritance of File Descriptors:: 

Files and Directories

* Timer File Descriptors:: 
* Linux extended attributes:: 

io — Core tools for working with streams

* Overview: Overview<2>. 
* Text Encoding:: 
* High-level Module Interface:: 
* Class hierarchy:: 
* Static Typing:: 
* Performance: Performance<3>. 

Overview

* Text I/O:: 
* Binary I/O:: 
* Raw I/O:: 

Text Encoding

* Opt-in EncodingWarning:: 

Class hierarchy

* I/O Base Classes:: 
* Raw File I/O:: 
* Buffered Streams:: 
* Text I/O: Text I/O<2>. 

Performance

* Binary I/O: Binary I/O<2>. 
* Text I/O: Text I/O<3>. 
* Multi-threading: Multi-threading<3>. 
* Reentrancy:: 

time — Πρόσβαση και μετατροπές χρόνου

* Συναρτήσεις: Συναρτήσεις<2>. 
* Σταθερές αναγνωριστικού ρολογιού:: 
* Σταθερές ζώνης ώρας:: 

logging — Logging facility for Python

* Logger Objects:: 
* Logging Levels:: 
* Handler Objects:: 
* Formatter Objects:: 
* Filter Objects:: 
* LogRecord Objects:: 
* LogRecord attributes:: 
* LoggerAdapter Objects:: 
* Thread Safety:: 
* Module-Level Functions:: 
* 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

* StreamHandler:: 
* FileHandler:: 
* NullHandler:: 
* WatchedFileHandler:: 
* BaseRotatingHandler:: 
* RotatingFileHandler:: 
* TimedRotatingFileHandler:: 
* SocketHandler:: 
* DatagramHandler:: 
* SysLogHandler:: 
* NTEventLogHandler:: 
* SMTPHandler:: 
* MemoryHandler:: 
* HTTPHandler:: 
* QueueHandler:: 
* QueueListener:: 

platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας

* Cross Platform:: 
* Πλατφόρμα Windows:: 
* Πλατφόρμα macOS:: 
* Πλατφόρμα iOS:: 
* Πλατφόρμες Unix:: 
* Πλατφόρμες Linux:: 
* Πλατφόρμα Android:: 
* Χρήση από γραμμή εντολών:: 

ctypes — A foreign function library for Python

* ctypes tutorial:: 
* ctypes reference:: 

ctypes tutorial

* Loading dynamic link libraries:: 
* Accessing functions from loaded dlls:: 
* Calling functions:: 
* Fundamental data types:: 
* Calling functions@comma{} continued: Calling functions continued. 
* Calling variadic functions:: 
* Calling functions with your own custom data types:: 
* Specifying the required argument types (function prototypes): Specifying the required argument types function prototypes. 
* Return types:: 
* Passing pointers (or; passing parameters by reference): Passing pointers or passing parameters by reference. 
* Structures and unions:: 
* Structure/union layout@comma{} alignment and byte order: Structure/union layout alignment and byte order. 
* Bit fields in structures and unions:: 
* Arrays:: 
* Pointers:: 
* Thread safety without the GIL:: 
* Type conversions:: 
* Incomplete Types:: 
* Callback functions:: 
* Accessing values exported from dlls:: 
* Surprises:: 
* Variable-sized data types:: 

ctypes reference

* Loading shared libraries:: 
* Finding shared libraries:: 
* Listing loaded shared libraries:: 
* Foreign functions:: 
* Function prototypes:: 
* Utility functions:: 
* Data types: Data types<2>. 
* Fundamental data types: Fundamental data types<2>. 
* Structured data types:: 
* Arrays and pointers:: 
* Exceptions: Exceptions<9>. 

Command-line interface libraries

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

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

* ArgumentParser objects:: 
* The add_argument() method: The add_argument method. 
* The parse_args() method: The parse_args method. 
* Other utilities:: 
* Exceptions: Exceptions<10>. 

ArgumentParser objects

* prog:: 
* usage:: 
* description:: 
* epilog:: 
* parents:: 
* formatter_class:: 
* prefix_chars:: 
* fromfile_prefix_chars:: 
* argument_default:: 
* allow_abbrev:: 
* conflict_handler:: 
* add_help:: 
* exit_on_error:: 
* suggest_on_error:: 
* color:: 

The add_argument() method

* name or flags:: 
* action:: 
* nargs:: 
* const:: 
* default:: 
* type:: 
* choices:: 
* required:: 
* help:: 
* metavar:: 
* dest:: 
* deprecated:: 
* Action classes:: 

The parse_args() method

* Option value syntax:: 
* Invalid arguments:: 
* Arguments containing -:: 
* Argument abbreviations (prefix matching): Argument abbreviations prefix matching. 
* Beyond sys.argv: Beyond sys argv. 
* The Namespace object:: 

Other utilities

* Subcommands:: 
* FileType objects:: 
* Argument groups:: 
* Mutual exclusion:: 
* Parser defaults:: 
* Printing help:: 
* Partial parsing:: 
* Customizing file parsing:: 
* Exiting methods:: 
* Intermixed parsing:: 
* Registering custom types or actions:: 

Exceptions

* Argparse Tutorial:: 
* Migrating optparse code to argparse:: 

Argparse Tutorial

* Concepts:: 
* The basics:: 
* Introducing Positional arguments:: 
* Introducing Optional arguments:: 
* Combining Positional and Optional arguments:: 
* Getting a little more advanced:: 
* How to translate the argparse output:: 
* Custom type converters:: 
* Conclusion:: 

Introducing Optional arguments

* Short options:: 

Getting a little more advanced

* Specifying ambiguous arguments:: 
* Conflicting options:: 

optparse — Parser for command line options

* Choosing an argument parsing library:: 
* Introduction: Introduction<5>. 
* Background:: 
* Tutorial: Tutorial<2>. 
* Reference Guide:: 
* Option Callbacks:: 
* Extending optparse:: 
* Exceptions: Exceptions<11>. 

Background

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

Tutorial

* Understanding option actions:: 
* The store action:: 
* Handling boolean (flag) options: Handling boolean flag options. 
* Other actions:: 
* Default values:: 
* 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:: 
* Parsing arguments:: 
* Querying and manipulating your option parser:: 
* Conflicts between options:: 
* Cleanup:: 
* 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

* Functions: Functions<4>. 
* Window Objects:: 
* Constants: Constants<6>. 

curses.textpad — Text input widget for curses programs

* Textbox objects:: 

curses.panel — A panel stack extension for curses

* Functions: Functions<5>. 
* Panel Objects:: 

cmd — Support for line-oriented command interpreters

* Cmd Objects:: 
* Cmd Example:: 

Concurrent Execution

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

threading — Thread-based parallelism

* Introduction: Introduction<6>. 
* GIL and performance considerations:: 
* Reference: Reference<2>. 
* Using locks@comma{} conditions@comma{} and semaphores in the with statement: Using locks conditions and semaphores in the with statement. 
* Iterator synchronization:: 

Reference

* Thread-local data:: 
* Thread objects:: 
* Lock objects:: 
* RLock objects:: 
* Condition objects:: 
* Semaphore objects:: 
* Semaphore example:: 
* Event objects:: 
* Timer objects:: 
* Barrier objects:: 

multiprocessing — Process-based parallelism

* Introduction: Introduction<7>. 
* Reference: Reference<3>. 
* Programming guidelines:: 
* Examples: Examples<12>. 

Introduction

* The Process class:: 
* Contexts and start methods:: 
* Exchanging objects between processes:: 
* Synchronization between processes:: 
* Sharing state between processes:: 
* Using a pool of workers:: 

Reference

* Global start method:: 
* Process and exceptions:: 
* Pipes and Queues:: 
* Miscellaneous: Miscellaneous<3>. 
* Connection Objects:: 
* Synchronization primitives:: 
* Shared ctypes Objects:: 
* Managers:: 
* Proxy Objects:: 
* Process Pools:: 
* Listeners and Clients:: 
* Authentication keys:: 
* Logging: Logging<2>. 
* The multiprocessing.dummy module: The multiprocessing dummy module. 

Shared ctypes Objects

* The multiprocessing.sharedctypes module: The multiprocessing sharedctypes module. 

Managers

* Customized managers:: 
* Using a remote manager:: 

Proxy Objects

* Cleanup: Cleanup<2>. 

Listeners and Clients

* Address Formats:: 

Programming guidelines

* All start methods:: 
* The spawn and forkserver start methods:: 

concurrent.futures — Launching parallel tasks

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

ThreadPoolExecutor

* ThreadPoolExecutor Example:: 

ProcessPoolExecutor

* ProcessPoolExecutor Example:: 

concurrent.interpreters — Multiple interpreters in the same process

* Key details:: 
* Introduction: Introduction<8>. 
* Reference: Reference<4>. 
* Basic usage:: 

Introduction

* Multiple Interpreters and Isolation:: 
* Running in an Interpreter:: 
* Concurrency and Parallelism:: 
* Communication Between Interpreters:: 
* «Sharing» Objects:: 

Reference

* Interpreter objects:: 
* Exceptions: Exceptions<12>. 
* Communicating Between Interpreters:: 

subprocess — Subprocess management

* Using the subprocess Module:: 
* Security Considerations:: 
* Popen Objects:: 
* Windows Popen Helpers:: 
* Older high-level API:: 
* Replacing Older Functions with the subprocess Module:: 
* Legacy Shell Invocation Functions:: 
* Notes: Notes<2>. 

Using the subprocess Module

* Frequently Used Arguments:: 
* Popen Constructor:: 
* Exceptions: Exceptions<13>. 

Windows Popen Helpers

* Windows Constants:: 

Replacing Older Functions with the subprocess Module

* Replacing /bin/sh shell command substitution:: 
* Replacing shell pipeline:: 
* Replacing os.system(): Replacing os system. 
* Replacing the os.spawn family: Replacing the os spawn family. 
* Replacing os.popen(): Replacing os popen. 

Notes

* Timeout Behavior:: 
* Converting an argument sequence to a string on Windows:: 
* Disable use of posix_spawn(): Disable use of posix_spawn. 

sched — Event scheduler

* Scheduler Objects:: 

queue — A synchronized queue class

* Queue Objects:: 
* SimpleQueue Objects:: 

Queue Objects

* Waiting for task completion:: 
* Terminating queues:: 

contextvars — Context Variables

* Context Variables:: 
* Manual Context Management:: 
* asyncio support:: 

Networking and Interprocess Communication

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

asyncio — Asynchronous I/O

* Runners:: 
* Coroutines and tasks:: 
* Streams:: 
* Synchronization Primitives:: 
* Subprocesses:: 
* Ουρές:: 
* Exceptions: Exceptions<14>. 
* Call Graph Introspection:: 
* Event loop:: 
* Futures:: 
* Transports and Protocols:: 
* Policies:: 
* Platform Support:: 
* Extending:: 
* High-level API Index:: 
* Low-level API Index:: 
* Developing with asyncio:: 

Runners

* Running an asyncio Program:: 
* Runner context manager:: 
* Handling Keyboard Interruption:: 

Coroutines and tasks

* Coroutines: Coroutines<3>. 
* Awaitables:: 
* Creating tasks:: 
* Task cancellation:: 
* Task groups:: 
* Sleeping:: 
* Running tasks concurrently:: 
* Eager task factory:: 
* Shielding from cancellation:: 
* Timeouts:: 
* Waiting primitives:: 
* Running in threads:: 
* Scheduling from other threads:: 
* Introspection:: 
* Task object:: 

Streams

* StreamReader:: 
* StreamWriter:: 
* Examples: Examples<13>. 

Examples

* TCP echo client using streams:: 
* TCP echo server using streams:: 
* Get HTTP headers:: 
* Register an open socket to wait for data using streams:: 

Synchronization Primitives

* Lock:: 
* Event:: 
* Condition:: 
* Semaphore:: 
* BoundedSemaphore:: 
* Barrier:: 

Subprocesses

* Creating Subprocesses:: 
* Constants: Constants<7>. 
* Interacting with Subprocesses:: 

Interacting with Subprocesses

* Subprocess and Threads:: 
* Examples: Examples<14>. 

Ουρές

* Ουρά:: 
* Σειρά Προτεραιότητας:: 
* Ουρά LIFO:: 
* Εξαιρέσεις: Εξαιρέσεις<2>. 
* Παραδείγματα: Παραδείγματα<4>. 

Call Graph Introspection

* Low level utility functions:: 

Event loop

* Event loop methods:: 
* Callback handles:: 
* Server objects:: 
* Event loop implementations:: 
* Examples: Examples<15>. 

Event loop methods

* Running and stopping the loop:: 
* Scheduling callbacks:: 
* Scheduling delayed callbacks:: 
* Creating futures and tasks:: 
* Opening network connections:: 
* Creating network servers:: 
* Transferring files:: 
* TLS upgrade:: 
* Watching file descriptors:: 
* Working with socket objects directly:: 
* DNS:: 
* Working with pipes:: 
* Unix signals:: 
* Executing code in thread or process pools:: 
* Error handling API:: 
* Enabling debug mode:: 
* Running subprocesses:: 

Examples

* Hello World with call_soon(): Hello World with call_soon. 
* Display the current date with call_later(): Display the current date with call_later. 
* Watch a file descriptor for read events:: 
* Set signal handlers for SIGINT and SIGTERM:: 

Futures

* Future Functions:: 
* Future Object:: 

Transports and Protocols

* Transports:: 
* Protocols: Protocols<2>. 
* Examples: Examples<16>. 

Transports

* Transports Hierarchy:: 
* Base Transport:: 
* Read-only Transports:: 
* Write-only Transports:: 
* Datagram Transports:: 
* Subprocess Transports:: 

Protocols

* Base Protocols:: 
* Base Protocol:: 
* Streaming Protocols:: 
* Buffered Streaming Protocols:: 
* Datagram Protocols:: 
* Subprocess Protocols:: 

Examples

* TCP Echo Server:: 
* TCP Echo Client:: 
* UDP Echo Server:: 
* UDP Echo Client:: 
* Connecting Existing Sockets:: 
* loop.subprocess_exec() and SubprocessProtocol: loop subprocess_exec and SubprocessProtocol. 

Policies

* Getting and Setting the Policy:: 
* Policy Objects:: 
* Custom Policies:: 

Platform Support

* All Platforms:: 
* Windows: Windows<83>. 
* macOS: macOS<53>. 

Windows

* Subprocess Support on Windows:: 

Extending

* Writing a Custom Event Loop:: 
* Future and Task private constructors:: 
* Task lifetime support:: 

High-level API Index

* Tasks:: 
* Queues:: 
* Subprocesses: Subprocesses<2>. 
* Streams: Streams<2>. 
* Synchronization:: 
* Exceptions: Exceptions<15>. 

Low-level API Index

* Obtaining the Event Loop:: 
* Event Loop Methods:: 
* Transports: Transports<2>. 
* Protocols: Protocols<3>. 
* Event Loop Policies:: 

Developing with asyncio

* Debug Mode:: 
* Concurrency and Multithreading:: 
* Running Blocking Code:: 
* Logging: Logging<3>. 
* Detect never-awaited coroutines:: 
* Detect never-retrieved exceptions:: 
* Asynchronous generators best practices:: 

Asynchronous generators best practices

* Close asynchronous generators explicitly:: 
* Create asynchronous generators only when the event loop is running:: 
* Avoid concurrent iteration and closure of the same generator:: 

socket — Low-level networking interface

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

Module contents

* Exceptions: Exceptions<16>. 
* Constants: Constants<8>. 
* Functions: Functions<6>. 

Functions

* Creating sockets:: 
* Other functions: Other functions<2>. 

Notes on socket timeouts

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

ssl — TLS/SSL wrapper for socket objects

* Functions@comma{} constants@comma{} and exceptions: Functions constants and exceptions. 
* SSL sockets:: 
* SSL contexts:: 
* Certificates:: 
* Examples: Examples<17>. 
* Notes on non-blocking sockets:: 
* Memory BIO support:: 
* SSL session:: 
* Security considerations: Security considerations<2>. 
* TLS 1.3: TLS 1 3. 

Functions, constants, and exceptions

* Socket creation:: 
* Context creation:: 
* Signature algorithms:: 
* Exceptions: Exceptions<17>. 
* Random generation:: 
* Certificate handling:: 
* Constants: Constants<9>. 

Certificates

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

Examples

* 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:: 
* Examples: Examples<18>. 

signal — Set handlers for asynchronous events

* General rules:: 
* Module contents: Module contents<4>. 
* Examples: Examples<19>. 
* 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:: 
* MS_* Constants:: 

Internet Data Handling

* email — An email and MIME handling package:: 
* json — JSON encoder and decoder:: 
* mailbox — Manipulate mailboxes in various formats:: 
* mimetypes — Map filenames to MIME types:: 
* base64 — Base16@comma{} Base32@comma{} Base64@comma{} Base85 Data Encodings: base64 — Base16 Base32 Base64 Base85 Data Encodings. 
* binascii — Convert between binary and ASCII:: 
* quopri — 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; Κλάσεις Εξαιρέσεων και Ελαττωμάτων: email errors Κλάσεις Εξαιρέσεων και Ελαττωμάτων. 
* email.headerregistry; Custom Header Objects: email headerregistry Custom Header Objects. 
* email.contentmanager; Managing MIME Content: email contentmanager Managing MIME Content. 
* email; Examples: email Examples. 
* email.message.Message; Representing an email message using the compat32 API: email message Message Representing an email message using the compat32 API. 
* 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; Αναπαράσταση συνόλων χαρακτήρων: email charset Αναπαράσταση συνόλων χαρακτήρων. 
* 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

* FeedParser API:: 
* Parser API:: 
* Additional notes:: 

email.contentmanager: Managing MIME Content

* Content Manager Instances:: 

json — JSON encoder and decoder

* Basic Usage:: 
* Encoders and Decoders:: 
* Exceptions: Exceptions<18>. 
* Standard Compliance and Interoperability:: 
* Command-line interface: Command-line interface<4>. 

Standard Compliance and Interoperability

* Character Encodings:: 
* Infinite and NaN Number Values:: 
* Repeated Names Within an Object:: 
* Top-level Non-Object@comma{} Non-Array Values: Top-level Non-Object Non-Array Values. 
* Implementation Limitations:: 

Command-line interface

* Command-line options: Command-line options<3>. 

mailbox — Manipulate mailboxes in various formats

* Mailbox objects:: 
* Message objects:: 
* Exceptions: Exceptions<19>. 
* Examples: Examples<20>. 

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:: 
* Command-line usage: Command-line usage<2>. 
* Command-line example:: 

base64 — Base16, Base32, Base64, Base85 Data Encodings

* RFC 4648 Encodings:: 
* Base85 Encodings:: 
* Legacy Interface:: 
* Security Considerations: Security Considerations<2>. 

Structured Markup Processing Tools

* html — HyperText Markup Language support:: 
* html.parser — Simple HTML and XHTML parser: html parser — Simple HTML and XHTML parser. 
* html.entities — Definitions of HTML general entities: html entities — Definitions of HTML general entities. 
* XML Processing Modules:: 
* xml.etree.ElementTree — The ElementTree XML API: xml etree ElementTree — The ElementTree XML API. 
* xml.dom — The Document Object Model API: xml dom — The Document Object Model API. 
* xml.dom.minidom — Minimal DOM implementation: xml dom minidom — Minimal DOM implementation. 
* xml.dom.pulldom — Support for building partial DOM trees: xml dom pulldom — Support for building partial DOM trees. 
* xml.sax — Support for SAX2 parsers: xml sax — Support for SAX2 parsers. 
* xml.sax.handler — Βασικές κλάσεις για χειριστές SAX: xml sax handler — Βασικές κλάσεις για χειριστές SAX. 
* xml.sax.saxutils — SAX Utilities: xml sax saxutils — SAX Utilities. 
* xml.sax.xmlreader — Interface for XML parsers: xml sax xmlreader — Interface for XML parsers. 
* xml.parsers.expat — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat: xml parsers expat — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat. 

html.parser — Simple HTML and XHTML parser

* Example HTML Parser Application:: 
* HTMLParser Methods:: 
* Examples: Examples<21>. 

XML Processing Modules

* XML security:: 

xml.etree.ElementTree — The ElementTree XML API

* Tutorial: Tutorial<3>. 
* XPath support:: 
* Reference: Reference<5>. 
* XInclude support:: 
* Reference: Reference<6>. 

Tutorial

* XML tree and elements:: 
* Parsing XML:: 
* Pull API for non-blocking parsing:: 
* Finding interesting elements:: 
* Modifying an XML File:: 
* Building XML documents:: 
* Parsing XML with Namespaces:: 

XPath support

* Example: Example<8>. 
* Supported XPath syntax:: 

Reference

* Functions: Functions<7>. 

XInclude support

* Example: Example<9>. 

Reference

* Functions: Functions<8>. 
* Element Objects:: 
* ElementTree Objects:: 
* QName Objects:: 
* TreeBuilder Objects:: 
* XMLParser Objects:: 
* XMLPullParser Objects:: 
* Exceptions: Exceptions<20>. 

xml.dom — The Document Object Model API

* Module Contents:: 
* Objects in the DOM:: 
* Conformance:: 

Objects in the DOM

* DOMImplementation Objects:: 
* Node Objects:: 
* NodeList Objects:: 
* DocumentType Objects:: 
* Document Objects:: 
* Element Objects: Element Objects<2>. 
* Attr Objects:: 
* NamedNodeMap Objects:: 
* Comment Objects:: 
* Text and CDATASection Objects:: 
* ProcessingInstruction Objects:: 
* Exceptions: Exceptions<21>. 

Conformance

* Type Mapping:: 
* Accessor Methods:: 

xml.dom.minidom — Minimal DOM implementation

* DOM Objects:: 
* DOM Example:: 
* minidom and the DOM standard:: 

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

* DOMEventStream Objects:: 

xml.sax — Support for SAX2 parsers

* SAXException Objects:: 

xml.sax.handler — Βασικές κλάσεις για χειριστές SAX

* ContentHandler Αντικείμενα:: 
* DTDHandler Αντικείμενα:: 
* EntityResolver Αντικείμενα:: 
* ErrorHandler Αντικείμενα:: 
* 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 — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat

* Αντικείμενα XMLParser:: 
* Εξαιρέσεις ExpatError:: 
* Παράδειγμα:: 
* Περιγραφές Μοντέλου Περιεχομένου:: 
* Σταθερές σφαλμάτων Expat:: 

Πρωτόκολλα Internet και Υποστήριξη

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

webbrowser — Convenient web-browser controller

* Command-line interface: Command-line interface<5>. 
* Browser controller objects:: 

wsgiref — WSGI Utilities and Reference Implementation

* wsgiref.util – WSGI environment utilities: wsgiref util – WSGI environment utilities. 
* wsgiref.headers – WSGI response header tools: wsgiref headers – WSGI response header tools. 
* wsgiref.simple_server – a simple WSGI HTTP server: wsgiref simple_server – a simple WSGI HTTP server. 
* wsgiref.validate — WSGI conformance checker: wsgiref validate — WSGI conformance checker. 
* wsgiref.handlers – server/gateway base classes: wsgiref handlers – server/gateway base classes. 
* wsgiref.types – WSGI types for static type checking: wsgiref types – WSGI types for static type checking. 
* Examples: Examples<22>. 

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:: 
* Examples: Examples<23>. 
* 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

* HTTP status codes:: 
* HTTP status category:: 
* HTTP methods:: 

http.client — HTTP protocol client

* HTTPConnection Objects:: 
* HTTPResponse Objects:: 
* Examples: Examples<24>. 
* HTTPMessage Objects:: 

ftplib — FTP protocol client

* Reference: Reference<7>. 

Reference

* 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 9562

* Command-Line Usage:: 
* Example: Example<10>. 
* Command-Line Example:: 

socketserver — A framework for network servers

* Server Creation Notes:: 
* Server Objects:: 
* Request Handler Objects:: 
* Examples: Examples<25>. 

Examples

* socketserver.TCPServer Example: socketserver TCPServer Example. 
* socketserver.UDPServer Example: socketserver UDPServer Example. 
* Asynchronous Mixins:: 

http.server — HTTP servers

* Command-line interface: Command-line interface<6>. 
* Security considerations: Security considerations<3>. 

http.cookies — HTTP state management

* Cookie Objects:: 
* Morsel Objects:: 
* Example: Example<11>. 

http.cookiejar — Cookie handling for HTTP clients

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

xmlrpc.client — XML-RPC client access

* ServerProxy Objects:: 
* DateTime Objects:: 
* 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

* Convenience factory functions:: 
* IP Addresses:: 
* IP Network definitions:: 
* Interface objects:: 
* Other Module Level Functions:: 
* Custom Exceptions:: 

IP Addresses

* Address objects:: 
* Conversion to Strings and Integers:: 
* Operators: Operators<2>. 

Operators

* Comparison operators:: 
* Arithmetic operators:: 

IP Network definitions

* Prefix@comma{} net mask and host mask: Prefix net mask and host mask. 
* Network objects:: 
* Operators: Operators<3>. 

Operators

* Logical operators:: 
* Iteration:: 
* Networks as containers of addresses:: 

Interface objects

* Operators: Operators<4>. 

Operators

* Logical operators: Logical operators<2>. 

Multimedia Services

* wave — Read and write WAV files:: 
* colorsys — Μετατροπές μεταξύ συστημάτων χρωμάτων:: 

wave — Read and write WAV files

* Wave_read Objects:: 
* Wave_write Objects:: 

Internationalization

* gettext — Multilingual internationalization services:: 
* locale — Internationalization services:: 

gettext — Multilingual internationalization services

* GNU gettext API:: 
* Class-based API:: 
* Internationalizing your programs and modules:: 
* Acknowledgements: Acknowledgements<9>. 

Class-based API

* The NullTranslations class:: 
* The GNUTranslations class:: 
* Solaris message catalog support:: 
* The Catalog constructor:: 

Internationalizing your programs and modules

* Localizing your module:: 
* Localizing your application:: 
* Changing languages on the fly:: 
* Deferred translations:: 

locale — Internationalization services

* Background@comma{} details@comma{} hints@comma{} tips and caveats: Background details hints tips and caveats. 
* Locale names:: 
* For extension writers and programs that embed Python:: 
* Access to message catalogs:: 

Γραφικές επαφές χρηστών με το Tk

* tkinter — Python interface to Tcl/Tk:: 
* tkinter.colorchooser — Color choosing dialog: tkinter colorchooser — Color choosing dialog. 
* tkinter.font — Tkinter font wrapper: tkinter font — Tkinter font wrapper. 
* Tkinter Dialogs:: 
* tkinter.messagebox — Tkinter message prompts: tkinter messagebox — Tkinter message prompts. 
* tkinter.scrolledtext — Scrolled Text Widget: tkinter scrolledtext — Scrolled Text Widget. 
* tkinter.dnd — Drag and drop support: tkinter dnd — Drag and drop support. 
* tkinter.ttk — Tk themed widgets: tkinter ttk — Tk themed widgets. 
* IDLE — Python editor and shell:: 
* turtle — Turtle graphics:: 

tkinter — Python interface to Tcl/Tk

* Architecture:: 
* Tkinter Modules:: 
* Tkinter Life Preserver:: 
* Threading model:: 
* Handy Reference:: 
* File Handlers:: 

Tkinter Life Preserver

* A Hello World Program:: 
* Important Tk Concepts:: 
* Understanding How Tkinter Wraps Tcl/Tk:: 
* How do I…? What option does…?:: 
* Navigating the Tcl/Tk Reference Manual:: 

Handy Reference

* Setting Options:: 
* The Packer:: 
* Packer Options:: 
* Coupling Widget Variables:: 
* The Window Manager:: 
* Tk Option Data Types:: 
* Bindings and Events:: 
* The index Parameter:: 
* Images:: 

Tkinter Dialogs

* tkinter.simpledialog — Standard Tkinter input dialogs: tkinter simpledialog — Standard Tkinter input dialogs. 
* tkinter.filedialog — File selection dialogs: tkinter filedialog — File selection dialogs. 
* tkinter.commondialog — Dialog window templates: tkinter commondialog — Dialog window templates. 

tkinter.filedialog — File selection dialogs

* Native Load/Save Dialogs:: 

tkinter.ttk — Tk themed widgets

* Using Ttk:: 
* Ttk Widgets:: 
* Widget:: 
* Combobox:: 
* Spinbox:: 
* Notebook:: 
* Progressbar:: 
* Separator:: 
* Sizegrip:: 
* Treeview:: 
* Ttk Styling:: 

Widget

* Standard Options:: 
* Scrollable Widget Options:: 
* Label Options:: 
* Compatibility Options:: 
* Widget States:: 
* ttk.Widget: ttk Widget. 

Combobox

* Options:: 
* Virtual events:: 
* ttk.Combobox: ttk Combobox. 

Spinbox

* Options: Options<2>. 
* Virtual events: Virtual events<2>. 
* ttk.Spinbox: ttk Spinbox. 

Notebook

* Options: Options<3>. 
* Tab Options:: 
* Tab Identifiers:: 
* Virtual Events:: 
* ttk.Notebook: ttk Notebook. 

Progressbar

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

Separator

* Options: Options<5>. 

Sizegrip

* Platform-specific notes:: 
* Bugs:: 

Treeview

* Options: Options<6>. 
* Item Options:: 
* Tag Options:: 
* Column Identifiers:: 
* Virtual Events: Virtual Events<2>. 
* ttk.Treeview: ttk Treeview. 

Ttk Styling

* Layouts:: 

IDLE — Python editor and shell

* Menus:: 
* Editing and Navigation:: 
* Startup and Code Execution:: 
* Help and Preferences:: 
* idlelib — implementation of IDLE application:: 

Menus

* File menu (Shell and Editor): File menu Shell and Editor. 
* Edit menu (Shell and Editor): Edit menu Shell and Editor. 
* Format menu (Editor window only): Format menu Editor window only. 
* Run menu (Editor window only): Run menu Editor window only. 
* Shell menu (Shell window only): Shell menu Shell window only. 
* Debug menu (Shell window only): Debug menu Shell window only. 
* Options menu (Shell and Editor): Options menu Shell and Editor. 
* Window menu (Shell and Editor): Window menu Shell and Editor. 
* Help menu (Shell and Editor): Help menu Shell and Editor. 
* Context menus:: 

Editing and Navigation

* Editor windows:: 
* Key bindings:: 
* Automatic indentation:: 
* Search and Replace:: 
* Completions:: 
* Calltips:: 
* Format block:: 
* Code Context:: 
* Shell window:: 
* Text colors:: 

Startup and Code Execution

* Command-line usage: Command-line usage<3>. 
* Startup failure:: 
* Running user code:: 
* User output in Shell:: 
* Developing tkinter applications:: 
* Running without a subprocess:: 

Help and Preferences

* Help sources:: 
* Setting preferences:: 
* IDLE on macOS:: 
* Extensions:: 

turtle — Turtle graphics

* Introduction: Introduction<10>. 
* Get started:: 
* Tutorial: Tutorial<4>. 
* How to…:: 
* Turtle graphics reference:: 
* Methods of RawTurtle/Turtle and corresponding functions:: 
* Methods of TurtleScreen/Screen and corresponding functions:: 
* Public classes:: 
* Explanation: Explanation<2>. 
* Help and configuration:: 
* turtledemo — Demo scripts:: 
* Changes since Python 2.6: Changes since Python 2 6. 
* Changes since Python 3.0: Changes since Python 3 0. 

Tutorial

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

Basic drawing

* Pen control:: 
* The turtle’s position:: 

How to…

* Get started as quickly as possible:: 
* Automatically begin and end filling:: 
* Use the turtle module namespace:: 
* Use turtle graphics in a script:: 
* Use object-oriented turtle graphics:: 

Turtle graphics reference

* Turtle methods:: 
* Methods of TurtleScreen/Screen:: 

Methods of RawTurtle/Turtle and corresponding functions

* Turtle motion:: 
* Tell Turtle’s state:: 
* Settings for measurement:: 
* Pen control: Pen control<2>. 
* Turtle state:: 
* Using events:: 
* Special Turtle methods:: 
* Compound shapes:: 

Pen control

* Drawing state:: 
* Color control:: 
* Filling:: 
* More drawing control:: 

Turtle state

* Visibility:: 
* Appearance:: 

Methods of TurtleScreen/Screen and corresponding functions

* Window control:: 
* Animation control:: 
* Using screen events:: 
* Input methods:: 
* Settings and special methods:: 
* Methods specific to Screen@comma{} not inherited from TurtleScreen: Methods specific to Screen not inherited from TurtleScreen. 

Help and configuration

* How to use help:: 
* Translation of docstrings into different languages:: 
* How to configure Screen and Turtles:: 

Εργαλεία Ανάπτυξης

* typing — Support for type hints:: 
* pydoc — Documentation generator and online help system:: 
* Python Development Mode:: 
* doctest — Test interactive Python examples:: 
* unittest — Unit testing framework:: 
* unittest.mock — mock object library: unittest mock — mock object library. 
* unittest.mock — ξεκινώντας: unittest mock — ξεκινώντας. 
* test — Regression tests package for Python:: 
* test.support — Utilities for the Python test suite: test support — Utilities for the Python test suite. 
* test.support.socket_helper — Utilities for socket tests: test support socket_helper — Utilities for socket tests. 
* test.support.script_helper — Utilities for the Python execution tests: test support script_helper — Utilities for the Python execution tests. 
* test.support.bytecode_helper — Support tools for testing correct bytecode generation: test support bytecode_helper — Support tools for testing correct bytecode generation. 
* test.support.threading_helper — Utilities for threading tests: test support threading_helper — Utilities for threading tests. 
* test.support.os_helper — Utilities for os tests: test support os_helper — Utilities for os tests. 
* test.support.import_helper — Utilities for import tests: test support import_helper — Utilities for import tests. 
* test.support.warnings_helper — Utilities for warnings tests: test support warnings_helper — Utilities for warnings tests. 

typing — Support for type hints

* Specification for the Python Type System:: 
* Type aliases:: 
* NewType:: 
* Annotating callable objects:: 
* Generics:: 
* Annotating tuples:: 
* The type of class objects:: 
* Annotating generators and coroutines:: 
* User-defined generic types:: 
* The Any type:: 
* Nominal vs structural subtyping:: 
* Module contents: Module contents<5>. 
* Deprecation Timeline of Major Features:: 

Module contents

* Special typing primitives:: 
* Protocols: Protocols<4>. 
* ABCs and Protocols for working with I/O:: 
* Functions and decorators:: 
* Introspection helpers:: 
* Constant:: 
* 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 — Test interactive Python examples

* Simple Usage; Checking Examples in Docstrings: Simple Usage Checking Examples in Docstrings. 
* Simple Usage; Checking Examples in a Text File: Simple Usage Checking Examples in a Text File. 
* Command-line Usage:: 
* How It Works:: 
* Basic API:: 
* Unittest API:: 
* Advanced API:: 
* Debugging:: 
* Soapbox:: 

How It Works

* Which Docstrings Are Examined?:: 
* How are Docstring Examples Recognized?:: 
* What’s the Execution Context?:: 
* What About Exceptions?:: 
* Option Flags:: 
* Directives:: 
* Warnings: Warnings<2>. 

Advanced API

* DocTest Objects:: 
* Example Objects:: 
* DocTestFinder objects:: 
* DocTestParser objects:: 
* TestResults objects:: 
* DocTestRunner objects:: 
* OutputChecker objects:: 

unittest — Unit testing framework

* Basic example:: 
* Command-Line Interface: Command-Line Interface<2>. 
* Test Discovery:: 
* Organizing test code:: 
* Re-using old test code:: 
* Skipping tests and expected failures:: 
* Distinguishing test iterations using subtests:: 
* Classes and functions:: 
* Class and Module Fixtures:: 
* Signal Handling:: 

Command-Line Interface

* Command-line options: Command-line options<4>. 

Classes and functions

* Test cases:: 
* Grouping tests:: 
* Loading and running tests:: 

Loading and running tests

* load_tests Protocol:: 

Class and Module Fixtures

* setUpClass and tearDownClass:: 
* setUpModule and tearDownModule:: 

unittest.mock — mock object library

* Quick Guide:: 
* The Mock Class:: 
* 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. 

The Mock Class

* 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:: 
* call:: 
* create_autospec:: 
* ANY:: 
* FILTER_DIR:: 
* mock_open:: 
* Autospeccing:: 
* Sealing mocks:: 

unittest.mock — ξεκινώντας

* Χρήση της Προσομοίωσης (Mock): Χρήση της Προσομοίωσης Mock. 
* Patch decorators:: 
* Further examples:: 

Χρήση της Προσομοίωσης (Mock)

* Mock patching methods:: 
* Mock for method calls on an object:: 
* Mocking classes:: 
* Ονομασία των προσομοιώσεών σας:: 
* Tracking all calls:: 
* Setting return values and attributes:: 
* Πρόκληση εξαιρέσεων με προσομοιώσεις:: 
* Συναρτήσεις παρενέργειας και iterables:: 
* Προσομοίωση ασύγχρονων επαναληπτών:: 
* Προσομοίωση ασύγχρονου διαχειριστή περιεχομένου:: 
* Creating a mock from an existing object:: 
* Χρήση του side_effect για επιστροφή περιεχομένου ανά αρχείο:: 

Further examples

* Προσομοίωση αλυσιδωτών κλήσεων:: 
* Μερική προσομοίωση:: 
* Mocking a generator method:: 
* Εφαρμογή της ίδιας επιδιόρθωσης σε κάθε μέθοδο δοκιμής:: 
* Mocking unbound methods:: 
* Έλεγχος πολλαπλών κλήσεων με προσομοίωση:: 
* Αντιμετώπιση μεταβλητών ορισμάτων:: 
* Nesting patches:: 
* Προσομοίωση ενός λεξικού με το MagicMock:: 
* Υποκλάσεις Mock και τα χαρακτηριστικά τους:: 
* Προσομοίωση εισαγωγών με το patch.dict: Προσομοίωση εισαγωγών με το patch dict. 
* Παρακολούθηση της σειράς κλήσεων και λιγότερο λεκτικές δηλώσεις κλήσεων:: 
* Πιο σύνθετη αντιστοίχιση ορισμάτων:: 

test — Regression tests package for Python

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

Debugging and profiling

* Audit events table:: 
* bdb — Debugger framework:: 
* faulthandler — Dump the Python traceback:: 
* pdb — The Python Debugger:: 
* profiling — Python profilers:: 
* pstats — Statistics for profilers:: 
* timeit — Μέτρηση χρόνου εκτέλεσης μικρών αποσπασμάτων κώδικα:: 
* trace — Ιχνηλάτηση ή παρακολούθηση εκτέλεσης εντολών Python:: 
* tracemalloc — Trace memory allocations:: 

faulthandler — Dump the Python traceback

* Dumping the traceback:: 
* Dumping the C stack:: 
* Fault handler state:: 
* Dumping the tracebacks after a timeout:: 
* Dumping the traceback on a user signal:: 
* Issue with file descriptors:: 
* Example: Example<12>. 

Dumping the C stack

* C Stack Compatibility:: 

pdb — The Python Debugger

* Command-line interface: Command-line interface<7>. 
* Debugger commands:: 

profiling — Python profilers

* Introduction to profiling:: 
* Choosing a profiler:: 
* Quick start:: 
* Understanding profile output:: 
* Legacy compatibility:: 

Choosing a profiler

* When to use statistical sampling:: 
* When to use deterministic tracing:: 

Quick start

* Statistical profiling:: 
* Deterministic profiling:: 

Legacy compatibility

* profiling.tracing — Deterministic profiler: profiling tracing — Deterministic profiler. 
* profiling.sampling — Statistical profiler: profiling sampling — Statistical profiler. 

profiling.tracing — Deterministic profiler

* What is deterministic profiling?:: 
* Command-line interface: Command-line interface<8>. 
* Programmatic usage examples:: 
* Module reference:: 
* Using a custom timer:: 
* Limitations:: 

Programmatic usage examples

* Basic profiling:: 
* Using the Profile class:: 

profiling.sampling — Statistical profiler

* What is statistical profiling?:: 
* Quick examples:: 
* Commands:: 
* Sampling configuration:: 
* Profiling modes:: 
* Output formats:: 
* Record and replay workflow:: 
* Live mode:: 
* Async-aware profiling:: 
* Command-line interface: Command-line interface<9>. 

What is statistical profiling?

* How time is estimated:: 
* When to use a different approach:: 

Commands

* The run command:: 
* The attach command:: 
* The dump command:: 
* The replay command:: 
* Profiling in production:: 
* Platform requirements:: 
* Version compatibility:: 

Sampling configuration

* Sampling rate and duration:: 
* Thread selection:: 
* Blocking mode:: 
* Special frames:: 
* Opcode-aware profiling:: 
* Real-time statistics:: 
* Subprocess profiling:: 
* Sampling efficiency:: 

Profiling modes

* Wall-clock mode:: 
* CPU mode:: 
* Comparing wall-clock and CPU profiles:: 
* GIL mode:: 
* Exception mode:: 

Output formats

* pstats format:: 
* Collapsed stacks format:: 
* Flame graph format:: 
* Gecko format:: 
* Heatmap format:: 
* Binary format:: 

Flame graph format

* Differential flame graphs:: 

Live mode

* Keyboard commands:: 

Async-aware profiling

* Async modes:: 
* Task markers and stack reconstruction:: 
* Option restrictions:: 

Command-line interface

* Global options:: 
* Dump options:: 
* Sampling options:: 
* Mode options:: 
* Output options:: 
* pstats display options:: 
* Run command options:: 

pstats — Statistics for profilers

* Reading and displaying profile data:: 
* The Stats class:: 
* Command-line interface: Command-line interface<10>. 

Reading and displaying profile data

* Working with statistics:: 
* Filtering output:: 
* Analyzing call relationships:: 
* Combining multiple profiles:: 

timeit — Μέτρηση χρόνου εκτέλεσης μικρών αποσπασμάτων κώδικα

* Basic examples:: 
* Python interface:: 
* Command-line interface: Command-line interface<11>. 
* Παραδείγματα: Παραδείγματα<5>. 

trace — Ιχνηλάτηση ή παρακολούθηση εκτέλεσης εντολών Python

* Οδηγίες χρήσης γραμμής εντολών:: 
* Προγραμματιστική διεπαφή:: 

Οδηγίες χρήσης γραμμής εντολών

* Κύριες επιλογές:: 
* Τροποποιητές:: 
* Φίλτρα:: 

tracemalloc — Trace memory allocations

* Examples: Examples<27>. 
* API:: 

Examples

* 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

* Functions: Functions<9>. 
* DomainFilter:: 
* Filter:: 
* Frame:: 
* Snapshot:: 
* Statistic:: 
* StatisticDiff:: 
* Trace:: 
* Traceback:: 

Software Packaging and Distribution

* ensurepip — Bootstrapping the pip installer:: 
* venv — Creation of virtual environments:: 
* zipapp — Διαχείριση εκτελέσιμων αρχείων zip Python:: 

ensurepip — Bootstrapping the pip installer

* Command-line interface: Command-line interface<12>. 
* Module API:: 

venv — Creation of virtual environments

* Creating virtual environments:: 
* How venvs work:: 
* API: API<2>. 
* An example of extending EnvBuilder:: 

zipapp — Διαχείριση εκτελέσιμων αρχείων zip Python

* Βασικό Παράδειγμα:: 
* Διεπαφή Γραμμής Εντολών: Διεπαφή Γραμμής Εντολών<2>. 
* Διεπαφή Python:: 
* Παραδείγματα: Παραδείγματα<6>. 
* Καθορισμός του Διερμηνέα:: 
* Δημιουργία Αυτόνομων Εφαρμογών με το zipapp:: 
* Η Μορφή Αρχείου Εφαρμογής Zip της Python:: 

Δημιουργία Αυτόνομων Εφαρμογών με το zipapp

* Προειδοποιήσεις:: 

Python Runtime Services

* sys — System-specific parameters and functions:: 
* sys.monitoring — Execution event monitoring: sys monitoring — Execution event monitoring. 
* sysconfig — Provide access to Python’s configuration information:: 
* builtins — Built-in objects:: 
* __main__ — Top-level code environment:: 
* warnings — Έλεγχος προειδοποιήσεων:: 
* dataclasses — Data Classes:: 
* contextlib — Utilities for with-statement contexts:: 
* abc — Abstract Base Classes:: 
* atexit — Exit handlers:: 
* traceback — Print or retrieve a stack traceback:: 
* __future__ — Future statement definitions:: 
* gc — Garbage Collector interface:: 
* inspect — Inspect live objects:: 
* annotationlib — Functionality for introspecting annotations:: 
* site — 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:: 
* Deprecated event:: 
* 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:: 
* Other functions: Other functions<3>. 
* Command-line usage: Command-line usage<4>. 

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__':: 
* __main__.py in Python Packages: __main__ py in Python Packages. 
* import __main__:: 

__name__ == '__main__'

* What is the «top-level code environment»?:: 
* Idiomatic Usage:: 
* Packaging Considerations:: 

__main__.py in Python Packages

* Idiomatic Usage: Idiomatic Usage<2>. 

warnings — Έλεγχος προειδοποιήσεων

* Κατηγορίες Προειδοποίησης:: 
* Το Φίλτρο Προειδοποιήσεων:: 
* Προσωρινή Καταστολή Προειδοποιήσεων:: 
* Δοκιμή Προειδοποιήσεων:: 
* Ενημέρωση κώδικα για νέες εκδόσεις εξαρτήσεων:: 
* Διαθέσιμες λειτουργίες:: 
* Διαθέσιμοι Context Managers:: 
* Συγχρονισμένη ασφάλεια των Context Managers:: 

Το Φίλτρο Προειδοποιήσεων

* Κριτήρια Καταστολής Επαναλαμβανόμενων Προειδοποιήσεων:: 
* Περιγραφή Φίλτρων Προειδοποιήσεων:: 
* Προεπιλεγμένο φίλτρο προειδοποιήσεων:: 
* Αντικατάσταση του προεπιλεγμένου φίλτρου:: 

dataclasses — Data Classes

* Module contents: Module contents<6>. 
* Post-init processing:: 
* Class variables:: 
* Init-only variables:: 
* Frozen instances:: 
* Inheritance:: 
* Re-ordering of keyword-only parameters in __init__(): Re-ordering of keyword-only parameters in __init__. 
* Default factory functions:: 
* Mutable default values:: 
* Descriptor-typed fields:: 

contextlib — Utilities for with-statement contexts

* Utilities:: 
* Examples and Recipes: Examples and Recipes<2>. 
* Single use@comma{} reusable and reentrant context managers: Single use reusable and reentrant context managers. 

Examples and Recipes

* Supporting a variable number of context managers:: 
* Catching exceptions from __enter__ methods:: 
* Cleaning up in an __enter__ implementation:: 
* Replacing any use of try-finally and flag variables:: 
* Using a context manager as a function decorator:: 

Single use, reusable and reentrant context managers

* Reentrant context managers:: 
* Reusable context managers:: 

atexit — Exit handlers

* atexit Example:: 

traceback — Print or retrieve a stack traceback

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

__future__ — Future statement definitions

* Module Contents: Module Contents<2>. 

inspect — Inspect live objects

* Types and members:: 
* Retrieving source code:: 
* Introspecting callables with the Signature object:: 
* Classes and functions: Classes and functions<2>. 
* The interpreter stack:: 
* Fetching attributes statically:: 
* Current State of Generators@comma{} Coroutines@comma{} and Asynchronous Generators: Current State of Generators Coroutines and Asynchronous Generators. 
* Code Objects Bit Flags:: 
* Buffer flags:: 
* Command-line interface: Command-line interface<13>. 

annotationlib — Functionality for introspecting annotations

* Annotation semantics:: 
* Classes: Classes<2>. 
* Functions: Functions<10>. 
* Recipes: Recipes<2>. 
* Limitations of the STRING format:: 
* Limitations of the FORWARDREF format:: 
* Security implications of introspecting annotations:: 

Recipes

* Using annotations in a metaclass:: 
* Creating a custom callable annotate function:: 

site — Site-specific configuration hook

* Path extensions (.pth files): Path extensions pth files. 
* Startup entry points (.start files): Startup entry points start files. 
* Startup file examples:: 
* Migrating from import lines in .pth files to .start files: Migrating from import lines in pth files to start files. 
* sitecustomize:: 
* usercustomize:: 
* Readline configuration:: 
* Module contents: Module contents<7>. 
* Command-line interface: Command-line interface<14>. 

Custom Python Interpreters

* code — Interpreter base classes:: 
* codeop — Compile Python code:: 

code — Interpreter base classes

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

Importing Modules

* zipimport — Import modules from Zip archives:: 
* pkgutil — Package extension utility:: 
* modulefinder — Find modules used by a script:: 
* runpy — Locating and executing Python modules:: 
* importlib — The implementation of import:: 
* importlib.resources – Ανάγνωση@comma{} άνοιγμα και πρόσβαση σε πόρους πακέτων: importlib resources – Ανάγνωση άνοιγμα και πρόσβαση σε πόρους πακέτων. 
* importlib.resources.abc – Abstract base classes for resources: importlib resources abc – Abstract base classes for resources. 
* importlib.metadata – Accessing package metadata: importlib 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

* zipimporter Objects:: 
* Examples: Examples<28>. 

modulefinder — Find modules used by a script

* Example usage of ModuleFinder:: 

importlib — The implementation of import

* Introduction: Introduction<11>. 
* Functions: Functions<11>. 
* importlib.abc – Abstract base classes related to import: importlib abc – Abstract base classes related to import. 
* importlib.machinery – Importers and path hooks: importlib machinery – Importers and path hooks. 
* importlib.util – Utility code for importers: importlib util – Utility code for importers. 
* Examples: Examples<29>. 

Examples

* 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 – Ανάγνωση, άνοιγμα και πρόσβαση σε πόρους πακέτων

* Λειτουργικό API:: 

importlib.metadata – Accessing package metadata

* Overview: Overview<3>. 
* Functional API:: 
* Distributions:: 
* Distribution Discovery:: 
* Implementing Custom Providers:: 

Functional API

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

Implementing Custom Providers

* Example: Example<13>. 

The initialization of the sys.path module search path

* Virtual Environments:: 
* _pth files:: 
* Embedded Python:: 

Python Language Services

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

ast — Abstract syntax trees

* Abstract grammar:: 
* Node classes:: 
* ast helpers:: 
* Compiler flags: Compiler flags<2>. 
* Command-line usage: Command-line usage<5>. 

Node classes

* Root nodes:: 
* Literals: Literals<2>. 
* Variables:: 
* Expressions: Expressions<2>. 
* Statements:: 
* Control flow:: 
* Pattern matching:: 
* Type annotations:: 
* Type parameters:: 
* Function and class definitions:: 
* Async and await:: 

Expressions

* Subscripting:: 
* Comprehensions:: 

Statements

* Imports:: 

symtable — Access to the compiler’s symbol tables

* Generating Symbol Tables:: 
* Examining Symbol Tables:: 
* Command-Line Usage: Command-Line Usage<2>. 

tokenize — Tokenizer for Python source

* Tokenizing input:: 
* Command-line usage: Command-line usage<6>. 
* Examples: Examples<30>. 

pyclbr — Python module browser support

* Function Objects:: 
* Class Objects:: 

py_compile — Compile Python source files

* Command-Line Interface: Command-Line Interface<3>. 

compileall — Byte-compile Python libraries

* Command-line use:: 
* Public functions:: 

dis — Disassembler for Python bytecode

* Command-line interface: Command-line interface<15>. 
* Bytecode analysis:: 
* Analysis functions:: 
* Python Bytecode Instructions:: 
* Opcode collections:: 

pickletools — Tools for pickle developers

* Command-line usage: Command-line usage<7>. 
* Programmatic interface:: 

Command-line usage

* Command-line options: Command-line options<5>. 

MS Windows Specific Services

* msvcrt — Useful routines from the MS VC++ runtime:: 
* winreg — Windows registry access:: 
* winsound — Διεπαφή αναπαραγωγής ήχου για Windows:: 

msvcrt — Useful routines from the MS VC++ runtime

* File Operations:: 
* Console I/O:: 
* Other Functions:: 

winreg — Windows registry access

* Functions: Functions<12>. 
* Constants: Constants<10>. 
* Registry Handle Objects:: 

Constants

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

Access Rights

* 64-bit Specific:: 

winsound — Διεπαφή αναπαραγωγής ήχου για Windows

* Functions: Functions<13>. 
* Constants: Constants<11>. 

Unix-specific services

* shlex — Simple lexical analysis:: 
* posix — The most common POSIX system calls:: 
* pwd — Η βάση δεδομένων κωδικών πρόσβασης:: 
* grp — The group database:: 
* termios — POSIX style tty control:: 
* tty — Terminal control functions:: 
* pty — Βοηθητικά προγράμματα ψευδοτερματικού:: 
* fcntl — The fcntl and ioctl system calls:: 
* resource — Resource usage information:: 
* syslog — Unix syslog library routines:: 

shlex — Simple lexical analysis

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

posix — The most common POSIX system calls

* Large File Support:: 
* Notable Module Contents:: 

termios — POSIX style tty control

* Example: Example<14>. 

pty — Βοηθητικά προγράμματα ψευδοτερματικού

* Παράδειγμα: Παράδειγμα<2>. 

resource — Resource usage information

* Resource Limits:: 
* Resource Usage:: 

syslog — Unix syslog library routines

* Examples: Examples<31>. 

Examples

* Simple example:: 

Superseded modules

* getopt — C-style parser for command line options:: 
* profile — Pure Python profiler:: 

profile — Pure Python profiler

* Migration:: 
* profile and profiling.tracing module reference: profile and profiling tracing module reference. 
* Differences from profiling.tracing: Differences from profiling tracing. 
* What is deterministic profiling?: What is deterministic profiling?<2>. 
* Limitations: Limitations<2>. 
* Calibration:: 
* Using a custom timer: Using a custom timer<2>. 

Removed Modules

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

Επέκταση και Ενσωμάτωση του Διερμηνέα της Python

* Your first C API extension module:: 
* Using the C API; Assorted topics: Using the C API Assorted topics. 
* Defining Extension Types; Tutorial: Defining Extension Types Tutorial. 
* Defining Extension Types; Assorted Topics: Defining Extension Types Assorted Topics. 
* Κατασκευή Επεκτάσεων C και C++:: 
* Building C and C++ Extensions on Windows:: 
* Embedding Python in Another Application:: 
* Προτεινόμενα εργαλεία τρίτων:: 
* C API Tutorial:: 
* Guides for intermediate topics:: 
* Ενσωμάτωση του χρόνου εκτέλεσης της CPython σε μεγαλύτερη εφαρμογή:: 

Your first C API extension module

* What we’ll do:: 
* Start with the headers:: 
* Running your build tool:: 
* Module export hook:: 
* The slot table:: 
* Exposing a function:: 
* Returning an integer:: 
* Accepting a string:: 
* The result:: 
* Appendix; Other build tools: Appendix Other build tools. 

Exposing a function

* Method definitions:: 

Appendix: Other build tools

* Workaround for missing PyInit function:: 
* Compiling directly:: 

Compiling directly

* Linux:: 

Using the C API: Assorted topics

* Errors and Exceptions:: 
* Embedding an extension:: 
* Calling Python Functions from C:: 
* Extracting Parameters in Extension Functions:: 
* Keyword Parameters for Extension Functions:: 
* Building Arbitrary Values:: 
* Reference Counts:: 
* Writing Extensions in C++:: 
* Providing a C API for an Extension Module:: 

Reference Counts

* Reference Counting in Python:: 
* Ownership Rules:: 
* Thin Ice:: 
* NULL Pointers:: 

Defining Extension Types: Tutorial

* The Basics:: 
* Adding data and methods to the Basic example:: 
* Providing finer control over data attributes:: 
* Supporting cyclic garbage collection:: 
* Subclassing other types:: 

Defining Extension Types: Assorted Topics

* Finalization and De-allocation:: 
* Object Presentation:: 
* Attribute Management:: 
* Object Comparison:: 
* Abstract Protocol Support:: 
* Weak Reference Support:: 
* More Suggestions:: 

Attribute Management

* Generic Attribute Management:: 
* Type-specific Attribute Management:: 

Κατασκευή Επεκτάσεων C και C++

* Κατασκευή Επεκτάσεων C και C++ με το setuptools:: 

Building C and C++ Extensions on Windows

* A Cookbook Approach:: 
* Differences Between Unix and Windows:: 
* Using DLLs in Practice:: 

Embedding Python in Another Application

* Very High Level Embedding:: 
* Beyond Very High Level Embedding; An overview: Beyond Very High Level Embedding An overview. 
* Pure Embedding:: 
* Extending Embedded Python:: 
* Embedding Python in C++:: 
* Compiling and Linking under Unix-like systems:: 

Python/C API reference manual

* Introduction: Introduction<12>. 
* C API and ABI Stability:: 
* The Very High Level Layer:: 
* Reference Counting:: 
* Exception Handling:: 
* Defining extension modules:: 
* Definition slots:: 
* Utilities: Utilities<2>. 
* Abstract Objects Layer:: 
* Concrete Objects Layer:: 
* Interpreter initialization and finalization:: 
* Thread states and the global interpreter lock:: 
* Asynchronous notifications:: 
* Operating system thread APIs:: 
* Synchronization primitives: Synchronization primitives<2>. 
* Thread-local storage support:: 
* Multiple interpreters in a Python process:: 
* Profiling and tracing:: 
* Reference tracing:: 
* Python Initialization Configuration:: 
* Memory Management:: 
* Object Implementation Support:: 
* API and ABI Versioning:: 
* Monitoring C API:: 
* Generating Execution Events:: 

Introduction

* Language version compatibility:: 
* Coding standards:: 
* Include Files:: 
* Useful macros:: 
* Objects@comma{} Types and Reference Counts: Objects Types and Reference Counts. 
* Exceptions: Exceptions<22>. 
* Embedding Python:: 
* Debugging Builds:: 
* Recommended third party tools:: 

Include Files

* System includes:: 

Useful macros

* Docstring macros:: 
* General utility macros:: 
* Declaration utilities:: 
* Outdated macros:: 

General utility macros

* Numeric utilities:: 
* Assertion utilities:: 
* Type size utilities:: 
* Macro definition utilities:: 

Objects, Types and Reference Counts

* Reference Counts: Reference Counts<2>. 
* Types: Types<2>. 

Reference Counts

* Reference Count Details:: 

C API and ABI Stability

* Unstable C API:: 
* Stable Application Binary Interfaces:: 
* Platform Considerations:: 
* ABI Checking:: 
* Contents of Limited API:: 

Stable Application Binary Interfaces

* Compiling for Stable ABI:: 
* Stable ABI Scope and Performance:: 
* Stable ABI Caveats:: 

The Very High Level Layer

* Available start symbols:: 
* Stack Effects:: 

Exception Handling

* Printing and clearing:: 
* Raising exceptions:: 
* Issuing warnings:: 
* Querying the error indicator:: 
* Signal Handling: Signal Handling<2>. 
* Exception Classes:: 
* Exception Objects:: 
* Unicode Exception Objects:: 
* Recursion Control:: 
* Exception and warning types:: 
* Tracebacks:: 

Exception and warning types

* Exception types:: 
* OSError aliases:: 
* Warning types:: 

Defining extension modules

* Extension export hook:: 
* Multi-phase initialization:: 
* Multiple module instances:: 
* PyInit function:: 

PyInit function

* Legacy single-phase initialization:: 

Definition slots

* Convenience macros:: 
* Common slot IDs:: 

Utilities

* Operating System Utilities:: 
* System Functions:: 
* Process Control:: 
* Importing Modules: Importing Modules<2>. 
* Data marshalling support:: 
* Parsing arguments and building values:: 
* String conversion and formatting:: 
* Character classification and conversion:: 
* PyHash API:: 
* Reflection:: 
* Codec registry and support functions:: 
* PyTime C API:: 
* Support for Perf Maps:: 

Parsing arguments and building values

* Parsing arguments: Parsing arguments<2>. 
* Building values:: 

Parsing arguments

* Strings and buffers:: 
* Numbers:: 
* Other objects:: 
* API Functions:: 

Codec registry and support functions

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

PyTime C API

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

Abstract Objects Layer

* Object Protocol:: 
* Call Protocol:: 
* Number Protocol:: 
* Sequence Protocol:: 
* Mapping Protocol:: 
* Iterator Protocol:: 
* Buffer Protocol:: 

Call Protocol

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

The Vectorcall Protocol

* Recursion Control: Recursion Control<2>. 
* Vectorcall Support API:: 

Buffer Protocol

* Buffer structure:: 
* Buffer request types:: 
* Complex arrays:: 
* Buffer-related functions:: 

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. 

Concrete Objects Layer

* Fundamental Objects:: 
* Numeric Objects:: 
* Sequence Objects:: 
* Container Objects:: 
* Function Objects: Function Objects<2>. 
* Other Objects:: 
* C API for extension modules:: 

Fundamental Objects

* Type Objects:: 
* The None Object:: 

Type Objects

* Creating Heap-Allocated Types:: 
* Soft-deprecated API:: 

Creating Heap-Allocated Types

* Type slot IDs:: 

Numeric Objects

* Integer Objects:: 
* Boolean Objects:: 
* Floating-Point Objects:: 
* Complex Number Objects:: 

Integer Objects

* Export API:: 
* PyLongWriter API:: 
* Deprecated API:: 

Floating-Point Objects

* Pack and Unpack functions:: 

Pack and Unpack functions

* Pack functions:: 
* Unpack functions:: 

Complex Number Objects

* Complex Numbers as C Structures:: 

Sequence Objects

* Bytes Objects:: 
* PyBytesWriter:: 
* Byte Array Objects:: 
* Unicode Objects and Codecs:: 
* Tuple Objects:: 
* Struct Sequence Objects:: 
* List Objects:: 

PyBytesWriter

* Create@comma{} Finish@comma{} Discard: Create Finish Discard. 
* High-level API:: 
* Getters:: 
* Low-level API:: 

Byte Array Objects

* Type check macros:: 
* Direct API functions:: 
* Macros:: 

Unicode Objects and Codecs

* Unicode Objects:: 
* Built-in Codecs:: 
* Methods and Slot Functions:: 
* PyUnicodeWriter:: 
* Deprecated API: Deprecated API<2>. 

Unicode Objects

* Unicode Type:: 
* 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:: 

Container Objects

* Dictionary objects:: 
* Set Objects:: 

Dictionary objects

* Dictionary view objects:: 
* Frozen dictionary objects:: 
* Ordered dictionaries:: 

Set Objects

* Deprecated API: Deprecated API<3>. 

Function Objects

* Function Objects: Function Objects<3>. 
* Instance Method Objects:: 
* Method Objects:: 
* Cell Objects:: 
* Code Objects:: 
* Code Object Flags:: 
* Extra information:: 

Other Objects

* File objects:: 
* Module Objects:: 
* Iterator Objects:: 
* Descriptor Objects:: 
* Slice Objects:: 
* MemoryView objects:: 
* Pickle buffer objects:: 
* Weak Reference Objects: Weak Reference Objects<2>. 
* Capsules: Capsules<2>. 
* Sentinel objects:: 
* Frame objects:: 
* Generator Objects:: 
* Coroutine Objects:: 
* Context Variables Objects:: 
* Objects for Type Hinting:: 

File objects

* Soft-deprecated API: Soft-deprecated API<2>. 

Module Objects

* Module definition:: 
* Module state:: 
* Creating extension modules dynamically:: 
* Module definition struct:: 
* Support functions:: 

Module definition

* Metadata slots:: 
* Feature slots:: 
* Creation and initialization slots:: 

Module state

* Slots for defining module state:: 
* Module token:: 

Support functions

* Module lookup (single-phase initialization): Module lookup single-phase initialization. 

Iterator Objects

* Range Objects:: 
* Builtin Iterator Types:: 
* Other Iterator Objects:: 

Descriptor Objects

* Built-in descriptors:: 

Slice Objects

* Ellipsis Object:: 

Frame objects

* Frame locals proxies:: 
* Legacy local variable APIs:: 
* Internal frames:: 

Generator Objects

* Asynchronous Generator Objects:: 
* Deprecated API: Deprecated API<4>. 

C API for extension modules

* Curses C API:: 
* Internal data:: 
* DateTime Objects: DateTime Objects<2>. 
* Internal data: Internal data<2>. 

Interpreter initialization and finalization

* Before Python initialization:: 
* Global configuration variables:: 
* Initializing and finalizing the interpreter:: 
* Cautions regarding interpreter finalization:: 
* Interpreter views:: 
* Process-wide parameters:: 

Thread states and the global interpreter lock

* Detaching the thread state from extension code:: 
* Using the C API from foreign threads:: 
* GIL-state APIs:: 
* Cautions about fork(): Cautions about fork. 
* High-level APIs:: 
* Low-level APIs:: 

Detaching the thread state from extension code

* APIs:: 

Using the C API from foreign threads

* Attaching/detaching thread states:: 

Synchronization primitives

* Python critical section API:: 
* Legacy locking APIs:: 

Python critical section API

* Low-level critical section API:: 

Thread-local storage support

* Thread-specific storage API:: 
* Dynamic allocation:: 
* Methods:: 
* Legacy APIs:: 

Multiple interpreters in a Python process

* A per-interpreter GIL:: 
* Bugs and caveats:: 
* High-level APIs: High-level APIs<2>. 
* Low-level APIs: Low-level APIs<2>. 
* Advanced debugger support:: 

Python Initialization Configuration

* PyInitConfig C API:: 
* Configuration Options:: 
* Runtime Python configuration API:: 
* PyConfig C API:: 
* Py_GetArgcArgv(): Py_GetArgcArgv. 
* Multi-Phase Initialization Private Provisional API:: 

PyInitConfig C API

* Example: Example<15>. 
* Create Config:: 
* Error Handling:: 
* Get Options:: 
* Set Options:: 
* Module:: 
* Initialize Python:: 

PyConfig C API

* Example: Example<16>. 
* PyWideStringList:: 
* PyStatus:: 
* PyPreConfig:: 
* Preinitialize Python with PyPreConfig:: 
* PyConfig:: 
* Initialization with PyConfig:: 
* Isolated Configuration:: 
* Python Configuration:: 
* Python Path Configuration:: 

Memory Management

* Overview: Overview<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:: 
* Examples: Examples<32>. 

Memory Interface

* Deprecated aliases: Deprecated aliases<2>. 

The pymalloc allocator

* Customize pymalloc Arena Allocator:: 

Object Implementation Support

* Allocating objects on the heap:: 
* Object Life Cycle:: 
* Common Object Structures:: 
* Type Object Structures:: 
* Supporting Cyclic Garbage Collection:: 

Allocating objects on the heap

* Soft-deprecated aliases:: 

Object Life Cycle

* Life Events:: 
* Cyclic Isolate Destruction:: 
* Functions: Functions<14>. 

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:: 

Type Object Structures

* 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:: 
* Examples: Examples<33>. 

Quick Reference

* «tp slots»:: 
* sub-slots:: 
* slot typedefs:: 

Supporting Cyclic Garbage Collection

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

Traversal

* Traversal-safe functions:: 
* «DuringGC» functions:: 

API and ABI Versioning

* Build-time version constants:: 
* Run-time version:: 
* Bit-packing macros:: 

Generating Execution Events

* Managing the Monitoring State:: 

Installing Python modules

* Key terms:: 
* Basic usage: Basic usage<2>. 
* How do I …?:: 
* Common installation issues:: 

How do I …?

* … install packages just for the current user?:: 
* … install scientific Python packages?:: 
* … work with multiple versions of Python installed in parallel?:: 

Common installation issues

* Installing into the system Python on Linux:: 
* Pip not installed:: 
* Installing binary extensions:: 

Python HOWTOs

* A conceptual overview of asyncio:: 
* Porting Extension Modules to Python 3:: 
* Curses Programming with Python:: 
* Descriptor Guide:: 
* Debugging C API extensions and CPython Internals with GDB:: 
* Enum HOWTO:: 
* Functional Programming HOWTO:: 
* Logging HOWTO:: 
* Logging Cookbook:: 
* Regular expression HOWTO:: 
* Socket Programming HOWTO:: 
* Sorting Techniques:: 
* Unicode HOWTO:: 
* HOWTO Fetch Internet Resources Using The urllib Package:: 
* An introduction to the ipaddress module:: 
* Instrumenting CPython with DTrace and SystemTap:: 
* Python support for the perf map compatible profilers:: 
* Annotations Best Practices:: 
* Isolating Extension Modules:: 
* timer file descriptor HOWTO:: 
* The Python 2.3 Method Resolution Order: The Python 2 3 Method Resolution Order. 
* Python support for free threading:: 
* C API Extension Support for Free Threading:: 
* Remote debugging attachment protocol:: 
* Permission requirements:: 
* Locating the PyRuntime structure:: 
* Reading _Py_DebugOffsets:: 
* Locating the interpreter and thread state:: 
* Writing control information:: 
* Summary:: 
* Security and threat model:: 

A conceptual overview of asyncio

* A conceptual overview part 1; the high-level: A conceptual overview part 1 the high-level. 
* A conceptual overview part 2; the nuts and bolts: A conceptual overview part 2 the nuts and bolts. 

A conceptual overview part 1: the high-level

* Event loop: Event loop<2>. 
* Asynchronous functions and coroutines:: 
* Tasks: Tasks<2>. 
* await:: 

await

* Awaiting tasks:: 
* Awaiting coroutines:: 

A conceptual overview part 2: the nuts and bolts

* The inner workings of coroutines:: 
* Futures: Futures<2>. 
* A homemade asyncio.sleep: A homemade asyncio sleep. 

Curses Programming with Python

* What is curses?:: 
* Starting and ending a curses application:: 
* Windows and Pads:: 
* Displaying Text:: 
* User Input:: 
* For More Information:: 

What is curses?

* The Python curses module:: 

Displaying Text

* Attributes and Color:: 

Descriptor Guide

* Primer:: 
* Complete Practical Example:: 
* Technical Tutorial:: 
* Pure Python Equivalents:: 

Primer

* Simple example; A descriptor that returns a constant: Simple example A descriptor that returns a constant. 
* Dynamic lookups:: 
* Managed attributes:: 
* Customized names:: 
* Closing thoughts:: 

Complete Practical Example

* Validator class:: 
* Custom validators:: 
* Practical application:: 

Technical Tutorial

* Abstract:: 
* Definition and introduction:: 
* Descriptor protocol:: 
* Overview of descriptor invocation:: 
* Invocation from an instance:: 
* Invocation from a class:: 
* Invocation from super:: 
* Summary of invocation logic:: 
* Automatic name notification:: 
* ORM example:: 

Pure Python Equivalents

* Properties:: 
* Functions and methods:: 
* Kinds of methods:: 
* Static methods:: 
* Class methods:: 
* Member objects and __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:: 

Enum HOWTO

* Programmatic access to enumeration members and their attributes:: 
* Duplicating enum members and values:: 
* Ensuring unique enumeration values:: 
* Using automatic values:: 
* Iteration: Iteration<2>. 
* Comparisons: Comparisons<2>. 
* Allowed members and attributes of enumerations:: 
* Restricted Enum subclassing:: 
* Dataclass support:: 
* Pickling:: 
* Functional API: Functional API<2>. 
* Derived Enumerations:: 
* When to use __new__() vs. __init__(): When to use __new__ vs __init__. 
* Finer Points:: 
* How are Enums and Flags different?:: 
* Enum Cookbook:: 
* Subclassing EnumType:: 

Derived Enumerations

* IntEnum:: 
* StrEnum:: 
* IntFlag:: 
* Flag:: 
* Others: Others<2>. 

Finer Points

* Supported __dunder__ and _sunder_ names:: 
* _Private__names:: 
* Enum member type:: 
* Creating members that are mixed with other data types:: 
* Boolean value of Enum classes and members:: 
* Enum classes with methods:: 
* Combining members of Flag:: 
* Flag and IntFlag minutia:: 

How are Enums and Flags different?

* Enum Classes:: 
* Flag Classes:: 
* Enum Members (aka instances): Enum Members aka instances. 
* Flag Members:: 

Enum Cookbook

* Omitting values:: 
* OrderedEnum:: 
* DuplicateFreeEnum:: 
* MultiValueEnum:: 
* Planet:: 
* TimePeriod:: 

Omitting values

* Using auto:: 
* Using object:: 
* Using a descriptive string:: 
* Using a custom __new__(): Using a custom __new__. 

Functional Programming HOWTO

* Introduction: Introduction<13>. 
* Iterators:: 
* Generator expressions and list comprehensions:: 
* Generators:: 
* Built-in functions:: 
* The itertools module:: 
* The functools module:: 
* Small functions and the lambda expression:: 
* Revision History and Acknowledgements:: 
* References:: 

Introduction

* Formal provability:: 
* Modularity:: 
* Ease of debugging and testing:: 
* Composability:: 

Iterators

* Data Types That Support Iterators:: 

Generators

* Passing values into a generator:: 

The itertools module

* Creating new iterators:: 
* Calling functions on elements:: 
* Selecting elements:: 
* Combinatoric functions:: 
* Grouping elements:: 

The functools module

* The operator module:: 

References

* General:: 
* Python-specific:: 
* Python documentation:: 

Logging HOWTO

* Basic Logging Tutorial:: 
* Advanced Logging Tutorial:: 
* Logging Levels: Logging Levels<2>. 
* Useful Handlers:: 
* Exceptions raised during logging:: 
* Using arbitrary objects as messages:: 
* Optimization:: 
* Other resources:: 

Basic Logging Tutorial

* When to use logging:: 
* A simple example:: 
* Logging to a file:: 
* Logging variable data:: 
* Changing the format of displayed messages:: 
* Displaying the date/time in messages:: 
* Next Steps:: 

Advanced Logging Tutorial

* Logging Flow:: 
* Loggers:: 
* Handlers:: 
* Formatters:: 
* Configuring Logging:: 
* What happens if no configuration is provided:: 
* Configuring Logging for a Library:: 

Logging Levels

* Custom Levels:: 

Logging Cookbook

* Using logging in multiple modules:: 
* Logging from multiple threads:: 
* Multiple handlers and formatters:: 
* Logging to multiple destinations:: 
* Custom handling of levels:: 
* Configuration server example:: 
* Dealing with handlers that block:: 
* Sending and receiving logging events across a network:: 
* Adding contextual information to your logging output:: 
* Use of contextvars:: 
* Imparting contextual information in handlers:: 
* Logging to a single file from multiple processes:: 
* Using file rotation:: 
* Use of alternative formatting styles:: 
* Customizing LogRecord:: 
* Subclassing QueueHandler and QueueListener- a ZeroMQ example:: 
* Subclassing QueueHandler and QueueListener- a pynng example:: 
* An example dictionary-based configuration:: 
* Using a rotator and namer to customize log rotation processing:: 
* A more elaborate multiprocessing example:: 
* Inserting a BOM into messages sent to a SysLogHandler:: 
* Implementing structured logging:: 
* Customizing handlers with dictConfig(): Customizing handlers with 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:: 
* How to uniformly handle newlines in logging output:: 
* Patterns to avoid:: 
* Other resources: Other resources<2>. 

Sending and receiving logging events across a network

* Running a logging socket listener in production:: 

Adding contextual information to your logging output

* Using LoggerAdapters to impart contextual information:: 
* Using Filters to impart contextual information:: 

Using LoggerAdapters to impart contextual information

* Using objects other than dicts to pass contextual information:: 

Logging to a single file from multiple processes

* Using concurrent.futures.ProcessPoolExecutor: Using concurrent futures ProcessPoolExecutor. 
* Deploying web applications using Gunicorn and 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:: 

Regular expression HOWTO

* Introduction: Introduction<14>. 
* Simple patterns:: 
* Using regular expressions:: 
* More pattern power:: 
* Modifying strings:: 
* Common problems:: 
* Feedback:: 

Simple patterns

* Matching characters:: 
* Repeating things:: 

Using regular expressions

* Compiling regular expressions:: 
* The backslash plague:: 
* Performing matches:: 
* Module-level functions:: 
* Compilation flags:: 

More pattern power

* More metacharacters:: 
* Grouping:: 
* Non-capturing and named groups:: 
* Lookahead assertions:: 

Modifying strings

* Splitting strings:: 
* Search and replace:: 

Common problems

* Use string methods:: 
* prefixmatch() (aka match) versus search(): prefixmatch aka match versus search. 
* Greedy versus non-greedy:: 
* Using re.VERBOSE: Using re VERBOSE. 

Socket Programming HOWTO

* Sockets:: 
* Creating a Socket:: 
* Using a Socket:: 
* Disconnecting:: 
* Non-blocking Sockets:: 

Sockets

* History:: 

Creating a Socket

* IPC:: 

Using a Socket

* Binary Data:: 

Disconnecting

* When Sockets Die:: 

Sorting Techniques

* Sorting Basics:: 
* Key Functions:: 
* Operator Module Functions and Partial Function Evaluation:: 
* Ascending and Descending:: 
* Sort Stability and Complex Sorts:: 
* Decorate-Sort-Undecorate:: 
* Comparison Functions:: 
* Strategies For Unorderable Types and Values:: 
* Odds and Ends:: 
* Partial Sorts:: 

Unicode HOWTO

* Introduction to Unicode:: 
* Python’s Unicode Support:: 
* Reading and Writing Unicode Data:: 
* Acknowledgements: Acknowledgements<10>. 

Introduction to Unicode

* Definitions:: 
* Encodings:: 
* References: References<2>. 

Python’s Unicode Support

* The String Type:: 
* Converting to Bytes:: 
* Unicode Literals in Python Source Code:: 
* Unicode Properties:: 
* Comparing Strings:: 
* Unicode Regular Expressions:: 
* References: References<3>. 

Reading and Writing Unicode Data

* Unicode filenames:: 
* Tips for Writing Unicode-aware Programs:: 
* References: References<4>. 

Tips for Writing Unicode-aware Programs

* Converting Between File Encodings:: 
* Files in an Unknown Encoding:: 

HOWTO Fetch Internet Resources Using The urllib Package

* Introduction: Introduction<15>. 
* Fetching URLs:: 
* Handling Exceptions:: 
* info and geturl:: 
* Openers and Handlers:: 
* Basic Authentication:: 
* Proxies:: 
* Sockets and Layers:: 
* Footnotes:: 

Fetching URLs

* Data:: 
* Headers:: 

Handling Exceptions

* URLError:: 
* HTTPError:: 
* Wrapping it Up:: 

HTTPError

* Error Codes:: 

Wrapping it Up

* Number 1:: 
* Number 2:: 

An introduction to the ipaddress module

* Creating Address/Network/Interface objects:: 
* Inspecting Address/Network/Interface Objects:: 
* Networks as lists of Addresses:: 
* Comparisons: Comparisons<3>. 
* Using IP Addresses with other modules:: 
* Getting more detail when instance creation fails:: 

Creating Address/Network/Interface objects

* A Note on IP Versions:: 
* IP Host Addresses:: 
* Defining Networks:: 
* Host Interfaces:: 

Instrumenting CPython with DTrace and SystemTap

* Enabling the static markers:: 
* Static DTrace probes:: 
* Static SystemTap markers:: 
* Available static markers:: 
* SystemTap Tapsets:: 
* Examples: Examples<34>. 

Available static markers

* C Entry Points:: 
* C Probing Checks:: 

Python support for the perf map compatible profilers

* Using the samply profiler:: 
* How to enable perf profiling support:: 
* How to obtain the best results:: 
* How to work without frame pointers:: 

Annotations Best Practices

* Accessing The Annotations Dict Of An Object In Python 3.10 And Newer: Accessing The Annotations Dict Of An Object In Python 3 10 And Newer. 
* Accessing The Annotations Dict Of An Object In Python 3.9 And Older: Accessing The Annotations Dict Of An Object In Python 3 9 And Older. 
* Manually Un-Stringizing Stringized Annotations:: 
* Best Practices For __annotations__ In Any Python Version:: 
* __annotations__ Quirks:: 

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

* Examples: Examples<35>. 

The Python 2.3 Method Resolution Order

* The beginning:: 
* The C3 Method Resolution Order:: 
* Examples: Examples<36>. 
* Bad Method Resolution Orders:: 
* The end:: 
* Resources:: 

Python support for free threading

* Installation:: 
* Identifying free-threaded Python:: 
* The global interpreter lock in free-threaded Python:: 
* Thread safety:: 
* Known limitations:: 
* Behavioral changes:: 

Known limitations

* Immortalization:: 
* Frame objects: Frame objects<2>. 
* Iterators: Iterators<2>. 
* Single-threaded performance:: 

Behavioral changes

* Context variables:: 
* Warning filters:: 

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:: 
* Critical Sections:: 
* 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:: 

Critical Sections

* What Are Critical Sections?:: 
* Using Critical Sections:: 
* How Critical Sections Work:: 
* Deadlock Avoidance:: 
* Important Considerations:: 
* Per-Object Locks (ob_mutex): Per-Object Locks ob_mutex. 

Building Extensions for the Free-Threaded Build

* Limited C API and Stable ABI:: 
* Windows: Windows<84>. 

Remote debugging attachment protocol

* Disabling remote debugging:: 

Security and threat model

* When to use PYTHON_DISABLE_REMOTE_DEBUG:: 

Συχνές Ερωτήσεις για την Python

* General Python FAQ:: 
* FAQ Προγραμματισμού:: 
* Design and History FAQ:: 
* Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης:: 
* Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης:: 
* Python στα Windows FAQ:: 
* Graphic User Interface FAQ:: 
* «Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;» FAQ:: 

General Python FAQ

* General Information:: 
* Python in the real world:: 

General Information

* What is Python?:: 
* What is the Python Software Foundation?:: 
* Are there copyright restrictions on the use of Python?:: 
* Why was Python created in the first place?:: 
* What is Python good for?:: 
* How does the Python version numbering scheme work?:: 
* How do I obtain a copy of the Python source?:: 
* How do I get documentation on Python?:: 
* I’ve never programmed before. Is there a Python tutorial?: I’ve never programmed before Is there a Python tutorial?. 
* Is there a newsgroup or mailing list devoted to Python?:: 
* How do I get a beta test version of Python?:: 
* How do I submit bug reports and patches for Python?:: 
* Are there any published articles about Python that I can reference?:: 
* Are there any books on Python?:: 
* Where in the world is www.python.org located?: Where in the world is www python org located?. 
* Why is it called Python?:: 
* Do I have to like «Monty Python’s Flying Circus»?:: 

Python in the real world

* How stable is Python?:: 
* How many people are using Python?:: 
* Have any significant projects been done in Python?:: 
* What new developments are expected for Python in the future?:: 
* Is it reasonable to propose incompatible changes to Python?:: 
* Is Python a good language for beginning programmers?:: 

FAQ Προγραμματισμού

* General questions:: 
* Core language:: 
* Αριθμοί και συμβολοσειρές:: 
* Απόδοση:: 
* Sequences (tuples/lists): Sequences tuples/lists. 
* Αντικείμενα:: 
* Modules: Modules<5>. 

General questions

* Is there a source code-level debugger with breakpoints and single-stepping?:: 
* Υπάρχουν εργαλεία που βοηθούν στην εύρεση σφαλμάτων ή στην εκτέλεση στατικής ανάλυσης;:: 
* Πως μπορώ να δημιουργήσω ένα stand-alone binary από ένα Python script;:: 
* Υπάρχουν πρότυπα κωδικοποίησης ή οδηγός στυλ για προγράμματα Python;:: 

Core language

* Γιατί λαμβάνω ένα UnboundLocalError όταν η μεταβλητή έχει μια τιμή;:: 
* Ποιοι είναι οι κανόνες για τις τοπικές και τις καθολικές μεταβλητές στην Python;:: 
* Γιατί τα lambdas που ορίζονται σε έναν βρόχο με διαφορετικές τιμές επιστρέφουν όλα το ίδιο αποτέλεσμα;:: 
* Πως μοιράζομαι καθολικές μεταβλητές σε modules;:: 
* Ποιες είναι οι «βέλτιστες πρακτικές» για τη χρήση import σε ένα module;:: 
* Γιατί μοιράζονται οι προεπιλεγμένες τιμές μεταξύ των αντικειμένων;:: 
* Πώς μπορώ να μεταβιβάσω προαιρετικές παραμέτρους ή παραμέτρους λέξεων-κλειδιών από τη μια συνάρτηση στην άλλη;:: 
* Ποια είναι η διαφορά μεταξύ ορισμάτων και παραμέτρων;:: 
* Γιατί η αλλαγή της λίστας “y” αλλάζει επίσης και τη λίστα “x”;:: 
* Πως μπορώ να γράψω μια συνάρτηση με παραμέτρους εξόδου (κλήση με αναφορά);: Πως μπορώ να γράψω μια συνάρτηση με παραμέτρους εξόδου κλήση με αναφορά ;. 
* Πως δημιουργείτε μια συνάρτηση υψηλότερης τάξης στην Python;:: 
* Πως μπορώ να αντιγράψω ένα αντικείμενο στην Python;:: 
* Πως μπορώ να βρω τις μεθόδους ή τα χαρακτηριστικά ενός αντικειμένου;:: 
* Πως μπορεί ο κώδικας μου να ανακαλύψει το όνομα ενός αντικειμένου;:: 
* Τι συμβαίνει με την προτεραιότητα του τελεστή κόμματος;:: 
* Υπάρχει ισοδύναμο του τριαδικού τελεστή «?;» της C;: Υπάρχει ισοδύναμο του τριαδικού τελεστή «? » της C;. 
* Είναι δυνατόν να γράψουμε ασαφή one-liners στην Python;:: 
* Τι σημαίνει η κάθετος(/) στη λίστα παραμέτρων μιας συνάρτησης;: Τι σημαίνει η κάθετος / στη λίστα παραμέτρων μιας συνάρτησης;. 

Αριθμοί και συμβολοσειρές

* Πώς προσδιορίζω δεκαεξαδικούς ή οκταδικούς ακέραιους αριθμούς;:: 
* Γιατί το -22 // 10 επιστρέφει -3;:: 
* Πώς μπορώ να πάρω το literal χαρακτηριστικό int αντί για το SyntaxError;:: 
* Πως μετατρέπω μια συμβολοσειρά σε έναν αριθμό;:: 
* Πως μετατρέπω έναν αριθμό σε συμβολοσειρά;:: 
* Πώς μπορώ να τροποποιήσω μια συμβολοσειρά στη θέση της;:: 
* Πως μπορώ να χρησιμοποιήσω συμβολοσειρές για να καλέσω συναρτήσεις/μεθόδους;:: 
* Υπάρχει ισοδύναμο με το Perl’s chomp() για την αφαίρεση των νέων γραμμών από τις συμβολοσειρές;: Υπάρχει ισοδύναμο με το Perl’s chomp για την αφαίρεση των νέων γραμμών από τις συμβολοσειρές;. 
* Υπάρχει αντίστοιχο scanf() ή sscanf();: Υπάρχει αντίστοιχο scanf ή sscanf ;. 
* Τι σημαίνει το σφάλμα UnicodeDecodeError ή UnicodeEncodeError;:: 
* Μπορώ να τερματίσω μια ακατέργαστη συμβολοσειρά με περιττό αριθμό backslashes;:: 

Απόδοση

* Το πρόγραμμα μου είναι πολύ αργό. Πως μπορώ να το επιταχύνω;: Το πρόγραμμα μου είναι πολύ αργό Πως μπορώ να το επιταχύνω;. 
* Ποιος είναι ο πιο αποτελεσματικός τρόπος για να συνδέσετε πολλές συμβολοσειρές μεταξύ τους;:: 

Sequences (tuples/lists)

* Πως μπορώ να κάνω μετατροπή μεταξύ πλειάδων και λιστών;:: 
* Τι είναι αρνητικός δείκτης;:: 
* Πώς μπορώ να επαναλάβω μια ακολουθία με αντίστροφη σειρά;:: 
* Πως αφαιρείτε διπλότυπα από μια λίστα;:: 
* How do you remove multiple items from a list?:: 
* Πως μπορείτε να φτιάξετε έναν πίνακα στην Python;:: 
* Πως φτιάχνω μια πολυδιάστατη λίστα;:: 
* Πώς μπορώ να εφαρμόσω μια μέθοδο ή μια συνάρτηση σε μια ακολουθία αντικειμένων;:: 
* Γιατί το a_tuple[i] += [“item”] δημιουργεί μια εξαίρεση όταν λειτουργεί η προσθήκη;:: 
* Θέλω να κάνω μια περίπλοκη ταξινόμηση; μπορείτε να κάνετε ένα Schwartzian Transform στην Python;: Θέλω να κάνω μια περίπλοκη ταξινόμηση μπορείτε να κάνετε ένα Schwartzian Transform στην Python;. 
* Πως μπορώ να ταξινομήσω μια λίστα με βάση τις τιμές από μια άλλη λίστα;:: 

Αντικείμενα

* Τι είναι μια κλάση;:: 
* Τι είναι μια μέθοδος;:: 
* Τι είναι το self;:: 
* Πώς μπορώ να ελέγξω εάν ένα αντικείμενο είναι μια οντότητα μιας δεδομένης κλάσης ή μιας υποκλάσης της;:: 
* Τι είναι το delegation;:: 
* Πώς μπορώ να καλέσω μια μέθοδο που ορίζεται σε μια βασική κλάση από μια παράγωγη κλάση που την επεκτείνει;:: 
* Πως μπορώ να οργανώσω τον κώδικα μου προκειμένου να διευκολύνω την αλλαγή της βασικής κλάσης;:: 
* Πως δημιουργώ δεδομένα στατικής κλάσης και μεθόδους στατικής κλάσης;:: 
* Πως μπορώ να υπερφορτώσω κατασκευαστές (ή μεθόδους) στην Python;: Πως μπορώ να υπερφορτώσω κατασκευαστές ή μεθόδους στην Python;. 
* Προσπαθώ να χρησιμοποιήσω __spam και λαμβάνω ένα σφάλμα σχετικά με το _SomeClassName__spam.: Προσπαθώ να χρησιμοποιήσω __spam και λαμβάνω ένα σφάλμα σχετικά με το _SomeClassName__spam. 
* Η κλάση μου ορίζει __del__ αλλά δεν καλείται όταν διαγράφω το αντικείμενο.: Η κλάση μου ορίζει __del__ αλλά δεν καλείται όταν διαγράφω το αντικείμενο. 
* Πως μπορώ να λάβω μια λίστα με όλες τις οντότητες μιας δεδομένης κλάσης;:: 
* Γιατί το αποτέλεσμα του id() φαίνεται να μην είναι μοναδικό;: Γιατί το αποτέλεσμα του id φαίνεται να μην είναι μοναδικό;. 
* Πότε μπορώ να βασιστώ σε δοκιμές ταυτότητας με τον τελεστή is;:: 
* Πώς μπορεί μια υποκλάση να ελέγξει ποια δεδομένα αποθηκεύονται σε μια αμετάβλητη παρουσία;:: 
* Πώς μπορώ να αποθηκεύσω τις κλήσεις μεθόδου στην κρυφή μνήμη;:: 

Modules

* Πως δημιουργώ ένα .pyc αρχείο;: Πως δημιουργώ ένα pyc αρχείο;. 
* Πως μπορώ να βρω το όνομα του τρέχοντος module;:: 
* Πως μπορώ να έχω modules που εισάγουν αμοιβαία το ένα το άλλο;:: 
* __import__(“x.y.z”) επιστρέφει <module “x”>∙ πως μπορώ να πάρω το z?: __import__ “x y z” επιστρέφει <module “x”>∙ πως μπορώ να πάρω το z?. 
* Όταν επεξεργάζομαι ένα module που έχει εισαχθεί και την επανεισάγω@comma{} οι αλλαγές δεν εμφανίζονται. Γιατί συμβαίνει αυτό;: Όταν επεξεργάζομαι ένα module που έχει εισαχθεί και την επανεισάγω οι αλλαγές δεν εμφανίζονται Γιατί συμβαίνει αυτό;. 

Design and History FAQ

* Why does Python use indentation for grouping of statements?:: 
* Why am I getting strange results with simple arithmetic operations?:: 
* Why are floating-point calculations so inaccurate?:: 
* Why are Python strings immutable?:: 
* Why must “self” be used explicitly in method definitions and calls?:: 
* Why can’t I use an assignment in an expression?:: 
* Why does Python use methods for some functionality (e.g. list.index()) but functions for other (e.g. len(list))?: Why does Python use methods for some functionality e g list index but functions for other e g len list ?. 
* Why is join() a string method instead of a list or tuple method?: Why is join a string method instead of a list or tuple method?. 
* How fast are exceptions?:: 
* Why isn’t there a switch or case statement in Python?:: 
* Can’t you emulate threads in the interpreter instead of relying on an OS-specific thread implementation?:: 
* Why can’t lambda expressions contain statements?:: 
* Can Python be compiled to machine code@comma{} C or some other language?: Can Python be compiled to machine code C or some other language?. 
* How does Python manage memory?:: 
* Why doesn’t CPython use a more traditional garbage collection scheme?:: 
* Why isn’t all memory freed when CPython exits?:: 
* Why are there separate tuple and list data types?:: 
* How are lists implemented in CPython?:: 
* How are dictionaries implemented in CPython?:: 
* Why must dictionary keys be immutable?:: 
* Why doesn’t list.sort() return the sorted list?: Why doesn’t list sort return the sorted list?. 
* How do you specify and enforce an interface spec in Python?:: 
* Why is there no goto?:: 
* Why can’t raw strings (r-strings) end with a backslash?: Why can’t raw strings r-strings end with a backslash?. 
* Why doesn’t Python have a «with» statement for attribute assignments?:: 
* Why don’t generators support the with statement?:: 
* Why are colons required for the if/while/def/class statements?:: 
* Why does Python allow commas at the end of lists and tuples?:: 

Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης

* Γενικές Ερωτήσεις Βιβλιοθήκης:: 
* Κοινές εργασίες:: 
* Νήματα (Threads): Νήματα Threads. 
* Είσοδος και Έξοδος: Είσοδος και Έξοδος<2>. 
* Προγραμματισμός Δικτύου/Διαδικτύου:: 
* Βάσεις Δεδομένων:: 
* Μαθηματικά και Αριθμητικά:: 

Γενικές Ερωτήσεις Βιβλιοθήκης

* Πως μπορώ να βρω ένα module ή μια εφαρμογή για να εκτελέσω την εργασία Χ;:: 
* Που βρίσκεται το πηγαίο αρχείο math.py (socket.py@comma{} regex.py@comma{} κ.λπ.);: Που βρίσκεται το πηγαίο αρχείο math py socket py regex py κ λπ ;. 
* Πως δημιουργώ ένα εκτελέσιμο Python script στο Unix;:: 
* Υπάρχει ένα curses/termcap πακέτο για την Python;:: 
* Υπάρχει κάτι ισοδύναμο με την onexit() της C στην Python;: Υπάρχει κάτι ισοδύναμο με την onexit της C στην Python;. 
* Γιατί δεν λειτουργούν οι χειριστές σήματος μου;:: 

Κοινές εργασίες

* Πως μπορώ να τεστάρω ένα Python πρόγραμμα ή ένα Python component;:: 
* Πως δημιουργώ τεκμηρίωση από doc strings;:: 
* Πως μπορώ να λάβω μόνο ένα πάτημα κουμπιού κάθε φορά;:: 

Νήματα (Threads)

* Πώς μπορώ να προγραμματίσω χρησιμοποιώντας νήματα(threads);: Πώς μπορώ να προγραμματίσω χρησιμοποιώντας νήματα threads ;. 
* Κανένα από τα νήματα (threads) μου δεν φαίνεται να εκτελείται; γιατί;: Κανένα από τα νήματα threads μου δεν φαίνεται να εκτελείται γιατί;. 
* Πως μπορώ να μοιράσω την εργασία σε ένα σωρό από νήματα για αυτήν την εργασία;:: 
* Ποια είδη global μετάλλαξης τιμής είναι ασφαλή για νήμα(thread);: Ποια είδη global μετάλλαξης τιμής είναι ασφαλή για νήμα thread ;. 
* Μπορούμε να απαλλαγούμε από ένα Global Interpreter Lock;:: 

Είσοδος και Έξοδος

* Πώς μπορώ να διαγράψω ένα αρχείο; (Και άλλες ερωτήσεις για το αρχείο…): Πώς μπορώ να διαγράψω ένα αρχείο; Και άλλες ερωτήσεις για το αρχείο…. 
* Πως αντιγράφω ένα αρχείο;:: 
* Πώς διαβάζω (ή γράφω) δυαδικά δεδομένα;: Πώς διαβάζω ή γράφω δυαδικά δεδομένα;. 
* Δεν μπορώ να χρησιμοποιήσω το os.read() σε ένα pipe που δημιουργήθηκε με το os.popen()∙ γιατί;: Δεν μπορώ να χρησιμοποιήσω το os read σε ένα pipe που δημιουργήθηκε με το os popen ∙ γιατί;. 
* Πώς μπορώ να αποκτήσω πρόσβαση στη σειριακή θύρα (RS232);: Πώς μπορώ να αποκτήσω πρόσβαση στη σειριακή θύρα RS232 ;. 
* Γιατί το κλείσιμο του sys.stdout (stdin@comma{} stderr) δεν το κλείνει πραγματικά;: Γιατί το κλείσιμο του sys stdout stdin stderr δεν το κλείνει πραγματικά;. 

Προγραμματισμός Δικτύου/Διαδικτύου

* Ποια εργαλεία WWW υπάρχουν για την Python;:: 
* Τι module πρέπει να χρησιμοποιήσω για να βοηθήσω στην δημιουργία HTML;:: 
* Πώς μπορώ να στείλω αλληλογραφία από ένα Python script;:: 
* Πώς μπορώ να αποφύγω τον αποκλεισμό στη μέθοδο connect() ενός socket;: Πώς μπορώ να αποφύγω τον αποκλεισμό στη μέθοδο connect ενός socket;. 

Βάσεις Δεδομένων

* Υπάρχουν διεπαφές σε πακέτα βάσεων δεδομένων στην Python;:: 
* Πως υλοποιείτε persistent αντικείμενα στην Python;:: 

Μαθηματικά και Αριθμητικά

* Πως μπορώ να δημιουργήσω τυχαίους αριθμούς στην Python;:: 

Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης

* Μπορώ να δημιουργήσω τις δικές μου συναρτήσεις στη C;:: 
* Μπορώ να δημιουργήσω τις δικές μου συναρτήσεις στη C++;:: 
* Το να γράψει C κάποιος είναι δύσκολο· υπάρχουν άλλες εναλλακτικές;:: 
* Πως μπορώ να εκτελέσω αυθαίρετες δηλώσεις Python από το C;:: 
* Πώς μπορώ να αξιολογήσω μια αυθαίρετη έκφραση Python από τη C;:: 
* Πως μπορώ να εξάγω τιμές C από ένα αντικείμενο Python;:: 
* Πώς μπορώ να χρησιμοποιήσω την Py_BuildValue() για να δημιουργήσω μια πλειάδα (tuple) αυθαίρετου μήκους;: Πώς μπορώ να χρησιμοποιήσω την Py_BuildValue για να δημιουργήσω μια πλειάδα tuple αυθαίρετου μήκους;. 
* Πώς καλώ τη μέθοδο ενός αντικειμένου από τη C;:: 
* Πώς μπορώ να κάνω catch την έξοδο από την PyErr_Print() (ή οτιδήποτε εκτυπώνεται σε stdout/stderr);: Πώς μπορώ να κάνω catch την έξοδο από την PyErr_Print ή οτιδήποτε εκτυπώνεται σε stdout/stderr ;. 
* Πως μπορώ να αποκτήσω πρόσβαση σε ένα module γραμμένο σε Python από τη C;:: 
* Πως διασυνδέομαι με αντικείμενα C++ από την Python;:: 
* Πρόσθεσα ένα module χρησιμοποιώντας το αρχείο Setup και το make αποτυγχάνει· γιατί;:: 
* Πως κάνω debug μια επέκταση;:: 
* Θέλω να κάνω compile ένα Python module στο σύστημα Linux μου@comma{} αλλά λείπουν ορισμένα αρχεία. Γιατί;: Θέλω να κάνω compile ένα Python module στο σύστημα Linux μου αλλά λείπουν ορισμένα αρχεία Γιατί;. 
* Πώς μπορώ να ξεχωρίσω την «ελλιπή εισαγωγή» από την «έγκυρη εισαγωγή»;:: 
* Πώς μπορώ να βρω απροσδιόριστα σύμβολα g++ __builtin_new ή __pure_virtual;:: 
* Μπορώ να δημιουργήσω μια κλάση αντικειμένου με ορισμένες μεθόδους που υλοποιούνται στη C και άλλες στη Python (π.χ. μέσω κληρονομικότητας);: Μπορώ να δημιουργήσω μια κλάση αντικειμένου με ορισμένες μεθόδους που υλοποιούνται στη C και άλλες στη Python π χ μέσω κληρονομικότητας ;. 

Python στα Windows FAQ

* Πως μπορώ να εκτελέσω ένα πρόγραμμα Python στα Windows;:: 
* Πως κάνω τα Python scripts εκτελέσιμα;:: 
* Γιατί μερικές φορές η Python αργεί τόσο πολύ να ξεκινήσει;:: 
* Πώς μπορώ να δημιουργήσω ένα εκτελέσιμο από ένα σενάριο Python;:: 
* Είναι ένα αρχείο *.pyd ίδιο με ένα αρχείο DLL;: Είναι ένα αρχείο * pyd ίδιο με ένα αρχείο DLL;. 
* Πώς μπορώ να ενσωματώσω την Python σε μια εφαρμογή Windows;:: 
* Πως μπορώ να εμποδίσω τους editors να εισάγουν tabs στον πηγαίο της Python μου;:: 
* Πώς μπορώ να ελέγξω για ένα πάτημα πλήκτρων χωρίς αποκλεισμό;:: 
* Πως μπορώ να διορθώσω το σφάλμα που λείπει το api-ms-win-crt-runtime-l1-1-0.dll;: Πως μπορώ να διορθώσω το σφάλμα που λείπει το api-ms-win-crt-runtime-l1-1-0 dll;. 

Graphic User Interface FAQ

* General GUI Questions:: 
* What GUI toolkits exist for Python?:: 
* Tkinter questions:: 

Tkinter questions

* How do I freeze Tkinter applications?:: 
* Can I have Tk events handled while waiting for I/O?:: 
* I can’t get key bindings to work in Tkinter; why?: I can’t get key bindings to work in Tkinter why?. 

«Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;» FAQ

* Τι είναι η Python;:: 
* Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;:: 
* Μπορώ να διαγράψω την Python;:: 

Deprecations

* Pending removal in Python 3.15: Pending removal in Python 3 15<7>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<8>. 
* Pending removal in Python 3.17: Pending removal in Python 3 17<5>. 
* Pending removal in Python 3.18: Pending removal in Python 3 18<6>. 
* Pending removal in Python 3.19: Pending removal in Python 3 19<5>. 
* Pending removal in Python 3.20: Pending removal in Python 3 20<5>. 
* Pending removal in future versions: Pending removal in future versions<8>. 
* Soft deprecations: Soft deprecations<2>. 
* C API deprecations:: 

C API deprecations

* Pending removal in Python 3.15: Pending removal in Python 3 15<8>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<9>. 
* Pending removal in Python 3.18: Pending removal in Python 3 18<7>. 
* Pending removal in Python 3.19: Pending removal in Python 3 19<6>. 
* Pending removal in Python 3.20: Pending removal in Python 3 20<6>. 
* Pending removal in future versions: Pending removal in future versions<9>. 

Σχετικά με την τεκμηρίωση

* Συντελεστές στη τεκμηρίωση της Python:: 

Αντιμετώπιση Σφαλμάτων

* Σφάλματα Τεκμηρίωσης:: 
* Χρησιμοποιώντας τον Python issue tracker:: 
* Ξεκινήστε να συνεισφέρετε και εσείς στην Python:: 

Ιστορία και Άδεια

* Η ιστορία του λογισμικού:: 
* Όροι και προϋποθέσεις για την πρόσβαση ή την χρήση της Python με άλλους τρόπους:: 
* Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό:: 

Όροι και προϋποθέσεις για την πρόσβαση ή την χρήση της Python με άλλους τρόπους

* PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2:: 
* ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ BEOPEN.COM ΓΙΑ PYTHON 2.0: ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ BEOPEN COM ΓΙΑ PYTHON 2 0. 
* ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CNRI ΓΙΑ PYTHON 1.6.1: ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CNRI ΓΙΑ PYTHON 1 6 1. 
* ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CWI ΓΙΑ PYTHON 0.9.0 ΕΩΣ 1.2: ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CWI ΓΙΑ PYTHON 0 9 0 ΕΩΣ 1 2. 
* ZERO-CLAUSE BSD ΑΔΕΙΑ ΓΙΑ ΤΟΝ ΚΩΔΙΚΑ ΣΤΗΝ ΤΕΚΜΗΡΙΩΣΗ ΤΗΣ PYTHON:: 

Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό

* Mersenne Twister:: 
* Sockets: Sockets<2>. 
* Ασύγχρονες socket υπηρεσίες:: 
* Διαχείριση Cookie:: 
* Ανίχνευση εκτέλεσης:: 
* Συναρτήσεις UUencode και UUdecode:: 
* Κλήσεις Απομακρυσμένης Διαδικασίας XML:: 
* test_epoll:: 
* Επιλογή kqueue:: 
* SipHash24:: 
* strtod και dtoa:: 
* OpenSSL: OpenSSL<2>. 
* expat:: 
* libffi:: 
* zlib: zlib<5>. 
* cfuhash:: 
* libmpdec:: 
* W3C C14N σουίτα δοκιμής:: 
* mimalloc:: 
* asyncio: asyncio<16>. 
* Καθολικές Απεριόριστες Ακολουθίες (ΚΑΑ): Καθολικές Απεριόριστες Ακολουθίες ΚΑΑ. 
* Δεσμεύσεις Zstandard:: 
* Profiling module:: 
* Pixi packages:: 

@end detailmenu
@end menu

@node Τι νέο υπάρχει στην Python,Οδηγός εκμάθησης Python,Top,Top
@anchor{whatsnew/index doc}@anchor{13f}@anchor{whatsnew/index python-documentation-contents}@anchor{140}@anchor{whatsnew/index what-s-new-in-python}@anchor{141}@anchor{whatsnew/index whatsnew-index}@anchor{142}
@chapter Τι νέο υπάρχει στην Python


Η σειρά άρθρων «Τι νέο υπάρχει στην Python» περιγράφει τις πιο σημαντικές αλλαγές μεταξύ μεγάλων εκδόσεων της Python. Αποτελεί «must read» για όσους επιθυμούν να παραμείνουν ενημερωμένοι μετά από κάθε νέα έκδοση.

@menu
* What’s new in Python 3.16: What’s new in Python 3 16. 
* What’s new in Python 3.15: What’s new in Python 3 15. 
* What’s new in Python 3.14: What’s new in Python 3 14. 
* 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. 
* What’s New In Python 3.11: What’s New In Python 3 11. 
* What’s New In Python 3.10: What’s New In Python 3 10. 
* What’s New In Python 3.9: What’s New In Python 3 9. 
* What’s New In Python 3.8: What’s New In 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. 
* What’s New In Python 3.5: What’s New In Python 3 5. 
* What’s New In Python 3.4: What’s New In Python 3 4. 
* What’s New In Python 3.3: What’s New In Python 3 3. 
* What’s New In Python 3.2: What’s New In Python 3 2. 
* What’s New In Python 3.1: What’s New In Python 3 1. 
* What’s New In Python 3.0: What’s New In Python 3 0. 
* What’s New in Python 2.7: What’s New in Python 2 7. 
* What’s New in Python 2.6: What’s New in Python 2 6. 
* What’s New in Python 2.5: What’s New in Python 2 5. 
* What’s New in Python 2.4: What’s New in Python 2 4. 
* What’s New in Python 2.3: What’s New in Python 2 3. 
* What’s New in Python 2.2: What’s New in Python 2 2. 
* What’s New in Python 2.1: What’s New in Python 2 1. 
* What’s New in Python 2.0: What’s New in Python 2 0. 
* Changelog:: 

@end menu

@node What’s new in Python 3 16,What’s new in Python 3 15,,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 16 doc}@anchor{143}@anchor{whatsnew/3 16 what-s-new-in-python-3-16}@anchor{144}
@section What’s new in Python 3.16


@*Editor: 
TBD


@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.16, compared to 3.15.

For full details, see the @ref{145,,changelog}.

@cartouche
@quotation Σημείωση 
Prerelease users should be aware that this document is currently in draft
form. It will be updated substantially as Python 3.16 moves towards release,
so it’s worth checking back even after reading earlier versions.
@end quotation
@end cartouche

@menu
* Summary — release highlights:: 
* New features:: 
* Other language changes:: 
* New modules:: 
* Improved modules:: 
* Optimizations:: 
* Removed:: 
* Deprecated:: 
* Porting to Python 3.16: Porting to Python 3 16. 
* Build changes:: 
* C API changes:: 

@end menu

@node Summary — release highlights,New features,,What’s new in Python 3 16
@anchor{whatsnew/3 16 summary-release-highlights}@anchor{146}
@subsection Summary — release highlights


@c This section singles out the most important changes in Python 3.16.
@c Brevity is key.

@c PEP-sized items next.

@node New features,Other language changes,Summary — release highlights,What’s new in Python 3 16
@anchor{whatsnew/3 16 new-features}@anchor{147}
@subsection New features


@node Other language changes,New modules,New features,What’s new in Python 3 16
@anchor{whatsnew/3 16 other-language-changes}@anchor{148}
@subsection Other language changes


@node New modules,Improved modules,Other language changes,What’s new in Python 3 16
@anchor{whatsnew/3 16 new-modules}@anchor{149}
@subsection New modules



@itemize *

@item 
None yet.
@end itemize

@node Improved modules,Optimizations,New modules,What’s new in Python 3 16
@anchor{whatsnew/3 16 improved-modules}@anchor{14a}
@subsection Improved modules


@menu
* module_name:: 

@end menu

@node module_name,,,Improved modules
@anchor{whatsnew/3 16 module-name}@anchor{14b}
@subsubsection module_name



@itemize *

@item 
TODO
@end itemize

@c Add improved modules above alphabetically, not here at the end.

@node Optimizations,Removed,Improved modules,What’s new in Python 3 16
@anchor{whatsnew/3 16 optimizations}@anchor{14c}
@subsection Optimizations


@menu
* module_name: module_name<2>. 

@end menu

@node module_name<2>,,,Optimizations
@anchor{whatsnew/3 16 id1}@anchor{14d}
@subsubsection module_name



@itemize *

@item 
TODO
@end itemize

@node Removed,Deprecated,Optimizations,What’s new in Python 3 16
@anchor{whatsnew/3 16 removed}@anchor{14e}
@subsection Removed


@menu
* annotationlib:: 
* functools:: 
* symtable:: 
* sysconfig:: 

@end menu

@node annotationlib,functools,,Removed
@anchor{whatsnew/3 16 annotationlib}@anchor{14f}
@subsubsection annotationlib



@itemize *

@item 
The @code{annotationlib.ForwardRef._evaluate()} method
which has been deprecated since Python 3.14.
Use @ref{150,,annotationlib.ForwardRef.evaluate()}
or @ref{151,,typing.evaluate_forward_ref()} instead.
@end itemize

@node functools,symtable,annotationlib,Removed
@anchor{whatsnew/3 16 functools}@anchor{152}
@subsubsection functools



@itemize *

@item 
Calling the Python implementation of @ref{153,,functools.reduce()} with `function'
or `sequence' as keyword arguments has been deprecated since Python 3.14.
@end itemize

@node symtable,sysconfig,functools,Removed
@anchor{whatsnew/3 16 symtable}@anchor{154}
@subsubsection symtable



@itemize *

@item 
The @code{symtable.Class.get_methods()} method
which has been deprecated since Python 3.14.
@end itemize

@node sysconfig,,symtable,Removed
@anchor{whatsnew/3 16 sysconfig}@anchor{155}
@subsubsection sysconfig



@itemize *

@item 
The @code{sysconfig.expand_makefile_vars()} function
which has been deprecated since Python 3.14.
Use the @code{vars} argument of @ref{156,,sysconfig.get_paths()} instead.
@end itemize

@c Add removals above alphabetically, not here at the end.

@node Deprecated,Porting to Python 3 16,Removed,What’s new in Python 3 16
@anchor{whatsnew/3 16 deprecated}@anchor{157}
@subsection Deprecated



@itemize *

@item 
module_name:
TODO
@end itemize

@c Add deprecations above alphabetically, not here at the end.

@node Porting to Python 3 16,Build changes,Deprecated,What’s new in Python 3 16
@anchor{whatsnew/3 16 porting-to-python-3-16}@anchor{158}
@subsection Porting to Python 3.16


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

@node Build changes,C API changes,Porting to Python 3 16,What’s new in Python 3 16
@anchor{whatsnew/3 16 build-changes}@anchor{159}
@subsection Build changes


@node C API changes,,Build changes,What’s new in Python 3 16
@anchor{whatsnew/3 16 c-api-changes}@anchor{15a}
@subsection C API changes


@menu
* New features: New features<2>. 
* Porting to Python 3.16: Porting to Python 3 16<2>. 
* Deprecated C APIs:: 
* Removed C APIs:: 

@end menu

@node New features<2>,Porting to Python 3 16<2>,,C API changes
@anchor{whatsnew/3 16 id2}@anchor{15b}
@subsubsection New features



@itemize *

@item 
TODO
@end itemize

@node Porting to Python 3 16<2>,Deprecated C APIs,New features<2>,C API changes
@anchor{whatsnew/3 16 id3}@anchor{15c}
@subsubsection Porting to Python 3.16



@itemize *

@item 
TODO
@end itemize

@node Deprecated C APIs,Removed C APIs,Porting to Python 3 16<2>,C API changes
@anchor{whatsnew/3 16 deprecated-c-apis}@anchor{15d}
@subsubsection Deprecated C APIs



@itemize *

@item 
TODO
@end itemize

@c Add C API deprecations above alphabetically, not here at the end.

@node Removed C APIs,,Deprecated C APIs,C API changes
@anchor{whatsnew/3 16 removed-c-apis}@anchor{15e}
@subsubsection Removed C APIs


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s new in Python 3 15,What’s new in Python 3 14,What’s new in Python 3 16,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 15 doc}@anchor{15f}@anchor{whatsnew/3 15 translation-repo}@anchor{160}@anchor{whatsnew/3 15 what-s-new-in-python-3-15}@anchor{161}
@section What’s new in Python 3.15


@*Editor: 
Hugo van Kemenade


@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.15, compared to 3.14.

For full details, see the @ref{145,,changelog}.

@cartouche
@quotation Σημείωση 
Prerelease users should be aware that this document is currently in draft
form. It will be updated substantially as Python 3.15 moves towards release,
so it’s worth checking back even after reading earlier versions.
@end quotation
@end cartouche

@menu
* Summary – Release highlights:: 
* New features: New features<3>. 
* Other language changes: Other language changes<2>. 
* Default interactive shell:: 
* New modules: New modules<2>. 
* Improved modules: Improved modules<2>. 
* Optimizations: Optimizations<2>. 
* Removed: Removed<2>. 
* Deprecated: Deprecated<2>. 
* C API changes: C API changes<2>. 
* Build changes: Build changes<2>. 
* Porting to Python 3.15: Porting to Python 3 15. 

@end menu

@node Summary – Release highlights,New features<3>,,What’s new in Python 3 15
@anchor{whatsnew/3 15 summary-release-highlights}@anchor{162}
@subsection Summary – Release highlights


@c This section singles out the most important changes in Python 3.15.
@c Brevity is key.

@c PEP-sized items next.


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 810
PEP 810@footnote{https://peps.python.org/pep-0810/}: @ref{163,,Explicit lazy imports for faster startup times}

@item 
@geindex Python Enhancement Proposals; PEP 814
PEP 814@footnote{https://peps.python.org/pep-0814/}: @ref{164,,Add frozendict built-in type}

@item 
@geindex Python Enhancement Proposals; PEP 661
PEP 661@footnote{https://peps.python.org/pep-0661/}: @ref{165,,Add sentinel built-in type}

@item 
@geindex Python Enhancement Proposals; PEP 799
PEP 799@footnote{https://peps.python.org/pep-0799/}: @ref{166,,A dedicated profiling package for organizing Python profiling tools}

@item 
@geindex Python Enhancement Proposals; PEP 799
PEP 799@footnote{https://peps.python.org/pep-0799/}: @ref{167,,Tachyon; High frequency statistical sampling profiler}

@item 
@geindex Python Enhancement Proposals; PEP 831
PEP 831@footnote{https://peps.python.org/pep-0831/}: @ref{168,,Frame pointers are enabled by default for improved system-level observability}

@item 
@geindex Python Enhancement Proposals; PEP 798
PEP 798@footnote{https://peps.python.org/pep-0798/}: @ref{169,,Unpacking in comprehensions}

@item 
@geindex Python Enhancement Proposals; PEP 686
PEP 686@footnote{https://peps.python.org/pep-0686/}: @ref{16a,,Python now uses UTF-8 as the default encoding}

@item 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/}: @ref{16b,,Package startup configuration files}

@item 
@geindex Python Enhancement Proposals; PEP 728
PEP 728@footnote{https://peps.python.org/pep-0728/}: @ref{16c,,TypedDict with typed extra items}

@item 
@geindex Python Enhancement Proposals; PEP 747
PEP 747@footnote{https://peps.python.org/pep-0747/}: @ref{16d,,Annotating type forms with TypeForm}

@item 
@geindex Python Enhancement Proposals; PEP 800
PEP 800@footnote{https://peps.python.org/pep-0800/}: Disjoint bases in the type system

@item 
@geindex Python Enhancement Proposals; PEP 782
PEP 782@footnote{https://peps.python.org/pep-0782/}: @ref{16e,,A new PyBytesWriter C API to create a Python bytes object}

@item 
@geindex Python Enhancement Proposals; PEP 803
PEP 803@footnote{https://peps.python.org/pep-0803/}, 
@geindex Python Enhancement Proposals; PEP 820
820@footnote{https://peps.python.org/pep-0820/}, 
@geindex Python Enhancement Proposals; PEP 793
793@footnote{https://peps.python.org/pep-0793/}:
@ref{16f,,Stable ABI for free-threaded builds} and
related C API

@item 
@geindex Python Enhancement Proposals; PEP 788
PEP 788@footnote{https://peps.python.org/pep-0788/}: @ref{170,,Protection against finalization in the C API}

@item 
@ref{171,,The JIT compiler has been significantly upgraded}

@item 
@ref{172,,The official Windows 64-bit binaries now use the tail-calling interpreter}

@item 
@ref{173,,Improved error messages}

@item 
@ref{174,,More color}
@end itemize

@node New features<3>,Other language changes<2>,Summary – Release highlights,What’s new in Python 3 15
@anchor{whatsnew/3 15 new-features}@anchor{175}
@subsection New features


@menu
* PEP 810; Explicit lazy imports: PEP 810 Explicit lazy imports. 
* PEP 814; Add frozendict built-in type: PEP 814 Add frozendict built-in type. 
* PEP 661; Add sentinel built-in type: PEP 661 Add sentinel built-in type. 
* PEP 799; A dedicated profiling package: PEP 799 A dedicated profiling package. 
* Tachyon; High frequency statistical sampling profiler: Tachyon High frequency statistical sampling profiler. 
* PEP 831; Frame pointers enabled by default: PEP 831 Frame pointers enabled by default. 
* PEP 798; Unpacking in comprehensions: PEP 798 Unpacking in comprehensions. 
* PEP 829; Package startup configuration files: PEP 829 Package startup configuration files. 
* PEP 803 – Stable ABI for free-threaded builds:: 
* PEP 788; Protecting the C API from interpreter finalization: PEP 788 Protecting the C API from interpreter finalization. 
* Improved error messages:: 

@end menu

@node PEP 810 Explicit lazy imports,PEP 814 Add frozendict built-in type,,New features<3>
@anchor{whatsnew/3 15 pep-810-explicit-lazy-imports}@anchor{176}@anchor{whatsnew/3 15 whatsnew315-lazy-imports}@anchor{163}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 810
`PEP 810': Explicit lazy imports


Large Python applications often suffer from slow startup times. A
significant contributor to this problem is the import system: when a module
is imported, Python must locate the file, read it from disk, compile it to
bytecode, and execute all top-level code. For applications with deep
dependency trees, this process can take seconds, even when most of the
imported code is never actually used during a particular run.

Developers have worked around this by moving imports inside functions, using
@ref{7a,,importlib} to load modules on demand, or restructuring code to avoid
unnecessary dependencies. These approaches work but make code harder to read
and maintain, scatter import statements throughout the codebase, and require
discipline to apply consistently.

Python now provides a cleaner solution through explicit @ref{177,,lazy}
imports using the new @code{lazy} soft keyword. When you mark an import as
lazy, Python defers the actual module loading until the imported name is
first used. This gives you the organizational benefits of declaring all
imports at the top of the file while only paying the loading cost for
modules you actually use.

The @code{lazy} keyword works with both @code{import} and @code{from ... import}
statements. When you write @code{lazy import heavy_module}, Python does not
immediately load the module. Instead, it creates a lightweight proxy object.
The actual module loading happens transparently when you first access the
name:

@example
lazy import json
lazy from pathlib import Path

print("Starting up...")  # json and pathlib not loaded yet

data = json.loads('@{"key": "value"@}')  # json loads here
p = Path(".")  # pathlib loads here
@end example

This mechanism is particularly useful for applications that import many
modules at the top level but may only use a subset of them in any given run.
The deferred loading reduces startup latency without requiring code
restructuring or conditional imports scattered throughout the codebase.

In the case where loading a lazily imported module fails (for example, if
the module does not exist), Python raises the exception at the point of
first use rather than at import time. The associated traceback includes both
the location where the name was accessed and the original import statement,
making it straightforward to diagnose and debug the failure.

For cases where you want to enable lazy loading globally without modifying
source code, Python provides the @ref{178,,-X lazy_imports} command-line
option and the 
@geindex PYTHON_LAZY_IMPORTS
@geindex μεταβλητή περιβάλλοντος; PYTHON_LAZY_IMPORTS
@ref{179,,PYTHON_LAZY_IMPORTS} environment variable. Both
accept three values: @code{all} makes all imports lazy by default, @code{none}
disables lazy imports entirely (even explicit @code{lazy} statements become
eager), and @code{normal} (the default) respects the @code{lazy} keyword in source
code. The @ref{17a,,sys.set_lazy_imports()} and @ref{17b,,sys.get_lazy_imports()}
functions allow changing and querying this mode at runtime.

For more selective control, @ref{17c,,sys.set_lazy_imports_filter()} accepts a
callable that determines whether a specific module should be loaded lazily.
The filter receives three arguments: the importing module’s name (or
@code{None}), the imported module’s name, and the fromlist (or @code{None} for
regular imports). It should return @code{True} to allow the import to be lazy,
or @code{False} to force eager loading. This allows patterns like making only
your own application’s modules lazy while keeping third-party dependencies
eager:

@example
import sys

def myapp_filter(importing, imported, fromlist):
    return imported.startswith("myapp.")
sys.set_lazy_imports_filter(myapp_filter)
sys.set_lazy_imports("all")

import myapp.slow_module  # lazy (matches filter)
import json               # eager (does not match filter)
@end example

The proxy type itself is available as @ref{17d,,types.LazyImportType} for code
that needs to detect lazy imports programmatically.

There are some restrictions on where the @code{lazy} keyword can be used. Lazy
imports are only permitted at module scope; using @code{lazy} inside a
function, class body, or @code{try}/@code{except}/@code{finally} block raises a
@ref{17e,,SyntaxError}. Neither star imports nor future imports can be lazy
(@code{lazy from module import *} and @code{lazy from __future__ import ...} both
raise @code{SyntaxError}).

For code that cannot use the @code{lazy} keyword directly (for example, when
supporting Python versions older than 3.15 while still using lazy
imports on 3.15+), a module can define
@ref{17f,,__lazy_modules__} as a container of fully qualified module
name strings.  Regular @code{import} statements for those modules are then treated
as lazy, with the same semantics as the @code{lazy} keyword:

@example
__lazy_modules__ = ["json", "pathlib"]

import json     # lazy
import os       # still eager
@end example


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 810
PEP 810@footnote{https://peps.python.org/pep-0810/} for the full specification and rationale.


(Contributed by Pablo Galindo Salgado and Dino Viehland in gh-142349@footnote{https://github.com/python/cpython/issues/142349}.)

@node PEP 814 Add frozendict built-in type,PEP 661 Add sentinel built-in type,PEP 810 Explicit lazy imports,New features<3>
@anchor{whatsnew/3 15 pep-814-add-frozendict-built-in-type}@anchor{180}@anchor{whatsnew/3 15 whatsnew315-frozendict}@anchor{164}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 814
`PEP 814': Add frozendict built-in type


A new @ref{181,,immutable} type, @ref{182,,frozendict}, is added to the @ref{13,,builtins} module.
It does not allow modification after creation. A @code{frozendict} is not a subclass of @code{dict};
it inherits directly from @code{object}. A @code{frozendict} is @ref{183,,hashable}
as long as all of its keys and values are hashable. A @code{frozendict} preserves
insertion order, but comparison does not take order into account.

For example:

@example
>>> a = frozendict(x=1, y=2)
>>> a
frozendict(@{'x': 1, 'y': 2@})
>>> a['z'] = 3
Traceback (most recent call last):
  File "<python-input-2>", line 1, in <module>
    a['z'] = 3
    ~^^^^^
TypeError: 'frozendict' object does not support item assignment
>>> b = frozendict(y=2, x=1)
>>> hash(a) == hash(b)
True
>>> a == b
True
@end example

The following standard library modules have been updated to accept
@code{frozendict}: @ref{29,,copy}, @ref{39,,decimal}, @ref{85,,json}, @ref{90,,marshal},
@ref{b0,,plistlib} (only for serialization), @ref{ab,,pickle}, @ref{b3,,pprint} and
@ref{12e,,xml.etree.ElementTree}.

@ref{184,,eval()} and @ref{185,,exec()} accept @code{frozendict} for `globals', and
@ref{186,,type()} and @ref{187,,str.maketrans()} accept @code{frozendict} for `dict'.

Code checking for @ref{188,,dict} type using @code{isinstance(arg, dict)} can be
updated to @code{isinstance(arg, (dict, frozendict))} to accept also the
@code{frozendict} type, or to @code{isinstance(arg, collections.abc.Mapping)}
to accept also other mapping types such as @ref{189,,MappingProxyType}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 814
PEP 814@footnote{https://peps.python.org/pep-0814/} for the full specification and rationale.


(Contributed by Victor Stinner and Donghee Na in gh-141510@footnote{https://github.com/python/cpython/issues/141510}.)

@node PEP 661 Add sentinel built-in type,PEP 799 A dedicated profiling package,PEP 814 Add frozendict built-in type,New features<3>
@anchor{whatsnew/3 15 pep-661-add-sentinel-built-in-type}@anchor{18a}@anchor{whatsnew/3 15 whatsnew315-sentinel}@anchor{165}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 661
`PEP 661': Add sentinel built-in type


A new @ref{18b,,sentinel} type is added to the @ref{13,,builtins} module for
creating unique sentinel values with a concise representation.  Sentinel
objects preserve identity when copied, support use in type expressions with
the @code{|} operator, and can be pickled when they are importable by module and
name.

(PEP by Tal Einat; contributed by Jelle Zijlstra in gh-148829@footnote{https://github.com/python/cpython/issues/148829}.)


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 661
PEP 661@footnote{https://peps.python.org/pep-0661/} for further details.


@node PEP 799 A dedicated profiling package,Tachyon High frequency statistical sampling profiler,PEP 661 Add sentinel built-in type,New features<3>
@anchor{whatsnew/3 15 pep-799-a-dedicated-profiling-package}@anchor{18c}@anchor{whatsnew/3 15 whatsnew315-profiling-package}@anchor{166}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 799
`PEP 799': A dedicated profiling package


A new @ref{b5,,profiling} module has been added to organize Python’s built-in
profiling tools under a single, coherent namespace. This module contains:


@itemize *

@item 
@ref{b7,,profiling.tracing}: deterministic function-call tracing (relocated from
@code{cProfile}).

@item 
@ref{b6,,profiling.sampling}: a new statistical sampling profiler (named Tachyon).
@end itemize

The @code{cProfile} module remains as an alias for backwards compatibility.
The @ref{b4,,profile} module is deprecated and will be removed in Python 3.17.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 799
PEP 799@footnote{https://peps.python.org/pep-0799/} for further details.


(Contributed by Pablo Galindo and László Kiss Kollár in gh-138122@footnote{https://github.com/python/cpython/issues/138122}.)

@node Tachyon High frequency statistical sampling profiler,PEP 831 Frame pointers enabled by default,PEP 799 A dedicated profiling package,New features<3>
@anchor{whatsnew/3 15 tachyon-high-frequency-statistical-sampling-profiler}@anchor{18d}@anchor{whatsnew/3 15 whatsnew315-sampling-profiler}@anchor{167}
@subsubsection Tachyon: High frequency statistical sampling profiler


@image{python-figures/tachyon-logo,,,Tachyon profiler logo,png}

A new statistical sampling profiler (Tachyon) has been added as
@ref{b6,,profiling.sampling}. This profiler enables low-overhead performance analysis of
running Python processes without requiring code modification or process restart.

Unlike deterministic profilers (such as @ref{b7,,profiling.tracing}) that instrument
every function call, the sampling profiler periodically captures stack traces from
running processes.  This approach provides virtually zero overhead while achieving
sampling rates of `up to 1,000,000 Hz', making it the fastest sampling profiler
available for Python (at the time of its contribution) and ideal for debugging
performance issues in production environments. This capability is particularly
valuable for debugging performance issues in production systems where traditional
profiling approaches would be too intrusive.

Key features include:


@itemize *

@item 
`Zero-overhead profiling': Attach to any running Python process without
affecting its performance. Ideal for production debugging where you can’t afford
to restart or slow down your application.

@item 
`No code modification required': Profile existing applications without restart.
Simply point the profiler at a running process by PID and start collecting data.

@item 
`Flexible target modes':


@itemize *

@item 
Profile running processes by PID (@code{attach}) - attach to already-running applications

@item 
Run and profile scripts directly (@code{run}) - profile from the very start of execution

@item 
Execute and profile modules (@code{run -m}) - profile packages run as @code{python -m module}

@item 
Capture a one-shot snapshot of a running process (@code{dump}) - print a
traceback-style stack of every thread (or all asyncio tasks with
@code{--async-aware}). Useful for investigating hung processes.
@end itemize

@item 
`Multiple profiling modes': Choose what to measure based on your performance investigation:


@itemize *

@item 
`Wall-clock time' (@code{--mode wall}, default): Measures real elapsed time including I/O,
network waits, and blocking operations. Use this to understand where your program spends
calendar time, including when waiting for external resources.

@item 
`CPU time' (@code{--mode cpu}): Measures only active CPU execution time, excluding I/O waits
and blocking. Use this to identify CPU-bound bottlenecks and optimize computational work.

@item 
`GIL-holding time' (@code{--mode gil}): Measures time spent holding Python’s Global Interpreter
Lock. Use this to identify which threads dominate GIL usage in multi-threaded applications.

@item 
`Exception handling time' (@code{--mode exception}): Captures samples only from threads with
an active exception. Use this to analyze exception handling overhead.
@end itemize

@item 
`Thread-aware profiling': Option to profile all threads (@code{-a}) or just the main thread,
essential for understanding multi-threaded application behavior.

@item 
`Multiple output formats': Choose the visualization that best fits your workflow:


@itemize *

@item 
@code{--pstats}: Detailed tabular statistics compatible with @ref{b8,,pstats}. Shows function-level
timing with direct and cumulative samples. Best for detailed analysis and integration with
existing Python profiling tools.

@item 
@code{--collapsed}: Generates collapsed stack traces (one line per stack). This format is
specifically designed for creating flame graphs with external tools like Brendan Gregg’s
FlameGraph scripts or speedscope.

@item 
@code{--flamegraph}: Generates a self-contained interactive HTML flame graph using D3.js.
Opens directly in your browser for immediate visual analysis. Flame graphs show the call
hierarchy where width represents time spent, making it easy to spot bottlenecks at a glance.

@item 
@code{--gecko}: Generates Gecko Profiler format compatible with Firefox Profiler@footnote{https://profiler.firefox.com}. Upload the output to Firefox Profiler for advanced
timeline-based analysis with features like stack charts, markers, and network activity.

@item 
@code{--heatmap}: Generates an interactive HTML heatmap visualization with line-level sample
counts. Creates a directory with per-file heatmaps showing exactly where time is spent
at the source code level.
@end itemize

@item 
`Live interactive mode': Real-time TUI profiler with a top-like interface (@code{--live}).
Monitor performance as your application runs with interactive sorting and filtering.

@item 
`Async-aware profiling': Profile async/await code with task-based stack reconstruction
(@code{--async-aware}). See which coroutines are consuming time, with options to show only
running tasks or all tasks including those waiting.

@item 
`Opcode-level profiling': Gather bytecode opcode information for instruction-level
profiling (@code{--opcodes}). Shows which bytecode instructions are executing, including
specializations from the adaptive interpreter.
@end itemize

See @ref{b6,,profiling.sampling} for the complete documentation, including all
available output formats, profiling modes, and configuration options.

(Contributed by Pablo Galindo and László Kiss Kollár in gh-135953@footnote{https://github.com/python/cpython/issues/135953} and gh-138122@footnote{https://github.com/python/cpython/issues/138122}.)

@node PEP 831 Frame pointers enabled by default,PEP 798 Unpacking in comprehensions,Tachyon High frequency statistical sampling profiler,New features<3>
@anchor{whatsnew/3 15 pep-831-frame-pointers-enabled-by-default}@anchor{18e}@anchor{whatsnew/3 15 whatsnew315-frame-pointers}@anchor{168}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 831
`PEP 831': Frame pointers enabled by default


CPython is now built with frame pointers by default on platforms that support
them.  This uses the compiler flags @code{-fno-omit-frame-pointer} and
@code{-mno-omit-leaf-frame-pointer}, making native stack unwinding faster and
more reliable for system profilers, debuggers, crash analysis tools, and
eBPF-based observability tools.

The flags are exposed through @ref{e4,,sysconfig}, so extension modules built by
tools that consume Python’s build configuration inherit frame pointers by
default.  This propagation is intentional: mixed Python/native profiling needs
an unbroken frame-pointer chain through the interpreter, extension modules,
embedding applications, and native libraries.

@cartouche
@quotation Σημαντικό 
Third-party build backends and native build systems should preserve these
flags when they consume Python’s @ref{e4,,sysconfig} values.  Build systems
that compile C, C++, Rust, or other native code without inheriting Python’s
compiler flags should enable equivalent frame-pointer flags themselves.  A
single native component built without frame pointers can break stack
unwinding for the whole Python process.
@end quotation
@end cartouche

(Contributed by Pablo Galindo Salgado and Savannah Ostrowski in
gh-149201@footnote{https://github.com/python/cpython/issues/149201}; PEP 831 written by Pablo Galindo Salgado, Ken Jin,
Savannah Ostrowski, and Diego Russo.)


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 831
PEP 831@footnote{https://peps.python.org/pep-0831/} for further details.


@node PEP 798 Unpacking in comprehensions,PEP 829 Package startup configuration files,PEP 831 Frame pointers enabled by default,New features<3>
@anchor{whatsnew/3 15 pep-798-unpacking-in-comprehensions}@anchor{18f}@anchor{whatsnew/3 15 whatsnew315-unpacking-in-comprehensions}@anchor{169}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 798
`PEP 798': Unpacking in comprehensions


List, set, and dictionary comprehensions, as well as generator expressions, now
support unpacking with @code{*} and @code{**}.  This extends the unpacking syntax
from 
@geindex Python Enhancement Proposals; PEP 448
PEP 448@footnote{https://peps.python.org/pep-0448/} to comprehensions, providing a new syntax for combining an
arbitrary number of iterables or dictionaries into a single flat structure.
This new syntax is a direct alternative to nested comprehensions,
@ref{190,,itertools.chain()}, and @ref{191,,itertools.chain.from_iterable()}.  For
example:

@example
>>> lists = [[1, 2], [3, 4], [5]]
>>> [*L for L in lists]  # equivalent to [x for L in lists for x in L]
[1, 2, 3, 4, 5]

>>> sets = [@{1, 2@}, @{2, 3@}, @{3, 4@}]
>>> @{*s for s in sets@}  # equivalent to @{x for s in sets for x in s@}
@{1, 2, 3, 4@}

>>> dicts = [@{'a': 1@}, @{'b': 2@}, @{'a': 3@}]
>>> @{**d for d in dicts@}  # equivalent to @{k: v for d in dicts for k,v in d.items()@}
@{'a': 3, 'b': 2@}
@end example

Generator expressions can similarly use unpacking to yield values from multiple
iterables:

@example
>>> gen = (*L for L in lists)  # equivalent to (x for L in lists for x in L)
>>> list(gen)
[1, 2, 3, 4, 5]
@end example

This change also extends to asynchronous generator expressions, such that, for
example, @code{(*a async for a in agen())} is equivalent to @code{(x async for a in
agen() for x in a)}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 798
PEP 798@footnote{https://peps.python.org/pep-0798/} for further details.


(Contributed by Adam Hartz in gh-143055@footnote{https://github.com/python/cpython/issues/143055}.)

@node PEP 829 Package startup configuration files,PEP 803 – Stable ABI for free-threaded builds,PEP 798 Unpacking in comprehensions,New features<3>
@anchor{whatsnew/3 15 pep-829-package-startup-configuration-files}@anchor{192}@anchor{whatsnew/3 15 whatsnew315-startup-files}@anchor{16b}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 829
`PEP 829': Package startup configuration files


Loaded by the @ref{cf,,site} module when @code{-S} is not given, @ref{193,,.pth files}
can contain lines that both extend @ref{194,,sys.path} and execute arbitrary code
when the line starts with @code{import} (followed by a space or tab).  The latter
functionality can be problematic, since it is difficult to know exactly what
gets executed when Python starts up.

As a step towards improving the ability to audit pre-start executable code,
Python 3.15 introduces @ref{195,,.start files} which contain entry point
specifications of the form @code{pkg.mod:callable} where @code{pkg.mod} is the
import path to the given callable.  When Python starts up, the callable is
located and called with no arguments.

@code{import} lines in @code{.pth} files are silently deprecated.  When a
matching @code{.start} file is found, @code{import} lines in @code{.pth} files
are ignored.  There is no change to @ref{194,,sys.path} extension lines in
@code{.pth} files.

(Contributed by Barry Warsaw in gh-148641@footnote{https://github.com/python/cpython/issues/148641}.)

@node PEP 803 – Stable ABI for free-threaded builds,PEP 788 Protecting the C API from interpreter finalization,PEP 829 Package startup configuration files,New features<3>
@anchor{whatsnew/3 15 pep-803-stable-abi-for-free-threaded-builds}@anchor{196}@anchor{whatsnew/3 15 whatsnew315-abi3t}@anchor{16f}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 803
`PEP 803' – Stable ABI for free-threaded builds


C extensions that target the @ref{197,,Stable ABI} can now be
compiled for the new `Stable ABI for Free-Threaded Builds' (also known
as @code{abi3t}), which makes them compatible with
@ref{198,,free-threaded builds} of CPython.
This usually requires some non-trivial changes to the source code;
specifically:


@itemize -

@item 
Switching to API introduced in 
@geindex Python Enhancement Proposals; PEP 697
PEP 697@footnote{https://peps.python.org/pep-0697/} (Python 3.12), such as
negative @ref{199,,basicsize} and
@ref{19a,,PyObject_GetTypeData()}, rather than making @ref{19b,,PyObject}
part of the instance struct; and

@item 
Switching from a @code{PyInit_} function to a new export hook,
@ref{19c,,PyModExport_*}, introduced for this
purpose in 
@geindex Python Enhancement Proposals; PEP 793
PEP 793@footnote{https://peps.python.org/pep-0793/}, with a new @ref{19d,,PySlot} structure
introduced in 
@geindex Python Enhancement Proposals; PEP 820
PEP 820@footnote{https://peps.python.org/pep-0820/}.
@end itemize

The reference documentation for these features is complete, but currently
aimed at early adopters.
A migration guide is planned for an upcoming beta release.

Note that Stable ABI does not offer all the functionality that CPython
has to offer.
Extensions that cannot switch to @code{abi3t} should continue to build for
the existing Stable ABI (@code{abi3}) and the version-specific ABI for
free-threading (@code{cp315t}) separately.

Stable ABI for Free-Threaded Builds should typically
be selected in a build tool (such as, for example, Setuptools, meson-python,
scikit-build-core, or Maturin).
At the time of writing, these tools did `not' support @code{abi3t}.
If this is the case for your tool, compile for @code{cp315t} separately.
If not using a build tool – or when writing such a tool – you can select
@code{abi3t} by setting the macro @code{Py_TARGET_ABI3T} as discussed
in @ref{19e,,Compiling for Stable ABI}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 803
PEP 803@footnote{https://peps.python.org/pep-0803/} for further details.


@node PEP 788 Protecting the C API from interpreter finalization,Improved error messages,PEP 803 – Stable ABI for free-threaded builds,New features<3>
@anchor{whatsnew/3 15 pep-788-protecting-the-c-api-from-interpreter-finalization}@anchor{19f}@anchor{whatsnew/3 15 whatsnew315-c-api-interpreter-finalization}@anchor{170}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 788
`PEP 788': Protecting the C API from interpreter finalization


In the C API, @ref{1a0,,interpreter finalization} can be
problematic for many extensions, because @ref{1a1,,attaching} a thread state will permanently hang the thread, resulting in deadlocks
and other spurious issues. Additionally, it has historically been impossible
to safely check whether an interpreter is alive before using it, leading to crashes
when a thread concurrently deletes an interpreter while another thread is
trying to attach to it.

There are now several new suites of APIs to circumvent these problems:


@itemize *

@item 
@ref{1a2,,Interpreter guards}, which prevent an interpreter
from finalizing.

@item 
@ref{1a3,,Interpreter views}, which allow thread-safe access
to an interpreter that may be concurrently finalizing or deleted.

@item 
@ref{1a4,,New APIs} to automatically attach and detach
thread states that come with built-in protection against finalization.
@end itemize

In addition, APIs in the @code{PyGILState} family (most notably
@ref{1a5,,PyGILState_Ensure()} and @ref{1a6,,PyGILState_Release()}) have been
@ref{1a7,,soft deprecated}. There is `no' plan to remove them, and existing
code will continue to work, but there will be no new @code{PyGILState} APIs
in future versions of Python.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 788
PEP 788@footnote{https://peps.python.org/pep-0788/} for further details.


(Contributed by Peter Bierma in gh-149101@footnote{https://github.com/python/cpython/issues/149101}.)

@node Improved error messages,,PEP 788 Protecting the C API from interpreter finalization,New features<3>
@anchor{whatsnew/3 15 improved-error-messages}@anchor{1a8}@anchor{whatsnew/3 15 whatsnew315-improved-error-messages}@anchor{173}
@subsubsection Improved error messages



@itemize *

@item 
The interpreter now provides more helpful suggestions in @ref{1a9,,AttributeError}
exceptions when accessing an attribute on an object that does not exist, but
a similar attribute is available through one of its members.

For example, if the object has an attribute that itself exposes the requested
name, the error message will suggest accessing it via that inner attribute:

@example
@@dataclass
class Circle:
   radius: float

   @@property
   def area(self) -> float:
      return pi * self.radius**2

class Container:
   def __init__(self, inner: Circle) -> None:
      self.inner = inner

circle = Circle(radius=4.0)
container = Container(circle)
print(container.area)
@end example

Running this code now produces a clearer suggestion:

@example
Traceback (most recent call last):
  File "/home/pablogsal/github/python/main/lel.py", line 42, in <module>
    print(container.area)
          ^^^^^^^^^^^^^^
AttributeError: 'Container' object has no attribute 'area'. Did you mean '.inner.area' instead of '.area'?
@end example

@item 
When an @ref{1a9,,AttributeError} on a builtin type has no close match via
Levenshtein distance, the error message now checks a static table of common
method names from other languages (JavaScript, Java, Ruby, C#) and suggests
the Python equivalent:

@example
>>> [1, 2, 3].push(4)
Traceback (most recent call last):
...
AttributeError: 'list' object has no attribute 'push'. Did you mean '.append'?

>>> 'hello'.toUpperCase()
Traceback (most recent call last):
...
AttributeError: 'str' object has no attribute 'toUpperCase'. Did you mean '.upper'?
@end example

When the Python equivalent is a language construct rather than a method,
the hint describes the construct directly:

@example
>>> @{@}.put("a", 1)
Traceback (most recent call last):
...
AttributeError: 'dict' object has no attribute 'put'. Use d[k] = v.
@end example

When a mutable method is called on an immutable type, the hint suggests
the mutable counterpart:

@example
>>> (1, 2, 3).append(4)
Traceback (most recent call last):
...
AttributeError: 'tuple' object has no attribute 'append'. Did you mean to use a 'list' object?
@end example

These hints also work for subclasses of builtin types.

(Contributed by Matt Van Horn in gh-146406@footnote{https://github.com/python/cpython/issues/146406}.)

@item 
The interpreter now tries to provide a suggestion when
@ref{1aa,,delattr()} fails due to a missing attribute.
When an attribute name that closely resembles an existing attribute is used,
the interpreter will suggest the correct attribute name in the error message.
For example:

@example
>>> class A:
...     pass
>>> a = A()
>>> a.abcde = 1
>>> del a.abcdf
Traceback (most recent call last):
...
AttributeError: 'A' object has no attribute 'abcdf'. Did you mean: 'abcde'?
@end example

(Contributed by Nikita Sobolev and Pranjal Prajapati in gh-136588@footnote{https://github.com/python/cpython/issues/136588}.)

@item 
Several error messages incorrectly using the term «argument» have been corrected.
(Contributed by Stan Ulbrych in gh-133382@footnote{https://github.com/python/cpython/issues/133382}.)
@end itemize

@node Other language changes<2>,Default interactive shell,New features<3>,What’s new in Python 3 15
@anchor{whatsnew/3 15 other-language-changes}@anchor{1ab}
@subsection Other language changes

@anchor{whatsnew/3 15 whatsnew315-utf8-default}@anchor{16a}

@itemize *

@item 
Python now uses UTF-8@footnote{https://en.wikipedia.org/wiki/UTF-8} as the default encoding, independent of the system’s
environment. This means that I/O operations without an explicit encoding,
for example, @code{open('flying-circus.txt')}, will use UTF-8.
UTF-8 is a widely-supported Unicode@footnote{https://home.unicode.org/} character encoding that has become a
`de facto' standard for representing text, including nearly every webpage
on the internet, many common file formats, programming languages, and more.

This only applies when no @code{encoding} argument is given. For best
compatibility between versions of Python, ensure that an explicit @code{encoding}
argument is always provided. The @ref{1ac,,opt-in encoding warning}
can be used to identify code that may be affected by this change.
The special @code{encoding='locale'} argument uses the current locale
encoding, and has been supported since Python 3.10.

To retain the previous behaviour, Python’s UTF-8 mode may be disabled with
the 
@geindex PYTHONUTF8
@geindex μεταβλητή περιβάλλοντος; PYTHONUTF8
@ref{1ad,,PYTHONUTF8=0} environment variable or the
@ref{178,,-X utf8=0} command-line option.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 686
PEP 686@footnote{https://peps.python.org/pep-0686/} for further details.


(Contributed by Adam Turner in gh-133711@footnote{https://github.com/python/cpython/issues/133711}; PEP 686 written by Inada Naoki.)
@anchor{whatsnew/3 15 whatsnew315-color-interpreter-help}@anchor{1ae}
@item 
The interpreter help (such as @code{python --help}) is now in color.
This can be controlled by @ref{1af,,environment variables}.
(Contributed by Hugo van Kemenade in gh-148766@footnote{https://github.com/python/cpython/issues/148766}.)
@anchor{whatsnew/3 15 whatsnew315-color-exceptions}@anchor{1b0}
@item 
Unraisable exceptions are now highlighted with color by default. This can be
controlled by @ref{1af,,environment variables}.
(Contributed by Peter Bierma in gh-134170@footnote{https://github.com/python/cpython/issues/134170}.)
@anchor{whatsnew/3 15 whatsnew315-more-color}@anchor{174}
@item 
More color in
@ref{1b1,,argparse},
@ref{1b2,,ast},
@ref{1b3,,calendar},
@ref{1b4,,difflib},
@ref{1b5,,http.server},
@ref{1b6,,pickletools},
@ref{1b7,,PyREPL tab completion},
@ref{1ae,,python –help},
@ref{1b8,,sqlite3},
@ref{1b9,,timeit},
@ref{1ba,,tokenize},
@ref{1b0,,unraisable exceptions} and
@ref{1bb,,stdlib} (ast, compileall, doctest, gzip, inspect, json.tool, pdb,
profiling.sampling, random, regrtest, sqlite3, timeit, tokenize, trace,
unittest, uuid, zipapp, zipfile) CLI help.

@item 
The @ref{1bc,,__repr__()} of @ref{1bd,,ImportError} and @ref{1be,,ModuleNotFoundError}
now shows «name» and «path» as @code{name=<name>} and @code{path=<path>} if they were given
as keyword arguments at construction time.
(Contributed by Serhiy Storchaka, Oleg Iarygin, and Yoav Nir in gh-74185@footnote{https://github.com/python/cpython/issues/74185}.)

@item 
The @ref{1bf,,__dict__} and @code{__weakref__} descriptors now use a
single descriptor instance per interpreter, shared across all types that
need them.
This speeds up class creation, and helps avoid reference cycles.
(Contributed by Petr Viktorin in gh-135228@footnote{https://github.com/python/cpython/issues/135228}.)

@item 
The @ref{1c0,,-W} option and the 
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,PYTHONWARNINGS} environment variable
can now specify regular expressions instead of literal strings to match
the warning message and the module name, if the corresponding field starts
and ends with a forward slash (@code{/}).
(Contributed by Serhiy Storchaka in gh-134716@footnote{https://github.com/python/cpython/issues/134716}.)

@item 
Functions that take timestamp or timeout arguments now accept any real
numbers (such as @ref{1c2,,Decimal} and @ref{1c3,,Fraction}),
not only integers or floats, although this does not improve precision.
(Contributed by Serhiy Storchaka in gh-67795@footnote{https://github.com/python/cpython/issues/67795}.)
@end itemize
@anchor{whatsnew/3 15 whatsnew315-bytearray-take-bytes}@anchor{1c4}

@itemize *

@item 
Added @ref{1c5,,bytearray.take_bytes(n=None@comma{} /)} to take
bytes out of a @ref{1c6,,bytearray} without copying. This enables optimizing code
which must return @ref{1c7,,bytes} after working with a mutable buffer of bytes
such as data buffering, network protocol parsing, encoding, decoding,
and compression. Common code patterns which can be optimized with
@ref{1c5,,take_bytes()} are listed below.
Suggested optimizing refactors



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Description

@tab

Old

@tab

New

@item

Return @ref{1c7,,bytes} after working with @ref{1c6,,bytearray}

@tab

@example
def read() -> bytes:
    buffer = bytearray(1024)
    ...
    return bytes(buffer)
@end example

@tab

@example
def read() -> bytes:
    buffer = bytearray(1024)
    ...
    return buffer.take_bytes()
@end example

@item

Empty a buffer getting the bytes

@tab

@example
buffer = bytearray(1024)
...
data = bytes(buffer)
buffer.clear()
@end example

@tab

@example
buffer = bytearray(1024)
...
data = buffer.take_bytes()
@end example

@item

Split a buffer at a specific separator

@tab

@example
buffer = bytearray(b'abc\ndef')
n = buffer.find(b'\n')
data = bytes(buffer[:n + 1])
del buffer[:n + 1]
assert data == b'abc\n'
assert buffer == bytearray(b'def')
@end example

@tab

@example
buffer = bytearray(b'abc\ndef')
n = buffer.find(b'\n')
data = buffer.take_bytes(n + 1)
@end example

@item

Split a buffer at a specific separator; discard after the separator

@tab

@example
buffer = bytearray(b'abc\ndef')
n = buffer.find(b'\n')
data = bytes(buffer[:n])
buffer.clear()
assert data == b'abc'
assert len(buffer) == 0
@end example

@tab

@example
buffer = bytearray(b'abc\ndef')
n = buffer.find(b'\n')
buffer.resize(n)
data = buffer.take_bytes()
@end example

@end multitable


(Contributed by Cody Maloney in gh-139871@footnote{https://github.com/python/cpython/issues/139871}.)

@item 
Many functions related to compiling or parsing Python code, such as
@ref{1c8,,compile()}, @ref{1c9,,ast.parse()}, @ref{1ca,,symtable.symtable()},
and @ref{1cb,,importlib.abc.InspectLoader.source_to_code()}, now allow the module
name to be passed. It is needed to unambiguously @ref{1cc,,filter}
syntax warnings by module name.
(Contributed by Serhiy Storchaka in gh-135801@footnote{https://github.com/python/cpython/issues/135801}.)

@item 
Allowed defining the `__dict__' and `__weakref__' @ref{1cd,,__slots__}
for any class.
(Contributed by Serhiy Storchaka in gh-41779@footnote{https://github.com/python/cpython/issues/41779}.)

@item 
Allowed defining any @ref{1cd,,__slots__} for a class derived from
@ref{1ce,,tuple} (including classes created by @ref{1cf,,collections.namedtuple()}).
(Contributed by Serhiy Storchaka in gh-41779@footnote{https://github.com/python/cpython/issues/41779}.)

@item 
The @ref{1d0,,slice} type now supports subscription,
making it a @ref{1d1,,generic type}.
(Contributed by James Hilton-Balfe in gh-128335@footnote{https://github.com/python/cpython/issues/128335}.)

@item 
The class @ref{1d2,,memoryview} now supports the float complex and
double complex C types: formatting characters @code{'Zf'} and @code{'Zd'}
respectively.
(Contributed by Victor Stinner in gh-146151@footnote{https://github.com/python/cpython/issues/146151} and gh-148675@footnote{https://github.com/python/cpython/issues/148675}.)

@item 
Allow the `count' argument of @ref{1d3,,bytes.replace()} to be a keyword.
(Contributed by Stan Ulbrych in gh-147856@footnote{https://github.com/python/cpython/issues/147856}.)

@item 
Unary plus is now accepted in @ref{1d4,,match} literal patterns, mirroring
the existing support for unary minus.
(Contributed by Bartosz Sławecki in gh-145239@footnote{https://github.com/python/cpython/issues/145239}.)

@item 
The import system now acquires per-module locks in hierarchical order
(parent packages before their submodules). This fixes a long-standing
deadlock where one thread importing @code{pkg.sub} and another importing
@code{pkg.sub.mod} could each block the other when @code{pkg/sub/__init__.py}
imports @code{pkg.sub.mod}.
(Contributed by Gregory P. Smith in gh-83065@footnote{https://github.com/python/cpython/issues/83065}.)
@end itemize

@node Default interactive shell,New modules<2>,Other language changes<2>,What’s new in Python 3 15
@anchor{whatsnew/3 15 default-interactive-shell}@anchor{1d5}
@subsection Default interactive shell

@anchor{whatsnew/3 15 whatsnew315-pyrepl-completion}@anchor{1b7}

@itemize *

@item 
Tab completions are now colored by object kind, based on
fancycompleter@footnote{https://pypi.org/project/fancycompleter/}.
Set 
@geindex PYTHON_BASIC_COMPLETER
@geindex μεταβλητή περιβάλλοντος; PYTHON_BASIC_COMPLETER
@ref{1d6,,PYTHON_BASIC_COMPLETER} to fall back to @ref{c5,,rlcompleter}.
Color can also be controlled by @ref{1af,,environment variables}.
(Contributed by Antonio Cuni and Pablo Galindo in gh-130472@footnote{https://github.com/python/cpython/issues/130472}.)
@end itemize

@node New modules<2>,Improved modules<2>,Default interactive shell,What’s new in Python 3 15
@anchor{whatsnew/3 15 new-modules}@anchor{1d7}
@subsection New modules


@menu
* math.integer: math integer. 

@end menu

@node math integer,,,New modules<2>
@anchor{whatsnew/3 15 math-integer}@anchor{1d8}
@subsubsection math.integer


This module provides access to the mathematical functions for integer
arguments (
@geindex Python Enhancement Proposals; PEP 791
PEP 791@footnote{https://peps.python.org/pep-0791/}).
(Contributed by Serhiy Storchaka in gh-81313@footnote{https://github.com/python/cpython/issues/81313}.)

@node Improved modules<2>,Optimizations<2>,New modules<2>,What’s new in Python 3 15
@anchor{whatsnew/3 15 improved-modules}@anchor{1d9}
@subsection Improved modules


@menu
* argparse:: 
* array:: 
* ast:: 
* asyncio:: 
* base64:: 
* binascii:: 
* calendar:: 
* collections:: 
* concurrent.futures: concurrent futures. 
* contextlib:: 
* dataclasses:: 
* dbm:: 
* difflib:: 
* email:: 
* faulthandler:: 
* functools: functools<2>. 
* gc:: 
* hashlib:: 
* http.client: http client. 
* http.server: http server. 
* inspect:: 
* json:: 
* locale:: 
* math:: 
* mimetypes:: 
* mmap:: 
* os:: 
* os.path: os path. 
* pdb:: 
* pickle:: 
* pickletools:: 
* pprint:: 
* re:: 
* resource:: 
* shelve:: 
* socket:: 
* sqlite3:: 
* ssl:: 
* subprocess:: 
* symtable: symtable<2>. 
* sys:: 
* sys.monitoring: sys monitoring. 
* tarfile:: 
* threading:: 
* timeit:: 
* tkinter:: 
* tokenize:: 
* tomllib:: 
* types:: 
* typing:: 
* unicodedata:: 
* unittest:: 
* urllib.parse: urllib parse. 
* venv:: 
* warnings:: 
* wave:: 
* webbrowser:: 
* xml:: 
* xml.parsers.expat: xml parsers expat. 
* zlib:: 

@end menu

@node argparse,array,,Improved modules<2>
@anchor{whatsnew/3 15 argparse}@anchor{1da}
@subsubsection argparse



@itemize *

@item 
The @ref{1db,,BooleanOptionalAction} action now supports single-dash
long options and alternate prefix characters.
(Contributed by Serhiy Storchaka in gh-138525@footnote{https://github.com/python/cpython/issues/138525}.)

@item 
Changed the `suggest_on_error' parameter of @ref{1dc,,argparse.ArgumentParser} to
default to @code{True}. This enables suggestions for mistyped arguments by default.
(Contributed by Jakob Schluse in gh-140450@footnote{https://github.com/python/cpython/issues/140450}.)
@anchor{whatsnew/3 15 whatsnew315-color-argparse}@anchor{1b1}
@item 
Added backtick markup support in @ref{1dc,,ArgumentParser} description
and epilog text to highlight inline code when color output is enabled.
(Contributed by Savannah Ostrowski in gh-142390@footnote{https://github.com/python/cpython/issues/142390}.)

@item 
Extended backtick markup to argument @code{help} text and added support for
double backticks (RST inline-literal style).
(Contributed by Hugo van Kemenade in gh-149375@footnote{https://github.com/python/cpython/issues/149375}.)
@end itemize

@node array,ast,argparse,Improved modules<2>
@anchor{whatsnew/3 15 array}@anchor{1dd}
@subsubsection array



@itemize *

@item 
Support the float complex and double complex C types:
formatting characters @code{'Zf'} and @code{'Zd'} respectively.
(Contributed by Victor Stinner in gh-146151@footnote{https://github.com/python/cpython/issues/146151} and gh-148675@footnote{https://github.com/python/cpython/issues/148675}.)

@item 
Support half-floats (16-bit IEEE 754 binary interchange format): formatting
character @code{'e'}.
(Contributed by Sergey B Kirpichev in gh-146238@footnote{https://github.com/python/cpython/issues/146238}.)

@item 
The @ref{1de,,array.typecodes} type changed from @ref{1df,,str} to @ref{1ce,,tuple}
to support type codes longer than 1 character (@code{Zf} and @code{Zd}).
(Contributed by Victor Stinner in gh-148675@footnote{https://github.com/python/cpython/issues/148675}.)
@end itemize

@node ast,asyncio,array,Improved modules<2>
@anchor{whatsnew/3 15 ast}@anchor{1e0}
@subsubsection ast


@quotation
@anchor{whatsnew/3 15 whatsnew315-color-ast}@anchor{1b2}
@end quotation


@itemize *

@item 
Add `color' parameter to @ref{1e1,,dump()}.
If @code{True}, the returned string is syntax highlighted using ANSI escape
sequences.
If @code{False} (the default), colored output is always disabled.
(Contributed by Stan Ulbrych in gh-148981@footnote{https://github.com/python/cpython/issues/148981}.)

@item 
The @ref{1e2,,command-line} output is now syntax highlighted by default.
This can be @ref{1af,,controlled using environment variables}.
(Contributed by Stan Ulbrych in gh-148981@footnote{https://github.com/python/cpython/issues/148981}.)
@end itemize

@node asyncio,base64,ast,Improved modules<2>
@anchor{whatsnew/3 15 asyncio}@anchor{1e3}
@subsubsection asyncio



@itemize *

@item 
Added @ref{1e4,,TaskGroup.cancel} to allow early
termination of a task group, for instance, when the goal of the tasks has
been achieved or their services are no longer needed.
Previously this would involve unintuitive boilerplate such as an extra task
raising a custom exception which is then suppressed as it exits the task group.
(Contributed by John Belmonte in gh-127214@footnote{https://github.com/python/cpython/issues/127214}.)
@end itemize

@node base64,binascii,asyncio,Improved modules<2>
@anchor{whatsnew/3 15 base64}@anchor{1e5}
@subsubsection base64



@itemize *

@item 
Added the `pad' parameter in @ref{1e6,,z85encode()}.
(Contributed by Hauke Dämpfling in gh-143103@footnote{https://github.com/python/cpython/issues/143103}.)

@item 
Added the `padded' parameter in
@ref{1e7,,b32encode()}, @ref{1e8,,b32decode()},
@ref{1e9,,b32hexencode()}, @ref{1ea,,b32hexdecode()},
@ref{1eb,,b64encode()}, @ref{1ec,,b64decode()},
@ref{1ed,,urlsafe_b64encode()}, and @ref{1ee,,urlsafe_b64decode()}.
(Contributed by Serhiy Storchaka in gh-73613@footnote{https://github.com/python/cpython/issues/73613}.)

@item 
Added the `wrapcol' parameter in @ref{1ef,,b16encode()},
@ref{1e7,,b32encode()}, @ref{1e9,,b32hexencode()},
@ref{1eb,,b64encode()}, @ref{1f0,,b85encode()}, and
@ref{1e6,,z85encode()}.
(Contributed by Serhiy Storchaka in gh-143214@footnote{https://github.com/python/cpython/issues/143214} and gh-146431@footnote{https://github.com/python/cpython/issues/146431}.)

@item 
Added the `ignorechars' parameter in @ref{1f1,,b16decode()},
@ref{1e8,,b32decode()}, @ref{1ea,,b32hexdecode()},
@ref{1ec,,b64decode()}, @ref{1f2,,b85decode()}, and
@ref{1f3,,z85decode()}.
(Contributed by Serhiy Storchaka in gh-144001@footnote{https://github.com/python/cpython/issues/144001} and gh-146431@footnote{https://github.com/python/cpython/issues/146431}.)

@item 
Added the `canonical' parameter in
@ref{1e8,,b32decode()}, @ref{1ea,,b32hexdecode()},
@ref{1ec,,b64decode()}, @ref{1ee,,urlsafe_b64decode()},
@ref{1f4,,a85decode()}, @ref{1f2,,b85decode()}, and
@ref{1f3,,z85decode()},
to reject encodings with non-zero padding bits or other non-canonical
forms.
(Contributed by Gregory P. Smith in gh-146311@footnote{https://github.com/python/cpython/issues/146311}.)
@end itemize

@node binascii,calendar,base64,Improved modules<2>
@anchor{whatsnew/3 15 binascii}@anchor{1f5}
@subsubsection binascii



@itemize *

@item 
Added functions for Base32 encoding:


@itemize -

@item 
@ref{1f6,,b2a_base32()} and @ref{1f7,,a2b_base32()}
@end itemize

(Contributed by James Seo in gh-146192@footnote{https://github.com/python/cpython/issues/146192}.)

@item 
Added functions for Ascii85, Base85, and Z85 encoding:


@itemize -

@item 
@ref{1f8,,b2a_ascii85()} and @ref{1f9,,a2b_ascii85()}

@item 
@ref{1fa,,b2a_base85()} and @ref{1fb,,a2b_base85()}
@end itemize

(Contributed by James Seo and Serhiy Storchaka in gh-101178@footnote{https://github.com/python/cpython/issues/101178}.)

@item 
Added the `padded' parameter in
@ref{1f6,,b2a_base32()}, @ref{1f7,,a2b_base32()},
@ref{1fc,,b2a_base64()}, and @ref{1fd,,a2b_base64()}.
(Contributed by Serhiy Storchaka in gh-73613@footnote{https://github.com/python/cpython/issues/73613}.)

@item 
Added the `wrapcol' parameter in @ref{1fc,,b2a_base64()}.
(Contributed by Serhiy Storchaka in gh-143214@footnote{https://github.com/python/cpython/issues/143214}.)

@item 
Added the `alphabet' parameter in @ref{1fc,,b2a_base64()} and
@ref{1fd,,a2b_base64()}.
(Contributed by Serhiy Storchaka in gh-145980@footnote{https://github.com/python/cpython/issues/145980}.)

@item 
Added the `ignorechars' parameter in @ref{1fe,,a2b_hex()},
@ref{1ff,,unhexlify()}, and @ref{1fd,,a2b_base64()}.
(Contributed by Serhiy Storchaka in gh-144001@footnote{https://github.com/python/cpython/issues/144001} and gh-146431@footnote{https://github.com/python/cpython/issues/146431}.)

@item 
Added the `canonical' parameter in @ref{1fd,,a2b_base64()},
to reject encodings with non-zero padding bits.
(Contributed by Gregory P. Smith in gh-146311@footnote{https://github.com/python/cpython/issues/146311}.)
@end itemize

@node calendar,collections,binascii,Improved modules<2>
@anchor{whatsnew/3 15 calendar}@anchor{200}
@subsubsection calendar


@quotation
@anchor{whatsnew/3 15 whatsnew315-color-calendar}@anchor{1b3}
@end quotation


@itemize *

@item 
@ref{15,,calendar}’s @ref{201,,command-line} text output has more
color. This can be controlled with @ref{1af,,environment variables}.
(Contributed by Hugo van Kemenade in gh-148352@footnote{https://github.com/python/cpython/issues/148352}.)

@item 
The @ref{15,,calendar}’s @ref{201,,command-line} HTML output now
accepts the year-month option: @code{python -m calendar -t html 2009 06}.
(Contributed by Pål Grønås Drange in gh-140212@footnote{https://github.com/python/cpython/issues/140212}.)

@item 
Calendar pages generated by the @ref{202,,calendar.HTMLCalendar} class now support
dark mode and have been migrated to the HTML5 standard for improved accessibility.
(Contributed by Jiahao Li and Hugo van Kemenade in gh-137634@footnote{https://github.com/python/cpython/issues/137634}.)
@end itemize

@node collections,concurrent futures,calendar,Improved modules<2>
@anchor{whatsnew/3 15 collections}@anchor{203}
@subsubsection collections



@itemize *

@item 
Added @code{collections.Counter.__xor__()} and
@code{collections.Counter.__ixor__()} to compute the symmetric difference
between @ref{204,,Counter} objects.
(Contributed by Raymond Hettinger in gh-138682@footnote{https://github.com/python/cpython/issues/138682}.)
@end itemize

@node concurrent futures,contextlib,collections,Improved modules<2>
@anchor{whatsnew/3 15 concurrent-futures}@anchor{205}
@subsubsection concurrent.futures



@itemize *

@item 
Improved error reporting when a child process in a
@ref{206,,concurrent.futures.ProcessPoolExecutor} terminates abruptly.
The resulting traceback will now tell you the PID and exit code of the
terminated process.
(Contributed by Jonathan Berg in gh-139486@footnote{https://github.com/python/cpython/issues/139486}.)
@end itemize

@node contextlib,dataclasses,concurrent futures,Improved modules<2>
@anchor{whatsnew/3 15 contextlib}@anchor{207}
@subsubsection contextlib



@itemize *

@item 
Added support for arbitrary descriptors @code{__enter__()},
@code{__exit__()}, @code{__aenter__()}, and @code{__aexit__()} in
@ref{208,,ExitStack} and @ref{209,,contextlib.AsyncExitStack}, for
consistency with the @ref{20a,,with} and @ref{20b,,async with} statements.
(Contributed by Serhiy Storchaka in gh-144386@footnote{https://github.com/python/cpython/issues/144386}.)

@item 
@ref{20c,,ContextDecorator} and
@ref{20d,,AsyncContextDecorator} (and therefore
@ref{20e,,contextmanager()} and @ref{20f,,asynccontextmanager()}
used as decorators) now detect generator functions, coroutine functions, and
asynchronous generator functions and keep the context manager open across
iteration or await.  Previously the context manager exited as soon as the
generator or coroutine object was created.
(Contributed by Alex Grönholm & Gregory P. Smith in gh-125862@footnote{https://github.com/python/cpython/issues/125862}.)
@end itemize

@node dataclasses,dbm,contextlib,Improved modules<2>
@anchor{whatsnew/3 15 dataclasses}@anchor{210}
@subsubsection dataclasses



@itemize *

@item 
Annotations for generated @code{__init__} methods no longer include internal
type names.
@end itemize

@node dbm,difflib,dataclasses,Improved modules<2>
@anchor{whatsnew/3 15 dbm}@anchor{211}
@subsubsection dbm



@itemize *

@item 
Added new @code{reorganize()} methods to @ref{35,,dbm.dumb} and @ref{38,,dbm.sqlite3}
to recover unused free space previously occupied by deleted entries.
(Contributed by Andrea Oliveri in gh-134004@footnote{https://github.com/python/cpython/issues/134004}.)
@end itemize

@node difflib,email,dbm,Improved modules<2>
@anchor{whatsnew/3 15 difflib}@anchor{212}
@subsubsection difflib


@quotation
@anchor{whatsnew/3 15 whatsnew315-color-difflib}@anchor{1b4}
@end quotation


@itemize *

@item 
Introduced the optional `color' parameter to @ref{213,,difflib.unified_diff()},
enabling color output similar to @code{git diff}.
This can be controlled by @ref{1af,,environment variables}.
(Contributed by Douglas Thor in gh-133725@footnote{https://github.com/python/cpython/issues/133725}.)

@item 
Improved the styling of HTML diff pages generated by the @ref{214,,difflib.HtmlDiff}
class, and migrated the output to the HTML5 standard.
(Contributed by Jiahao Li in gh-134580@footnote{https://github.com/python/cpython/issues/134580}.)
@end itemize

@node email,faulthandler,difflib,Improved modules<2>
@anchor{whatsnew/3 15 email}@anchor{215}
@subsubsection email



@itemize *

@item 
Email generators now raise an error when an @ref{216,,EmailMessage} cannot be
accurately flattened due to a non-ASCII email address (mailbox) in an address
header. Options for supporting Email Address Internationalization (EAI) are
discussed in @ref{217,,EmailPolicy.utf8}.
(Contributed by R David Murray and Mike Edmunds in gh-122540@footnote{https://github.com/python/cpython/issues/122540}.)
@end itemize

@node faulthandler,functools<2>,email,Improved modules<2>
@anchor{whatsnew/3 15 faulthandler}@anchor{218}
@subsubsection faulthandler



@itemize *

@item 
Added the `max_threads' parameter in @ref{219,,faulthandler.enable()},
@ref{21a,,faulthandler.dump_traceback()}, @ref{21b,,faulthandler.dump_traceback_later()},
and @ref{21c,,faulthandler.register()}.
(Contributed by Eric Froemling in gh-149085@footnote{https://github.com/python/cpython/issues/149085}.)
@end itemize

@node functools<2>,gc,faulthandler,Improved modules<2>
@anchor{whatsnew/3 15 functools}@anchor{21d}
@subsubsection functools



@itemize *

@item 
@ref{21e,,singledispatchmethod()} now supports non-@ref{21f,,descriptor}
callables.
(Contributed by Serhiy Storchaka in gh-140873@footnote{https://github.com/python/cpython/issues/140873}.)

@item 
@ref{21e,,singledispatchmethod()} now dispatches on the second argument
if it wraps a regular method and is called as a class attribute.
(Contributed by Bartosz Sławecki in gh-143535@footnote{https://github.com/python/cpython/issues/143535}.)
@end itemize

@node gc,hashlib,functools<2>,Improved modules<2>
@anchor{whatsnew/3 15 gc}@anchor{220}
@subsubsection gc



@itemize *

@item 
Python 3.14.0-3.14.4 shipped with a new incremental garbage collector.
However, due to a number of reports@footnote{https://github.com/python/cpython/issues/142516}
of significant memory pressure in production environments,
it has been reverted back to the generational GC from 3.13.
This is the GC now used in Python 3.14.5 and later and Python 3.15.
@end itemize

@node hashlib,http client,gc,Improved modules<2>
@anchor{whatsnew/3 15 hashlib}@anchor{221}
@subsubsection hashlib



@itemize *

@item 
Ensure that hash functions guaranteed to be always `available' exist as
attributes of @ref{6b,,hashlib} even if they will not work at runtime due to
missing backend implementations. For instance, @code{hashlib.md5} will no
longer raise @ref{1a9,,AttributeError} if OpenSSL is not available and Python
has been built without MD5 support.
(Contributed by Bénédikt Tran in gh-136929@footnote{https://github.com/python/cpython/issues/136929}.)
@end itemize

@node http client,http server,hashlib,Improved modules<2>
@anchor{whatsnew/3 15 http-client}@anchor{222}
@subsubsection http.client



@itemize *

@item 
A new `max_response_headers' keyword-only parameter has been added to
@ref{223,,HTTPConnection} and @ref{224,,HTTPSConnection}
constructors. This parameter overrides the default maximum number of allowed
response headers.
(Contributed by Alexander Enrique Urieles Nieto in gh-131724@footnote{https://github.com/python/cpython/issues/131724}.)
@end itemize

@node http server,inspect,http client,Improved modules<2>
@anchor{whatsnew/3 15 http-server}@anchor{225}
@subsubsection http.server


@quotation
@anchor{whatsnew/3 15 whatsnew315-color-http-server}@anchor{1b5}
@end quotation


@itemize *

@item 
The logging of @ref{226,,BaseHTTPRequestHandler},
as used by the @ref{227,,command-line interface},
is colored by default.
This can be controlled with @ref{1af,,environment variables}.
(Contributed by Hugo van Kemenade in gh-146292@footnote{https://github.com/python/cpython/issues/146292}.)

@item 
Added @ref{228,,default_content_type}
and the @ref{229,,--content-type} command-line
option to allow customizing the default @code{Content-Type} header
for files with unknown extensions.
(Contributed by John Comeau and Hugo van Kemenade in gh-113471@footnote{https://github.com/python/cpython/issues/113471}.)

@item 
Add a new @code{extra_response_headers} keyword argument to
@ref{22a,,SimpleHTTPRequestHandler} to support custom headers in
HTTP responses.
(Contributed by Anton I. Sipos in gh-135057@footnote{https://github.com/python/cpython/issues/135057}.)

@item 
Add a @code{-H/--header} option to the @code{python -m http.server}
command-line interface to support custom headers in HTTP responses.
(Contributed by Anton I. Sipos in gh-135057@footnote{https://github.com/python/cpython/issues/135057}.)
@end itemize

@node inspect,json,http server,Improved modules<2>
@anchor{whatsnew/3 15 inspect}@anchor{22b}
@subsubsection inspect



@itemize *

@item 
Add parameters `inherit_class_doc' and `fallback_to_class_doc'
for @ref{22c,,getdoc()}.
(Contributed by Serhiy Storchaka in gh-132686@footnote{https://github.com/python/cpython/issues/132686}.)
@end itemize

@node json,locale,inspect,Improved modules<2>
@anchor{whatsnew/3 15 json}@anchor{22d}
@subsubsection json



@itemize *

@item 
Add the `array_hook' parameter to @ref{22e,,load()} and
@ref{22f,,loads()} functions:
allow a callback for JSON literal array types to customize Python lists in
the resulting decoded object. Passing combined @ref{182,,frozendict} to
`object_pairs_hook' param and @ref{1ce,,tuple} to @code{array_hook} will yield a
deeply nested immutable Python structure representing the JSON data.
(Contributed by Joao S. O. Bueno in gh-146440@footnote{https://github.com/python/cpython/issues/146440}.)
@end itemize

@node locale,math,json,Improved modules<2>
@anchor{whatsnew/3 15 locale}@anchor{230}
@subsubsection locale



@itemize *

@item 
@ref{231,,setlocale()} now supports language codes with @code{@@}-modifiers.
@code{@@}-modifiers are no longer silently removed in @ref{232,,getlocale()},
but included in the language code.
(Contributed by Serhiy Storchaka in gh-137729@footnote{https://github.com/python/cpython/issues/137729}.)

@item 
Undeprecate the @ref{233,,locale.getdefaultlocale()} function.
(Contributed by Victor Stinner in gh-130796@footnote{https://github.com/python/cpython/issues/130796}.)
@end itemize

@node math,mimetypes,locale,Improved modules<2>
@anchor{whatsnew/3 15 math}@anchor{234}
@subsubsection math



@itemize *

@item 
Add @ref{235,,math.isnormal()} and @ref{236,,math.issubnormal()} functions.
(Contributed by Sergey B Kirpichev in gh-132908@footnote{https://github.com/python/cpython/issues/132908}.)

@item 
Add @ref{237,,math.fmax()}, @ref{238,,math.fmin()} and @ref{239,,math.signbit()} functions.
(Contributed by Bénédikt Tran in gh-135853@footnote{https://github.com/python/cpython/issues/135853}.)
@end itemize

@node mimetypes,mmap,math,Improved modules<2>
@anchor{whatsnew/3 15 mimetypes}@anchor{23a}
@subsubsection mimetypes



@itemize *

@item 
Add more MIME types.
(Contributed by Benedikt Johannes, Charlie Lin, Foolbar, Gil Forcada and
John Franey
in gh-144217@footnote{https://github.com/python/cpython/issues/144217}, gh-145720@footnote{https://github.com/python/cpython/issues/145720}, gh-140937@footnote{https://github.com/python/cpython/issues/140937}, gh-139959@footnote{https://github.com/python/cpython/issues/139959}, gh-145698@footnote{https://github.com/python/cpython/issues/145698},
gh-145718@footnote{https://github.com/python/cpython/issues/145718}, gh-145918@footnote{https://github.com/python/cpython/issues/145918}, and gh-144213@footnote{https://github.com/python/cpython/issues/144213}.)

@item 
Rename @code{application/x-texinfo} to @code{application/texinfo}.
(Contributed by Charlie Lin in gh-140165@footnote{https://github.com/python/cpython/issues/140165}.)

@item 
Changed the MIME type for @code{.ai} files to @code{application/pdf}.
(Contributed by Stan Ulbrych in gh-141239@footnote{https://github.com/python/cpython/issues/141239}.)
@end itemize

@node mmap,os,mimetypes,Improved modules<2>
@anchor{whatsnew/3 15 mmap}@anchor{23b}
@subsubsection mmap



@itemize *

@item 
@ref{23c,,mmap.mmap} now has a `trackfd' parameter on Windows;
if it is @code{False}, the file handle corresponding to `fileno' will
not be duplicated.
(Contributed by Serhiy Storchaka in gh-78502@footnote{https://github.com/python/cpython/issues/78502}.)

@item 
Added the @ref{23d,,mmap.mmap.set_name()} method
to annotate an anonymous memory mapping
if Linux kernel supports @code{PR_SET_VMA_ANON_NAME@footnote{https://manpages.debian.org/PR_SET_VMA(2const)}} (Linux 5.17 or newer).
(Contributed by Donghee Na in gh-142419@footnote{https://github.com/python/cpython/issues/142419}.)
@end itemize

@node os,os path,mmap,Improved modules<2>
@anchor{whatsnew/3 15 os}@anchor{23e}
@subsubsection os



@itemize *

@item 
Add @ref{23f,,os.statx()} on Linux kernel versions 4.11 and later with
glibc versions 2.28 and later.
(Contributed by Jeffrey Bosboom and Victor Stinner in gh-83714@footnote{https://github.com/python/cpython/issues/83714}.)
@end itemize

@node os path,pdb,os,Improved modules<2>
@anchor{whatsnew/3 15 os-path}@anchor{240}
@subsubsection os.path



@itemize *

@item 
Add support of the all-but-last mode in @ref{241,,realpath()}.
(Contributed by Serhiy Storchaka in gh-71189@footnote{https://github.com/python/cpython/issues/71189}.)

@item 
The `strict' parameter to @ref{241,,os.path.realpath()} accepts a new value,
@ref{242,,os.path.ALLOW_MISSING}.
If used, errors other than @ref{243,,FileNotFoundError} will be re-raised;
the resulting path can be missing but it will be free of symlinks.
(Contributed by Petr Viktorin for 
@geindex Common Vulnerabilities and Exposures; CVE 2025-4517
CVE 2025-4517@footnote{https://www.cve.org/CVERecord?id=CVE-2025-4517}.)
@end itemize

@node pdb,pickle,os path,Improved modules<2>
@anchor{whatsnew/3 15 pdb}@anchor{244}
@subsubsection pdb



@itemize *

@item 
Use the new interactive shell as the default input shell for @ref{aa,,pdb}.
(Contributed by Tian Gao in gh-145379@footnote{https://github.com/python/cpython/issues/145379}.)
@end itemize

@node pickle,pickletools,pdb,Improved modules<2>
@anchor{whatsnew/3 15 pickle}@anchor{245}
@subsubsection pickle



@itemize *

@item 
Add support for pickling private methods and nested classes.
(Contributed by Zackery Spytz and Serhiy Storchaka in gh-77188@footnote{https://github.com/python/cpython/issues/77188}.)
@end itemize

@node pickletools,pprint,pickle,Improved modules<2>
@anchor{whatsnew/3 15 pickletools}@anchor{246}
@subsubsection pickletools


@quotation
@anchor{whatsnew/3 15 whatsnew315-color-pickletools}@anchor{1b6}
@end quotation


@itemize *

@item 
The output of the @ref{ac,,pickletools} command-line interface is colored by
default. This can be controlled with
@ref{1af,,environment variables}.
(Contributed by Hugo van Kemenade in gh-149026@footnote{https://github.com/python/cpython/issues/149026}.)
@end itemize

@node pprint,re,pickletools,Improved modules<2>
@anchor{whatsnew/3 15 pprint}@anchor{247}
@subsubsection pprint



@itemize *

@item 
@ref{b3,,pprint} now uses modern defaults: @code{indent=4, width=88},
and the default @code{compact=False} output is now formatted similar to
pretty-printed @ref{248,,json.dumps()}.
(Contributed by Stefan Todoran, Semyon Moroz and Hugo van Kemenade in
gh-112632@footnote{https://github.com/python/cpython/issues/112632} and gh-149189@footnote{https://github.com/python/cpython/issues/149189}.)

@item 
Add t-string support to @ref{b3,,pprint}.
(Contributed by Loïc Simon and Hugo van Kemenade in gh-134551@footnote{https://github.com/python/cpython/issues/134551}.)
@end itemize

@node re,resource,pprint,Improved modules<2>
@anchor{whatsnew/3 15 re}@anchor{249}
@subsubsection re



@itemize *

@item 
@ref{24a,,re.prefixmatch()} and a corresponding @ref{24b,,re.Pattern.prefixmatch()}
have been added as alternate, more explicit names for the existing
and now @ref{1a7,,soft deprecated}
@ref{24c,,re.match()} and @ref{24d,,re.Pattern.match()} APIs. These are intended
to be used to alleviate confusion around what `match' means by following the
Zen of Python’s `«Explicit is better than implicit»' mantra. Most other
language regular expression libraries use an API named `match' to mean what
Python has always called `search'.
(Contributed by Gregory P. Smith in gh-86519@footnote{https://github.com/python/cpython/issues/86519}.)
@end itemize

@node resource,shelve,re,Improved modules<2>
@anchor{whatsnew/3 15 resource}@anchor{24e}
@subsubsection resource



@itemize *

@item 
Add new constants: @ref{24f,,RLIMIT_NTHR},
@ref{250,,RLIMIT_UMTXP}, @ref{251,,RLIMIT_THREADS},
@ref{252,,RLIM_SAVED_CUR}, and @ref{253,,RLIM_SAVED_MAX}.
(Contributed by Serhiy Storchaka in gh-137512@footnote{https://github.com/python/cpython/issues/137512}.)
@end itemize

@node shelve,socket,resource,Improved modules<2>
@anchor{whatsnew/3 15 shelve}@anchor{254}
@subsubsection shelve



@itemize *

@item 
Added new @code{reorganize()} method to @ref{cb,,shelve} used to recover unused free
space previously occupied by deleted entries.
(Contributed by Andrea Oliveri in gh-134004@footnote{https://github.com/python/cpython/issues/134004}.)

@item 
Add support for custom serialization and deserialization functions
in the @ref{cb,,shelve} module.
(Contributed by Furkan Onder in gh-99631@footnote{https://github.com/python/cpython/issues/99631}.)
@end itemize

@node socket,sqlite3,shelve,Improved modules<2>
@anchor{whatsnew/3 15 socket}@anchor{255}
@subsubsection socket



@itemize *

@item 
Add constants for the ISO-TP CAN protocol.
(Contributed by Patrick Menschel and Stefan Tatschner in gh-86819@footnote{https://github.com/python/cpython/issues/86819}.)
@end itemize

@node sqlite3,ssl,socket,Improved modules<2>
@anchor{whatsnew/3 15 sqlite3}@anchor{256}
@subsubsection sqlite3



@itemize *

@item 
The @ref{257,,command-line interface} has several new features:


@itemize *

@item 
SQL keyword completion on <tab>.
(Contributed by Long Tan in gh-133393@footnote{https://github.com/python/cpython/issues/133393}.)
@end itemize
@anchor{whatsnew/3 15 whatsnew315-color-sqlite3}@anchor{1b8}

@itemize *

@item 
Prompts, error messages, and help text are now colored.
This is enabled by default, see @ref{1af,,Controlling color} for
details.
(Contributed by Stan Ulbrych and Łukasz Langa in gh-133461@footnote{https://github.com/python/cpython/issues/133461}.)

@item 
Table, index, trigger, view, column, function, and schema completion on <tab>.
(Contributed by Long Tan in gh-136101@footnote{https://github.com/python/cpython/issues/136101}.)
@end itemize
@end itemize

@node ssl,subprocess,sqlite3,Improved modules<2>
@anchor{whatsnew/3 15 ssl}@anchor{258}
@subsubsection ssl



@itemize *

@item 
Indicate through @ref{259,,ssl.HAS_PSK_TLS13} whether the @ref{d8,,ssl} module
supports «External PSKs» in TLSv1.3, as described in 
@geindex RFC; RFC 9258
RFC 9258@footnote{https://datatracker.ietf.org/doc/html/rfc9258.html}.
(Contributed by Will Childs-Klein in gh-133624@footnote{https://github.com/python/cpython/issues/133624}.)

@item 
Added new methods for managing groups used for SSL key agreement


@itemize *

@item 
@ref{25a,,ssl.SSLContext.set_groups()} sets the groups allowed for doing
key agreement, extending the previous
@ref{25b,,ssl.SSLContext.set_ecdh_curve()} method.
This new API provides the ability to list multiple groups and
supports fixed-field and post-quantum groups in addition to ECDH
curves. This method can also be used to control what key shares
are sent in the TLS handshake.

@item 
@ref{25c,,ssl.SSLSocket.group()} returns the group selected for doing key
agreement on the current connection after the TLS handshake completes.
This call requires OpenSSL 3.2 or later.

@item 
@ref{25d,,ssl.SSLContext.get_groups()} returns a list of all available key
agreement groups compatible with the minimum and maximum TLS versions
currently set in the context. This call requires OpenSSL 3.5 or later.
@end itemize

(Contributed by Ron Frederick in gh-136306@footnote{https://github.com/python/cpython/issues/136306}.)

@item 
Added a new method @ref{25e,,ssl.SSLContext.set_ciphersuites()} for setting TLS 1.3
ciphers. For TLS 1.2 or earlier, @ref{25f,,ssl.SSLContext.set_ciphers()} should
continue to be used. Both calls can be made on the same context and the
selected cipher suite will depend on the TLS version negotiated when a
connection is made.
(Contributed by Ron Frederick in gh-137197@footnote{https://github.com/python/cpython/issues/137197}.)

@item 
Added new methods for managing signature algorithms:


@itemize *

@item 
@ref{260,,ssl.get_sigalgs()} returns a list of all available TLS signature
algorithms. This call requires OpenSSL 3.4 or later.

@item 
@ref{261,,ssl.SSLContext.set_client_sigalgs()} sets the signature algorithms
allowed for certificate-based client authentication.

@item 
@ref{262,,ssl.SSLContext.set_server_sigalgs()} sets the signature algorithms
allowed for the server to complete the TLS handshake.

@item 
@ref{263,,ssl.SSLSocket.client_sigalg()} returns the signature algorithm
selected for client authentication on the current connection. This call
requires OpenSSL 3.5 or later.

@item 
@ref{264,,ssl.SSLSocket.server_sigalg()} returns the signature algorithm
selected for the server to complete the TLS handshake on the current
connection. This call requires OpenSSL 3.5 or later.
@end itemize

(Contributed by Ron Frederick in gh-138252@footnote{https://github.com/python/cpython/issues/138252}.)
@end itemize

@node subprocess,symtable<2>,ssl,Improved modules<2>
@anchor{whatsnew/3 15 subprocess}@anchor{265}
@subsubsection subprocess



@itemize *

@item 
@ref{266,,subprocess.Popen.wait()}: when @code{timeout} is not @code{None} and the
platform supports it, an efficient event-driven mechanism is used to wait for
process termination:


@itemize -

@item 
Linux >= 5.3 uses @ref{267,,os.pidfd_open()} + @ref{268,,select.poll()}.

@item 
macOS and other BSD variants use @ref{269,,select.kqueue()} + @code{KQ_FILTER_PROC} + @code{KQ_NOTE_EXIT}.

@item 
Windows keeps using @code{WaitForSingleObject} (unchanged).
@end itemize

If none of these mechanisms are available, the function falls back to the
traditional busy loop (non-blocking call and short sleeps).
(Contributed by Giampaolo Rodola in gh-83069@footnote{https://github.com/python/cpython/issues/83069}.)
@end itemize

@node symtable<2>,sys,subprocess,Improved modules<2>
@anchor{whatsnew/3 15 symtable}@anchor{26a}
@subsubsection symtable



@itemize *

@item 
Add @ref{26b,,symtable.Function.get_cells()} and @ref{26c,,symtable.Symbol.is_cell()} methods.
(Contributed by Yashp002 in gh-143504@footnote{https://github.com/python/cpython/issues/143504}.)
@end itemize

@node sys,sys monitoring,symtable<2>,Improved modules<2>
@anchor{whatsnew/3 15 sys}@anchor{26d}
@subsubsection sys



@itemize *

@item 
Add @ref{26e,,sys.abi_info} namespace to improve access to ABI information.
(Contributed by Klaus Zimmermann in gh-137476@footnote{https://github.com/python/cpython/issues/137476}.)
@end itemize

@node sys monitoring,tarfile,sys,Improved modules<2>
@anchor{whatsnew/3 15 sys-monitoring}@anchor{26f}
@subsubsection sys.monitoring



@itemize *

@item 
The @ref{270,,other events}
(@ref{271,,PY_THROW}, @ref{272,,PY_UNWIND},
@ref{273,,RAISE}, @ref{274,,EXCEPTION_HANDLED}, and
@ref{275,,RERAISE}) can now be turned on and disabled on a per code
object basis. Returning @ref{276,,DISABLE} from a callback for
one of these events disables the event for the entire code object (for the
current tool), rather than raising @ref{277,,ValueError} as in prior versions.
(Contributed by Gabriele N. Tornetta in gh-146182@footnote{https://github.com/python/cpython/issues/146182}.)
@end itemize

@node tarfile,threading,sys monitoring,Improved modules<2>
@anchor{whatsnew/3 15 tarfile}@anchor{278}
@subsubsection tarfile



@itemize *

@item 
@ref{279,,data_filter()} now normalizes symbolic link targets in order to
avoid path traversal attacks.
(Contributed by Petr Viktorin in gh-127987@footnote{https://github.com/python/cpython/issues/127987} and 
@geindex Common Vulnerabilities and Exposures; CVE 2025-4138
CVE 2025-4138@footnote{https://www.cve.org/CVERecord?id=CVE-2025-4138}.)

@item 
@ref{27a,,extractall()} now skips fixing up directory attributes
when a directory was removed or replaced by another kind of file.
(Contributed by Petr Viktorin in gh-127987@footnote{https://github.com/python/cpython/issues/127987} and 
@geindex Common Vulnerabilities and Exposures; CVE 2024-12718
CVE 2024-12718@footnote{https://www.cve.org/CVERecord?id=CVE-2024-12718}.)

@item 
@ref{27b,,extract()} and @ref{27a,,extractall()}
now (re-)apply the extraction filter when substituting a link (hard or
symbolic) with a copy of another archive member, and when fixing up
directory attributes.
The former raises a new exception, @ref{27c,,LinkFallbackError}.
(Contributed by Petr Viktorin for 
@geindex Common Vulnerabilities and Exposures; CVE 2025-4330
CVE 2025-4330@footnote{https://www.cve.org/CVERecord?id=CVE-2025-4330} and 
@geindex Common Vulnerabilities and Exposures; CVE 2024-12718
CVE 2024-12718@footnote{https://www.cve.org/CVERecord?id=CVE-2024-12718}.)

@item 
@ref{27b,,extract()} and @ref{27a,,extractall()}
no longer extract rejected members when
@ref{27d,,errorlevel()} is zero.
(Contributed by Matt Prodani and Petr Viktorin in gh-112887@footnote{https://github.com/python/cpython/issues/112887}
and 
@geindex Common Vulnerabilities and Exposures; CVE 2025-4435
CVE 2025-4435@footnote{https://www.cve.org/CVERecord?id=CVE-2025-4435}.)

@item 
@ref{27b,,extract()} and @ref{27a,,extractall()}
now replace slashes with backslashes in symlink targets on Windows to prevent
creation of corrupted links.
(Contributed by Christoph Walcher in gh-57911@footnote{https://github.com/python/cpython/issues/57911}.)
@end itemize

@node threading,timeit,tarfile,Improved modules<2>
@anchor{whatsnew/3 15 threading}@anchor{27e}
@subsubsection threading



@itemize *

@item 
Added @ref{27f,,serialize_iterator},
@ref{280,,synchronized_iterator()},
and @ref{281,,concurrent_tee()} to support concurrent access to
generators and iterators.
(Contributed by Raymond Hettinger in gh-124397@footnote{https://github.com/python/cpython/issues/124397}.)
@end itemize

@node timeit,tkinter,threading,Improved modules<2>
@anchor{whatsnew/3 15 timeit}@anchor{282}
@subsubsection timeit


@quotation
@anchor{whatsnew/3 15 whatsnew315-color-timeit}@anchor{1b9}
@end quotation


@itemize *

@item 
The output of the @ref{f8,,timeit} command-line interface is colored by default.
This can be controlled with
@ref{1af,,environment variables}.
(Contributed by Hugo van Kemenade in gh-146609@footnote{https://github.com/python/cpython/issues/146609}.)

@item 
The command-line interface now colorizes error tracebacks
by default. This can be controlled with
@ref{1af,,environment variables}.
(Contributed by Yi Hong in gh-139374@footnote{https://github.com/python/cpython/issues/139374}.)

@item 
Make the target time of @ref{283,,timeit.Timer.autorange()} configurable
and add @code{--target-time} option to the command-line interface.
(Contributed by Alessandro Cucci and Miikka Koskinen in gh-80642@footnote{https://github.com/python/cpython/issues/80642}.)
@end itemize

@node tkinter,tokenize,timeit,Improved modules<2>
@anchor{whatsnew/3 15 tkinter}@anchor{284}
@subsubsection tkinter



@itemize *

@item 
The @code{tkinter.Text.search()} method now supports two additional
arguments: `nolinestop' which allows the search to
continue across line boundaries;
and `strictlimits' which restricts the search to within the specified range.
(Contributed by Rihaan Meher in gh-130848@footnote{https://github.com/python/cpython/issues/130848}.)

@item 
A new method @code{tkinter.Text.search_all()} has been introduced.
This method allows for searching for all matches of a pattern
using Tcl’s @code{-all} and @code{-overlap} options.
(Contributed by Rihaan Meher in gh-130848@footnote{https://github.com/python/cpython/issues/130848}.)

@item 
Added new methods @code{pack_content()}, @code{place_content()} and
@code{grid_content()} which use Tk commands with new names (introduced
in Tk 8.6) instead of @code{*_slaves()} methods which use Tk commands
with outdated names.
(Contributed by Serhiy Storchaka in gh-143754@footnote{https://github.com/python/cpython/issues/143754}.)

@item 
Added @code{Event} attributes @code{user_data} for Tk virtual events
and @code{detail} for @code{Enter}, @code{Leave}, @code{FocusIn}, @code{FocusOut},
and @code{ConfigureRequest} events.
(Contributed by Matthias Kievernagel and Serhiy Storchaka in gh-47655@footnote{https://github.com/python/cpython/issues/47655}.)
@end itemize

@node tokenize,tomllib,tkinter,Improved modules<2>
@anchor{whatsnew/3 15 tokenize}@anchor{285}
@subsubsection tokenize


@quotation
@anchor{whatsnew/3 15 whatsnew315-color-tokenize}@anchor{1ba}
@end quotation


@itemize *

@item 
The output of the @ref{104,,tokenize} @ref{286,,command-line interface} is colored by default. This can be controlled with
@ref{1af,,environment variables}.
(Contributed by Hugo van Kemenade in gh-148991@footnote{https://github.com/python/cpython/issues/148991}.)
@end itemize

@node tomllib,types,tokenize,Improved modules<2>
@anchor{whatsnew/3 15 tomllib}@anchor{287}@anchor{whatsnew/3 15 whatsnew315-tomllib-1-1-0}@anchor{288}
@subsubsection tomllib



@itemize *

@item 
The @ref{105,,tomllib} module now supports TOML 1.1.0.
This is a backwards compatible update, meaning that all valid TOML 1.0.0
documents are parsed the same way.

The changes, according to the official TOML changelog@footnote{https://github.com/toml-lang/toml/blob/main/CHANGELOG.md}, are:


@itemize -

@item 
Allow newlines and trailing commas in inline tables.

Previously an inline table had to be on a single line and couldn’t end
with a trailing comma. This is now relaxed so that the following is valid:

@example
tbl = @{
   key      = "a string",
   moar-tbl =  @{
      key = 1,
   @},
@}
@end example

@item 
Add @code{\xHH} notation to basic strings for codepoints under 255,
and the @code{\e} escape for the escape character:

@example
null = "null byte: \x00; letter a: \x61"
csi = "\e["
@end example

@item 
Seconds in datetime and time values are now optional.
The following are now valid:

@example
dt = 2010-02-03 14:15
t  = 14:15
@end example
@end itemize

(Contributed by Taneli Hukkinen in gh-142956@footnote{https://github.com/python/cpython/issues/142956}.)
@end itemize

@node types,typing,tomllib,Improved modules<2>
@anchor{whatsnew/3 15 official-toml-changelog}@anchor{289}@anchor{whatsnew/3 15 types}@anchor{28a}
@subsubsection types



@itemize *

@item 
Expose the write-through @ref{28b,,locals()} proxy type
as @ref{28c,,types.FrameLocalsProxyType}.
This represents the type of the @ref{28d,,frame.f_locals} attribute,
as described in 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}.
@end itemize

@node typing,unicodedata,types,Improved modules<2>
@anchor{whatsnew/3 15 typing}@anchor{28e}
@subsubsection typing

@anchor{whatsnew/3 15 whatsnew315-typeform}@anchor{16d}

@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 747
PEP 747@footnote{https://peps.python.org/pep-0747/}: Add @ref{28f,,TypeForm}, a new special form for annotating
values that are themselves type expressions.
@code{TypeForm[T]} means «a type form object describing @code{T} (or a type
assignable to @code{T})». At runtime, @code{TypeForm(x)} simply returns @code{x},
which allows explicit annotation of type-form values without changing
behavior.

This helps libraries that accept user-provided type expressions
(for example @code{int}, @code{str | None}, @ref{290,,TypedDict}
classes, or @code{list[int]}) expose precise signatures:

@example
from typing import Any, TypeForm

def cast[T](typ: TypeForm[T], value: Any) -> T: ...
@end example

(Contributed by Jelle Zijlstra in gh-145033@footnote{https://github.com/python/cpython/issues/145033}.)
@end itemize
@anchor{whatsnew/3 15 whatsnew315-typeddict}@anchor{16c}

@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 728
PEP 728@footnote{https://peps.python.org/pep-0728/}: Add support in @ref{290,,TypedDict} for the `closed'
and `extra_items' class arguments. A closed @code{TypedDict}
does not allow extra keys beyond those specified in the class body, while
a @code{TypedDict} with @code{extra_items} allows arbitrary extra
items where the values are of the specified type. (Contributed by Angela
Liss in gh-137840@footnote{https://github.com/python/cpython/issues/137840}.)

@item 
Code like @code{class ExtraTypeVars(P1[S], Protocol[T, T2]): ...} now raises
a @ref{291,,TypeError}, because @code{S} is not listed in @code{Protocol} parameters.
(Contributed by Nikita Sobolev in gh-137191@footnote{https://github.com/python/cpython/issues/137191}.)

@item 
Code like @code{class B2(A[T2], Protocol[T1, T2]): ...} now correctly handles
type parameters order: it is @code{(T1, T2)}, not @code{(T2, T1)}
as it was incorrectly inferred at runtime before.
(Contributed by Nikita Sobolev in gh-137191@footnote{https://github.com/python/cpython/issues/137191}.)

@item 
@geindex Python Enhancement Proposals; PEP 800
PEP 800@footnote{https://peps.python.org/pep-0800/}: Add @ref{292,,@@typing.disjoint_base}, a new decorator marking a class
as a disjoint base. This is an advanced feature primarily intended to allow
type checkers to faithfully reflect the runtime semantics of types defined
as builtins or in compiled extensions. If a class @code{C} is a disjoint base, then
child classes of that class cannot inherit from other disjoint bases that are
not parent or child classes of @code{C}. (Contributed by Jelle Zijlstra in gh-148639@footnote{https://github.com/python/cpython/issues/148639}.)

@item 
@ref{293,,TypeVarTuple} now accepts @code{bound}, @code{covariant},
@code{contravariant}, and @code{infer_variance} keyword arguments, matching the
interface of @ref{294,,TypeVar} and @ref{295,,ParamSpec}.
@code{bound} semantics remain undefined in the specification.
@end itemize

@node unicodedata,unittest,typing,Improved modules<2>
@anchor{whatsnew/3 15 unicodedata}@anchor{296}
@subsubsection unicodedata



@itemize *

@item 
The Unicode database has been updated to Unicode 17.0.0.

@item 
Add @ref{297,,unicodedata.isxidstart()} and @ref{298,,unicodedata.isxidcontinue()}
functions to check whether a character can start or continue a
Unicode Standard Annex #31@footnote{https://www.unicode.org/reports/tr31/} identifier.
(Contributed by Stan Ulbrych in gh-129117@footnote{https://github.com/python/cpython/issues/129117}.)

@item 
Add the @ref{299,,iter_graphemes()}
function to iterate over grapheme clusters according to rules defined in
Unicode Standard Annex #29@comma{} "Unicode Text Segmentation"@footnote{https://www.unicode.org/reports/tr29/}.
Add @ref{29a,,grapheme_cluster_break()},
@ref{29b,,indic_conjunct_break()} and
@ref{29c,,extended_pictographic()} functions to get the properties
of the character which are related to the above algorithm.
(Contributed by Serhiy Storchaka and Guillaume Sanchez in gh-74902@footnote{https://github.com/python/cpython/issues/74902}.)

@item 
Add @ref{29d,,block()} function to return the Unicode block@footnote{https://www.unicode.org/versions/Unicode17.0.0/core-spec/chapter-3/#G64189}
assigned to a character.
(Contributed by Stan Ulbrych in gh-66802@footnote{https://github.com/python/cpython/issues/66802}.)
@end itemize

@node unittest,urllib parse,unicodedata,Improved modules<2>
@anchor{whatsnew/3 15 unittest}@anchor{29e}
@subsubsection unittest



@itemize *

@item 
@ref{29f,,unittest.TestCase.assertLogs()} will now accept a formatter
to control how messages are formatted.
(Contributed by Garry Cairns in gh-134567@footnote{https://github.com/python/cpython/issues/134567}.)

@item 
@ref{2a0,,unittest.TestCase.assertWarns()} and
@ref{2a1,,unittest.TestCase.assertWarnsRegex()} no longer swallow warnings that
do not match the specified category or regex.
Nested context managers are now supported.
(Contributed by Serhiy Storchaka in gh-143231@footnote{https://github.com/python/cpython/issues/143231}.)
@end itemize

@node urllib parse,venv,unittest,Improved modules<2>
@anchor{whatsnew/3 15 urllib-parse}@anchor{2a2}
@subsubsection urllib.parse



@itemize *

@item 
Add the `missing_as_none' parameter to @ref{2a3,,urlsplit()},
@ref{2a4,,urlparse()} and @ref{2a5,,urldefrag()} functions.
Add the `keep_empty' parameter to @ref{2a6,,urlunsplit()} and
@ref{2a7,,urlunparse()} functions.
This allows distinguishing between empty and undefined URI components
and preserving empty components.
(Contributed by Serhiy Storchaka in gh-67041@footnote{https://github.com/python/cpython/issues/67041}.)
@end itemize

@node venv,warnings,urllib parse,Improved modules<2>
@anchor{whatsnew/3 15 venv}@anchor{2a8}
@subsubsection venv



@itemize *

@item 
On POSIX platforms, platlib directories will be created if needed when
creating virtual environments, instead of using a @code{lib64 -> lib} symlink.
This means purelib and platlib of virtual environments no longer share the
same @code{lib} directory on platforms where @ref{2a9,,sys.platlibdir} is not
equal to @code{lib}.
(Contributed by Rui Xi in gh-133951@footnote{https://github.com/python/cpython/issues/133951}.)
@end itemize

@node warnings,wave,venv,Improved modules<2>
@anchor{whatsnew/3 15 warnings}@anchor{2aa}
@subsubsection warnings



@itemize *

@item 
Improve filtering by module in @ref{2ab,,warnings.warn_explicit()} if no `module'
argument is passed.
It now tests the module regular expression in the warnings filter not only
against the filename with @code{.py} stripped, but also against module names
constructed starting from different parent directories of the filename
(with @code{/__init__.py}, @code{.py} and, on Windows, @code{.pyw} stripped).
(Contributed by Serhiy Storchaka in gh-135801@footnote{https://github.com/python/cpython/issues/135801}.)
@end itemize

@node wave,webbrowser,warnings,Improved modules<2>
@anchor{whatsnew/3 15 wave}@anchor{2ac}
@subsubsection wave



@itemize *

@item 
Added support for IEEE floating-point WAVE audio
(@code{WAVE_FORMAT_IEEE_FLOAT}) in @ref{11c,,wave}.

@item 
Added @ref{2ad,,wave.Wave_read.getformat()}, @ref{2ae,,wave.Wave_write.getformat()},
and @ref{2af,,wave.Wave_write.setformat()} for explicit frame format handling.

@item 
@ref{2b0,,wave.Wave_write.setparams()} accepts both 7-item tuples including
@code{format} and 6-item tuples for backwards compatibility (defaulting to
@code{WAVE_FORMAT_PCM}).

@item 
@code{WAVE_FORMAT_IEEE_FLOAT} output now includes a @code{fact} chunk,
as required for non-PCM WAVE formats.
@end itemize

(Contributed by Lionel Koenig and Michiel W. Beijen in gh-60729@footnote{https://github.com/python/cpython/issues/60729}.)

@node webbrowser,xml,wave,Improved modules<2>
@anchor{whatsnew/3 15 webbrowser}@anchor{2b1}
@subsubsection webbrowser



@itemize *

@item 
On macOS, the new @code{webbrowser.MacOS} class opens URLs via
@code{/usr/bin/open} instead of constructing and executing AppleScript
via @code{osascript}. The default browser is detected from the
LaunchServices preferences file using @ref{b0,,plistlib}, with
@code{com.apple.Safari} as the fallback on fresh installations.
For non-HTTP(S) URLs, @code{open -b <bundle-id>} is used to route the
URL through a browser rather than the OS file handler, preventing
file injection attacks.
(Contributed by Jeff Lyon in gh-137586@footnote{https://github.com/python/cpython/issues/137586}.)
@end itemize

@node xml,xml parsers expat,webbrowser,Improved modules<2>
@anchor{whatsnew/3 15 xml}@anchor{2b2}
@subsubsection xml



@itemize *

@item 
Add the @ref{2b3,,xml.is_valid_name()} function to check
whether a string can be used as an element or attribute name in XML.
(Contributed by Serhiy Storchaka in gh-139489@footnote{https://github.com/python/cpython/issues/139489}.)

@item 
Add the @ref{2b4,,xml.is_valid_text()} function, which allows to check
whether a string can be used in the XML document.
(Contributed by Serhiy Storchaka in gh-139489@footnote{https://github.com/python/cpython/issues/139489}.)
@end itemize

@node xml parsers expat,zlib,xml,Improved modules<2>
@anchor{whatsnew/3 15 xml-parsers-expat}@anchor{2b5}
@subsubsection xml.parsers.expat



@itemize *

@item 
Add @ref{2b6,,SetAllocTrackerActivationThreshold()}
and @ref{2b7,,SetAllocTrackerMaximumAmplification()}
to @ref{2b8,,xmlparser} objects to tune protections against
disproportional amounts of dynamic memory usage from within an Expat parser.
(Contributed by Bénédikt Tran in gh-90949@footnote{https://github.com/python/cpython/issues/90949}.)

@item 
Add @ref{2b9,,SetBillionLaughsAttackProtectionActivationThreshold()}
and @ref{2ba,,SetBillionLaughsAttackProtectionMaximumAmplification()}
to @ref{2b8,,xmlparser} objects to tune protections against
billion laughs@footnote{https://en.wikipedia.org/wiki/Billion_laughs_attack} attacks.
(Contributed by Bénédikt Tran in gh-90949@footnote{https://github.com/python/cpython/issues/90949}.)
@end itemize

@node zlib,,xml parsers expat,Improved modules<2>
@anchor{whatsnew/3 15 zlib}@anchor{2bb}
@subsubsection zlib



@itemize *

@item 
Allow combining two Adler-32 checksums via @ref{2bc,,adler32_combine()}.
(Contributed by Callum Attryde and Bénédikt Tran in gh-134635@footnote{https://github.com/python/cpython/issues/134635}.)

@item 
Allow combining two CRC-32 checksums via @ref{2bd,,crc32_combine()}.
(Contributed by Bénédikt Tran in gh-134635@footnote{https://github.com/python/cpython/issues/134635}.)
@end itemize

@c Add improved modules above alphabetically, not here at the end.

@node Optimizations<2>,Removed<2>,Improved modules<2>,What’s new in Python 3 15
@anchor{whatsnew/3 15 optimizations}@anchor{2be}
@subsection Optimizations



@itemize *

@item 
@code{mimalloc} is now used as the default allocator for
raw memory allocations such as via @ref{2bf,,PyMem_RawMalloc()}
for better performance on @ref{198,,free-threaded builds}.
(Contributed by Kumar Aditya in gh-144914@footnote{https://github.com/python/cpython/issues/144914}.)
@end itemize

@menu
* base64 & binascii:: 
* csv:: 
* Upgraded JIT compiler:: 

@end menu

@node base64 & binascii,csv,,Optimizations<2>
@anchor{whatsnew/3 15 base64-binascii}@anchor{2c0}
@subsubsection base64 & binascii



@itemize *

@item 
CPython’s underlying base64 implementation now encodes 2x faster and decodes 3x
faster thanks to simple CPU pipelining optimizations.
(Contributed by Gregory P. Smith and Serhiy Storchaka in gh-143262@footnote{https://github.com/python/cpython/issues/143262}.)

@item 
Implementation for Ascii85, Base85, and Z85 encoding has been rewritten in C.
Encoding and decoding is now two orders of magnitude faster and consumes
two orders of magnitude less memory.
(Contributed by James Seo and Serhiy Storchaka in gh-101178@footnote{https://github.com/python/cpython/issues/101178}.)

@item 
Implementation for Base32 has been rewritten in C.
Encoding and decoding is now two orders of magnitude faster.
(Contributed by James Seo in gh-146192@footnote{https://github.com/python/cpython/issues/146192}.)
@end itemize

@node csv,Upgraded JIT compiler,base64 & binascii,Optimizations<2>
@anchor{whatsnew/3 15 csv}@anchor{2c1}
@subsubsection csv



@itemize *

@item 
@ref{2c2,,csv.Sniffer.sniff()} delimiter detection is now up to 1.6x faster.
(Contributed by Maurycy Pawłowski-Wieroński in gh-137628@footnote{https://github.com/python/cpython/issues/137628}.)
@end itemize

@node Upgraded JIT compiler,,csv,Optimizations<2>
@anchor{whatsnew/3 15 upgraded-jit-compiler}@anchor{2c3}@anchor{whatsnew/3 15 whatsnew315-jit}@anchor{171}
@subsubsection Upgraded JIT compiler


Results from the pyperformance@footnote{https://github.com/python/pyperformance}
benchmark suite report
8-9%@footnote{https://www.doesjitgobrrr.com/run/2026-04-29}
geometric mean performance improvement for the JIT over the standard CPython
interpreter built with all optimizations enabled on x86-64 Linux. On AArch64
macOS, the JIT has a
12-13%@footnote{https://www.doesjitgobrrr.com/run/2026-04-29}
speedup over the @ref{2c4,,tail calling interpreter}
with all optimizations enabled. The speedups for JIT
builds versus no JIT builds range from roughly 15% slowdown to over
100% speedup (ignoring the @code{unpack_sequence} microbenchmark) on
x86-64 Linux and AArch64 macOS systems.

@cartouche
@quotation Προσοχή 
These results are not yet final.
@end quotation
@end cartouche

The major upgrades to the JIT are:


@itemize *

@item 
LLVM 21 build-time dependency

@item 
New tracing frontend

@item 
Basic register allocation in the JIT

@item 
More JIT optimizations

@item 
GDB and GNU @code{backtrace()} unwinding support

@item 
Better machine code generation
@end itemize

@subsubheading LLVM 21 build-time dependency


The JIT compiler now uses LLVM 21 for build-time stencil generation. As
always, LLVM is only needed when building CPython with the JIT enabled;
end users running Python do not need LLVM installed. Instructions for
installing LLVM can be found in the JIT compiler documentation@footnote{https://github.com/python/cpython/blob/main/Tools/jit/README.md}
for all supported platforms.
(Contributed by Savannah Ostrowski in gh-140973@footnote{https://github.com/python/cpython/issues/140973}.)

@subsubheading A new tracing frontend


The JIT compiler now supports significantly more bytecode operations and
control flow than in Python 3.14, enabling speedups on a wider variety of
code. For example, simple Python object creation is now understood by the
3.15 JIT compiler. Overloaded operations and generators are also partially
supported. This was made possible by an overhauled JIT tracing frontend
that records actual execution paths through code, rather than estimating
them as the previous implementation did.
(Contributed by Ken Jin in gh-139109@footnote{https://github.com/python/cpython/issues/139109}. Support for Windows added by
Mark Shannon in gh-141703@footnote{https://github.com/python/cpython/issues/141703}.)

@subsubheading Basic register allocation in the JIT


A basic form of register allocation has been added to the JIT compiler’s
optimizer. This allows the JIT compiler to avoid certain stack operations
altogether and instead operate on registers. This allows the JIT to produce
more efficient traces by avoiding reads and writes to memory.
(Contributed by Mark Shannon in gh-135379@footnote{https://github.com/python/cpython/issues/135379}.)

@subsubheading More JIT optimizations


More constant-propagation@footnote{https://en.wikipedia.org/wiki/Constant_folding}
is now performed. This means when the JIT compiler detects that certain user
code results in constants, the code can be simplified by the JIT.
(Contributed by Ken Jin and Savannah Ostrowski in gh-132732@footnote{https://github.com/python/cpython/issues/132732}.)

@ref{2c5,,Reference count}s are avoided whenever it is safe to do so. This generally
reduces the cost of most operations in Python.
(Contributed by Ken Jin, Donghee Na, Zheao Li, Hai Zhu, Savannah Ostrowski,
Reiden Ong, Noam Cohen, Tomas Roun, PuQing, Cajetan Rodrigues, and Sacul in gh-134584@footnote{https://github.com/python/cpython/issues/134584}.)

By tracking unique references to objects, the JIT optimizer can now eliminate
reference count updates and perform in-place operations on ints and floats.
(Contributed by Reiden Ong, and Pieter Eendebak in gh-143414@footnote{https://github.com/python/cpython/issues/143414} and gh-146306@footnote{https://github.com/python/cpython/issues/146306}.)

The JIT optimizer now supports significantly more operations than in 3.14.
(Contributed by Kumar Aditya, Ken Jin, Jiahao Li, and Sacul in gh-131798@footnote{https://github.com/python/cpython/issues/131798}.)

@subsubheading GDB and GNU @code{backtrace()} unwinding support


The JIT compiler now publishes unwind information for generated machine code to the
GDB interface on supported Linux ELF platforms. When libgcc frame
registration is available, the same unwind information is also registered for
GNU @code{backtrace()} stack walkers. This allows native debuggers, crash
handlers, and diagnostic tools using these mechanisms to unwind through JIT
frames instead of stopping at generated code.
(Contributed by Diego Russo and Pablo Galindo Salgado in gh-146071@footnote{https://github.com/python/cpython/issues/146071} and
gh-149104@footnote{https://github.com/python/cpython/issues/149104}.)

@subsubheading Better machine code generation


The JIT compiler’s machine code generator now produces better machine code
for x86-64 and AArch64 macOS and Linux targets. In general, users should
experience lower memory usage for generated machine code and more efficient
machine code versus 3.14.
(Contributed by Brandt Bucher in gh-136528@footnote{https://github.com/python/cpython/issues/136528} and gh-135905@footnote{https://github.com/python/cpython/issues/135905}.
Implementation for AArch64 contributed by Mark Shannon in gh-139855@footnote{https://github.com/python/cpython/issues/139855}.
Additional optimizations for AArch64 contributed by Mark Shannon and
Diego Russo in gh-140683@footnote{https://github.com/python/cpython/issues/140683} and gh-142305@footnote{https://github.com/python/cpython/issues/142305}.)

@subsubheading Maintainability


The JIT optimizer’s operations have been simplified.
This was made possible by a refactoring of JIT data structures.
(Contributed by Zhongtian Zheng in gh-148211@footnote{https://github.com/python/cpython/issues/148211} and Hai Zhu in gh-143421@footnote{https://github.com/python/cpython/issues/143421}.)

@node Removed<2>,Deprecated<2>,Optimizations<2>,What’s new in Python 3 15
@anchor{whatsnew/3 15 removed}@anchor{2c6}
@subsection Removed


@menu
* ast: ast<2>. 
* collections.abc: collections abc. 
* ctypes:: 
* datetime:: 
* glob:: 
* http.server: http server<2>. 
* importlib.resources: importlib resources. 
* pathlib:: 
* platform:: 
* sre_*:: 
* sysconfig: sysconfig<2>. 
* threading: threading<2>. 
* types: types<2>. 
* typing: typing<2>. 
* wave: wave<2>. 
* zipimport:: 

@end menu

@node ast<2>,collections abc,,Removed<2>
@anchor{whatsnew/3 15 id1}@anchor{2c7}
@subsubsection ast



@itemize *

@item 
The constructors of @ref{2c8,,AST nodes} now raise a @ref{291,,TypeError}
when a required argument is omitted or when a keyword argument that does not
map to a field on the AST node is passed. These cases had previously raised a
@ref{2c9,,DeprecationWarning} since Python 3.13.
(Contributed by Brian Schubert and Jelle Zijlstra in gh-137600@footnote{https://github.com/python/cpython/issues/137600} and gh-105858@footnote{https://github.com/python/cpython/issues/105858}.)
@end itemize

@node collections abc,ctypes,ast<2>,Removed<2>
@anchor{whatsnew/3 15 collections-abc}@anchor{2ca}
@subsubsection collections.abc



@itemize *

@item 
@ref{2cb,,collections.abc.ByteString} has been removed from
@code{collections.abc.__all__}. @code{collections.abc.ByteString} has been
deprecated since Python 3.12, and is scheduled for removal in Python 3.17.
@end itemize

@node ctypes,datetime,collections abc,Removed<2>
@anchor{whatsnew/3 15 ctypes}@anchor{2cc}
@subsubsection ctypes



@itemize *

@item 
Removed the undocumented function @code{ctypes.SetPointerType()},
which has been deprecated since Python 3.13.
(Contributed by Bénédikt Tran in gh-133866@footnote{https://github.com/python/cpython/issues/133866}.)

@item 
Change the @ref{2cd,,_type_} of
@ref{2ce,,c_float_complex}, @ref{2cf,,c_double_complex} and
@ref{2d0,,c_longdouble_complex} from @code{F}, @code{D} and @code{G} to @code{Zf},
@code{Zd} and @code{Zg} for compatibility with numpy.
(Contributed by Victor Stinner in gh-148675@footnote{https://github.com/python/cpython/issues/148675}.)
@end itemize

@node datetime,glob,ctypes,Removed<2>
@anchor{whatsnew/3 15 datetime}@anchor{2d1}
@subsubsection datetime



@itemize *

@item 
@ref{2d2,,strptime()} now raises @ref{277,,ValueError} when the
format string contains @code{%d} (day of month) without a year directive.
This has been deprecated since Python 3.13.
(Contributed by Stan Ulbrych and Gregory P. Smith in gh-70647@footnote{https://github.com/python/cpython/issues/70647}.)
@end itemize

@node glob,http server<2>,datetime,Removed<2>
@anchor{whatsnew/3 15 glob}@anchor{2d3}
@subsubsection glob



@itemize *

@item 
Removed the undocumented @code{glob.glob0()} and @code{glob.glob1()}
functions, which have been deprecated since Python 3.13. Use
@ref{2d4,,glob.glob()} and pass a directory to its `root_dir' argument instead.
(Contributed by Barney Gale in gh-137466@footnote{https://github.com/python/cpython/issues/137466}.)
@end itemize

@node http server<2>,importlib resources,glob,Removed<2>
@anchor{whatsnew/3 15 id2}@anchor{2d5}
@subsubsection http.server



@itemize *

@item 
Removed the @code{CGIHTTPRequestHandler} class
and the @code{--cgi} flag from the @code{python -m http.server}
command-line interface. They were deprecated in Python 3.13.
(Contributed by Bénédikt Tran in gh-133810@footnote{https://github.com/python/cpython/issues/133810}.)
@end itemize

@node importlib resources,pathlib,http server<2>,Removed<2>
@anchor{whatsnew/3 15 importlib-resources}@anchor{2d6}
@subsubsection importlib.resources



@itemize *

@item 
Removed deprecated @code{package} parameter
from @ref{2d7,,importlib.resources.files()} function.
(Contributed by Semyon Moroz in gh-138044@footnote{https://github.com/python/cpython/issues/138044}.)
@end itemize

@node pathlib,platform,importlib resources,Removed<2>
@anchor{whatsnew/3 15 pathlib}@anchor{2d8}
@subsubsection pathlib



@itemize *

@item 
Removed deprecated @code{pathlib.PurePath.is_reserved()}.
Use @ref{2d9,,os.path.isreserved()} to detect reserved paths on Windows.
(Contributed by Nikita Sobolev in gh-133875@footnote{https://github.com/python/cpython/issues/133875}.)
@end itemize

@node platform,sre_*,pathlib,Removed<2>
@anchor{whatsnew/3 15 platform}@anchor{2da}
@subsubsection platform



@itemize *

@item 
Removed the @code{platform.java_ver()} function,
which was deprecated since Python 3.13.
(Contributed by Alexey Makridenko in gh-133604@footnote{https://github.com/python/cpython/issues/133604}.)
@end itemize

@node sre_*,sysconfig<2>,platform,Removed<2>
@anchor{whatsnew/3 15 sre}@anchor{2db}
@subsubsection sre_*



@itemize *

@item 
Removed @code{sre_compile}, @code{sre_constants} and @code{sre_parse} modules.
(Contributed by Stan Ulbrych in gh-135994@footnote{https://github.com/python/cpython/issues/135994}.)
@end itemize

@node sysconfig<2>,threading<2>,sre_*,Removed<2>
@anchor{whatsnew/3 15 sysconfig}@anchor{2dc}
@subsubsection sysconfig



@itemize *

@item 
Removed the `check_home' parameter of @ref{2dd,,sysconfig.is_python_build()}.
(Contributed by Filipe Laíns in gh-92897@footnote{https://github.com/python/cpython/issues/92897}.)
@end itemize

@node threading<2>,types<2>,sysconfig<2>,Removed<2>
@anchor{whatsnew/3 15 id3}@anchor{2de}
@subsubsection threading



@itemize *

@item 
Remove support for arbitrary positional or keyword arguments in the C
implementation of @ref{2df,,RLock} objects. This was deprecated
in Python 3.14.
(Contributed by Bénédikt Tran in gh-134087@footnote{https://github.com/python/cpython/issues/134087}.)
@end itemize

@node types<2>,typing<2>,threading<2>,Removed<2>
@anchor{whatsnew/3 15 id4}@anchor{2e0}
@subsubsection types



@itemize *

@item 
Removed deprecated in 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/} since Python 3.12
@code{codeobject.co_lnotab} from @ref{2e1,,types.CodeType}.
(Contributed by Nikita Sobolev in gh-134690@footnote{https://github.com/python/cpython/issues/134690}.)
@end itemize

@node typing<2>,wave<2>,types<2>,Removed<2>
@anchor{whatsnew/3 15 id5}@anchor{2e2}
@subsubsection typing



@itemize *

@item 
@ref{2e3,,typing.ByteString} has been removed from @code{typing.__all__}.
@code{typing.ByteString} has been deprecated since Python 3.9, and is
scheduled for removal in Python 3.17.

@item 
The undocumented keyword argument syntax for creating
@ref{2e4,,NamedTuple} classes (for example,
@code{Point = NamedTuple("Point", x=int, y=int)}) is no longer supported.
Use the class-based syntax or the functional syntax instead.
(Contributed by Bénédikt Tran in gh-133817@footnote{https://github.com/python/cpython/issues/133817}.)

@item 
Using @code{TD = TypedDict("TD")} or @code{TD = TypedDict("TD", None)} to
construct a @ref{290,,TypedDict} type with zero fields is no
longer supported. Use @code{class TD(TypedDict): pass}
or @code{TD = TypedDict("TD", @{@})} instead.
(Contributed by Bénédikt Tran in gh-133823@footnote{https://github.com/python/cpython/issues/133823}.)

@item 
Deprecated @code{typing.no_type_check_decorator()} has been removed.
(Contributed by Nikita Sobolev in gh-133601@footnote{https://github.com/python/cpython/issues/133601}.)
@end itemize

@node wave<2>,zipimport,typing<2>,Removed<2>
@anchor{whatsnew/3 15 id6}@anchor{2e5}
@subsubsection wave



@itemize *

@item 
Removed the @code{getmark()}, @code{setmark()} and @code{getmarkers()} methods
of the @ref{2e6,,Wave_read} and @ref{2e7,,Wave_write} classes,
which were deprecated since Python 3.13.
(Contributed by Bénédikt Tran in gh-133873@footnote{https://github.com/python/cpython/issues/133873}.)
@end itemize

@node zipimport,,wave<2>,Removed<2>
@anchor{whatsnew/3 15 zipimport}@anchor{2e8}
@subsubsection zipimport



@itemize *

@item 
Remove deprecated @code{zipimport.zipimporter.load_module()}.
Use @ref{2e9,,zipimport.zipimporter.exec_module()} instead.
(Contributed by Jiahao Li in gh-133656@footnote{https://github.com/python/cpython/issues/133656}.)
@end itemize

@node Deprecated<2>,C API changes<2>,Removed<2>,What’s new in Python 3 15
@anchor{whatsnew/3 15 deprecated}@anchor{2ea}
@subsection Deprecated


@menu
* New deprecations:: 
* Pending removal in Python 3.16: Pending removal in Python 3 16. 
* Pending removal in Python 3.17: Pending removal in Python 3 17. 
* Pending removal in Python 3.18: Pending removal in Python 3 18. 
* Pending removal in Python 3.19: Pending removal in Python 3 19. 
* Pending removal in Python 3.20: Pending removal in Python 3 20. 
* Pending removal in future versions:: 
* Soft deprecations:: 

@end menu

@node New deprecations,Pending removal in Python 3 16,,Deprecated<2>
@anchor{whatsnew/3 15 new-deprecations}@anchor{2eb}
@subsubsection New deprecations



@itemize *

@item 
@ref{9,,ast}


@itemize *

@item 
Creating instances of abstract AST nodes (such as @ref{2ec,,ast.AST}
or @code{ast.expr}) is deprecated and will raise an error in Python 3.20.

(Contributed by Brian Schubert in gh-116021@footnote{https://github.com/python/cpython/issues/116021}.)
@end itemize

@item 
@ref{f,,base64}:


@itemize *

@item 
Accepting the @code{+} and @code{/} characters with an alternative alphabet in
@ref{1ec,,b64decode()} and @ref{1ee,,urlsafe_b64decode()} is now
deprecated.
In future Python versions they will be errors in the strict mode and
discarded in the non-strict mode.
(Contributed by Serhiy Storchaka in gh-125346@footnote{https://github.com/python/cpython/issues/125346}.)
@end itemize

@item 
CLI:


@itemize *

@item 
Deprecate @ref{2ed,,-b} and @code{-bb} command-line options
and schedule them to become no-ops in Python 3.17.
These were primarily helpers for the Python 2 -> 3 transition.
Starting with Python 3.17, no @ref{2ee,,BytesWarning} will be raised
for these cases; use a type checker instead.

(Contributed by Nikita Sobolev in gh-136355@footnote{https://github.com/python/cpython/issues/136355}.)
@end itemize

@item 
@ref{1f,,collections.abc}


@itemize *

@item 
The following statements now cause @code{DeprecationWarning}s to be emitted
at runtime:


@itemize *

@item 
@code{from collections.abc import ByteString}

@item 
@code{import collections.abc; collections.abc.ByteString}.
@end itemize

@code{DeprecationWarning}s were already emitted if
@ref{2cb,,collections.abc.ByteString} was subclassed or used as the second
argument to @ref{2ef,,isinstance()} or @ref{2f0,,issubclass()}, but warnings were not
previously emitted if it was merely imported or accessed from the
@code{collections.abc} module.
@end itemize

@item 
@ref{6b,,hashlib}:


@itemize *

@item 
In hash function constructors such as @ref{2f1,,new()} or the
direct hash-named constructors such as @ref{2f2,,md5()} and
@ref{2f3,,sha256()}, the optional initial data parameter could
also be passed as a keyword argument named @code{data=} or @code{string=} in
various @ref{6b,,hashlib} implementations.

Support for the @code{string} keyword argument name is now deprecated and
is slated for removal in Python 3.19. Prefer passing the initial data as
a positional argument for maximum backwards compatibility.

(Contributed by Bénédikt Tran in gh-134978@footnote{https://github.com/python/cpython/issues/134978}.)
@end itemize

@item 
@ref{74,,http.cookies}:


@itemize *

@item 
@ref{2f4,,Morsel.js_output} and
@ref{2f5,,BaseCookie.js_output} are
deprecated and will be removed in Python 3.19. Use
@ref{2f6,,Morsel.output} or
@ref{2f7,,BaseCookie.output} instead.
(Contributed by kishorhange111 in gh-148849@footnote{https://github.com/python/cpython/issues/148849}.)
@end itemize

@item 
@ref{77,,imaplib}:


@itemize *

@item 
Altering @ref{2f8,,IMAP4.file} is now deprecated
and slated for removal in Python 3.19. This property is now unused
and changing its value does `not' explicitly close the current file.
@end itemize

@item 
@ref{c1,,re}:


@itemize *

@item 
@ref{24c,,re.match()} and @ref{24d,,re.Pattern.match()} are now
@ref{1a7,,soft deprecated} in favor of the new @ref{24a,,re.prefixmatch()} and
@ref{24b,,re.Pattern.prefixmatch()} APIs, which have been added as alternate,
more explicit names. These are intended to be used to alleviate confusion
around what `match' means by following the Zen of Python’s `«Explicit is
better than implicit»' mantra. Most other language regular expression
libraries use an API named `match' to mean what Python has always called
`search'.

We `do not' plan to remove the older @code{match()} name, as it has been
used in code for over 30 years. Code supporting older versions of Python
should continue to use @code{match()}, while new code should prefer
@code{prefixmatch()}. See @ref{2f9,,prefixmatch() vs. match()}.

(Contributed by Gregory P. Smith in gh-86519@footnote{https://github.com/python/cpython/issues/86519} and
Hugo van Kemenade in gh-148100@footnote{https://github.com/python/cpython/issues/148100}.)
@end itemize

@item 
@ref{de,,struct}:


@itemize *

@item 
Calling @code{Struct.__new__()} without a required argument is now
deprecated and will be removed in Python 3.20.  Calling the
@ref{2fa,,__init__()} method on an initialized @ref{2fb,,Struct}
object is deprecated and will be removed in Python 3.20.

(Contributed by Sergey B Kirpichev and Serhiy Storchaka in gh-143715@footnote{https://github.com/python/cpython/issues/143715}.)
@end itemize

@item 
@ref{10d,,typing}:


@itemize *

@item 
The following statements now cause @code{DeprecationWarning}s to be emitted
at runtime:


@itemize *

@item 
@code{from typing import ByteString}

@item 
@code{import typing; typing.ByteString}.
@end itemize

@code{DeprecationWarning}s were already emitted if @ref{2e3,,typing.ByteString}
was subclassed or used as the second argument to @ref{2ef,,isinstance()} or
@ref{2f0,,issubclass()}, but warnings were not previously emitted if it was
merely imported or accessed from the @code{typing} module.
@end itemize

@item 
@ref{11e,,webbrowser}:


@itemize *

@item 
@code{webbrowser.MacOSXOSAScript} is deprecated in favour of
@code{webbrowser.MacOS} and scheduled for removal in Python 3.17.
(Contributed by Jeff Lyon in gh-137586@footnote{https://github.com/python/cpython/issues/137586}.)
@end itemize

@item 
@code{__version__}


@itemize *

@item 
The @code{__version__}, @code{version} and @code{VERSION} attributes have been
deprecated in these standard library modules and will be removed in
Python 3.20. Use @ref{2fc,,sys.version_info} instead.


@itemize -

@item 
@ref{7,,argparse}

@item 
@ref{2c,,csv}

@item 
@ref{2d,,ctypes}

@item 
@code{ctypes.macholib}

@item 
@ref{39,,decimal} (use @ref{2fd,,decimal.SPEC_VERSION} instead)

@item 
@ref{75,,http.server}

@item 
@ref{77,,imaplib}

@item 
@ref{83,,ipaddress}

@item 
@ref{85,,json}

@item 
@ref{8a,,logging} (@code{__date__} also deprecated)

@item 
@ref{a4,,optparse}

@item 
@ref{ab,,pickle}

@item 
@ref{af,,platform}

@item 
@ref{c1,,re}

@item 
@ref{d5,,socketserver}

@item 
@ref{e6,,tabnanny}

@item 
@ref{e7,,tarfile}

@item 
@ref{fe,,tkinter.font}

@item 
@ref{102,,tkinter.ttk}

@item 
@ref{124,,wsgiref.simple_server}

@item 
@ref{12e,,xml.etree.ElementTree}

@item 
@code{xml.sax.expatreader}

@item 
@ref{133,,xml.sax.handler}

@item 
@ref{13c,,zlib}
@end itemize

(Contributed by Hugo van Kemenade and Stan Ulbrych in gh-76007@footnote{https://github.com/python/cpython/issues/76007}.)
@end itemize
@end itemize

@c Add deprecations above alphabetically, not here at the end.

@node Pending removal in Python 3 16,Pending removal in Python 3 17,New deprecations,Deprecated<2>
@anchor{whatsnew/3 15 pending-removal-in-python-3-16}@anchor{2fe}
@subsubsection Pending removal in Python 3.16



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @ref{2ff,,__loader__} on a module while
failing to set @ref{300,,__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{8,,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{301,,Py_UCS4})
for Unicode characters instead.
@end itemize

@item 
@ref{b,,asyncio}:


@itemize *

@item 
@code{asyncio.iscoroutinefunction()} is deprecated
and will be removed in Python 3.16;
use @ref{302,,inspect.iscoroutinefunction()} instead.
(Contributed by Jiahao Li and Kumar Aditya in gh-122875@footnote{https://github.com/python/cpython/issues/122875}.)

@item 
@ref{b,,asyncio} policy system is deprecated and will be removed in Python 3.16.
In particular, the following classes and functions are deprecated:


@itemize *

@item 
@ref{303,,asyncio.AbstractEventLoopPolicy}

@item 
@ref{304,,asyncio.DefaultEventLoopPolicy}

@item 
@ref{305,,asyncio.WindowsSelectorEventLoopPolicy}

@item 
@ref{306,,asyncio.WindowsProactorEventLoopPolicy}

@item 
@ref{307,,asyncio.get_event_loop_policy()}

@item 
@ref{308,,asyncio.set_event_loop_policy()}
@end itemize

Users should use @ref{309,,asyncio.run()} or @ref{30a,,asyncio.Runner} with
`loop_factory' to use the desired event loop implementation.

For example, to use @ref{30b,,asyncio.SelectorEventLoop} on Windows:

@example
import asyncio

async def main():
    ...

asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
@end example

(Contributed by Kumar Aditya in gh-127949@footnote{https://github.com/python/cpython/issues/127949}.)
@end itemize

@item 
@ref{13,,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{62,,functools}:


@itemize *

@item 
Calling the Python implementation of @ref{153,,functools.reduce()} with `function'
or `sequence' as keyword arguments has been deprecated since Python 3.14.
@end itemize

@item 
@ref{8a,,logging}:


@itemize *

@item 
Support for custom logging handlers with the `strm' argument is deprecated
and scheduled for removal in Python 3.16. Define handlers with the `stream'
argument instead. (Contributed by Mariusz Felisiak in gh-115032@footnote{https://github.com/python/cpython/issues/115032}.)
@end itemize

@item 
@ref{93,,mimetypes}:


@itemize *

@item 
Valid extensions start with a “.” or are empty for
@ref{30c,,mimetypes.MimeTypes.add_type()}.
Undotted extensions are deprecated and will
raise a @ref{277,,ValueError} in Python 3.16.
(Contributed by Hugo van Kemenade in gh-75223@footnote{https://github.com/python/cpython/issues/75223}.)
@end itemize

@item 
@ref{cd,,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{30d,,RuntimeError}.
@end itemize

@item 
@ref{e1,,symtable}:


@itemize *

@item 
The @code{symtable.Class.get_methods()} method
has been deprecated since Python 3.14.
@end itemize

@item 
@ref{e2,,sys}:


@itemize *

@item 
The @ref{30e,,_enablelegacywindowsfsencoding()} function
has been deprecated since Python 3.13.
Use the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,PYTHONLEGACYWINDOWSFSENCODING} environment variable instead.
@end itemize

@item 
@ref{e4,,sysconfig}:


@itemize *

@item 
The @code{sysconfig.expand_makefile_vars()} function
has been deprecated since Python 3.14.
Use the @code{vars} argument of @ref{156,,sysconfig.get_paths()} instead.
@end itemize

@item 
@ref{e7,,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 Python 3 17,Pending removal in Python 3 18,Pending removal in Python 3 16,Deprecated<2>
@anchor{whatsnew/3 15 pending-removal-in-python-3-17}@anchor{310}
@subsubsection Pending removal in Python 3.17



@itemize *

@item 
@ref{33,,datetime}:


@itemize *

@item 
@ref{2d2,,strptime()} calls using a format string containing
@code{%e} (day of month) without a year.
This has been deprecated since Python 3.15.
(Contributed by Stan Ulbrych in gh-70647@footnote{https://github.com/python/cpython/issues/70647}.)
@end itemize

@item 
@ref{1f,,collections.abc}:


@itemize -

@item 
@ref{2cb,,collections.abc.ByteString} is scheduled for removal in Python 3.17.

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj}
implements the @ref{311,,buffer protocol} at runtime. For use
in type annotations, either use @ref{312,,Buffer} or a union
that explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} was originally intended to be an abstract class that
would serve as a supertype of both @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
However, since the ABC never had any methods, knowing that an object was an
instance of @code{ByteString} never actually told you anything useful
about the object. Other common buffer types such as @ref{1d2,,memoryview}
were also never understood as subtypes of @code{ByteString} (either at
runtime or by static type checkers).

See 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} for more details.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)
@end itemize

@item 
@ref{54,,encodings}:


@itemize -

@item 
Passing non-ascii `encoding' names to @ref{313,,encodings.normalize_encoding()}
is deprecated and scheduled for removal in Python 3.17.
(Contributed by Stan Ulbrych in gh-136702@footnote{https://github.com/python/cpython/issues/136702}.)
@end itemize

@item 
@ref{11e,,webbrowser}:


@itemize -

@item 
@code{webbrowser.MacOSXOSAScript} is deprecated in favour of
@code{webbrowser.MacOS}. (gh-137586@footnote{https://github.com/python/cpython/issues/137586})
@end itemize

@item 
@ref{10d,,typing}:


@itemize -

@item 
Before Python 3.14, old-style unions were implemented using the private class
@code{typing._UnionGenericAlias}. This class is no longer needed for the implementation,
but it has been retained for backward compatibility, with removal scheduled for Python
3.17. Users should use documented introspection helpers like @ref{314,,typing.get_origin()}
and @ref{315,,typing.get_args()} instead of relying on private implementation details.

@item 
@ref{2e3,,typing.ByteString}, deprecated since Python 3.9, is scheduled for removal in
Python 3.17.

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj}
implements the @ref{311,,buffer protocol} at runtime. For use
in type annotations, either use @ref{312,,Buffer} or a union
that explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} was originally intended to be an abstract class that
would serve as a supertype of both @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
However, since the ABC never had any methods, knowing that an object was an
instance of @code{ByteString} never actually told you anything useful
about the object. Other common buffer types such as @ref{1d2,,memoryview}
were also never understood as subtypes of @code{ByteString} (either at
runtime or by static type checkers).

See 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} for more details.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)
@end itemize
@end itemize

@node Pending removal in Python 3 18,Pending removal in Python 3 19,Pending removal in Python 3 17,Deprecated<2>
@anchor{whatsnew/3 15 pending-removal-in-python-3-18}@anchor{316}
@subsubsection Pending removal in Python 3.18



@itemize *

@item 
No longer accept a boolean value when a file descriptor is expected.
(Contributed by Serhiy Storchaka in gh-82626@footnote{https://github.com/python/cpython/issues/82626}.)

@item 
@ref{39,,decimal}:


@itemize *

@item 
The non-standard and undocumented @ref{1c2,,Decimal} format
specifier @code{'N'}, which is only supported in the @code{decimal} module’s
C implementation, has been deprecated since Python 3.13.
(Contributed by Serhiy Storchaka in gh-89902@footnote{https://github.com/python/cpython/issues/89902}.)
@end itemize

@item 
Deprecations defined by 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/}:


@itemize *

@item 
@code{import} lines in @code{`name'.pth} files are silently ignored.
@end itemize

(Contributed by Barry Warsaw in gh-148641@footnote{https://github.com/python/cpython/issues/148641}.)
@end itemize

@node Pending removal in Python 3 19,Pending removal in Python 3 20,Pending removal in Python 3 18,Deprecated<2>
@anchor{whatsnew/3 15 pending-removal-in-python-3-19}@anchor{317}
@subsubsection Pending removal in Python 3.19



@itemize *

@item 
@ref{2d,,ctypes}:


@itemize *

@item 
Implicitly switching to the MSVC-compatible struct layout by setting
@ref{318,,_pack_} but not @ref{319,,_layout_}
on non-Windows platforms.
@end itemize

@item 
@ref{6b,,hashlib}:


@itemize -

@item 
In hash function constructors such as @ref{2f1,,new()} or the
direct hash-named constructors such as @ref{2f2,,md5()} and
@ref{2f3,,sha256()}, their optional initial data parameter could
also be passed a keyword argument named @code{data=} or @code{string=} in
various @code{hashlib} implementations.

Support for the @code{string} keyword argument name is now deprecated
and slated for removal in Python 3.19.

Before Python 3.13, the @code{string} keyword parameter was not correctly
supported depending on the backend implementation of hash functions.
Prefer passing the initial data as a positional argument for maximum
backwards compatibility.
@end itemize

@item 
@ref{74,,http.cookies}:


@itemize *

@item 
@ref{2f4,,http.cookies.Morsel.js_output()} is deprecated and will be
removed in Python 3.19.

@item 
@ref{2f5,,http.cookies.BaseCookie.js_output()} is deprecated and will be
removed in Python 3.19.
@end itemize

@item 
@ref{77,,imaplib}:


@itemize *

@item 
Altering @ref{2f8,,IMAP4.file} is now deprecated
and slated for removal in Python 3.19. This property is now unused
and changing its value does not automatically close the current file.

Before Python 3.14, this property was used to implement the corresponding
@code{read()} and @code{readline()} methods for @ref{31a,,IMAP4} but this
is no longer the case since then.
@end itemize
@end itemize

@node Pending removal in Python 3 20,Pending removal in future versions,Pending removal in Python 3 19,Deprecated<2>
@anchor{whatsnew/3 15 pending-removal-in-python-3-20}@anchor{31b}
@subsubsection Pending removal in Python 3.20



@itemize *

@item 
Calling the @code{__new__()} method of @ref{2fb,,struct.Struct} without the
`format' argument is deprecated and will be removed in Python 3.20.  Calling
@ref{2fa,,__init__()} method on initialized @code{Struct}
objects is deprecated and will be removed in Python 3.20.

(Contributed by Sergey B Kirpichev and Serhiy Storchaka in gh-143715@footnote{https://github.com/python/cpython/issues/143715}.)

@item 
The @code{__version__}, @code{version} and @code{VERSION} attributes have been
deprecated in these standard library modules and will be removed in
Python 3.20. Use @ref{2fc,,sys.version_info} instead.


@itemize -

@item 
@ref{7,,argparse}

@item 
@ref{2c,,csv}

@item 
@ref{2d,,ctypes}

@item 
@code{ctypes.macholib}

@item 
@ref{39,,decimal} (use @ref{2fd,,decimal.SPEC_VERSION} instead)

@item 
@ref{75,,http.server}

@item 
@ref{77,,imaplib}

@item 
@ref{83,,ipaddress}

@item 
@ref{85,,json}

@item 
@ref{8a,,logging} (@code{__date__} also deprecated)

@item 
@ref{a4,,optparse}

@item 
@ref{ab,,pickle}

@item 
@ref{af,,platform}

@item 
@ref{c1,,re}

@item 
@ref{d5,,socketserver}

@item 
@ref{e6,,tabnanny}

@item 
@ref{e7,,tarfile}

@item 
@ref{fe,,tkinter.font}

@item 
@ref{102,,tkinter.ttk}

@item 
@ref{124,,wsgiref.simple_server}

@item 
@ref{12e,,xml.etree.ElementTree}

@item 
@code{xml.sax.expatreader}

@item 
@ref{133,,xml.sax.handler}

@item 
@ref{13c,,zlib}
@end itemize

(Contributed by Hugo van Kemenade and Stan Ulbrych in gh-76007@footnote{https://github.com/python/cpython/issues/76007}.)

@item 
Deprecations defined by 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/}:


@itemize *

@item 
Warnings are produced for @code{import} lines found in @code{`name'.pth}
files.

@item 
@code{`name'.pth} files are no longer decoded in the locale encoding by
default.  They `MUST' be encoded in @code{utf-8-sig}.
@end itemize

(Contributed by Barry Warsaw in gh-148641@footnote{https://github.com/python/cpython/issues/148641}.)

@item 
@ref{9,,ast}:


@itemize *

@item 
Creating instances of abstract AST nodes (such as @ref{2ec,,ast.AST}
or @code{ast.expr}) is deprecated and will raise an error in Python 3.20.
@end itemize
@end itemize

@node Pending removal in future versions,Soft deprecations,Pending removal in Python 3 20,Deprecated<2>
@anchor{whatsnew/3 15 pending-removal-in-future-versions}@anchor{31c}
@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{7,,argparse}:


@itemize *

@item 
Nesting argument groups and nesting mutually exclusive
groups are deprecated.

@item 
Passing the undocumented keyword argument `prefix_chars' to
@ref{31d,,add_argument_group()} is now
deprecated.

@item 
The @ref{31e,,argparse.FileType} type converter is deprecated.
@end itemize

@item 
@ref{13,,builtins}:


@itemize *

@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{31f,,and}, @ref{320,,else}, @ref{321,,for}, @ref{322,,if},
@ref{323,,in}, @ref{324,,is} and @ref{325,,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{326,,int}.

@item 
Support for @code{__float__()} method returning a strict subclass of
@ref{327,,float}: these methods will be required to return an instance of
@code{float}.

@item 
Support for @code{__complex__()} method returning a strict subclass of
@ref{328,,complex}: these methods will be required to return an instance of
@code{complex}.

@item 
Passing a complex number as the `real' or `imag' argument in the
@ref{328,,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{15,,calendar}: @code{calendar.January} and @code{calendar.February} constants are
deprecated and replaced by @ref{329,,calendar.JANUARY} and
@ref{32a,,calendar.FEBRUARY}.
(Contributed by Prince Roshan in gh-103636@footnote{https://github.com/python/cpython/issues/103636}.)

@item 
@ref{1c,,codecs}: use @ref{32b,,open()} instead of @ref{32c,,codecs.open()}. (gh-133038@footnote{https://github.com/python/cpython/issues/133038})

@item 
@code{codeobject.co_lnotab}: use the @ref{32d,,codeobject.co_lines()} method
instead.

@item 
@ref{33,,datetime}:


@itemize *

@item 
@ref{32e,,utcnow()}:
use @code{datetime.datetime.now(tz=datetime.UTC)}.

@item 
@ref{32f,,utcfromtimestamp()}:
use @code{datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)}.
@end itemize

@item 
@ref{66,,gettext}: Plural value must be an integer.

@item 
@ref{7a,,importlib}:


@itemize *

@item 
@ref{330,,cache_from_source()} `debug_override' parameter is
deprecated: use the `optimization' parameter instead.
@end itemize

@item 
@ref{7d,,importlib.metadata}:


@itemize *

@item 
@code{EntryPoints} tuple interface.

@item 
Implicit @code{None} on return values.
@end itemize

@item 
@ref{8a,,logging}: the @code{warn()} method has been deprecated
since Python 3.3, use @ref{331,,warning()} instead.

@item 
@ref{8e,,mailbox}: Use of StringIO input and text mode is deprecated, use
BytesIO and binary mode instead.

@item 
@ref{a5,,os}: Calling @ref{332,,os.register_at_fork()} in a multi-threaded process.

@item 
@ref{a6,,os.path}: @ref{333,,os.path.commonprefix()} is deprecated, use
@ref{334,,os.path.commonpath()} for path prefixes. The @code{os.path.commonprefix()}
function is being deprecated due to having a misleading name and module.
The function is not safe to use for path prefixes despite being included in a
module about path manipulation, meaning it is easy to accidentally
introduce path traversal vulnerabilities into Python programs by using this
function.

@item 
@code{pydoc.ErrorDuringImport}: A tuple value for `exc_info' parameter is
deprecated, use an exception instance.

@item 
@ref{c1,,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 
@ref{cd,,shutil}: @ref{335,,rmtree()}”s `onerror' parameter is deprecated in
Python 3.12; use the `onexc' parameter instead.

@item 
@ref{d8,,ssl} options and protocols:


@itemize *

@item 
@ref{336,,ssl.SSLContext} without protocol argument is deprecated.

@item 
@ref{336,,ssl.SSLContext}: @ref{337,,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{f6,,threading} methods:


@itemize *

@item 
@code{threading.Condition.notifyAll()}: use @ref{338,,notify_all()}.

@item 
@code{threading.Event.isSet()}: use @ref{339,,is_set()}.

@item 
@code{threading.Thread.isDaemon()}, @ref{33a,,threading.Thread.setDaemon()}:
use @ref{33b,,threading.Thread.daemon} attribute.

@item 
@code{threading.Thread.getName()}, @ref{33c,,threading.Thread.setName()}:
use @ref{33d,,threading.Thread.name} attribute.

@item 
@code{threading.currentThread()}: use @ref{33e,,threading.current_thread()}.

@item 
@code{threading.activeCount()}: use @ref{33f,,threading.active_count()}.
@end itemize

@item 
@ref{340,,typing.Text} (gh-92332@footnote{https://github.com/python/cpython/issues/92332}).

@item 
The internal class @code{typing._UnionGenericAlias} is no longer used to implement
@ref{341,,typing.Union}. To preserve compatibility with users using this private
class, a compatibility shim will be provided until at least Python 3.17. (Contributed by
Jelle Zijlstra in gh-105499@footnote{https://github.com/python/cpython/issues/105499}.)

@item 
@ref{342,,unittest.IsolatedAsyncioTestCase}: it is deprecated to return a value
that is not @code{None} from a test case.

@item 
@ref{113,,urllib.parse} deprecated functions: @ref{2a4,,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{121,,wsgiref}: @code{SimpleHandler.stdout.write()} should not do partial
writes.

@item 
@ref{12e,,xml.etree.ElementTree}: Testing the truth value of an
@ref{343,,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{344,,sys._clear_type_cache()} is deprecated:
use @ref{345,,sys._clear_internal_caches()} instead.
@end itemize

@node Soft deprecations,,Pending removal in future versions,Deprecated<2>
@anchor{whatsnew/3 15 soft-deprecations}@anchor{346}
@subsubsection Soft deprecations


There are no plans to remove @ref{1a7,,soft deprecated} APIs.


@itemize *

@item 
@ref{24c,,re.match()} and @ref{24d,,re.Pattern.match()} are now
@ref{1a7,,soft deprecated} in favor of the new @ref{24a,,re.prefixmatch()} and
@ref{24b,,re.Pattern.prefixmatch()} APIs, which have been added as alternate,
more explicit names. These are intended to be used to alleviate confusion
around what `match' means by following the Zen of Python’s `«Explicit is
better than implicit»' mantra. Most other language regular expression
libraries use an API named `match' to mean what Python has always called
`search'.

We `do not' plan to remove the older @code{match()} name, as it has been
used in code for over 30 years. Code supporting older versions of Python
should continue to use @code{match()}, while new code should prefer
@code{prefixmatch()}. See @ref{2f9,,prefixmatch() vs. match()}.

(Contributed by Gregory P. Smith in gh-86519@footnote{https://github.com/python/cpython/issues/86519} and
Hugo van Kemenade in gh-148100@footnote{https://github.com/python/cpython/issues/148100}.)
@end itemize

@node C API changes<2>,Build changes<2>,Deprecated<2>,What’s new in Python 3 15
@anchor{whatsnew/3 15 c-api-changes}@anchor{347}
@subsection C API changes


@menu
* New features: New features<4>. 
* Changed C APIs:: 
* Removed C APIs: Removed C APIs<2>. 
* Deprecated C APIs: Deprecated C APIs<2>. 

@end menu

@node New features<4>,Changed C APIs,,C API changes<2>
@anchor{whatsnew/3 15 id7}@anchor{348}
@subsubsection New features



@itemize *

@item 
Add @ref{349,,PyArg_ParseArray()} and @ref{34a,,PyArg_ParseArrayAndKeywords()}
functions to parse arguments of functions using the @ref{34b,,METH_FASTCALL}
calling convention.
(Contributed by Victor Stinner in gh-144175@footnote{https://github.com/python/cpython/issues/144175}.)

@item 
Add the following functions for the new @ref{182,,frozendict} type:


@itemize *

@item 
@ref{34c,,PyAnyDict_Check()}

@item 
@ref{34d,,PyAnyDict_CheckExact()}

@item 
@ref{34e,,PyFrozenDict_Check()}

@item 
@ref{34f,,PyFrozenDict_CheckExact()}

@item 
@ref{350,,PyFrozenDict_New()}
@end itemize

(Contributed by Victor Stinner in gh-141510@footnote{https://github.com/python/cpython/issues/141510}.)

@item 
Add @ref{351,,PyObject_CallFinalizerFromDealloc()} function to the limited C
API.
(Contributed by Victor Stinner in gh-146063@footnote{https://github.com/python/cpython/issues/146063}.)

@item 
Add @ref{352,,PySys_GetAttr()}, @ref{353,,PySys_GetAttrString()},
@ref{354,,PySys_GetOptionalAttr()}, and @ref{355,,PySys_GetOptionalAttrString()}
functions as replacements for @ref{356,,PySys_GetObject()}.
(Contributed by Serhiy Storchaka in gh-108512@footnote{https://github.com/python/cpython/issues/108512}.)

@item 
Add @ref{357,,PyUnstable_Unicode_GET_CACHED_HASH} to get the cached hash of
a string. See the documentation for caveats.
(Contributed by Petr Viktorin in gh-131510@footnote{https://github.com/python/cpython/issues/131510}.)

@item 
Add API for checking an extension module’s ABI compatibility:
@ref{358,,Py_mod_abi}, @ref{359,,PyABIInfo_Check()},
and @ref{35a,,PyABIInfo_VAR}.
(Contributed by Petr Viktorin in gh-137210@footnote{https://github.com/python/cpython/issues/137210}.)
@end itemize
@anchor{whatsnew/3 15 whatsnew315-pybyteswriter}@anchor{16e}

@itemize *

@item 
Implement 
@geindex Python Enhancement Proposals; PEP 782
PEP 782@footnote{https://peps.python.org/pep-0782/}, the @ref{35b,,PyBytesWriter API}.
Add functions:


@itemize *

@item 
@ref{35c,,PyBytesWriter_Create()}

@item 
@ref{35d,,PyBytesWriter_Discard()}

@item 
@ref{35e,,PyBytesWriter_FinishWithPointer()}

@item 
@ref{35f,,PyBytesWriter_FinishWithSize()}

@item 
@ref{360,,PyBytesWriter_Finish()}

@item 
@ref{361,,PyBytesWriter_Format()}

@item 
@ref{362,,PyBytesWriter_GetData()}

@item 
@ref{363,,PyBytesWriter_GetSize()}

@item 
@ref{364,,PyBytesWriter_GrowAndUpdatePointer()}

@item 
@ref{365,,PyBytesWriter_Grow()}

@item 
@ref{366,,PyBytesWriter_Resize()}

@item 
@ref{367,,PyBytesWriter_WriteBytes()}
@end itemize

(Contributed by Victor Stinner in gh-129813@footnote{https://github.com/python/cpython/issues/129813}.)

@item 
@ref{368,,PyCriticalSection} and related functions are added to the Stable
ABI.

(Contributed in gh-149227@footnote{https://github.com/python/cpython/issues/149227}.)

@item 
Add a new @ref{369,,PyImport_CreateModuleFromInitfunc()} C-API for creating
a module from a `spec' and `initfunc'.
(Contributed by Itamar Oren in gh-116146@footnote{https://github.com/python/cpython/issues/116146}.)

@item 
Add @ref{36a,,PyTuple_FromArray()} to create a @ref{1ce,,tuple} from an array.
(Contributed by Victor Stinner in gh-111489@footnote{https://github.com/python/cpython/issues/111489}.)

@item 
Add a new module export hook,
@ref{19c,,PyModExport_*}.

(Contributed by Petr Viktorin in 
@geindex Python Enhancement Proposals; PEP 793
PEP 793@footnote{https://peps.python.org/pep-0793/} and gh-140550@footnote{https://github.com/python/cpython/issues/140550}.)

@item 
Add functions that are guaranteed to be safe for use in
@ref{36b,,tp_traverse} handlers:
@ref{36c,,PyObject_GetTypeData_DuringGC()},
@ref{36d,,PyObject_GetItemData_DuringGC()},
@ref{36e,,PyType_GetModuleState_DuringGC()},
@ref{36f,,PyModule_GetState_DuringGC()}, @ref{370,,PyModule_GetToken_DuringGC()},
@ref{371,,PyType_GetBaseByToken_DuringGC()},
@ref{372,,PyType_GetModule_DuringGC()},
@ref{373,,PyType_GetModuleByToken_DuringGC()}.
(Contributed by Petr Viktorin in gh-145925@footnote{https://github.com/python/cpython/issues/145925}.)

@item 
Add @ref{374,,PyObject_Dump()} to dump an object to @code{stderr}.
It should only be used for debugging.
(Contributed by Victor Stinner in gh-141070@footnote{https://github.com/python/cpython/issues/141070}.)

@item 
Implement 
@geindex Python Enhancement Proposals; PEP 820
PEP 820@footnote{https://peps.python.org/pep-0820/}: @code{PySlot} – Unified slot system for the C API.
See @ref{375,,Definition slots} for documentation.

This adds:


@itemize *

@item 
The @ref{19d,,PySlot} struct;

@item 
the @ref{376,,PyType_FromSlots()} function;

@item 
new slot IDs: @ref{377,,Py_slot_end}, @ref{378,,Py_slot_invalid};
@ref{379,,Py_slot_subslots}, @ref{37a,,Py_tp_slots},
@ref{37b,,Py_mod_slots};
@ref{37c,,Py_tp_name}, @ref{37d,,Py_tp_basicsize},
@ref{37e,,Py_tp_extra_basicsize}, @ref{37f,,Py_tp_itemsize},
@ref{380,,Py_tp_flags}, @ref{381,,Py_tp_metaclass},
@ref{382,,Py_tp_module};

@item 
convenience macros: @ref{383,,PySlot_DATA}, @ref{384,,PySlot_FUNC},
@ref{385,,PySlot_SIZE}, @ref{386,,PySlot_INT64}, @ref{387,,PySlot_UINT64},
@ref{388,,PySlot_STATIC_DATA}, @ref{389,,PySlot_END},
@ref{38a,,PySlot_PTR}, @ref{38b,,PySlot_PTR_STATIC}.
@end itemize

The @ref{38c,,PyModule_FromSlotsAndSpec()} function and
@code{PyModExport} @ref{38d,,module export hook} also
use the new @code{PySlot} struct.

These following functions are @ref{1a7,,soft deprecated}:


@itemize *

@item 
@ref{38e,,PyType_FromSpec()}

@item 
@ref{38f,,PyType_FromSpecWithBases()}

@item 
@ref{390,,PyType_FromModuleAndSpec()}

@item 
@ref{391,,PyType_FromMetaclass()}

@item 
@ref{392,,PyModule_FromDefAndSpec()}

@item 
@ref{393,,PyModule_FromDefAndSpec2()}

@item 
@ref{394,,PyModule_ExecDef()}
@end itemize

(Contributed by Petr Viktorin in gh-149044@footnote{https://github.com/python/cpython/issues/149044}.)

@item 
Add @ref{395,,PyUnstable_ThreadState_SetStackProtection()} and
@ref{396,,PyUnstable_ThreadState_ResetStackProtection()} functions to set
the stack protection base address and stack protection size of a Python
thread state.
(Contributed by Victor Stinner in gh-139653@footnote{https://github.com/python/cpython/issues/139653}.)

@item 
Add @ref{397,,PyUnstable_SetImmortal()} C-API function to mark objects as @ref{398,,immortal}.
(Contributed by Kumar Aditya in gh-143300@footnote{https://github.com/python/cpython/issues/143300}.)

@item 
Restore private provisional @code{_Py_InitializeMain()} function removed in
Python 3.14.
(Contributed by Victor Stinner in gh-142417@footnote{https://github.com/python/cpython/issues/142417}.)

@item 
Add @ref{399,,PyUnstable_DumpTraceback()} and
@ref{39a,,PyUnstable_DumpTracebackThreads()} functions to output Python
stacktraces.
(Contributed by Alex Malyshev in gh-145559@footnote{https://github.com/python/cpython/issues/145559}.)
@end itemize

@node Changed C APIs,Removed C APIs<2>,New features<4>,C API changes<2>
@anchor{whatsnew/3 15 changed-c-apis}@anchor{39b}
@subsubsection Changed C APIs



@itemize *

@item 
If the @ref{39c,,Py_TPFLAGS_MANAGED_DICT} or @ref{39d,,Py_TPFLAGS_MANAGED_WEAKREF}
flag is set then @ref{39e,,Py_TPFLAGS_HAVE_GC} must be set too.
(Contributed by Sergey Miryanov in gh-134786@footnote{https://github.com/python/cpython/issues/134786}.)

@item 
@ref{39f,,PyDateTime_IMPORT} is now thread safe. Code that directly checks @code{PyDateTimeAPI}
for @code{NULL} should be updated to call @code{PyDateTime_IMPORT} instead.
(Contributed by Kumar Aditya in gh-141563@footnote{https://github.com/python/cpython/issues/141563}.)
@end itemize

@node Removed C APIs<2>,Deprecated C APIs<2>,Changed C APIs,C API changes<2>
@anchor{whatsnew/3 15 removed-c-apis}@anchor{3a0}
@subsubsection Removed C APIs



@itemize *

@item 
Remove deprecated @code{PyUnicode} functions:


@itemize *

@item 
@code{PyUnicode_AsDecodedObject()}:
Use @ref{3a1,,PyCodec_Decode()} instead.

@item 
@code{PyUnicode_AsDecodedUnicode()}:
Use @ref{3a1,,PyCodec_Decode()} instead; note that some codecs (for example, «base64»)
may return a type other than @ref{1df,,str}, such as @ref{1c7,,bytes}.

@item 
@code{PyUnicode_AsEncodedObject()}:
Use @ref{3a2,,PyCodec_Encode()} instead.

@item 
@code{PyUnicode_AsEncodedUnicode()}:
Use @ref{3a2,,PyCodec_Encode()} instead; note that some codecs (for example, «base64»)
may return a type other than @ref{1c7,,bytes}, such as @ref{1df,,str}.
@end itemize

(Contributed by Stan Ulbrych in gh-133612@footnote{https://github.com/python/cpython/issues/133612}.)

@item 
@code{PyImport_ImportModuleNoBlock()}: deprecated alias
of @ref{3a3,,PyImport_ImportModule()}.
(Contributed by Bénédikt Tran in gh-133644@footnote{https://github.com/python/cpython/issues/133644}.)

@item 
@code{PyWeakref_GetObject()} and @code{PyWeakref_GET_OBJECT}:
use @ref{3a4,,PyWeakref_GetRef()} instead. The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat}
can be used to get @code{PyWeakref_GetRef()} on Python 3.12 and older.
(Contributed by Bénédikt Tran in gh-133644@footnote{https://github.com/python/cpython/issues/133644}.)

@item 
Remove deprecated @code{PySys_ResetWarnOptions()}.
Clear @ref{3a5,,sys.warnoptions} and @code{warnings.filters} instead.

(Contributed by Nikita Sobolev in gh-138886@footnote{https://github.com/python/cpython/issues/138886}.)
@end itemize

The following functions are removed in favor of @ref{3a6,,PyConfig_Get()}.
The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat} can be used to get @code{PyConfig_Get()}
on Python 3.13 and older.


@itemize *

@item 
Python initialization functions:


@itemize *

@item 
@code{Py_GetExecPrefix()}:
use @ref{3a6,,PyConfig_Get("base_exec_prefix")}
(@ref{3a7,,sys.base_exec_prefix}) instead.
Use @code{PyConfig_Get("exec_prefix")}
(@ref{3a8,,sys.exec_prefix}) if @ref{3a9,,virtual environments}
need to be handled.

@item 
@code{Py_GetPath()}:
use @ref{3a6,,PyConfig_Get("module_search_paths")}
(@ref{194,,sys.path}) instead.

@item 
@code{Py_GetPrefix()}:
use @ref{3a6,,PyConfig_Get("base_prefix")}
(@ref{3aa,,sys.base_prefix}) instead.
Use @code{PyConfig_Get("prefix")}
(@ref{3ab,,sys.prefix}) if @ref{3a9,,virtual environments}
need to be handled.

@item 
@code{Py_GetProgramFullPath()}:
use @ref{3a6,,PyConfig_Get("executable")}
(@ref{3ac,,sys.executable}) instead.

@item 
@code{Py_GetProgramName()}:
use @ref{3a6,,PyConfig_Get("executable")}
(@ref{3ac,,sys.executable}) instead.

@item 
@code{Py_GetPythonHome()}:
use @ref{3a6,,PyConfig_Get("home")} or the
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} environment variable instead.
@end itemize

(Contributed by Bénédikt Tran in gh-133644@footnote{https://github.com/python/cpython/issues/133644}.)
@end itemize

@node Deprecated C APIs<2>,,Removed C APIs<2>,C API changes<2>
@anchor{whatsnew/3 15 deprecated-c-apis}@anchor{3ae}@anchor{whatsnew/3 15 pythoncapi-compat-project-link}@anchor{3af}
@subsubsection Deprecated C APIs



@itemize *

@item 
Deprecate 
@geindex Python Enhancement Proposals; PEP 456
PEP 456@footnote{https://peps.python.org/pep-0456/} support for providing an external definition
of the string hashing scheme. Removal is scheduled for Python 3.19.

Previously, embedders could define @ref{3b0,,Py_HASH_ALGORITHM} to be
@code{Py_HASH_EXTERNAL} to indicate that the hashing scheme was provided
externally but this feature was undocumented, untested and most likely
unused.

(Contributed by Bénédikt Tran in gh-141226@footnote{https://github.com/python/cpython/issues/141226}.)

@item 
For unsigned integer formats in @ref{3b1,,PyArg_ParseTuple()},
accepting Python integers with value that is larger than the maximal value
for the C type or less than the minimal value for the corresponding
signed integer type of the same size is now deprecated.
(Contributed by Serhiy Storchaka in gh-132629@footnote{https://github.com/python/cpython/issues/132629}.)

@item 
@ref{3b2,,PyBytes_FromStringAndSize(NULL@comma{} len)}
and @ref{3b3,,_PyBytes_Resize()} are @ref{1a7,,soft deprecated},
use the @ref{3b4,,PyBytesWriter} API instead.
(Contributed by Victor Stinner in gh-129813@footnote{https://github.com/python/cpython/issues/129813}.)

@item 
@code{_PyObject_CallMethodId()}, @code{_PyObject_GetAttrId()} and
@code{_PyUnicode_FromId()} are deprecated since 3.15 and will be removed in
3.20. Instead, use @ref{3b5,,PyUnicode_InternFromString()} and cache the result in
the module state, then call @ref{3b6,,PyObject_CallMethod()} or
@ref{3b7,,PyObject_GetAttr()}.
(Contributed by Victor Stinner in gh-141049@footnote{https://github.com/python/cpython/issues/141049}.)

@item 
Deprecate @ref{3b8,,cval} field of the
@ref{3b9,,PyComplexObject} type.
Use @ref{3ba,,PyComplex_AsCComplex()} and @ref{3bb,,PyComplex_FromCComplex()}
to convert a Python complex number to/from the C @ref{3bc,,Py_complex}
representation.
(Contributed by Sergey B Kirpichev in gh-128813@footnote{https://github.com/python/cpython/issues/128813}.)

@item 
Functions @ref{3bd,,_Py_c_sum()}, @ref{3be,,_Py_c_diff()}, @ref{3bf,,_Py_c_neg()},
@ref{3c0,,_Py_c_prod()}, @ref{3c1,,_Py_c_quot()}, @ref{3c2,,_Py_c_pow()} and
@ref{3c3,,_Py_c_abs()} are @ref{1a7,,soft deprecated}.
(Contributed by Sergey B Kirpichev in gh-128813@footnote{https://github.com/python/cpython/issues/128813}.)

@item 
@ref{3c4,,bytes_warning} is deprecated
since 3.15 and will be removed in 3.17.
(Contributed by Nikita Sobolev in gh-136355@footnote{https://github.com/python/cpython/issues/136355}.)

@item 
@code{Py_INFINITY} macro is @ref{1a7,,soft deprecated},
use the C11 standard @code{<math.h>} @code{INFINITY} instead.
(Contributed by Sergey B Kirpichev in gh-141004@footnote{https://github.com/python/cpython/issues/141004}.)

@item 
The following macros are @ref{1a7,,soft deprecated}:


@itemize -

@item 
@ref{3c5,,Py_ALIGNED}: Prefer @code{alignas} instead.

@item 
@ref{3c6,,PY_FORMAT_SIZE_T}: Use @code{"z"} directly.

@item 
@ref{3c7,,Py_LL} and @ref{3c8,,Py_ULL}:
Use standard suffixes, @code{LL} and @code{ULL}.

@item 
@ref{3c9,,PY_LONG_LONG}, @ref{3ca,,PY_LLONG_MIN}, @ref{3cb,,PY_LLONG_MAX},
@ref{3cc,,PY_ULLONG_MAX}, @ref{3cd,,PY_INT32_T}, @ref{3ce,,PY_UINT32_T},
@ref{3cf,,PY_INT64_T}, @ref{3d0,,PY_UINT64_T}, @ref{3d1,,PY_SIZE_MAX}:
Use C99 types/limits.

@item 
@ref{3d2,,Py_UNICODE_SIZE}: Use @code{sizeof(wchar_t)} directly.

@item 
@ref{3d3,,Py_VA_COPY}: Use @code{va_copy} directly.
@end itemize

The macro @ref{3d4,,Py_UNICODE_WIDE}, which was scheduled for removal,
is @ref{1a7,,soft deprecated} instead.

(Contributed by Petr Viktorin in gh-146175@footnote{https://github.com/python/cpython/issues/146175}.)

@item 
@code{Py_MATH_El} and @code{Py_MATH_PIl} are deprecated
since 3.15 and will be removed in 3.20.
(Contributed by Sergey B Kirpichev in gh-141004@footnote{https://github.com/python/cpython/issues/141004}.)
@end itemize

@c Add C API deprecations above alphabetically, not here at the end.

@node Build changes<2>,Porting to Python 3 15,C API changes<2>,What’s new in Python 3 15
@anchor{whatsnew/3 15 build-changes}@anchor{3d5}
@subsection Build changes



@itemize *

@item 
Removed implicit fallback to the bundled copy of the @code{libmpdec} library.
Now this should be explicitly enabled with @ref{3d6,,--with-system-libmpdec}
set to @code{no} or with @code{--without-system-libmpdec}.
(Contributed by Sergey B Kirpichev in gh-115119@footnote{https://github.com/python/cpython/issues/115119}.)

@item 
The new configure option @ref{3d7,,--with-missing-stdlib-config=FILE} allows
distributors to pass a JSON@footnote{https://www.json.org/json-en.html}
configuration file containing custom error messages for @ref{3d8,,standard library}
modules that are missing or packaged separately.
(Contributed by Stan Ulbrych and Petr Viktorin in gh-139707@footnote{https://github.com/python/cpython/issues/139707}.)

@item 
The new configure option @ref{3d9,,--with-pymalloc-hugepages} enables huge
page support for @ref{3da,,pymalloc} arenas. When enabled, arena size
increases to 2 MiB and allocation uses @code{MAP_HUGETLB} (Linux) or
@code{MEM_LARGE_PAGES} (Windows) with automatic fallback to regular pages.
On Windows, use @code{build.bat --pymalloc-hugepages}.
At runtime, huge pages must be explicitly enabled by setting the
@geindex PYTHON_PYMALLOC_HUGEPAGES
@geindex μεταβλητή περιβάλλοντος; PYTHON_PYMALLOC_HUGEPAGES
@ref{3db,,PYTHON_PYMALLOC_HUGEPAGES} environment variable to @code{1}.

@item 
Annotating anonymous mmap usage is now supported if Linux kernel supports
@code{PR_SET_VMA_ANON_NAME@footnote{https://manpages.debian.org/PR_SET_VMA(2const)}} (Linux 5.17 or newer).
Annotations are visible in @code{/proc/<pid>/maps} if the kernel supports the feature
and @ref{178,,-X dev} is passed to the Python or Python is built in @ref{3dc,,debug mode}.
(Contributed by Donghee Na in gh-141770@footnote{https://github.com/python/cpython/issues/141770}.)

@item 
CPython is now built with frame pointers enabled by default
(
@geindex Python Enhancement Proposals; PEP 831
PEP 831@footnote{https://peps.python.org/pep-0831/}). Pass @ref{3dd,,--without-frame-pointers} to opt out.

Authors of C extensions and native libraries built with custom build
systems should ensure the unwind chain is intact.
This is usually done by adding @code{-fno-omit-frame-pointer} and
similar flags to @code{CFLAGS}. See @ref{3dd,,--without-frame-pointers}
documentation for the specific flags Python uses.

(Contributed by Pablo Galindo Salgado and Savannah Ostrowski in gh-149201@footnote{https://github.com/python/cpython/issues/149201}.)
@end itemize
@anchor{whatsnew/3 15 whatsnew315-windows-tail-calling-interpreter}@anchor{172}

@itemize *

@item 
64-bit builds using Visual Studio 2026 (MSVC 18) may now use the new
@ref{2c4,,tail-calling interpreter}.
Results on Visual Studio 18.1.1 report between
15-20%@footnote{https://github.com/faster-cpython/ideas/blob/main/results/5800X-msvc.pgo2-vs-msvc.pgo.tc.svg}
speedup on the geometric mean of pyperformance on Windows x86-64 over
the switch-case interpreter on an AMD Ryzen 7 5800X. We have
observed speedups ranging from 14% for large pure-Python libraries
to 40% for long-running small pure-Python scripts on Windows.
This was made possible by a new feature introduced in MSVC 18,
which the official Windows 64-bit binaries on python.org@footnote{https://www.python.org/downloads/windows/} now use.
(Contributed by Chris Eibl, Ken Jin, and Brandt Bucher in gh-143068@footnote{https://github.com/python/cpython/issues/143068}.
Special thanks to Steve Dower, and the MSVC team including Hulon Jenkins.)
@end itemize

@node Porting to Python 3 15,,Build changes<2>,What’s new in Python 3 15
@anchor{whatsnew/3 15 porting-to-python-3-15}@anchor{3de}
@subsection Porting to Python 3.15


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


@itemize *

@item 
@ref{3df,,sqlite3.Connection} APIs have been cleaned up.


@itemize *

@item 
All parameters of @ref{3e0,,sqlite3.connect()} except `database' are now keyword-only.

@item 
The first three parameters of methods @ref{3e1,,create_function()}
and @ref{3e2,,create_aggregate()} are now positional-only.

@item 
The first parameter of methods @ref{3e3,,set_authorizer()},
@ref{3e4,,set_progress_handler()} and
@ref{3e5,,set_trace_callback()} is now positional-only.
@end itemize

(Contributed by Serhiy Storchaka in gh-133595@footnote{https://github.com/python/cpython/issues/133595}.)

@item 
@ref{3e6,,resource.RLIM_INFINITY} is now always positive.
Passing a negative integer value that corresponded to its old value
(such as @code{-1} or @code{-3}, depending on platform) to
@ref{3e7,,resource.setrlimit()} and @ref{3e8,,resource.prlimit()} is now deprecated.
(Contributed by Serhiy Storchaka in gh-137044@footnote{https://github.com/python/cpython/issues/137044}.)

@item 
@ref{3e9,,mmap.mmap.resize()} has been removed on platforms that don’t support the
underlying syscall, instead of raising a @ref{3ea,,SystemError}.

@item 
A resource warning is now emitted for an unclosed
@ref{3eb,,xml.etree.ElementTree.iterparse()} iterator if it opened a file.
Use its @code{close()} method or the @ref{3ec,,contextlib.closing()} context
manager to close it.
(Contributed by Osama Abdelkader and Serhiy Storchaka in gh-140601@footnote{https://github.com/python/cpython/issues/140601}.)

@item 
If a short option and a single-dash long option are passed to
@ref{3ed,,argparse.ArgumentParser.add_argument()}, `dest' is now inferred from
the single-dash long option. For example, in @code{add_argument('-f', '-foo')},
`dest' is now @code{'foo'} instead of @code{'f'}.
Pass an explicit `dest' argument to preserve the old behavior.
(Contributed by Serhiy Storchaka in gh-138697@footnote{https://github.com/python/cpython/issues/138697}.)

@item 
Padding of input no longer required in @ref{1ee,,base64.urlsafe_b64decode()}.
Pass a new argument @code{padded=True} or use @ref{1ec,,base64.b64decode()}
with argument @code{altchars=b'-_'} (this works with older Python versions)
to make padding required.
(Contributed by Serhiy Storchaka in gh-73613@footnote{https://github.com/python/cpython/issues/73613}.)

@item 
Since @ref{2a0,,unittest.TestCase.assertWarns()} and
@ref{2a1,,unittest.TestCase.assertWarnsRegex()} no longer swallow warnings that
do not match the specified category or regex, your tests may start leaking
some warnings that were previously masked.
Use warning filters to silence them or additional @code{assertWarns*()}
to catch and check them.
(Contributed by Serhiy Storchaka in gh-143231@footnote{https://github.com/python/cpython/issues/143231}.)
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s new in Python 3 14,What’s New In Python 3 13,What’s new in Python 3 15,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 14 doc}@anchor{3ee}@anchor{whatsnew/3 14 translation-repo}@anchor{3ef}@anchor{whatsnew/3 14 what-s-new-in-python-3-14}@anchor{3f0}
@section What’s new in Python 3.14


@*Editors: 
Adam Turner and Hugo van Kemenade


@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.14, compared to 3.13.
Python 3.14 was released on 7 October 2025.
For full details, see the @ref{145,,changelog}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 745
PEP 745@footnote{https://peps.python.org/pep-0745/} – Python 3.14 release schedule


@menu
* Summary – Release highlights: Summary – Release highlights<2>. 
* New features: New features<5>. 
* Other language changes: Other language changes<3>. 
* New modules: New modules<3>. 
* Improved modules: Improved modules<3>. 
* Optimizations: Optimizations<3>. 
* Removed: Removed<3>. 
* Deprecated: Deprecated<3>. 
* CPython bytecode changes:: 
* C API changes: C API changes<3>. 
* Build changes: Build changes<3>. 
* Porting to Python 3.14: Porting to Python 3 14. 
* Notable changes in 3.14.5: Notable changes in 3 14 5. 

@end menu

@node Summary – Release highlights<2>,New features<5>,,What’s new in Python 3 14
@anchor{whatsnew/3 14 summary-release-highlights}@anchor{3f1}
@subsection Summary – Release highlights


@c This section singles out the most important changes in Python 3.14.
@c Brevity is key.

Python 3.14 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 @ref{3f2,,template string literals},
@ref{3f3,,deferred evaluation of annotations},
and support for @ref{3f4,,subinterpreters} in
the standard library.

The library changes include significantly improved capabilities for
@ref{3f5,,introspection in asyncio},
@ref{3f6,,support for Zstandard} via a new
@ref{23,,compression.zstd} module, syntax highlighting in the REPL,
as well as the usual deprecations and removals,
and improvements in user-friendliness and correctness.

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{3f7,,Library Reference}
and @ref{3f8,,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{3f9,,Porting to Python 3.14} for guidance on upgrading from
earlier versions of Python.


__________________________________________________________________


@c PEP-sized items next.

Interpreter improvements:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/} and 
@geindex Python Enhancement Proposals; PEP 749
PEP 749@footnote{https://peps.python.org/pep-0749/}: @ref{3f3,,Deferred evaluation of annotations}

@item 
@geindex Python Enhancement Proposals; PEP 734
PEP 734@footnote{https://peps.python.org/pep-0734/}: @ref{3f4,,Multiple interpreters in the standard library}

@item 
@geindex Python Enhancement Proposals; PEP 750
PEP 750@footnote{https://peps.python.org/pep-0750/}: @ref{3f2,,Template strings}

@item 
@geindex Python Enhancement Proposals; PEP 758
PEP 758@footnote{https://peps.python.org/pep-0758/}: @ref{3fa,,Allow except and except* expressions without brackets}

@item 
@geindex Python Enhancement Proposals; PEP 765
PEP 765@footnote{https://peps.python.org/pep-0765/}: @ref{3fb,,Control flow in finally blocks}

@item 
@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/}: @ref{3fc,,Safe external debugger interface for CPython}

@item 
@ref{2c4,,A new type of interpreter}

@item 
@ref{3fd,,Free-threaded mode improvements}

@item 
@ref{3fe,,Improved error messages}

@item 
@ref{3ff,,Incremental garbage collection}
@end itemize

Significant improvements in the standard library:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 784
PEP 784@footnote{https://peps.python.org/pep-0784/}: @ref{3f6,,Zstandard support in the standard library}

@item 
@ref{3f5,,Asyncio introspection capabilities}

@item 
@ref{400,,Concurrent safe warnings control}

@item 
@ref{401,,Syntax highlighting in the default interactive shell}, and color output in several
standard library CLIs
@end itemize

C API improvements:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 741
PEP 741@footnote{https://peps.python.org/pep-0741/}: @ref{402,,Python configuration C API}
@end itemize

Platform support:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 776
PEP 776@footnote{https://peps.python.org/pep-0776/}: Emscripten is now an @ref{403,,officially supported platform}, at 
@geindex Python Enhancement Proposals; PEP 11#tier-3
tier 3@footnote{https://peps.python.org/pep-0011/#tier-3}.
@end itemize

Release changes:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 779
PEP 779@footnote{https://peps.python.org/pep-0779/}: @ref{404,,Free-threaded Python is officially supported}

@item 
@geindex Python Enhancement Proposals; PEP 761
PEP 761@footnote{https://peps.python.org/pep-0761/}: @ref{405,,PGP signatures have been discontinued for official releases}

@item 
@ref{406,,Windows and macOS binary releases now support the experimental just-in-time compiler}

@item 
@ref{403,,Binary releases for Android are now provided}
@end itemize

@node New features<5>,Other language changes<3>,Summary – Release highlights<2>,What’s new in Python 3 14
@anchor{whatsnew/3 14 new-features}@anchor{407}
@subsection New features


@menu
* PEP 649 & PEP 749; Deferred evaluation of annotations: PEP 649 & PEP 749 Deferred evaluation of annotations. 
* PEP 734; Multiple interpreters in the standard library: PEP 734 Multiple interpreters in the standard library. 
* PEP 750; Template string literals: PEP 750 Template string literals. 
* PEP 768; Safe external debugger interface: PEP 768 Safe external debugger interface. 
* A new type of interpreter:: 
* Free-threaded mode improvements:: 
* Improved error messages: Improved error messages<2>. 
* PEP 784; Zstandard support in the standard library: PEP 784 Zstandard support in the standard library. 
* Asyncio introspection capabilities:: 
* Concurrent safe warnings control:: 

@end menu

@node PEP 649 & PEP 749 Deferred evaluation of annotations,PEP 734 Multiple interpreters in the standard library,,New features<5>
@anchor{whatsnew/3 14 pep-649-pep-749-deferred-evaluation-of-annotations}@anchor{408}@anchor{whatsnew/3 14 whatsnew314-deferred-annotations}@anchor{3f3}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 649
`PEP 649' & 
@geindex Python Enhancement Proposals; PEP 749
`PEP 749': Deferred evaluation of annotations


The @ref{409,,annotations} on functions, classes, and modules are no
longer evaluated eagerly. Instead, annotations are stored in special-purpose
@ref{40a,,annotate functions} and evaluated only when
necessary (except if @code{from __future__ import annotations} is used).

This change is designed to improve performance and usability of annotations
in Python in most circumstances. The runtime cost for defining annotations is
minimized, but it remains possible to introspect annotations at runtime.
It is no longer necessary to enclose annotations in strings if they
contain forward references.

The new @ref{6,,annotationlib} module provides tools for inspecting deferred
annotations. Annotations may be evaluated in the @ref{40b,,VALUE}
format (which evaluates annotations to runtime values, similar to the behavior in
earlier Python versions), the @ref{40c,,FORWARDREF} format
(which replaces undefined names with special markers), and the
@ref{40d,,STRING} format (which returns annotations as strings).

This example shows how these formats behave:

@example
>>> from annotationlib import get_annotations, Format
>>> def func(arg: Undefined):
...     pass
>>> get_annotations(func, format=Format.VALUE)
Traceback (most recent call last):
  ...
NameError: name 'Undefined' is not defined
>>> get_annotations(func, format=Format.FORWARDREF)
@{'arg': ForwardRef('Undefined', owner=<function func at 0x...>)@}
>>> get_annotations(func, format=Format.STRING)
@{'arg': 'Undefined'@}
@end example

The @ref{40e,,porting} section contains guidance
on changes that may be needed due to these changes, though in the majority of
cases, code will continue working as-is.

(Contributed by Jelle Zijlstra in 
@geindex Python Enhancement Proposals; PEP 749
PEP 749@footnote{https://peps.python.org/pep-0749/} and gh-119180@footnote{https://github.com/python/cpython/issues/119180};
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/} was written by Larry Hastings.)


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 649

@item PEP 649@footnote{https://peps.python.org/pep-0649/}

Deferred Evaluation Of Annotations Using Descriptors

@geindex Python Enhancement Proposals; PEP 749

@item PEP 749@footnote{https://peps.python.org/pep-0749/}

Implementing PEP 649
@end table


@node PEP 734 Multiple interpreters in the standard library,PEP 750 Template string literals,PEP 649 & PEP 749 Deferred evaluation of annotations,New features<5>
@anchor{whatsnew/3 14 pep-734-multiple-interpreters-in-the-standard-library}@anchor{40f}@anchor{whatsnew/3 14 whatsnew314-multiple-interpreters}@anchor{3f4}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 734
`PEP 734': Multiple interpreters in the standard library


The CPython runtime supports running multiple copies of Python in the
same process simultaneously and has done so for over 20 years.
Each of these separate copies is called an “interpreter”.
However, the feature had been available only through
the @ref{410,,C-API}.

That limitation is removed in Python 3.14,
with the new @ref{25,,concurrent.interpreters} module.

There are at least two notable reasons why using multiple interpreters
has significant benefits:


@itemize *

@item 
they support a new (to Python), human-friendly concurrency model

@item 
true multi-core parallelism
@end itemize

For some use cases, concurrency in software improves efficiency and
can simplify design, at a high level.
At the same time, implementing and maintaining all but the simplest concurrency
is often a struggle for the human brain.
That especially applies to plain threads (for example, @ref{f6,,threading}),
where all memory is shared between all threads.

With multiple isolated interpreters, you can take advantage of a class
of concurrency models, like Communicating Sequential Processes (CSP)
or the actor model, that have found
success in other programming languages, like Smalltalk, Erlang,
Haskell, and Go. Think of multiple interpreters as threads
but with opt-in sharing.

Regarding multi-core parallelism: as of Python 3.12, interpreters
are now sufficiently isolated from one another to be used in parallel
(see 
@geindex Python Enhancement Proposals; PEP 684
PEP 684@footnote{https://peps.python.org/pep-0684/}). This unlocks a variety of CPU-intensive use cases
for Python that were limited by the @ref{411,,GIL}.

Using multiple interpreters is similar in many ways to
@ref{98,,multiprocessing}, in that they both provide isolated logical
«processes» that can run in parallel, with no sharing by default.
However, when using multiple interpreters, an application will use
fewer system resources and will operate more efficiently (since it
stays within the same process). Think of multiple interpreters as
having the isolation of processes with the efficiency of threads.

@c XXX Add an example or two.

@c XXX Link to the not-yet-added HOWTO doc.

While the feature has been around for decades, multiple interpreters
have not been used widely, due to low awareness and the lack of a
standard library module. Consequently, they currently have several
notable limitations, which are expected to improve significantly now
that the feature is going mainstream.

Current limitations:


@itemize *

@item 
starting each interpreter has not been optimized yet

@item 
each interpreter uses more memory than necessary
(work continues on extensive internal sharing between interpreters)

@item 
there aren’t many options `yet' for truly sharing objects or other
data between interpreters (other than @ref{1d2,,memoryview})

@item 
many third-party extension modules on PyPI are not yet compatible
with multiple interpreters
(all standard library extension modules `are' compatible)

@item 
the approach to writing applications that use multiple isolated
interpreters is mostly unfamiliar to Python users, for now
@end itemize

The impact of these limitations will depend on future CPython
improvements, how interpreters are used, and what the community solves
through PyPI packages. Depending on the use case, the limitations may
not have much impact, so try it out!

Furthermore, future CPython releases will reduce or eliminate overhead
and provide utilities that are less appropriate on PyPI. In the
meantime, most of the limitations can also be addressed through
extension modules, meaning PyPI packages can fill any gap for 3.14, and
even back to 3.12 where interpreters were finally properly isolated and
stopped sharing the @ref{411,,GIL}. Likewise, libraries on PyPI are expected
to emerge for high-level abstractions on top of interpreters.

Regarding extension modules, work is in progress to update some PyPI
projects, as well as tools like Cython, pybind11, nanobind, and PyO3.
The steps for isolating an extension module are found at
@ref{412,,Isolating Extension Modules}.
Isolating a module has a lot of overlap with what is required to support
@ref{3fd,,free-threading}, so the ongoing
work in the community in that area will help accelerate support
for multiple interpreters.

Also added in 3.14: @ref{413,,concurrent.futures.InterpreterPoolExecutor}.

(Contributed by Eric Snow in gh-134939@footnote{https://github.com/python/cpython/issues/134939}.)


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 734
PEP 734@footnote{https://peps.python.org/pep-0734/}


@node PEP 750 Template string literals,PEP 768 Safe external debugger interface,PEP 734 Multiple interpreters in the standard library,New features<5>
@anchor{whatsnew/3 14 pep-750-template-string-literals}@anchor{414}@anchor{whatsnew/3 14 whatsnew314-template-string-literals}@anchor{3f2}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 750
`PEP 750': Template string literals


Template strings are a new mechanism for custom string processing.
They share the familiar syntax of f-strings but, unlike f-strings,
return an object representing the static and interpolated parts of
the string, instead of a simple @ref{1df,,str}.

To write a t-string, use a @code{'t'} prefix instead of an @code{'f'}:

@example
>>> variety = 'Stilton'
>>> template = t'Try some @{variety@} cheese!'
>>> type(template)
<class 'string.templatelib.Template'>
@end example

@ref{415,,Template} objects provide access to the static
and interpolated (in curly braces) parts of a string `before' they are combined.
Iterate over @code{Template} instances to access their parts in order:

@c variety = 'Stilton'
@c template = t'Try some {variety} cheese!'

@example
>>> list(template)
['Try some ', Interpolation('Stilton', 'variety', None, '@w{'}), ' cheese!']
@end example

It’s easy to write (or call) code to process @code{Template} instances.
For example, here’s a function that renders static parts lowercase and
@ref{416,,Interpolation} instances uppercase:

@example
from string.templatelib import Interpolation

def lower_upper(template):
    """Render static parts lowercase and interpolations uppercase."""
    parts = []
    for part in template:
        if isinstance(part, Interpolation):
            parts.append(str(part.value).upper())
        else:
            parts.append(part.lower())
    return '@w{'}.join(parts)

name = 'Wenslydale'
template = t'Mister @{name@}'
assert lower_upper(template) == 'mister WENSLYDALE'
@end example

Because @code{Template} instances distinguish between static strings and
interpolations at runtime, they can be useful for sanitising user input.
Writing a @code{html()} function that escapes user input in HTML is an exercise
left to the reader!
Template processing code can provide improved flexibility.
For instance, a more advanced @code{html()} function could accept
a @code{dict} of HTML attributes directly in the template:

@example
attributes = @{'src': 'limburger.jpg', 'alt': 'lovely cheese'@}
template = t'<img @{attributes@}>'
assert html(template) == '<img src="limburger.jpg" alt="lovely cheese" />'
@end example

Of course, template processing code does not need to return a string-like result.
An even `more' advanced @code{html()} could return a custom type representing
a DOM-like structure.

With t-strings in place, developers can write systems that sanitise SQL,
make safe shell operations, improve logging, tackle modern ideas in web
development (HTML, CSS, and so on), and implement lightweight custom business DSLs.

(Contributed by Jim Baker, Guido van Rossum, Paul Everitt, Koudai Aono,
Lysandros Nikolaou, Dave Peck, Adam Turner, Jelle Zijlstra, Bénédikt Tran,
and Pablo Galindo Salgado in gh-132661@footnote{https://github.com/python/cpython/issues/132661}.)


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 750
PEP 750@footnote{https://peps.python.org/pep-0750/}.


@node PEP 768 Safe external debugger interface,A new type of interpreter,PEP 750 Template string literals,New features<5>
@anchor{whatsnew/3 14 pep-768-safe-external-debugger-interface}@anchor{417}@anchor{whatsnew/3 14 whatsnew314-remote-debugging}@anchor{3fc}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 768
`PEP 768': Safe external debugger interface


Python 3.14 introduces a zero-overhead debugging interface that allows
debuggers and profilers to safely attach to running Python processes
without stopping or restarting them.
This is a significant enhancement to Python’s debugging capabilities,
meaning that unsafe alternatives are no longer required.

The new interface provides safe execution points for attaching debugger code
without modifying the interpreter’s normal execution path
or adding any overhead at runtime.
Due to this, tools can now inspect and interact with Python applications
in real-time, which is a crucial capability for high-availability systems
and production environments.

For convenience, this interface is implemented in the @ref{418,,sys.remote_exec()}
function. For example:

@example
import sys
from tempfile import NamedTemporaryFile

with NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
    script_path = f.name
    f.write(f'import my_debugger; my_debugger.connect(@{os.getpid()@})')

# Execute in process with PID 1234
print('Behold! An offering:')
sys.remote_exec(1234, script_path)
@end example

This function allows sending Python code to be executed in a target process
at the next safe execution point.
However, tool authors can also implement the protocol directly as described
in the PEP, which details the underlying mechanisms used to safely attach to
running processes.

The debugging interface has been carefully designed with security in mind
and includes several mechanisms to control access:


@itemize *

@item 
A 
@geindex PYTHON_DISABLE_REMOTE_DEBUG
@geindex μεταβλητή περιβάλλοντος; PYTHON_DISABLE_REMOTE_DEBUG
@ref{419,,PYTHON_DISABLE_REMOTE_DEBUG} environment variable.

@item 
A @ref{178,,-X disable-remote-debug} command-line option.

@item 
A @ref{41a,,--without-remote-debug} configure flag to completely disable
the feature at build time.
@end itemize

(Contributed by Pablo Galindo Salgado, Matt Wozniski, and Ivona Stojanovic
in gh-131591@footnote{https://github.com/python/cpython/issues/131591}.)


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/}.


@node A new type of interpreter,Free-threaded mode improvements,PEP 768 Safe external debugger interface,New features<5>
@anchor{whatsnew/3 14 a-new-type-of-interpreter}@anchor{41b}@anchor{whatsnew/3 14 whatsnew314-tail-call-interpreter}@anchor{2c4}
@subsubsection A new type of interpreter


A new type of interpreter has been added to CPython.
It uses tail calls between small C functions that implement individual
Python opcodes, rather than one large C @code{case} statement.
For certain newer compilers, this interpreter provides
significantly better performance. Preliminary benchmarks suggest a geometric
mean of 3-5% faster on the standard @code{pyperformance} benchmark suite,
depending on platform and architecture.
The baseline is Python 3.14 built with Clang 19, without this new interpreter.

This interpreter currently only works with Clang 19 and newer
on x86-64 and AArch64 architectures.
However, a future release of GCC is expected to support this as well.

This feature is opt-in for now. Enabling profile-guided optimization is highly
recommended when using the new interpreter as it is the only configuration
that has been tested and validated for improved performance.
For further information, see @ref{41c,,--with-tail-call-interp}.

@cartouche
@quotation Σημείωση 
This is not to be confused with tail call optimization@footnote{https://en.wikipedia.org/wiki/Tail_call} of Python
functions, which is currently not implemented in CPython.

This new interpreter type is an internal implementation detail of the CPython
interpreter.  It doesn’t change the visible behavior of Python programs at
all.  It can improve their performance, but doesn’t change anything else.
@end quotation
@end cartouche

(Contributed by Ken Jin in gh-128563@footnote{https://github.com/python/cpython/issues/128563}, with ideas on how to implement this
in CPython by Mark Shannon, Garrett Gu, Haoran Xu, and Josh Haberman.)

@node Free-threaded mode improvements,Improved error messages<2>,A new type of interpreter,New features<5>
@anchor{whatsnew/3 14 free-threaded-mode-improvements}@anchor{41d}@anchor{whatsnew/3 14 whatsnew314-free-threaded-cpython}@anchor{3fd}
@subsubsection Free-threaded mode improvements


CPython’s free-threaded mode (
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}), initially added in 3.13,
has been significantly improved in Python 3.14.
The implementation described in PEP 703 has been finished, including C API
changes, and temporary workarounds in the interpreter were replaced with
more permanent solutions.
The specializing adaptive interpreter (
@geindex Python Enhancement Proposals; PEP 659
PEP 659@footnote{https://peps.python.org/pep-0659/}) is now enabled
in free-threaded mode, which along with many other optimizations
greatly improves its performance.
The performance penalty on single-threaded code in free-threaded mode
is now roughly 5-10%, depending on the platform and C compiler used.

From Python 3.14, when compiling extension modules for the free-threaded build of
CPython on Windows, the preprocessor variable @code{Py_GIL_DISABLED} now needs to
be specified by the build backend, as it will no longer be determined
automatically by the C compiler. For a running interpreter, the setting that
was used at compile time can be found using @ref{41e,,sysconfig.get_config_var()}.

The new @ref{178,,-X context_aware_warnings} flag controls if
@ref{400,,concurrent safe warnings control}
is enabled. The flag defaults to true for the free-threaded build
and false for the GIL-enabled build.

A new @ref{41f,,thread_inherit_context} flag has been added,
which if enabled means that threads created with @ref{420,,threading.Thread}
start with a copy of the @ref{421,,Context()} of the caller of
@ref{422,,start()}.  Most significantly, this makes the warning
filtering context established by @ref{423,,catch_warnings} be
«inherited» by threads (or asyncio tasks) started within that context.  It also
affects other modules that use context variables, such as the @ref{39,,decimal}
context manager.
This flag defaults to true for the free-threaded build and false for
the GIL-enabled build.

(Contributed by Sam Gross, Matt Page, Neil Schemenauer, Thomas Wouters,
Donghee Na, Kirill Podoprigora, Ken Jin, Itamar Oren, Brett Simmers,
Dino Viehland, Nathan Goldbaum, Ralf Gommers, Lysandros Nikolaou, Kumar Aditya,
Edgar Margffoy, and many others.
Some of these contributors are employed by Meta, which has continued to provide
significant engineering resources to support this project.)

@node Improved error messages<2>,PEP 784 Zstandard support in the standard library,Free-threaded mode improvements,New features<5>
@anchor{whatsnew/3 14 improved-error-messages}@anchor{424}@anchor{whatsnew/3 14 whatsnew314-improved-error-messages}@anchor{3fe}
@subsubsection Improved error messages



@itemize *

@item 
The interpreter now provides helpful suggestions when it detects typos in Python
keywords. When a word that closely resembles a Python keyword is encountered,
the interpreter will suggest the correct keyword in the error message. This
feature helps programmers quickly identify and fix common typing mistakes. For
example:

@example
>>> whille True:
...     pass
Traceback (most recent call last):
  File "<stdin>", line 1
    whille True:
    ^^^^^^
SyntaxError: invalid syntax. Did you mean 'while'?
@end example

While the feature focuses on the most common cases, some variations of
misspellings may still result in regular syntax errors.
(Contributed by Pablo Galindo in gh-132449@footnote{https://github.com/python/cpython/issues/132449}.)

@item 
@ref{425,,elif} statements that follow an @ref{320,,else} block now have
a specific error message.
(Contributed by Steele Farnsworth in gh-129902@footnote{https://github.com/python/cpython/issues/129902}.)

@example
>>> if who == "me":
...     print("It's me!")
... else:
...     print("It's not me!")
... elif who is None:
...     print("Who is it?")
File "<stdin>", line 5
  elif who is None:
  ^^^^
SyntaxError: 'elif' block follows an 'else' block
@end example

@item 
If a statement is passed to the @ref{426,,Conditional expressions} after @ref{320,,else},
or one of @ref{427,,pass}, @ref{428,,break}, or @ref{429,,continue}
is passed before @ref{322,,if}, then the
error message highlights where the @ref{42a,,expression} is
required. (Contributed by Sergey Miryanov in gh-129515@footnote{https://github.com/python/cpython/issues/129515}.)

@example
>>> x = 1 if True else pass
Traceback (most recent call last):
  File "<string>", line 1
    x = 1 if True else pass
                       ^^^^
SyntaxError: expected expression after 'else', but statement is given

>>> x = continue if True else break
Traceback (most recent call last):
  File "<string>", line 1
    x = continue if True else break
        ^^^^^^^^
SyntaxError: expected expression before 'if', but statement is given
@end example

@item 
When incorrectly closed strings are detected, the error message suggests
that the string may be intended to be part of the string.
(Contributed by Pablo Galindo in gh-88535@footnote{https://github.com/python/cpython/issues/88535}.)

@example
>>> "The interesting object "The important object" is very important"
Traceback (most recent call last):
SyntaxError: invalid syntax. Is this intended to be part of the string?
@end example

@item 
When strings have incompatible prefixes, the error now shows
which prefixes are incompatible.
(Contributed by Nikita Sobolev in gh-133197@footnote{https://github.com/python/cpython/issues/133197}.)

@example
>>> ub'abc'
  File "<python-input-0>", line 1
    ub'abc'
    ^^
SyntaxError: 'u' and 'b' prefixes are incompatible
@end example

@item 
Improved error messages when using @code{as} with incompatible targets in:


@itemize -

@item 
Imports: @code{import ... as ...}

@item 
From imports: @code{from ... import ... as ...}

@item 
Except handlers: @code{except ... as ...}

@item 
Pattern-match cases: @code{case ... as ...}
@end itemize

(Contributed by Nikita Sobolev in gh-123539@footnote{https://github.com/python/cpython/issues/123539}, gh-123562@footnote{https://github.com/python/cpython/issues/123562}, and gh-123440@footnote{https://github.com/python/cpython/issues/123440}.)

@item 
Improved error message when trying to add an instance of an unhashable type to
a @ref{188,,dict} or @ref{42b,,set}.
(Contributed by CF Bolz-Tereick and Victor Stinner in gh-132828@footnote{https://github.com/python/cpython/issues/132828}.)

@example
>>> s = set()
>>> s.add(@{'pages': 12, 'grade': 'A'@})
Traceback (most recent call last):
  File "<python-input-1>", line 1, in <module>
    s.add(@{'pages': 12, 'grade': 'A'@})
    ~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: cannot use 'dict' as a set element (unhashable type: 'dict')
>>> d = @{@}
>>> l = [1, 2, 3]
>>> d[l] = 12
Traceback (most recent call last):
  File "<python-input-4>", line 1, in <module>
    d[l] = 12
    ~^^^
TypeError: cannot use 'list' as a dict key (unhashable type: 'list')
@end example

@item 
Improved error message when an object supporting the synchronous
context manager protocol is entered using @ref{20b,,async with}
instead of @ref{20a,,with},
and vice versa for the asynchronous context manager protocol.
(Contributed by Bénédikt Tran in gh-128398@footnote{https://github.com/python/cpython/issues/128398}.)
@end itemize

@node PEP 784 Zstandard support in the standard library,Asyncio introspection capabilities,Improved error messages<2>,New features<5>
@anchor{whatsnew/3 14 pep-784-zstandard-support-in-the-standard-library}@anchor{42c}@anchor{whatsnew/3 14 whatsnew314-zstandard}@anchor{3f6}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 784
`PEP 784': Zstandard support in the standard library


The new @code{compression} package contains modules @code{compression.lzma},
@code{compression.bz2}, @code{compression.gzip} and @code{compression.zlib}
which re-export the @ref{8d,,lzma}, @ref{14,,bz2}, @ref{6a,,gzip} and @ref{13c,,zlib}
modules respectively. The new import names under @code{compression} are the
preferred names for importing these compression modules from Python 3.14. However,
the existing modules names have not been deprecated. Any deprecation or removal
of the existing compression modules will occur no sooner than five years after
the release of 3.14.

The new @code{compression.zstd} module provides compression and decompression
APIs for the Zstandard format via bindings to Meta's zstd library@footnote{https://facebook.github.io/zstd/}. Zstandard is a widely adopted, highly
efficient, and fast compression format. In addition to the APIs introduced in
@code{compression.zstd}, support for reading and writing Zstandard compressed
archives has been added to the @ref{e7,,tarfile}, @ref{13a,,zipfile}, and
@ref{cd,,shutil} modules.

Here’s an example of using the new module to compress some data:

@example
from compression import zstd
import math

data = str(math.pi).encode() * 20
compressed = zstd.compress(data)
ratio = len(compressed) / len(data)
print(f"Achieved compression ratio of @{ratio@}")
@end example

As can be seen, the API is similar to the APIs of the @code{lzma} and
@code{bz2} modules.

(Contributed by Emma Harper Smith, Adam Turner, Gregory P. Smith, Tomas Roun,
Victor Stinner, and Rogdham in gh-132983@footnote{https://github.com/python/cpython/issues/132983}.)


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 784
PEP 784@footnote{https://peps.python.org/pep-0784/}.


@node Asyncio introspection capabilities,Concurrent safe warnings control,PEP 784 Zstandard support in the standard library,New features<5>
@anchor{whatsnew/3 14 asyncio-introspection-capabilities}@anchor{42d}@anchor{whatsnew/3 14 whatsnew314-asyncio-introspection}@anchor{3f5}
@subsubsection Asyncio introspection capabilities


Added a new command-line interface to inspect running Python processes
using asynchronous tasks, available via @code{python -m asyncio ps PID}
or @code{python -m asyncio pstree PID}.

The @code{ps} subcommand inspects the given process ID (PID) and displays
information about currently running asyncio tasks.
It outputs a task table: a flat listing of all tasks, their names,
their coroutine stacks, and which tasks are awaiting them.

The @code{pstree} subcommand fetches the same information, but instead renders a
visual async call tree, showing coroutine relationships in a hierarchical format.
This command is particularly useful for debugging long-running or stuck
asynchronous programs.
It can help developers quickly identify where a program is blocked,
what tasks are pending, and how coroutines are chained together.

For example given this code:

@example
import asyncio

async def play_track(track):
    await asyncio.sleep(5)
    print(f'🎵 Finished: @{track@}')

async def play_album(name, tracks):
    async with asyncio.TaskGroup() as tg:
        for track in tracks:
            tg.create_task(play_track(track), name=track)

async def main():
    async with asyncio.TaskGroup() as tg:
        tg.create_task(
          play_album('Sundowning', ['TNDNBTG', 'Levitate']),
          name='Sundowning')
        tg.create_task(
          play_album('TMBTE', ['DYWTYLM', 'Aqua Regia']),
          name='TMBTE')

if __name__ == '__main__':
    asyncio.run(main())
@end example

Executing the new tool on the running process will yield a table like this:

@example
python -m asyncio ps 12345

tid        task id              task name            coroutine stack                                    awaiter chain                                      awaiter name    awaiter id
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1935500    0x7fc930c18050       Task-1               TaskGroup._aexit -> TaskGroup.__aexit__ -> main                                                                       0x0
1935500    0x7fc930c18230       Sundowning           TaskGroup._aexit -> TaskGroup.__aexit__ -> album   TaskGroup._aexit -> TaskGroup.__aexit__ -> main    Task-1          0x7fc930c18050
1935500    0x7fc93173fa50       TMBTE                TaskGroup._aexit -> TaskGroup.__aexit__ -> album   TaskGroup._aexit -> TaskGroup.__aexit__ -> main    Task-1          0x7fc930c18050
1935500    0x7fc93173fdf0       TNDNBTG              sleep -> play                                      TaskGroup._aexit -> TaskGroup.__aexit__ -> album   Sundowning      0x7fc930c18230
1935500    0x7fc930d32510       Levitate             sleep -> play                                      TaskGroup._aexit -> TaskGroup.__aexit__ -> album   Sundowning      0x7fc930c18230
1935500    0x7fc930d32890       DYWTYLM              sleep -> play                                      TaskGroup._aexit -> TaskGroup.__aexit__ -> album   TMBTE           0x7fc93173fa50
1935500    0x7fc93161ec30       Aqua Regia           sleep -> play                                      TaskGroup._aexit -> TaskGroup.__aexit__ -> album   TMBTE           0x7fc93173fa50
@end example

or a tree like this:

@example
python -m asyncio pstree 12345

└── (T) Task-1
    └──  main example.py:13
        └──  TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:72
            └──  TaskGroup._aexit Lib/asyncio/taskgroups.py:121
                ├── (T) Sundowning
                │   └──  album example.py:8
                │       └──  TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:72
                │           └──  TaskGroup._aexit Lib/asyncio/taskgroups.py:121
                │               ├── (T) TNDNBTG
                │               │   └──  play example.py:4
                │               │       └──  sleep Lib/asyncio/tasks.py:702
                │               └── (T) Levitate
                │                   └──  play example.py:4
                │                       └──  sleep Lib/asyncio/tasks.py:702
                └── (T) TMBTE
                    └──  album example.py:8
                        └──  TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:72
                            └──  TaskGroup._aexit Lib/asyncio/taskgroups.py:121
                                ├── (T) DYWTYLM
                                │   └──  play example.py:4
                                │       └──  sleep Lib/asyncio/tasks.py:702
                                └── (T) Aqua Regia
                                    └──  play example.py:4
                                        └──  sleep Lib/asyncio/tasks.py:702
@end example

If a cycle is detected in the async await graph (which could indicate a
programming issue), the tool raises an error and lists the cycle paths that
prevent tree construction:

@example
python -m asyncio pstree 12345

ERROR: await-graph contains cycles - cannot print a tree!

cycle: Task-2 → Task-3 → Task-2
@end example

(Contributed by Pablo Galindo, Łukasz Langa, Yury Selivanov, and Marta
Gomez Macias in gh-91048@footnote{https://github.com/python/cpython/issues/91048}.)

@node Concurrent safe warnings control,,Asyncio introspection capabilities,New features<5>
@anchor{whatsnew/3 14 concurrent-safe-warnings-control}@anchor{42e}@anchor{whatsnew/3 14 whatsnew314-concurrent-warnings-control}@anchor{400}
@subsubsection Concurrent safe warnings control


The @ref{423,,warnings.catch_warnings} context manager will now optionally
use a context variable for warning filters. This is enabled by setting
the @ref{42f,,context_aware_warnings} flag, either with the @code{-X}
command-line option or an environment variable. This gives predictable
warnings control when using @code{catch_warnings} combined with
multiple threads or asynchronous tasks. The flag defaults to true for the
free-threaded build and false for the GIL-enabled build.

(Contributed by Neil Schemenauer and Kumar Aditya in gh-130010@footnote{https://github.com/python/cpython/issues/130010}.)

@node Other language changes<3>,New modules<3>,New features<5>,What’s new in Python 3 14
@anchor{whatsnew/3 14 other-language-changes}@anchor{430}
@subsection Other language changes



@itemize *

@item 
All Windows code pages are now supported as “cpXXX” codecs on Windows.
(Contributed by Serhiy Storchaka in gh-123803@footnote{https://github.com/python/cpython/issues/123803}.)

@item 
Implement mixed-mode arithmetic rules combining real and complex numbers
as specified by the C standard since C99.
(Contributed by Sergey B Kirpichev in gh-69639@footnote{https://github.com/python/cpython/issues/69639}.)

@item 
More syntax errors are now detected regardless of optimisation and
the @ref{431,,-O} command-line option.
This includes writes to @code{__debug__}, incorrect use of @ref{432,,await},
and asynchronous comprehensions outside asynchronous functions.
For example, @code{python -O -c 'assert (__debug__ := 1)'}
or @code{python -O -c 'assert await 1'} now produce @ref{17e,,SyntaxError}s.
(Contributed by Irit Katriel and Jelle Zijlstra in gh-122245@footnote{https://github.com/python/cpython/issues/122245} & gh-121637@footnote{https://github.com/python/cpython/issues/121637}.)

@item 
When subclassing a pure C type, the C slots for the new type
are no longer replaced with a wrapped version on class creation
if they are not explicitly overridden in the subclass.
(Contributed by Tomasz Pytel in gh-132284@footnote{https://github.com/python/cpython/issues/132284}.)
@end itemize

@menu
* Built-ins:: 
* Command line and environment:: 
* PEP 758; Allow except and except* expressions without brackets: PEP 758 Allow except and except* expressions without brackets. 
* PEP 765; Control flow in finally blocks: PEP 765 Control flow in finally blocks. 
* Garbage collection:: 
* Default interactive shell: Default interactive shell<2>. 

@end menu

@node Built-ins,Command line and environment,,Other language changes<3>
@anchor{whatsnew/3 14 built-ins}@anchor{433}
@subsubsection Built-ins



@itemize *

@item 
The @ref{434,,bytes.fromhex()} and @ref{435,,bytearray.fromhex()} methods now accept
ASCII @ref{1c7,,bytes} and @ref{436,,bytes-like objects}.
(Contributed by Daniel Pope in gh-129349@footnote{https://github.com/python/cpython/issues/129349}.)

@item 
Add class methods @ref{437,,float.from_number()} and @ref{438,,complex.from_number()}
to convert a number to @ref{327,,float} or @ref{328,,complex} type correspondingly.
They raise a @ref{291,,TypeError} if the argument is not a real number.
(Contributed by Serhiy Storchaka in gh-84978@footnote{https://github.com/python/cpython/issues/84978}.)

@item 
Support underscore and comma as thousands separators in the fractional part
for floating-point presentation types of the new-style string formatting
(with @ref{439,,format()} or @ref{43a,,f-strings}).
(Contributed by Sergey B Kirpichev in gh-87790@footnote{https://github.com/python/cpython/issues/87790}.)

@item 
The @ref{326,,int()} function no longer delegates to @ref{43b,,__trunc__()}.
Classes that want to support conversion to @code{int()} must implement
either @ref{43c,,__int__()} or @ref{43d,,__index__()}.
(Contributed by Mark Dickinson in gh-119743@footnote{https://github.com/python/cpython/issues/119743}.)

@item 
The @ref{43e,,map()} function now has an optional keyword-only `strict' flag
like @ref{43f,,zip()} to check that all the iterables are of equal length.
(Contributed by Wannes Boeykens in gh-119793@footnote{https://github.com/python/cpython/issues/119793}.)

@item 
The @ref{1d2,,memoryview} type now supports subscription,
making it a @ref{1d1,,generic type}.
(Contributed by Brian Schubert in gh-126012@footnote{https://github.com/python/cpython/issues/126012}.)

@item 
Using @ref{440,,NotImplemented} in a boolean context
will now raise a @ref{291,,TypeError}.
This has raised a @ref{2c9,,DeprecationWarning} since Python 3.9.
(Contributed by Jelle Zijlstra in gh-118767@footnote{https://github.com/python/cpython/issues/118767}.)

@item 
Three-argument @ref{441,,pow()} now tries calling @ref{442,,__rpow__()}
if necessary.
Previously it was only called in two-argument @code{pow()}
and the binary power operator.
(Contributed by Serhiy Storchaka in gh-130104@footnote{https://github.com/python/cpython/issues/130104}.)

@item 
@ref{443,,super} objects are now @ref{29,,copyable} and @ref{ab,,pickleable}.
(Contributed by Serhiy Storchaka in gh-125767@footnote{https://github.com/python/cpython/issues/125767}.)
@end itemize

@node Command line and environment,PEP 758 Allow except and except* expressions without brackets,Built-ins,Other language changes<3>
@anchor{whatsnew/3 14 command-line-and-environment}@anchor{444}
@subsubsection Command line and environment



@itemize *

@item 
The import time flag can now track modules that are already loaded (“cached”),
via the new @ref{178,,-X importtime=2}.
When such a module is imported, the @code{self} and @code{cumulative} times
are replaced by the string @code{cached}.

Values above @code{2} for @code{-X importtime} are now reserved for future use.

(Contributed by Noah Kim and Adam Turner in gh-118655@footnote{https://github.com/python/cpython/issues/118655}.)

@item 
The command-line option @ref{445,,-c} now automatically dedents its code
argument before execution.
(Contributed by Jon Crall and Steven Sun in gh-103998@footnote{https://github.com/python/cpython/issues/103998}.)

@item 
@code{-J} is no longer a reserved flag for Jython@footnote{https://www.jython.org/},
and now has no special meaning.
(Contributed by Adam Turner in gh-133336@footnote{https://github.com/python/cpython/issues/133336}.)
@end itemize

@node PEP 758 Allow except and except* expressions without brackets,PEP 765 Control flow in finally blocks,Command line and environment,Other language changes<3>
@anchor{whatsnew/3 14 pep-758-allow-except-and-except-expressions-without-brackets}@anchor{446}@anchor{whatsnew/3 14 whatsnew314-bracketless-except}@anchor{3fa}
@subsubsection PEP 758: Allow @code{except} and @code{except*} expressions without brackets


The @ref{447,,except} and @ref{448,,except*} expressions
now allow brackets to be omitted when there are multiple exception types
and the @code{as} clause is not used.
For example:

@example
try:
    connect_to_server()
except TimeoutError, ConnectionRefusedError:
    print('The network has ceased to be!')
@end example

(Contributed by Pablo Galindo and Brett Cannon in 
@geindex Python Enhancement Proposals; PEP 758
PEP 758@footnote{https://peps.python.org/pep-0758/} and gh-131831@footnote{https://github.com/python/cpython/issues/131831}.)

@node PEP 765 Control flow in finally blocks,Garbage collection,PEP 758 Allow except and except* expressions without brackets,Other language changes<3>
@anchor{whatsnew/3 14 pep-765-control-flow-in-finally-blocks}@anchor{449}@anchor{whatsnew/3 14 whatsnew314-finally-syntaxwarning}@anchor{3fb}
@subsubsection PEP 765: Control flow in @code{finally} blocks


The compiler now emits a @ref{44a,,SyntaxWarning} when a @ref{44b,,return},
@ref{428,,break}, or @ref{429,,continue} statement have the effect of
leaving a @ref{44c,,finally} block.
This change is specified in 
@geindex Python Enhancement Proposals; PEP 765
PEP 765@footnote{https://peps.python.org/pep-0765/}.

In situations where this change is inconvenient (such as those where the
warnings are redundant due to code linting), the @ref{1cc,,warning filter} can be used to turn off all syntax warnings by adding
@code{ignore::SyntaxWarning} as a filter. This can be specified in combination
with a filter that converts other warnings to errors (for example, passing
@code{-Werror -Wignore::SyntaxWarning} as CLI options, or setting
@code{PYTHONWARNINGS=error,ignore::SyntaxWarning}).

Note that applying such a filter at runtime using the @ref{11b,,warnings} module
will only suppress the warning in code that is compiled `after' the filter is
adjusted. Code that is compiled prior to the filter adjustment (for example,
when a module is imported) will still emit the syntax warning.

(Contributed by Irit Katriel in gh-130080@footnote{https://github.com/python/cpython/issues/130080}.)
@anchor{whatsnew/3 14 incremental-garbage-collection}@anchor{44d}
@node Garbage collection,Default interactive shell<2>,PEP 765 Control flow in finally blocks,Other language changes<3>
@anchor{whatsnew/3 14 garbage-collection}@anchor{44e}@anchor{whatsnew/3 14 whatsnew314-incremental-gc}@anchor{3ff}
@subsubsection Garbage collection


`From Python 3.14.5 onwards:'

The garbage collector (GC) has changed in Python 3.14.5.

Python 3.14.0-3.14.4 shipped with a new incremental GC.
However, due to a number of reports@footnote{https://github.com/python/cpython/issues/142516}
of significant memory pressure in production environments,
it has been reverted back to the generational GC from 3.13.
This is the GC now used in Python 3.14.5 and later.

`Previously in Python 3.14.0-3.14.4:'

The cycle garbage collector is now incremental.
This means that maximum pause times are reduced
by an order of magnitude or more for larger heaps.

There are now only two generations: young and old.
When @ref{44f,,gc.collect()} is not called directly, the
GC is invoked a little less frequently. When invoked, it
collects the young generation and an increment of the
old generation, instead of collecting one or more generations.

The behavior of @code{gc.collect()} changes slightly:


@itemize *

@item 
@code{gc.collect(1)}: Performs an increment of garbage collection,
rather than collecting generation 1.

@item 
Other calls to @code{gc.collect()} are unchanged.
@end itemize

(Contributed by Mark Shannon in gh-108362@footnote{https://github.com/python/cpython/issues/108362}.)

@node Default interactive shell<2>,,Garbage collection,Other language changes<3>
@anchor{whatsnew/3 14 default-interactive-shell}@anchor{450}
@subsubsection Default interactive shell

@anchor{whatsnew/3 14 whatsnew314-pyrepl-highlighting}@anchor{401}

@itemize *

@item 
The default @ref{451,,interactive} shell now highlights Python syntax.
The feature is enabled by default, save if 
@geindex PYTHON_BASIC_REPL
@geindex μεταβλητή περιβάλλοντος; PYTHON_BASIC_REPL
@ref{452,,PYTHON_BASIC_REPL}
or any other environment variable that disables colour is set.
See @ref{1af,,Controlling color} for details.

The default color theme for syntax highlighting strives for good contrast
and exclusively uses the 4-bit VGA standard ANSI color codes for maximum
compatibility. The theme can be customized using an experimental API
@code{_colorize.set_theme()}.
This can be called interactively or in the 
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP} script.
Note that this function has no stability guarantees,
and may change or be removed.

(Contributed by Łukasz Langa in gh-131507@footnote{https://github.com/python/cpython/issues/131507}.)

@item 
The default @ref{451,,interactive} shell now supports import auto-completion.
This means that typing @code{import co} and pressing @code{<Tab>} will suggest
modules starting with @code{co}. Similarly, typing @code{from concurrent import i}
will suggest submodules of @code{concurrent} starting with @code{i}.
Note that autocompletion of module attributes is not currently supported.
(Contributed by Tomas Roun in gh-69605@footnote{https://github.com/python/cpython/issues/69605}.)
@end itemize

@node New modules<3>,Improved modules<3>,Other language changes<3>,What’s new in Python 3 14
@anchor{whatsnew/3 14 new-modules}@anchor{454}
@subsection New modules



@itemize *

@item 
@ref{6,,annotationlib}:
For introspecting @ref{409,,annotations}.
See @ref{3f3,,PEP 749} for more details.
(Contributed by Jelle Zijlstra in gh-119180@footnote{https://github.com/python/cpython/issues/119180}.)

@item 
@ref{22,,compression} (including @ref{23,,compression.zstd}):
A package for compression-related modules,
including a new module to support the Zstandard compression format.
See @ref{3f6,,PEP 784} for more details.
(Contributed by Emma Harper Smith, Adam Turner, Gregory P. Smith, Tomas Roun,
Victor Stinner, and Rogdham in gh-132983@footnote{https://github.com/python/cpython/issues/132983}.)

@item 
@ref{25,,concurrent.interpreters}:
Support for multiple interpreters in the standard library.
See @ref{3f4,,PEP 734} for more details.
(Contributed by Eric Snow in gh-134939@footnote{https://github.com/python/cpython/issues/134939}.)

@item 
@ref{dc,,string.templatelib}:
Support for template string literals (t-strings).
See @ref{3f2,,PEP 750} for more details.
(Contributed by Jim Baker, Guido van Rossum, Paul Everitt, Koudai Aono,
Lysandros Nikolaou, Dave Peck, Adam Turner, Jelle Zijlstra, Bénédikt Tran,
and Pablo Galindo Salgado in gh-132661@footnote{https://github.com/python/cpython/issues/132661}.)
@end itemize

@node Improved modules<3>,Optimizations<3>,New modules<3>,What’s new in Python 3 14
@anchor{whatsnew/3 14 improved-modules}@anchor{455}
@subsection Improved modules


@menu
* argparse: argparse<2>. 
* ast: ast<3>. 
* asyncio: asyncio<2>. 
* calendar: calendar<2>. 
* concurrent.futures: concurrent futures<2>. 
* configparser:: 
* contextvars:: 
* ctypes: ctypes<2>. 
* curses:: 
* datetime: datetime<2>. 
* decimal:: 
* difflib: difflib<2>. 
* dis:: 
* errno:: 
* faulthandler: faulthandler<2>. 
* fnmatch:: 
* fractions:: 
* functools: functools<3>. 
* getopt:: 
* getpass:: 
* graphlib:: 
* heapq:: 
* hmac:: 
* http:: 
* imaplib:: 
* inspect: inspect<2>. 
* io:: 
* json: json<2>. 
* linecache:: 
* logging.handlers: logging handlers. 
* math: math<2>. 
* mimetypes: mimetypes<2>. 
* multiprocessing:: 
* operator:: 
* os: os<2>. 
* os.path: os path<2>. 
* pathlib: pathlib<2>. 
* pdb: pdb<2>. 
* pickle: pickle<2>. 
* platform: platform<2>. 
* pydoc:: 
* re: re<2>. 
* socket: socket<2>. 
* ssl: ssl<2>. 
* struct:: 
* symtable: symtable<3>. 
* sys: sys<2>. 
* sys.monitoring: sys monitoring<2>. 
* sysconfig: sysconfig<3>. 
* tarfile: tarfile<2>. 
* threading: threading<3>. 
* tkinter: tkinter<2>. 
* turtle:: 
* types: types<3>. 
* typing: typing<3>. 
* unicodedata: unicodedata<2>. 
* unittest: unittest<2>. 
* urllib:: 
* uuid:: 
* webbrowser: webbrowser<2>. 
* zipfile:: 

@end menu

@node argparse<2>,ast<3>,,Improved modules<3>
@anchor{whatsnew/3 14 argparse}@anchor{456}
@subsubsection argparse



@itemize *

@item 
The default value of the @ref{457,,program name} for
@ref{1dc,,argparse.ArgumentParser} now reflects the way the Python
interpreter was instructed to find the @code{__main__} module code.
(Contributed by Serhiy Storchaka and Alyssa Coghlan in gh-66436@footnote{https://github.com/python/cpython/issues/66436}.)

@item 
Introduced the optional `suggest_on_error' parameter to
@ref{1dc,,argparse.ArgumentParser}, enabling suggestions for argument choices
and subparser names if mistyped by the user.
(Contributed by Savannah Ostrowski in gh-124456@footnote{https://github.com/python/cpython/issues/124456}.)

@item 
Enable color for help text, which can be disabled with the optional `color'
parameter to @ref{1dc,,argparse.ArgumentParser}.
This can also be controlled by @ref{1af,,environment variables}.
(Contributed by Hugo van Kemenade in gh-130645@footnote{https://github.com/python/cpython/issues/130645}.)
@end itemize

@node ast<3>,asyncio<2>,argparse<2>,Improved modules<3>
@anchor{whatsnew/3 14 ast}@anchor{458}
@subsubsection ast



@itemize *

@item 
Add @ref{459,,compare()}, a function for comparing two ASTs.
(Contributed by Batuhan Taskaya and Jeremy Hylton in gh-60191@footnote{https://github.com/python/cpython/issues/60191}.)

@item 
Add support for @ref{45a,,copy.replace()} for AST nodes.
(Contributed by Bénédikt Tran in gh-121141@footnote{https://github.com/python/cpython/issues/121141}.)

@item 
Docstrings are now removed from an optimized AST in optimization level 2.
(Contributed by Irit Katriel in gh-123958@footnote{https://github.com/python/cpython/issues/123958}.)

@item 
The @ref{45b,,repr()} output for AST nodes now includes more information.
(Contributed by Tomas Roun in gh-116022@footnote{https://github.com/python/cpython/issues/116022}.)

@item 
When called with an AST as input, the @ref{1c9,,parse()} function
now always verifies that the root node type is appropriate.
(Contributed by Irit Katriel in gh-130139@footnote{https://github.com/python/cpython/issues/130139}.)

@item 
Add new options to the command-line interface:
@ref{45c,,--feature-version},
@ref{45d,,--optimize}, and
@ref{45e,,--show-empty}.
(Contributed by Semyon Moroz in gh-133367@footnote{https://github.com/python/cpython/issues/133367}.)
@end itemize

@node asyncio<2>,calendar<2>,ast<3>,Improved modules<3>
@anchor{whatsnew/3 14 asyncio}@anchor{45f}
@subsubsection asyncio



@itemize *

@item 
The function and methods named @code{create_task()} now take an arbitrary
list of keyword arguments. All keyword arguments are passed to the
@ref{460,,Task} constructor or the custom task factory.
(See @ref{461,,set_task_factory()} for details.)
The @code{name} and @code{context} keyword arguments are no longer special;
the name should now be set using the @code{name} keyword argument of the factory,
and @code{context} may be @code{None}.

This affects the following function and methods:
@ref{462,,asyncio.create_task()},
@ref{463,,asyncio.loop.create_task()},
@ref{464,,asyncio.TaskGroup.create_task()}.

(Contributed by Thomas Grainger in gh-128307@footnote{https://github.com/python/cpython/issues/128307}.)

@item 
There are two new utility functions for
introspecting and printing a program’s call graph:
@ref{465,,capture_call_graph()} and @ref{466,,print_call_graph()}.
See @ref{3f5,,Asyncio introspection capabilities} for more details.
(Contributed by Yury Selivanov, Pablo Galindo Salgado, and Łukasz Langa
in gh-91048@footnote{https://github.com/python/cpython/issues/91048}.)
@end itemize

@node calendar<2>,concurrent futures<2>,asyncio<2>,Improved modules<3>
@anchor{whatsnew/3 14 calendar}@anchor{467}
@subsubsection calendar

@anchor{whatsnew/3 14 whatsnew314-color-calendar}@anchor{468}

@itemize *

@item 
By default, today’s date is highlighted in color in @ref{15,,calendar}’s
@ref{201,,command-line} text output.
This can be controlled by @ref{1af,,environment variables}.
(Contributed by Hugo van Kemenade in gh-128317@footnote{https://github.com/python/cpython/issues/128317}.)
@end itemize

@node concurrent futures<2>,configparser,calendar<2>,Improved modules<3>
@anchor{whatsnew/3 14 concurrent-futures}@anchor{469}
@subsubsection concurrent.futures

@anchor{whatsnew/3 14 whatsnew314-concurrent-futures-interp-pool}@anchor{413}

@itemize *

@item 
Add a new executor class, @ref{46a,,InterpreterPoolExecutor},
which exposes multiple Python interpreters in the same process
(“subinterpreters”) to Python code.
This uses a pool of independent Python interpreters to execute calls
asynchronously.

This is separate from the new @ref{25,,interpreters} module
introduced by @ref{3f4,,PEP 734}.
(Contributed by Eric Snow in gh-124548@footnote{https://github.com/python/cpython/issues/124548}.)
@end itemize
@anchor{whatsnew/3 14 whatsnew314-concurrent-futures-start-method}@anchor{46b}

@itemize *

@item 
On Unix platforms other than macOS, @ref{46c,,“forkserver”} is now the default @ref{46d,,start method} for
@ref{206,,ProcessPoolExecutor}
(replacing @ref{46e,,“fork”}).
This change does not affect Windows or macOS, where @ref{46f,,“spawn”} remains the default start method.

If the threading incompatible `fork' method is required, you must explicitly
request it by supplying a multiprocessing context `mp_context' to
@ref{206,,ProcessPoolExecutor}.

See @ref{470,,forkserver restrictions}
for information and differences with the `fork' method and how this change
may affect existing code with mutable global shared variables and/or shared
objects that can not be automatically @ref{ab,,pickled}.

(Contributed by Gregory P. Smith in gh-84559@footnote{https://github.com/python/cpython/issues/84559}.)

@item 
Add two new methods to @ref{206,,ProcessPoolExecutor},
@ref{471,,terminate_workers()}
and @ref{472,,kill_workers()},
as ways to terminate or kill all living worker processes in the given pool.
(Contributed by Charles Machalow in gh-130849@footnote{https://github.com/python/cpython/issues/130849}.)

@item 
Add the optional `buffersize' parameter to @ref{473,,Executor.map} to limit the number of submitted
tasks whose results have not yet been yielded. If the buffer is full,
iteration over the `iterables' pauses until a result is yielded from the
buffer.
(Contributed by Enzo Bonnal and Josh Rosenberg in gh-74028@footnote{https://github.com/python/cpython/issues/74028}.)
@end itemize

@node configparser,contextvars,concurrent futures<2>,Improved modules<3>
@anchor{whatsnew/3 14 configparser}@anchor{474}
@subsubsection configparser



@itemize *

@item 
@code{configparser} will no longer write config files it cannot read,
to improve security.
Attempting to @ref{475,,write()} keys containing
delimiters or beginning with the section header pattern will raise an
@ref{476,,InvalidWriteError}.
(Contributed by Jacob Lincoln in gh-129270@footnote{https://github.com/python/cpython/issues/129270}.)
@end itemize

@node contextvars,ctypes<2>,configparser,Improved modules<3>
@anchor{whatsnew/3 14 contextvars}@anchor{477}
@subsubsection contextvars



@itemize *

@item 
Support the @ref{478,,context manager} protocol
for @ref{479,,Token} objects.
(Contributed by Andrew Svetlov in gh-129889@footnote{https://github.com/python/cpython/issues/129889}.)
@end itemize

@node ctypes<2>,curses,contextvars,Improved modules<3>
@anchor{whatsnew/3 14 ctypes}@anchor{47a}
@subsubsection ctypes



@itemize *

@item 
The layout of @ref{47b,,bit fields}
in @ref{47c,,Structure} and @ref{47d,,Union} objects
is now a closer match to platform defaults (GCC/Clang or MSVC).
In particular, fields no longer overlap.
(Contributed by Matthias Görgens in gh-97702@footnote{https://github.com/python/cpython/issues/97702}.)

@item 
The @ref{319,,Structure._layout_} class attribute can now be set
to help match a non-default ABI.
(Contributed by Petr Viktorin in gh-97702@footnote{https://github.com/python/cpython/issues/97702}.)

@item 
The class of @ref{47c,,Structure}/@ref{47d,,Union}
field descriptors is now available as @ref{47e,,CField},
and has new attributes to aid debugging and introspection.
(Contributed by Petr Viktorin in gh-128715@footnote{https://github.com/python/cpython/issues/128715}.)

@item 
On Windows, the @ref{47f,,COMError} exception is now public.
(Contributed by Jun Komoda in gh-126686@footnote{https://github.com/python/cpython/issues/126686}.)

@item 
On Windows, the @ref{480,,CopyComPointer()} function is now public.
(Contributed by Jun Komoda in gh-127275@footnote{https://github.com/python/cpython/issues/127275}.)

@item 
Add @ref{481,,memoryview_at()}, a function to create a
@ref{1d2,,memoryview} object that refers to the supplied pointer and
length. This works like @ref{482,,ctypes.string_at()} except it avoids a
buffer copy, and is typically useful when implementing pure Python
callback functions that are passed dynamically-sized buffers.
(Contributed by Rian Hunter in gh-112018@footnote{https://github.com/python/cpython/issues/112018}.)

@item 
Complex types, @ref{2ce,,c_float_complex},
@ref{2cf,,c_double_complex}, and @ref{2d0,,c_longdouble_complex},
are now available if both the compiler and the @code{libffi} library support
complex C types.
(Contributed by Sergey B Kirpichev in gh-61103@footnote{https://github.com/python/cpython/issues/61103}.)

@item 
Add @ref{483,,ctypes.util.dllist()} for listing the shared libraries
loaded by the current process.
(Contributed by Brian Ward in gh-119349@footnote{https://github.com/python/cpython/issues/119349}.)

@item 
Move @ref{484,,ctypes.POINTER()} types cache from a global internal cache
(@code{_pointer_type_cache}) to the @ref{485,,_CData.__pointer_type__} attribute of the corresponding
@code{ctypes} types.
This will stop the cache from growing without limits in some situations.
(Contributed by Sergey Miryanov in gh-100926@footnote{https://github.com/python/cpython/issues/100926}.)

@item 
The @ref{486,,py_object} type now supports subscription,
making it a @ref{1d1,,generic type}.
(Contributed by Brian Schubert in gh-132168@footnote{https://github.com/python/cpython/issues/132168}.)

@item 
@code{ctypes} now supports @ref{487,,free-threading builds}.
(Contributed by Kumar Aditya and Peter Bierma in gh-127945@footnote{https://github.com/python/cpython/issues/127945}.)
@end itemize

@node curses,datetime<2>,ctypes<2>,Improved modules<3>
@anchor{whatsnew/3 14 curses}@anchor{488}
@subsubsection curses



@itemize *

@item 
Add the @ref{489,,assume_default_colors()} function,
a refinement of the @ref{48a,,use_default_colors()} function which
allows changing the color pair @code{0}.
(Contributed by Serhiy Storchaka in gh-133139@footnote{https://github.com/python/cpython/issues/133139}.)
@end itemize

@node datetime<2>,decimal,curses,Improved modules<3>
@anchor{whatsnew/3 14 datetime}@anchor{48b}
@subsubsection datetime



@itemize *

@item 
Add the @ref{48c,,strptime()} method to the
@ref{48d,,datetime.date} and @ref{48e,,datetime.time} classes.
(Contributed by Wannes Boeykens in gh-41431@footnote{https://github.com/python/cpython/issues/41431}.)
@end itemize

@node decimal,difflib<2>,datetime<2>,Improved modules<3>
@anchor{whatsnew/3 14 decimal}@anchor{48f}
@subsubsection decimal



@itemize *

@item 
Add @ref{490,,Decimal.from_number()} as an alternative constructor for
@ref{1c2,,Decimal}.
(Contributed by Serhiy Storchaka in gh-121798@footnote{https://github.com/python/cpython/issues/121798}.)

@item 
Expose @ref{491,,IEEEContext()} to support creation of contexts
corresponding to the IEEE 754 (2008) decimal interchange formats.
(Contributed by Sergey B Kirpichev in gh-53032@footnote{https://github.com/python/cpython/issues/53032}.)
@end itemize

@node difflib<2>,dis,decimal,Improved modules<3>
@anchor{whatsnew/3 14 difflib}@anchor{492}
@subsubsection difflib



@itemize *

@item 
Comparison pages with highlighted changes generated by the
@ref{214,,HtmlDiff} class now support “dark mode”.
(Contributed by Jiahao Li in gh-129939@footnote{https://github.com/python/cpython/issues/129939}.)
@end itemize

@node dis,errno,difflib<2>,Improved modules<3>
@anchor{whatsnew/3 14 dis}@anchor{493}
@subsubsection dis



@itemize *

@item 
Add support for rendering full source location information of
@ref{494,,instructions}, rather than only the line number.
This feature is added to the following interfaces via the `show_positions'
keyword argument:


@itemize -

@item 
@ref{495,,dis.Bytecode}

@item 
@ref{496,,dis.dis()}

@item 
@ref{497,,dis.distb()}

@item 
@ref{498,,dis.disassemble()}
@end itemize

This feature is also exposed via @ref{499,,dis --show-positions}.
(Contributed by Bénédikt Tran in gh-123165@footnote{https://github.com/python/cpython/issues/123165}.)

@item 
Add the @ref{49a,,dis --specialized} command-line option to
show specialized bytecode.
(Contributed by Bénédikt Tran in gh-127413@footnote{https://github.com/python/cpython/issues/127413}.)
@end itemize

@node errno,faulthandler<2>,dis,Improved modules<3>
@anchor{whatsnew/3 14 errno}@anchor{49b}
@subsubsection errno



@itemize *

@item 
Add the @ref{49c,,EHWPOISON} error code constant.
(Contributed by James Roy in gh-126585@footnote{https://github.com/python/cpython/issues/126585}.)
@end itemize

@node faulthandler<2>,fnmatch,errno,Improved modules<3>
@anchor{whatsnew/3 14 faulthandler}@anchor{49d}
@subsubsection faulthandler



@itemize *

@item 
Add support for printing the C stack trace on systems that
@ref{49e,,support it} via the new
@ref{49f,,dump_c_stack()} function or via the `c_stack' argument
in @ref{219,,faulthandler.enable()}.
(Contributed by Peter Bierma in gh-127604@footnote{https://github.com/python/cpython/issues/127604}.)
@end itemize

@node fnmatch,fractions,faulthandler<2>,Improved modules<3>
@anchor{whatsnew/3 14 fnmatch}@anchor{4a0}
@subsubsection fnmatch



@itemize *

@item 
Add @ref{4a1,,filterfalse()}, a function to reject names
matching a given pattern.
(Contributed by Bénédikt Tran in gh-74598@footnote{https://github.com/python/cpython/issues/74598}.)
@end itemize

@node fractions,functools<3>,fnmatch,Improved modules<3>
@anchor{whatsnew/3 14 fractions}@anchor{4a2}
@subsubsection fractions



@itemize *

@item 
A @ref{1c3,,Fraction} object may now be constructed from any
object with the @code{as_integer_ratio()} method.
(Contributed by Serhiy Storchaka in gh-82017@footnote{https://github.com/python/cpython/issues/82017}.)

@item 
Add @ref{4a3,,Fraction.from_number()} as an alternative constructor for
@ref{1c3,,Fraction}.
(Contributed by Serhiy Storchaka in gh-121797@footnote{https://github.com/python/cpython/issues/121797}.)
@end itemize

@node functools<3>,getopt,fractions,Improved modules<3>
@anchor{whatsnew/3 14 functools}@anchor{4a4}
@subsubsection functools



@itemize *

@item 
Add the @ref{4a5,,Placeholder} sentinel.
This may be used with the @ref{4a6,,partial()}
or @ref{4a7,,partialmethod()} functions to reserve a place
for positional arguments in the returned @ref{4a8,,partial object}.
(Contributed by Dominykas Grigonis in gh-119127@footnote{https://github.com/python/cpython/issues/119127}.)

@item 
Allow the `initial' parameter of @ref{153,,reduce()} to be passed
as a keyword argument.
(Contributed by Sayandip Dutta in gh-125916@footnote{https://github.com/python/cpython/issues/125916}.)
@end itemize

@node getopt,getpass,functools<3>,Improved modules<3>
@anchor{whatsnew/3 14 getopt}@anchor{4a9}
@subsubsection getopt



@itemize *

@item 
Add support for options with optional arguments.
(Contributed by Serhiy Storchaka in gh-126374@footnote{https://github.com/python/cpython/issues/126374}.)

@item 
Add support for returning intermixed options and non-option arguments in order.
(Contributed by Serhiy Storchaka in gh-126390@footnote{https://github.com/python/cpython/issues/126390}.)
@end itemize

@node getpass,graphlib,getopt,Improved modules<3>
@anchor{whatsnew/3 14 getpass}@anchor{4aa}
@subsubsection getpass



@itemize *

@item 
Support keyboard feedback in the @ref{4ab,,getpass()} function via
the keyword-only optional argument `echo_char'.
Placeholder characters are rendered whenever a character is entered,
and removed when a character is deleted.
(Contributed by Semyon Moroz in gh-77065@footnote{https://github.com/python/cpython/issues/77065}.)
@end itemize

@node graphlib,heapq,getpass,Improved modules<3>
@anchor{whatsnew/3 14 graphlib}@anchor{4ac}
@subsubsection graphlib



@itemize *

@item 
Allow @ref{4ad,,TopologicalSorter.prepare()} to be called more than once
as long as sorting has not started.
(Contributed by Daniel Pope in gh-130914@footnote{https://github.com/python/cpython/issues/130914}.)
@end itemize

@node heapq,hmac,graphlib,Improved modules<3>
@anchor{whatsnew/3 14 heapq}@anchor{4ae}
@subsubsection heapq



@itemize *

@item 
The @code{heapq} module has improved support for working with max-heaps,
via the following new functions:


@itemize *

@item 
@ref{4af,,heapify_max()}

@item 
@ref{4b0,,heappush_max()}

@item 
@ref{4b1,,heappop_max()}

@item 
@ref{4b2,,heapreplace_max()}

@item 
@ref{4b3,,heappushpop_max()}
@end itemize
@end itemize

@node hmac,http,heapq,Improved modules<3>
@anchor{whatsnew/3 14 hmac}@anchor{4b4}
@subsubsection hmac



@itemize *

@item 
Add a built-in implementation for HMAC (
@geindex RFC; RFC 2104
RFC 2104@footnote{https://datatracker.ietf.org/doc/html/rfc2104.html}) using formally verified
code from the HACL*@footnote{https://github.com/hacl-star/hacl-star/} project.
This implementation is used as a fallback when the OpenSSL implementation
of HMAC is not available.
(Contributed by Bénédikt Tran in gh-99108@footnote{https://github.com/python/cpython/issues/99108}.)
@end itemize

@node http,imaplib,hmac,Improved modules<3>
@anchor{whatsnew/3 14 http}@anchor{4b5}
@subsubsection http



@itemize *

@item 
Directory lists and error pages generated by the @ref{75,,http.server}
module allow the browser to apply its default dark mode.
(Contributed by Yorik Hansen in gh-123430@footnote{https://github.com/python/cpython/issues/123430}.)

@item 
The @ref{75,,http.server} module now supports serving over HTTPS using the
@ref{4b6,,http.server.HTTPSServer} class. This functionality is exposed by
the command-line interface (@code{python -m http.server}) through the following
options:


@itemize *

@item 
@ref{4b7,,--tls-cert <path>}:
Path to the TLS certificate file.

@item 
@ref{4b8,,--tls-key <path>}:
Optional path to the private key file.

@item 
@ref{4b9,,--tls-password-file <path>}:
Optional path to the password file for the private key.
@end itemize

(Contributed by Semyon Moroz in gh-85162@footnote{https://github.com/python/cpython/issues/85162}.)
@end itemize

@node imaplib,inspect<2>,http,Improved modules<3>
@anchor{whatsnew/3 14 imaplib}@anchor{4ba}
@subsubsection imaplib



@itemize *

@item 
Add @ref{4bb,,IMAP4.idle()}, implementing the IMAP4
@code{IDLE} command as defined in 
@geindex RFC; RFC 2177
RFC 2177@footnote{https://datatracker.ietf.org/doc/html/rfc2177.html}.
(Contributed by Forest in gh-55454@footnote{https://github.com/python/cpython/issues/55454}.)
@end itemize

@node inspect<2>,io,imaplib,Improved modules<3>
@anchor{whatsnew/3 14 inspect}@anchor{4bc}
@subsubsection inspect



@itemize *

@item 
@ref{4bd,,signature()} takes a new argument `annotation_format' to control
the @ref{4be,,annotationlib.Format} used for representing annotations.
(Contributed by Jelle Zijlstra in gh-101552@footnote{https://github.com/python/cpython/issues/101552}.)

@item 
@ref{4bf,,Signature.format()} takes a new argument `unquote_annotations'.
If true, string @ref{409,,annotations} are displayed without
surrounding quotes.
(Contributed by Jelle Zijlstra in gh-101552@footnote{https://github.com/python/cpython/issues/101552}.)

@item 
Add function @ref{4c0,,ispackage()} to determine whether an object is a
@ref{4c1,,package} or not.
(Contributed by Zhikang Yan in gh-125634@footnote{https://github.com/python/cpython/issues/125634}.)
@end itemize

@node io,json<2>,inspect<2>,Improved modules<3>
@anchor{whatsnew/3 14 io}@anchor{4c2}
@subsubsection io



@itemize *

@item 
Reading text from a non-blocking stream with @code{read} may now raise a
@ref{4c3,,BlockingIOError} if the operation cannot immediately return bytes.
(Contributed by Giovanni Siragusa in gh-109523@footnote{https://github.com/python/cpython/issues/109523}.)

@item 
Add the @ref{4c4,,Reader} and @ref{4c5,,Writer} protocols as simpler
alternatives to the pseudo-protocols @ref{4c6,,typing.IO},
@ref{4c7,,typing.TextIO}, and @ref{4c8,,typing.BinaryIO}.
(Contributed by Sebastian Rittau in gh-127648@footnote{https://github.com/python/cpython/issues/127648}.)
@end itemize

@node json<2>,linecache,io,Improved modules<3>
@anchor{whatsnew/3 14 json}@anchor{4c9}
@subsubsection json



@itemize *

@item 
Add exception notes for JSON serialization errors that allow
identifying the source of the error.
(Contributed by Serhiy Storchaka in gh-122163@footnote{https://github.com/python/cpython/issues/122163}.)

@item 
Allow using the @ref{85,,json} module as a script using the @ref{4ca,,-m} switch:
@code{python -m json}.
This is now preferred to @code{python -m json.tool},
which is @ref{1a7,,soft deprecated}.
See the @ref{4cb,,JSON command-line interface} documentation.
(Contributed by Trey Hunner in gh-122873@footnote{https://github.com/python/cpython/issues/122873}.)

@item 
By default, the output of the @ref{4cb,,JSON command-line interface} is highlighted in color.
This can be controlled by @ref{1af,,environment variables}.
(Contributed by Tomas Roun in gh-131952@footnote{https://github.com/python/cpython/issues/131952}.)
@end itemize

@node linecache,logging handlers,json<2>,Improved modules<3>
@anchor{whatsnew/3 14 linecache}@anchor{4cc}
@subsubsection linecache



@itemize *

@item 
@ref{4cd,,getline()} can now retrieve source code for frozen modules.
(Contributed by Tian Gao in gh-131638@footnote{https://github.com/python/cpython/issues/131638}.)
@end itemize

@node logging handlers,math<2>,linecache,Improved modules<3>
@anchor{whatsnew/3 14 logging-handlers}@anchor{4ce}
@subsubsection logging.handlers



@itemize *

@item 
@ref{4cf,,QueueListener} objects now support the
@ref{478,,context manager} protocol.
(Contributed by Charles Machalow in gh-132106@footnote{https://github.com/python/cpython/issues/132106}.)

@item 
@ref{4d0,,QueueListener.start} now
raises a @ref{30d,,RuntimeError} if the listener is already started.
(Contributed by Charles Machalow in gh-132106@footnote{https://github.com/python/cpython/issues/132106}.)
@end itemize

@node math<2>,mimetypes<2>,logging handlers,Improved modules<3>
@anchor{whatsnew/3 14 math}@anchor{4d1}
@subsubsection math



@itemize *

@item 
Added more detailed error messages for domain errors in the module.
(Contributed by Charlie Zhao and Sergey B Kirpichev in gh-101410@footnote{https://github.com/python/cpython/issues/101410}.)
@end itemize

@node mimetypes<2>,multiprocessing,math<2>,Improved modules<3>
@anchor{whatsnew/3 14 mimetypes}@anchor{4d2}
@subsubsection mimetypes



@itemize *

@item 
Add a public @ref{4d3,,command-line} for the module,
invoked via @code{python -m mimetypes}.
(Contributed by Oleg Iarygin and Hugo van Kemenade in gh-93096@footnote{https://github.com/python/cpython/issues/93096}.)

@item 
Add several new MIME types based on RFCs and common usage:

@subsubheading Microsoft and 
@geindex RFC; RFC 8081
RFC 8081@footnote{https://datatracker.ietf.org/doc/html/rfc8081.html} MIME types for fonts



@itemize *

@item 
Embedded OpenType: @code{application/vnd.ms-fontobject}

@item 
OpenType Layout (OTF) @code{font/otf}

@item 
TrueType: @code{font/ttf}

@item 
WOFF 1.0 @code{font/woff}

@item 
WOFF 2.0 @code{font/woff2}
@end itemize

@subsubheading 
@geindex RFC; RFC 9559
RFC 9559@footnote{https://datatracker.ietf.org/doc/html/rfc9559.html} MIME types for Matroska audiovisual data container structures



@itemize *

@item 
audio with no video: @code{audio/matroska} (@code{.mka})

@item 
video: @code{video/matroska} (@code{.mkv})

@item 
stereoscopic video: @code{video/matroska-3d} (@code{.mk3d})
@end itemize

@subsubheading Images with RFCs



@itemize *

@item 
@geindex RFC; RFC 1494
RFC 1494@footnote{https://datatracker.ietf.org/doc/html/rfc1494.html}: CCITT Group 3 (@code{.g3})

@item 
@geindex RFC; RFC 3362
RFC 3362@footnote{https://datatracker.ietf.org/doc/html/rfc3362.html}: Real-time Facsimile, T.38 (@code{.t38})

@item 
@geindex RFC; RFC 3745
RFC 3745@footnote{https://datatracker.ietf.org/doc/html/rfc3745.html}: JPEG 2000 (@code{.jp2}), extension (@code{.jpx}) and compound (@code{.jpm})

@item 
@geindex RFC; RFC 3950
RFC 3950@footnote{https://datatracker.ietf.org/doc/html/rfc3950.html}: Tag Image File Format Fax eXtended, TIFF-FX (@code{.tfx})

@item 
@geindex RFC; RFC 4047
RFC 4047@footnote{https://datatracker.ietf.org/doc/html/rfc4047.html}: Flexible Image Transport System (@code{.fits})

@item 
@geindex RFC; RFC 7903
RFC 7903@footnote{https://datatracker.ietf.org/doc/html/rfc7903.html}: Enhanced Metafile (@code{.emf}) and Windows Metafile (@code{.wmf})
@end itemize

@subsubheading Other MIME type additions and changes



@itemize *

@item 
@geindex RFC; RFC 2361
RFC 2361@footnote{https://datatracker.ietf.org/doc/html/rfc2361.html}: Change type for @code{.avi} to @code{video/vnd.avi}
and for @code{.wav} to @code{audio/vnd.wave}

@item 
@geindex RFC; RFC 4337
RFC 4337@footnote{https://datatracker.ietf.org/doc/html/rfc4337.html}: Add MPEG-4 @code{audio/mp4} (@code{.m4a})

@item 
@geindex RFC; RFC 5334
RFC 5334@footnote{https://datatracker.ietf.org/doc/html/rfc5334.html}: Add Ogg media (@code{.oga}, @code{.ogg} and @code{.ogx})

@item 
@geindex RFC; RFC 6713
RFC 6713@footnote{https://datatracker.ietf.org/doc/html/rfc6713.html}: Add gzip @code{application/gzip} (@code{.gz})

@item 
@geindex RFC; RFC 9639
RFC 9639@footnote{https://datatracker.ietf.org/doc/html/rfc9639.html}: Add FLAC @code{audio/flac} (@code{.flac})

@item 
@geindex RFC; RFC 9512
RFC 9512@footnote{https://datatracker.ietf.org/doc/html/rfc9512.html} @code{application/yaml} MIME type for YAML files (@code{.yaml}
and @code{.yml})

@item 
Add 7z @code{application/x-7z-compressed} (@code{.7z})

@item 
Add Android Package @code{application/vnd.android.package-archive} (@code{.apk})
when not strict

@item 
Add deb @code{application/x-debian-package} (@code{.deb})

@item 
Add glTF binary @code{model/gltf-binary} (@code{.glb})

@item 
Add glTF JSON/ASCII @code{model/gltf+json} (@code{.gltf})

@item 
Add M4V @code{video/x-m4v} (@code{.m4v})

@item 
Add PHP @code{application/x-httpd-php} (@code{.php})

@item 
Add RAR @code{application/vnd.rar} (@code{.rar})

@item 
Add RPM @code{application/x-rpm} (@code{.rpm})

@item 
Add STL @code{model/stl} (@code{.stl})

@item 
Add Windows Media Video @code{video/x-ms-wmv} (@code{.wmv})

@item 
De facto: Add WebM @code{audio/webm} (@code{.weba})

@item 
ECMA-376@footnote{https://ecma-international.org/publications-and-standards/standards/ecma-376/}:
Add @code{.docx}, @code{.pptx} and @code{.xlsx} types

@item 
OASIS@footnote{https://docs.oasis-open.org/office/v1.2/cs01/OpenDocument-v1.2-cs01-part1.html#Appendix_C}:
Add OpenDocument @code{.odg}, @code{.odp}, @code{.ods} and @code{.odt} types

@item 
W3C@footnote{https://www.w3.org/TR/epub-33/#app-media-type}:
Add EPUB @code{application/epub+zip} (@code{.epub})
@end itemize

(Contributed by Sahil Prajapati and Hugo van Kemenade in gh-84852@footnote{https://github.com/python/cpython/issues/84852},
by Sasha «Nelie» Chernykh and Hugo van Kemenade in gh-132056@footnote{https://github.com/python/cpython/issues/132056},
and by Hugo van Kemenade in gh-89416@footnote{https://github.com/python/cpython/issues/89416}, gh-85957@footnote{https://github.com/python/cpython/issues/85957}, and gh-129965@footnote{https://github.com/python/cpython/issues/129965}.)
@end itemize

@node multiprocessing,operator,mimetypes<2>,Improved modules<3>
@anchor{whatsnew/3 14 multiprocessing}@anchor{4d4}
@subsubsection multiprocessing

@anchor{whatsnew/3 14 whatsnew314-multiprocessing-start-method}@anchor{4d5}

@itemize *

@item 
On Unix platforms other than macOS, @ref{46c,,“forkserver”} is now the default @ref{46d,,start method}
(replacing @ref{46e,,“fork”}).
This change does not affect Windows or macOS, where @ref{46f,,“spawn”} remains the default start method.

If the threading incompatible `fork' method is required, you must explicitly
request it via a context from @ref{4d6,,get_context()} (preferred)
or change the default via @ref{4d7,,set_start_method()}.

See @ref{470,,forkserver restrictions}
for information and differences with the `fork' method and how this change
may affect existing code with mutable global shared variables and/or shared
objects that can not be automatically @ref{ab,,pickled}.

(Contributed by Gregory P. Smith in gh-84559@footnote{https://github.com/python/cpython/issues/84559}.)

@item 
@ref{98,,multiprocessing}’s @code{'forkserver'} start method now authenticates
its control socket to avoid solely relying on filesystem permissions
to restrict what other processes could cause the forkserver to spawn workers
and run code.
(Contributed by Gregory P. Smith for gh-97514@footnote{https://github.com/python/cpython/issues/97514}.)

@item 
The @ref{4d8,,multiprocessing proxy objects}
for `list' and `dict' types gain previously overlooked missing methods:

@quotation


@itemize *

@item 
@code{clear()} and @code{copy()} for proxies of @ref{4d9,,list}

@item 
@ref{4da,,fromkeys()}, @code{reversed(d)}, @code{d | @{@}}, @code{@{@} | d},
@code{d |= @{'b': 2@}} for proxies of @ref{188,,dict}
@end itemize
@end quotation

(Contributed by Roy Hyunjin Han for gh-103134@footnote{https://github.com/python/cpython/issues/103134}.)

@item 
Add support for shared @ref{42b,,set} objects via
@ref{4db,,SyncManager.set()}.
The @ref{42b,,set()} in @ref{4dc,,Manager()} method is now available.
(Contributed by Mingyu Park in gh-129949@footnote{https://github.com/python/cpython/issues/129949}.)

@item 
Add the @ref{4dd,,interrupt()}
to @ref{4de,,multiprocessing.Process} objects, which terminates the child
process by sending @ref{4df,,SIGINT}. This enables
@ref{44c,,finally} clauses to print a stack trace for the terminated
process. (Contributed by Artem Pulkin in gh-131913@footnote{https://github.com/python/cpython/issues/131913}.)
@end itemize

@node operator,os<2>,multiprocessing,Improved modules<3>
@anchor{whatsnew/3 14 operator}@anchor{4e0}
@subsubsection operator



@itemize *

@item 
Add @ref{4e1,,is_none()} and @ref{4e2,,is_not_none()} as a pair
of functions, such that @code{operator.is_none(obj)} is equivalent
to @code{obj is None} and @code{operator.is_not_none(obj)} is equivalent
to @code{obj is not None}.
(Contributed by Raymond Hettinger and Nico Mexis in gh-115808@footnote{https://github.com/python/cpython/issues/115808}.)
@end itemize

@node os<2>,os path<2>,operator,Improved modules<3>
@anchor{whatsnew/3 14 os}@anchor{4e3}
@subsubsection os



@itemize *

@item 
Add the @ref{4e4,,reload_environ()} function to update @ref{4e5,,os.environ} and
@ref{4e6,,os.environb} with changes to the environment made by
@ref{4e7,,os.putenv()}, by @ref{4e8,,os.unsetenv()}, or made outside Python in the
same process.
(Contributed by Victor Stinner in gh-120057@footnote{https://github.com/python/cpython/issues/120057}.)

@item 
Add the @ref{4e9,,SCHED_DEADLINE} and @ref{4ea,,SCHED_NORMAL} constants
to the @code{os} module.
(Contributed by James Roy in gh-127688@footnote{https://github.com/python/cpython/issues/127688}.)

@item 
Add the @ref{4eb,,readinto()} function to read into a
@ref{311,,buffer object} from a file descriptor.
(Contributed by Cody Maloney in gh-129205@footnote{https://github.com/python/cpython/issues/129205}.)
@end itemize

@node os path<2>,pathlib<2>,os<2>,Improved modules<3>
@anchor{whatsnew/3 14 os-path}@anchor{4ec}
@subsubsection os.path



@itemize *

@item 
The `strict' parameter to @ref{241,,realpath()} accepts a new value,
@ref{242,,ALLOW_MISSING}.
If used, errors other than @ref{243,,FileNotFoundError} will be re-raised;
the resulting path can be missing but it will be free of symlinks.
(Contributed by Petr Viktorin for 
@geindex Common Vulnerabilities and Exposures; CVE 2025-4517
CVE 2025-4517@footnote{https://www.cve.org/CVERecord?id=CVE-2025-4517}.)
@end itemize

@node pathlib<2>,pdb<2>,os path<2>,Improved modules<3>
@anchor{whatsnew/3 14 pathlib}@anchor{4ed}
@subsubsection pathlib



@itemize *

@item 
Add methods to @ref{4ee,,pathlib.Path} to recursively copy or move files and
directories:


@itemize *

@item 
@ref{4ef,,copy()} copies a file or directory tree to a destination.

@item 
@ref{4f0,,copy_into()} copies `into' a destination directory.

@item 
@ref{4f1,,move()} moves a file or directory tree to a destination.

@item 
@ref{4f2,,move_into()} moves `into' a destination directory.
@end itemize

(Contributed by Barney Gale in gh-73991@footnote{https://github.com/python/cpython/issues/73991}.)

@item 
Add the @ref{4f3,,info} attribute, which stores an object
implementing the new @ref{4f4,,pathlib.types.PathInfo} protocol. The
object supports querying the file type and internally caching
@ref{4f5,,stat()} results. Path objects generated by
@ref{4f6,,iterdir()} are initialized with file type information
gleaned from scanning the parent directory.
(Contributed by Barney Gale in gh-125413@footnote{https://github.com/python/cpython/issues/125413}.)
@end itemize

@node pdb<2>,pickle<2>,pathlib<2>,Improved modules<3>
@anchor{whatsnew/3 14 pdb}@anchor{4f7}
@subsubsection pdb



@itemize *

@item 
The @ref{aa,,pdb} module now supports remote attaching to a running Python process
using a new @ref{4f8,,-p PID} command-line option:

@example
python -m pdb -p 1234
@end example

This will connect to the Python process with the given PID and allow you to
debug it interactively. Notice that due to how the Python interpreter works
attaching to a remote process that is blocked in a system call or waiting for
I/O will only work once the next bytecode instruction is executed or when the
process receives a signal.

This feature uses @ref{3fc,,PEP 768}
and the new @ref{418,,sys.remote_exec()} function to attach to the remote process
and send the PDB commands to it.

(Contributed by Matt Wozniski and Pablo Galindo in gh-131591@footnote{https://github.com/python/cpython/issues/131591}.)

@item 
Hardcoded breakpoints (@ref{4f9,,breakpoint()} and @ref{4fa,,set_trace()}) now
reuse the most recent @ref{4fb,,Pdb} instance that calls
@ref{4fc,,set_trace()}, instead of creating a new one each time.
As a result, all the instance specific data like @ref{4fd,,display} and
@ref{4fe,,commands} are preserved across hardcoded breakpoints.
(Contributed by Tian Gao in gh-121450@footnote{https://github.com/python/cpython/issues/121450}.)

@item 
Add a new argument `mode' to @ref{4fb,,pdb.Pdb}. Disable the @code{restart}
command when @ref{aa,,pdb} is in @code{inline} mode.
(Contributed by Tian Gao in gh-123757@footnote{https://github.com/python/cpython/issues/123757}.)

@item 
A confirmation prompt will be shown when the user tries to quit @ref{aa,,pdb}
in @code{inline} mode. @code{y}, @code{Y}, @code{<Enter>} or @code{EOF} will confirm
the quit and call @ref{4ff,,sys.exit()}, instead of raising @ref{500,,bdb.BdbQuit}.
(Contributed by Tian Gao in gh-124704@footnote{https://github.com/python/cpython/issues/124704}.)

@item 
Inline breakpoints like @ref{4f9,,breakpoint()} or @ref{4fa,,pdb.set_trace()} will
always stop the program at calling frame, ignoring the @code{skip} pattern
(if any).
(Contributed by Tian Gao in gh-130493@footnote{https://github.com/python/cpython/issues/130493}.)

@item 
@code{<tab>} at the beginning of the line in @ref{aa,,pdb} multi-line input will
fill in a 4-space indentation now, instead of inserting a @code{\t} character.
(Contributed by Tian Gao in gh-130471@footnote{https://github.com/python/cpython/issues/130471}.)

@item 
Auto-indent is introduced in @ref{aa,,pdb} multi-line input. It will either
keep the indentation of the last line or insert a 4-space indentation when
it detects a new code block.
(Contributed by Tian Gao in gh-133350@footnote{https://github.com/python/cpython/issues/133350}.)

@item 
@code{$_asynctask} is added to access the current asyncio task if applicable.
(Contributed by Tian Gao in gh-124367@footnote{https://github.com/python/cpython/issues/124367}.)

@item 
@ref{501,,pdb.set_trace_async()} is added to support debugging asyncio
coroutines. @ref{432,,await} statements are supported with this
function.
(Contributed by Tian Gao in gh-132576@footnote{https://github.com/python/cpython/issues/132576}.)

@item 
Source code displayed in @ref{aa,,pdb} will be syntax-highlighted. This feature
can be controlled using the same methods as the default @ref{451,,interactive}
shell, in addition to the newly added @code{colorize} argument of @ref{4fb,,pdb.Pdb}.
(Contributed by Tian Gao and Łukasz Langa in gh-133355@footnote{https://github.com/python/cpython/issues/133355}.)
@end itemize

@node pickle<2>,platform<2>,pdb<2>,Improved modules<3>
@anchor{whatsnew/3 14 pickle}@anchor{502}
@subsubsection pickle



@itemize *

@item 
Set the default protocol version on the @ref{ab,,pickle} module to 5.
For more details, see @ref{503,,pickle protocols}.

@item 
Add exception notes for pickle serialization errors that allow
identifying the source of the error.
(Contributed by Serhiy Storchaka in gh-122213@footnote{https://github.com/python/cpython/issues/122213}.)
@end itemize

@node platform<2>,pydoc,pickle<2>,Improved modules<3>
@anchor{whatsnew/3 14 platform}@anchor{504}
@subsubsection platform



@itemize *

@item 
Add @ref{505,,invalidate_caches()}, a function to invalidate
cached results in the @code{platform} module.
(Contributed by Bénédikt Tran in gh-122549@footnote{https://github.com/python/cpython/issues/122549}.)
@end itemize

@node pydoc,re<2>,platform<2>,Improved modules<3>
@anchor{whatsnew/3 14 pydoc}@anchor{506}
@subsubsection pydoc



@itemize *

@item 
@ref{409,,Annotations} in help output are now usually
displayed in a format closer to that in the original source.
(Contributed by Jelle Zijlstra in gh-101552@footnote{https://github.com/python/cpython/issues/101552}.)
@end itemize

@node re<2>,socket<2>,pydoc,Improved modules<3>
@anchor{whatsnew/3 14 re}@anchor{507}
@subsubsection re



@itemize *

@item 
Support @code{\z} as a synonym for @code{\Z} in @ref{c1,,regular expressions}.
It is interpreted unambiguously in many other regular expression engines,
unlike @code{\Z}, which has subtly different behavior.
(Contributed by Serhiy Storchaka in gh-133306@footnote{https://github.com/python/cpython/issues/133306}.)

@item 
@code{\B} in @ref{c1,,regular expression} now matches the empty input string,
meaning that it is now always the opposite of @code{\b}.
(Contributed by Serhiy Storchaka in gh-124130@footnote{https://github.com/python/cpython/issues/124130}.)
@end itemize

@node socket<2>,ssl<2>,re<2>,Improved modules<3>
@anchor{whatsnew/3 14 socket}@anchor{508}
@subsubsection socket



@itemize *

@item 
Improve and fix support for Bluetooth sockets.


@itemize *

@item 
Fix support of Bluetooth sockets on NetBSD and DragonFly BSD.
(Contributed by Serhiy Storchaka in gh-132429@footnote{https://github.com/python/cpython/issues/132429}.)

@item 
Fix support for @ref{509,,BTPROTO_HCI} on FreeBSD.
(Contributed by Victor Stinner in gh-111178@footnote{https://github.com/python/cpython/issues/111178}.)

@item 
Add support for @ref{50a,,BTPROTO_SCO} on FreeBSD.
(Contributed by Serhiy Storchaka in gh-85302@footnote{https://github.com/python/cpython/issues/85302}.)

@item 
Add support for `cid' and `bdaddr_type' in the address for
@ref{50b,,BTPROTO_L2CAP} on FreeBSD.
(Contributed by Serhiy Storchaka in gh-132429@footnote{https://github.com/python/cpython/issues/132429}.)

@item 
Add support for `channel' in the address for
@ref{509,,BTPROTO_HCI} on Linux.
(Contributed by Serhiy Storchaka in gh-70145@footnote{https://github.com/python/cpython/issues/70145}.)

@item 
Accept an integer as the address for
@ref{509,,BTPROTO_HCI} on Linux.
(Contributed by Serhiy Storchaka in gh-132099@footnote{https://github.com/python/cpython/issues/132099}.)

@item 
Return `cid' in @ref{50c,,getsockname()} for
@ref{50b,,BTPROTO_L2CAP}.
(Contributed by Serhiy Storchaka in gh-132429@footnote{https://github.com/python/cpython/issues/132429}.)

@item 
Add many new constants.
(Contributed by Serhiy Storchaka in gh-132734@footnote{https://github.com/python/cpython/issues/132734}.)
@end itemize
@end itemize

@node ssl<2>,struct,socket<2>,Improved modules<3>
@anchor{whatsnew/3 14 ssl}@anchor{50d}
@subsubsection ssl



@itemize *

@item 
Indicate through the @ref{50e,,HAS_PHA} Boolean whether the @code{ssl}
module supports TLSv1.3 post-handshake client authentication (PHA).
(Contributed by Will Childs-Klein in gh-128036@footnote{https://github.com/python/cpython/issues/128036}.)
@end itemize

@node struct,symtable<3>,ssl<2>,Improved modules<3>
@anchor{whatsnew/3 14 struct}@anchor{50f}
@subsubsection struct



@itemize *

@item 
Support the float complex and double complex C types in
the @ref{de,,struct} module (formatting characters @code{'F'} and @code{'D'}
respectively).
(Contributed by Sergey B Kirpichev in gh-121249@footnote{https://github.com/python/cpython/issues/121249}.)
@end itemize

@node symtable<3>,sys<2>,struct,Improved modules<3>
@anchor{whatsnew/3 14 symtable}@anchor{510}
@subsubsection symtable



@itemize *

@item 
Expose the following @ref{511,,Symbol} methods:


@itemize *

@item 
@ref{512,,is_comp_cell()}

@item 
@ref{513,,is_comp_iter()}

@item 
@ref{514,,is_free_class()}
@end itemize

(Contributed by Bénédikt Tran in gh-120029@footnote{https://github.com/python/cpython/issues/120029}.)
@end itemize

@node sys<2>,sys monitoring<2>,symtable<3>,Improved modules<3>
@anchor{whatsnew/3 14 sys}@anchor{515}
@subsubsection sys



@itemize *

@item 
The previously undocumented special function @ref{516,,sys.getobjects()},
which only exists in specialized builds of Python, may now return objects
from other interpreters than the one it’s called in.
(Contributed by Eric Snow in gh-125286@footnote{https://github.com/python/cpython/issues/125286}.)

@item 
Add @ref{517,,sys._is_immortal()} for determining if an object is @ref{398,,immortal}.
(Contributed by Peter Bierma in gh-128509@footnote{https://github.com/python/cpython/issues/128509}.)

@item 
On FreeBSD, @ref{518,,sys.platform} no longer contains the major version number.
It is always @code{'freebsd'}, instead of @code{'freebsd13'} or @code{'freebsd14'}.
(Contributed by Michael Osipov in gh-129393@footnote{https://github.com/python/cpython/issues/129393}.)

@item 
Raise @ref{2c9,,DeprecationWarning} for @ref{344,,sys._clear_type_cache()}. This
function was deprecated in Python 3.13 but it didn’t raise a runtime warning.

@item 
Add @ref{418,,sys.remote_exec()} to implement the new external debugger interface.
See @ref{3fc,,PEP 768} for details.
(Contributed by Pablo Galindo Salgado, Matt Wozniski, and Ivona Stojanovic
in gh-131591@footnote{https://github.com/python/cpython/issues/131591}.)

@item 
Add the @ref{519,,sys._jit} namespace, containing utilities for introspecting
just-in-time compilation.
(Contributed by Brandt Bucher in gh-133231@footnote{https://github.com/python/cpython/issues/133231}.)
@end itemize

@node sys monitoring<2>,sysconfig<3>,sys<2>,Improved modules<3>
@anchor{whatsnew/3 14 sys-monitoring}@anchor{51a}
@subsubsection sys.monitoring



@itemize *

@item 
Add two new monitoring events, @ref{51b,,BRANCH_LEFT} and
@ref{51c,,BRANCH_RIGHT}.
These replace and deprecate the @code{BRANCH} event.
(Contributed by Mark Shannon in gh-122548@footnote{https://github.com/python/cpython/issues/122548}.)
@end itemize

@node sysconfig<3>,tarfile<2>,sys monitoring<2>,Improved modules<3>
@anchor{whatsnew/3 14 sysconfig}@anchor{51d}
@subsubsection sysconfig



@itemize *

@item 
Add @code{ABIFLAGS} key to @ref{51e,,get_config_vars()} on Windows.
(Contributed by Xuehai Pan in gh-131799@footnote{https://github.com/python/cpython/issues/131799}.)
@end itemize

@node tarfile<2>,threading<3>,sysconfig<3>,Improved modules<3>
@anchor{whatsnew/3 14 tarfile}@anchor{51f}
@subsubsection tarfile



@itemize *

@item 
@ref{279,,data_filter()} now normalizes symbolic link targets in order to
avoid path traversal attacks.
(Contributed by Petr Viktorin in gh-127987@footnote{https://github.com/python/cpython/issues/127987} and 
@geindex Common Vulnerabilities and Exposures; CVE 2025-4138
CVE 2025-4138@footnote{https://www.cve.org/CVERecord?id=CVE-2025-4138}.)

@item 
@ref{27a,,extractall()} now skips fixing up directory attributes
when a directory was removed or replaced by another kind of file.
(Contributed by Petr Viktorin in gh-127987@footnote{https://github.com/python/cpython/issues/127987} and 
@geindex Common Vulnerabilities and Exposures; CVE 2024-12718
CVE 2024-12718@footnote{https://www.cve.org/CVERecord?id=CVE-2024-12718}.)

@item 
@ref{27b,,extract()} and @ref{27a,,extractall()}
now (re-)apply the extraction filter when substituting a link (hard or
symbolic) with a copy of another archive member, and when fixing up
directory attributes.
The former raises a new exception, @ref{27c,,LinkFallbackError}.
(Contributed by Petr Viktorin for 
@geindex Common Vulnerabilities and Exposures; CVE 2025-4330
CVE 2025-4330@footnote{https://www.cve.org/CVERecord?id=CVE-2025-4330} and 
@geindex Common Vulnerabilities and Exposures; CVE 2024-12718
CVE 2024-12718@footnote{https://www.cve.org/CVERecord?id=CVE-2024-12718}.)

@item 
@ref{27b,,extract()} and @ref{27a,,extractall()}
no longer extract rejected members when
@ref{27d,,errorlevel()} is zero.
(Contributed by Matt Prodani and Petr Viktorin in gh-112887@footnote{https://github.com/python/cpython/issues/112887}
and 
@geindex Common Vulnerabilities and Exposures; CVE 2025-4435
CVE 2025-4435@footnote{https://www.cve.org/CVERecord?id=CVE-2025-4435}.)
@end itemize

@node threading<3>,tkinter<2>,tarfile<2>,Improved modules<3>
@anchor{whatsnew/3 14 threading}@anchor{520}
@subsubsection threading



@itemize *

@item 
@ref{422,,threading.Thread.start()} now sets the operating system thread name
to @ref{33d,,threading.Thread.name}.
(Contributed by Victor Stinner in gh-59705@footnote{https://github.com/python/cpython/issues/59705}.)
@end itemize

@node tkinter<2>,turtle,threading<3>,Improved modules<3>
@anchor{whatsnew/3 14 tkinter}@anchor{521}
@subsubsection tkinter



@itemize *

@item 
Make @ref{f9,,tkinter} widget methods @code{after()} and @code{after_idle()}
accept keyword arguments.
(Contributed by Zhikang Yan in gh-126899@footnote{https://github.com/python/cpython/issues/126899}.)

@item 
Add ability to specify a name for @code{tkinter.OptionMenu} and
@code{tkinter.ttk.OptionMenu}.
(Contributed by Zhikang Yan in gh-130482@footnote{https://github.com/python/cpython/issues/130482}.)
@end itemize

@node turtle,types<3>,tkinter<2>,Improved modules<3>
@anchor{whatsnew/3 14 turtle}@anchor{522}
@subsubsection turtle



@itemize *

@item 
Add context managers for @ref{523,,turtle.fill()}, @ref{524,,turtle.poly()},
and @ref{525,,turtle.no_animation()}.
(Contributed by Marie Roald and Yngve Mardal Moe in gh-126350@footnote{https://github.com/python/cpython/issues/126350}.)
@end itemize

@node types<3>,typing<3>,turtle,Improved modules<3>
@anchor{whatsnew/3 14 types}@anchor{526}
@subsubsection types



@itemize *

@item 
@ref{527,,types.UnionType} is now an alias for @ref{341,,typing.Union}.
See @ref{528,,below} for more details.
(Contributed by Jelle Zijlstra in gh-105499@footnote{https://github.com/python/cpython/issues/105499}.)
@end itemize

@node typing<3>,unicodedata<2>,types<3>,Improved modules<3>
@anchor{whatsnew/3 14 typing}@anchor{529}
@subsubsection typing

@anchor{whatsnew/3 14 whatsnew314-typing-union}@anchor{528}

@itemize *

@item 
The @ref{527,,types.UnionType} and @ref{341,,typing.Union} types are now
aliases for each other, meaning that both old-style unions
(created with @code{Union[int, str]}) and new-style unions (@code{int | str})
now create instances of the same runtime type. This unifies the behavior
between the two syntaxes, but leads to some differences in behavior that
may affect users who introspect types at runtime:


@itemize -

@item 
Both syntaxes for creating a union now produce the same string
representation in @ref{45b,,repr()}.
For example, @code{repr(Union[int, str])} is now @code{"int | str"} instead of
@code{"typing.Union[int, str]"}.

@item 
Unions created using the old syntax are no longer cached.
Previously, running @code{Union[int, str]} multiple times would return
the same object (@code{Union[int, str] is Union[int, str]} would be @code{True}),
but now it will return two different objects.
Use @code{==} to compare unions for equality, not @code{is}.
New-style unions have never been cached this way.
This change could increase memory usage for some programs that use
a large number of unions created by subscripting @code{typing.Union}.
However, several factors offset this cost:
unions used in annotations are no longer evaluated by default in Python
3.14 because of 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/}; an instance of @ref{527,,types.UnionType} is
itself much smaller than the object returned by @code{Union[]} was on prior
Python versions; and removing the cache also saves some space.
It is therefore unlikely that this change will cause a significant increase
in memory usage for most users.

@item 
Previously, old-style unions were implemented using the private class
@code{typing._UnionGenericAlias}.
This class is no longer needed for the implementation,
but it has been retained for backward compatibility,
with removal scheduled for Python 3.17.
Users should use documented introspection helpers like
@ref{314,,get_origin()} and @ref{315,,typing.get_args()} instead of
relying on private implementation details.

@item 
It is now possible to use @ref{341,,typing.Union} itself in
@ref{2ef,,isinstance()} checks.
For example, @code{isinstance(int | str, typing.Union)} will return @code{True};
previously this raised @ref{291,,TypeError}.

@item 
The @code{__args__} attribute of @ref{341,,typing.Union} objects is
no longer writable.

@item 
It is no longer possible to set any attributes on @ref{341,,Union}
objects.
This only ever worked for dunder attributes on previous versions, was never
documented to work, and was subtly broken in many cases.
@end itemize

(Contributed by Jelle Zijlstra in gh-105499@footnote{https://github.com/python/cpython/issues/105499}.)

@item 
@ref{52a,,TypeAliasType} now supports star unpacking.
@end itemize

@node unicodedata<2>,unittest<2>,typing<3>,Improved modules<3>
@anchor{whatsnew/3 14 unicodedata}@anchor{52b}
@subsubsection unicodedata



@itemize *

@item 
The Unicode database has been updated to Unicode 16.0.0.
@end itemize

@node unittest<2>,urllib,unicodedata<2>,Improved modules<3>
@anchor{whatsnew/3 14 unittest}@anchor{52c}
@subsubsection unittest

@anchor{whatsnew/3 14 whatsnew314-color-unittest}@anchor{52d}

@itemize *

@item 
@ref{10f,,unittest} output is now colored by default.
This can be controlled by @ref{1af,,environment variables}.
(Contributed by Hugo van Kemenade in gh-127221@footnote{https://github.com/python/cpython/issues/127221}.)

@item 
unittest discovery supports @ref{52e,,namespace package} as start
directory again. It was removed in Python 3.11.
(Contributed by Jacob Walls in gh-80958@footnote{https://github.com/python/cpython/issues/80958}.)

@item 
A number of new methods were added in the @ref{52f,,TestCase} class
that provide more specialized tests.


@itemize -

@item 
@ref{530,,assertHasAttr()} and
@ref{531,,assertNotHasAttr()} check whether the object
has a particular attribute.

@item 
@ref{532,,assertIsSubclass()} and
@ref{533,,assertNotIsSubclass()} check whether the object
is a subclass of a particular class, or of one of a tuple of classes.

@item 
@ref{534,,assertStartsWith()},
@ref{535,,assertNotStartsWith()},
@ref{536,,assertEndsWith()} and
@ref{537,,assertNotEndsWith()} check whether the Unicode
or byte string starts or ends with particular strings.
@end itemize

(Contributed by Serhiy Storchaka in gh-71339@footnote{https://github.com/python/cpython/issues/71339}.)
@end itemize

@node urllib,uuid,unittest<2>,Improved modules<3>
@anchor{whatsnew/3 14 urllib}@anchor{538}
@subsubsection urllib



@itemize *

@item 
Upgrade HTTP digest authentication algorithm for @ref{114,,urllib.request} by
supporting SHA-256 digest authentication as specified in 
@geindex RFC; RFC 7616
RFC 7616@footnote{https://datatracker.ietf.org/doc/html/rfc7616.html}.
(Contributed by Calvin Bui in gh-128193@footnote{https://github.com/python/cpython/issues/128193}.)

@item 
Improve ergonomics and standards compliance when parsing and emitting
@code{file:} URLs.

In @ref{539,,url2pathname()}:


@itemize -

@item 
Accept a complete URL when the new `require_scheme' argument is set to
true.

@item 
Discard URL authority if it matches the local hostname.

@item 
Discard URL authority if it resolves to a local IP address when the new
`resolve_host' argument is set to true.

@item 
Discard URL query and fragment components.

@item 
Raise @ref{53a,,URLError} if a URL authority isn’t local,
except on Windows where we return a UNC path as before.
@end itemize

In @ref{53b,,pathname2url()}:


@itemize -

@item 
Return a complete URL when the new `add_scheme' argument is set to true.

@item 
Include an empty URL authority when a path begins with a slash. For
example, the path @code{/etc/hosts} is converted to the URL @code{///etc/hosts}.
@end itemize

On Windows, drive letters are no longer converted to uppercase, and @code{:}
characters not following a drive letter no longer cause an @ref{53c,,OSError}
exception to be raised.

(Contributed by Barney Gale in gh-125866@footnote{https://github.com/python/cpython/issues/125866}.)
@end itemize

@node uuid,webbrowser<2>,urllib,Improved modules<3>
@anchor{whatsnew/3 14 uuid}@anchor{53d}
@subsubsection uuid



@itemize *

@item 
Add support for UUID versions 6, 7, and 8 via @ref{53e,,uuid6()},
@ref{53f,,uuid7()}, and @ref{540,,uuid8()} respectively, as specified
in 
@geindex RFC; RFC 9562
RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html}.
(Contributed by Bénédikt Tran in gh-89083@footnote{https://github.com/python/cpython/issues/89083}.)

@item 
@ref{541,,NIL} and @ref{542,,MAX} are now available to represent the
Nil and Max UUID formats as defined by 
@geindex RFC; RFC 9562
RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html}.
(Contributed by Nick Pope in gh-128427@footnote{https://github.com/python/cpython/issues/128427}.)

@item 
Allow generating multiple UUIDs simultaneously on the command-line via
@ref{543,,python -m uuid --count}.
(Contributed by Simon Legner in gh-131236@footnote{https://github.com/python/cpython/issues/131236}.)
@end itemize

@node webbrowser<2>,zipfile,uuid,Improved modules<3>
@anchor{whatsnew/3 14 webbrowser}@anchor{544}
@subsubsection webbrowser



@itemize *

@item 
Names in the 
@geindex BROWSER
@geindex μεταβλητή περιβάλλοντος; BROWSER
@code{BROWSER} environment variable can now refer to already
registered browsers for the @ref{11e,,webbrowser} module, instead of always
generating a new browser command.

This makes it possible to set 
@geindex BROWSER
@geindex μεταβλητή περιβάλλοντος; BROWSER
@code{BROWSER} to the value of one of the
supported browsers on macOS.
@end itemize

@node zipfile,,webbrowser<2>,Improved modules<3>
@anchor{whatsnew/3 14 zipfile}@anchor{545}
@subsubsection zipfile



@itemize *

@item 
Added @ref{546,,ZipInfo._for_archive}, a method
to resolve suitable defaults for a @ref{547,,ZipInfo} object
as used by @ref{548,,ZipFile.writestr}.
(Contributed by Bénédikt Tran in gh-123424@footnote{https://github.com/python/cpython/issues/123424}.)

@item 
@ref{548,,ZipFile.writestr()} now respects the 
@geindex SOURCE_DATE_EPOCH
@geindex μεταβλητή περιβάλλοντος; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH}
environment variable in order to better support reproducible builds.
(Contributed by Jiahao Li in gh-91279@footnote{https://github.com/python/cpython/issues/91279}.)
@end itemize

@c Add improved modules above alphabetically, not here at the end.

@node Optimizations<3>,Removed<3>,Improved modules<3>,What’s new in Python 3 14
@anchor{whatsnew/3 14 optimizations}@anchor{549}
@subsection Optimizations



@itemize *

@item 
The import time for several standard library modules has been improved,
including @ref{6,,annotationlib}, @ref{9,,ast}, @ref{b,,asyncio}, @ref{f,,base64},
@ref{1a,,cmd}, @ref{2c,,csv}, @ref{66,,gettext}, @ref{80,,importlib.util}, @ref{89,,locale},
@ref{93,,mimetypes}, @ref{a4,,optparse}, @ref{ab,,pickle}, @ref{b3,,pprint},
@ref{b8,,pstats}, @ref{cc,,shlex}, @ref{d4,,socket}, @ref{db,,string}, @ref{df,,subprocess},
@ref{f6,,threading}, @ref{105,,tomllib}, @ref{10c,,types}, and @ref{13a,,zipfile}.

(Contributed by Adam Turner, Bénédikt Tran, Chris Markiewicz, Eli Schwartz,
Hugo van Kemenade, Jelle Zijlstra, and others in gh-118761@footnote{https://github.com/python/cpython/issues/118761}.)

@item 
The interpreter now avoids some reference count modifications internally
when it’s safe to do so.
This can lead to different values being returned from @ref{54a,,sys.getrefcount()}
and @ref{54b,,Py_REFCNT()} compared to previous versions of Python.
See @ref{54c,,below} for details.
@end itemize

@menu
* asyncio: asyncio<3>. 
* base64: base64<2>. 
* bdb:: 
* difflib: difflib<3>. 
* gc: gc<2>. 
* io: io<2>. 
* pathlib: pathlib<3>. 
* pdb: pdb<3>. 
* textwrap:: 
* uuid: uuid<2>. 
* zlib: zlib<2>. 

@end menu

@node asyncio<3>,base64<2>,,Optimizations<3>
@anchor{whatsnew/3 14 id2}@anchor{54d}
@subsubsection asyncio



@itemize *

@item 
Standard benchmark results have improved by 10-20% following the
implementation of a new per-thread doubly linked list
for @ref{460,,native tasks},
also reducing memory usage.
This enables external introspection tools such as
@ref{3f5,,python -m asyncio pstree}
to introspect the call graph of asyncio tasks running in all threads.
(Contributed by Kumar Aditya in gh-107803@footnote{https://github.com/python/cpython/issues/107803}.)

@item 
The module now has first class support for
@ref{487,,free-threading builds}.
This enables parallel execution of multiple event loops across
different threads, scaling linearly with the number of threads.
(Contributed by Kumar Aditya in gh-128002@footnote{https://github.com/python/cpython/issues/128002}.)
@end itemize

@node base64<2>,bdb,asyncio<3>,Optimizations<3>
@anchor{whatsnew/3 14 base64}@anchor{54e}
@subsubsection base64



@itemize *

@item 
@ref{1f1,,b16decode()} is now up to six times faster.
(Contributed by Bénédikt Tran, Chris Markiewicz, and Adam Turner
in gh-118761@footnote{https://github.com/python/cpython/issues/118761}.)
@end itemize

@node bdb,difflib<3>,base64<2>,Optimizations<3>
@anchor{whatsnew/3 14 bdb}@anchor{54f}
@subsubsection bdb



@itemize *

@item 
The basic debugger now has a @ref{e3,,sys.monitoring}-based backend,
which can be selected via the passing @code{'monitoring'}
to the @ref{550,,Bdb} class’s new `backend' parameter.
(Contributed by Tian Gao in gh-124533@footnote{https://github.com/python/cpython/issues/124533}.)
@end itemize

@node difflib<3>,gc<2>,bdb,Optimizations<3>
@anchor{whatsnew/3 14 id3}@anchor{551}
@subsubsection difflib



@itemize *

@item 
The @ref{552,,IS_LINE_JUNK()} function is now up to twice as fast.
(Contributed by Adam Turner and Semyon Moroz in gh-130167@footnote{https://github.com/python/cpython/issues/130167}.)
@end itemize

@node gc<2>,io<2>,difflib<3>,Optimizations<3>
@anchor{whatsnew/3 14 gc}@anchor{553}
@subsubsection gc



@itemize *

@item 
`From Python 3.14.5 onwards:'

Python 3.14.0-3.14.4 shipped with a new incremental garbage collector.
However, due to a number of reports@footnote{https://github.com/python/cpython/issues/142516}
of significant memory pressure in production environments,
it has been reverted back to the generational GC from 3.13.
This is the GC now used in Python 3.14.5 and later.

@item 
`Previously in Python 3.14.0-3.14.4:'

The new @ref{3ff,,incremental garbage collector}
means that maximum pause times are reduced
by an order of magnitude or more for larger heaps.

Because of this optimization, the meaning of the results of
@ref{554,,get_threshold()} and @ref{555,,set_threshold()} have changed,
along with @ref{556,,get_count()} and @ref{557,,get_stats()}.


@itemize -

@item 
For backwards compatibility, @ref{554,,get_threshold()} continues to return
a three-item tuple.
The first value is the threshold for young collections, as before;
the second value determines the rate at which the old collection is scanned
(the default is 10, and higher values mean that the old collection
is scanned more slowly).
The third value is now meaningless and is always zero.

@item 
@ref{555,,set_threshold()} now ignores any items after the second.

@item 
@ref{556,,get_count()} and @ref{557,,get_stats()} continue to return
the same format of results.
The only difference is that instead of the results referring to
the young, aging and old generations,
the results refer to the young generation
and the aging and collecting spaces of the old generation.
@end itemize

In summary, code that attempted to manipulate the behavior of the cycle GC
may not work exactly as intended, but it is very unlikely to be harmful.
All other code will work just fine.

(Contributed by Mark Shannon in gh-108362@footnote{https://github.com/python/cpython/issues/108362}.)
@end itemize

@node io<2>,pathlib<3>,gc<2>,Optimizations<3>
@anchor{whatsnew/3 14 id4}@anchor{558}
@subsubsection io



@itemize *

@item 
Opening and reading files now executes fewer system calls.
Reading a small operating system cached file in full is up to 15% faster.
(Contributed by Cody Maloney and Victor Stinner
in gh-120754@footnote{https://github.com/python/cpython/issues/120754} and gh-90102@footnote{https://github.com/python/cpython/issues/90102}.)
@end itemize

@node pathlib<3>,pdb<3>,io<2>,Optimizations<3>
@anchor{whatsnew/3 14 id5}@anchor{559}
@subsubsection pathlib



@itemize *

@item 
@ref{55a,,Path.read_bytes} now uses unbuffered mode
to open files, which is between 9% and 17% faster to read in full.
(Contributed by Cody Maloney in gh-120754@footnote{https://github.com/python/cpython/issues/120754}.)
@end itemize

@node pdb<3>,textwrap,pathlib<3>,Optimizations<3>
@anchor{whatsnew/3 14 id6}@anchor{55b}
@subsubsection pdb



@itemize *

@item 
@ref{aa,,pdb} now supports two backends, based on either
@ref{55c,,sys.settrace()} or @ref{e3,,sys.monitoring}.
Using the @ref{55d,,pdb CLI} or @ref{4f9,,breakpoint()}
will always use the @code{sys.monitoring} backend.
Explicitly instantiating @ref{4fb,,pdb.Pdb} and its derived classes
will use the @code{sys.settrace()} backend by default, which is configurable.
(Contributed by Tian Gao in gh-124533@footnote{https://github.com/python/cpython/issues/124533}.)
@end itemize

@node textwrap,uuid<2>,pdb<3>,Optimizations<3>
@anchor{whatsnew/3 14 textwrap}@anchor{55e}
@subsubsection textwrap



@itemize *

@item 
Optimize the @ref{55f,,dedent()} function, improving performance by
an average of 2.4x, with larger improvements for bigger inputs,
and fix a bug with incomplete normalization of blank lines with whitespace
characters other than space and tab.
@end itemize

@node uuid<2>,zlib<2>,textwrap,Optimizations<3>
@anchor{whatsnew/3 14 id7}@anchor{560}
@subsubsection uuid



@itemize *

@item 
@ref{561,,uuid3()} and @ref{562,,uuid5()} are now both roughly 40% faster
for 16-byte names and 20% faster for 1024-byte names.
Performance for longer names remains unchanged.
(Contributed by Bénédikt Tran in gh-128150@footnote{https://github.com/python/cpython/issues/128150}.)

@item 
@ref{563,,uuid4()} is now c. 30% faster.
(Contributed by Bénédikt Tran in gh-128150@footnote{https://github.com/python/cpython/issues/128150}.)
@end itemize

@node zlib<2>,,uuid<2>,Optimizations<3>
@anchor{whatsnew/3 14 zlib}@anchor{564}
@subsubsection zlib



@itemize *

@item 
On Windows, zlib-ng@footnote{https://github.com/zlib-ng/zlib-ng}
is now used as the implementation of the @ref{13c,,zlib} module
in the default binaries.
There are no known incompatibilities between @code{zlib-ng}
and the previously-used @code{zlib} implementation.
This should result in better performance at all compression levels.

It is worth noting that @code{zlib.Z_BEST_SPEED} (@code{1}) may result in
significantly less compression than the previous implementation,
whilst also significantly reducing the time taken to compress.

(Contributed by Steve Dower in gh-91349@footnote{https://github.com/python/cpython/issues/91349}.)
@end itemize

@node Removed<3>,Deprecated<3>,Optimizations<3>,What’s new in Python 3 14
@anchor{whatsnew/3 14 removed}@anchor{565}
@subsection Removed


@menu
* argparse: argparse<3>. 
* ast: ast<4>. 
* asyncio: asyncio<4>. 
* email: email<2>. 
* importlib.abc: importlib abc. 
* itertools:: 
* pathlib: pathlib<4>. 
* pkgutil:: 
* pty:: 
* sqlite3: sqlite3<2>. 
* urllib: urllib<2>. 

@end menu

@node argparse<3>,ast<4>,,Removed<3>
@anchor{whatsnew/3 14 id8}@anchor{566}
@subsubsection argparse



@itemize *

@item 
Remove the `type', `choices', and `metavar' parameters
of @code{BooleanOptionalAction}.
These have been deprecated since Python 3.12.
(Contributed by Nikita Sobolev in gh-118805@footnote{https://github.com/python/cpython/issues/118805}.)

@item 
Calling @ref{31d,,add_argument_group()}
on an argument group now raises a @ref{277,,ValueError}.
Similarly, @code{add_argument_group()}
or @ref{567,,add_mutually_exclusive_group()}
on a mutually exclusive group now both raise @code{ValueError}s.
This “nesting” was never supported, often failed to work correctly,
and was unintentionally exposed through inheritance.
This functionality has been deprecated since Python 3.11.
(Contributed by Savannah Ostrowski in gh-127186@footnote{https://github.com/python/cpython/issues/127186}.)
@end itemize

@node ast<4>,asyncio<4>,argparse<3>,Removed<3>
@anchor{whatsnew/3 14 id9}@anchor{568}
@subsubsection ast



@itemize *

@item 
Remove the following classes, which have been deprecated aliases of
@ref{569,,Constant} since Python 3.8 and have emitted
deprecation warnings since Python 3.12:


@itemize *

@item 
@code{Bytes}

@item 
@code{Ellipsis}

@item 
@code{NameConstant}

@item 
@code{Num}

@item 
@code{Str}
@end itemize

As a consequence of these removals, user-defined @code{visit_Num}, @code{visit_Str},
@code{visit_Bytes}, @code{visit_NameConstant} and @code{visit_Ellipsis} methods
on custom @ref{56a,,NodeVisitor} subclasses will no longer be called
when the @code{NodeVisitor} subclass is visiting an AST.
Define a @code{visit_Constant} method instead.

(Contributed by Alex Waygood in gh-119562@footnote{https://github.com/python/cpython/issues/119562}.)

@item 
Remove the following deprecated properties on @ref{569,,ast.Constant},
which were present for compatibility with the now-removed AST classes:


@itemize *

@item 
@code{Constant.n}

@item 
@code{Constant.s}
@end itemize

Use @code{Constant.value} instead.
(Contributed by Alex Waygood in gh-119562@footnote{https://github.com/python/cpython/issues/119562}.)
@end itemize

@node asyncio<4>,email<2>,ast<4>,Removed<3>
@anchor{whatsnew/3 14 id10}@anchor{56b}
@subsubsection asyncio



@itemize *

@item 
Remove the following classes, methods, and functions,
which have been deprecated since Python 3.12:


@itemize *

@item 
@code{AbstractChildWatcher}

@item 
@code{FastChildWatcher}

@item 
@code{MultiLoopChildWatcher}

@item 
@code{PidfdChildWatcher}

@item 
@code{SafeChildWatcher}

@item 
@code{ThreadedChildWatcher}

@item 
@code{AbstractEventLoopPolicy.get_child_watcher()}

@item 
@code{AbstractEventLoopPolicy.set_child_watcher()}

@item 
@code{get_child_watcher()}

@item 
@code{set_child_watcher()}
@end itemize

(Contributed by Kumar Aditya in gh-120804@footnote{https://github.com/python/cpython/issues/120804}.)

@item 
@ref{56c,,asyncio.get_event_loop()} now raises a @ref{30d,,RuntimeError}
if there is no current event loop,
and no longer implicitly creates an event loop.

(Contributed by Kumar Aditya in gh-126353@footnote{https://github.com/python/cpython/issues/126353}.)

@c TODO: move these patterns to the asyncio docs?
@c quite long for What's New

There’s a few patterns that use @ref{56c,,asyncio.get_event_loop()}, most
of them can be replaced with @ref{309,,asyncio.run()}.

If you’re running an async function, simply use @ref{309,,asyncio.run()}.

Before:

@example
async def main():
    ...


loop = asyncio.get_event_loop()
try:
    loop.run_until_complete(main())
finally:
    loop.close()
@end example

After:

@example
async def main():
    ...

asyncio.run(main())
@end example

If you need to start something, for example, a server listening on a socket
and then run forever, use @ref{309,,asyncio.run()} and an
@ref{56d,,asyncio.Event}.

Before:

@example
def start_server(loop): ...

loop = asyncio.get_event_loop()
try:
    start_server(loop)
    loop.run_forever()
finally:
    loop.close()
@end example

After:

@example
def start_server(loop): ...

async def main():
    start_server(asyncio.get_running_loop())
    await asyncio.Event().wait()

asyncio.run(main())
@end example

If you need to run something in an event loop, then run some blocking
code around it, use @ref{30a,,asyncio.Runner}.

Before:

@example
async def operation_one(): ...
def blocking_code(): ...
async def operation_two(): ...

loop = asyncio.get_event_loop()
try:
    loop.run_until_complete(operation_one())
    blocking_code()
    loop.run_until_complete(operation_two())
finally:
    loop.close()
@end example

After:

@example
async def operation_one(): ...
def blocking_code(): ...
async def operation_two(): ...

with asyncio.Runner() as runner:
    runner.run(operation_one())
    blocking_code()
    runner.run(operation_two())
@end example
@end itemize

@node email<2>,importlib abc,asyncio<4>,Removed<3>
@anchor{whatsnew/3 14 email}@anchor{56e}
@subsubsection email



@itemize *

@item 
Remove @ref{56f,,email.utils.localtime()}”s `isdst' parameter,
which was deprecated in and has been ignored since Python 3.12.
(Contributed by Hugo van Kemenade in gh-118798@footnote{https://github.com/python/cpython/issues/118798}.)
@end itemize

@node importlib abc,itertools,email<2>,Removed<3>
@anchor{whatsnew/3 14 importlib-abc}@anchor{570}
@subsubsection importlib.abc



@itemize *

@item 
Remove deprecated @ref{7b,,importlib.abc} classes:


@itemize *

@item 
@code{ResourceReader}
(use @ref{571,,TraversableResources})

@item 
@code{Traversable}
(use @ref{572,,Traversable})

@item 
@code{TraversableResources}
(use @ref{571,,TraversableResources})
@end itemize

(Contributed by Jason R. Coombs and Hugo van Kemenade in gh-93963@footnote{https://github.com/python/cpython/issues/93963}.)
@end itemize

@node itertools,pathlib<4>,importlib abc,Removed<3>
@anchor{whatsnew/3 14 itertools}@anchor{573}
@subsubsection itertools



@itemize *

@item 
Remove support for copy, deepcopy, and pickle operations
from @ref{84,,itertools} iterators.
These have emitted a @ref{2c9,,DeprecationWarning} since Python 3.12.
(Contributed by Raymond Hettinger in gh-101588@footnote{https://github.com/python/cpython/issues/101588}.)
@end itemize

@node pathlib<4>,pkgutil,itertools,Removed<3>
@anchor{whatsnew/3 14 id11}@anchor{574}
@subsubsection pathlib



@itemize *

@item 
Remove support for passing additional keyword arguments
to @ref{4ee,,Path}.
In previous versions, any such arguments are ignored.
(Contributed by Barney Gale in gh-74033@footnote{https://github.com/python/cpython/issues/74033}.)

@item 
Remove support for passing additional positional arguments to
@ref{575,,PurePath.relative_to()} and @ref{576,,is_relative_to()}.
In previous versions, any such arguments are joined onto `other'.
(Contributed by Barney Gale in gh-78707@footnote{https://github.com/python/cpython/issues/78707}.)
@end itemize

@node pkgutil,pty,pathlib<4>,Removed<3>
@anchor{whatsnew/3 14 pkgutil}@anchor{577}
@subsubsection pkgutil



@itemize *

@item 
Remove the @code{get_loader()} and @code{find_loader()} functions,
which have been deprecated since Python 3.12.
(Contributed by Bénédikt Tran in gh-97850@footnote{https://github.com/python/cpython/issues/97850}.)
@end itemize

@node pty,sqlite3<2>,pkgutil,Removed<3>
@anchor{whatsnew/3 14 pty}@anchor{578}
@subsubsection pty



@itemize *

@item 
Remove the @code{master_open()} and @code{slave_open()} functions,
which have been deprecated since Python 3.12.
Use @ref{579,,pty.openpty()} instead.
(Contributed by Nikita Sobolev in gh-118824@footnote{https://github.com/python/cpython/issues/118824}.)
@end itemize

@node sqlite3<2>,urllib<2>,pty,Removed<3>
@anchor{whatsnew/3 14 sqlite3}@anchor{57a}
@subsubsection sqlite3



@itemize *

@item 
Remove @code{version} and @code{version_info} from
the @ref{d7,,sqlite3} module;
use @ref{57b,,sqlite_version} and @ref{57c,,sqlite_version_info}
for the actual version number of the runtime SQLite library.
(Contributed by Hugo van Kemenade in gh-118924@footnote{https://github.com/python/cpython/issues/118924}.)

@item 
Using a sequence of parameters with named placeholders now
raises a @ref{57d,,ProgrammingError},
having been deprecated since Python 3.12.
(Contributed by Erlend E. Aasland in gh-118928@footnote{https://github.com/python/cpython/issues/118928} and gh-101693@footnote{https://github.com/python/cpython/issues/101693}.)
@end itemize

@node urllib<2>,,sqlite3<2>,Removed<3>
@anchor{whatsnew/3 14 id12}@anchor{57e}
@subsubsection urllib



@itemize *

@item 
Remove the @code{Quoter} class from @ref{113,,urllib.parse},
which has been deprecated since Python 3.11.
(Contributed by Nikita Sobolev in gh-118827@footnote{https://github.com/python/cpython/issues/118827}.)

@item 
Remove the @code{URLopener} and @code{FancyURLopener} classes
from @ref{114,,urllib.request},
which have been deprecated since Python 3.3.

@code{myopener.open()} can be replaced with @ref{57f,,urlopen()}.
@code{myopener.retrieve()} can be replaced with
@ref{580,,urlretrieve()}.
Customisations to the opener classes can be replaced by passing
customized handlers to @ref{581,,build_opener()}.
(Contributed by Barney Gale in gh-84850@footnote{https://github.com/python/cpython/issues/84850}.)
@end itemize

@node Deprecated<3>,CPython bytecode changes,Removed<3>,What’s new in Python 3 14
@anchor{whatsnew/3 14 deprecated}@anchor{582}
@subsection Deprecated


@menu
* New deprecations: New deprecations<2>. 
* Pending removal in Python 3.15: Pending removal in Python 3 15. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<2>. 
* Pending removal in Python 3.17: Pending removal in Python 3 17<2>. 
* Pending removal in Python 3.18: Pending removal in Python 3 18<2>. 
* Pending removal in Python 3.19: Pending removal in Python 3 19<2>. 
* Pending removal in Python 3.20: Pending removal in Python 3 20<2>. 
* Pending removal in future versions: Pending removal in future versions<2>. 

@end menu

@node New deprecations<2>,Pending removal in Python 3 15,,Deprecated<3>
@anchor{whatsnew/3 14 new-deprecations}@anchor{583}
@subsubsection New deprecations



@itemize *

@item 
Passing a complex number as the `real' or `imag' argument in the
@ref{328,,complex()} constructor is now deprecated;
complex numbers should only be passed as a single positional argument.
(Contributed by Serhiy Storchaka in gh-109218@footnote{https://github.com/python/cpython/issues/109218}.)

@item 
@ref{7,,argparse}:


@itemize *

@item 
Passing the undocumented keyword argument `prefix_chars' to the
@ref{31d,,add_argument_group()} method is now deprecated.
(Contributed by Savannah Ostrowski in gh-125563@footnote{https://github.com/python/cpython/issues/125563}.)

@item 
Deprecated the @ref{31e,,argparse.FileType} type converter.
Anything relating to resource management should be handled
downstream, after the arguments have been parsed.
(Contributed by Serhiy Storchaka in gh-58032@footnote{https://github.com/python/cpython/issues/58032}.)
@end itemize

@item 
@ref{b,,asyncio}:


@itemize *

@item 
The @code{asyncio.iscoroutinefunction()} is now deprecated
and will be removed in Python 3.16;
use @ref{302,,inspect.iscoroutinefunction()} instead.
(Contributed by Jiahao Li and Kumar Aditya in gh-122875@footnote{https://github.com/python/cpython/issues/122875}.)

@item 
The @ref{b,,asyncio} policy system is deprecated
and will be removed in Python 3.16.
In particular, the following classes and functions are deprecated:


@itemize *

@item 
@ref{303,,asyncio.AbstractEventLoopPolicy}

@item 
@ref{304,,asyncio.DefaultEventLoopPolicy}

@item 
@ref{305,,asyncio.WindowsSelectorEventLoopPolicy}

@item 
@ref{306,,asyncio.WindowsProactorEventLoopPolicy}

@item 
@ref{307,,asyncio.get_event_loop_policy()}

@item 
@ref{308,,asyncio.set_event_loop_policy()}
@end itemize

Users should use @ref{309,,asyncio.run()} or @ref{30a,,asyncio.Runner} with
the `loop_factory' argument to use the desired event loop implementation.

For example, to use @ref{30b,,asyncio.SelectorEventLoop} on Windows:

@example
import asyncio

async def main():
    ...

asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
@end example

(Contributed by Kumar Aditya in gh-127949@footnote{https://github.com/python/cpython/issues/127949}.)
@end itemize

@item 
@ref{1c,,codecs}:
The @ref{32c,,codecs.open()} function is now deprecated,
and will be removed in a future version of Python.
Use @ref{32b,,open()} instead.
(Contributed by Inada Naoki in gh-133036@footnote{https://github.com/python/cpython/issues/133036}.)

@item 
@ref{2d,,ctypes}:


@itemize *

@item 
On non-Windows platforms, setting @ref{318,,Structure._pack_} to use a
MSVC-compatible default memory layout is now deprecated in favor of setting
@ref{319,,Structure._layout_} to @code{'ms'}, and will be removed in Python 3.19.
(Contributed by Petr Viktorin in gh-131747@footnote{https://github.com/python/cpython/issues/131747}.)

@item 
Calling @ref{484,,ctypes.POINTER()} on a string is now deprecated.
Use @ref{584,,incomplete types}
for self-referential structures.
Also, the internal @code{ctypes._pointer_type_cache} is deprecated.
See @code{ctypes.POINTER()} for updated implementation details.
(Contributed by Sergey Myrianov in gh-100926@footnote{https://github.com/python/cpython/issues/100926}.)
@end itemize

@item 
@ref{62,,functools}:
Calling the Python implementation of @ref{153,,functools.reduce()} with `function'
or `sequence' as keyword arguments is now deprecated;
the parameters will be made positional-only in Python 3.16.
(Contributed by Kirill Podoprigora in gh-121676@footnote{https://github.com/python/cpython/issues/121676}.)

@item 
@ref{8a,,logging}:
Support for custom logging handlers with the `strm' argument
is now deprecated and scheduled for removal in Python 3.16.
Define handlers with the `stream' argument instead.
(Contributed by Mariusz Felisiak in gh-115032@footnote{https://github.com/python/cpython/issues/115032}.)

@item 
@ref{93,,mimetypes}:
Valid extensions are either empty or must start with “.” for
@ref{30c,,mimetypes.MimeTypes.add_type()}.
Undotted extensions are deprecated and will
raise a @ref{277,,ValueError} in Python 3.16.
(Contributed by Hugo van Kemenade in gh-75223@footnote{https://github.com/python/cpython/issues/75223}.)

@item 
@code{nturl2path}:
This module is now deprecated. Call @ref{539,,urllib.request.url2pathname()}
and @ref{53b,,pathname2url()} instead.
(Contributed by Barney Gale in gh-125866@footnote{https://github.com/python/cpython/issues/125866}.)

@item 
@ref{a5,,os}:
The @ref{585,,os.popen()} and @ref{586,,os.spawn*} functions
are now @ref{1a7,,soft deprecated}.
They should no longer be used to write new code.
The @ref{df,,subprocess} module is recommended instead.
(Contributed by Victor Stinner in gh-120743@footnote{https://github.com/python/cpython/issues/120743}.)

@item 
@ref{a8,,pathlib}:
@code{pathlib.PurePath.as_uri()} is now deprecated
and scheduled for removal in Python 3.19.
Use @ref{587,,pathlib.Path.as_uri()} instead.
(Contributed by Barney Gale in gh-123599@footnote{https://github.com/python/cpython/issues/123599}.)

@item 
@ref{aa,,pdb}:
The undocumented @code{pdb.Pdb.curframe_locals} attribute is now a deprecated
read-only property, which will be removed in a future version of Python.
The low overhead dynamic frame locals access added in Python 3.13 by 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}
means the frame locals cache reference previously stored in this attribute
is no longer needed. Derived debuggers should access
@code{pdb.Pdb.curframe.f_locals} directly in Python 3.13 and later versions.
(Contributed by Tian Gao in gh-124369@footnote{https://github.com/python/cpython/issues/124369} and gh-125951@footnote{https://github.com/python/cpython/issues/125951}.)

@item 
@ref{e1,,symtable}:
Deprecate @code{symtable.Class.get_methods()} due to the lack of interest,
scheduled for removal in Python 3.16.
(Contributed by Bénédikt Tran in gh-119698@footnote{https://github.com/python/cpython/issues/119698}.)

@item 
@ref{f9,,tkinter}:
The @code{tkinter.Variable} methods @code{trace_variable()},
@code{trace_vdelete()} and @code{trace_vinfo()} are now deprecated.
Use @code{trace_add()}, @code{trace_remove()} and @code{trace_info()} instead.
(Contributed by Serhiy Storchaka in gh-120220@footnote{https://github.com/python/cpython/issues/120220}.)

@item 
@ref{113,,urllib.parse}:
Accepting objects with false values (like @code{0} and @code{[]}) except empty
strings, bytes-like objects and @code{None} in @ref{588,,parse_qsl()}
and @ref{589,,parse_qs()} is now deprecated.
(Contributed by Serhiy Storchaka in gh-116897@footnote{https://github.com/python/cpython/issues/116897}.)
@end itemize

@c Add deprecations above alphabetically, not here at the end.

@node Pending removal in Python 3 15,Pending removal in Python 3 16<2>,New deprecations<2>,Deprecated<3>
@anchor{whatsnew/3 14 pending-removal-in-python-3-15}@anchor{58a}
@subsubsection Pending removal in Python 3.15



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @code{__cached__} on a module while
failing to set @ref{58b,,__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{58c,,__package__} on a module while
failing to set @ref{58d,,__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{2d,,ctypes}:


@itemize *

@item 
The undocumented @code{ctypes.SetPointerType()} function
has been deprecated since Python 3.13.
@end itemize

@item 
@ref{75,,http.server}:


@itemize *

@item 
The obsolete and rarely used @code{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{7a,,importlib}:


@itemize *

@item 
@code{load_module()} method: use @code{exec_module()} instead.
@end itemize

@item 
@ref{a8,,pathlib}:


@itemize *

@item 
@code{.PurePath.is_reserved()}
has been deprecated since Python 3.13.
Use @ref{2d9,,os.path.isreserved()} to detect reserved paths on Windows.
@end itemize

@item 
@ref{af,,platform}:


@itemize *

@item 
@code{platform.java_ver()} has been deprecated since Python 3.13.
This function is only useful for Jython support, has a confusing API,
and is largely untested.
@end itemize

@item 
@ref{e4,,sysconfig}:


@itemize *

@item 
The `check_home' argument of @ref{2dd,,sysconfig.is_python_build()} has been
deprecated since Python 3.12.
@end itemize

@item 
@ref{f6,,threading}:


@itemize *

@item 
@ref{2df,,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{10c,,types}:


@itemize *

@item 
@ref{2e1,,types.CodeType}: Accessing @code{codeobject.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{2c9,,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{10d,,typing}:


@itemize *

@item 
The undocumented keyword argument syntax for creating
@ref{2e4,,NamedTuple} classes
(for example, @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 
When using the functional syntax of @ref{290,,TypedDict}s, failing
to pass a value to the `fields' parameter (@code{TD = TypedDict("TD")}) or
passing @code{None} (@code{TD = TypedDict("TD", None)}) has been deprecated
since Python 3.13.
Use @code{class TD(TypedDict): pass} or @code{TD = TypedDict("TD", @{@})}
to create a TypedDict with zero field.

@item 
The @code{typing.no_type_check_decorator()} decorator function
has been deprecated since Python 3.13.
After eight years in the @ref{10d,,typing} module,
it has yet to be supported by any major type checker.
@end itemize

@item 
@code{sre_compile}, @code{sre_constants} and @code{sre_parse} modules.

@item 
@ref{11c,,wave}:


@itemize *

@item 
The @code{getmark()}, @code{setmark()} and @code{getmarkers()} methods of
the @ref{2e6,,Wave_read} and @ref{2e7,,Wave_write} classes
have been deprecated since Python 3.13.
@end itemize

@item 
@ref{13b,,zipimport}:


@itemize *

@item 
@code{zipimport.zipimporter.load_module()} has been deprecated since
Python 3.10. Use @ref{2e9,,exec_module()} instead.
(gh-125746@footnote{https://github.com/python/cpython/issues/125746}.)
@end itemize
@end itemize

@node Pending removal in Python 3 16<2>,Pending removal in Python 3 17<2>,Pending removal in Python 3 15,Deprecated<3>
@anchor{whatsnew/3 14 pending-removal-in-python-3-16}@anchor{58e}
@subsubsection Pending removal in Python 3.16



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @ref{2ff,,__loader__} on a module while
failing to set @ref{300,,__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{8,,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{301,,Py_UCS4})
for Unicode characters instead.
@end itemize

@item 
@ref{b,,asyncio}:


@itemize *

@item 
@code{asyncio.iscoroutinefunction()} is deprecated
and will be removed in Python 3.16;
use @ref{302,,inspect.iscoroutinefunction()} instead.
(Contributed by Jiahao Li and Kumar Aditya in gh-122875@footnote{https://github.com/python/cpython/issues/122875}.)

@item 
@ref{b,,asyncio} policy system is deprecated and will be removed in Python 3.16.
In particular, the following classes and functions are deprecated:


@itemize *

@item 
@ref{303,,asyncio.AbstractEventLoopPolicy}

@item 
@ref{304,,asyncio.DefaultEventLoopPolicy}

@item 
@ref{305,,asyncio.WindowsSelectorEventLoopPolicy}

@item 
@ref{306,,asyncio.WindowsProactorEventLoopPolicy}

@item 
@ref{307,,asyncio.get_event_loop_policy()}

@item 
@ref{308,,asyncio.set_event_loop_policy()}
@end itemize

Users should use @ref{309,,asyncio.run()} or @ref{30a,,asyncio.Runner} with
`loop_factory' to use the desired event loop implementation.

For example, to use @ref{30b,,asyncio.SelectorEventLoop} on Windows:

@example
import asyncio

async def main():
    ...

asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
@end example

(Contributed by Kumar Aditya in gh-127949@footnote{https://github.com/python/cpython/issues/127949}.)
@end itemize

@item 
@ref{13,,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{62,,functools}:


@itemize *

@item 
Calling the Python implementation of @ref{153,,functools.reduce()} with `function'
or `sequence' as keyword arguments has been deprecated since Python 3.14.
@end itemize

@item 
@ref{8a,,logging}:


@itemize *

@item 
Support for custom logging handlers with the `strm' argument is deprecated
and scheduled for removal in Python 3.16. Define handlers with the `stream'
argument instead. (Contributed by Mariusz Felisiak in gh-115032@footnote{https://github.com/python/cpython/issues/115032}.)
@end itemize

@item 
@ref{93,,mimetypes}:


@itemize *

@item 
Valid extensions start with a “.” or are empty for
@ref{30c,,mimetypes.MimeTypes.add_type()}.
Undotted extensions are deprecated and will
raise a @ref{277,,ValueError} in Python 3.16.
(Contributed by Hugo van Kemenade in gh-75223@footnote{https://github.com/python/cpython/issues/75223}.)
@end itemize

@item 
@ref{cd,,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{30d,,RuntimeError}.
@end itemize

@item 
@ref{e1,,symtable}:


@itemize *

@item 
The @code{symtable.Class.get_methods()} method
has been deprecated since Python 3.14.
@end itemize

@item 
@ref{e2,,sys}:


@itemize *

@item 
The @ref{30e,,_enablelegacywindowsfsencoding()} function
has been deprecated since Python 3.13.
Use the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,PYTHONLEGACYWINDOWSFSENCODING} environment variable instead.
@end itemize

@item 
@ref{e4,,sysconfig}:


@itemize *

@item 
The @code{sysconfig.expand_makefile_vars()} function
has been deprecated since Python 3.14.
Use the @code{vars} argument of @ref{156,,sysconfig.get_paths()} instead.
@end itemize

@item 
@ref{e7,,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 Python 3 17<2>,Pending removal in Python 3 18<2>,Pending removal in Python 3 16<2>,Deprecated<3>
@anchor{whatsnew/3 14 pending-removal-in-python-3-17}@anchor{58f}
@subsubsection Pending removal in Python 3.17



@itemize *

@item 
@ref{33,,datetime}:


@itemize *

@item 
@ref{2d2,,strptime()} calls using a format string containing
@code{%e} (day of month) without a year.
This has been deprecated since Python 3.15.
(Contributed by Stan Ulbrych in gh-70647@footnote{https://github.com/python/cpython/issues/70647}.)
@end itemize

@item 
@ref{1f,,collections.abc}:


@itemize -

@item 
@ref{2cb,,collections.abc.ByteString} is scheduled for removal in Python 3.17.

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj}
implements the @ref{311,,buffer protocol} at runtime. For use
in type annotations, either use @ref{312,,Buffer} or a union
that explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} was originally intended to be an abstract class that
would serve as a supertype of both @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
However, since the ABC never had any methods, knowing that an object was an
instance of @code{ByteString} never actually told you anything useful
about the object. Other common buffer types such as @ref{1d2,,memoryview}
were also never understood as subtypes of @code{ByteString} (either at
runtime or by static type checkers).

See 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} for more details.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)
@end itemize

@item 
@ref{54,,encodings}:


@itemize -

@item 
Passing non-ascii `encoding' names to @ref{313,,encodings.normalize_encoding()}
is deprecated and scheduled for removal in Python 3.17.
(Contributed by Stan Ulbrych in gh-136702@footnote{https://github.com/python/cpython/issues/136702}.)
@end itemize

@item 
@ref{11e,,webbrowser}:


@itemize -

@item 
@code{webbrowser.MacOSXOSAScript} is deprecated in favour of
@code{webbrowser.MacOS}. (gh-137586@footnote{https://github.com/python/cpython/issues/137586})
@end itemize

@item 
@ref{10d,,typing}:


@itemize -

@item 
Before Python 3.14, old-style unions were implemented using the private class
@code{typing._UnionGenericAlias}. This class is no longer needed for the implementation,
but it has been retained for backward compatibility, with removal scheduled for Python
3.17. Users should use documented introspection helpers like @ref{314,,typing.get_origin()}
and @ref{315,,typing.get_args()} instead of relying on private implementation details.

@item 
@ref{2e3,,typing.ByteString}, deprecated since Python 3.9, is scheduled for removal in
Python 3.17.

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj}
implements the @ref{311,,buffer protocol} at runtime. For use
in type annotations, either use @ref{312,,Buffer} or a union
that explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} was originally intended to be an abstract class that
would serve as a supertype of both @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
However, since the ABC never had any methods, knowing that an object was an
instance of @code{ByteString} never actually told you anything useful
about the object. Other common buffer types such as @ref{1d2,,memoryview}
were also never understood as subtypes of @code{ByteString} (either at
runtime or by static type checkers).

See 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} for more details.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)
@end itemize
@end itemize

@node Pending removal in Python 3 18<2>,Pending removal in Python 3 19<2>,Pending removal in Python 3 17<2>,Deprecated<3>
@anchor{whatsnew/3 14 pending-removal-in-python-3-18}@anchor{590}
@subsubsection Pending removal in Python 3.18



@itemize *

@item 
No longer accept a boolean value when a file descriptor is expected.
(Contributed by Serhiy Storchaka in gh-82626@footnote{https://github.com/python/cpython/issues/82626}.)

@item 
@ref{39,,decimal}:


@itemize *

@item 
The non-standard and undocumented @ref{1c2,,Decimal} format
specifier @code{'N'}, which is only supported in the @code{decimal} module’s
C implementation, has been deprecated since Python 3.13.
(Contributed by Serhiy Storchaka in gh-89902@footnote{https://github.com/python/cpython/issues/89902}.)
@end itemize

@item 
Deprecations defined by 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/}:


@itemize *

@item 
@code{import} lines in @code{`name'.pth} files are silently ignored.
@end itemize

(Contributed by Barry Warsaw in gh-148641@footnote{https://github.com/python/cpython/issues/148641}.)
@end itemize

@node Pending removal in Python 3 19<2>,Pending removal in Python 3 20<2>,Pending removal in Python 3 18<2>,Deprecated<3>
@anchor{whatsnew/3 14 pending-removal-in-python-3-19}@anchor{591}
@subsubsection Pending removal in Python 3.19



@itemize *

@item 
@ref{2d,,ctypes}:


@itemize *

@item 
Implicitly switching to the MSVC-compatible struct layout by setting
@ref{318,,_pack_} but not @ref{319,,_layout_}
on non-Windows platforms.
@end itemize

@item 
@ref{6b,,hashlib}:


@itemize -

@item 
In hash function constructors such as @ref{2f1,,new()} or the
direct hash-named constructors such as @ref{2f2,,md5()} and
@ref{2f3,,sha256()}, their optional initial data parameter could
also be passed a keyword argument named @code{data=} or @code{string=} in
various @code{hashlib} implementations.

Support for the @code{string} keyword argument name is now deprecated
and slated for removal in Python 3.19.

Before Python 3.13, the @code{string} keyword parameter was not correctly
supported depending on the backend implementation of hash functions.
Prefer passing the initial data as a positional argument for maximum
backwards compatibility.
@end itemize

@item 
@ref{74,,http.cookies}:


@itemize *

@item 
@ref{2f4,,http.cookies.Morsel.js_output()} is deprecated and will be
removed in Python 3.19.

@item 
@ref{2f5,,http.cookies.BaseCookie.js_output()} is deprecated and will be
removed in Python 3.19.
@end itemize

@item 
@ref{77,,imaplib}:


@itemize *

@item 
Altering @ref{2f8,,IMAP4.file} is now deprecated
and slated for removal in Python 3.19. This property is now unused
and changing its value does not automatically close the current file.

Before Python 3.14, this property was used to implement the corresponding
@code{read()} and @code{readline()} methods for @ref{31a,,IMAP4} but this
is no longer the case since then.
@end itemize
@end itemize

@node Pending removal in Python 3 20<2>,Pending removal in future versions<2>,Pending removal in Python 3 19<2>,Deprecated<3>
@anchor{whatsnew/3 14 pending-removal-in-python-3-20}@anchor{592}
@subsubsection Pending removal in Python 3.20



@itemize *

@item 
Calling the @code{__new__()} method of @ref{2fb,,struct.Struct} without the
`format' argument is deprecated and will be removed in Python 3.20.  Calling
@ref{2fa,,__init__()} method on initialized @code{Struct}
objects is deprecated and will be removed in Python 3.20.

(Contributed by Sergey B Kirpichev and Serhiy Storchaka in gh-143715@footnote{https://github.com/python/cpython/issues/143715}.)

@item 
The @code{__version__}, @code{version} and @code{VERSION} attributes have been
deprecated in these standard library modules and will be removed in
Python 3.20. Use @ref{2fc,,sys.version_info} instead.


@itemize -

@item 
@ref{7,,argparse}

@item 
@ref{2c,,csv}

@item 
@ref{2d,,ctypes}

@item 
@code{ctypes.macholib}

@item 
@ref{39,,decimal} (use @ref{2fd,,decimal.SPEC_VERSION} instead)

@item 
@ref{75,,http.server}

@item 
@ref{77,,imaplib}

@item 
@ref{83,,ipaddress}

@item 
@ref{85,,json}

@item 
@ref{8a,,logging} (@code{__date__} also deprecated)

@item 
@ref{a4,,optparse}

@item 
@ref{ab,,pickle}

@item 
@ref{af,,platform}

@item 
@ref{c1,,re}

@item 
@ref{d5,,socketserver}

@item 
@ref{e6,,tabnanny}

@item 
@ref{e7,,tarfile}

@item 
@ref{fe,,tkinter.font}

@item 
@ref{102,,tkinter.ttk}

@item 
@ref{124,,wsgiref.simple_server}

@item 
@ref{12e,,xml.etree.ElementTree}

@item 
@code{xml.sax.expatreader}

@item 
@ref{133,,xml.sax.handler}

@item 
@ref{13c,,zlib}
@end itemize

(Contributed by Hugo van Kemenade and Stan Ulbrych in gh-76007@footnote{https://github.com/python/cpython/issues/76007}.)

@item 
Deprecations defined by 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/}:


@itemize *

@item 
Warnings are produced for @code{import} lines found in @code{`name'.pth}
files.

@item 
@code{`name'.pth} files are no longer decoded in the locale encoding by
default.  They `MUST' be encoded in @code{utf-8-sig}.
@end itemize

(Contributed by Barry Warsaw in gh-148641@footnote{https://github.com/python/cpython/issues/148641}.)

@item 
@ref{9,,ast}:


@itemize *

@item 
Creating instances of abstract AST nodes (such as @ref{2ec,,ast.AST}
or @code{ast.expr}) is deprecated and will raise an error in Python 3.20.
@end itemize
@end itemize

@node Pending removal in future versions<2>,,Pending removal in Python 3 20<2>,Deprecated<3>
@anchor{whatsnew/3 14 pending-removal-in-future-versions}@anchor{593}
@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{7,,argparse}:


@itemize *

@item 
Nesting argument groups and nesting mutually exclusive
groups are deprecated.

@item 
Passing the undocumented keyword argument `prefix_chars' to
@ref{31d,,add_argument_group()} is now
deprecated.

@item 
The @ref{31e,,argparse.FileType} type converter is deprecated.
@end itemize

@item 
@ref{13,,builtins}:


@itemize *

@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{31f,,and}, @ref{320,,else}, @ref{321,,for}, @ref{322,,if},
@ref{323,,in}, @ref{324,,is} and @ref{325,,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{326,,int}.

@item 
Support for @code{__float__()} method returning a strict subclass of
@ref{327,,float}: these methods will be required to return an instance of
@code{float}.

@item 
Support for @code{__complex__()} method returning a strict subclass of
@ref{328,,complex}: these methods will be required to return an instance of
@code{complex}.

@item 
Passing a complex number as the `real' or `imag' argument in the
@ref{328,,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{15,,calendar}: @code{calendar.January} and @code{calendar.February} constants are
deprecated and replaced by @ref{329,,calendar.JANUARY} and
@ref{32a,,calendar.FEBRUARY}.
(Contributed by Prince Roshan in gh-103636@footnote{https://github.com/python/cpython/issues/103636}.)

@item 
@ref{1c,,codecs}: use @ref{32b,,open()} instead of @ref{32c,,codecs.open()}. (gh-133038@footnote{https://github.com/python/cpython/issues/133038})

@item 
@code{codeobject.co_lnotab}: use the @ref{32d,,codeobject.co_lines()} method
instead.

@item 
@ref{33,,datetime}:


@itemize *

@item 
@ref{32e,,utcnow()}:
use @code{datetime.datetime.now(tz=datetime.UTC)}.

@item 
@ref{32f,,utcfromtimestamp()}:
use @code{datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)}.
@end itemize

@item 
@ref{66,,gettext}: Plural value must be an integer.

@item 
@ref{7a,,importlib}:


@itemize *

@item 
@ref{330,,cache_from_source()} `debug_override' parameter is
deprecated: use the `optimization' parameter instead.
@end itemize

@item 
@ref{7d,,importlib.metadata}:


@itemize *

@item 
@code{EntryPoints} tuple interface.

@item 
Implicit @code{None} on return values.
@end itemize

@item 
@ref{8a,,logging}: the @code{warn()} method has been deprecated
since Python 3.3, use @ref{331,,warning()} instead.

@item 
@ref{8e,,mailbox}: Use of StringIO input and text mode is deprecated, use
BytesIO and binary mode instead.

@item 
@ref{a5,,os}: Calling @ref{332,,os.register_at_fork()} in a multi-threaded process.

@item 
@ref{a6,,os.path}: @ref{333,,os.path.commonprefix()} is deprecated, use
@ref{334,,os.path.commonpath()} for path prefixes. The @code{os.path.commonprefix()}
function is being deprecated due to having a misleading name and module.
The function is not safe to use for path prefixes despite being included in a
module about path manipulation, meaning it is easy to accidentally
introduce path traversal vulnerabilities into Python programs by using this
function.

@item 
@code{pydoc.ErrorDuringImport}: A tuple value for `exc_info' parameter is
deprecated, use an exception instance.

@item 
@ref{c1,,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 
@ref{cd,,shutil}: @ref{335,,rmtree()}”s `onerror' parameter is deprecated in
Python 3.12; use the `onexc' parameter instead.

@item 
@ref{d8,,ssl} options and protocols:


@itemize *

@item 
@ref{336,,ssl.SSLContext} without protocol argument is deprecated.

@item 
@ref{336,,ssl.SSLContext}: @ref{337,,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{f6,,threading} methods:


@itemize *

@item 
@code{threading.Condition.notifyAll()}: use @ref{338,,notify_all()}.

@item 
@code{threading.Event.isSet()}: use @ref{339,,is_set()}.

@item 
@code{threading.Thread.isDaemon()}, @ref{33a,,threading.Thread.setDaemon()}:
use @ref{33b,,threading.Thread.daemon} attribute.

@item 
@code{threading.Thread.getName()}, @ref{33c,,threading.Thread.setName()}:
use @ref{33d,,threading.Thread.name} attribute.

@item 
@code{threading.currentThread()}: use @ref{33e,,threading.current_thread()}.

@item 
@code{threading.activeCount()}: use @ref{33f,,threading.active_count()}.
@end itemize

@item 
@ref{340,,typing.Text} (gh-92332@footnote{https://github.com/python/cpython/issues/92332}).

@item 
The internal class @code{typing._UnionGenericAlias} is no longer used to implement
@ref{341,,typing.Union}. To preserve compatibility with users using this private
class, a compatibility shim will be provided until at least Python 3.17. (Contributed by
Jelle Zijlstra in gh-105499@footnote{https://github.com/python/cpython/issues/105499}.)

@item 
@ref{342,,unittest.IsolatedAsyncioTestCase}: it is deprecated to return a value
that is not @code{None} from a test case.

@item 
@ref{113,,urllib.parse} deprecated functions: @ref{2a4,,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{121,,wsgiref}: @code{SimpleHandler.stdout.write()} should not do partial
writes.

@item 
@ref{12e,,xml.etree.ElementTree}: Testing the truth value of an
@ref{343,,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{344,,sys._clear_type_cache()} is deprecated:
use @ref{345,,sys._clear_internal_caches()} instead.
@end itemize

@node CPython bytecode changes,C API changes<3>,Deprecated<3>,What’s new in Python 3 14
@anchor{whatsnew/3 14 cpython-bytecode-changes}@anchor{594}
@subsection CPython bytecode changes



@itemize *

@item 
Replaced the opcode @code{BINARY_SUBSCR} by the @ref{595,,BINARY_OP}
opcode with the @code{NB_SUBSCR} oparg.
(Contributed by Irit Katriel in gh-100239@footnote{https://github.com/python/cpython/issues/100239}.)

@item 
Add the @ref{596,,BUILD_INTERPOLATION} and @ref{597,,BUILD_TEMPLATE}
opcodes to construct new @ref{416,,Interpolation}
and @ref{415,,Template} instances, respectively.
(Contributed by Lysandros Nikolaou and others in gh-132661@footnote{https://github.com/python/cpython/issues/132661};
see also @ref{3f2,,PEP 750; Template strings}).

@item 
Remove the @code{BUILD_CONST_KEY_MAP} opcode.
Use @ref{598,,BUILD_MAP} instead.
(Contributed by Mark Shannon in gh-122160@footnote{https://github.com/python/cpython/issues/122160}.)

@item 
Replace the @code{LOAD_ASSERTION_ERROR} opcode with
@ref{599,,LOAD_COMMON_CONSTANT} and add support for loading
@ref{59a,,NotImplementedError}.

@item 
Add the @ref{59b,,LOAD_FAST_BORROW} and @ref{59c,,LOAD_FAST_BORROW_LOAD_FAST_BORROW}
opcodes to reduce reference counting overhead when the interpreter can prove
that the reference in the frame outlives the reference loaded onto the stack.
(Contributed by Matt Page in gh-130704@footnote{https://github.com/python/cpython/issues/130704}.)

@item 
Add the @ref{59d,,LOAD_SMALL_INT} opcode, which pushes a small integer
equal to the @code{oparg} to the stack.
The @code{RETURN_CONST} opcode is removed as it is no longer used.
(Contributed by Mark Shannon in gh-125837@footnote{https://github.com/python/cpython/issues/125837}.)

@item 
Add the new @ref{59e,,LOAD_SPECIAL} instruction.
Generate code for @ref{20a,,with} and @ref{20b,,async with} statements
using the new instruction.
Removed the @code{BEFORE_WITH} and @code{BEFORE_ASYNC_WITH} instructions.
(Contributed by Mark Shannon in gh-120507@footnote{https://github.com/python/cpython/issues/120507}.)

@item 
Add the @ref{59f,,POP_ITER} opcode to support “virtual” iterators.
(Contributed by Mark Shannon in gh-132554@footnote{https://github.com/python/cpython/issues/132554}.)
@end itemize

@menu
* Pseudo-instructions:: 

@end menu

@node Pseudo-instructions,,,CPython bytecode changes
@anchor{whatsnew/3 14 pseudo-instructions}@anchor{5a0}
@subsubsection Pseudo-instructions



@itemize *

@item 
Add the @code{ANNOTATIONS_PLACEHOLDER} pseudo instruction
to support partially executed module-level annotations with
@ref{3f3,,deferred evaluation of annotations}.
(Contributed by Jelle Zijlstra in gh-130907@footnote{https://github.com/python/cpython/issues/130907}.)

@item 
Add the @code{BINARY_OP_EXTEND} pseudo instruction,
which executes a pair of functions (guard and specialization functions)
accessed from the inline cache.
(Contributed by Irit Katriel in gh-100239@footnote{https://github.com/python/cpython/issues/100239}.)

@item 
Add three specializations for @ref{5a1,,CALL_KW};
@code{CALL_KW_PY} for calls to Python functions,
@code{CALL_KW_BOUND_METHOD} for calls to bound methods, and
@code{CALL_KW_NON_PY} for all other calls.
(Contributed by Mark Shannon in gh-118093@footnote{https://github.com/python/cpython/issues/118093}.)

@item 
Add the @ref{5a2,,JUMP_IF_TRUE} and @ref{5a3,,JUMP_IF_FALSE} pseudo instructions,
conditional jumps which do not impact the stack.
Replaced by the sequence @code{COPY 1}, @code{TO_BOOL}, @code{POP_JUMP_IF_TRUE/FALSE}.
(Contributed by Irit Katriel in gh-124285@footnote{https://github.com/python/cpython/issues/124285}.)

@item 
Add the @code{LOAD_CONST_MORTAL} pseudo instruction.
(Contributed by Mark Shannon in gh-128685@footnote{https://github.com/python/cpython/issues/128685}.)

@item 
Add the @code{LOAD_CONST_IMMORTAL} pseudo instruction,
which does the same as @code{LOAD_CONST}, but is more efficient
for immortal objects.
(Contributed by Mark Shannon in gh-125837@footnote{https://github.com/python/cpython/issues/125837}.)

@item 
Add the @ref{5a4,,NOT_TAKEN} pseudo instruction, used by @ref{e3,,sys.monitoring}
to record branch events (such as @ref{51b,,BRANCH_LEFT}).
(Contributed by Mark Shannon in gh-122548@footnote{https://github.com/python/cpython/issues/122548}.)
@end itemize

@node C API changes<3>,Build changes<3>,CPython bytecode changes,What’s new in Python 3 14
@anchor{whatsnew/3 14 c-api-changes}@anchor{5a5}
@subsection C API changes


@menu
* Python configuration C API:: 
* New features in the C API:: 
* Limited C API changes:: 
* Removed C APIs: Removed C APIs<3>. 
* Deprecated C APIs: Deprecated C APIs<3>. 

@end menu

@node Python configuration C API,New features in the C API,,C API changes<3>
@anchor{whatsnew/3 14 python-configuration-c-api}@anchor{5a6}@anchor{whatsnew/3 14 whatsnew314-capi-config}@anchor{402}
@subsubsection Python configuration C API


Add a @ref{5a7,,PyInitConfig C API} to configure the Python
initialization without relying on C structures and the ability to make
ABI-compatible changes in the future.

Complete the 
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/} @ref{5a8,,PyConfig C API} by adding
@ref{5a9,,PyInitConfig_AddModule()} which can be used to add a built-in extension
module; a feature previously referred to as the «inittab».

Add @ref{3a6,,PyConfig_Get()} and @ref{5aa,,PyConfig_Set()} functions to get and set
the current runtime configuration.

@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/} “Python Initialization Configuration” unified all the ways
to configure Python’s initialization. This PEP also unifies the configuration
of Python’s preinitialization and initialization in a single API.
Moreover, this PEP only provides a single choice to embed Python,
instead of having two “Python” and “Isolated” choices (PEP 587),
to further simplify the API.

The lower level PEP 587 PyConfig API remains available for use cases
with an intentionally higher level of coupling to CPython implementation details
(such as emulating the full functionality of CPython’s CLI, including its
configuration mechanisms).

(Contributed by Victor Stinner in gh-107954@footnote{https://github.com/python/cpython/issues/107954}.)


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 741
PEP 741@footnote{https://peps.python.org/pep-0741/} and 
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/}


@node New features in the C API,Limited C API changes,Python configuration C API,C API changes<3>
@anchor{whatsnew/3 14 new-features-in-the-c-api}@anchor{5ab}
@subsubsection New features in the C API



@itemize *

@item 
Add @ref{5ac,,Py_PACK_VERSION()} and @ref{5ad,,Py_PACK_FULL_VERSION()},
two new macros for bit-packing Python version numbers.
This is useful for comparisons with @ref{5ae,,Py_Version}
or @ref{5af,,PY_VERSION_HEX}.
(Contributed by Petr Viktorin in gh-128629@footnote{https://github.com/python/cpython/issues/128629}.)

@item 
Add @ref{5b0,,PyBytes_Join(sep@comma{} iterable)} function,
similar to @code{sep.join(iterable)} in Python.
(Contributed by Victor Stinner in gh-121645@footnote{https://github.com/python/cpython/issues/121645}.)

@item 
Add functions to manipulate the configuration of the current
runtime Python interpreter
(@ref{402,,PEP 741; Python configuration C API}):


@itemize *

@item 
@ref{3a6,,PyConfig_Get()}

@item 
@ref{5b1,,PyConfig_GetInt()}

@item 
@ref{5aa,,PyConfig_Set()}

@item 
@ref{5b2,,PyConfig_Names()}
@end itemize

(Contributed by Victor Stinner in gh-107954@footnote{https://github.com/python/cpython/issues/107954}.)

@item 
Add functions to configure Python initialization
(@ref{402,,PEP 741; Python configuration C API}):


@itemize *

@item 
@ref{5b3,,Py_InitializeFromInitConfig()}

@item 
@ref{5a9,,PyInitConfig_AddModule()}

@item 
@ref{5b4,,PyInitConfig_Create()}

@item 
@ref{5b5,,PyInitConfig_Free()}

@item 
@ref{5b6,,PyInitConfig_FreeStrList()}

@item 
@ref{5b7,,PyInitConfig_GetError()}

@item 
@ref{5b8,,PyInitConfig_GetExitCode()}

@item 
@ref{5b9,,PyInitConfig_GetInt()}

@item 
@ref{5ba,,PyInitConfig_GetStr()}

@item 
@ref{5bb,,PyInitConfig_GetStrList()}

@item 
@ref{5bc,,PyInitConfig_HasOption()}

@item 
@ref{5bd,,PyInitConfig_SetInt()}

@item 
@ref{5be,,PyInitConfig_SetStr()}

@item 
@ref{5bf,,PyInitConfig_SetStrList()}
@end itemize

(Contributed by Victor Stinner in gh-107954@footnote{https://github.com/python/cpython/issues/107954}.)

@item 
Add @ref{5c0,,Py_fopen()} function to open a file.
This works similarly to the standard C @code{fopen()} function,
instead accepting a Python object for the `path' parameter
and setting an exception on error.
The corresponding new @ref{5c1,,Py_fclose()} function should be used
to close a file.
(Contributed by Victor Stinner in gh-127350@footnote{https://github.com/python/cpython/issues/127350}.)

@item 
Add @ref{5c2,,Py_HashBuffer()} to compute and return the hash value of a buffer.
(Contributed by Antoine Pitrou and Victor Stinner in gh-122854@footnote{https://github.com/python/cpython/issues/122854}.)

@item 
Add @ref{5c3,,PyImport_ImportModuleAttr()} and
@ref{5c4,,PyImport_ImportModuleAttrString()} helper functions to import a module
and get an attribute of the module.
(Contributed by Victor Stinner in gh-128911@footnote{https://github.com/python/cpython/issues/128911}.)

@item 
Add @ref{5c5,,PyIter_NextItem()} to replace @ref{5c6,,PyIter_Next()},
which has an ambiguous return value.
(Contributed by Irit Katriel and Erlend Aasland in gh-105201@footnote{https://github.com/python/cpython/issues/105201}.)

@item 
Add @ref{5c7,,PyLong_GetSign()} function to get the sign of @ref{326,,int} objects.
(Contributed by Sergey B Kirpichev in gh-116560@footnote{https://github.com/python/cpython/issues/116560}.)

@item 
Add @ref{5c8,,PyLong_IsPositive()}, @ref{5c9,,PyLong_IsNegative()}
and @ref{5ca,,PyLong_IsZero()} for checking if @ref{5cb,,PyLongObject}
is positive, negative, or zero, respectively.
(Contributed by James Roy and Sergey B Kirpichev in gh-126061@footnote{https://github.com/python/cpython/issues/126061}.)

@item 
Add new functions to convert C @code{<stdint.h>} numbers to/from
Python @ref{326,,int} objects:


@itemize *

@item 
@ref{5cc,,PyLong_AsInt32()}

@item 
@ref{5cd,,PyLong_AsInt64()}

@item 
@ref{5ce,,PyLong_AsUInt32()}

@item 
@ref{5cf,,PyLong_AsUInt64()}

@item 
@ref{5d0,,PyLong_FromInt32()}

@item 
@ref{5d1,,PyLong_FromInt64()}

@item 
@ref{5d2,,PyLong_FromUInt32()}

@item 
@ref{5d3,,PyLong_FromUInt64()}
@end itemize

(Contributed by Victor Stinner in gh-120389@footnote{https://github.com/python/cpython/issues/120389}.)

@item 
Add a new import and export API for Python @ref{326,,int} objects
(
@geindex Python Enhancement Proposals; PEP 757
PEP 757@footnote{https://peps.python.org/pep-0757/}):


@itemize *

@item 
@ref{5d4,,PyLong_GetNativeLayout()}

@item 
@ref{5d5,,PyLong_Export()}

@item 
@ref{5d6,,PyLong_FreeExport()}

@item 
@ref{5d7,,PyLongWriter_Create()}

@item 
@ref{5d8,,PyLongWriter_Finish()}

@item 
@ref{5d9,,PyLongWriter_Discard()}
@end itemize

(Contributed by Sergey B Kirpichev and Victor Stinner in gh-102471@footnote{https://github.com/python/cpython/issues/102471}.)

@item 
Add @ref{5da,,PyMonitoring_FireBranchLeftEvent()} and
@ref{5db,,PyMonitoring_FireBranchRightEvent()} for generating
@ref{51b,,BRANCH_LEFT} and @ref{51c,,BRANCH_RIGHT}
events, respectively.
(Contributed by Mark Shannon in gh-122548@footnote{https://github.com/python/cpython/issues/122548}.)

@item 
Add @ref{5dc,,PyType_Freeze()} function to make a type immutable.
(Contributed by Victor Stinner in gh-121654@footnote{https://github.com/python/cpython/issues/121654}.)

@item 
Add @ref{5dd,,PyType_GetBaseByToken()} and @ref{5de,,Py_tp_token} slot
for easier superclass identification, which attempts to resolve the
type checking issue mentioned in 
@geindex Python Enhancement Proposals; PEP 630#type-checking
PEP 630@footnote{https://peps.python.org/pep-0630/#type-checking}.
(Contributed in gh-124153@footnote{https://github.com/python/cpython/issues/124153}.)

@item 
Add a new @ref{5df,,PyUnicode_Equal()} function to test if two
strings are equal.
The function is also added to the Limited C API.
(Contributed by Victor Stinner in gh-124502@footnote{https://github.com/python/cpython/issues/124502}.)

@item 
Add a new @ref{5e0,,PyUnicodeWriter} API to create a Python @ref{1df,,str}
object, with the following functions:


@itemize *

@item 
@ref{5e1,,PyUnicodeWriter_Create()}

@item 
@ref{5e2,,PyUnicodeWriter_DecodeUTF8Stateful()}

@item 
@ref{5e3,,PyUnicodeWriter_Discard()}

@item 
@ref{5e4,,PyUnicodeWriter_Finish()}

@item 
@ref{5e5,,PyUnicodeWriter_Format()}

@item 
@ref{5e6,,PyUnicodeWriter_WriteASCII()}

@item 
@ref{5e7,,PyUnicodeWriter_WriteChar()}

@item 
@ref{5e8,,PyUnicodeWriter_WriteRepr()}

@item 
@ref{5e9,,PyUnicodeWriter_WriteStr()}

@item 
@ref{5ea,,PyUnicodeWriter_WriteSubstring()}

@item 
@ref{5eb,,PyUnicodeWriter_WriteUCS4()}

@item 
@ref{5ec,,PyUnicodeWriter_WriteUTF8()}

@item 
@ref{5ed,,PyUnicodeWriter_WriteWideChar()}
@end itemize

(Contributed by Victor Stinner in gh-119182@footnote{https://github.com/python/cpython/issues/119182}.)

@item 
The @code{k} and @code{K} formats in @ref{3b1,,PyArg_ParseTuple()} and
similar functions now use @ref{43d,,__index__()} if available,
like all other integer formats.
(Contributed by Serhiy Storchaka in gh-112068@footnote{https://github.com/python/cpython/issues/112068}.)

@item 
Add support for a new @code{p} format unit in @ref{5ee,,Py_BuildValue()}
that produces a Python @ref{5ef,,bool} object from a C integer.
(Contributed by Pablo Galindo in bpo-45325@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45325}.)

@item 
Add @ref{5f0,,PyUnstable_IsImmortal()} for determining if
an object is @ref{398,,immortal}, for debugging purposes.
(Contributed by Peter Bierma in gh-128509@footnote{https://github.com/python/cpython/issues/128509}.)

@item 
Add @ref{5f1,,PyUnstable_Object_EnableDeferredRefcount()} for enabling
deferred reference counting, as outlined in 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}.

@item 
Add @ref{5f2,,PyUnstable_Object_IsUniquelyReferenced()} as
a replacement for @code{Py_REFCNT(op) == 1} on @ref{487,,free threaded} builds.
(Contributed by Peter Bierma in gh-133140@footnote{https://github.com/python/cpython/issues/133140}.)

@item 
Add @ref{5f3,,PyUnstable_Object_IsUniqueReferencedTemporary()} to
determine if an object is a unique temporary object on the
interpreter’s operand stack.
This can be used in some cases as a replacement for checking
if @ref{54b,,Py_REFCNT()} is @code{1} for Python objects passed
as arguments to C API functions.
(Contributed by Sam Gross in gh-133164@footnote{https://github.com/python/cpython/issues/133164}.)
@end itemize

@node Limited C API changes,Removed C APIs<3>,New features in the C API,C API changes<3>
@anchor{whatsnew/3 14 limited-c-api-changes}@anchor{5f4}
@subsubsection Limited C API changes



@itemize *

@item 
In the limited C API version 3.14 and newer, @ref{5f5,,Py_TYPE()} and
@ref{54b,,Py_REFCNT()} are now implemented as an opaque function call
to hide implementation details.
(Contributed by Victor Stinner in gh-120600@footnote{https://github.com/python/cpython/issues/120600} and gh-124127@footnote{https://github.com/python/cpython/issues/124127}.)

@item 
Remove the @ref{5f6,,PySequence_Fast_GET_SIZE},
@ref{5f7,,PySequence_Fast_GET_ITEM},
and @ref{5f8,,PySequence_Fast_ITEMS}
macros from the limited C API, since they have always been broken
in the limited C API.
(Contributed by Victor Stinner in gh-91417@footnote{https://github.com/python/cpython/issues/91417}.)
@end itemize

@node Removed C APIs<3>,Deprecated C APIs<3>,Limited C API changes,C API changes<3>
@anchor{whatsnew/3 14 removed-c-apis}@anchor{5f9}@anchor{whatsnew/3 14 whatsnew314-c-api-removed}@anchor{5fa}
@subsubsection Removed C APIs



@itemize *

@item 
Creating @ref{5fb,,immutable types} with
mutable bases was deprecated in Python 3.12,
and now raises a @ref{291,,TypeError}.
(Contributed by Nikita Sobolev in gh-119775@footnote{https://github.com/python/cpython/issues/119775}.)

@item 
Remove @code{PyDictObject.ma_version_tag} member, which was deprecated
in Python 3.12.
Use the @ref{5fc,,PyDict_AddWatcher()} API instead.
(Contributed by Sam Gross in gh-124296@footnote{https://github.com/python/cpython/issues/124296}.)

@item 
Remove the private @code{_Py_InitializeMain()} function.
It was a @ref{5fd,,provisional API} added to Python 3.8 by 
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/}.
(Contributed by Victor Stinner in gh-129033@footnote{https://github.com/python/cpython/issues/129033}.)

@item 
Remove the undocumented APIs @code{Py_C_RECURSION_LIMIT}
and @code{PyThreadState.c_recursion_remaining}.
These were added in 3.13 and have been removed without deprecation.
Use @ref{5fe,,Py_EnterRecursiveCall()} to guard against runaway
recursion in C code.
(Removed by Petr Viktorin in gh-133079@footnote{https://github.com/python/cpython/issues/133079}, see also gh-130396@footnote{https://github.com/python/cpython/issues/130396}.)
@end itemize

@node Deprecated C APIs<3>,,Removed C APIs<3>,C API changes<3>
@anchor{whatsnew/3 14 deprecated-c-apis}@anchor{5ff}@anchor{whatsnew/3 14 whatsnew314-c-api-deprecated}@anchor{600}
@subsubsection Deprecated C APIs



@itemize *

@item 
The @code{Py_HUGE_VAL} macro is now @ref{1a7,,soft deprecated}.
Use @code{INFINITY} instead.
(Contributed by Sergey B Kirpichev in gh-120026@footnote{https://github.com/python/cpython/issues/120026}.)

@item 
The @code{Py_IS_NAN}, @code{Py_IS_INFINITY},
and @code{Py_IS_FINITE} macros are now @ref{1a7,,soft deprecated}.
Use @code{isnan}, @code{isinf} and @code{isfinite}
instead, available from @code{math.h} since C99.
(Contributed by Sergey B Kirpichev in gh-119613@footnote{https://github.com/python/cpython/issues/119613}.)

@item 
Non-tuple sequences are now deprecated as argument for the @code{(items)}
format unit in @ref{3b1,,PyArg_ParseTuple()} and other @ref{601,,argument parsing} functions if `items' contains format units
which store a @ref{602,,borrowed buffer} or a
@ref{603,,borrowed reference}.
(Contributed by Serhiy Storchaka in gh-50333@footnote{https://github.com/python/cpython/issues/50333}.)

@item 
The @code{_PyMonitoring_FireBranchEvent} function is now deprecated
and should be replaced with calls to
@ref{5da,,PyMonitoring_FireBranchLeftEvent()} and
@ref{5db,,PyMonitoring_FireBranchRightEvent()}.

@item 
The previously undocumented function @ref{604,,PySequence_In()} is
now @ref{1a7,,soft deprecated}.
Use @ref{605,,PySequence_Contains()} instead.
(Contributed by Yuki Kobayashi in gh-127896@footnote{https://github.com/python/cpython/issues/127896}.)
@end itemize

@c Add C API deprecations above alphabetically, not here at the end.

@menu
* Pending removal in Python 3.15: Pending removal in Python 3 15<2>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<3>. 
* Pending removal in Python 3.18: Pending removal in Python 3 18<3>. 
* Pending removal in future versions: Pending removal in future versions<3>. 

@end menu

@node Pending removal in Python 3 15<2>,Pending removal in Python 3 16<3>,,Deprecated C APIs<3>
@anchor{whatsnew/3 14 id13}@anchor{606}
@subsubsection Pending removal in Python 3.15



@itemize *

@item 
The @code{PyImport_ImportModuleNoBlock()}:
Use @ref{3a3,,PyImport_ImportModule()} instead.

@item 
@code{PyWeakref_GetObject()} and @code{PyWeakref_GET_OBJECT()}:
Use @ref{3a4,,PyWeakref_GetRef()} instead. The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
@code{PyWeakref_GetRef()} on Python 3.12 and older.

@item 
@code{PyUnicode_AsDecodedObject()}:
Use @ref{3a1,,PyCodec_Decode()} instead.

@item 
@code{PyUnicode_AsDecodedUnicode()}:
Use @ref{3a1,,PyCodec_Decode()} instead; Note that some codecs (for example, «base64»)
may return a type other than @ref{1df,,str}, such as @ref{1c7,,bytes}.

@item 
@code{PyUnicode_AsEncodedObject()}:
Use @ref{3a2,,PyCodec_Encode()} instead.

@item 
@code{PyUnicode_AsEncodedUnicode()}:
Use @ref{3a2,,PyCodec_Encode()} instead; Note that some codecs (for example, «base64»)
may return a type other than @ref{1c7,,bytes}, such as @ref{1df,,str}.

@item 
Python initialization functions, deprecated in Python 3.13:


@itemize *

@item 
@code{Py_GetPath()}:
Use @ref{3a6,,PyConfig_Get("module_search_paths")}
(@ref{194,,sys.path}) instead.

@item 
@code{Py_GetPrefix()}:
Use @ref{3a6,,PyConfig_Get("base_prefix")}
(@ref{3aa,,sys.base_prefix}) instead. Use @code{PyConfig_Get("prefix")} (@ref{3ab,,sys.prefix}) if @ref{3a9,,virtual environments} need to be handled.

@item 
@code{Py_GetExecPrefix()}:
Use @ref{3a6,,PyConfig_Get("base_exec_prefix")}
(@ref{3a7,,sys.base_exec_prefix}) instead. Use
@code{PyConfig_Get("exec_prefix")}
(@ref{3a8,,sys.exec_prefix}) if @ref{3a9,,virtual environments} need to
be handled.

@item 
@code{Py_GetProgramFullPath()}:
Use @ref{3a6,,PyConfig_Get("executable")}
(@ref{3ac,,sys.executable}) instead.

@item 
@code{Py_GetProgramName()}:
Use @ref{3a6,,PyConfig_Get("executable")}
(@ref{3ac,,sys.executable}) instead.

@item 
@code{Py_GetPythonHome()}:
Use @ref{3a6,,PyConfig_Get("home")} or the
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} environment variable instead.
@end itemize

The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
@ref{3a6,,PyConfig_Get()} on Python 3.13 and older.

@item 
Functions to configure Python’s initialization, deprecated in Python 3.11:


@itemize *

@item 
@code{PySys_SetArgvEx()}:
Set @ref{607,,PyConfig.argv} instead.

@item 
@code{PySys_SetArgv()}:
Set @ref{607,,PyConfig.argv} instead.

@item 
@code{Py_SetProgramName()}:
Set @ref{608,,PyConfig.program_name} instead.

@item 
@code{Py_SetPythonHome()}:
Set @ref{609,,PyConfig.home} instead.

@item 
@code{PySys_ResetWarnOptions()}:
Clear @ref{3a5,,sys.warnoptions} and @code{warnings.filters} instead.
@end itemize

The @ref{60a,,Py_InitializeFromConfig()} API should be used with
@ref{60b,,PyConfig} instead.

@item 
Global configuration variables:


@itemize *

@item 
@ref{60c,,Py_DebugFlag}:
Use @ref{60d,,PyConfig.parser_debug} or
@ref{3a6,,PyConfig_Get("parser_debug")} instead.

@item 
@ref{60e,,Py_VerboseFlag}:
Use @ref{60f,,PyConfig.verbose} or
@ref{3a6,,PyConfig_Get("verbose")} instead.

@item 
@ref{610,,Py_QuietFlag}:
Use @ref{611,,PyConfig.quiet} or
@ref{3a6,,PyConfig_Get("quiet")} instead.

@item 
@ref{612,,Py_InteractiveFlag}:
Use @ref{613,,PyConfig.interactive} or
@ref{3a6,,PyConfig_Get("interactive")} instead.

@item 
@ref{614,,Py_InspectFlag}:
Use @ref{615,,PyConfig.inspect} or
@ref{3a6,,PyConfig_Get("inspect")} instead.

@item 
@ref{616,,Py_OptimizeFlag}:
Use @ref{617,,PyConfig.optimization_level} or
@ref{3a6,,PyConfig_Get("optimization_level")} instead.

@item 
@ref{618,,Py_NoSiteFlag}:
Use @ref{619,,PyConfig.site_import} or
@ref{3a6,,PyConfig_Get("site_import")} instead.

@item 
@ref{61a,,Py_BytesWarningFlag}:
Use @ref{3c4,,PyConfig.bytes_warning} or
@ref{3a6,,PyConfig_Get("bytes_warning")} instead.

@item 
@ref{61b,,Py_FrozenFlag}:
Use @ref{61c,,PyConfig.pathconfig_warnings} or
@ref{3a6,,PyConfig_Get("pathconfig_warnings")} instead.

@item 
@ref{61d,,Py_IgnoreEnvironmentFlag}:
Use @ref{61e,,PyConfig.use_environment} or
@ref{3a6,,PyConfig_Get("use_environment")} instead.

@item 
@ref{61f,,Py_DontWriteBytecodeFlag}:
Use @ref{620,,PyConfig.write_bytecode} or
@ref{3a6,,PyConfig_Get("write_bytecode")} instead.

@item 
@ref{621,,Py_NoUserSiteDirectory}:
Use @ref{622,,PyConfig.user_site_directory} or
@ref{3a6,,PyConfig_Get("user_site_directory")} instead.

@item 
@ref{623,,Py_UnbufferedStdioFlag}:
Use @ref{624,,PyConfig.buffered_stdio} or
@ref{3a6,,PyConfig_Get("buffered_stdio")} instead.

@item 
@ref{625,,Py_HashRandomizationFlag}:
Use @ref{626,,PyConfig.use_hash_seed}
and @ref{627,,PyConfig.hash_seed} or
@ref{3a6,,PyConfig_Get("hash_seed")} instead.

@item 
@ref{628,,Py_IsolatedFlag}:
Use @ref{629,,PyConfig.isolated} or
@ref{3a6,,PyConfig_Get("isolated")} instead.

@item 
@ref{62a,,Py_LegacyWindowsFSEncodingFlag}:
Use @ref{62b,,PyPreConfig.legacy_windows_fs_encoding} or
@ref{3a6,,PyConfig_Get("legacy_windows_fs_encoding")} instead.

@item 
@ref{62c,,Py_LegacyWindowsStdioFlag}:
Use @ref{62d,,PyConfig.legacy_windows_stdio} or
@ref{3a6,,PyConfig_Get("legacy_windows_stdio")} instead.

@item 
@code{Py_FileSystemDefaultEncoding}, @code{Py_HasFileSystemDefaultEncoding}:
Use @ref{62e,,PyConfig.filesystem_encoding} or
@ref{3a6,,PyConfig_Get("filesystem_encoding")} instead.

@item 
@code{Py_FileSystemDefaultEncodeErrors}:
Use @ref{62f,,PyConfig.filesystem_errors} or
@ref{3a6,,PyConfig_Get("filesystem_errors")} instead.

@item 
@code{Py_UTF8Mode}:
Use @ref{630,,PyPreConfig.utf8_mode} or
@ref{3a6,,PyConfig_Get("utf8_mode")} instead.
(see @ref{631,,Py_PreInitialize()})
@end itemize

The @ref{60a,,Py_InitializeFromConfig()} API should be used with
@ref{60b,,PyConfig} to set these options. Or @ref{3a6,,PyConfig_Get()} can be
used to get these options at runtime.
@end itemize

@node Pending removal in Python 3 16<3>,Pending removal in Python 3 18<3>,Pending removal in Python 3 15<2>,Deprecated C APIs<3>
@anchor{whatsnew/3 14 id14}@anchor{632}
@subsubsection Pending removal in Python 3.16



@itemize *

@item 
The bundled copy of @code{libmpdec}.
@end itemize

@node Pending removal in Python 3 18<3>,Pending removal in future versions<3>,Pending removal in Python 3 16<3>,Deprecated C APIs<3>
@anchor{whatsnew/3 14 id15}@anchor{633}
@subsubsection Pending removal in Python 3.18



@itemize *

@item 
The following private functions are deprecated
and planned for removal in Python 3.18:


@itemize *

@item 
@code{_PyBytes_Join()}: use @ref{5b0,,PyBytes_Join()}.

@item 
@code{_PyDict_GetItemStringWithError()}: use @ref{634,,PyDict_GetItemStringRef()}.

@item 
@code{_PyDict_Pop()}: use @ref{635,,PyDict_Pop()}.

@item 
@code{_PyLong_Sign()}: use @ref{5c7,,PyLong_GetSign()}.

@item 
@code{_PyLong_FromDigits()} and @code{_PyLong_New()}:
use @ref{5d7,,PyLongWriter_Create()}.

@item 
@code{_PyThreadState_UncheckedGet()}: use @ref{636,,PyThreadState_GetUnchecked()}.

@item 
@code{_PyUnicode_AsString()}: use @ref{637,,PyUnicode_AsUTF8()}.

@item 
@code{_PyUnicodeWriter_Init()}:
replace @code{_PyUnicodeWriter_Init(&writer)} with
@ref{5e1,,writer = PyUnicodeWriter_Create(0)}.

@item 
@code{_PyUnicodeWriter_Finish()}:
replace @code{_PyUnicodeWriter_Finish(&writer)} with
@ref{5e4,,PyUnicodeWriter_Finish(writer)}.

@item 
@code{_PyUnicodeWriter_Dealloc()}:
replace @code{_PyUnicodeWriter_Dealloc(&writer)} with
@ref{5e3,,PyUnicodeWriter_Discard(writer)}.

@item 
@code{_PyUnicodeWriter_WriteChar()}:
replace @code{_PyUnicodeWriter_WriteChar(&writer, ch)} with
@ref{5e7,,PyUnicodeWriter_WriteChar(writer@comma{} ch)}.

@item 
@code{_PyUnicodeWriter_WriteStr()}:
replace @code{_PyUnicodeWriter_WriteStr(&writer, str)} with
@ref{5e9,,PyUnicodeWriter_WriteStr(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_WriteSubstring()}:
replace @code{_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)} with
@ref{5ea,,PyUnicodeWriter_WriteSubstring(writer@comma{} str@comma{} start@comma{} end)}.

@item 
@code{_PyUnicodeWriter_WriteASCIIString()}:
replace @code{_PyUnicodeWriter_WriteASCIIString(&writer, str)} with
@ref{5e6,,PyUnicodeWriter_WriteASCII(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_WriteLatin1String()}:
replace @code{_PyUnicodeWriter_WriteLatin1String(&writer, str)} with
@ref{5ec,,PyUnicodeWriter_WriteUTF8(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_Prepare()}: (no replacement).

@item 
@code{_PyUnicodeWriter_PrepareKind()}: (no replacement).

@item 
@code{_Py_HashPointer()}: use @ref{638,,Py_HashPointer()}.

@item 
@code{_Py_fopen_obj()}: use @ref{5c0,,Py_fopen()}.
@end itemize

The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
these new public functions on Python 3.13 and older.
(Contributed by Victor Stinner in gh-128863@footnote{https://github.com/python/cpython/issues/128863}.)
@end itemize

@node Pending removal in future versions<3>,,Pending removal in Python 3 18<3>,Deprecated C APIs<3>
@anchor{whatsnew/3 14 id16}@anchor{639}
@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{63a,,Py_TPFLAGS_HAVE_FINALIZE}:
Unneeded since Python 3.8.

@item 
@ref{63b,,PyErr_Fetch()}:
Use @ref{63c,,PyErr_GetRaisedException()} instead.

@item 
@ref{63d,,PyErr_NormalizeException()}:
Use @ref{63c,,PyErr_GetRaisedException()} instead.

@item 
@ref{63e,,PyErr_Restore()}:
Use @ref{63f,,PyErr_SetRaisedException()} instead.

@item 
@ref{640,,PyModule_GetFilename()}:
Use @ref{641,,PyModule_GetFilenameObject()} instead.

@item 
@ref{642,,PyOS_AfterFork()}:
Use @ref{643,,PyOS_AfterFork_Child()} instead.

@item 
@ref{644,,PySlice_GetIndicesEx()}:
Use @ref{645,,PySlice_Unpack()} and @ref{646,,PySlice_AdjustIndices()} instead.

@item 
@ref{647,,PyUnicode_READY()}:
Unneeded since Python 3.12

@item 
@code{PyErr_Display()}:
Use @ref{648,,PyErr_DisplayException()} instead.

@item 
@code{_PyErr_ChainExceptions()}:
Use @code{_PyErr_ChainExceptions1()} instead.

@item 
@code{PyBytesObject.ob_shash} member:
call @ref{649,,PyObject_Hash()} instead.

@item 
Thread Local Storage (TLS) API:


@itemize *

@item 
@ref{64a,,PyThread_create_key()}:
Use @ref{64b,,PyThread_tss_alloc()} instead.

@item 
@ref{64c,,PyThread_delete_key()}:
Use @ref{64d,,PyThread_tss_free()} instead.

@item 
@ref{64e,,PyThread_set_key_value()}:
Use @ref{64f,,PyThread_tss_set()} instead.

@item 
@ref{650,,PyThread_get_key_value()}:
Use @ref{651,,PyThread_tss_get()} instead.

@item 
@ref{652,,PyThread_delete_key_value()}:
Use @ref{653,,PyThread_tss_delete()} instead.

@item 
@ref{654,,PyThread_ReInitTLS()}:
Unneeded since Python 3.7.
@end itemize
@end itemize

@node Build changes<3>,Porting to Python 3 14,C API changes<3>,What’s new in Python 3 14
@anchor{whatsnew/3 14 build-changes}@anchor{655}@anchor{whatsnew/3 14 whatsnew314-build-changes}@anchor{403}
@subsection Build changes



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 776
PEP 776@footnote{https://peps.python.org/pep-0776/}: Emscripten is now an officially supported platform at
@geindex Python Enhancement Proposals; PEP 11#tier-3
tier 3@footnote{https://peps.python.org/pep-0011/#tier-3}. As a part of this effort, more than 25 bugs in
Emscripten libc@footnote{https://emscripten.org/docs/porting/emscripten-runtime-environment.html} were fixed. Emscripten now includes support
for @ref{2d,,ctypes}, @ref{ea,,termios}, and @ref{5c,,fcntl}, as well as
experimental support for the new @ref{656,,default interactive shell}.
(Contributed by R. Hood Chatham in gh-127146@footnote{https://github.com/python/cpython/issues/127146}, gh-127683@footnote{https://github.com/python/cpython/issues/127683}, and gh-136931@footnote{https://github.com/python/cpython/issues/136931}.)

@item 
Official Android binary releases are now provided on python.org@footnote{https://www.python.org/downloads/android/}.

@item 
GNU Autoconf 2.72 is now required to generate @code{configure}.
(Contributed by Erlend Aasland in gh-115765@footnote{https://github.com/python/cpython/issues/115765}.)

@item 
@code{wasm32-unknown-emscripten} is now a 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} tier 3 platform.
(Contributed by R. Hood Chatham in gh-127146@footnote{https://github.com/python/cpython/issues/127146}, gh-127683@footnote{https://github.com/python/cpython/issues/127683}, and gh-136931@footnote{https://github.com/python/cpython/issues/136931}.)

@item 
@code{#pragma}-based linking with @code{python3*.lib} can now be switched off
with @ref{657,,Py_NO_LINK_LIB}.
(Contributed by Jean-Christophe Fillion-Robin in gh-82909@footnote{https://github.com/python/cpython/issues/82909}.)

@item 
CPython now enables a set of recommended compiler options by default
for improved security.
Use the @ref{658,,--disable-safety} @code{configure} option to disable them,
or the @ref{659,,--enable-slower-safety} option for a larger set
of compiler options, albeit with a performance cost.

@item 
The @code{WITH_FREELISTS} macro and @code{--without-freelists} @code{configure}
option have been removed.

@item 
The new @code{configure} option @ref{41c,,--with-tail-call-interp}
may be used to enable the experimental tail call interpreter.
See @ref{2c4,,A new type of interpreter} for further details.

@item 
To disable the new remote debugging support, use the
@ref{41a,,--without-remote-debug} @code{configure} option.
This may be useful for security reasons.

@item 
iOS and macOS apps can now be configured to redirect @code{stdout} and
@code{stderr} content to the system log.
(Contributed by Russell Keith-Magee in gh-127592@footnote{https://github.com/python/cpython/issues/127592}.)

@item 
The iOS testbed is now able to stream test output while the test is running.
The testbed can also be used to run the test suite of projects other than
CPython itself.
(Contributed by Russell Keith-Magee in gh-127592@footnote{https://github.com/python/cpython/issues/127592}.)
@end itemize

@menu
* build-details.json: build-details json. 
* Discontinuation of PGP signatures:: 
* Free-threaded Python is officially supported:: 
* Binary releases for the experimental just-in-time compiler:: 

@end menu

@node build-details json,Discontinuation of PGP signatures,,Build changes<3>
@anchor{whatsnew/3 14 build-details-json}@anchor{65a}@anchor{whatsnew/3 14 whatsnew314-build-details}@anchor{65b}
@subsubsection @code{build-details.json}


Installations of Python now contain a new file, @code{build-details.json}.
This is a static JSON document containing build details for CPython,
to allow for introspection without needing to run code.
This is helpful for use-cases such as Python launchers, cross-compilation,
and so on.

@code{build-details.json} must be installed in the platform-independent
standard library directory. This corresponds to the @ref{65c,,“stdlib”} @ref{e4,,sysconfig} installation path,
which can be found by running @code{sysconfig.get_path('stdlib')}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 739
PEP 739@footnote{https://peps.python.org/pep-0739/} – @code{build-details.json} 1.0 – a static description file
for Python build details


@node Discontinuation of PGP signatures,Free-threaded Python is officially supported,build-details json,Build changes<3>
@anchor{whatsnew/3 14 discontinuation-of-pgp-signatures}@anchor{65d}@anchor{whatsnew/3 14 whatsnew314-no-more-pgp}@anchor{405}
@subsubsection Discontinuation of PGP signatures


PGP (Pretty Good Privacy) signatures will not be provided
for releases of Python 3.14 or future versions.
To verify CPython artifacts, users must use Sigstore verification materials@footnote{https://www.python.org/downloads/metadata/sigstore/}.
Releases have been signed using Sigstore@footnote{https://www.sigstore.dev/} since Python 3.11.

This change in release process was specified in 
@geindex Python Enhancement Proposals; PEP 761
PEP 761@footnote{https://peps.python.org/pep-0761/}.

@node Free-threaded Python is officially supported,Binary releases for the experimental just-in-time compiler,Discontinuation of PGP signatures,Build changes<3>
@anchor{whatsnew/3 14 free-threaded-python-is-officially-supported}@anchor{65e}@anchor{whatsnew/3 14 whatsnew314-free-threaded-now-supported}@anchor{404}
@subsubsection Free-threaded Python is officially supported


The free-threaded build of Python is now supported and no longer experimental.
This is the start of phase II@footnote{https://discuss.python.org/t/37075} where
free-threaded Python is officially supported but still optional.

The free-threading team are confident that the project is on the right path,
and appreciate the continued dedication from everyone working to make
free-threading ready for broader adoption across the Python community.

With these recommendations and the acceptance of this PEP, the Python developer
community should broadly advertise that free-threading is a supported
Python build option now and into the future, and that it will not be removed
without a proper deprecation schedule.

Any decision to transition to phase III@footnote{https://discuss.python.org/t/37075},
with free-threading as the default or sole build of Python is still undecided,
and dependent on many factors both within CPython itself and the community.
This decision is for the future.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 779
PEP 779@footnote{https://peps.python.org/pep-0779/}

PEP 779's acceptance@footnote{https://discuss.python.org/t/84319/123}


@node Binary releases for the experimental just-in-time compiler,,Free-threaded Python is officially supported,Build changes<3>
@anchor{whatsnew/3 14 binary-releases-for-the-experimental-just-in-time-compiler}@anchor{65f}@anchor{whatsnew/3 14 whatsnew314-jit-compiler}@anchor{406}
@subsubsection Binary releases for the experimental just-in-time compiler


The official macOS and Windows release binaries now include an `experimental'
just-in-time (JIT) compiler. Although it is `not' recommended for production
use, it can be tested by setting 
@geindex PYTHON_JIT
@geindex μεταβλητή περιβάλλοντος; PYTHON_JIT
@ref{660,,PYTHON_JIT=1} as an
environment variable. Downstream source builds and redistributors can use the
@ref{661,,--enable-experimental-jit=yes-off} configuration option for similar
behavior.

The JIT is at an early stage and still in active development. As such, the
typical performance impact of enabling it can range from 10% slower to 20%
faster, depending on workload. To aid in testing and evaluation, a set of
introspection functions has been provided in the @ref{519,,sys._jit} namespace.
@ref{662,,sys._jit.is_available()} can be used to determine if the current executable
supports JIT compilation, while @ref{663,,sys._jit.is_enabled()} can be used to tell
if JIT compilation has been enabled for the current process.

Currently, the most significant missing functionality is that native debuggers
and profilers like @code{gdb} and @code{perf} are unable to unwind through JIT frames
(Python debuggers and profilers, like @ref{aa,,pdb} or @ref{b4,,profile}, continue to
work without modification). Free-threaded builds do not support JIT compilation.

Please report any bugs or major performance regressions that you encounter!


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 744
PEP 744@footnote{https://peps.python.org/pep-0744/}


@node Porting to Python 3 14,Notable changes in 3 14 5,Build changes<3>,What’s new in Python 3 14
@anchor{whatsnew/3 14 porting-to-python-3-14}@anchor{3f9}
@subsection Porting to Python 3.14


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

@menu
* Changes in the Python API:: 
* Changes in annotations (PEP 649 and PEP 749): Changes in annotations PEP 649 and PEP 749. 
* Changes in the C API:: 

@end menu

@node Changes in the Python API,Changes in annotations PEP 649 and PEP 749,,Porting to Python 3 14
@anchor{whatsnew/3 14 changes-in-the-python-api}@anchor{664}
@subsubsection Changes in the Python API



@itemize *

@item 
On Unix platforms other than macOS, `forkserver' is now the default
@ref{46d,,start method} for @ref{98,,multiprocessing}
and @ref{206,,ProcessPoolExecutor}, instead of `fork'.

See @ref{46b,,(1)} and
@ref{4d5,,(2)} for details.

If you encounter @ref{665,,NameError}s or pickling errors coming out of
@ref{98,,multiprocessing} or @ref{24,,concurrent.futures}, see the
@ref{470,,forkserver restrictions}.

This change does not affect Windows or macOS, where @ref{46f,,“spawn”} remains the default start method.

@item 
@ref{4a6,,functools.partial} is now a method descriptor.
Wrap it in @ref{666,,staticmethod()} if you want to preserve the old behavior.
(Contributed by Serhiy Storchaka and Dominykas Grigonis in gh-121027@footnote{https://github.com/python/cpython/issues/121027}.)

@item 
The @ref{3ff,,garbage collector is now incremental},
which means that the behavior of @ref{44f,,gc.collect()} changes slightly:


@itemize *

@item 
@code{gc.collect(1)}: Performs an increment of garbage collection,
rather than collecting generation 1.

@item 
Other calls to @code{gc.collect()} are unchanged.
@end itemize

@item 
The @ref{667,,locale.nl_langinfo()} function now temporarily sets the @code{LC_CTYPE}
locale in some cases.
This temporary change affects other threads.
(Contributed by Serhiy Storchaka in gh-69998@footnote{https://github.com/python/cpython/issues/69998}.)

@item 
@ref{527,,types.UnionType} is now an alias for @ref{341,,typing.Union},
causing changes in some behaviors.
See @ref{528,,above} for more details.
(Contributed by Jelle Zijlstra in gh-105499@footnote{https://github.com/python/cpython/issues/105499}.)

@item 
The runtime behavior of annotations has changed in various ways; see
@ref{3f3,,above} for details. While most code that interacts
with annotations should continue to work, some undocumented details may behave
differently.

@item 
As part of making the @ref{93,,mimetypes} CLI public,
it now exits with @code{1} on failure instead of @code{0}
and @code{2} on incorrect command-line parameters instead of @code{1}.
Error messages are now printed to stderr.

@item 
The @code{\B} pattern in regular expression now matches the empty string
when given as the entire pattern, which may cause behavioural changes.

@item 
On FreeBSD, @ref{518,,sys.platform} no longer contains the major version number.
@end itemize

@node Changes in annotations PEP 649 and PEP 749,Changes in the C API,Changes in the Python API,Porting to Python 3 14
@anchor{whatsnew/3 14 changes-in-annotations-pep-649-and-pep-749}@anchor{668}@anchor{whatsnew/3 14 whatsnew314-porting-annotations}@anchor{40e}
@subsubsection Changes in annotations (
@geindex Python Enhancement Proposals; PEP 649
`PEP 649' and 
@geindex Python Enhancement Proposals; PEP 749
`PEP 749')


This section contains guidance on changes that may be needed to annotations
or Python code that interacts with or introspects annotations,
due to the changes related to @ref{3f3,,deferred evaluation of annotations}.

In the majority of cases, working code from older versions of Python
will not require any changes.

@menu
* Implications for annotated code:: 
* Implications for readers of __annotations__:: 
* Related changes:: 
* from __future__ import annotations:: 

@end menu

@node Implications for annotated code,Implications for readers of __annotations__,,Changes in annotations PEP 649 and PEP 749
@anchor{whatsnew/3 14 implications-for-annotated-code}@anchor{669}
@subsubsection Implications for annotated code


If you define annotations in your code (for example, for use with a static type
checker), then this change probably does not affect you: you can keep
writing annotations the same way you did with previous versions of Python.

You will likely be able to remove quoted strings in annotations, which are frequently
used for forward references. Similarly, if you use @code{from __future__ import annotations}
to avoid having to write strings in annotations, you may well be able to
remove that import once you support only Python 3.14 and newer.
However, if you rely on third-party libraries that read annotations,
those libraries may need changes to support unquoted annotations before they
work as expected.

@node Implications for readers of __annotations__,Related changes,Implications for annotated code,Changes in annotations PEP 649 and PEP 749
@anchor{whatsnew/3 14 implications-for-readers-of-annotations}@anchor{66a}
@subsubsection Implications for readers of @code{__annotations__}


If your code reads the @ref{66b,,__annotations__} attribute on objects,
you may want to make changes in order to support code that relies on
deferred evaluation of annotations.
For example, you may want to use @ref{66c,,annotationlib.get_annotations()} with
the @ref{40c,,FORWARDREF} format,
as the @ref{32,,dataclasses} module now does.

The external typing_extensions@footnote{https://pypi.org/project/typing_extensions/} package provides partial backports
of some of the functionality of the @ref{6,,annotationlib} module,
such as the @ref{4be,,Format} enum and
the @ref{66c,,get_annotations()} function.
These can be used to write cross-version code that takes advantage of
the new behavior in Python 3.14.

@node Related changes,from __future__ import annotations,Implications for readers of __annotations__,Changes in annotations PEP 649 and PEP 749
@anchor{whatsnew/3 14 related-changes}@anchor{66d}
@subsubsection Related changes


The changes in Python 3.14 are designed to rework how @code{__annotations__}
works at runtime while minimizing breakage to code that contains
annotations in source code and to code that reads @code{__annotations__}.
However, if you rely on undocumented details of the annotation behavior
or on private functions in the standard library, there are many ways in which
your code may not work in Python 3.14.
To safeguard your code against future changes, only use the documented
functionality of the @ref{6,,annotationlib} module.

In particular, do not read annotations directly from the namespace dictionary
attribute of type objects.
Use @ref{66e,,annotationlib.get_annotate_from_class_namespace()} during class
construction and @ref{66c,,annotationlib.get_annotations()} afterwards.

In previous releases, it was sometimes possible to access class annotations
from an instance of an annotated class. This behavior was undocumented
and accidental, and will no longer work in Python 3.14.

@node from __future__ import annotations,,Related changes,Changes in annotations PEP 649 and PEP 749
@anchor{whatsnew/3 14 from-future-import-annotations}@anchor{66f}
@subsubsection @code{from __future__ import annotations}


In Python 3.7, 
@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/} introduced the @code{from __future__ import annotations}
@ref{670,,future statement}, which turns all annotations into strings.

However, this statement is now deprecated and it is expected to be removed
in a future version of Python.
This removal will not happen until after Python 3.13 reaches its end of life
in 2029, being the last version of Python without support for deferred
evaluation of annotations.

In Python 3.14, the behavior of code using @code{from __future__ import annotations}
is unchanged.

@node Changes in the C API,,Changes in annotations PEP 649 and PEP 749,Porting to Python 3 14
@anchor{whatsnew/3 14 changes-in-the-c-api}@anchor{671}
@subsubsection Changes in the C API



@itemize *

@item 
@ref{672,,Py_Finalize()} now deletes all interned strings. This
is backwards incompatible to any C extension that holds onto an interned
string after a call to @code{Py_Finalize()} and is then reused after a
call to @ref{673,,Py_Initialize()}.  Any issues arising from this behavior will
normally result in crashes during the execution of the subsequent call to
@code{Py_Initialize()} from accessing uninitialized memory. To fix, use
an address sanitizer to identify any use-after-free coming from
an interned string and deallocate it during module shutdown.
(Contributed by Eddie Elizondo in gh-113601@footnote{https://github.com/python/cpython/issues/113601}.)

@item 
The @ref{674,,Unicode Exception Objects} C API
now raises a @ref{291,,TypeError} if its exception argument is not
a @ref{675,,UnicodeError} object.
(Contributed by Bénédikt Tran in gh-127691@footnote{https://github.com/python/cpython/issues/127691}.)
@end itemize
@anchor{whatsnew/3 14 whatsnew314-refcount}@anchor{54c}

@itemize *

@item 
The interpreter internally avoids some reference count modifications when
loading objects onto the operands stack by @ref{603,,borrowing}
references when possible. This can lead to smaller reference count values
compared to previous Python versions. C API extensions that checked
@ref{54b,,Py_REFCNT()} of @code{1} to determine if an function argument is not
referenced by any other code should instead use
@ref{5f3,,PyUnstable_Object_IsUniqueReferencedTemporary()} as a safer replacement.

@item 
Private functions promoted to public C APIs:


@itemize *

@item 
@code{_PyBytes_Join()}: @ref{5b0,,PyBytes_Join()}

@item 
@code{_PyLong_IsNegative()}: @ref{5c9,,PyLong_IsNegative()}

@item 
@code{_PyLong_IsPositive()}: @ref{5c8,,PyLong_IsPositive()}

@item 
@code{_PyLong_IsZero()}: @ref{5ca,,PyLong_IsZero()}

@item 
@code{_PyLong_Sign()}: @ref{5c7,,PyLong_GetSign()}

@item 
@code{_PyUnicodeWriter_Dealloc()}: @ref{5e3,,PyUnicodeWriter_Discard()}

@item 
@code{_PyUnicodeWriter_Finish()}: @ref{5e4,,PyUnicodeWriter_Finish()}

@item 
@code{_PyUnicodeWriter_Init()}: use @ref{5e1,,PyUnicodeWriter_Create()}

@item 
@code{_PyUnicodeWriter_Prepare()}: (no replacement)

@item 
@code{_PyUnicodeWriter_PrepareKind()}: (no replacement)

@item 
@code{_PyUnicodeWriter_WriteChar()}: @ref{5e7,,PyUnicodeWriter_WriteChar()}

@item 
@code{_PyUnicodeWriter_WriteStr()}: @ref{5e9,,PyUnicodeWriter_WriteStr()}

@item 
@code{_PyUnicodeWriter_WriteSubstring()}: @ref{5ea,,PyUnicodeWriter_WriteSubstring()}

@item 
@code{_PyUnicode_EQ()}: @ref{5df,,PyUnicode_Equal()}

@item 
@code{_PyUnicode_Equal()}: @ref{5df,,PyUnicode_Equal()}

@item 
@code{_Py_GetConfig()}: @ref{3a6,,PyConfig_Get()} and @ref{5b1,,PyConfig_GetInt()}

@item 
@code{_Py_HashBytes()}: @ref{5c2,,Py_HashBuffer()}

@item 
@code{_Py_fopen_obj()}: @ref{5c0,,Py_fopen()}

@item 
@code{PyMutex_IsLocked()} : @ref{676,,PyMutex_IsLocked()}
@end itemize

The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get most of these new
functions on Python 3.13 and older.
@end itemize

@node Notable changes in 3 14 5,,Porting to Python 3 14,What’s new in Python 3 14
@anchor{whatsnew/3 14 notable-changes-in-3-14-5}@anchor{677}@anchor{whatsnew/3 14 pythoncapi-compat-project}@anchor{678}
@subsection Notable changes in 3.14.5


@menu
* gc: gc<3>. 

@end menu

@node gc<3>,,,Notable changes in 3 14 5
@anchor{whatsnew/3 14 id19}@anchor{679}
@subsubsection gc



@itemize *

@item 
The incremental garbage collector shipped in Python 3.14.0-3.14.4 has been
reverted back to the generational garbage collector from 3.13,
due to a number of reports@footnote{https://github.com/python/cpython/issues/142516}
of significant memory pressure in production environments.
See @ref{3ff,,Garbage collection} for details.
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 13,What’s New In Python 3 12,What’s new in Python 3 14,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 13 doc}@anchor{67a}@anchor{whatsnew/3 13 translation-repo}@anchor{67b}@anchor{whatsnew/3 13 what-s-new-in-python-3-13}@anchor{67c}
@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{145,,changelog}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 719
PEP 719@footnote{https://peps.python.org/pep-0719/} – Python 3.13 Release Schedule


@menu
* Summary – Release Highlights:: 
* New Features:: 
* Other Language Changes:: 
* New Modules:: 
* Improved Modules:: 
* Optimizations: Optimizations<4>. 
* Removed Modules And APIs:: 
* New Deprecations:: 
* CPython Bytecode Changes:: 
* C API Changes:: 
* Build Changes:: 
* Porting to Python 3.13: Porting to Python 3 13. 
* Regression Test Changes:: 

@end menu

@node Summary – Release Highlights,New Features,,What’s New In Python 3 13
@anchor{whatsnew/3 13 summary-release-highlights}@anchor{67d}
@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 a 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{67e,,interactive interpreter}@anchor{whatsnew/3 13 whatsnew313-better-interactive-interpreter}@anchor{67e},
experimental support for running in a @ref{67f,,free-threaded mode}@anchor{whatsnew/3 13 whatsnew313-free-threaded-cpython}@anchor{67f} (
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}),
and a @ref{680,,Just-In-Time compiler}@anchor{whatsnew/3 13 whatsnew313-jit-compiler}@anchor{680} (
@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{28b,,locals()} builtin now has @ref{681,,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{682,,been removed}@anchor{whatsnew/3 13 whatsnew313-pep594}@anchor{682} 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{3f7,,Library Reference}
and @ref{3f8,,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{683,,Porting to Python 3.13} for guidance on upgrading from
earlier versions of Python.


__________________________________________________________________


@c PEP-sized items next.

Interpreter improvements:


@itemize *

@item 
A greatly improved @ref{67e,,interactive interpreter} and
@ref{684,,improved error messages}.

@item 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}: The @ref{28b,,locals()} builtin now has
@ref{681,,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{685,,global interpreter lock} disabled. See @ref{67f,,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{680,,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{67e,,interactive interpreter},
as well as in @ref{684,,tracebacks}
and @ref{686,,doctest} output.
This can be disabled through the 
@geindex PYTHON_COLORS
@geindex μεταβλητή περιβάλλοντος; PYTHON_COLORS
@ref{687,,PYTHON_COLORS} and NO_COLOR@footnote{https://no-color.org/}
environment variables.
@end itemize

Python data model improvements:


@itemize *

@item 
@ref{688,,__static_attributes__} stores the names of attributes accessed
through @code{self.X} in any function in a class body.

@item 
@ref{689,,__firstlineno__} records the first line number of a class
definition.
@end itemize

Significant improvements in the standard library:


@itemize *

@item 
Add a new @ref{68a,,PythonFinalizationError} exception, raised when an operation
is blocked during @ref{1a0,,finalization}.

@item 
The @ref{7,,argparse} module now supports deprecating command-line options,
positional arguments, and subcommands.

@item 
The new functions @ref{1e6,,base64.z85encode()} and @ref{1f3,,base64.z85decode()}
support encoding and decoding Z85 data@footnote{https://rfc.zeromq.org/spec/32/}.

@item 
The @ref{29,,copy} module now has a @ref{45a,,copy.replace()} function,
with support for many builtin types and any class defining
the @ref{68b,,__replace__()} method.

@item 
The new @ref{38,,dbm.sqlite3} module is now the default @ref{34,,dbm} backend.

@item 
The @ref{a5,,os} module has a @ref{68c,,suite of new functions}
for working with Linux’s timer notification file descriptors.

@item 
The @ref{c0,,random} module now has a @ref{68d,,command-line interface}.
@end itemize

Security improvements:


@itemize *

@item 
@ref{68e,,ssl.create_default_context()} sets @ref{68f,,ssl.VERIFY_X509_PARTIAL_CHAIN}
and @ref{690,,ssl.VERIFY_X509_STRICT} as default flags.
@end itemize

C API improvements:


@itemize *

@item 
The @ref{691,,Py_mod_gil} slot is now used to indicate that
an extension module supports running with the @ref{411,,GIL} disabled.

@item 
The @ref{692,,PyTime C API} has been added,
providing access to system clocks.

@item 
@ref{693,,PyMutex} is a new lightweight mutex that occupies a single byte.

@item 
There is a new @ref{694,,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

New typing features:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 696
PEP 696@footnote{https://peps.python.org/pep-0696/}: Type parameters (@ref{294,,typing.TypeVar}, @ref{295,,typing.ParamSpec},
and @ref{293,,typing.TypeVarTuple}) now support defaults.

@item 
@geindex Python Enhancement Proposals; PEP 702
PEP 702@footnote{https://peps.python.org/pep-0702/}: The new @ref{695,,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{696,,typing.ReadOnly} can be used to mark an item of a
@ref{290,,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{697,,typing.TypeIs} provides more intuitive
type narrowing behavior, as an alternative to @ref{698,,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{699,,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{699,,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{682,,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{69a,,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 New Features,Other Language Changes,Summary – Release Highlights,What’s New In Python 3 13
@anchor{whatsnew/3 13 new-features}@anchor{69b}
@subsection New Features


@menu
* A better interactive interpreter:: 
* Improved error messages: Improved error messages<3>. 
* 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<3>,,New Features
@anchor{whatsnew/3 13 a-better-interactive-interpreter}@anchor{69c}
@subsubsection A better interactive interpreter


Python now uses a new @ref{451,,interactive} shell by default, based on code
from the PyPy project@footnote{https://pypy.org/}.
When the user starts the @ref{69d,,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{1af,,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{69e,,>>>} and @ref{69f,,…} 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 μεταβλητή περιβάλλοντος; PYTHON_BASIC_REPL
@ref{452,,PYTHON_BASIC_REPL} environment variable.
For more on interactive mode, see @ref{6a0,,Διαδραστική Λειτουργία}.

(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<3>,Free-threaded CPython,A better interactive interpreter,New Features
@anchor{whatsnew/3 13 improved-error-messages}@anchor{6a1}@anchor{whatsnew/3 13 whatsnew313-improved-error-messages}@anchor{684}
@subsubsection Improved error messages



@itemize *

@item 
The interpreter now uses color by default when displaying tracebacks in the
terminal. This feature @ref{1af,,can be controlled}
via the new 
@geindex PYTHON_COLORS
@geindex μεταβλητή περιβάλλοντος; PYTHON_COLORS
@ref{687,,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}.)

@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<3>,New Features
@anchor{whatsnew/3 13 free-threaded-cpython}@anchor{6a2}
@subsubsection Free-threaded CPython


CPython now has experimental support for running in a free-threaded mode,
with the @ref{685,,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{6a3,,Windows}
and @ref{6a4,,macOS} installers,
or CPython can be built from source with the @ref{6a5,,--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 μεταβλητή περιβάλλοντος; PYTHON_GIL
@ref{6a6,,PYTHON_GIL} or
the command-line option @ref{178,,-X gil=1}.

To check if the current interpreter supports free-threading, @ref{6a7,,python -VV}
and @ref{6a8,,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{411,,GIL} disabled should
use the @ref{691,,Py_mod_gil} slot. Extensions using single-phase init should
use @ref{6a9,,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 μεταβλητή περιβάλλοντος; PYTHON_GIL
@ref{6a6,,PYTHON_GIL} environment variable or the
@ref{178,,-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 Δείτε επίσης


@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,New Features
@anchor{whatsnew/3 13 an-experimental-just-in-time-jit-compiler}@anchor{6aa}
@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{6ab,,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 Δείτε επίσης


@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,New Features
@anchor{whatsnew/3 13 defined-mutation-semantics-for-locals}@anchor{6ac}@anchor{whatsnew/3 13 whatsnew313-locals-semantics}@anchor{681}
@subsubsection Defined mutation semantics for @code{locals()}


Historically, the expected result of mutating the return value of
@ref{28b,,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{6ad,,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{28b,,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{185,,exec()} and @ref{184,,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{6ae,,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{28d,,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{6af,,Python APIs} and @ref{6b0,,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,New Features
@anchor{whatsnew/3 13 support-for-mobile-platforms}@anchor{6b1}@anchor{whatsnew/3 13 whatsnew313-platform-support}@anchor{699}
@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 Δείτε επίσης


@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 Other Language Changes,New Modules,New Features,What’s New In Python 3 13
@anchor{whatsnew/3 13 other-language-changes}@anchor{6b2}
@subsection Other Language Changes



@itemize *

@item 
The compiler now strips common leading whitespace
from every line in a docstring.
This reduces the size of the @ref{6b3,,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{3d,,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{6b4,,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{670,,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{6b5,,global} declarations are now permitted in @ref{447,,except} blocks
when that global is used in the @ref{320,,else} block.
Previously this raised an erroneous @ref{17e,,SyntaxError}.
(Contributed by Irit Katriel in gh-111123@footnote{https://github.com/python/cpython/issues/111123}.)

@item 
Add 
@geindex PYTHON_FROZEN_MODULES
@geindex μεταβλητή περιβάλλοντος; PYTHON_FROZEN_MODULES
@ref{6b6,,PYTHON_FROZEN_MODULES}, a new environment variable that
determines whether frozen modules are ignored by the import machinery,
equivalent to the @ref{178,,-X frozen_modules} command-line option.
(Contributed by Yilei Yang in gh-111374@footnote{https://github.com/python/cpython/issues/111374}.)

@item 
Add @ref{6b7,,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 μεταβλητή περιβάλλοντος; PYTHON_PERF_JIT_SUPPORT
@ref{6b8,,PYTHON_PERF_JIT_SUPPORT}
and command-line option @ref{178,,-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 μεταβλητή περιβάλλοντος; PYTHON_HISTORY
@ref{6b9,,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{688,,__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{185,,exec()} and @ref{184,,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{1c8,,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{6ba,,__name__} attribute on @ref{6bb,,property} objects.
(Contributed by Eugene Toder in gh-101860@footnote{https://github.com/python/cpython/issues/101860}.)

@item 
Add @ref{68a,,PythonFinalizationError}, a new exception derived from
@ref{30d,,RuntimeError} and used to signal when operations are blocked
during @ref{1a0,,finalization}.
The following callables now raise @code{PythonFinalizationError},
instead of @code{RuntimeError}:


@itemize *

@item 
@ref{6bc,,_thread.start_new_thread()}

@item 
@ref{6bd,,os.fork()}

@item 
@ref{6be,,os.forkpty()}

@item 
@ref{6bf,,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{6c0,,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{14,,bz2}, @ref{8d,,lzma}, @ref{e7,,tarfile}, and @ref{13a,,zipfile} modules.
(Contributed by Serhiy Storchaka in gh-115961@footnote{https://github.com/python/cpython/issues/115961}.)
@end itemize

@node New Modules,Improved Modules,Other Language Changes,What’s New In Python 3 13
@anchor{whatsnew/3 13 new-modules}@anchor{6c1}
@subsection New Modules



@itemize *

@item 
@ref{38,,dbm.sqlite3}: An SQLite backend for @ref{34,,dbm}.
(Contributed by Raymond Hettinger and Erlend E. Aasland in gh-100414@footnote{https://github.com/python/cpython/issues/100414}.)
@end itemize

@node Improved Modules,Optimizations<4>,New Modules,What’s New In Python 3 13
@anchor{whatsnew/3 13 improved-modules}@anchor{6c2}
@subsection Improved Modules


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

@end menu

@node argparse<4>,array<2>,,Improved Modules
@anchor{whatsnew/3 13 argparse}@anchor{6c3}
@subsubsection argparse



@itemize *

@item 
Add the `deprecated' parameter to the
@ref{3ed,,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<2>,ast<5>,argparse<4>,Improved Modules
@anchor{whatsnew/3 13 array}@anchor{6c4}
@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{6c5,,array.array} as a @ref{6c6,,MutableSequence}
by implementing the @ref{6c7,,clear()} method.
(Contributed by Mike Zimin in gh-114894@footnote{https://github.com/python/cpython/issues/114894}.)
@end itemize

@node ast<5>,asyncio<5>,array<2>,Improved Modules
@anchor{whatsnew/3 13 ast}@anchor{6c8}
@subsubsection ast



@itemize *

@item 
The constructors of node types in the @ref{9,,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{6c9,,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{2c9,,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{2ec,,ast.AST}
unless the class opts in to the new behavior
by defining the @ref{6ca,,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{1c9,,ast.parse()} now accepts an optional argument `optimize'
which is passed on to @ref{1c8,,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<5>,base64<3>,ast<5>,Improved Modules
@anchor{whatsnew/3 13 asyncio}@anchor{6cb}
@subsubsection asyncio



@itemize *

@item 
@ref{6cc,,asyncio.as_completed()} now returns an object that is both an
@ref{6cd,,asynchronous iterator} and a plain @ref{6ce,,iterator}
of @ref{6cf,,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{6d0,,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{6d1,,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{6d2,,Queue.shutdown}
and @ref{6d3,,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{6d4,,Server.close_clients()} and @ref{6d5,,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{6d6,,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{6d7,,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{6d8,,ExceptionGroup},
it will now call the parent task’s @ref{6d9,,cancel()} method.
This ensures that a @ref{6da,,CancelledError} will be raised
at the next @ref{432,,await}, so the cancellation is not lost.

An added benefit of these changes is that task groups now preserve
the cancellation count (@ref{6db,,cancelling()}).

In order to handle some corner cases, @ref{6dc,,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{464,,TaskGroup.create_task()} is called on an inactive
@ref{6d7,,TaskGroup}, the given coroutine will be closed (which
prevents a @ref{6dd,,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}.)

@item 
The function and methods named @code{create_task} have received a new
@code{**kwargs} argument that is passed through to the task constructor.
This change was accidentally added in 3.13.3,
and broke the API contract for custom task factories.
Several third-party task factories implemented workarounds for this.
In 3.13.4 and later releases the old factory contract is honored
once again (until 3.14).
To keep the workarounds working, the extra @code{**kwargs} argument still
allows passing additional keyword arguments to @ref{460,,Task}
and to custom task factories.

This affects the following function and methods:
@ref{462,,asyncio.create_task()},
@ref{463,,asyncio.loop.create_task()},
@ref{464,,asyncio.TaskGroup.create_task()}.
(Contributed by Thomas Grainger in gh-128307@footnote{https://github.com/python/cpython/issues/128307}.)
@end itemize

@node base64<3>,compileall,asyncio<5>,Improved Modules
@anchor{whatsnew/3 13 base64}@anchor{6de}
@subsubsection base64



@itemize *

@item 
Add @ref{1e6,,z85encode()} and @ref{1f3,,z85decode()} functions
for encoding @ref{1c7,,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<3>,base64<3>,Improved Modules
@anchor{whatsnew/3 13 compileall}@anchor{6df}
@subsubsection compileall



@itemize *

@item 
The default number of worker threads and processes is now selected using
@ref{6e0,,os.process_cpu_count()} instead of @ref{6e1,,os.cpu_count()}.
(Contributed by Victor Stinner in gh-109649@footnote{https://github.com/python/cpython/issues/109649}.)
@end itemize

@node concurrent futures<3>,configparser<2>,compileall,Improved Modules
@anchor{whatsnew/3 13 concurrent-futures}@anchor{6e2}
@subsubsection concurrent.futures



@itemize *

@item 
The default number of worker threads and processes is now selected using
@ref{6e0,,os.process_cpu_count()} instead of @ref{6e1,,os.cpu_count()}.
(Contributed by Victor Stinner in gh-109649@footnote{https://github.com/python/cpython/issues/109649}.)
@end itemize

@node configparser<2>,copy,concurrent futures<3>,Improved Modules
@anchor{whatsnew/3 13 configparser}@anchor{6e3}
@subsubsection configparser



@itemize *

@item 
@ref{6e4,,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<3>,configparser<2>,Improved Modules
@anchor{whatsnew/3 13 copy}@anchor{6e5}
@subsubsection copy



@itemize *

@item 
The new @ref{45a,,replace()} function and the @ref{68b,,replace protocol} make creating modified copies of objects much simpler.
This is especially useful when working with immutable objects.
The following types support the @code{replace()} function
and implement the replace protocol:


@itemize *

@item 
@ref{1cf,,collections.namedtuple()}

@item 
@ref{6e6,,dataclasses.dataclass}

@item 
@ref{6e7,,datetime.datetime}, @ref{48d,,datetime.date}, @ref{48e,,datetime.time}

@item 
@ref{6e8,,inspect.Signature}, @ref{6e9,,inspect.Parameter}

@item 
@ref{6ea,,types.SimpleNamespace}

@item 
@ref{6eb,,code objects}
@end itemize

Any user-defined class can also support @ref{45a,,copy.replace()} by defining
the @ref{68b,,__replace__()} method.
(Contributed by Serhiy Storchaka in gh-108751@footnote{https://github.com/python/cpython/issues/108751}.)
@end itemize

@node ctypes<3>,dbm<2>,copy,Improved Modules
@anchor{whatsnew/3 13 ctypes}@anchor{6ec}
@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{47c,,ctypes.Structure} objects have a new @ref{6ed,,_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<2>,dis<2>,ctypes<3>,Improved Modules
@anchor{whatsnew/3 13 dbm}@anchor{6ee}
@subsubsection dbm



@itemize *

@item 
Add @ref{38,,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 @code{clear()} methods of the GDBM and NDBM database objects.
(Contributed by Donghee Na in gh-107122@footnote{https://github.com/python/cpython/issues/107122}.)
@end itemize

@node dis<2>,doctest,dbm<2>,Improved Modules
@anchor{whatsnew/3 13 dis}@anchor{6ef}
@subsubsection dis



@itemize *

@item 
Change the output of @ref{3b,,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{6f0,,-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{6f1,,get_instructions()} no longer represents cache entries
as separate instructions.
Instead, it returns them as part of the @ref{494,,Instruction},
in the new `cache_info' field.
The `show_caches' argument to @code{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<3>,dis<2>,Improved Modules
@anchor{whatsnew/3 13 doctest}@anchor{6f2}@anchor{whatsnew/3 13 whatsnew313-doctest}@anchor{686}
@subsubsection doctest



@itemize *

@item 
@ref{3d,,doctest} output is now colored by default.
This can be controlled via the new 
@geindex PYTHON_COLORS
@geindex μεταβλητή περιβάλλοντος; PYTHON_COLORS
@ref{687,,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{1af,,Controlling color}.
(Contributed by Hugo van Kemenade in gh-117225@footnote{https://github.com/python/cpython/issues/117225}.)

@item 
The @ref{6f3,,DocTestRunner.run()} method now counts the number of skipped tests.
Add the @ref{6f4,,DocTestRunner.skips} and @ref{6f5,,TestResults.skipped} attributes.
(Contributed by Victor Stinner in gh-108794@footnote{https://github.com/python/cpython/issues/108794}.)
@end itemize

@node email<3>,enum,doctest,Improved Modules
@anchor{whatsnew/3 13 email}@anchor{6f6}
@subsubsection email



@itemize *

@item 
Headers with embedded newlines are now quoted on output.
The @ref{43,,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{6f7,,verify_generated_headers}.
(Contributed by Bas Bloemsaat and Petr Viktorin in gh-121650@footnote{https://github.com/python/cpython/issues/121650}.)

@item 
@ref{6f8,,getaddresses()} and @ref{6f9,,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<2>,email<3>,Improved Modules
@anchor{whatsnew/3 13 enum}@anchor{6fa}
@subsubsection enum



@itemize *

@item 
@ref{6fb,,EnumDict} has been made public to better support subclassing
@ref{6fc,,EnumType}.
@end itemize

@node fractions<2>,glob<2>,enum,Improved Modules
@anchor{whatsnew/3 13 fractions}@anchor{6fd}
@subsubsection fractions



@itemize *

@item 
@ref{1c3,,Fraction} objects now support the standard
@ref{6fe,,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<2>,importlib,fractions<2>,Improved Modules
@anchor{whatsnew/3 13 glob}@anchor{6ff}
@subsubsection glob



@itemize *

@item 
Add @ref{700,,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<3>,glob<2>,Improved Modules
@anchor{whatsnew/3 13 importlib}@anchor{701}
@subsubsection importlib



@itemize *

@item 
The following functions in @ref{7e,,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{702,,is_resource()}

@item 
@ref{703,,open_binary()}

@item 
@ref{704,,open_text()}

@item 
@ref{705,,path()}

@item 
@ref{706,,read_binary()}

@item 
@ref{707,,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{708,,contents()} remains deprecated in favor of
the fully-featured @ref{572,,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<3>,ipaddress,importlib,Improved Modules
@anchor{whatsnew/3 13 io}@anchor{709}
@subsubsection io



@itemize *

@item 
The @ref{70a,,IOBase} finalizer now logs any errors raised by
the @ref{70b,,close()} method with @ref{70c,,sys.unraisablehook}.
Previously, errors were ignored silently by default,
and only logged in @ref{70d,,Python Development Mode}
or when using a @ref{3dc,,Python debug build}.
(Contributed by Victor Stinner in gh-62948@footnote{https://github.com/python/cpython/issues/62948}.)
@end itemize

@node ipaddress,itertools<2>,io<3>,Improved Modules
@anchor{whatsnew/3 13 ipaddress}@anchor{70e}
@subsubsection ipaddress



@itemize *

@item 
Add the @ref{70f,,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{710,,IPv4Address}, @ref{711,,IPv6Address},
@ref{712,,IPv4Network}, and @ref{713,,IPv6Network}.
(Contributed by Jakub Stasiak in gh-113171@footnote{https://github.com/python/cpython/issues/113171}.)
@end itemize

@node itertools<2>,marshal,ipaddress,Improved Modules
@anchor{whatsnew/3 13 itertools}@anchor{714}
@subsubsection itertools



@itemize *

@item 
@ref{715,,batched()} has a new `strict' parameter,
which raises a @ref{277,,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<3>,itertools<2>,Improved Modules
@anchor{whatsnew/3 13 marshal}@anchor{716}
@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<3>,mimetypes<3>,marshal,Improved Modules
@anchor{whatsnew/3 13 math}@anchor{717}
@subsubsection math



@itemize *

@item 
The new function @ref{718,,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<3>,mmap<2>,math<3>,Improved Modules
@anchor{whatsnew/3 13 mimetypes}@anchor{719}
@subsubsection mimetypes



@itemize *

@item 
Add the @ref{71a,,guess_file_type()} function to guess a MIME type
from a filesystem path.
Using paths with @ref{71b,,guess_type()} is now @ref{1a7,,soft deprecated}.
(Contributed by Serhiy Storchaka in gh-66543@footnote{https://github.com/python/cpython/issues/66543}.)
@end itemize

@node mmap<2>,multiprocessing<2>,mimetypes<3>,Improved Modules
@anchor{whatsnew/3 13 mmap}@anchor{71c}
@subsubsection mmap



@itemize *

@item 
@ref{23c,,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{23c,,mmap} has a new @ref{71d,,seekable()} method
that can be used when a seekable file-like object is required.
The @ref{71e,,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{23c,,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<2>,os<3>,mmap<2>,Improved Modules
@anchor{whatsnew/3 13 multiprocessing}@anchor{71f}
@subsubsection multiprocessing



@itemize *

@item 
The default number of worker threads and processes is now selected using
@ref{6e0,,os.process_cpu_count()} instead of @ref{6e1,,os.cpu_count()}.
(Contributed by Victor Stinner in gh-109649@footnote{https://github.com/python/cpython/issues/109649}.)
@end itemize

@node os<3>,os path<3>,multiprocessing<2>,Improved Modules
@anchor{whatsnew/3 13 os}@anchor{720}
@subsubsection os



@itemize *

@item 
Add @ref{6e0,,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{6e1,,cpu_count()} and @ref{6e0,,process_cpu_count()} can be overridden
through the new environment variable 
@geindex PYTHON_CPU_COUNT
@geindex μεταβλητή περιβάλλοντος; PYTHON_CPU_COUNT
@ref{721,,PYTHON_CPU_COUNT}
or the new command-line option @ref{178,,-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{68c,,low level interface} to Linux’s
@code{timer file descriptors@footnote{https://manpages.debian.org/timerfd_create(2)}}
via @ref{722,,timerfd_create()},
@ref{723,,timerfd_settime()}, @ref{724,,timerfd_settime_ns()},
@ref{725,,timerfd_gettime()}, @ref{726,,timerfd_gettime_ns()},
@ref{727,,TFD_NONBLOCK}, @ref{728,,TFD_CLOEXEC},
@ref{729,,TFD_TIMER_ABSTIME}, and @ref{72a,,TFD_TIMER_CANCEL_ON_SET}
(Contributed by Masaru Tsuchiyama in gh-108277@footnote{https://github.com/python/cpython/issues/108277}.)

@item 
@ref{72b,,lchmod()} and the `follow_symlinks' argument of @ref{72c,,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{72d,,fchmod()} and support for file descriptors in @ref{72c,,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{72e,,mkdir()} and @ref{72f,,makedirs()} now support passing
a `mode' value of @code{0o700} to apply access control to the new directory.
This implicitly affects @ref{730,,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{731,,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{731,,posix_spawn()} can now use the @ref{732,,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<3>,pathlib<5>,os<3>,Improved Modules
@anchor{whatsnew/3 13 os-path}@anchor{733}
@subsubsection os.path



@itemize *

@item 
Add @ref{2d9,,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{734,,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{241,,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<5>,pdb<4>,os path<3>,Improved Modules
@anchor{whatsnew/3 13 pathlib}@anchor{735}
@subsubsection pathlib



@itemize *

@item 
Add @ref{736,,UnsupportedOperation}, which is raised instead of
@ref{59a,,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{4ee,,Path} objects
from “file” URIs (@code{file:///}), @ref{737,,Path.from_uri()}.
(Contributed by Barney Gale in gh-107465@footnote{https://github.com/python/cpython/issues/107465}.)

@item 
Add @ref{738,,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{739,,PurePath.parser} class attribute to store the
implementation of @ref{a6,,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{73a,,Path.glob()} and @ref{73b,,rglob()}.
(Contributed by Barney Gale in gh-77609@footnote{https://github.com/python/cpython/issues/77609}.)

@item 
@ref{73a,,Path.glob()} and @ref{73b,,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{73c,,Path.is_file},
@ref{73d,,Path.is_dir},
@ref{73e,,Path.owner()}, and @ref{73f,,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<4>,queue,pathlib<5>,Improved Modules
@anchor{whatsnew/3 13 pdb}@anchor{740}
@subsubsection pdb



@itemize *

@item 
@ref{4f9,,breakpoint()} and @ref{4fa,,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{741,,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{139,,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{742,,pm()} using
the new @ref{743,,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<4>,Improved Modules
@anchor{whatsnew/3 13 queue}@anchor{744}
@subsubsection queue



@itemize *

@item 
Add @ref{745,,Queue.shutdown} and @ref{746,,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<3>,queue,Improved Modules
@anchor{whatsnew/3 13 random}@anchor{747}
@subsubsection random



@itemize *

@item 
Add a @ref{68d,,command-line interface}.
(Contributed by Hugo van Kemenade in gh-118131@footnote{https://github.com/python/cpython/issues/118131}.)
@end itemize

@node re<3>,shutil,random,Improved Modules
@anchor{whatsnew/3 13 re}@anchor{748}
@subsubsection re



@itemize *

@item 
Rename @code{re.error} to @ref{749,,PatternError} for improved clarity.
@code{re.error} is kept for backward compatibility.
@end itemize

@node shutil,site,re<3>,Improved Modules
@anchor{whatsnew/3 13 shutil}@anchor{74a}
@subsubsection shutil



@itemize *

@item 
Support the `dir_fd' and `follow_symlinks' keyword arguments
in @ref{74b,,chown()}.
(Contributed by Berker Peksag and Tahia K in gh-62308@footnote{https://github.com/python/cpython/issues/62308})
@end itemize

@node site,sqlite3<3>,shutil,Improved Modules
@anchor{whatsnew/3 13 site}@anchor{74c}
@subsubsection site



@itemize *

@item 
@code{.pth} files are now decoded using UTF-8 first,
and then with the @ref{74d,,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<3>,ssl<3>,site,Improved Modules
@anchor{whatsnew/3 13 sqlite3}@anchor{74e}
@subsubsection sqlite3



@itemize *

@item 
A @ref{74f,,ResourceWarning} is now emitted if a @ref{3df,,Connection}
object is not @ref{750,,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{751,,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<3>,statistics,sqlite3<3>,Improved Modules
@anchor{whatsnew/3 13 ssl}@anchor{752}
@subsubsection ssl



@itemize *

@item 
The @ref{68e,,create_default_context()} API now includes
@ref{68f,,VERIFY_X509_PARTIAL_CHAIN} and @ref{690,,VERIFY_X509_STRICT}
in its default flags.

@cartouche
@quotation Σημείωση 
@ref{690,,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<2>,ssl<3>,Improved Modules
@anchor{whatsnew/3 13 statistics}@anchor{753}
@subsubsection statistics



@itemize *

@item 
Add @ref{754,,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{755,,kde_random()} for sampling from an
estimated probability density function created by @ref{754,,kde()}.
(Contributed by Raymond Hettinger in gh-115863@footnote{https://github.com/python/cpython/issues/115863}.)
@end itemize

@node subprocess<2>,sys<3>,statistics,Improved Modules
@anchor{whatsnew/3 13 subprocess}@anchor{756}@anchor{whatsnew/3 13 whatsnew313-subprocess}@anchor{757}
@subsubsection subprocess



@itemize *

@item 
The @ref{df,,subprocess} module now uses the @ref{731,,posix_spawn()} function in
more situations.

Notably, when `close_fds' is @code{True} (the default),
@ref{731,,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{df,,subprocess}
to never use @ref{731,,posix_spawn()}.
Please report your reason and platform details in
the @ref{758,,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<3>,tempfile,subprocess<2>,Improved Modules
@anchor{whatsnew/3 13 sys}@anchor{759}
@subsubsection sys



@itemize *

@item 
Add the @ref{75a,,_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<3>,Improved Modules
@anchor{whatsnew/3 13 tempfile}@anchor{75b}
@subsubsection tempfile



@itemize *

@item 
On Windows, the default mode @code{0o700} used by @ref{730,,tempfile.mkdtemp()} now
limits access to the new directory due to changes to @ref{72e,,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<3>,tempfile,Improved Modules
@anchor{whatsnew/3 13 time}@anchor{75c}
@subsubsection time



@itemize *

@item 
On Windows, @ref{75d,,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{75e,,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<3>,traceback,time,Improved Modules
@anchor{whatsnew/3 13 tkinter}@anchor{75f}
@subsubsection tkinter



@itemize *

@item 
Add @ref{f9,,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{f9,,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{188,,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{326,,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{760,,element_create()} method of
@ref{761,,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<4>,tkinter<3>,Improved Modules
@anchor{whatsnew/3 13 traceback}@anchor{762}
@subsubsection traceback



@itemize *

@item 
Add the @ref{763,,exc_type_str} attribute
to @ref{764,,TracebackException},
which holds a string display of the `exc_type'.
Deprecate the @ref{765,,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{766,,TracebackException.format_exception_only()} to (recursively) format
the nested exceptions of a @ref{767,,BaseExceptionGroup} instance.
(Contributed by Irit Katriel in gh-105292@footnote{https://github.com/python/cpython/issues/105292}.)
@end itemize

@node types<4>,typing<4>,traceback,Improved Modules
@anchor{whatsnew/3 13 types}@anchor{768}
@subsubsection types



@itemize *

@item 
@ref{6ea,,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<4>,unicodedata<3>,types<4>,Improved Modules
@anchor{whatsnew/3 13 typing}@anchor{769}
@subsubsection typing



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 705
PEP 705@footnote{https://peps.python.org/pep-0705/}: Add @ref{696,,ReadOnly}, a special typing construct
to mark a @ref{290,,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{697,,TypeIs}, a typing construct
that can be used to instruct a type checker how to narrow a type.

@item 
Add @ref{76a,,NoDefault}, a sentinel object used to represent
the defaults of some parameters in the @ref{10d,,typing} module.
(Contributed by Jelle Zijlstra in gh-116126@footnote{https://github.com/python/cpython/issues/116126}.)

@item 
Add @ref{76b,,get_protocol_members()} to return the set of members
defining a @ref{76c,,typing.Protocol}.
(Contributed by Jelle Zijlstra in gh-104873@footnote{https://github.com/python/cpython/issues/104873}.)

@item 
Add @ref{76d,,is_protocol()} to check whether a class
is a @ref{76c,,Protocol}.
(Contributed by Jelle Zijlstra in gh-104873@footnote{https://github.com/python/cpython/issues/104873}.)

@item 
@ref{76e,,ClassVar} can now be nested in @ref{76f,,Final},
and vice versa.
(Contributed by Mehdi Drissi in gh-89547@footnote{https://github.com/python/cpython/issues/89547}.)
@end itemize

@node unicodedata<3>,venv<2>,typing<4>,Improved Modules
@anchor{whatsnew/3 13 unicodedata}@anchor{770}
@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<2>,warnings<2>,unicodedata<3>,Improved Modules
@anchor{whatsnew/3 13 venv}@anchor{771}
@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{772,,EnvBuilder} and @ref{773,,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<2>,xml<2>,venv<2>,Improved Modules
@anchor{whatsnew/3 13 warnings}@anchor{774}
@subsubsection warnings



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 702
PEP 702@footnote{https://peps.python.org/pep-0702/}: The new @ref{695,,warnings.deprecated()} decorator provides a way to
communicate deprecations to a @ref{775,,static type checker}
and to warn on usage of deprecated classes and functions.
A @ref{2c9,,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<2>,zipimport<2>,warnings<2>,Improved Modules
@anchor{whatsnew/3 13 xml}@anchor{776}
@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{777,,xml.etree.ElementTree.XMLParser.flush()}

@item 
@ref{778,,xml.etree.ElementTree.XMLPullParser.flush()}

@item 
@ref{779,,xml.parsers.expat.xmlparser.GetReparseDeferralEnabled()}

@item 
@ref{77a,,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{3eb,,iterparse()} for explicit cleanup.
(Contributed by Serhiy Storchaka in gh-69893@footnote{https://github.com/python/cpython/issues/69893}.)
@end itemize

@node zipimport<2>,,xml<2>,Improved Modules
@anchor{whatsnew/3 13 zipimport}@anchor{77b}
@subsubsection 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 Optimizations<4>,Removed Modules And APIs,Improved Modules,What’s New In Python 3 13
@anchor{whatsnew/3 13 optimizations}@anchor{77c}
@subsection Optimizations



@itemize *

@item 
Several standard library modules have had
their import times significantly improved.
For example, the import time of the @ref{10d,,typing} module
has been reduced by around a third by removing dependencies
on @ref{c1,,re} and @ref{27,,contextlib}.
Other modules to enjoy import-time speedups include
@ref{53,,email.utils}, @ref{59,,enum}, @ref{62,,functools},
@ref{7d,,importlib.metadata}, and @ref{f6,,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{77d,,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{df,,subprocess} module now uses the @ref{731,,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{757,,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,Optimizations<4>,What’s New In Python 3 13
@anchor{whatsnew/3 13 removed-modules-and-apis}@anchor{77e}
@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<3>. 
* importlib.metadata: importlib metadata. 
* locale: locale<2>. 
* opcode:: 
* optparse:: 
* pathlib: pathlib<6>. 
* re: re<4>. 
* tkinter.tix: tkinter tix. 
* turtle: turtle<2>. 
* typing: typing<5>. 
* unittest: unittest<3>. 
* urllib: urllib<3>. 
* webbrowser: webbrowser<3>. 

@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{77f}
@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}


@itemize *

@item 
standard-aifc@footnote{https://pypi.org/project/standard-aifc/}:
Use the redistribution of @code{aifc} library from PyPI.
@end itemize

@item 
@code{audioop}


@itemize *

@item 
audioop-lts@footnote{https://pypi.org/project/audioop-lts/}:
Use @code{audioop-lts} library from PyPI.
@end itemize

@item 
@code{chunk}


@itemize *

@item 
standard-chunk@footnote{https://pypi.org/project/standard-chunk/}:
Use the redistribution of @code{chunk} library from PyPI.
@end itemize

@item 
@code{cgi} and @code{cgitb}


@itemize *

@item 
@code{cgi.FieldStorage} can typically be replaced with
@ref{588,,urllib.parse.parse_qsl()} for @code{GET} and @code{HEAD} requests,
and the @ref{47,,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{589,,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{3e,,email} package, which implements the same MIME RFCs.
For example, with @ref{216,,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{3e,,email} package, which implements the same MIME RFCs,
or with the multipart@footnote{https://pypi.org/project/multipart/} library.
For example, the @ref{216,,email.message.EmailMessage}
and @ref{780,,email.message.Message} classes.

@item 
standard-cgi@footnote{https://pypi.org/project/standard-cgi/}: and standard-cgitb@footnote{https://pypi.org/project/standard-cgitb/}:
Use the redistribution of @code{cgi} and @code{cgitb} library from PyPI.
@end itemize

@item 
@code{crypt} and the private @code{_crypt} extension.
The @ref{6b,,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 
argon2-cffi@footnote{https://pypi.org/project/argon2-cffi/}:
The secure Argon2 password hashing algorithm.

@item 
legacycrypt@footnote{https://pypi.org/project/legacycrypt/}:
@ref{2d,,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.

@item 
standard-crypt@footnote{https://pypi.org/project/standard-crypt/} and deprecated-crypt-alternative@footnote{https://pypi.org/project/deprecated-crypt-alternative/}:
Use the redistribution of @code{crypt} and reimplementation of @code{_crypt} libraries from PyPI.
@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}.


@itemize *

@item 
standard-imghdr@footnote{https://pypi.org/project/standard-imghdr/}:
Use the redistribution of @code{imghdr} library from PyPI.
@end itemize

@item 
@code{mailcap}:
Use the @ref{93,,mimetypes} module instead.


@itemize *

@item 
standard-mailcap@footnote{https://pypi.org/project/standard-mailcap/}:
Use the redistribution of @code{mailcap} library from PyPI.
@end itemize

@item 
@code{msilib}

@item 
@code{nis}

@item 
@code{nntplib}:
Use the pynntp@footnote{https://pypi.org/project/pynntp/} library from PyPI instead.


@itemize *

@item 
standard-nntplib@footnote{https://pypi.org/project/standard-nntplib/}:
Use the redistribution of @code{nntplib} library from PyPI.
@end itemize

@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{df,,subprocess} module instead.
Use @ref{781,,shlex.quote()} to replace the undocumented @code{pipes.quote}
function.


@itemize *

@item 
standard-pipes@footnote{https://pypi.org/project/standard-pipes/}:
Use the redistribution of @code{pipes} library from PyPI.
@end itemize

@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.


@itemize *

@item 
standard-sndhdr@footnote{https://pypi.org/project/standard-sndhdr/}:
Use the redistribution of @code{sndhdr} library from PyPI.
@end itemize

@item 
@code{spwd}:
Use the python-pam@footnote{https://pypi.org/project/python-pam/} library from PyPI instead.

@item 
@code{sunau}


@itemize *

@item 
standard-sunau@footnote{https://pypi.org/project/standard-sunau/}:
Use the redistribution of @code{sunau} library from PyPI.
@end itemize

@item 
@code{telnetlib},
Use the telnetlib3@footnote{https://pypi.org/project/telnetlib3/} or Exscript@footnote{https://pypi.org/project/Exscript/} libraries from PyPI instead.


@itemize *

@item 
standard-telnetlib@footnote{https://pypi.org/project/standard-telnetlib/}:
Use the redistribution of @code{telnetlib} library from PyPI.
@end itemize

@item 
@code{uu}:
Use the @ref{f,,base64} module instead, as a modern alternative.


@itemize *

@item 
standard-uu@footnote{https://pypi.org/project/standard-uu/}:
Use the redistribution of @code{uu} library from PyPI.
@end itemize

@item 
@code{xdrlib}


@itemize *

@item 
standard-xdrlib@footnote{https://pypi.org/project/standard-xdrlib/}:
Use the redistribution of @code{xdrlib} library from PyPI.
@end itemize
@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{782}
@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<3>,2to3,Removed Modules And APIs
@anchor{whatsnew/3 13 builtins}@anchor{783}
@subsubsection builtins



@itemize *

@item 
Remove support for chained @ref{69a,,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{6bb,,property}.
The core design of this feature was flawed and led to several problems.
To «pass-through» a @code{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{30d,,RuntimeError} when calling @ref{784,,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<3>,importlib metadata,builtins,Removed Modules And APIs
@anchor{whatsnew/3 13 id3}@anchor{785}
@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<2>,configparser<3>,Removed Modules And APIs
@anchor{whatsnew/3 13 importlib-metadata}@anchor{786}
@subsubsection importlib.metadata



@itemize *

@item 
Remove deprecated subscript (@ref{787,,__getitem__()}) access for
@ref{788,,EntryPoint} objects.
(Contributed by Jason R. Coombs in gh-113175@footnote{https://github.com/python/cpython/issues/113175}.)
@end itemize

@node locale<2>,opcode,importlib metadata,Removed Modules And APIs
@anchor{whatsnew/3 13 locale}@anchor{789}
@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<2>,Removed Modules And APIs
@anchor{whatsnew/3 13 opcode}@anchor{78a}
@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{3b,,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<6>,opcode,Removed Modules And APIs
@anchor{whatsnew/3 13 optparse}@anchor{78b}
@subsubsection optparse



@itemize *

@item 
This module is no longer considered @ref{1a7,,soft deprecated}.
While @ref{7,,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<6>,re<4>,optparse,Removed Modules And APIs
@anchor{whatsnew/3 13 id4}@anchor{78c}
@subsubsection pathlib



@itemize *

@item 
Remove the ability to use @ref{4ee,,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<4>,tkinter tix,pathlib<6>,Removed Modules And APIs
@anchor{whatsnew/3 13 id5}@anchor{78d}
@subsubsection 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<2>,re<4>,Removed Modules And APIs
@anchor{whatsnew/3 13 tkinter-tix}@anchor{78e}
@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<2>,typing<5>,tkinter tix,Removed Modules And APIs
@anchor{whatsnew/3 13 turtle}@anchor{78f}
@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<5>,unittest<3>,turtle<2>,Removed Modules And APIs
@anchor{whatsnew/3 13 id6}@anchor{790}
@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{10d,,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{290,,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<3>,urllib<3>,typing<5>,Removed Modules And APIs
@anchor{whatsnew/3 13 unittest}@anchor{791}
@subsubsection unittest



@itemize *

@item 
Remove the following @ref{10f,,unittest} functions, deprecated in Python 3.11:


@itemize *

@item 
@code{unittest.findTestCases()}

@item 
@code{unittest.makeSuite()}

@item 
@code{unittest.getTestCaseNames()}
@end itemize

Use @ref{792,,TestLoader} methods instead:


@itemize *

@item 
@ref{793,,loadTestsFromModule()}

@item 
@ref{794,,loadTestsFromTestCase()}

@item 
@ref{795,,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<3>,webbrowser<3>,unittest<3>,Removed Modules And APIs
@anchor{whatsnew/3 13 urllib}@anchor{796}
@subsubsection urllib



@itemize *

@item 
Remove the `cafile', `capath', and `cadefault' parameters of the
@ref{57f,,urllib.request.urlopen()} function, deprecated in Python 3.6.
Use the `context' parameter instead with an @ref{336,,SSLContext} instance.
The @ref{797,,ssl.SSLContext.load_cert_chain()} function
can be used to load specific certificates,
or let @ref{68e,,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<3>,,urllib<3>,Removed Modules And APIs
@anchor{whatsnew/3 13 webbrowser}@anchor{798}
@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{799,,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{79a}
@subsection New Deprecations



@itemize *

@item 
@ref{79b,,User-defined functions}:


@itemize *

@item 
Deprecate assignment to a function’s @ref{79c,,__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{8,,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{301,,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{2d,,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{1a7,,Soft-deprecate} the @ref{79d,,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{39,,decimal}:


@itemize *

@item 
Deprecate the non-standard and undocumented @ref{1c2,,Decimal}
format specifier @code{'N'},
which is only supported in the @code{decimal} module’s C implementation.
Scheduled to be removed in Python 3.18.
(Contributed by Serhiy Storchaka in gh-89902@footnote{https://github.com/python/cpython/issues/89902}.)
@end itemize

@item 
@ref{3b,,dis}:


@itemize *

@item 
Deprecate the @code{HAVE_ARGUMENT} separator.
Check membership in @ref{79e,,hasarg} instead.
(Contributed by Irit Katriel in gh-109319@footnote{https://github.com/python/cpython/issues/109319}.)
@end itemize

@item 
@ref{66,,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{67,,glob}:


@itemize *

@item 
Deprecate the undocumented @code{glob0()} and @code{glob1()} functions.
Use @ref{2d4,,glob()} and pass a @ref{79f,,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{75,,http.server}:


@itemize *

@item 
Deprecate @code{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{93,,mimetypes}:


@itemize *

@item 
@ref{1a7,,Soft-deprecate} file path arguments
to @ref{71b,,guess_type()},
use @ref{71a,,guess_file_type()} instead.
(Contributed by Serhiy Storchaka in gh-66543@footnote{https://github.com/python/cpython/issues/66543}.)
@end itemize

@item 
@ref{c1,,re}:


@itemize *

@item 
Deprecate passing the optional `maxsplit', `count', or `flags' arguments
as positional arguments to the module-level
@ref{7a0,,split()}, @ref{7a1,,sub()}, and @ref{7a2,,subn()} functions.
These parameters will become @ref{7a3,,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{a8,,pathlib}:


@itemize *

@item 
Deprecate @code{.PurePath.is_reserved()},
to be removed in Python 3.15.
Use @ref{2d9,,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{af,,platform}:


@itemize *

@item 
Deprecate @code{platform.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{bd,,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{d7,,sqlite3}:


@itemize *

@item 
Deprecate passing more than one positional argument to
the @ref{3e0,,connect()} function
and the @ref{3df,,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{3e1,,Connection.create_function()}
and @ref{3e2,,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{3e3,,set_authorizer()},
@ref{3e4,,set_progress_handler()}, and
@ref{3e5,,set_trace_callback()}
@ref{3df,,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{e2,,sys}:


@itemize *

@item 
Deprecate the @ref{30e,,_enablelegacywindowsfsencoding()} function,
to be removed in Python 3.16.
Use the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,PYTHONLEGACYWINDOWSFSENCODING} environment variable instead.
(Contributed by Inada Naoki in gh-73427@footnote{https://github.com/python/cpython/issues/73427}.)
@end itemize

@item 
@ref{e7,,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{107,,traceback}:


@itemize *

@item 
Deprecate the @ref{765,,TracebackException.exc_type} attribute.
Use @ref{763,,TracebackException.exc_type_str} instead.
(Contributed by Irit Katriel in gh-112332@footnote{https://github.com/python/cpython/issues/112332}.)
@end itemize

@item 
@ref{10d,,typing}:


@itemize *

@item 
Deprecate the undocumented keyword argument syntax for creating
@ref{2e4,,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{2e4,,NamedTuple} or @ref{290,,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 @code{typing.no_type_check_decorator()} decorator function,
to be removed in Python 3.15.
After eight years in the @ref{10d,,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{7a4,,typing.AnyStr}.
In Python 3.16, it will be removed from @code{typing.__all__},
and a @ref{2c9,,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{7a5,,type parameter syntax} instead.
(Contributed by Michael The in gh-107116@footnote{https://github.com/python/cpython/issues/107116}.)
@end itemize

@item 
@ref{11c,,wave}:


@itemize *

@item 
Deprecate the @code{getmark()}, @code{setmark()} and @code{getmarkers()} methods of
the @ref{2e6,,Wave_read} and @ref{2e7,,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<3>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<4>. 
* Pending removal in Python 3.17: Pending removal in Python 3 17<3>. 
* Pending removal in Python 3.18: Pending removal in Python 3 18<4>. 
* Pending removal in Python 3.19: Pending removal in Python 3 19<3>. 
* Pending removal in Python 3.20: Pending removal in Python 3 20<3>. 
* Pending removal in future versions: Pending removal in future versions<4>. 

@end menu

@node Pending removal in Python 3 14,Pending removal in Python 3 15<3>,,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-14}@anchor{7a6}
@subsubsection Pending removal in Python 3.14



@itemize *

@item 
@ref{7,,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{9,,ast}: The following features have been deprecated in documentation
since Python 3.8, now cause a @ref{2c9,,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{569,,ast.Constant} instead.
(Contributed by Serhiy Storchaka in gh-90953@footnote{https://github.com/python/cpython/issues/90953}.)

@item 
@ref{b,,asyncio}:


@itemize *

@item 
The child watcher classes @code{asyncio.MultiLoopChildWatcher},
@code{asyncio.FastChildWatcher}, @code{asyncio.AbstractChildWatcher}
and @code{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 
@code{asyncio.set_child_watcher()}, @code{asyncio.get_child_watcher()},
@code{asyncio.AbstractEventLoopPolicy.set_child_watcher()} and
@code{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{56c,,get_event_loop()} method of the
default event loop policy now emits a @ref{2c9,,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{3e,,email}: Deprecated the `isdst' parameter in @ref{56f,,email.utils.localtime()}.
(Contributed by Alan Williams in gh-72346@footnote{https://github.com/python/cpython/issues/72346}.)

@item 
@ref{7b,,importlib.abc} deprecated classes:


@itemize *

@item 
@code{importlib.abc.ResourceReader}

@item 
@code{importlib.abc.Traversable}

@item 
@code{importlib.abc.TraversableResources}
@end itemize

Use @ref{7f,,importlib.resources.abc} classes instead:


@itemize *

@item 
@ref{572,,importlib.resources.abc.Traversable}

@item 
@ref{571,,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{84,,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{98,,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{4d6,,get_context()} or
@ref{4d7,,set_start_method()} APIs to explicitly specify when
your code `requires' @code{'fork'}.  See @ref{46d,,Contexts and start methods}.

@item 
@ref{a8,,pathlib}: @ref{576,,is_relative_to()} and
@ref{575,,relative_to()}: passing additional arguments is
deprecated.

@item 
@ref{ae,,pkgutil}: @code{pkgutil.find_loader()} and @code{pkgutil.get_loader()}
now raise @ref{2c9,,DeprecationWarning};
use @ref{7a7,,importlib.util.find_spec()} instead.
(Contributed by Nikita Sobolev in gh-97850@footnote{https://github.com/python/cpython/issues/97850}.)

@item 
@ref{b9,,pty}:


@itemize *

@item 
@code{master_open()}: use @ref{579,,pty.openpty()}.

@item 
@code{slave_open()}: use @ref{579,,pty.openpty()}.
@end itemize

@item 
@ref{d7,,sqlite3}:


@itemize *

@item 
@code{version} and @code{version_info}.

@item 
@ref{7a8,,execute()} and @ref{7a9,,executemany()}
if @ref{7aa,,named placeholders} are used and
`parameters' is a sequence instead of a @ref{188,,dict}.
@end itemize

@item 
@ref{111,,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<4>,Pending removal in Python 3 14,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-15}@anchor{7ab}
@subsubsection Pending removal in Python 3.15



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @code{__cached__} on a module while
failing to set @ref{58b,,__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{58c,,__package__} on a module while
failing to set @ref{58d,,__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{2d,,ctypes}:


@itemize *

@item 
The undocumented @code{ctypes.SetPointerType()} function
has been deprecated since Python 3.13.
@end itemize

@item 
@ref{75,,http.server}:


@itemize *

@item 
The obsolete and rarely used @code{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{7a,,importlib}:


@itemize *

@item 
@code{load_module()} method: use @code{exec_module()} instead.
@end itemize

@item 
@ref{a8,,pathlib}:


@itemize *

@item 
@code{.PurePath.is_reserved()}
has been deprecated since Python 3.13.
Use @ref{2d9,,os.path.isreserved()} to detect reserved paths on Windows.
@end itemize

@item 
@ref{af,,platform}:


@itemize *

@item 
@code{platform.java_ver()} has been deprecated since Python 3.13.
This function is only useful for Jython support, has a confusing API,
and is largely untested.
@end itemize

@item 
@ref{e4,,sysconfig}:


@itemize *

@item 
The `check_home' argument of @ref{2dd,,sysconfig.is_python_build()} has been
deprecated since Python 3.12.
@end itemize

@item 
@ref{f6,,threading}:


@itemize *

@item 
@ref{2df,,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{10c,,types}:


@itemize *

@item 
@ref{2e1,,types.CodeType}: Accessing @code{codeobject.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{2c9,,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{10d,,typing}:


@itemize *

@item 
The undocumented keyword argument syntax for creating
@ref{2e4,,NamedTuple} classes
(for example, @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 
When using the functional syntax of @ref{290,,TypedDict}s, failing
to pass a value to the `fields' parameter (@code{TD = TypedDict("TD")}) or
passing @code{None} (@code{TD = TypedDict("TD", None)}) has been deprecated
since Python 3.13.
Use @code{class TD(TypedDict): pass} or @code{TD = TypedDict("TD", @{@})}
to create a TypedDict with zero field.

@item 
The @code{typing.no_type_check_decorator()} decorator function
has been deprecated since Python 3.13.
After eight years in the @ref{10d,,typing} module,
it has yet to be supported by any major type checker.
@end itemize

@item 
@code{sre_compile}, @code{sre_constants} and @code{sre_parse} modules.

@item 
@ref{11c,,wave}:


@itemize *

@item 
The @code{getmark()}, @code{setmark()} and @code{getmarkers()} methods of
the @ref{2e6,,Wave_read} and @ref{2e7,,Wave_write} classes
have been deprecated since Python 3.13.
@end itemize

@item 
@ref{13b,,zipimport}:


@itemize *

@item 
@code{zipimport.zipimporter.load_module()} has been deprecated since
Python 3.10. Use @ref{2e9,,exec_module()} instead.
(gh-125746@footnote{https://github.com/python/cpython/issues/125746}.)
@end itemize
@end itemize

@node Pending removal in Python 3 16<4>,Pending removal in Python 3 17<3>,Pending removal in Python 3 15<3>,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-16}@anchor{7ac}
@subsubsection Pending removal in Python 3.16



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @ref{2ff,,__loader__} on a module while
failing to set @ref{300,,__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{8,,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{301,,Py_UCS4})
for Unicode characters instead.
@end itemize

@item 
@ref{b,,asyncio}:


@itemize *

@item 
@code{asyncio.iscoroutinefunction()} is deprecated
and will be removed in Python 3.16;
use @ref{302,,inspect.iscoroutinefunction()} instead.
(Contributed by Jiahao Li and Kumar Aditya in gh-122875@footnote{https://github.com/python/cpython/issues/122875}.)

@item 
@ref{b,,asyncio} policy system is deprecated and will be removed in Python 3.16.
In particular, the following classes and functions are deprecated:


@itemize *

@item 
@ref{303,,asyncio.AbstractEventLoopPolicy}

@item 
@ref{304,,asyncio.DefaultEventLoopPolicy}

@item 
@ref{305,,asyncio.WindowsSelectorEventLoopPolicy}

@item 
@ref{306,,asyncio.WindowsProactorEventLoopPolicy}

@item 
@ref{307,,asyncio.get_event_loop_policy()}

@item 
@ref{308,,asyncio.set_event_loop_policy()}
@end itemize

Users should use @ref{309,,asyncio.run()} or @ref{30a,,asyncio.Runner} with
`loop_factory' to use the desired event loop implementation.

For example, to use @ref{30b,,asyncio.SelectorEventLoop} on Windows:

@example
import asyncio

async def main():
    ...

asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
@end example

(Contributed by Kumar Aditya in gh-127949@footnote{https://github.com/python/cpython/issues/127949}.)
@end itemize

@item 
@ref{13,,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{62,,functools}:


@itemize *

@item 
Calling the Python implementation of @ref{153,,functools.reduce()} with `function'
or `sequence' as keyword arguments has been deprecated since Python 3.14.
@end itemize

@item 
@ref{8a,,logging}:


@itemize *

@item 
Support for custom logging handlers with the `strm' argument is deprecated
and scheduled for removal in Python 3.16. Define handlers with the `stream'
argument instead. (Contributed by Mariusz Felisiak in gh-115032@footnote{https://github.com/python/cpython/issues/115032}.)
@end itemize

@item 
@ref{93,,mimetypes}:


@itemize *

@item 
Valid extensions start with a “.” or are empty for
@ref{30c,,mimetypes.MimeTypes.add_type()}.
Undotted extensions are deprecated and will
raise a @ref{277,,ValueError} in Python 3.16.
(Contributed by Hugo van Kemenade in gh-75223@footnote{https://github.com/python/cpython/issues/75223}.)
@end itemize

@item 
@ref{cd,,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{30d,,RuntimeError}.
@end itemize

@item 
@ref{e1,,symtable}:


@itemize *

@item 
The @code{symtable.Class.get_methods()} method
has been deprecated since Python 3.14.
@end itemize

@item 
@ref{e2,,sys}:


@itemize *

@item 
The @ref{30e,,_enablelegacywindowsfsencoding()} function
has been deprecated since Python 3.13.
Use the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,PYTHONLEGACYWINDOWSFSENCODING} environment variable instead.
@end itemize

@item 
@ref{e4,,sysconfig}:


@itemize *

@item 
The @code{sysconfig.expand_makefile_vars()} function
has been deprecated since Python 3.14.
Use the @code{vars} argument of @ref{156,,sysconfig.get_paths()} instead.
@end itemize

@item 
@ref{e7,,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 Python 3 17<3>,Pending removal in Python 3 18<4>,Pending removal in Python 3 16<4>,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-17}@anchor{7ad}
@subsubsection Pending removal in Python 3.17



@itemize *

@item 
@ref{33,,datetime}:


@itemize *

@item 
@ref{2d2,,strptime()} calls using a format string containing
@code{%e} (day of month) without a year.
This has been deprecated since Python 3.15.
(Contributed by Stan Ulbrych in gh-70647@footnote{https://github.com/python/cpython/issues/70647}.)
@end itemize

@item 
@ref{1f,,collections.abc}:


@itemize -

@item 
@ref{2cb,,collections.abc.ByteString} is scheduled for removal in Python 3.17.

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj}
implements the @ref{311,,buffer protocol} at runtime. For use
in type annotations, either use @ref{312,,Buffer} or a union
that explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} was originally intended to be an abstract class that
would serve as a supertype of both @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
However, since the ABC never had any methods, knowing that an object was an
instance of @code{ByteString} never actually told you anything useful
about the object. Other common buffer types such as @ref{1d2,,memoryview}
were also never understood as subtypes of @code{ByteString} (either at
runtime or by static type checkers).

See 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} for more details.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)
@end itemize

@item 
@ref{54,,encodings}:


@itemize -

@item 
Passing non-ascii `encoding' names to @ref{313,,encodings.normalize_encoding()}
is deprecated and scheduled for removal in Python 3.17.
(Contributed by Stan Ulbrych in gh-136702@footnote{https://github.com/python/cpython/issues/136702}.)
@end itemize

@item 
@ref{11e,,webbrowser}:


@itemize -

@item 
@code{webbrowser.MacOSXOSAScript} is deprecated in favour of
@code{webbrowser.MacOS}. (gh-137586@footnote{https://github.com/python/cpython/issues/137586})
@end itemize

@item 
@ref{10d,,typing}:


@itemize -

@item 
Before Python 3.14, old-style unions were implemented using the private class
@code{typing._UnionGenericAlias}. This class is no longer needed for the implementation,
but it has been retained for backward compatibility, with removal scheduled for Python
3.17. Users should use documented introspection helpers like @ref{314,,typing.get_origin()}
and @ref{315,,typing.get_args()} instead of relying on private implementation details.

@item 
@ref{2e3,,typing.ByteString}, deprecated since Python 3.9, is scheduled for removal in
Python 3.17.

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj}
implements the @ref{311,,buffer protocol} at runtime. For use
in type annotations, either use @ref{312,,Buffer} or a union
that explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} was originally intended to be an abstract class that
would serve as a supertype of both @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
However, since the ABC never had any methods, knowing that an object was an
instance of @code{ByteString} never actually told you anything useful
about the object. Other common buffer types such as @ref{1d2,,memoryview}
were also never understood as subtypes of @code{ByteString} (either at
runtime or by static type checkers).

See 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} for more details.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)
@end itemize
@end itemize

@node Pending removal in Python 3 18<4>,Pending removal in Python 3 19<3>,Pending removal in Python 3 17<3>,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-18}@anchor{7ae}
@subsubsection Pending removal in Python 3.18



@itemize *

@item 
No longer accept a boolean value when a file descriptor is expected.
(Contributed by Serhiy Storchaka in gh-82626@footnote{https://github.com/python/cpython/issues/82626}.)

@item 
@ref{39,,decimal}:


@itemize *

@item 
The non-standard and undocumented @ref{1c2,,Decimal} format
specifier @code{'N'}, which is only supported in the @code{decimal} module’s
C implementation, has been deprecated since Python 3.13.
(Contributed by Serhiy Storchaka in gh-89902@footnote{https://github.com/python/cpython/issues/89902}.)
@end itemize

@item 
Deprecations defined by 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/}:


@itemize *

@item 
@code{import} lines in @code{`name'.pth} files are silently ignored.
@end itemize

(Contributed by Barry Warsaw in gh-148641@footnote{https://github.com/python/cpython/issues/148641}.)
@end itemize

@node Pending removal in Python 3 19<3>,Pending removal in Python 3 20<3>,Pending removal in Python 3 18<4>,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-19}@anchor{7af}
@subsubsection Pending removal in Python 3.19



@itemize *

@item 
@ref{2d,,ctypes}:


@itemize *

@item 
Implicitly switching to the MSVC-compatible struct layout by setting
@ref{318,,_pack_} but not @ref{319,,_layout_}
on non-Windows platforms.
@end itemize

@item 
@ref{6b,,hashlib}:


@itemize -

@item 
In hash function constructors such as @ref{2f1,,new()} or the
direct hash-named constructors such as @ref{2f2,,md5()} and
@ref{2f3,,sha256()}, their optional initial data parameter could
also be passed a keyword argument named @code{data=} or @code{string=} in
various @code{hashlib} implementations.

Support for the @code{string} keyword argument name is now deprecated
and slated for removal in Python 3.19.

Before Python 3.13, the @code{string} keyword parameter was not correctly
supported depending on the backend implementation of hash functions.
Prefer passing the initial data as a positional argument for maximum
backwards compatibility.
@end itemize

@item 
@ref{74,,http.cookies}:


@itemize *

@item 
@ref{2f4,,http.cookies.Morsel.js_output()} is deprecated and will be
removed in Python 3.19.

@item 
@ref{2f5,,http.cookies.BaseCookie.js_output()} is deprecated and will be
removed in Python 3.19.
@end itemize

@item 
@ref{77,,imaplib}:


@itemize *

@item 
Altering @ref{2f8,,IMAP4.file} is now deprecated
and slated for removal in Python 3.19. This property is now unused
and changing its value does not automatically close the current file.

Before Python 3.14, this property was used to implement the corresponding
@code{read()} and @code{readline()} methods for @ref{31a,,IMAP4} but this
is no longer the case since then.
@end itemize
@end itemize

@node Pending removal in Python 3 20<3>,Pending removal in future versions<4>,Pending removal in Python 3 19<3>,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-20}@anchor{7b0}
@subsubsection Pending removal in Python 3.20



@itemize *

@item 
Calling the @code{__new__()} method of @ref{2fb,,struct.Struct} without the
`format' argument is deprecated and will be removed in Python 3.20.  Calling
@ref{2fa,,__init__()} method on initialized @code{Struct}
objects is deprecated and will be removed in Python 3.20.

(Contributed by Sergey B Kirpichev and Serhiy Storchaka in gh-143715@footnote{https://github.com/python/cpython/issues/143715}.)

@item 
The @code{__version__}, @code{version} and @code{VERSION} attributes have been
deprecated in these standard library modules and will be removed in
Python 3.20. Use @ref{2fc,,sys.version_info} instead.


@itemize -

@item 
@ref{7,,argparse}

@item 
@ref{2c,,csv}

@item 
@ref{2d,,ctypes}

@item 
@code{ctypes.macholib}

@item 
@ref{39,,decimal} (use @ref{2fd,,decimal.SPEC_VERSION} instead)

@item 
@ref{75,,http.server}

@item 
@ref{77,,imaplib}

@item 
@ref{83,,ipaddress}

@item 
@ref{85,,json}

@item 
@ref{8a,,logging} (@code{__date__} also deprecated)

@item 
@ref{a4,,optparse}

@item 
@ref{ab,,pickle}

@item 
@ref{af,,platform}

@item 
@ref{c1,,re}

@item 
@ref{d5,,socketserver}

@item 
@ref{e6,,tabnanny}

@item 
@ref{e7,,tarfile}

@item 
@ref{fe,,tkinter.font}

@item 
@ref{102,,tkinter.ttk}

@item 
@ref{124,,wsgiref.simple_server}

@item 
@ref{12e,,xml.etree.ElementTree}

@item 
@code{xml.sax.expatreader}

@item 
@ref{133,,xml.sax.handler}

@item 
@ref{13c,,zlib}
@end itemize

(Contributed by Hugo van Kemenade and Stan Ulbrych in gh-76007@footnote{https://github.com/python/cpython/issues/76007}.)

@item 
Deprecations defined by 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/}:


@itemize *

@item 
Warnings are produced for @code{import} lines found in @code{`name'.pth}
files.

@item 
@code{`name'.pth} files are no longer decoded in the locale encoding by
default.  They `MUST' be encoded in @code{utf-8-sig}.
@end itemize

(Contributed by Barry Warsaw in gh-148641@footnote{https://github.com/python/cpython/issues/148641}.)

@item 
@ref{9,,ast}:


@itemize *

@item 
Creating instances of abstract AST nodes (such as @ref{2ec,,ast.AST}
or @code{ast.expr}) is deprecated and will raise an error in Python 3.20.
@end itemize
@end itemize

@node Pending removal in future versions<4>,,Pending removal in Python 3 20<3>,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-future-versions}@anchor{7b1}
@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{7,,argparse}:


@itemize *

@item 
Nesting argument groups and nesting mutually exclusive
groups are deprecated.

@item 
Passing the undocumented keyword argument `prefix_chars' to
@ref{31d,,add_argument_group()} is now
deprecated.

@item 
The @ref{31e,,argparse.FileType} type converter is deprecated.
@end itemize

@item 
@ref{13,,builtins}:


@itemize *

@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{31f,,and}, @ref{320,,else}, @ref{321,,for}, @ref{322,,if},
@ref{323,,in}, @ref{324,,is} and @ref{325,,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{326,,int}.

@item 
Support for @code{__float__()} method returning a strict subclass of
@ref{327,,float}: these methods will be required to return an instance of
@code{float}.

@item 
Support for @code{__complex__()} method returning a strict subclass of
@ref{328,,complex}: these methods will be required to return an instance of
@code{complex}.

@item 
Passing a complex number as the `real' or `imag' argument in the
@ref{328,,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{15,,calendar}: @code{calendar.January} and @code{calendar.February} constants are
deprecated and replaced by @ref{329,,calendar.JANUARY} and
@ref{32a,,calendar.FEBRUARY}.
(Contributed by Prince Roshan in gh-103636@footnote{https://github.com/python/cpython/issues/103636}.)

@item 
@ref{1c,,codecs}: use @ref{32b,,open()} instead of @ref{32c,,codecs.open()}. (gh-133038@footnote{https://github.com/python/cpython/issues/133038})

@item 
@code{codeobject.co_lnotab}: use the @ref{32d,,codeobject.co_lines()} method
instead.

@item 
@ref{33,,datetime}:


@itemize *

@item 
@ref{32e,,utcnow()}:
use @code{datetime.datetime.now(tz=datetime.UTC)}.

@item 
@ref{32f,,utcfromtimestamp()}:
use @code{datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)}.
@end itemize

@item 
@ref{66,,gettext}: Plural value must be an integer.

@item 
@ref{7a,,importlib}:


@itemize *

@item 
@ref{330,,cache_from_source()} `debug_override' parameter is
deprecated: use the `optimization' parameter instead.
@end itemize

@item 
@ref{7d,,importlib.metadata}:


@itemize *

@item 
@code{EntryPoints} tuple interface.

@item 
Implicit @code{None} on return values.
@end itemize

@item 
@ref{8a,,logging}: the @code{warn()} method has been deprecated
since Python 3.3, use @ref{331,,warning()} instead.

@item 
@ref{8e,,mailbox}: Use of StringIO input and text mode is deprecated, use
BytesIO and binary mode instead.

@item 
@ref{a5,,os}: Calling @ref{332,,os.register_at_fork()} in a multi-threaded process.

@item 
@ref{a6,,os.path}: @ref{333,,os.path.commonprefix()} is deprecated, use
@ref{334,,os.path.commonpath()} for path prefixes. The @code{os.path.commonprefix()}
function is being deprecated due to having a misleading name and module.
The function is not safe to use for path prefixes despite being included in a
module about path manipulation, meaning it is easy to accidentally
introduce path traversal vulnerabilities into Python programs by using this
function.

@item 
@code{pydoc.ErrorDuringImport}: A tuple value for `exc_info' parameter is
deprecated, use an exception instance.

@item 
@ref{c1,,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 
@ref{cd,,shutil}: @ref{335,,rmtree()}”s `onerror' parameter is deprecated in
Python 3.12; use the `onexc' parameter instead.

@item 
@ref{d8,,ssl} options and protocols:


@itemize *

@item 
@ref{336,,ssl.SSLContext} without protocol argument is deprecated.

@item 
@ref{336,,ssl.SSLContext}: @ref{337,,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{f6,,threading} methods:


@itemize *

@item 
@code{threading.Condition.notifyAll()}: use @ref{338,,notify_all()}.

@item 
@code{threading.Event.isSet()}: use @ref{339,,is_set()}.

@item 
@code{threading.Thread.isDaemon()}, @ref{33a,,threading.Thread.setDaemon()}:
use @ref{33b,,threading.Thread.daemon} attribute.

@item 
@code{threading.Thread.getName()}, @ref{33c,,threading.Thread.setName()}:
use @ref{33d,,threading.Thread.name} attribute.

@item 
@code{threading.currentThread()}: use @ref{33e,,threading.current_thread()}.

@item 
@code{threading.activeCount()}: use @ref{33f,,threading.active_count()}.
@end itemize

@item 
@ref{340,,typing.Text} (gh-92332@footnote{https://github.com/python/cpython/issues/92332}).

@item 
The internal class @code{typing._UnionGenericAlias} is no longer used to implement
@ref{341,,typing.Union}. To preserve compatibility with users using this private
class, a compatibility shim will be provided until at least Python 3.17. (Contributed by
Jelle Zijlstra in gh-105499@footnote{https://github.com/python/cpython/issues/105499}.)

@item 
@ref{342,,unittest.IsolatedAsyncioTestCase}: it is deprecated to return a value
that is not @code{None} from a test case.

@item 
@ref{113,,urllib.parse} deprecated functions: @ref{2a4,,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{121,,wsgiref}: @code{SimpleHandler.stdout.write()} should not do partial
writes.

@item 
@ref{12e,,xml.etree.ElementTree}: Testing the truth value of an
@ref{343,,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{344,,sys._clear_type_cache()} is deprecated:
use @ref{345,,sys._clear_internal_caches()} instead.
@end itemize

@node CPython Bytecode Changes,C API Changes,New Deprecations,What’s New In Python 3 13
@anchor{whatsnew/3 13 cpython-bytecode-changes}@anchor{7b2}
@subsection CPython Bytecode Changes



@itemize *

@item 
The oparg of @ref{7b3,,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{7b4,,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 C API Changes,Build Changes,CPython Bytecode Changes,What’s New In Python 3 13
@anchor{whatsnew/3 13 c-api-changes}@anchor{7b5}
@subsection C API Changes


@menu
* New Features: New Features<2>. 
* Changed C APIs: Changed C APIs<2>. 
* Limited C API Changes:: 
* Removed C APIs: Removed C APIs<4>. 
* Deprecated C APIs: Deprecated C APIs<4>. 

@end menu

@node New Features<2>,Changed C APIs<2>,,C API Changes
@anchor{whatsnew/3 13 id7}@anchor{7b6}
@subsubsection New Features



@itemize *

@item 
Add the @ref{694,,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{7b7,,PyMonitoringState}

@item 
@ref{7b8,,PyMonitoring_FirePyStartEvent()}

@item 
@ref{7b9,,PyMonitoring_FirePyResumeEvent()}

@item 
@ref{7ba,,PyMonitoring_FirePyReturnEvent()}

@item 
@ref{7bb,,PyMonitoring_FirePyYieldEvent()}

@item 
@ref{7bc,,PyMonitoring_FireCallEvent()}

@item 
@ref{7bd,,PyMonitoring_FireLineEvent()}

@item 
@ref{7be,,PyMonitoring_FireJumpEvent()}

@item 
@code{PyMonitoring_FireBranchEvent}

@item 
@ref{7bf,,PyMonitoring_FireCReturnEvent()}

@item 
@ref{7c0,,PyMonitoring_FirePyThrowEvent()}

@item 
@ref{7c1,,PyMonitoring_FireRaiseEvent()}

@item 
@ref{7c2,,PyMonitoring_FireCRaiseEvent()}

@item 
@ref{7c3,,PyMonitoring_FireReraiseEvent()}

@item 
@ref{7c4,,PyMonitoring_FireExceptionHandledEvent()}

@item 
@ref{7c5,,PyMonitoring_FirePyUnwindEvent()}

@item 
@ref{7c6,,PyMonitoring_FireStopIterationEvent()}

@item 
@ref{7c7,,PyMonitoring_EnterScope()}

@item 
@ref{7c8,,PyMonitoring_ExitScope()}
@end itemize

(Contributed by Irit Katriel in gh-111997@footnote{https://github.com/python/cpython/issues/111997}).

@item 
Add @ref{693,,PyMutex}, a lightweight mutex that occupies a single byte,
and the new @ref{7c9,,PyMutex_Lock()} and @ref{7ca,,PyMutex_Unlock()} functions.
@code{PyMutex_Lock()} will release the @ref{411,,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{7cb,,PyTime C API} to provide access to system clocks:


@itemize *

@item 
@ref{7cc,,PyTime_t}.

@item 
@ref{7cd,,PyTime_MIN} and @ref{7ce,,PyTime_MAX}.

@item 
@ref{7cf,,PyTime_AsSecondsDouble()}.

@item 
@ref{7d0,,PyTime_Monotonic()}.

@item 
@ref{7d1,,PyTime_MonotonicRaw()}.

@item 
@ref{7d2,,PyTime_PerfCounter()}.

@item 
@ref{7d3,,PyTime_PerfCounterRaw()}.

@item 
@ref{7d4,,PyTime_Time()}.

@item 
@ref{7d5,,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{7d6,,PyDict_ContainsString()} function
with the same behavior as @ref{7d7,,PyDict_Contains()},
but `key' is specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.
(Contributed by Victor Stinner in gh-108314@footnote{https://github.com/python/cpython/issues/108314}.)

@item 
Add the @ref{7d8,,PyDict_GetItemRef()} and @ref{634,,PyDict_GetItemStringRef()}
functions,
which behave similarly to @ref{7d9,,PyDict_GetItemWithError()},
but return a  @ref{7da,,strong reference} instead of a @ref{603,,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{7db,,PyDict_SetDefaultRef()} function,
which behaves similarly to @ref{7dc,,PyDict_SetDefault()},
but returns a @ref{7da,,strong reference} instead of a @ref{603,,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{635,,PyDict_Pop()} and @ref{7dd,,PyDict_PopString()} functions
to remove a key from a dictionary and optionally return the removed value.
This is similar to @ref{7de,,dict.pop()},
though there is no default value,
and @ref{7df,,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{7e0,,PyMapping_GetOptionalItem()}
and @ref{7e1,,PyMapping_GetOptionalItemString()} functions
as alternatives to @ref{7e2,,PyObject_GetItem()}
and @ref{7e3,,PyMapping_GetItemString()} respectively.
The new functions do not raise @ref{7df,,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{7e4,,PyObject_GetOptionalAttr()}
and @ref{7e5,,PyObject_GetOptionalAttrString()} functions
as alternatives to  @ref{3b7,,PyObject_GetAttr()}
and @ref{7e6,,PyObject_GetAttrString()} respectively.
The new functions do not raise @ref{1a9,,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{7e7,,PyErr_FormatUnraisable()} function
as an extension to @ref{7e8,,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{7da,,strong reference} instead of
a @ref{603,,borrowed reference} for frame locals, globals, and builtins,
as part of @ref{681,,PEP 667}:


@itemize *

@item 
@ref{7e9,,PyEval_GetFrameBuiltins()} replaces @ref{7ea,,PyEval_GetBuiltins()}

@item 
@ref{7eb,,PyEval_GetFrameGlobals()} replaces @ref{7ec,,PyEval_GetGlobals()}

@item 
@ref{7ed,,PyEval_GetFrameLocals()} replaces @ref{7ee,,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{7ef,,Py_GetConstant()} and @ref{7f0,,Py_GetConstantBorrowed()}
functions to get @ref{7da,,strong}
or @ref{603,,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{7f1,,PyImport_AddModuleRef()} function
as a replacement for @ref{7f2,,PyImport_AddModule()}
that returns a @ref{7da,,strong reference} instead of a @ref{603,,borrowed reference}.
(Contributed by Victor Stinner in gh-105922@footnote{https://github.com/python/cpython/issues/105922}.)

@item 
Add the @ref{7f3,,Py_IsFinalizing()} function to check
whether the main Python interpreter is
@ref{1a0,,shutting down}.
(Contributed by Victor Stinner in gh-108014@footnote{https://github.com/python/cpython/issues/108014}.)

@item 
Add the @ref{7f4,,PyList_GetItemRef()} function
as a replacement for @ref{7f5,,PyList_GetItem()}
that returns a @ref{7da,,strong reference} instead of a @ref{603,,borrowed reference}.
(Contributed by Sam Gross in gh-114329@footnote{https://github.com/python/cpython/issues/114329}.)

@item 
Add the @ref{7f6,,PyList_Extend()} and @ref{7f7,,PyList_Clear()} functions,
mirroring the Python @ref{7f8,,list.extend()} and @ref{7f9,,list.clear()} methods.
(Contributed by Victor Stinner in gh-111138@footnote{https://github.com/python/cpython/issues/111138}.)

@item 
Add the @ref{7fa,,PyLong_AsInt()} function.
It behaves similarly to @ref{7fb,,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{7fc,,PyLong_AsNativeBytes()}, @ref{7fd,,PyLong_FromNativeBytes()},
and @ref{7fe,,PyLong_FromUnsignedNativeBytes()} functions
to simplify converting between native integer types
and Python @ref{326,,int} objects.
(Contributed by Steve Dower in gh-111140@footnote{https://github.com/python/cpython/issues/111140}.)

@item 
Add @ref{7ff,,PyModule_Add()} function, which is similar to
@ref{800,,PyModule_AddObjectRef()} and @ref{801,,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{802,,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{638,,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{803,,PyObject_VisitManagedDict()} and
@ref{804,,PyObject_ClearManagedDict()} functions.
which must be called by the traverse and clear functions of a type using
the @ref{39c,,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{805,,PyRefTracer_SetTracer()}
and @ref{806,,PyRefTracer_GetTracer()} functions,
which enable tracking object creation and destruction
in the same way that the @ref{108,,tracemalloc} module does.
(Contributed by Pablo Galindo in gh-93502@footnote{https://github.com/python/cpython/issues/93502}.)

@item 
Add the @ref{807,,PySys_AuditTuple()} function
as an alternative to @ref{808,,PySys_Audit()}
that takes event arguments as a Python @ref{1ce,,tuple} object.
(Contributed by Victor Stinner in gh-85283@footnote{https://github.com/python/cpython/issues/85283}.)

@item 
Add the @ref{636,,PyThreadState_GetUnchecked()} function
as an alternative to @ref{809,,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{80a,,PyType_GetFullyQualifiedName()} function
to get the type’s fully qualified name.
The module name is prepended if @ref{80b,,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{80c,,PyType_GetModuleName()} function
to get the type’s module name. This is equivalent to getting the
@ref{80b,,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{80d,,PyUnicode_EqualToUTF8AndSize()}
and @ref{80e,,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{3a4,,PyWeakref_GetRef()} function
as an alternative to  @code{PyWeakref_GetObject()}
that returns a @ref{7da,,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{80f,,PyObject_HasAttrWithError()} replaces @ref{810,,PyObject_HasAttr()}.

@item 
@ref{811,,PyObject_HasAttrStringWithError()}
replaces @ref{812,,PyObject_HasAttrString()}.

@item 
@ref{813,,PyMapping_HasKeyWithError()} replaces @ref{814,,PyMapping_HasKey()}.

@item 
@ref{815,,PyMapping_HasKeyStringWithError()}
replaces @ref{816,,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<2>,Limited C API Changes,New Features<2>,C API Changes
@anchor{whatsnew/3 13 changed-c-apis}@anchor{817}
@subsubsection Changed C APIs



@itemize *

@item 
The `keywords' parameter of @ref{818,,PyArg_ParseTupleAndKeywords()}
and @ref{819,,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{81a,,PY_CXX_CONST} macro.
(Contributed by Serhiy Storchaka in gh-65210@footnote{https://github.com/python/cpython/issues/65210}.)

@item 
@ref{818,,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{81b,,PyUnstable_Code_GetFirstFree()}.
(Contributed by Bogdan Romanyuk in gh-115781@footnote{https://github.com/python/cpython/issues/115781}.)

@item 
The @ref{81c,,PyDict_GetItem()}, @ref{81d,,PyDict_GetItemString()},
@ref{814,,PyMapping_HasKey()}, @ref{816,,PyMapping_HasKeyString()},
@ref{810,,PyObject_HasAttr()}, @ref{812,,PyObject_HasAttrString()},
and @ref{356,,PySys_GetObject()} functions,
each of which clears all errors which occurred when calling them
now reports these errors using @ref{70c,,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{81e,,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{81f,,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{3dc,,debug mode}
or @ref{820,,with assertions},
@ref{821,,PyTuple_SET_ITEM()} and @ref{822,,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<4>,Changed C APIs<2>,C API Changes
@anchor{whatsnew/3 13 limited-c-api-changes}@anchor{823}
@subsubsection Limited C API Changes



@itemize *

@item 
The following functions are now included in the Limited C API:


@itemize *

@item 
@ref{2bf,,PyMem_RawMalloc()}

@item 
@ref{824,,PyMem_RawCalloc()}

@item 
@ref{825,,PyMem_RawRealloc()}

@item 
@ref{826,,PyMem_RawFree()}

@item 
@ref{808,,PySys_Audit()}

@item 
@ref{807,,PySys_AuditTuple()}

@item 
@ref{827,,PyType_GetModuleByDef()}
@end itemize

(Contributed by Victor Stinner in 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{828,,--with-trace-refs} (tracing references)
now supports the @ref{829,,Limited API}.
(Contributed by Victor Stinner in gh-108634@footnote{https://github.com/python/cpython/issues/108634}.)
@end itemize

@node Removed C APIs<4>,Deprecated C APIs<4>,Limited C API Changes,C API Changes
@anchor{whatsnew/3 13 removed-c-apis}@anchor{82a}
@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{758,,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{311,,Buffer Protocol} instead.


@itemize *

@item 
@code{PyObject_CheckReadBuffer()}:
Use @ref{82b,,PyObject_CheckBuffer()} to test
whether the object supports the buffer protocol.
Note that @code{PyObject_CheckBuffer()} doesn’t guarantee
that @ref{82c,,PyObject_GetBuffer()} will succeed.
To test if the object is actually readable,
see the next example of @code{PyObject_GetBuffer()}.

@item 
@code{PyObject_AsCharBuffer()}, @code{PyObject_AsReadBuffer()}:
Use @ref{82c,,PyObject_GetBuffer()} and @ref{82d,,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{82c,,PyObject_GetBuffer()} and @ref{82d,,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{82e,,PyObject_CallNoArgs()} or @ref{82f,,PyObject_Call()} instead.

@cartouche
@quotation Προειδοποίηση 
In @ref{82f,,PyObject_Call()}, positional arguments must be a @ref{1ce,,tuple}
and must not be @code{NULL},
and keyword arguments must be a @ref{188,,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
@code{PyObject_Call()},
pass an empty tuple as positional arguments using
@ref{830,,PyTuple_New(0)}.
@end quotation
@end cartouche

@item 
@code{PyEval_CallFunction()}:
Use @ref{831,,PyObject_CallFunction()} instead.

@item 
@code{PyEval_CallMethod()}:
Use @ref{3b6,,PyObject_CallMethod()} instead.

@item 
@code{PyCFunction_Call()}:
Use @ref{82f,,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{832,,PyConfig.warnoptions} instead.

@item 
@code{PySys_AddWarnOption()}:
Use @ref{832,,PyConfig.warnoptions} instead.

@item 
@code{PySys_AddXOption()}:
Use @ref{833,,PyConfig.xoptions} instead.

@item 
@code{PySys_HasWarnOptions()}:
Use @ref{833,,PyConfig.xoptions} instead.

@item 
@code{PySys_SetPath()}:
Set @ref{834,,PyConfig.module_search_paths} instead.

@item 
@code{Py_SetPath()}:
Set @ref{834,,PyConfig.module_search_paths} instead.

@item 
@code{Py_SetStandardStreamEncoding()}:
Set @ref{835,,PyConfig.stdio_encoding} instead,
and set also maybe @ref{62d,,PyConfig.legacy_windows_stdio} (on Windows).

@item 
@code{_Py_SetProgramFullPath()}:
Set @ref{836,,PyConfig.executable} instead.
@end itemize

Use the new @ref{60b,,PyConfig} API of the @ref{837,,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{838,,PyEval_SaveThread()} and @ref{839,,PyEval_RestoreThread()};

@item 
low-level @ref{83a,,PyEval_AcquireThread()} and @ref{839,,PyEval_RestoreThread()};

@item 
or @ref{1a5,,PyGILState_Ensure()} and @ref{1a6,,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{83b,,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
@code{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<4>,,Removed C APIs<4>,C API Changes
@anchor{whatsnew/3 13 deprecated-c-apis}@anchor{83c}
@subsubsection Deprecated C APIs



@itemize *

@item 
Deprecate old Python initialization functions:


@itemize *

@item 
@code{PySys_ResetWarnOptions()}:
Clear @ref{3a5,,sys.warnoptions} and @code{warnings.filters} instead.

@item 
@code{Py_GetExecPrefix()}:
Get @ref{3a8,,sys.exec_prefix} instead.

@item 
@code{Py_GetPath()}:
Get @ref{194,,sys.path} instead.

@item 
@code{Py_GetPrefix()}:
Get @ref{3ab,,sys.prefix} instead.

@item 
@code{Py_GetProgramFullPath()}:
Get @ref{3ac,,sys.executable} instead.

@item 
@code{Py_GetProgramName()}:
Get @ref{3ac,,sys.executable} instead.

@item 
@code{Py_GetPythonHome()}:
Get @ref{609,,PyConfig.home}
or the 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} environment variable instead.
@end itemize

(Contributed by Victor Stinner in gh-105145@footnote{https://github.com/python/cpython/issues/105145}.)

@item 
@ref{1a7,,Soft deprecate} the
@ref{7ea,,PyEval_GetBuiltins()}, @ref{7ec,,PyEval_GetGlobals()},
and @ref{7ee,,PyEval_GetLocals()} functions,
which return a @ref{603,,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 @code{PyImport_ImportModuleNoBlock()} function,
which is just an alias to @ref{3a3,,PyImport_ImportModule()} since Python 3.3.
(Contributed by Victor Stinner in gh-105396@footnote{https://github.com/python/cpython/issues/105396}.)

@item 
@ref{1a7,,Soft deprecate} the
@ref{801,,PyModule_AddObject()} function.
It should be replaced with @ref{7ff,,PyModule_Add()}
or @ref{800,,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 @code{PyWeakref_GetObject()} and
@code{PyWeakref_GET_OBJECT()} functions,
which return a @ref{603,,borrowed reference}.
Replace them with the new @ref{3a4,,PyWeakref_GetRef()} function,
which returns a @ref{7da,,strong reference}.
The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
@code{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<4>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<5>. 
* Pending removal in Python 3.18: Pending removal in Python 3 18<5>. 
* Pending removal in future versions: Pending removal in future versions<5>. 

@end menu

@node Pending removal in Python 3 14<2>,Pending removal in Python 3 15<4>,,Deprecated C APIs<4>
@anchor{whatsnew/3 13 id8}@anchor{83d}
@subsubsection Pending removal in Python 3.14



@itemize *

@item 
The @code{ma_version_tag} field in @ref{83e,,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{5fb,,immutable types} with mutable
bases (gh-95388@footnote{https://github.com/python/cpython/issues/95388}).
@end itemize

@node Pending removal in Python 3 15<4>,Pending removal in Python 3 16<5>,Pending removal in Python 3 14<2>,Deprecated C APIs<4>
@anchor{whatsnew/3 13 id9}@anchor{83f}
@subsubsection Pending removal in Python 3.15



@itemize *

@item 
The @code{PyImport_ImportModuleNoBlock()}:
Use @ref{3a3,,PyImport_ImportModule()} instead.

@item 
@code{PyWeakref_GetObject()} and @code{PyWeakref_GET_OBJECT()}:
Use @ref{3a4,,PyWeakref_GetRef()} instead. The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
@code{PyWeakref_GetRef()} on Python 3.12 and older.

@item 
@code{PyUnicode_AsDecodedObject()}:
Use @ref{3a1,,PyCodec_Decode()} instead.

@item 
@code{PyUnicode_AsDecodedUnicode()}:
Use @ref{3a1,,PyCodec_Decode()} instead; Note that some codecs (for example, «base64»)
may return a type other than @ref{1df,,str}, such as @ref{1c7,,bytes}.

@item 
@code{PyUnicode_AsEncodedObject()}:
Use @ref{3a2,,PyCodec_Encode()} instead.

@item 
@code{PyUnicode_AsEncodedUnicode()}:
Use @ref{3a2,,PyCodec_Encode()} instead; Note that some codecs (for example, «base64»)
may return a type other than @ref{1c7,,bytes}, such as @ref{1df,,str}.

@item 
Python initialization functions, deprecated in Python 3.13:


@itemize *

@item 
@code{Py_GetPath()}:
Use @ref{3a6,,PyConfig_Get("module_search_paths")}
(@ref{194,,sys.path}) instead.

@item 
@code{Py_GetPrefix()}:
Use @ref{3a6,,PyConfig_Get("base_prefix")}
(@ref{3aa,,sys.base_prefix}) instead. Use @code{PyConfig_Get("prefix")} (@ref{3ab,,sys.prefix}) if @ref{3a9,,virtual environments} need to be handled.

@item 
@code{Py_GetExecPrefix()}:
Use @ref{3a6,,PyConfig_Get("base_exec_prefix")}
(@ref{3a7,,sys.base_exec_prefix}) instead. Use
@code{PyConfig_Get("exec_prefix")}
(@ref{3a8,,sys.exec_prefix}) if @ref{3a9,,virtual environments} need to
be handled.

@item 
@code{Py_GetProgramFullPath()}:
Use @ref{3a6,,PyConfig_Get("executable")}
(@ref{3ac,,sys.executable}) instead.

@item 
@code{Py_GetProgramName()}:
Use @ref{3a6,,PyConfig_Get("executable")}
(@ref{3ac,,sys.executable}) instead.

@item 
@code{Py_GetPythonHome()}:
Use @ref{3a6,,PyConfig_Get("home")} or the
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} environment variable instead.
@end itemize

The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
@ref{3a6,,PyConfig_Get()} on Python 3.13 and older.

@item 
Functions to configure Python’s initialization, deprecated in Python 3.11:


@itemize *

@item 
@code{PySys_SetArgvEx()}:
Set @ref{607,,PyConfig.argv} instead.

@item 
@code{PySys_SetArgv()}:
Set @ref{607,,PyConfig.argv} instead.

@item 
@code{Py_SetProgramName()}:
Set @ref{608,,PyConfig.program_name} instead.

@item 
@code{Py_SetPythonHome()}:
Set @ref{609,,PyConfig.home} instead.

@item 
@code{PySys_ResetWarnOptions()}:
Clear @ref{3a5,,sys.warnoptions} and @code{warnings.filters} instead.
@end itemize

The @ref{60a,,Py_InitializeFromConfig()} API should be used with
@ref{60b,,PyConfig} instead.

@item 
Global configuration variables:


@itemize *

@item 
@ref{60c,,Py_DebugFlag}:
Use @ref{60d,,PyConfig.parser_debug} or
@ref{3a6,,PyConfig_Get("parser_debug")} instead.

@item 
@ref{60e,,Py_VerboseFlag}:
Use @ref{60f,,PyConfig.verbose} or
@ref{3a6,,PyConfig_Get("verbose")} instead.

@item 
@ref{610,,Py_QuietFlag}:
Use @ref{611,,PyConfig.quiet} or
@ref{3a6,,PyConfig_Get("quiet")} instead.

@item 
@ref{612,,Py_InteractiveFlag}:
Use @ref{613,,PyConfig.interactive} or
@ref{3a6,,PyConfig_Get("interactive")} instead.

@item 
@ref{614,,Py_InspectFlag}:
Use @ref{615,,PyConfig.inspect} or
@ref{3a6,,PyConfig_Get("inspect")} instead.

@item 
@ref{616,,Py_OptimizeFlag}:
Use @ref{617,,PyConfig.optimization_level} or
@ref{3a6,,PyConfig_Get("optimization_level")} instead.

@item 
@ref{618,,Py_NoSiteFlag}:
Use @ref{619,,PyConfig.site_import} or
@ref{3a6,,PyConfig_Get("site_import")} instead.

@item 
@ref{61a,,Py_BytesWarningFlag}:
Use @ref{3c4,,PyConfig.bytes_warning} or
@ref{3a6,,PyConfig_Get("bytes_warning")} instead.

@item 
@ref{61b,,Py_FrozenFlag}:
Use @ref{61c,,PyConfig.pathconfig_warnings} or
@ref{3a6,,PyConfig_Get("pathconfig_warnings")} instead.

@item 
@ref{61d,,Py_IgnoreEnvironmentFlag}:
Use @ref{61e,,PyConfig.use_environment} or
@ref{3a6,,PyConfig_Get("use_environment")} instead.

@item 
@ref{61f,,Py_DontWriteBytecodeFlag}:
Use @ref{620,,PyConfig.write_bytecode} or
@ref{3a6,,PyConfig_Get("write_bytecode")} instead.

@item 
@ref{621,,Py_NoUserSiteDirectory}:
Use @ref{622,,PyConfig.user_site_directory} or
@ref{3a6,,PyConfig_Get("user_site_directory")} instead.

@item 
@ref{623,,Py_UnbufferedStdioFlag}:
Use @ref{624,,PyConfig.buffered_stdio} or
@ref{3a6,,PyConfig_Get("buffered_stdio")} instead.

@item 
@ref{625,,Py_HashRandomizationFlag}:
Use @ref{626,,PyConfig.use_hash_seed}
and @ref{627,,PyConfig.hash_seed} or
@ref{3a6,,PyConfig_Get("hash_seed")} instead.

@item 
@ref{628,,Py_IsolatedFlag}:
Use @ref{629,,PyConfig.isolated} or
@ref{3a6,,PyConfig_Get("isolated")} instead.

@item 
@ref{62a,,Py_LegacyWindowsFSEncodingFlag}:
Use @ref{62b,,PyPreConfig.legacy_windows_fs_encoding} or
@ref{3a6,,PyConfig_Get("legacy_windows_fs_encoding")} instead.

@item 
@ref{62c,,Py_LegacyWindowsStdioFlag}:
Use @ref{62d,,PyConfig.legacy_windows_stdio} or
@ref{3a6,,PyConfig_Get("legacy_windows_stdio")} instead.

@item 
@code{Py_FileSystemDefaultEncoding}, @code{Py_HasFileSystemDefaultEncoding}:
Use @ref{62e,,PyConfig.filesystem_encoding} or
@ref{3a6,,PyConfig_Get("filesystem_encoding")} instead.

@item 
@code{Py_FileSystemDefaultEncodeErrors}:
Use @ref{62f,,PyConfig.filesystem_errors} or
@ref{3a6,,PyConfig_Get("filesystem_errors")} instead.

@item 
@code{Py_UTF8Mode}:
Use @ref{630,,PyPreConfig.utf8_mode} or
@ref{3a6,,PyConfig_Get("utf8_mode")} instead.
(see @ref{631,,Py_PreInitialize()})
@end itemize

The @ref{60a,,Py_InitializeFromConfig()} API should be used with
@ref{60b,,PyConfig} to set these options. Or @ref{3a6,,PyConfig_Get()} can be
used to get these options at runtime.
@end itemize

@node Pending removal in Python 3 16<5>,Pending removal in Python 3 18<5>,Pending removal in Python 3 15<4>,Deprecated C APIs<4>
@anchor{whatsnew/3 13 id10}@anchor{840}
@subsubsection Pending removal in Python 3.16



@itemize *

@item 
The bundled copy of @code{libmpdec}.
@end itemize

@node Pending removal in Python 3 18<5>,Pending removal in future versions<5>,Pending removal in Python 3 16<5>,Deprecated C APIs<4>
@anchor{whatsnew/3 13 id11}@anchor{841}
@subsubsection Pending removal in Python 3.18



@itemize *

@item 
The following private functions are deprecated
and planned for removal in Python 3.18:


@itemize *

@item 
@code{_PyBytes_Join()}: use @ref{5b0,,PyBytes_Join()}.

@item 
@code{_PyDict_GetItemStringWithError()}: use @ref{634,,PyDict_GetItemStringRef()}.

@item 
@code{_PyDict_Pop()}: use @ref{635,,PyDict_Pop()}.

@item 
@code{_PyLong_Sign()}: use @ref{5c7,,PyLong_GetSign()}.

@item 
@code{_PyLong_FromDigits()} and @code{_PyLong_New()}:
use @ref{5d7,,PyLongWriter_Create()}.

@item 
@code{_PyThreadState_UncheckedGet()}: use @ref{636,,PyThreadState_GetUnchecked()}.

@item 
@code{_PyUnicode_AsString()}: use @ref{637,,PyUnicode_AsUTF8()}.

@item 
@code{_PyUnicodeWriter_Init()}:
replace @code{_PyUnicodeWriter_Init(&writer)} with
@ref{5e1,,writer = PyUnicodeWriter_Create(0)}.

@item 
@code{_PyUnicodeWriter_Finish()}:
replace @code{_PyUnicodeWriter_Finish(&writer)} with
@ref{5e4,,PyUnicodeWriter_Finish(writer)}.

@item 
@code{_PyUnicodeWriter_Dealloc()}:
replace @code{_PyUnicodeWriter_Dealloc(&writer)} with
@ref{5e3,,PyUnicodeWriter_Discard(writer)}.

@item 
@code{_PyUnicodeWriter_WriteChar()}:
replace @code{_PyUnicodeWriter_WriteChar(&writer, ch)} with
@ref{5e7,,PyUnicodeWriter_WriteChar(writer@comma{} ch)}.

@item 
@code{_PyUnicodeWriter_WriteStr()}:
replace @code{_PyUnicodeWriter_WriteStr(&writer, str)} with
@ref{5e9,,PyUnicodeWriter_WriteStr(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_WriteSubstring()}:
replace @code{_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)} with
@ref{5ea,,PyUnicodeWriter_WriteSubstring(writer@comma{} str@comma{} start@comma{} end)}.

@item 
@code{_PyUnicodeWriter_WriteASCIIString()}:
replace @code{_PyUnicodeWriter_WriteASCIIString(&writer, str)} with
@ref{5e6,,PyUnicodeWriter_WriteASCII(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_WriteLatin1String()}:
replace @code{_PyUnicodeWriter_WriteLatin1String(&writer, str)} with
@ref{5ec,,PyUnicodeWriter_WriteUTF8(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_Prepare()}: (no replacement).

@item 
@code{_PyUnicodeWriter_PrepareKind()}: (no replacement).

@item 
@code{_Py_HashPointer()}: use @ref{638,,Py_HashPointer()}.

@item 
@code{_Py_fopen_obj()}: use @ref{5c0,,Py_fopen()}.
@end itemize

The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
these new public functions on Python 3.13 and older.
(Contributed by Victor Stinner in gh-128863@footnote{https://github.com/python/cpython/issues/128863}.)
@end itemize

@node Pending removal in future versions<5>,,Pending removal in Python 3 18<5>,Deprecated C APIs<4>
@anchor{whatsnew/3 13 id12}@anchor{842}
@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{63a,,Py_TPFLAGS_HAVE_FINALIZE}:
Unneeded since Python 3.8.

@item 
@ref{63b,,PyErr_Fetch()}:
Use @ref{63c,,PyErr_GetRaisedException()} instead.

@item 
@ref{63d,,PyErr_NormalizeException()}:
Use @ref{63c,,PyErr_GetRaisedException()} instead.

@item 
@ref{63e,,PyErr_Restore()}:
Use @ref{63f,,PyErr_SetRaisedException()} instead.

@item 
@ref{640,,PyModule_GetFilename()}:
Use @ref{641,,PyModule_GetFilenameObject()} instead.

@item 
@ref{642,,PyOS_AfterFork()}:
Use @ref{643,,PyOS_AfterFork_Child()} instead.

@item 
@ref{644,,PySlice_GetIndicesEx()}:
Use @ref{645,,PySlice_Unpack()} and @ref{646,,PySlice_AdjustIndices()} instead.

@item 
@ref{647,,PyUnicode_READY()}:
Unneeded since Python 3.12

@item 
@code{PyErr_Display()}:
Use @ref{648,,PyErr_DisplayException()} instead.

@item 
@code{_PyErr_ChainExceptions()}:
Use @code{_PyErr_ChainExceptions1()} instead.

@item 
@code{PyBytesObject.ob_shash} member:
call @ref{649,,PyObject_Hash()} instead.

@item 
Thread Local Storage (TLS) API:


@itemize *

@item 
@ref{64a,,PyThread_create_key()}:
Use @ref{64b,,PyThread_tss_alloc()} instead.

@item 
@ref{64c,,PyThread_delete_key()}:
Use @ref{64d,,PyThread_tss_free()} instead.

@item 
@ref{64e,,PyThread_set_key_value()}:
Use @ref{64f,,PyThread_tss_set()} instead.

@item 
@ref{650,,PyThread_get_key_value()}:
Use @ref{651,,PyThread_tss_get()} instead.

@item 
@ref{652,,PyThread_delete_key_value()}:
Use @ref{653,,PyThread_tss_delete()} instead.

@item 
@ref{654,,PyThread_ReInitTLS()}:
Unneeded since Python 3.7.
@end itemize
@end itemize

@node Build Changes,Porting to Python 3 13,C API Changes,What’s New In Python 3 13
@anchor{whatsnew/3 13 build-changes}@anchor{843}@anchor{whatsnew/3 13 pythoncapi-compat-project}@anchor{844}
@subsection Build Changes



@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{699,,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{699,,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{d7,,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{845,,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{3d6,,--with-system-libmpdec}
now defaults to @code{yes}.
The bundled copy of @code{libmpdec} will be removed in Python 3.16.

@item 
Python built with @code{configure} @ref{828,,--with-trace-refs}
(tracing references) is now ABI compatible with the Python release build
and @ref{3dc,,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{829,,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,Build Changes,What’s New In Python 3 13
@anchor{whatsnew/3 13 porting-to-python-3-13}@anchor{683}
@subsection Porting to Python 3.13


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

@menu
* Changes in the Python API: Changes in the Python API<2>. 
* Changes in the C API: Changes in the C API<2>. 

@end menu

@node Changes in the Python API<2>,Changes in the C API<2>,,Porting to Python 3 13
@anchor{whatsnew/3 13 changes-in-the-python-api}@anchor{846}
@subsubsection Changes in the Python API

@anchor{whatsnew/3 13 pep667-porting-notes-py}@anchor{6af}

@itemize *

@item 
@ref{681,,PEP 667} introduces several changes
to the semantics of @ref{28b,,locals()} and @ref{28d,,f_locals}:


@itemize *

@item 
Calling @ref{28b,,locals()} in an @ref{6ad,,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{28b,,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{28d,,FrameType.f_locals} in an
@ref{6ad,,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{4a6,,functools.partial} now emits a @ref{847,,FutureWarning}
when used as a method.
The behavior will change in future Python versions.
Wrap it in @ref{666,,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{53c,,OSError} is now raised by @ref{848,,getpass.getuser()}
for any failure to retrieve a username,
instead of @ref{1bd,,ImportError} on non-Unix platforms
or @ref{7df,,KeyError} on Unix platforms where the password database is empty.

@item 
The value of the @code{mode} attribute of @ref{849,,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{84a,,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{84b,,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{73a,,pathlib.Path.glob()} and @ref{73b,,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{f6,,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 Changes in the C API<2>,,Changes in the Python API<2>,Porting to Python 3 13
@anchor{whatsnew/3 13 changes-in-the-c-api}@anchor{84c}
@subsubsection Changes in the C API



@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{84d,,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{6b0}

@itemize *

@item 
@ref{681,,PEP 667} introduces several changes
to frame-related functions:


@itemize *

@item 
The effects of mutating the dictionary returned from
@ref{7ee,,PyEval_GetLocals()} in an @ref{6ad,,optimized scope} have changed.
New dict entries added this way will now `only' be visible to
subsequent @code{PyEval_GetLocals()} calls in that frame,
as @ref{84e,,PyFrame_GetLocals()}, @ref{28b,,locals()},
and @ref{28d,,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 @code{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{84e,,PyFrame_GetLocals()} in an @ref{6ad,,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{84f,,PyDict_Copy()}),
or by calling the new @ref{7ed,,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{84e,,PyFrame_GetLocals()} was first introduced.

@item 
@code{PyFrame_LocalsToFast()} no longer has any effect.
Calling this function is redundant now that @ref{84e,,PyFrame_GetLocals()}
returns a write-through proxy for @ref{6ad,,optimized scopes}.
@end itemize

@item 
Python 3.13 removed many private functions. Some of them can be replaced using these
alternatives:


@itemize *

@item 
@code{_PyDict_Pop()}: @ref{635,,PyDict_Pop()} or @ref{7dd,,PyDict_PopString()};

@item 
@code{_PyDict_GetItemWithError()}: @ref{7d8,,PyDict_GetItemRef()};

@item 
@code{_PyErr_WriteUnraisableMsg()}:  @ref{7e7,,PyErr_FormatUnraisable()};

@item 
@code{_PyEval_SetTrace()}: @ref{850,,PyEval_SetTrace()} or @ref{851,,PyEval_SetTraceAllThreads()};

@item 
@code{_PyList_Extend()}: @ref{7f6,,PyList_Extend()};

@item 
@code{_PyLong_AsInt()}: @ref{7fa,,PyLong_AsInt()};

@item 
@code{_PyMem_RawStrdup()}: @code{strdup()};

@item 
@code{_PyMem_Strdup()}: @code{strdup()};

@item 
@code{_PyObject_ClearManagedDict()}: @ref{804,,PyObject_ClearManagedDict()};

@item 
@code{_PyObject_VisitManagedDict()}: @ref{803,,PyObject_VisitManagedDict()};

@item 
@code{_PyThreadState_UncheckedGet()}: @ref{636,,PyThreadState_GetUnchecked()};

@item 
@code{_PyTime_AsSecondsDouble()}: @ref{7cf,,PyTime_AsSecondsDouble()};

@item 
@code{_PyTime_GetMonotonicClock()}: @ref{7d0,,PyTime_Monotonic()} or @ref{7d1,,PyTime_MonotonicRaw()};

@item 
@code{_PyTime_GetPerfCounter()}: @ref{7d2,,PyTime_PerfCounter()} or @ref{7d3,,PyTime_PerfCounterRaw()};

@item 
@code{_PyTime_GetSystemClock()}: @ref{7d4,,PyTime_Time()} or @ref{7d5,,PyTime_TimeRaw()};

@item 
@code{_PyTime_MAX}: @ref{7ce,,PyTime_MAX};

@item 
@code{_PyTime_MIN}: @ref{7cd,,PyTime_MIN};

@item 
@code{_PyTime_t}: @ref{7cc,,PyTime_t};

@item 
@code{_Py_HashPointer()}: @ref{638,,Py_HashPointer()};

@item 
@code{_Py_IsFinalizing()}: @ref{7f3,,Py_IsFinalizing()}.
@end itemize

The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get most of these new
functions on Python 3.12 and older.
@end itemize

@node Regression Test Changes,,Porting to Python 3 13,What’s New In Python 3 13
@anchor{whatsnew/3 13 regression-test-changes}@anchor{852}
@subsection Regression Test Changes



@itemize *

@item 
Python built with @code{configure} @ref{853,,--with-pydebug} now
supports a @ref{178,,-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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 12,What’s New In Python 3 11,What’s New In Python 3 13,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 12 doc}@anchor{854}@anchor{whatsnew/3 12 translation-repo}@anchor{855}@anchor{whatsnew/3 12 what-s-new-in-python-3-12}@anchor{856}
@section What’s New In Python 3.12


@*Editor: 
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{145,,changelog}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 693
PEP 693@footnote{https://peps.python.org/pep-0693/} – Python 3.12 Release Schedule


@menu
* Summary – Release highlights: Summary – Release highlights<3>. 
* New Features: New Features<3>. 
* New Features Related to Type Hints:: 
* Other Language Changes: Other Language Changes<2>. 
* New Modules: New Modules<2>. 
* Improved Modules: Improved Modules<2>. 
* Optimizations: Optimizations<5>. 
* CPython bytecode changes: CPython bytecode changes<2>. 
* Demos and Tools:: 
* Deprecated: Deprecated<4>. 
* Removed: Removed<4>. 
* Porting to Python 3.12: Porting to Python 3 12. 
* Build Changes: Build Changes<2>. 
* C API Changes: C API Changes<2>. 

@end menu

@node Summary – Release highlights<3>,New Features<3>,,What’s New In Python 3 12
@anchor{whatsnew/3 12 summary-release-highlights}@anchor{857}
@subsection Summary – Release highlights


@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{a5,,os} and @ref{a8,,pathlib} has seen a number of improvements,
and several modules have better performance.

The language changes focus on usability,
as @ref{858,,f-strings} have had many limitations removed
and “Did you mean …” suggestions continue to improve.
The new @ref{859,,type parameter syntax}
and @ref{85a,,type} statement improve ergonomics for using @ref{1d1,,generic types} and @ref{85b,,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{3f7,,Library Reference}
and @ref{3f8,,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.

New syntax features:


@itemize *

@item 
@ref{859,,PEP 695}, type parameter syntax and the @ref{85a,,type} statement
@end itemize

New grammar features:


@itemize *

@item 
@ref{85c,,PEP 701}, @ref{858,,f-strings} in the grammar
@end itemize

Interpreter improvements:


@itemize *

@item 
@ref{85d,,PEP 684}, a unique per-interpreter @ref{685,,GIL}

@item 
@ref{85e,,PEP 669}, low impact monitoring

@item 
@ref{85f,,Improved 'Did you mean ...' suggestions}@anchor{whatsnew/3 12 improved-error-messages}@anchor{85f}
for @ref{665,,NameError}, @ref{1bd,,ImportError}, and @ref{17e,,SyntaxError} exceptions
@end itemize

Python data model improvements:


@itemize *

@item 
@ref{860,,PEP 688}, using the @ref{311,,buffer protocol} from Python
@end itemize

Significant improvements in the standard library:


@itemize *

@item 
The @ref{4ee,,pathlib.Path} class now supports subclassing

@item 
The @ref{a5,,os} module received several improvements for Windows support

@item 
A @ref{257,,command-line interface} has been added to the
@ref{d7,,sqlite3} module

@item 
@ref{2ef,,isinstance()} checks against @ref{861,,runtime-checkable protocols} enjoy a speed up of between two and 20 times

@item 
The @ref{b,,asyncio} package has had a number of performance improvements,
with some benchmarks showing a 75% speed up.

@item 
A @ref{862,,command-line interface} has been added to the
@ref{119,,uuid} module

@item 
Due to the changes in @ref{85c,,PEP 701},
producing tokens via the @ref{104,,tokenize} module is up to 64% faster.
@end itemize

Security improvements:


@itemize *

@item 
Replace the builtin @ref{6b,,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{863,,PEP 697}, unstable C API tier

@item 
@ref{864,,PEP 683}, immortal objects
@end itemize

CPython implementation improvements:


@itemize *

@item 
@ref{865,,PEP 709}, comprehension inlining

@item 
@ref{6b7,,CPython support} for the Linux @code{perf} profiler

@item 
Implement stack overflow protection on supported platforms
@end itemize

New typing features:


@itemize *

@item 
@ref{866,,PEP 692}, using @ref{290,,TypedDict} to
annotate @ref{867,,**kwargs}

@item 
@ref{868,,PEP 698}, @ref{869,,typing.override()} decorator
@end itemize

Important deprecations, removals or 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{1df,,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{11a,,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{86a,,activated}
virtual environment.

@item 
The @code{asynchat}, @code{asyncore}, and @code{imp} modules have been
removed, along with several @ref{52f,,unittest.TestCase}
@ref{86b,,method aliases}@anchor{whatsnew/3 12 unittest-testcase-removed-aliases}@anchor{86b}.
@end itemize

@node New Features<3>,New Features Related to Type Hints,Summary – Release highlights<3>,What’s New In Python 3 12
@anchor{whatsnew/3 12 new-features}@anchor{86c}
@subsection New Features


@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,,New Features<3>
@anchor{whatsnew/3 12 pep-695-type-parameter-syntax}@anchor{86d}@anchor{whatsnew/3 12 whatsnew312-pep695}@anchor{859}
@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{86e,,generic classes} and @ref{86f,,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{870,,type aliases}
using the @ref{85a,,type} statement, which creates an instance of
@ref{52a,,TypeAliasType}:

@example
type Point = tuple[float, float]
@end example

Type aliases can also be @ref{871,,generic}:

@example
type Point[T] = tuple[T, T]
@end example

The new syntax allows declaring @ref{293,,TypeVarTuple}
and @ref{295,,ParamSpec} parameters, as well as @ref{294,,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{872,,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{7a5,,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{6b4,,annotation scope}. Annotation scopes behave for the
most part like function scopes, but interact differently with enclosing class scopes.
In Python 3.13, @ref{409,,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,New Features<3>
@anchor{whatsnew/3 12 pep-701-syntactic-formalization-of-f-strings}@anchor{873}@anchor{whatsnew/3 12 whatsnew312-pep701}@anchor{85c}
@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{858,,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{17e,,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{874,,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{17e,,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,New Features<3>
@anchor{whatsnew/3 12 pep-684-a-per-interpreter-gil}@anchor{875}@anchor{whatsnew/3 12 whatsnew312-pep684}@anchor{85d}
@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{685,,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{876,,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,New Features<3>
@anchor{whatsnew/3 12 pep-669-low-impact-monitoring-for-cpython}@anchor{877}@anchor{whatsnew/3 12 whatsnew312-pep669}@anchor{85e}
@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{e3,,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  @code{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,New Features<3>
@anchor{whatsnew/3 12 pep-688-making-the-buffer-protocol-accessible-in-python}@anchor{878}@anchor{whatsnew/3 12 whatsnew312-pep688}@anchor{860}
@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{311,,buffer protocol}
from Python code. Classes that implement the @ref{879,,__buffer__()} method
are now usable as buffer types.

The new @ref{312,,collections.abc.Buffer} ABC provides a standard
way to represent buffer objects, for example in type annotations.
The new @ref{87a,,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,New Features<3>
@anchor{whatsnew/3 12 pep-709-comprehension-inlining}@anchor{87b}@anchor{whatsnew/3 12 whatsnew312-pep709}@anchor{865}
@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{e1,,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{28b,,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,New Features<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{665,,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{665,,NameError} exceptions for instances.
Now if a @code{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{17e,,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{1bd,,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 New Features Related to Type Hints,Other Language Changes<2>,New Features<3>,What’s New In Python 3 12
@anchor{whatsnew/3 12 new-features-related-to-type-hints}@anchor{87c}
@subsection New Features Related to Type Hints


This section covers major changes affecting 
@geindex Python Enhancement Proposals; PEP 484
type hints@footnote{https://peps.python.org/pep-0484/} and
the @ref{10d,,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,,New Features Related to Type Hints
@anchor{whatsnew/3 12 pep-692-using-typeddict-for-more-precise-kwargs-typing}@anchor{87d}@anchor{whatsnew/3 12 whatsnew312-pep692}@anchor{866}
@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,New Features Related to Type Hints
@anchor{whatsnew/3 12 pep-698-override-decorator-for-static-typing}@anchor{87e}@anchor{whatsnew/3 12 whatsnew312-pep698}@anchor{868}
@subsubsection PEP 698: Override Decorator for Static Typing


A new decorator @ref{869,,typing.override()} has been added to the @ref{10d,,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.

Example:

@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 Other Language Changes<2>,New Modules<2>,New Features Related to Type Hints,What’s New In Python 3 12
@anchor{whatsnew/3 12 other-language-changes}@anchor{87f}
@subsection Other Language Changes



@itemize *

@item 
The parser now raises @ref{17e,,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{44a,,SyntaxWarning}, instead of @ref{2c9,,DeprecationWarning}.
For example, @code{re.compile("\d+\.\d+")} now emits a @code{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{17e,,SyntaxError} will eventually be raised,
instead of @code{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{44a,,SyntaxWarning}, instead of
@ref{2c9,,DeprecationWarning}.
In a future Python version they will be eventually a @ref{17e,,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{30d,,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{6d8,,ExceptionGroup}
and raises one other exception, that exception is no longer wrapped in an
@code{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{880,,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{5ef,,bool} and @ref{326,,int}.
(Contributed by Serhiy Storchaka in gh-60203@footnote{https://github.com/python/cpython/issues/60203}.)

@item 
@ref{1d2,,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{1d0,,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{881,,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{1c9,,ast.parse()} now raises @ref{17e,,SyntaxError} instead of @ref{277,,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{e7,,tarfile}, and @ref{882,,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{883,,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{189,,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{6b7,,support for the perf profiler} through the new
environment variable 
@geindex PYTHONPERFSUPPORT
@geindex μεταβλητή περιβάλλοντος; PYTHONPERFSUPPORT
@ref{884,,PYTHONPERFSUPPORT}
and command-line option @ref{178,,-X perf},
as well as the new @ref{885,,sys.activate_stack_trampoline()},
@ref{886,,sys.deactivate_stack_trampoline()},
and @ref{887,,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 New Modules<2>,Improved Modules<2>,Other Language Changes<2>,What’s New In Python 3 12
@anchor{whatsnew/3 12 new-modules}@anchor{888}
@subsection New Modules



@itemize *

@item 
None.
@end itemize

@node Improved Modules<2>,Optimizations<5>,New Modules<2>,What’s New In Python 3 12
@anchor{whatsnew/3 12 improved-modules}@anchor{889}
@subsection Improved Modules


@menu
* array: array<3>. 
* asyncio: asyncio<6>. 
* calendar: calendar<3>. 
* csv: csv<2>. 
* dis: dis<3>. 
* fractions: fractions<3>. 
* importlib.resources: importlib resources<2>. 
* inspect: inspect<3>. 
* itertools: itertools<3>. 
* math: math<4>. 
* os: os<4>. 
* os.path: os path<4>. 
* pathlib: pathlib<7>. 
* platform: platform<3>. 
* pdb: pdb<5>. 
* random: random<2>. 
* shutil: shutil<2>. 
* sqlite3: sqlite3<4>. 
* statistics: statistics<2>. 
* sys: sys<4>. 
* tempfile: tempfile<2>. 
* threading: threading<4>. 
* tkinter: tkinter<4>. 
* tokenize: tokenize<2>. 
* types: types<5>. 
* typing: typing<6>. 
* unicodedata: unicodedata<4>. 
* unittest: unittest<4>. 
* uuid: uuid<3>. 

@end menu

@node array<3>,asyncio<6>,,Improved Modules<2>
@anchor{whatsnew/3 12 array}@anchor{88a}
@subsubsection array



@itemize *

@item 
The @ref{6c5,,array.array} class now supports subscripting, making it a
@ref{1d1,,generic type}. (Contributed by Jelle Zijlstra in gh-98658@footnote{https://github.com/python/cpython/issues/98658}.)
@end itemize

@node asyncio<6>,calendar<3>,array<3>,Improved Modules<2>
@anchor{whatsnew/3 12 asyncio}@anchor{88b}
@subsubsection asyncio



@itemize *

@item 
The performance of writing to sockets in @ref{b,,asyncio} has been
significantly improved. @code{asyncio} now avoids unnecessary copying when
writing to sockets and uses @ref{88c,,sendmsg()} if the platform
supports it. (Contributed by Kumar Aditya in gh-91166@footnote{https://github.com/python/cpython/issues/91166}.)

@item 
Add @ref{88d,,asyncio.eager_task_factory()} and @ref{88e,,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{b,,asyncio} uses @code{asyncio.PidfdChildWatcher} by default
if @ref{267,,os.pidfd_open()} is available and functional instead of
@code{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
(@code{asyncio.PidfdChildWatcher} if supported and
@code{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{309,,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{88f,,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{890,,asyncio.iscoroutine()} now returns @code{False} for generators as
@ref{b,,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{891,,asyncio.wait()} and @ref{6cc,,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<3>,csv<2>,asyncio<6>,Improved Modules<2>
@anchor{whatsnew/3 12 calendar}@anchor{892}
@subsubsection calendar



@itemize *

@item 
Add enums @ref{893,,calendar.Month} and @ref{894,,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<2>,dis<3>,calendar<3>,Improved Modules<2>
@anchor{whatsnew/3 12 csv}@anchor{895}
@subsubsection csv



@itemize *

@item 
Add @ref{896,,csv.QUOTE_NOTNULL} and @ref{897,,csv.QUOTE_STRINGS} flags to
provide finer grained control of @code{None} and empty strings by
@ref{898,,reader} and @ref{899,,writer} objects.
@end itemize

@node dis<3>,fractions<3>,csv<2>,Improved Modules<2>
@anchor{whatsnew/3 12 dis}@anchor{89a}
@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{3b,,dis} module.
@ref{89b,,HAVE_ARGUMENT} is still relevant to real opcodes,
but it is not useful for pseudo instructions. Use the new
@ref{79e,,dis.hasarg} collection instead.
(Contributed by Irit Katriel in gh-94216@footnote{https://github.com/python/cpython/issues/94216}.)

@item 
Add the @ref{89c,,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<3>,importlib resources<2>,dis<3>,Improved Modules<2>
@anchor{whatsnew/3 12 fractions}@anchor{89d}
@subsubsection fractions



@itemize *

@item 
Objects of type @ref{1c3,,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<2>,inspect<3>,fractions<3>,Improved Modules<2>
@anchor{whatsnew/3 12 importlib-resources}@anchor{89e}
@subsubsection importlib.resources



@itemize *

@item 
@ref{89f,,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{2d7,,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<3>,itertools<3>,importlib resources<2>,Improved Modules<2>
@anchor{whatsnew/3 12 inspect}@anchor{8a0}
@subsubsection inspect



@itemize *

@item 
Add @ref{8a1,,inspect.markcoroutinefunction()} to mark sync functions that return
a @ref{8a2,,coroutine} for use with @ref{302,,inspect.iscoroutinefunction()}.
(Contributed by Carlton Gibson in gh-99247@footnote{https://github.com/python/cpython/issues/99247}.)

@item 
Add @ref{8a3,,inspect.getasyncgenstate()} and @ref{8a4,,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{8a5,,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<3>,math<4>,inspect<3>,Improved Modules<2>
@anchor{whatsnew/3 12 itertools}@anchor{8a6}
@subsubsection itertools



@itemize *

@item 
Add @ref{715,,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<4>,os<4>,itertools<3>,Improved Modules<2>
@anchor{whatsnew/3 12 math}@anchor{8a7}
@subsubsection math



@itemize *

@item 
Add @ref{8a8,,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{8a9,,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<4>,os path<4>,math<4>,Improved Modules<2>
@anchor{whatsnew/3 12 os}@anchor{8aa}
@subsubsection os



@itemize *

@item 
Add @ref{8ab,,os.PIDFD_NONBLOCK} to open a file descriptor
for a process with @ref{267,,os.pidfd_open()} in non-blocking mode.
(Contributed by Kumar Aditya in gh-93312@footnote{https://github.com/python/cpython/issues/93312}.)

@item 
@ref{8ac,,os.DirEntry} now includes an @ref{8ad,,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{8ae,,os.listdrives()}, @ref{8af,,os.listvolumes()} and @ref{8b0,,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{4f5,,os.stat()} and @ref{8b1,,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<4>,pathlib<7>,os<4>,Improved Modules<2>
@anchor{whatsnew/3 12 os-path}@anchor{8b2}
@subsubsection os.path



@itemize *

@item 
Add @ref{8b3,,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{8b4,,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<7>,platform<3>,os path<4>,Improved Modules<2>
@anchor{whatsnew/3 12 pathlib}@anchor{8b5}
@subsubsection pathlib



@itemize *

@item 
Add support for subclassing @ref{8b6,,pathlib.PurePath} and
@ref{4ee,,pathlib.Path}, plus their Posix- and Windows-specific variants.
Subclasses may override the @ref{8b7,,pathlib.PurePath.with_segments()} method
to pass information between path instances.

@item 
Add @ref{8b8,,pathlib.Path.walk()} for walking the directory trees and generating
all file or directory names within them, similar to @ref{8b9,,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{575,,pathlib.PurePath.relative_to()}
to allow the insertion of @code{..} entries in the result; this behavior is
more consistent with @ref{8ba,,os.path.relpath()}.
(Contributed by Domenico Ragusa in gh-84538@footnote{https://github.com/python/cpython/issues/84538}.)

@item 
Add @ref{8bb,,pathlib.Path.is_junction()} as a proxy to @ref{8b3,,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{73a,,pathlib.Path.glob()},
@ref{73b,,pathlib.Path.rglob()} and @ref{8bc,,pathlib.PurePath.match()} for matching
the path’s case sensitivity, allowing for more precise control over the matching process.
@end itemize

@node platform<3>,pdb<5>,pathlib<7>,Improved Modules<2>
@anchor{whatsnew/3 12 platform}@anchor{8bd}
@subsubsection platform



@itemize *

@item 
Add support for detecting Windows 11 and Windows Server releases past 2012.
Previously, lookups on Windows Server platforms newer than Windows Server 2012
and on Windows 11 would return @code{Windows-10}.
(Contributed by Steve Dower in gh-89545@footnote{https://github.com/python/cpython/issues/89545}.)
@end itemize

@node pdb<5>,random<2>,platform<3>,Improved Modules<2>
@anchor{whatsnew/3 12 pdb}@anchor{8be}
@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>,shutil<2>,pdb<5>,Improved Modules<2>
@anchor{whatsnew/3 12 random}@anchor{8bf}
@subsubsection random



@itemize *

@item 
Add @ref{8c0,,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{8c1,,random.expovariate()}.
(Contributed by Raymond Hettinger in gh-100234@footnote{https://github.com/python/cpython/issues/100234}.)
@end itemize

@node shutil<2>,sqlite3<4>,random<2>,Improved Modules<2>
@anchor{whatsnew/3 12 shutil}@anchor{8c2}
@subsubsection shutil



@itemize *

@item 
@ref{8c3,,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{335,,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{8c4,,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{8c4,,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{8c4,,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<4>,statistics<2>,shutil<2>,Improved Modules<2>
@anchor{whatsnew/3 12 sqlite3}@anchor{8c5}
@subsubsection sqlite3



@itemize *

@item 
Add a @ref{257,,command-line interface}.
(Contributed by Erlend E. Aasland in gh-77617@footnote{https://github.com/python/cpython/issues/77617}.)

@item 
Add the @ref{8c6,,sqlite3.Connection.autocommit} attribute
to @ref{3df,,sqlite3.Connection}
and the `autocommit' parameter to @ref{3e0,,sqlite3.connect()}
to control 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}-compliant
@ref{8c7,,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{8c8,,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{8c9,,sqlite3.Connection.getconfig()} and
@ref{8ca,,sqlite3.Connection.setconfig()} to @ref{3df,,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<4>,sqlite3<4>,Improved Modules<2>
@anchor{whatsnew/3 12 statistics}@anchor{8cb}
@subsubsection statistics



@itemize *

@item 
Extend @ref{8cc,,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<4>,tempfile<2>,statistics<2>,Improved Modules<2>
@anchor{whatsnew/3 12 sys}@anchor{8cd}
@subsubsection sys



@itemize *

@item 
Add the @ref{e3,,sys.monitoring} namespace to expose the new @ref{85e,,PEP 669} monitoring API.
(Contributed by Mark Shannon in gh-103082@footnote{https://github.com/python/cpython/issues/103082}.)

@item 
Add @ref{885,,sys.activate_stack_trampoline()} and
@ref{886,,sys.deactivate_stack_trampoline()} for activating and deactivating
stack profiler trampolines,
and @ref{887,,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{8ce,,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{8cf,,sys.last_type}, @ref{8d0,,sys.last_value} and @ref{8d1,,sys.last_traceback}.
(Contributed by Irit Katriel in gh-102778@footnote{https://github.com/python/cpython/issues/102778}.)

@item 
@ref{8d2,,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{8d3,,sys.setrecursionlimit()} and @ref{8d4,,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<4>,sys<4>,Improved Modules<2>
@anchor{whatsnew/3 12 tempfile}@anchor{8d5}
@subsubsection tempfile



@itemize *

@item 
The @ref{8d6,,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{730,,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<4>,tkinter<4>,tempfile<2>,Improved Modules<2>
@anchor{whatsnew/3 12 threading}@anchor{8d7}
@subsubsection threading



@itemize *

@item 
Add @ref{8d8,,threading.settrace_all_threads()} and
@ref{8d9,,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<4>,tokenize<2>,threading<4>,Improved Modules<2>
@anchor{whatsnew/3 12 tkinter}@anchor{8da}
@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<2>,types<5>,tkinter<4>,Improved Modules<2>
@anchor{whatsnew/3 12 tokenize}@anchor{8db}
@subsubsection tokenize



@itemize *

@item 
The @ref{104,,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{8dc,,Porting to Python 3.12} for more information on the
changes to the @code{tokenize} module.
@end itemize

@node types<5>,typing<6>,tokenize<2>,Improved Modules<2>
@anchor{whatsnew/3 12 types}@anchor{8dd}
@subsubsection types



@itemize *

@item 
Add @ref{8de,,types.get_original_bases()} to allow for further introspection of
@ref{8df,,User-defined generic types} 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<6>,unicodedata<4>,types<5>,Improved Modules<2>
@anchor{whatsnew/3 12 typing}@anchor{8e0}@anchor{whatsnew/3 12 whatsnew-typing-py312}@anchor{8e1}
@subsubsection typing



@itemize *

@item 
@ref{2ef,,isinstance()} checks against
@ref{861,,runtime-checkable protocols} now use
@ref{8a5,,inspect.getattr_static()} rather than @ref{8e2,,hasattr()} to lookup whether
attributes exist. This means that descriptors and @ref{8e3,,__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{2ef,,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{2ef,,isinstance()} checks against
@ref{861,,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{290,,typing.TypedDict} and @ref{2e4,,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{8e4,,typing.dataclass_transform()}.
(Contributed by Erik De Bonte in gh-99957@footnote{https://github.com/python/cpython/issues/99957}.)
@end itemize

@node unicodedata<4>,unittest<4>,typing<6>,Improved Modules<2>
@anchor{whatsnew/3 12 unicodedata}@anchor{8e5}
@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<4>,uuid<3>,unicodedata<4>,Improved Modules<2>
@anchor{whatsnew/3 12 unittest}@anchor{8e6}
@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<3>,,unittest<4>,Improved Modules<2>
@anchor{whatsnew/3 12 uuid}@anchor{8e7}
@subsubsection uuid



@itemize *

@item 
Add a @ref{862,,command-line interface}.
(Contributed by Adam Chhina in gh-88597@footnote{https://github.com/python/cpython/issues/88597}.)
@end itemize

@node Optimizations<5>,CPython bytecode changes<2>,Improved Modules<2>,What’s New In Python 3 12
@anchor{whatsnew/3 12 optimizations}@anchor{8e8}
@subsection Optimizations



@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{7a1,,re.sub()} and
@ref{7a2,,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{460,,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{8e9,,tokenize.tokenize()} and @ref{8ea,,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{104,,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{443,,super()} method calls and attribute loads via the
new @ref{8eb,,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 CPython bytecode changes<2>,Demos and Tools,Optimizations<5>,What’s New In Python 3 12
@anchor{whatsnew/3 12 cpython-bytecode-changes}@anchor{8ec}
@subsection CPython bytecode changes



@itemize *

@item 
Remove the @code{LOAD_METHOD} instruction. It has been merged into
@ref{8ed,,LOAD_ATTR}. @code{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{8ee,,BINARY_SLICE} and @ref{8ef,,STORE_SLICE} instructions.
(Contributed by Mark Shannon in gh-94163@footnote{https://github.com/python/cpython/issues/94163}.)

@item 
Add the @ref{8f0,,CALL_INTRINSIC_1} instructions.
(Contributed by Mark Shannon in gh-99005@footnote{https://github.com/python/cpython/issues/99005}.)

@item 
Add the @ref{8f1,,CALL_INTRINSIC_2} instruction.
(Contributed by Irit Katriel in gh-101799@footnote{https://github.com/python/cpython/issues/101799}.)

@item 
Add the @ref{8f2,,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{8f3,,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{8f4,,LOAD_FAST_CHECK} instruction.
(Contributed by Dennis Sweeney in gh-93143@footnote{https://github.com/python/cpython/issues/93143}.)

@item 
Add the @ref{8f5,,LOAD_FROM_DICT_OR_DEREF}, @ref{8f6,,LOAD_FROM_DICT_OR_GLOBALS},
and @ref{8f7,,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
@code{LOAD_LOCALS} plus @code{LOAD_FROM_DICT_OR_DEREF}. (Contributed
by Jelle Zijlstra in gh-103764@footnote{https://github.com/python/cpython/issues/103764}.)

@item 
Add the @ref{8eb,,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 @code{RETURN_CONST} instruction. (Contributed by Wenyang Wang in gh-101632@footnote{https://github.com/python/cpython/issues/101632}.)
@end itemize

@node Demos and Tools,Deprecated<4>,CPython bytecode changes<2>,What’s New In Python 3 12
@anchor{whatsnew/3 12 demos-and-tools}@anchor{8f8}
@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 Deprecated<4>,Removed<4>,Demos and Tools,What’s New In Python 3 12
@anchor{whatsnew/3 12 deprecated}@anchor{8f9}
@subsection Deprecated



@itemize *

@item 
@ref{7,,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{9,,ast}: The following @code{ast} features have been deprecated in documentation since
Python 3.8, now cause a @ref{2c9,,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{569,,ast.Constant} instead.
(Contributed by Serhiy Storchaka in gh-90953@footnote{https://github.com/python/cpython/issues/90953}.)

@item 
@ref{b,,asyncio}:


@itemize *

@item 
The child watcher classes @code{asyncio.MultiLoopChildWatcher},
@code{asyncio.FastChildWatcher}, @code{asyncio.AbstractChildWatcher}
and @code{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 
@code{asyncio.set_child_watcher()}, @code{asyncio.get_child_watcher()},
@code{asyncio.AbstractEventLoopPolicy.set_child_watcher()} and
@code{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{56c,,get_event_loop()} method of the
default event loop policy now emits a @ref{2c9,,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{15,,calendar}: @code{calendar.January} and @code{calendar.February} constants are deprecated and
replaced by @ref{329,,calendar.JANUARY} and @ref{32a,,calendar.FEBRUARY}.
(Contributed by Prince Roshan in gh-103636@footnote{https://github.com/python/cpython/issues/103636}.)

@item 
@ref{1f,,collections.abc}: Deprecated @ref{2cb,,collections.abc.ByteString}.

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj} implements
the @ref{311,,buffer protocol} at runtime. For use in type
annotations, either use @ref{312,,Buffer} or a union
that explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} was originally intended to be an abstract class that
would serve as a supertype of both @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
However, since the ABC never had any methods, knowing that an object was an
instance of @code{ByteString} never actually told you anything useful
about the object. Other common buffer types such as @ref{1d2,,memoryview} were
also never understood as subtypes of @code{ByteString} (either at
runtime or by static type checkers).

See 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} for more details.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)

@item 
@ref{33,,datetime}: @ref{6e7,,datetime.datetime}’s @ref{32e,,utcnow()} and
@ref{32f,,utcfromtimestamp()} are deprecated and will be
removed in a future version. Instead, use timezone-aware objects to represent
datetimes in UTC: respectively, call @ref{8fa,,now()} and
@ref{8fb,,fromtimestamp()}  with the `tz' parameter set to
@ref{8fc,,datetime.UTC}.
(Contributed by Paul Ganssle in gh-103857@footnote{https://github.com/python/cpython/issues/103857}.)

@item 
@ref{3e,,email}: Deprecate the `isdst' parameter in @ref{56f,,email.utils.localtime()}.
(Contributed by Alan Williams in gh-72346@footnote{https://github.com/python/cpython/issues/72346}.)

@item 
@ref{7b,,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{7f,,importlib.resources.abc} classes instead:


@itemize *

@item 
@ref{572,,importlib.resources.abc.Traversable}

@item 
@ref{571,,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{84,,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{98,,multiprocessing}: In Python 3.14, the default @code{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{4d6,,get_context()} or
@ref{4d7,,set_start_method()} APIs to explicitly specify when
your code `requires' @code{'fork'}.  See @ref{46d,,contexts and start methods}.

@item 
@ref{ae,,pkgutil}: @code{pkgutil.find_loader()} and @code{pkgutil.get_loader()}
are deprecated and will be removed in Python 3.14;
use @ref{7a7,,importlib.util.find_spec()} instead.
(Contributed by Nikita Sobolev in gh-97850@footnote{https://github.com/python/cpython/issues/97850}.)

@item 
@ref{b9,,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{2c9,,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{a5,,os}:


@itemize *

@item 
The @code{st_ctime} fields return by @ref{4f5,,os.stat()} and @ref{8b1,,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{6bd,,os.fork()} can now raise a
@ref{2c9,,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 @code{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{98,,multiprocessing} or
@ref{24,,concurrent.futures} the fix is to use a different
@code{multiprocessing} start method such as @code{"spawn"} or @code{"forkserver"}.

@item 
@ref{cd,,shutil}: The `onerror' argument of @ref{335,,shutil.rmtree()} is deprecated;
use `onexc' instead. (Contributed by Irit Katriel in gh-102828@footnote{https://github.com/python/cpython/issues/102828}.)

@item 
@ref{d7,,sqlite3}:


@itemize *

@item 
@ref{8fd,,default adapters and converters} are now deprecated.
Instead, use the @ref{8fe,,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{7a8,,execute()}, @ref{2c9,,DeprecationWarning} is now emitted
when @ref{7aa,,named placeholders} are used together with
parameters supplied as a @ref{8ff,,sequence} instead of as a @ref{188,,dict}.
Starting from Python 3.14, using named placeholders with parameters supplied
as a sequence will raise a @ref{57d,,ProgrammingError}.
(Contributed by Erlend E. Aasland in gh-101698@footnote{https://github.com/python/cpython/issues/101698}.)
@end itemize

@item 
@ref{e2,,sys}: The @ref{8cf,,sys.last_type}, @ref{8d0,,sys.last_value} and @ref{8d1,,sys.last_traceback}
fields are deprecated. Use @ref{8ce,,sys.last_exc} instead.
(Contributed by Irit Katriel in gh-102778@footnote{https://github.com/python/cpython/issues/102778}.)

@item 
@ref{e7,,tarfile}: Extracting tar archives without specifying `filter' is deprecated until
Python 3.14, when @code{'data'} filter will become the default.
See @ref{883,,Extraction filters} for details.

@item 
@ref{10d,,typing}:


@itemize *

@item 
@ref{900,,typing.Hashable} and @ref{901,,typing.Sized}, aliases for
@ref{902,,collections.abc.Hashable} and @ref{903,,collections.abc.Sized} respectively, are
deprecated. (gh-94309@footnote{https://github.com/python/cpython/issues/94309}.)

@item 
@ref{2e3,,typing.ByteString}, deprecated since Python 3.9, now causes a
@ref{2c9,,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{12e,,xml.etree.ElementTree}: The module now emits @ref{2c9,,DeprecationWarning}
when testing the truth value of an @ref{343,,xml.etree.ElementTree.Element}.
Before, the Python implementation emitted @ref{847,,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{904,,coroutine throw()}, @ref{905,,generator throw()} and
@ref{906,,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{2c9,,DeprecationWarning} is now raised when @ref{58c,,__package__} on a
module differs from
@ref{58d,,__spec__.parent} (previously
it was @ref{907,,ImportWarning}).
(Contributed by Brett Cannon in gh-65961@footnote{https://github.com/python/cpython/issues/65961}.)

@item 
Setting @ref{58c,,__package__} or @code{__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 @code{codeobject.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{2c9,,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<5>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<6>. 
* Pending removal in Python 3.17: Pending removal in Python 3 17<4>. 
* Pending removal in Python 3.19: Pending removal in Python 3 19<4>. 
* Pending removal in Python 3.20: Pending removal in Python 3 20<4>. 
* Pending removal in future versions: Pending removal in future versions<6>. 

@end menu

@node Pending removal in Python 3 13,Pending removal in Python 3 14<3>,,Deprecated<4>
@anchor{whatsnew/3 12 pending-removal-in-python-3-13}@anchor{908}
@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{69a,,classmethod} descriptor chaining (gh-89519@footnote{https://github.com/python/cpython/issues/89519})
@end itemize

@node Pending removal in Python 3 14<3>,Pending removal in Python 3 15<5>,Pending removal in Python 3 13,Deprecated<4>
@anchor{whatsnew/3 12 pending-removal-in-python-3-14}@anchor{909}
@subsubsection Pending removal in Python 3.14



@itemize *

@item 
@ref{7,,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{9,,ast}: The following features have been deprecated in documentation
since Python 3.8, now cause a @ref{2c9,,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{569,,ast.Constant} instead.
(Contributed by Serhiy Storchaka in gh-90953@footnote{https://github.com/python/cpython/issues/90953}.)

@item 
@ref{b,,asyncio}:


@itemize *

@item 
The child watcher classes @code{asyncio.MultiLoopChildWatcher},
@code{asyncio.FastChildWatcher}, @code{asyncio.AbstractChildWatcher}
and @code{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 
@code{asyncio.set_child_watcher()}, @code{asyncio.get_child_watcher()},
@code{asyncio.AbstractEventLoopPolicy.set_child_watcher()} and
@code{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{56c,,get_event_loop()} method of the
default event loop policy now emits a @ref{2c9,,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{3e,,email}: Deprecated the `isdst' parameter in @ref{56f,,email.utils.localtime()}.
(Contributed by Alan Williams in gh-72346@footnote{https://github.com/python/cpython/issues/72346}.)

@item 
@ref{7b,,importlib.abc} deprecated classes:


@itemize *

@item 
@code{importlib.abc.ResourceReader}

@item 
@code{importlib.abc.Traversable}

@item 
@code{importlib.abc.TraversableResources}
@end itemize

Use @ref{7f,,importlib.resources.abc} classes instead:


@itemize *

@item 
@ref{572,,importlib.resources.abc.Traversable}

@item 
@ref{571,,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{84,,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{98,,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{4d6,,get_context()} or
@ref{4d7,,set_start_method()} APIs to explicitly specify when
your code `requires' @code{'fork'}.  See @ref{46d,,Contexts and start methods}.

@item 
@ref{a8,,pathlib}: @ref{576,,is_relative_to()} and
@ref{575,,relative_to()}: passing additional arguments is
deprecated.

@item 
@ref{ae,,pkgutil}: @code{pkgutil.find_loader()} and @code{pkgutil.get_loader()}
now raise @ref{2c9,,DeprecationWarning};
use @ref{7a7,,importlib.util.find_spec()} instead.
(Contributed by Nikita Sobolev in gh-97850@footnote{https://github.com/python/cpython/issues/97850}.)

@item 
@ref{b9,,pty}:


@itemize *

@item 
@code{master_open()}: use @ref{579,,pty.openpty()}.

@item 
@code{slave_open()}: use @ref{579,,pty.openpty()}.
@end itemize

@item 
@ref{d7,,sqlite3}:


@itemize *

@item 
@code{version} and @code{version_info}.

@item 
@ref{7a8,,execute()} and @ref{7a9,,executemany()}
if @ref{7aa,,named placeholders} are used and
`parameters' is a sequence instead of a @ref{188,,dict}.
@end itemize

@item 
@ref{111,,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<6>,Pending removal in Python 3 14<3>,Deprecated<4>
@anchor{whatsnew/3 12 pending-removal-in-python-3-15}@anchor{90a}
@subsubsection Pending removal in Python 3.15



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @code{__cached__} on a module while
failing to set @ref{58b,,__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{58c,,__package__} on a module while
failing to set @ref{58d,,__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{2d,,ctypes}:


@itemize *

@item 
The undocumented @code{ctypes.SetPointerType()} function
has been deprecated since Python 3.13.
@end itemize

@item 
@ref{75,,http.server}:


@itemize *

@item 
The obsolete and rarely used @code{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{7a,,importlib}:


@itemize *

@item 
@code{load_module()} method: use @code{exec_module()} instead.
@end itemize

@item 
@ref{a8,,pathlib}:


@itemize *

@item 
@code{.PurePath.is_reserved()}
has been deprecated since Python 3.13.
Use @ref{2d9,,os.path.isreserved()} to detect reserved paths on Windows.
@end itemize

@item 
@ref{af,,platform}:


@itemize *

@item 
@code{platform.java_ver()} has been deprecated since Python 3.13.
This function is only useful for Jython support, has a confusing API,
and is largely untested.
@end itemize

@item 
@ref{e4,,sysconfig}:


@itemize *

@item 
The `check_home' argument of @ref{2dd,,sysconfig.is_python_build()} has been
deprecated since Python 3.12.
@end itemize

@item 
@ref{f6,,threading}:


@itemize *

@item 
@ref{2df,,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{10c,,types}:


@itemize *

@item 
@ref{2e1,,types.CodeType}: Accessing @code{codeobject.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{2c9,,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{10d,,typing}:


@itemize *

@item 
The undocumented keyword argument syntax for creating
@ref{2e4,,NamedTuple} classes
(for example, @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 
When using the functional syntax of @ref{290,,TypedDict}s, failing
to pass a value to the `fields' parameter (@code{TD = TypedDict("TD")}) or
passing @code{None} (@code{TD = TypedDict("TD", None)}) has been deprecated
since Python 3.13.
Use @code{class TD(TypedDict): pass} or @code{TD = TypedDict("TD", @{@})}
to create a TypedDict with zero field.

@item 
The @code{typing.no_type_check_decorator()} decorator function
has been deprecated since Python 3.13.
After eight years in the @ref{10d,,typing} module,
it has yet to be supported by any major type checker.
@end itemize

@item 
@code{sre_compile}, @code{sre_constants} and @code{sre_parse} modules.

@item 
@ref{11c,,wave}:


@itemize *

@item 
The @code{getmark()}, @code{setmark()} and @code{getmarkers()} methods of
the @ref{2e6,,Wave_read} and @ref{2e7,,Wave_write} classes
have been deprecated since Python 3.13.
@end itemize

@item 
@ref{13b,,zipimport}:


@itemize *

@item 
@code{zipimport.zipimporter.load_module()} has been deprecated since
Python 3.10. Use @ref{2e9,,exec_module()} instead.
(gh-125746@footnote{https://github.com/python/cpython/issues/125746}.)
@end itemize
@end itemize

@node Pending removal in Python 3 16<6>,Pending removal in Python 3 17<4>,Pending removal in Python 3 15<5>,Deprecated<4>
@anchor{whatsnew/3 12 pending-removal-in-python-3-16}@anchor{90b}
@subsubsection Pending removal in Python 3.16



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @ref{2ff,,__loader__} on a module while
failing to set @ref{300,,__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{8,,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{301,,Py_UCS4})
for Unicode characters instead.
@end itemize

@item 
@ref{b,,asyncio}:


@itemize *

@item 
@code{asyncio.iscoroutinefunction()} is deprecated
and will be removed in Python 3.16;
use @ref{302,,inspect.iscoroutinefunction()} instead.
(Contributed by Jiahao Li and Kumar Aditya in gh-122875@footnote{https://github.com/python/cpython/issues/122875}.)

@item 
@ref{b,,asyncio} policy system is deprecated and will be removed in Python 3.16.
In particular, the following classes and functions are deprecated:


@itemize *

@item 
@ref{303,,asyncio.AbstractEventLoopPolicy}

@item 
@ref{304,,asyncio.DefaultEventLoopPolicy}

@item 
@ref{305,,asyncio.WindowsSelectorEventLoopPolicy}

@item 
@ref{306,,asyncio.WindowsProactorEventLoopPolicy}

@item 
@ref{307,,asyncio.get_event_loop_policy()}

@item 
@ref{308,,asyncio.set_event_loop_policy()}
@end itemize

Users should use @ref{309,,asyncio.run()} or @ref{30a,,asyncio.Runner} with
`loop_factory' to use the desired event loop implementation.

For example, to use @ref{30b,,asyncio.SelectorEventLoop} on Windows:

@example
import asyncio

async def main():
    ...

asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
@end example

(Contributed by Kumar Aditya in gh-127949@footnote{https://github.com/python/cpython/issues/127949}.)
@end itemize

@item 
@ref{13,,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{62,,functools}:


@itemize *

@item 
Calling the Python implementation of @ref{153,,functools.reduce()} with `function'
or `sequence' as keyword arguments has been deprecated since Python 3.14.
@end itemize

@item 
@ref{8a,,logging}:


@itemize *

@item 
Support for custom logging handlers with the `strm' argument is deprecated
and scheduled for removal in Python 3.16. Define handlers with the `stream'
argument instead. (Contributed by Mariusz Felisiak in gh-115032@footnote{https://github.com/python/cpython/issues/115032}.)
@end itemize

@item 
@ref{93,,mimetypes}:


@itemize *

@item 
Valid extensions start with a “.” or are empty for
@ref{30c,,mimetypes.MimeTypes.add_type()}.
Undotted extensions are deprecated and will
raise a @ref{277,,ValueError} in Python 3.16.
(Contributed by Hugo van Kemenade in gh-75223@footnote{https://github.com/python/cpython/issues/75223}.)
@end itemize

@item 
@ref{cd,,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{30d,,RuntimeError}.
@end itemize

@item 
@ref{e1,,symtable}:


@itemize *

@item 
The @code{symtable.Class.get_methods()} method
has been deprecated since Python 3.14.
@end itemize

@item 
@ref{e2,,sys}:


@itemize *

@item 
The @ref{30e,,_enablelegacywindowsfsencoding()} function
has been deprecated since Python 3.13.
Use the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,PYTHONLEGACYWINDOWSFSENCODING} environment variable instead.
@end itemize

@item 
@ref{e4,,sysconfig}:


@itemize *

@item 
The @code{sysconfig.expand_makefile_vars()} function
has been deprecated since Python 3.14.
Use the @code{vars} argument of @ref{156,,sysconfig.get_paths()} instead.
@end itemize

@item 
@ref{e7,,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 Python 3 17<4>,Pending removal in Python 3 19<4>,Pending removal in Python 3 16<6>,Deprecated<4>
@anchor{whatsnew/3 12 pending-removal-in-python-3-17}@anchor{90c}
@subsubsection Pending removal in Python 3.17



@itemize *

@item 
@ref{33,,datetime}:


@itemize *

@item 
@ref{2d2,,strptime()} calls using a format string containing
@code{%e} (day of month) without a year.
This has been deprecated since Python 3.15.
(Contributed by Stan Ulbrych in gh-70647@footnote{https://github.com/python/cpython/issues/70647}.)
@end itemize

@item 
@ref{1f,,collections.abc}:


@itemize -

@item 
@ref{2cb,,collections.abc.ByteString} is scheduled for removal in Python 3.17.

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj}
implements the @ref{311,,buffer protocol} at runtime. For use
in type annotations, either use @ref{312,,Buffer} or a union
that explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} was originally intended to be an abstract class that
would serve as a supertype of both @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
However, since the ABC never had any methods, knowing that an object was an
instance of @code{ByteString} never actually told you anything useful
about the object. Other common buffer types such as @ref{1d2,,memoryview}
were also never understood as subtypes of @code{ByteString} (either at
runtime or by static type checkers).

See 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} for more details.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)
@end itemize

@item 
@ref{54,,encodings}:


@itemize -

@item 
Passing non-ascii `encoding' names to @ref{313,,encodings.normalize_encoding()}
is deprecated and scheduled for removal in Python 3.17.
(Contributed by Stan Ulbrych in gh-136702@footnote{https://github.com/python/cpython/issues/136702}.)
@end itemize

@item 
@ref{11e,,webbrowser}:


@itemize -

@item 
@code{webbrowser.MacOSXOSAScript} is deprecated in favour of
@code{webbrowser.MacOS}. (gh-137586@footnote{https://github.com/python/cpython/issues/137586})
@end itemize

@item 
@ref{10d,,typing}:


@itemize -

@item 
Before Python 3.14, old-style unions were implemented using the private class
@code{typing._UnionGenericAlias}. This class is no longer needed for the implementation,
but it has been retained for backward compatibility, with removal scheduled for Python
3.17. Users should use documented introspection helpers like @ref{314,,typing.get_origin()}
and @ref{315,,typing.get_args()} instead of relying on private implementation details.

@item 
@ref{2e3,,typing.ByteString}, deprecated since Python 3.9, is scheduled for removal in
Python 3.17.

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj}
implements the @ref{311,,buffer protocol} at runtime. For use
in type annotations, either use @ref{312,,Buffer} or a union
that explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} was originally intended to be an abstract class that
would serve as a supertype of both @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
However, since the ABC never had any methods, knowing that an object was an
instance of @code{ByteString} never actually told you anything useful
about the object. Other common buffer types such as @ref{1d2,,memoryview}
were also never understood as subtypes of @code{ByteString} (either at
runtime or by static type checkers).

See 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} for more details.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)
@end itemize
@end itemize

@node Pending removal in Python 3 19<4>,Pending removal in Python 3 20<4>,Pending removal in Python 3 17<4>,Deprecated<4>
@anchor{whatsnew/3 12 pending-removal-in-python-3-19}@anchor{90d}
@subsubsection Pending removal in Python 3.19



@itemize *

@item 
@ref{2d,,ctypes}:


@itemize *

@item 
Implicitly switching to the MSVC-compatible struct layout by setting
@ref{318,,_pack_} but not @ref{319,,_layout_}
on non-Windows platforms.
@end itemize

@item 
@ref{6b,,hashlib}:


@itemize -

@item 
In hash function constructors such as @ref{2f1,,new()} or the
direct hash-named constructors such as @ref{2f2,,md5()} and
@ref{2f3,,sha256()}, their optional initial data parameter could
also be passed a keyword argument named @code{data=} or @code{string=} in
various @code{hashlib} implementations.

Support for the @code{string} keyword argument name is now deprecated
and slated for removal in Python 3.19.

Before Python 3.13, the @code{string} keyword parameter was not correctly
supported depending on the backend implementation of hash functions.
Prefer passing the initial data as a positional argument for maximum
backwards compatibility.
@end itemize

@item 
@ref{74,,http.cookies}:


@itemize *

@item 
@ref{2f4,,http.cookies.Morsel.js_output()} is deprecated and will be
removed in Python 3.19.

@item 
@ref{2f5,,http.cookies.BaseCookie.js_output()} is deprecated and will be
removed in Python 3.19.
@end itemize

@item 
@ref{77,,imaplib}:


@itemize *

@item 
Altering @ref{2f8,,IMAP4.file} is now deprecated
and slated for removal in Python 3.19. This property is now unused
and changing its value does not automatically close the current file.

Before Python 3.14, this property was used to implement the corresponding
@code{read()} and @code{readline()} methods for @ref{31a,,IMAP4} but this
is no longer the case since then.
@end itemize
@end itemize

@node Pending removal in Python 3 20<4>,Pending removal in future versions<6>,Pending removal in Python 3 19<4>,Deprecated<4>
@anchor{whatsnew/3 12 pending-removal-in-python-3-20}@anchor{90e}
@subsubsection Pending removal in Python 3.20



@itemize *

@item 
Calling the @code{__new__()} method of @ref{2fb,,struct.Struct} without the
`format' argument is deprecated and will be removed in Python 3.20.  Calling
@ref{2fa,,__init__()} method on initialized @code{Struct}
objects is deprecated and will be removed in Python 3.20.

(Contributed by Sergey B Kirpichev and Serhiy Storchaka in gh-143715@footnote{https://github.com/python/cpython/issues/143715}.)

@item 
The @code{__version__}, @code{version} and @code{VERSION} attributes have been
deprecated in these standard library modules and will be removed in
Python 3.20. Use @ref{2fc,,sys.version_info} instead.


@itemize -

@item 
@ref{7,,argparse}

@item 
@ref{2c,,csv}

@item 
@ref{2d,,ctypes}

@item 
@code{ctypes.macholib}

@item 
@ref{39,,decimal} (use @ref{2fd,,decimal.SPEC_VERSION} instead)

@item 
@ref{75,,http.server}

@item 
@ref{77,,imaplib}

@item 
@ref{83,,ipaddress}

@item 
@ref{85,,json}

@item 
@ref{8a,,logging} (@code{__date__} also deprecated)

@item 
@ref{a4,,optparse}

@item 
@ref{ab,,pickle}

@item 
@ref{af,,platform}

@item 
@ref{c1,,re}

@item 
@ref{d5,,socketserver}

@item 
@ref{e6,,tabnanny}

@item 
@ref{e7,,tarfile}

@item 
@ref{fe,,tkinter.font}

@item 
@ref{102,,tkinter.ttk}

@item 
@ref{124,,wsgiref.simple_server}

@item 
@ref{12e,,xml.etree.ElementTree}

@item 
@code{xml.sax.expatreader}

@item 
@ref{133,,xml.sax.handler}

@item 
@ref{13c,,zlib}
@end itemize

(Contributed by Hugo van Kemenade and Stan Ulbrych in gh-76007@footnote{https://github.com/python/cpython/issues/76007}.)

@item 
Deprecations defined by 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/}:


@itemize *

@item 
Warnings are produced for @code{import} lines found in @code{`name'.pth}
files.

@item 
@code{`name'.pth} files are no longer decoded in the locale encoding by
default.  They `MUST' be encoded in @code{utf-8-sig}.
@end itemize

(Contributed by Barry Warsaw in gh-148641@footnote{https://github.com/python/cpython/issues/148641}.)

@item 
@ref{9,,ast}:


@itemize *

@item 
Creating instances of abstract AST nodes (such as @ref{2ec,,ast.AST}
or @code{ast.expr}) is deprecated and will raise an error in Python 3.20.
@end itemize
@end itemize

@node Pending removal in future versions<6>,,Pending removal in Python 3 20<4>,Deprecated<4>
@anchor{whatsnew/3 12 pending-removal-in-future-versions}@anchor{90f}
@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{7,,argparse}:


@itemize *

@item 
Nesting argument groups and nesting mutually exclusive
groups are deprecated.

@item 
Passing the undocumented keyword argument `prefix_chars' to
@ref{31d,,add_argument_group()} is now
deprecated.

@item 
The @ref{31e,,argparse.FileType} type converter is deprecated.
@end itemize

@item 
@ref{13,,builtins}:


@itemize *

@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{31f,,and}, @ref{320,,else}, @ref{321,,for}, @ref{322,,if},
@ref{323,,in}, @ref{324,,is} and @ref{325,,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{326,,int}.

@item 
Support for @code{__float__()} method returning a strict subclass of
@ref{327,,float}: these methods will be required to return an instance of
@code{float}.

@item 
Support for @code{__complex__()} method returning a strict subclass of
@ref{328,,complex}: these methods will be required to return an instance of
@code{complex}.

@item 
Passing a complex number as the `real' or `imag' argument in the
@ref{328,,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{15,,calendar}: @code{calendar.January} and @code{calendar.February} constants are
deprecated and replaced by @ref{329,,calendar.JANUARY} and
@ref{32a,,calendar.FEBRUARY}.
(Contributed by Prince Roshan in gh-103636@footnote{https://github.com/python/cpython/issues/103636}.)

@item 
@ref{1c,,codecs}: use @ref{32b,,open()} instead of @ref{32c,,codecs.open()}. (gh-133038@footnote{https://github.com/python/cpython/issues/133038})

@item 
@code{codeobject.co_lnotab}: use the @ref{32d,,codeobject.co_lines()} method
instead.

@item 
@ref{33,,datetime}:


@itemize *

@item 
@ref{32e,,utcnow()}:
use @code{datetime.datetime.now(tz=datetime.UTC)}.

@item 
@ref{32f,,utcfromtimestamp()}:
use @code{datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)}.
@end itemize

@item 
@ref{66,,gettext}: Plural value must be an integer.

@item 
@ref{7a,,importlib}:


@itemize *

@item 
@ref{330,,cache_from_source()} `debug_override' parameter is
deprecated: use the `optimization' parameter instead.
@end itemize

@item 
@ref{7d,,importlib.metadata}:


@itemize *

@item 
@code{EntryPoints} tuple interface.

@item 
Implicit @code{None} on return values.
@end itemize

@item 
@ref{8a,,logging}: the @code{warn()} method has been deprecated
since Python 3.3, use @ref{331,,warning()} instead.

@item 
@ref{8e,,mailbox}: Use of StringIO input and text mode is deprecated, use
BytesIO and binary mode instead.

@item 
@ref{a5,,os}: Calling @ref{332,,os.register_at_fork()} in a multi-threaded process.

@item 
@ref{a6,,os.path}: @ref{333,,os.path.commonprefix()} is deprecated, use
@ref{334,,os.path.commonpath()} for path prefixes. The @code{os.path.commonprefix()}
function is being deprecated due to having a misleading name and module.
The function is not safe to use for path prefixes despite being included in a
module about path manipulation, meaning it is easy to accidentally
introduce path traversal vulnerabilities into Python programs by using this
function.

@item 
@code{pydoc.ErrorDuringImport}: A tuple value for `exc_info' parameter is
deprecated, use an exception instance.

@item 
@ref{c1,,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 
@ref{cd,,shutil}: @ref{335,,rmtree()}”s `onerror' parameter is deprecated in
Python 3.12; use the `onexc' parameter instead.

@item 
@ref{d8,,ssl} options and protocols:


@itemize *

@item 
@ref{336,,ssl.SSLContext} without protocol argument is deprecated.

@item 
@ref{336,,ssl.SSLContext}: @ref{337,,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{f6,,threading} methods:


@itemize *

@item 
@code{threading.Condition.notifyAll()}: use @ref{338,,notify_all()}.

@item 
@code{threading.Event.isSet()}: use @ref{339,,is_set()}.

@item 
@code{threading.Thread.isDaemon()}, @ref{33a,,threading.Thread.setDaemon()}:
use @ref{33b,,threading.Thread.daemon} attribute.

@item 
@code{threading.Thread.getName()}, @ref{33c,,threading.Thread.setName()}:
use @ref{33d,,threading.Thread.name} attribute.

@item 
@code{threading.currentThread()}: use @ref{33e,,threading.current_thread()}.

@item 
@code{threading.activeCount()}: use @ref{33f,,threading.active_count()}.
@end itemize

@item 
@ref{340,,typing.Text} (gh-92332@footnote{https://github.com/python/cpython/issues/92332}).

@item 
The internal class @code{typing._UnionGenericAlias} is no longer used to implement
@ref{341,,typing.Union}. To preserve compatibility with users using this private
class, a compatibility shim will be provided until at least Python 3.17. (Contributed by
Jelle Zijlstra in gh-105499@footnote{https://github.com/python/cpython/issues/105499}.)

@item 
@ref{342,,unittest.IsolatedAsyncioTestCase}: it is deprecated to return a value
that is not @code{None} from a test case.

@item 
@ref{113,,urllib.parse} deprecated functions: @ref{2a4,,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{121,,wsgiref}: @code{SimpleHandler.stdout.write()} should not do partial
writes.

@item 
@ref{12e,,xml.etree.ElementTree}: Testing the truth value of an
@ref{343,,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{344,,sys._clear_type_cache()} is deprecated:
use @ref{345,,sys._clear_internal_caches()} instead.
@end itemize

@node Removed<4>,Porting to Python 3 12,Deprecated<4>,What’s New In Python 3 12
@anchor{whatsnew/3 12 removed}@anchor{910}@anchor{whatsnew/3 12 whatsnew312-removed}@anchor{911}
@subsection Removed


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

@end menu

@node asynchat and asyncore,configparser<4>,,Removed<4>
@anchor{whatsnew/3 12 asynchat-and-asyncore}@anchor{912}
@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{b,,asyncio} instead.
(Contributed by Nikita Sobolev in gh-96580@footnote{https://github.com/python/cpython/issues/96580}.)
@end itemize

@node configparser<4>,distutils,asynchat and asyncore,Removed<4>
@anchor{whatsnew/3 12 configparser}@anchor{913}
@subsubsection configparser



@itemize *

@item 
Several names deprecated in the @ref{26,,configparser} way back in 3.2 have
been removed per gh-89336@footnote{https://github.com/python/cpython/issues/89336}:


@itemize *

@item 
@ref{914,,configparser.ParsingError} no longer has a @code{filename} attribute
or argument. Use the @code{source} attribute and argument instead.

@item 
@ref{26,,configparser} no longer has a @code{SafeConfigParser} class. Use the
shorter @ref{6e4,,ConfigParser} name instead.

@item 
@ref{6e4,,configparser.ConfigParser} no longer has a @code{readfp} method.
Use @ref{915,,read_file()} instead.
@end itemize
@end itemize

@node distutils,ensurepip,configparser<4>,Removed<4>
@anchor{whatsnew/3 12 distutils}@anchor{916}@anchor{whatsnew/3 12 whatsnew312-removed-distutils}@anchor{917}
@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,Removed<4>
@anchor{whatsnew/3 12 ensurepip}@anchor{918}
@subsubsection ensurepip



@itemize *

@item 
Remove the bundled setuptools wheel from @ref{58,,ensurepip},
and stop installing setuptools in environments created by @ref{11a,,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,Removed<4>
@anchor{whatsnew/3 12 enum}@anchor{919}
@subsubsection enum



@itemize *

@item 
Remove @ref{59,,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>,Removed<4>
@anchor{whatsnew/3 12 ftplib}@anchor{91a}
@subsubsection ftplib



@itemize *

@item 
Remove @ref{61,,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<2>,ftplib,Removed<4>
@anchor{whatsnew/3 12 gzip}@anchor{91b}
@subsubsection gzip



@itemize *

@item 
Remove the @code{filename} attribute of @ref{6a,,gzip}’s @ref{849,,gzip.GzipFile},
deprecated since Python 2.6, use the @ref{91c,,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<2>,importlib<2>,gzip,Removed<4>
@anchor{whatsnew/3 12 hashlib}@anchor{91d}
@subsubsection hashlib



@itemize *

@item 
Remove the pure Python implementation of @ref{6b,,hashlib}’s
@ref{91e,,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 @code{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<2>,Removed<4>
@anchor{whatsnew/3 12 importlib}@anchor{91f}
@subsubsection importlib



@itemize *

@item 
Many previously deprecated cleanups in @ref{7a,,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<4>,importlib<2>,Removed<4>
@anchor{whatsnew/3 12 imp}@anchor{920}@anchor{whatsnew/3 12 whatsnew312-removed-imp}@anchor{921}
@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} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@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{330,,importlib.util.cache_from_source()}

@item

@code{imp.find_module()}

@tab

@ref{7a7,,importlib.util.find_spec()}

@item

@code{imp.get_magic()}

@tab

@ref{922,,importlib.util.MAGIC_NUMBER}

@item

@code{imp.get_suffixes()}

@tab

@ref{923,,importlib.machinery.SOURCE_SUFFIXES}, @ref{924,,importlib.machinery.EXTENSION_SUFFIXES}, and @ref{925,,importlib.machinery.BYTECODE_SUFFIXES}

@item

@code{imp.get_tag()}

@tab

@ref{926,,sys.implementation.cache_tag}

@item

@code{imp.load_module()}

@tab

@ref{927,,importlib.import_module()}

@item

@code{imp.new_module(name)}

@tab

@code{types.ModuleType(name)}

@item

@code{imp.reload()}

@tab

@ref{928,,importlib.reload()}

@item

@code{imp.source_from_cache()}

@tab

@ref{929,,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<4>,locale<3>,imp,Removed<4>
@anchor{whatsnew/3 12 io}@anchor{92a}
@subsubsection io



@itemize *

@item 
Remove @ref{82,,io}’s @code{io.OpenWrapper} and @code{_pyio.OpenWrapper}, deprecated in Python
3.10: just use @ref{32b,,open()} instead. The @code{open()} (@ref{92b,,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<3>,smtpd,io<4>,Removed<4>
@anchor{whatsnew/3 12 locale}@anchor{92c}
@subsubsection locale



@itemize *

@item 
Remove @ref{89,,locale}’s @code{locale.format()} function, deprecated in Python 3.7:
use @ref{92d,,locale.format_string()} instead.
(Contributed by Victor Stinner in gh-94226@footnote{https://github.com/python/cpython/issues/94226}.)
@end itemize

@node smtpd,sqlite3<5>,locale<3>,Removed<4>
@anchor{whatsnew/3 12 smtpd}@anchor{92e}
@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{b,,asyncio}-based server instead.
(Contributed by Oleg Iarygin in gh-93243@footnote{https://github.com/python/cpython/issues/93243}.)
@end itemize

@node sqlite3<5>,ssl<4>,smtpd,Removed<4>
@anchor{whatsnew/3 12 id2}@anchor{92f}
@subsubsection sqlite3



@itemize *

@item 
The following undocumented @ref{d7,,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{1df,,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<4>,unittest<5>,sqlite3<5>,Removed<4>
@anchor{whatsnew/3 12 ssl}@anchor{930}
@subsubsection ssl



@itemize *

@item 
Remove @ref{d8,,ssl}’s @code{ssl.RAND_pseudo_bytes()} function, deprecated in Python 3.6:
use @ref{931,,os.urandom()} or @ref{932,,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{336,,ssl.SSLContext} object and call its
@ref{933,,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<5>,webbrowser<4>,ssl<4>,Removed<4>
@anchor{whatsnew/3 12 id3}@anchor{934}
@subsubsection unittest



@itemize *

@item 
Remove many long-deprecated @ref{10f,,unittest} features:


@itemize *

@item 
A number of @ref{52f,,TestCase} method aliases:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Deprecated alias

@tab

Method Name

@tab

Deprecated in

@item

@code{failUnless}

@tab

@ref{935,,assertTrue()}

@tab

3.1

@item

@code{failIf}

@tab

@ref{936,,assertFalse()}

@tab

3.1

@item

@code{failUnlessEqual}

@tab

@ref{937,,assertEqual()}

@tab

3.1

@item

@code{failIfEqual}

@tab

@ref{938,,assertNotEqual()}

@tab

3.1

@item

@code{failUnlessAlmostEqual}

@tab

@ref{939,,assertAlmostEqual()}

@tab

3.1

@item

@code{failIfAlmostEqual}

@tab

@ref{93a,,assertNotAlmostEqual()}

@tab

3.1

@item

@code{failUnlessRaises}

@tab

@ref{93b,,assertRaises()}

@tab

3.1

@item

@code{assert_}

@tab

@ref{935,,assertTrue()}

@tab

3.2

@item

@code{assertEquals}

@tab

@ref{937,,assertEqual()}

@tab

3.2

@item

@code{assertNotEquals}

@tab

@ref{938,,assertNotEqual()}

@tab

3.2

@item

@code{assertAlmostEquals}

@tab

@ref{939,,assertAlmostEqual()}

@tab

3.2

@item

@code{assertNotAlmostEquals}

@tab

@ref{93a,,assertNotAlmostEqual()}

@tab

3.2

@item

@code{assertRegexpMatches}

@tab

@ref{93c,,assertRegex()}

@tab

3.2

@item

@code{assertRaisesRegexp}

@tab

@ref{93d,,assertRaisesRegex()}

@tab

3.2

@item

@code{assertNotRegexpMatches}

@tab

@ref{93e,,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{52f,,TestCase} method
@code{assertDictContainsSubset} (deprecated in Python 3.2).

@item 
Undocumented @ref{793,,TestLoader.loadTestsFromModule} parameter `use_load_tests'
(deprecated and ignored since Python 3.5).

@item 
An alias of the @ref{93f,,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<4>,xml etree ElementTree,unittest<5>,Removed<4>
@anchor{whatsnew/3 12 webbrowser}@anchor{940}
@subsubsection webbrowser



@itemize *

@item 
Remove support for obsolete browsers from @ref{11e,,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<3>,webbrowser<4>,Removed<4>
@anchor{whatsnew/3 12 xml-etree-elementtree}@anchor{941}
@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{942,,copy.copy()} function instead.  The C implementation of @ref{12e,,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<3>,Others,xml etree ElementTree,Removed<4>
@anchor{whatsnew/3 12 zipimport}@anchor{943}
@subsubsection zipimport



@itemize *

@item 
Remove @ref{13b,,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 Others,,zipimport<3>,Removed<4>
@anchor{whatsnew/3 12 others}@anchor{944}
@subsubsection Others



@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{61,,ftplib}, @ref{77,,imaplib}, @ref{b1,,poplib} and @ref{d2,,smtplib} modules,
and the `key_file', `cert_file' and `check_hostname' parameters from the
@ref{72,,http.client} module,
all deprecated since Python 3.6. Use the `context' parameter
(`ssl_context' in @code{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{2d,,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,Build Changes<2>,Removed<4>,What’s New In Python 3 12
@anchor{whatsnew/3 12 porting-to-python-3-12}@anchor{945}@anchor{whatsnew/3 12 whatsnew312-porting-to-python312}@anchor{8dc}
@subsection Porting to Python 3.12


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

@menu
* Changes in the Python API: Changes in the Python API<3>. 

@end menu

@node Changes in the Python API<3>,,,Porting to Python 3 12
@anchor{whatsnew/3 12 changes-in-the-python-api}@anchor{946}
@subsubsection Changes in the Python API



@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{291,,TypeError}. Also, the exception raised for non-integer values such as
@code{randrange(10.5)} or @code{randrange('10')} has been changed from @ref{277,,ValueError} to
@code{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{1dc,,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{947,,locale.getpreferredencoding(False)})
to @ref{948,,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{b,,asyncio}-based aiosmtpd@footnote{https://pypi.org/project/aiosmtpd/} PyPI module.

@item 
@ref{949,,shlex.split()}: Passing @code{None} for `s' argument now raises an
exception, rather than reading @ref{94a,,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{a5,,os} module no longer accepts bytes-like paths, like
@ref{1c6,,bytearray} and @ref{1d2,,memoryview} types: only the exact
@ref{1c7,,bytes} type is accepted for bytes strings.
(Contributed by Victor Stinner in gh-98393@footnote{https://github.com/python/cpython/issues/98393}.)

@item 
@ref{94b,,syslog.openlog()} and @ref{94c,,syslog.closelog()} now fail if used in subinterpreters.
@ref{94d,,syslog.syslog()} may still be used in subinterpreters,
but now only if @code{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{e5,,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{94e,,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{8d2,,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{e7,,tarfile} or
@ref{882,,shutil.unpack_archive()}, pass the `filter' argument to limit features
that may be surprising or dangerous.
See @ref{883,,Extraction filters} for details.

@item 
The output of the @ref{8e9,,tokenize.tokenize()} and @ref{8ea,,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{94f,,tokenize.TokenError} as incomplete
multiline strings do.

@item 
Some incomplete or invalid Python code now raises @ref{94f,,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{950,,TabError}.
@end itemize

@item 
The @ref{f6,,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 Build Changes<2>,C API Changes<2>,Porting to Python 3 12,What’s New In Python 3 12
@anchor{whatsnew/3 12 build-changes}@anchor{951}
@subsection Build Changes



@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{21,,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 C API Changes<2>,,Build Changes<2>,What’s New In Python 3 12
@anchor{whatsnew/3 12 c-api-changes}@anchor{952}
@subsection C API Changes


@menu
* New Features: New Features<4>. 
* Porting to Python 3.12: Porting to Python 3 12<2>. 
* Deprecated: Deprecated<5>. 
* Removed: Removed<5>. 

@end menu

@node New Features<4>,Porting to Python 3 12<2>,,C API Changes<2>
@anchor{whatsnew/3 12 id4}@anchor{953}
@subsubsection New Features

@anchor{whatsnew/3 12 whatsnew312-pep697}@anchor{863}

@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 697
PEP 697@footnote{https://peps.python.org/pep-0697/}: Introduce the @ref{954,,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{199,,PyType_Spec.basicsize} can be zero or negative to specify
inheriting or extending the base class size.

@item 
@ref{19a,,PyObject_GetTypeData()} and @ref{955,,PyType_GetTypeDataSize()}
added to allow access to subclass-specific instance data.

@item 
@ref{956,,Py_TPFLAGS_ITEMS_AT_END} and @ref{957,,PyObject_GetItemData()}
added to allow safely extending certain variable-sized types, including
@ref{958,,PyType_Type}.

@item 
@ref{959,,Py_RELATIVE_OFFSET} added to allow defining
@ref{95a,,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{829,,limited C API} function @ref{391,,PyType_FromMetaclass()},
which generalizes the existing @ref{390,,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{95b,,the vectorcall protocol} was added to the
@ref{95c,,Limited API}:


@itemize *

@item 
@ref{95d,,Py_TPFLAGS_HAVE_VECTORCALL}

@item 
@ref{95e,,PyVectorcall_NARGS()}

@item 
@ref{95f,,PyVectorcall_Call()}

@item 
@ref{960,,vectorcallfunc}
@end itemize

The @ref{95d,,Py_TPFLAGS_HAVE_VECTORCALL} flag is now removed from a class
when the class’s @ref{961,,__call__()} method is reassigned.
This makes vectorcall safe to use with mutable types (i.e. heap types
without the immutable flag, @ref{5fb,,Py_TPFLAGS_IMMUTABLETYPE}).
Mutable types that do not override @ref{962,,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{39c,,Py_TPFLAGS_MANAGED_DICT} and @ref{39d,,Py_TPFLAGS_MANAGED_WEAKREF}
flags have been added. This allows extensions classes to support object
@ref{1bf,,__dict__} and weakrefs with less bookkeeping,
using less memory and with faster access.

@item 
API for performing calls using
@ref{95b,,the vectorcall protocol} was added to the
@ref{95c,,Limited API}:


@itemize *

@item 
@ref{963,,PyObject_Vectorcall()}

@item 
@ref{964,,PyObject_VectorcallMethod()}

@item 
@ref{965,,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{95c,,Limited API}. (Contributed
by Wenzel Jakob in gh-98586@footnote{https://github.com/python/cpython/issues/98586}.)

@item 
Add two new public functions,
@ref{966,,PyEval_SetProfileAllThreads()} and
@ref{851,,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{967,,PyFunction_SetVectorcall()} to the C API
which sets the vectorcall field of a given @ref{968,,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{5fc,,PyDict_AddWatcher()},
@ref{969,,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{96a,,PyType_AddWatcher()} and @ref{96b,,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{96c,,PyCode_AddWatcher()} and @ref{96d,,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{96e,,PyFrame_GetVar()} and @ref{96f,,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{63c,,PyErr_GetRaisedException()} and @ref{63f,,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{63b,,PyErr_Fetch()} and @ref{63e,,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{970,,PyException_GetArgs()} and @ref{971,,PyException_SetArgs()}
as convenience functions for retrieving and modifying
the @ref{972,,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{648,,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{864}

@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{876,,Py_NewInterpreterFromConfig()}
function and @ref{973,,PyInterpreterConfig}, which may be used
to create sub-interpreters with their own GILs.
(See @ref{85d,,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{974,,Py_INCREF()} and
@ref{975,,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>,Deprecated<5>,New Features<4>,C API Changes<2>
@anchor{whatsnew/3 12 id5}@anchor{976}
@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{3b1,,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{977,,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{978,,__subclasses__()} (using @ref{3b6,,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{81e,,PyUnicode_FromFormat()} and
@ref{979,,PyUnicode_FromFormatV()}.
(Contributed by Serhiy Storchaka in gh-98836@footnote{https://github.com/python/cpython/issues/98836}.)

@item 
An unrecognized format character in @ref{81e,,PyUnicode_FromFormat()} and
@ref{979,,PyUnicode_FromFormatV()} now sets a @ref{3ea,,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{81e,,PyUnicode_FromFormat()} and
@ref{979,,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{1bf,,__dict__} or weak reference slot
should use @ref{39c,,Py_TPFLAGS_MANAGED_DICT} and
@ref{39d,,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 @code{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{97a,,PyObject_ClearWeakRefs()}, as before.

@item 
The @ref{97b,,PyUnicode_FSDecoder()} function no longer accepts bytes-like
paths, like @ref{1c6,,bytearray} and @ref{1d2,,memoryview} types: only the exact
@ref{1c7,,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{97c,,Py_CLEAR}, @ref{97d,,Py_SETREF} and @ref{97e,,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{97f,,PyErr_SetObject()}, @ref{980,,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{38e,,PyType_FromSpec()}

@item 
@ref{38f,,PyType_FromSpecWithBases()}

@item 
@ref{390,,PyType_FromModuleAndSpec()}
@end itemize

Creating classes whose metaclass overrides @ref{981,,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{391,,PyType_FromMetaclass()} (added in Python 3.12)
already disallows creating classes whose metaclass overrides @code{tp_new}
(@ref{982,,__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{983,,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{984,,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{985,,calling}
the metaclass.

@item 
If you `know' the @code{tp_new} can be skipped safely, filter the deprecation
warning out using @ref{423,,warnings.catch_warnings()} from Python.
@end itemize

@item 
@ref{986,,PyOS_InputHook} and @ref{987,,PyOS_ReadlineFunctionPointer} are no
longer called in @ref{410,,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{5cb,,PyLongObject} has had its internals changed for better performance.
Although the internals of @code{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 @code{PyLongObject}s which fit into a single machine word:


@itemize *

@item 
@ref{988,,PyUnstable_Long_IsCompact()}

@item 
@ref{989,,PyUnstable_Long_CompactValue()}
@end itemize

@item 
Custom allocators, set via @ref{98a,,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 Deprecated<5>,Removed<5>,Porting to Python 3 12<2>,C API Changes<2>
@anchor{whatsnew/3 12 id6}@anchor{98b}
@subsubsection Deprecated



@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{83e,,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{60c,,Py_DebugFlag}: use @ref{60d,,PyConfig.parser_debug}

@item 
@ref{60e,,Py_VerboseFlag}: use @ref{60f,,PyConfig.verbose}

@item 
@ref{610,,Py_QuietFlag}: use @ref{611,,PyConfig.quiet}

@item 
@ref{612,,Py_InteractiveFlag}: use @ref{613,,PyConfig.interactive}

@item 
@ref{614,,Py_InspectFlag}: use @ref{615,,PyConfig.inspect}

@item 
@ref{616,,Py_OptimizeFlag}: use @ref{617,,PyConfig.optimization_level}

@item 
@ref{618,,Py_NoSiteFlag}: use @ref{619,,PyConfig.site_import}

@item 
@ref{61a,,Py_BytesWarningFlag}: use @ref{3c4,,PyConfig.bytes_warning}

@item 
@ref{61b,,Py_FrozenFlag}: use @ref{61c,,PyConfig.pathconfig_warnings}

@item 
@ref{61d,,Py_IgnoreEnvironmentFlag}: use @ref{61e,,PyConfig.use_environment}

@item 
@ref{61f,,Py_DontWriteBytecodeFlag}: use @ref{620,,PyConfig.write_bytecode}

@item 
@ref{621,,Py_NoUserSiteDirectory}: use @ref{622,,PyConfig.user_site_directory}

@item 
@ref{623,,Py_UnbufferedStdioFlag}: use @ref{624,,PyConfig.buffered_stdio}

@item 
@ref{625,,Py_HashRandomizationFlag}: use @ref{626,,PyConfig.use_hash_seed}
and @ref{627,,PyConfig.hash_seed}

@item 
@ref{628,,Py_IsolatedFlag}: use @ref{629,,PyConfig.isolated}

@item 
@ref{62a,,Py_LegacyWindowsFSEncodingFlag}: use @ref{62b,,PyPreConfig.legacy_windows_fs_encoding}

@item 
@ref{62c,,Py_LegacyWindowsStdioFlag}: use @ref{62d,,PyConfig.legacy_windows_stdio}

@item 
@code{Py_FileSystemDefaultEncoding}: use @ref{62e,,PyConfig.filesystem_encoding}

@item 
@code{Py_HasFileSystemDefaultEncoding}: use @ref{62e,,PyConfig.filesystem_encoding}

@item 
@code{Py_FileSystemDefaultEncodeErrors}: use @ref{62f,,PyConfig.filesystem_errors}

@item 
@code{Py_UTF8Mode}: use @ref{630,,PyPreConfig.utf8_mode} (see @ref{631,,Py_PreInitialize()})
@end itemize

The @ref{60a,,Py_InitializeFromConfig()} API should be used with
@ref{60b,,PyConfig} instead.
(Contributed by Victor Stinner in gh-77782@footnote{https://github.com/python/cpython/issues/77782}.)

@item 
Creating @ref{5fb,,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{95a,,PyMemberDef}, @ref{98c,,PyMember_GetOne()} and
@ref{98d,,PyMember_SetOne()}

@item 
Type macros like @ref{98e,,Py_T_INT}, @ref{98f,,Py_T_DOUBLE}, etc.
(previously @code{T_INT}, @code{T_DOUBLE}, etc.)

@item 
The flags @ref{990,,Py_READONLY} (previously @code{READONLY}) and
@ref{991,,Py_AUDIT_READ} (previously all uppercase)
@end itemize

Several items are not exposed from @code{Python.h}:


@itemize -

@item 
@ref{992,,T_OBJECT} (use @ref{993,,Py_T_OBJECT_EX})

@item 
@ref{994,,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{991,,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{63b,,PyErr_Fetch()} and @ref{63e,,PyErr_Restore()} are deprecated.
Use @ref{63c,,PyErr_GetRaisedException()} and
@ref{63f,,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{648,,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{38e,,PyType_FromSpec()}, @ref{38f,,PyType_FromSpecWithBases()}
or @ref{390,,PyType_FromModuleAndSpec()} to create a class whose metaclass
overrides @ref{981,,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<6>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<7>. 
* Pending removal in future versions: Pending removal in future versions<7>. 

@end menu

@node Pending removal in Python 3 14<4>,Pending removal in Python 3 15<6>,,Deprecated<5>
@anchor{whatsnew/3 12 id7}@anchor{995}
@subsubsection Pending removal in Python 3.14



@itemize *

@item 
The @code{ma_version_tag} field in @ref{83e,,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{5fb,,immutable types} with mutable
bases (gh-95388@footnote{https://github.com/python/cpython/issues/95388}).
@end itemize

@node Pending removal in Python 3 15<6>,Pending removal in Python 3 16<7>,Pending removal in Python 3 14<4>,Deprecated<5>
@anchor{whatsnew/3 12 id8}@anchor{996}
@subsubsection Pending removal in Python 3.15



@itemize *

@item 
The @code{PyImport_ImportModuleNoBlock()}:
Use @ref{3a3,,PyImport_ImportModule()} instead.

@item 
@code{PyWeakref_GetObject()} and @code{PyWeakref_GET_OBJECT()}:
Use @ref{3a4,,PyWeakref_GetRef()} instead. The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
@code{PyWeakref_GetRef()} on Python 3.12 and older.

@item 
@code{PyUnicode_AsDecodedObject()}:
Use @ref{3a1,,PyCodec_Decode()} instead.

@item 
@code{PyUnicode_AsDecodedUnicode()}:
Use @ref{3a1,,PyCodec_Decode()} instead; Note that some codecs (for example, «base64»)
may return a type other than @ref{1df,,str}, such as @ref{1c7,,bytes}.

@item 
@code{PyUnicode_AsEncodedObject()}:
Use @ref{3a2,,PyCodec_Encode()} instead.

@item 
@code{PyUnicode_AsEncodedUnicode()}:
Use @ref{3a2,,PyCodec_Encode()} instead; Note that some codecs (for example, «base64»)
may return a type other than @ref{1c7,,bytes}, such as @ref{1df,,str}.

@item 
Python initialization functions, deprecated in Python 3.13:


@itemize *

@item 
@code{Py_GetPath()}:
Use @ref{3a6,,PyConfig_Get("module_search_paths")}
(@ref{194,,sys.path}) instead.

@item 
@code{Py_GetPrefix()}:
Use @ref{3a6,,PyConfig_Get("base_prefix")}
(@ref{3aa,,sys.base_prefix}) instead. Use @code{PyConfig_Get("prefix")} (@ref{3ab,,sys.prefix}) if @ref{3a9,,virtual environments} need to be handled.

@item 
@code{Py_GetExecPrefix()}:
Use @ref{3a6,,PyConfig_Get("base_exec_prefix")}
(@ref{3a7,,sys.base_exec_prefix}) instead. Use
@code{PyConfig_Get("exec_prefix")}
(@ref{3a8,,sys.exec_prefix}) if @ref{3a9,,virtual environments} need to
be handled.

@item 
@code{Py_GetProgramFullPath()}:
Use @ref{3a6,,PyConfig_Get("executable")}
(@ref{3ac,,sys.executable}) instead.

@item 
@code{Py_GetProgramName()}:
Use @ref{3a6,,PyConfig_Get("executable")}
(@ref{3ac,,sys.executable}) instead.

@item 
@code{Py_GetPythonHome()}:
Use @ref{3a6,,PyConfig_Get("home")} or the
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} environment variable instead.
@end itemize

The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
@ref{3a6,,PyConfig_Get()} on Python 3.13 and older.

@item 
Functions to configure Python’s initialization, deprecated in Python 3.11:


@itemize *

@item 
@code{PySys_SetArgvEx()}:
Set @ref{607,,PyConfig.argv} instead.

@item 
@code{PySys_SetArgv()}:
Set @ref{607,,PyConfig.argv} instead.

@item 
@code{Py_SetProgramName()}:
Set @ref{608,,PyConfig.program_name} instead.

@item 
@code{Py_SetPythonHome()}:
Set @ref{609,,PyConfig.home} instead.

@item 
@code{PySys_ResetWarnOptions()}:
Clear @ref{3a5,,sys.warnoptions} and @code{warnings.filters} instead.
@end itemize

The @ref{60a,,Py_InitializeFromConfig()} API should be used with
@ref{60b,,PyConfig} instead.

@item 
Global configuration variables:


@itemize *

@item 
@ref{60c,,Py_DebugFlag}:
Use @ref{60d,,PyConfig.parser_debug} or
@ref{3a6,,PyConfig_Get("parser_debug")} instead.

@item 
@ref{60e,,Py_VerboseFlag}:
Use @ref{60f,,PyConfig.verbose} or
@ref{3a6,,PyConfig_Get("verbose")} instead.

@item 
@ref{610,,Py_QuietFlag}:
Use @ref{611,,PyConfig.quiet} or
@ref{3a6,,PyConfig_Get("quiet")} instead.

@item 
@ref{612,,Py_InteractiveFlag}:
Use @ref{613,,PyConfig.interactive} or
@ref{3a6,,PyConfig_Get("interactive")} instead.

@item 
@ref{614,,Py_InspectFlag}:
Use @ref{615,,PyConfig.inspect} or
@ref{3a6,,PyConfig_Get("inspect")} instead.

@item 
@ref{616,,Py_OptimizeFlag}:
Use @ref{617,,PyConfig.optimization_level} or
@ref{3a6,,PyConfig_Get("optimization_level")} instead.

@item 
@ref{618,,Py_NoSiteFlag}:
Use @ref{619,,PyConfig.site_import} or
@ref{3a6,,PyConfig_Get("site_import")} instead.

@item 
@ref{61a,,Py_BytesWarningFlag}:
Use @ref{3c4,,PyConfig.bytes_warning} or
@ref{3a6,,PyConfig_Get("bytes_warning")} instead.

@item 
@ref{61b,,Py_FrozenFlag}:
Use @ref{61c,,PyConfig.pathconfig_warnings} or
@ref{3a6,,PyConfig_Get("pathconfig_warnings")} instead.

@item 
@ref{61d,,Py_IgnoreEnvironmentFlag}:
Use @ref{61e,,PyConfig.use_environment} or
@ref{3a6,,PyConfig_Get("use_environment")} instead.

@item 
@ref{61f,,Py_DontWriteBytecodeFlag}:
Use @ref{620,,PyConfig.write_bytecode} or
@ref{3a6,,PyConfig_Get("write_bytecode")} instead.

@item 
@ref{621,,Py_NoUserSiteDirectory}:
Use @ref{622,,PyConfig.user_site_directory} or
@ref{3a6,,PyConfig_Get("user_site_directory")} instead.

@item 
@ref{623,,Py_UnbufferedStdioFlag}:
Use @ref{624,,PyConfig.buffered_stdio} or
@ref{3a6,,PyConfig_Get("buffered_stdio")} instead.

@item 
@ref{625,,Py_HashRandomizationFlag}:
Use @ref{626,,PyConfig.use_hash_seed}
and @ref{627,,PyConfig.hash_seed} or
@ref{3a6,,PyConfig_Get("hash_seed")} instead.

@item 
@ref{628,,Py_IsolatedFlag}:
Use @ref{629,,PyConfig.isolated} or
@ref{3a6,,PyConfig_Get("isolated")} instead.

@item 
@ref{62a,,Py_LegacyWindowsFSEncodingFlag}:
Use @ref{62b,,PyPreConfig.legacy_windows_fs_encoding} or
@ref{3a6,,PyConfig_Get("legacy_windows_fs_encoding")} instead.

@item 
@ref{62c,,Py_LegacyWindowsStdioFlag}:
Use @ref{62d,,PyConfig.legacy_windows_stdio} or
@ref{3a6,,PyConfig_Get("legacy_windows_stdio")} instead.

@item 
@code{Py_FileSystemDefaultEncoding}, @code{Py_HasFileSystemDefaultEncoding}:
Use @ref{62e,,PyConfig.filesystem_encoding} or
@ref{3a6,,PyConfig_Get("filesystem_encoding")} instead.

@item 
@code{Py_FileSystemDefaultEncodeErrors}:
Use @ref{62f,,PyConfig.filesystem_errors} or
@ref{3a6,,PyConfig_Get("filesystem_errors")} instead.

@item 
@code{Py_UTF8Mode}:
Use @ref{630,,PyPreConfig.utf8_mode} or
@ref{3a6,,PyConfig_Get("utf8_mode")} instead.
(see @ref{631,,Py_PreInitialize()})
@end itemize

The @ref{60a,,Py_InitializeFromConfig()} API should be used with
@ref{60b,,PyConfig} to set these options. Or @ref{3a6,,PyConfig_Get()} can be
used to get these options at runtime.
@end itemize

@node Pending removal in Python 3 16<7>,Pending removal in future versions<7>,Pending removal in Python 3 15<6>,Deprecated<5>
@anchor{whatsnew/3 12 id9}@anchor{997}
@subsubsection Pending removal in Python 3.16



@itemize *

@item 
The bundled copy of @code{libmpdec}.
@end itemize

@node Pending removal in future versions<7>,,Pending removal in Python 3 16<7>,Deprecated<5>
@anchor{whatsnew/3 12 id10}@anchor{998}
@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{63a,,Py_TPFLAGS_HAVE_FINALIZE}:
Unneeded since Python 3.8.

@item 
@ref{63b,,PyErr_Fetch()}:
Use @ref{63c,,PyErr_GetRaisedException()} instead.

@item 
@ref{63d,,PyErr_NormalizeException()}:
Use @ref{63c,,PyErr_GetRaisedException()} instead.

@item 
@ref{63e,,PyErr_Restore()}:
Use @ref{63f,,PyErr_SetRaisedException()} instead.

@item 
@ref{640,,PyModule_GetFilename()}:
Use @ref{641,,PyModule_GetFilenameObject()} instead.

@item 
@ref{642,,PyOS_AfterFork()}:
Use @ref{643,,PyOS_AfterFork_Child()} instead.

@item 
@ref{644,,PySlice_GetIndicesEx()}:
Use @ref{645,,PySlice_Unpack()} and @ref{646,,PySlice_AdjustIndices()} instead.

@item 
@ref{647,,PyUnicode_READY()}:
Unneeded since Python 3.12

@item 
@code{PyErr_Display()}:
Use @ref{648,,PyErr_DisplayException()} instead.

@item 
@code{_PyErr_ChainExceptions()}:
Use @code{_PyErr_ChainExceptions1()} instead.

@item 
@code{PyBytesObject.ob_shash} member:
call @ref{649,,PyObject_Hash()} instead.

@item 
Thread Local Storage (TLS) API:


@itemize *

@item 
@ref{64a,,PyThread_create_key()}:
Use @ref{64b,,PyThread_tss_alloc()} instead.

@item 
@ref{64c,,PyThread_delete_key()}:
Use @ref{64d,,PyThread_tss_free()} instead.

@item 
@ref{64e,,PyThread_set_key_value()}:
Use @ref{64f,,PyThread_tss_set()} instead.

@item 
@ref{650,,PyThread_get_key_value()}:
Use @ref{651,,PyThread_tss_get()} instead.

@item 
@ref{652,,PyThread_delete_key_value()}:
Use @ref{653,,PyThread_tss_delete()} instead.

@item 
@ref{654,,PyThread_ReInitTLS()}:
Unneeded since Python 3.7.
@end itemize
@end itemize

@node Removed<5>,,Deprecated<5>,C API Changes<2>
@anchor{whatsnew/3 12 id11}@anchor{999}
@subsubsection Removed



@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 11,What’s New In Python 3 10,What’s New In Python 3 12,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 11 doc}@anchor{99a}@anchor{whatsnew/3 11 translation-repo}@anchor{99b}@anchor{whatsnew/3 11 what-s-new-in-python-3-11}@anchor{99c}
@section What’s New In Python 3.11


@*Editor: 
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{145,,changelog}.

@menu
* Summary – Release highlights: Summary – Release highlights<4>. 
* New Features: New Features<5>. 
* New Features Related to Type Hints: New Features Related to Type Hints<2>. 
* Other Language Changes: Other Language Changes<3>. 
* Other CPython Implementation Changes:: 
* New Modules: New Modules<3>. 
* Improved Modules: Improved Modules<3>. 
* Optimizations: Optimizations<6>. 
* Faster CPython:: 
* CPython bytecode changes: CPython bytecode changes<3>. 
* Deprecated: Deprecated<6>. 
* Pending Removal in Python 3.12: Pending Removal in Python 3 12. 
* Removed: Removed<6>. 
* Porting to Python 3.11: Porting to Python 3 11. 
* Build Changes: Build Changes<3>. 
* C API Changes: C API Changes<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 Summary – Release highlights<4>,New Features<5>,,What’s New In Python 3 11
@anchor{whatsnew/3 11 summary-release-highlights}@anchor{99d}@anchor{whatsnew/3 11 whatsnew311-summary}@anchor{99e}
@subsection Summary – Release highlights


@c This section singles out the most important changes in Python 3.11.
@c Brevity is key.


@itemize *

@item 
Python 3.11 is between 10-60% faster than Python 3.10.
On average, we measured a 1.25x speedup on the standard benchmark suite.
See @ref{99f,,Faster CPython} for details.
@end itemize

@c PEP-sized items next.

New syntax features:


@itemize *

@item 
@ref{9a0,,PEP 654; Exception Groups and except*}
@end itemize

New built-in features:


@itemize *

@item 
@ref{9a1,,PEP 678; Exceptions can be enriched with notes}
@end itemize

New standard library modules:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 680
PEP 680@footnote{https://peps.python.org/pep-0680/}: @ref{105,,tomllib} —
Support for parsing TOML@footnote{https://toml.io/} in the Standard Library
@end itemize

Interpreter improvements:


@itemize *

@item 
@ref{9a2,,PEP 657; Fine-grained error locations in tracebacks}

@item 
New @ref{9a3,,-P} command line option and 
@geindex PYTHONSAFEPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONSAFEPATH
@ref{9a4,,PYTHONSAFEPATH} environment
variable to @ref{9a5,,disable automatically prepending potentially unsafe paths} to @ref{194,,sys.path}
@end itemize

New typing features:


@itemize *

@item 
@ref{9a6,,PEP 646; Variadic generics}

@item 
@ref{9a7,,PEP 655; Marking individual TypedDict items as required or not-required}

@item 
@ref{9a8,,PEP 673; Self type}

@item 
@ref{9a9,,PEP 675; Arbitrary literal string type}

@item 
@ref{9aa,,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{9ab,,Many legacy standard library modules have been deprecated} and will be removed in Python 3.13

@item 
@geindex Python Enhancement Proposals; PEP 624
PEP 624@footnote{https://peps.python.org/pep-0624/}:
@ref{9ac,,Py_UNICODE encoder APIs have been removed}

@item 
@geindex Python Enhancement Proposals; PEP 670
PEP 670@footnote{https://peps.python.org/pep-0670/}:
@ref{9ad,,Macros converted to static inline functions}
@end itemize

@node New Features<5>,New Features Related to Type Hints<2>,Summary – Release highlights<4>,What’s New In Python 3 11
@anchor{whatsnew/3 11 new-features}@anchor{9ae}@anchor{whatsnew/3 11 whatsnew311-features}@anchor{9af}
@subsection New Features


@menu
* PEP 657; Fine-grained error locations in tracebacks: PEP 657 Fine-grained error locations in tracebacks. 
* PEP 654; Exception Groups and except*: PEP 654 Exception Groups and except*. 
* PEP 678; Exceptions can be enriched with notes: PEP 678 Exceptions can be enriched with notes. 
* Windows py.exe launcher improvements: Windows py exe launcher improvements. 

@end menu

@node PEP 657 Fine-grained error locations in tracebacks,PEP 654 Exception Groups and except*,,New Features<5>
@anchor{whatsnew/3 11 pep-657-fine-grained-error-locations-in-tracebacks}@anchor{9b0}@anchor{whatsnew/3 11 whatsnew311-pep657}@anchor{9a2}
@subsubsection PEP 657: Fine-grained error locations in tracebacks


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{188,,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{6b3,,bytecode} @ref{9b1,,instructions} with source code location.
This information can be retrieved using:


@itemize -

@item 
The @ref{9b2,,codeobject.co_positions()} method in Python.

@item 
The @ref{9b3,,PyCode_Addr2Location()} function in the C API.
@end itemize

See 
@geindex Python Enhancement Proposals; PEP 657
PEP 657@footnote{https://peps.python.org/pep-0657/} for more details. (Contributed by Pablo Galindo, Batuhan Taskaya
and Ammar Askar in bpo-43950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43950}.)

@cartouche
@quotation Σημείωση 
This feature requires storing column positions in @ref{9b4,,Code Objects},
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{178,,-X no_debug_ranges} command line option
or the 
@geindex PYTHONNODEBUGRANGES
@geindex μεταβλητή περιβάλλοντος; PYTHONNODEBUGRANGES
@ref{9b5,,PYTHONNODEBUGRANGES} environment variable.
@end quotation
@end cartouche

@node PEP 654 Exception Groups and except*,PEP 678 Exceptions can be enriched with notes,PEP 657 Fine-grained error locations in tracebacks,New Features<5>
@anchor{whatsnew/3 11 pep-654-exception-groups-and-except}@anchor{9b6}@anchor{whatsnew/3 11 whatsnew311-pep654}@anchor{9a0}
@subsubsection PEP 654: Exception Groups and @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{6d8,,ExceptionGroup} and @ref{767,,BaseExceptionGroup}
make it possible to group exceptions and raise them together,
and the new @ref{448,,except*} syntax generalizes
@ref{447,,except} to match subgroups of exception groups.

See 
@geindex Python Enhancement Proposals; PEP 654
PEP 654@footnote{https://peps.python.org/pep-0654/} for more details.

(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,Windows py exe launcher improvements,PEP 654 Exception Groups and except*,New Features<5>
@anchor{whatsnew/3 11 pep-678-exceptions-can-be-enriched-with-notes}@anchor{9b7}@anchor{whatsnew/3 11 whatsnew311-pep678}@anchor{9a1}
@subsubsection PEP 678: Exceptions can be enriched with notes


The @ref{9b8,,add_note()} method is added to @ref{9b9,,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.

See 
@geindex Python Enhancement Proposals; PEP 678
PEP 678@footnote{https://peps.python.org/pep-0678/} for more details.

(Contributed by Irit Katriel in bpo-45607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45607}.
PEP written by Zac Hatfield-Dodds.)

@node Windows py exe launcher improvements,,PEP 678 Exceptions can be enriched with notes,New Features<5>
@anchor{whatsnew/3 11 whatsnew311-windows-launcher}@anchor{9ba}@anchor{whatsnew/3 11 windows-py-exe-launcher-improvements}@anchor{9bb}
@subsubsection Windows @code{py.exe} launcher improvements


The copy of the @ref{9bc,,Διαχειριστής εγκατάστασης Python} 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{9bd}
@node New Features Related to Type Hints<2>,Other Language Changes<3>,New Features<5>,What’s New In Python 3 11
@anchor{whatsnew/3 11 new-features-related-to-type-hints}@anchor{9be}@anchor{whatsnew/3 11 whatsnew311-typing-features}@anchor{9bf}
@subsection New Features Related to Type Hints


This section covers major changes affecting 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} type hints and
the @ref{10d,,typing} module.

@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,,New Features Related to Type Hints<2>
@anchor{whatsnew/3 11 pep-646-variadic-generics}@anchor{9c0}@anchor{whatsnew/3 11 whatsnew311-pep646}@anchor{9a6}
@subsubsection PEP 646: Variadic generics


@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} previously introduced @ref{294,,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{293,,TypeVarTuple}, enabling parameterisation
with an `arbitrary' number of types. In other words,
a @code{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.

See 
@geindex Python Enhancement Proposals; PEP 646
PEP 646@footnote{https://peps.python.org/pep-0646/} for more details.

(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,New Features Related to Type Hints<2>
@anchor{whatsnew/3 11 pep-655-marking-individual-typeddict-items-as-required-or-not-required}@anchor{9c1}@anchor{whatsnew/3 11 whatsnew311-pep655}@anchor{9a7}
@subsubsection PEP 655: Marking individual @code{TypedDict} items as required or not-required


@ref{9c2,,Required} and @ref{9c3,,NotRequired} provide a
straightforward way to mark whether individual items in a
@ref{290,,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

The following definition is equivalent:

@example
class Movie(TypedDict, total=False):
   title: Required[str]
   year: int
@end example

See 
@geindex Python Enhancement Proposals; PEP 655
PEP 655@footnote{https://peps.python.org/pep-0655/} for more details.

(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,New Features Related to Type Hints<2>
@anchor{whatsnew/3 11 pep-673-self-type}@anchor{9c4}@anchor{whatsnew/3 11 whatsnew311-pep673}@anchor{9a8}
@subsubsection PEP 673: @code{Self} type


The new @ref{9c5,,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{294,,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{69a,,classmethod}s,
and @ref{9c6,,__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{9c5,,Self} can also be used to annotate method parameters
or attributes of the same type as their enclosing class.

See 
@geindex Python Enhancement Proposals; PEP 673
PEP 673@footnote{https://peps.python.org/pep-0673/} for more details.

(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,New Features Related to Type Hints<2>
@anchor{whatsnew/3 11 pep-675-arbitrary-literal-string-type}@anchor{9c7}@anchor{whatsnew/3 11 whatsnew311-pep675}@anchor{9a9}
@subsubsection PEP 675: Arbitrary literal string type


The new @ref{9c8,,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.

For example, a SQL query function could be annotated as follows:

@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

See 
@geindex Python Enhancement Proposals; PEP 675
PEP 675@footnote{https://peps.python.org/pep-0675/} for more details.

(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,New Features Related to Type Hints<2>
@anchor{whatsnew/3 11 pep-681-data-class-transforms}@anchor{9c9}@anchor{whatsnew/3 11 whatsnew311-pep681}@anchor{9aa}
@subsubsection PEP 681: Data class transforms


@ref{8e4,,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{6e6,,dataclass}-like behaviors.

For example:

@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

See 
@geindex Python Enhancement Proposals; PEP 681
PEP 681@footnote{https://peps.python.org/pep-0681/} for more details.

(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,New Features Related to Type Hints<2>
@anchor{whatsnew/3 11 pep-563-may-not-be-the-future}@anchor{9ca}@anchor{whatsnew/3 11 whatsnew311-pep563-deferred}@anchor{9cb}
@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{670,,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 Other Language Changes<3>,Other CPython Implementation Changes,New Features Related to Type Hints<2>,What’s New In Python 3 11
@anchor{whatsnew/3 11 other-language-changes}@anchor{9cc}@anchor{whatsnew/3 11 whatsnew311-other-lang-changes}@anchor{9cd}
@subsection Other Language Changes



@itemize *

@item 
Starred unpacking expressions can now be used in @ref{321,,for} statements.
(See bpo-46725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46725} for more details.)

@item 
Asynchronous @ref{9ce,,comprehensions} are now allowed
inside comprehensions in @ref{9cf,,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{291,,TypeError} is now raised instead of an @ref{1a9,,AttributeError} in
@ref{20a,,with} statements and @ref{9d0,,contextlib.ExitStack.enter_context()}
for objects that do not support the @ref{478,,context manager} protocol,
and in @ref{20b,,async with} statements and
@ref{9d1,,contextlib.AsyncExitStack.enter_async_context()}
for objects not supporting the @ref{9d2,,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{9d3,,object.__getstate__()}, which provides the default
implementation of the @code{__getstate__()} method. @ref{29,,copy}ing
and @ref{ab,,pickle}ing instances of subclasses of builtin types
@ref{1c6,,bytearray}, @ref{42b,,set}, @ref{9d4,,frozenset},
@ref{9d5,,collections.OrderedDict}, @ref{9d6,,collections.deque},
@ref{9d7,,weakref.WeakSet}, and @ref{9d8,,datetime.tzinfo} now copies and
pickles instance attributes implemented as @ref{9d9,,slots}.
This change has an unintended side effect: It trips up a small minority
of existing Python projects not expecting @code{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{9a5}

@itemize *

@item 
Added a @ref{9a3,,-P} command line option
and a 
@geindex PYTHONSAFEPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONSAFEPATH
@ref{9a4,,PYTHONSAFEPATH} environment variable,
which disable the automatic prepending to @ref{194,,sys.path}
of the script’s directory when running a script,
or the current directory when using @ref{445,,-c} and @ref{4ca,,-m}.
This ensures only stdlib and installed modules
are picked up by @ref{9da,,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{6fe,,Format specification mini-language} 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{194,,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{2ed,,-b} and @ref{9db,,sys.path_importer_cache} when
there is a mixture of @ref{1df,,str} and @ref{1c7,,bytes} keys.
(Contributed by Thomas Grainger in gh-91181@footnote{https://github.com/python/cpython/issues/91181}.)
@end itemize

@node Other CPython Implementation Changes,New Modules<3>,Other Language Changes<3>,What’s New In Python 3 11
@anchor{whatsnew/3 11 other-cpython-implementation-changes}@anchor{9dc}@anchor{whatsnew/3 11 whatsnew311-other-implementation-changes}@anchor{9dd}
@subsection Other CPython Implementation Changes



@itemize *

@item 
The special methods @ref{9de,,__complex__()} for @ref{328,,complex}
and @ref{9df,,__bytes__()} for @ref{1c7,,bytes} are implemented to support
the @ref{9e0,,typing.SupportsComplex} and @ref{9e1,,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{1df,,str}, @ref{1c7,,bytes}, and some other types
now use it as the default algorithm for @ref{9e2,,hash()}.
@geindex Python Enhancement Proposals; PEP 552
PEP 552@footnote{https://peps.python.org/pep-0552/} @ref{9e3,,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{9e4,,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{447,,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{9e5,,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{9e6,,PyConfig.module_search_paths_set} field must now be set to @code{1} for
initialization to use @ref{834,,PyConfig.module_search_paths} to initialize
@ref{194,,sys.path}. Otherwise, initialization will recalculate the path and replace
any values added to @code{module_search_paths}.

@item 
The output of the @ref{9e7,,--help} option now fits in 50 lines/80 columns.
Information about @ref{9e8,,Python environment variables}
and @ref{178,,-X} options is now available using the respective
@ref{9e9,,--help-env} and @ref{9ea,,--help-xoptions} flags,
and with the new @ref{9eb,,--help-all}.
(Contributed by Éric Araujo in bpo-46142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46142}.)

@item 
Converting between @ref{326,,int} and @ref{1df,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{277,,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{e2,,sys} APIs. See the @ref{9ec,,integer string conversion length limitation} documentation.  The default limit
is 4300 digits in string form.
@end itemize

@node New Modules<3>,Improved Modules<3>,Other CPython Implementation Changes,What’s New In Python 3 11
@anchor{whatsnew/3 11 new-modules}@anchor{9ed}@anchor{whatsnew/3 11 whatsnew311-new-modules}@anchor{9ee}
@subsection New Modules



@itemize *

@item 
@ref{105,,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{125,,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 Improved Modules<3>,Optimizations<6>,New Modules<3>,What’s New In Python 3 11
@anchor{whatsnew/3 11 improved-modules}@anchor{9ef}@anchor{whatsnew/3 11 whatsnew311-improved-modules}@anchor{9f0}
@subsection Improved Modules


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

@end menu

@node asyncio<7>,contextlib<2>,,Improved Modules<3>
@anchor{whatsnew/3 11 asyncio}@anchor{9f1}@anchor{whatsnew/3 11 whatsnew311-asyncio}@anchor{9f2}
@subsubsection asyncio



@itemize *

@item 
Added the @ref{6d7,,TaskGroup} class,
an @ref{9f3,,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{462,,create_task()} and @ref{9f4,,gather()} directly.
(Contributed by Yury Selivanov and others in gh-90908@footnote{https://github.com/python/cpython/issues/90908}.)

@item 
Added @ref{9f5,,timeout()}, an asynchronous context manager for
setting a timeout on asynchronous operations. For new code this is
recommended over using @ref{9f6,,wait_for()} directly.
(Contributed by Andrew Svetlov in gh-90927@footnote{https://github.com/python/cpython/issues/90927}.)

@item 
Added the @ref{30a,,Runner} class, which exposes the machinery
used by @ref{309,,run()}.
(Contributed by Andrew Svetlov in gh-91218@footnote{https://github.com/python/cpython/issues/91218}.)

@item 
Added the @ref{9f7,,Barrier} class to the synchronization
primitives in the asyncio library, and the related
@ref{9f8,,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{9f9,,asyncio.loop.create_connection()}
so that multiple connection errors can be raised as an @ref{6d8,,ExceptionGroup}.

@item 
Added the @ref{9fa,,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{9fb,,sock_sendto()},
@ref{9fc,,sock_recvfrom()} and
@ref{9fd,,sock_recvfrom_into()}.
These have implementations in @ref{30b,,SelectorEventLoop} and
@ref{9fe,,ProactorEventLoop}.
(Contributed by Alex Grönholm in bpo-46805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46805}.)

@item 
Added @ref{6db,,cancelling()} and
@ref{6dc,,uncancel()} methods to @ref{460,,Task}.
These are primarily intended for internal use,
notably by @ref{6d7,,TaskGroup}.
@end itemize

@node contextlib<2>,dataclasses<2>,asyncio<7>,Improved Modules<3>
@anchor{whatsnew/3 11 contextlib}@anchor{9ff}@anchor{whatsnew/3 11 whatsnew311-contextlib}@anchor{a00}
@subsubsection contextlib



@itemize *

@item 
Added non parallel-safe @ref{a01,,chdir()} context manager to change
the current working directory and then restore it on exit. Simple wrapper
around @ref{a02,,chdir()}. (Contributed by Filipe Laíns in bpo-25625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25625})
@end itemize

@node dataclasses<2>,datetime<3>,contextlib<2>,Improved Modules<3>
@anchor{whatsnew/3 11 dataclasses}@anchor{a03}@anchor{whatsnew/3 11 whatsnew311-dataclasses}@anchor{a04}
@subsubsection dataclasses



@itemize *

@item 
Change field default mutability check, allowing only defaults which are
@ref{183,,hashable} instead of any object which is not an instance of
@ref{188,,dict}, @ref{4d9,,list} or @ref{42b,,set}. (Contributed by Eric V. Smith in
bpo-44674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44674}.)
@end itemize

@node datetime<3>,enum<3>,dataclasses<2>,Improved Modules<3>
@anchor{whatsnew/3 11 datetime}@anchor{a05}@anchor{whatsnew/3 11 whatsnew311-datetime}@anchor{a06}
@subsubsection datetime



@itemize *

@item 
Add @ref{8fc,,datetime.UTC}, a convenience alias for
@ref{a07,,datetime.timezone.utc}. (Contributed by Kabir Kwatra in gh-91973@footnote{https://github.com/python/cpython/issues/91973}.)

@item 
@ref{a08,,datetime.date.fromisoformat()}, @ref{a09,,datetime.time.fromisoformat()} and
@ref{a0a,,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<3>,Improved Modules<3>
@anchor{whatsnew/3 11 enum}@anchor{a0b}@anchor{whatsnew/3 11 whatsnew311-enum}@anchor{a0c}
@subsubsection enum



@itemize *

@item 
Renamed @code{EnumMeta} to @ref{6fc,,EnumType}
(@code{EnumMeta} kept as an alias).

@item 
Added @ref{a0d,,StrEnum},
with members that can be used as (and must be) strings.

@item 
Added @ref{a0e,,ReprEnum},
which only modifies the @ref{1bc,,__repr__()} of members
while returning their literal values (rather than names)
for @ref{a0f,,__str__()} and @ref{a10,,__format__()}
(used by @ref{1df,,str()}, @ref{439,,format()} and @ref{858,,f-string}s).

@item 
Changed @ref{a11,,Enum.__format__()} (the default for
@ref{439,,format()}, @ref{a12,,str.format()} and @ref{858,,f-string}s) to always produce
the same result as @ref{a13,,Enum.__str__()}:  for enums inheriting from
@ref{a0e,,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{a14,,Flag} enums
and the @ref{a15,,FlagBoundary} enum with its options,
to control how to handle out-of-range flag values.

@item 
Added the @ref{a16,,verify()} enum decorator
and the @ref{a17,,EnumCheck} enum with its options,
to check enum classes against several specific constraints.

@item 
Added the @ref{a18,,member()} and @ref{a19,,nonmember()} decorators,
to ensure the decorated object is/is not converted to an enum member.

@item 
Added the @ref{a1a,,property()} decorator,
which works like @ref{6bb,,property()} except for enums.
Use this instead of @ref{a1b,,types.DynamicClassAttribute()}.

@item 
Added the @ref{a1c,,global_enum()} enum decorator,
which adjusts @ref{1bc,,__repr__()} and @ref{a0f,,__str__()}
to show values as members of their module rather than the enum class.
For example, @code{'re.ASCII'} for the @ref{a1d,,ASCII} member
of @ref{a1e,,re.RegexFlag} rather than @code{'RegexFlag.ASCII'}.

@item 
Enhanced @ref{a14,,Flag} to support
@ref{a1f,,len()}, iteration and @ref{323,,in}/@ref{a20,,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{a21,,Enum} and @ref{a14,,Flag}
so that members are now defined
before @ref{a22,,__init_subclass__()} is called;
@ref{a23,,dir()} now includes methods, etc., from mixed-in data types.

@item 
Changed @ref{a14,,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<4>,enum<3>,Improved Modules<3>
@anchor{whatsnew/3 11 fcntl}@anchor{a24}@anchor{whatsnew/3 11 whatsnew311-fcntl}@anchor{a25}
@subsubsection 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<4>,functools<4>,fcntl,Improved Modules<3>
@anchor{whatsnew/3 11 fractions}@anchor{a26}@anchor{whatsnew/3 11 whatsnew311-fractions}@anchor{a27}
@subsubsection fractions



@itemize *

@item 
Support 
@geindex Python Enhancement Proposals; PEP 515
PEP 515@footnote{https://peps.python.org/pep-0515/}-style initialization of @ref{1c3,,Fraction} from
string.  (Contributed by Sergey B Kirpichev in bpo-44258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44258}.)

@item 
@ref{1c3,,Fraction} now implements an @code{__int__} method, so
that an @code{isinstance(some_fraction, typing.SupportsInt)} check passes.
(Contributed by Mark Dickinson in bpo-44547@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44547}.)
@end itemize

@node functools<4>,gzip<2>,fractions<4>,Improved Modules<3>
@anchor{whatsnew/3 11 functools}@anchor{a28}@anchor{whatsnew/3 11 whatsnew311-functools}@anchor{a29}
@subsubsection functools



@itemize *

@item 
@ref{a2a,,functools.singledispatch()} now supports @ref{527,,types.UnionType}
and @ref{341,,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<3>,functools<4>,Improved Modules<3>
@anchor{whatsnew/3 11 gzip}@anchor{a2b}@anchor{whatsnew/3 11 whatsnew311-gzip}@anchor{a2c}
@subsubsection gzip



@itemize *

@item 
The @ref{a2d,,gzip.compress()} function is now faster when used with the
`mtime=0' argument as it delegates the compression entirely to a single
@ref{a2e,,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{6a,,gzip}
module. Now, when using @code{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<3>,IDLE and idlelib,gzip<2>,Improved Modules<3>
@anchor{whatsnew/3 11 hashlib}@anchor{a2f}@anchor{whatsnew/3 11 whatsnew311-hashlib}@anchor{a30}
@subsubsection hashlib



@itemize *

@item 
@ref{a31,,hashlib.blake2b()} and @ref{a32,,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{6b,,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{a33,,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 and idlelib,inspect<4>,hashlib<3>,Improved Modules<3>
@anchor{whatsnew/3 11 idle-and-idlelib}@anchor{a34}@anchor{whatsnew/3 11 whatsnew311-idle}@anchor{a35}
@subsubsection IDLE and idlelib



@itemize *

@item 
Apply syntax highlighting to @code{.pyi} files. (Contributed by Alex
Waygood and Terry Jan Reedy in 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<4>,locale<4>,IDLE and idlelib,Improved Modules<3>
@anchor{whatsnew/3 11 inspect}@anchor{a36}@anchor{whatsnew/3 11 whatsnew311-inspect}@anchor{a37}
@subsubsection inspect



@itemize *

@item 
Add @ref{a38,,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{a39,,ismethodwrapper()}
for checking if the type of an object is a @ref{a3a,,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{81,,inspect} module to return new
@ref{a3b,,FrameInfo} and @ref{a3c,,Traceback} class instances
(backwards compatible with the previous @ref{a3d,,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{a3e,,inspect.getframeinfo()}

@item 
@ref{a3f,,inspect.getouterframes()}

@item 
@ref{a40,,inspect.getinnerframes()},

@item 
@ref{a41,,inspect.stack()}

@item 
@ref{a42,,inspect.trace()}
@end itemize

(Contributed by Pablo Galindo in gh-88116@footnote{https://github.com/python/cpython/issues/88116}.)
@end itemize

@node locale<4>,logging,inspect<4>,Improved Modules<3>
@anchor{whatsnew/3 11 locale}@anchor{a43}@anchor{whatsnew/3 11 whatsnew311-locale}@anchor{a44}
@subsubsection locale



@itemize *

@item 
Add @ref{a45,,locale.getencoding()} to get the current locale encoding. It is similar to
@code{locale.getpreferredencoding(False)} but ignores the
@ref{a46,,Python UTF-8 Mode}.
@end itemize

@node logging,math<5>,locale<4>,Improved Modules<3>
@anchor{whatsnew/3 11 logging}@anchor{a47}@anchor{whatsnew/3 11 whatsnew311-logging}@anchor{a48}
@subsubsection logging



@itemize *

@item 
Added @ref{a49,,getLevelNamesMapping()}
to return a mapping from logging level names (e.g. @code{'CRITICAL'})
to the values of their corresponding @ref{a4a,,Logging Levels} (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{a4b,,createSocket()} method
to @ref{a4c,,SysLogHandler}, to match
@ref{a4d,,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<5>,operator<2>,logging,Improved Modules<3>
@anchor{whatsnew/3 11 math}@anchor{a4e}@anchor{whatsnew/3 11 whatsnew311-math}@anchor{a4f}
@subsubsection math



@itemize *

@item 
Add @ref{a50,,math.exp2()}: return 2 raised to the power of x.
(Contributed by Gideon Mitchell in bpo-45917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45917}.)

@item 
Add @ref{a51,,math.cbrt()}: return the cube root of x.
(Contributed by Ajith Ramachandran in bpo-44357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44357}.)

@item 
The behaviour of two @ref{a52,,math.pow()} corner cases was changed, for
consistency with the IEEE 754 specification. The operations
@code{math.pow(0.0, -math.inf)} and @code{math.pow(-0.0, -math.inf)} now return
@code{inf}. Previously they raised @ref{277,,ValueError}. (Contributed by Mark
Dickinson in bpo-44339@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44339}.)

@item 
The @ref{a53,,math.nan} value is now always available.
(Contributed by Victor Stinner in bpo-46917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46917}.)
@end itemize

@node operator<2>,os<5>,math<5>,Improved Modules<3>
@anchor{whatsnew/3 11 operator}@anchor{a54}@anchor{whatsnew/3 11 whatsnew311-operator}@anchor{a55}
@subsubsection 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<5>,pathlib<8>,operator<2>,Improved Modules<3>
@anchor{whatsnew/3 11 os}@anchor{a56}@anchor{whatsnew/3 11 whatsnew311-os}@anchor{a57}
@subsubsection os



@itemize *

@item 
On Windows, @ref{931,,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<8>,re<5>,os<5>,Improved Modules<3>
@anchor{whatsnew/3 11 pathlib}@anchor{a58}@anchor{whatsnew/3 11 whatsnew311-pathlib}@anchor{a59}
@subsubsection pathlib



@itemize *

@item 
@ref{73a,,glob()} and @ref{73b,,rglob()} return only
directories if `pattern' ends with a pathname components separator:
@ref{a5a,,sep} or @ref{a5b,,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<5>,shutil<3>,pathlib<8>,Improved Modules<3>
@anchor{whatsnew/3 11 re}@anchor{a5c}@anchor{whatsnew/3 11 whatsnew311-re}@anchor{a5d}
@subsubsection re



@itemize *

@item 
Atomic grouping (@code{(?>...)}) and possessive quantifiers (@code{*+}, @code{++},
@code{?+}, @code{@{m,n@}+}) are now supported in regular expressions.
(Contributed by Jeffrey C. Jacobs and Serhiy Storchaka in bpo-433030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=433030}.)
@end itemize

@node shutil<3>,socket<3>,re<5>,Improved Modules<3>
@anchor{whatsnew/3 11 shutil}@anchor{a5e}@anchor{whatsnew/3 11 whatsnew311-shutil}@anchor{a5f}
@subsubsection shutil



@itemize *

@item 
Add optional parameter `dir_fd' in @ref{335,,shutil.rmtree()}.
(Contributed by Serhiy Storchaka in bpo-46245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46245}.)
@end itemize

@node socket<3>,sqlite3<6>,shutil<3>,Improved Modules<3>
@anchor{whatsnew/3 11 socket}@anchor{a60}@anchor{whatsnew/3 11 whatsnew311-socket}@anchor{a61}
@subsubsection 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{a62,,create_connection()} has an option to raise, in case of
failure to connect, an @ref{6d8,,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<6>,string,socket<3>,Improved Modules<3>
@anchor{whatsnew/3 11 sqlite3}@anchor{a63}@anchor{whatsnew/3 11 whatsnew311-sqlite3}@anchor{a64}
@subsubsection sqlite3



@itemize *

@item 
You can now disable the authorizer by passing @ref{a65,,None} to
@ref{3e3,,set_authorizer()}.
(Contributed by Erlend E. Aasland in bpo-44491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44491}.)

@item 
Collation name @ref{a66,,create_collation()} can now
contain any Unicode character.  Collation names with invalid characters
now raise @ref{a67,,UnicodeEncodeError} instead of @ref{57d,,sqlite3.ProgrammingError}.
(Contributed by Erlend E. Aasland in bpo-44688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44688}.)

@item 
@ref{d7,,sqlite3} exceptions now include the SQLite extended error code as
@ref{a68,,sqlite_errorcode} and the SQLite error name as
@ref{a69,,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 
Add @ref{a6a,,setlimit()} and
@ref{a6b,,getlimit()} to @ref{3df,,sqlite3.Connection} for
setting and getting SQLite limits by connection basis.
(Contributed by Erlend E. Aasland in bpo-45243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45243}.)

@item 
@ref{d7,,sqlite3} now sets @ref{a6c,,sqlite3.threadsafety} based on the default
threading mode the underlying SQLite library has been compiled with.
(Contributed by Erlend E. Aasland in bpo-45613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45613}.)

@item 
@ref{d7,,sqlite3} C callbacks now use unraisable exceptions if callback
tracebacks are enabled. Users can now register an
@ref{70c,,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{a6d,,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{a6e,,serialize()} and
@ref{a6f,,deserialize()} to @ref{3df,,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{a70,,create_window_function()} to
@ref{3df,,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{a71,,blobopen()} to @ref{3df,,sqlite3.Connection}.
@ref{a72,,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<5>,sqlite3<6>,Improved Modules<3>
@anchor{whatsnew/3 11 string}@anchor{a73}@anchor{whatsnew/3 11 whatsnew311-string}@anchor{a74}
@subsubsection string



@itemize *

@item 
Add @ref{a75,,get_identifiers()}
and @ref{a76,,is_valid()} to @ref{a77,,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<5>,sysconfig<4>,string,Improved Modules<3>
@anchor{whatsnew/3 11 sys}@anchor{a78}@anchor{whatsnew/3 11 whatsnew311-sys}@anchor{a79}
@subsubsection sys



@itemize *

@item 
@ref{a7a,,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 
Add @ref{a7b,,sys.exception()} which returns the active exception instance
(equivalent to @code{sys.exc_info()[1]}).
(Contributed by Irit Katriel in bpo-46328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46328}.)

@item 
Add the @ref{a7c,,sys.flags.safe_path} flag.
(Contributed by Victor Stinner in gh-57684@footnote{https://github.com/python/cpython/issues/57684}.)
@end itemize

@node sysconfig<4>,tempfile<3>,sys<5>,Improved Modules<3>
@anchor{whatsnew/3 11 sysconfig}@anchor{a7d}@anchor{whatsnew/3 11 whatsnew311-sysconfig}@anchor{a7e}
@subsubsection sysconfig



@itemize *

@item 
Three new @ref{65c,,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{a7f,,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{11a,,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<5>,sysconfig<4>,Improved Modules<3>
@anchor{whatsnew/3 11 tempfile}@anchor{a80}@anchor{whatsnew/3 11 whatsnew311-tempfile}@anchor{a81}
@subsubsection tempfile



@itemize *

@item 
@ref{a82,,SpooledTemporaryFile} objects now fully implement the methods
of @ref{a83,,io.BufferedIOBase} or @ref{a84,,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<5>,time<2>,tempfile<3>,Improved Modules<3>
@anchor{whatsnew/3 11 threading}@anchor{a85}@anchor{whatsnew/3 11 whatsnew311-threading}@anchor{a86}
@subsubsection threading



@itemize *

@item 
On Unix, if the @code{sem_clockwait()} function is available in the C library
(glibc 2.30 and newer), the @ref{a87,,threading.Lock.acquire()} method now uses
the monotonic clock (@ref{a88,,time.CLOCK_MONOTONIC}) for the timeout, rather
than using the system clock (@ref{a89,,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<5>,threading<5>,Improved Modules<3>
@anchor{whatsnew/3 11 time}@anchor{a8a}@anchor{whatsnew/3 11 whatsnew311-time}@anchor{a8b}
@subsubsection time



@itemize *

@item 
On Unix, @ref{a8c,,time.sleep()} now uses the @code{clock_nanosleep()} or
@code{nanosleep()} function, if available, which has a resolution of 1 nanosecond
(10@w{^-9} seconds), rather than using @code{select()} which has a resolution
of 1 microsecond (10@w{^-6} seconds).
(Contributed by Benjamin Szőke and Victor Stinner in bpo-21302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21302}.)

@item 
On Windows 8.1 and newer, @ref{a8c,,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<5>,traceback<2>,time<2>,Improved Modules<3>
@anchor{whatsnew/3 11 tkinter}@anchor{a8d}@anchor{whatsnew/3 11 whatsnew311-tkinter}@anchor{a8e}
@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{2fc,,sys.version_info}.
(Contributed by Serhiy Storchaka in gh-91827@footnote{https://github.com/python/cpython/issues/91827}.)
@end itemize

@node traceback<2>,typing<7>,tkinter<5>,Improved Modules<3>
@anchor{whatsnew/3 11 traceback}@anchor{a8f}@anchor{whatsnew/3 11 whatsnew311-traceback}@anchor{a90}
@subsubsection traceback



@itemize *

@item 
Add @ref{a91,,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{a92,,traceback.TracebackException.print()}, which prints the
formatted @ref{764,,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<7>,unicodedata<5>,traceback<2>,Improved Modules<3>
@anchor{whatsnew/3 11 typing}@anchor{a93}@anchor{whatsnew/3 11 whatsnew311-typing}@anchor{a94}
@subsubsection typing


For major changes, see @ref{9bd,,New Features Related to Type Hints}.


@itemize *

@item 
Add @ref{a95,,typing.assert_never()} and @ref{a96,,typing.Never}.
@code{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{a97,,AssertionError}.
(Contributed by Jelle Zijlstra in gh-90633@footnote{https://github.com/python/cpython/issues/90633}.)

@item 
Add @ref{a98,,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{a99,,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{290,,typing.TypedDict} types can now be generic. (Contributed by
Samodya Abeysiriwardane in gh-89026@footnote{https://github.com/python/cpython/issues/89026}.)

@item 
@ref{2e4,,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{a9a,,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{a9b,,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{a9c,,typing.get_overloads()} function can be used for introspecting
the overloads of a function. @ref{a9d,,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{2fa,,__init__()} method of @ref{76c,,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{a9e,,typing.get_type_hints()} now supports evaluating strings as forward
references in @ref{a9f,,PEP 585 generic aliases}.
(Contributed by Niklas Rosenstein in gh-85542@footnote{https://github.com/python/cpython/issues/85542}.)

@item 
@ref{a9e,,typing.get_type_hints()} no longer adds @ref{aa0,,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{a9e,,typing.get_type_hints()} now supports evaluating bare stringified
@ref{76e,,ClassVar} annotations. (Contributed by Gregory Beauregard
in gh-90711@footnote{https://github.com/python/cpython/issues/90711}.)

@item 
@ref{aa1,,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<5>,unittest<6>,typing<7>,Improved Modules<3>
@anchor{whatsnew/3 11 unicodedata}@anchor{aa2}@anchor{whatsnew/3 11 whatsnew311-unicodedata}@anchor{aa3}
@subsubsection 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<6>,venv<3>,unicodedata<5>,Improved Modules<3>
@anchor{whatsnew/3 11 unittest}@anchor{aa4}@anchor{whatsnew/3 11 whatsnew311-unittest}@anchor{aa5}
@subsubsection unittest



@itemize *

@item 
Added methods @ref{aa6,,enterContext()} and
@ref{aa7,,enterClassContext()} of class
@ref{52f,,TestCase}, method
@ref{aa8,,enterAsyncContext()} of
class @ref{342,,IsolatedAsyncioTestCase} and function
@ref{aa9,,unittest.enterModuleContext()}.
(Contributed by Serhiy Storchaka in bpo-45046@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45046}.)
@end itemize

@node venv<3>,warnings<3>,unittest<6>,Improved Modules<3>
@anchor{whatsnew/3 11 venv}@anchor{aaa}@anchor{whatsnew/3 11 whatsnew311-venv}@anchor{aab}
@subsubsection venv



@itemize *

@item 
When new Python virtual environments are created, the `venv'
@ref{65c,,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<3>,zipfile<2>,venv<3>,Improved Modules<3>
@anchor{whatsnew/3 11 warnings}@anchor{aac}@anchor{whatsnew/3 11 whatsnew311-warnings}@anchor{aad}
@subsubsection warnings



@itemize *

@item 
@ref{423,,warnings.catch_warnings()} now accepts arguments for @ref{aae,,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<2>,,warnings<3>,Improved Modules<3>
@anchor{whatsnew/3 11 whatsnew311-zipfile}@anchor{aaf}@anchor{whatsnew/3 11 zipfile}@anchor{ab0}
@subsubsection zipfile



@itemize *

@item 
Added support for specifying member name encoding for reading metadata
in a @ref{ab1,,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{ab2,,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{ab3,,stem}, @ref{ab4,,suffix}
and @ref{ab5,,suffixes} to @ref{ab6,,zipfile.Path}.
(Contributed by Miguel Brito in gh-88261@footnote{https://github.com/python/cpython/issues/88261}.)
@end itemize

@node Optimizations<6>,Faster CPython,Improved Modules<3>,What’s New In Python 3 11
@anchor{whatsnew/3 11 optimizations}@anchor{ab7}@anchor{whatsnew/3 11 whatsnew311-optimizations}@anchor{ab8}
@subsection Optimizations


This section covers specific optimizations independent of the
@ref{99f,,Faster CPython} project, which is covered in its own section.


@itemize *

@item 
The compiler now optimizes simple
@ref{ab9,,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{858,,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{326,,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{881,,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 @ref{aba,,list.append()} by ≈15%
and simple @ref{abb,,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{188,,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{abc,,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{91,,math} functions @ref{abd,,comb()} and @ref{abe,,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{da,,statistics} functions @ref{abf,,mean()},
@ref{ac0,,variance()} and @ref{ac1,,stdev()} now consume
iterators in one pass rather than converting them to a @ref{4d9,,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{ac2,,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,CPython bytecode changes<3>,Optimizations<6>,What’s New In Python 3 11
@anchor{whatsnew/3 11 faster-cpython}@anchor{ac3}@anchor{whatsnew/3 11 whatsnew311-faster-cpython}@anchor{99f}
@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{ac4,,Faster Startup} and @ref{ac5,,Faster Runtime}.
Optimizations not covered by this project are listed separately under
@ref{ab8,,Optimizations}.

@menu
* Faster Startup:: 
* Faster Runtime:: 
* Misc:: 
* FAQ:: 
* About:: 

@end menu

@node Faster Startup,Faster Runtime,,Faster CPython
@anchor{whatsnew/3 11 faster-startup}@anchor{ac6}@anchor{whatsnew/3 11 whatsnew311-faster-startup}@anchor{ac4}
@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{ac7}@anchor{whatsnew/3 11 whatsnew311-faster-imports}@anchor{ac8}
@subsubsection Frozen imports / Static code objects


Python caches @ref{6b3,,bytecode} in the @ref{ac9,,__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{9b4,,Code Objects} (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

Interpreter startup is now 10-15% faster in Python 3.11. This has a big
impact for short-running programs using 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{aca}@anchor{whatsnew/3 11 whatsnew311-faster-runtime}@anchor{ac5}
@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{acb}@anchor{whatsnew/3 11 whatsnew311-lazy-python-frames}@anchor{acc}
@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{acd,,frame objects}
are now created only when requested by debuggers
or by Python introspection functions such as @ref{ace,,sys._getframe()} and
@ref{acf,,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{ad0}
@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{ad1}@anchor{whatsnew/3 11 whatsnew311-inline-calls}@anchor{ad2}
@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{8d3,,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{ad3}@anchor{whatsnew/3 11 whatsnew311-pep659}@anchor{6ab}
@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{6b3,,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

Operation

@tab

Form

@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{326,,int}, @ref{327,,float} and @ref{1df,,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{4d9,,list},
@ref{1ce,,tuple} and @ref{188,,dict} directly index
the underlying data structures.

Subscripting custom @ref{787,,__getitem__()}
is also inlined similar to @ref{ad0,,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

Calls

@tab

@code{f(arg)}

@code{C(arg)}

@tab

Calls to common builtin (C) functions and types such
as @ref{a1f,,len()} and @ref{1df,,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{4d9,,list} and @ref{1ce,,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{ad4}@anchor{whatsnew/3 11 whatsnew311-faster-cpython-misc}@anchor{ad5}
@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{ad6,,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{c1,,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,About,Misc,Faster CPython
@anchor{whatsnew/3 11 faq}@anchor{ad7}@anchor{whatsnew/3 11 whatsnew311-faster-cpython-faq}@anchor{ad8}
@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{ad9}@anchor{whatsnew/3 11 how-should-i-write-my-code-to-utilize-these-speedups}@anchor{ada}
@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{adb}@anchor{whatsnew/3 11 will-cpython-3-11-use-more-memory}@anchor{adc}
@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{add}@anchor{whatsnew/3 11 i-don-t-see-any-speedups-in-my-workload-why}@anchor{ade}
@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{adf}@anchor{whatsnew/3 11 is-there-a-jit-compiler}@anchor{ae0}
@subsubsection Is there a JIT compiler?


No. We’re still exploring other optimizations.

@node About,,FAQ,Faster CPython
@anchor{whatsnew/3 11 about}@anchor{ae1}@anchor{whatsnew/3 11 whatsnew311-faster-cpython-about}@anchor{ae2}
@subsubsection About


Faster CPython explores optimizations for @ref{ae3,,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 CPython bytecode changes<3>,Deprecated<6>,Faster CPython,What’s New In Python 3 11
@anchor{whatsnew/3 11 cpython-bytecode-changes}@anchor{ae4}@anchor{whatsnew/3 11 whatsnew311-bytecode-changes}@anchor{ae5}
@subsection CPython bytecode changes


The bytecode now contains inline cache entries,
which take the form of the newly-added @ref{ae6,,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,,CPython bytecode changes<3>
@anchor{whatsnew/3 11 new-opcodes}@anchor{ae7}@anchor{whatsnew/3 11 whatsnew311-added-opcodes}@anchor{ae8}
@subsubsection New opcodes



@itemize *

@item 
@code{ASYNC_GEN_WRAP}, @ref{ae9,,RETURN_GENERATOR} and @ref{aea,,SEND},
used in generators and co-routines.

@item 
@ref{aeb,,COPY_FREE_VARS},
which avoids needing special caller-side code for closures.

@item 
@ref{aec,,JUMP_BACKWARD_NO_INTERRUPT},
for use in certain loops where handling interrupts is undesirable.

@item 
@ref{aed,,MAKE_CELL}, to create @ref{aee,,Cell Objects}.

@item 
@ref{aef,,CHECK_EG_MATCH}  and  @code{PREP_RERAISE_STAR},
to handle the @ref{9a0,,new exception groups and except*}
added in 
@geindex Python Enhancement Proposals; PEP 654
PEP 654@footnote{https://peps.python.org/pep-0654/}.

@item 
@ref{af0,,PUSH_EXC_INFO}, for use in exception handlers.

@item 
@ref{7b4,,RESUME}, a no-op,
for internal tracing, debugging and optimization checks.
@end itemize

@node Replaced opcodes,Changed/removed opcodes,New opcodes,CPython bytecode changes<3>
@anchor{whatsnew/3 11 replaced-opcodes}@anchor{af1}@anchor{whatsnew/3 11 whatsnew311-replaced-opcodes}@anchor{af2}
@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{595,,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{af3,,CALL}@w{ }
@code{KW_NAMES}@w{ }
@code{PRECALL}@w{ }
@ref{af4,,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{af5,,COPY}@w{ }
@ref{af6,,SWAP}@w{ }
@end display



@tab

Stack manipulation instructions

@item


@display
@code{JUMP_IF_NOT_EXC_MATCH}@w{ }
@end display



@tab


@display
@ref{af7,,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{af8,,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

@code{BEFORE_WITH}

@tab

@ref{20a,,with} block setup

@end multitable

@anchor{whatsnew/3 11 whatsnew311-changed-opcodes}@anchor{af9}@anchor{whatsnew/3 11 whatsnew311-removed-opcodes}@anchor{afa}
@node Changed/removed opcodes,,Replaced opcodes,CPython bytecode changes<3>
@anchor{whatsnew/3 11 changed-removed-opcodes}@anchor{afb}@anchor{whatsnew/3 11 whatsnew311-changed-removed-opcodes}@anchor{afc}
@subsubsection Changed/removed opcodes



@itemize *

@item 
Changed @ref{afd,,MATCH_CLASS} and @ref{afe,,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{aff}
@node Deprecated<6>,Pending Removal in Python 3 12,CPython bytecode changes<3>,What’s New In Python 3 11
@anchor{whatsnew/3 11 deprecated}@anchor{b00}@anchor{whatsnew/3 11 whatsnew311-python-api-deprecated}@anchor{b01}
@subsection Deprecated


This section lists Python APIs that have been deprecated in Python 3.11.

Deprecated C APIs are @ref{b02,,listed separately}.
@anchor{whatsnew/3 11 whatsnew311-deprecated-language}@anchor{b03}
@menu
* Language/Builtins:: 
* Modules:: 
* Standard Library:: 

@end menu

@node Language/Builtins,Modules,,Deprecated<6>
@anchor{whatsnew/3 11 language-builtins}@anchor{b04}@anchor{whatsnew/3 11 whatsnew311-deprecated-builtins}@anchor{b05}
@subsubsection Language/Builtins



@itemize *

@item 
Chaining @ref{69a,,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{6bb,,property}.  The core design of this feature was flawed
and caused a number of downstream problems.  To «pass-through» a
@code{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{2c9,,DeprecationWarning}.
In a future Python version, they will raise a @ref{44a,,SyntaxWarning} and
eventually a @ref{17e,,SyntaxError}.
(Contributed by Serhiy Storchaka in gh-81548@footnote{https://github.com/python/cpython/issues/81548}.)

@item 
The delegation of @ref{326,,int()} to @ref{43b,,__trunc__()} is now deprecated.
Calling @code{int(a)} when @code{type(a)} implements @code{__trunc__()} but not
@ref{43c,,__int__()} or @ref{43d,,__index__()} now raises
a @ref{2c9,,DeprecationWarning}.
(Contributed by Zackery Spytz in bpo-44977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44977}.)
@end itemize

@node Modules,Standard Library,Language/Builtins,Deprecated<6>
@anchor{whatsnew/3 11 modules}@anchor{b06}@anchor{whatsnew/3 11 whatsnew311-deprecated-modules}@anchor{b07}
@subsubsection Modules

@anchor{whatsnew/3 11 whatsnew311-pep594}@anchor{9ab}

@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 Standard Library,,Modules,Deprecated<6>
@anchor{whatsnew/3 11 standard-library}@anchor{b08}@anchor{whatsnew/3 11 whatsnew311-deprecated-stdlib}@anchor{b09}
@subsubsection Standard Library



@itemize *

@item 
The following have been deprecated in @ref{26,,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{26,,configparser} documentation.
It now emits a @ref{2c9,,DeprecationWarning} and will be removed
in Python 3.13. Use @ref{b0a,,configparser.BasicInterpolation} or
@ref{b0b,,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{7e,,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{233,,locale.getdefaultlocale()} function is deprecated and will be
removed in Python 3.15. Use @ref{231,,locale.setlocale()},
@ref{947,,locale.getpreferredencoding(False)} and
@ref{232,,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{b0c,,regular expressions}.
Only sequences of ASCII digits will now be accepted as a numerical reference,
and the group name in @ref{1c7,,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{c1,,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{b0d,,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{340,,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{1df,,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{290,,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{11e,,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{52f,,TestCase} and
@ref{342,,IsolatedAsyncioTestCase} test methods (other than the
default @code{None} value) is now deprecated.

@item 
Deprecated the following not-formally-documented @ref{10f,,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{792,,TestLoader} methods instead:


@itemize *

@item 
@ref{793,,unittest.TestLoader.loadTestsFromModule()}

@item 
@ref{794,,unittest.TestLoader.loadTestsFromTestCase()}

@item 
@ref{795,,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{b0e}
@node Pending Removal in Python 3 12,Removed<6>,Deprecated<6>,What’s New In Python 3 11
@anchor{whatsnew/3 11 pending-removal-in-python-3-12}@anchor{b0f}@anchor{whatsnew/3 11 whatsnew311-python-api-pending-removal}@anchor{b10}
@subsection Pending Removal in Python 3.12


The following Python APIs have been deprecated in earlier Python releases,
and will be removed in Python 3.12.

C APIs pending removal are
@ref{b11,,listed separately}.


@itemize *

@item 
The @code{asynchat} module

@item 
The @code{asyncore} module

@item 
The @ref{b12,,entire distutils package}

@item 
The @code{imp} module

@item 
The @ref{4c6,,typing.io} namespace

@item 
The @ref{b13,,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{10f,,unittest}:

@quotation


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Deprecated alias

@tab

Method Name

@tab

Deprecated in

@item

@code{failUnless}

@tab

@ref{935,,assertTrue()}

@tab

3.1

@item

@code{failIf}

@tab

@ref{936,,assertFalse()}

@tab

3.1

@item

@code{failUnlessEqual}

@tab

@ref{937,,assertEqual()}

@tab

3.1

@item

@code{failIfEqual}

@tab

@ref{938,,assertNotEqual()}

@tab

3.1

@item

@code{failUnlessAlmostEqual}

@tab

@ref{939,,assertAlmostEqual()}

@tab

3.1

@item

@code{failIfAlmostEqual}

@tab

@ref{93a,,assertNotAlmostEqual()}

@tab

3.1

@item

@code{failUnlessRaises}

@tab

@ref{93b,,assertRaises()}

@tab

3.1

@item

@code{assert_}

@tab

@ref{935,,assertTrue()}

@tab

3.2

@item

@code{assertEquals}

@tab

@ref{937,,assertEqual()}

@tab

3.2

@item

@code{assertNotEquals}

@tab

@ref{938,,assertNotEqual()}

@tab

3.2

@item

@code{assertAlmostEquals}

@tab

@ref{939,,assertAlmostEqual()}

@tab

3.2

@item

@code{assertNotAlmostEquals}

@tab

@ref{93a,,assertNotAlmostEqual()}

@tab

3.2

@item

@code{assertRegexpMatches}

@tab

@ref{93c,,assertRegex()}

@tab

3.2

@item

@code{assertRaisesRegexp}

@tab

@ref{93d,,assertRaisesRegex()}

@tab

3.2

@item

@code{assertNotRegexpMatches}

@tab

@ref{93e,,assertNotRegex()}

@tab

3.5

@end multitable

@end quotation
@end itemize
@anchor{whatsnew/3 11 whatsnew311-removed}@anchor{b14}
@node Removed<6>,Porting to Python 3 11,Pending Removal in Python 3 12,What’s New In Python 3 11
@anchor{whatsnew/3 11 removed}@anchor{b15}@anchor{whatsnew/3 11 whatsnew311-python-api-removed}@anchor{b16}
@subsection Removed


This section lists Python APIs that have been removed in Python 3.11.

Removed C APIs are @ref{b17,,listed separately}.


@itemize *

@item 
Removed the @code{@@asyncio.coroutine()} @ref{b18,,decorator}
enabling legacy generator-based coroutines to be compatible with
@ref{b19,,async} / @ref{432,,await} code.
The function has been deprecated since Python 3.8 and the removal was
initially scheduled for Python 3.10. Use @ref{9cf,,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{b1a,,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{11,,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{b1b,,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{787,,__getitem__()} methods of
@ref{b1c,,xml.dom.pulldom.DOMEventStream}, @ref{b1d,,wsgiref.util.FileWrapper}
and @ref{b1e,,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{66,,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{81,,inspect} module:


@itemize *

@item 
The @code{getargspec()} function, deprecated since Python 3.0;
use @ref{4bd,,inspect.signature()} or @ref{b1f,,inspect.getfullargspec()} instead.

@item 
The @code{formatargspec()} function, deprecated since Python 3.5;
use the @ref{4bd,,inspect.signature()} function
or the @ref{6e8,,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{b20,,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{b21,,__class_getitem__()} method
from @ref{8b6,,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{10f,,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{b22}
@node Porting to Python 3 11,Build Changes<3>,Removed<6>,What’s New In Python 3 11
@anchor{whatsnew/3 11 porting-to-python-3-11}@anchor{b23}@anchor{whatsnew/3 11 whatsnew311-python-api-porting}@anchor{b24}
@subsection Porting to Python 3.11


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

Porting notes for the C API are
@ref{b25,,listed separately}.


@itemize *

@item 
@ref{32b,,open()}, @ref{92b,,io.open()}, @ref{32c,,codecs.open()} and
@ref{b1e,,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{b26,,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{2ec,,ast.AST} node positions are now validated when provided to
@ref{1c8,,compile()} and other related functions. If invalid positions are detected,
a @ref{277,,ValueError} will be raised. (Contributed by Pablo Galindo in gh-93351@footnote{https://github.com/python/cpython/issues/93351})

@item 
Prohibited passing non-@ref{b27,,concurrent.futures.ThreadPoolExecutor}
executors to @ref{b28,,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{15,,calendar}: The @ref{b29,,calendar.LocaleTextCalendar} and
@ref{b2a,,calendar.LocaleHTMLCalendar} classes now use
@ref{232,,locale.getlocale()}, instead of using @ref{233,,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{aa,,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{b2b,,random.sample()} must be a sequence,
and automatic conversion of @ref{42b,,set}s to @ref{4d9,,list}s
is no longer supported. Also, if the sample size
is larger than the population size, a @ref{277,,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{b2c,,random.shuffle()} was removed.
It was previously an arbitrary random function to use for the shuffle;
now, @ref{b2d,,random.random()} (its previous default) will always be used.

@item 
In @ref{c1,,re} @ref{b0c,,Regular expression syntax}, 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{c1,,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 Build Changes<3>,C API Changes<3>,Porting to Python 3 11,What’s New In Python 3 11
@anchor{whatsnew/3 11 build-changes}@anchor{b2e}@anchor{whatsnew/3 11 whatsnew311-build-changes}@anchor{b2f}
@subsection Build Changes



@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{f9,,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{f9,,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{b30,,--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 @code{--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 Σημείωση 
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{326,,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{b31,,--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 C API Changes<3>,Notable changes in 3 11 4,Build Changes<3>,What’s New In Python 3 11
@anchor{whatsnew/3 11 c-api-changes}@anchor{b32}@anchor{whatsnew/3 11 whatsnew311-c-api}@anchor{b33}
@subsection C API Changes


@menu
* New Features: New Features<6>. 
* Porting to Python 3.11: Porting to Python 3 11<2>. 
* Deprecated: Deprecated<7>. 
* Pending Removal in Python 3.12: Pending Removal in Python 3 12<2>. 
* Removed: Removed<7>. 

@end menu

@node New Features<6>,Porting to Python 3 11<2>,,C API Changes<3>
@anchor{whatsnew/3 11 id5}@anchor{b34}@anchor{whatsnew/3 11 whatsnew311-c-api-new-features}@anchor{b35}
@subsubsection New Features



@itemize *

@item 
Add a new @ref{b36,,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{b37,,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{b38,,PyThreadState_EnterTracing()} and
@ref{b39,,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{5ae,,Py_Version} constant which bears the same value as
@ref{5af,,PY_VERSION_HEX}.
(Contributed by  Gabriele N. Tornetta in bpo-43931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43931}.)

@item 
@ref{b3a,,Py_buffer} and APIs are now part of the limited API and the stable
ABI:


@itemize *

@item 
@ref{82b,,PyObject_CheckBuffer()}

@item 
@ref{82c,,PyObject_GetBuffer()}

@item 
@ref{b3b,,PyBuffer_GetPointer()}

@item 
@ref{b3c,,PyBuffer_SizeFromFormat()}

@item 
@ref{b3d,,PyBuffer_ToContiguous()}

@item 
@ref{b3e,,PyBuffer_FromContiguous()}

@item 
@ref{b3f,,PyObject_CopyData()}

@item 
@ref{b40,,PyBuffer_IsContiguous()}

@item 
@ref{b41,,PyBuffer_FillContiguousStrides()}

@item 
@ref{b42,,PyBuffer_FillInfo()}

@item 
@ref{82d,,PyBuffer_Release()}

@item 
@ref{b43,,PyMemoryView_FromBuffer()}

@item 
@ref{b44,,bf_getbuffer} and
@ref{b45,,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{827,,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{b46,,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{b47,,PyFloat_Pack2()}, @ref{b48,,PyFloat_Pack4()}, @ref{b49,,PyFloat_Pack8()},
@ref{b4a,,PyFloat_Unpack2()}, @ref{b4b,,PyFloat_Unpack4()} and
@ref{b4c,,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{b4d,,PyFrame_GetBuiltins()}, @ref{b4e,,PyFrame_GetGenerator()},
@ref{b4f,,PyFrame_GetGlobals()}, @ref{b50,,PyFrame_GetLasti()}.

@item 
Added two new functions to get and set the active exception instance:
@ref{b51,,PyErr_GetHandledException()} and @ref{b52,,PyErr_SetHandledException()}.
These are alternatives to @ref{b53,,PyErr_SetExcInfo()} and
@ref{b54,,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{b55,,PyConfig.safe_path} member.
(Contributed by Victor Stinner in gh-57684@footnote{https://github.com/python/cpython/issues/57684}.)
@end itemize

@node Porting to Python 3 11<2>,Deprecated<7>,New Features<6>,C API Changes<3>
@anchor{whatsnew/3 11 id6}@anchor{b56}@anchor{whatsnew/3 11 whatsnew311-c-api-porting}@anchor{b25}
@subsubsection Porting to Python 3.11

@anchor{whatsnew/3 11 whatsnew311-pep670}@anchor{9ad}

@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{b53,,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{b54,,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{b57,,_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{b58,,_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{b59,,PyCodeObject} no longer has the @code{co_code}, @code{co_varnames},
@code{co_cellvars} and @code{co_freevars} fields.  Instead, use
@ref{b5a,,PyCode_GetCode()}, @ref{b5b,,PyCode_GetVarnames()},
@ref{b5c,,PyCode_GetCellvars()} and @ref{b5d,,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{b5e,,PyType_Ready()} function now raises an error if a type is defined
with the @ref{39e,,Py_TPFLAGS_HAVE_GC} flag set but has no traverse function
(@ref{36b,,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{5fb,,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{b5f,,static types}.
(Contributed by Erlend E. Aasland in bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908})

@item 
Since @ref{5f5,,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{b60,,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

(Contributed by Victor Stinner in bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}.)

@item 
Since @ref{b61,,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{b62,,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

(Contributed by Victor Stinner in 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{b63,,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{b64,,PyFrame_Check()}

@item 
@ref{b65,,PyFrame_GetBack()}

@item 
@ref{b4d,,PyFrame_GetBuiltins()}

@item 
@ref{b4e,,PyFrame_GetGenerator()}

@item 
@ref{b4f,,PyFrame_GetGlobals()}

@item 
@ref{b50,,PyFrame_GetLasti()}

@item 
@ref{84e,,PyFrame_GetLocals()}

@item 
@ref{b66,,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{b67}

@itemize *

@item 
The @ref{b68,,PyFrameObject} structure members have been removed from the
public C API.

While the documentation notes that the @ref{b68,,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{b68,,PyFrameObject} fields:


@itemize *

@item 
@code{f_back}: use @ref{b65,,PyFrame_GetBack()}.

@item 
@code{f_blockstack}: removed.

@item 
@code{f_builtins}: use @ref{b4d,,PyFrame_GetBuiltins()}.

@item 
@code{f_code}: use @ref{b69,,PyFrame_GetCode()}.

@item 
@code{f_gen}: use @ref{b4e,,PyFrame_GetGenerator()}.

@item 
@code{f_globals}: use @ref{b4f,,PyFrame_GetGlobals()}.

@item 
@code{f_iblock}: removed.

@item 
@code{f_lasti}: use @ref{b50,,PyFrame_GetLasti()}.
Code using @code{f_lasti} with @code{PyCode_Addr2Line()} should use
@ref{b6a,,PyFrame_GetLineNumber()} instead; it may be faster.

@item 
@code{f_lineno}: use @ref{b6a,,PyFrame_GetLineNumber()}

@item 
@code{f_locals}: use @ref{84e,,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{b6b,,f_back} member must not be accessed directly,
since its value is now also
computed lazily. The @ref{b65,,PyFrame_GetBack()} function must be called
instead.

Debuggers that accessed the @ref{28d,,f_locals} directly `must' call
@ref{84e,,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{b6c,,PyThreadState} structure members:


@itemize *

@item 
@code{frame}: removed, use @ref{b6d,,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{7da,,strong reference}, need to call
@ref{b6e,,Py_XDECREF()}.

@item 
@code{tracing}: changed, use @ref{b38,,PyThreadState_EnterTracing()}
and @ref{b39,,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{9e6,,PyConfig.module_search_paths_set} field must now be set to 1 for
initialization to use @ref{834,,PyConfig.module_search_paths} to initialize
@ref{194,,sys.path}. Otherwise, initialization will recalculate the path and replace
any values added to @code{module_search_paths}.

@item 
@ref{b6f,,PyConfig_Read()} no longer calculates the initial search path, and will not
fill any values into @ref{834,,PyConfig.module_search_paths}. To calculate default
paths and then modify them, finish initialization and use @ref{356,,PySys_GetObject()}
to retrieve @ref{194,,sys.path} as a Python list object and modify it directly.
@end itemize

@node Deprecated<7>,Pending Removal in Python 3 12<2>,Porting to Python 3 11<2>,C API Changes<3>
@anchor{whatsnew/3 11 id7}@anchor{b70}@anchor{whatsnew/3 11 whatsnew311-c-api-deprecated}@anchor{b02}
@subsubsection Deprecated



@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{60b,,PyConfig} API of the @ref{837,,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{b71,,PyBytesObject}. Use @ref{649,,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>,Removed<7>,Deprecated<7>,C API Changes<3>
@anchor{whatsnew/3 11 id8}@anchor{b72}@anchor{whatsnew/3 11 whatsnew311-c-api-pending-removal}@anchor{b11}
@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{647,,PyUnicode_READY()}

@item 
@code{PyUnicode_WSTR_LENGTH()}

@item 
@code{_PyUnicode_AsUnicode()}

@item 
@code{PyUnicode_WCHAR_KIND}

@item 
@ref{b73,,PyUnicodeObject}

@item 
@code{PyUnicode_InternImmortal()}
@end itemize

@node Removed<7>,,Pending Removal in Python 3 12<2>,C API Changes<3>
@anchor{whatsnew/3 11 id9}@anchor{b74}@anchor{whatsnew/3 11 whatsnew311-c-api-removed}@anchor{b17}
@subsubsection Removed



@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{84d,,Py_LIMITED_API}
is defined:


@itemize *

@item 
@ref{b75,,PyMarshal_WriteLongToFile()}

@item 
@ref{b76,,PyMarshal_WriteObjectToFile()}

@item 
@ref{b77,,PyMarshal_ReadObjectFromString()}

@item 
@ref{b78,,PyMarshal_WriteObjectToString()}

@item 
the @code{Py_MARSHAL_VERSION} macro
@end itemize

These are not part of the @ref{b79,,limited API}.

(Contributed by Victor Stinner in bpo-45474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45474}.)

@item 
Exclude @code{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{9ac}

@itemize *

@item 
Remove the @ref{b7a,,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,C API Changes<3>,What’s New In Python 3 11
@anchor{whatsnew/3 11 notable-changes-in-3-11-4}@anchor{b7b}
@subsection Notable changes in 3.11.4


@menu
* tarfile: tarfile<3>. 

@end menu

@node tarfile<3>,,,Notable changes in 3 11 4
@anchor{whatsnew/3 11 tarfile}@anchor{b7c}
@subsubsection tarfile



@itemize *

@item 
The extraction methods in @ref{e7,,tarfile}, and @ref{882,,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{883,,Extraction filters} for details.
In Python 3.12, use without the `filter' argument will show a
@ref{2c9,,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,What’s New In Python 3 11
@anchor{whatsnew/3 11 notable-changes-in-3-11-5}@anchor{b7d}
@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{b7e}
@subsubsection OpenSSL



@itemize *

@item 
Windows builds and macOS installers from python.org now use OpenSSL 3.0.
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 10,What’s New In Python 3 9,What’s New In Python 3 11,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 10 doc}@anchor{b7f}@anchor{whatsnew/3 10 translation-repo}@anchor{b80}@anchor{whatsnew/3 10 what-s-new-in-python-3-10}@anchor{b81}
@section What’s New In Python 3.10


@*Editor: 
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{145,,changelog}.

@menu
* Summary – Release highlights: Summary – Release highlights<5>. 
* New Features: New Features<7>. 
* New Features Related to Type Hints: New Features Related to Type Hints<3>. 
* Other Language Changes: Other Language Changes<4>. 
* New Modules: New Modules<4>. 
* Improved Modules: Improved Modules<4>. 
* Optimizations: Optimizations<7>. 
* Deprecated: Deprecated<8>. 
* Removed: Removed<8>. 
* Porting to Python 3.10: Porting to Python 3 10. 
* CPython bytecode changes: CPython bytecode changes<4>. 
* Build Changes: Build Changes<4>. 
* C API Changes: C API Changes<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 Summary – Release highlights<5>,New Features<7>,,What’s New In Python 3 10
@anchor{whatsnew/3 10 summary-release-highlights}@anchor{b82}
@subsection Summary – Release highlights


@c This section singles out the most important changes in Python 3.10.
@c Brevity is key.

@c PEP-sized items next.

New syntax features:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/}, Structural Pattern Matching: Specification

@item 
@geindex Python Enhancement Proposals; PEP 635
PEP 635@footnote{https://peps.python.org/pep-0635/}, Structural Pattern Matching: Motivation and Rationale

@item 
@geindex Python Enhancement Proposals; PEP 636
PEP 636@footnote{https://peps.python.org/pep-0636/}, Structural Pattern Matching: Tutorial

@item 
bpo-12782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12782}, Parenthesized context managers are now officially allowed.
@end itemize

New features in the standard library:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 618
PEP 618@footnote{https://peps.python.org/pep-0618/}, Add Optional Length-Checking To zip.
@end itemize

Interpreter improvements:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/}, Precise line numbers for debugging and other tools.
@end itemize

New typing features:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/}, Allow writing union types as X | Y

@item 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/}, Parameter Specification Variables

@item 
@geindex Python Enhancement Proposals; PEP 613
PEP 613@footnote{https://peps.python.org/pep-0613/}, Explicit Type Aliases

@item 
@geindex Python Enhancement Proposals; PEP 647
PEP 647@footnote{https://peps.python.org/pep-0647/}, User-Defined Type Guards
@end itemize

Important deprecations, removals or restrictions:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/}, Require OpenSSL 1.1.1 or newer

@item 
@geindex Python Enhancement Proposals; PEP 632
PEP 632@footnote{https://peps.python.org/pep-0632/}, Deprecate distutils module.

@item 
@geindex Python Enhancement Proposals; PEP 623
PEP 623@footnote{https://peps.python.org/pep-0623/}, Deprecate and prepare for the removal of the wstr member in PyUnicodeObject.

@item 
@geindex Python Enhancement Proposals; PEP 624
PEP 624@footnote{https://peps.python.org/pep-0624/}, Remove Py_UNICODE encoder APIs

@item 
@geindex Python Enhancement Proposals; PEP 597
PEP 597@footnote{https://peps.python.org/pep-0597/}, Add optional EncodingWarning
@end itemize

@node New Features<7>,New Features Related to Type Hints<3>,Summary – Release highlights<5>,What’s New In Python 3 10
@anchor{whatsnew/3 10 new-features}@anchor{b83}
@subsection New Features


@menu
* Parenthesized context managers:: 
* Better error messages:: 
* PEP 626; Precise line numbers for debugging and other tools: PEP 626 Precise line numbers for debugging and other tools. 
* PEP 634; Structural Pattern Matching: PEP 634 Structural Pattern Matching. 
* Optional EncodingWarning and encoding="locale" option:: 

@end menu

@node Parenthesized context managers,Better error messages,,New Features<7>
@anchor{whatsnew/3 10 parenthesized-context-managers}@anchor{b84}@anchor{whatsnew/3 10 whatsnew310-pep563}@anchor{b85}
@subsubsection Parenthesized context managers


Using enclosing parentheses for continuation across multiple lines
in context managers is now supported. This allows formatting a long
collection of context managers in multiple lines in a similar way
as it was previously possible with import statements. For instance,
all these examples are now valid:

@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

it is also possible to use a trailing comma at the end of the
enclosed group:

@example
with (
    CtxManager1() as example1,
    CtxManager2() as example2,
    CtxManager3() as example3,
):
    ...
@end example

This new syntax uses the non LL(1) capacities of the new parser.
Check 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/} for more details.

(Contributed by Guido van Rossum, Pablo Galindo and Lysandros Nikolaou
in bpo-12782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12782} and bpo-40334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40334}.)

@node Better error messages,PEP 626 Precise line numbers for debugging and other tools,Parenthesized context managers,New Features<7>
@anchor{whatsnew/3 10 better-error-messages}@anchor{b86}
@subsubsection Better error messages


@menu
* SyntaxErrors:: 
* IndentationErrors:: 
* AttributeErrors:: 
* NameErrors:: 

@end menu

@node SyntaxErrors,IndentationErrors,,Better error messages
@anchor{whatsnew/3 10 syntaxerrors}@anchor{b87}
@subsubsection SyntaxErrors


When parsing code that contains unclosed parentheses or brackets the interpreter
now includes the location of the unclosed bracket of parentheses instead of displaying
`SyntaxError: unexpected EOF while parsing' or pointing to some incorrect location.
For instance, consider the following code (notice the unclosed “@{“):

@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

Previous versions of the interpreter reported confusing places as the location of
the syntax error:

@example
File "example.py", line 3
    some_other_code = foo()
                    ^
SyntaxError: invalid syntax
@end example

but in Python 3.10 a more informative error is emitted:

@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

In a similar way, errors involving unclosed string literals (single and triple
quoted) now point to the start of the string instead of reporting EOF/EOL.

These improvements are inspired by previous work in the PyPy interpreter.

(Contributed by Pablo Galindo in bpo-42864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42864} and Batuhan Taskaya in
bpo-40176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40176}.)

@ref{17e,,SyntaxError} exceptions raised by the interpreter will now highlight the
full error range of the expression that constitutes the syntax error itself,
instead of just where the problem is detected. In this way, instead of displaying
(before 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

now Python 3.10 will display the exception as:

@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

This improvement was contributed by Pablo Galindo in bpo-43914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43914}.

A considerable amount of new specialized messages for @ref{17e,,SyntaxError} exceptions
have been incorporated. Some of the most notable ones are as follows:


@itemize *

@item 
Missing @code{:} before blocks:

@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 
Unparenthesised tuples in comprehensions targets:

@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 
Missing commas in collection literals and between 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 
Multiple Exception types without parentheses:

@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 
Missing @code{:} and values in dictionary literals:

@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 
@code{try} blocks without @code{except} or @code{finally} blocks:

@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 
Usage of @code{=} instead of @code{==} in comparisons:

@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 
Usage of @code{*} in 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 IndentationErrors,AttributeErrors,SyntaxErrors,Better error messages
@anchor{whatsnew/3 10 indentationerrors}@anchor{b88}
@subsubsection IndentationErrors


Many @ref{b89,,IndentationError} exceptions now have more context regarding what kind of block
was expecting an indentation, including the location of the statement:

@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 AttributeErrors,NameErrors,IndentationErrors,Better error messages
@anchor{whatsnew/3 10 attributeerrors}@anchor{b8a}
@subsubsection AttributeErrors


When printing @ref{1a9,,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

(Contributed by Pablo Galindo in bpo-38530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38530}.)

@cartouche
@quotation Προειδοποίηση 
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 NameErrors,,AttributeErrors,Better error messages
@anchor{whatsnew/3 10 nameerrors}@anchor{b8b}
@subsubsection NameErrors


When printing @ref{665,,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

(Contributed by Pablo Galindo in bpo-38530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38530}.)

@cartouche
@quotation Προειδοποίηση 
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 Precise line numbers for debugging and other tools,PEP 634 Structural Pattern Matching,Better error messages,New Features<7>
@anchor{whatsnew/3 10 pep-626-precise-line-numbers-for-debugging-and-other-tools}@anchor{b8c}
@subsubsection PEP 626: Precise line numbers for debugging and other tools


PEP 626 brings more precise and reliable line numbers for debugging, profiling and coverage tools.
Tracing events, with the correct line number, are generated for all lines of code executed and only for lines of code that are executed.

The @ref{b8d,,f_lineno} attribute of frame objects will always contain the
expected line number.

The @code{codeobject.co_lnotab} attribute of
@ref{6eb,,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{32d,,co_lines()} method instead.

@node PEP 634 Structural Pattern Matching,Optional EncodingWarning and encoding="locale" option,PEP 626 Precise line numbers for debugging and other tools,New Features<7>
@anchor{whatsnew/3 10 pep-634-structural-pattern-matching}@anchor{b8e}
@subsubsection PEP 634: Structural Pattern Matching


Structural pattern matching has been added in the form of a `match statement'
and `case statements' of patterns with associated actions. Patterns
consist of sequences, mappings, primitive data types as well as class instances.
Pattern matching enables programs to extract information from complex data types,
branch on the structure of data, and apply specific actions based on different
forms of data.

@menu
* Syntax and operations:: 
* Declarative approach:: 
* Simple pattern; match to a literal: Simple pattern match to a literal. 
* Patterns with a literal and variable:: 
* Patterns and classes:: 
* Nested patterns:: 
* Complex patterns and the wildcard:: 
* Guard:: 
* Other Key Features:: 

@end menu

@node Syntax and operations,Declarative approach,,PEP 634 Structural Pattern Matching
@anchor{whatsnew/3 10 syntax-and-operations}@anchor{b8f}
@subsubsection Syntax and operations


The generic syntax of pattern matching is:

@example
match subject:
    case <pattern_1>:
        <action_1>
    case <pattern_2>:
        <action_2>
    case <pattern_3>:
        <action_3>
    case _:
        <action_wildcard>
@end example

A match statement takes an expression and compares its value to successive
patterns given as one or more case blocks.  Specifically, pattern matching
operates by:


@enumerate 

@item 
using data with type and shape (the @code{subject})

@item 
evaluating the @code{subject} in the @code{match} statement

@item 
comparing the subject with each pattern in a @code{case} statement
from top to bottom until a match is confirmed.

@item 
executing the action associated with the pattern of the confirmed
match

@item 
If an exact match is not confirmed, the last case, a wildcard @code{_},
if provided, will be used as the matching case. If an exact match is
not confirmed and a wildcard case does not exist, the entire match
block is a no-op.
@end enumerate

@node Declarative approach,Simple pattern match to a literal,Syntax and operations,PEP 634 Structural Pattern Matching
@anchor{whatsnew/3 10 declarative-approach}@anchor{b90}
@subsubsection Declarative approach


Readers may be aware of pattern matching through the simple example of matching
a subject (data object) to a literal (pattern) with the switch statement found
in C, Java or JavaScript (and many other languages). Often the switch statement
is used for comparison of an object/expression with case statements containing
literals.

More powerful examples of pattern matching can be found in languages such as
Scala and Elixir. With structural pattern matching, the approach is «declarative» and
explicitly states the conditions (the patterns) for data to match.

While an «imperative» series of instructions using nested «if» statements
could be used to accomplish something similar to structural pattern matching,
it is less clear than the «declarative» approach. Instead the «declarative»
approach states the conditions to meet for a match and is more readable through
its explicit patterns. While structural pattern matching can be used in its
simplest form comparing a variable to a literal in a case statement, its
true value for Python lies in its handling of the subject’s type and shape.

@node Simple pattern match to a literal,Patterns with a literal and variable,Declarative approach,PEP 634 Structural Pattern Matching
@anchor{whatsnew/3 10 simple-pattern-match-to-a-literal}@anchor{b91}
@subsubsection Simple pattern: match to a literal


Let’s look at this example as pattern matching in its simplest form: a value,
the subject, being matched to several literals, the patterns. In the example
below, @code{status} is the subject of the match statement. The patterns are
each of the case statements, where literals represent request status codes.
The associated action to the case is executed after a match:

@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

If the above function is passed a @code{status} of 418, «I’m a teapot» is returned.
If the above function is passed a @code{status} of 500, the case statement with
@code{_} will match as a wildcard, and «Something’s wrong with the internet» is
returned.
Note the last block: the variable name, @code{_}, acts as a `wildcard' and insures
the subject will always match. The use of @code{_} is optional.

You can combine several literals in a single pattern using @code{|} («or»):

@example
case 401 | 403 | 404:
    return "Not allowed"
@end example

@menu
* Behavior without the wildcard:: 

@end menu

@node Behavior without the wildcard,,,Simple pattern match to a literal
@anchor{whatsnew/3 10 behavior-without-the-wildcard}@anchor{b92}
@subsubsection Behavior without the wildcard


If we modify the above example by removing the last case block, the example
becomes:

@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

Without the use of @code{_} in a case statement, a match may not exist. If no
match exists, the behavior is a no-op. For example, if @code{status} of 500 is
passed, a no-op occurs.

@node Patterns with a literal and variable,Patterns and classes,Simple pattern match to a literal,PEP 634 Structural Pattern Matching
@anchor{whatsnew/3 10 patterns-with-a-literal-and-variable}@anchor{b93}
@subsubsection Patterns with a literal and variable


Patterns can look like unpacking assignments, and a pattern may be used to bind
variables. In this example, a data point can be unpacked to its x-coordinate
and y-coordinate:

@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

The first pattern has two literals, @code{(0, 0)}, and may be thought of as an
extension of the literal pattern shown above. The next two patterns combine a
literal and a variable, and the variable `binds' a value from the subject
(@code{point}).  The fourth pattern captures two values, which makes it
conceptually similar to the unpacking assignment @code{(x, y) = point}.

@node Patterns and classes,Nested patterns,Patterns with a literal and variable,PEP 634 Structural Pattern Matching
@anchor{whatsnew/3 10 patterns-and-classes}@anchor{b94}
@subsubsection Patterns and classes


If you are using classes to structure your data, you can use as a pattern
the class name followed by an argument list resembling a constructor. This
pattern has the ability to capture instance attributes into variables:

@example
class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

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
* Patterns with positional parameters:: 

@end menu

@node Patterns with positional parameters,,,Patterns and classes
@anchor{whatsnew/3 10 patterns-with-positional-parameters}@anchor{b95}
@subsubsection Patterns with positional parameters


You can use positional parameters with some builtin classes that provide an
ordering for their attributes (e.g. dataclasses). You can also define a specific
position for attributes in patterns by setting the @code{__match_args__} special
attribute in your classes. If it’s set to («x», «y»), the following patterns
are all equivalent (and all bind the @code{y} attribute to the @code{var} variable):

@example
Point(1, var)
Point(1, y=var)
Point(x=1, y=var)
Point(y=var, x=1)
@end example

@node Nested patterns,Complex patterns and the wildcard,Patterns and classes,PEP 634 Structural Pattern Matching
@anchor{whatsnew/3 10 nested-patterns}@anchor{b96}
@subsubsection Nested patterns


Patterns can be arbitrarily nested.  For example, if our data is a short
list of points, it could be matched like this:

@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 Complex patterns and the wildcard,Guard,Nested patterns,PEP 634 Structural Pattern Matching
@anchor{whatsnew/3 10 complex-patterns-and-the-wildcard}@anchor{b97}
@subsubsection Complex patterns and the wildcard


To this point, the examples have used @code{_} alone in the last case statement.
A wildcard can be used in more complex patterns, such as @code{('error', code, _)}.
For example:

@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

In the above case, @code{test_variable} will match for (“error”, code, 100) and
(“error”, code, 800).

@node Guard,Other Key Features,Complex patterns and the wildcard,PEP 634 Structural Pattern Matching
@anchor{whatsnew/3 10 guard}@anchor{b98}
@subsubsection Guard


We can add an @code{if} clause to a pattern, known as a «guard».  If the
guard is false, @code{match} goes on to try the next case block.  Note
that value capture happens before the guard is evaluated:

@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 Other Key Features,,Guard,PEP 634 Structural Pattern Matching
@anchor{whatsnew/3 10 other-key-features}@anchor{b99}
@subsubsection Other Key Features


Several other key features:


@itemize -

@item 
Like unpacking assignments, tuple and list patterns have exactly the
same meaning and actually match arbitrary sequences. Technically,
the subject must be a sequence.
Therefore, an important exception is that patterns don’t match iterators.
Also, to prevent a common mistake, sequence patterns don’t match strings.

@item 
Sequence patterns support wildcards: @code{[x, y, *rest]} and @code{(x, y,
*rest)} work similar to wildcards in unpacking assignments.  The
name after @code{*} may also be @code{_}, so @code{(x, y, *_)} matches a sequence
of at least two items without binding the remaining items.

@item 
Mapping patterns: @code{@{"bandwidth": b, "latency": l@}} captures the
@code{"bandwidth"} and @code{"latency"} values from a dict.  Unlike sequence
patterns, extra keys are ignored.  A wildcard @code{**rest} is also
supported.  (But @code{**_} would be redundant, so is not allowed.)

@item 
Subpatterns may be captured using the @code{as} keyword:

@example
case (Point(x1, y1), Point(x2, y2) as p2): ...
@end example

This binds x1, y1, x2, y2 like you would expect without the @code{as} clause,
and p2 to the entire second item of the subject.

@item 
Most literals are compared by equality. However, the singletons @code{True},
@code{False} and @code{None} are compared by identity.

@item 
Named constants may be used in patterns.  These named constants must be
dotted names to prevent the constant from being interpreted as a capture
variable:

@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

For the full specification see 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/}.  Motivation and rationale
are in 
@geindex Python Enhancement Proposals; PEP 635
PEP 635@footnote{https://peps.python.org/pep-0635/}, and a longer tutorial is in 
@geindex Python Enhancement Proposals; PEP 636
PEP 636@footnote{https://peps.python.org/pep-0636/}.

@node Optional EncodingWarning and encoding="locale" option,,PEP 634 Structural Pattern Matching,New Features<7>
@anchor{whatsnew/3 10 optional-encodingwarning-and-encoding-locale-option}@anchor{b9a}@anchor{whatsnew/3 10 whatsnew310-pep597}@anchor{b9b}
@subsubsection Optional @code{EncodingWarning} and @code{encoding="locale"} option


The default encoding of @ref{b9c,,TextIOWrapper} and @ref{32b,,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

To find this type of bug, an optional @code{EncodingWarning} is added.
It is emitted when @ref{a7c,,sys.flags.warn_default_encoding}
is true and locale-specific default encoding is used.

@code{-X warn_default_encoding} option and 
@geindex PYTHONWARNDEFAULTENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNDEFAULTENCODING
@ref{b9d,,PYTHONWARNDEFAULTENCODING}
are added to enable the warning.

See @ref{b9e,,Text Encoding} for more information.

@node New Features Related to Type Hints<3>,Other Language Changes<4>,New Features<7>,What’s New In Python 3 10
@anchor{whatsnew/3 10 new-feat-related-type-hints}@anchor{b9f}@anchor{whatsnew/3 10 new-features-related-to-type-hints}@anchor{ba0}
@subsection New Features Related to Type Hints


This section covers major changes affecting 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} type hints and
the @ref{10d,,typing} module.

@menu
* PEP 604; New Type Union Operator: PEP 604 New Type Union Operator. 
* PEP 612; Parameter Specification Variables: PEP 612 Parameter Specification Variables. 
* PEP 613; TypeAlias: PEP 613 TypeAlias. 
* PEP 647; User-Defined Type Guards: PEP 647 User-Defined Type Guards. 

@end menu

@node PEP 604 New Type Union Operator,PEP 612 Parameter Specification Variables,,New Features Related to Type Hints<3>
@anchor{whatsnew/3 10 pep-604-new-type-union-operator}@anchor{ba1}
@subsubsection PEP 604: New Type Union Operator


A new type union operator was introduced which enables the syntax @code{X | Y}.
This provides a cleaner way of expressing “either type X or type Y” instead of
using @ref{341,,typing.Union}, especially in type hints.

In previous versions of Python, to apply a type hint for functions accepting
arguments of multiple types, @ref{341,,typing.Union} was used:

@example
def square(number: Union[int, float]) -> Union[int, float]:
    return number ** 2
@end example

Type hints can now be written in a more succinct manner:

@example
def square(number: int | float) -> int | float:
    return number ** 2
@end example

This new syntax is also accepted as the second argument to @ref{2ef,,isinstance()}
and @ref{2f0,,issubclass()}:

@example
>>> isinstance(1, int | str)
True
@end example

See @ref{ba2,,Τύπος Ένωσης} and 
@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/} for more details.

(Contributed by Maggie Moss and Philippe Prados in bpo-41428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41428},
with additions by Yurii Karabas and Serhiy Storchaka in bpo-44490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44490}.)

@node PEP 612 Parameter Specification Variables,PEP 613 TypeAlias,PEP 604 New Type Union Operator,New Features Related to Type Hints<3>
@anchor{whatsnew/3 10 pep-612-parameter-specification-variables}@anchor{ba3}
@subsubsection PEP 612: Parameter Specification Variables


Two new options to improve the information provided to static type checkers for
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}“s @code{Callable} have been added to the @ref{10d,,typing} module.

The first is the parameter specification variable.  They are used to forward the
parameter types of one callable to another callable – a pattern commonly
found in higher order functions and decorators.  Examples of usage can be found
in @ref{295,,typing.ParamSpec}. Previously, there was no easy way to type annotate
dependency of parameter types in such a precise manner.

The second option is the new @code{Concatenate} operator. It’s used in conjunction
with parameter specification variables to type annotate a higher order callable
which adds or removes parameters of another callable.  Examples of usage can
be found in @ref{ba4,,typing.Concatenate}.

See @ref{ba5,,typing.Callable}, @ref{295,,typing.ParamSpec},
@ref{ba4,,typing.Concatenate}, @ref{ba6,,typing.ParamSpecArgs},
@ref{ba7,,typing.ParamSpecKwargs}, and 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} for more details.

(Contributed by Ken Jin in bpo-41559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41559}, with minor enhancements by Jelle
Zijlstra in bpo-43783@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43783}.  PEP written by Mark Mendoza.)

@node PEP 613 TypeAlias,PEP 647 User-Defined Type Guards,PEP 612 Parameter Specification Variables,New Features Related to Type Hints<3>
@anchor{whatsnew/3 10 pep-613-typealias}@anchor{ba8}
@subsubsection PEP 613: TypeAlias


@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} introduced the concept of type aliases, only requiring them to be
top-level unannotated assignments. This simplicity sometimes made it difficult
for type checkers to distinguish between type aliases and ordinary assignments,
especially when forward references or invalid types were involved. Compare:

@example
StrCache = 'Cache[str]'  # a type alias
LOG_PREFIX = 'LOG[DEBUG]'  # a module constant
@end example

Now the @ref{10d,,typing} module has a special value @ref{ba9,,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

See 
@geindex Python Enhancement Proposals; PEP 613
PEP 613@footnote{https://peps.python.org/pep-0613/} for more details.

(Contributed by Mikhail Golubev in bpo-41923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41923}.)

@node PEP 647 User-Defined Type Guards,,PEP 613 TypeAlias,New Features Related to Type Hints<3>
@anchor{whatsnew/3 10 pep-647-user-defined-type-guards}@anchor{baa}
@subsubsection PEP 647: User-Defined Type Guards


@ref{698,,TypeGuard} has been added to the @ref{10d,,typing} module to annotate
type guard functions and improve information provided to static type checkers
during type narrowing.  For more information, please see
@code{TypeGuard}“s documentation, and 
@geindex Python Enhancement Proposals; PEP 647
PEP 647@footnote{https://peps.python.org/pep-0647/}.

(Contributed by Ken Jin and Guido van Rossum in bpo-43766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43766}.
PEP written by Eric Traut.)

@node Other Language Changes<4>,New Modules<4>,New Features Related to Type Hints<3>,What’s New In Python 3 10
@anchor{whatsnew/3 10 other-language-changes}@anchor{bab}
@subsection Other Language Changes



@itemize *

@item 
The @ref{326,,int} type has a new method @ref{bac,,int.bit_count()}, returning the
number of ones in the binary expansion of a given integer, also known
as the population count. (Contributed by Niklas Fiekas in bpo-29882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29882}.)

@item 
The views returned by @ref{bad,,dict.keys()}, @ref{bae,,dict.values()} and
@ref{baf,,dict.items()} now all have a @code{mapping} attribute that gives a
@ref{189,,types.MappingProxyType} object wrapping the original
dictionary. (Contributed by Dennis Sweeney in 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/}: The @ref{43f,,zip()} function now has an optional @code{strict} flag, used
to require that all the iterables have an equal length.

@item 
Builtin and extension functions that take integer arguments no longer accept
@ref{1c2,,Decimal}s, @ref{1c3,,Fraction}s and other
objects that can be converted to integers only with a loss (e.g. that have
the @ref{43c,,__int__()} method but do not have the
@ref{43d,,__index__()} method).
(Contributed by Serhiy Storchaka in bpo-37999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37999}.)

@item 
If @ref{bb0,,object.__ipow__()} returns @ref{440,,NotImplemented}, the operator will
correctly fall back to @ref{bb1,,object.__pow__()} and @ref{442,,object.__rpow__()} as expected.
(Contributed by Alex Shkop in bpo-38302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38302}.)

@item 
Assignment expressions can now be used unparenthesized within set literals
and set comprehensions, as well as in sequence indexes (but not slices).

@item 
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__']}. The attribute is initialized from
@code{__globals__["__builtins__"]} if it exists, else from the current builtins.
(Contributed by Mark Shannon in bpo-42990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42990}.)

@item 
Two new builtin functions – @ref{bb2,,aiter()} and @ref{bb3,,anext()} have been added
to provide asynchronous counterparts to @ref{bb4,,iter()} and @ref{bb5,,next()},
respectively.
(Contributed by Joshua Bronson, Daniel Pope, and Justin Wang in bpo-31861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31861}.)

@item 
Static methods (@ref{666,,@@staticmethod}) and class methods
(@ref{69a,,@@classmethod}) now inherit the method attributes
(@code{__module__}, @code{__name__}, @code{__qualname__}, @code{__doc__},
@code{__annotations__}) and have a new @code{__wrapped__} attribute.
Moreover, static methods are now callable as regular functions.
(Contributed by Victor Stinner in bpo-43682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43682}.)

@item 
Annotations for complex targets (everything beside @code{simple name} targets
defined by 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}) no longer cause any runtime effects with @code{from __future__ import annotations}.
(Contributed by Batuhan Taskaya in bpo-42737@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42737}.)

@item 
Class and module objects now lazy-create empty annotations dicts on demand.
The annotations dicts are stored in the object’s @code{__dict__} for
backwards compatibility.  This improves the best practices for working
with @code{__annotations__}; for more information, please see
@ref{bb6,,Annotations Best Practices}.
(Contributed by Larry Hastings in bpo-43901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43901}.)

@item 
Annotations consist of @code{yield}, @code{yield from}, @code{await} or named expressions
are now forbidden under @code{from __future__ import annotations} due to their side
effects.
(Contributed by Batuhan Taskaya in bpo-42725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42725}.)

@item 
Usage of unbound variables, @code{super()} and other expressions that might
alter the processing of symbol table as annotations are now rendered
effectless under @code{from __future__ import annotations}.
(Contributed by Batuhan Taskaya in bpo-42725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42725}.)

@item 
Hashes of NaN values of both @ref{327,,float} type and
@ref{1c2,,decimal.Decimal} type now depend on object identity. Formerly, they
always hashed to @code{0} even though NaN values are not equal to one another.
This caused potentially quadratic runtime behavior due to excessive hash
collisions when creating dictionaries and sets containing multiple NaNs.
(Contributed by Raymond Hettinger in bpo-43475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43475}.)

@item 
A @ref{17e,,SyntaxError} (instead of a @ref{665,,NameError}) will be raised when deleting
the @ref{bb7,,__debug__} constant.  (Contributed by Donghee Na in bpo-45000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45000}.)

@item 
@ref{17e,,SyntaxError} exceptions now have @code{end_lineno} and
@code{end_offset} attributes.  They will be @code{None} if not determined.
(Contributed by Pablo Galindo in bpo-43914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43914}.)
@end itemize

@node New Modules<4>,Improved Modules<4>,Other Language Changes<4>,What’s New In Python 3 10
@anchor{whatsnew/3 10 new-modules}@anchor{bb8}
@subsection New Modules



@itemize *

@item 
None.
@end itemize

@node Improved Modules<4>,Optimizations<7>,New Modules<4>,What’s New In Python 3 10
@anchor{whatsnew/3 10 improved-modules}@anchor{bb9}
@subsection Improved Modules


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

@end menu

@node asyncio<8>,argparse<5>,,Improved Modules<4>
@anchor{whatsnew/3 10 asyncio}@anchor{bba}
@subsubsection asyncio


Add missing @ref{bbb,,connect_accepted_socket()}
method.
(Contributed by Alex Grönholm in bpo-41332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41332}.)

@node argparse<5>,array<4>,asyncio<8>,Improved Modules<4>
@anchor{whatsnew/3 10 argparse}@anchor{bbc}
@subsubsection argparse


Misleading phrase «optional arguments» was replaced with «options» in argparse help. Some tests might require adaptation if they rely on exact output match.
(Contributed by Raymond Hettinger in bpo-9694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9694}.)

@node array<4>,asynchat asyncore smtpd,argparse<5>,Improved Modules<4>
@anchor{whatsnew/3 10 array}@anchor{bbd}
@subsubsection array


The @ref{bbe,,index()} method of @ref{6c5,,array.array} now has
optional `start' and `stop' parameters.
(Contributed by Anders Lorentsen and Zackery Spytz in bpo-31956@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31956}.)

@node asynchat asyncore smtpd,base64<4>,array<4>,Improved Modules<4>
@anchor{whatsnew/3 10 asynchat-asyncore-smtpd}@anchor{bbf}
@subsubsection asynchat, asyncore, smtpd


These modules have been marked as deprecated in their module documentation
since Python 3.6.  An import-time @ref{2c9,,DeprecationWarning} has now been
added to all three of these modules.

@node base64<4>,bdb<2>,asynchat asyncore smtpd,Improved Modules<4>
@anchor{whatsnew/3 10 base64}@anchor{bc0}
@subsubsection base64


Add @ref{1e9,,base64.b32hexencode()} and @ref{1ea,,base64.b32hexdecode()} to support the
Base32 Encoding with Extended Hex Alphabet.

@node bdb<2>,bisect,base64<4>,Improved Modules<4>
@anchor{whatsnew/3 10 bdb}@anchor{bc1}
@subsubsection bdb


Add @code{clearBreakpoints()} to reset all set breakpoints.
(Contributed by Irit Katriel in bpo-24160@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24160}.)

@node bisect,codecs,bdb<2>,Improved Modules<4>
@anchor{whatsnew/3 10 bisect}@anchor{bc2}
@subsubsection bisect


Added the possibility of providing a `key' function to the APIs in the @ref{12,,bisect}
module. (Contributed by Raymond Hettinger in bpo-4356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4356}.)

@node codecs,collections abc<2>,bisect,Improved Modules<4>
@anchor{whatsnew/3 10 codecs}@anchor{bc3}
@subsubsection codecs


Add a @ref{bc4,,codecs.unregister()} function to unregister a codec search function.
(Contributed by Hai Shi in bpo-41842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41842}.)

@node collections abc<2>,contextlib<3>,codecs,Improved Modules<4>
@anchor{whatsnew/3 10 collections-abc}@anchor{bc5}
@subsubsection collections.abc


The @code{__args__} of the @ref{a9f,,parameterized generic} for
@ref{bc6,,collections.abc.Callable} are now consistent with @ref{ba5,,typing.Callable}.
@code{collections.abc.Callable} generic now flattens type parameters, similar
to what @code{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{bc7,,types.GenericAlias} can now be subclassed, and a subclass will
be returned when subscripting the @code{collections.abc.Callable} type.  Note
that a @ref{291,,TypeError} may be raised for invalid forms of parameterizing
@code{collections.abc.Callable} which may have passed silently in Python 3.9.
(Contributed by Ken Jin in bpo-42195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42195}.)

@node contextlib<3>,curses<2>,collections abc<2>,Improved Modules<4>
@anchor{whatsnew/3 10 contextlib}@anchor{bc8}
@subsubsection contextlib


Add a @ref{bc9,,contextlib.aclosing()} context manager to safely close async generators
and objects representing asynchronously released resources.
(Contributed by Joongi Kim and John Belmonte in bpo-41229@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41229}.)

Add asynchronous context manager support to @ref{bca,,contextlib.nullcontext()}.
(Contributed by Tom Gringauz in bpo-41543@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41543}.)

Add @ref{20d,,AsyncContextDecorator}, for supporting usage of async
context managers as decorators.

@node curses<2>,dataclasses<3>,contextlib<3>,Improved Modules<4>
@anchor{whatsnew/3 10 curses}@anchor{bcb}
@subsubsection curses


The extended color functions added in ncurses 6.1 will be used transparently
by @ref{bcc,,curses.color_content()}, @ref{bcd,,curses.init_color()},
@ref{bce,,curses.init_pair()}, and @ref{bcf,,curses.pair_content()}. A new function,
@ref{bd0,,curses.has_extended_color_support()}, indicates whether extended color
support is provided by the underlying ncurses library.
(Contributed by Jeffrey Kintscher and Hans Petter Jansson in bpo-36982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36982}.)

The @code{BUTTON5_*} constants are now exposed in the @ref{2e,,curses} module if
they are provided by the underlying curses library.
(Contributed by Zackery Spytz in bpo-39273@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39273}.)

@node dataclasses<3>,distutils<2>,curses<2>,Improved Modules<4>
@anchor{whatsnew/3 10 dataclasses}@anchor{bd1}
@subsubsection dataclasses


@menu
* __slots__:: 
* Keyword-only fields:: 

@end menu

@node __slots__,Keyword-only fields,,dataclasses<3>
@anchor{whatsnew/3 10 slots}@anchor{bd2}
@subsubsection __slots__


Added @code{slots} parameter in @ref{6e6,,dataclasses.dataclass()} decorator.
(Contributed by Yurii Karabas in bpo-42269@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42269})

@node Keyword-only fields,,__slots__,dataclasses<3>
@anchor{whatsnew/3 10 keyword-only-fields}@anchor{bd3}
@subsubsection Keyword-only fields


dataclasses now supports fields that are keyword-only in the
generated __init__ method.  There are a number of ways of specifying
keyword-only fields.

You can say that every field is keyword-only:

@example
from dataclasses import dataclass

@@dataclass(kw_only=True)
class Birthday:
    name: str
    birthday: datetime.date
@end example

Both @code{name} and @code{birthday} are keyword-only parameters to the
generated __init__ method.

You can specify keyword-only on a per-field basis:

@example
from dataclasses import dataclass, field

@@dataclass
class Birthday:
    name: str
    birthday: datetime.date = field(kw_only=True)
@end example

Here only @code{birthday} is keyword-only.  If you set @code{kw_only} on
individual fields, be aware that there are rules about re-ordering
fields due to keyword-only fields needing to follow non-keyword-only
fields.  See the full dataclasses documentation for details.

You can also specify that all fields following a KW_ONLY marker are
keyword-only.  This will probably be the most common usage:

@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<3>,Improved Modules<4>
@anchor{whatsnew/3 10 distutils}@anchor{bd4}@anchor{whatsnew/3 10 distutils-deprecated}@anchor{b12}
@subsubsection distutils


The entire @code{distutils} package is deprecated, to be removed in Python
3.12. Its functionality for specifying package builds has already been
completely replaced by third-party packages @code{setuptools} and
@code{packaging}, and most other commonly used APIs are available elsewhere
in the standard library (such as @ref{af,,platform}, @ref{cd,,shutil},
@ref{df,,subprocess} or @ref{e4,,sysconfig}). There are no plans to migrate
any other functionality from @code{distutils}, and applications that are
using other functions should plan to make private copies of the code.
Refer to 
@geindex Python Enhancement Proposals; PEP 632
PEP 632@footnote{https://peps.python.org/pep-0632/} for discussion.

The @code{bdist_wininst} command deprecated in Python 3.8 has been removed.
The @code{bdist_wheel} command is now recommended to distribute binary packages
on Windows.
(Contributed by Victor Stinner in bpo-42802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42802}.)

@node doctest<2>,encodings,distutils<2>,Improved Modules<4>
@anchor{whatsnew/3 10 doctest}@anchor{bd5}
@subsubsection doctest


When a module does not define @code{__loader__}, fall back to @code{__spec__.loader}.
(Contributed by Brett Cannon in bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133}.)

@node encodings,enum<4>,doctest<2>,Improved Modules<4>
@anchor{whatsnew/3 10 encodings}@anchor{bd6}
@subsubsection encodings


@ref{313,,encodings.normalize_encoding()} now ignores non-ASCII characters.
(Contributed by Hai Shi in bpo-39337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39337}.)

@node enum<4>,fileinput,encodings,Improved Modules<4>
@anchor{whatsnew/3 10 enum}@anchor{bd7}
@subsubsection enum


@ref{a21,,Enum} @ref{1bc,,__repr__()} now returns @code{enum_name.member_name} and
@ref{a0f,,__str__()} now returns @code{member_name}.  Stdlib enums available as
module constants have a @ref{45b,,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{a0d,,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<3>,enum<4>,Improved Modules<4>
@anchor{whatsnew/3 10 fileinput}@anchor{bd8}
@subsubsection fileinput


Add `encoding' and `errors' parameters in @ref{bd9,,fileinput.input()} and
@ref{b1e,,fileinput.FileInput}.
(Contributed by Inada Naoki in bpo-43712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43712}.)

@ref{bda,,fileinput.hook_compressed()} now returns @ref{b9c,,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<3>,gc<4>,fileinput,Improved Modules<4>
@anchor{whatsnew/3 10 faulthandler}
@subsubsection faulthandler


The @ref{5b,,faulthandler} module now detects if a fatal error occurs during a
garbage collector collection.
(Contributed by Victor Stinner in bpo-44466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44466}.)

@node gc<4>,glob<3>,faulthandler<3>,Improved Modules<4>
@anchor{whatsnew/3 10 gc}@anchor{bdc}
@subsubsection gc


Add audit hooks for @ref{bdd,,gc.get_objects()}, @ref{bde,,gc.get_referrers()} and
@ref{bdf,,gc.get_referents()}. (Contributed by Pablo Galindo in bpo-43439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43439}.)

@node glob<3>,hashlib<4>,gc<4>,Improved Modules<4>
@anchor{whatsnew/3 10 glob}@anchor{be0}
@subsubsection glob


Add the `root_dir' and `dir_fd' parameters in @ref{2d4,,glob()} and
@ref{be1,,iglob()} which allow to specify the root directory for searching.
(Contributed by Serhiy Storchaka in bpo-38144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38144}.)

@node hashlib<4>,hmac<2>,glob<3>,Improved Modules<4>
@anchor{whatsnew/3 10 hashlib}@anchor{be2}
@subsubsection hashlib


The hashlib module requires OpenSSL 1.1.1 or newer.
(Contributed by Christian Heimes in 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/} and bpo-43669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43669}.)

The hashlib module has preliminary support for OpenSSL 3.0.0.
(Contributed by Christian Heimes in bpo-38820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38820} and other issues.)

The pure-Python fallback of @ref{91e,,pbkdf2_hmac()} is deprecated. In
the future PBKDF2-HMAC will only be available when Python has been built with
OpenSSL support.
(Contributed by Christian Heimes in bpo-43880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43880}.)

@node hmac<2>,IDLE and idlelib<2>,hashlib<4>,Improved Modules<4>
@anchor{whatsnew/3 10 hmac}@anchor{be3}
@subsubsection hmac


The hmac module now uses OpenSSL’s HMAC implementation internally.
(Contributed by Christian Heimes in bpo-40645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40645}.)

@node IDLE and idlelib<2>,importlib metadata<2>,hmac<2>,Improved Modules<4>
@anchor{whatsnew/3 10 idle-and-idlelib}@anchor{be4}
@subsubsection IDLE and idlelib


Make IDLE invoke @ref{be5,,sys.excepthook()} (when started without “-n”).
User hooks were previously ignored.  (Contributed by Ken Hilton in
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}.)

The changes above were backported to a 3.9 maintenance release.

Add a Shell sidebar.  Move the primary prompt (“>>>”) to the sidebar.
Add secondary prompts (”…”) to the sidebar.  Left click and optional
drag selects one or more lines of text, as with the editor
line number sidebar.  Right click after selecting text lines displays
a context menu with “copy with prompts”.  This zips together prompts
from the sidebar with lines from the selected text.  This option also
appears on the context menu for the text.  (Contributed by Tal Einat
in bpo-37903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37903}.)

Use spaces instead of tabs to indent interactive code.  This makes
interactive code entries “look right”.  Making this feasible was a
major motivation for adding the shell sidebar.  (Contributed by
Terry Jan Reedy in bpo-37892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37892}.)

Highlight the new @ref{be6,,soft keywords} @ref{1d4,,match},
@code{case}, and @ref{be7,,_} 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.  (Contributed by Tal Einat in bpo-44010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44010}.)

New in 3.10 maintenance releases.

Apply syntax highlighting to @code{.pyi} files. (Contributed by Alex
Waygood and Terry Jan Reedy in 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<5>,IDLE and idlelib<2>,Improved Modules<4>
@anchor{whatsnew/3 10 importlib-metadata}@anchor{be8}
@subsubsection importlib.metadata


Feature parity with @code{importlib_metadata} 4.6
(history@footnote{https://importlib-metadata.readthedocs.io/en/latest/history.html}).

@ref{788,,importlib.metadata entry points}
now provide a nicer experience
for selecting entry points by group and name through a new
@ref{788,,importlib.metadata.EntryPoints} class. See the Compatibility
Note in the docs for more info on the deprecation and usage.

Added @ref{be9,,importlib.metadata.packages_distributions()}
for resolving top-level Python modules and packages to their
@ref{bea,,importlib.metadata.Distribution}.

@node inspect<5>,itertools<4>,importlib metadata<2>,Improved Modules<4>
@anchor{whatsnew/3 10 inspect}@anchor{beb}
@subsubsection inspect


When a module does not define @code{__loader__}, fall back to @code{__spec__.loader}.
(Contributed by Brett Cannon in bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133}.)

Add @ref{bec,,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. @code{inspect.get_annotations()} can also correctly un-stringize
stringized annotations.  @code{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{bb6,,Annotations Best Practices}.
Relatedly, @ref{4bd,,inspect.signature()},
@ref{b20,,inspect.Signature.from_callable()}, and @code{inspect.Signature.from_function()}
now call @code{inspect.get_annotations()} to retrieve annotations. This means
@code{inspect.signature()} and @code{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<4>,linecache<2>,inspect<5>,Improved Modules<4>
@anchor{whatsnew/3 10 itertools}@anchor{bed}
@subsubsection itertools


Add @ref{bee,,itertools.pairwise()}.
(Contributed by Raymond Hettinger in bpo-38200@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38200}.)

@node linecache<2>,os<6>,itertools<4>,Improved Modules<4>
@anchor{whatsnew/3 10 linecache}@anchor{bef}
@subsubsection linecache


When a module does not define @code{__loader__}, fall back to @code{__spec__.loader}.
(Contributed by Brett Cannon in bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133}.)

@node os<6>,os path<5>,linecache<2>,Improved Modules<4>
@anchor{whatsnew/3 10 os}@anchor{bf0}
@subsubsection os


Add @ref{6e1,,os.cpu_count()} support for VxWorks RTOS.
(Contributed by Peixing Xin in bpo-41440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41440}.)

Add a new function @ref{bf1,,os.eventfd()} and related helpers to wrap the
@code{eventfd2} syscall on Linux.
(Contributed by Christian Heimes in bpo-41001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41001}.)

Add @ref{bf2,,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{bf3,,O_EVTONLY}, @ref{bf4,,O_FSYNC}, @ref{bf5,,O_SYMLINK}
and @ref{bf6,,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<5>,pathlib<9>,os<6>,Improved Modules<4>
@anchor{whatsnew/3 10 os-path}@anchor{bf7}
@subsubsection os.path


@ref{241,,os.path.realpath()} now accepts a `strict' keyword-only argument. When set
to @code{True}, @ref{53c,,OSError} is raised if a path doesn’t exist or a symlink loop
is encountered.
(Contributed by Barney Gale in bpo-43757@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43757}.)

@node pathlib<9>,platform<4>,os path<5>,Improved Modules<4>
@anchor{whatsnew/3 10 pathlib}@anchor{bf8}
@subsubsection pathlib


Add slice support to @ref{bf9,,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{bf9,,PurePath.parents}.
(Contributed by Yaroslav Pankovych in bpo-21041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21041}.)

Add @ref{bfa,,Path.hardlink_to} method that
supersedes @code{link_to()}. The new method has the same argument
order as @ref{bfb,,symlink_to()}.
(Contributed by Barney Gale in bpo-39950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39950}.)

@ref{bfc,,pathlib.Path.stat()} and @ref{bfd,,chmod()} now accept a
`follow_symlinks' keyword-only argument for consistency with corresponding
functions in the @ref{a5,,os} module.
(Contributed by Barney Gale in bpo-39906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39906}.)

@node platform<4>,pprint<2>,pathlib<9>,Improved Modules<4>
@anchor{whatsnew/3 10 platform}@anchor{bfe}
@subsubsection platform


Add @ref{bff,,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<2>,py_compile,platform<4>,Improved Modules<4>
@anchor{whatsnew/3 10 pprint}@anchor{c00}
@subsubsection pprint


@ref{c01,,pprint.pprint()} now accepts a new @code{underscore_numbers} keyword argument.
(Contributed by sblondon in bpo-42914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42914}.)

@ref{b3,,pprint} can now pretty-print @ref{6e6,,dataclasses.dataclass} instances.
(Contributed by Lewis Gaul in bpo-43080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43080}.)

@node py_compile,pyclbr,pprint<2>,Improved Modules<4>
@anchor{whatsnew/3 10 py-compile}@anchor{c02}
@subsubsection py_compile


Add @code{--quiet} option to command-line interface of @ref{bb,,py_compile}.
(Contributed by Gregory Schevchenko in bpo-38731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38731}.)

@node pyclbr,shelve<2>,py_compile,Improved Modules<4>
@anchor{whatsnew/3 10 pyclbr}@anchor{c03}
@subsubsection pyclbr


Add an @code{end_lineno} attribute to the @code{Function} and @code{Class}
objects in the tree returned by @ref{c04,,pyclbr.readmodule()} and
@ref{c05,,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<2>,statistics<3>,pyclbr,Improved Modules<4>
@anchor{whatsnew/3 10 shelve}@anchor{c06}
@subsubsection shelve


The @ref{cb,,shelve} module now uses @ref{c07,,pickle.DEFAULT_PROTOCOL} by default
instead of @ref{ab,,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<2>,Improved Modules<4>
@anchor{whatsnew/3 10 statistics}@anchor{c08}
@subsubsection statistics


Add @ref{c09,,covariance()}, Pearson’s
@ref{8cc,,correlation()}, and simple
@ref{c0a,,linear_regression()} functions.
(Contributed by Tymoteusz Wołodźko in bpo-38490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38490}.)

@node site<2>,socket<4>,statistics<3>,Improved Modules<4>
@anchor{whatsnew/3 10 site}@anchor{c0b}
@subsubsection site


When a module does not define @code{__loader__}, fall back to @code{__spec__.loader}.
(Contributed by Brett Cannon in bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133}.)

@node socket<4>,ssl<5>,site<2>,Improved Modules<4>
@anchor{whatsnew/3 10 socket}@anchor{c0c}
@subsubsection socket


The exception @ref{c0d,,socket.timeout} is now an alias of @ref{c0e,,TimeoutError}.
(Contributed by Christian Heimes in bpo-42413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42413}.)

Add option to create MPTCP sockets with @code{IPPROTO_MPTCP}
(Contributed by Rui Cunha in bpo-43571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43571}.)

Add @code{IP_RECVTOS} option to receive the type of service (ToS) or DSCP/ECN fields
(Contributed by Georg Sauthoff in bpo-44077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44077}.)

@node ssl<5>,sqlite3<7>,socket<4>,Improved Modules<4>
@anchor{whatsnew/3 10 ssl}@anchor{c0f}
@subsubsection ssl


The ssl module requires OpenSSL 1.1.1 or newer.
(Contributed by Christian Heimes in 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/} and 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{c10,,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}.)

Deprecated function and use of deprecated constants now result in
a @ref{2c9,,DeprecationWarning}. @ref{c11,,ssl.SSLContext.options} has
@ref{c12,,OP_NO_SSLv2} and @ref{c13,,OP_NO_SSLv3} set by default and
therefore cannot warn about setting the flag again. The
@ref{c14,,deprecation section} has a list of deprecated
features.
(Contributed by Christian Heimes in bpo-43880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43880}.)

The ssl module now has more secure default settings. Ciphers without forward
secrecy or 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{336,,SSLContext} defaults to minimum protocol version TLS 1.2.
Settings are based on Hynek Schlawack’s research.
(Contributed by Christian Heimes in bpo-43998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43998}.)

The deprecated protocols SSL 3.0, TLS 1.0, and TLS 1.1 are no longer
officially supported. Python does not block them actively. However
OpenSSL build options, distro configurations, vendor patches, and cipher
suites may prevent a successful handshake.

Add a `timeout' parameter to the @ref{c15,,ssl.get_server_certificate()} function.
(Contributed by Zackery Spytz in bpo-31870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31870}.)

The ssl module uses heap-types and multi-phase initialization.
(Contributed by Christian Heimes in bpo-42333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42333}.)

A new verify flag @ref{68f,,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<7>,sys<6>,ssl<5>,Improved Modules<4>
@anchor{whatsnew/3 10 sqlite3}@anchor{c16}
@subsubsection sqlite3


Add audit events for @ref{3e0,,connect()},
@ref{c17,,enable_load_extension()}, and
@ref{8c8,,load_extension()}.
(Contributed by Erlend E. Aasland in bpo-43762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43762}.)

@node sys<6>,_thread,sqlite3<7>,Improved Modules<4>
@anchor{whatsnew/3 10 sys}@anchor{c18}
@subsubsection sys


Add @ref{c19,,sys.orig_argv} attribute: the list of the original command line
arguments passed to the Python executable.
(Contributed by Victor Stinner in bpo-23427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23427}.)

Add @ref{c1a,,sys.stdlib_module_names}, containing the list of the standard library
module names.
(Contributed by Victor Stinner in bpo-42955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42955}.)

@node _thread,threading<6>,sys<6>,Improved Modules<4>
@anchor{whatsnew/3 10 thread}@anchor{c1b}
@subsubsection _thread


@ref{c1c,,_thread.interrupt_main()} now takes an optional signal number to
simulate (the default is still @ref{4df,,signal.SIGINT}).
(Contributed by Antoine Pitrou in bpo-43356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43356}.)

@node threading<6>,traceback<3>,_thread,Improved Modules<4>
@anchor{whatsnew/3 10 threading}@anchor{c1d}
@subsubsection threading


Add @ref{c1e,,threading.gettrace()} and @ref{c1f,,threading.getprofile()} to
retrieve the functions set by @ref{c20,,threading.settrace()} and
@ref{c21,,threading.setprofile()} respectively.
(Contributed by Mario Corchero in bpo-42251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42251}.)

Add @ref{c22,,threading.__excepthook__} to allow retrieving the original value
of @ref{c23,,threading.excepthook()} in case it is set to a broken or a different
value.
(Contributed by Mario Corchero in bpo-42308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42308}.)

@node traceback<3>,types<6>,threading<6>,Improved Modules<4>
@anchor{whatsnew/3 10 traceback}@anchor{c24}
@subsubsection traceback


The @ref{c25,,format_exception()},
@ref{c26,,format_exception_only()}, and
@ref{c27,,print_exception()} functions can now take an exception object
as a positional-only argument.
(Contributed by Zackery Spytz and Matthias Bussonnier in bpo-26389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26389}.)

@node types<6>,typing<8>,traceback<3>,Improved Modules<4>
@anchor{whatsnew/3 10 types}@anchor{c28}
@subsubsection types


Reintroduce the @ref{c29,,types.EllipsisType}, @ref{c2a,,types.NoneType}
and @ref{c2b,,types.NotImplementedType} classes, providing a new set
of types readily interpretable by type checkers.
(Contributed by Bas van Beek in bpo-41810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41810}.)

@node typing<8>,unittest<7>,types<6>,Improved Modules<4>
@anchor{whatsnew/3 10 typing}@anchor{c2c}
@subsubsection typing


For major changes, see @ref{b9f,,New Features Related to Type Hints}.

The behavior of @ref{c2d,,typing.Literal} was changed to conform with 
@geindex Python Enhancement Proposals; PEP 586
PEP 586@footnote{https://peps.python.org/pep-0586/}
and to match the behavior of static type checkers specified in the PEP.


@enumerate 

@item 
@code{Literal} now de-duplicates parameters.

@item 
Equality comparisons between @code{Literal} objects are now order independent.

@item 
@code{Literal} comparisons now respect types.  For example,
@code{Literal[0] == Literal[False]} previously evaluated to @code{True}.  It is
now @code{False}.  To support this change, the internally used type cache now
supports differentiating types.

@item 
@code{Literal} objects will now raise a @ref{291,,TypeError} exception during
equality comparisons if any of their parameters are not @ref{183,,hashable}.
Note that declaring @code{Literal} with unhashable parameters will not throw
an error:

@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

(Contributed by Yurii Karabas in bpo-42345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42345}.)

Add new function @ref{c2e,,typing.is_typeddict()} to introspect if an annotation
is a @ref{290,,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{861,,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{2c9,,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{10d,,typing} instead.
(Contributed by Sebastian Rittau in bpo-38291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38291}.)

@node unittest<7>,urllib parse<2>,typing<8>,Improved Modules<4>
@anchor{whatsnew/3 10 unittest}@anchor{c2f}
@subsubsection unittest


Add new method @ref{c30,,assertNoLogs()} to complement the
existing @ref{29f,,assertLogs()}. (Contributed by Kit Yan Choi
in bpo-39385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39385}.)

@node urllib parse<2>,xml<3>,unittest<7>,Improved Modules<4>
@anchor{whatsnew/3 10 urllib-parse}@anchor{c31}
@subsubsection urllib.parse


Python versions earlier than Python 3.10 allowed using both @code{;} and @code{&} as
query parameter separators in @ref{589,,urllib.parse.parse_qs()} and
@ref{588,,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{113,,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<3>,zipimport<4>,urllib parse<2>,Improved Modules<4>
@anchor{whatsnew/3 10 xml}@anchor{c32}
@subsubsection xml


Add a @ref{c33,,LexicalHandler} class to the
@ref{133,,xml.sax.handler} module.
(Contributed by Jonathan Gossage and Zackery Spytz in bpo-35018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35018}.)

@node zipimport<4>,,xml<3>,Improved Modules<4>
@anchor{whatsnew/3 10 zipimport}@anchor{c34}
@subsubsection zipimport


Add methods related to 
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/}: @ref{c35,,find_spec()},
@ref{c36,,zipimport.zipimporter.create_module()}, and
@ref{2e9,,zipimport.zipimporter.exec_module()}.
(Contributed by Brett Cannon in bpo-42131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42131}.)

Add @ref{c37,,invalidate_caches()} method.
(Contributed by Desmond Cheong in bpo-14678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14678}.)

@node Optimizations<7>,Deprecated<8>,Improved Modules<4>,What’s New In Python 3 10
@anchor{whatsnew/3 10 optimizations}@anchor{c38}
@subsection Optimizations



@itemize *

@item 
Constructors @ref{1df,,str()}, @ref{1c7,,bytes()} and @ref{1c6,,bytearray()} are now faster
(around 30–40% for small objects).
(Contributed by Serhiy Storchaka in bpo-41334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41334}.)

@item 
The @ref{c6,,runpy} module now imports fewer modules.
The @code{python3 -m module-name} command startup time is 1.4x faster in
average. On Linux, @code{python3 -I -m module-name} imports 69 modules on Python
3.9, whereas it only imports 51 modules (-18) on Python 3.10.
(Contributed by Victor Stinner in bpo-41006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41006} and bpo-41718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41718}.)

@item 
The @code{LOAD_ATTR} instruction now uses new «per opcode cache» mechanism.  It
is about 36% faster now for regular attributes and 44% faster for slots.
(Contributed by Pablo Galindo and Yury Selivanov in bpo-42093@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42093} and Guido
van Rossum in bpo-42927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42927}, based on ideas implemented originally in PyPy
and MicroPython.)

@item 
When building Python with @ref{c39,,--enable-optimizations} now
@code{-fno-semantic-interposition} is added to both the compile and link line.
This speeds builds of the Python interpreter created with @ref{c3a,,--enable-shared}
with @code{gcc} by up to 30%. See this article@footnote{https://developers.redhat.com/blog/2020/06/25/red-hat-enterprise-linux-8-2-brings-faster-python-3-8-run-speeds/}
for more details. (Contributed by Victor Stinner and Pablo Galindo in
bpo-38980@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38980}.)

@item 
Use a new output buffer management code for @ref{14,,bz2} / @ref{8d,,lzma} /
@ref{13c,,zlib} modules, and add @code{.readall()} function to
@code{_compression.DecompressReader} class. bz2 decompression is now 1.09x ~ 1.17x
faster, lzma decompression 1.20x ~ 1.32x faster, @code{GzipFile.read(-1)} 1.11x
~ 1.18x faster. (Contributed by Ma Lin, reviewed by Gregory P. Smith, in 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 
Substring search functions such as @code{str1 in str2} and @code{str2.find(str1)}
now sometimes use Crochemore & Perrin’s «Two-Way» string searching
algorithm to avoid quadratic behavior on long strings.  (Contributed
by Dennis Sweeney in 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{43e,,map()}, @ref{c3b,,filter()}, @ref{c3c,,reversed()}, @ref{5ef,,bool()} and @ref{327,,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{c3d,,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{6a,,gzip} and
@ref{8d,,lzma} have always been.  (Contributed by Inada Naoki in bpo-43785@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43785}.)
@end itemize

@node Deprecated<8>,Removed<8>,Optimizations<7>,What’s New In Python 3 10
@anchor{whatsnew/3 10 deprecated}@anchor{c3e}@anchor{whatsnew/3 10 whatsnew310-deprecated}@anchor{c14}
@subsection Deprecated



@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{31f,,and}, @ref{320,,else},
@ref{321,,for}, @ref{322,,if}, @ref{323,,in}, @ref{324,,is} and @ref{325,,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{c3f,,find_spec()}),
@code{importlib.abc.Loader.load_module}
(superseded by @ref{c40,,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{7a,,importlib}).
@ref{907,,ImportWarning} and/or @ref{2c9,,DeprecationWarning} will be raised
as appropriate to help identify code which needs updating during
this transition.

@item 
The entire @code{distutils} namespace is deprecated, to be removed in
Python 3.12. Refer to the @ref{b12,,module changes}
section for more information.

@item 
Non-integer arguments to @ref{c41,,random.randrange()} are deprecated.
The @ref{277,,ValueError} is deprecated in favor of a @ref{291,,TypeError}.
(Contributed by Serhiy Storchaka and Raymond Hettinger in bpo-37319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37319}.)

@item 
The various @code{load_module()} methods of @ref{7a,,importlib} have been
documented as deprecated since Python 3.6, but will now also trigger
a @ref{2c9,,DeprecationWarning}. Use
@ref{c40,,exec_module()} instead.
(Contributed by Brett Cannon in 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{2e9,,exec_module()}.
(Contributed by Brett Cannon in bpo-26131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26131}.)

@item 
The use of @code{importlib.abc.Loader.load_module} by the import
system now triggers an @ref{907,,ImportWarning} as
@ref{c40,,exec_module()} is preferred.
(Contributed by Brett Cannon in 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{907,,ImportWarning} as
@ref{c3f,,importlib.abc.MetaPathFinder.find_spec()} and
@ref{c42,,importlib.abc.PathEntryFinder.find_spec()}
are preferred, respectively. You can use
@ref{c43,,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{907,,ImportWarning} as
@ref{c42,,importlib.abc.PathEntryFinder.find_spec()} is preferred. You can use
@ref{c43,,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{2c9,,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{c44,,importlib.abc.MetaPathFinder} and @ref{c45,,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{2c9,,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} has been undocumented and obsolete since Python
3.3, when it was made an alias to @ref{1df,,str}.  It is now deprecated,
scheduled for removal in Python 3.12.
(Contributed by Erlend E. Aasland in bpo-42264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42264}.)

@item 
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.  See the SQLite3 docs@footnote{https://sqlite.org/c3ref/enable_shared_cache.html} for more details.
If a shared cache must be used, open the database in URI mode using the
@code{cache=shared} query parameter.
(Contributed by Erlend E. Aasland in bpo-24464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24464}.)

@item 
The following @code{threading} methods are now deprecated:


@itemize *

@item 
@code{threading.currentThread} => @ref{33e,,threading.current_thread()}

@item 
@code{threading.activeCount} => @ref{33f,,threading.active_count()}

@item 
@code{threading.Condition.notifyAll} =>
@ref{338,,threading.Condition.notify_all()}

@item 
@code{threading.Event.isSet} => @ref{339,,threading.Event.is_set()}

@item 
@code{threading.Thread.setName} => @ref{33d,,threading.Thread.name}

@item 
@code{threading.thread.getName} => @ref{33d,,threading.Thread.name}

@item 
@code{threading.Thread.isDaemon} => @ref{33b,,threading.Thread.daemon}

@item 
@code{threading.Thread.setDaemon} => @ref{33b,,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{bfa,,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()} is deprecated and slated for removal in Python 3.12.
(Contributed by Inada Naoki in bpo-41139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41139}.)

@item 
The following @ref{d8,,ssl} features have been deprecated since Python 3.6,
Python 3.7, or OpenSSL 1.1.0 and will be removed in 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{c46,,minimum_version} and
@ref{c47,,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{c48,,PROTOCOL_TLS_CLIENT} and @ref{c49,,PROTOCOL_TLS_SERVER}

@item 
@code{wrap_socket()} is replaced by @ref{933,,ssl.SSLContext.wrap_socket()}

@item 
@code{match_hostname()}

@item 
@code{RAND_pseudo_bytes()}, @code{RAND_egd()}

@item 
NPN features like @ref{c4a,,ssl.SSLSocket.selected_npn_protocol()} and
@ref{337,,ssl.SSLContext.set_npn_protocols()} are replaced by ALPN.
@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{3dc,,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{2c9,,DeprecationWarning}.  These submodules will be removed in a future version
of Python.  Anything belonging to these submodules should be imported directly
from @ref{10d,,typing} instead.
(Contributed by Sebastian Rittau in bpo-38291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38291}.)
@end itemize

@node Removed<8>,Porting to Python 3 10,Deprecated<8>,What’s New In Python 3 10
@anchor{whatsnew/3 10 removed}@anchor{c4b}@anchor{whatsnew/3 10 whatsnew310-removed}@anchor{c4c}
@subsection Removed



@itemize *

@item 
Removed special methods @code{__int__}, @code{__float__}, @code{__floordiv__},
@code{__mod__}, @code{__divmod__}, @code{__rfloordiv__}, @code{__rmod__} and
@code{__rdivmod__} of the @ref{328,,complex} class.  They always raised
a @ref{291,,TypeError}.
(Contributed by Serhiy Storchaka in bpo-41974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41974}.)

@item 
The @code{ParserBase.error()} method from the private and undocumented @code{_markupbase}
module has been removed.  @ref{c4d,,html.parser.HTMLParser} is the only subclass of
@code{ParserBase} and its @code{error()} implementation was already removed in
Python 3.5.
(Contributed by Berker Peksag in bpo-31844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31844}.)

@item 
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.
(Contributed by Victor Stinner in bpo-42157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42157}.)

@item 
Removed the @code{parser} module, which was deprecated in 3.9 due to the
switch to the new PEG parser, as well as all the C source and header files
that were only being used by the old parser, including @code{node.h}, @code{parser.h},
@code{graminit.h} and @code{grammar.h}.

@item 
Removed the Public C API functions @code{PyParser_SimpleParseStringFlags},
@code{PyParser_SimpleParseStringFlagsFilename},
@code{PyParser_SimpleParseFileFlags} and @code{PyNode_Compile}
that were deprecated in 3.9 due to the switch to the new PEG parser.

@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 
Remove deprecated aliases to @ref{c4e,,Αφηρημένες Βασικές Κλάσεις Συλλογών} from
the @ref{1e,,collections} module.
(Contributed by Victor Stinner in bpo-37324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37324}.)

@item 
The @code{loop} parameter has been removed from most of @ref{b,,asyncio}“s
@ref{c4f,,high-level API} following deprecation
in Python 3.8.  The motivation behind this change is multifold:


@enumerate 

@item 
This simplifies the high-level API.

@item 
The functions in the high-level API have been implicitly getting the
current thread’s running event loop since Python 3.7.  There isn’t a need to
pass the event loop to the API in most normal use cases.

@item 
Event loop passing is error-prone especially when dealing with loops
running in different threads.
@end enumerate

Note that the low-level API will still accept @code{loop}.
See @ref{c50,,Changes in the Python API} for examples of how to replace existing code.

(Contributed by Yurii Karabas, Andrew Svetlov, Yury Selivanov and Kyle Stanley
in bpo-42392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42392}.)
@end itemize

@node Porting to Python 3 10,CPython bytecode changes<4>,Removed<8>,What’s New In Python 3 10
@anchor{whatsnew/3 10 porting-to-python-3-10}@anchor{c51}
@subsection Porting to Python 3.10


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

@menu
* Changes in the Python syntax:: 
* Changes in the Python API: Changes in the Python API<4>. 
* Changes in the C API: Changes in the C API<3>. 

@end menu

@node Changes in the Python syntax,Changes in the Python API<4>,,Porting to Python 3 10
@anchor{whatsnew/3 10 changes-in-the-python-syntax}@anchor{c52}
@subsubsection Changes in the Python syntax



@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 Changes in the Python API<4>,Changes in the C API<3>,Changes in the Python syntax,Porting to Python 3 10
@anchor{whatsnew/3 10 changes-in-the-python-api}@anchor{c53}@anchor{whatsnew/3 10 changes-python-api}@anchor{c50}
@subsubsection Changes in the Python API



@itemize *

@item 
The `etype' parameters of the @ref{c25,,format_exception()},
@ref{c26,,format_exception_only()}, and
@ref{c27,,print_exception()} functions in the @ref{107,,traceback} module
have been renamed to `exc'.
(Contributed by Zackery Spytz and Matthias Bussonnier in bpo-26389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26389}.)

@item 
@ref{d,,atexit}: At Python exit, if a callback registered with
@ref{c54,,atexit.register()} fails, its exception is now logged. Previously, only
some exceptions were logged, and the last exception was always silently
ignored.
(Contributed by Victor Stinner in bpo-42639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42639}.)

@item 
@ref{bc6,,collections.abc.Callable} generic now flattens type parameters, similar
to what @ref{ba5,,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)}.  Code which
accesses the arguments via @ref{315,,typing.get_args()} or @code{__args__} need to account
for this change.  Furthermore, @ref{291,,TypeError} may be raised for invalid forms
of parameterizing @code{collections.abc.Callable} which may have passed
silently in Python 3.9.
(Contributed by Ken Jin in bpo-42195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42195}.)

@item 
@ref{c55,,socket.htons()} and @ref{c56,,socket.ntohs()} now raise @ref{c57,,OverflowError}
instead of @ref{2c9,,DeprecationWarning} if the given parameter will not fit in
a 16-bit unsigned integer.
(Contributed by Erlend E. Aasland in bpo-42393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42393}.)

@item 
The @code{loop} parameter has been removed from most of @ref{b,,asyncio}“s
@ref{c4f,,high-level API} following deprecation
in Python 3.8.

A coroutine that currently looks like this:

@example
async def foo(loop):
    await asyncio.sleep(1, loop=loop)
@end example

Should be replaced with this:

@example
async def foo():
    await asyncio.sleep(1)
@end example

If @code{foo()} was specifically designed `not' to run in the current thread’s
running event loop (e.g. running in another thread’s event loop), consider
using @ref{c58,,asyncio.run_coroutine_threadsafe()} instead.

(Contributed by Yurii Karabas, Andrew Svetlov, Yury Selivanov and Kyle Stanley
in bpo-42392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42392}.)

@item 
The @ref{c59,,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{184,,eval()} and
@ref{185,,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.
(Contributed by Victor Stinner in bpo-42990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42990}.)
@end itemize

@node Changes in the C API<3>,,Changes in the Python API<4>,Porting to Python 3 10
@anchor{whatsnew/3 10 changes-in-the-c-api}@anchor{c5a}
@subsubsection Changes in the C API



@itemize *

@item 
The C API functions @code{PyParser_SimpleParseStringFlags},
@code{PyParser_SimpleParseStringFlagsFilename},
@code{PyParser_SimpleParseFileFlags}, @code{PyNode_Compile} and the type
used by these functions, @code{struct _node}, were removed due to the switch
to the new PEG parser.

Source should be now be compiled directly to a code object using, for
example, @ref{c5b,,Py_CompileString()}. The resulting code object can then be
evaluated using, for example, @ref{c5c,,PyEval_EvalCode()}.

Specifically:


@itemize *

@item 
A call to @code{PyParser_SimpleParseStringFlags} followed by
@code{PyNode_Compile} can be replaced by calling @ref{c5b,,Py_CompileString()}.

@item 
There is no direct replacement for @code{PyParser_SimpleParseFileFlags}.
To compile code from a @code{FILE *} argument, you will need to read
the file in C and pass the resulting buffer to @ref{c5b,,Py_CompileString()}.

@item 
To compile a file given a @code{char *} filename, explicitly open the file, read
it and compile the result. One way to do this is using the @ref{82,,io}
module with @ref{3a3,,PyImport_ImportModule()}, @ref{3b6,,PyObject_CallMethod()},
@ref{c5d,,PyBytes_AsString()} and @ref{c5b,,Py_CompileString()},
as sketched below. (Declarations and error handling are omitted.)

@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{c5e,,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{c5f,,PyCode_Addr2Line()} for example). Notice as well that the
@code{f_lasti} member of @code{FrameObject} objects is not considered stable: please
use @ref{b6a,,PyFrame_GetLineNumber()} instead.
@end itemize
@end itemize

@node CPython bytecode changes<4>,Build Changes<4>,Porting to Python 3 10,What’s New In Python 3 10
@anchor{whatsnew/3 10 cpython-bytecode-changes}@anchor{c60}
@subsection CPython bytecode changes



@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 Build Changes<4>,C API Changes<4>,CPython bytecode changes<4>,What’s New In Python 3 10
@anchor{whatsnew/3 10 build-changes}@anchor{c61}
@subsection Build Changes



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/}: Python now requires OpenSSL 1.1.1 or newer. OpenSSL 1.0.2 is no
longer supported.
(Contributed by Christian Heimes in bpo-43669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43669}.)

@item 
The C99 functions @code{snprintf()} and @code{vsnprintf()} are now required
to build Python.
(Contributed by Victor Stinner in bpo-36020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36020}.)

@item 
@ref{d7,,sqlite3} requires SQLite 3.7.15 or higher. (Contributed by Sergey Fedoseev
and Erlend E. Aasland in bpo-40744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40744} and bpo-40810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40810}.)

@item 
The @ref{d,,atexit} module must now always be built as a built-in module.
(Contributed by Victor Stinner in bpo-42639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42639}.)

@item 
Add @ref{c62,,--disable-test-modules} option to the @code{configure} script:
don’t build nor install test modules.
(Contributed by Xavier de Gaye, Thomas Petazzoni and Peixing Xin in bpo-27640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27640}.)

@item 
Add @ref{c63,,--with-wheel-pkg-dir=PATH option}
to the @code{./configure} script. If
specified, the @ref{58,,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.

(Contributed by Victor Stinner in bpo-42856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42856}.)

@item 
Add a new @ref{c64,,configure --without-static-libpython option} to not build the @code{libpythonMAJOR.MINOR.a}
static library and not install the @code{python.o} object file.

(Contributed by Victor Stinner in 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 
Add @ref{c65,,--with-openssl-rpath} option to @code{configure} script. The option
simplifies building Python with a custom OpenSSL installation, e.g.
@code{./configure --with-openssl=/path/to/openssl --with-openssl-rpath=auto}.
(Contributed by Christian Heimes in bpo-43466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43466}.)
@end itemize

@node C API Changes<4>,Notable security feature in 3 10 7,Build Changes<4>,What’s New In Python 3 10
@anchor{whatsnew/3 10 c-api-changes}@anchor{c66}
@subsection C API Changes


@menu
* PEP 652; Maintaining the Stable ABI: PEP 652 Maintaining the Stable ABI. 
* New Features: New Features<8>. 
* Porting to Python 3.10: Porting to Python 3 10<2>. 
* Deprecated: Deprecated<9>. 
* Removed: Removed<9>. 

@end menu

@node PEP 652 Maintaining the Stable ABI,New Features<8>,,C API Changes<4>
@anchor{whatsnew/3 10 pep-652-maintaining-the-stable-abi}@anchor{c67}
@subsubsection PEP 652: Maintaining the Stable ABI


The Stable ABI (Application Binary Interface) for extension modules or
embedding Python is now explicitly defined.
@ref{95c,,C API and ABI Stability} describes C API and ABI stability guarantees along with best
practices for using the Stable ABI.

(Contributed by Petr Viktorin in 
@geindex Python Enhancement Proposals; PEP 652
PEP 652@footnote{https://peps.python.org/pep-0652/} and bpo-43795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43795}.)

@node New Features<8>,Porting to Python 3 10<2>,PEP 652 Maintaining the Stable ABI,C API Changes<4>
@anchor{whatsnew/3 10 id1}@anchor{c68}
@subsubsection New Features



@itemize *

@item 
The result of @ref{c69,,PyNumber_Index()} now always has exact type @ref{326,,int}.
Previously, the result could have been an instance of a subclass of @code{int}.
(Contributed by Serhiy Storchaka in bpo-40792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40792}.)

@item 
Add a new @ref{c6a,,orig_argv} member to the @ref{60b,,PyConfig}
structure: the list of the original command line arguments passed to the
Python executable.
(Contributed by Victor Stinner in bpo-23427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23427}.)

@item 
The @ref{c6b,,PyDateTime_DATE_GET_TZINFO()} and
@ref{c6c,,PyDateTime_TIME_GET_TZINFO()} macros have been added for accessing
the @code{tzinfo} attributes of @ref{6e7,,datetime.datetime} and
@ref{48e,,datetime.time} objects.
(Contributed by Zackery Spytz in bpo-30155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30155}.)

@item 
Add a @ref{c6d,,PyCodec_Unregister()} function to unregister a codec
search function.
(Contributed by Hai Shi in bpo-41842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41842}.)

@item 
The @ref{c6e,,PyIter_Send()} function was added to allow
sending value into iterator without raising @code{StopIteration} exception.
(Contributed by Vladimir Matveev in bpo-41756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41756}.)

@item 
Add @ref{c6f,,PyUnicode_AsUTF8AndSize()} to the limited C API.
(Contributed by Alex Gaynor in bpo-41784@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41784}.)

@item 
Add @ref{800,,PyModule_AddObjectRef()} function: similar to
@ref{801,,PyModule_AddObject()} but don’t steal a reference to the value on
success.
(Contributed by Victor Stinner in bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}.)

@item 
Add @ref{c70,,Py_NewRef()} and @ref{c71,,Py_XNewRef()} functions to increment the
reference count of an object and return the object.
(Contributed by Victor Stinner in bpo-42262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42262}.)

@item 
The @ref{38f,,PyType_FromSpecWithBases()} and @ref{390,,PyType_FromModuleAndSpec()}
functions now accept a single class as the `bases' argument.
(Contributed by Serhiy Storchaka in bpo-42423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42423}.)

@item 
The @ref{390,,PyType_FromModuleAndSpec()} function now accepts NULL @code{tp_doc}
slot.
(Contributed by Hai Shi in bpo-41832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41832}.)

@item 
The @ref{c72,,PyType_GetSlot()} function can accept
@ref{b5f,,static types}.
(Contributed by Hai Shi and Petr Viktorin in bpo-41073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41073}.)

@item 
Add a new @ref{c73,,PySet_CheckExact()} function to the C-API to check if an
object is an instance of @ref{42b,,set} but not an instance of a subtype.
(Contributed by Pablo Galindo in bpo-43277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43277}.)

@item 
Add @ref{c74,,PyErr_SetInterruptEx()} which allows passing a signal number
to simulate.
(Contributed by Antoine Pitrou in bpo-43356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43356}.)

@item 
The limited C API is now supported if @ref{3dc,,Python is built in debug mode} (if the @code{Py_DEBUG} macro is defined). In the limited C API,
the @ref{974,,Py_INCREF()} and @ref{975,,Py_DECREF()} functions are now implemented
as opaque function
calls, rather than accessing directly the @ref{c75,,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{19b,,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 @ref{828,,--with-trace-refs}
special build (@code{Py_TRACE_REFS} macro).
(Contributed by Victor Stinner in bpo-43688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43688}.)

@item 
Add the @ref{c76,,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{c77,,Py_IsNone()}, @ref{c78,,Py_IsTrue()}, @ref{c79,,Py_IsFalse()} functions to
test if an object is, respectively, the @code{None} singleton, the @code{True}
singleton or the @code{False} singleton.
(Contributed by Victor Stinner in bpo-43753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43753}.)

@item 
Add new functions to control the garbage collector from C code:
@ref{c7a,,PyGC_Enable()},
@ref{c7b,,PyGC_Disable()},
@ref{c7c,,PyGC_IsEnabled()}.
These functions allow to activate, deactivate and query the state of the garbage collector from C code without
having to import the @ref{63,,gc} module.

@item 
Add a new @ref{984,,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{5fb,,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 Porting to Python 3 10<2>,Deprecated<9>,New Features<8>,C API Changes<4>
@anchor{whatsnew/3 10 id2}@anchor{c7d}
@subsubsection Porting to Python 3.10



@itemize *

@item 
The @code{PY_SSIZE_T_CLEAN} macro must now be defined to use
@ref{3b1,,PyArg_ParseTuple()} and @ref{5ee,,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{601,,Parsing arguments and building values} 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 
Since @ref{54b,,Py_REFCNT()} is changed to the inline static function,
@code{Py_REFCNT(obj) = new_refcnt} must be replaced with @code{Py_SET_REFCNT(obj, new_refcnt)}:
see @ref{c7e,,Py_SET_REFCNT()} (available since Python 3.9). For backward
compatibility, this macro can be used:

@example
#if PY_VERSION_HEX < 0x030900A4
#  define Py_SET_REFCNT(obj, refcnt) ((Py_REFCNT(obj) = (refcnt)), (void)0)
#endif
@end example

(Contributed by Victor Stinner in bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}.)

@item 
Calling @ref{81c,,PyDict_GetItem()} without @ref{411,,GIL} held had been allowed
for historical reason. It is no longer allowed.
(Contributed by Victor Stinner in bpo-40839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40839}.)

@item 
@code{PyUnicode_FromUnicode(NULL, size)} and @code{PyUnicode_FromStringAndSize(NULL, size)}
raise @code{DeprecationWarning} now.  Use @ref{c7f,,PyUnicode_New()} to allocate
Unicode object without initial data.
(Contributed by Inada Naoki in bpo-36346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36346}.)

@item 
The private @code{_PyUnicode_Name_CAPI} structure of the PyCapsule API
@code{unicodedata.ucnhash_CAPI} has been moved to the internal C API.
(Contributed by Victor Stinner in bpo-42157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42157}.)

@item 
@code{Py_GetPath()}, @code{Py_GetPrefix()}, @code{Py_GetExecPrefix()},
@code{Py_GetProgramFullPath()}, @code{Py_GetPythonHome()} and
@code{Py_GetProgramName()} functions now return @code{NULL} if called before
@ref{673,,Py_Initialize()} (before Python is initialized). Use the new
@ref{837,,Python Initialization Configuration} API to get the @ref{c80,,Python Path Configuration}.
(Contributed by Victor Stinner in bpo-42260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42260}.)

@item 
@ref{822,,PyList_SET_ITEM()}, @ref{821,,PyTuple_SET_ITEM()} and
@ref{c81,,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{b63,,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{5fb,,Py_TPFLAGS_IMMUTABLETYPE} type flag to create immutable type
objects. Do not rely on @ref{c82,,Py_TPFLAGS_HEAPTYPE} to decide if a type
object is mutable or not; check if @code{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 Deprecated<9>,Removed<9>,Porting to Python 3 10<2>,C API Changes<4>
@anchor{whatsnew/3 10 id3}@anchor{c83}
@subsubsection Deprecated



@itemize *

@item 
The @code{PyUnicode_InternImmortal()} function is now deprecated
and will be removed in Python 3.12: use @ref{c84,,PyUnicode_InternInPlace()}
instead.
(Contributed by Victor Stinner in bpo-41692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41692}.)
@end itemize

@node Removed<9>,,Deprecated<9>,C API Changes<4>
@anchor{whatsnew/3 10 id4}@anchor{c85}
@subsubsection Removed



@itemize *

@item 
Removed @code{Py_UNICODE_str*} functions manipulating @code{Py_UNICODE*} strings.
(Contributed by Inada Naoki in bpo-41123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41123}.)


@itemize *

@item 
@code{Py_UNICODE_strlen}: use @ref{c86,,PyUnicode_GetLength()} or
@ref{c87,,PyUnicode_GET_LENGTH}

@item 
@code{Py_UNICODE_strcat}: use @ref{c88,,PyUnicode_CopyCharacters()} or
@ref{81e,,PyUnicode_FromFormat()}

@item 
@code{Py_UNICODE_strcpy}, @code{Py_UNICODE_strncpy}: use
@ref{c88,,PyUnicode_CopyCharacters()} or @ref{c89,,PyUnicode_Substring()}

@item 
@code{Py_UNICODE_strcmp}: use @ref{c8a,,PyUnicode_Compare()}

@item 
@code{Py_UNICODE_strncmp}: use @ref{c8b,,PyUnicode_Tailmatch()}

@item 
@code{Py_UNICODE_strchr}, @code{Py_UNICODE_strrchr}: use
@ref{c8c,,PyUnicode_FindChar()}
@end itemize

@item 
Removed @code{PyUnicode_GetMax()}. Please migrate to new (
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/}) APIs.
(Contributed by Inada Naoki in bpo-41103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41103}.)

@item 
Removed @code{PyLong_FromUnicode()}. Please migrate to @ref{c8d,,PyLong_FromUnicodeObject()}.
(Contributed by Inada Naoki in bpo-41103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41103}.)

@item 
Removed @code{PyUnicode_AsUnicodeCopy()}. Please use @ref{c8e,,PyUnicode_AsUCS4Copy()} or
@ref{c8f,,PyUnicode_AsWideCharString()}
(Contributed by Inada Naoki in bpo-41103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41103}.)

@item 
Removed @code{_Py_CheckRecursionLimit} variable: it has been replaced by
@code{ceval.recursion_limit} of the @ref{c90,,PyInterpreterState} structure.
(Contributed by Victor Stinner in bpo-41834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41834}.)

@item 
Removed undocumented macros @code{Py_ALLOW_RECURSION} and
@code{Py_END_ALLOW_RECURSION} and the @code{recursion_critical} field of the
@ref{c90,,PyInterpreterState} structure.
(Contributed by Serhiy Storchaka in bpo-41936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41936}.)

@item 
Removed the undocumented @code{PyOS_InitInterrupts()} function. Initializing
Python already implicitly installs signal handlers: see
@ref{c91,,PyConfig.install_signal_handlers}.
(Contributed by Victor Stinner in bpo-41713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41713}.)

@item 
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/}).
(Contributed by Victor Stinner in bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}.)

@item 
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.

Use Python @ref{e1,,symtable} module instead.
(Contributed by Victor Stinner in bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}.)

@item 
Remove @ref{987,,PyOS_ReadlineFunctionPointer()} from the limited C API headers
and from @code{python3.dll}, the library that provides the stable ABI on
Windows. Since the function takes a @code{FILE*} argument, its ABI stability
cannot be guaranteed.
(Contributed by Petr Viktorin in bpo-43868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43868}.)

@item 
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{9,,ast} module instead.
(Contributed by Victor Stinner in bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}.)

@item 
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.
(Contributed by Victor Stinner in bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}.)

@item 
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.
(Contributed by Victor Stinner in bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}.)

@item 
The @code{PyThreadState.use_tracing} member has been removed to optimize Python.
(Contributed by Mark Shannon in 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,C API Changes<4>,What’s New In Python 3 10
@anchor{whatsnew/3 10 notable-security-feature-in-3-10-7}@anchor{c92}
@subsection Notable security feature in 3.10.7


Converting between @ref{326,,int} and @ref{1df,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{277,,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{e2,,sys} APIs. See the @ref{9ec,,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,What’s New In Python 3 10
@anchor{whatsnew/3 10 notable-security-feature-in-3-10-8}@anchor{c93}
@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,What’s New In Python 3 10
@anchor{whatsnew/3 10 notable-changes-in-3-10-12}@anchor{c94}
@subsection Notable changes in 3.10.12


@menu
* tarfile: tarfile<4>. 

@end menu

@node tarfile<4>,,,Notable changes in 3 10 12
@anchor{whatsnew/3 10 tarfile}@anchor{c95}
@subsubsection tarfile



@itemize *

@item 
The extraction methods in @ref{e7,,tarfile}, and @ref{882,,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{883,,Extraction filters} for details.
In Python 3.12, use without the `filter' argument will show a
@ref{2c9,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 9,What’s New In Python 3 8,What’s New In Python 3 10,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 9 doc}@anchor{c96}@anchor{whatsnew/3 9 translation-repo}@anchor{c97}@anchor{whatsnew/3 9 what-s-new-in-python-3-9}@anchor{c98}
@section What’s New In Python 3.9


@*Editor: 
Ł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{145,,changelog}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 596
PEP 596@footnote{https://peps.python.org/pep-0596/} - Python 3.9 Release Schedule


@menu
* Summary – Release highlights: Summary – Release highlights<6>. 
* You should check for DeprecationWarning in your code:: 
* New Features: New Features<9>. 
* Other Language Changes: Other Language Changes<5>. 
* New Modules: New Modules<5>. 
* Improved Modules: Improved Modules<5>. 
* Optimizations: Optimizations<8>. 
* Deprecated: Deprecated<10>. 
* Removed: Removed<10>. 
* Porting to Python 3.9: Porting to Python 3 9. 
* Build Changes: Build Changes<5>. 
* C API Changes: C API Changes<5>. 
* Notable changes in Python 3.9.1: Notable changes in Python 3 9 1. 
* Notable changes in Python 3.9.2: Notable changes in 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 Summary – Release highlights<6>,You should check for DeprecationWarning in your code,,What’s New In Python 3 9
@anchor{whatsnew/3 9 summary-release-highlights}@anchor{c99}
@subsection Summary – Release highlights


@c This section singles out the most important changes in Python 3.9.
@c Brevity is key.

New syntax features:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}, union operators added to @code{dict};

@item 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/}, type hinting generics in standard collections;

@item 
@geindex Python Enhancement Proposals; PEP 614
PEP 614@footnote{https://peps.python.org/pep-0614/}, relaxed grammar restrictions on decorators.
@end itemize

New built-in features:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 616
PEP 616@footnote{https://peps.python.org/pep-0616/}, string methods to remove prefixes and suffixes.
@end itemize

New features in the standard library:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 593
PEP 593@footnote{https://peps.python.org/pep-0593/}, flexible function and variable annotations;

@item 
@ref{267,,os.pidfd_open()} added that allows process management without races
and signals.
@end itemize

Interpreter improvements:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 573
PEP 573@footnote{https://peps.python.org/pep-0573/}, fast access to module state from methods of C extension
types;

@item 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/}, CPython now uses a new parser based on PEG;

@item 
a number of Python builtins (range, tuple, set, frozenset, list, dict) are
now sped up using 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} vectorcall;

@item 
garbage collection does not block on resurrected objects;

@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{91,,math}, @ref{a3,,operator}, @ref{c4,,resource},
@ref{f7,,time}, @code{_weakref}) now use multiphase initialization as defined
by PEP 489;

@item 
a number of standard library modules (@code{audioop}, @ref{9,,ast}, @ref{69,,grp},
@code{_hashlib}, @ref{ba,,pwd}, @code{_posixsubprocess}, @ref{c0,,random},
@ref{c9,,select}, @ref{de,,struct}, @ref{ea,,termios}, @ref{13c,,zlib}) are now using
the stable ABI defined by PEP 384.
@end itemize

New library modules:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 615
PEP 615@footnote{https://peps.python.org/pep-0615/}, the IANA Time Zone Database is now present in the standard
library in the @ref{13d,,zoneinfo} module;

@item 
an implementation of a topological sort of a graph is now provided in
the new @ref{68,,graphlib} module.
@end itemize

Release process changes:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 602
PEP 602@footnote{https://peps.python.org/pep-0602/}, CPython adopts an annual release cycle.
@end itemize

@node You should check for DeprecationWarning in your code,New Features<9>,Summary – Release highlights<6>,What’s New In Python 3 9
@anchor{whatsnew/3 9 you-should-check-for-deprecationwarning-in-your-code}@anchor{c9a}
@subsection You should check for DeprecationWarning in your code


When Python 2.7 was still supported, a lot of functionality in Python 3
was kept for backward compatibility with Python 2.7. With the end of Python
2 support, these backward compatibility layers have been removed, or will
be removed soon. Most of them emitted a @ref{2c9,,DeprecationWarning} warning for
several years. For example, using @code{collections.Mapping} instead of
@code{collections.abc.Mapping} emits a @code{DeprecationWarning} since Python
3.3, released in 2012.

Test your application with the @ref{1c0,,-W} @code{default} command-line option to see
@ref{2c9,,DeprecationWarning} and @ref{c9b,,PendingDeprecationWarning}, or even with
@code{-W} @code{error} to treat them as errors. @ref{1cc,,Warnings Filter} can be used to ignore warnings from third-party code.

Python 3.9 is the last version providing those Python 2 backward compatibility
layers, to give more time to Python projects maintainers to organize the
removal of the Python 2 support and add support for Python 3.9.

Aliases to @ref{c4e,,Abstract Base Classes} in
the @ref{1e,,collections} module, like @code{collections.Mapping} alias to
@ref{c9c,,collections.abc.Mapping}, are kept for one last release for backward
compatibility. They will be removed from Python 3.10.

More generally, try to run your tests in the @ref{70d,,Python Development Mode} which helps to prepare your code to make it compatible with the
next Python version.

Note: a number of pre-existing deprecations were removed in this version of
Python as well. Consult the @ref{c9d,,Removed} section.

@node New Features<9>,Other Language Changes<5>,You should check for DeprecationWarning in your code,What’s New In Python 3 9
@anchor{whatsnew/3 9 new-features}@anchor{c9e}
@subsection New Features


@menu
* Dictionary Merge & Update Operators:: 
* New String Methods to Remove Prefixes and Suffixes:: 
* Type Hinting Generics in Standard Collections:: 
* New Parser:: 

@end menu

@node Dictionary Merge & Update Operators,New String Methods to Remove Prefixes and Suffixes,,New Features<9>
@anchor{whatsnew/3 9 dictionary-merge-update-operators}@anchor{c9f}
@subsubsection Dictionary Merge & Update Operators


Merge (@code{|}) and update (@code{|=}) operators have been added to the built-in
@ref{188,,dict} class. Those complement the existing @code{dict.update} and
@code{@{**d1, **d2@}} methods of merging dictionaries.

Example:

@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

See 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/} for a full description.
(Contributed by Brandt Bucher in bpo-36144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36144}.)

@node New String Methods to Remove Prefixes and Suffixes,Type Hinting Generics in Standard Collections,Dictionary Merge & Update Operators,New Features<9>
@anchor{whatsnew/3 9 new-string-methods-to-remove-prefixes-and-suffixes}@anchor{ca0}
@subsubsection New String Methods to Remove Prefixes and Suffixes


@ref{ca1,,str.removeprefix(prefix)} and
@ref{ca2,,str.removesuffix(suffix)} have been added
to easily remove an unneeded prefix or a suffix from a string. Corresponding
@code{bytes}, @code{bytearray}, and @code{collections.UserString} methods have also been
added. See 
@geindex Python Enhancement Proposals; PEP 616
PEP 616@footnote{https://peps.python.org/pep-0616/} for a full description. (Contributed by Dennis Sweeney in
bpo-39939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39939}.)

@node Type Hinting Generics in Standard Collections,New Parser,New String Methods to Remove Prefixes and Suffixes,New Features<9>
@anchor{whatsnew/3 9 type-hinting-generics-in-standard-collections}@anchor{ca3}
@subsubsection Type Hinting Generics in Standard Collections


In type annotations you can now use built-in collection types such as
@code{list} and @code{dict} as generic types instead of importing the
corresponding capitalized types (e.g. @code{List} or @code{Dict}) from
@code{typing}.  Some other types in the standard library are also now generic,
for example @code{queue.Queue}.

Example:

@example
def greet_all(names: list[str]) -> None:
    for name in names:
        print("Hello", name)
@end example

See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} for more details.  (Contributed by Guido van Rossum,
Ethan Smith, and Batuhan Taşkaya in bpo-39481@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39481}.)

@node New Parser,,Type Hinting Generics in Standard Collections,New Features<9>
@anchor{whatsnew/3 9 new-parser}@anchor{ca4}
@subsubsection New Parser


Python 3.9 uses a new parser, based on PEG@footnote{https://en.wikipedia.org/wiki/Parsing_expression_grammar} instead
of LL(1)@footnote{https://en.wikipedia.org/wiki/LL_parser}.  The new
parser’s performance is roughly comparable to that of the old parser,
but the PEG formalism is more flexible than LL(1) when it comes to
designing new language features.  We’ll start using this flexibility
in Python 3.10 and later.

The @ref{9,,ast} module uses the new parser and produces the same AST as
the old parser.

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}).

See 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/} for more details.  (Contributed by Guido van Rossum,
Pablo Galindo and Lysandros Nikolaou in bpo-40334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40334}.)

@node Other Language Changes<5>,New Modules<5>,New Features<9>,What’s New In Python 3 9
@anchor{whatsnew/3 9 other-language-changes}@anchor{ca5}
@subsection Other Language Changes



@itemize *

@item 
@ref{ca6,,__import__()} now raises @ref{1bd,,ImportError} instead of
@ref{277,,ValueError}, which used to occur when a relative import went past
its top-level package.
(Contributed by Ngalim Siregar in bpo-37444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37444}.)

@item 
Python now gets the absolute path of the script filename specified on
the command line (ex: @code{python3 script.py}): the @code{__file__} attribute of
the @ref{1,,__main__} module became an absolute path, rather than a relative
path. These paths now remain valid after the current directory is changed
by @ref{a02,,os.chdir()}. As a side effect, the traceback also displays the
absolute path for @code{__main__} module frames in this case.
(Contributed by Victor Stinner in bpo-20443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20443}.)

@item 
In the @ref{70d,,Python Development Mode} and in @ref{3dc,,debug build}, the
`encoding' and `errors' arguments are now checked for string encoding and
decoding operations. Examples: @ref{32b,,open()}, @ref{ca7,,str.encode()} and
@ref{ca8,,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.
(Contributed by Victor Stinner in bpo-37388@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37388}.)

@item 
@code{"".replace("", s, n)} now returns @code{s} instead of an empty string for
all non-zero @code{n}.  It is now consistent with @code{"".replace("", s)}.
There are similar changes for @ref{1c7,,bytes} and @ref{1c6,,bytearray} objects.
(Contributed by Serhiy Storchaka in bpo-28029@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28029}.)

@item 
Any valid expression can now be used as a @ref{b18,,decorator}.  Previously, the
grammar was much more restrictive.  See 
@geindex Python Enhancement Proposals; PEP 614
PEP 614@footnote{https://peps.python.org/pep-0614/} for details.
(Contributed by Brandt Bucher in bpo-39702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39702}.)

@item 
Improved help for the @ref{10d,,typing} module. Docstrings are now shown for
all special forms and special generic aliases (like @code{Union} and @code{List}).
Using @ref{ca9,,help()} with generic alias like @code{List[int]} will show the help
for the correspondent concrete type (@code{list} in this case).
(Contributed by Serhiy Storchaka in bpo-40257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40257}.)

@item 
Parallel running of @ref{caa,,aclose()} / @ref{cab,,asend()} /
@ref{906,,athrow()} is now prohibited, and @code{ag_running} now reflects
the actual running status of the async generator.
(Contributed by Yury Selivanov in bpo-30773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30773}.)

@item 
Unexpected errors in calling the @code{__iter__} method are no longer masked by
@code{TypeError} in the @ref{323,,in} operator and functions
@ref{cac,,contains()}, @ref{cad,,indexOf()} and
@ref{cae,,countOf()} of the @ref{a3,,operator} module.
(Contributed by Serhiy Storchaka in bpo-40824@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40824}.)

@item 
Unparenthesized lambda expressions can no longer be the expression part in an
@code{if} clause in comprehensions and generator expressions. See bpo-41848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41848}
and bpo-43755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43755} for details.
@end itemize

@node New Modules<5>,Improved Modules<5>,Other Language Changes<5>,What’s New In Python 3 9
@anchor{whatsnew/3 9 new-modules}@anchor{caf}
@subsection New Modules


@menu
* zoneinfo:: 
* graphlib: graphlib<2>. 

@end menu

@node zoneinfo,graphlib<2>,,New Modules<5>
@anchor{whatsnew/3 9 zoneinfo}@anchor{cb0}
@subsubsection zoneinfo


The @ref{13d,,zoneinfo} module brings support for the IANA time zone database to
the standard library. It adds @ref{cb1,,zoneinfo.ZoneInfo}, a concrete
@ref{9d8,,datetime.tzinfo} implementation backed by the system’s time zone data.

Example:

@example
>>> from zoneinfo import ZoneInfo
>>> import datetime as dt

>>> # Daylight saving time
>>> when = dt.datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(when)
2020-10-31 12:00:00-07:00
>>> when.tzname()
'PDT'

>>> # Standard time
>>> when += dt.timedelta(days=7)
>>> print(when)
2020-11-07 12:00:00-08:00
>>> print(when.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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 615

@item PEP 615@footnote{https://peps.python.org/pep-0615/} – Support for the IANA Time Zone Database in the Standard Library

PEP written and implemented by Paul Ganssle
@end table


@node graphlib<2>,,zoneinfo,New Modules<5>
@anchor{whatsnew/3 9 graphlib}@anchor{cb2}
@subsubsection graphlib


A new module, @ref{68,,graphlib}, was added that contains the
@ref{cb3,,graphlib.TopologicalSorter} class to offer functionality to perform
topological sorting of graphs. (Contributed by Pablo Galindo, Tim Peters and
Larry Hastings in bpo-17005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17005}.)

@node Improved Modules<5>,Optimizations<8>,New Modules<5>,What’s New In Python 3 9
@anchor{whatsnew/3 9 improved-modules}@anchor{cb4}
@subsection Improved Modules


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

@end menu

@node ast<6>,asyncio<9>,,Improved Modules<5>
@anchor{whatsnew/3 9 ast}@anchor{cb5}
@subsubsection ast


Added the `indent' option to @ref{1e1,,dump()} which allows it to produce a
multiline indented output.
(Contributed by Serhiy Storchaka in bpo-37995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37995}.)

Added @ref{cb6,,ast.unparse()} as a function in the @ref{9,,ast} module that can
be used to unparse an @ref{2ec,,ast.AST} object and produce a string with code
that would produce an equivalent @code{ast.AST} object when parsed.
(Contributed by Pablo Galindo and Batuhan Taskaya in bpo-38870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38870}.)

Added docstrings to AST nodes that contains the ASDL signature used to
construct that node. (Contributed by Batuhan Taskaya in bpo-39638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39638}.)

@node asyncio<9>,compileall<2>,ast<6>,Improved Modules<5>
@anchor{whatsnew/3 9 asyncio}@anchor{cb7}
@subsubsection asyncio


Due to significant security concerns, the `reuse_address' parameter of
@ref{b1a,,asyncio.loop.create_datagram_endpoint()} is no longer supported. This is
because of the behavior of the socket option @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}.)

Added a new @ref{8a2,,coroutine} @ref{cb8,,shutdown_default_executor()}
that schedules a shutdown for the default executor that waits on the
@ref{b27,,ThreadPoolExecutor} to finish closing. Also,
@ref{309,,asyncio.run()} has been updated to use the new coroutine.
(Contributed by Kyle Stanley in bpo-34037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34037}.)

Added @code{asyncio.PidfdChildWatcher}, a Linux-specific child watcher
implementation that polls process file descriptors. (bpo-38692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38692})

Added a new @ref{8a2,,coroutine} @ref{cb9,,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{cba,,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{9f6,,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{b,,asyncio} now raises @ref{291,,TypeError} when calling incompatible
methods with an @ref{cbb,,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<4>,asyncio<9>,Improved Modules<5>
@anchor{whatsnew/3 9 compileall}@anchor{cbc}
@subsubsection compileall


Added new possibility to use hardlinks for duplicated @code{.pyc} files: `hardlink_dupes' parameter and –hardlink-dupes command line option.
(Contributed by  Lumír “Frenzy” Balhar in bpo-40495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40495}.)

Added new options for path manipulation in resulting @code{.pyc} files: `stripdir', `prependdir', `limit_sl_dest' parameters and -s, -p, -e command line options.
Added the possibility to specify the option for an optimization level multiple times.
(Contributed by Lumír “Frenzy” Balhar in bpo-38112@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38112}.)

@node concurrent futures<4>,curses<3>,compileall<2>,Improved Modules<5>
@anchor{whatsnew/3 9 concurrent-futures}@anchor{cbd}
@subsubsection concurrent.futures


Added a new `cancel_futures' parameter to
@ref{cbe,,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.
(Contributed by Kyle Stanley in bpo-39349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39349}.)

Removed daemon threads from @ref{b27,,ThreadPoolExecutor}
and @ref{206,,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{206,,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<3>,datetime<4>,concurrent futures<4>,Improved Modules<5>
@anchor{whatsnew/3 9 curses}@anchor{cbf}
@subsubsection curses


Added @ref{cc0,,curses.get_escdelay()}, @ref{cc1,,curses.set_escdelay()},
@ref{cc2,,curses.get_tabsize()}, and @ref{cc3,,curses.set_tabsize()} functions.
(Contributed by Anthony Sottile in bpo-38312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38312}.)

@node datetime<4>,distutils<3>,curses<3>,Improved Modules<5>
@anchor{whatsnew/3 9 datetime}@anchor{cc4}
@subsubsection datetime


The @ref{cc5,,isocalendar()} of @ref{48d,,datetime.date}
and @ref{cc6,,isocalendar()} of @ref{6e7,,datetime.datetime}
methods now returns a @ref{1cf,,namedtuple()} instead of a @ref{1ce,,tuple}.
(Contributed by Donghee Na in bpo-24416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24416}.)

@node distutils<3>,fcntl<2>,datetime<4>,Improved Modules<5>
@anchor{whatsnew/3 9 distutils}@anchor{cc7}
@subsubsection distutils


The @code{upload} command now creates SHA2-256 and Blake2b-256 hash
digests. It skips MD5 on platforms that block MD5 digest.
(Contributed by Christian Heimes in bpo-40698@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40698}.)

@node fcntl<2>,ftplib<2>,distutils<3>,Improved Modules<5>
@anchor{whatsnew/3 9 fcntl}@anchor{cc8}
@subsubsection fcntl


Added constants @code{fcntl.F_OFD_GETLK}, @code{fcntl.F_OFD_SETLK}
and @code{fcntl.F_OFD_SETLKW}.
(Contributed by Donghee Na in bpo-38602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38602}.)

@node ftplib<2>,gc<5>,fcntl<2>,Improved Modules<5>
@anchor{whatsnew/3 9 ftplib}@anchor{cc9}
@subsubsection ftplib


@ref{cca,,FTP} and @ref{ccb,,FTP_TLS} now raise a @ref{277,,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<5>,hashlib<5>,ftplib<2>,Improved Modules<5>
@anchor{whatsnew/3 9 gc}@anchor{ccc}
@subsubsection gc


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. (Contributed by Pablo Galindo and Tim Peters in bpo-38379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38379}.)

Added a new function @ref{ccd,,gc.is_finalized()} to check if an object has been
finalized by the garbage collector. (Contributed by Pablo Galindo in
bpo-39322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39322}.)

@node hashlib<5>,http<2>,gc<5>,Improved Modules<5>
@anchor{whatsnew/3 9 hashlib}@anchor{cce}
@subsubsection hashlib


The @ref{6b,,hashlib} module can now use SHA3 hashes and SHAKE XOF from OpenSSL
when available.
(Contributed by Christian Heimes in bpo-37630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37630}.)

Builtin hash modules can now be disabled with
@code{./configure --without-builtin-hashlib-hashes} or selectively enabled with
e.g. @code{./configure --with-builtin-hashlib-hashes=sha3,blake2} to force use
of OpenSSL based implementation.
(Contributed by Christian Heimes in bpo-40479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40479})

@node http<2>,IDLE and idlelib<3>,hashlib<5>,Improved Modules<5>
@anchor{whatsnew/3 9 http}@anchor{ccf}
@subsubsection http


HTTP status codes @code{103 EARLY_HINTS}, @code{418 IM_A_TEAPOT} and @code{425 TOO_EARLY} are added to
@ref{cd0,,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 and idlelib<3>,imaplib<2>,http<2>,Improved Modules<5>
@anchor{whatsnew/3 9 idle-and-idlelib}@anchor{cd1}
@subsubsection IDLE and idlelib


Added option to toggle cursor blink off.  (Contributed by Zackery Spytz
in bpo-4603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4603}.)

Escape key now closes IDLE completion windows.  (Contributed by Johnny
Najera in bpo-38944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38944}.)

Added keywords to module name completion list.  (Contributed by Terry J.
Reedy in bpo-37765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37765}.)

New in 3.9 maintenance releases

Make IDLE invoke @ref{be5,,sys.excepthook()} (when started without “-n”).
User hooks were previously ignored.  (Contributed by Ken Hilton in
bpo-43008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43008}.)

The changes above have been backported to 3.8 maintenance releases.

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}.)

Apply syntax highlighting to @code{.pyi} files. (Contributed by Alex
Waygood and Terry Jan Reedy in bpo-45447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45447}.)

@node imaplib<2>,importlib<3>,IDLE and idlelib<3>,Improved Modules<5>
@anchor{whatsnew/3 9 imaplib}@anchor{cd2}
@subsubsection imaplib


@ref{31a,,IMAP4} and @ref{cd3,,IMAP4_SSL} now have
an optional `timeout' parameter for their constructors.
Also, the @ref{cd4,,open()} method now has an optional `timeout' parameter
with this change. The overridden methods of @code{IMAP4_SSL} and
@ref{cd5,,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{cd6,,imaplib.IMAP4.unselect()} is added.
@code{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{cd7,,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<6>,imaplib<2>,Improved Modules<5>
@anchor{whatsnew/3 9 importlib}@anchor{cd8}
@subsubsection importlib


To improve consistency with import statements, @ref{cd9,,importlib.util.resolve_name()}
now raises @ref{1bd,,ImportError} instead of @ref{277,,ValueError} for invalid relative
import attempts.
(Contributed by Ngalim Siregar in bpo-37444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37444}.)

Import loaders which publish immutable module objects can now publish
immutable packages in addition to individual modules.
(Contributed by Dino Viehland in bpo-39336@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39336}.)

Added @ref{2d7,,importlib.resources.files()} function with support for
subdirectories in package data, matching backport in @code{importlib_resources}
version 1.5.
(Contributed by Jason R. Coombs in bpo-39791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39791}.)

Refreshed @code{importlib.metadata} from @code{importlib_metadata} version 1.6.1.

@node inspect<6>,ipaddress<2>,importlib<3>,Improved Modules<5>
@anchor{whatsnew/3 9 inspect}@anchor{cda}
@subsubsection inspect


@ref{cdb,,inspect.BoundArguments.arguments} is changed from @code{OrderedDict} to regular
dict.  (Contributed by Inada Naoki in bpo-36350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36350} and bpo-39775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39775}.)

@node ipaddress<2>,math<6>,inspect<6>,Improved Modules<5>
@anchor{whatsnew/3 9 ipaddress}@anchor{cdc}
@subsubsection ipaddress


@ref{83,,ipaddress} now supports IPv6 Scoped Addresses (IPv6 address with suffix @code{%<scope_id>}).

Scoped IPv6 addresses can be parsed using @ref{711,,ipaddress.IPv6Address}.
If present, scope zone ID is available through the @ref{cdd,,scope_id} attribute.
(Contributed by Oleksandr Pavliuk in bpo-34788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34788}.)

Starting with Python 3.9.5 the @ref{83,,ipaddress} module no longer
accepts any leading zeros in IPv4 address strings.
(Contributed by Christian Heimes in bpo-36384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36384}).

@node math<6>,multiprocessing<3>,ipaddress<2>,Improved Modules<5>
@anchor{whatsnew/3 9 math}@anchor{cde}
@subsubsection math


Expanded the @ref{cdf,,math.gcd()} function to handle multiple arguments.
Formerly, it only supported two arguments.
(Contributed by Serhiy Storchaka in bpo-39648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39648}.)

Added @ref{ce0,,math.lcm()}: return the least common multiple of specified arguments.
(Contributed by Mark Dickinson, Ananthakrishnan and Serhiy Storchaka in
bpo-39479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39479} and bpo-39648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39648}.)

Added @ref{8a9,,math.nextafter()}: return the next floating-point value after `x'
towards `y'.
(Contributed by Victor Stinner in bpo-39288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39288}.)

Added @ref{ce1,,math.ulp()}: return the value of the least significant bit
of a float.
(Contributed by Victor Stinner in bpo-39310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39310}.)

@node multiprocessing<3>,nntplib,math<6>,Improved Modules<5>
@anchor{whatsnew/3 9 multiprocessing}@anchor{ce2}
@subsubsection multiprocessing


The @ref{ce3,,multiprocessing.SimpleQueue} class has a new
@ref{ce4,,close()} method to explicitly close the
queue.
(Contributed by Victor Stinner in bpo-30966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30966}.)

@node nntplib,os<7>,multiprocessing<3>,Improved Modules<5>
@anchor{whatsnew/3 9 nntplib}@anchor{ce5}
@subsubsection nntplib


@code{NNTP} and @code{NNTP_SSL} now raise a @ref{277,,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<7>,pathlib<10>,nntplib,Improved Modules<5>
@anchor{whatsnew/3 9 os}@anchor{ce6}
@subsubsection os


Added @ref{ce7,,CLD_KILLED} and @ref{ce8,,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{267,,os.pidfd_open()} (bpo-38692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38692}) and
@ref{ce9,,os.P_PIDFD} (bpo-38713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38713}) for process management with file
descriptors.

The @ref{4e8,,os.unsetenv()} function is now also available on Windows.
(Contributed by Victor Stinner in bpo-39413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39413}.)

The @ref{4e7,,os.putenv()} and @ref{4e8,,os.unsetenv()} functions are now always
available.
(Contributed by Victor Stinner in bpo-39395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39395}.)

Added @ref{cea,,os.waitstatus_to_exitcode()} function:
convert a wait status to an exit code.
(Contributed by Victor Stinner in bpo-40094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40094}.)

@node pathlib<10>,pdb<6>,os<7>,Improved Modules<5>
@anchor{whatsnew/3 9 pathlib}@anchor{ceb}
@subsubsection pathlib


Added @ref{cec,,pathlib.Path.readlink()} which acts similarly to
@ref{ced,,os.readlink()}.
(Contributed by Girts Folkmanis in bpo-30618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30618})

@node pdb<6>,poplib,pathlib<10>,Improved Modules<5>
@anchor{whatsnew/3 9 pdb}@anchor{cee}
@subsubsection pdb


On Windows now @ref{4fb,,Pdb} supports @code{~/.pdbrc}.
(Contributed by Tim Hopper and Dan Lidral-Porter in bpo-20523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20523}.)

@node poplib,pprint<3>,pdb<6>,Improved Modules<5>
@anchor{whatsnew/3 9 poplib}@anchor{cef}
@subsubsection poplib


@ref{cf0,,POP3} and @ref{cf1,,POP3_SSL} now raise a @ref{277,,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<3>,pydoc<2>,poplib,Improved Modules<5>
@anchor{whatsnew/3 9 pprint}@anchor{cf2}
@subsubsection pprint


@ref{b3,,pprint} can now pretty-print @ref{6ea,,types.SimpleNamespace}.
(Contributed by Carl Bordum Hansen in bpo-37376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37376}.)

@node pydoc<2>,random<3>,pprint<3>,Improved Modules<5>
@anchor{whatsnew/3 9 pydoc}@anchor{cf3}
@subsubsection pydoc


The documentation string is now shown not only for class, function,
method etc, but for any object that has its own @ref{cf4,,__doc__}
attribute.
(Contributed by Serhiy Storchaka in bpo-40257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40257}.)

@node random<3>,signal,pydoc<2>,Improved Modules<5>
@anchor{whatsnew/3 9 random}@anchor{cf5}
@subsubsection random


Added a new @ref{cf6,,random.Random.randbytes()} method: generate random bytes.
(Contributed by Victor Stinner in bpo-40286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40286}.)

@node signal,smtplib,random<3>,Improved Modules<5>
@anchor{whatsnew/3 9 signal}@anchor{cf7}
@subsubsection signal


Exposed the Linux-specific @ref{cf8,,signal.pidfd_send_signal()} for sending to
signals to a process using a file descriptor instead of a pid. (bpo-38712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38712})

@node smtplib,socket<5>,signal,Improved Modules<5>
@anchor{whatsnew/3 9 smtplib}@anchor{cf9}
@subsubsection smtplib


@ref{cfa,,SMTP} and @ref{cfb,,SMTP_SSL} now raise a @ref{277,,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{cfc,,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<5>,time<3>,smtplib,Improved Modules<5>
@anchor{whatsnew/3 9 socket}@anchor{cfd}
@subsubsection socket


The @ref{d4,,socket} module now exports the @ref{cfe,,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{cff,,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}.)

The socket module now has the @ref{d00,,socket.send_fds()} and
@ref{d01,,socket.recv_fds()} functions. (Contributed by Joannah Nanjekye, Shinya
Okano and Victor Stinner in bpo-28724@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28724}.)

@node time<3>,sys<7>,socket<5>,Improved Modules<5>
@anchor{whatsnew/3 9 time}@anchor{d02}
@subsubsection time


On AIX, @ref{d03,,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<7>,tracemalloc,time<3>,Improved Modules<5>
@anchor{whatsnew/3 9 sys}@anchor{d04}
@subsubsection sys


Added a new @ref{2a9,,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{d05,,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<9>,sys<7>,Improved Modules<5>
@anchor{whatsnew/3 9 tracemalloc}@anchor{d06}
@subsubsection tracemalloc


Added @ref{d07,,tracemalloc.reset_peak()} to set the peak size of traced memory
blocks to the current size, to measure the peak of specific pieces of code.
(Contributed by Huon Wilson in bpo-40630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40630}.)

@node typing<9>,unicodedata<6>,tracemalloc,Improved Modules<5>
@anchor{whatsnew/3 9 typing}@anchor{d08}
@subsubsection typing


@geindex Python Enhancement Proposals; PEP 593
PEP 593@footnote{https://peps.python.org/pep-0593/} introduced an @ref{d09,,typing.Annotated} type to decorate existing
types with context-specific metadata and new @code{include_extras} parameter to
@ref{a9e,,typing.get_type_hints()} to access the metadata at runtime. (Contributed
by Till Varoquaux and Konstantin Kashin.)

@node unicodedata<6>,venv<4>,typing<9>,Improved Modules<5>
@anchor{whatsnew/3 9 unicodedata}@anchor{d0a}
@subsubsection unicodedata


The Unicode database has been updated to version 13.0.0. (bpo-39926@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39926}).

@node venv<4>,xml<4>,unicodedata<6>,Improved Modules<5>
@anchor{whatsnew/3 9 venv}@anchor{d0b}
@subsubsection venv


The activation scripts provided by @ref{11a,,venv} now all specify their prompt
customization consistently by always using the value specified by
@code{__VENV_PROMPT__}. Previously some scripts unconditionally used
@code{__VENV_PROMPT__}, others only if it happened to be set (which was the default
case), and one used @code{__VENV_NAME__} instead.
(Contributed by Brett Cannon in bpo-37663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37663}.)

@node xml<4>,,venv<4>,Improved Modules<5>
@anchor{whatsnew/3 9 xml}@anchor{d0c}
@subsubsection xml


White space characters within attributes are now preserved when serializing
@ref{12e,,xml.etree.ElementTree} to XML file. EOLNs are no longer normalized
to «n». This is the result of discussion about how to interpret
section 2.11 of XML spec.
(Contributed by Mefistotelis in bpo-39011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39011}.)

@node Optimizations<8>,Deprecated<10>,Improved Modules<5>,What’s New In Python 3 9
@anchor{whatsnew/3 9 optimizations}@anchor{d0d}
@subsection Optimizations



@itemize *

@item 
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}.  For example:

@quotation

sums = [s for s in [0] for x in data for s in [s + x]]
@end quotation

Unlike the @code{:=} operator this idiom does not leak a variable to the
outer scope.

(Contributed by Serhiy Storchaka in bpo-32856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32856}.)

@item 
Optimized 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.
(Contributed by Victor Stinner in bpo-40010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40010}.)

@item 
Optimized the @ref{df,,subprocess} module on FreeBSD using @code{closefrom()}.
(Contributed by Ed Maste, Conrad Meyer, Kyle Evans, Kubilay Kocak and Victor
Stinner in bpo-38061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38061}.)

@item 
@ref{d0e,,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{d0f,,range}, @ref{1ce,,tuple}, @ref{42b,,set},
@ref{9d4,,frozenset}, @ref{4d9,,list}, @ref{188,,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 
Optimized @code{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ù in bpo-8425@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8425}.)

@item 
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.
(Contributed by Tim Peters in bpo-37257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37257}.)

@item 
@ref{d10,,floor division} of float operation now has a better performance. Also
the message of @ref{d11,,ZeroDivisionError} for this operation is updated.
(Contributed by Donghee Na in bpo-39434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39434}.)

@item 
Decoding short ASCII strings with UTF-8 and ascii codecs is now about
15% faster.  (Contributed by Inada Naoki in bpo-37348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37348}.)
@end itemize

Here’s a summary of performance improvements from Python 3.4 through 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 Deprecated<10>,Removed<10>,Optimizations<8>,What’s New In Python 3 9
@anchor{whatsnew/3 9 deprecated}@anchor{d12}
@subsection Deprecated



@itemize *

@item 
The distutils @code{bdist_msi} command is now deprecated, use
@code{bdist_wheel} (wheel packages) instead.
(Contributed by Hugo van Kemenade in bpo-39586@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39586}.)

@item 
Currently @ref{d13,,math.factorial()} accepts @ref{327,,float} instances with
non-negative integer values (like @code{5.0}).  It raises a @ref{277,,ValueError}
for non-integral and negative floats.  It is now deprecated.  In future
Python versions it will raise a @ref{291,,TypeError} for all floats.
(Contributed by Serhiy Storchaka in 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{9,,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 
Using @ref{440,,NotImplemented} in a boolean context has been deprecated,
as it is almost exclusively the result of incorrect rich comparator
implementations. It will be made a @ref{291,,TypeError} in a future version
of Python.
(Contributed by Josh Rosenberg in bpo-35712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35712}.)

@item 
The @ref{c0,,random} module currently accepts any hashable type as a
possible seed value.  Unfortunately, some of those types are not
guaranteed to have a deterministic hash value.  After Python 3.9,
the module will restrict its seeds to @ref{a65,,None}, @ref{326,,int},
@ref{327,,float}, @ref{1df,,str}, @ref{1c7,,bytes}, and @ref{1c6,,bytearray}.

@item 
Opening the @ref{849,,GzipFile} file for writing without specifying
the `mode' argument is deprecated.  In future Python versions it will always
be opened for reading by default.  Specify the `mode' argument for opening
it for writing and silencing a warning.
(Contributed by Serhiy Storchaka in 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 
The explicit passing of coroutine objects to @ref{891,,asyncio.wait()} has been
deprecated and will be removed in version 3.11.
(Contributed by Yury Selivanov and Kyle Stanley in 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{11,,binascii} functions are now deprecated:


@itemize *

@item 
@code{b2a_hqx()}, @code{a2b_hqx()}

@item 
@code{rlecode_hqx()}, @code{rledecode_hqx()}
@end itemize

(Contributed by Victor Stinner in bpo-39353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39353}.)

@item 
@ref{9,,ast} classes @code{slice}, @code{Index} and @code{ExtSlice} are considered deprecated
and will be removed in future Python versions.  @code{value} itself should be
used instead of @code{Index(value)}.  @code{Tuple(slices, Load())} should be
used instead of @code{ExtSlice(slices)}.
(Contributed by Serhiy Storchaka in bpo-34822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34822}.)

@item 
@ref{9,,ast} classes @code{Suite}, @code{Param}, @code{AugLoad} and @code{AugStore}
are considered deprecated and will be removed in future Python versions.
They were not generated by the parser and not accepted by the code
generator in Python 3.
(Contributed by Batuhan Taskaya in bpo-39639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39639} and bpo-39969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39969}
and Serhiy Storchaka in 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{411,,GIL} is initialized
by @ref{673,,Py_Initialize()} since Python 3.7.
(Contributed by Victor Stinner in bpo-39877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39877}.)

@item 
Passing @code{None} as the first argument to the @ref{949,,shlex.split()} function
has been deprecated.  (Contributed by Zackery Spytz in 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{c9b,,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 
The `random' parameter of @ref{b2c,,random.shuffle()} has been deprecated.
(Contributed by Raymond Hettinger in bpo-40465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40465})
@end itemize

@node Removed<10>,Porting to Python 3 9,Deprecated<10>,What’s New In Python 3 9
@anchor{whatsnew/3 9 removed}@anchor{d14}@anchor{whatsnew/3 9 removed-in-python-39}@anchor{c9d}
@subsection Removed



@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 
@ref{6c5,,array.array}: @code{tostring()} and @code{fromstring()} methods have been
removed. They were aliases to @code{tobytes()} and @code{frombytes()}, deprecated
since Python 3.2.
(Contributed by Victor Stinner in bpo-38916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38916}.)

@item 
The undocumented @code{sys.callstats()} function has been removed. Since Python
3.7, it was deprecated and always returned @ref{a65,,None}. It required a special
build option @code{CALL_PROFILE} which was already removed in Python 3.7.
(Contributed by Victor Stinner in bpo-37414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37414}.)

@item 
The @code{sys.getcheckinterval()} and @code{sys.setcheckinterval()} functions have
been removed. They were deprecated since Python 3.2. Use
@ref{d15,,sys.getswitchinterval()} and @ref{d16,,sys.setswitchinterval()} instead.
(Contributed by Victor Stinner in bpo-37392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37392}.)

@item 
The C function @code{PyImport_Cleanup()} has been removed. It was documented as:
«Empty the module table.  For internal use only.»
(Contributed by Victor Stinner in bpo-36710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36710}.)

@item 
@code{_dummy_thread} and @code{dummy_threading} modules have been removed. These
modules were deprecated since Python 3.7 which requires threading support.
(Contributed by Victor Stinner in 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{d17,,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{420,,threading.Thread}
has been removed. It was deprecated since Python 3.8.
Use @ref{d18,,is_alive()} instead.
(Contributed by Donghee Na in bpo-37804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37804}.)

@item 
Methods @code{getchildren()} and @code{getiterator()} of classes
@ref{d19,,ElementTree} and
@ref{343,,Element} in the @ref{12e,,ElementTree}
module have been removed.  They were deprecated in Python 3.2.
Use @code{iter(x)} or @code{list(x)} instead of @code{x.getchildren()} and
@code{x.iter()} or @code{list(x.iter())} instead of @code{x.getiterator()}.
(Contributed by Serhiy Storchaka in bpo-36543@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36543}.)

@item 
The old @ref{b0,,plistlib} API has been removed, it was deprecated since Python
3.4. Use the @ref{d1a,,load()}, @ref{d1b,,loads()}, @ref{d1c,,dump()}, and
@ref{d1d,,dumps()} functions. Additionally, the `use_builtin_types' parameter was
removed, standard @ref{1c7,,bytes} objects are always used instead.
(Contributed by Jon Janzen in bpo-36409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36409}.)

@item 
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.
(Contributed by Joannah Nanjekye in bpo-15088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15088})

@item 
@code{base64.encodestring()} and @code{base64.decodestring()}, aliases deprecated
since Python 3.1, have been removed: use @ref{d1e,,base64.encodebytes()} and
@ref{d1f,,base64.decodebytes()} instead.
(Contributed by Victor Stinner in bpo-39351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39351}.)

@item 
@code{fractions.gcd()} function has been removed, it was deprecated since Python
3.5 (bpo-22486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22486}): use @ref{cdf,,math.gcd()} instead.
(Contributed by Victor Stinner in bpo-39350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39350}.)

@item 
The `buffering' parameter of @ref{c3d,,bz2.BZ2File} has been removed. Since
Python 3.0, it was ignored and using it emitted a @ref{2c9,,DeprecationWarning}.
Pass an open file object to control how the file is opened.
(Contributed by Victor Stinner in bpo-39357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39357}.)

@item 
The `encoding' parameter of @ref{22f,,json.loads()} has been removed.
As of Python 3.1, it was deprecated and ignored; using it has emitted a
@ref{2c9,,DeprecationWarning} since Python 3.8.
(Contributed by Inada Naoki in bpo-39377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39377})

@item 
@code{with (await asyncio.lock):} and @code{with (yield from asyncio.lock):} statements are
not longer supported, use @code{async with lock} instead.  The same is correct for
@code{asyncio.Condition} and @code{asyncio.Semaphore}.
(Contributed by Andrew Svetlov in 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{60b,,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 
The @code{_field_types} attribute of the @ref{2e4,,typing.NamedTuple} class
has been removed.  It was deprecated since Python 3.8.  Use
the @code{__annotations__} attribute instead.
(Contributed by Serhiy Storchaka in 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{88f,,asyncio.current_task()} and @ref{d20,,asyncio.all_tasks()} instead.
(Contributed by Rémi Lapeyre in bpo-40967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40967})

@item 
The @code{unescape()} method in the @ref{c4d,,html.parser.HTMLParser} class
has been removed (it was deprecated since Python 3.4).  @ref{d21,,html.unescape()}
should be used for converting character references to the corresponding
unicode characters.
@end itemize

@node Porting to Python 3 9,Build Changes<5>,Removed<10>,What’s New In Python 3 9
@anchor{whatsnew/3 9 porting-to-python-3-9}@anchor{d22}
@subsection Porting to Python 3.9


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

@menu
* Changes in the Python API: Changes in the Python API<5>. 
* Changes in the C API: Changes in the C API<4>. 
* CPython bytecode changes: CPython bytecode changes<5>. 

@end menu

@node Changes in the Python API<5>,Changes in the C API<4>,,Porting to Python 3 9
@anchor{whatsnew/3 9 changes-in-the-python-api}@anchor{d23}
@subsubsection Changes in the Python API



@itemize *

@item 
@ref{ca6,,__import__()} and @ref{cd9,,importlib.util.resolve_name()} now raise
@ref{1bd,,ImportError} where it previously raised @ref{277,,ValueError}. Callers
catching the specific exception type and supporting both Python 3.9 and
earlier versions will need to catch both using @code{except (ImportError, ValueError):}.

@item 
The @ref{11a,,venv} activation scripts no longer special-case when
@code{__VENV_PROMPT__} is set to @code{""}.

@item 
The @ref{d24,,select.epoll.unregister()} method no longer ignores the
@ref{d25,,EBADF} error.
(Contributed by Victor Stinner in bpo-39239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39239}.)

@item 
The `compresslevel' parameter of @ref{c3d,,bz2.BZ2File} became keyword-only,
since the `buffering' parameter has been removed.
(Contributed by Victor Stinner in bpo-39357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39357}.)

@item 
Simplified AST for subscription. Simple indices will be represented by
their value, extended slices will be represented as tuples.
@code{Index(value)} will return a @code{value} itself, @code{ExtSlice(slices)}
will return @code{Tuple(slices, Load())}.
(Contributed by Serhiy Storchaka in bpo-34822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34822}.)

@item 
The @ref{7a,,importlib} module now ignores the 
@geindex PYTHONCASEOK
@geindex μεταβλητή περιβάλλοντος; PYTHONCASEOK
@ref{d26,,PYTHONCASEOK}
environment variable when the @ref{d27,,-E} or @ref{d28,,-I} command line
options are being used.

@item 
The `encoding' parameter has been added to the classes @ref{cca,,ftplib.FTP} and
@ref{ccb,,ftplib.FTP_TLS} as a keyword-only parameter, and the default encoding
is changed from Latin-1 to UTF-8 to follow 
@geindex RFC; RFC 2640
RFC 2640@footnote{https://datatracker.ietf.org/doc/html/rfc2640.html}.

@item 
@ref{cb8,,asyncio.loop.shutdown_default_executor()} has been added to
@ref{d29,,AbstractEventLoop}, meaning alternative event loops that
inherit from it should have this method defined.
(Contributed by Kyle Stanley in bpo-34037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34037}.)

@item 
The constant values of future flags in the @ref{0,,__future__} module
is 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 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 
The @ref{d2a,,logging.getLogger()} API now returns the root logger when passed
the name @code{'root'}, whereas previously it returned a non-root logger named
@code{'root'}. This could affect cases where user code explicitly wants a
non-root logger named @code{'root'}, or instantiates a logger using
@code{logging.getLogger(__name__)} in some top-level module called @code{'root.py'}.
(Contributed by Vinay Sajip in bpo-37742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37742}.)

@item 
Division handling of @ref{8b6,,PurePath} now returns @ref{440,,NotImplemented}
instead of raising a @ref{291,,TypeError} when passed something other than an
instance of @code{str} or @code{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{83,,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{d2b,,socket.inet_aton()} treats leading zeros as octal
notatation. glibc implementation of modern @ref{d2c,,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{d2d,,codecs.lookup()} now normalizes the encoding name the same way as
@ref{313,,encodings.normalize_encoding()}, except that @code{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 Changes in the C API<4>,CPython bytecode changes<5>,Changes in the Python API<5>,Porting to Python 3 9
@anchor{whatsnew/3 9 changes-in-the-c-api}@anchor{d2e}
@subsubsection Changes in the C API



@itemize *

@item 
Instances of @ref{d2f,,heap-allocated types} (such as those created with
@ref{38e,,PyType_FromSpec()} and similar APIs) hold a reference to their type
object since Python 3.8. As indicated in the «Changes in the C API» of Python
3.8, for the vast majority of cases, there should be no side effect but for
types that have a custom @ref{36b,,tp_traverse} function,
ensure that all custom @code{tp_traverse} functions of heap-allocated types
visit the object’s type.

@quotation

Example:

@example
int
foo_traverse(PyObject *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

If your traverse function delegates to @code{tp_traverse} of its base class
(or another type), ensure that @code{Py_TYPE(self)} is visited only once.
Note that only @ref{d2f,,heap type} are expected to visit the type
in @code{tp_traverse}.

@quotation

For example, if your @code{tp_traverse} function includes:

@example
base->tp_traverse(self, visit, arg)
@end example

then add:

@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

(See bpo-35810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35810} and bpo-40217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40217} for more information.)

@item 
The functions @code{PyEval_CallObject}, @code{PyEval_CallFunction},
@code{PyEval_CallMethod} and @code{PyEval_CallObjectWithKeywords} are deprecated.
Use @ref{82f,,PyObject_Call()} and its variants instead.
(See more details in bpo-29548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29548}.)
@end itemize

@node CPython bytecode changes<5>,,Changes in the C API<4>,Porting to Python 3 9
@anchor{whatsnew/3 9 cpython-bytecode-changes}@anchor{d30}
@subsubsection CPython bytecode changes



@itemize *

@item 
The @code{LOAD_ASSERTION_ERROR} opcode was added for handling the
@ref{d31,,assert} statement. Previously, the assert statement would not work
correctly if the @ref{a97,,AssertionError} exception was being shadowed.
(Contributed by Zackery Spytz in bpo-34880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34880}.)

@item 
The @ref{d32,,COMPARE_OP} opcode was split into four distinct instructions:


@itemize *

@item 
@code{COMPARE_OP} for rich comparisons

@item 
@code{IS_OP} for “is” and “is not” tests

@item 
@code{CONTAINS_OP} for “in” and “not in” tests

@item 
@code{JUMP_IF_NOT_EXC_MATCH} for checking exceptions in “try-except”
statements.
@end itemize

(Contributed by Mark Shannon in bpo-39156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39156}.)
@end itemize

@node Build Changes<5>,C API Changes<5>,Porting to Python 3 9,What’s New In Python 3 9
@anchor{whatsnew/3 9 build-changes}@anchor{d33}
@subsection Build Changes



@itemize *

@item 
Added @code{--with-platlibdir} option to the @code{configure} script: name of the
platform-specific library directory, stored in the new @ref{2a9,,sys.platlibdir}
attribute. See @code{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 
The @code{COUNT_ALLOCS} special build macro has been removed.
(Contributed by Victor Stinner in 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 
On non-Windows platforms, creating @code{bdist_wininst} installers is now
officially unsupported.  (See bpo-10945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10945} for more details.)

@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{d34,,--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 can now be built for Windows 10 ARM64.
(Contributed by Steve Dower in bpo-33125@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33125}.)

@item 
Some individual tests are now skipped when @code{--pgo} is used.  The tests
in question increased the PGO task time significantly and likely
didn’t help improve optimization of the final executable. 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
@code{./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.
(See bpo-36044@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36044} and bpo-37707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37707} for more details.)
@end itemize

@node C API Changes<5>,Notable changes in Python 3 9 1,Build Changes<5>,What’s New In Python 3 9
@anchor{whatsnew/3 9 c-api-changes}@anchor{d35}
@subsection C API Changes


@menu
* New Features: New Features<10>. 
* Porting to Python 3.9: Porting to Python 3 9<2>. 
* Removed: Removed<11>. 

@end menu

@node New Features<10>,Porting to Python 3 9<2>,,C API Changes<5>
@anchor{whatsnew/3 9 id1}@anchor{d36}
@subsubsection New Features



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 573
PEP 573@footnote{https://peps.python.org/pep-0573/}: Added @ref{390,,PyType_FromModuleAndSpec()} to associate
a module with a class; @ref{d37,,PyType_GetModule()} and
@ref{d38,,PyType_GetModuleState()} to retrieve the module and its state; and
@ref{b46,,PyCMethod} and @ref{d39,,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 
Added @ref{b69,,PyFrame_GetCode()} function: get a frame code.
Added @ref{b65,,PyFrame_GetBack()} function: get the frame next outer frame.
(Contributed by Victor Stinner in bpo-40421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40421}.)

@item 
Added @ref{b6a,,PyFrame_GetLineNumber()} to the limited C API.
(Contributed by Victor Stinner in bpo-40421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40421}.)

@item 
Added @ref{d3a,,PyThreadState_GetInterpreter()} and
@ref{83b,,PyInterpreterState_Get()} functions to get the interpreter.
Added @ref{b6d,,PyThreadState_GetFrame()} function to get the current frame of a
Python thread state.
Added @ref{d3b,,PyThreadState_GetID()} function: get the unique identifier of a
Python thread state.
(Contributed by Victor Stinner in bpo-39947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39947}.)

@item 
Added a new public @ref{82e,,PyObject_CallNoArgs()} function to the C API, which
calls a callable Python object without any arguments. It is the most efficient
way to call a callable Python object without any argument.
(Contributed by Victor Stinner in bpo-37194@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37194}.)

@item 
Changes in the limited C API (if @code{Py_LIMITED_API} macro is defined):


@itemize *

@item 
Provide @ref{5fe,,Py_EnterRecursiveCall()} and @ref{d3c,,Py_LeaveRecursiveCall()}
as regular functions for the limited API. Previously, there were defined as
macros, but these macros didn’t compile with the limited C API which cannot
access @code{PyThreadState.recursion_depth} field (the structure is opaque in
the limited C API).

@item 
@code{PyObject_INIT()} and @code{PyObject_INIT_VAR()} become regular «opaque»
function to hide implementation details.
@end itemize

(Contributed by Victor Stinner in bpo-38644@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38644} and bpo-39542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39542}.)

@item 
The @ref{d3d,,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 
Added the functions @ref{d3e,,PyObject_GC_IsTracked()} and
@ref{d3f,,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.
(Contributed by Pablo Galindo Salgado in 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 
Added @ref{d40,,PyObject_CallOneArg()} for calling an object with one
positional argument
(Patch by Jeroen Demeyer in bpo-37483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37483}.)
@end itemize

@node Porting to Python 3 9<2>,Removed<11>,New Features<10>,C API Changes<5>
@anchor{whatsnew/3 9 id2}@anchor{d41}
@subsubsection Porting to Python 3.9



@itemize *

@item 
@code{PyInterpreterState.eval_frame} (
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/}) now requires a new mandatory
`tstate' parameter (@code{PyThreadState*}).
(Contributed by Victor Stinner in bpo-38500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38500}.)

@item 
Extension modules: @ref{d42,,m_traverse},
@ref{d43,,m_clear} and @ref{d44,,m_free}
functions of @ref{d45,,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{d46,,Py_mod_exec} function). More precisely, these functions are not called
if @ref{d47,,m_size} is greater than 0 and the module state (as
returned by @ref{d48,,PyModule_GetState()}) is @code{NULL}.

Extension modules without module state (@code{m_size <= 0}) are not affected.

@item 
If @ref{d49,,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.
(Contributed by Victor Stinner in bpo-39984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39984}.)

@item 
The Windows registry is no longer used to initialize @ref{194,,sys.path} when
the @code{-E} option is used (if @ref{61e,,PyConfig.use_environment} is set to
@code{0}). This is significant when embedding Python on Windows.
(Contributed by Zackery Spytz in bpo-8901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8901}.)

@item 
The global variable @ref{d4a,,PyStructSequence_UnnamedField} is now a constant
and refers to a constant string.
(Contributed by Serhiy Storchaka in 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 
The @ref{d4b,,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.
(Contributed by Victor Stinner in bpo-39882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39882}.)

@item 
The vectorcall protocol now requires that the caller passes only strings as
keyword names. (See bpo-37540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37540} for more information.)

@item 
Implementation details of a number of macros and functions are now hidden:


@itemize *

@item 
@ref{d4c,,PyObject_IS_GC()} macro was converted to a function.

@item 
The @code{PyObject_NEW()} macro becomes an alias to the
@ref{d4d,,PyObject_New} macro, and the @code{PyObject_NEW_VAR()} macro
becomes an alias to the @ref{d4e,,PyObject_NewVar} macro. They no longer
access directly the @ref{d4f,,PyTypeObject.tp_basicsize} member.

@item 
@code{PyObject_GET_WEAKREFS_LISTPTR()} macro was converted to a function:
the macro accessed directly the @ref{d50,,PyTypeObject.tp_weaklistoffset}
member.

@item 
@ref{82b,,PyObject_CheckBuffer()} macro was converted to a function: the macro
accessed directly the @ref{d51,,PyTypeObject.tp_as_buffer} member.

@item 
@ref{d52,,PyIndex_Check()} is now always declared as an opaque function to hide
implementation details: removed the @code{PyIndex_Check()} macro. The macro accessed
directly the @ref{d53,,PyTypeObject.tp_as_number} member.
@end itemize

(See bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170} for more details.)
@end itemize

@node Removed<11>,,Porting to Python 3 9<2>,C API Changes<5>
@anchor{whatsnew/3 9 id3}@anchor{d54}
@subsubsection Removed



@itemize *

@item 
Excluded @code{PyFPE_START_PROTECT()} and @code{PyFPE_END_PROTECT()} macros of
@code{pyfpe.h} from the limited C API.
(Contributed by Victor Stinner in bpo-38835@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38835}.)

@item 
The @code{tp_print} slot of @ref{d55,,PyTypeObject} has been removed.
It was used for printing objects to files in Python 2.7 and before. Since
Python 3.0, it has been ignored and unused.
(Contributed by Jeroen Demeyer in bpo-36974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36974}.)

@item 
Changes in the limited C API (if @code{Py_LIMITED_API} macro is defined):


@itemize *

@item 
Excluded the following functions from the limited C API:


@itemize *

@item 
@code{PyThreadState_DeleteCurrent()}
(Contributed by Joannah Nanjekye in 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 
The trashcan mechanism which never worked in the limited C API.

@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 
Moved following functions and definitions to the internal C API:


@itemize *

@item 
@code{_PyDebug_PrintTotalRefs()}

@item 
@code{_Py_PrintReferences()}

@item 
@code{_Py_PrintReferenceAddresses()}

@item 
@code{_Py_tracemalloc_config}

@item 
@code{_Py_AddToAllObjects()} (specific to @code{Py_TRACE_REFS} build)
@end itemize
@end itemize

(Contributed by Victor Stinner in bpo-38644@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38644} and bpo-39542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39542}.)

@item 
Removed @code{_PyRuntime.getframe} hook and removed @code{_PyThreadState_GetFrame}
macro which was an alias to @code{_PyRuntime.getframe}. They were only exposed
by the internal C API. Removed also @code{PyThreadFrameGetter} type.
(Contributed by Victor Stinner in bpo-39946@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39946}.)

@item 
Removed the following functions from the C API. Call @ref{d56,,PyGC_Collect()}
explicitly to clear all free lists.
(Contributed by Inada Naoki and Victor Stinner in bpo-37340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37340},
bpo-38896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38896} and 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()} and @code{PyCFunction_ClearFreeList()}:
the free lists of bound method objects have been removed.

@item 
@code{PySet_ClearFreeList()}: the set free list has been removed
in Python 3.4.

@item 
@code{PyTuple_ClearFreeList()}

@item 
@code{PyUnicode_ClearFreeList()}: the Unicode free list has been removed in
Python 3.3.
@end itemize

@item 
Removed @code{_PyUnicode_ClearStaticStrings()} function.
(Contributed by Victor Stinner in bpo-39465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39465}.)

@item 
Removed @code{Py_UNICODE_MATCH}. It has been deprecated by 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/}, and
broken since Python 3.3. The @ref{c8b,,PyUnicode_Tailmatch()} function can be
used instead.
(Contributed by Inada Naoki in bpo-36346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36346}.)

@item 
Cleaned 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}.
(Contributed by Pablo Galindo Salgado in bpo-39372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39372}.)
@end itemize

@node Notable changes in Python 3 9 1,Notable changes in Python 3 9 2,C API Changes<5>,What’s New In Python 3 9
@anchor{whatsnew/3 9 notable-changes-in-python-3-9-1}@anchor{d57}
@subsection Notable changes in Python 3.9.1


@menu
* typing: typing<10>. 
* macOS 11.0 (Big Sur) and Apple Silicon Mac support: macOS 11 0 Big Sur and Apple Silicon Mac support. 

@end menu

@node typing<10>,macOS 11 0 Big Sur and Apple Silicon Mac support,,Notable changes in Python 3 9 1
@anchor{whatsnew/3 9 id4}@anchor{d58}
@subsubsection typing


The behavior of @ref{c2d,,typing.Literal} was changed to conform with 
@geindex Python Enhancement Proposals; PEP 586
PEP 586@footnote{https://peps.python.org/pep-0586/}
and to match the behavior of static type checkers specified in the PEP.


@enumerate 

@item 
@code{Literal} now de-duplicates parameters.

@item 
Equality comparisons between @code{Literal} objects are now order independent.

@item 
@code{Literal} comparisons now respect types.  For example,
@code{Literal[0] == Literal[False]} previously evaluated to @code{True}.  It is
now @code{False}.  To support this change, the internally used type cache now
supports differentiating types.

@item 
@code{Literal} objects will now raise a @ref{291,,TypeError} exception during
equality comparisons if any of their parameters are not @ref{183,,hashable}.
Note that declaring @code{Literal} with mutable parameters will not throw
an error:

@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

(Contributed by Yurii Karabas in bpo-42345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42345}.)

@node macOS 11 0 Big Sur and Apple Silicon Mac support,,typing<10>,Notable changes in Python 3 9 1
@anchor{whatsnew/3 9 macos-11-0-big-sur-and-apple-silicon-mac-support}@anchor{d59}
@subsubsection macOS 11.0 (Big Sur) and Apple Silicon Mac support


As of 3.9.1, Python now fully supports building and running on macOS 11.0
(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. Binaries
can also now be built on current versions of macOS to be deployed on a range
of older macOS versions (tested to 10.9) while making some newer OS
functions and options conditionally available based on the operating system
version in use at runtime («weaklinking»).

(Contributed by Ronald Oussoren and Lawrence D’Anna in bpo-41100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41100}.)

@node Notable changes in Python 3 9 2,Notable changes in Python 3 9 3,Notable changes in Python 3 9 1,What’s New In Python 3 9
@anchor{whatsnew/3 9 notable-changes-in-python-3-9-2}@anchor{d5a}
@subsection Notable changes in Python 3.9.2


@menu
* collections.abc: collections abc<3>. 
* urllib.parse: urllib parse<3>. 

@end menu

@node collections abc<3>,urllib parse<3>,,Notable changes in Python 3 9 2
@anchor{whatsnew/3 9 collections-abc}@anchor{d5b}
@subsubsection collections.abc


@ref{bc6,,collections.abc.Callable} generic now flattens type parameters, similar
to what @ref{ba5,,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{bc7,,types.GenericAlias} can now be subclassed, and a subclass will
be returned when subscripting the @code{collections.abc.Callable} type.
Code which accesses the arguments via @ref{315,,typing.get_args()} or @code{__args__}
need to account for this change.  A @ref{2c9,,DeprecationWarning} may be emitted for
invalid forms of parameterizing @code{collections.abc.Callable} which may have
passed silently in Python 3.9.1.  This @code{DeprecationWarning} will
become a @ref{291,,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<3>,,collections abc<3>,Notable changes in Python 3 9 2
@anchor{whatsnew/3 9 urllib-parse}@anchor{d5c}
@subsubsection urllib.parse


Earlier Python versions allowed using both @code{;} and @code{&} as
query parameter separators in @ref{589,,urllib.parse.parse_qs()} and
@ref{588,,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,Notable changes in Python 3 9 2,What’s New In Python 3 9
@anchor{whatsnew/3 9 notable-changes-in-python-3-9-3}@anchor{d5d}
@subsection Notable changes in Python 3.9.3


A security fix alters the @ref{cca,,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,What’s New In Python 3 9
@anchor{whatsnew/3 9 notable-changes-in-python-3-9-5}@anchor{d5e}
@subsection Notable changes in Python 3.9.5


@menu
* urllib.parse: urllib parse<4>. 

@end menu

@node urllib parse<4>,,,Notable changes in Python 3 9 5
@anchor{whatsnew/3 9 id5}@anchor{d5f}
@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{113,,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,What’s New In Python 3 9
@anchor{whatsnew/3 9 notable-security-feature-in-3-9-14}@anchor{d60}
@subsection Notable security feature in 3.9.14


Converting between @ref{326,,int} and @ref{1df,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{277,,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{e2,,sys} APIs. See the @ref{9ec,,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,What’s New In Python 3 9
@anchor{whatsnew/3 9 notable-changes-in-3-9-17}@anchor{d61}
@subsection Notable changes in 3.9.17


@menu
* tarfile: tarfile<5>. 

@end menu

@node tarfile<5>,,,Notable changes in 3 9 17
@anchor{whatsnew/3 9 tarfile}@anchor{d62}
@subsubsection tarfile



@itemize *

@item 
The extraction methods in @ref{e7,,tarfile}, and @ref{882,,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{883,,Extraction filters} for details.
In Python 3.12, use without the `filter' argument will show a
@ref{2c9,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 8,What’s New In Python 3 7,What’s New In Python 3 9,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 8 doc}@anchor{d63}@anchor{whatsnew/3 8 translation-repo}@anchor{d64}@anchor{whatsnew/3 8 what-s-new-in-python-3-8}@anchor{d65}
@section What’s New In 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.

@*Editor: 
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{145,,changelog}.

@c from math import cos, radians
@c from unicodedata import normalize
@c import re
@c import math

@menu
* Summary – Release highlights: Summary – Release highlights<7>. 
* New Features: New Features<11>. 
* Other Language Changes: Other Language Changes<6>. 
* New Modules: New Modules<6>. 
* Improved Modules: Improved Modules<6>. 
* Optimizations: Optimizations<9>. 
* Build and C API Changes:: 
* Deprecated: Deprecated<11>. 
* 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<7>,New Features<11>,,What’s New In Python 3 8
@anchor{whatsnew/3 8 summary-release-highlights}@anchor{d66}
@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 New Features<11>,Other Language Changes<6>,Summary – Release highlights<7>,What’s New In Python 3 8
@anchor{whatsnew/3 8 new-features}@anchor{d67}
@subsection New Features


@menu
* Assignment expressions:: 
* 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 Assignment expressions,Positional-only parameters,,New Features<11>
@anchor{whatsnew/3 8 assignment-expressions}@anchor{d68}
@subsubsection Assignment expressions


There is new syntax @code{:=} that assigns values to variables as part of a larger
expression. It is affectionately known as «the walrus operator» due to
its resemblance to the eyes and tusks of a walrus@footnote{https://en.wikipedia.org/wiki/Walrus#/media/File:Pacific_Walrus_-_Bull_(8247646168).jpg}.

In this example, the assignment expression helps avoid calling
@ref{a1f,,len()} twice:

@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

The operator is also useful with while-loops that compute
a value to test loop termination and then need that same
value again in the body of the loop:

@example
# Loop over fixed length blocks
while (block := f.read(256)) != '@w{'}:
    process(block)
@end example

Another motivating use case arises in list comprehensions where
a value computed in a filtering condition is also needed in
the expression body:

@example
[clean_name.title() for name in names
 if (clean_name := normalize('NFC', name)) in allowed_names]
@end example

Try to limit use of the walrus operator to clean cases that reduce
complexity and improve readability.

See 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/} for a full description.

(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,Assignment expressions,New Features<11>
@anchor{whatsnew/3 8 positional-only-parameters}@anchor{d69}
@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.

In the following example, parameters `a' and `b' are positional-only,
while `c' or `d' can be positional or keyword, and `e' or `f' are
required to be keywords:

@example
def f(a, b, /, c, d, *, e, f):
    print(a, b, c, d, e, f)
@end example

The following is a valid call:

@example
f(10, 20, 30, d=40, e=50, f=60)
@end example

However, these are invalid calls:

@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{d6a,,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{a1f,,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{da,,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{1e,,collections} module:

@example
class Counter(dict):

    def __init__(self, iterable=None, /, **kwds):
        # Note "iterable" is a possible keyword argument
@end example

See 
@geindex Python Enhancement Proposals; PEP 570
PEP 570@footnote{https://peps.python.org/pep-0570/} for a full description.

(Contributed by Pablo Galindo in 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,New Features<11>
@anchor{whatsnew/3 8 parallel-filesystem-cache-for-compiled-bytecode-files}@anchor{d6b}
@subsubsection Parallel filesystem cache for compiled bytecode files


The new 
@geindex PYTHONPYCACHEPREFIX
@geindex μεταβλητή περιβάλλοντος; PYTHONPYCACHEPREFIX
@ref{d6c,,PYTHONPYCACHEPREFIX} setting (also available as
@ref{178,,-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{d6d,,sys.pycache_prefix}
(@ref{a65,,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,New Features<11>
@anchor{whatsnew/3 8 debug-build-uses-the-same-abi-as-release-build}@anchor{d6e}
@subsubsection Debug build uses the same ABI as release build


The ABI of Python @ref{3dc,,debug builds}  is now compatible with
Python release builds. 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. The inverse is not true, as debug builds expose
additional symbols not available in release builds.

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{516,,sys.getobjects()} function and the 
@geindex PYTHONDUMPREFS
@geindex μεταβλητή περιβάλλοντος; PYTHONDUMPREFS
@ref{d6f,,PYTHONDUMPREFS}
environment variable, can be set using the new @ref{828,,./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,New Features<11>
@anchor{whatsnew/3 8 bpo-36817-whatsnew}@anchor{d70}@anchor{whatsnew/3 8 f-strings-support-for-self-documenting-expressions-and-debugging}@anchor{d71}
@subsubsection f-strings support @code{=} for self-documenting expressions and debugging


Added an @code{=} specifier to @ref{858,,f-string}s. An f-string such as
@code{f'@{expr=@}'} will expand to the text of the expression, an equal sign,
then the representation of the evaluated expression.  For example:

@example
>>> import datetime as dt
>>> user = 'eric_idle'
>>> member_since = dt.date(1975, 7, 31)
>>> f'@{user=@} @{member_since=@}'
"user='eric_idle' member_since=datetime.date(1975, 7, 31)"
@end example

The usual @ref{43a,,f-string format specifiers} allow more
control over how the result of the expression is displayed:

@example
>>> delta = dt.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,New Features<11>
@anchor{whatsnew/3 8 pep-578-python-runtime-audit-hooks}@anchor{d72}
@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,New Features<11>
@anchor{whatsnew/3 8 pep-587-python-initialization-configuration}@anchor{d73}
@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{60b,,PyConfig}

@item 
@ref{d74,,PyPreConfig}

@item 
@ref{d75,,PyStatus}

@item 
@ref{d76,,PyWideStringList}
@end itemize

New functions:


@itemize *

@item 
@ref{d77,,PyConfig_Clear()}

@item 
@ref{d78,,PyConfig_InitIsolatedConfig()}

@item 
@ref{d79,,PyConfig_InitPythonConfig()}

@item 
@ref{b6f,,PyConfig_Read()}

@item 
@ref{d7a,,PyConfig_SetArgv()}

@item 
@ref{d7b,,PyConfig_SetBytesArgv()}

@item 
@ref{d7c,,PyConfig_SetBytesString()}

@item 
@ref{d7d,,PyConfig_SetString()}

@item 
@ref{d7e,,PyPreConfig_InitIsolatedConfig()}

@item 
@ref{d7f,,PyPreConfig_InitPythonConfig()}

@item 
@ref{d80,,PyStatus_Error()}

@item 
@ref{d81,,PyStatus_Exception()}

@item 
@ref{d82,,PyStatus_Exit()}

@item 
@ref{d83,,PyStatus_IsError()}

@item 
@ref{d84,,PyStatus_IsExit()}

@item 
@ref{d85,,PyStatus_NoMemory()}

@item 
@ref{d86,,PyStatus_Ok()}

@item 
@ref{d87,,PyWideStringList_Append()}

@item 
@ref{d88,,PyWideStringList_Insert()}

@item 
@ref{d89,,Py_BytesMain()}

@item 
@ref{d8a,,Py_ExitStatusException()}

@item 
@ref{60a,,Py_InitializeFromConfig()}

@item 
@ref{631,,Py_PreInitialize()}

@item 
@ref{d8b,,Py_PreInitializeFromArgs()}

@item 
@ref{d8c,,Py_PreInitializeFromBytesArgs()}

@item 
@ref{d8d,,Py_RunMain()}
@end itemize

This PEP also adds @code{_PyRuntimeState.preconfig} (@ref{d74,,PyPreConfig} type)
and @code{PyInterpreterState.config} (@ref{60b,,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{837,,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,New Features<11>
@anchor{whatsnew/3 8 pep-590-vectorcall-a-fast-calling-protocol-for-cpython}@anchor{d8e}
@subsubsection PEP 590: Vectorcall: a fast calling protocol for CPython


@ref{95b,,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{b5f,,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,New Features<11>
@anchor{whatsnew/3 8 pickle-protocol-5-with-out-of-band-data-buffers}@anchor{d8f}
@subsubsection Pickle protocol 5 with out-of-band data buffers


When @ref{ab,,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{ab,,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 Other Language Changes<6>,New Modules<6>,New Features<11>,What’s New In Python 3 8
@anchor{whatsnew/3 8 other-language-changes}@anchor{d90}
@subsection Other Language Changes



@itemize *

@item 
A @ref{429,,continue} statement was illegal in the @ref{44c,,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{5ef,,bool}, @ref{326,,int}, and @ref{1c3,,fractions.Fraction} types
now have an @ref{d91,,as_integer_ratio()} method like that found in
@ref{327,,float} and @ref{1c2,,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{326,,int}, @ref{327,,float} and @ref{328,,complex} will now
use the @ref{43d,,__index__()} special method, if available and the
corresponding method @ref{43c,,__int__()}, @ref{d92,,__float__()}
or @ref{9de,,__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{c1,,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{c3c,,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{d93,,yield} and
@ref{44b,,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{44a,,SyntaxWarning} with a helpful suggestion.
This improves on just having a @ref{291,,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{48d,,datetime.date} or
@ref{6e7,,datetime.datetime} and @ref{d94,,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 @code{datetime.timedelta} arithmetic, such as
@ref{d95,,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{d96,,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{2e1,,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{abf,,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{441,,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{d97,,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
@ref{d98,,__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 New Modules<6>,Improved Modules<6>,Other Language Changes<6>,What’s New In Python 3 8
@anchor{whatsnew/3 8 new-modules}@anchor{d99}
@subsection New Modules



@itemize *

@item 
The new @ref{7d,,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 Improved Modules<6>,Optimizations<9>,New Modules<6>,What’s New In Python 3 8
@anchor{whatsnew/3 8 improved-modules}@anchor{d9a}
@subsection Improved Modules


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

@end menu

@node ast<7>,asyncio<10>,,Improved Modules<6>
@anchor{whatsnew/3 8 ast}@anchor{d9b}
@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{d9c,,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{1c9,,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{b19,,async} and @ref{432,,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<10>,builtins<2>,ast<7>,Improved Modules<6>
@anchor{whatsnew/3 8 asyncio}@anchor{d9d}
@subsubsection asyncio


@ref{309,,asyncio.run()} has graduated from the provisional to stable API. This
function can be used to execute a @ref{8a2,,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{309,,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{432,,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{6da,,asyncio.CancelledError} now inherits from
@ref{9b9,,BaseException} rather than @ref{d9e,,Exception} and no longer inherits
from @ref{d9f,,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{9fe,,ProactorEventLoop}.
(Contributed by Victor Stinner in bpo-34687@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34687}.)

@ref{9fe,,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{9fe,,ProactorEventLoop} can now be interrupted by
@ref{d96,,KeyboardInterrupt} («CTRL+C»).
(Contributed by Vladimir Matveev in bpo-23057@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23057}.)

Added @ref{da0,,asyncio.Task.get_coro()} for getting the wrapped coroutine
within an @ref{460,,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{462,,asyncio.create_task()} or
the @ref{463,,create_task()} event loop method, or by
calling the @ref{da1,,set_name()} method on the task object. The
task name is visible in the @code{repr()} output of @ref{460,,asyncio.Task} and
can also be retrieved using the @ref{da2,,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{9f9,,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<2>,asyncio<10>,Improved Modules<6>
@anchor{whatsnew/3 8 builtins}@anchor{da3}
@subsubsection builtins


The @ref{1c8,,compile()} built-in has been improved to accept the
@code{ast.PyCF_ALLOW_TOP_LEVEL_AWAIT} flag. With this new flag passed,
@code{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<2>,cProfile,builtins<2>,Improved Modules<6>
@anchor{whatsnew/3 8 collections}@anchor{da4}
@subsubsection collections


The @ref{da5,,_asdict()} method for
@ref{1cf,,collections.namedtuple()} now returns a @ref{188,,dict} instead of a
@ref{9d5,,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<3>,collections<2>,Improved Modules<6>
@anchor{whatsnew/3 8 cprofile}@anchor{da6}
@subsubsection cProfile


The @ref{da7,,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<3>,curses<4>,cProfile,Improved Modules<6>
@anchor{whatsnew/3 8 csv}@anchor{da8}
@subsubsection csv


The @ref{da9,,csv.DictReader} now returns instances of @ref{188,,dict} instead of
a @ref{9d5,,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<4>,ctypes<4>,csv<3>,Improved Modules<6>
@anchor{whatsnew/3 8 curses}@anchor{daa}
@subsubsection curses


Added a new variable holding structured version information for the
underlying ncurses library: @ref{dab,,ncurses_version}.
(Contributed by Serhiy Storchaka in bpo-31680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31680}.)

@node ctypes<4>,datetime<5>,curses<4>,Improved Modules<6>
@anchor{whatsnew/3 8 ctypes}@anchor{dac}
@subsubsection ctypes


On Windows, @ref{dad,,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{dae,,add_dll_directory()}.
(Contributed by Steve Dower in bpo-36085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36085}.)

@node datetime<5>,functools<5>,ctypes<4>,Improved Modules<6>
@anchor{whatsnew/3 8 datetime}@anchor{daf}
@subsubsection datetime


Added new alternate constructors @ref{db0,,datetime.date.fromisocalendar()} and
@ref{db1,,datetime.datetime.fromisocalendar()}, which construct @ref{48d,,date} and
@ref{6e7,,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<5>,gc<6>,datetime<5>,Improved Modules<6>
@anchor{whatsnew/3 8 functools}@anchor{db2}
@subsubsection functools


@ref{db3,,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{94e,,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{21e,,functools.singledispatchmethod()} decorator that converts
methods into @ref{db4,,generic functions} using
@ref{db5,,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<6>,gettext,functools<5>,Improved Modules<6>
@anchor{whatsnew/3 8 gc}@anchor{db6}
@subsubsection gc


@ref{bdd,,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<6>,Improved Modules<6>
@anchor{whatsnew/3 8 gettext}@anchor{db7}
@subsubsection gettext


Added @ref{db8,,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 and idlelib<4>,gettext,Improved Modules<6>
@anchor{whatsnew/3 8 gzip}@anchor{db9}
@subsubsection gzip


Added the `mtime' parameter to @ref{a2d,,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{dba,,BadGzipFile} exception is now raised instead of @ref{53c,,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 and idlelib<4>,inspect<7>,gzip<3>,Improved Modules<6>
@anchor{whatsnew/3 8 idle-and-idlelib}@anchor{dbb}
@subsubsection IDLE and 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}.)

Escape key now closes IDLE completion windows.  (Contributed by Johnny
Najera in 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<7>,io<5>,IDLE and idlelib<4>,Improved Modules<6>
@anchor{whatsnew/3 8 inspect}@anchor{dbc}
@subsubsection inspect


The @ref{22c,,inspect.getdoc()} function can now find docstrings for @code{__slots__}
if that attribute is a @ref{188,,dict} where the values are docstrings.
This provides documentation options similar to what we already have
for @ref{6bb,,property()}, @ref{69a,,classmethod()}, and @ref{666,,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<5>,itertools<5>,inspect<7>,Improved Modules<6>
@anchor{whatsnew/3 8 io}@anchor{dbd}
@subsubsection io


In development mode (@ref{178,,-X} @code{env}) and in @ref{3dc,,debug build}, the
@ref{70a,,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<5>,json tool,io<5>,Improved Modules<6>
@anchor{whatsnew/3 8 itertools}@anchor{dbe}
@subsubsection itertools


The @ref{dbf,,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<5>,Improved Modules<6>
@anchor{whatsnew/3 8 json-tool}@anchor{dc0}
@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<7>,json tool,Improved Modules<6>
@anchor{whatsnew/3 8 logging}@anchor{dc1}
@subsubsection logging


Added a `force' keyword argument to @ref{dc2,,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<7>,mmap<3>,logging<2>,Improved Modules<6>
@anchor{whatsnew/3 8 math}@anchor{dc3}
@subsubsection math


Added new function @ref{dc4,,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{dc5,,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{dc6,,math.prod()}, as analogous function to @ref{881,,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{abe,,math.perm()} and @ref{abd,,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{dc7,,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{dc8,,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{d13,,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<3>,multiprocessing<4>,math<7>,Improved Modules<6>
@anchor{whatsnew/3 8 mmap}@anchor{dc9}
@subsubsection mmap


The @ref{23c,,mmap.mmap} class now has an @ref{dca,,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<4>,os<8>,mmap<3>,Improved Modules<6>
@anchor{whatsnew/3 8 multiprocessing}@anchor{dcb}
@subsubsection multiprocessing


Added new @ref{9d,,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<8>,os path<6>,multiprocessing<4>,Improved Modules<6>
@anchor{whatsnew/3 8 os}@anchor{dcc}
@subsubsection os


Added new function @ref{dae,,add_dll_directory()} on Windows for providing
additional search paths for native dependencies when importing extension
modules or loading DLLs using @ref{2d,,ctypes}.
(Contributed by Steve Dower in bpo-36085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36085}.)

A new @ref{dcd,,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{4f5,,os.stat()} will now traverse anything supported by the
operating system, while @ref{8b1,,os.lstat()} will only open reparse points that
identify as «name surrogates» while others are opened as for @code{os.stat()}.
In all cases, @ref{dce,,os.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 @ref{dcf,,os.stat_result.st_reparse_tag} attribute.

On Windows, @ref{ced,,os.readlink()} is now able to read directory junctions. Note
that @ref{dd0,,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 @code{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<6>,pathlib<11>,os<8>,Improved Modules<6>
@anchor{whatsnew/3 8 os-path}@anchor{dd1}
@subsubsection os.path


@ref{a6,,os.path} functions that return a boolean result like
@ref{dd2,,exists()}, @ref{dd3,,lexists()}, @ref{dd4,,isdir()},
@ref{dd5,,isfile()}, @ref{dd0,,islink()}, and @ref{dd6,,ismount()}
now return @code{False} instead of raising @ref{277,,ValueError} or its subclasses
@ref{a67,,UnicodeEncodeError} and @ref{dd7,,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{dd8,,expanduser()} on Windows now prefers the 
@geindex USERPROFILE
@geindex μεταβλητή περιβάλλοντος; USERPROFILE
@code{USERPROFILE}
environment variable and does not use 
@geindex HOME
@geindex μεταβλητή περιβάλλοντος; 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{dd4,,isdir()} on Windows no longer returns @code{True} for a link to a
non-existent directory.

@ref{241,,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<11>,pickle<3>,os path<6>,Improved Modules<6>
@anchor{whatsnew/3 8 pathlib}@anchor{dd9}
@subsubsection pathlib


@ref{4ee,,pathlib.Path} methods that return a boolean result like
@ref{dda,,exists()}, @ref{73d,,is_dir()},
@ref{73c,,is_file()}, @ref{ddb,,is_mount()},
@ref{ddc,,is_symlink()}, @ref{ddd,,is_block_device()},
@ref{dde,,is_char_device()}, @ref{ddf,,is_fifo()},
@ref{de0,,is_socket()} now return @code{False} instead of raising
@ref{277,,ValueError} or its subclass @ref{a67,,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<3>,plistlib,pathlib<11>,Improved Modules<6>
@anchor{whatsnew/3 8 pickle}@anchor{de1}
@subsubsection pickle


@ref{ab,,pickle} extensions subclassing the C-optimized @ref{de2,,Pickler}
can now override the pickling logic of functions and classes by defining the
special @ref{de3,,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<4>,pickle<3>,Improved Modules<6>
@anchor{whatsnew/3 8 plistlib}@anchor{de4}
@subsubsection plistlib


Added new @ref{de5,,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<4>,py_compile<2>,plistlib,Improved Modules<6>
@anchor{whatsnew/3 8 pprint}@anchor{de6}
@subsubsection pprint


The @ref{b3,,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{de7,,pprint.pp()} that is
like @ref{c01,,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<4>,Improved Modules<6>
@anchor{whatsnew/3 8 py-compile}@anchor{de8}
@subsubsection py_compile


@ref{de9,,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,shutil<4>,py_compile<2>,Improved Modules<6>
@anchor{whatsnew/3 8 shlex}@anchor{dea}
@subsubsection shlex


The new @ref{deb,,shlex.join()} function acts as the inverse of @ref{949,,shlex.split()}.
(Contributed by Bo Bayles in bpo-32102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32102}.)

@node shutil<4>,socket<6>,shlex,Improved Modules<6>
@anchor{whatsnew/3 8 shutil}@anchor{dec}
@subsubsection shutil


@ref{ded,,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{8c3,,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{e7,,tarfile} module.
(Contributed by C.A.M. Gerlach in bpo-30661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30661}.)

@ref{335,,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<6>,ssl<6>,shutil<4>,Improved Modules<6>
@anchor{whatsnew/3 8 socket}@anchor{dee}
@subsubsection socket


Added @ref{def,,create_server()} and @ref{df0,,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{df1,,socket.if_nameindex()}, @ref{df2,,socket.if_nametoindex()}, and
@ref{df3,,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<6>,statistics<4>,socket<6>,Improved Modules<6>
@anchor{whatsnew/3 8 ssl}@anchor{df4}
@subsubsection ssl


Added @ref{df5,,post_handshake_auth} to enable and
@ref{df6,,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<8>,ssl<6>,Improved Modules<6>
@anchor{whatsnew/3 8 statistics}@anchor{df7}
@subsubsection statistics


Added @ref{df8,,statistics.fmean()} as a faster, floating-point variant of
@ref{abf,,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{df9,,statistics.geometric_mean()}
(Contributed by Raymond Hettinger in bpo-27181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27181}.)

Added @ref{dfa,,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{dfb,,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{dfc,,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<8>,tarfile<6>,statistics<4>,Improved Modules<6>
@anchor{whatsnew/3 8 sys}@anchor{dfd}
@subsubsection sys


Add new @ref{70c,,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{44f,,gc.collect()}).
(Contributed by Victor Stinner in bpo-36829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36829}.)

@node tarfile<6>,threading<7>,sys<8>,Improved Modules<6>
@anchor{whatsnew/3 8 tarfile}@anchor{dfe}
@subsubsection tarfile


The @ref{e7,,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<7>,tokenize<3>,tarfile<6>,Improved Modules<6>
@anchor{whatsnew/3 8 threading}@anchor{dff}
@subsubsection threading


Add a new @ref{c23,,threading.excepthook()} function which handles uncaught
@ref{e00,,threading.Thread.run()} exception. It can be overridden to control how
uncaught @code{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{e01,,threading.get_native_id()} function and
a @ref{e02,,native_id}
attribute to the @ref{420,,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
@code{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<3>,tkinter<6>,threading<7>,Improved Modules<6>
@anchor{whatsnew/3 8 tokenize}@anchor{e03}
@subsubsection tokenize


The @ref{104,,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<6>,time<4>,tokenize<3>,Improved Modules<6>
@anchor{whatsnew/3 8 tkinter}@anchor{e04}
@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<11>,tkinter<6>,Improved Modules<6>
@anchor{whatsnew/3 8 time}@anchor{e05}
@subsubsection time


Added new clock @ref{e06,,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<11>,unicodedata<7>,time<4>,Improved Modules<6>
@anchor{whatsnew/3 8 typing}@anchor{e07}
@subsubsection typing


The @ref{10d,,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{290,,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{c2d,,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{76f,,typing.Final} and @ref{a9b,,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{76c,,typing.Protocol} and
@ref{861,,typing.runtime_checkable()}.  Simple ABCs like
@ref{e08,,typing.SupportsInt} are now @code{Protocol} subclasses.

@item 
New protocol class @ref{e09,,typing.SupportsIndex}.

@item 
New functions @ref{314,,typing.get_origin()} and @ref{315,,typing.get_args()}.
@end itemize

@node unicodedata<7>,unittest<8>,typing<11>,Improved Modules<6>
@anchor{whatsnew/3 8 unicodedata}@anchor{e0a}
@subsubsection unicodedata


The @ref{10e,,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{e0b,,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<8>,venv<5>,unicodedata<7>,Improved Modules<6>
@anchor{whatsnew/3 8 unittest}@anchor{e0c}
@subsubsection unittest


Added @ref{e0d,,AsyncMock} to support an asynchronous version of
@ref{e0e,,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{e0f,,addModuleCleanup()} and
@ref{e10,,addClassCleanup()} to unittest to support
cleanups for @ref{e11,,setUpModule()} and
@ref{e12,,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{10f,,unittest} module gained support for coroutines to be used as test cases
with @ref{342,,unittest.IsolatedAsyncioTestCase}.
(Contributed by Andrew Svetlov in bpo-32972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32972}.)

Example:

@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<5>,weakref,unittest<8>,Improved Modules<6>
@anchor{whatsnew/3 8 venv}@anchor{e13}
@subsubsection venv


@ref{11a,,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<5>,venv<5>,Improved Modules<6>
@anchor{whatsnew/3 8 weakref}@anchor{e14}
@subsubsection weakref


The proxy objects returned by @ref{e15,,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<5>,xmlrpc,weakref,Improved Modules<6>
@anchor{whatsnew/3 8 xml}@anchor{e16}
@subsubsection xml


As mitigation against DTD and external entity retrieval, the
@ref{12b,,xml.dom.minidom} and @ref{132,,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{12e,,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{12e,,xml.etree.ElementTree} module provides a new function
@ref{e17,,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{e18,,xml.etree.ElementTree.XMLParser} can
receive namespace declaration events through the new callback methods
@code{start_ns()} and @code{end_ns()}.  Additionally, the
@ref{e19,,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<5>,Improved Modules<6>
@anchor{whatsnew/3 8 xmlrpc}@anchor{e1a}
@subsubsection xmlrpc


@ref{e1b,,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<9>,Build and C API Changes,Improved Modules<6>,What’s New In Python 3 8
@anchor{whatsnew/3 8 optimizations}@anchor{e1c}
@subsection Optimizations



@itemize *

@item 
The @ref{df,,subprocess} module can now use the @ref{731,,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{e1d,,shutil.copyfile()}, @ref{e1e,,shutil.copy()}, @ref{e1f,,shutil.copy2()},
@ref{ded,,shutil.copytree()} and @ref{e20,,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 @code{shutil.copyfile()} uses a bigger default buffer size (1 MiB
instead of 16 KiB) and a @ref{1d2,,memoryview()}-based variant of
@ref{e21,,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{e22,,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{ded,,shutil.copytree()} uses @ref{e23,,os.scandir()} function and all copy
functions depending from it use cached @ref{4f5,,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 @code{os.stat()}
syscalls is reduced by 38% making @code{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{ab,,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{e24,,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{e25,,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{e26,,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{1cf,,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{4d9,,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,Deprecated<11>,Optimizations<9>,What’s New In Python 3 8
@anchor{whatsnew/3 8 build-and-c-api-changes}@anchor{e27}
@subsection Build and C API Changes



@itemize *

@item 
Default @ref{e28,,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{974,,Py_INCREF()}, @ref{975,,Py_DECREF()}

@item 
@ref{e29,,Py_XINCREF()}, @ref{b6e,,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 @ref{e2a,,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{7fb,,PyLong_AsLong()} and argument parsing functions like
@ref{3b1,,PyArg_ParseTuple()} with integer converting format units like @code{'i'}
will now use the @ref{43d,,__index__()} special method instead of
@ref{43c,,__int__()}, if available.  The deprecation warning will be
emitted for objects with the @code{__int__()} method but without the
@code{__index__()} method (like @ref{1c2,,Decimal} and
@ref{1c3,,Fraction}).  @ref{e2b,,PyNumber_Check()} will now return
@code{1} for objects implementing @code{__index__()}.
@ref{e2c,,PyNumber_Long()}, @ref{e2d,,PyNumber_Float()} and
@ref{e2e,,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{e2f,,PyObject_Init()} (and its parallel macro @code{PyObject_INIT})
instead of in @ref{e30,,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{3ac,,sys.executable} to the program full
path (@code{Py_GetProgramFullPath()}) rather than to the program name
(@code{Py_GetProgramName()}).
(Contributed by Victor Stinner in bpo-38234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38234}.)
@end itemize

@node Deprecated<11>,API and Feature Removals,Build and C API Changes,What’s New In Python 3 8
@anchor{whatsnew/3 8 deprecated}@anchor{e31}
@subsection Deprecated



@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{12e,,ElementTree} module now emit a
@ref{2c9,,DeprecationWarning} instead of @ref{c9b,,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{b27,,concurrent.futures.ThreadPoolExecutor} to
@ref{b28,,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{787,,__getitem__()} methods of @ref{b1c,,xml.dom.pulldom.DOMEventStream},
@ref{b1d,,wsgiref.util.FileWrapper} and @ref{b1e,,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{2e4,,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{9,,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{569,,Constant} should be used instead.
(Contributed by Serhiy Storchaka in bpo-32892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32892}.)

@item 
@ref{56a,,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{e32,,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{b18,,decorator} is deprecated and will be
removed in version 3.10.  Instead of @code{@@asyncio.coroutine}, use
@ref{9cf,,async def} instead.
(Contributed by Andrew Svetlov in bpo-36921@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36921}.)

@item 
In @ref{b,,asyncio}, the explicit passing of a `loop' argument has been
deprecated and will be removed in version 3.10 for the following:
@ref{e33,,asyncio.sleep()}, @ref{9f4,,asyncio.gather()}, @ref{e34,,asyncio.shield()},
@ref{9f6,,asyncio.wait_for()}, @ref{891,,asyncio.wait()}, @ref{6cc,,asyncio.as_completed()},
@ref{460,,asyncio.Task}, @ref{e35,,asyncio.Lock}, @ref{56d,,asyncio.Event},
@ref{e36,,asyncio.Condition}, @ref{e37,,asyncio.Semaphore},
@ref{e38,,asyncio.BoundedSemaphore}, @ref{e39,,asyncio.Queue},
@ref{e3a,,asyncio.create_subprocess_exec()}, and
@ref{e3b,,asyncio.create_subprocess_shell()}.

@item 
The explicit passing of coroutine objects to @ref{891,,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{66,,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{NullTranslations.output_charset()} and
@code{NullTranslations.set_output_charset()}, and the `codeset'
parameter of functions @ref{e3c,,translation()} and
@ref{e3d,,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{420,,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{1c2,,Decimal}s,
@ref{1c3,,Fraction}s and any other objects that can be converted
to integers only with a loss (e.g. that have the @ref{43c,,__int__()}
method but do not have the @ref{43d,,__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{4a7,,functools.partialmethod()}, @ref{e3e,,weakref.finalize()},
@ref{e3f,,profile.Profile.runcall()}, @code{cProfile.Profile.runcall()},
@ref{e40,,bdb.Bdb.runcall()}, @ref{e41,,trace.Trace.runfunc()} and
@ref{e42,,curses.wrapper()}.

@item 
`function' in @ref{e43,,unittest.TestCase.addCleanup()}.

@item 
`fn' in the @ref{e44,,submit()} method of
@ref{b27,,concurrent.futures.ThreadPoolExecutor} and
@ref{206,,concurrent.futures.ProcessPoolExecutor}.

@item 
`callback' in @ref{e45,,contextlib.ExitStack.callback()},
@code{contextlib.AsyncExitStack.callback()} and
@ref{e46,,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{e3e,,weakref.finalize()}.
@end itemize

In future releases of Python, they will be @ref{e47,,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,Deprecated<11>,What’s New In Python 3 8
@anchor{whatsnew/3 8 api-and-feature-removals}@anchor{e48}
@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{1e,,collections} was
deprecated, and importing should be done from @ref{1f,,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{585,,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{e49,,time.perf_counter()} or
@ref{e4a,,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{e7,,tarfile} module.
It is not documented and deprecated since Python 3.3.

@item 
The @ref{e18,,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{7a3,,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{e18,,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{d7,,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{bd9,,fileinput.input()} and
@ref{b1e,,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,What’s New In Python 3 8
@anchor{whatsnew/3 8 porting-to-python-3-8}@anchor{e4b}
@subsection Porting to Python 3.8


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

@menu
* Changes in Python behavior:: 
* Changes in the Python API: Changes in the Python API<6>. 
* Changes in the C API: Changes in the C API<5>. 
* CPython bytecode changes: CPython bytecode changes<6>. 
* Demos and Tools: Demos and Tools<2>. 

@end menu

@node Changes in Python behavior,Changes in the Python API<6>,,Porting to Python 3 8
@anchor{whatsnew/3 8 changes-in-python-behavior}@anchor{e4c}
@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{44a,,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{5ef,,bool},
@ref{326,,int}, @ref{327,,float}, @ref{328,,complex} and few classes from
the standard library.  They now inherit @code{__str__()} from @ref{e4d,,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{518,,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{839,,PyEval_RestoreThread()},
@ref{e4e,,Py_END_ALLOW_THREADS()}, and @ref{1a5,,PyGILState_Ensure()}. If this
behavior is not desired, guard the call by checking @code{_Py_IsFinalizing()}
or @ref{e4f,,sys.is_finalizing()}.
(Contributed by Joannah Nanjekye in bpo-36475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36475}.)
@end itemize

@node Changes in the Python API<6>,Changes in the C API<5>,Changes in Python behavior,Porting to Python 3 8
@anchor{whatsnew/3 8 changes-in-the-python-api}@anchor{e50}
@subsubsection Changes in the Python API



@itemize *

@item 
The @ref{e51,,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{6bf,,subprocess.Popen} can now use @ref{731,,os.posix_spawn()} in some cases
for better performance. On Windows Subsystem for Linux and QEMU User
Emulation, the @code{Popen} constructor using
@code{os.posix_spawn()} no longer raises an exception on errors like
«missing program».  Instead the child process fails with a
non-zero @ref{e52,,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{6bf,,subprocess.Popen} is no longer
compatible with subinterpreters. The use of the parameter in a
subinterpreter now raises @ref{30d,,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 @ref{e53,,imaplib.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{585,,os.popen()} instead.
(Contributed by Victor Stinner in bpo-35345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35345}.)

@item 
The @ref{e54,,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{e55,,selection()} method of the
@ref{e56,,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{e57,,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 @ref{e58,,writexml()}, @ref{e59,,toxml()}
and @ref{e5a,,toprettyxml()} methods of
@ref{12b,,xml.dom.minidom} and the @ref{e5b,,write()}
method of @ref{12e,,xml.etree.ElementTree} 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{35,,dbm.dumb} database opened with flags @code{'r'} is now read-only.
@ref{e5c,,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{e18,,XMLParser} will no longer be called and will
emit a @ref{6dd,,RuntimeWarning} instead of a @ref{2c9,,DeprecationWarning}.
Define the @ref{e5d,,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{30d,,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{2c9,,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 @ref{da7,,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{e1d,,shutil.copyfile()}, @ref{e1e,,shutil.copy()}, @ref{e1f,,shutil.copy2()},
@ref{ded,,shutil.copytree()} and @ref{e20,,shutil.move()} use platform-specific
«fast-copy» syscalls (see
@ref{e22,,Platform-dependent efficient copy operations} section).

@item 
@ref{e1d,,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{c90,,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{e5e,,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{12b,,xml.dom.minidom} and @ref{132,,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{34,,dbm} database (@ref{35,,dbm.dumb},
@ref{36,,dbm.gnu} or @ref{37,,dbm.ndbm}) raises @code{error} (@ref{e5f,,dbm.dumb.error},
@ref{e60,,dbm.gnu.error} or @ref{e61,,dbm.ndbm.error}) instead of @ref{7df,,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{569,,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{dd8,,expanduser()} on Windows now prefers the 
@geindex USERPROFILE
@geindex μεταβλητή περιβάλλοντος; USERPROFILE
@code{USERPROFILE}
environment variable and does not use 
@geindex HOME
@geindex μεταβλητή περιβάλλοντος; 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{6da,,asyncio.CancelledError} now inherits from
@ref{9b9,,BaseException} rather than @ref{d9e,,Exception} and no longer inherits
from @ref{d9f,,concurrent.futures.CancelledError}.
(Contributed by Yury Selivanov in bpo-32528@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32528}.)

@item 
The function @ref{9f6,,asyncio.wait_for()} now correctly waits for cancellation
when using an instance of @ref{460,,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{e62,,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{e63,,asyncio.BufferedProtocol} has graduated to the stable API.
@end itemize
@anchor{whatsnew/3 8 bpo-36085-whatsnew}@anchor{e64}

@itemize *

@item 
DLL dependencies for extension modules and DLLs loaded with @ref{2d,,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{dae,,add_dll_directory()} are searched for load-time dependencies.
Specifically, 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; 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 @code{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{2e1,,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 @code{types.CodeType} can be used to make the code
future-proof.

@item 
The parameter @code{digestmod} for @ref{e65,,hmac.new()} no longer uses the MD5 digest
by default.
@end itemize

@node Changes in the C API<5>,CPython bytecode changes<6>,Changes in the Python API<6>,Porting to Python 3 8
@anchor{whatsnew/3 8 changes-in-the-c-api}@anchor{e66}
@subsubsection Changes in the C API



@itemize *

@item 
The @ref{e67,,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{643,,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{3b1,,PyArg_ParseTuple()}, @ref{5ee,,Py_BuildValue()}, @ref{831,,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{601,,Parsing arguments and building values} 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{38e,,PyType_FromSpec()}) hold a reference to their type object.
Increasing the reference count of these type objects has been moved from
@ref{e30,,PyType_GenericAlloc()} to the more low-level functions,
@ref{e2f,,PyObject_Init()} and @code{PyObject_INIT}.
This makes types created through @code{PyType_FromSpec()} behave like
other classes in managed code.

@ref{b5f,,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{974,,Py_INCREF} on the type object after allocating an
instance - if any.
This may happen after calling @ref{d4d,,PyObject_New},
@ref{d4e,,PyObject_NewVar}, @ref{e68,,PyObject_GC_New()},
@ref{e69,,PyObject_GC_NewVar()}, or any other custom allocator that uses
@ref{e2f,,PyObject_Init()} or @code{PyObject_INIT}.

Example:

@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.

Example:

@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{e6a,,Py_DEPRECATED()} macro has been implemented for MSVC.
The macro now must be placed before the symbol name.

Example:

@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{e6b,,PyTypeObject}
exported by a third-party extension module is supposed to have all the
slots expected in the current Python version, including
@ref{e6c,,tp_finalize} (@ref{63a,,Py_TPFLAGS_HAVE_FINALIZE}
is not checked anymore before reading @code{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{e6d,,Χρησιμοποιώντας Python στα 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 CPython bytecode changes<6>,Demos and Tools<2>,Changes in the C API<5>,Porting to Python 3 8
@anchor{whatsnew/3 8 cpython-bytecode-changes}@anchor{e6e}
@subsubsection CPython bytecode changes



@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{428,,break}, @ref{429,,continue} and
@ref{44b,,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{e6f,,END_ASYNC_FOR} for handling exceptions raised
when awaiting a next item in an @ref{e70,,async for} loop.
(Contributed by Serhiy Storchaka in bpo-33041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33041}.)

@item 
The @ref{e71,,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>,,CPython bytecode changes<6>,Porting to Python 3 8
@anchor{whatsnew/3 8 demos-and-tools}@anchor{e72}
@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,What’s New In Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-1}@anchor{e73}
@subsection Notable changes in Python 3.8.1


Due to significant security concerns, the `reuse_address' parameter of
@ref{b1a,,asyncio.loop.create_datagram_endpoint()} is no longer supported. This is
because of the behavior of the socket option @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}.)

@node Notable changes in Python 3 8 2,Notable changes in Python 3 8 3,Notable changes in Python 3 8 1,What’s New In Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-2}@anchor{e74}
@subsection Notable changes in Python 3.8.2


Fixed a regression with the @code{ignore} callback of @ref{ded,,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,What’s New In Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-3}@anchor{e75}
@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,What’s New In Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-8}@anchor{e76}
@subsection Notable changes in Python 3.8.8


Earlier Python versions allowed using both @code{;} and @code{&} as
query parameter separators in @ref{589,,urllib.parse.parse_qs()} and
@ref{588,,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,What’s New In Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-9}@anchor{e77}
@subsection Notable changes in Python 3.8.9


A security fix alters the @ref{cca,,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,What’s New In Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-10}@anchor{e78}
@subsection Notable changes in Python 3.8.10


@menu
* macOS 11.0 (Big Sur) and Apple Silicon Mac support: macOS 11 0 Big Sur and Apple Silicon Mac support<2>. 

@end menu

@node macOS 11 0 Big Sur and Apple Silicon Mac support<2>,,,Notable changes in Python 3 8 10
@anchor{whatsnew/3 8 macos-11-0-big-sur-and-apple-silicon-mac-support}@anchor{e79}
@subsubsection macOS 11.0 (Big Sur) and Apple Silicon Mac support


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,What’s New In Python 3 8
@anchor{whatsnew/3 8 id1}@anchor{e7a}
@subsection Notable changes in Python 3.8.10


@menu
* urllib.parse: urllib parse<5>. 

@end menu

@node urllib parse<5>,,,Notable changes in Python 3 8 10<2>
@anchor{whatsnew/3 8 urllib-parse}@anchor{e7b}
@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{113,,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 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>,What’s New In Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-12}@anchor{e7c}
@subsection Notable changes in Python 3.8.12


@menu
* Changes in the Python API: Changes in the Python API<7>. 

@end menu

@node Changes in the Python API<7>,,,Notable changes in Python 3 8 12
@anchor{whatsnew/3 8 id2}@anchor{e7d}
@subsubsection Changes in the Python API


Starting with Python 3.8.12 the @ref{83,,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{d2b,,socket.inet_aton()} treats leading zeros as octal notation.
glibc implementation of modern @ref{d2c,,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,What’s New In Python 3 8
@anchor{whatsnew/3 8 notable-security-feature-in-3-8-14}@anchor{e7e}
@subsection Notable security feature in 3.8.14


Converting between @ref{326,,int} and @ref{1df,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{277,,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{e2,,sys} APIs. See the @ref{9ec,,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,What’s New In Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-3-8-17}@anchor{e7f}
@subsection Notable changes in 3.8.17


@menu
* tarfile: tarfile<7>. 

@end menu

@node tarfile<7>,,,Notable changes in 3 8 17
@anchor{whatsnew/3 8 id3}@anchor{e80}
@subsubsection tarfile



@itemize *

@item 
The extraction methods in @ref{e7,,tarfile}, and @ref{882,,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{883,,Extraction filters} for details.
In Python 3.12, use without the `filter' argument will show a
@ref{2c9,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 7,What’s New In Python 3 6,What’s New In Python 3 8,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 7 doc}@anchor{e81}@anchor{whatsnew/3 7 translation-repo}@anchor{e82}@anchor{whatsnew/3 7 what-s-new-in-python-3-7}@anchor{e83}
@section What’s New In Python 3.7


@*Editor: 
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{145,,changelog}.

@menu
* Summary – Release Highlights: Summary – Release Highlights<2>. 
* New Features: New Features<12>. 
* Other Language Changes: Other Language Changes<7>. 
* New Modules: New Modules<7>. 
* Improved Modules: Improved Modules<7>. 
* C API Changes: C API Changes<6>. 
* Build Changes: Build Changes<6>. 
* Optimizations: Optimizations<10>. 
* Other CPython Implementation Changes: Other CPython Implementation Changes<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>,New Features<12>,,What’s New In Python 3 7
@anchor{whatsnew/3 7 summary-release-highlights}@anchor{e84}
@subsection Summary – Release Highlights


@c This section singles out the most important changes in Python 3.7.
@c Brevity is key.

New syntax features:


@itemize *

@item 
@ref{e85,,PEP 563}, postponed evaluation of type annotations.
@end itemize

Backwards incompatible syntax changes:


@itemize *

@item 
@ref{b19,,async} and @ref{432,,await} are now reserved keywords.
@end itemize

New library modules:


@itemize *

@item 
@ref{28,,contextvars}: @ref{e86,,PEP 567 – Context Variables}

@item 
@ref{32,,dataclasses}: @ref{e87,,PEP 557 – Data Classes}

@item 
@ref{e88,,importlib.resources}
@end itemize

New built-in features:


@itemize *

@item 
@ref{e89,,PEP 553}, the new @ref{4f9,,breakpoint()} function.
@end itemize

Python data model improvements:


@itemize *

@item 
@ref{e8a,,PEP 562}, customization of access to
module attributes.

@item 
@ref{e8b,,PEP 560}, core support for typing module and
generic types.

@item 
the insertion-order preservation nature of @ref{e8c,,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{b,,asyncio} module has received new features, significant
@ref{e8d,,usability and performance improvements}.

@item 
The @ref{f7,,time} module gained support for
@ref{e8e,,functions with nanosecond resolution}.
@end itemize

CPython implementation improvements:


@itemize *

@item 
Avoiding the use of ASCII as a default text encoding:


@itemize *

@item 
@ref{e8f,,PEP 538}, legacy C locale coercion

@item 
@ref{e90,,PEP 540}, forced UTF-8 runtime mode
@end itemize

@item 
@ref{e91,,PEP 552}, deterministic .pycs

@item 
@ref{e92,,New Python Development Mode}

@item 
@ref{e93,,PEP 565}, improved @ref{2c9,,DeprecationWarning}
handling
@end itemize

C API improvements:


@itemize *

@item 
@ref{e94,,PEP 539}, new C API for thread-local storage
@end itemize

Documentation improvements:


@itemize *

@item 
@ref{e95,,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{e96,,Optimizations} section lists them in detail.

For a list of changes that may affect compatibility with previous Python
releases please refer to the @ref{e97,,Porting to Python 3.7} section.

@node New Features<12>,Other Language Changes<7>,Summary – Release Highlights<2>,What’s New In Python 3 7
@anchor{whatsnew/3 7 new-features}@anchor{e98}
@subsection New Features


@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,,New Features<12>
@anchor{whatsnew/3 7 pep-563-postponed-evaluation-of-annotations}@anchor{e99}@anchor{whatsnew/3 7 whatsnew37-pep563}@anchor{e85}
@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{a9e,,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 Δείτε επίσης



@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,New Features<12>
@anchor{whatsnew/3 7 pep-538-legacy-c-locale-coercion}@anchor{e9a}@anchor{whatsnew/3 7 whatsnew37-pep538}@anchor{e8f}
@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 μεταβλητή περιβάλλοντος; PYTHONCOERCECLOCALE
@ref{e9b,,PYTHONCOERCECLOCALE}
environment variable. Automatically setting @code{LC_CTYPE} this way means that
both the core interpreter and locale-aware C extensions (such as
@ref{c2,,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{94a,,stdin} and
@ref{e9c,,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{d05,,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{d05,,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{e90,,PEP 540; Forced UTF-8 Runtime Mode}.


@subsubheading Δείτε επίσης



@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,New Features<12>
@anchor{whatsnew/3 7 pep-540-forced-utf-8-runtime-mode}@anchor{e9d}@anchor{whatsnew/3 7 whatsnew37-pep540}@anchor{e90}
@subsubsection PEP 540: Forced UTF-8 Runtime Mode


The new @ref{178,,-X} @code{utf8} command line option and 
@geindex PYTHONUTF8
@geindex μεταβλητή περιβάλλοντος; PYTHONUTF8
@ref{1ad,,PYTHONUTF8}
environment variable can be used to enable the @ref{a46,,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{94a,,sys.stdin} and
@ref{e9c,,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{e90,,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 Δείτε επίσης



@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,New Features<12>
@anchor{whatsnew/3 7 pep-553-built-in-breakpoint}@anchor{e9e}@anchor{whatsnew/3 7 whatsnew37-pep553}@anchor{e89}
@subsubsection PEP 553: Built-in @code{breakpoint()}


Python 3.7 includes the new built-in @ref{4f9,,breakpoint()} function as
an easy and consistent way to enter the Python debugger.

Built-in @code{breakpoint()} calls @ref{e9f,,sys.breakpointhook()}.  By default, the
latter imports @ref{aa,,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 μεταβλητή περιβάλλοντος; PYTHONBREAKPOINT
@ref{ea0,,PYTHONBREAKPOINT} can be set to the callable of your debugger of
choice.  Set @code{PYTHONBREAKPOINT=0} to completely disable built-in
@code{breakpoint()}.


@subsubheading Δείτε επίσης



@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,New Features<12>
@anchor{whatsnew/3 7 pep-539-new-c-api-for-thread-local-storage}@anchor{ea1}@anchor{whatsnew/3 7 whatsnew37-pep539}@anchor{e94}
@subsubsection PEP 539: New C API for Thread-Local Storage


While Python provides a C API for thread-local storage support; the existing
@ref{ea2,,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{ea3,,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{ea4,,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 Δείτε επίσης



@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,New Features<12>
@anchor{whatsnew/3 7 pep-562-customization-of-access-to-module-attributes}@anchor{ea5}@anchor{whatsnew/3 7 whatsnew37-pep562}@anchor{e8a}
@subsubsection PEP 562: Customization of Access to Module Attributes


Python 3.7 allows defining @ref{ea6,,__getattr__()} on modules and will call
it whenever a module attribute is otherwise not found.  Defining
@ref{ea7,,__dir__()} on modules is now also allowed.

A typical example of where this may be useful is module attribute deprecation
and lazy loading.


@subsubheading Δείτε επίσης



@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,New Features<12>
@anchor{whatsnew/3 7 pep-564-new-time-functions-with-nanosecond-resolution}@anchor{ea8}@anchor{whatsnew/3 7 whatsnew37-pep564}@anchor{e8e}
@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{75e,,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{f7,,time}
module:


@itemize *

@item 
@ref{ea9,,time.clock_gettime_ns()}

@item 
@ref{eaa,,time.clock_settime_ns()}

@item 
@ref{eab,,time.monotonic_ns()}

@item 
@ref{eac,,time.perf_counter_ns()}

@item 
@ref{ead,,time.process_time_ns()}

@item 
@ref{eae,,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{eae,,time.time_ns()} is
approximately 3 times better than that of @ref{75e,,time.time()}.


@subsubheading Δείτε επίσης



@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,New Features<12>
@anchor{whatsnew/3 7 pep-565-show-deprecationwarning-in-main}@anchor{eaf}@anchor{whatsnew/3 7 whatsnew37-pep565}@anchor{e93}
@subsubsection PEP 565: Show DeprecationWarning in @code{__main__}


The default handling of @ref{2c9,,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{847,,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{2c9,,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{c9b,,PendingDeprecationWarning}: displayed by default only when running
tests, intended for cases where a future version upgrade will change the
warning category to @ref{2c9,,DeprecationWarning} or @ref{847,,FutureWarning}.
@end itemize

Previously both @ref{2c9,,DeprecationWarning} and @ref{c9b,,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 Δείτε επίσης



@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__,New Features<12>
@anchor{whatsnew/3 7 pep-560-core-support-for-typing-module-and-generic-types}@anchor{eb0}@anchor{whatsnew/3 7 whatsnew37-pep560}@anchor{e8b}
@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{10d,,typing}
module are extensively used by the community, so this restriction is removed.
The PEP introduces two special methods @ref{b21,,__class_getitem__()} and
@ref{eb1,,__mro_entries__()}, these methods are now used by most classes and special
constructs in @code{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 @code{typing} module are
fixed.


@subsubheading Δείτε επίσης



@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,New Features<12>
@anchor{whatsnew/3 7 pep-552-hash-based-pyc-files}@anchor{eb2}@anchor{whatsnew/3 7 whatsnew37-pep552}@anchor{e91}
@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{bb,,py_compile} or @ref{21,,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{9e3,,Ακύρωση cached bytecode} for more information.


@subsubheading Δείτε επίσης



@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,New Features<12>
@anchor{whatsnew/3 7 pep-545-python-documentation-translations}@anchor{eb3}@anchor{whatsnew/3 7 whatsnew37-pep545}@anchor{e95}
@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 Δείτε επίσης



@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,New Features<12>
@anchor{whatsnew/3 7 python-development-mode-x-dev}@anchor{eb4}@anchor{whatsnew/3 7 whatsnew37-devmode}@anchor{e92}
@subsubsection Python Development Mode (-X dev)


The new @ref{178,,-X} @code{dev} command line option or the new
@geindex PYTHONDEVMODE
@geindex μεταβλητή περιβάλλοντος; PYTHONDEVMODE
@ref{eb5,,PYTHONDEVMODE} environment variable can be used to enable
@ref{70d,,Python Development Mode}.  When in development mode, Python performs
additional runtime checks that are too expensive to be enabled by default.
See @ref{70d,,Python Development Mode} documentation for the full
description.

@node Other Language Changes<7>,New Modules<7>,New Features<12>,What’s New In Python 3 7
@anchor{whatsnew/3 7 other-language-changes}@anchor{eb6}
@subsection Other Language Changes



@itemize *

@item 
An @ref{432,,await} expression and comprehensions containing an
@ref{e70,,async for} clause were illegal in the expressions in
@ref{43a,,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{434,,bytes.fromhex()} and @ref{435,,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{1df,,str}, @ref{1c7,,bytes}, and @ref{1c6,,bytearray} gained support for
the new @ref{eb7,,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{1bd,,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{eb8,,types.TracebackType} can now be instantiated from Python code, and
the @ref{eb9,,tb_next} attribute on
@ref{eba,,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{4ca,,-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{178,,-X} @code{importtime} option or the
@geindex PYTHONPROFILEIMPORTTIME
@geindex μεταβλητή περιβάλλοντος; PYTHONPROFILEIMPORTTIME
@ref{ebb,,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 New Modules<7>,Improved Modules<7>,Other Language Changes<7>,What’s New In Python 3 7
@anchor{whatsnew/3 7 new-modules}@anchor{ebc}
@subsection New Modules


@menu
* contextvars: contextvars<2>. 
* dataclasses: dataclasses<4>. 
* importlib.resources: importlib resources<3>. 

@end menu

@node contextvars<2>,dataclasses<4>,,New Modules<7>
@anchor{whatsnew/3 7 contextvars}@anchor{ebd}@anchor{whatsnew/3 7 whatsnew37-pep567}@anchor{e86}
@subsubsection contextvars


The new @ref{28,,contextvars} module and a set of
@ref{ebe,,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{b,,asyncio} and @ref{39,,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 Δείτε επίσης



@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<4>,importlib resources<3>,contextvars<2>,New Modules<7>
@anchor{whatsnew/3 7 dataclasses}@anchor{ebf}@anchor{whatsnew/3 7 whatsnew37-pep557}@anchor{e87}
@subsubsection dataclasses


The new @ref{6e6,,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{1bc,,__repr__()}, @ref{ec0,,__eq__()}, and
@ref{ec1,,__hash__()} are generated automatically.

Example:

@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 Δείτε επίσης



@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<3>,,dataclasses<4>,New Modules<7>
@anchor{whatsnew/3 7 importlib-resources}@anchor{ec2}@anchor{whatsnew/3 7 whatsnew37-importlib-resources}@anchor{e88}
@subsubsection importlib.resources


The new @ref{7e,,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 @code{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 Δείτε επίσης


importlib_resources@footnote{https://importlib-resources.readthedocs.io/en/latest/}
– a PyPI backport for earlier Python versions.


@node Improved Modules<7>,C API Changes<6>,New Modules<7>,What’s New In Python 3 7
@anchor{whatsnew/3 7 improved-modules}@anchor{ec3}
@subsection Improved Modules


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

@end menu

@node argparse<6>,asyncio<11>,,Improved Modules<7>
@anchor{whatsnew/3 7 argparse}@anchor{ec4}
@subsubsection argparse


The new @ref{ec5,,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<11>,binascii<2>,argparse<6>,Improved Modules<7>
@anchor{whatsnew/3 7 asyncio}@anchor{ec6}@anchor{whatsnew/3 7 whatsnew37-asyncio}@anchor{e8d}
@subsubsection asyncio


The @ref{b,,asyncio} module has received many new features, usability and
@ref{ec7,,performance improvements}.  Notable changes
include:


@itemize *

@item 
The new @ref{5fd,,provisional} @ref{309,,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{28,,contextvars}.
@ref{ec8,,loop.call_soon()},
@ref{ec9,,loop.call_soon_threadsafe()},
@ref{eca,,loop.call_later()},
@ref{ecb,,loop.call_at()}, and
@ref{ecc,,Future.add_done_callback()}
have a new optional keyword-only `context' parameter.
@ref{460,,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{462,,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{ecd,,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{ece,,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{88f,,asyncio.current_task()} function returns the currently running
@ref{460,,Task} instance, and the new @ref{d20,,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{e63,,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{ecf,,asyncio.get_running_loop()} function returns the currently
running loop, and raises a @ref{30d,,RuntimeError} if no loop is running.
This is in contrast with @ref{56c,,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{ed0,,StreamWriter.wait_closed()}
coroutine method allows waiting until the stream writer is closed.  The new
@ref{ed1,,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{ed2,,loop.sock_sendfile()}
coroutine method allows sending files using @ref{ed3,,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{ed4,,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{ed5,,Server.get_loop()} allows doing the same for
@ref{ed6,,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{ed6,,asyncio.Server} begin
serving.  Previously, the server would start serving immediately when created.
The new `start_serving' keyword argument to
@ref{ed7,,loop.create_server()} and
@ref{6d0,,loop.create_unix_server()},
as well as @ref{ed8,,Server.start_serving()}, and
@ref{ed9,,Server.serve_forever()}
can be used to decouple server instantiation and serving.  The new
@ref{eda,,Server.is_serving()} method returns @code{True}
if the server is serving.  @code{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{eca,,loop.call_later()}
gained the new @ref{edb,,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{b1a,,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{edc,,asyncio.open_connection()}, @ref{edd,,asyncio.start_server()} functions,
@ref{9f9,,loop.create_connection()},
@ref{ed7,,loop.create_server()},
@ref{bbb,,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{ede,,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{b19,,async}/@ref{432,,await} syntax.
(Contributed by Andrew Svetlov in bpo-32193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32193}.)

@item 
The new @ref{edf,,ReadTransport.is_reading()}
method can be used to determine the reading state of the transport.
Additionally, calls to
@ref{ee0,,ReadTransport.resume_reading()}
and @ref{ee1,,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{79f,,path-like objects}.
(Contributed by Yury Selivanov in bpo-32066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32066}.)

@item 
In @ref{b,,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{ee2,,deprecated}.

@node binascii<2>,calendar<4>,asyncio<11>,Improved Modules<7>
@anchor{whatsnew/3 7 binascii}@anchor{ee3}
@subsubsection binascii


The @ref{ee4,,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<4>,collections<3>,binascii<2>,Improved Modules<7>
@anchor{whatsnew/3 7 calendar}@anchor{ee5}
@subsubsection calendar


The @ref{202,,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<3>,compileall<3>,calendar<4>,Improved Modules<7>
@anchor{whatsnew/3 7 collections}@anchor{ee6}
@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<5>,collections<3>,Improved Modules<7>
@anchor{whatsnew/3 7 compileall}@anchor{ee7}
@subsubsection compileall


@ref{ee8,,compileall.compile_dir()} learned the new `invalidation_mode' parameter,
which can be used to enable
@ref{e91,,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<5>,contextlib<4>,compileall<3>,Improved Modules<7>
@anchor{whatsnew/3 7 concurrent-futures}@anchor{ee9}
@subsubsection concurrent.futures


@ref{206,,ProcessPoolExecutor} and
@ref{b27,,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{206,,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<4>,cProfile<2>,concurrent futures<5>,Improved Modules<7>
@anchor{whatsnew/3 7 contextlib}@anchor{eea}
@subsubsection contextlib


The new @ref{bca,,nullcontext()} is a simpler and faster no-op
context manager than @ref{208,,ExitStack}.
(Contributed by Jesse-Bakker in bpo-10049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10049}.)

The new @ref{20f,,asynccontextmanager()},
@ref{eeb,,AbstractAsyncContextManager}, and
@ref{209,,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<4>,Improved Modules<7>
@anchor{whatsnew/3 7 cprofile}@anchor{eec}
@subsubsection cProfile


The @code{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<6>,cProfile<2>,Improved Modules<7>
@anchor{whatsnew/3 7 crypt}@anchor{eed}
@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<6>,dbm<3>,crypt,Improved Modules<7>
@anchor{whatsnew/3 7 datetime}@anchor{eee}
@subsubsection datetime


The new @ref{a0a,,datetime.fromisoformat()}
method constructs a @ref{6e7,,datetime} object from a string
in one of the formats output by
@ref{eef,,datetime.isoformat()}.
(Contributed by Paul Ganssle in bpo-15873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15873}.)

The @ref{9d8,,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<3>,decimal<2>,datetime<6>,Improved Modules<7>
@anchor{whatsnew/3 7 dbm}@anchor{ef0}
@subsubsection dbm


@ref{35,,dbm.dumb} now supports reading read-only files and no longer writes the
index file when it is not changed.

@node decimal<2>,dis<4>,dbm<3>,Improved Modules<7>
@anchor{whatsnew/3 7 decimal}@anchor{ef1}
@subsubsection decimal


The @ref{39,,decimal} module now uses @ref{e86,,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<4>,distutils<4>,decimal<2>,Improved Modules<7>
@anchor{whatsnew/3 7 dis}@anchor{ef2}
@subsubsection dis


The @ref{496,,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<4>,Improved Modules<7>
@anchor{whatsnew/3 7 distutils}@anchor{ef3}
@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<6>,distutils<4>,Improved Modules<7>
@anchor{whatsnew/3 7 enum}@anchor{ef4}
@subsubsection enum


The @ref{a21,,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 @ref{a21,,Enum}
classes will raise a @ref{291,,TypeError} (e.g. @code{1 in Color}); similarly,
attempting to check for non-Flag objects in a @ref{a14,,Flag} member will
raise @code{TypeError} (e.g. @code{1 in Perm.RW}); currently, both operations
return @ref{ef5,,False} instead and are deprecated.
(Contributed by Ethan Furman in bpo-33217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33217}.)

@node functools<6>,gc<7>,enum<5>,Improved Modules<7>
@anchor{whatsnew/3 7 functools}@anchor{ef6}
@subsubsection functools


@ref{a2a,,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<7>,hmac<3>,functools<6>,Improved Modules<7>
@anchor{whatsnew/3 7 gc}@anchor{ef7}
@subsubsection gc


The new @ref{ef8,,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{ef9,,gc.unfreeze()} functions
reverses this operation.  Additionally, @ref{efa,,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<3>,http client<2>,gc<7>,Improved Modules<7>
@anchor{whatsnew/3 7 hmac}@anchor{efb}
@subsubsection hmac


The @ref{6d,,hmac} module now has an optimized one-shot @ref{efc,,digest()}
function, which is up to three times faster than @ref{efd,,HMAC()}.
(Contributed by Christian Heimes in bpo-32433@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32433}.)

@node http client<2>,http server<3>,hmac<3>,Improved Modules<7>
@anchor{whatsnew/3 7 http-client}@anchor{efe}
@subsubsection http.client


@ref{223,,HTTPConnection} and @ref{224,,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<3>,idlelib and IDLE,http client<2>,Improved Modules<7>
@anchor{whatsnew/3 7 http-server}@anchor{eff}
@subsubsection http.server


@ref{22a,,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{22a,,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{f00,,ThreadingHTTPServer} class
uses threads to handle requests using @ref{f01,,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<3>,Improved Modules<7>
@anchor{whatsnew/3 7 idlelib-and-idle}@anchor{f02}
@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<6>,idlelib and IDLE,Improved Modules<7>
@anchor{whatsnew/3 7 importlib}@anchor{f03}
@subsubsection importlib


The @code{importlib.abc.ResourceReader} ABC was introduced to
support the loading of resources from packages.  See also
@ref{e88,,importlib.resources}.
(Contributed by Barry Warsaw, Brett Cannon in bpo-32248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32248}.)

@ref{928,,importlib.reload()} now raises @ref{1be,,ModuleNotFoundError} if the module
lacks a spec.
(Contributed by Garvit Khatri in bpo-29851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29851}.)

@ref{7a7,,importlib.util.find_spec()} now raises @ref{1be,,ModuleNotFoundError} instead of
@ref{1a9,,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 @ref{f04,,importlib.util.source_hash()} can be used to compute the hash of
the passed source.  A @ref{e91,,hash-based .pyc file}
embeds the value returned by this function.

@node io<6>,ipaddress<3>,importlib<4>,Improved Modules<7>
@anchor{whatsnew/3 7 io}@anchor{f05}
@subsubsection io


The new @ref{f06,,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<6>,io<6>,Improved Modules<7>
@anchor{whatsnew/3 7 ipaddress}@anchor{f07}
@subsubsection ipaddress


The new @code{subnet_of()} and @code{supernet_of()} methods of
@ref{713,,ipaddress.IPv6Network} and @ref{712,,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<6>,locale<5>,ipaddress<3>,Improved Modules<7>
@anchor{whatsnew/3 7 itertools}@anchor{f08}
@subsubsection itertools


@ref{f09,,itertools.islice()} now accepts
@ref{43d,,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<5>,logging<3>,itertools<6>,Improved Modules<7>
@anchor{whatsnew/3 7 locale}@anchor{f0a}
@subsubsection locale


The new `monetary' argument to @ref{92d,,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{947,,locale.getpreferredencoding()} function now always returns @code{'UTF-8'}
on Android or when in the @ref{e90,,forced UTF-8 mode}.

@node logging<3>,math<8>,locale<5>,Improved Modules<7>
@anchor{whatsnew/3 7 logging}@anchor{f0b}
@subsubsection logging


@ref{f0c,,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{f0d,,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{f0e,,logging.config.fileConfig()}.
(Contributed by Preston Landers in bpo-31080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31080}.)

@node math<8>,mimetypes<4>,logging<3>,Improved Modules<7>
@anchor{whatsnew/3 7 math}@anchor{f0f}
@subsubsection math


The new @ref{f10,,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<4>,msilib,math<8>,Improved Modules<7>
@anchor{whatsnew/3 7 mimetypes}@anchor{f11}
@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<5>,mimetypes<4>,Improved Modules<7>
@anchor{whatsnew/3 7 msilib}@anchor{f12}
@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<5>,os<9>,msilib,Improved Modules<7>
@anchor{whatsnew/3 7 multiprocessing}@anchor{f13}
@subsubsection multiprocessing


The new @ref{f14,,Process.close()} method
explicitly closes the process object and releases all resources associated
with it.  @ref{277,,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{f15,,Process.kill()} method can
be used to terminate the process using the @ref{f16,,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{4de,,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<9>,pathlib<12>,multiprocessing<5>,Improved Modules<7>
@anchor{whatsnew/3 7 os}@anchor{f17}
@subsubsection os


@ref{f18,,os.fwalk()} now accepts the `path' argument as @ref{1c7,,bytes}.
(Contributed by Serhiy Storchaka in bpo-28682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28682}.)

@ref{e23,,os.scandir()} gained support for @ref{f19,,file descriptors}.
(Contributed by Serhiy Storchaka in bpo-25996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25996}.)

The new @ref{332,,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{f1a,,os.preadv()} (combine the functionality of @ref{f1b,,os.readv()} and
@ref{f1c,,os.pread()}) and @ref{f1d,,os.pwritev()} functions (combine the functionality
of @ref{f1e,,os.writev()} and @ref{f1f,,os.pwrite()}). (Contributed by Pablo Galindo in
bpo-31368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31368}.)

The mode argument of @ref{72f,,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{f20,,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{4f5,,os.stat()} now contains the
@ref{f21,,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<12>,pdb<7>,os<9>,Improved Modules<7>
@anchor{whatsnew/3 7 pathlib}@anchor{f22}
@subsubsection pathlib


The new @ref{ddb,,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<7>,py_compile<3>,pathlib<12>,Improved Modules<7>
@anchor{whatsnew/3 7 pdb}@anchor{f23}
@subsubsection pdb


@ref{4fa,,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{aa,,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<3>,pdb<7>,Improved Modules<7>
@anchor{whatsnew/3 7 py-compile}@anchor{f24}
@subsubsection py_compile


@ref{de9,,py_compile.compile()} – and by extension, @ref{21,,compileall} – now
respects the 
@geindex SOURCE_DATE_EPOCH
@geindex μεταβλητή περιβάλλοντος; 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<3>,queue<2>,py_compile<3>,Improved Modules<7>
@anchor{whatsnew/3 7 pydoc}@anchor{f25}
@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<6>,pydoc<3>,Improved Modules<7>
@anchor{whatsnew/3 7 queue}@anchor{f26}
@subsubsection queue


The new @ref{f27,,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<6>,signal<2>,queue<2>,Improved Modules<7>
@anchor{whatsnew/3 7 re}@anchor{f28}
@subsubsection re


The flags @ref{a1d,,re.ASCII}, @ref{f29,,re.LOCALE} and @ref{f2a,,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{7a0,,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{f29,,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{847,,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{942,,copy.copy()} and @ref{f2b,,copy.deepcopy()}.
(Contributed by Serhiy Storchaka in bpo-10076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10076}.)

@node signal<2>,socket<7>,re<6>,Improved Modules<7>
@anchor{whatsnew/3 7 signal}@anchor{f2c}
@subsubsection signal


The new `warn_on_full_buffer' argument to the @ref{f2d,,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<7>,socketserver,signal<2>,Improved Modules<7>
@anchor{whatsnew/3 7 socket}@anchor{f2e}
@subsubsection socket


The new @ref{f2f,,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{f30,,socket.close()} function closes the passed socket file descriptor.
This function should be used instead of @ref{f31,,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{d4,,socket} module now exposes the @ref{f32,,socket.TCP_CONGESTION} (Linux 2.6.13), @ref{f32,,socket.TCP_USER_TIMEOUT} (Linux 2.6.37), and @ref{f32,,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{f33,,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<8>,socket<7>,Improved Modules<7>
@anchor{whatsnew/3 7 socketserver}@anchor{f34}
@subsubsection socketserver


@ref{f35,,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 @ref{f36,,socketserver.ForkingMixIn.block_on_close} class attribute to
@ref{f37,,socketserver.ForkingMixIn} and @ref{f01,,socketserver.ThreadingMixIn}
classes. Set the class attribute to @code{False} to get the pre-3.7 behaviour.

@node sqlite3<8>,ssl<7>,socketserver,Improved Modules<7>
@anchor{whatsnew/3 7 sqlite3}@anchor{f38}
@subsubsection sqlite3


@ref{3df,,sqlite3.Connection} now exposes the @ref{f39,,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{3e0,,sqlite3.connect()} now accepts any
@ref{79f,,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<7>,string<2>,sqlite3<8>,Improved Modules<7>
@anchor{whatsnew/3 7 ssl}@anchor{f3a}
@subsubsection ssl


The @ref{d8,,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{f3b,,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{f3c,,SSLContext.hostname_checks_common_name}.
(Contributed by Christian Heimes in bpo-31399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31399}.)

@cartouche
@quotation Σημείωση 
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{f3d,,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{f3e,,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{f3f,,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{cbb,,SSLSocket} and @ref{f40,,SSLObject} no longer have a public
constructor.  Direct instantiation was never a documented and supported
feature.  Instances must be created with @ref{336,,SSLContext} methods
@ref{933,,wrap_socket()} and @ref{f41,,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{c46,,SSLContext.minimum_version}
and @ref{c47,,SSLContext.maximum_version}.
Supported protocols are indicated by several new flags, such as
@ref{f42,,HAS_TLSv1_1}.
(Contributed by Christian Heimes in bpo-32609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32609}.)

Added @ref{df5,,ssl.SSLContext.post_handshake_auth} to enable and
@ref{df6,,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<3>,ssl<7>,Improved Modules<7>
@anchor{whatsnew/3 7 string}@anchor{f43}
@subsubsection string


@ref{a77,,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<3>,sys<9>,string<2>,Improved Modules<7>
@anchor{whatsnew/3 7 subprocess}@anchor{f44}
@subsubsection subprocess


The @ref{f45,,subprocess.run()} function accepts the new `capture_output'
keyword argument.  When true, stdout and stderr will be captured.
This is equivalent to passing @ref{f46,,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{6bf,,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{6bf,,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{d96,,KeyboardInterrupt} during @ref{f47,,subprocess.call()},
@ref{f45,,subprocess.run()}, or in a @ref{6bf,,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<9>,time<5>,subprocess<3>,Improved Modules<7>
@anchor{whatsnew/3 7 sys}@anchor{f48}
@subsubsection sys


The new @ref{e9f,,sys.breakpointhook()} hook function is called by the
built-in @ref{4f9,,breakpoint()}.
(Contributed by Barry Warsaw in bpo-31353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31353}.)

On Android, the new @ref{f49,,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{f4a,,sys.get_coroutine_origin_tracking_depth()} function returns
the current coroutine origin tracking depth, as set by
the new @ref{f4b,,sys.set_coroutine_origin_tracking_depth()}.  @ref{b,,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<7>,sys<9>,Improved Modules<7>
@anchor{whatsnew/3 7 time}@anchor{f4c}
@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{f7,,time} module:


@itemize *

@item 
@ref{ea9,,time.clock_gettime_ns()}

@item 
@ref{eaa,,time.clock_settime_ns()}

@item 
@ref{eab,,time.monotonic_ns()}

@item 
@ref{eac,,time.perf_counter_ns()}

@item 
@ref{ead,,time.process_time_ns()}

@item 
@ref{eae,,time.time_ns()}
@end itemize

New clock identifiers have been added:


@itemize *

@item 
@ref{f4d,,time.CLOCK_BOOTTIME} (Linux): Identical to
@ref{a88,,time.CLOCK_MONOTONIC}, except it also includes any time that the
system is suspended.

@item 
@ref{f4e,,time.CLOCK_PROF} (FreeBSD, NetBSD and OpenBSD): High-resolution
per-process CPU timer.

@item 
@ref{f4f,,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{d03,,time.thread_time()} and @ref{f50,,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{f51,,time.pthread_getcpuclockid()} function returns the clock ID
of the thread-specific CPU-time clock.

@node tkinter<7>,tracemalloc<2>,time<5>,Improved Modules<7>
@anchor{whatsnew/3 7 tkinter}@anchor{f52}
@subsubsection tkinter


The new @ref{f53,,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<7>,tkinter<7>,Improved Modules<7>
@anchor{whatsnew/3 7 tracemalloc}@anchor{f54}
@subsubsection tracemalloc


@ref{f55,,tracemalloc.Traceback} behaves more like regular tracebacks,
sorting the frames from oldest to most recent.
@ref{f56,,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<7>,unicodedata<8>,tracemalloc<2>,Improved Modules<7>
@anchor{whatsnew/3 7 types}@anchor{f57}
@subsubsection types


The new @ref{f58,,WrapperDescriptorType},
@ref{a3a,,MethodWrapperType}, @ref{f59,,MethodDescriptorType},
and @ref{f5a,,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{f5b,,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<8>,unittest<9>,types<7>,Improved Modules<7>
@anchor{whatsnew/3 7 unicodedata}@anchor{f5c}
@subsubsection unicodedata


The internal @ref{10e,,unicodedata} database has been upgraded to use Unicode 11@footnote{https://www.unicode.org/versions/Unicode11.0.0/}. (Contributed by Benjamin
Peterson.)

@node unittest<9>,unittest mock,unicodedata<8>,Improved Modules<7>
@anchor{whatsnew/3 7 unittest}@anchor{f5d}
@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<6>,unittest<9>,Improved Modules<7>
@anchor{whatsnew/3 7 unittest-mock}@anchor{f5e}
@subsubsection unittest.mock


The @ref{f5f,,sentinel} attributes now preserve their identity
when they are @ref{29,,copied} or @ref{ab,,pickled}. (Contributed by
Serhiy Storchaka in bpo-20804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20804}.)

The new @ref{f60,,seal()} function allows sealing
@ref{e0e,,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<6>,uu,unittest mock,Improved Modules<7>
@anchor{whatsnew/3 7 urllib-parse}@anchor{f61}
@subsubsection urllib.parse


@ref{f62,,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<4>,urllib parse<6>,Improved Modules<7>
@anchor{whatsnew/3 7 uu}@anchor{f63}
@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<4>,warnings<4>,uu,Improved Modules<7>
@anchor{whatsnew/3 7 uuid}@anchor{f64}
@subsubsection uuid


The new @ref{f65,,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{f66,,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{f67,,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<4>,xml<6>,uuid<4>,Improved Modules<7>
@anchor{whatsnew/3 7 warnings}@anchor{f68}
@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{2ed,,-b}
and the new CPython-specific @ref{178,,-X} @code{dev} option) are always passed
to the warnings machinery via the @ref{3a5,,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{2ed,,-b} (or @code{-bb})

@item 
any filters specified with the @ref{1c0,,-W} option

@item 
any filters specified with the 
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,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{3dc,,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{e93,,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<6>,xml etree,warnings<4>,Improved Modules<7>
@anchor{whatsnew/3 7 xml}@anchor{f69}
@subsubsection xml


As mitigation against DTD and external entity retrieval, the
@ref{12b,,xml.dom.minidom} and @ref{132,,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<6>,Improved Modules<7>
@anchor{whatsnew/3 7 xml-etree}@anchor{f6a}
@subsubsection xml.etree


@ref{f6b,,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,Improved Modules<7>
@anchor{whatsnew/3 7 xmlrpc-server}@anchor{f6c}
@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<3>,xmlrpc server,Improved Modules<7>
@anchor{whatsnew/3 7 zipapp}@anchor{f6d}
@subsubsection zipapp


Function @ref{f6e,,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{f6e,,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<3>,,zipapp,Improved Modules<7>
@anchor{whatsnew/3 7 zipfile}@anchor{f6f}
@subsubsection zipfile


@ref{ab1,,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 C API Changes<6>,Build Changes<6>,Improved Modules<7>,What’s New In Python 3 7
@anchor{whatsnew/3 7 c-api-changes}@anchor{f70}
@subsection C API Changes


A new API for thread-local storage has been implemented.  See
@ref{e94,,PEP 539; New C API for Thread-Local Storage} for an overview and
@ref{ea3,,Thread-specific storage 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{e86,,context variables} functionality
exposes a number of @ref{ebe,,new C APIs}.

The new @ref{f71,,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{f72,,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{f73,,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{108,,tracemalloc} now exposes a C API through the new
@ref{f74,,PyTraceMalloc_Track()} and @ref{f75,,PyTraceMalloc_Untrack()}
functions.
(Contributed by Victor Stinner in bpo-30054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30054}.)

The new @ref{f76,,import__find__load__start} and
@ref{f76,,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{95a,,PyMemberDef}, @ref{f77,,PyGetSetDef},
@ref{f78,,PyStructSequence_Field}, @ref{f79,,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{c6f,,PyUnicode_AsUTF8AndSize()} and @ref{637,,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{f7a,,PyMapping_Keys()}, @ref{f7b,,PyMapping_Values()} and
@ref{f7c,,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{645,,PySlice_Unpack()} and @ref{646,,PySlice_AdjustIndices()}.
(Contributed by Serhiy Storchaka in bpo-27867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27867}.)

@ref{642,,PyOS_AfterFork()} is deprecated in favour of the new functions
@ref{f7d,,PyOS_BeforeFork()}, @ref{f7e,,PyOS_AfterFork_Parent()} and
@ref{643,,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{f7f,,PyTimeZone_FromOffset()} and @ref{f80,,PyTimeZone_FromOffsetAndName()},
and access to the UTC singleton with @ref{f81,,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{f82,,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{c8f,,PyUnicode_AsWideCharString()} now raises a @ref{277,,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{673,,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{e97,,Porting to Python 3.7} section in this
document and the @ref{f83,,Before Python initialization} section in the C API documentation
for more details.

The new @ref{f84,,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{f85,,Py_DecodeLocale()}, @ref{f86,,Py_EncodeLocale()} now use the UTF-8
encoding when the @ref{e90,,UTF-8 mode} is enabled.
(Contributed by Victor Stinner in bpo-29240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29240}.)

@ref{f87,,PyUnicode_DecodeLocaleAndSize()} and @ref{f88,,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{c8c,,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 Build Changes<6>,Optimizations<10>,C API Changes<6>,What’s New In Python 3 7
@anchor{whatsnew/3 7 build-changes}@anchor{f89}
@subsection Build Changes


Support for building @code{--without-threads} has been removed.  The
@ref{f6,,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{2d,,_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{d8,,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<10>,Other CPython Implementation Changes<2>,Build Changes<6>,What’s New In Python 3 7
@anchor{whatsnew/3 7 optimizations}@anchor{f8a}@anchor{whatsnew/3 7 whatsnew37-perf}@anchor{e96}
@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{ec7}
The @ref{b,,asyncio} module received a number of notable optimizations for
commonly used functions:


@itemize *

@item 
The @ref{56c,,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{f8b,,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{9f4,,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{e33,,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{e8b,,PEP 560 work}, the import time
of @ref{10d,,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{f8c,,sorted()} and @ref{f8d,,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{f8e,,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{8e2,,hasattr()} and @ref{f8f,,getattr()} are now about 4 times faster when
`name' is not found and `obj' does not override @ref{8e3,,object.__getattr__()}
or @ref{f90,,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{1cf,,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}.)

@ref{f91,,datetime.date.fromordinal()} and @ref{f92,,datetime.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{f18,,os.fwalk()} function is now up to 2 times faster thanks to
the use of @ref{e23,,os.scandir()}.
(Contributed by Serhiy Storchaka in bpo-25996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25996}.)

The speed of the @ref{335,,shutil.rmtree()} function has been improved by
20–40% thanks to the use of the @ref{e23,,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{c1,,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{f93,,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{f94,,modify()} methods of classes
@ref{f95,,selectors.EpollSelector}, @ref{f96,,selectors.PollSelector}
and @ref{f97,,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{2ef,,isinstance()}
and @ref{2f0,,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{48d,,datetime.date} and @ref{6e7,,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{6c5,,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{f98,,math.erf()} and @ref{f99,,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 Other CPython Implementation Changes<2>,Deprecated Python Behavior,Optimizations<10>,What’s New In Python 3 7
@anchor{whatsnew/3 7 other-cpython-implementation-changes}@anchor{f9a}
@subsection Other CPython Implementation Changes



@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{f9b,,f_trace_lines} and @ref{f9c,,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{28b,,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,Other CPython Implementation Changes<2>,What’s New In Python 3 7
@anchor{whatsnew/3 7 deprecated-python-behavior}@anchor{f9d}
@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{f9e,,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{2c9,,DeprecationWarning} when compiled, in Python 3.8 this will be a
@ref{17e,,SyntaxError}.
(Contributed by Serhiy Storchaka in bpo-10544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10544}.)

Returning a subclass of @ref{328,,complex} from @ref{9de,,object.__complex__()} is
deprecated and will be an error in future Python versions.  This makes
@code{__complex__()} consistent with @ref{43c,,object.__int__()} and
@ref{d92,,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{f9f}
@subsection Deprecated Python modules, functions and methods


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

@end menu

@node aifc,asyncio<12>,,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 aifc}@anchor{fa0}
@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<12>,collections<4>,aifc,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id2}@anchor{fa1}@anchor{whatsnew/3 7 whatsnew37-asyncio-deprecated}@anchor{ee2}
@subsubsection asyncio


Support for directly @code{await}-ing instances of @ref{e35,,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<4>,dbm<4>,asyncio<12>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id3}@anchor{fa2}
@subsubsection collections


In Python 3.8, the abstract base classes in @ref{1f,,collections.abc} will no
longer be exposed in the regular @ref{1e,,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<4>,enum<6>,collections<4>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id4}@anchor{fa3}
@subsubsection dbm


@ref{35,,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<4>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id5}@anchor{fa4}
@subsubsection enum


In Python 3.8, attempting to check for non-Enum objects in @ref{a21,,Enum}
classes will raise a @ref{291,,TypeError} (e.g. @code{1 in Color}); similarly,
attempting to check for non-Flag objects in a @ref{a14,,Flag} member will
raise @code{TypeError} (e.g. @code{1 in Perm.RW}); currently, both operations
return @ref{ef5,,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{fa5}
@subsubsection gettext


Using non-integer value for selecting a plural form in @ref{66,,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<6>,gettext<2>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id6}@anchor{fa6}
@subsubsection importlib


Methods
@code{MetaPathFinder.find_module()}
(replaced by
@ref{c3f,,MetaPathFinder.find_spec()})
and
@code{PathEntryFinder.find_loader()}
(replaced by
@ref{c42,,PathEntryFinder.find_spec()})
both deprecated in Python 3.4 now emit @ref{2c9,,DeprecationWarning}.
(Contributed by Matthias Bussonnier in bpo-29576@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29576}.)

The @ref{fa7,,importlib.abc.ResourceLoader} ABC has been deprecated in
favour of @code{importlib.abc.ResourceReader}.

@node locale<6>,macpath,importlib<5>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id7}@anchor{fa8}
@subsubsection locale


@code{locale.format()} has been deprecated, use @ref{92d,,locale.format_string()}
instead.  (Contributed by Garvit in bpo-10379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10379}.)

@node macpath,threading<8>,locale<6>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 macpath}@anchor{fa9}
@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<8>,socket<8>,macpath,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 threading}@anchor{faa}
@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{f6,,threading} instead.
(Contributed by Antoine Pitrou in bpo-31370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31370}.)

@node socket<8>,ssl<8>,threading<8>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id8}@anchor{fab}
@subsubsection socket


The silent argument value truncation in @ref{c55,,socket.htons()} and
@ref{c56,,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<8>,sunau,socket<8>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id9}@anchor{fac}
@subsubsection ssl


@code{ssl.wrap_socket()} is deprecated.  Use
@ref{933,,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<10>,ssl<8>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 sunau}@anchor{fad}
@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<10>,wave<3>,sunau,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id10}@anchor{fae}
@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<3>,,sys<10>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 wave}@anchor{faf}
@subsubsection wave


@code{wave.openfp()} has been deprecated and will be removed in Python 3.9.
Use @ref{d17,,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{fb0}
@subsection Deprecated functions and types of the C API


Function @ref{644,,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{642,,PyOS_AfterFork()} has been deprecated.  Use @ref{f7d,,PyOS_BeforeFork()},
@ref{f7e,,PyOS_AfterFork_Parent()} or @ref{643,,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{fb1}@anchor{whatsnew/3 7 platform-support-removals}@anchor{f3d}
@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/main/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{fb2}
@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{7a1,,re.sub()} were deprecated in Python 3.5, and will now
cause an error.

@item 
Removed support of the `exclude' argument in @ref{fb3,,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{fb4,,splitdrive()}
instead.

@item 
@ref{1cf,,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{5ef,,bool()}, @ref{327,,float()}, @ref{4d9,,list()} and @ref{1ce,,tuple()} no
longer take keyword arguments.  The first argument of @ref{326,,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{b0,,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{fb5,,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{b,,asyncio} no longer exports the @ref{ca,,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{cbb,,ssl.SSLSocket} and @ref{f40,,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{336,,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{fb6}
@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{fb7}
@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{fb8}@anchor{whatsnew/3 7 porting-to-python-37}@anchor{e97}
@subsection Porting to Python 3.7


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

@menu
* Changes in Python Behavior:: 
* Changes in the Python API: Changes in the Python API<8>. 
* Changes in the C API: Changes in the C API<6>. 
* CPython bytecode changes: CPython bytecode changes<7>. 
* Windows-only Changes: Windows-only Changes<2>. 
* Other CPython implementation changes:: 

@end menu

@node Changes in Python Behavior,Changes in the Python API<8>,,Porting to Python 3 7
@anchor{whatsnew/3 7 changes-in-python-behavior}@anchor{fb9}
@subsubsection Changes in Python Behavior



@itemize *

@item 
@ref{b19,,async} and @ref{432,,await} names are now reserved keywords.
Code using these names as identifiers will now raise a @ref{17e,,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{fba,,StopIteration} exceptions raised directly or indirectly in
coroutines and generators are transformed into @ref{30d,,RuntimeError}
exceptions.
(Contributed by Yury Selivanov in bpo-32670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32670}.)

@item 
@ref{fbb,,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{17e,,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{4ca,,-m} switch, the initial working directory is now added
to @ref{194,,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 Changes in the Python API<8>,Changes in the C API<6>,Changes in Python Behavior,Porting to Python 3 7
@anchor{whatsnew/3 7 changes-in-the-python-api}@anchor{fbc}
@subsubsection Changes in the Python API



@itemize *

@item 
@ref{f35,,socketserver.ThreadingMixIn.server_close} now waits until all
non-daemon threads complete.  Set the new
@ref{f36,,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 
@ref{f35,,socketserver.ForkingMixIn.server_close} now waits until all
child processes complete. Set the new
@ref{f36,,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{fbd,,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{fbe,,pkgutil.walk_packages()} now raises a @ref{277,,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{fbf,,string.Formatter.format()}
is now @ref{e47,,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{fc0,,key},
@ref{fc1,,value} and
@ref{fc2,,coded_value} of class
@ref{fc3,,http.cookies.Morsel} are now read-only.
Assigning to them was deprecated in Python 3.5.
Use the @ref{fc4,,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{72f,,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{fc5,,struct.Struct.format} type is now @ref{1df,,str} instead of
@ref{1c7,,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{d4,,socket}, calling @ref{fc6,,socket.fromshare()}
on a socket created by @ref{fc7,,socket.share} in older
Python versions is not supported.

@item 
@code{repr} for @ref{9b9,,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{d94,,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{335,,shutil.rmtree()} is now implemented using the @ref{e23,,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{847,,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{c1,,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{847,,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{7a1,,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{fc8,,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{f55,,tracemalloc.Traceback} frames are now sorted from oldest to most
recent to be more consistent with @ref{107,,traceback}.
(Contributed by Jesse Bakker in bpo-32121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32121}.)

@item 
On OSes that support @ref{fc9,,socket.SOCK_NONBLOCK} or
@ref{fca,,socket.SOCK_CLOEXEC} bit flags, the
@ref{fcb,,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{6bf,,subprocess.Popen} was changed from @ref{ef5,,False} to @ref{fcc,,True}
when redirecting the standard handles. If you previously depended on handles
being inherited when using @code{subprocess.Popen} with standard io
redirection, you will have to pass @code{close_fds=False} to preserve the
previous behaviour, or use
@ref{fcd,,STARTUPINFO.lpAttributeList}.

@item 
@ref{fce,,importlib.machinery.PathFinder.invalidate_caches()} – which implicitly
affects @ref{fcf,,importlib.invalidate_caches()} – now deletes entries
in @ref{9db,,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{b,,asyncio},
@ref{fd0,,loop.sock_recv()},
@ref{fd1,,loop.sock_sendall()},
@ref{fd2,,loop.sock_accept()},
@ref{fd3,,loop.getaddrinfo()},
@ref{fd4,,loop.getnameinfo()}
have been changed to be proper coroutine methods to match their
documentation.  Previously, these methods returned @ref{f8b,,asyncio.Future}
instances.
(Contributed by Yury Selivanov in bpo-32327@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32327}.)

@item 
@ref{fd5,,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{fc5,,Struct.format} is now a @ref{1df,,str} instance
instead of a @ref{1c7,,bytes} instance.
(Contributed by Victor Stinner in bpo-21071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21071}.)

@item 
@ref{7,,argparse} subparsers can now be made mandatory by passing @code{required=True}
to @ref{fd6,,ArgumentParser.add_subparsers()}.
(Contributed by Anthony Sottile in bpo-26510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26510}.)

@item 
@ref{fd7,,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{fd8,,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{fd9,,Calendar.itermonthdays3} and
@ref{fda,,Calendar.itermonthdays4} can be used.
The new methods return tuples and are not restricted by the range supported by
@ref{48d,,datetime.date}.
(Contributed by Alexander Belopolsky in bpo-28292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28292}.)

@item 
@ref{fdb,,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{b27,,concurrent.futures.ThreadPoolExecutor}
and @ref{206,,concurrent.futures.ProcessPoolExecutor} now raises
a @ref{30d,,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{6e4,,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 Changes in the C API<6>,CPython bytecode changes<7>,Changes in the Python API<8>,Porting to Python 3 7
@anchor{whatsnew/3 7 changes-in-the-c-api}@anchor{fdc}
@subsubsection Changes in the C API


The function @ref{644,,PySlice_GetIndicesEx()} is considered unsafe for
resizable sequences.  If the slice indices are not instances of @ref{326,,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{645,,PySlice_Unpack()} and
@ref{646,,PySlice_AdjustIndices()}.
(Contributed by Serhiy Storchaka in bpo-27867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27867}.)

@node CPython bytecode changes<7>,Windows-only Changes<2>,Changes in the C API<6>,Porting to Python 3 7
@anchor{whatsnew/3 7 cpython-bytecode-changes}@anchor{fdd}
@subsubsection CPython bytecode changes


There are two new opcodes: @code{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,CPython bytecode changes<7>,Porting to Python 3 7
@anchor{whatsnew/3 7 id12}@anchor{fde}
@subsubsection Windows-only Changes


The file used to override @ref{194,,sys.path} is now called
@code{<python-executable>._pth} instead of @code{'sys.path'}.
See @ref{fdf,,Εύρεση 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{fe0}
@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{61a,,Py_BytesWarningFlag} to a value greater than one is no longer
sufficient to both emit @ref{2ee,,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{fe1}
@subsection Notable changes in Python 3.7.1


Starting in 3.7.1, @ref{673,,Py_Initialize()} now consistently reads and respects
all of the same environment settings as @ref{fe2,,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{61d,,Py_IgnoreEnvironmentFlag} to 1 before
calling @code{Py_Initialize()}.

In 3.7.1 the C API for Context Variables
@ref{fe3,,was updated} to use
@ref{19b,,PyObject} pointers.  See also bpo-34762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34762}.

In 3.7.1 the @ref{104,,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{fe4}
@subsection Notable changes in Python 3.7.2


In 3.7.2, @ref{11a,,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{fe5}
@subsection Notable changes in Python 3.7.6


Due to significant security concerns, the `reuse_address' parameter of
@ref{b1a,,asyncio.loop.create_datagram_endpoint()} is no longer supported. This is
because of the behavior of the socket option @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}.)

@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{fe6}
@subsection Notable changes in Python 3.7.10


Earlier Python versions allowed using both @code{;} and @code{&} as
query parameter separators in @ref{589,,urllib.parse.parse_qs()} and
@ref{588,,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{fe7}
@subsection Notable changes in Python 3.7.11


A security fix alters the @ref{cca,,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{113,,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{fe8}
@subsection Notable security feature in 3.7.14


Converting between @ref{326,,int} and @ref{1df,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{277,,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{e2,,sys} APIs. See the @ref{9ec,,integer string conversion length limitation} documentation.  The default limit
is 4300 digits in string form.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 6,What’s New In Python 3 5,What’s New In Python 3 7,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 6 doc}@anchor{fe9}@anchor{whatsnew/3 6 translation-repo}@anchor{fea}@anchor{whatsnew/3 6 what-s-new-in-python-3-6}@anchor{feb}
@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 Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 494
PEP 494@footnote{https://peps.python.org/pep-0494/} - Python 3.6 Release Schedule


@menu
* Summary – Release highlights: Summary – Release highlights<8>. 
* New Features: New Features<13>. 
* Other Language Changes: Other Language Changes<8>. 
* New Modules: New Modules<8>. 
* Improved Modules: Improved Modules<8>. 
* Optimizations: Optimizations<11>. 
* Build and C API Changes: Build and C API Changes<2>. 
* Other Improvements:: 
* Deprecated: Deprecated<12>. 
* Removed: Removed<12>. 
* 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 Summary – Release highlights<8>,New Features<13>,,What’s New In Python 3 6
@anchor{whatsnew/3 6 summary-release-highlights}@anchor{fec}
@subsection Summary – Release highlights


New syntax features:


@itemize *

@item 
@ref{fed,,PEP 498}, formatted string literals.

@item 
@ref{fee,,PEP 515}, underscores in numeric literals.

@item 
@ref{fef,,PEP 526}, syntax for variable annotations.

@item 
@ref{ff0,,PEP 525}, asynchronous generators.

@item 
@ref{ff1,,PEP 530}: asynchronous comprehensions.
@end itemize

New library modules:


@itemize *

@item 
@ref{c8,,secrets}: @ref{ff2,,PEP 506 – Adding A Secrets Module To The Standard Library}.
@end itemize

CPython implementation improvements:


@itemize *

@item 
The @ref{e8c,,dict} type has been reimplemented to use
a @ref{ff3,,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{ff4,,new protocol}.

@item 
The class attribute definition order is
@ref{ff5,,now preserved}.

@item 
The order of elements in @code{**kwargs} now
@ref{ff6,,corresponds to the order} in which keyword
arguments were passed to the function.

@item 
DTrace and SystemTap @ref{ff7,,probing support} has
been added.

@item 
The new @ref{ff8,,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{b,,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{ff9,,file system path protocol} has been
implemented to support @ref{79f,,path-like objects}.
All standard library functions operating on paths have been updated to
work with the new protocol.

@item 
The @ref{33,,datetime} module has gained support for
@ref{ffa,,Local Time Disambiguation}.

@item 
The @ref{10d,,typing} module received a number of
@ref{ffb,,improvements}.

@item 
The @ref{108,,tracemalloc} module has been significantly reworked
and is now used to provide better output for @ref{74f,,ResourceWarning}
as well as provide better diagnostics for memory allocation errors.
See the @ref{ff8,,PYTHONMALLOC section} for more
information.
@end itemize

Security improvements:


@itemize *

@item 
The new @ref{c8,,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{931,,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{6b,,hashlib} and @ref{d8,,ssl} modules now support OpenSSL 1.1.0.

@item 
The default settings and feature set of the @ref{d8,,ssl} module have been
improved.

@item 
The @ref{6b,,hashlib} module received support for the BLAKE2, SHA-3 and SHAKE
hash algorithms and the @ref{ffc,,scrypt()} key derivation function.
@end itemize

Windows improvements:


@itemize *

@item 
@ref{ffd,,PEP 528} and @ref{ffe,,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{fff,,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{fdf,,the documentation} for more information.

@item 
A @code{python36.zip} file now works as a landmark to infer
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME}. See @ref{fdf,,the documentation} for
more information.
@end itemize

@node New Features<13>,Other Language Changes<8>,Summary – Release highlights<8>,What’s New In Python 3 6
@anchor{whatsnew/3 6 new-features}@anchor{1000}@anchor{whatsnew/3 6 pypy-dict-implementation}@anchor{1001}
@subsection New Features


@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,,New Features<13>
@anchor{whatsnew/3 6 pep-498-formatted-string-literals}@anchor{1002}@anchor{whatsnew/3 6 whatsnew36-pep498}@anchor{fed}
@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{43a,,formatted string literals}.

Formatted string literals are prefixed with @code{'f'} and are similar to
the format strings accepted by @ref{a12,,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{439,,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 Δείτε επίσης



@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{43a,,Feature documentation}.


@node PEP 526 Syntax for variable annotations,PEP 515 Underscores in Numeric Literals,PEP 498 Formatted string literals,New Features<13>
@anchor{whatsnew/3 6 pep-526-syntax-for-variable-annotations}@anchor{1003}@anchor{whatsnew/3 6 whatsnew36-pep526}@anchor{fef}
@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 Δείτε επίσης



@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,New Features<13>
@anchor{whatsnew/3 6 pep-515-underscores-in-numeric-literals}@anchor{1004}@anchor{whatsnew/3 6 whatsnew36-pep515}@anchor{fee}
@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{6fe,,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 Δείτε επίσης



@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,New Features<13>
@anchor{whatsnew/3 6 pep-525-asynchronous-generators}@anchor{1005}@anchor{whatsnew/3 6 whatsnew36-pep525}@anchor{ff0}
@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 Δείτε επίσης



@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,New Features<13>
@anchor{whatsnew/3 6 pep-530-asynchronous-comprehensions}@anchor{1006}@anchor{whatsnew/3 6 whatsnew36-pep530}@anchor{ff1}
@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 Δείτε επίσης



@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,New Features<13>
@anchor{whatsnew/3 6 pep-487-simpler-customization-of-class-creation}@anchor{1007}@anchor{whatsnew/3 6 whatsnew36-pep487}@anchor{ff4}
@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{443,,super()} calls to work correctly from
@ref{a22,,__init_subclass__()} implementations, custom metaclasses must
ensure that the new @code{__classcell__} namespace entry is propagated to
@code{type.__new__} (as described in @ref{1008,,Δημιουργία αντικειμένου κλάσης}).


@subsubheading Δείτε επίσης



@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{1009,,Feature documentation}


@node PEP 487 Descriptor Protocol Enhancements,PEP 519 Adding a file system path protocol,PEP 487 Simpler customization of class creation,New Features<13>
@anchor{whatsnew/3 6 pep-487-descriptor-protocol-enhancements}@anchor{100a}@anchor{whatsnew/3 6 whatsnew36-pep487-descriptors}@anchor{100b}
@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{100c,,__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 Δείτε επίσης



@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{100d,,Feature documentation}


@node PEP 519 Adding a file system path protocol,PEP 495 Local Time Disambiguation,PEP 487 Descriptor Protocol Enhancements,New Features<13>
@anchor{whatsnew/3 6 pep-519-adding-a-file-system-path-protocol}@anchor{100e}@anchor{whatsnew/3 6 whatsnew36-pep519}@anchor{ff9}
@subsubsection PEP 519: Adding a file system path protocol


File system paths have historically been represented as @ref{1df,,str}
or @ref{1c7,,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{326,,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{a8,,pathlib} from working with pre-existing code,
including Python’s standard library.

To fix this situation, a new interface represented by
@ref{100f,,os.PathLike} has been defined. By implementing the
@ref{1010,,__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{1df,,str} or
@ref{1c7,,bytes} object. This means an object is considered
@ref{79f,,path-like} if it implements
@code{os.PathLike} or is a @code{str} or @code{bytes} object
which represents a file system path. Code can use @ref{1011,,os.fspath()},
@ref{1012,,os.fsdecode()}, or @ref{1013,,os.fsencode()} to explicitly get a
@code{str} and/or @code{bytes} representation of a path-like
object.

The built-in @ref{32b,,open()} function has been updated to accept
@ref{100f,,os.PathLike} objects, as have all relevant functions in the
@ref{a5,,os} and @ref{a6,,os.path} modules, and most other functions and
classes in the standard library.  The @ref{8ac,,os.DirEntry} class
and relevant classes in @ref{a8,,pathlib} have also been updated to
implement @code{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{79f,,path-like objects} without any
code changes, or at least very minimal ones (e.g. calling
@ref{1011,,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{4ee,,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 Δείτε επίσης



@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,New Features<13>
@anchor{whatsnew/3 6 pep-495-local-time-disambiguation}@anchor{1014}@anchor{whatsnew/3 6 whatsnew36-pep495}@anchor{ffa}
@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{6e7,,datetime.datetime} and @ref{48e,,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{1015,,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 Δείτε επίσης



@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,New Features<13>
@anchor{whatsnew/3 6 pep-529-change-windows-filesystem-encoding-to-utf-8}@anchor{1016}@anchor{whatsnew/3 6 whatsnew36-pep529}@anchor{ffe}
@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{1017,,sys.getfilesystemencoding()}, which now defaults to @code{'utf-8'}.

Applications that do not use str to represent paths should use
@ref{1013,,os.fsencode()} and @ref{1012,,os.fsdecode()} to ensure their bytes are
correctly encoded. To revert to the previous behaviour, set
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,PYTHONLEGACYWINDOWSFSENCODING} or call
@ref{30e,,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,New Features<13>
@anchor{whatsnew/3 6 pep-528-change-windows-console-encoding-to-utf-8}@anchor{1018}@anchor{whatsnew/3 6 whatsnew36-pep528}@anchor{ffd}
@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 μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSSTDIO
@ref{1019,,PYTHONLEGACYWINDOWSSTDIO}.


@subsubheading Δείτε επίσης



@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,New Features<13>
@anchor{whatsnew/3 6 pep-520-preserving-class-attribute-definition-order}@anchor{101a}@anchor{whatsnew/3 6 whatsnew36-pep520}@anchor{ff5}
@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{101b,,__dict__} attribute.

Also, the effective default class `execution' namespace (returned from
@ref{101c,,type.__prepare__()}) is now an insertion-order-preserving
mapping.


@subsubheading Δείτε επίσης



@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,New Features<13>
@anchor{whatsnew/3 6 pep-468-preserving-keyword-argument-order}@anchor{101d}@anchor{whatsnew/3 6 whatsnew36-pep468}@anchor{ff6}
@subsubsection PEP 468: Preserving Keyword Argument Order


@code{**kwargs} in a function signature is now guaranteed to be an
insertion-order-preserving mapping.


@subsubheading Δείτε επίσης



@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,New Features<13>
@anchor{whatsnew/3 6 new-dict-implementation}@anchor{101e}@anchor{whatsnew/3 6 whatsnew36-compactdict}@anchor{ff3}
@subsubsection New dict implementation


The @ref{e8c,,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{188,,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,New Features<13>
@anchor{whatsnew/3 6 pep-523-adding-a-frame-evaluation-api-to-cpython}@anchor{101f}@anchor{whatsnew/3 6 whatsnew36-pep523}@anchor{1020}
@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 Δείτε επίσης



@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,New Features<13>
@anchor{whatsnew/3 6 pythonmalloc-environment-variable}@anchor{1021}@anchor{whatsnew/3 6 whatsnew36-pythonmalloc}@anchor{ff8}
@subsubsection PYTHONMALLOC environment variable


The new 
@geindex PYTHONMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,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{1023,,PyObject_Free()} called on a memory block allocated by
@ref{1024,,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{685,,GIL} is held when allocator
functions of @ref{1025,,PYMEM_DOMAIN_OBJ} (ex: @ref{1026,,PyObject_Malloc()}) and
@ref{1027,,PYMEM_DOMAIN_MEM} (ex: @ref{1024,,PyMem_Malloc()}) domains are called.
@end itemize

Checking if the GIL is held is also a new feature of Python 3.6.

See the @ref{1028,,PyMem_SetupDebugHooks()} function for debug hooks on Python
memory allocators.

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{108,,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,New Features<13>
@anchor{whatsnew/3 6 dtrace-and-systemtap-probing-support}@anchor{1029}@anchor{whatsnew/3 6 whatsnew36-tracing}@anchor{ff7}
@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{3dc,,debug builds} or
providing application-specific profiling/debugging code.

More details in @ref{102a,,Instrumenting CPython with DTrace and 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 Other Language Changes<8>,New Modules<8>,New Features<13>,What’s New In Python 3 6
@anchor{whatsnew/3 6 other-language-changes}@anchor{102b}
@subsection Other Language Changes


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{44a,,SyntaxWarning}.

@item 
It is now possible to set a @ref{102c,,special method} to
@code{None} to indicate that the corresponding operation is not available.
For example, if a class sets @ref{102d,,__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{102e,,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{1be,,ModuleNotFoundError}
(subclass of @ref{1bd,,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 New Modules<8>,Improved Modules<8>,Other Language Changes<8>,What’s New In Python 3 6
@anchor{whatsnew/3 6 new-modules}@anchor{102f}
@subsection New Modules


@menu
* secrets:: 

@end menu

@node secrets,,,New Modules<8>
@anchor{whatsnew/3 6 secrets}@anchor{1030}@anchor{whatsnew/3 6 whatsnew36-pep506}@anchor{ff2}
@subsubsection secrets


The main purpose of the new @ref{c8,,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 Προειδοποίηση 
Note that the pseudo-random generators in the @ref{c0,,random} module
should `NOT' be used for security purposes.  Use @ref{c8,,secrets}
on Python 3.6+ and @ref{931,,os.urandom()} on Python 3.5 and earlier.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης



@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 Improved Modules<8>,Optimizations<11>,New Modules<8>,What’s New In Python 3 6
@anchor{whatsnew/3 6 improved-modules}@anchor{1031}
@subsection Improved Modules


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

@end menu

@node array<5>,ast<8>,,Improved Modules<8>
@anchor{whatsnew/3 6 array}@anchor{1032}
@subsubsection array


Exhausted iterators of @ref{6c5,,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<8>,asyncio<13>,array<5>,Improved Modules<8>
@anchor{whatsnew/3 6 ast}@anchor{1033}
@subsubsection ast


The new @ref{569,,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<13>,binascii<3>,ast<8>,Improved Modules<8>
@anchor{whatsnew/3 6 asyncio}@anchor{1034}
@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{b,,asyncio} module since Python 3.5.0
(all backported to 3.5.x due to the provisional status):


@itemize *

@item 
The @ref{56c,,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{1035,,ensure_future()} function and all functions that
use it, such as @ref{1036,,loop.run_until_complete()},
now accept all kinds of @ref{6cf,,awaitable objects}.
(Contributed by Yury Selivanov.)

@item 
New @ref{c58,,run_coroutine_threadsafe()} function to submit
coroutines to event loops from other threads.
(Contributed by Vincent Michel.)

@item 
New @ref{1037,,Transport.is_closing()}
method to check if the transport is closing or closed.
(Contributed by Yury Selivanov.)

@item 
The @ref{ed7,,loop.create_server()}
method can now accept a list of hosts.
(Contributed by Yann Sionneau.)

@item 
New @ref{1038,,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{f8b,,asyncio.Future} implementation.
(Contributed by Yury Selivanov in bpo-27041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27041}.)

@item 
New @ref{1039,,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{6d6,,StreamReader.readuntil()}
method to read data from the stream until a separator bytes
sequence appears.
(Contributed by Mark Korenberg.)

@item 
The performance of @ref{103a,,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{fd3,,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{103b,,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 
@ref{103c,,Future.set_exception}
will now raise @ref{291,,TypeError} when passed an instance of
the @ref{fba,,StopIteration} exception.
(Contributed by Chris Angelico in bpo-26221@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26221}.)

@item 
New @ref{bbb,,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{103d,,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{f8b,,Future} and @ref{460,,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<3>,cmath,asyncio<13>,Improved Modules<8>
@anchor{whatsnew/3 6 binascii}@anchor{103e}
@subsubsection binascii


The @ref{1fc,,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<5>,binascii<3>,Improved Modules<8>
@anchor{whatsnew/3 6 cmath}@anchor{103f}
@subsubsection cmath


The new @ref{1040,,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{1041,,cmath.inf} and @ref{1042,,cmath.nan} to
match @ref{1043,,math.inf} and @ref{a53,,math.nan}, and also @ref{1044,,cmath.infj}
and @ref{1045,,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<5>,concurrent futures<6>,cmath,Improved Modules<8>
@anchor{whatsnew/3 6 collections}@anchor{1046}
@subsubsection collections


The new @ref{1047,,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{1048,,Reversible} abstract base class represents
iterable classes that also provide the @ref{1049,,__reversed__()} method.
(Contributed by Ivan Levkivskyi in bpo-25987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25987}.)

The new @ref{104a,,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{1cf,,namedtuple()} function now accepts an optional
keyword argument `module', which, when specified, is used for
the @ref{80b,,__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{1cf,,namedtuple()} are now keyword-only.
(Contributed by Raymond Hettinger in bpo-25628@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25628}.)

Recursive @ref{9d6,,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<6>,contextlib<5>,collections<5>,Improved Modules<8>
@anchor{whatsnew/3 6 concurrent-futures}@anchor{104b}
@subsubsection concurrent.futures


The @ref{b27,,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<5>,datetime<7>,concurrent futures<6>,Improved Modules<8>
@anchor{whatsnew/3 6 contextlib}@anchor{104c}
@subsubsection contextlib


The @ref{104d,,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{10d,,typing} module as
@ref{104e,,typing.ContextManager}.
(Contributed by Brett Cannon in bpo-25609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25609}.)

@node datetime<7>,decimal<3>,contextlib<5>,Improved Modules<8>
@anchor{whatsnew/3 6 datetime}@anchor{104f}
@subsubsection datetime


The @ref{6e7,,datetime} and @ref{48e,,time} classes have
the new @ref{1050,,fold} attribute used to disambiguate local time
when necessary.  Many functions in the @ref{33,,datetime} have been
updated to support local time disambiguation.
See @ref{ffa,,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{1051,,datetime.strftime()} and
@ref{1052,,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{eef,,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{1053,,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<3>,distutils<5>,datetime<7>,Improved Modules<8>
@anchor{whatsnew/3 6 decimal}@anchor{1054}
@subsubsection decimal


New @ref{1055,,Decimal.as_integer_ratio()}
method that returns a pair @code{(n, d)} of integers that represent the given
@ref{1c2,,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<4>,decimal<3>,Improved Modules<8>
@anchor{whatsnew/3 6 distutils}@anchor{1056}
@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<4>,encodings<2>,distutils<5>,Improved Modules<8>
@anchor{whatsnew/3 6 email}@anchor{1057}
@subsubsection email


The new email API, enabled via the `policy' keyword to various constructors, is
no longer provisional.  The @ref{3e,,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{48,,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{1058,,DecodedGenerator} now supports the `policy'
keyword.

There is a new @ref{52,,policy} attribute,
@ref{1059,,message_factory}, that controls what class is used
by default when the parser creates new message objects.  For the
@ref{105a,,email.policy.compat32} policy this is @ref{780,,Message},
for the new policies it is @ref{216,,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<4>,Improved Modules<8>
@anchor{whatsnew/3 6 encodings}@anchor{105b}
@subsubsection 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<4>,encodings<2>,Improved Modules<8>
@anchor{whatsnew/3 6 enum}@anchor{105c}
@subsubsection enum


Two new enumeration base classes have been added to the @ref{59,,enum} module:
@ref{a14,,Flag} and @ref{105d,,IntFlag}.  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
@ref{105d,,IntFlag} class for their constants.

The new @ref{105e,,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<4>,fileinput<2>,enum<7>,Improved Modules<8>
@anchor{whatsnew/3 6 faulthandler}@anchor{105f}
@subsubsection faulthandler


On Windows, the @ref{5b,,faulthandler} module now installs a handler for Windows
exceptions: see @ref{219,,faulthandler.enable()}. (Contributed by Victor Stinner in
bpo-23848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23848}.)

@node fileinput<2>,hashlib<6>,faulthandler<4>,Improved Modules<8>
@anchor{whatsnew/3 6 fileinput}@anchor{1060}
@subsubsection fileinput


@ref{1061,,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<6>,http client<3>,fileinput<2>,Improved Modules<8>
@anchor{whatsnew/3 6 hashlib}@anchor{1062}
@subsubsection hashlib


@ref{6b,,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{a31,,blake2b()}
and @ref{a32,,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{1063,,sha3_224()}, @ref{1064,,sha3_256()},
@ref{1065,,sha3_384()}, @ref{1066,,sha3_512()}, and SHAKE hash functions
@ref{1067,,shake_128()} and @ref{1068,,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{ffc,,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<3>,idlelib and IDLE<2>,hashlib<6>,Improved Modules<8>
@anchor{whatsnew/3 6 http-client}@anchor{1069}
@subsubsection http.client


@ref{106a,,HTTPConnection.request()} and
@ref{106b,,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<3>,Improved Modules<8>
@anchor{whatsnew/3 6 idlelib-and-idle}@anchor{106c}
@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<8>,idlelib and IDLE<2>,Improved Modules<8>
@anchor{whatsnew/3 6 importlib}@anchor{106d}
@subsubsection importlib


Import now raises the new exception @ref{1be,,ModuleNotFoundError}
(subclass of @ref{1bd,,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{106e,,importlib.util.LazyLoader} now calls
@ref{106f,,create_module()} on the wrapped loader, removing the
restriction that @ref{1070,,importlib.machinery.BuiltinImporter} and
@ref{1071,,importlib.machinery.ExtensionFileLoader} couldn’t be used with
@code{importlib.util.LazyLoader}.

@ref{330,,importlib.util.cache_from_source()},
@ref{929,,importlib.util.source_from_cache()}, and
@ref{1072,,importlib.util.spec_from_file_location()} now accept a
@ref{79f,,path-like object}.

@node inspect<8>,json<3>,importlib<6>,Improved Modules<8>
@anchor{whatsnew/3 6 inspect}@anchor{1073}
@subsubsection inspect


The @ref{4bd,,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{b1f,,inspect.getfullargspec()} has been reversed. While this function is
convenient for single/source Python 2/3 code bases, the richer
@ref{4bd,,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<3>,logging<4>,inspect<8>,Improved Modules<8>
@anchor{whatsnew/3 6 json}@anchor{1074}
@subsubsection json


@ref{22e,,json.load()} and @ref{22f,,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<9>,json<3>,Improved Modules<8>
@anchor{whatsnew/3 6 logging}@anchor{1075}
@subsubsection logging


The new @ref{1076,,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<9>,multiprocessing<6>,logging<4>,Improved Modules<8>
@anchor{whatsnew/3 6 math}@anchor{1077}
@subsubsection math


The tau (`τ') constant has been added to the @ref{91,,math} and @ref{19,,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<6>,os<10>,math<9>,Improved Modules<8>
@anchor{whatsnew/3 6 multiprocessing}@anchor{1078}
@subsubsection multiprocessing


@ref{4d8,,Proxy Objects} returned by
@ref{4dc,,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<10>,pathlib<13>,multiprocessing<6>,Improved Modules<8>
@anchor{whatsnew/3 6 os}@anchor{1079}
@subsubsection os


See the summary of @ref{ff9,,PEP 519} for details on how the
@ref{a5,,os} and @ref{a6,,os.path} modules now support
@ref{79f,,path-like objects}.

@ref{e23,,scandir()} now supports @ref{1c7,,bytes} paths on Windows.

A new @ref{107a,,close()} method allows explicitly closing a
@ref{e23,,scandir()} iterator.  The @code{scandir()} iterator now
supports the @ref{478,,context manager} protocol.  If a @code{scandir()}
iterator is neither exhausted nor explicitly closed a @ref{74f,,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{931,,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{107b,,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<13>,pdb<8>,os<10>,Improved Modules<8>
@anchor{whatsnew/3 6 pathlib}@anchor{107c}
@subsubsection pathlib


@ref{a8,,pathlib} now supports @ref{79f,,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{ff9,,PEP 519} for details.

@node pdb<8>,pickle<4>,pathlib<13>,Improved Modules<8>
@anchor{whatsnew/3 6 pdb}@anchor{107d}
@subsubsection pdb


The @ref{4fb,,Pdb} class constructor has a new optional `readrc' argument
to control whether @code{.pdbrc} files should be read.

@node pickle<4>,pickletools<2>,pdb<8>,Improved Modules<8>
@anchor{whatsnew/3 6 pickle}@anchor{107e}
@subsubsection pickle


Objects that need @code{__new__} called with keyword arguments can now be pickled
using @ref{503,,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<2>,pydoc<4>,pickle<4>,Improved Modules<8>
@anchor{whatsnew/3 6 pickletools}@anchor{107f}
@subsubsection pickletools


@ref{1080,,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<4>,random<4>,pickletools<2>,Improved Modules<8>
@anchor{whatsnew/3 6 pydoc}@anchor{1081}
@subsubsection pydoc


The @ref{bd,,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{ca9,,help()} and @ref{bd,,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<7>,pydoc<4>,Improved Modules<8>
@anchor{whatsnew/3 6 random}@anchor{1082}
@subsubsection random


The new @ref{1083,,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<7>,readline,random<4>,Improved Modules<8>
@anchor{whatsnew/3 6 re}@anchor{1084}
@subsubsection 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{1085,,Match} objects now support
@ref{43d,,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<7>,Improved Modules<8>
@anchor{whatsnew/3 6 readline}@anchor{1086}
@subsubsection readline


Added @ref{1087,,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,Improved Modules<8>
@anchor{whatsnew/3 6 rlcompleter}@anchor{1088}
@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,Improved Modules<8>
@anchor{whatsnew/3 6 shlex}@anchor{1089}
@subsubsection shlex


The @ref{108a,,shlex} has much
@ref{108b,,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<9>,shlex<2>,Improved Modules<8>
@anchor{whatsnew/3 6 site}@anchor{108c}
@subsubsection site


When specifying paths to add to @ref{194,,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<9>,socket<9>,site<3>,Improved Modules<8>
@anchor{whatsnew/3 6 sqlite3}@anchor{108d}
@subsubsection sqlite3


@ref{108e,,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<9>,socketserver<2>,sqlite3<9>,Improved Modules<8>
@anchor{whatsnew/3 6 socket}@anchor{108f}
@subsubsection socket


The @ref{1090,,ioctl()} function now supports the
@ref{1091,,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{1092,,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{1093,,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{1094,,AF_ALG} to interface with Linux Kernel crypto API. @code{ALG_*},
@code{SOL_ALG} and @ref{1095,,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<9>,socket<9>,Improved Modules<8>
@anchor{whatsnew/3 6 socketserver}@anchor{1096}
@subsubsection socketserver


Servers based on the @ref{d5,,socketserver} module, including those
defined in @ref{75,,http.server}, @ref{138,,xmlrpc.server} and
@ref{124,,wsgiref.simple_server}, now support the @ref{478,,context manager}
protocol.
(Contributed by Aviv Palivoda in bpo-26404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26404}.)

The @ref{1097,,wfile} attribute of
@ref{1098,,StreamRequestHandler} classes now implements
the @ref{a83,,io.BufferedIOBase} writable interface.  In particular,
calling @ref{1099,,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<9>,statistics<5>,socketserver<2>,Improved Modules<8>
@anchor{whatsnew/3 6 ssl}@anchor{109a}
@subsubsection ssl


@ref{d8,,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{336,,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{109b,,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{109c,,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{109d,,IntEnum} and
@ref{105d,,IntFlag}.
(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{336,,SSLContext}
were added.
(Contributed by Christian Heimes in bpo-28085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28085}.)

Added @ref{df5,,ssl.SSLContext.post_handshake_auth} to enable and
@ref{df6,,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<2>,ssl<9>,Improved Modules<8>
@anchor{whatsnew/3 6 statistics}@anchor{109e}
@subsubsection statistics


A new @ref{109f,,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<2>,subprocess<4>,statistics<5>,Improved Modules<8>
@anchor{whatsnew/3 6 struct}@anchor{10a0}
@subsubsection struct


@ref{de,,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<4>,sys<11>,struct<2>,Improved Modules<8>
@anchor{whatsnew/3 6 subprocess}@anchor{10a1}
@subsubsection subprocess


@ref{6bf,,subprocess.Popen} destructor now emits a @ref{74f,,ResourceWarning} warning
if the child process is still running. Use the context manager protocol (@code{with
proc: ...}) or explicitly call the @ref{266,,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{6bf,,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<11>,telnetlib,subprocess<4>,Improved Modules<8>
@anchor{whatsnew/3 6 sys}@anchor{10a2}
@subsubsection sys


The new @ref{10a3,,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{10a4,,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<11>,Improved Modules<8>
@anchor{whatsnew/3 6 telnetlib}@anchor{10a5}
@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<2>,telnetlib,Improved Modules<8>
@anchor{whatsnew/3 6 time}@anchor{10a6}
@subsubsection time


The @ref{10a7,,struct_time} attributes @code{tm_gmtoff} and
@code{tm_zone} are now available on all platforms.

@node timeit<2>,tkinter<8>,time<6>,Improved Modules<8>
@anchor{whatsnew/3 6 timeit}@anchor{10a8}
@subsubsection timeit


The new @ref{283,,Timer.autorange()} convenience
method has been added to call @ref{10a9,,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{f8,,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<8>,traceback<4>,timeit<2>,Improved Modules<8>
@anchor{whatsnew/3 6 tkinter}@anchor{10aa}
@subsubsection tkinter


Added methods @code{Variable.trace_add()},
@code{Variable.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<8>,Improved Modules<8>
@anchor{whatsnew/3 6 traceback}@anchor{10ab}@anchor{whatsnew/3 6 whatsnew36-traceback}@anchor{102e}
@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<12>,traceback<4>,Improved Modules<8>
@anchor{whatsnew/3 6 tracemalloc}@anchor{10ac}
@subsubsection tracemalloc


The @ref{108,,tracemalloc} module now supports tracing memory allocations in
multiple different address spaces.

The new @ref{10ad,,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<12>,unicodedata<9>,tracemalloc<3>,Improved Modules<8>
@anchor{whatsnew/3 6 typing}@anchor{10ae}@anchor{whatsnew/3 6 whatsnew36-typing}@anchor{ffb}
@subsubsection typing


Since the @ref{10d,,typing} module is @ref{5fd,,provisional},
all changes introduced in Python 3.6 have also been
backported to Python 3.5.x.

The @ref{10d,,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{104e,,typing.ContextManager} class has been added for
representing @ref{104d,,contextlib.AbstractContextManager}.
(Contributed by Brett Cannon in bpo-25609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25609}.)

The @ref{10af,,typing.Collection} class has been added for
representing @ref{1047,,collections.abc.Collection}.
(Contributed by Ivan Levkivskyi in bpo-27598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27598}.)

The @ref{76e,,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{10b0,,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{10b1,,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<9>,unittest mock<2>,typing<12>,Improved Modules<8>
@anchor{whatsnew/3 6 unicodedata}@anchor{10b2}
@subsubsection unicodedata


The @ref{10e,,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<9>,Improved Modules<8>
@anchor{whatsnew/3 6 unittest-mock}@anchor{10b3}
@subsubsection unittest.mock


The @ref{e0e,,Mock} class has the following improvements:


@itemize *

@item 
Two new methods, @ref{10b4,,Mock.assert_called()} and @ref{10b5,,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{10b6,,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>,Improved Modules<8>
@anchor{whatsnew/3 6 urllib-request}@anchor{10b7}
@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, @ref{10b8,,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<6>,urllib request,Improved Modules<8>
@anchor{whatsnew/3 6 urllib-robotparser}@anchor{10b9}
@subsubsection urllib.robotparser


@ref{10ba,,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<6>,warnings<5>,urllib robotparser,Improved Modules<8>
@anchor{whatsnew/3 6 venv}@anchor{10bb}
@subsubsection venv


@ref{11a,,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<5>,winreg,venv<6>,Improved Modules<8>
@anchor{whatsnew/3 6 warnings}@anchor{10bc}
@subsubsection warnings


A new optional `source' parameter has been added to the
@ref{2ab,,warnings.warn_explicit()} function: the destroyed object which emitted a
@ref{74f,,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{74f,,ResourceWarning} warning is logged, the @ref{108,,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{108,,tracemalloc} is tracing Python memory allocations and if the
@ref{11b,,warnings} module was already imported.

@node winreg,winsound,warnings<5>,Improved Modules<8>
@anchor{whatsnew/3 6 winreg}@anchor{10bd}
@subsubsection winreg


Added the 64-bit integer type @ref{10be,,REG_QWORD}.
(Contributed by Clement Rouault in bpo-23026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23026}.)

@node winsound,xmlrpc client,winreg,Improved Modules<8>
@anchor{whatsnew/3 6 winsound}@anchor{10bf}
@subsubsection winsound


Allowed keyword arguments to be passed to @ref{10c0,,Beep},
@ref{10c1,,MessageBeep}, and @ref{10c2,,PlaySound} (bpo-27982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27982}).

@node xmlrpc client,zipfile<4>,winsound,Improved Modules<8>
@anchor{whatsnew/3 6 xmlrpc-client}@anchor{10c3}
@subsubsection xmlrpc.client


The @ref{137,,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<4>,zlib<3>,xmlrpc client,Improved Modules<8>
@anchor{whatsnew/3 6 zipfile}@anchor{10c4}
@subsubsection zipfile


A new @ref{10c5,,ZipInfo.from_file()} class method
allows making a @ref{547,,ZipInfo} instance from a filesystem file.
A new @ref{10c6,,ZipInfo.is_dir()} method can be used
to check if the @code{ZipInfo} instance represents a directory.
(Contributed by Thomas Kluyver in bpo-26039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26039}.)

The @ref{84a,,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<3>,,zipfile<4>,Improved Modules<8>
@anchor{whatsnew/3 6 zlib}@anchor{10c7}
@subsubsection zlib


The @ref{a2e,,compress()} and @ref{10c8,,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<11>,Build and C API Changes<2>,Improved Modules<8>,What’s New In Python 3 6
@anchor{whatsnew/3 6 optimizations}@anchor{10c9}
@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{f8b,,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{460,,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{10d,,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{434,,bytes.fromhex()} and @ref{435,,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{1024,,PyMem_Malloc()} domain
(@ref{1027,,PYMEM_DOMAIN_MEM}) now use the @ref{3da,,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{10ca,,pickle.load()} and @ref{10cb,,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{10cc,,keyword arguments} to a function has an
overhead in comparison with passing @ref{10cd,,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{2d4,,glob()} and @ref{be1,,iglob()} functions in the
@ref{67,,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{a8,,pathlib} by using @ref{e23,,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{12e,,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{1c3,,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>,Other Improvements,Optimizations<11>,What’s New In Python 3 6
@anchor{whatsnew/3 6 build-and-c-api-changes}@anchor{10ce}
@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{685,,GIL} must now be held when allocator
functions of @ref{1025,,PYMEM_DOMAIN_OBJ} (ex: @ref{1026,,PyObject_Malloc()}) and
@ref{1027,,PYMEM_DOMAIN_MEM} (ex: @ref{1024,,PyMem_Malloc()}) domains are called.

@item 
New @ref{10cf,,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{818,,PyArg_ParseTupleAndKeywords()} now supports @ref{e47,,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{10d0,,PyErr_SetImportErrorSubclass()} function allows for
specifying a subclass of @ref{1bd,,ImportError} to raise.
(Contributed by Eric Snow in bpo-15767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15767}.)

@item 
The new @ref{10d1,,PyErr_ResourceWarning()} function can be used to generate
a @ref{74f,,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{10d2,,PyOS_FSPath()} function returns the file system
representation of a @ref{79f,,path-like object}.
(Contributed by Brett Cannon in bpo-27186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27186}.)

@item 
The @ref{10d3,,PyUnicode_FSConverter()} and @ref{97b,,PyUnicode_FSDecoder()}
functions will now accept @ref{79f,,path-like objects}.
@end itemize

@node Other Improvements,Deprecated<12>,Build and C API Changes<2>,What’s New In Python 3 6
@anchor{whatsnew/3 6 other-improvements}@anchor{10d4}
@subsection Other Improvements



@itemize *

@item 
When @ref{10d5,,--version} (short form: @ref{6a7,,-V}) is supplied twice,
Python prints @ref{6a8,,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 Deprecated<12>,Removed<12>,Other Improvements,What’s New In Python 3 6
@anchor{whatsnew/3 6 deprecated}@anchor{10d6}
@subsection Deprecated


@menu
* New Keywords:: 
* Deprecated Python behavior:: 
* Deprecated Python modules@comma{} functions and methods: Deprecated Python modules functions and methods<2>. 
* xml: xml<7>. 
* Deprecated functions and types of the C API: Deprecated functions and types of the C API<2>. 
* Deprecated Build Options:: 

@end menu

@node New Keywords,Deprecated Python behavior,,Deprecated<12>
@anchor{whatsnew/3 6 new-keywords}@anchor{10d7}
@subsubsection New Keywords


@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{2c9,,DeprecationWarning}.

@node Deprecated Python behavior,Deprecated Python modules functions and methods<2>,New Keywords,Deprecated<12>
@anchor{whatsnew/3 6 deprecated-python-behavior}@anchor{10d8}
@subsubsection Deprecated Python behavior


Raising the @ref{fba,,StopIteration} exception inside a generator will now
generate a @ref{2c9,,DeprecationWarning}, and will trigger a @ref{30d,,RuntimeError}
in Python 3.7.  See @ref{10d9,,PEP 479; Change StopIteration handling inside generators} for details.

The @ref{fbb,,__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{2c9,,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{2c9,,DeprecationWarning}.  Although this will eventually become a
@ref{17e,,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{907,,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<7>,Deprecated Python behavior,Deprecated<12>
@anchor{whatsnew/3 6 deprecated-python-modules-functions-and-methods}@anchor{10da}
@subsubsection Deprecated Python modules, functions and methods


@menu
* asynchat:: 
* asyncore:: 
* dbm: dbm<5>. 
* distutils: distutils<6>. 
* grp:: 
* importlib: importlib<7>. 
* os: os<11>. 
* re: re<8>. 
* ssl: ssl<10>. 
* tkinter: tkinter<9>. 
* venv: venv<7>. 

@end menu

@node asynchat,asyncore,,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 asynchat}@anchor{10db}
@subsubsection asynchat


The @code{asynchat} has been deprecated in favor of @ref{b,,asyncio}.
(Contributed by Mariatta in bpo-25002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25002}.)

@node asyncore,dbm<5>,asynchat,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 asyncore}@anchor{10dc}
@subsubsection asyncore


The @code{asyncore} has been deprecated in favor of @ref{b,,asyncio}.
(Contributed by Mariatta in bpo-25002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25002}.)

@node dbm<5>,distutils<6>,asyncore,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 dbm}@anchor{10dd}
@subsubsection dbm


Unlike other @ref{34,,dbm} implementations, the @ref{35,,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<5>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id2}@anchor{10de}
@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{10df}
@subsubsection grp


The support of non-integer arguments in @ref{10e0,,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<11>,grp,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id3}@anchor{10e1}
@subsubsection importlib


The @code{importlib.machinery.SourceFileLoader.load_module} and
@code{importlib.machinery.SourcelessFileLoader.load_module} methods
are now deprecated. They were the only remaining implementations of
@code{importlib.abc.Loader.load_module} in @ref{7a,,importlib} that had not
been deprecated in previous versions of Python in favour of
@ref{c40,,importlib.abc.Loader.exec_module()}.

The @ref{10e2,,importlib.machinery.WindowsRegistryFinder} class is now
deprecated. As of 3.6.0, it is still added to @ref{10e3,,sys.meta_path} by
default (on Windows), but this may change in future releases.

@node os<11>,re<8>,importlib<7>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id4}@anchor{10e4}
@subsubsection os


Undocumented support of general @ref{436,,bytes-like objects}
as paths in @ref{a5,,os} functions, @ref{1c8,,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<8>,ssl<10>,os<11>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id5}@anchor{10e5}
@subsubsection 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<10>,tkinter<9>,re<8>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id6}@anchor{10e6}
@subsubsection ssl


OpenSSL 0.9.8, 1.0.0 and 1.0.1 are deprecated and no longer supported.
In the future the @ref{d8,,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{61,,ftplib}, @ref{72,,http.client}, @ref{77,,imaplib}, @ref{b1,,poplib},
and @ref{d2,,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{d8,,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<9>,venv<7>,ssl<10>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id7}@anchor{10e7}
@subsubsection tkinter


The @code{tkinter.tix} module is now deprecated.  @ref{f9,,tkinter} users
should use @ref{102,,tkinter.ttk} instead.

@node venv<7>,,tkinter<9>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id8}@anchor{10e8}@anchor{whatsnew/3 6 whatsnew36-venv}@anchor{10e9}
@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<7>,Deprecated functions and types of the C API<2>,Deprecated Python modules functions and methods<2>,Deprecated<12>
@anchor{whatsnew/3 6 xml}@anchor{10ea}
@subsubsection xml



@itemize *

@item 
As mitigation against DTD and external entity retrieval, the
@ref{12b,,xml.dom.minidom} and @ref{132,,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<7>,Deprecated<12>
@anchor{whatsnew/3 6 deprecated-functions-and-types-of-the-c-api}@anchor{10eb}
@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{10ec,,generic codec based API} instead.

@node Deprecated Build Options,,Deprecated functions and types of the C API<2>,Deprecated<12>
@anchor{whatsnew/3 6 deprecated-build-options}@anchor{10ed}
@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 Removed<12>,Porting to Python 3 6,Deprecated<12>,What’s New In Python 3 6
@anchor{whatsnew/3 6 removed}@anchor{10ee}
@subsection Removed


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

@end menu

@node API and Feature Removals<3>,,,Removed<12>
@anchor{whatsnew/3 6 api-and-feature-removals}@anchor{10ef}
@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{7a1,,re.sub()} they are still allowed, but deprecated.
The @ref{f29,,re.LOCALE} flag can now only be used with binary patterns.

@item 
@code{inspect.getmoduleinfo()} was removed (was deprecated since CPython 3.3).
@ref{10f0,,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{107,,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{f9,,tkinter} widget classes were removed (corresponding Tk commands
were obsolete since Tk 4.0).

@item 
The @ref{84a,,open()} method of the @ref{ab1,,zipfile.ZipFile}
class no longer supports the @code{'U'} mode (was deprecated since Python 3.4).
Use @ref{b9c,,io.TextIOWrapper} for reading compressed text files in
@ref{10f1,,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,Removed<12>,What’s New In Python 3 6
@anchor{whatsnew/3 6 porting-to-python-3-6}@anchor{10f2}
@subsection Porting to Python 3.6


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

@menu
* Changes in “python” Command Behavior:: 
* Changes in the Python API: Changes in the Python API<9>. 
* Changes in the C API: Changes in the C API<7>. 
* CPython bytecode changes: CPython bytecode changes<8>. 

@end menu

@node Changes in “python” Command Behavior,Changes in the Python API<9>,,Porting to Python 3 6
@anchor{whatsnew/3 6 changes-in-python-command-behavior}@anchor{10f3}
@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 Changes in the Python API<9>,Changes in the C API<7>,Changes in “python” Command Behavior,Porting to Python 3 6
@anchor{whatsnew/3 6 changes-in-the-python-api}@anchor{10f4}
@subsubsection Changes in the Python API



@itemize *

@item 
@ref{32b,,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{d7,,sqlite3} no longer implicitly commits an open transaction before DDL
statements.

@item 
On Linux, @ref{931,,os.urandom()} now blocks until the system urandom entropy pool
is initialized to increase the security.

@item 
When @ref{c40,,importlib.abc.Loader.exec_module()} is defined,
@ref{106f,,importlib.abc.Loader.create_module()} must also be defined.

@item 
@ref{10f5,,PyErr_SetImportError()} now sets @ref{291,,TypeError} when its `msg'
argument is not set. Previously only @code{NULL} was returned.

@item 
The format of the @code{codeobject.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{b8d,,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{21,,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{2a3,,urllib.parse.urlsplit()} and @ref{2a4,,urlparse()} results
now raises @ref{277,,ValueError} for out-of-range values, rather than
returning @ref{a65,,None}.  See bpo-20059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20059}.

@item 
The @code{imp} module now raises a @ref{2c9,,DeprecationWarning} instead of
@ref{c9b,,PendingDeprecationWarning}.

@item 
The following modules have had missing APIs added to their
@ref{10f6,,__all__} attributes to match the documented APIs:
@ref{15,,calendar}, @code{cgi}, @ref{2c,,csv},
@ref{12e,,ElementTree}, @ref{59,,enum},
@ref{5e,,fileinput}, @ref{61,,ftplib}, @ref{8a,,logging}, @ref{8e,,mailbox},
@ref{93,,mimetypes}, @ref{a4,,optparse}, @ref{b0,,plistlib}, @code{smtpd},
@ref{df,,subprocess}, @ref{e7,,tarfile}, @ref{f6,,threading} and
@ref{11c,,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{907,,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{1bd,,ImportError} will be raised. Previously, @ref{3ea,,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{d5,,socketserver} module, including those
defined in @ref{75,,http.server}, @ref{138,,xmlrpc.server} and
@ref{124,,wsgiref.simple_server}, now only catch exceptions derived
from @ref{d9e,,Exception}. Therefore if a request handler raises
an exception like @ref{10f7,,SystemExit} or @ref{d96,,KeyboardInterrupt},
@ref{10f8,,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{10f9,,PermissionError} instead of
@ref{7df,,KeyError} if the user doesn’t have privileges.

@item 
The @ref{10fa,,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{10fb,,dump()}, @ref{248,,dumps()},
@ref{22e,,load()} and @ref{22f,,loads()} functions and
@ref{10fc,,JSONEncoder} and @ref{10fd,,JSONDecoder} class
constructors in the @ref{85,,json} module are now @ref{7a3,,keyword-only}.
(Contributed by Serhiy Storchaka in bpo-18726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18726}.)

@item 
Subclasses of @ref{186,,type} which don’t override @code{type.__new__} may no
longer use the one-argument form to get the type of an object.

@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{186,,type} (other than the metaclass hint, @code{metaclass}) is now
consistently delegated to @ref{a22,,object.__init_subclass__()}. This means that
@ref{982,,type.__new__} and @ref{2fa,,type.__init__} both now accept arbitrary keyword arguments,
but @code{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{443,,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{114,,urllib.request} module and the
@ref{106a,,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{da9,,DictReader} now returns rows of type
@ref{9d5,,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{1cf,,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{10fe,,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{31a,,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 @ref{10ff,,mmap.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{1100,,pkgutil.iter_modules()} and @ref{fbe,,pkgutil.walk_packages()}
functions now return @ref{1101,,ModuleInfo} named tuples.
(Contributed by Ramchandra Apte in bpo-17211@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17211}.)

@item 
@ref{7a1,,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{ab1,,zipfile.ZipFile} will now raise @ref{59a,,NotImplementedError} for
unrecognized compression values.  Previously a plain @ref{30d,,RuntimeError}
was raised.  Additionally, calling @code{ZipFile} methods
on a closed ZipFile or calling the @ref{1102,,write()} method
on a ZipFile created with mode @code{'r'} will raise a @ref{277,,ValueError}.
Previously, a @code{RuntimeError} was raised in those scenarios.

@item 
when custom metaclasses are combined with zero-argument @ref{443,,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{2c9,,DeprecationWarning} in Python 3.6 and a @ref{30d,,RuntimeError} in
Python 3.8.

@item 
With the introduction of @ref{1be,,ModuleNotFoundError}, import system consumers
may start expecting import system replacements to raise that more specific
exception when appropriate, rather than the less-specific @ref{1bd,,ImportError}.
To provide future compatibility with such consumers, implementers of
alternative import systems that completely replace @ref{ca6,,__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 Changes in the C API<7>,CPython bytecode changes<8>,Changes in the Python API<9>,Porting to Python 3 6
@anchor{whatsnew/3 6 changes-in-the-c-api}@anchor{1103}
@subsubsection Changes in the C API



@itemize *

@item 
The @ref{1024,,PyMem_Malloc()} allocator family now uses the @ref{3da,,pymalloc allocator} rather than the system @code{malloc()}. Applications calling
@code{PyMem_Malloc()} without holding the GIL can now crash. Set the
@geindex PYTHONMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,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{1104,,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 CPython bytecode changes<8>,,Changes in the C API<7>,Porting to Python 3 6
@anchor{whatsnew/3 6 cpython-bytecode-changes}@anchor{1105}
@subsubsection CPython bytecode changes


There have been several major changes to the @ref{6b3,,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{1106,,BUILD_STRING} opcodes as part
of the  @ref{fed,,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 @code{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{1107,,MAKE_FUNCTION}, @code{CALL_FUNCTION},
@code{CALL_FUNCTION_KW} and @code{BUILD_MAP_UNPACK_WITH_CALL} opcodes
have been modified, the new @ref{1108,,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{1109,,SETUP_ANNOTATIONS} and @code{STORE_ANNOTATION} opcodes
have been added to support the new @ref{110a,,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{110b}
@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{110c}
@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/main/Makefile.pre.in} for details.

(Contributed by Victor Stinner in bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404}.)


Added in 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{110d}
@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}.)


Άλλαξε στην έκδοση 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{110e}
@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{110f}
@subsection Notable changes in Python 3.6.5


The @ref{fbd,,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{1110}
@subsection Notable changes in Python 3.6.7


@ref{12b,,xml.dom.minidom} and @ref{132,,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{104,,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{1111}
@subsection Notable changes in Python 3.6.10


Due to significant security concerns, the `reuse_address' parameter of
@ref{b1a,,asyncio.loop.create_datagram_endpoint()} is no longer supported. This is
because of the behavior of the socket option @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}.)

@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{1112}
@subsection Notable changes in Python 3.6.13


Earlier Python versions allowed using both @code{;} and @code{&} as
query parameter separators in @ref{589,,urllib.parse.parse_qs()} and
@ref{588,,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{1113}
@subsection Notable changes in Python 3.6.14


A security fix alters the @ref{cca,,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{113,,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})

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 5,What’s New In Python 3 4,What’s New In Python 3 6,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 5 doc}@anchor{1114}@anchor{whatsnew/3 5 translation-repo}@anchor{1115}@anchor{whatsnew/3 5 what-s-new-in-python-3-5}@anchor{1116}
@section What’s New In 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 Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 478
PEP 478@footnote{https://peps.python.org/pep-0478/} - Python 3.5 Release Schedule


@menu
* Summary – Release highlights: Summary – Release highlights<9>. 
* New Features: New Features<14>. 
* Other Language Changes: Other Language Changes<9>. 
* New Modules: New Modules<9>. 
* Improved Modules: Improved Modules<9>. 
* Other module-level changes:: 
* Optimizations: Optimizations<12>. 
* Build and C API Changes: Build and C API Changes<3>. 
* Deprecated: Deprecated<13>. 
* Removed: Removed<13>. 
* Porting to Python 3.5: Porting to Python 3 5. 
* Notable changes in Python 3.5.4: Notable changes in Python 3 5 4. 

@end menu

@node Summary – Release highlights<9>,New Features<14>,,What’s New In Python 3 5
@anchor{whatsnew/3 5 summary-release-highlights}@anchor{1117}
@subsection Summary – Release highlights


New syntax features:


@itemize *

@item 
@ref{1118,,PEP 492}, coroutines with async and await syntax.

@item 
@ref{1119,,PEP 465}, a new matrix multiplication operator: @code{a @@ b}.

@item 
@ref{111a,,PEP 448}, additional unpacking generalizations.
@end itemize

New library modules:


@itemize *

@item 
@ref{10d,,typing}: @ref{111b,,PEP 484 – Type Hints}.

@item 
@ref{139,,zipapp}: @ref{111c,,PEP 441 Improving Python ZIP Application Support}.
@end itemize

New built-in features:


@itemize *

@item 
@code{bytes % args}, @code{bytearray % args}: @ref{111d,,PEP 461} –
Adding @code{%} formatting to bytes and bytearray.

@item 
New @ref{111e,,bytes.hex()}, @ref{111f,,bytearray.hex()} and @ref{1120,,memoryview.hex()}
methods. (Contributed by Arnon Yaari in bpo-9951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9951}.)

@item 
@ref{1d2,,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{1121,,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{94a,,sys.stdin} and @ref{e9c,,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{1122,,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{1123,,PEP 489 overview}.)
@end itemize

Significant improvements in the standard library:


@itemize *

@item 
@ref{9d5,,collections.OrderedDict} is now
@ref{1124,,implemented in C}, which makes it
4 to 100 times faster.

@item 
The @ref{d8,,ssl} module gained
@ref{1125,,support for Memory BIO}, which decouples SSL
protocol handling from network IO.

@item 
The new @ref{e23,,os.scandir()} function provides a
@ref{1126,,better and significantly faster way}
of directory traversal.

@item 
@ref{db3,,functools.lru_cache()} has been mostly
@ref{1127,,reimplemented in C}, yielding much better
performance.

@item 
The new @ref{f45,,subprocess.run()} function provides a
@ref{1128,,streamlined way to run subprocesses}.

@item 
The @ref{107,,traceback} module has been significantly
@ref{1129,,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{336,,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{e6d,,Χρησιμοποιώντας Python στα 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 New Features<14>,Other Language Changes<9>,Summary – Release highlights<9>,What’s New In Python 3 5
@anchor{whatsnew/3 5 new-features}@anchor{112a}
@subsection New Features


@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 – a better and faster directory iterator: PEP 471 - os scandir function – 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; Elimination of PYO files: PEP 488 Elimination of PYO files. 
* 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,,New Features<14>
@anchor{whatsnew/3 5 pep-492-coroutines-with-async-and-await-syntax}@anchor{112b}@anchor{whatsnew/3 5 whatsnew-pep-492}@anchor{1118}
@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{6cf,,awaitable objects},
@ref{112c,,coroutine functions},
@ref{112d,,asynchronous iteration},
and @ref{9d2,,asynchronous context managers}.

Coroutine functions are declared using the new @ref{9cf,,async def} syntax:

@example
>>> async def coro():
...     return 'spam'
@end example

Inside a coroutine function, the new @ref{432,,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{6cf,,awaitable} protocol by
defining the @ref{112e,,__await__()} method.

PEP 492 also adds @ref{e70,,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

will output:

@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{e70,,async for} and @ref{20b,,async with} can only
be used inside a coroutine function declared with @ref{9cf,,async def}.

Coroutine functions are intended to be run inside a compatible event loop,
such as the @ref{112f,,asyncio loop}.

@cartouche
@quotation Σημείωση 

Άλλαξε στην έκδοση 3.5.2: Starting with CPython 3.5.2, @code{__aiter__} can directly return
@ref{6cd,,asynchronous iterators}.  Returning
an @ref{6cf,,awaitable} object will result in a
@ref{c9b,,PendingDeprecationWarning}.

See more details in the @ref{1130,,Ασύγχρονοι Iterators} documentation
section.

@end quotation
@end cartouche


@subsubheading Δείτε επίσης



@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,New Features<14>
@anchor{whatsnew/3 5 pep-465-a-dedicated-infix-operator-for-matrix-multiplication}@anchor{1131}@anchor{whatsnew/3 5 whatsnew-pep-465}@anchor{1119}
@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 @ref{1132,,__matmul__()},
@ref{1133,,__rmatmul__()}, and @ref{1134,,__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 Δείτε επίσης



@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,New Features<14>
@anchor{whatsnew/3 5 pep-448-additional-unpacking-generalizations}@anchor{1135}@anchor{whatsnew/3 5 whatsnew-pep-448}@anchor{111a}
@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{1136,,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{1137,,Expression lists} and @ref{1138,,Dictionary displays}):

@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 Δείτε επίσης



@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,New Features<14>
@anchor{whatsnew/3 5 pep-461-percent-formatting-support-for-bytes-and-bytearray}@anchor{1139}@anchor{whatsnew/3 5 whatsnew-pep-461}@anchor{111d}
@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{113a,,interpolation operator} to @ref{1c7,,bytes}
and @ref{1c6,,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.

Examples:

@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 Δείτε επίσης



@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,New Features<14>
@anchor{whatsnew/3 5 pep-484-type-hints}@anchor{113b}@anchor{whatsnew/3 5 whatsnew-pep-484}@anchor{111b}
@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{5fd,,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
@ref{66b,,__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{a9a,,Any} which is consistent with (i.e. assignable to
and from) all types.


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{10d,,typing} module documentation

@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 written by 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,New Features<14>
@anchor{whatsnew/3 5 pep-471-os-scandir-function-a-better-and-faster-directory-iterator}@anchor{113c}@anchor{whatsnew/3 5 whatsnew-pep-471}@anchor{1126}
@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{e23,,os.scandir()},
to the standard library.  Additionally, @ref{8b9,,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{4f5,,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{e23,,os.scandir()} to display all
the files (excluding directories) in the given `path' that don’t start with
@code{'.'}. The @ref{113d,,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 Δείτε επίσης



@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,New Features<14>
@anchor{whatsnew/3 5 pep-475-retry-system-calls-failing-with-eintr}@anchor{113e}@anchor{whatsnew/3 5 whatsnew-pep-475}@anchor{113f}
@subsubsection PEP 475: Retry system calls failing with EINTR


An @ref{1140,,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{1141,,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

and:

@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{1141,,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{32b,,open()} and @ref{92b,,io.open()};

@item 
functions of the @ref{5b,,faulthandler} module;

@item 
@ref{a5,,os} functions: @ref{1142,,fchdir()}, @ref{72d,,fchmod()},
@ref{1143,,fchown()}, @ref{1144,,fdatasync()}, @ref{1145,,fstat()},
@ref{1146,,fstatvfs()}, @ref{1147,,fsync()}, @ref{1148,,ftruncate()},
@ref{1149,,mkfifo()}, @ref{114a,,mknod()}, @ref{114b,,open()},
@ref{114c,,posix_fadvise()}, @ref{114d,,posix_fallocate()}, @ref{f1c,,pread()},
@ref{f1f,,pwrite()}, @ref{114e,,read()}, @ref{f1b,,readv()}, @ref{ed3,,sendfile()},
@ref{114f,,wait3()}, @ref{1150,,wait4()}, @ref{1151,,wait()},
@ref{1152,,waitid()}, @ref{1153,,waitpid()}, @ref{1154,,write()},
@ref{f1e,,writev()};

@item 
special cases: @ref{f31,,os.close()} and @ref{f20,,os.dup2()} now ignore
@ref{1140,,EINTR} errors; the syscall is not retried (see the PEP
for the rationale);

@item 
@ref{c9,,select} functions: @ref{1155,,devpoll.poll()},
@ref{1156,,epoll.poll()},
@ref{1157,,kqueue.control()},
@ref{1158,,poll.poll()}, @ref{1159,,select()};

@item 
methods of the @ref{115a,,socket} class: @ref{115b,,accept()},
@ref{115c,,connect()} (except for non-blocking sockets),
@ref{115d,,recv()}, @ref{115e,,recvfrom()},
@ref{115f,,recvmsg()}, @ref{1160,,send()},
@ref{1161,,sendall()}, @ref{88c,,sendmsg()},
@ref{1162,,sendto()};

@item 
@ref{1163,,signal.sigtimedwait()} and @ref{1164,,signal.sigwaitinfo()};

@item 
@ref{a8c,,time.sleep()}.
@end itemize


@subsubheading Δείτε επίσης



@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,New Features<14>
@anchor{whatsnew/3 5 pep-479-change-stopiteration-handling-inside-generators}@anchor{1165}@anchor{whatsnew/3 5 whatsnew-pep-479}@anchor{10d9}
@subsubsection PEP 479: Change StopIteration handling inside generators


The interaction of generators and @ref{fba,,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{30d,,RuntimeError} before it exits the generator frame.  The main goal of
this change is to ease debugging in the situation where an unguarded
@ref{bb5,,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{1166,,__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{c9b,,PendingDeprecationWarning} will be
raised whenever a @ref{fba,,StopIteration} exception is raised inside a generator.


@subsubheading Δείτε επίσης



@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,New Features<14>
@anchor{whatsnew/3 5 pep-485-a-function-for-testing-approximate-equality}@anchor{1167}@anchor{whatsnew/3 5 whatsnew-pep-485}@anchor{1168}
@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{1169,,math.isclose()} and @ref{116a,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 485

@item PEP 485@footnote{https://peps.python.org/pep-0485/} – A function for testing approximate equality

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 Elimination of PYO files,PEP 485 A function for testing approximate equality,New Features<14>
@anchor{whatsnew/3 5 pep-486-make-the-python-launcher-aware-of-virtual-environments}@anchor{116b}@anchor{whatsnew/3 5 whatsnew-pep-486}@anchor{116c}
@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 Δείτε επίσης



@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 Elimination of PYO files,PEP 489 Multi-phase extension module initialization,PEP 486 Make the Python Launcher aware of virtual environments,New Features<14>
@anchor{whatsnew/3 5 pep-488-elimination-of-pyo-files}@anchor{116d}@anchor{whatsnew/3 5 whatsnew-pep-488}@anchor{1122}
@subsubsection PEP 488: Elimination of PYO files


@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{431,,-O} or @ref{116e,,-OO}. Consequently, bytecode files generated from
@code{-O}, and @code{-OO} may now exist simultaneously.
@ref{330,,importlib.util.cache_from_source()} has an updated API to help with
this change.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 488

@item PEP 488@footnote{https://peps.python.org/pep-0488/} – Elimination of PYO files

PEP written and implemented by Brett Cannon.
@end table


@node PEP 489 Multi-phase extension module initialization,,PEP 488 Elimination of PYO files,New Features<14>
@anchor{whatsnew/3 5 pep-489-multi-phase-extension-module-initialization}@anchor{116f}@anchor{whatsnew/3 5 whatsnew-pep-489}@anchor{1123}
@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 Δείτε επίσης



@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 Other Language Changes<9>,New Modules<9>,New Features<14>,What’s New In Python 3 5
@anchor{whatsnew/3 5 other-language-changes}@anchor{1170}
@subsection Other Language Changes


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{2ed,,-b} option now affects comparisons of @ref{1c7,,bytes} with
@ref{326,,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{1171,,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{1cf,,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 New Modules<9>,Improved Modules<9>,Other Language Changes<9>,What’s New In Python 3 5
@anchor{whatsnew/3 5 new-modules}@anchor{1172}
@subsection New Modules


@menu
* typing: typing<13>. 
* zipapp: zipapp<2>. 

@end menu

@node typing<13>,zipapp<2>,,New Modules<9>
@anchor{whatsnew/3 5 typing}@anchor{1173}
@subsubsection typing


The new @ref{10d,,typing} @ref{5fd,,provisional} module
provides standard definitions and tools for function type annotations.
See @ref{111b,,Type Hints} for more information.

@node zipapp<2>,,typing<13>,New Modules<9>
@anchor{whatsnew/3 5 whatsnew-zipapp}@anchor{111c}@anchor{whatsnew/3 5 zipapp}@anchor{1174}
@subsubsection zipapp


The new @ref{139,,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 Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 441
PEP 441@footnote{https://peps.python.org/pep-0441/} – Improving Python ZIP Application Support


@node Improved Modules<9>,Other module-level changes,New Modules<9>,What’s New In Python 3 5
@anchor{whatsnew/3 5 improved-modules}@anchor{1175}
@subsection Improved Modules


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

@end menu

@node argparse<7>,asyncio<14>,,Improved Modules<9>
@anchor{whatsnew/3 5 argparse}@anchor{1176}
@subsubsection argparse


The @ref{1dc,,ArgumentParser} class now allows disabling
@ref{1177,,abbreviated usage} of long options by setting
@ref{1178,,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<14>,bz2,argparse<7>,Improved Modules<9>
@anchor{whatsnew/3 5 asyncio}@anchor{1179}
@subsubsection asyncio


Since the @ref{b,,asyncio} module is @ref{5fd,,provisional},
all changes introduced in Python 3.5 have also been backported to Python 3.4.x.

Notable changes in the @ref{b,,asyncio} module since Python 3.4.0:


@itemize *

@item 
New debugging APIs: @ref{117a,,loop.set_debug()}
and @ref{117b,,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{117c,,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{463,,loop.create_task()}
to conveniently create and schedule a new @ref{460,,Task}
for a coroutine.  The @code{create_task} method is also used by all
asyncio functions that wrap coroutines into tasks, such as
@ref{891,,asyncio.wait()}, @ref{9f4,,asyncio.gather()}, etc.
(Contributed by Victor Stinner.)

@item 
A new @ref{117d,,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{1035,,ensure_future()}.
(Contributed by Yury Selivanov.)

@item 
New @ref{461,,loop.set_task_factory()} and
@ref{117e,,loop.get_task_factory()}
methods to customize the task factory that @ref{463,,loop.create_task()} method uses.  (Contributed by Yury
Selivanov.)

@item 
New @ref{117f,,Queue.join()} and
@ref{1180,,Queue.task_done()} queue methods.
(Contributed by Victor Stinner.)

@item 
The @code{JoinableQueue} class was removed, in favor of the
@ref{e39,,asyncio.Queue} class.
(Contributed by Victor Stinner.)
@end itemize

Updates in 3.5.1:


@itemize *

@item 
The @ref{1035,,ensure_future()} function and all functions that
use it, such as @ref{1036,,loop.run_until_complete()},
now accept all kinds of @ref{6cf,,awaitable objects}.
(Contributed by Yury Selivanov.)

@item 
New @ref{c58,,run_coroutine_threadsafe()} function to submit
coroutines to event loops from other threads.
(Contributed by Vincent Michel.)

@item 
New @ref{1037,,Transport.is_closing()}
method to check if the transport is closing or closed.
(Contributed by Yury Selivanov.)

@item 
The @ref{ed7,,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{1038,,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{f8b,,asyncio.Future} implementation.
(Contributed by Yury Selivanov.)

@item 
New @ref{1039,,loop.get_exception_handler()}
method to get the current exception handler.
(Contributed by Yury Selivanov.)

@item 
New @ref{6d6,,StreamReader.readuntil()}
method to read data from the stream until a separator bytes
sequence appears.
(Contributed by Mark Korenberg.)

@item 
The @ref{9f9,,loop.create_connection()}
and @ref{ed7,,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{1181,,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<14>,Improved Modules<9>
@anchor{whatsnew/3 5 bz2}@anchor{1182}
@subsubsection bz2


The @ref{1183,,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,Improved Modules<9>
@anchor{whatsnew/3 5 cgi}@anchor{1184}
@subsubsection cgi


The @code{FieldStorage} class now supports the @ref{478,,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,Improved Modules<9>
@anchor{whatsnew/3 5 cmath}@anchor{1185}
@subsubsection cmath


A new function @ref{116a,,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<6>,cmath<2>,Improved Modules<9>
@anchor{whatsnew/3 5 code}@anchor{1186}
@subsubsection code


The @ref{1187,,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<6>,collections abc<4>,code,Improved Modules<9>
@anchor{whatsnew/3 5 collections}@anchor{1188}
@subsubsection collections

@anchor{whatsnew/3 5 whatsnew-ordereddict}@anchor{1124}
The @ref{9d5,,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()},
and @code{OrderedDict.values()} views now support @ref{c3c,,reversed()} iteration.
(Contributed by Serhiy Storchaka in bpo-19505@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19505}.)

The @ref{9d6,,deque} class now defines
@ref{1189,,index()}, @ref{118a,,insert()}, and
@ref{118b,,copy()}, and supports the @code{+} and @code{*} operators.
This allows deques to be recognized as a @ref{6c6,,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{1cf,,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{118c,,UserString} class now implements the
@ref{118d,,__getnewargs__()}, @ref{118e,,__rmod__()}, @ref{118f,,casefold()},
@ref{1190,,format_map()}, @ref{1191,,isprintable()}, and @ref{187,,maketrans()}
methods to match the corresponding methods of @ref{1df,,str}.
(Contributed by Joe Jevnik in bpo-22189@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22189}.)

@node collections abc<4>,compileall<4>,collections<6>,Improved Modules<9>
@anchor{whatsnew/3 5 collections-abc}@anchor{1192}
@subsubsection collections.abc


The @code{Sequence.index()} method now
accepts `start' and `stop' arguments to match the corresponding methods
of @ref{1ce,,tuple}, @ref{4d9,,list}, etc.
(Contributed by Devin Jeanpierre in bpo-23086@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23086}.)

A new @ref{1193,,Generator} abstract base class. (Contributed
by Stefan Behnel in bpo-24018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24018}.)

New @ref{1194,,Awaitable}, @ref{1195,,Coroutine},
@ref{1196,,AsyncIterator}, and
@ref{1197,,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<7>,collections abc<4>,Improved Modules<9>
@anchor{whatsnew/3 5 compileall}@anchor{1198}
@subsubsection compileall


A new @ref{21,,compileall} option, @code{-j @var{N}}, allows running `N' workers
simultaneously to perform parallel bytecode compilation.
The @ref{ee8,,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{ee8,,compile_dir()},
@ref{1199,,compile_file()}, and @ref{119a,,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<7>,configparser<5>,compileall<4>,Improved Modules<9>
@anchor{whatsnew/3 5 concurrent-futures}@anchor{119b}
@subsubsection concurrent.futures


The @ref{473,,Executor.map()} method now accepts a
`chunksize' argument to allow batching of tasks to improve performance when
@ref{206,,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{b27,,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<5>,contextlib<6>,concurrent futures<7>,Improved Modules<9>
@anchor{whatsnew/3 5 configparser}@anchor{119c}
@subsubsection configparser


@ref{26,,configparser} now provides a way to customize the conversion
of values by specifying a dictionary of converters in the
@ref{6e4,,ConfigParser} constructor, or by defining them
as methods in @code{ConfigParser} subclasses.  Converters defined in
a parser instance are inherited by its section proxies.

Example:

@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<6>,csv<4>,configparser<5>,Improved Modules<9>
@anchor{whatsnew/3 5 contextlib}@anchor{119d}
@subsubsection contextlib


The new @ref{119e,,redirect_stderr()} @ref{478,,context manager} (similar to
@ref{119f,,redirect_stdout()}) makes it easier for utility scripts to
handle inflexible APIs that write their output to @ref{d05,,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<4>,curses<5>,contextlib<6>,Improved Modules<9>
@anchor{whatsnew/3 5 csv}@anchor{11a0}
@subsubsection csv


The @ref{11a1,,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<5>,dbm<6>,csv<4>,Improved Modules<9>
@anchor{whatsnew/3 5 curses}@anchor{11a2}
@subsubsection curses


The new @ref{11a3,,update_lines_cols()} function updates the @ref{11a4,,LINES}
and @ref{11a5,,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<6>,difflib<4>,curses<5>,Improved Modules<9>
@anchor{whatsnew/3 5 dbm}@anchor{11a6}
@subsubsection dbm


@ref{e5c,,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<4>,distutils<7>,dbm<6>,Improved Modules<9>
@anchor{whatsnew/3 5 difflib}@anchor{11a7}
@subsubsection difflib


The charset of HTML documents generated by
@ref{11a8,,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{11a9,,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<4>,Improved Modules<9>
@anchor{whatsnew/3 5 distutils}@anchor{11aa}
@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<5>,distutils<7>,Improved Modules<9>
@anchor{whatsnew/3 5 doctest}@anchor{11ab}
@subsubsection doctest


The @ref{11ac,,DocTestSuite()} function returns an empty
@ref{11ad,,unittest.TestSuite} if `module' contains no docstrings, instead of
raising @ref{277,,ValueError}.  (Contributed by Glenn Jones in bpo-15916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15916}.)

@node email<5>,enum<8>,doctest<3>,Improved Modules<9>
@anchor{whatsnew/3 5 email}@anchor{11ae}
@subsubsection email


A new policy option @ref{11af,,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{105a,,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{11b0,,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{217,,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{11b1,,mime.text.MIMEText} constructor now
accepts a @ref{11b2,,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<5>,email<5>,Improved Modules<9>
@anchor{whatsnew/3 5 enum}@anchor{11b3}
@subsubsection enum


The @ref{a21,,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<5>,functools<7>,enum<8>,Improved Modules<9>
@anchor{whatsnew/3 5 faulthandler}@anchor{11b4}
@subsubsection faulthandler


The @ref{219,,enable()}, @ref{21c,,register()},
@ref{21a,,dump_traceback()} and
@ref{21b,,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<7>,glob<4>,faulthandler<5>,Improved Modules<9>
@anchor{whatsnew/3 5 functools}@anchor{11b5}
@subsubsection functools

@anchor{whatsnew/3 5 whatsnew-lrucache}@anchor{1127}
Most of the @ref{db3,,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<4>,gzip<4>,functools<7>,Improved Modules<9>
@anchor{whatsnew/3 5 glob}@anchor{11b6}
@subsubsection glob


The @ref{be1,,iglob()} and @ref{2d4,,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<2>,glob<4>,Improved Modules<9>
@anchor{whatsnew/3 5 gzip}@anchor{11b7}
@subsubsection gzip


The `mode' argument of the @ref{849,,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<2>,http<3>,gzip<4>,Improved Modules<9>
@anchor{whatsnew/3 5 heapq}@anchor{11b8}
@subsubsection heapq


Element comparison in @ref{11b9,,merge()} can now be customized by
passing a @ref{11ba,,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<3>,http client<4>,heapq<2>,Improved Modules<9>
@anchor{whatsnew/3 5 http}@anchor{11bb}
@subsubsection http


A new @ref{cd0,,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<4>,idlelib and IDLE<3>,http<3>,Improved Modules<9>
@anchor{whatsnew/3 5 http-client}@anchor{11bc}
@subsubsection http.client


@ref{11bd,,HTTPConnection.getresponse()}
now raises a @ref{11be,,RemoteDisconnected} exception when a
remote server connection is closed unexpectedly.  Additionally, if a
@ref{11bf,,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<3>,http client<4>,Improved Modules<9>
@anchor{whatsnew/3 5 idlelib-and-idle}@anchor{11c0}
@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<3>,imghdr,idlelib and IDLE<3>,Improved Modules<9>
@anchor{whatsnew/3 5 imaplib}@anchor{11c1}
@subsubsection imaplib


The @ref{31a,,IMAP4} class now supports the @ref{478,,context manager} protocol.
When used in a @ref{20a,,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{77,,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{11c2,,IMAP4.enable()}
method.  A new @ref{11c3,,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{77,,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<3>,Improved Modules<9>
@anchor{whatsnew/3 5 imghdr}@anchor{11c4}
@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<9>,imghdr,Improved Modules<9>
@anchor{whatsnew/3 5 importlib}@anchor{11c5}
@subsubsection importlib


The @ref{106e,,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{1cb,,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{11c6,,util.module_from_spec()}
function is now the preferred way to create a new module.  As opposed to
creating a @ref{11c7,,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<9>,io<7>,importlib<8>,Improved Modules<9>
@anchor{whatsnew/3 5 inspect}@anchor{11c8}
@subsubsection inspect


Both the @ref{6e8,,Signature} and @ref{6e9,,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{11c9,,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{b20,,Signature.from_callable()} makes
subclassing of @ref{6e8,,Signature} easier.  (Contributed
by Yury Selivanov and Eric Snow in bpo-17373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17373}.)

The @ref{4bd,,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{112c,,coroutine functions} and
@ref{8a2,,coroutine objects} has been added:
@ref{11ca,,iscoroutine()}, @ref{302,,iscoroutinefunction()},
@ref{11cb,,isawaitable()}, @ref{11cc,,getcoroutinelocals()},
and @ref{11cd,,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{a41,,stack()}, @ref{a42,,trace()},
@ref{a3f,,getouterframes()}, and @ref{a40,,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<7>,ipaddress<4>,inspect<9>,Improved Modules<9>
@anchor{whatsnew/3 5 io}@anchor{11ce}
@subsubsection io


A new @ref{11cf,,BufferedIOBase.readinto1()}
method, that uses at most one call to the underlying raw stream’s
@ref{11d0,,RawIOBase.read()} or
@ref{11d1,,RawIOBase.readinto()} methods.
(Contributed by Nikolaus Rath in bpo-20578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20578}.)

@node ipaddress<4>,json<4>,io<7>,Improved Modules<9>
@anchor{whatsnew/3 5 ipaddress}@anchor{11d2}
@subsubsection ipaddress


Both the @ref{712,,IPv4Network} and @ref{713,,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 @ref{11d3,,reverse_pointer} attribute for the
@ref{710,,IPv4Address} and @ref{711,,IPv6Address} 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<4>,linecache<3>,ipaddress<4>,Improved Modules<9>
@anchor{whatsnew/3 5 json}@anchor{11d4}
@subsubsection json


The @ref{86,,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{11d5,,JSONDecodeError} instead of
@ref{277,,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<3>,locale<7>,json<4>,Improved Modules<9>
@anchor{whatsnew/3 5 linecache}@anchor{11d6}
@subsubsection linecache


A new @ref{11d7,,lazycache()} function can be used to capture information
about a non-file-based module to permit getting its lines later via
@ref{4cd,,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<7>,logging<5>,linecache<3>,Improved Modules<9>
@anchor{whatsnew/3 5 locale}@anchor{11d8}
@subsubsection locale


A new @ref{11d9,,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<7>,Improved Modules<9>
@anchor{whatsnew/3 5 logging}@anchor{11da}
@subsubsection logging


All logging methods (@ref{f0c,,Logger} @ref{11db,,log()},
@ref{11dc,,exception()}, @ref{11dd,,critical()},
@ref{11de,,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{11df,,handlers.HTTPHandler} class now
accepts an optional @ref{336,,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{4cf,,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<10>,logging<5>,Improved Modules<9>
@anchor{whatsnew/3 5 lzma}@anchor{11e0}
@subsubsection lzma


The @ref{11e1,,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<10>,multiprocessing<7>,lzma,Improved Modules<9>
@anchor{whatsnew/3 5 math}@anchor{11e2}
@subsubsection math


Two new constants have been added to the @ref{91,,math} module: @ref{1043,,inf}
and @ref{a53,,nan}.  (Contributed by Mark Dickinson in bpo-23185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23185}.)

A new function @ref{1169,,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{cdf,,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<7>,operator<3>,math<10>,Improved Modules<9>
@anchor{whatsnew/3 5 multiprocessing}@anchor{11e3}
@subsubsection multiprocessing


@ref{11e4,,sharedctypes.synchronized()}
objects now support the @ref{478,,context manager} protocol.
(Contributed by Charles-François Natali in bpo-21565@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21565}.)

@node operator<3>,os<12>,multiprocessing<7>,Improved Modules<9>
@anchor{whatsnew/3 5 operator}@anchor{11e5}
@subsubsection operator


@ref{11e6,,attrgetter()}, @ref{e26,,itemgetter()},
and @ref{11e7,,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{11e8,,matmul()} and @ref{11e9,,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<12>,pathlib<14>,operator<3>,Improved Modules<9>
@anchor{whatsnew/3 5 os}@anchor{11ea}
@subsubsection os


The new @ref{e23,,scandir()} function returning an iterator of
@ref{8ac,,DirEntry} objects has been added.  If possible, @code{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{11eb,,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{931,,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{11ec,,get_blocking()} and @ref{11ed,,set_blocking()} functions allow
getting and setting a file descriptor’s blocking mode (@ref{11ee,,O_NONBLOCK}.)
(Contributed by Victor Stinner in bpo-22054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22054}.)

The @ref{11ef,,truncate()} and @ref{1148,,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{334,,os.path.commonpath()} function returning the longest
common sub-path of each passed pathname.  Unlike the
@ref{333,,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<14>,pickle<5>,os<12>,Improved Modules<9>
@anchor{whatsnew/3 5 pathlib}@anchor{11f0}
@subsubsection pathlib


The new @ref{11f1,,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{4ee,,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{11f2,,Path.mkdir()} method now accepts a new optional
`exist_ok' argument to match @code{mkdir -p} and @ref{72f,,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{11f3,,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{11f4,,Path.home()} class method can be used to get
a @ref{4ee,,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{11f5,,Path.write_text()},
@ref{11f6,,Path.read_text()},
@ref{11f7,,Path.write_bytes()},
@ref{55a,,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<5>,poplib<2>,pathlib<14>,Improved Modules<9>
@anchor{whatsnew/3 5 pickle}@anchor{11f8}
@subsubsection pickle


Nested objects, such as unbound methods or nested classes, can now be pickled
using @ref{503,,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<9>,pickle<5>,Improved Modules<9>
@anchor{whatsnew/3 5 poplib}@anchor{11f9}
@subsubsection poplib


A new @ref{11fa,,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<9>,readline<2>,poplib<2>,Improved Modules<9>
@anchor{whatsnew/3 5 re}@anchor{11fb}
@subsubsection 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

(Contributed by Serhiy Storchaka in 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{7a1,,sub()} and @ref{7a2,,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 @ref{749,,re.error} exceptions have new attributes,
@ref{11fc,,msg}, @ref{11fd,,pattern},
@ref{11fe,,pos}, @ref{11ff,,lineno},
and @ref{1200,,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

(Contributed by Serhiy Storchaka in bpo-22578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22578}.)

@node readline<2>,selectors,re<9>,Improved Modules<9>
@anchor{whatsnew/3 5 readline}@anchor{1201}
@subsubsection readline


A new @ref{1202,,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,shutil<5>,readline<2>,Improved Modules<9>
@anchor{whatsnew/3 5 selectors}@anchor{1203}
@subsubsection selectors


The new @ref{f97,,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 shutil<5>,signal<3>,selectors,Improved Modules<9>
@anchor{whatsnew/3 5 shutil}@anchor{1204}
@subsubsection shutil


The @ref{e20,,move()} function now accepts a `copy_function' argument,
allowing, for example, the @ref{e1e,,copy()} function to be used instead of
the default @ref{e1f,,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{8c3,,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>,shutil<5>,Improved Modules<9>
@anchor{whatsnew/3 5 signal}@anchor{1205}
@subsubsection signal


On Windows, the @ref{f2d,,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{ce,,signal} module have been converted into
@ref{59,,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>,Improved Modules<9>
@anchor{whatsnew/3 5 smtpd}@anchor{1206}
@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>,Improved Modules<9>
@anchor{whatsnew/3 5 smtplib}@anchor{1207}
@subsubsection smtplib


A new @ref{1208,,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{1209,,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{120a,,SMTP.sendmail()} and
@ref{120b,,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<10>,smtplib<2>,Improved Modules<9>
@anchor{whatsnew/3 5 sndhdr}@anchor{120c}
@subsubsection sndhdr


The @code{what()} and @code{whathdr()} functions  now return
a @ref{1cf,,namedtuple()}.  (Contributed by Claudiu Popa in
bpo-18615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18615}.)

@node socket<10>,ssl<11>,sndhdr,Improved Modules<9>
@anchor{whatsnew/3 5 socket}@anchor{120d}
@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{120e,,socket.sendfile()} method allows
sending a file over a socket by using the high-performance @ref{ed3,,os.sendfile()}
function on UNIX, resulting in uploads being from 2 to 3 times faster than when
using plain @ref{1160,,socket.send()}.
(Contributed by Giampaolo Rodola” in bpo-17552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17552}.)

The @ref{1161,,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{120f,,socket.listen()}
method is now optional.  By default it is set to
@ref{1210,,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<11>,sqlite3<10>,socket<10>,Improved Modules<9>
@anchor{whatsnew/3 5 ssl}@anchor{1211}
@subsubsection ssl


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

@end menu

@node Memory BIO Support,Application-Layer Protocol Negotiation Support,,ssl<11>
@anchor{whatsnew/3 5 memory-bio-support}@anchor{1212}@anchor{whatsnew/3 5 whatsnew-sslmemorybio}@anchor{1125}
@subsubsection Memory BIO Support


(Contributed by Geert Jansen in bpo-21965@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21965}.)

The new @ref{f40,,SSLObject} class has been added to provide SSL protocol
support for cases when the network I/O capabilities of @ref{cbb,,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{1213,,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{cbb,,SSLSocket}’s readiness
model («select/poll») is inefficient.

A new @ref{f41,,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<11>
@anchor{whatsnew/3 5 application-layer-protocol-negotiation-support}@anchor{1214}
@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{d8,,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{1215,,SSLContext.set_alpn_protocols()}
can be used to specify which protocols a socket should advertise during
the TLS handshake.

The new
@ref{1216,,SSLSocket.selected_alpn_protocol()}
returns the protocol that was selected during the TLS handshake.
The @ref{1217,,HAS_ALPN} flag indicates whether ALPN support is present.

@node Other Changes,,Application-Layer Protocol Negotiation Support,ssl<11>
@anchor{whatsnew/3 5 other-changes}@anchor{1218}
@subsubsection Other Changes


There is a new @ref{1219,,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{cbb,,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{121a,,ssl.SSLWantReadError} or @ref{121b,,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{121c,,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{326,,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{121d,,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{121e,,SSLSocket.do_handshake()},
@ref{121f,,SSLSocket.read()},
@code{SSLSocket.shutdown()}, and
@ref{1220,,SSLSocket.write()} methods of the @ref{cbb,,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<10>,subprocess<5>,ssl<11>,Improved Modules<9>
@anchor{whatsnew/3 5 sqlite3}@anchor{1221}
@subsubsection sqlite3


The @ref{1222,,Row} class now fully supports the sequence protocol,
in particular @ref{c3c,,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<5>,sys<12>,sqlite3<10>,Improved Modules<9>
@anchor{whatsnew/3 5 subprocess}@anchor{1223}@anchor{whatsnew/3 5 whatsnew-subprocess}@anchor{1128}
@subsubsection subprocess


The new @ref{f45,,run()} function has been added.
It runs the specified command and returns a
@ref{1224,,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}.)

Examples:

@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<12>,sysconfig<5>,subprocess<5>,Improved Modules<9>
@anchor{whatsnew/3 5 sys}@anchor{1225}
@subsubsection sys


A new @code{set_coroutine_wrapper()} function allows setting a global
hook that will be called whenever a @ref{8a2,,coroutine object}
is created by an @ref{9cf,,async def} function.  A corresponding
@code{get_coroutine_wrapper()} can be used to obtain a currently set
wrapper.  Both functions are @ref{5fd,,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{e4f,,is_finalizing()} function can be used to check if the Python
interpreter is @ref{1a0,,shutting down}.
(Contributed by Antoine Pitrou in bpo-22696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22696}.)

@node sysconfig<5>,tarfile<8>,sys<12>,Improved Modules<9>
@anchor{whatsnew/3 5 sysconfig}@anchor{1226}
@subsubsection 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<8>,threading<9>,sysconfig<5>,Improved Modules<9>
@anchor{whatsnew/3 5 tarfile}@anchor{1227}
@subsubsection tarfile


The `mode' argument of the @ref{1228,,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{27a,,TarFile.extractall()} and
@ref{27b,,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{1229,,TarFile.list()} now accepts an optional
`members' keyword argument that can be set to a subset of the list returned
by @ref{122a,,TarFile.getmembers()}.
(Contributed by Serhiy Storchaka in bpo-21549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21549}.)

@node threading<9>,time<7>,tarfile<8>,Improved Modules<9>
@anchor{whatsnew/3 5 threading}@anchor{122b}
@subsubsection threading


Both the @ref{a87,,Lock.acquire()} and
@ref{122c,,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<3>,threading<9>,Improved Modules<9>
@anchor{whatsnew/3 5 time}@anchor{122d}
@subsubsection time


The @ref{75d,,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<3>,tkinter<10>,time<7>,Improved Modules<9>
@anchor{whatsnew/3 5 timeit}@anchor{122e}
@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{122f,,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<10>,traceback<5>,timeit<3>,Improved Modules<9>
@anchor{whatsnew/3 5 tkinter}@anchor{1230}
@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<8>,tkinter<10>,Improved Modules<9>
@anchor{whatsnew/3 5 traceback}@anchor{1231}@anchor{whatsnew/3 5 whatsnew-traceback}@anchor{1129}
@subsubsection traceback


New @ref{1232,,walk_stack()} and @ref{1233,,walk_tb()}
functions to conveniently traverse frame and
@ref{eba,,traceback objects}.
(Contributed by Robert Collins in bpo-17911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17911}.)

New lightweight classes: @ref{764,,TracebackException},
@ref{1234,,StackSummary}, and @ref{1235,,FrameSummary}.
(Contributed by Robert Collins in bpo-17911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17911}.)

Both the @ref{1236,,print_tb()} and @ref{1237,,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<8>,unicodedata<10>,traceback<5>,Improved Modules<9>
@anchor{whatsnew/3 5 types}@anchor{1238}
@subsubsection types


A new @ref{1239,,coroutine()} function to transform
@ref{f9e,,generator} and
@ref{1193,,generator-like} objects into
@ref{6cf,,awaitables}.
(Contributed by Yury Selivanov in bpo-24017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24017}.)

A new type called @ref{123a,,CoroutineType}, which is used for
@ref{8a2,,coroutine} objects created by @ref{9cf,,async def} functions.
(Contributed by Yury Selivanov in bpo-24400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24400}.)

@node unicodedata<10>,unittest<10>,types<8>,Improved Modules<9>
@anchor{whatsnew/3 5 unicodedata}@anchor{123b}
@subsubsection unicodedata


The @ref{10e,,unicodedata} module now uses data from Unicode 8.0.0@footnote{https://unicode.org/versions/Unicode8.0.0/}.

@node unittest<10>,unittest mock<3>,unicodedata<10>,Improved Modules<9>
@anchor{whatsnew/3 5 unittest}@anchor{123c}
@subsubsection unittest


The @ref{793,,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{123d,,TestLoader.errors} attribute of the
@ref{792,,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<4>,unittest<10>,Improved Modules<9>
@anchor{whatsnew/3 5 unittest-mock}@anchor{123e}
@subsubsection unittest.mock


The @ref{e0e,,Mock} class has the following improvements:


@itemize *

@item 
The class constructor has a new `unsafe' parameter, which causes mock
objects to raise @ref{1a9,,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{123f,,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{1240,,MagicMock} class now supports
@ref{1241,,__truediv__()}, @ref{1242,,__divmod__()}
and @ref{1132,,__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{1243,,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<4>,wsgiref,unittest mock<3>,Improved Modules<9>
@anchor{whatsnew/3 5 urllib}@anchor{1244}
@subsubsection urllib


A new
@ref{1245,,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{1246,,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{57f,,request.urlopen()} function accepts an
@ref{336,,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{1247,,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<4>,Improved Modules<9>
@anchor{whatsnew/3 5 wsgiref}@anchor{1248}
@subsubsection wsgiref


The `headers' argument of the @ref{1249,,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,Improved Modules<9>
@anchor{whatsnew/3 5 xmlrpc}@anchor{124a}
@subsubsection xmlrpc


The @ref{e1b,,client.ServerProxy} class now supports
the @ref{478,,context manager} protocol.
(Contributed by Claudiu Popa in bpo-20627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20627}.)

The @ref{e1b,,client.ServerProxy} constructor now accepts
an optional @ref{336,,ssl.SSLContext} instance.
(Contributed by Alex Gaynor in bpo-22960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22960}.)

@node xml sax,zipfile<5>,xmlrpc<2>,Improved Modules<9>
@anchor{whatsnew/3 5 xml-sax}@anchor{124b}
@subsubsection xml.sax


SAX parsers now support a character stream of the
@ref{124c,,xmlreader.InputSource} object.
(Contributed by Serhiy Storchaka in bpo-2175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2175}.)

@ref{124d,,parseString()} now accepts a @ref{1df,,str} instance.
(Contributed by Serhiy Storchaka in bpo-10590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10590}.)

@node zipfile<5>,,xml sax,Improved Modules<9>
@anchor{whatsnew/3 5 zipfile}@anchor{124e}
@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{84a,,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<12>,Improved Modules<9>,What’s New In Python 3 5
@anchor{whatsnew/3 5 other-module-level-changes}@anchor{124f}
@subsection Other module-level changes


Many functions in the @ref{94,,mmap}, @code{ossaudiodev}, @ref{d4,,socket},
@ref{d8,,ssl}, and @ref{1c,,codecs} modules now accept writable
@ref{436,,bytes-like objects}.
(Contributed by Serhiy Storchaka in bpo-23001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23001}.)

@node Optimizations<12>,Build and C API Changes<3>,Other module-level changes,What’s New In Python 3 5
@anchor{whatsnew/3 5 optimizations}@anchor{1250}
@subsection Optimizations


The @ref{8b9,,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{e23,,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{83,,ipaddress} @ref{712,,IPv4Network} and
@ref{713,,IPv6Network} have been massively sped up, such as
@ref{1251,,subnets()}, @ref{1252,,supernet()},
@ref{1253,,summarize_address_range()}, @ref{1254,,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{83,,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{1255,,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{1256,,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{248,,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{1257,,PyObject_IsInstance()} and @ref{1258,,PyObject_IsSubclass()}
functions have been sped up in the common case that the second argument
has @ref{186,,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{c0,,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{6bb,,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{1c3,,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{1259,,find()}, @ref{125a,,rfind()}, @ref{125b,,split()},
@ref{125c,,partition()} and the @ref{323,,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>,Deprecated<13>,Optimizations<12>,What’s New In Python 3 5
@anchor{whatsnew/3 5 build-and-c-api-changes}@anchor{125d}
@subsection Build and C API Changes


New @code{calloc} functions were added:


@itemize *

@item 
@ref{824,,PyMem_RawCalloc()},

@item 
@ref{125e,,PyMem_Calloc()},

@item 
@ref{125f,,PyObject_Calloc()}.
@end itemize

(Contributed by Victor Stinner in bpo-21233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21233}.)

New encoding/decoding helper functions:


@itemize *

@item 
@ref{f85,,Py_DecodeLocale()} (replaced @code{_Py_char2wchar()}),

@item 
@ref{f86,,Py_EncodeLocale()} (replaced @code{_Py_wchar2char()}).
@end itemize

(Contributed by Victor Stinner in bpo-18395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18395}.)

A new @ref{1260,,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{1261,,PyErr_FormatV()} function similar to @ref{1262,,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 @ref{1263,,PyExc_RecursionError} exception.
(Contributed by Georg Brandl in bpo-19235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19235}.)

New @ref{392,,PyModule_FromDefAndSpec()}, @ref{393,,PyModule_FromDefAndSpec2()},
and @ref{394,,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{1264,,PyNumber_MatrixMultiply()} and
@ref{1265,,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{e6c,,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 Deprecated<13>,Removed<13>,Build and C API Changes<3>,What’s New In Python 3 5
@anchor{whatsnew/3 5 deprecated}@anchor{1266}
@subsection Deprecated


@menu
* New Keywords: New Keywords<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 New Keywords<2>,Deprecated Python Behavior<2>,,Deprecated<13>
@anchor{whatsnew/3 5 new-keywords}@anchor{1267}
@subsubsection New Keywords


@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,New Keywords<2>,Deprecated<13>
@anchor{whatsnew/3 5 deprecated-python-behavior}@anchor{1268}
@subsubsection Deprecated Python Behavior


Raising the @ref{fba,,StopIteration} exception inside a generator will now generate a silent
@ref{c9b,,PendingDeprecationWarning}, which will become a non-silent deprecation
warning in Python 3.6 and will trigger a @ref{30d,,RuntimeError} in Python 3.7.
See @ref{10d9,,PEP 479; Change StopIteration handling inside generators}
for details.

@node Unsupported Operating Systems,Deprecated Python modules functions and methods<3>,Deprecated Python Behavior<2>,Deprecated<13>
@anchor{whatsnew/3 5 unsupported-operating-systems}@anchor{1269}
@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,Deprecated<13>
@anchor{whatsnew/3 5 deprecated-python-modules-functions-and-methods}@anchor{126a}
@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{1035,,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{fc0,,key},
@ref{fc1,,value} and
@ref{fc2,,coded_value} of @ref{fc3,,http.cookies.Morsel}
objects is deprecated.  Use the @ref{fc4,,set()} method
instead.  In addition, the undocumented `LegalChars' parameter of
@code{set()} is deprecated, and is now ignored.

Passing a format string as keyword argument `format_string' to the
@ref{fbf,,format()} method of the @ref{126b,,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{6e8,,inspect.Signature} are deprecated.  Use the new
@ref{b20,,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{81,,inspect} @ref{b1f,,getfullargspec()},
@ref{126c,,getcallargs()}, and @code{formatargspec()} functions are
deprecated in favor of the @ref{4bd,,inspect.signature()} API. (Contributed by Yury
Selivanov in bpo-20438@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20438}.)

@ref{126d,,getargvalues()} and @ref{126e,,formatargvalues()} functions
were inadvertently marked as deprecated with the release of Python 3.5.0.

Use of @ref{f29,,re.LOCALE} flag with str patterns or @ref{a1d,,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{793,,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 Removed<13>,Porting to Python 3 5,Deprecated<13>,What’s New In Python 3 5
@anchor{whatsnew/3 5 removed}@anchor{126f}
@subsection Removed


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

@end menu

@node API and Feature Removals<4>,,,Removed<13>
@anchor{whatsnew/3 5 api-and-feature-removals}@anchor{1270}
@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{61,,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{b,,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 Porting to Python 3 5,Notable changes in Python 3 5 4,Removed<13>,What’s New In Python 3 5
@anchor{whatsnew/3 5 porting-to-python-3-5}@anchor{1271}
@subsection Porting to Python 3.5


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

@menu
* Changes in Python behavior: Changes in Python behavior<2>. 
* Changes in the Python API: Changes in the Python API<10>. 
* Changes in the C API: Changes in the C API<8>. 

@end menu

@node Changes in Python behavior<2>,Changes in the Python API<10>,,Porting to Python 3 5
@anchor{whatsnew/3 5 changes-in-python-behavior}@anchor{1272}
@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{17e,,SyntaxError}, as generator
expressions must be put in parentheses if not a sole argument to a function.
@end itemize

@node Changes in the Python API<10>,Changes in the C API<8>,Changes in Python behavior<2>,Porting to Python 3 5
@anchor{whatsnew/3 5 changes-in-the-python-api}@anchor{1273}
@subsubsection Changes in the Python API



@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{1141,,InterruptedError} if the Python signal handler does not
raise an exception.

@item 
Before Python 3.5, a @ref{48e,,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{121a,,ssl.SSLWantReadError} or @ref{121b,,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{c4d,,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 @code{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{436,,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{243,,FileNotFoundError} will no longer be raised and instead
@ref{1274,,find_spec()} will return @code{None}
`without' caching @code{None} in @ref{9db,,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{72,,http.client} and @ref{75,,http.server}
were refactored into a common @ref{cd0,,HTTPStatus} enum.  The values in
@code{http.client} and @code{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 @ref{c40,,exec_module()}
it is now expected to also define
@ref{106f,,create_module()} (raises a
@ref{2c9,,DeprecationWarning} now, will be an error in Python 3.6). If the loader
inherits from @ref{1275,,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{7a0,,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 @code{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{fc3,,http.cookies.Morsel} dict-like interface has been made self
consistent:  morsel comparison now takes the @ref{fc0,,key}
and @ref{fc1,,value} into account,
@ref{1276,,copy()} now results in a
@code{Morsel} instance rather than a @ref{188,,dict}, and
@ref{1277,,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{fc4,,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{330,,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{d4,,socket} module now exports the @ref{1278,,CAN_RAW_FD_FRAMES}
constant on linux 3.6 and greater.

@item 
The @ref{121c,,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{326,,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{d2,,smtplib} module now uses @ref{d05,,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{1279,,str.startswith()} and @ref{127a,,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{22c,,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{bd,,pydoc}
module and the @ref{ca9,,help()} function.
(Contributed by Serhiy Storchaka in bpo-15582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15582}.)

@item 
Nested @ref{4a6,,functools.partial()} calls are now flattened.  If you were
relying on the previous behavior, you can now either add an attribute to a
@code{functools.partial()} object or you can create a subclass of
@code{functools.partial()}.
(Contributed by Alexander Belopolsky in bpo-7830@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7830}.)
@end itemize

@node Changes in the C API<8>,,Changes in the Python API<10>,Porting to Python 3 5
@anchor{whatsnew/3 5 changes-in-the-c-api}@anchor{127b}
@subsubsection Changes in the C API



@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{127c,,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{81e,,PyUnicode_FromFormat()}-like functions
to format the @ref{45b,,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{80b,,__module__} attribute breaks pickling and
introspection, a deprecation warning is now raised for builtin types without
the @code{__module__} attribute.  This will be an @ref{1a9,,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{e6b,,PyTypeObject} was replaced with a
@ref{127d,,tp_as_async} slot.  Refer to @ref{127e,,Coroutine Objects} for
new types, structures and functions.
@end itemize

@node Notable changes in Python 3 5 4,,Porting to Python 3 5,What’s New In Python 3 5
@anchor{whatsnew/3 5 notable-changes-in-python-3-5-4}@anchor{127f}
@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{1280}
@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/main/Makefile.pre.in} for details.

(Contributed by Victor Stinner in bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404}.)


Added in 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{1281}
@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}.)


Άλλαξε στην έκδοση 3.5.4.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 4,What’s New In Python 3 3,What’s New In Python 3 5,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 4 doc}@anchor{1282}@anchor{whatsnew/3 4 translation-repo}@anchor{1283}@anchor{whatsnew/3 4 what-s-new-in-python-3-4}@anchor{1284}
@section What’s New In Python 3.4


@*Author: 
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 Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 429
PEP 429@footnote{https://peps.python.org/pep-0429/} – Python 3.4 Release Schedule


@menu
* Summary – Release Highlights: Summary – Release Highlights<3>. 
* New Features: New Features<15>. 
* New Modules: New Modules<10>. 
* Improved Modules: Improved Modules<10>. 
* CPython Implementation Changes:: 
* Deprecated: Deprecated<14>. 
* Removed: Removed<14>. 
* Porting to Python 3.4: Porting to Python 3 4. 
* Changed in 3.4.3: Changed in 3 4 3. 

@end menu

@node Summary – Release Highlights<3>,New Features<15>,,What’s New In Python 3 4
@anchor{whatsnew/3 4 summary-release-highlights}@anchor{1285}
@subsection Summary – Release Highlights


@c This section singles out the most important changes in Python 3.4.
@c Brevity is key.

New syntax features:


@itemize *

@item 
No new syntax features were added in Python 3.4.
@end itemize

Other new features:


@itemize *

@item 
@ref{1286,,pip should always be available} (
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/}).

@item 
@ref{1287,,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{1288,,isolated mode}
(bpo-16499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16499}).

@item 
@ref{1289,,improvements in the handling of codecs}
that are not text encodings (multiple issues).

@item 
@ref{128a,,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{90,,marshal} format has been made @ref{128b,,more compact and efficient} (bpo-16475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16475}).
@end itemize

New library modules:


@itemize *

@item 
@ref{b,,asyncio}: @ref{128c,,New provisional API for asynchronous IO} (
@geindex Python Enhancement Proposals; PEP 3156
PEP 3156@footnote{https://peps.python.org/pep-3156/}).

@item 
@ref{58,,ensurepip}: @ref{128d,,Bootstrapping the pip installer}
(
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/}).

@item 
@ref{59,,enum}: @ref{128e,,Support for enumeration types}
(
@geindex Python Enhancement Proposals; PEP 435
PEP 435@footnote{https://peps.python.org/pep-0435/}).

@item 
@ref{a8,,pathlib}: @ref{128f,,Object-oriented filesystem paths}
(
@geindex Python Enhancement Proposals; PEP 428
PEP 428@footnote{https://peps.python.org/pep-0428/}).

@item 
@ref{ca,,selectors}: @ref{1290,,High-level and efficient I/O multiplexing}, built upon the @ref{c9,,select} module primitives (part
of 
@geindex Python Enhancement Proposals; PEP 3156
PEP 3156@footnote{https://peps.python.org/pep-3156/}).

@item 
@ref{da,,statistics}: A basic @ref{1291,,numerically stable statistics library} (
@geindex Python Enhancement Proposals; PEP 450
PEP 450@footnote{https://peps.python.org/pep-0450/}).

@item 
@ref{108,,tracemalloc}: @ref{1292,,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{1293,,Single-dispatch generic functions} in
@ref{62,,functools} (
@geindex Python Enhancement Proposals; PEP 443
PEP 443@footnote{https://peps.python.org/pep-0443/}).

@item 
New @ref{ab,,pickle} @ref{1294,,protocol 4} (
@geindex Python Enhancement Proposals; PEP 3154
PEP 3154@footnote{https://peps.python.org/pep-3154/}).

@item 
@ref{98,,multiprocessing} now has @ref{1295,,an option to avoid using os.fork on Unix} (bpo-8713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8713}).

@item 
@ref{3e,,email} has a new submodule, @ref{40,,contentmanager}, and
a new @ref{780,,Message} subclass
(@ref{216,,EmailMessage}) that @ref{1296,,simplify MIME handling} (bpo-18891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18891}).

@item 
The @ref{81,,inspect} and @ref{bd,,pydoc} modules are now capable of
correct introspection of a much wider variety of callable objects,
which improves the output of the Python @ref{ca9,,help()} system.

@item 
The @ref{83,,ipaddress} module API has been declared stable
@end itemize

Security improvements:


@itemize *

@item 
@ref{1297,,Secure and interchangeable hash algorithm}
(
@geindex Python Enhancement Proposals; PEP 456
PEP 456@footnote{https://peps.python.org/pep-0456/}).

@item 
@ref{1287,,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{1288,,isolated mode},
(bpo-16499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16499}).

@item 
@ref{98,,multiprocessing} now has @ref{1295,,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{98,,multiprocessing} child processes on Windows no longer inherit
all of the parent’s inheritable handles, only the necessary ones.

@item 
A new @ref{91e,,hashlib.pbkdf2_hmac()} function provides
the PKCS#5 password-based key derivation function 2@footnote{https://en.wikipedia.org/wiki/PBKDF2}.

@item 
@ref{1298,,TLSv1.1 and TLSv1.2 support} for @ref{d8,,ssl}.

@item 
@ref{1299,,Retrieving certificates from the Windows system cert store support} for @ref{d8,,ssl}.

@item 
@ref{129a,,Server-side SNI (Server Name Indication) support} for @ref{d8,,ssl}.

@item 
The @ref{336,,ssl.SSLContext} class has a @ref{129b,,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{129c,,ssl.SSLContext.load_verify_locations()}).
@end itemize

CPython implementation improvements:


@itemize *

@item 
@ref{129d,,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{129d,,module globals are no longer set to None during finalization} (bpo-18214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18214}).

@item 
@ref{129e,,Configurable memory allocators} (
@geindex Python Enhancement Proposals; PEP 445
PEP 445@footnote{https://peps.python.org/pep-0445/}).

@item 
@ref{129f,,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 New Features<15>,New Modules<10>,Summary – Release Highlights<3>,What’s New In Python 3 4
@anchor{whatsnew/3 4 new-features}@anchor{12a0}
@subsection New Features


@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. 
* Other Language Changes: Other Language Changes<10>. 

@end menu

@node PEP 453 Explicit Bootstrapping of PIP in Python Installations,PEP 446 Newly Created File Descriptors Are Non-Inheritable,,New Features<15>
@anchor{whatsnew/3 4 pep-453-explicit-bootstrapping-of-pip-in-python-installations}@anchor{12a1}@anchor{whatsnew/3 4 whatsnew-pep-453}@anchor{1286}
@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{12a2}
@subsubsection Bootstrapping pip By Default


The new @ref{58,,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{11a,,venv}
module make use of the @ref{58,,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 @code{venv} module
@ref{12a3,,API} installation of @code{pip} must be requested explicitly.

For CPython @ref{12a4,,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 Σημείωση 
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{12a5}
@subsubsection Documentation Changes


As part of this change, the @ref{12a6,,Installing Python modules} 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{12a7,,Κατασκευή Επεκτάσεων C και C++ με το setuptools}
and @ref{12a8,,Κατασκευή Επεκτάσεων C και C++ με το setuptools}.


@subsubheading Δείτε επίσης



@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,New Features<15>
@anchor{whatsnew/3 4 pep-446-newly-created-file-descriptors-are-non-inheritable}@anchor{12a9}@anchor{whatsnew/3 4 whatsnew-pep-446}@anchor{1287}
@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{12aa,,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{12ab,,os.get_inheritable()}, @ref{12ac,,os.set_inheritable()}

@item 
@ref{12ad,,os.get_handle_inheritable()}, @ref{12ae,,os.set_handle_inheritable()}

@item 
@ref{12af,,socket.socket.get_inheritable()}, @ref{12b0,,socket.socket.set_inheritable()}
@end itemize


@subsubheading Δείτε επίσης



@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,New Features<15>
@anchor{whatsnew/3 4 codec-handling-improvements}@anchor{1289}@anchor{whatsnew/3 4 improvements-to-codec-handling}@anchor{12b1}
@subsubsection Improvements to Codec Handling


Since it was first introduced, the @ref{1c,,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{1df,,str},
@ref{1c7,,bytes} and @ref{1c6,,bytearray} types, has historically obscured that
fact.

As a key step in clarifying the situation, the @ref{12b2,,codecs.encode()} and
@ref{12b3,,codecs.decode()} convenience functions are now properly documented in
Python 2.7, 3.3 and 3.4. These functions have existed in the @ref{1c,,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{1df,,str}, @ref{1c7,,bytes} and
@ref{1c6,,bytearray}, the @ref{1c,,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{12b4,,Binary Transforms} and @ref{12b5,,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,Other Language Changes<10>,Improvements to Codec Handling,New Features<15>
@anchor{whatsnew/3 4 pep-451-a-modulespec-type-for-the-import-system}@anchor{12b6}@anchor{whatsnew/3 4 whatsnew-pep-451}@anchor{128a}
@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{12b7,,Deprecated} section for a list of methods that should be replaced and
their replacements.

@node Other Language Changes<10>,,PEP 451 A ModuleSpec Type for the Import System,New Features<15>
@anchor{whatsnew/3 4 other-language-changes}@anchor{12b8}
@subsubsection Other Language Changes


Some smaller changes made to the core Python language are:


@itemize *

@item 
Unicode database updated to UCD version 6.3.

@item 
@ref{12b9,,min()} and @ref{12ba,,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{12bb,,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{1171,,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{1171,,codec} @code{cp1125}.  (Contributed by
Serhiy Storchaka in bpo-19668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19668}.)

@item 
@ref{1c7,,bytes}.join() and @ref{1c6,,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{326,,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{784,,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{1d2,,memoryview} is now registered as a @ref{1f,,Sequence},
and supports the @ref{c3c,,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{ca9,,help()} have been modified and improved in
several cases as a result of the introduction of Argument Clinic and other
changes to the @ref{81,,inspect} and @ref{bd,,pydoc} modules.

@item 
@ref{12bc,,__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 New Modules<10>,Improved Modules<10>,New Features<15>,What’s New In Python 3 4
@anchor{whatsnew/3 4 new-modules}@anchor{12bd}
@subsection New Modules


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

@end menu

@node asyncio<15>,ensurepip<2>,,New Modules<10>
@anchor{whatsnew/3 4 asyncio}@anchor{12be}@anchor{whatsnew/3 4 whatsnew-asyncio}@anchor{128c}
@subsubsection asyncio


The new @ref{b,,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{5fd,,provisional API}.


@subsubheading Δείτε επίσης



@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<15>,New Modules<10>
@anchor{whatsnew/3 4 ensurepip}@anchor{12bf}@anchor{whatsnew/3 4 whatsnew-ensurepip}@anchor{128d}
@subsubsection ensurepip


The new @ref{58,,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{58,,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<15>,ensurepip<2>,New Modules<10>
@anchor{whatsnew/3 4 enum}@anchor{12c0}@anchor{whatsnew/3 4 whatsnew-enum}@anchor{128e}
@subsubsection enum


The new @ref{59,,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{d4,,socket}) to provide more informative error messages and better
debugging support by replacing opaque integer constants with backwards
compatible enumeration values.


@subsubheading Δείτε επίσης



@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<15>,selectors<2>,enum<9>,New Modules<10>
@anchor{whatsnew/3 4 pathlib}@anchor{12c1}@anchor{whatsnew/3 4 whatsnew-pathlib}@anchor{128f}
@subsubsection pathlib


The new @ref{a8,,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{5fd,,provisional API}.


@subsubheading Δείτε επίσης



@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<15>,New Modules<10>
@anchor{whatsnew/3 4 selectors}@anchor{12c2}@anchor{whatsnew/3 4 whatsnew-selectors}@anchor{1290}
@subsubsection selectors


The new @ref{ca,,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{c9,,select} module primitives.

@node statistics<6>,tracemalloc<4>,selectors<2>,New Modules<10>
@anchor{whatsnew/3 4 statistics}@anchor{12c3}@anchor{whatsnew/3 4 whatsnew-statistics}@anchor{1291}
@subsubsection statistics


The new @ref{da,,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 Δείτε επίσης



@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>,New Modules<10>
@anchor{whatsnew/3 4 tracemalloc}@anchor{12c4}@anchor{whatsnew/3 4 whatsnew-tracemalloc}@anchor{1292}
@subsubsection tracemalloc


The new @ref{108,,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 Δείτε επίσης



@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 Improved Modules<10>,CPython Implementation Changes,New Modules<10>,What’s New In Python 3 4
@anchor{whatsnew/3 4 improved-modules}@anchor{12c5}
@subsection Improved Modules


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

@end menu

@node abc,aifc<2>,,Improved Modules<10>
@anchor{whatsnew/3 4 abc}@anchor{12c6}
@subsubsection abc


New function @ref{12c7,,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{12c8,,ABC} has @ref{12c9,,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<8>,abc,Improved Modules<10>
@anchor{whatsnew/3 4 aifc}@anchor{12ca}
@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{20a,,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{436,,bytes-like object}.  (Contributed by Serhiy
Storchaka in bpo-8311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8311}.)

@node argparse<8>,audioop,aifc<2>,Improved Modules<10>
@anchor{whatsnew/3 4 argparse}@anchor{12cb}
@subsubsection argparse


The @ref{31e,,FileType} class now accepts `encoding' and
`errors' arguments, which are passed through to @ref{32b,,open()}.  (Contributed
by Lucas Maystre in bpo-11175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11175}.)

@node audioop,base64<5>,argparse<8>,Improved Modules<10>
@anchor{whatsnew/3 4 audioop}@anchor{12cc}
@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{436,,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<5>,collections<7>,audioop,Improved Modules<10>
@anchor{whatsnew/3 4 base64}@anchor{12cd}
@subsubsection base64


The encoding and decoding functions in @ref{f,,base64} now accept any
@ref{436,,bytes-like object} in cases where it previously required a
@ref{1c7,,bytes} or @ref{1c6,,bytearray} instance.  (Contributed by Nick Coghlan in
bpo-17839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17839}.)

New functions @ref{12ce,,a85encode()}, @ref{1f4,,a85decode()},
@ref{1f0,,b85encode()}, and @ref{1f2,,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<7>,colorsys,base64<5>,Improved Modules<10>
@anchor{whatsnew/3 4 collections}@anchor{12cf}
@subsubsection collections


The @ref{12d0,,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<7>,collections<7>,Improved Modules<10>
@anchor{whatsnew/3 4 colorsys}@anchor{12d1}
@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<7>,dbm<7>,colorsys,Improved Modules<10>
@anchor{whatsnew/3 4 contextlib}@anchor{12d2}
@subsubsection contextlib


The new @ref{12d3,,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{119f,,contextlib.redirect_stdout()} context manager makes it easier
for utility scripts to handle inflexible APIs that write their output to
@ref{e9c,,sys.stdout} and don’t provide any options to redirect it.  Using the
context manager, the @code{sys.stdout} output can be redirected to any
other stream or, in conjunction with @ref{12d4,,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 @code{sys.stdout}.  (Contributed by Raymond Hettinger
in bpo-15805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15805}.)

The @ref{27,,contextlib} documentation has also been updated to include a
@ref{12d5,,discussion} of the
differences between single use, reusable and reentrant context managers.

@node dbm<7>,dis<5>,contextlib<7>,Improved Modules<10>
@anchor{whatsnew/3 4 dbm}@anchor{12d6}
@subsubsection dbm


@ref{12d7,,dbm.open()} objects now support the context management protocol.  When
used in a @ref{20a,,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<5>,doctest<4>,dbm<7>,Improved Modules<10>
@anchor{whatsnew/3 4 dis}@anchor{12d8}
@subsubsection dis


Functions @ref{12d9,,show_code()}, @ref{496,,dis()}, @ref{497,,distb()}, and
@ref{498,,disassemble()} now accept a keyword-only `file' argument that
controls where they write their output.

The @ref{3b,,dis} module is now built around an @ref{494,,Instruction} class
that provides object oriented access to the details of each individual bytecode
operation.

A new method, @ref{6f1,,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{3b,,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{3b,,dis} module have been rewritten to use
these new components.

In addition, a new application-friendly class @ref{495,,Bytecode} provides
an object-oriented API for inspecting bytecode in both in human-readable form
and for iterating over instructions.  The @code{Bytecode} constructor
takes the same arguments that @ref{6f1,,get_instructions()} does (plus an
optional `current_offset'), and the resulting object can be iterated to produce
@ref{494,,Instruction} objects.  But it also has a @ref{12da,,dis}
method, equivalent to calling @ref{496,,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{495,,Bytecode} also has a class method,
@ref{12db,,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{12dc,,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<6>,dis<5>,Improved Modules<10>
@anchor{whatsnew/3 4 doctest}@anchor{12dd}
@subsubsection doctest


A new @ref{12de,,option flag}, @ref{12df,,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{3d,,doctest} command line interface now uses @ref{7,,argparse}, and has two
new options, @code{-o} and @code{-f}.  @code{-o} allows @ref{12de,,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{10f,,unittest} CLI).  (Contributed by R. David Murray in bpo-11390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11390}.)

@ref{3d,,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<6>,filecmp,doctest<4>,Improved Modules<10>
@anchor{whatsnew/3 4 email}@anchor{12e0}
@subsubsection email


@ref{12e1,,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{43,,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{12e2,,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{780,,Message} @ref{12e3,,__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{12e4,,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{1296}
A pair of new subclasses of @ref{780,,Message} have been added
(@ref{216,,EmailMessage} and @ref{12e5,,MIMEPart}), along with a new sub-module,
@ref{40,,contentmanager} and a new @ref{52,,policy} attribute
@ref{12e6,,content_manager}.  All documentation is
currently in the new module, which is being added as part of email’s new
@ref{5fd,,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 @code{contentmanager} documentation and
the @ref{12e7,,email; Examples}.  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<8>,email<6>,Improved Modules<10>
@anchor{whatsnew/3 4 filecmp}@anchor{12e8}
@subsubsection filecmp


A new @ref{12e9,,clear_cache()} function provides the ability to clear the
@ref{5d,,filecmp} comparison cache, which uses @ref{4f5,,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{12ea,,DEFAULT_IGNORES} provides the list of
directories that are used as the default value for the `ignore' parameter of
the @ref{12eb,,dircmp()} function.  (Contributed by Eli Bendersky in
bpo-15442@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15442}.)

@node functools<8>,gc<8>,filecmp,Improved Modules<10>
@anchor{whatsnew/3 4 functools}@anchor{12ec}
@subsubsection functools


The new @ref{4a7,,partialmethod()} descriptor brings partial argument
application to descriptors, just as @ref{4a6,,partial()} provides
for normal callables. The new descriptor also makes it easier to get
arbitrary callables (including @code{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{1293}
The new @ref{a2a,,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 Δείτε επίσης



@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{12ed,,total_ordering()} now supports a return value of
@ref{440,,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{4a6,,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<8>,glob<5>,functools<8>,Improved Modules<10>
@anchor{whatsnew/3 4 gc}@anchor{12ee}
@subsubsection gc


New function @ref{557,,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<5>,hashlib<7>,gc<8>,Improved Modules<10>
@anchor{whatsnew/3 4 glob}@anchor{12ef}
@subsubsection glob


A new function @ref{12f0,,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<7>,hmac<4>,glob<5>,Improved Modules<10>
@anchor{whatsnew/3 4 hashlib}@anchor{12f1}
@subsubsection hashlib


A new @ref{91e,,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{12f2,,name} attribute of @ref{6b,,hashlib} hash objects is now
a formally supported interface.  It has always existed in CPython’s
@code{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<4>,html,hashlib<7>,Improved Modules<10>
@anchor{whatsnew/3 4 hmac}@anchor{12f3}
@subsubsection hmac


@ref{6d,,hmac} now accepts @code{bytearray} as well as @code{bytes} for the `key'
argument to the @ref{e65,,new()} function, and the `msg' parameter to both the
@code{new()} function and the @ref{12f4,,update()} method now
accepts any type supported by the @ref{6b,,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{e65,,hmac.new()} function may now be any hash
digest name recognized by @ref{6b,,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{12f5,,block_size} and @ref{12f6,,name}
attributes (and the formal documentation of the @ref{12f7,,digest_size}
attribute), the @ref{6d,,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<4>,hmac<4>,Improved Modules<10>
@anchor{whatsnew/3 4 html}@anchor{12f8}
@subsubsection html


New function @ref{d21,,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{c4d,,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{c4d,,HTMLParser} is now deprecated.
(Contributed by Ezio Melotti in bpo-15114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15114}.)

@node http<4>,idlelib and IDLE<4>,html,Improved Modules<10>
@anchor{whatsnew/3 4 http}@anchor{12f9}
@subsubsection http


@ref{12fa,,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
@ref{12fb,,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{75,,http.server} @ref{227,,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<4>,Improved Modules<10>
@anchor{whatsnew/3 4 idlelib-and-idle}@anchor{12fc}
@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<10>,idlelib and IDLE<4>,Improved Modules<10>
@anchor{whatsnew/3 4 importlib}@anchor{12fd}
@subsubsection importlib


The @ref{12fe,,InspectLoader} ABC defines a new method,
@ref{1cb,,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{12fe,,InspectLoader} also now has a default implementation
for the @ref{12ff,,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{928,,reload()} function has been moved from @code{imp} to
@ref{7a,,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{80,,importlib.util} now has a @ref{922,,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{80,,importlib.util} functions @ref{330,,cache_from_source()}
and @ref{929,,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{7a,,importlib} bootstrap @ref{1300,,NamespaceLoader} now conforms to
the @ref{12fe,,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{80,,importlib.util} has a new function @ref{1301,,decode_source()}
that decodes source from bytes using universal newline processing.  This is
useful for implementing @ref{1302,,InspectLoader.get_source()} methods.

@ref{1071,,importlib.machinery.ExtensionFileLoader} now has a
@ref{1303,,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<10>,ipaddress<5>,importlib<9>,Improved Modules<10>
@anchor{whatsnew/3 4 inspect}@anchor{1304}
@subsubsection inspect


The @ref{81,,inspect} module now offers a basic @ref{1305,,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{1306,,unwrap()} makes it easy to unravel wrapper function chains
created by @ref{1307,,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{59,,enum} module, the
@ref{81,,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{b1f,,getfullargspec()} and @code{getargspec()}
now use the @ref{4bd,,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{4a6,,functools.partial()} objects and more. Note that, unlike
@code{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
@code{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{4bd,,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<10>,Improved Modules<10>
@anchor{whatsnew/3 4 ipaddress}@anchor{1308}
@subsubsection ipaddress


@ref{83,,ipaddress} was added to the standard library in Python 3.3 as a
@ref{5fd,,provisional API}. With the release of Python 3.4, this qualification
has been removed: @code{ipaddress} is now considered a stable API, covered
by the normal standard library requirements to maintain backwards
compatibility.

A new @ref{1309,,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>,Improved Modules<10>
@anchor{whatsnew/3 4 logging}@anchor{130a}
@subsubsection logging


The @ref{130b,,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{130c,,SocketHandler} and
@ref{130d,,DatagramHandler} now support Unix domain sockets (by
setting `port' to @code{None}).  (Contributed by Vinay Sajip in commit
ce46195b56a9.)

@ref{f0e,,fileConfig()} now accepts a
@ref{130e,,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
@code{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{130f,,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<4>,logging<6>,Improved Modules<10>
@anchor{whatsnew/3 4 marshal}@anchor{1310}@anchor{whatsnew/3 4 whatsnew-marshal-3}@anchor{128b}
@subsubsection marshal


The default @ref{90,,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<4>,multiprocessing<8>,marshal<2>,Improved Modules<10>
@anchor{whatsnew/3 4 mmap}@anchor{1311}
@subsubsection mmap


mmap objects are now @ref{12bb,,weakly referenceable}.
(Contributed by Valerie Lambert in bpo-4885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4885}.)

@node multiprocessing<8>,operator<4>,mmap<4>,Improved Modules<10>
@anchor{whatsnew/3 4 multiprocessing}@anchor{1312}
@subsubsection multiprocessing

@anchor{whatsnew/3 4 whatsnew-multiprocessing-no-fork}@anchor{1295}
On Unix two new @ref{46d,,start methods},
@code{spawn} and @code{forkserver}, have been added for starting processes using
@ref{98,,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{1313,,get_all_start_methods()} reports all start methods
available on the platform, @ref{1314,,get_start_method()} reports
the current start method, and @ref{4d7,,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{98,,multiprocessing} also now has the concept of a @code{context}, which
determines how child processes are created.  New function
@ref{4d6,,get_context()} returns a context that uses a specified
start method.  It has the same API as the @code{multiprocessing} module itself,
so you can use it to create @ref{1315,,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{98,,multiprocessing} now relies on @ref{c6,,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<4>,os<13>,multiprocessing<8>,Improved Modules<10>
@anchor{whatsnew/3 4 operator}@anchor{1316}
@subsubsection operator


New function @ref{1317,,length_hint()} provides an implementation of the
specification for how the @ref{12bc,,__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{a3,,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<13>,pdb<9>,operator<4>,Improved Modules<10>
@anchor{whatsnew/3 4 os}@anchor{1318}
@subsubsection os


There are new functions to get and set the @ref{12aa,,inheritable flag} of a file descriptor (@ref{12ab,,os.get_inheritable()},
@ref{12ac,,os.set_inheritable()}) or a Windows handle
(@ref{12ad,,os.get_handle_inheritable()}, @ref{12ae,,os.set_handle_inheritable()}).

New function @ref{6e1,,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{1319,,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{131a,,os.path.samestat()} is now available on the Windows platform (and the
@ref{131b,,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{dd6,,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{114b,,os.open()} supports two new flags on platforms that provide them,
@ref{131c,,O_PATH} (un-opened file descriptor), and @ref{131d,,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<9>,pickle<6>,os<13>,Improved Modules<10>
@anchor{whatsnew/3 4 pdb}@anchor{131e}
@subsubsection pdb


@ref{aa,,pdb} has been enhanced to handle generators, @ref{d93,,yield}, and
@code{yield from} in a more useful fashion.  This is especially helpful when
debugging @ref{b,,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{aa,,pdb}, restoring access to the
Python @ref{131f,,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{1320,,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<6>,plistlib<2>,pdb<9>,Improved Modules<10>
@anchor{whatsnew/3 4 pickle}@anchor{1321}@anchor{whatsnew/3 4 whatsnew-protocol-4}@anchor{1294}
@subsubsection pickle


@ref{ab,,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 @ref{982,,__new__()} method takes
keyword-only arguments.  It also provides some efficiency improvements.


@subsubheading Δείτε επίσης



@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<6>,Improved Modules<10>
@anchor{whatsnew/3 4 plistlib}@anchor{1322}
@subsubsection plistlib


@ref{b0,,plistlib} now has an API that is similar to the standard pattern for
stdlib serialization protocols, with new @ref{d1a,,load()},
@ref{d1c,,dump()}, @ref{d1b,,loads()}, and @ref{d1d,,dumps()}
functions.  (The older API is now deprecated.)  In addition to the already
supported XML plist format (@ref{1323,,FMT_XML}), it also now supports
the binary plist format (@ref{1324,,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<5>,plistlib<2>,Improved Modules<10>
@anchor{whatsnew/3 4 poplib}@anchor{1325}
@subsubsection poplib


Two new methods have been added to @ref{b1,,poplib}: @ref{1326,,capa()},
which returns the list of capabilities advertised by the POP server, and
@ref{1327,,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<5>,pty<2>,poplib<3>,Improved Modules<10>
@anchor{whatsnew/3 4 pprint}@anchor{1328}
@subsubsection pprint


The @ref{b3,,pprint} module’s @ref{1329,,PrettyPrinter} class and its
@ref{132a,,pformat()}, and @ref{c01,,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<2>,pydoc<5>,pprint<5>,Improved Modules<10>
@anchor{whatsnew/3 4 pty}@anchor{132b}
@subsubsection pty


@ref{132c,,pty.spawn()} now returns the status value from @ref{1153,,os.waitpid()} on
the child process, instead of @code{None}.  (Contributed by Gregory P. Smith.)

@node pydoc<5>,re<10>,pty<2>,Improved Modules<10>
@anchor{whatsnew/3 4 pydoc}@anchor{132d}
@subsubsection pydoc


The @ref{bd,,pydoc} module is now based directly on the @ref{4bd,,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{bd,,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{bd,,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{81,,inspect} module.

As the @ref{ca9,,help()} builtin is based on @ref{bd,,pydoc}, the above changes also
affect the behaviour of @code{help()}.

@node re<10>,resource<2>,pydoc<5>,Improved Modules<10>
@anchor{whatsnew/3 4 re}@anchor{132e}
@subsubsection re


New @ref{132f,,fullmatch()} function and @ref{1330,,Pattern.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{1331,,regex objects} now includes the pattern
and the flags; the repr of @ref{1332,,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<2>,select,re<10>,Improved Modules<10>
@anchor{whatsnew/3 4 resource}@anchor{1333}
@subsubsection resource


New @ref{3e8,,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{1334,,RLIMIT_MSGQUEUE},
@ref{1335,,RLIMIT_NICE}, @ref{1336,,RLIMIT_RTPRIO},
@ref{1337,,RLIMIT_RTTIME}, and @ref{1338,,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{1339,,RLIMIT_SBSIZE}, @ref{133a,,RLIMIT_SWAP}, and
@ref{133b,,RLIMIT_NPTS}.  (Contributed by Claudiu Popa in
bpo-19343@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19343}.)

@node select,shelve<3>,resource<2>,Improved Modules<10>
@anchor{whatsnew/3 4 select}@anchor{133c}
@subsubsection select


@ref{133d,,epoll} objects now support the context management protocol.
When used in a @ref{20a,,with} statement, the @ref{133e,,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{133f,,devpoll} objects now have @ref{1340,,fileno()} and
@ref{1341,,close()} methods, as well as a new attribute
@ref{1342,,closed}.  (Contributed by Victor Stinner in
bpo-18794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18794}.)

@node shelve<3>,shutil<6>,select,Improved Modules<10>
@anchor{whatsnew/3 4 shelve}@anchor{1343}
@subsubsection shelve


@ref{1344,,Shelf} instances may now be used in @ref{20a,,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 shutil<6>,smtpd<3>,shelve<3>,Improved Modules<10>
@anchor{whatsnew/3 4 shutil}@anchor{1345}
@subsubsection shutil


@ref{e1d,,copyfile()} now raises a specific @ref{1346,,Error} subclass,
@ref{1347,,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>,shutil<6>,Improved Modules<10>
@anchor{whatsnew/3 4 smtpd}@anchor{1348}
@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<11>,smtpd<3>,Improved Modules<10>
@anchor{whatsnew/3 4 smtplib}@anchor{1349}
@subsubsection smtplib


@ref{134a,,SMTPException} is now a subclass of @ref{53c,,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<11>,sqlite3<11>,smtplib<3>,Improved Modules<10>
@anchor{whatsnew/3 4 socket}@anchor{134b}
@subsubsection socket


The socket module now supports the @ref{134c,,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{12aa,,inheritable flag}, @ref{12af,,get_inheritable()} and
@ref{12b0,,set_inheritable()}.

The @code{socket.AF_*} and @code{socket.SOCK_*} constants are now enumeration values
using the new @ref{59,,enum} module.  This allows meaningful names to be printed
during debugging, instead of integer «magic numbers».

The @ref{134d,,AF_LINK} constant is now available on BSD and OSX.

@ref{d2c,,inet_pton()} and @ref{134e,,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<11>,ssl<12>,socket<11>,Improved Modules<10>
@anchor{whatsnew/3 4 sqlite3}@anchor{134f}
@subsubsection sqlite3


A new boolean parameter to the @ref{3e0,,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<12>,stat,sqlite3<11>,Improved Modules<10>
@anchor{whatsnew/3 4 ssl}@anchor{1350}
@subsubsection ssl

@anchor{whatsnew/3 4 whatsnew-tls-11-12}@anchor{1298}
@ref{1351,,PROTOCOL_TLSv1_1} and @ref{1352,,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{129b}
New function @ref{68e,,create_default_context()} provides a standard way to
obtain an @ref{336,,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 @code{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
@code{create_default_context()} to obtain an @code{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{336,,SSLContext} method @ref{129c,,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{1353,,get_default_verify_paths()} returns
a named tuple of the paths and environment variables that the
@ref{1354,,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{336,,SSLContext} has a new method,
@ref{1355,,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{1356,,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{336,,SSLContext} has a new
attribute @ref{1357,,verify_flags} that can be used to control the
certificate verification process by setting it to some combination of the new
constants @ref{1358,,VERIFY_DEFAULT}, @ref{1359,,VERIFY_CRL_CHECK_LEAF},
@ref{135a,,VERIFY_CRL_CHECK_CHAIN}, or @ref{690,,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{336,,SSLContext} method @ref{135b,,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{135c,,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{135d,,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{1299}
Two new windows-only functions, @ref{135e,,enum_certificates()} and
@ref{135f,,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{129a}
Support for server-side SNI (Server Name Indication) using the new
@ref{1360,,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{1361,,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<3>,ssl<12>,Improved Modules<10>
@anchor{whatsnew/3 4 stat}@anchor{1362}
@subsubsection stat


The @ref{d9,,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{1363,,ST_MODE} flags, @ref{1364,,S_IFDOOR},
@ref{1365,,S_IFPORT}, and @ref{1366,,S_IFWHT}.  (Contributed by
Christian Hiemes in bpo-11016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11016}.)

@node struct<3>,subprocess<6>,stat,Improved Modules<10>
@anchor{whatsnew/3 4 struct}@anchor{1367}
@subsubsection struct


New function @ref{1368,,iter_unpack} and a new
@ref{1369,,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<6>,sunau<2>,struct<3>,Improved Modules<10>
@anchor{whatsnew/3 4 subprocess}@anchor{136a}
@subsubsection subprocess


@ref{136b,,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}.)

@ref{136c,,getoutput()} and @ref{136d,,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<13>,subprocess<6>,Improved Modules<10>
@anchor{whatsnew/3 4 sunau}@anchor{136e}
@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{20a,,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{436,,bytes-like object}.  (Contributed by Serhiy Storchaka in bpo-8311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8311}.)

@node sys<13>,tarfile<9>,sunau<2>,Improved Modules<10>
@anchor{whatsnew/3 4 sys}@anchor{136f}
@subsubsection sys


New function @ref{1370,,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{1026,,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{656,,interactive mode}, it checks for an @ref{1371,,__interactivehook__} attribute
on the @ref{e2,,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 μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP} file is read, so it can be set there.  The @ref{cf,,site}
module @ref{1372,,sets it} to a function that enables tab
completion and history saving (in @code{~/.python-history}) if the platform
supports @ref{c2,,readline}.  If you do not want this (new) behavior, you can
override it in 
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@code{PYTHONSTARTUP}, @ref{d0,,sitecustomize}, or
@ref{117,,usercustomize} by deleting this attribute from @code{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<9>,textwrap<2>,sys<13>,Improved Modules<10>
@anchor{whatsnew/3 4 tarfile}@anchor{1373}
@subsubsection tarfile


The @ref{e7,,tarfile} module now supports a simple @ref{1374,,Command-Line Interface} 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<2>,threading<10>,tarfile<9>,Improved Modules<10>
@anchor{whatsnew/3 4 textwrap}@anchor{1375}
@subsubsection textwrap


The @ref{1376,,TextWrapper} class has two new attributes/constructor
arguments: @ref{1377,,max_lines}, which limits the number of
lines in the output, and @ref{1378,,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{1379,,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<10>,traceback<6>,textwrap<2>,Improved Modules<10>
@anchor{whatsnew/3 4 threading}@anchor{137a}
@subsubsection threading


The @ref{420,,Thread} object representing the main thread can be
obtained from the new @ref{137b,,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<9>,threading<10>,Improved Modules<10>
@anchor{whatsnew/3 4 traceback}@anchor{137c}
@subsubsection traceback


A new @ref{137d,,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<9>,urllib<5>,traceback<6>,Improved Modules<10>
@anchor{whatsnew/3 4 types}@anchor{137e}
@subsubsection types


A new @ref{a1b,,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 @ref{59,,enum} for an example).
(Contributed by Ethan Furman in bpo-19030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19030}.)

@node urllib<5>,unittest<11>,types<9>,Improved Modules<10>
@anchor{whatsnew/3 4 urllib}@anchor{137f}
@subsubsection urllib


@ref{114,,urllib.request} now supports @code{data:} URLs via the
@ref{1380,,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{1381,,Request} class
can now be specified by setting a @ref{1382,,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{1381,,Request} objects are now reusable: if the
@ref{1383,,full_url} or @ref{1384,,data}
attributes are modified, all relevant internal properties are updated.  This
means, for example, that it is now possible to use the same
@code{Request} object in more than one
@ref{1385,,OpenerDirector.open()} call with different `data' arguments, or to
modify a @code{Request}“s @code{url} rather than recomputing it
from scratch.  There is also a new
@ref{1386,,remove_header()} method that can be used to remove
headers from a @code{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{1387,,HTTPError} objects now have a
@ref{1388,,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<11>,venv<8>,urllib<5>,Improved Modules<10>
@anchor{whatsnew/3 4 unittest}@anchor{1389}
@subsubsection unittest


The @ref{52f,,TestCase} class has a new method,
@ref{138a,,subTest()}, that produces a context manager whose
@ref{20a,,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{138b,,Distinguishing test iterations using subtests} 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{138c,,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{138d,,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{138e,,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{11ad,,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 @code{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{29f,,assertLogs()},
will ensure that a given block of code emits a log message using the
@ref{8a,,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{138f,,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{110,,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}.)

@ref{1390,,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<8>,wave<4>,unittest<11>,Improved Modules<10>
@anchor{whatsnew/3 4 venv}@anchor{1391}
@subsubsection venv


@ref{11a,,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{772,,EnvBuilder} and the @ref{773,,create()} convenience function
take a new keyword argument `with_pip', which defaults to @code{False}, that
controls whether or not @code{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<4>,weakref<2>,venv<8>,Improved Modules<10>
@anchor{whatsnew/3 4 wave}@anchor{1392}
@subsubsection wave


The @ref{1393,,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{d17,,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{11c,,wave} can now @ref{1394,,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{1395,,writeframesraw()} and
@ref{1396,,writeframes()} methods now accept any @ref{436,,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<4>,Improved Modules<10>
@anchor{whatsnew/3 4 weakref}@anchor{1397}
@subsubsection weakref


New @ref{1398,,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{e3e,,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{1399,,ref} is now
exposed via the @ref{139a,,__callback__} attribute.  (Contributed
by Mark Dickinson in bpo-17643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17643}.)

@node xml etree<2>,zipfile<6>,weakref<2>,Improved Modules<10>
@anchor{whatsnew/3 4 xml-etree}@anchor{139b}
@subsubsection xml.etree


A new parser, @ref{139c,,XMLPullParser}, allows a
non-blocking applications to parse XML documents.  An example can be
seen at @ref{139d,,Pull API for non-blocking parsing}.  (Contributed by Antoine
Pitrou in bpo-17741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17741}.)

The @ref{12e,,xml.etree.ElementTree} @ref{139e,,tostring()} and
@ref{139f,,tostringlist()} functions, and the
@ref{d19,,ElementTree}
@ref{e5b,,write()} method, now have a
`short_empty_elements' @ref{7a3,,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<6>,,xml etree<2>,Improved Modules<10>
@anchor{whatsnew/3 4 zipfile}@anchor{13a0}
@subsubsection zipfile


The @ref{13a1,,writepy()} method of the
@ref{13a2,,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{ab1,,ZipFile} and
@ref{13a2,,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,Deprecated<14>,Improved Modules<10>,What’s New In Python 3 4
@anchor{whatsnew/3 4 cpython-implementation-changes}@anchor{13a3}
@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:: 
* Other Improvements: Other Improvements<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{13a4}@anchor{whatsnew/3 4 whatsnew-pep-445}@anchor{129e}
@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 Δείτε επίσης



@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{13a5}@anchor{whatsnew/3 4 whatsnew-pep-442}@anchor{129d}
@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 @ref{13a6,,__del__()} methods, as well as
generators with @ref{44c,,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{a65,,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 Δείτε επίσης



@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{13a7}@anchor{whatsnew/3 4 whatsnew-pep-456}@anchor{1297}
@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{13a8,,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{13a9}@anchor{whatsnew/3 4 whatsnew-pep-436}@anchor{129f}
@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{bd,,pydoc} and @ref{81,,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 Σημείωση 
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 Δείτε επίσης



@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,Other Improvements<2>,PEP 436 Argument Clinic,CPython Implementation Changes
@anchor{whatsnew/3 4 other-build-and-c-api-changes}@anchor{13aa}
@subsubsection Other Build and C API Changes



@itemize *

@item 
The new @ref{c72,,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{81e,,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{13ab,,PyStructSequence_InitType2()} supplements the
existing @ref{13ac,,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{13ad,,PyObject_LengthHint()} is the C API equivalent
of @ref{1317,,operator.length_hint()}.  (Contributed by Armin Ronacher in
bpo-16148@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16148}.)
@end itemize

@node Other Improvements<2>,Significant Optimizations,Other Build and C API Changes,CPython Implementation Changes
@anchor{whatsnew/3 4 other-improvements}@anchor{13ae}@anchor{whatsnew/3 4 other-improvements-3-4}@anchor{13af}
@subsubsection Other Improvements

@anchor{whatsnew/3 4 whatsnew-isolated-mode}@anchor{1288}

@itemize *

@item 
The @ref{13b0,,python} command has a new @ref{13b1,,option}, @code{-I}, which causes it to run in «isolated mode»,
which means that @ref{194,,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{c2,,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{7,,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 μεταβλητή περιβάλλοντος; 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{13b2,,python regression test suite} now
also checks for memory allocation leaks, using
@ref{1370,,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{d9,,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{101c,,__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 μεταβλητή περιβάλλοντος; PYTHONIOENCODING
@ref{13b3,,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{14,,bz2}, @ref{8d,,lzma}, and @ref{6a,,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,,Other Improvements<2>,CPython Implementation Changes
@anchor{whatsnew/3 4 significant-optimizations}@anchor{13b4}
@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{c1,,re},
@ref{1e,,collections} and @ref{89,,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{c3d,,bz2.BZ2File} is now as fast or faster than the Python2 version for
most cases.  @ref{13b5,,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{13b6,,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{df,,subprocess}.  (Contributed
by Richard Oudkerk in bpo-15758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15758}.)

@item 
@ref{13b7,,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{931,,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 Deprecated<14>,Removed<14>,CPython Implementation Changes,What’s New In Python 3 4
@anchor{whatsnew/3 4 deprecated}@anchor{13b8}@anchor{whatsnew/3 4 deprecated-3-4}@anchor{12b7}
@subsection Deprecated


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{2c9,,DeprecationWarning}
when the interpreter is run with deprecation warnings enabled (for example, by
using @code{-Wd}).

@menu
* Deprecations in the Python API:: 
* Deprecated Features:: 

@end menu

@node Deprecations in the Python API,Deprecated Features,,Deprecated<14>
@anchor{whatsnew/3 4 deprecations-in-the-python-api}@anchor{13b9}
@subsubsection Deprecations in the Python API



@itemize *

@item 
As mentioned in @ref{128a,,PEP 451; A ModuleSpec Type for the Import System}, a number of @ref{7a,,importlib}
methods and functions are deprecated: @code{importlib.find_loader()} is
replaced by @ref{7a7,,importlib.util.find_spec()};
@code{importlib.machinery.PathFinder.find_module()} is replaced by
@ref{13ba,,importlib.machinery.PathFinder.find_spec()};
@code{importlib.abc.MetaPathFinder.find_module()} is replaced by
@ref{c3f,,importlib.abc.MetaPathFinder.find_spec()};
@code{importlib.abc.PathEntryFinder.find_loader()} and
@code{find_module()} are replaced by
@ref{c42,,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{c40,,importlib.abc.Loader.exec_module()},
@ref{13bb,,importlib.abc.InspectLoader.exec_module()}
@ref{13bc,,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{e65,,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{61,,ftplib} module has been documented
as deprecated in its docstring for quite some time.  It now emits a
@ref{2c9,,DeprecationWarning} and will be removed completely in Python 3.5.

@item 
The undocumented `endtime' argument to @ref{266,,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{c4d,,HTMLParser} is deprecated.

@item 
The @ref{b0,,plistlib} @code{readPlist()},
@code{writePlist()}, @code{readPlistFromBytes()}, and
@code{writePlistToBytes()} functions are deprecated in favor of the
corresponding new functions @ref{d1a,,load()}, @ref{d1c,,dump()},
@ref{d1b,,loads()}, and @ref{d1d,,dumps()}.  @code{Data()}
is deprecated in favor of just using the @ref{1c7,,bytes} constructor.

@item 
The @ref{e4,,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{b9c,,io.TextIOWrapper} (if needed) and its `newline'
argument.

@item 
The `parser' argument of @ref{3eb,,xml.etree.ElementTree.iterparse()} has
been deprecated, as has the `html' argument of
@ref{e18,,XMLParser()}.  To prepare for the removal of the
latter, all arguments to @code{XMLParser} should be passed by keyword.
@end itemize

@node Deprecated Features,,Deprecations in the Python API,Deprecated<14>
@anchor{whatsnew/3 4 deprecated-features}@anchor{13bd}
@subsubsection Deprecated Features



@itemize *

@item 
Running @ref{13be,,IDLE — Python editor and shell} 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 Removed<14>,Porting to Python 3 4,Deprecated<14>,What’s New In Python 3 4
@anchor{whatsnew/3 4 removed}@anchor{13bf}
@subsection Removed


@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>,,Removed<14>
@anchor{whatsnew/3 4 operating-systems-no-longer-supported}@anchor{13c0}
@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,Removed<14>
@anchor{whatsnew/3 4 api-and-feature-removals}@anchor{13c1}
@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{7a,,importlib}.
(Contributed by Taras Lyapun in bpo-15641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15641}.)

@item 
The `strict' argument to @ref{223,,HTTPConnection} and
@ref{224,,HTTPSConnection} has been removed.  HTTP 0.9-style
«Simple Responses» are no longer supported.

@item 
The deprecated @ref{1381,,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{90,,marshal}.  (Contributed by Dan Riti in bpo-15480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15480}.)

@item 
@ref{6e8,,inspect.Signature}: positional-only parameters are now required
to have a valid name.

@item 
@ref{a10,,object.__format__()} no longer accepts non-empty format strings, it now
raises a @ref{291,,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 @code{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{13c2,,SequenceMatcher} object
(bpo-13248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13248}).
@end itemize

@node Code Cleanups,,API and Feature Removals<5>,Removed<14>
@anchor{whatsnew/3 4 code-cleanups}@anchor{13c3}
@subsubsection Code Cleanups



@itemize *

@item 
The unused and undocumented internal @code{Scanner} class has been removed from
the @ref{bd,,pydoc} module.

@item 
The private and effectively unused @code{_gestalt} module has been removed,
along with the private @ref{af,,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{d9,,stat} constants that were included in
the @ref{e7,,tarfile} module namespace have been removed.
@end itemize

@node Porting to Python 3 4,Changed in 3 4 3,Removed<14>,What’s New In Python 3 4
@anchor{whatsnew/3 4 porting-to-python-3-4}@anchor{13c4}
@subsection Porting to Python 3.4


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

@menu
* Changes in “python” Command Behavior: Changes in “python” Command Behavior<2>. 
* Changes in the Python API: Changes in the Python API<11>. 
* Changes in the C API: Changes in the C API<9>. 

@end menu

@node Changes in “python” Command Behavior<2>,Changes in the Python API<11>,,Porting to Python 3 4
@anchor{whatsnew/3 4 changes-in-python-command-behavior}@anchor{13c5}
@subsubsection Changes in “python” Command Behavior



@itemize *

@item 
In a posix shell, setting the 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} environment variable to
an empty value is equivalent to not setting it at all.  However, setting
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} to an empty value was `not' equivalent to not setting it
at all: setting 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@code{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 μεταβλητή περιβάλλοντος; PATH
@code{PATH} works.  The behavior now conforms to the posix convention
for 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; 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{7,,argparse}) now
output @code{--version} information to @code{stdout} instead of @code{stderr} (for
issue list see @ref{13af,,Other Improvements} above).
@end itemize

@node Changes in the Python API<11>,Changes in the C API<9>,Changes in “python” Command Behavior<2>,Porting to Python 3 4
@anchor{whatsnew/3 4 changes-in-the-python-api}@anchor{13c7}
@subsubsection Changes in the Python API



@itemize *

@item 
The ABCs defined in @ref{7b,,importlib.abc} now either raise the appropriate
exception or return a default value instead of raising
@ref{59a,,NotImplementedError} blindly. This will only affect code calling
@ref{443,,super()} and falling through all the way to the ABCs. For compatibility,
catch both @code{NotImplementedError} or the appropriate exception as needed.

@item 
The module type now initializes the @ref{58c,,__package__} and
@ref{2ff,,__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{13c8,,importlib.machinery.FrozenImporter},
or if Python 2 compatibility is necessary you can use @code{imp.is_frozen()}.

@item 
@ref{de9,,py_compile.compile()} now raises @ref{13c9,,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{13ca,,importlib.abc.SourceLoader.get_source()} no longer raises
@ref{1bd,,ImportError} when the source code being loaded triggers a
@ref{17e,,SyntaxError} or @ref{dd7,,UnicodeDecodeError}. As @code{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{13cb,,functools.update_wrapper()} and @ref{1307,,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{1306,,inspect.unwrap()} to access the first function in the chain that has
no @code{__wrapped__} attribute.

@item 
@ref{b1f,,inspect.getfullargspec()} has been reimplemented on top of
@ref{4bd,,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
@code{inspect.getfullargspec()} will fail on non-Python callables may need
to be adjusted accordingly.

@item 
@ref{13cc,,importlib.machinery.PathFinder} now passes on the current working
directory to objects in @ref{13cd,,sys.path_hooks} for the empty string. This
results in @ref{9db,,sys.path_importer_cache} never containing @code{'@w{'}}, thus
iterating through @code{sys.path_importer_cache} based on @ref{194,,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{223,,HTTPConnection}
and @ref{224,,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{17e,,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{1361,,ssl.SSLSocket.getpeercert()} and @ref{121e,,ssl.SSLSocket.do_handshake()}
now raise an @ref{53c,,OSError} with @code{ENOTCONN} when the @code{SSLSocket} is not
connected, instead of the previous behavior of raising an
@ref{1a9,,AttributeError}.  In addition, @code{getpeercert()}
will raise a @ref{277,,ValueError} if the handshake has not yet been done.

@item 
@ref{1e8,,base64.b32decode()} now raises a @ref{13ce,,binascii.Error} when the
input string contains non-b32-alphabet characters, instead of a
@ref{291,,TypeError}.  This particular @code{TypeError} was missed when the other
@code{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{277,,ValueError} rather than the previous more mysterious
@ref{1a9,,AttributeError} (bpo-9177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9177}).

@item 
@ref{13cf,,slice.indices()} no longer produces an @ref{c57,,OverflowError} for huge
values.  As a consequence of this fix, @code{slice.indices()} now raises a
@ref{277,,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{328,,complex} constructor, unlike the @ref{19,,cmath} functions, was
incorrectly accepting @ref{327,,float} values if an object’s @code{__complex__}
special method returned one.  This now raises a @ref{291,,TypeError}.
(bpo-16290@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16290}.)

@item 
The @ref{326,,int} constructor in 3.2 and 3.3 erroneously accepts @ref{327,,float}
values for the `base' parameter.  It is unlikely anyone was doing this, but
if so, it will now raise a @ref{291,,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{6bd,,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{13d0,,__kwdefaults__}.
(Contributed by Yury Selivanov in bpo-20625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20625}.)

@item 
@ref{12f2,,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{11ad,,unittest.TestSuite} now drops references to tests after they
are run, test harnesses that reuse a @ref{11ad,,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{10f,,unittest} is designed to provide.  However, if the lack
of isolation is considered acceptable, the old behavior can be restored by
creating a @code{TestSuite} subclass that defines a
@code{_removeTestAtIndex} method that does nothing (see
@ref{13d1,,TestSuite.__iter__()}) (bpo-11798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11798}).

@item 
@ref{10f,,unittest} now uses @ref{7,,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{7a0,,re.split()}, @ref{13d2,,re.findall()}, and @ref{7a1,,re.sub()} functions, and
the @ref{13d3,,group()} and @ref{13d4,,groups()} methods of
@code{match} objects now always return a `bytes' object when the string
to be matched is a @ref{436,,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{c4d,,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
@code{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{e65,,hmac.new()} function will in the
future have no default, all calls to @code{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{41e,,sysconfig.get_config_var()} with the @code{SO} key, or looking
@code{SO} up in the results of a call to @ref{51e,,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{b9c,,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{10fb,,json.dump()} and @ref{248,,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{3d,,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{1f,,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{1e,,collections} automatically imports
@code{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 Changes in the C API<9>,,Changes in the Python API<11>,Porting to Python 3 4
@anchor{whatsnew/3 4 changes-in-the-c-api}@anchor{13d5}
@subsubsection Changes in the C API



@itemize *

@item 
@ref{13d6,,PyEval_EvalFrameEx()}, @ref{13d7,,PyObject_Repr()}, and
@ref{13d8,,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{63b,,PyErr_Fetch()} or
is being deliberately replaced with a different exception), an explicit
@ref{13d9,,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{10f5,,PyErr_SetImportError()} now sets @ref{291,,TypeError} when its `msg'
argument is not set. Previously only @code{NULL} was returned with no exception
set.

@item 
The result of the @ref{987,,PyOS_ReadlineFunctionPointer} callback must
now be a string allocated by @ref{2bf,,PyMem_RawMalloc()} or
@ref{825,,PyMem_RawRealloc()}, or @code{NULL} if an error occurred, instead of a
string allocated by @ref{1024,,PyMem_Malloc()} or @ref{13da,,PyMem_Realloc()}
(bpo-16742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16742})

@item 
@ref{64e,,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{b68,,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,,Porting to Python 3 4,What’s New In Python 3 4
@anchor{whatsnew/3 4 changed-in-3-4-3}@anchor{13db}
@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{13dc}@anchor{whatsnew/3 4 pep-476-enabling-certificate-verification-by-default-for-stdlib-http-clients}@anchor{13dd}
@subsubsection PEP 476: Enabling certificate verification by default for stdlib http clients


@ref{72,,http.client} and modules which use it, such as @ref{114,,urllib.request} and
@ref{137,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 3,What’s New In Python 3 2,What’s New In Python 3 4,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 3 doc}@anchor{13de}@anchor{whatsnew/3 3 translation-repo}@anchor{13df}@anchor{whatsnew/3 3 what-s-new-in-python-3-3}@anchor{13e0}
@section What’s New In 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 Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 398
PEP 398@footnote{https://peps.python.org/pep-0398/} - Python 3.3 Release Schedule


@menu
* Summary – Release highlights: Summary – Release highlights<10>. 
* 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:: 
* Other Language Changes: Other Language Changes<11>. 
* A Finer-Grained Import Lock:: 
* Builtin functions and types:: 
* New Modules: New Modules<11>. 
* Improved Modules: Improved Modules<11>. 
* Optimizations: Optimizations<13>. 
* Build and C API Changes: Build and C API Changes<4>. 
* Deprecated: Deprecated<15>. 
* Porting to Python 3.3: Porting to Python 3 3. 

@end menu

@node Summary – Release highlights<10>,PEP 405 Virtual Environments,,What’s New In Python 3 3
@anchor{whatsnew/3 3 summary-release-highlights}@anchor{13e1}
@subsection Summary – Release highlights


@c This section singles out the most important changes in Python 3.3.
@c Brevity is key.

New syntax features:


@itemize *

@item 
New @code{yield from} expression for @ref{13e2,,generator delegation}.

@item 
The @code{u'unicode'} syntax is accepted again for @ref{1df,,str} objects.
@end itemize

New library modules:


@itemize *

@item 
@ref{5b,,faulthandler} (helps debugging low-level crashes)

@item 
@ref{83,,ipaddress} (high-level objects representing IP addresses and masks)

@item 
@ref{8d,,lzma} (compress data using the XZ / LZMA algorithm)

@item 
@ref{110,,unittest.mock} (replace parts of your system under test with mock objects)

@item 
@ref{11a,,venv} (Python @ref{13e3,,virtual environments}, as in the
popular @code{virtualenv} package)
@end itemize

New built-in features:


@itemize *

@item 
Reworked @ref{13e4,,I/O exception hierarchy}.
@end itemize

Implementation improvements:


@itemize *

@item 
Rewritten @ref{13e5,,import machinery} based on @ref{7a,,importlib}.

@item 
More compact @ref{13e6,,unicode strings}.

@item 
More compact @ref{13e7,,attribute dictionaries}.
@end itemize

Significantly Improved Library Modules:


@itemize *

@item 
C Accelerator for the @ref{13e8,,decimal} module.

@item 
Better unicode handling in the @ref{13e9,,email} module
(@ref{13ea,,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,Summary – Release highlights<10>,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-405}@anchor{13e3}@anchor{whatsnew/3 3 pep-405-virtual-environments}@anchor{13eb}
@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{11a,,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 Δείτε επίσης



@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,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-420-implicit-namespace-packages}@anchor{13ec}
@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 Δείτε επίσης



@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,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-3118-new-memoryview-implementation-and-buffer-protocol-documentation}@anchor{13ed}@anchor{whatsnew/3 3 pep-3118-update}@anchor{13ee}
@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
* Features:: 
* API changes:: 

@end menu

@node Features,API changes,,PEP 3118 New memoryview implementation and buffer protocol documentation
@anchor{whatsnew/3 3 features}@anchor{13ef}
@subsubsection Features



@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,,Features,PEP 3118 New memoryview implementation and buffer protocol documentation
@anchor{whatsnew/3 3 api-changes}@anchor{13f0}
@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{13f1,,Build and C API Changes} and @ref{13f2,,Porting C code}.
@end itemize

(Contributed by Stefan Krah in bpo-10181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10181}.)


@subsubheading Δείτε επίσης


@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,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-393}@anchor{13e6}@anchor{whatsnew/3 3 pep-393-flexible-string-representation}@anchor{13f3}
@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{13f4}
@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{a1f,,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{13f5,,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{13f6}
@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 Δείτε επίσης



@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,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-397}@anchor{13f7}@anchor{whatsnew/3 3 pep-397-python-launcher-for-windows}@anchor{13f8}
@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 Δείτε επίσης



@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{9bc,,Διαχειριστής εγκατάστασης Python}

Installer PATH modification: @ref{13f9,,Διαχειριστής εγκατάστασης 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,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-3151}@anchor{13e4}@anchor{whatsnew/3 3 pep-3151-reworking-the-os-and-io-exception-hierarchy}@anchor{13fa}
@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{53c,,OSError}, @ref{13fb,,IOError}, @ref{13fc,,EnvironmentError},
@ref{13fd,,WindowsError}, @code{mmap.error}, @ref{13fe,,socket.error} or
@ref{13ff,,select.error}.  All these exception types are now only one:
@code{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{5a,,errno} module, you can catch the adequate
@ref{53c,,OSError} subclass.  The available subclasses are the following:


@itemize *

@item 
@ref{4c3,,BlockingIOError}

@item 
@ref{1400,,ChildProcessError}

@item 
@ref{11bf,,ConnectionError}

@item 
@ref{13c9,,FileExistsError}

@item 
@ref{243,,FileNotFoundError}

@item 
@ref{1141,,InterruptedError}

@item 
@ref{1401,,IsADirectoryError}

@item 
@ref{1402,,NotADirectoryError}

@item 
@ref{10f9,,PermissionError}

@item 
@ref{1403,,ProcessLookupError}

@item 
@ref{c0e,,TimeoutError}
@end itemize

And the @ref{11bf,,ConnectionError} itself has finer-grained subclasses:


@itemize *

@item 
@ref{1404,,BrokenPipeError}

@item 
@ref{1405,,ConnectionAbortedError}

@item 
@ref{1406,,ConnectionRefusedError}

@item 
@ref{1407,,ConnectionResetError}
@end itemize

Thanks to the new exceptions, common usages of the @ref{5a,,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{5a,,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 Δείτε επίσης



@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,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-380}@anchor{13e2}@anchor{whatsnew/3 3 pep-380-syntax-for-delegating-to-a-subgenerator}@anchor{1408}
@subsection PEP 380: Syntax for Delegating to a Subgenerator


PEP 380 adds the @code{yield from} expression, allowing a @ref{1409,,generator} to
delegate
part of its operations to another generator. This allows a section of code
containing @ref{d93,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 380

@item PEP 380@footnote{https://peps.python.org/pep-0380/} - Syntax for Delegating to a Subgenerator

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,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-409-suppressing-exception-context}@anchor{140a}
@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 Δείτε επίσης



@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,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-414-explicit-unicode-literals}@anchor{140b}
@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 Δείτε επίσης



@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,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-3155-qualified-name-for-classes-and-functions}@anchor{140c}
@subsection PEP 3155: Qualified name for classes and functions


Functions and class objects have a new @ref{140d,,__qualname__}
attribute representing
the «path» from the module top-level to their definition.  For global functions
and classes, this is the same as @ref{140e,,__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 Δείτε επίσης



@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,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-412}@anchor{13e7}@anchor{whatsnew/3 3 pep-412-key-sharing-dictionary}@anchor{140f}
@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 Δείτε επίσης



@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,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-362-function-signature-object}@anchor{1410}
@subsection PEP 362: Function Signature Object


A new function @ref{4bd,,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{4a6,,functools.partial()}
objects.  New classes @ref{6e8,,inspect.Signature}, @ref{6e9,,inspect.Parameter}
and @ref{1411,,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 Δείτε επίσης



@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,What’s New In Python 3 3
@anchor{whatsnew/3 3 pep-421-adding-sys-implementation}@anchor{1412}
@subsection PEP 421: Adding sys.implementation


A new attribute on the @ref{e2,,sys} module exposes details specific to the
implementation of the currently running interpreter.  The initial set of
attributes on @ref{926,,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{7a,,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{1413}
@subsubsection SimpleNamespace


The implementation of @code{sys.implementation} also introduces a new type to
Python: @ref{6ea,,types.SimpleNamespace}.  In contrast to a mapping-based
namespace, like @ref{188,,dict}, @code{SimpleNamespace} is attribute-based, like
@ref{e4d,,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 Δείτε επίσης



@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,Other Language Changes<11>,PEP 421 Adding sys implementation,What’s New In Python 3 3
@anchor{whatsnew/3 3 importlib}@anchor{13e5}@anchor{whatsnew/3 3 using-importlib-as-the-implementation-of-import}@anchor{1414}
@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{ca6,,__import__()} function is now powered by @ref{1415,,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{1416,,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{1417}
@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{7a,,importlib} package.

The abstract base classes defined in @ref{7b,,importlib.abc} have been expanded
to properly delineate between @ref{1418,,meta path finders}
and @ref{1419,,path entry finders} by introducing
@ref{c44,,importlib.abc.MetaPathFinder} and
@ref{c45,,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{141a,,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{13cd,,sys.path_hooks}.

For loaders, the new abstract base class @ref{141b,,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{141c,,importlib.machinery.SourceFileLoader}), sourceless bytecode files
(@ref{141d,,importlib.machinery.SourcelessFileLoader}), and extension modules
(@ref{1071,,importlib.machinery.ExtensionFileLoader}) are now available for
direct use.

@ref{1bd,,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{fcf,,importlib.invalidate_caches()} function will now call the method with
the same name on all finders cached in @ref{9db,,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{141e}
@subsubsection Visible Changes


For potential required changes to code, see the @ref{1416,,Porting Python code}
section.

Beyond the expanse of what @ref{7a,,importlib} now exposes, there are other
visible changes to import. The biggest is that @ref{10e3,,sys.meta_path} and
@ref{13cd,,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{7a,,importlib} and import itself is setting the attribute post-load.

@code{None} is now inserted into @ref{9db,,sys.path_importer_cache} when no finder
can be found on @ref{13cd,,sys.path_hooks}. Since @code{imp.NullImporter} is not
directly exposed on @code{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{1416,,Porting Python code} section of this document.

(Implementation by Brett Cannon)

@node Other Language Changes<11>,A Finer-Grained Import Lock,Using importlib as the Implementation of Import,What’s New In Python 3 3
@anchor{whatsnew/3 3 other-language-changes}@anchor{141f}
@subsection Other Language Changes


Some smaller changes made to the core Python language are:


@itemize *

@item 
Added support for Unicode name aliases and named sequences.
Both @ref{1420,,unicodedata.lookup()} and @code{'\N@{...@}'} now resolve name aliases,
and @code{unicodedata.lookup()} resolves named sequences too.

(Contributed by Ezio Melotti in 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{d0f,,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{1c7,,bytes} and @ref{1c6,,bytearray} objects now accept an
integer between 0 and 255 as their first argument.

(Contributed by Petri Lehtinen in bpo-12170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12170}.)

@item 
The @code{rjust()}, @code{ljust()}, and @code{center()} methods of @ref{1c7,,bytes}
and @ref{1c6,,bytearray} now accept a @code{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{4d9,,list} and @ref{1c6,,bytearray}:
@code{copy()} and @code{clear()} (bpo-10516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10516}).  Consequently,
@ref{6c6,,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"..."}.

(Contributed by Antoine Pitrou in bpo-13748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13748}.)

@item 
@ref{1421,,dict.setdefault()} now does only one lookup for the given key, making
it atomic when used with built-in types.

(Contributed by Filip Gruszczyński in 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.

(Contributed by Benjamin Peterson.)
@end itemize

@node A Finer-Grained Import Lock,Builtin functions and types,Other Language Changes<11>,What’s New In Python 3 3
@anchor{whatsnew/3 3 a-finer-grained-import-lock}@anchor{1422}
@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
@code{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.

(Contributed by Antoine Pitrou in bpo-9260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9260}.)

@node Builtin functions and types,New Modules<11>,A Finer-Grained Import Lock,What’s New In Python 3 3
@anchor{whatsnew/3 3 builtin-functions-and-types}@anchor{1423}
@subsection Builtin functions and types



@itemize *

@item 
@ref{32b,,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{1424,,os.O_CLOEXEC} for
example. The @code{'x'} mode was added: open for exclusive creation, failing if
the file already exists.

@item 
@ref{131f,,print()}: added the `flush' keyword argument. If the `flush' keyword
argument is true, the stream is forcibly flushed.

@item 
@ref{9e2,,hash()}: hash randomization is enabled by default, see
@ref{ec1,,object.__hash__()} and 
@geindex PYTHONHASHSEED
@geindex μεταβλητή περιβάλλοντος; PYTHONHASHSEED
@ref{1425,,PYTHONHASHSEED}.

@item 
The @ref{1df,,str} type gets a new @ref{118f,,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 New Modules<11>,Improved Modules<11>,Builtin functions and types,What’s New In Python 3 3
@anchor{whatsnew/3 3 new-modules}@anchor{1426}
@subsection New Modules


@menu
* faulthandler: faulthandler<6>. 
* ipaddress: ipaddress<6>. 
* lzma: lzma<2>. 

@end menu

@node faulthandler<6>,ipaddress<6>,,New Modules<11>
@anchor{whatsnew/3 3 faulthandler}@anchor{1427}
@subsubsection faulthandler


This new debug module @ref{5b,,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{219,,faulthandler.enable()} to install fault handlers for the
@ref{1428,,SIGSEGV}, @ref{1429,,SIGFPE}, @ref{142a,,SIGABRT},
@ref{142b,,SIGBUS}, and @ref{142c,,SIGILL} signals.
You can also enable them at startup by setting the 
@geindex PYTHONFAULTHANDLER
@geindex μεταβλητή περιβάλλοντος; PYTHONFAULTHANDLER
@ref{142d,,PYTHONFAULTHANDLER}
environment variable or by using @ref{178,,-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<6>,New Modules<11>
@anchor{whatsnew/3 3 ipaddress}@anchor{142e}
@subsubsection ipaddress


The new @ref{83,,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).

(Contributed by Google and Peter Moody in 
@geindex Python Enhancement Proposals; PEP 3144
PEP 3144@footnote{https://peps.python.org/pep-3144/}.)

@node lzma<2>,,ipaddress<6>,New Modules<11>
@anchor{whatsnew/3 3 lzma}@anchor{142f}
@subsubsection lzma


The newly added @ref{8d,,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 Improved Modules<11>,Optimizations<13>,New Modules<11>,What’s New In Python 3 3
@anchor{whatsnew/3 3 improved-modules}@anchor{1430}
@subsection Improved Modules


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

@end menu

@node abc<2>,array<6>,,Improved Modules<11>
@anchor{whatsnew/3 3 abc}@anchor{1431}
@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{1432,,abc.abstractproperty} has been deprecated, use @ref{6bb,,property}
with @ref{1433,,abc.abstractmethod()} instead.

@item 
@ref{1434,,abc.abstractclassmethod} has been deprecated, use
@ref{69a,,classmethod} with @ref{1433,,abc.abstractmethod()} instead.

@item 
@ref{1435,,abc.abstractstaticmethod} has been deprecated, use
@ref{666,,staticmethod} with @ref{1433,,abc.abstractmethod()} instead.
@end itemize

(Contributed by Darren Dale in bpo-11610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11610}.)

@ref{1436,,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<6>,base64<6>,abc<2>,Improved Modules<11>
@anchor{whatsnew/3 3 array}@anchor{1437}
@subsubsection array


The @ref{8,,array} module supports the long long type using @code{q} and
@code{Q} type codes.

(Contributed by Oren Tirosh and Hirokazu Yamamoto in bpo-1172711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1172711}.)

@node base64<6>,binascii<4>,array<6>,Improved Modules<11>
@anchor{whatsnew/3 3 base64}@anchor{1438}
@subsubsection base64


ASCII-only Unicode strings are now accepted by the decoding functions of the
@ref{f,,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<4>,bz2<2>,base64<6>,Improved Modules<11>
@anchor{whatsnew/3 3 binascii}@anchor{1439}
@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<4>,Improved Modules<11>
@anchor{whatsnew/3 3 bz2}@anchor{143a}
@subsubsection bz2


The @ref{14,,bz2} module has been rewritten from scratch. In the process, several
new features have been added:


@itemize *

@item 
New @ref{143b,,bz2.open()} function: open a bzip2-compressed file in binary or
text mode.

@item 
@ref{c3d,,bz2.BZ2File} can now read from and write to arbitrary file-like
objects, by means of its constructor’s `fileobj' argument.

(Contributed by Nadeem Vawda in bpo-5863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5863}.)

@item 
@ref{c3d,,bz2.BZ2File} and @ref{143c,,bz2.decompress()} can now decompress
multi-stream inputs (such as those produced by the @code{pbzip2} tool).
@code{bz2.BZ2File} can now also be used to create this type of file, using
the @code{'a'} (append) mode.

(Contributed by Nir Aides in bpo-1625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1625}.)

@item 
@ref{c3d,,bz2.BZ2File} now implements all of the @ref{a83,,io.BufferedIOBase} API,
except for the @code{detach()} and @code{truncate()} methods.
@end itemize

@node codecs<2>,collections<8>,bz2<2>,Improved Modules<11>
@anchor{whatsnew/3 3 codecs}@anchor{143d}
@subsubsection codecs


The @ref{56,,mbcs} codec has been rewritten to handle correctly
@code{replace} and @code{ignore} error handlers on all Windows versions.  The
@code{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<8>,contextlib<8>,codecs<2>,Improved Modules<11>
@anchor{whatsnew/3 3 collections}@anchor{143e}
@subsubsection collections


Addition of a new @ref{fdb,,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{1f,,collections.abc}
module, to better differentiate between the abstract and the concrete
collections classes.  Aliases for ABCs are still present in the
@ref{1e,,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{204,,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<8>,crypt<2>,collections<8>,Improved Modules<11>
@anchor{whatsnew/3 3 contextlib}@anchor{143f}
@subsubsection contextlib


@ref{208,,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{f6,,threading} module).

(bpo-13585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13585})

@node crypt<2>,curses<6>,contextlib<8>,Improved Modules<11>
@anchor{whatsnew/3 3 crypt}@anchor{1440}
@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<6>,datetime<8>,crypt<2>,Improved Modules<11>
@anchor{whatsnew/3 3 curses}@anchor{1441}
@subsubsection curses



@itemize *

@item 
If the @ref{2e,,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 
@ref{1442,,curses.window} has a new @ref{1443,,curses.window.encoding} attribute.

@item 
The @ref{1442,,curses.window} class has a new @ref{1444,,get_wch()}
method to get a wide character

@item 
The @ref{2e,,curses} module has a new @ref{1445,,unget_wch()} function to
push a wide character so the next @ref{1444,,get_wch()} will return
it
@end itemize

(Contributed by Iñigo Serna in bpo-6755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6755}.)

@node datetime<8>,decimal<4>,curses<6>,Improved Modules<11>
@anchor{whatsnew/3 3 datetime}@anchor{1446}
@subsubsection datetime



@itemize *

@item 
Equality comparisons between naive and aware @ref{6e7,,datetime}
instances now return @ref{ef5,,False} instead of raising @ref{291,,TypeError}
(bpo-15006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15006}).

@item 
New @ref{1447,,datetime.datetime.timestamp()} method: Return POSIX timestamp
corresponding to the @ref{6e7,,datetime} instance.

@item 
The @ref{1051,,datetime.datetime.strftime()} method supports formatting years
older than 1000.

@item 
The @ref{d95,,datetime.datetime.astimezone()} method can now be
called without arguments to convert datetime instance to the system
timezone.
@end itemize

@node decimal<4>,email<7>,datetime<8>,Improved Modules<11>
@anchor{whatsnew/3 3 decimal}@anchor{1448}@anchor{whatsnew/3 3 new-decimal}@anchor{13e8}
@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
* Features: Features<2>. 
* API changes: API changes<2>. 

@end menu

@node Features<2>,API changes<2>,,decimal<4>
@anchor{whatsnew/3 3 id1}@anchor{1449}
@subsubsection Features



@itemize *

@item 
The @ref{144a,,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{144b,,HAVE_THREADS} is set to @code{False}.
@end itemize

@node API changes<2>,,Features<2>,decimal<4>
@anchor{whatsnew/3 3 id2}@anchor{144c}
@subsubsection API changes



@itemize *

@item 
The C module has the following context limits, depending on the machine
architecture:

@quotation


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@tab

32-bit

@tab

64-bit

@item

@ref{144d,,MAX_PREC}

@tab

@code{425000000}

@tab

@code{999999999999999999}

@item

@ref{144e,,MAX_EMAX}

@tab

@code{425000000}

@tab

@code{999999999999999999}

@item

@ref{144f,,MIN_EMIN}

@tab

@code{-425000000}

@tab

@code{-999999999999999999}

@end multitable

@end quotation

@item 
In the context templates (@ref{1450,,DefaultContext},
@ref{1451,,BasicContext} and @ref{1452,,ExtendedContext})
the magnitude of @ref{1453,,Emax} and
@ref{1454,,Emin} has changed to @code{999999}.

@item 
The @ref{1c2,,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{1455,,InvalidOperation} is raised and the result is NaN. In the
latter case it is always possible to use @ref{1456,,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{1457,,exp()} and @ref{1458,,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{1459,,MutableMapping}.  For speed reasons,
@ref{145a,,flags} and @ref{145b,,traps} always
refer to the same @code{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{145c,,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{145c,,Context} constructor has been
changed to match the order displayed by @ref{45b,,repr()}.

@item 
The @code{watchexp} parameter in the @ref{145d,,quantize()} method
is deprecated.
@end itemize

@node email<7>,ftplib<3>,decimal<4>,Improved Modules<11>
@anchor{whatsnew/3 3 email}@anchor{145e}@anchor{whatsnew/3 3 new-email}@anchor{13e9}
@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<7>
@anchor{whatsnew/3 3 policy-framework}@anchor{145f}
@subsubsection Policy Framework


The email package now has a @ref{52,,policy} framework.  A
@ref{1460,,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{1461,,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{51,,parser}, or when a
@ref{780,,Message} object is created, or when an email is
serialized using a @ref{43,,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{105a,,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{1462,,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<7>
@anchor{whatsnew/3 3 provisional-policy-with-new-header-api}@anchor{1463}
@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{13ea,,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{1464,,EmailPolicy},
and add the following additional controls:


@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

refold_source

@tab

Controls whether or not headers parsed by a
@ref{51,,parser} are refolded by the
@ref{43,,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{44,,email.header} @ref{1465,,decode_header()} or
@ref{1466,,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<7>
@anchor{whatsnew/3 3 other-api-changes}@anchor{1467}
@subsubsection Other API Changes


New @ref{1468,,BytesHeaderParser}, added to the @ref{51,,parser}
module to complement @ref{1469,,HeaderParser} and complete the Bytes
API.

New utility functions:


@itemize *

@item 
@ref{146a,,format_datetime()}: given a @ref{6e7,,datetime},
produce a string formatted for use in an email header.

@item 
@ref{146b,,parsedate_to_datetime()}: given a date string from
an email header, convert it into an aware @ref{6e7,,datetime},
or a naive @code{datetime} if the offset is @code{-0000}.

@item 
@ref{56f,,localtime()}: With no argument, returns the
current local time as an aware @ref{6e7,,datetime} using the local
@ref{146c,,timezone}.  Given an aware @code{datetime},
converts it into an aware @code{datetime} using the
local @code{timezone}.
@end itemize

@node ftplib<3>,functools<9>,email<7>,Improved Modules<11>
@anchor{whatsnew/3 3 ftplib}@anchor{146d}
@subsubsection ftplib



@itemize *

@item 
@ref{cca,,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{ccb,,FTP_TLS} class now provides a new
@ref{146e,,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{146f,,ftplib.FTP.mlsd()} method which provides a parsable directory
listing format and deprecates @ref{1470,,ftplib.FTP.nlst()} and
@ref{1471,,ftplib.FTP.dir()}.  (Contributed by Giampaolo Rodolà in bpo-11072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11072}.)
@end itemize

@node functools<9>,gc<9>,ftplib<3>,Improved Modules<11>
@anchor{whatsnew/3 3 functools}@anchor{1472}
@subsubsection functools


The @ref{db3,,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<9>,hmac<5>,functools<9>,Improved Modules<11>
@anchor{whatsnew/3 3 gc}@anchor{1473}
@subsubsection gc


It is now possible to register callbacks invoked by the garbage collector
before and after collection using the new @ref{1474,,callbacks} list.

@node hmac<5>,http<5>,gc<9>,Improved Modules<11>
@anchor{whatsnew/3 3 hmac}@anchor{1475}
@subsubsection hmac


A new @ref{1476,,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<5>,html<2>,hmac<5>,Improved Modules<11>
@anchor{whatsnew/3 3 http}@anchor{1477}
@subsubsection http


@ref{226,,http.server.BaseHTTPRequestHandler} now buffers the headers and writes
them all at once when @ref{1478,,end_headers()} is
called.  A new method @ref{1479,,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{75,,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{147a,,http.client.HTTPResponse} now has a
@ref{147b,,readinto()} method, which means it can be used
as an @ref{147c,,io.RawIOBase} class.  (Contributed by John Kuhn in
bpo-13464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13464}.)

@node html<2>,imaplib<4>,http<5>,Improved Modules<11>
@anchor{whatsnew/3 3 html}@anchor{147d}
@subsubsection html


@ref{c4d,,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{147e,,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{6f,,html.entities} module.  The dictionary is
now also used by @ref{c4d,,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<4>,inspect<11>,html<2>,Improved Modules<11>
@anchor{whatsnew/3 3 imaplib}@anchor{147f}
@subsubsection imaplib


The @ref{cd3,,IMAP4_SSL} constructor now accepts an SSLContext
parameter to control parameters of the secure channel.

(Contributed by Sijin Joseph in bpo-8808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8808}.)

@node inspect<11>,io<8>,imaplib<4>,Improved Modules<11>
@anchor{whatsnew/3 3 inspect}@anchor{1480}
@subsubsection inspect


A new @ref{1481,,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.

(Contributed by Meador Inge and Nick Coghlan in bpo-13062@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13062}.)

A new @ref{1482,,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.

(Contributed by Meador Inge in bpo-15153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15153}.)

@node io<8>,itertools<7>,inspect<11>,Improved Modules<11>
@anchor{whatsnew/3 3 io}@anchor{1483}
@subsubsection io


The @ref{92b,,open()} function has a new @code{'x'} mode that can be used to
exclusively create a new file, and raise a @ref{13c9,,FileExistsError} if the file
already exists. It is based on the C11 “x” mode to fopen().

(Contributed by David Townshend in bpo-12760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12760}.)

The constructor of the @ref{b9c,,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 @code{TextIOWrapper} object is immediately handled to its
underlying binary buffer.

@node itertools<7>,logging<7>,io<8>,Improved Modules<11>
@anchor{whatsnew/3 3 itertools}@anchor{1484}
@subsubsection itertools


@ref{dbf,,accumulate()} now takes an optional @code{func} argument for
providing a user-supplied binary function.

@node logging<7>,math<11>,itertools<7>,Improved Modules<11>
@anchor{whatsnew/3 3 logging}@anchor{1485}
@subsubsection logging


The @ref{dc2,,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{a4c,,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<11>,mmap<5>,logging<7>,Improved Modules<11>
@anchor{whatsnew/3 3 math}@anchor{1486}
@subsubsection math


The @ref{91,,math} module has a new function, @ref{1487,,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<5>,multiprocessing<9>,math<11>,Improved Modules<11>
@anchor{whatsnew/3 3 mmap}@anchor{1488}
@subsubsection mmap


The @ref{1489,,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<9>,nntplib<2>,mmap<5>,Improved Modules<11>
@anchor{whatsnew/3 3 multiprocessing}@anchor{148a}
@subsubsection multiprocessing


The new @ref{148b,,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}.)

@ref{148c,,multiprocessing.connection.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{4de,,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{148d,,multiprocessing.Process.sentinel} allows a
program to wait on multiple @ref{4de,,Process} objects at one
time using the appropriate OS primitives (for example, @ref{c9,,select} on
posix systems).

New methods @ref{148e,,multiprocessing.pool.Pool.starmap()} and
@ref{148f,,starmap_async()} provide
@ref{1490,,itertools.starmap()} equivalents to the existing
@ref{1491,,multiprocessing.pool.Pool.map()} and
@ref{1492,,map_async()} functions.  (Contributed by Hynek
Schlawack in bpo-12708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12708}.)

@node nntplib<2>,os<14>,multiprocessing<9>,Improved Modules<11>
@anchor{whatsnew/3 3 nntplib}@anchor{1493}
@subsubsection nntplib


The @code{nntplib.NNTP} class now supports the context management protocol to
unconditionally consume @ref{13fe,,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

(Contributed by Giampaolo Rodolà in bpo-9795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9795}.)

@node os<14>,pdb<10>,nntplib<2>,Improved Modules<11>
@anchor{whatsnew/3 3 os}@anchor{1494}
@subsubsection os



@itemize *

@item 
The @ref{a5,,os} module has a new @ref{1495,,pipe2()} function that makes it
possible to create a pipe with @ref{1424,,O_CLOEXEC} or
@ref{11ee,,O_NONBLOCK} flags set atomically. This is especially useful to
avoid race conditions in multi-threaded programs.

@item 
The @ref{a5,,os} module has a new @ref{ed3,,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. @code{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{a5,,os} module has a new @ref{f18,,fwalk()} function similar to
@ref{8b9,,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{1496,,paths relative to directory descriptors}) and/or `follow_symlinks' (@ref{1497,,not following symlinks}):
@ref{1498,,access()}, @ref{1499,,chflags()}, @ref{72c,,chmod()}, @ref{149a,,chown()},
@ref{149b,,link()}, @ref{8b1,,lstat()}, @ref{72e,,mkdir()}, @ref{1149,,mkfifo()},
@ref{114a,,mknod()}, @ref{114b,,open()}, @ref{ced,,readlink()}, @ref{149c,,remove()},
@ref{149d,,rename()}, @ref{149e,,replace()}, @ref{149f,,rmdir()}, @ref{4f5,,stat()},
@ref{14a0,,symlink()}, @ref{14a1,,unlink()}, @ref{14a2,,utime()}.  Platform
support for using these parameters can be checked via the sets
@ref{14a3,,os.supports_dir_fd} and @ref{14a4,,os.supports_follow_symlinks}.

@item 
The following functions now support a file descriptor for their path argument:
@ref{a02,,chdir()}, @ref{72c,,chmod()}, @ref{149a,,chown()},
@ref{14a5,,execve()}, @ref{14a6,,listdir()}, @ref{14a7,,pathconf()}, @ref{dd2,,exists()},
@ref{4f5,,stat()}, @ref{14a8,,statvfs()}, @ref{14a2,,utime()}.  Platform support
for this can be checked via the @ref{14a9,,os.supports_fd} set.
@end itemize

@item 
@ref{1498,,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{14aa,,supports_effective_ids} set.

@item 
The @ref{a5,,os} module has two new functions: @ref{14ab,,getpriority()} and
@ref{14ac,,setpriority()}. They can be used to get or set process
niceness/priority in a fashion similar to @ref{14ad,,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{149e,,os.replace()} function allows cross-platform renaming of a
file with overwriting the destination.  With @ref{149d,,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{4f5,,stat()}, @ref{1145,,fstat()},
and @ref{8b1,,lstat()}) now support reading a file’s timestamps
with nanosecond precision.  Symmetrically, @ref{14a2,,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{14ae,,os.get_terminal_size()} function queries the size of the
terminal attached to a file descriptor. See also
@ref{14af,,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{14b0,,getxattr()}, @ref{14b1,,listxattr()}, @ref{14b2,,removexattr()},
@ref{14b3,,setxattr()}.

@item 
New interface to the scheduler. These functions
control how a process is allocated CPU time by the operating system. New
functions:
@ref{14b4,,sched_get_priority_max()}, @ref{14b5,,sched_get_priority_min()},
@ref{14b6,,sched_getaffinity()}, @ref{14b7,,sched_getparam()},
@ref{14b8,,sched_getscheduler()}, @ref{14b9,,sched_rr_get_interval()},
@ref{14ba,,sched_setaffinity()}, @ref{14bb,,sched_setparam()},
@ref{14bc,,sched_setscheduler()}, @ref{14bd,,sched_yield()},

@item 
New functions to control the file system:


@itemize *

@item 
@ref{114c,,posix_fadvise()}: Announces an intention to access data in a
specific pattern thus allowing the kernel to make optimizations.

@item 
@ref{114d,,posix_fallocate()}: Ensures that enough disk space is allocated
for a file.

@item 
@ref{14be,,sync()}: Force write of everything to disk.
@end itemize

@item 
Additional new  posix functions:


@itemize *

@item 
@ref{14bf,,lockf()}: Apply, test or remove a POSIX lock on an open file descriptor.

@item 
@ref{f1c,,pread()}: Read from a file descriptor at an offset, the file
offset remains unchanged.

@item 
@ref{f1f,,pwrite()}: Write to a file descriptor from an offset, leaving
the file offset unchanged.

@item 
@ref{f1b,,readv()}: Read from a file descriptor into a number of writable buffers.

@item 
@ref{11ef,,truncate()}: Truncate the file corresponding to `path', so that
it is at most `length' bytes in size.

@item 
@ref{1152,,waitid()}: Wait for the completion of one or more child processes.

@item 
@ref{f1e,,writev()}: Write the contents of `buffers' to a file descriptor,
where `buffers' is an arbitrary sequence of buffers.

@item 
@ref{14c0,,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{14c1,,times()} and @ref{14c2,,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{14c3,,lseek()}
function, such as @code{os.SEEK_HOLE} and @code{os.SEEK_DATA}.

@item 
New constants @ref{14c4,,RTLD_LAZY}, @ref{14c5,,RTLD_NOW},
@ref{14c6,,RTLD_GLOBAL}, @ref{14c7,,RTLD_LOCAL}, @ref{14c8,,RTLD_NODELETE},
@ref{14c9,,RTLD_NOLOAD}, and @ref{14ca,,RTLD_DEEPBIND} are available on
platforms that support them.   These are for use with the
@ref{14cb,,sys.setdlopenflags()} function, and supersede the similar constants
defined in @ref{2d,,ctypes} and @code{DLFCN}.  (Contributed by Victor Stinner
in bpo-13226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13226}.)

@item 
@ref{14a0,,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<10>,pickle<7>,os<14>,Improved Modules<11>
@anchor{whatsnew/3 3 pdb}@anchor{14cc}
@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.

(Contributed by Georg Brandl in bpo-14210@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14210})

@node pickle<7>,pydoc<6>,pdb<10>,Improved Modules<11>
@anchor{whatsnew/3 3 pickle}@anchor{14cd}
@subsubsection pickle


@ref{de2,,pickle.Pickler} objects now have an optional
@ref{14ce,,dispatch_table} attribute allowing per-pickler
reduction functions to be set.

(Contributed by Richard Oudkerk in bpo-14166@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14166}.)

@node pydoc<6>,re<11>,pickle<7>,Improved Modules<11>
@anchor{whatsnew/3 3 pydoc}@anchor{14cf}
@subsubsection pydoc


The Tk GUI and the @code{serve()} function have been removed from the
@ref{bd,,pydoc} module: @code{pydoc -g} and @code{serve()} have been deprecated
in Python 3.2.

@node re<11>,sched,pydoc<6>,Improved Modules<11>
@anchor{whatsnew/3 3 re}@anchor{14d0}
@subsubsection re


@ref{1df,,str} regular expressions now support @code{\u} and @code{\U} escapes.

(Contributed by Serhiy Storchaka in bpo-3665@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3665}.)

@node sched,select<2>,re<11>,Improved Modules<11>
@anchor{whatsnew/3 3 sched}@anchor{14d1}
@subsubsection sched



@itemize *

@item 
@ref{14d2,,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{14d3,,scheduler} in
non-blocking applications.  (Contributed by Giampaolo Rodolà in bpo-13449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13449}.)

@item 
@ref{14d3,,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{14d3,,scheduler} class
constructor are now optional and defaults to @ref{75e,,time.time()} and
@ref{a8c,,time.sleep()} respectively.  (Contributed by Chris Clark in
bpo-13245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13245}.)

@item 
@ref{14d4,,enter()} and @ref{14d5,,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{14d4,,enter()} and @ref{14d5,,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,Improved Modules<11>
@anchor{whatsnew/3 3 select}@anchor{14d6}
@subsubsection select


Solaris and derivative platforms have a new class @ref{133f,,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>,shutil<7>,select<2>,Improved Modules<11>
@anchor{whatsnew/3 3 shlex}@anchor{14d7}
@subsubsection shlex


The previously undocumented helper function @code{quote} from the
@code{pipes} modules has been moved to the @ref{cc,,shlex} module and
documented.  @ref{781,,quote()} properly escapes all characters in a string
that might be otherwise given special meaning by the shell.

@node shutil<7>,signal<4>,shlex<3>,Improved Modules<11>
@anchor{whatsnew/3 3 shutil}@anchor{14d8}
@subsubsection shutil



@itemize *

@item 
New functions:


@itemize *

@item 
@ref{14d9,,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{74b,,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{14af,,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{e1f,,copy2()} and @ref{14da,,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{e20,,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}.)  @code{move()} now also returns
the @code{dst} argument as its result.

@item 
@ref{335,,rmtree()} is now resistant to symlink attacks on platforms
which support the new @code{dir_fd} parameter in @ref{114b,,os.open()} and
@ref{14a1,,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>,shutil<7>,Improved Modules<11>
@anchor{whatsnew/3 3 signal}@anchor{14db}
@subsubsection signal



@itemize *

@item 
The @ref{ce,,signal} module has new functions:


@itemize *

@item 
@ref{14dc,,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{14dd,,pthread_kill()}: send a signal to a thread;

@item 
@ref{14de,,sigpending()}: examine pending functions;

@item 
@ref{14df,,sigwait()}: wait a signal;

@item 
@ref{1164,,sigwaitinfo()}: wait for a signal, returning detailed
information about it;

@item 
@ref{1163,,sigtimedwait()}: like @ref{1164,,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{14e0,,signal.signal()} and @ref{14e1,,signal.siginterrupt()} raise an OSError,
instead of a RuntimeError: OSError has an errno attribute.
@end itemize

@node smtpd<4>,smtplib<4>,signal<4>,Improved Modules<11>
@anchor{whatsnew/3 3 smtpd}@anchor{14e2}
@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<12>,smtpd<4>,Improved Modules<11>
@anchor{whatsnew/3 3 smtplib}@anchor{14e3}
@subsubsection smtplib


The @ref{cfa,,SMTP}, @ref{cfb,,SMTP_SSL}, and
@ref{cfc,,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{cfa,,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{cfb,,SMTP_SSL} constructor and the @ref{14e4,,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<12>,socketserver<3>,smtplib<4>,Improved Modules<11>
@anchor{whatsnew/3 3 socket}@anchor{14e5}
@subsubsection socket



@itemize *

@item 
The @ref{115a,,socket} class now exposes additional methods to process
ancillary data when supported by the underlying platform:


@itemize *

@item 
@ref{88c,,sendmsg()}

@item 
@ref{115f,,recvmsg()}

@item 
@ref{14e6,,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{115a,,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{115a,,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{115a,,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{14e7,,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<12>,socket<12>,Improved Modules<11>
@anchor{whatsnew/3 3 socketserver}@anchor{14e8}
@subsubsection socketserver


@ref{14e9,,BaseServer} now has an overridable method
@ref{14ea,,service_actions()} that is called by the
@ref{14eb,,serve_forever()} method in the service loop.
@ref{f37,,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<12>,ssl<13>,socketserver<3>,Improved Modules<11>
@anchor{whatsnew/3 3 sqlite3}@anchor{14ec}
@subsubsection sqlite3


New @ref{3df,,sqlite3.Connection} method
@ref{3e5,,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<13>,stat<2>,sqlite3<12>,Improved Modules<11>
@anchor{whatsnew/3 3 ssl}@anchor{14ed}
@subsubsection ssl



@itemize *

@item 
The @ref{d8,,ssl} module has two new random generation functions:


@itemize *

@item 
@ref{932,,RAND_bytes()}: generate cryptographically strong
pseudo-random bytes.

@item 
@code{RAND_pseudo_bytes()}: generate pseudo-random bytes.
@end itemize

(Contributed by Victor Stinner in bpo-12049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12049}.)

@item 
The @ref{d8,,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{797,,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{14ee,,load_dh_params()} and
@ref{25b,,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{14ef,,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{14f0,,compression()} method.  The new attribute
@ref{14f1,,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{337,,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{14f2,,library} and @ref{14f3,,reason} attributes.
(Contributed by Antoine Pitrou in bpo-14837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14837}.)

@item 
The @ref{c15,,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{14f4,,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<4>,ssl<13>,Improved Modules<11>
@anchor{whatsnew/3 3 stat}@anchor{14f5}
@subsubsection stat


The undocumented tarfile.filemode function has been moved to
@ref{14f6,,stat.filemode()}. It can be used to convert a file’s mode to a string of
the form “-rwxrwxrwx”.

(Contributed by Giampaolo Rodolà in bpo-14807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14807}.)

@node struct<4>,subprocess<7>,stat<2>,Improved Modules<11>
@anchor{whatsnew/3 3 struct}@anchor{14f7}
@subsubsection struct


The @ref{de,,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<7>,sys<14>,struct<4>,Improved Modules<11>
@anchor{whatsnew/3 3 subprocess}@anchor{14f8}
@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{14f9,,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<14>,tarfile<10>,subprocess<7>,Improved Modules<11>
@anchor{whatsnew/3 3 sys}@anchor{14fa}
@subsubsection sys


The @ref{e2,,sys} module has a new @ref{14fb,,thread_info} @ref{a3d,,named tuple} holding information about the thread implementation
(bpo-11223@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11223}).

@node tarfile<10>,tempfile<4>,sys<14>,Improved Modules<11>
@anchor{whatsnew/3 3 tarfile}@anchor{14fc}
@subsubsection tarfile


@ref{e7,,tarfile} now supports @code{lzma} encoding via the @ref{8d,,lzma} module.
(Contributed by Lars Gustäbel in bpo-5689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5689}.)

@node tempfile<4>,textwrap<3>,tarfile<10>,Improved Modules<11>
@anchor{whatsnew/3 3 tempfile}@anchor{14fd}
@subsubsection tempfile


@ref{a82,,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<3>,threading<11>,tempfile<4>,Improved Modules<11>
@anchor{whatsnew/3 3 textwrap}@anchor{14fe}
@subsubsection textwrap


The @ref{f5,,textwrap} module has a new @ref{77d,,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<11>,time<8>,textwrap<3>,Improved Modules<11>
@anchor{whatsnew/3 3 threading}@anchor{14ff}
@subsubsection threading


@ref{1500,,threading.Condition}, @ref{1501,,threading.Semaphore},
@ref{1502,,threading.BoundedSemaphore}, @ref{1503,,threading.Event}, and
@ref{1504,,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{420,,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{1505,,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<10>,threading<11>,Improved Modules<11>
@anchor{whatsnew/3 3 time}@anchor{1506}
@subsubsection time


The 
@geindex Python Enhancement Proposals; PEP 418
PEP 418@footnote{https://peps.python.org/pep-0418/} added new functions to the @ref{f7,,time} module:


@itemize *

@item 
@ref{1507,,get_clock_info()}: Get information on a clock.

@item 
@ref{75d,,monotonic()}: Monotonic clock (cannot go backward), not affected
by system clock updates.

@item 
@ref{e49,,perf_counter()}: Performance counter with the highest available
resolution to measure a short duration.

@item 
@ref{e4a,,process_time()}: Sum of the system and user CPU time of the
current process.
@end itemize

Other new functions:


@itemize *

@item 
@ref{1508,,clock_getres()}, @ref{1509,,clock_gettime()} and
@ref{150a,,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{a8c,,sleep()} now raises a
@ref{277,,ValueError} when passed a negative sleep value.  Previously this was an
error on posix, but produced an infinite sleep on Windows.

@node types<10>,unittest<12>,time<8>,Improved Modules<11>
@anchor{whatsnew/3 3 types}@anchor{150b}
@subsubsection types


Add a new @ref{189,,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{150c,,types.new_class()} and @ref{150d,,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<12>,urllib<6>,types<10>,Improved Modules<11>
@anchor{whatsnew/3 3 unittest}@anchor{150e}
@subsubsection unittest


@ref{93b,,assertRaises()}, @ref{93d,,assertRaisesRegex()}, @ref{2a0,,assertWarns()}, and
@ref{2a1,,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{150f,,unittest.TestCase.run()} now returns the @ref{1510,,TestResult}
object.

@node urllib<6>,webbrowser<5>,unittest<12>,Improved Modules<11>
@anchor{whatsnew/3 3 urllib}@anchor{1511}
@subsubsection urllib


The @ref{1381,,Request} class, now accepts a `method' argument
used by @ref{1512,,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<5>,xml etree ElementTree<2>,urllib<6>,Improved Modules<11>
@anchor{whatsnew/3 3 webbrowser}@anchor{1513}
@subsubsection webbrowser


The @ref{11e,,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<4>,webbrowser<5>,Improved Modules<11>
@anchor{whatsnew/3 3 xml-etree-elementtree}@anchor{1514}
@subsubsection xml.etree.ElementTree


The @ref{12e,,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{343,,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<4>,,xml etree ElementTree<2>,Improved Modules<11>
@anchor{whatsnew/3 3 zlib}@anchor{1515}
@subsubsection zlib


New attribute @ref{1516,,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{1517,,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<13>,Build and C API Changes<4>,Improved Modules<11>,What’s New In Python 3 3
@anchor{whatsnew/3 3 optimizations}@anchor{1518}
@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 
the UTF-8 encoder has been optimized

@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>,Deprecated<15>,Optimizations<13>,What’s New In Python 3 3
@anchor{whatsnew/3 3 build-and-c-api-changes}@anchor{13f1}
@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{1519,,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{c88,,PyUnicode_CopyCharacters()}

@item 
@ref{c8c,,PyUnicode_FindChar()}

@item 
@ref{c86,,PyUnicode_GetLength()}, @ref{c87,,PyUnicode_GET_LENGTH}

@item 
@ref{c7f,,PyUnicode_New()}

@item 
@ref{c89,,PyUnicode_Substring()}

@item 
@ref{151a,,PyUnicode_ReadChar()}, @ref{151b,,PyUnicode_WriteChar()}
@end itemize

@item 
Low-level API:


@itemize *

@item 
@ref{151c,,Py_UCS1}, @ref{151d,,Py_UCS2}, @ref{301,,Py_UCS4} types

@item 
@ref{151e,,PyASCIIObject} and @ref{151f,,PyCompactUnicodeObject} structures

@item 
@ref{647,,PyUnicode_READY}

@item 
@ref{1520,,PyUnicode_FromKindAndData()}

@item 
@ref{1521,,PyUnicode_AsUCS4()}, @ref{c8e,,PyUnicode_AsUCS4Copy()}

@item 
@ref{1522,,PyUnicode_DATA}, @ref{1523,,PyUnicode_1BYTE_DATA},
@ref{1524,,PyUnicode_2BYTE_DATA}, @ref{1525,,PyUnicode_4BYTE_DATA}

@item 
@ref{1526,,PyUnicode_KIND} with @code{PyUnicode_Kind} enum:
@code{PyUnicode_WCHAR_KIND}, @ref{1527,,PyUnicode_1BYTE_KIND},
@ref{1528,,PyUnicode_2BYTE_KIND}, @ref{1529,,PyUnicode_4BYTE_KIND}

@item 
@ref{152a,,PyUnicode_READ}, @ref{152b,,PyUnicode_READ_CHAR}, @ref{152c,,PyUnicode_WRITE}

@item 
@ref{152d,,PyUnicode_MAX_CHAR_VALUE}
@end itemize
@end itemize

@item 
@ref{3b1,,PyArg_ParseTuple} now accepts a @ref{1c6,,bytearray} for the @code{c}
format (bpo-12380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12380}).
@end itemize

@node Deprecated<15>,Porting to Python 3 3,Build and C API Changes<4>,What’s New In Python 3 3
@anchor{whatsnew/3 3 deprecated}@anchor{152e}
@subsection Deprecated


@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>. 
* Deprecated features:: 

@end menu

@node Unsupported Operating Systems<2>,Deprecated Python modules functions and methods<4>,,Deprecated<15>
@anchor{whatsnew/3 3 unsupported-operating-systems}@anchor{152f}
@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>,Deprecated<15>
@anchor{whatsnew/3 3 deprecated-python-modules-functions-and-methods}@anchor{1530}
@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{291,,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{1470,,ftplib.FTP.nlst()} and @ref{1471,,ftplib.FTP.dir()}: use
@ref{146f,,ftplib.FTP.mlsd()}

@item 
@code{platform.popen()}: use the @ref{df,,subprocess} module. Check especially
the @ref{1531,,Replacing Older Functions with the subprocess Module} 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{a5,,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{e49,,time.perf_counter()} or @ref{e4a,,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{1432,,abc.abstractproperty} has been deprecated, use @ref{6bb,,property}
with @ref{1433,,abc.abstractmethod()} instead.

@item 
@ref{1434,,abc.abstractclassmethod} has been deprecated, use
@ref{69a,,classmethod} with @ref{1433,,abc.abstractmethod()} instead.

@item 
@ref{1435,,abc.abstractstaticmethod} has been deprecated, use
@ref{666,,staticmethod} with @ref{1433,,abc.abstractmethod()} instead.
@end itemize

@item 
@ref{7a,,importlib} package:


@itemize *

@item 
@ref{1532,,importlib.abc.SourceLoader.path_mtime()} is now deprecated in favour of
@ref{1533,,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>,Deprecated features,Deprecated Python modules functions and methods<4>,Deprecated<15>
@anchor{whatsnew/3 3 deprecated-functions-and-types-of-the-c-api}@anchor{1534}
@subsubsection Deprecated functions and types of the C API


The @ref{b7a,,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{b7a,,Py_UNICODE} and
@ref{b7a,,Py_UNICODE}* types:


@itemize *

@item 
@code{PyUnicode_FromUnicode}: use @ref{1535,,PyUnicode_FromWideChar()} or
@ref{1520,,PyUnicode_FromKindAndData()}

@item 
@code{PyUnicode_AS_UNICODE}, @code{PyUnicode_AsUnicode()},
@code{PyUnicode_AsUnicodeAndSize()}: use @ref{c8f,,PyUnicode_AsWideCharString()}

@item 
@code{PyUnicode_AS_DATA}: use @ref{1522,,PyUnicode_DATA} with
@ref{152a,,PyUnicode_READ} and @ref{152c,,PyUnicode_WRITE}

@item 
@code{PyUnicode_GET_SIZE}, @code{PyUnicode_GetSize()}: use
@ref{c87,,PyUnicode_GET_LENGTH} or @ref{c86,,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{c8e,,PyUnicode_AsUCS4Copy()} or
@ref{c8f,,PyUnicode_AsWideCharString()}

@item 
@code{PyUnicode_GetMax()}
@end itemize

Functions and macros manipulating Py_UNICODE* strings:


@itemize *

@item 
@code{Py_UNICODE_strlen()}: use @ref{c86,,PyUnicode_GetLength()} or
@ref{c87,,PyUnicode_GET_LENGTH}

@item 
@code{Py_UNICODE_strcat()}: use @ref{c88,,PyUnicode_CopyCharacters()} or
@ref{81e,,PyUnicode_FromFormat()}

@item 
@code{Py_UNICODE_strcpy()}, @code{Py_UNICODE_strncpy()},
@code{Py_UNICODE_COPY()}: use @ref{c88,,PyUnicode_CopyCharacters()} or
@ref{c89,,PyUnicode_Substring()}

@item 
@code{Py_UNICODE_strcmp()}: use @ref{c8a,,PyUnicode_Compare()}

@item 
@code{Py_UNICODE_strncmp()}: use @ref{c8b,,PyUnicode_Tailmatch()}

@item 
@code{Py_UNICODE_strchr()}, @code{Py_UNICODE_strrchr()}: use
@ref{c8c,,PyUnicode_FindChar()}

@item 
@code{Py_UNICODE_FILL()}: use @ref{1536,,PyUnicode_Fill()}

@item 
@code{Py_UNICODE_MATCH}
@end itemize

Encoders:


@itemize *

@item 
@code{PyUnicode_Encode()}: use @code{PyUnicode_AsEncodedObject()}

@item 
@code{PyUnicode_EncodeUTF7()}

@item 
@code{PyUnicode_EncodeUTF8()}: use @ref{637,,PyUnicode_AsUTF8()} or
@ref{1537,,PyUnicode_AsUTF8String()}

@item 
@code{PyUnicode_EncodeUTF32()}

@item 
@code{PyUnicode_EncodeUTF16()}

@item 
@code{PyUnicode_EncodeUnicodeEscape()} use
@ref{1538,,PyUnicode_AsUnicodeEscapeString()}

@item 
@code{PyUnicode_EncodeRawUnicodeEscape()} use
@ref{1539,,PyUnicode_AsRawUnicodeEscapeString()}

@item 
@code{PyUnicode_EncodeLatin1()}: use @ref{153a,,PyUnicode_AsLatin1String()}

@item 
@code{PyUnicode_EncodeASCII()}: use @ref{153b,,PyUnicode_AsASCIIString()}

@item 
@code{PyUnicode_EncodeCharmap()}

@item 
@code{PyUnicode_TranslateCharmap()}

@item 
@code{PyUnicode_EncodeMBCS()}: use @ref{153c,,PyUnicode_AsMBCSString()} or
@ref{153d,,PyUnicode_EncodeCodePage()} (with @code{CP_ACP} code_page)

@item 
@code{PyUnicode_EncodeDecimal()},
@code{PyUnicode_TransformDecimalToASCII()}
@end itemize

@node Deprecated features,,Deprecated functions and types of the C API<3>,Deprecated<15>
@anchor{whatsnew/3 3 deprecated-features}@anchor{153e}
@subsubsection Deprecated features


The @ref{8,,array} module’s @code{'u'} format code is now deprecated and will be
removed in Python 4 together with the rest of the (@ref{b7a,,Py_UNICODE}) API.

@node Porting to Python 3 3,,Deprecated<15>,What’s New In Python 3 3
@anchor{whatsnew/3 3 porting-to-python-3-3}@anchor{153f}
@subsection Porting to Python 3.3


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

@menu
* Porting Python code:: 
* Porting C code:: 
* Building C extensions:: 
* Command Line Switch Changes:: 

@end menu

@node Porting Python code,Porting C code,,Porting to Python 3 3
@anchor{whatsnew/3 3 porting-python-code}@anchor{1416}@anchor{whatsnew/3 3 portingpythoncode}@anchor{1540}
@subsubsection Porting Python code



@itemize *

@item 
Hash randomization is enabled by default. Set the 
@geindex PYTHONHASHSEED
@geindex μεταβλητή περιβάλλοντος; PYTHONHASHSEED
@ref{1425,,PYTHONHASHSEED}
environment variable to @code{0} to disable hash randomization. See also the
@ref{ec1,,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{f7,,time} and @ref{33,,datetime}:
@ref{c57,,OverflowError} is now raised instead of @ref{277,,ValueError} if a
timestamp is out of range. @ref{53c,,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{fcf,,importlib.invalidate_caches()} to clear
out the cache for the finders to notice the new file.

@item 
@ref{1bd,,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{ca6,,__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{927,,importlib.import_module()} rather than call @code{__import__()} directly.

@item 
@ref{ca6,,__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{10e3,,sys.meta_path} and @ref{13cd,,sys.path_hooks} now have finders on
them by default, you will most likely want to use @ref{1541,,list.insert()} instead
of @ref{aba,,list.append()} to add to those lists.

@item 
Because @code{None} is now inserted into @ref{9db,,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
@code{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{1419,,path entry finders}.

@item 
@ref{ae,,pkgutil} has been converted to use @ref{7a,,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{1542,,pkgutil.iter_importers()} and @ref{fbe,,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{1465,,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{1543,,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{1544,,poplib.POP3.quit()} may now raise protocol errors like all other
@code{poplib} methods.  Code that assumes @code{quit} does not raise
@ref{1545,,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{1546,,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{39,,decimal} module.  It was previously replaced by the public attribute
@ref{1547,,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{d2,,smtplib}, since its functionality has long been provided directly
by @ref{1548,,socket.socket.makefile()}.

@item 
Passing a negative value to @ref{a8c,,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{2fc,,sys.version_info}
to make the decision.

@item 
Code that used to work around the fact that the @ref{f6,,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,Porting Python code,Porting to Python 3 3
@anchor{whatsnew/3 3 porting-c-code}@anchor{13f2}
@subsubsection Porting C code



@itemize *

@item 
In the course of changes to the buffer API the undocumented
@code{smalltable} member of the
@ref{b3a,,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{13e6,,PEP 393}, the @ref{b7a,,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{1549,,Unicode API}.

However, if you only have been using high-level functions such as
@ref{154a,,PyUnicode_Concat()}, @ref{154b,,PyUnicode_Join()} or
@ref{81e,,PyUnicode_FromFormat()}, your code will automatically take
advantage of the new unicode representations.

@item 
@ref{154c,,PyImport_GetMagicNumber()} now returns @code{-1} upon failure.

@item 
As a negative value for the `level' argument to @ref{ca6,,__import__()} is no
longer valid, the same now holds for @ref{154d,,PyImport_ImportModuleLevel()}.
This also means that the value of `level' used by
@ref{154e,,PyImport_ImportModuleEx()} is now @code{0} instead of @code{-1}.
@end itemize

@node Building C extensions,Command Line Switch Changes,Porting C code,Porting to Python 3 3
@anchor{whatsnew/3 3 building-c-extensions}@anchor{154f}
@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,Porting to Python 3 3
@anchor{whatsnew/3 3 command-line-switch-changes}@anchor{1550}
@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{1551,,-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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 2,What’s New In Python 3 1,What’s New In Python 3 3,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 2 doc}@anchor{1552}@anchor{whatsnew/3 2 translation-repo}@anchor{1553}@anchor{whatsnew/3 2 what-s-new-in-python-3-2}@anchor{1554}
@section What’s New In Python 3.2


@*Author: 
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 Δείτε επίσης


@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. 
* Other Language Changes: Other Language Changes<12>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules. 
* Multi-threading:: 
* Optimizations: Optimizations<14>. 
* Unicode:: 
* Codecs:: 
* Documentation:: 
* IDLE:: 
* Code Repository:: 
* Build and C API Changes: Build and C API Changes<5>. 
* Porting to Python 3.2: Porting to Python 3 2. 

@end menu

@node PEP 384 Defining a Stable ABI,PEP 389 Argparse Command Line Parsing Module,,What’s New In Python 3 2
@anchor{whatsnew/3 2 pep-384-defining-a-stable-abi}@anchor{1555}
@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 Δείτε επίσης



@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,What’s New In Python 3 2
@anchor{whatsnew/3 2 pep-389-argparse-command-line-parsing-module}@anchor{1556}
@subsection PEP 389: Argparse Command Line Parsing Module


A new module for command line parsing, @ref{7,,argparse}, was introduced to
overcome the limitations of @ref{a4,,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{7,,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{7,,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 Δείτε επίσης



@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{1557,,Migrating optparse code to argparse} for details on the differences from @ref{a4,,optparse}.


@node PEP 391 Dictionary Based Configuration for Logging,PEP 3148 The concurrent futures module,PEP 389 Argparse Command Line Parsing Module,What’s New In Python 3 2
@anchor{whatsnew/3 2 pep-391-dictionary-based-configuration-for-logging}@anchor{1558}
@subsection PEP 391:  Dictionary Based Configuration for Logging


The @ref{8a,,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{26,,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{1559,,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 Δείτε επίσης



@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,What’s New In Python 3 2
@anchor{whatsnew/3 2 pep-3148-the-concurrent-futures-module}@anchor{155a}
@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{24,,concurrent.futures} was inspired by the
`java.util.concurrent' package.  In that model, a running call and its result
are represented by a @ref{155b,,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{e44,,submit()} for scheduling a callable and
returning a @ref{155b,,Future} object;
@ref{473,,map()} for scheduling many asynchronous calls
at a time, and @ref{cbe,,shutdown()} for freeing
resources.  The class is a @ref{478,,context manager} and can be used in a
@ref{20a,,with} statement to assure that resources are automatically released
when currently pending futures are done executing.

A simple of example of @ref{b27,,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 Δείτε επίσης



@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{155c,,Code for Threaded Parallel URL reads}, an
example using threads to fetch multiple web pages in parallel.

@ref{155d,,Code for computing prime numbers in parallel}, an example demonstrating
@ref{206,,ProcessPoolExecutor}.


@node PEP 3147 PYC Repository Directories,PEP 3149 ABI Version Tagged so Files,PEP 3148 The concurrent futures module,What’s New In Python 3 2
@anchor{whatsnew/3 2 pep-3147-pyc-repository-directories}@anchor{155e}
@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 @code{__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{bb,,py_compile} and @ref{21,,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{7b,,importlib.abc} module has been updated with new @ref{155f,,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 Δείτε επίσης



@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,What’s New In Python 3 2
@anchor{whatsnew/3 2 pep-3149-abi-version-tagged-so-files}@anchor{1560}
@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{e4,,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 Δείτε επίσης



@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,Other Language Changes<12>,PEP 3149 ABI Version Tagged so Files,What’s New In Python 3 2
@anchor{whatsnew/3 2 pep-3333-python-web-server-gateway-interface-v1-0-1}@anchor{1561}
@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{1df,,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{1df,,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{121,,wsgiref} module has a new function,
@ref{1562,,wsgiref.handlers.read_environ()} for transcoding CGI variables from
@ref{4e5,,os.environ} into native strings and returning a new dictionary.


@subsubheading Δείτε επίσης



@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 Other Language Changes<12>,New Improved and Deprecated Modules,PEP 3333 Python Web Server Gateway Interface v1 0 1,What’s New In Python 3 2
@anchor{whatsnew/3 2 other-language-changes}@anchor{1563}
@subsection Other Language Changes


Some smaller changes made to the core Python language are:


@itemize *

@item 
String formatting for @ref{439,,format()} and @ref{a12,,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{1190,,str.format_map()} method that extends the
capabilities of the existing @ref{a12,,str.format()} method by accepting arbitrary
@ref{1564,,mapping} objects.  This new method makes it possible to use string
formatting with any of Python’s many dictionary-like objects such as
@ref{1565,,defaultdict}, @ref{1344,,Shelf},
@ref{6e4,,ConfigParser}, or @ref{34,,dbm}.  It is also useful with
custom @ref{188,,dict} subclasses that normalize keys before look-up or that
supply a @ref{1566,,__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{a7c,,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

(Contributed by Marcin Wojdyr in bpo-1772833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1772833}).

@item 
The @ref{8e2,,hasattr()} function works by calling @ref{f8f,,getattr()} and detecting
whether an exception is raised.  This technique allows it to detect methods
created dynamically by @ref{8e3,,__getattr__()} or @ref{f90,,__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{1a9,,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{1df,,str()} of a float or complex number is now the same as its
@ref{45b,,repr()}. Previously, the @code{str()} form was shorter but that just
caused confusion and is no longer needed now that the shortest possible
@code{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{1d2,,memoryview} objects now have a @ref{1567,,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

(Added by 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{447,,except} clause
is cleared, so this code which used to work with Python 2.6, raised a
@ref{17e,,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{1568,,Struct sequence types} are now subclasses of tuple.
This means that C structures like those returned by @ref{4f5,,os.stat()},
@ref{1569,,time.gmtime()}, and @ref{2fc,,sys.version_info} now work like a
@ref{a3d,,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 μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,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{74f,,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{11b,,warnings}
module, or on the command line.

A @ref{74f,,ResourceWarning} is issued at interpreter shutdown if the
@ref{156a,,gc.garbage} list isn’t empty, and if @ref{156b,,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{74f,,ResourceWarning} is also issued when a @ref{156c,,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{d0f,,range} objects now support `index' and `count' methods. This is part
of an effort to make more objects fully implement the
@ref{156d,,collections.Sequence} @ref{155f,,abstract base class}.  As a result, the
language will have a more uniform API.  In addition, @code{range} objects
now support slicing and negative indices, even with values larger than
@ref{156e,,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{156f,,callable()} builtin function from Py2.x was resurrected.  It provides
a concise, readable alternative to using an @ref{155f,,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,Multi-threading,Other Language Changes<12>,What’s New In Python 3 2
@anchor{whatsnew/3 2 new-improved-and-deprecated-modules}@anchor{1570}
@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{3e,,email} package, @ref{8e,,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{478,,context manager} to support
convenient and reliable resource clean-up using a @ref{20a,,with} statement.

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

@end menu

@node email<8>,elementtree,,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 email}@anchor{1571}
@subsubsection email


The usability of the @ref{3e,,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{1c7,,bytes} rather than @ref{1df,,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{1572,,message_from_bytes()} and
@ref{1573,,message_from_binary_file()}, and new classes
@ref{1574,,BytesFeedParser} and @ref{1575,,BytesParser}
allow binary message data to be parsed into model objects.

@item 
Given bytes input to the model, @ref{1576,,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{1577,,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{1578,,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{d2,,smtplib} @ref{cfa,,SMTP} class now accepts a byte string
for the `msg' argument to the @ref{120a,,sendmail()} method,
and a new method, @ref{120b,,send_message()} accepts a
@ref{780,,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<10>,email<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 elementtree}@anchor{1579}
@subsubsection elementtree


The @ref{12e,,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{157a,,xml.etree.ElementTree.fromstringlist()} which builds an XML document
from a sequence of fragments

@item 
@ref{157b,,xml.etree.ElementTree.register_namespace()} for registering a global
namespace prefix

@item 
@ref{139f,,xml.etree.ElementTree.tostringlist()} for string representation
including all sublists

@item 
@ref{157c,,xml.etree.ElementTree.Element.extend()} for appending a sequence of zero
or more elements

@item 
@ref{157d,,xml.etree.ElementTree.Element.iterfind()} searches an element and
subelements

@item 
@ref{157e,,xml.etree.ElementTree.Element.itertext()} creates a text iterator over
an element and its subelements

@item 
@ref{157f,,xml.etree.ElementTree.TreeBuilder.end()} closes the current element

@item 
@ref{e5d,,xml.etree.ElementTree.TreeBuilder.doctype()} handles a doctype
declaration
@end itemize

Two methods have been deprecated:


@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.

(Contributed by Florent Xicluna and Fredrik Lundh, bpo-6472@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6472}.)

@node functools<10>,itertools<8>,elementtree,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 functools}@anchor{1580}
@subsubsection functools



@itemize *

@item 
The @ref{62,,functools} module includes a new decorator for caching function
calls.  @ref{db3,,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{1307,,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{1581,,__annotations__} if
defined.  And now it also gracefully skips over missing attributes such as
@ref{1582,,__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{12ed,,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{12ed,,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{1583,,functools.cmp_to_key()}
function converts an old-style comparison function to
modern @ref{11ba,,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<8>,collections<9>,functools<10>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 itertools}@anchor{1584}
@subsubsection itertools



@itemize *

@item 
The @ref{84,,itertools} module has a new @ref{dbf,,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{dbf,,accumulate()}, see the @ref{1585,,examples for the random module}.

(Contributed by Raymond Hettinger and incorporating design suggestions
from Mark Dickinson.)
@end itemize

@node collections<9>,threading<12>,itertools<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 collections}@anchor{1586}
@subsubsection collections



@itemize *

@item 
The @ref{204,,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{1587,,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{9d5,,collections.OrderedDict} class has a new method
@ref{1588,,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{9d6,,collections.deque} class grew two new methods
@ref{1589,,count()} and @ref{158a,,reverse()} that
make them more substitutable for @ref{4d9,,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<12>,datetime and time,collections<9>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 threading}@anchor{158b}
@subsubsection threading


The @ref{f6,,threading} module has a new @ref{158c,,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{158c,,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{158d,,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{158e,,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<12>,threading<12>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 datetime-and-time}@anchor{158f}
@subsubsection datetime and time



@itemize *

@item 
The @ref{33,,datetime} module has a new type @ref{146c,,timezone} that
implements the @ref{9d8,,tzinfo} interface by returning a fixed UTC
offset and timezone name. This makes it easier to create timezone-aware
datetime objects:

@example
>>> import datetime as dt

>>> dt.datetime.now(dt.timezone.utc)
datetime.datetime(2010, 12, 8, 21, 4, 2, 923754, tzinfo=datetime.timezone.utc)

>>> dt.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{d94,,timedelta} objects can now be multiplied by
@ref{327,,float} and divided by @code{float} and @ref{326,,int} objects.
And @code{timedelta} objects can now divide one another.

@item 
The @ref{1052,,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{2c9,,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{1590,,time.asctime()} function will
accept any year that fits in a C int, while the @ref{1591,,time.mktime()} and
@ref{1592,,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<12>,abc<3>,datetime and time,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 math}@anchor{1593}
@subsubsection math


The @ref{91,,math} module has been updated with six new functions inspired by the
C99 standard.

The @ref{1594,,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{1595,,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{f98,,erf()} function computes a probability integral or Gaussian error function@footnote{https://en.wikipedia.org/wiki/Error_function}.  The
complementary error function, @ref{f99,,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{1596,,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{1597,,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<9>,math<12>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 abc}@anchor{1598}
@subsubsection abc


The @ref{4,,abc} module now supports @ref{1434,,abstractclassmethod()} and
@ref{1435,,abstractstaticmethod()}.

These tools make it possible to define an @ref{155f,,abstract base class} that
requires a particular @ref{69a,,classmethod()} or @ref{666,,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<9>,reprlib,abc<3>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 io}@anchor{1599}
@subsubsection io


The @ref{1255,,io.BytesIO} has a new method, @ref{159a,,getbuffer()}, which
provides functionality similar to @ref{1d2,,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

(Contributed by Antoine Pitrou in bpo-5506@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5506}.)

@node reprlib,logging<8>,io<9>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 reprlib}@anchor{159b}
@subsubsection reprlib


When writing a @ref{1bc,,__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{4d9,,list} and @ref{42b,,set} handle
self-reference by displaying «…» in the recursive part of the representation
string.

To help write such @ref{1bc,,__repr__()} methods, the @ref{c3,,reprlib} module has a new
decorator, @ref{159c,,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

(Contributed by Raymond Hettinger in bpo-9826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9826} and bpo-9840@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9840}.)

@node logging<8>,csv<5>,reprlib,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 logging}@anchor{159d}
@subsubsection logging


In addition to dictionary-based configuration described above, the
@ref{8a,,logging} package has many other improvements.

The logging documentation has been augmented by a @ref{159e,,basic tutorial}, an @ref{159f,,advanced tutorial}, and a @ref{15a0,,cookbook} of
logging recipes.  These documents are the fastest way to learn about logging.

The @ref{dc2,,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{a12,,str.format()} style, or
can be set to «$» for the shell-style formatting provided by
@ref{a77,,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{15a1,,StreamHandler} directed to
@ref{d05,,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{15a2,,logging.raiseExceptions}.  The new default handler is stored in
@ref{15a3,,logging.lastResort}.

The use of filters has been simplified.  Instead of creating a
@ref{15a4,,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<5>,contextlib<9>,logging<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 csv}@anchor{15a5}
@subsubsection csv


The @ref{2c,,csv} module now supports a new dialect, @ref{15a6,,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{15a7,,csv.DictWriter} has a new method,
@ref{15a8,,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<9>,decimal and fractions,csv<5>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 contextlib}@anchor{15a9}
@subsubsection contextlib


There is a new and slightly mind-blowing tool
@ref{20c,,ContextDecorator} that is helpful for creating a
@ref{478,,context manager} that does double duty as a function decorator.

As a convenience, this new functionality is used by
@ref{20e,,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{20a,,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{20e,,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{20a,,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.

(Contributed by Michael Foord in bpo-9110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9110}.)

@node decimal and fractions,ftp,contextlib<9>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 decimal-and-fractions}@anchor{15aa}
@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{13a8,,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{1c2,,decimal.Decimal} constructor now accepts @ref{327,,float} objects
directly so there in no longer a need to use the @ref{15ab,,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{1c2,,Decimal} objects can be directly compared with @ref{327,,float}
and @ref{1c3,,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{1c3,,fractions.Fraction} so that the
@ref{15ac,,from_float()} and @ref{15ad,,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{39,,decimal} module is that the
@ref{1547,,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{15ae}
@subsubsection ftp


The @ref{cca,,ftplib.FTP} class now supports the context management protocol to
unconditionally consume @ref{13fe,,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{23c,,mmap.mmap} and @ref{bd9,,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{ccb,,FTP_TLS} class now accepts a `context' parameter, which is a
@ref{336,,ssl.SSLContext} object allowing bundling SSL configuration options,
certificates and private keys into a single (potentially long-lived) structure.

(Contributed by 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{15af}
@subsubsection popen


The @ref{585,,os.popen()} and @ref{6bf,,subprocess.Popen()} functions now support
@ref{20a,,with} statements for auto-closing of the file descriptors.

(Contributed by Antoine Pitrou and Brian Curtin in bpo-7461@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7461} and
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{15b0}
@subsubsection select


The @ref{c9,,select} module now exposes a new, constant attribute,
@ref{15b1,,PIPE_BUF}, which gives the minimum number of bytes which are
guaranteed not to block when @ref{1159,,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<11>,select<3>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 gzip-and-zipfile}@anchor{15b2}
@subsubsection gzip and zipfile


@ref{849,,gzip.GzipFile} now implements the @ref{a83,,io.BufferedIOBase}
@ref{155f,,abstract base class} (except for @code{truncate()}).  It also has a
@ref{15b3,,peek()} method and supports unseekable as well as
zero-padded file objects.

The @ref{6a,,gzip} module also gains the @ref{a2d,,compress()} and
@ref{15b4,,decompress()} functions for easier in-memory compression and
decompression.  Keep in mind that text needs to be encoded as @ref{1c7,,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{84a,,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{15b5,,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<11>,hashlib<8>,gzip and zipfile,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 tarfile}@anchor{15b6}
@subsubsection tarfile


The @ref{15b7,,TarFile} class can now be used as a context manager.  In
addition, its @ref{fb3,,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{10cc,,keyword argument}.  The user-supplied filter function accepts a
@ref{15b8,,TarInfo} object and returns an updated
@code{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<8>,ast<9>,tarfile<11>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 hashlib}@anchor{15b9}
@subsubsection hashlib


The @ref{6b,,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<9>,os<15>,hashlib<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 ast}@anchor{15ba}
@subsubsection ast


The @ref{9,,ast} module has a wonderful a general-purpose tool for safely
evaluating expression strings using the Python literal
syntax.  The @ref{fd7,,ast.literal_eval()} function serves as a secure alternative to
the builtin @ref{184,,eval()} function which is easily abused.  Python 3.2 adds
@ref{1c7,,bytes} and @ref{42b,,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<15>,shutil<8>,ast<9>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 os}@anchor{15bb}
@subsubsection os


Different operating systems use various encodings for filenames and environment
variables.  The @ref{a5,,os} module provides two new functions,
@ref{1013,,fsencode()} and @ref{1012,,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{15bc,,os.supports_bytes_environ} constant will be
true.

For direct access to encoded environment variables (if available),
use the new @ref{15bd,,os.getenvb()} function or use @ref{4e6,,os.environb}
which is a bytes version of @ref{4e5,,os.environ}.

(Contributed by Victor Stinner.)

@node shutil<8>,sqlite3<13>,os<15>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 shutil}@anchor{15be}
@subsubsection shutil


The @ref{ded,,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{e1f,,shutil.copy2()} is used by default.
@end itemize

(Contributed by Tarek Ziadé.)

In addition, the @ref{cd,,shutil} module now supports @ref{15bf,,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{8c3,,make_archive()} and
@ref{882,,unpack_archive()}.  By default, both operate on the current
directory (which can be set by @ref{a02,,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<13>,html<3>,shutil<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 sqlite3}@anchor{15c0}
@subsubsection sqlite3


The @ref{d7,,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{c17,,sqlite3.Connection.enable_load_extension()} and
@ref{8c8,,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<13>,sqlite3<13>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 html}@anchor{15c1}
@subsubsection html


A new @ref{6e,,html} module was introduced with only a single function,
@ref{13b7,,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<13>,ssl<14>,html<3>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 socket}@anchor{15c2}
@subsubsection socket


The @ref{d4,,socket} module has two new improvements.


@itemize *

@item 
Socket objects now have a @ref{15c3,,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{a62,,socket.create_connection()} now supports the context management protocol
to unconditionally consume @ref{13fe,,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<14>,nntp,socket<13>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 ssl}@anchor{15c4}
@subsubsection ssl


The @ref{d8,,ssl} module added a number of features to satisfy common requirements
for secure (encrypted, authenticated) internet connections:


@itemize *

@item 
A new class, @ref{336,,SSLContext}, serves as a container for persistent
SSL data, such as protocol settings, certificates, private keys, and various
other options. It includes a @ref{933,,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{933,,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{d8,,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{933,,ssl.SSLContext.wrap_socket()}.

@item 
Various options have been added to the @ref{d8,,ssl} module, such as
@ref{c12,,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{15c5,,ssl.OPENSSL_VERSION} (a string),
@ref{15c6,,ssl.OPENSSL_VERSION_INFO} (a 5-tuple), and
@ref{15c7,,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<14>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 nntp}@anchor{15c8}
@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.

(Contributed by Antoine Pitrou in bpo-9360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9360} and Andrew Vant in bpo-1926@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1926}.)

@node certificates,imaplib<5>,nntp,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 certificates}@anchor{15c9}
@subsubsection certificates


@ref{224,,http.client.HTTPSConnection}, @ref{15ca,,urllib.request.HTTPSHandler}
and @ref{57f,,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.

(Added by Antoine Pitrou, bpo-9003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9003}.)

@node imaplib<5>,http client<5>,certificates,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 imaplib}@anchor{15cb}
@subsubsection imaplib


Support for explicit TLS on standard IMAP4 connections has been added through
the new @ref{15cc,,imaplib.IMAP4.starttls} method.

(Contributed by Lorenzo M. Catucci and Antoine Pitrou, bpo-4471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4471}.)

@node http client<5>,unittest<13>,imaplib<5>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 http-client}@anchor{15cd}
@subsubsection http.client


There were a number of small API improvements in the @ref{72,,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{223,,HTTPConnection} and
@ref{224,,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{224,,HTTPSConnection}.

The @ref{106a,,request()} method on connection objects
allowed an optional `body' argument so that a @ref{156c,,file object} could be used
to supply the content of the request.  Conveniently, the `body' argument now
also accepts an @ref{15ce,,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{15cf,,set_tunnel()} method that sets the host and
port for HTTP Connect tunneling.

To match the behavior of @ref{75,,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<13>,random<5>,http client<5>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 unittest}@anchor{15d0}
@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{52f,,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{10f,,unittest} module has two new methods,
@ref{2a0,,assertWarns()} and
@ref{2a1,,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

(Contributed by Antoine Pitrou, bpo-9754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9754}.)

Another new method, @ref{15d1,,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{15d2,,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{93c,,assertRegex()} is the new name for
@code{assertRegexpMatches()} which was misnamed because the
test uses @ref{15d3,,re.search()}, not @ref{24c,,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{c1,,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{935,,assertTrue()}

@item

@code{assertEquals()}

@tab

@ref{937,,assertEqual()}

@item

@code{assertNotEquals()}

@tab

@ref{938,,assertNotEqual()}

@item

@code{assertAlmostEquals()}

@tab

@ref{939,,assertAlmostEqual()}

@item

@code{assertNotAlmostEquals()}

@tab

@ref{93a,,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.

(Contributed by 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<13>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 random}@anchor{15d4}
@subsubsection random


The integer methods in the @ref{c0,,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{c41,,randrange()},
@ref{15d5,,randint()}, @ref{15d6,,choice()}, @ref{b2c,,shuffle()} and
@ref{b2b,,sample()}.

(Contributed by 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{15d7}
@subsubsection poplib


@ref{cf1,,POP3_SSL} class now accepts a `context' parameter, which is a
@ref{336,,ssl.SSLContext} object allowing bundling SSL configuration options,
certificates and private keys into a single (potentially long-lived)
structure.

(Contributed by 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{15d8}
@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.

(Contributed by Giampaolo Rodolà; bpo-6706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6706}.)

@node tempfile<5>,inspect<12>,asyncore<2>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 tempfile}@anchor{15d9}
@subsubsection tempfile


The @ref{e9,,tempfile} module has a new context manager,
@ref{15da,,TemporaryDirectory} which provides easy deterministic
cleanup of temporary directories:

@example
with tempfile.TemporaryDirectory() as tmpdirname:
    print('created temporary dir:', tmpdirname)
@end example

(Contributed by Neil Schemenauer and Nick Coghlan; bpo-5178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5178}.)

@node inspect<12>,pydoc<7>,tempfile<5>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 inspect}@anchor{15db}
@subsubsection inspect



@itemize *

@item 
The @ref{81,,inspect} module has a new function
@ref{15dc,,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

(Contributed by Rodolpho Eckhardt and 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{81,,inspect} module has a new function, @ref{8a5,,getattr_static()}.
Unlike @ref{8e2,,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<7>,dis<6>,inspect<12>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 pydoc}@anchor{15dd}
@subsubsection pydoc


The @ref{bd,,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

(Contributed by Ron Adam; bpo-2001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2001}.)

@node dis<6>,dbm<8>,pydoc<7>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 dis}@anchor{15de}
@subsubsection dis


The @ref{3b,,dis} module gained two new functions for inspecting code,
@ref{15df,,code_info()} and @ref{12d9,,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{496,,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.

(Contributed by Nick Coghlan in bpo-9147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9147}.)

@node dbm<8>,ctypes<5>,dis<6>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 dbm}@anchor{15e0}
@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<5>,site<4>,dbm<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 ctypes}@anchor{15e1}
@subsubsection ctypes


A new type, @ref{15e2,,ctypes.c_ssize_t} represents the C @code{ssize_t} datatype.

@node site<4>,sysconfig<6>,ctypes<5>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 site}@anchor{15e3}
@subsubsection site


The @ref{cf,,site} module has three new functions useful for reporting on the
details of a given Python installation.


@itemize *

@item 
@ref{15e4,,getsitepackages()} lists all global site-packages directories.

@item 
@ref{15e5,,getuserbase()} reports on the user’s base directory where data can
be stored.

@item 
@ref{15e6,,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

(Contributed by Tarek Ziadé in bpo-6693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6693}.)

@node sysconfig<6>,pdb<11>,site<4>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 sysconfig}@anchor{15e7}
@subsubsection sysconfig


The new @ref{e4,,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{15e8,,get_platform()} returning values like `linux-i586' or
`macosx-10.6-ppc'.

@item 
@ref{15e9,,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{156,,get_paths()} makes a dictionary containing installation paths
for the current installation scheme.

@item 
@ref{51e,,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<11>,configparser<6>,sysconfig<6>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 pdb}@anchor{15ea}
@subsubsection pdb


The @ref{aa,,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{4fb,,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<6>,urllib parse<7>,pdb<11>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 configparser}@anchor{15eb}
@subsubsection configparser


The @ref{26,,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{6e4,,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{b0b,,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<7>,mailbox,configparser<6>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 urllib-parse}@anchor{15ec}
@subsubsection urllib.parse


A number of usability improvements were made for the @ref{113,,urllib.parse} module.

The @ref{2a4,,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{2a5,,urldefrag()} function now returns a @ref{a3d,,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{1246,,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{15ed,,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{15ee,,Parsing ASCII Encoded Bytes}, all the @ref{113,,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<7>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 mailbox}@anchor{15ef}
@subsubsection mailbox


Thanks to a concerted effort by R. David Murray, the @ref{8e,,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{1c7,,bytes} because various parts of a message may have different encodings.

The solution harnessed the @ref{3e,,email} package’s binary support for parsing
arbitrary email messages.  In addition, the solution required a number of API
changes.

As expected, the @ref{15f0,,add()} method for
@ref{15f1,,mailbox.Mailbox} objects now accepts binary input.

@ref{12d4,,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{15f2,,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{15f3,,get_bytes()}
method that returns a @ref{1c7,,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{15f4,,get_string()} method, but that approach
is not very useful.  Instead, it is best to extract messages from
a @ref{15f5,,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{15f6}
@subsubsection turtledemo


The demonstration code for the @ref{10a,,turtle} module was moved from the `Demo'
directory to main library.  It includes over a dozen sample scripts with
lively displays.  Being on @ref{194,,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 Multi-threading,Optimizations<14>,New Improved and Deprecated Modules,What’s New In Python 3 2
@anchor{whatsnew/3 2 multi-threading}@anchor{15f7}
@subsection Multi-threading



@itemize *

@item 
The mechanism for serializing execution of concurrently running Python threads
(generally known as the @ref{411,,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{d16,,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).

(Contributed by Antoine Pitrou.)

@item 
Regular and recursive locks now accept an optional `timeout' argument to their
@ref{a87,,acquire()} method.  (Contributed by Antoine Pitrou;
bpo-7316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7316}.)

@item 
Similarly, @ref{15f8,,threading.Semaphore.acquire()} also gained a `timeout'
argument.  (Contributed by 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}+@code{C} in most shells).
(Contributed by Reid Kleckner; bpo-8844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8844}.)
@end itemize

@node Optimizations<14>,Unicode,Multi-threading,What’s New In Python 3 2
@anchor{whatsnew/3 2 optimizations}@anchor{15f9}
@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{42b,,set} as a @ref{9d4,,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{ab,,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{f8d,,list.sort()} and @ref{f8c,,sorted()} now runs faster and uses less memory
when called with a @ref{11ba,,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{2df,,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.

(Contributed by 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{125b,,split()},
@ref{15fa,,rsplit()}, @ref{15fb,,splitlines()} and @ref{6c0,,replace()} methods on
@ref{1c7,,bytes}, @ref{1c6,,bytearray} and @ref{1df,,str} objects. Likewise, the
algorithm is also used by @ref{125a,,rfind()}, @ref{15fc,,rindex()}, @code{rsplit()} and
@ref{15fd,,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{226,,BaseHTTPRequestHandler}
has more efficient buffering (bpo-3709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3709} by Andrew Schaaf).  The
@ref{11e6,,operator.attrgetter()} function has been sped-up (bpo-10160@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10160} by
Christos Georgiou).  And @ref{6e4,,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<14>,What’s New In Python 3 2
@anchor{whatsnew/3 2 unicode}@anchor{15fe}
@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,What’s New In Python 3 2
@anchor{whatsnew/3 2 codecs}@anchor{15ff}
@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{dd7,,UnicodeDecodeError} when it encounters an
undecodable byte sequence and an @ref{a67,,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{e7,,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,What’s New In Python 3 2
@anchor{whatsnew/3 2 documentation}@anchor{1600}
@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{1601,,Ενσωματωμένες (Built-in) Συναρτήσεις}.  In the case of @ref{84,,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{62,,functools} module
documentation has a quick link at the top labeled:

@quotation

`Source code' Lib/functools.py@footnote{https://github.com/python/cpython/tree/main/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{c1,,re}
module has an extensive section, @ref{1602,,Regular expression examples}.  Likewise, the
@ref{84,,itertools} module continues to be updated with new
@ref{1603,,Itertools Recipes}.

@item 
The @ref{33,,datetime} module now has an auxiliary implementation in pure Python.
No functionality was changed.  This just provides an easier-to-read alternate
implementation.

(Contributed by Alexander Belopolsky in 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.

(Contributed by Georg Brandl in bpo-7962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7962}.)
@end itemize

@node IDLE,Code Repository,Documentation,What’s New In Python 3 2
@anchor{whatsnew/3 2 idle}@anchor{1604}
@subsection IDLE



@itemize *

@item 
The format menu now has an option to clean source files by stripping
trailing whitespace.

(Contributed by 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,What’s New In Python 3 2
@anchor{whatsnew/3 2 code-repository}@anchor{1605}
@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>,Porting to Python 3 2,Code Repository,What’s New In Python 3 2
@anchor{whatsnew/3 2 build-and-c-api-changes}@anchor{1606}
@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{1607,,unicodedata.numeric()} now returns the correct value
for large code points, and @ref{45b,,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}.

(Contributed by 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.

(Contributed by 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{1608,,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{42b,,set} and @ref{188,,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{1609,,sys.argv} without also modifying @ref{194,,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{160a,,PyLong_AsLongLongAndOverflow()} which
is analogous to @ref{160b,,PyLong_AsLongAndOverflow()}.  They both serve to
convert Python @ref{326,,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{160c,,PyUnicode_CompareWithASCIIString()} function now returns `not
equal' if the Python string is `NUL' terminated.

@item 
There is a new function @ref{160d,,PyErr_NewExceptionWithDoc()} that is
like @ref{160e,,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 Porting to Python 3 2,,Build and C API Changes<5>,What’s New In Python 3 2
@anchor{whatsnew/3 2 porting-to-python-3-2}@anchor{160f}
@subsection Porting to Python 3.2


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


@itemize *

@item 
The @ref{26,,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{1610,,get()} and
@ref{1611,,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{1611,,set()} and
@ref{1612,,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{1613,,DuplicateSectionError} or
@ref{1614,,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 
@ref{1c6,,bytearray} objects can no longer be used as filenames; instead,
they should be converted to @ref{1c7,,bytes}.

@item 
The @code{array.tostring()} and @code{array.fromstring()} have been renamed to
@ref{1615,,array.tobytes()} and
@ref{1616,,array.frombytes()} for clarity.  The old names
have been deprecated. (See bpo-8990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8990}.)

@item 
@code{PyArg_Parse*()} functions:


@itemize *

@item 
«t#» format has been removed: use «s#» or «s*» instead

@item 
«w» and «w#» formats has been removed: use «w*» instead
@end itemize

@item 
The @code{PyCObject} type, deprecated in 3.1, has been removed.  To wrap
opaque C pointers in Python objects, the @ref{1617,,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{1618,,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{1619,,bytes.maketrans()} and
@ref{161a,,bytearray.maketrans()}.  This change solves the confusion around which
types were supported by the @ref{db,,string} module.  Now, @ref{1df,,str},
@ref{1c7,,bytes}, and @ref{1c6,,bytearray} each have their own `maketrans' and
`translate' methods with intermediate translation tables of the appropriate
type.

(Contributed by 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{20a,,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{161b,,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{12e,,xml.etree.ElementTree} class now raises an
@ref{161c,,xml.etree.ElementTree.ParseError} when a parse fails. Previously it
raised an @ref{161d,,xml.parsers.expat.ExpatError}.

@item 
The new, longer @ref{1df,,str()} value on floats may break doctests which rely on
the old output format.

@item 
In @ref{6bf,,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{114,,urllib.request}
and @ref{72,,http.client}.  Such support is still present on the server side
(in @ref{75,,http.server}).

(Contributed by Antoine Pitrou, bpo-10711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10711}.)

@item 
SSL sockets in timeout mode now raise @ref{c0d,,socket.timeout} when a timeout
occurs, rather than a generic @ref{161e,,SSLError}.

(Contributed by 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{838,,PyEval_SaveThread()}
and @ref{839,,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.

(Contributed by Giampaolo Rodola in bpo-6706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6706}.)

@item 
Due to the new @ref{411,,GIL} implementation, @code{PyEval_InitThreads()}
cannot be called before @ref{673,,Py_Initialize()} anymore.
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 1,What’s New In Python 3 0,What’s New In Python 3 2,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 1 doc}@anchor{161f}@anchor{whatsnew/3 1 translation-repo}@anchor{1620}@anchor{whatsnew/3 1 what-s-new-in-python-3-1}@anchor{1621}
@section What’s New In Python 3.1


@*Author: 
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. 
* Other Language Changes: Other Language Changes<13>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules<2>. 
* Optimizations: Optimizations<15>. 
* IDLE: IDLE<2>. 
* Build and C API Changes: Build and C API Changes<6>. 
* Porting to Python 3.1: Porting to Python 3 1. 

@end menu

@node PEP 372 Ordered Dictionaries,PEP 378 Format Specifier for Thousands Separator,,What’s New In Python 3 1
@anchor{whatsnew/3 1 pep-372-ordered-dictionaries}@anchor{1622}
@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{9d5,,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{26,,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{1cf,,collections.namedtuple()} now
returns an ordered dictionary with the values appearing in the same order as
the underlying tuple indices.  The @ref{85,,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 Δείτε επίσης



@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,Other Language Changes<13>,PEP 372 Ordered Dictionaries,What’s New In Python 3 1
@anchor{whatsnew/3 1 pep-378-format-specifier-for-thousands-separator}@anchor{1623}
@subsection PEP 378: Format Specifier for Thousands Separator


The built-in @ref{439,,format()} function and the @ref{a12,,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{326,,int}, @ref{327,,float}, @ref{328,,complex}
and @ref{1c2,,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 Δείτε επίσης



@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 Other Language Changes<13>,New Improved and Deprecated Modules<2>,PEP 378 Format Specifier for Thousands Separator,What’s New In Python 3 1
@anchor{whatsnew/3 1 other-language-changes}@anchor{1624}
@subsection Other Language Changes


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{326,,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{439,,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@}'}.

(Contributed by 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{1619,,bytes.maketrans()} and @ref{161a,,bytearray.maketrans()}.
This change solves the confusion around which types were supported by the
@ref{db,,string} module. Now, @ref{1df,,str}, @ref{1c7,,bytes}, and
@ref{1c6,,bytearray} each have their own `maketrans' and `translate'
methods with intermediate translation tables of the appropriate type.

(Contributed by Georg Brandl; bpo-5675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5675}.)

@item 
The syntax of the @ref{20a,,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

(Contributed by 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.

(Contributed by Eric Smith and Mark Dickinson; bpo-1580@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1580})
@end itemize

@node New Improved and Deprecated Modules<2>,Optimizations<15>,Other Language Changes<13>,What’s New In Python 3 1
@anchor{whatsnew/3 1 new-improved-and-deprecated-modules}@anchor{1625}
@subsection New, Improved, and Deprecated Modules



@itemize *

@item 
Added a @ref{204,,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

(Contributed by Raymond Hettinger; bpo-1696199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1696199}.)

@item 
Added a new module, @ref{102,,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.

(Contributed by Guilherme Polo; bpo-2983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2983}.)

@item 
The @ref{849,,gzip.GzipFile} and @ref{c3d,,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

(Contributed by Antoine Pitrou.)

@item 
The @ref{39,,decimal} module now supports methods for creating a
decimal object from a binary @ref{327,,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{84,,itertools} module grew two new functions.  The
@ref{1626,,itertools.combinations_with_replacement()} function is one of
four for generating combinatorics including permutations and Cartesian
products.  The @ref{1627,,itertools.compress()} function mimics its namesake
from APL.  Also, the existing @ref{1628,,itertools.count()} function now has
an optional `step' argument and can accept any type of counting
sequence including @ref{1c3,,fractions.Fraction} and
@ref{1c2,,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{1cf,,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

(Contributed by Raymond Hettinger; bpo-1818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1818}.)

@item 
The @ref{7a1,,re.sub()}, @ref{7a2,,re.subn()} and @ref{7a0,,re.split()} functions now
accept a flags parameter.

(Contributed by Gregory Smith.)

@item 
The @ref{8a,,logging} module now implements a simple @ref{1629,,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

(Contributed by Vinay Sajip; bpo-4384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4384}).

@item 
The @ref{c6,,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.

(Contributed by Andi Vajda; bpo-4195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4195}.)

@item 
The @ref{aa,,pdb} module can now access and display source code loaded via
@ref{13b,,zipimport} (or any other conformant 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} loader).

(Contributed by Alexander Belopolsky; bpo-4201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4201}.)

@item 
@ref{4a6,,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{bd,,pydoc} help topics for symbols so that @code{help('@@')}
works as expected in the interactive environment.

(Contributed by David Laban; bpo-4739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4739}.)

@item 
The @ref{10f,,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{20a,,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{162a,,assertSetEqual()},
@ref{162b,,assertDictEqual()},
@code{assertDictContainsSubset()},
@ref{162c,,assertListEqual()},
@ref{162d,,assertTupleEqual()},
@ref{162e,,assertSequenceEqual()},
@ref{93d,,assertRaisesRegexp()},
@ref{162f,,assertIsNone()},
and @ref{1630,,assertIsNotNone()}.

(Contributed by Benjamin Peterson and Antoine Pitrou.)

@item 
The @ref{82,,io} module has three new constants for the @ref{1631,,seek()}
method: @ref{1632,,SEEK_SET}, @ref{1633,,SEEK_CUR}, and @ref{1634,,SEEK_END}.

@item 
The @ref{2fc,,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

(Contributed by Ross Light; bpo-4285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4285}.)

@item 
The @code{nntplib} and @ref{77,,imaplib} modules now support IPv6.

(Contributed by Derek Morr; bpo-1655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1655} and bpo-1664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1664}.)

@item 
The @ref{ab,,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.

(Contributed by Alexandre Vassalotti and Antoine Pitrou, bpo-6137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6137}.)

@item 
A new module, @ref{7a,,importlib} was added.  It provides a complete, portable,
pure Python reference implementation of the @ref{9da,,import} statement and its
counterpart, the @ref{ca6,,__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<15>,IDLE<2>,New Improved and Deprecated Modules<2>,What’s New In Python 3 1
@anchor{whatsnew/3 1 optimizations}@anchor{1635}
@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.

(Contributed by Amaury Forgeot d’Arc and 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.

(Contributed by 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.

(Contributed by Antoine Pitrou along with a number of other 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.

(Contributed by Antoine Pitrou and Amaury Forgeot d’Arc, bpo-4868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4868}.)

@item 
The @ref{85,,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{1df,,str}, not with @ref{1c7,,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.

(Contributed by Jake McGuire and 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<15>,What’s New In Python 3 1
@anchor{whatsnew/3 1 idle}@anchor{1636}
@subsection IDLE



@itemize *

@item 
IDLE’s format menu now provides an option to strip trailing whitespace
from a source file.

(Contributed by Roger D. Serwy; bpo-5150@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5150}.)
@end itemize

@node Build and C API Changes<6>,Porting to Python 3 1,IDLE<2>,What’s New In Python 3 1
@anchor{whatsnew/3 1 build-and-c-api-changes}@anchor{1637}
@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{1638,,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

(Contributed by Mark Dickinson; bpo-4258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4258}.)

@item 
The @ref{1639,,PyLong_AsUnsignedLongLong()} function now handles a negative
`pylong' by raising @ref{c57,,OverflowError} instead of @ref{291,,TypeError}.

(Contributed by Mark Dickinson and Lisandro Dalcrin; bpo-5175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5175}.)

@item 
Deprecated @code{PyNumber_Int()}.  Use @ref{e2c,,PyNumber_Long()} instead.

(Contributed by Mark Dickinson; bpo-4910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4910}.)

@item 
Added a new @ref{163a,,PyOS_string_to_double()} function to replace the
deprecated functions @code{PyOS_ascii_strtod()} and @code{PyOS_ascii_atof()}.

(Contributed by Mark Dickinson; bpo-5914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5914}.)

@item 
Added @ref{1617,,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.

(Contributed by Larry Hastings; bpo-5630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5630}.)
@end itemize

@node Porting to Python 3 1,,Build and C API Changes<6>,What’s New In Python 3 1
@anchor{whatsnew/3 1 porting-to-python-3-1}@anchor{163b}
@subsection Porting to 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New In Python 3 0,What’s New in Python 2 7,What’s New In Python 3 1,Τι νέο υπάρχει στην Python
@anchor{whatsnew/3 0 doc}@anchor{163c}@anchor{whatsnew/3 0 translation-repo}@anchor{163d}@anchor{whatsnew/3 0 what-s-new-in-python-3-0}@anchor{163e}
@section What’s New In Python 3.0


@c XXX Add trademark info for Apple, Microsoft.

@*Author: 
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>. 
* Performance:: 
* Porting To Python 3.0: Porting To Python 3 0. 

@end menu

@node Common Stumbling Blocks,Overview Of Syntax Changes,,What’s New In Python 3 0
@anchor{whatsnew/3 0 common-stumbling-blocks}@anchor{163f}
@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{1640}
@subsubsection Print Is A Function


The @code{print} statement has been replaced with a @ref{131f,,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{131f,,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{131f,,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{1641}
@subsubsection Views And Iterators Instead Of Lists


Some well-known APIs no longer return lists:


@itemize *

@item 
@ref{188,,dict} methods @ref{bad,,dict.keys()}, @ref{baf,,dict.items()} and
@ref{bae,,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{43e,,map()} and @ref{c3b,,filter()} return iterators.  If you really need
a list and the input sequences are all of equal length, a quick
fix is to wrap @code{map()} in @ref{4d9,,list()}, e.g. @code{list(map(...))},
but a better fix is
often to use a list comprehension (especially when the original code
uses @ref{1642,,lambda}), or rewriting the code so it doesn’t need a
list at all.  Particularly tricky is @code{map()} invoked for the
side effects of the function; the correct transformation is to use a
regular @ref{321,,for} loop (since creating a list would just be
wasteful).

If the input sequences are not of equal length, @ref{43e,,map()} will
stop at the termination of the shortest of the sequences. For full
compatibility with @code{map()} from Python 2.x, also wrap the sequences in
@ref{1643,,itertools.zip_longest()}, e.g. @code{map(func, *sequences)} becomes
@code{list(map(func, itertools.zip_longest(*sequences)))}.

@item 
@ref{d0f,,range()} now behaves like @code{xrange()} used to behave, except
it works with values of arbitrary size.  The latter no longer
exists.

@item 
@ref{43f,,zip()} now returns an iterator.
@end itemize

@node Ordering Comparisons,Integers,Views And Iterators Instead Of Lists,Common Stumbling Blocks
@anchor{whatsnew/3 0 ordering-comparisons}@anchor{1644}
@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{291,,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{f8c,,sorted()} and @ref{f8d,,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{1645,,__lt__()} for sorting,
@ref{ec0,,__eq__()} with @ref{ec1,,__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{1646}
@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{326,,int}.
That is, there is only one built-in integral type, named
@code{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{156e,,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{45b,,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{1df,,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{1647}
@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{1df,,str}, the type used to hold data is
@ref{1c7,,bytes}.  The biggest difference with the 2.x situation is
that any attempt to mix text and data in Python 3.0 raises
@ref{291,,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{dd7,,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{1df,,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{1df,,str} and @ref{1c7,,bytes} types cannot be mixed, you
must always explicitly convert between them.  Use @ref{ca7,,str.encode()}
to go from @code{str} to @code{bytes}, and @ref{ca8,,bytes.decode()}
to go from @code{bytes} to @code{str}.  You can also use
@code{bytes(s, encoding=...)} and @code{str(b, encoding=...)},
respectively.

@item 
Like @ref{1df,,str}, the @ref{1c7,,bytes} type is immutable.  There is a
separate `mutable' type to hold buffered binary data,
@ref{1c6,,bytearray}.  Nearly all APIs that accept @code{bytes} also
accept @code{bytearray}.  The mutable API is based on
@ref{6c6,,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{1df,,str} instead.  The @code{str} and @ref{1c7,,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 @code{str}.

@item 
Files opened as text files (still the default mode for @ref{32b,,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{1c,,codecs} module.

@item 
The initial values of @ref{94a,,sys.stdin}, @ref{e9c,,sys.stdout} and
@ref{d05,,sys.stderr} are now unicode-only text files (i.e., they are
instances of @ref{a84,,io.TextIOBase}).  To read and write bytes data
with these streams, you need to use their @ref{1648,,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{32b,,open()} and many functions in the
@ref{a5,,os} module) that take filenames accept @ref{1c7,,bytes} objects
as well as strings, and a few APIs have a way to ask for a
@code{bytes} return value.  Thus, @ref{14a6,,os.listdir()} returns a
list of @code{bytes} instances if the argument is a @code{bytes}
instance, and @ref{e51,,os.getcwdb()} returns the current working
directory as a @code{bytes} instance.  Note that when
@code{os.listdir()} returns a list of strings, filenames that
cannot be decoded properly are omitted rather than raising
@ref{675,,UnicodeError}.

@item 
Some system APIs like @ref{4e5,,os.environ} and @ref{1609,,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{45b,,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{82,,io} module and use @ref{12d4,,io.StringIO} or
@ref{1255,,io.BytesIO} for text and data respectively.

@item 
See also the @ref{1649,,Unicode HOWTO}, which was updated for Python 3.0.
@end itemize

@node Overview Of Syntax Changes,Changes Already Present In Python 2 6,Common Stumbling Blocks,What’s New In Python 3 0
@anchor{whatsnew/3 0 overview-of-syntax-changes}@anchor{164a}
@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{164b}
@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 @ref{66b,,__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{164c,,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{164d,,bin()}.

@item 
Bytes literals are introduced with a leading @code{b} or @code{B}, and
there is a new corresponding built-in function, @ref{1c7,,bytes()}.
@end itemize

@node Changed Syntax,Removed Syntax,New Syntax,Overview Of Syntax Changes
@anchor{whatsnew/3 0 changed-syntax}@anchor{164e}
@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{9e4,,raise} statement syntax:
@code{raise [@var{expr} [from @var{expr}]]}.  See below.

@item 
@code{as} and @ref{20a,,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{447,,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{e4d,,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{4d9,,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{164f}
@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{45b,,repr()} instead).

@item 
Removed @code{<>} (use @code{!=} instead).

@item 
Removed keyword: @ref{185,,exec()} is no longer a keyword; it remains as
a function.  (Fortunately the function syntax was also accepted in
2.x.)  Also note that @code{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{1650,,from} `module' @ref{9da,,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{9da,,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,What’s New In Python 3 0
@anchor{whatsnew/3 0 changes-already-present-in-python-2-6}@anchor{1651}
@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{1652,,What’s New in Python 2.6} should be
consulted for longer descriptions.


@itemize *

@item 
@ref{1653,,PEP 343; The “with” statement}.  The @ref{20a,,with} statement is now a standard
feature and no longer needs to be imported from the @ref{0,,__future__}.
Also check out @ref{1654,,Writing Context Managers} and
@ref{1655,,The contextlib module}.

@item 
@ref{1656,,PEP 366; Explicit Relative Imports From a Main Module}.  This enhances the usefulness of the @ref{4ca,,-m}
option when the referenced module lives in a package.

@item 
@ref{1657,,PEP 370; Per-user site-packages Directory}.

@item 
@ref{1658,,PEP 371; The multiprocessing Package}.

@item 
@ref{1659,,PEP 3101; Advanced String Formatting}.  Note: the 2.6 description mentions the
@ref{439,,format()} method for both 8-bit and Unicode strings.  In 3.0,
only the @ref{1df,,str} type (text strings with Unicode support)
supports this method; the @ref{1c7,,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{165a,,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{165b,,PEP 3110; Exception-Handling Changes}.  The @ref{447,,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{165c,,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{1c7,,bytes}.

@item 
@ref{165d,,PEP 3116; New I/O Library}.  The @ref{82,,io} module is now the standard way of
doing file I/O.  The built-in @ref{32b,,open()} function is now an
alias for @ref{92b,,io.open()} and has additional keyword arguments
`encoding', `errors', `newline' and `closefd'.  Also note that an
invalid `mode' argument now raises @ref{277,,ValueError}, not
@ref{13fb,,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{165e,,PEP 3118; Revised Buffer Protocol}.  The old builtin @code{buffer()} is now really gone;
the new builtin @ref{1d2,,memoryview()} provides (mostly) similar
functionality.

@item 
@ref{165f,,PEP 3119; Abstract Base Classes}.  The @ref{4,,abc} module and the ABCs defined in the
@ref{1e,,collections} module plays a somewhat more prominent role in
the language now, and built-in collection types like @ref{188,,dict}
and @ref{4d9,,list} conform to the @ref{1459,,collections.MutableMapping}
and @ref{6c6,,collections.MutableSequence} ABCs, respectively.

@item 
@ref{1660,,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{1661,,PEP 3129; Class Decorators}.

@item 
@ref{1662,,PEP 3141; A Type Hierarchy for Numbers}.  The @ref{a2,,numbers} module is another new use of
ABCs, defining Python’s «numeric tower».  Also note the new
@ref{60,,fractions} module which implements @ref{1663,,numbers.Rational}.
@end itemize

@node Library Changes,PEP 3101 A New Approach To String Formatting,Changes Already Present In Python 2 6,What’s New In Python 3 0
@anchor{whatsnew/3 0 library-changes}@anchor{1664}
@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{6b,,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

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{ab,,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 @code{pickle} / @code{cPickle} pair received this
treatment.  The @ref{b4,,profile} module is on the list for 3.1.  The
@code{StringIO} module has been turned into a class in the @ref{82,,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{34,,dbm} (@code{anydbm}, @code{dbhash}, @code{dbm},
@code{dumbdbm}, @code{gdbm}, @code{whichdb}).

@item 
@ref{6e,,html} (@code{HTMLParser}, @code{htmlentitydefs}).

@item 
@ref{71,,http} (@code{httplib}, @code{BaseHTTPServer},
@code{CGIHTTPServer}, @code{SimpleHTTPServer}, @code{Cookie},
@code{cookielib}).

@item 
@ref{f9,,tkinter} (all @code{Tkinter}-related modules except
@ref{10a,,turtle}).  The target audience of @code{turtle} doesn’t
really care about @code{tkinter}.  Also note that as of Python
2.6, the functionality of @code{turtle} has been greatly enhanced.

@item 
@ref{111,,urllib} (@code{urllib}, @code{urllib2}, @code{urlparse},
@code{robotparse}).

@item 
@ref{136,,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{42b,,set()} class.

@item 
Cleanup of the @ref{e2,,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{8cf,,sys.last_type}
etc. remain.)

@item 
Cleanup of the @ref{6c5,,array.array} type: the @code{read()} and
@code{write()} methods are gone; use @ref{1665,,fromfile()} and
@ref{1666,,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{a3,,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{a87,,acquire()} and
@ref{1667,,release()} instead.

@item 
Cleanup of the @ref{c0,,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{e9,,tempfile}
module.

@item 
The @ref{104,,tokenize} module has been changed to work with bytes.  The
main entry point is now @ref{8e9,,tokenize.tokenize()}, instead of
generate_tokens.

@item 
@code{string.letters} and its friends (@code{string.lowercase} and
@code{string.uppercase}) are gone.  Use
@ref{1668,,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{13,,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 @code{builtins}, not @code{__builtins__}!
@end itemize

@node PEP 3101 A New Approach To String Formatting,Changes To Exceptions,Library Changes,What’s New In Python 3 0
@anchor{whatsnew/3 0 pep-3101-a-new-approach-to-string-formatting}@anchor{1669}
@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,What’s New In Python 3 0
@anchor{whatsnew/3 0 changes-to-exceptions}@anchor{166a}
@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{9b9,,BaseException}.  This is the root of the exception
hierarchy.  This is not new as a recommendation, but the
`requirement' to inherit from @code{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{d9e,,Exception};
@ref{9b9,,BaseException} should only be used as a base class for
exceptions that should only be handled at the top level, such as
@ref{10f7,,SystemExit} or @ref{d96,,KeyboardInterrupt}.  The recommended
idiom for handling all exceptions except for this latter category is
to use @ref{447,,except} @code{Exception}.

@item 
@code{StandardError} was removed.

@item 
Exceptions no longer behave as sequences.  Use the @ref{972,,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{166b,,__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{447,,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{447,,except} or @ref{44c,,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{166c,,__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{166d,,__cause__} attribute of the secondary exception.  The
traceback printed when an unhandled exception occurs walks the chain
of @code{__cause__} and @ref{166c,,__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{166b,,__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{a7a,,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,What’s New In Python 3 0
@anchor{whatsnew/3 0 miscellaneous-other-changes}@anchor{166e}
@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{166f}
@subsubsection Operators And Special Methods



@itemize *

@item 
@code{!=} now returns the opposite of @code{==}, unless @code{==} returns
@ref{440,,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{1670,,__setitem__()} or
@ref{1671,,__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{bb5,,next()} method has been renamed to
@ref{1672,,__next__()}.

@item 
The @code{__oct__()} and @code{__hex__()} special methods are removed
– @ref{1673,,oct()} and @ref{1674,,hex()} use @ref{43d,,__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{1675,,__closure__},
@ref{79c,,__code__}, @ref{1676,,__defaults__},
@ref{1677,,__dict__}, @ref{1582,,__doc__},
@ref{1678,,__globals__}, @ref{1679,,__name__},
respectively.

@item 
@code{__nonzero__()} is now @ref{167a,,__bool__()}.
@end itemize

@node Builtins,,Operators And Special Methods,Miscellaneous Other Changes
@anchor{whatsnew/3 0 builtins}@anchor{167b}
@subsubsection Builtins



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 3135
PEP 3135@footnote{https://peps.python.org/pep-3135/}: New @ref{443,,super()}.  You can now invoke @code{super()}
without arguments and (assuming this is in a regular instance method
defined inside a @ref{167c,,class} statement) the right class and
instance will automatically be chosen.  With arguments, the behavior
of @code{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{167d,,input()}.  That
is, the new @code{input()} function reads a line from
@ref{94a,,sys.stdin} and returns it with the trailing newline stripped.
It raises @ref{167e,,EOFError} if the input is terminated prematurely.
To get the old behavior of @code{input()}, use @code{eval(input())}.

@item 
A new built-in function @ref{bb5,,next()} was added to call the
@ref{1672,,__next__()} method on an object.

@item 
The @ref{167f,,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{1680,,sys.intern()}.

@item 
Removed: @code{apply()}.  Instead of @code{apply(f, args)} use
@code{f(*args)}.

@item 
Removed @ref{156f,,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{32b,,open()}.  There are now several
different kinds of streams that open can return in the @ref{82,,io} module.

@item 
Removed @code{reduce()}.  Use @ref{153,,functools.reduce()} if you really
need it; however, 99 percent of the time an explicit @ref{321,,for}
loop is more readable.

@item 
Removed @code{reload()}.  Use @code{imp.reload()}.

@item 
Removed. @code{dict.has_key()} – use the @ref{323,,in} operator
instead.
@end itemize

@c ======================================================================

@node Build and C API Changes<7>,Performance,Miscellaneous Other Changes,What’s New In Python 3 0
@anchor{whatsnew/3 0 build-and-c-api-changes}@anchor{1681}
@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{1682,,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 @code{PyImport_ImportModuleNoBlock()}, works like
@ref{3a3,,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 Performance,Porting To Python 3 0,Build and C API Changes<7>,What’s New In Python 3 0
@anchor{whatsnew/3 0 performance}@anchor{1683}
@subsection Performance


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 Porting To Python 3 0,,Performance,What’s New In Python 3 0
@anchor{whatsnew/3 0 porting-to-python-3-0}@anchor{1684}
@subsection Porting To 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{1685,,Porting Extension Modules to Python 3}.

@c ======================================================================

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New in Python 2 7,What’s New in Python 2 6,What’s New In Python 3 0,Τι νέο υπάρχει στην Python
@anchor{whatsnew/2 7 doc}@anchor{1686}@anchor{whatsnew/2 7 translation-repo}@anchor{1687}@anchor{whatsnew/2 7 what-s-new-in-python-2-7}@anchor{1688}
@section What’s New in Python 2.7


@*Author: 
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{1c2,,Decimal} class.
There are some useful additions to the standard library, such as a
greatly enhanced @ref{10f,,unittest} module, the @ref{7,,argparse} module
for parsing command-line options, convenient @ref{9d5,,OrderedDict}
and @ref{204,,Counter} classes in the @ref{1e,,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. 
* Other Language Changes: Other Language Changes<14>. 
* New and Improved Modules:: 
* Build and C API Changes: Build and C API Changes<8>. 
* Other Changes and Fixes:: 
* Porting to Python 2.7: Porting to Python 2 7. 
* New Features Added to Python 2.7 Maintenance Releases: New Features Added to Python 2 7 Maintenance Releases. 
* Acknowledgements:: 

@end menu

@node The Future for Python 2 x,Changes to the Handling of Deprecation Warnings,,What’s New in Python 2 7
@anchor{whatsnew/2 7 the-future-for-python-2-x}@anchor{1689}@anchor{whatsnew/2 7 whatsnew27-python31}@anchor{168a}
@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{168b,,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,What’s New in Python 2 7
@anchor{whatsnew/2 7 changes-to-the-handling-of-deprecation-warnings}@anchor{168c}
@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{2c9,,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{2c9,,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{2c9,,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{2c9,,DeprecationWarning} messages by
running Python with the @ref{1c0,,-Wdefault} (short form:
@code{-Wd}) switch, or by setting the 
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,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,What’s New in Python 2 7
@anchor{whatsnew/2 7 python-3-1-features}@anchor{168d}
@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{20a,,with} statement.

@item 
A new version of the @ref{82,,io} library, rewritten in C for performance.

@item 
The ordered-dictionary type described in @ref{168e,,PEP 372; Adding an Ordered Dictionary to collections}.

@item 
The new @code{","} format specifier described in @ref{168f,,PEP 378; Format Specifier for Thousands Separator}.

@item 
The @ref{1d2,,memoryview} object.

@item 
A small subset of the @ref{7a,,importlib} module,
@ref{1690,,described below}.

@item 
The @ref{45b,,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{167f,,round()} function is also now correctly rounded.

@item 
The @ref{1617,,PyCapsule} type, used to provide a C API for extension modules.

@item 
The @ref{160b,,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,What’s New in Python 2 7
@anchor{whatsnew/2 7 pep-0372}@anchor{168e}@anchor{whatsnew/2 7 pep-372-adding-an-ordered-dictionary-to-collections}@anchor{1691}
@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{9d5,,OrderedDict} class in the @ref{1e,,collections} module.

The @ref{9d5,,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{1692,,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{9d5,,OrderedDict} with a regular dictionary
ignores the insertion order and just compares the keys and values.

How does the @ref{9d5,,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{26,,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{da5,,_asdict()} method for
@ref{1cf,,collections.namedtuple()} now returns an ordered dictionary with the
values appearing in the same order as the underlying tuple indices.

@item 
The @ref{85,,json} module’s @ref{10fd,,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 Δείτε επίσης



@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,What’s New in Python 2 7
@anchor{whatsnew/2 7 pep-0378}@anchor{168f}@anchor{whatsnew/2 7 pep-378-format-specifier-for-thousands-separator}@anchor{1693}
@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{89,,locale} module,
which can use different separators («,» in North America, «.» in
Europe) and different grouping sizes, but @code{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{a12,,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{89,,locale}
module, but it’s easier to use.


@subsubheading Δείτε επίσης



@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>,What’s New in Python 2 7
@anchor{whatsnew/2 7 pep-389-the-argparse-module-for-parsing-command-lines}@anchor{1694}
@subsection PEP 389: The argparse Module for Parsing Command Lines


The @ref{7,,argparse} module for parsing command-line arguments was
added as a more powerful replacement for the
@ref{a4,,optparse} module.

This means Python now supports three different modules for parsing
command-line arguments: @ref{64,,getopt}, @ref{a4,,optparse}, and
@ref{7,,argparse}.  The @code{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.
@code{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 @code{argparse}
API consistent with @code{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{7,,argparse} instead of @ref{a4,,optparse}.

Here’s an example:

@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{a4,,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{7,,argparse} has much fancier validation than @ref{a4,,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{31e,,FileType}, which will
automatically open files for you and understands that @code{'-'} means
standard input or output.


@subsubheading Δείτε επίσης



@table @asis

@item @ref{7,,argparse} documentation

The documentation page of the argparse module.

@item @ref{1557,,Migrating optparse code to argparse}

Part of the Python documentation, describing how to convert
code that uses @ref{a4,,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,What’s New in Python 2 7
@anchor{whatsnew/2 7 pep-391-dictionary-based-configuration-for-logging}@anchor{1695}
@subsection PEP 391: Dictionary-Based Configuration For Logging


The @ref{8a,,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{8a,,logging} also supports a @ref{f0e,,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{1559,,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{1696,,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{8a,,logging} module, all
implemented by Vinay Sajip, are:

@c rev79293


@itemize *

@item 
The @ref{a4c,,SysLogHandler} class now supports
syslogging over TCP.  The constructor has a `socktype' parameter
giving the type of socket to use, either @ref{1697,,socket.SOCK_DGRAM}
for UDP or @ref{1698,,socket.SOCK_STREAM} for TCP.  The default
protocol remains UDP.

@item 
@ref{f0c,,Logger} instances gained a @ref{1699,,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{169a,,LoggerAdapter} class gained an
@ref{169b,,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 Δείτε επίσης



@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,What’s New in Python 2 7
@anchor{whatsnew/2 7 pep-3106-dictionary-views}@anchor{169c}
@subsection PEP 3106: Dictionary Views


The dictionary methods @ref{bad,,keys()}, @ref{bae,,values()}, and
@ref{baf,,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{bad,,keys()},
@ref{bae,,values()}, and @ref{baf,,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{bad,,keys()},
@ref{bae,,values()}, and @ref{baf,,items()} methods.


@subsubheading Δείτε επίσης



@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,Other Language Changes<14>,PEP 3106 Dictionary Views,What’s New in Python 2 7
@anchor{whatsnew/2 7 pep-3137-the-memoryview-object}@anchor{169d}
@subsection PEP 3137: The memoryview Object


The @ref{1d2,,memoryview} object provides a view of another object’s
memory content that matches the @ref{1c7,,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{1d2,,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 Δείτε επίσης



@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 Other Language Changes<14>,New and Improved Modules,PEP 3137 The memoryview Object,What’s New in Python 2 7
@anchor{whatsnew/2 7 other-language-changes}@anchor{169e}
@subsection Other Language Changes


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{20a,,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

is equivalent to:

@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{1df,,str()} on
floats and complex numbers; the @ref{327,,float} and @ref{328,,complex}
constructors;
numeric formatting; serializing and
deserializing floats and complex numbers using the
@ref{90,,marshal}, @ref{ab,,pickle}
and @ref{85,,json} modules;
parsing of float and imaginary literals in Python code;
and @ref{1c2,,Decimal}-to-float conversion.

Related to this, the @ref{45b,,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{169f,,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{a12,,str.format()} method now supports automatic numbering of the replacement
fields.  This makes using @code{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{a12,,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{439,,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{a10,,object.__format__()} method now triggers
a @ref{c9b,,PendingDeprecationWarning} if it’s passed a format string,
because the @code{__format__()} method for @ref{e4d,,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{326,,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{9da,,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{1c6,,bytearray} type’s @ref{16a0,,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{69a,,@@classmethod} and
@ref{666,,@@staticmethod} to wrap
methods as class or static methods, the wrapper object now
exposes the wrapped function as their @ref{16a1,,__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{1a9,,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{13fb,,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{1c8,,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<16>. 

@end menu

@node Interpreter Changes,Optimizations<16>,,Other Language Changes<14>
@anchor{whatsnew/2 7 interpreter-changes}@anchor{16a2}@anchor{whatsnew/2 7 new-27-interpreter}@anchor{16a3}
@subsubsection Interpreter Changes


A new environment variable, 
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,PYTHONWARNINGS},
allows controlling warnings.  It should be set to a string
containing warning settings, equivalent to those
used with the @ref{1c0,,-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{74,,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<16>,,Interpreter Changes,Other Language Changes<14>
@anchor{whatsnew/2 7 optimizations}@anchor{16a4}
@subsubsection Optimizations


Several performance enhancements have been added:


@itemize *

@item 
A new opcode was added to perform the initial setup for
@ref{20a,,with} statements, looking up the @ref{9c6,,__enter__()} and
@ref{16a5,,__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

(Contributed by 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{1c6,,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{ab,,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>,Other Language Changes<14>,What’s New in Python 2 7
@anchor{whatsnew/2 7 new-and-improved-modules}@anchor{16a6}
@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{10,,bdb} module’s base debugging class @ref{550,,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{11,,binascii} module now supports the buffer API, so it can be
used with @ref{1d2,,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{14,,bz2} module’s @ref{c3d,,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{204,,Counter} class in the @ref{1e,,collections}
module is useful for tallying data.  @code{Counter} instances
behave mostly like dictionaries but return zero for missing keys instead of
raising a @ref{7df,,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{204,,Counter} methods.
@ref{16a7,,most_common()} returns the N most common
elements and their counts.  @ref{16a8,,elements()}
returns an iterator over the contained elements, repeating each
element as many times as its count.
@ref{1587,,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{9d5,,OrderedDict} is described in the earlier
section @ref{168e,,PEP 372; Adding an Ordered Dictionary to collections}.

New method: The @ref{9d6,,deque} data type now has a
@ref{1589,,count()} method that returns the number of
contained elements equal to the supplied argument `x', and a
@ref{158a,,reverse()} method that reverses the elements
of the deque in-place.  @code{deque} also exposes its maximum
length as the read-only @ref{16a9,,maxlen} attribute.
(Both features added by Raymond Hettinger.)

The @ref{1cf,,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{c9c,,Mapping} abstract base class now
returns @ref{440,,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{26,,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{20a,,with}
statement, has been deprecated, because the @code{with} statement
now supports multiple context managers.

@item 
The @ref{73,,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{29,,copy} module’s @ref{f2b,,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{2d,,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{33,,datetime} module’s @ref{d94,,timedelta} class
gained a @ref{16aa,,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{1c2,,Decimal} class gained a
@ref{15ab,,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{1c2,,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{1c2,,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{145c,,Context} class now accept integers
as well as @ref{1c2,,Decimal} instances; the only exceptions are the
@ref{16ab,,canonical()} and @ref{16ac,,is_canonical()}
methods.  (Patch by Juan José Conti; bpo-7633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7633}.)

When using @ref{1c2,,Decimal} instances with a string’s
@ref{a12,,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{1455,,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{3a,,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{3d,,doctest} module’s @ref{16ad,,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{3e,,email} module’s @ref{780,,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{1c3,,Fraction} class now accepts a single float or
@ref{1c2,,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{291,,TypeError}.
This fixes an oversight, making the @ref{1c3,,Fraction}
match the other numeric types.

@c revision 79455

@item 
New class: @ref{ccb,,FTP_TLS} in
the @ref{61,,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{16ae,,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{12ed,,total_ordering()} in the @ref{62,,functools}
module takes a class that defines an @ref{ec0,,__eq__()} method and one of
@ref{1645,,__lt__()}, @ref{16af,,__le__()}, @ref{16b0,,__gt__()}, or @ref{16b1,,__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{1583,,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{f8c,,sorted()}, @ref{12b9,,min()} and @ref{12ba,,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{63,,gc} module’s @ref{16b2,,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{6a,,gzip} module’s @ref{849,,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{a83,,io.BufferedIOBase} ABC, so you can wrap it with
@ref{15b5,,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{6a,,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{6b,,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{147a,,HTTPResponse} class used by the @ref{71,,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{223,,HTTPConnection} and @ref{224,,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{77,,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{81,,inspect} module’s @ref{126c,,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{82,,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{a84,,io.TextIOBase} class now
has an @ref{16b3,,errors} attribute giving the error setting
used for encoding and decoding errors (one of @code{'strict'}, @code{'replace'},
@code{'ignore'}).

The @ref{16b4,,io.FileIO} class now raises an @ref{53c,,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{16b5,,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{16b6,,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{1628,,itertools.count()} function now has a `step' argument that
allows incrementing by values other than 1.  @code{count()} also
now allows keyword arguments, and using non-integer values such as
floats or @ref{1c2,,Decimal} instances.  (Implemented by Raymond
Hettinger; bpo-5032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5032}.)

@ref{16b6,,itertools.combinations()} and @ref{16b7,,itertools.product()}
previously raised @ref{277,,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{85,,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{9d5,,collections.OrderedDict} type, @ref{22e,,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{8e,,mailbox} module’s @ref{84b,,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{91,,math} module gained
@ref{f98,,erf()} and @ref{f99,,erfc()} for the error function and the complementary error function,
@ref{1595,,expm1()} which computes @code{e**x - 1} with more precision than
using @ref{16b8,,exp()} and subtracting 1,
@ref{1596,,gamma()} for the Gamma function, and
@ref{1597,,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{98,,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{1315,,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{a5,,os} module wraps the following POSIX system
calls: @ref{16b9,,getresgid()} and @ref{16ba,,getresuid()}, which return the
real, effective, and saved GIDs and UIDs;
@ref{16bb,,setresgid()} and @ref{16bc,,setresuid()}, which set
real, effective, and saved GIDs and UIDs to new values;
@ref{16bd,,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{6bd,,os.fork()} function now re-initializes the import lock in
the child process; this fixes problems on Solaris when @code{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{a6,,os.path} module, the @ref{16be,,normpath()} and
@ref{16bf,,abspath()} functions now preserve Unicode; if their input path
is a Unicode string, the return value is also a Unicode string.
(@ref{16be,,normpath()} fixed by Matt Giuca in bpo-5827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5827};
@ref{16bf,,abspath()} fixed by Ezio Melotti in bpo-3426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3426}.)

@item 
The @ref{bd,,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{c1,,re} module’s @ref{7a0,,split()}, @ref{7a1,,sub()}, and @ref{7a2,,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{6ae,,run_path()} in the @ref{c6,,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 @code{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{cd,,shutil} module, @ref{8c3,,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{cd,,shutil}’s @ref{e1d,,copyfile()} and @ref{ded,,copytree()}
functions now raise a @ref{16c0,,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{ce,,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{cf,,site} module, three new functions
return various site- and user-specific paths.
@ref{15e4,,getsitepackages()} returns a list containing all
global site-packages directories,
@ref{15e6,,getusersitepackages()} returns the path of the user’s
site-packages directory, and
@ref{15e5,,getuserbase()} returns the value of the @ref{16c1,,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{cf,,site} module now reports exceptions occurring
when the @ref{d0,,sitecustomize} module is imported, and will no longer
catch and swallow the @ref{d96,,KeyboardInterrupt} exception.  (Fixed by
Victor Stinner; bpo-3137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3137}.)

@item 
The @ref{a62,,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{16c2,,recv_into()} and @ref{16c3,,recvfrom_into()}
methods will now write into objects that support the buffer API, most usefully
the @ref{1c6,,bytearray} and @ref{1d2,,memoryview} objects.  (Implemented by
Antoine Pitrou; bpo-8104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8104}.)

@item 
The @ref{d5,,SocketServer} module’s @ref{16c4,,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{16c5,,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{16c6,,handle_timeout()}
will be called and @ref{16c7,,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{d7,,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{8c8,,load_extension()} to load a particular shared library.
(Updated by Gerhard Häring.)

@item 
The @ref{d8,,ssl} module’s @ref{cbb,,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{933,,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{15c5,,ssl.OPENSSL_VERSION} (a string),
@ref{15c6,,ssl.OPENSSL_VERSION_INFO} (a 5-tuple), and
@ref{15c7,,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{de,,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{16c8,,struct.error} exception.  (Changed by Mark Dickinson;
bpo-1523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1523}.)  The @ref{161b,,pack()} function will also
attempt to use @ref{43d,,__index__()} to convert and pack non-integers
before trying the @ref{43c,,__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{df,,subprocess} module’s
@ref{136b,,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{16c9,,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{df,,subprocess} module will now retry its internal system calls
on receiving an @ref{1140,,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{16ca,,is_declared_global()} in the @ref{e1,,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{e5,,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{2fc,,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{10a4,,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{e7,,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{e7,,tarfile} now supports filtering the @ref{15b8,,TarInfo}
objects being added to a tar file.  When you call @ref{fb3,,add()},
you may supply an optional `filter' argument
that’s a callable.  The `filter' callable will be passed the
@code{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{15b7,,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{16cb,,wait()} method of the @ref{1503,,threading.Event} class
now returns the internal flag on exit.  This means the method will usually
return true because @code{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{10e,,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{113,,urlparse} module’s @ref{2a3,,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{113,,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{9d7,,WeakSet} class in the @ref{11d,,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{12e,,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{137,,xmlrpclib} and
@ref{138,,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{16cc,,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{13a,,zipfile} module’s @ref{ab1,,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{13a,,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{16cd,,read()} and
@ref{16ce,,readline()} now works correctly.
(Contributed by Nir Aides; bpo-7610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7610}.)

The @ref{16cf,,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{548,,writestr()} method now has an optional `compress_type' parameter
that lets you override the default compression method specified in the
@ref{ab1,,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. 
* Updated module; ElementTree 1.3: Updated module ElementTree 1 3. 

@end menu

@node New module importlib,New module sysconfig,,New and Improved Modules
@anchor{whatsnew/2 7 importlib-section}@anchor{1690}@anchor{whatsnew/2 7 new-module-importlib}@anchor{16d0}
@subsubsection New module: importlib


Python 3.1 includes the @ref{7a,,importlib} package, a re-implementation
of the logic underlying Python’s @ref{9da,,import} statement.
@code{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
@code{importlib} package, but instead has a tiny subset that contains
a single function, @ref{927,,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{927,,import_module()} both inserts the imported
module into @code{sys.modules} and returns the module object.

Here are some examples:

@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{7a,,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{16d1}
@subsubsection New module: sysconfig


The @ref{e4,,sysconfig} module has been pulled out of the Distutils
package, becoming a new top-level module in its own right.
@code{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{41e,,get_config_var()} returns variables from Python’s
Makefile and the @code{pyconfig.h} file.

@item 
@ref{51e,,get_config_vars()} returns a dictionary containing
all of the configuration variables.

@item 
@ref{16d2,,get_path()} returns the configured path for
a particular type of module: the standard library,
site-specific modules, platform-specific modules, etc.

@item 
@ref{2dd,,is_python_build()} returns true if you’re running a
binary from a Python source tree, and false otherwise.
@end itemize

Consult the @ref{e4,,sysconfig} documentation for more details and for
a complete list of functions.

The Distutils package and @ref{e4,,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{16d3}
@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{102,,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{102,,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,Updated module ElementTree 1 3,ttk Themed Widgets for Tk,New and Improved Modules
@anchor{whatsnew/2 7 unittest-section}@anchor{16d4}@anchor{whatsnew/2 7 updated-module-unittest}@anchor{16d5}
@subsubsection Updated module: unittest


The @ref{10f,,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{10f,,unittest} module documentation for more details.
(Developed in bpo-6001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6001}.)

The @ref{138c,,main()} function supports some other new options:


@itemize *

@item 
@ref{16d6,,-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{16d7,,-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{16d8,,removeHandler()} decorator that can be used to mark tests that
should have the control-C handling disabled.

@item 
@ref{16d9,,-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{138d,,SkipTest} exception to skip a
test (bpo-1034053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1034053}).

The error messages for @ref{937,,assertEqual()},
@ref{935,,assertTrue()}, and @ref{936,,assertFalse()}
failures now provide more information.  If you set the
@ref{16da,,longMessage} attribute of your @ref{52f,,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{93b,,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 @ref{e11,,setUpModule()} and @ref{16db,,tearDownModule()}
functions.  Classes can have @ref{e12,,setUpClass()} and
@ref{16dc,,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{e43,,addCleanup()} and
@ref{16dd,,doCleanups()} were added.
@code{addCleanup()} lets you add cleanup functions that
will be called unconditionally (after @ref{16de,,setUp()} if
@code{setUp()} fails, otherwise after @ref{16df,,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{10f,,unittest}.


@itemize *

@item 
@ref{162f,,assertIsNone()} and @ref{1630,,assertIsNotNone()} take one
expression and verify that the result is or is not @code{None}.

@item 
@ref{16e0,,assertIs()} and @ref{16e1,,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{16e2,,assertIsInstance()} and
@ref{16e3,,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{16e4,,assertGreater()}, @ref{16e5,,assertGreaterEqual()},
@ref{16e6,,assertLess()}, and @ref{16e7,,assertLessEqual()} compare
two quantities.

@item 
@ref{16e8,,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{937,,assertEqual()}.

@item 
@ref{93c,,assertRegexpMatches()} and
@ref{93e,,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{93d,,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{16e9,,assertIn()} and @ref{16ea,,assertNotIn()}
tests whether `first' is or is not in  `second'.

@item 
@ref{15d1,,assertItemsEqual()} tests whether two provided sequences
contain the same elements.

@item 
@ref{162a,,assertSetEqual()} compares whether two sets are equal, and
only reports the differences between the sets in case of error.

@item 
Similarly, @ref{162c,,assertListEqual()} and @ref{162d,,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{937,,assertEqual()}.
More generally, @ref{162e,,assertSequenceEqual()} compares two sequences
and can optionally check whether both sequences are of a
particular type.

@item 
@ref{162b,,assertDictEqual()} compares two dictionaries and reports the
differences; it’s now used by default when you compare two dictionaries
using @ref{937,,assertEqual()}.  @code{assertDictContainsSubset()} checks whether
all of the key/value pairs in `first' are found in `second'.

@item 
@ref{939,,assertAlmostEqual()} and @ref{93a,,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{16eb,,loadTestsFromName()} properly honors the
@ref{16ec,,suiteClass} attribute of
the @ref{792,,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{937,,assertEqual()} method to handle
new data types.  The @ref{16ed,,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{138c,,unittest.main()} now takes an optional @code{exit} argument.  If
false, @code{main()} doesn’t call @ref{4ff,,sys.exit()}, allowing
@code{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{1510,,TestResult} has new @ref{16ee,,startTestRun()} and
@ref{16ef,,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 Δείτε επίσης



@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 Updated module ElementTree 1 3,,Updated module unittest,New and Improved Modules
@anchor{whatsnew/2 7 elementtree-section}@anchor{16f0}@anchor{whatsnew/2 7 updated-module-elementtree-1-3}@anchor{16f1}
@subsubsection Updated module: 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{e18,,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{161c,,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{e5b,,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{16f2,,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{157b,,register_namespace()}.  In XML mode,
you can use the true/false `xml_declaration' parameter to suppress the
XML declaration.

@item 
New @ref{343,,Element} method:
@ref{157c,,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{343,,Element} method:
@ref{16f3,,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{343,,Element} method:
@ref{157e,,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{847,,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>,Other Changes and Fixes,New and Improved Modules,What’s New in Python 2 7
@anchor{whatsnew/2 7 build-and-c-api-changes}@anchor{16f4}
@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{d49,,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{16f5,,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{160d,,PyErr_NewExceptionWithDoc()} creates a new
exception class, just as the existing @ref{160e,,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{b6a,,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{160b,,PyLong_AsLongAndOverflow()} and
@ref{160a,,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{163a,,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:
@ref{16f6,,Py_ISALNUM},
@ref{16f7,,Py_ISALPHA},
@ref{16f8,,Py_ISDIGIT},
@ref{16f9,,Py_ISLOWER},
@ref{16fa,,Py_ISSPACE},
@ref{16fb,,Py_ISUPPER},
@ref{16fc,,Py_ISXDIGIT},
@ref{16fd,,Py_TOLOWER}, and @ref{16fe,,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}.)

@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{1262,,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{6bd,,os.fork()} might fail because the child is created with only a
single thread running, the thread performing the @code{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{6bd,,os.fork()}, and will also clean up any locks created using the
@ref{f6,,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{672,,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{95a,,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{2d,,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{12f,,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 @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{16ff}@anchor{whatsnew/2 7 whatsnew27-capsules}@anchor{1700}
@subsubsection Capsules


Python 3.1 adds a new C datatype, @ref{1617,,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{d4,,socket} module’s API is exposed as @code{socket.CAPI},
and @ref{10e,,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{1701,,PyCapsule_IsValid()} would
detect the mismatched name and return false.  Refer to
@ref{1702,,Providing a C API for an Extension Module} 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{c9b,,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{1703}
@subsubsection Port-Specific Changes: Windows



@itemize *

@item 
The @ref{97,,msvcrt} module now contains some constants from
the @code{crtassem.h} header file:
@ref{1704,,CRT_ASSEMBLY_VERSION},
@ref{1705,,VC_ASSEMBLY_PUBLICKEYTOKEN},
and @ref{1706,,LIBRARIES_ASSEMBLY_NAME_PREFIX}.
(Contributed by David Cournapeau; bpo-4365@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4365}.)

@item 
The @ref{11f,,_winreg} module for accessing the registry now implements
the @ref{1707,,CreateKeyEx()} and @ref{1708,,DeleteKeyEx()}
functions, extended versions of previously supported functions that
take several extra arguments.  The @ref{1709,,DisableReflectionKey()},
@ref{170a,,EnableReflectionKey()}, and @ref{170b,,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{170c,,os.kill()} function now works on Windows.  The signal value
can be the constants @ref{170d,,CTRL_C_EVENT},
@ref{170e,,CTRL_BREAK_EVENT}, or any integer.  The first two constants
will send @code{Control}-@code{C} and @code{Control}-@code{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{14a6,,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{93,,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{170f}
@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}.)


Άλλαξε στην έκδοση 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{1710}
@subsubsection Port-Specific Changes: FreeBSD



@itemize *

@item 
FreeBSD 7.1’s @code{SO_SETFIB} constant, used with the @ref{115a,,socket()} methods
@ref{1092,,getsockopt()}/@ref{1093,,setsockopt()} to select an
alternate routing table, is now available in the @ref{d4,,socket}
module.  (Added by Kyle VanderBeek; bpo-8235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8235}.)
@end itemize

@node Other Changes and Fixes,Porting to Python 2 7,Build and C API Changes<8>,What’s New in Python 2 7
@anchor{whatsnew/2 7 other-changes-and-fixes}@anchor{1711}
@subsection Other Changes and Fixes



@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{32b,,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{1712,,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 Porting to Python 2 7,New Features Added to Python 2 7 Maintenance Releases,Other Changes and Fixes,What’s New in Python 2 7
@anchor{whatsnew/2 7 porting-to-python-2-7}@anchor{1713}
@subsection Porting to Python 2.7


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


@itemize *

@item 
The @ref{d0f,,range()} function processes its arguments more
consistently; it will now call @ref{43c,,__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{439,,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{1df,,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{20a,,with} statement, the special
methods @ref{9c6,,__enter__()} and @ref{16a5,,__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{e4d,,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{16a5,,__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{1a9,,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{6e7,,datetime} instances that resulted in a year
falling outside the supported range didn’t always raise
@ref{c57,,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{1c2,,Decimal} instances with a string’s
@ref{439,,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{1455,,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{12e,,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{12d4,,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{e5,,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{e7,,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{113,,urlparse} module’s @ref{2a3,,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{291,,TypeError} exception
instead of triggering a @ref{2c9,,DeprecationWarning} (bpo-5080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5080}).

@item 
Use the new @ref{163a,,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,Acknowledgements,Porting to Python 2 7,What’s New in Python 2 7
@anchor{whatsnew/2 7 new-features-added-to-python-2-7-maintenance-releases}@anchor{1714}@anchor{whatsnew/2 7 py27-maintenance-enhancements}@anchor{168b}
@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{1715}
@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}.)


Added in 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{1716}
@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{1717}
@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{1476,,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{91e,,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{d8,,ssl} module was backported. This means @code{ssl}
now supports Server Name Indication, TLS1.x settings, access to the platform
certificate store, the @ref{336,,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{931,,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{1718,,hashlib.algorithms_guaranteed} and
@ref{1719,,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{171a}
@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{171b}
@subsubsection Bootstrapping pip By Default


The new @ref{58,,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{12a4,,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{171c}
@subsubsection Documentation Changes


As part of this change, the @ref{12a6,,Installing Python modules} 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{12a7,,Κατασκευή Επεκτάσεων C και C++ με το setuptools}
and @ref{12a8,,Κατασκευή Επεκτάσεων C και C++ με το setuptools}.


@subsubheading Δείτε επίσης



@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{171d}
@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{71,,httplib} and modules which use it, such as
@ref{114,,urllib2} and @ref{137,,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{171e}
@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{171f}
@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/main/Makefile.pre.in} for details.

(Contributed by Victor Stinner in bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404}.)


Added in 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{1720}
@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}.)


Άλλαξε στην έκδοση 2.7.14.


@c ======================================================================

@node Acknowledgements,,New Features Added to Python 2 7 Maintenance Releases,What’s New in Python 2 7
@anchor{whatsnew/2 7 acknowledgements}@anchor{1721}@anchor{whatsnew/2 7 acks27}@anchor{1722}
@subsection Acknowledgements


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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New in Python 2 6,What’s New in Python 2 5,What’s New in Python 2 7,Τι νέο υπάρχει στην Python
@anchor{whatsnew/2 6 doc}@anchor{1723}@anchor{whatsnew/2 6 translation-repo}@anchor{1724}@anchor{whatsnew/2 6 what-s-new-in-python-2-6}@anchor{1725}@anchor{whatsnew/2 6 whats-new-in-2-6}@anchor{1652}
@section What’s New in Python 2.6


@*Author: 
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{98,,multiprocessing} and @ref{85,,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. 
* Other Language Changes: Other Language Changes<15>. 
* New and Improved Modules: New and Improved Modules<2>. 
* Deprecations and Removals:: 
* Build and C API Changes: Build and C API Changes<9>. 
* Porting to Python 2.6: Porting to Python 2 6. 
* Acknowledgements: Acknowledgements<2>. 

@end menu

@node Python 3 0,Changes to the Development Process,,What’s New in Python 2 6
@anchor{whatsnew/2 6 python-3-0}@anchor{1726}
@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{153,,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{164d,,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 Δείτε επίσης


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,What’s New in Python 2 6
@anchor{whatsnew/2 6 changes-to-the-development-process}@anchor{1727}
@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{1728}
@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 Δείτε επίσης



@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{1729}
@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 Δείτε επίσης



@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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-0343}@anchor{1653}@anchor{whatsnew/2 6 pep-343-the-with-statement}@anchor{172a}
@subsection PEP 343: The “with” statement


The previous version, Python 2.5, added the “@ref{20a,,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{20a,,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{20a,,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{9c6,,__enter__()} and @ref{16a5,,__exit__()}
methods).

The object’s @ref{9c6,,__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{16a5,,__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{20a,,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{321,,for} loop raised an exception
part-way through the block.

@cartouche
@quotation Σημείωση 
In this case, `f' is the same object created by @ref{32b,,open()}, because
@ref{9c6,,__enter__()} returns `self'.
@end quotation
@end cartouche

The @ref{f6,,threading} module’s locks and condition variables  also support the
“@ref{20a,,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 @ref{172b,,localcontext()} function in the @ref{39,,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
* Writing Context Managers:: 
* The contextlib module:: 

@end menu

@node Writing Context Managers,The contextlib module,,PEP 343 The “with” statement
@anchor{whatsnew/2 6 new-26-context-managers}@anchor{1654}@anchor{whatsnew/2 6 writing-context-managers}@anchor{172c}
@subsubsection Writing Context Managers


Under the hood, the “@ref{20a,,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{9c6,,__enter__()} and
@ref{16a5,,__exit__()} methods.

@item 
The context manager’s @ref{9c6,,__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 
The code in `BLOCK' is executed.

@item 
If `BLOCK' raises an exception, the context manager’s @ref{16a5,,__exit__()} method
is called with three arguments, the exception details (@code{type, value, traceback},
the same values returned by @ref{a7a,,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{20a,,with}” statement will
never realize anything went wrong.

@item 
If `BLOCK' didn’t raise an exception,  the @ref{16a5,,__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{9c6,,__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{20a,,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{16a5,,__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{44b,,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 The contextlib module,,Writing Context Managers,PEP 343 The “with” statement
@anchor{whatsnew/2 6 new-module-contextlib}@anchor{1655}@anchor{whatsnew/2 6 the-contextlib-module}@anchor{172d}
@subsubsection The contextlib module


The @ref{27,,contextlib} module provides some functions and a decorator that
are useful when writing objects for use with the “@ref{20a,,with}” statement.

The decorator is called @ref{20e,,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{d93,,yield} will be
executed as the @ref{9c6,,__enter__()} method, and the value yielded will
be the method’s return value that will get bound to the variable in the
“@ref{20a,,with}” statement’s @code{as} clause, if any.  The code after
the @code{yield} will be executed in the @ref{16a5,,__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{27,,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{20a,,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 @ref{3ec,,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 Δείτε επίσης



@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{20a,,with}” statement, which can be helpful in learning how the statement
works.
@end table

The documentation  for the @ref{27,,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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-0366}@anchor{1656}@anchor{whatsnew/2 6 pep-366-explicit-relative-imports-from-a-main-module}@anchor{172e}
@subsection PEP 366: Explicit Relative Imports From a Main Module


Python’s @ref{4ca,,-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{58c,,module.__package__} attribute.
When this attribute is present, relative imports will be
relative to the value of this attribute instead of the
@ref{172f,,__name__} attribute.

PEP 302-style importers can then set @ref{58c,,__package__} as necessary.
The @ref{c6,,runpy} module that implements the @ref{4ca,,-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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-0370}@anchor{1657}@anchor{whatsnew/2 6 pep-370-per-user-site-packages-directory}@anchor{1730}
@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 and 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 μεταβλητή περιβάλλοντος; PYTHONUSERBASE
@ref{1731,,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 @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{1732,,-s} option or setting the 
@geindex PYTHONNOUSERSITE
@geindex μεταβλητή περιβάλλοντος; PYTHONNOUSERSITE
@ref{1733,,PYTHONNOUSERSITE}
environment variable.


@subsubheading Δείτε επίσης



@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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-0371}@anchor{1658}@anchor{whatsnew/2 6 pep-371-the-multiprocessing-package}@anchor{1734}
@subsection PEP 371: The @code{multiprocessing} Package


The new @ref{98,,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{98,,multiprocessing} module started out as an exact emulation of
the @ref{f6,,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 @ref{4de,,Process}, which is passed a callable object and
a collection of arguments.  The @ref{1735,,start()} method
sets the callable running in a subprocess, after which you can call
the @ref{1736,,is_alive()} method to check whether the
subprocess is still running and the @ref{1737,,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{1738,,Queue} is used to communicate the result of the factorial.
The @code{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 @code{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, @ref{1315,,Pool} and
@ref{4dc,,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
@ref{1739,,apply()} or
@ref{173a,,apply_async()} to add a single request, and
@ref{1491,,map()} or
@ref{1492,,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

This produces the following output:

@example
1
39916800
51090942171709440000
8222838654177922817725562880000000
33452526613163807108170062053440751665152000000000
...
@end example

The other high-level interface, the @ref{4dc,,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{188,,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
@ref{173b,,Lock()},
@ref{173c,,RLock()},
and @ref{173d,,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 Δείτε επίσης


The documentation for the @ref{98,,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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-3101}@anchor{1659}@anchor{whatsnew/2 6 pep-3101-advanced-string-formatting}@anchor{173e}
@subsection PEP 3101: Advanced String Formatting


In Python 3.0, the @code{%} operator is supplemented by a more powerful string
formatting method, @ref{439,,format()}.  Support for the @ref{a12,,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

Character

@tab

Effect

@item

< (default)

@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{173f,,complete list}; here’s a sample:


@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{b}

@tab

Binary. Outputs the number in base 2.

@item

@code{c}

@tab

Character. Converts the integer to the corresponding Unicode character
before printing.

@item

@code{d}

@tab

Decimal Integer. Outputs the number in base 10.

@item

@code{o}

@tab

Octal format. Outputs the number in base 8.

@item

@code{x}

@tab

Hex format. Outputs the number in base 16, using lower-case letters for
the digits above 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

Percentage. Multiplies the number by 100 and displays in fixed (“f”)
format, followed by a percent sign.

@end multitable


Classes and types can define a @ref{a10,,__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{439,,format()} builtin that will format a single
value.  It calls the type’s @ref{a10,,__format__()} method with the
provided specifier:

@example
>>> format(75.6564, '.2f')
'75.66'
@end example


@subsubheading Δείτε επίσης



@table @asis

@item @ref{173f,,Format string syntax}

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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-3105}@anchor{165a}@anchor{whatsnew/2 6 pep-3105-print-as-a-function}@anchor{1740}
@subsection PEP 3105: @code{print} As a Function


The @code{print} statement becomes the @ref{131f,,print()} function in Python 3.0.
Making @code{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 Δείτε επίσης



@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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-3110}@anchor{165b}@anchor{whatsnew/2 6 pep-3110-exception-handling-changes}@anchor{1741}
@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{291,,TypeError} and
@ref{277,,ValueError} exceptions, but this code actually does something
different: it will catch @code{TypeError} and bind the resulting
exception object to the local name @code{"ValueError"}.  The
@code{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 Δείτε επίσης



@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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-3112}@anchor{165c}@anchor{whatsnew/2 6 pep-3112-byte-literals}@anchor{1742}
@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{1c7,,bytes} constructor.  For future compatibility,
Python 2.6 adds @code{bytes} as a synonym for the @ref{1df,,str} type,
and it also supports the @code{b'@w{'}} notation.

The 2.6 @ref{1df,,str} differs from 3.0’s @ref{1c7,,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{1df,,str()} of the list.

The primary use of @ref{1c7,,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 @code{bytes} or @ref{1df,,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{b71,,PyBytesObject}.  Python 2.6 uses @code{#define}
to support using the names @ref{b71,,PyBytesObject()},
@ref{1743,,PyBytes_Check()}, @ref{3b2,,PyBytes_FromStringAndSize()},
and all the other functions and macros used with strings.

Instances of the @ref{1c7,,bytes} type are immutable just
as strings are.  A new @ref{1c6,,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
@ref{1744,,startswith()}/@ref{1745,,endswith()},
@ref{1746,,find()}/@ref{1747,,rfind()},
and some of the methods of lists, such as @ref{1748,,append()},
@ref{1749,,pop()},  and @ref{174a,,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{174b,,PyByteArray_FromObject()},
@ref{174c,,PyByteArray_FromStringAndSize()},
and various other functions.


@subsubheading Δείτε επίσης



@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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-3116}@anchor{165d}@anchor{whatsnew/2 6 pep-3116-new-i-o-library}@anchor{174d}
@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 @code{readline()},
for example.  Python 3.0 introduces a layered I/O library in the @ref{82,,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{82,,io} module:


@itemize *

@item 
@ref{147c,,RawIOBase} defines raw I/O operations: @ref{11d0,,read()},
@ref{11d1,,readinto()}, @ref{174e,,write()},
@ref{1631,,seek()}, @ref{174f,,tell()}, @ref{16b5,,truncate()},
and @ref{70b,,close()}.
Most of the methods of this class will often map to a single system call.
There are also @ref{1750,,readable()}, @ref{1751,,writable()},
and @ref{1752,,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 
@ref{a83,,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 @ref{147c,,RawIOBase},
and adds a @ref{1753,,raw} attribute holding the underlying
raw object.

There are five concrete classes implementing this ABC.
@ref{1754,,BufferedWriter} and @ref{15b5,,BufferedReader} are for objects
that support write-only or read-only usage that have a @ref{1631,,seek()}
method for random access.  @ref{1755,,BufferedRandom} objects support
read and write access upon the same underlying stream, and
@ref{1756,,BufferedRWPair} is for objects such as TTYs that have both
read and write operations acting upon unconnected streams of data.
The @ref{1255,,BytesIO} class supports reading, writing, and seeking
over an in-memory buffer.

@geindex universal newlines;What's new

@item 
@ref{a84,,TextIOBase}: Provides functions for reading and writing
strings (remember, strings will be Unicode in Python 3.0),
and supporting @ref{10f1,,universal newlines}.  @code{TextIOBase} defines
the @ref{c2,,readline()} method and supports iteration upon
objects.

There are two concrete implementations.  @ref{b9c,,TextIOWrapper}
wraps a buffered I/O object, supporting all of the methods for
text I/O and adding a @ref{1648,,buffer} attribute for access
to the underlying object.  @ref{12d4,,StringIO} simply buffers
everything in memory without ever writing anything to disk.

(In Python 2.6, @ref{12d4,,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{82,,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{82,,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 Δείτε επίσης



@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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-3118}@anchor{165e}@anchor{whatsnew/2 6 pep-3118-revised-buffer-protocol}@anchor{1757}
@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{c1,,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{82c,,PyObject_GetBuffer()} specifies
constraints upon the memory returned.  Some examples are:


@itemize *

@item 
@ref{1758,,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{1759,,PyBUF_C_CONTIGUOUS} and @ref{175a,,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{3b1,,PyArg_ParseTuple()},
@code{s*} and @code{z*}, return locked buffer objects for a parameter.


@subsubheading Δείτε επίσης



@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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-3119}@anchor{165f}@anchor{whatsnew/2 6 pep-3119-abstract-base-classes}@anchor{175b}
@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 @ref{12c9,,ABCMeta}, special handling of
this metaclass by the @ref{2ef,,isinstance()} and @ref{2f0,,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()}?
@code{copy`and :meth:()}!update`?  Iterating over the object with @code{iter()}?

The Python 2.6 @ref{1e,,collections} module includes a number of
different ABCs that represent these distinctions.  @code{Iterable}
indicates that a class defines @ref{102d,,__iter__()}, and
@code{Container} means the class defines a @ref{175c,,__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 @ref{1436,,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 @ref{1436,,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 @ref{1433,,@@~abc.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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 3119

@item PEP 3119@footnote{https://peps.python.org/pep-3119/} - Introducing Abstract Base Classes

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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-3127}@anchor{1660}@anchor{whatsnew/2 6 pep-3127-integer-literal-support-and-syntax}@anchor{175d}
@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{1673,,oct()} builtin still returns numbers
prefixed with a leading zero, and a new @ref{164d,,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{326,,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 Δείτε επίσης



@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,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-3129}@anchor{1661}@anchor{whatsnew/2 6 pep-3129-class-decorators}@anchor{175e}
@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

This is equivalent to:

@example
class A:
  pass

A = foo(bar(A))
@end example


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 3129

@item PEP 3129@footnote{https://peps.python.org/pep-3129/} - Class Decorators

PEP written by Collin Winter.
@end table


@c ======================================================================

@node PEP 3141 A Type Hierarchy for Numbers,Other Language Changes<15>,PEP 3129 Class Decorators,What’s New in Python 2 6
@anchor{whatsnew/2 6 pep-3141}@anchor{1662}@anchor{whatsnew/2 6 pep-3141-a-type-hierarchy-for-numbers}@anchor{175f}
@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{a2,,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{60,,fractions} module.  (It’s called
@code{Fraction} instead of @code{Rational} to avoid
a name clash with @ref{1663,,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{167f,,round()}, @ref{1760,,math.floor()}, @ref{1761,,math.ceil()}, and adds a new
one, @ref{1762,,math.trunc()}, that’s been backported to Python 2.6.
@code{math.trunc()} rounds toward zero, returning the closest
@code{Integral} that’s between the function’s argument and zero.


@subsubheading Δείτε επίσης



@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{1763}
@subsubsection The @code{fractions} Module


To fill out the hierarchy of numeric types, the @ref{60,,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{60,,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 Other Language Changes<15>,New and Improved Modules<2>,PEP 3141 A Type Hierarchy for Numbers,What’s New in Python 2 6
@anchor{whatsnew/2 6 other-language-changes}@anchor{1764}
@subsection Other Language Changes


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{8e2,,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 @code{hasattr()} would
therefore be @code{False}.  This logic shouldn’t be applied to
@ref{d96,,KeyboardInterrupt} and @ref{10f7,,SystemExit}, however; Python 2.6
will no longer discard such exceptions when @code{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

(Contributed by 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{fba,,StopIteration} exception will be raised.  (Backported
in bpo-2719@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2719}.)

@item 
Tuples now have @ref{1765,,index()} and @ref{1766,,count()} methods
matching the list type’s @ref{1767,,index()} and @ref{1768,,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{327,,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{91,,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{1674,,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{328,,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{291,,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{1769,,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{176a,,GeneratorExit} exception now subclasses
@ref{9b9,,BaseException} instead of @ref{d9e,,Exception}.  This means
that an exception handler that does @code{except Exception:}
will not inadvertently catch @code{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{1c8,,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{328,,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{a23,,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 @code{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{176b,,__self__}, and @code{im_func} is also available as
@ref{16a1,,__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{28b,,locals()} function inside a
@ref{167c,,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<17>. 
* Interpreter Changes: Interpreter Changes<2>. 

@end menu

@node Optimizations<17>,Interpreter Changes<2>,,Other Language Changes<15>
@anchor{whatsnew/2 6 optimizations}@anchor{176c}
@subsubsection Optimizations



@itemize *

@item 
The @ref{11b,,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 @ref{176d,,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{de,,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{16a5,,__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<17>,Other Language Changes<15>
@anchor{whatsnew/2 6 interpreter-changes}@anchor{176e}@anchor{whatsnew/2 6 new-26-interpreter}@anchor{176f}
@subsubsection Interpreter Changes


Two command-line options have been reserved for use by other Python
implementations.  The @code{-J} switch has been reserved for use by
Jython for Jython-specific options, such as switches that are passed to
the underlying JVM.  @ref{178,,-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{1770,,-B} switch to the Python interpreter,
or by setting the 
@geindex PYTHONDONTWRITEBYTECODE
@geindex μεταβλητή περιβάλλοντος; PYTHONDONTWRITEBYTECODE
@ref{1771,,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 μεταβλητή περιβάλλοντος; PYTHONIOENCODING
@ref{13b3,,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,Other Language Changes<15>,What’s New in Python 2 6
@anchor{whatsnew/2 6 new-and-improved-modules}@anchor{1772}
@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{113,,urlparse} module.
The versions still available in the @code{cgi} module will
trigger @ref{c9b,,PendingDeprecationWarning} messages in 2.6
(bpo-600362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=600362}).

@item 
The @ref{19,,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{19,,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{19,,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{1e,,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{1e,,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{74,,Cookie} module’s @ref{fc3,,Morsel} objects now support an
@ref{1773,,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{2e,,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{31,,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{33,,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{39,,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{3a,,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{cca,,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{62,,functools} module.  In Python 3.0, the builtin has been
dropped and @code{reduce()} is only available from @code{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{65,,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{2d4,,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{6c,,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{6c,,heapq} is now implemented to only use less-than comparison,
instead of the less-than-or-equal comparison it previously used.
This makes @code{heapq}’s usage of a type match the
@ref{f8d,,list.sort()} method.
(Contributed by Raymond Hettinger.)

@item 
An optional @code{timeout} parameter, specifying a timeout measured in
seconds, was added to the @ref{223,,httplib.HTTPConnection} and
@ref{224,,HTTPSConnection} class constructors.  (Added by Facundo
Batista.)

@item 
Most of the @ref{81,,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{84,,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{84,,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{8a,,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{91,,math} module:


@itemize *

@item 
@ref{1774,,isinf()} and @ref{1775,,isnan()} determine whether a given float
is a (positive or negative) infinity or a NaN (Not a Number), respectively.

@item 
@ref{1776,,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{d13,,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{1777,,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{1778,,acosh()}, @ref{1779,,asinh()}
and @ref{177a,,atanh()} compute the inverse hyperbolic functions.

@item 
@ref{177b,,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{1662,,PEP 3141's type hierarchy for numbers}.
@end itemize

@item 
The @ref{91,,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{277,,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 @code{ValueError}.
Where Annex “F” of the C99 standard recommends signaling “overflow”,
Python will raise @ref{c57,,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{23c,,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{a3,,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{a5,,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{d9,,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{df,,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{4e8,,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{8b9,,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{a6,,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{177c,,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{aa,,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{177d,,pdb.post_mortem()} function, used to begin debugging a
traceback, will now use the traceback returned by @ref{a7a,,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{ac,,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{ae,,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{c0,,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{c1,,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{c5,,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{c7,,sched} module’s @code{scheduler} instances now
have a read-only @ref{be,,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{c9,,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{ded,,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{cd,,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

(Contributed by 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{ce,,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{177e,,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{d2,,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{d4,,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{d5,,SocketServer} module now support
calling a @ref{16c6,,handle_timeout()} method after a span of inactivity
specified by the server’s @ref{16c5,,timeout} attribute.  (Contributed
by Michael Pomraning.)  The @ref{14eb,,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{d7,,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{de,,struct} module now supports the C99 _Bool type,
using the format character @code{'?'}.
(Contributed by David Remahl.)

@item 
The @ref{6bf,,Popen} objects provided by the @ref{df,,subprocess} module
now have @ref{177f,,terminate()}, @ref{1780,,kill()}, and @ref{1781,,send_signal()} methods.
On Windows, @code{send_signal()} only supports the @ref{1782,,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{e2,,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{1770,,-B}
switch to the Python interpreter, or by setting the
@geindex PYTHONDONTWRITEBYTECODE
@geindex μεταβλητή περιβάλλοντος; PYTHONDONTWRITEBYTECODE
@ref{1771,,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{1783,,sys.getprofile()} and @ref{1784,,sys.gettrace()}.
(Contributed by Georg Brandl; bpo-1648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1648}.)

@item 
The @ref{e7,,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{8d6,,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{ed,,test.test_support} module gained a number
of context managers useful for writing tests.
@ref{1785,,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{f5,,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{f6,,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{f6,,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{f8,,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{10a,,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{57f,,urllib.urlopen} function and the
@code{urllib.ftpwrapper} class constructor, as well as the
@code{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{10e,,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{11b,,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 @code{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{138,,SimpleXMLRPCServer} and @code{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{137,,xmlrpclib} module no longer automatically converts
@ref{48d,,datetime.date} and @ref{48e,,datetime.time} to the
@ref{1786,,xmlrpclib.DateTime} type; the conversion semantics were
not necessarily correct for all applications.  Code using
@code{xmlrpclib} should convert @code{date} and @code{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{13a,,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{32b,,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{13a,,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{1787}
@subsubsection The @code{ast} module


The @ref{9,,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{184,,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{1788}
@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{45b,,repr()}.  In Python 3.0,
@code{repr()} will return a Unicode string, while @ref{1789,,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{1673,,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{178a}
@subsubsection The @code{json} module: JavaScript Object Notation


The new @ref{85,,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{85,,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{85,,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{178b}
@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{b0,,plistlib} module
has been promoted to the standard library.

Using the module is simple:

@example
import sys
import plistlib
import datetime as dt

# Create data structure
data_struct = dict(lastAccessed=dt.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{178c}
@subsubsection ctypes Enhancements


Thomas Heller continued to maintain and enhance the
@ref{2d,,ctypes} module.

@ref{2d,,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{2d,,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{2d,,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{2d,,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{178d}
@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{d8,,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{d4,,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 Δείτε επίσης


The documentation for the @ref{d8,,ssl} module.


@c ======================================================================

@node Deprecations and Removals,Build and C API Changes<9>,New and Improved Modules<2>,What’s New in Python 2 6
@anchor{whatsnew/2 6 deprecations-and-removals}@anchor{178e}
@subsection Deprecations and Removals



@itemize *

@item 
String exceptions have been removed.  Attempting to use them raises a
@ref{291,,TypeError}.

@item 
Changes to the @ref{d9e,,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{972,,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{3e,,email}
package instead.

@item 
The @code{md5} module has been deprecated; use the @ref{6b,,hashlib} module
instead.

@item 
The @code{posixfile} module has been deprecated; @ref{178f,,fcntl.lockf()}
provides better locking.

@item 
The @code{popen2} module has been deprecated; use the @ref{df,,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{42b,,set} and @ref{9d4,,frozenset} types.

@item 
The @code{sha} module has been deprecated; use the @ref{6b,,hashlib} module
instead.
@end itemize

@c ======================================================================

@node Build and C API Changes<9>,Porting to Python 2 6,Deprecations and Removals,What’s New in Python 2 6
@anchor{whatsnew/2 6 build-and-c-api-changes}@anchor{1790}
@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{1757,,the PEP 3118 section},
adds @ref{82c,,PyObject_GetBuffer()} and @ref{82d,,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{1bd,,ImportError}.  A new API
function, @code{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 @code{ImportError} is raised.
(Contributed by Christian Heimes.)

@item 
Several functions return information about the platform’s
floating-point support.  @ref{1791,,PyFloat_GetMax()} returns
the maximum representable floating-point value,
and @ref{1792,,PyFloat_GetMin()} returns the minimum
positive value.  @ref{1793,,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{3ba,,PyComplex_AsCComplex()} will now accept arguments that
have a @code{__complex__()} method.  In particular, the functions in the
@ref{19,,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{1794,,PyModule_AddStringMacro}
and @ref{1795,,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{b61,,Py_SIZE()},
@code{Py_Type()} became @ref{5f5,,Py_TYPE()}, and
@code{Py_Refcnt()} became @ref{54b,,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{1796}
@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{97,,msvcrt} module now supports
both the normal and wide char variants of the console I/O
API.  The @ref{1797,,getwch()} function reads a keypress and returns a Unicode
value, as does the @ref{1798,,getwche()} function.  The @ref{1799,,putwch()} function
takes a Unicode character and writes it to the console.
(Contributed by Christian Heimes.)

@item 
@ref{177c,,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{d4,,socket} module’s socket objects now have an
@ref{1090,,ioctl()} method that provides a limited interface to the
@code{WSAIoctl()} system interface.

@item 
The @ref{11f,,_winreg} module now has a function,
@ref{179a,,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{20a,,with} statements. (Contributed by Christian Heimes.)

@ref{11f,,_winreg} also has better support for x64 systems,
exposing the @ref{1709,,DisableReflectionKey()}, @ref{170a,,EnableReflectionKey()},
and @ref{170b,,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{179b}
@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{179c}
@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 Porting to Python 2 6,Acknowledgements<2>,Build and C API Changes<9>,What’s New in Python 2 6
@anchor{whatsnew/2 6 porting-to-python-2-6}@anchor{179d}
@subsection Porting to 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{291,,TypeError}.

@item 
The @code{__init__()} method of @ref{9d6,,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{2fa,,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{291,,TypeError}.  This will affect
@code{__init__()} methods that end up calling the corresponding
method on @ref{e4d,,object} (perhaps through using @ref{443,,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{ca6,,__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{1bd,,ImportError}.

@item 
C API: the @ref{179e,,PyImport_Import()} and @ref{3a3,,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{1769,,PyObject_HashNotImplemented()}.

@item 
The @ref{d4,,socket} module exception @ref{13fe,,socket.error} now inherits
from @ref{13fb,,IOError}.  Previously it wasn’t a subclass of
@code{StandardError} but now it is, through @code{IOError}.
(Implemented by Gregory P. Smith; bpo-1706815@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1706815}.)

@item 
The @ref{137,,xmlrpclib} module no longer automatically converts
@ref{48d,,datetime.date} and @ref{48e,,datetime.time} to the
@ref{1786,,xmlrpclib.DateTime} type; the conversion semantics were
not necessarily correct for all applications.  Code using
@code{xmlrpclib} should convert @code{date} and @code{time}
instances. (bpo-1330538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1330538})

@item 
(3.0-warning mode) The @ref{d9e,,Exception} class now warns
when accessed using slicing or index access; having
@code{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 Acknowledgements<2>,,Porting to Python 2 6,What’s New in Python 2 6
@anchor{whatsnew/2 6 acknowledgements}@anchor{179f}@anchor{whatsnew/2 6 acks}@anchor{17a0}
@subsection Acknowledgements


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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New in Python 2 5,What’s New in Python 2 4,What’s New in Python 2 6,Τι νέο υπάρχει στην Python
@anchor{whatsnew/2 5 doc}@anchor{17a1}@anchor{whatsnew/2 5 translation-repo}@anchor{17a2}@anchor{whatsnew/2 5 what-s-new-in-python-2-5}@anchor{17a3}
@section What’s New in Python 2.5


@*Author: 
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{2d,,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{17a4,,PEP 308; Conditional Expressions}.  The new “@ref{20a,,with}” statement will make
writing cleanup code easier (section @ref{17a5,,PEP 343; The “with” statement}).  Values can now be passed
into generators (section @ref{17a6,,PEP 342; New Generator Features}).  Imports are now visible as either
absolute or relative (section @ref{17a7,,PEP 328; Absolute and Relative Imports}).  Some corner cases of exception
handling are handled better (section @ref{17a8,,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; Conditional Expressions: PEP 308 Conditional Expressions. 
* PEP 309; Partial Function Application: PEP 309 Partial Function Application. 
* 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. 
* Other Language Changes: Other Language Changes<16>. 
* New@comma{} Improved@comma{} and Removed Modules: New Improved and Removed Modules. 
* Build and C API Changes: Build and C API Changes<10>. 
* Porting to Python 2.5: Porting to Python 2 5. 
* Acknowledgements: Acknowledgements<3>. 

@end menu

@node PEP 308 Conditional Expressions,PEP 309 Partial Function Application,,What’s New in Python 2 5
@anchor{whatsnew/2 5 pep-308}@anchor{17a4}@anchor{whatsnew/2 5 pep-308-conditional-expressions}@anchor{17a9}
@subsection PEP 308: Conditional Expressions


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 eventually chose a surprising syntax:

@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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 308

@item PEP 308@footnote{https://peps.python.org/pep-0308/} - Conditional Expressions

PEP written by Guido van Rossum and Raymond D. Hettinger; implemented by Thomas
Wouters.
@end table


@c ======================================================================

@node PEP 309 Partial Function Application,PEP 314 Metadata for Python Software Packages v1 1,PEP 308 Conditional Expressions,What’s New in Python 2 5
@anchor{whatsnew/2 5 pep-309}@anchor{17aa}@anchor{whatsnew/2 5 pep-309-partial-function-application}@anchor{17ab}
@subsection PEP 309: Partial Function Application


The @ref{62,,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.

Here’s a small but realistic example:

@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{62,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 309

@item PEP 309@footnote{https://peps.python.org/pep-0309/} - Partial Function Application

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 Partial Function Application,What’s New in Python 2 5
@anchor{whatsnew/2 5 pep-314}@anchor{17ac}@anchor{whatsnew/2 5 pep-314-metadata-for-python-software-packages-v1-1}@anchor{17ad}
@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 Δείτε επίσης



@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,What’s New in Python 2 5
@anchor{whatsnew/2 5 pep-328}@anchor{17a7}@anchor{whatsnew/2 5 pep-328-absolute-and-relative-imports}@anchor{17ae}
@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{db,,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{db,,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{9da,,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{db,,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 Δείτε επίσης



@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 written by Aahz; implemented by 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,What’s New in Python 2 5
@anchor{whatsnew/2 5 pep-338}@anchor{17af}@anchor{whatsnew/2 5 pep-338-executing-modules-as-scripts}@anchor{17b0}
@subsection PEP 338: Executing Modules as Scripts


The @ref{4ca,,-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{c6,,runpy}.

The @ref{c6,,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{13b,,zipimport} module.  This means you can add a .zip archive’s path to
@code{sys.path} and then use the @ref{4ca,,-m} switch to execute code from the
archive.


@subsubheading Δείτε επίσης



@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,What’s New in Python 2 5
@anchor{whatsnew/2 5 pep-341}@anchor{17a8}@anchor{whatsnew/2 5 pep-341-unified-try-except-finally}@anchor{17b1}
@subsection PEP 341: Unified try/except/finally


Until Python 2.5, the @ref{ad6,,try} statement came in two flavours. You could
use a @ref{44c,,finally} block to ensure that code is always executed, or one or
more @ref{447,,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{447,,except} blocks and a @ref{44c,,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{447,,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 Δείτε επίσης



@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,What’s New in Python 2 5
@anchor{whatsnew/2 5 pep-342}@anchor{17a6}@anchor{whatsnew/2 5 pep-342-new-generator-features}@anchor{17b2}
@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{d93,,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{bb5,,next()} method, picking up after the @code{yield} statement.

In Python 2.3, @ref{d93,,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{d93,,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{d93,,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{d93,,yield} expression returns the
specified `value'.  If the regular @ref{bb5,,next()} method is called, the
@code{yield} returns @ref{a65,,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{d93,,yield} will usually return @ref{a65,,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{d93,,yield} expression
where the generator’s execution is paused.

@item 
@code{close()} raises a new @ref{176a,,GeneratorExit} exception inside the generator
to terminate the iteration.  On receiving this exception, the generator’s code
must either raise @code{GeneratorExit} or @ref{fba,,StopIteration}.  Catching the
@code{GeneratorExit} exception and returning a value is illegal and will trigger
a @ref{30d,,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{176a,,GeneratorExit} occurs, I suggest
using a @code{try: ... finally:} suite instead of  catching @code{GeneratorExit}.
@end itemize

The cumulative effect of these changes is to turn generators from one-way
producers of information into both producers and consumers.

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{44b,,return} statement), but coroutines can be entered,
exited, and resumed at many different points (the @ref{d93,,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{44c,,finally} clause will now always get a
chance to run.  The syntactic restriction that you couldn’t mix @ref{d93,,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{20a,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 342

@item PEP 342@footnote{https://peps.python.org/pep-0342/} - Coroutines via Enhanced Generators

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}

The Wikipedia entry for  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,What’s New in Python 2 5
@anchor{whatsnew/2 5 pep-343}@anchor{17a5}@anchor{whatsnew/2 5 pep-343-the-with-statement}@anchor{17b3}
@subsection PEP 343: The “with” statement


The “@ref{20a,,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{20a,,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{9c6,,__enter__()} and @ref{16a5,,__exit__()}
methods.

The object’s @ref{9c6,,__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{16a5,,__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{20a,,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{321,,for} loop raised an exception
part-way through the block.

@cartouche
@quotation Σημείωση 
In this case, `f' is the same object created by @ref{32b,,open()}, because
@ref{9c6,,__enter__()} returns `self'.
@end quotation
@end cartouche

The @ref{f6,,threading} module’s locks and condition variables  also support the
“@ref{20a,,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{39,,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
* Writing Context Managers: Writing Context Managers<2>. 
* The contextlib module: The contextlib module<2>. 

@end menu

@node Writing Context Managers<2>,The contextlib module<2>,,PEP 343 The “with” statement<2>
@anchor{whatsnew/2 5 new-25-context-managers}@anchor{17b4}@anchor{whatsnew/2 5 writing-context-managers}@anchor{17b5}
@subsubsection Writing Context Managers


Under the hood, the “@ref{20a,,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{9c6,,__enter__()} and @ref{16a5,,__exit__()}
methods.

@item 
The context manager’s @ref{9c6,,__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 
The code in `BLOCK' is executed.

@item 
If `BLOCK' raises an exception, the @code{__exit__(type, value, traceback)}
is called with the exception details, the same values returned by
@ref{a7a,,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{20a,,with}” statement will
never realize anything went wrong.

@item 
If `BLOCK' didn’t raise an exception,  the @ref{16a5,,__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{9c6,,__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{20a,,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{16a5,,__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{44b,,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 The contextlib module<2>,,Writing Context Managers<2>,PEP 343 The “with” statement<2>
@anchor{whatsnew/2 5 contextlibmod}@anchor{17b6}@anchor{whatsnew/2 5 the-contextlib-module}@anchor{17b7}
@subsubsection The contextlib module


The new @ref{27,,contextlib} module provides some functions and a decorator that
are useful for writing objects for use with the “@ref{20a,,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{d93,,yield} will be executed as the
@ref{9c6,,__enter__()} method, and the value yielded will be the method’s return
value that will get bound to the variable in the “@ref{20a,,with}” statement’s
@code{as} clause, if any.  The code after the @code{yield} will be
executed in the @ref{16a5,,__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{27,,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{20a,,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 Δείτε επίσης



@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{20a,,with}” statement, which can be helpful in learning how the statement
works.
@end table

The documentation  for the @ref{27,,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>,What’s New in Python 2 5
@anchor{whatsnew/2 5 pep-352}@anchor{17b8}@anchor{whatsnew/2 5 pep-352-exceptions-as-new-style-classes}@anchor{17b9}
@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{d9e,,Exception} class and all the standard built-in exceptions
(@ref{665,,NameError}, @ref{277,,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{d96,,KeyboardInterrupt} and @ref{10f7,,SystemExit}
aren’t errors, though, and usually represent an explicit action such as the user
hitting @code{Control}-@code{C} or code calling @ref{4ff,,sys.exit()}.  A bare @code{except:} will
catch all exceptions, so you commonly need to list @code{KeyboardInterrupt} and
@code{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{d96,,KeyboardInterrupt} and @ref{10f7,,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{9b9,,BaseException} or some descendant of @code{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{d9e,,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 Δείτε επίσης



@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,What’s New in Python 2 5
@anchor{whatsnew/2 5 pep-353}@anchor{17ba}@anchor{whatsnew/2 5 pep-353-using-ssize-t-as-the-index-type}@anchor{17bb}
@subsection PEP 353: Using ssize_t as the index type


A wide-ranging change to Python’s C API, using a new  @ref{e24,,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{19b,,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{e24,,Py_ssize_t} to store their size.   Functions such as
@ref{17bc,,PyList_Size()}  now return @code{Py_ssize_t}.  Code in extension modules
may therefore need to have some variables changed to @code{Py_ssize_t}.

The @ref{3b1,,PyArg_ParseTuple()} and @ref{5ee,,Py_BuildValue()} functions have a new
conversion code, @code{n}, for @ref{e24,,Py_ssize_t}.   @code{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 @code{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 Δείτε επίσης



@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,Other Language Changes<16>,PEP 353 Using ssize_t as the index type,What’s New in Python 2 5
@anchor{whatsnew/2 5 pep-357}@anchor{17bd}@anchor{whatsnew/2 5 pep-357-the-index-method}@anchor{17be}
@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{291,,TypeError} if this requirement isn’t met.

A corresponding @ref{17bf,,nb_index} slot was added to the C-level
@ref{17c0,,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 Δείτε επίσης



@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 Other Language Changes<16>,New Improved and Removed Modules,PEP 357 The “__index__” method,What’s New in Python 2 5
@anchor{whatsnew/2 5 other-lang}@anchor{17c1}@anchor{whatsnew/2 5 other-language-changes}@anchor{17c2}
@subsection Other Language Changes


Here are all of the changes that Python 2.5 makes to the core Python language.


@itemize *

@item 
The @ref{188,,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{1e,,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”.

Some examples:

@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{12b9,,min()} and @ref{12ba,,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; @code{min()}/@code{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{17c3,,any()} and @ref{17c4,,all()}, evaluate whether an
iterator contains any true or false values.  @code{any()} returns @ref{fcc,,True}
if any value returned by the iterator is true; otherwise it will return
@ref{ef5,,False}.  @code{all()} returns @code{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{17c5,,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{17c6,,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{dd7,,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
@code{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{17c6,,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{17c7,,-v} switch to
log all the paths searched. In Python 2.5, a new @ref{907,,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{1c0,,-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
* Interactive Interpreter Changes:: 
* Optimizations: Optimizations<18>. 

@end menu

@node Interactive Interpreter Changes,Optimizations<18>,,Other Language Changes<16>
@anchor{whatsnew/2 5 interactive}@anchor{17c8}@anchor{whatsnew/2 5 interactive-interpreter-changes}@anchor{17c9}
@subsubsection Interactive Interpreter Changes


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{9e7,,--help}
and @ref{10d5,,--version}; on Windows,  it also accepts the @ref{17ca,,/?} option
for displaying a help message. (Implemented by Georg Brandl.)

@c ======================================================================

@node Optimizations<18>,,Interactive Interpreter Changes,Other Language Changes<16>
@anchor{whatsnew/2 5 optimizations}@anchor{17cb}@anchor{whatsnew/2 5 opts}@anchor{17cc}
@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{42b,,set} and
@ref{9d4,,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{c2,,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{277,,ValueError} from the @code{read*()} method.
(Implemented by Thomas Wouters.)

@c Patch 1397960

@item 
The @ref{de,,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{c1,,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 New Improved and Removed Modules,Build and C API Changes<10>,Other Language Changes<16>,What’s New in Python 2 5
@anchor{whatsnew/2 5 modules}@anchor{17cd}@anchor{whatsnew/2 5 new-improved-and-removed-modules}@anchor{17ce}
@subsection New, Improved, and Removed Modules


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{1c,,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 @code{codecs} module
documentation for details. (Designed and implemented by Walter Dörwald.)

@c Patch  1436130

@item 
The @ref{1e,,collections} module gained a new type, @code{defaultdict}, that
subclasses the standard @ref{188,,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{4d9,,list()} or @ref{326,,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

(Contributed by Guido van Rossum.)

@item 
The @code{deque} double-ended queue type supplied by the @ref{1e,,collections}
module now has a @code{remove(value)} method that removes the first occurrence
of `value' in the queue, raising @ref{277,,ValueError} if the value isn’t found.
(Contributed by Raymond Hettinger.)

@item 
New module: The @ref{27,,contextlib} module contains helper functions for use
with the new “@ref{20a,,with}” statement.  See section @ref{17b6,,The contextlib module}
for more about this module.

@item 
New module: The @code{cProfile} module is a C implementation of  the existing
@code{profile} module that has much lower overhead. The module’s interface is
the same as @code{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
@code{profile} module’s interface, will continue to be maintained in future
versions of Python.  (Contributed by Armin Rigo.)

Also, the @ref{b8,,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{2c,,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{6e7,,datetime} class in the @ref{33,,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{17cf,,time.strptime()} and
@ref{1592,,time.strftime()}:

@example
import datetime as dt

ts = dt.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{3a,,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{3d,,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{3e,,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{5e,,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{167d,,input()} function to allow opening files in binary or @ref{10f1,,universal newlines} mode.  Another new parameter, `openhook', lets you use a function
other than @ref{32b,,open()}  to open the input files.  Once you’re iterating over
the set of files, the @code{FileInput} object’s new @ref{17d0,,fileno()} returns
the file descriptor for the currently opened file. (Contributed by Georg
Brandl.)

@item 
In the @ref{63,,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{44f,,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{6c,,heapq}
module  now support a @code{key} keyword parameter similar to the one provided by
the @ref{12b9,,min()}/@ref{12ba,,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{f09,,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{439,,format()} function in the @ref{89,,locale} module has been modified and
two new functions were added, @code{format_string()} and @code{currency()}.

The @ref{439,,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{439,,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{8e,,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{a3,,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{a4,,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{a5,,os} module underwent several changes.  The @code{stat_float_times}
variable now defaults to true, meaning that @ref{4f5,,os.stat()} will now return time
values as floats.  (This doesn’t necessarily mean that @code{os.stat()} will
return times that are precise to fractions of a second; not all systems support
such precision.)

Constants named @ref{1632,,os.SEEK_SET}, @ref{1633,,os.SEEK_CUR}, and
@ref{1634,,os.SEEK_END} have been added; these are the parameters to the
@ref{14c3,,os.lseek()} function.  Two new constants for locking are
@ref{17d1,,os.O_SHLOCK} and @ref{17d2,,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{17d3,,resource.getrusage()} function. @code{wait4(pid)} does take a process ID.
(Contributed by Chad J. Schroeder.)

On FreeBSD, the @ref{4f5,,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{aa,,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{ab,,pickle} and @code{cPickle} modules no longer accept a return value
of @code{None} from the @ref{d97,,__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{ae,,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{1738,,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{c5,,rlcompleter} module is no longer  dependent on importing the
@ref{c2,,readline} module and therefore now works on non-Unix platforms. (Patch
from Robert Kiendl.)

@c Patch #1472854

@item 
The @ref{138,,SimpleXMLRPCServer} and @code{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{d4,,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{de,,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{c1,,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{17d4,,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{17d5,,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{e7,,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{f6,,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{10e,,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{17d6,,unicodedata.ucd_3_2_0}.

@item 
New module: the  @ref{119,,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{11d,,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{11e,,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{32b,,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{137,,xmlrpclib} module now supports returning  @ref{6e7,,datetime} objects
for the XML-RPC date type.  Supply  @code{use_datetime=True} to the @ref{17d7,,loads()}
function or the @code{Unmarshaller} class to enable this feature. (Contributed
by Skip Montanaro.)

@c Patch 1120353

@item 
The @ref{13a,,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{13c,,zlib} module’s @code{Compress} and @code{Decompress} objects now
support a @ref{29,,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,,New Improved and Removed Modules
@anchor{whatsnew/2 5 module-ctypes}@anchor{17d8}@anchor{whatsnew/2 5 the-ctypes-package}@anchor{17d9}
@subsubsection The ctypes package


The @ref{2d,,ctypes} package, written by Thomas Heller, has been added  to the
standard library.  @code{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 @code{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{2d,,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{486,,py_object} type
constructor that will create a  @ref{19b,,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{486,,py_object()}; if it’s omitted you end  up with a
segmentation fault.

@ref{2d,,ctypes} has been around for a while, but people still write  and
distribution hand-coded extension modules because you can’t rely on
@code{ctypes} being present. Perhaps developers will begin to write  Python
wrappers atop a library accessed through @code{ctypes} instead of extension
modules, now that @code{ctypes} is included with core Python.


@subsubheading Δείτε επίσης



@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{2d,,ctypes} module.


@c ======================================================================

@node The ElementTree package,The hashlib package,The ctypes package,New Improved and Removed Modules
@anchor{whatsnew/2 5 module-etree}@anchor{17da}@anchor{whatsnew/2 5 the-elementtree-package}@anchor{17db}
@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

Operation

@tab

Result

@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

Deletes attribute `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 Δείτε επίσης



@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,New Improved and Removed Modules
@anchor{whatsnew/2 5 module-hashlib}@anchor{17dc}@anchor{whatsnew/2 5 the-hashlib-package}@anchor{17dd}
@subsubsection The hashlib package


A new @ref{6b,,hashlib} module, written by Gregory P. Smith,  has been added to
replace the @code{md5} and @code{sha} modules.  @code{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{29,,copy()} returns a new hashing object
with the same digest state.


@subsubheading Δείτε επίσης


The documentation  for the @ref{6b,,hashlib} module.


@c ======================================================================

@node The sqlite3 package,The wsgiref package,The hashlib package,New Improved and Removed Modules
@anchor{whatsnew/2 5 module-sqlite}@anchor{17de}@anchor{whatsnew/2 5 the-sqlite3-package}@anchor{17df}
@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{d7,,sqlite3}.

SQLite is a C library that provides a lightweight disk-based database that
doesn’t require a separate server process and allows accessing the database
using a nonstandard variant of the SQL query language. Some applications can use
SQLite for internal data storage.  It’s also possible to prototype an
application using SQLite and then port the code to a larger database such as
PostgreSQL or 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

You can also supply the special name @code{:memory:} to create a database in RAM.

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.

This example uses the iterator form:

@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 Δείτε επίσης



@table @asis

@item @indicateurl{https://www.pysqlite.org}

The pysqlite web page.

@item @indicateurl{https://www.sqlite.org}

The SQLite web page; the documentation describes the syntax and the available
data types for the supported SQL dialect.
@end table

The documentation  for the @ref{d7,,sqlite3} module.


@table @asis

@geindex Python Enhancement Proposals; PEP 249

@item PEP 249@footnote{https://peps.python.org/pep-0249/} - Database API Specification 2.0

PEP written by Marc-André Lemburg.
@end table


@c ======================================================================

@node The wsgiref package,,The sqlite3 package,New Improved and Removed Modules
@anchor{whatsnew/2 5 module-wsgiref}@anchor{17e0}@anchor{whatsnew/2 5 the-wsgiref-package}@anchor{17e1}
@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{121,,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 Δείτε επίσης



@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>,Porting to Python 2 5,New Improved and Removed Modules,What’s New in Python 2 5
@anchor{whatsnew/2 5 build-and-c-api-changes}@anchor{17e2}@anchor{whatsnew/2 5 build-api}@anchor{17e3}
@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{e24,,Py_ssize_t} type definition instead of
int.  See the earlier section @ref{17ba,,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{1c8,,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{1024,,PyMem_Malloc()},
@ref{13da,,PyMem_Realloc()}, and @ref{17e4,,PyMem_Free()} are one family that allocates
raw memory, while @ref{1026,,PyObject_Malloc()}, @ref{17e5,,PyObject_Realloc()}, and
@ref{1023,,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{17e6,,PySet_New()}
and @ref{17e7,,PyFrozenSet_New()} to create a new set, @ref{17e8,,PySet_Add()} and
@ref{17e9,,PySet_Discard()} to add and remove elements, and @ref{17ea,,PySet_Contains()}
and @ref{17eb,,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{17d4,,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.
@ref{17ec,,Py_LOCAL} declares the function as returning a value of the
specified `type' and uses a fast-calling qualifier.
@ref{17ed,,Py_LOCAL_INLINE} 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{17ee,,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{17ef}@anchor{whatsnew/2 5 ports}@anchor{17f0}
@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 Porting to Python 2 5,Acknowledgements<3>,Build and C API Changes<10>,What’s New in Python 2 5
@anchor{whatsnew/2 5 porting}@anchor{17f1}@anchor{whatsnew/2 5 porting-to-python-2-5}@anchor{17f2}
@subsection Porting to 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{17a6,,PEP 342; New Generator Features},
it’s now possible for @code{gi_frame} to be @code{None}.

@item 
A new warning, @ref{17c6,,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{dd7,,UnicodeDecodeError} exception.

@item 
Library: the @ref{2c,,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{89,,locale} module’s  @ref{439,,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{ab,,pickle} and @code{cPickle} modules no longer accept a
return value of @code{None} from the @ref{d97,,__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{138,,SimpleXMLRPCServer} and @code{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{e24,,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{17ba,,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 Acknowledgements<3>,,Porting to Python 2 5,What’s New in Python 2 5
@anchor{whatsnew/2 5 acknowledgements}@anchor{17f3}
@subsection Acknowledgements


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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New in Python 2 4,What’s New in Python 2 3,What’s New in Python 2 5,Τι νέο υπάρχει στην Python
@anchor{whatsnew/2 4 doc}@anchor{17f4}@anchor{whatsnew/2 4 translation-repo}@anchor{17f5}@anchor{whatsnew/2 4 what-s-new-in-python-2-4}@anchor{17f6}
@section What’s New in Python 2.4


@*Author: 
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. 
* Other Language Changes: Other Language Changes<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>. 
* Porting to Python 2.4: Porting to Python 2 4. 
* Acknowledgements: Acknowledgements<4>. 

@end menu

@node PEP 218 Built-In Set Objects,PEP 237 Unifying Long Integers and Integers,,What’s New in Python 2 4
@anchor{whatsnew/2 4 pep-218-built-in-set-objects}@anchor{17f7}
@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{9d4,,frozenset()} type is an immutable version of @ref{42b,,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 Δείτε επίσης



@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,What’s New in Python 2 4
@anchor{whatsnew/2 4 pep-237-unifying-long-integers-and-integers}@anchor{17f8}
@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{847,,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 Δείτε επίσης



@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,What’s New in Python 2 4
@anchor{whatsnew/2 4 pep-289-generator-expressions}@anchor{17f9}
@subsection PEP 289: Generator Expressions


The iterator feature introduced in Python 2.2 and the @ref{84,,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 Δείτε επίσης



@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,What’s New in Python 2 4
@anchor{whatsnew/2 4 pep-292-simpler-string-substitutions}@anchor{17fa}
@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{277,,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{db,,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{7df,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 292

@item PEP 292@footnote{https://peps.python.org/pep-0292/} - Simpler String Substitutions

Written and implemented  by Barry Warsaw.
@end table


@c ======================================================================

@node PEP 318 Decorators for Functions and Methods,PEP 322 Reverse Iteration,PEP 292 Simpler String Substitutions,What’s New in Python 2 4
@anchor{whatsnew/2 4 pep-318-decorators-for-functions-and-methods}@anchor{17fb}
@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{17fc,,def} statement
in the usual way, and pass the resulting method to a @ref{666,,staticmethod()} or
@ref{69a,,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{69a,,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{69a,,classmethod()}, @ref{666,,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{1679,,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 Δείτε επίσης



@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,What’s New in Python 2 4
@anchor{whatsnew/2 4 pep-322-reverse-iteration}@anchor{17fd}
@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{c3c,,reversed()} is
easier to read, runs faster, and uses substantially less memory.

Note that @ref{c3c,,reversed()} only accepts sequences, not arbitrary iterators.  If
you want to reverse an iterator, first convert it to  a list with @ref{4d9,,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 Δείτε επίσης



@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,What’s New in Python 2 4
@anchor{whatsnew/2 4 pep-324-new-subprocess-module}@anchor{17fe}
@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{df,,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{df,,subprocess} contains a
single class called @ref{6bf,,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{17ff,,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{10f1,,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{17ff,,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{df,,subprocess}.  Reading this section
of the PEP is highly recommended.


@subsubheading Δείτε επίσης



@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,What’s New in Python 2 4
@anchor{whatsnew/2 4 pep-327-decimal-data-type}@anchor{1800}
@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{1801}
@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{1802}
@subsubsection The @code{Decimal} type


A new module, @ref{39,,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{91,,math} and @ref{19,,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{1803}
@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{39,,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{39,,decimal} module, which
includes a quick-start tutorial and a reference.


@subsubheading Δείτε επίσης



@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,What’s New in Python 2 4
@anchor{whatsnew/2 4 pep-328-multi-line-imports}@anchor{1804}
@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{9da,,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 Δείτε επίσης



@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,Other Language Changes<17>,PEP 328 Multi-line Imports,What’s New in Python 2 4
@anchor{whatsnew/2 4 pep-331-locale-independent-float-string-conversions}@anchor{1805}
@subsection PEP 331: Locale-Independent Float/String Conversions


The @ref{89,,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{89,,locale} module  can now change the numeric locale,
letting extensions such as GTK+  produce the correct results.


@subsubheading Δείτε επίσης



@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 Other Language Changes<17>,New Improved and Deprecated Modules<3>,PEP 331 Locale-Independent Float/String Conversions,What’s New in Python 2 4
@anchor{whatsnew/2 4 other-language-changes}@anchor{1806}
@subsection Other Language Changes


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{42b,,set()} and @ref{9d4,,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{1807,,dict.update()} method now accepts the same argument forms as the
@ref{188,,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{1642,,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{f8d,,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{4ca,,-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{43f,,zip()} built-in function and @code{itertools.izip()} now return an
empty list if called with no arguments. Previously they raised a
@ref{291,,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{a65,,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<19>. 

@end menu

@node Optimizations<19>,,,Other Language Changes<17>
@anchor{whatsnew/2 4 optimizations}@anchor{1808}
@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.   @ref{7f8,,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{4d9,,list()}, @ref{1ce,,tuple()}, @ref{43e,,map()}, @ref{c3b,,filter()}, and @ref{43f,,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>,Other Language Changes<17>,What’s New in Python 2 4
@anchor{whatsnew/2 4 new-improved-and-deprecated-modules}@anchor{1809}
@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{f,,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{12,,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 
Chinese (PRC): gb2312, gbk, gb18030, big5hkscs, hz

@item 
Chinese (ROC): big5, cp950

@item 

@table @asis

@item Japanese: 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 
Korean: cp949, euc-kr, johab, iso-2022-kr

@item 
Some other new encodings were added: HP Roman8,  ISO_8859-11, ISO_8859-16,
PCTP-154, and 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{1e,,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{f6,,threading} modules, now take
advantage of @ref{9d6,,collections.deque} for improved performance.  (Contributed
by Raymond Hettinger.)

@item 
The @ref{26,,ConfigParser} classes have been enhanced slightly. The @ref{180a,,read()}
method now returns a list of the files that were successfully parsed, and the
@ref{1611,,set()} method raises @ref{291,,TypeError} if passed a `value' argument that
isn’t a string.   (Contributed by John Belmonte and David Goodger.)

@item 
The @ref{2e,,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{3a,,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{3e,,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{6c,,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{71,,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{77,,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{84,,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

(Contributed by Hye-Shik Chang.)

@item 
@ref{84,,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{4d9,,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{89,,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{8a,,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{8a,,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.

(Changes implemented by Vinay Sajip.)

@item 
The @ref{90,,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{a3,,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{43e,,map()}
or @ref{f8c,,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{a4,,optparse} module was updated in various ways.  The module now passes
its messages through @ref{180b,,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{3e,,email} package. To this end, the
@ref{180c,,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{a5,,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{b2,,posix} module that
underlies the @ref{a5,,os} module. (Contributed by J. Raynor.)

@item 
The @ref{b1,,poplib} module now supports POP over SSL.  (Contributed by Hector
Urtubia.)

@item 
The @ref{b4,,profile} module can now profile C extension functions. (Contributed
by Nick Bastin.)

@item 
The @ref{c0,,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{c1,,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{c1,,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{30d,,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{ce,,signal} module now performs tighter error-checking on the parameters
to the @ref{14e0,,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{30d,,RuntimeError} exception.

@item 
Two new functions were added to the @ref{d4,,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{d,,atexit} module, which correctly handles calling multiple exit
functions.  Eventually @code{sys.exitfunc()} will become a purely internal
interface, accessed only by @code{atexit}.

@item 
The @ref{e7,,tarfile} module now generates GNU-format tar files by default.
(Contributed by Lars Gustäbel.)

@item 
The @ref{f6,,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{f8,,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{11d,,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{137,,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{180d}
@subsubsection cookielib


The @ref{73,,cookielib} library supports client-side handling for HTTP cookies,
mirroring the @ref{74,,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{114,,urllib2} has been changed to interact with @ref{73,,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{180e}
@subsubsection doctest


The @ref{3d,,doctest} module underwent considerable refactoring thanks to Edward
Loper and Tim Peters.  Testing can still be as simple as running
@ref{180f,,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{1810,,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{1811,,doctest.REPORT_UDIFF} (unified diffs),
@ref{1812,,doctest.REPORT_CDIFF} (context diffs), or @ref{1813,,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{1811,,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>,Porting to Python 2 4,New Improved and Deprecated Modules<3>,What’s New in Python 2 4
@anchor{whatsnew/2 4 build-and-c-api-changes}@anchor{1814}
@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{1815,,Py_RETURN_NONE}, @ref{1816,,Py_RETURN_TRUE}, and
@ref{1817,,Py_RETURN_FALSE}. (Contributed by Brett Cannon.)

@item 
Another new macro, @ref{97c,,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 @ref{1818,,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{819,,PyArg_VaParseTupleAndKeywords()}, is the same as
@ref{818,,PyArg_ParseTupleAndKeywords()} but takes a  @code{va_list} instead of a
number of arguments. (Contributed by Greg Chapman.)

@item 
A new method flag, @ref{1819,,METH_COEXIST}, allows a function defined in slots
to co-exist with a @ref{181a,,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{181b}
@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 Porting to Python 2 4,Acknowledgements<4>,Build and C API Changes<11>,What’s New in Python 2 4
@anchor{whatsnew/2 4 porting-to-python-2-4}@anchor{181c}
@subsection Porting to 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{847,,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{43f,,zip()} built-in function and @code{itertools.izip()} now return  an
empty list instead of raising a @ref{291,,TypeError} exception if called with no
arguments.

@item 
You can no longer compare the @code{date} and @ref{6e7,,datetime} instances
provided by the @ref{33,,datetime} module.  Two  instances of different classes
will now always be unequal, and  relative comparisons (@code{<}, @code{>}) will raise
a @ref{291,,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{181d,,fcntl.ioctl()} now warns if the `mutate'  argument is omitted and
relevant.

@item 
The @ref{e7,,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{a65,,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{30d,,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 Acknowledgements<4>,,Porting to Python 2 4,What’s New in Python 2 4
@anchor{whatsnew/2 4 acknowledgements}@anchor{181e}@anchor{whatsnew/2 4 acks}@anchor{181f}
@subsection Acknowledgements


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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New in Python 2 3,What’s New in Python 2 2,What’s New in Python 2 4,Τι νέο υπάρχει στην Python
@anchor{whatsnew/2 3 doc}@anchor{1820}@anchor{whatsnew/2 3 translation-repo}@anchor{1821}@anchor{whatsnew/2 3 what-s-new-in-python-2-3}@anchor{1822}
@section What’s New in Python 2.3


@*Author: 
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{881,,sum()} and @ref{1823,,enumerate()}.  The @ref{323,,in}
operator can now be used for substring searches (e.g. @code{"ab" in "abc"} returns
@ref{fcc,,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; Simple Generators: PEP 255 Simple Generators. 
* 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; A Boolean Type: PEP 285 A Boolean Type. 
* 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:: 
* Other Language Changes: Other Language Changes<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>. 
* Other Changes and Fixes: Other Changes and Fixes<2>. 
* Porting to Python 2.3: Porting to Python 2 3. 
* Acknowledgements: Acknowledgements<5>. 

@end menu

@node PEP 218 A Standard Set Datatype,PEP 255 Simple Generators,,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-218-a-standard-set-datatype}@anchor{1824}
@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{1825,,union()} and
@ref{1826,,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{1827,,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{1828,,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 Δείτε επίσης



@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 Simple Generators,PEP 263 Source Code Encodings,PEP 218 A Standard Set Datatype,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-255-simple-generators}@anchor{1829}@anchor{whatsnew/2 3 section-generators}@anchor{182a}
@subsection PEP 255: Simple Generators


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{d93,,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{44b,,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{d93,,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{d93,,yield} statement, the generator outputs the value of @code{i},
similar to a @ref{44b,,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{ad6,,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{44b,,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{fba,,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{bb5,,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{322,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 255

@item PEP 255@footnote{https://peps.python.org/pep-0255/} - Simple Generators

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 Simple Generators,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-263-source-code-encodings}@anchor{182b}@anchor{whatsnew/2 3 section-encodings}@anchor{182c}
@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{2c9,,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 Δείτε επίσης



@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,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-273-importing-modules-from-zip-archives}@anchor{182d}
@subsection PEP 273: Importing Modules from ZIP Archives


The new @ref{13b,,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 Δείτε επίσης



@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{182e,,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,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-277-unicode-file-name-support-for-windows-nt}@anchor{182f}
@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{32b,,open()} built-in function. If a Unicode string is passed to
@ref{14a6,,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{675,,UnicodeError}
to be raised. Applications can test whether arbitrary Unicode strings are
supported as file names by checking @ref{1830,,os.path.supports_unicode_filenames},
a Boolean value.

Under MacOS, @ref{14a6,,os.listdir()} may now return Unicode filenames.


@subsubheading Δείτε επίσης



@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,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-278-universal-newline-support}@anchor{1831}
@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{10f1,,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 Δείτε επίσης



@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,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-279-enumerate}@anchor{1832}@anchor{whatsnew/2 3 section-enumerate}@anchor{1833}
@subsection PEP 279: enumerate()


A new built-in function, @ref{1823,,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{1823,,enumerate()} as:

@example
for i, item in enumerate(L):
    # ... compute some result based on item ...
    L[i] = result
@end example


@subsubheading Δείτε επίσης



@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 A Boolean Type,PEP 279 enumerate,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-282-the-logging-package}@anchor{1834}
@subsection PEP 282: The logging Package


A standard package for writing logs, @ref{8a,,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{f0c,,Logger} class is the primary class. Most application code will deal
with one or more @code{Logger} objects, each one used by a particular
subsystem of the application. Each @code{Logger} is identified by a name, and
names are organized into a hierarchy using @code{.}  as the component separator.
For example, you might have @code{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 @code{Logger} that’s the parent of all other loggers.

For simple uses, the @ref{8a,,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

This produces the following output:

@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{1835,,setLevel()} method
on the root logger.

Notice the @ref{331,,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{1836,,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

This produces the following output:

@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{f0c,,Logger}
can prevent this by setting its @ref{1837,,propagate} attribute to @ref{ef5,,False}.

There are more classes provided by the @ref{8a,,logging} package that can be
customized.  When a @ref{f0c,,Logger} instance is told to log a message, it
creates a @ref{138f,,LogRecord} instance that is sent to any number of different
@ref{1838,,Handler} instances.  Loggers and handlers can also have an attached list
of filters, and each filter can cause the @code{LogRecord} to be ignored or
can modify the record before passing it along.  When they’re finally output,
@code{LogRecord} instances are converted to text by a @ref{1839,,Formatter}
class.  All of these classes can be replaced by your own specially written
classes.

With all of these features the @ref{8a,,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 Δείτε επίσης



@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 A Boolean Type,PEP 293 Codec Error Handling Callbacks,PEP 282 The logging Package,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-285-a-boolean-type}@anchor{183a}@anchor{whatsnew/2 3 section-bool}@anchor{183b}
@subsection PEP 285: A Boolean Type


A Boolean type was added to Python 2.3.  Two new constants were added to the
@code{__builtin__} module, @ref{fcc,,True} and @ref{ef5,,False}.  (@code{True} and
@code{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{5ef,,bool}; the constructor for it
takes any Python value and converts it to @ref{fcc,,True} or @ref{ef5,,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{322,,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{326,,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{fcc,,True} and @ref{ef5,,False} in a sentence: they’re alternative
ways to spell the integer values 1 and 0, with the single difference that
@ref{1df,,str()} and @ref{45b,,repr()} return the strings @code{'True'} and @code{'False'}
instead of @code{'1'} and @code{'0'}.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 285

@item PEP 285@footnote{https://peps.python.org/pep-0285/} - Adding a bool type

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 A Boolean Type,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-293-codec-error-handling-callbacks}@anchor{183c}
@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{675,,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{183d,,codecs.register_error()}, and codecs then
can access the error handler with @ref{183e,,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 Δείτε επίσης



@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,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-301-package-index-and-metadata-for-distutils}@anchor{183f}@anchor{whatsnew/2 3 section-pep301}@anchor{1840}
@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 Δείτε επίσης



@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,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-302-new-import-hooks}@anchor{1841}@anchor{whatsnew/2 3 section-pep302}@anchor{182e}
@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{e2,,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{1bd,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 302

@item PEP 302@footnote{https://peps.python.org/pep-0302/} - New Import Hooks

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,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-305-comma-separated-files}@anchor{1842}@anchor{whatsnew/2 3 section-pep305}@anchor{1843}
@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{2c,,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{898,,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{899,,csv.writer} class will generate comma-separated files from a succession
of tuples or lists, quoting strings that contain the delimiter.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 305

@item PEP 305@footnote{https://peps.python.org/pep-0305/} - CSV File API

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,What’s New in Python 2 3
@anchor{whatsnew/2 3 pep-307-pickle-enhancements}@anchor{1844}@anchor{whatsnew/2 3 section-pep307}@anchor{1845}
@subsection PEP 307: Pickle Enhancements


The @ref{ab,,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{1846,,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{1847,,pickle.HIGHEST_PROTOCOL}, can be used to select the
fanciest protocol available.

Unpickling is no longer considered a safe operation.  2.2’s @ref{ab,,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{9d3,,__getstate__()}, @ref{d98,,__setstate__()}, and @ref{118d,,__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 Δείτε επίσης



@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,Other Language Changes<18>,PEP 307 Pickle Enhancements,What’s New in Python 2 3
@anchor{whatsnew/2 3 extended-slices}@anchor{1848}@anchor{whatsnew/2 3 section-slices}@anchor{1849}
@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{291,,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{787,,__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{d0f,,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{1d0,,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{326,,int}, @ref{1df,,str}, etc., underwent
the same change.

@c ======================================================================

@node Other Language Changes<18>,New Improved and Deprecated Modules<4>,Extended Slices,What’s New in Python 2 3
@anchor{whatsnew/2 3 other-language-changes}@anchor{184a}
@subsection Other Language Changes


Here are all of the changes that Python 2.3 makes to the core Python language.


@itemize *

@item 
The @ref{d93,,yield} statement is now always a keyword, as described in
section @ref{182a,,PEP 255; Simple Generators} of this document.

@item 
A new built-in function @ref{1823,,enumerate()} was added, as described in section
@ref{1833,,PEP 279; enumerate()} of this document.

@item 
Two new constants, @ref{fcc,,True} and @ref{ef5,,False} were added along with the
built-in @ref{5ef,,bool} type, as described in section @ref{183b,,PEP 285; A Boolean Type} of this
document.

@item 
The @ref{326,,int()} type constructor will now return a long integer instead of
raising an @ref{c57,,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{1849,,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{881,,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{7df,,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{188,,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{d31,,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{431,,-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{10c,,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{c9b,,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{1c0,,-Walways;;PendingDeprecationWarning;;} on the command line or
use @ref{184b,,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{c9b,,PendingDeprecationWarning}.

@item 
Using @code{None} as a variable name will now result in a @ref{44a,,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{184c,,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{184d,,__name__} and @ref{184e,,__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{184f,,__class__} attribute.
@end itemize

@c ======================================================================

@menu
* String Changes:: 
* Optimizations: Optimizations<20>. 

@end menu

@node String Changes,Optimizations<20>,,Other Language Changes<18>
@anchor{whatsnew/2 3 string-changes}@anchor{1850}
@subsubsection String Changes



@itemize *

@item 
The @ref{323,,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{fcc,,True} if `X' is a substring of `Y'.  If `X' is the empty
string, the result is always @code{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{1259,,find()} string method.

@item 
The @ref{1851,,strip()}, @ref{1852,,lstrip()}, and @ref{1853,,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{1279,,startswith()} and @ref{127a,,endswith()} string methods now accept negative
numbers for the `start' and `end' parameters.

@item 
Another new string method is @ref{1854,,zfill()}, originally a function in the
@ref{db,,string} module.  @code{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 @code{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{fcc,,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<20>,,String Changes,Other Language Changes<18>
@anchor{whatsnew/2 3 optimizations}@anchor{1855}
@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{f8d,,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{1856,,Other Changes and Fixes} 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,Other Language Changes<18>,What’s New in Python 2 3
@anchor{whatsnew/2 3 new-improved-and-deprecated-modules}@anchor{1857}
@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{8,,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{14,,bz2} module is an interface to the bz2 data compression library.
bz2-compressed data is usually smaller than  corresponding
@ref{13c,,zlib}-compressed data. (Contributed by Gustavo Niemeyer.)

@item 
A set of standard date/time types has been added in the new @ref{33,,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 μεταβλητή περιβάλλοντος; CC
@ref{1858,,CC},
@geindex CFLAGS
@geindex μεταβλητή περιβάλλοντος; CFLAGS
@ref{1859,,CFLAGS}, @code{CPP}, 
@geindex LDFLAGS
@geindex μεταβλητή περιβάλλοντος; LDFLAGS
@ref{185a,,LDFLAGS}, and 
@geindex CPPFLAGS
@geindex μεταβλητή περιβάλλοντος; CPPFLAGS
@ref{185b,,CPPFLAGS}
environment variables, using them to override the settings in Python’s
configuration (contributed by Robert Weber).

@item 
Previously the @ref{3d,,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{11ac,,DocTestSuite()} function creates a
@ref{11ad,,unittest.TestSuite} object from a set of @code{doctest} tests.

@item 
The new @code{gc.get_referents(object)} function returns a list of all the
objects referenced by `object'.

@item 
The @ref{64,,getopt} module gained a new function, @ref{185c,,gnu_getopt()}, that
supports the same arguments as the existing @ref{185d,,getopt()} function but uses
GNU-style scanning mode. The existing @code{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{69,,grp}, @ref{ba,,pwd}, and @ref{c4,,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{6a,,gzip} module can now handle files exceeding 2 GiB.

@item 
The new @ref{6c,,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{6c,,heapq} module provides @ref{185e,,heappush()} and @ref{185f,,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{76,,idlelib} package.

@item 
The @ref{77,,imaplib} module now supports IMAP over SSL. (Contributed by Piers
Lauder and Tino Lange.)

@item 
The @ref{84,,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{fcc,,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{91,,math} module, @code{degrees(rads)} and
@code{radians(degs)}, convert between radians and degrees.  Other functions in
the @code{math} module such as @ref{1860,,math.sin()} and @ref{1861,,math.cos()} have always
required input values measured in radians.  Also, an optional `base' argument
was added to @ref{1862,,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{b2,,posix} module that underlies the
@ref{a5,,os} module. (Contributed by Gustavo Niemeyer, Geert Jansen, and Denis S.
Otkidach.)

@item 
In the @ref{a5,,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{75e,,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{1863,,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{a4,,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{af,,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{12f,,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{1864,,buffer_text} attribute to @ref{fcc,,True} will enable buffering.

@item 
The @code{sample(population, k)} function was added to the @ref{c0,,random}
module.  `population' is a sequence or @code{xrange} object containing the
elements of a population, and @ref{b2b,,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{c0,,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{c2,,readline} module also gained a number of new functions:
@ref{1865,,get_history_item()}, @ref{1866,,get_current_history_length()}, and
@ref{1867,,redisplay()}.

@item 
The @code{rexec} and @code{Bastion} modules have been declared dead, and
attempts to import them will fail with a @ref{30d,,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{cd,,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{ce,,signal}
but then removed again as it proved impossible to make it work reliably across
platforms.

@item 
The @ref{d4,,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{c0d,,socket.timeout} exception.

The original timeout implementation was by Tim O’Malley.  Michael Gilfix
integrated it into the Python @ref{d4,,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{d4,,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{e7,,tarfile} module  allows reading from and writing to
@code{tar}-format archive files. (Contributed by Lars Gustäbel.)

@item 
The new @ref{f5,,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{1868,,fill()} is built on top of @ref{1869,,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{1376,,TextWrapper} class that actually implements
the text wrapping strategy.   Both the @code{TextWrapper} class and the
@ref{1869,,wrap()} and @ref{1868,,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{f6,,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{f6,,threading}
module. Code can call functions and use classes in @code{_threading} whether or
not threads are supported, avoiding an @ref{322,,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{f7,,time} module’s @ref{17cf,,strptime()} function has long been an annoyance
because it uses the platform C library’s @code{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{f8,,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{186a,,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{cb,,shelve}
module.

Adding the mix-in as a superclass provides the full dictionary interface
whenever the class defines @ref{787,,__getitem__()}, @ref{1670,,__setitem__()},
@ref{1671,,__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{12b,,xml.dom.minidom} can now generate XML output
in a particular encoding by providing an optional encoding argument to the
@ref{e59,,toxml()} and @ref{e5a,,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{d4,,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{61,,ftplib})
also support Unicode host names; @code{httplib} also sends HTTP @code{Host}
headers using the ACE version of the domain name.  @ref{111,,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{dd,,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{186b}
@subsubsection Date/Time Type


Date and time types suitable for expressing timestamps were added as the
@ref{33,,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{48d,,date}, representing a day, month, and year;
@ref{48e,,time}, consisting of hour, minute, and second; and @ref{6e7,,datetime},
which contains all the attributes of both @code{date} and @code{time}.
There’s also a @ref{d94,,timedelta} class representing differences between two
points in time, and time zone logic is implemented by classes inheriting from
the abstract @ref{9d8,,tzinfo} class.

You can create instances of @ref{48d,,date} and @ref{48e,,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{186c,,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 as dt
>>> now = dt.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{186d,,replace()} method allows modifying one or more fields  of a
@ref{48d,,date} or @ref{6e7,,datetime} instance, returning a new instance:

@example
>>> d = dt.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{eef,,isoformat()}).  @ref{48d,,date} and @ref{6e7,,datetime}
instances can be subtracted from each other, and added to @ref{d94,,timedelta}
instances.  The largest missing feature is that there’s no standard library
support for parsing strings and getting back a @code{date} or
@code{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{186e}
@subsubsection The optparse Module


The @ref{64,,getopt} module provides simple parsing of command-line arguments.  The
new @ref{a4,,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{186f,,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{1870,,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>,What’s New in Python 2 3
@anchor{whatsnew/2 3 pymalloc-a-specialized-object-allocator}@anchor{1871}@anchor{whatsnew/2 3 section-pymalloc}@anchor{1872}
@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{1026,,PyObject_Malloc()}, it has to be freed using @ref{1023,,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{1024,,PyMem_Malloc()}, @ref{13da,,PyMem_Realloc()}, and @ref{17e4,,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{1026,,PyObject_Malloc()}, @ref{17e5,,PyObject_Realloc()}, and @ref{1023,,PyObject_Free()}.

@item 
To allocate and free Python objects, use the «object» family
@ref{d4d,,PyObject_New}, @ref{d4e,,PyObject_NewVar}, and @ref{1873,,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 Δείτε επίσης



@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>,Other Changes and Fixes<2>,Pymalloc A Specialized Object Allocator,What’s New in Python 2 3
@anchor{whatsnew/2 3 build-and-c-api-changes}@anchor{1874}
@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{1875,,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{1876,,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 @code{METH_NOARGS}.

@item 
@ref{3b1,,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{1877,,METH_CLASS} or @ref{1878,,METH_STATIC} flags in a
method’s @ref{1879,,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{80b,,__module__} and
@ref{184d,,__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{187a}
@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{5c,,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 Other Changes and Fixes<2>,Porting to Python 2 3,Build and C API Changes<12>,What’s New in Python 2 3
@anchor{whatsnew/2 3 other-changes-and-fixes}@anchor{187b}@anchor{whatsnew/2 3 section-other}@anchor{1856}
@subsection Other Changes and Fixes


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 μεταβλητή περιβάλλοντος; PYTHONINSPECT
@ref{187c,,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{187d,,-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{aa,,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{431,,-O}.

C extensions that access the @ref{b8d,,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{b8d,,f_lineno} attribute of frame objects, changing the line that will be
executed next.  A @code{jump} command has been added to the @ref{aa,,pdb} debugger
taking advantage of this new feature. (Implemented by Richie Hindle.)
@end itemize

@c ======================================================================

@node Porting to Python 2 3,Acknowledgements<5>,Other Changes and Fixes<2>,What’s New in Python 2 3
@anchor{whatsnew/2 3 porting-to-python-2-3}@anchor{187e}
@subsection Porting to Python 2.3


This section lists previously described changes that may require changes to your
code:


@itemize *

@item 
@ref{d93,,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{326,,int()} type constructor will now return a long integer instead of
raising an @ref{c57,,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{182c,,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{847,,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{44a,,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 Acknowledgements<5>,,Porting to Python 2 3,What’s New in Python 2 3
@anchor{whatsnew/2 3 acknowledgements}@anchor{187f}@anchor{whatsnew/2 3 acks}@anchor{1880}
@subsection Acknowledgements


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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New in Python 2 2,What’s New in Python 2 1,What’s New in Python 2 3,Τι νέο υπάρχει στην Python
@anchor{whatsnew/2 2 doc}@anchor{1881}@anchor{whatsnew/2 2 translation-repo}@anchor{1882}@anchor{whatsnew/2 2 what-s-new-in-python-2-2}@anchor{1883}
@section What’s New in Python 2.2


@*Author: 
A.M. Kuchling


@c $Id: whatsnew22.tex 37315 2004-09-10 19:33:00Z akuchling $

@menu
* Introduction:: 
* PEPs 252 and 253; Type and Class Changes: PEPs 252 and 253 Type and Class Changes. 
* PEP 234; Iterators: PEP 234 Iterators. 
* PEP 255; Simple Generators: PEP 255 Simple Generators<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:: 
* Other Changes and Fixes: Other Changes and Fixes<3>. 
* Acknowledgements: Acknowledgements<6>. 

@end menu

@node Introduction,PEPs 252 and 253 Type and Class Changes,,What’s New in Python 2 2
@anchor{whatsnew/2 2 introduction}@anchor{1884}
@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 PEPs 252 and 253 Type and Class Changes,PEP 234 Iterators,Introduction,What’s New in Python 2 2
@anchor{whatsnew/2 2 peps-252-and-253-type-and-class-changes}@anchor{1885}
@subsection PEPs 252 and 253: Type and Class Changes


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{1886,,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{8e3,,__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{1887,,Related Links}, «Related Links», for
further sources of information about Python 2.2’s new object model.

@menu
* Old and New Classes:: 
* Descriptors:: 
* Multiple Inheritance; The Diamond Rule: Multiple Inheritance The Diamond Rule. 
* Attribute Access:: 
* Related Links:: 

@end menu

@node Old and New Classes,Descriptors,,PEPs 252 and 253 Type and Class Changes
@anchor{whatsnew/2 2 old-and-new-classes}@anchor{1888}
@subsubsection Old and New 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{e4d,,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
@code{object}:

@example
class C(object):
    def __init__ (self):
        ...
    ...
@end example

This means that @ref{167c,,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{e4d,,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{326,,int()},
@ref{327,,float()}, and @ref{1df,,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{188,,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 Descriptors,Multiple Inheritance The Diamond Rule,Old and New Classes,PEPs 252 and 253 Type and Class Changes
@anchor{whatsnew/2 2 descriptors}@anchor{1889}
@subsubsection Descriptors


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{1bf,,__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{140e,,__name__} is the attribute’s name.

@item 
@ref{cf4,,__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{188a,,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{666,,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 Multiple Inheritance The Diamond Rule,Attribute Access,Descriptors,PEPs 252 and 253 Type and Class Changes
@anchor{whatsnew/2 2 multiple-inheritance-the-diamond-rule}@anchor{188b}
@subsubsection Multiple Inheritance: The Diamond Rule


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{443,,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{443,,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,Multiple Inheritance The Diamond Rule,PEPs 252 and 253 Type and Class Changes
@anchor{whatsnew/2 2 attribute-access}@anchor{188c}
@subsubsection Attribute Access


A fair number of sophisticated Python classes define hooks for attribute access
using @ref{8e3,,__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{f90,,__getattribute__()} is `always' called whenever any attribute is
accessed, while the old @ref{8e3,,__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{1bf,,__dict__}. @ref{8e3,,__getattr__()} methods also end up being called by Python
when it checks for other methods such as @ref{1bc,,__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{6bb,,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{1bf,,__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{188d,,__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 @code{__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{1a9,,AttributeError} on the attempt to assign to an
attribute not listed in @ref{188d,,__slots__}.

@node Related Links,,Attribute Access,PEPs 252 and 253 Type and Class Changes
@anchor{whatsnew/2 2 related-links}@anchor{188e}@anchor{whatsnew/2 2 sect-rellinks}@anchor{1887}
@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{188f,,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 Iterators,PEP 255 Simple Generators<2>,PEPs 252 and 253 Type and Class Changes,What’s New in Python 2 2
@anchor{whatsnew/2 2 pep-234-iterators}@anchor{1890}
@subsection PEP 234: Iterators


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{787,,__getitem__()} method that looks something like this:

@example
def __getitem__(self, index):
    return <next item>
@end example

@ref{787,,__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{321,,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 @code{__getitem__()} calls will be made with `index' incrementing by
one each time.  In other words, the presence of the @code{__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{787,,__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{1891,,tp_iter}
function in order to return an iterator, and extension types that want to behave
as iterators can define a @ref{1892,,tp_iternext} function.

So, after all this, what do iterators actually do?  They have one required
method, @ref{bb5,,next()}, which takes no arguments and returns the next value.  When
there are no more values to be returned, calling @code{next()} should raise the
@ref{fba,,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{321,,for} statement no longer expects a sequence; it
expects something for which @ref{bb4,,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{1891,,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{bb4,,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{323,,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{c2,,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{bb5,,next()} method.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 234

@item PEP 234@footnote{https://peps.python.org/pep-0234/} - Iterators

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 Simple Generators<2>,PEP 237 Unifying Long Integers and Integers<2>,PEP 234 Iterators,What’s New in Python 2 2
@anchor{whatsnew/2 2 pep-255-simple-generators}@anchor{1893}
@subsection PEP 255: Simple Generators


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{44b,,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{d93,,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{d93,,yield} statement, the generator outputs the value of @code{i},
similar to a @ref{44b,,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{ad6,,try}…@ref{44c,,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{44b,,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{fba,,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{bb5,,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{322,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 255

@item PEP 255@footnote{https://peps.python.org/pep-0255/} - Simple Generators

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 Simple Generators<2>,What’s New in Python 2 2
@anchor{whatsnew/2 2 pep-237-unifying-long-integers-and-integers}@anchor{1894}
@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{291,,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{c57,,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{186,,type()} built-in function, but that’s
rarely needed.


@subsubheading Δείτε επίσης



@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>,What’s New in Python 2 2
@anchor{whatsnew/2 2 pep-238-changing-the-division-operator}@anchor{1895}
@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{1241,,__truediv__()} and @ref{1896,,__floordiv__()}
to overload the two division operators.  At the C level, there are also slots in
the @ref{17c0,,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 Δείτε επίσης



@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,What’s New in Python 2 2
@anchor{whatsnew/2 2 unicode-changes}@anchor{1897}
@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{277,,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{13c,,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 Δείτε επίσης



@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,What’s New in Python 2 2
@anchor{whatsnew/2 2 pep-227-nested-scopes}@anchor{1898}
@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{665,,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{1642,,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{17fc,,def}, @ref{167c,,class}, or @ref{9da,,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{1642,,lambda} expressions with free variables, the compiler
will flag this by raising a @ref{17e,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 227

@item PEP 227@footnote{https://peps.python.org/pep-0227/} - Statically Nested Scopes

Written and implemented by Jeremy Hylton.
@end table


@c ======================================================================

@node New and Improved Modules<3>,Interpreter Changes and Fixes,PEP 227 Nested Scopes,What’s New in Python 2 2
@anchor{whatsnew/2 2 new-and-improved-modules}@anchor{1899}
@subsection New and Improved Modules



@itemize *

@item 
The @ref{137,,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{138,,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{6d,,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{189a,,tm_year}. The enhanced functions include
@ref{4f5,,stat()}, @ref{1145,,fstat()}, @ref{14a8,,statvfs()}, and @ref{1146,,fstatvfs()} in the
@ref{a5,,os} module, and @ref{189b,,localtime()}, @ref{1569,,gmtime()}, and @ref{17cf,,strptime()} in
the @ref{f7,,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{d4,,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{de,,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{ca9,,help()} that uses the @ref{bd,,pydoc} module introduced in Python 2.1 to
provide interactive help. @code{help(object)} displays any available help text
about `object'.  @code{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
@code{pydoc} module.)

@item 
Various bugfixes and performance improvements have been made to the SRE engine
underlying the @ref{c1,,re} module.  For example, the @ref{7a1,,re.sub()} and
@ref{7a0,,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{189c,,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{d2,,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.  @code{smtplib} also supports SMTP
authentication.  (Contributed by Gerhard Häring.)

@item 
The @ref{77,,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{3e,,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{3a,,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{db,,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{93,,mimetypes} module now makes it easier to use alternative MIME-type
databases by the addition of a @ref{189d,,MimeTypes} class, which takes a list of
filenames to be parsed.  (Contributed by Fred L. Drake, Jr.)

@item 
A @ref{1504,,Timer} class was added to the @ref{f6,,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,Other Changes and Fixes<3>,New and Improved Modules<3>,What’s New in Python 2 2
@anchor{whatsnew/2 2 interpreter-changes-and-fixes}@anchor{189e}
@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{189f,,PyEval_SetProfile()} and @ref{850,,PyEval_SetTrace()}. The existing
@ref{18a0,,sys.setprofile()} and @ref{55c,,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{18a1,,PyInterpreterState_Head()} and
@ref{18a2,,PyInterpreterState_Next()} let a caller walk through all the existing
interpreter objects; @ref{18a3,,PyInterpreterState_ThreadHead()} and
@ref{18a4,,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{39e,,Py_TPFLAGS_HAVE_GC}.

@item 

@table @asis

@item Use @ref{e68,,PyObject_GC_New()} or @ref{e69,,PyObject_GC_NewVar()} to allocate

objects, and @ref{18a5,,PyObject_GC_Del()} to deallocate them.
@end table

@item 
Rename @code{PyObject_GC_Init()} to @ref{18a6,,PyObject_GC_Track()} and
@code{PyObject_GC_Fini()} to @ref{18a7,,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{3b1,,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{18a8,,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{19b,,PyObject}* variables that will be
filled in with argument values.

@item 
Two new flags @ref{1876,,METH_NOARGS} and @ref{18a9,,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{18aa,,METH_VARARGS}.  Also, the old
@code{METH_OLDARGS} style of writing C methods is  now officially deprecated.

@item 
Two new wrapper functions, @ref{18ab,,PyOS_snprintf()} and @ref{18ac,,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{18ad,,_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 Other Changes and Fixes<3>,Acknowledgements<6>,Interpreter Changes and Fixes,What’s New in Python 2 2
@anchor{whatsnew/2 2 other-changes-and-fixes}@anchor{18ae}
@subsection Other Changes and Fixes


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{291,,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{18af,,ReferenceError} exception has therefore moved from the @ref{11d,,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{1c8,,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{323,,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{18b0,,sys.getdlopenflags()} and @ref{14cb,,sys.setdlopenflags()} functions.
(Contributed by Bram Stolk.)

@item 
The @ref{441,,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{291,,TypeError} exception.
@end itemize

@c ======================================================================

@node Acknowledgements<6>,,Other Changes and Fixes<3>,What’s New in Python 2 2
@anchor{whatsnew/2 2 acknowledgements}@anchor{18b1}
@subsection Acknowledgements


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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New in Python 2 1,What’s New in Python 2 0,What’s New in Python 2 2,Τι νέο υπάρχει στην Python
@anchor{whatsnew/2 1 doc}@anchor{18b2}@anchor{whatsnew/2 1 translation-repo}@anchor{18b3}@anchor{whatsnew/2 1 what-s-new-in-python-2-1}@anchor{18b4}
@section What’s New in Python 2.1


@*Author: 
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; __future__ Directives: PEP 236 __future__ Directives. 
* 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; Function Attributes: PEP 232 Function Attributes. 
* 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>. 
* Other Changes and Fixes: Other Changes and Fixes<4>. 
* Acknowledgements: Acknowledgements<7>. 

@end menu

@node Introduction<2>,PEP 227 Nested Scopes<2>,,What’s New in Python 2 1
@anchor{whatsnew/2 1 introduction}@anchor{18b5}
@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 __future__ Directives,Introduction<2>,What’s New in Python 2 1
@anchor{whatsnew/2 1 pep-227-nested-scopes}@anchor{18b6}
@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{665,,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{1642,,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.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{17fc,,def}, @ref{167c,,class}, or @ref{9da,,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{1642,,lambda} expressions with free variables, the compiler
will flag this by raising a @ref{17e,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 227

@item PEP 227@footnote{https://peps.python.org/pep-0227/} - Statically Nested Scopes

Written and implemented by Jeremy Hylton.
@end table


@c ======================================================================

@node PEP 236 __future__ Directives,PEP 207 Rich Comparisons,PEP 227 Nested Scopes<2>,What’s New in Python 2 1
@anchor{whatsnew/2 1 pep-236-future-directives}@anchor{18b7}
@subsection PEP 236: __future__ Directives


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{9da,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 236

@item PEP 236@footnote{https://peps.python.org/pep-0236/} - Back to the @ref{0,,__future__}

Written by Tim Peters, and primarily implemented by Jeremy Hylton.
@end table


@c ======================================================================

@node PEP 207 Rich Comparisons,PEP 230 Warning Framework,PEP 236 __future__ Directives,What’s New in Python 2 1
@anchor{whatsnew/2 1 pep-207-rich-comparisons}@anchor{18b8}
@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

Operation

@tab

Method name

@item

@code{<}

@tab

@ref{1645,,__lt__()}

@item

@code{<=}

@tab

@ref{16af,,__le__()}

@item

@code{>}

@tab

@ref{16b0,,__gt__()}

@item

@code{>=}

@tab

@ref{16b1,,__ge__()}

@item

@code{==}

@tab

@ref{ec0,,__eq__()}

@item

@code{!=}

@tab

@ref{18b9,,__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 Δείτε επίσης



@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,What’s New in Python 2 1
@anchor{whatsnew/2 1 pep-230-warning-framework}@anchor{18ba}
@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{11b,,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{18bb,,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{c1,,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{2c9,,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 Δείτε επίσης



@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,What’s New in Python 2 1
@anchor{whatsnew/2 1 pep-229-new-build-system}@anchor{18bc}
@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 Δείτε επίσης



@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 Function Attributes,PEP 229 New Build System,What’s New in Python 2 1
@anchor{whatsnew/2 1 pep-205-weak-references}@anchor{18bd}
@subsection PEP 205: Weak References


Weak references, available through the @ref{11d,,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{11d,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 205

@item PEP 205@footnote{https://peps.python.org/pep-0205/} - Weak References

Written and implemented by Fred L. Drake, Jr.
@end table


@c ======================================================================

@node PEP 232 Function Attributes,PEP 235 Importing Modules on Case-Insensitive Platforms,PEP 205 Weak References,What’s New in Python 2 1
@anchor{whatsnew/2 1 pep-232-function-attributes}@anchor{18be}
@subsection PEP 232: Function Attributes


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{1582,,__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{1677,,__dict__}. Unlike the @ref{101b,,__dict__} attribute of class instances, in
functions you can actually assign a new dictionary to @code{__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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 232

@item PEP 232@footnote{https://peps.python.org/pep-0232/} - Function Attributes

Written and implemented by Barry Warsaw.
@end table


@c ======================================================================

@node PEP 235 Importing Modules on Case-Insensitive Platforms,PEP 217 Interactive Display Hook,PEP 232 Function Attributes,What’s New in Python 2 1
@anchor{whatsnew/2 1 pep-235-importing-modules-on-case-insensitive-platforms}@anchor{18bf}
@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{9da,,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{1bd,,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 μεταβλητή περιβάλλοντος; PYTHONCASEOK
@ref{d26,,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,What’s New in Python 2 1
@anchor{whatsnew/2 1 pep-217-interactive-display-hook}@anchor{18c0}
@subsection PEP 217: Interactive Display Hook


When using the Python interpreter interactively, the output of commands is
displayed using the built-in @ref{45b,,repr()} function. In Python 2.1, the variable
@ref{18c1,,sys.displayhook()} can be set to a callable object which will be called
instead of @code{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 Δείτε επίσης



@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,What’s New in Python 2 1
@anchor{whatsnew/2 1 pep-208-new-coercion-model}@anchor{18c2}
@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{291,,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 @code{TypeError}, perhaps trying another
object’s numeric methods).


@subsubheading Δείτε επίσης



@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,What’s New in Python 2 1
@anchor{whatsnew/2 1 pep-241-metadata-in-python-packages}@anchor{18c3}
@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 Δείτε επίσης



@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>,Other Changes and Fixes<4>,PEP 241 Metadata in Python Packages,What’s New in Python 2 1
@anchor{whatsnew/2 1 new-and-improved-modules}@anchor{18c4}
@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{3d,,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{3a,,difflib} module contains a class, @ref{13c2,,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{30,,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{129,,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{be5,,sys.excepthook()} can be set to a callable object.  When an exception isn’t
caught by any @ref{ad6,,try}…@ref{447,,except} blocks, the exception will be
passed to @code{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{f7,,time} module, such as @ref{1590,,asctime()} and
@ref{189b,,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{61,,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 @code{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{d4,,socket} module,
contributed by Grant Edwards.

@item 
The @ref{b8,,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{ace,,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 Other Changes and Fixes<4>,Acknowledgements<7>,New and Improved Modules<4>,What’s New in Python 2 1
@anchor{whatsnew/2 1 other-changes-and-fixes}@anchor{18c5}
@subsection Other Changes and Fixes


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{18c6,,PyMem_New}, it has to be freed
using @ref{18c7,,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{c2,,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{18c8,,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{e2,,sys} or @ref{db,,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{45b,,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{3a3,,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 Acknowledgements<7>,,Other Changes and Fixes<4>,What’s New in Python 2 1
@anchor{whatsnew/2 1 acknowledgements}@anchor{18c9}
@subsection Acknowledgements


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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node What’s New in Python 2 0,Changelog,What’s New in Python 2 1,Τι νέο υπάρχει στην Python
@anchor{whatsnew/2 0 doc}@anchor{18ca}@anchor{whatsnew/2 0 translation-repo}@anchor{18cb}@anchor{whatsnew/2 0 what-s-new-in-python-2-0}@anchor{18cc}
@section What’s New in Python 2.0


@*Author: 
A.M. Kuchling and Moshe Zadka


@c $Id: whatsnew20.tex 50964 2006-07-30 03:03:43Z fred.drake $

@menu
* Introduction: Introduction<3>. 
* What About Python 1.6?: What About Python 1 6?. 
* New Development Process:: 
* Unicode: Unicode<2>. 
* List Comprehensions:: 
* Augmented Assignment:: 
* String Methods:: 
* 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. 
* XML Modules:: 
* Module changes:: 
* New modules: New modules<4>. 
* IDLE Improvements:: 
* Deleted and Deprecated Modules:: 
* Acknowledgements: Acknowledgements<8>. 

@end menu

@node Introduction<3>,What About Python 1 6?,,What’s New in Python 2 0
@anchor{whatsnew/2 0 introduction}@anchor{18cd}
@subsection Introduction


A new release of Python, version 2.0, was released on October 16, 2000. This
article covers the exciting new features in 2.0, highlights some other useful
changes, and points out a few incompatible changes that may require rewriting
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 What About Python 1 6?,New Development Process,Introduction<3>,What’s New in Python 2 0
@anchor{whatsnew/2 0 what-about-python-1-6}@anchor{18ce}
@subsection What About Python 1.6?


Python 1.6 can be thought of as the Contractual Obligations Python release.
After the core development team left CNRI in May 2000, CNRI requested that a 1.6
release be created, containing all the work on Python that had been performed at
CNRI.  Python 1.6 therefore represents the state of the CVS tree as of May 2000,
with the most significant new feature being Unicode support.  Development
continued after May, of course, so the 1.6 tree received a few fixes to ensure
that it’s forward-compatible with Python 2.0.  1.6 is therefore part of Python’s
evolution, and not a side branch.

So, should you take much interest in Python 1.6?  Probably not.  The 1.6final
and 2.0beta1 releases were made on the same day (September 5, 2000), the plan
being to finalize Python 2.0 within a month or so.  If you have applications to
maintain, there seems little point in breaking things by moving to 1.6, fixing
them, and then having another round of breakage within a month by moving to 2.0;
you’re better off just going straight to 2.0.  Most of the really interesting
features described in this document are only in 2.0, because a lot of work was
done between May and September.

@c ======================================================================

@node New Development Process,Unicode<2>,What About Python 1 6?,What’s New in Python 2 0
@anchor{whatsnew/2 0 new-development-process}@anchor{18cf}
@subsection New Development Process


The most important change in Python 2.0 may not be to the code at all, but to
how Python is developed: in May 2000 the Python developers began using the tools
made available by SourceForge for storing  source code, tracking bug reports,
and managing the queue of patch submissions.  To report bugs or submit patches
for Python 2.0, use the bug tracking and patch manager tools available from
Python’s project page, located at @indicateurl{https://sourceforge.net/projects/python/}.

The most important of the services now hosted at SourceForge is the Python CVS
tree, the version-controlled repository containing the source code for Python.
Previously, there were roughly 7 or so people who had write access to the CVS
tree, and all patches had to be inspected and checked in by one of the people on
this short list. Obviously, this wasn’t very scalable.  By moving the CVS tree
to SourceForge, it became possible to grant write access to more people; as of
September 2000 there were 27 people able to check in changes, a fourfold
increase.  This makes possible large-scale changes that wouldn’t be attempted if
they’d have to be filtered through the small group of core developers.  For
example, one day Peter Schneider-Kamp took it into his head to drop K&R C
compatibility and convert the C source for Python to ANSI C. After getting
approval on the python-dev mailing list, he launched into a flurry of checkins
that lasted about a week, other developers joined in to help, and the job was
done.  If there were only 5 people with write access, probably that task would
have been viewed as «nice, but not worth the time and effort needed» and it
would never have gotten done.

The shift to using SourceForge’s services has resulted in a remarkable increase
in the speed of development.  Patches now get submitted, commented on, revised
by people other than the original submitter, and bounced back and forth between
people until the patch is deemed worth checking in.  Bugs are tracked in one
central location and can be assigned to a specific person for fixing, and we can
count the number of open bugs to measure progress.  This didn’t come without a
cost: developers now have more e-mail to deal with, more mailing lists to
follow, and special tools had to be written for the new environment. For
example, SourceForge sends default patch and bug notification e-mail messages
that are completely unhelpful, so Ka-Ping Yee wrote an HTML screen-scraper that
sends more useful messages.

The ease of adding code caused a few initial growing pains, such as code was
checked in before it was ready or without getting clear agreement from the
developer group.  The approval process that has emerged is somewhat similar to
that used by the Apache group. Developers can vote +1, +0, -0, or -1 on a patch;
+1 and -1 denote acceptance or rejection, while +0 and -0 mean the developer is
mostly indifferent to the change, though with a slight positive or negative
slant.  The most significant change from the Apache model is that the voting is
essentially advisory, letting Guido van Rossum, who has Benevolent Dictator For
Life status, know what the general opinion is. He can still ignore the result of
a vote, and approve or reject a change even if the community disagrees with him.

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 stands for Python Enhancement Proposal.  A PEP is a design document
providing information to the Python community, or describing a new feature for
Python.  The PEP should provide a concise technical specification of the feature
and a rationale for the feature.

We intend PEPs to be the primary mechanisms for proposing new features, for
collecting community input on an issue, and for documenting the design decisions
that have gone into Python.  The PEP author is responsible for building
consensus within the community and documenting dissenting opinions.
@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>,List Comprehensions,New Development Process,What’s New in Python 2 0
@anchor{whatsnew/2 0 unicode}@anchor{18d0}
@subsection Unicode


The largest new feature in Python 2.0 is a new fundamental data type: Unicode
strings.  Unicode uses 16-bit numbers to represent characters instead of the
8-bit number used by ASCII, meaning that 65,536 distinct characters can be
supported.

The final interface for Unicode support was arrived at through countless
often-stormy discussions on the python-dev mailing list, and mostly implemented by
Marc-André Lemburg, based on a Unicode string type implementation by Fredrik
Lundh.  A detailed explanation of the interface was written up as 
@geindex Python Enhancement Proposals; PEP 100
PEP 100@footnote{https://peps.python.org/pep-0100/},
«Python Unicode Integration». This article will simply cover the most
significant points about the Unicode interfaces.

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}.

Unicode strings, just like regular strings, are an immutable sequence type.
They can be indexed and sliced, but not modified in place. Unicode strings have
an @code{encode( [encoding] )} method that returns an 8-bit string in the desired
encoding.  Encodings are named by strings, such as @code{'ascii'}, @code{'utf-8'},
@code{'iso-8859-1'}, or whatever.  A codec API is defined for implementing and
registering new encodings that are then available throughout a Python program.
If an encoding isn’t specified, the default encoding is usually 7-bit ASCII,
though it can be changed for your Python installation by calling the
@code{sys.setdefaultencoding(encoding)} function in a customized version of
@code{site.py}.

Combining 8-bit and Unicode strings always coerces to Unicode, using the default
ASCII encoding; the result of @code{'a' + u'bc'} is @code{u'abc'}.

New built-in functions have been added, and existing built-ins modified to
support Unicode:


@itemize *

@item 
@code{unichr(ch)} returns a Unicode string 1 character long, containing the
character `ch'.

@item 
@code{ord(u)}, where `u' is a 1-character regular or Unicode string, returns the
number of the character as an integer.

@item 
@code{unicode(string [, encoding]  [, errors] )} creates a Unicode string
from an 8-bit string.  @code{encoding} is a string naming the encoding to use. The
@code{errors} parameter specifies the treatment of characters that are invalid for
the current encoding; passing @code{'strict'} as the value causes an exception to
be raised on any encoding error, while @code{'ignore'} causes errors to be silently
ignored and @code{'replace'} uses U+FFFD, the official replacement character, in
case of any problems.

@item 
The @code{exec} statement, and various built-ins such as @code{eval()},
@code{getattr()}, and @code{setattr()} will also accept Unicode strings as well as
regular strings.  (It’s possible that the process of fixing this missed some
built-ins; if you find a built-in function that accepts strings but doesn’t
accept Unicode strings at all, please report it as a bug.)
@end itemize

A new module, @ref{10e,,unicodedata}, provides an interface to Unicode character
properties.  For example, @code{unicodedata.category(u'A')} returns the 2-character
string “Lu”, the “L” denoting it’s a letter, and “u” meaning that it’s
uppercase. @code{unicodedata.bidirectional(u'\u0660')} returns “AN”, meaning that
U+0660 is an Arabic number.

The @ref{1c,,codecs} module contains functions to look up existing encodings and
register new ones.  Unless you want to implement a new encoding, you’ll most
often use the @code{codecs.lookup(encoding)} function, which returns a
4-element tuple: @code{(encode_func, decode_func, stream_reader, stream_writer)}.


@itemize *

@item 
`encode_func' is a function that takes a Unicode string, and returns a 2-tuple
@code{(string, length)}.  `string' is an 8-bit string containing a portion (perhaps
all) of the Unicode string converted into the given encoding, and `length' tells
you how much of the Unicode string was converted.

@item 
`decode_func' is the opposite of `encode_func', taking an 8-bit string and
returning a 2-tuple @code{(ustring, length)}, consisting of the resulting Unicode
string `ustring' and the integer `length' telling how much of the 8-bit string
was consumed.

@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

For example, the following code writes a Unicode string into a file,  encoding
it as 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

The following code would then read UTF-8 input from the file:

@example
input = UTF8_streamreader( open( '/tmp/output', 'rb') )
print repr(input.read())
input.close()
@end example

Unicode-aware regular expressions are available through the @ref{c1,,re} module,
which has a new underlying implementation called SRE written by Fredrik Lundh of
Secret Labs AB.

A @code{-U} command line option was added which causes the Python compiler to
interpret all string literals as Unicode string literals. This is intended to be
used in testing and future-proofing your Python code, since some future version
of Python may drop support for 8-bit strings and provide only Unicode strings.

@c ======================================================================

@node List Comprehensions,Augmented Assignment,Unicode<2>,What’s New in Python 2 0
@anchor{whatsnew/2 0 list-comprehensions}@anchor{18d1}
@subsection List Comprehensions


Lists are a workhorse data type in Python, and many programs manipulate a list
at some point.  Two common operations on lists are to loop over them, and either
pick out the elements that meet a certain criterion, or apply some function to
each element.  For example, given a list of strings, you might want to pull out
all the strings containing a given substring, or strip off trailing whitespace
from each line.

The existing @ref{43e,,map()} and @ref{c3b,,filter()} functions can be used for this
purpose, but they require a function as one of their arguments.  This is fine if
there’s an existing built-in function that can be passed directly, but if there
isn’t, you have to create a little function to do the required work, and
Python’s scoping rules make the result ugly if the little function needs
additional information.  Take the first example in the previous paragraph,
finding all the strings in the list containing a given substring.  You could
write the following to do it:

@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

Because of Python’s scoping rules, a default argument is used so that the
anonymous function created by the @ref{1642,,lambda} expression knows what
substring is being searched for.  List comprehensions make this cleaner:

@example
sublist = [ s for s in L if string.find(s, S) != -1 ]
@end example

List comprehensions have the form:

@example
[ expression for expr in sequence1
             for expr2 in sequence2 ...
             for exprN in sequenceN
             if condition ]
@end example

The @code{for}…@code{in} clauses contain the sequences to be
iterated over.  The sequences do not have to be the same length, because they
are `not' iterated over in parallel, but from left to right; this is explained
more clearly in the following paragraphs.  The elements of the generated list
will be the successive values of `expression'.  The final @code{if} clause
is optional; if present, `expression' is only evaluated and added to the result
if `condition' is true.

To make the semantics very clear, a list comprehension is equivalent to the
following Python code:

@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

This means that when there are multiple @code{for}…@code{in}
clauses, the resulting list will be equal to the product of the lengths of all
the sequences.  If you have two lists of length 3, the output list is 9 elements
long:

@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

To avoid introducing an ambiguity into Python’s grammar, if `expression' is
creating a tuple, it must be surrounded with parentheses.  The first list
comprehension below is a syntax error, while the second one is correct:

@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

The idea of list comprehensions originally comes from the functional programming
language Haskell (@indicateurl{https://www.haskell.org}).  Greg Ewing argued most effectively
for adding them to Python and wrote the initial list comprehension patch, which
was then discussed for a seemingly endless time on the python-dev mailing list
and kept up-to-date by Skip Montanaro.

@c ======================================================================

@node Augmented Assignment,String Methods,List Comprehensions,What’s New in Python 2 0
@anchor{whatsnew/2 0 augmented-assignment}@anchor{18d2}
@subsection Augmented Assignment


Augmented assignment operators, another long-requested feature, have been added
to Python 2.0.  Augmented assignment operators include @code{+=}, @code{-=}, @code{*=},
and so forth.  For example, the statement @code{a += 2} increments the value of the
variable  @code{a} by 2, equivalent to the slightly lengthier @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 String Methods,Garbage Collection of Cycles,Augmented Assignment,What’s New in Python 2 0
@anchor{whatsnew/2 0 string-methods}@anchor{18d3}
@subsection String Methods


Until now string-manipulation functionality was in the @ref{db,,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{db,,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{db,,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,String Methods,What’s New in Python 2 0
@anchor{whatsnew/2 0 garbage-collection-of-cycles}@anchor{18d4}
@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{63,,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,What’s New in Python 2 0
@anchor{whatsnew/2 0 other-core-changes}@anchor{18d5}
@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
* Minor Language Changes:: 
* Changes to Built-in Functions:: 

@end menu

@node Minor Language Changes,Changes to Built-in Functions,,Other Core Changes
@anchor{whatsnew/2 0 minor-language-changes}@anchor{18d6}
@subsubsection Minor Language Changes


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{45b,,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{1df,,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{323,,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{18d7,,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{665,,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
@code{NameError} exception is raised, while 2.0 raises a new
@ref{18d8,,UnboundLocalError} exception. @code{UnboundLocalError} is a subclass of
@code{NameError}, so any existing code that expects @code{NameError} to be
raised should still work.

@example
def f():
    print "i=",i
    i = i + 1
f()
@end example

Two new exceptions, @ref{950,,TabError} and @ref{b89,,IndentationError}, have been
introduced.  They’re both subclasses of @ref{17e,,SyntaxError}, and are raised when
Python code is found to be improperly indented.

@node Changes to Built-in Functions,,Minor Language Changes,Other Core Changes
@anchor{whatsnew/2 0 changes-to-built-in-functions}@anchor{18d9}
@subsubsection Changes to Built-in Functions


A new built-in, @code{zip(seq1, seq2, ...)}, has been added.  @ref{43f,,zip()}
returns a list of tuples where each tuple contains the i-th element from each of
the argument sequences.  The difference between @code{zip()} and @code{map(None,
seq1, seq2)} is that @ref{43e,,map()} pads the sequences with @code{None} if the
sequences aren’t all of the same length, while @code{zip()} truncates the
returned list to the length of the shortest argument sequence.

The @ref{326,,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{291,,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{e2,,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{8d4,,sys.getrecursionlimit()} and
@ref{8d3,,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,What’s New in Python 2 0
@anchor{whatsnew/2 0 porting-to-2-0}@anchor{18da}
@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
@ref{aba,,append()} and @ref{1541,,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{291,,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{3b1,,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{d4,,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{18db,,socket.connect_ex} and @ref{18dc,,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 @code{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{1a9,,AttributeError} and @ref{665,,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{291,,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{1df,,str()} of a long
integer no longer has a trailing “L” character, though @ref{45b,,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{45b,,repr()} of a float now uses a different formatting precision
than @ref{1df,,str()}.  @code{repr()} uses @code{%.17g} format string for C’s
@code{sprintf()}, while @code{str()} uses @code{%.12g} as before.  The effect is that
@code{repr()} may occasionally show more decimal places than  @code{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,What’s New in Python 2 0
@anchor{whatsnew/2 0 extending-embedding-changes}@anchor{18dd}
@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{2ef,,isinstance()} and @ref{2f0,,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{801,,PyModule_AddObject()},
@ref{18de,,PyModule_AddIntConstant()}, and @ref{18df,,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{18e0,,PyOS_getsig()} gets
a signal handler and @ref{18e1,,PyOS_setsig()} will set a new handler.

@c ======================================================================

@node Distutils Making Modules Easy to Install,XML Modules,Extending/Embedding Changes,What’s New in Python 2 0
@anchor{whatsnew/2 0 distutils-making-modules-easy-to-install}@anchor{18e2}
@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 XML Modules,Module changes,Distutils Making Modules Easy to Install,What’s New in Python 2 0
@anchor{whatsnew/2 0 xml-modules}@anchor{18e3}
@subsection XML Modules


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{129,,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
* SAX2 Support:: 
* DOM Support:: 
* Relationship to PyXML:: 

@end menu

@node SAX2 Support,DOM Support,,XML Modules
@anchor{whatsnew/2 0 sax2-support}@anchor{18e4}
@subsubsection SAX2 Support


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{18e5,,startElement()} and @ref{18e6,,endElement()}
methods are called for every starting and end tag encountered by the parser, the
@ref{18e7,,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 DOM Support,Relationship to PyXML,SAX2 Support,XML Modules
@anchor{whatsnew/2 0 dom-support}@anchor{18e8}
@subsubsection DOM Support


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{12b,,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,,DOM Support,XML Modules
@anchor{whatsnew/2 0 relationship-to-pyxml}@anchor{18e9}
@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{129,,xml} package.

The answer is that Python 2.0’s @ref{129,,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
@code{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,New modules<4>,XML Modules,What’s New in Python 2 0
@anchor{whatsnew/2 0 module-changes}@anchor{18ea}
@subsection Module changes


Lots of improvements and bugfixes were made to Python’s extensive standard
library; some of the affected modules include @ref{c2,,readline},
@ref{26,,ConfigParser}, @code{cgi}, @ref{15,,calendar}, @ref{b2,,posix}, @code{readline},
@code{xmllib}, @code{aifc}, @code{chunk}, @ref{11c,,wave}, @ref{c0,,random}, @ref{cb,,shelve},
and @code{nntplib}.  Consult the CVS logs for the exact patch-by-patch details.

Brian Gallew contributed OpenSSL support for the @ref{d4,,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 @code{socket}
module: @code{socket.ssl(socket, keyfile, certfile)}, which takes a socket
object and returns an SSL socket.  The @ref{71,,httplib} and @ref{111,,urllib} modules
were also changed to support @code{https://} URLs, though no one has implemented
FTP or SMTP over SSL.

The @ref{71,,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{2e,,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{c1,,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 New modules<4>,IDLE Improvements,Module changes,What’s New in Python 2 0
@anchor{whatsnew/2 0 new-modules}@anchor{18eb}
@subsection New 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{d,,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 @code{atexit} module instead, importing @code{atexit} and
calling @ref{c54,,atexit.register()} with  the function to be called on exit.
(Contributed by Skip Montanaro.)

@item 
@ref{1c,,codecs}, @code{encodings}, @ref{10e,,unicodedata}:  Added as part of the new
Unicode support.

@item 
@ref{5d,,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{66,,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{94,,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{c1,,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{116,,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{e6,,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{11e,,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{111,,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{11f,,_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{13a,,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{6a,,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,New modules<4>,What’s New in Python 2 0
@anchor{whatsnew/2 0 idle-improvements}@anchor{18ec}
@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}-@code{F5}), Import module (@code{F5}) and
Run script (@code{Ctrl}-@code{F5}).
@end itemize

@c ======================================================================

@node Deleted and Deprecated Modules,Acknowledgements<8>,IDLE Improvements,What’s New in Python 2 0
@anchor{whatsnew/2 0 deleted-and-deprecated-modules}@anchor{18ed}
@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 Acknowledgements<8>,,Deleted and Deprecated Modules,What’s New in Python 2 0
@anchor{whatsnew/2 0 acknowledgements}@anchor{18ee}
@subsection Acknowledgements


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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

Το «Changelog» είναι μια έκδοση σε HTML του file built@footnote{https://pypi.org/project/blurb/} από τα περιεχόμενα του Misc/NEWS.d@footnote{https://github.com/python/cpython/tree/main/Misc/NEWS.d} δέντρου καταλόγων, το οποίο περιέχει `όλες' τις μη ασήμαντες αλλαγές στην Python για την τρέχουσα έκδοση.

@node Changelog,,What’s New in Python 2 0,Τι νέο υπάρχει στην Python
@anchor{whatsnew/changelog doc}@anchor{18ef}@anchor{whatsnew/changelog changelog}@anchor{145}@anchor{whatsnew/changelog id1}@anchor{18f0}@anchor{whatsnew/changelog translation-repo}@anchor{18f1}
@section Changelog


@menu
* Python next:: 
* Python 3.15.0 beta 1: Python 3 15 0 beta 1. 
* Python 3.15.0 alpha 8: Python 3 15 0 alpha 8. 
* Python 3.15.0 alpha 7: Python 3 15 0 alpha 7. 
* Python 3.15.0 alpha 6: Python 3 15 0 alpha 6. 
* Python 3.15.0 alpha 5: Python 3 15 0 alpha 5. 
* Python 3.15.0 alpha 4: Python 3 15 0 alpha 4. 
* Python 3.15.0 alpha 3: Python 3 15 0 alpha 3. 
* Python 3.15.0 alpha 2: Python 3 15 0 alpha 2. 
* Python 3.15.0 alpha 1: Python 3 15 0 alpha 1. 
* Python 3.14.0 beta 1: Python 3 14 0 beta 1. 
* Python 3.14.0 alpha 7: Python 3 14 0 alpha 7. 
* Python 3.14.0 alpha 6: Python 3 14 0 alpha 6. 
* Python 3.14.0 alpha 5: Python 3 14 0 alpha 5. 
* Python 3.14.0 alpha 4: Python 3 14 0 alpha 4. 
* Python 3.14.0 alpha 3: Python 3 14 0 alpha 3. 
* Python 3.14.0 alpha 2: Python 3 14 0 alpha 2. 
* Python 3.14.0 alpha 1: Python 3 14 0 alpha 1. 
* 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 15 0 beta 1,,Changelog
@anchor{whatsnew/changelog python-next}@anchor{18f2}
@subsection Python next


`Release date: XXXX-XX-XX'

@menu
* Security:: 
* Library:: 
* Core and Builtins:: 

@end menu

@node Security,Library,,Python next
@anchor{whatsnew/changelog security}@anchor{18f3}
@subsubsection Security



@itemize -

@item 
gh-149474@footnote{https://github.com/python/cpython/issues/149474}: Fix the binary writer in @ref{b6,,profiling.sampling} not firing
the audit (
@geindex Python Enhancement Proposals; PEP 578
PEP 578@footnote{https://peps.python.org/pep-0578/}) when creating the output file. The writer and the
reader now accept any path-like object. Patch by Maurycy
Pawłowski-Wieroński.

@item 
gh-149486@footnote{https://github.com/python/cpython/issues/149486}: @ref{279,,tarfile.data_filter()} now validates link targets using
the same normalised value that is written to disk, strips trailing
separators from the member name when resolving a symlink’s directory, and
rejects link members that would replace the destination directory itself.
This closes several path-traversal bypasses of the @code{data} extraction
filter.
@end itemize

@node Library,Core and Builtins,Security,Python next
@anchor{whatsnew/changelog library}@anchor{18f4}
@subsubsection Library



@itemize -

@item 
gh-149436@footnote{https://github.com/python/cpython/issues/149436}: Improve performance of @ref{8a5,,inspect.getattr_static()}.

@item 
gh-149537@footnote{https://github.com/python/cpython/issues/149537}: Remove kw parameters from python version of
@ref{153,,functools.reduce()} function.

@item 
gh-149530@footnote{https://github.com/python/cpython/issues/149530}: Removed @code{symtable.Class.get_methods()} which has been
deprecated since 3.14.

@item 
gh-149528@footnote{https://github.com/python/cpython/issues/149528}: Remove @code{annotationlib.ForwardRef._evaludate} deprecated
method.

@item 
gh-149388@footnote{https://github.com/python/cpython/issues/149388}: Make @code{asyncio.windows_utils.PipeHandle} closing
idempotent.

@item 
gh-149499@footnote{https://github.com/python/cpython/issues/149499}: Removed the @code{sysconfig.expand_makefile_vars()} function
which has been deprecated since Python 3.14. Use the @code{vars} argument of
@ref{156,,sysconfig.get_paths()} instead.
@end itemize

@node Core and Builtins,,Library,Python next
@anchor{whatsnew/changelog core-and-builtins}@anchor{18f5}
@subsubsection Core and Builtins



@itemize -

@item 
gh-149459@footnote{https://github.com/python/cpython/issues/149459}: Fix a crash in the JIT optimizer when a specialized
@code{LOAD_SPECIAL} guard deoptimized after inserting the synthetic @code{NULL}
stack entry.
@end itemize

@node Python 3 15 0 beta 1,Python 3 15 0 alpha 8,Python next,Changelog
@anchor{whatsnew/changelog python-3-15-0-beta-1}@anchor{18f6}
@subsection Python 3.15.0 beta 1


`Release date: 2026-05-07'

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

@end menu

@node Security<2>,Core and Builtins<2>,,Python 3 15 0 beta 1
@anchor{whatsnew/changelog id2}@anchor{18f7}
@subsubsection Security



@itemize -

@item 
gh-149254@footnote{https://github.com/python/cpython/issues/149254}: Update Android and iOS installer to use OpenSSL 3.5.6.

@item 
gh-149017@footnote{https://github.com/python/cpython/issues/149017}: Update bundled libexpat@footnote{https://libexpat.github.io/} to
version 2.8.0.

@item 
gh-148252@footnote{https://github.com/python/cpython/issues/148252}: Fixed string table and sample record bounds checks in
@code{_remote_debugging} when decoding certain @code{.pyb} inputs on 32-bit
builds. Patch by Maurycy Pawłowski-Wieroński.

@item 
gh-90309@footnote{https://github.com/python/cpython/issues/90309}: Base64-encode values when embedding cookies to JavaScript using
the @ref{2f5,,http.cookies.BaseCookie.js_output()} method to avoid injection
and escaping.

@item 
gh-148808@footnote{https://github.com/python/cpython/issues/148808}: Added buffer boundary check when using @code{nbytes} parameter
with @code{asyncio.AbstractEventLoop.sock_recvfrom_into()}. Only relevant
for Windows and the @ref{9fe,,asyncio.ProactorEventLoop}.

@item 
gh-148395@footnote{https://github.com/python/cpython/issues/148395}: Fix a dangling input pointer in @ref{18f8,,lzma.LZMADecompressor},
@ref{18f9,,bz2.BZ2Decompressor}, and internal
@code{zlib._ZlibDecompressor} when memory allocation fails with
@ref{18fa,,MemoryError}, which could let a subsequent @code{decompress()} call
read or write through a stale pointer to the already-released caller
buffer.

@item 
gh-148252@footnote{https://github.com/python/cpython/issues/148252}: Fixed stack depth calculation in @code{_remote_debugging} when
decoding certain @code{.pyb} inputs on 32-bit builds. Issue originally
identified and diagnosed by Tristan Madani (@@TristanInSec on GitHub).

@item 
gh-148178@footnote{https://github.com/python/cpython/issues/148178}: Hardened @code{_remote_debugging} by validating remote debug
offset tables before using them to size memory reads or interpret remote
layouts.

@item 
gh-148169@footnote{https://github.com/python/cpython/issues/148169}: A bypass in @ref{11e,,webbrowser} allowed URLs prefixed with
@code{%action} to pass the dash-prefix safety check.

@item 
gh-146581@footnote{https://github.com/python/cpython/issues/146581}: Fix vulnerability in @ref{882,,shutil.unpack_archive()} for ZIP
files on Windows which allowed to write files outside of the destination
tree if the patch in the archive contains a Windows drive prefix. Now such
invalid paths will be skipped. Files containing «..» in the name (like
«foo..bar») are no longer skipped.

@item 
gh-137586@footnote{https://github.com/python/cpython/issues/137586}: Fix a PATH-injection vulnerability in @ref{11e,,webbrowser} on
macOS where @code{osascript} was invoked without an absolute path. The new
@code{MacOS} class uses @code{/usr/bin/open} directly, eliminating the
dependency on @code{osascript} entirely.

@item 
gh-146333@footnote{https://github.com/python/cpython/issues/146333}: Fix quadratic backtracking in
@ref{130e,,configparser.RawConfigParser} option parsing regexes (@code{OPTCRE}
and @code{OPTCRE_NV}). A crafted configuration line with many whitespace
characters could cause excessive CPU usage.

@item 
gh-146211@footnote{https://github.com/python/cpython/issues/146211}: Reject CR/LF characters in tunnel request headers for the
HTTPConnection.set_tunnel() method.
@end itemize

@node Core and Builtins<2>,Library<2>,Security<2>,Python 3 15 0 beta 1
@anchor{whatsnew/changelog id3}@anchor{18fb}
@subsubsection Core and Builtins



@itemize -

@item 
gh-148940@footnote{https://github.com/python/cpython/issues/148940}: Revert the process size based deferral of garbage collection
(gh-133464@footnote{https://github.com/python/cpython/issues/133464}). The performance issue this change resolves is also fixed by
gh-142562@footnote{https://github.com/python/cpython/issues/142562}.  This approach has the problem that process size as seen by the
OS (e.g. the resident size or RSS) does not immediately decrease after
cyclic garbage is freed since mimalloc defers returning memory of the OS.
This change applies to the free-threaded GC only.

@item 
gh-149243@footnote{https://github.com/python/cpython/issues/149243}: Check for recursion limits in @code{CALL_ALLOC_AND_ENTER_INIT}
opcode.

@item 
gh-126910@footnote{https://github.com/python/cpython/issues/126910}: Add support for unwinding JIT frames using GNU backtrace. Patch
by Diego Russo and Pablo Galindo

@item 
gh-149171@footnote{https://github.com/python/cpython/issues/149171}: Allow assignment to the @code{__module__} attribute of
@ref{52a,,typing.TypeAliasType} instances.

@item 
gh-149122@footnote{https://github.com/python/cpython/issues/149122}: Fix a crash in optimized calls to @ref{17c4,,all()}, @ref{17c3,,any()},
@ref{1ce,,tuple()}, @ref{4d9,,list()}, and @ref{42b,,set()} with an async generator
expression argument (for example, @code{tuple(await x for x in y)}). These
calls now correctly raise @code{TypeError} instead of crashing.

@item 
gh-149049@footnote{https://github.com/python/cpython/issues/149049}: Fix stack underflow for @code{BINARY_OP} in tier 2.

@item 
gh-83065@footnote{https://github.com/python/cpython/issues/83065}: Fix a deadlock that could occur when one thread is importing a
submodule (for example @code{import pkg.sub.mod}) while another thread is
importing one of its parent packages (for example @code{import pkg.sub}) and
that parent’s @code{__init__.py} itself imports the submodule. The import
system now acquires module locks in hierarchical (parent-before-child)
order so the two threads serialise instead of raising @code{_DeadlockError}.

@item 
gh-113956@footnote{https://github.com/python/cpython/issues/113956}: Fix a data race in @ref{1680,,sys.intern()} in the free-threaded
build when interning a string owned by another thread. An interned copy
owned by the current thread is used instead when it is not safe to
immortalize the original.

@item 
gh-148850@footnote{https://github.com/python/cpython/issues/148850}: Fix the memory sanitizer false positive in
@ref{107b,,os.getrandom()}.

@item 
gh-148820@footnote{https://github.com/python/cpython/issues/148820}: Fix a race in @code{_PyRawMutex} on the free-threaded build
where a @code{Py_PARK_INTR} return from @code{_PySemaphore_Wait} could let the
waiter destroy its semaphore before the unlocking thread’s
@code{_PySemaphore_Wakeup} completed, causing a fatal @code{ReleaseSemaphore}
error.

@item 
gh-148829@footnote{https://github.com/python/cpython/issues/148829}: Add @ref{18b,,sentinel}, implementing 
@geindex Python Enhancement Proposals; PEP 661
PEP 661@footnote{https://peps.python.org/pep-0661/}. PEP by Tal
Einat; patch by Jelle Zijlstra.

@item 
gh-146270@footnote{https://github.com/python/cpython/issues/146270}: Fix a sequential consistency bug in @code{structmember.c}.

@item 
gh-148766@footnote{https://github.com/python/cpython/issues/148766}: The interpreter help (such as @code{python --help}) is now in
color. Patch by Hugo van Kemenade.

@item 
gh-148571@footnote{https://github.com/python/cpython/issues/148571}: Fix a crash in the JIT optimizer when specialized opcode
families inherited incompatible recorded operand layouts.

@item 
gh-148653@footnote{https://github.com/python/cpython/issues/148653}: Forbid @ref{90,,marshalling} recursive code objects,
@ref{1d0,,slice} and @ref{182,,frozendict} objects which cannot be correctly
unmarshalled.

@item 
gh-142516@footnote{https://github.com/python/cpython/issues/142516}: Forward-port the generational cycle garbage collector to the
default 3.15 build, replacing the incremental collector while leaving the
free-threaded collector unchanged.

@item 
gh-146462@footnote{https://github.com/python/cpython/issues/146462}: Added @code{PyTypeObject.tp_basicsize},
@code{PyTypeObject.tp_dictoffset}, and @code{PyHeapTypeObject.ht_cached_keys}
offsets to @code{_Py_DebugOffsets} to support version-independent
read-only dict introspection tools.

@item 
gh-145239@footnote{https://github.com/python/cpython/issues/145239}: Unary plus is now accepted in @ref{1d4,,match} literal
patterns, mirroring the existing support for unary minus. Patch by Bartosz
Sławecki.

@item 
gh-148515@footnote{https://github.com/python/cpython/issues/148515}: Fix a bug in the JIT optimizer reading operands for uops with
multiple caches.

@item 
gh-148390@footnote{https://github.com/python/cpython/issues/148390}: Fix an undefined behavior in @ref{1d2,,memoryview} when using the
native boolean format (@code{?}) in @ref{18fc,,cast()}. Previously, on
some common platforms, calling @code{memoryview(b).cast("?").tolist()}
incorrectly returned @code{[False]} instead of @code{[True]} for any even byte
`b'. Patch by Bénédikt Tran.

@item 
gh-148418@footnote{https://github.com/python/cpython/issues/148418}: Fix a possible reference leak in a corrupted @code{TYPE_CODE}
marshal stream.

@item 
gh-148393@footnote{https://github.com/python/cpython/issues/148393}: Fix data races between @ref{969,,PyDict_Watch()} /
@ref{18fd,,PyDict_Unwatch()} and concurrent dict mutation in the
@ref{198,,free-threaded build}.

@item 
gh-148398@footnote{https://github.com/python/cpython/issues/148398}: Fix a bug in the JIT optimizer where class attribute loads were
not invalidated after type mutation.

@item 
gh-146527@footnote{https://github.com/python/cpython/issues/146527}: Add a @code{GCMonitor} class with a @code{get_gc_stats} method to the
@code{_remote_debugging} module to allow reading GC statistics from an
external Python process without requiring the full @code{RemoteUnwinder}
functionality. Patch by Sergey Miryanov and Pablo Galindo.

@item 
gh-148284@footnote{https://github.com/python/cpython/issues/148284}: Fix high stack consumption in Python’s interpreter loop on
Clang 22 by setting function limits for inlining when building with
computed gotos.

@item 
gh-148037@footnote{https://github.com/python/cpython/issues/148037}: Remove critical section from @code{PyCode_Addr2Line()} in
free-threading.

@item 
gh-115802@footnote{https://github.com/python/cpython/issues/115802}: Improve JIT code generation on Linux AArch64 by reducing the
indirect call to external symbols. Patch by Diego Russo.

@item 
gh-148189@footnote{https://github.com/python/cpython/issues/148189}: Repaired undercount of bytes in type-specific free lists
reported by sys._debugmallocstats(). For types that participate in cyclic
garbage collection, it was missing two pointers used by GC.

@item 
gh-148222@footnote{https://github.com/python/cpython/issues/148222}: Fix vectorcall support in @ref{bc7,,types.GenericAlias} when the
underlying type does not support the vectorcall protocol. Fix possible
leaks in @code{types.GenericAlias} and @ref{527,,types.UnionType} in case
of memory error.

@item 
gh-148208@footnote{https://github.com/python/cpython/issues/148208}: Fix recursion depth leak in @ref{18fe,,PyObject_Print()}

@item 
gh-95004@footnote{https://github.com/python/cpython/issues/95004}: The specializing interpreter now specializes for
@ref{a21,,enum.Enum} improving performance and scaling in free-threading.
Patch by Kumar Aditya.

@item 
gh-149202@footnote{https://github.com/python/cpython/issues/149202}: Enable frame pointers by default for GCC-compatible CPython
builds, including @code{-mno-omit-leaf-frame-pointer}, @code{-marm} on 32-bit
ARM, and/or @code{-mbackchain} on s390x platforms when the compiler supports
them, so profilers and debuggers can unwind native interpreter frames more
reliably. Users can pass @ref{3dd,,--without-frame-pointers} to
@code{./configure} to opt out.

@item 
gh-148014@footnote{https://github.com/python/cpython/issues/148014}: Accept a function name in @ref{178,,-X presite} command
line option and 
@geindex PYTHON_PRESITE
@geindex μεταβλητή περιβάλλοντος; PYTHON_PRESITE
@ref{18ff,,PYTHON_PRESITE} environment variable. Patch by
Victor Stinner.

@item 
gh-147998@footnote{https://github.com/python/cpython/issues/147998}: Fixed a memory leak in interpreter helper calls so cleanup
works when an operation falls across interpreter boundaries. Patch by
Maurycy Pawłowski-Wieroński.

@item 
gh-146455@footnote{https://github.com/python/cpython/issues/146455}: Fix O(N²) compile-time regression in constant folding after it
was moved from AST to CFG optimizer.

@item 
gh-146306@footnote{https://github.com/python/cpython/issues/146306}: Specialize float true division in the tier 2 optimizer with
inplace mutation for uniquely-referenced operands.

@item 
gh-142186@footnote{https://github.com/python/cpython/issues/142186}: Global @ref{e3,,sys.monitoring} events can now be turned on and
disabled on a per code object basis. Returning @code{DISABLE} from a callback
disables the event for the entire code object (for the current tool).

@item 
gh-126910@footnote{https://github.com/python/cpython/issues/126910}: Add support for unwinding JIT frames using GDB. Patch by Diego
Russo and Pablo Galindo.

@item 
gh-146031@footnote{https://github.com/python/cpython/issues/146031}: The unstable API _PyInterpreterState_SetEvalFrameFunc has a
companion function _PyInterpreterState_SetEvalFrameAllowSpecialization to
specify if specialization should be allowed. When this option is set to 1
the specializer will turn Python -> Python calls into specialized opcodes
which the replacement interpreter loop can choose to respect and perform
inlined dispatch.

@item 
gh-145278@footnote{https://github.com/python/cpython/issues/145278}: The @ref{54,,encodings} is now partially frozen, including the
@code{aliases} and @code{utf_8} submodules.

The @ref{88,,linecache} is now frozen.

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Optimize and eliminate redundant ref-counting for
@code{MAKE_FUNCTION} in the JIT.

@item 
gh-143886@footnote{https://github.com/python/cpython/issues/143886}: Reorder function annotations so positional-only arguments are
returned before other arguments. This fixes how
@ref{a2a,,functools.singledispatch()} registers functions with positional-only
arguments.

@item 
gh-98894@footnote{https://github.com/python/cpython/issues/98894}: Restore @code{function__entry} and @code{function__return}
DTrace/SystemTap probes that were broken since Python 3.11.

@item 
gh-116021@footnote{https://github.com/python/cpython/issues/116021}: Support for creating instances of abstract AST nodes from the
@ref{9,,ast} module is deprecated and scheduled for removal in Python 3.20.
Patch by Brian Schubert.

@item 
gh-137814@footnote{https://github.com/python/cpython/issues/137814}: Fix the @code{__qualname__} attribute of @code{__annotate__}
functions on functions.

@item 
gh-137600@footnote{https://github.com/python/cpython/issues/137600}: @ref{9,,ast}: The constructors of AST nodes now raise a
@ref{291,,TypeError} when a required argument is omitted or when a keyword
argument that does not map to a field on the AST node is passed. These
cases had previously raised a @ref{2c9,,DeprecationWarning} since Python 3.13.
Patch by Brian Schubert.

@item 
gh-137293@footnote{https://github.com/python/cpython/issues/137293}: Fix @ref{3ea,,SystemError} when searching ELF Files in
@ref{418,,sys.remote_exec()}.

@item 
gh-135357@footnote{https://github.com/python/cpython/issues/135357}: Add support for @code{socket.SO_PASSRIGHTS} on Linux.

@item 
gh-134690@footnote{https://github.com/python/cpython/issues/134690}: Removed deprecated in 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/} since Python 3.12
@code{codeobject.co_lnotab} from @ref{2e1,,types.CodeType}.

@item 
gh-100239@footnote{https://github.com/python/cpython/issues/100239}: Specialize @code{BINARY_OP} for concatenation of lists and tuples,
and propagate the result type through @code{_BINARY_OP_EXTEND} in the tier 2
optimizer so that follow-up type guards can be eliminated.
@end itemize

@node Library<2>,Documentation<2>,Core and Builtins<2>,Python 3 15 0 beta 1
@anchor{whatsnew/changelog id4}@anchor{1900}
@subsubsection Library



@itemize -

@item 
gh-148823@footnote{https://github.com/python/cpython/issues/148823}: Defer the import of @code{_colorize} in @code{argparse} until needed
for coloring output.

@item 
gh-141560@footnote{https://github.com/python/cpython/issues/141560}: Add an `annotation_format' parameter to
@ref{b1f,,inspect.getfullargspec()}.

@item 
gh-139489@footnote{https://github.com/python/cpython/issues/139489}: Add the @ref{2b4,,xml.is_valid_text()} function, which allows to
check whether a string can be used in the XML document.

@item 
gh-142389@footnote{https://github.com/python/cpython/issues/142389}: Add backticks to stdlib argparse help to display in colour.
Patch by Hugo van Kemenade.

@item 
gh-149377@footnote{https://github.com/python/cpython/issues/149377}: Update bundled pip to 26.1.1

@item 
gh-142389@footnote{https://github.com/python/cpython/issues/142389}: Add backtick markup support in @ref{7,,argparse} option help text
to highlight inline code when color output is enabled. Patch by Hugo van
Kemenade.

@item 
gh-148675@footnote{https://github.com/python/cpython/issues/148675}: Remove @code{F} and @code{D} formats from @ref{8,,array} and
@ref{1d2,,memoryview}. Patch by Victor Stinner.

@item 
gh-149342@footnote{https://github.com/python/cpython/issues/149342}: Fix @code{_remote_debugging} binary writing so that sampling a
thread whose Python frame stack is empty (for example while it is in a C
call or mid-syscall) no longer raises @code{RuntimeError("Invalid stack
encoding type")}, and so that @code{BinaryWriter.total_samples} after
@code{finalize()} or context-manager exit includes samples flushed from
the RLE buffer. Patch by Maurycy Pawłowski-Wieroński.

@item 
gh-149010@footnote{https://github.com/python/cpython/issues/149010}: The @code{inspect} module CLI now reports as much information as
it has available for non-source modules when @code{--details} is specified,
and provides an error message rather than a traceback when @code{--details}
is omitted. It also reports improved information when the given target
location is not the target’s defining location and when the given target
is a data value rather than a class or function definition.

@item 
gh-146609@footnote{https://github.com/python/cpython/issues/146609}: Use @ref{7,,argparse} for colour help @ref{f8,,timeit} CLI. Patch by
Hugo van Kemenade.

@item 
gh-142389@footnote{https://github.com/python/cpython/issues/142389}: Add backticks for colour to regrtest and pdb’s help
description. Patch by Hugo van Kemenade.

@item 
gh-144384@footnote{https://github.com/python/cpython/issues/144384}: Lazily import @code{_colorize}. Patch by Hugo van Kemenade.

@item 
gh-149321@footnote{https://github.com/python/cpython/issues/149321}: Fix import cycles exposed by running standard library modules
with @code{-X lazy_imports=none}.

@item 
gh-145378@footnote{https://github.com/python/cpython/issues/145378}: Generate consistent colors for @ref{aa,,pdb} commands in
@code{pdb} REPL.

@item 
gh-149296@footnote{https://github.com/python/cpython/issues/149296}: Add a @code{dump} subcommand to @ref{b6,,profiling.sampling} that
prints a single traceback-style snapshot of a running process’s Python
stack, including per-thread status, source line highlighting, optional
bytecode opcode names, and async-aware task reconstruction. Patch by Pablo
Galindo.

@item 
gh-143231@footnote{https://github.com/python/cpython/issues/143231}: A `module' attribute has been added to
@code{warnings.WarningMessage}.

@item 
gh-148675@footnote{https://github.com/python/cpython/issues/148675}: @ref{2d,,ctypes}: Change the
@ref{2cd,,_type_} of
@ref{2ce,,c_float_complex}, @ref{2cf,,c_double_complex} and
@ref{2d0,,c_longdouble_complex} from @code{F}, @code{D} and @code{G} to
@code{Zf}, @code{Zd} and @code{Zg} for compatibility with numpy. Patch by Victor
Stinner.

@item 
gh-148675@footnote{https://github.com/python/cpython/issues/148675}: The @ref{1de,,array.typecodes} type changed from @ref{1df,,str} to
@ref{1ce,,tuple} to support type codes longer than 1 character (@code{Zf} and
@code{Zd}). Patch by Victor Stinner.

@item 
gh-149221@footnote{https://github.com/python/cpython/issues/149221}: Catch rare math domain error for
@ref{8c0,,random.binomialvariate()}.

@item 
gh-149231@footnote{https://github.com/python/cpython/issues/149231}: In @ref{105,,tomllib}, the number of parts in TOML keys is now
limited.

@item 
gh-143231@footnote{https://github.com/python/cpython/issues/143231}: @ref{2a0,,unittest.TestCase.assertWarns()} and
@ref{2a1,,unittest.TestCase.assertWarnsRegex()} no longer swallow warnings that
do not match the specified category or regex. Nested context managers are
now supported.

@item 
gh-149214@footnote{https://github.com/python/cpython/issues/149214}: Fix @code{_remote_debugging} misreading non-ASCII Unicode
strings (Latin-1, BMP and non-BMP) from a remote process. Filenames and
function names that contain non-ASCII characters are now reported
correctly in stack traces, the sampling profiler, and @ref{b,,asyncio} task
introspection.

@item 
gh-149189@footnote{https://github.com/python/cpython/issues/149189}: @ref{b3,,pprint} now uses modern defaults: @code{indent=4} and
@code{width=88}, and the default @code{compact=False} output is now formatted
similar to pretty-printed @ref{248,,json.dumps()}, with opening parentheses and
brackets followed by a newline and the contents indented by one level. The
`expand' parameter, added in 3.15.0a8, has been removed; @code{compact=False}
(the default) now produces the former @code{expand=True} layout. Patch by
Hugo van Kemenade.

@item 
gh-149173@footnote{https://github.com/python/cpython/issues/149173}: Fix inverted 
@geindex PYTHON_BASIC_REPL
@geindex μεταβλητή περιβάλλοντος; PYTHON_BASIC_REPL
@ref{452,,PYTHON_BASIC_REPL} environment check in
@code{pdb._pyrepl_available}.

@item 
gh-149117@footnote{https://github.com/python/cpython/issues/149117}: Fix @ref{1901,,runpy.run_module()} and @ref{6ae,,runpy.run_path()} to set
the @ref{1902,,name} attribute on the @ref{1bd,,ImportError} they
raise.

@item 
gh-149148@footnote{https://github.com/python/cpython/issues/149148}: @ref{58,,ensurepip}: Upgrade bundled pip to 26.1. This version
fixes the 
@geindex Common Vulnerabilities and Exposures; CVE 2026-3219
CVE 2026-3219@footnote{https://www.cve.org/CVERecord?id=CVE-2026-3219} vulnerability. Patch by Victor Stinner.

@item 
gh-149009@footnote{https://github.com/python/cpython/issues/149009}: Validate that @ref{b6,,profiling.sampling} binary profiles do not
contain more unique (thread, interpreter) pairs than declared in the
header. Patch by Maurycy Pawłowski-Wieroński.

@item 
gh-148292@footnote{https://github.com/python/cpython/issues/148292}: @ref{d8,,ssl}: Update @ref{cbb,,ssl.SSLSocket} and
@ref{f40,,ssl.SSLObject} for OpenSSL 4. The classes now remember if they get
a @ref{1903,,ssl.SSLEOFError}. In this case, following
@ref{121f,,read()}, @code{sendfile()},
@ref{1220,,write()}, and @ref{121e,,do_handshake()}
calls raise @code{ssl.SSLEOFError} without calling the underlying OpenSSL
function. Thanks to that, @code{ssl.SSLSocket} behaves the same on all
OpenSSL versions on EOF.  Patch by Victor Stinner.

@item 
gh-149085@footnote{https://github.com/python/cpython/issues/149085}: Add a `max_threads' keyword argument to
@ref{21a,,faulthandler.dump_traceback()},
@ref{21b,,faulthandler.dump_traceback_later()}, @ref{219,,faulthandler.enable()},
and @ref{21c,,faulthandler.register()}.

@item 
gh-148641@footnote{https://github.com/python/cpython/issues/148641}: @ref{1904,,pkgutil.resolve_name()} gets a new optional, keyword-only
argument called @code{strict}.  The default is @code{False} for backward
compatibility.

@item 
gh-148093@footnote{https://github.com/python/cpython/issues/148093}: Fix an out-of-bounds read of one byte in
@ref{1905,,binascii.a2b_uu()}. Raise @ref{13ce,,binascii.Error}, instead of reading
past the buffer end.

@item 
gh-149083@footnote{https://github.com/python/cpython/issues/149083}: @ref{1906,,dataclasses.MISSING} and @ref{1907,,dataclasses.KW_ONLY} are
now instances of @ref{18b,,sentinel}.

@item 
gh-148914@footnote{https://github.com/python/cpython/issues/148914}: Fix memoization of in-band @ref{1908,,PickleBuffer} in the
Python implementation of @ref{ab,,pickle}. Previously, identical
@code{PickleBuffer}s did not preserve identity, and empty writable
@code{PickleBuffer} memoized an empty bytearray object in place of
@code{b'@w{'}}, so the following references to @code{b'@w{'}} were unpickled as an empty
bytearray object.

@item 
gh-149026@footnote{https://github.com/python/cpython/issues/149026}: Add colour to @ref{ac,,pickletools} CLI output. Patch by Hugo van
Kemenade.

@item 
gh-148991@footnote{https://github.com/python/cpython/issues/148991}: Add colour to @ref{104,,tokenize} CLI output. Patch by Hugo van
Kemenade.

@item 
gh-138907@footnote{https://github.com/python/cpython/issues/138907}: Support 
@geindex RFC; RFC 9309
RFC 9309@footnote{https://datatracker.ietf.org/doc/html/rfc9309.html} in @ref{116,,urllib.robotparser}.

@item 
gh-148981@footnote{https://github.com/python/cpython/issues/148981}: Add `color' parameter to @ref{1e1,,ast.dump()}.

@item 
gh-148849@footnote{https://github.com/python/cpython/issues/148849}: Deprecate @ref{2f4,,http.cookies.Morsel.js_output()} and
@ref{2f5,,http.cookies.BaseCookie.js_output()}, which will be removed in Python
3.19. Use @ref{2f6,,http.cookies.Morsel.output()} or
@ref{2f7,,http.cookies.BaseCookie.output()} instead.

@item 
gh-146311@footnote{https://github.com/python/cpython/issues/146311}: Add a `canonical' keyword-only parameter to the base16, base32,
base64, base85, ascii85, and Z85 decoders in @ref{f,,base64} and
@ref{11,,binascii}. When true, encodings with non-zero padding bits
(base16/32/64) or non-canonical encodings (base85/ascii85) are rejected.
Single-character final groups in @ref{1f9,,binascii.a2b_ascii85()} and
@ref{1fb,,binascii.a2b_base85()} are now always rejected as encoding
violations, regardless of `canonical'; previously they were silently
ignored and produced no output bytes.

@item 
gh-148947@footnote{https://github.com/python/cpython/issues/148947}: Fix crash in @ref{6e6,,@@dataclasses.dataclass} with @code{slots=True}
that occurred when a function found within the class had an empty
@code{__class__} cell.

@item 
gh-148680@footnote{https://github.com/python/cpython/issues/148680}: @code{ForwardRef} objects that contain internal names to represent
known objects now show the @code{type_repr} of the known object rather than
the internal @code{__annotationlib_name_x__} name when evaluated as strings.

@item 
gh-124397@footnote{https://github.com/python/cpython/issues/124397}: The threading module added tooling to support concurrent
iterator access: @ref{27f,,threading.serialize_iterator},
@ref{280,,threading.synchronized_iterator()}, and
@ref{281,,threading.concurrent_tee()}.

@item 
gh-148801@footnote{https://github.com/python/cpython/issues/148801}: @ref{12e,,xml.etree.ElementTree}: Fix a crash in
@ref{1909,,Element.__deepcopy__} on deeply nested trees.

@item 
gh-148735@footnote{https://github.com/python/cpython/issues/148735}: @ref{12e,,xml.etree.ElementTree}: Fix a use-after-free in
@ref{190a,,Element.findtext} when the
element tree is mutated concurrently during the search.

@item 
gh-148740@footnote{https://github.com/python/cpython/issues/148740}: Fix usage for @ref{119,,uuid} command-line interface to support a
custom namespace be provided for uuid3 and uuid5.

@item 
gh-148688@footnote{https://github.com/python/cpython/issues/148688}: @ref{14,,bz2}, @ref{23,,compression.zstd}, @ref{8d,,lzma}, @ref{13c,,zlib}:
Fix a double free on memory allocation failure. Patch by Victor Stinner.

@item 
gh-148675@footnote{https://github.com/python/cpython/issues/148675}: @ref{8,,array}, @ref{de,,struct}: Add support for @code{Zd} and @code{Zf}
formats for double complex and float complex. Patch by Victor Stinner.

@item 
gh-148651@footnote{https://github.com/python/cpython/issues/148651}: Fix reference leak in
@ref{190b,,compression.zstd.ZstdDecompressor} when an invalid option key is
passed.

@item 
gh-148641@footnote{https://github.com/python/cpython/issues/148641}: 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/} (package startup configuration files) implements a
new format @code{<name>.start} parallel to @code{<name>.pth} files, to replace
@code{import} lines in the latter.

@item 
gh-148639@footnote{https://github.com/python/cpython/issues/148639}: Implement 
@geindex Python Enhancement Proposals; PEP 800
PEP 800@footnote{https://peps.python.org/pep-0800/}, adding the @ref{292,,@@typing.disjoint_base}
decorator. Patch by Jelle Zijlstra.

@item 
gh-148615@footnote{https://github.com/python/cpython/issues/148615}: Fix @ref{aa,,pdb} to accept standard – end of options separator.
Reported by haampie. Patched by Shrey Naithani.

@item 
gh-146553@footnote{https://github.com/python/cpython/issues/146553}: Fix infinite loop in @ref{a9e,,typing.get_type_hints()} when
@code{__wrapped__} forms a cycle. Patch by Shamil Abdulaev.

@item 
gh-148599@footnote{https://github.com/python/cpython/issues/148599}: Update the @ref{d4,,socket} module’s WSA error messages to match
official documentation.

@item 
gh-148508@footnote{https://github.com/python/cpython/issues/148508}: An intermittent timing error when running SSL tests on iOS has
been resolved.

@item 
gh-144881@footnote{https://github.com/python/cpython/issues/144881}: @ref{b,,asyncio} debugging tools (@code{python -m asyncio ps} and
@code{pstree}) now retry automatically on transient errors that can occur
when attaching to a process under active thread delegation. The number of
retries can be controlled with the @code{--retries} flag. Patch by Bartosz
Sławecki.

@item 
gh-148518@footnote{https://github.com/python/cpython/issues/148518}: If an email containing an address header that ended in an open
double quote was parsed with a non-@code{compat32} policy, accessing the
@code{username} attribute of the mailbox accessed through that header object
would result in an @code{IndexError}. It now correctly returns an empty
string as the result.

@item 
gh-148464@footnote{https://github.com/python/cpython/issues/148464}: Add missing @code{__ctype_le/be__} attributes for
@ref{2ce,,c_float_complex} and @ref{2cf,,c_double_complex}.
Patch by Sergey B Kirpichev.

@item 
gh-148370@footnote{https://github.com/python/cpython/issues/148370}: @ref{26,,configparser}: prevent quadratic behavior when a
@ref{914,,ParsingError} is raised after a parser fails to parse
multiple lines. Patch by Bénédikt Tran.

@item 
gh-121190@footnote{https://github.com/python/cpython/issues/121190}: @code{importlib.resources.files()} now emits a more meaningful
error message when module spec is None (as found in some @code{__main__}
modules).

@item 
gh-127012@footnote{https://github.com/python/cpython/issues/127012}: @code{importlib.abc.Traversable.read_text} now allows/solicits an
@code{errors} parameter.

@item 
gh-137855@footnote{https://github.com/python/cpython/issues/137855}: Improve import time of @ref{32,,dataclasses} module by lazy
importing @ref{c1,,re} and @ref{29,,copy} modules.

@item 
gh-148352@footnote{https://github.com/python/cpython/issues/148352}: Add more color to @ref{15,,calendar}’s CLI output. Patch by Hugo
van Kemenade.

@item 
gh-148254@footnote{https://github.com/python/cpython/issues/148254}: Use singular «sec» instead of «secs» in @ref{f8,,timeit} verbose
output for consistency with other time units.

@item 
gh-130472@footnote{https://github.com/python/cpython/issues/130472}: Integrate fancycompleter with import completions.

@item 
gh-148241@footnote{https://github.com/python/cpython/issues/148241}: @ref{85,,json}: Fix serialization: no longer call @code{str(obj)} on
@ref{1df,,str} subclasses. Patch by Victor Stinner.

@item 
gh-148225@footnote{https://github.com/python/cpython/issues/148225}: The @ref{b6,,profiling.sampling} @code{replay} command now rejects
non-binary profile files with a clear error explaining that replay only
accepts files created with @code{--binary}.

@item 
gh-148192@footnote{https://github.com/python/cpython/issues/148192}: @code{email.generator.Generator._make_boundary} could fail to
detect a duplicate boundary string if linesep was not n. It now correctly
detects boundary strings when linesep is rn as well.

@item 
gh-148207@footnote{https://github.com/python/cpython/issues/148207}: @ref{293,,typing.TypeVarTuple} now accepts @code{bound},
@code{covariant}, @code{contravariant}, and @code{infer_variance} parameters,
matching the interface of @ref{294,,typing.TypeVar} and
@ref{295,,typing.ParamSpec}.

@item 
gh-148100@footnote{https://github.com/python/cpython/issues/148100}: @ref{1a7,,Soft deprecate} @ref{24c,,re.match()} and
@ref{24d,,re.Pattern.match()} in favour of @ref{24a,,re.prefixmatch()} and
@ref{24b,,re.Pattern.prefixmatch()}. Patch by Hugo van Kemenade.

@item 
gh-147991@footnote{https://github.com/python/cpython/issues/147991}: Improve @ref{105,,tomllib} import time (up to 10x faster). Patch by
Victor Stinner.

@item 
gh-147957@footnote{https://github.com/python/cpython/issues/147957}: Guarantees that @ref{190c,,collections.UserDict.popitem()} will pop
in the same order as the wrapped dictionary rather than an arbitrary
order.

@item 
gh-146256@footnote{https://github.com/python/cpython/issues/146256}: The @code{profiling.sampling} module now supports JSONL output
format via @code{--jsonl}. Each run emits a newline-delimited JSON file that
is sequentially parseable by external tools, scripts, and programmatic
consumers. Patch by Maurycy Pawłowski-Wieroński.

@item 
gh-146609@footnote{https://github.com/python/cpython/issues/146609}: Add colour to @ref{f8,,timeit} CLI output. Patch by Hugo van
Kemenade.

@item 
gh-146563@footnote{https://github.com/python/cpython/issues/146563}: @ref{12f,,xml.parsers.expat}: add an exception note when a custom
Expat handler return value cannot be properly interpreted. Patch by
Bénédikt Tran.

@item 
gh-137586@footnote{https://github.com/python/cpython/issues/137586}: Add @code{MacOS} to @ref{11e,,webbrowser} for macOS, which opens
URLs via @code{/usr/bin/open} instead of piping AppleScript to @code{osascript}.
Deprecate @code{MacOSXOSAScript} in favour of @code{MacOS}.

@item 
gh-146406@footnote{https://github.com/python/cpython/issues/146406}: Cross-language method suggestions are now shown for
@ref{1a9,,AttributeError} on builtin types and their subclasses. For example,
@code{[].push()} suggests @code{append}, @code{(1,2).append(3)} suggests using a
@code{list}, @code{None.keys()} suggests expecting a @code{dict}, and
@code{1.0.__or__} suggests using an @code{int}.

@item 
gh-146313@footnote{https://github.com/python/cpython/issues/146313}: Fix a deadlock in @ref{98,,multiprocessing}’s resource tracker
where the parent process could hang indefinitely in @ref{1153,,os.waitpid()}
during interpreter shutdown if a child created via @ref{6bd,,os.fork()} still
held the resource tracker’s pipe open.

@item 
gh-146292@footnote{https://github.com/python/cpython/issues/146292}: Add colour to @ref{226,,BaseHTTPRequestHandler} logs,
as used by the @ref{75,,http.server} CLI. Patch by Hugo van Kemenade.

@item 
gh-145917@footnote{https://github.com/python/cpython/issues/145917}: Add MIME types for TTC and Haptics formats to @ref{93,,mimetypes}.
(Contributed by Charlie Lin in gh-145918@footnote{https://github.com/python/cpython/issues/145918}.)

@item 
gh-145846@footnote{https://github.com/python/cpython/issues/145846}: Fix memory leak in @code{_lsprof} when @code{clear()} is called
during active profiling with nested calls. @code{clearEntries()} now walks
the entire @code{currentProfilerContext} linked list instead of only freeing
the top context.

@item 
gh-145831@footnote{https://github.com/python/cpython/issues/145831}: Fix @code{email.quoprimime.decode()} leaving a stray @code{\r}
when @code{eol='\r\n'} by stripping the full `eol' string instead of one
character.

@item 
gh-145378@footnote{https://github.com/python/cpython/issues/145378}: Use @code{PyREPL} as the default input console for @ref{aa,,pdb}

@item 
gh-145244@footnote{https://github.com/python/cpython/issues/145244}: Fixed a use-after-free in @ref{85,,json} encoder when a
@code{default} callback mutates the dictionary being serialized.

@item 
gh-117716@footnote{https://github.com/python/cpython/issues/117716}: Fix @ref{11c,,wave} writing of odd-sized @code{data} chunks by
appending the required RIFF pad byte and correcting the RIFF chunk size
field accordingly.

@item 
gh-145200@footnote{https://github.com/python/cpython/issues/145200}: @ref{6b,,hashlib}: fix a memory leak when allocating or
initializing an OpenSSL HMAC context fails.

@item 
gh-145056@footnote{https://github.com/python/cpython/issues/145056}: Add support for @ref{182,,frozendict} in
@ref{190d,,dataclasses.asdict()} and @ref{190e,,dataclasses.astuple()}.

@item 
gh-145105@footnote{https://github.com/python/cpython/issues/145105}: Fix crash in @ref{2c,,csv} reader when iterating with a re-entrant
iterator that calls @ref{bb5,,next()} on the same reader from within
@code{__next__}.

@item 
gh-130750@footnote{https://github.com/python/cpython/issues/130750}: Restore quoting of choices in @ref{7,,argparse} error messages
for improved clarity and consistency with documentation.

@item 
gh-137855@footnote{https://github.com/python/cpython/issues/137855}: Reduce the import time of @ref{32,,dataclasses} module by ~20%.

@item 
gh-70647@footnote{https://github.com/python/cpython/issues/70647}: @ref{2d2,,strptime()} now raises @ref{277,,ValueError}
when the format string contains @code{%d} without a year directive. Using
@code{%e} without a year now emits a @ref{2c9,,DeprecationWarning}.

@item 
gh-105936@footnote{https://github.com/python/cpython/issues/105936}: Attempting to mutate non-field attributes of @ref{32,,dataclasses}
with both `frozen' and `slots' being @code{True} now raises
@ref{190f,,FrozenInstanceError} instead of @ref{291,,TypeError}.
Their non-dataclass subclasses can now freely mutate non-field attributes,
and the original non-slotted class can be garbage collected.

@item 
gh-142831@footnote{https://github.com/python/cpython/issues/142831}: Fix a crash in the @ref{85,,json} module where a use-after-free
could occur if the object being encoded is modified during serialization.

@item 
gh-108411@footnote{https://github.com/python/cpython/issues/108411}: @code{typing.IO} and @code{typing.BinaryIO} method arguments are now
positional-only.

@item 
gh-130273@footnote{https://github.com/python/cpython/issues/130273}: Fix traceback color output with Unicode characters.

@item 
gh-142307@footnote{https://github.com/python/cpython/issues/142307}: @ref{77,,imaplib}: deprecate support for @ref{2f8,,IMAP4.file}. This attribute was never meant to be part of the
public interface and altering its value may result in unclosed files or
other synchronization issues with the underlying socket. Patch by Bénédikt
Tran.

@item 
gh-141449@footnote{https://github.com/python/cpython/issues/141449}: Improve tests and documentation for non-function callables as
@ref{40a,,annotate functions}.

@item 
gh-140287@footnote{https://github.com/python/cpython/issues/140287}: The @ref{b,,asyncio} REPL now handles exceptions when executing
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP} scripts. Patch by Bartosz Sławecki.

@item 
gh-139489@footnote{https://github.com/python/cpython/issues/139489}: Add the @ref{2b3,,xml.is_valid_name()} function, which allows to
check whether a string can be used as an element or attribute name in XML.

@item 
gh-75707@footnote{https://github.com/python/cpython/issues/75707}: Add optional @code{mtime} argument to @ref{1228,,tarfile.open()}, for
setting the @code{mtime} header field in @code{.tar.gz} archives.

@item 
gh-125862@footnote{https://github.com/python/cpython/issues/125862}: The @ref{20e,,contextlib.contextmanager()} and
@ref{20f,,contextlib.asynccontextmanager()} decorators now work correctly with
generators, coroutine functions, and async generators when the wrapped
callables are used as decorators.

@item 
gh-135528@footnote{https://github.com/python/cpython/issues/135528}: @ref{73,,http.cookiejar}: add «tv», «or», «nom», «sch», and «web»
to the default list of supported country code second-level domains.

@item 
gh-135056@footnote{https://github.com/python/cpython/issues/135056}: Add a @code{-H} or @code{--header} CLI option to @code{python -m
http.server}. Contributed by Anton I. Sipos.

@item 
gh-134551@footnote{https://github.com/python/cpython/issues/134551}: Add t-strings support to pprint functions

@item 
gh-133956@footnote{https://github.com/python/cpython/issues/133956}: Fix bug where @ref{6e6,,@@dataclass}
wouldn’t detect @code{ClassVar} fields if @code{ClassVar} was re-exported from a
module other than @ref{10d,,typing}.

@item 
gh-132631@footnote{https://github.com/python/cpython/issues/132631}: Fix «I/O operation on closed file» when parsing JSON Lines file
with @ref{86,,JSON CLI}.

@item 
gh-108951@footnote{https://github.com/python/cpython/issues/108951}: @ref{b,,asyncio}: Add @ref{1e4,,TaskGroup.cancel} which cancels unfinished tasks and exits the
group without raising @ref{6da,,asyncio.CancelledError}.

@item 
gh-123853@footnote{https://github.com/python/cpython/issues/123853}: Update the table of Windows language code identifiers (LCIDs)
used by @ref{233,,locale.getdefaultlocale()} on Windows to protocol version
16.0 (2024-04-23).

@item 
gh-122476@footnote{https://github.com/python/cpython/issues/122476}: The @ref{3e,,email} module no longer incorrectly uses 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html}
encoding for a mailbox with non-ASCII characters in its local-part. Under
a policy with @ref{217,,utf8} set @code{False},
attempting to serialize such a message will now raise an
@ref{1910,,HeaderWriteError}. There is no valid 7-bit encoding
for an internationalized local-part. Use @ref{1911,,email.policy.SMTPUTF8} (or
another policy with @code{utf8=True}) to correctly pass through the
local-part as Unicode characters.

@item 
gh-83938@footnote{https://github.com/python/cpython/issues/83938}: The @ref{3e,,email} module no longer incorrectly uses 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html}
encoding for a mailbox with non-ASCII characters in its domain. Under a
policy with @ref{217,,utf8} set @code{False},
attempting to serialize such a message will now raise an
@ref{1910,,HeaderWriteError}. Either apply an appropriate IDNA
encoding to convert the domain to ASCII before serialization, or use
@ref{1911,,email.policy.SMTPUTF8} (or another policy with @code{utf8=True}) to
correctly pass through the internationalized domain name as Unicode
characters.

@item 
gh-81074@footnote{https://github.com/python/cpython/issues/81074}: The @ref{3e,,email} module no longer treats email addresses with
non-ASCII characters as defects when parsing a Unicode string or in the
@code{addr_spec} parameter to @ref{1912,,email.headerregistry.Address}.
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} permits such addresses, and they were already supported when
parsing bytes and in the Address @code{username} parameter.

The (undocumented) @code{email.errors.NonASCIILocalPartDefect} is no
longer used and should be considered deprecated.

@item 
gh-70039@footnote{https://github.com/python/cpython/issues/70039}: Fixed bug where @ref{14e4,,smtplib.SMTP.starttls()} could fail if
@ref{1913,,smtplib.SMTP.connect()} is called explicitly rather than implicitly.

@item 
gh-113471@footnote{https://github.com/python/cpython/issues/113471}: Allow @ref{75,,http.server} to set a default content-type when
serving files with an unknown or missing extension.

@item 
gh-83281@footnote{https://github.com/python/cpython/issues/83281}: @ref{3e,,email}: improve handling trailing garbage in address lists
to avoid throwing AttributeError in certain edge cases

@item 
gh-96894@footnote{https://github.com/python/cpython/issues/96894}: Do not turn echo off for subsequent commands in batch activators
(@code{activate.bat} and @code{deactivate.bat}) of @ref{11a,,venv}.
@end itemize

@node Documentation<2>,Tests,Library<2>,Python 3 15 0 beta 1
@anchor{whatsnew/changelog documentation}@anchor{1914}
@subsubsection Documentation



@itemize -

@item 
gh-148663@footnote{https://github.com/python/cpython/issues/148663}: Document that @ref{1915,,calendar.IllegalMonthError} is a subclass
of both @ref{277,,ValueError} and @ref{18d7,,IndexError} since Python 3.12.

@item 
gh-146646@footnote{https://github.com/python/cpython/issues/146646}: Document that @ref{2d4,,glob.glob()}, @ref{be1,,glob.iglob()},
@ref{73a,,pathlib.Path.glob()}, and @ref{73b,,pathlib.Path.rglob()} silently
suppress @ref{53c,,OSError} exceptions raised from scanning the filesystem.
@end itemize

@node Tests,Build,Documentation<2>,Python 3 15 0 beta 1
@anchor{whatsnew/changelog tests}@anchor{1916}
@subsubsection Tests



@itemize -

@item 
gh-149425@footnote{https://github.com/python/cpython/issues/149425}: Increase time delta in
@code{test.test_zipfile.test_core.OtherTests.test_write_without_source_date_epoch}

@item 
gh-148600@footnote{https://github.com/python/cpython/issues/148600}: Add OpenSSL 4.0.0 support to test configurations.
@end itemize

@node Build,Windows,Tests,Python 3 15 0 beta 1
@anchor{whatsnew/changelog build}@anchor{1917}
@subsubsection Build



@itemize -

@item 
gh-149353@footnote{https://github.com/python/cpython/issues/149353}: Avoid unnecessary JIT-related rebuilds during @code{make install}
after @code{--enable-optimizations} builds.

@item 
gh-149351@footnote{https://github.com/python/cpython/issues/149351}: Avoid possible broken macOS framework install names when
DESTDIR is specified during builds.

@item 
gh-149252@footnote{https://github.com/python/cpython/issues/149252}: Update to WASI SDK 33.

@item 
gh-148690@footnote{https://github.com/python/cpython/issues/148690}: Windows free-threaded builds now output to a different default
path with default filenames, for example, @code{PCbuild/amd64t/python.exe}
rather than @code{PCbuild/amd64/python3.15t.exe}. The @code{PC/layout} script
has been updated to ensure compatibility of generated layouts.

@item 
gh-146475@footnote{https://github.com/python/cpython/issues/146475}: Block Apple Clang from being used to build the JIT as it ships
without required LLVM tools.

@item 
gh-148644@footnote{https://github.com/python/cpython/issues/148644}: Errors during the PGO training job on Windows are no longer
ignored, and a non-zero return code will cause the build to fail.

@item 
gh-148535@footnote{https://github.com/python/cpython/issues/148535}: No longer use the @code{gcc -fprofile-update=atomic} flag on i686.
The flag has been added to fix a random GCC internal error on PGO build
(gh-145801@footnote{https://github.com/python/cpython/issues/145801}) caused by corruption of profile data (.gcda files). The
problem is that it makes the PGO build way slower (up to 47x slower) on
i686. Since the GCC internal error was not seen on i686 so far, don’t use
@code{-fprofile-update=atomic} on i686 anymore. Patch by Victor Stinner.

@item 
gh-148483@footnote{https://github.com/python/cpython/issues/148483}: Use @code{Py_GCC_ATTRIBUTE(unused)} for stop_tracing label.

@item 
gh-148474@footnote{https://github.com/python/cpython/issues/148474}: Fixed compilation of @code{Python/pystrhex.c} with older clang
versions.

@item 
gh-146445@footnote{https://github.com/python/cpython/issues/146445}: The Android build tools have been moved to the Platforms
folder.

@item 
gh-146264@footnote{https://github.com/python/cpython/issues/146264}: Fix static module builds on non-WASI targets by linking HACL
dependencies as static libraries when @code{MODULE_BUILDTYPE=static},
preventing duplicate @code{_Py_LibHacl_*} symbol errors at link time.

@item 
gh-138451@footnote{https://github.com/python/cpython/issues/138451}: Allow for custom LLVM path using @code{LLVM_TOOLS_INSTALL_DIR}
during JIT build.

@item 
gh-133312@footnote{https://github.com/python/cpython/issues/133312}: Add a new @code{./configure} option
@ref{1918,,--enable-static-libpython-for-interpreter} which, when used with
@ref{c3a,,--enable-shared}, continues to build the shared library but does
not use it for the interpreter. Instead, libpython is statically linked
into the interpreter, as if @code{--enable-shared} had not been used.
This allows you to do a single build and get a Python interpreter binary
that does not use a shared library but also get a shared library for use
by other programs.
@end itemize

@node Windows,macOS,Build,Python 3 15 0 beta 1
@anchor{whatsnew/changelog windows}@anchor{1919}
@subsubsection Windows



@itemize -

@item 
gh-149254@footnote{https://github.com/python/cpython/issues/149254}: Updated bundled version of OpenSSL to 3.5.6.

@item 
gh-148690@footnote{https://github.com/python/cpython/issues/148690}: Non-freethreaded builds on Windows now support extensions
linked to @code{python3t.dll}, and will include a copy of that library in
normal installs that references the non-freethreaded runtime.

@item 
gh-146458@footnote{https://github.com/python/cpython/issues/146458}: Fix incorrect REPL height and width tracking on console window
resize on Windows.
@end itemize

@node macOS,IDLE<3>,Windows,Python 3 15 0 beta 1
@anchor{whatsnew/changelog macos}@anchor{191a}
@subsubsection macOS



@itemize -

@item 
gh-142295@footnote{https://github.com/python/cpython/issues/142295}: For Python macOS framework builds, update Info.plist files to
be more compliant with current Apple guidelines. Original patch
contributed by Martinus Verburg.

@item 
gh-149254@footnote{https://github.com/python/cpython/issues/149254}: Update macOS installer to use OpenSSL 3.5.6.
@end itemize

@node IDLE<3>,C API,macOS,Python 3 15 0 beta 1
@anchor{whatsnew/changelog idle}@anchor{191b}
@subsubsection IDLE



@itemize -

@item 
gh-94523@footnote{https://github.com/python/cpython/issues/94523}: Detect file if modified at local disk and prompt to ask refresh.
Patch by Shixian Li.

@item 
gh-139551@footnote{https://github.com/python/cpython/issues/139551}: Support rendering @ref{767,,BaseExceptionGroup} in IDLE.

@item 
gh-89520@footnote{https://github.com/python/cpython/issues/89520}: Make IDLE extension configuration look at user config files,
allowing user-installed extensions to have settings and key bindings
defined in ~/.idlerc.
@end itemize

@node C API,,IDLE<3>,Python 3 15 0 beta 1
@anchor{whatsnew/changelog c-api}@anchor{191c}
@subsubsection C API



@itemize -

@item 
gh-149225@footnote{https://github.com/python/cpython/issues/149225}: @ref{368,,PyCriticalSection} and related functions are added to
the Stable ABI.

@item 
gh-149216@footnote{https://github.com/python/cpython/issues/149216}: @ref{191d,,PyType_WatchCallback} callbacks registered via
@ref{96a,,PyType_AddWatcher()} are now also invoked when a watched heap type
is deallocated. Previously, type watchers were only notified of
modifications, which could cause stale references when a type was freed
and its address was reused.

@item 
gh-149101@footnote{https://github.com/python/cpython/issues/149101}: Implement 
@geindex Python Enhancement Proposals; PEP 788
PEP 788@footnote{https://peps.python.org/pep-0788/}.

@item 
gh-149044@footnote{https://github.com/python/cpython/issues/149044}: Implement 
@geindex Python Enhancement Proposals; PEP 820
PEP 820@footnote{https://peps.python.org/pep-0820/}: Unified slot system for the C API.

@item 
gh-148267@footnote{https://github.com/python/cpython/issues/148267}: Using @ref{84d,,Py_LIMITED_API} on a non-Windows free-threaded
build no longer needs an extra @ref{191e,,Py_GIL_DISABLED}.

@item 
gh-145559@footnote{https://github.com/python/cpython/issues/145559}: Rename @code{_Py_DumpTraceback} and @code{_Py_DumpTracebackThreads}
to @ref{399,,PyUnstable_DumpTraceback()} and
@ref{39a,,PyUnstable_DumpTracebackThreads()}.

@item 
gh-146636@footnote{https://github.com/python/cpython/issues/146636}: Implement 
@geindex Python Enhancement Proposals; PEP 803
PEP 803@footnote{https://peps.python.org/pep-0803/} – @code{abi3t}: Stable ABI for Free-Threaded
Builds.

@item 
gh-146302@footnote{https://github.com/python/cpython/issues/146302}: @ref{191f,,Py_IsInitialized()} no longer returns true until
initialization has fully completed, including import of the @ref{cf,,site}
module.  The underlying runtime flags now use atomic operations.

@item 
gh-146063@footnote{https://github.com/python/cpython/issues/146063}: Add @ref{351,,PyObject_CallFinalizerFromDealloc()} function to the
limited C API. Patch by Victor Stinner.

@item 
gh-145921@footnote{https://github.com/python/cpython/issues/145921}: Add functions that are guaranteed to be safe for use in
@ref{36b,,tp_traverse} handlers:
@ref{36c,,PyObject_GetTypeData_DuringGC()},
@ref{36d,,PyObject_GetItemData_DuringGC()},
@ref{36e,,PyType_GetModuleState_DuringGC()},
@ref{36f,,PyModule_GetState_DuringGC()},
@ref{370,,PyModule_GetToken_DuringGC()},
@ref{371,,PyType_GetBaseByToken_DuringGC()},
@ref{372,,PyType_GetModule_DuringGC()},
@ref{373,,PyType_GetModuleByToken_DuringGC()}.
@end itemize

@node Python 3 15 0 alpha 8,Python 3 15 0 alpha 7,Python 3 15 0 beta 1,Changelog
@anchor{whatsnew/changelog python-3-15-0-alpha-8}@anchor{1920}
@subsection Python 3.15.0 alpha 8


`Release date: 2026-04-07'

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

@end menu

@node Security<3>,Core and Builtins<3>,,Python 3 15 0 alpha 8
@anchor{whatsnew/changelog id5}@anchor{1921}
@subsubsection Security



@itemize -

@item 
gh-145986@footnote{https://github.com/python/cpython/issues/145986}: @ref{12f,,xml.parsers.expat}: Fixed a crash caused by unbounded C
recursion when converting deeply nested XML content models with
@ref{1922,,ElementDeclHandler()}. This addresses
@geindex Common Vulnerabilities and Exposures; CVE 2026-4224
CVE 2026-4224@footnote{https://www.cve.org/CVERecord?id=CVE-2026-4224}.

@item 
gh-145599@footnote{https://github.com/python/cpython/issues/145599}: Reject control characters in @ref{fc3,,http.cookies.Morsel}
@ref{1277,,update()} and
@ref{2f5,,js_output()}. This addresses
@geindex Common Vulnerabilities and Exposures; CVE 2026-3644
CVE 2026-3644@footnote{https://www.cve.org/CVERecord?id=CVE-2026-3644}.

@item 
gh-143930@footnote{https://github.com/python/cpython/issues/143930}: Reject leading dashes in URLs passed to
@ref{1923,,webbrowser.open()}.
@end itemize

@node Core and Builtins<3>,Library<3>,Security<3>,Python 3 15 0 alpha 8
@anchor{whatsnew/changelog id6}@anchor{1924}
@subsubsection Core and Builtins



@itemize -

@item 
gh-148157@footnote{https://github.com/python/cpython/issues/148157}: Fix an unlikely crash when parsing an invalid type comments for
function parameters. Found by OSS Fuzz in #492782951@footnote{https://issues.oss-fuzz.com/issues/492782951}.

@item 
gh-100239@footnote{https://github.com/python/cpython/issues/100239}: Propagate result type and uniqueness information through
@code{_BINARY_OP_EXTEND} in the tier 2 optimizer, enabling elimination of
downstream type guards and selection of inplace float operations.

@item 
gh-148144@footnote{https://github.com/python/cpython/issues/148144}: Initialize @code{_PyInterpreterFrame.visited} when copying
interpreter frames so incremental GC does not read an uninitialized byte
from generator and frame-object copies.

@item 
gh-148072@footnote{https://github.com/python/cpython/issues/148072}: Cache @code{pickle.dumps} and @code{pickle.loads} per interpreter in
the XIData framework, avoiding repeated module lookups on every
cross-interpreter data transfer.  This speeds up
@ref{46a,,InterpreterPoolExecutor} for mutable types
(@code{list}, @code{dict}) by 1.7x–3.3x.

@item 
gh-148110@footnote{https://github.com/python/cpython/issues/148110}: Fix @ref{17c,,sys.set_lazy_imports_filter()} so relative lazy
imports pass the resolved imported module name to the filter callback.
Patch by Pablo Galindo.

@item 
gh-148083@footnote{https://github.com/python/cpython/issues/148083}: Constant-fold @code{_CONTAINS_OP_SET} for @ref{9d4,,frozenset}.
Patch by Donghee Na.

@item 
gh-144319@footnote{https://github.com/python/cpython/issues/144319}: Fix a bug that could cause applications with specific
allocation patterns to leak memory via Huge Pages if compiled with Huge
Page support. Patch by Pablo Galindo

@item 
gh-147985@footnote{https://github.com/python/cpython/issues/147985}: Make @ref{17ea,,PySet_Contains()} attempt a lock-free lookup,
similar to @code{set.__contains__()}.  This avoids acquiring the set
object mutex in the normal case.

@item 
gh-147856@footnote{https://github.com/python/cpython/issues/147856}: Allow the `count' argument of @ref{1d3,,bytes.replace()} to be a
keyword.

@item 
gh-146615@footnote{https://github.com/python/cpython/issues/146615}: Fix a crash in @ref{188a,,__get__()} for
@ref{d39,,METH_METHOD} descriptors when an invalid (non-type) object is
passed as the second argument. Patch by Steven Sun.

@item 
gh-146306@footnote{https://github.com/python/cpython/issues/146306}: Optimize compact integer arithmetic in the JIT by mutating
uniquely-referenced operands in place, avoiding allocation of a new int
object. Speeds up the pyperformance @code{spectral_norm} benchmark by ~10%.

@item 
gh-146587@footnote{https://github.com/python/cpython/issues/146587}: Fix type slot assignment incase of multiple slots for same name
in type object implementation. Patch by Kumar Aditya.

@item 
gh-126910@footnote{https://github.com/python/cpython/issues/126910}: Set frame pointers in @code{aarch64-unknown-linux-gnu} JIT code,
allowing most native profilers and debuggers to unwind through them. Patch
by Diego Russo

@item 
gh-146388@footnote{https://github.com/python/cpython/issues/146388}: Adds a null check to handle when the JIT optimizer runs out of
space when dealing with contradictions in @code{make_bottom}.

@item 
gh-146369@footnote{https://github.com/python/cpython/issues/146369}: Ensure @code{-X lazy_imports=none} and
@code{PYTHON_LAZY_IMPORTS=none} override @ref{17f,,__lazy_modules__}.
Patch by Hugo van Kemenade.

@item 
gh-146308@footnote{https://github.com/python/cpython/issues/146308}: Fixed multiple error handling issues in the
@code{_remote_debugging} module including a double-free in code object
caching, memory leaks on allocation failure, missing exception checks in
binary format varint decoding, reference leaks on error paths in frame
chain processing, and inconsistent thread status error reporting across
platforms. Patch by Pablo Galindo.

@item 
gh-146306@footnote{https://github.com/python/cpython/issues/146306}: Optimize float arithmetic in the JIT by mutating
uniquely-referenced operands in place, avoiding allocation of a new float
object. Speeds up the pyperformance @code{nbody} benchmark by ~19%.

@item 
gh-146128@footnote{https://github.com/python/cpython/issues/146128}: Fix a bug which could cause constant values to be partially
corrupted in AArch64 JIT code. This issue is theoretical, and hasn’t
actually been observed in unmodified Python interpreters.

@item 
gh-146250@footnote{https://github.com/python/cpython/issues/146250}: Fixed a memory leak in @ref{17e,,SyntaxError} when re-initializing
it.

@item 
gh-146245@footnote{https://github.com/python/cpython/issues/146245}: Fixed reference leaks in @ref{d4,,socket} when audit hooks raise
exceptions in @ref{1925,,socket.getaddrinfo()} and @code{socket.sendto()}.

@item 
gh-146151@footnote{https://github.com/python/cpython/issues/146151}: @ref{1d2,,memoryview} now supports the float complex
and double complex C types: formatting characters @code{'F'} and
@code{'D'} respectively.  Patch by Sergey B Kirpichev.

@item 
gh-146196@footnote{https://github.com/python/cpython/issues/146196}: Fix potential Undefined Behavior in
@ref{5e6,,PyUnicodeWriter_WriteASCII()} by adding a zero-length check. Patch
by Shamil Abdulaev.

@item 
gh-146227@footnote{https://github.com/python/cpython/issues/146227}: Fix wrong type in @code{_Py_atomic_load_uint16} in the C11 atomics
backend (@code{pyatomic_std.h}), which used a 32-bit atomic load instead of
16-bit. Found by Mohammed Zuhaib.

@item 
gh-146205@footnote{https://github.com/python/cpython/issues/146205}: Fixed a bug where @ref{133e,,select.epoll.close()},
@ref{1926,,select.kqueue.close()}, and @ref{1341,,select.devpoll.close()} silently
ignored errors.

@item 
gh-146199@footnote{https://github.com/python/cpython/issues/146199}: Comparison of code objects now handles errors correctly.

@item 
gh-145667@footnote{https://github.com/python/cpython/issues/145667}: Remove the @code{GET_ITER_YIELD_FROM} instruction, modifying
@code{SEND} to pair with @code{GET_ITER} when compiling @code{yield from}
expressions.

@item 
gh-146192@footnote{https://github.com/python/cpython/issues/146192}: Add Base32 support to @ref{11,,binascii} and improve the
performance of the Base32 converters in @ref{f,,base64}. Patch by James Seo.

@item 
gh-135871@footnote{https://github.com/python/cpython/issues/135871}: Improve multithreaded scaling of PyMutex in low-contention
scenarios by reloading the lock’s internal state, without slowing down
high-contention scenarios.

@item 
gh-146096@footnote{https://github.com/python/cpython/issues/146096}: Fixed segmentation fault when called repr for
BaseExceptionGroup with empty or 1-size tuple args.

@item 
gh-146056@footnote{https://github.com/python/cpython/issues/146056}: Fix @ref{45b,,repr()} for lists and tuples containing @code{NULL}s.

@item 
gh-145059@footnote{https://github.com/python/cpython/issues/145059}: Fixed @code{sys.lazy_modules} to include lazy modules without
submodules. Patch by Bartosz Sławecki.

@item 
gh-146041@footnote{https://github.com/python/cpython/issues/146041}: Fix free-threading scaling bottleneck in @ref{1680,,sys.intern()} and
@ref{1927,,PyObject_SetAttr()} by avoiding the interpreter-wide lock when the
string is already interned and immortalized.

@item 
gh-145990@footnote{https://github.com/python/cpython/issues/145990}: @code{python --help-env} sections are now sorted by environment
variable name.

@item 
gh-145990@footnote{https://github.com/python/cpython/issues/145990}: @code{python --help-xoptions} is now sorted by @code{-X} option name.

@item 
gh-145876@footnote{https://github.com/python/cpython/issues/145876}: @ref{1a9,,AttributeError}s and @ref{7df,,KeyError}s raised in
@code{keys()} or @code{__getitem__()} during dictionary unpacking
(@code{@{**mymapping@}} or @code{func(**mymapping)}) are no longer masked by
@ref{291,,TypeError}.

@item 
gh-127958@footnote{https://github.com/python/cpython/issues/127958}: Support tracing from function entrypoints in the JIT. Patch by
Ken Jin.

@item 
gh-145376@footnote{https://github.com/python/cpython/issues/145376}: Fix GC tracking in @code{structseq.__replace__()}.

@item 
gh-145792@footnote{https://github.com/python/cpython/issues/145792}: Fix out-of-bounds access when invoking faulthandler on a
CPython build compiled without support for VLAs.

@item 
gh-142183@footnote{https://github.com/python/cpython/issues/142183}: Avoid a pathological case where repeated calls at a specific
stack depth could be significantly slower.

@item 
gh-145779@footnote{https://github.com/python/cpython/issues/145779}: Improve scaling of @ref{69a,,classmethod()} and @ref{666,,staticmethod()}
calls in the free-threaded build by avoiding the descriptor @code{__get__}
call.

@item 
gh-145783@footnote{https://github.com/python/cpython/issues/145783}: Fix an unlikely crash in the parser when certain errors were
erroneously not propagated. Found by OSS Fuzz in #491369109@footnote{https://issues.oss-fuzz.com/issues/491369109}.

@item 
gh-145685@footnote{https://github.com/python/cpython/issues/145685}: Improve scaling of type attribute lookups in the
@ref{198,,free-threaded build} by avoiding contention on the internal type
lock.

@item 
gh-145713@footnote{https://github.com/python/cpython/issues/145713}: Make @ref{1928,,bytearray.resize()} thread-safe in the free-threaded
build by using a critical section and calling the lock-held variant of the
resize function.

@item 
gh-145036@footnote{https://github.com/python/cpython/issues/145036}: In free-threaded build, fix race condition when calling
@code{__sizeof__()} on a @ref{4d9,,list}

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Eliminate redundant refcounting for @code{MATCH_CLASS} in the JIT.

@item 
gh-69605@footnote{https://github.com/python/cpython/issues/69605}: Add @ref{92,,math.integer} to @ref{69d,,REPL} auto-completion of
imports.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Optimize @code{_ITER_CHECK_RANGE} and @code{_ITER_CHECK_LIST} in the
JIT

@item 
gh-143414@footnote{https://github.com/python/cpython/issues/143414}: Add tracking to the JIT optimizer to determine whether a
reference is uniquely owned or shared

@item 
gh-143636@footnote{https://github.com/python/cpython/issues/143636}: Fix a crash when calling @ref{6ea,,SimpleNamespace.__replace__()} on non-namespace instances. Patch by Bénédikt
Tran.

@item 
gh-126910@footnote{https://github.com/python/cpython/issues/126910}: Set frame pointers in @code{x86_64-unknown-linux-gnu} JIT code,
allowing most native profilers and debuggers to unwind through them.

@item 
gh-140594@footnote{https://github.com/python/cpython/issues/140594}: Fix an out of bounds read when a single NUL character is read
from the standard input. Patch by Shamil Abdulaev.

@item 
gh-140870@footnote{https://github.com/python/cpython/issues/140870}: Add support for module attributes in the @ref{69d,,REPL}
auto-completion of imports.
@end itemize

@node Library<3>,Documentation<3>,Core and Builtins<3>,Python 3 15 0 alpha 8
@anchor{whatsnew/changelog id7}@anchor{1929}
@subsubsection Library



@itemize -

@item 
gh-144503@footnote{https://github.com/python/cpython/issues/144503}: Fix a regression introduced in 3.14.3 and 3.13.12 where the
@ref{98,,multiprocessing} @code{forkserver} start method would fail with
@ref{1404,,BrokenPipeError} when the parent process had a very large
@ref{1609,,sys.argv}.  The argv is now passed to the forkserver as separate
command-line arguments rather than being embedded in the @code{-c} command
string, avoiding the operating system’s per-argument length limit.

@item 
gh-148153@footnote{https://github.com/python/cpython/issues/148153}: @ref{1e7,,base64.b32encode()} now always raises @ref{277,,ValueError}
instead of @ref{a97,,AssertionError} for the value of `map01' with invalid
length.

@item 
gh-73613@footnote{https://github.com/python/cpython/issues/73613}: Add the `padded' parameter in functions related to Base32 and
Base64 codecs in the @ref{11,,binascii} and @ref{f,,base64} modules. In the
encoding functions it controls  whether the pad character can be added in
the output, in the decoding functions it controls whether padding is
required in input. Padding of input no longer required in
@ref{1ee,,base64.urlsafe_b64decode()} by default.

@item 
gh-146613@footnote{https://github.com/python/cpython/issues/146613}: @ref{84,,itertools}: Fix a crash in @ref{192a,,itertools.groupby()} when
the grouper iterator is concurrently mutated.

@item 
gh-147944@footnote{https://github.com/python/cpython/issues/147944}: Accepted range for the `bytes_per_sep' argument of
@ref{111e,,bytes.hex()}, @ref{111f,,bytearray.hex()}, @ref{1120,,memoryview.hex()}, and
@ref{192b,,binascii.b2a_hex()} is now increased, so passing @code{sys.maxsize} and
@code{-sys.maxsize} is now valid.

@item 
gh-146080@footnote{https://github.com/python/cpython/issues/146080}: @ref{d8,,ssl}: fix a crash when an SNI callback tries to use an
SSL object that has already been garbage-collected. Patch by Bénédikt
Tran.

@item 
gh-146556@footnote{https://github.com/python/cpython/issues/146556}: Fix @ref{66c,,annotationlib.get_annotations()} hanging indefinitely
when called with @code{eval_str=True} on a callable that has a circular
@code{__wrapped__} chain (e.g. @code{f.__wrapped__ = f}). Cycle detection using
an id-based visited set now stops the traversal and falls back to the
globals found so far, mirroring the approach of @ref{1306,,inspect.unwrap()}.

@item 
gh-146090@footnote{https://github.com/python/cpython/issues/146090}: @ref{d7,,sqlite3}: fix a crash when
@ref{a66,,sqlite3.Connection.create_collation()} fails with SQLITE_BUSY@footnote{https://sqlite.org/rescode.html#busy}. Patch by Bénédikt Tran.

@item 
gh-146090@footnote{https://github.com/python/cpython/issues/146090}: @ref{d7,,sqlite3}: properly raise @ref{18fa,,MemoryError} instead of
@ref{3ea,,SystemError} when a context callback fails to be allocated. Patch by
Bénédikt Tran.

@item 
gh-146507@footnote{https://github.com/python/cpython/issues/146507}: Make @ref{30b,,asyncio.SelectorEventLoop()} stream transport’s
@ref{192c,,get_write_buffer_size()} O(1) by maintaining
a running byte counter instead of iterating the buffer on every call.

@item 
gh-145056@footnote{https://github.com/python/cpython/issues/145056}: Fix merging of @ref{9d5,,collections.OrderedDict} and
@ref{182,,frozendict}.

@item 
gh-145056@footnote{https://github.com/python/cpython/issues/145056}: Add support for merging @ref{192d,,collections.UserDict} and
@ref{182,,frozendict}.

@item 
gh-145633@footnote{https://github.com/python/cpython/issues/145633}: Fix @code{struct.pack('f', float)}: use @ref{b48,,PyFloat_Pack4()} to
raise @ref{c57,,OverflowError}. Patch by Sergey B Kirpichev and Victor
Stinner.

@item 
gh-146440@footnote{https://github.com/python/cpython/issues/146440}: @ref{85,,json}: Add the `array_hook' parameter to
@ref{22e,,load()} and @ref{22f,,loads()} functions: allow a callback for
JSON literal array types to customize Python lists in the resulting
decoded object. Passing combined @ref{182,,frozendict} to
`object_pairs_hook' param and @ref{1ce,,tuple} to @code{array_hook} will yield
a deeply nested immutable Python structure representing the JSON data.

@item 
gh-146431@footnote{https://github.com/python/cpython/issues/146431}: Add the `wrapcol' parameter to @ref{f,,base64} functions
@ref{1ef,,b16encode()}, @ref{1e7,,b32encode()},
@ref{1e9,,b32hexencode()}, @ref{1f0,,b85encode()} and
@ref{1e6,,z85encode()}, and @ref{11,,binascii} functions
@ref{1f6,,b2a_base32()} and @ref{1fa,,b2a_base85()}. Add the
`ignorechars' parameter to @code{base64} functions
@ref{1f1,,b16decode()}, @ref{1e8,,b32decode()},
@ref{1ea,,b32hexdecode()}, @ref{1f2,,b85decode()} and
@ref{1f3,,z85decode()}, and @code{binascii} functions
@ref{1fe,,a2b_hex()}, @ref{1ff,,unhexlify()},
@ref{1f7,,a2b_base32()} and @ref{1fb,,a2b_base85()}.

@item 
gh-146310@footnote{https://github.com/python/cpython/issues/146310}: The @ref{58,,ensurepip} module no longer looks for @code{pip-*.whl}
wheel packages in the current directory.

@item 
gh-141510@footnote{https://github.com/python/cpython/issues/141510}: Support @ref{182,,frozendict} in @ref{b0,,plistlib}, for
serialization only. Patch by Hugo van Kemenade.

@item 
gh-146238@footnote{https://github.com/python/cpython/issues/146238}: Support half-floats (type code @code{'e'} of the @ref{de,,struct}
module) in the @ref{8,,array} module.  Patch by Sergey B Kirpichev.

@item 
gh-140947@footnote{https://github.com/python/cpython/issues/140947}: Fix incorrect contextvars handling in server tasks created by
@ref{b,,asyncio}. Patch by Kumar Aditya.

@item 
gh-146151@footnote{https://github.com/python/cpython/issues/146151}: Support the float complex and double complex C types in the @ref{8,,array} module: formatting characters @code{'F'}
and @code{'D'} respectively.  Patch by Sergey B Kirpichev.

@item 
gh-143387@footnote{https://github.com/python/cpython/issues/143387}: In importlib.metadata, when a distribution file is corrupt and
there is no metadata file, calls to @code{Distribution.metadata()} (including
implicit calls from other properties like @code{.name} and @code{.requires})
will now raise a @code{MetadataNotFound} Exception. This allows callers to
distinguish between missing metadata and a degenerate (empty) metadata.
Previously, if the file was missing, an empty @code{PackageMetadata} would be
returned and would be indistinguishable from the presence of an empty
file.

@item 
gh-146228@footnote{https://github.com/python/cpython/issues/146228}: Cached FastPath objects in importlib.metadata are now cleared
on fork, avoiding broken references to zip files during fork.

@item 
gh-146171@footnote{https://github.com/python/cpython/issues/146171}: Nested @ref{1a9,,AttributeError} suggestions now include
property-backed attributes on nested objects without executing the
property getter.

@item 
gh-145410@footnote{https://github.com/python/cpython/issues/145410}: On Windows, @ref{15e8,,sysconfig.get_platform()} now gets the
platform from the @code{_sysconfig} module instead of parsing
@ref{6a8,,sys.version} string. Patch by Victor Stinner.

@item 
gh-146091@footnote{https://github.com/python/cpython/issues/146091}: Fix a bug in @ref{192e,,termios.tcsetwinsize()} where passing a
sequence that raises an exception in @code{__getitem__} would cause a
@ref{3ea,,SystemError} instead of propagating the original exception.

@item 
gh-146083@footnote{https://github.com/python/cpython/issues/146083}: Update bundled libexpat@footnote{https://libexpat.github.io/} to
version 2.7.5.

@item 
gh-146076@footnote{https://github.com/python/cpython/issues/146076}: @ref{13d,,zoneinfo}: fix crashes when deleting @code{_weak_cache} from
a @ref{cb1,,zoneinfo.ZoneInfo} subclass.

@item 
gh-123471@footnote{https://github.com/python/cpython/issues/123471}: Make concurrent iteration over @ref{1643,,itertools.zip_longest}
safe under free-threading.

@item 
gh-146075@footnote{https://github.com/python/cpython/issues/146075}: Errors when calling @ref{4a6,,functools.partial()} with a malformed
keyword will no longer crash the interpreter.

@item 
gh-146054@footnote{https://github.com/python/cpython/issues/146054}: Limit the size of @ref{192f,,encodings.search_function()} cache.
Found by OSS Fuzz in #493449985@footnote{https://issues.oss-fuzz.com/issues/493449985}.

@item 
gh-146004@footnote{https://github.com/python/cpython/issues/146004}: All @ref{178,,-X} options from the Python command line are now
propagated to child processes spawned by @ref{98,,multiprocessing}, not just
a hard-coded subset.  This makes the behavior consistent between default
«spawn» and «forkserver» start methods and the old «fork» start method.
The options that were previously not propagated are:
@code{context_aware_warnings}, @code{cpu_count}, @code{disable-remote-debug},
@code{int_max_str_digits}, @code{lazy_imports}, @code{no_debug_ranges},
@code{pathconfig_warnings}, @code{perf}, @code{perf_jit}, @code{presite},
@code{pycache_prefix}, @code{thread_inherit_context}, and
@code{warn_default_encoding}.

@item 
gh-145980@footnote{https://github.com/python/cpython/issues/145980}: Added the `alphabet' parameter in @ref{1fc,,b2a_base64()},
@ref{1fd,,a2b_base64()}, @ref{1fa,,b2a_base85()} and
@ref{1fb,,a2b_base85()} and a number of @code{*_ALPHABET} constants in
the @ref{11,,binascii} module. Removed @code{b2a_z85()} and @code{a2b_z85()}.

@item 
gh-145968@footnote{https://github.com/python/cpython/issues/145968}: Fix translation in @ref{1ec,,base64.b64decode()} when altchars
overlaps with the standard ones.

@item 
gh-145966@footnote{https://github.com/python/cpython/issues/145966}: Non-@ref{1a9,,AttributeError} exceptions raised during dialect
attribute lookup in @ref{2c,,csv} are no longer silently suppressed.

@item 
gh-145883@footnote{https://github.com/python/cpython/issues/145883}: @ref{13d,,zoneinfo}: Fix heap buffer overflow reads from malformed
TZif data. Found by OSS Fuzz, issues #492245058@footnote{https://issues.oss-fuzz.com/issues/492245058} and
#492230068@footnote{https://issues.oss-fuzz.com/issues/492230068}.

@item 
gh-145850@footnote{https://github.com/python/cpython/issues/145850}: Changed some implementation details in @ref{2fb,,struct.Struct}:
calling it with non-ASCII string format will now raise a @ref{277,,ValueError}
instead of @ref{a67,,UnicodeEncodeError}, calling it with non-ASCII bytes
format will now raise a @code{ValueError} instead of @ref{16c8,,struct.error},
getting the @code{format} attribute of uninitialized object will now
raise an @ref{1a9,,AttributeError} instead of @ref{30d,,RuntimeError}.

@item 
gh-123720@footnote{https://github.com/python/cpython/issues/123720}: asyncio: Fix @ref{ed9,,asyncio.Server.serve_forever()} shutdown
regression. Since 3.12, cancelling @code{serve_forever()} could hang waiting
for a handler blocked on a read from a client that never closed
(effectively requiring two interrupts to stop); the shutdown sequence now
ensures client streams are closed so @code{serve_forever()} exits promptly
and handlers observe EOF.

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: The @code{profiling.sampling} module now supports differential
flamegraph visualization via @code{--diff-flamegraph} to compare two
profiling runs. Functions are colored red (regressions), blue
(improvements), gray (neutral), or purple (new). Elided stacks show code
paths that disappeared between runs.

@item 
gh-145754@footnote{https://github.com/python/cpython/issues/145754}: Request signature during mock autospec with @code{FORWARDREF}
annotation format. This prevents runtime errors when an annotation uses a
name that is not defined at runtime.

@item 
gh-145750@footnote{https://github.com/python/cpython/issues/145750}: Avoid undefined behaviour from signed integer overflow when
parsing format strings in the @ref{de,,struct} module. Found by OSS Fuzz in
#488466741@footnote{https://issues.oss-fuzz.com/issues/488466741}.

@item 
gh-145719@footnote{https://github.com/python/cpython/issues/145719}: Add @code{application/efi} MIME type to @ref{93,,mimetypes}.

@item 
gh-145717@footnote{https://github.com/python/cpython/issues/145717}: Add a few Microsoft-specific MIME types.

@item 
gh-145703@footnote{https://github.com/python/cpython/issues/145703}: @ref{b,,asyncio}: Make sure that @ref{ecb,,loop.call_at} and @ref{eca,,loop.call_later} trigger scheduled events on time when the clock
resolution becomes too small.

@item 
gh-145697@footnote{https://github.com/python/cpython/issues/145697}: Add @code{application/sql} and @code{application/vnd.sqlite3} into
@code{mimetypes}.

@item 
gh-145492@footnote{https://github.com/python/cpython/issues/145492}: Fix infinite recursion in @ref{1565,,collections.defaultdict}
@code{__repr__} when a @code{defaultdict} contains itself. Based on analysis by
KowalskiThomas in gh-145492@footnote{https://github.com/python/cpython/issues/145492}.

@item 
gh-145650@footnote{https://github.com/python/cpython/issues/145650}: Add @ref{1bc,,__repr__()} support to
@ref{1839,,logging.Formatter} and @ref{15a4,,logging.Filter}, showing the format
string and filter name respectively.

@item 
gh-145587@footnote{https://github.com/python/cpython/issues/145587}: Resolved a performance regression in
@code{multiprocessing.connection.wait} on Windows that caused infinite busy
loops when called with no objects. The function now properly yields
control to the OS to conserve CPU resources. Patch By Shrey Naithani

@item 
gh-145616@footnote{https://github.com/python/cpython/issues/145616}: Detect Android sysconfig ABI correctly on 32-bit ARM Android on
64-bit ARM kernel

@item 
gh-145546@footnote{https://github.com/python/cpython/issues/145546}: Fix @code{unittest.util.sorted_list_difference()} to deduplicate
remaining elements when one input list is exhausted before the other.

@item 
gh-145446@footnote{https://github.com/python/cpython/issues/145446}: Now @ref{62,,functools} is safer in free-threaded build when using
keywords in @ref{4a6,,functools.partial()}

@item 
gh-145264@footnote{https://github.com/python/cpython/issues/145264}: Base64 decoder (see @ref{1fd,,binascii.a2b_base64()},
@ref{1ec,,base64.b64decode()}, etc) no longer ignores excess data after the
first padded quad in non-strict (default) mode.  Instead, in conformance
with 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}, section 3.3, it now ignores the pad character, «=», if
it is present before the end of the encoded data.

@item 
gh-145035@footnote{https://github.com/python/cpython/issues/145035}: Allows omitting the internal library @code{_pyrepl} with limited
loss of functionality. This allows complete removal of the modern REPL,
which is an unsupported configuration, but still desirable for some
distributions.

@item 
gh-144270@footnote{https://github.com/python/cpython/issues/144270}: Made the `tag' parameter of
@ref{343,,xml.etree.ElementTree.Element} and the `parent' and `tag'
parameters of @ref{1930,,xml.etree.ElementTree.SubElement()} positional-only,
matching the behavior of the C accelerator.

@item 
gh-144984@footnote{https://github.com/python/cpython/issues/144984}: Fix crash in
@ref{1931,,xml.parsers.expat.xmlparser.ExternalEntityParserCreate()} when an
allocation fails. The error paths could dereference NULL @code{handlers} and
double-decrement the parent parser’s reference count.

@item 
gh-144975@footnote{https://github.com/python/cpython/issues/144975}: @ref{1932,,wave.Wave_write.setframerate()} now validates the frame
rate after rounding to an integer, preventing values like @code{0.5} from
being accepted and causing confusing errors later. Patch by Michiel
Beijen.

@item 
gh-140715@footnote{https://github.com/python/cpython/issues/140715}: Add @code{%n} and @code{%t} support to
@ref{2d2,,strptime()}.

@item 
gh-144259@footnote{https://github.com/python/cpython/issues/144259}: Fix inconsistent display of long multiline pasted content in
the REPL.

@item 
gh-140814@footnote{https://github.com/python/cpython/issues/140814}: @ref{1933,,multiprocessing.freeze_support()} no longer sets the
default start method as a side effect, which previously caused a
subsequent @ref{4d7,,multiprocessing.set_start_method()} call to raise
@ref{30d,,RuntimeError}.

@item 
gh-123471@footnote{https://github.com/python/cpython/issues/123471}: Make concurrent iteration over @ref{dbf,,itertools.accumulate}
safe under free-threading.

@item 
gh-143715@footnote{https://github.com/python/cpython/issues/143715}: Calling the @code{Struct.__new__()} without required argument now
is deprecated. Calling @ref{2fa,,__init__()} method on initialized
@ref{2fb,,Struct} objects is deprecated.

@item 
gh-142763@footnote{https://github.com/python/cpython/issues/142763}: Fix a race condition between @ref{cb1,,zoneinfo.ZoneInfo}
creation and @ref{1934,,zoneinfo.ZoneInfo.clear_cache()} that could raise
@ref{7df,,KeyError}.

@item 
gh-141707@footnote{https://github.com/python/cpython/issues/141707}: Don’t change @ref{15b8,,tarfile.TarInfo} type from @code{AREGTYPE} to
@code{DIRTYPE} when parsing GNU long name or link headers.

@item 
gh-138577@footnote{https://github.com/python/cpython/issues/138577}: @ref{4ab,,getpass.getpass()} with non-empty @code{echo_char} now
handles keyboard shortcuts including Ctrl+A/E (cursor movement), Ctrl+K/U
(kill line), Ctrl+W (erase word), and Ctrl+V (literal next) by reading the
terminal’s control character settings and processing them appropriately in
non-canonical mode. Patch by Sanyam Khurana.

@item 
gh-140049@footnote{https://github.com/python/cpython/issues/140049}: @ref{c26,,traceback.format_exception_only()} now colorizes exception
notes.

@item 
gh-139933@footnote{https://github.com/python/cpython/issues/139933}: Improve @ref{1a9,,AttributeError} suggestions for classes with a
custom @ref{1935,,__dir__()} method returning a list of unsortable
values. Patch by Bénédikt Tran.

@item 
gh-139633@footnote{https://github.com/python/cpython/issues/139633}: The @ref{9f,,netrc} security check is now run once per parse
rather than once per entry.

@item 
gh-130472@footnote{https://github.com/python/cpython/issues/130472}: Add fancycompleter and enable it by default when using pyrepl.
This gives colored tab completion.

@item 
gh-112632@footnote{https://github.com/python/cpython/issues/112632}: Add an `expand' keyword argument for @ref{c01,,pprint.pprint()},
@ref{132a,,pprint.pformat()}, @ref{de7,,pprint.pp()} by passing on all `kwargs' and
@ref{1329,,pprint.PrettyPrinter}. Contributed by Stefan Todoran and Semyon
Moroz.

@item 
gh-66419@footnote{https://github.com/python/cpython/issues/66419}: Optional argument with @ref{1936,,nargs} equals to
@code{argparse.REMAINDER} now consumes all remaining arguments including
@code{'--'}.

@item 
gh-60729@footnote{https://github.com/python/cpython/issues/60729}: Add support for floating point audio wave files in @ref{11c,,wave}.

@item 
bpo-36461@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36461}: Make the target time of @ref{283,,timeit.Timer.autorange()}
configurable and add @code{--target-time} option to the command-line
interface of @ref{f8,,timeit}.
@end itemize

@node Documentation<3>,Tests<2>,Library<3>,Python 3 15 0 alpha 8
@anchor{whatsnew/changelog id9}@anchor{1937}
@subsubsection Documentation



@itemize -

@item 
gh-126676@footnote{https://github.com/python/cpython/issues/126676}: Expand @ref{7,,argparse} documentation for @code{type=bool} with a
demonstration of the surprising behavior and pointers to common
alternatives.

@item 
gh-145649@footnote{https://github.com/python/cpython/issues/145649}: Fix text wrapping and formatting of @code{-X} option descriptions
in the @code{python(1)@footnote{https://manpages.debian.org/python(1)}} man page by using proper roff markup.
@end itemize

@node Tests<2>,Build<2>,Documentation<3>,Python 3 15 0 alpha 8
@anchor{whatsnew/changelog id10}@anchor{1938}
@subsubsection Tests



@itemize -

@item 
gh-144418@footnote{https://github.com/python/cpython/issues/144418}: The Android testbed’s emulator RAM has been increased from 2 GB
to 4 GB.

@item 
gh-146202@footnote{https://github.com/python/cpython/issues/146202}: Fix a race condition in regrtest: make sure that the temporary
directory is created in the worker process. Previously, temp_cwd() could
fail on Windows if the «build» directory was not created.  Patch by Victor
Stinner.
@end itemize

@node Build<2>,Windows<2>,Tests<2>,Python 3 15 0 alpha 8
@anchor{whatsnew/changelog id11}@anchor{1939}
@subsubsection Build



@itemize -

@item 
gh-146541@footnote{https://github.com/python/cpython/issues/146541}: The Android testbed can now be built for 32-bit ARM and x86
targets.

@item 
gh-146498@footnote{https://github.com/python/cpython/issues/146498}: The iOS XCframework build script now ensures libpython isn’t
included in installed app content, and is more robust in identifying
standard library binary content that requires processing.

@item 
gh-146450@footnote{https://github.com/python/cpython/issues/146450}: The Android build script was modified to improve parity with
other platform build scripts.

@item 
gh-146446@footnote{https://github.com/python/cpython/issues/146446}: The clean target for the Apple/iOS XCframework build script is
now more selective when targeting a single architecture.

@item 
gh-146444@footnote{https://github.com/python/cpython/issues/146444}: The Apple/iOS build script has been moved to the Platforms
directory.

@item 
gh-146210@footnote{https://github.com/python/cpython/issues/146210}: Fix building the jit stencils on Windows when the interpreter
is built with a different clang version. Patch by Chris Eibl.

@item 
gh-145844@footnote{https://github.com/python/cpython/issues/145844}: Update to WASI SDK 32.

@item 
gh-145801@footnote{https://github.com/python/cpython/issues/145801}: When Python build is optimized with GCC using PGO, use
@code{-fprofile-update=atomic} option to use atomic operations when updating
profile information. This option reduces the risk of gcov Data Files
(.gcda) corruption which can cause random GCC crashes. Patch by Victor
Stinner.

@item 
gh-138850@footnote{https://github.com/python/cpython/issues/138850}: Add @ref{193a,,--disable-epoll} to @code{configure}

@item 
gh-145633@footnote{https://github.com/python/cpython/issues/145633}: Remove support for ancient ARM platforms (ARMv4L and ARMv5L
OABI boards), using mixed-endian representation for doubles.  Patch by
Sergey B Kirpichev.

@item 
gh-85277@footnote{https://github.com/python/cpython/issues/85277}: Fix building without @code{stropts.h} or empty @code{stropts.h}
@end itemize

@node Windows<2>,macOS<2>,Build<2>,Python 3 15 0 alpha 8
@anchor{whatsnew/changelog id12}@anchor{193b}
@subsubsection Windows



@itemize -

@item 
gh-140131@footnote{https://github.com/python/cpython/issues/140131}: Fix REPL cursor position on Windows when module completion
suggestion line hits console width.
@end itemize

@node macOS<2>,Tools/Demos,Windows<2>,Python 3 15 0 alpha 8
@anchor{whatsnew/changelog id13}@anchor{193c}
@subsubsection macOS



@itemize -

@item 
gh-137586@footnote{https://github.com/python/cpython/issues/137586}: Invoke @code{osascript} with absolute path in
@ref{11e,,webbrowser} and @code{turtledemo}.
@end itemize

@node Tools/Demos,C API<2>,macOS<2>,Python 3 15 0 alpha 8
@anchor{whatsnew/changelog tools-demos}@anchor{193d}
@subsubsection Tools/Demos



@itemize -

@item 
gh-135953@footnote{https://github.com/python/cpython/issues/135953}: Properly identify the main thread in the Gecko profiler
collector by using a status flag from the interpreter state instead of
relying on @ref{137b,,threading.main_thread()} in the collector process.

@item 
gh-145976@footnote{https://github.com/python/cpython/issues/145976}: Remove @code{Misc/indent.pro}, a configuration file for GNU
@code{indent(1)@footnote{https://manpages.debian.org/indent(1)}}.

@item 
gh-145976@footnote{https://github.com/python/cpython/issues/145976}: Remove @code{Misc/vgrindefs} and @code{Misc/Porting}.
@end itemize

@node C API<2>,,Tools/Demos,Python 3 15 0 alpha 8
@anchor{whatsnew/changelog id14}@anchor{193e}
@subsubsection C API



@itemize -

@item 
gh-146636@footnote{https://github.com/python/cpython/issues/146636}: The @ref{358,,Py_mod_abi} slot is now mandatory for modules
created from a slots array (using @ref{38c,,PyModule_FromSlotsAndSpec()} or
the @ref{19c,,PyModExport_*} export hook).

@item 
gh-146175@footnote{https://github.com/python/cpython/issues/146175}: The following macros are @ref{1a7,,soft deprecated}:
@ref{3c5,,Py_ALIGNED}, @ref{3c6,,PY_FORMAT_SIZE_T}, @ref{3c7,,Py_LL},
@ref{3c8,,Py_ULL}, @ref{3c9,,PY_LONG_LONG}, @ref{3ca,,PY_LLONG_MIN},
@ref{3cb,,PY_LLONG_MAX}, @ref{3cc,,PY_ULLONG_MAX}, @ref{3cd,,PY_INT32_T},
@ref{3ce,,PY_UINT32_T}, @ref{3cf,,PY_INT64_T}, @ref{3d0,,PY_UINT64_T},
@ref{3d1,,PY_SIZE_MAX}, @ref{3d2,,Py_UNICODE_SIZE}, @ref{3d3,,Py_VA_COPY}.

The macro @ref{3d4,,Py_UNICODE_WIDE}, which was scheduled for removal, is
@ref{1a7,,soft deprecated} instead.

@item 
gh-146143@footnote{https://github.com/python/cpython/issues/146143}: @ref{5eb,,PyUnicodeWriter_WriteUCS4()} now accepts a pointer to a
constant buffer of @code{Py_UCS4}.

@item 
gh-146056@footnote{https://github.com/python/cpython/issues/146056}: @ref{5e8,,PyUnicodeWriter_WriteRepr()} now supports @code{NULL}
argument.

@item 
gh-145010@footnote{https://github.com/python/cpython/issues/145010}: Use GCC dialect alternatives for inline assembly in
@code{object.h} so that the Python headers compile correctly with
@code{-masm=intel}.
@end itemize

@node Python 3 15 0 alpha 7,Python 3 15 0 alpha 6,Python 3 15 0 alpha 8,Changelog
@anchor{whatsnew/changelog python-3-15-0-alpha-7}@anchor{193f}
@subsection Python 3.15.0 alpha 7


`Release date: 2026-03-10'

@menu
* Windows: Windows<3>. 
* Tests: Tests<3>. 
* Security: Security<4>. 
* Library: Library<4>. 
* Documentation: Documentation<4>. 
* Core and Builtins: Core and Builtins<4>. 
* C API: C API<3>. 
* Build: Build<3>. 

@end menu

@node Windows<3>,Tests<3>,,Python 3 15 0 alpha 7
@anchor{whatsnew/changelog id15}@anchor{1940}
@subsubsection Windows



@itemize -

@item 
gh-145731@footnote{https://github.com/python/cpython/issues/145731}: Fix negative timestamp during DST on Windows. Patch by Hugo van
Kemenade.

@item 
gh-145307@footnote{https://github.com/python/cpython/issues/145307}: Defers loading of the @code{psapi.dll} module until it is used by
@ref{483,,ctypes.util.dllist()}.

@item 
gh-144551@footnote{https://github.com/python/cpython/issues/144551}: Updated bundled version of OpenSSL to 3.5.5.
@end itemize

@node Tests<3>,Security<4>,Windows<3>,Python 3 15 0 alpha 7
@anchor{whatsnew/changelog id16}@anchor{1941}
@subsubsection Tests



@itemize -

@item 
gh-144741@footnote{https://github.com/python/cpython/issues/144741}: Fix @code{test_frame_pointer_unwind} when Python is built with
@ref{c3a,,--enable-shared}. Classify also libpython frames as @code{"python"}.
Patch by Victor Stinner.

@item 
gh-144739@footnote{https://github.com/python/cpython/issues/144739}: When Python was compiled with system expat older then 2.7.2 but
tests run with newer expat, still skip
@code{test.test_pyexpat.MemoryProtectionTest}.
@end itemize

@node Security<4>,Library<4>,Tests<3>,Python 3 15 0 alpha 7
@anchor{whatsnew/changelog id17}@anchor{1942}
@subsubsection Security



@itemize -

@item 
gh-145506@footnote{https://github.com/python/cpython/issues/145506}: Fixes 
@geindex Common Vulnerabilities and Exposures; CVE 2026-2297
CVE 2026-2297@footnote{https://www.cve.org/CVERecord?id=CVE-2026-2297} by ensuring that
@code{SourcelessFileLoader} uses @ref{1943,,io.open_code()} when opening @code{.pyc}
files.

@item 
gh-144370@footnote{https://github.com/python/cpython/issues/144370}: Disallow usage of control characters in status in
@ref{122,,wsgiref.handlers} to prevent HTTP header injections. Patch by
Benedikt Johannes.
@end itemize

@node Library<4>,Documentation<4>,Security<4>,Python 3 15 0 alpha 7
@anchor{whatsnew/changelog id18}@anchor{1944}
@subsubsection Library



@itemize -

@item 
gh-145623@footnote{https://github.com/python/cpython/issues/145623}: Fix crash in @ref{de,,struct} when calling @ref{45b,,repr()} or
@code{__sizeof__()} on an uninitialized @ref{2fb,,struct.Struct} object created
via @code{Struct.__new__()} without calling @code{__init__()}.

@item 
gh-145551@footnote{https://github.com/python/cpython/issues/145551}: Fix InvalidStateError when cancelling process created by
@ref{e3a,,asyncio.create_subprocess_exec()} or
@ref{e3b,,asyncio.create_subprocess_shell()}. Patch by Daan De Meyer.

@item 
gh-141510@footnote{https://github.com/python/cpython/issues/141510}: @ref{90,,marshal} now supports @ref{182,,frozendict} objects. The
marshal format version was increased to 6. Patch by Victor Stinner.

@item 
gh-145417@footnote{https://github.com/python/cpython/issues/145417}: @ref{11a,,venv}: Prevent incorrect preservation of SELinux context
when copying the @code{Activate.ps1} script. The script inherited the SELinux
security context of the system template directory, rather than the
destination project directory.

@item 
gh-145335@footnote{https://github.com/python/cpython/issues/145335}: @code{os.listdir(-1)} and @code{os.scandir(-1)} now fail with
@code{OSError(errno.EBADF)} rather than listing the current directory.
@code{os.listxattr(-1)} now fails with @code{OSError(errno.EBADF)} rather than
listing extended attributes of the current directory. Patch by Victor
Stinner.

@item 
gh-145376@footnote{https://github.com/python/cpython/issues/145376}: Fix double free and null pointer dereference in unusual error
scenarios in @ref{6b,,hashlib} and @ref{6d,,hmac} modules.

@item 
gh-145301@footnote{https://github.com/python/cpython/issues/145301}: @ref{6d,,hmac}: fix a crash when the initialization of the
underlying C extension module fails.

@item 
gh-145301@footnote{https://github.com/python/cpython/issues/145301}: @ref{6b,,hashlib}: fix a crash when the initialization of the
underlying C extension module fails.

@item 
gh-76007@footnote{https://github.com/python/cpython/issues/76007}: The @code{version} attribute of the @ref{e7,,tarfile} module is
deprecated and slated for removal in Python 3.20.

@item 
gh-145158@footnote{https://github.com/python/cpython/issues/145158}: Avoid undefined behaviour from signed integer overflow when
parsing format strings in the @ref{de,,struct} module.

@item 
gh-123853@footnote{https://github.com/python/cpython/issues/123853}: Removed Windows 95 compatibility for
@ref{233,,locale.getdefaultlocale()}.

@item 
gh-66802@footnote{https://github.com/python/cpython/issues/66802}: Add @ref{29d,,unicodedata.block()} function to return the Unicode block@footnote{https://www.unicode.org/versions/Unicode17.0.0/core-spec/chapter-3/#G64189}
of a character.

@item 
gh-145033@footnote{https://github.com/python/cpython/issues/145033}: Add @ref{28f,,typing.TypeForm}, implementing 
@geindex Python Enhancement Proposals; PEP 747
PEP 747@footnote{https://peps.python.org/pep-0747/}. Patch by
Jelle Zijlstra.

@item 
gh-141510@footnote{https://github.com/python/cpython/issues/141510}: @ref{1945,,dataclasses.field()}: if `metadata' is @code{None}, use an
empty @ref{182,,frozendict}, instead of a @ref{189,,MappingProxyType()} of
an empty @ref{188,,dict}. Patch by Victor Stinner.

@item 
gh-145006@footnote{https://github.com/python/cpython/issues/145006}: Add @ref{1be,,ModuleNotFoundError} hints when a module for a
different ABI exists.

@item 
gh-141510@footnote{https://github.com/python/cpython/issues/141510}: @code{ParameterizedMIMEHeader.params} of
@ref{45,,email.headerregistry} is now a @ref{182,,frozendict} instead of a
@ref{189,,types.MappingProxyType}. Patch by Victor Stinner.

@item 
gh-134872@footnote{https://github.com/python/cpython/issues/134872}: Add valid import name suggestions on
@ref{1be,,ModuleNotFoundError}.

@item 
gh-88091@footnote{https://github.com/python/cpython/issues/88091}: Fix @ref{1946,,unicodedata.decomposition()} for Hangul characters.

@item 
gh-144986@footnote{https://github.com/python/cpython/issues/144986}: Fix a memory leak in @ref{c54,,atexit.register()}. Patch by Shamil
Abdulaev.

@item 
gh-144777@footnote{https://github.com/python/cpython/issues/144777}: Fix data races in @ref{1947,,io.IncrementalNewlineDecoder} in the
@ref{198,,free-threaded build}.

@item 
gh-144809@footnote{https://github.com/python/cpython/issues/144809}: Make @ref{9d6,,collections.deque} copy atomic in the
@ref{198,,free-threaded build}.

@item 
gh-141510@footnote{https://github.com/python/cpython/issues/141510}: The @ref{29,,copy} module now supports the @ref{182,,frozendict}
type. Patch by Pieter Eendebak based on work by Victor Stinner.

@item 
gh-141510@footnote{https://github.com/python/cpython/issues/141510}: The @ref{85,,json} module now supports the @ref{182,,frozendict}
type. Patch by Victor Stinner.

@item 
gh-144835@footnote{https://github.com/python/cpython/issues/144835}: Added missing explanations for some parameters in
@ref{2d4,,glob.glob()} and @ref{be1,,glob.iglob()}.

@item 
gh-144833@footnote{https://github.com/python/cpython/issues/144833}: Fixed a use-after-free in @ref{d8,,ssl} when @code{SSL_new()} returns
NULL in @code{newPySSLSocket()}. The error was reported via a dangling
pointer after the object had already been freed.

@item 
gh-140715@footnote{https://github.com/python/cpython/issues/140715}: Add @code{'%D'} support to @ref{2d2,,strptime()}.

@item 
gh-144782@footnote{https://github.com/python/cpython/issues/144782}: Fix @ref{1dc,,argparse.ArgumentParser} to be @ref{ab,,pickleable}.

@item 
gh-144763@footnote{https://github.com/python/cpython/issues/144763}: Fix a race condition in @ref{108,,tracemalloc}: it no longer
detaches the attached thread state to acquire its internal lock. Patch by
Victor Stinner.

@item 
gh-142224@footnote{https://github.com/python/cpython/issues/142224}: @ref{1948,,unicodedata.bidirectional()} now return the correct
default bidi class for unassigned code points.

@item 
gh-117865@footnote{https://github.com/python/cpython/issues/117865}: Reduce the import time of @ref{81,,inspect} module by ~20%.

@item 
gh-144156@footnote{https://github.com/python/cpython/issues/144156}: Fix the folding of headers by the @ref{3e,,email} library when
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} encoded words are used.  Now whitespace is correctly preserved
and also correctly added between adjacent encoded words.  The latter
property was broken by the fix for gh-92081@footnote{https://github.com/python/cpython/issues/92081}, which mostly fixed previous
failures to preserve whitespace.

@item 
gh-66305@footnote{https://github.com/python/cpython/issues/66305}: Fixed a hang on Windows in the @ref{e9,,tempfile} module when
trying to create a temporary file or subdirectory in a non-writable
directory.

@item 
gh-144615@footnote{https://github.com/python/cpython/issues/144615}: Methods directly decorated with
@ref{21e,,@@functools.singledispatchmethod} now dispatch on the second argument
when called after being accessed as class attributes. Patch by Bartosz
Sławecki.

@item 
gh-144321@footnote{https://github.com/python/cpython/issues/144321}: The functional syntax for creating @ref{2e4,,typing.NamedTuple}
classes now supports passing any @ref{15ce,,iterable} of fields and types.
Previously, only sequences were supported.

@item 
gh-144475@footnote{https://github.com/python/cpython/issues/144475}: Calling @ref{45b,,repr()} on @ref{4a6,,functools.partial()} is now safer
when the partial object’s internal attributes are replaced while the
string representation is being generated.

@item 
gh-144285@footnote{https://github.com/python/cpython/issues/144285}: Attribute suggestions in @ref{1a9,,AttributeError} tracebacks are
now formatted differently to make them easier to understand, for example:
@code{Did you mean '.datetime.now' instead of '.now'}. Contributed by Bartosz
Sławecki.

@item 
gh-144316@footnote{https://github.com/python/cpython/issues/144316}: Fix crash in @code{_remote_debugging} that caused
@code{test_external_inspection} to intermittently fail. Patch by Taegyun Kim.

@item 
gh-143637@footnote{https://github.com/python/cpython/issues/143637}: Fixed a crash in socket.sendmsg() that could occur if ancillary
data is mutated re-entrantly during argument parsing.

@item 
gh-140652@footnote{https://github.com/python/cpython/issues/140652}: Fix a crash in @code{_interpchannels.list_all()} after closing
a channel.

@item 
gh-143698@footnote{https://github.com/python/cpython/issues/143698}: Allow `scheduler' and `setpgroup' arguments to be explicitly
@ref{a65,,None} when calling @ref{731,,os.posix_spawn()} or
@ref{1949,,os.posix_spawnp()}. Patch by Bénédikt Tran.

@item 
gh-143698@footnote{https://github.com/python/cpython/issues/143698}: Raise @ref{291,,TypeError} instead of @ref{3ea,,SystemError} when the
`scheduler' in @ref{731,,os.posix_spawn()} or @ref{1949,,os.posix_spawnp()} is not a
tuple. Patch by Bénédikt Tran.

@item 
gh-142516@footnote{https://github.com/python/cpython/issues/142516}: @ref{d8,,ssl}: fix reference leaks in @ref{336,,ssl.SSLContext}
objects. Patch by Bénédikt Tran.

@item 
gh-85809@footnote{https://github.com/python/cpython/issues/85809}: Added @ref{79f,,path-like object} support for
@ref{8c3,,shutil.make_archive()}.

@item 
gh-143304@footnote{https://github.com/python/cpython/issues/143304}: Fix @ref{dad,,ctypes.CDLL} to honor the @code{handle} parameter on
POSIX systems.

@item 
gh-142781@footnote{https://github.com/python/cpython/issues/142781}: @ref{13d,,zoneinfo}: fix a crash when instantiating
@ref{cb1,,ZoneInfo} objects for which the internal class-level
cache is inconsistent.

@item 
gh-142787@footnote{https://github.com/python/cpython/issues/142787}: Fix assertion failure in @ref{d7,,sqlite3} blob subscript when
slicing with indices that result in an empty slice.

@item 
gh-142352@footnote{https://github.com/python/cpython/issues/142352}: Fix @ref{9fa,,asyncio.StreamWriter.start_tls()} to transfer buffered
data from @ref{194a,,StreamReader} to the SSL layer, preventing data
loss when upgrading a connection to TLS mid-stream (e.g., when
implementing PROXY protocol support).

@item 
gh-139899@footnote{https://github.com/python/cpython/issues/139899}: Introduced @ref{194b,,importlib.abc.MetaPathFinder.discover()} and
@ref{194c,,importlib.abc.PathEntryFinder.discover()} to allow module and
submodule name discovery without assuming the use of traditional
filesystem based imports.

@item 
gh-137335@footnote{https://github.com/python/cpython/issues/137335}: Get rid of any possibility of a name conflict for named pipes
in @ref{98,,multiprocessing} and @ref{b,,asyncio} on Windows, no matter how
small.

@item 
gh-135883@footnote{https://github.com/python/cpython/issues/135883}: Fix @ref{d7,,sqlite3}’s @ref{257,,interactive shell}
keeping part of previous commands when scrolling history.

@item 
gh-124748@footnote{https://github.com/python/cpython/issues/124748}: Improve @ref{291,,TypeError} error message when
@code{weakref.WeakKeyDictionary.update()} is used with keyword-only
parameters.

@item 
gh-80667@footnote{https://github.com/python/cpython/issues/80667}: Add support for Tangut Ideographs names in @ref{10e,,unicodedata}.

@item 
bpo-42353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42353}: The @ref{c1,,re} module gains a new @ref{24a,,re.prefixmatch()}
function as an explicit spelling of what has to date always been known as
@ref{24c,,re.match()}. @ref{194d,,re.Pattern} similary gains a
@ref{24b,,re.Pattern.prefixmatch()} method.

Why? Explicit is better than implicit. Other widely used languages all use
the term «match» to mean what Python uses the term «search» for. The
unadorened «match» name in Python has been a frequent case of confusion
and coding bugs due to the inconsistency with the rest if the software
industry.

We do not plan to deprecate and remove the older @code{match} name.

@item 
bpo-40243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40243}: Fix @code{unicodedata.ucd_3_2_0.numeric()} for non-decimal
values.

@item 
bpo-40212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40212}: Re-enable @ref{114d,,os.posix_fallocate()} and
@ref{114c,,os.posix_fadvise()} on AIX.

@item 
bpo-3405@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3405}: Add support for user data of Tk virtual events and detail for
@code{Enter}, @code{Leave}, @code{FocusIn}, @code{FocusOut}, and @code{ConfigureRequest}
events to @ref{f9,,tkinter}.

@item 
bpo-32234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32234}: @ref{15f1,,mailbox.Mailbox} instances can now be used as a context
manager. The Mailbox is locked on context entry and unlocked and closed at
context exit.
@end itemize

@node Documentation<4>,Core and Builtins<4>,Library<4>,Python 3 15 0 alpha 7
@anchor{whatsnew/changelog id19}@anchor{194e}
@subsubsection Documentation



@itemize -

@item 
gh-145450@footnote{https://github.com/python/cpython/issues/145450}: Document missing public @ref{2e7,,wave.Wave_write} getter
methods.

@item 
gh-110937@footnote{https://github.com/python/cpython/issues/110937}: Document rest of full public
@ref{194f,,importlib.metadata.Distribution} API. Also add the (already
documented) @ref{1950,,PackagePath} to @code{__all__}.

@item 
gh-136246@footnote{https://github.com/python/cpython/issues/136246}: A new «Improve this page» link is available in the left-hand
sidebar of the docs, offering links to create GitHub issues, discussion
forum posts, or pull requests.
@end itemize

@node Core and Builtins<4>,C API<3>,Documentation<4>,Python 3 15 0 alpha 7
@anchor{whatsnew/changelog id20}@anchor{1951}
@subsubsection Core and Builtins



@itemize -

@item 
gh-145701@footnote{https://github.com/python/cpython/issues/145701}: Fix @ref{3ea,,SystemError} when @code{__classdict__} or
@code{__conditional_annotations__} is in a class-scope inlined comprehension.
Found by OSS Fuzz in #491105000@footnote{https://issues.oss-fuzz.com/issues/491105000}.

@item 
gh-145615@footnote{https://github.com/python/cpython/issues/145615}: Fixed a memory leak in the @ref{198,,free-threaded build} where
mimalloc pages could become permanently unreclaimable until the owning
thread exited.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make @code{mmap.mmap.set_name()} thread-safe on the @ref{487,,free threaded} build.

@item 
gh-145566@footnote{https://github.com/python/cpython/issues/145566}: In the free threading build, skip the stop-the-world pause when
reassigning @code{__class__} on a newly created object.

@item 
gh-143055@footnote{https://github.com/python/cpython/issues/143055}: Fix crash in AST unparser when unparsing dict comprehension
unpacking. Found by OSS Fuzz in #489790200@footnote{https://issues.oss-fuzz.com/issues/489790200}.

@item 
gh-145335@footnote{https://github.com/python/cpython/issues/145335}: Fix a crash in @ref{14a7,,os.pathconf()} when called with @code{-1} as
the path argument.

@item 
gh-145376@footnote{https://github.com/python/cpython/issues/145376}: Fix reference leaks in various unusual error scenarios.

@item 
gh-145234@footnote{https://github.com/python/cpython/issues/145234}: Fixed a @code{SystemError} in the parser when an encoding cookie
(for example, UTF-7) decodes to carriage returns (@code{\r}). Newlines are
now normalized after decoding in the string tokenizer.

Patch by Pablo Galindo.

@item 
gh-145275@footnote{https://github.com/python/cpython/issues/145275}: Added the @ref{178,,-X pathconfig_warnings} and
@geindex PYTHON_PATHCONFIG_WARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHON_PATHCONFIG_WARNINGS
@ref{1952,,PYTHON_PATHCONFIG_WARNINGS} options, allowing to disable warnings
from @ref{1953,,The initialization of the sys.path module search path}.

@item 
gh-145273@footnote{https://github.com/python/cpython/issues/145273}: A warning is now shown during @ref{1953,,The initialization of the sys.path module search path} if it can’t
find a valid standard library.

@item 
gh-145241@footnote{https://github.com/python/cpython/issues/145241}: Specialized the parser error for when @code{with} items are
followed by a trailing comma (for example, @code{with item,:}), raising a
clearer @ref{17e,,SyntaxError} message. Patch by Pablo Galindo and Bartosz
Sławecki.

@item 
gh-130555@footnote{https://github.com/python/cpython/issues/130555}: Fix use-after-free in @ref{1954,,dict.clear()} when the dictionary
values are embedded in an object and a destructor causes re-entrant
mutation of the dictionary.

@item 
gh-145197@footnote{https://github.com/python/cpython/issues/145197}: Fix JIT trace crash when recording function from cleared
generator frame.

@item 
gh-145187@footnote{https://github.com/python/cpython/issues/145187}: Fix compiler assertion fail when a type parameter bound
contains an invalid expression in a conditional block.

@item 
gh-145142@footnote{https://github.com/python/cpython/issues/145142}: Fix a crash in the free-threaded build when the dictionary
argument to @ref{187,,str.maketrans()} is concurrently modified.

@item 
gh-145118@footnote{https://github.com/python/cpython/issues/145118}: @ref{187,,str.maketrans()} now accepts @ref{182,,frozendict}.

@item 
gh-144015@footnote{https://github.com/python/cpython/issues/144015}: Speed up @ref{111e,,bytes.hex()}, @ref{111f,,bytearray.hex()},
@ref{1955,,binascii.hexlify()}, and @ref{6b,,hashlib} @code{.hexdigest()} operations
with SIMD on x86-64, ARM64, and ARM32 with NEON when built with gcc
(version 12 or higher) or clang (version 3 or higher) compilers.  Around
1.1-3x faster for common 16-64 byte inputs such as hashlib hex digests,
and up to 8x faster for larger data.

@item 
gh-145118@footnote{https://github.com/python/cpython/issues/145118}: @ref{186,,type()} now accepts @ref{182,,frozendict} as an argument.

@item 
gh-145064@footnote{https://github.com/python/cpython/issues/145064}: Fix JIT optimizer assertion failure during
@code{CALL_ALLOC_AND_ENTER_INIT} side exit.

@item 
gh-145055@footnote{https://github.com/python/cpython/issues/145055}: @ref{185,,exec()} and @ref{184,,eval()} now accept @ref{182,,frozendict}
for `globals'. Patch by Victor Stinner.

@item 
gh-145058@footnote{https://github.com/python/cpython/issues/145058}: Fix a crash when @code{__lazy_import__()} is passed a
non-string argument, by raising an @ref{291,,TypeError} instead.

@item 
gh-144995@footnote{https://github.com/python/cpython/issues/144995}: Optimize @ref{1d2,,memoryview} comparison: a @code{memoryview}
is equal to itself, there is no need to compare values. Patch by Victor
Stinner.

@item 
gh-141510@footnote{https://github.com/python/cpython/issues/141510}: Update specializer to support frozendict. Patch by Donghee Na.

@item 
gh-141510@footnote{https://github.com/python/cpython/issues/141510}: Optimize @code{frozendict.fromkeys()} to avoid unnecessary
thread-safety operations in frozendict cases. Patch by Donghee Na.

@item 
gh-100239@footnote{https://github.com/python/cpython/issues/100239}: Speedup @code{BINARY_OP_EXTEND} for exact floats and medium-size
integers by up to 15%. Patch by Chris Eibl.

@item 
gh-144914@footnote{https://github.com/python/cpython/issues/144914}: Use @code{mimalloc} for raw memory allocations such as via
@ref{2bf,,PyMem_RawMalloc()} for better performance on @ref{198,,free-threaded builds}. Patch by Kumar Aditya.

@item 
gh-144872@footnote{https://github.com/python/cpython/issues/144872}: Fix heap buffer overflow in the parser found by OSS-Fuzz.

@item 
gh-144766@footnote{https://github.com/python/cpython/issues/144766}: Fix a crash in fork child process when perf support is enabled.

@item 
gh-144759@footnote{https://github.com/python/cpython/issues/144759}: Fix undefined behavior in the lexer when @code{start} and
@code{multi_line_start} pointers are @code{NULL} in
@code{_PyLexer_remember_fstring_buffers()} and
@code{_PyLexer_restore_fstring_buffers()}. The @code{NULL} pointer arithmetic
(@code{NULL - valid_pointer}) is now guarded with explicit @code{NULL} checks.

@item 
gh-141510@footnote{https://github.com/python/cpython/issues/141510}: Add built-in @ref{182,,frozendict} type. Patch by Victor Stinner.

@item 
gh-144681@footnote{https://github.com/python/cpython/issues/144681}: Fix a JIT assertion failure when a conditional branch jumps to
the same target as the fallthrough path.

@item 
gh-143300@footnote{https://github.com/python/cpython/issues/143300}: Add @ref{397,,PyUnstable_SetImmortal()} C-API function to mark
objects as @ref{398,,immortal}.

@item 
gh-144702@footnote{https://github.com/python/cpython/issues/144702}: Clarify the error message raised when a class pattern is used
to match on a non-class object.

@item 
gh-144569@footnote{https://github.com/python/cpython/issues/144569}: Optimize @code{BINARY_SLICE} for list, tuple, and unicode by
avoiding temporary @code{slice} object creation.

@item 
gh-144438@footnote{https://github.com/python/cpython/issues/144438}: Align the QSBR thread state array to a 64-byte cache line
boundary to avoid false sharing in the @ref{198,,free-threaded build}.

@item 
gh-142349@footnote{https://github.com/python/cpython/issues/142349}: Implement 
@geindex Python Enhancement Proposals; PEP 810
PEP 810@footnote{https://peps.python.org/pep-0810/}. Patch by Pablo Galindo and Dino Viehland.

@item 
gh-141226@footnote{https://github.com/python/cpython/issues/141226}: Deprecate 
@geindex Python Enhancement Proposals; PEP 456
PEP 456@footnote{https://peps.python.org/pep-0456/} support for providing an external
definition of the string hashing scheme. Removal is scheduled for Python
3.19. Patch by Bénédikt Tran.

@item 
gh-138912@footnote{https://github.com/python/cpython/issues/138912}: Improve @ref{afd,,MATCH_CLASS} performance by up to 52% in
certain cases. Patch by Marc Mueller.

@item 
gh-130327@footnote{https://github.com/python/cpython/issues/130327}: Fix erroneous clearing of an object’s @ref{1bf,,__dict__}
if overwritten at runtime.

@item 
gh-80667@footnote{https://github.com/python/cpython/issues/80667}: Literals using the @code{\N@{name@}} escape syntax can now construct
CJK ideographs and Hangul syllables using case-insensitive names.
@end itemize

@node C API<3>,Build<3>,Core and Builtins<4>,Python 3 15 0 alpha 7
@anchor{whatsnew/changelog id21}@anchor{1956}
@subsubsection C API



@itemize -

@item 
gh-142417@footnote{https://github.com/python/cpython/issues/142417}: Restore private provisional @code{_Py_InitializeMain()} function
removed in Python 3.14. Patch by Victor Stinner.

@item 
gh-144748@footnote{https://github.com/python/cpython/issues/144748}: @ref{880,,PyErr_CheckSignals()} now raises the exception scheduled
by @ref{f82,,PyThreadState_SetAsyncExc()}, if any.

@item 
gh-144981@footnote{https://github.com/python/cpython/issues/144981}: Made @ref{1957,,PyUnstable_Code_SetExtra()},
@ref{1958,,PyUnstable_Code_GetExtra()}, and
@ref{1959,,PyUnstable_Eval_RequestCodeExtraIndex()} thread-safe on the
@ref{487,,free threaded} build.

@item 
gh-141510@footnote{https://github.com/python/cpython/issues/141510}: Add the following functions for the new @ref{182,,frozendict}
type:


@itemize *

@item 
@ref{34c,,PyAnyDict_Check()}

@item 
@ref{34d,,PyAnyDict_CheckExact()}

@item 
@ref{34e,,PyFrozenDict_Check()}

@item 
@ref{34f,,PyFrozenDict_CheckExact()}

@item 
@ref{350,,PyFrozenDict_New()}
@end itemize

Patch by Victor Stinner.

@item 
gh-121617@footnote{https://github.com/python/cpython/issues/121617}: @code{Python.h} now also includes @code{<string.h>} in the limited C
API version 3.11 and newer to fix the @ref{97c,,Py_CLEAR} macro which uses
@code{memcpy()}. Patch by Victor Stinner.

@item 
gh-144175@footnote{https://github.com/python/cpython/issues/144175}: Add @ref{349,,PyArg_ParseArray()} and
@ref{34a,,PyArg_ParseArrayAndKeywords()} functions to parse arguments of
functions using the @ref{34b,,METH_FASTCALL} calling convention. Patch by
Victor Stinner.
@end itemize

@node Build<3>,,C API<3>,Python 3 15 0 alpha 7
@anchor{whatsnew/changelog id22}@anchor{195a}
@subsubsection Build



@itemize -

@item 
gh-144533@footnote{https://github.com/python/cpython/issues/144533}: Use wasmtime’s @code{--argv0} to auto-discover sysconfig in WASI
builds

@item 
gh-145110@footnote{https://github.com/python/cpython/issues/145110}: Fix targets «Clean» and «CLeanAll» in case of PGO builds on
Windows. Patch by Chris Eibl.

@item 
gh-144679@footnote{https://github.com/python/cpython/issues/144679}: When building with Visual Studio 2026 (Version 18), use
PlatformToolSet v145 by default. Patch by Chris Eibl.

@item 
gh-144675@footnote{https://github.com/python/cpython/issues/144675}: Update to WASI SDK 30.

@item 
gh-136677@footnote{https://github.com/python/cpython/issues/136677}: Introduce executable specific linker flags to @code{./configure}.
@end itemize

@node Python 3 15 0 alpha 6,Python 3 15 0 alpha 5,Python 3 15 0 alpha 7,Changelog
@anchor{whatsnew/changelog python-3-15-0-alpha-6}@anchor{195b}
@subsection Python 3.15.0 alpha 6


`Release date: 2026-02-11'

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

@end menu

@node macOS<3>,Windows<4>,,Python 3 15 0 alpha 6
@anchor{whatsnew/changelog id23}@anchor{195c}
@subsubsection macOS



@itemize -

@item 
gh-144648@footnote{https://github.com/python/cpython/issues/144648}: Allowed _remote_debugging to build on more OS versions by using
proc_listpids() rather than proc_listallpids().

@item 
gh-124111@footnote{https://github.com/python/cpython/issues/124111}: Update macOS installer to use Tcl/Tk 9.0.3.

@item 
gh-144551@footnote{https://github.com/python/cpython/issues/144551}: Update macOS installer to use OpenSSL 3.5.5.
@end itemize

@node Windows<4>,Tests<4>,macOS<3>,Python 3 15 0 alpha 6
@anchor{whatsnew/changelog id24}@anchor{195d}
@subsubsection Windows



@itemize -

@item 
gh-80620@footnote{https://github.com/python/cpython/issues/80620}: Support negative timestamps in @ref{1569,,time.gmtime()},
@ref{189b,,time.localtime()}, and various @ref{33,,datetime} functions.
@end itemize

@node Tests<4>,Security<5>,Windows<4>,Python 3 15 0 alpha 6
@anchor{whatsnew/changelog id25}@anchor{195e}
@subsubsection Tests



@itemize -

@item 
gh-144415@footnote{https://github.com/python/cpython/issues/144415}: The Android testbed now distinguishes between stdout/stderr
messages which were triggered by a newline, and those triggered by a
manual call to @code{flush}. This fixes logging of progress indicators and
similar content.

@item 
gh-65784@footnote{https://github.com/python/cpython/issues/65784}: Add support for parametrized resource @code{wantobjects} in
regrtests, which allows to run Tkinter tests with the specified value of
@code{tkinter.wantobjects}, for example @code{-u wantobjects=0}.
@end itemize

@node Security<5>,Library<5>,Tests<4>,Python 3 15 0 alpha 6
@anchor{whatsnew/changelog id26}@anchor{195f}
@subsubsection Security



@itemize -

@item 
gh-144125@footnote{https://github.com/python/cpython/issues/144125}: @ref{1578,,BytesGenerator} will now refuse to
serialize (write) headers that are unsafely folded or delimited; see
@ref{6f7,,verify_generated_headers}. (Contributed by Bas
Bloemsaat and Petr Viktorin in gh-121650@footnote{https://github.com/python/cpython/issues/121650}).

@item 
gh-143935@footnote{https://github.com/python/cpython/issues/143935}: Fixed a bug in the folding of comments when flattening an email
message using a modern email policy. Comments consisting of a very long
sequence of non-foldable characters could trigger a forced line wrap that
omitted the required leading space on the continuation line, causing the
remainder of the comment to be interpreted as a new header field. This
enabled header injection with carefully crafted inputs.

@item 
gh-143925@footnote{https://github.com/python/cpython/issues/143925}: Reject control characters in @code{data:} URL media types.

@item 
gh-143923@footnote{https://github.com/python/cpython/issues/143923}: Reject control characters in POP3 commands.

@item 
gh-143921@footnote{https://github.com/python/cpython/issues/143921}: Reject control characters in IMAP commands.

@item 
gh-143919@footnote{https://github.com/python/cpython/issues/143919}: Reject control characters in @ref{fc3,,http.cookies.Morsel}
fields and values.

@item 
gh-143916@footnote{https://github.com/python/cpython/issues/143916}: Reject C0 control characters within wsgiref.headers.Headers
fields, values, and parameters.
@end itemize

@node Library<5>,IDLE<4>,Security<5>,Python 3 15 0 alpha 6
@anchor{whatsnew/changelog id27}@anchor{1960}
@subsubsection Library



@itemize -

@item 
gh-144538@footnote{https://github.com/python/cpython/issues/144538}: Bump the version of pip bundled in ensurepip to version 26.0.1

@item 
gh-144493@footnote{https://github.com/python/cpython/issues/144493}: Improve an exception error message in
@code{_overlapped.BindLocal()} that is raised when
@ref{1181,,asyncio.loop.sock_connect()} is called on a
@ref{9fe,,asyncio.ProactorEventLoop} with a socket that has an invalid
address family.

@item 
gh-144386@footnote{https://github.com/python/cpython/issues/144386}: Add support for arbitrary descriptors @code{__enter__()},
@code{__exit__()}, @code{__aenter__()}, and @code{__aexit__()} in
@ref{208,,contextlib.ExitStack} and @ref{209,,contextlib.AsyncExitStack}, for
consistency with the @ref{20a,,with} and @ref{20b,,async with} statements.

@item 
gh-123471@footnote{https://github.com/python/cpython/issues/123471}: Make concurrent iteration over
@ref{1626,,itertools.combinations_with_replacement} and
@ref{1961,,itertools.permutations} safe under free-threading.

@item 
gh-74453@footnote{https://github.com/python/cpython/issues/74453}: Deprecate @ref{333,,os.path.commonprefix()} in favor of
@ref{334,,os.path.commonpath()} for path segment prefixes.

The @ref{333,,os.path.commonprefix()} function is being deprecated due to
having a misleading name and module. The function is not safe to use for
path prefixes despite being included in a module about path manipulation,
meaning it is easy to accidentally introduce path traversal
vulnerabilities into Python programs by using this function.

@item 
gh-144380@footnote{https://github.com/python/cpython/issues/144380}: Improve performance of @ref{15b5,,io.BufferedReader} line
iteration by ~49%.

@item 
gh-144363@footnote{https://github.com/python/cpython/issues/144363}: Update bundled libexpat@footnote{https://libexpat.github.io/} to
2.7.4

@item 
gh-140824@footnote{https://github.com/python/cpython/issues/140824}: When @ref{5b,,faulthandler} dumps the list of third-party
extension modules, ignore sub-modules of stdlib packages. Patch by Victor
Stinner.

@item 
gh-144206@footnote{https://github.com/python/cpython/issues/144206}: Improve error messages for buffer overflow in
@ref{1962,,fcntl.fcntl()} and @ref{181d,,fcntl.ioctl()}.

@item 
gh-144264@footnote{https://github.com/python/cpython/issues/144264}: Speed up Base64 decoding of data containing ignored characters
(both in non-strict mode and with an explicit `ignorechars' argument). It
is now up to 2 times faster for multiline Base64 data.

@item 
gh-144249@footnote{https://github.com/python/cpython/issues/144249}: Add filename context to @ref{53c,,OSError} exceptions raised by
@ref{797,,ssl.SSLContext.load_cert_chain()}, allowing users to have more
context.

@item 
gh-132888@footnote{https://github.com/python/cpython/issues/132888}: Fix incorrect use of @ref{1963,,ctypes.GetLastError()} and add
missing error checks for Windows API calls in
@code{_pyrepl.windows_console}.

@item 
gh-142956@footnote{https://github.com/python/cpython/issues/142956}: Updated @ref{105,,tomllib} to parse TOML 1.1.0.

@item 
gh-144217@footnote{https://github.com/python/cpython/issues/144217}: @ref{93,,mimetypes}: Add support for DICOM files (for medical
imaging) with the official MIME type @code{application/dicom}. Patch by
Benedikt Johannes.

@item 
gh-144212@footnote{https://github.com/python/cpython/issues/144212}: Mime type @code{image/jxl} is now supported by @ref{93,,mimetypes}.

@item 
gh-143594@footnote{https://github.com/python/cpython/issues/143594}: Add @ref{26b,,symtable.Function.get_cells()} and
@ref{26c,,symtable.Symbol.is_cell()} methods.

@item 
gh-144169@footnote{https://github.com/python/cpython/issues/144169}: Fix three crashes when non-string keyword arguments are
supplied to objects in the @ref{9,,ast} module.

@item 
gh-144128@footnote{https://github.com/python/cpython/issues/144128}: Fix a crash in @ref{1964,,array.array.fromlist()} when an element’s
@ref{43d,,__index__()} method mutates the input list during conversion.

@item 
gh-144100@footnote{https://github.com/python/cpython/issues/144100}: Fixed a crash in ctypes when using a deprecated
@code{POINTER(str)} type in @code{argtypes}. Instead of aborting, ctypes now
raises a proper Python exception when the pointer target type is
unresolved.

@item 
gh-143658@footnote{https://github.com/python/cpython/issues/143658}: @ref{7d,,importlib.metadata}: Use @ref{1965,,str.lower()} and
@ref{6c0,,str.replace()} to further improve performance of
@code{importlib.metadata.Prepared.normalize()}. Patch by Hugo van Kemenade
and Henry Schreiner.

@item 
gh-144050@footnote{https://github.com/python/cpython/issues/144050}: Fix @ref{14f6,,stat.filemode()} in the pure-Python implementation to
avoid misclassifying invalid mode values as block devices.

@item 
gh-83069@footnote{https://github.com/python/cpython/issues/83069}: @ref{266,,subprocess.Popen.wait()}: when @code{timeout} is not @code{None},
an efficient event-driven mechanism now waits for process termination, if
available. Linux >= 5.3 uses @ref{267,,os.pidfd_open()} + @ref{268,,select.poll()}.
macOS and other BSD variants use @ref{269,,select.kqueue()} +
@code{KQ_FILTER_PROC} + @code{KQ_NOTE_EXIT}. Windows keeps using
@code{WaitForSingleObject} (unchanged). If none of these mechanisms are
available, the function falls back to the traditional busy loop
(non-blocking call and short sleeps). Patch by Giampaolo Rodola.

@item 
gh-144030@footnote{https://github.com/python/cpython/issues/144030}: The Python implementation of @ref{db3,,functools.lru_cache()}
differed from the default C implementation in that it did not check that
its argument is callable. This discrepancy is now fixed and both raise a
@ref{291,,TypeError}.

@item 
gh-144001@footnote{https://github.com/python/cpython/issues/144001}: Added the `ignorechars' parameter in
@ref{1fd,,binascii.a2b_base64()} and @ref{1ec,,base64.b64decode()}.

@item 
gh-144023@footnote{https://github.com/python/cpython/issues/144023}: Fixed validation of file descriptor 0 in posix functions when
used with follow_symlinks parameter.

@item 
gh-143999@footnote{https://github.com/python/cpython/issues/143999}: Fix an issue where @ref{15dc,,inspect.getgeneratorstate()} and
@ref{11cd,,inspect.getcoroutinestate()} could fail for generators wrapped by
@ref{1239,,types.coroutine()} in the suspended state.

@item 
gh-143952@footnote{https://github.com/python/cpython/issues/143952}: Fixed @ref{b,,asyncio} debugging tools to work with new remote
debugging API. Patch by Bartosz Sławecki.

@item 
gh-143904@footnote{https://github.com/python/cpython/issues/143904}: @ref{1966,,struct.pack_into()} now raises OverflowError instead of
IndexError for too large `offset' argument.

@item 
gh-143897@footnote{https://github.com/python/cpython/issues/143897}: Remove the @code{isxidstart()} and @code{isxidcontinue()}
methods of @ref{17d6,,unicodedata.ucd_3_2_0}. They are now only exposed as
@ref{297,,unicodedata.isxidstart()} and @ref{298,,unicodedata.isxidcontinue()}.

@item 
gh-143831@footnote{https://github.com/python/cpython/issues/143831}: @ref{1967,,annotationlib.ForwardRef} objects are now hashable when
created from annotation scopes with closures. Previously, hashing such
objects would throw an exception. Patch by Bartosz Sławecki.

@item 
gh-143874@footnote{https://github.com/python/cpython/issues/143874}: Fixed a bug in @ref{aa,,pdb} where expression results were not
sent back to remote client.

@item 
gh-143754@footnote{https://github.com/python/cpython/issues/143754}: Add new @ref{f9,,tkinter} widget methods @code{pack_content()},
@code{place_content()} and @code{grid_content()} which are alternative
spelling of old @code{*_slaves()} methods.

@item 
gh-143756@footnote{https://github.com/python/cpython/issues/143756}: Fix potential thread safety issues in @ref{d8,,ssl} module.

@item 
gh-132604@footnote{https://github.com/python/cpython/issues/132604}: Previously, @ref{76c,,Protocol} classes that were not
decorated with @ref{861,,@@~typing.runtime_checkable}, but that inherited from
another @code{Protocol} class that did have this decorator, could be used in
@ref{2ef,,isinstance()} and @ref{2f0,,issubclass()} checks. This behavior is now
deprecated and such checks will throw a @ref{291,,TypeError} in Python 3.20.
Patch by Bartosz Sławecki.

@item 
gh-143543@footnote{https://github.com/python/cpython/issues/143543}: Fix a crash in itertools.groupby that could occur when a
user-defined @ref{ec0,,__eq__()} method re-enters the iterator during
key comparison.

@item 
gh-143689@footnote{https://github.com/python/cpython/issues/143689}: Fix @ref{1968,,io.BufferedReader.read1()} state cleanup on buffer
allocation failure.

@item 
gh-143602@footnote{https://github.com/python/cpython/issues/143602}: Fix a inconsistency issue in @ref{174e,,write()} that
leads to unexpected buffer overwrite by deduplicating the buffer exports.

@item 
gh-142434@footnote{https://github.com/python/cpython/issues/142434}: Use @code{ppoll()} if available in @ref{268,,select.poll()} to have a
timeout resolution of 1 nanosecond, instead of a resolution of 1 ms. Patch
by Victor Stinner.

@item 
gh-140557@footnote{https://github.com/python/cpython/issues/140557}: @ref{6c5,,array.array} buffers now have the same alignment when
empty as when allocated. Unaligned buffers can still be created by
slicing.

@item 
gh-143423@footnote{https://github.com/python/cpython/issues/143423}: Fix free-threaded build detection in the sampling profiler when
Py_GIL_DISABLED is set to 0.

@item 
gh-101178@footnote{https://github.com/python/cpython/issues/101178}: Add Ascii85, Base85, and Z85 support to @ref{11,,binascii} and
improve the performance of the base-85 converters in @ref{f,,base64}.

@item 
gh-142966@footnote{https://github.com/python/cpython/issues/142966}: Fix @code{ctypes.POINTER.set_type()} not updating the format
string to match the type.

@item 
gh-142555@footnote{https://github.com/python/cpython/issues/142555}: @ref{8,,array}: fix a crash in @code{a[i] = v} when converting `i'
to an index via @ref{43d,,i.__index__} or
@ref{d92,,i.__float__} mutates the array.

@item 
gh-142438@footnote{https://github.com/python/cpython/issues/142438}: Fix _decimal builds configured with EXTRA_FUNCTIONALITY by
correcting the Context.apply wrapper to pass the right argument.

@item 
gh-141860@footnote{https://github.com/python/cpython/issues/141860}: Add an @code{on_error} keyword-only parameter to
@ref{1969,,multiprocessing.set_forkserver_preload()} to control how import
failures during module preloading are handled. Accepts @code{'ignore'}
(default, silent), @code{'warn'} (emit @ref{907,,ImportWarning}), or @code{'fail'}
(raise exception). Contributed by Nick Neumann and Gregory P. Smith.

@item 
gh-125346@footnote{https://github.com/python/cpython/issues/125346}: Accepting @code{+} and @code{/} characters with an alternative
alphabet in @ref{1ec,,base64.b64decode()} and @ref{1ee,,base64.urlsafe_b64decode()}
is now deprecated. In future Python versions they will be errors in the
strict mode and discarded in the non-strict mode.

@item 
gh-140715@footnote{https://github.com/python/cpython/issues/140715}: Add @code{'%F'} support to @ref{2d2,,strptime()}.

@item 
gh-67041@footnote{https://github.com/python/cpython/issues/67041}: Add the `missing_as_none' parameter to
@ref{2a4,,urlparse()}, @ref{2a3,,urlsplit()} and
@ref{2a5,,urldefrag()} functions. Add the `keep_empty' parameter
to @ref{2a7,,urlunparse()} and @ref{2a6,,urlunsplit()}
functions. This allows to distinguish between empty and not defined URI
components and preserve empty components.

@item 
gh-77188@footnote{https://github.com/python/cpython/issues/77188}: The @ref{ab,,pickle} module now properly handles name-mangled
private methods.
@end itemize

@node IDLE<4>,Core and Builtins<5>,Library<5>,Python 3 15 0 alpha 6
@anchor{whatsnew/changelog id29}@anchor{196a}
@subsubsection IDLE



@itemize -

@item 
gh-143774@footnote{https://github.com/python/cpython/issues/143774}: Better explain the operation of Format / Format Paragraph.
@end itemize

@node Core and Builtins<5>,C API<4>,IDLE<4>,Python 3 15 0 alpha 6
@anchor{whatsnew/changelog id30}@anchor{196b}
@subsubsection Core and Builtins



@itemize -

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Optimize and eliminate ref-counting in
@code{_BINARY_OP_SUBSCR_LIST_SLICE}

@item 
gh-144563@footnote{https://github.com/python/cpython/issues/144563}: Fix interaction of the Tachyon profiler and @ref{2d,,ctypes} and
other modules that load the Python shared library (if present) in an
independent map as this was causing the mechanism that loads the binary
information to be confused. Patch by Pablo Galindo

@item 
gh-144601@footnote{https://github.com/python/cpython/issues/144601}: Fix crash when importing a module whose @code{PyInit} function
raises an exception from a subinterpreter.

@item 
gh-144549@footnote{https://github.com/python/cpython/issues/144549}: Fix building the tail calling interpreter on Visual Studio 2026
with free-threading.

@item 
gh-144513@footnote{https://github.com/python/cpython/issues/144513}: Fix potential deadlock when using critical sections during
stop-the-world pauses in the free-threaded build.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Optimise @code{_GUARD_TOS_SLICE} in the JIT.

@item 
gh-144330@footnote{https://github.com/python/cpython/issues/144330}: Move @code{classmethod} and @code{staticmethod} initialization from
@code{__init__()} to @code{__new__()}. Patch by Victor Stinner.

@item 
gh-144446@footnote{https://github.com/python/cpython/issues/144446}: Fix data races in the free-threaded build when reading frame
object attributes while another thread is executing the frame.

@item 
gh-120321@footnote{https://github.com/python/cpython/issues/120321}: Add @code{gi_state}, @code{cr_state}, and @code{ag_state} attributes to
generators, coroutines, and async generators that return the current state
as a string (e.g., @code{GEN_RUNNING}). The @ref{81,,inspect} module functions
@ref{15dc,,getgeneratorstate()}, @ref{11cd,,getcoroutinestate()},
and @ref{8a3,,getasyncgenstate()} now return these attributes
directly.

@item 
gh-141563@footnote{https://github.com/python/cpython/issues/141563}: Fix thread safety of @code{ PyDateTime_IMPORT}.

@item 
gh-144280@footnote{https://github.com/python/cpython/issues/144280}: Fix a bug in JIT where the predicate symbol had no truthiness

@item 
gh-140550@footnote{https://github.com/python/cpython/issues/140550}: In @ref{196c,,PyModuleDef.m_slots}, allow slots that repeat
information present in @ref{d45,,PyModuleDef}.

@item 
gh-139103@footnote{https://github.com/python/cpython/issues/139103}: Improve scaling of @ref{1cf,,namedtuple()}
instantiation in the free-threaded build.

@item 
gh-144307@footnote{https://github.com/python/cpython/issues/144307}: Prevent a reference leak in module teardown at interpreter
finalization.

@item 
gh-144319@footnote{https://github.com/python/cpython/issues/144319}: Add huge pages support for the pymalloc allocator. Patch by
Pablo Galindo

@item 
gh-120321@footnote{https://github.com/python/cpython/issues/120321}: Made @code{gi_yieldfrom} thread-safe in the free-threading build
by using a lightweight lock on the frame state.

@item 
gh-144194@footnote{https://github.com/python/cpython/issues/144194}: Fix error handling in perf jitdump initialization on memory
allocation failure.

@item 
gh-143962@footnote{https://github.com/python/cpython/issues/143962}: Name suggestion for not normalized name suggests now the
normalized name or the closest name to the normalized name. If the
suggested name is not ASCII, include also its ASCII representation.

@item 
gh-144157@footnote{https://github.com/python/cpython/issues/144157}: @ref{196d,,bytes.translate()} now allows the compiler to unroll its
loop more usefully for a 2x speedup in the common no-deletions specified
case.

@item 
gh-144068@footnote{https://github.com/python/cpython/issues/144068}: Fix JIT tracer memory leak, ensure the JIT tracer state is
freed when daemon threads are cleaned up during interpreter shutdown.

@item 
gh-144012@footnote{https://github.com/python/cpython/issues/144012}: Check if the result is @code{NULL} in @code{BINARY_OP_EXTENT} opcode.

@item 
gh-144007@footnote{https://github.com/python/cpython/issues/144007}: Eliminate redundant refcounting in the JIT for @code{BINARY_OP}.

@item 
gh-144005@footnote{https://github.com/python/cpython/issues/144005}: Eliminate redundant refcounting from @code{BINARY_OP_EXTEND}.

@item 
gh-143939@footnote{https://github.com/python/cpython/issues/143939}: Fix erroneous «cannot reuse already awaited coroutine» error
that could occur when a generator was run during the process of clearing a
coroutine’s frame.

@item 
gh-141805@footnote{https://github.com/python/cpython/issues/141805}: Fix crash in @ref{42b,,set} when objects with the same hash are
concurrently added to the set after removing an element with the same hash
while the set still contains elements with the same hash.

@item 
gh-143670@footnote{https://github.com/python/cpython/issues/143670}: Fixes a crash in @code{ga_repr_items_list} function.

@item 
gh-143650@footnote{https://github.com/python/cpython/issues/143650}: Fix race condition in @ref{7a,,importlib} where a thread could
receive a stale module reference when another thread’s import fails.

@item 
gh-143569@footnote{https://github.com/python/cpython/issues/143569}: Generator expressions in 3.15 now conform to the documented
behavior when the iterable does not support iteration. This matches the
behavior in 3.14 and earlier

@item 
gh-143192@footnote{https://github.com/python/cpython/issues/143192}: Improve performance of bitwise operations on multi-digit ints.

@item 
gh-132657@footnote{https://github.com/python/cpython/issues/132657}: If we are specializing to @code{LOAD_GLOBAL_MODULE} or
@code{LOAD_ATTR_MODULE}, try to enable deferred reference counting for the
value, if the object is owned by a different thread.  This applies to the
free-threaded build only and should improve scaling of multi-threaded
programs. Note that when deferred reference counting is enabled, the
object will be deallocated by the GC, rather than by @ref{975,,Py_DECREF()}.

@item 
gh-143055@footnote{https://github.com/python/cpython/issues/143055}: Implement 
@geindex Python Enhancement Proposals; PEP 798
PEP 798@footnote{https://peps.python.org/pep-0798/} (Unpacking in Comprehensions).  Patch by
Adam Hartz.

@item 
gh-142037@footnote{https://github.com/python/cpython/issues/142037}: Improve error messages for printf-style formatting. For errors
in the format string, always include the position of the start of the
format unit. For errors related to the formatted arguments, always include
the number or the name of the argument. Raise more specific errors and
include more information (type and number of arguments, most probable
causes of error).

@item 
gh-140557@footnote{https://github.com/python/cpython/issues/140557}: @ref{1c6,,bytearray} buffers now have the same alignment when
empty as when allocated. Unaligned buffers can still be created by
slicing.

@item 
gh-140232@footnote{https://github.com/python/cpython/issues/140232}: Frozenset objects with immutable elements are no longer tracked
by the garbage collector.

@item 
gh-115231@footnote{https://github.com/python/cpython/issues/115231}: Setup @code{__module__} attribute for built-in static methods.
Patch by Sergey B Kirpichev.
@end itemize

@node C API<4>,Build<4>,Core and Builtins<5>,Python 3 15 0 alpha 6
@anchor{whatsnew/changelog id31}@anchor{196e}
@subsubsection C API



@itemize -

@item 
gh-143869@footnote{https://github.com/python/cpython/issues/143869}: Added @ref{5d4,,PyLong_GetNativeLayout()},
@ref{196f,,PyLongLayout}, @ref{1970,,PyLongExport},
@ref{5d5,,PyLong_Export()}, @ref{5d6,,PyLong_FreeExport()},
@ref{1971,,PyLongWriter}, @ref{5d7,,PyLongWriter_Create()},
@ref{5d8,,PyLongWriter_Finish()} and @ref{5d9,,PyLongWriter_Discard()} to the
limited API.

@item 
gh-141070@footnote{https://github.com/python/cpython/issues/141070}: Renamed @code{PyUnstable_Object_Dump()} to
@ref{374,,PyObject_Dump()}.
@end itemize

@node Build<4>,,C API<4>,Python 3 15 0 alpha 6
@anchor{whatsnew/changelog id32}@anchor{1972}
@subsubsection Build



@itemize -

@item 
gh-140421@footnote{https://github.com/python/cpython/issues/140421}: Disable the perf trampoline on older macOS versions where it
cannot be built.

@item 
gh-144309@footnote{https://github.com/python/cpython/issues/144309}: Build Python with POSIX 2024, instead of POSIX 2008. Patch by
Victor Stinner.

@item 
gh-144278@footnote{https://github.com/python/cpython/issues/144278}: Enables defining the @code{_PY_IMPL_NAME} and
@code{_PY_IMPL_CACHE_TAG} preprocessor definitions to override
@ref{926,,sys.implementation} at build time. Definitions need to include
quotes when setting to a string literal. Setting the cache tag to @code{NULL}
has the effect of completely disabling automatic creation and use of
@code{.pyc} files.

@item 
gh-143960@footnote{https://github.com/python/cpython/issues/143960}: Add support for OpenSSL 3.6, drop EOL 3.2. Patch by Hugo van
Kemenade.

@item 
gh-143941@footnote{https://github.com/python/cpython/issues/143941}: Move WASI-related files to @code{Platforms/WASI}. Along the
way, leave a deprecated @code{Tools/wasm/wasi/__main__.py} behind for
backwards-compatibility.

@item 
gh-143842@footnote{https://github.com/python/cpython/issues/143842}: Prevent static builds from clashing with curses by making the
optimizer COLORS table static.
@end itemize

@node Python 3 15 0 alpha 5,Python 3 15 0 alpha 4,Python 3 15 0 alpha 6,Changelog
@anchor{whatsnew/changelog python-3-15-0-alpha-5}@anchor{1973}
@subsection Python 3.15.0 alpha 5


`Release date: 2026-01-14'

@menu
* Windows: Windows<5>. 
* Tools/Demos: Tools/Demos<2>. 
* Tests: Tests<5>. 
* Library: Library<6>. 
* Documentation: Documentation<5>. 
* Core and Builtins: Core and Builtins<6>. 
* C API: C API<5>. 

@end menu

@node Windows<5>,Tools/Demos<2>,,Python 3 15 0 alpha 5
@anchor{whatsnew/changelog id33}@anchor{1974}
@subsubsection Windows



@itemize -

@item 
gh-143082@footnote{https://github.com/python/cpython/issues/143082}: Fix @ref{aa,,pdb} arrow key history not working when @code{stdin} is
@code{sys.stdin}.

@item 
gh-128067@footnote{https://github.com/python/cpython/issues/128067}: Fix a bug in PyREPL on Windows where output without a trailing
newline was overwritten by the next prompt.
@end itemize

@node Tools/Demos<2>,Tests<5>,Windows<5>,Python 3 15 0 alpha 5
@anchor{whatsnew/changelog id34}@anchor{1975}
@subsubsection Tools/Demos



@itemize -

@item 
gh-142095@footnote{https://github.com/python/cpython/issues/142095}: Make gdb “py-bt” command use frame from thread local state when
available. Patch by Sam Gross and Victor Stinner.
@end itemize

@node Tests<5>,Library<6>,Tools/Demos<2>,Python 3 15 0 alpha 5
@anchor{whatsnew/changelog id35}@anchor{1976}
@subsubsection Tests



@itemize -

@item 
gh-143460@footnote{https://github.com/python/cpython/issues/143460}: Skip tests relying on infinite recusion if stack size is
unlimited.

@item 
gh-143553@footnote{https://github.com/python/cpython/issues/143553}: Add support for parametrized resources, such as @code{-u
xpickle=2.7}.

@item 
bpo-31391@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31391}: Forward-port test_xpickle from Python 2 to Python 3 and add the
resource back to test’s command line.
@end itemize

@node Library<6>,Documentation<5>,Tests<5>,Python 3 15 0 alpha 5
@anchor{whatsnew/changelog id36}@anchor{1977}
@subsubsection Library



@itemize -

@item 
gh-143706@footnote{https://github.com/python/cpython/issues/143706}: Fix @ref{98,,multiprocessing} forkserver so that @ref{1609,,sys.argv}
is correctly set before @code{__main__} is preloaded. Previously,
@code{sys.argv} was empty during main module import in forkserver child
processes. This fixes a regression introduced in 3.13.8 and 3.14.1. Root
caused by Aaron Wieczorek, test provided by Thomas Watson, thanks!

@item 
gh-143638@footnote{https://github.com/python/cpython/issues/143638}: Forbid reentrant calls of the @ref{de2,,pickle.Pickler} and
@ref{1978,,pickle.Unpickler} methods for the C implementation. Previously,
this could cause crash or data corruption, now concurrent calls of methods
of the same object raise @ref{30d,,RuntimeError}.

@item 
gh-143658@footnote{https://github.com/python/cpython/issues/143658}: @ref{7d,,importlib.metadata}: Use @ref{1979,,str.translate()} to improve
performance of @code{importlib.metadata.Prepared.normalize()}. Patch by
Hugo van Kemenade and Henry Schreiner.

@item 
gh-78724@footnote{https://github.com/python/cpython/issues/78724}: Raise @ref{30d,,RuntimeError}’s when user attempts to call methods
on half-initialized @ref{2fb,,Struct} objects, For example, created
by @code{Struct.__new__(Struct)}.  Patch by Sergey B Kirpichev.

@item 
gh-143196@footnote{https://github.com/python/cpython/issues/143196}: Fix crash when the internal encoder object returned by
undocumented function @code{json.encoder.c_make_encoder()} was called with
non-zero second (`_current_indent_level') argument.

@item 
gh-143191@footnote{https://github.com/python/cpython/issues/143191}: @ref{197a,,_thread.stack_size()} now raises @ref{277,,ValueError} if the
stack size is too small. Patch by Victor Stinner.

@item 
gh-143547@footnote{https://github.com/python/cpython/issues/143547}: Fix @ref{70c,,sys.unraisablehook()} when the hook raises an
exception and changes @code{sys.unraisablehook()}: hold a strong reference
to the old hook. Patch by Victor Stinner.

@item 
gh-139686@footnote{https://github.com/python/cpython/issues/139686}: Revert 0a97941245f1dda6d838f9aaf0512104e5253929 and
57db12514ac686f0a752ec8fe1c08b6daa0c6219 which made importlib.reload a
no-op for lazy modules; caused Buildbot failures.

@item 
gh-143517@footnote{https://github.com/python/cpython/issues/143517}: @ref{66c,,annotationlib.get_annotations()} no longer raises a
@ref{17e,,SyntaxError} when evaluating a stringified starred annotation that
starts with one or more whitespace characters followed by a @code{*}. Patch
by Bartosz Sławecki.

@item 
gh-143474@footnote{https://github.com/python/cpython/issues/143474}: Add @ref{197b,,os.RWF_ATOMIC} constant for Linux 6.11+.

@item 
gh-143445@footnote{https://github.com/python/cpython/issues/143445}: Speed up @ref{f2b,,copy.deepcopy()} by 1.04x.

@item 
gh-143378@footnote{https://github.com/python/cpython/issues/143378}: Fix use-after-free crashes when a @ref{1255,,BytesIO} object
is concurrently mutated during @ref{174e,,write()} or
@ref{197c,,writelines()}.

@item 
gh-143368@footnote{https://github.com/python/cpython/issues/143368}: Fix endless retry loop in @ref{b6,,profiling.sampling} blocking
mode when threads cannot be seized due to @code{EPERM}. Such threads are now
skipped instead of causing repeated error messages. Patch by Pablo
Galindo.

@item 
gh-143346@footnote{https://github.com/python/cpython/issues/143346}: Fix incorrect wrapping of the Base64 data in
@code{plistlib._PlistWriter} when the indent contains a mix of tabs and
spaces.

@item 
gh-140025@footnote{https://github.com/python/cpython/issues/140025}: @ref{be,,queue}: Fix @code{SimpleQueue.__sizeof__()} computation.

@item 
gh-143310@footnote{https://github.com/python/cpython/issues/143310}: @ref{f9,,tkinter}: fix a crash when a Python @ref{4d9,,list} is
mutated during the conversion to a Tcl object (e.g., when setting a Tcl
variable). Patch by Bénédikt Tran.

@item 
gh-143309@footnote{https://github.com/python/cpython/issues/143309}: Fix a crash in @ref{14a5,,os.execve()} on non-Windows platforms when
given a custom environment mapping which is then mutated during parsing.
Patch by Bénédikt Tran.

@item 
gh-143308@footnote{https://github.com/python/cpython/issues/143308}: @ref{ab,,pickle}: fix use-after-free crashes when a
@ref{1908,,PickleBuffer} is concurrently mutated by a custom buffer
callback during pickling. Patch by Bénédikt Tran and Aaron Wieczorek.

@item 
gh-142939@footnote{https://github.com/python/cpython/issues/142939}: Performance optimisations for @ref{197d,,difflib.get_close_matches()}

@item 
gh-124951@footnote{https://github.com/python/cpython/issues/124951}: The base64 implementation behind the @ref{11,,binascii},
@ref{f,,base64}, and related codec has been optimized for modern pipelined
CPU architectures and now performs 2-3x faster across all platforms.

@item 
gh-143237@footnote{https://github.com/python/cpython/issues/143237}: Fix support of named pipes in the rotating @ref{8a,,logging}
handlers.

@item 
gh-143249@footnote{https://github.com/python/cpython/issues/143249}: Fix possible buffer leaks in Windows overlapped I/O on error
handling.

@item 
gh-143241@footnote{https://github.com/python/cpython/issues/143241}: @ref{13d,,zoneinfo}: fix infinite loop in @ref{197e,,ZoneInfo.from_file} when parsing a malformed TZif file. Patch
by Fatih Celik.

@item 
gh-142830@footnote{https://github.com/python/cpython/issues/142830}: @ref{d7,,sqlite3}: fix use-after-free crashes when the
connection’s callbacks are mutated during a callback execution. Patch by
Bénédikt Tran.

@item 
gh-143200@footnote{https://github.com/python/cpython/issues/143200}: @ref{12e,,xml.etree.ElementTree}: fix use-after-free crashes in
@ref{787,,__getitem__()} and @ref{1670,,__setitem__()} methods of
@ref{343,,Element} when the element is concurrently
mutated. Patch by Bénédikt Tran.

@item 
gh-143214@footnote{https://github.com/python/cpython/issues/143214}: Add the `wrapcol' parameter in @ref{1fc,,binascii.b2a_base64()} and
@ref{1eb,,base64.b64encode()}.

@item 
gh-142195@footnote{https://github.com/python/cpython/issues/142195}: Updated timeout evaluation logic in @ref{df,,subprocess} to be
compatible with deterministic environments like Shadow where time moves
exactly as requested.

@item 
gh-140739@footnote{https://github.com/python/cpython/issues/140739}: Fix several crashes due to reading invalid memory in the new
Tachyon sampling profiler. Patch by Pablo Galindo.

@item 
gh-142164@footnote{https://github.com/python/cpython/issues/142164}: Fix the ctypes bitfield overflow error message to report the
correct offset and size calculation.

@item 
gh-143145@footnote{https://github.com/python/cpython/issues/143145}: Fixed a possible reference leak in ctypes when constructing
results with multiple output parameters on error.

@item 
gh-143103@footnote{https://github.com/python/cpython/issues/143103}: Add padding support to @ref{1e6,,base64.z85encode()} via the @code{pad}
parameter.

@item 
gh-130796@footnote{https://github.com/python/cpython/issues/130796}: Undeprecate the @ref{233,,locale.getdefaultlocale()} function. Patch
by Victor Stinner.

@item 
gh-74902@footnote{https://github.com/python/cpython/issues/74902}: Add the @ref{299,,iter_graphemes()} function in the
@ref{10e,,unicodedata} module to iterate over grapheme clusters according to
rules defined in Unicode Standard Annex #29@comma{} "Unicode Text Segmentation"@footnote{https://www.unicode.org/reports/tr29/}. Add
@ref{29a,,grapheme_cluster_break()},
@ref{29b,,indic_conjunct_break()} and
@ref{29c,,extended_pictographic()} functions to get the properties
of the character which are related to the above algorithm.

@item 
gh-143004@footnote{https://github.com/python/cpython/issues/143004}: Fix a potential use-after-free in
@ref{197f,,collections.Counter.update()} when user code mutates the Counter
during an update.

@item 
gh-140648@footnote{https://github.com/python/cpython/issues/140648}: The @ref{b,,asyncio} REPL now respects the @ref{d28,,-I} flag
(isolated mode). Previously, it would load and execute
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP} even if the flag was set. Contributed by Bartosz
Sławecki.

@item 
gh-142991@footnote{https://github.com/python/cpython/issues/142991}: Fixed socket operations such as recvfrom() and sendto() for
FreeBSD divert(4) socket.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make the attributes in @ref{8d,,lzma} thread-safe on the
@ref{487,,free threaded} build.

@item 
gh-142950@footnote{https://github.com/python/cpython/issues/142950}: Fix regression in @ref{7,,argparse} where format specifiers in
help strings raised @ref{277,,ValueError}.

@item 
gh-142881@footnote{https://github.com/python/cpython/issues/142881}: Fix concurrent and reentrant call of @ref{1980,,atexit.unregister()}.

@item 
gh-142615@footnote{https://github.com/python/cpython/issues/142615}: Fix possible crashes when initializing @ref{460,,asyncio.Task} or
@ref{f8b,,asyncio.Future} multiple times. These classes can now be
initialized only once and any subsequent initialization attempt will raise
a RuntimeError. Patch by Kumar Aditya.

@item 
gh-142517@footnote{https://github.com/python/cpython/issues/142517}: The non-@code{compat32} @ref{3e,,email} policies now correctly handle
refolding encoded words that contain bytes that can not be decoded in
their specified character set.  Previously this resulted in an encoding
exception during folding.

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: The Tachyon profiler’s live TUI now integrates with the
experimental @code{_colorize} theming system. Users can customize colors
via @code{_colorize.set_theme()} (experimental API, subject to change). A
@code{LiveProfilerLight} theme is provided for light terminal
backgrounds. Patch by Pablo Galindo.

@item 
gh-142306@footnote{https://github.com/python/cpython/issues/142306}: Improve errors for @ref{1981,,Element.remove}.

@item 
gh-63016@footnote{https://github.com/python/cpython/issues/63016}: Add a @code{flags} parameter to @ref{e5e,,mmap.mmap.flush()} to control
synchronization behavior.

@item 
gh-139262@footnote{https://github.com/python/cpython/issues/139262}: Some keystrokes can be swallowed in the new @code{PyREPL} on
Windows, especially when used together with the ALT key. Fix by Chris
Eibl.

@item 
gh-138897@footnote{https://github.com/python/cpython/issues/138897}: Improved @ref{1982,,license}/@ref{1983,,copyright}/@ref{1984,,credits}
display in the @ref{69d,,REPL}: now uses a pager.

@item 
gh-135852@footnote{https://github.com/python/cpython/issues/135852}: Add @code{_winapi.RegisterEventSource()},
@code{_winapi.DeregisterEventSource()} and @code{_winapi.ReportEvent()}.
Using these functions in @ref{1985,,NTEventLogHandler} to
replace @code{pywin32}.

@item 
gh-109263@footnote{https://github.com/python/cpython/issues/109263}: Starting a process from spawn context in @ref{98,,multiprocessing}
no longer sets the start method globally.

@item 
gh-132715@footnote{https://github.com/python/cpython/issues/132715}: Skip writing objects during marshalling once a failure has
occurred.
@end itemize

@node Documentation<5>,Core and Builtins<6>,Library<6>,Python 3 15 0 alpha 5
@anchor{whatsnew/changelog id37}@anchor{1986}
@subsubsection Documentation



@itemize -

@item 
gh-140806@footnote{https://github.com/python/cpython/issues/140806}: Add documentation for @ref{1987,,enum.bin()}.
@end itemize

@node Core and Builtins<6>,C API<5>,Documentation<5>,Python 3 15 0 alpha 5
@anchor{whatsnew/changelog id38}@anchor{1988}
@subsubsection Core and Builtins



@itemize -

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Eliminate redundant refcounting from @code{_CONTAINS_OP},
@code{_CONTAINS_OP_SET} and @code{_CONTAINS_OP_DICT}.

@item 
gh-143604@footnote{https://github.com/python/cpython/issues/143604}: Fix a reference counting issue in the JIT tracer where the
current executor could be prematurely freed during tracing.

@item 
gh-143469@footnote{https://github.com/python/cpython/issues/143469}: Enable @code{LOAD_ATTR_MODULE} specialization even if
@code{__getattr__()} is defined in module.

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Eliminate redundant refcounting from @code{TO_BOOL_STR}.

@item 
gh-143377@footnote{https://github.com/python/cpython/issues/143377}: Fix a crash in @code{_interpreters.capture_exception()} when
the exception is incorrectly formatted. Patch by Bénédikt Tran.

@item 
gh-139757@footnote{https://github.com/python/cpython/issues/139757}: Add @code{BINARY_OP_SUBSCR_USTR_INT} to specialize reading an
ASCII character from any string. Patch by Chris Eibl.

@item 
gh-141504@footnote{https://github.com/python/cpython/issues/141504}: Factor out tracing and optimization heuristics into a single
object. Patch by Donghee Na.

@item 
gh-142982@footnote{https://github.com/python/cpython/issues/142982}: Specialize @ref{1108,,CALL_FUNCTION_EX} for Python and non-Python
callables.

@item 
gh-136924@footnote{https://github.com/python/cpython/issues/136924}: The interactive help mode in the @ref{69d,,REPL} no longer
incorrectly syntax highlights text input as Python code. Contributed by
Olga Matoula.

@item 
gh-139757@footnote{https://github.com/python/cpython/issues/139757}: Fix unintended bytecode specialization for non-ascii string.
Patch by Donghee Na, Ken Jin and Chris Eibl.

@item 
gh-143361@footnote{https://github.com/python/cpython/issues/143361}: Add @code{PY_VECTORCALL_ARGUMENTS_OFFSET} to
@code{_Py_CallBuiltinClass_StackRefSteal} to avoid redundant allocations

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: The JIT optimizer now understands more generator instructions.

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Eliminate redundant refcounting from @code{_LOAD_ATTR_SLOT}.

@item 
gh-143189@footnote{https://github.com/python/cpython/issues/143189}: Fix crash when inserting a non-@ref{1df,,str} key into a split
table dictionary when the key matches an existing key in the split table
but has no corresponding value in the dict.

@item 
gh-143228@footnote{https://github.com/python/cpython/issues/143228}: Fix use-after-free in perf trampoline when toggling profiling
while threads are running or during interpreter finalization with daemon
threads active. The fix uses reference counting to ensure trampolines are
not freed while any code object could still reference them. Pach by Pablo
Galindo

@item 
gh-142664@footnote{https://github.com/python/cpython/issues/142664}: Fix a use-after-free crash in @ref{ec1,,memoryview.__hash__} when the @code{__hash__} method of the referenced object
mutates that object or the view. Patch by Bénédikt Tran.

@item 
gh-142557@footnote{https://github.com/python/cpython/issues/142557}: Fix a use-after-free crash in @ref{113a,,bytearray.__mod__} when the @code{bytearray} is mutated while
formatting the @code{%}-style arguments. Patch by Bénédikt Tran.

@item 
gh-143195@footnote{https://github.com/python/cpython/issues/143195}: Fix use-after-free crashes in @ref{111f,,bytearray.hex()} and
@ref{1120,,memoryview.hex()} when the separator’s @ref{1989,,__len__()}
mutates the original object. Patch by Bénédikt Tran.

@item 
gh-143183@footnote{https://github.com/python/cpython/issues/143183}: Fix a bug in the JIT when dealing with unsupported control-flow
or operations.

@item 
gh-142975@footnote{https://github.com/python/cpython/issues/142975}: Fix crash after unfreezing all objects tracked by the garbage
collector on the @ref{487,,free threaded} build.

@item 
gh-143135@footnote{https://github.com/python/cpython/issues/143135}: Set @ref{198a,,sys.flags.inspect} to @code{1} when
@geindex PYTHONINSPECT
@geindex μεταβλητή περιβάλλοντος; PYTHONINSPECT
@ref{187c,,PYTHONINSPECT} is @code{0}. Previously, it was set to @code{0} in this
case.

@item 
gh-143123@footnote{https://github.com/python/cpython/issues/143123}: Protect the JIT against recursive tracing.

@item 
gh-143092@footnote{https://github.com/python/cpython/issues/143092}: Fix a crash in the JIT when dealing with @code{list.append(x)}
style code.

@item 
gh-143003@footnote{https://github.com/python/cpython/issues/143003}: Fix an overflow of the shared empty buffer in
@ref{198b,,bytearray.extend()} when @code{__length_hint__()} returns 0 for
non-empty iterator.

@item 
gh-143006@footnote{https://github.com/python/cpython/issues/143006}: Fix a possible assertion error when comparing negative
non-integer @code{float} and @code{int} with the same number of bits in the
integer part.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Fix thread safety of @ref{198c,,contextvars.Context.run()}.

@item 
gh-142829@footnote{https://github.com/python/cpython/issues/142829}: Fix a use-after-free crash in @ref{421,,contextvars.Context}
comparison when a custom @code{__eq__} method modifies the context via
@ref{198d,,set()}.

@item 
gh-142863@footnote{https://github.com/python/cpython/issues/142863}: Generate optimized bytecode when calling @ref{4d9,,list} or
@ref{42b,,set} with generator expression.

@item 
gh-41779@footnote{https://github.com/python/cpython/issues/41779}: Allowed defining any @ref{1cd,,__slots__} for a class
derived from @ref{1ce,,tuple} (including classes created by
@ref{1cf,,collections.namedtuple()}).

@item 
gh-69605@footnote{https://github.com/python/cpython/issues/69605}: Fix edge-cases around already imported modules in the
@ref{69d,,REPL} auto-completion of imports.

@item 
gh-138568@footnote{https://github.com/python/cpython/issues/138568}: Adjusted the built-in @ref{ca9,,help()} function so that empty
inputs are ignored in interactive mode.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Remove bounds check when indexing into tuples with a constant
index.

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Eliminate redundant refcounting from @code{_CALL_TYPE_1}. Patch by
Tomas Roun

@item 
gh-132108@footnote{https://github.com/python/cpython/issues/132108}: Speed up @ref{198e,,int.from_bytes()} when passed object supports
@ref{311,,buffer protocol}, like @ref{1c6,,bytearray} by ~1.2x.

@item 
gh-128334@footnote{https://github.com/python/cpython/issues/128334}: Make the @ref{1d0,,slice} class subscriptable at runtime to be
consistent with typing implementation.
@end itemize

@node C API<5>,,Core and Builtins<6>,Python 3 15 0 alpha 5
@anchor{whatsnew/changelog id39}@anchor{198f}
@subsubsection C API



@itemize -

@item 
gh-141671@footnote{https://github.com/python/cpython/issues/141671}: @ref{1875,,PyMODINIT_FUNC} (and the new
@ref{1990,,PyMODEXPORT_FUNC}) now adds a linkage declaration
(@code{__declspec(dllexport)}) on Windows.
@end itemize

@node Python 3 15 0 alpha 4,Python 3 15 0 alpha 3,Python 3 15 0 alpha 5,Changelog
@anchor{whatsnew/changelog python-3-15-0-alpha-4}@anchor{1991}
@subsection Python 3.15.0 alpha 4


`Release date: 2026-01-13'

@menu
* Tests: Tests<6>. 
* Library: Library<7>. 
* Core and Builtins: Core and Builtins<7>. 

@end menu

@node Tests<6>,Library<7>,,Python 3 15 0 alpha 4
@anchor{whatsnew/changelog id40}@anchor{1992}
@subsubsection Tests



@itemize -

@item 
gh-142836@footnote{https://github.com/python/cpython/issues/142836}: Accommodated Solaris in
@code{test_pdb.test_script_target_anonymous_pipe}.
@end itemize

@node Library<7>,Core and Builtins<7>,Tests<6>,Python 3 15 0 alpha 4
@anchor{whatsnew/changelog id41}@anchor{1993}
@subsubsection Library



@itemize -

@item 
gh-122431@footnote{https://github.com/python/cpython/issues/122431}: Corrected the error message in
@ref{1202,,readline.append_history_file()} to state that @code{nelements} must be
non-negative instead of positive.

@item 
gh-143046@footnote{https://github.com/python/cpython/issues/143046}: The @ref{b,,asyncio} REPL no longer prints copyright and version
messages in the quiet mode (@ref{1994,,-q}). Patch by Bartosz Sławecki.

@item 
gh-80744@footnote{https://github.com/python/cpython/issues/80744}: Fix issue where @code{pdb} would read a @code{.pdbrc} twice if
launched from the home directory

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: Add blocking mode to Tachyon for accurate stack traces in
applications with many generators or fast-changing call stacks. Patch by
Pablo Galindo.

@item 
gh-143010@footnote{https://github.com/python/cpython/issues/143010}: Fixed a bug in @ref{8e,,mailbox} where the precise timing of an
external event could result in the library opening an existing file
instead of a file it expected to create.

@item 
gh-112127@footnote{https://github.com/python/cpython/issues/112127}: Fix possible use-after-free in @ref{1980,,atexit.unregister()} when
the callback is unregistered during comparison.

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: Fix incomplete stack traces in the Tachyon profiler’s frame
cache when profiling code with deeply nested generators. The frame cache
now validates that stack traces reach the base frame before caching,
preventing broken flamegraphs. Patch by Pablo Galindo.

@item 
gh-142834@footnote{https://github.com/python/cpython/issues/142834}: Change the @ref{aa,,pdb} @code{commands} command to use the last
available breakpoint instead of failing when the most recently created
breakpoint was deleted.

@item 
gh-142783@footnote{https://github.com/python/cpython/issues/142783}: Fix zoneinfo use-after-free with descriptor _weak_cache. a
descriptor as _weak_cache could cause crashes during object creation. The
fix ensures proper reference counting for descriptor-provided objects.

@item 
gh-76007@footnote{https://github.com/python/cpython/issues/76007}: Deprecate @code{VERSION} from @ref{12e,,xml.etree.ElementTree} and
@code{version} from @code{xml.sax.expatreader} and @ref{133,,xml.sax.handler}.
Patch by Hugo van Kemenade.

@item 
gh-142784@footnote{https://github.com/python/cpython/issues/142784}: The @ref{b,,asyncio} REPL now properly closes the loop upon the
end of interactive session. Previously, it could cause surprising
warnings. Contributed by Bartosz Sławecki.

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: Add binary output format to @ref{b6,,profiling.sampling} for
compact storage of profiling data. The new @code{--binary} option captures
samples to a file that can be converted to other formats using the
@code{replay} command. Patch by Pablo Galindo

@item 
gh-142495@footnote{https://github.com/python/cpython/issues/142495}: @ref{1565,,collections.defaultdict} now prioritizes
@ref{1670,,__setitem__()} when inserting default values from
@code{default_factory}. This prevents race conditions where a default value
would overwrite a value set before @code{default_factory} returns.

@item 
gh-142654@footnote{https://github.com/python/cpython/issues/142654}: Show the clearer error message when using
@code{profiling.sampling} on an unknown PID.

@item 
gh-142560@footnote{https://github.com/python/cpython/issues/142560}: Fix use-after-free in @ref{1c6,,bytearray} search-like methods
(@ref{1746,,find()}, @ref{1995,,count()},
@ref{1996,,index()}, @ref{1997,,rindex()}, and
@ref{1747,,rfind()}) by marking the storage as exported which causes
reallocation attempts to raise @ref{1998,,BufferError}. For
@ref{cac,,contains()}, @ref{1999,,split()}, and
@ref{199a,,rsplit()} the @ref{311,,buffer protocol} is
used for this.

@item 
gh-142419@footnote{https://github.com/python/cpython/issues/142419}: @ref{23d,,mmap.mmap.set_name()} method added to annotate an
anonymous memory map if Linux kernel supports @code{PR_SET_VMA_ANON_NAME}
(Linux 5.17 or newer). Patch by Donghee Na.

@item 
gh-139971@footnote{https://github.com/python/cpython/issues/139971}: @ref{bd,,pydoc}: Ensure that the link to the online documentation
of a @ref{1bb,,stdlib} module is correct.

@item 
gh-124098@footnote{https://github.com/python/cpython/issues/124098}: Fix issue where methods in handlers that lacked the protocol
name but matched a valid base handler method (e.g., @code{_open()} or
@code{error()}) were incorrectly added to
@ref{199b,,urllib.request.OpenerDirector}’s handlers. Contributed by Andrea
Mattei.

@item 
gh-136282@footnote{https://github.com/python/cpython/issues/136282}: Add support for @ref{199c,,UNNAMED_SECTION} when
creating a section via the mapping protocol access
@end itemize

@node Core and Builtins<7>,,Library<7>,Python 3 15 0 alpha 4
@anchor{whatsnew/changelog id42}@anchor{199d}
@subsubsection Core and Builtins



@itemize -

@item 
gh-143057@footnote{https://github.com/python/cpython/issues/143057}: Avoid locking in @ref{f74,,PyTraceMalloc_Track()} and
@ref{f75,,PyTraceMalloc_Untrack()} when @ref{108,,tracemalloc} is not enabled.

@item 
gh-139109@footnote{https://github.com/python/cpython/issues/139109}: Add missing terminator in certain cases when tracing in the new
JIT compiler.

@item 
gh-142961@footnote{https://github.com/python/cpython/issues/142961}: Fix a segfault in the JIT when constant folding @code{len(tuple)}.

@item 
gh-142776@footnote{https://github.com/python/cpython/issues/142776}: Fix a file descriptor leak in import.c

@item 
gh-139757@footnote{https://github.com/python/cpython/issues/139757}: Fix building JIT stencils on free-threaded builds.

@item 
gh-129068@footnote{https://github.com/python/cpython/issues/129068}: Make concurrent iteration over the same range iterator
thread-safe in the free threading build.

@item 
gh-142543@footnote{https://github.com/python/cpython/issues/142543}: Fix a stack overflow on Clang JIT build configurations with
full LTO.

@item 
gh-142448@footnote{https://github.com/python/cpython/issues/142448}: Fix a bug when using monitoring with the JIT.

@item 
gh-142766@footnote{https://github.com/python/cpython/issues/142766}: Clear the frame of a generator when @ref{199e,,generator.close()} is
called.

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Eliminate redundant refcounting from
@code{_LOAD_ATTR_INSTANCE_VALUE}.

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Eliminate redundant refcounting from @code{_STORE_ATTR_WITH_HINT}.

@item 
gh-142476@footnote{https://github.com/python/cpython/issues/142476}: Fix a memory leak in the experimental Tier 2 optimizer when
creating executors. Patched by Shamil Abdulaev.

@item 
gh-100964@footnote{https://github.com/python/cpython/issues/100964}: Fix reference cycle in exhausted generator frames. Patch by
Savannah Ostrowski.

@item 
gh-139922@footnote{https://github.com/python/cpython/issues/139922}: Allow building CPython with the tail calling interpreter on
Visual Studio 2026 MSVC. This provides a performance gain over the prior
interpreter for MSVC. Patch by Ken Jin, Brandt Bucher, and Chris Eibl.
With help from the MSVC team including Hulon Jenkins.
@end itemize

@node Python 3 15 0 alpha 3,Python 3 15 0 alpha 2,Python 3 15 0 alpha 4,Changelog
@anchor{whatsnew/changelog python-3-15-0-alpha-3}@anchor{199f}
@subsection Python 3.15.0 alpha 3


`Release date: 2025-12-16'

@menu
* Tools/Demos: Tools/Demos<3>. 
* Tests: Tests<7>. 
* Security: Security<6>. 
* Library: Library<8>. 
* Documentation: Documentation<6>. 
* Core and Builtins: Core and Builtins<8>. 
* C API: C API<6>. 
* Build: Build<5>. 

@end menu

@node Tools/Demos<3>,Tests<7>,,Python 3 15 0 alpha 3
@anchor{whatsnew/changelog id43}@anchor{19a0}
@subsubsection Tools/Demos



@itemize -

@item 
gh-141692@footnote{https://github.com/python/cpython/issues/141692}: Each slice of an iOS XCframework now contains a @code{lib} folder
that contains a symlink to the libpython dylib. This allows binary modules
to be compiled for iOS using dynamic libreary linking, rather than
Framework linking.
@end itemize

@node Tests<7>,Security<6>,Tools/Demos<3>,Python 3 15 0 alpha 3
@anchor{whatsnew/changelog id44}@anchor{19a1}
@subsubsection Tests



@itemize -

@item 
gh-140381@footnote{https://github.com/python/cpython/issues/140381}: Fix flaky test_profiling tests on i686 and s390x architectures
by increasing slow_fibonacci call frequency from every 5th iteration to
every 2nd iteration.

@item 
gh-140210@footnote{https://github.com/python/cpython/issues/140210}: Make @code{test_sysconfig.test_parse_makefile_renamed_vars} less
fragile by clearing the environment variables before parsing the Makefile.
@end itemize

@node Security<6>,Library<8>,Tests<7>,Python 3 15 0 alpha 3
@anchor{whatsnew/changelog id45}@anchor{19a2}
@subsubsection Security



@itemize -

@item 
gh-142145@footnote{https://github.com/python/cpython/issues/142145}: Remove quadratic behavior in @code{xml.minidom} node ID cache
clearing.

@item 
gh-42400@footnote{https://github.com/python/cpython/issues/42400}: Fix buffer overflow in @code{_Py_wrealpath()} for paths exceeding
@code{MAXPATHLEN} bytes by using dynamic memory allocation instead of
fixed-size buffer. Patch by Shamil Abdulaev.

@item 
gh-119451@footnote{https://github.com/python/cpython/issues/119451}: Fix a potential memory denial of service in the
@ref{72,,http.client} module. When connecting to a malicious server, it could
cause an arbitrary amount of memory to be allocated. This could have led
to symptoms including a @ref{18fa,,MemoryError}, swapping, out of memory (OOM)
killed processes or containers, or even system crashes.

@item 
gh-119342@footnote{https://github.com/python/cpython/issues/119342}: Fix a potential memory denial of service in the @ref{b0,,plistlib}
module. When reading a Plist file received from untrusted source, it could
cause an arbitrary amount of memory to be allocated. This could have led
to symptoms including a @ref{18fa,,MemoryError}, swapping, out of memory (OOM)
killed processes or containers, or even system crashes.
@end itemize

@node Library<8>,Documentation<6>,Security<6>,Python 3 15 0 alpha 3
@anchor{whatsnew/changelog id46}@anchor{19a3}
@subsubsection Library



@itemize -

@item 
gh-142754@footnote{https://github.com/python/cpython/issues/142754}: Add the `ownerDocument' attribute to @ref{12b,,xml.dom.minidom}
elements and attributes created by directly instantiating the @code{Element}
or @code{Attr} class. Note that this way of creating nodes is not supported;
creator functions like @ref{19a4,,xml.dom.Document.documentElement()} should
be used instead.

@item 
gh-142594@footnote{https://github.com/python/cpython/issues/142594}: Fix crash in @code{TextIOWrapper.close()} when the underlying
buffer’s @code{closed} property calls @ref{19a5,,detach()}.

@item 
gh-76007@footnote{https://github.com/python/cpython/issues/76007}: Deprecate @code{__version__} from @ref{2d,,ctypes}. Patch by Hugo van
Kemenade.

@item 
gh-76007@footnote{https://github.com/python/cpython/issues/76007}: Deprecate @code{__version__} from @ref{124,,wsgiref.simple_server}.
Patch by Hugo van Kemenade.

@item 
gh-142651@footnote{https://github.com/python/cpython/issues/142651}: @ref{110,,unittest.mock}: fix a thread safety issue where
@ref{19a6,,Mock.call_count} may return
inaccurate values when the mock is called concurrently from multiple
threads.

@item 
gh-76007@footnote{https://github.com/python/cpython/issues/76007}: Deprecate @code{__version__} from @ref{75,,http.server}. Patch by Hugo
van Kemenade.

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: Add @code{--subprocesses} flag to @ref{b6,,profiling.sampling} CLI to
automatically profile subprocesses spawned by the target. When enabled,
the profiler monitors for new Python subprocesses and profiles each one
separately, writing results to individual output files. This is useful for
profiling applications that use @ref{98,,multiprocessing},
@ref{206,,ProcessPoolExecutor}, or other
subprocess-based parallelism. Patch by Pablo Galindo.

@item 
gh-142595@footnote{https://github.com/python/cpython/issues/142595}: Added type check during initialization of the @ref{39,,decimal}
module to prevent a crash in case of broken stdlib.  Patch by Sergey B
Kirpichev.

@item 
gh-142556@footnote{https://github.com/python/cpython/issues/142556}: Fix crash when a task gets re-registered during finalization in
@ref{b,,asyncio}. Patch by Kumar Aditya.

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: Add @code{--mode=exception} to the sampling profiler to capture
samples only from threads with an active exception, useful for analyzing
exception handling overhead. Patch by Pablo Galindo.

@item 
gh-142539@footnote{https://github.com/python/cpython/issues/142539}: @ref{107,,traceback}: Fix location of carets in
@ref{17e,,SyntaxError}s when the source contains wide characters.

@item 
gh-123241@footnote{https://github.com/python/cpython/issues/123241}: Avoid reference count operations in garbage collection of
@ref{2d,,ctypes} objects.

@item 
gh-142451@footnote{https://github.com/python/cpython/issues/142451}: @ref{6d,,hmac}: correctly copy @ref{efd,,HMAC} attributes for
objects copied through @ref{19a7,,HMAC.copy()}. Patch by
Bénédikt Tran.

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: The @code{profiling.sampling} flamegraph profiler now supports
inverted flamegraph view that aggregates all leaf nodes. In a standard
flamegraph, if a hot function is called from multiple locations, it
appears multiple times as separate leaf nodes. In the inverted flamegraph,
all occurrences of the same leaf function are merged into a single
aggregated node at the root, showing the total hotness of that function in
one place. The children of each aggregated node represent its callers,
making it easier to identify which functions consume the most CPU time and
where they are called from.

@item 
gh-112527@footnote{https://github.com/python/cpython/issues/112527}: The help text for required options in @ref{7,,argparse} no longer
extended with « (default: None)».

@item 
gh-142438@footnote{https://github.com/python/cpython/issues/142438}: Fixed a possible leaked GIL in _PySSL_keylog_callback.

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: Add bytecode-level instruction profiling to the sampling
profiler via the new @code{--opcodes} flag. When enabled, the profiler
captures which bytecode opcode is executing at each sample, including
Python 3.11+ adaptive specializations, and visualizes this data in the
heatmap, flamegraph, gecko, and live output formats. Patch by Pablo
Galindo

@item 
gh-142389@footnote{https://github.com/python/cpython/issues/142389}: Add backtick markup support in @ref{7,,argparse} description and
epilog text to highlight inline code when color output is enabled.

@item 
gh-142346@footnote{https://github.com/python/cpython/issues/142346}: Fix usage formatting for mutually exclusive groups in
@ref{7,,argparse} when they are preceded by positional arguments or followed
or intermixed with other optional arguments.

@item 
gh-142374@footnote{https://github.com/python/cpython/issues/142374}: Fix cumulative percentage calculation for recursive functions
in the new sampling profiler. When profiling recursive functions,
cumulative statistics (cumul%, cumtime) could exceed 100% because each
recursive frame in a stack was counted separately. For example, a function
recursing 500 times in every sample would show 50000% cumulative presence.
The fix deduplicates locations within each sample so cumulative stats
correctly represent «percentage of samples where this function was on the
stack». Patch by Pablo Galindo.

@item 
gh-142315@footnote{https://github.com/python/cpython/issues/142315}: Pdb can now run scripts from anonymous pipes used in process
substitution. Patch by Bartosz Sławecki.

@item 
gh-64532@footnote{https://github.com/python/cpython/issues/64532}: Subparser help now includes required optional arguments from the
parent parser in the usage, making it clearer what arguments are needed to
run a subcommand. Patch by Savannah Ostrowski.

@item 
gh-142207@footnote{https://github.com/python/cpython/issues/142207}: Fix: profiling.sampling may cause assertion @code{!(has_gil &&
gil_requested)}

@item 
gh-142332@footnote{https://github.com/python/cpython/issues/142332}: Fix usage formatting for positional arguments in mutually
exclusive groups in @ref{7,,argparse}. in @code{argparse}.

@item 
gh-142282@footnote{https://github.com/python/cpython/issues/142282}: Fix @ref{19a8,,winreg.QueryValueEx()} to not accidentally read
garbage buffer under race condition.

@item 
gh-142318@footnote{https://github.com/python/cpython/issues/142318}: Fix typing @code{'q'} at the help of the interactive tachyon
profiler exiting the profiler.

@item 
gh-75949@footnote{https://github.com/python/cpython/issues/75949}: Fix @ref{7,,argparse} to preserve @code{|} separators in mutually
exclusive groups when the usage line wraps due to length.

@item 
gh-142267@footnote{https://github.com/python/cpython/issues/142267}: Improve @ref{7,,argparse} performance by caching the formatter
used for argument validation.

@item 
gh-139862@footnote{https://github.com/python/cpython/issues/139862}: Remove @code{color} parameter from
@code{argparse.HelpFormatter} constructor. Color is controlled by
@ref{1dc,,ArgumentParser}.

@item 
gh-68552@footnote{https://github.com/python/cpython/issues/68552}: @code{MisplacedEnvelopeHeaderDefect} and @code{Missing header name}
defects are now correctly passed to the @code{handle_defect} method of
@code{policy} in @ref{19a9,,FeedParser}.

@item 
gh-142206@footnote{https://github.com/python/cpython/issues/142206}: The resource tracker in the @ref{98,,multiprocessing} module can
now understand messages from older versions of itself. This avoids issues
with upgrading Python while it is running. (Note that such “in-place”
upgrades are not tested.)

@item 
gh-142214@footnote{https://github.com/python/cpython/issues/142214}: Fix two regressions in @ref{32,,dataclasses} in Python 3.14.1
related to annotations.


@itemize *

@item 
An exception is no longer raised if @code{slots=True} is used and the
@code{__init__} method does not have an @code{__annotate__} attribute
(likely because @code{init=False} was used).

@item 
An exception is no longer raised if annotations are requested on the
@code{__init__} method and one of the fields is not present in the class
annotations. This can occur in certain dynamic scenarios.
@end itemize

Patch by Jelle Zijlstra.

@item 
gh-142203@footnote{https://github.com/python/cpython/issues/142203}: Remove the `debug_override' parameter from
@ref{330,,importlib.util.cache_from_source()} which has been deprecated since
Python 3.5.

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: The @code{_remote_debugging} module now implements frame caching
in the @code{RemoteUnwinder} class to reduce memory reads when profiling
remote processes. When @code{cache_frames=True}, unchanged portions of the
call stack are reused from previous samples, significantly improving
profiling performance for deep call stacks.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Fix @ref{19,,cmath} data race when initializing trigonometric
tables with subinterpreters.

@item 
gh-141982@footnote{https://github.com/python/cpython/issues/141982}: Allow @ref{aa,,pdb} to set breakpoints on async functions with
function names.

@item 
gh-74389@footnote{https://github.com/python/cpython/issues/74389}: When the stdin being used by a @ref{6bf,,subprocess.Popen}
instance is closed, this is now ignored in
@ref{19aa,,subprocess.Popen.communicate()} instead of leaving the class in an
inconsistent state.

@item 
gh-87512@footnote{https://github.com/python/cpython/issues/87512}: Fix @ref{19aa,,subprocess.Popen.communicate()} timeout handling on
Windows when writing large input. Previously, the timeout was ignored
during stdin writing, causing the method to block indefinitely if the
child process did not consume input quickly. The stdin write is now
performed in a background thread, allowing the timeout to be properly
enforced.

@item 
gh-141939@footnote{https://github.com/python/cpython/issues/141939}: Add color to all interpolated values in @ref{7,,argparse} help,
like @code{%(default)s} or @code{%(choices)s}. Patch by Alex Prengère.

@item 
gh-141473@footnote{https://github.com/python/cpython/issues/141473}: When @ref{19aa,,subprocess.Popen.communicate()} was called with
`input' and a `timeout' and is called for a second time after a
@ref{19ab,,TimeoutExpired} exception before the process has died,
it should no longer hang.

@item 
gh-141999@footnote{https://github.com/python/cpython/issues/141999}: Correctly allow @ref{d96,,KeyboardInterrupt} to stop the process
when using @code{profiling.sampling}.

@item 
gh-142006@footnote{https://github.com/python/cpython/issues/142006}: Fix a bug in the @ref{19ac,,email.policy.default} folding algorithm
which incorrectly resulted in a doubled newline when a line ending at
exactly max_line_length was followed by an unfoldable token.

@item 
gh-141968@footnote{https://github.com/python/cpython/issues/141968}: Remove data copy from @ref{c1,,re} compilation of regexes with
large charsets by using @ref{1c5,,bytearray.take_bytes()}.

@item 
gh-141968@footnote{https://github.com/python/cpython/issues/141968}: Remove data copy from @ref{55,,encodings.idna}
@ref{19ad,,encode()} and @ref{19ae,,encode()}
by using @ref{1c5,,bytearray.take_bytes()}.

@item 
gh-141968@footnote{https://github.com/python/cpython/issues/141968}: Remove data copy from @ref{1c,,codecs} @code{punycode} encoding by
using @ref{1c5,,bytearray.take_bytes()}.

@item 
gh-141968@footnote{https://github.com/python/cpython/issues/141968}: Remove data copy from @ref{19af,,wave.Wave_read.readframes()} and
@ref{1396,,wave.Wave_write.writeframes()} by using @ref{1c5,,bytearray.take_bytes()}.

@item 
gh-141968@footnote{https://github.com/python/cpython/issues/141968}: Remove a data copy from @ref{1e8,,base64.b32decode()} and
@ref{1e7,,base64.b32encode()} by using @ref{1c5,,bytearray.take_bytes()}.

@item 
gh-59000@footnote{https://github.com/python/cpython/issues/59000}: Fix @ref{aa,,pdb} breakpoint resolution for class methods when the
module defining the class is not imported.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Fix thread safety issue with @ref{c1,,re} scanner objects in
free-threaded builds.

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: The @code{profiling.sampling} flamegraph profiler now displays
thread status statistics showing the percentage of time threads spend
holding the GIL, running without the GIL, waiting for the GIL, and
performing garbage collection. These statistics help identify GIL
contention and thread behavior patterns. When filtering by thread, the
display shows per-thread metrics.

@item 
gh-141781@footnote{https://github.com/python/cpython/issues/141781}: Fixed an issue where pdb.line_prefix assignment was ignored if
assigned after the module was imported.

@item 
gh-141863@footnote{https://github.com/python/cpython/issues/141863}: Update @ref{19b0,,Streams} to use
@ref{1c5,,bytearray.take_bytes()} for a over 10% performance improvement on
pyperformance asyncio_tcp benchmark.

@item 
gh-141817@footnote{https://github.com/python/cpython/issues/141817}: Add @code{socket.IPV6_HDRINCL} constant.

@item 
gh-105836@footnote{https://github.com/python/cpython/issues/105836}: Fix @ref{c58,,asyncio.run_coroutine_threadsafe()} leaving underlying
cancelled asyncio task running.

@item 
gh-141570@footnote{https://github.com/python/cpython/issues/141570}: Support @ref{19b1,,file-like object} raising @ref{53c,,OSError} from
@ref{19b2,,fileno()} in color detection
(@code{_colorize.can_colorize()}). This can occur when @code{sys.stdout} is
redirected.

@item 
gh-141679@footnote{https://github.com/python/cpython/issues/141679}: Add colour to defaults in @ref{7,,argparse} help. Patch by Hugo
van Kemenade.

@item 
gh-141686@footnote{https://github.com/python/cpython/issues/141686}: Break reference cycles created by each call to
@ref{10fb,,json.dump()} or @ref{19b3,,json.JSONEncoder.iterencode()}.

@item 
gh-141659@footnote{https://github.com/python/cpython/issues/141659}: Fix bad file descriptor errors from @code{_posixsubprocess} on
AIX.

@item 
gh-141645@footnote{https://github.com/python/cpython/issues/141645}: Add a new @code{--live} mode to the tachyon profiler in
@code{profiling.sampling} module. This mode consist of a live TUI that
displays real-time profiling statistics as the target application runs,
similar to @code{top}. Patch by Pablo Galindo

@item 
gh-141615@footnote{https://github.com/python/cpython/issues/141615}: Check @code{stdin} instead of @code{stdout} for @code{use_rawinput} in
@ref{aa,,pdb}.

@item 
gh-69113@footnote{https://github.com/python/cpython/issues/69113}: Fix @ref{3d,,doctest} to correctly report line numbers for doctests
in @code{__test__} dictionary when formatted as triple-quoted strings by
finding unique lines in the string and matching them in the source file.

@item 
gh-141600@footnote{https://github.com/python/cpython/issues/141600}: Fix musl version detection on Void Linux.

@item 
gh-48752@footnote{https://github.com/python/cpython/issues/48752}: Add @ref{19b4,,readline.get_pre_input_hook()} function to retrieve the
current pre-input hook. This allows applications to save and restore the
hook without overwriting user settings. Patch by Sanyam Khurana.

@item 
gh-141565@footnote{https://github.com/python/cpython/issues/141565}: Add async-aware profiling to the Tachyon sampling profiler. The
profiler now reconstructs and displays async task hierarchies in
flamegraphs, making the output more actionable for users. Patch by
Savannah Ostrowski and Pablo Galindo Salgado.

@item 
gh-60107@footnote{https://github.com/python/cpython/issues/60107}: Remove a copy from @ref{11d0,,io.RawIOBase.read()}. If the underlying
I/O class keeps a reference to the mutable memory, raise a
@ref{1998,,BufferError}.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make csv module thread-safe on the @ref{487,,free threaded} build.

@item 
gh-140911@footnote{https://github.com/python/cpython/issues/140911}: @ref{1e,,collections}: Ensure that the methods
@code{UserString.rindex()} and @code{UserString.index()} accept
@ref{118c,,collections.UserString} instances as the sub argument.

@item 
gh-140875@footnote{https://github.com/python/cpython/issues/140875}: Fix handling of unclosed character references (named and
numerical) followed by the end of file in @ref{c4d,,html.parser.HTMLParser}
with @code{convert_charrefs=False}.

@item 
gh-140677@footnote{https://github.com/python/cpython/issues/140677}: Add heatmap visualization mode to the Tachyon sampling
profiler. The new @code{--heatmap} output format provides a line-by-line view
showing execution intensity with color-coded samples, inline statistics,
and interactive call graph navigation between callers and callees.

@item 
gh-139946@footnote{https://github.com/python/cpython/issues/139946}: Distinguish stdout and stderr when colorizing output in
argparse module.

@item 
gh-76007@footnote{https://github.com/python/cpython/issues/76007}: @ref{bd,,pydoc}: Fix @ref{2c9,,DeprecationWarning} being raised when
generating doc for @ref{1bb,,stdlib} modules.

@item 
gh-138697@footnote{https://github.com/python/cpython/issues/138697}: Fix inferring `dest' from a single-dash long option in
@ref{7,,argparse}. If a short option and a single-dash long option are
passed to @code{add_argument()}, `dest' is now inferred from the
single-dash long option.

@item 
gh-138525@footnote{https://github.com/python/cpython/issues/138525}: Add support for single-dash long options and alternate prefix
characters in @ref{1db,,argparse.BooleanOptionalAction}.

@item 
gh-79986@footnote{https://github.com/python/cpython/issues/79986}: Add parsing for @code{References} and @code{In-Reply-To} headers to
the @ref{3e,,email} library that parses the header content as lists of
message id tokens.  This prevents them from being folded incorrectly.

@item 
gh-135559@footnote{https://github.com/python/cpython/issues/135559}: Flag: a @code{dir()} on a @code{Flag} enumeration now shows
non-canonical members. (i.e. aliases).

@item 
gh-134453@footnote{https://github.com/python/cpython/issues/134453}: Fixed @ref{19aa,,subprocess.Popen.communicate()} @code{input=} handling
of @ref{1d2,,memoryview} instances that were non-byte shaped on POSIX
platforms. Those are now properly cast to a byte shaped view instead of
truncating the input.  Windows platforms did not have this bug.

@item 
gh-127930@footnote{https://github.com/python/cpython/issues/127930}: Add @code{__all__} to @ref{101,,tkinter.simpledialog}.

@item 
gh-115952@footnote{https://github.com/python/cpython/issues/115952}: Fix a potential memory denial of service in the @ref{ab,,pickle}
module. When reading a pickled data received from untrusted source, it
could cause an arbitrary amount of memory to be allocated, even if the
code that is allowed to execute is restricted by overriding the
@ref{19b5,,find_class()} method. This could have led to
symptoms including a @ref{18fa,,MemoryError}, swapping, out of memory (OOM)
killed processes or containers, or even system crashes.

@item 
bpo-40350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40350}: Fix support for namespace packages in @ref{95,,modulefinder}.
@end itemize

@node Documentation<6>,Core and Builtins<8>,Library<8>,Python 3 15 0 alpha 3
@anchor{whatsnew/changelog id47}@anchor{19b6}
@subsubsection Documentation



@itemize -

@item 
gh-141994@footnote{https://github.com/python/cpython/issues/141994}: @ref{133,,xml.sax.handler}: Make Documentation of
@ref{19b7,,xml.sax.handler.feature_external_ges} warn of opening up to
external entity attacks@footnote{https://en.wikipedia.org/wiki/XML_external_entity_attack}. Patch by
Sebastian Pipping.
@end itemize

@node Core and Builtins<8>,C API<6>,Documentation<6>,Python 3 15 0 alpha 3
@anchor{whatsnew/changelog id48}@anchor{19b8}
@subsubsection Core and Builtins



@itemize -

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Eliminate redundant refcounting from
@code{_STORE_ATTR_INSTANCE_VALUE}.

@item 
gh-142718@footnote{https://github.com/python/cpython/issues/142718}: JIT: Fix segfault caused by not flushing the stack to memory at
side exits.

@item 
gh-142737@footnote{https://github.com/python/cpython/issues/142737}: Tracebacks will be displayed in fallback mode even if
@ref{92b,,io.open()} is lost. Previously, this would crash the interpreter.
Patch by Bartosz Sławecki.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make the attributes in @ref{14,,bz2} thread-safe on the
@ref{487,,free threaded} build.

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Eliminate redundant refcounting from @code{_CALL_LIST_APPEND}.

@item 
gh-142554@footnote{https://github.com/python/cpython/issues/142554}: Fix a crash in @ref{d6a,,divmod()} when @code{_pylong.int_divmod()}
does not return a tuple of length two exactly. Patch by Bénédikt Tran.

@item 
gh-142531@footnote{https://github.com/python/cpython/issues/142531}: Fix a free-threaded GC performance regression.  If there are
many untracked tuples, the GC will run too often, resulting in poor
performance.  The fix is to include untracked tuples in the «long lived»
object count. The number of frozen objects is also now included since the
free-threaded GC must scan those too.

@item 
gh-142402@footnote{https://github.com/python/cpython/issues/142402}: Fix reference counting when adjacent literal parts are merged
while constructing @ref{415,,string.templatelib.Template}, preventing the
displaced string object from leaking.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make the attributes in @ref{13c,,zlib} thread-safe on the
@ref{487,,free threaded} build.

@item 
gh-142343@footnote{https://github.com/python/cpython/issues/142343}: Fix SIGILL crash on m68k due to incorrect assembly constraint.

@item 
gh-142236@footnote{https://github.com/python/cpython/issues/142236}: Improve the «Perhaps you forgot a comma?» syntax error for
multi-line string concatenations to point to the last string instead of
the first, making it easier to locate where the comma is missing. Patch by
Pablo Galindo.

@item 
gh-142236@footnote{https://github.com/python/cpython/issues/142236}: Fix incorrect keyword suggestions for syntax errors in
@ref{107,,traceback}. The keyword typo suggestion mechanism would incorrectly
suggest replacements when the extracted source code was incomplete rather
than containing an actual typo. Patch by Pablo Galindo.

@item 
gh-142305@footnote{https://github.com/python/cpython/issues/142305}: Decrease the size of the generated stencils and the runtime JIT
code. Patch by Diego Russo.

@item 
gh-135379@footnote{https://github.com/python/cpython/issues/135379}: Implement a limited form of register allocation known as «top
of stack caching» in the JIT. It works by keeping 0-3 of the top items in
the stack in registers. The code generator generates multiple versions of
those uops that do not escape and are relatively small. During JIT
compilation, the copy that produces the least memory traffic is selected,
spilling or reloading values when needed.

@item 
gh-142276@footnote{https://github.com/python/cpython/issues/142276}: Fix missing type watcher when promoting attribute loads to
constants in the JIT. Patch by Ken Jin. Reproducer by Yuancheng Jiang.

@item 
gh-142218@footnote{https://github.com/python/cpython/issues/142218}: Fix crash when inserting into a split table dictionary with a
non @ref{1df,,str} key that matches an existing key.

@item 
gh-141976@footnote{https://github.com/python/cpython/issues/141976}: Check against abstract stack overflow in the JIT optimizer.

@item 
gh-97850@footnote{https://github.com/python/cpython/issues/97850}: Remove all @code{*.load_module()} usage and definitions from the
import system and importlib. The method has been deprecated in favor of
@code{importlib.abc.Loader.exec_module()} since Python 3.4.

@item 
gh-142048@footnote{https://github.com/python/cpython/issues/142048}: Fix quadratically increasing garbage collection delays in
free-threaded build.

@item 
gh-65961@footnote{https://github.com/python/cpython/issues/65961}: Stop setting @code{__cached__} on modules.

@item 
gh-141770@footnote{https://github.com/python/cpython/issues/141770}: Annotate anonymous mmap usage only when supported by the Linux
kernel and if @code{-X dev} is used or Python is built in debug mode. Patch
by Donghee Na.

@item 
gh-142029@footnote{https://github.com/python/cpython/issues/142029}: Raise @ref{1be,,ModuleNotFoundError} instead of crashing when a
nonexistent module is used as a name in @code{_imp.create_builtin()}.

@item 
gh-142029@footnote{https://github.com/python/cpython/issues/142029}: Raise @ref{277,,ValueError} instead of crashing when empty string
is used as a name in @code{_imp.create_builtin()}.

@item 
gh-141976@footnote{https://github.com/python/cpython/issues/141976}: Protect against specialization failures in the tracing JIT
compiler for performance reasons.

@item 
gh-141861@footnote{https://github.com/python/cpython/issues/141861}: Fix invalid memory read in the @code{ENTER_EXECUTOR} instruction.

@item 
gh-141930@footnote{https://github.com/python/cpython/issues/141930}: When importing a module, use Python’s regular file object to
ensure that writes to @code{.pyc} files are complete or an appropriate error
is raised.

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: Add incomplete sample detection to prevent corrupted profiling
data. Each thread state now contains an embedded base frame (sentinel at
the bottom of the frame stack) with owner type
@code{FRAME_OWNED_BY_INTERPRETER}. The profiler validates that stack
unwinding terminates at this sentinel frame. Samples that fail to reach
the base frame (due to race conditions, memory corruption, or other
errors) are now rejected rather than being included as spurious data.

@item 
gh-120158@footnote{https://github.com/python/cpython/issues/120158}: Fix inconsistent state when enabling or disabling monitoring
events too many times.

@item 
gh-140638@footnote{https://github.com/python/cpython/issues/140638}: Expose a @code{"candidates"} stat in @ref{557,,gc.get_stats()} and
@ref{1474,,gc.callbacks}.

@item 
gh-141780@footnote{https://github.com/python/cpython/issues/141780}: Fix @ref{691,,Py_mod_gil} with API added in 
@geindex Python Enhancement Proposals; PEP 793
PEP 793@footnote{https://peps.python.org/pep-0793/}:
@code{PyModule_FromSlotsAndSpec()} and @code{PyModExport} hooks

@item 
gh-141732@footnote{https://github.com/python/cpython/issues/141732}: Ensure the @ref{1bc,,__repr__()} for @ref{6d8,,ExceptionGroup}
and @ref{767,,BaseExceptionGroup} does not change when the exception sequence
that was original passed in to its constructor is subsequently mutated.

@item 
gh-140638@footnote{https://github.com/python/cpython/issues/140638}: Expose a @code{"duration"} stat in @ref{557,,gc.get_stats()} and
@ref{1474,,gc.callbacks}.

@item 
gh-139653@footnote{https://github.com/python/cpython/issues/139653}: Only raise a @code{RecursionError} or trigger a fatal error if the
stack pointer is both below the limit pointer `and' above the stack base.
If outside of these bounds assume that it is OK. This prevents false
positives when user-space threads swap stacks.

@item 
gh-41779@footnote{https://github.com/python/cpython/issues/41779}: Allowed defining the `__dict__' and `__weakref__'
@ref{1cd,,__slots__} for any class.

@item 
gh-139103@footnote{https://github.com/python/cpython/issues/139103}: Improve multithreaded scaling of dataclasses on the
free-threaded build.

@item 
gh-141589@footnote{https://github.com/python/cpython/issues/141589}: Change @code{backoff counter} to use prime numbers instead of
powers of 2. Use only 3 bits for @code{counter} and 13 bits for @code{value}.
This allows to support values up to 8191. Patch by Mikhail Efimov.

@item 
gh-137007@footnote{https://github.com/python/cpython/issues/137007}: Fix a bug during JIT compilation failure which caused garbage
collection debug assertions to fail.

@item 
gh-132657@footnote{https://github.com/python/cpython/issues/132657}: For the free-threaded build, avoid locking the @ref{42b,,set}
object for the @code{__contains__} method.

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Eliminate redundant refcounting from @code{_CALL_STR_1}.

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Eliminate redundant refcounting from @code{_CALL_BUILTIN_O}.

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Eliminate redundant refcounting from @code{_CALL_TUPLE_1}. Patch
by Noam Cohen
@end itemize

@node C API<6>,Build<5>,Core and Builtins<8>,Python 3 15 0 alpha 3
@anchor{whatsnew/changelog id49}@anchor{19b9}
@subsubsection C API



@itemize -

@item 
gh-142589@footnote{https://github.com/python/cpython/issues/142589}: Fix @ref{5f3,,PyUnstable_Object_IsUniqueReferencedTemporary()}
handling of tagged ints on the interpreter stack.

@item 
gh-142571@footnote{https://github.com/python/cpython/issues/142571}: @code{PyUnstable_CopyPerfMapFile()} now checks that opening
the file succeeded before flushing.

@item 
gh-142225@footnote{https://github.com/python/cpython/issues/142225}: Fixed the @ref{35a,,PyABIInfo_VAR} macro.

@item 
gh-141049@footnote{https://github.com/python/cpython/issues/141049}: @code{_PyObject_CallMethodId()},
@code{_PyObject_GetAttrId()} and @code{_PyUnicode_FromId()} are
deprecated since 3.15 and will be removed in 3.20. Instead, use
@ref{3b5,,PyUnicode_InternFromString()} and cache the result in the module
state, then call @ref{3b6,,PyObject_CallMethod()} or
@ref{3b7,,PyObject_GetAttr()}. Patch by Victor Stinner.

@item 
gh-142163@footnote{https://github.com/python/cpython/issues/142163}: Fix the @code{HAVE_THREAD_LOCAL} macro being defined without the
@code{Py_BUILD_CORE} macro set after including @code{Python.h}.

@item 
gh-137422@footnote{https://github.com/python/cpython/issues/137422}: Fix @ref{487,,free threading} race condition in
@ref{7f1,,PyImport_AddModuleRef()}. It was previously possible for two calls
to the function return two different objects, only one of which was stored
in @ref{19ba,,sys.modules}.

@item 
gh-141726@footnote{https://github.com/python/cpython/issues/141726}: Add @ref{7db,,PyDict_SetDefaultRef()} to the Stable ABI.

@item 
gh-140042@footnote{https://github.com/python/cpython/issues/140042}: Removed the sqlite3_shutdown call that could cause closing
connections for sqlite when used with multiple sub interpreters.

@item 
gh-141070@footnote{https://github.com/python/cpython/issues/141070}: Add @code{PyUnstable_Object_Dump()} to dump an object to
@code{stderr}. It should only be used for debugging. Patch by Victor Stinner.

@item 
gh-139165@footnote{https://github.com/python/cpython/issues/139165}: Expose the functions @ref{b61,,Py_SIZE()}, @ref{19bb,,Py_IS_TYPE()}
and @ref{b62,,Py_SET_SIZE()} in the Stable ABI.
@end itemize

@node Build<5>,,C API<6>,Python 3 15 0 alpha 3
@anchor{whatsnew/changelog id50}@anchor{19bc}
@subsubsection Build



@itemize -

@item 
gh-131372@footnote{https://github.com/python/cpython/issues/131372}: Add @code{LDVERSION} and @code{EXE} to the @code{base_interpreter} value
of @code{build-details.json}.

@item 
gh-142454@footnote{https://github.com/python/cpython/issues/142454}: When calculating the digest of the JIT stencils input, sort the
hashed files by filenames before adding their content to the hasher. This
ensures deterministic hash input and hence deterministic hash, independent
on filesystem order.

@item 
gh-131372@footnote{https://github.com/python/cpython/issues/131372}: @code{build-details.py} will only be installed as part of the main
install (@code{make install}). @code{make altinstall} will no longer include it.

@item 
gh-142234@footnote{https://github.com/python/cpython/issues/142234}: Allow @code{--enable-wasm-dynamic-linking} for WASI. While CPython
doesn’t directly support it so external/downstream users do not have to
patch in support for the flag.

@item 
gh-142050@footnote{https://github.com/python/cpython/issues/142050}: Fixed a bug where JIT stencils produced on Windows contained
debug data. Patch by Chris Eibl.

@item 
gh-141808@footnote{https://github.com/python/cpython/issues/141808}: Do not generate the jit stencils twice in case of PGO builds on
Windows.

@item 
gh-141926@footnote{https://github.com/python/cpython/issues/141926}: @code{RUNSHARED} is no longer cleared when cross-compiling.
Previously, @code{RUNSHARED} was cleared when cross-compiling, which breaks
PGO when using @code{--enabled-shared} on systems where the cross-compiled
CPython is otherwise executable (e.g., via transparent emulation).

@item 
gh-141808@footnote{https://github.com/python/cpython/issues/141808}: When running @code{make clean-retain-profile}, keep the generated
JIT stencils. That way, the stencils are not generated twice when
Profile-guided optimization (PGO) is used. It also allows distributors to
supply their own pre-built JIT stencils.

@item 
gh-141784@footnote{https://github.com/python/cpython/issues/141784}: Fix @code{_remote_debugging_module.c} compilation on 32-bit Linux.
Include Python.h before system headers to make sure that
@code{_remote_debugging_module.c} uses the same types (ABI) than Python.
Patch by Victor Stinner.

@item 
gh-141172@footnote{https://github.com/python/cpython/issues/141172}: Update to WASI SDK 29.

@item 
gh-139707@footnote{https://github.com/python/cpython/issues/139707}: Add configure option
@ref{3d7,,--with-missing-stdlib-config=FILE} allows which distributors to
pass a JSON@footnote{https://www.json.org/json-en.html} configuration file
containing custom error messages for missing @ref{3d8,,standard library}
modules.

@item 
gh-108819@footnote{https://github.com/python/cpython/issues/108819}: Honor @ref{19bd,,--with-platlibdir} in the pure-Python standard
library installation path, if @code{PLATLIBDIR} doesn’t match the value used
in @code{LIBDIR}.
@end itemize

@node Python 3 15 0 alpha 2,Python 3 15 0 alpha 1,Python 3 15 0 alpha 3,Changelog
@anchor{whatsnew/changelog python-3-15-0-alpha-2}@anchor{19be}
@subsection Python 3.15.0 alpha 2


`Release date: 2025-11-18'

@menu
* Windows: Windows<6>. 
* Tools/Demos: Tools/Demos<4>. 
* Tests: Tests<8>. 
* Security: Security<7>. 
* Library: Library<9>. 
* Core and Builtins: Core and Builtins<9>. 
* Library: Library<10>. 
* Core and Builtins: Core and Builtins<10>. 
* Library: Library<11>. 
* Core and Builtins: Core and Builtins<11>. 
* Library: Library<12>. 
* Core and Builtins: Core and Builtins<12>. 
* Library: Library<13>. 
* Core and Builtins: Core and Builtins<13>. 
* Library: Library<14>. 
* Core and Builtins: Core and Builtins<14>. 
* C API: C API<7>. 
* Build: Build<6>. 

@end menu

@node Windows<6>,Tools/Demos<4>,,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id51}@anchor{19bf}
@subsubsection Windows



@itemize -

@item 
gh-140849@footnote{https://github.com/python/cpython/issues/140849}: Update bundled liblzma to version 5.8.1.
@end itemize

@node Tools/Demos<4>,Tests<8>,Windows<6>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id52}@anchor{19c0}
@subsubsection Tools/Demos



@itemize -

@item 
gh-141442@footnote{https://github.com/python/cpython/issues/141442}: The iOS testbed now correctly handles test arguments that
contain spaces.

@item 
gh-140702@footnote{https://github.com/python/cpython/issues/140702}: The iOS testbed app will now expose the @code{GITHUB_ACTIONS}
environment variable to iOS apps being tested.

@item 
gh-139198@footnote{https://github.com/python/cpython/issues/139198}: Remove @code{Tools/scripts/checkpip.py} script.

@item 
gh-139188@footnote{https://github.com/python/cpython/issues/139188}: Remove @code{Tools/tz/zdump.py} script.
@end itemize

@node Tests<8>,Security<7>,Tools/Demos<4>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id53}@anchor{19c1}
@subsubsection Tests



@itemize -

@item 
gh-140482@footnote{https://github.com/python/cpython/issues/140482}: Preserve and restore the state of @code{stty echo} as part of the
test environment.

@item 
gh-140082@footnote{https://github.com/python/cpython/issues/140082}: Update @code{python -m test} to set @code{FORCE_COLOR=1} when being
run with color enabled so that @ref{10f,,unittest} which is run by it with
redirected output will output in color.

@item 
gh-136442@footnote{https://github.com/python/cpython/issues/136442}: Use exitcode @code{1} instead of @code{5} if
@ref{e12,,unittest.TestCase.setUpClass()} raises an exception
@end itemize

@node Security<7>,Library<9>,Tests<8>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id54}@anchor{19c2}
@subsubsection Security



@itemize -

@item 
gh-137836@footnote{https://github.com/python/cpython/issues/137836}: Add support of the «plaintext» element, RAWTEXT elements «xmp»,
«iframe», «noembed» and «noframes», and optionally RAWTEXT element
«noscript» in @ref{c4d,,html.parser.HTMLParser}.

@item 
gh-136063@footnote{https://github.com/python/cpython/issues/136063}: @ref{47,,email.message}: ensure linear complexity for legacy HTTP
parameters parsing. Patch by Bénédikt Tran.

@item 
gh-136065@footnote{https://github.com/python/cpython/issues/136065}: Fix quadratic complexity in @ref{177c,,os.path.expandvars()}.
@end itemize

@node Library<9>,Core and Builtins<9>,Security<7>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id55}@anchor{19c3}
@subsubsection Library



@itemize -

@item 
gh-141497@footnote{https://github.com/python/cpython/issues/141497}: @ref{83,,ipaddress}: ensure that the methods
@ref{19c4,,IPv4Network.hosts()} and
@ref{19c5,,IPv6Network.hosts()} always return an
iterator.

@item 
gh-140938@footnote{https://github.com/python/cpython/issues/140938}: The @ref{ac1,,statistics.stdev()} and @ref{19c6,,statistics.pstdev()}
functions now raise a @ref{277,,ValueError} when the input contains an
infinity or a NaN.

@item 
gh-124111@footnote{https://github.com/python/cpython/issues/124111}: Updated Tcl threading configuration in @ref{3,,_tkinter} to
assume that threads are always available in Tcl 9 and later.

@item 
gh-137109@footnote{https://github.com/python/cpython/issues/137109}: The @ref{6bd,,os.fork} and related forking APIs will no longer warn
in the common case where Linux or macOS platform APIs return the number of
threads in a process and find the answer to be 1 even when a
@ref{332,,os.register_at_fork()} @code{after_in_parent=} callback (re)starts a
thread.

@item 
gh-141314@footnote{https://github.com/python/cpython/issues/141314}: Fix assertion failure in @ref{19c7,,io.TextIOWrapper.tell()} when
reading files with standalone carriage return (@code{\r}) line endings.

@item 
gh-141311@footnote{https://github.com/python/cpython/issues/141311}: Fix assertion failure in @code{io.BytesIO.readinto()} and
undefined behavior arising when read position is above capcity in
@ref{1255,,io.BytesIO}.

@item 
gh-87710@footnote{https://github.com/python/cpython/issues/87710}: @ref{93,,mimetypes}: Update mime type for @code{.ai} files to
@code{application/pdf}.

@item 
gh-85524@footnote{https://github.com/python/cpython/issues/85524}: Update @code{io.FileIO.readall}, an implementation of
@ref{19c8,,io.RawIOBase.readall()}, to follow @ref{70a,,io.IOBase} guidelines and
raise @ref{19c9,,io.UnsupportedOperation} when a file is in «w» mode rather
than @ref{53c,,OSError}

@item 
gh-141141@footnote{https://github.com/python/cpython/issues/141141}: Fix a thread safety issue with @ref{1f2,,base64.b85decode()}.
Contributed by Benel Tayar.

@item 
gh-141018@footnote{https://github.com/python/cpython/issues/141018}: @ref{93,,mimetypes}: Update @code{.exe}, @code{.dll}, @code{.rtf} and (when
@code{strict=False}) @code{.jpg} to their correct IANA mime type.

@item 
gh-137969@footnote{https://github.com/python/cpython/issues/137969}: Fix @ref{150,,annotationlib.ForwardRef.evaluate()} returning
@ref{1967,,ForwardRef} objects which don’t update with new
globals.

@item 
gh-75593@footnote{https://github.com/python/cpython/issues/75593}: Add support of @ref{79f,,path-like objects} and
@ref{436,,bytes-like objects} in @ref{d17,,wave.open()}.

@item 
gh-140797@footnote{https://github.com/python/cpython/issues/140797}: The undocumented @code{re.Scanner} class now forbids regular
expressions containing capturing groups in its lexicon patterns. Patterns
using capturing groups could previously lead to crashes with segmentation
fault. Use non-capturing groups (?:…) instead.

@item 
gh-125115@footnote{https://github.com/python/cpython/issues/125115}: Refactor the @ref{aa,,pdb} parsing issue so positional arguments
can pass through intuitively.

@item 
gh-140815@footnote{https://github.com/python/cpython/issues/140815}: @ref{5b,,faulthandler} now detects if a frame or a code object is
invalid or freed. Patch by Victor Stinner.

@item 
gh-100218@footnote{https://github.com/python/cpython/issues/100218}: Correctly set @ref{19ca,,errno} when
@ref{df2,,socket.if_nametoindex()} or @ref{df3,,socket.if_indextoname()} raise an
@ref{53c,,OSError}. Patch by Bénédikt Tran.

@item 
gh-140734@footnote{https://github.com/python/cpython/issues/140734}: @ref{98,,multiprocessing}: fix off-by-one error when checking the
length of a temporary socket file path. Patch by Bénédikt Tran.

@item 
gh-140873@footnote{https://github.com/python/cpython/issues/140873}: Add support of non-@ref{21f,,descriptor} callables in
@ref{21e,,functools.singledispatchmethod()}.

@item 
gh-140874@footnote{https://github.com/python/cpython/issues/140874}: Bump the version of pip bundled in ensurepip to version 25.3

@item 
gh-140826@footnote{https://github.com/python/cpython/issues/140826}: Now @code{winreg.HKEYType} objects are compared by their
underlying Windows registry handle value instead of their object identity.

@item 
gh-140808@footnote{https://github.com/python/cpython/issues/140808}: The internal class @code{mailbox._ProxyFile} is no longer a
parameterized generic.

@item 
gh-140691@footnote{https://github.com/python/cpython/issues/140691}: In @ref{114,,urllib.request}, when opening a FTP URL fails because
a data connection cannot be made, the control connection’s socket is now
closed to avoid a @ref{74f,,ResourceWarning}.

@item 
gh-103847@footnote{https://github.com/python/cpython/issues/103847}: Fix hang when cancelling process created by
@ref{e3a,,asyncio.create_subprocess_exec()} or
@ref{e3b,,asyncio.create_subprocess_shell()}. Patch by Kumar Aditya.

@item 
gh-137821@footnote{https://github.com/python/cpython/issues/137821}: Convert @code{_json} module to use Argument Clinic. Patched by
Yoonho Hann.

@item 
gh-140790@footnote{https://github.com/python/cpython/issues/140790}: Initialize all Pdb’s instance variables in @code{__init__},
remove some hasattr/getattr

@item 
gh-140766@footnote{https://github.com/python/cpython/issues/140766}: Add @ref{19cb,,enum.show_flag_values()} and @code{enum.bin} to
@code{enum.__all__}.

@item 
gh-120057@footnote{https://github.com/python/cpython/issues/120057}: Add @ref{4e4,,os.reload_environ()} to @code{os.__all__}.

@item 
gh-140741@footnote{https://github.com/python/cpython/issues/140741}: Fix @code{profiling.sampling.sample()} incorrectly handling a
@ref{243,,FileNotFoundError} or @ref{10f9,,PermissionError}.

@item 
gh-140228@footnote{https://github.com/python/cpython/issues/140228}: Avoid making unnecessary filesystem calls for frozen modules in
@ref{88,,linecache} when the global module cache is not present.

@item 
gh-139946@footnote{https://github.com/python/cpython/issues/139946}: Error and warning keywords in @code{argparse.ArgumentParser}
messages are now colorized when color output is enabled, fixing a visual
inconsistency in which they remained plain text while other output was
colorized.

@item 
gh-140590@footnote{https://github.com/python/cpython/issues/140590}: Fix arguments checking for the
@code{functools.partial.__setstate__()} that may lead to internal state
corruption and crash. Patch by Sergey Miryanov.

@item 
gh-125434@footnote{https://github.com/python/cpython/issues/125434}: Display thread name in @ref{5b,,faulthandler} on Windows. Patch by
Victor Stinner.

@item 
gh-140634@footnote{https://github.com/python/cpython/issues/140634}: Fix a reference counting bug in
@code{os.sched_param.__reduce__()}.

@item 
gh-140650@footnote{https://github.com/python/cpython/issues/140650}: Fix an issue where closing @ref{1754,,io.BufferedWriter} could
crash if the closed attribute raised an exception on access or could not
be converted to a boolean.

@item 
gh-140633@footnote{https://github.com/python/cpython/issues/140633}: Ignore @ref{1a9,,AttributeError} when setting a module’s
@code{__file__} attribute when loading an extension module packaged as Apple
Framework.

@item 
gh-140601@footnote{https://github.com/python/cpython/issues/140601}: @ref{3eb,,xml.etree.ElementTree.iterparse()} now emits a
@ref{74f,,ResourceWarning} when the iterator is not explicitly closed and was
opened with a filename. This helps developers identify and fix resource
leaks. Patch by Osama Abdelkader.

@item 
gh-140593@footnote{https://github.com/python/cpython/issues/140593}: @ref{12f,,xml.parsers.expat}: Fix a memory leak that could affect
users with @ref{1922,,ElementDeclHandler()} set to
a custom element declaration handler. Patch by Sebastian Pipping.

@item 
gh-140607@footnote{https://github.com/python/cpython/issues/140607}: Inside @ref{11d0,,io.RawIOBase.read()}, validate that the count of
bytes returned by @ref{11d1,,io.RawIOBase.readinto()} is valid (inside the
provided buffer).

@item 
gh-138162@footnote{https://github.com/python/cpython/issues/138162}: Fix @ref{169a,,logging.LoggerAdapter} with @code{merge_extra=True}
and without the `extra' argument.

@item 
gh-140481@footnote{https://github.com/python/cpython/issues/140481}: Improve error message when trying to iterate a Tk widget, image
or font.

@item 
gh-138774@footnote{https://github.com/python/cpython/issues/138774}: @ref{cb6,,ast.unparse()} now generates full source code when
handling @ref{19cc,,ast.Interpolation} nodes that do not have a specified
source.

@item 
gh-140474@footnote{https://github.com/python/cpython/issues/140474}: Fix memory leak in @ref{6c5,,array.array} when creating arrays
from an empty @ref{1df,,str} and the @code{u} type code.

@item 
gh-140448@footnote{https://github.com/python/cpython/issues/140448}: Change the default of @code{suggest_on_error} to @code{True} in
@code{argparse.ArgumentParser}.

@item 
gh-137530@footnote{https://github.com/python/cpython/issues/137530}: @ref{32,,dataclasses} Fix annotations for generated @code{__init__}
methods by replacing the annotations that were in-line in the generated
source code with @code{__annotate__} functions attached to the methods.

@item 
gh-140348@footnote{https://github.com/python/cpython/issues/140348}: Fix regression in Python 3.14.0 where using the @code{|} operator
on a @ref{341,,typing.Union} object combined with an object that is not a
type would raise an error.

@item 
gh-76007@footnote{https://github.com/python/cpython/issues/76007}: @ref{39,,decimal}: Deprecate @code{__version__} and replace with
@ref{2fd,,decimal.SPEC_VERSION}.

@item 
gh-76007@footnote{https://github.com/python/cpython/issues/76007}: Deprecate @code{__version__} from @ref{77,,imaplib}. Patch by Hugo van
Kemenade.

@item 
gh-140272@footnote{https://github.com/python/cpython/issues/140272}: Fix memory leak in the @code{clear()} method of the
@ref{36,,dbm.gnu} database.

@item 
gh-129117@footnote{https://github.com/python/cpython/issues/129117}: @ref{10e,,unicodedata}: Add @ref{297,,isxidstart()} and
@ref{298,,isxidcontinue()} functions to check whether a character
can start or continue a Unicode Standard Annex #31@footnote{https://www.unicode.org/reports/tr31/} identifier.

@item 
gh-140251@footnote{https://github.com/python/cpython/issues/140251}: Colorize the default import statement @code{import asyncio} in
asyncio REPL.

@item 
gh-140212@footnote{https://github.com/python/cpython/issues/140212}: Calendar’s HTML formatting now accepts year and month as
options. Previously, running @code{python -m calendar -t html 2025 10} would
result in an error message. It now generates an HTML document displaying
the calendar for the specified month. Contributed by Pål Grønås Drange.

@item 
gh-135801@footnote{https://github.com/python/cpython/issues/135801}: Improve filtering by module in @ref{2ab,,warnings.warn_explicit()}
if no `module' argument is passed. It now tests the module regular
expression in the warnings filter not only against the filename with
@code{.py} stripped, but also against module names constructed starting from
different parent directories of the filename (with @code{/__init__.py},
@code{.py} and, on Windows, @code{.pyw} stripped).

@item 
gh-139707@footnote{https://github.com/python/cpython/issues/139707}: Improve @ref{1be,,ModuleNotFoundError} error message when a
@ref{3d8,,standard library} module is missing.

@item 
gh-140041@footnote{https://github.com/python/cpython/issues/140041}: Fix import of @ref{2d,,ctypes} on Android and Cygwin when ABI
flags are present.

@item 
gh-140120@footnote{https://github.com/python/cpython/issues/140120}: Fixed a memory leak in @ref{6d,,hmac} when it was using the
hacl-star backend. Discovered by @code{@@ashm-dev} using AddressSanitizer.

@item 
gh-140141@footnote{https://github.com/python/cpython/issues/140141}: The @ref{19cd,,importlib.metadata.PackageNotFoundError}
traceback raised when @code{importlib.metadata.Distribution.from_name} cannot
discover a distribution no longer includes a transient
@ref{fba,,StopIteration} exception trace.

Contributed by Bartosz Sławecki in gh-140142@footnote{https://github.com/python/cpython/issues/140142}.

@item 
gh-140166@footnote{https://github.com/python/cpython/issues/140166}: @ref{93,,mimetypes}: Per the IANA assignment@footnote{https://www.iana.org/assignments/media-types/application/texinfo},
update the MIME type for the @code{.texi} and @code{.texinfo} file formats to
@code{application/texinfo}, instead of @code{application/x-texinfo}.

@item 
gh-140135@footnote{https://github.com/python/cpython/issues/140135}: Speed up @ref{19c8,,io.RawIOBase.readall()} by using PyBytesWriter
API (about 4x faster)

@item 
gh-76007@footnote{https://github.com/python/cpython/issues/76007}: @ref{13c,,zlib}: Deprecate @code{__version__} and schedule for removal
in Python 3.20.

@item 
gh-136702@footnote{https://github.com/python/cpython/issues/136702}: @ref{54,,encodings}: Deprecate passing a non-ascii `encoding' name
to @ref{313,,encodings.normalize_encoding()} and schedule removal of support
for Python 3.17.

@item 
gh-139940@footnote{https://github.com/python/cpython/issues/139940}: Print clearer error message when using @code{pdb} to attach to a
non-existing process.

@item 
gh-139462@footnote{https://github.com/python/cpython/issues/139462}: When a child process in a
@ref{206,,concurrent.futures.ProcessPoolExecutor} terminates abruptly, the
resulting traceback will now tell you the PID and exit code of the
terminated process. Contributed by Jonathan Berg.

@item 
gh-63161@footnote{https://github.com/python/cpython/issues/63161}: Fix @ref{19ce,,tokenize.detect_encoding()}. Support non-UTF-8 shebang
and comments if non-UTF-8 encoding is specified. Detect decoding error for
non-UTF-8 encoding. Detect null bytes in source code.

@item 
gh-101828@footnote{https://github.com/python/cpython/issues/101828}: Fix @code{'shift_jisx0213'}, @code{'shift_jis_2004'},
@code{'euc_jisx0213'} and @code{'euc_jis_2004'} codecs truncating null chars as
they were treated as part of multi-character sequences.

@item 
gh-139246@footnote{https://github.com/python/cpython/issues/139246}: fix: paste zero-width in default repl width is wrong.

@item 
gh-83714@footnote{https://github.com/python/cpython/issues/83714}: Implement @ref{23f,,os.statx()} on Linux kernel versions 4.11 and
later with glibc versions 2.28 and later.  Contributed by Jeffrey Bosboom
and Victor Stinner.

@item 
gh-138891@footnote{https://github.com/python/cpython/issues/138891}: Fix @code{SyntaxError} when @code{inspect.get_annotations(f,
eval_str=True)} is called on a function annotated with a 
@geindex Python Enhancement Proposals; PEP 646
PEP 646@footnote{https://peps.python.org/pep-0646/}
@code{star_expression}

@item 
gh-138859@footnote{https://github.com/python/cpython/issues/138859}: Fix generic type parameterization raising a @ref{291,,TypeError}
when omitting a @code{ParamSpec} that has a default which is not a list
of types.

@item 
gh-138764@footnote{https://github.com/python/cpython/issues/138764}: Prevent @ref{19cf,,annotationlib.call_annotate_function()} from
calling @code{__annotate__} functions that don’t support
@code{VALUE_WITH_FAKE_GLOBALS} in a fake globals namespace with empty
globals.

Make @code{FORWARDREF} and @code{STRING} annotations fall back to using
@code{VALUE} annotations in the case that neither their own format, nor
@code{VALUE_WITH_FAKE_GLOBALS} are supported.

@item 
gh-138775@footnote{https://github.com/python/cpython/issues/138775}: Use of @code{python -m} with @ref{f,,base64} has been fixed to
detect input from a terminal so that it properly notices EOF.

@item 
gh-98896@footnote{https://github.com/python/cpython/issues/98896}: Fix a failure in multiprocessing resource_tracker when
SharedMemory names contain colons. Patch by Rani Pinchuk.

@item 
gh-138425@footnote{https://github.com/python/cpython/issues/138425}: Fix partial evaluation of @ref{1967,,annotationlib.ForwardRef}
objects which rely on names defined as globals.

@item 
gh-138151@footnote{https://github.com/python/cpython/issues/138151}: In @ref{6,,annotationlib}, improve evaluation of forward
references to nonlocal variables that are not yet defined when the
annotations are initially evaluated.

@item 
gh-69528@footnote{https://github.com/python/cpython/issues/69528}: The @ref{19d0,,mode} attribute of files opened in the
@code{'wb+'} mode is now @code{'wb+'} instead of @code{'rb+'}.

@item 
gh-137627@footnote{https://github.com/python/cpython/issues/137627}: Speed up @ref{2c2,,csv.Sniffer.sniff()} delimiter detection by up to
1.6x.

@item 
gh-55531@footnote{https://github.com/python/cpython/issues/55531}: @ref{54,,encodings}: Improve @ref{313,,normalize_encoding()}
performance by implementing the function in C using the private
@code{_Py_normalize_encoding} which has been modified to make lowercase
conversion optional.

@item 
gh-136057@footnote{https://github.com/python/cpython/issues/136057}: Fixed the bug in @ref{aa,,pdb} and @ref{10,,bdb} where @code{next} and
@code{step} can’t go over the line if a loop exists in the line.

@item 
gh-133390@footnote{https://github.com/python/cpython/issues/133390}: Support table, index, trigger, view, column, function, and
schema completion for @ref{d7,,sqlite3}’s @ref{257,,command-line interface}.

@item 
gh-135307@footnote{https://github.com/python/cpython/issues/135307}: @ref{3e,,email}: Fix exception in @code{set_content()} when encoding
text and max_line_length is set to @code{0} or @code{None} (unlimited).

@item 
gh-133789@footnote{https://github.com/python/cpython/issues/133789}: Fix unpickling of @ref{a8,,pathlib} objects that were pickled in
Python 3.13.

@item 
gh-133601@footnote{https://github.com/python/cpython/issues/133601}: Remove deprecated @code{typing.no_type_check_decorator()}.

@item 
gh-132686@footnote{https://github.com/python/cpython/issues/132686}: Add parameters `inherit_class_doc' and `fallback_to_class_doc'
for @ref{22c,,inspect.getdoc()}.

@item 
gh-131116@footnote{https://github.com/python/cpython/issues/131116}: @ref{22c,,inspect.getdoc()} now correctly returns an inherited
docstring on @ref{94e,,cached_property} objects if none is given
in a subclass.

@item 
gh-130693@footnote{https://github.com/python/cpython/issues/130693}: Add support for @code{-nolinestop}, and @code{-strictlimits} options
to @code{tkinter.Text.search()}. Also add the
@code{tkinter.Text.search_all()} method for @code{-all} and @code{-overlap}
options.

@item 
gh-122255@footnote{https://github.com/python/cpython/issues/122255}: In the @ref{88,,linecache} module and in the Python implementation
of the @ref{11b,,warnings} module, a @code{DeprecationWarning} is issued when
@code{mod.__loader__} differs from @code{mod.__spec__.loader} (like in the C
implementation of the @code{warnings} module).

@item 
gh-121011@footnote{https://github.com/python/cpython/issues/121011}: @ref{1862,,math.log()} now supports arbitrary large integer-like
arguments in the same way as arbitrary large integer arguments.

@item 
gh-119668@footnote{https://github.com/python/cpython/issues/119668}: Publicly expose and document
@ref{19d1,,importlib.machinery.NamespacePath}.

@item 
gh-102431@footnote{https://github.com/python/cpython/issues/102431}: Clarify constraints for «logical» arguments in methods of
@ref{145c,,decimal.Context}.

@item 
gh-81313@footnote{https://github.com/python/cpython/issues/81313}: Add the @ref{92,,math.integer} module (
@geindex Python Enhancement Proposals; PEP 791
PEP 791@footnote{https://peps.python.org/pep-0791/}).
@end itemize

@node Core and Builtins<9>,Library<10>,Library<9>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id56}@anchor{19d2}
@subsubsection Core and Builtins



@itemize -

@item 
gh-141579@footnote{https://github.com/python/cpython/issues/141579}: Fix @ref{885,,sys.activate_stack_trampoline()} to properly support
the @code{perf_jit} backend. Patch by Pablo Galindo.

@item 
gh-114203@footnote{https://github.com/python/cpython/issues/114203}: Skip locking if object is already locked by two-mutex critical
section.

@item 
gh-141528@footnote{https://github.com/python/cpython/issues/141528}: Suggest using @ref{19d3,,concurrent.interpreters.Interpreter.close()}
instead of the private @code{_interpreters.destroy} function when warning
about remaining subinterpreters. Patch by Sergey Miryanov.

@item 
gh-141367@footnote{https://github.com/python/cpython/issues/141367}: Specialize @code{CALL_LIST_APPEND} instruction only for lists, not
for list subclasses, to avoid unnecessary deopt. Patch by Mikhail Efimov.

@item 
gh-141312@footnote{https://github.com/python/cpython/issues/141312}: Fix the assertion failure in the @code{__setstate__} method of the
range iterator when a non-integer argument is passed. Patch by Sergey
Miryanov.

@item 
gh-140643@footnote{https://github.com/python/cpython/issues/140643}: Add support for @code{<GC>} and @code{<native>} frames to
@code{profiling.sampling} output to denote active garbage collection and
calls to native code.
@end itemize

@node Library<10>,Core and Builtins<10>,Core and Builtins<9>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id57}@anchor{19d4}
@subsubsection Library



@itemize -

@item 
gh-140942@footnote{https://github.com/python/cpython/issues/140942}: Add @code{.cjs} to @ref{93,,mimetypes} to give CommonJS modules a
MIME type of @code{application/node}.
@end itemize

@node Core and Builtins<10>,Library<11>,Library<10>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id58}@anchor{19d5}
@subsubsection Core and Builtins



@itemize -

@item 
gh-140479@footnote{https://github.com/python/cpython/issues/140479}: Update JIT compilation to use LLVM 21 at build time.

@item 
gh-140939@footnote{https://github.com/python/cpython/issues/140939}: Fix memory leak when @ref{1c6,,bytearray} or @ref{1c7,,bytes} is
formated with the @code{%*b} format with a large width that results in a
@ref{18fa,,MemoryError}.
@end itemize

@node Library<11>,Core and Builtins<11>,Core and Builtins<10>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id59}@anchor{19d6}
@subsubsection Library



@itemize -

@item 
gh-140260@footnote{https://github.com/python/cpython/issues/140260}: Fix @ref{de,,struct} data race in endian table initialization with
subinterpreters. Patch by Shamil Abdulaev.
@end itemize

@node Core and Builtins<11>,Library<12>,Library<11>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id60}@anchor{19d7}
@subsubsection Core and Builtins



@itemize -

@item 
gh-140530@footnote{https://github.com/python/cpython/issues/140530}: Fix a reference leak when @code{raise exc from cause} fails. Patch
by Bénédikt Tran.
@end itemize

@node Library<12>,Core and Builtins<12>,Core and Builtins<11>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id61}@anchor{19d8}
@subsubsection Library



@itemize -

@item 
gh-90344@footnote{https://github.com/python/cpython/issues/90344}: Replace @ref{1947,,io.IncrementalNewlineDecoder} with non
incremental newline decoders in codebase where
@code{io.IncrementalNewlineDecoder.decode()} was being called once.
@end itemize

@node Core and Builtins<12>,Library<13>,Library<12>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id62}@anchor{19d9}
@subsubsection Core and Builtins



@itemize -

@item 
gh-140373@footnote{https://github.com/python/cpython/issues/140373}: Correctly emit @code{PY_UNWIND} event when generator object is
closed. Patch by Mikhail Efimov.

@item 
gh-140729@footnote{https://github.com/python/cpython/issues/140729}: Fix pickling error in the sampling profiler when using
@code{concurrent.futures.ProcessPoolExecutor} script can not be properly
pickled and executed in worker processes.

@item 
gh-131527@footnote{https://github.com/python/cpython/issues/131527}: Dynamic borrow checking for stackrefs is added to
@code{Py_STACKREF_DEBUG} mode. Patch by Mikhail Efimov.

@item 
gh-140576@footnote{https://github.com/python/cpython/issues/140576}: Fixed crash in @ref{8ea,,tokenize.generate_tokens()} in case of
specific incorrect input. Patch by Mikhail Efimov.

@item 
gh-140544@footnote{https://github.com/python/cpython/issues/140544}: Speed up accessing interpreter state by caching it in a thread
local variable. Patch by Kumar Aditya.

@item 
gh-140551@footnote{https://github.com/python/cpython/issues/140551}: Fixed crash in @ref{188,,dict} if @ref{1954,,dict.clear()} is called at
the lookup stage. Patch by Mikhail Efimov and Inada Naoki.

@item 
gh-140517@footnote{https://github.com/python/cpython/issues/140517}: Fixed a reference leak when iterating over the result of
@ref{43e,,map()} with @code{strict=True} when the input iterables have different
lengths. Patch by Mikhail Efimov.

@item 
gh-133467@footnote{https://github.com/python/cpython/issues/133467}: Fix race when updating @code{type.__bases__} that could allow
a read of @code{type.__base__} to observe an inconsistent value on the
free threaded build.

@item 
gh-140471@footnote{https://github.com/python/cpython/issues/140471}: Fix potential buffer overflow in @ref{2ec,,ast.AST} node
initialization when encountering malformed @ref{19da,,_fields}
containing non-@ref{1df,,str}.
@end itemize

@node Library<13>,Core and Builtins<13>,Core and Builtins<12>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id63}@anchor{19db}
@subsubsection Library



@itemize -

@item 
gh-140443@footnote{https://github.com/python/cpython/issues/140443}: The logarithm functions (such as @ref{19dc,,math.log10()} and
@ref{1862,,math.log()}) may now produce slightly different results for extremely
large integers that cannot be converted to floats without overflow. These
results are generally more accurate, with reduced worst-case error and a
tighter overall error distribution.
@end itemize

@node Core and Builtins<13>,Library<14>,Library<13>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id64}@anchor{19dd}
@subsubsection Core and Builtins



@itemize -

@item 
gh-140431@footnote{https://github.com/python/cpython/issues/140431}: Fix a crash in Python’s @ref{19de,,garbage collector} due to partially initialized @ref{8a2,,coroutine} objects when
coroutine origin tracking depth is enabled
(@ref{f4b,,sys.set_coroutine_origin_tracking_depth()}).

@item 
gh-140476@footnote{https://github.com/python/cpython/issues/140476}: Optimize @ref{17e8,,PySet_Add()} for @ref{9d4,,frozenset} in
@ref{487,,free threaded} build.

@item 
gh-135904@footnote{https://github.com/python/cpython/issues/135904}: Add special labels to the assembly created during stencil
creation to support relocations that the native object file format does
not support. Specifically, 19 bit branches for AArch64 in Mach-O object
files.
@end itemize

@node Library<14>,Core and Builtins<14>,Core and Builtins<13>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id65}@anchor{19df}
@subsubsection Library



@itemize -

@item 
gh-140398@footnote{https://github.com/python/cpython/issues/140398}: Fix memory leaks in @ref{c2,,readline} functions
@ref{19e0,,read_init_file()}, @ref{19e1,,read_history_file()},
@ref{19e2,,write_history_file()}, and
@ref{1202,,append_history_file()} when @ref{808,,PySys_Audit()} fails.
@end itemize

@node Core and Builtins<14>,C API<7>,Library<14>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id66}@anchor{19e3}
@subsubsection Core and Builtins



@itemize -

@item 
gh-140406@footnote{https://github.com/python/cpython/issues/140406}: Fix memory leak when an object’s @ref{ec1,,__hash__()}
method returns an object that isn’t an @ref{326,,int}.

@item 
gh-140358@footnote{https://github.com/python/cpython/issues/140358}: Restore elapsed time and unreachable object count in GC debug
output. These were inadvertently removed during a refactor of @code{gc.c}.
The debug log now again reports elapsed collection time and the number of
unreachable objects. Contributed by Pål Grønås Drange.

@item 
gh-136895@footnote{https://github.com/python/cpython/issues/136895}: Update JIT compilation to use LLVM 20 at build time.

@item 
gh-139109@footnote{https://github.com/python/cpython/issues/139109}: A new tracing frontend for the JIT compiler has been
implemented. Patch by Ken Jin. Design for CPython by Ken Jin, Mark Shannon
and Brandt Bucher.

@item 
gh-140306@footnote{https://github.com/python/cpython/issues/140306}: Fix memory leaks in cross-interpreter channel operations and
shared namespace handling.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make _suggestions module thread-safe on the @ref{487,,free threaded} build.

@item 
gh-140301@footnote{https://github.com/python/cpython/issues/140301}: Fix memory leak of @code{PyConfig} in subinterpreters.

@item 
gh-140257@footnote{https://github.com/python/cpython/issues/140257}: Fix data race between interpreter_clear() and take_gil() on
eval_breaker during finalization with daemon threads.

@item 
gh-139951@footnote{https://github.com/python/cpython/issues/139951}: Fixes a regression in GC performance for a growing heap
composed mostly of small tuples.


@itemize *

@item 
Counts number of actually tracked objects, instead of trackable objects.
This ensures that untracking tuples has the desired effect of reducing GC overhead.

@item 
Does not track most untrackable tuples during creation.
This prevents large numbers of small tuples causing excessive GCs.
@end itemize

@item 
gh-140253@footnote{https://github.com/python/cpython/issues/140253}: Wrong placement of a double-star pattern inside a mapping
pattern now throws a specialized syntax error. Contributed by Bartosz
Sławecki in gh-140253@footnote{https://github.com/python/cpython/issues/140253}.

@item 
gh-140104@footnote{https://github.com/python/cpython/issues/140104}: Fix a bug with exception handling in the JIT. Patch by Ken Jin.
Bug reported by Daniel Diniz.

@item 
gh-140149@footnote{https://github.com/python/cpython/issues/140149}: Speed up parsing bytes literals concatenation by using
PyBytesWriter API and a single memory allocation (about 3x faster).

@item 
gh-140061@footnote{https://github.com/python/cpython/issues/140061}: Fixing the checking of whether an object is uniquely referenced
to ensure free-threaded compatibility. Patch by Sergey Miryanov.

@item 
gh-140080@footnote{https://github.com/python/cpython/issues/140080}: Fix hang during finalization when attempting to call
@ref{d,,atexit} handlers under no memory.

@item 
gh-139871@footnote{https://github.com/python/cpython/issues/139871}: Update @ref{1c6,,bytearray} to use a @ref{1c7,,bytes} under the
hood as its buffer and add @ref{1c5,,bytearray.take_bytes()} to take it out.

@item 
gh-140067@footnote{https://github.com/python/cpython/issues/140067}: Fix memory leak in sub-interpreter creation.

@item 
gh-139914@footnote{https://github.com/python/cpython/issues/139914}: Restore support for HP PA-RISC, which has an upwards-growing
stack.

@item 
gh-139817@footnote{https://github.com/python/cpython/issues/139817}: Attribute @code{__qualname__} is added to
@ref{52a,,typing.TypeAliasType}. Patch by Mikhail Efimov.

@item 
gh-135801@footnote{https://github.com/python/cpython/issues/135801}: Many functions related to compiling or parsing Python code,
such as @ref{1c8,,compile()}, @ref{1c9,,ast.parse()}, @ref{1ca,,symtable.symtable()}, and
@ref{1cb,,importlib.abc.InspectLoader.source_to_code()} now allow to specify
the module name. It is needed to unambiguous @ref{1cc,,filter} syntax warnings by module name.

@item 
gh-139640@footnote{https://github.com/python/cpython/issues/139640}: @ref{1c9,,ast.parse()} no longer emits syntax warnings for
@code{return}/@code{break}/@code{continue} in @code{finally} (see 
@geindex Python Enhancement Proposals; PEP 765
PEP 765@footnote{https://peps.python.org/pep-0765/}) – they
are only emitted during compilation.

@item 
gh-139640@footnote{https://github.com/python/cpython/issues/139640}: Fix swallowing some syntax warnings in different modules if
they accidentally have the same message and are emitted from the same
line. Fix duplicated warnings in the @code{finally} block.

@item 
gh-139475@footnote{https://github.com/python/cpython/issues/139475}: Changes in stackref debugging mode when @code{Py_STACKREF_DEBUG}
is set. We use the same pattern of refcounting for stackrefs as in
production build.

@item 
gh-139269@footnote{https://github.com/python/cpython/issues/139269}: Fix undefined behavior when using unaligned store in JIT’s
@code{patch_*} functions.

@item 
gh-138944@footnote{https://github.com/python/cpython/issues/138944}: Fix @ref{17e,,SyntaxError} message when invalid syntax appears on
the same line as a valid @code{import ... as ...} or @code{from ... import ... as
...} statement. Patch by Brian Schubert.

@item 
gh-138857@footnote{https://github.com/python/cpython/issues/138857}: Improve @ref{17e,,SyntaxError} message for @code{case} keyword placed
outside @ref{1d4,,match} body.

@item 
gh-131253@footnote{https://github.com/python/cpython/issues/131253}: Support the @code{--enable-pystats} build option for the
free-threaded build.

@item 
gh-136327@footnote{https://github.com/python/cpython/issues/136327}: Errors when calling functions with invalid values after @code{*}
and @code{**} now do not include the function name. Patch by Ilia Solin.

@item 
gh-134786@footnote{https://github.com/python/cpython/issues/134786}: If @ref{39c,,Py_TPFLAGS_MANAGED_DICT} and
@ref{39d,,Py_TPFLAGS_MANAGED_WEAKREF} are used, then
@ref{39e,,Py_TPFLAGS_HAVE_GC} must be used as well.
@end itemize

@node C API<7>,Build<6>,Core and Builtins<14>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id67}@anchor{19e4}
@subsubsection C API



@itemize -

@item 
gh-141341@footnote{https://github.com/python/cpython/issues/141341}: On Windows, rename the @code{COMPILER} macro to @code{_Py_COMPILER}
to avoid name conflicts. Patch by Victor Stinner.

@item 
gh-116146@footnote{https://github.com/python/cpython/issues/116146}: Add a new @ref{369,,PyImport_CreateModuleFromInitfunc()} C-API for
creating a module from a `spec' and `initfunc'. Patch by Itamar Oren.

@item 
gh-141042@footnote{https://github.com/python/cpython/issues/141042}: Make qNaN in @ref{b47,,PyFloat_Pack2()} and
@ref{b48,,PyFloat_Pack4()}, if while conversion to a narrower precision
floating-point format — the remaining after truncation payload will be
zero.  Patch by Sergey B Kirpichev.

@item 
gh-141004@footnote{https://github.com/python/cpython/issues/141004}: @code{Py_MATH_El} and @code{Py_MATH_PIl} are
deprecated.

@item 
gh-141004@footnote{https://github.com/python/cpython/issues/141004}: The @code{Py_INFINITY} macro is @ref{1a7,,soft deprecated}.

@item 
gh-140556@footnote{https://github.com/python/cpython/issues/140556}: 
@geindex Python Enhancement Proposals; PEP 793
PEP 793@footnote{https://peps.python.org/pep-0793/}: Add a new entry point for C extension modules,
@code{PyModExport_<modulename>}.

@item 
gh-140487@footnote{https://github.com/python/cpython/issues/140487}: Fix @ref{19e5,,Py_RETURN_NOTIMPLEMENTED} in limited C API 3.11
and older: don’t treat @code{Py_NotImplemented} as immortal. Patch by Victor
Stinner.

@item 
gh-140153@footnote{https://github.com/python/cpython/issues/140153}: Fix @ref{54b,,Py_REFCNT()} definition on limited C API 3.11-3.13.
Patch by Victor Stinner.

@item 
gh-139653@footnote{https://github.com/python/cpython/issues/139653}: Add @ref{395,,PyUnstable_ThreadState_SetStackProtection()} and
@ref{396,,PyUnstable_ThreadState_ResetStackProtection()} functions to set the
stack protection base address and stack protection size of a Python thread
state. Patch by Victor Stinner.
@end itemize

@node Build<6>,,C API<7>,Python 3 15 0 alpha 2
@anchor{whatsnew/changelog id68}@anchor{19e6}
@subsubsection Build



@itemize -

@item 
gh-140454@footnote{https://github.com/python/cpython/issues/140454}: When building the JIT, match the jit_stencils filename
expectations in Makefile with the generator script. This avoid needless
JIT recompilation during @code{make install}.

@item 
gh-140768@footnote{https://github.com/python/cpython/issues/140768}: Warn when the WASI SDK version doesn’t match what’s supported.

@item 
gh-140513@footnote{https://github.com/python/cpython/issues/140513}: Generate a clear compilation error when
@code{_Py_TAIL_CALL_INTERP} is enabled but either @code{preserve_none} or
@code{musttail} is not supported.

@item 
gh-140475@footnote{https://github.com/python/cpython/issues/140475}: Support WASI SDK 25.

@item 
gh-140239@footnote{https://github.com/python/cpython/issues/140239}: Check @code{statx} availability only on Linux (including Android).

@item 
gh-140189@footnote{https://github.com/python/cpython/issues/140189}: iOS builds were added to CI.

@item 
gh-137618@footnote{https://github.com/python/cpython/issues/137618}: @code{PYTHON_FOR_REGEN} now requires Python 3.10 to Python 3.15.
Patch by Adam Turner.
@end itemize

@node Python 3 15 0 alpha 1,Python 3 14 0 beta 1,Python 3 15 0 alpha 2,Changelog
@anchor{whatsnew/changelog python-3-15-0-alpha-1}@anchor{19e7}
@subsection Python 3.15.0 alpha 1


`Release date: 2025-10-14'

@menu
* macOS: macOS<4>. 
* Windows: Windows<7>. 
* Tools/Demos: Tools/Demos<5>. 
* Tests: Tests<9>. 
* Security: Security<8>. 
* Library: Library<15>. 
* IDLE: IDLE<5>. 
* Documentation: Documentation<7>. 
* Core and Builtins: Core and Builtins<15>. 
* Library: Library<16>. 
* Core and Builtins: Core and Builtins<16>. 
* Library: Library<17>. 
* Core and Builtins: Core and Builtins<17>. 
* Library: Library<18>. 
* Core and Builtins: Core and Builtins<18>. 
* Library: Library<19>. 
* Core and Builtins: Core and Builtins<19>. 
* Library: Library<20>. 
* Core and Builtins: Core and Builtins<20>. 
* Library: Library<21>. 
* Core and Builtins: Core and Builtins<21>. 
* Library: Library<22>. 
* Core and Builtins: Core and Builtins<22>. 
* Library: Library<23>. 
* Core and Builtins: Core and Builtins<23>. 
* Library: Library<24>. 
* Core and Builtins: Core and Builtins<24>. 
* Library: Library<25>. 
* Core and Builtins: Core and Builtins<25>. 
* Library: Library<26>. 
* Core and Builtins: Core and Builtins<26>. 
* Library: Library<27>. 
* Core and Builtins: Core and Builtins<27>. 
* Library: Library<28>. 
* Core and Builtins: Core and Builtins<28>. 
* C API: C API<8>. 
* Build: Build<7>. 

@end menu

@node macOS<4>,Windows<7>,,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id69}@anchor{19e8}
@subsubsection macOS



@itemize -

@item 
gh-115119@footnote{https://github.com/python/cpython/issues/115119}: Update macOS installer to use libmpdecimal 4.0.1.

@item 
gh-124111@footnote{https://github.com/python/cpython/issues/124111}: Update macOS installer to use Tcl/Tk 9.0.2.

@item 
gh-132339@footnote{https://github.com/python/cpython/issues/132339}: Update macOS installer version of OpenSSL to 3.5.4.

@item 
gh-137450@footnote{https://github.com/python/cpython/issues/137450}: macOS installer shell path management improvements: separate
the installer @code{Shell profile updater} postinstall script from the
@code{Update Shell Profile.command} to enable more robust error handling.

@item 
gh-137134@footnote{https://github.com/python/cpython/issues/137134}: Update macOS installer to ship with SQLite version 3.50.4.
@end itemize

@node Windows<7>,Tools/Demos<5>,macOS<4>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id70}@anchor{19e9}
@subsubsection Windows



@itemize -

@item 
gh-139810@footnote{https://github.com/python/cpython/issues/139810}: Installing with @code{py install 3[.x]-dev} will now select final
versions as well as prereleases.

@item 
gh-139573@footnote{https://github.com/python/cpython/issues/139573}: Updated bundled version of OpenSSL to 3.0.18.

@item 
gh-138896@footnote{https://github.com/python/cpython/issues/138896}: Fix error installing C runtime on non-updated Windows machines

@item 
gh-138314@footnote{https://github.com/python/cpython/issues/138314}: Add @ref{19ea,,winreg.DeleteTree()}.

@item 
gh-137136@footnote{https://github.com/python/cpython/issues/137136}: Suppress build warnings when build on Windows with
@code{--experimental-jit-interpreter}.

@item 
gh-137134@footnote{https://github.com/python/cpython/issues/137134}: Update Windows installer to ship with SQLite 3.50.4.

@item 
gh-135099@footnote{https://github.com/python/cpython/issues/135099}: Fix a crash that could occur on Windows when a background
thread waits on a @ref{693,,PyMutex} while the main thread is shutting down
the interpreter.

@item 
gh-130727@footnote{https://github.com/python/cpython/issues/130727}: Fix a race in internal calls into WMI that can result in an
«invalid handle» exception under high load. Patch by Chris Eibl.

@item 
gh-76023@footnote{https://github.com/python/cpython/issues/76023}: Make @ref{241,,os.path.realpath()} ignore Windows error 1005 when in
non-strict mode.

@item 
gh-133779@footnote{https://github.com/python/cpython/issues/133779}: Reverts the change to generate different @code{pyconfig.h}
files based on compiler settings, as it was frequently causing extension
builds to break. In particular, the @code{Py_GIL_DISABLED} preprocessor
variable must now always be defined explicitly when compiling for the
experimental free-threaded runtime. The @ref{41e,,sysconfig.get_config_var()}
function can be used to determine whether the current runtime was compiled
with that flag or not.

@item 
gh-133626@footnote{https://github.com/python/cpython/issues/133626}: Ensures packages are not accidentally bundled into the
traditional installer.

@item 
gh-133580@footnote{https://github.com/python/cpython/issues/133580}: Fix @ref{10a4,,sys.getwindowsversion()} failing without setting an
exception when called on some WinAPI partitions.

@item 
gh-133572@footnote{https://github.com/python/cpython/issues/133572}: Avoid LsaNtStatus to WinError conversion on unsupported WinAPI
partitions.

@item 
gh-133568@footnote{https://github.com/python/cpython/issues/133568}: Fix compile error when using a WinAPI partition that doesn’t
support the RPC runtime library.

@item 
gh-133562@footnote{https://github.com/python/cpython/issues/133562}: Disable handling of security descriptors by @ref{72e,,os.mkdir()}
with mode @code{0o700} on WinAPI partitions that do not support it. This only
affects custom builds for specialized targets.

@item 
gh-133537@footnote{https://github.com/python/cpython/issues/133537}: Avoid using console I/O in WinAPI partitions that don’t support
it

@item 
gh-131942@footnote{https://github.com/python/cpython/issues/131942}: Use the Python-specific @ref{19eb,,Py_DEBUG} macro rather than
@code{_DEBUG} in Windows-related C code. Patch by Xuehai Pan.
@end itemize

@node Tools/Demos<5>,Tests<9>,Windows<7>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id71}@anchor{19ec}
@subsubsection Tools/Demos



@itemize -

@item 
gh-139330@footnote{https://github.com/python/cpython/issues/139330}: SBOM generation tool didn’t cross-check the version and
checksum values against the @code{Modules/expat/refresh.sh} script, leading
to the values becoming out-of-date during routine updates.

@item 
gh-132006@footnote{https://github.com/python/cpython/issues/132006}: XCframeworks now include privacy manifests to satisfy Apple App
Store submission requirements.

@item 
gh-138171@footnote{https://github.com/python/cpython/issues/138171}: A script for building an iOS XCframework was added. As part of
this change, the top level @code{iOS} folder has been moved to be a
subdirectory of the @code{Apple} folder.

@item 
gh-137873@footnote{https://github.com/python/cpython/issues/137873}: The iOS test runner has been simplified, resolving some issues
that have been observed using the runner in GitHub Actions and Azure
Pipelines test environments.

@item 
gh-137484@footnote{https://github.com/python/cpython/issues/137484}: Have @code{Tools/wasm/wasi} put the build Python into a directory
named after the build triple instead of «build».

@item 
gh-137025@footnote{https://github.com/python/cpython/issues/137025}: The @code{wasm_build.py} script has been removed.
@code{Tools/wasm/emscripten} and @code{Tools/wasm/wasi} should be used instead,
as described in the Dev Guide@footnote{https://devguide.python.org/contrib/workflows/compile/}.

@item 
gh-137248@footnote{https://github.com/python/cpython/issues/137248}: Add a @code{--logdir} option to @code{Tools/wasm/wasi} for specifying
where to write log files.

@item 
gh-137243@footnote{https://github.com/python/cpython/issues/137243}: Have Tools/wasm/wasi detect a WASI SDK install in /opt when it
was directly extracted from a release tarball.

@item 
gh-136251@footnote{https://github.com/python/cpython/issues/136251}: Fixes and usability improvements for
@code{Tools/wasm/emscripten/web_example}

@item 
gh-135968@footnote{https://github.com/python/cpython/issues/135968}: Stubs for @code{strip} are now provided as part of an iOS install.

@item 
gh-135379@footnote{https://github.com/python/cpython/issues/135379}: The cases generator no longer accepts type annotations on stack
items. Conversions to non-default types are now done explicitly in
bytecodes.c and optimizer_bytecodes.c. This will simplify code generation
for top-of-stack caching and other future features.

@item 
gh-134215@footnote{https://github.com/python/cpython/issues/134215}: @ref{69d,,REPL} import autocomplete only suggests private modules
when explicitly specified.
@end itemize

@node Tests<9>,Security<8>,Tools/Demos<5>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id72}@anchor{19ed}
@subsubsection Tests



@itemize -

@item 
gh-139208@footnote{https://github.com/python/cpython/issues/139208}: Fix regrtest @code{--fast-ci --verbose}: don’t ignore the
@code{--verbose} option anymore. Patch by Victor Stinner.

@item 
gh-138313@footnote{https://github.com/python/cpython/issues/138313}: Restore skipped test and add janky workaround to prevent select
buildbots from failing with a ResourceWarning.

@item 
gh-135966@footnote{https://github.com/python/cpython/issues/135966}: The iOS testbed now handles the @code{app_packages} folder as a
site directory.

@item 
gh-135494@footnote{https://github.com/python/cpython/issues/135494}: Fix regrtest to support excluding tests from @code{--pgo} tests.
Patch by Victor Stinner.

@item 
gh-132815@footnote{https://github.com/python/cpython/issues/132815}: Fix test__opcode: add @code{JUMP_BACKWARD} to specialization
stats.

@item 
gh-135489@footnote{https://github.com/python/cpython/issues/135489}: Show verbose output for failing tests during PGO profiling step
with –enable-optimizations.

@item 
gh-135401@footnote{https://github.com/python/cpython/issues/135401}: Add a new GitHub CI job to test the @ref{d8,,ssl} module with
AWS-LC@footnote{https://github.com/aws/aws-lc} as the backing cryptography and
TLS library.

@item 
gh-135120@footnote{https://github.com/python/cpython/issues/135120}: Add @code{test.support.subTests()}.

@item 
gh-134567@footnote{https://github.com/python/cpython/issues/134567}: Expose log formatter to users in TestCase.assertLogs.
@ref{29f,,unittest.TestCase.assertLogs()} will now optionally accept a
formatter that will be used to format the strings in output if provided.

@item 
gh-133744@footnote{https://github.com/python/cpython/issues/133744}: Fix multiprocessing interrupt test. Add an event to synchronize
the parent process with the child process: wait until the child process
starts sleeping. Patch by Victor Stinner.

@item 
gh-133682@footnote{https://github.com/python/cpython/issues/133682}: Fixed test case
@code{test.test_annotationlib.TestStringFormat.test_displays} which ensures
proper handling of complex data structures (lists, sets, dictionaries, and
tuples) in string annotations.

@item 
gh-133639@footnote{https://github.com/python/cpython/issues/133639}: Fix @code{TestPyReplAutoindent.test_auto_indent_default()} doesn’t
run @code{input_code}.
@end itemize

@node Security<8>,Library<15>,Tests<9>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id73}@anchor{19ee}
@subsubsection Security



@itemize -

@item 
gh-139700@footnote{https://github.com/python/cpython/issues/139700}: Check consistency of the zip64 end of central directory record.
Support records with «zip64 extensible data» if there are no bytes
prepended to the ZIP file.

@item 
gh-139400@footnote{https://github.com/python/cpython/issues/139400}: @ref{12f,,xml.parsers.expat}: Make sure that parent Expat parsers
are only garbage-collected once they are no longer referenced by
subparsers created by
@ref{1931,,ExternalEntityParserCreate()}. Patch by
Sebastian Pipping.

@item 
gh-139283@footnote{https://github.com/python/cpython/issues/139283}: @ref{d7,,sqlite3}: correctly handle maximum number of rows to
fetch in @ref{19ef,,Cursor.fetchmany} and reject
negative values for @ref{19f0,,Cursor.arraysize}.
Patch by Bénédikt Tran.

@item 
gh-136053@footnote{https://github.com/python/cpython/issues/136053}: @ref{90,,marshal}: fix a possible crash when deserializing
@ref{1d0,,slice} objects.

@item 
gh-135661@footnote{https://github.com/python/cpython/issues/135661}: Fix parsing start and end tags in
@ref{c4d,,html.parser.HTMLParser} according to the HTML5 standard.


@itemize *

@item 
Whitespaces no longer accepted between @code{</} and the tag name.
E.g. @code{</ script>} does not end the script section.

@item 
Vertical tabulation (@code{\v}) and non-ASCII whitespaces no longer recognized
as whitespaces. The only whitespaces are @code{\t\n\r\f} and space.

@item 
Null character (U+0000) no longer ends the tag name.

@item 
Attributes and slashes after the tag name in end tags are now ignored,
instead of terminating after the first @code{>} in quoted attribute value.
E.g. @code{</script/foo=">"/>}.

@item 
Multiple slashes and whitespaces between the last attribute and closing @code{>}
are now ignored in both start and end tags. E.g. @code{<a foo=bar/ //>}.

@item 
Multiple @code{=} between attribute name and value are no longer collapsed.
E.g. @code{<a foo==bar>} produces attribute «foo» with value «=bar».
@end itemize

@item 
gh-135661@footnote{https://github.com/python/cpython/issues/135661}: Fix CDATA section parsing in @ref{c4d,,html.parser.HTMLParser}
according to the HTML5 standard: @code{] ]>} and @code{]] >} no longer end the
CDATA section. Add private method @code{_set_support_cdata()} which can be
used to specify how to parse @code{<[CDATA[} — as a CDATA section in
foreign content (SVG or MathML) or as a bogus comment in the HTML
namespace.

@item 
gh-102555@footnote{https://github.com/python/cpython/issues/102555}: Fix comment parsing in @ref{c4d,,html.parser.HTMLParser}
according to the HTML5 standard. @code{--!>} now ends the comment. @code{-- >}
no longer ends the comment. Support abnormally ended empty comments
@code{<-->} and @code{<--->}.

@item 
gh-135462@footnote{https://github.com/python/cpython/issues/135462}: Fix quadratic complexity in processing specially crafted input
in @ref{c4d,,html.parser.HTMLParser}. End-of-file errors are now handled
according to the HTML5 specs – comments and declarations are
automatically closed, tags are ignored.

@item 
gh-118350@footnote{https://github.com/python/cpython/issues/118350}: Fix support of escapable raw text mode (elements «textarea» and
«title») in @ref{c4d,,html.parser.HTMLParser}.

@item 
gh-135034@footnote{https://github.com/python/cpython/issues/135034}: Fixes multiple issues that allowed @code{tarfile} extraction
filters (@code{filter="data"} and @code{filter="tar"}) to be bypassed using
crafted symlinks and hard links.

Addresses 
@geindex Common Vulnerabilities and Exposures; CVE 2024-12718
CVE 2024-12718@footnote{https://www.cve.org/CVERecord?id=CVE-2024-12718}, 
@geindex Common Vulnerabilities and Exposures; CVE 2025-4138
CVE 2025-4138@footnote{https://www.cve.org/CVERecord?id=CVE-2025-4138}, 
@geindex Common Vulnerabilities and Exposures; CVE 2025-4330
CVE 2025-4330@footnote{https://www.cve.org/CVERecord?id=CVE-2025-4330}, and
@geindex Common Vulnerabilities and Exposures; CVE 2025-4517
CVE 2025-4517@footnote{https://www.cve.org/CVERecord?id=CVE-2025-4517}.

@item 
gh-133767@footnote{https://github.com/python/cpython/issues/133767}: Fix use-after-free in the «unicode-escape» decoder with a
non-«strict» error handler.

@item 
gh-133623@footnote{https://github.com/python/cpython/issues/133623}: Indicate through @ref{259,,ssl.HAS_PSK_TLS13} whether the
@ref{d8,,ssl} module supports «External PSKs» in TLSv1.3, as described in RFC
9258. Patch by Will Childs-Klein.

@item 
gh-128840@footnote{https://github.com/python/cpython/issues/128840}: Short-circuit the processing of long IPv6 addresses early in
@ref{83,,ipaddress} to prevent excessive memory consumption and a minor
denial-of-service.
@end itemize

@node Library<15>,IDLE<5>,Security<8>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id74}@anchor{19f1}
@subsubsection Library



@itemize -

@item 
gh-139482@footnote{https://github.com/python/cpython/issues/139482}: Optimize @ref{4e5,,os.environ.clear()} by calling
@code{clearenv(3)@footnote{https://manpages.debian.org/clearenv(3)}} when this function is available. Patch by Victor
Stinner.

@item 
gh-139958@footnote{https://github.com/python/cpython/issues/139958}: The @code{application/toml} mime type is now supported by
@ref{93,,mimetypes}. Patch by Gil Forcada.

@item 
gh-139823@footnote{https://github.com/python/cpython/issues/139823}: @ref{58,,ensurepip} now fails with a nicer error message when the
@ref{13c,,zlib} module is not available.

@item 
gh-139905@footnote{https://github.com/python/cpython/issues/139905}: Add suggestion to error message for @ref{19f2,,typing.Generic}
subclasses when @code{cls.__parameters__} is missing due to a parent class
failing to call @ref{a22,,super().__init_subclass__()} in its @code{__init_subclass__}.

@item 
gh-139894@footnote{https://github.com/python/cpython/issues/139894}: Fix incorrect sharing of current task with the child process
while forking in @ref{b,,asyncio}. Patch by Kumar Aditya.

@item 
gh-139845@footnote{https://github.com/python/cpython/issues/139845}: Fix to not print KeyboardInterrupt twice in default asyncio
REPL.

@item 
gh-139783@footnote{https://github.com/python/cpython/issues/139783}: Fix @ref{19f3,,inspect.getsourcelines()} for the case when a
decorator is followed by a comment or an empty line.

@item 
gh-139809@footnote{https://github.com/python/cpython/issues/139809}: Prevent premature colorization of subparser @code{prog} in
@ref{fd6,,argparse.ArgumentParser.add_subparsers()} to respect color
environment variable changes after parser creation.

@item 
gh-139736@footnote{https://github.com/python/cpython/issues/139736}: Fix excessive indentation in the default @ref{7,,argparse}
@code{HelpFormatter}. Patch by Alexander Edland.

@item 
gh-70765@footnote{https://github.com/python/cpython/issues/70765}: @ref{75,,http.server}: fix default handling of HTTP/0.9 requests in
@ref{226,,BaseHTTPRequestHandler}. Previously,
@code{BaseHTTPRequestHandler.parse_request()} incorrectly waited for
headers in the request although those are not supported in HTTP/0.9. Patch
by Bénédikt Tran.

@item 
gh-139322@footnote{https://github.com/python/cpython/issues/139322}: Fix @ref{19f4,,os.getlogin()} error handling: fix the error number.
Patch by Victor Stinner.

@item 
gh-135953@footnote{https://github.com/python/cpython/issues/135953}: Add a Gecko format output to the tachyon profiler via
@code{--gecko}.

@item 
gh-139184@footnote{https://github.com/python/cpython/issues/139184}: @ref{6be,,os.forkpty()} does now make the returned file descriptor
non-inheritable.

@item 
gh-139391@footnote{https://github.com/python/cpython/issues/139391}: Fix an issue when, on non-Windows platforms, it was not
possible to gracefully exit a @code{python -m asyncio} process suspended by
Ctrl+Z and later resumed by @code{fg@footnote{https://manpages.debian.org/fg}} other than with @code{kill@footnote{https://manpages.debian.org/kill}}.

@item 
gh-139374@footnote{https://github.com/python/cpython/issues/139374}: @ref{f8,,timeit}: Add color to error tracebacks.

@item 
gh-90949@footnote{https://github.com/python/cpython/issues/90949}: Add
@ref{2b9,,SetBillionLaughsAttackProtectionActivationThreshold()}
and
@ref{2ba,,SetBillionLaughsAttackProtectionMaximumAmplification()}
to @ref{2b8,,xmlparser} objects to tune protections
against billion laughs@footnote{https://en.wikipedia.org/wiki/Billion_laughs_attack} attacks. Patch by
Bénédikt Tran.

@item 
gh-139312@footnote{https://github.com/python/cpython/issues/139312}: Upgrade bundled libexpat to 2.7.3

@item 
gh-139289@footnote{https://github.com/python/cpython/issues/139289}: Do a real lazy-import on @ref{c5,,rlcompleter} in @ref{aa,,pdb} and
restore the existing completer after importing @code{rlcompleter}.

@item 
gh-90949@footnote{https://github.com/python/cpython/issues/90949}: Add
@ref{2b6,,SetAllocTrackerActivationThreshold()}
and
@ref{2b7,,SetAllocTrackerMaximumAmplification()}
to @ref{2b8,,xmlparser} objects to tune protections
against disproportional amounts of dynamic memory usage from within an
Expat parser. Patch by Bénédikt Tran.

@item 
gh-67795@footnote{https://github.com/python/cpython/issues/67795}: Functions that take timestamp or timeout arguments now accept
any real numbers (such as @ref{1c2,,Decimal} and
@ref{1c3,,Fraction}), not only integers or floats, although this
does not improve precision.

@item 
gh-95953@footnote{https://github.com/python/cpython/issues/95953}: A CSS class, @code{diff_changed}, was added to the changed lines in
the @code{make_table} output of @ref{214,,difflib.HtmlDiff}. Patch by Katie
Gardner.

@item 
gh-139210@footnote{https://github.com/python/cpython/issues/139210}: Fix use-after-free when reporting unknown event in
@ref{3eb,,xml.etree.ElementTree.iterparse()}. Patch by Ken Jin.

@item 
gh-138860@footnote{https://github.com/python/cpython/issues/138860}: Lazy import @ref{c5,,rlcompleter} in @ref{aa,,pdb} to avoid deadlock
in subprocess.

@item 
gh-112729@footnote{https://github.com/python/cpython/issues/112729}: Fix crash when calling @ref{19f5,,concurrent.interpreters.create()}
when the process is out of memory.

@item 
gh-126016@footnote{https://github.com/python/cpython/issues/126016}: Fix an assertion failure when sending @ref{d96,,KeyboardInterrupt}
to a Python process running a subinterpreter in a separate thread.

@item 
gh-118803@footnote{https://github.com/python/cpython/issues/118803}: @ref{2cb,,collections.abc.ByteString} has been removed from
@code{collections.abc.__all__}, and @ref{2e3,,typing.ByteString} has been
removed from @code{typing.__all__}. The former has been deprecated since
Python 3.12, and the latter has been deprecated since Python 3.9. Both
classes are scheduled for removal in Python 3.17.

Additionally, the following statements now cause @code{DeprecationWarning}s
to be emitted at runtime: @code{from collections.abc import ByteString},
@code{from typing import ByteString}, @code{import collections.abc;
collections.abc.ByteString} and @code{import typing; typing.ByteString}.
Both classes already caused @code{DeprecationWarning}s to be emitted if
they were subclassed or used as the second argument to @code{isinstance()} or
@code{issubclass()}, but they did not previously lead to
@code{DeprecationWarning}s if they were merely imported or accessed from
their respective modules.

@item 
gh-135729@footnote{https://github.com/python/cpython/issues/135729}: Fix unraisable exception during finalization when using
@ref{25,,concurrent.interpreters} in the REPL.

@item 
gh-139076@footnote{https://github.com/python/cpython/issues/139076}: Fix a bug in the @ref{bd,,pydoc} module that was hiding functions
in a Python module if they were implemented in an extension module and the
module did not have @code{__all__}.

@item 
gh-139090@footnote{https://github.com/python/cpython/issues/139090}: Add @ref{19f6,,os.RWF_DONTCACHE} constant for Linux 6.14+.

@item 
gh-139065@footnote{https://github.com/python/cpython/issues/139065}: Fix trailing space before a wrapped long word if the line
length is exactly `width' in @ref{f5,,textwrap}.

@item 
gh-139001@footnote{https://github.com/python/cpython/issues/139001}: Fix race condition in @ref{4ee,,pathlib.Path} on the internal
@code{_raw_paths} field.

@item 
gh-138813@footnote{https://github.com/python/cpython/issues/138813}: @code{multiprocessing.BaseProcess} defaults @code{kwargs} to
@code{None} instead of a shared dictionary.

@item 
gh-138998@footnote{https://github.com/python/cpython/issues/138998}: Update bundled libexpat to 2.7.2

@item 
gh-138993@footnote{https://github.com/python/cpython/issues/138993}: Dedent @ref{1984,,credits} text.

@item 
gh-118803@footnote{https://github.com/python/cpython/issues/118803}: Add back @ref{2cb,,collections.abc.ByteString} and
@ref{2e3,,typing.ByteString}. Both had been removed in prior alpha, beta and
release candidates for Python 3.14, but their removal has now been
postponed to Python 3.17.

@item 
gh-130567@footnote{https://github.com/python/cpython/issues/130567}: Fix possible crash in @ref{19f7,,locale.strxfrm()} due to a platform
bug on macOS.

@item 
gh-137226@footnote{https://github.com/python/cpython/issues/137226}: Fix @ref{a9e,,typing.get_type_hints()} calls on generic
@ref{290,,typing.TypedDict} classes defined with string annotations.

@item 
gh-138899@footnote{https://github.com/python/cpython/issues/138899}: Executing @code{quit} command in @ref{aa,,pdb} will raise
@ref{500,,bdb.BdbQuit} when @code{pdb} is started from an asyncio console
using @ref{4f9,,breakpoint()} or @ref{4fa,,pdb.set_trace()}.

@item 
gh-138804@footnote{https://github.com/python/cpython/issues/138804}: Raise @ref{291,,TypeError} instead of @ref{1a9,,AttributeError} when an
argument of incorrect type is passed to @ref{781,,shlex.quote()}. This restores
the behavior of the function prior to 3.14.

@item 
gh-138779@footnote{https://github.com/python/cpython/issues/138779}: Support device numbers larger than @code{2**63-1} for the
@ref{19f8,,st_rdev} field of the @ref{1863,,os.stat_result}
structure.

@item 
gh-138682@footnote{https://github.com/python/cpython/issues/138682}: Added symmetric difference support to
@ref{204,,collections.Counter} objects.

@item 
gh-138712@footnote{https://github.com/python/cpython/issues/138712}: Add @ref{19f9,,os.NODEV}.

@item 
gh-128636@footnote{https://github.com/python/cpython/issues/128636}: Fix crash in PyREPL when os.environ is overwritten with an
invalid value for mac

@item 
gh-138720@footnote{https://github.com/python/cpython/issues/138720}: Fix an issue where @ref{1754,,io.BufferedWriter} and
@ref{1755,,io.BufferedRandom} had different definitions of «closed» for
@ref{70b,,close()} and @ref{19fa,,flush()} which resulted in an
exception when close called flush but flush thought the file was already
closed.

@item 
gh-138706@footnote{https://github.com/python/cpython/issues/138706}: Update @ref{10e,,unicodedata} database to Unicode 17.0.0.

@item 
gh-76007@footnote{https://github.com/python/cpython/issues/76007}: Deprecate @code{__version__} from a number of standard library
modules. Patch by Hugo van Kemenade.

@item 
gh-138535@footnote{https://github.com/python/cpython/issues/138535}: Speed up @ref{4f5,,os.stat()} for files with reasonable timestamps.
Contributed by Jeffrey Bosboom.

@item 
gh-116946@footnote{https://github.com/python/cpython/issues/116946}: @ref{30,,curses.panel}: the type of @ref{19fb,,curses.panel.new_panel()}
is now immutable. Patch by Bénédikt Tran.

@item 
gh-116946@footnote{https://github.com/python/cpython/issues/116946}: @ref{13c,,zlib}: the types of @ref{19fc,,zlib.compressobj()} and
@ref{19fd,,zlib.decompressobj()} are now immutable. Patch by Bénédikt Tran.

@item 
gh-116946@footnote{https://github.com/python/cpython/issues/116946}: @ref{a5,,os}: the @ref{8ac,,os.DirEntry} type and the type of
@ref{e23,,os.scandir()} are now immutable. Patch by Bénédikt Tran.

@item 
gh-116946@footnote{https://github.com/python/cpython/issues/116946}: @ref{f9,,tkinter}: the types @code{_tkinter.Tcl_Obj} (wrapper
for Tcl objects), @code{_tkinter.tktimertoken} (obtained by calling
@code{createtimerhandler()} on a @ref{19fe,,Tk} application) and
@code{_tkinter.tkapp} (the runtime type of Tk applications) are now
immutable. Patch by Bénédikt Tran.

@item 
gh-138514@footnote{https://github.com/python/cpython/issues/138514}: Raise @ref{277,,ValueError} when a multi-character string is passed
to the `echo_char' parameter of @ref{4ab,,getpass.getpass()}. Patch by Benjamin
Johnson.

@item 
gh-137706@footnote{https://github.com/python/cpython/issues/137706}: Fix the partial evaluation of annotations that use
@code{typing.Annotated[T, x]} where @code{T} is a forward reference.

@item 
gh-88375@footnote{https://github.com/python/cpython/issues/88375}: Fix normalization of the @code{robots.txt} rules and URLs in the
@ref{116,,urllib.robotparser} module. No longer ignore trailing @code{?}.
Distinguish raw special characters @code{?}, @code{=} and @code{&} from the
percent-encoded ones.

@item 
gh-138515@footnote{https://github.com/python/cpython/issues/138515}: @ref{3e,,email} is added to Emscripten build.

@item 
gh-99948@footnote{https://github.com/python/cpython/issues/99948}: @ref{10fe,,ctypes.util.find_library()} now works in Emscripten build.

@item 
gh-111788@footnote{https://github.com/python/cpython/issues/111788}: Fix parsing errors in the @ref{116,,urllib.robotparser} module.
Don’t fail trying to parse weird paths. Don’t fail trying to decode
non-UTF-8 @code{robots.txt} files.

@item 
gh-138432@footnote{https://github.com/python/cpython/issues/138432}: @ref{19ff,,zoneinfo.reset_tzpath()} will now convert any
@ref{100f,,os.PathLike} objects it receives into strings before adding them
to @code{TZPATH}. It will raise @code{TypeError} if anything other than a string
is found after this conversion. If given an @code{os.PathLike} object
that represents a relative path, it will now raise @code{ValueError} instead
of @code{TypeError}, and present a more informative error message.

@item 
gh-132657@footnote{https://github.com/python/cpython/issues/132657}: Improve the scaling of @ref{942,,copy.copy()} and
@ref{f2b,,copy.deepcopy()} in the free-threading build.

@item 
gh-116946@footnote{https://github.com/python/cpython/issues/116946}: The types of @ref{268,,select.poll()} and @ref{133d,,select.epoll()}
objects are now immutable. Patch by Bénédikt Tran.

@item 
gh-116946@footnote{https://github.com/python/cpython/issues/116946}: The @code{_random.Random} C type is now immutable. Patch by
Bénédikt Tran.

@item 
gh-57911@footnote{https://github.com/python/cpython/issues/57911}: When extracting tar files on Windows, slashes in symlink targets
will be replaced by backslashes to prevent corrupted links.

@item 
gh-138205@footnote{https://github.com/python/cpython/issues/138205}: Removed the @ref{3e9,,resize()} method on platforms that
don’t support the underlying syscall, instead of raising a
@ref{3ea,,SystemError}.

@item 
gh-138008@footnote{https://github.com/python/cpython/issues/138008}: Fix segmentation faults in the @ref{2d,,ctypes} module due to
invalid @ref{1a00,,argtypes}. Patch by Dung Nguyen.

@item 
gh-138252@footnote{https://github.com/python/cpython/issues/138252}: @ref{d8,,ssl}: @ref{336,,SSLContext} objects can now set client
and server TLS signature algorithms. If Python has been built with OpenSSL
3.5 or later, @ref{cbb,,SSLSocket} objects can return the signature
algorithms selected on a connection.

@item 
gh-138253@footnote{https://github.com/python/cpython/issues/138253}: Add the `block' parameter in the @code{put()} and @code{get()}
methods of the @ref{25,,concurrent.interpreters} queues for compatibility
with the @ref{1738,,queue.Queue} interface.

@item 
gh-60462@footnote{https://github.com/python/cpython/issues/60462}: Fix @ref{19f7,,locale.strxfrm()} on Solaris (and possibly other
platforms).

@item 
gh-138239@footnote{https://github.com/python/cpython/issues/138239}: The REPL now highlights @ref{85a,,type} as a soft keyword in
@ref{85a,,type statements}.

@item 
gh-78502@footnote{https://github.com/python/cpython/issues/78502}: @ref{23c,,mmap.mmap} now has a `trackfd' parameter on Windows; if
it is @code{False}, the file handle corresponding to `fileno' will not be
duplicated.

@item 
gh-138204@footnote{https://github.com/python/cpython/issues/138204}: Forbid expansion of shared anonymous @ref{94,,memory maps}
on Linux, which caused a bus error.

@item 
gh-138010@footnote{https://github.com/python/cpython/issues/138010}: Fix an issue where defining a class with a
@ref{695,,@@warnings.deprecated}-decorated base class may not invoke the
correct @ref{a22,,__init_subclass__()} method in cases involving
multiple inheritance. Patch by Brian Schubert.

@item 
gh-134716@footnote{https://github.com/python/cpython/issues/134716}: Add support of regular expressions in the @ref{1c0,,-W} option
and the 
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,PYTHONWARNINGS} environment variable.

@item 
gh-138133@footnote{https://github.com/python/cpython/issues/138133}: Prevent infinite traceback loop when sending CTRL^C to Python
through @code{strace}.

@item 
gh-138122@footnote{https://github.com/python/cpython/issues/138122}: Implement 
@geindex Python Enhancement Proposals; PEP 799
PEP 799@footnote{https://peps.python.org/pep-0799/} – A dedicated profiling package for
organizing Python profiling tools. Patch by Pablo Galindo.

@item 
gh-138092@footnote{https://github.com/python/cpython/issues/138092}: Fixed a bug in @ref{e5e,,mmap.mmap.flush()} where calling with only
an offset parameter would fail.

@item 
gh-138044@footnote{https://github.com/python/cpython/issues/138044}: Remove compatibility shim for deprecated parameter `package' in
@ref{2d7,,importlib.resources.files()}. Patch by Semyon Moroz.

@item 
gh-86819@footnote{https://github.com/python/cpython/issues/86819}: @ref{d4,,socket}: Add missing constants for ISO-TP sockets.

@item 
gh-137884@footnote{https://github.com/python/cpython/issues/137884}: Add @ref{e01,,threading.get_native_id()} support for
Illumos/Solaris. Patch by Yüce Tekol.

@item 
gh-134869@footnote{https://github.com/python/cpython/issues/134869}: Fix an issue where pressing Ctrl+C during tab completion in the
REPL would leave the autocompletion menu in a corrupted state.

@item 
gh-137840@footnote{https://github.com/python/cpython/issues/137840}: @ref{290,,typing.TypedDict} now supports the @code{closed} and
@code{extra_items} keyword arguments (as described in 
@geindex Python Enhancement Proposals; PEP 728
PEP 728@footnote{https://peps.python.org/pep-0728/}) to control
whether additional non-required keys are allowed and to specify their
value type.

@item 
gh-132947@footnote{https://github.com/python/cpython/issues/132947}: Applied changes to @code{importlib.metadata} from
importlib_metadata 8.7@footnote{https://importlib-metadata.readthedocs.io/en/latest/history.html#v8-7-0},
including @code{dist} now disallowed for @code{EntryPoints.select}; deferred
imports for faster import times; added support for metadata with newlines
(python/cpython#119650); and @code{metadata()} function now returns @code{None}
when a metadata directory is present but no metadata is present.

@item 
gh-90548@footnote{https://github.com/python/cpython/issues/90548}: Fix @code{musl} detection for @ref{1a01,,platform.libc_ver()} on Alpine
Linux if compiled with –strip-all.

@item 
gh-137317@footnote{https://github.com/python/cpython/issues/137317}: @ref{4bd,,inspect.signature()} now correctly handles classes that
use a descriptor on a wrapped @code{__init__()} or @code{__new__()}
method. Contributed by Yongyu Yan.

@item 
gh-137754@footnote{https://github.com/python/cpython/issues/137754}: Fix import of the @ref{13d,,zoneinfo} module if the C
implementation of the @ref{33,,datetime} module is not available.

@item 
gh-125854@footnote{https://github.com/python/cpython/issues/125854}: Improve error messages for invalid category in
@ref{18bb,,warnings.warn()}.

@item 
gh-137729@footnote{https://github.com/python/cpython/issues/137729}: @ref{231,,locale.setlocale()} now supports language codes with
@code{@@}-modifiers. @code{@@}-modifier are no longer silently removed in
@ref{232,,locale.getlocale()}, but included in the language code.

@item 
gh-73487@footnote{https://github.com/python/cpython/issues/73487}: Speedup processing arguments (up to 1.5x) in the @ref{39,,decimal}
module methods, that now using @ref{34b,,METH_FASTCALL} calling
convention.  Patch by Sergey B Kirpichev.

@item 
gh-137634@footnote{https://github.com/python/cpython/issues/137634}: Calendar pages generated by the @ref{202,,calendar.HTMLCalendar}
class now support dark mode and have been migrated to the HTML5 standard
for improved accessibility.

@item 
gh-137630@footnote{https://github.com/python/cpython/issues/137630}: The @code{_interpreters} module now uses Argument Clinic to
parse arguments. Patch by Adam Turner.

@item 
gh-137583@footnote{https://github.com/python/cpython/issues/137583}: Fix a deadlock introduced in 3.13.6 when a call to
@ref{115d,,ssl.SSLSocket.recv} was blocked in one thread,
and then another method on the object (such as @ref{1160,,ssl.SSLSocket.send}) was subsequently called in another thread.

@item 
gh-92936@footnote{https://github.com/python/cpython/issues/92936}: Update regex used by @code{http.cookies.SimpleCookie} to handle
values containing double quotes.

@item 
gh-137426@footnote{https://github.com/python/cpython/issues/137426}: Remove the code deprecation of
@code{importlib.abc.ResourceLoader}. It is documented as deprecated, but left
for backwards compatibility with other classes in @code{importlib.abc}.

@item 
gh-137490@footnote{https://github.com/python/cpython/issues/137490}: Handle @ref{1a02,,ECANCELED} in the same way as
@ref{1140,,EINTR} in @ref{1164,,signal.sigwaitinfo()} on NetBSD.

@item 
gh-137512@footnote{https://github.com/python/cpython/issues/137512}: Add new constants in the @ref{c4,,resource} module:
@ref{24f,,RLIMIT_NTHR}, @ref{250,,RLIMIT_UMTXP},
@ref{1a03,,RLIMIT_PIPEBUF}, @ref{251,,RLIMIT_THREADS},
@ref{252,,RLIM_SAVED_CUR}, and @ref{253,,RLIM_SAVED_MAX}.

@item 
gh-137044@footnote{https://github.com/python/cpython/issues/137044}: @ref{3e6,,resource.RLIM_INFINITY} is now always a positive
integer. On all supported platforms, it is larger than any limited
resource value, which simplifies comparison of the resource values.
Previously, it could be negative, such as -1 or -3, depending on platform.

@item 
gh-137477@footnote{https://github.com/python/cpython/issues/137477}: Fix @code{inspect.getblock()}, @ref{19f3,,inspect.getsourcelines()}
and @ref{1a04,,inspect.getsource()} for generator expressions.

@item 
gh-137481@footnote{https://github.com/python/cpython/issues/137481}: Calendar uses the lengths of the locale’s weekdays to decide if
the width requires abbreviation.

@item 
gh-137466@footnote{https://github.com/python/cpython/issues/137466}: Remove undocumented @code{glob.glob0()} and @code{glob.glob1()}
functions, which have been deprecated since Python 3.13. Use
@ref{2d4,,glob.glob()} and pass a directory to its `root_dir' argument instead.

@item 
gh-137044@footnote{https://github.com/python/cpython/issues/137044}: Return large limit values as positive integers instead of
negative integers in @ref{1a05,,resource.getrlimit()}. Accept large values and
reject negative values (except @ref{3e6,,RLIM_INFINITY}) for limits
in @ref{3e7,,resource.setrlimit()}.

@item 
gh-115766@footnote{https://github.com/python/cpython/issues/115766}: Fix @code{ipaddress.IPv4Interface.is_unspecified}.

@item 
gh-75989@footnote{https://github.com/python/cpython/issues/75989}: @ref{27a,,tarfile.TarFile.extractall()} and
@ref{27b,,tarfile.TarFile.extract()} now overwrite symlinks when extracting
hardlinks. (Contributed by Alexander Enrique Urieles Nieto in
gh-75989@footnote{https://github.com/python/cpython/issues/75989}.)

@item 
gh-137017@footnote{https://github.com/python/cpython/issues/137017}: Fix @ref{d18,,threading.Thread.is_alive} to remain @code{True} until
the underlying OS thread is fully cleaned up. This avoids false negatives
in edge cases involving thread monitoring or premature
@code{threading.Thread.is_alive} calls.

@item 
gh-137273@footnote{https://github.com/python/cpython/issues/137273}: Fix debug assertion failure in @ref{231,,locale.setlocale()} on
Windows.

@item 
gh-137191@footnote{https://github.com/python/cpython/issues/137191}: Fix how type parameters are collected, when
@ref{76c,,typing.Protocol} are specified with explicit parameters. Now,
@ref{19f2,,typing.Generic} and @code{typing.Protocol} always dictate the
parameter number and parameter ordering of types. Previous behavior was a
bug.

@item 
gh-137282@footnote{https://github.com/python/cpython/issues/137282}: Fix tab completion and @ref{a23,,dir()} on
@ref{24,,concurrent.futures}.

@item 
gh-137257@footnote{https://github.com/python/cpython/issues/137257}: Bump the version of pip bundled in ensurepip to version 25.2

@item 
gh-137239@footnote{https://github.com/python/cpython/issues/137239}: @ref{6c,,heapq}: Update @code{heapq.__all__} with @code{*_max}
functions.

@item 
gh-124503@footnote{https://github.com/python/cpython/issues/124503}: @ref{fd7,,ast.literal_eval()} is 10-20% faster for small inputs.

@item 
gh-137226@footnote{https://github.com/python/cpython/issues/137226}: Fix behavior of @ref{150,,annotationlib.ForwardRef.evaluate()} when
the `type_params' parameter is passed and the name of a type param is also
present in an enclosing scope.

@item 
gh-137197@footnote{https://github.com/python/cpython/issues/137197}: @ref{336,,SSLContext} objects can now set TLS 1.3 cipher
suites via @ref{25e,,set_ciphersuites()}.

@item 
gh-81325@footnote{https://github.com/python/cpython/issues/81325}: @ref{15b7,,tarfile.TarFile} now accepts a @ref{79f,,path-like} when working on a tar archive. (Contributed by
Alexander Enrique Urieles Nieto in gh-81325@footnote{https://github.com/python/cpython/issues/81325}.)

@item 
gh-137185@footnote{https://github.com/python/cpython/issues/137185}: Fix a potential async-signal-safety issue in
@ref{5b,,faulthandler} when printing C stack traces.

@item 
gh-133951@footnote{https://github.com/python/cpython/issues/133951}: Remove lib64-lib symlink creation when creating new virtual
environments in @ref{11a,,venv} module

@item 
gh-130522@footnote{https://github.com/python/cpython/issues/130522}: Fix unraisable @ref{291,,TypeError} raised during
@ref{1a0,,interpreter shutdown} in the @ref{f6,,threading} module.

@item 
gh-137059@footnote{https://github.com/python/cpython/issues/137059}: Fix handling of file URLs with a Windows drive letter in the
URL authority by @ref{539,,urllib.request.url2pathname()}. This fixes a
regression in earlier pre-releases of Python 3.14.

@item 
gh-136980@footnote{https://github.com/python/cpython/issues/136980}: Remove unused C tracing code in bdb for event type @code{c_call},
@code{c_return} and @code{c_exception}

@item 
gh-130577@footnote{https://github.com/python/cpython/issues/130577}: @ref{e7,,tarfile} now validates archives to ensure member offsets
are non-negative.  (Contributed by Alexander Enrique Urieles Nieto in
gh-130577@footnote{https://github.com/python/cpython/issues/130577}.)

@item 
gh-136170@footnote{https://github.com/python/cpython/issues/136170}: Removed the unreleased @code{zipfile.ZipFile.data_offset} property
added in 3.14.0a7 as it wasn’t fully clear which behavior it should have
in some situations so the result was not always what a user might expect.

@item 
gh-121237@footnote{https://github.com/python/cpython/issues/121237}: Support @code{%:z} directive for
@ref{2d2,,datetime.datetime.strptime()}, @ref{1a06,,datetime.time.strptime()} and
@ref{17cf,,time.strptime()}. Patch by Lucas Esposito and Semyon Moroz.

@item 
gh-136929@footnote{https://github.com/python/cpython/issues/136929}: Ensure that hash functions guaranteed to be always `available'
exist as attributes of @ref{6b,,hashlib} even if they will not work at
runtime due to missing backend implementations. For instance,
@code{hashlib.md5} will no longer raise @ref{1a9,,AttributeError} if OpenSSL is
not available and Python has been built without MD5 support. Patch by
Bénédikt Tran.

@item 
gh-124621@footnote{https://github.com/python/cpython/issues/124621}: pyrepl now works in Emscripten.

@item 
gh-136914@footnote{https://github.com/python/cpython/issues/136914}: Fix retrieval of @ref{1a07,,doctest.DocTest.lineno} for objects
decorated with @ref{1a08,,functools.cache()} or
@ref{94e,,functools.cached_property}.

@item 
gh-136912@footnote{https://github.com/python/cpython/issues/136912}: @ref{efc,,hmac.digest()} now properly handles large keys and
messages by falling back to the pure Python implementation when necessary.
Patch by Bénédikt Tran.

@item 
gh-83424@footnote{https://github.com/python/cpython/issues/83424}: Allows creating a @ref{dad,,ctypes.CDLL} without name when passing
a handle as an argument.

@item 
gh-135228@footnote{https://github.com/python/cpython/issues/135228}: When @ref{32,,dataclasses} replaces a class with a slotted
dataclass, the original class can now be garbage collected again. Earlier
changes in Python 3.14 caused this class to always remain in existence
together with the replacement class synthesized by @code{dataclasses}.

@item 
gh-136874@footnote{https://github.com/python/cpython/issues/136874}: Discard URL query and fragment in
@ref{539,,urllib.request.url2pathname()}.

@item 
gh-136787@footnote{https://github.com/python/cpython/issues/136787}: @ref{6b,,hashlib}: improve exception messages when a hash
algorithm is not recognized, blocked by the current security policy or
incompatible with the desired operation (for instance, using HMAC with
SHAKE). Patch by Bénédikt Tran.

@item 
gh-130645@footnote{https://github.com/python/cpython/issues/130645}: Enable color help by default in @ref{7,,argparse}.

@item 
gh-131724@footnote{https://github.com/python/cpython/issues/131724}: In @ref{72,,http.client}, a new `max_response_headers'
keyword-only parameter has been added to
@ref{223,,HTTPConnection} and
@ref{224,,HTTPSConnection} constructors. This parameter sets
the maximum number of allowed response headers, helping to prevent
denial-of-service attacks.

@item 
gh-135427@footnote{https://github.com/python/cpython/issues/135427}: With @ref{1c0,,-Werror}, the DeprecationWarning emitted by
@ref{6bd,,os.fork()} and @ref{6be,,os.forkpty()} in mutli-threaded processes
is now raised as an exception. Previously it was silently ignored. Patch
by Rani Pinchuk.

@item 
gh-136234@footnote{https://github.com/python/cpython/issues/136234}: Fix @ref{1a09,,asyncio.WriteTransport.writelines()} to be robust to
connection failure, by using the same behavior as
@ref{1a0a,,write()}.

@item 
gh-53144@footnote{https://github.com/python/cpython/issues/53144}: @code{encodings.aliases}: Add @code{latin_N} aliases

@item 
gh-136669@footnote{https://github.com/python/cpython/issues/136669}: @code{_asyncio} is now statically linked for improved
performance.

@item 
gh-136134@footnote{https://github.com/python/cpython/issues/136134}: @code{SMTP.auth_cram_md5()} now raises an
@ref{134a,,SMTPException} instead of a @ref{277,,ValueError} if Python has
been built without MD5 support. In particular, @ref{cfa,,SMTP}
clients will not attempt to use this method even if the remote server is
assumed to support it. Patch by Bénédikt Tran.

@item 
gh-136134@footnote{https://github.com/python/cpython/issues/136134}: @ref{1a0b,,IMAP4.login_cram_md5} now
raises an @ref{1a0c,,IMAP4.error} if CRAM-MD5
authentication is not supported. Patch by Bénédikt Tran.

@item 
gh-136591@footnote{https://github.com/python/cpython/issues/136591}: @code{_hashlib}: avoid using deprecated functions
@code{ERR_func_error_string@footnote{https://manpages.debian.org/ERR_func_error_string}} and @code{EVP_MD_CTX_md@footnote{https://manpages.debian.org/EVP_MD_CTX_md}} when using
OpenSSL 3.0 and later. Patch by Bénédikt Tran.

@item 
gh-136571@footnote{https://github.com/python/cpython/issues/136571}: @ref{db0,,datetime.date.fromisocalendar()} can now raise
OverflowError for out of range arguments.

@item 
gh-136549@footnote{https://github.com/python/cpython/issues/136549}: Fix signature of @ref{c23,,threading.excepthook()}.

@item 
gh-136492@footnote{https://github.com/python/cpython/issues/136492}: Expose 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}’s @ref{28c,,FrameLocalsProxyType} in the
@ref{10c,,types} module.

@item 
gh-83336@footnote{https://github.com/python/cpython/issues/83336}: @code{utf8_sig} is now aliased to @ref{57,,encodings.utf_8_sig}

@item 
gh-136523@footnote{https://github.com/python/cpython/issues/136523}: Fix @ref{2e7,,wave.Wave_write} emitting an unraisable when open
raises.

@item 
gh-136507@footnote{https://github.com/python/cpython/issues/136507}: Fix mimetypes CLI to handle multiple file parameters.

@item 
gh-52876@footnote{https://github.com/python/cpython/issues/52876}: Add missing @code{keepends} (default @code{True}) parameter to
@code{codecs.StreamReaderWriter.readline()} and
@code{codecs.StreamReaderWriter.readlines()}.

@item 
gh-136470@footnote{https://github.com/python/cpython/issues/136470}: Correct @ref{46a,,concurrent.futures.InterpreterPoolExecutor}’s
default thread name.

@item 
gh-136476@footnote{https://github.com/python/cpython/issues/136476}: Fix a bug that was causing the @code{get_async_stack_trace}
function to miss some frames in the stack trace.

@item 
gh-136434@footnote{https://github.com/python/cpython/issues/136434}: Fix docs generation of @code{UnboundItem} in
@ref{25,,concurrent.interpreters} when running with @ref{116e,,-OO}.

@item 
gh-136380@footnote{https://github.com/python/cpython/issues/136380}: Raises @ref{1a9,,AttributeError} when accessing
@ref{46a,,concurrent.futures.InterpreterPoolExecutor} and subinterpreters
are not available.

@item 
gh-72327@footnote{https://github.com/python/cpython/issues/72327}: Suggest using the system command prompt when @code{pip install} is
typed into the REPL. Patch by Tom Viner, Richard Si, and Brian Schubert.

@item 
gh-135953@footnote{https://github.com/python/cpython/issues/135953}: Implement a new high-frequency runtime profiler that leverages
the existing remote debugging functionality to collect detailed execution
statistics from running Python processes. This tool is exposed in the
@code{profile.sample} module and enables non-intrusive observation of
production applications by attaching to already-running processes without
requiring any code modifications, restarts, or special startup flags. The
observer can perform extremely high-frequency sampling of stack traces and
interpreter state, providing detailed runtime execution analysis of live
applications.

@item 
gh-136021@footnote{https://github.com/python/cpython/issues/136021}: Make @code{type_params} parameter required in
@code{typing._eval_type()} after a deprecation period for not providing
this parameter. Also remove the @ref{2c9,,DeprecationWarning} for the old
behavior.

@item 
gh-136286@footnote{https://github.com/python/cpython/issues/136286}: Fix pickling failures for protocols 0 and 1 for many objects
related to subinterpreters.

@item 
gh-136047@footnote{https://github.com/python/cpython/issues/136047}: Fix issues with @ref{10d,,typing} when the C implementation of
@ref{4,,abc} is not available.

@item 
gh-136316@footnote{https://github.com/python/cpython/issues/136316}: Improve support for evaluating nested forward references in
@ref{151,,typing.evaluate_forward_ref()}.

@item 
gh-136306@footnote{https://github.com/python/cpython/issues/136306}: @ref{d8,,ssl} can now get and set groups used for key agreement.

@item 
gh-136156@footnote{https://github.com/python/cpython/issues/136156}: @ref{1a0d,,tempfile.TemporaryFile()} no longer uses @ref{1a0e,,os.O_EXCL}
with @ref{131d,,os.O_TMPFILE}, so it’s possible to use @code{linkat()} on the
file descriptor. Patch by Victor Stinner.

@item 
gh-133982@footnote{https://github.com/python/cpython/issues/133982}: Update Python implementation of @ref{1255,,io.BytesIO} to be
thread safe.

@item 
gh-136193@footnote{https://github.com/python/cpython/issues/136193}: Improve @ref{291,,TypeError} error message, when richcomparing two
@ref{6ea,,types.SimpleNamespace} objects.

@item 
gh-136097@footnote{https://github.com/python/cpython/issues/136097}: Fix potential infinite recursion and KeyError in @code{sysconfig
--generate-posix-vars}.

@item 
gh-85702@footnote{https://github.com/python/cpython/issues/85702}: If @code{zoneinfo._common.load_tzdata} is given a package without a
resource a @ref{1a0f,,zoneinfo.ZoneInfoNotFoundError} is raised rather than a
@ref{10f9,,PermissionError}. Patch by Victor Stinner.

@item 
gh-90733@footnote{https://github.com/python/cpython/issues/90733}: Improve error messages when reporting invalid parameters in
@ref{ffc,,hashlib.scrypt()}. Patch by Bénédikt Tran.

@item 
gh-134759@footnote{https://github.com/python/cpython/issues/134759}: Fix @ref{18d8,,UnboundLocalError} in
@ref{1576,,email.message.Message.get_payload()} when the payload to decode is a
@ref{1c7,,bytes} object. Patch by Kliment Lamonov.

@item 
gh-136028@footnote{https://github.com/python/cpython/issues/136028}: Fix parsing month names containing «İ» (U+0130, LATIN CAPITAL
LETTER I WITH DOT ABOVE) in @ref{17cf,,time.strptime()}. This affects locales
az_AZ, ber_DZ, ber_MA and crh_UA.

@item 
gh-87135@footnote{https://github.com/python/cpython/issues/87135}: Acquiring a @ref{1a10,,threading.Lock} or @ref{2df,,threading.RLock}
at interpreter shutdown will raise @ref{68a,,PythonFinalizationError} if
Python can determine that it would otherwise deadlock.

@item 
gh-135995@footnote{https://github.com/python/cpython/issues/135995}: In the palmos encoding, make byte @code{0x9b} decode to @code{›}
(U+203A - SINGLE RIGHT-POINTING ANGLE QUOTATION MARK).

@item 
gh-105456@footnote{https://github.com/python/cpython/issues/105456}: Removed @code{sre_compile}, @code{sre_constants} and
@code{sre_parse} modules.

@item 
gh-53203@footnote{https://github.com/python/cpython/issues/53203}: Fix @ref{17cf,,time.strptime()} for @code{%c} and @code{%x} formats on
locales byn_ER, wal_ET and lzh_TW, and for @code{%X} format on locales ar_SA,
bg_BG and lzh_TW.

@item 
gh-135878@footnote{https://github.com/python/cpython/issues/135878}: Fixes a crash of @ref{6ea,,types.SimpleNamespace} on @ref{487,,free threading} builds, when several threads were calling its
@ref{1bc,,__repr__()} method at the same time.

@item 
gh-135853@footnote{https://github.com/python/cpython/issues/135853}: Add @ref{237,,math.fmax()} and @ref{238,,math.fmin()} to get the larger
and smaller of two floating-point values. Patch by Bénédikt Tran.

@item 
gh-135836@footnote{https://github.com/python/cpython/issues/135836}: Fix @ref{18d7,,IndexError} in @ref{9f9,,asyncio.loop.create_connection()}
that could occur when non-@ref{53c,,OSError} exception is raised during
connection and socket’s @code{close()} raises @code{OSError}.

@item 
gh-135853@footnote{https://github.com/python/cpython/issues/135853}: @ref{91,,math}: expose C99 @ref{239,,signbit()} function to
determine whether the sign bit of a floating-point value is set. Patch by
Bénédikt Tran.

@item 
gh-134531@footnote{https://github.com/python/cpython/issues/134531}: @ref{6d,,hmac}: use the @code{EVP_MAC(3ssl)@footnote{https://manpages.debian.org/EVP_MAC(3ssl)}} interface for
HMAC when Python is built with OpenSSL 3.0 and later instead of the
deprecated @code{HMAC_CTX(3ssl)@footnote{https://manpages.debian.org/hmac(3)}} interface. Patch by
Bénédikt Tran.

@item 
gh-135836@footnote{https://github.com/python/cpython/issues/135836}: Fix @ref{18d7,,IndexError} in @ref{9f9,,asyncio.loop.create_connection()}
that could occur when the Happy Eyeballs algorithm resulted in an empty
exceptions list during connection attempts.

@item 
gh-135855@footnote{https://github.com/python/cpython/issues/135855}: Raise @ref{291,,TypeError} instead of @ref{3ea,,SystemError} when
@code{_interpreters.set___main___attrs()} is passed a non-dict object.
Patch by Brian Schubert.

@item 
gh-135823@footnote{https://github.com/python/cpython/issues/135823}: @ref{9f,,netrc}: improve the error message when the security check
for the ownership of the default configuration file @code{~/.netrc} fails.
Patch by Bénédikt Tran.

@item 
gh-135815@footnote{https://github.com/python/cpython/issues/135815}: @ref{9f,,netrc}: skip security checks if @ref{1a11,,os.getuid()} is
missing. Patch by Bénédikt Tran.

@item 
gh-135640@footnote{https://github.com/python/cpython/issues/135640}: Address bug where it was possible to call
@ref{e5b,,xml.etree.ElementTree.ElementTree.write()} on an ElementTree object
with an invalid root element. This behavior blanked the file passed to
@code{write} if it already existed.

@item 
gh-90117@footnote{https://github.com/python/cpython/issues/90117}: Speed up @ref{b3,,pprint} for @ref{4d9,,list} and @ref{1ce,,tuple}.

@item 
gh-135759@footnote{https://github.com/python/cpython/issues/135759}: @ref{6b,,hashlib}: reject negative digest lengths in OpenSSL-based
SHAKE objects by raising a @ref{277,,ValueError}. Previously, negative lengths
were implicitly rejected by raising a @ref{18fa,,MemoryError} or a
@ref{3ea,,SystemError}. Patch by Bénédikt Tran.

@item 
gh-123471@footnote{https://github.com/python/cpython/issues/123471}: Make concurrent iterations over @ref{190,,itertools.chain} safe
under @ref{487,,free threading}.

@item 
gh-135645@footnote{https://github.com/python/cpython/issues/135645}: Added @code{supports_isolated_interpreters} field to
@ref{926,,sys.implementation}.

@item 
gh-135646@footnote{https://github.com/python/cpython/issues/135646}: Raise consistent @ref{665,,NameError} exceptions in
@ref{150,,annotationlib.ForwardRef.evaluate()}

@item 
gh-135557@footnote{https://github.com/python/cpython/issues/135557}: Fix races on @ref{6c,,heapq} updates and @ref{4d9,,list} reads on
the @ref{487,,free threaded} build.

@item 
gh-119180@footnote{https://github.com/python/cpython/issues/119180}: Only fetch globals and locals if necessary in
@ref{66c,,annotationlib.get_annotations()}

@item 
gh-135561@footnote{https://github.com/python/cpython/issues/135561}: Fix a crash on DEBUG builds when an HACL* HMAC routine fails.
Patch by Bénédikt Tran.

@item 
gh-135386@footnote{https://github.com/python/cpython/issues/135386}: Fix opening a @ref{38,,dbm.sqlite3} database for reading from
read-only file or directory.

@item 
gh-135444@footnote{https://github.com/python/cpython/issues/135444}: Fix @ref{6d1,,asyncio.DatagramTransport.sendto()} to account for
datagram header size when data cannot be sent.

@item 
gh-65697@footnote{https://github.com/python/cpython/issues/65697}: @ref{26,,configparser}’s error message when attempting to write
an invalid key is now more helpful.

@item 
gh-135497@footnote{https://github.com/python/cpython/issues/135497}: Fix @ref{19f4,,os.getlogin()} failing for longer usernames on
BSD-based platforms.

@item 
gh-135487@footnote{https://github.com/python/cpython/issues/135487}: Fix @code{reprlib.Repr.repr_int()} when given integers with
more than @ref{1a12,,sys.get_int_max_str_digits()} digits. Patch by Bénédikt
Tran.

@item 
gh-135429@footnote{https://github.com/python/cpython/issues/135429}: Fix the argument mismatch in @code{_lsprof} for @code{PY_THROW}
event.

@item 
gh-135368@footnote{https://github.com/python/cpython/issues/135368}: Fix @ref{e0e,,unittest.mock.Mock} generation on
@ref{6e6,,dataclasses.dataclass()} objects. Now all special attributes are set
as it was before gh-124429@footnote{https://github.com/python/cpython/issues/124429}.

@item 
gh-135336@footnote{https://github.com/python/cpython/issues/135336}: @ref{85,,json} now encodes strings up to 2.2x faster if they
consist solely of characters that don’t require escaping.

@item 
gh-135335@footnote{https://github.com/python/cpython/issues/135335}: @ref{98,,multiprocessing}: Flush @code{stdout} and @code{stderr} after
preloading modules in the @code{forkserver}.

@item 
gh-126631@footnote{https://github.com/python/cpython/issues/126631}: Fix @ref{98,,multiprocessing} @code{forkserver} bug which prevented
@code{__main__} from being preloaded.

@item 
gh-133967@footnote{https://github.com/python/cpython/issues/133967}: Do not normalize @ref{89,,locale} name “C.UTF-8” to “en_US.UTF-8”.

@item 
gh-130870@footnote{https://github.com/python/cpython/issues/130870}: Preserve @ref{bc7,,types.GenericAlias} subclasses in
@ref{a9e,,typing.get_type_hints()}

@item 
gh-135321@footnote{https://github.com/python/cpython/issues/135321}: Raise a correct exception for values greater than 0x7fffffff
for the @code{BINSTRING} opcode in the C implementation of @ref{ab,,pickle}.

@item 
gh-121914@footnote{https://github.com/python/cpython/issues/121914}: Changed the names of the symbol tables for lambda expressions
and generator expressions to «<lambda>» and «<genexpr>» respectively to
avoid conflicts with user-defined names.

@item 
gh-135276@footnote{https://github.com/python/cpython/issues/135276}: Synchronized zipfile.Path with zipp 3.23, including improved
performance of @ref{1a13,,zipfile.Path.open()} for non-reading modes, rely on
@ref{94e,,functools.cached_property()} to cache values on the instance. Rely on
@code{save_method_args} to save the initialization method arguments. Fixed
@code{.name}, @code{.stem} and other basename-based properties on Windows when
working with a zipfile on disk.

@item 
gh-135234@footnote{https://github.com/python/cpython/issues/135234}: @ref{6b,,hashlib}: improve exception messages when an OpenSSL
function failed. When memory allocation fails on OpenSSL’s side, a
@ref{18fa,,MemoryError} is raised instead of a @ref{277,,ValueError}. Patch by
Bénédikt Tran.

@item 
gh-135244@footnote{https://github.com/python/cpython/issues/135244}: @ref{119,,uuid}: when the MAC address cannot be determined, the
48-bit node ID is now generated with a cryptographically-secure
pseudo-random number generator (CSPRNG) as per 
@geindex RFC; RFC 9562 Section 6.10-3
RFC 9562@comma{} §6.10.3@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html#section-6.10-3}. This affects @ref{f67,,uuid1()} and
@ref{53e,,uuid6()}.

@item 
gh-135241@footnote{https://github.com/python/cpython/issues/135241}: The @code{INT} opcode of the C accelerator @code{_pickle}
module was updated to look only for «00» and «01» to push booleans onto
the stack, aligning with the Python @ref{ab,,pickle} module.

@item 
gh-133934@footnote{https://github.com/python/cpython/issues/133934}: Improve @ref{d7,,sqlite3} CLI’s @code{.help} message.

@item 
gh-135069@footnote{https://github.com/python/cpython/issues/135069}: Fix the «Invalid error handling» exception in
@code{encodings.idna.IncrementalDecoder} to correctly replace the
“errors” parameter.

@item 
gh-130662@footnote{https://github.com/python/cpython/issues/130662}: +Accept leading zeros in precision and width fields for
+:class:@ref{1c2,,Decimal} formatting, for example @code{format(Decimal(1.25),
'.016f')}.

@item 
gh-130662@footnote{https://github.com/python/cpython/issues/130662}: Accept leading zeros in precision and width fields for
@ref{1c3,,Fraction} formatting, for example @code{format(Fraction(1,
3), '.016f')}.

@item 
gh-135004@footnote{https://github.com/python/cpython/issues/135004}: Rewrite and cleanup the internal @code{_blake2} module. Some
exception messages were changed but their types were left untouched. Patch
by Bénédikt Tran.

@item 
gh-134953@footnote{https://github.com/python/cpython/issues/134953}: Expand @code{_colorize} theme with @code{keyword_constant} and
implement in @ref{69d,,repl}.

@item 
gh-134978@footnote{https://github.com/python/cpython/issues/134978}: @ref{6b,,hashlib}: Supporting the @code{string} keyword parameter in
hash function constructors such as @ref{2f1,,new()} or the direct
hash-named constructors such as @ref{2f2,,md5()} and
@ref{2f3,,sha256()} is now deprecated and slated for removal in Python
3.19. Prefer passing the initial data as a positional argument for maximum
backwards compatibility. Patch by Bénédikt Tran.

@item 
gh-134970@footnote{https://github.com/python/cpython/issues/134970}: Fix the «unknown action» exception in
@ref{31d,,argparse.ArgumentParser.add_argument_group()} to correctly replace
the action class.

@item 
gh-134718@footnote{https://github.com/python/cpython/issues/134718}: By default, omit optional @code{Load()} values in
@ref{1e1,,ast.dump()}.

@item 
gh-134718@footnote{https://github.com/python/cpython/issues/134718}: @ref{1e1,,ast.dump()} now only omits @code{None} and @code{[]} values if
they are default values.

@item 
gh-134939@footnote{https://github.com/python/cpython/issues/134939}: Add the @ref{25,,concurrent.interpreters} module.  See 
@geindex Python Enhancement Proposals; PEP 734
PEP 734@footnote{https://peps.python.org/pep-0734/}.

@item 
gh-108885@footnote{https://github.com/python/cpython/issues/108885}: Run each example as a subtest in unit tests synthesized by
@ref{1a14,,doctest.DocFileSuite()} and @ref{11ac,,doctest.DocTestSuite()}. Add the
@ref{1a15,,doctest.DocTestRunner.report_skip()} method.

@item 
gh-134885@footnote{https://github.com/python/cpython/issues/134885}: Fix possible crash in the @ref{23,,compression.zstd} module
related to setting parameter types. Patch by Jelle Zijlstra.

@item 
gh-134857@footnote{https://github.com/python/cpython/issues/134857}: Improve error report for @ref{3d,,doctest}s run with
@ref{10f,,unittest}. Remove @code{doctest} module frames from tracebacks and
redundant newline character from a failure message.

@item 
gh-128840@footnote{https://github.com/python/cpython/issues/128840}: Fix parsing long IPv6 addresses with embedded IPv4 address.

@item 
gh-133579@footnote{https://github.com/python/cpython/issues/133579}: @ref{2e,,curses}: Consistently report failures of curses C API
calls in module-level methods by raising a @ref{1a16,,curses.error}. This
affects @ref{489,,assume_default_colors()}, @ref{1a17,,baudrate()},
@ref{1a18,,cbreak()}, @ref{1a19,,echo()}, @ref{1a1a,,longname()},
@ref{1a1b,,initscr()}, @ref{1a1c,,nl()}, @ref{1a1d,,raw()},
@ref{1a1e,,termattrs()}, @ref{1a1f,,termname()} and
@ref{1a20,,unctrl()}. Patch by Bénédikt Tran.

@item 
gh-133579@footnote{https://github.com/python/cpython/issues/133579}: @ref{1a21,,curses.window.refresh()} and
@ref{1a22,,curses.window.noutrefresh()} now raise a @ref{291,,TypeError} instead of
@ref{1a16,,curses.error} when called with an incorrect number of arguments for
@ref{1a23,,pads}. Patch by Bénédikt Tran.

@item 
gh-133579@footnote{https://github.com/python/cpython/issues/133579}: @ref{1a24,,curses.window}: Consistently
report failures of curses C API calls in Window methods by raising a
@ref{1a16,,curses.error}. This affects @ref{1a25,,addch()},
@ref{1a26,,addnstr()}, @ref{1a27,,addstr()},
@ref{1a28,,border()}, @ref{1a29,,box()},
@ref{1a2a,,chgat()}, @ref{1a2b,,getbkgd()},
@ref{1a2c,,inch()}, @ref{1a2d,,insstr()} and
@ref{1a2e,,insnstr()}. Patch by Bénédikt Tran.

@item 
gh-134771@footnote{https://github.com/python/cpython/issues/134771}: The @code{time_clockid_converter()} function now selects correct
type for @code{clockid_t} on Cygwin which fixes a build error.

@item 
gh-134637@footnote{https://github.com/python/cpython/issues/134637}: Fix performance regression in calling a @ref{2d,,ctypes} function
pointer in @ref{487,,free threading}.

@item 
gh-134696@footnote{https://github.com/python/cpython/issues/134696}: Built-in HACL* and OpenSSL implementations of hash function
constructors now correctly accept the same `documented' named arguments.
For instance, @ref{2f2,,md5()} could be previously invoked as
@code{md5(data=data)} or @code{md5(string=string)} depending on the underlying
implementation but these calls were not compatible. Patch by Bénédikt
Tran.

@item 
gh-132710@footnote{https://github.com/python/cpython/issues/132710}: If possible, ensure that @ref{f66,,uuid.getnode()} returns the same
result even across different processes. Previously, the result was
constant only within the same process. Patch by Bénédikt Tran.

@item 
gh-134531@footnote{https://github.com/python/cpython/issues/134531}: @code{_hashlib}: Rename internal C functions for
@code{_hashlib.HASH} and @code{_hashlib.HASHXOF} objects. Patch by
Bénédikt Tran.

@item 
gh-134698@footnote{https://github.com/python/cpython/issues/134698}: Fix a crash when calling methods of @ref{336,,ssl.SSLContext} or
@ref{cbb,,ssl.SSLSocket} across multiple threads.

@item 
gh-134151@footnote{https://github.com/python/cpython/issues/134151}: @ref{3e,,email}: Fix @ref{291,,TypeError} in
@ref{1a2f,,email.utils.decode_params()} when sorting 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} continuations
that contain an unnumbered section.

@item 
gh-134635@footnote{https://github.com/python/cpython/issues/134635}: @ref{13c,,zlib}: Allow to combine Adler-32 and CRC-32 checksums via
@ref{2bc,,adler32_combine()} and @ref{2bd,,crc32_combine()}. Patch by
Callum Attryde and Bénédikt Tran.

@item 
gh-134657@footnote{https://github.com/python/cpython/issues/134657}: @ref{b,,asyncio}: Remove some private names from
@code{asyncio.__all__}.

@item 
gh-134210@footnote{https://github.com/python/cpython/issues/134210}: @ref{1a30,,curses.window.getch()} now correctly handles signals.
Patch by Bénédikt Tran.

@item 
gh-80334@footnote{https://github.com/python/cpython/issues/80334}: @ref{1933,,multiprocessing.freeze_support()} now checks for work on
any «spawn» start method platform rather than only on Windows.

@item 
gh-134582@footnote{https://github.com/python/cpython/issues/134582}: Fix tokenize.untokenize() round-trip errors related to
t-strings braces escaping

@item 
gh-134580@footnote{https://github.com/python/cpython/issues/134580}: Improved the styling of HTML diff pages generated by the
@ref{214,,difflib.HtmlDiff} class, and migrated the output to the HTML5
standard.

@item 
gh-134565@footnote{https://github.com/python/cpython/issues/134565}: @ref{1a31,,unittest.doModuleCleanups()} no longer swallows all but
first exception raised in the cleanup code, but raises a
@ref{6d8,,ExceptionGroup} if multiple errors occurred.

@item 
gh-134546@footnote{https://github.com/python/cpython/issues/134546}: Ensure @ref{aa,,pdb} remote debugging script is readable by remote
Python process.

@item 
gh-134451@footnote{https://github.com/python/cpython/issues/134451}: Converted @code{asyncio.tools.CycleFoundException} from dataclass
to a regular exception type.

@item 
gh-114177@footnote{https://github.com/python/cpython/issues/114177}: Fix @ref{b,,asyncio} to not close subprocess pipes which would
otherwise error out when the event loop is already closed.

@item 
gh-90871@footnote{https://github.com/python/cpython/issues/90871}: Fixed an off by one error concerning the backlog parameter in
@ref{6d0,,create_unix_server()}. Contributed by Christian
Harries.

@item 
gh-134323@footnote{https://github.com/python/cpython/issues/134323}: Fix the @ref{1a32,,threading.RLock.locked()} method.

@item 
gh-86802@footnote{https://github.com/python/cpython/issues/86802}: Fixed asyncio memory leak in cancelled shield tasks. For
shielded tasks where the shield was cancelled, log potential exceptions
through the exception handler. Contributed by Christian Harries.

@item 
gh-71189@footnote{https://github.com/python/cpython/issues/71189}: Add support of the all-but-last mode in
@ref{241,,os.path.realpath()}.

@item 
gh-72902@footnote{https://github.com/python/cpython/issues/72902}: Improve speed (x1.1-1.8) of the @ref{1c3,,Fraction}
constructor for typical inputs (@ref{327,,float}’s,
@ref{1c2,,Decimal}’s or strings).

@item 
gh-134209@footnote{https://github.com/python/cpython/issues/134209}: @ref{2e,,curses}: The @ref{1a33,,curses.window.instr()} and
@ref{1a34,,curses.window.getstr()} methods now allocate their internal buffer on
the heap instead of the stack; in addition, the max buffer size is
increased from 1023 to 2047.

@item 
gh-88994@footnote{https://github.com/python/cpython/issues/88994}: Change @ref{8fa,,datetime.datetime.now()} to half-even rounding for
consistency with @ref{8fb,,datetime.datetime.fromtimestamp()}.  Patch by John
Keith Hohm.

@item 
gh-80184@footnote{https://github.com/python/cpython/issues/80184}: The default queue size is now @code{socket.SOMAXCONN} for
@ref{16c4,,socketserver.TCPServer}.

@item 
gh-132983@footnote{https://github.com/python/cpython/issues/132983}: Add @code{compression.zstd} version information to
@code{test.pythoninfo}.

@item 
gh-134235@footnote{https://github.com/python/cpython/issues/134235}: Updated tab completion on REPL to include builtin modules.
Contributed by Tom Wang, Hunter Young

@item 
gh-134152@footnote{https://github.com/python/cpython/issues/134152}: Fixed @ref{18d8,,UnboundLocalError} that could occur during
@ref{3e,,email} header parsing if an expected trailing delimiter is missing
in some contexts.

@item 
gh-134152@footnote{https://github.com/python/cpython/issues/134152}: @ref{3e,,email}: Fix parsing of email message ID with invalid
domain.

@item 
gh-134168@footnote{https://github.com/python/cpython/issues/134168}: @ref{75,,http.server}: Fix IPv6 address binding and
@ref{1a35,,--directory} handling when using HTTPS.

@item 
gh-62184@footnote{https://github.com/python/cpython/issues/62184}: Remove import of C implementation of @ref{16b4,,io.FileIO} from
Python implementation which has its own implementation

@item 
gh-134087@footnote{https://github.com/python/cpython/issues/134087}: Remove support for arbitrary positional or keyword arguments in
the C implementation of @ref{2df,,threading.RLock} objects. This was
deprecated since Python 3.14. Patch by Bénédikt Tran.

@item 
gh-134173@footnote{https://github.com/python/cpython/issues/134173}: Speed up @ref{b,,asyncio} performance of transferring state from
thread pool @ref{155b,,concurrent.futures.Future} by up to 4.4x. Patch by J.
Nick Koston.

@item 
gh-133982@footnote{https://github.com/python/cpython/issues/133982}: Emit @ref{6dd,,RuntimeWarning} in the Python implementation of
@ref{82,,io} when the @ref{156c,,file-like object} is not closed
explicitly in the presence of multiple I/O layers.

@item 
gh-133890@footnote{https://github.com/python/cpython/issues/133890}: The @ref{e7,,tarfile} module now handles @ref{a67,,UnicodeEncodeError}
in the same way as @ref{53c,,OSError} when cannot extract a member.

@item 
gh-134097@footnote{https://github.com/python/cpython/issues/134097}: Fix interaction of the new @ref{69d,,REPL} and @ref{178,,-X showrefcount} command line option.

@item 
gh-133889@footnote{https://github.com/python/cpython/issues/133889}: The generated directory listing page in
@ref{22a,,http.server.SimpleHTTPRequestHandler} now only shows the decoded
path component of the requested URL, and not the query and fragment.

@item 
gh-134098@footnote{https://github.com/python/cpython/issues/134098}: Fix handling paths that end with a percent-encoded slash
(@code{%2f} or @code{%2F}) in @ref{22a,,http.server.SimpleHTTPRequestHandler}.

@item 
gh-132124@footnote{https://github.com/python/cpython/issues/132124}: On POSIX-compliant systems,
@code{multiprocessing.util.get_temp_dir()} now ignores 
@geindex TMPDIR
@geindex μεταβλητή περιβάλλοντος; TMPDIR
@code{TMPDIR}
(and similar environment variables) if the path length of @code{AF_UNIX}
socket files exceeds the platform-specific maximum length when using the
@ref{46c,,forkserver} start method.
Patch by Bénédikt Tran.

@item 
gh-134062@footnote{https://github.com/python/cpython/issues/134062}: @ref{83,,ipaddress}: fix collisions in @ref{ec1,,__hash__()}
for @ref{712,,IPv4Network} and @ref{713,,IPv6Network}
objects.

@item 
gh-134004@footnote{https://github.com/python/cpython/issues/134004}: @ref{cb,,shelve} as well as underlying @code{dbm.dumb} and
@code{dbm.sqlite} now have @code{reorganize()} methods to recover unused
free space previously occupied by deleted entries.

@item 
gh-133970@footnote{https://github.com/python/cpython/issues/133970}: Make @code{string.templatelib.Template} and
@code{string.templatelib.Interpolation} generic.

@item 
gh-71253@footnote{https://github.com/python/cpython/issues/71253}: Raise @ref{277,,ValueError} in @ref{32b,,open()} if `opener' returns a
negative file-descriptor in the Python implementation of @ref{82,,io} to
match the C implementation.

@item 
gh-133960@footnote{https://github.com/python/cpython/issues/133960}: Simplify and improve @ref{151,,typing.evaluate_forward_ref()}. It
now no longer raises errors on certain invalid types. In several
situations, it is now able to evaluate forward references that were
previously unsupported.

@item 
gh-133925@footnote{https://github.com/python/cpython/issues/133925}: Make the private class @code{typing._UnionGenericAlias} hashable.

@item 
gh-133604@footnote{https://github.com/python/cpython/issues/133604}: Remove @code{platform.java_ver()} which was deprecated since
Python 3.13.

@item 
gh-133875@footnote{https://github.com/python/cpython/issues/133875}: Removed deprecated @code{pathlib.PurePath.is_reserved()}. Use
@ref{2d9,,os.path.isreserved()} to detect reserved paths on Windows.

@item 
gh-133873@footnote{https://github.com/python/cpython/issues/133873}: Remove the deprecated @code{getmark()}, @code{setmark()} and
@code{getmarkers()} methods of the @ref{2e6,,Wave_read} and
@ref{2e7,,Wave_write} classes, which were deprecated since Python
3.13. Patch by Bénédikt Tran.

@item 
gh-133866@footnote{https://github.com/python/cpython/issues/133866}: Remove the undocumented function
@code{ctypes.SetPointerType()}, which has been deprecated since Python
3.13. Patch by Bénédikt Tran.

@item 
gh-133823@footnote{https://github.com/python/cpython/issues/133823}: Remove support for @code{TD = TypedDict("TD")} and @code{TD =
TypedDict("TD", None)} calls for constructing @ref{290,,typing.TypedDict}
objects with zero field. Patch by Bénédikt Tran.

@item 
gh-125996@footnote{https://github.com/python/cpython/issues/125996}: Fix thread safety of @ref{9d5,,collections.OrderedDict}. Patch by
Kumar Aditya.

@item 
gh-133817@footnote{https://github.com/python/cpython/issues/133817}: Remove support for creating @ref{2e4,,NamedTuple} classes
via the undocumented keyword argument syntax. Patch by Bénédikt Tran.

@item 
gh-133653@footnote{https://github.com/python/cpython/issues/133653}: Fix @ref{1dc,,argparse.ArgumentParser} with the `formatter_class'
argument. Fix TypeError when `formatter_class' is a custom subclass of
@code{HelpFormatter}. Fix TypeError when `formatter_class' is not a
subclass of @code{HelpFormatter} and non-standard `prefix_char' is
used. Fix support of colorizing when `formatter_class' is not a subclass
of @code{HelpFormatter}.

@item 
gh-133810@footnote{https://github.com/python/cpython/issues/133810}: Remove @code{http.server.CGIHTTPRequestHandler} and
@code{--cgi} flag from the @code{python -m http.server} command-line
interface. They were deprecated in Python 3.13. Patch by Bénédikt Tran.

@item 
gh-132641@footnote{https://github.com/python/cpython/issues/132641}: Fixed a race in @ref{db3,,functools.lru_cache()} under
free-threading.

@item 
gh-133783@footnote{https://github.com/python/cpython/issues/133783}: Fix bug with applying @ref{45a,,copy.replace()} to @ref{9,,ast}
objects. Attributes that default to @code{None} were incorrectly treated as
required for manually created AST nodes.

@item 
gh-133684@footnote{https://github.com/python/cpython/issues/133684}: Fix bug where @ref{66c,,annotationlib.get_annotations()} would
return the wrong result for certain classes that are part of a class
hierarchy where @code{from __future__ import annotations} is used.

@item 
gh-77057@footnote{https://github.com/python/cpython/issues/77057}: Fix handling of invalid markup declarations in
@ref{c4d,,html.parser.HTMLParser}.

@item 
gh-130328@footnote{https://github.com/python/cpython/issues/130328}: Speedup pasting in @code{PyREPL} on Windows in a legacy console.
Patch by Chris Eibl.

@item 
gh-133701@footnote{https://github.com/python/cpython/issues/133701}: Fix bug where @ref{290,,typing.TypedDict} classes defined under
@code{from __future__ import annotations} and inheriting from another
@code{TypedDict} had an incorrect @code{__annotations__} attribute.

@item 
gh-133656@footnote{https://github.com/python/cpython/issues/133656}: Remove deprecated @code{zipimport.zipimporter.load_module()}.
Use @ref{2e9,,zipimport.zipimporter.exec_module()} instead.

@item 
gh-133722@footnote{https://github.com/python/cpython/issues/133722}: Added a `color' option to @ref{213,,difflib.unified_diff()} that
colors output similar to @code{git diff}.

@item 
gh-133489@footnote{https://github.com/python/cpython/issues/133489}: @ref{13b6,,random.getrandbits()} can now generate more that 2@w{^31} bits. @ref{1a36,,random.randbytes()} can now generate more that 256
MiB.

@item 
gh-133595@footnote{https://github.com/python/cpython/issues/133595}: Clean up @ref{3df,,sqlite3.Connection} APIs. All parameters of
@ref{3e0,,sqlite3.connect()} except `database' are now keyword-only. The first
three parameters of methods @ref{3e1,,create_function()}
and @ref{3e2,,create_aggregate()} are now positional-only.
The first parameter of methods @ref{3e3,,set_authorizer()},
@ref{3e4,,set_progress_handler()} and
@ref{3e5,,set_trace_callback()} is now positional-only.

@item 
gh-133581@footnote{https://github.com/python/cpython/issues/133581}: Improve unparsing of t-strings in @ref{cb6,,ast.unparse()} and
@code{from __future__ import annotations}. Empty t-strings now round-trip
correctly and formatting in interpolations is preserved. Patch by Jelle
Zijlstra.

@item 
gh-133577@footnote{https://github.com/python/cpython/issues/133577}: Add parameter @code{formatter} to @ref{dc2,,logging.basicConfig()}.

@item 
gh-92897@footnote{https://github.com/python/cpython/issues/92897}: Removed the @code{check_home} parameter from
@ref{2dd,,sysconfig.is_python_build()}, deprecated since Python 3.12.

@item 
gh-133551@footnote{https://github.com/python/cpython/issues/133551}: Support t-strings (
@geindex Python Enhancement Proposals; PEP 750
PEP 750@footnote{https://peps.python.org/pep-0750/}) in @ref{6,,annotationlib}. Patch
by Jelle Zijlstra.

@item 
gh-133517@footnote{https://github.com/python/cpython/issues/133517}: Remove @ref{8ae,,os.listdrives()}, @ref{8af,,os.listvolumes()} and
@ref{8b0,,os.listmounts()} in non Windows desktop builds since the underlying
functionality is missing.

@item 
gh-133439@footnote{https://github.com/python/cpython/issues/133439}: Fix dot commands with trailing spaces are mistaken for
multi-line SQL statements in the sqlite3 command-line interface.

@item 
gh-133447@footnote{https://github.com/python/cpython/issues/133447}: Add basic color to @ref{d7,,sqlite3} CLI interface.

@item 
gh-133253@footnote{https://github.com/python/cpython/issues/133253}: Fix thread-safety issues in @ref{88,,linecache}.

@item 
gh-133390@footnote{https://github.com/python/cpython/issues/133390}: Support keyword completion in the @ref{d7,,sqlite3} command-line
interface and add @ref{1a37,,sqlite3.SQLITE_KEYWORDS} constant.

@item 
gh-132493@footnote{https://github.com/python/cpython/issues/132493}: Avoid accessing @code{__annotations__} unnecessarily in
@ref{4bd,,inspect.signature()}.

@item 
gh-133017@footnote{https://github.com/python/cpython/issues/133017}: Improve the error message of
@ref{1a38,,multiprocessing.sharedctypes.Array()},
@ref{1a39,,multiprocessing.sharedctypes.RawArray()},
@ref{1a3a,,multiprocessing.sharedctypes.Value()} and
@ref{1a3b,,multiprocessing.sharedctypes.RawValue()} when an invalid typecode is
passed. Patch by Tomas Roun

@item 
gh-132813@footnote{https://github.com/python/cpython/issues/132813}: Improve error messages for incorrect types and values of
@ref{1a3c,,csv.Dialect} attributes.

@item 
gh-132969@footnote{https://github.com/python/cpython/issues/132969}: Prevent the @ref{206,,ProcessPoolExecutor}
executor thread, which remains running when @ref{cbe,,shutdown(wait=False)}, from attempting to adjust the
pool’s worker processes after the object state has already been reset
during shutdown. A combination of conditions, including a worker process
having terminated abormally, resulted in an exception and a potential hang
when the still-running executor thread attempted to replace dead workers
within the pool.

@item 
gh-132876@footnote{https://github.com/python/cpython/issues/132876}: @code{ldexp()} on Windows doesn’t round subnormal results before
Windows 11, but should.  Python’s @ref{1a3d,,math.ldexp()} wrapper now does
round them, so results may change slightly, in rare cases of very small
results, on Windows versions before 11.

@item 
gh-133009@footnote{https://github.com/python/cpython/issues/133009}: @ref{12e,,xml.etree.ElementTree}: Fix a crash in
@ref{1909,,Element.__deepcopy__} when the element is
concurrently mutated. Patch by Bénédikt Tran.

@item 
gh-132908@footnote{https://github.com/python/cpython/issues/132908}: Add @ref{235,,math.isnormal()} and @ref{236,,math.issubnormal()}
functions.  Patch by Sergey B Kirpichev.

@item 
gh-95380@footnote{https://github.com/python/cpython/issues/95380}: @ref{1962,,fcntl.fcntl()} and @ref{181d,,fcntl.ioctl()}: Remove the 1024
bytes limit on the size of not mutated bytes-like argument.

@item 
gh-122781@footnote{https://github.com/python/cpython/issues/122781}: Fix @code{%z} directive in @ref{2d2,,datetime.datetime.strptime()} to
allow for no provided offset as was documented.

@item 
gh-123471@footnote{https://github.com/python/cpython/issues/123471}: Make concurrent iterations over @ref{16b6,,itertools.combinations}
and @ref{16b7,,itertools.product} safe under free-threading.

@item 
gh-127081@footnote{https://github.com/python/cpython/issues/127081}: Fix libc thread safety issues with @ref{34,,dbm} by performing
stateful operations in critical sections.

@item 
gh-127081@footnote{https://github.com/python/cpython/issues/127081}: Fix libc thread safety issues with @ref{a5,,os} by replacing
@code{getlogin} with @code{getlogin_r} re-entrant version.

@item 
gh-127081@footnote{https://github.com/python/cpython/issues/127081}: Fix libc thread safety issues with @ref{ba,,pwd} by locking access
to @code{getpwall}.

@item 
gh-132551@footnote{https://github.com/python/cpython/issues/132551}: Make @ref{1255,,io.BytesIO} safe in @ref{487,,free-threaded} build.

@item 
gh-107583@footnote{https://github.com/python/cpython/issues/107583}: Fix @code{Flag} inversion when flag set has missing values
(@code{IntFlag} still flips all bits); fix negative assigned values
during flag creation (both @code{Flag} and @code{IntFlag} ignore
missing values).

@item 
gh-87790@footnote{https://github.com/python/cpython/issues/87790}: Support underscore and comma as thousands separators in the
fractional part for @ref{1c3,,Fraction}’s formatting.  Patch by
Sergey B Kirpichev.

@item 
gh-87790@footnote{https://github.com/python/cpython/issues/87790}: Support underscore and comma as thousands separators in the
fractional part for @ref{1c2,,Decimal}’s formatting.  Patch by
Sergey B Kirpichev.

@item 
gh-131884@footnote{https://github.com/python/cpython/issues/131884}: Fix formatting issues in @ref{10fb,,json.dump()} when both `indent'
and `skipkeys' are used.

@item 
gh-131788@footnote{https://github.com/python/cpython/issues/131788}: Make @code{ResourceTracker.send} from @ref{98,,multiprocessing}
re-entrant safe

@item 
gh-91349@footnote{https://github.com/python/cpython/issues/91349}: Adjust default @code{compressionlevel=} to 6 (down from 9) in
@ref{6a,,gzip} and @ref{e7,,tarfile}. It is the default level used by most
compression tools and a better tradeoff between speed and performance.

@item 
gh-131146@footnote{https://github.com/python/cpython/issues/131146}: Fix @ref{1a3e,,calendar.TextCalendar},
@ref{202,,calendar.HTMLCalendar}, and the @ref{15,,calendar} CLI to display
month names in the nominative case by adding
@ref{1a3f,,calendar.standalone_month_name} and
@ref{1a40,,calendar.standalone_month_abbr}, which provide month names and
abbreviations in the grammatical form used when a month name stands by
itself, if the locale supports it.

@item 
gh-123471@footnote{https://github.com/python/cpython/issues/123471}: Make concurrent iterations over @ref{1a41,,itertools.cycle} safe
under free-threading.

@item 
gh-130664@footnote{https://github.com/python/cpython/issues/130664}: Handle corner-case for @ref{1c3,,Fraction}’s
formatting: treat zero-padding (preceding the width field by a zero
(@code{'0'}) character) as an equivalent to a fill character of @code{'0'} with
an alignment type of @code{'='}, just as in case of @ref{327,,float}’s.

@item 
gh-130999@footnote{https://github.com/python/cpython/issues/130999}: Avoid exiting the new REPL and offer suggestions even if there
are non-string candidates when errors occur.

@item 
gh-88473@footnote{https://github.com/python/cpython/issues/88473}: Implement a fast path for @ref{48d,,datetime.date} objects in
@ref{186c,,datetime.date.today()} which results in a 5x performance gain while
proper subclasses retain their previous performance.

@item 
gh-126883@footnote{https://github.com/python/cpython/issues/126883}: Add check that timezone fields are in range for
@ref{a0a,,datetime.datetime.fromisoformat()} and
@ref{a09,,datetime.time.fromisoformat()}. Patch by Semyon Moroz.

@item 
gh-125028@footnote{https://github.com/python/cpython/issues/125028}: @ref{4a5,,functools.Placeholder} cannot be passed to
@ref{4a6,,functools.partial()} as a keyword argument.

@item 
gh-125843@footnote{https://github.com/python/cpython/issues/125843}: If possible, indicate which @ref{2e,,curses} C function or macro
is responsible for raising a @ref{1a16,,curses.error} exception. Patch by
Bénédikt Tran.

@item 
gh-119109@footnote{https://github.com/python/cpython/issues/119109}: @ref{4a6,,functools.partial()} calls are now faster when keyword
arguments are used.

@item 
gh-124033@footnote{https://github.com/python/cpython/issues/124033}: @code{SimplePath} is now presented in
@code{importlib.metadata.__all__}.

@item 
gh-91216@footnote{https://github.com/python/cpython/issues/91216}: @code{importlib.metadata} now raises a @code{KeyError} instead of
returning @code{None} when a key is missing from the metadata.

@item 
gh-120492@footnote{https://github.com/python/cpython/issues/120492}: @code{importlib.metadata} now prioritizes valid dists to invalid
dists when retrieving by name.

@item 
gh-99631@footnote{https://github.com/python/cpython/issues/99631}: The @ref{cb,,shelve} module now accepts custom serialization and
deserialization functions.

@item 
gh-119186@footnote{https://github.com/python/cpython/issues/119186}: Slightly speed up @ref{8b9,,os.walk()} by calling
@ref{1a42,,os.path.join()} less often.

@item 
gh-120170@footnote{https://github.com/python/cpython/issues/120170}: Fix an issue in the @code{_pickle} extension module in which
importing @ref{98,,multiprocessing} could change how pickle identifies which
module an object belongs to, potentially breaking the unpickling of those
objects.

@item 
gh-118981@footnote{https://github.com/python/cpython/issues/118981}: Fix potential hang in @code{multiprocessing.popen_spawn_posix}
that can happen when the child proc dies early by closing the child fds
right away.

@item 
gh-105497@footnote{https://github.com/python/cpython/issues/105497}: Fix flag mask inversion when unnamed flags exist.

@item 
gh-99813@footnote{https://github.com/python/cpython/issues/99813}: @ref{d8,,ssl} now uses @code{SSL_sendfile} internally when it is
possible (see @ref{1a43,,OP_ENABLE_KTLS}). The function sends a file more
efficiently because it performs TLS encryption in the kernel to avoid
additional context switches. Patch by Illia Volochii.

@item 
gh-62824@footnote{https://github.com/python/cpython/issues/62824}: Fix aliases for @code{iso8859_8} encoding. Patch by Dave Goncalves.

@item 
gh-86155@footnote{https://github.com/python/cpython/issues/86155}: @ref{1a44,,html.parser.HTMLParser.close()} no longer loses data when
the @code{<script>} tag is not closed. Patch by Waylan Limberg.

@item 
gh-78319@footnote{https://github.com/python/cpython/issues/78319}: UTF8 support for the IMAP APPEND command has been made RFC
compliant.

@item 
gh-93334@footnote{https://github.com/python/cpython/issues/93334}: Reraise @ref{7df,,KeyError} as @ref{1be,,ModuleNotFoundError} when
@ref{13ba,,importlib.machinery.PathFinder.find_spec()} is called on a submodule
without importing the parent (and without a @code{path} argument).

@item 
gh-69426@footnote{https://github.com/python/cpython/issues/69426}: Fix @ref{c4d,,html.parser.HTMLParser} to not unescape character
entities in attribute values if they are followed by an ASCII alphanumeric
or an equals sign.

@item 
bpo-38735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38735}: Fix failure when importing a module from the root directory on
unix-like platforms with sys.pycache_prefix set.

@item 
bpo-45959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45959}: @ref{b3,,pprint} can now pretty-print dict views.

@item 
gh-84683@footnote{https://github.com/python/cpython/issues/84683}: @ref{13d,,zoneinfo}: Check in @code{<prefix>/share/zoneinfo} for data
files on Windows

@item 
bpo-43429@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43429}: The @ref{1a45,,size()} method of the @ref{23c,,mmap.mmap}
class now returns the size of an anonymous mapping on both Unix and
Windows. Previously, the size would be returned on Windows and an
@ref{53c,,OSError} would be raised on Unix. @ref{277,,ValueError} is now raised
instead of @code{OSError} when @code{trackfd=False}.

@item 
bpo-41839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41839}: Allow negative priority values from
@ref{14b5,,os.sched_get_priority_min()} and @ref{14b4,,os.sched_get_priority_max()}
functions.

@item 
bpo-28494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28494}: Improve Zip file validation false positive rate in
@ref{16cf,,zipfile.is_zipfile()}.
@end itemize

@node IDLE<5>,Documentation<7>,Library<15>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id75}@anchor{1a46}
@subsubsection IDLE



@itemize -

@item 
gh-96491@footnote{https://github.com/python/cpython/issues/96491}: Deduplicate version number in IDLE shell title bar after saving
to a file.

@item 
gh-139742@footnote{https://github.com/python/cpython/issues/139742}: Colorize t-string prefixes for template strings in IDLE, as
done for f-string prefixes.
@end itemize

@node Documentation<7>,Core and Builtins<15>,IDLE<5>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id76}@anchor{1a47}
@subsubsection Documentation



@itemize -

@item 
gh-136155@footnote{https://github.com/python/cpython/issues/136155}: We are now checking for fatal errors in EPUB builds in CI.

@item 
gh-135171@footnote{https://github.com/python/cpython/issues/135171}: Document that the @ref{6ce,,iterator} for the leftmost
@code{for} clause in the generator expression is created immediately.

@item 
bpo-45210@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45210}: Document that error indicator may be set in tp_dealloc, and how
to avoid clobbering it.
@end itemize

@node Core and Builtins<15>,Library<16>,Documentation<7>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id77}@anchor{1a48}
@subsubsection Core and Builtins



@itemize -

@item 
gh-140000@footnote{https://github.com/python/cpython/issues/140000}: Fix potential memory leak when a reference cycle exists between
an instance of @ref{52a,,typing.TypeAliasType}, @ref{294,,typing.TypeVar},
@ref{295,,typing.ParamSpec}, or @ref{293,,typing.TypeVarTuple} and its
@code{__name__} attribute. Patch by Mikhail Efimov.

@item 
gh-140009@footnote{https://github.com/python/cpython/issues/140009}: Improve performance of list extension by dictionary items.

@item 
gh-139988@footnote{https://github.com/python/cpython/issues/139988}: Fix a memory leak when failing to create a
@ref{341,,Union} type. Patch by Bénédikt Tran.

@item 
gh-139748@footnote{https://github.com/python/cpython/issues/139748}: Fix reference leaks in error branches of functions accepting
path strings or bytes such as @ref{1c8,,compile()} and @ref{17ff,,os.system()}. Patch
by Bénédikt Tran.

@item 
gh-139516@footnote{https://github.com/python/cpython/issues/139516}: Fix lambda colon erroneously start format spec in f-string in
tokenizer.

@item 
gh-63161@footnote{https://github.com/python/cpython/issues/63161}: Support non-UTF-8 shebang and comments in Python source files if
non-UTF-8 encoding is specified. Detect decoding error in comments for
default (UTF-8) encoding. Show the line and position of decoding error for
default encoding in a traceback. Show the line containing the coding
cookie when it conflicts with the BOM in a traceback.

@item 
gh-139116@footnote{https://github.com/python/cpython/issues/139116}: Prevent a deadlock when multiple threads start, stop and use
@ref{108,,tracemalloc} simultaneously.

@item 
gh-139275@footnote{https://github.com/python/cpython/issues/139275}: Fix compilation problems in @code{_remote_debugging_module.c} when
the system doesn’t have @code{process_vm_readv}. Patch by Pablo Galindo

@item 
gh-133059@footnote{https://github.com/python/cpython/issues/133059}: Increased the number of cached small positive integers from 256
to 1024.

@item 
gh-74857@footnote{https://github.com/python/cpython/issues/74857}: 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/}: Coerce the POSIX locale to a UTF-8 based locale.
Patch by Victor Stinner.
@end itemize

@node Library<16>,Core and Builtins<16>,Core and Builtins<15>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id78}@anchor{1a49}
@subsubsection Library



@itemize -

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make @ref{94,,mmap} thread-safe on the @ref{487,,free threaded} build.
@end itemize

@node Core and Builtins<16>,Library<17>,Library<16>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id79}@anchor{1a4a}
@subsubsection Core and Builtins



@itemize -

@item 
gh-138558@footnote{https://github.com/python/cpython/issues/138558}: Fix handling of unusual t-string annotations in annotationlib.
Patch by Dave Peck.

@item 
gh-134466@footnote{https://github.com/python/cpython/issues/134466}: Don’t run PyREPL in a degraded environment where setting
termios attributes is not allowed.

@item 
gh-138794@footnote{https://github.com/python/cpython/issues/138794}: When a new tracing function is registered with
@ref{805,,PyRefTracer_SetTracer()},  replacing the current a call to the
trace function will be made with the object set to `NULL' and `event'
set to @ref{1a4b,,PyRefTracer_TRACKER_REMOVED}. This will happen just before
the new function is registered. Patch by Pablo Galindo

@item 
gh-71810@footnote{https://github.com/python/cpython/issues/71810}: Raise @ref{c57,,OverflowError} for @code{(-1).to_bytes()} for signed
conversions when bytes count is zero.  Patch by Sergey B Kirpichev.

@item 
gh-138716@footnote{https://github.com/python/cpython/issues/138716}: Improve @ref{17e,,SyntaxError} message for @ref{d31,,assert} in
cases like @code{assert a := b}.

@item 
gh-105487@footnote{https://github.com/python/cpython/issues/105487}: Remove non-existent @ref{1a4c,,__copy__()},
@ref{1909,,__deepcopy__()}, and @ref{184e,,__bases__} from the
@ref{1935,,__dir__()} entries of @ref{bc7,,types.GenericAlias}.

@item 
gh-138192@footnote{https://github.com/python/cpython/issues/138192}: Fix @ref{28,,contextvars} initialization so that all
subinterpreters are assigned the @ref{1a4d,,MISSING} value.

@item 
gh-138479@footnote{https://github.com/python/cpython/issues/138479}: Fix a crash when a generic object’s @code{__typing_subst__}
returns an object that isn’t a @ref{1ce,,tuple}.

@item 
gh-138431@footnote{https://github.com/python/cpython/issues/138431}: Fix a bug in the JIT optimizer when round-tripping strings and
tuples.

@item 
gh-138378@footnote{https://github.com/python/cpython/issues/138378}: Move the globals-to-const JIT optimizer pass into to the main
JIT optimizer pass
@end itemize

@node Library<17>,Core and Builtins<17>,Core and Builtins<16>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id80}@anchor{1a4e}
@subsubsection Library



@itemize -

@item 
gh-138401@footnote{https://github.com/python/cpython/issues/138401}: Add missing validation of argument @code{count} in
@ref{ed3,,os.sendfile()} to be non-negative.
@end itemize

@node Core and Builtins<17>,Library<18>,Library<17>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id81}@anchor{1a4f}
@subsubsection Core and Builtins



@itemize -

@item 
gh-138372@footnote{https://github.com/python/cpython/issues/138372}: Fix @ref{44a,,SyntaxWarning} emitted for erroneous subscript
expressions involving @ref{1a50,,template string literals}. Patch
by Brian Schubert.

@item 
gh-138302@footnote{https://github.com/python/cpython/issues/138302}: @code{BINARY_OP} now specializes to @code{BINARY_OP_ADD_INT},
@code{BINARY_OP_SUBTRACT_INT} or @code{BINARY_OP_MULTIPLY_INT} if operands are
compact ints.

@item 
gh-138318@footnote{https://github.com/python/cpython/issues/138318}: The default REPL now avoids highlighting built-in names (for
instance @ref{42b,,set} or @ref{439,,format()}) when they are used as attribute
names (for instance in @code{value.set} or @code{text.format}).

@item 
gh-138349@footnote{https://github.com/python/cpython/issues/138349}: Fix crash in certain cases where a module contains both a
module-level annotation and a comprehension.

@item 
gh-69605@footnote{https://github.com/python/cpython/issues/69605}: Fix some standard library submodules missing from the
@ref{69d,,REPL} auto-completion of imports.

@item 
gh-61206@footnote{https://github.com/python/cpython/issues/61206}: @ref{13b,,zipimport} now supports zstandard compressed zip file
entries.
@end itemize

@node Library<18>,Core and Builtins<18>,Core and Builtins<17>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id82}@anchor{1a51}
@subsubsection Library



@itemize -

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make @code{cProfile} thread-safe on the @ref{487,,free threaded} build.
@end itemize

@node Core and Builtins<18>,Library<19>,Library<18>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id83}@anchor{1a52}
@subsubsection Core and Builtins



@itemize -

@item 
gh-137838@footnote{https://github.com/python/cpython/issues/137838}: Fix JIT trace buffer overrun by increasing possible exit stubs.
Patch by Donghee Na.

@item 
gh-71679@footnote{https://github.com/python/cpython/issues/71679}: Use the same quoting algorithm for the repr of bytearrays as for
bytes objects and strings – use double quotes for quoting if the
bytearray contains single quotes and does not contain double quotes.

@item 
gh-137384@footnote{https://github.com/python/cpython/issues/137384}: Fix a crash when using the @ref{11b,,warnings} module in a
finalizer at shutdown. Patch by Kumar Aditya.
@end itemize

@node Library<19>,Core and Builtins<19>,Core and Builtins<18>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id84}@anchor{1a53}
@subsubsection Library



@itemize -

@item 
gh-138004@footnote{https://github.com/python/cpython/issues/138004}: On Solaris/Illumos platforms, thread names are now encoded as
ASCII to avoid errors on systems (e.g. OpenIndiana) that don’t support
non-ASCII names.

@item 
gh-137976@footnote{https://github.com/python/cpython/issues/137976}: Removed @code{localtime} from the list of reported system
timezones.
@end itemize

@node Core and Builtins<19>,Library<20>,Library<19>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id85}@anchor{1a54}
@subsubsection Core and Builtins



@itemize -

@item 
gh-137992@footnote{https://github.com/python/cpython/issues/137992}: Ensure that  @ref{805,,PyRefTracer_SetTracer()} sync with all
existing threads when called to avoid races in the free threaded build.
Patch by Pablo Galindo

@item 
gh-137967@footnote{https://github.com/python/cpython/issues/137967}: Show error suggestions on nested attribute access. Patch by
Pablo Galindo

@item 
gh-137959@footnote{https://github.com/python/cpython/issues/137959}: Replace the shim code added to every piece of jitted code with
a single trampoline function.

@item 
gh-137883@footnote{https://github.com/python/cpython/issues/137883}: Fix runaway recursion when calling a function with keyword
arguments.

@item 
gh-137079@footnote{https://github.com/python/cpython/issues/137079}: Fix keyword typo recognition when parsing files. Patch by Pablo
Galindo.

@item 
gh-137728@footnote{https://github.com/python/cpython/issues/137728}: Fix the JIT’s handling of many local variables. This previously
caused a segfault.

@item 
gh-137716@footnote{https://github.com/python/cpython/issues/137716}: Fix double period in @ref{1a9,,AttributeError} message for invalid
mock assertions

@item 
gh-137433@footnote{https://github.com/python/cpython/issues/137433}: Fix a potential deadlock in the @ref{487,,free threading} build
when daemon threads enable or disable profiling or tracing while the main
thread is shutting down the interpreter.

@item 
gh-137576@footnote{https://github.com/python/cpython/issues/137576}: Fix for incorrect source code being shown in tracebacks from
the Basic REPL when 
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP} is given. Patch by Adam Hartz.

@item 
gh-37817@footnote{https://github.com/python/cpython/issues/37817}: Allow assignment to @ref{184e,,__bases__} of direct subclasses
of builtin classes.

@item 
gh-132732@footnote{https://github.com/python/cpython/issues/132732}: Optimize @code{_COMPARE_OP}, @code{_CONTAINS_OP},
@code{_UNARY_NEGATIVE}, @code{_UNARY_NOT}, and @code{_UNARY_INVERT} in JIT builds
with constant-loading uops (@code{_POP_TWO_LOAD_CONST_INLINE_BORROW} and
@code{_POP_TOP_LOAD_CONST_INLINE_BORROW}), and then remove both to reduce
instruction count.

@item 
gh-137400@footnote{https://github.com/python/cpython/issues/137400}: Fix a crash in the @ref{487,,free threading} build when disabling
profiling or tracing across all threads with
@ref{966,,PyEval_SetProfileAllThreads()} or
@ref{851,,PyEval_SetTraceAllThreads()} or their Python equivalents
@ref{8d8,,threading.settrace_all_threads()} and
@ref{8d9,,threading.setprofile_all_threads()}.

@item 
gh-133143@footnote{https://github.com/python/cpython/issues/133143}: Add @ref{26e,,sys.abi_info} object to make ABI information more
easily accessible.

@item 
gh-137400@footnote{https://github.com/python/cpython/issues/137400}: Fix a crash in the @ref{487,,free threading} build when disabling
profiling or tracing across all threads with
@ref{966,,PyEval_SetProfileAllThreads()} or
@ref{851,,PyEval_SetTraceAllThreads()} or their Python equivalents
@ref{8d8,,threading.settrace_all_threads()} and
@ref{8d9,,threading.setprofile_all_threads()}.

@item 
gh-120037@footnote{https://github.com/python/cpython/issues/120037}: Disable user site packages directory when a @code{._pth} file is
used, even if it contains @code{import site}.

@item 
gh-58124@footnote{https://github.com/python/cpython/issues/58124}: Fix name of the Python encoding in Unicode errors of the code
page codec: use «cp65000» and «cp65001» instead of «CP_UTF7» and «CP_UTF8»
which are not valid Python code names. Patch by Victor Stinner.

@item 
gh-136966@footnote{https://github.com/python/cpython/issues/136966}: The @ref{1bf,,object.__dict__} and @code{__weakref__}
descriptors now use a single descriptor instance per interpreter, shared
across all types that need them. This speeds up class creation, and helps
avoid reference cycles.

@item 
gh-137314@footnote{https://github.com/python/cpython/issues/137314}: Fixed a regression where raw f-strings incorrectly interpreted
escape sequences in format specifications. Raw f-strings now properly
preserve literal backslashes in format specs, matching the behavior from
Python 3.11. For example, @code{rf"@{obj:\xFF@}"} now correctly produces
@code{'\\xFF'} instead of @code{'ÿ'}. Patch by Pablo Galindo.

@item 
gh-137308@footnote{https://github.com/python/cpython/issues/137308}: A standalone docstring in a node body is optimized as a
@ref{427,,pass} statement to ensure that the node’s body is never empty.
There was a @ref{277,,ValueError} in @ref{1c8,,compile()} otherwise.

@item 
gh-137288@footnote{https://github.com/python/cpython/issues/137288}: Fix bug where some bytecode instructions of a boolean
expression are not associated with the correct exception handler.

@item 
gh-137291@footnote{https://github.com/python/cpython/issues/137291}: The perf profiler can now be used if a previous frame
evaluation API has been provided.

@item 
gh-134291@footnote{https://github.com/python/cpython/issues/134291}: Remove some newer macOS API usage from the JIT compiler in
order to restore compatibility with older OSX 10.15 deployment targets.

@item 
gh-88886@footnote{https://github.com/python/cpython/issues/88886}: The codecs lookup function now again performs only minimal
normalization of the encoding name before passing it to the search
functions: all ASCII letters are converted to lower case, spaces are
replaced with hyphens. This restores the pre-Python 3.9 behavior.

@item 
gh-131338@footnote{https://github.com/python/cpython/issues/131338}: Disable computed stack limit checks on non-glibc linux
platforms to fix crashes on deep recursion.

@item 
gh-136870@footnote{https://github.com/python/cpython/issues/136870}: Fix data races while de-instrumenting bytecode of code objects
running concurrently in threads.

@item 
gh-132732@footnote{https://github.com/python/cpython/issues/132732}: Optimize constant comparison for @code{_COMPARE_OP_INT},
@code{_COMPARE_OP_FLOAT} and @code{_COMPARE_OP_STR} in JIT builds

@item 
gh-127598@footnote{https://github.com/python/cpython/issues/127598}: Improve @ref{1be,,ModuleNotFoundError} by adding flavour text to
the exception when the @ref{1551,,-S} option is passed. Patch by Andrea
Mattei.

@item 
gh-136801@footnote{https://github.com/python/cpython/issues/136801}: Fix PyREPL syntax highlighting on match cases after multi-line
case. Contributed by Olga Matoula.

@item 
gh-74185@footnote{https://github.com/python/cpython/issues/74185}: The @ref{1bc,,__repr__()} of @ref{1bd,,ImportError} and
@ref{1be,,ModuleNotFoundError} now shows «name» and «path» as
@code{name=<name>} and @code{path=<path>} if they were given as keyword
arguments at construction time. Patch by Serhiy Storchaka, Oleg Iarygin,
and Yoav Nir
@end itemize

@node Library<20>,Core and Builtins<20>,Core and Builtins<19>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id86}@anchor{1a55}
@subsubsection Library



@itemize -

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make functions in @ref{e5,,syslog} thread-safe on the @ref{487,,free threaded} build.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make functions in @ref{ba,,pwd} thread-safe on the @ref{487,,free threaded} build.
@end itemize

@node Core and Builtins<20>,Library<21>,Library<20>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id87}@anchor{1a56}
@subsubsection Core and Builtins



@itemize -

@item 
gh-136616@footnote{https://github.com/python/cpython/issues/136616}: Improve @ref{17e,,SyntaxError} error messages for invalid
@ref{d31,,assert} usages.

@item 
gh-136599@footnote{https://github.com/python/cpython/issues/136599}: Improve performance of @ref{326,,int} hash calculations.
@end itemize

@node Library<21>,Core and Builtins<21>,Core and Builtins<20>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id88}@anchor{1a57}
@subsubsection Library



@itemize -

@item 
gh-136421@footnote{https://github.com/python/cpython/issues/136421}: Fix crash when initializing @ref{33,,datetime} concurrently.
@end itemize

@node Core and Builtins<21>,Library<22>,Library<21>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id89}@anchor{1a58}
@subsubsection Core and Builtins



@itemize -

@item 
gh-136541@footnote{https://github.com/python/cpython/issues/136541}: Fix some issues with the perf trampolines on x86-64 and
aarch64.  The trampolines were not being generated correctly for some
cases, which could lead to the perf integration not working correctly.
Patch by Pablo Galindo.
@end itemize

@node Library<22>,Core and Builtins<22>,Core and Builtins<21>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id90}@anchor{1a59}
@subsubsection Library



@itemize -

@item 
gh-107545@footnote{https://github.com/python/cpython/issues/107545}: Improve the error messages that may be raised by
@ref{1093,,setsockopt()}.
@end itemize

@node Core and Builtins<22>,Library<23>,Library<22>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id91}@anchor{1a5a}
@subsubsection Core and Builtins



@itemize -

@item 
gh-136517@footnote{https://github.com/python/cpython/issues/136517}: Fixed a typo that prevented printing of uncollectable objects
when the @ref{156b,,gc.DEBUG_UNCOLLECTABLE} mode was set.

@item 
gh-136525@footnote{https://github.com/python/cpython/issues/136525}: Fix issue where per-thread bytecode was not instrumented for
newly created threads.

@item 
gh-132657@footnote{https://github.com/python/cpython/issues/132657}: Improve performance of @ref{9d4,,frozenset} by removing locks in
the free-threading build.

@item 
gh-136459@footnote{https://github.com/python/cpython/issues/136459}: Add support for perf trampoline on macOS, to allow profilers
wit JIT map support to read Python calls. While profiling,
@code{PYTHONPERFSUPPORT=1} can be appended to enable the trampoline.

@item 
gh-132661@footnote{https://github.com/python/cpython/issues/132661}: @code{Interpolation.expression} now has a default, the empty
string.

@item 
gh-132661@footnote{https://github.com/python/cpython/issues/132661}: Reflect recent 
@geindex Python Enhancement Proposals; PEP 750
PEP 750@footnote{https://peps.python.org/pep-0750/} change.

Disallow concatenation of @code{string.templatelib.Template} and
@ref{1df,,str}. Also, disallow implicit concatenation of t-string literals
with string or f-string literals.

@item 
gh-91636@footnote{https://github.com/python/cpython/issues/91636}: While performing garbage collection, clear weakrefs to
unreachable objects that are created during running of finalizers.  If
those weakrefs were are not cleared, they could reveal unreachable
objects.

@item 
gh-136355@footnote{https://github.com/python/cpython/issues/136355}: Deprecate @ref{2ed,,-b} and @code{-bb} command line options
and schedule them to become no-op in Python 3.17.

@item 
gh-109700@footnote{https://github.com/python/cpython/issues/109700}: Fix memory error handling in @ref{7dc,,PyDict_SetDefault()}.

@item 
gh-135552@footnote{https://github.com/python/cpython/issues/135552}: Fix a bug caused by the garbage collector clearing weakrefs too
early.  The weakrefs in the @code{tp_subclasses} dictionary are needed in
order to correctly invalidate type caches (for example, by calling
@code{PyType_Modified()}). Clearing weakrefs before calling finalizers causes
the caches to not be correctly invalidated.  That can cause crashes since
the caches can refer to invalid objects.  Defer the clearing of weakrefs
without callbacks until after finalizers are executed.

@item 
gh-136203@footnote{https://github.com/python/cpython/issues/136203}: Improve @ref{291,,TypeError} error message, when richcomparing two
@ref{189,,types.MappingProxyType} objects.

@item 
gh-136003@footnote{https://github.com/python/cpython/issues/136003}: Fix @ref{420,,threading.Thread} objects becoming incorrectly
daemon when created from an @ref{d,,atexit} callback or a pending call
(@ref{d49,,Py_AddPendingCall()}).

@item 
gh-78465@footnote{https://github.com/python/cpython/issues/78465}: Fix error message for @code{cls.__new__(cls, ...)} where @code{cls} is
not instantiable builtin or extension type (with @code{tp_new} set to
@code{NULL}).

@item 
gh-135904@footnote{https://github.com/python/cpython/issues/135904}: Perform more aggressive control-flow optimizations on the
machine code templates emitted by the experimental JIT compiler.

@item 
gh-129958@footnote{https://github.com/python/cpython/issues/129958}: Differentiate between t-strings and f-strings in syntax error
for newlines in format specifiers of single-quoted interpolated strings.

@item 
gh-135871@footnote{https://github.com/python/cpython/issues/135871}: Non-blocking mutex lock attempts now return immediately when
the lock is busy instead of briefly spinning in the @ref{487,,free threading}
build.

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Specialize @ref{1a5b,,POP_TOP} in the JIT compiler by
specializing for reference lifetime and type. This will also enable easier
top of stack caching in the JIT compiler.

@item 
gh-135106@footnote{https://github.com/python/cpython/issues/135106}: Restrict the trashcan mechanism to GC’ed objects and untrack
them while in the trashcan to prevent the GC and trashcan mechanisms
conflicting.

@item 
gh-135379@footnote{https://github.com/python/cpython/issues/135379}: Changes specialization of @code{BINARY_OP} for ints to only
specialize for «compact» ints. This streamlines the fast path at the cost
of fewer specializations when very large integers are used.

@item 
gh-135607@footnote{https://github.com/python/cpython/issues/135607}: Fix potential @ref{11d,,weakref} races in an object’s destructor on
the @ref{487,,free threaded} build.

@item 
gh-135608@footnote{https://github.com/python/cpython/issues/135608}: Fix a crash in the JIT involving attributes of modules.

@item 
gh-82088@footnote{https://github.com/python/cpython/issues/82088}: Improve performance of @code{PyLongObject} conversion functions
@code{PyLong_AsLongAndOverflow()}, @code{PyLong_AsSsize_t()},
@code{PyLong_AsUnsignedLong()}, @code{PyLong_AsSize_t()},
@code{PyLong_AsUnsignedLongMask()}, @code{PyLong_AsUnsignedLongLongMask()},
@code{PyLong_AsLongLongAndOverflow()} for integers larger than 2**30 up to
30%.

@item 
gh-135551@footnote{https://github.com/python/cpython/issues/135551}: Sorting randomly ordered lists will often run a bit faster,
thanks to a new scheme for picking minimum run lengths from Stefan
Pochmann, which arranges for the merge tree to be as evenly balanced as is
possible.

@item 
gh-135543@footnote{https://github.com/python/cpython/issues/135543}: Emit @code{sys.remote_exec} audit event when
@ref{418,,sys.remote_exec()} is called and migrate @code{remote_debugger_script}
to @code{cpython.remote_debugger_script}.

@item 
gh-135496@footnote{https://github.com/python/cpython/issues/135496}: Fix typo in the f-string conversion type error («exclamanation»
-> «exclamation»).

@item 
gh-135474@footnote{https://github.com/python/cpython/issues/135474}: Specialize integer operations only on compact integers. This is
a CPython internal change.

@item 
gh-135371@footnote{https://github.com/python/cpython/issues/135371}: Fixed @ref{b,,asyncio} debugging tools to properly display
internal coroutine call stacks alongside external task dependencies. The
@code{python -m asyncio ps} and @code{python -m asyncio pstree} commands now
show complete execution context. Patch by Pablo Galindo.

@item 
gh-135422@footnote{https://github.com/python/cpython/issues/135422}: Fix regression in @ref{17e,,SyntaxError} messages after
gh-134036@footnote{https://github.com/python/cpython/issues/134036}.
@end itemize

@node Library<23>,Core and Builtins<23>,Core and Builtins<22>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id92}@anchor{1a5c}
@subsubsection Library



@itemize -

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make functions in @ref{69,,grp} thread-safe on the @ref{487,,free threaded} build.

@item 
gh-127319@footnote{https://github.com/python/cpython/issues/127319}: Set the @code{allow_reuse_port} class variable to @code{False} on the
XMLRPC, logging, and HTTP servers. This matches the behavior in prior
Python releases, which is to not allow port reuse.
@end itemize

@node Core and Builtins<23>,Library<24>,Library<23>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id93}@anchor{1a5d}
@subsubsection Core and Builtins



@itemize -

@item 
gh-130077@footnote{https://github.com/python/cpython/issues/130077}: Properly raise custom syntax errors when incorrect syntax
containing names that are prefixes of soft keywords is encountered.  Patch
by Pablo Galindo.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Optimize _CALL_LEN in the JIT when the length is known. Patch
by Tomas Roun

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Optimize @code{_UNARY_NEGATIVE} in JIT-compiled code.

@item 
gh-135148@footnote{https://github.com/python/cpython/issues/135148}: Fixed a bug where f-string debug expressions (using =) would
incorrectly strip out parts of strings containing escaped quotes and #
characters. Patch by Pablo Galindo.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Optimize @code{_UNARY_INVERT} in JIT-compiled code.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Optimize away @code{_CALL_TYPE_1} in the JIT when the return type
is known. Patch by Tomas Roun

@item 
gh-133136@footnote{https://github.com/python/cpython/issues/133136}: Limit excess memory usage in the @ref{487,,free threading} build
when a large dictionary or list is resized and accessed by multiple
threads.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Optimize @code{_CHECK_METHOD_VERSION} into
@code{_CHECK_FUNCTION_VERSION_INLINE} in JIT-compiled code.
@end itemize

@node Library<24>,Core and Builtins<24>,Core and Builtins<23>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id94}@anchor{1a5e}
@subsubsection Library



@itemize -

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make methods in @ref{6c,,heapq} thread-safe on the @ref{487,,free threaded} build.
@end itemize

@node Core and Builtins<24>,Library<25>,Library<24>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id95}@anchor{1a5f}
@subsubsection Core and Builtins



@itemize -

@item 
gh-134280@footnote{https://github.com/python/cpython/issues/134280}: Disable constant folding for @code{~} with a boolean argument.
This moves the deprecation warning from compile time to runtime.

@item 
gh-134876@footnote{https://github.com/python/cpython/issues/134876}: Add support to 
@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/} remote debugging for Linux kernels
which don’t have CONFIG_CROSS_MEMORY_ATTACH configured.

@item 
gh-134889@footnote{https://github.com/python/cpython/issues/134889}: Fix handling of a few opcodes that leave operands on the stack
when optimizing @code{LOAD_FAST}.
@end itemize

@node Library<25>,Core and Builtins<25>,Core and Builtins<24>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id96}@anchor{1a60}
@subsubsection Library



@itemize -

@item 
gh-134908@footnote{https://github.com/python/cpython/issues/134908}: Fix crash when iterating over lines in a text file on the
@ref{487,,free threaded} build.
@end itemize

@node Core and Builtins<25>,Library<26>,Library<25>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id97}@anchor{1a61}
@subsubsection Core and Builtins



@itemize -

@item 
gh-117852@footnote{https://github.com/python/cpython/issues/117852}: Fix argument checking of @ref{906,,athrow()}.

@item 
gh-132617@footnote{https://github.com/python/cpython/issues/132617}: Fix @ref{1807,,dict.update()} modification check that could
incorrectly raise a «dict mutated during update» error when a different
dictionary was modified that happens to share the same underlying keys
object.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Allow the JIT to remove unnecessary @code{_ITER_CHECK_TUPLE} ops.

@item 
gh-134679@footnote{https://github.com/python/cpython/issues/134679}: Fix crash in the @ref{487,,free threading} build’s QSBR code that
could occur when changing an object’s @code{__dict__} attribute.

@item 
gh-133912@footnote{https://github.com/python/cpython/issues/133912}: Fix the C API function @code{PyObject_GenericSetDict} to handle
extension classes with inline values.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Make the JIT optimizer understand that slicing a
string/list/tuple returns the same type.

@item 
gh-134584@footnote{https://github.com/python/cpython/issues/134584}: Add a reference count elimination pass to the JIT compiler.
Patch by Ken Jin.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Optimize @code{_POP_CALL_TWO_LOAD_CONST_INLINE_BORROW}.
@end itemize

@node Library<26>,Core and Builtins<26>,Core and Builtins<25>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id98}@anchor{1a62}
@subsubsection Library



@itemize -

@item 
gh-134381@footnote{https://github.com/python/cpython/issues/134381}: Fix @ref{30d,,RuntimeError} when using a not-started
@ref{420,,threading.Thread} after calling @ref{6bd,,os.fork()}
@end itemize

@node Core and Builtins<26>,Library<27>,Library<26>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id99}@anchor{1a63}
@subsubsection Core and Builtins



@itemize -

@item 
gh-127960@footnote{https://github.com/python/cpython/issues/127960}: PyREPL interactive shell no longer starts with @code{__package__}
and @code{__file__} global names set to @code{_pyrepl} package internals.
Contributed by Yuichiro Tachibana.

@item 
gh-130397@footnote{https://github.com/python/cpython/issues/130397}: Remove special-casing for C stack depth limits for WASI. Due to
WebAssembly’s built-in stack protection this does not pose a security
concern.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: JIT: replace @code{_LOAD_SMALL_INT} with
@code{_LOAD_CONST_INLINE_BORROW}

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Improve the JIT’s ability to optimize away cached class
attribute and method loads.

@item 
gh-128066@footnote{https://github.com/python/cpython/issues/128066}: Fixes an edge case where PyREPL improperly threw an error when
Python is invoked on a read only filesystem while trying to write history
file entries.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Improve the JIT’s ability to narrow unknown classes to constant
values.

@item 
gh-134268@footnote{https://github.com/python/cpython/issues/134268}: Add @code{_POP_CALL_TWO_LOAD_CONST_INLINE_BORROW} and use it to
further optimize @code{CALL_ISINSTANCE}.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Split @code{CALL_LIST_APPEND} into several uops. Patch by Diego
Russo.

@item 
gh-69605@footnote{https://github.com/python/cpython/issues/69605}: When auto-completing an import in the @ref{69d,,REPL}, finding no
candidates now issues no suggestion, rather than suggestions from the
current namespace.

@item 
gh-134170@footnote{https://github.com/python/cpython/issues/134170}: Add colorization to @ref{70c,,sys.unraisablehook()} by default.

@item 
gh-91153@footnote{https://github.com/python/cpython/issues/91153}: Fix a crash when a @ref{1c6,,bytearray} is concurrently mutated
during item assignment.

@item 
gh-134158@footnote{https://github.com/python/cpython/issues/134158}: Fix coloring of double braces in f-strings and t-strings in the
@ref{69d,,REPL}.

@item 
gh-134119@footnote{https://github.com/python/cpython/issues/134119}: Fix crash when calling @ref{bb5,,next()} on an exhausted template
string iterator. Patch by Jelle Zijlstra.

@item 
gh-134100@footnote{https://github.com/python/cpython/issues/134100}: Fix a use-after-free bug that occurs when an imported module
isn’t in @ref{19ba,,sys.modules} after its initial import. Patch by
Nico-Posada.

@item 
gh-134036@footnote{https://github.com/python/cpython/issues/134036}: Improve @ref{17e,,SyntaxError} message when using invalid
@ref{9e4,,raise} statements.

@item 
gh-133999@footnote{https://github.com/python/cpython/issues/133999}: Fix @ref{17e,,SyntaxError} regression in @ref{447,,except} parsing
after gh-123440@footnote{https://github.com/python/cpython/issues/123440}.

@item 
gh-133886@footnote{https://github.com/python/cpython/issues/133886}: Fix @ref{418,,sys.remote_exec()} for non-ASCII paths in non-UTF-8
locales and non-UTF-8 paths in UTF-8 locales.

@item 
gh-133400@footnote{https://github.com/python/cpython/issues/133400}: Fixed Ctrl+D (^D) behavior in _pyrepl module to match old
pre-3.13 REPL behavior.

@item 
gh-133703@footnote{https://github.com/python/cpython/issues/133703}: Fix hashtable in dict can be bigger than intended in some
situations.

@item 
gh-133778@footnote{https://github.com/python/cpython/issues/133778}: Fix bug where assigning to the @ref{1a64,,__annotations__}
attributes of classes defined under @code{from __future__ import annotations}
had no effect.

@item 
gh-133711@footnote{https://github.com/python/cpython/issues/133711}: Implement 
@geindex Python Enhancement Proposals; PEP 686
PEP 686@footnote{https://peps.python.org/pep-0686/}: Enable @ref{a46,,Python UTF-8 Mode} by default. Patch by Adam Turner.

@item 
gh-132762@footnote{https://github.com/python/cpython/issues/132762}: @ref{4da,,fromkeys()} no longer loops forever when adding a
small set of keys to a large base dict. Patch by Angela Liss.

@item 
gh-133541@footnote{https://github.com/python/cpython/issues/133541}: Inconsistent indentation in user input crashed the new REPL
when syntax highlighting was active. This is now fixed.

@item 
gh-133516@footnote{https://github.com/python/cpython/issues/133516}: Raise @ref{277,,ValueError} when constants @code{True}, @code{False} or
@code{None} are used as an identifier after NFKC normalization.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Allow the JIT to remove int guards after @code{_GET_LEN} by
setting the return type to int.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Split @code{CALL_ISINSTANCE} into several uops, allowing the JIT
to remove some of them.

@item 
gh-132554@footnote{https://github.com/python/cpython/issues/132554}: Change iteration to use «virtual iterators» for sequences.
Instead of creating an iterator, a tagged integer representing the next
index is pushed to the stack above the iterable. For non-sequence
iterators, @code{NULL} is pushed.

@item 
gh-130821@footnote{https://github.com/python/cpython/issues/130821}: Enhance wrong type error messages and make them more
consistent. Patch by Semyon Moroz.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Narrow the return type and constant-evaluate
@code{CALL_ISINSTANCE} for a subset of known values in the JIT. Patch by
Tomas Roun

@item 
gh-132542@footnote{https://github.com/python/cpython/issues/132542}: Update @ref{e02,,Thread.native_id}
after @code{fork(2)@footnote{https://manpages.debian.org/fork(2)}} to ensure accuracy. Patch by Noam Cohen.
@end itemize

@node Library<27>,Core and Builtins<27>,Core and Builtins<26>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id100}@anchor{1a65}
@subsubsection Library



@itemize -

@item 
gh-132732@footnote{https://github.com/python/cpython/issues/132732}: Automatically constant evaluate bytecode operations marked as
pure in the JIT optimizer.
@end itemize

@node Core and Builtins<27>,Library<28>,Library<27>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id101}@anchor{1a66}
@subsubsection Core and Builtins



@itemize -

@item 
gh-127971@footnote{https://github.com/python/cpython/issues/127971}: Fix off-by-one read beyond the end of a string in string
search.

@item 
gh-132042@footnote{https://github.com/python/cpython/issues/132042}: Improve class creation times by up to 12% by pre-computing type
slots just once. Patch by Sergey Miryanov.

@item 
gh-133379@footnote{https://github.com/python/cpython/issues/133379}: Correct usage of `arguments' in error messages.

@item 
gh-127266@footnote{https://github.com/python/cpython/issues/127266}: In the free-threaded build, avoid data races caused by updating
type slots or type flags after the type was initially created.  For those
(typically rare) cases, use the stop-the-world mechanism.  Remove the use
of atomics when reading or writing type flags.  The use of atomics is not
sufficient to avoid races (since flags are sometimes read without a lock
and without atomics) and are no longer required.

@item 
gh-130425@footnote{https://github.com/python/cpython/issues/130425}: Add @code{"Did you mean: 'attr'?"} suggestion when using @code{del
obj.attr} if @code{attr} does not exist.

@item 
gh-128640@footnote{https://github.com/python/cpython/issues/128640}: Fix a crash when using threads inside of a subinterpreter.
@end itemize

@node Library<28>,Core and Builtins<28>,Core and Builtins<27>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id102}@anchor{1a67}
@subsubsection Library



@itemize -

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make the module @ref{85,,json} safe to use under the
free-threading build.
@end itemize

@node Core and Builtins<28>,C API<8>,Library<28>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id103}@anchor{1a68}
@subsubsection Core and Builtins



@itemize -

@item 
gh-119494@footnote{https://github.com/python/cpython/issues/119494}: Exception text when trying to delete attributes of types was
clarified.
@end itemize

@node C API<8>,Build<7>,Core and Builtins<28>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id104}@anchor{1a69}
@subsubsection C API



@itemize -

@item 
gh-139924@footnote{https://github.com/python/cpython/issues/139924}: Function watchers can now receive a
PyFunction_PYFUNC_EVENT_MODIFY_QUALNAME event when a watched functions
qualname is changed.

@item 
gh-111489@footnote{https://github.com/python/cpython/issues/111489}: Add @ref{36a,,PyTuple_FromArray()} to create a @ref{1ce,,tuple} from
an array. Patch by Victor Stinner.

@item 
gh-136355@footnote{https://github.com/python/cpython/issues/136355}: Deprecate @ref{3c4,,PyConfig.bytes_warning} field and schedule
its removal in 3.17.

@item 
gh-138886@footnote{https://github.com/python/cpython/issues/138886}: Remove deprecated @code{PySys_ResetWarnOptions()} C-API
function.

@item 
gh-129813@footnote{https://github.com/python/cpython/issues/129813}: Implement 
@geindex Python Enhancement Proposals; PEP 782
PEP 782@footnote{https://peps.python.org/pep-0782/}, the @ref{3b4,,PyBytesWriter} API. Add
functions:


@itemize *

@item 
@ref{35c,,PyBytesWriter_Create()}

@item 
@ref{35d,,PyBytesWriter_Discard()}

@item 
@ref{35e,,PyBytesWriter_FinishWithPointer()}

@item 
@ref{35f,,PyBytesWriter_FinishWithSize()}

@item 
@ref{360,,PyBytesWriter_Finish()}

@item 
@ref{361,,PyBytesWriter_Format()}

@item 
@ref{362,,PyBytesWriter_GetData()}

@item 
@ref{363,,PyBytesWriter_GetSize()}

@item 
@ref{364,,PyBytesWriter_GrowAndUpdatePointer()}

@item 
@ref{365,,PyBytesWriter_Grow()}

@item 
@ref{366,,PyBytesWriter_Resize()}

@item 
@ref{367,,PyBytesWriter_WriteBytes()}
@end itemize

Patch by Victor Stinner.

@item 
gh-137956@footnote{https://github.com/python/cpython/issues/137956}: Display and raise an exception if an extension compiled for
non-free-threaded Python is loaded in a free-threaded interpreter.

@item 
gh-137573@footnote{https://github.com/python/cpython/issues/137573}: Mark @code{_PyOptimizer_Optimize} as @ref{1a6a,,Py_NO_INLINE} to
prevent stack overflow crashes on macOS.

@item 
gh-128813@footnote{https://github.com/python/cpython/issues/128813}: Functions @ref{3bd,,_Py_c_sum()}, @ref{3be,,_Py_c_diff()},
@ref{3bf,,_Py_c_neg()}, @ref{3c0,,_Py_c_prod()}, @ref{3c1,,_Py_c_quot()},
@ref{3c2,,_Py_c_pow()} and previously undocumented @ref{3c3,,_Py_c_abs()} are
@ref{1a7,,soft deprecated}. Deprecate also @ref{3b8,,cval}
field of the @ref{3b9,,PyComplexObject} type. Patch by Sergey B Kirpichev.

@item 
gh-137210@footnote{https://github.com/python/cpython/issues/137210}: Add API for checking an extension module’s ABI compatibility:
@ref{358,,Py_mod_abi}, @ref{359,,PyABIInfo_Check()}, @ref{35a,,PyABIInfo_VAR}
and @code{Py_mod_abi}.

@item 
gh-136759@footnote{https://github.com/python/cpython/issues/136759}: Rename @code{lock.h} to @code{pylock.h} to avoid potential include
conflicts.

@item 
gh-112068@footnote{https://github.com/python/cpython/issues/112068}: Revert support of nullable arguments in @ref{1a6b,,PyArg_Parse()}.

@item 
gh-136006@footnote{https://github.com/python/cpython/issues/136006}: On Solaris, the @code{Py_NAN} macro now expands to a
@code{double} instead of a function address. Patch by Bénédikt Tran.

@item 
gh-135075@footnote{https://github.com/python/cpython/issues/135075}: Make @ref{1927,,PyObject_SetAttr()} and
@ref{1a6c,,PyObject_SetAttrString()} fail if called with @code{NULL} value and an
exception set. Patch by Victor Stinner.

@item 
gh-135906@footnote{https://github.com/python/cpython/issues/135906}: Fix compilation errors when compiling the internal headers with
a C++ compiler.

@item 
gh-133296@footnote{https://github.com/python/cpython/issues/133296}: New variants for the critical section API that accept one or
two @ref{693,,PyMutex} pointers rather than @ref{19b,,PyObject} instances
are now public in the non-limited C API.

@item 
gh-133157@footnote{https://github.com/python/cpython/issues/133157}: Remove the private, undocumented macro
@code{_Py_NO_SANITIZE_UNDEFINED}.

@item 
gh-134989@footnote{https://github.com/python/cpython/issues/134989}: Fix @code{Py_RETURN_NONE}, @code{Py_RETURN_TRUE} and
@code{Py_RETURN_FALSE} macros in the limited C API 3.11 and older: don’t
treat @code{Py_None}, @code{Py_True} and @code{Py_False} as immortal. Patch by
Victor Stinner.

@item 
gh-134989@footnote{https://github.com/python/cpython/issues/134989}: Implement @ref{1a6d,,PyObject_DelAttr()} and
@ref{1a6e,,PyObject_DelAttrString()} as macros in the limited C API 3.12 and
older. Patch by Victor Stinner.

@item 
gh-134745@footnote{https://github.com/python/cpython/issues/134745}: Change @code{PyThread_allocate_lock()} implementation to
@code{PyMutex}. On Windows, @code{PyThread_acquire_lock_timed()} now
supports the `intr_flag' parameter: it can be interrupted. Patch by Victor
Stinner.

@item 
gh-134891@footnote{https://github.com/python/cpython/issues/134891}: Add @ref{357,,PyUnstable_Unicode_GET_CACHED_HASH} to get the
cached hash of a string.

@item 
gh-134009@footnote{https://github.com/python/cpython/issues/134009}: Expose @ref{676,,PyMutex_IsLocked()} as part of the public C API.

@item 
gh-134144@footnote{https://github.com/python/cpython/issues/134144}: Fix crash when calling @ref{1a6f,,Py_EndInterpreter()} with a
@ref{1a70,,thread state} that isn’t the initial thread for the interpreter.

@item 
gh-133968@footnote{https://github.com/python/cpython/issues/133968}: Add @ref{5e6,,PyUnicodeWriter_WriteASCII()} function to write an
ASCII string into a @ref{5e0,,PyUnicodeWriter}. The function is faster than
@ref{5ec,,PyUnicodeWriter_WriteUTF8()}, but has an undefined behavior if the
input string contains non-ASCII characters. Patch by Victor Stinner.

@item 
gh-133644@footnote{https://github.com/python/cpython/issues/133644}: Remove deprecated Python initialization getter functions
@code{Py_Get*}. Patch by Bénédikt Tran.

@item 
gh-133644@footnote{https://github.com/python/cpython/issues/133644}: Remove deprecated function @code{PyWeakref_GetObject()} and
macro @code{PyWeakref_GET_OBJECT}. Use @ref{3a4,,PyWeakref_GetRef()}
instead. Patch by Bénédikt Tran.

@item 
gh-133644@footnote{https://github.com/python/cpython/issues/133644}: Remove deprecated alias @code{PyImport_ImportModuleNoBlock()}
of @ref{3a3,,PyImport_ImportModule()}. Patch by Bénédikt Tran.

@item 
gh-133610@footnote{https://github.com/python/cpython/issues/133610}: Remove deprecated functions
@code{PyUnicode_AsDecodedObject()},
@code{PyUnicode_AsDecodedUnicode()},
@code{PyUnicode_AsEncodedObject()}, and
@code{PyUnicode_AsEncodedUnicode()}.

@item 
gh-132629@footnote{https://github.com/python/cpython/issues/132629}: For unsigned integer formats in @ref{3b1,,PyArg_ParseTuple()},
accepting Python integers with value that is larger than the maximal value
for the C type or less than the minimal value for the corresponding signed
integer type of the same size is now deprecated.

@item 
gh-131185@footnote{https://github.com/python/cpython/issues/131185}: @ref{1a5,,PyGILState_Ensure()} no longer crashes when called after
interpreter finalization.

@item 
gh-108512@footnote{https://github.com/python/cpython/issues/108512}: Add functions @ref{352,,PySys_GetAttr()},
@ref{353,,PySys_GetAttrString()}, @ref{354,,PySys_GetOptionalAttr()} and
@ref{355,,PySys_GetOptionalAttrString()}.
@end itemize

@node Build<7>,,C API<8>,Python 3 15 0 alpha 1
@anchor{whatsnew/changelog id105}@anchor{1a71}
@subsubsection Build



@itemize -

@item 
gh-138489@footnote{https://github.com/python/cpython/issues/138489}: When cross-compiling for WASI by @code{build_wasm} or
@code{build_emscripten}, the @code{build-details.json} step is now included in
the build process, just like with native builds.

This fixes the @code{libinstall} task which requires the
@code{build-details.json} file during the process.

@item 
gh-138497@footnote{https://github.com/python/cpython/issues/138497}: The LLVM version used by the JIT at build time can now be
modified using the @code{LLVM_VERSION} environment variable. Use this at your
own risk, as there is only one officially supported LLVM version. For more
information, please check @code{Tools/jit/README.md}.

@item 
gh-95952@footnote{https://github.com/python/cpython/issues/95952}: When cross-compiling for WASI, require that the HOSTRUNNER
environment variable be explicitly set.

This was needed as macOS lacks the appropriate CLI tools to set a
reasonable default.

@item 
gh-138061@footnote{https://github.com/python/cpython/issues/138061}: Ensure reproducible builds by making JIT stencil header
generation deterministic.

@item 
gh-128042@footnote{https://github.com/python/cpython/issues/128042}: @code{./configure} now warns when @code{--enable-optimizations} and
@code{CFLAGS=-O0} are both set, suggesting removing @code{-O0} from @code{CFLAGS}
for optimal performance.  Patch by Taegyun Kim.

@item 
gh-132339@footnote{https://github.com/python/cpython/issues/132339}: Add support for OpenSSL 3.5.

@item 
gh-135621@footnote{https://github.com/python/cpython/issues/135621}: PyREPL no longer depends on the @ref{2e,,curses} standard library.
Contributed by Łukasz Langa.

@item 
gh-135927@footnote{https://github.com/python/cpython/issues/135927}: Fix building with MSVC when passing option @code{/std:clatest}.

@item 
gh-119132@footnote{https://github.com/python/cpython/issues/119132}: Remove «experimental» tag from the CPython free-threading
build.

@item 
gh-135497@footnote{https://github.com/python/cpython/issues/135497}: Fix the detection of @code{MAXLOGNAME} in the @code{configure.ac}
script.

@item 
gh-134923@footnote{https://github.com/python/cpython/issues/134923}: Windows builds with profile-guided optimization enabled now use
@code{/GENPROFILE} and @code{/USEPROFILE} instead of deprecated @code{/LTCG:}
options.

@item 
gh-134632@footnote{https://github.com/python/cpython/issues/134632}: Fixed @code{build-details.json} generation to use @code{INCLUDEPY},
in order to reference the @code{pythonX.Y} subdirectory of the include
directory, as required in 
@geindex Python Enhancement Proposals; PEP 739
PEP 739@footnote{https://peps.python.org/pep-0739/}, instead of the top-level include
directory.

@item 
gh-134486@footnote{https://github.com/python/cpython/issues/134486}: The @ref{2d,,ctypes} module now performs a more portable test for
the definition of @code{alloca(3)@footnote{https://manpages.debian.org/alloca(3)}}, fixing a compilation failure on
NetBSD.

@item 
gh-134455@footnote{https://github.com/python/cpython/issues/134455}: Fixed @code{build-details.json} generation to use the correct
@code{c_api.headers} as defined in 
@geindex Python Enhancement Proposals; PEP 739
PEP 739@footnote{https://peps.python.org/pep-0739/}, instead of @code{c_api.include}.

@item 
gh-134273@footnote{https://github.com/python/cpython/issues/134273}: Add support for configuring compiler flags for the JIT with
@code{CFLAGS_JIT}

@item 
gh-115119@footnote{https://github.com/python/cpython/issues/115119}: Removed implicit fallback to the bundled copy of the
@code{libmpdec} library. Now this should be explicitly enabled via
@ref{3d6,,--with-system-libmpdec} set to @code{no} or
@code{--without-system-libmpdec}.  Patch by Sergey B Kirpichev.

@item 
gh-131769@footnote{https://github.com/python/cpython/issues/131769}: Fix detecting when the build Python in a cross-build is a
pydebug build.

@item 
gh-117088@footnote{https://github.com/python/cpython/issues/117088}: AIX linker don’t support -h option, so avoid it through
platform check

@item 
gh-123681@footnote{https://github.com/python/cpython/issues/123681}: Check the @code{strftime()} behavior at runtime instead of at the
compile time to support cross-compiling. Remove the internal macro
@code{_Py_NORMALIZE_CENTURY}.

@item 
gh-127545@footnote{https://github.com/python/cpython/issues/127545}: Fix crash when building on Linux/m68k.
@end itemize

@node Python 3 14 0 beta 1,Python 3 14 0 alpha 7,Python 3 15 0 alpha 1,Changelog
@anchor{whatsnew/changelog python-3-14-0-beta-1}@anchor{1a72}
@subsection Python 3.14.0 beta 1


`Release date: 2025-05-06'

@menu
* Windows: Windows<8>. 
* Tools/Demos: Tools/Demos<6>. 
* Tests: Tests<10>. 
* Security: Security<9>. 
* Library: Library<29>. 
* IDLE: IDLE<6>. 
* Documentation: Documentation<8>. 
* Core and Builtins: Core and Builtins<29>. 
* Library: Library<30>. 
* Core and Builtins: Core and Builtins<30>. 
* Library: Library<31>. 
* Core and Builtins: Core and Builtins<31>. 
* Library: Library<32>. 
* C API: C API<9>. 
* Build: Build<8>. 

@end menu

@node Windows<8>,Tools/Demos<6>,,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id106}@anchor{1a73}
@subsubsection Windows



@itemize -

@item 
gh-132930@footnote{https://github.com/python/cpython/issues/132930}: Marks the installer for Windows as deprecated and updates
documentation to cover the new Python install manager.

@item 
gh-127405@footnote{https://github.com/python/cpython/issues/127405}: Add @code{ABIFLAGS} to @ref{51e,,sysconfig.get_config_vars()} on
Windows. Patch by Xuehai Pan.
@end itemize

@node Tools/Demos<6>,Tests<10>,Windows<8>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id107}@anchor{1a74}
@subsubsection Tools/Demos



@itemize -

@item 
gh-130453@footnote{https://github.com/python/cpython/issues/130453}: Allow passing multiple keyword arguments with the same function
name in @code{pygettext}.

@item 
gh-130195@footnote{https://github.com/python/cpython/issues/130195}: Add warning messages when @code{pygettext} unimplemented
@code{-a/--extract-all} option is called.
@end itemize

@node Tests<10>,Security<9>,Tools/Demos<6>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id108}@anchor{1a75}
@subsubsection Tests



@itemize -

@item 
gh-133131@footnote{https://github.com/python/cpython/issues/133131}: The iOS testbed will now select the most recently released
«SE-class» device for testing if a device isn’t explicitly specified.

@item 
gh-91048@footnote{https://github.com/python/cpython/issues/91048}: Add ability to externally inspect all pending asyncio tasks,
even if no task is currently entered on the event loop.

@item 
gh-109981@footnote{https://github.com/python/cpython/issues/109981}: The test helper that counts the list of open file descriptors
now uses the optimised @code{/dev/fd} approach on all Apple platforms, not
just macOS. This avoids crashes caused by guarded file descriptors.

@item 
gh-132678@footnote{https://github.com/python/cpython/issues/132678}: Add @code{--prioritize} to @code{-m test}. This option allows the
user to specify which selected tests should execute first, even if the
order is otherwise randomized. This is particularly useful for tests that
run the longest.

@item 
gh-131290@footnote{https://github.com/python/cpython/issues/131290}: Tests in @code{Lib/test} can now be correctly executed as
standalone scripts.
@end itemize

@node Security<9>,Library<29>,Tests<10>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id109}@anchor{1a76}
@subsubsection Security



@itemize -

@item 
gh-115322@footnote{https://github.com/python/cpython/issues/115322}: The underlying extension modules behind @ref{c2,,readline}:,
@ref{df,,subprocess}, and @ref{2d,,ctypes} now raise audit events on previously
uncovered code paths that could lead to file system access related to C
function calling and external binary execution.  The
@code{ctypes.call_function} audit hook has also been fixed to use an unsigned
value for its @code{function pointer}.
@end itemize

@node Library<29>,IDLE<6>,Security<9>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id110}@anchor{1a77}
@subsubsection Library



@itemize -

@item 
gh-133490@footnote{https://github.com/python/cpython/issues/133490}: Add color support to PDB in remote mode.

@item 
gh-132493@footnote{https://github.com/python/cpython/issues/132493}: Avoid eagerly evaluating annotations in functions decorated
with @ref{159c,,reprlib.recursive_repr()}.

@item 
gh-130645@footnote{https://github.com/python/cpython/issues/130645}: Add color to stdlib argparse CLIs. Patch by Hugo van Kemenade.

@item 
gh-119180@footnote{https://github.com/python/cpython/issues/119180}: Make @ref{66c,,annotationlib.get_annotations()} succeed with the
@code{FORWARDREF} format if evaluating the annotations throws an exception
other than @ref{665,,NameError} or @ref{1a9,,AttributeError}.

@item 
gh-133351@footnote{https://github.com/python/cpython/issues/133351}: Fix remote PDB to correctly request tab completions for Python
expressions from the server when completing a continuation line of a
multi-line Python block.

@item 
gh-133367@footnote{https://github.com/python/cpython/issues/133367}: Add the @code{--feature-version}, @code{--optimize}, and
@code{--show-empty} options to the @ref{9,,ast} command-line interface. Patch
by Semyon Moroz.

@item 
gh-133363@footnote{https://github.com/python/cpython/issues/133363}: The @ref{1a78,,cmd.Cmd} class has been fixed to reliably call the
@code{completedefault} method whenever the @code{do_shell} method is not defined
and tab completion is requested for a line beginning with @code{!}.

@item 
gh-113081@footnote{https://github.com/python/cpython/issues/113081}: Highlight syntax on source code in @ref{aa,,pdb}.

@item 
gh-133349@footnote{https://github.com/python/cpython/issues/133349}: Introduced auto-indent in @ref{aa,,pdb} multi-line input.

@item 
gh-133306@footnote{https://github.com/python/cpython/issues/133306}: Use @code{\z} instead of @code{\Z} in @ref{1a79,,fnmatch.translate()} and
@ref{700,,glob.translate()}.

@item 
gh-133306@footnote{https://github.com/python/cpython/issues/133306}: Support @code{\z} as a synonym for @code{\Z} in @ref{c1,,regular expressions}.

@item 
gh-133300@footnote{https://github.com/python/cpython/issues/133300}: Make @ref{1dc,,argparse.ArgumentParser}’s @code{suggest_on_error} a
keyword-only parameter. Patch by Hugo van Kemenade.

@item 
gh-133290@footnote{https://github.com/python/cpython/issues/133290}: Fix attribute caching issue when setting
@ref{1a7a,,ctypes._Pointer._type_} in the undocumented and deprecated
@code{ctypes.SetPointerType()} function and the undocumented
@code{set_type()} method.

@item 
gh-133223@footnote{https://github.com/python/cpython/issues/133223}: When PDB is attached to a remote process, do a better job of
intercepting Ctrl+C and forwarding it to the remote process.

@item 
gh-133153@footnote{https://github.com/python/cpython/issues/133153}: Do not complete @ref{aa,,pdb} commands in @code{interact} mode of
@code{pdb}.

@item 
gh-133139@footnote{https://github.com/python/cpython/issues/133139}: Add the @ref{489,,curses.assume_default_colors()} function, a
refinement of the @ref{48a,,curses.use_default_colors()} function which allows
to change the color pair @code{0}.

@item 
gh-133089@footnote{https://github.com/python/cpython/issues/133089}: Use original timeout value for @ref{19ab,,subprocess.TimeoutExpired}
when the func @ref{f45,,subprocess.run()} is called with a timeout instead of
sometimes a confusing partial remaining time out value used internally on
the final @code{wait()}.

@item 
gh-133036@footnote{https://github.com/python/cpython/issues/133036}: @ref{32c,,codecs.open()} is now deprecated. Use @ref{32b,,open()}
instead. Contributed by Inada Naoki.

@item 
gh-132987@footnote{https://github.com/python/cpython/issues/132987}: Many builtin and extension functions which accept an unsigned
integer argument, now use @ref{43d,,__index__()} if available.

@item 
gh-124703@footnote{https://github.com/python/cpython/issues/124703}: Set return code to @code{1} when aborting process from @ref{aa,,pdb}.

@item 
gh-133005@footnote{https://github.com/python/cpython/issues/133005}: Support passing @code{preset} option to @ref{1228,,tarfile.open()} when
using @code{'w|xz'} mode.

@item 
gh-115032@footnote{https://github.com/python/cpython/issues/115032}: Support for custom logging handlers with the `strm' argument is
deprecated and scheduled for removal in Python 3.16. Define handlers with
the `stream' argument instead. Patch by Mariusz Felisiak.

@item 
gh-132991@footnote{https://github.com/python/cpython/issues/132991}: Add @code{socket.IP_FREEBIND} constant on Linux 2.4 and
later.

@item 
gh-132995@footnote{https://github.com/python/cpython/issues/132995}: Bump the version of pip bundled in ensurepip to version 25.1.1

@item 
gh-132933@footnote{https://github.com/python/cpython/issues/132933}: The zipapp module now applies the filter when creating the list
of files to add, rather than waiting until the file is being added to the
archive.

@item 
gh-121249@footnote{https://github.com/python/cpython/issues/121249}: Always support the float complex and double complex C types in the @ref{de,,struct} module.  Patch by Sergey B
Kirpichev.

@item 
gh-132915@footnote{https://github.com/python/cpython/issues/132915}: @ref{1962,,fcntl.fcntl()} and @ref{181d,,fcntl.ioctl()} can now detect a
buffer overflow and raise @ref{3ea,,SystemError}. The stack and memory can be
corrupted in such case, so treat this error as fatal.

@item 
gh-132017@footnote{https://github.com/python/cpython/issues/132017}: Fix error when @code{pyrepl} is suspended, then resumed and
terminated.

@item 
gh-132893@footnote{https://github.com/python/cpython/issues/132893}: Improved @ref{1a7b,,statistics.NormalDist.cdf()} accuracy for inputs
smaller than the mean.

@item 
gh-130328@footnote{https://github.com/python/cpython/issues/130328}: Speedup pasting in @code{PyREPL} on Windows. Fix by Chris Eibl.

@item 
gh-132882@footnote{https://github.com/python/cpython/issues/132882}: Fix copying of @ref{341,,typing.Union} objects containing objects
that do not support the @code{|} operator.

@item 
gh-93696@footnote{https://github.com/python/cpython/issues/93696}: Fixed the breakpoint display error for frozen modules in
@ref{aa,,pdb}.

@item 
gh-129965@footnote{https://github.com/python/cpython/issues/129965}: Add MIME types for @code{.7z}, @code{.apk}, @code{.deb}, @code{.glb},
@code{.gltf}, @code{.gz}, @code{.m4v}, @code{.php}, @code{.rar}, @code{.rpm}, @code{.stl} and
@code{.wmv}. Patch by Hugo van Kemenade.

@item 
gh-132742@footnote{https://github.com/python/cpython/issues/132742}: @ref{1962,,fcntl.fcntl()} now supports arbitrary @ref{436,,bytes-like objects}, not only @ref{1c7,,bytes}. @ref{181d,,fcntl.ioctl()}
now automatically retries system calls failing with EINTR and releases the
GIL during a system call even for large bytes-like object.

@item 
gh-132451@footnote{https://github.com/python/cpython/issues/132451}: The CLI for the PDB debugger now accepts a @code{-p PID} argument
to allow attaching to a running process. The process must be running the
same version of Python as the one running PDB.

@item 
gh-125618@footnote{https://github.com/python/cpython/issues/125618}: Add a `format' parameter to
@ref{150,,annotationlib.ForwardRef.evaluate()}. Evaluating annotations in the
@code{FORWARDREF} format now succeeds in more cases that would previously
have raised an exception.

@item 
gh-132805@footnote{https://github.com/python/cpython/issues/132805}: Fix incorrect handling of nested non-constant values in the
FORWARDREF format in @ref{6,,annotationlib}.

@item 
gh-132734@footnote{https://github.com/python/cpython/issues/132734}: Add new constants for Bluetooth @ref{d4,,sockets}.

@item 
gh-132673@footnote{https://github.com/python/cpython/issues/132673}: Fix @ref{a97,,AssertionError} raised on @ref{47c,,ctypes.Structure}
with @code{_align_ = 0} and @code{_fields_ = []}.

@item 
gh-132578@footnote{https://github.com/python/cpython/issues/132578}: Rename the @code{threading.Thread._handle} field to avoid
shadowing methods defined on subclasses of @code{threading.Thread}.

@item 
gh-132561@footnote{https://github.com/python/cpython/issues/132561}: Fix the public @code{locked} method of @code{multiprocessing.SemLock}
class. Also adding 2 tests for the derivated @ref{1a7c,,multiprocessing.Lock}
and @ref{1a7d,,multiprocessing.RLock} classes.

@item 
gh-121468@footnote{https://github.com/python/cpython/issues/121468}: Add @ref{501,,pdb.set_trace_async()} function to support
@ref{432,,await} statements in @ref{aa,,pdb}.

@item 
gh-132493@footnote{https://github.com/python/cpython/issues/132493}: @ref{76c,,typing.Protocol} now uses
@ref{66c,,annotationlib.get_annotations()} when checking whether or not an
instance implements the protocol with @ref{2ef,,isinstance()}. This enables
support for @code{isinstance} checks against classes with deferred
annotations.

@item 
gh-132536@footnote{https://github.com/python/cpython/issues/132536}: Do not disable @ref{271,,PY_THROW} event in @ref{10,,bdb}
because it can’t be disabled.

@item 
gh-132527@footnote{https://github.com/python/cpython/issues/132527}: Include the valid typecode “w” in the error message when an
invalid typecode is passed to @ref{6c5,,array.array}.

@item 
gh-132099@footnote{https://github.com/python/cpython/issues/132099}: The Bluetooth socket with the @ref{509,,BTPROTO_HCI}
protocol on Linux now accepts an address in the format of an integer
@code{device_id}, not only a tuple  @code{(device_id,)}.

@item 
gh-81793@footnote{https://github.com/python/cpython/issues/81793}: Fix @ref{149b,,os.link()} on platforms (like Linux) where the system
@code{link()} function does not follow symlinks. On Linux, it now
follows symlinks by default or if @code{follow_symlinks=True} is specified.
On Windows, it now raises an error if @code{follow_symlinks=True} is passed.
On macOS, it now raises an error if @code{follow_symlinks=False} is passed
and the system @code{linkat()} function is not available at runtime.

@item 
gh-132493@footnote{https://github.com/python/cpython/issues/132493}: Support creation of @ref{76c,,typing.Protocol} classes with
annotations that cannot be resolved at class creation time.

@item 
gh-132491@footnote{https://github.com/python/cpython/issues/132491}: Rename @code{annotationlib.value_to_string} to
@ref{1a7e,,annotationlib.type_repr()} and provide better handling for function
objects.

@item 
gh-132426@footnote{https://github.com/python/cpython/issues/132426}: Add @ref{66e,,annotationlib.get_annotate_from_class_namespace()} as
a helper for accessing annotations in metaclasses, and remove
@code{annotationlib.get_annotate_function}.

@item 
gh-70145@footnote{https://github.com/python/cpython/issues/70145}: Add support for channels in Bluetooth HCI protocol
(@ref{509,,BTPROTO_HCI}).

@item 
gh-131913@footnote{https://github.com/python/cpython/issues/131913}: Add a shortcut function
@ref{4dd,,multiprocessing.Process.interrupt()} alongside the existing
@ref{1a7f,,multiprocessing.Process.terminate()} and
@ref{f15,,multiprocessing.Process.kill()} for an improved control over child
process termination.

@item 
gh-132439@footnote{https://github.com/python/cpython/issues/132439}: Fix @code{PyREPL} on Windows: characters entered via AltGr are
swallowed. Patch by Chris Eibl.

@item 
gh-132429@footnote{https://github.com/python/cpython/issues/132429}: Fix support of Bluetooth sockets on NetBSD and DragonFly BSD.
Add support for `cid' and `bdaddr_type' in the BTPROTO_L2CAP address on
FreeBSD. Return `cid' in @code{getsockname()} for BTPROTO_L2CAP if it is not
zero.

@item 
gh-132106@footnote{https://github.com/python/cpython/issues/132106}: @ref{4d0,,QueueListener.start} now raises a @ref{30d,,RuntimeError}
if the listener is already started.

@item 
gh-132417@footnote{https://github.com/python/cpython/issues/132417}: Fix a @code{NULL} pointer dereference when a C function called
using @ref{2d,,ctypes} with @code{restype} @ref{486,,py_object} returns
@code{NULL}.

@item 
gh-132385@footnote{https://github.com/python/cpython/issues/132385}: Fix instance error suggestions trigger potential exceptions in
@ref{8e3,,object.__getattr__()} in @ref{107,,traceback}.

@item 
gh-125866@footnote{https://github.com/python/cpython/issues/125866}: Add optional `add_scheme' argument to
@ref{53b,,urllib.request.pathname2url()}; when set to true, a complete URL is
returned. Likewise add optional `require_scheme' argument to
@ref{539,,url2pathname()}; when set to true, a complete URL is
accepted.

@item 
gh-132308@footnote{https://github.com/python/cpython/issues/132308}: A @ref{764,,traceback.TracebackException} now correctly renders
the @code{__context__} and @code{__cause__} attributes from @ref{1a80,,falsey} @ref{d9e,,Exception}, and the @code{exceptions} attribute from falsey
@ref{6d8,,ExceptionGroup}.

@item 
gh-130645@footnote{https://github.com/python/cpython/issues/130645}: Add colour to @ref{7,,argparse} help output. Patch by Hugo van
Kemenade.

@item 
gh-127495@footnote{https://github.com/python/cpython/issues/127495}: In PyREPL, append a new entry to the @code{PYTHON_HISTORY} file
`after' every statement.  This should preserve command-line history after
interpreter is terminated.  Patch by Sergey B Kirpichev.

@item 
gh-129463@footnote{https://github.com/python/cpython/issues/129463}: Comparison of @ref{1967,,annotationlib.ForwardRef} objects no
longer uses the internal @code{__code__} and @code{__ast_node__} attributes,
which are used as caches.

@item 
gh-132250@footnote{https://github.com/python/cpython/issues/132250}: Fixed the @ref{3ea,,SystemError} in @code{cProfile} when locating
the actual C function of a method raises an exception.

@item 
gh-132064@footnote{https://github.com/python/cpython/issues/132064}: @ref{66c,,annotationlib.get_annotations()} now uses the
@code{__annotate__} attribute if it is present, even if @code{__annotations__}
is not present. Additionally, the function now raises a
@ref{291,,TypeError} if it is passed an object that does not have any
annotatins.

@item 
gh-130664@footnote{https://github.com/python/cpython/issues/130664}: Support the @code{'_'} digit separator in formatting of the
integral part of @ref{1c2,,Decimal}’s.  Patch by Sergey B
Kirpichev.

@item 
gh-131952@footnote{https://github.com/python/cpython/issues/131952}: Add color output to the @code{json} CLI. Patch by Tomas
Roun.

@item 
gh-132063@footnote{https://github.com/python/cpython/issues/132063}: Prevent exceptions that evaluate as falsey (namely, when their
@code{__bool__} method returns @code{False} or their @code{__len__} method returns
0) from being ignored by @ref{206,,concurrent.futures.ProcessPoolExecutor}
and @ref{b27,,concurrent.futures.ThreadPoolExecutor}.

@item 
gh-132106@footnote{https://github.com/python/cpython/issues/132106}: @ref{4cf,,logging.handlers.QueueListener} now implements the
context manager protocol, allowing it to be used in a @ref{20a,,with}
statement.

@item 
gh-132054@footnote{https://github.com/python/cpython/issues/132054}: The @code{application/yaml} mime type (
@geindex RFC; RFC 9512
RFC 9512@footnote{https://datatracker.ietf.org/doc/html/rfc9512.html}) is now
supported by @ref{93,,mimetypes}. Patch by Sasha «Nelie» Chernykh and Hugo
van Kemenade.

@item 
gh-119605@footnote{https://github.com/python/cpython/issues/119605}: Respect @code{follow_wrapped} for @code{__init__()} and
@code{__new__()} methods when getting the class signature for a class with
@ref{4bd,,inspect.signature()}. Preserve class signature after wrapping with
@ref{695,,warnings.deprecated()}. Patch by Xuehai Pan.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve import times by up to 33x for the @ref{cc,,shlex} module,
and improve the performance of @ref{781,,shlex.quote()} by up to 12x. Patch by
Adam Turner.

@item 
gh-85302@footnote{https://github.com/python/cpython/issues/85302}: Add support for @ref{50a,,BTPROTO_SCO} in sockets on
FreeBSD.

@item 
gh-131757@footnote{https://github.com/python/cpython/issues/131757}: Make @ref{db3,,functools.lru_cache()} call the cached function
unlocked to allow concurrency.

@item 
gh-131423@footnote{https://github.com/python/cpython/issues/131423}: @ref{d8,,ssl} can show descriptions for errors added in OpenSSL
3.4.1. Patch by Bénédikt Tran.

@item 
gh-131434@footnote{https://github.com/python/cpython/issues/131434}: Improve error reporting for incorrect format in
@ref{17cf,,time.strptime()}.

@item 
gh-131524@footnote{https://github.com/python/cpython/issues/131524}: Add help message to @ref{af,,platform} command-line interface.
Contributed by Harry Lees.

@item 
gh-100926@footnote{https://github.com/python/cpython/issues/100926}: Move @ref{484,,ctypes.POINTER()} types cache from a global internal
cache (@code{_pointer_type_cache}) to the
@ref{485,,ctypes._CData.__pointer_type__} attribute of the corresponding
@ref{2d,,ctypes} types. This will stop the cache from growing without limits
in some situations.

@item 
gh-85702@footnote{https://github.com/python/cpython/issues/85702}: If @code{zoneinfo._common.load_tzdata} is given a package without a
resource a @code{ZoneInfoNotFoundError} is raised rather than a
@ref{1401,,IsADirectoryError}.

@item 
gh-123471@footnote{https://github.com/python/cpython/issues/123471}: Make concurrent iterations over @ref{1a81,,itertools.repeat} safe
under free-threading.

@item 
gh-131127@footnote{https://github.com/python/cpython/issues/131127}: Systems using LibreSSL now successfully build.

@item 
gh-89157@footnote{https://github.com/python/cpython/issues/89157}: Make the pure Python implementation of
@ref{a08,,datetime.date.fromisoformat()}, only accept ASCII strings for
consistency with the C implementation.

@item 
gh-130941@footnote{https://github.com/python/cpython/issues/130941}: Fix @ref{6e4,,configparser.ConfigParser} parsing empty
interpolation with @code{allow_no_value} set to @code{True}.

@item 
gh-110067@footnote{https://github.com/python/cpython/issues/110067}: Make @ref{6c,,heapq} max-heap functions @ref{4af,,heapq.heapify_max()},
@ref{4b0,,heapq.heappush_max()}, @ref{4b1,,heapq.heappop_max()}, and
@ref{4b2,,heapq.heapreplace_max()} public. Previous underscored naming is kept
for backwards compatibility. Additionally, the missing function
@ref{4b3,,heapq.heappushpop_max()} has been added to both the C and Python
implementations.

@item 
gh-129098@footnote{https://github.com/python/cpython/issues/129098}: Fix REPL traceback reporting when using @ref{1c8,,compile()} with an
inexisting file. Patch by Bénédikt Tran.

@item 
gh-130631@footnote{https://github.com/python/cpython/issues/130631}: @code{http.cookiejar.join_header_words()} is now more similar
to the original Perl version. It now quotes the same set of characters and
always quote values that end with @code{"\n"}.

@item 
gh-130482@footnote{https://github.com/python/cpython/issues/130482}: Add ability to specify name for @code{tkinter.OptionMenu}
and @code{tkinter.ttk.OptionMenu}.

@item 
gh-77065@footnote{https://github.com/python/cpython/issues/77065}: Add keyword-only optional argument `echo_char' for
@ref{4ab,,getpass.getpass()} for optional visual keyboard feedback support.
Patch by Semyon Moroz.

@item 
gh-130317@footnote{https://github.com/python/cpython/issues/130317}: Fix @ref{b47,,PyFloat_Pack2()} and @ref{b4a,,PyFloat_Unpack2()} for
NaN’s with payload.  This corrects round-trip for @ref{1a82,,struct.unpack()}
and @ref{161b,,struct.pack()} in case of the IEEE 754 binary16 «half precision»
type. Patch by Sergey B Kirpichev.

@item 
gh-130402@footnote{https://github.com/python/cpython/issues/130402}: Joining running daemon threads during interpreter shutdown now
raises @ref{68a,,PythonFinalizationError}.

@item 
gh-130167@footnote{https://github.com/python/cpython/issues/130167}: Improve speed of @ref{552,,difflib.IS_LINE_JUNK()}. Patch by Semyon
Moroz.

@item 
gh-101410@footnote{https://github.com/python/cpython/issues/101410}: Added more detailed messages for domain errors in the
@ref{91,,math} module.

@item 
gh-128384@footnote{https://github.com/python/cpython/issues/128384}: Make @ref{423,,warnings.catch_warnings} use a context variable
for holding the warning filtering state if the
@ref{42f,,sys.flags.context_aware_warnings} flag is set to true.  This makes
using the context manager thread-safe in multi-threaded programs.  The
flag is true by default in free-threaded builds and is otherwise false.
The value of the flag can be overridden by the @ref{178,,-X context_aware_warnings} command-line option or by the
@geindex PYTHON_CONTEXT_AWARE_WARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHON_CONTEXT_AWARE_WARNINGS
@ref{1a83,,PYTHON_CONTEXT_AWARE_WARNINGS} environment variable.

@item 
gh-129719@footnote{https://github.com/python/cpython/issues/129719}: Fix missing @code{socket.CAN_RAW_ERR_FILTER} constant in the
socket module on Linux systems. It was missing since Python 3.11.

@item 
gh-129027@footnote{https://github.com/python/cpython/issues/129027}: Raise @ref{2c9,,DeprecationWarning} for
@ref{344,,sys._clear_type_cache()}. This function was deprecated in Python 3.13
but it didn’t raise a runtime warning.

@item 
gh-128307@footnote{https://github.com/python/cpython/issues/128307}: Add @code{eager_start} keyword argument to
@ref{463,,asyncio.loop.create_task()}

@item 
gh-127604@footnote{https://github.com/python/cpython/issues/127604}: Add support for printing the C stack trace on systems that
support it via @ref{49f,,faulthandler.dump_c_stack()} or via the `c_stack'
argument in @ref{219,,faulthandler.enable()}.

@item 
gh-127385@footnote{https://github.com/python/cpython/issues/127385}: Add the @code{F_DUPFD_QUERY} constant to the @ref{5c,,fcntl} module.

@item 
gh-126838@footnote{https://github.com/python/cpython/issues/126838}: Add `resolve_host' keyword-only parameter to
@ref{539,,urllib.request.url2pathname()}, and fix handling of file URLs with
authorities.

@item 
gh-82129@footnote{https://github.com/python/cpython/issues/82129}: Fix @ref{665,,NameError} when calling @ref{a9e,,typing.get_type_hints()}
on a @ref{6e6,,dataclasses.dataclass()} created by
@ref{1a84,,dataclasses.make_dataclass()} with un-annotated fields.

@item 
gh-122559@footnote{https://github.com/python/cpython/issues/122559}: Remove @code{__reduce__()} and @code{__reduce_ex__()} methods
that always raise @ref{291,,TypeError} in the C implementation of
@ref{16b4,,io.FileIO}, @ref{15b5,,io.BufferedReader}, @ref{1754,,io.BufferedWriter}
and @ref{1755,,io.BufferedRandom} and replace them with default
@code{__getstate__()} methods that raise @code{TypeError}. This restores
fine details of behavior of Python 3.11 and older versions.

@item 
gh-122179@footnote{https://github.com/python/cpython/issues/122179}: @ref{a33,,hashlib.file_digest()} now raises @ref{4c3,,BlockingIOError}
when no data is available during non-blocking I/O. Before, it added
spurious null bytes to the digest.

@item 
gh-53032@footnote{https://github.com/python/cpython/issues/53032}: Expose @ref{491,,decimal.IEEEContext()} to support creation of
contexts corresponding to the IEEE 754 (2008) decimal interchange formats.
Patch by Sergey B Kirpichev.

@item 
gh-120220@footnote{https://github.com/python/cpython/issues/120220}: Deprecate the @code{tkinter.Variable} methods
@code{trace_variable()}, @code{trace_vdelete()} and @code{trace_vinfo()}.
Methods @code{trace_add()}, @code{trace_remove()} and @code{trace_info()}
can be used instead.

@item 
gh-113539@footnote{https://github.com/python/cpython/issues/113539}: @ref{11e,,webbrowser}: Names in the 
@geindex BROWSER
@geindex μεταβλητή περιβάλλοντος; BROWSER
@code{BROWSER} environment
variable can now refer to already registered web browsers, instead of
always generating a new browser command.

This makes it possible to set 
@geindex BROWSER
@geindex μεταβλητή περιβάλλοντος; BROWSER
@code{BROWSER} to the value of one of the
supported browsers on macOS.

@item 
bpo-44172@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44172}: Keep a reference to original @ref{2e,,curses} windows in
subwindows so that the original window does not get deleted before
subwindows.

@item 
gh-75223@footnote{https://github.com/python/cpython/issues/75223}: Deprecate undotted extensions in
@ref{30c,,mimetypes.MimeTypes.add_type()}. Patch by Hugo van Kemenade.
@end itemize

@node IDLE<6>,Documentation<8>,Library<29>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id111}@anchor{1a85}
@subsubsection IDLE



@itemize -

@item 
gh-112936@footnote{https://github.com/python/cpython/issues/112936}: fix IDLE: no Shell menu item in single-process mode.
@end itemize

@node Documentation<8>,Core and Builtins<29>,IDLE<6>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id112}@anchor{1a86}
@subsubsection Documentation



@itemize -

@item 
gh-107006@footnote{https://github.com/python/cpython/issues/107006}: Move documentation and example code for
@ref{1a87,,threading.local} from its docstring to the official docs.

@item 
gh-125142@footnote{https://github.com/python/cpython/issues/125142}: As part of the builtin help intro text, show the keyboard
shortcuts for the new, non-basic REPL (F1, F2, and F3).
@end itemize

@node Core and Builtins<29>,Library<30>,Documentation<8>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id113}@anchor{1a88}
@subsubsection Core and Builtins



@itemize -

@item 
gh-133336@footnote{https://github.com/python/cpython/issues/133336}: @code{-J} is no longer reserved for use by Jython. Patch by
Adam Turner.

@item 
gh-133261@footnote{https://github.com/python/cpython/issues/133261}: Fix bug where the cycle GC could untrack objects in the
trashcan because they looked like they were immortal. When objects are
added to the trashcan, we take care to ensure they keep a mortal reference
count.

@item 
gh-133346@footnote{https://github.com/python/cpython/issues/133346}: Added experimental color theming support to the @code{_colorize}
module.

@item 
gh-132917@footnote{https://github.com/python/cpython/issues/132917}: For the free-threaded build, check the process memory usage
increase before triggering a full automatic garbage collection.  If the
memory used has not increased 10% since the last collection then defer it.

@item 
gh-91048@footnote{https://github.com/python/cpython/issues/91048}: Add a new @code{python -m asyncio ps PID} command-line interface to
inspect asyncio tasks in a running Python process. Displays a flat table
of await relationships. A variant showing a tree view is also available as
@code{python -m asyncio pstree PID}. Both are useful for debugging async
code. Patch by Pablo Galindo, Łukasz Langa, Yury Selivanov, and Marta
Gomez Macias.

@item 
gh-133304@footnote{https://github.com/python/cpython/issues/133304}: Workaround NaN’s «canonicalization» in @ref{b48,,PyFloat_Pack4()}
and @ref{b4b,,PyFloat_Unpack4()} on RISC-V.

@item 
gh-133197@footnote{https://github.com/python/cpython/issues/133197}: Improve @ref{17e,,SyntaxError} error messages for incompatible
string / bytes prefixes.

@item 
gh-133231@footnote{https://github.com/python/cpython/issues/133231}: Add new utilities of observing JIT compilation:
@ref{662,,sys._jit.is_available()}, @ref{663,,sys._jit.is_enabled()}, and
@ref{1a89,,sys._jit.is_active()}.
@end itemize

@node Library<30>,Core and Builtins<30>,Core and Builtins<29>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id114}@anchor{1a8a}
@subsubsection Library



@itemize -

@item 
gh-133194@footnote{https://github.com/python/cpython/issues/133194}: @ref{1c9,,ast.parse()} will no longer parse new 
@geindex Python Enhancement Proposals; PEP 758
PEP 758@footnote{https://peps.python.org/pep-0758/} syntax
with older `feature_version' passed.
@end itemize

@node Core and Builtins<30>,Library<31>,Library<30>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id115}@anchor{1a8b}
@subsubsection Core and Builtins



@itemize -

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Split @code{CALL_LEN} into several uops allowing the JIT to remove
them when optimizing. Patch by Diego Russo.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Use @code{sym_new_type} instead of @code{sym_new_not_null} for
_BUILD_STRING, _BUILD_SET

@item 
gh-132942@footnote{https://github.com/python/cpython/issues/132942}: Fix two races in the type lookup cache.  This affected the
free-threaded build and could cause crashes (apparently quite difficult to
trigger).

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Propagate the return type of @code{_BINARY_OP_SUBSCR_TUPLE_INT} in
JIT. Patch by Tomas Roun

@item 
gh-132952@footnote{https://github.com/python/cpython/issues/132952}: Speed up startup with the @code{-S} argument by importing the
private @code{_io} module instead of @ref{82,,io}. This fixes a performance
regression introduced earlier in Python 3.14 development and restores
performance to the level of Python 3.13.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Allow the JIT to remove int guards after @code{_CALL_LEN} by
setting the return type to int. Patch by Diego Russo

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Split @code{CALL_TUPLE_1} into several uops allowing the JIT to
remove some of them. Patch by Tomas Roun

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Split @code{CALL_STR_1} into several uops allowing the JIT to
remove some of them. Patch by Tomas Roun

@item 
gh-132825@footnote{https://github.com/python/cpython/issues/132825}: Enhance unhashable key/element error messages for @ref{188,,dict}
and @ref{42b,,set}. Patch by Victor Stinner.

@item 
gh-131591@footnote{https://github.com/python/cpython/issues/131591}: Reset any 
@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/} remote debugging pending call in children
after @ref{6bd,,os.fork()} calls.

@item 
gh-132713@footnote{https://github.com/python/cpython/issues/132713}: Fix @code{repr(list)} race condition: hold a strong reference to
the item while calling @code{repr(item)}. Patch by Victor Stinner.

@item 
gh-132661@footnote{https://github.com/python/cpython/issues/132661}: Implement 
@geindex Python Enhancement Proposals; PEP 750
PEP 750@footnote{https://peps.python.org/pep-0750/} (Template Strings). Add new syntax for
t-strings and implement new internal @code{string.templatelib.Template}
and @code{string.templatelib.Interpolation} types.

@item 
gh-132479@footnote{https://github.com/python/cpython/issues/132479}: Fix compiler crash in certain circumstances where multiple
module-level annotations include comprehensions and other nested scopes.

@item 
gh-132747@footnote{https://github.com/python/cpython/issues/132747}: Fix a crash when calling @ref{188a,,__get__()} of a
@ref{1a8c,,method} with a @ref{a65,,None} second argument.

@item 
gh-132744@footnote{https://github.com/python/cpython/issues/132744}: Certain calls now check for runaway recursion and respect the
system recursion limit.

@item 
gh-132449@footnote{https://github.com/python/cpython/issues/132449}: Syntax errors that look like misspellings of Python keywords
now provide a helpful fix suggestion for the typo.  Contributed by Pablo
Galindo Salgado.
@end itemize

@node Library<31>,Core and Builtins<31>,Core and Builtins<30>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id116}@anchor{1a8d}
@subsubsection Library



@itemize -

@item 
gh-132737@footnote{https://github.com/python/cpython/issues/132737}: Support profiling code that requires @code{__main__}, such as
@ref{ab,,pickle}.
@end itemize

@node Core and Builtins<31>,Library<32>,Library<31>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id117}@anchor{1a8e}
@subsubsection Core and Builtins



@itemize -

@item 
gh-132639@footnote{https://github.com/python/cpython/issues/132639}: Added @ref{7fc,,PyLong_AsNativeBytes()},
@ref{7fd,,PyLong_FromNativeBytes()} and
@ref{7fe,,PyLong_FromUnsignedNativeBytes()} to the limited C API.

@item 
gh-100239@footnote{https://github.com/python/cpython/issues/100239}: Add specialisation for @code{BINARY_OP/SUBSCR} on list and slice.

@item 
gh-132508@footnote{https://github.com/python/cpython/issues/132508}: Uses tagged integers on the evaluation stack to represent the
instruction offsets when reraising an exception. This avoids the need to
box the integer which could fail in low memory conditions.

@item 
gh-124476@footnote{https://github.com/python/cpython/issues/124476}: Fix decoding from the locale encoding in the C.UTF-8 locale.

@item 
gh-131927@footnote{https://github.com/python/cpython/issues/131927}: Compiler warnings originating from the same module and line
number are now only emitted once, matching the behaviour of warnings
emitted from user code. This can also be configured with @ref{11b,,warnings}
filters.

@item 
gh-132457@footnote{https://github.com/python/cpython/issues/132457}: Make @ref{666,,staticmethod()} and @ref{69a,,classmethod()} generic.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Use @code{sym_new_type} instead of @code{sym_new_not_null} for
_BUILD_LIST, _BUILD_SET, _BUILD_MAP

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Split @code{CALL_TYPE_1} into several uops allowing the JIT to
remove some of them.

@item 
gh-132386@footnote{https://github.com/python/cpython/issues/132386}: Fix crash when passing a dict subclass as the @code{globals}
parameter to @ref{185,,exec()}.

@item 
gh-127682@footnote{https://github.com/python/cpython/issues/127682}: No longer call @code{__iter__} twice when creating and executing a
generator expression. Creating a generator expression from a non-interable
will raise only when the generator expression is executed. This brings the
behavior of generator expressions in line with other generators.

@item 
gh-132261@footnote{https://github.com/python/cpython/issues/132261}: The internal storage for annotations and annotate functions on
classes now uses different keys in the class dictionary. This eliminates
various edge cases where access to the @code{__annotate__} and
@code{__annotations__} attributes would behave unpredictably.

@item 
gh-132284@footnote{https://github.com/python/cpython/issues/132284}: Don’t wrap base @code{PyCFunction} slots on class creation if not
overridden.

@item 
gh-130415@footnote{https://github.com/python/cpython/issues/130415}: Improve the JIT’s ability to remove unused constant and local
variable loads, and fix an issue where deallocating unused values could
cause JIT code to crash or behave incorrectly.

@item 
gh-126703@footnote{https://github.com/python/cpython/issues/126703}: Fix possible use after free in cases where a method’s
definition has the same lifetime as its @code{self}.

@item 
gh-132286@footnote{https://github.com/python/cpython/issues/132286}: Fix that @ref{1a8f,,type.__annotate__} was not deleted, when
@ref{1a64,,type.__annotations__} was deleted.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Allow the JIT to remove an extra @code{_TO_BOOL_BOOL} instruction
after @code{_CONTAINS_OP_DICT} by setting the return type to bool.

@item 
gh-124715@footnote{https://github.com/python/cpython/issues/124715}: Prevents against stack overflows when calling
@ref{975,,Py_DECREF()}. Third-party extension objects no longer need to use
the «trashcan» mechanism, as protection is now built into the
@code{Py_DECREF()} macro.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Allow the JIT compiler to remove some type checks for
operations on lists, tuples, dictionaries, and sets.

@item 
gh-128398@footnote{https://github.com/python/cpython/issues/128398}: Improve error message when an object supporting the synchronous
(resp. asynchronous) context manager protocol is entered using
@ref{20b,,async with} (resp. @ref{20a,,with}) instead of @code{with}
(resp. @code{async with}). Patch by Bénédikt Tran.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Allow the JIT to remove unicode guards after
@code{_BINARY_OP_SUBSCR_STR_INT} by setting the return type to string.

@item 
gh-131878@footnote{https://github.com/python/cpython/issues/131878}: Handle uncaught exceptions in the main input loop for the new
REPL.

@item 
gh-131878@footnote{https://github.com/python/cpython/issues/131878}: Fix support of unicode characters with two or more codepoints
on Windows in the new REPL.

@item 
gh-126835@footnote{https://github.com/python/cpython/issues/126835}: Move constant folding to the peephole optimizer. Rename AST
optimization related files (Python/ast_opt.c -> Python/ast_preprocess.c),
structs (_PyASTOptimizeState -> _PyASTPreprocessState) and functions
(_PyAST_Optimize -> _PyAST_Preprocess, _PyCompile_AstOptimize ->
_PyCompile_AstPreprocess).

@item 
gh-114809@footnote{https://github.com/python/cpython/issues/114809}: Add support for macOS multi-arch builds with the JIT enabled

@item 
gh-131507@footnote{https://github.com/python/cpython/issues/131507}: PyREPL now supports syntax highlighting. Contributed by Łukasz
Langa.

@item 
gh-130907@footnote{https://github.com/python/cpython/issues/130907}: If the @code{__annotations__} of a module object are accessed
while the module is executing, return the annotations that have been
defined so far, without caching them.

@item 
gh-130104@footnote{https://github.com/python/cpython/issues/130104}: Three-argument @ref{441,,pow()} now try calling
@ref{442,,__rpow__()} if necessary. Previously it was only called in
two-argument @code{pow()} and the binary power operator.

@item 
gh-130070@footnote{https://github.com/python/cpython/issues/130070}: Fixed an assertion error for @ref{185,,exec()} passed a string
@code{source} and a non-@code{None} @code{closure}. Patch by Bartosz Sławecki.

@item 
gh-129958@footnote{https://github.com/python/cpython/issues/129958}: Fix a bug that was allowing newlines inconsistently in format
specifiers for single-quoted f-strings. Patch by Pablo Galindo.

@item 
gh-129858@footnote{https://github.com/python/cpython/issues/129858}: @code{elif} statements that follow an @code{else} block now have a
specific error message.

@item 
gh-69605@footnote{https://github.com/python/cpython/issues/69605}: Add module autocomplete to PyREPL.

@item 
gh-128555@footnote{https://github.com/python/cpython/issues/128555}: Add the @ref{41f,,sys.flags.thread_inherit_context} flag.


@itemize *

@item 
This flag is set to true by default on the free-threaded build
and false otherwise.  If the flag is true, starting a new thread using
@ref{420,,threading.Thread} will, by default, use a copy of the
@ref{421,,contextvars.Context} from the caller of
@ref{422,,threading.Thread.start()} rather than using an empty context.

@item 
Add the @ref{178,,-X thread_inherit_context} command-line option and
@geindex PYTHON_THREAD_INHERIT_CONTEXT
@geindex μεταβλητή περιβάλλοντος; PYTHON_THREAD_INHERIT_CONTEXT
@ref{1a90,,PYTHON_THREAD_INHERIT_CONTEXT} environment variable, which set the
@ref{41f,,thread_inherit_context} flag.

@item 
Add the @code{context} keyword parameter to @ref{420,,Thread}.  It can
be used to explicitly pass a context value to be used by a new thread.

@item 
Make the @code{_contextvars} module built-in.
@end itemize

@item 
gh-123539@footnote{https://github.com/python/cpython/issues/123539}: Improve @ref{17e,,SyntaxError} message for using @code{import ... as}
and @code{from ... import ... as} with not a name.

@item 
gh-102567@footnote{https://github.com/python/cpython/issues/102567}: @ref{178,,-X importtime} now accepts value @code{2}, which
indicates that an @code{importtime} entry should also be printed if an
imported module has already been loaded. Patch by Noah Kim and Adam
Turner.

@item 
gh-116436@footnote{https://github.com/python/cpython/issues/116436}: Improve error message when @ref{291,,TypeError} occurs during
@ref{1807,,dict.update()}

@item 
gh-103997@footnote{https://github.com/python/cpython/issues/103997}: String arguments passed to «-c» are now automatically dedented.
This allows «python -c» invocations to be indented in shell scripts
without causing indentation errors. (Patch by Jon Crall and Steven Sun)
@end itemize

@node Library<32>,C API<9>,Core and Builtins<31>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id118}@anchor{1a91}
@subsubsection Library



@itemize -

@item 
gh-89562@footnote{https://github.com/python/cpython/issues/89562}: Remove @code{hostflags} member from @code{PySSLContext} struct.
@end itemize

@node C API<9>,Build<8>,Library<32>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id119}@anchor{1a92}
@subsubsection C API



@itemize -

@item 
gh-133166@footnote{https://github.com/python/cpython/issues/133166}: Fix regression where @ref{827,,PyType_GetModuleByDef()} returns
NULL without setting @ref{291,,TypeError} when a static type is passed.

@item 
gh-133164@footnote{https://github.com/python/cpython/issues/133164}: Add @ref{5f3,,PyUnstable_Object_IsUniqueReferencedTemporary()}
function for determining if an object exists as a unique temporary
variable on the interpreter’s stack.  This is a replacement for some cases
where checking that @ref{54b,,Py_REFCNT()} is one is no longer sufficient to
determine if it’s safe to modify a Python object in-place with no visible
side effects.

@item 
gh-133140@footnote{https://github.com/python/cpython/issues/133140}: Add @ref{5f2,,PyUnstable_Object_IsUniquelyReferenced()} as a
replacement for @code{Py_REFNCT(op) == 1} on @ref{487,,free threaded} builds of Python.

@item 
gh-131747@footnote{https://github.com/python/cpython/issues/131747}: On non-Windows platforms, deprecate using
@ref{318,,ctypes.Structure._pack_} to use a Windows-compatible layout on
non-Windows platforms. The layout should be specified explicitly by
setting @ref{319,,ctypes.Structure._layout_} to @code{'ms'}.

@item 
gh-128972@footnote{https://github.com/python/cpython/issues/128972}: For non-free-threaded builds, the memory layout of
@ref{151e,,PyASCIIObject} is reverted to match Python 3.13. (Note that the
structure is not part of stable ABI and so its memory layout is
`guaranteed' to remain stable.)

@item 
gh-133079@footnote{https://github.com/python/cpython/issues/133079}: The undocumented APIs @code{Py_C_RECURSION_LIMIT} and
@code{PyThreadState.c_recursion_remaining}, added in 3.13, are
removed without a deprecation period.

@item 
gh-132987@footnote{https://github.com/python/cpython/issues/132987}: The @code{k} and @code{K} formats in @ref{1a6b,,PyArg_Parse()} now
support the @ref{43d,,__index__()} special method, like all other
integer formats.

@item 
gh-132909@footnote{https://github.com/python/cpython/issues/132909}: Fix an overflow when handling the @ref{1a93,,K} format in @ref{5ee,,Py_BuildValue()}. Patch by
Bénédikt Tran.

@item 
gh-132798@footnote{https://github.com/python/cpython/issues/132798}: Deprecated and undocumented functions
@code{PyUnicode_AsEncodedObject()},
@code{PyUnicode_AsDecodedObject()},
@code{PyUnicode_AsEncodedUnicode()} and
@code{PyUnicode_AsDecodedUnicode()} are scheduled for removal in 3.15.

@item 
gh-132470@footnote{https://github.com/python/cpython/issues/132470}: Creating a @ref{47e,,ctypes.CField} with a `byte_size' that does
not match the actual type size now raises a @ref{277,,ValueError} instead of
crashing the interpreter.

@item 
gh-112068@footnote{https://github.com/python/cpython/issues/112068}: [Reverted in gh-136991@footnote{https://github.com/python/cpython/issues/136991}] Add support of nullable arguments in
@ref{1a6b,,PyArg_Parse()} and similar functions. Adding @code{?} after any format
unit makes @code{None} be accepted as a value.

@item 
gh-50333@footnote{https://github.com/python/cpython/issues/50333}: Non-tuple sequences are deprecated as argument for the
@code{(items)} format unit in @ref{3b1,,PyArg_ParseTuple()} and other
@ref{601,,argument parsing} functions if `items' contains format
units which store a @ref{602,,borrowed buffer} or a
@ref{603,,borrowed reference}.
@end itemize

@node Build<8>,,C API<9>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id120}@anchor{1a94}
@subsubsection Build



@itemize -

@item 
gh-113464@footnote{https://github.com/python/cpython/issues/113464}: Use the cpython-bin-deps «externals» repository for Windows
LLVM dependency management. Installing LLVM manually is no longer
necessary for Windows JIT builds.

@item 
gh-133183@footnote{https://github.com/python/cpython/issues/133183}: iOS compiler shims now include @code{IPHONEOS_DEPLOYMENT_TARGET}
in target triples, ensuring that SDK version minimums are honored.

@item 
gh-133167@footnote{https://github.com/python/cpython/issues/133167}: Fix compilation process with @code{--enable-optimizations} and
@code{--without-docstrings}.

@item 
gh-133171@footnote{https://github.com/python/cpython/issues/133171}: Since free-threaded builds do not support the experimental JIT
compiler, prevent these configurations from being combined.

@item 
gh-132758@footnote{https://github.com/python/cpython/issues/132758}: Fix building with tail call interpreter and pystats.

@item 
gh-132649@footnote{https://github.com/python/cpython/issues/132649}: The @code{PClayout} script now allows passing
@code{--include-tcltk} on Windows ARM64.

@item 
gh-132257@footnote{https://github.com/python/cpython/issues/132257}: Change the default LTO flags on GCC to not pass
@code{-flto-partition=none}, and allow parallelization of LTO. For newer GNU
makes and GCC, this has a multiple factor speedup for LTO build times,
with no noticeable loss in performance.

@item 
gh-132026@footnote{https://github.com/python/cpython/issues/132026}: Fix use of undefined identifiers in platform triplet detection
on MIPS Linux platforms.
@end itemize

@node Python 3 14 0 alpha 7,Python 3 14 0 alpha 6,Python 3 14 0 beta 1,Changelog
@anchor{whatsnew/changelog python-3-14-0-alpha-7}@anchor{1a95}
@subsection Python 3.14.0 alpha 7


`Release date: 2025-04-08'

@menu
* macOS: macOS<5>. 
* Windows: Windows<9>. 
* Tools/Demos: Tools/Demos<7>. 
* Tests: Tests<11>. 
* Security: Security<10>. 
* Library: Library<33>. 
* Documentation: Documentation<9>. 
* Core and Builtins: Core and Builtins<32>. 
* Library: Library<34>. 
* Core and Builtins: Core and Builtins<33>. 
* C API: C API<10>. 
* Build: Build<9>. 

@end menu

@node macOS<5>,Windows<9>,,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id121}@anchor{1a96}
@subsubsection macOS



@itemize -

@item 
gh-124111@footnote{https://github.com/python/cpython/issues/124111}: Update macOS installer to use Tcl/Tk 8.6.16.

@item 
gh-131423@footnote{https://github.com/python/cpython/issues/131423}: Update macOS installer to use OpenSSL 3.0.16. Patch by Bénédikt
Tran.

@item 
gh-131025@footnote{https://github.com/python/cpython/issues/131025}: Update macOS installer to ship with SQLite 3.49.1.
@end itemize

@node Windows<9>,Tools/Demos<7>,macOS<5>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id122}@anchor{1a97}
@subsubsection Windows



@itemize -

@item 
gh-131423@footnote{https://github.com/python/cpython/issues/131423}: Update bundled version of OpenSSL to 3.0.16. The new build also
disables uplink support, which may be relevant to embedders but has no
impact on normal use.

@item 
gh-131453@footnote{https://github.com/python/cpython/issues/131453}: Some @code{SND_*} and @code{MB_*} constants are added to
@ref{120,,winsound}.

@item 
gh-91349@footnote{https://github.com/python/cpython/issues/91349}: Replaces our copy of @code{zlib} with @code{zlib-ng}, for performance
improvements in @ref{13c,,zlib}.

@item 
gh-131025@footnote{https://github.com/python/cpython/issues/131025}: Update Windows installer to ship with SQLite 3.49.1.
@end itemize

@node Tools/Demos<7>,Tests<11>,Windows<9>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id123}@anchor{1a98}
@subsubsection Tools/Demos



@itemize -

@item 
gh-132121@footnote{https://github.com/python/cpython/issues/132121}: Always escape non-printable Unicode characters in
@code{pygettext}.

@item 
gh-131852@footnote{https://github.com/python/cpython/issues/131852}: @code{msgfmt} no longer adds the @code{POT-Creation-Date} to
generated @code{.mo} files for consistency with GNU @code{msgfmt}.
@end itemize

@node Tests<11>,Security<10>,Tools/Demos<7>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id124}@anchor{1a99}
@subsubsection Tests



@itemize -

@item 
gh-131277@footnote{https://github.com/python/cpython/issues/131277}: Allow to unset one or more environment variables at once via
@ref{1a9a,,EnvironmentVarGuard.unset()}. Patch by Bénédikt
Tran.

@item 
gh-131050@footnote{https://github.com/python/cpython/issues/131050}: @code{test_ssl.test_dh_params} is skipped if the underlying TLS
library does not support finite-field ephemeral Diffie-Hellman.
@end itemize

@node Security<10>,Library<33>,Tests<11>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id125}@anchor{1a9b}
@subsubsection Security



@itemize -

@item 
gh-131809@footnote{https://github.com/python/cpython/issues/131809}: Update bundled libexpat to 2.7.1

@item 
gh-131261@footnote{https://github.com/python/cpython/issues/131261}: Upgrade to libexpat 2.7.0

@item 
gh-121284@footnote{https://github.com/python/cpython/issues/121284}: Fix bug in the folding of rfc2047 encoded-words when flattening
an email message using a modern email policy. Previously when an
encoded-word was too long for a line, it would be decoded, split across
lines, and re-encoded. But commas and other special characters in the
original text could be left unencoded and unquoted. This could
theoretically be used to spoof header lines using a carefully constructed
encoded-word if the resulting rendered email was transmitted or re-parsed.
@end itemize

@node Library<33>,Documentation<9>,Security<10>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id126}@anchor{1a9c}
@subsubsection Library



@itemize -

@item 
gh-132174@footnote{https://github.com/python/cpython/issues/132174}: Fix function name in error message of
@code{_interpreters.run_string}.

@item 
gh-132171@footnote{https://github.com/python/cpython/issues/132171}: Fix crash of @code{_interpreters.run_string} on string subclasses.

@item 
gh-129204@footnote{https://github.com/python/cpython/issues/129204}: Introduce new @code{_PYTHON_SUBPROCESS_USE_POSIX_SPAWN}
environment variable knob in @ref{df,,subprocess} to control the use of
@ref{731,,os.posix_spawn()}.

@item 
gh-132159@footnote{https://github.com/python/cpython/issues/132159}: Do not shadow user arguments in generated @code{__new__()} by
decorator @ref{695,,warnings.deprecated}. Patch by Xuehai Pan.

@item 
gh-132168@footnote{https://github.com/python/cpython/issues/132168}: The @ref{486,,ctypes.py_object} type now supports subscription,
making it a @ref{1d1,,generic type}.

@item 
gh-84481@footnote{https://github.com/python/cpython/issues/84481}: Add the @code{zipfile.ZipFile.data_offset} attribute, which
stores the offset to the beginning of ZIP data in a file when available.
When the @ref{ab1,,zipfile.ZipFile} is opened in either mode @code{'w'} or
@code{'x'} and the underlying file does not support @code{tell()}, the value
will be @code{None} instead.

@item 
gh-132075@footnote{https://github.com/python/cpython/issues/132075}: Fix possible use of @ref{d4,,socket} address structures with
uninitialized members. Now all structure members are initialized with
zeroes by default.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve import times by up to 27x for the @ref{db,,string} module.
Patch by Adam Turner.

@item 
gh-125434@footnote{https://github.com/python/cpython/issues/125434}: Display thread name in @ref{5b,,faulthandler}. Patch by Victor
Stinner.

@item 
gh-132002@footnote{https://github.com/python/cpython/issues/132002}: Fix crash when deallocating @ref{1a9d,,contextvars.ContextVar}
with weird unahashable string names.

@item 
gh-131938@footnote{https://github.com/python/cpython/issues/131938}: @ref{12e,,xml.etree.ElementTree}: update the error message when an
element to remove via @ref{1981,,Element.remove} is not found. Patch by Bénédikt
Tran.

@item 
gh-115942@footnote{https://github.com/python/cpython/issues/115942}: Add @ref{1a32,,threading.RLock.locked()},
@ref{1a9e,,multiprocessing.Lock.locked()}, @ref{1a9f,,multiprocessing.RLock.locked()},
and allow @ref{173b,,multiprocessing.managers.SyncManager.Lock()} and
@ref{173c,,multiprocessing.managers.SyncManager.RLock()} to proxy @code{locked()}
call.

@item 
gh-131974@footnote{https://github.com/python/cpython/issues/131974}: Fix several thread-safety issues in @ref{2d,,ctypes} on the
@ref{487,,free threaded} build.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve the import time of the @ref{9,,ast} module by extracting
the @ref{cb6,,unparse()} function to a helper module.

@item 
gh-107369@footnote{https://github.com/python/cpython/issues/107369}: Improved performance of @ref{77d,,textwrap.indent()} by an average
of ~1.3x. Patch by Adam Turner.

@item 
gh-131792@footnote{https://github.com/python/cpython/issues/131792}: Improved performance of @ref{55f,,textwrap.dedent()} by an average
of ~2.4x, (with improvements of up to 4x for large inputs), and fixed a
bug where blank lines with whitespace characters other than space or
horizontal tab were not normalised to the newline. Patch by Adam Turner,
Marius Juston, and Pieter Eendebak.

@item 
gh-131668@footnote{https://github.com/python/cpython/issues/131668}: @ref{d4,,socket}: Fix code parsing AF_BLUETOOTH socket addresses.

@item 
gh-60115@footnote{https://github.com/python/cpython/issues/60115}: Support frozen modules for @ref{4cd,,linecache.getline()}.

@item 
gh-131492@footnote{https://github.com/python/cpython/issues/131492}: Fix a resource leak when constructing a @ref{849,,gzip.GzipFile}
with a filename fails, for example when passing an invalid
@code{compresslevel}.

@item 
gh-131435@footnote{https://github.com/python/cpython/issues/131435}: 10-20% performance improvement of @ref{15d5,,random.randint()}.

@item 
gh-131461@footnote{https://github.com/python/cpython/issues/131461}: Fix @ref{74f,,ResourceWarning} when constructing a
@ref{849,,gzip.GzipFile} in write mode with a broken file object.

@item 
gh-125866@footnote{https://github.com/python/cpython/issues/125866}: Deprecate the @code{nturl2path} module. Call
@ref{539,,urllib.request.url2pathname()} and
@ref{53b,,pathname2url()} instead.

@item 
gh-126367@footnote{https://github.com/python/cpython/issues/126367}: Fix issue where @ref{539,,urllib.request.url2pathname()} raised
@ref{53c,,OSError} when given a Windows URI containing a colon character not
following a drive letter, such as before an NTFS alternate data stream.

@item 
gh-120144@footnote{https://github.com/python/cpython/issues/120144}: Disable @code{CALL} event in @ref{10,,bdb} in @code{monitoring} backend
when we don’t need any new events on the code object to get a better
performance.

@item 
gh-131358@footnote{https://github.com/python/cpython/issues/131358}: Register @code{cseuckr} as an encoding alias for @code{euc_kr}.

@item 
gh-131325@footnote{https://github.com/python/cpython/issues/131325}: Fix sendfile fallback implementation to drain data after
writing to transport in @ref{b,,asyncio}.

@item 
gh-90548@footnote{https://github.com/python/cpython/issues/90548}: @ref{1a01,,platform.libc_ver()} can now detect and report the version
of @code{musl} on Alpine Linux.

@item 
gh-129843@footnote{https://github.com/python/cpython/issues/129843}: Fix incorrect argument passing in
@ref{2ab,,warnings.warn_explicit()}.

@item 
gh-70647@footnote{https://github.com/python/cpython/issues/70647}: When creating a @ref{33,,datetime} object with an out of range date
a more informative error is raised.

@item 
gh-130914@footnote{https://github.com/python/cpython/issues/130914}: Allow @ref{4ad,,graphlib.TopologicalSorter.prepare()} to be called
more than once as long as sorting has not started. Patch by Daniel Pope.

@item 
gh-131236@footnote{https://github.com/python/cpython/issues/131236}: Allow to generate multiple UUIDs at once via @ref{543,,python -m uuid --count}.

@item 
gh-126895@footnote{https://github.com/python/cpython/issues/126895}: Fix @ref{c2,,readline} in @ref{487,,free-threaded}
build.

@item 
gh-121468@footnote{https://github.com/python/cpython/issues/121468}: @code{$_asynctask} is added as a @ref{aa,,pdb} convenience variable
to access the current asyncio task if applicable.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve import time of @ref{89,,locale} using lazy import @code{re}.
Patch by Semyon Moroz.

@item 
gh-129598@footnote{https://github.com/python/cpython/issues/129598}: Fix @ref{cb6,,ast.unparse()} when @ref{1aa0,,ast.Interactive} contains
multiple statements.

@item 
gh-85162@footnote{https://github.com/python/cpython/issues/85162}: The @ref{75,,http.server} module now includes built-in support for
HTTPS servers exposed by @ref{4b6,,http.server.HTTPSServer}. This
functionality is exposed by the command-line interface (@code{python -m
http.server}) through the @code{--tls-cert}, @code{--tls-key} and
@code{--tls-password-file} options. Patch by Semyon Moroz.

@item 
gh-129463@footnote{https://github.com/python/cpython/issues/129463}: The implementations of equality and hashing for
@ref{1967,,annotationlib.ForwardRef} now use all attributes on the object.
Two @code{ForwardRef} objects are equal only if all attributes are
equal.

@item 
gh-128593@footnote{https://github.com/python/cpython/issues/128593}: @ref{1967,,annotationlib.ForwardRef} objects no longer cache their
value when they are successfully evaluated. Successive calls to
@ref{150,,annotationlib.ForwardRef.evaluate()} may return different values.

@item 
gh-117779@footnote{https://github.com/python/cpython/issues/117779}: Fix reading duplicated entries in @ref{13a,,zipfile} by name.
Reading duplicated entries (except the last one) by @code{ZipInfo} now emits
a warning instead of raising an exception.

@item 
gh-128715@footnote{https://github.com/python/cpython/issues/128715}: The class of @ref{47c,,Structure}/@ref{47d,,Union}
field descriptors is now available as @ref{47e,,CField}, and has new
attributes to aid debugging and introspection.

@item 
gh-128055@footnote{https://github.com/python/cpython/issues/128055}: Fix @code{test.test_sysconfig.test_sysconfigdata_json} when
running outside the build directory (eg. after installing).

@item 
gh-126037@footnote{https://github.com/python/cpython/issues/126037}: @ref{12e,,xml.etree.ElementTree}: Fix a crash in
@ref{1aa1,,Element.find},
@ref{190a,,Element.findtext} and
@ref{1aa2,,Element.findall} when the
tag to find implements an @ref{ec0,,__eq__()} method mutating the
element being queried. Patch by Bénédikt Tran.

@item 
gh-127794@footnote{https://github.com/python/cpython/issues/127794}: When headers are added to @ref{780,,email.message.Message}
objects, either through @ref{1aa3,,email.message.Message.__setitem__()} or
@ref{1aa4,,email.message.Message.add_header()}, the field name is now validated
according to 
@geindex RFC; RFC 5322 Section 2.2
RFC 5322@comma{} Section 2.2@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html#section-2.2} and a
@ref{277,,ValueError} is raised if the field name contains any invalid
characters.

@item 
gh-123599@footnote{https://github.com/python/cpython/issues/123599}: Deprecate @code{pathlib.PurePath.as_uri()}; use
@ref{587,,pathlib.Path.as_uri()} instead.

@item 
gh-126033@footnote{https://github.com/python/cpython/issues/126033}: @ref{12e,,xml.etree.ElementTree}: Fix a crash in
@ref{1981,,Element.remove} when the
element is concurrently mutated. Patch by Bénédikt Tran.

@item 
gh-120144@footnote{https://github.com/python/cpython/issues/120144}: Add the optional backend of @code{sys.monitoring} to @ref{10,,bdb}
and use it for @ref{aa,,pdb}.

@item 
gh-74598@footnote{https://github.com/python/cpython/issues/74598}: Add @ref{4a1,,fnmatch.filterfalse()} for excluding names matching a
pattern. Patch by Bénédikt Tran.

@item 
gh-114917@footnote{https://github.com/python/cpython/issues/114917}: Add support for AI_NUMERICSERV in getaddrinfo emulation

@item 
bpo-17254@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17254}: Added aliases for Thai Language using Microsoft Code Pages.
@end itemize

@node Documentation<9>,Core and Builtins<32>,Library<33>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id127}@anchor{1aa5}
@subsubsection Documentation



@itemize -

@item 
gh-131417@footnote{https://github.com/python/cpython/issues/131417}: Mention @ref{f8b,,asyncio.Future} and @ref{460,,asyncio.Task} in
generic classes list.
@end itemize

@node Core and Builtins<32>,Library<34>,Documentation<9>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id128}@anchor{1aa6}
@subsubsection Core and Builtins



@itemize -

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Allow the JIT to remove an extra @code{_TO_BOOL_BOOL} instruction
after @code{_CONTAINS_OP_SET} by setting the return type to bool.

@item 
gh-132011@footnote{https://github.com/python/cpython/issues/132011}: Fix crash when calling @ref{aba,,list.append()} as an unbound
method.

@item 
gh-131998@footnote{https://github.com/python/cpython/issues/131998}: Fix a crash when using an unbound method @ref{21f,,descriptor}
object in a function where a bound method descriptor was used.

@item 
gh-131591@footnote{https://github.com/python/cpython/issues/131591}: Implement 
@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/} (Safe external debugger interface for
CPython). Add a new @ref{418,,sys.remote_exec()} function to the @ref{e2,,sys}
module. This function schedules the execution of a Python file in a
separate process. Patch by Pablo Galindo, Matt Wozniski and Ivona
Stojanovic.

@item 
gh-131798@footnote{https://github.com/python/cpython/issues/131798}: Allow JIT to omit str guard in truthiness test when str type is
known.

@item 
gh-131833@footnote{https://github.com/python/cpython/issues/131833}: Add support for optionally dropping grouping parentheses when
using multiple exception types as per 
@geindex Python Enhancement Proposals; PEP 758
PEP 758@footnote{https://peps.python.org/pep-0758/}. Patch by Pablo Galindo

@item 
gh-130924@footnote{https://github.com/python/cpython/issues/130924}: Usage of a name in a function-scope annotation no longer
triggers creation of a cell for that variable. This fixes a regression in
earlier alphas of Python 3.14.

@item 
gh-131800@footnote{https://github.com/python/cpython/issues/131800}: Improve the experimental JIT’s ability to remove type checks
for certain subscripting operations.

@item 
gh-131738@footnote{https://github.com/python/cpython/issues/131738}: Compiler emits optimized code for builtin any/all/tuple calls
over a generator expression.

@item 
gh-131719@footnote{https://github.com/python/cpython/issues/131719}: Fix missing NULL check in @code{_PyMem_FreeDelayed} in
@ref{487,,free-threaded} build.

@item 
gh-131670@footnote{https://github.com/python/cpython/issues/131670}: Fix @ref{bb3,,anext()} failing on sync @ref{1aa7,,__anext__()}
raising an exception.

@item 
gh-131666@footnote{https://github.com/python/cpython/issues/131666}: Fix signature of @code{anext_awaitable.close} objects. Patch by
Bénédikt Tran.

@item 
gh-130415@footnote{https://github.com/python/cpython/issues/130415}: Optimize comparison of two constants in JIT builds

@item 
gh-129149@footnote{https://github.com/python/cpython/issues/129149}: Add fast path for small and medium-size integers in
@ref{5d0,,PyLong_FromInt32()}, @ref{5d2,,PyLong_FromUInt32()},
@ref{5d1,,PyLong_FromInt64()} and @ref{5d3,,PyLong_FromUInt64()}. Patch by Chris
Eibl.

@item 
gh-130887@footnote{https://github.com/python/cpython/issues/130887}: Optimize the AArch64 code generation for the JIT. Patch by
Diego Russo

@item 
gh-130956@footnote{https://github.com/python/cpython/issues/130956}: Optimize the AArch64 code generation for the JIT. Patch by
Diego Russo

@item 
gh-130928@footnote{https://github.com/python/cpython/issues/130928}: Fix error message when formatting bytes using the @code{'i'} flag.
Patch by Maxim Ageev.

@item 
gh-130935@footnote{https://github.com/python/cpython/issues/130935}: Annotations at the class and module level that are
conditionally defined are now only reflected in @code{__annotations__} if the
block they are in is executed. Patch by Jelle Zijlstra.

@item 
gh-130775@footnote{https://github.com/python/cpython/issues/130775}: Do not crash on negative @code{column} and @code{end_column} in
@ref{9,,ast} locations.

@item 
gh-130704@footnote{https://github.com/python/cpython/issues/130704}: Optimize @code{LOAD_FAST} and its superinstruction form to reduce
reference counting overhead. These instructions are replaced with faster
variants that load borrowed references onto the operand stack when we can
prove that the reference in the frame outlives the reference loaded onto
the stack.

@item 
gh-88887@footnote{https://github.com/python/cpython/issues/88887}: Fixing multiprocessing Resource Tracker process leaking, usually
observed when running Python as PID 1.

@item 
gh-130115@footnote{https://github.com/python/cpython/issues/130115}: Fix an issue with thread identifiers being sign-extended on
some platforms.
@end itemize

@node Library<34>,Core and Builtins<33>,Core and Builtins<32>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id129}@anchor{1aa8}
@subsubsection Library



@itemize -

@item 
gh-99108@footnote{https://github.com/python/cpython/issues/99108}: Add support for built-in implementation of HMAC (
@geindex RFC; RFC 2104
RFC 2104@footnote{https://datatracker.ietf.org/doc/html/rfc2104.html})
based on HACL*. Patch by Bénédikt Tran.
@end itemize

@node Core and Builtins<33>,C API<10>,Library<34>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id130}@anchor{1aa9}
@subsubsection Core and Builtins



@itemize -

@item 
gh-130080@footnote{https://github.com/python/cpython/issues/130080}: Implement PEP 765: Disallow return/break/continue that exit a
finally block.

@item 
gh-129900@footnote{https://github.com/python/cpython/issues/129900}: Fix return codes inside @ref{10f7,,SystemExit} not getting returned
by the REPL.

@item 
gh-128632@footnote{https://github.com/python/cpython/issues/128632}: Disallow @code{__classdict__} as the name of a type parameter.
Using this name would previously crash the interpreter in some
circumstances.

@item 
gh-126703@footnote{https://github.com/python/cpython/issues/126703}: Improve performance of builtin methods by using a freelist.

@item 
gh-126703@footnote{https://github.com/python/cpython/issues/126703}: Improve performance of  @ref{d0f,,range} by using a freelist.
@end itemize

@node C API<10>,Build<9>,Core and Builtins<33>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id131}@anchor{1aaa}
@subsubsection C API



@itemize -

@item 
gh-131740@footnote{https://github.com/python/cpython/issues/131740}: Update PyUnstable_GC_VisitObjects to traverse perm gen.

@item 
gh-131525@footnote{https://github.com/python/cpython/issues/131525}: The PyTupleObject now caches the computed hash value in the new
field ob_hash.
@end itemize

@node Build<9>,,C API<10>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id132}@anchor{1aab}
@subsubsection Build



@itemize -

@item 
gh-131865@footnote{https://github.com/python/cpython/issues/131865}: The DTrace build now properly passes the @code{CC} and @code{CFLAGS}
variables to the @code{dtrace} command when utilizing SystemTap on Linux.

@item 
gh-131675@footnote{https://github.com/python/cpython/issues/131675}: Fix mimalloc library builds for 32-bit ARM targets.

@item 
gh-131691@footnote{https://github.com/python/cpython/issues/131691}: clang-cl on Windows needs option @code{/EHa} to support SEH
(structured exception handling) correctly. Fix by Chris Eibl.

@item 
gh-131278@footnote{https://github.com/python/cpython/issues/131278}: Add optimizing flag @code{WITH_COMPUTED_GOTOS} to Windows builds
for when using a compiler that supports it (currently clang-cl). Patch by
Chris Eibl.

@item 
gh-130213@footnote{https://github.com/python/cpython/issues/130213}: Update the vendored HACL* library to fix build issues with
older clang compilers.

@item 
gh-130673@footnote{https://github.com/python/cpython/issues/130673}: Fix potential @code{KeyError} when handling object sections during
JIT building process.
@end itemize

@node Python 3 14 0 alpha 6,Python 3 14 0 alpha 5,Python 3 14 0 alpha 7,Changelog
@anchor{whatsnew/changelog python-3-14-0-alpha-6}@anchor{1aac}
@subsection Python 3.14.0 alpha 6


`Release date: 2025-03-14'

@menu
* macOS: macOS<6>. 
* Windows: Windows<10>. 
* Tools/Demos: Tools/Demos<8>. 
* Tests: Tests<12>. 
* Security: Security<11>. 
* Library: Library<35>. 
* Documentation: Documentation<10>. 
* Core and Builtins: Core and Builtins<34>. 
* Library: Library<36>. 
* Core and Builtins: Core and Builtins<35>. 
* Library: Library<37>. 
* Core and Builtins: Core and Builtins<36>. 
* C API: C API<11>. 
* Build: Build<10>. 

@end menu

@node macOS<6>,Windows<10>,,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id133}@anchor{1aad}
@subsubsection macOS



@itemize -

@item 
gh-128540@footnote{https://github.com/python/cpython/issues/128540}: Ensure web browser is launched by @ref{1923,,webbrowser.open()} on
macOS, even for @code{file://} URLs.
@end itemize

@node Windows<10>,Tools/Demos<8>,macOS<6>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id134}@anchor{1aae}
@subsubsection Windows



@itemize -

@item 
gh-131020@footnote{https://github.com/python/cpython/issues/131020}: pylauncher@footnote{https://github.com/python/cpython/tree/main/PC/launcher2.c} correctly detects a BOM
when searching for the shebang. Fix by Chris Eibl.
@end itemize

@node Tools/Demos<8>,Tests<12>,Windows<10>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id135}@anchor{1aaf}
@subsubsection Tools/Demos



@itemize -

@item 
gh-130453@footnote{https://github.com/python/cpython/issues/130453}: Make it possible to override default keywords in
@code{pygettext}.

@item 
gh-85012@footnote{https://github.com/python/cpython/issues/85012}: Correctly reset @code{msgctxt} when compiling messages in
@code{msgfmt}.

@item 
gh-130453@footnote{https://github.com/python/cpython/issues/130453}: Extend support for specifying custom keywords in
@code{pygettext}.

@item 
gh-130195@footnote{https://github.com/python/cpython/issues/130195}: Add warning messages when @code{pygettext} unimplemented
@code{-a/--extract-all} option is called.

@item 
gh-130057@footnote{https://github.com/python/cpython/issues/130057}: Add support for translator comments in @code{pygettext.py}.

@item 
gh-130025@footnote{https://github.com/python/cpython/issues/130025}: The iOS testbed now correctly handles symlinks used as Python
framework references.

@item 
gh-129911@footnote{https://github.com/python/cpython/issues/129911}: Fix the keyword entry in the help output of
@code{pygettext}.
@end itemize

@node Tests<12>,Security<11>,Tools/Demos<8>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id136}@anchor{1ab0}
@subsubsection Tests



@itemize -

@item 
gh-129200@footnote{https://github.com/python/cpython/issues/129200}: Multiple iOS testbed runners can now be started at the same
time without introducing an ambiguity over simulator ownership.

@item 
gh-130292@footnote{https://github.com/python/cpython/issues/130292}: The iOS testbed will now run successfully on a machine that has
not previously run Xcode tests (such as CI configurations).

@item 
gh-130293@footnote{https://github.com/python/cpython/issues/130293}: The tests of terminal colorization are no longer sensitive to
the value of the @code{TERM} variable in the testing environment.

@item 
gh-129401@footnote{https://github.com/python/cpython/issues/129401}: Fix a flaky test in @code{test_repr_rlock} that checks the
representation of @ref{1a7d,,multiprocessing.RLock}.

@item 
gh-126332@footnote{https://github.com/python/cpython/issues/126332}: Add unit tests for pyrepl.
@end itemize

@node Security<11>,Library<35>,Tests<12>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id137}@anchor{1ab1}
@subsubsection Security



@itemize -

@item 
gh-127371@footnote{https://github.com/python/cpython/issues/127371}: Avoid unbounded buffering for
@code{tempfile.SpooledTemporaryFile.writelines()}. Previously, disk
spillover was only checked after the lines iterator had been exhausted.
This is now done after each line is written.
@end itemize

@node Library<35>,Documentation<10>,Security<11>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id138}@anchor{1ab2}
@subsubsection Library



@itemize -

@item 
gh-131204@footnote{https://github.com/python/cpython/issues/131204}: Use monospace font from System Font Stack for cross-platform
support in @ref{214,,difflib.HtmlDiff}.

@item 
gh-131196@footnote{https://github.com/python/cpython/issues/131196}: Improve performance of @ref{1ab3,,uuid.UUID.hex} and
@ref{a0f,,uuid.UUID.__str__}.

@item 
gh-130940@footnote{https://github.com/python/cpython/issues/130940}: The behavior of @code{PyConfig.use_system_logger} was modified to
be enabled by default on iOS. It remains disabled by default on macOS.

@item 
gh-131123@footnote{https://github.com/python/cpython/issues/131123}: Supported completions for attributes of convenience variables
in @ref{aa,,pdb}.

@item 
gh-93096@footnote{https://github.com/python/cpython/issues/93096}: Removed undocumented CLI @code{python -m difflib}. Use @code{python -m
doctest Lib/difflib.py -v} instead. Patch by Semyon Moroz.

@item 
gh-93096@footnote{https://github.com/python/cpython/issues/93096}: Removed undocumented @code{-t} and @code{-v} arguments of @code{python -m
pickle}. Use @code{python -m doctest Lib/pickle.py -v} instead. Patch by
Semyon Moroz.

@item 
gh-81267@footnote{https://github.com/python/cpython/issues/81267}: Correct @ref{a8c,,time.sleep()} error message when an object that
cannot be interpreted as an integer or float is provided.

@item 
gh-93096@footnote{https://github.com/python/cpython/issues/93096}: Removed undocumented @code{-t} and @code{-v} arguments of @code{python -m
pickletools}. Use @code{python -m doctest Lib/pickletools.py -v} instead.
Patch by Semyon Moroz.

@item 
gh-131045@footnote{https://github.com/python/cpython/issues/131045}: Fix issue with @code{__contains__}, values, and pseudo-members for
@ref{a14,,enum.Flag}.

@item 
gh-130959@footnote{https://github.com/python/cpython/issues/130959}: Fix pure-Python implementation of
@ref{a09,,datetime.time.fromisoformat()} to reject times with spaces in
fractional part (for example, @code{12:34:56.400 +02:00}), matching the C
implementation. Patch by Michał Gorny.

@item 
gh-130806@footnote{https://github.com/python/cpython/issues/130806}: Deleting @ref{849,,gzip.GzipFile} before it is closed now emits a
@ref{74f,,ResourceWarning}.

@item 
gh-130637@footnote{https://github.com/python/cpython/issues/130637}: Add validation for numeric response data in poplib.POP3.stat()
method

@item 
gh-130665@footnote{https://github.com/python/cpython/issues/130665}: Only apply locale to @ref{201,,calendar CLI} when
set via @code{--locale} and not via @code{LANG} environment variable.

@item 
gh-130660@footnote{https://github.com/python/cpython/issues/130660}: @code{sys.ps1} and @code{sys.ps2} are now restored after
@ref{1ab4,,code.interact()} call.

@item 
gh-130608@footnote{https://github.com/python/cpython/issues/130608}: Remove `dirs_exist_ok' argument from @ref{4ef,,pathlib.Path.copy()}
and @ref{4f0,,copy_into()}. These methods are new in Python 3.14.

@item 
gh-130461@footnote{https://github.com/python/cpython/issues/130461}: Remove @code{.. index::} directives from the @ref{119,,uuid} module
documentation. These directives previously created entries in the general
index for @ref{f66,,getnode()} as well as the @ref{f67,,uuid1()},
@ref{561,,uuid3()}, @ref{563,,uuid4()}, @ref{562,,uuid5()}, and
@ref{540,,uuid8()} constructor functions.

@item 
gh-130379@footnote{https://github.com/python/cpython/issues/130379}: The zipapp module now calculates the list of files to be added
to the archive before creating the archive. This avoids accidentally
including the target when it is being created in the source directory.

@item 
gh-82987@footnote{https://github.com/python/cpython/issues/82987}: Inline breakpoints like @ref{4f9,,breakpoint()} or
@ref{4fa,,pdb.set_trace()} will always stop the program at calling frame,
ignoring the @code{skip} pattern (if any).

@item 
gh-125377@footnote{https://github.com/python/cpython/issues/125377}: @code{<tab>} at the beginning of the line in @ref{aa,,pdb} multi-line
input will fill in a 4-space indentation now, instead of inserting a
@code{\t} character.

@item 
gh-125413@footnote{https://github.com/python/cpython/issues/125413}: Ensure the path returned from @ref{4ef,,pathlib.Path.copy()} or
@ref{4f1,,move()} has fresh @ref{4f3,,info}.

@item 
gh-65697@footnote{https://github.com/python/cpython/issues/65697}: stdlib configparser will now attempt to validate that keys it
writes will not result in file corruption (creating a file unable to be
accurately parsed by a future read() call from the same parser).
Attempting a corrupting write() will raise an InvalidWriteError.

@item 
gh-125413@footnote{https://github.com/python/cpython/issues/125413}: Speed up @ref{4ef,,Path.copy} by making better
use of @ref{4f3,,info} internally.

@item 
gh-130285@footnote{https://github.com/python/cpython/issues/130285}: Fix corner case for @ref{b2b,,random.sample()} allowing the `counts'
parameter to specify an empty population. So now, @code{sample([], 0,
counts=[])} and @code{sample('abc', k=0, counts=[0, 0, 0])} both give the
same result as @code{sample([], 0)}.

@item 
gh-124703@footnote{https://github.com/python/cpython/issues/124703}: Executing @code{quit} command in @ref{aa,,pdb} will raise
@ref{500,,bdb.BdbQuit} when @code{pdb} is started from an interactive console
using @ref{4f9,,breakpoint()} or @ref{4fa,,pdb.set_trace()}.

@item 
gh-107773@footnote{https://github.com/python/cpython/issues/107773}: Make @ref{33,,datetime} subclass @ref{1bc,,__repr__()}
consistent both implementations. Patch by Semyon Moroz.

@item 
gh-130250@footnote{https://github.com/python/cpython/issues/130250}: Fix regression in @code{traceback.print_last()}.

@item 
gh-123471@footnote{https://github.com/python/cpython/issues/123471}: Make concurrent iterations over @ref{715,,itertools.batched} safe
under free-threading.

@item 
gh-57537@footnote{https://github.com/python/cpython/issues/57537}: Support breakpoints for @ref{13b,,zipimport} modules on @ref{aa,,pdb}

@item 
gh-130230@footnote{https://github.com/python/cpython/issues/130230}: Fix crash in @ref{441,,pow()} with only @ref{1c2,,Decimal}
third argument.

@item 
gh-126944@footnote{https://github.com/python/cpython/issues/126944}: Show explicit errors when required arguments of @ref{aa,,pdb}
commands are missing

@item 
gh-127750@footnote{https://github.com/python/cpython/issues/127750}: Improve repr of @ref{21e,,functools.singledispatchmethod} methods
and descriptors.

@item 
gh-128520@footnote{https://github.com/python/cpython/issues/128520}: Apply type conversion consistently in @ref{8b6,,pathlib.PurePath}
and @ref{4ee,,Path} methods can accept a path object as an
argument, such as @ref{8bc,,match()} and
@ref{1ab5,,rename()}. The argument is now converted to path object
if it lacks a @ref{8b7,,with_segments()} attribute, and not
otherwise.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Reverts a change in the previous release attempting to make
some stdlib imports used within the @ref{df,,subprocess} module lazy as this
was causing errors during @code{__del__} finalizers calling methods such as
@code{terminate}, or @code{kill}, or @code{send_signal}.

@item 
gh-130164@footnote{https://github.com/python/cpython/issues/130164}: Fixed failure to raise @ref{291,,TypeError} in
@ref{1ab6,,inspect.Signature.bind()} for positional-only arguments provided by
keyword when a variadic keyword argument (e.g. @code{**kwargs}) is present.

@item 
gh-130151@footnote{https://github.com/python/cpython/issues/130151}: Fix reference leaks in @code{_hashlib.hmac_new()} and
@code{_hashlib.hmac_digest()}. Patch by Bénédikt Tran.

@item 
gh-130145@footnote{https://github.com/python/cpython/issues/130145}: Fix @code{asyncio.AbstractEventloop.run_forever()} when another
loop is already running.

@item 
gh-130139@footnote{https://github.com/python/cpython/issues/130139}: Fix bug where @ref{1c9,,ast.parse()} did not error on AST input
which is not of the correct type, when called with optimize=False.

@item 
gh-127260@footnote{https://github.com/python/cpython/issues/127260}: Forbid the use of colon («:») as a fractional component
separator and other improvements to the consistency of error raising
between the C and Python implementations of
@ref{a09,,datetime.time.fromisoformat()} and
@ref{a0a,,datetime.datetime.fromisoformat()}. Patch by Semyon Moroz.

@item 
gh-85795@footnote{https://github.com/python/cpython/issues/85795}: Using @ref{443,,super()} and @code{__class__} @ref{1ab7,,closure variable}
in user-defined methods of @ref{2e4,,typing.NamedTuple} subclasses is now
explicitly prohibited at runtime. Contributed by Bartosz Sławecki in
gh-130082@footnote{https://github.com/python/cpython/issues/130082}.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve import time of @ref{1a,,cmd} by lazy importing
@ref{81,,inspect} and removing @ref{db,,string}. Patch by Semyon Moroz.

@item 
gh-129726@footnote{https://github.com/python/cpython/issues/129726}: Fix @ref{849,,gzip.GzipFile} raising an unraisable exception
during garbage collection when referring to a temporary object by breaking
the reference loop with @ref{11d,,weakref}.

@item 
gh-127750@footnote{https://github.com/python/cpython/issues/127750}: Remove broken @ref{21e,,functools.singledispatchmethod()} caching
introduced in gh-85160@footnote{https://github.com/python/cpython/issues/85160}. Achieve the same performance using different
optimization.

@item 
gh-129948@footnote{https://github.com/python/cpython/issues/129948}: Add support for shared @ref{42b,,set} to
@ref{1ab8,,multiprocessing.managers.SyncManager} via @ref{4db,,SyncManager.set()}.

@item 
gh-129965@footnote{https://github.com/python/cpython/issues/129965}: Update MIME types for @code{.avi} and @code{.wav}. Add MIME types for
@code{.docx}, @code{.pptx}, @code{.xlsx}, @code{.epub}, @code{.flac}, @code{.m4a}, @code{.odg},
@code{.odp}, @code{.ods}, @code{.odt}, @code{.oga}, @code{.ogg}, @code{.ogx} and @code{.weba}.
Patch by Hugo van Kemenade.

@item 
gh-129889@footnote{https://github.com/python/cpython/issues/129889}: Support context manager protocol by @ref{479,,contextvars.Token}.
Patch by Andrew Svetlov.

@item 
gh-97850@footnote{https://github.com/python/cpython/issues/97850}: Update the deprecation warning of
@code{importlib.abc.Loader.load_module}.

@item 
gh-129678@footnote{https://github.com/python/cpython/issues/129678}: @ref{6e4,,configparser.ConfigParser}: do not write an empty
unnamed section

@item 
gh-128641@footnote{https://github.com/python/cpython/issues/128641}: Restore @ref{180a,,configparser.ConfigParser.read()} performance.

@item 
gh-129569@footnote{https://github.com/python/cpython/issues/129569}: Fix @ref{ac2,,unicodedata.normalize()} to always return a built-in
@ref{1df,,str} object when given an input of a @code{str} subclass,
regardless of whether the string is already normalized.

@item 
gh-128231@footnote{https://github.com/python/cpython/issues/128231}: Execution of multiple statements in the new REPL now stops
immediately upon the first exception encountered. Patch by Bartosz
Sławecki.

@item 
gh-96092@footnote{https://github.com/python/cpython/issues/96092}: Fix bug in @ref{1232,,traceback.walk_stack()} called with None where
it was skipping more frames than in prior versions. This bug fix also
changes walk_stack to walk the stack in the frame where it was called
rather than where it first gets used.

@item 
gh-129288@footnote{https://github.com/python/cpython/issues/129288}: Add optional @code{l2_cid} and @code{l2_bdaddr_type} fields to
@ref{d4,,socket} @code{BTPROTO_L2CAP} sockaddr tuple.

@item 
gh-128703@footnote{https://github.com/python/cpython/issues/128703}: Fix @ref{71b,,mimetypes.guess_type()} to use default mapping for
empty @code{Content-Type} in registry.

@item 
gh-128647@footnote{https://github.com/python/cpython/issues/128647}: Eagerly write to buffers passed to @ref{849,,gzip.GzipFile}’s
@ref{1ab9,,readinto()} and
@ref{11cf,,readinto1()} implementations, avoiding unnecessary
allocations. Patch by Chris Markiewicz.

@item 
gh-128184@footnote{https://github.com/python/cpython/issues/128184}: Improve display of @ref{1967,,annotationlib.ForwardRef} object
within @ref{6e8,,inspect.Signature} representations. This also fixes a
@ref{665,,NameError} that was raised when using @ref{6e6,,dataclasses.dataclass()}
on classes with unresolvable forward references.

@item 
gh-128041@footnote{https://github.com/python/cpython/issues/128041}: Add
@ref{471,,concurrent.futures.ProcessPoolExecutor.terminate_workers()} and
@ref{472,,concurrent.futures.ProcessPoolExecutor.kill_workers()} as ways to
terminate or kill all living worker processes in the given pool.
(Contributed by Charles Machalow in gh-130849@footnote{https://github.com/python/cpython/issues/130849}.)

@item 
gh-127647@footnote{https://github.com/python/cpython/issues/127647}: Add protocols @ref{4c4,,io.Reader} and @ref{4c5,,io.Writer} as
alternatives to @ref{4c6,,typing.IO}, @ref{4c7,,typing.TextIO}, and
@ref{4c8,,typing.BinaryIO}.

@item 
gh-109798@footnote{https://github.com/python/cpython/issues/109798}: Added additional information into error messages in
@ref{33,,datetime}, and made the messages more consistent between the C and
Python implementations. Patch by Semyon Moroz.

@item 
gh-125746@footnote{https://github.com/python/cpython/issues/125746}: Delay deprecated @code{zipimport.zipimporter.load_module()}
removal time to 3.15. Use @ref{2e9,,zipimport.zipimporter.exec_module()}
instead.

@item 
gh-74028@footnote{https://github.com/python/cpython/issues/74028}: Add the optional @code{buffersize} parameter to
@ref{473,,concurrent.futures.Executor.map()} to limit the number of submitted
tasks whose results have not yet been yielded. If the buffer is full,
iteration over the `iterables' pauses until a result is yielded from the
buffer.

@item 
gh-124927@footnote{https://github.com/python/cpython/issues/124927}: Non-printing characters are now properly handled in the new
REPL.

@item 
gh-124096@footnote{https://github.com/python/cpython/issues/124096}: Turn on virtual terminal mode and enable bracketed paste in
REPL on Windows console. (If the terminal does not support bracketed
paste, enabling it does nothing.)

@item 
gh-89083@footnote{https://github.com/python/cpython/issues/89083}: Add @ref{53f,,uuid.uuid7()} for generating UUIDv7 objects as
specified in 
@geindex RFC; RFC 9562
RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html}. Patch by Bénédikt Tran.

@item 
gh-89083@footnote{https://github.com/python/cpython/issues/89083}: Add @ref{53e,,uuid.uuid6()} for generating UUIDv6 objects as
specified in 
@geindex RFC; RFC 9562
RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html}. Patch by Bénédikt Tran.

@item 
gh-117151@footnote{https://github.com/python/cpython/issues/117151}: Increase @code{io.DEFAULT_BUFFER_SIZE} from 8k to 128k and adjust
@ref{32b,,open()} on platforms where @ref{1145,,os.fstat()} provides a @code{st_blksize}
field (such as Linux) to use @code{max(min(blocksize, 8 MiB),
io.DEFAULT_BUFFER_SIZE)} rather than always using the device block size.
This should improve I/O performance. Patch by Romain Morotti.

@item 
gh-105499@footnote{https://github.com/python/cpython/issues/105499}: Make @ref{527,,types.UnionType} an alias for
@ref{341,,typing.Union}. Both @code{int | str} and @code{Union[int, str]} now
create instances of the same type. Patch by Jelle Zijlstra.

@item 
gh-93096@footnote{https://github.com/python/cpython/issues/93096}: Document the command-line for @ref{93,,mimetypes}. It now exits
with @code{1} on failure instead of @code{0} and @code{2} on incorrect command-line
parameters instead of @code{1}. Also, errors are printed to stderr instead of
stdout and their text is made tighter. Patch by Oleg Iarygin and Hugo van
Kemenade.
@end itemize

@node Documentation<10>,Core and Builtins<34>,Library<35>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id139}@anchor{1aba}
@subsubsection Documentation



@itemize -

@item 
gh-125722@footnote{https://github.com/python/cpython/issues/125722}: Require Sphinx 8.2.0 or later to build the Python
documentation. Patch by Adam Turner.

@item 
gh-129712@footnote{https://github.com/python/cpython/issues/129712}: The wheel tags supported by each macOS universal SDK option are
now documented.

@item 
gh-46236@footnote{https://github.com/python/cpython/issues/46236}: C API: Document @ref{1abb,,PyUnicode_RSplit()},
@ref{1abc,,PyUnicode_Partition()} and @ref{1abd,,PyUnicode_RPartition()}.
@end itemize

@node Core and Builtins<34>,Library<36>,Documentation<10>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id140}@anchor{1abe}
@subsubsection Core and Builtins



@itemize -

@item 
gh-131141@footnote{https://github.com/python/cpython/issues/131141}: Fix data race in @ref{e3,,sys.monitoring} instrumentation while
registering callback.

@item 
gh-130804@footnote{https://github.com/python/cpython/issues/130804}: Fix support of unicode characters on Windows in the new REPL.

@item 
gh-130932@footnote{https://github.com/python/cpython/issues/130932}: Fix incorrect exception handling in
@code{_PyModule_IsPossiblyShadowing}

@item 
gh-122029@footnote{https://github.com/python/cpython/issues/122029}: @ref{18a0,,sys.setprofile()} and @ref{55c,,sys.settrace()} will not
generate a @code{c_call} event for @code{INSTRUMENTED_CALL_FUNCTION_EX} if the
callable is a method with a C function wrapped, because we do not generate
@code{c_return} event in such case.

@item 
gh-129964@footnote{https://github.com/python/cpython/issues/129964}: Fix JIT crash on Windows on Arm. Patch by Diego Russo and
Brandt Bucher.

@item 
gh-130851@footnote{https://github.com/python/cpython/issues/130851}: Fix a crash in the @ref{487,,free threading} build when
constructing a @ref{1b,,code} object with @ref{1abf,,co_consts}
that contains instances of types that are not otherwise generated by the
bytecode compiler.

@item 
gh-128534@footnote{https://github.com/python/cpython/issues/128534}: Ensure that both left and right branches have the same source
for @code{async for} loops. Add these branches to the @code{co_branches()}
iterator.

@item 
gh-130794@footnote{https://github.com/python/cpython/issues/130794}: Fix memory leak in the @ref{487,,free threaded}
build when resizing a shared list or dictionary from multiple short-lived
threads.

@item 
gh-130415@footnote{https://github.com/python/cpython/issues/130415}: Improve JIT understanding of integers in boolean context.

@item 
gh-130382@footnote{https://github.com/python/cpython/issues/130382}: Fix @code{PyRefTracer_DESTROY} not being sent from
@code{Python/ceval.c} @code{Py_DECREF()}.

@item 
gh-130574@footnote{https://github.com/python/cpython/issues/130574}: Renumber @ref{7b4,,RESUME} from 149 to 128.

@item 
gh-124878@footnote{https://github.com/python/cpython/issues/124878}: Fix race conditions during runtime finalization that could lead
to accessing freed memory.

@item 
gh-130415@footnote{https://github.com/python/cpython/issues/130415}: Improve the experimental JIT’s ability to narrow boolean values
based on the results of truthiness tests.

@item 
gh-130618@footnote{https://github.com/python/cpython/issues/130618}: Fix a bug that was causing @code{UnicodeDecodeError} or
@code{SystemError} to be raised when using f-strings with @code{lambda}
expressions with non-ASCII characters. Patch by Pablo Galindo

@item 
gh-123044@footnote{https://github.com/python/cpython/issues/123044}: Make sure that the location of branch targets in @code{match}
cases is in the body, not the pattern.

@item 
gh-128534@footnote{https://github.com/python/cpython/issues/128534}: Add branch monitoring (@code{BRANCH_LEFT} and @code{BRANCH_RIGHT}
events) for @code{async for} loops.

@item 
gh-130163@footnote{https://github.com/python/cpython/issues/130163}: Fix possible crashes related to concurrent change and use of
the @ref{e2,,sys} module attributes.

@item 
gh-122029@footnote{https://github.com/python/cpython/issues/122029}: @code{INSTRUMENTED_CALL_KW} will expand the method before
monitoring to reflect the actual behavior more accurately.

@item 
gh-130415@footnote{https://github.com/python/cpython/issues/130415}: Improve JIT’s ability to optimize strings in boolean contexts.

@item 
gh-130396@footnote{https://github.com/python/cpython/issues/130396}: Use actual stack limits (from
@code{pthread_getattr_np(3)@footnote{https://manpages.debian.org/pthread_getattr_np(3)}}) for linux, and other systems with
@code{_GNU_SOURCE} defined, when determining limits for C stack protection.

@item 
gh-128396@footnote{https://github.com/python/cpython/issues/128396}: Fix a crash that occurs when calling @ref{28b,,locals()} inside an
inline comprehension that uses the same local variable as the outer frame
scope where the variable is a free or cell var.

@item 
gh-129107@footnote{https://github.com/python/cpython/issues/129107}: Fix two more @ref{1c6,,bytearray} functions for @ref{487,,free threading}.

@item 
gh-127705@footnote{https://github.com/python/cpython/issues/127705}: Use tagged references (@code{_PyStackRef}) for the default build
as well as for the free-threading build. This has a small negative
performance impact short-term but will enable larger speedups in the
future and significantly reduce maintenance costs by allowing a single
implementation of tagged references in the future.

@item 
gh-130094@footnote{https://github.com/python/cpython/issues/130094}: Fix two race conditions involving concurrent imports that could
lead to spurious failures with @ref{1be,,ModuleNotFoundError}.

@item 
gh-129107@footnote{https://github.com/python/cpython/issues/129107}: Make @ref{1c6,,bytearray} iterator safe under @ref{487,,free threading}.

@item 
gh-115802@footnote{https://github.com/python/cpython/issues/115802}: Use the more efficient «medium» code model for JIT-compiled
code on supported platforms.

@item 
gh-107956@footnote{https://github.com/python/cpython/issues/107956}: A @code{build-details.json} file is now install in the
platform-independent standard library directory (
@geindex Python Enhancement Proposals; PEP 739
PEP 739@footnote{https://peps.python.org/pep-0739/}
implementation).

@item 
gh-116042@footnote{https://github.com/python/cpython/issues/116042}: Fix location for SyntaxErrors of invalid escapes in the
tokenizer. Patch by Pablo Galindo

@item 
gh-91079@footnote{https://github.com/python/cpython/issues/91079}: Change C stack overflow protection to consider the amount of
stack consumed, rather than a counter. This allows deeper recursion in
many cases, but remains safe.

@item 
gh-129715@footnote{https://github.com/python/cpython/issues/129715}: Improve the experimental JIT’s handling of returns to unknown
callers.
@end itemize

@node Library<36>,Core and Builtins<35>,Core and Builtins<34>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id141}@anchor{1ac0}
@subsubsection Library



@itemize -

@item 
gh-129983@footnote{https://github.com/python/cpython/issues/129983}: Fix data race in compile_template in @code{sre.c}.
@end itemize

@node Core and Builtins<35>,Library<37>,Library<36>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id142}@anchor{1ac1}
@subsubsection Core and Builtins



@itemize -

@item 
gh-129967@footnote{https://github.com/python/cpython/issues/129967}: Fix a race condition in the @ref{487,,free threading} build when
@code{repr(set)} is called concurrently with @code{set.clear()}.

@item 
gh-129953@footnote{https://github.com/python/cpython/issues/129953}: The internal (evaluation) stack is now spilled to memory
whenever execution escapes from the interpreter or JIT compiled code. This
should have no observable effect in either Python or builtin extensions,
but will allow various important optimizations in the future.

@item 
gh-129515@footnote{https://github.com/python/cpython/issues/129515}: Clarify syntax error messages for conditional expressions when
a statement is specified before an @ref{322,,if} or after an
@ref{320,,else} keyword.

@item 
gh-129349@footnote{https://github.com/python/cpython/issues/129349}: @ref{434,,bytes.fromhex()} and @ref{435,,bytearray.fromhex()} now accepts
ASCII @ref{1c7,,bytes} and @ref{436,,bytes-like objects}.

@item 
gh-129149@footnote{https://github.com/python/cpython/issues/129149}: Add fast path for medium-size integers in
@ref{1ac2,,PyLong_FromSsize_t()}. Patch by Chris Eibl.

@item 
gh-129107@footnote{https://github.com/python/cpython/issues/129107}: Make the @ref{1c6,,bytearray} safe under @ref{487,,free threading}.

@item 
gh-128974@footnote{https://github.com/python/cpython/issues/128974}: Fix a crash in @ref{a0f,,UnicodeError.__str__}
when custom attributes implement @code{__str__()} with
side-effects. Patch by Bénédikt Tran.

@item 
gh-126085@footnote{https://github.com/python/cpython/issues/126085}: @ref{52a,,typing.TypeAliasType} now supports star unpacking.

@item 
gh-125331@footnote{https://github.com/python/cpython/issues/125331}: @code{from __future__ import barry_as_FLUFL} now works in more
contexts, including when it is used in files, with the @code{-c} flag, and in
the REPL when there are multiple statements on the same line. Previously,
it worked only on subsequent lines in the REPL, and when the appropriate
flags were passed directly to @ref{1c8,,compile()}. Patch by Pablo Galindo.

@item 
gh-121464@footnote{https://github.com/python/cpython/issues/121464}: Make concurrent iterations over the same @ref{1823,,enumerate()}
iterator safe under free-threading. See Strategy for Iterators in Free Threading@footnote{https://github.com/python/cpython/issues/124397}.

@item 
gh-87790@footnote{https://github.com/python/cpython/issues/87790}: Support underscore and comma as thousands separators in the
fractional part for floating-point presentation types of the new-style
string formatting (with @ref{439,,format()} or @ref{43a,,f-strings}).  Patch by
Sergey B Kirpichev.

@item 
gh-124445@footnote{https://github.com/python/cpython/issues/124445}: Fix specialization of generic aliases that are generic over a
@ref{295,,typing.ParamSpec} and have been specialized with a nested type
variable.

@item 
gh-120608@footnote{https://github.com/python/cpython/issues/120608}: Adapt @ref{c3c,,reversed()} for use in the free-threading build. The
@code{reversed()} is still not thread-safe in the sense that concurrent
iterations may see the same object, but they will not corrupt the
interpreter state.
@end itemize

@node Library<37>,Core and Builtins<36>,Core and Builtins<35>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id143}@anchor{1ac3}
@subsubsection Library



@itemize -

@item 
gh-100388@footnote{https://github.com/python/cpython/issues/100388}: Fix the @code{platform._sys_version()} method when @code{__DATE__} is
undefined at buildtime by changing default buildtime datetime string to
the UNIX epoch.
@end itemize

@node Core and Builtins<36>,C API<11>,Library<37>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id144}@anchor{1ac4}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-44369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44369}: Improve syntax errors for incorrectly closed strings. Patch by
Pablo Galindo
@end itemize

@node C API<11>,Build<10>,Core and Builtins<36>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id145}@anchor{1ac5}
@subsubsection C API



@itemize -

@item 
gh-111178@footnote{https://github.com/python/cpython/issues/111178}: Fix @ref{b46,,PyCMethod} API: replace @code{size_t nargs} with
@code{Py_ssize_t nargs} in @code{PyCMethod}. Patch by Victor Stinner.

@item 
gh-130947@footnote{https://github.com/python/cpython/issues/130947}: Add again @ref{1ac6,,PySequence_Fast()} to the limited C API. Patch
by Victor Stinner.

@item 
gh-128863@footnote{https://github.com/python/cpython/issues/128863}: The following private functions are deprecated and planned for
removal in Python 3.18:


@itemize *

@item 
@code{_PyUnicodeWriter_Init()}:
replace @code{_PyUnicodeWriter_Init(&writer)} with
@ref{5e1,,writer = PyUnicodeWriter_Create(0)}.

@item 
@code{_PyUnicodeWriter_Finish()}:
replace @code{_PyUnicodeWriter_Finish(&writer)} with
@ref{5e4,,PyUnicodeWriter_Finish(writer)}.

@item 
@code{_PyUnicodeWriter_Dealloc()}:
replace @code{_PyUnicodeWriter_Dealloc(&writer)} with
@ref{5e3,,PyUnicodeWriter_Discard(writer)}.

@item 
@code{_PyUnicodeWriter_WriteChar()}:
replace @code{_PyUnicodeWriter_WriteChar(&writer, ch)} with
@ref{5e7,,PyUnicodeWriter_WriteChar(writer@comma{} ch)}.

@item 
@code{_PyUnicodeWriter_WriteStr()}:
replace @code{_PyUnicodeWriter_WriteStr(&writer, str)} with
@ref{5e9,,PyUnicodeWriter_WriteStr(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_WriteSubstring()}:
replace @code{_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)} with
@ref{5ea,,PyUnicodeWriter_WriteSubstring(writer@comma{} str@comma{} start@comma{} end)}.

@item 
@code{_PyUnicodeWriter_WriteASCIIString()}:
replace @code{_PyUnicodeWriter_WriteASCIIString(&writer, str)} with
@ref{5ec,,PyUnicodeWriter_WriteUTF8(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_WriteLatin1String()}:
replace @code{_PyUnicodeWriter_WriteLatin1String(&writer, str)} with
@ref{5ec,,PyUnicodeWriter_WriteUTF8(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_Prepare()}: (no replacement).

@item 
@code{_PyUnicodeWriter_PrepareKind()}: (no replacement).
@end itemize

The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get these
new public functions on Python 3.13 and older.

Patch by Victor Stinner.

@item 
gh-45325@footnote{https://github.com/python/cpython/issues/45325}: Add a new @code{p} format parameter to @ref{5ee,,Py_BuildValue()} that
allows to take a C integer and produce a Python @ref{5ef,,bool} object.
Patch by Pablo Galindo.
@end itemize

@node Build<10>,,C API<11>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id146}@anchor{1ac7}
@subsubsection Build



@itemize -

@item 
gh-131035@footnote{https://github.com/python/cpython/issues/131035}: Use @code{-flto=thin} for faster build times using clang-cl on
Windows. Patch by Chris Eibl.

@item 
gh-130740@footnote{https://github.com/python/cpython/issues/130740}: Ensure that @code{Python.h} is included before @code{stdbool.h}
unless @code{pyconfig.h} is included before or in some platform-specific
contexts.

@item 
gh-130090@footnote{https://github.com/python/cpython/issues/130090}: Building with @code{PlatformToolset=ClangCL} on Windows now
supports PGO (profile guided optimization). Patch by Chris Eibl with
invaluable support from Steve Dover.

@item 
gh-129819@footnote{https://github.com/python/cpython/issues/129819}: Allow building the JIT with the tailcall interpreter.

@item 
gh-129989@footnote{https://github.com/python/cpython/issues/129989}: Fix a bug where the tailcall interpreter was enabled when
@code{--without-tail-call-interp} was provided to the configure script.

@item 
gh-129838@footnote{https://github.com/python/cpython/issues/129838}: Don’t redefine @code{_Py_NO_SANITIZE_UNDEFINED} when compiling
with a recent GCC version and undefined sanitizer enabled.

@item 
gh-82909@footnote{https://github.com/python/cpython/issues/82909}: @code{#pragma}-based linking with @code{python3*.lib} can now be
switched off with @ref{657,,Py_NO_LINK_LIB}. Patch by Jean-Christophe
Fillion-Robin.
@end itemize

@node Python 3 14 0 alpha 5,Python 3 14 0 alpha 4,Python 3 14 0 alpha 6,Changelog
@anchor{whatsnew/changelog python-3-14-0-alpha-5}@anchor{1ac8}
@subsection Python 3.14.0 alpha 5


`Release date: 2025-02-11'

@menu
* macOS: macOS<7>. 
* Tools/Demos: Tools/Demos<9>. 
* Tests: Tests<13>. 
* Security: Security<12>. 
* Library: Library<38>. 
* IDLE: IDLE<7>. 
* Documentation: Documentation<11>. 
* Core and Builtins: Core and Builtins<37>. 
* Library: Library<39>. 
* Core and Builtins: Core and Builtins<38>. 
* Library: Library<40>. 
* Core and Builtins: Core and Builtins<39>. 
* Library: Library<41>. 
* C API: C API<12>. 
* Build: Build<11>. 

@end menu

@node macOS<7>,Tools/Demos<9>,,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id147}@anchor{1ac9}
@subsubsection macOS



@itemize -

@item 
gh-91132@footnote{https://github.com/python/cpython/issues/91132}: Update macOS installer to use ncurses 6.5.
@end itemize

@node Tools/Demos<9>,Tests<13>,macOS<7>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id148}@anchor{1aca}
@subsubsection Tools/Demos



@itemize -

@item 
gh-129248@footnote{https://github.com/python/cpython/issues/129248}: The iOS test runner now strips the log prefix from each line
output by the test suite.

@item 
gh-104400@footnote{https://github.com/python/cpython/issues/104400}: Fix several bugs in extraction by switching to an AST parser in
@code{pygettext}.
@end itemize

@node Tests<13>,Security<12>,Tools/Demos<9>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id149}@anchor{1acb}
@subsubsection Tests



@itemize -

@item 
gh-129386@footnote{https://github.com/python/cpython/issues/129386}: Add @code{test.support.reset_code}, which can be used to reset
various bytecode-level optimizations and local instrumentation for a
function.

@item 
gh-128474@footnote{https://github.com/python/cpython/issues/128474}: Disable @code{test_embed} test cases that segfault on BOLT
instrument binaries. The tests are only disabled when BOLT is enabled.

@item 
gh-128003@footnote{https://github.com/python/cpython/issues/128003}: Add an option @code{--parallel-threads=N} to the regression test
runner that runs individual tests in multiple threads in parallel in order
to find concurrency bugs.  Note that most of the test suite is not yet
reviewed for thread-safety or annotated with @code{@@thread_unsafe} when
necessary.
@end itemize

@node Security<12>,Library<38>,Tests<13>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id150}@anchor{1acc}
@subsubsection Security



@itemize -

@item 
gh-105704@footnote{https://github.com/python/cpython/issues/105704}: When using @ref{2a3,,urllib.parse.urlsplit()} and
@ref{2a4,,urllib.parse.urlparse()} host parsing would not reject domain names
containing square brackets (@code{[} and @code{]}). Square brackets are only
valid for IPv6 and IPvFuture hosts according to RFC 3986 Section 3.2.2@footnote{https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2}.

@item 
gh-126108@footnote{https://github.com/python/cpython/issues/126108}: Fix a possible @code{NULL} pointer dereference in
@code{PySys_AddWarnOptionUnicode()}.

@item 
gh-80222@footnote{https://github.com/python/cpython/issues/80222}: Fix bug in the folding of quoted strings when flattening an
email message using a modern email policy. Previously when a quoted string
was folded so that it spanned more than one line, the surrounding quotes
and internal escapes would be omitted. This could theoretically be used to
spoof header lines using a carefully constructed quoted string if the
resulting rendered email was transmitted or re-parsed.

@item 
gh-119511@footnote{https://github.com/python/cpython/issues/119511}: Fix a potential denial of service in the @ref{77,,imaplib} module.
When connecting to a malicious server, it could cause an arbitrary amount
of memory to be allocated. On many systems this is harmless as unused
virtual memory is only a mapping, but if this hit a virtual address size
limit it could lead to a @ref{18fa,,MemoryError} or other process crash. On
unusual systems or builds where all allocated memory is touched and backed
by actual ram or storage it could’ve consumed resources doing so until
similarly crashing.
@end itemize

@node Library<38>,IDLE<7>,Security<12>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id151}@anchor{1acd}
@subsubsection Library



@itemize -

@item 
gh-129939@footnote{https://github.com/python/cpython/issues/129939}: Comparison pages with highlighted changes generated by the
@ref{214,,difflib.HtmlDiff} class now support dark mode.

@item 
gh-129928@footnote{https://github.com/python/cpython/issues/129928}: Raise @ref{57d,,sqlite3.ProgrammingError} if a user-defined SQL
function with invalid number of parameters is created. Patch by Erlend
Aasland.

@item 
gh-129583@footnote{https://github.com/python/cpython/issues/129583}: Update bundled pip to 25.0.1

@item 
gh-129766@footnote{https://github.com/python/cpython/issues/129766}: Fix crash in @ref{11b,,warnings}, when calling @code{_release_lock()}
with no existing lock.

@item 
gh-129005@footnote{https://github.com/python/cpython/issues/129005}: @code{_pyio.FileIO.readall()} now allocates, resizes, and fills a
data buffer using the same algorithm @code{_io.FileIO.readall()} uses.

@item 
gh-129646@footnote{https://github.com/python/cpython/issues/129646}: Update the locale alias mapping in the @ref{89,,locale} module to
match the latest X Org locale alias mapping and support new locales in
Glibc 2.41.

@item 
gh-128317@footnote{https://github.com/python/cpython/issues/128317}: Put CLI calendar highlighting in private class, removing
@code{highlight_day} from public @ref{1a3e,,calendar.TextCalendar} API. Patch by
Hugo van Kemenade.

@item 
gh-129603@footnote{https://github.com/python/cpython/issues/129603}: Fix bugs where @ref{1222,,sqlite3.Row} objects could segfault if
their inherited @ref{1ace,,description} was set to @code{None}.
Patch by Erlend Aasland.

@item 
gh-129559@footnote{https://github.com/python/cpython/issues/129559}: Add @ref{1928,,bytearray.resize()} method so @ref{1c6,,bytearray} can
be efficiently resized in place.

@item 
gh-129502@footnote{https://github.com/python/cpython/issues/129502}: Unlikely errors in preparing arguments for @ref{2d,,ctypes}
callback are now handled in the same way as errors raised in the callback
of in converting the result of the callback – using
@ref{70c,,sys.unraisablehook()} instead of @ref{be5,,sys.excepthook()} and not
setting @ref{8ce,,sys.last_exc} and other variables.

@item 
gh-129403@footnote{https://github.com/python/cpython/issues/129403}: Corrected @ref{277,,ValueError} message for
@ref{9f7,,asyncio.Barrier} and @ref{158c,,threading.Barrier}.

@item 
gh-129409@footnote{https://github.com/python/cpython/issues/129409}: Fix an integer overflow in the @ref{2c,,csv} module when writing a
data field larger than 2GB.

@item 
gh-126400@footnote{https://github.com/python/cpython/issues/126400}: Add a socket `timeout' keyword argument to
@ref{a4c,,logging.handlers.SysLogHandler}.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Always lazy import @code{warnings} in @ref{f6,,threading}. Patch by
Taneli Hukkinen.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve import time of @ref{df,,subprocess} by lazy importing
@code{locale} and @code{signal}. Patch by Taneli Hukkinen.

@item 
gh-129346@footnote{https://github.com/python/cpython/issues/129346}: In @ref{d7,,sqlite3}, handle out-of-memory when creating
user-defined SQL functions.

@item 
gh-129005@footnote{https://github.com/python/cpython/issues/129005}: Optimize @code{_pyio.FileIO.readinto} by avoiding unnecessary
objects and copies using @ref{4eb,,os.readinto()}.

@item 
gh-129195@footnote{https://github.com/python/cpython/issues/129195}: Support reporting call graph information from
@code{asyncio.staggered.staggered_race()}.

@item 
gh-129205@footnote{https://github.com/python/cpython/issues/129205}: Add @ref{4eb,,os.readinto()} to read into a @ref{311,,buffer object} from a file descriptor.

@item 
gh-128772@footnote{https://github.com/python/cpython/issues/128772}: Fix @ref{bd,,pydoc} for methods with the @code{__module__} attribute
equal to @code{None}.

@item 
gh-129061@footnote{https://github.com/python/cpython/issues/129061}: Fix FORCE_COLOR and NO_COLOR when empty strings. Patch by Hugo
van Kemenade.

@item 
gh-92897@footnote{https://github.com/python/cpython/issues/92897}: Scheduled the deprecation of the @code{check_home} argument of
@ref{2dd,,sysconfig.is_python_build()} to Python 3.15.

@item 
gh-129064@footnote{https://github.com/python/cpython/issues/129064}: Deprecate @code{sysconfig.expand_makefile_vars()}, in favor of
using @ref{156,,sysconfig.get_paths()} with the @code{vars} argument.

@item 
gh-128550@footnote{https://github.com/python/cpython/issues/128550}: Removed an incorrect optimization relating to eager tasks in
@ref{6d7,,asyncio.TaskGroup} that resulted in cancellations being missed.

@item 
gh-128991@footnote{https://github.com/python/cpython/issues/128991}: Release the enter frame reference within @ref{10,,bdb} callback

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Reduce import time of @ref{b8,,pstats} and @ref{13a,,zipfile} by up to
20%, by removing unnecessary imports to @ref{10d,,typing}. Patch by Bénédikt
Tran.

@item 
gh-128978@footnote{https://github.com/python/cpython/issues/128978}: Fix a @ref{665,,NameError} in
@code{sysconfig.expand_makefile_vars()}. Patch by Bénédikt Tran.

@item 
gh-128961@footnote{https://github.com/python/cpython/issues/128961}: Fix a crash when setting state on an exhausted
@ref{6c5,,array.array} iterator.

@item 
gh-128894@footnote{https://github.com/python/cpython/issues/128894}: Fix @code{traceback.TracebackException._format_syntax_error} not
to fail on exceptions with custom metadata.

@item 
gh-128916@footnote{https://github.com/python/cpython/issues/128916}: Do not attempt to set @code{SO_REUSEPORT} on sockets of address
families other than @code{AF_INET} and @code{AF_INET6}, as it is meaningless
with these address families, and the call with fail with Linux kernel
6.12.9 and newer.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve import time of @ref{105,,tomllib} by removing @code{typing},
@code{string}, and @code{tomllib._types} imports. Patch by Taneli Hukkinen.

@item 
gh-128679@footnote{https://github.com/python/cpython/issues/128679}: @ref{108,,tracemalloc}: Fix race conditions when
@ref{1acf,,tracemalloc.stop()} is called by a thread, while other threads are
tracing memory allocations. Patch by Victor Stinner.

@item 
gh-128891@footnote{https://github.com/python/cpython/issues/128891}: Add specialized opcodes to @code{opcode.opname}.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Reduce import time of @ref{66,,gettext} by up to ten times, by
importing @ref{c1,,re} on demand. In particular, @code{re} is no longer
implicitly exposed as @code{gettext.re}. Patch by Eli Schwartz.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Reduce the import time of @ref{a4,,optparse} when no help text is
printed. Patch by Eli Schwartz.

@item 
gh-128657@footnote{https://github.com/python/cpython/issues/128657}: Fix possible extra reference when using objects returned by
@ref{2f3,,hashlib.sha256()} under @ref{487,,free threading}.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Reduce the import time of @ref{2c,,csv} by up to five times, by
importing @ref{c1,,re} on demand. In particular, @code{re} is no more implicitly
exposed as @code{csv.re}. Patch by Bénédikt Tran.

@item 
gh-128308@footnote{https://github.com/python/cpython/issues/128308}: Support the `name' keyword argument for eager tasks in
@ref{463,,asyncio.loop.create_task()},  @ref{462,,asyncio.create_task()} and
@ref{464,,asyncio.TaskGroup.create_task()}, by passing on all `kwargs' to the
task factory set by @ref{461,,asyncio.loop.set_task_factory()}.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve the performance of @ref{1f1,,base64.b16decode()} by up to
ten times by more efficiently checking the byte-string for hexadecimal
digits. Reduce the import time of @ref{f,,base64} by up to six times, by no
longer importing @ref{c1,,re}. Patch by Bénédikt Tran, Chris Markiewicz, and
Adam Turner.

@item 
gh-128156@footnote{https://github.com/python/cpython/issues/128156}: When using macOS system @code{libffi}, support for complex types
in @ref{2d,,ctypes} is now checked at runtime (macOS 10.15 or newer). The
types must also be available at build time.

@item 
gh-128636@footnote{https://github.com/python/cpython/issues/128636}: Fix PyREPL failure when @ref{4e5,,os.environ} is overwritten with
an invalid value.

@item 
gh-128498@footnote{https://github.com/python/cpython/issues/128498}: Default to stdout isatty for color detection instead of stderr.
Patch by Hugo van Kemenade.

@item 
gh-128384@footnote{https://github.com/python/cpython/issues/128384}: Add locking to @ref{11b,,warnings} to avoid some data races when
free-threading is used.  Change @code{_warnings_runtime_state.mutex} to be a
recursive mutex and expose it to @code{warnings}, via the
@code{_acquire_lock()} and @code{_release_lock()} functions. The lock is
held when @code{filters} and @code{_filters_version} are updated.

@item 
gh-128509@footnote{https://github.com/python/cpython/issues/128509}: Add @ref{517,,sys._is_immortal()} for identifying @ref{398,,immortal}
objects at runtime.

@item 
gh-128479@footnote{https://github.com/python/cpython/issues/128479}: Fix @code{asyncio.staggered.staggered_race()} leaking tasks and
issuing an unhandled exception.

@item 
gh-128427@footnote{https://github.com/python/cpython/issues/128427}: @ref{541,,uuid.NIL} and @ref{542,,uuid.MAX} are now available to
represent the Nil and Max UUID formats as defined by 
@geindex RFC; RFC 9562
RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html}.

@item 
gh-91279@footnote{https://github.com/python/cpython/issues/91279}: @ref{548,,zipfile.ZipFile.writestr()} now respect
@code{SOURCE_DATE_EPOCH} that distributions can set centrally and have build
tools consume this in order to produce reproducible output.

@item 
gh-112064@footnote{https://github.com/python/cpython/issues/112064}: Fix incorrect handling of negative read sizes in
@ref{1ad0,,HTTPResponse.read}. Patch by Yury
Manushkin.

@item 
gh-58956@footnote{https://github.com/python/cpython/issues/58956}: Fixed a frame reference leak in @ref{10,,bdb}.

@item 
gh-128131@footnote{https://github.com/python/cpython/issues/128131}: Completely support random access of uncompressed unencrypted
read-only zip files obtained by @ref{84a,,ZipFile.open}.

@item 
gh-127975@footnote{https://github.com/python/cpython/issues/127975}: Avoid reusing quote types in @ref{cb6,,ast.unparse()} if not needed.

@item 
gh-115514@footnote{https://github.com/python/cpython/issues/115514}: Fix exceptions and incomplete writes after
@code{asyncio._SelectorTransport} is closed before writes are
completed.

@item 
gh-121604@footnote{https://github.com/python/cpython/issues/121604}: Add missing Deprecation warnings for
@ref{1ad1,,importlib.machinery.DEBUG_BYTECODE_SUFFIXES},
@ref{1ad2,,importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES},
@ref{10e2,,importlib.machinery.WindowsRegistryFinder},
@ref{fa7,,importlib.abc.ResourceLoader},
@ref{1532,,importlib.abc.SourceLoader.path_mtime()}.

@item 
gh-127873@footnote{https://github.com/python/cpython/issues/127873}: When @code{-E} is set, only ignore @code{PYTHON_COLORS} and not
@code{FORCE_COLOR}/@code{NO_COLOR}/@code{TERM} when colourising output. Patch by
Hugo van Kemenade.

@item 
gh-125413@footnote{https://github.com/python/cpython/issues/125413}: Add @ref{4f3,,pathlib.Path.info} attribute, which stores an object
implementing the @ref{4f4,,pathlib.types.PathInfo} protocol (also new). The
object supports querying the file type and internally caching
@ref{4f5,,stat()} results. Path objects generated by
@ref{4f6,,iterdir()} are initialized with file type information
gleaned from scanning the parent directory.

@item 
gh-127712@footnote{https://github.com/python/cpython/issues/127712}: Fix handling of the @code{secure} argument of
@ref{1ad3,,logging.handlers.SMTPHandler}.

@item 
gh-127096@footnote{https://github.com/python/cpython/issues/127096}: Do not recreate unnamed section on every read in
@ref{6e4,,configparser.ConfigParser}. Patch by Andrey Efremov.

@item 
gh-124369@footnote{https://github.com/python/cpython/issues/124369}: Deprecate @code{pdb.Pdb.curframe_locals}

@item 
gh-126332@footnote{https://github.com/python/cpython/issues/126332}: Fix _pyrepl crash when entering a double CTRL-Z on an
overflowing line.

@item 
gh-125553@footnote{https://github.com/python/cpython/issues/125553}: Fix round-trip invariance for backslash continuations in
@ref{1ad4,,tokenize.untokenize()}.

@item 
gh-91048@footnote{https://github.com/python/cpython/issues/91048}: Add @ref{465,,asyncio.capture_call_graph()} and
@ref{466,,asyncio.print_call_graph()} functions.

@item 
gh-124703@footnote{https://github.com/python/cpython/issues/124703}: Quitting @ref{aa,,pdb} in @code{inline} mode will emit a confirmation
prompt and exit gracefully now, instead of printing an exception
traceback.

@item 
gh-123987@footnote{https://github.com/python/cpython/issues/123987}: Fixed issue in NamespaceReader where a non-path item in a
namespace path, such as a sentinel added by an editable installer, would
break resource loading.

@item 
gh-119349@footnote{https://github.com/python/cpython/issues/119349}: Add the @ref{483,,ctypes.util.dllist()} function to list the loaded
shared libraries for the current process.

@item 
gh-55454@footnote{https://github.com/python/cpython/issues/55454}: Add IMAP4 @code{IDLE} support to the @ref{77,,imaplib} module.  Patch
by Forest.

@item 
gh-119257@footnote{https://github.com/python/cpython/issues/119257}: Show tab completions menu below the current line, which results
in less janky behaviour, and fixes a cursor movement bug. Patch by Daniel
Hollas

@item 
gh-101410@footnote{https://github.com/python/cpython/issues/101410}: Support custom messages for domain errors in the @ref{91,,math}
module (@ref{dc8,,math.sqrt()}, @ref{1862,,math.log()} and @ref{177a,,math.atanh()} were
modified as examples).  Patch by Charlie Zhao and Sergey B Kirpichev.

@item 
gh-81340@footnote{https://github.com/python/cpython/issues/81340}: Use @ref{1ad5,,os.copy_file_range()} in @ref{e1e,,shutil.copy()},
@ref{e1f,,shutil.copy2()}, and @ref{e1d,,shutil.copyfile()} functions by default. An
underlying Linux system call gives filesystems an opportunity to implement
the use of copy-on-write (in case of btrfs and XFS) or server-side copy
(in the case of NFS.) Patch by Illia Volochii.

@item 
bpo-27307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27307}: Add attribute and item access support to
@ref{126b,,string.Formatter} in auto-numbering mode, which allows format
strings like “@{.name@}” and “@{[1]@}”.
@end itemize

@node IDLE<7>,Documentation<11>,Library<38>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id152}@anchor{1ad6}
@subsubsection IDLE



@itemize -

@item 
gh-129873@footnote{https://github.com/python/cpython/issues/129873}: Simplify displaying the IDLE doc by only copying the text
section of idle.html to idlelib/help.html. Patch by Stan Ulbrych.
@end itemize

@node Documentation<11>,Core and Builtins<37>,IDLE<7>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id153}@anchor{1ad7}
@subsubsection Documentation



@itemize -

@item 
gh-125722@footnote{https://github.com/python/cpython/issues/125722}: Require Sphinx 8.1.3 or later to build the Python
documentation. Patch by Adam Turner.

@item 
gh-67206@footnote{https://github.com/python/cpython/issues/67206}: Document that @ref{1ad8,,string.printable} is not printable in the
POSIX sense. In particular, @ref{1191,,string.printable.isprintable()} returns @ref{ef5,,False}. Patch by Bénédikt Tran.
@end itemize

@node Core and Builtins<37>,Library<39>,Documentation<11>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id154}@anchor{1ad9}
@subsubsection Core and Builtins



@itemize -

@item 
gh-100239@footnote{https://github.com/python/cpython/issues/100239}: Replace the opcode BINARY_SUBSCR and its family by BINARY_OP
with oparg NB_SUBSCR.

@item 
gh-129732@footnote{https://github.com/python/cpython/issues/129732}: Fixed a race in @code{_Py_qsbr_reserve} in the free threading
build.

@item 
gh-129763@footnote{https://github.com/python/cpython/issues/129763}: Remove the internal @code{LLTRACE} macro (use @ref{19eb,,Py_DEBUG}
instead).

@item 
gh-129715@footnote{https://github.com/python/cpython/issues/129715}: Improve JIT performance for generators.

@item 
gh-129643@footnote{https://github.com/python/cpython/issues/129643}: Fix thread safety of @ref{1ada,,PyList_Insert()} in free-threading
builds.

@item 
gh-129668@footnote{https://github.com/python/cpython/issues/129668}: Fix race condition when raising @ref{18fa,,MemoryError} in the free
threaded build.

@item 
gh-129643@footnote{https://github.com/python/cpython/issues/129643}: Fix thread safety of @ref{1adb,,PyList_SetItem()} in free-threading
builds. Patch by Kumar Aditya.

@item 
gh-128563@footnote{https://github.com/python/cpython/issues/128563}: Fix an issue where the «lltrace» debug feature could have been
incorrectly enabled for some frames.

@item 
gh-129393@footnote{https://github.com/python/cpython/issues/129393}: On FreeBSD, @ref{518,,sys.platform} doesn’t contain the major
version anymore. It is always @code{'freebsd'}, instead of @code{'freebsd13'} or
@code{'freebsd14'}.
@end itemize

@node Library<39>,Core and Builtins<38>,Core and Builtins<37>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id155}@anchor{1adc}
@subsubsection Library



@itemize -

@item 
gh-129345@footnote{https://github.com/python/cpython/issues/129345}: Fix null pointer dereference in @ref{94b,,syslog.openlog()} when an
audit hook raises an exception.
@end itemize

@node Core and Builtins<38>,Library<40>,Library<39>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id156}@anchor{1add}
@subsubsection Core and Builtins



@itemize -

@item 
gh-129231@footnote{https://github.com/python/cpython/issues/129231}: Improve memory layout of JIT traces. Patch by Diego Russo

@item 
gh-129149@footnote{https://github.com/python/cpython/issues/129149}: Add fast path for medium-size integers in
@ref{1ade,,PyLong_FromUnsignedLong()}, @ref{1adf,,PyLong_FromUnsignedLongLong()}
and @ref{1ae0,,PyLong_FromSize_t()}.

@item 
gh-129201@footnote{https://github.com/python/cpython/issues/129201}: The free-threaded version of the cyclic garbage collector has
been optimized to conditionally use CPU prefetch instructions during the
collection.  This can reduce collection times by making it more likely
that data is in the CPU cache when it is needed.  The prefetch
instructions are enabled if the number of long-lived objects (objects
surviving a full collection) exceeds a threshold.

@item 
gh-129093@footnote{https://github.com/python/cpython/issues/129093}: Fix f-strings such as @code{f'@{expr=@}'} sometimes not displaying
the full expression when the expression contains @code{!=}.

@item 
gh-124363@footnote{https://github.com/python/cpython/issues/124363}: Treat debug expressions in f-string as raw strings. Patch by
Pablo Galindo

@item 
gh-128714@footnote{https://github.com/python/cpython/issues/128714}: Fix the potential races in get/set dunder methods
@code{__annotations__}, @code{__annotate__} and @code{__type_params__} for function
object, and add related tests.

@item 
gh-128799@footnote{https://github.com/python/cpython/issues/128799}: Add frame of @code{except*} to traceback when it wraps a naked
exception.

@item 
gh-128842@footnote{https://github.com/python/cpython/issues/128842}: Collect JIT memory stats using pystats. Patch by Diego Russo.

@item 
gh-100239@footnote{https://github.com/python/cpython/issues/100239}: Specialize @code{BINARY_OP} for bitwise logical operations on
compact ints.

@item 
gh-128910@footnote{https://github.com/python/cpython/issues/128910}: Undocumented and unused private C-API functions
@code{_PyTrash_begin} and @code{_PyTrash_end} are removed.

@item 
gh-128807@footnote{https://github.com/python/cpython/issues/128807}: Add a marking phase to the free-threaded GC.  This is similar
to what was done in gh-126491@footnote{https://github.com/python/cpython/issues/126491}.  Since the free-threaded GC does not have
generations and is not incremental, the marking phase looks for all
objects reachable from known roots.  The roots are objects known to not be
garbage, like the module dictionary for @ref{e2,,sys}.  For most programs,
this marking phase should make the GC a bit faster since typically less
work is done per object.

@item 
gh-100239@footnote{https://github.com/python/cpython/issues/100239}: Add opcode @code{BINARY_OP_EXTEND} which executes a pair of
functions (guard and specialization functions) accessed from the inline
cache.

@item 
gh-128563@footnote{https://github.com/python/cpython/issues/128563}: A new type of interpreter has been added to CPython. This
interpreter uses tail calls for its instruction handlers. Preliminary
benchmark results suggest 7-11% geometric mean faster on pyperformance
(depending on platform), and up to 30% faster on Python-intensive
workloads. This interpreter currently only works on newer compilers, such
as @code{clang-19}. Other compilers will continue using the old interpreter.
Patch by Ken Jin, with ideas on how to implement this in CPython by Mark
Shannon, Garret Gu, Haoran Xu, and Josh Haberman.

@item 
gh-126703@footnote{https://github.com/python/cpython/issues/126703}: Improve performance of iterating over lists and tuples by using
a freelist for the iterator objects.

@item 
gh-127953@footnote{https://github.com/python/cpython/issues/127953}: The time to handle a @code{LINE} event in sys.monitoring (and
sys.settrace) is now independent of the number of lines in the code
object.

@item 
gh-128330@footnote{https://github.com/python/cpython/issues/128330}: Restore terminal control characters on REPL exit.

@item 
gh-128016@footnote{https://github.com/python/cpython/issues/128016}: Improved the @code{SyntaxWarning} message for invalid escape
sequences to clarify that such sequences will raise a @code{SyntaxError} in
future Python releases. The new message also suggests a potential fix,
i.e., @code{Did you mean "\\e"?}.

@item 
gh-126004@footnote{https://github.com/python/cpython/issues/126004}: Fix handling of @ref{1ae1,,UnicodeError.start} and
@ref{1ae2,,UnicodeError.end} values in the @ref{1ae3,,codecs.replace_errors()} error
handler. Patch by Bénédikt Tran.

@item 
gh-126004@footnote{https://github.com/python/cpython/issues/126004}: Fix handling of @ref{1ae1,,UnicodeError.start} and
@ref{1ae2,,UnicodeError.end} values in the
@ref{1ae4,,codecs.backslashreplace_errors()} error handler. Patch by Bénédikt
Tran.

@item 
gh-126004@footnote{https://github.com/python/cpython/issues/126004}: Fix handling of @ref{1ae1,,UnicodeError.start} and
@ref{1ae2,,UnicodeError.end} values in the
@ref{1ae5,,codecs.xmlcharrefreplace_errors()} error handler. Patch by Bénédikt
Tran.

@item 
gh-127119@footnote{https://github.com/python/cpython/issues/127119}: Slightly optimize the @ref{326,,int} deallocator.

@item 
gh-127349@footnote{https://github.com/python/cpython/issues/127349}: Fixed the error when resizing terminal in Python REPL. Patch by
Semyon Moroz.

@item 
gh-125723@footnote{https://github.com/python/cpython/issues/125723}: Fix crash with @code{gi_frame.f_locals} when generator frames
outlive their generator. Patch by Mikhail Efimov.
@end itemize

@node Library<40>,Core and Builtins<39>,Core and Builtins<38>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id157}@anchor{1ae6}
@subsubsection Library



@itemize -

@item 
gh-126349@footnote{https://github.com/python/cpython/issues/126349}: Add @ref{523,,turtle.fill()}, @ref{524,,turtle.poly()} and
@ref{525,,turtle.no_animation()} context managers. Patch by Marie Roald and
Yngve Mardal Moe.
@end itemize

@node Core and Builtins<39>,Library<41>,Library<40>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id158}@anchor{1ae7}
@subsubsection Core and Builtins



@itemize -

@item 
gh-115911@footnote{https://github.com/python/cpython/issues/115911}: If the current working directory cannot be determined due to
permissions, then import will no longer raise @ref{10f9,,PermissionError}.
Patch by Alex Willmer.
@end itemize

@node Library<41>,C API<12>,Core and Builtins<39>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id159}@anchor{1ae8}
@subsubsection Library



@itemize -

@item 
gh-112713@footnote{https://github.com/python/cpython/issues/112713}: Added support for the @code{Partitioned} cookie flag in
@ref{74,,http.cookies}.
@end itemize

@node C API<12>,Build<11>,Library<41>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id160}@anchor{1ae9}
@subsubsection C API



@itemize -

@item 
gh-129533@footnote{https://github.com/python/cpython/issues/129533}: Update @ref{c7a,,PyGC_Enable()}, @ref{c7b,,PyGC_Disable()},
@ref{c7c,,PyGC_IsEnabled()} to use atomic operation for thread-safety at
free-threading build. Patch by Donghee Na.

@item 
gh-89188@footnote{https://github.com/python/cpython/issues/89188}: Implement @ref{1526,,PyUnicode_KIND()} and @ref{1522,,PyUnicode_DATA()}
as function, in addition to the macros with the same names. The macros
rely on C bit fields which have compiler-specific layout. Patch by Victor
Stinner.

@item 
gh-91417@footnote{https://github.com/python/cpython/issues/91417}: Remove @ref{1ac6,,PySequence_Fast()} from the limited C API, since
this function has to be used with @ref{5f7,,PySequence_Fast_GET_ITEM}
which never worked in the limited C API. Patch by Victor Stinner.

@item 
gh-128509@footnote{https://github.com/python/cpython/issues/128509}: Add @ref{5f0,,PyUnstable_IsImmortal()} for determining whether an
object is @ref{398,,immortal}.

@item 
gh-129033@footnote{https://github.com/python/cpython/issues/129033}: Remove @code{_PyInterpreterState_GetConfigCopy()} and
@code{_PyInterpreterState_SetConfig()} private functions. Use instead
@ref{3a6,,PyConfig_Get()} and @ref{5aa,,PyConfig_Set()}, public C API added by
@geindex Python Enhancement Proposals; PEP 741
PEP 741@footnote{https://peps.python.org/pep-0741/} «Python Configuration C API». Patch by Victor Stinner.

@item 
gh-129033@footnote{https://github.com/python/cpython/issues/129033}: Remove the private @code{_Py_InitializeMain()} function. It was a
@ref{5fd,,provisional API} added to Python 3.8 by 
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/}. Patch by Victor
Stinner.

@item 
gh-128844@footnote{https://github.com/python/cpython/issues/128844}: Add @ref{1aea,,PyUnstable_TryIncRef()} and
@ref{1aeb,,PyUnstable_EnableTryIncRef()} unstable APIs.  These are helpers for
dealing with unowned references in a thread-safe way, particularly in the
free threading build.

@item 
gh-128911@footnote{https://github.com/python/cpython/issues/128911}: Add @ref{5c3,,PyImport_ImportModuleAttr()} and
@ref{5c4,,PyImport_ImportModuleAttrString()} helper functions to import a
module and get an attribute of the module. Patch by Victor Stinner.

@item 
gh-128863@footnote{https://github.com/python/cpython/issues/128863}: The following private functions are deprecated and planned for
removal in Python 3.18:


@itemize *

@item 
@code{_PyBytes_Join()}: use @ref{5b0,,PyBytes_Join()}.

@item 
@code{_PyDict_GetItemStringWithError()}: use @ref{634,,PyDict_GetItemStringRef()}.

@item 
@code{_PyDict_Pop()}: use @ref{635,,PyDict_Pop()}.

@item 
@code{_PyLong_Sign()}: use @ref{5c7,,PyLong_GetSign()}.

@item 
@code{_PyLong_FromDigits()} and @code{_PyLong_New()}:
use @ref{5d7,,PyLongWriter_Create()}.

@item 
@code{_PyThreadState_UncheckedGet()}: use @ref{636,,PyThreadState_GetUnchecked()}.

@item 
@code{_PyUnicode_AsString()}: use @ref{637,,PyUnicode_AsUTF8()}.

@item 
@code{_Py_HashPointer()}: use @ref{638,,Py_HashPointer()}.

@item 
@code{_Py_fopen_obj()}: use @ref{5c0,,Py_fopen()}.
@end itemize

The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get these
new public functions on Python 3.13 and older.

Patch by Victor Stinner.

@item 
gh-126599@footnote{https://github.com/python/cpython/issues/126599}: Remove some internal test APIs for the experimental JIT
compiler.

@item 
gh-127925@footnote{https://github.com/python/cpython/issues/127925}: Convert the @ref{39,,decimal} module to use 
@geindex Python Enhancement Proposals; PEP 757
PEP 757@footnote{https://peps.python.org/pep-0757/} C API
(export-import integers), offering some speed-up if the integer part of
the @ref{1c2,,Decimal} instance is small.  Patch by Sergey B
Kirpichev.
@end itemize

@node Build<11>,,C API<12>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id161}@anchor{1aec}
@subsubsection Build



@itemize -

@item 
gh-129660@footnote{https://github.com/python/cpython/issues/129660}: Drop @code{test_embed} from PGO training, whose contribution in
recent versions is considered to be ignorable.

@item 
gh-128902@footnote{https://github.com/python/cpython/issues/128902}: Fix compile errors with Clang 9 and older due to lack of
@code{__attribute__((fallthrough))} support.
@end itemize

@node Python 3 14 0 alpha 4,Python 3 14 0 alpha 3,Python 3 14 0 alpha 5,Changelog
@anchor{whatsnew/changelog python-3-14-0-alpha-4}@anchor{1aed}
@subsection Python 3.14.0 alpha 4


`Release date: 2025-01-14'

@menu
* macOS: macOS<8>. 
* Tools/Demos: Tools/Demos<10>. 
* Tests: Tests<14>. 
* Library: Library<42>. 
* Core and Builtins: Core and Builtins<40>. 
* Library: Library<43>. 
* Core and Builtins: Core and Builtins<41>. 
* Library: Library<44>. 
* Core and Builtins: Core and Builtins<42>. 
* C API: C API<13>. 
* Build: Build<12>. 

@end menu

@node macOS<8>,Tools/Demos<10>,,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id162}@anchor{1aee}
@subsubsection macOS



@itemize -

@item 
gh-127592@footnote{https://github.com/python/cpython/issues/127592}: Usage of the unified Apple System Log APIs was disabled when
the minimum macOS version is earlier than 10.12.
@end itemize

@node Tools/Demos<10>,Tests<14>,macOS<8>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id163}@anchor{1aef}
@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<14>,Library<42>,Tools/Demos<10>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id164}@anchor{1af0}
@subsubsection Tests



@itemize -

@item 
gh-128690@footnote{https://github.com/python/cpython/issues/128690}: Temporarily do not use test_embed in PGO profile builds until
the problem with test_init_pyvenv_cfg failing in some configurations is
resolved.
@end itemize

@node Library<42>,Core and Builtins<40>,Tests<14>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id165}@anchor{1af1}
@subsubsection Library



@itemize -

@item 
gh-128731@footnote{https://github.com/python/cpython/issues/128731}: Fix @ref{74f,,ResourceWarning} in
@ref{1af2,,urllib.robotparser.RobotFileParser.read()}.

@item 
gh-71339@footnote{https://github.com/python/cpython/issues/71339}: Add new assertion methods for @ref{10f,,unittest}:
@ref{530,,assertHasAttr()},
@ref{531,,assertNotHasAttr()},
@ref{532,,assertIsSubclass()},
@ref{533,,assertNotIsSubclass()}
@ref{534,,assertStartsWith()},
@ref{535,,assertNotStartsWith()},
@ref{536,,assertEndsWith()} and
@ref{537,,assertNotEndsWith()}.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve import time of @ref{ab,,pickle} by 25% by removing an
unnecessary regular expression. As such, @ref{c1,,re} is no more implicitly
available as @code{pickle.re}. Patch by Bénédikt Tran.

@item 
gh-128661@footnote{https://github.com/python/cpython/issues/128661}: Fixes @ref{151,,typing.evaluate_forward_ref()} not showing
deprecation when @code{type_params} arg is not passed.

@item 
gh-128562@footnote{https://github.com/python/cpython/issues/128562}: Fix possible conflicts in generated @ref{f9,,tkinter} widget names
if the widget class name ends with a digit.

@item 
gh-128559@footnote{https://github.com/python/cpython/issues/128559}: Improved import time of @ref{b,,asyncio}.

@item 
gh-128552@footnote{https://github.com/python/cpython/issues/128552}: Fix cyclic garbage introduced by
@ref{463,,asyncio.loop.create_task()} and @ref{464,,asyncio.TaskGroup.create_task()}
holding a reference to the created task if it is eager.

@item 
gh-128340@footnote{https://github.com/python/cpython/issues/128340}: Add internal thread safe handle to be used in
@ref{ec9,,asyncio.loop.call_soon_threadsafe()} for thread safe cancellation.

@item 
gh-128182@footnote{https://github.com/python/cpython/issues/128182}: Fix crash when using @ref{2d,,ctypes} pointers concurrently on the
@ref{487,,free threaded} build.

@item 
gh-128400@footnote{https://github.com/python/cpython/issues/128400}: Only show the current thread in @ref{5b,,faulthandler} on the
@ref{487,,free threaded} build to prevent races.

@item 
gh-128400@footnote{https://github.com/python/cpython/issues/128400}: Fix crash when using @ref{21a,,faulthandler.dump_traceback()} while
other threads are active on the @ref{487,,free threaded}
build.

@item 
gh-128388@footnote{https://github.com/python/cpython/issues/128388}: Fix @code{PyREPL} on Windows to support more keybindings, like the
@code{Control}-@code{←} and @code{Control}-@code{→} word-skipping keybindings and those
with meta (i.e. @code{Alt}), e.g. @code{Alt}-@code{d} to @code{kill-word} or
@code{Alt}-@code{Backspace} @code{backward-kill-word}.

@item 
gh-88834@footnote{https://github.com/python/cpython/issues/88834}: Unify the instance check for @ref{341,,typing.Union} and
@ref{527,,types.UnionType}: @code{Union} now uses the instance checks
against its parameters instead of the subclass checks.

@item 
gh-128302@footnote{https://github.com/python/cpython/issues/128302}: Fix
@code{xml.dom.xmlbuilder.DOMEntityResolver.resolveEntity()}, which was
broken by the Python 3.0 transition.

@item 
gh-128317@footnote{https://github.com/python/cpython/issues/128317}: Highlight today in colour in @ref{15,,calendar}’s CLI output.
Patch by Hugo van Kemenade.

@item 
gh-128302@footnote{https://github.com/python/cpython/issues/128302}: Allow @code{xml.dom.xmlbuilder.DOMParser.parse()} to correctly
handle @code{xml.dom.xmlbuilder.DOMInputSource} instances that only
have a @code{systemId} attribute set.

@item 
gh-128151@footnote{https://github.com/python/cpython/issues/128151}: Improve generation of @ref{e25,,UUID} objects version 3, 4,
5, and 8 via their dedicated functions by 30%. Patch by Bénédikt Tran.

@item 
gh-128118@footnote{https://github.com/python/cpython/issues/128118}: Improve performance of @ref{942,,copy.copy()} by 30% via a fast path
for atomic types and container types.

@item 
gh-127946@footnote{https://github.com/python/cpython/issues/127946}: Fix crash when modifying @ref{1af3,,ctypes._CFuncPtr} objects
concurrently on the @ref{487,,free threaded} build.

@item 
gh-128062@footnote{https://github.com/python/cpython/issues/128062}: Revert the font of @ref{10b,,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{f9,,tkinter} method @code{wm_iconbitmap()}.

@item 
gh-41872@footnote{https://github.com/python/cpython/issues/41872}: Fix quick extraction of module docstrings from a file in
@ref{bd,,pydoc}. It now supports docstrings with single quotes, escape
sequences, raw string literals, and other Python syntax.

@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{2d,,ctypes} and @ref{36,,dbm.gnu} functions respectively. Patch by Bénédikt
Tran.

@item 
gh-122548@footnote{https://github.com/python/cpython/issues/122548}: Adds two new local events to sys.monitoring, @code{BRANCH_LEFT}
and @code{BRANCH_RIGHT}. This allows the two arms of the branch to be
disabled independently, which should hugely improve performance of
branch-level coverage tools. The old branch event, @code{BRANCH} is now
deprecated.

@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{84a,,zipfile.ZipFile.open()}.

@item 
gh-127688@footnote{https://github.com/python/cpython/issues/127688}: Add the @ref{4e9,,SCHED_DEADLINE} and @ref{4ea,,SCHED_NORMAL}
constants to the @ref{a5,,os} module.

@item 
gh-83662@footnote{https://github.com/python/cpython/issues/83662}: Add missing @code{__class_getitem__} method to the Python
implementation of @ref{4a6,,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{1315,,multiprocessing.pool.Pool} now properly restores
blocked signal handlers of the parent thread when creating processes via
either `spawn' or `forkserver'.

@item 
gh-98188@footnote{https://github.com/python/cpython/issues/98188}: Fix an issue in @ref{1576,,email.message.Message.get_payload()} where
data cannot be decoded if the Content Transfer Encoding mechanism contains
trailing whitespaces or additional junk text. Patch by Hui Liu.

@item 
gh-127529@footnote{https://github.com/python/cpython/issues/127529}: Correct behavior of
@code{asyncio.selector_events.BaseSelectorEventLoop._accept_connection()}
in handling @ref{1405,,ConnectionAbortedError} in a loop. This improves
performance on OpenBSD.

@item 
gh-127360@footnote{https://github.com/python/cpython/issues/127360}: When a descriptive error message cannot be provided for an
@ref{161e,,ssl.SSLError}, the «unknown error» message now shows the internal
error code (as retrieved by @code{ERR_get_error} and similar OpenSSL
functions).

@item 
gh-127196@footnote{https://github.com/python/cpython/issues/127196}: Fix crash when dict with keys in invalid encoding were passed
to several functions in @code{_interpreters} module.

@item 
gh-124130@footnote{https://github.com/python/cpython/issues/124130}: Fix a bug in matching regular expression @code{\B} in empty input
string. Now it is always the opposite of @code{\b}. To get an old behavior,
use @code{(?!\A\Z)\B}. To get a new behavior in old Python versions, use
@code{(?!\b)}.

@item 
gh-126639@footnote{https://github.com/python/cpython/issues/126639}: @ref{8d6,,tempfile.NamedTemporaryFile} will now issue a
@ref{74f,,ResourceWarning} when it is finalized by the garbage collector
without being explicitly closed.

@item 
gh-126624@footnote{https://github.com/python/cpython/issues/126624}: Expose error code
@ref{1af4,,XML_ERROR_NOT_STARTED} of Expat >=2.6.4
in @ref{130,,xml.parsers.expat.errors}.

@item 
gh-126225@footnote{https://github.com/python/cpython/issues/126225}: @ref{64,,getopt} and @ref{a4,,optparse} are no longer marked as
deprecated. There are legitimate reasons to use one of these modules in
preference to @ref{7,,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-124761@footnote{https://github.com/python/cpython/issues/124761}: Add @ref{1af5,,SO_REUSEPORT_LB} constant to @ref{d4,,socket}
for FreeBSD.

@item 
gh-121720@footnote{https://github.com/python/cpython/issues/121720}: @ref{6fb,,enum.EnumDict} can now be used without resorting to
private API.

@item 
gh-123424@footnote{https://github.com/python/cpython/issues/123424}: Add @ref{546,,zipfile.ZipInfo._for_archive()} setting default
properties on @ref{547,,ZipInfo} objects. Patch by Bénédikt Tran
and Jason R. Coombs.

@item 
gh-121676@footnote{https://github.com/python/cpython/issues/121676}: Deprecate calling the Python implementation of
@ref{153,,functools.reduce()} with a @code{function} or @code{sequence} as a
@ref{10cc,,keyword argument}. This will be forbidden in Python 3.16 in order
to match the C implementation.

@item 
gh-112015@footnote{https://github.com/python/cpython/issues/112015}: @ref{481,,ctypes.memoryview_at()} now exists to create a
@ref{1d2,,memoryview} object that refers to the supplied pointer and length.
This works like @ref{482,,ctypes.string_at()} except it avoids a buffer copy,
and is typically useful when implementing pure Python callback functions
that are passed dynamically-sized buffers.

@item 
gh-95371@footnote{https://github.com/python/cpython/issues/95371}: Added support for other image formats (PNG, PGM, and PPM) to the
turtle module. Patch by Shin-myoung-serp.
@end itemize

@node Core and Builtins<40>,Library<43>,Library<42>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id166}@anchor{1af6}
@subsubsection Core and Builtins



@itemize -

@item 
gh-128078@footnote{https://github.com/python/cpython/issues/128078}: Fix a @ref{3ea,,SystemError} when using @ref{bb3,,anext()} with a
default tuple value. Patch by Bénédikt Tran.

@item 
gh-128717@footnote{https://github.com/python/cpython/issues/128717}: Fix a crash when setting the recursion limit while other
threads are active on the @ref{487,,free threaded} build.

@item 
gh-124483@footnote{https://github.com/python/cpython/issues/124483}: Treat @code{Py_DECREF} and variants as escaping when generating
opcode and uop metadata. This prevents the possibility of a @code{__del__}
method causing the JIT to behave incorrectly.

@item 
gh-126703@footnote{https://github.com/python/cpython/issues/126703}: Improve performance of class methods by using a freelist.

@item 
gh-128137@footnote{https://github.com/python/cpython/issues/128137}: Update @ref{151e,,PyASCIIObject} layout to handle interned field
with the atomic operation. Patch by Donghee Na.
@end itemize

@node Library<43>,Core and Builtins<41>,Core and Builtins<40>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id167}@anchor{1af7}
@subsubsection Library



@itemize -

@item 
gh-128192@footnote{https://github.com/python/cpython/issues/128192}: Upgrade HTTP digest authentication algorithm for
@ref{114,,urllib.request} by supporting SHA-256 digest authentication as
specified in 
@geindex RFC; RFC 7616
RFC 7616@footnote{https://datatracker.ietf.org/doc/html/rfc7616.html}.
@end itemize

@node Core and Builtins<41>,Library<44>,Library<43>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id168}@anchor{1af8}
@subsubsection Core and Builtins



@itemize -

@item 
gh-126868@footnote{https://github.com/python/cpython/issues/126868}: Increase usage of freelist for @ref{326,,int} allocation.

@item 
gh-114203@footnote{https://github.com/python/cpython/issues/114203}: Optimize @code{Py_BEGIN_CRITICAL_SECTION} for simple recursive
calls.

@item 
gh-127705@footnote{https://github.com/python/cpython/issues/127705}: Adds stackref debugging when @code{Py_STACKREF_DEBUG} is set.
Finds all double-closes and leaks, logging the origin and last borrow.

Inspired by HPy’s debug mode.
@indicateurl{https://docs.hpyproject.org/en/latest/debug-mode.html}

@item 
gh-128079@footnote{https://github.com/python/cpython/issues/128079}: Fix a bug where @ref{448,,except*} does not
properly check the return value of an @ref{6d8,,ExceptionGroup}’s
@ref{1af9,,split()} function, leading to a crash in some
cases. Now when @code{split()} returns an invalid
object, @code{except*} raises a @ref{291,,TypeError} with
the original raised @code{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.
@end itemize

@node Library<44>,Core and Builtins<42>,Core and Builtins<41>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id169}@anchor{1afa}
@subsubsection Library



@itemize -

@item 
gh-128035@footnote{https://github.com/python/cpython/issues/128035}: Indicate through @ref{50e,,ssl.HAS_PHA} whether the @ref{d8,,ssl}
module supports TLSv1.3 post-handshake client authentication (PHA). Patch
by Will Childs-Klein.
@end itemize

@node Core and Builtins<42>,C API<13>,Library<44>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id170}@anchor{1afb}
@subsubsection Core and Builtins



@itemize -

@item 
gh-127274@footnote{https://github.com/python/cpython/issues/127274}: Add a new flag, @code{CO_METHOD}, to @ref{1afc,,co_flags}
that indicates whether the code object belongs to a function defined in
class scope.

@item 
gh-66409@footnote{https://github.com/python/cpython/issues/66409}: During the @ref{1953,,path initialization}, we now
check if @code{base_exec_prefix} is the same as @code{base_prefix} before
falling back to searching the Python interpreter directory.

@item 
gh-127970@footnote{https://github.com/python/cpython/issues/127970}: We now use the location of the @code{libpython} runtime library
used in the current process to determine @ref{3aa,,sys.base_prefix} on all
platforms implementing the dladdr@footnote{https://pubs.opengroup.org/onlinepubs/9799919799/functions/dladdr.html}
function defined by the UNIX standard — this includes Linux, Android,
macOS, iOS, FreeBSD, etc. This was already the case on Windows and macOS
Framework builds.

@item 
gh-127773@footnote{https://github.com/python/cpython/issues/127773}: Do not use the type attribute cache for types with incompatible
@ref{1afd,,MRO}.

@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-127809@footnote{https://github.com/python/cpython/issues/127809}: Fix an issue where the experimental JIT may infer an incorrect
result type for exponentiation (@code{**} and @code{**=}), leading to bugs or
crashes.

@item 
gh-126862@footnote{https://github.com/python/cpython/issues/126862}: Fix a possible overflow when a class inherits from an absurd
number of super-classes. Reported by Valery Fedorenko. Patch by Bénédikt
Tran.
@end itemize

@node C API<13>,Build<12>,Core and Builtins<42>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id171}@anchor{1afe}
@subsubsection C API



@itemize -

@item 
gh-128400@footnote{https://github.com/python/cpython/issues/128400}: @ref{d4b,,Py_FatalError()} no longer shows all threads on the
@ref{487,,free threaded} build to prevent crashes.

@item 
gh-128629@footnote{https://github.com/python/cpython/issues/128629}: Add macros @ref{5ac,,Py_PACK_VERSION()} and
@ref{5ad,,Py_PACK_FULL_VERSION()} for bit-packing Python version numbers.

@item 
gh-128008@footnote{https://github.com/python/cpython/issues/128008}: Add @ref{1aff,,PyWeakref_IsDead()} function, which tests if a weak
reference is dead.

@item 
gh-127350@footnote{https://github.com/python/cpython/issues/127350}: Add @ref{5c0,,Py_fopen()} function to open a file. Similar to the
@code{fopen()} function, but the `path' parameter is a Python object and
an exception is set on error. Add also @ref{5c1,,Py_fclose()} function to
close a file, function needed for Windows support. Patch by Victor
Stinner.
@end itemize

@node Build<12>,,C API<13>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id172}@anchor{1b00}
@subsubsection Build



@itemize -

@item 
gh-128627@footnote{https://github.com/python/cpython/issues/128627}: For Emscripten builds the function pointer cast call trampoline
now uses the wasm-gc ref.test instruction if it’s available instead of
Wasm JS type reflection.

@item 
gh-128472@footnote{https://github.com/python/cpython/issues/128472}: Skip BOLT optimization of functions using computed gotos,
fixing errors on build with LLVM 19.

@item 
gh-115765@footnote{https://github.com/python/cpython/issues/115765}: GNU Autoconf 2.72 is now required to generate
@code{configure}. Patch by Erlend Aasland.

@item 
gh-123925@footnote{https://github.com/python/cpython/issues/123925}: Fix building the @ref{2e,,curses} module on platforms with
libncurses but without libncursesw.

@item 
gh-90905@footnote{https://github.com/python/cpython/issues/90905}: Add support for cross-compiling to x86_64 on aarch64/arm64
macOS.

@item 
gh-128321@footnote{https://github.com/python/cpython/issues/128321}: Set @code{LIBS} instead of @code{LDFLAGS} when checking if
@ref{d7,,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-100384@footnote{https://github.com/python/cpython/issues/100384}: Error on @code{unguarded-availability} in macOS builds, preventing
invalid use of symbols that are not available in older versions of the OS.

@item 
gh-128104@footnote{https://github.com/python/cpython/issues/128104}: Remove @code{Py_STRFTIME_C99_SUPPORT} conditions in favor of
requiring C99 @code{strftime(3)@footnote{https://manpages.debian.org/strftime(3)}} specifier support at build time. When
cross-compiling, there is no build time check and support is assumed.

@item 
gh-127951@footnote{https://github.com/python/cpython/issues/127951}: Add option @code{--pystats} to the Windows build to enable
performance statistics collection.
@end itemize

@node Python 3 14 0 alpha 3,Python 3 14 0 alpha 2,Python 3 14 0 alpha 4,Changelog
@anchor{whatsnew/changelog python-3-14-0-alpha-3}@anchor{1b01}
@subsection Python 3.14.0 alpha 3


`Release date: 2024-12-17'

@menu
* Windows: Windows<11>. 
* Tools/Demos: Tools/Demos<11>. 
* Tests: Tests<15>. 
* Security: Security<13>. 
* Library: Library<45>. 
* Documentation: Documentation<12>. 
* Core and Builtins: Core and Builtins<43>. 
* Library: Library<46>. 
* Core and Builtins: Core and Builtins<44>. 
* C API: C API<14>. 
* Build: Build<13>. 

@end menu

@node Windows<11>,Tools/Demos<11>,,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id173}@anchor{1b02}
@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.

@item 
gh-125729@footnote{https://github.com/python/cpython/issues/125729}: Makes the presence of the @ref{10a,,turtle} module dependent on the
Tcl/Tk installer option. Previously, the module was always installed but
would be unusable without Tcl/Tk.
@end itemize

@node Tools/Demos<11>,Tests<15>,Windows<11>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id174}@anchor{1b03}
@subsubsection Tools/Demos



@itemize -

@item 
gh-126700@footnote{https://github.com/python/cpython/issues/126700}: Add support for multi-argument @ref{66,,gettext} functions in
@code{pygettext.py}.
@end itemize

@node Tests<15>,Security<13>,Tools/Demos<11>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id175}@anchor{1b04}
@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{3b,,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.

@item 
gh-127076@footnote{https://github.com/python/cpython/issues/127076}: Disable strace based system call tests when LD_PRELOAD is set.

@item 
gh-127076@footnote{https://github.com/python/cpython/issues/127076}: Filter out memory-related @code{mmap}, @code{munmap}, and
@code{mprotect}  calls from file-related ones when testing @ref{82,,io} behavior
using strace.
@end itemize

@node Security<13>,Library<45>,Tests<15>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id176}@anchor{1b05}
@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{1a09,,asyncio.WriteTransport.writelines()}.
@end itemize

@node Library<45>,Documentation<12>,Security<13>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id177}@anchor{1b06}
@subsubsection Library



@itemize -

@item 
gh-126907@footnote{https://github.com/python/cpython/issues/126907}: Fix crash when using @ref{d,,atexit} concurrently on the
@ref{487,,free-threaded} build.

@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-127732@footnote{https://github.com/python/cpython/issues/127732}: The @ref{af,,platform} module now correctly detects Windows Server
2025.

@item 
gh-126789@footnote{https://github.com/python/cpython/issues/126789}: Fixed @ref{51e,,sysconfig.get_config_vars()},
@ref{156,,sysconfig.get_paths()}, and siblings, returning outdated cached data
if the value  of @ref{3ab,,sys.prefix} or @ref{3a8,,sys.exec_prefix} changes.
Overwriting @code{sys.prefix} or @code{sys.exec_prefix} still is
discouraged, as that might break other parts of the code.

@item 
gh-127718@footnote{https://github.com/python/cpython/issues/127718}: Add colour to @ref{ec,,test.regrtest} output. Patch by Hugo van
Kemenade.

@item 
gh-127610@footnote{https://github.com/python/cpython/issues/127610}: Added validation for more than one var-positional or
var-keyword parameters in @ref{6e8,,inspect.Signature}. Patch by Maxim
Ageev.

@item 
gh-127627@footnote{https://github.com/python/cpython/issues/127627}: Added @code{posix._emscripten_debugger()} to help with debugging
the test suite on the Emscripten target.

@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-127481@footnote{https://github.com/python/cpython/issues/127481}: Add the @code{EPOLLWAKEUP} constant to the @ref{c9,,select} module.

@item 
gh-127065@footnote{https://github.com/python/cpython/issues/127065}: Make @ref{11e7,,operator.methodcaller()} thread-safe and re-entrant
safe.

@item 
gh-127321@footnote{https://github.com/python/cpython/issues/127321}: @ref{4fa,,pdb.set_trace()} will not stop at an opcode that does not
have an associated line number anymore.

@item 
gh-127429@footnote{https://github.com/python/cpython/issues/127429}: Fixed bug where, on cross-builds, the @ref{e4,,sysconfig} POSIX
data was being generated with the host Python’s @code{Makefile}. The data is
now generated from current build’s @code{Makefile}.

@item 
gh-127413@footnote{https://github.com/python/cpython/issues/127413}: Add the @ref{49a,,dis --specialized} command-line option to show
specialized bytecode. Patch by Bénédikt Tran.

@item 
gh-125413@footnote{https://github.com/python/cpython/issues/125413}: Revert addition of @code{pathlib.Path.scandir()}. This method
was added in 3.14.0a2. The optimizations remain for file system paths, but
other subclasses should only have to implement
@ref{4f6,,pathlib.Path.iterdir()}.

@item 
gh-127257@footnote{https://github.com/python/cpython/issues/127257}: In @ref{d8,,ssl}, system call failures that OpenSSL reports using
@code{ERR_LIB_SYS} are now raised as @ref{53c,,OSError}.

@item 
gh-59705@footnote{https://github.com/python/cpython/issues/59705}: On Linux, @ref{420,,threading.Thread} now sets the thread name to
the operating system. Patch by Victor Stinner.

@item 
gh-127303@footnote{https://github.com/python/cpython/issues/127303}: Publicly expose @ref{1b07,,EXACT_TOKEN_TYPES} in
@code{token.__all__}.

@item 
gh-127331@footnote{https://github.com/python/cpython/issues/127331}: @ref{d8,,ssl} can show descriptions for errors added in OpenSSL
3.4.

@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-127178@footnote{https://github.com/python/cpython/issues/127178}: A @code{_sysconfig_vars_(...).json} file is now shipped in the
standard library directory. It contains the output of
@ref{51e,,sysconfig.get_config_vars()} on the default environment encoded as
JSON data. This is an implementation detail, and may change at any time.

@item 
gh-127072@footnote{https://github.com/python/cpython/issues/127072}: Remove outdated @code{socket.NETLINK_*} constants not present in
Linux kernels beyond 2.6.17.

@item 
gh-127255@footnote{https://github.com/python/cpython/issues/127255}: The @ref{480,,CopyComPointer()} function is now public.
Previously, this was private and only available in @code{_ctypes}.

@item 
gh-127182@footnote{https://github.com/python/cpython/issues/127182}: Fix @code{io.StringIO.__setstate__()} crash, when @ref{a65,,None}
was passed as the first value.

@item 
gh-127217@footnote{https://github.com/python/cpython/issues/127217}: Fix @ref{53b,,urllib.request.pathname2url()} for paths starting with
multiple slashes on Posix.

@item 
gh-125866@footnote{https://github.com/python/cpython/issues/125866}: @ref{53b,,urllib.request.pathname2url()} now adds an empty authority
when generating a URL for a path that begins with exactly one slash. For
example, the path @code{/etc/hosts} is converted to the scheme-less URL
@code{///etc/hosts}. As a result of this change, URLs without authorities are
only generated for relative paths.

@item 
gh-127221@footnote{https://github.com/python/cpython/issues/127221}: Add colour to @ref{10f,,unittest} output. Patch by Hugo van
Kemenade.

@item 
gh-127035@footnote{https://github.com/python/cpython/issues/127035}: Fix @ref{8c4,,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-125866@footnote{https://github.com/python/cpython/issues/125866}: @ref{53b,,urllib.request.pathname2url()} and
@ref{539,,url2pathname()} no longer convert Windows drive
letters to uppercase.

@item 
gh-127078@footnote{https://github.com/python/cpython/issues/127078}: Fix issue where @ref{539,,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{539,,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{11e7,,operator.methodcaller()} instance
from multiple threads in the free threading build.

@item 
gh-127090@footnote{https://github.com/python/cpython/issues/127090}: Fix value of @ref{1b08,,urllib.response.addinfourl.url} for
@code{file:} URLs that express relative paths and absolute Windows paths. The
canonical URL generated by @ref{53b,,urllib.request.pathname2url()} is now
used.

@item 
gh-126992@footnote{https://github.com/python/cpython/issues/126992}: Fix LONG and INT opcodes to only use base 10 for string to
integer conversion in @ref{ab,,pickle}.

@item 
gh-126997@footnote{https://github.com/python/cpython/issues/126997}: Fix support of STRING and GLOBAL opcodes with non-ASCII
arguments in @ref{ac,,pickletools}. @ref{1080,,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{69,,grp}: Make @ref{1b09,,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{1628,,itertools.count} objects when
the count value is @ref{156e,,sys.maxsize}.

@item 
gh-126615@footnote{https://github.com/python/cpython/issues/126615}: The @ref{47f,,COMError} exception is now public.
Previously, this was private and only available in @code{_ctypes}.

@item 
gh-126985@footnote{https://github.com/python/cpython/issues/126985}: When running under a virtual environment with the @ref{cf,,site}
disabled (see @ref{1551,,-S}), @ref{3ab,,sys.prefix} and
@ref{3aa,,sys.base_prefix} will now point to the virtual environment, instead
of the base installation.

@item 
gh-112192@footnote{https://github.com/python/cpython/issues/112192}: In the @ref{106,,trace} module, increase the coverage precision
(@code{cov%}) to one decimal.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve import time of @ref{93,,mimetypes} by around 11-16 times.
Patch by Hugo van Kemenade.

@item 
gh-126947@footnote{https://github.com/python/cpython/issues/126947}: Raise @ref{291,,TypeError} in
@code{_pydatetime.timedelta.__new__()} if the passed arguments are not
@ref{326,,int} or @ref{327,,float}, so that the Python implementation is in
line with the C implementation.

@item 
gh-126946@footnote{https://github.com/python/cpython/issues/126946}: Improve the @ref{1b0a,,GetoptError} error message when a
long option prefix matches multiple accepted options in
@ref{185d,,getopt.getopt()} and @ref{185c,,getopt.gnu_getopt()}.

@item 
gh-126899@footnote{https://github.com/python/cpython/issues/126899}: Make tkinter widget methods @code{after()} and
@code{after_idle()} accept arguments passed by keyword.

@item 
gh-85168@footnote{https://github.com/python/cpython/issues/85168}: Fix issue where @ref{539,,urllib.request.url2pathname()} and
@ref{53b,,pathname2url()} always used UTF-8 when quoting and
unquoting file URIs. They now use the @ref{948,,filesystem encoding and error handler}.

@item 
gh-126780@footnote{https://github.com/python/cpython/issues/126780}: Fix @ref{16be,,os.path.normpath()} for drive-relative paths on
Windows.

@item 
gh-126775@footnote{https://github.com/python/cpython/issues/126775}: Make @ref{1b0b,,linecache.checkcache()} thread safe and GC
re-entrancy safe.

@item 
gh-126601@footnote{https://github.com/python/cpython/issues/126601}: Fix issue where @ref{53b,,urllib.request.pathname2url()} raised
@ref{53c,,OSError} when given a Windows path containing a colon character not
following a drive letter, such as before an NTFS alternate data stream.

@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-85046@footnote{https://github.com/python/cpython/issues/85046}: Add @ref{49c,,EHWPOISON} error code to @ref{5a,,errno}.

@item 
gh-118201@footnote{https://github.com/python/cpython/issues/118201}: Fixed intermittent failures of @ref{1b0c,,os.confstr},
@ref{14a7,,os.pathconf} and @ref{1b0d,,os.sysconf} on iOS and Android.

@item 
gh-86463@footnote{https://github.com/python/cpython/issues/86463}: The @code{usage} parameter of @ref{1dc,,argparse.ArgumentParser} no
longer affects the default value of the @code{prog} parameter in subparsers.

@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-123401@footnote{https://github.com/python/cpython/issues/123401}: The @ref{74,,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{1202,,readline.append_history_file()} now raises a
@ref{277,,ValueError} when given a negative value.

@item 
gh-122356@footnote{https://github.com/python/cpython/issues/122356}: Guarantee that the position of a file-like object passed to
@ref{16cf,,zipfile.is_zipfile()} is left untouched after the call. Patch by
Bénédikt Tran.

@item 
gh-122288@footnote{https://github.com/python/cpython/issues/122288}: Improve the performances of @ref{1a79,,fnmatch.translate()} by a
factor 1.7. Patch by Bénédikt Tran.

@item 
gh-88110@footnote{https://github.com/python/cpython/issues/88110}: Fixed @ref{4de,,multiprocessing.Process} reporting a @code{.exitcode}
of 1 even on success when using the @code{"fork"} start method while using a
@ref{b27,,concurrent.futures.ThreadPoolExecutor}.

@item 
gh-97514@footnote{https://github.com/python/cpython/issues/97514}: Authentication was added to the @ref{98,,multiprocessing}
forkserver start method control socket so that only processes with the
authentication key generated by the process that spawned the forkserver
can control it.  This is an enhancement over the other gh-97514@footnote{https://github.com/python/cpython/issues/97514} fixes
so that access is no longer limited only by filesystem permissions.

The file descriptor exchange of control pipes with the forked worker
process now requires an explicit acknowledgement byte to be sent over the
socket after the exchange on all forkserver supporting platforms. That
makes testing the above much easier.
@end itemize

@node Documentation<12>,Core and Builtins<43>,Library<45>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id178}@anchor{1b0e}
@subsubsection Documentation



@itemize -

@item 
gh-127347@footnote{https://github.com/python/cpython/issues/127347}: Publicly expose @ref{1b0f,,traceback.print_list()} in
@code{traceback.__all__}.
@end itemize

@node Core and Builtins<43>,Library<46>,Documentation<12>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id179}@anchor{1b10}
@subsubsection Core and Builtins



@itemize -

@item 
gh-127740@footnote{https://github.com/python/cpython/issues/127740}: Fix error message in @ref{434,,bytes.fromhex()} when given an odd
number of digits to properly indicate that an even number of hexadecimal
digits is required.

@item 
gh-127058@footnote{https://github.com/python/cpython/issues/127058}: @code{PySequence_Tuple} now creates the resulting tuple
atomically, preventing partially created tuples being visible to the
garbage collector or through @code{gc.get_referrers()}

@item 
gh-127599@footnote{https://github.com/python/cpython/issues/127599}: Fix statistics for increments of object reference counts (in
particular, when a reference count was increased by more than 1 in a
single operation).

@item 
gh-127651@footnote{https://github.com/python/cpython/issues/127651}: When raising @ref{1bd,,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-127085@footnote{https://github.com/python/cpython/issues/127085}: Fix race when exporting a buffer from a @ref{1d2,,memoryview}
object on the @ref{487,,free-threaded} build.

@item 
gh-127238@footnote{https://github.com/python/cpython/issues/127238}: Correct error message for @ref{1b11,,sys.set_int_max_str_digits()}.

@item 
gh-113841@footnote{https://github.com/python/cpython/issues/113841}: Fix possible undefined behavior division by zero in
@ref{328,,complex}’s @ref{3c2,,_Py_c_pow()}.
@end itemize

@node Library<46>,Core and Builtins<44>,Core and Builtins<43>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id180}@anchor{1b12}
@subsubsection Library



@itemize -

@item 
gh-127133@footnote{https://github.com/python/cpython/issues/127133}: Calling @ref{31d,,argparse.ArgumentParser.add_argument_group()} on
an argument group, and calling
@code{argparse.ArgumentParser.add_argument_group()} or
@ref{567,,argparse.ArgumentParser.add_mutually_exclusive_group()} on a mutually
exclusive group now raise exceptions. This nesting was never supported,
often failed to work correctly, and was unintentionally exposed through
inheritance. This functionality has been deprecated since Python 3.11.
@end itemize

@node Core and Builtins<44>,C API<14>,Library<46>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id181}@anchor{1b13}
@subsubsection Core and Builtins



@itemize -

@item 
gh-126491@footnote{https://github.com/python/cpython/issues/126491}: Add a marking phase to the GC. All objects that can be
transitively reached from builtin modules or the stacks are marked as
reachable before cycle detection. This reduces the amount of work done by
the GC by approximately half.

@item 
gh-127020@footnote{https://github.com/python/cpython/issues/127020}: Fix a crash in the free threading build when
@ref{b5a,,PyCode_GetCode()}, @ref{b5b,,PyCode_GetVarnames()},
@ref{b5c,,PyCode_GetCellvars()}, or @ref{b5d,,PyCode_GetFreevars()} were called
from multiple threads at the same time.

@item 
gh-127010@footnote{https://github.com/python/cpython/issues/127010}: Simplify GC tracking of dictionaries. All dictionaries are
tracked when created, rather than being lazily tracked when a trackable
object was added to them. This simplifies the code considerably and
results in a slight speedup.

@item 
gh-126980@footnote{https://github.com/python/cpython/issues/126980}: Fix @ref{879,,__buffer__()} of @ref{1c6,,bytearray} crashing
when @ref{1b14,,READ} or
@ref{1b15,,WRITE} are passed as flags.

@item 
gh-126937@footnote{https://github.com/python/cpython/issues/126937}: Fix @ref{291,,TypeError} when a @ref{47c,,ctypes.Structure} has a
field size that doesn’t fit into an unsigned 16-bit integer. Instead, the
maximum number of `bits' is @ref{156e,,sys.maxsize}.

@item 
gh-126868@footnote{https://github.com/python/cpython/issues/126868}: Increase performance of @ref{326,,int} by adding a freelist for
compact ints.

@item 
gh-126881@footnote{https://github.com/python/cpython/issues/126881}: Fix crash in finalization of dtoa state. Patch by Kumar Aditya.

@item 
gh-126892@footnote{https://github.com/python/cpython/issues/126892}: Require cold or invalidated code to «warm up» before being JIT
compiled again.

@item 
gh-126091@footnote{https://github.com/python/cpython/issues/126091}: Ensure stack traces are complete when throwing into a generator
chain that ends in a custom generator.

@item 
gh-126024@footnote{https://github.com/python/cpython/issues/126024}: Optimize decoding of short UTF-8 sequences containing non-ASCII
characters by approximately 15%.

@item 
gh-125420@footnote{https://github.com/python/cpython/issues/125420}: Add @ref{1b16,,memoryview.index()} to @ref{1d2,,memoryview} objects.
Patch by Bénédikt Tran.

@item 
gh-125420@footnote{https://github.com/python/cpython/issues/125420}: Add @ref{1b17,,memoryview.count()} to @ref{1d2,,memoryview} objects.
Patch by Bénédikt Tran.

@item 
gh-124470@footnote{https://github.com/python/cpython/issues/124470}: Fix crash in free-threaded builds when replacing object
dictionary while reading attribute on another thread

@item 
gh-69639@footnote{https://github.com/python/cpython/issues/69639}: Implement mixed-mode arithmetic rules combining real and complex
numbers as specified by C standards since C99.  Patch by Sergey B
Kirpichev.

@item 
gh-120010@footnote{https://github.com/python/cpython/issues/120010}: Correct invalid corner cases which resulted in @code{(nan+nanj)}
output in complex multiplication, e.g., @code{(1e300+1j)*(nan+infj)}.  Patch
by Sergey B Kirpichev.

@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<14>,Build<13>,Core and Builtins<44>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id182}@anchor{1b18}
@subsubsection C API



@itemize -

@item 
gh-127896@footnote{https://github.com/python/cpython/issues/127896}: The previously undocumented function @ref{604,,PySequence_In()} is
@ref{1a7,,soft deprecated}. Use @ref{605,,PySequence_Contains()} instead.

@item 
gh-127791@footnote{https://github.com/python/cpython/issues/127791}: Fix loss of callbacks after more than one call to
@ref{1b19,,PyUnstable_AtExit()}.

@item 
gh-127691@footnote{https://github.com/python/cpython/issues/127691}: The @ref{674,,Unicode Exception Objects} C API
now raises a @ref{291,,TypeError} if its exception argument is not a
@ref{675,,UnicodeError} object. Patch by Bénédikt Tran.

@item 
gh-123378@footnote{https://github.com/python/cpython/issues/123378}: Ensure that the value of @ref{1ae2,,UnicodeEncodeError.end} retrieved by @ref{1b1a,,PyUnicodeEncodeError_GetEnd()}
lies in @code{[min(1, objlen), max(min(1, objlen), objlen)]} where `objlen'
is the length of @ref{1b1b,,UnicodeEncodeError.object}.
Similar arguments apply to @ref{dd7,,UnicodeDecodeError} and
@ref{1b1c,,UnicodeTranslateError} and their corresponding C interface. Patch by
Bénédikt Tran.

@item 
gh-127314@footnote{https://github.com/python/cpython/issues/127314}: Improve error message when calling the C API without an active
thread state on the @ref{487,,free-threaded} build.

@item 
gh-123378@footnote{https://github.com/python/cpython/issues/123378}: Ensure that the value of @ref{1ae1,,UnicodeEncodeError.start} retrieved by @ref{1b1d,,PyUnicodeEncodeError_GetStart()}
lies in @code{[0, max(0, objlen - 1)]} where `objlen' is the length of
@ref{1b1b,,UnicodeEncodeError.object}. Similar arguments
apply to @ref{dd7,,UnicodeDecodeError} and @ref{1b1c,,UnicodeTranslateError} and
their corresponding C interface. Patch by Bénédikt Tran.

@item 
gh-109523@footnote{https://github.com/python/cpython/issues/109523}: Reading text from a non-blocking stream with @code{read} may now
raise a @ref{4c3,,BlockingIOError} if the operation cannot immediately return
bytes.

@item 
gh-102471@footnote{https://github.com/python/cpython/issues/102471}: Add a new import and export API for Python @ref{326,,int} objects
(
@geindex Python Enhancement Proposals; PEP 757
PEP 757@footnote{https://peps.python.org/pep-0757/}):


@itemize *

@item 
@ref{5d4,,PyLong_GetNativeLayout()};

@item 
@ref{5d5,,PyLong_Export()};

@item 
@ref{5d6,,PyLong_FreeExport()};

@item 
@ref{5d7,,PyLongWriter_Create()};

@item 
@ref{5d8,,PyLongWriter_Finish()};

@item 
@ref{5d9,,PyLongWriter_Discard()}.
@end itemize

Patch by Victor Stinner.

@item 
gh-121058@footnote{https://github.com/python/cpython/issues/121058}: @code{PyThreadState_Clear()} now warns (and calls
@code{sys.excepthook}) if the thread state still has an active exception.
@end itemize

@node Build<13>,,C API<14>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id183}@anchor{1b1e}
@subsubsection Build



@itemize -

@item 
gh-127865@footnote{https://github.com/python/cpython/issues/127865}: Fix build failure on systems without thread-locals support.

@item 
gh-127629@footnote{https://github.com/python/cpython/issues/127629}: Emscripten builds now include ctypes support.

@item 
gh-127111@footnote{https://github.com/python/cpython/issues/127111}: Updated the Emscripten web example to use ES6 modules and be
built into a distinct @code{web_example} subfolder.

@item 
gh-115869@footnote{https://github.com/python/cpython/issues/115869}: Make @code{jit_stencils.h} (which is produced during JIT builds)
reproducible.

@item 
gh-126898@footnote{https://github.com/python/cpython/issues/126898}: The Emscripten build of Python is now based on ES6 modules.
@end itemize

@node Python 3 14 0 alpha 2,Python 3 14 0 alpha 1,Python 3 14 0 alpha 3,Changelog
@anchor{whatsnew/changelog python-3-14-0-alpha-2}@anchor{1b1f}
@subsection Python 3.14.0 alpha 2


`Release date: 2024-11-19'

@menu
* Windows: Windows<12>. 
* Tools/Demos: Tools/Demos<12>. 
* Tests: Tests<16>. 
* Security: Security<14>. 
* Library: Library<47>. 
* Documentation: Documentation<13>. 
* Core and Builtins: Core and Builtins<45>. 
* Library: Library<48>. 
* Core and Builtins: Core and Builtins<46>. 
* Library: Library<49>. 
* Core and Builtins: Core and Builtins<47>. 
* Library: Library<50>. 
* C API: C API<15>. 
* Build: Build<14>. 

@end menu

@node Windows<12>,Tools/Demos<12>,,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id184}@anchor{1b20}
@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{af,,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{3ea,,SystemError} when @ref{4ff,,sys.exit()} is called with
@code{0xffffffff} on Windows.

@item 
gh-125550@footnote{https://github.com/python/cpython/issues/125550}: Enable the @ref{9bc,,Διαχειριστής εγκατάστασης Python} to detect Python 3.14 installs from
the Windows Store.

@item 
gh-123803@footnote{https://github.com/python/cpython/issues/123803}: All Windows code pages are now supported as «cpXXX» codecs on
Windows.
@end itemize

@node Tools/Demos<12>,Tests<16>,Windows<12>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id185}@anchor{1b21}
@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<16>,Security<14>,Tools/Demos<12>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id186}@anchor{1b22}
@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-125730@footnote{https://github.com/python/cpython/issues/125730}: Change @code{make test} to not run GUI tests by default. Use
@code{make ci} to run tests with GUI tests instead.

@item 
gh-124295@footnote{https://github.com/python/cpython/issues/124295}: Add translation tests to the @ref{7,,argparse} module.
@end itemize

@node Security<14>,Library<47>,Tests<16>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id187}@anchor{1b23}
@subsubsection Security



@itemize -

@item 
gh-126623@footnote{https://github.com/python/cpython/issues/126623}: Upgrade libexpat to 2.6.4
@end itemize

@node Library<47>,Documentation<13>,Security<14>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id188}@anchor{1b24}
@subsubsection Library



@itemize -

@item 
gh-85957@footnote{https://github.com/python/cpython/issues/85957}: Add missing MIME types for images with RFCs: emf, fits, g3fax,
jp2, jpm, jpx, t38, tiff-fx and wmf. Patch by Hugo van Kemenade.

@item 
gh-126920@footnote{https://github.com/python/cpython/issues/126920}: Fix the @code{prefix} and @code{exec_prefix} keys from
@ref{51e,,sysconfig.get_config_vars()} incorrectly having the same value as
@ref{3aa,,sys.base_prefix} and @ref{3a7,,sys.base_exec_prefix},
respectively, inside virtual environments. They now accurately reflect
@ref{3ab,,sys.prefix} and @ref{3a8,,sys.exec_prefix}.

@item 
gh-67877@footnote{https://github.com/python/cpython/issues/67877}: Fix memory leaks when @ref{c1,,regular expression} matching
terminates abruptly, either because of a signal or because memory
allocation fails.

@item 
gh-125063@footnote{https://github.com/python/cpython/issues/125063}: @ref{90,,marshal} now supports @ref{1d0,,slice} objects. The marshal
format version was increased to 5.

@item 
gh-126789@footnote{https://github.com/python/cpython/issues/126789}: Fixed the values of @ref{51e,,sysconfig.get_config_vars()},
@ref{156,,sysconfig.get_paths()}, and their siblings when the @ref{cf,,site}
initialization happens after @ref{e4,,sysconfig} has built a cache for
@code{sysconfig.get_config_vars()}.

@item 
gh-126188@footnote{https://github.com/python/cpython/issues/126188}: Update bundled pip to 24.3.1

@item 
gh-126766@footnote{https://github.com/python/cpython/issues/126766}: Fix issue where @ref{539,,urllib.request.url2pathname()} failed to
discard two leading slashes introducing an empty authority section.

@item 
gh-126705@footnote{https://github.com/python/cpython/issues/126705}: Allow @ref{100f,,os.PathLike} to be a base for Protocols.

@item 
gh-126699@footnote{https://github.com/python/cpython/issues/126699}: Allow @ref{1196,,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{1243,,unittest.mock.patch()} or
@ref{1b25,,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{1628,,itertools.count} with an
initial count of @ref{156e,,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{53b,,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{1a13,,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{c1,,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{98,,multiprocessing} @code{"forkserver"} start method
forkserver process to correctly inherit the parent’s @ref{194,,sys.path}
during the importing of @ref{1969,,multiprocessing.set_forkserver_preload()}
modules in the same manner as @code{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 degradation 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{194,,sys.path}
during forkserver preload imports instead of the absolute path from
@ref{1b26,,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{1a7c,,multiprocessing.Lock} and
@ref{1a7d,,multiprocessing.RLock} @code{repr} values no longer say «unknown» on
macOS.

@item 
gh-126476@footnote{https://github.com/python/cpython/issues/126476}: Raise @ref{1915,,calendar.IllegalMonthError} (now a subclass of
@ref{18d7,,IndexError}) for @ref{1b27,,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{ab,,pickle} no longer calls
@ref{1b28,,pickle.Pickler.persistent_id()} for the result of
@code{persistent_id()}.

@item 
gh-126451@footnote{https://github.com/python/cpython/issues/126451}: Register the @ref{421,,contextvars.Context} type to
@ref{c9c,,collections.abc.Mapping}.

@item 
gh-126175@footnote{https://github.com/python/cpython/issues/126175}: Add @code{msg}, @code{doc}, @code{pos}, @code{lineno} and @code{colno}
attributes to @ref{1b29,,tomllib.TOMLDecodeError}. Deprecate instantiating with
free-form arguments.

@item 
gh-89416@footnote{https://github.com/python/cpython/issues/89416}: Add 
@geindex RFC; RFC 9559
RFC 9559@footnote{https://datatracker.ietf.org/doc/html/rfc9559.html} MIME types for Matroska audiovisual container
formats. Patch by Hugo van Kemenade.

@item 
gh-126417@footnote{https://github.com/python/cpython/issues/126417}: Register the @code{multiprocessing.managers.DictProxy} and
@code{multiprocessing.managers.ListProxy} types in
@ref{9b,,multiprocessing.managers} to @ref{1459,,collections.abc.MutableMapping}
and @ref{6c6,,collections.abc.MutableSequence}, respectively.

@item 
gh-126390@footnote{https://github.com/python/cpython/issues/126390}: Add support for returning intermixed options and non-option
arguments in order in @ref{185c,,getopt.gnu_getopt()}.

@item 
gh-126374@footnote{https://github.com/python/cpython/issues/126374}: Add support for options with optional arguments in the
@ref{64,,getopt} module.

@item 
gh-126363@footnote{https://github.com/python/cpython/issues/126363}: Speed up pattern parsing in @ref{73a,,pathlib.Path.glob()} by
skipping creation of a @ref{4ee,,pathlib.Path} object for the pattern.

@item 
gh-126353@footnote{https://github.com/python/cpython/issues/126353}: @ref{56c,,asyncio.get_event_loop()} now does not implicitly creates
an event loop. It now raises a @ref{30d,,RuntimeError} if there is no set
event loop. Patch by Kumar Aditya.

@item 
gh-126313@footnote{https://github.com/python/cpython/issues/126313}: Fix an issue in @ref{1b2a,,curses.napms()} when
@ref{1a1b,,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{1b2b,,os.sched_param} objects.

@item 
gh-126138@footnote{https://github.com/python/cpython/issues/126138}: Fix a use-after-free crash on @ref{460,,asyncio.Task} objects
whose underlying coroutine yields an object that implements an evil
@ref{f90,,__getattribute__()}. Patch by Nico Posada.

@item 
gh-120057@footnote{https://github.com/python/cpython/issues/120057}: Replace the @code{os.environ.refresh()} method with a new
@ref{4e4,,os.reload_environ()} function. Patch by Victor Stinner.

@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{53b,,urllib.request.pathname2url()} and
@ref{539,,url2pathname()} removed slashes from Windows DOS
drive paths and URLs.

@item 
gh-126223@footnote{https://github.com/python/cpython/issues/126223}: Raise a @ref{a67,,UnicodeEncodeError} instead of a
@ref{3ea,,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{53b,,urllib.request.pathname2url()} generated
URLs beginning with four slashes (rather than two) when given a Windows
UNC path.

@item 
gh-126156@footnote{https://github.com/python/cpython/issues/126156}: Improved performances of creating
@ref{fc3,,Morsel} objects by a factor of 3.8x.

@item 
gh-126105@footnote{https://github.com/python/cpython/issues/126105}: Fix a crash in @ref{9,,ast} when the @ref{19da,,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{d8,,ssl}.

@item 
gh-126080@footnote{https://github.com/python/cpython/issues/126080}: Fix a use-after-free crash on @ref{460,,asyncio.Task} objects for
which the underlying event loop implements an evil
@ref{f90,,__getattribute__()}. Reported by Nico-Posada. Patch by
Bénédikt Tran.

@item 
gh-125322@footnote{https://github.com/python/cpython/issues/125322}: Correct detection of complex numbers support in libffi.

@item 
gh-126083@footnote{https://github.com/python/cpython/issues/126083}: Fixed a reference leak in @ref{460,,asyncio.Task} objects when
reinitializing the same object with a non-@code{None} context. Patch by Nico
Posada.

@item 
gh-126068@footnote{https://github.com/python/cpython/issues/126068}: Fix exceptions in the @ref{7,,argparse} module so that only error
messages for ArgumentError and ArgumentTypeError are now translated.
ArgumentError is now only used for command line errors, not for logical
errors in the program. TypeError is now raised instead of ValueError for
some logical errors.

@item 
gh-125413@footnote{https://github.com/python/cpython/issues/125413}: Add @code{pathlib.Path.scandir()} method to efficiently fetch
directory children and their file attributes. This is a trivial wrapper of
@ref{e23,,os.scandir()}.

@item 
gh-125984@footnote{https://github.com/python/cpython/issues/125984}: Fix use-after-free crashes on @ref{f8b,,asyncio.Future} objects
for which the underlying event loop implements an evil
@ref{f90,,__getattribute__()}. Reported by Nico-Posada. Patch by
Bénédikt Tran.

@item 
gh-125926@footnote{https://github.com/python/cpython/issues/125926}: Fix @ref{1247,,urllib.parse.urljoin()} for base URI with undefined
authority. Although 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html} only specify reference resolution for
absolute base URI, @code{urljoin()} should continue to return sensible
result for relative base URI.

@item 
gh-125969@footnote{https://github.com/python/cpython/issues/125969}: Fix an out-of-bounds crash when an evil
@ref{ec8,,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{1b2c,,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-126916@footnote{https://github.com/python/cpython/issues/126916}: Allow the `initial' parameter of @ref{153,,functools.reduce()} to be
passed as a keyword argument. Patch by Sayandip Dutta.

@item 
gh-124452@footnote{https://github.com/python/cpython/issues/124452}: Fix an issue in
@ref{1b2d,,email.policy.EmailPolicy.header_source_parse()} and
@ref{1b2e,,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-117941@footnote{https://github.com/python/cpython/issues/117941}: @code{argparse.BooleanOptionalAction} now rejects option
names starting with @code{--no-}.

@item 
gh-125884@footnote{https://github.com/python/cpython/issues/125884}: Fixed the bug for @ref{aa,,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{ec5,,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-125767@footnote{https://github.com/python/cpython/issues/125767}: @ref{443,,super} objects are now @ref{ab,,pickleable} and
@ref{29,,copyable}.

@item 
gh-124969@footnote{https://github.com/python/cpython/issues/124969}: @code{locale.nl_langinfo(locale.ALT_DIGITS)} now returns a string
again. The returned value consists of up to 100 semicolon-separated
symbols.

@item 
gh-84850@footnote{https://github.com/python/cpython/issues/84850}: Remove @code{URLopener} and @code{FancyURLopener} classes
from @ref{114,,urllib.request}. They had previously raised
@ref{2c9,,DeprecationWarning} since Python 3.3.

@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{1b28,,persistent_id}
and @ref{1b2f,,persistent_load} attributes of instances of
the @code{Pickler} and @code{Unpickler} classes in the @ref{ab,,pickle}
module.

@item 
gh-125378@footnote{https://github.com/python/cpython/issues/125378}: Fixed the bug in @ref{aa,,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{22f,,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{22f,,json.loads()}.

@item 
gh-52551@footnote{https://github.com/python/cpython/issues/52551}: Use @code{wcsftime()} to implement @ref{1592,,time.strftime()} on
Windows.

@item 
gh-125259@footnote{https://github.com/python/cpython/issues/125259}: Fix the notes removal logic for errors thrown in enum
initialization.

@item 
gh-125633@footnote{https://github.com/python/cpython/issues/125633}: Add function @ref{4c0,,inspect.ispackage()} to determine whether an
object is a @ref{4c1,,package} or not.

@item 
gh-125614@footnote{https://github.com/python/cpython/issues/125614}: In the @ref{40c,,FORWARDREF} format of
@ref{6,,annotationlib}, fix bug where nested expressions were not returned
as @ref{1967,,annotationlib.ForwardRef} format.

@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-125600@footnote{https://github.com/python/cpython/issues/125600}: Only show stale code warning in @ref{aa,,pdb} when we display
source code.

@item 
gh-125542@footnote{https://github.com/python/cpython/issues/125542}: Deprecate passing keyword-only `prefix_chars' argument to
@ref{31d,,argparse.ArgumentParser.add_argument_group()}.

@item 
gh-125541@footnote{https://github.com/python/cpython/issues/125541}: Pressing @code{Ctrl}-@code{C} while blocked in
@ref{a87,,threading.Lock.acquire()}, @ref{122c,,threading.RLock.acquire()}, and
@ref{158d,,threading.Thread.join()} now interrupts the function call and raises
a @ref{d96,,KeyboardInterrupt} exception on Windows, similar to how those
functions behave on macOS and Linux.

@item 
gh-125519@footnote{https://github.com/python/cpython/issues/125519}: Improve traceback if @ref{928,,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{206,,concurrent.futures.ProcessPoolExecutor} shuts down concurrently
with an error when feeding a job to a worker process.

@item 
gh-125115@footnote{https://github.com/python/cpython/issues/125115}: Fixed a bug in @ref{aa,,pdb} where arguments starting with @code{-}
can’t be passed to the debugged script.

@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{11a,,venv} when running in Git Bash for Windows.

@item 
gh-125245@footnote{https://github.com/python/cpython/issues/125245}: Fix race condition when importing @ref{1f,,collections.abc}, which
could incorrectly return an empty module.

@item 
gh-52551@footnote{https://github.com/python/cpython/issues/52551}: Fix encoding issues in @ref{1592,,time.strftime()}, the
@ref{1051,,strftime()} method of the @ref{33,,datetime} classes
@ref{6e7,,datetime}, @ref{48d,,date} and
@ref{48e,,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-124984@footnote{https://github.com/python/cpython/issues/124984}: Fixed thread safety in @ref{d8,,ssl} in the free-threaded build.
OpenSSL operations are now protected by a per-object lock.

@item 
gh-124651@footnote{https://github.com/python/cpython/issues/124651}: Properly quote template strings in @ref{11a,,venv} activation
scripts.

@item 
gh-124694@footnote{https://github.com/python/cpython/issues/124694}: We’ve added
@ref{46a,,concurrent.futures.InterpreterPoolExecutor}, which allows you to
run code in multiple isolated interpreters.  This allows you to circumvent
the limitations of CPU-bound threads (due to the GIL). Patch by Eric Snow.

This addition is unrelated to 
@geindex Python Enhancement Proposals; PEP 734
PEP 734@footnote{https://peps.python.org/pep-0734/}.

@item 
gh-58032@footnote{https://github.com/python/cpython/issues/58032}: Deprecate the @ref{31e,,argparse.FileType} type converter.

@item 
gh-99749@footnote{https://github.com/python/cpython/issues/99749}: Adds a feature to optionally enable suggestions for argument
choices and subparser names if mistyped by the user.

@item 
gh-58956@footnote{https://github.com/python/cpython/issues/58956}: Fixed a bug in @ref{aa,,pdb} where sometimes the breakpoint won’t
trigger if it was set on a function which is already in the call stack.

@item 
gh-124111@footnote{https://github.com/python/cpython/issues/124111}: The tkinter module can now be built to use either the new
version 9.0.0 of Tcl/Tk or the latest release 8.6.15 of Tcl/Tk 8.  Tcl/Tk
9 includes many improvements, both to the Tcl language and to the
appearance and utility of the graphical user interface provided by Tk.

@item 
gh-80958@footnote{https://github.com/python/cpython/issues/80958}: unittest discovery supports PEP 420 namespace packages as start
directory again.

@item 
gh-123370@footnote{https://github.com/python/cpython/issues/123370}: Fix the canvas not clearing after running turtledemo clock.

@item 
gh-89083@footnote{https://github.com/python/cpython/issues/89083}: Add @ref{540,,uuid.uuid8()} for generating UUIDv8 objects as
specified in 
@geindex RFC; RFC 9562
RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html}. Patch by Bénédikt Tran

@item 
gh-122549@footnote{https://github.com/python/cpython/issues/122549}: Add @ref{505,,platform.invalidate_caches()} to invalidate cached
results.

@item 
gh-120754@footnote{https://github.com/python/cpython/issues/120754}: Update unbounded @code{read} calls in @ref{13a,,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-121267@footnote{https://github.com/python/cpython/issues/121267}: Improve the performance of @ref{e7,,tarfile} when writing files,
by caching user names and group names.

@item 
gh-70764@footnote{https://github.com/python/cpython/issues/70764}: Fixed an issue where @ref{1481,,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{1402,,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{16bf,,os.path.abspath()} on
Windows.

@item 
gh-97850@footnote{https://github.com/python/cpython/issues/97850}: Remove deprecated @code{pkgutil.get_loader()} and
@code{pkgutil.find_loader()}.

@item 
gh-118986@footnote{https://github.com/python/cpython/issues/118986}: Add @code{socket.IPV6_RECVERR} constant (available since
Linux 2.2).

@item 
gh-116897@footnote{https://github.com/python/cpython/issues/116897}: Accepting objects with false values (like @code{0} and @code{[]})
except empty strings, byte-like objects and @code{None} in
@ref{113,,urllib.parse} functions @ref{588,,parse_qsl()} and
@ref{589,,parse_qs()} is now deprecated.

@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-71936@footnote{https://github.com/python/cpython/issues/71936}: Fix a race condition in @ref{1315,,multiprocessing.pool.Pool}.

@item 
bpo-46128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46128}: Strip @ref{342,,unittest.IsolatedAsyncioTestCase} stack frames
from reported stacktraces.

@item 
gh-84852@footnote{https://github.com/python/cpython/issues/84852}: Add MIME types for MS Embedded OpenType, OpenType Layout,
TrueType, WOFF 1.0 and 2.0 fonts. Patch by Sahil Prajapati and Hugo van
Kemenade.
@end itemize

@node Documentation<13>,Core and Builtins<45>,Library<47>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id189}@anchor{1b30}
@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-60712@footnote{https://github.com/python/cpython/issues/60712}: Include the @ref{e4d,,object} type in the lists of documented
types. Change by Furkan Onder and Martin Panter.
@end itemize

@node Core and Builtins<45>,Library<48>,Documentation<13>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id190}@anchor{1b31}
@subsubsection Core and Builtins



@itemize -

@item 
gh-126795@footnote{https://github.com/python/cpython/issues/126795}: Increase the threshold for JIT code warmup. Depending on
platform and workload, this can result in performance gains of 1-9% and
memory savings of 3-5%.

@item 
gh-126341@footnote{https://github.com/python/cpython/issues/126341}: Now @ref{277,,ValueError} is raised instead of @ref{3ea,,SystemError}
when trying to iterate over a released @ref{1d2,,memoryview} object.

@item 
gh-126688@footnote{https://github.com/python/cpython/issues/126688}: Fix a crash when calling @ref{6bd,,os.fork()} on some operating
systems, including SerenityOS.
@end itemize

@node Library<48>,Core and Builtins<46>,Core and Builtins<45>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id191}@anchor{1b32}
@subsubsection Library



@itemize -

@item 
gh-126066@footnote{https://github.com/python/cpython/issues/126066}: Fix @ref{7a,,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.
@end itemize

@node Core and Builtins<46>,Library<49>,Library<48>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id192}@anchor{1b33}
@subsubsection Core and Builtins



@itemize -

@item 
gh-126222@footnote{https://github.com/python/cpython/issues/126222}: Do not include count of «peek» items in @code{_PyUop_num_popped}.
This ensures that the correct number of items are popped from the stack
when a micro-op exits with an error.

@item 
gh-126366@footnote{https://github.com/python/cpython/issues/126366}: Fix crash when using @code{yield from} on an object that raises an
exception in its @code{__iter__}.
@end itemize

@node Library<49>,Core and Builtins<47>,Core and Builtins<46>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id193}@anchor{1b34}
@subsubsection Library



@itemize -

@item 
gh-126209@footnote{https://github.com/python/cpython/issues/126209}: Fix an issue with @code{skip_file_prefixes} parameter which
resulted in an inconsistent behaviour between the C and Python
implementations of @ref{18bb,,warnings.warn()}. Patch by Daehee Kim.
@end itemize

@node Core and Builtins<47>,Library<50>,Library<49>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id194}@anchor{1b35}
@subsubsection Core and Builtins



@itemize -

@item 
gh-126312@footnote{https://github.com/python/cpython/issues/126312}: Fix crash during garbage collection on an object frozen by
@ref{ef8,,gc.freeze()} on the free-threaded build.

@item 
gh-103951@footnote{https://github.com/python/cpython/issues/103951}: Relax optimization requirements to allow fast attribute access
to module subclasses.

@item 
gh-126072@footnote{https://github.com/python/cpython/issues/126072}: Following gh-126101@footnote{https://github.com/python/cpython/issues/126101}, for @ref{9b4,,Code Objects} like lambda,
annotation and type alias, we no longer  add @code{None} to its
@ref{1abf,,co_consts}.

@item 
gh-126195@footnote{https://github.com/python/cpython/issues/126195}: Improve JIT performance by 1.4% on macOS Apple Silicon by using
platform-specific memory protection APIs. Patch by Diego Russo.

@item 
gh-126139@footnote{https://github.com/python/cpython/issues/126139}: Provide better error location when attempting to use a
@ref{1166,,future statement} with an unknown future feature.

@item 
gh-126072@footnote{https://github.com/python/cpython/issues/126072}: Add a new attribute in @ref{1afc,,co_flags} to indicate
whether the first item in @ref{1abf,,co_consts} is the docstring.
If a code object has no docstring, @code{None} will `NOT' be inserted.

@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{108,,tracemalloc} and its associated
hooks. Patch by Pablo Galindo.

@item 
gh-90370@footnote{https://github.com/python/cpython/issues/90370}: Avoid temporary tuple creation for vararg in argument passing
with Argument Clinic generated code (if arguments either vararg or
positional-only).

@item 
gh-126018@footnote{https://github.com/python/cpython/issues/126018}: Fix a crash in @ref{1b36,,sys.audit()} when passing a non-string as
first argument and Python was compiled in debug mode.

@item 
gh-126012@footnote{https://github.com/python/cpython/issues/126012}: The @ref{1d2,,memoryview} type now supports subscription, making
it a @ref{1d1,,generic type}.

@item 
gh-125837@footnote{https://github.com/python/cpython/issues/125837}: Adds @ref{59d,,LOAD_SMALL_INT} and
@code{LOAD_CONST_IMMORTAL} instructions. @code{LOAD_SMALL_INT} pushes a
small integer equal to the @code{oparg} to the stack. @code{LOAD_CONST_IMMORTAL}
does the same as @code{LOAD_CONST} but is more efficient for immortal
objects. Removes @code{RETURN_CONST}  instruction.

@item 
gh-125942@footnote{https://github.com/python/cpython/issues/125942}: On Android, the @code{errors} setting of @ref{e9c,,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{bdd,,gc.get_objects()} or @ref{bde,,gc.get_referrers()} is called during an
in-progress garbage collection.

@item 
gh-125868@footnote{https://github.com/python/cpython/issues/125868}: It was possible in 3.14.0a1 only for attribute lookup to give
the wrong value. This was due to an incorrect specialization in very
specific circumstances. This is fixed in 3.14.0a2.

@item 
gh-125498@footnote{https://github.com/python/cpython/issues/125498}: The JIT has been updated to leverage Clang 19’s new
@code{preserve_none} attribute, which supports more platforms and is more
useful than LLVM’s existing @code{ghccc} calling convention. This also
removes the need to manually patch the calling convention in LLVM IR,
simplifying the JIT compilation process.

@item 
gh-125703@footnote{https://github.com/python/cpython/issues/125703}: Correctly honour @ref{108,,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-125017@footnote{https://github.com/python/cpython/issues/125017}: Fix crash on certain accesses to the @code{__annotations__} of
@ref{666,,staticmethod} and @ref{69a,,classmethod} objects.

@item 
gh-125588@footnote{https://github.com/python/cpython/issues/125588}: The Python PEG generator can now use f-strings in the grammar
actions. Patch by Pablo Galindo

@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-118423@footnote{https://github.com/python/cpython/issues/118423}: Add a new @code{INSTRUCTION_SIZE} macro to the cases generator
which returns the current instruction size.

@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-124855@footnote{https://github.com/python/cpython/issues/124855}: Don’t allow the JIT and perf support to be active at the same
time. Patch by Pablo Galindo

@item 
gh-123714@footnote{https://github.com/python/cpython/issues/123714}: Update JIT compilation to use LLVM 19

@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{1bd,,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-119793@footnote{https://github.com/python/cpython/issues/119793}: The @ref{43e,,map()} built-in now has an optional keyword-only
`strict' flag like @ref{43f,,zip()} to check that all the iterables are of
equal length. Patch by Wannes Boeykens.
@end itemize

@node Library<50>,C API<15>,Core and Builtins<47>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id195}@anchor{1b37}
@subsubsection Library



@itemize -

@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.
@end itemize

@node C API<15>,Build<14>,Library<50>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id196}@anchor{1b38}
@subsubsection C API



@itemize -

@item 
gh-126554@footnote{https://github.com/python/cpython/issues/126554}: Fix error handling in @ref{dad,,ctypes.CDLL} objects which could
result in a crash in rare situations.

@item 
gh-126061@footnote{https://github.com/python/cpython/issues/126061}: Add @ref{5c8,,PyLong_IsPositive()}, @ref{5c9,,PyLong_IsNegative()}
and @ref{5ca,,PyLong_IsZero()} for checking if a @ref{5cb,,PyLongObject} is
positive, negative, or zero, respectively.

@item 
gh-125608@footnote{https://github.com/python/cpython/issues/125608}: Fix a bug where dictionary watchers (e.g.,
@ref{969,,PyDict_Watch()}) on an object’s attribute dictionary
(@ref{1bf,,__dict__}) were not triggered when the object’s attributes
were modified.

@item 
gh-123619@footnote{https://github.com/python/cpython/issues/123619}: Added the @ref{5f1,,PyUnstable_Object_EnableDeferredRefcount()}
function for enabling 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/} deferred reference counting.

@item 
gh-121654@footnote{https://github.com/python/cpython/issues/121654}: Add @ref{5dc,,PyType_Freeze()} function to make a type immutable.
Patch by Victor Stinner.

@item 
gh-120026@footnote{https://github.com/python/cpython/issues/120026}: The @code{Py_HUGE_VAL} macro is @ref{1a7,,soft deprecated}.
@end itemize

@node Build<14>,,C API<15>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id197}@anchor{1b39}
@subsubsection Build



@itemize -

@item 
gh-126691@footnote{https://github.com/python/cpython/issues/126691}: Removed the @code{--with-emscripten-target} configure flag. We
unified the @code{node} and @code{browser} options and the same build can now be
used, independent of target runtime.

@item 
gh-123877@footnote{https://github.com/python/cpython/issues/123877}: Use @code{wasm32-wasip1} as the target triple for WASI instead of
@code{wasm32-wasi}. The latter will eventually be reclaimed for WASI 1.0
while CPython currently only supports WASI preview1.

@item 
gh-126458@footnote{https://github.com/python/cpython/issues/126458}: Disable SIMD support for HACL under WASI.

@item 
gh-89640@footnote{https://github.com/python/cpython/issues/89640}: Hard-code float word ordering as little endian on WASM.

@item 
gh-126206@footnote{https://github.com/python/cpython/issues/126206}: @code{make clinic} now runs Argument Clinic using the @code{--force}
option, thus forcefully regenerating generated code.

@item 
gh-126187@footnote{https://github.com/python/cpython/issues/126187}: Introduced @code{Tools/wasm/emscripten.py} to simplify doing
Emscripten builds.

@item 
gh-124932@footnote{https://github.com/python/cpython/issues/124932}: For cross builds, there is now support for having a different
install @code{prefix} than the @code{host_prefix} used by @code{getpath.py}. This
is set to @code{/} by default for Emscripten, on other platforms the default
behavior is the same as before.

@item 
gh-125946@footnote{https://github.com/python/cpython/issues/125946}: The minimum supported Android version is now 7.0 (API level
24).

@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-124928@footnote{https://github.com/python/cpython/issues/124928}: Emscripten builds now require node >= 18.

@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 14 0 alpha 1,Python 3 13 0 beta 1,Python 3 14 0 alpha 2,Changelog
@anchor{whatsnew/changelog python-3-14-0-alpha-1}@anchor{1b3a}
@subsection Python 3.14.0 alpha 1


`Release date: 2024-10-15'

@menu
* macOS: macOS<9>. 
* Windows: Windows<13>. 
* Tools/Demos: Tools/Demos<13>. 
* Tests: Tests<17>. 
* Security: Security<15>. 
* Library: Library<51>. 
* IDLE: IDLE<8>. 
* Documentation: Documentation<14>. 
* Core and Builtins: Core and Builtins<48>. 
* Library: Library<52>. 
* Core and Builtins: Core and Builtins<49>. 
* Library: Library<53>. 
* Core and Builtins: Core and Builtins<50>. 
* Library: Library<54>. 
* Core and Builtins: Core and Builtins<51>. 
* Library: Library<55>. 
* Core and Builtins: Core and Builtins<52>. 
* Library: Library<56>. 
* Core and Builtins: Core and Builtins<53>. 
* Library: Library<57>. 
* Core and Builtins: Core and Builtins<54>. 
* Library: Library<58>. 
* Core and Builtins: Core and Builtins<55>. 
* C API: C API<16>. 
* Build: Build<15>. 

@end menu

@node macOS<9>,Windows<13>,,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id198}@anchor{1b3b}
@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.

@item 
gh-123797@footnote{https://github.com/python/cpython/issues/123797}: Check for runtime availability of @code{ptsname_r} function on
macos.

@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<13>,Tools/Demos<13>,macOS<9>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id199}@anchor{1b3c}
@subsubsection Windows



@itemize -

@item 
gh-124487@footnote{https://github.com/python/cpython/issues/124487}: Increases Windows required OS and API level to Windows 10.

@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-124448@footnote{https://github.com/python/cpython/issues/124448}: Updated bundled Tcl/Tk to 8.6.15.

@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.

@item 
gh-123418@footnote{https://github.com/python/cpython/issues/123418}: Updated Windows build to use OpenSSL 3.0.15.

@item 
gh-123476@footnote{https://github.com/python/cpython/issues/123476}: Add support for @code{socket.TCP_QUICKACK} on Windows platforms.

@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{93,,mimetypes} no longer fails when it encounters an
inaccessible registry key.

@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{94,,mmap} on Windows when the mapped memory
is inaccessible due to file system errors or access violations.

@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<13>,Tests<17>,Windows<13>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id200}@anchor{1b3d}
@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<17>,Security<15>,Tools/Demos<13>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id201}@anchor{1b3e}
@subsubsection Tests



@itemize -

@item 
gh-125041@footnote{https://github.com/python/cpython/issues/125041}: Re-enable skipped tests for @ref{13c,,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-124378@footnote{https://github.com/python/cpython/issues/124378}: Updated @code{test_ttk} to pass with Tcl/Tk 8.6.15.

@item 
gh-124213@footnote{https://github.com/python/cpython/issues/124213}: Detect whether the test suite is running inside a
systemd-nspawn container with @code{--suppress-sync=true} option, and skip
the @code{test_os} and @code{test_mmap} tests that are failing in this scenario.

@item 
gh-124190@footnote{https://github.com/python/cpython/issues/124190}: Add capability to ignore entire files or directories in check
warning CI tool

@item 
gh-121921@footnote{https://github.com/python/cpython/issues/121921}: Update @code{Lib/test/crashers/bogus_code_obj.py} so that it
crashes properly again.

@item 
gh-112301@footnote{https://github.com/python/cpython/issues/112301}: Add tooling to check for changes in compiler warnings. Patch by
Nate Ohlson.

@item 
gh-59022@footnote{https://github.com/python/cpython/issues/59022}: Add tests for @ref{1b3f,,pkgutil.extend_path()}. Patch by Andreas
Stocker.

@item 
gh-99242@footnote{https://github.com/python/cpython/issues/99242}: @ref{1b40,,os.getloadavg()} may throw @ref{53c,,OSError} when running
regression tests under certain conditions (e.g. chroot). This error is now
caught and ignored, since reporting load average is optional.

@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{1b41,,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.

@item 
gh-120801@footnote{https://github.com/python/cpython/issues/120801}: Cleaned up fixtures for importlib.metadata tests and
consolidated behavior with “test.support.os_helper”.

@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-119273@footnote{https://github.com/python/cpython/issues/119273}: Python test runner no longer runs tests using TTY (ex:
test_ioctl) in a process group (using @code{setsid()}). Previously, tests
using TTY were skipped. Patch by Victor Stinner.

@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.

@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.

@item 
gh-107562@footnote{https://github.com/python/cpython/issues/107562}: Test certificates have been updated to expire far in the
future. This allows testing Y2038 with system time set to after that, so
that actual Y2038 issues can be exposed, and not masked by expired
certificate errors.
@end itemize

@node Security<15>,Library<51>,Tests<17>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id202}@anchor{1b42}
@subsubsection Security



@itemize -

@item 
gh-125140@footnote{https://github.com/python/cpython/issues/125140}: Remove the current directory from @code{sys.path} when using
PyREPL.

@item 
gh-123678@footnote{https://github.com/python/cpython/issues/123678}: Upgrade libexpat to 2.6.3

@item 
gh-112301@footnote{https://github.com/python/cpython/issues/112301}: Enable compiler options that warn of potential security
vulnerabilities.

@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}.

@item 
gh-112301@footnote{https://github.com/python/cpython/issues/112301}: Add ability to ignore warnings per file with warning count in
warning checking tooling. Patch by Nate Ohlson.

@item 
gh-112301@footnote{https://github.com/python/cpython/issues/112301}: Add macOS warning tracking to warning check tooling. Patch by
Nate Ohlson.

@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}.

@item 
gh-112301@footnote{https://github.com/python/cpython/issues/112301}: Enable runtime protections for glibc to abort execution when
unsafe behavior is encountered, for all platforms except Windows.

@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.

@item 
gh-112301@footnote{https://github.com/python/cpython/issues/112301}: Add default compiler options to improve security. Enable
-Wimplicit-fallthrough, -fstack-protector-strong, -Wtrampolines.

@item 
gh-118773@footnote{https://github.com/python/cpython/issues/118773}: Fixes creation of ACLs in @ref{72e,,os.mkdir()} on Windows to work
correctly on non-English machines.

@item 
gh-118486@footnote{https://github.com/python/cpython/issues/118486}: @ref{72e,,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{730,,tempfile.mkdtemp()} in scenarios where the
base temporary directory is more permissive than the default.
@end itemize

@node Library<51>,IDLE<8>,Security<15>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id203}@anchor{1b43}
@subsubsection Library



@itemize -

@item 
gh-125422@footnote{https://github.com/python/cpython/issues/125422}: Fixed the bug where @ref{aa,,pdb} and @ref{10,,bdb} can step into the
bottom caller frame.

@item 
gh-100141@footnote{https://github.com/python/cpython/issues/100141}: Fixed the bug where @ref{aa,,pdb} will be stuck in an infinite
loop when debugging an empty file.

@item 
gh-53203@footnote{https://github.com/python/cpython/issues/53203}: Fix @ref{17cf,,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-125206@footnote{https://github.com/python/cpython/issues/125206}: Workaround for old libffi versions is added. Module ctypes
supports double complex only with libffi >= 3.3.0. Patch by
Mikhail Efimov.

@item 
gh-89967@footnote{https://github.com/python/cpython/issues/89967}: Make @ref{1b44,,WeakKeyDictionary} and
@ref{1b45,,WeakValueDictionary} safe against concurrent mutations
from other threads. Patch by Kumar Aditya.

@item 
gh-125260@footnote{https://github.com/python/cpython/issues/125260}: The @ref{a2d,,gzip.compress()} `mtime' parameter now defaults to 0
for reproducible output. Patch by Bernhard M. Wiedemann and Adam Turner.

@item 
gh-125243@footnote{https://github.com/python/cpython/issues/125243}: Fix data race when creating @ref{cb1,,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{7,,argparse}.

@item 
gh-125235@footnote{https://github.com/python/cpython/issues/125235}: Keep @ref{f9,,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{1dc,,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-125118@footnote{https://github.com/python/cpython/issues/125118}: Don’t copy arbitrary values to _Bool in the
@ref{de,,struct} module.

@item 
gh-125069@footnote{https://github.com/python/cpython/issues/125069}: Fix an issue where providing a @ref{8b6,,pathlib.PurePath} object
as an initializer argument to a second @code{PurePath} object
with a different @ref{739,,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 μεταβλητή περιβάλλοντος; PYTHON_BASIC_REPL
@ref{452,,PYTHON_BASIC_REPL} environment variable is set,
the @ref{cf,,site} module no longer imports the @code{_pyrepl} module.
Moreover, the @code{site} module now respects @ref{d27,,-E} and
@ref{d28,,-I} command line options: ignore 
@geindex PYTHON_BASIC_REPL
@geindex μεταβλητή περιβάλλοντος; PYTHON_BASIC_REPL
@code{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)}. Now it returns a
tuple of up to 100 strings (an empty tuple on most locales). Previously it
returned the first item of that tuple 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-69998@footnote{https://github.com/python/cpython/issues/69998}: Fix @ref{667,,locale.nl_langinfo()} in case when different categories
have different locales. The function now sets temporarily the @code{LC_CTYPE}
locale in some cases. This temporary change affects other threads.

@item 
gh-124958@footnote{https://github.com/python/cpython/issues/124958}: Fix refcycles in exceptions raised from
@ref{6d7,,asyncio.TaskGroup} and the python implementation of
@ref{f8b,,asyncio.Future}

@item 
gh-53203@footnote{https://github.com/python/cpython/issues/53203}: Fix @ref{17cf,,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-123961@footnote{https://github.com/python/cpython/issues/123961}: Convert @ref{2e,,curses} to multi-phase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}), thereby fixing reference leaks at interpreter shutdown.
Patch by Bénédikt Tran.

@item 
gh-124944@footnote{https://github.com/python/cpython/issues/124944}: Add @code{SO_ORIGINAL_DST} to the @ref{d4,,socket} module.

@item 
gh-117151@footnote{https://github.com/python/cpython/issues/117151}: The default buffer size used by @ref{e21,,shutil.copyfileobj()} has
been increased from 64k to 256k on non-Windows platforms. It was already
larger on Windows.

@item 
gh-90102@footnote{https://github.com/python/cpython/issues/90102}: Skip the @code{isatty} system call during open() when the file is
known to not be a character device. This provides a slight performance
improvement when reading whole files.

@item 
gh-124917@footnote{https://github.com/python/cpython/issues/124917}: Allow calling @ref{dd2,,os.path.exists()} and
@ref{dd3,,os.path.lexists()} with keyword arguments on Windows. Fixes a
regression in 3.13.0.

@item 
gh-65865@footnote{https://github.com/python/cpython/issues/65865}: @ref{7,,argparse} now raises early error for invalid @code{help}
arguments to @ref{3ed,,add_argument()},
@ref{fd6,,add_subparsers()} and @code{add_parser()}.

@item 
gh-124653@footnote{https://github.com/python/cpython/issues/124653}: Fix detection of the minimal Queue API needed by the
@ref{8a,,logging} module. Patch by Bénédikt Tran.

@item 
gh-91818@footnote{https://github.com/python/cpython/issues/91818}: The CLI of many modules (@ref{9,,ast}, @ref{58,,ensurepip},
@ref{85,,json}, @ref{aa,,pdb}, @ref{d7,,sqlite3}, @ref{104,,tokenize}, @ref{11a,,venv}) now
uses the actual executable name instead of simply «python» to display in
the usage message.

@item 
gh-124858@footnote{https://github.com/python/cpython/issues/124858}: Fix reference cycles left in tracebacks in
@ref{edc,,asyncio.open_connection()} when used with @code{happy_eyeballs_delay}

@item 
gh-124390@footnote{https://github.com/python/cpython/issues/124390}: Fixed @ref{a97,,AssertionError} when using
@code{asyncio.staggered.staggered_race()} with
@ref{88d,,asyncio.eager_task_factory}.

@item 
gh-85935@footnote{https://github.com/python/cpython/issues/85935}: @ref{3ed,,argparse.ArgumentParser.add_argument()} now raises an
exception if an @ref{1b46,,action} that does not consume arguments (like
“store_const” or “store_true”) or explicit @code{nargs=0} are specified for
positional arguments.

@item 
gh-124835@footnote{https://github.com/python/cpython/issues/124835}: Make @ref{1b47,,tomllib.loads()} raise @ref{291,,TypeError} not
@ref{1a9,,AttributeError} on bad input types that do not have the @code{replace}
attribute. Improve error message when @ref{1c7,,bytes} is received.

@item 
gh-124693@footnote{https://github.com/python/cpython/issues/124693}: Fix a bug where @ref{7,,argparse} doesn’t recognize negative
complex numbers or negative numbers using scientific notation.

@item 
gh-124787@footnote{https://github.com/python/cpython/issues/124787}: Fix @ref{52a,,typing.TypeAliasType} with incorrect
@code{type_params} argument. Now it raises a @ref{291,,TypeError} when a type
parameter without a default follows one with a default, and when an entry
in the @code{type_params} tuple is not a type parameter object.

@item 
gh-66436@footnote{https://github.com/python/cpython/issues/66436}: Improved @ref{457,,prog} default value for
@ref{1dc,,argparse.ArgumentParser}. It will now include the name of the
Python executable along with the module or package name, or the path to a
directory, ZIP file, or directory within a ZIP file if the code was run
that way.

@item 
gh-116850@footnote{https://github.com/python/cpython/issues/116850}: Fix @ref{7,,argparse} for namespaces with not directly writable
dict (e.g. classes).

@item 
gh-101552@footnote{https://github.com/python/cpython/issues/101552}: Add an `annoation_format' parameter to
@ref{4bd,,inspect.signature()}. Add an `quote_annotation_strings' parameter to
@ref{4bf,,inspect.Signature.format()}. Use the new functionality to improve the
display of annotations in signatures in @ref{bd,,pydoc}. Patch by Jelle
Zijlstra.

@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{7,,argparse}.

@item 
gh-124594@footnote{https://github.com/python/cpython/issues/124594}: All @ref{b,,asyncio} REPL prompts run in the same @ref{421,,context}. Contributed by Bartosz Sławecki.

@item 
gh-61181@footnote{https://github.com/python/cpython/issues/61181}: Fix support of @ref{1b48,,choices} with string value in
@ref{7,,argparse}. Substrings of the specified string no longer considered
valid values.

@item 
gh-116750@footnote{https://github.com/python/cpython/issues/116750}: Provide @ref{1b49,,sys.monitoring.clear_tool_id()} to unregister all
events and callbacks set by the tool.

@item 
gh-124552@footnote{https://github.com/python/cpython/issues/124552}: Improve the accuracy of @ref{10,,bdb}’s check for the possibility
of breakpoint in a frame. This makes it possible to disable unnecessary
events in functions.

@item 
gh-124538@footnote{https://github.com/python/cpython/issues/124538}: Fixed crash when using @ref{bdf,,gc.get_referents()} on a capsule
object.

@item 
gh-80259@footnote{https://github.com/python/cpython/issues/80259}: Fix @ref{7,,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{1b4a,,curses.resizeterm()} and @ref{1b4b,,curses.resize_term()}.

@item 
gh-124498@footnote{https://github.com/python/cpython/issues/124498}: Fix @ref{52a,,typing.TypeAliasType} not to be generic, when
@code{type_params} is an empty tuple.

@item 
gh-53834@footnote{https://github.com/python/cpython/issues/53834}: Fix support of arguments with @ref{1b48,,choices} in @ref{7,,argparse}.
Positional arguments with @ref{1936,,nargs} equal to @code{'?'} or @code{'*'} no
longer check @ref{1b4c,,default} against @code{choices}. Optional arguments with
@code{nargs} equal to @code{'?'} no longer check @ref{1b4d,,const} against
@code{choices}.

@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-123017@footnote{https://github.com/python/cpython/issues/123017}: Due to unreliable results on some devices,
@ref{1592,,time.strftime()} no longer accepts negative years on Android.

@item 
gh-123014@footnote{https://github.com/python/cpython/issues/123014}: @ref{267,,os.pidfd_open()} and @ref{cf8,,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-124176@footnote{https://github.com/python/cpython/issues/124176}: Add support for @ref{6e6,,dataclasses.dataclass()} in
@ref{1b4e,,unittest.mock.create_autospec()}. Now @code{create_autospec} will check
for potential dataclasses and use @ref{1b4f,,dataclasses.fields()} function to
retrieve the spec information.

@item 
gh-124345@footnote{https://github.com/python/cpython/issues/124345}: @ref{7,,argparse} supports abbreviated single-dash long options
separated by @code{=} from its value.

@item 
gh-124400@footnote{https://github.com/python/cpython/issues/124400}: Fixed a @ref{aa,,pdb} bug where @code{until} has no effect when it
appears in a @code{commands} sequence. Also avoid printing the frame
information at a breakpoint that has a command list containing a command
that resumes execution.

@item 
gh-90562@footnote{https://github.com/python/cpython/issues/90562}: Modify dataclasses to support zero-argument super() when
@code{slots=True} is specified.  This works by modifying all references to
@code{__class__} to point to the newly created class.

@item 
gh-104860@footnote{https://github.com/python/cpython/issues/104860}: Fix disallowing abbreviation of single-dash long options in
@ref{7,,argparse} with @code{allow_abbrev=False}.

@item 
gh-63143@footnote{https://github.com/python/cpython/issues/63143}: Fix parsing mutually exclusive arguments in @ref{7,,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{1936,,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{1936,,nargs} equal to
@code{'?'} or @code{'*'} if it is preceded by an option and another positional
argument.

@item 
gh-100980@footnote{https://github.com/python/cpython/issues/100980}: The @ref{1b50,,_fields_} attribute of
@ref{47c,,ctypes.Structure} and @ref{47d,,Union} is no longer set if
the setattr operation raises an error.

@item 
gh-53780@footnote{https://github.com/python/cpython/issues/53780}: @ref{7,,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{83,,ipaddress} module.

@item 
gh-111513@footnote{https://github.com/python/cpython/issues/111513}: Improve the error message that may be raised by
@ref{f92,,datetime.date.fromtimestamp()}.

@item 
gh-124248@footnote{https://github.com/python/cpython/issues/124248}: Fixed potential crash when using @ref{de,,struct} to process
zero-width “Pascal string” fields (@code{0p}).

@item 
gh-81691@footnote{https://github.com/python/cpython/issues/81691}: Fix handling of multiple @code{"--"} (double dashes) in
@ref{7,,argparse}. Only the first one has now been removed, all subsequent
ones are now taken literally.

@item 
gh-87041@footnote{https://github.com/python/cpython/issues/87041}: Fix a bug in @ref{7,,argparse} where lengthy subparser argument
help is incorrectly indented.

@item 
gh-84559@footnote{https://github.com/python/cpython/issues/84559}: The default @ref{98,,multiprocessing} start method on Linux and
other POSIX systems has been changed away from often unsafe @code{"fork"} to
@code{"forkserver"} (when the platform supports sending file handles over
pipes as most do) or @code{"spawn"}.  Mac and Windows are unchanged as they
already default to @code{"spawn"}.

@item 
gh-124212@footnote{https://github.com/python/cpython/issues/124212}: Fix invalid variable in @ref{11a,,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-123978@footnote{https://github.com/python/cpython/issues/123978}: Remove broken @ref{d03,,time.thread_time()} and
@ref{f50,,time.thread_time_ns()} on NetBSD.

@item 
gh-123934@footnote{https://github.com/python/cpython/issues/123934}: Fix @ref{1240,,unittest.mock.MagicMock} resetting magic methods
return values after @code{.reset_mock(return_value=True)} was called.

@item 
gh-124016@footnote{https://github.com/python/cpython/issues/124016}: Update @ref{10e,,unicodedata} database to Unicode 16.0.0.

@item 
gh-123968@footnote{https://github.com/python/cpython/issues/123968}: Fix the command-line interface for the @ref{c0,,random} module to
select floats between 0 and N, not 1 and N.

@item 
gh-123945@footnote{https://github.com/python/cpython/issues/123945}: Fix a bug where @ref{7,,argparse} doesn’t recognize negative
numbers with underscores

@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-123892@footnote{https://github.com/python/cpython/issues/123892}: Add @code{"_wmi"} to @ref{c1a,,sys.stdlib_module_names}. Patch by
Victor Stinner.

@item 
gh-84808@footnote{https://github.com/python/cpython/issues/84808}: Fix error handling in @ref{115a,,socket} method
@ref{18db,,connect_ex()} on platforms where @code{errno}
can be negative.

@item 
gh-123756@footnote{https://github.com/python/cpython/issues/123756}: Added a new argument @code{mode} to @ref{4fb,,pdb.Pdb}. Only allow
@ref{aa,,pdb} from command line to use @code{restart} command.

@item 
gh-122765@footnote{https://github.com/python/cpython/issues/122765}: Fix unbalanced quote errors occurring when activate.csh in
@ref{11a,,venv} was sourced with a custom prompt containing unpaired quotes or
newlines.

@item 
gh-123657@footnote{https://github.com/python/cpython/issues/123657}: Fix crash and memory leak in @ref{1b51,,decimal.getcontext()}. It
crashed when using a thread-local context by
@code{--with-decimal-contextvar=no}.

@item 
gh-123339@footnote{https://github.com/python/cpython/issues/123339}: Fix @ref{1a04,,inspect.getsource()} for classes in
@ref{1f,,collections.abc} and @ref{39,,decimal} (for pure Python implementation)
modules. @ref{1b52,,inspect.getcomments()} now raises OSError instead of
IndexError if the @code{__firstlineno__} value for a class is out of bound.

@item 
gh-123374@footnote{https://github.com/python/cpython/issues/123374}: Remove check for redefined memo entry in
@ref{1080,,pickletools.dis()}.

@item 
gh-123504@footnote{https://github.com/python/cpython/issues/123504}: Fixed reference leak in the finalization of @ref{f9,,tkinter}.

@item 
gh-123430@footnote{https://github.com/python/cpython/issues/123430}: Pages generated by the @ref{75,,http.server} module allow the
browser to apply its default dark mode.

@item 
gh-123446@footnote{https://github.com/python/cpython/issues/123446}: Fix empty function name in @ref{291,,TypeError} when
@ref{898,,csv.reader()}, @ref{899,,csv.writer()}, or @ref{1b53,,csv.register_dialect()}
are used without the required args.

@item 
gh-123448@footnote{https://github.com/python/cpython/issues/123448}: Fixed memory leak of @ref{76a,,typing.NoDefault} by moving it to
the static types array.

@item 
gh-123409@footnote{https://github.com/python/cpython/issues/123409}: Fix @ref{1b54,,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-123089@footnote{https://github.com/python/cpython/issues/123089}: Make @ref{9d7,,weakref.WeakSet} safe against concurrent mutations
while it is being iterated. Patch by Kumar Aditya.

@item 
gh-123363@footnote{https://github.com/python/cpython/issues/123363}: Show string value of @ref{1b55,,CONTAINS_OP} oparg in @ref{3b,,dis}
output. Patch by Alexandr153.

@item 
gh-123341@footnote{https://github.com/python/cpython/issues/123341}: Add @ref{b21,,__class_getitem__()} to
@code{tkinter.Event} for type subscript support at runtime. Patch by
Adonis Rakateli.

@item 
gh-123340@footnote{https://github.com/python/cpython/issues/123340}: Show string value of @ref{1b56,,IS_OP} oparg in @ref{3b,,dis}
output.

@item 
gh-119518@footnote{https://github.com/python/cpython/issues/119518}: Speed up normalization of @ref{8b6,,pathlib.PurePath} and
@ref{4ee,,Path} objects by not interning string parts.

@item 
gh-123270@footnote{https://github.com/python/cpython/issues/123270}: Applied a more surgical fix for malformed payloads in
@ref{ab6,,zipfile.Path} causing infinite loops (gh-122905@footnote{https://github.com/python/cpython/issues/122905}) without breaking
contents using legitimate characters.

@item 
gh-73991@footnote{https://github.com/python/cpython/issues/73991}: Add @ref{4f0,,pathlib.Path.copy_into()} and
@ref{4f2,,move_into()}, which copy and move files and directories
into `existing' directories.

@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{1df,,str()}.  Patch by Sergey B Kirpichev.

@item 
gh-123240@footnote{https://github.com/python/cpython/issues/123240}: Raise audit events for the @ref{167d,,input()} in the new REPL.

@item 
gh-76960@footnote{https://github.com/python/cpython/issues/76960}: Fix @ref{1247,,urllib.parse.urljoin()} and
@ref{2a5,,urllib.parse.urldefrag()} for URIs containing empty components. For
example, @code{urljoin()} with relative reference «?» now sets empty query
and removes fragment. Preserve empty components (authority, params, query,
fragment) in @code{urljoin()}. Preserve empty components (authority,
params, query) in @code{urldefrag()}.

@item 
gh-116810@footnote{https://github.com/python/cpython/issues/116810}: Resolve a memory leak introduced in CPython 3.10’s @ref{d8,,ssl}
when the @ref{1b57,,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-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{157c,,xml.etree.ElementTree.Element.extend()} and
@ref{343,,Element} assignment no longer hide the
internal exception if an erroneous 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{2a6,,urllib.parse.urlunsplit()} and @ref{2a7,,urllib.parse.urlunparse()}.

@item 
gh-123165@footnote{https://github.com/python/cpython/issues/123165}: Add support for rendering @ref{1b58,,Positions} in
@ref{3b,,dis}.

@item 
gh-122909@footnote{https://github.com/python/cpython/issues/122909}: In urllib.request when URLError is raised opening an ftp URL,
the exception argument is now consistently a string. Earlier versions
passed either a string or an ftplib exception instance as the argument to
URLError.

@item 
gh-123084@footnote{https://github.com/python/cpython/issues/123084}: Deprecate @code{shutil.ExecError}, which hasn’t been raised
by any @ref{cd,,shutil} function since Python 3.4. It’s now an alias for
@ref{30d,,RuntimeError}.

@item 
gh-123085@footnote{https://github.com/python/cpython/issues/123085}: In a bare call to @ref{2d7,,importlib.resources.files()}, ensure the
caller’s frame is properly detected when @code{importlib.resources} is itself
available as a compiled module only (no source).

@item 
gh-123067@footnote{https://github.com/python/cpython/issues/123067}: Fix quadratic complexity in parsing @code{"}-quoted cookie values
with backslashes by @ref{74,,http.cookies}.

@item 
gh-123049@footnote{https://github.com/python/cpython/issues/123049}: Add support for @ref{199c,,UNNAMED_SECTION} in
@ref{1612,,configparser.ConfigParser.add_section()}.

@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-122981@footnote{https://github.com/python/cpython/issues/122981}: Fix @ref{1a04,,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{ab6,,zipfile.Path} objects now sanitize names from the
zipfile.

@item 
gh-122873@footnote{https://github.com/python/cpython/issues/122873}: Enable @ref{85,,json} module to work as a script using the
@ref{4ca,,-m} switch: @code{python -m json}. See the @ref{4cb,,JSON command-line interface} documentation. Patch by Trey Hunner.

@item 
gh-122858@footnote{https://github.com/python/cpython/issues/122858}: Deprecate @code{asyncio.iscoroutinefunction()} in favor of
@ref{302,,inspect.iscoroutinefunction()}.

@item 
gh-116263@footnote{https://github.com/python/cpython/issues/116263}: @ref{1b59,,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{8a,,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-122311@footnote{https://github.com/python/cpython/issues/122311}: Improve errors in the @ref{ab,,pickle} module.
@ref{1b5a,,PicklingError} is now raised more often instead of
@ref{a67,,UnicodeEncodeError}, @ref{277,,ValueError} and @ref{1a9,,AttributeError},
and the original exception is chained to it. Improve and unify error
messages in Python and C implementations.

@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-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve import time of @ref{b3,,pprint} by around seven times.
Patch by Hugo van Kemenade.

@item 
gh-118974@footnote{https://github.com/python/cpython/issues/118974}: Add @code{decorator} parameter to
@ref{1a84,,dataclasses.make_dataclass()} to customize the functional creation of
dataclasses.

@item 
gh-118814@footnote{https://github.com/python/cpython/issues/118814}: Fix the @ref{294,,typing.TypeVar} constructor when name is passed
by keyword.

@item 
gh-122637@footnote{https://github.com/python/cpython/issues/122637}: Adjust @code{cmath.tanh(nanj)} and @code{cmath.tanh(infj)} for recent
C standards.

@item 
gh-122478@footnote{https://github.com/python/cpython/issues/122478}: Remove internal frames from tracebacks shown in
@ref{1b5b,,code.InteractiveInterpreter} with non-default
@ref{be5,,sys.excepthook()}. Save correct tracebacks in
@ref{8d1,,sys.last_traceback} and update @code{__traceback__} attribute of
@ref{8d0,,sys.last_value} and @ref{8ce,,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{5c,,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{69d,,REPL} interprets
@ref{1b5c,,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{d8,,ssl} after the main interpreter
restarts.

@item 
gh-122459@footnote{https://github.com/python/cpython/issues/122459}: Optimize @ref{ab,,pickling} by name objects without the
@code{__module__} attribute.

@item 
gh-87320@footnote{https://github.com/python/cpython/issues/87320}: In @ref{1b5b,,code.InteractiveInterpreter}, handle exceptions
caused by calling a non-default @ref{be5,,sys.excepthook()}. Before, the
exception bubbled up to the caller, ending the @ref{69d,,REPL}.

@item 
gh-122272@footnote{https://github.com/python/cpython/issues/122272}: On some platforms such as Linux, year with century was not
0-padded when formatted by @ref{1051,,strftime()} with C99-specific
specifiers @code{'%C'} or @code{'%F'}. The 0-padding behavior is now guaranteed
when the format specifiers @code{'%C'} and @code{'%F'} are supported by the C
library. Patch by Ben Hsing

@item 
gh-122400@footnote{https://github.com/python/cpython/issues/122400}: Handle @ref{277,,ValueError}s raised by @ref{4f5,,os.stat()} in
@ref{12eb,,filecmp.dircmp} and @ref{1b5d,,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{ab,,pickle}.

@item 
gh-121650@footnote{https://github.com/python/cpython/issues/121650}: @ref{3e,,email} headers with embedded newlines are now quoted on
output. The @ref{43,,generator} will now refuse to serialize (write)
headers that are unsafely folded or delimited; see
@ref{6f7,,verify_generated_headers}. (Contributed by Bas
Bloemsaat and Petr Viktorin in gh-121650@footnote{https://github.com/python/cpython/issues/121650}.)

@item 
gh-122332@footnote{https://github.com/python/cpython/issues/122332}: Fixed segfault with @ref{da0,,asyncio.Task.get_coro()} when using an
eager task factory.

@item 
gh-105733@footnote{https://github.com/python/cpython/issues/105733}: @ref{79d,,ctypes.ARRAY()} is now @ref{1a7,,soft deprecated}: it no
longer emits deprecation warnings and is not scheduled for removal.

@item 
gh-122213@footnote{https://github.com/python/cpython/issues/122213}: Add notes for pickle serialization errors that allow to
identify the source of the error.

@item 
gh-119180@footnote{https://github.com/python/cpython/issues/119180}: As part of 
@geindex Python Enhancement Proposals; PEP 749
PEP 749@footnote{https://peps.python.org/pep-0749/}, add the following attributes for
customizing evaluation of annotation scopes:


@itemize *

@item 
@code{evaluate_value} on @ref{52a,,typing.TypeAliasType}

@item 
@code{evaluate_bound}, @code{evaluate_constraints}, and @code{evaluate_default} on @ref{294,,typing.TypeVar}

@item 
@code{evaluate_default} on @ref{295,,typing.ParamSpec}

@item 
@code{evaluate_default} on @ref{293,,typing.TypeVarTuple}
@end itemize

@item 
gh-119180@footnote{https://github.com/python/cpython/issues/119180}: Fix handling of classes with custom metaclasses in
@code{annotationlib.get_annotations}.

@item 
gh-122170@footnote{https://github.com/python/cpython/issues/122170}: Handle @ref{277,,ValueError}s raised by @ref{4f5,,os.stat()} in
@ref{88,,linecache}. Patch by Bénédikt Tran.

@item 
gh-122163@footnote{https://github.com/python/cpython/issues/122163}: Add notes for JSON serialization errors that allow to identify
the source of the error.

@item 
gh-122129@footnote{https://github.com/python/cpython/issues/122129}: Improve support of method descriptors and wrappers in the help
title.

@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-121723@footnote{https://github.com/python/cpython/issues/121723}: Make @ref{1559,,logging.config.dictConfig()} accept any object
implementing the Queue public API. See the @ref{1b5e,,queue configuration} section for details. 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-120754@footnote{https://github.com/python/cpython/issues/120754}: @code{Pathlib.read_bytes} no longer opens the file in Python’s
buffered I/O mode. This reduces overheads as the code reads a file in
whole leading to a modest speedup.

@item 
gh-113785@footnote{https://github.com/python/cpython/issues/113785}: @ref{2c,,csv} now correctly parses numeric fields (when used with
@ref{1b5f,,csv.QUOTE_NONNUMERIC} or @ref{897,,csv.QUOTE_STRINGS}) which start
with an escape character.

@item 
gh-122088@footnote{https://github.com/python/cpython/issues/122088}: @ref{695,,@@warnings.deprecated} now copies the coroutine status of
functions and methods so that @ref{302,,inspect.iscoroutinefunction()} returns
the correct result.

@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-73991@footnote{https://github.com/python/cpython/issues/73991}: Add @ref{4f1,,pathlib.Path.move()}, which moves a file or directory
tree.

@item 
gh-121268@footnote{https://github.com/python/cpython/issues/121268}: Remove workarounds for non-IEEE 754 systems in @ref{19,,cmath}.

@item 
gh-119698@footnote{https://github.com/python/cpython/issues/119698}: Due to the lack of interest for
@code{symtable.Class.get_methods()}, the method is marked as deprecated
and will be removed in Python 3.16. Patch by Bénédikt Tran.

@item 
gh-121889@footnote{https://github.com/python/cpython/issues/121889}: Adjusts @code{cmath.acosh(complex('0+nanj'))} for recent C
standards.

@item 
gh-121804@footnote{https://github.com/python/cpython/issues/121804}: Correctly show error locations, when @ref{17e,,SyntaxError} raised
in new repl. Patch by Sergey B Kirpichev.

@item 
gh-121797@footnote{https://github.com/python/cpython/issues/121797}: Add alternative @ref{1c3,,Fraction} constructor
@ref{4a3,,Fraction.from_number()}.

@item 
gh-121798@footnote{https://github.com/python/cpython/issues/121798}: Add alternative @ref{1c2,,Decimal} constructor
@ref{490,,Decimal.from_number()}.

@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-57141@footnote{https://github.com/python/cpython/issues/57141}: The `shallow' argument to @ref{12eb,,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-121249@footnote{https://github.com/python/cpython/issues/121249}: Support the float complex and double complex C types in the @ref{de,,struct} module if the compiler has C11
complex arithmetic.  Patch by Sergey B Kirpichev.

@item 
gh-121486@footnote{https://github.com/python/cpython/issues/121486}: @ref{91,,math} functions @ref{dc7,,isqrt()}, @ref{1862,,log()},
@ref{1487,,log2()} and @ref{19dc,,log10()} now support integers larger
than @code{2**2**32} on 32-bit platforms.

@item 
gh-121474@footnote{https://github.com/python/cpython/issues/121474}: Fix missing sanity check for @code{parties} arg in
@ref{158c,,threading.Barrier} constructor. Patch by Clinton Christian
(pygeek).

@item 
gh-121450@footnote{https://github.com/python/cpython/issues/121450}: Hard-coded breakpoints (@ref{4f9,,breakpoint()} and
@ref{4fa,,pdb.set_trace()}) now reuse the most recent @code{Pdb} instance that
calls @code{Pdb.set_trace()}, instead of creating a new one each time. As a
result, all the instance specific data like @code{display} and @code{commands}
are preserved across Hard-coded breakpoints.

@item 
gh-119169@footnote{https://github.com/python/cpython/issues/119169}: Slightly speed up @ref{8b9,,os.walk()} by simplifying exception
handling.

@item 
gh-121423@footnote{https://github.com/python/cpython/issues/121423}: Improve import time of @ref{d4,,socket} by lazy importing modules
and writing @code{socket.errorTab} as a constant.

@item 
gh-59110@footnote{https://github.com/python/cpython/issues/59110}: @ref{13b,,zipimport} supports now namespace packages when no
directory entry exists.

@item 
gh-119004@footnote{https://github.com/python/cpython/issues/119004}: Fix a crash in @ref{1b60,,OrderedDict.__eq__} when operands are mutated during the
check. Patch by Bénédikt Tran.

@item 
gh-121313@footnote{https://github.com/python/cpython/issues/121313}: Limit the reading size in the
@ref{148c,,multiprocessing.connection.Connection} class to 64 KiB to prevent
memory overallocation and unnecessary memory management system calls.

@item 
gh-121332@footnote{https://github.com/python/cpython/issues/121332}: Fix constructor of @ref{9,,ast} nodes with custom
@code{_attributes}. Previously, passing custom attributes would raise a
@ref{2c9,,DeprecationWarning}. Passing arguments to the constructor that
are not in @code{_fields} or @code{_attributes} remains deprecated. Patch by
Jelle Zijlstra.

@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{69d,,REPL} that caused the history file to be wiped at REPL exit.

@item 
gh-121210@footnote{https://github.com/python/cpython/issues/121210}: Handle AST nodes with missing runtime fields or attributes in
@ref{459,,ast.compare()}. Patch by Bénédikt Tran.

@item 
gh-121163@footnote{https://github.com/python/cpython/issues/121163}: Add support for @code{all} as an valid @code{action} for
@ref{aae,,warnings.simplefilter()} and @ref{184b,,warnings.filterwarnings()}.

@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{7,,argparse}.

@item 
gh-121141@footnote{https://github.com/python/cpython/issues/121141}: Add support for @ref{45a,,copy.replace()} to AST nodes. Patch by
Bénédikt Tran.

@item 
gh-87744@footnote{https://github.com/python/cpython/issues/87744}: Fix waitpid race while calling
@ref{1b61,,send_signal()} in asyncio. Patch by Kumar
Aditya.

@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{4a6,,functools.partial} will be a method
descriptor.

@item 
gh-121027@footnote{https://github.com/python/cpython/issues/121027}: Make the @ref{4a6,,functools.partial} object a method descriptor.

@item 
gh-117784@footnote{https://github.com/python/cpython/issues/117784}: CPython now detects whether its linked TLS library supports
TLSv1.3 post-handshake authentication and disables that feature if support
is lacking.

@item 
gh-121025@footnote{https://github.com/python/cpython/issues/121025}: Improve the @ref{1bc,,__repr__()} of
@ref{4a7,,functools.partialmethod}. Patch by Bénédikt Tran.

@item 
gh-121018@footnote{https://github.com/python/cpython/issues/121018}: Fixed issues where @code{argparse.ArgumentParser.parse_args()}
did not honor @code{exit_on_error=False}. Based on 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{f9,,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-61103@footnote{https://github.com/python/cpython/issues/61103}: Support float complex, double complex and
long double complex C types in @ref{2d,,ctypes} as
@ref{2ce,,c_float_complex}, @ref{2cf,,c_double_complex} and
@ref{2d0,,c_longdouble_complex} if the compiler has C11 complex
arithmetic. Patch by Sergey B Kirpichev.

@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{f9,,tkinter} object’s string representation no
longer converts the underlying Tcl object to a string on Windows.

@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-120811@footnote{https://github.com/python/cpython/issues/120811}: Fix possible memory leak in @ref{198c,,contextvars.Context.run()}.

@item 
gh-120782@footnote{https://github.com/python/cpython/issues/120782}: Fix wrong references of the @ref{33,,datetime} types after
reloading the module.

@item 
gh-120713@footnote{https://github.com/python/cpython/issues/120713}: @ref{1051,,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-120769@footnote{https://github.com/python/cpython/issues/120769}: Make empty line in @ref{aa,,pdb} repeats the last command even
when the command is from @code{cmdqueue}.

@item 
gh-120780@footnote{https://github.com/python/cpython/issues/120780}: Show string value of LOAD_SPECIAL oparg in @ref{3b,,dis} output.

@item 
gh-41431@footnote{https://github.com/python/cpython/issues/41431}: Add @ref{1a06,,datetime.time.strptime()} and
@ref{48c,,datetime.date.strptime()}. Contributed by Wannes Boeykens.

@item 
gh-120743@footnote{https://github.com/python/cpython/issues/120743}: @ref{1a7,,Soft deprecate} @ref{585,,os.popen()} and
@ref{586,,os.spawn*} functions. They should no longer be used to
write new code. The @ref{df,,subprocess} module is recommended instead. Patch
by Victor Stinner.

@item 
gh-120732@footnote{https://github.com/python/cpython/issues/120732}: Fix @code{name} passing to @ref{e0e,,unittest.mock.Mock} object when
using @ref{1b4e,,unittest.mock.create_autospec()}.

@item 
gh-111259@footnote{https://github.com/python/cpython/issues/111259}: @ref{c1,,re} now handles patterns like @code{"[\s\S]"} or @code{"\s|\S"}
which match any character as effectively as a dot with the @code{DOTALL}
modifier (@code{"(?s:.)"}).

@item 
gh-120683@footnote{https://github.com/python/cpython/issues/120683}: Fix an error in @ref{138f,,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-118710@footnote{https://github.com/python/cpython/issues/118710}: @ref{710,,ipaddress.IPv4Address} and
@ref{711,,ipaddress.IPv6Address} attributes @code{version} and
@code{max_prefixlen} are now available on the class.

@item 
gh-120633@footnote{https://github.com/python/cpython/issues/120633}: Move scrollbar and remove tear-off menus in turtledemo.

@item 
gh-120606@footnote{https://github.com/python/cpython/issues/120606}: Allow users to use EOF to exit @code{commands} definition in
@ref{aa,,pdb}

@item 
gh-120284@footnote{https://github.com/python/cpython/issues/120284}: Allow @ref{1b62,,asyncio.Runner.run()} to accept @ref{6cf,,awaitable}
objects instead of simply @ref{8a2,,coroutine}s.

@item 
gh-120541@footnote{https://github.com/python/cpython/issues/120541}: Improve the prompt in the «less» pager when @ref{ca9,,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-120388@footnote{https://github.com/python/cpython/issues/120388}: Improve a warning message when a test method in @ref{10f,,unittest}
returns something other than @code{None}. Now we show the returned object
type and optional asyncio-related tip.

@item 
gh-120381@footnote{https://github.com/python/cpython/issues/120381}: Correct @ref{1b63,,inspect.ismethoddescriptor()} to check also for
the lack of @ref{1b64,,__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{a2d,,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{104,,tokenize} module.

@item 
gh-119180@footnote{https://github.com/python/cpython/issues/119180}: As part of implementing 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/} and 
@geindex Python Enhancement Proposals; PEP 749
PEP 749@footnote{https://peps.python.org/pep-0749/}, add a new
module @code{annotationlib}. Add support for unresolved forward references in
annotations to @ref{32,,dataclasses}, @ref{290,,typing.TypedDict}, and
@ref{2e4,,typing.NamedTuple}.

@item 
gh-119600@footnote{https://github.com/python/cpython/issues/119600}: Fix @ref{1243,,unittest.mock.patch()} to not read attributes of the
target when @code{new_callable} is set. Patch by Robert Collins.

@item 
gh-120289@footnote{https://github.com/python/cpython/issues/120289}: Fixed the use-after-free issue in @code{cProfile} by
disallowing @code{disable()} and @code{clear()} in external timers.

@item 
gh-82017@footnote{https://github.com/python/cpython/issues/82017}: Added support for converting any objects that have the
@code{as_integer_ratio()} method to a @ref{1c3,,Fraction}.

@item 
gh-114053@footnote{https://github.com/python/cpython/issues/114053}: Fix edge-case bug where @ref{a9e,,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{665,,NameError} when calling
@ref{bec,,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{f92,,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{7a1,,re.sub()} when the replacement string
contains backreferences.

@item 
gh-120254@footnote{https://github.com/python/cpython/issues/120254}: Added @code{commands} argument to @ref{4fa,,pdb.set_trace()} which
allows users to send debugger commands from the source file.

@item 
gh-120211@footnote{https://github.com/python/cpython/issues/120211}: Fix @ref{102,,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{2d2,,datetime.datetime.strptime()}
when called again on the restarted interpreter.

@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-120157@footnote{https://github.com/python/cpython/issues/120157}: Remove unused constant
@code{concurrent.futures._base._FUTURE_STATES} in @ref{24,,concurrent.futures}.
Patch by Clinton Christian (pygeek).

@item 
gh-120161@footnote{https://github.com/python/cpython/issues/120161}: @ref{33,,datetime} no longer crashes in certain complex reference
cycle situations.

@item 
gh-119698@footnote{https://github.com/python/cpython/issues/119698}: Fix @code{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{1b65,,concurrent.futures.InvalidStateError} to module’s
@code{__all__}.

@item 
gh-119933@footnote{https://github.com/python/cpython/issues/119933}: Add the @ref{1b66,,symtable.SymbolTableType} enumeration to
represent the possible outputs of the
@ref{1b67,,symtable.SymbolTable.get_type} method. Patch by Bénédikt Tran.

@item 
gh-120029@footnote{https://github.com/python/cpython/issues/120029}: Expose @ref{511,,symtable.Symbol} methods
@ref{514,,is_free_class()},
@ref{513,,is_comp_iter()} and
@ref{512,,is_comp_cell()}. Patch by Bénédikt Tran.

@item 
gh-120108@footnote{https://github.com/python/cpython/issues/120108}: Fix calling @ref{f2b,,copy.deepcopy()} on @ref{9,,ast} trees that have
been modified to have references to parent nodes. Patch by Jelle Zijlstra.

@item 
gh-120056@footnote{https://github.com/python/cpython/issues/120056}: Add @code{socket.IP_RECVERR} and @code{socket.IP_RECVTTL}
constants (both available since Linux 2.2). And
@code{socket.IP_RECVORIGDSTADDR} constant (available since Linux
2.6.29).

@item 
gh-112672@footnote{https://github.com/python/cpython/issues/112672}: Support building @ref{f9,,tkinter} with Tcl 9.0.

@item 
gh-120057@footnote{https://github.com/python/cpython/issues/120057}: Added the @ref{4e5,,os.environ.refresh()} method to
update @code{os.environ} with changes to the environment made by
@ref{4e7,,os.putenv()}, by @ref{4e8,,os.unsetenv()}, or made outside Python in the
same process. Patch by Victor Stinner.

@item 
gh-120029@footnote{https://github.com/python/cpython/issues/120029}: Expose @ref{1b68,,symtable.Symbol.is_type_parameter()} in the
@ref{e1,,symtable} module. Patch by Bénédikt Tran.

@item 
gh-119819@footnote{https://github.com/python/cpython/issues/119819}: Fix regression to allow logging configuration with
multiprocessing queue types.

@item 
gh-65454@footnote{https://github.com/python/cpython/issues/65454}: @ref{1b69,,unittest.mock.Mock.attach_mock()} no longer triggers a call
to a @code{PropertyMock} being attached.

@item 
gh-117142@footnote{https://github.com/python/cpython/issues/117142}: The @ref{2d,,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-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-117398@footnote{https://github.com/python/cpython/issues/117398}: The @code{_datetime} module (C implementation for @ref{33,,datetime})
now supports being imported in multiple interpreters.

@item 
gh-119824@footnote{https://github.com/python/cpython/issues/119824}: Print stack entry in @ref{aa,,pdb} when and only when user input
is needed.

@item 
gh-119838@footnote{https://github.com/python/cpython/issues/119838}: In mixed arithmetic operations with
@ref{1c3,,Fraction} and complex, the fraction is now converted to
@ref{327,,float} instead of @ref{328,,complex}.

@item 
gh-119770@footnote{https://github.com/python/cpython/issues/119770}: Make @ref{ea,,termios} @code{ioctl()} constants positive. Patch by
Victor Stinner.

@item 
gh-89727@footnote{https://github.com/python/cpython/issues/89727}: Fix issue with @ref{335,,shutil.rmtree()} where a
@ref{1121,,RecursionError} is raised on deep directory trees.

@item 
gh-119577@footnote{https://github.com/python/cpython/issues/119577}: The @ref{2c9,,DeprecationWarning} emitted when testing the truth
value of an @ref{343,,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-89727@footnote{https://github.com/python/cpython/issues/89727}: Partially fix issue with @ref{335,,shutil.rmtree()} where a
@ref{1121,,RecursionError} is raised on deep directory trees. A recursion error
is no longer raised when @code{rmtree.avoids_symlink_attacks} is false.

@item 
gh-93963@footnote{https://github.com/python/cpython/issues/93963}: Remove deprecated names from @code{importlib.abc} as found in
@code{importlib.resources.abc}.

@item 
gh-119118@footnote{https://github.com/python/cpython/issues/119118}: Fix performance regression in the @ref{104,,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{f18,,os.fwalk()} where a @ref{1121,,RecursionError}
was raised on deep directory trees by adjusting the implementation to be
iterative instead of recursive.

@item 
gh-119594@footnote{https://github.com/python/cpython/issues/119594}: If one calls pow(fractions.Fraction, x, module) with modulo not
None, the error message now says that the types are incompatible rather
than saying pow only takes 2 arguments. Patch by Wim Jeantine-Glenn and
Mark Dickinson.

@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-119562@footnote{https://github.com/python/cpython/issues/119562}: Remove @code{ast.Num}, @code{ast.Str},
@code{ast.Bytes}, @code{ast.NameConstant} and
@code{ast.Ellipsis}. They had all emitted deprecation warnings since
Python 3.12. Patch by Alex Waygood.

@item 
gh-119555@footnote{https://github.com/python/cpython/issues/119555}: Catch @ref{17e,,SyntaxError} from @ref{1c8,,compile()} in the
runsource() method of the InteractiveColoredConsole.  Patch by Sergey B
Kirpichev.

@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-117865@footnote{https://github.com/python/cpython/issues/117865}: Improve the import time of the @ref{9,,ast} module by deferring
the import of @ref{c1,,re}. Patch by Jelle Zijlstra.

@item 
gh-119127@footnote{https://github.com/python/cpython/issues/119127}: Positional arguments of @ref{4a6,,functools.partial()} objects now
support placeholders via @ref{4a5,,functools.Placeholder}.

@item 
gh-113892@footnote{https://github.com/python/cpython/issues/113892}: Now, the method @code{sock_connect} of
@ref{9fe,,asyncio.ProactorEventLoop} raises a @ref{277,,ValueError} if given
socket is not in non-blocking mode, as well as in other loop
implementations.

@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.

@item 
gh-69214@footnote{https://github.com/python/cpython/issues/69214}: Fix @code{fcntl.ioctl()} `request' parameter: use an @code{unsigned
long} instead of an @code{unsigned int} for the `request' parameter of
@ref{181d,,fcntl.ioctl()} to support requests larger than @code{UINT_MAX}. Patch by
Victor Stinner.

@item 
gh-119105@footnote{https://github.com/python/cpython/issues/119105}: @code{difflib}’s @code{DIffer.compare()} (and so also @code{ndiff}) can
no longer be provoked into cubic-time behavior, or into unbounded
recursion, and should generally be faster in ordinary cases too. Results
may change in some cases, although that should be rare. Correctness of
diffs is not affected. Some similar lines far apart may be reported as
deleting one and adding the other, where before they were displayed on
adjacent output lines with markup showing the intraline differences.

@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-119461@footnote{https://github.com/python/cpython/issues/119461}: Add @code{socket.VMADDR_CID_LOCAL} constant. Patch by Victor
Stinner.

@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{b,,asyncio} REPL now has the same capabilities as PyREPL.

@item 
gh-118830@footnote{https://github.com/python/cpython/issues/118830}: Bump @ref{ab,,pickle} default protocol to @code{5}.

@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-115225@footnote{https://github.com/python/cpython/issues/115225}: Raise error on certain technically valid but pathological ISO
8601 strings passed to @ref{a09,,datetime.time.fromisoformat()} that were
previously parsed incorrectly.

@item 
gh-111201@footnote{https://github.com/python/cpython/issues/111201}: Remove dependency to @ref{c2,,readline} from the new Python REPL.

@item 
gh-119189@footnote{https://github.com/python/cpython/issues/119189}: When using the @code{**} operator or @ref{441,,pow()} with
@ref{1c3,,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-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-119105@footnote{https://github.com/python/cpython/issues/119105}: @code{difflib.Differ} is much faster for some cases of diffs where
many pairs of lines are equally similar.

@item 
gh-119113@footnote{https://github.com/python/cpython/issues/119113}: Fix issue where @ref{1b6a,,pathlib.PurePath.with_suffix()} didn’t
raise @ref{291,,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{3e,,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-73991@footnote{https://github.com/python/cpython/issues/73991}: Add @ref{4ef,,pathlib.Path.copy()}, which copies a file or directory
to another.

@item 
gh-58933@footnote{https://github.com/python/cpython/issues/58933}: Make @ref{aa,,pdb} return to caller frame correctly when
@code{f_trace} of the caller frame is not set

@item 
gh-82805@footnote{https://github.com/python/cpython/issues/82805}: Support single-dot file extensions in
@ref{1b6b,,pathlib.PurePath.suffix} and related attributes and methods. For
example, the @ref{1b6c,,suffixes} of
@code{PurePath('foo.bar.')} are now @code{['.bar', '.']} rather than @code{[]}.
This brings file extension splitting in line with
@ref{1b6d,,os.path.splitext()}.

@item 
gh-118924@footnote{https://github.com/python/cpython/issues/118924}: Remove @code{version} and @code{version_info} from
@ref{d7,,sqlite3}. Patch by Hugo van Kemenade.

@item 
gh-118928@footnote{https://github.com/python/cpython/issues/118928}: Disallow using a sequence of parameters with named placeholders
in @ref{d7,,sqlite3} queries. Patch by Erlend E. Aasland.

@item 
gh-118895@footnote{https://github.com/python/cpython/issues/118895}: Setting attributes on @ref{76a,,typing.NoDefault} now raises
@ref{1a9,,AttributeError} instead of @ref{291,,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-118827@footnote{https://github.com/python/cpython/issues/118827}: Remove deprecated @code{Quoter} class from
@ref{113,,urllib.parse}. It had previously raised a @ref{2c9,,DeprecationWarning}
since Python 3.11. Patch by Nikita Sobolev.

@item 
gh-118824@footnote{https://github.com/python/cpython/issues/118824}: Remove deprecated @code{pty.master_open()} and
@code{pty.slave_open()}. Use @ref{579,,pty.openpty()} instead. Patch by Nikita
Sobolev.

@item 
gh-118851@footnote{https://github.com/python/cpython/issues/118851}: @code{ctx} arguments to the constructors of @ref{9,,ast} node
classes now default to @ref{6c9,,ast.Load()}. Patch by Jelle
Zijlstra.

@item 
gh-101588@footnote{https://github.com/python/cpython/issues/101588}: Remove copy, deepcopy, and pickle from itertools. These had
previously raised a DeprecationWarning since Python 3.12.

@item 
gh-118805@footnote{https://github.com/python/cpython/issues/118805}: Remove `type', `choices', and `metavar' parameters of
@code{argparse.BooleanOptionalAction}. They were deprecated since
Python 3.12.

@item 
gh-118803@footnote{https://github.com/python/cpython/issues/118803}: @code{typing.ByteString} and
@code{collections.abc.ByteString} are removed. They had previously
raised a @ref{2c9,,DeprecationWarning} since Python 3.12.

@item 
gh-118798@footnote{https://github.com/python/cpython/issues/118798}: The `isdst' parameter has been removed from
@ref{56f,,email.utils.localtime()}. Patch by Hugo van Kemenade.

@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-74033@footnote{https://github.com/python/cpython/issues/74033}: Drop support for passing keyword arguments to
@ref{4ee,,pathlib.Path}.

@item 
gh-101357@footnote{https://github.com/python/cpython/issues/101357}: Suppress all @ref{53c,,OSError} exceptions from
@ref{dda,,pathlib.Path.exists()} and @code{is_*()} methods, rather than a
selection of more common errors. The new behaviour is consistent with
@ref{dd2,,os.path.exists()}, @ref{dd4,,os.path.isdir()}, etc. Use
@ref{bfc,,pathlib.Path.stat()} to retrieve the file status without suppressing
exceptions.

@item 
gh-78707@footnote{https://github.com/python/cpython/issues/78707}: Drop support for passing additional positional arguments to
@ref{575,,pathlib.PurePath.relative_to()} and
@ref{576,,is_relative_to()}.

@item 
gh-118507@footnote{https://github.com/python/cpython/issues/118507}: Fix @ref{dd5,,os.path.isfile()} on Windows for pipes. Speedup
@ref{8b3,,os.path.isjunction()} and @ref{dd3,,os.path.lexists()} on Windows with a
native implementation.

@item 
gh-118772@footnote{https://github.com/python/cpython/issues/118772}: Allow @ref{294,,typing.TypeVar} instances without a default to
follow instances without a default in some cases. Patch by Jelle Zijlstra.

@item 
gh-118714@footnote{https://github.com/python/cpython/issues/118714}: Allow @code{restart} in post-mortem debugging of @ref{aa,,pdb}.
Removed restart message when the user quits pdb from post-mortem mode.

@item 
gh-118673@footnote{https://github.com/python/cpython/issues/118673}: Removed executable bits and shebang from stdlib modules.

@item 
gh-110863@footnote{https://github.com/python/cpython/issues/110863}: @ref{241,,os.path.realpath()} now suppresses any @ref{53c,,OSError} from
@ref{ced,,os.readlink()} when `strict' mode is disabled (the default).

@item 
gh-118263@footnote{https://github.com/python/cpython/issues/118263}: Speed up @ref{8b4,,os.path.splitroot()} & @ref{16be,,os.path.normpath()}
with a direct C call.

@item 
gh-110190@footnote{https://github.com/python/cpython/issues/110190}: Fix ctypes structs with array on SPARC by setting
@code{MAX_STRUCT_SIZE} to 32 in stgdict. Patch by Jakub Kulik

@item 
gh-118033@footnote{https://github.com/python/cpython/issues/118033}: Fix @ref{6e6,,dataclasses.dataclass()} not creating a
@code{__weakref__} slot when subclassing @ref{19f2,,typing.Generic}.

@item 
gh-117766@footnote{https://github.com/python/cpython/issues/117766}: Always use @ref{1df,,str()} to print @code{choices} in @ref{7,,argparse}.

@item 
gh-106531@footnote{https://github.com/python/cpython/issues/106531}: In @ref{7e,,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-115937@footnote{https://github.com/python/cpython/issues/115937}: Removed extra preprocessing for the @code{__signature__}
attribute: the code just check if it’s a @ref{6e8,,inspect.Signature}
instance.  Patch by Sergey B Kirpichev.

@item 
gh-115808@footnote{https://github.com/python/cpython/issues/115808}: Add @ref{4e1,,operator.is_none()} and @ref{4e2,,operator.is_not_none()}
functions.

@item 
gh-114264@footnote{https://github.com/python/cpython/issues/114264}: Improve performance of @ref{f2b,,copy.deepcopy()} by adding a fast
path for atomic types.

@item 
gh-113878@footnote{https://github.com/python/cpython/issues/113878}: Add `doc' parameter to @ref{1945,,dataclasses.field()}, so it can be
stored and shown as a documentation / metadata. If
@code{@@dataclass(slots=True)} is used, then the supplied string is available
in the @ref{188d,,__slots__} dict. Otherwise, the supplied string is
only available in the corresponding @ref{1b6e,,dataclasses.Field} object.

In order to support this feature we are changing the @code{__slots__} format
in dataclasses from @ref{1ce,,tuple} to @ref{188,,dict} when documentation /
metadata is present.

@item 
gh-113978@footnote{https://github.com/python/cpython/issues/113978}: Ignore warnings on text completion inside REPL.

@item 
gh-113008@footnote{https://github.com/python/cpython/issues/113008}: Correct argparse usage output for required, mutually exclusive
groups containing a positional argument

@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{1b6f,,ssl.SSLSocket.get_verified_chain()} and
@ref{1b70,,ssl.SSLSocket.get_unverified_chain()} methods.

Contributed by Mateusz Nowak.

@item 
gh-105623@footnote{https://github.com/python/cpython/issues/105623}: Fix performance degradation in
@ref{1b59,,logging.handlers.RotatingFileHandler}. Patch by Craig Robson.

@item 
gh-102450@footnote{https://github.com/python/cpython/issues/102450}: Add missing ISO-8601 24:00 alternative to midnight of next day
to @ref{a0a,,datetime.datetime.fromisoformat()} and
@ref{a09,,datetime.time.fromisoformat()}. Patch by Izan «TizzySaurus» Robinson
(@email{tizzysaurus@@gmail.com})

@item 
gh-103956@footnote{https://github.com/python/cpython/issues/103956}: Fix lack of newline characters in @ref{106,,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{5ef,,bool}, @ref{1df,,str}, @ref{1c6,,bytearray}, or @ref{326,,int}.

@item 
gh-87106@footnote{https://github.com/python/cpython/issues/87106}: Fixed handling in @ref{1ab6,,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 
gh-103134@footnote{https://github.com/python/cpython/issues/103134}: Add additional methods to @ref{4d8,,proxy objects} in the @code{multiprocessing} module:


@itemize *

@item 
@code{clear()} and @code{copy()} for proxies of @ref{4d9,,list}

@item 
@ref{4da,,fromkeys()}, @code{reversed(d)}, @code{d | @{@}}, @code{@{@} | d},
@code{d |= @{'b': 2@}} for proxies of @ref{188,,dict}
@end itemize

@item 
bpo-45767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45767}: Fix integer conversion in @ref{1b71,,os.major()}, @ref{1b72,,os.minor()},
and @ref{1b73,,os.makedev()}. Support device numbers larger than @code{2**63-1}.
Support non-existent device number (@code{NODEV}).

@item 
bpo-44864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44864}: Do not translate user-provided strings in
@ref{1dc,,argparse.ArgumentParser}.

@item 
bpo-41843@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41843}: Solaris now uses @ref{ed3,,os.sendfile()} fast-copy syscall for more
efficient @ref{cd,,shutil} file copy related functions.

@item 
bpo-15987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15987}: Implemented @ref{459,,ast.compare()} for comparing two ASTs. Patch
by Batuhan Taskaya with some help from Jeremy Hylton.

@item 
gh-67693@footnote{https://github.com/python/cpython/issues/67693}: Fix @ref{2a7,,urllib.parse.urlunparse()} and
@ref{2a6,,urllib.parse.urlunsplit()} for URIs with path starting with multiple
slashes and no authority. Based on patch by Ashwin Ramaswami.

@item 
bpo-14074@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14074}: Fix @ref{7,,argparse} metavar processing to allow positional
arguments to have a tuple metavar.
@end itemize

@node IDLE<8>,Documentation<14>,Library<51>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id204}@anchor{1b74}
@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.

@item 
gh-112938@footnote{https://github.com/python/cpython/issues/112938}: Fix uninteruptable hang when Shell gets rapid continuous
output.

@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.

@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.

@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.

@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<14>,Core and Builtins<48>,IDLE<8>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id205}@anchor{1b75}
@subsubsection Documentation



@itemize -

@item 
gh-124872@footnote{https://github.com/python/cpython/issues/124872}: Added definitions for @ref{1b76,,context}, @ref{1b77,,current context},
and @ref{1b78,,context management protocol}, updated related definitions to be
consistent, and expanded the documentation for
@ref{421,,contextvars.Context}.

@item 
gh-125018@footnote{https://github.com/python/cpython/issues/125018}: The @ref{7d,,importlib.metadata} documentation now includes
semantic cross-reference targets for the significant documented APIs. This
means intersphinx references like @ref{1b79,,importlib.metadata.version()} will
now work as expected.

@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-124457@footnote{https://github.com/python/cpython/issues/124457}: Remove coverity scan from the CPython repo. It has not been
used since 2020 and is currently unmaintained.

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: Add an Android platform guide, and flag modules not available
on Android.

@item 
gh-123976@footnote{https://github.com/python/cpython/issues/123976}: Refresh docs around custom providers.

@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-117765@footnote{https://github.com/python/cpython/issues/117765}: Improved documentation for @ref{1b7a,,unittest.mock.patch.dict()}

@item 
gh-121749@footnote{https://github.com/python/cpython/issues/121749}: Fix documentation for @ref{800,,PyModule_AddObjectRef()}.

@item 
gh-120012@footnote{https://github.com/python/cpython/issues/120012}: Clarify the behaviours of @ref{1b7b,,multiprocessing.Queue.empty()}
and @ref{1b7c,,multiprocessing.SimpleQueue.empty()} on closed queues. Patch by
Bénédikt Tran.

@item 
gh-119574@footnote{https://github.com/python/cpython/issues/119574}: Added some missing environment variables to the output of
@ref{9e9,,--help-env}.

@item 
bpo-34008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34008}: The @ref{fe2,,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<48>,Library<52>,Documentation<14>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id206}@anchor{1b7d}
@subsubsection Core and Builtins



@itemize -

@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{1b7e,,__reduce_ex__()} for the first time in the free threading
build.

@item 
gh-125174@footnote{https://github.com/python/cpython/issues/125174}: Make the handling of reference counts of immortal objects more
robust. Immortal objects with reference counts that deviate from their
original reference count by up to a billion (half a billion on 32 bit
builds) are still counted as immortal.

@item 
gh-125039@footnote{https://github.com/python/cpython/issues/125039}: Make @code{this_instr} and @code{prev_instr} const in cases
generator.
@end itemize

@node Library<52>,Core and Builtins<49>,Core and Builtins<48>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id207}@anchor{1b7f}
@subsubsection Library



@itemize -

@item 
gh-125008@footnote{https://github.com/python/cpython/issues/125008}: Fix @ref{1ad4,,tokenize.untokenize()} producing invalid syntax for
double braces preceded by certain escape characters.
@end itemize

@node Core and Builtins<49>,Library<53>,Library<52>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id208}@anchor{1b80}
@subsubsection Core and Builtins



@itemize -

@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.

@item 
gh-123378@footnote{https://github.com/python/cpython/issues/123378}: Fix a crash in the @ref{a0f,,__str__()} method of
@ref{675,,UnicodeError} objects when the @ref{1ae1,,UnicodeError.start} and
@ref{1ae2,,UnicodeError.end} values are invalid or out-of-range. Patch by
Bénédikt Tran.

@item 
gh-118093@footnote{https://github.com/python/cpython/issues/118093}: Improve the experimental JIT compiler’s ability to stay «on
trace» when encountering highly-biased branches.

@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 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-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-119180@footnote{https://github.com/python/cpython/issues/119180}: The @code{__main__} module no longer always contains an
@code{__annotations__} dictionary in its global namespace.

@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{688,,__static_attributes__}. Patch by kp2pml30.

@item 
gh-124285@footnote{https://github.com/python/cpython/issues/124285}: Fix bug where @code{bool(a)} can be invoked more than once during
the evaluation of a compound boolean expression.

@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}: Deprecate the setting and using @code{__package__} and
@code{__cached__}.

@item 
gh-119726@footnote{https://github.com/python/cpython/issues/119726}: The JIT now generates more efficient code for calls to C
functions resulting in up to 0.8% memory savings and 1.5% speed
improvement on AArch64. Patch by Diego Russo.

@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 with
non-UTF-8 encoding for syntax errors raised in the compiler.

@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-124022@footnote{https://github.com/python/cpython/issues/124022}: Fix bug where docstring is removed from classes in interactive
mode.

@item 
gh-123958@footnote{https://github.com/python/cpython/issues/123958}: docstrings are now removed from the optimized AST in
optimization level 2.

@item 
gh-123923@footnote{https://github.com/python/cpython/issues/123923}: The @code{f_executable} field in the internal
@ref{1b81,,_PyInterpreterFrame} struct now uses a tagged pointer.
Profilers and debuggers that uses this field should clear the least
significant bit to recover the @ref{19b,,PyObject}* pointer.

@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{1d2,,memoryview} object. Now a
@code{memoryview} object can only be cleared if there are no buffers
that refer it.

@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
@end itemize

@node Library<53>,Core and Builtins<50>,Core and Builtins<49>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id209}@anchor{1b82}
@subsubsection Library



@itemize -

@item 
gh-123614@footnote{https://github.com/python/cpython/issues/123614}: Add @ref{1b83,,turtle.save()} to easily save Turtle drawings as
PostScript files. Patch by Marie Roald and Yngve Mardal Moe.
@end itemize

@node Core and Builtins<50>,Library<54>,Library<53>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id210}@anchor{1b84}
@subsubsection Core and Builtins



@itemize -

@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.

@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-123562@footnote{https://github.com/python/cpython/issues/123562}: Improve @ref{17e,,SyntaxError} message for using @code{case ... as
...} with not a name.

@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-123446@footnote{https://github.com/python/cpython/issues/123446}: Fix empty function name in @ref{291,,TypeError} when builtin magic
methods are used without the required args.

@item 
gh-123440@footnote{https://github.com/python/cpython/issues/123440}: Improve @ref{17e,,SyntaxError} message for using @code{except as} with
not a name.

@item 
gh-116017@footnote{https://github.com/python/cpython/issues/116017}: Improved JIT memory consumption by periodically freeing memory
used by infrequently-executed code. This change is especially likely to
improve the memory footprint of long-running programs.

@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-123271@footnote{https://github.com/python/cpython/issues/123271}: Make concurrent iterations over the same @ref{43f,,zip()} iterator
safe under free-threading.

@item 
gh-123275@footnote{https://github.com/python/cpython/issues/123275}: Support @ref{178,,-X gil=1} and 
@geindex PYTHON_GIL
@geindex μεταβλητή περιβάλλοντος; PYTHON_GIL
@ref{6a6,,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 feature 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{17e,,SyntaxError} is
raised in the basic REPL. Patch by Sergey B Kirpichev.

@item 
gh-115776@footnote{https://github.com/python/cpython/issues/115776}: Enables inline values (Python’s equivalent of hidden classes)
on any class who’s instances are of a fixed size.

@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{1b85,,JUMP_FORWARD} with no source location.

@item 
gh-118093@footnote{https://github.com/python/cpython/issues/118093}: Break up @code{CALL_ALLOC_AND_ENTER_INIT} into micro-ops and relax
requirement for exact args, in order to increase the amount of code
supported by tier 2.

@item 
gh-123123@footnote{https://github.com/python/cpython/issues/123123}: Fix displaying @ref{17e,,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{673,,Py_Initialize()} from a non-main thread.

@item 
gh-118093@footnote{https://github.com/python/cpython/issues/118093}: Add three specializations for @ref{5a1,,CALL_KW}:


@itemize *

@item 
@code{CALL_KW_PY} for calls to Python functions

@item 
@code{CALL_KW_BOUND_METHOD} for calls to bound methods

@item 
@code{CALL_KW_NON_PY} for all other calls
@end itemize

@item 
gh-122821@footnote{https://github.com/python/cpython/issues/122821}: Make sure that branches in @ref{1b86,,while} statements have
consistent offsets for @ref{e3,,sys.monitoring}. @code{while} statements
are now compiled with a simple jump at the end of the body, instead of
duplicating the test.

@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-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-118093@footnote{https://github.com/python/cpython/issues/118093}: Improve the experimental JIT’s handling of polymorphic code.

@item 
gh-122697@footnote{https://github.com/python/cpython/issues/122697}: Fixed memory leaks at interpreter shutdown in the free-threaded
build, and also reporting of leaked memory blocks via @ref{178,,-X showrefcount}.

@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{d4f,,tp_basicsize} now accounts for non-sequence
fields that aren’t included in the @ref{b61,,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{688,,__static_attributes__}.

@item 
gh-122417@footnote{https://github.com/python/cpython/issues/122417}: In the free-threaded build, the reference counts for heap type
objects are now partially stored in a distributed manner in per-thread
arrays.  This reduces contention on the heap type’s reference count fields
when creating or destroying instances of the same type from multiple
threads concurrently.

@item 
gh-116090@footnote{https://github.com/python/cpython/issues/116090}: Fix an issue in JIT builds that prevented some @ref{321,,for}
loops from correctly firing @ref{273,,RAISE} monitoring events.

@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{28d,,frame.f_locals} now supports arbitrary hashable objects
as keys.

@item 
gh-122239@footnote{https://github.com/python/cpython/issues/122239}: When a @ref{4d9,,list}, @ref{1ce,,tuple} or @ref{188,,dict} with too
many elements is unpacked, show the actual length in the error message.

@item 
gh-122245@footnote{https://github.com/python/cpython/issues/122245}: Detection of writes to @code{__debug__} is moved from the
compiler’s codegen stage to the symtable. This means that these errors are
now detected even in code that is optimized away before codegen (such as
assertions with the @ref{431,,-O} command line option).

@item 
gh-122234@footnote{https://github.com/python/cpython/issues/122234}: Specializations for sums with float and complex inputs in
@ref{881,,sum()} now always use compensated summation.  Also, for integer items
in above specializations: @ref{1b87,,PyLong_AsDouble()} is used, instead of
@ref{160b,,PyLong_AsLongAndOverflow()}.  Patch by Sergey B Kirpichev.

@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-122160@footnote{https://github.com/python/cpython/issues/122160}: Remove the @code{BUILD_CONST_KEY_MAP} opcode. Use
@ref{598,,BUILD_MAP} instead.

@item 
gh-122029@footnote{https://github.com/python/cpython/issues/122029}: Emit @code{c_call} events in @ref{18a0,,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-99108@footnote{https://github.com/python/cpython/issues/99108}: Python’s hashlib now unconditionally uses the vendored HACL*
library for Blake2. Python no longer accepts libb2 as an optional
dependency for Blake2.

We refreshed HACL* to the latest version, and now vendor HACL*”s 128-bit
and 256-bit wide vector implementations for Blake2, which are used on
x86/x64 toolchains when the required CPU features are available at
runtime.

HACL*”s 128-bit wide vector implementation of Blake2 can also run on ARM
NEON and Power8, but lacking evidence of a performance gain, these are not
enabled (yet).
@end itemize

@node Library<54>,Core and Builtins<51>,Core and Builtins<50>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id211}@anchor{1b88}
@subsubsection Library



@itemize -

@item 
gh-121999@footnote{https://github.com/python/cpython/issues/121999}: The default extraction filter for the @ref{e7,,tarfile} module is
now set to @ref{279,,'data'}.
@end itemize

@node Core and Builtins<51>,Library<55>,Library<54>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id212}@anchor{1b89}
@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-121795@footnote{https://github.com/python/cpython/issues/121795}: Improve performance of set membership testing, @code{set.remove()}
and @code{set.discard()} when the argument is a set.

@item 
gh-121814@footnote{https://github.com/python/cpython/issues/121814}: Fixed the SegFault when @ref{850,,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{17e,,SyntaxError} message if the user tries to use
@ref{d93,,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-121297@footnote{https://github.com/python/cpython/issues/121297}: Previously, incorrect usage of @ref{432,,await} or asynchronous
comprehensions in code removed by the @ref{431,,-O} option was not flagged
by the Python compiler. Now, such code raises @ref{17e,,SyntaxError}. Patch by
Jelle Zijlstra.

@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-121562@footnote{https://github.com/python/cpython/issues/121562}: Optimized performance of hex_from_char by replacing switch-case
with a lookup table

@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-121288@footnote{https://github.com/python/cpython/issues/121288}: @ref{277,,ValueError} messages for @ref{1767,,list.index()},
@ref{1b8a,,range.index()}, @code{deque.index()}, @code{deque.remove()} and
@code{ShareableList.index()} no longer contain the repr of the searched
value (which can be arbitrary large) and are consistent with error
messages for other @ref{1b8b,,index()} and @ref{1b8c,,remove()}
methods.

@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-121149@footnote{https://github.com/python/cpython/issues/121149}: Added specialization for summation of complexes, this also
improves accuracy of builtin @ref{881,,sum()} for such inputs.  Patch by Sergey
B Kirpichev.

@item 
gh-121130@footnote{https://github.com/python/cpython/issues/121130}: Fix f-strings with debug expressions in format specifiers.
Patch by Pablo Galindo
@end itemize

@node Library<55>,Core and Builtins<52>,Core and Builtins<51>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id213}@anchor{1b8d}
@subsubsection Library



@itemize -

@item 
gh-121381@footnote{https://github.com/python/cpython/issues/121381}: Remove @code{subprocess._USE_VFORK} escape hatch code and
documentation. It was added just in case, and doesn’t have any known cases
that require it.
@end itemize

@node Core and Builtins<52>,Library<56>,Library<55>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id214}@anchor{1b8e}
@subsubsection Core and Builtins



@itemize -

@item 
gh-119726@footnote{https://github.com/python/cpython/issues/119726}: Optimize code layout for calls to C functions from the JIT on
AArch64. Patch by Diego Russo.

@item 
gh-121115@footnote{https://github.com/python/cpython/issues/121115}: @ref{7fc,,PyLong_AsNativeBytes()} no longer uses
@ref{43d,,__index__()} methods by default. The
@code{Py_ASNATIVEBYTES_ALLOW_INDEX} flag has been added to allow it.

@item 
gh-120838@footnote{https://github.com/python/cpython/issues/120838}: @ref{672,,Py_Finalize()} and @ref{10cf,,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-119726@footnote{https://github.com/python/cpython/issues/119726}: Improve the speed and memory use of C function calls from JIT
code on AArch64. Patch by Diego Russo

@item 
gh-116017@footnote{https://github.com/python/cpython/issues/116017}: Simplify the warmup mechanism used for «side exits» in JIT
code, resulting in slightly better performance and slightly lower memory
usage for most platforms.

@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-120754@footnote{https://github.com/python/cpython/issues/120754}: Reduce the number of system calls invoked when reading a whole
file (ex. @code{open('a.txt').read()}). For a sample program that reads the
contents of the 400+ @code{.rst} files in the cpython repository @code{Doc}
folder, there is an over 10% reduction in system call count.

@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-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-120507@footnote{https://github.com/python/cpython/issues/120507}: Remove the @code{BEFORE_WITH} and @code{BEFORE_ASYNC_WITH}
instructions. Add the new @ref{59e,,LOAD_SPECIAL} instruction. Generate
code for @code{with} and @code{async with} statements using the new instruction.

@item 
gh-113993@footnote{https://github.com/python/cpython/issues/113993}: Strings interned with @ref{1680,,sys.intern()} are again
garbage-collected when no longer used, as per the documentation. Strings
interned with the C function @ref{c84,,PyUnicode_InternInPlace()} are still
immortal. Internals of the string interning mechanism have been changed.
This may affect performance and identities of @ref{1df,,str} objects.
@end itemize

@node Library<56>,Core and Builtins<53>,Core and Builtins<52>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id215}@anchor{1b8f}
@subsubsection Library



@itemize -

@item 
gh-120485@footnote{https://github.com/python/cpython/issues/120485}: Add an override of @code{allow_reuse_port} on classes subclassing
@code{socketserver.TCPServer} where @code{allow_reuse_address} is also
overridden.
@end itemize

@node Core and Builtins<53>,Library<57>,Library<56>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id216}@anchor{1b90}
@subsubsection Core and Builtins



@itemize -

@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 specifically 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.
@end itemize

@node Library<57>,Core and Builtins<54>,Core and Builtins<53>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id217}@anchor{1b91}
@subsubsection Library



@itemize -

@item 
gh-120380@footnote{https://github.com/python/cpython/issues/120380}: Fix Python implementation of @ref{de2,,pickle.Pickler} for
@ref{1c7,,bytes} and @ref{1c6,,bytearray} objects when using protocol version
5. Patch by Bénédikt Tran.
@end itemize

@node Core and Builtins<54>,Library<58>,Library<57>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id218}@anchor{1b92}
@subsubsection Core and Builtins



@itemize -

@item 
gh-120397@footnote{https://github.com/python/cpython/issues/120397}: Improve the throughput by up to two times for the
@ref{1b93,,str.count()}, @ref{1b94,,bytes.count()} and @ref{1995,,bytearray.count()} methods
for counting single characters.

@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 μεταβλητή περιβάλλοντος; PYTHON_BASIC_REPL
@ref{452,,PYTHON_BASIC_REPL} when running in interactive
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 specifically 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-119726@footnote{https://github.com/python/cpython/issues/119726}: JIT: Re-use trampolines on AArch64 when creating stencils.
Patch by Diego Russo

@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-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

@item 
gh-120080@footnote{https://github.com/python/cpython/issues/120080}: Direct call to the @code{int.__round__()} now accepts @code{None}
as a valid argument.

@item 
gh-119933@footnote{https://github.com/python/cpython/issues/119933}: Improve @ref{17e,,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 
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-119879@footnote{https://github.com/python/cpython/issues/119879}: String search is now slightly faster for certain cases. It now
utilizes last character gap (good suffix rule) for two-way periodic
needles.

@item 
gh-119842@footnote{https://github.com/python/cpython/issues/119842}: Honor @ref{986,,PyOS_InputHook()} in the new REPL. Patch by Pablo
Galindo

@item 
gh-119180@footnote{https://github.com/python/cpython/issues/119180}: @ref{69a,,classmethod()} and @ref{666,,staticmethod()} now wrap the
@ref{66b,,__annotations__} and @ref{1b95,,__annotate__}
attributes of their underlying callable lazily. See 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/}. Patch by
Jelle Zijlstra.

@item 
gh-119821@footnote{https://github.com/python/cpython/issues/119821}: Fix execution of @ref{6b4,,annotation scopes}
within classes when @code{globals} is set to a non-dict. Patch by Jelle
Zijlstra.

@item 
gh-118934@footnote{https://github.com/python/cpython/issues/118934}: Make @code{PyEval_GetLocals} return borrowed reference

@item 
gh-119740@footnote{https://github.com/python/cpython/issues/119740}: Remove the previously-deprecated delegation of @ref{326,,int()} to
@ref{43b,,__trunc__()}.

@item 
gh-119689@footnote{https://github.com/python/cpython/issues/119689}: Generate stack effect metadata for pseudo instructions from
bytecodes.c.

@item 
gh-109218@footnote{https://github.com/python/cpython/issues/109218}: @ref{328,,complex()} accepts now a string only as a positional
argument. Passing a complex number as the «real» or «imag» argument is
deprecated; it should only be passed as a single positional argument.

@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{1190,,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-119258@footnote{https://github.com/python/cpython/issues/119258}: Eliminate type version guards in the tier two interpreter.

Note that setting the @code{tp_version_tag} manually (which has never been
supported) may result in crashes.

@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-119372@footnote{https://github.com/python/cpython/issues/119372}: Correct invalid corner cases in complex division (resulted in
@code{(nan+nanj)} output), e.g.  @code{1/complex('(inf+infj)')}.  Patch by
Sergey B Kirpichev.

@item 
gh-119180@footnote{https://github.com/python/cpython/issues/119180}: Evaluation of annotations is now deferred. See 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/} for
details.

@item 
gh-119180@footnote{https://github.com/python/cpython/issues/119180}: Replace @code{LOAD_ASSERTION_ERROR} opcode with
@ref{599,,LOAD_COMMON_CONSTANT} and add support for
@ref{59a,,NotImplementedError}.

@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{fba,,StopIteration} instances for
monitoring.

@item 
gh-119180@footnote{https://github.com/python/cpython/issues/119180}: Add an @code{__annotate__} attribute to functions, classes, and
modules as part of 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/}. Patch by Jelle Zijlstra.

@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{11b,,warnings} module had not yet been imported.

@item 
gh-119057@footnote{https://github.com/python/cpython/issues/119057}: Improve @ref{d11,,ZeroDivisionError} error message. Now, all error
messages are harmonized: all @code{/}, @code{//}, and @code{%} operations just use
«division by zero» message. And @code{0 ** -1} operation uses «zero to a
negative power».

@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-118750@footnote{https://github.com/python/cpython/issues/118750}: If the C version of the @code{decimal} module is available,
@code{int(str)} now uses it to supply an asymptotically much faster
conversion. However, this only applies if the string contains over about 2
million digits.

@item 
gh-118767@footnote{https://github.com/python/cpython/issues/118767}: Using @ref{440,,NotImplemented} in a boolean context now raises
@ref{291,,TypeError}. Contributed by Jelle Zijlstra.

@item 
gh-118561@footnote{https://github.com/python/cpython/issues/118561}: Fix race condition in free-threaded build where
@ref{7f8,,list.extend()} could expose uninitialised memory to concurrent
readers.

@item 
gh-117139@footnote{https://github.com/python/cpython/issues/117139}: Convert the Python evaluation stack to use internal stack
references. The purpose is to support tagged pointers. In 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}, this
will allow for its form of deferred reference counting. For both the
default and free-threaded builds, this sets up the infrastructure for
unboxed integers in the future.
@end itemize

@node Library<58>,Core and Builtins<55>,Core and Builtins<54>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id219}@anchor{1b96}
@subsubsection Library



@itemize -

@item 
gh-115801@footnote{https://github.com/python/cpython/issues/115801}: Raise @code{TypeError} when passing a string to
@ref{213,,difflib.unified_diff()} and @ref{1b97,,difflib.context_diff()}.
@end itemize

@node Core and Builtins<55>,C API<16>,Library<58>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id220}@anchor{1b98}
@subsubsection Core and Builtins



@itemize -

@item 
gh-117558@footnote{https://github.com/python/cpython/issues/117558}: Improve error messages when a string, bytes or bytearray object
of length 1 is expected.

@item 
gh-117195@footnote{https://github.com/python/cpython/issues/117195}: Avoid assertion failure for debug builds when calling
@code{object.__sizeof__(1)}

@item 
gh-116022@footnote{https://github.com/python/cpython/issues/116022}: Improve the @ref{1bc,,__repr__()} output of
@ref{2ec,,AST} nodes.

@item 
gh-114091@footnote{https://github.com/python/cpython/issues/114091}: Changed the error message for awaiting something that can’t be
awaited from «object <type> can’t be used in an await expression» to
«”<type>” object can’t be awaited».

@item 
gh-113190@footnote{https://github.com/python/cpython/issues/113190}: @ref{672,,Py_Finalize()} now deletes all interned strings.

@item 
gh-84978@footnote{https://github.com/python/cpython/issues/84978}: Add class methods @ref{437,,float.from_number()} and
@ref{438,,complex.from_number()}.

@item 
gh-95144@footnote{https://github.com/python/cpython/issues/95144}: Improve the error message from @code{a in b} when @code{b} is not a
container to mention the term «container».

@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 C API<16>,Build<15>,Core and Builtins<55>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id221}@anchor{1b99}
@subsubsection C API



@itemize -

@item 
gh-123961@footnote{https://github.com/python/cpython/issues/123961}: Convert the @ref{1a24,,curses.window} static
type exposed by the @code{PyCursesWindow_Type} macro in
@code{Include/py_curses.h} to a @ref{d2f,,heap type}. Patch by
Bénédikt Tran.

@item 
gh-124502@footnote{https://github.com/python/cpython/issues/124502}: Add @ref{5df,,PyUnicode_Equal()} function to the limited C API:
test if two strings are equal. Patch by Victor Stinner.

@item 
gh-124296@footnote{https://github.com/python/cpython/issues/124296}: @ref{83e,,PyDictObject} no longer maintains a private version
tag field @code{ma_version_tag} per 
@geindex Python Enhancement Proposals; PEP 699
PEP 699@footnote{https://peps.python.org/pep-0699/}.  This field was originally
added in Python 3.6 (
@geindex Python Enhancement Proposals; PEP 509
PEP 509@footnote{https://peps.python.org/pep-0509/}) and deprecated in Python 3.12.

@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-124153@footnote{https://github.com/python/cpython/issues/124153}: Add @ref{5dd,,PyType_GetBaseByToken()} and @ref{5de,,Py_tp_token}
slot for easier type checking, related to 
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/} and 
@geindex Python Enhancement Proposals; PEP 630
PEP 630@footnote{https://peps.python.org/pep-0630/}.

@item 
gh-124127@footnote{https://github.com/python/cpython/issues/124127}: In the limited C API 3.14 and newer, @ref{54b,,Py_REFCNT()} is now
implemented as an opaque function call to hide implementation details.
Patch by Victor Stinner.

@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.

@item 
gh-123909@footnote{https://github.com/python/cpython/issues/123909}: @ref{38e,,PyType_FromSpec()}, @ref{38f,,PyType_FromSpecWithBases()}
and @ref{390,,PyType_FromModuleAndSpec()} will now fail if the metaclass of
the new type has custom @ref{981,,tp_new}.

@item 
gh-107954@footnote{https://github.com/python/cpython/issues/107954}: Add functions to configure the Python initialization
(
@geindex Python Enhancement Proposals; PEP 741
PEP 741@footnote{https://peps.python.org/pep-0741/}):


@itemize *

@item 
@ref{5b4,,PyInitConfig_Create()}

@item 
@ref{5b5,,PyInitConfig_Free()}

@item 
@ref{5b7,,PyInitConfig_GetError()}

@item 
@ref{5b8,,PyInitConfig_GetExitCode()}

@item 
@ref{5bc,,PyInitConfig_HasOption()}

@item 
@ref{5b9,,PyInitConfig_GetInt()}

@item 
@ref{5ba,,PyInitConfig_GetStr()}

@item 
@ref{5bb,,PyInitConfig_GetStrList()}

@item 
@ref{5b6,,PyInitConfig_FreeStrList()}

@item 
@ref{5bd,,PyInitConfig_SetInt()}

@item 
@ref{5be,,PyInitConfig_SetStr()}

@item 
@ref{5bf,,PyInitConfig_SetStrList()}

@item 
@ref{5a9,,PyInitConfig_AddModule()}

@item 
@ref{5b3,,Py_InitializeFromInitConfig()}
@end itemize

Patch by Victor Stinner.

@item 
gh-107954@footnote{https://github.com/python/cpython/issues/107954}: Add functions to get and set the current runtime Python
configuration:


@itemize *

@item 
@ref{3a6,,PyConfig_Get()}

@item 
@ref{5b1,,PyConfig_GetInt()}

@item 
@ref{5aa,,PyConfig_Set()}

@item 
@ref{5b2,,PyConfig_Names()}
@end itemize

Patch by Victor Stinner.

@item 
gh-123465@footnote{https://github.com/python/cpython/issues/123465}: @ref{959,,Py_RELATIVE_OFFSET} is now allowed in
@ref{95a,,PyMemberDef} for the special offset member
@code{"__vectorcalloffset__"}, as well as the discouraged special offset
members @code{"__dictoffset__"} and @code{"__weaklistoffset__"}

@item 
gh-100554@footnote{https://github.com/python/cpython/issues/100554}: Added a slot @code{Py_tp_vectorcall} to set
@ref{1b9a,,tp_vectorcall} via the @ref{38e,,PyType_FromSpec()}
function family. Limited API extensions can use this feature to provide
more efficient vector call-based implementation of @code{__new__} and
@code{__init__}.

@item 
gh-122854@footnote{https://github.com/python/cpython/issues/122854}: Add @ref{5c2,,Py_HashBuffer()} to compute and return the hash
value of a buffer. Patch by Antoine Pitrou and Victor Stinner.

@item 
gh-122728@footnote{https://github.com/python/cpython/issues/122728}: Fix @ref{7ee,,PyEval_GetLocals()} to avoid @ref{3ea,,SystemError}
(«bad argument to internal function»). Patch by Victor Stinner.

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: Make @ref{18fe,,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-105201@footnote{https://github.com/python/cpython/issues/105201}: Add @ref{5c5,,PyIter_NextItem()} to replace @ref{5c6,,PyIter_Next()},
which has an ambiguous return value. Patch by Irit Katriel and Erlend
Aasland.

@item 
gh-121489@footnote{https://github.com/python/cpython/issues/121489}: Export private @code{_PyBytes_Join()} again.

@item 
gh-121645@footnote{https://github.com/python/cpython/issues/121645}: Add @ref{5b0,,PyBytes_Join(sep@comma{} iterable)}
function, similar to @code{sep.join(iterable)} in Python. Patch by Victor
Stinner.

@item 
gh-89364@footnote{https://github.com/python/cpython/issues/89364}: Export the @ref{177e,,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{c84,,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{3b5,,PyUnicode_InternFromString()},
@ref{1b9b,,PyDict_SetItemString()}, @ref{1a6c,,PyObject_SetAttrString()},
@ref{1a6e,,PyObject_DelAttrString()}, @code{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.

@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{1b9c,,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-120389@footnote{https://github.com/python/cpython/issues/120389}: Add new functions to convert C @code{<stdint.h>} numbers from/to
Python @ref{326,,int}:


@itemize *

@item 
@ref{5d0,,PyLong_FromInt32()}

@item 
@ref{5d2,,PyLong_FromUInt32()}

@item 
@ref{5d1,,PyLong_FromInt64()}

@item 
@ref{5d3,,PyLong_FromUInt64()}

@item 
@ref{5cc,,PyLong_AsInt32()}

@item 
@ref{5ce,,PyLong_AsUInt32()}

@item 
@ref{5cd,,PyLong_AsInt64()}

@item 
@ref{5cf,,PyLong_AsUInt64()}
@end itemize

Patch by Victor Stinner.

@item 
gh-120600@footnote{https://github.com/python/cpython/issues/120600}: In the limited C API 3.14 and newer, @ref{5f5,,Py_TYPE()} is now
implemented as an opaque function call to hide implementation details.
Patch by Victor Stinner.

@item 
gh-70278@footnote{https://github.com/python/cpython/issues/70278}: @ref{81e,,PyUnicode_FromFormat()} no longer produces the ending
@code{\ufffd} character for truncated C string when use precision with @code{%s}
and @code{%V}. It now truncates the string before the start of truncated
multibyte sequences.

@item 
gh-119771@footnote{https://github.com/python/cpython/issues/119771}: Set @ref{5a,,errno} in @ref{3c2,,_Py_c_pow()} on overflows.  Patch
by Sergey B Kirpichev.

@item 
gh-119182@footnote{https://github.com/python/cpython/issues/119182}: Add a new @ref{5e0,,PyUnicodeWriter} API to create a Python
@ref{1df,,str} object:


@itemize *

@item 
@ref{5e1,,PyUnicodeWriter_Create()}.

@item 
@ref{5e3,,PyUnicodeWriter_Discard()}.

@item 
@ref{5e4,,PyUnicodeWriter_Finish()}.

@item 
@ref{5e7,,PyUnicodeWriter_WriteChar()}.

@item 
@ref{5ec,,PyUnicodeWriter_WriteUTF8()}.

@item 
@ref{5eb,,PyUnicodeWriter_WriteUCS4()}.

@item 
@ref{5ed,,PyUnicodeWriter_WriteWideChar()}.

@item 
@ref{5e9,,PyUnicodeWriter_WriteStr()}.

@item 
@ref{5e8,,PyUnicodeWriter_WriteRepr()}.

@item 
@ref{5ea,,PyUnicodeWriter_WriteSubstring()}.

@item 
@ref{5e5,,PyUnicodeWriter_Format()}.

@item 
@ref{5e2,,PyUnicodeWriter_DecodeUTF8Stateful()}.
@end itemize

Patch by Victor Stinner.

@item 
gh-119613@footnote{https://github.com/python/cpython/issues/119613}: Soft deprecate the @ref{1b9d,,Py_MEMCPY} macro: use directly
@code{memcpy()} instead.  Patch by Victor Stinner.

@item 
gh-119775@footnote{https://github.com/python/cpython/issues/119775}: Creating @ref{5fb,,immutable types}
with mutable bases was deprecated since 3.12 and now raises a
@ref{291,,TypeError}.

@item 
gh-119585@footnote{https://github.com/python/cpython/issues/119585}: Fix crash when a thread state that was created by
@ref{1a5,,PyGILState_Ensure()} calls a destructor that during
@ref{1b9e,,PyThreadState_Clear()} that calls back into
@code{PyGILState_Ensure()} and @ref{1a6,,PyGILState_Release()}. This might
occur when in the free-threaded build or when using thread-local variables
whose destructors call @code{PyGILState_Ensure()}.

@item 
gh-119613@footnote{https://github.com/python/cpython/issues/119613}: Macros @code{Py_IS_NAN}, @code{Py_IS_INFINITY} and @code{Py_IS_FINITE}
are @ref{1a7,,soft deprecated}.

@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-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-119333@footnote{https://github.com/python/cpython/issues/119333}: Add @ref{1b9f,,PyContext_AddWatcher()} and
@ref{1ba0,,PyContext_ClearWatcher()} APIs to register callbacks to receive
notification on enter and exit of context objects.

@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{1ba1,,PyHASH_MULTIPLIER} constant: prime multiplier
used in string and various other hashes. Patch by Victor Stinner.

@item 
gh-118771@footnote{https://github.com/python/cpython/issues/118771}: Several C declarations with names that didn’t start with the
@code{Py} or @code{_Py} prefixes, which were added by mistake in 3.13 alpha and
beta releases, were moved to internal headers.

@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}: Add @ref{1ba2,,PyUnstable_Object_ClearWeakRefsNoCallbacks()}, which
clears weakrefs without calling their callbacks.

@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.

@item 
gh-117511@footnote{https://github.com/python/cpython/issues/117511}: Make the @ref{693,,PyMutex} public in the non-limited C API.

@item 
gh-116560@footnote{https://github.com/python/cpython/issues/116560}: Add @ref{5c7,,PyLong_GetSign()} function.  Patch by Sergey B
Kirpichev.

@item 
gh-97588@footnote{https://github.com/python/cpython/issues/97588}: Fix creating bitfields in @ref{2d,,ctypes} structures and unions.
Fields no longer overlap.

@item 
gh-87135@footnote{https://github.com/python/cpython/issues/87135}: Attempting to acquire the GIL after runtime finalization has
begun in a different thread now causes the thread to hang rather than
terminate, which avoids potential crashes or memory corruption caused by
attempting to terminate a thread that is running code not specifically
designed to support termination. In most cases this hanging is harmless
since the process will soon exit anyway.

The @code{PyThread_exit_thread} function is now deprecated.  Its behavior is
inconsistent across platforms, and it can only be used safely in the
unlikely case that every function in the entire call stack has been
designed to support the platform-dependent termination mechanism.  It is
recommended that users of this function change their design to not require
thread termination.  In the unlikely case that thread termination is
needed and can be done safely, users may migrate to calling
platform-specific APIs such as @code{pthread_exit} (POSIX) or
@code{_endthreadex} (Windows) directly.

@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<15>,,C API<16>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id222}@anchor{1ba3}
@subsubsection Build



@itemize -

@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-123990@footnote{https://github.com/python/cpython/issues/123990}: Remove @code{WITH_FREELISTS} macro and @code{--without-freelists}
build configuration

@item 
gh-124102@footnote{https://github.com/python/cpython/issues/124102}: Update internal documentation under PCbuild, so it now
correctly states that Windows requires VS2017 or later and Python 3.10 or
later

@item 
gh-124043@footnote{https://github.com/python/cpython/issues/124043}: Building using @ref{828,,--with-trace-refs} is (temporarily)
disallowed when the GIL is disabled.

@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{e4,,sysconfig}. Patch by Pablo Galindo

@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-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-121996@footnote{https://github.com/python/cpython/issues/121996}: Introduce ./configure –disable-safety and
–enable-slower-safety options. Patch by Donghee Na.

@item 
gh-120522@footnote{https://github.com/python/cpython/issues/120522}: Added a @ref{1ba4,,--with-app-store-compliance} option to patch
out known issues with macOS/iOS App Store review processes.

@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-121082@footnote{https://github.com/python/cpython/issues/121082}: Fix build failure when the developer use @code{--enable-pystats}
arguments in configuration command after #118450.

@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-120688@footnote{https://github.com/python/cpython/issues/120688}: On WASI in debug mode, Python is now built with compiler flag
@code{-O3} instead of @code{-Og}, to support more recursive calls. Patch by
Victor Stinner.

@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{243,,FileNotFoundError} could be caused by another process already moving
@code{jit_stencils.h.new} to @code{jit_stencils.h}.

@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.

@item 
gh-113565@footnote{https://github.com/python/cpython/issues/113565}: Improve @ref{2e,,curses} and @ref{30,,curses.panel} dependency checks
in @code{configure}.

@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-119400@footnote{https://github.com/python/cpython/issues/119400}: @code{make_ssl_certs}, the script that prepares certificate data
for the test suite, now allows specifying expiration dates.

@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{6a8,,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 Python 3 13 0 beta 1,Python 3 13 0 alpha 6,Python 3 14 0 alpha 1,Changelog
@anchor{whatsnew/changelog python-3-13-0-beta-1}@anchor{1ba5}
@subsection Python 3.13.0 beta 1


`Release date: 2024-05-08'

@menu
* Security: Security<16>. 
* Core and Builtins: Core and Builtins<56>. 
* Library: Library<59>. 
* Core and Builtins: Core and Builtins<57>. 
* Library: Library<60>. 
* Documentation: Documentation<15>. 
* Build: Build<16>. 
* Windows: Windows<14>. 
* macOS: macOS<10>. 
* IDLE: IDLE<9>. 
* C API: C API<17>. 

@end menu

@node Security<16>,Core and Builtins<56>,,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id223}@anchor{1ba6}
@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{6b,,hashlib}
to be used with libraries that do not to support every algorithm that
upstream OpenSSL does.
@end itemize

@node Core and Builtins<56>,Library<59>,Security<16>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id224}@anchor{1ba7}
@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.
@end itemize

@node Library<59>,Core and Builtins<57>,Core and Builtins<56>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id225}@anchor{1ba8}
@subsubsection Library



@itemize -

@item 
gh-95382@footnote{https://github.com/python/cpython/issues/95382}: Improve performance of @ref{248,,json.dumps()} and @ref{10fb,,json.dump()}
when using the argument `indent'. Depending on the data the encoding using
@code{json.dumps()} with `indent' can be up to 2 to 3 times faster.
@end itemize

@node Core and Builtins<57>,Library<60>,Library<59>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id226}@anchor{1ba9}
@subsubsection Core and Builtins



@itemize -

@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{18d8,,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{39,,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{1baa,,sys.set_asyncgen_hooks()} not to be partially set when
raising @ref{291,,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{451,,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{28d,,FrameType.f_locals} and @ref{84e,,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{6b4,,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{17e,,SyntaxError} message for imports without names,
like in @code{from x import} and @code{import} cases. It now points out to users
that @ref{9da,,import} expects at least one name after it.

@item 
gh-118090@footnote{https://github.com/python/cpython/issues/118090}: Improve @ref{17e,,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{6b4,,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{6dd,,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{1c7,,bytes} and
@ref{1c6,,bytearray} methods by adapting them to the
@ref{34b,,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{1df,,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{55c,,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{805,,PyRefTracer_SetTracer()} and @ref{806,,PyRefTracer_GetTracer()}, that
allows to track object creation and destruction the same way the
@ref{108,,tracemalloc} module does. Patch by Pablo Galindo

@item 
gh-107674@footnote{https://github.com/python/cpython/issues/107674}: Improved the performance of @ref{55c,,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{1a9,,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{185,,exec()} and
@ref{184,,eval()} to be passed as keywords.
@end itemize

@node Library<60>,Documentation<15>,Core and Builtins<57>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id227}@anchor{1bab}
@subsubsection Library



@itemize -

@item 
gh-118418@footnote{https://github.com/python/cpython/issues/118418}: A @ref{2c9,,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{104e,,typing.ContextManager} and @ref{1bac,,typing.AsyncContextManager},
representing the return types of @ref{16a5,,__exit__()} and
@ref{1bad,,__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{1bae,,typing.Generator} and
@ref{1baf,,typing.AsyncGenerator}.

@item 
gh-101137@footnote{https://github.com/python/cpython/issues/101137}: Mime type @code{text/x-rst} is now supported by @ref{93,,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{aa,,pdb} support for zipapps

@item 
gh-118406@footnote{https://github.com/python/cpython/issues/118406}: Add signature for @ref{3df,,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{4bd,,inspect.signature()} for non-comparable callables.

@item 
gh-118402@footnote{https://github.com/python/cpython/issues/118402}: Fix @ref{4bd,,inspect.signature()} for the result of the
@ref{1583,,functools.cmp_to_key()} call.

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: On Android, @ref{15e8,,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{11e6,,operator.attrgetter}, @ref{e26,,operator.itemgetter}, and
@ref{11e7,,operator.methodcaller} instances.

@item 
gh-118314@footnote{https://github.com/python/cpython/issues/118314}: Fix an edge case in @ref{1fd,,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{751,,sqlite3.Connection.iterdump()} could fail
if a custom @ref{1bb0,,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{8a5,,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{81,,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{bee,,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{2ec,,ast.AST}. Such classes will now require no changes in the usual
case to conform with the behavior changes of the @ref{9,,ast} module in
Python 3.13. Patch by Jelle Zijlstra.

@item 
gh-90848@footnote{https://github.com/python/cpython/issues/90848}: Fixed @ref{1b4e,,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{1bb1,,typing.Unpack}
is used with the builtin @ref{1ce,,tuple}. @code{typing.Unpack} now raises
@ref{291,,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{c0,,random} module. Patch
by Hugo van Kemenade.

@item 
gh-118107@footnote{https://github.com/python/cpython/issues/118107}: Fix @ref{13b,,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{16be,,os.path.normpath()} for UNC paths on Windows. Speed up
@ref{8b4,,os.path.splitroot()} with a native implementation.

@item 
gh-117535@footnote{https://github.com/python/cpython/issues/117535}: Change the unknown filename of @ref{11b,,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{665,,NameError} when calling
@ref{a9e,,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{1bb2,,tarfile.TarFile.addfile()}

@item 
gh-117995@footnote{https://github.com/python/cpython/issues/117995}: Don’t raise @ref{2c9,,DeprecationWarning} when a @ref{8ff,,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{1576,,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{e7,,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{73a,,pathlib.Path.glob()} by omitting an initial
@ref{73d,,is_dir()} call. As a result of this change,
@code{glob()} can no longer raise @ref{53c,,OSError}.

@item 
gh-77102@footnote{https://github.com/python/cpython/issues/77102}: @ref{cf,,site} module now parses @code{.pth} file with UTF-8 first,
and @ref{74d,,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{73a,,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{4f6,,pathlib.Path.iterdir()} by using
@ref{e23,,os.scandir()} internally.

@item 
gh-117586@footnote{https://github.com/python/cpython/issues/117586}: Speed up @ref{8b8,,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{6d6,,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{1bb3,,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{334,,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{1a42,,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{aa,,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{8ba,,os.path.relpath()}.

@item 
gh-117586@footnote{https://github.com/python/cpython/issues/117586}: Speed up @ref{73a,,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{1bb4,,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{241,,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{6d7,,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{6d8,,ExceptionGroup}, it will now call the parent task’s
@ref{6d9,,cancel()} method. This ensures that a
@ref{6da,,asyncio.CancelledError} will be raised at the next @ref{432,,await},
so the cancellation is not lost.

An added benefit of these changes is that task groups now preserve the
cancellation count (@ref{6db,,asyncio.Task.cancelling()}).

In order to handle some corner cases, @ref{6dc,,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{697,,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{dd8,,os.path.expanduser()} on Posix.

@item 
gh-117394@footnote{https://github.com/python/cpython/issues/117394}: @ref{dd6,,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{3e,,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{71a,,mimetypes.guess_file_type()} function which works
with file path. Passing file path instead of URL in
@ref{71b,,guess_type()} is @ref{1a7,,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{1a9,,AttributeError} and
@ref{1bd,,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{1e1,,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{14,,bz2}, @ref{8d,,lzma},
@ref{e7,,tarfile} and @ref{13a,,zipfile}. The value of the @code{mode}
attribute of @ref{849,,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{84a,,zipfile.ZipFile.open()} was changed from @code{'r'} to @code{'rb'}.

@item 
gh-82062@footnote{https://github.com/python/cpython/issues/82062}: Fix @ref{4bd,,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{d,,atexit} for all @ref{98,,multiprocessing} start methods

@item 
gh-113081@footnote{https://github.com/python/cpython/issues/113081}: Print colorized exception just like built-in traceback in
@ref{aa,,pdb}

@item 
gh-112855@footnote{https://github.com/python/cpython/issues/112855}: Speed up pickling of @ref{8b6,,pathlib.PurePath} objects. Patch
by Barney Gale.

@item 
gh-111744@footnote{https://github.com/python/cpython/issues/111744}: Support opcode events in @ref{10,,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{aa,,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{b21,,__class_getitem__()} to
@ref{1bb5,,types.GeneratorType} and @ref{123a,,types.CoroutineType} for type
hinting purposes. Patch by James Hilton-Balfe.

@item 
gh-108191@footnote{https://github.com/python/cpython/issues/108191}: The @ref{6ea,,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{7,,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{1bb6,,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{f9,,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{74b,,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<15>,Build<16>,Library<60>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id228}@anchor{1bb7}
@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<16>,Windows<14>,Documentation<15>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id229}@anchor{1bb8}
@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{3d6,,--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{39,,decimal} dependencies if the @ref{3d6,,--with-system-libmpdec} option
is given.
@end itemize

@node Windows<14>,macOS<10>,Build<16>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id230}@anchor{1bb9}
@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{72e,,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<10>,IDLE<9>,Windows<14>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id231}@anchor{1bba}
@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 μεταβλητή περιβάλλοντος; PATH
@code{PATH} when installing for the
Fish shell.
@end itemize

@node IDLE<9>,C API<17>,macOS<10>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id232}@anchor{1bbb}
@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<17>,,IDLE<9>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id233}@anchor{1bbc}
@subsubsection C API



@itemize -

@item 
gh-118124@footnote{https://github.com/python/cpython/issues/118124}: Fix @ref{1bbd,,Py_BUILD_ASSERT} and
@ref{1bbe,,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{7d1,,PyTime_MonotonicRaw()}

@item 
@ref{7d3,,PyTime_PerfCounterRaw()}

@item 
@ref{7d5,,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{1bbf,,Py_SetPythonHome()}

@item 
@ref{1bc0,,Py_SetProgramName()}

@item 
@ref{1bc1,,PySys_SetArgvEx()}

@item 
@ref{1bc2,,PySys_SetArgv()}
@end itemize

Patch by Victor Stinner.

@item 
gh-117929@footnote{https://github.com/python/cpython/issues/117929}: Restore removed @ref{1bc3,,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{a0a,,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{1bc4}
@subsection Python 3.13.0 alpha 6


`Release date: 2024-04-09'

@menu
* Core and Builtins: Core and Builtins<58>. 
* Library: Library<61>. 
* Core and Builtins: Core and Builtins<59>. 
* Library: Library<62>. 
* Documentation: Documentation<16>. 
* Tests: Tests<18>. 
* Build: Build<17>. 
* Windows: Windows<15>. 
* C API: C API<18>. 

@end menu

@node Core and Builtins<58>,Library<61>,,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id234}@anchor{1bc5}
@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{1c7,,bytes} and
@ref{1c6,,bytearray} methods by adapting them to the
@ref{34b,,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{1df,,str} methods
by adapting them to the @ref{34b,,METH_FASTCALL} calling convention:


@itemize *

@item 
@ref{1b93,,count()}

@item 
@ref{127a,,endswith()}

@item 
@ref{1259,,find()}

@item 
@ref{1bc6,,index()}

@item 
@ref{125a,,rfind()}

@item 
@ref{15fc,,rindex()}

@item 
@ref{1279,,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{2ec,,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{6b,,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{1bc7,,CALL} event.

@item 
gh-113964@footnote{https://github.com/python/cpython/issues/113964}: Starting new threads and process creation through
@ref{6bd,,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{1bc7,,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.
@end itemize

@node Library<61>,Core and Builtins<59>,Core and Builtins<58>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id235}@anchor{1bc8}
@subsubsection Library



@itemize -

@item 
gh-109870@footnote{https://github.com/python/cpython/issues/109870}: Dataclasses now calls @ref{185,,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{93,,mimetypes}.
@end itemize

@node Core and Builtins<59>,Library<62>,Library<61>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id236}@anchor{1bc9}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-24612@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24612}: Improve the @ref{17e,,SyntaxError} that happens when “not” appears
after an operator. Patch by Pablo Galindo
@end itemize

@node Library<62>,Documentation<16>,Core and Builtins<59>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id237}@anchor{1bca}
@subsubsection Library



@itemize -

@item 
gh-117648@footnote{https://github.com/python/cpython/issues/117648}: Improve performance of @ref{1a42,,os.path.join()} and
@ref{dd8,,os.path.expanduser()}.

@item 
gh-117584@footnote{https://github.com/python/cpython/issues/117584}: Raise @ref{291,,TypeError} for non-paths in
@ref{8ba,,posixpath.relpath}.

@item 
gh-117467@footnote{https://github.com/python/cpython/issues/117467}: Preserve mailbox ownership when rewriting in
@ref{1bcb,,mailbox.mbox.flush}. Patch by Tony
Mountifield.

@item 
gh-114848@footnote{https://github.com/python/cpython/issues/114848}: Raise @ref{243,,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{c0e,,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{2d4,,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{a6,,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{6e4,,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{849,,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{d8,,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{df,,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{ee8,,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{3b,,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{11c7,,types.ModuleType}.

@item 
gh-117084@footnote{https://github.com/python/cpython/issues/117084}: Fix @ref{13a,,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{1bcc,,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{a9a,,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{2d2,,datetime.datetime.strptime()} and @ref{17cf,,time.strptime()} which always
fails to parse a date string with a @ref{277,,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{266,,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{75e,,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{113,,urllib.parse} functions @ref{589,,parse_qs()} and
@ref{588,,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{1bcd,,ipaddress.IPv4Address.is_private} (see these docs for details)

@item 
@ref{1309,,ipaddress.IPv4Address.is_global}

@item 
@ref{1bce,,ipaddress.IPv6Address.is_private}

@item 
@ref{1bcf,,ipaddress.IPv6Address.is_global}
@end itemize

Also in the corresponding @ref{712,,ipaddress.IPv4Network} and
@ref{713,,ipaddress.IPv6Network} attributes.

@item 
gh-63283@footnote{https://github.com/python/cpython/issues/63283}: In @ref{55,,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{1bd0,,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{718,,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{7e,,importlib.resources} functions
@ref{702,,is_resource()},
@ref{703,,open_binary()},
@ref{704,,open_text()}, @ref{705,,path()},
@ref{706,,read_binary()}, and
@ref{707,,read_text()} are un-deprecated, and support
subdirectories via multiple positional arguments. The
@ref{708,,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{2d,,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{f18,,os.fwalk()} and @ref{335,,shutil.rmtree()} on
opening named pipe.

@item 
gh-71052@footnote{https://github.com/python/cpython/issues/71052}: Implement @ref{10fe,,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{119,,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{d8,,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{241,,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{6d4,,asyncio.Server.close_clients()} and
@ref{6d5,,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{aa,,pdb} now allows CLI arguments to @code{pdb -m}.

@item 
gh-112948@footnote{https://github.com/python/cpython/issues/112948}: Make completion of @ref{aa,,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{e39,,asyncio.Queue} termination with
@ref{6d2,,shutdown()} method.

@item 
gh-89739@footnote{https://github.com/python/cpython/issues/89739}: The @ref{13b,,zipimport} module can now read ZIP64 files.

@item 
bpo-33533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33533}: @ref{6cc,,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{1bd1,,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{1a04,,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{6d6,,asyncio.StreamReader.readuntil()}, stopping when one of them is
encountered.

@item 
gh-66543@footnote{https://github.com/python/cpython/issues/66543}: Make @ref{71b,,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{138e,,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<16>,Tests<18>,Library<62>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id238}@anchor{1bd2}
@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<18>,Build<17>,Documentation<16>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id239}@anchor{1bd3}
@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<17>,Windows<15>,Tests<18>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id240}@anchor{1bd4}
@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<15>,C API<18>,Build<17>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id241}@anchor{1bd5}
@subsubsection Windows



@itemize -

@item 
gh-117267@footnote{https://github.com/python/cpython/issues/117267}: Ensure @code{DirEntry.stat().st_ctime} behaves consistently with
@ref{4f5,,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{1bd6,,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{75d,,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<18>,,Windows<15>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id242}@anchor{1bd7}
@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{3b3,,_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 @ref{1bd8,,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{81b,,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{827,,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{7ef,,Py_GetConstant()} and
@ref{7f0,,Py_GetConstantBorrowed()} functions to get constants. For example,
@code{Py_GetConstant(Py_CONSTANT_ZERO)} returns a @ref{7da,,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{81e,,PyUnicode_FromFormat()}: format the fully qualified name of an
object type and of a type: call @ref{80c,,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{80c,,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{80a,,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{829,,limited C API}. Patch by Victor Stinner.

@item 
gh-111140@footnote{https://github.com/python/cpython/issues/111140}: Add additional flags to @ref{7fc,,PyLong_AsNativeBytes()} and
@ref{7fd,,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{802,,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{1bd9}
@subsection Python 3.13.0 alpha 5


`Release date: 2024-03-12'

@menu
* Security: Security<17>. 
* Core and Builtins: Core and Builtins<60>. 
* Library: Library<63>. 
* Core and Builtins: Core and Builtins<61>. 
* Library: Library<64>. 
* Core and Builtins: Core and Builtins<62>. 
* Library: Library<65>. 
* Documentation: Documentation<17>. 
* Tests: Tests<19>. 
* Build: Build<18>. 
* Windows: Windows<16>. 
* macOS: macOS<11>. 
* IDLE: IDLE<10>. 
* Tools/Demos: Tools/Demos<14>. 
* C API: C API<19>. 

@end menu

@node Security<17>,Core and Builtins<60>,,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id243}@anchor{1bda}
@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{777,,xml.etree.ElementTree.XMLParser.flush()}

@item 
@ref{778,,xml.etree.ElementTree.XMLPullParser.flush()}

@item 
@ref{779,,xml.parsers.expat.xmlparser.GetReparseDeferralEnabled()}

@item 
@ref{77a,,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{1355,,ssl.SSLContext.cert_store_stats()} and
@ref{1356,,ssl.SSLContext.get_ca_certs()} now correctly lock access to the
certificate store, when the @ref{336,,ssl.SSLContext} is shared across
multiple threads.
@end itemize

@node Core and Builtins<60>,Library<63>,Security<17>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id244}@anchor{1bdb}
@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{880,,PyErr_CheckSignals()} and the evaluation breaker.
Patch by Pablo Galindo

@item 
gh-112087@footnote{https://github.com/python/cpython/issues/112087}: @ref{4d9,,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{17e,,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
@ref{198b,,bytearray.extend()} is called with a @ref{1df,,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.
@end itemize

@node Library<63>,Core and Builtins<61>,Core and Builtins<60>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id245}@anchor{1bdc}
@subsubsection Library



@itemize -

@item 
gh-115154@footnote{https://github.com/python/cpython/issues/115154}: Fix a bug that was causing the @ref{1ad4,,tokenize.untokenize()}
function to handle unicode named literals incorrectly. Patch by Pablo
Galindo
@end itemize

@node Core and Builtins<61>,Library<64>,Library<63>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id246}@anchor{1bdd}
@subsubsection Core and Builtins



@itemize -

@item 
gh-112433@footnote{https://github.com/python/cpython/issues/112433}: Add ability to force alignment of @ref{47c,,ctypes.Structure} by
way of the new @code{_align_} attribute on the class.
@end itemize

@node Library<64>,Core and Builtins<62>,Core and Builtins<61>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id247}@anchor{1bde}
@subsubsection Library



@itemize -

@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.
@end itemize

@node Core and Builtins<62>,Library<65>,Library<64>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id248}@anchor{1bdf}
@subsubsection Core and Builtins



@itemize -

@item 
gh-105858@footnote{https://github.com/python/cpython/issues/105858}: Improve the constructors for @ref{9,,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<65>,Documentation<17>,Core and Builtins<62>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id249}@anchor{1be0}
@subsubsection Library



@itemize -

@item 
gh-116600@footnote{https://github.com/python/cpython/issues/116600}: Fix @ref{45b,,repr()} for global @ref{a14,,Flag} members.

@item 
gh-116349@footnote{https://github.com/python/cpython/issues/116349}: @code{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{10d,,typing}: implement 
@geindex Python Enhancement Proposals; PEP 705
PEP 705@footnote{https://peps.python.org/pep-0705/} which adds
@ref{696,,typing.ReadOnly} support to @ref{290,,typing.TypedDict}.

@item 
gh-116325@footnote{https://github.com/python/cpython/issues/116325}: @ref{10d,,typing}: raise @ref{17e,,SyntaxError} instead of
@ref{1a9,,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{aa,,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{bd,,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{11e,,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{1b4e,,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{1c9,,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{1be1,,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{f7,,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{113,,urllib.parse} functions @ref{589,,parse_qs()} and
@ref{588,,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{899,,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{2c,,csv}. @ref{899,,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{cb6,,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{b,,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{6bb,,property} methods @ref{1be2,,getter()},
@ref{1be3,,setter()} and @ref{1be4,,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{1306,,inspect.unwrap()} for types with the @code{__wrapper__}
data descriptor. Fix @ref{b20,,inspect.Signature.from_callable()} for builtins
@ref{69a,,classmethod()} and @ref{666,,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{b20,,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{bd,,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{106e,,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{277,,ValueError}
exception when passed an empty iterable. Previously, @ref{18d7,,IndexError} was
raised.

@code{posixpath.commonpath()} now raises a @ref{291,,TypeError} exception when
passed @code{None}. Previously, @ref{277,,ValueError} was raised.

@item 
gh-114610@footnote{https://github.com/python/cpython/issues/114610}: Fix bug where @ref{1be5,,pathlib.PurePath.with_stem()} converted a
non-empty path suffix to a stem when given an empty `stem' argument. It
now raises @ref{277,,ValueError}, just like
@ref{1b6a,,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{68f,,ssl.VERIFY_X509_PARTIAL_CHAIN} and
@code{VERIFY_X509_STRICT} to the default SSL context created with
@ref{68e,,ssl.create_default_context()}.

@item 
gh-112281@footnote{https://github.com/python/cpython/issues/112281}: Allow creating @ref{ba2,,union of types} for
@ref{d09,,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{914,,configparser.ParsingError} from
@ref{180a,,read()} and
@ref{915,,read_file()} methods of
@ref{6e4,,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{1642,,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{12eb,,filecmp.dircmp} like @ref{1be6,,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}: Always include the @ref{1be7,,module} name in the @ref{45b,,repr()} of
@ref{4a6,,functools.partial()} objects.  Patch 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{7,,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{130b,,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{7,,argparse}.

@item 
bpo-43952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43952}: Fix @ref{1be8,,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{21e,,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{1371,,sys.__interactivehook__} on
startup. The default implementation of @code{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<17>,Tests<19>,Library<65>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id250}@anchor{1be9}
@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{119,,uuid} on Linux.
@end itemize

@node Tests<19>,Build<18>,Documentation<17>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id251}@anchor{1bea}
@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<18>,Windows<16>,Tests<19>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id252}@anchor{1beb}
@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{518,,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<16>,macOS<11>,Build<18>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id253}@anchor{1bec}
@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{9bc,,Διαχειριστής εγκατάστασης Python}. 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{9bc,,Διαχειριστής εγκατάστασης Python} 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 μεταβλητή περιβάλλοντος; PYLAUNCHER_ALLOW_INSTALL
@code{PYLAUNCHER_ALLOW_INSTALL} is set.
@end itemize

@node macOS<11>,IDLE<10>,Windows<16>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id254}@anchor{1bed}
@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<10>,Tools/Demos<14>,macOS<11>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id255}@anchor{1bee}
@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<14>,C API<19>,IDLE<10>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id256}@anchor{1bef}
@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<19>,,Tools/Demos<14>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id257}@anchor{1bf0}
@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{1bf1,,PyHASH_MODULUS}, @ref{1bf2,,PyHASH_BITS},
@ref{1bf3,,PyHASH_INF} and @ref{1bf4,,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{1bf5}
@subsection Python 3.13.0 alpha 4


`Release date: 2024-02-15'

@menu
* Security: Security<18>. 
* Core and Builtins: Core and Builtins<63>. 
* Library: Library<66>. 
* Documentation: Documentation<18>. 
* Tests: Tests<20>. 
* Build: Build<19>. 
* Windows: Windows<17>. 
* macOS: macOS<12>. 
* IDLE: IDLE<11>. 
* Tools/Demos: Tools/Demos<15>. 
* C API: C API<20>. 

@end menu

@node Security<18>,Core and Builtins<63>,,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id258}@anchor{1bf6}
@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{1189,,collections.deque.index()} when
the deque is concurrently modified.
@end itemize

@node Core and Builtins<63>,Library<66>,Security<18>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id259}@anchor{1bf7}
@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{c3c,,reversed()}. Patch by Donghee Na

@item 
gh-114570@footnote{https://github.com/python/cpython/issues/114570}: Add @ref{68a,,PythonFinalizationError} exception. This exception
derived from @ref{30d,,RuntimeError} is raised when an operation is blocked
during the @ref{1a0,,Python finalization}. Patch by
Victor Stinner.

@item 
gh-114695@footnote{https://github.com/python/cpython/issues/114695}: Add @ref{345,,sys._clear_internal_caches()}, which clears all
internal performance-related caches (and deprecate the less-general
@ref{344,,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{443,,super()} inside a comprehension in a class body.

@item 
gh-112069@footnote{https://github.com/python/cpython/issues/112069}: Adapt @ref{42b,,set} and @ref{9d4,,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{43d,,__index__()} method as for @ref{326,,int}.

@item 
gh-114887@footnote{https://github.com/python/cpython/issues/114887}: Changed socket type validation in
@ref{b1a,,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{1bf8,,chr()} builtin function now always raises
@ref{277,,ValueError} for values outside the valid range. Previously it raised
@ref{c57,,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{6dd,,RuntimeWarning} emitted when assign an integer-like
value that is not an instance of @ref{326,,int} to an attribute that
corresponds to a C struct member of @ref{1bf9,,type} T_UINT
and T_ULONG. Fix a double @code{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{f27,,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{9d6,,collections.deque} to use Argument Clinic.

@item 
gh-112050@footnote{https://github.com/python/cpython/issues/112050}: Make methods on @ref{9d6,,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{186,,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<66>,Documentation<18>,Core and Builtins<63>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id260}@anchor{1bfa}
@subsubsection Library



@itemize -

@item 
gh-115392@footnote{https://github.com/python/cpython/issues/115392}: Fix a bug in @ref{3d,,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{439,,format()} bugs when using the C implementation
of @ref{1c2,,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{1c3,,fractions.Fraction} and
@ref{328,,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{10d,,typing} generic aliases (including generic aliases created using
@ref{d09,,typing.Annotated}). Previously only @ref{1a9,,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{139c,,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{2d4,,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{e7,,tarfile} and @ref{13a,,zipfile}.

@item 
gh-115060@footnote{https://github.com/python/cpython/issues/115060}: Speed up @ref{73a,,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{ea,,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{e7,,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{6c7,,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{7,,argparse}
(e.g. @code{--option=--}).

@item 
gh-49766@footnote{https://github.com/python/cpython/issues/49766}: Fix @ref{48d,,date}-@ref{6e7,,datetime}
comparison. Now the special comparison methods like @code{__eq__} and
@code{__lt__} return @ref{440,,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{291,,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{1c2,,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{73a,,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{7d,,importlib.metadata} and
@ref{53,,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{cbb,,ssl.SSLSocket} creation.

@item 
gh-77749@footnote{https://github.com/python/cpython/issues/77749}: @ref{1bfb,,email.policy.EmailPolicy.fold()} now always encodes
non-ASCII characters in headers if @ref{217,,utf8}
is false.

@item 
gh-83383@footnote{https://github.com/python/cpython/issues/83383}: Synchronization of the @ref{35,,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 @code{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{751,,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{146c,,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{3eb,,xml.etree.ElementTree.iterparse()}.

@item 
gh-109653@footnote{https://github.com/python/cpython/issues/109653}: Reduce the import time of @ref{f6,,threading} module by ~50%.
Patch by Daniel Hollas.

@item 
gh-114492@footnote{https://github.com/python/cpython/issues/114492}: Make the result of @ref{1bfc,,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{1a10,,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{38,,dbm.sqlite3} as a backend to @ref{34,,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{53c,,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{10fe,,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{5c,,fcntl}
module on Linux, macOS, FreeBSD and NetBSD.

@item 
gh-114328@footnote{https://github.com/python/cpython/issues/114328}: The @ref{1bfd,,tty.setcbreak()} and new @ref{1bfe,,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{32,,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{53c,,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{7,,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{79f,,path-like objects} as patterns
in @ref{73a,,pathlib.Path.glob()} and @ref{73b,,rglob()}.

@item 
gh-112202@footnote{https://github.com/python/cpython/issues/112202}: Ensure that a @ref{1bff,,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{bd,,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{1a3c,,csv.Dialect}
constructor. @ref{277,,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{896,,QUOTE_NOTNULL} and
@ref{897,,QUOTE_STRINGS} in @ref{898,,csv.reader()}.

@item 
gh-113225@footnote{https://github.com/python/cpython/issues/113225}: Speed up @ref{8b8,,pathlib.Path.walk()} by using
@ref{1c00,,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{186d,,datetime.datetime.replace()},
@ref{1c01,,datetime.date.replace()} and @ref{1c02,,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{aa,,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{93,,mimetypes} module.

@item 
gh-43457@footnote{https://github.com/python/cpython/issues/43457}: Fix the @ref{f9,,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{aa,,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{106,,trace}. Instead of checking if a
directory exists and creating it, directly call @ref{72f,,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{1c03,,mailbox.mbox} and
@ref{1c04,,mailbox.MMDF}.

@item 
gh-106233@footnote{https://github.com/python/cpython/issues/106233}: Fix stacklevel in @code{InvalidTZPathWarning} during
@ref{13d,,zoneinfo} module import.

@item 
gh-105102@footnote{https://github.com/python/cpython/issues/105102}: Allow @ref{47d,,ctypes.Union} to be nested in
@ref{47c,,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{1738,,queue.Queue} termination with
@ref{745,,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{1c05,,os.posix_openpt()},
@ref{1c06,,os.grantpt()}, @ref{1c07,,os.unlockpt()}, and @ref{1c08,,os.ptsname()}.

@item 
gh-102512@footnote{https://github.com/python/cpython/issues/102512}: When @ref{6bd,,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{2d9,,os.path.isreserved()}, which identifies reserved
pathnames such as «NUL», «AUX» and «CON». This function is only available
on Windows.

Deprecate @code{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<18>,Tests<20>,Library<66>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id261}@anchor{1c09}
@subsubsection Documentation



@itemize -

@item 
gh-115233@footnote{https://github.com/python/cpython/issues/115233}: Fix an example for @ref{169a,,LoggerAdapter} in the
Logging Cookbook.

@item 
gh-114123@footnote{https://github.com/python/cpython/issues/114123}: Move the @ref{2c,,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<20>,Build<19>,Documentation<18>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id262}@anchor{1c0a}
@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<19>,Windows<17>,Tests<20>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id263}@anchor{1c0b}
@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{69,,grp} module.
@end itemize

@node Windows<17>,macOS<12>,Build<19>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id264}@anchor{1c0c}
@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{98,,multiprocessing} to create pools of greater than 62
processes.
@end itemize

@node macOS<12>,IDLE<11>,Windows<17>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id265}@anchor{1c0d}
@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{1c0e,,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<11>,Tools/Demos<15>,macOS<12>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id266}@anchor{1c0f}
@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<15>,C API<20>,IDLE<11>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id267}@anchor{1c10}
@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{1c11,,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<20>,,Tools/Demos<15>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id268}@anchor{1c12}
@subsubsection C API



@itemize -

@item 
gh-111140@footnote{https://github.com/python/cpython/issues/111140}: Adds @ref{7fc,,PyLong_AsNativeBytes()},
@ref{7fd,,PyLong_FromNativeBytes()} and
@ref{7fe,,PyLong_FromUnsignedNativeBytes()} functions.

@item 
gh-114685@footnote{https://github.com/python/cpython/issues/114685}: @ref{b42,,PyBuffer_FillInfo()} now raises a @ref{3ea,,SystemError} if
called with @ref{1c13,,PyBUF_READ} or @ref{1c14,,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{82c,,PyObject_GetBuffer()} now raises a @ref{3ea,,SystemError} if
called with @ref{1c13,,PyBUF_READ} or @ref{1c14,,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{7f4,,PyList_GetItemRef()}, which is similar to
@ref{7f5,,PyList_GetItem()} but returns a @ref{7da,,strong reference} instead of
a @ref{603,,borrowed reference}.

@item 
gh-110850@footnote{https://github.com/python/cpython/issues/110850}: Add PyTime C API:


@itemize *

@item 
@ref{7cc,,PyTime_t} type.

@item 
@ref{7cd,,PyTime_MIN} and @ref{7ce,,PyTime_MAX} constants.

@item 
@ref{7cf,,PyTime_AsSecondsDouble()},
@ref{7d0,,PyTime_Monotonic()}, @ref{7d2,,PyTime_PerfCounter()}, and
@ref{7d4,,PyTime_Time()} functions.
@end itemize

Patch by Victor Stinner.

@item 
gh-112066@footnote{https://github.com/python/cpython/issues/112066}: Add @ref{7db,,PyDict_SetDefaultRef()}: insert a key and value into
a dictionary if the key is not already present. This is similar to
@ref{1421,,dict.setdefault()}, but returns an integer value indicating if the
key was already present. It is also similar to
@ref{7dc,,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{1c15}
@subsection Python 3.13.0 alpha 3


`Release date: 2024-01-17'

@menu
* Security: Security<19>. 
* Core and Builtins: Core and Builtins<64>. 
* Library: Library<67>. 
* Documentation: Documentation<19>. 
* Tests: Tests<21>. 
* Build: Build<20>. 
* Windows: Windows<18>. 
* macOS: macOS<13>. 
* IDLE: IDLE<12>. 
* C API: C API<21>. 

@end menu

@node Security<19>,Core and Builtins<64>,,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id269}@anchor{1c16}
@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<64>,Library<67>,Security<19>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id270}@anchor{1c17}
@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{1d,,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{443,,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{1c9,,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{12b9,,min()} and @ref{12ba,,max()}.

@item 
gh-112943@footnote{https://github.com/python/cpython/issues/112943}: Correctly compute end column offsets for multiline tokens in
the @ref{104,,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{167d,,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{1c18,,zlib.crc32()} and @ref{1c19,,binascii.crc32()} could produce incorrect
results on multi-gigabyte inputs. Including when using @ref{13a,,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{11cd,,getcoroutinestate()} and @ref{15dc,,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{1c1a,,PyComplex_RealAsDouble()}/@ref{1c1b,,PyComplex_ImagAsDouble()} now
tries to convert an object to a @ref{328,,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{75a,,sys._is_interned()}.
@end itemize

@node Library<67>,Documentation<19>,Core and Builtins<64>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id271}@anchor{1c1c}
@subsubsection Library



@itemize -

@item 
gh-114077@footnote{https://github.com/python/cpython/issues/114077}: Fix possible @ref{c57,,OverflowError} in
@ref{120e,,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{b0,,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{1c3,,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{751,,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{547,,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{f9,,tkinter} method @code{winfo_pathname()} on 64-bit
Windows.

@item 
gh-113868@footnote{https://github.com/python/cpython/issues/113868}: Added @ref{1c1d,,mmap.MAP_NORESERVE}, @ref{1c1e,,mmap.MAP_NOEXTEND},
@ref{1c1f,,mmap.MAP_HASSEMAPHORE}, @ref{1c20,,mmap.MAP_NOCACHE},
@ref{1c21,,mmap.MAP_JIT}, @ref{1c22,,mmap.MAP_RESILIENT_CODESIGN},
@ref{1c23,,mmap.MAP_RESILIENT_MEDIA}, @ref{1c24,,mmap.MAP_32BIT},
@ref{1c25,,mmap.MAP_TRANSLATED_ALLOW_EXECUTE}, @ref{1c26,,mmap.MAP_UNIX03} and
@ref{1c27,,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{6d7,,asyncio.TaskGroup()} and @ref{9f5,,asyncio.timeout()} context
managers now handle @ref{6da,,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{c0e,,TimeoutError} in the context of the exception that
was raised during exiting an expired @ref{9f5,,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{1c28,,asyncio.Condition.wait()} now re-raises the same
@code{CancelledError} instance that may have caused it to be interrupted.
Fixed race condition in @ref{1c29,,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{f7,,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{13a,,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{8b6,,pathlib.PurePath} and
not its private base class @code{PurePathBase}.

@item 
gh-113594@footnote{https://github.com/python/cpython/issues/113594}: Fix @ref{a67,,UnicodeEncodeError} in @ref{3e,,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{90,,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{ab,,pickle} and
@ref{ac,,pickletools} command line interfaces.

@item 
gh-113537@footnote{https://github.com/python/cpython/issues/113537}: Support loads @code{str} in @ref{d1b,,plistlib.loads()}.

@item 
gh-89850@footnote{https://github.com/python/cpython/issues/89850}: Add default implementations of
@ref{1b28,,pickle.Pickler.persistent_id()} and
@ref{1b2f,,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{de2,,pickle.Pickler} and
@ref{1978,,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{1c2a,,assert_has_calls()} failure.

@item 
gh-101225@footnote{https://github.com/python/cpython/issues/101225}: Increase the backlog for
@ref{1c2b,,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{148c,,multiprocessing.connection.Connection} to them.

@item 
gh-113568@footnote{https://github.com/python/cpython/issues/113568}: Raise audit events from @ref{4ee,,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{ab,,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{110,,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{76c,,Protocol}
classes that were not marked as @ref{861,,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{b0,,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{fba,,StopIteration} into @ref{30d,,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{73a,,pathlib.Path.glob()} by using
@ref{1c00,,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{df,,subprocess} module can now use the
@ref{731,,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{72d,,os.fchmod()} and a file descriptor in
@ref{72c,,os.chmod()} on Windows.

@item 
gh-113188@footnote{https://github.com/python/cpython/issues/113188}: Fix @ref{1c2c,,shutil.copymode()} and @ref{14da,,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{731,,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{72b,,os.lchmod()} and the `follow_symlinks'
argument in @ref{72c,,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{14e0,,signal.signal()} and @ref{1c2d,,signal.getsignal()} no longer
call @code{repr} on callable handlers. @ref{309,,asyncio.run()} and
@ref{1b62,,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{3b,,dis} module functions add cache information to the
@ref{494,,Instruction} instance rather than creating fake
@code{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{b,,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{e5,,syslog} module, all of them constants
on used on macOS.

@item 
gh-112800@footnote{https://github.com/python/cpython/issues/112800}: Fix @ref{b,,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{ea,,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{15da,,tempfile.TemporaryDirectory()} cleanup on Windows.

@item 
gh-94692@footnote{https://github.com/python/cpython/issues/94692}: @ref{335,,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{1c2e,,pathlib.Path.absolute()}. Patch by Barney Gale.

@item 
gh-74690@footnote{https://github.com/python/cpython/issues/74690}: Speedup @ref{2f0,,issubclass()} checks against simple
@ref{861,,runtime-checkable protocols} by around
6%. Patch by Alex Waygood.

@item 
gh-74690@footnote{https://github.com/python/cpython/issues/74690}: Speedup @ref{2ef,,isinstance()} checks by roughly 20% for
@ref{861,,runtime-checkable protocols} that only
have one callable member. Speedup @ref{2f0,,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{335,,shutil.rmtree()}.

@item 
gh-112640@footnote{https://github.com/python/cpython/issues/112640}: Add @code{kwdefaults} parameter to @ref{c59,,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{462,,asyncio.create_task()}.

@item 
gh-112618@footnote{https://github.com/python/cpython/issues/112618}: Fix a caching bug relating to @ref{d09,,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{df,,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{6bf,,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{df3,,socket.if_indextoname()} with specific value
(UINT_MAX). Fix an integer overflow in @code{socket.if_indextoname()} on
64-bit non-Windows platforms.

@item 
gh-112578@footnote{https://github.com/python/cpython/issues/112578}: Fix a spurious @ref{6dd,,RuntimeWarning} when executing the
@ref{13a,,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{1c2f,,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{290,,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{d8,,ssl} module.

@item 
gh-112414@footnote{https://github.com/python/cpython/issues/112414}: Fix regression in Python 3.12 where calling @ref{45b,,repr()} on a
module that had been imported using a custom @ref{1c30,,loader} could fail
with @ref{1a9,,AttributeError}. Patch by Alex Waygood.

@item 
gh-112358@footnote{https://github.com/python/cpython/issues/112358}: Revert change to @ref{2fb,,struct.Struct} initialization that
broke some cases of subclassing.

@item 
gh-112405@footnote{https://github.com/python/cpython/issues/112405}: Optimize @ref{575,,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{1c31,,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{a8,,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{2f0,,issubclass()}
against a @ref{76c,,typing.Protocol} that has non-method members. Patch by
Randolf Scholz.

@item 
gh-112137@footnote{https://github.com/python/cpython/issues/112137}: Change @ref{3b,,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{764,,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{8c0,,random.binomialvariate()}

@item 
gh-112292@footnote{https://github.com/python/cpython/issues/112292}: Fix a crash in @ref{c2,,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{a8,,pathlib} module by
deferring some imports. Patch by Barney Gale.

@item 
gh-112137@footnote{https://github.com/python/cpython/issues/112137}: Change @ref{3b,,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{bd,,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{1c32,,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{2e4,,typing.NamedTuple} class, ensure
@ref{100c,,__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{760,,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{aa,,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{f9,,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{1c3,,fractions.Fraction}.

@item 
gh-111049@footnote{https://github.com/python/cpython/issues/111049}: Fix crash during garbage collection of the @ref{1255,,io.BytesIO}
buffer object.

@item 
gh-102980@footnote{https://github.com/python/cpython/issues/102980}: Redirect the output of @code{interact} command of @ref{aa,,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{6f8,,email.utils.getaddresses()} and
@ref{6f9,,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{1c33,,cmd.Cmd.do_help()} now cleans docstrings with
@ref{1c34,,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{1be1,,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{8b6,,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{13a,,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{bee,,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{73e,,pathlib.Path.owner()} and @ref{73f,,group()}, defaulting to
@code{True}.

@item 
gh-102130@footnote{https://github.com/python/cpython/issues/102130}: Support tab completion in @ref{1a,,cmd} for @code{editline}.

@item 
gh-99437@footnote{https://github.com/python/cpython/issues/99437}: @ref{6ae,,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{695,,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{1c35,,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{15da,,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{848,,getpass.getuser()} now raises @ref{53c,,OSError} for all
failures rather than @ref{1bd,,ImportError} on systems lacking the @ref{ba,,pwd}
module or @ref{7df,,KeyError} if the password database is empty.

@item 
bpo-34321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34321}: @ref{23c,,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{335,,shutil.rmtree()} function now ignores errors when
calling @ref{f31,,os.close()} when `ignore_errors' is @code{True}, and
@code{os.close()} no longer retried after error.

@item 
bpo-35928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35928}: @ref{b9c,,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{e20,,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{de2,,pickle.Pickler} and
@ref{1978,,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{184b,,warnings.filterwarnings()} and
@ref{aae,,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{335,,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 μεταβλητή περιβάλλοντος; PYTHON_HISTORY
@ref{6b9,,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{84b,,mailbox.Maildir} now ignores files with a leading dot.
@end itemize

@node Documentation<19>,Tests<21>,Library<67>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id272}@anchor{1c36}
@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{b,,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<21>,Build<20>,Documentation<19>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id273}@anchor{1c37}
@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{734,,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{8c3,,shutil.make_archive}.

@item 
gh-112769@footnote{https://github.com/python/cpython/issues/112769}: The tests now correctly compare zlib version when
@ref{1517,,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{df,,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<20>,Windows<18>,Tests<21>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id274}@anchor{1c38}
@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{1b71,,os.major()}, @ref{1b73,,os.makedev()}, and @ref{1b72,,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<18>,macOS<13>,Build<20>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id275}@anchor{1c39}
@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{4f5,,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{98,,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{af,,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{30e,,sys._enablelegacywindowsfsencoding()}. Use
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,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{23c,,mmap.mmap} when using a non-ASCII
`tagname' argument on Windows.
@end itemize

@node macOS<13>,IDLE<12>,Windows<18>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id276}@anchor{1c3a}
@subsubsection macOS



@itemize -

@item 
gh-113666@footnote{https://github.com/python/cpython/issues/113666}: Add the following constants to module @ref{d9,,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{1152,,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{37,,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<12>,C API<21>,macOS<13>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id277}@anchor{1c3b}
@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<21>,,IDLE<12>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id278}@anchor{1c3c}
@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{3b1,,PyArg_ParseTuple()}-like functions.

@item 
gh-111545@footnote{https://github.com/python/cpython/issues/111545}: Add @ref{638,,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{818,,PyArg_ParseTupleAndKeywords()} and
@ref{819,,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{1c3d}
@subsection Python 3.13.0 alpha 2


`Release date: 2023-11-22'

@menu
* Core and Builtins: Core and Builtins<65>. 
* Library: Library<68>. 
* Tests: Tests<22>. 
* Build: Build<21>. 
* Windows: Windows<19>. 
* macOS: macOS<14>. 
* IDLE: IDLE<13>. 
* Tools/Demos: Tools/Demos<16>. 
* C API: C API<22>. 

@end menu

@node Core and Builtins<65>,Library<68>,,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id279}@anchor{1c3e}
@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{1bf,,__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{784,,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{1c3f,,BaseExceptionGroup.derive()},
@ref{1c40,,BaseExceptionGroup.subgroup()}, and @ref{1af9,,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{7b3,,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{1d,,codeop} that was causing
@ref{17e,,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{44a,,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 μεταβλητή περιβάλλοντος; PYTHON_FROZEN_MODULES
@ref{6b6,,PYTHON_FROZEN_MODULES}. It determines whether or not frozen
modules are ignored by the import machinery, equivalent of the @ref{178,,-X frozen_modules} command-line option.

@item 
gh-111354@footnote{https://github.com/python/cpython/issues/111354}: Remove @code{oparg} from @ref{7b3,,YIELD_VALUE}. Change @code{oparg}
of @ref{7b4,,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{6b5,,global} declaration in an
@ref{447,,except} block is rejected when the global is used in the
@ref{320,,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{18fa,,MemoryError}
exceptions using the @ref{107,,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{18fa,,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 μεταβλητή περιβάλλοντος; 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{3dc,,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{69a,,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{6bb,,property}.  The core design of this feature was flawed and
caused a number of downstream problems.  To «pass-through» a
@code{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<68>,Tests<22>,Core and Builtins<65>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id280}@anchor{1c41}
@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{d4,,socket} module when
present in C at build time for use with @ref{1c42,,socket.getnameinfo()}.

@item 
gh-109538@footnote{https://github.com/python/cpython/issues/109538}: Issue warning message instead of having @ref{30d,,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{f06,,io.TextIOWrapper.reconfigure()} when pass
invalid arguments, e.g. non-string encoding.

@item 
gh-111460@footnote{https://github.com/python/cpython/issues/111460}: @ref{2e,,curses}: restore wide character support (including
@ref{1445,,curses.unget_wch()} and @ref{1444,,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{12d3,,contextlib.suppress} now supports suppressing
exceptions raised as part of a @ref{767,,BaseExceptionGroup}, in addition to
the recent support for @ref{6d8,,ExceptionGroup}.

@item 
gh-111835@footnote{https://github.com/python/cpython/issues/111835}: The @ref{23c,,mmap.mmap} class now has an
@ref{71d,,seekable()} method that can be used when a seekable
file-like object is required. The @ref{71e,,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{4e7,,os.putenv()} and @ref{4e8,,os.unsetenv()} on Windows.

@item 
gh-111768@footnote{https://github.com/python/cpython/issues/111768}: @ref{1c43,,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{1a78,,cmd.Cmd} in an
except block

@item 
gh-111541@footnote{https://github.com/python/cpython/issues/111541}: Fix @ref{3d,,doctest} for @ref{17e,,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{aa,,pdb}

@item 
gh-111482@footnote{https://github.com/python/cpython/issues/111482}: @ref{f7,,time}: Make @ref{1509,,time.clock_gettime()} and
@ref{ea9,,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{edd,,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{f9,,tkinter} widgets.

@item 
gh-111246@footnote{https://github.com/python/cpython/issues/111246}: @ref{6d0,,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{1c44,,io.text_encoding()}, @ref{1c45,,io.DEFAULT_BUFFER_SIZE},
and @ref{1947,,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{575,,pathlib.PurePath.relative_to()} and
@ref{576,,is_relative_to()}.

@item 
gh-111342@footnote{https://github.com/python/cpython/issues/111342}: Fixed typo in @ref{8a8,,math.sumprod()}.

@item 
gh-68166@footnote{https://github.com/python/cpython/issues/68166}: Remove mention of not supported «vsapi» element type in
@ref{760,,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{c26,,traceback.format_exception_only()}, which allows to format
@ref{6d8,,ExceptionGroup} instances.

@item 
gh-79033@footnote{https://github.com/python/cpython/issues/79033}: Another attempt at fixing @ref{1c46,,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{a8,,pathlib}.

@item 
gh-111295@footnote{https://github.com/python/cpython/issues/111295}: Fix @ref{f7,,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{c9,,select} not checking for errors when initializing.

@item 
gh-111230@footnote{https://github.com/python/cpython/issues/111230}: Fix @ref{d8,,ssl} not checking for errors when initializing.

@item 
gh-111174@footnote{https://github.com/python/cpython/issues/111174}: Fix crash in @ref{159a,,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{3d,,doctest} output comparison for exceptions with notes.

@item 
gh-110910@footnote{https://github.com/python/cpython/issues/110910}: Fix invalid state handling in @ref{6d7,,asyncio.TaskGroup} and
@ref{1c47,,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{aa,,pdb} completion

@item 
gh-110745@footnote{https://github.com/python/cpython/issues/110745}: Added `newline' parameter to @ref{11f6,,pathlib.Path.read_text()}.
Patch by Junya Okabe.

@item 
gh-84583@footnote{https://github.com/python/cpython/issues/84583}: Make @ref{aa,,pdb} enter post-mortem mode even for
@ref{17e,,SyntaxError}

@item 
gh-80675@footnote{https://github.com/python/cpython/issues/80675}: Set @code{f_trace_lines = True} on all frames upon
@ref{4fa,,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{30a,,asyncio.Runner} loop_factory kwarg
in @ref{342,,unittest.IsolatedAsyncioTestCase}

@item 
gh-110392@footnote{https://github.com/python/cpython/issues/110392}: Fix @ref{1c48,,tty.setraw()} and @ref{1bfd,,tty.setcbreak()}: previously
they returned partially modified list of the original tty attributes.
@ref{1c49,,tty.cfmakeraw()} and @ref{1bfe,,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{aa,,pdb}

@item 
gh-88434@footnote{https://github.com/python/cpython/issues/88434}: Emit deprecation warning for non-integer numbers in
@ref{66,,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{269,,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{70f,,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{e1,,symtable} module and improve the
repr of @ref{511,,Symbol}.

@item 
gh-108791@footnote{https://github.com/python/cpython/issues/108791}: Improved error handling in @ref{aa,,pdb} command line interface,
making it produce more concise error messages.

@item 
gh-105931@footnote{https://github.com/python/cpython/issues/105931}: Change @ref{21,,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{9b,,multiprocessing.managers} @ref{a9f,,Generic Alias Types} for @code{[]} use in typing contexts.

@item 
gh-72904@footnote{https://github.com/python/cpython/issues/72904}: Add @ref{700,,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{a5,,os} module become available.

@item 
gh-90890@footnote{https://github.com/python/cpython/issues/90890}: New methods @ref{1c4a,,mailbox.Maildir.get_info()},
@ref{1c4b,,mailbox.Maildir.set_info()}, @ref{1c4c,,mailbox.Maildir.get_flags()},
@ref{1c4d,,mailbox.Maildir.set_flags()}, @ref{1c4e,,mailbox.Maildir.add_flag()},
@ref{1c4f,,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{1ab4,,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{72,,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<22>,Build<21>,Library<68>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id281}@anchor{1c50}
@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{ed,,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{cf,,site}.
@end itemize

@node Build<21>,Windows<19>,Tests<22>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id282}@anchor{1c51}
@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{829,,limited C API}. Patch by Victor
Stinner.
@end itemize

@node Windows<19>,macOS<14>,Build<21>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id283}@anchor{1c52}
@subsubsection Windows



@itemize -

@item 
gh-111856@footnote{https://github.com/python/cpython/issues/111856}: Fixes @ref{1145,,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{1c53,,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<14>,IDLE<13>,Windows<19>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id284}@anchor{1c54}
@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{1bb6,,tkinter.Tk()} instance
is destroyed.
@end itemize

@node IDLE<13>,Tools/Demos<16>,macOS<14>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id285}@anchor{1c55}
@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<16>,C API<22>,IDLE<13>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id286}@anchor{1c56}
@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<22>,,Tools/Demos<16>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id287}@anchor{1c57}
@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{636,,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{635,,PyDict_Pop()} and @ref{7dd,,PyDict_PopString()}
functions: remove a key from a dictionary and optionally return the
removed value. This is similar to @ref{7de,,dict.pop()}, but without the
default value and not raising @ref{7df,,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{7f6,,PyList_Extend()} and @ref{7f7,,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{c7e,,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{7e7,,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{818,,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{808,,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{2bf,,PyMem_RawMalloc()}, @ref{824,,PyMem_RawCalloc()},
@ref{825,,PyMem_RawRealloc()} and @ref{826,,PyMem_RawFree()} to the limited C
API. Patch by Victor Stinner.

@item 
gh-106672@footnote{https://github.com/python/cpython/issues/106672}: Functions @ref{81c,,PyDict_GetItem()},
@ref{81d,,PyDict_GetItemString()}, @ref{814,,PyMapping_HasKey()},
@ref{816,,PyMapping_HasKeyString()}, @ref{810,,PyObject_HasAttr()},
@ref{812,,PyObject_HasAttrString()}, and @ref{356,,PySys_GetObject()}, which
clear all errors occurred during calling the function, report now them
using @ref{70c,,sys.unraisablehook()}.

@item 
gh-67565@footnote{https://github.com/python/cpython/issues/67565}: Remove redundant C-contiguity check in @code{getargs.c},
@ref{11,,binascii}, @ref{d8,,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{1c58}
@subsection Python 3.13.0 alpha 1


`Release date: 2023-10-13'

@menu
* Security: Security<20>. 
* Core and Builtins: Core and Builtins<66>. 
* Library: Library<69>. 
* Documentation: Documentation<20>. 
* Tests: Tests<23>. 
* Build: Build<22>. 
* Windows: Windows<20>. 
* macOS: macOS<15>. 
* IDLE: IDLE<14>. 
* Tools/Demos: Tools/Demos<17>. 
* C API: C API<23>. 

@end menu

@node Security<20>,Core and Builtins<66>,,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id288}@anchor{1c59}
@subsubsection Security



@itemize -

@item 
gh-108310@footnote{https://github.com/python/cpython/issues/108310}: Fixed an issue where instances of @ref{cbb,,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{53,,email.utils} security improvement change
released in 3.12beta4 that unintentionally caused
@ref{6f8,,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{6b,,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{5cb,,PyLongObject} objects. Patch by Illia Volochii.
@end itemize

@node Core and Builtins<66>,Library<69>,Security<20>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id289}@anchor{1c5a}
@subsubsection Core and Builtins



@itemize -

@item 
gh-110782@footnote{https://github.com/python/cpython/issues/110782}: Fix crash when @ref{294,,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{107,,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{42b,,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 μεταβλητή περιβάλλοντος; PYTHONUOPS
@code{PYTHONUOPS} or
@ref{178,,-X uops} enabled.

@item 
gh-110514@footnote{https://github.com/python/cpython/issues/110514}: Add @code{PY_THROW} to @ref{18a0,,sys.setprofile()} events

@item 
gh-110489@footnote{https://github.com/python/cpython/issues/110489}: Optimise @ref{1761,,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 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{178,,-X cpu_count}  command line option to
override return results of @ref{6e1,,os.cpu_count()} and
@ref{6e0,,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{975,,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{1c5b,,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{598,,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{17e,,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{5a1,,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 μεταβλητή περιβάλλοντος; PYTHONUOPS
@code{PYTHONUOPS} or
@ref{178,,-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{af8,,JUMP_BACKWARD} at the end
of a for loop.

@item 
gh-108113@footnote{https://github.com/python/cpython/issues/108113}: The @ref{1c8,,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{1c9,,ast.parse()} now accepts an optional argument @code{optimize} which is
passed on to the @ref{1c8,,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 μεταβλητή περιβάλλοντος; PYTHONUOPS
@code{PYTHONUOPS} or @ref{178,,-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{1876,,METH_NOARGS} and
@ref{18a9,,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{1c5c,,ctypes.pointer()} and
@ref{484,,ctypes.POINTER()}.

@item 
gh-105848@footnote{https://github.com/python/cpython/issues/105848}: Modify the bytecode so that the actual callable for a
@ref{af3,,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{1df,,str} objects by @ref{326,,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{1c5d,,ctypes.c_char_p}, @ref{1c5e,,ctypes.c_wchar_p} and
@ref{1c5f,,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 μεταβλητή περιβάλλοντος; PYTHONUOPS
@code{PYTHONUOPS} or @ref{178,,-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{69,,grp} and
@ref{d4,,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 @code{dbm.ndbm.ndbm.clear()} to @ref{37,,dbm.ndbm}. Patch By
Donghee Na.

@item 
gh-107122@footnote{https://github.com/python/cpython/issues/107122}: Add @code{dbm.gnu.gdbm.clear()} to @ref{36,,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{1c9,,ast.parse()}.

@item 
gh-106917@footnote{https://github.com/python/cpython/issues/106917}: Fix classmethod-style @ref{443,,super()} method calls (i.e., where
the second argument to @code{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 μεταβλητή περιβάλλοντος; PYTHONUOPS
@code{PYTHONUOPS} or
@ref{178,,-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{1c60,,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{6c0,,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 @ref{1c61,,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{1c62,,ast.JoinedStr} node for
it instead of an one-element @code{ast.JoinedStr} with an empty string
@ref{569,,ast.Constant}.

@item 
gh-100288@footnote{https://github.com/python/cpython/issues/100288}: Specialize @ref{8ed,,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{a65,,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{1017,,sys.getfilesystemencoding()} and
@ref{10a3,,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{1c63,,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{1af9,,BaseExceptionGroup.split()} and
@ref{1c40,,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{1c64,,TO_BOOL} instruction, which performs boolean
conversions for @ref{1c65,,POP_JUMP_IF_TRUE}, @ref{1c66,,POP_JUMP_IF_FALSE},
and @ref{1c67,,UNARY_NOT} (which all expect exact @ref{5ef,,bool} values now).
Also, modify the oparg of @ref{d32,,COMPARE_OP} to include an optional
«boolean conversion» flag.

@item 
gh-98931@footnote{https://github.com/python/cpython/issues/98931}: Ensure custom @ref{17e,,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{44a,,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{277,,ValueError} if the @code{delay} argument to
@ref{e33,,asyncio.sleep()} is a NaN (matching @ref{a8c,,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{104,,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{9,,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{13,,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 @ref{1c68,,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{94f,,tokenize.TokenError} exceptions instead
of @ref{17e,,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{104,,tokenize} module. Patch by Pablo Galindo

@item 
gh-104635@footnote{https://github.com/python/cpython/issues/104635}: Eliminate redundant @ref{1c69,,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{104,,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{6bb,,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{1a9,,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{1d4,,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{9,,ast} nodes that are lists now default to
the empty list if omitted. This means that some code that previously
raised @ref{291,,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{443,,super()} calls on types with custom
@ref{1c6a,,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{1a04,,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{104,,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{104,,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{1c6b,,__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{6bd,,os.fork()} during interpreter shutdown (such as from @ref{d,,atexit}
handlers) is no longer supported.  It can lead to race condition between
the main Python runtime thread freeing thread states while internal
@ref{f6,,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{104,,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{199e,,generator.close()}.

@item 
gh-89091@footnote{https://github.com/python/cpython/issues/89091}: Raise @ref{6dd,,RuntimeWarning} for unawaited async generator
methods like @ref{cab,,asend()}, @ref{906,,athrow()} and
@ref{caa,,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{1b7e,,__reduce_ex__()} or @ref{d97,,__reduce__()} to
@code{None}, pickling will result in a @ref{291,,TypeError}.

@item 
gh-101006@footnote{https://github.com/python/cpython/issues/101006}: Improve error handling when read @ref{90,,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<69>,Documentation<20>,Core and Builtins<66>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id290}@anchor{1c6c}
@subsubsection Library



@itemize -

@item 
gh-110786@footnote{https://github.com/python/cpython/issues/110786}: @ref{e4,,sysconfig}’s CLI now ignores @ref{1404,,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{e4,,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{1c6d,,asyncio.EventLoop} for use with the
@ref{309,,asyncio.run()} `loop_factory' kwarg to avoid calling the asyncio
policy system.

@item 
gh-110682@footnote{https://github.com/python/cpython/issues/110682}: @ref{861,,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{1c6e,,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{291,,TypeError} would
be overwritten by @ref{c57,,OverflowError} when the `code' argument was a list
of non-ints.

@item 
gh-65052@footnote{https://github.com/python/cpython/issues/65052}: Prevent @ref{aa,,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{66,,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{1c2,,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{20e,,contextmanager()} and
@ref{20f,,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{aa,,pdb}, set convenience variable @code{$_exception} for
post mortem debugging.

@item 
gh-110365@footnote{https://github.com/python/cpython/issues/110365}: Fix @ref{1c6f,,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{11b,,warnings} within those modules.
Patch by Alex Waygood.

@item 
gh-110273@footnote{https://github.com/python/cpython/issues/110273}: @ref{1c70,,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{c0,,random}. Patch by Alex Waygood.

@item 
gh-110222@footnote{https://github.com/python/cpython/issues/110222}: Add support of struct sequence objects in @ref{45a,,copy.replace()}.
Patched by Xuehai Pan.

@item 
gh-109649@footnote{https://github.com/python/cpython/issues/109649}: @ref{98,,multiprocessing}, @ref{24,,concurrent.futures},
@ref{21,,compileall}: Replace @ref{6e1,,os.cpu_count()} with
@ref{6e0,,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{10f9,,PermissionError} and get the process exit code. If the process is
still running, raise again the @code{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{e1,,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{51e,,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{c1,,re} functions such as @ref{13d2,,re.findall()},
@ref{7a0,,re.split()}, @ref{15d3,,re.search()} and @ref{7a1,,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{53,,email.utils} by around 43%.
This results in the import time of @ref{47,,email.message} falling by around
18%, which in turn reduces the import time of @ref{7d,,importlib.metadata} by
around 6%. Patch by Alex Waygood.

@item 
gh-109818@footnote{https://github.com/python/cpython/issues/109818}: Fix @ref{159c,,reprlib.recursive_repr()} not copying
@code{__type_params__} from decorated function.

@item 
gh-109047@footnote{https://github.com/python/cpython/issues/109047}: @ref{24,,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{30d,,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{dd4,,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{62,,functools} by around 13%. Patch by
Alex Waygood.

@item 
gh-109590@footnote{https://github.com/python/cpython/issues/109590}: @ref{8c4,,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 @code{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{59,,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{10d,,typing} by around a third.
Patch by Alex Waygood.

@item 
gh-109649@footnote{https://github.com/python/cpython/issues/109649}: Add @ref{6e0,,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{4f5,,os.stat()} and @ref{1c71,,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{1b6f,,ssl.SSLSocket.get_verified_chain()} and
@ref{1b70,,ssl.SSLSocket.get_unverified_chain()} methods.

Contributed by Mateusz Nowak.

@item 
gh-109559@footnote{https://github.com/python/cpython/issues/109559}: Update @ref{10e,,unicodedata} database to Unicode 15.1.0.

@item 
gh-109543@footnote{https://github.com/python/cpython/issues/109543}: Remove unnecessary @ref{8e2,,hasattr()} check during
@ref{290,,typing.TypedDict} creation.

@item 
gh-109495@footnote{https://github.com/python/cpython/issues/109495}: Remove unnecessary extra @code{__slots__} in
@ref{6e7,,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{8a,,logging}: Use a context manager for lock acquisition.

@item 
gh-109096@footnote{https://github.com/python/cpython/issues/109096}: @code{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{aa,,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{1c72,,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{1c73,,pathlib.Path.resolve()} now treats symlink loops like
other errors: in strict mode, @ref{53c,,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{1c,,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{6ea,,types.SimpleNamespace} in
@ref{45a,,copy.replace()}.

@item 
gh-109164@footnote{https://github.com/python/cpython/issues/109164}: @ref{aa,,pdb}: Replace @ref{64,,getopt} with @ref{7,,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{257,,sqlite3 command-line interface} (@code{python -m sqlite3}).

@item 
gh-108987@footnote{https://github.com/python/cpython/issues/108987}: Fix @ref{6bc,,_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{cb6,,ast.unparse()} when unparsing f-strings
containing many quote types.

@item 
gh-108469@footnote{https://github.com/python/cpython/issues/108469}: @ref{cb6,,ast.unparse()} now supports new @ref{858,,f-string} syntax
introduced in Python 3.12. Note that the 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{45a,,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{291,,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{3df,,sqlite3.Connection} APIs:


@itemize *

@item 
@ref{3e3,,set_authorizer()}

@item 
@ref{3e4,,set_progress_handler()}

@item 
@ref{3e5,,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{294,,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{722,,os.timerfd_create()}, @ref{723,,os.timerfd_settime()},
@ref{725,,os.timerfd_gettime()}, @ref{724,,os.timerfd_settime_ns()}, and
@ref{726,,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{e7,,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{751,,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{a8c,,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{3df,,sqlite3.Connection} APIs:


@itemize *

@item 
@ref{3e1,,create_function()}

@item 
@ref{3e2,,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{9d5,,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{3df,,sqlite3.Connection} and
@ref{750,,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{d7,,sqlite3} now emits an @ref{74f,,ResourceWarning} if a
@ref{3df,,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{94e,,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{3d,,doctest} module. Patch by Tyler Smart.

@item 
gh-107963@footnote{https://github.com/python/cpython/issues/107963}: Fix @ref{1969,,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{16be,,os.path.normpath()} to handle embedded null
characters without truncating the path.

@item 
gh-81555@footnote{https://github.com/python/cpython/issues/81555}: @ref{12b,,xml.dom.minidom} now only quotes @code{"} in attributes.

@item 
gh-50002@footnote{https://github.com/python/cpython/issues/50002}: @ref{12b,,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{3e0,,sqlite3.connect()} and the @ref{3df,,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{169a,,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{53c,,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{279,,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{10a,,turtle}.

@item 
gh-107782@footnote{https://github.com/python/cpython/issues/107782}: @ref{bd,,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{7a0,,re.split()}, @ref{7a1,,re.sub()} and
@ref{7a2,,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{1c74,,logging.getHandlerNames()}.

@item 
gh-107715@footnote{https://github.com/python/cpython/issues/107715}: Fix @ref{1c75,,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{f9,,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{74f,,ResourceWarning} when @ref{1c76,,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{737,,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{8de,,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{159c,,reprlib.recursive_repr()}.

@item 
gh-107406@footnote{https://github.com/python/cpython/issues/107406}: Implement new @code{__repr__()} method for
@ref{2fb,,struct.Struct}. Now it returns @code{Struct(<format repr>)}.

@item 
gh-107369@footnote{https://github.com/python/cpython/issues/107369}: Optimize @ref{77d,,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{4f6,,pathlib.Path.iterdir()} did not raise
@ref{53c,,OSError} until iterated.

@item 
gh-105578@footnote{https://github.com/python/cpython/issues/105578}: Deprecate @ref{7a4,,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{db8,,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{1c77,,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{b,,asyncio}
@ref{ed3,,os.sendfile()} implementation.

@item 
gh-83006@footnote{https://github.com/python/cpython/issues/83006}: Document behavior of @ref{14d9,,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{1546,,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{277,,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{3b,,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{1a04,,inspect.getsource()} smarter for class for same name
definitions

@item 
gh-106789@footnote{https://github.com/python/cpython/issues/106789}: Remove import of @ref{b3,,pprint} from @ref{e4,,sysconfig}.

@item 
gh-105726@footnote{https://github.com/python/cpython/issues/105726}: Added @code{__slots__} to
@ref{104d,,contextlib.AbstractContextManager} and
@ref{eeb,,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{ca,,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{d8,,ssl} module.

@item 
gh-106734@footnote{https://github.com/python/cpython/issues/106734}: Disable tab completion in multiline mode of @ref{aa,,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{59,,enum}

@item 
gh-106664@footnote{https://github.com/python/cpython/issues/106664}: @ref{ca,,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{11a,,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{1c78,,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{ca,,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{a6,,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{b,,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{c1,,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{294,,typing.TypeVar},
@ref{295,,typing.ParamSpec}, @ref{ba6,,typing.ParamSpecArgs},
@ref{ba7,,typing.ParamSpecKwargs}, and @ref{293,,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{94e,,functools.cached_property()}. This better matches the
pre-3.12 behavior and improves compatibility for users subclassing
@code{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{8bc,,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 @code{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{1bd,,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{f6,,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 @code{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{1011,,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{b,,asyncio}
eager task factory internal routines.

@item 
gh-105974@footnote{https://github.com/python/cpython/issues/105974}: Fix bug where a @ref{76c,,typing.Protocol} class that had one or
more non-callable members would raise @ref{291,,TypeError} when
@ref{2f0,,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 @code{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{736,,pathlib.UnsupportedOperation}, which is raised instead
of @ref{59a,,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{12dc,,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{cb6,,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{73d,,pathlib.Path.is_dir()} and @ref{73c,,is_file()}, defaulting
to @code{True}.

@item 
gh-105570@footnote{https://github.com/python/cpython/issues/105570}: Deprecate two methods of creating @ref{290,,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{2d,,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{da1,,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{1c79,,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{e2,,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{39,,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{6c5,,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{b2,,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{13d,,zoneinfo} where exceptions could be
overwritten.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bugs in @ref{5a,,errno} where exceptions could be overwritten.

@item 
gh-105566@footnote{https://github.com/python/cpython/issues/105566}: Deprecate creating a @ref{2e4,,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{d09,,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{10d,,typing} module public API.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bugs in @ref{ab,,pickle} where exceptions could be
overwritten.

@item 
gh-70303@footnote{https://github.com/python/cpython/issues/70303}: Emit @ref{847,,FutureWarning} from @ref{73a,,pathlib.Path.glob()} and
@ref{73b,,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{d7,,sqlite3} where an exception could be
overwritten in the @ref{a66,,collation}
callback.

@item 
gh-105382@footnote{https://github.com/python/cpython/issues/105382}: Remove `cafile', `capath' and `cadefault' parameters of the
@ref{57f,,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{8a,,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{1c7a,,logging.Logger.warning()} method,
@code{logging.LoggerAdapter.warning()} method and @ref{331,,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{c26,,traceback.format_exception_only()} to
recurse into the nested exception of a @ref{767,,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{76c,,typing.Protocol} in Python 3.12.

@item 
gh-80480@footnote{https://github.com/python/cpython/issues/80480}: @ref{8,,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{4bd,,inspect.signature()}

@item 
gh-105144@footnote{https://github.com/python/cpython/issues/105144}: Fix a recent regression in the @ref{10d,,typing} module. The
regression meant that doing @code{class Foo(X, typing.Protocol)}, where @code{X}
was a class that had @ref{12c9,,abc.ABCMeta} as its metaclass, would then
cause subsequent @code{isinstance(1, X)} calls to erroneously raise
@ref{291,,TypeError}. Patch by Alex Waygood.

@item 
gh-62948@footnote{https://github.com/python/cpython/issues/62948}: The @ref{70a,,io.IOBase} finalizer now logs the @code{close()} method
errors with @ref{70c,,sys.unraisablehook}. Previously, errors were ignored
silently by default, and only logged in @ref{70d,,Python Development Mode} or on @ref{3dc,,Python built on debug mode}.  Patch
by Victor Stinner.

@item 
gh-105096@footnote{https://github.com/python/cpython/issues/105096}: @ref{11c,,wave}: Deprecate the @code{getmark()}, @code{setmark()} and
@code{getmarkers()} methods of the @ref{2e6,,wave.Wave_read} and
@ref{2e7,,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{8b6,,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{1c7b,,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{861,,typing.runtime_checkable()} and @ref{19f2,,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{188d,,__slots__} to @ref{100f,,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{290,,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{76b,,typing.get_protocol_members()} to return the set of
members defining a @ref{76c,,typing.Protocol}.  Add
@ref{76d,,typing.is_protocol()} to check whether a class is a
@code{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{10b1,,typing.NewType}. Patch by Jelle Zijlstra.

@item 
gh-104835@footnote{https://github.com/python/cpython/issues/104835}: Removed the following @ref{10f,,unittest} functions, deprecated in
Python 3.11:


@itemize *

@item 
@code{unittest.findTestCases()}

@item 
@code{unittest.makeSuite()}

@item 
@code{unittest.getTestCaseNames()}
@end itemize

Use @ref{792,,TestLoader} methods instead:


@itemize *

@item 
@ref{793,,unittest.TestLoader.loadTestsFromModule()}

@item 
@ref{794,,unittest.TestLoader.loadTestsFromTestCase()}

@item 
@ref{795,,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{11e,,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{4ee,,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{1c7c,,ast.ClassDef}, @ref{1c7d,,ast.AsyncFunctionDef}, and
@ref{1c7e,,ast.FunctionDef} to better preserve backward compatibility. Patch
by Jelle Zijlstra

@item 
gh-104797@footnote{https://github.com/python/cpython/issues/104797}: Allow @ref{76c,,typing.Protocol} classes to inherit from
@ref{312,,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{df,,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{6b,,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{73a,,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{e23,,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{494,,dis.Instruction}.

@item 
gh-103558@footnote{https://github.com/python/cpython/issues/103558}: Fixed @code{parent} argument validation mechanism of
@ref{7,,argparse}. Improved test coverage.

@item 
gh-103464@footnote{https://github.com/python/cpython/issues/103464}: Provide helpful usage messages when parsing incorrect
@ref{aa,,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{aa,,pdb}

@item 
gh-101162@footnote{https://github.com/python/cpython/issues/101162}: Forbid using @code{builtins.issubclass()} with
@ref{bc7,,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{73a,,pathlib.Path.glob()} and
@ref{73b,,rglob()}, defaulting to false.

@item 
gh-102541@footnote{https://github.com/python/cpython/issues/102541}: Hide traceback in @ref{ca9,,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{2df,,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{8bc,,pathlib.PurePath.match()}.

@item 
gh-84867@footnote{https://github.com/python/cpython/issues/84867}: @ref{792,,unittest.TestLoader} no longer loads test cases from
exact @ref{52f,,unittest.TestCase} and @ref{1c7f,,unittest.FunctionTestCase}
classes.

@item 
gh-99203@footnote{https://github.com/python/cpython/issues/99203}: Restore following CPython <= 3.10.5 behavior of
@ref{8c3,,shutil.make_archive()}: do not create an empty archive if
@code{root_dir} is not a directory, and, in that case, raise
@ref{243,,FileNotFoundError} or @ref{1402,,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{2c9,,DeprecationWarning} for @ref{8,,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{1b4e,,unittest.mock.create_autospec()} now properly returns
coroutine functions compatible with @ref{302,,inspect.iscoroutinefunction()}

@item 
gh-94777@footnote{https://github.com/python/cpython/issues/94777}: Fix hanging @ref{98,,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{10d,,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{83,,ipaddress}. Patch
by Oleksandr Pavliuk.

@item 
bpo-44850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44850}: Improve performance of @ref{11e7,,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{1390,,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{21e,,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{110,,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{110,,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<20>,Tests<23>,Library<69>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id291}@anchor{1c80}
@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{3b,,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{973,,PyInterpreterConfig} and
@ref{876,,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{2e,,curses} module variables
@ref{11a4,,LINES} and @ref{11a5,,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{db3,,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{764,,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{764,,traceback.TracebackException}
class.

@item 
gh-104943@footnote{https://github.com/python/cpython/issues/104943}: Remove mentions of old Python versions in
@ref{2e4,,typing.NamedTuple}.

@item 
gh-54738@footnote{https://github.com/python/cpython/issues/54738}: Add documentation on how to localize the @ref{7,,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{327,,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<23>,Build<22>,Documentation<20>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id292}@anchor{1c81}
@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{109,,tty}.

@item 
gh-81002@footnote{https://github.com/python/cpython/issues/81002}: Add tests for @ref{ea,,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{a8c,,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{1618,,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{ed,,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{6f3,,doctest.DocTestRunner.run()} method now counts the
number of skipped tests. Add @ref{6f4,,doctest.DocTestRunner.skips} and
@ref{6f5,,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{1c82,,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{15,,calendar} to achieve full test
coverage.
@end itemize

@node Build<22>,Windows<20>,Tests<23>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id293}@anchor{1c83}
@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 μεταβλητή περιβάλλοντος; PROFILE_TASK
@ref{1c84,,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{828,,--with-trace-refs}
(tracing references) is now ABI compatible with Python release build and
@ref{3dc,,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{829,,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{d7,,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<20>,macOS<15>,Build<22>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id294}@anchor{1c85}
@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{241,,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{241,,realpath()} to behave consistently when
passed a path containing an embedded null character on Windows. In strict
mode, it now raises @ref{53c,,OSError} instead of the unexpected
@ref{277,,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{9bc,,Διαχειριστής εγκατάστασης Python} 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{e1f,,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{4f5,,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{1bcc,,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<15>,IDLE<14>,Windows<20>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id295}@anchor{1c86}
@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<14>,Tools/Demos<17>,macOS<15>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id296}@anchor{1c87}
@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<17>,C API<23>,IDLE<14>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id297}@anchor{1c88}
@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{829,,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<23>,,Tools/Demos<17>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id298}@anchor{1c89}
@subsubsection C API



@itemize -

@item 
gh-85283@footnote{https://github.com/python/cpython/issues/85283}: If the @ref{84d,,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{80d,,PyUnicode_EqualToUTF8AndSize()} and
@ref{80e,,PyUnicode_EqualToUTF8()} functions.

@item 
gh-110235@footnote{https://github.com/python/cpython/issues/110235}: Raise @ref{291,,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{1c8a,,PyImport_GetImporter()} now sets RuntimeError if it
fails to get @ref{13cd,,sys.path_hooks} or @ref{9db,,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{693,,PyMutex} internal-only lightweight locking API.

@item 
gh-85283@footnote{https://github.com/python/cpython/issues/85283}: Add @ref{807,,PySys_AuditTuple()} function: similar to
@ref{808,,PySys_Audit()}, but pass event arguments as a Python @ref{1ce,,tuple}
object.  Patch by Victor Stinner.

@item 
gh-108867@footnote{https://github.com/python/cpython/issues/108867}: Add @ref{636,,PyThreadState_GetUnchecked()} function: similar to
@ref{809,,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{80f,,PyObject_HasAttrWithError()},
@ref{811,,PyObject_HasAttrStringWithError()},
@ref{813,,PyMapping_HasKeyWithError()} and
@ref{815,,PyMapping_HasKeyStringWithError()}.

@item 
gh-107073@footnote{https://github.com/python/cpython/issues/107073}: Add @ref{803,,PyObject_VisitManagedDict()} and
@ref{804,,PyObject_ClearManagedDict()} functions which must be called by the
traverse and clear functions of a type using
@ref{39c,,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{828,,--with-trace-refs}
(tracing references) now supports the @ref{829,,Limited API}.
Patch by Victor Stinner.

@item 
gh-108014@footnote{https://github.com/python/cpython/issues/108014}: Add @ref{7fa,,PyLong_AsInt()} function: similar to
@ref{7fb,,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{7d6,,PyDict_ContainsString()} function: same as
@ref{7d7,,PyDict_Contains()}, but `key' is specified as a const char* UTF-8 encoded bytes string, rather than a @ref{19b,,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{7f3,,Py_IsFinalizing()} function: check if the main
Python interpreter is @ref{1a0,,shutting down}. Patch
by Victor Stinner.

@item 
gh-107916@footnote{https://github.com/python/cpython/issues/107916}: C API functions @ref{1c8b,,PyErr_SetFromErrnoWithFilename()},
@ref{1c8c,,PyErr_SetExcFromWindowsErrWithFilename()} and
@ref{1c8d,,PyErr_SetFromWindowsErrWithFilename()} save now the error code
before calling @ref{1c8e,,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{2c9,,DeprecationWarning} for uses of
@ref{1c8f,,PyType_Spec} with metaclasses that have custom @code{tp_new}.

@item 
gh-107249@footnote{https://github.com/python/cpython/issues/107249}: Implement the @ref{1c90,,Py_UNUSED} macro for Windows MSVC
compiler. Patch by Victor Stinner.

@item 
gh-107226@footnote{https://github.com/python/cpython/issues/107226}: @ref{800,,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{637,,PyUnicode_AsUTF8()}. It was kept for backward compatibility with
Python 3.0 - 3.2. The @code{PyUnicode_AsUTF8()} is available since Python
3.3. The @ref{1537,,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{1a6d,,PyObject_DelAttr()} and
@ref{1a6e,,PyObject_DelAttrString()} macros to functions. Patch by Victor
Stinner.

@item 
gh-106307@footnote{https://github.com/python/cpython/issues/106307}: Add @ref{7e0,,PyMapping_GetOptionalItem()} function.

@item 
gh-106521@footnote{https://github.com/python/cpython/issues/106521}: Add @ref{7e4,,PyObject_GetOptionalAttr()} and
@ref{7e5,,PyObject_GetOptionalAttrString()} functions.

@item 
gh-106320@footnote{https://github.com/python/cpython/issues/106320}: Remove @code{_PyInterpreterState_Get()} alias to
@ref{83b,,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{3dc,,debug mode} or
@ref{820,,with assertions}, @ref{821,,PyTuple_SET_ITEM()}
and @ref{822,,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{7d8,,PyDict_GetItemRef()} and
@ref{634,,PyDict_GetItemStringRef()} functions: similar to
@ref{7d9,,PyDict_GetItemWithError()} but returning a @ref{7da,,strong reference}
instead of a @ref{603,,borrowed reference}. Patch by Victor Stinner.

@item 
gh-105927@footnote{https://github.com/python/cpython/issues/105927}: Deprecate the @code{PyWeakref_GetObject()} and
@code{PyWeakref_GET_OBJECT()} functions: use the new
@ref{3a4,,PyWeakref_GetRef()} function instead. Patch by Victor Stinner.

@item 
gh-105927@footnote{https://github.com/python/cpython/issues/105927}: Add @ref{3a4,,PyWeakref_GetRef()} function: similar to
@code{PyWeakref_GetObject()} but returns a @ref{7da,,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{7f1,,PyImport_AddModuleRef()}: similar to
@ref{7f2,,PyImport_AddModule()}, but return a @ref{7da,,strong reference}
instead of a @ref{603,,borrowed reference}. Patch by Victor Stinner.

@item 
gh-105227@footnote{https://github.com/python/cpython/issues/105227}: The new @ref{1c91,,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{1c92,,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{1c93,,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{974,,Py_INCREF()} and
@ref{975,,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 @code{PyImport_ImportModuleNoBlock()} function
which is just an alias to @ref{3a3,,PyImport_ImportModule()} since Python
3.3. Patch by Victor Stinner.

@item 
gh-103968@footnote{https://github.com/python/cpython/issues/103968}: @ref{391,,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 
@code{PySys_ResetWarnOptions()}

@item 
@code{Py_GetExecPrefix()}

@item 
@code{Py_GetPath()}

@item 
@code{Py_GetPrefix()}

@item 
@code{Py_GetProgramFullPath()}

@item 
@code{Py_GetProgramName()}

@item 
@code{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{82c,,PyObject_GetBuffer()} and @ref{82d,,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{82e,,PyObject_CallNoArgs()} and @ref{82f,,PyObject_Call()} (positional
arguments must not be `NULL') instead.

@item 
@code{PyEval_CallFunction()}: use @ref{831,,PyObject_CallFunction()} instead.

@item 
@code{PyEval_CallMethod()}: use @ref{3b6,,PyObject_CallMethod()} instead.

@item 
@code{PyCFunction_Call()}: use @ref{82f,,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{448,,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{3b1,,PyArg_ParseTuple()} and
@ref{5ee,,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{986,,PyOS_InputHook} or
@ref{987,,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{7ff,,PyModule_Add()} function: similar to
@ref{800,,PyModule_AddObjectRef()} and @ref{801,,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{5ee,,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{1c94}
@subsection Python 3.12.0 beta 1


`Release date: 2023-05-22'

@menu
* Security: Security<21>. 
* Library: Library<70>. 
* Core and Builtins: Core and Builtins<67>. 
* Library: Library<71>. 
* Core and Builtins: Core and Builtins<68>. 
* Library: Library<72>. 
* Documentation: Documentation<21>. 
* Tests: Tests<24>. 
* Build: Build<23>. 
* Windows: Windows<21>. 
* macOS: macOS<16>. 
* IDLE: IDLE<15>. 
* Tools/Demos: Tools/Demos<18>. 
* C API: C API<24>. 

@end menu

@node Security<21>,Library<70>,,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id299}@anchor{1c95}
@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{6b,,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{2a3,,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 Library<70>,Core and Builtins<67>,Security<21>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id300}@anchor{1c96}
@subsubsection Library



@itemize -

@item 
gh-102856@footnote{https://github.com/python/cpython/issues/102856}: Implement PEP 701 changes in the @ref{104,,tokenize} module. Patch
by Marta Gómez Macías and Pablo Galindo Salgado
@end itemize

@node Core and Builtins<67>,Library<71>,Library<70>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id301}@anchor{1c97}
@subsubsection Core and Builtins



@itemize -

@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{6b3,,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{4d9,,list} or @ref{1ce,,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{812,,PyObject_HasAttrString()}

@item 
gh-104066@footnote{https://github.com/python/cpython/issues/104066}: Improve the performance of @ref{8e2,,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{fcc,,True}, @ref{ef5,,False}, and @ref{a65,,None}) in the main interpreter
loop.

@item 
gh-103899@footnote{https://github.com/python/cpython/issues/103899}: Provide a helpful hint in the @ref{291,,TypeError} message when
accidentally calling a @ref{1be7,,module} object that has a callable attribute
of the same name (such as @ref{496,,dis.dis()} or @ref{6e7,,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.
@end itemize

@node Library<71>,Core and Builtins<68>,Core and Builtins<67>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id302}@anchor{1c98}
@subsubsection Library



@itemize -

@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.
@end itemize

@node Core and Builtins<68>,Library<72>,Library<71>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id303}@anchor{1c99}
@subsubsection Core and Builtins



@itemize -

@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{6d8,,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{448,,except*}.

@item 
gh-103492@footnote{https://github.com/python/cpython/issues/103492}: Clarify @ref{44a,,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{8eb,,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{30d,,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{1a9,,AttributeError} now retains the @code{name} attribute when
pickled and unpickled.

@item 
gh-103242@footnote{https://github.com/python/cpython/issues/103242}: Migrate @ref{25b,,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{ae6,,CACHE} entries for
@ref{af3,,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{1399,,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{1d2,,memoryview} objects (such
as @code{memoryview(ctypes.c_uint8(42))}) now raises a @ref{291,,TypeError}.
Previously this returned @code{1}, which was not consistent with
@code{mem_0d[0]} raising an @ref{18d7,,IndexError}.
@end itemize

@node Library<72>,Documentation<21>,Core and Builtins<68>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id304}@anchor{1c9a}
@subsubsection Library



@itemize -

@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{b,,asyncio}.

@item 
gh-104600@footnote{https://github.com/python/cpython/issues/104600}: @ref{13cb,,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{2f0,,issubclass()} check comparing a class
@code{X} against a @ref{861,,runtime-checkable protocol} @code{Y} with non-callable members would not
cause @ref{291,,TypeError} to be raised if an @ref{2ef,,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{8bc,,pathlib.PurePath.match()}

@item 
gh-75367@footnote{https://github.com/python/cpython/issues/75367}: Fix data descriptor detection in
@ref{8a5,,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{10d,,typing}.

@item 
gh-102613@footnote{https://github.com/python/cpython/issues/102613}: Fix issue where @ref{73a,,pathlib.Path.glob()} raised
@ref{1121,,RecursionError} when walking deep directory trees.

@item 
gh-103000@footnote{https://github.com/python/cpython/issues/103000}: Improve performance of @ref{190d,,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{aa,,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{1c42,,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{73a,,pathlib.Path.glob()} raised @ref{53c,,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{73a,,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{73a,,pathlib.Path.glob()} returned incomplete
results when it encountered a @ref{10f9,,PermissionError}. This method now
suppresses all @ref{53c,,OSError} exceptions, except those raised from calling
@ref{73d,,is_dir()} on the top-level path.

@item 
gh-104144@footnote{https://github.com/python/cpython/issues/104144}: Optimize @ref{6d7,,asyncio.TaskGroup} when using
@ref{88d,,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{9f4,,asyncio.gather()} when using
@ref{88d,,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{73a,,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{73a,,pathlib.Path.glob()} by using
@ref{1c9b,,re.IGNORECASE} to implement case-insensitive matching.

@item 
gh-104102@footnote{https://github.com/python/cpython/issues/104102}: Improve performance of @ref{73a,,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{1bb1,,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{3b,,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{94,,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{af,,platform} module.

@item 
gh-88773@footnote{https://github.com/python/cpython/issues/88773}: Added @ref{1c9c,,turtle.teleport()} to the @ref{10a,,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{1943,,io.open_code()} for files to be executed instead of
raw @ref{32b,,open()}

@item 
gh-68968@footnote{https://github.com/python/cpython/issues/68968}: Fixed garbled output of @ref{937,,assertEqual()}
when an input lacks final newline.

@item 
gh-100370@footnote{https://github.com/python/cpython/issues/100370}: Fix potential @ref{c57,,OverflowError} in
@ref{a71,,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{d7,,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{15,,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{2a3,,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{3b,,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{32e,,datetime.datetime.utcnow()} and
@ref{32f,,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{12d3,,contextlib.suppress} now supports suppressing
exceptions raised as part of an @ref{6d8,,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{db1,,datetime.datetime.fromisocalendar()} in the
implementation of @ref{2d2,,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{1c9d,,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{aa,,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{d4,,socket} constants for source-specific multicast. Patch
by Reese Hyde.

@item 
gh-103673@footnote{https://github.com/python/cpython/issues/103673}: @ref{d5,,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{aa,,pdb} crashes when reading source file
with different encoding by replacing @ref{92b,,io.open()} with
@ref{1943,,io.open_code()}. The new method would also call into the hook set by
@ref{1c9e,,PyFile_SetOpenCodeHook()}.

@item 
gh-103556@footnote{https://github.com/python/cpython/issues/103556}: Now creating @ref{6e8,,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{1c2e,,pathlib.Path.absolute()} and
@ref{1c9f,,cwd()} by joining paths only when necessary. Also
improve performance of @ref{1ca0,,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 @code{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{8b6,,pathlib.PurePath} and
@ref{4ee,,Path}.

@item 
gh-103489@footnote{https://github.com/python/cpython/issues/103489}: Add @ref{8c9,,getconfig()} and
@ref{8ca,,setconfig()} to @ref{3df,,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{74f,,ResourceWarning} in
@ref{223,,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{1a09,,writelines()} in @ref{b,,asyncio} to send very
large payloads that exceed the amount of data that can be written in one
call to @ref{1160,,socket.socket.send()} or @ref{88c,,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{6e6,,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{1839,,logging.Formatter} @code{defaults}
parameter to @ref{1559,,logging.config.dictConfig()} and
@ref{f0e,,logging.config.fileConfig()}. Patch by Bar Harel.

@item 
gh-103092@footnote{https://github.com/python/cpython/issues/103092}: Adapt the @ref{11f,,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{2ef,,isinstance()} checks against
@ref{861,,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{10d,,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{8e1,,«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{6d,,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{76,,idlelib}.

@item 
gh-103285@footnote{https://github.com/python/cpython/issues/103285}: Improve performance of @ref{d9c,,ast.get_source_segment()}.

@item 
gh-103225@footnote{https://github.com/python/cpython/issues/103225}: Fix a bug in @ref{aa,,pdb} when displaying line numbers of
module-level source code.

@item 
gh-103092@footnote{https://github.com/python/cpython/issues/103092}: Adapt the @ref{97,,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{120,,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{1243,,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{8b7,,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{1ca1,,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{1a42,,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{75,,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{8a5,,inspect.getattr_static()}. Patch by
Alex Waygood.

@item 
gh-103176@footnote{https://github.com/python/cpython/issues/103176}: @ref{8d2,,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{aa,,pdb}.

@item 
gh-103015@footnote{https://github.com/python/cpython/issues/103015}: Add `entrypoint' keyword-only parameter to
@ref{8c8,,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{190e,,dataclasses.astuple()} and
@ref{190d,,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{e7,,tarfile}, and
@ref{882,,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{883,,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{73a,,pathlib.Path.glob()} and @ref{73b,,rglob()}.

@item 
gh-101819@footnote{https://github.com/python/cpython/issues/101819}: Isolate the @ref{82,,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{2cb,,collections.abc.ByteString}

@item 
gh-101362@footnote{https://github.com/python/cpython/issues/101362}: Speed up @ref{4ee,,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{3b,,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{10f,,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{8b6,,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{1c49,,tty.cfmakeraw()} and @ref{1bfe,,tty.cfmakecbreak()} to
@ref{109,,tty} and modernize, the behavior of @ref{1c48,,tty.setraw()} and
@ref{1bfd,,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{8de,,types.get_original_bases()} to provide further
introspection for types.

@item 
gh-101640@footnote{https://github.com/python/cpython/issues/101640}: @ref{1dc,,argparse.ArgumentParser} now catches errors when
writing messages, such as when @ref{d05,,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{6a,,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{223,,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 @code{pkgutil.find_loader()} and
@code{pkgutil.get_loader()} in favor of @ref{7a7,,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{6bf,,subprocess.Popen}.

@item 
gh-94906@footnote{https://github.com/python/cpython/issues/94906}: Support multiple steps in @ref{8a9,,math.nextafter()}. Patch by
Shantanu Jain and Matthias Gorgens.

@item 
gh-51574@footnote{https://github.com/python/cpython/issues/51574}: Make @ref{730,,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{13a,,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{11e,,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{73a,,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{897,,QUOTE_STRINGS} and @ref{896,,QUOTE_NOTNULL}
to the suite of @ref{2c,,csv} module quoting styles.

@item 
bpo-24964@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24964}: Added
@ref{1c79,,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{98,,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{1ca2,,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<21>,Tests<24>,Library<72>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id305}@anchor{1ca3}
@subsubsection Documentation



@itemize -

@item 
gh-67056@footnote{https://github.com/python/cpython/issues/67056}: Document that the effect of registering or unregistering an
@ref{d,,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<24>,Build<23>,Documentation<21>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id306}@anchor{1ca4}
@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{13d,,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{586,,os.spawn*} tests failing on Windows
when the working directory or interpreter path contains spaces.
@end itemize

@node Build<23>,Windows<21>,Tests<24>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id307}@anchor{1ca5}
@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<21>,macOS<16>,Build<23>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id308}@anchor{1ca6}
@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{14da,,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{291,,TypeError} was raised when calling
@code{ntpath.realpath()} with a bytes parameter in some cases.
@end itemize

@node macOS<16>,IDLE<15>,Windows<21>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id309}@anchor{1ca7}
@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<15>,Tools/Demos<18>,macOS<16>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id310}@anchor{1ca8}
@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<18>,C API<24>,IDLE<15>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id311}@anchor{1ca9}
@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{1c90,,Py_UNUSED}. Patch by Erlend E.
Aasland.
@end itemize

@node C API<24>,,Tools/Demos<18>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id312}@anchor{1caa}
@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{988,,PyUnstable_Long_IsCompact()} and
@ref{989,,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{38e,,PyType_FromSpec()} and its variants now allow creating
classes whose metaclass overrides @ref{981,,tp_new}. The
@code{tp_new} is ignored. This behavior is deprecated and will be disallowed
in 3.14+. The new @ref{391,,PyType_FromMetaclass()} already disallows it.

@item 
gh-103743@footnote{https://github.com/python/cpython/issues/103743}: Add @ref{1cab,,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{1cac,,PyUnstable_WritePerfMapEntry()},
@ref{1cad,,PyUnstable_PerfMapState_Init()} and
@ref{1cae,,PyUnstable_PerfMapState_Fini()}. These allow extension modules (JIT
compilers in particular) to write to perf-map files in a thread safe
manner. The @ref{1caf,,Python support for the perf map compatible profilers} 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{199,,PyType_Spec.basicsize} can now be zero or negative,
@ref{19a,,PyObject_GetTypeData()} can be used to get subclass-specific data,
and @ref{956,,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{1cb0,,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{81e,,PyUnicode_FromFormat()} and @ref{979,,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{1cb1}
@subsection Python 3.12.0 alpha 7


`Release date: 2023-04-04'

@menu
* Core and Builtins: Core and Builtins<69>. 
* Library: Library<73>. 
* Core and Builtins: Core and Builtins<70>. 
* Build: Build<24>. 
* Core and Builtins: Core and Builtins<71>. 
* Library: Library<74>. 
* Documentation: Documentation<22>. 
* Tests: Tests<25>. 
* Build: Build<25>. 
* Windows: Windows<22>. 
* Tools/Demos: Tools/Demos<19>. 
* C API: C API<25>. 

@end menu

@node Core and Builtins<69>,Library<73>,,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id313}@anchor{1cb2}
@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{ae6,,CACHE} entries for
@code{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{8ce,,sys.last_exc} and deprecate @ref{8cf,,sys.last_type},
@ref{8d0,,sys.last_value} and @ref{8d1,,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{d32,,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{648,,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{ae6,,CACHE} entries used by
@ref{1c60,,LOAD_GLOBAL}.
@end itemize

@node Library<73>,Core and Builtins<70>,Core and Builtins<69>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id314}@anchor{1cb3}
@subsubsection Library



@itemize -

@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}).
@end itemize

@node Core and Builtins<70>,Build<24>,Library<73>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id315}@anchor{1cb4}
@subsubsection Core and Builtins



@itemize -

@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{1c,,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.
@end itemize

@node Build<24>,Core and Builtins<71>,Core and Builtins<70>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id316}@anchor{1cb5}
@subsubsection Build



@itemize -

@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.
@end itemize

@node Core and Builtins<71>,Library<74>,Build<24>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id317}@anchor{1cb6}
@subsubsection Core and Builtins



@itemize -

@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
@end itemize

@node Library<74>,Documentation<22>,Core and Builtins<71>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id318}@anchor{1cb7}
@subsubsection Library



@itemize -

@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.

@item 
gh-103085@footnote{https://github.com/python/cpython/issues/103085}: Pure python @ref{a45,,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{4fb,,Pdb} that raise @ref{17e,,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{3b,,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{2ef,,isinstance()} checks against @ref{861,,runtime-checkable protocols} now use
@ref{8a5,,inspect.getattr_static()} rather than @ref{8e2,,hasattr()} to lookup
whether attributes exist. This means that descriptors and
@ref{8e3,,__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{4fb,,Pdb} that raise @ref{17e,,SyntaxError}. Patch by Tian Gao.

@item 
gh-102947@footnote{https://github.com/python/cpython/issues/102947}: Improve traceback when @ref{1b4f,,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{1c47,,asyncio.Timeout} context manager now works reliably
even when performing cleanup due to task cancellation.  Previously it
could raise a @ref{6da,,CancelledError} instead of an
@ref{1cb8,,TimeoutError} in such cases.

@item 
gh-102871@footnote{https://github.com/python/cpython/issues/102871}: Remove support for obsolete browsers from @ref{11e,,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{1862,,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{335,,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{295,,ParamSpec}. Previously, if the
@code{ParamSpec} was substituted with a parameters list that itself contained
a @ref{294,,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{8b6,,pathlib.PurePath} and @ref{4ee,,Path} subclasses were not
called in some circumstances.

@item 
gh-78530@footnote{https://github.com/python/cpython/issues/78530}: @ref{891,,asyncio.wait()} now accepts generators yielding tasks.
Patch by Kumar Aditya.

@item 
gh-102748@footnote{https://github.com/python/cpython/issues/102748}: @ref{890,,asyncio.iscoroutine()} now returns @code{False} for
generators as @ref{b,,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{295,,ParamSpec}. (Use square brackets to
represent a parameter list.)

@item 
gh-100112@footnote{https://github.com/python/cpython/issues/100112}: @ref{da0,,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{8ae,,os.listdrives()}, @ref{8af,,os.listvolumes()} and
@ref{8b0,,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{e7,,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{8a3,,inspect.getasyncgenstate()} and
@ref{8a4,,inspect.getasyncgenlocals()}. Patch by Thomas Krennwallner.

@item 
gh-102103@footnote{https://github.com/python/cpython/issues/102103}: Add @code{module} argument to @ref{1a84,,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{cf,,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{32,,dataclasses}.

@item 
gh-101673@footnote{https://github.com/python/cpython/issues/101673}: Fix a @ref{aa,,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{129c,,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{15da,,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{1cb9,,unittest.TextTestRunner} and
@ref{93f,,unittest.TextTestResult} constructors accept a new `durations'
keyword argument. Subclasses should take this into account or accept
@code{**kwargs}. Added @ref{1cba,,unittest.TestResult.addDuration()} method and
@ref{1c82,,unittest.TestResult.collectedDurations} attribute.

(Contributed by Giampaolo Rodola)

@item 
gh-98169@footnote{https://github.com/python/cpython/issues/98169}: Fix @ref{190e,,dataclasses.astuple()} crash when
@ref{1565,,collections.defaultdict} is present in the attributes.

@item 
gh-96931@footnote{https://github.com/python/cpython/issues/96931}: Fix incorrect results from @ref{121d,,ssl.SSLSocket.shared_ciphers()}

@item 
gh-95495@footnote{https://github.com/python/cpython/issues/95495}: When built against OpenSSL 3.0, the @ref{d8,,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{1903,,SSLEOFError}, matching the
behavior in previous versions of OpenSSL. The
@ref{c11,,options} attribute on @ref{336,,SSLContext} also
no longer includes @ref{c10,,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{561,,uuid.uuid3()} and @ref{562,,uuid.uuid5()} functions support
@ref{1c7,,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{56f,,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{a8,,pathlib}.
@end itemize

@node Documentation<22>,Tests<25>,Library<74>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id319}@anchor{1cbb}
@subsubsection Documentation



@itemize -

@item 
gh-103112@footnote{https://github.com/python/cpython/issues/103112}: Add docstring to @ref{1ad0,,http.client.HTTPResponse.read()} to fix
@code{pydoc} output.
@end itemize

@node Tests<25>,Build<25>,Documentation<22>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id320}@anchor{1cbc}
@subsubsection Tests



@itemize -

@item 
gh-102980@footnote{https://github.com/python/cpython/issues/102980}: Improve test coverage on @ref{aa,,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<25>,Windows<22>,Tests<25>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id321}@anchor{1cbd}
@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<22>,Tools/Demos<19>,Build<25>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id322}@anchor{1cbe}
@subsubsection Windows



@itemize -

@item 
gh-102690@footnote{https://github.com/python/cpython/issues/102690}: Update @ref{11e,,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<19>,C API<25>,Windows<22>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id323}@anchor{1cbf}
@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<25>,,Tools/Demos<19>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id324}@anchor{1cc0}
@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{1cc1}
@subsection Python 3.12.0 alpha 6


`Release date: 2023-03-07'

@menu
* Security: Security<22>. 
* Core and Builtins: Core and Builtins<72>. 
* Library: Library<75>. 
* Documentation: Documentation<23>. 
* Tests: Tests<26>. 
* Build: Build<26>. 
* Windows: Windows<23>. 
* macOS: macOS<17>. 
* C API: C API<26>. 

@end menu

@node Security<22>,Core and Builtins<72>,,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id325}@anchor{1cc2}
@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{6b,,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{6bf,,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<72>,Library<75>,Security<22>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id326}@anchor{1cc3}
@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{1cc4,,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{1925,,socket.getaddrinfo} no longer raises
@ref{c57,,OverflowError} for @ref{326,,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{1cc5,,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{8f1,,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{108,,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 @code{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<75>,Documentation<23>,Core and Builtins<72>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id327}@anchor{1cc6}
@subsubsection Library



@itemize -

@item 
gh-102302@footnote{https://github.com/python/cpython/issues/102302}: Micro-optimise hashing of @ref{6e9,,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{3ed,,argparse.ArgumentParser.add_argument()} were dropped. Patch by Yeojin
Kim.

@item 
gh-91038@footnote{https://github.com/python/cpython/issues/91038}: @ref{1cc7,,platform.platform()} now has boolean default arguments.

@item 
gh-81652@footnote{https://github.com/python/cpython/issues/81652}: Add @ref{1cc8,,mmap.MAP_ALIGNED_SUPER} FreeBSD and
@ref{1cc9,,mmap.MAP_CONCEAL} OpenBSD constants to @ref{94,,mmap}. Patch by
Yeojin Kim.

@item 
gh-102179@footnote{https://github.com/python/cpython/issues/102179}: Fix @ref{f20,,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{1255,,io.BytesIO} if
@ref{1387,,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{6b,,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{3ea,,SystemError} when
the callable object exhausts the iterator but forgets to either return a
sentinel value or raise @ref{fba,,StopIteration}.

@item 
gh-87634@footnote{https://github.com/python/cpython/issues/87634}: Remove locking behavior from @ref{94e,,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{10,,bdb} looks up the source line with
@ref{88,,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{1c3,,fractions.Fraction} for small components. The
private argument @code{_normalize} of the @code{fractions.Fraction}
constructor has been removed.

@item 
gh-101693@footnote{https://github.com/python/cpython/issues/101693}: In @ref{7a8,,sqlite3.Cursor.execute()}, @ref{2c9,,DeprecationWarning} is
now emitted when @ref{7aa,,named placeholders} are used
together with parameters supplied as a @ref{8ff,,sequence} instead of as a
@ref{188,,dict}. Starting from Python 3.14, using named placeholders with
parameters supplied as a sequence will raise a
@ref{57d,,ProgrammingError}. Patch by Erlend E. Aasland.

@item 
gh-101446@footnote{https://github.com/python/cpython/issues/101446}: Change repr of @ref{9d5,,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{8b6,,pathlib.PurePath} construction by handling
arguments more uniformly. When a @ref{4ee,,pathlib.Path} argument is
supplied, we use its string representation rather than joining its parts
with @ref{1a42,,os.path.join()}.

@item 
gh-101362@footnote{https://github.com/python/cpython/issues/101362}: Speed up @ref{8b6,,pathlib.PurePath} construction by calling
@ref{1a42,,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{4ee,,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{1cca,,pty.fork()} to use
@ref{1ccb,,os.login_tty()}.

A @ref{2c9,,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{579,,pty.openpty()}.

@item 
gh-101561@footnote{https://github.com/python/cpython/issues/101561}: Add a new decorator @ref{869,,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{e6,,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{5f,,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{84,,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{1c2e,,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{13d,,zoneinfo}. Patch by Erlend E. Aasland.

@item 
gh-96764@footnote{https://github.com/python/cpython/issues/96764}: @ref{9f6,,asyncio.wait_for()} now uses @ref{9f5,,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{18f8,,lzma.LZMADecompressor} and
@ref{18f9,,bz2.BZ2Decompressor} objects without calling @code{__init__()}, and
fix leakage of locks and internal buffers when calling the @code{__init__()}
methods of @code{lzma.LZMADecompressor}, @ref{1ccc,,lzma.LZMACompressor},
@ref{1ccd,,bz2.BZ2Compressor}, and @code{bz2.BZ2Decompressor} objects
multiple times.
@end itemize

@node Documentation<23>,Tests<26>,Library<75>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id328}@anchor{1cce}
@subsubsection Documentation



@itemize -

@item 
gh-85417@footnote{https://github.com/python/cpython/issues/85417}: Update @ref{19,,cmath} documentation to clarify behaviour on branch
cuts.

@item 
gh-97725@footnote{https://github.com/python/cpython/issues/97725}: Fix @ref{1ccf,,asyncio.Task.print_stack()} description for
@code{file=None}. Patch by Oleg Iarygin.
@end itemize

@node Tests<26>,Build<26>,Documentation<23>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id329}@anchor{1cd0}
@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<26>,Windows<23>,Tests<26>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id330}@anchor{1cd1}
@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{1cd2,,--with-strict-overflow}. Patch by Matthias Görgens and Shantanu
Jain.
@end itemize

@node Windows<23>,macOS<17>,Build<26>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id331}@anchor{1cd3}
@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<17>,C API<26>,Windows<23>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id332}@anchor{1cd4}
@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<26>,,macOS<17>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id333}@anchor{1cd5}
@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{63c,,PyErr_GetRaisedException()} and
@ref{63f,,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{63b,,PyErr_Fetch()} and @ref{63e,,PyErr_Restore()}. This is less error
prone and a bit more efficient.

Add @ref{970,,PyException_GetArgs()} and @ref{971,,PyException_SetArgs()} as
convenience functions for retrieving and modifying the
@ref{972,,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{1cd6}
@subsection Python 3.12.0 alpha 5


`Release date: 2023-02-07'

@menu
* Security: Security<23>. 
* Core and Builtins: Core and Builtins<73>. 
* Library: Library<76>. 
* Documentation: Documentation<24>. 
* Tests: Tests<27>. 
* Build: Build<27>. 
* Windows: Windows<24>. 

@end menu

@node Security<23>,Core and Builtins<73>,,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id334}@anchor{1cd7}
@subsubsection Security



@itemize -

@item 
gh-99108@footnote{https://github.com/python/cpython/issues/99108}: Replace the builtin @ref{6b,,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<73>,Library<76>,Security<23>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id336}@anchor{1cd8}
@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{1cd9,,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{429,,continue} or
@ref{428,,break} which are not in a loop. Patch by Donghee Na.

@item 
gh-101372@footnote{https://github.com/python/cpython/issues/101372}: Fix @ref{e0b,,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{1cda,,sys.getsizeof()} reporting for @ref{326,,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{18fa,,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{326,,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{7b3,,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{d32,,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{1a87,,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{7df,,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}.
@end itemize

@node Library<76>,Documentation<24>,Core and Builtins<73>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id337}@anchor{1cdb}
@subsubsection Library



@itemize -

@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{47c,,ctypes.Structure} objects, reflecting their
true representation in memory.

@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{9fa,,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{d4,,socket} 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{1cdc,,TimerHandle} in
@code{asyncio.base_events.BaseEventLoop._add_callback}.

@item 
gh-101144@footnote{https://github.com/python/cpython/issues/101144}: Make @ref{1a13,,zipfile.Path.open()} and
@ref{1cdd,,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{291,,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{a9e,,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{8b4,,os.path.splitroot()}, which splits a path into a
3-item tuple @code{(drive, root, tail)}. This new function is used by
@ref{a8,,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{b,,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{18bb,,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{47c,,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{1c3,,fractions.Fraction} instances.

@item 
gh-99266@footnote{https://github.com/python/cpython/issues/99266}: Preserve more detailed error messages in @ref{2d,,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{1cde,,sys._getframemodulename()}.

@item 
gh-88597@footnote{https://github.com/python/cpython/issues/88597}: @ref{119,,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{1cdf,,c_byte} to @ref{1ce0,,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{12e,,xml.etree.ElementTree} module now emits
@ref{2c9,,DeprecationWarning} when testing the truth value of an
@ref{343,,xml.etree.ElementTree.Element}. Before, the Python implementation
emitted @ref{847,,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{4ee,,pathlib.Path} accepted and ignored
keyword arguments. Patch provided by Yurii Karabas.

@item 
gh-77772@footnote{https://github.com/python/cpython/issues/77772}: @ref{dad,,ctypes.CDLL}, @ref{1ce1,,ctypes.OleDLL},
@ref{1ce2,,ctypes.WinDLL}, and @ref{1ce3,,ctypes.PyDLL} now accept
@ref{79f,,path-like objects} as their @code{name} argument.
Patch by Robert Hoelzl.
@end itemize

@node Documentation<24>,Tests<27>,Library<76>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id338}@anchor{1ce4}
@subsubsection Documentation



@itemize -

@item 
gh-88324@footnote{https://github.com/python/cpython/issues/88324}: Reword @ref{df,,subprocess} to emphasize default behavior of
`stdin', `stdout', and `stderr' arguments. Remove inaccurate statement
about child file handle inheritance.
@end itemize

@node Tests<27>,Build<27>,Documentation<24>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id339}@anchor{1ce5}
@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<27>,Windows<24>,Tests<27>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id340}@anchor{1ce6}
@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{83e,,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<24>,,Build<27>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id341}@anchor{1ce7}
@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{1ce8}
@subsection Python 3.12.0 alpha 4


`Release date: 2023-01-10'

@menu
* Core and Builtins: Core and Builtins<74>. 
* Library: Library<77>. 
* Core and Builtins: Core and Builtins<75>. 
* Library: Library<78>. 
* Core and Builtins: Core and Builtins<76>. 
* Library: Library<79>. 
* Documentation: Documentation<25>. 
* Tests: Tests<28>. 
* Build: Build<28>. 
* Windows: Windows<25>. 
* macOS: macOS<18>. 
* Tools/Demos: Tools/Demos<20>. 
* C API: C API<27>. 

@end menu

@node Core and Builtins<74>,Library<77>,,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id342}@anchor{1ce9}
@subsubsection Core and Builtins



@itemize -

@item 
gh-100776@footnote{https://github.com/python/cpython/issues/100776}: Fix misleading default value in @ref{167d,,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{8f0,,CALL_INTRINSIC_1} instruction. Remove
@code{IMPORT_STAR}, @code{PRINT_EXPR} and
@code{STOPITERATION_ERROR}, replacing them with the
@code{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{17e,,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{1cea,,int.is_integer()} to improve duck type compatibility
between @ref{326,,int} and @ref{327,,float}.

@item 
gh-100425@footnote{https://github.com/python/cpython/issues/100425}: Improve the accuracy of @code{sum()} with compensated summation.
@end itemize

@node Library<77>,Core and Builtins<75>,Core and Builtins<74>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id343}@anchor{1ceb}
@subsubsection Library



@itemize -

@item 
gh-100374@footnote{https://github.com/python/cpython/issues/100374}: Fix incorrect result and delay in @ref{1cec,,socket.getfqdn()}. Patch
by Dominic Socular.
@end itemize

@node Core and Builtins<75>,Library<78>,Library<77>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id344}@anchor{1ced}
@subsubsection Core and Builtins



@itemize -

@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{32d,,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{d32,,COMPARE_OP} for
@ref{327,,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 @ref{1cee,,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{8e2,,hasattr()} for type objects with
a missing attribute.

@item 
gh-99582@footnote{https://github.com/python/cpython/issues/99582}: Freeze @ref{13b,,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.
@end itemize

@node Library<78>,Core and Builtins<76>,Core and Builtins<75>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id345}@anchor{1cef}
@subsubsection Library



@itemize -

@item 
gh-89051@footnote{https://github.com/python/cpython/issues/89051}: Add @ref{1cf0,,ssl.OP_LEGACY_SERVER_CONNECT}
@end itemize

@node Core and Builtins<76>,Library<79>,Library<78>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id346}@anchor{1cf1}
@subsubsection Core and Builtins



@itemize -

@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<79>,Documentation<25>,Core and Builtins<76>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id347}@anchor{1cf2}
@subsubsection Library



@itemize -

@item 
gh-100833@footnote{https://github.com/python/cpython/issues/100833}: Speed up @ref{1777,,math.fsum()} by removing defensive @code{volatile}
qualifiers.

@item 
gh-100805@footnote{https://github.com/python/cpython/issues/100805}: Modify @ref{15d6,,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{1cf3,,email.message.Message.__contains__()} twice as fast.

@item 
gh-91851@footnote{https://github.com/python/cpython/issues/91851}: Microoptimizations for @ref{1cf4,,fractions.Fraction.__round__()},
@ref{1cf5,,fractions.Fraction.__ceil__()} and
@ref{1cf6,,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{8b9,,os.walk()} by using
@ref{2ef,,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{edc,,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{1c2e,,pathlib.Path.absolute()} by nearly
2x. This comes at the cost of a performance regression in
@ref{1c9f,,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{f60,,unittest.mock.seal()} with
@ref{e0d,,unittest.mock.AsyncMock}.

@item 
gh-100488@footnote{https://github.com/python/cpython/issues/100488}: Add @code{Fraction.is_integer()} to check whether a
@ref{1c3,,fractions.Fraction} is an integer. This improves duck type
compatibility with @ref{327,,float} and @ref{326,,int}.

@item 
gh-100474@footnote{https://github.com/python/cpython/issues/100474}: @ref{75,,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{ecf,,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{88f,,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{2c9,,DeprecationWarning} may be raised when @ref{6bd,,os.fork()}
or @ref{6be,,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{b,,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{15a7,,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{1cf7,,datetime.time.strftime()} to `format'. Rename the `t' parameter of
@ref{8fb,,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{1387,,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{8b9,,os.walk()} where a @ref{1121,,RecursionError}
would occur on deep directory structures by adjusting the implementation
of @code{os.walk()} to be iterative instead of recursive.

@item 
gh-94943@footnote{https://github.com/python/cpython/issues/94943}: Add @ref{1cf8,,Dataclass support} to the @ref{a21,,Enum}
@ref{1cf9,,__repr__()}. When inheriting from a
@ref{6e6,,dataclass}, only show the field names in the value
section of the member @ref{45b,,repr()}, and not the dataclass” class name.

@item 
gh-83035@footnote{https://github.com/python/cpython/issues/83035}: Fix @ref{1a04,,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{8a1,,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{3d,,doctest} failure on @ref{a3a,,types.MethodWrapperType}
in modules.

@item 
gh-85267@footnote{https://github.com/python/cpython/issues/85267}: Several improvements to @ref{4bd,,inspect.signature()}”s handling of
@code{__text_signature}. - Fixes a case where @code{inspect.signature()}
dropped parameters - Fixes a case where @code{inspect.signature()} raised
@ref{94f,,tokenize.TokenError} - Allows @code{inspect.signature()} to
understand defaults involving binary operations of constants -
@code{inspect.signature()} is documented as only raising @ref{291,,TypeError}
or @ref{277,,ValueError}, but sometimes raised @ref{30d,,RuntimeError}. These
cases now raise @code{ValueError} - Removed a dead code path

@item 
gh-91166@footnote{https://github.com/python/cpython/issues/91166}: @ref{b,,asyncio} is optimized to avoid excessive copying when
writing to socket and use @ref{88c,,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{1cfa,,urllib.parse.unquote()} and
@ref{1cfb,,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{20f,,asynccontextmanager()}, which caused it to propagate
exceptions with incorrect tracebacks and fix a 3.11 regression in
@ref{20e,,contextmanager()}, which caused it to propagate
exceptions with incorrect tracebacks for @ref{fba,,StopIteration}.

@item 
gh-78707@footnote{https://github.com/python/cpython/issues/78707}: Deprecate passing more than one positional argument to
@ref{575,,pathlib.PurePath.relative_to()} and
@ref{576,,is_relative_to()}.

@item 
gh-92122@footnote{https://github.com/python/cpython/issues/92122}: Fix reStructuredText syntax errors in docstrings in the
@ref{59,,enum} module.

@item 
gh-91851@footnote{https://github.com/python/cpython/issues/91851}: Optimize the @ref{1c3,,Fraction} arithmetics for small
components.

@item 
bpo-24132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24132}: Make @ref{8b6,,pathlib.PurePath} and @ref{4ee,,Path}
subclassable (private to start). Previously, attempting to instantiate a
subclass resulted in an @ref{1a9,,AttributeError} being raised. Patch by
Barney Gale.

@item 
bpo-40447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40447}: Accept @ref{100f,,os.PathLike} (such as @ref{4ee,,pathlib.Path}) in
the @code{stripdir} arguments of @ref{1199,,compileall.compile_file()} and
@ref{ee8,,compileall.compile_dir()}.

@item 
bpo-36880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36880}: Fix a reference counting issue when a @ref{2d,,ctypes} callback
with return type @ref{486,,py_object} returns @code{None}, which could
cause crashes.
@end itemize

@node Documentation<25>,Tests<28>,Library<79>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id348}@anchor{1cfc}
@subsubsection Documentation



@itemize -

@item 
gh-100616@footnote{https://github.com/python/cpython/issues/100616}: Document existing @code{attr} parameter to
@ref{1cfd,,curses.window.vline()} function in @ref{2e,,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{ee8,,compileall.compile_dir()} and @ref{1199,,compileall.compile_file()} could
be @ref{1c7,,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<28>,Build<28>,Documentation<25>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id349}@anchor{1cfe}
@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<28>,Windows<25>,Tests<28>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id350}@anchor{1cff}
@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<25>,macOS<18>,Build<28>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id351}@anchor{1d00}
@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{1d01,,asyncio.Protocol.data_received()} receives an
immutable @ref{1c7,,bytes} object (as documented), instead of
@ref{1c6,,bytearray}.

@item 
bpo-43984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43984}: @ref{1d02,,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{53c,,OSError}.
@end itemize

@node macOS<18>,Tools/Demos<20>,Windows<25>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id352}@anchor{1d03}
@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<20>,C API<27>,macOS<18>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id353}@anchor{1d04}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-45256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45256}: Fix a bug that caused an @ref{1a9,,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<27>,,Tools/Demos<20>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id354}@anchor{1d05}
@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{97c,,Py_CLEAR}, @ref{97d,,Py_SETREF} and
@ref{97e,,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{1d06}
@subsection Python 3.12.0 alpha 3


`Release date: 2022-12-06'

@menu
* Security: Security<24>. 
* Core and Builtins: Core and Builtins<77>. 
* Library: Library<80>. 
* Core and Builtins: Core and Builtins<78>. 
* Library: Library<81>. 
* Documentation: Documentation<26>. 
* Tests: Tests<29>. 
* Build: Build<29>. 
* Windows: Windows<26>. 
* macOS: macOS<19>. 
* Tools/Demos: Tools/Demos<21>. 
* C API: C API<28>. 

@end menu

@node Security<24>,Core and Builtins<77>,,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id355}@anchor{1d07}
@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{75,,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{63,,gc} module
@end itemize

@node Core and Builtins<77>,Library<80>,Security<24>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id356}@anchor{1d08}
@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{96c,,PyCode_AddWatcher()} and
@ref{96d,,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{6d8,,ExceptionGroup} subclass can wrap a
@ref{9b9,,BaseException}.
@end itemize

@node Library<80>,Core and Builtins<78>,Core and Builtins<77>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id357}@anchor{1d09}
@subsubsection Library



@itemize -

@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.
@end itemize

@node Core and Builtins<78>,Library<81>,Library<80>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id358}@anchor{1d0a}
@subsubsection Core and Builtins



@itemize -

@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{b5e,,PyType_Ready()} called on them yet.

@item 
gh-99127@footnote{https://github.com/python/cpython/issues/99127}: Allow some features of @ref{e5,,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{d0f,,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{277,,ValueError} instead of @ref{3ea,,SystemError} when
methods of uninitialized @ref{1947,,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{16b4,,io.FileIO} when the
opener returns an invalid file descriptor.
@end itemize

@node Library<81>,Documentation<26>,Core and Builtins<78>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id359}@anchor{1d0b}
@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{8e4,,typing.dataclass_transform()}.

@item 
gh-79033@footnote{https://github.com/python/cpython/issues/79033}: Fix @ref{1c46,,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{52f,,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{b,,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{309,,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{1d0c,,ast.increment_lineno()} to also cover
@ref{1d0d,,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{293,,TypeVarTuple} and one or more
@ref{294,,TypeVar}.

@item 
gh-99379@footnote{https://github.com/python/cpython/issues/99379}: Fix substitution of @ref{295,,ParamSpec} followed by
@ref{293,,TypeVarTuple} in generic aliases.

@item 
gh-99344@footnote{https://github.com/python/cpython/issues/99344}: Fix substitution of @ref{293,,TypeVarTuple} and
@ref{295,,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{2d,,ctypes}.

@item 
gh-99201@footnote{https://github.com/python/cpython/issues/99201}: Fix @ref{18d7,,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{575,,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{56c,,asyncio.get_event_loop()} and many other @ref{b,,asyncio}
functions like @ref{1035,,asyncio.ensure_future()}, @ref{e34,,asyncio.shield()} or
@ref{9f4,,asyncio.gather()}, and also the
@code{get_event_loop()} method of
@code{asyncio.BaseDefaultEventLoopPolicy} now raise a
@ref{30d,,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{2c9,,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{161b,,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{1bcd,,is_private} properties in the
@ref{83,,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{1a43,,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{edc,,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{1052,,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<26>,Tests<29>,Library<81>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id360}@anchor{1d0e}
@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{5ef,,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{1151,,os.wait*} family of functions, and improved the docs for
@ref{1152,,os.waitid()} with more explanation of the possible argument
constants.
@end itemize

@node Tests<29>,Build<29>,Documentation<26>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id361}@anchor{1d0f}
@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<29>,Windows<26>,Tests<29>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id362}@anchor{1d10}
@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{21,,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<26>,macOS<19>,Build<29>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id363}@anchor{1d11}
@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{6a8,,sys.version} and @code{sys._git} on
Windows

@item 
gh-99442@footnote{https://github.com/python/cpython/issues/99442}: Fix handling in @ref{9bc,,Διαχειριστής εγκατάστασης Python} 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{1be1,,multiprocessing.shared_memory.SharedMemory} on Windows.
@end itemize

@node macOS<19>,Tools/Demos<21>,Windows<26>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id364}@anchor{1d12}
@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<21>,C API<28>,macOS<19>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id365}@anchor{1d13}
@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<28>,,Tools/Demos<21>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id366}@anchor{1d14}
@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{84d,,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{1d15,,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{992,,T_OBJECT}, @ref{994,,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{1d16}
@subsection Python 3.12.0 alpha 2


`Release date: 2022-11-14'

@menu
* Security: Security<25>. 
* Core and Builtins: Core and Builtins<79>. 
* Build: Build<30>. 
* Core and Builtins: Core and Builtins<80>. 
* Library: Library<82>. 
* Documentation: Documentation<27>. 
* Tests: Tests<30>. 
* Build: Build<31>. 
* Windows: Windows<27>. 
* macOS: macOS<20>. 
* C API: C API<29>. 

@end menu

@node Security<25>,Core and Builtins<79>,,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id367}@anchor{1d17}
@subsubsection Security



@itemize -

@item 
gh-98433@footnote{https://github.com/python/cpython/issues/98433}: The IDNA codec decoder used on DNS hostnames by @ref{d4,,socket} or
@ref{b,,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{111,,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<79>,Build<30>,Security<25>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id368}@anchor{1d18}
@subsubsection Core and Builtins



@itemize -

@item 
gh-81057@footnote{https://github.com/python/cpython/issues/81057}: The docs clearly say that @ref{1d19,,PyImport_Inittab},
@ref{1d1a,,PyImport_AppendInittab()}, and @ref{1d1b,,PyImport_ExtendInittab()}
should not be used after @ref{673,,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{b6c,,PyThreadState} and
@ref{c90,,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{448,,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{5b,,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{17e,,SyntaxError} for a @ref{ad6,,try} block
with both @ref{447,,except} and @ref{448,,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{1d1c,,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{665,,NameError} exceptions for
instances. Now if a @code{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{44a,,SyntaxWarning}, instead of
@ref{2c9,,DeprecationWarning}. In a future Python version they will be
eventually a @ref{17e,,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{44a,,SyntaxWarning}, instead of
@ref{2c9,,DeprecationWarning}.  For example, @code{re.compile("\d+\.\d+")} now
emits a @code{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{17e,,SyntaxError} will eventually be raised,
instead of @code{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{17e,,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{294,,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{1cc4,,FOR_ITER} for generators. Saves
multiple layers of dispatch and checking to get from the
@code{FOR_ITER} instruction in the caller to the @ref{7b4,,RESUME} in
the generator.

@item 
gh-98762@footnote{https://github.com/python/cpython/issues/98762}: Fix source locations of @ref{1d4,,match} sub-patterns.

@item 
gh-98586@footnote{https://github.com/python/cpython/issues/98586}: Added the methods @ref{963,,PyObject_Vectorcall()} and
@ref{964,,PyObject_VectorcallMethod()} to the @ref{95c,,Limited API}
along with the auxiliary macro constant
@ref{965,,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{188d,,__slots__}) could behave incorrectly or crash instead of
raising a @ref{291,,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{6dd,,RuntimeWarning} and assign
@ref{a65,,None} to any fast locals that are left unbound after jumps or
@ref{1d1d,,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{13d6,,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{1d1e,,RETURN_VALUE}, @ref{7b3,,YIELD_VALUE}, and
@ref{ae9,,RETURN_GENERATOR}, which now clear the frame.
@end itemize

@node Build<30>,Core and Builtins<80>,Core and Builtins<79>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id369}@anchor{1d1f}
@subsubsection Build



@itemize -

@item 
gh-98415@footnote{https://github.com/python/cpython/issues/98415}: Fix detection of MAC addresses for @ref{119,,uuid} on certain OSs.
Patch by Chaim Sanders
@end itemize

@node Core and Builtins<80>,Library<82>,Build<30>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id370}@anchor{1d20}
@subsubsection Core and Builtins



@itemize -

@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{2d,,ctypes} calls.

@item 
gh-91058@footnote{https://github.com/python/cpython/issues/91058}: @ref{1bd,,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{1cc4,,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{1d21,,ETH_P_ALL} and some of the
@ref{1d22,,ETHERTYPE_* constants} in @ref{d4,,socket}.
Patch by Noam Cohen.
@end itemize

@node Library<82>,Documentation<27>,Core and Builtins<80>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id371}@anchor{1d23}
@subsubsection Library



@itemize -

@item 
gh-93696@footnote{https://github.com/python/cpython/issues/93696}: Allow @ref{aa,,pdb} to locate source for frozen modules in the
standard library.

@item 
gh-99418@footnote{https://github.com/python/cpython/issues/99418}: Fix bug in @ref{2a4,,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 @code{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{1d24,,secrets.token_hex()}.

@item 
gh-74044@footnote{https://github.com/python/cpython/issues/74044}: Fixed bug where @ref{4bd,,inspect.signature()} reported incorrect
arguments for decorated methods.

@item 
gh-99275@footnote{https://github.com/python/cpython/issues/99275}: Fix @code{SystemError} in @ref{2d,,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{dfc,,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{dc4,,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{107,,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{1d25,,DatagramTransport} in @ref{b,,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{107,,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{c1,,re} module which in very rare
circumstances prevented compilation of a regular expression containing a
@ref{1d26,,conditional expression} without the
«else» branch.

@item 
gh-98703@footnote{https://github.com/python/cpython/issues/98703}: Fix @ref{1d27,,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{6c5,,array.array} class now supports subscripting, making
it a @ref{1d1,,generic type}.

@item 
gh-98284@footnote{https://github.com/python/cpython/issues/98284}: Improved @ref{291,,TypeError} message for undefined abstract
methods of a @ref{12c8,,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{79f,,path-like objects} in @code{os.ismount()}.

@item 
gh-94172@footnote{https://github.com/python/cpython/issues/94172}: @ref{61,,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{61,,ftplib}, @ref{77,,imaplib}, @ref{b1,,poplib} and @ref{d2,,smtplib} modules,
and the `key_file', `cert_file' and `check_hostname' parameters from the
@ref{72,,http.client} module, all deprecated since Python 3.6. Use the
`context' parameter (`ssl_context' in @code{imaplib}) instead. Patch by
Victor Stinner.

@item 
gh-83638@footnote{https://github.com/python/cpython/issues/83638}: Add the @ref{8c6,,autocommit} attribute to
@ref{3df,,sqlite3.Connection} and the `autocommit' parameter to
@ref{3e0,,sqlite3.connect()} to control 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}-compliant @ref{8c7,,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{41e,,sysconfig.get_config_var()} to incorrectly return @ref{a65,,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{1b4e,,unittest.mock.create_autospec()} after it was sealed with
@ref{f60,,unittest.mock.seal()} function.

@item 
bpo-38523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38523}: @ref{ded,,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{575,,pathlib.PurePath.relative_to()}.

@item 
bpo-36267@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36267}: Fix IndexError in @ref{1dc,,argparse.ArgumentParser} when a
@code{store_true} action is given an explicit argument.
@end itemize

@node Documentation<27>,Tests<30>,Library<82>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id372}@anchor{1d28}
@subsubsection Documentation



@itemize -

@item 
gh-98832@footnote{https://github.com/python/cpython/issues/98832}: Changes wording of docstring for @ref{4f6,,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<30>,Build<31>,Documentation<27>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id373}@anchor{1d29}
@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{10d,,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<31>,Windows<27>,Tests<30>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id374}@anchor{1d2a}
@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{3d6,,--with-system-libmpdec} is passed to @code{configure}. Don’t
use vendored @code{libexpat} headers if @ref{1d2b,,--with-system-expat} is
passed to @code{configure}.
@end itemize

@node Windows<27>,macOS<20>,Build<31>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id375}@anchor{1d2c}
@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{9bc,,Διαχειριστής εγκατάστασης Python} 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<20>,C API<29>,Windows<27>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id376}@anchor{1d2d}
@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<29>,,macOS<20>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id377}@anchor{1d2e}
@subsubsection C API



@itemize -

@item 
gh-98724@footnote{https://github.com/python/cpython/issues/98724}: The @ref{97c,,Py_CLEAR}, @ref{97d,,Py_SETREF} and
@ref{97e,,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{df,,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{1d2f,,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{96e,,PyFrame_GetVar()} and @ref{96f,,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{1d30}
@subsection Python 3.12.0 alpha 1


`Release date: 2022-10-25'

@menu
* Security: Security<26>. 
* Core and Builtins: Core and Builtins<81>. 
* Library: Library<83>. 
* Core and Builtins: Core and Builtins<82>. 
* Library: Library<84>. 
* Core and Builtins: Core and Builtins<83>. 
* Library: Library<85>. 
* Core and Builtins: Core and Builtins<84>. 
* Library: Library<86>. 
* Core and Builtins: Core and Builtins<85>. 
* Library: Library<87>. 
* Core and Builtins: Core and Builtins<86>. 
* Library: Library<88>. 
* Core and Builtins: Core and Builtins<87>. 
* Library: Library<89>. 
* Core and Builtins: Core and Builtins<88>. 
* Library: Library<90>. 
* Core and Builtins: Core and Builtins<89>. 
* Library: Library<91>. 
* Core and Builtins: Core and Builtins<90>. 
* Library: Library<92>. 
* Documentation: Documentation<28>. 
* Tests: Tests<31>. 
* Build: Build<32>. 
* Windows: Windows<28>. 
* macOS: macOS<21>. 
* IDLE: IDLE<16>. 
* Tools/Demos: Tools/Demos<22>. 
* C API: C API<30>. 

@end menu

@node Security<26>,Core and Builtins<81>,,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id378}@anchor{1d31}
@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{98,,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{46d,,«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{75,,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<81>,Library<83>,Security<26>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id379}@anchor{1d32}
@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{665,,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.
@end itemize

@node Library<83>,Core and Builtins<82>,Core and Builtins<81>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id380}@anchor{1d33}
@subsubsection Library



@itemize -

@item 
gh-96078@footnote{https://github.com/python/cpython/issues/96078}: @ref{14bd,,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{13d,,zoneinfo} to Argument Clinic.
@end itemize

@node Core and Builtins<82>,Library<84>,Library<83>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id381}@anchor{1d34}
@subsubsection Core and Builtins



@itemize -

@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{8f4,,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{1d35,,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{880,,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{1d36,,./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{194,,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{17e,,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{1d37,,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{178,,-X int_max_str_digits} option with no value (invalid) when the
@geindex PYTHONINTMAXSTRDIGITS
@geindex μεταβλητή περιβάλλοντος; PYTHONINTMAXSTRDIGITS
@ref{1d38,,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.
@end itemize

@node Library<84>,Core and Builtins<83>,Core and Builtins<82>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id382}@anchor{1d39}
@subsubsection Library



@itemize -

@item 
gh-96821@footnote{https://github.com/python/cpython/issues/96821}: Fix undefined behaviour in @code{audioop.c}.
@end itemize

@node Core and Builtins<83>,Library<85>,Library<84>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id383}@anchor{1d3a}
@subsubsection Core and Builtins



@itemize -

@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{277,,ValueError} is raised if an integer is larger than
the limit, mention the @ref{1b11,,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{3ea,,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{1d2,,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
@end itemize

@node Library<85>,Core and Builtins<84>,Core and Builtins<83>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id384}@anchor{1d3b}
@subsubsection Library



@itemize -

@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}.
@end itemize

@node Core and Builtins<84>,Library<86>,Library<85>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id385}@anchor{1d3c}
@subsubsection Core and Builtins



@itemize -

@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{8ed,,LOAD_ATTR} from
specializing properly when accessing properties.

@item 
gh-96348@footnote{https://github.com/python/cpython/issues/96348}: Emit a DeprecationWarning when @ref{905,,throw()},
@ref{904,,throw()} or @ref{906,,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{1a9,,AttributeError} missing @code{name} and @code{obj}
attributes in @ref{f90,,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{885,,sys.activate_stack_trampoline()} and
@ref{886,,sys.deactivate_stack_trampoline()} function in the @ref{e2,,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{887,,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{1a5,,PyGILState_Ensure()} when allocating
new thread state. Patch by Kumar Aditya.

@item 
gh-96046@footnote{https://github.com/python/cpython/issues/96046}: @ref{b5e,,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{1d3d,,ENOTCAPABLE} is now mapped to
@ref{10f9,,PermissionError}. The @ref{5a,,errno} modules exposes the new error
number. @code{getpath.py} now ignores @code{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{ad6,,try}/@ref{447,,except} blocks to
handle exceptions raised during @ref{199e,,close()} or
@ref{905,,throw()} calls through a suspended frame.

@item 
gh-95977@footnote{https://github.com/python/cpython/issues/95977}: Optimized calling @ref{188a,,__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{b6d,,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{327,,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{4d9,,list} from @ref{125b,,str.split()}
and @ref{15fa,,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{18a7,,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{1121,,RecursionError} is
now raised instead. Patch by Pablo Galindo

@item 
gh-93351@footnote{https://github.com/python/cpython/issues/93351}: @ref{2ec,,ast.AST} node positions are now validated when provided
to @ref{1c8,,compile()} and other related functions. If invalid positions are
detected, a @ref{277,,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{1d1c,,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.
@end itemize

@node Library<86>,Core and Builtins<85>,Core and Builtins<84>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id386}@anchor{1d3e}
@subsubsection Library



@itemize -

@item 
gh-95023@footnote{https://github.com/python/cpython/issues/95023}: Implement @ref{1d3f,,os.setns()} and  @ref{1d40,,os.unshare()} for Linux.
Patch by Noam Cohen.
@end itemize

@node Core and Builtins<85>,Library<87>,Library<86>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id387}@anchor{1d41}
@subsubsection Core and Builtins



@itemize -

@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.
@end itemize

@node Library<87>,Core and Builtins<86>,Core and Builtins<85>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id388}@anchor{1d42}
@subsubsection Library



@itemize -

@item 
gh-94996@footnote{https://github.com/python/cpython/issues/94996}: @ref{1c9,,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.
@end itemize

@node Core and Builtins<86>,Library<88>,Library<87>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id389}@anchor{1d43}
@subsubsection Core and Builtins



@itemize -

@item 
gh-94739@footnote{https://github.com/python/cpython/issues/94739}: Allow jumping within, out of, and across exception handlers in
the debugger.
@end itemize

@node Library<88>,Core and Builtins<87>,Core and Builtins<86>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id390}@anchor{1d44}
@subsubsection Library



@itemize -

@item 
gh-94949@footnote{https://github.com/python/cpython/issues/94949}: @ref{1c9,,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{1c9,,ast.parse()} will no longer parse assignment expressions
when passed @code{feature_version} less than @code{(3, 8)}. Patch by Shantanu
Jain.
@end itemize

@node Core and Builtins<87>,Library<89>,Library<88>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id391}@anchor{1d45}
@subsubsection Core and Builtins



@itemize -

@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{9,,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{1c6,,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{189,,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{8ee,,BINARY_SLICE} and @ref{8ef,,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{bc7,,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.
@end itemize

@node Library<89>,Core and Builtins<88>,Core and Builtins<87>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id392}@anchor{1d46}
@subsubsection Library



@itemize -

@item 
gh-93461@footnote{https://github.com/python/cpython/issues/93461}: @ref{fcf,,importlib.invalidate_caches()} now drops entries from
@ref{9db,,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}.
@end itemize

@node Core and Builtins<88>,Library<90>,Library<89>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id393}@anchor{1d47}
@subsubsection Core and Builtins



@itemize -

@item 
gh-93621@footnote{https://github.com/python/cpython/issues/93621}: Change order of bytecode instructions emitted for
@ref{20a,,with} and @ref{20b,,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{b5a,,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{9,,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{391,,PyType_FromMetaclass()}, which
generalizes the existing @ref{390,,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{391,,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.
@end itemize

@node Library<90>,Core and Builtins<89>,Core and Builtins<88>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id394}@anchor{1d48}
@subsubsection Library



@itemize -

@item 
gh-91102@footnote{https://github.com/python/cpython/issues/91102}: @code{_warnings.warn_explicit()} is ported to Argument Clinic.
@end itemize

@node Core and Builtins<89>,Library<91>,Library<90>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id395}@anchor{1d49}
@subsubsection Core and Builtins



@itemize -

@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.
@end itemize

@node Library<91>,Core and Builtins<90>,Core and Builtins<89>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id396}@anchor{1d4a}
@subsubsection Library



@itemize -

@item 
gh-92261@footnote{https://github.com/python/cpython/issues/92261}: Fix hang when trying to iterate over a @code{typing.Union}.
@end itemize

@node Core and Builtins<90>,Library<92>,Library<91>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id397}@anchor{1d4b}
@subsubsection Core and Builtins



@itemize -

@item 
gh-91432@footnote{https://github.com/python/cpython/issues/91432}: Specialized the @ref{1cc4,,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{4d9,,list} and
@ref{1ce,,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<92>,Documentation<28>,Core and Builtins<90>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id398}@anchor{1d4c}
@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{b,,asyncio} with @ref{9fe,,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{a5,,os} module no longer accepts bytes-like paths, like
@ref{1c6,,bytearray} and @ref{1d2,,memoryview} types: only the exact
@ref{1c7,,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{a4b,,createSocket()} method
was added to @ref{a4c,,SysLogHandler}.

@item 
gh-96035@footnote{https://github.com/python/cpython/issues/96035}: Fix bug in @ref{2a4,,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{18a0,,sys.setprofile()} and @ref{55c,,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{11a,,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
@code{asyncio.AbstractEventLoopPolicy.get_child_watcher()} and
@code{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{94d,,syslog.syslog()} in multi-threaded
applications. On macOS, the libc @code{syslog()} function is not thread-safe,
so @code{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{23c,,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
@code{MultiLoopChildWatcher},
@code{FastChildWatcher} and @code{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
@code{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{93,,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{80,,importlib.util}.

@item 
gh-97837@footnote{https://github.com/python/cpython/issues/97837}: Change deprecate warning message in @ref{10f,,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{1a9,,AttributeError} when @ref{136b,,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{665,,NameError} and @ref{1a9,,AttributeError} spelling suggestions
provided since gh-82711@footnote{https://github.com/python/cpython/issues/82711} are now also emitted by the pure Python
@ref{107,,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{bec,,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{b,,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{1b2c,,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{e6,,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{b,,asyncio} where
@ref{1d4d,,process_exited()} called before the
@ref{1d4e,,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{1d4f,,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{10e,,unicodedata} database to Unicode 15.0.0.

@item 
gh-96735@footnote{https://github.com/python/cpython/issues/96735}: Fix undefined behaviour in @ref{1a82,,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{1663,,numbers.Rational}’s to
@ref{327,,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{10d,,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{115a,,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{81,,inspect}, fix overeager replacement of «@code{typing.}» in
formatting annotations.

@item 
gh-89258@footnote{https://github.com/python/cpython/issues/89258}: Added a @ref{1d50,,getChildren()} method to
@ref{f0c,,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{12b,,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{1d51,,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{1d52,,strftime() and strptime() behavior}.

@item 
gh-95899@footnote{https://github.com/python/cpython/issues/95899}: Fix @ref{30a,,asyncio.Runner} to call
@ref{1d53,,asyncio.set_event_loop()} only once to avoid calling
@code{attach_loop()} multiple times on child
watchers. Patch by Kumar Aditya.

@item 
gh-95736@footnote{https://github.com/python/cpython/issues/95736}: Fix @ref{342,,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{1d4f,,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{6da,,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{cd0,,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{6d7,,asyncio.TaskGroup} to propagate exception when
@ref{6da,,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{8b6,,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{1ab6,,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{1d54,,EPERM} or
@ref{1d55,,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{309,,asyncio.run()} for @ref{460,,asyncio.Task}
implementations without @ref{6dc,,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{3e,,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{1d56,,os.EFD_CLOEXEC},
@ref{1d57,,os.EFD_NONBLOCK} and @ref{1d58,,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{473,,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{d7,,sqlite3} regression where @code{*args} and @code{**kwds}
were incorrectly relayed from @ref{3e0,,connect()} to the
@ref{3df,,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{5e,,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{1c47,,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{1c9,,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{d7,,sqlite3} @ref{257,,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{f8,,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{1d27,,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{107,,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{b,,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{900,,typing.Hashable} and
@ref{901,,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{10d,,typing}. Previously an error message saying @code{Some type variables
... are not listed in Generic[...]} was shown. @code{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{7a,,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{309,,asyncio.run()} and
@ref{342,,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{2fb,,struct.Struct} when it was not completely
initialized by initializing it in @ref{982,,__new__()}.  Patch by Kumar
Aditya.

@item 
gh-94510@footnote{https://github.com/python/cpython/issues/94510}: Re-entrant calls to @ref{18a0,,sys.setprofile()} and
@ref{55c,,sys.settrace()} now raise @ref{30d,,RuntimeError}. Patch by Pablo
Galindo.

@item 
gh-92336@footnote{https://github.com/python/cpython/issues/92336}: Fix bug where @ref{4cd,,linecache.getline()} fails on bad files with
@ref{dd7,,UnicodeDecodeError} or @ref{17e,,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{6d7,,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{942,,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{13b,,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{949,,shlex.split()}: Passing @code{None} for `s' argument now
raises an exception, rather than reading @ref{94a,,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{bd,,pydoc} text output.

@item 
gh-89988@footnote{https://github.com/python/cpython/issues/89988}: Fix memory leak in @ref{de2,,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{d7,,sqlite3} @ref{8fd,,default adapters and converters}. Patch by Erlend E. Aasland.

@item 
gh-94254@footnote{https://github.com/python/cpython/issues/94254}: Fixed types of @ref{de,,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{8c3,,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{3b,,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{92d,,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{336,,ssl.SSLContext} object and call its
@ref{933,,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{931,,os.urandom()} or @ref{932,,ssl.RAND_bytes()} instead.
Patch by Victor Stinner.

@item 
gh-94199@footnote{https://github.com/python/cpython/issues/94199}: @ref{6b,,hashlib}: Remove the pure Python implementation of
@ref{91e,,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 @code{pbkdf2_hmac()} which is faster. Patch by
Victor Stinner.

@item 
gh-94196@footnote{https://github.com/python/cpython/issues/94196}: @ref{6a,,gzip}: Remove the @code{filename} attribute of
@ref{849,,gzip.GzipFile}, deprecated since Python 2.6, use the
@ref{91c,,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 @code{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{32b,,open()} instead. The @code{open()}
(@ref{92b,,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{aa,,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{109b,,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{302,,inspect.iscoroutinefunction()},
@ref{1d59,,inspect.isgeneratorfunction()}, and
@ref{1d5a,,inspect.isasyncgenfunction()} now properly return @code{True} for
duck-typed function-like objects like instances of
@ref{e0d,,unittest.mock.AsyncMock}.

This makes @ref{302,,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{d7,,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{a14,,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{c1,,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{e9,,tempfile}.

@item 
gh-93820@footnote{https://github.com/python/cpython/issues/93820}: Fixed a regression when @ref{942,,copy.copy()}-ing @ref{a14,,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{11d,,weakref} classes
@ref{1d5b,,ReferenceType}, @ref{1d5c,,ProxyType},
@ref{1d5d,,CallableProxyType}. It makes them pickleable.

@item 
gh-91389@footnote{https://github.com/python/cpython/issues/91389}: Fix an issue where @ref{3b,,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{942,,copy.copy()} and @ref{f2b,,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{d7,,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{1d5e,,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{5c,,fcntl}. Patch by Illia Volochii.

@item 
gh-93370@footnote{https://github.com/python/cpython/issues/93370}: Deprecate @code{version} and @code{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{89f,,importlib.resources.as_file()} context manager to
remove the temporary file if destroyed late during Python finalization:
keep a local reference to the @ref{149c,,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{8ab,,os.PIDFD_NONBLOCK} flag to open a file descriptor
for a process with @ref{267,,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{291,,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{1dc,,argparse.ArgumentParser} to use
@ref{948,,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{bf9,,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{1559,,logging.config.dictConfig()} to
usefully configure @ref{1d5f,,QueueHandler} and
@ref{4cf,,QueueListener} as a pair, and add
@ref{1d60,,logging.getHandlerByName()} and @ref{1c74,,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{e37,,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{8a,,logging} module for use
with @ref{b,,asyncio} tasks.

@item 
gh-74696@footnote{https://github.com/python/cpython/issues/74696}: @ref{8c3,,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{5f,,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{3e0,,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{cb6,,ast.unparse()} when @code{ImportFrom.level} is @code{None}

@item 
gh-92932@footnote{https://github.com/python/cpython/issues/92932}: Now @ref{496,,dis()} and @ref{6f1,,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{4ee,,pathlib.Path} arguments in addition to @ref{1df,,str} paths. Patch
by David Foster.

@item 
gh-87901@footnote{https://github.com/python/cpython/issues/87901}: Removed the @code{encoding} argument from @ref{585,,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{1d61,,c_time_t} to @ref{2d,,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{df,,subprocess} now fails early on Emscripten and WASI
platforms to work around missing @ref{1d62,,os.pipe()} on WASI.

@item 
gh-89325@footnote{https://github.com/python/cpython/issues/89325}: Removed many old deprecated @ref{10f,,unittest} features:
@ref{52f,,TestCase} method aliases, undocumented and broken
@code{TestCase} method @code{assertDictContainsSubset},
undocumented @ref{793,,TestLoader.loadTestsFromModule} parameter `use_load_tests', and
an underscored alias of the @ref{93f,,TextTestResult} class.

@item 
gh-92734@footnote{https://github.com/python/cpython/issues/92734}: Allow multi-element reprs emitted by @ref{c3,,reprlib} to be
pretty-printed using configurable indentation.

@item 
gh-92671@footnote{https://github.com/python/cpython/issues/92671}: Fixed @ref{cb6,,ast.unparse()} for empty tuples in the assignment
target context.

@item 
gh-91581@footnote{https://github.com/python/cpython/issues/91581}: @ref{32f,,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{1d63,,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{8b8,,pathlib.Path.walk()} as an alternative to
@ref{8b9,,os.walk()}.

@item 
gh-92550@footnote{https://github.com/python/cpython/issues/92550}: Fix @ref{73b,,pathlib.Path.rglob()} for empty pattern.

@item 
gh-92591@footnote{https://github.com/python/cpython/issues/92591}: Allow @ref{8a,,logging} filters to return a
@ref{138f,,logging.LogRecord} instance so that filters attached to
@ref{1838,,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{7,,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{d7,,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{1d64,,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{4ee,,pathlib.Path} deprecated method @code{link_to} has been
removed. Use 3.10’s @ref{bfa,,hardlink_to()} method instead as
its semantics are consistent with that of
@ref{bfb,,symlink_to()}.

@item 
gh-89336@footnote{https://github.com/python/cpython/issues/89336}: Removed @ref{26,,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{b21,,__class_getitem__()} to
@ref{da9,,csv.DictReader} and @ref{15a7,,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{d4,,socket}.

@item 
gh-91810@footnote{https://github.com/python/cpython/issues/91810}: @ref{d19,,ElementTree} method
@ref{e5b,,write()} and function
@ref{139e,,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{fb4,,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{206,,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{8fb,,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{7a1,,re.sub()} and @ref{7a2,,re.subn()} and corresponding @ref{194d,,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{ab1,,zipfile.ZipFile} now raises @ref{1d65,,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{6bb,,property()}.

@item 
gh-90005@footnote{https://github.com/python/cpython/issues/90005}: @ref{2d,,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{15a7,,DictWriter} and
@ref{da9,,DictReader} now coerce the @code{fieldnames} argument to a
@ref{4d9,,list} if it is an iterator.

@item 
bpo-35540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35540}: Fix @ref{190d,,dataclasses.asdict()} crash when
@ref{1565,,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{1c7,,bytes} on @ref{194,,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{ddb,,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{ca9,,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{294,,typing.TypeVar}, @ref{295,,typing.ParamSpec},
@ref{293,,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{b,,asyncio} to AIX platform only.

@item 
bpo-28249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28249}: Set @ref{1a07,,doctest.DocTest.lineno} to @code{None} when an object
does not have @ref{cf4,,__doc__}.

@item 
bpo-46197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46197}: Fix @ref{58,,ensurepip} environment isolation for subprocess
running @code{pip}.

@item 
bpo-45924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45924}: Fix @ref{b,,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{10f,,unittest}: methods
@ref{aa6,,enterContext()} and
@ref{aa7,,enterClassContext()} of class
@ref{52f,,TestCase}, method
@ref{aa8,,enterAsyncContext()} of class
@ref{342,,IsolatedAsyncioTestCase} and function
@ref{aa9,,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{e01,,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{8d6,,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
@ref{1566,,__missing__()} when a value is not found. This matches the
behavior of @ref{188,,dict}. Patch by Bar Harel.

@item 
bpo-38693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38693}: @ref{7a,,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{cb8,,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{30a,,asyncio.Runner} or @ref{309,,asyncio.run()}, the
default timeout is 5 minutes.

@item 
bpo-34828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34828}: @ref{751,,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{11c,,wave} module.

@item 
bpo-26253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26253}: Allow adjustable compression level for tarfile streams in
@ref{1228,,tarfile.open()}.
@end itemize

@node Documentation<28>,Tests<31>,Library<92>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id399}@anchor{1d66}
@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{9,,ast}
documentation about @ref{fd7,,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{1d67,,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{1d68,,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{d7,,sqlite3} behavior when
@ref{1d69,,How to use the connection context manager}.

@item 
gh-87260@footnote{https://github.com/python/cpython/issues/87260}: Align @ref{d7,,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{1c0,,-W} and 
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,PYTHONWARNINGS} are
matched literally and case-insensitively, rather than as regular
expressions, in @ref{11b,,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{8b6,,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{22c,,inspect.getdoc()},
@ref{1d6a,,inspect.getmodule()}, and @ref{1d6b,,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{1d6c,,Error Handlers} documentation in
@ref{1c,,codecs}.

@item 
bpo-13553@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13553}: Document tkinter.Tk args.
@end itemize

@node Tests<31>,Build<32>,Documentation<28>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id400}@anchor{1d6d}
@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/main/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{1d6e,,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{c1,,re} exponentional slowdown when
using rjsmin.

@item 
gh-91330@footnote{https://github.com/python/cpython/issues/91330}: Added more tests for @ref{32,,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{1d6f,,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{1d70,,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 μεταβλητή περιβάλλοντος; 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{1cda,,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{72c,,os.chmod()} is
now a dummy function on WASI. Skip all tests that depend on working
@code{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<32>,Windows<28>,Tests<31>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id401}@anchor{1d71}
@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{24,,concurrent.futures} for @ref{b,,asyncio} and @ref{110,,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{c4,,resource}
module, @ref{16ba,,getresuid()}, @ref{16b9,,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{5a,,errno}, @ref{c9,,select}, and @ref{d4,,socket}
constants.

@item 
gh-95174@footnote{https://github.com/python/cpython/issues/95174}: Python now skips missing @ref{d4,,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{1023,,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{c2,,readline} and @ref{2e,,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<28>,macOS<21>,Build<32>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id402}@anchor{1d72}
@subsubsection Windows



@itemize -

@item 
gh-98360@footnote{https://github.com/python/cpython/issues/98360}: Fixes @ref{98,,multiprocessing} spawning child processes on Windows
from a virtual environment to ensure that child processes that also use
@code{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{17ff,,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{9bc,,Διαχειριστής εγκατάστασης Python} 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{af,,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{c17,,enable_load_extension()}
@ref{d7,,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{9bc,,Διαχειριστής εγκατάστασης Python} for @code{/usr/bin/env}
shebang lines, which will now search 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; 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{9bc,,Διαχειριστής εγκατάστασης Python} 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{9bc,,Διαχειριστής εγκατάστασης Python} 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{13a,,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{14ae,,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{b,,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{1965,,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<21>,IDLE<16>,Windows<28>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id403}@anchor{1d73}
@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{1149,,os.mkfifo()} or @ref{114a,,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<16>,Tools/Demos<22>,macOS<21>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id404}@anchor{1d74}
@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<22>,C API<30>,IDLE<16>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id405}@anchor{1d75}
@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<30>,,Tools/Demos<22>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id407}@anchor{1d76}
@subsubsection C API



@itemize -

@item 
gh-98393@footnote{https://github.com/python/cpython/issues/98393}: The @ref{97b,,PyUnicode_FSDecoder()} function no longer accepts
bytes-like paths, like @ref{1c6,,bytearray} and @ref{1d2,,memoryview} types:
only the exact @ref{1c7,,bytes} type is accepted for bytes strings. Patch by
Victor Stinner.

@item 
gh-91051@footnote{https://github.com/python/cpython/issues/91051}: Add @ref{96b,,PyType_Watch()} and related APIs to allow callbacks
on @ref{1d77,,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{9ec,,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{39c,,Py_TPFLAGS_MANAGED_DICT}
and @ref{39d,,Py_TPFLAGS_MANAGED_WEAKREF} instead.

@item 
gh-95781@footnote{https://github.com/python/cpython/issues/95781}: An unrecognized format character in
@ref{81e,,PyUnicode_FromFormat()} and @ref{979,,PyUnicode_FromFormatV()} now
sets a @ref{3ea,,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{95d,,Py_TPFLAGS_HAVE_VECTORCALL}, @ref{95e,,PyVectorcall_NARGS()} and
@ref{95f,,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{81e,,PyUnicode_FromFormat()} and @ref{979,,PyUnicode_FromFormatV()}. Patch
by Philip Georgi.

@item 
gh-93012@footnote{https://github.com/python/cpython/issues/93012}: The @ref{95d,,Py_TPFLAGS_HAVE_VECTORCALL} flag is now removed
from a class when the class’s @ref{961,,__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{962,,tp_call} now inherit the
@code{Py_TPFLAGS_HAVE_VECTORCALL} flag.

@item 
gh-95388@footnote{https://github.com/python/cpython/issues/95388}: Creating @ref{5fb,,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{b5b,,PyCode_GetVarnames()}, @ref{b5c,,PyCode_GetCellvars()}
and @ref{b5d,,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{818,,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{b64,,PyFrame_Check()}

@item 
@ref{b65,,PyFrame_GetBack()}

@item 
@ref{b4d,,PyFrame_GetBuiltins()}

@item 
@ref{b4e,,PyFrame_GetGenerator()}

@item 
@ref{b4f,,PyFrame_GetGlobals()}

@item 
@ref{b50,,PyFrame_GetLasti()}

@item 
@ref{84e,,PyFrame_GetLocals()}

@item 
@ref{b66,,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{391,,PyType_FromMetaclass()} (and other @code{PyType_From*}
functions) now check that offsets and the base class’s
@ref{d4f,,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{966,,PyEval_SetProfileAllThreads()} and
@ref{851,,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{f6,,threading} module
(@ref{8d9,,threading.setprofile_all_threads()} and
@ref{8d8,,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{61d,,Py_IgnoreEnvironmentFlag}, in the documentation: the
@ref{60a,,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{61d,,Py_IgnoreEnvironmentFlag}: the @ref{60a,,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{834,,PyConfig.module_search_paths} are
ignored unless @ref{9e6,,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{967,,PyFunction_SetVectorcall()} to the C API
which sets the vectorcall field of a given @ref{968,,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{38e,,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{1d78}
@subsection Python 3.11.0 beta 1


`Release date: 2022-05-06'

@menu
* Security: Security<27>. 
* Core and Builtins: Core and Builtins<91>. 
* Library: Library<93>. 
* Core and Builtins: Core and Builtins<92>. 
* Build: Build<33>. 
* Core and Builtins: Core and Builtins<93>. 
* Library: Library<94>. 
* Documentation: Documentation<29>. 
* Tests: Tests<32>. 
* Build: Build<34>. 
* Windows: Windows<29>. 
* macOS: macOS<22>. 
* Tools/Demos: Tools/Demos<23>. 
* C API: C API<31>. 

@end menu

@node Security<27>,Core and Builtins<91>,,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id408}@anchor{1d79}
@subsubsection Security



@itemize -

@item 
gh-57684@footnote{https://github.com/python/cpython/issues/57684}: Add the @ref{9a3,,-P} command line option and the
@geindex PYTHONSAFEPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONSAFEPATH
@ref{9a4,,PYTHONSAFEPATH} environment variable to not prepend a potentially
unsafe path to @ref{194,,sys.path}. Patch by Victor Stinner.
@end itemize

@node Core and Builtins<91>,Library<93>,Security<27>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id409}@anchor{1d7a}
@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{1a9,,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{185,,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{527,,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{2c9,,DeprecationWarning}. In a future Python version they will be a
@ref{44a,,SyntaxWarning} and eventually a @ref{17e,,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{2ef,,isinstance()} and @ref{2f0,,issubclass()} checks for
@ref{527,,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{b68,,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{9b9,,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, @code{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{1c65,,POP_JUMP_IF_TRUE}, @ref{1c66,,POP_JUMP_IF_FALSE},
@ref{1d7b,,POP_JUMP_IF_NONE} and @ref{1d7c,,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.
@end itemize

@node Library<93>,Core and Builtins<92>,Core and Builtins<91>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id410}@anchor{1d7d}
@subsubsection Library



@itemize -

@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.
@end itemize

@node Core and Builtins<92>,Build<33>,Library<93>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id411}@anchor{1d7e}
@subsubsection Core and Builtins



@itemize -

@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{441,,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{1908,,pickle.PickleBuffer}, @code{testcapi.RecursingInfinitelyError},
and @ref{bc7,,types.GenericAlias}.

The functions affected are 24 methods in @ref{2d,,ctypes}.

Patch by Oleg Iarygin.

@item 
bpo-46942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46942}: Use Argument Clinic for the @ref{1d7f,,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 @ref{1d80,,set.intersection()} for non-set arguments.

@item 
bpo-46721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46721}: Optimize @ref{1d81,,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.
@end itemize

@node Build<33>,Core and Builtins<93>,Core and Builtins<92>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id412}@anchor{1d82}
@subsubsection Build



@itemize -

@item 
bpo-46045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46045}: Do not use POSIX semaphores on NetBSD
@end itemize

@node Core and Builtins<93>,Library<94>,Build<33>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id413}@anchor{1d83}
@subsubsection Core and Builtins



@itemize -

@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<94>,Documentation<29>,Core and Builtins<93>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id414}@anchor{1d84}
@subsubsection Library



@itemize -

@item 
gh-87901@footnote{https://github.com/python/cpython/issues/87901}: Add the `encoding' parameter to @ref{585,,os.popen()}.

@item 
gh-90997@footnote{https://github.com/python/cpython/issues/90997}: Fix an issue where @ref{3b,,dis} utilities may interpret populated
inline cache entries as valid instructions.

@item 
gh-92332@footnote{https://github.com/python/cpython/issues/92332}: Deprecate @ref{340,,typing.Text} (removal of the class is
currently not planned). Patch by Alex Waygood.

@item 
gh-78157@footnote{https://github.com/python/cpython/issues/78157}: 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{3b,,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{df,,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{a0a,,datetime.datetime.fromisoformat()},
@ref{a08,,datetime.date.fromisoformat()} and
@ref{a09,,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{20e,,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{6e6,,@@~dataclasses.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{b21,,__class_getitem__()} to
@ref{169a,,logging.LoggerAdapter} and @ref{15a1,,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{6e9,,inspect.Parameter} now raises @ref{277,,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{bc7,,types.GenericAlias}. Patch by Jelle Zijlstra.

@item 
gh-88089@footnote{https://github.com/python/cpython/issues/88089}: Add support for generic @ref{2e4,,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{136c,,subprocess.getoutput()} and @ref{136d,,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{1d85,,multiprocessing.Queue} `after' the last write of buffered data to
the write end of the pipe to avoid @ref{1404,,BrokenPipeError} at garbage
collection and at @ref{1d86,,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{93,,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{df,,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{1d87,,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{98,,multiprocessing} and @ref{b,,asyncio} modules.

@item 
gh-91860@footnote{https://github.com/python/cpython/issues/91860}: Add @ref{8e4,,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{1d88,,argparse.Action} repr
output.

@item 
gh-91827@footnote{https://github.com/python/cpython/issues/91827}: In the @ref{f9,,tkinter} module add method @code{info_patchlevel()}
which returns the exact version of the Tcl library as a named tuple
similar to @ref{2fc,,sys.version_info}.

@item 
gh-84461@footnote{https://github.com/python/cpython/issues/84461}: Add @ref{1d89,,--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{1d8a,,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{1d8b,,signal.raise_signal()} and @ref{170c,,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{a95,,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{a9e,,typing.get_type_hints()} for
@ref{bc6,,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{c1,,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{e4,,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{c1,,re} module, fix @ref{1330,,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{c1,,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{a62,,create_connection()} in an @ref{6d8,,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{c1,,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{d7,,sqlite3}, @code{SQLITE_MISUSE} result codes are now mapped
to @ref{a6d,,InterfaceError} instead of
@ref{57d,,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{81,,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{a3e,,inspect.getframeinfo()},
@ref{a3f,,inspect.getouterframes()}, @ref{a40,,inspect.getinnerframes()},
@ref{a41,,inspect.stack()} and @ref{a42,,inspect.trace()}. Patch by Pablo Galindo.

@item 
gh-69093@footnote{https://github.com/python/cpython/issues/69093}: Add indexing and slicing support to @ref{a72,,sqlite3.Blob}. Patch
by Aviv Palivoda and Erlend E. Aasland.

@item 
gh-69093@footnote{https://github.com/python/cpython/issues/69093}: Add @ref{478,,context manager} support to @ref{a72,,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{c1,,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{3b,,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{423,,warnings.catch_warnings()} now accepts arguments for
@ref{aae,,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 
gh-91498@footnote{https://github.com/python/cpython/issues/91498}: Add the @code{TCP_CONNECTION_INFO} option (available on macOS) to
@ref{d4,,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{a45,,locale.getencoding()} to get the current locale
encoding. It is similar to @code{locale.getpreferredencoding(False)} but
ignores the @ref{a46,,Python UTF-8 Mode}.

@item 
bpo-42012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42012}: Add @ref{125,,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{c1,,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{172b,,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{3e,,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{a9c,,typing.get_overloads()} and
@ref{a9d,,typing.clear_overloads()}. Patch by Jelle Zijlstra.

@item 
bpo-44807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44807}: @ref{76c,,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{206,,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{1d8c,,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{d4,,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{93,,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{75,,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 @code{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{ba4,,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{a83,,io.BufferedIOBase} or
@ref{a84,,io.TextIOBase} interface for
@ref{a82,,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{d7,,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{290,,TypedDict} subclasses to also include
@ref{19f2,,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{6bf,,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{a70,,create_window_function()} to
@ref{3df,,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{2c,,csv} to use Argument Clinic for
@ref{1d8d,,csv.field_size_limit()}, @ref{1d8e,,csv.get_dialect()},
@ref{1d8f,,csv.unregister_dialect()} and @ref{1d90,,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{57d,,ProgrammingError} instead of segfaulting
on recursive usage of cursors in @ref{d7,,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{336,,SSLContext}.

@item 
bpo-22276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22276}: @ref{4ee,,Path} methods @ref{73a,,glob()} and
@ref{73b,,rglob()} return only directories if `pattern' ends with
a pathname components separator (@code{/} or @ref{a5a,,sep}). Patch by
Eisuke Kawashima.

@item 
bpo-24905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24905}: Add @ref{a71,,blobopen()} to
@ref{3df,,sqlite3.Connection}. @ref{a72,,sqlite3.Blob} allows incremental I/O
operations on blobs. Patch by Aviv Palivoda and Erlend E. Aasland.
@end itemize

@node Documentation<29>,Tests<32>,Library<94>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id415}@anchor{1d91}
@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{882,,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{ded,,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{a6,,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{95c,,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{1d92,,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{1901,,runpy.run_module()} and
@ref{6ae,,runpy.run_path()}. Original patch by Andrew Brezovsky.
@end itemize

@node Tests<32>,Build<34>,Documentation<29>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id416}@anchor{1d93}
@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 μεταβλητή περιβάλλοντος; 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{10f,,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{1d94,,ipaddress.IPv4Interface} and
@ref{1d95,,ipaddress.IPv6Interface} construction with tuple arguments.
Original patch and tests by louisom.
@end itemize

@node Build<34>,Windows<29>,Tests<32>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id417}@anchor{1d96}
@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<29>,macOS<22>,Build<34>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id418}@anchor{1d97}
@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{9bc,,Διαχειριστής εγκατάστασης Python} 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{4f5,,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<22>,Tools/Demos<23>,Windows<29>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id419}@anchor{1d98}
@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<23>,C API<31>,macOS<22>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id420}@anchor{1d99}
@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<31>,,Tools/Demos<23>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id421}@anchor{1d9a}
@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{b5a,,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{1cd9,,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{54b,,Py_REFCNT()}, @ref{5f5,,Py_TYPE()}, @ref{b61,,Py_SIZE()} and
@ref{19bb,,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{1d9b,,PyOS_CheckStack()} is now exported in the Stable ABI on
Windows.

@item 
bpo-47169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47169}: @ref{1d9c,,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{b51,,PyErr_GetHandledException()} and
@ref{b52,,PyErr_SetHandledException()} as simpler alternatives to
@ref{b54,,PyErr_GetExcInfo()} and @ref{b53,,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{1d9d}
@subsection Python 3.11.0 alpha 7


`Release date: 2022-04-05'

@menu
* Core and Builtins: Core and Builtins<94>. 
* Library: Library<95>. 
* Core and Builtins: Core and Builtins<95>. 
* Library: Library<96>. 
* Core and Builtins: Core and Builtins<96>. 
* Library: Library<97>. 
* Documentation: Documentation<30>. 
* Tests: Tests<33>. 
* Build: Build<35>. 
* Windows: Windows<30>. 
* macOS: macOS<23>. 
* Tools/Demos: Tools/Demos<24>. 
* C API: C API<32>. 

@end menu

@node Core and Builtins<94>,Library<95>,,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id422}@anchor{1d9e}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-47212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47212}: Raise @ref{b89,,IndentationError} instead of @ref{17e,,SyntaxError} for
a bare @code{except} with no following indent. Improve @code{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{aef,,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{af7,,CHECK_EXC_MATCH} + jump.

@item 
bpo-47120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47120}: Replace the absolute jump opcode @ref{1d9f,,JUMP_NO_INTERRUPT} by
the relative @ref{aec,,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{53c,,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{af8,,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{b68,,PyFrameObject} by calling @ref{84e,,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.
@end itemize

@node Library<95>,Core and Builtins<95>,Core and Builtins<94>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id423}@anchor{1da0}
@subsubsection Library



@itemize -

@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{5b,,faulthandler} to avoid compilation problems in systems where this
header doesn’t exist. Patch by Pablo Galindo
@end itemize

@node Core and Builtins<95>,Library<96>,Library<95>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id424}@anchor{1da1}
@subsubsection Core and Builtins



@itemize -

@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{1c7,,bytes} and @ref{1c6,,bytearray} by
30%. Patch by Kumar Aditya.

@item 
bpo-47009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47009}: Improved the performance of @ref{aba,,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}.
@end itemize

@node Library<96>,Core and Builtins<96>,Core and Builtins<95>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id425}@anchor{1da2}
@subsubsection Library



@itemize -

@item 
bpo-46829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46829}: Deprecate passing a message into @ref{1da3,,asyncio.Future.cancel()}
and @ref{6d9,,asyncio.Task.cancel()}
@end itemize

@node Core and Builtins<96>,Library<97>,Library<96>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id426}@anchor{1da4}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-46993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46993}: Speed up @ref{1c6,,bytearray} creation from @ref{4d9,,list} and
@ref{1ce,,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{34b,,METH_FASTCALL} calling convention. Patch by Kumar Aditya.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Modify @ref{1da5,,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{af3,,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{1be2,,getter},
@ref{1be3,,setter}, and @ref{1be4,,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<97>,Documentation<30>,Core and Builtins<96>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id427}@anchor{1da6}
@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{c1,,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{460,,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{c1,,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{1181,,asyncio.loop.sock_connect()} to only resolve names for
@ref{1da7,,socket.AF_INET} or @ref{1da8,,socket.AF_INET6} families. Resolution
may not make sense for other families, like @ref{1da9,,socket.AF_BLUETOOTH}
and @ref{1daa,,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{1719,,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
@code{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{a7a,,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{6b,,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{6b,,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{9c8,,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{15d3,,re.search()}, @ref{7a0,,re.split()},
@ref{13d2,,re.findall()}, @ref{189c,,re.finditer()} and @ref{7a1,,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{189c,,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{ab1,,zipfile.ZipFile} constructor and the @code{--metadata-encoding}
option in the @ref{13a,,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{1c44,,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{1c19,,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{1c19,,binascii.crc32()} release the GIL when computing on
larger inputs as @ref{1c18,,zlib.crc32()} and @ref{6b,,hashlib} do.

This also boosts performance on Windows as it now uses the zlib crc32
implementation for @ref{1c19,,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{c1,,regular expressions}.

@item 
bpo-47062@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47062}: Implement @ref{30a,,asyncio.Runner} context manager.

@item 
bpo-46382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46382}: @ref{6e6,,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{891,,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{a33,,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{e37,,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{1159,,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{a9a,,typing.Any}. Patch by Shantanu
Jain.

@item 
bpo-46995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46995}: Deprecate missing @ref{da1,,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{462,,asyncio.create_task()} and @ref{463,,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{5b,,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{a53,,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{ed6,,asyncio.Server}. Patch by Stefan Zabka.

@item 
bpo-23325@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23325}: The @ref{ce,,signal} module no longer assumes that
@ref{1dab,,SIG_IGN} and @ref{1dac,,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{ba,,pwd} module is now optional.
@ref{dd8,,os.path.expanduser()} returns the path when the @code{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{105,,tomllib} module. Adds support for parsing
TOML.

@item 
bpo-464471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=464471}: @ref{9f5,,asyncio.timeout()} and @ref{1dad,,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{d09,,typing.Annotated} to wrap @ref{ba6,,typing.ParamSpecArgs} and
@ref{1dae,,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{65c,,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{11a,,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{1daf,,sysconfig.get_default_scheme()} and
@ref{a7f,,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{a9e,,typing.get_type_hints()} now supports evaluating strings
as forward references in @ref{a9f,,PEP 585 generic aliases}.

@item 
bpo-46607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46607}: Add @ref{2c9,,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{bd,,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{a99,,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{335,,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{10b1,,typing.NewType}.

@item 
bpo-40296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40296}: Fix supporting generic aliases in @ref{bd,,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{8a,,logging} module so that it is consistent across all
logging functions and, as advertised, similar to the @code{stacklevel}
argument used in @ref{18bb,,warn()}.

@item 
bpo-24959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24959}: Fix bug where @ref{10f,,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{d7,,sqlite3}.


@itemize *

@item 
Raise @ref{a6d,,InterfaceError} instead of
@ref{57d,,ProgrammingError} for @code{SQLITE_MISUSE} errors.

@item 
Don’t overwrite @ref{1998,,BufferError} with @ref{277,,ValueError} when conversion to
BLOB fails.

@item 
Raise @ref{57d,,ProgrammingError} instead of @ref{1db0,,Warning} if
user tries to @ref{7a8,,execute()} more than one SQL statement.

@item 
Raise @ref{57d,,ProgrammingError} instead of @ref{277,,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{a6e,,serialize()} and
@ref{a6f,,deserialize()} support to @ref{d7,,sqlite3}. Patch
by Erlend E. Aasland.

@item 
bpo-33178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33178}: Added @ref{1db1,,ctypes.BigEndianUnion} and
@ref{1db2,,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{c1,,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<30>,Tests<33>,Library<97>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id428}@anchor{1db3}
@subsubsection Documentation



@itemize -

@item 
bpo-45099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45099}: Document internal @ref{b,,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{1c19,,binascii.crc32()} / @ref{1db4,,zlib.adler32()} / @ref{1c18,,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{1db5,,Defining Extension Types; Tutorial} 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{d96,,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<33>,Build<35>,Documentation<30>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id429}@anchor{1db6}
@subsubsection Tests



@itemize -

@item 
bpo-47205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47205}: Skip test for @ref{14b6,,sched_getaffinity()} and
@ref{14ba,,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{cb9,,asyncio.to_thread()} tests to use
@ref{342,,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{ed3,,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{b,,asyncio}. Patch by
Oleg Iarygin.
@end itemize

@node Build<35>,Windows<30>,Tests<33>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id430}@anchor{1db7}
@subsubsection Build



@itemize -

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: Add configure option @ref{1db8,,--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{f9,,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{d7,,sqlite3} extension module are found.
@end itemize

@node Windows<30>,macOS<23>,Build<35>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id431}@anchor{1db9}
@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{9bc,,Διαχειριστής εγκατάστασης Python} 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 μεταβλητή περιβάλλοντος; 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<23>,Tools/Demos<24>,Windows<30>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id432}@anchor{1dba}
@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{11a,,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<24>,C API<32>,macOS<23>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id433}@anchor{1dbb}
@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<32>,,Tools/Demos<24>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id434}@anchor{1dbc}
@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{1dbd,,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{f4a,,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{1dbe,,sys.get_asyncgen_hooks()} and
@ref{1baa,,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{b47,,PyFloat_Pack2()}, @ref{b48,,PyFloat_Pack4()},
@ref{b49,,PyFloat_Pack8()}, @ref{b4a,,PyFloat_Unpack2()},
@ref{b4b,,PyFloat_Unpack4()} and @ref{b4c,,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{1dbf}
@subsection Python 3.11.0 alpha 6


`Release date: 2022-03-07'

@menu
* Core and Builtins: Core and Builtins<97>. 
* Library: Library<98>. 
* Core and Builtins: Core and Builtins<98>. 
* Library: Library<99>. 
* Core and Builtins: Core and Builtins<99>. 
* Library: Library<100>. 
* Core and Builtins: Core and Builtins<100>. 
* Library: Library<101>. 
* Documentation: Documentation<31>. 
* Tests: Tests<34>. 
* Build: Build<36>. 
* Windows: Windows<31>. 
* IDLE: IDLE<17>. 
* C API: C API<33>. 

@end menu

@node Core and Builtins<97>,Library<98>,,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id435}@anchor{1dc0}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-46940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46940}: Avoid overriding @ref{1a9,,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{595,,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{1dc1,,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{d32,,COMPARE_OP} followed by @ref{1d1c,,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{8ed,,LOAD_ATTR},
@code{LOAD_METHOD}, and @ref{1dc2,,STORE_ATTR}.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Use inline cache for @code{BINARY_SUBSCR}.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Use inline caching for @ref{d32,,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{1dc3,,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{1c60,,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{595,,BINARY_OP} caches inline using a new
@ref{ae6,,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{8ed,,LOAD_ATTR} and
@ref{1dc2,,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{d32,,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.
@end itemize

@node Library<98>,Core and Builtins<98>,Core and Builtins<97>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id436}@anchor{1dc4}
@subsubsection Library



@itemize -

@item 
bpo-46794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46794}: Bump up the libexpat version into 2.4.6
@end itemize

@node Core and Builtins<98>,Library<99>,Library<98>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id437}@anchor{1dc5}
@subsubsection Core and Builtins



@itemize -

@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{167a,,__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{595,,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.
@end itemize

@node Library<99>,Core and Builtins<99>,Core and Builtins<98>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id438}@anchor{1dc6}
@subsubsection Library



@itemize -

@item 
bpo-46323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46323}: @ref{2d,,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.
@end itemize

@node Core and Builtins<99>,Library<100>,Library<99>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id439}@anchor{1dc7}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-45923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45923}: Add a quickened form of @ref{7b4,,RESUME} that skips quickening
checks.

@item 
bpo-46702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46702}: Specialize @ref{1dc3,,UNPACK_SEQUENCE} for @ref{1ce,,tuple} and
@ref{4d9,,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.
@end itemize

@node Library<100>,Core and Builtins<100>,Core and Builtins<99>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id440}@anchor{1dc8}
@subsubsection Library



@itemize -

@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{963,,PyObject_Vectorcall()} while calling ctypes callback
function. Patch by Donghee Na.
@end itemize

@node Core and Builtins<100>,Library<101>,Library<100>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id441}@anchor{1dc9}
@subsubsection Core and Builtins



@itemize -

@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{1dca,,PyLong_FromLong()}, and added a fast path for single-digit integers
to @ref{1dcb,,PyLong_FromLongLong()}.
@end itemize

@node Library<101>,Documentation<31>,Core and Builtins<100>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id442}@anchor{1dcc}
@subsubsection Library



@itemize -

@item 
bpo-25707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25707}: Fixed a file leak in @ref{3eb,,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{1a31,,unittest.doModuleCleanups()} in @ref{10f,,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{1dcd,,find()} and @ref{1dce,,rfind()} for
@code{find()} and @code{rfind()}.

@item 
bpo-46736@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46736}: @ref{22a,,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{1d25,,asyncio.DatagramTransport}.

@item 
bpo-46827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46827}: Support UDP sockets in  @ref{1181,,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{291,,TypeError} if @ref{cbb,,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{335,,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{6da,,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{1dcf,,urllib.request.HTTPPasswordMgr.find_user_password()} and
@ref{1dd0,,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{1dd1,,random.gauss()} and @ref{1dd2,,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{3b,,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{1dd3,,typing.ForwardRef} now
includes the @code{module} parameter of @code{typing.ForwardRef} when it is
set.

@item 
bpo-46643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46643}: In @ref{a9e,,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{e7,,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{290,,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{295,,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{9f4,,asyncio.gather()} when initial type
check fails.

@item 
bpo-46659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46659}: The @ref{b29,,calendar.LocaleTextCalendar} and
@ref{b2a,,calendar.LocaleHTMLCalendar} classes now use
@ref{232,,locale.getlocale()}, instead of using
@ref{233,,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{233,,locale.getdefaultlocale()} function is deprecated and
will be removed in Python 3.13. Use @ref{231,,locale.setlocale()},
@ref{947,,locale.getpreferredencoding(False)}
and @ref{232,,locale.getlocale()} functions instead.  Patch by Victor Stinner.

@item 
bpo-46655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46655}: In @ref{a9e,,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{12e,,xml.etree.ElementTree} module. Now, instantiating an
@ref{e18,,xml.etree.ElementTree.XMLParser} with a @code{target=None} keyword
provides a default @ref{e19,,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{d4,,socket}.

@item 
bpo-46521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46521}: Fix a bug in the @ref{1d,,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{aa1,,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{4ee,,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{9c5,,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{a96,,typing.Never} and @ref{a95,,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{1dd3,,typing.ForwardRef} now honor the @code{module} parameter of
@code{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{d8,,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{a9e,,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{a1e,,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{2d,,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{1dd4,,is_tarfile()} method when using
`fileobj' argument: position in the `fileobj' was advanced forward which
made it unreadable with @ref{1dd5,,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{6e4,,configparser.ConfigParser} constructor raise
@ref{291,,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{a39,,inspect.ismethodwrapper()} and fix
@ref{1dd6,,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<31>,Tests<34>,Library<101>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id443}@anchor{1dd7}
@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<34>,Build<36>,Documentation<31>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id444}@anchor{1dd8}
@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<36>,Windows<31>,Tests<34>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id445}@anchor{1dd9}
@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{b57,,_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<31>,IDLE<17>,Build<36>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id446}@anchor{1dda}
@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<17>,C API<33>,Windows<31>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id447}@anchor{1ddb}
@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<33>,,IDLE<17>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id448}@anchor{1ddc}
@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{b68,,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{827,,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{1ddd}
@subsection Python 3.11.0 alpha 5


`Release date: 2022-02-03'

@menu
* Core and Builtins: Core and Builtins<101>. 
* Library: Library<102>. 
* Core and Builtins: Core and Builtins<102>. 
* Library: Library<103>. 
* Build: Build<37>. 
* Core and Builtins: Core and Builtins<103>. 
* Library: Library<104>. 
* Documentation: Documentation<32>. 
* Tests: Tests<35>. 
* Build: Build<38>. 
* Windows: Windows<32>. 
* macOS: macOS<24>. 
* IDLE: IDLE<18>. 
* C API: C API<34>. 

@end menu

@node Core and Builtins<101>,Library<102>,,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id449}@anchor{1dde}
@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{443,,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{326,,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{2c9,,DeprecationWarning}.

@item 
bpo-46458@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46458}: Reorder code emitted by the compiler for a
@ref{ad6,,try}-@ref{447,,except} block so that the @ref{320,,else} block’s
code immediately follows the @code{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{1823,,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{af5,,COPY} and @ref{af6,,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{1ddf,,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}.
@end itemize

@node Library<102>,Core and Builtins<102>,Core and Builtins<101>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id450}@anchor{1de0}
@subsubsection Library



@itemize -

@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.
@end itemize

@node Core and Builtins<102>,Library<103>,Library<102>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id451}@anchor{1de1}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-46361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46361}: Ensure that «small» integers created by @ref{198e,,int.from_bytes()}
and @ref{1c2,,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
@end itemize

@node Library<103>,Build<37>,Core and Builtins<102>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id452}@anchor{1de2}
@subsubsection Library



@itemize -

@item 
bpo-30512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30512}: Add CAN Socket support for NetBSD.
@end itemize

@node Build<37>,Core and Builtins<103>,Library<103>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id453}@anchor{1de3}
@subsubsection Build



@itemize -

@item 
bpo-46045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46045}: Do not use POSIX semaphores on NetBSD
@end itemize

@node Core and Builtins<103>,Library<104>,Build<37>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id454}@anchor{1de4}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-44024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44024}: Improve the @ref{291,,TypeError} message for non-string second
arguments passed to the built-in functions @ref{f8f,,getattr()} and
@ref{8e2,,hasattr()}. Patch by Géry Ogam.
@end itemize

@node Library<104>,Documentation<32>,Core and Builtins<103>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id455}@anchor{1de5}
@subsubsection Library



@itemize -

@item 
bpo-46624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46624}: Restore support for non-integer arguments of
@ref{c41,,random.randrange()} and @ref{15d5,,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{a9e,,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{1376,,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{10f,,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{a9e,,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{eb8,,types.TracebackType} and
@ref{1de6,,types.FrameType}. Calculate them directly from the caught
exception without calling @ref{a7a,,sys.exc_info()}.

@item 
bpo-46491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46491}: Allow @ref{d09,,typing.Annotated} to wrap @ref{76f,,typing.Final} and
@ref{76e,,typing.ClassVar}. Patch by Gregory Beauregard.

@item 
bpo-46483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46483}: Remove @ref{b21,,__class_getitem__()} from
@ref{8b6,,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{75,,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{291,,TypeError} with a
relevant error message on invalid arg. Previously it allowed a cryptic
@ref{1a9,,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{b,,asyncio} generic classes now return
@ref{bc7,,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{1559,,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{aa,,pdb} now gracefully handles @code{help} when
@ref{1de7,,__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{a98,,typing.reveal_type()}. Patch by Jelle Zijlstra.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: @ref{df,,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{4f6,,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{1c2e,,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{dc7,,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{a21,,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{4bd,,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{1035,,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{1de8,,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{13d,,zoneinfo} to rely on importlib.resources
traversable API.

@item 
bpo-46103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46103}: Now @ref{1de9,,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{1db,,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{295,,ParamSpec} in
@ref{ba4,,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<32>,Tests<35>,Library<104>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id456}@anchor{1dea}
@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<35>,Build<38>,Documentation<32>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id457}@anchor{1deb}
@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{1121,,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{6bd,,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{df,,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<38>,Windows<32>,Tests<35>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id458}@anchor{1dec}
@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<32>,macOS<24>,Build<38>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id459}@anchor{1ded}
@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 μεταβλητή περιβάλλοντος; PATH
@code{PATH} instead of at the
start.
@end itemize

@node macOS<24>,IDLE<18>,Windows<32>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id460}@anchor{1dee}
@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<18>,C API<34>,macOS<24>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id461}@anchor{1def}
@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<34>,,IDLE<18>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id462}@anchor{1df0}
@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{b3a,,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{1df1}
@subsection Python 3.11.0 alpha 4


`Release date: 2022-01-13'

@menu
* Core and Builtins: Core and Builtins<104>. 
* Library: Library<105>. 
* Core and Builtins: Core and Builtins<105>. 
* Library: Library<106>. 
* Core and Builtins: Core and Builtins<106>. 
* Library: Library<107>. 
* Core and Builtins: Core and Builtins<107>. 
* Library: Library<108>. 
* Documentation: Documentation<33>. 
* Tests: Tests<36>. 
* Build: Build<39>. 
* Windows: Windows<33>. 
* macOS: macOS<25>. 
* C API: C API<35>. 

@end menu

@node Core and Builtins<104>,Library<105>,,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id463}@anchor{1df2}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-46070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46070}: @ref{1a6f,,Py_EndInterpreter()} now explicitly untracks all objects
currently tracked by the GC. Previously, if an object was used later by
another interpreter, calling @ref{18a7,,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.
@end itemize

@node Library<105>,Core and Builtins<105>,Core and Builtins<104>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id464}@anchor{1df3}
@subsubsection Library



@itemize -

@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».
@end itemize

@node Core and Builtins<105>,Library<106>,Library<105>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id465}@anchor{1df4}
@subsubsection Core and Builtins



@itemize -

@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.
@end itemize

@node Library<106>,Core and Builtins<106>,Core and Builtins<105>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id466}@anchor{1df5}
@subsubsection Library



@itemize -

@item 
bpo-46085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46085}: Fix iterator cache mechanism of @code{OrderedDict}.
@end itemize

@node Core and Builtins<106>,Library<107>,Library<106>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id467}@anchor{1df6}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-46055@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46055}: Speed up shifting operation involving integers less than
@ref{1df7,,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{17e,,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{1d7c,,POP_JUMP_IF_NOT_NONE} and
@ref{1d7b,,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{c6,,runpy}, patch by Kumar Aditya.

@item 
bpo-46025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46025}: Fix a crash in the @ref{d,,atexit} module involving functions
that unregister themselves before raising exceptions. Patch by Pablo
Galindo.
@end itemize

@node Library<107>,Core and Builtins<107>,Core and Builtins<106>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id468}@anchor{1df8}
@subsubsection Library



@itemize -

@item 
bpo-46000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46000}: Improve compatibility of the @ref{2e,,curses} module with NetBSD
curses.
@end itemize

@node Core and Builtins<107>,Library<108>,Library<107>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id469}@anchor{1df9}
@subsubsection Core and Builtins



@itemize -

@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{1c8,,compile()} function did not
always raise a @ref{17e,,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{42b,,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{5ae,,Py_Version} constant which bears the same
value as @ref{5af,,PY_VERSION_HEX}. Patch by Gabriele N. Tornetta.
@end itemize

@node Library<108>,Documentation<33>,Core and Builtins<107>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id470}@anchor{1dfa}
@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{a7b,,sys.exception()} method which returns the active
exception instance.

@item 
bpo-46307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46307}: Add @ref{a76,,string.Template.is_valid()} and
@ref{a75,,string.Template.get_identifiers()} methods.

@item 
bpo-46306@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46306}: Assume that @ref{2e1,,types.CodeType} always has
@code{types.CodeType.co_firstlineno} in @ref{3d,,doctest}.

@item 
bpo-40479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40479}: Fix @ref{6b,,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{b,,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{295,,typing.ParamSpec} and
@ref{294,,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{1dfb,,enum.Enum.__dir__()}.

@item 
bpo-46266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46266}: Improve day constants in @ref{15,,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{11a,,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{abd,,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{2d4,,glob()} and
@ref{be1,,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{1dfc,,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{93f,,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{7,,argparse} raises @ref{277,,ValueError} with clear message
when trying to render usage for an empty mutually exclusive group.
Previously it raised a cryptic @ref{18d7,,IndexError}.

@item 
bpo-45615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45615}: Functions in the @ref{107,,traceback} module raise @ref{291,,TypeError}
rather than @ref{1a9,,AttributeError} when an exception argument is not of
type @ref{9b9,,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{ce,,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{a2a,,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{81,,inspect}, patch by Kumar Aditya.

@item 
bpo-46018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46018}: Ensure that @ref{1595,,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 @ref{5c,,fcntl} module.

@item 
bpo-45755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45755}: @ref{10d,,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{1dfd,,multiprocessing.Event} objects, patch by Kumar Aditya.

@item 
bpo-45643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45643}: Added @ref{1dfe,,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{a6d,,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{c0e,,TimeoutError}, keep these
names as deprecated aliases.
@end itemize

@node Documentation<33>,Tests<36>,Library<108>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id471}@anchor{1dff}
@subsubsection Documentation



@itemize -

@item 
bpo-46196@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46196}: Document method @ref{1e00,,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{10d,,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{1e01,,globals()} function.
@end itemize

@node Tests<36>,Build<39>,Documentation<33>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id472}@anchor{1e02}
@subsubsection Tests



@itemize -

@item 
bpo-46296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46296}: Add a test case for @ref{59,,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{342,,unittest.IsolatedAsyncioTestCase} usage.

@item 
bpo-23819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23819}: Fixed @ref{b,,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<39>,Windows<33>,Tests<36>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id473}@anchor{1e03}
@subsubsection Build



@itemize -

@item 
bpo-44133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44133}: When Python is configured with
@ref{c64,,--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{c3a,,--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{133d,,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<33>,macOS<25>,Build<39>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id474}@anchor{1e04}
@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<25>,C API<35>,Windows<33>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id475}@anchor{1e05}
@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<35>,,macOS<25>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id476}@anchor{1e06}
@subsubsection C API



@itemize -

@item 
bpo-46236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46236}: Fix a bug in @ref{1d35,,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{b3b,,PyBuffer_GetPointer()},
@ref{b3e,,PyBuffer_FromContiguous()}, @ref{b3d,,PyBuffer_ToContiguous()} and
@ref{b43,,PyMemoryView_FromBuffer()} now take buffer info by @code{const
Py_buffer *} instead of @code{Py_buffer *}, as they do not need mutability.
@code{PyBuffer_FromContiguous()} also now takes the source buffer as
@code{const void *}, and similarly @code{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{1e07,,PyCapsule_Import()} is a no-op now.

@item 
bpo-45855@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45855}: Replaced deprecated usage of
@code{PyImport_ImportModuleNoBlock()} with
@ref{3a3,,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{1e08}
@subsection Python 3.11.0 alpha 3


`Release date: 2021-12-08'

@menu
* Core and Builtins: Core and Builtins<108>. 
* Library: Library<109>. 
* Core and Builtins: Core and Builtins<109>. 
* Library: Library<110>. 
* Documentation: Documentation<34>. 
* Tests: Tests<37>. 
* Build: Build<40>. 
* Windows: Windows<34>. 
* macOS: macOS<26>. 
* C API: C API<36>. 

@end menu

@node Core and Builtins<108>,Library<109>,,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id477}@anchor{1e09}
@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{17e,,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{9b9,,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{1e0a,,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{a7a,,sys.exc_info()} and @ref{b54,,PyErr_GetExcInfo()} if the exception
instance is modified while the exception is handled, as well as
@ref{b53,,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.
@end itemize

@node Library<109>,Core and Builtins<109>,Core and Builtins<108>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id478}@anchor{1e0b}
@subsubsection Library



@itemize -

@item 
bpo-45614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45614}: Fix @ref{107,,traceback} display for exceptions with invalid module
name.
@end itemize

@node Core and Builtins<109>,Library<110>,Library<109>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id479}@anchor{1e0c}
@subsubsection Core and Builtins



@itemize -

@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{aeb,,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 @code{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{595,,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{6bd,,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{595,,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{e2,,sys} and
@ref{e4,,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<110>,Documentation<34>,Core and Builtins<109>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id480}@anchor{1e0d}
@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{343,,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{b,,asyncio} normalize exceptions as soon as they are
captured with @ref{63b,,PyErr_Fetch()}, and before they are stored as an
exc_info triplet. This brings @code{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{93f,,unittest.TextTestResult} and
@ref{1cb9,,unittest.TextTestRunner} flush now the output stream more often.

@item 
bpo-45917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45917}: Added @ref{a50,,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{5b,,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{d7,,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{c0a,,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{3b,,dis} produced an incorrect oparg when
@ref{1d1c,,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{194,,sys.path}
location while the program is running, calling the
@ref{fcf,,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{f5b,,types.resolve_bases()} and @ref{150c,,types.new_class()} for
@ref{bc7,,types.GenericAlias} instance as a base.

@item 
bpo-45663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45663}: Fix @ref{1e0e,,dataclasses.is_dataclass()} for dataclasses which are
subclasses of @ref{bc7,,types.GenericAlias}.

@item 
bpo-45662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45662}: Fix the repr of @ref{1dae,,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{a8c,,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{abd,,math.comb()} and @ref{abe,,math.perm()}.

@item 
bpo-45514@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45514}: Deprecated legacy functions in @ref{7e,,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{cb3,,graphlib.TopologicalSorter}.

@item 
bpo-44733@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44733}: Add @code{max_tasks_per_child} to
@ref{206,,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{a38,,inspect.getmembers_static()} , it return all members
without triggering dynamic lookup via the descriptor protocol. Patch by
Weipeng Hong.
@end itemize

@node Documentation<34>,Tests<37>,Library<110>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id481}@anchor{1e0f}
@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{186,,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{190e,,astuple()} and
@ref{190d,,asdict()} docs, warning about deepcopy being applied and
providing a workaround.
@end itemize

@node Tests<37>,Build<40>,Documentation<34>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id482}@anchor{1e10}
@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{db3,,functools.lru_cache()}
to @code{test_functools}.
@end itemize

@node Build<40>,Windows<34>,Tests<37>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id483}@anchor{1e11}
@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{ce,,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{39,,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{d7,,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{13c,,zlib}, @ref{14,,bz2}, and
@ref{8d,,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<34>,macOS<26>,Build<40>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id484}@anchor{1e12}
@subsubsection Windows



@itemize -

@item 
bpo-46105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46105}: Fixed calculation of @ref{194,,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<26>,C API<36>,Windows<34>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id485}@anchor{1e13}
@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<36>,,macOS<26>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id486}@anchor{1e14}
@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{1e15}
@subsection Python 3.11.0 alpha 2


`Release date: 2021-11-05'

@menu
* Core and Builtins: Core and Builtins<110>. 
* Library: Library<111>. 
* Documentation: Documentation<35>. 
* Tests: Tests<38>. 
* Build: Build<41>. 
* Windows: Windows<35>. 
* macOS: macOS<27>. 
* IDLE: IDLE<19>. 
* C API: C API<37>. 

@end menu

@node Core and Builtins<110>,Library<111>,,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id487}@anchor{1e16}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-45716@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45716}: Improve the @ref{17e,,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{c1a,,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{1bd,,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{1e17,,Value comparisons} 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{178,,-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{6d8,,ExceptionGroup} and
@ref{767,,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<111>,Documentation<35>,Core and Builtins<110>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id488}@anchor{1e18}
@subsubsection Library



@itemize -

@item 
bpo-45679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45679}: Fix caching of multi-value @ref{c2d,,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{d7,,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{d7,,sqlite3} now sets @ref{a6c,,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{3e0,,sqlite3.connect()} now correctly raises @ref{18fa,,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{c01,,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{1e19,,operator.call()} to @code{operator.__all__}. Patch by
Kreusada.

@item 
bpo-42174@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42174}: @ref{14af,,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{1300,,importlib.machinery.NamespaceLoader} is
now public, and implements the @ref{12fe,,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{13d,,zoneinfo} in the @ref{33,,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{849,,gzip.GzipFile},
@ref{c3d,,bz2.BZ2File}, and @ref{13b5,,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{1dd3,,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{1e1a,,email.utils.parsedate_tz()} crashing with
@ref{18d8,,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{1e1b,,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{e36,,asyncio.Condition} with explicit
@ref{e35,,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{1a3c,,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{3d,,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{1d6a,,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{2c,,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{137,,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{1a3c,,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{223,,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{a6a,,setlimit()} and
@ref{a6b,,getlimit()} to @ref{3df,,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{81,,inspect} module:


@itemize *

@item 

@table @asis

@item the @code{getargspec} function, deprecated since Python 3.0;

use @ref{4bd,,inspect.signature()} or @ref{b1f,,inspect.getfullargspec()} instead.
@end table

@item 
the @code{formatargspec} function, deprecated since Python 3.5;
use the @ref{4bd,,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{b20,,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{e9,,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{a01,,chdir()} context
manager to change the current working directory and then restore it on
exit. Simple wrapper around @ref{a02,,chdir()}.

@item 
bpo-24139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24139}: Add support for SQLite extended result codes in
@ref{1e1c,,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{7,,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{1c3,,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{111,,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<35>,Tests<38>,Library<111>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id489}@anchor{1e1d}
@subsubsection Documentation



@itemize -

@item 
bpo-45726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45726}: Improve documentation for @ref{a2a,,functools.singledispatch()} and
@ref{21e,,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
@code{importlib.abc.TraversableResources} documentation.

@item 
bpo-45464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45464}: Mention in the documentation of @ref{1e1e,,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{1f,,collections.abc}.

@item 
bpo-45516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45516}: Add protocol description to the
@code{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<38>,Build<41>,Documentation<35>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id490}@anchor{1e1f}
@subsubsection Tests



@itemize -

@item 
bpo-45678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45678}: Add tests for scenarios in which
@ref{21e,,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 @ref{497,,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{d7,,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<41>,Windows<35>,Tests<38>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id491}@anchor{1e20}
@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{91,,math} and @ref{19,,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{6a8,,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<35>,macOS<27>,Build<41>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id492}@anchor{1e21}
@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<27>,IDLE<19>,Windows<35>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id493}@anchor{1e22}
@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<19>,C API<37>,macOS<27>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id494}@anchor{1e23}
@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<37>,,IDLE<19>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id495}@anchor{1e24}
@subsubsection C API



@itemize -

@item 
bpo-29103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29103}: @ref{390,,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 @code{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{b63,,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{b75,,PyMarshal_WriteLongToFile()}

@item 
@ref{b76,,PyMarshal_WriteObjectToFile()}

@item 
@ref{b77,,PyMarshal_ReadObjectFromString()}

@item 
@ref{b78,,PyMarshal_WriteObjectToString()}

@item 
the @code{Py_MARSHAL_VERSION} macro
@end itemize

These are not part of the @ref{b79,,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{b38,,PyThreadState_EnterTracing()}, and
@ref{b39,,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{d4a,,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{1e25}
@subsection Python 3.11.0 alpha 1


`Release date: 2021-10-05'

@menu
* Security: Security<28>. 
* Core and Builtins: Core and Builtins<111>. 
* Library: Library<112>. 
* Core and Builtins: Core and Builtins<112>. 
* Library: Library<113>. 
* Core and Builtins: Core and Builtins<113>. 
* Library: Library<114>. 
* Core and Builtins: Core and Builtins<114>. 
* Library: Library<115>. 
* Core and Builtins: Core and Builtins<115>. 
* Library: Library<116>. 
* Core and Builtins: Core and Builtins<116>. 
* Library: Library<117>. 
* Core and Builtins: Core and Builtins<117>. 
* Library: Library<118>. 
* Core and Builtins: Core and Builtins<118>. 
* Library: Library<119>. 
* Core and Builtins: Core and Builtins<119>. 
* Library: Library<120>. 
* Core and Builtins: Core and Builtins<120>. 
* Library: Library<121>. 
* Documentation: Documentation<36>. 
* Tests: Tests<39>. 
* Build: Build<42>. 
* Windows: Windows<36>. 
* macOS: macOS<28>. 
* IDLE: IDLE<20>. 
* Tools/Demos: Tools/Demos<25>. 
* C API: C API<38>. 

@end menu

@node Security<28>,Core and Builtins<111>,,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id496}@anchor{1e26}
@subsubsection Security



@itemize -

@item 
bpo-42278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42278}: Replaced usage of @ref{1e27,,tempfile.mktemp()} with
@ref{15da,,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{1d4,,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{90,,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{d2,,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{72,,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<111>,Library<112>,Security<28>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id497}@anchor{1e28}
@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{bc7,,types.GenericAlias} objects.

@item 
bpo-45155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45155}: @ref{1e29,,int.to_bytes()} and @ref{198e,,int.from_bytes()} now take a
default value of @code{"big"} for the @code{byteorder} argument.
@code{int.to_bytes()} also takes a default value of @code{1} for the
@code{length} argument.
@end itemize

@node Library<112>,Core and Builtins<112>,Core and Builtins<111>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id498}@anchor{1e2a}
@subsubsection Library



@itemize -

@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{1e2b,,os.isatty()},
@ref{1e2c,,os.device_encoding()} and @ref{b9c,,io.TextIOWrapper}. By extension,
@ref{92b,,io.open()} in text mode is also affected. This change solves a
deadlock in @code{os.isatty()}. Patch by Vincent Michel in bpo-44219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44219}.
@end itemize

@node Core and Builtins<112>,Library<113>,Library<112>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id499}@anchor{1e2d}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-44959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44959}: Added fallback to extension modules with “.sl” suffix on HP-UX
@end itemize

@node Library<113>,Core and Builtins<113>,Core and Builtins<112>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id500}@anchor{1e2e}
@subsubsection Library



@itemize -

@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.
@end itemize

@node Core and Builtins<113>,Library<114>,Library<113>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id501}@anchor{1e2f}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-44348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44348}: The deallocator function of the @ref{9b9,,BaseException} type now
uses the trashcan mechanism to prevent stack overflow. For example, when a
@ref{1121,,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{32b,,open()}, @ref{92b,,io.open()}, @ref{32c,,codecs.open()} and
@ref{b1e,,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{107,,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).
@end itemize

@node Library<114>,Core and Builtins<114>,Core and Builtins<113>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id502}@anchor{1e30}
@subsubsection Library



@itemize -

@item 
bpo-45012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45012}: In @ref{b2,,posix}, release GIL during @code{stat()}, @code{lstat()},
and @code{fstatat()} syscalls made by @ref{1c71,,os.DirEntry.stat()}. Patch by
Stanisław Skonieczny.
@end itemize

@node Core and Builtins<114>,Library<115>,Library<114>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id503}@anchor{1e31}
@subsubsection Core and Builtins



@itemize -

@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{17e,,SyntaxError} is now raised when trying to delete
@ref{bb7,,__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.
@end itemize

@node Library<115>,Core and Builtins<115>,Core and Builtins<114>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id504}@anchor{1e32}
@subsubsection Library



@itemize -

@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
@end itemize

@node Core and Builtins<115>,Library<116>,Library<115>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id505}@anchor{1e33}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-24234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24234}: Implement the @code{__bytes__()} special method on the
@ref{1c7,,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{328,,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
@end itemize

@node Library<116>,Core and Builtins<116>,Core and Builtins<115>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id506}@anchor{1e34}
@subsubsection Library



@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.
@end itemize

@node Core and Builtins<116>,Library<117>,Library<116>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id507}@anchor{1e35}
@subsubsection Core and Builtins



@itemize -

@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{327,,float} or @ref{328,,complex}.

@item 
bpo-44895@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44895}: A debug variable 
@geindex PYTHONDUMPREFSFILE
@geindex μεταβλητή περιβάλλοντος; PYTHONDUMPREFSFILE
@ref{1e36,,PYTHONDUMPREFSFILE} is added for
creating a dump file which is generated by @ref{828,,--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{17e,,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{10d,,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{440,,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.
@end itemize

@node Library<117>,Core and Builtins<117>,Core and Builtins<116>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id508}@anchor{1e37}
@subsubsection Library



@itemize -

@item 
bpo-44611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44611}: On Windows, @ref{931,,os.urandom()}: uses BCryptGenRandom API
instead of CryptGenRandom API which is deprecated from Microsoft Windows
API. Patch by Donghee Na.
@end itemize

@node Core and Builtins<117>,Library<118>,Library<117>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id509}@anchor{1e38}
@subsubsection Core and Builtins



@itemize -

@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{17e,,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.
@end itemize

@node Library<118>,Core and Builtins<118>,Core and Builtins<117>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id510}@anchor{1e39}
@subsubsection Library



@itemize -

@item 
bpo-44490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44490}: @ref{10d,,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.
@end itemize

@node Core and Builtins<118>,Library<119>,Library<118>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id511}@anchor{1e3a}
@subsubsection Core and Builtins



@itemize -

@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{18a5,,PyObject_GC_Del()} in error path when
initializing @ref{bc7,,types.GenericAlias}.
@end itemize

@node Library<119>,Core and Builtins<119>,Core and Builtins<118>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id512}@anchor{1e3b}
@subsubsection Library



@itemize -

@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.
@end itemize

@node Core and Builtins<119>,Library<120>,Library<119>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id513}@anchor{1e3c}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}: Heap types with the @ref{5fb,,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{b5f,,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{9e2,,hash()} of
@ref{e15,,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{291,,TypeError} is now raised instead of an
@ref{1a9,,AttributeError} in @ref{20a,,with} and @ref{20b,,async with}
statements for objects which do not support the @ref{478,,context manager} or
@ref{9d2,,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.
@end itemize

@node Library<120>,Core and Builtins<120>,Core and Builtins<119>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id514}@anchor{1e3d}
@subsubsection Library



@itemize -

@item 
bpo-44304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44304}: Fix a crash in the @ref{d7,,sqlite3} module that happened when the
garbage collector clears @code{sqlite.Statement} objects. Patch by Pablo
Galindo
@end itemize

@node Core and Builtins<120>,Library<121>,Library<120>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id515}@anchor{1e3e}
@subsubsection Core and Builtins



@itemize -

@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{1ce,,tuple}, @ref{4d9,,list}, @ref{9d4,,frozenset}) no longer accept
arbitrary keyword arguments. [reverted in 3.11a4] Subclass of @ref{42b,,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{186,,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{a12,,str.format()}.

@item 
bpo-11105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11105}: When compiling @ref{2ec,,ast.AST} objects with recursive
references through @ref{1c8,,compile()}, the interpreter doesn’t crash anymore
instead it raises a @ref{1121,,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<121>,Documentation<36>,Core and Builtins<120>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id516}@anchor{1e3f}
@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{a87,,threading.Lock.acquire()}
method now uses the monotonic clock (@ref{a88,,time.CLOCK_MONOTONIC}) for
the timeout, rather than using the system clock
(@ref{a89,,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{f6,,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{158d,,Thread.join()} method of the @ref{f6,,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{a8c,,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{a8c,,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{1e40,,unittest.TestCase.debug()} raises now a
@ref{138d,,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{e1d,,copyfile()},
@ref{e1e,,copy()}, @ref{e1f,,copy2()} raising
@ref{243,,FileNotFoundError} when source is a directory, which should raise
@ref{1401,,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{496,,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{a8c,,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{26,,configparser} module: the
@code{SafeConfigParser} class, the @code{filename} property of the
@ref{914,,ParsingError} class, the @code{readfp()} method of
the @ref{6e4,,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{ac2,,unicodedata.normalize()}. Patch by Donghee Na.

@item 
bpo-35474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35474}: Calling @ref{1e41,,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{a9e,,typing.get_type_hints()} now works with
@ref{76f,,Final} wrapped in @ref{1dd3,,ForwardRef}.

@item 
bpo-45162@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45162}: Remove many old deprecated @ref{10f,,unittest} features:


@itemize *

@item 
«@code{fail*}» and «@code{assert*}» aliases of @ref{52f,,TestCase} methods.

@item 
Broken from start @ref{52f,,TestCase} method @code{assertDictContainsSubset()}.

@item 
Ignored @code{<unittest.TestLoader.loadTestsFromModule> TestLoader.loadTestsFromModule()} parameter `use_load_tests'.

@item 
Old alias @code{_TextTestResult} of @ref{93f,,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{787,,__getitem__()} methods of
@ref{b1c,,xml.dom.pulldom.DOMEventStream}, @ref{b1d,,wsgiref.util.FileWrapper}
and @ref{b1e,,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{b1a,,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{1510,,unittest.TestResult} methods
@ref{1e42,,addFailure()},
@ref{1e43,,addError()},
@ref{1e44,,addSkip()} and
@ref{1e45,,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{10f,,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{11,,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{b1b,,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{a91,,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{150f,,run()} now always return a
@ref{1510,,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{24,,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{10f,,unittest}:


@itemize *

@item 
Functions registered with @ref{e0f,,addModuleCleanup()} were not called unless the user defines @code{tearDownModule()} in their test module.

@item 
Functions registered with @ref{e10,,addClassCleanup()} were not called if @code{tearDownClass} is set to @code{None}.

@item 
Buffering in @ref{1510,,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{110,,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{a2d,,gzip.compress()} and
@ref{15b4,,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{42b,,set} and @ref{9d4,,frozenset} objects are
always @ref{90,,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{11e,,webbrowser} itself. Patch by Donghee Na.

@item 
bpo-44955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44955}: Method @ref{16ef,,stopTestRun()} is now always
called in pair with method @ref{16ee,,startTestRun()} for
@ref{1510,,TestResult} objects implicitly created in
@ref{150f,,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{1e46,,ReadError} when a zlib error
occurs during file extraction.

@item 
bpo-44935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44935}: @ref{df,,subprocess} on Solaris now also uses
@ref{731,,os.posix_spawn()} for better performance.

@item 
bpo-44911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44911}: @ref{342,,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{1db,,argparse.BooleanOptionalAction}’s default value is no
longer printed twice when used with
@ref{1e47,,argparse.ArgumentDefaultsHelpFormatter}.

@item 
bpo-44860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44860}: Fix the @code{posix_user} scheme in @ref{e4,,sysconfig} to not depend
on @ref{2a9,,sys.platlibdir}.

@item 
bpo-44859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44859}: Improve error handling in @ref{d7,,sqlite3} and raise more
accurate exceptions.


@itemize *

@item 
@ref{18fa,,MemoryError} is now raised instead of @ref{1db0,,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{1db0,,sqlite3.Warning} when the statement contains surrogate characters in @code{Connection.__call__()} and @code{Cursor.execute()}.

@item 
@ref{291,,TypeError} is now raised instead of @ref{277,,ValueError} for non-string script argument in @code{Cursor.executescript()}.

@item 
@ref{277,,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{12ac,,os.set_inheritable()} function on FreeBSD 14 for
file descriptor opened with the @ref{131c,,O_PATH} flag: ignore the
@ref{d25,,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{18fa,,MemoryError} raised in user-defined functions will now
produce a @code{MemoryError} in @ref{d7,,sqlite3}. @ref{c57,,OverflowError} will
now be converted to @ref{1e48,,DataError}. Previously
@ref{1e49,,OperationalError} was produced in these cases.

@item 
bpo-44822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44822}: @ref{d7,,sqlite3} user-defined functions and aggregators returning
@ref{1df,,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{295,,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{76c,,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{1692,,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{8e9,,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{f8f,,getattr()} on
@ref{6bb,,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{1e4a,,logging.FileHandler} is used in @ref{d,,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{1199,,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{a66,,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{c57,,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{aa,,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{4bd,,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{1a04,,inspect.getsource()}
when examining a class in the interactive session. Instead of
@ref{291,,TypeError}, it should be @ref{53c,,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{5f,,fnmatch}, the cache size for compiled regex patterns
(@ref{db3,,functools.lru_cache()}) was bumped up from 256 to 32768, affecting
functions: @ref{1e4b,,fnmatch.fnmatch()}, @ref{1e4c,,fnmatch.fnmatchcase()},
@ref{1e4d,,fnmatch.filter()}.

@item 
bpo-41928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41928}: Update @ref{e1d,,shutil.copyfile()} to raise
@ref{243,,FileNotFoundError} instead of confusing @ref{1401,,IsADirectoryError}
when a path ending with a @code{os.path.sep} does not exist;
@ref{e1e,,shutil.copy()} and @ref{e1f,,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{107,,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{cad,,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{1329,,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{aa,,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{1e4e,,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{216,,email.message.EmailMessage}.

@item 
bpo-44468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44468}: @ref{a9e,,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{d7,,sqlite3} authorizer callback by
passing @ref{a65,,None} to @ref{3e3,,set_authorizer()}. Patch
by Erlend E. Aasland.

@item 
bpo-43977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43977}: Set the proper @ref{1e4f,,Py_TPFLAGS_MAPPING} and
@ref{1e50,,Py_TPFLAGS_SEQUENCE} flags for subclasses created before a
parent has been registered as a @ref{c9c,,collections.abc.Mapping} or
@ref{156d,,collections.abc.Sequence}.

@item 
bpo-44482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44482}: Fix very unlikely resource leak in @ref{67,,glob} in alternate
Python implementations.

@item 
bpo-44466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44466}: The @ref{5b,,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{291,,TypeError} is now raised instead of an
@ref{1a9,,AttributeError} in @ref{9d0,,contextlib.ExitStack.enter_context()} and
@ref{9d1,,contextlib.AsyncExitStack.enter_async_context()} for objects which do
not support the @ref{478,,context manager} or @ref{9d2,,asynchronous context manager} protocols correspondingly.

@item 
bpo-44404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44404}: @ref{f9,,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{b3,,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{1235,,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{39e,,Py_TPFLAGS_HAVE_GC} flag. Patch by
Victor Stinner.

@item 
bpo-44422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44422}: The @ref{1e51,,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{291,,TypeError}.

@item 
bpo-44389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44389}: Fix deprecation of @ref{1e52,,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{aa,,pdb}’s
run/restart command.

@item 
bpo-44362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44362}: Improve @ref{d8,,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{e4,,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{a51,,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{a49,,logging.getLevelNamesMapping()}

@item 
bpo-44260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44260}: The @ref{1e53,,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{66,,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{b18,,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{d7,,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{1c3,,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{1bce,,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{cb6,,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{6d,,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{6b,,hashlib}
algorithms support.

@item 
bpo-44095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44095}: @ref{ab6,,zipfile.Path} now supports @ref{ab3,,zipfile.Path.stem},
@ref{ab5,,zipfile.Path.suffixes}, and @ref{ab4,,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{10d,,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{cb6,,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{1100,,pkgutil.iter_modules()} with a list of @ref{4ee,,pathlib.Path} objects

@item 
bpo-44059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44059}: Register the SerenityOS Browser in the @ref{11e,,webbrowser}
module.

@item 
bpo-36515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36515}: The @ref{6b,,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{113,,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{113,,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{22a,,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{aa,,pdb} where @code{checkline()} raises
@ref{1a9,,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{d7,,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{18fa,,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{18fa,,MemoryError} in @ref{882,,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{a2e,,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{927,,importlib.import_module()} and @ref{1415,,importlib.__import__()}.

@item 
bpo-43318@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43318}: Fix a bug where @ref{aa,,pdb} does not always echo cleared
breakpoints.

@item 
bpo-43234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43234}: Prohibit passing
non-@ref{b27,,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{c27,,traceback.print_exception()}, @ref{c25,,traceback.format_exception()} and
@ref{c26,,traceback.format_exception_only()}.

@item 
bpo-33809@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33809}: Add the @ref{a92,,traceback.TracebackException.print()} method which
prints the formatted exception information.

@item 
bpo-42862@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42862}: @ref{d7,,sqlite3} now utilizes @ref{db3,,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{136b,,subprocess.check_output()} now raises @ref{277,,ValueError}
when the invalid keyword argument `check' is passed by user code.
Previously such use would fail later with a @ref{291,,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{d7,,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{81,,inspect} - by Anthony Sottile.

@item 
bpo-41402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41402}: Fix @ref{1e54,,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{1228,,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{f6,,threading} synchronization objects:
@ref{1501,,Semaphore}, @ref{1502,,BoundedSemaphore},
@ref{1503,,Event} and @ref{158c,,Barrier}.

@item 
bpo-5846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5846}: Deprecated the following @ref{10f,,unittest} functions, scheduled
for removal in Python 3.13:


@itemize *

@item 
@code{findTestCases()}

@item 
@code{makeSuite()}

@item 
@code{getTestCaseNames()}
@end itemize

Use @ref{792,,TestLoader} methods instead:


@itemize *

@item 
@ref{793,,unittest.TestLoader.loadTestsFromModule()}

@item 
@ref{794,,unittest.TestLoader.loadTestsFromTestCase()}

@item 
@ref{795,,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{aa,,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{26,,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{20f,,contextlib.asynccontextmanager()} to match
@ref{20e,,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{6f8,,email.utils.getaddresses()} now accepts
@ref{1e55,,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{d7,,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<36>,Tests<39>,Library<121>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id517}@anchor{1e56}
@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{1f,,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{1e57,,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{1e29,,int.to_bytes()} and
@ref{198e,,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{f,,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{8c3,,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{1be6,,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{cae,,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{1869,,textwrap.wrap()},
@ref{1868,,textwrap.fill()}, and @ref{1379,,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{13a,,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{16d2,,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{b,,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{32,,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{1565,,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<39>,Build<42>,Documentation<36>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id518}@anchor{1e58}
@subsubsection Tests



@itemize -

@item 
bpo-40173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40173}: Fix @ref{1e59,,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{2e4,,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{f60,,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{2a9,,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{44f,,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{17c5,,id()} is preserved when @code{obj
* 1} is used on @ref{1df,,str} and @ref{1c7,,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{1e5a,,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{dc8,,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{1903,,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<42>,Windows<36>,Tests<39>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id519}@anchor{1e5b}
@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 μεταβλητή περιβάλλοντος; 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<36>,macOS<28>,Build<42>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id520}@anchor{1e5c}
@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{af,,platform} module

@item 
bpo-44582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44582}: Accelerate speed of @ref{93,,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{f6,,threading}, such as with @ref{a87,,threading.Lock.acquire()} or
@ref{1e5d,,threading.Condition.wait()}.

@item 
bpo-42686@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42686}: Build @ref{d7,,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<28>,IDLE<20>,Windows<36>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id521}@anchor{1e5e}
@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{10fe,,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<20>,Tools/Demos<25>,macOS<28>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id522}@anchor{1e5f}
@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{1d4,,match} statement’s @ref{be6,,soft keywords}: @ref{1d4,,match}, @code{case}, and
@ref{be7,,_}. 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<25>,C API<38>,IDLE<20>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id523}@anchor{1e60}
@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<38>,,Tools/Demos<25>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id524}@anchor{1e61}
@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{277,,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{1e62,,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{1a6a,,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{5ef,,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{b37,,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{d8d,,Py_RunMain()} now resets @ref{1d19,,PyImport_Inittab} to
its initial value at exit. It must be possible to call
@ref{1d1a,,PyImport_AppendInittab()} or @ref{1d1b,,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{b6c,,PyThreadState} members like
@code{_tstate->trash_delete_nesting}, whereas the @code{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{b79,,Contents of Limited API} now shows the public name
@ref{b68,,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{19bb,,Py_IS_TYPE()} no longer uses @ref{5f5,,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{5f5,,Py_TYPE()} and @ref{b61,,Py_SIZE()} macros to
static inline functions. The @ref{b60,,Py_SET_TYPE()} and
@ref{b62,,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{b5e,,PyType_Ready()} function now raises an error if a
type is defined with the @ref{39e,,Py_TPFLAGS_HAVE_GC} flag set but has no
traverse function (@ref{36b,,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{60b,,PyConfig} API of the @ref{837,,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{c6d,,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{b36,,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{1e63}
@subsection Python 3.10.0 beta 1


`Release date: 2021-05-03'

@menu
* Security: Security<29>. 
* Core and Builtins: Core and Builtins<121>. 
* Library: Library<122>. 
* Core and Builtins: Core and Builtins<122>. 
* Library: Library<123>. 
* Core and Builtins: Core and Builtins<123>. 
* Library: Library<124>. 
* Documentation: Documentation<37>. 
* Tests: Tests<40>. 
* Build: Build<43>. 
* Windows: Windows<37>. 
* macOS: macOS<29>. 
* IDLE: IDLE<21>. 
* C API: C API<39>. 

@end menu

@node Security<29>,Core and Builtins<121>,,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id525}@anchor{1e64}
@subsubsection Security



@itemize -

@item 
bpo-43434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43434}: Creating @ref{3df,,sqlite3.Connection} objects now also produces
@code{sqlite3.connect} and @code{sqlite3.connect/handle} @ref{1e65,,auditing events}. Previously these events were only produced by
@ref{3e0,,sqlite3.connect()} calls. Patch by Erlend E. Aasland.

@item 
bpo-43998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43998}: The @ref{d8,,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{336,,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{113,,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{c17,,sqlite3.Connection.enable_load_extension()}, and
@ref{8c8,,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{2d4,,glob.glob()} and
@ref{be1,,glob.iglob()}.

@item 
bpo-36384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36384}: @ref{83,,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{d2b,,socket.inet_aton()} treats leading zeros as octal notation. glibc
implementation of modern @ref{d2c,,inet_pton()} does not accept any
leading zeros. For a while the @code{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{1e66,,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{72,,http.client} module.
@end itemize

@node Core and Builtins<121>,Library<122>,Security<29>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id526}@anchor{1e67}
@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{1e68,,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{1f,,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.
@end itemize

@node Library<122>,Core and Builtins<122>,Core and Builtins<121>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id527}@anchor{1e69}
@subsubsection Library



@itemize -

@item 
bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}: Make @ref{c1,,re} types immutable. Patch by Erlend E. Aasland.

@item 
bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}: Make the @ref{6c5,,array.array} type immutable. Patch by Erlend
E. Aasland.
@end itemize

@node Core and Builtins<122>,Library<123>,Library<122>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id528}@anchor{1e6a}
@subsubsection Core and Builtins



@itemize -

@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{17e,,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{b89,,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{665,,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{1e6b,,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{666,,@@staticmethod}) and class methods
(@ref{69a,,@@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{1e6c,,__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.
@end itemize

@node Library<123>,Core and Builtins<123>,Core and Builtins<122>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id529}@anchor{1e6d}
@subsubsection Library



@itemize -

@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.
@end itemize

@node Core and Builtins<123>,Library<124>,Library<123>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id530}@anchor{1e6e}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-43682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43682}: Static methods (@ref{666,,@@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{1121,,RecursionError} is now raised instead.

@item 
bpo-38530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38530}: When printing @ref{1a9,,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<124>,Documentation<37>,Core and Builtins<123>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id531}@anchor{1e6f}
@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{1e70,,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{588,,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{a9e,,typing.get_type_hints()} receives no namespace dictionary
arguments, @code{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{10a,,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{129c,,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{111,,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{bec,,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. @code{inspect.get_annotations()}
can also correctly un-stringize stringized annotations.

@ref{4bd,,inspect.signature()}, @code{inspect.from_callable()}, and
@code{inspect.from_function()} now call @ref{bec,,inspect.get_annotations()} to
retrieve annotations.  This means @code{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{d8,,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{d8,,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{98,,multiprocessing} @code{Server} class now explicitly
catches @ref{10f7,,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{c3d,,bz2.BZ2File},
@ref{849,,gzip.GzipFile}, and @ref{13b5,,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{92b,,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{7df,,KeyError} raised in @ref{a9e,,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{6bf,,subprocess.Popen} args are provided as a string or
as @ref{4ee,,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{2ef,,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{c10,,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{6a,,gzip} and @ref{8d,,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{d8,,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{10d,,typing} module by adding
@code{TypeGuard}.

@item 
bpo-25264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25264}: @ref{241,,os.path.realpath()} now accepts a `strict' keyword-only
argument. When set to @code{True}, @ref{53c,,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 
gh-47383@footnote{https://github.com/python/cpython/issues/47383}: The @code{P.args} and @code{P.kwargs} attributes of
@ref{295,,typing.ParamSpec} are now instances of the new classes
@ref{ba6,,typing.ParamSpecArgs} and @ref{ba7,,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{bd9,,fileinput.input()} and @ref{b1e,,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{1e6c,,__match_args__} generation
could fail for some @ref{32,,dataclasses}.

@item 
bpo-43752@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43752}: Fix @ref{d7,,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{f9,,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{33e,,threading.current_thread()}

@item 
@code{activeCount} => @ref{33f,,threading.active_count()}

@item 
@code{Condition.notifyAll} => @ref{338,,threading.Condition.notify_all()}

@item 
@code{Event.isSet} => @ref{339,,threading.Event.is_set()}

@item 
@code{Thread.setName} => @ref{33d,,threading.Thread.name}

@item 
@code{thread.getName} => @ref{33d,,threading.Thread.name}

@item 
@code{Thread.isDaemon} => @ref{33b,,threading.Thread.daemon}

@item 
@code{Thread.setDaemon} => @ref{33b,,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{1e71,,turtle.textinput()} and @ref{1e72,,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{f3c,,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{1228,,tarfile.open()} when @ref{8d,,lzma}
/ @ref{14,,bz2} are unavailable.  Patch by Anthony Sottile.

@item 
bpo-42967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42967}: Allow @ref{1c7,,bytes} @code{separator} argument in
@code{urllib.parse.parse_qs} and @code{urllib.parse.parse_qsl} when parsing
@ref{1df,,str} query strings. Previously, this raised a @code{TypeError}.

@item 
bpo-43296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43296}: Improve @ref{d7,,sqlite3} error handling: @code{sqlite3_value_blob()}
errors that set @code{SQLITE_NOMEM} now raise @ref{18fa,,MemoryError}. Patch by
Erlend E. Aasland.

@item 
bpo-43312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43312}: New functions @ref{a7f,,sysconfig.get_preferred_scheme()} and
@ref{1daf,,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{f39,,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{e4,,sysconfig}.

@item 
bpo-41282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41282}: @code{distutils.sysconfig} has been merged to @ref{e4,,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{b3,,pprint} now has support for
@ref{6e6,,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{a9e,,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{56c,,asyncio.get_event_loop()} without
running event loop. Emit deprecation warning for @ref{b,,asyncio} functions
which implicitly create a @ref{f8b,,Future} or
@ref{460,,Task} objects if there is no running event loop and no
explicit `loop' argument is passed: @ref{1035,,ensure_future()},
@ref{1e73,,wrap_future()}, @ref{9f4,,gather()},
@ref{e34,,shield()}, @ref{6cc,,as_completed()} and constructors of
@code{Future}, @code{Task},
@ref{194a,,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{14,,bz2} /
@ref{8d,,lzma} / @ref{13c,,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{c15,,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{1c70,,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{1e74,,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{bfc,,pathlib.Path.stat()} and @ref{bfd,,chmod()} now
accept a `follow_symlinks' keyword-only argument for consistency with
corresponding functions in the @ref{a5,,os} module.

@item 
bpo-39899@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39899}: @ref{dd8,,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{11f3,,pathlib.Path.expanduser()} and @ref{11f4,,home()} now
consistently raise @ref{30d,,RuntimeError} exception when a home directory
cannot be resolved. Previously a @ref{7df,,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{c15,,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{1c5e,,ctypes.c_wchar_p} type: embedded null characters would cause a
@ref{277,,ValueError} to be raised. Patch by Zackery Spytz.
@end itemize

@node Documentation<37>,Tests<40>,Library<124>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id532}@anchor{1e75}
@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{1e4f,,Py_TPFLAGS_MAPPING} and
@ref{1e50,,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<40>,Build<43>,Documentation<37>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id533}@anchor{1e76}
@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{149e,,os.replace()} rather than @ref{149d,,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{c23,,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<43>,Windows<37>,Tests<40>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id534}@anchor{1e77}
@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<37>,macOS<29>,Build<43>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id535}@anchor{1e78}
@subsubsection Windows



@itemize -

@item 
bpo-35306@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35306}: Adds additional arguments to @ref{1e79,,os.startfile()} function.

@item 
bpo-43538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43538}: Avoid raising errors from @ref{dda,,pathlib.Path.exists()} when
passed an invalid filename.

@item 
bpo-38822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38822}: Fixed @ref{4f5,,os.stat()} failing on inaccessible directories with
a trailing slash, rather than falling back to the parent directory’s
metadata. This implicitly affected @ref{dd2,,os.path.exists()} and
@ref{dd4,,os.path.isdir()}.

@item 
bpo-26227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26227}: Fixed decoding of host names in @ref{1e7a,,socket.gethostbyaddr()}
and @ref{1e7b,,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<29>,IDLE<21>,Windows<37>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id536}@anchor{1e7c}
@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<21>,C API<39>,macOS<29>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id537}@anchor{1e7d}
@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<39>,,IDLE<21>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id538}@anchor{1e7e}
@subsubsection C API



@itemize -

@item 
bpo-43916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43916}: Add a new @ref{984,,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{c7a,,PyGC_Enable()}, @ref{c7b,,PyGC_Disable()},
@ref{c7c,,PyGC_IsEnabled()}, corresponding to the functions in the
@ref{63,,gc} module.

@item 
bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}: Introduce @ref{5fb,,Py_TPFLAGS_IMMUTABLETYPE} flag for
immutable type objects, and modify @ref{b5e,,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{125e,,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{987,,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{c76,,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{c77,,Py_IsNone()}, @ref{c78,,Py_IsTrue()}, @ref{c79,,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{1e7f}
@subsection Python 3.10.0 alpha 7


`Release date: 2021-04-05'

@menu
* Security: Security<30>. 
* Core and Builtins: Core and Builtins<124>. 
* Library: Library<125>. 
* Core and Builtins: Core and Builtins<125>. 
* Library: Library<126>. 
* Documentation: Documentation<38>. 
* Tests: Tests<41>. 
* Build: Build<44>. 
* Windows: Windows<38>. 
* IDLE: IDLE<22>. 
* C API: C API<40>. 

@end menu

@node Security<30>,Core and Builtins<124>,,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id539}@anchor{1e80}
@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{bd,,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{61,,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{cca,,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{bdd,,gc.get_objects()},
@ref{bde,,gc.get_referrers()} and @ref{bdf,,gc.get_referents()}. Patch by Pablo
Galindo.
@end itemize

@node Core and Builtins<124>,Library<125>,Security<30>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id540}@anchor{1e81}
@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.
@end itemize

@node Library<125>,Core and Builtins<125>,Core and Builtins<124>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id541}@anchor{1e82}
@subsubsection Library



@itemize -

@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.
@end itemize

@node Core and Builtins<125>,Library<126>,Library<125>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id542}@anchor{1e83}
@subsubsection Core and Builtins



@itemize -

@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{17e,,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{f85,,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{1568,,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{16a5,,__exit__()} is always called in with statements, even
for interrupts.
@end itemize

@node Library<126>,Documentation<38>,Core and Builtins<125>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id543}@anchor{1e84}
@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{e1b,,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{bbe,,index()} method of @ref{6c5,,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{336,,ssl.SSLContext} debug callback
with @ref{1e85,,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{93,,mimetypes}.

@item 
bpo-40645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40645}: The @ref{6d,,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 μεταβλητή περιβάλλοντος; PYTHONWARNDEFAULTENCODING
@ref{b9d,,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{c01,,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{1e86,,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{c1a,,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{15da,,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{72,,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{1c3,,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{d7,,sqlite3} error handling: If
@code{sqlite3_column_text()} and @code{sqlite3_column_blob()} set
@code{SQLITE_NOMEM}, @ref{18fa,,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{d7,,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{2d2,,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{1e87,,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{e20,,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{aa,,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{aa,,pdb}’s interactive mode.

@item 
bpo-40701@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40701}: When the @ref{1e88,,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{1e89,,tempfile.gettempdir()} and @ref{1e8a,,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{1e8b,,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<38>,Tests<41>,Library<126>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id544}@anchor{1e8c}
@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{75d,,time.monotonic()},
@ref{e49,,time.perf_counter()}, @ref{e4a,,time.process_time()}, or
@ref{d03,,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<41>,Build<44>,Documentation<38>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id545}@anchor{1e8d}
@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<44>,Windows<38>,Tests<41>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id546}@anchor{1e8e}
@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<38>,IDLE<22>,Build<44>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id547}@anchor{1e8f}
@subsubsection Windows



@itemize -

@item 
bpo-43440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43440}: Build @ref{d7,,sqlite3} with the @code{R*Tree} module enabled. Patch
by Erlend E. Aasland.
@end itemize

@node IDLE<22>,C API<40>,Windows<38>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id548}@anchor{1e90}
@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<40>,,IDLE<22>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id549}@anchor{1e91}
@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{974,,Py_INCREF()} and @ref{975,,Py_DECREF()} functions are now implemented
as opaque function calls, rather than accessing directly the
@ref{c75,,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{19b,,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{9,,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{e1,,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{1e92}
@subsection Python 3.10.0 alpha 6


`Release date: 2021-03-01'

@menu
* Security: Security<31>. 
* Core and Builtins: Core and Builtins<126>. 
* Library: Library<127>. 
* Core and Builtins: Core and Builtins<127>. 
* Library: Library<128>. 
* Core and Builtins: Core and Builtins<128>. 
* Library: Library<129>. 
* Documentation: Documentation<39>. 
* Tests: Tests<42>. 
* Build: Build<45>. 
* Windows: Windows<39>. 
* macOS: macOS<30>. 
* IDLE: IDLE<23>. 
* C API: C API<41>. 

@end menu

@node Security<31>,Core and Builtins<126>,,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id550}@anchor{1e93}
@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<126>,Library<127>,Security<31>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id551}@anchor{1e94}
@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{c73,,PySet_CheckExact()} function to the C-API to
check if an object is an instance of @ref{42b,,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{c59,,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{184,,eval()} and @ref{185,,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{17e,,SyntaxError} message for missing comma
in literals. Patch by Pablo Galindo.
@end itemize

@node Library<127>,Core and Builtins<127>,Core and Builtins<126>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id552}@anchor{1e95}
@subsubsection Library



@itemize -

@item 
bpo-42819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42819}: @ref{c2,,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.
@end itemize

@node Core and Builtins<127>,Library<128>,Library<127>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id553}@anchor{1e96}
@subsubsection Core and Builtins



@itemize -

@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.
@end itemize

@node Library<128>,Core and Builtins<128>,Core and Builtins<127>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id554}@anchor{1e97}
@subsubsection Library



@itemize -

@item 
bpo-40692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40692}: In the @ref{206,,concurrent.futures.ProcessPoolExecutor},
validate that @code{multiprocess.synchronize()} is available on a given
platform and rely on that check in the @ref{24,,concurrent.futures} test
suite so we can run tests that are unrelated to
@code{ProcessPoolExecutor} on those platforms.
@end itemize

@node Core and Builtins<128>,Library<129>,Library<128>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id555}@anchor{1e98}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-38302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38302}: If @ref{bb0,,object.__ipow__()} returns @ref{440,,NotImplemented}, the
operator will correctly fall back to @ref{bb1,,object.__pow__()} and
@ref{442,,object.__rpow__()} as expected.
@end itemize

@node Library<129>,Documentation<39>,Core and Builtins<128>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id556}@anchor{1e99}
@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{c27,,print_exception()} and
@ref{c25,,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{d7,,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{d7,,sqlite3} error handling:
@code{sqlite3_column_name()} failures now result in @ref{18fa,,MemoryError}. Patch
by Erlend E. Aasland.

@item 
bpo-40956@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40956}: Fix segfault in @ref{f39,,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{1e9a,,readline.get_begidx()} and @ref{1e9b,,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{1d,,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{107,,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{bf3,,O_EVTONLY}, @ref{bf4,,O_FSYNC},
@ref{bf5,,O_SYMLINK} and @ref{bf6,,O_NOFOLLOW_ANY} for macOS. Patch by
Donghee Na.

@item 
bpo-42960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42960}: Adds @ref{1e9c,,resource.RLIMIT_KQUEUES} constant from FreeBSD to
the @ref{c4,,resource} module.

@item 
bpo-42151@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42151}: Make the pure Python implementation of
@ref{12e,,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<39>,Tests<42>,Library<129>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id557}@anchor{1e9d}
@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<42>,Build<45>,Documentation<39>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id558}@anchor{1e9e}
@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<45>,Windows<39>,Tests<42>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id559}@anchor{1e9f}
@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<39>,macOS<30>,Build<45>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id560}@anchor{1ea0}
@subsubsection Windows



@itemize -

@item 
bpo-43155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43155}: @ref{1ea1,,PyCMethod_New()} is now present in @code{python3.lib}.
@end itemize

@node macOS<30>,IDLE<23>,Windows<39>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id561}@anchor{1ea2}
@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<23>,C API<41>,macOS<30>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id562}@anchor{1ea3}
@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<41>,,IDLE<23>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id563}@anchor{1ea4}
@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{1ea5,,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{b63,,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{b63,,Include Files}.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: @ref{e2a,,PyExceptionClass_Name()} is now always declared as a
function, in order to hide implementation details. The macro accessed
@ref{1ea6,,PyTypeObject.tp_name} directly.  Patch by Erlend E. Aasland.

@item 
bpo-43239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43239}: The @ref{1ea7,,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{1ea8,,PyIter_Check()} is now always declared as a function, in
order to hide implementation details. The macro accessed
@ref{1892,,PyTypeObject.tp_iternext} directly. Patch by Erlend E. Aasland.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Convert @ref{1ea9,,PyDescr_IsData()} macro to a function to hide
implementation details: The macro accessed
@ref{1eaa,,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{1eab,,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{1eac}
@subsection Python 3.10.0 alpha 5


`Release date: 2021-02-02'

@menu
* Security: Security<32>. 
* Core and Builtins: Core and Builtins<129>. 
* Library: Library<130>. 
* Core and Builtins: Core and Builtins<130>. 
* Library: Library<131>. 
* Documentation: Documentation<40>. 
* Tests: Tests<43>. 
* Build: Build<46>. 
* Windows: Windows<40>. 
* macOS: macOS<31>. 
* IDLE: IDLE<24>. 
* C API: C API<42>. 

@end menu

@node Security<32>,Core and Builtins<129>,,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id564}@anchor{1ead}
@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{1eae,,ctypes.c_double} and @ref{1eaf,,ctypes.c_longdouble} values.
@end itemize

@node Core and Builtins<129>,Library<130>,Security<32>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id565}@anchor{1eb0}
@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{d4b,,Py_FatalError()} calls in the compiler with
regular @ref{3ea,,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{673,,Py_Initialize()} /
@ref{672,,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{17e,,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
@end itemize

@node Library<130>,Core and Builtins<130>,Core and Builtins<129>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id566}@anchor{1eb1}
@subsubsection Library



@itemize -

@item 
bpo-37324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37324}: Remove deprecated aliases to
@ref{c4e,,Αφηρημένες Βασικές Κλάσεις Συλλογών} from the @ref{1e,,collections}
module.
@end itemize

@node Core and Builtins<130>,Library<131>,Library<130>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id567}@anchor{1eb2}
@subsubsection Core and Builtins



@itemize -

@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<131>,Documentation<40>,Core and Builtins<130>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id568}@anchor{1eb3}
@subsubsection Library



@itemize -

@item 
bpo-43108@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43108}: Fixed a reference leak in the @ref{2e,,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{104,,tokenize} by 20-30%.  Patch by
Anthony Sottile.

@item 
bpo-42323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42323}: Fix @ref{8a9,,math.nextafter()} for NaN on AIX.

@item 
bpo-42955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42955}: Add @ref{c1a,,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{764,,TracebackException}’s new @code{compact}
param in @ref{1510,,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{764,,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{d4b,,Py_FatalError()} function and the
@ref{5b,,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{764,,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 @code{cProfile} and @code{profile} to catch
@ref{1404,,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{2e,,curses} module if available.

@item 
bpo-33289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33289}: Correct call to @ref{fa,,tkinter.colorchooser} to return RGB
triplet of ints instead of floats.  Patch by Cheryl Sabella.
@end itemize

@node Documentation<40>,Tests<43>,Library<131>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id569}@anchor{1eb4}
@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<43>,Build<46>,Documentation<40>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id570}@anchor{1eb5}
@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{d7,,sqlite3} tests. Patch by Erlend E.
Aasland.

@item 
bpo-40810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40810}: In @ref{d7,,sqlite3}, fix @code{CheckTraceCallbackContent} for SQLite
pre 3.7.15.
@end itemize

@node Build<46>,Windows<40>,Tests<43>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id571}@anchor{1eb6}
@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{58,,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<40>,macOS<31>,Build<46>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id572}@anchor{1eb7}
@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<31>,IDLE<24>,Windows<40>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id573}@anchor{1eb8}
@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<24>,C API<42>,macOS<31>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id574}@anchor{1eb9}
@subsubsection IDLE



@itemize -

@item 
bpo-43008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43008}: Make IDLE invoke @ref{be5,,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<42>,,IDLE<24>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id575}@anchor{1eba}
@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{1ebb,,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{1ebc}
@subsection Python 3.10.0 alpha 4


`Release date: 2021-01-04'

@menu
* Core and Builtins: Core and Builtins<131>. 
* Library: Library<132>. 
* Core and Builtins: Core and Builtins<132>. 
* Library: Library<133>. 
* Core and Builtins: Core and Builtins<133>. 
* Library: Library<134>. 
* Documentation: Documentation<41>. 
* Tests: Tests<44>. 
* Build: Build<47>. 
* macOS: macOS<32>. 
* Tools/Demos: Tools/Demos<26>. 
* C API: C API<43>. 

@end menu

@node Core and Builtins<131>,Library<132>,,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id576}@anchor{1ebd}
@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{9,,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{445,,-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
@end itemize

@node Library<132>,Core and Builtins<132>,Core and Builtins<131>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id577}@anchor{1ebe}
@subsubsection Library



@itemize -

@item 
bpo-42639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42639}: Make the @ref{d,,atexit} module state per-interpreter. It is now
safe have more than one @code{atexit} module instance. Patch by Donghee Na
and Victor Stinner.
@end itemize

@node Core and Builtins<132>,Library<133>,Library<132>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id578}@anchor{1ebf}
@subsubsection Core and Builtins



@itemize -

@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{1ec0,,PyRun_SimpleFileExFlags()} now uses the correct encoding to
decode the filename.
@end itemize

@node Library<133>,Core and Builtins<133>,Core and Builtins<132>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id579}@anchor{1ec1}
@subsubsection Library



@itemize -

@item 
bpo-42195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42195}: The @code{__args__} of the parameterized generics for
@ref{ba5,,typing.Callable} and @ref{bc6,,collections.abc.Callable} are now
consistent.  The @code{__args__} for @code{collections.abc.Callable} are
now flattened while @code{typing.Callable}’s have not changed.  To allow
this change, @ref{bc7,,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{390,,PyType_FromModuleAndSpec()}.

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @ref{8,,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/}).
@end itemize

@node Core and Builtins<133>,Library<134>,Library<133>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id580}@anchor{1ec2}
@subsubsection Core and Builtins



@itemize -

@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<134>,Documentation<41>,Core and Builtins<133>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id581}@anchor{1ec3}
@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{1ec4,,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{315,,typing.get_args()} and @ref{314,,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{df,,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{101,,tkinter.simpledialog}),
message boxes (@ref{ff,,tkinter.messagebox}) or color choose dialog
(@ref{fa,,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{1ec5,,collections.deque.remove()}.

@item 
bpo-35728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35728}: Added a root parameter to @ref{1ec6,,tkinter.font.nametofont()}.

@item 
bpo-15303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15303}: @ref{f9,,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{2e,,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{1ec7,,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{f9,,tkinter} functions and constructors which need a default
root window raise now @ref{30d,,RuntimeError} with descriptive message instead
of obscure @ref{1a9,,AttributeError} or @ref{665,,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{70c,,sys.unraisablehook}, rather than logging them directly into
@ref{d05,,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{c54,,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{10d,,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{fd7,,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{b2b,,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{107,,traceback} and the interpreter
in formatting of SyntaxError with lineno not set (@code{traceback} was
changed to match interpreter).

@item 
bpo-42393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42393}: Raise @ref{c57,,OverflowError} instead of silent truncation in
@ref{c56,,socket.ntohs()} and @ref{c55,,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{c41,,random.randrange()} argument handling to match
@ref{d0f,,range()}.


@itemize *

@item 
The integer test and conversion in @code{randrange()} now uses
@ref{1ec8,,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{290,,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{4bd,,inspect.signature()} and @ref{b20,,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{11ed,,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{f,,base64}. Patch by Brandon Stansbury.
@end itemize

@node Documentation<41>,Tests<44>,Library<134>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id582}@anchor{1ec9}
@subsubsection Documentation



@itemize -

@item 
bpo-17140@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17140}: Add documentation for the
@ref{1eca,,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<44>,Build<47>,Documentation<41>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id583}@anchor{1ecb}
@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<47>,macOS<32>,Tests<44>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id584}@anchor{1ecc}
@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<32>,Tools/Demos<26>,Build<47>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id585}@anchor{1ecd}
@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<26>,C API<43>,macOS<32>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id586}@anchor{1ece}
@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<43>,,Tools/Demos<26>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id587}@anchor{1ecf}
@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{c4,,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{1ed0}
@subsection Python 3.10.0 alpha 3


`Release date: 2020-12-07'

@menu
* Security: Security<33>. 
* Core and Builtins: Core and Builtins<134>. 
* Library: Library<135>. 
* Core and Builtins: Core and Builtins<135>. 
* Library: Library<136>. 
* Core and Builtins: Core and Builtins<136>. 
* Library: Library<137>. 
* Core and Builtins: Core and Builtins<137>. 
* Library: Library<138>. 
* Documentation: Documentation<42>. 
* Tests: Tests<45>. 
* Build: Build<48>. 
* Windows: Windows<41>. 
* macOS: macOS<33>. 
* IDLE: IDLE<25>. 
* Tools/Demos: Tools/Demos<27>. 
* C API: C API<44>. 

@end menu

@node Security<33>,Core and Builtins<134>,,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id588}@anchor{1ed1}
@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<134>,Library<135>,Security<33>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id589}@anchor{1ed2}
@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{19de,,garbage collector}:


@itemize -

@item 
@ref{9d5,,collections.OrderedDict.items()}

@item 
@ref{baf,,dict.items()}

@item 
@ref{1823,,enumerate()}

@item 
@ref{153,,functools.reduce()}

@item 
@ref{16b6,,itertools.combinations()}

@item 
@ref{1626,,itertools.combinations_with_replacement()}

@item 
@ref{1961,,itertools.permutations()}

@item 
@ref{16b7,,itertools.product()}

@item 
@ref{1643,,itertools.zip_longest()}

@item 
@ref{43f,,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{2ed,,-b} is specified. Speed up comparison of bytarray
objects with non-buffer object.
@end itemize

@node Library<135>,Core and Builtins<135>,Core and Builtins<134>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id590}@anchor{1ed3}
@subsubsection Library



@itemize -

@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.
@end itemize

@node Core and Builtins<135>,Library<136>,Library<135>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id591}@anchor{1ed4}
@subsubsection Core and Builtins



@itemize -

@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{c91,,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{bc7,,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.
@end itemize

@node Library<136>,Core and Builtins<136>,Core and Builtins<135>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id592}@anchor{1ed5}
@subsubsection Library



@itemize -

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @ref{be,,queue} to use heap types.
@end itemize

@node Core and Builtins<136>,Library<137>,Library<136>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id593}@anchor{1ed6}
@subsubsection Core and Builtins



@itemize -

@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.
@end itemize

@node Library<137>,Core and Builtins<137>,Core and Builtins<136>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id594}@anchor{1ed7}
@subsubsection Library



@itemize -

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @ref{94,,mmap} to use heap types.
@end itemize

@node Core and Builtins<137>,Library<138>,Library<137>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id595}@anchor{1ed8}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-42233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42233}: Allow @code{GenericAlias} objects to use @ref{ba2,,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<138>,Documentation<42>,Core and Builtins<137>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id596}@anchor{1ed9}
@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{53c,,OSError} instead of
@ref{18d7,,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{1a04,,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{764,,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{bff,,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 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{12eb,,filecmp.dircmp} respect subclassing. Now the
@ref{1eda,,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{c0d,,socket.timeout} is now an alias of
@ref{c0e,,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{7a,,importlib} external bootstrap code:
@code{importlib._bootstrap_external} now uses regular imports to import
builtin modules. When it is imported, the builtin @ref{ca6,,__import__()}
function is already fully working and so can be used to import builtin
modules like @ref{e2,,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{75e,,time.time()}, @ref{e49,,time.perf_counter()} and
@ref{75d,,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{1edb,,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{e49,,time.perf_counter()} on Windows and @ref{75d,,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{eac,,time.perf_counter_ns()} and @ref{eab,,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{f9,,tkinter} on macOS.

@item 
bpo-42350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42350}: Fix the @ref{420,,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{c22,,threading.__excepthook__} to allow retrieving the
original value of @ref{c23,,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{1df,,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{c1e,,threading.gettrace()} and
@ref{c1f,,threading.getprofile()} to retrieve the functions set by
@ref{c20,,threading.settrace()} and @ref{c21,,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{1e2c,,os.device_encoding()} function now returns
@code{'UTF-8'} rather than the device encoding if the @ref{a46,,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{c25,,traceback.format_exception()},
@ref{c26,,traceback.format_exception_only()}, and
@ref{c27,,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{d7,,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{1edc,,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{bf2,,os.splice()} in the
@ref{a5,,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{1edd,,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{bf9,,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{114,,urllib.request} and @ref{72,,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{bf1,,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{bc,,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{bf9,,pathlib.PurePath.parents}.
@end itemize

@node Documentation<42>,Tests<45>,Library<138>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id597}@anchor{1ede}
@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<45>,Build<48>,Documentation<42>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id598}@anchor{1edf}
@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<48>,Windows<41>,Tests<45>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id599}@anchor{1ee0}
@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<41>,macOS<33>,Build<48>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id600}@anchor{1ee1}
@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<33>,IDLE<25>,Windows<41>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id601}@anchor{1ee2}
@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<25>,Tools/Demos<27>,macOS<33>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id602}@anchor{1ee3}
@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<27>,C API<44>,IDLE<25>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id603}@anchor{1ee4}
@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<44>,,Tools/Demos<27>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id604}@anchor{1ee5}
@subsubsection C API



@itemize -

@item 
bpo-42423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42423}: The @ref{38f,,PyType_FromSpecWithBases()} and
@ref{390,,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{c9,,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{63,,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{5f5,,Py_TYPE()} and @ref{b61,,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{e1,,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{69,,grp} and @ref{ba,,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{c91,,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}: @code{Py_GetPath()}, @code{Py_GetPrefix()},
@code{Py_GetExecPrefix()}, @code{Py_GetProgramFullPath()},
@code{Py_GetPythonHome()} and @code{Py_GetProgramName()} functions now
return @code{NULL} if called before @ref{673,,Py_Initialize()} (before Python is
initialized). Use the new @ref{837,,Python Initialization Configuration API} to get the @ref{c80,,Python Path Configuration.}. Patch by Victor Stinner.

@item 
bpo-42260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42260}: The @ref{b6f,,PyConfig_Read()} function now only parses
@ref{607,,PyConfig.argv} arguments once: @ref{1ee6,,PyConfig.parse_argv}
is set to @code{2} after arguments are parsed. Since Python arguments are
strippped from @code{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{c70,,Py_NewRef()} and @ref{c71,,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{673,,Py_Initialize()} is called twice, the second call
now updates more @ref{e2,,sys} attributes for the configuration, rather than
only @ref{1609,,sys.argv}. Patch by Victor Stinner.

@item 
bpo-41832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41832}: The @ref{390,,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{800,,PyModule_AddObjectRef()} function: similar to
@ref{801,,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{34b,,METH_FASTCALL} calling convention is added to the
limited API. The functions  @ref{d3d,,PyModule_AddType()},
@ref{390,,PyType_FromModuleAndSpec()}, @ref{d37,,PyType_GetModule()} and
@ref{d38,,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{c72,,PyType_GetSlot()} can now accept static types.

@item 
bpo-30459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30459}: @ref{822,,PyList_SET_ITEM()}, @ref{821,,PyTuple_SET_ITEM()} and
@ref{c81,,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{1ee7}
@subsection Python 3.10.0 alpha 2


`Release date: 2020-11-03'

@menu
* Security: Security<34>. 
* Core and Builtins: Core and Builtins<138>. 
* Library: Library<139>. 
* Core and Builtins: Core and Builtins<139>. 
* Library: Library<140>. 
* Documentation: Documentation<43>. 
* Tests: Tests<46>. 
* Build: Build<49>. 
* Windows: Windows<42>. 
* macOS: macOS<34>. 
* IDLE: IDLE<26>. 
* C API: C API<45>. 

@end menu

@node Security<34>,Core and Builtins<138>,,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id605}@anchor{1ee8}
@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{b0,,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<138>,Library<139>,Security<34>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id606}@anchor{1ee9}
@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{9,,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{17e,,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{328,,complex} class.  They
always raised a @ref{291,,TypeError}.

@item 
bpo-41902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41902}: Micro optimization when compute
@ref{1eea,,sq_item} and
@ref{1eeb,,mp_subscript} of @ref{d0f,,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.
@end itemize

@node Library<139>,Core and Builtins<139>,Core and Builtins<138>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id607}@anchor{1eec}
@subsubsection Library



@itemize -

@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.
@end itemize

@node Core and Builtins<139>,Library<140>,Library<139>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id608}@anchor{1eed}
@subsubsection Core and Builtins



@itemize -

@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 @ref{66b,,__annotations__} dicts are now
strings, for example @code{@{"x": "int"@}} instead of @code{@{"x": int@}}.
@end itemize

@node Library<140>,Documentation<43>,Core and Builtins<139>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id609}@anchor{1eee}
@subsubsection Library



@itemize -

@item 
bpo-35455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35455}: On Solaris, @ref{d03,,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{45b,,repr()} of @ref{10d,,typing} types containing
@ref{a9f,,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{1e4a,,logging.FileHandler} class now keeps a reference to
the builtin @ref{32b,,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{10e,,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{6bf,,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}: @ref{1eef,,InvalidFileException} and @ref{1121,,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{48e,,datetime.time} subclasses.
Patch by Dean Inwood.

@item 
bpo-19270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19270}: @ref{1ef0,,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{1869,,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{6bf,,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{d7,,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{10fe,,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{ba9,,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}: @ref{313,,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{6e6,,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{8c4,,shutil.which()} now ignores empty entries in
@geindex PATHEXT
@geindex μεταβλητή περιβάλλοντος; 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 @code{cProfile} / @code{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{cb,,shelve} module now uses
@ref{c07,,pickle.DEFAULT_PROTOCOL} by default instead of @ref{ab,,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{73,,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<43>,Tests<46>,Library<140>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id610}@anchor{1ef1}
@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{1ef2,,classes} and @ref{1ef3,,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{a9f,,generic alias type} and
@ref{bc7,,types.GenericAlias}. Also added an entry in glossary for
@ref{1d1,,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<46>,Build<49>,Documentation<43>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id611}@anchor{1ef4}
@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<49>,Windows<42>,Tests<46>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id612}@anchor{1ef5}
@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<42>,macOS<34>,Build<49>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id613}@anchor{1ef6}
@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<34>,IDLE<26>,Windows<42>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id614}@anchor{1ef7}
@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<26>,C API<45>,macOS<34>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id615}@anchor{1ef8}
@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<45>,,IDLE<26>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id616}@anchor{1ef9}
@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{1879,,PyMethodDef}’s lifetime is managed through
the @code{self} argument of a @ref{181a,,PyCFunction}.

@item 
bpo-40423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40423}: The @ref{df,,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{1efa,,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{1efb}
@subsection Python 3.10.0 alpha 1


`Release date: 2020-10-05'

@menu
* Security: Security<35>. 
* Core and Builtins: Core and Builtins<140>. 
* Library: Library<141>. 
* Core and Builtins: Core and Builtins<141>. 
* Library: Library<142>. 
* Core and Builtins: Core and Builtins<142>. 
* Library: Library<143>. 
* Core and Builtins: Core and Builtins<143>. 
* Library: Library<144>. 
* Core and Builtins: Core and Builtins<144>. 
* Library: Library<145>. 
* Core and Builtins: Core and Builtins<145>. 
* Library: Library<146>. 
* Core and Builtins: Core and Builtins<146>. 
* Library: Library<147>. 
* Core and Builtins: Core and Builtins<147>. 
* Library: Library<148>. 
* Core and Builtins: Core and Builtins<148>. 
* Library: Library<149>. 
* Core and Builtins: Core and Builtins<149>. 
* Library: Library<150>. 
* Core and Builtins: Core and Builtins<150>. 
* Library: Library<151>. 
* Core and Builtins: Core and Builtins<151>. 
* Library: Library<152>. 
* Core and Builtins: Core and Builtins<152>. 
* Library: Library<153>. 
* Core and Builtins: Core and Builtins<153>. 
* Library: Library<154>. 
* Core and Builtins: Core and Builtins<154>. 
* Library: Library<155>. 
* Documentation: Documentation<44>. 
* Tests: Tests<47>. 
* Build: Build<50>. 
* Windows: Windows<43>. 
* macOS: macOS<35>. 
* IDLE: IDLE<27>. 
* C API: C API<46>. 

@end menu

@node Security<35>,Core and Builtins<140>,,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id617}@anchor{1efc}
@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<140>,Library<141>,Security<35>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id618}@anchor{1efd}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-41909@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41909}: Fixed stack overflow in @ref{2f0,,issubclass()} and
@ref{2ef,,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.
@end itemize

@node Library<141>,Core and Builtins<141>,Core and Builtins<140>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id619}@anchor{1efe}
@subsubsection Library



@itemize -

@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/}).
@end itemize

@node Core and Builtins<141>,Library<142>,Library<141>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id620}@anchor{1eff}
@subsubsection Core and Builtins



@itemize -

@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{bc7,,types.GenericAlias}. Patch by
Batuhan Taskaya.
@end itemize

@node Library<142>,Core and Builtins<142>,Core and Builtins<141>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id621}@anchor{1f00}
@subsubsection Library



@itemize -

@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{19,,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{ea,,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.
@end itemize

@node Core and Builtins<142>,Library<143>,Library<142>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id622}@anchor{1f01}
@subsubsection Core and Builtins



@itemize -

@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.
@end itemize

@node Library<143>,Core and Builtins<143>,Core and Builtins<142>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id623}@anchor{1f02}
@subsubsection Library



@itemize -

@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/}).
@end itemize

@node Core and Builtins<143>,Library<144>,Library<143>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id624}@anchor{1f03}
@subsubsection Core and Builtins



@itemize -

@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{a12,,str.format()}.
@end itemize

@node Library<144>,Core and Builtins<144>,Core and Builtins<143>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id625}@anchor{1f04}
@subsubsection Library



@itemize -

@item 
bpo-41675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41675}: The implementation of @ref{14e1,,signal.siginterrupt()} now uses
@code{sigaction()} (if it is available in the system) instead of the
deprecated @code{siginterrupt()}. Patch by Pablo Galindo.
@end itemize

@node Core and Builtins<144>,Library<145>,Library<144>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id626}@anchor{1f05}
@subsubsection Core and Builtins



@itemize -

@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{18fa,,MemoryError}. Patch by Pablo Galindo.
@end itemize

@node Library<145>,Core and Builtins<145>,Core and Builtins<144>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id627}@anchor{1f06}
@subsubsection Library



@itemize -

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @ref{13c,,zlib} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).
@end itemize

@node Core and Builtins<145>,Library<146>,Library<145>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id628}@anchor{1f07}
@subsubsection Core and Builtins



@itemize -

@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.
@end itemize

@node Library<146>,Core and Builtins<146>,Core and Builtins<145>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id629}@anchor{1f08}
@subsubsection Library



@itemize -

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @code{_operator} to use @ref{38e,,PyType_FromSpec()}.
@end itemize

@node Core and Builtins<146>,Library<147>,Library<146>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id630}@anchor{1f09}
@subsubsection Core and Builtins



@itemize -

@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.
@end itemize

@node Library<147>,Core and Builtins<147>,Core and Builtins<146>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id631}@anchor{1f0a}
@subsubsection Library



@itemize -

@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/}).
@end itemize

@node Core and Builtins<147>,Library<148>,Library<147>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id632}@anchor{1f0b}
@subsubsection Core and Builtins



@itemize -

@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.
@end itemize

@node Library<148>,Core and Builtins<148>,Core and Builtins<147>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id633}@anchor{1f0c}
@subsubsection Library



@itemize -

@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/}).
@end itemize

@node Core and Builtins<148>,Library<149>,Library<148>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id634}@anchor{1f0d}
@subsubsection Core and Builtins



@itemize -

@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{167f,,round()} with integer argument is now faster (9–60%).

@item 
bpo-41334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41334}: Constructors @ref{1df,,str()}, @ref{1c7,,bytes()} and @ref{1c6,,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{98,,multiprocessing} to multi-phase initialization
@end itemize

@node Library<149>,Core and Builtins<149>,Core and Builtins<148>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id635}@anchor{1f0e}
@subsubsection Library



@itemize -

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{winapi} to multiphase initialization
@end itemize

@node Core and Builtins<149>,Library<150>,Library<149>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id636}@anchor{1f0f}
@subsubsection Core and Builtins



@itemize -

@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.
@end itemize

@node Library<150>,Core and Builtins<150>,Core and Builtins<149>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id637}@anchor{1f10}
@subsubsection Library



@itemize -

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{5b,,faulthandler} to multiphase initialization.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{sha256} to multiphase initialization
@end itemize

@node Core and Builtins<150>,Library<151>,Library<150>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id638}@anchor{1f11}
@subsubsection Core and Builtins



@itemize -

@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{17e,,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.
@end itemize

@node Library<151>,Core and Builtins<151>,Core and Builtins<150>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id639}@anchor{1f12}
@subsubsection Library



@itemize -

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @code{_bz2} to use @ref{38e,,PyType_FromSpec()}.
@end itemize

@node Core and Builtins<151>,Library<152>,Library<151>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id640}@anchor{1f13}
@subsubsection Core and Builtins



@itemize -

@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{43f,,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{277,,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{17e,,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
@end itemize

@node Library<152>,Core and Builtins<152>,Core and Builtins<151>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id641}@anchor{1f14}
@subsubsection Library



@itemize -

@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.
@end itemize

@node Core and Builtins<152>,Library<153>,Library<152>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id642}@anchor{1f15}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-40947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40947}: The Python @ref{c80,,Path Configuration} now
takes @ref{1f16,,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{17e,,SyntaxError} for valid
input due to this. For example, an empty line following a line
continuation character was interpreted as a @code{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{189,,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{277,,ValueError} when validating custom AST’s where the
constants @code{True}, @code{False} and @code{None} are used within a
@ref{1f17,,ast.Name} node.

@item 
bpo-40854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40854}: Allow overriding @ref{2a9,,sys.platlibdir} via a new
@geindex PYTHONPLATLIBDIR
@geindex μεταβλητή περιβάλλοντος; PYTHONPLATLIBDIR
@ref{1f18,,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{5c,,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{323,,in} operator and functions
@ref{cac,,contains()}, @ref{cad,,indexOf()} and
@ref{cae,,countOf()} of the @ref{a3,,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{d0f,,range} object now always has exact type @ref{326,,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{17e,,SyntaxError} in the expression part of an
fstring, the filename attribute of the @code{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{38f,,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{5f5,,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{905,,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{291,,TypeError} messages about missing or extra
arguments now include the function’s @ref{1f19,,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{905,,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.
@end itemize

@node Library<153>,Core and Builtins<153>,Core and Builtins<152>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id643}@anchor{1f1a}
@subsubsection Library



@itemize -

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{94,,mmap} to multiphase initialization.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{_lzma} to multiphase initialization.
@end itemize

@node Core and Builtins<153>,Library<154>,Library<153>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id644}@anchor{1f1b}
@subsubsection Core and Builtins



@itemize -

@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{1c2,,Decimal}s, @ref{1c3,,Fraction}s and other objects that can be converted to integers only with a loss
(e.g. that have the @ref{43c,,__int__()} method but do not have the
@ref{43d,,__index__()} method).

@item 
bpo-29882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29882}: Add @ref{bac,,int.bit_count()}, counting the number of ones in the
binary representation of an integer. Patch by Niklas Fiekas.
@end itemize

@node Library<154>,Core and Builtins<154>,Core and Builtins<153>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id645}@anchor{1f1c}
@subsubsection Library



@itemize -

@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{bd0,,curses.has_extended_color_support()} to indicate whether extended
color support is provided by the underlying ncurses library.
@end itemize

@node Core and Builtins<154>,Library<155>,Library<154>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id646}@anchor{1f1d}
@subsubsection Core and Builtins



@itemize -

@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<155>,Documentation<44>,Core and Builtins<154>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id647}@anchor{1f1e}
@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{fd7,,ast.literal_eval()}. Also
document stripping of spaces and tabs for @ref{184,,eval()}.

@item 
bpo-41773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41773}: Note in documentation that @ref{1083,,random.choices()} doesn’t
support non-finite weights, raise @ref{277,,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{e1,,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{bc4,,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{186a,,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{420,,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{c29,,types.EllipsisType}, @ref{c2b,,types.NotImplementedType}
and @ref{c2a,,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{6ce,,iterator} to @ref{1d2,,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{309,,asyncio.run()}. This allows
setting @code{PYTHONASYNCIODEBUG} or @code{-X dev} to enable asyncio debug mode
when using @code{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{d7,,sqlite3} with
@ref{57d,,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{57d,,ProgrammingError} message for absent parameter
in @ref{d7,,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{d7,,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{9f6,,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{9f6,,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{1d,,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{1404,,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{6e1,,os.cpu_count()} support for VxWorks RTOS.

@item 
bpo-41316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41316}: Fix the @ref{e7,,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{119,,uuid}.

@item 
bpo-35328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35328}: Set the environment variable @code{VIRTUAL_ENV_PROMPT} at
@ref{11a,,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{14ee,,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{6c5,,array.array} as a
@ref{6c6,,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{19f2,,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{53c,,OSError} to ignore error if the filesystem
is read-only, instead of only ignoring @ref{243,,FileNotFoundError} and
@ref{10f9,,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{106,,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{153,,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{c9,,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{1f1f,,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{2d4,,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{cb1,,zoneinfo.ZoneInfo} from being subclassed.

@item 
bpo-35018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35018}: Add the @ref{c33,,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{58,,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{df,,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{87,,keyword} module.

@item 
bpo-23427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23427}: Add @ref{c19,,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{1839,,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{2c,,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{c9,,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{1f20,,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{62,,functools} module has been moved to a new
@ref{68,,graphlib} module to better accommodate the new tools and keep the
original scope of the @code{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{898,,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{d7,,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{1ec8,,operator.index()} now always has exact type
@ref{326,,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{11e,,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{2d,,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{1f21,,PyErr_Print()}.

@item 
bpo-16995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16995}: Add @ref{1e9,,base64.b32hexencode()} and @ref{1ea,,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{d8,,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{1f22,,os.RWF_APPEND} flag for @ref{f1d,,os.pwritev()}.

@item 
bpo-40737@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40737}: Fix possible reference leak for @ref{d7,,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{1d0c,,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{6b,,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{2f1,,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{1c9,,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{1925,,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 @code{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{d3d,,PyModule_AddType()}.

@item 
bpo-32309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32309}: Added a new @ref{8a2,,coroutine} @ref{cb9,,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{cba,,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{1f23,,MAP_POPULATE} constant has now been added to the
list of exported @ref{94,,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{bb,,py_compile}. Patch by Gregory Schevchenko.

@item 
bpo-35714@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35714}: @ref{16c8,,struct.error} is now raised if there is a null character
in a @ref{de,,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{2d4,,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{899,,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{291,,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{2a0,,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{c4d,,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<44>,Tests<47>,Library<155>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id648}@anchor{1f24}
@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{1f25,,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<47>,Build<50>,Documentation<44>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id649}@anchor{1f26}
@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{ed,,test.support}: Rename @code{blacklist} parameter of
@ref{1f27,,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{bbe,,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{1f28,,skip_if_broken_multiprocessing_synchronize()} function
to the @ref{ed,,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{77,,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{98,,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<50>,Windows<43>,Tests<47>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id650}@anchor{1f29}
@subsubsection Build



@itemize -

@item 
bpo-38249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38249}: Update @ref{f73,,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{13d,,zoneinfo} module and its tests
were not included when Python is installed with @code{make}.
@end itemize

@node Windows<43>,macOS<35>,Build<50>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id651}@anchor{1f2a}
@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<35>,IDLE<27>,Windows<43>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id652}@anchor{1f2b}
@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<27>,C API<46>,macOS<35>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id653}@anchor{1f2c}
@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<46>,,IDLE<27>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id654}@anchor{1f2d}
@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{c90,,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{c84,,PyUnicode_InternInPlace()}
instead. Patch by Victor Stinner.

@item 
bpo-41842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41842}: Add @ref{c6d,,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{c90,,PyInterpreterState}
structure. Patch by Victor Stinner.

@item 
bpo-41689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41689}: Types created with @ref{38e,,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 @ref{1f2e,,PyOS_mystrnicmp()} and
@ref{1f2f,,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{c6b,,PyDateTime_DATE_GET_TZINFO()} and
@ref{c6c,,PyDateTime_TIME_GET_TZINFO()} macros for accessing the @code{tzinfo}
attributes of @ref{6e7,,datetime.datetime} and @ref{48e,,datetime.time}
objects.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Revert @ref{1f30,,PyType_HasFeature()} change: it reads again
directly the @ref{1e68,,PyTypeObject.tp_flags} member when the limited C
API is not used, rather than always calling @ref{1f31,,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{82c,,PyObject_GetBuffer()} and @ref{82d,,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 @ref{1f32,,PyObject_INIT()} and @ref{1f33,,PyObject_INIT_VAR()}
macros become aliases to, respectively, @ref{e2f,,PyObject_Init()} and
@ref{1f34,,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{3b1,,PyArg_ParseTuple()} and @ref{5ee,,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{601,,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{1f35,,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{81c,,PyDict_GetItem()} without @ref{411,,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}: @ref{1f36,,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{c69,,PyNumber_Index()} now always has exact
type @ref{326,,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{54b,,Py_REFCNT()} and @ref{b61,,Py_SIZE()} macros to
static inline functions. They cannot be used as l-value anymore: use
@ref{c7e,,Py_SET_REFCNT()} and @ref{b62,,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{19b,,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{1f37}
@subsection Python 3.9.0 beta 1


`Release date: 2020-05-19'

@menu
* Security: Security<36>. 
* Core and Builtins: Core and Builtins<155>. 
* Library: Library<156>. 
* Documentation: Documentation<45>. 
* Tests: Tests<48>. 
* Build: Build<51>. 
* Windows: Windows<44>. 
* macOS: macOS<36>. 
* Tools/Demos: Tools/Demos<28>. 
* C API: C API<47>. 

@end menu

@node Security<36>,Core and Builtins<155>,,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id655}@anchor{1f38}
@subsubsection Security



@itemize -

@item 
bpo-40501@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40501}: @ref{119,,uuid} no longer uses @ref{2d,,ctypes} to load
@code{libuuid} or @code{rpcrt4.dll} at runtime.
@end itemize

@node Core and Builtins<155>,Library<156>,Security<36>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id656}@anchor{1f39}
@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{1f3a,,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{1d51,,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{5a,,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{9e2,,hash()} and @ref{c3c,,reversed()} to
@ref{e15,,weakref.proxy} objects. Patch by Pablo Galindo.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{e5,,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{905,,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{d0e,,PyLong_FromDouble()} for values
that fit into long.
@end itemize

@node Library<156>,Documentation<45>,Core and Builtins<155>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id657}@anchor{1f3b}
@subsubsection Library



@itemize -

@item 
bpo-40662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40662}: Fixed @ref{d9c,,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{12,,bisect} to use Argument Clinic.

@item 
bpo-40536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40536}: Added the @ref{1f3c,,available_timezones()} function to the
@ref{13d,,zoneinfo} module. Patch by Paul Ganssle.

@item 
bpo-40645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40645}: The @ref{efd,,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{6b,,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{6b,,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{22c,,inspect.getdoc()}.

@item 
bpo-40607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40607}: When cancelling a task due to timeout, @ref{9f6,,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{13d,,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{d8,,ssl} and @ref{6b,,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{460,,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{db3,,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{460,,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{21,,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{fd7,,ast.literal_eval()} in the
presence of malformed @ref{1f3d,,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{1f3e,,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{10cb,,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{36,,dbm.gnu} to use gdbm_count if possible when
calling @ref{a1f,,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{1f3f,,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{24,,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{ce4,,close()} method to
the @ref{ce3,,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{1240,,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{cd6,,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{189,,types.MappingProxyType} is now reversible.

@item 
bpo-39075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39075}: The repr for @ref{6ea,,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{d03,,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{48d,,datetime.date} and
@ref{6e7,,datetime.datetime} now return a @ref{a3d,,named tuple} instead of a
@ref{1ce,,tuple}.
@end itemize

@node Documentation<45>,Tests<48>,Library<156>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id658}@anchor{1f40}
@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{891,,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{10cb,,pickle.loads()} in the docs
@end itemize

@node Tests<48>,Build<51>,Documentation<45>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id659}@anchor{1f41}
@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<51>,Windows<44>,Tests<48>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id660}@anchor{1f42}
@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<44>,macOS<36>,Build<51>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id661}@anchor{1f43}
@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{b,,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<36>,Tools/Demos<28>,Windows<44>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id662}@anchor{1f44}
@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<28>,C API<47>,macOS<36>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id663}@anchor{1f45}
@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<47>,,Tools/Demos<28>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id664}@anchor{1f46}
@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{b6d,,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{d56,,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{b65,,PyFrame_GetBack()} function: get the frame next
outer frame.

@item 
bpo-40421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40421}: New @ref{b69,,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{38f,,PyType_FromSpecWithBases()} will visit its class object when
traversing references in the garbage collector (implemented as an
extension of the provided @ref{36b,,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{1f47}
@subsection Python 3.9.0 alpha 6


`Release date: 2020-04-27'

@menu
* Security: Security<37>. 
* Core and Builtins: Core and Builtins<156>. 
* Library: Library<157>. 
* Documentation: Documentation<46>. 
* Tests: Tests<49>. 
* Build: Build<52>. 
* Windows: Windows<45>. 
* macOS: macOS<37>. 
* IDLE: IDLE<28>. 
* Tools/Demos: Tools/Demos<29>. 
* C API: C API<48>. 

@end menu

@node Security<37>,Core and Builtins<156>,,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id665}@anchor{1f48}
@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{1e66,,AbstractBasicAuthHandler} class of the
@ref{114,,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<156>,Library<157>,Security<37>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id666}@anchor{1f49}
@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{c4,,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{91,,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{38e,,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{1b9e,,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<157>,Documentation<46>,Core and Builtins<156>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id667}@anchor{1f4a}
@subsubsection Library



@itemize -

@item 
bpo-40398@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40398}: @ref{315,,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{314,,typing.get_origin()}, @ref{315,,typing.get_args()}
and @ref{a9e,,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{df,,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{1153,,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{294,,typing.TypeVar}. Patch by Weipeng Hong.

@item 
bpo-40275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40275}: The @ref{8a,,logging} package is now imported lazily in
@ref{10f,,unittest} only when the @ref{29f,,assertLogs()}
assertion is used.

@item 
bpo-40275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40275}: The @ref{b,,asyncio} package is now imported lazily in
@ref{10f,,unittest} only when the @ref{342,,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{10d,,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{22c,,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{bd,,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{1a36,,random.randbytes()} function and
@ref{cf6,,random.Random.randbytes()} method to generate random bytes.

@item 
bpo-40277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40277}: @ref{1cf,,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{95,,modulefinder} uses @ref{1943,,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{206,,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{e1,,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{2e4,,typing.NamedTuple} class.

@item 
bpo-36517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36517}: Multiple inheritance with @ref{2e4,,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{c6,,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{cea,,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{2df,,threading.RLock}
and @ref{1500,,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{1503,,threading.Event} to
@code{_at_fork_reinit()}.

@item 
bpo-25780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25780}: Expose @ref{cfe,,CAN_RAW_JOIN_FILTERS} in the
@ref{d4,,socket} module.

@item 
bpo-39503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39503}: @ref{1e66,,AbstractBasicAuthHandler} of
@ref{114,,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{24,,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{19ba,,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{1f4b,,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{1b45,,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{1b44,,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{1f4c,,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{fdb,,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{1b36,,sys.audit()} failures in
@ref{1baa,,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{1a04,,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{949,,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<46>,Tests<49>,Library<157>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id668}@anchor{1f4d}
@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{1f4e,,Μοντέλο Δεδομένων} docs to include @ref{188,,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{1f4f,,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<49>,Build<52>,Documentation<46>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id669}@anchor{1f50}
@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{1f51,,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{cca,,ftplib.FTP} and
@ref{ccb,,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<52>,Windows<45>,Tests<49>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id670}@anchor{1f52}
@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<45>,macOS<37>,Build<52>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id671}@anchor{1f53}
@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<37>,IDLE<28>,Windows<45>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id672}@anchor{1f54}
@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<28>,Tools/Demos<29>,macOS<37>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id673}@anchor{1f55}
@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<29>,C API<48>,IDLE<28>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id674}@anchor{1f56}
@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{cea,,os.waitstatus_to_exitcode()} to convert @ref{17ff,,os.system()} exit status
into an exit code.
@end itemize

@node C API<48>,,Tools/Demos<29>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id675}@anchor{1f57}
@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{d4c,,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{d3e,,PyObject_GC_IsTracked()} and
@ref{d3f,,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{d4d,,PyObject_New()} macro, and the @code{PyObject_NEW_VAR()} macro
becomes an alias to the @ref{d4e,,PyObject_NewVar()} macro, to hide
implementation details. They no longer access directly the
@ref{d4f,,PyTypeObject.tp_basicsize} member.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: @ref{1f30,,PyType_HasFeature()} now always calls
@ref{1f31,,PyType_GetFlags()} to hide implementation details. Previously, it
accessed directly the @ref{1e68,,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{d50,,PyTypeObject.tp_weaklistoffset} member.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Convert @ref{82b,,PyObject_CheckBuffer()} macro to a function to
hide implementation details: the macro accessed directly the
@ref{d51,,PyTypeObject.tp_as_buffer} member.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Always declare @ref{d52,,PyIndex_Check()} as an opaque function to
hide implementation details: remove @code{PyIndex_Check()} macro. The macro
accessed directly the @ref{d53,,PyTypeObject.tp_as_number} member.

@item 
bpo-39947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39947}: Add @ref{d3b,,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{1f58}
@subsection Python 3.9.0 alpha 5


`Release date: 2020-03-23'

@menu
* Security: Security<38>. 
* Core and Builtins: Core and Builtins<157>. 
* Library: Library<158>. 
* Documentation: Documentation<47>. 
* Tests: Tests<50>. 
* Build: Build<53>. 
* Windows: Windows<46>. 
* macOS: macOS<38>. 
* IDLE: IDLE<29>. 
* Tools/Demos: Tools/Demos<30>. 
* C API: C API<49>. 

@end menu

@node Security<38>,Core and Builtins<157>,,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id676}@anchor{1f59}
@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<157>,Library<158>,Security<38>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id677}@anchor{1f5a}
@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{d49,,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{d49,,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{839,,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{672,,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{3ea,,SystemError} in
@code{math.@{atan2,copysign,remainder@}()} when the first argument cannot be
converted to a @ref{327,,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{b18,,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{637,,PyUnicode_AsUTF8()} and
@ref{c6f,,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{440,,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<158>,Documentation<47>,Core and Builtins<157>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id678}@anchor{1f5b}
@subsubsection Library



@itemize -

@item 
bpo-39830@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39830}: Add @ref{ab6,,zipfile.Path} to @code{__all__} in the @ref{13a,,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{f66,,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{808,,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{9d5,,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{1f5c,,unittest.mock.AsyncMock.await_args_list} has call
objects in the order of awaited arguments instead of using
@ref{1f5d,,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{4e5,,os.environ} and @ref{4e6,,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{1f5e,,random.Random.seed()} method when a @ref{5ef,,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{98,,multiprocessing} now supports abstract socket addresses
(if abstract sockets are supported in the running platform). When creating
arbitrary addresses (like when default-constructing
@ref{1c2b,,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{1e1,,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{cb6,,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{86,,json.tool} to catch @ref{1404,,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{1d6a,,inspect.getmodule()} when it tried to loop through
@ref{19ba,,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{df,,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{1565,,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{206,,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{ee8,,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{189,,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{7a,,importlib} module now ignores the
@geindex PYTHONCASEOK
@geindex μεταβλητή περιβάλλοντος; PYTHONCASEOK
@ref{d26,,PYTHONCASEOK} environment variable when the @ref{d27,,-E} or
@ref{d28,,-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{1f5f,,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{cd0,,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{1f60,,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{83,,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{9,,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<47>,Tests<50>,Library<158>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id679}@anchor{1f61}
@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{103,,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{3b,,dis}
@end itemize

@node Tests<50>,Build<53>,Documentation<47>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id680}@anchor{1f62}
@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{194,,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<53>,Windows<46>,Tests<50>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id681}@anchor{1f63}
@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{df,,subprocess} module if the @code{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{2a9,,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<46>,macOS<38>,Build<53>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id682}@anchor{1f64}
@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{f6,,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<38>,IDLE<29>,Windows<46>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id683}@anchor{1f65}
@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<29>,Tools/Demos<30>,macOS<38>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id684}@anchor{1f66}
@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<30>,C API<49>,IDLE<29>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id685}@anchor{1f67}
@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<49>,,Tools/Demos<30>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id686}@anchor{1f68}
@subsubsection C API



@itemize -

@item 
bpo-40024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40024}: Add @ref{d3d,,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{b6d,,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{d3a,,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{83b,,PyInterpreterState_Get()} function to the limited C
API.

@item 
bpo-35370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35370}: If @ref{808,,PySys_Audit()} fails in @ref{189f,,PyEval_SetProfile()}
or @ref{850,,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{1f69,,PyDescr_NewMethod()} and @ref{1f6a,,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{f73,,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{1d70,,PyNumber_ToBase()} now raises a @ref{3ea,,SystemError}
instead of crashing when called with invalid base.

@item 
bpo-39882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39882}: The @ref{d4b,,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{d42,,m_traverse},
@ref{d43,,m_clear} and @ref{d44,,m_free}
functions of @ref{d45,,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{d46,,Py_mod_exec} function). More precisely, these functions are not
called if @ref{d47,,m_size} is greater than 0 and the module
state (as returned by @ref{d48,,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{1f6b,,_PyInterpreterState_GetEvalFrameFunc()} and
@ref{1f6c,,_PyInterpreterState_SetEvalFrameFunc()} C functions. The
@ref{b58,,_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{1f6d}
@subsection Python 3.9.0 alpha 4


`Release date: 2020-02-25'

@menu
* Security: Security<39>. 
* Core and Builtins: Core and Builtins<158>. 
* Library: Library<159>. 
* Documentation: Documentation<48>. 
* Tests: Tests<51>. 
* Build: Build<54>. 
* Windows: Windows<47>. 
* IDLE: IDLE<30>. 
* C API: C API<50>. 

@end menu

@node Security<39>,Core and Builtins<158>,,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id687}@anchor{1f6e}
@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<158>,Library<159>,Security<39>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id688}@anchor{1f6f}
@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{19bb,,Py_IS_TYPE()}. Patch by
Donghee Na.

@item 
bpo-39619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39619}: Enable use of @ref{1f70,,os.chroot()} on HP-UX systems.

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: Add @ref{19bb,,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{189b,,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{d10,,floor division} of float operation now has a better
performance. Also the message of @ref{d11,,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{188,,dict} (and @ref{192d,,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<159>,Documentation<48>,Core and Builtins<158>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id689}@anchor{1f71}
@subsubsection Library



@itemize -

@item 
bpo-30566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30566}: Fix @ref{18d7,,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{cdf,,math.gcd()} and @ref{ce0,,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{19c9,,io.UnsupportedOperation} in
@code{io.BufferedReader.truncate()} when it is called on a read-only
@ref{15b5,,io.BufferedReader} instance.

@item 
bpo-39479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39479}: Add @ref{ce0,,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{bd,,pydoc} and @ref{106,,trace} modules now use the
@ref{e4,,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{1c3,,fractions.Fraction} if the numerator
and/or the denominator is an @ref{326,,int} subclass. The @ref{cdf,,math.gcd()}
function is now used to normalize the `numerator' and `denominator'.
@code{math.gcd()} always return a @code{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{8b9,,os.walk()}, @ref{f18,,os.fwalk()},
@ref{73a,,pathlib.Path.glob()} and @ref{73b,,pathlib.Path.rglob()}.

@item 
bpo-39559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39559}: Remove unused, undocumented argument @code{getters} from
@ref{f66,,uuid.getnode()}

@item 
bpo-38149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38149}: @ref{1b36,,sys.audit()} is now called only once per call of
@ref{2d4,,glob.glob()} and @ref{be1,,glob.iglob()}.

@item 
bpo-39546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39546}: Fix a regression in @ref{1dc,,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{b1b,,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{d09,,typing.Annotated} and @code{include_extras} parameter
to @ref{a9e,,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{1b4e,,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{e7,,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{cbe,,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{1240,,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<48>,Tests<51>,Library<159>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id690}@anchor{1f72}
@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<51>,Build<54>,Documentation<48>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id691}@anchor{1f73}
@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{189b,,time.localtime()} fails with @ref{c57,,OverflowError}. It is the case on
AIX 6.1 for example.
@end itemize

@node Build<54>,Windows<47>,Tests<51>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id692}@anchor{1f74}
@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<47>,IDLE<30>,Build<54>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id693}@anchor{1f75}
@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{11f4,,home()} and @ref{11f3,,expanduser()}
on Windows now prefer 
@geindex USERPROFILE
@geindex μεταβλητή περιβάλλοντος; USERPROFILE
@code{USERPROFILE} and no longer use
@geindex HOME
@geindex μεταβλητή περιβάλλοντος; HOME
@code{HOME}, which is not normally set for regular user accounts. This
makes them again behave like @ref{dd8,,os.path.expanduser()}, which was changed
to ignore 
@geindex HOME
@geindex μεταβλητή περιβάλλοντος; 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<30>,C API<50>,Windows<47>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id694}@anchor{1f76}
@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{d96,,KeyboardInterrupt} or
shell restart occurs.  Patch by Zackery Spytz.
@end itemize

@node C API<50>,,IDLE<30>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id695}@anchor{1f77}
@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{91,,math} and @ref{19,,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{b62,,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{1f78,,PyUnicode_IsIdentifier()} does not call
@ref{d4b,,Py_FatalError()} anymore if the string is not ready.

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: Add @ref{b60,,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{c7e,,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{1f30,,PyType_HasFeature()}, @ref{1f79,,PyType_Check()} and
@ref{1f7a,,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{e2f,,PyObject_Init()} and @ref{1f34,,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{1b9e,,PyThreadState_Clear()} function now calls the
@code{PyThreadState.on_delete} callback. Previously, that happened in
@ref{1f7b,,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{1f7c}
@subsection Python 3.9.0 alpha 3


`Release date: 2020-01-24'

@menu
* Core and Builtins: Core and Builtins<159>. 
* Library: Library<160>. 
* Documentation: Documentation<49>. 
* Build: Build<55>. 
* IDLE: IDLE<31>. 
* C API: C API<51>. 

@end menu

@node Core and Builtins<159>,Library<160>,,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id696}@anchor{1f7d}
@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{6c,,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{62,,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{ccd,,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{12b9,,min()} or
@ref{12ba,,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{d0f,,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{1f7e,,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{1f7f,,-u} command-line option or setting the
@geindex PYTHONUNBUFFERED
@geindex μεταβλητή περιβάλλοντος; PYTHONUNBUFFERED
@ref{1f80,,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{1f7e,,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<160>,Documentation<49>,Core and Builtins<159>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id697}@anchor{1f81}
@subsubsection Library



@itemize -

@item 
bpo-39430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39430}: Fixed race condition in lazy imports in @ref{e7,,tarfile}.

@item 
bpo-39413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39413}: The @ref{4e8,,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{ded,,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{4e7,,os.putenv()} and @ref{4e8,,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{4e7,,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{1dd4,,tarfile.is_tarfile()} to be used with file and
file-like objects, like @ref{16cf,,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{22f,,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{6a,,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{c3d,,bz2.BZ2File}. Since
Python 3.0, it was ignored and using it was emitting
@ref{2c9,,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{11,,binascii} functions:
@code{b2a_hqx()}, @code{a2b_hqx()},
@code{rlecode_hqx()}, @code{rledecode_hqx()},
@ref{b1b,,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{d1e,,base64.encodebytes()} and
@ref{d1f,,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{cdf,,math.gcd()} instead.

@item 
bpo-39329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39329}: @ref{cfc,,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{ccb,,FTP_TLS} and @code{FTP_TLS} now raise
a @ref{277,,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{cfa,,SMTP} and @ref{cfb,,SMTP_SSL} now raise
a @ref{277,,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{ce1,,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{277,,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{8a9,,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{cf0,,POP3} and @ref{cf1,,POP3_SSL} now raise a
@ref{277,,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{75,,http.server} module is imported.

@item 
bpo-39239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39239}: The @ref{d24,,select.epoll.unregister()} method no longer ignores
the @ref{d25,,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{1ec,,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{a82,,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{100f,,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{31a,,IMAP4} and @ref{cd3,,IMAP4_SSL} now
have an optional `timeout' parameter for their constructors. Also, the
@ref{cd4,,open()} method now has an optional `timeout' parameter
with this change. The overridden methods of @code{IMAP4_SSL}
and @ref{cd5,,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{1781,,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{e52,,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{94b,,syslog.openlog()} was called without arguments.

@item 
bpo-38293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38293}: Add @ref{942,,copy.copy()} and @ref{f2b,,copy.deepcopy()} support to
@ref{6bb,,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<49>,Build<55>,Library<160>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id698}@anchor{1f82}
@subsubsection Documentation



@itemize -

@item 
bpo-39381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39381}: Mention in docs that @ref{56c,,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{81,,inspect} docs” @ref{1f83,,Types and members} table.

@item 
bpo-3530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3530}: In the @ref{9,,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<55>,IDLE<31>,Documentation<49>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id699}@anchor{1f84}
@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<31>,C API<51>,Build<55>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id700}@anchor{1f85}
@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<51>,,IDLE<31>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id701}@anchor{1f86}
@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{1f87}
@subsection Python 3.9.0 alpha 2


`Release date: 2019-12-18'

@menu
* Security: Security<40>. 
* Core and Builtins: Core and Builtins<160>. 
* Library: Library<161>. 
* Documentation: Documentation<50>. 
* Tests: Tests<52>. 
* Build: Build<56>. 
* Windows: Windows<48>. 
* macOS: macOS<39>. 
* IDLE: IDLE<32>. 
* C API: C API<52>. 

@end menu

@node Security<40>,Core and Builtins<160>,,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id702}@anchor{1f88}
@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{b1a,,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{73,,http.cookiejar}. Patch by
Ben Caller.
@end itemize

@node Core and Builtins<160>,Library<161>,Security<40>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id703}@anchor{1f89}
@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{808,,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{be5,,sys.excepthook()} and
@ref{70c,,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{4d9,,list} and
@ref{42b,,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{4de,,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<161>,Documentation<50>,Core and Builtins<160>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id704}@anchor{1f8a}
@subsubsection Library



@itemize -

@item 
bpo-39033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39033}: Fix @ref{665,,NameError} in @ref{13b,,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{6c5,,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{1400,,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{c2,,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{75,,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{a9e,,typing.get_type_hints()} properly handles functions
decorated with @ref{1307,,functools.wraps()}.

@item 
bpo-38870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38870}: Expose @ref{cb6,,ast.unparse()} as a function of the @ref{9,,ast}
module that can be used to unparse an @ref{2ec,,ast.AST} object and produce
a string with code that would produce an equivalent @code{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{290,,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{7,,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{1361,,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{a8,,pathlib} when
@ref{149b,,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{1f5f,,urllib.request.AbstractDigestAuthHandler}.

@item 
bpo-38712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38712}: Add the Linux-specific @ref{cf8,,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{59,,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{3d,,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<50>,Tests<52>,Library<161>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id705}@anchor{1f8b}
@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{2d2,,datetime.datetime.strptime()} accepts for @code{%Z}. Patch by Karl
Dubost.
@end itemize

@node Tests<52>,Build<56>,Documentation<50>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id706}@anchor{1f8c}
@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{ed,,test.support} constants: @ref{1f8d,,LOOPBACK_TIMEOUT},
@ref{1f8e,,INTERNET_TIMEOUT},
@ref{1e5a,,SHORT_TIMEOUT} and
@ref{1f8f,,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{1777,,math.fsum()} that was failing due to
constant folding.

@item 
bpo-38991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38991}: @ref{ed,,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{10f9,,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{291,,TypeError} when passing target as a string with
@ref{1b25,,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<56>,Windows<48>,Tests<52>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id707}@anchor{1f90}
@subsubsection Build



@itemize -

@item 
bpo-37404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37404}: @ref{b,,asyncio} now raises @ref{291,,TypeError} when calling
incompatible methods with an @ref{cbb,,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<48>,macOS<39>,Build<56>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id708}@anchor{1f91}
@subsubsection Windows



@itemize -

@item 
bpo-39007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39007}: Add auditing events to functions in @ref{11f,,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<39>,IDLE<32>,Windows<48>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id709}@anchor{1f92}
@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<32>,C API<52>,macOS<39>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id710}@anchor{1f93}
@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<52>,,IDLE<32>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id711}@anchor{1f94}
@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{1f95}
@subsection Python 3.9.0 alpha 1


`Release date: 2019-11-19'

@menu
* Security: Security<41>. 
* Core and Builtins: Core and Builtins<161>. 
* Library: Library<162>. 
* Documentation: Documentation<51>. 
* Tests: Tests<53>. 
* Build: Build<57>. 
* Windows: Windows<49>. 
* macOS: macOS<40>. 
* IDLE: IDLE<33>. 
* Tools/Demos: Tools/Demos<31>. 
* C API: C API<53>. 

@end menu

@node Security<41>,Core and Builtins<161>,,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id712}@anchor{1f96}
@subsubsection Security



@itemize -

@item 
bpo-38722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38722}: @ref{c6,,runpy} now uses @ref{1943,,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{2d,,ctypes} module.

@item 
bpo-38418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38418}: Fixes audit event for @ref{17ff,,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{1f97,,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{1f98,,Command line and environment}).

@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{58,,ensurepip}, @ref{61,,ftplib},
@ref{67,,glob}, @ref{77,,imaplib}, @code{nntplib}, @ref{aa,,pdb}, @ref{b1,,poplib},
@ref{cd,,shutil}, @ref{d2,,smtplib}, @ref{d7,,sqlite3}, @ref{df,,subprocess},
@code{telnetlib}, @ref{e9,,tempfile} and @ref{11e,,webbrowser}, as well as
@ref{14a6,,os.listdir()}, @ref{e23,,os.scandir()} and @ref{4f9,,breakpoint()}.

@item 
bpo-37364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37364}: @ref{1943,,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<161>,Library<162>,Security<41>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id713}@anchor{1f99}
@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{30d,,RuntimeError} exception in @code{float.__getformat__()}.

@item 
bpo-38639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38639}: Optimized @ref{1760,,math.floor()}, @ref{1761,,math.ceil()} and
@ref{1762,,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{1c7,,bytes} and @ref{1c6,,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{1c6,,bytearray}, @ref{6c5,,array} and
@ref{23c,,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{18a6,,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{188,,dict} constructor and the
@ref{1807,,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{309,,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{e0b,,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{d2d,,codecs.lookup()} to normalize the encoding name the
same way than @ref{313,,encodings.normalize_encoding()}, except that
@code{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{428,,break} and @ref{429,,continue}
in the @ref{44c,,finally} block when the corresponding @ref{ad6,,try}
block contains @ref{44b,,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{1eea,,sq_item} of @ref{1c6,,bytearray}. Patch by
Sergey Fedoseev.

@item 
bpo-37802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37802}: Slightly improve performance of
@ref{1ade,,PyLong_FromUnsignedLong()}, @ref{1adf,,PyLong_FromUnsignedLongLong()}
and @ref{1ae0,,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{44a,,SyntaxWarning} instead
of @ref{2c9,,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{17e,,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{114f,,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{d31,,assert} statement now works properly if the
@ref{a97,,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{1415,,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{be5,,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}: @ref{198b,,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{d15,,sys.getswitchinterval()} and @ref{d16,,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{32b,,open()}, @ref{ca7,,str.encode()} and @ref{ca8,,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{32b,,open()}, @ref{92b,,io.open()}, @ref{32c,,codecs.open()} and
@ref{b1e,,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{808,,PySys_Audit()} call in @ref{23c,,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{b3c,,PyBuffer_SizeFromFormat()} function
(previously documented but not implemented): call @ref{1f9a,,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{e01,,threading.get_native_id()} now also supports NetBSD.

@item 
bpo-37077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37077}: Add @ref{e01,,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{881,,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{69a,,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<162>,Documentation<51>,Core and Builtins<161>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id714}@anchor{1f9b}
@subsubsection Library



@itemize -

@item 
bpo-36589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36589}: The @ref{11a3,,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{291,,TypeError} messages for @ref{1a42,,os.path.join()} to
include @ref{100f,,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{aa,,pdb} now uses @ref{1943,,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{32b,,open()}.

@item 
bpo-38438@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38438}: Simplify the @ref{7,,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{ce9,,os.P_PIDFD} constant, which may be passed to
@ref{1152,,os.waitid()} to wait on a Linux process file descriptor.

@item 
bpo-38692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38692}: Add @code{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{267,,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{5c,,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{cc0,,curses.get_escdelay()}, @ref{cc1,,curses.set_escdelay()},
@ref{cc2,,curses.get_tabsize()}, and @ref{cc3,,curses.set_tabsize()} functions - by
Anthony Sottile.

@item 
bpo-38586@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38586}: Now @ref{f0e,,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{ce7,,CLD_KILLED} and @ref{ce8,,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{ed3,,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{71b,,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 @ref{1dae,,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{1364,,stat.S_IFDOOR}, @ref{1365,,stat.S_IFPORT},
@ref{1366,,stat.S_IFWHT}, @ref{1f9c,,stat.S_ISDOOR()}, @ref{1f9d,,stat.S_ISPORT()}, and
@ref{1f9e,,stat.S_ISWHT()} values to the Python implementation of @ref{d9,,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{2e4,,typing.NamedTuple} are now
pickleable.

@item 
bpo-38332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38332}: Prevent @ref{7df,,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{1f9f,,smtplib.SMTPNotSupportedError} to the @ref{d2,,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{849,,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{f1c,,os.pread()} to accept
@ref{e24,,Py_ssize_t} instead of int.

@item 
bpo-38112@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38112}: @ref{21,,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{2e4,,NamedTuple} and
@ref{290,,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{33,,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{1222,,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{10b4,,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{1222,,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{b,,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{1f,,collections.abc} module

@item 
bpo-34037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34037}: For @ref{b,,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{309,,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{79f,,path-like object} as @code{directory}
argument to the @ref{22a,,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{ce,,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{9,,ast} module.

@item 
bpo-37953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37953}: In @ref{10d,,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{8a5,,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{1070,,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{1e1,,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{5c,,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{1e1,,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{e32,,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{5b,,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{1913,,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{3a,,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{7,,argparse}.

@item 
bpo-34488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34488}: @code{writelines()} method of @ref{1255,,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{f71,,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{3e,,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{d4,,socket}.

@item 
bpo-37685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37685}: Fixed comparisons of @ref{d94,,datetime.timedelta} and
@ref{146c,,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{1445,,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{1fa0,,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{440,,NotImplemented} for unsupported type of
the other operand. This allows the other operand to play role (for example
the equality comparison with @ref{1fa1,,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{146c,,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{b2,,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{59,,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{440,,NotImplemented} in Python implementation of
@code{__eq__} for @ref{d94,,timedelta} and @ref{48e,,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{1fa2,,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{14ba,,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{e51,,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{be,,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{b3,,pprint} now has support for
@ref{6ea,,types.SimpleNamespace}. Patch by Carl Bordum Hansen.

@item 
bpo-26967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26967}: An @ref{1dc,,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{1fa3,,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{3e2,,sqlite3.Connection.create_aggregate()},
@ref{3e1,,sqlite3.Connection.create_function()},
@ref{3e3,,sqlite3.Connection.set_authorizer()},
@ref{3e4,,sqlite3.Connection.set_progress_handler()}
@ref{3e5,,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{1c70,,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{d13,,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{1fa4,,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{ab,,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{8d,,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{1a9,,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{30d,,RuntimeError} raised by
@ref{d20,,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{f45,,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{9d6,,collections.deque} in
@ref{e35,,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{d00,,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{1fa5,,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{45b,,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{1fa6,,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{1f,,collections.abc} no longer
are exposed in the regular @ref{1e,,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{1fd,,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{cec,,readlink()}. Patch by Girts Folkmanis.

@item 
bpo-32498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32498}: Made @ref{1cfa,,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{e20,,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<51>,Tests<53>,Library<162>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id715}@anchor{1fa7}
@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{3e,,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{30d,,RuntimeError} is raised if
@ref{6bd,,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{801,,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{55c,,sys.settrace()} docs.

@item 
bpo-37878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37878}: Make @ref{1fa8,,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{114,,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{84b,,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{2d2,,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{33,,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{79f,,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<53>,Build<57>,Documentation<51>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id716}@anchor{1fa9}
@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{ed,,test.support}:
@ref{1f8d,,LOOPBACK_TIMEOUT},
@ref{1f8e,,INTERNET_TIMEOUT},
@ref{1e5a,,SHORT_TIMEOUT} and
@ref{1f8f,,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{1faa,,os.setsid()} and @ref{1fab,,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{33,,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{420,,threading.Thread} exception using
@ref{c23,,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{1fac,,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{1fad,,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{70c,,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{1fae,,unittest.skip()} is
uncalled. Patch by Naitree Zhu.
@end itemize

@node Build<57>,Windows<49>,Tests<53>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id717}@anchor{1faf}
@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{1df,,str} and by the
@ref{10e,,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{1fb0,,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<49>,macOS<40>,Build<57>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id718}@anchor{1fb1}
@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{6e1,,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{241,,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{4f5,,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{ced,,os.readlink()} (or
indirectly through @ref{241,,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{1fb2,,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{dd2,,exists()} and a valid result from @ref{4f5,,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{8b1,,os.lstat()} and other reparse points as regular files in
@ref{4f5,,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{1bd,,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 μεταβλητή περιβάλλοντος; 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{3ac,,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{1fb2,,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{1fb3,,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<40>,IDLE<33>,Windows<49>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id719}@anchor{1fb4}
@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<33>,Tools/Demos<31>,macOS<40>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id720}@anchor{1fb5}
@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<31>,C API<53>,IDLE<33>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id721}@anchor{1fb6}
@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{1fb7,,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<53>,,Tools/Demos<31>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id722}@anchor{1fb8}
@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{5fe,,Py_EnterRecursiveCall()} and
@ref{d3c,,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{d4a,,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{1a6b,,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{e15,,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{3ac,,sys.executable} to the
program full path (@code{Py_GetProgramFullPath()}) rather than to the
program name (@code{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{f73,,Py_UNREACHABLE()} macro now calls
@ref{d4b,,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{82f,,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{82f,,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{1fb9,,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{34b,,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{82e,,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{1fba,,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{1fbb}
@subsection Python 3.8.0 beta 1


`Release date: 2019-06-04'

@menu
* Security: Security<42>. 
* Core and Builtins: Core and Builtins<162>. 
* Library: Library<163>. 
* Documentation: Documentation<52>. 
* Tests: Tests<54>. 
* Build: Build<58>. 
* Windows: Windows<50>. 
* macOS: macOS<41>. 
* IDLE: IDLE<34>. 
* Tools/Demos: Tools/Demos<32>. 
* C API: C API<54>. 

@end menu

@node Security<42>,Core and Builtins<162>,,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id723}@anchor{1fbc}
@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{114,,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<162>,Library<163>,Security<42>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id724}@anchor{1fbd}
@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{326,,int}, @ref{327,,float} and
@ref{328,,complex} will now use the @ref{43d,,__index__()} special
method, if available and the corresponding method @ref{43c,,__int__()},
@ref{d92,,__float__()} or @ref{9de,,__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{dcd,,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{2e1,,types.CodeType}).

@item 
bpo-37007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37007}: Implement @ref{df1,,socket.if_nameindex()},
@ref{df2,,socket.if_nametoindex()}, and @ref{df3,,socket.if_indextoname()} on
Windows.

@item 
bpo-36829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36829}: @ref{7e8,,PyErr_WriteUnraisable()} now creates a traceback object
if there is no current traceback. Moreover, call
@ref{63d,,PyErr_NormalizeException()} and @ref{1fbe,,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{17e,,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{5ef,,bool}, @ref{326,,int}, @ref{327,,float}, @ref{328,,complex} and few
classes from the standard library. They now inherit @code{__str__()} from
@ref{e4d,,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{a7c,,sys.flags} and @ref{1fbf,,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{a5,,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<163>,Documentation<52>,Core and Builtins<162>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id725}@anchor{1fc0}
@subsubsection Library



@itemize -

@item 
bpo-37128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37128}: Added @ref{abe,,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{e3a,,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{6bc,,_thread.start_new_thread()} now logs uncaught exception
raised by the function using @ref{70c,,sys.unraisablehook()}, rather than
@ref{be5,,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{98,,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{e0d,,unittest.mock.AsyncMock} setup for autospeccing. Document newly
implemented async methods in @ref{1240,,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{1ca,,symtable.symtable()} now accepts the same input types for
source code as the built-in @ref{1c8,,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{c23,,threading.excepthook()} function which handles
uncaught @ref{e00,,threading.Thread.run()} exception. It can be overridden to
control how uncaught @code{threading.Thread.run()} exceptions are handled.

@item 
bpo-36996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36996}: Handle @ref{1243,,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{bb5,,next()} with the mock resulting
from @ref{1390,,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{bd9,,fileinput.input()} and @ref{b1e,,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{1e,,collections} is deprecated, and import should be done from
@ref{1f,,collections.abc}. Still being able to import from @code{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{665,,NameError} in
@code{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{14da,,shutil.copystat()} now ignores @ref{1fc1,,errno.EINVAL} on
@ref{14b3,,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{194a,,asyncio.StreamReader} and @ref{1c76,,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{e3b,,asyncio.create_subprocess_shell()} and
@ref{e3a,,asyncio.create_subprocess_exec()} to use @code{asyncio.Stream}
instead of deprecated @code{StreamReader} and @code{StreamWriter}.
Deprecate @code{asyncio.StreamReader} and @code{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{dc7,,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{d7,,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{70c,,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{44f,,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{4cf,,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{dba,,BadGzipFile} exception to the @ref{6a,,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{de9,,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{1fc2,,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{15a8,,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{1390,,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{abd,,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{15da,,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{153,,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{1fc3,,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{cc,,shlex} module now exposes @ref{deb,,shlex.join()}, the
inverse of @ref{949,,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{6bf,,subprocess.Popen()} on Windows.  The `args' parameter now accepts a
@ref{79f,,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 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{1fc4,,pathlib.Path.unlink} now accepts a `missing_ok'
parameter to avoid a @ref{243,,FileNotFoundError} from being raised. Patch by
Robert Buchholz.

@item 
bpo-32941@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32941}: Allow @ref{23c,,mmap.mmap} objects to access the madvise() system
call (through @ref{dca,,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{1b7a,,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<52>,Tests<54>,Library<163>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id726}@anchor{1fc5}
@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<54>,Build<58>,Documentation<52>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id727}@anchor{1fc6}
@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{1fad,,test.support.catch_unraisable_exception()} rather than
@ref{1fc7,,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{1fad,,test.support.catch_unraisable_exception()}: context
manager catching unraisable exception using @ref{70c,,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{33,,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<58>,Windows<50>,Tests<54>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id728}@anchor{1fc8}
@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<50>,macOS<41>,Build<58>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id729}@anchor{1fc9}
@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{e6a,,Py_DEPRECATED()} macro has been implemented for
MSVC.
@end itemize

@node macOS<41>,IDLE<34>,Windows<50>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id730}@anchor{1fca}
@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<34>,Tools/Demos<32>,macOS<41>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id731}@anchor{1fcb}
@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<32>,C API<54>,IDLE<34>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id732}@anchor{1fcc}
@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<54>,,Tools/Demos<32>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id733}@anchor{1fcd}
@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{1fce,,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{643,,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{1fcf}
@subsection Python 3.8.0 alpha 4


`Release date: 2019-05-06'

@menu
* Security: Security<43>. 
* Core and Builtins: Core and Builtins<163>. 
* Library: Library<164>. 
* Documentation: Documentation<53>. 
* Tests: Tests<55>. 
* Build: Build<59>. 
* Windows: Windows<51>. 
* macOS: macOS<42>. 
* IDLE: IDLE<35>. 
* Tools/Demos: Tools/Demos<33>. 
* C API: C API<55>. 

@end menu

@node Security<43>,Core and Builtins<163>,,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id734}@anchor{1fd0}
@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{8c4,,shutil.which()} now uses @code{os.confstr("CS_PATH")} if
available and if the 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} environment variable is not set.
Remove also the current directory from @code{posixpath.defpath}. On Unix,
@code{shutil.which()} and the @ref{df,,subprocess} module no longer search the
executable in the current directory if the 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} environment
variable is not set.
@end itemize

@node Core and Builtins<163>,Library<164>,Security<43>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id735}@anchor{1fd1}
@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{108,,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{518,,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{839,,PyEval_RestoreThread()}, @ref{e4e,,Py_END_ALLOW_THREADS()}, and
@ref{1a5,,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{1628,,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{87,,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{18a6,,PyObject_GC_Track()} calls in the
@ref{ab,,pickle} module. Patch by Zackery Spytz.
@end itemize

@node Library<164>,Documentation<53>,Core and Builtins<163>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id736}@anchor{1fd2}
@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{b1e,,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{3ac,,sys.executable} is
@code{None} or an empty string: use @ref{1b26,,os.getcwd()} to initialize
@code{project_base}.  Fix also the distutils build command: don’t use
@code{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{8c4,,shutil.which()} and @code{distutils.spawn.find_executable}
now use @code{os.confstr("CS_PATH")} if available instead of
@ref{1fd3,,os.defpath}, if the @code{PATH} environment variable is not set.
Moreover, don’t use @code{os.confstr("CS_PATH")} nor @code{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{b,,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{178,,-X} @code{dev}) and in debug build,
the @ref{70a,,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{1591,,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{72,,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{1243,,unittest.mock.patch()} object will now return @code{None} instead of
raising @ref{30d,,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{db0,,datetime.date.fromisocalendar()} and
@ref{db1,,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{95,,modulefinder} no longer depends on the deprecated
@ref{79,,imp} module, and the initializer for
@ref{1fd4,,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{95,,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{95,,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{def,,create_server()} and
@ref{df0,,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{69a,,classmethod()} and @ref{666,,staticmethod()} to
@ref{1b4e,,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{e0e,,unittest.mock.Mock}.

@item 
bpo-34547@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34547}: @ref{1fc2,,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{1fd5,,xml.sax.parse()} now supports @ref{79f,,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<53>,Tests<55>,Library<164>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id737}@anchor{1fd6}
@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{121,,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{121,,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<55>,Build<59>,Documentation<53>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id738}@anchor{1fd7}
@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{1fd8,,errno.ENETUNREACH} error.

@item 
bpo-36611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36611}: Fix @code{test_sys.test_getallocatedblocks()} when
@ref{108,,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<59>,Windows<51>,Tests<55>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id739}@anchor{1fd9}
@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{516,,sys.getobjects()} function
and the 
@geindex PYTHONDUMPREFS
@geindex μεταβλητή περιβάλλοντος; PYTHONDUMPREFS
@ref{d6f,,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<51>,macOS<42>,Build<59>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id740}@anchor{1fda}
@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{dae,,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<42>,IDLE<35>,Windows<51>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id741}@anchor{1fdb}
@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<35>,Tools/Demos<33>,macOS<42>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id742}@anchor{1fdc}
@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<33>,C API<55>,IDLE<35>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id743}@anchor{1fdd}
@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<55>,,Tools/Demos<33>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id744}@anchor{1fde}
@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}: @ref{1fdf,,PyDoc_VAR}(name) and @ref{1f4f,,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{1028,,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{f85,,Py_DecodeLocale()} before
@ref{673,,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{1fe0,,PyDate_FromTimestamp()} function were incorrectly
interpreted as a single timestamp rather than an arguments tuple, which
causes existing code to start raising @ref{291,,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{1fe1}
@subsection Python 3.8.0 alpha 3


`Release date: 2019-03-25'

@menu
* Security: Security<44>. 
* Core and Builtins: Core and Builtins<164>. 
* Library: Library<165>. 
* Documentation: Documentation<54>. 
* Tests: Tests<56>. 
* Build: Build<60>. 
* Windows: Windows<52>. 
* IDLE: IDLE<36>. 
* Tools/Demos: Tools/Demos<34>. 
* C API: C API<56>. 

@end menu

@node Security<44>,Core and Builtins<164>,,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id745}@anchor{1fe2}
@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{1fe3,,http.cookiejar.DefaultCookiePolicy} policy. Patch
by Karthikeyan Singaravelan.
@end itemize

@node Core and Builtins<164>,Library<165>,Security<44>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id746}@anchor{1fe4}
@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{194,,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{1c8,,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{10ca,,pickle.load()}, @ref{1fe5,,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{43d,,__index__()} special method will be used
instead of @ref{43c,,__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<165>,Documentation<54>,Core and Builtins<164>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id747}@anchor{1fe6}
@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{b,,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{e7,,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{8a,,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{aa,,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{23c,,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{1fe7,,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{79f,,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{148b,,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{1b4e,,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<54>,Tests<56>,Library<165>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id748}@anchor{1fe8}
@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<56>,Build<60>,Documentation<54>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id749}@anchor{1fe9}
@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<60>,Windows<52>,Tests<56>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id750}@anchor{1fea}
@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<52>,IDLE<36>,Build<60>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id751}@anchor{1feb}
@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<36>,Tools/Demos<34>,Windows<52>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id752}@anchor{1fec}
@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<34>,C API<56>,IDLE<36>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id753}@anchor{1fed}
@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<56>,,Tools/Demos<34>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id754}@anchor{1fee}
@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{1fef}
@subsection Python 3.8.0 alpha 2


`Release date: 2019-02-25'

@menu
* Core and Builtins: Core and Builtins<165>. 
* Library: Library<166>. 
* Documentation: Documentation<55>. 
* Tests: Tests<57>. 
* Windows: Windows<53>. 
* IDLE: IDLE<37>. 

@end menu

@node Core and Builtins<165>,Library<166>,,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id755}@anchor{1ff0}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-36052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36052}: Raise a @ref{17e,,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{100f,,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{f8d,,list.sort()} when sorting objects
with @code{ob_type->tp_richcompare == NULL}.  Patch by Zackery Spytz.
@end itemize

@node Library<166>,Documentation<55>,Core and Builtins<165>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id756}@anchor{1ff1}
@subsubsection Library



@itemize -

@item 
bpo-35512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35512}: @ref{1b7a,,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{8c4,,shutil.which()}.

@item 
bpo-35960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35960}: Fix @ref{1945,,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{1ff2,,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{aa,,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{15d3,,re.search()}, @ref{13d2,,re.findall()}, @ref{7a1,,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{11d,,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{dc6,,math.prod()} as analogous function to
@ref{881,,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{6e7,,datetime.datetime}
subclasses and @ref{d94,,datetime.timedelta} now returns an object of the
same type as the @code{datetime.datetime} subclass. As a result,
@ref{d95,,datetime.datetime.astimezone()} and alternate constructors like
@ref{8fa,,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{e1b,,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<55>,Tests<57>,Library<166>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id757}@anchor{1ff3}
@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<57>,Windows<53>,Documentation<55>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id758}@anchor{1ff4}
@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<53>,IDLE<37>,Tests<57>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id759}@anchor{1ff5}
@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<37>,,Windows<53>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id760}@anchor{1ff6}
@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{1ff7}
@subsection Python 3.8.0 alpha 1


`Release date: 2019-02-03'

@menu
* Security: Security<45>. 
* Core and Builtins: Core and Builtins<166>. 
* Library: Library<167>. 
* Documentation: Documentation<56>. 
* Tests: Tests<58>. 
* Build: Build<61>. 
* Windows: Windows<54>. 
* macOS: macOS<43>. 
* IDLE: IDLE<38>. 
* Tools/Demos: Tools/Demos<35>. 
* C API: C API<57>. 

@end menu

@node Security<45>,Core and Builtins<166>,,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id761}@anchor{1ff8}
@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{d28,,-I} command line option (run Python in isolated
mode) is now also copied by the @ref{98,,multiprocessing} and @code{distutils}
modules when spawning child processes. Previously, only @ref{d27,,-E} and
@ref{1732,,-s} options (enabled by @code{-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{ed3,,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<166>,Library<167>,Security<45>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id762}@anchor{1ff9}
@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{439,,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{81e,,PyUnicode_FromFormat()} and @code{%s} in @ref{1ffa,,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{3ea,,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{a12,,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{13b,,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{a5,,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{d4,,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{277,,ValueError} instead of @ref{c57,,OverflowError} in case
of a negative @code{_length_} in a @ref{1ffb,,ctypes.Array} subclass.  Also
raise @ref{291,,TypeError} instead of @ref{1a9,,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{44a,,SyntaxWarning} raised as an exception at code generation
time will be now replaced with a @ref{17e,,SyntaxError} for better error
reporting.

@item 
bpo-34983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34983}: Expose @ref{1ffc,,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{1c7,,bytes} and @ref{1c6,,bytearray} constructors no longer
convert unexpected exceptions (e.g. @ref{18fa,,MemoryError} and
@ref{d96,,KeyboardInterrupt}) to @ref{291,,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{1c7,,bytes()} when the @ref{4d9,,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{44a,,SyntaxWarning} is now emitted instead of a
@ref{2c9,,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{44a,,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{516,,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{32b,,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{1a9,,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{70b,,io.IOBase.close()}, ensure that the
@ref{1ffd,,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{1ec0,,PyRun_SimpleFileExFlags()}
before calling @ref{1f21,,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{1ea8,,PyIter_Check()}, @ref{d52,,PyIndex_Check()} and
@ref{e2a,,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{156a,,gc.garbage} list. @ref{d56,,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{30d,,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{2c9,,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 μεταβλητή περιβάλλοντος; PYTHONPYCACHEPREFIX
@ref{d6c,,PYTHONPYCACHEPREFIX} environment variable and
@ref{178,,-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{13b,,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 shrunk only when
@code{used == 0}. Now dict has more chance to be shrunk.

@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{e6f,,END_ASYNC_FOR} and fixes the
following issues:


@itemize *

@item 
Setting global @ref{1ffe,,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{429,,continue} statement is now allowed in the
@ref{44c,,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{428,,break}, @ref{429,,continue} and
@ref{44b,,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<167>,Documentation<56>,Core and Builtins<166>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id763}@anchor{1fff}
@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{731,,os.posix_spawn()} and @ref{1949,,os.posix_spawnp()} now have a
`setsid' parameter.

@item 
bpo-23846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23846}: @ref{9fe,,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{b,,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{1949,,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{91,,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{e06,,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{ca9,,help()} and
@ref{bd,,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{d6a,,divmod()}
function on @ref{1c3,,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{df,,subprocess} module can now use the
@ref{731,,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{2d,,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{f67,,uuid.uuid1()} now calls @ref{eae,,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{e49,,time.perf_counter()} rather than
@ref{75e,,time.time()} to measure the execution time of a test:
@code{time.time()} can go backwards, whereas @code{time.perf_counter()} is
monotonic.

@item 
bpo-35502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35502}: Fixed reference leaks in
@ref{e19,,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{1c0e,,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{98,,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{e0e,,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{81,,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{74f,,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{af,,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{7df,,KeyError} on calling @ref{2000,,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{cf,,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{1a01,,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{1159,,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.
@code{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{2001,,platform.uname()} now redirects @code{stderr} to
@ref{2002,,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{585,,os.popen()} instead.

@item 
bpo-35344@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35344}: On macOS, @ref{1cc7,,platform.platform()} now uses
@ref{2003,,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{fbd,,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{1fa3,,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{1947,,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{66,,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{14eb,,socketserver.BaseServer.serve_forever()} now exits
immediately if it’s @ref{2004,,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{1240,,unittest.mock.MagicMock} now supports the
@code{__fspath__} method (from @ref{100f,,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{343,,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{302,,inspect.iscoroutinefunction()},
@ref{1d59,,inspect.isgeneratorfunction()} and @ref{1d5a,,inspect.isasyncgenfunction()}
work with @ref{4a6,,functools.partial()}. Patch by Pablo Galindo.

@item 
bpo-34521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34521}: Use @ref{2005,,socket.CMSG_SPACE()} to calculate ancillary data size
instead of @ref{2006,,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{bd,,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{2007,,mimetypes.MimeTypes.guess_type()} now accepts
@ref{79f,,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{12e,,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{cfa,,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{2008,,digest()} and
@ref{2009,,hexdigest()} methods for the SHAKE algorithm in the
@ref{6b,,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{1e40,,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 μεταβλητή περιβάλλοντος; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} environment variable no longer
overrides the value of the `invalidation_mode' argument to
@ref{de9,,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{200a,,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{13b,,zipimport}.

@item 
bpo-32892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32892}: The parser now represents all constants as
@ref{569,,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{10b6,,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{1592,,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{72b,,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{e0f,,addModuleCleanup()} and
@ref{e10,,addClassCleanup()} to unittest to support cleanups
for @ref{e11,,setUpModule()} and
@ref{e12,,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{df,,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{df,,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{1fd3,,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{277,,ValueError} is now raised by
@ref{200b,,multiprocessing.Queue.put()} and @ref{200c,,multiprocessing.Queue.get()}
instead of @ref{a97,,AssertionError} and @ref{53c,,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{13a,,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{106,,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{2f0,,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{200d,,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{ced,,os.readlink()} now accepts @ref{79f,,path-like} and @ref{1c7,,bytes} objects on Windows.

@item 
bpo-22602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22602}: The UTF-7 decoder now raises @ref{dd7,,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{e5e,,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{1b6a,,pathlib.PurePath.with_suffix()} when
formatting an error message.

@item 
bpo-18540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18540}: The @ref{31a,,imaplib.IMAP4} and @ref{cd3,,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{93b,,assertRaises()},
@ref{93d,,assertRaisesRegex()},
@ref{2a0,,assertWarns()} and
@ref{2a1,,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{787,,__getitem__()} methods of
@ref{b1c,,xml.dom.pulldom.DOMEventStream}, @ref{b1d,,wsgiref.util.FileWrapper}
and @ref{b1e,,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{200e,,dbm.gnu.open()} and @ref{200f,,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{120b,,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{da2,,get_name()} and
@ref{da1,,set_name()}) and is visible in the @ref{45b,,repr()} output.
An initial name can also be set using the new @code{name} keyword argument to
@ref{462,,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{d7,,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{14af,,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{3e2,,sqlite3.Connection.create_aggregate()},
@ref{3e1,,sqlite3.Connection.create_function()},
@ref{3e3,,sqlite3.Connection.set_authorizer()},
@ref{3e4,,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{2c,,csv} reader are now @ref{5ef,,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{291,,TypeError} raised in methods
@code{__adapt__()} and @code{__conform__()} in the @ref{d7,,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{928,,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{1e8,,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{6b,,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{3e1,,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{75d,,time.monotonic()} instead of the system clock @ref{75e,,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{102,,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{f1b,,os.readv()}, @ref{f1e,,os.writev()},
@ref{f1a,,os.preadv()} and @ref{f1d,,os.pwritev()} and in @ref{ed3,,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{942,,copy.copy()} and @ref{f2b,,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{ded,,shutil.copytree()} uses @ref{e23,,os.scandir()} function and
all copy functions depending from it use cached @ref{4f5,,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 @code{os.stat()} syscalls is reduced by 38% making
@code{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{a6,,os.path} functions that return a boolean result like
@ref{dd2,,exists()}, @ref{dd3,,lexists()}, @ref{dd4,,isdir()},
@ref{dd5,,isfile()}, @ref{dd0,,islink()}, and
@ref{dd6,,ismount()}, and @ref{4ee,,pathlib.Path} methods that return a
boolean result like @ref{dda,,exists()},
@ref{73d,,is_dir()}, @ref{73c,,is_file()},
@ref{ddb,,is_mount()}, @ref{ddc,,is_symlink()},
@ref{ddd,,is_block_device()},
@ref{dde,,is_char_device()}, @ref{ddf,,is_fifo()},
@ref{de0,,is_socket()} now return @code{False} instead of raising
@ref{277,,ValueError} or its subclasses @ref{a67,,UnicodeEncodeError} and
@ref{dd7,,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{1a01,,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{291,,TypeError} instead of @ref{3ea,,SystemError} when
performed on @ref{23c,,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{11e,,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{9f6,,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{e1d,,shutil.copyfile()}, @ref{e1e,,shutil.copy()},
@ref{e1f,,shutil.copy2()}, @ref{ded,,shutil.copytree()} and @ref{e20,,shutil.move()} use
platform-specific fast-copy syscalls on Linux and macOS in order to copy
the file more efficiently. On Windows @code{shutil.copyfile()} uses a
bigger default buffer size (1 MiB instead of 16 KiB) and a
@ref{1d2,,memoryview()}-based variant of @ref{e21,,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{f67,,uuid.uuid1()} on FreeBSD.

@item 
bpo-33238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33238}: Add @code{InvalidStateError} to @ref{24,,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{8ea,,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{d5,,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{1240,,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{2010,,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{26,,configparser} from @ref{9d5,,collections.OrderedDict} to the standard
@ref{188,,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{e18,,XMLParser}.  The
@code{doctype()} method defined in a subclass will no longer be called.
Deprecated methods @code{getchildren()} and @code{getiterator()} in the
@ref{12e,,ElementTree} module emit now a @ref{2c9,,DeprecationWarning}
instead of @ref{c9b,,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{72,,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{1390,,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{291,,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{37,,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{12dc,,dis.stack_effect()}.

@item 
bpo-27485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27485}: Rename and deprecate undocumented functions in
@ref{113,,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{2011,,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{12dc,,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{2012,,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{708,,importlib.resources.contents()} and
@code{importlib.abc.ResourceReader.contents()} return an @ref{15ce,,iterable}
instead of an @ref{6ce,,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{4ca,,-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{194,,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{9db,,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{2013,,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{ab,,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{731,,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{83,,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{11c,,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{f9,,tkinter}, @code{after_cancel(None)} now raises a
@ref{277,,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{1a79,,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{35,,dbm.dumb} database opened with flags “r” is now
read-only. @ref{e5c,,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{102,,tkinter.ttk}.  Patch by Alan D
Moore.

@item 
bpo-32512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32512}: @ref{b4,,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{1ff,,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{dab,,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{6e7,,datetime}, @ref{48d,,date} and
@ref{48e,,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{3df,,sqlite3.Connection} now exposes a
@ref{f39,,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{2d,,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<56>,Tests<58>,Library<167>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id764}@anchor{2014}
@subsubsection Documentation



@itemize -

@item 
bpo-21257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21257}: Document @ref{2015,,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{53,,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{edc,,asyncio.open_connection()},
@ref{edd,,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{139,,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{ed,,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{1a9,,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{2c9,,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{d4,,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<58>,Build<61>,Documentation<56>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id765}@anchor{2016}
@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{12,,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{75e,,time.time()} with @ref{75d,,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<61>,Windows<54>,Tests<58>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id766}@anchor{2017}
@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
@ref{2018,,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<54>,macOS<43>,Build<61>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id767}@anchor{2019}
@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{53c,,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{ced,,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<43>,IDLE<38>,Windows<54>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id768}@anchor{201a}
@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<38>,Tools/Demos<35>,macOS<43>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id769}@anchor{201b}
@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 μεταβλητή περιβάλλοντος; IDLESTARTUP
@code{IDLESTARTUP} or
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,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<35>,C API<57>,IDLE<38>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id770}@anchor{201c}
@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<57>,,Tools/Demos<35>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id771}@anchor{201d}
@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{3b3,,_PyBytes_Resize()} for empty bytes objects.

@item 
bpo-35322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35322}: Fix memory leak in @ref{f88,,PyUnicode_EncodeLocale()} and
@ref{201e,,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{974,,Py_INCREF()}, @ref{975,,Py_DECREF()}, @ref{e29,,Py_XINCREF()},
@ref{b6e,,Py_XDECREF()}, @ref{1f32,,PyObject_INIT()},
@ref{1f33,,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{10cf,,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{18fe,,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{3ea,,SystemError} in
@ref{818,,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 @ref{201f,,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{2020,,PySequence_Size()},
@ref{2021,,PySequence_GetItem()}, @ref{2022,,PySequence_SetItem()} and
@ref{2023,,PySequence_DelItem()} called with a mapping and
@ref{2024,,PyMapping_Size()} called with a sequence.

@item 
bpo-33818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33818}: @ref{e2a,,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{2025,,PyUnicode_AsWideChar()} and
@ref{c8f,,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{2026}
@subsection Python 3.7.0 final


`Release date: 2018-06-27'

@menu
* Library: Library<168>. 
* C API: C API<58>. 

@end menu

@node Library<168>,C API<58>,,Python 3 7 0 final
@anchor{whatsnew/changelog id772}@anchor{2027}
@subsubsection Library



@itemize -

@item 
bpo-33851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33851}: Fix @ref{2028,,ast.get_docstring()} for a node that lacks a
docstring.
@end itemize

@node C API<58>,,Library<168>,Python 3 7 0 final
@anchor{whatsnew/changelog id773}@anchor{2029}
@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{202a}
@subsection Python 3.7.0 release candidate 1


`Release date: 2018-06-12'

@menu
* Core and Builtins: Core and Builtins<167>. 
* Library: Library<169>. 
* Documentation: Documentation<57>. 
* Build: Build<62>. 
* Windows: Windows<55>. 
* IDLE: IDLE<39>. 

@end menu

@node Core and Builtins<167>,Library<169>,,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id774}@anchor{202b}
@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<169>,Documentation<57>,Core and Builtins<167>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id775}@anchor{202c}
@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{291,,TypeError} instead of @ref{3ea,,SystemError} when
performed on @ref{23c,,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<57>,Build<62>,Library<169>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id776}@anchor{202d}
@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{edc,,asyncio.open_connection()},
@ref{edd,,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<62>,Windows<55>,Documentation<57>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id777}@anchor{202e}
@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<55>,IDLE<39>,Build<62>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id778}@anchor{202f}
@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<39>,,Windows<55>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id779}@anchor{2030}
@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{2031}
@subsection Python 3.7.0 beta 5


`Release date: 2018-05-30'

@menu
* Core and Builtins: Core and Builtins<168>. 
* Library: Library<170>. 
* Documentation: Documentation<58>. 
* Tests: Tests<59>. 
* Build: Build<63>. 
* macOS: macOS<44>. 
* IDLE: IDLE<40>. 

@end menu

@node Core and Builtins<168>,Library<170>,,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id780}@anchor{2032}
@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{156a,,gc.garbage} list. @ref{d56,,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<170>,Documentation<58>,Core and Builtins<168>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id781}@anchor{2033}
@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{9f6,,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{f67,,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{d5,,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{2d,,ctypes}.  Patch by Segev Finer.
@end itemize

@node Documentation<58>,Tests<59>,Library<170>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id782}@anchor{2034}
@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<59>,Build<63>,Documentation<58>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id783}@anchor{2035}
@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<63>,macOS<44>,Tests<59>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id784}@anchor{2036}
@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<44>,IDLE<40>,Build<63>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id785}@anchor{2037}
@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<40>,,macOS<44>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id786}@anchor{2038}
@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{2039}
@subsection Python 3.7.0 beta 4


`Release date: 2018-05-02'

@menu
* Core and Builtins: Core and Builtins<169>. 
* Library: Library<171>. 
* Documentation: Documentation<59>. 
* Tests: Tests<60>. 
* Build: Build<64>. 
* Windows: Windows<56>. 
* macOS: macOS<45>. 
* IDLE: IDLE<41>. 
* Tools/Demos: Tools/Demos<36>. 

@end menu

@node Core and Builtins<169>,Library<171>,,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id787}@anchor{203a}
@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 shrunk only when
@code{used == 0}. Now dict has more chance to be shrunk.

@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<171>,Documentation<59>,Core and Builtins<169>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id788}@anchor{203b}
@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{37,,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{2012,,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{708,,importlib.resources.contents()} and
@code{importlib.abc.ResourceReader.contents()} return an @ref{15ce,,iterable}
instead of an @ref{6ce,,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{4ca,,-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{194,,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{9db,,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{291,,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{2013,,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{731,,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<59>,Tests<60>,Library<171>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id789}@anchor{203c}
@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<60>,Build<64>,Documentation<59>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id790}@anchor{203d}
@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<64>,Windows<56>,Tests<60>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id791}@anchor{203e}
@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<56>,macOS<45>,Build<64>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id792}@anchor{203f}
@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<45>,IDLE<41>,Windows<56>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id793}@anchor{2040}
@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<41>,Tools/Demos<36>,macOS<45>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id794}@anchor{2041}
@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<36>,,IDLE<41>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id795}@anchor{2042}
@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{2043}
@subsection Python 3.7.0 beta 3


`Release date: 2018-03-29'

@menu
* Security: Security<46>. 
* Core and Builtins: Core and Builtins<170>. 
* Library: Library<172>. 
* Documentation: Documentation<60>. 
* Tests: Tests<61>. 
* Build: Build<65>. 
* Windows: Windows<57>. 
* macOS: macOS<46>. 
* IDLE: IDLE<42>. 
* Tools/Demos: Tools/Demos<37>. 
* C API: C API<59>. 

@end menu

@node Security<46>,Core and Builtins<170>,,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id796}@anchor{2044}
@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<170>,Library<172>,Security<46>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id797}@anchor{2045}
@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<172>,Documentation<60>,Core and Builtins<170>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id798}@anchor{2046}
@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{83,,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{11c,,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{f9,,tkinter}, @code{after_cancel(None)} now raises a
@ref{277,,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{3df,,sqlite3.Connection} now exposes a
@ref{f39,,backup} method, if the underlying SQLite
library is at version 3.6.11 or higher.  Patch by Lele Gaifax.
@end itemize

@node Documentation<60>,Tests<61>,Library<172>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id799}@anchor{2047}
@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{139,,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<61>,Build<65>,Documentation<60>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id800}@anchor{2048}
@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<65>,Windows<57>,Tests<61>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id801}@anchor{2049}
@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<57>,macOS<46>,Build<65>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id802}@anchor{204a}
@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<46>,IDLE<42>,Windows<57>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id803}@anchor{204b}
@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<42>,Tools/Demos<37>,macOS<46>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id804}@anchor{204c}
@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 μεταβλητή περιβάλλοντος; IDLESTARTUP
@code{IDLESTARTUP} or
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,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<37>,C API<59>,IDLE<42>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id805}@anchor{204d}
@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<59>,,Tools/Demos<37>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id806}@anchor{204e}
@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{204f}
@subsection Python 3.7.0 beta 2


`Release date: 2018-02-27'

@menu
* Security: Security<47>. 
* Core and Builtins: Core and Builtins<171>. 
* Library: Library<173>. 
* Documentation: Documentation<61>. 
* Tests: Tests<62>. 
* Build: Build<66>. 
* Windows: Windows<58>. 
* macOS: macOS<47>. 
* IDLE: IDLE<43>. 
* Tools/Demos: Tools/Demos<38>. 

@end menu

@node Security<47>,Core and Builtins<171>,,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id807}@anchor{2050}
@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<171>,Library<173>,Security<47>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id808}@anchor{2051}
@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<173>,Documentation<61>,Core and Builtins<171>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id809}@anchor{2052}
@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{2c9,,DeprecationWarning} when using or importing an ABC
directly from @ref{1e,,collections} rather than from @ref{1f,,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{1a79,,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{102,,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<61>,Tests<62>,Library<173>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id810}@anchor{2053}
@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{ed,,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{1a9,,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{2c9,,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<62>,Build<66>,Documentation<61>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id811}@anchor{2054}
@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<66>,Windows<58>,Tests<62>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id812}@anchor{2055}
@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<58>,macOS<47>,Build<66>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id813}@anchor{2056}
@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{ced,,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<47>,IDLE<43>,Windows<58>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id814}@anchor{2057}
@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<43>,Tools/Demos<38>,macOS<47>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id815}@anchor{2058}
@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<38>,,IDLE<43>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id816}@anchor{2059}
@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{205a}
@subsection Python 3.7.0 beta 1


`Release date: 2018-01-30'

@menu
* Core and Builtins: Core and Builtins<172>. 
* Library: Library<174>. 
* Documentation: Documentation<62>. 
* Tests: Tests<63>. 
* Build: Build<67>. 
* Windows: Windows<59>. 
* macOS: macOS<48>. 
* C API: C API<60>. 

@end menu

@node Core and Builtins<172>,Library<174>,,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id817}@anchor{205b}
@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<174>,Documentation<62>,Core and Builtins<172>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id818}@anchor{205c}
@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{ea,,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{1863,,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{ed0,,asyncio.StreamWriter.wait_closed()} and
@ref{ed1,,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 cancellation 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{8fb,,datetime.datetime.fromtimestamp()} did not
call __new__ in @ref{6e7,,datetime.datetime} subclasses.

@item 
bpo-32403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32403}: Improved speed of @ref{48d,,datetime.date} and
@ref{6e7,,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{7e,,importlib.resources} and
@code{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{fa7,,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{79f,,path-like object}. If `args' is given
as a sequence, it’s first element can now be a path-like object as
well.

@item 
bpo-31900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31900}: The @ref{fbd,,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{a12,,str.format()} method when formatting a number
(@ref{326,,int}, @ref{327,,float}, @code{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<62>,Tests<63>,Library<174>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id819}@anchor{205d}
@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<63>,Build<67>,Documentation<62>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id820}@anchor{205e}
@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<67>,Windows<59>,Tests<63>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id821}@anchor{205f}
@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 μεταβλητή περιβάλλοντος; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} environment variable is set,
@ref{bb,,py_compile} will always create hash-based @code{.pyc} files.
@end itemize

@node Windows<59>,macOS<48>,Build<67>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id822}@anchor{2060}
@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<48>,C API<60>,Windows<59>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id823}@anchor{2061}
@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<60>,,macOS<48>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id824}@anchor{2062}
@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.timezone.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{2063}
@subsection Python 3.7.0 alpha 4


`Release date: 2018-01-08'

@menu
* Core and Builtins: Core and Builtins<173>. 
* Library: Library<175>. 
* Documentation: Documentation<63>. 
* Tests: Tests<64>. 
* Windows: Windows<60>. 
* Tools/Demos: Tools/Demos<39>. 
* C API: C API<61>. 

@end menu

@node Core and Builtins<173>,Library<175>,,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id825}@anchor{2064}
@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{2065,,-R} option now turns on hash randomization when
the 
@geindex PYTHONHASHSEED
@geindex μεταβλητή περιβάλλοντος; PYTHONHASHSEED
@ref{1425,,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<175>,Documentation<63>,Core and Builtins<173>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id826}@anchor{2066}
@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 @code{importlib.abc.ResourceReader} as an ABC for
loaders to provide a unified API for reading resources contained within
packages.  Also add @ref{7e,,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{2a3,,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{7a1,,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 output.
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{a0a,,datetime.datetime.fromisoformat()},
@ref{a09,,datetime.time.fromisoformat()} and
@ref{a08,,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{206,,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<63>,Tests<64>,Library<175>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id827}@anchor{2067}
@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<64>,Windows<60>,Documentation<63>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id828}@anchor{2068}
@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<60>,Tools/Demos<39>,Tests<64>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id829}@anchor{2069}
@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<39>,C API<61>,Windows<60>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id830}@anchor{206a}
@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<61>,,Tools/Demos<39>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id831}@anchor{206b}
@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{206c}
@subsection Python 3.7.0 alpha 3


`Release date: 2017-12-05'

@menu
* Core and Builtins: Core and Builtins<174>. 
* Library: Library<176>. 
* Documentation: Documentation<64>. 
* Tests: Tests<65>. 
* Build: Build<68>. 
* Windows: Windows<61>. 
* macOS: macOS<49>. 
* IDLE: IDLE<44>. 
* Tools/Demos: Tools/Demos<40>. 
* C API: C API<62>. 

@end menu

@node Core and Builtins<174>,Library<176>,,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id832}@anchor{206d}
@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<176>,Documentation<64>,Core and Builtins<174>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id833}@anchor{206e}
@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{206f,,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{fb5,,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{dd8,,os.path.expanduser()} to find the @code{~/.netrc} file in
@ref{1e70,,netrc.netrc}.  If it does not exist, @ref{243,,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{1cf,,collections.namedtuple()} in the
@ref{2070,,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{2c9,,DeprecationWarning}, @ref{c9b,,PendingDeprecationWarning} and
@ref{907,,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{79f,,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{2071,,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{f4d,,time.CLOCK_BOOTTIME},
@ref{f4e,,time.CLOCK_PROF} and @ref{f4f,,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{2072,,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{713,,ipaddress.IPv6Network} and @ref{712,,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{f7,,time} module:
@ref{ea9,,clock_gettime_ns()}, @ref{eaa,,clock_settime_ns()},
@ref{eab,,monotonic_ns()}, @ref{eac,,perf_counter_ns()},
@ref{ead,,process_time_ns()}, @ref{eae,,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{180a,,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{cd0,,http.HTTPStatus}. Patch by Vitor Pereira.
@end itemize

@node Documentation<64>,Tests<65>,Library<176>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id834}@anchor{2073}
@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<65>,Build<68>,Documentation<64>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id835}@anchor{2074}
@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<68>,Windows<61>,Tests<65>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id836}@anchor{2075}
@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<61>,macOS<49>,Build<68>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id837}@anchor{2076}
@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<49>,IDLE<44>,Windows<61>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id838}@anchor{2077}
@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<44>,Tools/Demos<40>,macOS<49>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id839}@anchor{2078}
@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<40>,C API<62>,IDLE<44>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id840}@anchor{2079}
@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<62>,,Tools/Demos<40>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id841}@anchor{207a}
@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{207b}
@subsection Python 3.7.0 alpha 2


`Release date: 2017-10-16'

@menu
* Core and Builtins: Core and Builtins<175>. 
* Library: Library<177>. 
* Documentation: Documentation<65>. 
* Build: Build<69>. 
* IDLE: IDLE<45>. 
* C API: C API<63>. 

@end menu

@node Core and Builtins<175>,Library<177>,,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id842}@anchor{207c}
@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 μεταβλητή περιβάλλοντος; PYTHONPROFILEIMPORTTIME
@ref{ebb,,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<177>,Documentation<65>,Core and Builtins<175>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id843}@anchor{207d}
@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{206,,concurrent.futures.ProcessPoolExecutor} constructor. Also, free
job resources in @code{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<65>,Build<69>,Library<177>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id844}@anchor{207e}
@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<69>,IDLE<45>,Documentation<65>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id845}@anchor{207f}
@subsubsection Build



@itemize -

@item 
bpo-31696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31696}: Improve compiler version information in @ref{6a8,,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<45>,C API<63>,Build<69>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id846}@anchor{2080}
@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<63>,,IDLE<45>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id847}@anchor{2081}
@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{2082}
@subsection Python 3.7.0 alpha 1


`Release date: 2017-09-19'

@menu
* Security: Security<48>. 
* Core and Builtins: Core and Builtins<176>. 
* Library: Library<178>. 
* Documentation: Documentation<66>. 
* Tests: Tests<66>. 
* Build: Build<70>. 
* Windows: Windows<62>. 
* IDLE: IDLE<46>. 
* Tools/Demos: Tools/Demos<41>. 
* C API: C API<64>. 

@end menu

@node Security<48>,Core and Builtins<176>,,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id848}@anchor{2083}
@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<176>,Library<178>,Security<48>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id849}@anchor{2084}
@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 library 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{c57,,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{18a0,,sys.setprofile()} function,
@code{cProfile} or @code{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 split 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<178>,Documentation<66>,Core and Builtins<176>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id850}@anchor{2085}
@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{1df,,str} instead of
@ref{1c7,,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}: Added 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<66>,Tests<66>,Library<178>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id851}@anchor{2086}
@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{1c7,,bytes()} and @ref{1c6,,bytearray()} are
now their respective type definitions, rather than the corresponding
builtin function entries. Use @ref{2087,,bytes} and
@ref{2088,,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<66>,Build<70>,Documentation<66>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id852}@anchor{2089}
@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<70>,Windows<62>,Tests<66>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id853}@anchor{208a}
@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<62>,IDLE<46>,Build<70>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id854}@anchor{208b}
@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<46>,Tools/Demos<41>,Windows<62>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id855}@anchor{208c}
@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(“”) 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<41>,C API<64>,IDLE<46>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id856}@anchor{208d}
@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<64>,,Tools/Demos<41>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id857}@anchor{208e}
@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{208f}
@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{2090}
@subsection Python 3.6.6 release candidate 1


`Release date: 2018-06-11'

@menu
* Core and Builtins: Core and Builtins<177>. 
* Library: Library<179>. 
* Documentation: Documentation<67>. 
* Tests: Tests<67>. 
* Build: Build<71>. 
* Windows: Windows<63>. 
* macOS: macOS<50>. 
* IDLE: IDLE<47>. 
* Tools/Demos: Tools/Demos<42>. 
* C API: C API<65>. 

@end menu

@node Core and Builtins<177>,Library<179>,,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id858}@anchor{2091}
@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{156a,,gc.garbage} list. @ref{d56,,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<179>,Documentation<67>,Core and Builtins<177>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id859}@anchor{2092}
@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{291,,TypeError} instead of @ref{3ea,,SystemError} when
performed on @ref{23c,,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{37,,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{2012,,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{2013,,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{83,,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{2d,,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<67>,Tests<67>,Library<179>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id860}@anchor{2093}
@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{139,,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<67>,Build<71>,Documentation<67>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id861}@anchor{2094}
@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<71>,Windows<63>,Tests<67>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id862}@anchor{2095}
@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<63>,macOS<50>,Build<71>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id863}@anchor{2096}
@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<50>,IDLE<47>,Windows<63>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id864}@anchor{2097}
@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<47>,Tools/Demos<42>,macOS<50>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id865}@anchor{2098}
@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<42>,C API<65>,IDLE<47>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id866}@anchor{2099}
@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<65>,,Tools/Demos<42>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id867}@anchor{209a}
@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{209b}
@subsection Python 3.6.5 final


`Release date: 2018-03-28'

@menu
* Tests: Tests<68>. 
* Build: Build<72>. 

@end menu

@node Tests<68>,Build<72>,,Python 3 6 5 final
@anchor{whatsnew/changelog id868}@anchor{209c}
@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<72>,,Tests<68>,Python 3 6 5 final
@anchor{whatsnew/changelog id869}@anchor{209d}
@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{209e}
@subsection Python 3.6.5 release candidate 1


`Release date: 2018-03-13'

@menu
* Security: Security<49>. 
* Core and Builtins: Core and Builtins<178>. 
* Library: Library<180>. 
* Documentation: Documentation<68>. 
* Tests: Tests<69>. 
* Build: Build<73>. 
* Windows: Windows<64>. 
* macOS: macOS<51>. 
* IDLE: IDLE<48>. 
* Tools/Demos: Tools/Demos<43>. 
* C API: C API<66>. 

@end menu

@node Security<49>,Core and Builtins<178>,,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id870}@anchor{209f}
@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<178>,Library<180>,Security<49>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id871}@anchor{20a0}
@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<180>,Documentation<68>,Core and Builtins<178>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id872}@anchor{20a1}
@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{f9,,tkinter}, @code{after_cancel(None)} now raises a
@ref{277,,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{2a3,,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{fbd,,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{a12,,str.format()} method when formatting a number
(@ref{326,,int}, @ref{327,,float}, @code{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<68>,Tests<69>,Library<180>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id873}@anchor{20a2}
@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{1a9,,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{2c9,,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<69>,Build<73>,Documentation<68>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id874}@anchor{20a3}
@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<73>,Windows<64>,Tests<69>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id875}@anchor{20a4}
@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<64>,macOS<51>,Build<73>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id876}@anchor{20a5}
@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{ced,,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<51>,IDLE<48>,Windows<64>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id877}@anchor{20a6}
@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<48>,Tools/Demos<43>,macOS<51>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id878}@anchor{20a7}
@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 μεταβλητή περιβάλλοντος; IDLESTARTUP
@code{IDLESTARTUP} or
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,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<43>,C API<66>,IDLE<48>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id879}@anchor{20a8}
@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<66>,,Tools/Demos<43>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id880}@anchor{20a9}
@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{20aa}
@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{20ab}
@subsection Python 3.6.4 release candidate 1


`Release date: 2017-12-05'

@menu
* Core and Builtins: Core and Builtins<179>. 
* Library: Library<181>. 
* Documentation: Documentation<69>. 
* Tests: Tests<70>. 
* Build: Build<74>. 
* Windows: Windows<65>. 
* macOS: macOS<52>. 
* IDLE: IDLE<49>. 
* Tools/Demos: Tools/Demos<44>. 
* C API: C API<67>. 

@end menu

@node Core and Builtins<179>,Library<181>,,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id881}@anchor{20ac}
@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<181>,Documentation<69>,Core and Builtins<179>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id882}@anchor{20ad}
@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{1cf,,collections.namedtuple()} in the
@ref{2070,,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<69>,Tests<70>,Library<181>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id883}@anchor{20ae}
@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<70>,Build<74>,Documentation<69>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id884}@anchor{20af}
@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<74>,Windows<65>,Tests<70>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id885}@anchor{20b0}
@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<65>,macOS<52>,Build<74>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id886}@anchor{20b1}
@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<52>,IDLE<49>,Windows<65>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id887}@anchor{20b2}
@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<49>,Tools/Demos<44>,macOS<52>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id888}@anchor{20b3}
@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<44>,C API<67>,IDLE<49>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id889}@anchor{20b4}
@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<67>,,Tools/Demos<44>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id890}@anchor{20b5}
@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{20b6}
@subsection Python 3.6.3 final


`Release date: 2017-10-03'

@menu
* Library: Library<182>. 
* Build: Build<75>. 

@end menu

@node Library<182>,Build<75>,,Python 3 6 3 final
@anchor{whatsnew/changelog id891}@anchor{20b7}
@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<75>,,Library<182>,Python 3 6 3 final
@anchor{whatsnew/changelog id892}@anchor{20b8}
@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{20b9}
@subsection Python 3.6.3 release candidate 1


`Release date: 2017-09-18'

@menu
* Security: Security<50>. 
* Core and Builtins: Core and Builtins<180>. 
* Library: Library<183>. 
* Documentation: Documentation<70>. 
* Tests: Tests<71>. 
* Build: Build<76>. 
* Windows: Windows<66>. 
* IDLE: IDLE<50>. 
* Tools/Demos: Tools/Demos<45>. 

@end menu

@node Security<50>,Core and Builtins<180>,,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id893}@anchor{20ba}
@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<180>,Library<183>,Security<50>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id894}@anchor{20bb}
@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 library 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<183>,Documentation<70>,Core and Builtins<180>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id895}@anchor{20bc}
@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<70>,Tests<71>,Library<183>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id896}@anchor{20bd}
@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<71>,Build<76>,Documentation<70>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id897}@anchor{20be}
@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<76>,Windows<66>,Tests<71>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id898}@anchor{20bf}
@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<66>,IDLE<50>,Build<76>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id899}@anchor{20c0}
@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<50>,Tools/Demos<45>,Windows<66>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id900}@anchor{20c1}
@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(“”) 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<45>,,IDLE<50>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id901}@anchor{20c2}
@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{20c3}
@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{20c4}
@subsection Python 3.6.2 release candidate 2


`Release date: 2017-07-07'

@menu
* Security: Security<51>. 

@end menu

@node Security<51>,,,Python 3 6 2 release candidate 2
@anchor{whatsnew/changelog id902}@anchor{20c5}
@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{20c6}
@subsection Python 3.6.2 release candidate 1


`Release date: 2017-06-17'

@menu
* Security: Security<52>. 
* Core and Builtins: Core and Builtins<181>. 
* Library: Library<184>. 
* IDLE: IDLE<51>. 
* C API: C API<68>. 
* Build: Build<77>. 
* Documentation: Documentation<71>. 
* Tools/Demos: Tools/Demos<46>. 
* Tests: Tests<72>. 
* Windows: Windows<67>. 

@end menu

@node Security<52>,Core and Builtins<181>,,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id903}@anchor{20c7}
@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<181>,Library<184>,Security<52>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id904}@anchor{20c8}
@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{c57,,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<184>,IDLE<51>,Core and Builtins<181>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id905}@anchor{20c9}
@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<51>,C API<68>,Library<184>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id906}@anchor{20ca}
@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<68>,Build<77>,IDLE<51>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id907}@anchor{20cb}
@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<77>,Documentation<71>,C API<68>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id908}@anchor{20cc}
@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<71>,Tools/Demos<46>,Build<77>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id909}@anchor{20cd}
@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{1c7,,bytes()} and @ref{1c6,,bytearray()} are
now their respective type definitions, rather than the corresponding
builtin function entries. Use @ref{2087,,bytes} and
@ref{2088,,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<46>,Tests<72>,Documentation<71>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id910}@anchor{20ce}
@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<72>,Windows<67>,Tools/Demos<46>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id911}@anchor{20cf}
@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<67>,,Tests<72>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id912}@anchor{20d0}
@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{20d1}
@subsection Python 3.6.1 final


`Release date: 2017-03-21'

@menu
* Core and Builtins: Core and Builtins<182>. 
* Build: Build<78>. 

@end menu

@node Core and Builtins<182>,Build<78>,,Python 3 6 1 final
@anchor{whatsnew/changelog id913}@anchor{20d2}
@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<78>,,Core and Builtins<182>,Python 3 6 1 final
@anchor{whatsnew/changelog id914}@anchor{20d3}
@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{20d4}
@subsection Python 3.6.1 release candidate 1


`Release date: 2017-03-04'

@menu
* Core and Builtins: Core and Builtins<183>. 
* Library: Library<185>. 
* IDLE: IDLE<52>. 
* Windows: Windows<68>. 
* C API: C API<69>. 
* Documentation: Documentation<72>. 
* Tests: Tests<73>. 
* Build: Build<79>. 

@end menu

@node Core and Builtins<183>,Library<185>,,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id915}@anchor{20d5}
@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<185>,IDLE<52>,Core and Builtins<183>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id916}@anchor{20d6}
@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<52>,Windows<68>,Library<185>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id917}@anchor{20d7}
@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<68>,C API<69>,IDLE<52>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id918}@anchor{20d8}
@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<69>,Documentation<72>,Windows<68>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id919}@anchor{20d9}
@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<72>,Tests<73>,C API<69>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id920}@anchor{20da}
@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<73>,Build<79>,Documentation<72>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id921}@anchor{20db}
@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<79>,,Tests<73>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id922}@anchor{20dc}
@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{20dd}
@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{20de}
@subsection Python 3.6.0 release candidate 2


`Release date: 2016-12-16'

@menu
* Core and Builtins: Core and Builtins<184>. 
* Tools/Demos: Tools/Demos<47>. 
* Windows: Windows<69>. 
* Build: Build<80>. 

@end menu

@node Core and Builtins<184>,Tools/Demos<47>,,Python 3 6 0 release candidate 2
@anchor{whatsnew/changelog id923}@anchor{20df}
@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<47>,Windows<69>,Core and Builtins<184>,Python 3 6 0 release candidate 2
@anchor{whatsnew/changelog id924}@anchor{20e0}
@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<69>,Build<80>,Tools/Demos<47>,Python 3 6 0 release candidate 2
@anchor{whatsnew/changelog id925}@anchor{20e1}
@subsubsection Windows



@itemize -

@item 
bpo-28896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28896}: Deprecate WindowsRegistryFinder.
@end itemize

@node Build<80>,,Windows<69>,Python 3 6 0 release candidate 2
@anchor{whatsnew/changelog id926}@anchor{20e2}
@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{20e3}
@subsection Python 3.6.0 release candidate 1


`Release date: 2016-12-06'

@menu
* Core and Builtins: Core and Builtins<185>. 
* Library: Library<186>. 
* C API: C API<70>. 
* Documentation: Documentation<73>. 
* Tools/Demos: Tools/Demos<48>. 

@end menu

@node Core and Builtins<185>,Library<186>,,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id927}@anchor{20e4}
@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<186>,C API<70>,Core and Builtins<185>,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id928}@anchor{20e5}
@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<70>,Documentation<73>,Library<186>,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id929}@anchor{20e6}
@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<73>,Tools/Demos<48>,C API<70>,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id930}@anchor{20e7}
@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<48>,,Documentation<73>,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id931}@anchor{20e8}
@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{20e9}
@subsection Python 3.6.0 beta 4


`Release date: 2016-11-21'

@menu
* Core and Builtins: Core and Builtins<186>. 
* Library: Library<187>. 
* Documentation: Documentation<74>. 
* Tests: Tests<74>. 
* Build: Build<81>. 

@end menu

@node Core and Builtins<186>,Library<187>,,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id932}@anchor{20ea}
@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<187>,Documentation<74>,Core and Builtins<186>,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id933}@anchor{20eb}
@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<74>,Tests<74>,Library<187>,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id934}@anchor{20ec}
@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<74>,Build<81>,Documentation<74>,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id935}@anchor{20ed}
@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<81>,,Tests<74>,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id936}@anchor{20ee}
@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{20ef}
@subsection Python 3.6.0 beta 3


`Release date: 2016-10-31'

@menu
* Core and Builtins: Core and Builtins<187>. 
* Library: Library<188>. 
* Windows: Windows<70>. 
* Build: Build<82>. 
* Tests: Tests<75>. 

@end menu

@node Core and Builtins<187>,Library<188>,,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id937}@anchor{20f0}
@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<188>,Windows<70>,Core and Builtins<187>,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id938}@anchor{20f1}
@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<70>,Build<82>,Library<188>,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id939}@anchor{20f2}
@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<82>,Tests<75>,Windows<70>,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id940}@anchor{20f3}
@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<75>,,Build<82>,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id941}@anchor{20f4}
@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{20f5}
@subsection Python 3.6.0 beta 2


`Release date: 2016-10-10'

@menu
* Core and Builtins: Core and Builtins<188>. 
* Library: Library<189>. 
* Windows: Windows<71>. 
* C API: C API<71>. 
* Build: Build<83>. 
* Tests: Tests<76>. 

@end menu

@node Core and Builtins<188>,Library<189>,,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id942}@anchor{20f6}
@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 split 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<189>,Windows<71>,Core and Builtins<188>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id943}@anchor{20f7}
@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<71>,C API<71>,Library<189>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id944}@anchor{20f8}
@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<71>,Build<83>,Windows<71>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id945}@anchor{20f9}
@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<83>,Tests<76>,C API<71>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id946}@anchor{20fa}
@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<76>,,Build<83>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id947}@anchor{20fb}
@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{20fc}
@subsection Python 3.6.0 beta 1


`Release date: 2016-09-12'

@menu
* Core and Builtins: Core and Builtins<189>. 
* Library: Library<190>. 
* IDLE: IDLE<53>. 
* C API: C API<72>. 
* Tests: Tests<77>. 
* Build: Build<84>. 
* Tools/Demos: Tools/Demos<49>. 
* Windows: Windows<72>. 

@end menu

@node Core and Builtins<189>,Library<190>,,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id948}@anchor{20fd}
@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<190>,IDLE<53>,Core and Builtins<189>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id949}@anchor{20fe}
@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{931,,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{107b,,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<53>,C API<72>,Library<190>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id950}@anchor{20ff}
@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<72>,Tests<77>,IDLE<53>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id951}@anchor{2100}
@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<77>,Build<84>,C API<72>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id952}@anchor{2101}
@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<84>,Tools/Demos<49>,Tests<77>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id953}@anchor{2102}
@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<49>,Windows<72>,Build<84>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id954}@anchor{2103}
@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<72>,,Tools/Demos<49>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id955}@anchor{2104}
@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{2105}
@subsection Python 3.6.0 alpha 4


`Release date: 2016-08-15'

@menu
* Core and Builtins: Core and Builtins<190>. 
* Library: Library<191>. 
* IDLE: IDLE<54>. 
* Tests: Tests<78>. 
* Windows: Windows<73>. 
* Build: Build<85>. 

@end menu

@node Core and Builtins<190>,Library<191>,,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id956}@anchor{2106}
@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<191>,IDLE<54>,Core and Builtins<190>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id957}@anchor{2107}
@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<54>,Tests<78>,Library<191>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id958}@anchor{2108}
@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<78>,Windows<73>,IDLE<54>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id959}@anchor{2109}
@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<73>,Build<85>,Tests<78>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id960}@anchor{210a}
@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<85>,,Windows<73>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id961}@anchor{210b}
@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{210c}
@subsection Python 3.6.0 alpha 3


`Release date: 2016-07-11'

@menu
* Security: Security<53>. 
* Core and Builtins: Core and Builtins<191>. 
* Library: Library<192>. 
* IDLE: IDLE<55>. 
* C API: C API<73>. 
* Build: Build<86>. 
* Tools/Demos: Tools/Demos<50>. 
* Documentation: Documentation<75>. 
* Tests: Tests<79>. 

@end menu

@node Security<53>,Core and Builtins<191>,,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id962}@anchor{210d}
@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<191>,Library<192>,Security<53>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id963}@anchor{210e}
@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<192>,IDLE<55>,Core and Builtins<191>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id964}@anchor{210f}
@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<55>,C API<73>,Library<192>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id965}@anchor{2110}
@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<73>,Build<86>,IDLE<55>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id966}@anchor{2111}
@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<86>,Tools/Demos<50>,C API<73>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id967}@anchor{2112}
@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<50>,Documentation<75>,Build<86>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id968}@anchor{2113}
@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<75>,Tests<79>,Tools/Demos<50>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id969}@anchor{2114}
@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<79>,,Documentation<75>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id970}@anchor{2115}
@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{2116}
@subsection Python 3.6.0 alpha 2


`Release date: 2016-06-13'

@menu
* Security: Security<54>. 
* Core and Builtins: Core and Builtins<192>. 
* Library: Library<193>. 
* IDLE: IDLE<56>. 
* Documentation: Documentation<76>. 
* Tests: Tests<80>. 
* Windows: Windows<74>. 
* Build: Build<87>. 
* C API: C API<74>. 
* Tools/Demos: Tools/Demos<51>. 

@end menu

@node Security<54>,Core and Builtins<192>,,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id971}@anchor{2117}
@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{931,,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<192>,Library<193>,Security<54>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id972}@anchor{2118}
@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<193>,IDLE<56>,Core and Builtins<192>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id973}@anchor{2119}
@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{81,,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{db,,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<56>,Documentation<76>,Library<193>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id974}@anchor{211a}
@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<76>,Tests<80>,IDLE<56>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id975}@anchor{211b}
@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<80>,Windows<74>,Documentation<76>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id976}@anchor{211c}
@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<74>,Build<87>,Tests<80>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id977}@anchor{211d}
@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<87>,C API<74>,Windows<74>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id978}@anchor{211e}
@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<74>,Tools/Demos<51>,Build<87>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id979}@anchor{211f}
@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<51>,,C API<74>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id980}@anchor{2120}
@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{2121}
@subsection Python 3.6.0 alpha 1


`Release date: 2016-05-16'

@menu
* Security: Security<55>. 
* Core and Builtins: Core and Builtins<193>. 
* Library: Library<194>. 
* IDLE: IDLE<57>. 
* Documentation: Documentation<77>. 
* Tests: Tests<81>. 
* Build: Build<88>. 
* Windows: Windows<75>. 
* Tools/Demos: Tools/Demos<52>. 
* C API: C API<75>. 

@end menu

@node Security<55>,Core and Builtins<193>,,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id981}@anchor{2122}
@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<193>,Library<194>,Security<55>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id982}@anchor{2123}
@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{1024,,PyMem_Malloc()} domain
(@ref{1027,,PYMEM_DOMAIN_MEM}) now use the @ref{3da,,pymalloc allocator} rather than system @code{malloc()}. Applications calling
@code{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{1024,,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{108,,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{1026,,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 μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,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{1028,,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 μεταβλητή περιβάλλοντος; PYTHONMALLOCSTATS
@ref{2124,,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<194>,IDLE<57>,Core and Builtins<193>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id983}@anchor{2125}
@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{14af,,shutil.get_terminal_size()}, catch
@ref{1a9,,AttributeError} instead of @ref{665,,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{931,,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 split 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{7a,,importlib} module now emits an @ref{1bd,,ImportError}
rather than a @ref{291,,TypeError} if @ref{ca6,,__import__()} is tried during the
Python shutdown process but @ref{194,,sys.path} is already cleared (set to
@code{None}).

@item 
bpo-21925@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21925}: @ref{1fe7,,warnings.formatwarning()} now catches exceptions when
calling @ref{4cd,,linecache.getline()} and
@ref{2126,,tracemalloc.get_object_traceback()} to be able to log
@ref{74f,,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{108,,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{10d1,,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{c04,,pyclbr.readmodule()} and @ref{c05,,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”” instead of “” 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<57>,Documentation<77>,Library<194>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id984}@anchor{2127}
@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<77>,Tests<81>,IDLE<57>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id985}@anchor{2128}
@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<81>,Build<88>,Documentation<77>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id986}@anchor{2129}
@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<88>,Windows<75>,Tests<81>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id987}@anchor{212a}
@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<75>,Tools/Demos<52>,Build<88>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id988}@anchor{212b}
@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<52>,C API<75>,Windows<75>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id989}@anchor{212c}
@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<75>,,Tools/Demos<52>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id990}@anchor{212d}
@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{212e}
@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{212f}
@subsection Python 3.5.5 release candidate 1


`Release date: 2018-01-23'

@menu
* Security: Security<56>. 
* Core and Builtins: Core and Builtins<194>. 
* Library: Library<195>. 

@end menu

@node Security<56>,Core and Builtins<194>,,Python 3 5 5 release candidate 1
@anchor{whatsnew/changelog id991}@anchor{2130}
@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<194>,Library<195>,Security<56>,Python 3 5 5 release candidate 1
@anchor{whatsnew/changelog id992}@anchor{2131}
@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<195>,,Core and Builtins<194>,Python 3 5 5 release candidate 1
@anchor{whatsnew/changelog id993}@anchor{2132}
@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{2133}
@subsection Python 3.5.4 final


`Release date: 2017-08-07'

@menu
* Library: Library<196>. 

@end menu

@node Library<196>,,,Python 3 5 4 final
@anchor{whatsnew/changelog id994}@anchor{2134}
@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{2135}
@subsection Python 3.5.4 release candidate 1


`Release date: 2017-07-23'

@menu
* Security: Security<57>. 
* Core and Builtins: Core and Builtins<195>. 
* Library: Library<197>. 
* Documentation: Documentation<78>. 
* Tests: Tests<82>. 
* Build: Build<89>. 
* Windows: Windows<76>. 
* C API: C API<76>. 

@end menu

@node Security<57>,Core and Builtins<195>,,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id995}@anchor{2136}
@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<195>,Library<197>,Security<57>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id996}@anchor{2137}
@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{c57,,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<197>,Documentation<78>,Core and Builtins<195>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id997}@anchor{2138}
@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<78>,Tests<82>,Library<197>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id998}@anchor{2139}
@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<82>,Build<89>,Documentation<78>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id999}@anchor{213a}
@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<89>,Windows<76>,Tests<82>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id1000}@anchor{213b}
@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<76>,C API<76>,Build<89>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id1001}@anchor{213c}
@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<76>,,Windows<76>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id1002}@anchor{213d}
@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{213e}
@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{213f}
@subsection Python 3.5.3 release candidate 1


`Release date: 2017-01-02'

@menu
* Security: Security<58>. 
* Core and Builtins: Core and Builtins<196>. 
* Library: Library<198>. 
* IDLE: IDLE<58>. 
* C API: C API<77>. 
* Documentation: Documentation<79>. 
* Tests: Tests<83>. 
* Tools/Demos: Tools/Demos<53>. 
* Windows: Windows<77>. 
* Build: Build<90>. 

@end menu

@node Security<58>,Core and Builtins<196>,,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id1003}@anchor{2140}
@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<196>,Library<198>,Security<58>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id1004}@anchor{2141}
@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<198>,IDLE<58>,Core and Builtins<196>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id1005}@anchor{2142}
@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<58>,C API<77>,Library<198>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id1006}@anchor{2143}
@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<77>,Documentation<79>,IDLE<58>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id1007}@anchor{2144}
@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<79>,Tests<83>,C API<77>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id1008}@anchor{2145}
@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<83>,Tools/Demos<53>,Documentation<79>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id1009}@anchor{2146}
@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<53>,Windows<77>,Tests<83>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id1010}@anchor{2147}
@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<77>,Build<90>,Tools/Demos<53>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id1011}@anchor{2148}
@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<90>,,Windows<77>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id1012}@anchor{2149}
@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{214a}
@subsection Python 3.5.2 final


`Release date: 2016-06-26'

@menu
* Core and Builtins: Core and Builtins<197>. 
* Tests: Tests<84>. 
* IDLE: IDLE<59>. 

@end menu

@node Core and Builtins<197>,Tests<84>,,Python 3 5 2 final
@anchor{whatsnew/changelog id1013}@anchor{214b}
@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<84>,IDLE<59>,Core and Builtins<197>,Python 3 5 2 final
@anchor{whatsnew/changelog id1014}@anchor{214c}
@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<59>,,Tests<84>,Python 3 5 2 final
@anchor{whatsnew/changelog id1015}@anchor{214d}
@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{214e}
@subsection Python 3.5.2 release candidate 1


`Release date: 2016-06-12'

@menu
* Security: Security<59>. 
* Core and Builtins: Core and Builtins<198>. 
* Library: Library<199>. 
* IDLE: IDLE<60>. 
* Documentation: Documentation<80>. 
* Tests: Tests<85>. 
* Build: Build<91>. 
* Windows: Windows<78>. 
* Tools/Demos: Tools/Demos<54>. 

@end menu

@node Security<59>,Core and Builtins<198>,,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id1016}@anchor{214f}
@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{931,,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<198>,Library<199>,Security<59>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id1017}@anchor{2150}
@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<199>,IDLE<60>,Core and Builtins<198>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id1018}@anchor{2151}
@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{db,,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{14af,,shutil.get_terminal_size()}, catch
@ref{1a9,,AttributeError} instead of @ref{665,,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{931,,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{1fe7,,warnings.formatwarning()} now catches exceptions on
@code{linecache.getline(...)} to be able to log @ref{74f,,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{c04,,pyclbr.readmodule()} and @ref{c05,,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<60>,Documentation<80>,Library<199>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id1019}@anchor{2152}
@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<80>,Tests<85>,IDLE<60>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id1020}@anchor{2153}
@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<85>,Build<91>,Documentation<80>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id1021}@anchor{2154}
@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<91>,Windows<78>,Tests<85>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id1022}@anchor{2155}
@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<78>,Tools/Demos<54>,Build<91>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id1023}@anchor{2156}
@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<54>,,Windows<78>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id1024}@anchor{2157}
@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{2158}
@subsection Python 3.5.1 final


`Release date: 2015-12-06'

@menu
* Core and Builtins: Core and Builtins<199>. 
* Windows: Windows<79>. 

@end menu

@node Core and Builtins<199>,Windows<79>,,Python 3 5 1 final
@anchor{whatsnew/changelog id1025}@anchor{2159}
@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<79>,,Core and Builtins<199>,Python 3 5 1 final
@anchor{whatsnew/changelog id1026}@anchor{215a}
@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{215b}
@subsection Python 3.5.1 release candidate 1


`Release date: 2015-11-22'

@menu
* Core and Builtins: Core and Builtins<200>. 
* Library: Library<200>. 
* IDLE: IDLE<61>. 
* Documentation: Documentation<81>. 
* Tests: Tests<86>. 
* Build: Build<92>. 
* Windows: Windows<80>. 
* Tools/Demos: Tools/Demos<55>. 

@end menu

@node Core and Builtins<200>,Library<200>,,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id1027}@anchor{215c}
@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<200>,IDLE<61>,Core and Builtins<200>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id1028}@anchor{215d}
@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”” instead of “” 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<61>,Documentation<81>,Library<200>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id1029}@anchor{215e}
@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<81>,Tests<86>,IDLE<61>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id1030}@anchor{215f}
@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<86>,Build<92>,Documentation<81>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id1031}@anchor{2160}
@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<92>,Windows<80>,Tests<86>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id1032}@anchor{2161}
@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<80>,Tools/Demos<55>,Build<92>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id1033}@anchor{2162}
@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<55>,,Windows<80>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id1034}@anchor{2163}
@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{2164}
@subsection Python 3.5.0 final


`Release date: 2015-09-13'

@menu
* Build: Build<93>. 

@end menu

@node Build<93>,,,Python 3 5 0 final
@anchor{whatsnew/changelog id1035}@anchor{2165}
@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{2166}
@subsection Python 3.5.0 release candidate 4


`Release date: 2015-09-09'

@menu
* Library: Library<201>. 
* Build: Build<94>. 

@end menu

@node Library<201>,Build<94>,,Python 3 5 0 release candidate 4
@anchor{whatsnew/changelog id1036}@anchor{2167}
@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<94>,,Library<201>,Python 3 5 0 release candidate 4
@anchor{whatsnew/changelog id1037}@anchor{2168}
@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{2169}
@subsection Python 3.5.0 release candidate 3


`Release date: 2015-09-07'

@menu
* Core and Builtins: Core and Builtins<201>. 
* Library: Library<202>. 

@end menu

@node Core and Builtins<201>,Library<202>,,Python 3 5 0 release candidate 3
@anchor{whatsnew/changelog id1038}@anchor{216a}
@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<202>,,Core and Builtins<201>,Python 3 5 0 release candidate 3
@anchor{whatsnew/changelog id1039}@anchor{216b}
@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{216c}
@subsection Python 3.5.0 release candidate 2


`Release date: 2015-08-25'

@menu
* Core and Builtins: Core and Builtins<202>. 
* Library: Library<203>. 

@end menu

@node Core and Builtins<202>,Library<203>,,Python 3 5 0 release candidate 2
@anchor{whatsnew/changelog id1040}@anchor{216d}
@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<203>,,Core and Builtins<202>,Python 3 5 0 release candidate 2
@anchor{whatsnew/changelog id1041}@anchor{216e}
@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{216f}
@subsection Python 3.5.0 release candidate 1


`Release date: 2015-08-09'

@menu
* Core and Builtins: Core and Builtins<203>. 
* Library: Library<204>. 
* IDLE: IDLE<62>. 
* Documentation: Documentation<82>. 
* Tests: Tests<87>. 

@end menu

@node Core and Builtins<203>,Library<204>,,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id1042}@anchor{2170}
@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<204>,IDLE<62>,Core and Builtins<203>,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id1043}@anchor{2171}
@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<62>,Documentation<82>,Library<204>,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id1044}@anchor{2172}
@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<82>,Tests<87>,IDLE<62>,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id1045}@anchor{2173}
@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<87>,,Documentation<82>,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id1046}@anchor{2174}
@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{2175}
@subsection Python 3.5.0 beta 4


`Release date: 2015-07-26'

@menu
* Core and Builtins: Core and Builtins<204>. 
* Library: Library<205>. 
* Build: Build<95>. 

@end menu

@node Core and Builtins<204>,Library<205>,,Python 3 5 0 beta 4
@anchor{whatsnew/changelog id1047}@anchor{2176}
@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<205>,Build<95>,Core and Builtins<204>,Python 3 5 0 beta 4
@anchor{whatsnew/changelog id1048}@anchor{2177}
@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<95>,,Library<205>,Python 3 5 0 beta 4
@anchor{whatsnew/changelog id1049}@anchor{2178}
@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{2179}
@subsection Python 3.5.0 beta 3


`Release date: 2015-07-05'

@menu
* Core and Builtins: Core and Builtins<205>. 
* Library: Library<206>. 
* Tests: Tests<88>. 
* Documentation: Documentation<83>. 
* Build: Build<96>. 

@end menu

@node Core and Builtins<205>,Library<206>,,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id1050}@anchor{217a}
@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<206>,Tests<88>,Core and Builtins<205>,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id1051}@anchor{217b}
@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<88>,Documentation<83>,Library<206>,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id1052}@anchor{217c}
@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<83>,Build<96>,Tests<88>,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id1053}@anchor{217d}
@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<96>,,Documentation<83>,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id1054}@anchor{217e}
@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{217f}
@subsection Python 3.5.0 beta 2


`Release date: 2015-05-31'

@menu
* Core and Builtins: Core and Builtins<206>. 
* Library: Library<207>. 

@end menu

@node Core and Builtins<206>,Library<207>,,Python 3 5 0 beta 2
@anchor{whatsnew/changelog id1055}@anchor{2180}
@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<207>,,Core and Builtins<206>,Python 3 5 0 beta 2
@anchor{whatsnew/changelog id1056}@anchor{2181}
@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{2182}
@subsection Python 3.5.0 beta 1


`Release date: 2015-05-24'

@menu
* Core and Builtins: Core and Builtins<207>. 
* Library: Library<208>. 
* IDLE: IDLE<63>. 
* Tests: Tests<89>. 
* Documentation: Documentation<84>. 
* Tools/Demos: Tools/Demos<56>. 

@end menu

@node Core and Builtins<207>,Library<208>,,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id1057}@anchor{2183}
@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<208>,IDLE<63>,Core and Builtins<207>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id1058}@anchor{2184}
@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<63>,Tests<89>,Library<208>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id1059}@anchor{2185}
@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<89>,Documentation<84>,IDLE<63>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id1060}@anchor{2186}
@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<84>,Tools/Demos<56>,Tests<89>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id1061}@anchor{2187}
@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<56>,,Documentation<84>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id1062}@anchor{2188}
@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{2189}
@subsection Python 3.5.0 alpha 4


`Release date: 2015-04-19'

@menu
* Core and Builtins: Core and Builtins<208>. 
* Library: Library<209>. 
* Build: Build<97>. 
* Tests: Tests<90>. 
* Tools/Demos: Tools/Demos<57>. 
* C API: C API<78>. 

@end menu

@node Core and Builtins<208>,Library<209>,,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id1063}@anchor{218a}
@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<209>,Build<97>,Core and Builtins<208>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id1064}@anchor{218b}
@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{1161,,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{115c,,socket.socket.connect()} now waits until the connection
completes instead of raising @ref{1141,,InterruptedError} if the connection is
interrupted by signals, signal handlers don’t raise an exception and the
socket is blocking or has a timeout. @code{socket.socket.connect()} still
raise @code{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<97>,Tests<90>,Library<209>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id1065}@anchor{218c}
@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<90>,Tools/Demos<57>,Build<97>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id1066}@anchor{218d}
@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<57>,C API<78>,Tests<90>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id1067}@anchor{218e}
@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<78>,,Tools/Demos<57>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id1068}@anchor{218f}
@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{2190}
@subsection Python 3.5.0 alpha 3


`Release date: 2015-03-28'

@menu
* Core and Builtins: Core and Builtins<209>. 
* Library: Library<210>. 
* Build: Build<98>. 
* Tests: Tests<91>. 
* Tools/Demos: Tools/Demos<58>. 

@end menu

@node Core and Builtins<209>,Library<210>,,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id1069}@anchor{2191}
@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<210>,Build<98>,Core and Builtins<209>,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id1070}@anchor{2192}
@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{1164,,signal.sigwaitinfo()} and @ref{1163,,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<98>,Tests<91>,Library<210>,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id1071}@anchor{2193}
@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<91>,Tools/Demos<58>,Build<98>,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id1072}@anchor{2194}
@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<58>,,Tests<91>,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id1073}@anchor{2195}
@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{2196}
@subsection Python 3.5.0 alpha 2


`Release date: 2015-03-09'

@menu
* Core and Builtins: Core and Builtins<210>. 
* Library: Library<211>. 
* Build: Build<99>. 
* C API: C API<79>. 
* Windows: Windows<81>. 

@end menu

@node Core and Builtins<210>,Library<211>,,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id1074}@anchor{2197}
@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<211>,Build<99>,Core and Builtins<210>,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id1075}@anchor{2198}
@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(“”) 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<99>,C API<79>,Library<211>,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id1076}@anchor{2199}
@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<79>,Windows<81>,Build<99>,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id1077}@anchor{219a}
@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<81>,,C API<79>,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id1078}@anchor{219b}
@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{219c}
@subsection Python 3.5.0 alpha 1


`Release date: 2015-02-08'

@menu
* Core and Builtins: Core and Builtins<211>. 
* Library: Library<212>. 
* IDLE: IDLE<64>. 
* Build: Build<100>. 
* C API: C API<80>. 
* Documentation: Documentation<85>. 
* Tests: Tests<92>. 
* Tools/Demos: Tools/Demos<59>. 
* Windows: Windows<82>. 

@end menu

@node Core and Builtins<211>,Library<212>,,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id1079}@anchor{219d}
@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<212>,IDLE<64>,Core and Builtins<211>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id1080}@anchor{219e}
@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{e4f,,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().  Patch 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{e24,,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(“”) 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} in case 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{8d6,,tempfile.NamedTemporaryFile()}, close the file descriptor if
@ref{92b,,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{94a,,sys.stdin} and @ref{e9c,,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 usable 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<64>,Build<100>,Library<212>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id1081}@anchor{219f}
@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<100>,C API<80>,IDLE<64>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id1082}@anchor{21a0}
@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<80>,Documentation<85>,Build<100>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id1083}@anchor{21a1}
@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{f85,,Py_DecodeLocale()},
rename @code{_Py_wchar2char()} to @ref{f86,,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<85>,Tests<92>,C API<80>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id1084}@anchor{21a2}
@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<92>,Tools/Demos<59>,Documentation<85>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id1085}@anchor{21a3}
@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<59>,Windows<82>,Tests<92>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id1086}@anchor{21a4}
@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<82>,,Tools/Demos<59>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id1087}@anchor{21a5}
@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.)'

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Οδηγός εκμάθησης Python,Ρύθμιση και Χρήση της Python,Τι νέο υπάρχει στην Python,Top
@anchor{tutorial/index doc}@anchor{21a6}@anchor{tutorial/index the-python-tutorial}@anchor{21a7}@anchor{tutorial/index translation-repo}@anchor{21a8}@anchor{tutorial/index tutorial-index}@anchor{21a9}
@chapter Οδηγός εκμάθησης Python


@cartouche
@quotation Πρακτική συμβουλή 
Αυτός ο οδηγός εκμάθησης έχει σχεδιαστεί για `προγραμματιστές' που είναι νέοι στην γλώσσα Python, `όχι' για `αρχάριους' που είναι νέοι στο προγραμματισμό.
@end quotation
@end cartouche

Η Python είναι μια εύκολη στην εκμάθηση, ισχυρή γλώσσα προγραμματισμού. Έχει αποτελεσματικές δομές δεδομένων υψηλού επιπέδου και μια απλή αλλά αποτελεσματική προσέγγιση στον αντικειμενοστραφή προγραμματισμό. Το κομψό συντακτικό και η δυναμική τυποποίηση της Python, σε συνδυασμό με τη διερμηνευμένη φύση της, την καθιστούν ιδανική γλώσσα για scripting και ταχεία ανάπτυξη εφαρμογών σε πολλούς τομείς στις περισσότερες πλατφόρμες.

Ο διερμηνέας της Python και η εκτεταμένη τυπική (standard) βιβλιοθήκη διατίθενται ελεύθερα σε πηγαία ή δυαδική μορφή για όλες τις κύριες πλατφόρμες από την ιστοσελίδα της Python, @indicateurl{https://www.python.org/} και μπορούν να διανεμηθούν ελεύθερα. Ο ίδιος ιστότοπος περιέχει επίσης διανομές και δείκτες σε πολλά δωρεάν modules τρίτων, προγράμματα και εργαλεία Python, καθώς και πρόσθετη τεκμηρίωση.

Ο διερμηνέας της Python επεκτείνεται εύκολα με νέες συναρτήσεις και τύπους δεδομένων που υλοποιούνται σε C ή C++ (ή άλλες γλώσσες που μπορούν να κληθούν από τη C). Η Python είναι επίσης κατάλληλη ως γλώσσα επέκτασης για προσαρμόσιμες εφαρμογές.

Αυτό το tutorial εισάγει τον αναγνώστη ανεπίσημα στις βασικές έννοιες και δυνατότητες της γλώσσας και του συστήματος Python. Λάβετε υπόψη ότι απαιτεί να έχετε μια βασική κατανόηση του προγραμματισμού γενικά. Βοηθάει να έχετε πρόχειρο έναν διερμηνέα Python για πρακτική εμπειρία, αλλά όλα τα παραδείγματα είναι αυτοτελή, οπότε το tutorial μπορεί να διαβαστεί και εκτός σύνδεσης.

Για μια περιγραφή των τυποποιημένων αντικειμένων και ενοτήτων, δείτε @ref{3f7,,The Python Standard Library}. Το @ref{3f8,,Εγχειρίδιο Αναφοράς της Γλώσσας Python} δίνει έναν πιο επίσημο ορισμό της γλώσσας. Για να γράψετε επεκτάσεις σε C ή C++, διαβάστε το @ref{21aa,,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python} και το @ref{21ab,,Python/C API reference manual}. Υπάρχουν επίσης αρκετά βιβλία που καλύπτουν την Python σε βάθος.

Αυτό το tutorial δεν προσπαθεί να είναι περιεκτικό και να καλύψει κάθε χαρακτηριστικό ή ακόμη και κάθε συχνά χρησιμοποιούμενο χαρακτηριστικό. Αντίθετα, θα σας παρουσιάσει πολλά από τα πιο αξιοσημείωτα χαρακτηριστικά της Python και θα σας δώσει μια καλή ιδέα για τη γεύση και το ύφος της γλώσσας. Αφού το διαβάσετε, θα είστε σε θέση να διαβάζετε και να γράφετε modules και προγράμματα Python, και θα είστε έτοιμοι να μάθετε περισσότερα για τα διάφoρα modules βιβλιοθηκών Python που περιγράφονται στο @ref{3f7,,The Python Standard Library}.

Αξίζει επίσης να διαβάσετε το @ref{21ac,,Γλωσσάρι}.

@menu
* Ανοίγοντας την όρεξή σας:: 
* Χρησιμοποιώντας τον Interpreter της Python:: 
* Μία Άτυπη Εισαγωγή στην Python:: 
* Περισσότερα εργαλεία Ελέγχου Ροής:: 
* Δομές Δεδομένων:: 
* Modules: Modules<2>. 
* Είσοδος και Έξοδος:: 
* Σφάλματα και Εξαιρέσεις:: 
* Κλάσεις:: 
* Brief tour of the standard library:: 
* Brief tour of the standard library — part II:: 
* Εικονικά Περιβάλλοντα και πακέτα:: 
* Και τώρα τι;:: 
* Διαδραστική Επεξεργασία Input και Αντικατάσταση Ιστορικού:: 
* Αριθμητική Κινητής Υποδιαστολής; Ζητήματα και Περιορισμοί: Αριθμητική Κινητής Υποδιαστολής Ζητήματα και Περιορισμοί. 
* Παράρτημα:: 

@end menu

@node Ανοίγοντας την όρεξή σας,Χρησιμοποιώντας τον Interpreter της Python,,Οδηγός εκμάθησης Python
@anchor{tutorial/appetite doc}@anchor{21ad}@anchor{tutorial/appetite tut-intro}@anchor{21ae}@anchor{tutorial/appetite whetting-your-appetite}@anchor{21af}
@section Ανοίγοντας την όρεξή σας


Εάν κάνετε πολλή δουλειά σε υπολογιστές, τελικά θα διαπιστώσετε ότι υπάρχει κάποια εργασία που θα θέλατε να αυτοματοποιήσετε.  Για παράδειγμα, μπορεί να θέλετε να πραγματοποιήσετε αναζήτηση και αντικατάσταση σε μεγάλο αριθμό αρχείων κειμένου ή να μετονομάσετε και να αναδιατάξετε μια δέσμη αρχείων φωτογραφιών με περίπλοκο τρόπο. Ίσως θα θέλατε να γράψετε μια μικρή προσαρμοσμένη βάση δεδομένων ή μια εξειδικευμένη εφαρμογή GUI ή ένα απλό παιχνίδι.

Εάν είστε επαγγελματίας προγραμματιστής λογισμικού, μπορεί να χρειαστεί να εργαστείτε με πολλές βιβλιοθήκες C/C++/Java, αλλά ο συνηθισμένος κύκλος εγγραφής/compile/δοκιμής/re-compile είναι πολύ αργός.  Ίσως γράφετε ένα test suite για μια τέτοια βιβλιοθήκη και βρίσκετε τη δημιουργία κώδικα testing μια κουραστική διαδικασία.  Ή ίσως έχετε γράψει ένα πρόγραμμα που θα μπορούσε να χρησιμοποιεί μια γλώσσα επέκτασης, και δεν θέλετε να σχεδιάσετε και να εφαρμόσετε μια εντελώς νέα γλώσσα για την εφαρμογή σας.

Η Python είναι απλώς η γλώσσα για εσάς.

Θα μπορούσατε να γράψετε ένα Unix shell script ή Windows batch αρχεία για ορισμένες από αυτές τις εργασίες, αλλά τα shell scripts είναι τα καλύτερα για τη μετακίνηση αρχείων και την αλλαγή δεδομένων κειμένου, δεν είναι κατάλληλα για εφαρμογές ή παιχνίδια GUI. Θα μπορούσατε να γράψετε ένα C/C++/Java πρόγραμμα, αλλά μπορεί να χρειαστεί πολύς χρόνος ανάπτυξης για να δημιουργηθεί μια πρώτη έκδοση του προγράμματος.  Η Python είναι πιο απλή στη χρήση, διαθέσιμη σε λειτουργικά συστήματα Windows, macOS και Unix και θα σας βοηθήσει να ολοκληρώσετε τη δουλειά πιο γρήγορα.

Η Python είναι απλή στη χρήση, αλλά είναι μια πραγματική γλώσσα προγραμματισμού, που προσφέρει πολύ περισσότερη δομή και υποστήριξη για μεγάλα προγράμματα από ό,τι μπορούν να προσφέρουν τα shell scripts ή τα batch αρχεία. Από την άλλη πλευρά, η Python προσφέρει επίσης πολύ περισσότερο έλεγχο σφαλμάτων από τη C και, όντας μια γλώσσα `πολύ υψηλού επιπέδου', έχει ενσωματωμένους τύπους δεδομένων υψηλού επιπέδου, όπως ευέλικτους πίνακες, και λεξικά.  Λόγω των πιο γενικών τύπων δεδομένων της, η Python μπορεί να εφαρμοστεί σε έναν πολύ μεγαλύτερο τομέα προβλημάτων από την Awk ή ακόμα και την Perl, ωστόσο πολλά πράγματα είναι τουλάχιστον τόσο εύκολα στην Python όσο σε αυτές τις γλώσσες.

Η Python σάς επιτρέπει να χωρίσετε το πρόγραμμά σας σε modules που μπορούν να επαναχρησιμοποιηθούν σε άλλα προγράμματα Python.  Έρχεται με μια μεγάλη συλλογή standard modules που μπορείτε να χρησιμοποιήσετε ως βάση των προγραμμάτων σας — ή ως παράδειγμα για να ξεκινήσετε να μαθαίνετε να προγραμματίζετε σε Python.  Ορισμένα από αυτά τα modules παρέχουν πράγματα όπως I/O αρχείων, κλήσεις συστήματος, sockets, ακόμη και interfaces σε toolkits γραφικών διεπαφής χρήστη, όπως το Tk.

Η Python είναι μια interpreted γλώσσα, η οποία μπορεί να σας εξοικονομήσει σημαντικό χρόνο κατά την ανάπτυξη του προγράμματος, επειδή δεν απαιτείται compilation και linking.  Ο interpreter μπορεί να χρησιμοποιηθεί διαδραστικά, γεγονός που καθιστά εύκολο τον πειραματισμό με χαρακτηριστικά της γλώσσας, τη σύνταξη προγραμμάτων ή τον έλεγχο συναρτήσεων κατά την ανάπτυξη προγράμματος από κάτω προς τα πάνω. Είναι επίσης μια εύχρηστη αριθμομηχανή.

Η Python επιτρέπει στα προγράμματα να γράφονται συμπαγή και ευανάγνωστα. Τα προγράμματα που είναι γραμμένα σε Python είναι συνήθως πολύ μικρότερα από τα αντίστοιχα προγράμματα C, C++ ή Java, για διάφορους λόγους:


@itemize *

@item 
οι τύποι δεδομένων υψηλού επιπέδου σάς επιτρέπουν να εκφράσετε πολύπλοκες λειτουργίες σε μία μόνο δήλωση∙

@item 
η ομαδοποίηση δηλώσεων γίνεται με εσοχή αντί για αγκύλες αρχής και λήξης∙

@item 
δεν απαιτούνται δηλώσεις μεταβλητών ή ορισμάτων.
@end itemize

Η Python είναι `επεκτάσιμη': αν ξέρετε πώς να προγραμματίζετε σε C είναι εύκολο να προσθέσετε μια νέα ενσωματωμένη συνάρτηση ή module στον interpreter, είτε για να εκτελέσετε κρίσιμες λειτουργίες με μέγιστη ταχύτητα, είτε για να συνδέσετε προγράμματα Python με βιβλιοθήκες που μπορεί να είναι διαθέσιμες μόνο σε δυαδική μορφή (όπως μια βιβλιοθήκη γραφικών για συγκεκριμένο προμηθευτή). Μόλις κολλήσετε πραγματικά, μπορείτε να συνδέσετε τον Python interpreter σε μια εφαρμογή γραμμένη σε C και να τη χρησιμοποιήσετε ως επέκταση ή γλώσσα εντολών για αυτήν την εφαρμογή.

Παρεμπιπτόντως, η γλώσσα πήρε το όνομά της από την εκπομπή του BBC «Monty Python’s Flying Circus» και δεν έχει καμία σχέση με ερπετά. Η αναφορά σε σκετς Monty Python στην τεκμηρίωση όχι μόνο επιτρέπεται, αλλά και ενθαρρύνεται!

Τώρα που είστε όλοι ενθουσιασμένοι με την Python, θα θέλετε να την εξετάσετε με περισσότερες λεπτομέρειες. Επειδή ο καλύτερος τρόπος για να μάθετε μια γλώσσα είναι να τη χρησιμοποιήσετε, ο οδηγός εκμάθησης σας προσκαλεί να παίξετε με τον Python interpreter καθώς διαβάζετε.

Στο επόμενο κεφάλαιο, εξηγείται η μηχανική της χρήσης του interpreter. Αυτή είναι μάλλον πεζή πληροφορία, αλλά απαραίτητη για τη δοκιμή των παραδειγμάτων που παρουσιάζονται αργότερα.

Ο υπόλοιπος οδηγός εκμάθησης εισάγει διάφορα χαρακτηριστικά της γλώσσας και του συστήματος Python μέσω παραδειγμάτων, ξεκινώντας με απλές εκφράσεις, δηλώσεις και τύπους δεδομένων, μέσω συναρτήσεων και modules και τέλος αγγίζοντας προηγμένες έννοιες όπως εξαιρέσεις και κλάσεις που καθορίζονται από τον χρήστη.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Χρησιμοποιώντας τον Interpreter της Python,Μία Άτυπη Εισαγωγή στην Python,Ανοίγοντας την όρεξή σας,Οδηγός εκμάθησης Python
@anchor{tutorial/interpreter doc}@anchor{21b0}@anchor{tutorial/interpreter translation-repo}@anchor{21b1}@anchor{tutorial/interpreter tut-using}@anchor{21b2}@anchor{tutorial/interpreter using-the-python-interpreter}@anchor{21b3}
@section Χρησιμοποιώντας τον Interpreter της Python


@menu
* Κάνοντας invoke τον Interpreter:: 
* Ο Interpreter και το Περιβάλλον του:: 

@end menu

@node Κάνοντας invoke τον Interpreter,Ο Interpreter και το Περιβάλλον του,,Χρησιμοποιώντας τον Interpreter της Python
@anchor{tutorial/interpreter invoking-the-interpreter}@anchor{21b4}@anchor{tutorial/interpreter tut-invoking}@anchor{21b5}
@subsection Κάνοντας invoke τον Interpreter


Ο διερμηνέας της Python εγκαθίσταται συνήθως ως @code{/usr/local/bin/python3.16} σε εκείνα τα μηχανήματα όπου είναι διαθέσιμος· βάζοντας @code{/usr/local/bin} στη διαδρομή αναζήτησης του Unix shell σας επιτρέπει να το εκκινήσετε πληκτρολογώντας την εντολή:

@example
python3.16
@end example

στο shell. @footnote{
Στο Unix, ο Python 3.x interpreter από προεπιλογή δεν είναι εγκατεστημένος με το εκτελέσιμο αρχείο που ονομάζεται @code{python}, έτσι ώστε να μην έρχεται σε conflict με ένα εκτελέσιμο Python 2.x που εγκαθίσταται ταυτόχρονα.
} Εφόσον η επιλογή του καταλόγου όπου βρίσκεται ο interpreter είναι μια επιλογή εγκατάστασης, και άλλα μέρη είναι πιθανά∙ επικοινωνήστε με τον τοπικό σας guru της Python ή τον διαχειριστή συστήματος.  (π.χ., @code{/usr/local/python} είναι μια δημοφιλής εναλλακτική τοποθεσία.)

Σε μηχανήματα με Windows όπου έχετε εγκαταστήσει την Python από το @ref{21b6,,Microsoft Store}, η εντολή @code{python3.16} θα είναι διαθέσιμη. Εάν έχετε το πρόγραμμα εκκίνησης @ref{9bc,,py.exe launcher} εγκατεστημένο, μπορείτε να χρησιμοποιήσετε την εντολή @code{py}. Βλ. @ref{21b7,,Διαχειριστής εγκατάστασης Python} για άλλους τρόπους εκκίνησης της Python.

Η πληκτρολόγηση ενός χαρακτήρα τέλους αρχείου (@code{Control}-@code{D} στο Unix, @code{Control}-@code{Z} στα Windows) στην κύρια γραμμή εντολών αναγκάζει τον interpreter να βγει με μηδενική κατάσταση εξόδου.  Εάν αυτό δεν λειτουργεί, μπορείτε να βγείτε από τον διερμηνέα πληκτρολογώντας την ακόλουθη εντολή: @code{quit()}.

The interpreter’s line-editing features include interactive editing, history
substitution and code completion on most systems.
Perhaps the quickest check to see whether command line editing is supported is
typing a word in on the Python prompt, then pressing Left arrow (or @code{Control}-@code{b}).
If the cursor moves, you have command line editing; see Appendix
@ref{21b8,,Διαδραστική Επεξεργασία Input και Αντικατάσταση Ιστορικού} for an introduction to the keys.
If nothing appears to happen, or if a sequence like @code{^[[D} or @code{^B} appears,
command line editing isn’t available; you’ll only be able to use
backspace to remove characters from the current line.

Ο interpreter λειτουργεί κάπως όπως το Unix shell: όταν καλείται μια standard είσοδο συνδεδεμένη σε μια συσκευή tty, διαβάζει και εκτελεί εντολές αλληλεπιδραστικά∙ όταν καλείται με ένα όρισμα ονόματος αρχείου ή με ένα αρχείο ως standard είσοδο, διαβάζει και εκτελεί ένα `script' από αυτό το αρχείο.

Ένας δεύτερος τρόπος εκκίνησης του interpreter είναι @code{python -c command [arg] ...}, η οποία εκτελεί τις εντολές στο `command', ανάλογο με την επιλογή @ref{445,,-c} του shell.  Εφόσον οι δηλώσεις Python συχνά περιέχουν κενά διαστήματα ή άλλους χαρακτήρες που είναι ειδικοί για το shell, συνήθως συνίσταται να αναφέρετε το `command' στο σύνολο του.

Ορισμένα Python modules είναι επίσης χρήσιμα ως scripts.  Αυτά μπορούν να κληθούν χρησιμοποιώντας το @code{python -m module [arg] ...}, το οποίο εκτελεί το πηγαίο αρχείο για το `module' σαν να είχατε γράψει το πλήρες όνομα του, στη γραμμή εντολών.

Όταν χρησιμοποιείται ένα script αρχείο, μερικές φορές είναι χρήσιμο να μπορείτε να εκτελέσετε το script και να εισέλθετε σε interactive λειτουργία μετά.  Αυτό μπορεί να γίνει περνώντας το @ref{187d,,-i} πριν από το script.

Όλες οι επιλογές της γραμμής εντολών περιγράφονται στο @ref{1f98,,Command line and environment}.

@menu
* Εισαγωγή Ορίσματος:: 
* Interactive Λειτουργία:: 

@end menu

@node Εισαγωγή Ορίσματος,Interactive Λειτουργία,,Κάνοντας invoke τον Interpreter
@anchor{tutorial/interpreter argument-passing}@anchor{21b9}@anchor{tutorial/interpreter tut-argpassing}@anchor{21ba}
@subsubsection Εισαγωγή Ορίσματος


Όταν είναι γνωστά στον interpreter, το όνομα του script και τα πρόσθετα ορίσματα στην συνέχεια μετατρέπονται σε λίστα συμβολοσειρών και εκχωρούνται στην μεταβλητή @code{argv} στο module @code{sys}.  Μπορείτε να αποκτήσετε πρόσβαση σε αυτήν την λίστα εκτελώντας το @code{import sys}.  Το μήκος της λίστας είναι τουλάχιστον ένα∙ όταν δεν δίνονται script και δεν δίνονται ορίσματα, το @code{sys.argv[0]} είναι μια κενή συμβολοσειρά.  Όταν το όνομα του script δίνεται ως @code{'-'} (που σημαίνει standard είσοδος), το @code{sys.argv[0]} ορίζεται ως @code{'-'}.  Όταν χρησιμοποιείται η `εντολή' @ref{445,,-c}, το @code{sys.argv[0]} ορίζεται σε @code{'-c'}.  Όταν χρησιμοποιείται η `εντολή' @ref{4ca,,-m} , το @code{sys.argv[0]} ορίζεται ως το πλήρες όνομα του module που βρίσκεται. Οι επιλογές που βρέθηκαν μετά την `εντολή'  @code{-c} ή το @code{-m} `module' δεν καταναλώνονται από τον επεξεργαστή επιλογών του interpreter της Python αλλά αφήνονται στο @code{sys.argv} για την εντολή ή το module να το διαχειριστεί.

@node Interactive Λειτουργία,,Εισαγωγή Ορίσματος,Κάνοντας invoke τον Interpreter
@anchor{tutorial/interpreter interactive-mode}@anchor{21bb}@anchor{tutorial/interpreter tut-interactive}@anchor{656}
@subsubsection Interactive Λειτουργία


Όταν διαβάζονται εντολές από ένα tty, ο interpreter λέγεται ότι βρίσκεται σε `interactive λειτουργία'.  Σε αυτή τη λειτουργία υπενθυμίζει την επόμενη εντολή με την `κύρια εντολή', συνήθως τρία σύμβολα μεγαλύτερο (@code{>>>})∙ για τις γραμμές συνέχειας, υπενθυμίζει με τη `δευτερεύουσα εντολή', από προεπιλογή τρεις τελείες (@code{...}). Ο interpreter εκτυπώνει ένα μήνυμα καλωσορίσματος που αναφέρει τον αριθμό έκδοσης και μια ειδοποίηση πνευματικών δικαιωμάτων πριν εκτυπώσει το πρώτο μήνυμα:

@example
$ python3.16
Python 3.16 (default, May 7 2026, 19:03:04)
[GCC 10.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
@end example

@c XXX update for new releases

Απαιτούνται γραμμές συνέχειας όταν εισάγεται μια κατασκευή πολλών γραμμών. Για παράδειγμα ρίξτε μια ματιά σε αυτήν την δήλωση @ref{322,,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

Για περισσότερα σχετικά με την interactive λειτουργία, βλ. @ref{6a0,,Διαδραστική Λειτουργία}.

@node Ο Interpreter και το Περιβάλλον του,,Κάνοντας invoke τον Interpreter,Χρησιμοποιώντας τον Interpreter της Python
@anchor{tutorial/interpreter the-interpreter-and-its-environment}@anchor{21bc}@anchor{tutorial/interpreter tut-interp}@anchor{21bd}
@subsection Ο Interpreter και το Περιβάλλον του


@menu
* Κωδικοποίηση Πηγαίου Κώδικα:: 

@end menu

@node Κωδικοποίηση Πηγαίου Κώδικα,,,Ο Interpreter και το Περιβάλλον του
@anchor{tutorial/interpreter source-code-encoding}@anchor{21be}@anchor{tutorial/interpreter tut-source-encoding}@anchor{21bf}
@subsubsection Κωδικοποίηση Πηγαίου Κώδικα


Από προεπιλογή, τα πηγαία αρχεία Python αντιμετωπίζονται ως κωδικοποιημένα στο UTF-8.  Σε αυτήν την κωδικοποίηση, οι χαρακτήρες των περισσότερων γλωσσών στον κόσμο μπορούν να χρησιμοποιηθούν ταυτόχρονα σε literal συμβολοσειρές, αναγνωριστικά και σχόλια — αν και η τυπική βιβλιοθήκη χρησιμοποιεί μόνο χαρακτήρες ASCII για αναγνωριστικά, μια σύμβαση που πρέπει να ακολουθεί οποιοδήποτε φορητός κώδικας.  Για να εμφανίσει σωστά όλους αυτούς τους χαρακτήρες, το λογισμικό επεξεργασίας σας πρέπει να αναγνωρίσει ότι το αρχείο είναι UTF-8 και πρέπει να χρησιμοποιεί μια γραμματοσειρά που να υποστηρίζει όλους τους χαρακτήρες του αρχείου.

Για να δηλώσετε μια κωδικοποίηση διαφορετική από την προεπιλεγμένη, θα πρέπει να προστεθεί μια ειδική γραμμή σχολίων ως `πρώτη' γραμμή του αρχείου.  Η σύνταξη είναι η εξής:

@example
# -*- coding: encoding -*-
@end example

όπου το `encoding' είναι ένα από τα έγκυρα @ref{1c,,codecs} που υποστηρίζονται από την Python.

Για παράδειγμα, για να δηλώσετε ότι πρόκειται να χρησιμοποιηθεί η κωδικοποίηση Windows-1252 , η πρώτη γραμμή του αρχείου του πηγαίου κώδικα θα πρέπει να είναι:

@example
# -*- coding: cp1252 -*-
@end example

Μια εξαίρεση στον κανόνα `first line' είναι όταν ο πηγαίος κώδικας ξεκινά με μια γραμμή @ref{21c0,,UNIX «shebang»}.  Σε αυτήν την περίπτωση, η δήλωση κωδικοποίησης θα πρέπει να προστεθεί ως δεύτερη γραμμή του αρχείου.  Για παράδειγμα:

@example
#!/usr/bin/env python3
# -*- coding: cp1252 -*-
@end example

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Μία Άτυπη Εισαγωγή στην Python,Περισσότερα εργαλεία Ελέγχου Ροής,Χρησιμοποιώντας τον Interpreter της Python,Οδηγός εκμάθησης Python
@anchor{tutorial/introduction doc}@anchor{21c1}@anchor{tutorial/introduction an-informal-introduction-to-python}@anchor{21c2}@anchor{tutorial/introduction translation-repo}@anchor{21c3}@anchor{tutorial/introduction tut-informal}@anchor{21c4}
@section Μία Άτυπη Εισαγωγή στην Python


Στα ακόλουθα παραδείγματα, η είσοδος και η έξοδος διακρίνονται από την παρουσία ή την απουσία prompts (@ref{69e,,>>>} και @ref{69f,,…}): για να επαναλάβετε το παράδειγμα, πρέπει να πληκτρολογήσετε τα πάντα μετά το prompt, όταν αυτό υπάρχει∙ οι γραμμές που δεν αρχίζουν με prompt είναι έξοδος από τον διερμηνέα. Σημείωση ότι ένα δευτερεύον prompt μόνο του σε μια γραμμή σε ένα παράδειγμα σημαίνει ότι πρέπει να πληκτρολογήσετε μια κενή γραμμή∙ αυτό χρησιμοποιείται για να τερματίσετε μια εντολή πολλών γραμμών.


@geindex # (hash);σχόλιο

Πολλά από τα παραδείγματα σε αυτόν τον οδηγό, ακόμη και αυτά που εισάγονται στο διαδραστικό prompt, περιέχουν σχόλια.  Τα σχόλια στην Python ξεκινούν με τον χαρακτήρα hashtag, @code{#}, και εκτείνονται μέχρι το τέλος της γραμμής.  Ένα σχόλιο μπορεί να εμφανιστεί στην αρχή μιας σειράς ή μετά από κενά διαστήματα ή κώδικα, αλλά όχι μέσα σε μία συμβολοσειρά.  Ένας χαρακτήρας hashtag μέσα σε μία συμβολοσειρά είναι απλώς ένας χαρακτήρας hashtag. Δεδομένου ότι τα σχόλια αποσκοπούν στην αποσαφήνιση του κώδικα και δεν ερμηνεύονται από την Python, μπορούν να παραλείπονται κατά την πληκτρολόγηση παραδειγμάτων.

Μερικά παραδείγματα:

@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
* Χρησιμοποιώντας την Python ως Αριθμομηχανή:: 
* Πρώτα Βήματα Προς Τον Προγραμματισμό:: 

@end menu

@node Χρησιμοποιώντας την Python ως Αριθμομηχανή,Πρώτα Βήματα Προς Τον Προγραμματισμό,,Μία Άτυπη Εισαγωγή στην Python
@anchor{tutorial/introduction tut-calculator}@anchor{21c5}@anchor{tutorial/introduction using-python-as-a-calculator}@anchor{21c6}
@subsection Χρησιμοποιώντας την Python ως Αριθμομηχανή


Ας δοκιμάσουμε μερικές απλές εντολές της Python. Ξεκινήστε τον διερμηνέα και περιμένετε το πρώτο prompt, @code{`>>>`}.  (Δεν θα πάρει πολύ χρόνο.)

@menu
* Αριθμοί:: 
* Κείμενο:: 
* Λίστες:: 

@end menu

@node Αριθμοί,Κείμενο,,Χρησιμοποιώντας την Python ως Αριθμομηχανή
@anchor{tutorial/introduction numbers}@anchor{21c7}@anchor{tutorial/introduction tut-numbers}@anchor{21c8}
@subsubsection Αριθμοί


Ο διερμηνέας λειτουργεί ως μία απλή αριθμομηχανή: μπορείτε να πληκτρολογήσετε μία έκφραση μέσα σε αυτή και εκείνη θα γράψει την τιμή.  Το συντακτικό μίας έκφρασης είναι απλό: οι τελεστές @code{+}, @code{-}, @code{*} και @code{/} μπορούν να χρησιμοποιηθούν για την εκτέλεση αριθμητικών πράξεων∙ οι παρενθέσεις (@code{()}) μπορούν να χρησιμοποιηθούν για ομαδοποίηση. Για παράδειγμα:

@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

Οι ακέραιοι αριθμοί (π.χ. @code{2}, @code{4}, @code{20}) έχουν τον τύπο @ref{326,,int}, οι αριθμοί με δεκαδικά ψηφία (π.χ. @code{5.0}, @code{1.6}) έχουν τον τύπο @ref{327,,float}.  Θα δούμε περισσότερα για τους αριθμητικούς τύπους αργότερα σε αυτόν τον οδηγό.

Η διαίρεση (@code{/}) πάντα επιστρέφει ένα float.  Για να κάνετε @ref{d10,,floor division} (ακέραια διαίρεση) και να πάρετε ένα ακέραιο αποτέλεσμα, μπορείτε να χρησιμοποιήσετε τον τελεστή @code{//} ∙ για να υπολογίσετε το το υπόλοιπο μίας διαίρεσης, χρησιμοποιήστε τον τελεστή @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

Στην Python, είναι εφικτό να χρησιμοποιήσετε τον τελεστή @code{**} για να υπολογίσετε δυνάμεις @footnote{
Δεδομένου ότι το @code{**} έχει μεγαλύτερη προτεραιότητα από το @code{-}, το @code{-3**2} θα ερμηνευτεί ως @code{-(3**2)} και έτσι θα προκύψει @code{-9}.  Για να το αποφύγετε αυτό και να πάρετε @code{9}, μπορείτε να χρησιμοποιήσετε @code{(-3)**2}.
}:

@example
>>> 5 ** 2  # 5 squared
25
>>> 2 ** 7  # 2 to the power of 7
128
@end example

Το σύμβολο της ισότητας (@code{=}) χρησιμοποιείται για την ανάθεση μιας τιμής σε μια μεταβλητή. Στη συνέχεια, δεν εμφανίζεται αποτέλεσμα πριν από το επόμενο διαδραστικό prompt:

@example
>>> width = 20
>>> height = 5 * 9
>>> width * height
900
@end example

Αν μία μεταβλητή δεν έχει «οριστεί» (δεν της έχει αποδοθεί κάποια τιμή), η προσπάθεια χρήσης της θα σας δώσει ένα σφάλμα:

@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

Υπάρχει πλήρης υποστήριξη για δεκαδικά ψηφία∙ τελεστές με τελεστέους μικτού τύπου μετατρέπουν τον ακέραιο τελεστέο σε δεκαδικό:

@example
>>> 4 * 3.75 - 1
14.0
@end example

Στη διαδραστική λειτουργία, η τελευταία εκτυπωμένη έκφραση εκχωρείται στη μεταβλητή @code{_}.  Αυτό σημαίνει ότι όταν χρησιμοποιείτε την Python ως αριθμομηχανή γραφείου, είναι κάπως πιο εύκολο να συνεχίσετε προηγούμενους υπολογισμούς, για παράδειγμα:

@example
>>> tax = 12.5 / 100
>>> price = 100.50
>>> price * tax
12.5625
>>> price + _
113.0625
>>> round(_, 2)
113.06
@end example

Αυτή η μεταβλητή θα πρέπει να αντιμετωπίζεται από τον χρήστη ως μόνο για ανάγνωση.  Μην της αναθέτετε ρητά μια τιμή — θα δημιουργούσατε μια ανεξάρτητη τοπική μεταβλητή με το ίδιο όνομα αποκρύπτοντας την ενσωματωμένη μεταβλητή με τη μαγική της συμπεριφορά.

Εκτός από @ref{326,,int} και @ref{327,,float}, η Python υποστηρίζει και άλλους τύπους αριθμών, όπως @ref{1c2,,Decimal} και @ref{1c3,,Fraction}. Η Python έχει επίσης ενσωματωμένη υποστήριξη για @ref{21c9,,complex numbers} (μιγαδικούς αριθμούς), και χρησιμοποιεί την κατάληξη @code{j} ή @code{J} για να δηλώσει το φανταστικό μέρος (π.χ. @code{3+5j}).

@node Κείμενο,Λίστες,Αριθμοί,Χρησιμοποιώντας την Python ως Αριθμομηχανή
@anchor{tutorial/introduction text}@anchor{21ca}@anchor{tutorial/introduction tut-strings}@anchor{21cb}
@subsubsection Κείμενο


Η Python μπορεί να χειριστεί κείμενο (που αντιπροσωπεύεται από τον τύπο @ref{1df,,str}, τις λεγόμενες «συμβολοσειρές») καθώς και αριθμούς.  Αυτό περιλαμβάνει χαρακτήρες «@code{!}», λέξεις «@code{κουνέλι}», ονόματα «@code{Παρίσι}», προτάσεις «@code{Καλύπτω τα νώτα σου.}», κ.λπ. «@code{Ναι! :)}». Μπορούν να περικλείονται σε μονά εισαγωγικά (@code{'...'}) ή διπλά εισαγωγικά (@code{"..."}) με το ίδιο αποτέλεσμα @footnote{
Σε αντίθεση με άλλες γλώσσες, οι ειδικοί χαρακτήρες όπως το @code{\n} έχουν την ίδια σημασία τόσο με απλά (@code{'...'}) όσο και με διπλά (@code{"..."}) εισαγωγικά. Η μόνη διαφορά μεταξύ των δύο είναι ότι μέσα σε απλά εισαγωγικά δεν χρειάζεται να αποφύγετε το @code{"} (αλλά πρέπει να αποφύγετε το @code{\'}) και το αντίστροφο.
}.

@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

Για να προσθέσουμε ένα εισαγωγικό, πρέπει να το «κάνουμε escape», προτάσσοντάς του μία @code{\}. Εναλλακτικά, μπορούμε να χρησιμοποιήσουμε τον άλλο τύπο εισαγωγικών:

@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

Στο shell της Python, ο ορισμός συμβολοσειράς και η συμβολοσειρά εξόδου μπορεί να μοιάζουν διαφορετικά.  Η συνάρτηση @ref{131f,,print()} παράγει μια πιο ευανάγνωστη έξοδο, παραλείποντας τα εισαγωγικά που περικλείουν την συμβολοσειρά και εκτυπώνοντας escaped και ειδικούς χαρακτήρες:

@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

Εάν δεν θέλετε οι χαρακτήρες που προηγούνται από μία @code{\} να ερμηνεύονται ως ειδικοί χαρακτήρες, μπορείτε να χρησιμοποιήσετε `ακατέργαστες συμβολοσειρές' προσθέτοντας ένα @code{r} πριν από το πρώτο εισαγωγικό:

@example
>>> print('C:\this\name')  # here \t means tab, \n means newline
C:      his
ame
>>> print(r'C:\this\name')  # note the r before the quote
C:\this\name
@end example

Υπάρχει μια δυσδιάκριτη πτυχή στις ακατέργαστες συμβολοσειρές: μια ακατέργαστη συμβολοσειρά δεν μπορεί να τελειώνει σε περιττό αριθμό χαρακτήρων @code{\}” δείτε @ref{21cc,,το λήμμα των Συχνών Ερωτήσεων} για περισσότερες πληροφορίες και λύσεις.

Οι συμβολοσειρές κυριολεξίας μπορούν να καλύπτουν πολλές γραμμές.  Ένας τρόπος είναι χρησιμοποιώντας τριπλά εισαγωγικά: @code{"""..."""} ή @code{'@w{'}'...'@w{'}'}.  Οι χαρακτήρες στο τέλος των γραμμών συμπεριλαμβάνονται αυτόματα στην συμβολοσειρά, αλλά είναι εφικτό να το αποτρέψετε αυτό προσθέτοντας μία @code{\} στο τέλος της γραμμής.  Στο ακόλουθο παράδειγμα, η αρχική νέα γραμμή δεν περιλαμβάνεται:

@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

Οι συμβολοσειρές μπορούν να συνδεθούν (κολληθούν η μία στην άλλη) με τον τελεστή @code{+}, και να επαναληφθούν με τον τελεστή @code{*}:

@example
>>> # 3 times 'un', followed by 'ium'
>>> 3 * 'un' + 'ium'
'unununium'
@end example

Δύο ή παραπάνω `συμβολοσειρές' (που περικλείονται σε εισαγωγικά) η μία δίπλα στην άλλη συνδέονται αυτόματα.

@example
>>> 'Py' 'thon'
'Python'
@end example

Αυτή η λειτουργία είναι ιδιαίτερα χρήσιμη όταν θέλετε να σπάσετε μεγάλες συμβολοσειρές:

@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

Ωστόσο, αυτό λειτουργεί μόνο με κυριολεκτικές συμβολοσειρές, όχι με μεταβλητές ή εκφράσεις:

@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

Αν θέλετε να συνδέσετε μεταβλητές ή μία μεταβλητή και μία κυριολεκτική συμβολοσειρά, χρησιμοποιήστε το @code{+}:

@example
>>> prefix + 'thon'
'Python'
@end example

Οι συμβολοσειρές μπορούν να είναι `προσπελάσιμες' (μέσω ευρετηρίου), με τον πρώτο χαρακτήρα να έχει τον δείκτη 0. Δεν υπάρχει ξεχωριστός τύπος για χαρακτήρες∙ ένας χαρακτήρας είναι απλώς μία συμβολοσειρά με μέγεθος ένα:

@example
>>> word = 'Python'
>>> word[0]  # character in position 0
'P'
>>> word[5]  # character in position 5
'n'
@end example

Οι δείκτες μπορούν να είναι και αρνητικοί αριθμοί, για να ξεκινήσετε την αρίθμηση από τα δεξιά:

@example
>>> word[-1]  # last character
'n'
>>> word[-2]  # second-last character
'o'
>>> word[-6]
'P'
@end example

Σημειώστε ότι αφού το -0 είναι το ίδιο με το 0, οι αρνητικοί δείκτες ξεκινούν από το -1.

Εκτός από την ευρετηρίαση, υποστηρίζεται επίσης ο `τεμαχισμός'.  Ενώ η ευρετηρίαση χρησιμοποιείται για την απόκτηση μεμονομένων χαρακτήρων, ο `τεμαχισμός' σας επιτρέπει να αποκτήσετε ένας μέρος της συμβολοσειράς:

@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

Οι δείκτες ενός τεμαχισμού έχουν χρήσιμες προεπιλογές∙ η παράλειψη του πρώτου δείκτη έχει ως προεπιλογή το μηδέν, η παράλειψη του δεύτερου δείκτη έχει ως προεπιλογή το μέγεθος της συμβολοσειράς που τεμαχίζεται.

@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

Προσέξτε πώς η αρχή περιλαμβάνεται πάντα, ενώ το τέλος πάντα εξαιρείται.  Αυτό εξασφαλίζει ότι το @code{s[:i] + s[i:]} είναι πάντα ίσο με @code{s}:

@example
>>> word[:2] + word[2:]
'Python'
>>> word[:4] + word[4:]
'Python'
@end example

Ένας τρόπος να θυμάστε πώς λειτουργούν οι τεμαχισμοί είναι να σκεφτείτε ότι οι δείκτες δείχνουν `μεταξύ' χαρακτήρων, με το αριστερό άκρο του πρώτου χαρακτήρα να αριθμείται με 0. Τότε το δεξιό άκρο του τελευταίου χαρακτήρα μιας συμβολοσειράς `ν' χαρακτήρων έχει δείκτη `ν', για παράδειγμα:

@example
 +---+---+---+---+---+---+
 | P | y | t | h | o | n |
 +---+---+---+---+---+---+
 0   1   2   3   4   5   6
-6  -5  -4  -3  -2  -1
@end example

Η πρώτη σειρά αριθμών δίνει τη θέση των δεικτών 0…6 στην συμβολοσειρά∙ η δεύτερη σειρά δίνει τους αντίστοιχους αρνητικούς δείκτες. Ο τεμαχισμός από `i' έως `j' αποτελείται από όλους τους χαρακτήρες μεταξύ των άκρων με ετικέτες `i' και `j', αντίστοιχα.

Για μη αρνητικούς δείκτες, το μήκος ενός τεμαχισμού είναι η διαφορά των δεικτών, εάν και οι δύο είναι εντός των ορίων.  Για παράδειγμα, το μήκος του @code{word[1:3]} είναι 2.

Η απόπειρα χρήσης ενός πολύ μεγάλου δείκτη θα οδηγήσει σε σφάλμα:

@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

Ωστόσο, οι δείκτες εκτός εύρους αντιμετωπίζονται χωρίς σφάλμα όταν χρησιμοποιούνται για τεμαχισμούς:

@example
>>> word[4:42]
'on'
>>> word[42:]
'@w{'}
@end example

Οι συμβολοσειρές της Python δεν μπορούν να αλλάξουν — είναι @ref{181,,immutable}. Επομένως, η ανάθεση σε μια συγκεκριμένη θέση στη συμβολοσειρά οδηγεί σε σφάλμα:

@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

Εάν χρειάζεστε μια διαφορετική συμβολοσειρά, θα πρέπει να δημιουργήσετε μια νέα:

@example
>>> 'J' + word[1:]
'Jython'
>>> word[:2] + 'py'
'Pypy'
@end example

Η ενσωματωμένη συνάρτηση @ref{a1f,,len()} επιστρέφει το μήκος μιας συμβολοσειράς:

@example
>>> s = 'supercalifragilisticexpialidocious'
>>> len(s)
34
@end example


@subsubheading Δείτε επίσης



@table @asis

@item @ref{21cd,,Τύπος Ακολουθίας (Sequence) Κειμένου — str}

Οι συμβολοσειρές είναι παραδείγματα `τύπων ακολουθίας' και υποστηρίζουν τις κοινές πράξεις που υποστηρίζονται από τέτοιους τύπους.

@item @ref{21ce,,Μέθοδοι Συμβολοσειράς (String)}

Οι συμβολοσειρές υποστηρίζουν έναν μεγάλο αριθμό μεθόδων για βασικούς μετασχηματισμούς και αναζήτηση.

@item @ref{43a,,f-strings}

Κυριολεκτικές συμβολοσειρές που έχουν ενσωματωμένες εκφράσεις.

@item @ref{173f,,Format string syntax}

Πληροφορίες σχετικά με τη μορφοποίηση συμβολοσειρών με τη μέθοδο @ref{a12,,str.format()}.

@item @ref{ab9,,printf-style String Formatting}

Οι παλιές λειτουργίες μορφοποίησης που καλούνται όταν οι συμβολοσειρές είναι ο αριστερός τελεστέος του τελεστή @code{%} περιγράφονται λεπτομερέστερα εδώ.
@end table


@node Λίστες,,Κείμενο,Χρησιμοποιώντας την Python ως Αριθμομηχανή
@anchor{tutorial/introduction lists}@anchor{21cf}@anchor{tutorial/introduction tut-lists}@anchor{21d0}
@subsubsection Λίστες


Η Python γνωρίζει έναν αριθμό `σύνθετων' τύπων δεδομένων, που χρησιμοποιούνται για την ομαδοποίηση άλλων τιμών.  Ο πιο ευέλικτος είναι ο τύπος `λίστα', ο οποίος μπορεί να γραφτεί ως μια λίστα διαχωρισμένων με κόμμα τιμών (στοιχείων) ανάμεσα σε τετράγωνες αγκύλες.  Οι λίστες μπορεί να περιέχουν στοιχεία διαφορετικών τύπων, αλλά συνήθως όλα τα στοιχεία έχουν τον ίδιο τύπο.

@example
>>> squares = [1, 4, 9, 16, 25]
>>> squares
[1, 4, 9, 16, 25]
@end example

Όπως οι συμβολοσειρές (και όλοι οι άλλοι ενσωματωμένοι τύποι @ref{8ff,,sequence}), οι λίστες μπορούν να δεικτοδοτηθούν και να τεμαχιστούν:

@example
>>> squares[0]  # indexing returns the item
1
>>> squares[-1]
25
>>> squares[-3:]  # slicing returns a new list
[9, 16, 25]
@end example

Οι λίστες υποστηρίζουν επίσης λειτουργίες όπως σύνδεση:

@example
>>> squares + [36, 49, 64, 81, 100]
[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
@end example

Σε αντίθεση με τις συμβολοσειρές, οι οποίες είναι @ref{181,,immutable}, οι λίστες είναι @ref{21d1,,mutable} τύπος, δηλαδή είναι δυνατόν να αλλάξετε το περιεχόμενό τους:

@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

Μπορείτε επίσης να προσθέσετε νέα στοιχεία στο τέλος της λίστας, χρησιμοποιώντας @ref{aba,,list.append()} `μέθοδο' (θα δούμε περισσότερα για τις μεθόδους αργότερα):

@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

Η απλή ανάθεση στην Python δεν αντιγράφει ποτέ δεδομένα. Όταν αναθέτετε μια λίστα σε μια μεταβλητή, η μεταβλητή αναφέρεται στην `υπάρχουσα λίστα'. Οποιεσδήποτε αλλαγές κάνετε στη λίστα μέσω μιας μεταβλητής θα γίνουν αντιληπτές από όλες τις άλλες μεταβλητές που αναφέρονται σε αυτήν:

@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

Όλοι οι τεμαχισμοί επιστρέφουν μια νέα λίστα που περιέχει τα ζητούμενα στοιχεία.  Αυτό σημαίνει ότι ο ακόλουθος τεμαχισμός επιστρέφει ένα @ref{21d2,,shallow copy} (ρηχό αντίγραφο) της λίστας:

@example
>>> correct_rgba = rgba[:]
>>> correct_rgba[-1] = "Alpha"
>>> correct_rgba
["Red", "Green", "Blue", "Alpha"]
>>> rgba
["Red", "Green", "Blue", "Alph"]
@end example

Η ανάθεση σε τεμαχισμούς είναι επίσης δυνατή, και αυτό μπορεί ακόμη και να αλλάξει το μέγεθος της λίστας ή να τη διαγράψει εντελώς:

@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

Η ενσωματωμένη συνάρτηση @ref{a1f,,len()} εφαρμόζεται επίσης στις λίστες:

@example
>>> letters = ['a', 'b', 'c', 'd']
>>> len(letters)
4
@end example

Είναι δυνατό να εμφωλεύσετε λίστες (να δημιουργήσετε λίστες που περιέχουν άλλες λίστες), για παράδειγμα:

@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 Πρώτα Βήματα Προς Τον Προγραμματισμό,,Χρησιμοποιώντας την Python ως Αριθμομηχανή,Μία Άτυπη Εισαγωγή στην Python
@anchor{tutorial/introduction first-steps-towards-programming}@anchor{21d3}@anchor{tutorial/introduction tut-firststeps}@anchor{21d4}
@subsection Πρώτα Βήματα Προς Τον Προγραμματισμό


Φυσικά, μπορούμε να χρησιμοποιήσουμε την Python για πιο περίπλοκες εργασίες από την πρόσθεση δύο και δύο μαζί.  Για παράδειγμα, μπορούμε να γράψουμε μια αρχική υπο-σειρά της Σειράς Fibonacci@footnote{https://en.wikipedia.org/wiki/Fibonacci_sequence} ως ακολουθεί:

@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

Αυτό το παράδειγμα εισάγει διάφορα νέα χαρακτηριστικά.


@itemize *

@item 
Η πρώτη γραμμή περιέχει μια `πολλαπλή ανάθεση': οι μεταβλητές @code{a} και @code{b} παίρνουν ταυτόχρονα τις νέες τιμές 0 και 1. Στην τελευταία γραμμή αυτό χρησιμοποιείται ξανά, αποδεικνύοντας ότι οι εκφράσεις στη δεξιά πλευρά αξιολογούνται όλες πρώτα πριν γίνει οποιαδήποτε ανάθεση.  Οι εκφράσεις στην δεξιά πλευρά αξιολογούνται  από αριστερά προς τα δεξιά.

@item 
Ο βρόχος @ref{1b86,,while} εκτελείται όσο η συνθήκη (εδώ: @code{a < 10}) παραμένει αληθής.  Στην Python, όπως και στη C, οποιαδήποτε μη μηδενική ακέραια τιμή είναι αληθής, το μηδέν είναι ψευδές.  Η συνθήκη μπορεί επίσης να είναι μια συμβολοσειρά ή μια λίστα, στην πραγματικότητα οποιαδήποτε ακολουθία∙ οτιδήποτε με μη μηδενικό μήκος είναι αληθές, κενές ακολουθίες είναι ψευδείς.  Το τεστ που χρησιμοποιείται στο παράδειγμα είναι μια απλή σύγκριση.  Οι τυπικοί τελεστές σύγκρισης γράφονται όπως στη C: @code{<} (μικρότερο από), @code{>} (μεγαλύτερο από), @code{==} (ίσο με), @code{<=} (μικρότερο ή ίσο με), @code{>=} (μεγαλύτερο ή ίσο με) και @code{!=} (μη ίσο με).

@item 
Στο `σώμα' του βρόχου υπάρχει `εσοχή': η εσοχή είναι ο τρόπος της Python να ομαδοποιεί εντολές.  Στο διαδραστικό prompt, πρέπει να πληκτρολογήσετε ένα tab ή κενό(α) για κάθε γραμμή με εσοχή.  Στην πράξη θα προετοιμάσετε πιο περίπλοκες εισαγωγές για την Python με έναν επεξεργαστή κειμένου∙ όλοι οι αξιοπρεπείς επεξεργαστές κειμένου διαθέτουν την δυνατότητα αυτόματης εσοχής.  Όταν εισάγεται μια σύνθετη εντολή διαδραστικά, πρέπει να ακολουθείται από μια κενή γραμμή για να υποδηλώνει την ολοκλήρωση (αφού ο συντακτικός αναλυτής δεν μπορεί να μαντέψει πότε πληκτρολογήσατε την τελευταία γραμμή).  Σημείωση ότι κάθε γραμμή μέσα σε ένα βασικό μπλοκ πρέπει να έχει την ίδια εσοχή.

@item 
Η συνάρτηση @ref{131f,,print()} γράφει την τιμή του(των) ορίσματος(ων) που της δίνεται. Διαφέρει από το να γράφετε απλώς την έκφραση που θέλετε να γράψετε (όπως κάναμε νωρίτερα στα παραδείγματα της αριθμομηχανής) στον τρόπο με τον οποίο χειρίζεται πολλαπλά ορίσματα, αριθμούς με δεκαδικά ψηφία και συμβολοσειρές.  Οι συμβολοσειρές εκτυπώνονται χωρίς εισαγωγικά, και ένα κενό παρεμβάλλεται μεταξύ των στοιχείων, ώστε να μπορείτε να μορφοποιήσετε τα πράγματα όμορφα, όπως εδώ:

@example
>>> i = 256*256
>>> print('The value of i is', i)
The value of i is 65536
@end example

Το όρισμα-κλειδί `end' μπορεί να χρησιμοποιηθεί για την αποφυγή της νέας γραμμής μετά την έξοδο, ή για να τελειώσετε την έξοδο με μια διαφορετική συμβολοσειρά:

@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 Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Περισσότερα εργαλεία Ελέγχου Ροής,Δομές Δεδομένων,Μία Άτυπη Εισαγωγή στην Python,Οδηγός εκμάθησης Python
@anchor{tutorial/controlflow doc}@anchor{21d5}@anchor{tutorial/controlflow more-control-flow-tools}@anchor{21d6}@anchor{tutorial/controlflow translation-repo}@anchor{21d7}@anchor{tutorial/controlflow tut-morecontrol}@anchor{21d8}
@section Περισσότερα εργαλεία Ελέγχου Ροής


Εκτός από τη πρόταση @ref{1b86,,while} που μόλις εισήχθη, η Python χρησιμοποιεί μερικές ακόμη που θα συναντήσουμε σε αυτό το κεφάλαιο.

@menu
* Προτάσεις if:: 
* Προτάσεις for:: 
* Η συνάρτηση range(): Η συνάρτηση range. 
* break και continue Προτάσεις:: 
* else Ρήτρες στους βρόχους:: 
* Προτάσεις pass:: 
* Προτάσεις match:: 
* Καθορισμός Συναρτήσεων:: 
* Περισσότερο για τον Καθορισμό Συναρτήσεων:: 
* Intermezzo; Στυλ Κώδικα: Intermezzo Στυλ Κώδικα. 

@end menu

@node Προτάσεις if,Προτάσεις for,,Περισσότερα εργαλεία Ελέγχου Ροής
@anchor{tutorial/controlflow if-statements}@anchor{21d9}@anchor{tutorial/controlflow tut-if}@anchor{21da}
@subsection Προτάσεις @code{if}


Ίσως ο πιο γνωστός τύπος statement είναι η πρόταση @ref{322,,if}.  Για παράδειγμα:

@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

Μπορεί να υπάρχουν μηδέν ή περισσότερα μέρη @ref{425,,elif} και το τμήμα @ref{320,,else} είναι προαιρετικό.  To keyword “@code{elif}” είναι συντομογραφία του “else if”, και είναι χρήσιμη για να αποφύγετε την υπερβολική εσοχή.  Μια ακολουθία @code{if} … @code{elif} … @code{elif} … είναι υποκατάστατο των δηλώσεων @code{switch} ή @code{case} που υπάρχουν σε άλλες γλώσσες.

Εάν συγκρίνετε την ίδια τιμή με πολλές σταθερές ή ελέγχετε για συγκεκριμένους τύπους ή χαρακτηριστικά, μπορεί επίσης να βρείτε χρήσιμη τη δήλωση @code{match} Για περισσότερες λεπτομέρειες, ανατρέξτε στο @ref{21db,,Προτάσεις match}.

@node Προτάσεις for,Η συνάρτηση range,Προτάσεις if,Περισσότερα εργαλεία Ελέγχου Ροής
@anchor{tutorial/controlflow for-statements}@anchor{21dc}@anchor{tutorial/controlflow tut-for}@anchor{21dd}
@subsection Προτάσεις @code{for}


@geindex statement;for

Η δήλωση @ref{321,,for} στην Python διαφέρει λίγο από αυτό που μπορεί να έχετε συνηθίσει στη C ή στην Pascal.  Αντί να επαναλαμβάνετε πάντα μια αριθμητική πρόοδο αριθμών (όπως στη Pascal) ή να δίνετε στον χρήστη τη δυνατότητα να ορίσει τόσο το βήμα επανάληψης όσο και τη συνθήκη διακοπής (όπως C),η δήλωση της Python @code{for} επαναλαμβάνεται πάνω από τα στοιχεία οποιασδήποτε ακολουθίας (λίστας ή συμβολοσειράς), με τη σειρά που εμφανίζονται στην ακολουθία.  Για παράδειγμα (χωρίς λογοπαίγνιο):

@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

Ο κώδικας που τροποποιεί μια συλλογή ενώ επαναλαμβάνεται πάνω από την ίδια συλλογή μπορεί να είναι δύσκολος για να γίνει σωστός.  Αντίθετα, είναι συνήθως πιο απλό να κάνετε loop πάνω από ένα αντίγραφο συλλογής ή να δημιουργήσετε μια νέα συλλογή:

@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 Η συνάρτηση range,break και continue Προτάσεις,Προτάσεις for,Περισσότερα εργαλεία Ελέγχου Ροής
@anchor{tutorial/controlflow the-range-function}@anchor{21de}@anchor{tutorial/controlflow tut-range}@anchor{21df}
@subsection Η συνάρτηση @code{range()}


Εάν χρειάζεται να κάνετε επανάληψη σε μια ακολουθία αριθμών, η ενσωματωμένη (built-in) συνάρτηση @ref{d0f,,range()} είναι χρήσιμη.  Δημιουργεί αριθμητικές προόδους:

@example
>>> for i in range(5):
...     print(i)
...
0
1
2
3
4
@end example

Το δεδομένο τελικό σημείο δεν αποτελεί ποτέ μέρος της παραγόμενης ακολουθίας· το @code{range(10)} δημιουργεί 10 τιμές, τους δείκτες για στοιχεία μιας ακολουθίας μήκους 10.  Είναι δυνατόν να αφήσουμε το εύρος να ξεκινά από άλλο αριθμό ή για να καθορίσετε μια διαφορετική προσαύξηση (ακόμη και αρνητική, μερικές φορές αυτό ονομάζεται “βήμα”):

@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

Για να γίνουν iterate οι δείκτες μια ακολουθίας, μπορείτε να συνδυάσετε τις @ref{d0f,,range()} και @ref{a1f,,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

Στις περισσότερες τέτοιες περιπτώσεις, ωστόσο, είναι βολικό να χρησιμοποιήσετε τη συνάρτηση @ref{1823,,enumerate()}, δείτε @ref{21e0,,Τεχνικές Looping}.

Ένα περίεργο πράγμα συμβαίνει αν απλώς εκτυπώσετε ένα range:

@example
>>> range(10)
range(0, 10)
@end example

Με πολλούς τρόπους το αντικείμενο που επιστρέφεται από το @ref{d0f,,range()} συμπεριφέρεται σαν να είναι μια λίστα, αλλά στην πραγματικότητα δεν είναι. Είναι ένα αντικείμενο που επιστρέφει τα διαδοχικά στοιχεία της επιθυμητής ακολουθίας όταν κάνετε επανάληψη πάνω του, αλλά δεν μπαίνει πραγματικά στη λίστα, εξοικονομώντας έτσι χώρο.

Λέμε ότι ένα τέτοιο αντικείμενο είναι @ref{15ce,,iterable}, δηλαδή, κατάλληλο ως στόχος για συναρτήσεις και κατασκευές που περιμένουν κάτι από το οποίο μπορούν να λάβουν διαδοχικά στοιχεία μέχρι να εξαντληθεί η προσφορά.  Είδαμε ότι η δήλωση @ref{321,,for} είναι μια τέτοια κατασκευή, ενώ ένα παράδειγμα συνάρτησης που παίρνει ένα iterable είναι η @ref{881,,sum()}:

@example
>>> sum(range(4))  # 0 + 1 + 2 + 3
6
@end example

Later we will see more functions that return iterables and take iterables as
arguments.  In chapter @ref{21e1,,Δομές Δεδομένων}, we will discuss @ref{4d9,,list()} in more
detail.

@node break και continue Προτάσεις,else Ρήτρες στους βρόχους,Η συνάρτηση range,Περισσότερα εργαλεία Ελέγχου Ροής
@anchor{tutorial/controlflow break-and-continue-statements}@anchor{21e2}@anchor{tutorial/controlflow tut-break}@anchor{21e3}
@subsection @code{break} και @code{continue} Προτάσεις


Η δήλωση @ref{428,,break} ξεφεύγει από τον πιο εσωτερικό βρόχο @ref{321,,for} ή @ref{1b86,,while}:

@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

Η δήλωση @ref{429,,continue} συνεχίζεται με την επόμενη επανάληψη του βρόχου:

@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{21e4}
@node else Ρήτρες στους βρόχους,Προτάσεις pass,break και continue Προτάσεις,Περισσότερα εργαλεία Ελέγχου Ροής
@anchor{tutorial/controlflow break-and-continue-statements-and-else-clauses-on-loops}@anchor{21e5}@anchor{tutorial/controlflow else-clauses-on-loops}@anchor{21e6}
@subsection @code{else} Ρήτρες στους βρόχους


Σε έναν βρόχο @code{for} ή @code{while} η πρόταση @code{break} μπορεί να συνδυαστεί με μια πρόταση @code{else}.  Εάν ο βρόχος τελειώσει χωρίς να εκτελεστεί η @code{break}, εκτελείται ο όρος @code{else}.

Σε έναν βρόχο @ref{321,,for}, η πρόταση @code{else} εκτελείται αφού ο βρόχος ολοκληρώσει στην τελική του επανάληψη, δηλαδή αν δεν σημειωθεί διάλειμμα.

Σε έναν βρόχο @ref{1b86,,while}, εκτελείται αφού η συνθήκη του βρόχου είναι ψευδής.

Σε οποιοδήποτε είδος βρόχου, η πρόταση @code{else} `δεν' εκτελείται εάν ο βρόχος τερματίστηκε με μια λέξη @ref{428,,break}.  Φυσικά, άλλοι τρόποι για να τερματίσετε νωρίς τον βρόχο, όπως ένα @ref{44b,,return} ή μια αυξημένη εξαίρεση, θα παρακάμψουν επίσης την εκτέλεση της πρότασης @ref{320,,else}.

Αυτό αποδεικνύεται στον ακόλουθο βρόχο @code{for}, που αναζητά πρώτους αριθμούς:

@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

(Ναι, αυτός είναι ο σωστός κώδικας.  Κοιτάξτε προσεκτικά: η πρόταση @code{else} ανήκει στον βρόχο @code{for}, `όχι' στη δήλωση @cite{if}.)

Ένας τρόπος για να σκεφτούμε την ρήτρα else είναι να τη φανταστούμε σε σύζευξη με το @code{if} μέσα στον βρόχο.  Καθώς εκτελείται ο βρόχος, θα εκτελέσει μια ακολουθία όπως if/if/if/else. Το @code{if} βρίσκεται μέσα στον βρόχο, συναντάται πολλές φορές. Εάν η συνθήκη είναι ποτέ αληθής, θα συμβεί @code{break}. Εάν η συνθήκη δεν είναι ποτέ αληθής, θα εκτελεστεί ο όρος @code{else} εκτός του βρόχου.

Όταν χρησιμοποιείται με έναν βρόχο, η πρόταση @code{else} έχει περισσότερα κοινά με την πρόταση @code{else} μιας πρότασης @ref{ad6,,try} παρά με αυτήν των statements @code{if} η πρόταση @code{else} μιας @code{try} εκτελείται όταν δεν υπάρχει εξαίρεση, και η πρόταση @code{else} ενός βρόχου εκτελείται όταν δεν υπάρχει @code{break}. Για περισσότερα με τη δήλωση @code{try} και τις εξαιρέσεις, δείτε @ref{21e7,,Διαχείριση Εξαιρέσεων}.

@geindex ...;ellipsis literal

@node Προτάσεις pass,Προτάσεις match,else Ρήτρες στους βρόχους,Περισσότερα εργαλεία Ελέγχου Ροής
@anchor{tutorial/controlflow pass-statements}@anchor{21e8}@anchor{tutorial/controlflow tut-pass}@anchor{21e9}
@subsection Προτάσεις @code{pass}


Η δήλωση @ref{427,,pass} δεν κάνει τίποτα. Μπορεί να χρησιμοποιηθεί όταν απαιτείται συντακτικά μια πρόταση, αλλά το πρόγραμμα δεν απαιτεί καμία ενέργεια. Για παράδειγμα:

@example
>>> while True:
...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
...
@end example

Αυτό χρησιμοποιείται συνήθως για τη δημιουργία ελάχιστων κλάσεων:

@example
>>> class MyEmptyClass:
...     pass
...
@end example

Ένα άλλο μέρος @ref{427,,pass} που μπορεί να χρησιμοποιηθεί είναι ως place-holder για μια συνάρτηση ή το σώμα υπό όρους όταν εργάζεστε σε νέο κώδικα, επιτρέποντας σας να συνεχίσετε να σκέφτεστε σε ένα πιο αφηρημένο επίπεδο.  Το @code{pass} αγνοείται σιωπηλά:

@example
>>> def initlog(*args):
...     pass   # Remember to implement this!
...
@end example

Για αυτήν την τελευταία περίπτωση, πολλοί άνθρωποι χρησιμοποιούν το literale αποσιωπητικών @code{...} αντί για @code{pass}. Αυτή η χρήση δεν έχει ειδική σημασία για την Python και δεν αποτελεί μέρος του ορισμού της γλώσσας (θα μπορούσατε να χρησιμοποιήσετε οποιαδήποτε σταθερή έκφραση εδώ), αλλά το @code{...} χρησιμοποιείται συμβατικά και ως σώμα placeholder. Δείτε @ref{21ea,,Το αντικείμενο Ellipsis}.

@node Προτάσεις match,Καθορισμός Συναρτήσεων,Προτάσεις pass,Περισσότερα εργαλεία Ελέγχου Ροής
@anchor{tutorial/controlflow match-statements}@anchor{21eb}@anchor{tutorial/controlflow tut-match}@anchor{21db}
@subsection Προτάσεις @code{match}


Μια δήλωση @ref{1d4,,match} παίρνει μια έκφραση και συγκρίνει την τιμή της με διαδοχικά μοτίβα που δίνονται ως ένα ή περισσότερα μπλοκ πεζών-κεφαλαίων.  Αυτή είναι επιφανειακά παρόμοια με μια πρόταση switch στην C, Java ή JavaScript (και πολλές άλλες γλώσσες), αλλά είναι πιο παρόμοια με την αντιστοίχιση προτύπων σε γλώσσες όπως η Rust ή η Haskell. Εκτελείται μόνο το πρώτο μοτίβο που ταιριάζει και μπορεί επίσης να εξαγάγει στοιχεία (στοιχεία ακολουθίας ή ιδιότητες αντικειμένου) από την τιμή σε μεταβλητές. Εάν καμία περίπτωση δεν ταιριάζει, κανένας από τους κλάδους δεν εκτελείται.

Η απλούστερη φόρμα συγκρίνει μια τιμή θέματος με ένα ή περισσότερα literals:

@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

Σημειώστε το τελευταίο μπλοκ: το «variable name» @code{_} λειτουργεί ως `μπαλαντέρ' και δεν αποτυγχάνει ποτέ να ταιριάζει.

Μπορείτε να συνδυάσετε πολλά γράμματα σε ένα μόνο μοτίβο χρησιμοποιώντας το @code{|} («ή»):

@example
case 401 | 403 | 404:
    return "Not allowed"
@end example

Τα μοτίβα μπορεί να μοιάζουν με αναθέσεις unpacking, και μπορούν να χρησιμοποιηθούν για τη σύνδεση μεταβλητών:

@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

Μελετήστε το ένα προσεκτικά!  Το πρώτο μοτίβο έχει δύο literals, και μπορεί να θεωρηθεί ως επέκταση του literal μοτίβου που φαίνεται παραπάνω.  Αλλά τα επόμενα δύο μοτίβα συνδυάζουν ένα literal σε μια μεταβλητή, και η μεταβλητή `δεσμεύει' μια τιμή από το θέμα (@code{point}).  Το τέταρτο μοτίβο συλλαμβάνει δύο τιμές, γεγονός που το κάνει εννοιολογικά παρόμοιο με την ανάθεση unpacking @code{(x, y) = point}.

Εάν χρησιμοποιείτε κλάσεις για τη δομή των δεδομένων σας, μπορείτε να χρησιμοποιήσετε το όνομα της κλάσης ακολουθούμενο από μια λίστα ορισμάτων που μοιάζει με έναν κατασκευαστή, αλλά με τη δυνατότητα να συλλαμβάνει χαρακτηριστικά σε μεταβλητές:

@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

Μπορείτε να χρησιμοποιήσετε παραμέτρους θέσης με ορισμένες ενσωματωμένες κλάσεις που παρέχουν μια σειρά για τα χαρακτηριστικά τους (π.χ. κλάσεις δεδομένων). Μπορείτε επίσης να ορίσετε μια συγκεκριμένη θέση για χαρακτηριστικά σε μοτίβα, ορίζοντας το ειδικό χαρακτηριστικό @code{__match_args__} στις κλάσεις σας. Εάν έχει οριστεί σε («x», «y»), τα ακόλουθα μοτίβα είναι όλα ισοδύναμα (και όλα δεσμεύουν το χαρακτηριστικό @code{y} στη μεταβλητή @code{var}):

@example
Point(1, var)
Point(1, y=var)
Point(x=1, y=var)
Point(y=var, x=1)
@end example

Ένας συνιστώμενος τρόπος για να διαβάσετε τα μοτίβα είναι να τα δείτε ως μια εκτεταμένη μορφή αυτού που θα βάλετε στα αριστερά μιας ανάθεσης, για να κατανοήσετε ποιες μεταβλητές θα οριστούν σε τι. Μόνο τα ανεξάρτητα ονόματα (όπως @code{var} παραπάνω) εκχωρούνται από μια δήλωση αντιστοίχισης. Ονόματα με κουκκίδες (όπως @code{foo.bar}), ονόματα χαρακτηριστικών (τα @code{x=} και @code{y=} παραπάνω) ή ονόματα κλάσεων (αναγνωρίζονται από το «(…)» που βρίσκεται δίπλα όπως το @code{Point} παραπάνω) δεν ανατίθενται ποτέ.

Τα μοτίβα μπορούν να είναι αυθαίρετα ένθετα.  Για παράδειγμα, εάν έχουμε μια σύντομη λίστα με πόντους, με προσθήκη @code{__match_args__}, θα μπορούσαμε να την αντιστοιχίσουμε ως εξής:

@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

Μπορούμε να προσθέσουμε μια πρόταση @code{if} σε ένα μοτίβο, γνωστό ως «guard».  Εάν το guard είναι false, το @code{match} συνεχίζει για να δοκιμάσει το επόμενο μπλοκ πεζών-κεφαλαίων.  Λάβετε υπόψη ότι η σύλληψη της τιμής γίνεται πριν ο guard αξιολογηθεί:

@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

Πολλά άλλα βασικά χαρακτηριστικά αυτής της δήλωσης:


@itemize -

@item 
Όπως το unpacking αναθέσεων, τα μοτίβα πλειάδας (tuple) και λίστας έχουν ακριβώς την ίδια σημασία και ταιριάζουν πραγματικά με αυθαίρετες ακολουθίες.  Μια σημαντική εξαίρεση είναι ότι δεν ταιριάζουν με iterators ή συμβολοσειρές.

@item 
Τα μοτίβα ακολουθίας υποστηρίζουν εκτεταμένο unpacking: @code{[x, y, *rest]} και @code{(x, y, *rest)} λειτουργεί παρόμοια με το unpacking αναθέσεων.  Το όνομα μετά το @code{*} μπορεί επίσης να είναι @code{_}, οπότε το @code{(x, y, *_)} αντιστοιχεί σε μια ακολουθία τουλάχιστον δύο στοιχείων χωρίς να δεσμεύει τα υπόλοιπα στοιχεία.

@item 
Μοτίβα αντιστοίχισης: @code{@{"bandwidth": b, "latency": l@}} καταγράφει τις τιμές @code{"bandwidth"} και @code{"latency"} από ένα λεξικό.  Σε αντίθεση με τα μοτίβα ακολουθίας, επιπλέον κλειδιά αγνοούνται.  Υποστηρίζεται επίσης το unpacking όπως το @code{**rest}.  (Αλλά το @code{**_} θα ήταν περιττό, επομένως δεν επιτρέπεται.)

@item 
Τα δευτερεύοντα μοτίβα μπορούν να αποτυπωθούν χρησιμοποιώντας το keyword @code{as}:

@example
case (Point(x1, y1), Point(x2, y2) as p2): ...
@end example

θα καταγράψει το δεύτερο στοιχείο της εισόδου ως @code{p2} (εφόσον η είσοδος είναι μια ακολουθία δύο σημείων)

@item 
Τα περισσότερα literals συγκρίνονται με ισότητα, ωστόσο τα singletons @code{True}, @code{False} και @code{None} συγκρίνονται με ταυτότητα.

@item 
Patterns may use named constants.  These must be dotted names
to prevent them from being interpreted as capture variables:

@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

Για πιο λεπτομερή επεξήγηση και πρόσθετα παραδείγματα, μπορείτε να δείτε το 
@geindex Python Enhancement Proposals; PEP 636
PEP 636@footnote{https://peps.python.org/pep-0636/} το οποίο είναι γραμμένο σε μορφή εκμάθησης.

@node Καθορισμός Συναρτήσεων,Περισσότερο για τον Καθορισμό Συναρτήσεων,Προτάσεις match,Περισσότερα εργαλεία Ελέγχου Ροής
@anchor{tutorial/controlflow defining-functions}@anchor{21ec}@anchor{tutorial/controlflow tut-functions}@anchor{21ed}
@subsection Καθορισμός Συναρτήσεων


Μπορούμε να δημιουργήσουμε μια συνάρτηση που γράφει τη σειρά Fibonacci σε ένα αυθαίρετο όριο:

@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

Το keyword @ref{17fc,,def} εισάγει μια συνάρτηση `ορισμός'.  Πρέπει να ακολουθείται από το όνομα της συνάρτησης και τη λίστα των τυπικών παραμέτρων σε παρένθεση. Οι δηλώσεις που σχηματίζουν το σώμα της συνάρτησης ξεκινούν από την επόμενη γραμμή και πρέπει να είναι εσοχές.

Η πρώτη δήλωση του σώματος της συνάρτησης μπορεί προαιρετικά να είναι ένα literal συμβολοσειράς· αυτό το literal συμβολοσειράς είναι η συμβολοσειρά τεκμηρίωσης της συνάρτησης ή `docstring'. (Περισσότερα για τα docstring μπορείτε να βρείτε στην ενότητα @ref{21ee,,Συμβολοσειρές Τεκμηρίωσης}.) Υπάρχουν εργαλεία που χρησιμοποιούν docstrings για την αυτόματη παραγωγή διαδικτυακής ή έντυπης τεκμηρίωσης ή για να αφήσουν τον χρήστη να περιηγηθεί διαδραστικά στον κώδικα· είναι καλή πρακτική να συμπεριλαμβάνονται docstrings στον κώδικα που γράφετε, για αυτό κάντε το συνήθεια.

Η `εκτέλεση' μιας συνάρτησης εισάγει έναν νέο πίνακα συμβόλων που χρησιμοποιείται για τις τοπικές μεταβλητές της συνάρτησης.  Πιο συγκεκριμένα, όλες οι εκχωρήσεις μεταβλητών σε μια συνάρτηση αποθηκεύουν την τιμή στον πίνακα τοπικών συμβόλων∙ ενώ οι αναφορές μεταβλητών κοιτάζονται πρώτα στον πίνακα τοπικών συμβόλων, στη συνέχεια στους πίνακες τοπικών συμβόλων των συναρτήσεων που περικλείουν, μετά στον πίνακα καθολικών συμβόλων και, τέλος, στον πίνακα ενσωματωμένων ονομάτων.  Έτσι, οι καθολικές μεταβλητές και οι μεταβλητές των συναρτήσεων που περικλείουν δεν μπορούν να εκχωρηθούν ως μια τιμή μέσα σε μια συνάρτηση (εκτός εάν, για καθολικές μεταβλητές, που ονομάζονται σε μια δήλωση @ref{6b5,,global} ή, για μεταβλητές συναρτήσεων που περικλείουν, ονομάζονται ως μια δήλωση @ref{164c,,nonlocal}), αν και μπορεί να αναφέρονται.

Οι πραγματικές παράμετροι (ορίσματα) σε μια κλήση συνάρτησης εισάγονται στον τοπικό πίνακα συμβόλων της καλούμενης συνάρτησης όταν αυτή καλείται· έτσι, τα ορίσματα μεταβιβάζονται χρησιμοποιώντας `call by value' (όπου η `value' είναι πάντα ένα αντικείμενο `reference', όχι την τιμή του αντικειμένου). @footnote{
Στην πραγματικότητα, η `κλήση με αναφορά αντικειμένου' θα ήταν μια καλύτερη περιγραφή, καθώς εάν μεταβιβαστεί ένα μεταβλητό αντικείμενο, ο καλών θα δει τυχόν αλλαγές που κάνει ο καλών  σε αυτό (στοιχεία που εισάγονται σε μια λίστα).
} Όταν μια συνάρτηση καλεί μια άλλη συνάρτηση ή καλεί τον εαυτό της αναδρομικά, δημιουργείται ένας νέος πίνακας τοπικών συμβόλων για αυτήν την κλήση.

Ένας ορισμός συνάρτησης συσχετίζει το όνομα της συνάρτησης με το αντικείμενο συνάρτησης στον τρέχοντα πίνακα συμβόλων.  Ο διερμηνέας αναγνωρίζει το αντικείμενο στο οποίο επισημαίνεται αυτό το όνομα ως συνάρτηση που ορίζεται από τον χρήστη.  Άλλα ονόματα μπορούν επίσης να δείχνουν το ίδιο αντικείμενο συνάρτησης και μπορούν επίσης να χρησιμοποιηθούν για πρόσβαση στη συνάρτηση:

@example
>>> fib
<function fib at 10042ed0>
>>> f = fib
>>> f(100)
0 1 1 2 3 5 8 13 21 34 55 89
@end example

Προερχόμενοι από άλλες γλώσσες, μπορεί να αντιταχθείτε ότι το @code{fib} δεν είναι μια συνάρτηση αλλά μια διαδικασία, καθώς δεν επιστρέφει μια τιμή.  Στην πραγματικότητα, ακόμη και συναρτήσεις χωρίς δήλωση @ref{44b,,return} επιστρέφουν μια τιμή, αν και μάλλον βαρετή.  Αυτή η τιμή ονομάζεται @code{None}.  Η εγγραφή της τιμής @code{None} από τον διερμηνέα, εάν θα ήταν η μόνη τιμή που γράφεται.  Μπορείτε να το δείτε αν το θέλετε πραγματικά χρησιμοποιώντας τη @ref{131f,,print()}:

@example
>>> fib(0)
>>> print(fib(0))
None
@end example

Είναι απλό να γράψετε μια συνάρτηση που επιστρέφει μια λίστα με τους αριθμούς της σειράς Fibonacci, αντί να την εκτυπώσετε:

@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

Αυτό το παράδειγμα, ως συνήθως, δείχνει μερικά νέα χαρακτηριστικά Python:


@itemize *

@item 
Η δήλωση @ref{44b,,return} επιστρέφει με μια τιμή από μια συνάρτηση. Το @code{return} χωρίς όρισμα έκφρασης, επιστρέφει το @code{None}. Η πτώση του τέλους μιας συνάρτησης επιστρέφει επίσης @code{None}.

@item 
Η δήλωση @code{result.append(a)} καλεί μια `μέθοδο' του αντικειμένου της λίστας @code{result}.  Μια μέθοδος είναι μια συνάρτηση που “ανήκει” σε ένα αντικείμενο και ονομάζεται @code{obj.methodname}, όπου @code{obj} είναι κάποιο αντικείμενο (αυτό μπορεί να είναι μια έκφραση), και το @code{methodname} είναι το όνομα μιας μεθόδου που ορίζεται από τον τύπο του αντικειμένου. Διαφορετικοί τύποι ορίζουν διαφορετικές μεθόδους.  Μέθοδοι διαφορετικών τύπων μπορεί να έχουν το ίδιο όνομα χωρίς να προκαλούν ασάφεια.  (Είναι δυνατό να ορίσετε τους δικούς σας τύπους αντικειμένων και μεθόδους, χρησιμοποιώντας `classes', δείτε @ref{21ef,,Κλάσεις}) Η μέθοδος @ref{aba,,append()} που εμφανίζεται στο παράδειγμα ορίζεται για αντικείμενα λίστας· προσθέτει ένα νέο στοιχείο στο τέλος της λίστας.  Σε αυτό το παράδειγμα είναι ισοδύναμο με @code{result = result + [a]}, αλλά πιο αποτελεσματικό.
@end itemize

@node Περισσότερο για τον Καθορισμό Συναρτήσεων,Intermezzo Στυλ Κώδικα,Καθορισμός Συναρτήσεων,Περισσότερα εργαλεία Ελέγχου Ροής
@anchor{tutorial/controlflow more-on-defining-functions}@anchor{21f0}@anchor{tutorial/controlflow tut-defining}@anchor{21f1}
@subsection Περισσότερο για τον Καθορισμό Συναρτήσεων


Είναι επίσης δυνατός ο ορισμός συναρτήσεων με μεταβλητό αριθμό ορισμάτων. Υπάρχουν τρεις μορφές, που μπορούν να συνδυαστούν.

@menu
* Προεπιλεγμένες Τιμές Ορίσματος:: 
* Ορίσματα Keyword:: 
* Ειδικές παράμετροι:: 
* Λίστες Αυθαίρετων Ορισμάτων:: 
* Unpacking Λίστες Ορισμάτων:: 
* Εκφράσεις Lambda:: 
* Συμβολοσειρές Τεκμηρίωσης:: 
* Annotations Συναρτήσεων:: 

@end menu

@node Προεπιλεγμένες Τιμές Ορίσματος,Ορίσματα Keyword,,Περισσότερο για τον Καθορισμό Συναρτήσεων
@anchor{tutorial/controlflow default-argument-values}@anchor{21f2}@anchor{tutorial/controlflow tut-defaultargs}@anchor{21f3}
@subsubsection Προεπιλεγμένες Τιμές Ορίσματος


Η πιο χρήσιμη φόρμα είναι να καθορίσετε μια προεπιλεγμένη τιμή για ένα ή περισσότερα ορίσματα. Αυτό δημιουργεί μια συνάρτηση που μπορεί να κληθεί με λιγότερα ορίσματα από αυτά που έχει ορίσει ότι επιτρέπει.  Για παράδειγμα:

@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

Αυτή η συνάρτηση μπορεί να κληθεί με διάφορους τρόπους:


@itemize *

@item 
δίνοντας μόνο το υποχρεωτικό όρισμα: @code{ask_ok('Do you really want to quit?')}

@item 
δίνοντας ένα από τα προαιρετικά ορίσματα: @code{ask_ok('OK to overwrite the file?', 2)}

@item 
ή δίνοντας όλα τα ορίσματα: @code{ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or no!')}
@end itemize

Αυτό το παράδειγμα εισάγει επίσης το keyword @ref{323,,in}. Αυτό ελέγχει εάν μια ακολουθία περιέχει ή όχι μια συγκεκριμένη τιμή.

Οι προεπιλεγμένες τιμές αξιολογούνται στο σημείο του ορισμού της συνάρτησης στο πεδίο που `ορίζεται', έτσι ώστε

@example
i = 5

def f(arg=i):
    print(arg)

i = 6
f()
@end example

θα εκτυπώσει @code{5}.

`Σημαντική προειδοποίηση:'  Η προεπιλεγμένη τιμή αξιολογείται μόνο μία φορά. Αυτό κάνει τη διαφορά όταν η προεπιλογή είναι ένα μεταβλητό αντικείμενο, όπως μια λίστα, λεξικό ή στιγμιότυπα των περισσότερων κλάσεων.  Για παράδειγμα, η ακόλουθη συνάρτηση συσσωρεύει τα ορίσματα που διαβάζονται σε αυτό σε επόμενες κλήσεις:

@example
def f(a, L=[]):
    L.append(a)
    return L

print(f(1))
print(f(2))
print(f(3))
@end example

Αυτό θα εκτυπώσει

@example
[1]
[1, 2]
[1, 2, 3]
@end example

Εάν δεν θέλετε να γίνεται κοινή χρήση της προεπιλογής μεταξύ των επόμενων κλήσεων, μπορείτε να γράψετε τη συνάρτηση ως εξής:

@example
def f(a, L=None):
    if L is None:
        L = []
    L.append(a)
    return L
@end example

@node Ορίσματα Keyword,Ειδικές παράμετροι,Προεπιλεγμένες Τιμές Ορίσματος,Περισσότερο για τον Καθορισμό Συναρτήσεων
@anchor{tutorial/controlflow keyword-arguments}@anchor{21f4}@anchor{tutorial/controlflow tut-keywordargs}@anchor{21f5}
@subsubsection Ορίσματα Keyword


Οι συναρτήσεις μπορούν επίσης να κληθούν χρησιμοποιώντας το @ref{10cc,,keyword arguments} της μορφής @code{kwarg=value}.  Για παράδειγμα, την ακόλουθη συνάρτηση:

@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

δέχεται ένα απαιτούμενο όρισμα (@code{voltage}) και τρία προαιρετικά ορίσματα (@code{state}, @code{action}, και @code{type}).  Αυτή η συνάρτηση μπορεί να κληθεί με οποιονδήποτε από τους ακόλουθους τρόπους:

@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

αλλά όλες οι ακόλουθες κλήσεις θα ήταν άκυρες:

@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

Σε μια κλήση συνάρτησης, τα keyword ορίσματα πρέπει να ακολουθούν ορίσματα θέσης. Όλα τα keyword ορίσματα που διαβάζονται πρέπει να ταιριάζουν με ένα από τα ορίσματα που γίνονται δεκτά από τη συνάρτηση (π.χ. το @code{actor} δεν είναι έγκυρο όρισμα για τη συνάρτηση @code{parrot}), και η διάταξη τους δεν είναι σημαντική.  Αυτό περιλαμβάνει επίσης μη προαιρετικά ορίσματα (π.χ. @code{parrot(voltage=1000)} είναι επίσης έγκυρο). Κανένα όρισμα δεν μπορεί να λάβει μια τιμή περισσότερες από μία φορές. Ακολουθεί ένα παράδειγμα που αποτυγχάνει λόγω αυτού του περιορισμού:

@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

Όταν υπάρχει μια τελική επίσημη παράμετρος της μορφής @code{**name}, λαμβάνει ένα λεξικό (δείτε @ref{e8c,,Mapping types — dict@comma{} frozendict}) που περιέχει όλα τα keyword ορίσματα εκτός από αυτά που αντιστοιχούν σε μια επίσημη παράμετρο.  Αυτό μπορεί να συνδυαστεί με μια επίσημη παράμετρος της μορφής @code{*name} (που περιγράφεται στην επόμενη υποενότητα) η οποία λαμβάνει ένα @ref{21f6,,tuple} που περιέχει τα ορίσματα θέσης πέρα από την επίσημη λίστα παραμέτρων.  (Το @code{*name} πρέπει να εμφανίζεται πριν από το @code{**name}.) Για παράδειγμα, αν ορίσουμε μια συνάρτηση όπως αυτή:

@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

Μπορεί να καλεστεί κάπως έτσι:

@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

και φυσικά θα εκτυπώσει:

@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

Λάβετε υπόψη ότι η σειρά με την οποία εκτυπώνονται τα keyword ορίσματα είναι εγγυημένη ότι ταιριάζει με τη σειρά με την οποία δόθηκαν στην κλήση της συνάρτησης.

@node Ειδικές παράμετροι,Λίστες Αυθαίρετων Ορισμάτων,Ορίσματα Keyword,Περισσότερο για τον Καθορισμό Συναρτήσεων
@anchor{tutorial/controlflow special-parameters}@anchor{21f7}
@subsubsection Ειδικές παράμετροι


Από προεπιλογή, τα ορίσματα μπορούν να μεταβιβαστούν σε μια συνάρτηση Python είτε με βάση τη θέση είτε ρητά με το keyword. Για αναγνωσιμότητα και απόδοση, είναι λογικό να περιοριστεί ο τρόπος με τον οποίο μπορούν να περάσουν τα ορίσματα, έτσι ώστε ένας προγραμματιστής να μην χρειάζεται να κοιτάξει τον ορισμό της συνάρτησης για να προσδιορίσει εάν τα στοιχεία μεταβιβάζονται κατά θέση, κατά θέση ή keyword, ή κατά keyword.

Ένας ορισμός συνάρτησης μπορεί να μοιάζει με αυτό:

@example
def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
      -----------    ----------     ----------
        |             |                  |
        |        Positional or keyword   |
        |                                - Keyword only
         -- Positional only
@end example

όπου τα @code{/} και @code{*} είναι προαιρετικά. Εάν χρησιμοποιούνται, αυτά τα σύμβολα υποδεικνύουν το είδος της παραμέτρους με τον τρόπο που τα ορίσματα μπορούν να μεταβιβαστούν στη συνάρτηση: μόνο θέσης (positional-only), θέσης ή keyword (positional-or-keyword), και μόνο keyword (keyword-only). Οι keyword παράμετροι αναφέρονται επίσης ως ονομασμένες παράμετροι.

@menu
* Παράμετροι Θέσης ή Keyword:: 
* Παράμετροι Μόνο-Θέσης:: 
* Ορίσματα μόνο Keyword:: 
* Παραδείγματα Συναρτήσεων:: 
* Ανακεφαλαίωση:: 

@end menu

@node Παράμετροι Θέσης ή Keyword,Παράμετροι Μόνο-Θέσης,,Ειδικές παράμετροι
@anchor{tutorial/controlflow positional-or-keyword-arguments}@anchor{21f8}
@subsubsection Παράμετροι Θέσης ή Keyword


Εάν τα @code{/} και @code{*} δεν υπάρχουν στον ορισμό της συνάρτησης, τα ορίσματα μπορούν να μεταβιβαστούν σε μια συνάρτηση ανά θέση ή κατά keyword.

@node Παράμετροι Μόνο-Θέσης,Ορίσματα μόνο Keyword,Παράμετροι Θέσης ή Keyword,Ειδικές παράμετροι
@anchor{tutorial/controlflow positional-only-parameters}@anchor{21f9}
@subsubsection Παράμετροι Μόνο-Θέσης


Επανεξετάζοντας αυτό το θέμα λίγο πιο λεπτομερώς, είναι δυνατό να επισημάνετε ορισμένες παραμέτρους ως `μόνο θέσης'.Εάν `μόνο θέσης', η σειρά των παραμέτρων έχει σημασία και οι παράμετροι δεν μπορούν να μεταβιβαστούν με keyword. Οι παράμετροι μόνο θέσης τοποθετούνται πριν από ένα @code{/} (προς τα εμπρός-κάθετος). Το @code{/} χρησιμοποιείται για να διαχωρίσει λογικά τις παραμέτρους μόνο θέσης από τις υπόλοιπες παραμέτρους. Εάν δεν υπάρχει το @code{/} στον ορισμό της συνάρτησης, δεν υπάρχουν παράμετροι μόνο θέσης.

Οι παράμετροι που ακολουθούν το @code{/} μπορεί να είναι `θέσης ή keyword' ή `μόνο keyword'.

@node Ορίσματα μόνο Keyword,Παραδείγματα Συναρτήσεων,Παράμετροι Μόνο-Θέσης,Ειδικές παράμετροι
@anchor{tutorial/controlflow keyword-only-arguments}@anchor{21fa}
@subsubsection Ορίσματα μόνο Keyword


Για να επισημάνετε τις παραμέτρους ως `μόνο keyword', υποδεικνύοντας ότι οι παράμετροι πρέπει να περάσουν από το keyword όρισμα, τοποθετήσετε ένα @code{*} στη λίστα ορισμάτων ακριβώς πριν από την πρώτη παράμετρο `μόνο keyword'.

@node Παραδείγματα Συναρτήσεων,Ανακεφαλαίωση,Ορίσματα μόνο Keyword,Ειδικές παράμετροι
@anchor{tutorial/controlflow function-examples}@anchor{21fb}
@subsubsection Παραδείγματα Συναρτήσεων


Σκεφτείτε τα ακόλουθα παραδείγματα ορισμών συναρτήσεων δίνοντας ιδιαίτερη προσοχή στους δείκτες @code{/} και @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

Ο πρώτος ορισμός συνάρτησης, @code{standard_arg}, η πιο οικεία μορφή, δεν θέτει περιορισμούς στη σύμβαση κλήσης και τα ορίσματα μπορούν να περάσουν από θέση ή από keyword:

@example
>>> standard_arg(2)
2

>>> standard_arg(arg=2)
2
@end example

Η δεύτερη συνάρτηση @code{pos_only_arg} περιορίζεται στη χρήση μόνο παραμέτρων θέσης καθώς υπάρχει ένα @code{/} στον ορισμός της συνάρτησης:

@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

Η τρίτη συνάρτηση @code{kwd_only_arg} επιτρέπει μόνο keyword ορίσματα όπως υποδεικνύεται από ένα @code{*} στον ορισμός της συνάρτησης:

@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

Και το τελευταίο χρησιμοποιεί και τις τρεις συμβάσεις κλήσης στον ίδιο ορισμό συνάρτησης:

@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

Τέλος, εξετάστε αυτόν τον ορισμό συνάρτησης που έχει μια πιθανή σύγκρουση μεταξύ του ορίσματος θέσης @code{name}  και @code{**kwds} που έχει ως κλειδί το @code{name}:

@example
def foo(name, **kwds):
    return 'name' in kwds
@end example

Δεν υπάρχει καμία πιθανή κλήση που θα την κάνει να επιστρέψει @code{True} καθώς το keyword @code{'name'} θα συνδέεται πάντα με την πρώτη παράμετρο. Για παράδειγμα:

@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

Αλλά χρησιμοποιώντας @code{/} (ορίσματα μόνο θέσης), είναι δυνατό καθώς επιτρέπει το @code{name} ως όρισμα θέσης και το @code{'name'} ως κλειδί στα keyword ορίσματα:

@example
>>> def foo(name, /, **kwds):
...     return 'name' in kwds
...
>>> foo(1, **@{'name': 2@})
True
@end example

Με άλλα λόγια, τα ονόματα των παραμέτρων μόνο θέσης μπορούν να χρησιμοποιηθούν σε @code{**kwds} χωρίς ασάφεια.

@node Ανακεφαλαίωση,,Παραδείγματα Συναρτήσεων,Ειδικές παράμετροι
@anchor{tutorial/controlflow recap}@anchor{21fc}
@subsubsection Ανακεφαλαίωση


Η περίπτωση χρήσης θα καθορίσει ποιες παραμέτρους θα χρησιμοποιηθούν στον ορισμό της συνάρτησης:

@example
def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
@end example

Ως καθοδήγηση:


@itemize *

@item 
Χρησιμοποιήστε τη θέση μόνο εάν θέλετε το όνομα των παραμέτρων να μην είναι διαθέσιμο στο χρήστη. Αυτό είναι χρήσιμο όταν τα ονόματα παραμέτρων δεν έχουν πραγματικό νόημα, εάν δεν θέλετε να επιβάλετε τη σειρά των ορισμάτων όταν καλείται η συνάρτηση ή εάν πρέπει να ληφθούν ορισμένες παράμετροι θέσης και αυθαίρετα keywords.

@item 
Χρησιμοποιήστε keyword μόνο όταν τα ονόματα έχουν νόημα και ο ορισμός της συνάρτησης είναι πιο κατανοητός όταν είναι ρητός με ονόματα ή θέλετε να αποτρέψετε τους χρήστες να βασίζονται στη θέση του επιχειρήματος που μεταβιβάζεται.

@item 
Για ένα API, χρησιμοποιήστε το μόνο θέσης για να αποτρέψετε τη διακοπή των αλλαγών τους API, εάν το όνομα της παραμέτρου τροποποιηθεί στο μέλλον.
@end itemize

@node Λίστες Αυθαίρετων Ορισμάτων,Unpacking Λίστες Ορισμάτων,Ειδικές παράμετροι,Περισσότερο για τον Καθορισμό Συναρτήσεων
@anchor{tutorial/controlflow arbitrary-argument-lists}@anchor{21fd}@anchor{tutorial/controlflow tut-arbitraryargs}@anchor{21fe}
@subsubsection Λίστες Αυθαίρετων Ορισμάτων


@geindex * (αστερίσκος);in function calls

Τέλος, η λιγότερο συχνά χρησιμοποιούμενη επιλογή είναι να ορίσετε ότι μια συνάρτηση μπορεί να κληθεί με έναν αυθαίρετο αριθμός ορισμάτων.  Αυτά τα ορίσματα θα τυλιχθούν σε μια πλειάδα (tuple) (βλ. @ref{21f6,,Πλειάδες (Tuples) και Ακολουθίες}).  Πριν από τον μεταβλητό αριθμό ορισμάτων ενδέχεται να προκύψουν μηδέν ή περισσότερα κανονικά ορίσματα.

@example
def write_multiple_items(file, separator, *args):
    file.write(separator.join(args))
@end example

Κανονικά, αυτά τα `variadic' ορίσματα θα είναι τελευταία στη λίστα των επίσημων παραμέτρων, επειδή συλλέγουν όλα τα υπόλοιπα ορίσματα εισόδου που μεταβιβάζονται στη συνάρτηση. Οποιεσδήποτε τυπικές παράμετροι που εμφανίζονται μετά την παράμετρο @code{*args} είναι “μόνο keyword” ορίσματα, που σημαίνει ότι μπορούν να χρησιμοποιηθούν μόνο ως λέξεις-κλειδιά και όχι ως ορίσματα θέσης.

@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 Unpacking Λίστες Ορισμάτων,Εκφράσεις Lambda,Λίστες Αυθαίρετων Ορισμάτων,Περισσότερο για τον Καθορισμό Συναρτήσεων
@anchor{tutorial/controlflow tut-unpacking-arguments}@anchor{21ff}@anchor{tutorial/controlflow unpacking-argument-lists}@anchor{2200}
@subsubsection Unpacking Λίστες Ορισμάτων


Η αντίστροφη κατάσταση συμβαίνει όταν τα ορίσματα βρίσκονται ήδη σε μια λίστα ή πλειάδα (tuple), αλλά πρέπει να αποσυμπιεστούν για μια κλήση συνάρτησης που απαιτεί ξεχωριστά ορίσματα θέσης.  Για παράδειγμα, η ενσωματωμένη (built-in) συνάρτηση @ref{d0f,,range()} αναμένει ξεχωριστά `start' και `stop' ορίσματα.  Εάν δεν είναι διαθέσιμα ξεχωριστά, γράψτε την κλήση συνάρτησης με τον @code{*}-τελεστή για να αποσυμπιέσετε τα ορίσματα από μια λίστα ή πλειάδα (tuple):

@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

Με τον ίδιο τρόπο, τα λεξικά μπορούν να παραδίδουν keyword ορίσματα με τον @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 Εκφράσεις Lambda,Συμβολοσειρές Τεκμηρίωσης,Unpacking Λίστες Ορισμάτων,Περισσότερο για τον Καθορισμό Συναρτήσεων
@anchor{tutorial/controlflow lambda-expressions}@anchor{2201}@anchor{tutorial/controlflow tut-lambda}@anchor{2202}
@subsubsection Εκφράσεις Lambda


Μπορούν αν δημιουργηθούν μικρές ανώνυμες συναρτήσεις με το keyword @ref{1642,,lambda}. Αυτή η συνάρτηση επιστρέφει το άθροισμα των δύο ορισμάτων της: @code{lambda a, b: a+b}. Οι συναρτήσεις Lambda μπορούν να χρησιμοποιηθούν όπου απαιτούνται αντικείμενα συνάρτησης. Περιορίζονται συντακτικά σε μία μόνο έκφραση.  Σημασιολογικά, είναι απλώς syntactic sugar για έναν ορισμό κανονικής συνάρτησης.  Όπως οι ορισμοί ένθετων  συναρτήσεων, οι συναρτήσεις lambda μπορούν να παραπέμπουν σε μεταβλητές από το πεδίο που περιέχει:

@example
>>> def make_incrementor(n):
...     return lambda x: x + n
...
>>> f = make_incrementor(42)
>>> f(0)
42
>>> f(1)
43
@end example

Το παραπάνω παράδειγμα χρησιμοποιεί μια έκφραση lambda για να επιστρέψει μια συνάρτηση.  Μια άλλη χρήση είναι η μετάδοση μιας μικρής συνάρτησης ως όρισμα.  Για παράδειγμα, η @ref{f8d,,list.sort()} δέχεται μια συνάρτηση ταξινόμησης κλειδιού `key' η οποία μπορεί να είναι μια συνάρτηση lambda:

@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 Συμβολοσειρές Τεκμηρίωσης,Annotations Συναρτήσεων,Εκφράσεις Lambda,Περισσότερο για τον Καθορισμό Συναρτήσεων
@anchor{tutorial/controlflow documentation-strings}@anchor{2203}@anchor{tutorial/controlflow tut-docstrings}@anchor{21ee}
@subsubsection Συμβολοσειρές Τεκμηρίωσης


@geindex docstrings
@geindex documentation strings
@geindex strings@comma{} documentation

Ακολουθούν ορισμένες συμβάσεις σχετικά με το περιεχόμενο και τη μορφοποίηση των συμβολοσειρών τεκμηρίωσης.

Η πρώτη γραμμή πρέπει να είναι πάντα μια σύντομη, συνοπτική περίληψη του σκοπού του αντικειμένου.  Για συντομία, δεν πρέπει να αναφέρει ρητά το όνομα ή τον τύπο του αντικειμένου , καθώς αυτά είναι διαθέσιμα με άλλα μέσα (εκτός εάν το όνομα είναι ρήμα που περιγράφει τη λειτουργία της συνάρτησης).  Αυτή η γραμμή πρέπει να ξεκινά με κεφαλαίο γράμμα και να τελειώνει με τελεία.

Εάν υπάρχουν περισσότερες γραμμές στη συμβολοσειρά τεκμηρίωσης, η δεύτερη γραμμή θα πρέπει να είναι κενή, διαχωρίζοντας οπτικά τη σύνοψη από την υπόλοιπη περιγραφή.  Οι ακόλουθες γραμμές πρέπει να είναι μία ή περισσότερες παράγραφοι που περιγράφουν τις συμβάσεις κλήσης του αντικειμένου, τις παρενέργειές του κ.λπ..

The Python parser strips indentation from multi-line string literals when they
serve as module, class, or function docstrings.

Ακολουθεί ένα παράδειγμα ενός πολλαπλών γραμμών docstring:

@example
>>> def my_function():
...     """Do nothing, but document it.
...
...     No, really, it doesn't do anything:
...
...         >>> my_function()
...         >>>
...     """
...     pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.

No, really, it doesn't do anything:

    >>> my_function()
    >>>
@end example

@node Annotations Συναρτήσεων,,Συμβολοσειρές Τεκμηρίωσης,Περισσότερο για τον Καθορισμό Συναρτήσεων
@anchor{tutorial/controlflow function-annotations}@anchor{2204}@anchor{tutorial/controlflow tut-annotations}@anchor{2205}
@subsubsection Annotations Συναρτήσεων


@geindex function;annotations
@geindex ->;function annotations
@geindex ; (colon);function annotations

Το @ref{2206,,Function annotations} είναι εντελώς προαιρετικές πληροφορίες μεταδεδομένων σχετικά με τους τύπους χρησιμοποιούνται από συναρτήσεις που καθορίζονται από το χρήστη (δείτε 
@geindex Python Enhancement Proposals; PEP 3107
PEP 3107@footnote{https://peps.python.org/pep-3107/} και 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} για περισσότερες πληροφορίες).

Το @ref{2207,,Annotations} αποθηκεύονται στο χαρακτηριστικό @ref{66b,,__annotations__} της συνάρτησης ως λεξικό και δεν έχουνε καμία επίδραση σε κανένα άλλο μέρος της συνάρτησης.  Τα annotations των παραμέτρων ορίζονται με άνω και κάτω τελεία μετά το όνομα παραμέτρου, ακολουθούμενη από μια έκφραση που αξιολογεί την τιμή του annotation.  Τα annotations επιστροφής ορίζονται από ένα literal @code{->}, ακολουθούμενο από μια έκφραση, μεταξύ της λίστας παραμέτρων και της άνω και κάτω τελείας που υποδηλώνει το τέλος της δήλωσης @ref{17fc,,def}.  Το ακόλουθο παράδειγμα έχει ένα απαιτούμενο όρισμα, ένα προαιρετικό όρισμα και την επιστρεφόμενη τιμή σε annotations:

@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 Intermezzo Στυλ Κώδικα,,Περισσότερο για τον Καθορισμό Συναρτήσεων,Περισσότερα εργαλεία Ελέγχου Ροής
@anchor{tutorial/controlflow intermezzo-coding-style}@anchor{2208}@anchor{tutorial/controlflow tut-codingstyle}@anchor{2209}
@subsection Intermezzo: Στυλ Κώδικα


@geindex coding;style

Now that you are about to write longer, more complex pieces of Python, it is a
good time to talk about `coding style'.  Most languages can be written (or more
concisely, `formatted') in different styles; some are more readable than others.
Making it easy for others to read your code is always a good idea, and adopting
a nice coding style helps tremendously for that.

Για την Python, το 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/} έχει αναδειχθεί ως οδηγός στυλ στον οποίο τηρούν τα περισσότερα έργα· προωθεί ένα πολύ ευανάγνωστο και ευχάριστο στυλ κώδικα.  Κάθε προγραμματιστής Python θα πρέπει να το διαβάσει κάποια στιγμή· εδώ είναι τα πιο σημαντικό σημεία που εξάγονται για εσάς:


@itemize *

@item 
Χρησιμοποιήστε εσοχή 4 διαστημάτων και όχι tabs.

Τα 4 κενά είναι ένας καλός συμβιβασμός μεταξύ της μικρής εσοχής (επιτρέπει μεγαλύτερο βάθος εμφώλευσης) και της μεγάλης εσοχής (ευκολότερη στην ανάγνωση).  Τα tabs δημιουργούν σύγχυση, και είναι καλύτερο να παραμείνουν απέξω.

@item 
Τυλίξτε τις γραμμές έτσι ώστε να μην υπερβαίνουν τους 79 χαρακτήρες.

Αυτό βοηθά του χρήστες με μικρές οθόνες και καθιστά δυνατή την ύπαρξη πολλών αρχείων κώδικα δίπλα-δίπλα σε μεγαλύτερες οθόνες.

@item 
Χρησιμοποιείστε κενές γραμμές για να διαχωρίσετε συναρτήσεις και κλάσεις και μεγαλύτερα μπλοκ κώδικα μέσα συναρτήσεις.

@item 
Όταν είναι δυνατόν, βάλτε σχόλια σε μια δική τους γραμμή.

@item 
Χρησιμοποιήστε docstrings.

@item 
Χρησιμοποιήστε κενά γύρω από τελεστές και μετά από κόμματα, αλλά όχι απευθείας μέσα δε δομές αγκύλων: @code{a = f(1, 2) + g(3, 4)}.

@item 
Ονομάστε τις κλάσεις και τις συναρτήσεις σας με συνέπεια· η σύμβαση είναι να χρησιμοποιείτε @code{UpperCamelCase} για τις κλάσεις και @code{lowercase_with_underscores} για τις συναρτήσεις και τις μεθόδους.  Χρησιμοποιείτε πάντα το @code{self} ως όνομα για το πρώτο όρισμα μεθόδου (δείτε @ref{220a,,Μια πρώτη ματιά στις Κλάσεις} για περισσότερα σχετικά με τις κλάσεις και τις μεθόδους).

@item 
Μην χρησιμοποιείτε φανταχτερές κωδικοποιήσεις εάν ο κώδικας σας προορίζεται να χρησιμοποιηθεί σε διεθνή περιβάλλοντα.  Η προεπιλογή της Python, UTF-8, ή ακόμα και το απλό ASCII λειτουργούν καλύτερα σε κάθε περίπτωση.

@item 
Ομοίως, μη χρησιμοποιείτε χαρακτήρες που δεν είναι ASCII σε αναγνωριστικά εάν υπάρχει μόνο η παραμικρή πιθανότητα οι άνθρωποι που μιλούν διαφορετική γλώσσα να διαβάσουν ή να διατηρήσουν τον κώδικα.
@end itemize

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Δομές Δεδομένων,Modules<2>,Περισσότερα εργαλεία Ελέγχου Ροής,Οδηγός εκμάθησης Python
@anchor{tutorial/datastructures doc}@anchor{220b}@anchor{tutorial/datastructures data-structures}@anchor{220c}@anchor{tutorial/datastructures translation-repo}@anchor{220d}@anchor{tutorial/datastructures tut-structures}@anchor{21e1}
@section Δομές Δεδομένων


Αυτό το κεφάλαιο περιγράφει ορισμένα πράγματα τα οποία έχετε μάθει ήδη με περισσότερες λεπτομέρειες και προσθέτει επίσης μερικά νέα.

@menu
* Περισσότερα για τις Λίστες:: 
* Η δήλωση del:: 
* Πλειάδες (Tuples) και Ακολουθίες: Πλειάδες Tuples και Ακολουθίες. 
* Σύνολα (Sets): Σύνολα Sets. 
* Λεξικά (Dictionaries): Λεξικά Dictionaries. 
* Τεχνικές Looping:: 
* Περισσότερα για τις συνθήκες:: 
* Σύγκριση ακολουθιών και άλλων τύπων:: 

@end menu

@node Περισσότερα για τις Λίστες,Η δήλωση del,,Δομές Δεδομένων
@anchor{tutorial/datastructures more-on-lists}@anchor{220e}@anchor{tutorial/datastructures tut-morelists}@anchor{220f}
@subsection Περισσότερα για τις Λίστες


Ο τύπος δεδομένων @ref{2210,,λίστα} έχει μερικές ακόμη μεθόδους. Εδώ είναι όλες οι μέθοδοι των αντικειμένων λίστας:


@deffn {Μέθοδος} list.append (value, /)

Προσθέτει ένα στοιχείο στο τέλος της λίστας.  Παρόμοιο με @code{a[len(a):] = [x]}.
@end deffn


@deffn {Μέθοδος} list.extend (iterable, /)

Επεκτείνει τη λίστα προσθέτοντας όλα τα στοιχεία από το iterable.  Παρόμοιο με @code{a[len(a):] = iterable}.
@end deffn


@deffn {Μέθοδος} list.insert (index, value, /)

Εισάγει ένα στοιχείο σε μια δεδομένη θέση.  Το πρώτο όρισμα είναι το index του στοιχείου πριν από το οποίο θα εισαχθεί, επομένως @code{a.insert(0, x)} εισάγεται στο μπροστινό μέρος της λίστας, και το @code{a.insert(len(a), x)} ισοδυναμεί με @code{a.append(x)}.
@end deffn


@deffn {Μέθοδος} list.remove (value, /)

Remove the first item from the list whose value is equal to `value'.  It raises a
@ref{277,,ValueError} if there is no such item.
@end deffn


@deffn {Μέθοδος} list.pop (index=-1, /)

Καταργεί το στοιχείο στη δεδομένη θέση στη λίστα, και το επιστρέφει.  Εάν δεν έχει καθοριστεί ευρετήριο, το @code{a.pop()} αφαιρεί και επιστρέφει το τελευταίο στοιχείο στη λίστα. Κάνει raise ένα @ref{18d7,,IndexError} εάν η λίστα είναι κενή ή το ευρετήριο βρίσκεται εκτός του εύρους της λίστας.
@end deffn


@deffn {Μέθοδος} list.clear ()

Αφαιρεί όλα τα στοιχεία από τη λίστα.  Παρόμοιο με @code{del a[:]}.
@end deffn


@deffn {Μέθοδος} list.index (value[, start[, stop]])

Return zero-based index of the first occurrence of `value' in the list.
Raises a @ref{277,,ValueError} if there is no such item.

Τα προαιρετικά ορίσματα `start' και `end' ερμηνεύονται όπως στη σημειογραφία slice και χρησιμοποιούνται για τον περιορισμό της αναζήτησης σε μια συγκεκριμένη υποακολουθία της λίστας.  Ο επιστρεφόμενος δείκτης υπολογίζεται σε σχέση με την αρχή της πλήρους ακολουθίας αντί για το όρισμα `start'.
@end deffn


@deffn {Μέθοδος} list.count (value, /)

Return the number of times `value' appears in the list.
@end deffn


@deffn {Μέθοδος} list.sort (*, key=None, reverse=False)

Ταξινομεί τα στοιχεία της λίστας στη θέση τους (τα ορίσματα μπορούν να χρησιμοποιηθούν για προσαρμογή ταξινόμησης, βλ. @ref{f8c,,sorted()} για την εξήγησή τους).
@end deffn


@deffn {Μέθοδος} list.reverse ()

Αντιστρέφει τα στοιχεία της λίστας στη θέση τους.
@end deffn


@deffn {Μέθοδος} list.copy ()

Επιστρέφει ένα shallow (ρηχό) αντίγραφο της λίστας. Παρόμοιο με @code{a[:]}.
@end deffn

Ένα παράδειγμα που χρησιμοποιεί τις περισσότερες από τις μεθόδους της λίστας:

@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

Μπορεί να έχετε παρατηρήσει ότι μέθοδοι όπως @code{insert}, @code{remove} or @code{sort} που τροποποιούν μόνο τη λίστα δεν έχουν εκτυπωμένη τιμή επιστροφής – επιστρέφουν το προεπιλεγμένο (default) @code{None}. @footnote{
Άλλες γλώσσες ενδέχεται να επιστρέψουν το μεταλλαγμένο αντικείμενο, το οποίο επιτρέπει την αλυσιδωτή εκτέλεση μεθόδων, όπως @code{d->insert("a")->remove("b")->sort();}.
}  Αυτή είναι μια αρχή σχεδιασμού για όλες τις μεταβλητές δομές δεδομένων στην Python.

Ένα άλλο πράγμα που μπορεί να παρατηρήσετε είναι ότι δεν μπορούν να ταξινομηθούν ή να συγκριθούν όλα τα δεδομένα.  Για παράδειγμα, @code{[None, 'hello', 10]} δεν ταξινομούνται γιατί ακέραιοι αριθμοί δεν μπορούν να συγκριθούν με συμβολοσειρές (strings) και το @code{None} δεν μπορεί να συγκριθεί με άλλους τύπους.  Επίσης, υπάρχουν ορισμένοι τύποι που δεν έχουν καθορισμένη σχέση διάταξης.  Για παράδειγμα, το @code{3+4j < 5+7j} δεν είναι έγκυρη σύγκριση.

@menu
* Χρήστη Λιστών ως Στοίβες (Stacks): Χρήστη Λιστών ως Στοίβες Stacks. 
* Χρήση λιστών ως Ουρές (Queues): Χρήση λιστών ως Ουρές Queues. 
* Comprehensions Λίστας:: 
* Comprehensions Ένθετων Λιστών:: 
* Unpacking in Lists and List Comprehensions:: 

@end menu

@node Χρήστη Λιστών ως Στοίβες Stacks,Χρήση λιστών ως Ουρές Queues,,Περισσότερα για τις Λίστες
@anchor{tutorial/datastructures tut-lists-as-stacks}@anchor{2211}@anchor{tutorial/datastructures using-lists-as-stacks}@anchor{2212}
@subsubsection Χρήστη Λιστών ως Στοίβες (Stacks)


Οι μέθοδοι λίστας καθιστούν πιο εύκολη τη χρήση μιας λίστα ως στοίβας (stack), όπου το τελευταίο στοιχείο που προστέθηκε είναι το πρώτο στοιχείο που ανακτήθηκε («last-in, first-out»).  Για να προσθέσετε ένα στοιχείο στην κορυφή της στοίβας, χρησιμοποιήστε την @ref{aba,,append()}.  Για να ανακτήσετε ένα στοιχείο από την κορυφή της στοίβας, χρησιμοποιήστε την @ref{2213,,pop()} χωρίς κάποιο σαφές index.  Για παράδειγμα:

@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 Χρήση λιστών ως Ουρές Queues,Comprehensions Λίστας,Χρήστη Λιστών ως Στοίβες Stacks,Περισσότερα για τις Λίστες
@anchor{tutorial/datastructures tut-lists-as-queues}@anchor{2214}@anchor{tutorial/datastructures using-lists-as-queues}@anchor{2215}
@subsubsection Χρήση λιστών ως Ουρές (Queues)


Είναι επίσης δυνατό να χρησιμοποιηθεί μια λίστα ως ουρά (queue), όπου το πρώτο στοιχείο που προστίθεται είναι το πρώτο στοιχείο που ανακτάται («first-in, first-out») ∙ ωστόσο, οι λίστες δεν είναι αποτελεσματικές για αυτόν τον σκοπό.  Ενώ το να προσθέσεις και να αφαιρέσεις (στοιχεία) στο τέλος της λίστας είναι γρήγορο, κάνοντας αυτές τις προσθέσεις και τις αφαιρέσεις (στοιχείων) στην αρχή της λίστα είναι αργό (επειδή όλα τα στοιχεία πρέπει να μετατοπιστούν κατά ένα).

Για να εφαρμόσετε μια ουρά (queue), χρησιμοποιήστε την @ref{9d6,,collections.deque} η οποία σχεδιάστηκε για να έχει γρήγορες προσθέσεις και αφαιρέσεις και από τα δύο άκρα.  Για παράδειγμα:΅:

@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 Comprehensions Λίστας,Comprehensions Ένθετων Λιστών,Χρήση λιστών ως Ουρές Queues,Περισσότερα για τις Λίστες
@anchor{tutorial/datastructures list-comprehensions}@anchor{2216}@anchor{tutorial/datastructures tut-listcomps}@anchor{2217}
@subsubsection Comprehensions Λίστας


Τα comprehensions λίστας παρέχουν ένα συνοπτικό τρόπο δημιουργίας λιστών. Οι συνήθεις εφαρμογές είναι η δημιουργία νέων λιστών όπου κάθε στοιχείο είναι το αποτέλεσμα κάποιων πράξεων που εφαρμόζονται σε κάθε μέλος μιας άλλης ακολουθίας ή iterable, ή η δημιουργία μιας υποακολουθίας αυτών των στοιχείων που ικανοποιούν μια συγκεκριμένη συνθήκη.

Για παράδειγμα, ας υποθέσουμε ότι θέλουμε να δημιουργήσουμε μια λίστα τετραγώνων όπως:

@example
>>> squares = []
>>> for x in range(10):
...     squares.append(x**2)
...
>>> squares
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
@end example

Λάβετε υπόψη ότι αυτό δημιουργεί (ή αντικαθιστά) μια μεταβλητή με το όνομα @code{x} που εξακολουθεί να υπάρχει μετά την ολοκλήρωση της loop.  Μπορούμε να υπολογίσουμε τη λίστα των τετραγώνων χωρίς παρενέργειες χρησιμοποιώντας:

@example
squares = list(map(lambda x: x**2, range(10)))
@end example

ή, ισοδύναμα:

@example
squares = [x**2 for x in range(10)]
@end example

που είναι πιο συνοπτικό και ευανάγνωστο.

Ένα comprehension λίστας αποτελείται από αγκύλες που περιέχουν μια έκφραση ακολουθούμενη από μια πρόταση @code{for}, στη συνέχεια μηδέν ή περισσότερες προτάσεις @code{for} ή @code{if}.  Το αποτέλεσμα θα είναι μια νέα λίστα που προκύπτει από την αξιολόγηση της έκφρασης στο πλαίσιο των προτάσεων @code{for} και @code{if} που την ακολουθούν. Για παράδειγμα, αυτή η λίστα συνδυάζει τα στοιχεία δύο λιστών εάν δεν είναι ίσες:

@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

και ισοδυναμεί με:

@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

Σημειώστε πώς η σειρά των δηλώσεων @ref{321,,for} και @ref{322,,if} είναι ίδια και στα δύο αποσπάσματα.

Εάν η έκφραση είναι πλειάδα (π.χ. το @code{(x, y)} στο προηγούμενο παράδειγμα), πρέπει να μπει σε παρένθεση.

@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

Τα comprehensions λίστας μπορεί να περιέχουν σύνθετες εκφράσεις και ένθετες συναρτήσεις:

@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 Comprehensions Ένθετων Λιστών,Unpacking in Lists and List Comprehensions,Comprehensions Λίστας,Περισσότερα για τις Λίστες
@anchor{tutorial/datastructures nested-list-comprehensions}@anchor{2218}
@subsubsection Comprehensions Ένθετων Λιστών


Η αρχική έκφραση σε ένα comprehension λίστας μπορεί να είναι οποιαδήποτε αυθαίρετη έκφραση, συμπεριλαμβανομένης ενός άλλου comprehension λίστας.

Σκεφτείτε το ακόλουθο παράδειγμα μιας μήτρας 3x4 που υλοποιήθηκε ως μια λίστα 3 λιστών μήκους 4:

@example
>>> matrix = [
...     [1, 2, 3, 4],
...     [5, 6, 7, 8],
...     [9, 10, 11, 12],
... ]
@end example

Το ακόλουθο comprehension λίστας θα μεταφέρει γραμμές και στήλες:

@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

Όπως είδαμε στην προηγούμενη ενότητα, το comprehension της εσωτερικής λίστας αξιολογείται στο πλαίσιο του @ref{321,,for} που την ακολουθεί, επομένως αυτό το παράδειγμα είναι ισοδύναμο με:

@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

το οποίο, με τη σειρά του, είναι το ίδιο με:

@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

Στον πραγματικό κόσμο, θα πρέπει να προτιμάτε τις ενσωματωμένες (built-in) συναρτήσεις από τις σύνθετες εντολές ροής. Η συνάρτηση @ref{43f,,zip()} θα έκανε εξαιρετική δουλειά για αυτήν την περίπτωση χρήσης:

@example
>>> list(zip(*matrix))
[(1, 5, 9), (2, 6, 10), (3, 7, 11), (4, 8, 12)]
@end example

Δείτε @ref{21ff,,Unpacking Λίστες Ορισμάτων} για λεπτομέρειες σχετικά με τον αστερίσκο σε αυτήν τη γραμμή.

@node Unpacking in Lists and List Comprehensions,,Comprehensions Ένθετων Λιστών,Περισσότερα για τις Λίστες
@anchor{tutorial/datastructures unpacking-in-lists-and-list-comprehensions}@anchor{2219}
@subsubsection Unpacking in Lists and List Comprehensions


The section on @ref{21ff,,Unpacking Λίστες Ορισμάτων} describes the use of @code{*} to
«unpack» the elements of an iterable object, providing each one separately as
an argument to a function.  Unpacking can also be used in other contexts, for
example, when creating lists.  When specifying elements of a list, prefixing an
expression by a @code{*} will unpack the result of that expression, adding each of
its elements to the list we’re creating:

@example
>>> x = [1, 2, 3]
>>> [0, *x, 4, 5, 6]
[0, 1, 2, 3, 4, 5, 6]
@end example

This only works if the expression following the @code{*} evaluates to an iterable
object; trying to unpack a non-iterable object will raise an exception:

@example
>>> x = 1
>>> [0, *x, 2, 3, 4]
Traceback (most recent call last):
  File "<python-input-1>", line 1, in <module>
    [0, *x, 2, 3, 4]
TypeError: Value after * must be an iterable, not int
@end example

Unpacking can also be used in list comprehensions, as a way to build a new list
representing the concatenation of an arbitrary number of iterables:

@example
>>> x = [[1, 2, 3], [4, 5, 6], [], [7], [8, 9]]
>>> [*element for element in x]
[1, 2, 3, 4, 5, 6, 7, 8, 9]
@end example

Note that the effect is that each element from @code{x} is unpacked.  This works
for arbitrary iterable objects, not just lists:

@example
>>> x = [[1, 2, 3], 'cat', @{'spam': 'eggs'@}]
>>> [*element for element in x]
[1, 2, 3, 'c', 'a', 't', 'spam']
@end example

But if the objects in @code{x} are not iterable, this expression would again raise
an exception.

@node Η δήλωση del,Πλειάδες Tuples και Ακολουθίες,Περισσότερα για τις Λίστες,Δομές Δεδομένων
@anchor{tutorial/datastructures the-del-statement}@anchor{221a}@anchor{tutorial/datastructures tut-del}@anchor{221b}
@subsection Η δήλωση @code{del}


Υπάρχει ένας τρόπος να αφαιρέσετε ένα στοιχείο από μια λίστα με το ευρετήριο του αντί για την τιμή του: η δήλωση @ref{1d1d,,del}.  Αυτό διαφέρει από τη μέθοδο @ref{2213,,pop()} που επιστρέφει μια τιμή.  Η δήλωση @code{del} μπορεί επίσης να χρησιμοποιηθεί για την αφαίρεση τμημάτων από μια λίστα ή για να καθαρίσει ολόκληρη τη λίστα (που κάναμε νωρίτερα με την εκχώρηση μιας κενής λίστας στο τμήμα).  Για παράδειγμα:

@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{1d1d,,del} μπορεί επίσης να χρησιμοποιηθεί για τη διαγραφή ολόκληρων μεταβλητών:

@example
>>> del a
@end example

Η αναφορά στο όνομα @code{a} στο εξής είναι ένα σφάλμα (τουλάχιστον μέχρι να του εκχωρηθεί άλλη τιμή). Θα βρούμε άλλες χρήσεις για το @ref{1d1d,,del} αργότερα.

@node Πλειάδες Tuples και Ακολουθίες,Σύνολα Sets,Η δήλωση del,Δομές Δεδομένων
@anchor{tutorial/datastructures tuples-and-sequences}@anchor{221c}@anchor{tutorial/datastructures tut-tuples}@anchor{21f6}
@subsection Πλειάδες (Tuples) και Ακολουθίες


Είδαμε ότι οι λίστες και οι συμβολοσειρές (strings) έχουνε πολλές κοινές ιδιότητες, όπως λειτουργίες indexing και slicing.  Είναι δύο παραδείγματα τύπων δεδομένων `sequence' (δείτε @ref{221d,,Τύποι Ακολουθίας (Sequence) — list@comma{} tuple@comma{} range}).  Δεδομένου ότι η Python είναι μια εξελισσόμενη γλώσσα, άλλοι τύποι δεδομένων ακολουθίας μπορούν να προστεθούν.  Υπάρχει επίσης ένας άλλος τυπικός τύπος δεδομένων ακολουθίας type: the `πλειάδα' (`tuple').

Μια πλειάδα (tuple) αποτελείται από έναν αριθμό τιμών που χωρίζονται με κόμματα, για παράδειγμα:

@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])
>>> # they support unpacking just like lists:
>>> x = [1, 2, 3]
>>> 0, *x, 4
(0, 1, 2, 3, 4)
@end example

Όπως βλέπετε, οι πλειάδες (tuples) στην έξοδο περικλείονται πάντα σε παρενθέσεις, έτσι ώστε οι ένθετε πλειάδες (tuples) να ερμηνεύονται σωστά∙ μπορούν να εισαχθούν με ή χωρίς περιβάλλουσες παρενθέσεις, αν και συχνά οι παρενθέσεις είναι απαραίτητες ούτως ή άλλως (αν η πλειάδα είναι μέρος μιας μεγαλύτερης έκφρασης).  Δεν είναι δυνατή η αντιστοίχιση σε μεμονωμένα στοιχεία μιας πλειάδας, ωστόσο είναι δυνατό να δημιουργηθούν πλειάδες (tuples) που περιέχουν μεταβλητά αντικείμενα, όπως λίστες.

Αν και οι πλειάδες (tuples) μπορεί να φαίνονται παρόμοιες με λίστες, χρησιμοποιούνται συχνά σε διαφορετικές καταστάσεις και για διαφορετικούς σκοπούς. Οι πλειάδες (tuples) είναι @ref{181,,immutable}, και συνήθως περιέχουν μια ετερογενή ακολουθία στοιχείων στα οποία η πρόσβαση γίνεται μέσω unpacking (δείτε παρακάτω σε αυτήν την ενότητα) ή το indexing (ή ακόμα και κατά χαρακτηριστικό στην περίπτωση @ref{1cf,,namedtuples}). Οι λίστες είναι @ref{21d1,,mutable}, και τα στοιχεία τους είναι συνήθως ομοιογενή και προσπελάζονται με επανάληψη στη λίστα.

Ένα ειδικό πρόβλημα είναι η κατασκευή πλειάδων (tuples) που περιέχουν 0 ή 1 στοιχεία: η σύνταξη έχει κάποιες επιπλέον ιδιορρυθμίες για να τις προσαρμόσει.  Οι κενές πλειάδες κατασκευάζονται από ένα κενό ζευγάρι παρενθέσεων, μια πλειάδα (tuple) με ένα στοιχείο δημιουργείται ακολουθώντας μια τιμή με κόμμα (δεν αρκεί να περικλείεται μια μόνο τιμή σε παρενθέσεις). Άσχημο, αλλά αποτελεσματικό.  Για παράδειγμα:

@example
>>> empty = ()
>>> singleton = 'hello',    # <-- note trailing comma
>>> len(empty)
0
>>> len(singleton)
1
>>> singleton
('hello',)
@end example

Η δήλωση @code{t = 12345, 54321, 'hello!'} είναι ένα παράδειγμα `tuple packing': οι τιμές @code{12345}, @code{54321} και @code{'hello!'} είναι συσκευασμένες μαζί σε μια πλειάδα (tuple). Η αντίστροφη λειτουργία είναι επίσης εφικτή:

@example
>>> x, y, z = t
@end example

Αυτό ονομάζεται, αρκετά σωστά, `sequence unpacking' και λειτουργεί για οποιαδήποτε ακολουθία στη δεξιά πλευρά.  Το sequence unpacking απαιτεί να υπάρχουν τόσες μεταβλητές στην αριστερή πλευρά του συμβόλου ισότητας όσα στοιχεία υπάρχουν στην ακολουθία.  Σημείωση ότι η πολλαπλή ανάθεση είναι στην πραγματικότητα απλώς ένας συνδυασμός tuple packing και sequence unpacking.

@node Σύνολα Sets,Λεξικά Dictionaries,Πλειάδες Tuples και Ακολουθίες,Δομές Δεδομένων
@anchor{tutorial/datastructures sets}@anchor{221e}@anchor{tutorial/datastructures tut-sets}@anchor{221f}
@subsection Σύνολα (Sets)


Η Python περιλαμβάνει επίσης έναν τύπο δεδομένων για @ref{2220,,sets}.  Ένα set είναι μια μη ταξινομημένη συλλογή χωρίς διπλότυπα στοιχεία.  Οι βασικές χρήσεις περιλαμβάνουν τη δοκιμή ιδιότητας μέλους και την εξάλειψη διπλότυπων εγγραφών.  Τα αντικείμενα συνόλου υποστηρίζουν επίσης μαθηματικές πράξεις όπως ένωση, τομή, διαφορά και συμμετρική διαφορά.

Τα άγκιστρα ή η συνάρτηση @ref{42b,,set()} μπορούν να χρησιμοποιηθούν για τη δημιουργία συνόλων.  Σημείωση: για να δημιουργήσετε ένα κενό σύνολο πρέπει να χρησιμοποιήσετε το @code{set()}, όχι το @code{@{@}} ∙ το τελευταίο δημιουργεί ένα κενό λεξικό, μια δομή δεδομένων που θα συζητήσουμε στην επόμενη ενότητα.

Because sets are unordered, iterating over them or printing them can
produce the elements in a different order than you expect.

Ακολουθεί μια σύντομη επίδειξη:

@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

Similarly to @ref{2217,,list comprehensions}, set comprehensions
are also supported, including comprehensions with unpacking:

@example
>>> a = @{x for x in 'abracadabra' if x not in 'abc'@}
>>> a
@{'r', 'd'@}

>>> fruits = [@{'apple', 'avocado', 'apricot'@}, @{'banana', 'blueberry'@}]
>>> @{*fruit for fruit in fruits@}
@{'blueberry', 'banana', 'avocado', 'apple', 'apricot'@}
@end example

@node Λεξικά Dictionaries,Τεχνικές Looping,Σύνολα Sets,Δομές Δεδομένων
@anchor{tutorial/datastructures dictionaries}@anchor{2221}@anchor{tutorial/datastructures tut-dictionaries}@anchor{2222}
@subsection Λεξικά (Dictionaries)


Ένα άλλος χρήσιμος τύπος δεδομένων που είναι ενσωματωμένος στην Python είναι το `dictionary' (βλ. @ref{e8c,,Mapping types — dict@comma{} frozendict}). Τα λεξικά βρίσκονται μερικές φορές σε άλλες γλώσσες ως «συσχετιστικές μνήμες» ή «συσχετιστικοί πίνακες». Σε αντίθεση με τις ακολουθίες, οι οποίες είναι με indexes με ένα εύρος αριθμών, τα λεξικά γίνονται index με `keys', που μπορεί να είναι οποιοσδήποτε αμετάβλητος τύπος∙ οι συμβολοσειρές και οι αριθμοί μπορούν πάντα να είναι κλειδιά.  Οι πλειάδες (tuples) μπορούν να χρησιμοποιηθούν ως κλειδιά εάν περιέχουν μόνο συμβολοσειρές, αριθμούς ή πλειάδες (tuples)∙ εάν μια πλειάδα περιέχει οποιοδήποτε μεταβλητό αντικείμενο είτε άμεσα είτε έμμεσα, δεν μπορεί να χρησιμοποιηθεί ως κλειδί. Δεν μπορείτε να χρησιμοποιήσετε λίστες ως κλειδιά, καθώς οι λίστες μπορούν να τροποποιηθούν επιτόπου χρησιμοποιώντας αναθέσεις index, αναθέσεις slice, ή μεθόδους όπως @ref{aba,,append()} και @ref{7f8,,extend()}.

Είναι καλύτερο να σκεφτείτε ένα λεξικό ως ένα σύνολο ζευγών `key: value', με την προϋπόθεση ότι τα κλειδιά είναι μοναδικά (σε ένα λεξικό). Ένα ζεύγος αγκύλων δημιουργεί ένα κενό λεξικό: @code{@{@}}. Η τοποθέτηση μιας λίστας ζευγών key:value στο λεξικό, αυτός είναι επίσης ο τρόπος με τον οποίο γράφονται τα λεξικά στην έξοδο.

Οι κύριες λειτουργίες σε ένα λεξικό είναι η αποθήκευση μιας τιμής με κάποιο κλειδί και η εξαγωγή της τιμής που δίνεται στο κλειδί.  Είναι επίσης δυνατή η διαγραφή ενός ζεύγους key:value με @code{del}. Εάν αποθηκεύετε χρησιμοποιώντας ένα κλειδί που βρίσκεται ήδη σε χρήση, η παλιά τιμή που σχετίζεται με αυτό το κλειδί έχει ξεχαστεί.

Η εξαγωγή μιας τιμής για ένα μη υπάρχον κλειδί με δεικτοδότηση (@code{d[key]}) προκαλεί ένα @ref{7df,,KeyError}. Για να αποφύγετε αυτό το σφάλμα όταν προσπαθείτε να αποκτήσετε πρόσβαση σε ένα πιθανώς μη υπάρχον κλειδί, χρησιμοποιήστε αντίθετα τη μέθοδο @ref{2223,,get()}, η οποία επιστρέφει @code{None} (ή μια καθορισμένη προεπιλεγμένη τιμή) εάν το κλειδί δεν βρίσκεται στο λεξικό.

Η εκτέλεση του @code{list(d)} σε ένα λεξικό επιστρέφει μια λίστα με όλα τα κλειδιά που χρησιμοποιούνται στο λεξικό, με σειρά εισαγωγής (αν θέλετε να ταξινομηθεί, απλώς χρησιμοποιήστε το @code{sorted(d)}). Για να ελέγξετε εάν υπάρχει ένα μεμονωμένο κλειδί στο λεξικό, χρησιμοποιήστε τη λέξη-κλειδί @ref{323,,in}.

Ακολουθεί ένα μικρό παράδειγμα χρησιμοποιώντας ένα λεξικό:

@example
>>> tel = @{'jack': 4098, 'sape': 4139@}
>>> tel['guido'] = 4127
>>> tel
@{'jack': 4098, 'sape': 4139, 'guido': 4127@}
>>> tel['jack']
4098
>>> tel['irv']
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 'irv'
>>> print(tel.get('irv'))
None
>>> 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

Ο constructor @ref{188,,dict()} δημιουργεί λεξικά απευθείας από ακολουθίες ζευγών key-value:

@example
>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
@{'sape': 4139, 'guido': 4127, 'jack': 4098@}
@end example

Επιπλέον, τα comprehensions λεξικών μπορούν να χρησιμοποιηθούν για τη δημιουργία λεξικών από αυθαίρετες εκφράσεις κλειδιού και τιμών:

@example
>>> @{x: x**2 for x in (2, 4, 6)@}
@{2: 4, 4: 16, 6: 36@}
@end example

And dictionary unpacking (via @code{**}) can be used to merge multiple
dictionaries:

@example
>>> odds = @{i: i**2 for i in (1, 3, 5)@}
>>> evens = @{i: i**2 for i in (2, 4, 6)@}
>>> @{**odds, **evens@}
@{1: 1, 3: 9, 5: 25, 2: 4, 4: 16, 6: 36@}

>>> all_values = [odds, evens, @{0: 0@}]
>>> @{**i for i in all_values@}
@{1: 1, 3: 9, 5: 25, 2: 4, 4: 16, 6: 36, 0: 0@}
@end example

Όταν τα κλειδιά είναι απλές συμβολοσειρές, μερικές φορές είναι πιο εύκολο να ορίσετε ζεύγη χρησιμοποιώντας ορίσματα λέξεων-κλειδιών:

@example
>>> dict(sape=4139, guido=4127, jack=4098)
@{'sape': 4139, 'guido': 4127, 'jack': 4098@}
@end example

@node Τεχνικές Looping,Περισσότερα για τις συνθήκες,Λεξικά Dictionaries,Δομές Δεδομένων
@anchor{tutorial/datastructures looping-techniques}@anchor{2224}@anchor{tutorial/datastructures tut-loopidioms}@anchor{21e0}
@subsection Τεχνικές Looping


Κατά το looping μέσω λεξικών, το κλειδί και η αντίστοιχη τιμή μπορούν να ανακτηθούν ταυτόχρονα χρησιμοποιώντας τη μέθοδο @ref{baf,,items()}.

@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

Κατά το looping μέσω ακολουθίας, ο δείκτης θέσης και η αντίστοιχη τιμή μπορούν να ανακτηθούν ταυτόχρονα χρησιμοποιώντας τη συνάρτηση @ref{1823,,enumerate()}.

@example
>>> for i, v in enumerate(['tic', 'tac', 'toe']):
...     print(i, v)
...
0 tic
1 tac
2 toe
@end example

Για να κάνετε loop σε δύο ή περισσότερες ακολουθίες ταυτόχρονα, οι καταχωρίσεις μπορούν να αντιστοιχιστούν με τη συνάρτηση @ref{43f,,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

Για να κάνετε loop σε μια ακολουθία αντίστροφα, καθορίστε πρώτα την ακολουθία προς τα εμπρός και μετά καλέστε τη συνάρτηση @ref{c3c,,reversed()}.

@example
>>> for i in reversed(range(1, 10, 2)):
...     print(i)
...
9
7
5
3
1
@end example

Για να κάνετε loop σε μια ακολουθία με ταξινομημένη σειρά, χρησιμοποιήστε τη συνάρτηση @ref{f8c,,sorted()}, η οποία επιστρέφει μια νέα ταξινομημένη λίστα αφήνοντας την πηγή αναλλοίωτη.

@example
>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for i in sorted(basket):
...     print(i)
...
apple
apple
banana
orange
orange
pear
@end example

Η χρήση του @ref{42b,,set()} σε μια ακολουθία εξαλείφει τα διπλά στοιχεία. Η χρήση του @ref{f8c,,sorted()} σε συνδυασμό με το @code{set()} σε μια ακολουθία είναι ένας ιδιωματικός τρόπος για να κάνετε loop πάνω από μοναδικά στοιχεία της ακολουθίας σε ταξινομημένη σειρά.

@example
>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for f in sorted(set(basket)):
...     print(f)
...
apple
banana
orange
pear
@end example

Μερικές φορές είναι δελεαστικό να αλλάζετε μια λίστα ενώ την περιηγείστε∙ ωστόσο, είναι συχνά πιο απλό και ασφαλές να δημιουργήσετε μια νέα λίστα.

@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 Περισσότερα για τις συνθήκες,Σύγκριση ακολουθιών και άλλων τύπων,Τεχνικές Looping,Δομές Δεδομένων
@anchor{tutorial/datastructures more-on-conditions}@anchor{2225}@anchor{tutorial/datastructures tut-conditions}@anchor{2226}
@subsection Περισσότερα για τις συνθήκες


Οι συνθήκες που χρησιμοποιούνται στις δηλώσεις @code{while} και @code{if} μπορούν να περιέχουν οποιουσδήποτε τελεστές, όχι μόνο συγκρίσεις.

Οι τελεστές σύγκρισης @code{in} και @code{not in} είναι δοκιμές ιδιότητας μέλους που καθορίζουν εάν μια τιμή βρίσκεται (ή όχι σε) ένα container.  Οι τελεστές @code{is} και @code{is not} συγκρίνουν εάν δύο αντικείμενα είναι πραγματικά το ίδιο αντικείμενο.  Όλοι οι τελεστές σύγκρισης έχουν την ίδια προτεραιότητα, η οποία είναι χαμηλότερη από αυτή όλων των αριθμητικών τελεστών.

Οι συγκρίσεις μπορούν να είναι αλυσιδωτές.  Για παράδειγμα, @code{a < b == c} ελέγχει εάν το @code{a} είναι μικρότερο από @code{b} και επιπλέον το @code{b} ισούται με @code{c}.

Οι συγκρίσεις μπορούν να συνδυαστούν χρησιμοποιώντας τους λογικούς τελεστές @code{and} και @code{or}, και το αποτέλεσμα μιας σύγκρισης (ή οποιασδήποτε άλλης λογικής έκφρασης) μπορεί να ακυρωθεί με @code{not}.  Αυτοί έχουν χαμηλότερες προτεραιότητες μεταξύ των τελεστών σύγκρισης, το @code{not} έχει την υψηλότερη προτεραιότητα και το @code{or} τη χαμηλότερη, έτσι ώστε το @code{A and not B or C} ισοδυναμεί με @code{(A and (not B)) or C}. Όπως πάντα, οι παρενθέσεις μπορούν να χρησιμοποιηθούν για να εκφράσουν την επιθυμητή σύνθεση.

Οι λογικοί τελεστές @code{and} και @code{or} είναι οι λεγόμενοι τελεστές `short-circuit': τα ορίσματα τους αξιολογούνται από αριστερά προς τα δεξιά και η αξιολόγηση σταματά μόλις καθοριστεί το αποτέλεσμα.  Για παράδειγμα, εάν το @code{A} and @code{C} είναι αληθές, αλλά το @code{B} είναι ψευδές, το @code{A and B and C} δεν αξιολογεί την έκφραση @code{C}.  Όταν χρησιμοποιείται ως γενική τιμή και όχι ως λογική, η τιμή επιστροφής ενός short-circuit τελεστή είναι το τελευταίο αξιολογημένο όρισμα.

Είναι δυνατό να αντιστοιχίσετε το αποτέλεσμα μιας σύγκρισης ή άλλη δυαδική έκφρασης σε μια μεταβλητή.  Για παράδειγμα,

@example
>>> string1, string2, string3 = '@w{'}, 'Trondheim', 'Hammer Dance'
>>> non_null = string1 or string2 or string3
>>> non_null
'Trondheim'
@end example

Σημειώστε ότι στην Python, σε αντίθεση με την C, η ανάθεση εντός των εκφράσεων πρέπει να γίνεται ρητά με τον τελεστή @ref{2227,,walrus operator} @code{:=}. Αυτό αποφεύγει μια κοινή κατηγορία προβλημάτων που συναντώνται στα προγράμματα C: πληκτρολογώντας @code{=} σε μια έκφραση όταν προοριζόταν το @code{==}.

@node Σύγκριση ακολουθιών και άλλων τύπων,,Περισσότερα για τις συνθήκες,Δομές Δεδομένων
@anchor{tutorial/datastructures comparing-sequences-and-other-types}@anchor{2228}@anchor{tutorial/datastructures tut-comparing}@anchor{2229}
@subsection Σύγκριση ακολουθιών και άλλων τύπων


Τα αντικείμενα ακολουθίας μπορούν συνήθως να συγκριθούν με άλλα αντικείμενα με τον ίδιο τύπο ακολουθίας. Η σύγκριση χρησιμοποιεί `lexicographical' σειρά: πρώτα συγκρίνονται τα δύο πρώτα στοιχεία και αν διαφέρουν αυτό καθορίζει το αποτέλεσμα της σύγκρισης∙ εάν είναι ίσα, τα επόμενα δύο στοιχεία συγκρίνονται και ούτω καθεξής, έως ότου εξαντληθεί η μία από τις δύο ακολουθίες. Εάν δύο στοιχεία προς σύγκριση είναι τα ίδια ακολουθίες του ίδιου τύπου, η λεξικογραφική σύγκριση πραγματοποιείται αναδρομικά.  Εάν όλα τα στοιχεία δύο ακολουθιών συγκρίνονται ίσα, οι ακολουθίες θεωρούνται ίσες. Εάν η μια ακολουθία είναι αρχική υποακολουθία της άλλης, η μικρότερη ακολουθία είναι η μικρότερη (ελάχιστη).  Η λεξικογραφική ταξινόμηση συμβολοσειρών χρησιμοποιεί τον αριθμό κωδικού σημείου Unicode για να ταξινομήσει μεμονωμένους χαρακτήρες. Μερικά παραδείγματα συγκρίσεων μεταξύ ακολουθιών του ίδιου τύπου:

@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

Λάβετε υπόψη ότι η σύγκριση αντικειμένων διαφορετικών τύπων με @code{<} ή @code{>} είναι νόμιμη υπό τον όρο ότι τα αντικείμενα διαθέτουν κατάλληλες μεθόδους σύγκρισης.  Για παράδειγμα, οι μικτές αριθμητικοί τύποι συγκρίνονται σύμφωνα με την αριθμητική τους τιμή, οπότε το 0 ισούται με 0.0, κλπ.  Διαφορετικά, αντί να παρέχει μια αυθαίρετη παραγγελία, ο διερμηνέας θα κάνει raise μια εξαίρεση @ref{291,,TypeError}.

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Modules<2>,Είσοδος και Έξοδος,Δομές Δεδομένων,Οδηγός εκμάθησης Python
@anchor{tutorial/modules doc}@anchor{222a}@anchor{tutorial/modules modules}@anchor{222b}@anchor{tutorial/modules translation-repo}@anchor{222c}@anchor{tutorial/modules tut-modules}@anchor{222d}
@section Modules


Εάν βγείτε από τον interpreter της Python και μπείτε ξανά, οι ορισμοί που έχετε κάνει (συναρτήσεις και μεταβλητές) χάνονται.  Επομένως, εάν θέλετε να γράψετε ένα κάπως μεγαλύτερο πρόγραμμα, είναι προτιμότερο να χρησιμοποιήσετε έναν επεξεργαστή κειμένου για να προετοιμάσετε την εισαγωγή για τον interpreter και την εκτέλεση του με αυτό το αρχείο ως input.  Αυτό είναι γνωστό ως δημιουργία `script'.  Καθώς το πρόγραμμα σας μεγαλώνει, μπορεί να θέλετε να το χωρίσετε σε πολλά αρχεία για ευκολότερη συντήρηση.  Μπορεί επίσης να θέλετε να χρησιμοποιήσετε μια εύχρηστη συνάρτηση που έχετε γράψει σε πολλά προγράμματα χωρίς να αντιγράψετε τον ορισμό της σε κάθε πρόγραμμα.

Για να το υποστηρίξει αυτό, η Python έχει έναν τρόπο να βάζει ορισμούς σε ένα αρχείο και να τους χρησιμοποιεί σε ένα script ή σε ένα διαδραστικό instance του interpreter.  Ένα τέτοιο αρχείο ονομάζεται `module*∙ ορισμοί από μια ενότητα μπορούν να *εισαχθούν' σε άλλα modules ή στο `κύριο' module (η συλλογή των μεταβλητών στις οποίες έχετε πρόσβαση σε ένα script που εκτελείται στον ανώτερο επίπεδο και σε λειτουργία αριθμομηχανής).

Ένα module είναι ένα αρχείο που περιέχει ορισμούς και δηλώσεις Python.  Το όνομα αρχείου είναι το όνομα του module με το επίθημα @code{.py}.  Μέσε σε ένα module, το όνομα του module (ως συμβολοσειρά) είναι διαθέσιμο ως τιμή της global μεταβλητής @code{__name__}.  Για παράδειγμα, χρησιμοποιήστε το αγαπημένος σας πρόγραμμα επεξεργασίας κειμένου για να δημιουργήσετε ένα αρχείο που ονομάζεται @code{fibo.py} στον τρέχοντα κατάλογο με τα ακόλουθα περιεχόμενα:

@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

Τώρα εισάγετε τον Python interpreter και εισάγετε αυτό το module με την ακόλουθη εντολή:

@example
>>> import fibo
@end example

Αυτό δεν προσθέτει τα ονόματα των συναρτήσεων που ορίζονται στο @code{fibo}  απευθείας στον τρέχοντα @ref{222e,,namespace} (βλ. @ref{222f,,Εμβέλεια και Πεδία Ονομάτων στην Python} για περισσότερες λεπτομέρειες): προσθέτει μόνο το όνομα του module @code{fibo} εκεί. Χρησιμοποιώντας το όνομα του 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

Εάν σκοπεύετε να χρησιμοποιείτε συχνά μια συνάρτηση, μπορείτε να την αντιστοιχίσετε σε ένα τοπικό όνομα:

@example
>>> fib = fibo.fib
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377
@end example

@menu
* Περισσότερα για τα Modules:: 
* Standard Modules:: 
* Η συνάρτηση dir(): Η συνάρτηση dir. 
* Πακέτα:: 

@end menu

@node Περισσότερα για τα Modules,Standard Modules,,Modules<2>
@anchor{tutorial/modules more-on-modules}@anchor{2230}@anchor{tutorial/modules tut-moremodules}@anchor{2231}
@subsection Περισσότερα για τα Modules


Ένα module μπορεί να περιέχει εκτελέσιμες δηλώσεις καθώς και ορισμούς συναρτήσεων. Αυτές οι δηλώσεις προορίζονται για την προετοιμασία του module. Εκτελούνται μόνο την `πρώτη' φορά που εμφανίζεται το όνομα του module σε μια δήλωση εισαγωγής. @footnote{
Στην πραγματικότητα, οι ορισμοί συναρτήσεων είναι επίσης “statements” που “εκτελούνται”∙ η εκτέλεση ενός ορισμού συνάρτησης σε επίπεδο module προσθέτει το όνομα της συνάρτησης στον καθολικό namespace του module.
} (Εκτελούνται επίσης εάν το αρχείο εκτελείται ως script.)

Κάθε module έχει τον δικό της ιδιωτικό namespace, ο οποίος χρησιμοποιείται ως global namespace από όλες τις συναρτήσεις που ορίζονται στο module. Έτσι, ο συντάκτης μιας ενότητας μπορεί να χρησιμοποιήσει global μεταβλητές στο module χωρίς να ανησυχεί για τυχαία conflicts με τις global μεταβλητές του χρήστη. Από την άλλη πλευρά, εάν ξέρετε τι κάνετε, μπορείτε να αγγίξετε τις global μεταβλητές ενός module με το ίδιο notation που χρησιμοποιείται για να αναφέρεται στις συναρτήσεις, @code{modname.itemname}.

Τα modules μπορούν να εισάγουν άλλα modules.  Είναι σύνηθες, αλλά δεν απαιτείται να τοποθετούνται όλες οι δηλώσεις @ref{9da,,import} στην αρχή μιας ενότητα (ή σεναρίου, για αυτό το θέμα).  Τα ονόματα των modules που εισάγονται, εάν τοποθετούνται στο ανώτερο επίπεδο του ένα module (εκτός οποιωνδήποτε συναρτήσεων ή κλάσεων), προστίθενται στον global namespace του module.

Υπάρχει μια παραλλαγή της δήλωσης @ref{9da,,import} που εισάγει ονόματα από ένα module απευθείας στον χώρο στα importing module’s namespace.  Για παράδειγμα:

@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

Αυτό δεν εισάγει το όνομα ενός module από το οποίο λαμβάνονται οι εισαγωγές στο τοπικό namespace (αρά στο παράδειγμα, το @code{fibo} δεν ορίζεται).

Υπάρχει ακόμη και μια παραλλαγή για την εισαγωγή όλων των ονομάτων που ορίζει μια ενότητα:

@example
>>> from fibo import *
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377
@end example

Αυτό εισάγει όλα τα ονόματα εκτός από αυτά που ξεκινούν με κάτω παύλα (@code{_}). Στις περισσότερες περιπτώσεις, οι προγραμματιστές Python δεν χρησιμοποιούν αυτήν την δυνατότητα , καθώς εισάγει ένα άγνωστο σύνολο ονομάτων στον interpreter, κρύβοντας πιθανώς κάποια πράγματα που έχετε ήδη ορίσει.

Λάβετε υπόψη ότι γενικά η πρακτική της εισαγωγής @code{*} από ένα module ή ένα πακέτο αποδοκιμάζεται, καθώς προκαλεί συχνά κακώς αναγνώσιμο κώδικα. Ωστόσο, είναι εντάξει να τον χρησιμοποιήσετε για να αποθηκεύσετε την πληκτρολόγηση σε διαδραστικές περιόδους σύνδεσης.

Εάν το όνομα του module ακολουθείται από @code{as}, τότε το όνομα που ακολουθεί @code{as} συνδέεται απευθείας με το εισαγόμενο module.

@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

Αυτό ουσιαστικά εισάγει το module με τον ίδιο τρόπο που θα κάνει το @code{import fibo} , με τη μόνη διαφορά ότι είναι διαθέσιμο ως @code{fib}.

Μπορεί επίσης να χρησιμοποιηθεί όταν χρησιμοποιείτε @ref{1650,,from} με παρόμοια εφέ:

@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 Σημείωση 
Για λόγους αποτελεσματικότητας, κάθε module εισάγεται μόνο μία φορά ανά περίοδο λειτουργίες του interpreter.  Επομένως, εάν αλλάξετε τα modules σας, πρέπει να επανεκκινήσετε τον διερμηνέα – ή, εάν είναι μόνο ένα module που θέλετε να δοκιμάσετε διαδραστικά, χρησιμοποιήστε το @ref{928,,importlib.reload()}, π.χ. @code{import importlib; importlib.reload(modulename)}.
@end quotation
@end cartouche

@menu
* Εκτέλεση modules ως scripts:: 
* Το Search Path του Module:: 
* «Compiled» Python αρχεία:: 

@end menu

@node Εκτέλεση modules ως scripts,Το Search Path του Module,,Περισσότερα για τα Modules
@anchor{tutorial/modules executing-modules-as-scripts}@anchor{2232}@anchor{tutorial/modules tut-modulesasscripts}@anchor{2233}
@subsubsection Εκτέλεση modules ως scripts


Όταν εκτελείτε ένα Python module με:

@example
python fibo.py <arguments>
@end example

ο κώδικας στο module θα εκτελεστεί, ακριβώς σαν να τον εισαγάγετε, αλλά με το @code{name} να έχει οριστεί σε @code{"__main__"}.  Αυτό σημαίνει ότι προσθέτοντας αυτόν τον κώδικα στο τέλος του module σας:

@example
if __name__ == "__main__":
    import sys
    fib(int(sys.argv[1]))
@end example

μπορείτε να κάνετε το αρχείο χρησιμοποιήσιμο ως script καθώς και ως module που μπορεί να εισαχθεί, επειδή ο κώδικας που αναλύει την γραμμή εντολών εκτελείται μόνο εάν το module εκτελείται ως το «main» αρχείο:

@example
$ python fibo.py 50
0 1 1 2 3 5 8 13 21 34
@end example

Εάν το module έχει εισαχθεί, ο κώδικας δεν εκτελείται:

@example
>>> import fibo
>>>
@end example

Αυτό χρησιμοποιείται συχνά είτε για την παροχή ενός βολικού user interface σε ένα module, είτε για σκοπούς δοκιμής (η εκτέλεση του module ως script εκτελεί μια δοκιμαστική σουίτα).

@node Το Search Path του Module,«Compiled» Python αρχεία,Εκτέλεση modules ως scripts,Περισσότερα για τα Modules
@anchor{tutorial/modules the-module-search-path}@anchor{2234}@anchor{tutorial/modules tut-searchpath}@anchor{2235}
@subsubsection Το Search Path του Module


@geindex module;αναζήτηση;path

Όταν εισάγετε ένα module με το όνομα @code{spam}, ο interpreter αναζητά πρώτα ένα ενσωματωμένο module με αυτό το όνομα. Αυτά τα ονόματα των module παρατίθενται στο @ref{2236,,sys.builtin_module_names}. Εάν δεν βρεθεί, τότε αναζητά ένα αρχείο με το όνομα @code{spam.py} σε μια λίστα καταλόγων που δίνονται από τη μεταβλητή @ref{194,,sys.path}.  Το @code{sys.path} αρχικοποιείται από αυτές τις θέσεις:


@itemize *

@item 
Ο κατάλογος που περιέχει το input script (ή τον τρέχοντα κατάλογο όταν δεν έχει καθοριστεί αρχείο).

@item 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} (μια λίστα ονομάτων καταλόγου, με την ίδια σύνταξη με τη μεταβλητή του shell 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}).

@item 
Η προεπιλογή που εξαρτάται από την εγκατάσταση (κατά σύμβαση, συμπεριλαμβανομένου ενός καταλόγου @code{site-packages}, που χειρίζεται το module @ref{cf,,site}.
@end itemize

Περισσότερες λεπτομέρειες βρίσκονται στο @ref{1953,,The initialization of the sys.path module search path}.

@cartouche
@quotation Σημείωση 
Στα συστήματα αρχείων που υποστηρίζουν symlinks, ο κατάλογο που περιέχει το input script υπολογίζεται αφού ακολουθηθεί το symlink. Με άλλα λόγια, ο κατάλογος που περιέχει το symlink `δεν' προστίθεται στη διαδρομή αναζήτησης του module.
@end quotation
@end cartouche

Μετά την προετοιμασία, τα προγράμματα Python μπορούν να τροποποιήσουν το @ref{194,,sys.path}.  Ο κατάλογος που περιέχει το script που εκτελείται τοποθετείται στην αρχή της διαδρομής αναζήτησης , μπροστά από την τυπική διαδρομή της βιβλιοθήκης. Αυτό σημαίνει ότι τα scripts σε αυτόν τον κατάλογο θα είναι φορτωμένα αντί για τα modules με το ίδιο όνομα στον κατάλογο μιας βιβλιοθήκης. Αυτό είναι ένα σφάλμα, εκτός εάν προορίζεται η αντικατάσταση.  Βλ. την ενότητα @ref{2237,,Standard Modules} για περισσότερες πληροφορίες.

@c %
@c Do we need stuff on zip files etc. ? DUBOIS

@node «Compiled» Python αρχεία,,Το Search Path του Module,Περισσότερα για τα Modules
@anchor{tutorial/modules compiled-python-files}@anchor{2238}@anchor{tutorial/modules tut-pycache}@anchor{ac9}
@subsubsection «Compiled» Python αρχεία


Για να επιταχύνει τη φόρτωση modules, η Python κάνει cache την compiled έκδοση κάθε module στον κατάλογο @code{__pycache__} κάτω από το όνομα @code{module.`version'.pyc}, όπου η έκδοση κωδικοποιεί τη μορφή του compiled αρχείου∙ γενικά περιέχει τον αριθμό έκδοσης της Python.  Για παράδειγμα, στην έκδοση CPython 3.3 η compiled έκδοση του spam.py θα αποθηκευτεί ως @code{__pycache__/spam.cpython-33.pyc}.  Αυτή η σύμβαση ονομασίας, επιτρέπει σε compiled modules από διαφορετικές εκδόσεις και διαφορετικές εκδόσεις της Python να συνυπάρχουν.

Η Python ελέγχει την ημερομηνία τροποποίησης του πηγαίου έναντι της compiled έκδοσης για να δει εάν είναι ξεπερασμένη και χρειάζεται να γίνει compile ξανά.  Αυτή είναι μια εντελώς αυτόματη διαδικασία.  Επίσης, τα compiled modules είναι ανεξάρτητες από πλατφόρμα, επομένως η ίδια βιβλιοθήκη μπορεί να κοινοποιηθεί ανάμεσα σε συστήματα με διαφορετικές αρχιτεκτονικές.

Η Python δεν ελέγχει την cache σε δύο περιπτώσεις.  Πρώτον, πάντα κάνει compile ξανά και δεν αποθηκεύει το αποτέλεσμα για το module που φορτώνεται απευθείας από τη γραμμή εντολών.  Δεύτερον, δεν ελέγχει τη μνήμη cache εάν δεν υπάρχει το source module.  Για να υποστηρίξετε μια διανομή χωρίς πηγαίο (compiled μόνο), το compiled module πρέπει να βρίσκεται στον source κατάλογο και δεν πρέπει να υπάρχει source module.

Μερικές συμβουλές για ειδικούς:


@itemize *

@item 
Μπορείτε να χρησιμοποιήσετε τους switches @ref{431,,-O} ή @ref{116e,,-OO} στην εντολή Python για να μειώσετε το μέγεθος ενός compiled module.  Το @code{-O} switch αφαιρεί τις assert statements, το @code{-OO} switch αφαιρεί τόσο τα assert statements όσο και τις __doc__ συμβολοσειρές . Εφόσον ορισμένα προγράμματα μπορεί να βασίζονται στην ύπαρξη αυτών των διαθέσιμων, θα πρέπει να χρησιμοποιήσετε αυτήν την επιλογή μόνο εάν γνωρίζετε τι κάνετε.  «Optimized» modules έχουν ένα @code{opt-} tag και είναι συνήθως μικρότερες.  Οι μελλοντικές εκδόσεις μπορεί να αλλάξουν τα αποτελέσματα της βελτιστοποίησης.

@item 
Ένα πρόγραμμα δεν εκτελείται πιο γρήγορα όταν διαβάζεται από ένα αρχείο @code{.pyc} από ό,τι όταν διαβάζεται από ένα αρχείο @code{.py} ∙ το μόνο πράγμα που είναι πιο γρήγορο από τα αρχεία @code{.pyc} είναι η ταχύτητα με την οποία φορτώνονται.

@item 
Το module @ref{21,,compileall} μπορεί να δημιουργήσει αρχεία .pyc για όλα τα modules σε ένα κατάλογο.

@item 
Υπάρχουν περισσότερες λεπτομέρειες σχετικά με αυτή τη διαδικασία, συμπεριλαμβανομένου ενός διαγράμματος ροής των αποφάσεων, στο 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}.
@end itemize

@node Standard Modules,Η συνάρτηση dir,Περισσότερα για τα Modules,Modules<2>
@anchor{tutorial/modules standard-modules}@anchor{2239}@anchor{tutorial/modules tut-standardmodules}@anchor{2237}
@subsection Standard Modules


@geindex module;sys

Η Python συνοδεύεται από μια βιβλιοθήκη standard modules, η οποία περιγράφεται σε ένα ξεχωριστό έγγραφο, την Αναφορά Βιβλιοθήκης Python («Library Reference» hereafter).  Ορισμένα modules είναι ενσωματωμένα στον interpreter∙ αυτές παρέχουν πρόσβαση σε λειτουργίες που δεν αποτελούν μέρος του πυρήνα της γλώσσας, αλλά εντούτοις είναι ενσωματωμένα, είτε για αποτελεσματικότητα είτε για την παροχή πρόσβασης σε πρωτόγονα στοιχεία του λειτουργικού συστήματος όπως οι κλήσεις συστήματος.  Το σύνολο τέτοιων modules είναι μια επιλογή διαμόρφωσης που εξαρτάται επίσης από την υποκείμενη πλατφόρμα.  Για παράδειγμα, το module @ref{11f,,winreg} παρέχεται μόνο σε συστήματα Windows.  Ένα συγκεκριμένο module που αξίζει κάποια προσοχή είναι το @ref{e2,,sys}, το οποίο είναι ενσωματωμένο στον interpreter της Python.  Οι μεταβλητές @code{sys.ps1} και @code{sys.ps2} ορίζουν τις συμβολοσειρές που χρησιμοποιούνται ως κύρια και δευτερεύοντα prompts:

@example
>>> import sys
>>> sys.ps1
'>>> '
>>> sys.ps2
'... '
>>> sys.ps1 = 'C> '
C> print('Yuck!')
Yuck!
C>
@end example

Αυτές οι δύο μεταβλητές ορίζονται μόνο εάν ο interpreter βρίσκεται σε διαδραστική λειτουργία.

Η μεταβλητή @code{sys.path} είναι μια λίστα συμβολοσειρών που καθορίζει τη διαδρομή αναζήτησης του διερμηνέα για modules. Αρχικοποιείται σε μια προεπιλεγμένη διαδρομή που λαμβάνεται από τη μεταβλητή περιβάλλοντος 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH}, ή από μια ενσωματωμένη προεπιλογή εάν το 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@code{PYTHONPATH} δεν έχει οριστεί.  Μπορείτε να το τροποποιήσετε χρησιμοποιώντας τυπικές λειτουργίες λίστας:

@example
>>> import sys
>>> sys.path.append('/ufs/guido/lib/python')
@end example

@node Η συνάρτηση dir,Πακέτα,Standard Modules,Modules<2>
@anchor{tutorial/modules the-dir-function}@anchor{223a}@anchor{tutorial/modules tut-dir}@anchor{223b}
@subsection Η συνάρτηση @code{dir()}


Η ενσωματωμένη συνάρτηση @ref{a23,,dir()} χρησιμοποιείται για να ανακαλύψει ποια ονόματα ορίζει ένα module.  Επιστρέφει μια ταξινομημένη λίστα συμβολοσειρών:

@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

Χωρίς ορίσματα, η @ref{a23,,dir()} παραθέτει τα ονόματα που έχετε ορίσει αυτήν τη στιγμή:

@example
>>> a = [1, 2, 3, 4, 5]
>>> import fibo
>>> fib = fibo.fib
>>> dir()
['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']
@end example

Λάβετε υπόψη ότι παραθέτει όλους τους τύπους ονομάτων: μεταβλητές, modules, συναρτήσεις, κ.λπ.

@geindex module;builtins

Η @ref{a23,,dir()} δεν παραθέτει τα ονόματα των ενσωματωμένων συναρτήσεων και μεταβλητών.  Εάν θέλετε μια λίστα από αυτές, ορίζονται στην τυπική ενότητα @ref{13,,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 Πακέτα,,Η συνάρτηση dir,Modules<2>
@anchor{tutorial/modules packages}@anchor{223c}@anchor{tutorial/modules tut-packages}@anchor{223d}
@subsection Πακέτα


Τα πακέτα είναι ένας τρόπος δόμησης του namespace του module χρησιμοποιώντας «dotted module names».  Για παράδειγμα, το όνομα του module @code{A.B} υποδηλώνει ένα submodule με όνομα @code{B} σε ένα πακέτο με όνομα @code{A}.  Ακριβώς όπως η χρήση των modules σώζει τους δημιουργούς διαφορετικών modules να ανησυχούν ο ένας για τα καθολικά ονόματα μεταβλητών του άλλου, η χρήση dotted module ονομάτων σώζει τους δημιουργούς των multi-module πακέτων όπως το NumbPY ή το Pillow από το να χρειάζεται να ανησυχούν ο ένας για τα module ονόματα του άλλου.

Ας υποθέσουμε ότι θέλετε να σχεδιάσετε μια συλλογή από module (ένα «πακέτο») για τον ομοιόμορφο χειρισμό αρχείων ήχου και δεδομένων ήχου.  Υπάρχουν πολλές διαφορετικές μορφές αρχείων ήχου (που συνήθως αναγνωρίζονται από την επέκτασή τους, για παράδειγμα: @code{.wav}, @code{.aiff}, @code{.au}), επομένως μπορεί να χρειαστεί να δημιουργήσετε και να διατηρήσετε μια αυξανόμενη συλλογή λειτουργιών για τη μετατροπή μεταξύ των διαφόρων μορφών αρχείων. Υπάρχουν επίσης πολλές διαφορετικές λειτουργίες που μπορεί να θέλετε να εκτελέσετε σε δεδομένα ήχου (όπως μίξη, προσθήκη ηχούς, εφαρμογή μιας λειτουργίας ισοσταθμιστή, δημιουργία τεχνητού στερεοφωνικού εφέ), επομένως επιπλέον θα γράφετε μια ατελείωτη ροή από modules για να εκτελέσετε αυτές τις λειτουργίες.  Ακολουθεί μια πιθανή δομή για το πακέτο σας (που εκφράζεται ως ιεραρχικό σύστημα αρχείων):

@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

Κατά την εισαγωγή του πακέτου, η Python πραγματοποιεί αναζήτηση στους καταλόγους στο @code{sys.path} αναζητώντας τον υποκατάλογο του πακέτου.

Τα @code{__init__.py} αρχεία απαιτούνται για να κάνει την Python να αντιμετωπίζει του καταλόγου που περιέχουν το αρχείο ως πακέτα (εκτός εάν χρησιμοποιεί ένα @ref{52e,,namespace package}, ένα σχετικά προηγμένο χαρακτηριστικό). Αυτό αποτρέπει τους καταλόγους με κοινό όνομα, όπως π.χ. ως @code{string}, από την ακούσια απόκρυψη έγκυρων modules που εμφανίζονται αργότερα στο path αναζήτησης του module. Στην απλούστερη περίπτωση, το @code{__init__.py} μπορεί απλώς να είναι κενό αρχείο, αλλά μπορεί επίσης να εκτελέσει initialization κώδικα για το πακέτο ή να ορίσει την μεταβλητή @code{__all__}, που περιγράφεται αργότερα.

Οι χρήστες του πακέτου μπορούν να εισάγουν μεμονωμένα module από το πακέτο, για παράδειγμα:

@example
import sound.effects.echo
@end example

Αυτό φορτώνει το submodule @code{sound.effects.echo}.  Πρέπει να αναφέρεται με το πλήρες όνομά του.

@example
sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)
@end example

Ένα εναλλακτικός τρόπος για την εισαγωγή του submodule είναι:

@example
from sound.effects import echo
@end example

Αυτό φορτώνει επίσης το submodule @code{echo}, και την καθιστά διαθέσιμη χωρίς το πρόθεμα πακέτου, ώστε να μπορεί να χρησιμοποιηθεί ως εξής:

@example
echo.echofilter(input, output, delay=0.7, atten=4)
@end example

Μια άλλη παραλλαγή είναι η απευθείας εισαγωγή της επιθυμητής συνάρτησης ή μεταβλητής:

@example
from sound.effects.echo import echofilter
@end example

Και πάλι, αυτό φορτώνει το submodule @code{echo}, αλλά αυτό κάνει τη συνάρτηση της @code{echofilter()} άμεσα διαθέσιμη:

@example
echofilter(input, output, delay=0.7, atten=4)
@end example

Λάβετε υπόψη ότι όταν χρησιμοποιείτε @code{from package import item}, το στοιχείο μπορεί να είναι είτε submodule (ή υποπακέτο) του πακέτου ή κάποιο άλλο όνομα που ορίζεται στο πακέτο, όπως μια συνάρτηση, κλάση ή μεταβλητή. Η @code{import} δήλωση ελέγχει πρώτα εάν το στοιχείο έχει οριστεί στο πακέτο, εάν όχι, υποθέτει ότι είναι ένα module και επιχειρεί να το φορτώσει , αν δεν το βρει δημιουργεί η εξαίρεση @ref{1bd,,ImportError}.

Αντίθετα, όταν χρησιμοποιείται σύνταξη όπως @code{import item.subitem.subsubitem}, κάθε στοιχείο εκτός από αυτό το τελευταίο πρέπει να είναι πακέτο∙ το τελευταίο στοιχείο μπορεί να είναι ένα module ή ένα πακέτο αλλά δεν μπορεί να είναι μια κλάση ή συνάρτηση ή μεταβλητή που ορίζεται από προηγούμενο στοιχείο.

@menu
* Εισάγοντας * από ένα Πακέτο:: 
* Intra-package αναφορές:: 
* Πακέτα σε Πολλαπλούς Καταλόγους:: 

@end menu

@node Εισάγοντας * από ένα Πακέτο,Intra-package αναφορές,,Πακέτα
@anchor{tutorial/modules importing-from-a-package}@anchor{223e}@anchor{tutorial/modules tut-pkg-import-star}@anchor{223f}
@subsubsection Εισάγοντας * από ένα Πακέτο


@geindex __all__

Τώρα τι συμβαίνει όταν ο χρήστης γράφει @code{from sound.effects import *};  Ιδανικά, θα ήλπιζε κανείς ότι αυτό θα βγει με κάποιο τρόπο στο σύστημα αρχείων, θα βρει κάποια submodules που υπάρχουν το πακέτο, και θα τα εισάγει όλα σε αυτό.  Αυτό θα μπορούσε να πάρει πολύ χρόνο και η εισαγωγή submodules μπορεί να έχει ανεπιθύμητες παρενέργειες που θα έπρεπε να συμβούν όταν το submodule εισάγεται ρητά.

Η μόνη λύση είναι να παρέχει ο συντάκτης του πακέτου ένα ρητό ευρετήριο του πακέτου.  Η δήλωση @ref{9da,,import} χρησιμοποιεί την ακόλουθη σύμβαση: εάν ο κώδικας @code{__init__.py} του πακέτου ορίζει μια λίστα με το όνομα @code{__all__}, θεωρείται ότι είναι η λίστα με τα ονόματα των modules που θα πρέπει να εισαχθούν όταν συναντήσετε @code{from package import *}.  Είναι στην διακριτή ευχέρεια του συντάκτη του πακέτου να διατηρεί αυτή τη λίστα ενημερωμένη, όταν κυκλοφορήσει μια νέα έκδοση του πακέτου.  Οι συντάκτες του πακέτου ενδέχεται επίσης να αποφασίσουν να μην το υποστηρίξουν, εάν δεν βλέπουν ότι χρησιμοποιείται η εισαγωγή του * από το πακέτο τους.  Για παράδειγμα το αρχείο @code{sound/effects/__init__.py} θα μπορούσε να περιέχει τον ακόλουθο κώδικα:

@example
__all__ = ["echo", "surround", "reverse"]
@end example

Αυτό θα σήμαινε ότι @code{from sound.effects import *} θα εισαγάγει τα τρία submodules με το όνομα του πακέτου @code{sound.effects}.

Λάβετε υπόψη ότι τα submodules ενδέχεται να σκιάζονται από τοπικά καθορισμένα ονόματα. Για παράδειγμα, εάν προσθέσατε μια @code{reverse} συνάρτηση στο αρχείο @code{sound/effects/__init__.py}, το @code{from sound.effects import *} θα εισαγάγει μόνο τα δύο submodules @code{echo} και @code{surround}, αλλά `όχι' το submodule @code{reverse}, επειδή επισκιάζεται από την τοπικά καθορισμένη συνάρτηση @code{reverse}:

@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

Εάν δεν έχει οριστεί το @code{__all__}, η δήλωση @code{from sound.effects import *} `δεν' εισάγει όλα τα submodules από το πακέτο @code{sound.effects} στο τρέχων namespace∙ διασφαλίζει μόνο ότι το πακέτο @code{sound.effects} έχει εισαχθεί (ενδεχομένως να εκτελείται οποιοσδήποτε κωδικός προετοιμασίας στο στο @code{__init__.py}) και στη συνέχεια εισάγει οποιαδήποτε ονόματα ορίζονται στο πακέτο. Αυτό περιλαμβάνει τυχόν ονόματα που ορίζονται (και submodules που έχουν φορτωθεί ρητά) από το @code{__init__.py}.  Περιλαμβάνει επίσης τυχόν submodules του πακέτου που φορτώθηκαν ρητά από προηγούμενες δηλώσεις @ref{9da,,import}.  Σκεφτείτε αυτόν τον κώδικα:

@example
import sound.effects.echo
import sound.effects.surround
from sound.effects import *
@end example

Σε αυτό το παράδειγμα, τα modules @code{echo} και @code{surround} εισάγονται στο τρέχον namespace επειδή ορίζονται στο πακέτο @code{sound.effects} όταν η δήλωση @code{from...import} εκτελείται.  (Αυτό λειτουργεί επίσης όταν ορίζεται το @code{__all__}).

Αν και ορισμένα modules έχουν σχεδιαστεί για να εξάγουν μόνο ονόματα που ακολουθούν ορισμένα μοτίβα όταν χρησιμοποιείτε το @code{import *}, εξακολουθεί να θεωρείται κακή πρακτική στον κώδικα παραγωγής.

Θυμηθείτε, δεν υπάρχει τίποτα κακό με τη χρήση του @code{from package import specific_submodule}!  Στην πραγματικότητα, αυτή είναι η προτεινόμενη σημείωση, εκτός εάν το module εισαγωγής χρειάζεται να χρησιμοποιήσει submodules με το ίδιο όνομα από διαφορετικά πακέτα.

@node Intra-package αναφορές,Πακέτα σε Πολλαπλούς Καταλόγους,Εισάγοντας * από ένα Πακέτο,Πακέτα
@anchor{tutorial/modules id2}@anchor{2240}@anchor{tutorial/modules intra-package-references}@anchor{2241}
@subsubsection Intra-package αναφορές


Όταν τα πακέτα είναι δομημένα σε υποπακέτα (όπως με το πακέτο @code{sound} στο παράδειγμα), μπορείτε να χρησιμοποιήσετε απόλυτες εισαγωγές για να αναφερθείτε σε submodules αδερφών πακέτων.  Για παράδειγμα, εάν το module @code{sound.filters.vocoder} πρέπει να χρησιμοποιήσει το module @code{echo} στο πακέτο @code{sound.effects} , μπορεί να χρησιμοποιήσει το @code{from sound.effects import echo}.

Μπορείτε επίσης να γράψετε σχετικές εισαγωγές, με τη φόρμα @code{from module import name} της δήλωσης εισαγωγής.  Αυτές οι εισαγωγές χρησιμοποιούν leading dots για να υποδείξουν τα τρέχοντα και γονικά πακέτα που εμπλέκονται στη σχετική εισαγωγή.  Από το @code{surround} module για παράδειγμα, μπορεί να χρησιμοποιήσετε:

@example
from . import echo
from .. import formats
from ..filters import equalizer
@end example

Λάβετε υπόψη ότι οι σχετικές εισαγωγές βασίζονται στο όνομα του τρέχοντος module.  Επειδή το όνομα του κύριου module δεν έχει πακέτο, τα modules που προορίζονται για χρήση ως το κύριο module μιας εφαρμογής Python πρέπει πάντα να χρησιμοποιούν απόλυτες εισαγωγές.

@node Πακέτα σε Πολλαπλούς Καταλόγους,,Intra-package αναφορές,Πακέτα
@anchor{tutorial/modules packages-in-multiple-directories}@anchor{2242}
@subsubsection Πακέτα σε Πολλαπλούς Καταλόγους


Τα πακέτα υποστηρίζουν ένα ακόμη ειδικό χαρακτηριστικό, @ref{2243,,__path__}.  Αυτό έχει αρχικοποιηθεί ως μια @ref{8ff,,sequence} από συμβολοσειρές που περιέχει το όνομα του καταλόγου που το @code{__init__.py} του πακέτου πριν από την εκτέλεση του κώδικα σε αυτό το αρχείο.  Αυτή η μεταβλητή μπορεί να τροποποιηθεί, αυτό επηρεάζει τις μελλοντικές αναζητήσεις για modules και υποπακέτα που περιέχονται στο πακέτο.

Ενώ αυτή η δυνατότητα δεν χρειάζεται συχνά, μπορεί να χρησιμοποιηθεί για την επέκταση του συνόλου των modules που βρίσκονται σε ένα πακέτο.

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Είσοδος και Έξοδος,Σφάλματα και Εξαιρέσεις,Modules<2>,Οδηγός εκμάθησης Python
@anchor{tutorial/inputoutput doc}@anchor{2244}@anchor{tutorial/inputoutput input-and-output}@anchor{2245}@anchor{tutorial/inputoutput translation-repo}@anchor{2246}@anchor{tutorial/inputoutput tut-io}@anchor{2247}
@section Είσοδος και Έξοδος


Υπάρχουν διάφοροι τρόποι για να παρουσιάσετε τα αποτελέσματα ενός προγράμματος· τα δεδομένα μπορούν να εκτυπωθούν σε μορφή αναγνώσιμη από τον άνθρωπο ή να εγγραφούν σε ένα αρχείο για μελλοντική χρήση. Αυτό το κεφάλαιο θα συζητήσει μερικές από τις δυνατότητες.

@menu
* Ομορφότερη Μορφοποίηση Εξόδου:: 
* Ανάγνωση και Εγγραφή Αρχείων:: 

@end menu

@node Ομορφότερη Μορφοποίηση Εξόδου,Ανάγνωση και Εγγραφή Αρχείων,,Είσοδος και Έξοδος
@anchor{tutorial/inputoutput fancier-output-formatting}@anchor{2248}@anchor{tutorial/inputoutput tut-formatting}@anchor{2249}
@subsection Ομορφότερη Μορφοποίηση Εξόδου


Μέχρι στιγμής έχουμε συναντήσει δύο τρόπους γραφής τιμών: `expression statements' και τη συνάρτηση @ref{131f,,print()}.  (Ένας τρίτος τρόπος είναι η χρήση της μεθόδου @ref{224a,,write()} των αντικειμένων αρχείων· το standard αρχείο εξόδου μπορεί να αναφέρεται ως @code{sys.stdout}. Δείτε την Αναφορά Βιβλιοθήκης για περισσότερες πληροφορίες σχετικά με αυτό.)

Συχνά θα θέλετε περισσότερο έλεγχο στη μορφοποίηση της εξόδου σας παρά απλώς να εκτυπώνετε τιμές διαχωρισμένες με διάστημα. Υπάρχουν διάφοροι τρόποι για να μορφοποιήσετε την έξοδο.


@itemize *

@item 
Για να χρησιμοποιήσετε @ref{224b,,formatted string literals}, ξεκινήστε μια συμβολοσειρά με @code{f} or @code{F} πριν από το αρχικό εισαγωγικό ή το τριπλό εισαγωγικό. Μέσα σε αυτήν την συμβολοσειρά, μπορείτε να γράψετε μια έκφραση Python μεταξύ χαρακτήρων @code{@{} και @code{@}} που μπορεί να αναφέρεται σε μεταβλητές ή κυριολεκτικές τιμές.

@example
>>> year = 2016
>>> event = 'Referendum'
>>> f'Results of the @{year@} @{event@}'
'Results of the 2016 Referendum'
@end example

@item 
Η μέθοδος @ref{a12,,str.format()} των συμβολοσειρών απαιτεί περισσότερη μη χειροκίνητη προσπάθεια.  Θα εξακολουθείτε να χρησιμοποιείτε τα @code{@{} και @code{@}} για να επισημάνετε που θα αντικατασταθεί μια μεταβλητή και μπορεί να παρέχει λεπτομερείς οδηγίες μορφοποίησης, αλλά θα χρειαστεί επίσης να παρέχετε τις πληροφορίες που θα μορφοποιήσετε. Στο παρακάτω μπλοκ κώδικα υπάρχουν δύο παραδείγματα για τον τρόπο μορφοποίησης μεταβλητών:

@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

Παρατηρήστε πως τα @code{yes_votes} συμπληρώνονται με κενά και αρνητικό πρόσημο μόνο για αρνητικούς αριθμούς. Το παράδειγμα εκτυπώνει επίσης το @code{percentage} πολλαπλασιασμένο επί 100, με 2 δεκαδικά ψηφία και ακολουθούμενο από ένα σύμβολο ποσοστού (δείτε το @ref{6fe,,Format specification mini-language} για λεπτομέρειες).

@item 
Τέλος, μπορείτε να κάνετε μόνοι σας όλο τον χειρισμό συμβολοσειράς χρησιμοποιώντας λειτουργίες slicing και συνένωσης συμβολοσειρών για να δημιουργήσετε οποιαδήποτε διάταξη μπορείτε να φανταστείτε.  Ο τύπος συμβολοσειράς έχει ορισμένες μεθόδους που εκτελούν χρήσιμες λειτουργίες για την προσθήκη συμβολοσειρών σε ένα δεδομένο πλάτος στήλης.
@end itemize

Όταν δεν χρειάζεστε φανταχτερή έξοδο, άλλα θέλετε απλώς μια γρήγορη εμφάνιση ορισμένων μεταβλητών για σκοπούς εντοπισμού σφαλμάτων, μπορείτε να μετατρέψετε οποιαδήποτε τιμή σε μια συμβολοσειρά με τις συναρτήσεις @ref{45b,,repr()} ή @ref{1df,,str()}.

Η συνάρτηση @ref{1df,,str()} προορίζεται να επιστρέφει αναπαραστάσεις τιμών που είναι αρκετά αναγνώσιμες από τον άνθρωπο, ενώ το @ref{45b,,repr()} προορίζεται για τη δημιουργία αναπαραστάσεων που μπορούν να διαβαστούν από τον διερμηνέα (ή θα επιβάλουν ένα @ref{17e,,SyntaxError} αν δεν υπάρχει ισοδύναμη σύνταξη).  Για αντικείμενα που δεν έχουν συγκεκριμένη αναπαράσταση για ανθρώπινη κατανάλωση, η @code{str()} θα επιστρέψει την ίδια τιμή με το @code{repr()}.  Πολλές τιμές, όπως αριθμοί ή δομές όπως λίστες και λεξικά, έχουν την ίδια αναπαράσταση χρησιμοποιώντας οποιαδήποτε συνάρτηση. Τα strings, συγκεκριμένα, έχουν δύο διακριτές παραστάσεις.

Μερικά παραδείγματα:

@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

Το @ref{db,,string} module περιέχει υποστήριξη για μια απλή προσέγγιση templating βασισμένη σε κανονικές εκφράσεις, μέσω της @ref{a77,,string.Template}. Αυτό προσφέρει έναν ακόμη τρόπο για να αντικαταστήσετε τιμές σε συμβολοσειρές, χρησιμοποιώντας θέσεις κράτησης όπως @code{$x} και αντικαθιστώντας τις με τιμές από ένα λεξικό.

@geindex μορφοποιημένα String Literals
@geindex παρεμβαλλόμενα String Literals
@geindex string;Μορφοποιημένα Literals
@geindex string;παρεμβαλλόμενα literal
@geindex f-string
@geindex fstring

@menu
* Μορφοποιημένα String Literals:: 
* Η μέθοδος String format(): Η μέθοδος String format. 
* Χειροκίνητη Μορφοποίηση Συμβολοσειρών:: 
* Παλιά μορφοποίηση συμβολοσειράς:: 

@end menu

@node Μορφοποιημένα String Literals,Η μέθοδος String format,,Ομορφότερη Μορφοποίηση Εξόδου
@anchor{tutorial/inputoutput formatted-string-literals}@anchor{224c}@anchor{tutorial/inputoutput tut-f-strings}@anchor{224b}
@subsubsection Μορφοποιημένα String Literals


Τα @ref{43a,,Formatted string literals} (ονομάζονται επίσης f-strings για συντομία) σας επιτρέπουν να συμπεριλάβετε την τιμή των εκφράσεων Python μέσα σε μια συμβολοσειρά, θέτοντας πρόθεμα στη συμβολοσειρά με @code{f} ή @code{F} και γράφοντας εκφράσεις ως @code{@{expression@}}.

Ένας προαιρετικός αναθέτης (specifier) μορφής μπορεί να ακολουθεί την έκφραση. Αυτό επιτρέπει μεγαλύτερο έλεγχο στον τρόπο μορφοποίησης της τιμής. Το παρακάτω παράδειγμα στρογγυλοποιεί το pi σε τρία ψηφία μετά το δεκαδικό:

@example
>>> import math
>>> print(f'The value of pi is approximately @{math.pi:.3f@}.')
The value of pi is approximately 3.142.
@end example

Η μετάδοση ενός ακέραιου αριθμού μετά το @code{':'} θα έχει ως αποτέλεσμα αυτό το πεδίο να έχει πλάτος ελάχιστου αριθμού χαρακτήρων.  Αυτό είναι χρήσιμο για την ευθυγράμμιση στηλών.

@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

Μπορούν να χρησιμοποιηθούν άλλοι τροποποιητές για την μετατροπή της τιμής πριν τη μορφοποίηση της. Το @code{'!a'} ισχύει για @ref{1789,,ascii()}, το @code{'!s'} ισχύει για @ref{1df,,str()}, και το @code{'!r'} ισχύει για @ref{45b,,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

Ο αναθέτης (specifier) @code{=} μπορεί να χρησιμοποιηθεί για να επεκτείνει μια έκφραση στο κείμενο της έκφρασης, ένα σύμβολο ίσο, και μετά την αναπαράσταση της αξιολογούμενης έκφρασης:

@example
>>> bugs = 'roaches'
>>> count = 13
>>> area = 'living room'
>>> print(f'Debugging @{bugs=@} @{count=@} @{area=@}')
Debugging bugs='roaches' count=13 area='living room'
@end example

Δείτε το @ref{d70,,self-documenting expressions} για περισσότερες πληροφορίες σχετικά με τον αναθέτη (specifier) @code{=}. Για αναφορά σε αυτές τις προδιαγραφές μορφής, ανατρέξτε στον οδηγό αναφοράς για το @ref{6fe,,Format specification mini-language}.

@node Η μέθοδος String format,Χειροκίνητη Μορφοποίηση Συμβολοσειρών,Μορφοποιημένα String Literals,Ομορφότερη Μορφοποίηση Εξόδου
@anchor{tutorial/inputoutput the-string-format-method}@anchor{224d}@anchor{tutorial/inputoutput tut-string-format}@anchor{224e}
@subsubsection Η μέθοδος String format()


Η βασική χρήση της μεθόδου @ref{a12,,str.format()} μοιάζει με αυτό:

@example
>>> print('We are the @{@} who say "@{@}!"'.format('knights', 'Ni'))
We are the knights who say "Ni!"
@end example

Οι αγκύλες και οι χαρακτήρες μέσα σε αυτές (που ονομάζονται πεδία μορφής) αντικαθίστανται με τα αντικείμενα που μεταβιβάζονται στη μέθοδο @ref{a12,,str.format()}.  Ένας αριθμός στις αγκύλες μπορεί να χρησιμοποιηθεί για να αναφέρεται στη θέση του αντικειμένου που μεταβιβάζεται στη μέθοδο @code{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

Εάν χρησιμοποιούνται keyword ορίσματα στη μέθοδο @ref{a12,,str.format()}, οι τιμές τους αναφέρονται χρησιμοποιώντας το όνομα του ορίσματος.

@example
>>> print('This @{food@} is @{adjective@}.'.format(
...       food='spam', adjective='absolutely horrible'))
This spam is absolutely horrible.
@end example

Τα ορίσματα θέσης και λέξης-κλειδιού μπορούν να συνδυαστούν αυθαίρετα:

@example
>>> print('The story of @{0@}, @{1@}, and @{other@}.'.format('Bill', 'Manfred',
...                                                    other='Georg'))
The story of Bill, Manfred, and Georg.
@end example

Εάν έχετε μια συμβολοσειρά πολύ μακριάς μορφής που δεν θέλετε να χωρίσετε, θα ήταν ωραίο να αναφέρετε τις μεταβλητές που θα μορφοποιηθούν με βάση το όνομα αντί για τη θέση.  Αυτό μπορεί να γίνει απλά περνώντας το λεξικό και χρησιμοποιώντας αγκύλες @code{'[]'} για πρόσβαση στα κλειδιά

@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

Αυτό θα μπορούσε επίσης να γίνει περνώντας το λεξικό @code{table} ως ορίσματα λέξεων-κλειδιών με την σημείωση @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

Αυτό είναι ιδιαίτερα χρήσιμο σε συνδυασμό με την ενσωματωμένη (built-in) συνάρτηση @ref{2011,,vars()}, η οποία επιστρέφει ένα λεξικό που περιέχει όλες τις τοπικές μεταβλητές:

@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

Για παράδειγμα, οι ακόλουθες γραμμές παράγουν ένα τακτοποιημένο σύνολο στηλών που δίνουν ακέραιους αριθμούς και τα τετράγωνα και τους κύβους τους:

@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

Για μια πλήρη επισκόπηση της μορφοποίησης συμβολοσειρών με @ref{a12,,str.format()}, δείτε @ref{173f,,Format string syntax}.

@node Χειροκίνητη Μορφοποίηση Συμβολοσειρών,Παλιά μορφοποίηση συμβολοσειράς,Η μέθοδος String format,Ομορφότερη Μορφοποίηση Εξόδου
@anchor{tutorial/inputoutput manual-string-formatting}@anchor{224f}
@subsubsection Χειροκίνητη Μορφοποίηση Συμβολοσειρών


Ακολουθεί ο ίδιος πίνακας τετραγώνων και κύβων, μορφοποιημένος χειροκίνητα:

@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

(Σημειώστε ότι το ένα κενό μεταξύ κάθε στήλης προστέθηκε με τον τρόπο που λειτουργεί το @ref{131f,,print()}: προσθέτει πάντα κενά μεταξύ των ορισμάτων του.)

Η μέθοδος @ref{2250,,str.rjust()} των αντικειμένων συμβολοσειράς τοποθετεί δεξιά μια συμβολοσειρά σε ένα πεδίο δεδομένου πλάτους συμπληρώνοντας την με κενά στα αριστερά. Υπάρχουν παρόμοιες μέθοδοι @ref{2251,,str.ljust()} και @ref{2252,,str.center()}. Αυτές οι μέθοδοι δεν γράφουν τίποτα, απλώς επιστρέφουν μια συμβολοσειρά. Εάν η συμβολοσειρά εισόδου είναι πολύ μεγάλη, δεν την περικόπτουν, αλλά την επιστρέφουν αμετάβλητη· αυτό θα μπερδέψει τη διάταξη της στήλης σας, αλλά αυτό είναι συνήθως καλύτερο από την εναλλακτική, που θα ήταν ψέματα για μια τιμή. (Αν θέλετε πραγματικά περικοπή, μπορείτε πάντα να προσθέσετε μια λειτουργία slice, όπως στο @code{x.ljust(n)[:n]}.)

Υπάρχει μια άλλη μέθοδος, η @ref{1854,,str.zfill()}, η οποία συμπληρώνει μια αριθμητική συμβολοσειρά στα αριστερά με μηδενικά.  Καταλαβαίνει τα σύμβολα συν και πλην:

@example
>>> '12'.zfill(5)
'00012'
>>> '-3.14'.zfill(7)
'-003.14'
>>> '3.14159265359'.zfill(5)
'3.14159265359'
@end example

@node Παλιά μορφοποίηση συμβολοσειράς,,Χειροκίνητη Μορφοποίηση Συμβολοσειρών,Ομορφότερη Μορφοποίηση Εξόδου
@anchor{tutorial/inputoutput old-string-formatting}@anchor{2253}
@subsubsection Παλιά μορφοποίηση συμβολοσειράς


Ο τελεστής % (modulo) μπορεί επίσης να χρησιμοποιηθεί για τη μορφοποίηση συμβολοσειρών. Δεδομένων των τιμών @code{format % values} (όπου `format' είναι μια συμβολοσειρά), οι προδιαγραφές μετατροπής @code{%} σε `format' αντικαθίστανται με μηδέν ή περισσότερα στοιχεία `τιμών'. Αυτή η λειτουργία είναι κοινώς γνωστή ως παρεμβολή συμβολοσειρών. Για παράδειγμα:

@example
>>> import math
>>> print('The value of pi is approximately %5.3f.' % math.pi)
The value of pi is approximately 3.142.
@end example

Περισσότερες πληροφορίες μπορείτε να βρείτε στην ενότητα @ref{ab9,,printf-style String Formatting}.

@node Ανάγνωση και Εγγραφή Αρχείων,,Ομορφότερη Μορφοποίηση Εξόδου,Είσοδος και Έξοδος
@anchor{tutorial/inputoutput reading-and-writing-files}@anchor{2254}@anchor{tutorial/inputoutput tut-files}@anchor{2255}
@subsection Ανάγνωση και Εγγραφή Αρχείων


@geindex ενσωματωμένη (built-in) συνάρτηση;open
@geindex object;file

Η @ref{32b,,open()} επιστρέφει ένα @ref{156c,,file object}, και χρησιμοποιείται πιο συχνά με δύο ορίσματα θέσης και ένα όρισμα λέξης-κλειδιού: @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>

Το πρώτο όρισμα είναι μια συμβολοσειρά που περιέχει το όνομα αρχείου.  Το δεύτερο όρισμα είναι μια άλλη συμβολοσειρά που περιέχει μερικούς χαρακτήρες που περιγράφουν τον τρόπο με τον οποίο θα χρησιμοποιηθεί το αρχείο. Η `mode' μπορεί να είναι @code{'r'} όταν το αρχείο θα είναι μόνο για διάβασμα, @code{'w'} μόνο για εγγραφή (ένα υπάρχον αρχείο με το ίδιο όνομα θα διαγραφεί) και το @code{'a'} ανοίγει το αρχείο για προσάρτηση· οποιαδήποτε δεδομένα γράφονται στο αρχείο και προστίθενται αυτόματα στο τέλος. Το @code{'r+'} ανοίγει το αρχείο τόσο για ανάγνωση όσο και για γραφή. Το όρισμα `mode' είναι προαιρετικό· το @code{'r'} θα θεωρείται εάν παραληφθεί.

Κανονικά, τα αρχεία ανοίγουν σε `text mode', που σημαίνει ότι διαβάζετε και γράφετε συμβολοσειρές από και προς το αρχείο, οι οποίες κωδικοποιούνται σε μια συγκεκριμένη `κωδικοποίηση'. Εάν δεν έχει καθοριστεί η `κωδικοποιήση', η προεπιλογή είναι εξαρτώμενη από την πλατφόρμα (δείτε @ref{32b,,open()}). Επειδή το UTF-8 είναι το σύγχρονο de-facto standard, @code{encoding="utf-8"} συνίσταται εκτός εάν γνωρίζετε ότι πρέπει να χρησιμοποιήσετε διαφορετική κωδικοποίηση. Η προσθήκη ενός @code{'b'} στη λειτουργία ανοίγει το αρχείο σε `binary mode'. Τα δεδομένα δυαδικής λειτουργίας διαβάζονται και γράφονται ως αντικείμενα @ref{1c7,,bytes}. Δεν μπορείτε να καθορίσετε `κωδικοποίηση' όταν ανοίγετε αρχείο σε δυαδική λειτουργία.

Στη λειτουργία κειμένου, η προεπιλογή (default) κατά την ανάγνωση είναι να μετατρέψετε τις καταλήξεις γραμμών για συγκεκριμένη πλατφόρμα (@code{\n} στο Unix, @code{\r\n} στα Windows) σε μόνο @code{\n}.  Όταν γράφετε σε λειτουργία κειμένου, η προεπιλογή είναι να μετατρέπονται οι εμφανίσεις @code{\n} σε καταλήξεις γραμμών για συγκεκριμένη πλατφόρμα. Αυτή η παρασκηνιακή τροποποίηση στα δεδομένα αρχείων είναι καλή για αρχεία κειμένου, αλλά θα καταστρέψει δυαδικά δεδομένα όπως αυτό σε αρχεία @code{JPEG} ή @code{EXE}.  Να είστε πολύ προσεκτικοί να χρησιμοποιείτε τη δυαδική λειτουργία όταν διαβάζετε και γράφετε τέτοια αρχεία.

Είναι καλή πρακτική να χρησιμοποιείτε το keyword @ref{20a,,with} όταν ασχολούμαστε με αντικείμενα αρχείου.  Το πλεονέκτημα είναι ότι το αρχείο κλείνει σωστά μετά την ολοκλήρωση της εκτέλεσής του, ακόμα κι αν κάποια στιγμή προκύψει εξαίρεση.  Χρησιμοποιώντας το @code{with} είναι επίσης πολύ πιο σύντομο από την σύνταξη ισοδύναμου @ref{ad6,,try}-@ref{44c,,finally} blocks:

@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

Εάν δεν χρησιμοποιείτε τη keyword @ref{20a,,with}, τότε θα πρέπει να καλείτε τη @code{f.close()} για να κλείσετε το αρχείο και να ελευθερώσετε αμέσως τυχόν πόρους συστήματος που χρησιμοποιούνται από αυτό.

@cartouche
@quotation Προειδοποίηση 
Η κλήση του @code{f.write()} χωρίς τη χρήση της keyword @code{with} ή η κλήση του @code{f.close()} `μπορεί' να οδηγήσει στα ορίσματα του @code{f.write()} να μην εγγραφεί πλήρως στο δίσκο, ακόμα και αν το πρόγραμμα εξέλθει με επιτυχία.
@end quotation
@end cartouche

@c See also https://bugs.python.org/issue17852

Μετά το κλείσιμο ενός αντικειμένου αρχείου, είτε μια δήλωση @ref{20a,,with} είτε καλώντας @code{f.close()}, οι προσπάθειες χρήσης του αντικειμένου αρχείου θα αποτύχουν αυτόματα.

@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
* Μέθοδοι Αντικειμένων Αρχείων:: 
* Αποθήκευση δομημένων δεδομένων με json:: 

@end menu

@node Μέθοδοι Αντικειμένων Αρχείων,Αποθήκευση δομημένων δεδομένων με json,,Ανάγνωση και Εγγραφή Αρχείων
@anchor{tutorial/inputoutput methods-of-file-objects}@anchor{2256}@anchor{tutorial/inputoutput tut-filemethods}@anchor{2257}
@subsubsection Μέθοδοι Αντικειμένων Αρχείων


Τα υπόλοιπα παραδείγματα σε αυτήν την ενότητα θα υποθέσουν ότι ένα αντικείμενο αρχείου που ονομάζεται @code{f} έχει ήδη δημιουργηθεί.

Για να διαβάσετε τα περιεχόμενα ενός αρχείου, καλέστε το @code{f.read(size)}, το οποίο διαβάζει κάποια ποσότητα δεδομένων και την επιστρέφει ως συμβολοσειρά (σε λειτουργία κειμένου) ή ως αντικείμενο bytes (σε δυαδική λειτουργία). Το `size' είναι προαιρετικό αριθμητικό όρισμα.  Όταν το `size' παραλείπεται ή είναι αρνητικό, ολόκληρο το περιεχόμενο του αρχείου θα διαβαστεί και θα επιστραφεί∙ είναι δικό σας πρόβλημα εάν το αρχείο είναι διπλάσιο από τη μνήμη του υπολογιστή σας. Διαφορετικά, διαβάζονται και επιστρέφονται το πολύ `size' χαρακτήρες (σε λειτουργία κειμένου) ή byte `size' (σε δυαδική λειτουργία). Εάν έχει φτάσει το τέλος του αρχείου, το @code{f.read()} θα επιστρέψει μια κενή συμβολοσειρά (@code{'@w{'}}).

@example
>>> f.read()
'This is the entire file.\n'
>>> f.read()
'@w{'}
@end example

Το @code{f.readline()} διαβάζει μία γραμμή από το αρχείο· ένας χαρακτήρας νέας γραμμής (@code{\n}) παραμένει στο τέλος της συμβολοσειράς, και παραλείπεται μόνο στην τελευταία γραμμή του αρχείου εάν το αρχείο δεν τελειώνει σε μια νέα γραμμή.  Αυτό καθιστά την τιμή επιστροφής σαφή· εάν το @code{f.readline()} επιστρέφει μια κενή συμβολοσειρά, έχει φτάσει στο τέλος του αρχείου, ενώ μια κενή γραμμή αντιπροσωπεύεται από @code{'\n'}, μια συμβολοσειρά που περιέχει μόνο μία νέα γραμμή.

@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

Για την ανάγνωση γραμμών από ένα αρχείο, μπορείτε να κάνετε loop πάνω από το αντικείμενο του αρχείου. Αυτό είναι αποδοτικό στη μνήμη, γρήγορο και οδηγεί σε απλό κώδικα:

@example
>>> for line in f:
...     print(line, end='@w{'})
...
This is the first line of the file.
Second line of the file
@end example

Εάν θέλετε να διαβάσετε όλες τις γραμμές ενός αρχείου σε μια λίστα, μπορείτε επίσης να χρησιμοποιήσετε το @code{list(f)} ή @code{f.readlines()}.

Το @code{f.write(string)} γράφει τα περιεχόμενα του `string' στο αρχείο, επιστρέφοντας τον αριθμό των χαρακτήρων που γράφτηκαν.

@example
>>> f.write('This is a test\n')
15
@end example

Άλλοι τύποι αντικειμένων πρέπει να μετατραπούν – είτε σε μια συμβολοσειρά (σε λειτουργία κειμένου) ή σε ένα αντικείμενο bytes (σε δυαδική λειτουργία) – πριν τα γράψετε:

@example
>>> value = ('the answer', 42)
>>> s = str(value)  # convert the tuple to string
>>> f.write(s)
18
@end example

Το @code{f.tell()} επιστρέφει έναν ακέραιο που δίνει την τρέχουσα θέση του αντικειμένου αρχείου στο αρχείο που αντιπροσωπεύεται ως αριθμό byte από την αρχή του αρχείου όταν βρίσκεται σε δυαδική λειτουργία και έναν αδιαφανή αριθμό όταν βρίσκεται σε λειτουργία κειμένου.

Για να αλλάξετε τη θέση του αντικειμένου, χρησιμοποιήστε το @code{f.seek(offset, whence)}.  Η θέση υπολογίζεται από την προσθήκη `offset' σε ένα σημείο αναφοράς· το σημείο αναφοράς επιλέγεται από το όρισμα `whence'.  Μια 0 τιμή `whence' μετρά από την αρχή του αρχείο το 1 χρησιμοποιεί την τρέχουσα θέση αρχείου και το 2 χρησιμοποιεί το τέλος του αρχείου ως σημείο αναφοράς.  Το `whence' μπορεί να παραληφθεί και να οριστεί από προεπιλογή 0, χρησιμοποιώντας την αρχή του αρχείου ως σημείο αναφοράς.

@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

Σε αρχεία κειμένου (αυτά που ανοίγουν χωρίς @code{b} στη λειτουργία string), επιτρέπονται μόνο αναζητήσεις σε σχέση με την αρχή του αρχείου (η εξαίρεση είναι η αναζήτηση μέχρι το ίδιο το αρχείο που τελειώνει με @code{seek(0, 2)}) και οι μόνες έγκυρες τιμές `offset' είναι αυτές που επιστρέφονται από το @code{f.tell()}, ή μηδέν. Οποιαδήποτε άλλη τιμή `offset' παράγει  απροσδιόριστη συμπεριφορά.

Τα αντικείμενα αρχείου έχουν ορισμένες πρόσθετες μεθόδους, όπως @ref{2258,,isatty()} και @ref{16b5,,truncate()} που χρησιμοποιούνται λιγότερο συχνά· συμβουλευτείτε την Αναφορά της Βιβλιοθήκης για έναν πλήρη οδηγό για τα αντικείμενα αρχείων.

@node Αποθήκευση δομημένων δεδομένων με json,,Μέθοδοι Αντικειμένων Αρχείων,Ανάγνωση και Εγγραφή Αρχείων
@anchor{tutorial/inputoutput saving-structured-data-with-json}@anchor{2259}@anchor{tutorial/inputoutput tut-json}@anchor{225a}
@subsubsection Αποθήκευση δομημένων δεδομένων με @code{json}


@geindex module;json

Οι συμβολοσειρές μπορούν εύκολα να γραφούν και να διαβαστούν από ένα αρχείο.  Οι αριθμοί απαιτούν λίγο περισσότερη προσπάθεια, καθώς η μέθοδος @ref{225b,,read()} επιστρέφει μόνο συμβολοσειρές, οι οποίες θα πρέπει να περάσουν μια συνάρτηση όπως @ref{326,,int()}, που παίρνει μια συμβολοσειρά όπως @code{'123'} και επιστρέφει την αριθμητική της τιμή 123.  Όταν θέλετε να αποθηκεύσετε πιο σύνθετους τύπους δεδομένων, όπως ένθετε λίστες και λεξικά, η ανάλυση και η σειριοποίηση με το χέρι γίνεται περίπλοκη.

Αντί να χρειάζεται οι χρήστες να γράφουν και να διορθώνουν συνεχώς κώδικα για να αποθηκεύουν πολύπλοκους τύπους δεδομένων σε αρχεία, η Python σας επιτρέπει να χρησιμοποιείτε τη δημοφιλή μορφή ανταλλαγής δεδομένων που ονομάζεται JSON (JavaScript Object Notation)@footnote{https://json.org}.  Το standard module που ονομάζεται @ref{85,,json} μπορεί να λάβει ιεραρχίες δεδομένων Python, και να τις μετατρέψει σε αναπαραστάσεις συμβολοσειρών· αυτή η διαδικασία ονομάζεται `serializing'..  Η ανασύνθεση των δεδομένων από την αναπαράσταση συμβολοσειράς ονομάζεται `deserializing'.  Μεταξύ σειριοποίησης και αποσειριοποίησης, η συμβολοσειρά που αντιπροσωπεύει το αντικείμενο μπορεί να έχει αποθηκευτεί σε ένα αρχείο ή δεδομένα ή να έχει σταλεί μέσω μιας σύνδεσης δικτύου σε κάποιο απομακρυσμένο μηχάνημα.

@cartouche
@quotation Σημείωση 
Η μορφή JSON χρησιμοποιείται συνήθως από σύγχρονες εφαρμογές για να επιτρέπει την ανταλλαγή δεδομένων.  Πολλοί προγραμματιστές είναι ήδη εξοικειωμένοι με αυτήν, γεγονός που την καθιστά καλή επιλογή για διαλειτουργικότητα.
@end quotation
@end cartouche

Εάν έχετε ένα αντικείμενο @code{x}, μπορείτε να δείτε την αναπαράσταση συμβολοσειράς JSON με μια απλή γραμμή κώδικα:

@example
>>> import json
>>> x = [1, 'simple', 'list']
>>> json.dumps(x)
'[1, "simple", "list"]'
@end example

Μια άλλη παραλλαγή της συνάρτησης @ref{248,,dumps()}, που ονομάζεται @ref{10fb,,dump()}, απλώς σειριοποιεί το αντικείμενο σε ένα @ref{225c,,text file}.  Έτσι, εάν το @code{f} είναι ένα αντικείμενο text file που ανοίγει για εγγραφή, μπορούμε να κάνουμε αυτό:

@example
json.dump(x, f)
@end example

Για να αποκωδικοποιήσετε ξανά το αντικείμενο, εάν το @code{f} είναι ένα αντικείμενο @ref{225d,,binary file} ή @ref{225c,,text file} που έχει ανοίξει για ανάγνωση:

@example
x = json.load(f)
@end example

@cartouche
@quotation Σημείωση 
Τα αρχεία JSON πρέπει να είναι κωδικοποιημένα σε UTF-8. Χρησιμοποιήστε το @code{encoding="utf-8"} όταν ανοίγετε το αρχείο JSON ως @ref{225c,,text file} τόσο για ανάγνωση όσο και για εγγραφή.
@end quotation
@end cartouche

Αυτή η απλή τεχνική σειριοποίησης μπορεί να χειριστεί λίστες και λεξικά, άλλα η σειριοποίηση αυθαίρετων στιγμιοτύπων κλάσεων σε JSON απαιτεί λίγη επιπλέον προσπάθεια. Η αναφορά για το module @ref{85,,json} περιέχει μια εξήγηση για αυτό.


@subsubheading Δείτε επίσης


@ref{ab,,pickle} - το pickle module

Σε αντίθεση με το @ref{225a,,JSON}, το `pickle' είναι ένα πρωτόκολλο που επιτρέπει τη σειριοποίηση αυθαίρετα πολύπλοκων αντικειμένων Python.  Ως εκ τούτου, είναι συγκεκριμένο για την Python και δεν μπορεί να χρησιμοποιηθεί για επικοινωνία με εφαρμογές γραμμένες σε άλλες γλώσσες.  Είναι επίσης ανασφαλές από προεπιλογή: η αποσειριοποίηση pickle δεδομένων που προέρχονται από μια μη αξιόπιστη πηγή μπορεί να εκτελέσει αυθαίρετο κώδικα, εάν τα δεδομένα έχουν δημιουργηθεί από έναν έμπειρο εισβολέα.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Σφάλματα και Εξαιρέσεις,Κλάσεις,Είσοδος και Έξοδος,Οδηγός εκμάθησης Python
@anchor{tutorial/errors doc}@anchor{225e}@anchor{tutorial/errors errors-and-exceptions}@anchor{225f}@anchor{tutorial/errors translation-repo}@anchor{2260}@anchor{tutorial/errors tut-errors}@anchor{2261}
@section Σφάλματα και Εξαιρέσεις


Μέχρι τώρα τα μηνύματα σφαλμάτων (error messages) δεν ήταν περισσότερα από όσα αναφέρθηκαν, αλλά αν έχετε δοκιμάσει τα παραδείγματα, πιθανότατα έχετε δει μερικά.  Υπάρχουν (τουλάχιστον) δύο διαφορετικά είδη σφαλμάτων: `syntax errors' (συντακτικά σφάλματα) και `exceptions' (εξαιρέσεις).

@menu
* Syntax Errors (Συντακτικά Σφάλματα): Syntax Errors Συντακτικά Σφάλματα. 
* Exceptions (Εξαιρέσεις): Exceptions Εξαιρέσεις. 
* Διαχείριση Εξαιρέσεων:: 
* Raising Εξαιρέσεων:: 
* Αλυσιδωτές Εξαιρέσεις:: 
* Εξαιρέσεις που καθορίζονται από το χρήστη:: 
* Καθορισμός ενεργειών καθαρισμού:: 
* Προκαθορισμένες ενέργειες καθαρισμού:: 
* Raising και Χειρισμός Πολλαπλών Άσχετων Εξαιρέσεων:: 
* Εμπλουτίζοντας τις Εξαιρέσεις με Σημειώσεις:: 

@end menu

@node Syntax Errors Συντακτικά Σφάλματα,Exceptions Εξαιρέσεις,,Σφάλματα και Εξαιρέσεις
@anchor{tutorial/errors syntax-errors}@anchor{2262}@anchor{tutorial/errors tut-syntaxerrors}@anchor{2263}
@subsection Syntax Errors (Συντακτικά Σφάλματα)


Τα syntax errors, γνωστά και ως parsing errors, είναι ίσως το πιο συνηθισμένο είδος παραπόνου που λαμβάνετε ενώ εξακολουθείτε να μαθαίνετε Python:

@example
>>> while True print('Hello world')
  File "<stdin>", line 1
    while True print('Hello world')
               ^^^^^
SyntaxError: invalid syntax
@end example

Ο αναλυτής επαναλαμβάνει την παραβατική γραμμή και εμφανίζει μικρά βέλη που δείχνουν προς το μέρος όπου που εντοπίστηκε το σφάλμα. Σημειώστε ότι αυτό δεν είναι πάντα το μέρος που πρέπει να διορθωθεί.  Στο παράδειγμα, το σφάλμα εντοπίζεται στη συνάρτηση @ref{131f,,print()}, καθώς λείπει μια άνω και κάτω τελεία (@code{':'}) ακριβώς πριν από αυτήν.

Το όνομα αρχείου (@code{<stdin>} στο παράδειγμά μας) και ο αριθμός γραμμής εκτυπώνονται, ώστε να να γνωρίζετε πού να ψάξετε σε περίπτωση που η είσοδος προήλθε από αρχείο.

@node Exceptions Εξαιρέσεις,Διαχείριση Εξαιρέσεων,Syntax Errors Συντακτικά Σφάλματα,Σφάλματα και Εξαιρέσεις
@anchor{tutorial/errors exceptions}@anchor{2264}@anchor{tutorial/errors tut-exceptions}@anchor{2265}
@subsection Exceptions (Εξαιρέσεις)


Ακόμη και αν μια πρόταση ή μια έκφραση είναι συντακτικά σωστή, μπορεί να προκαλέσει σφάλμα όταν γίνεται προσπάθεια εκτέλεσης της. Τα σφάλματα που εντοπίζονται κατά την εκτέλεση ονομάζονται `εξαιρέσεις' και δεν είναι άνευ όρων μοιραία (fatal): σύντομα θα μάθετε πως να τα χειρίζεστε σε προγράμματα Python.  Ωστόσο, οι περισσότερες εξαιρέσεις δεν αντιμετωπίζονται από προγράμματα και οδηγούν σε μηνύματα σφάλματος όπως φαίνεται εδώ:

@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

Η τελευταία γραμμή του μηνύματος σφάλματος υποδεικνύει τι συνέβη. Οι εξαιρέσεις υπάρχουν σε διαφορετικούς τύπους και ο τύπος εκτυπώνεται ως μέρος του μηνύματος: οι τύποι στο παράδειγμα είναι @ref{d11,,ZeroDivisionError}, @ref{665,,NameError} και @ref{291,,TypeError}. Η συμβολοσειρά που εκτυπώνεται ως τύπος εξαίρεσης είναι όνομα της ενσωματωμένης εξαίρεσης που προέκυψε.  Αυτό ισχύει για όλες τις ενσωματωμένες (built-in) εξαιρέσεις, αλλά δεν χρειάζεται να ισχύει για εξαιρέσεις που ορίζονται από το χρήστη (αν και είναι μια χρήσιμη σύμβαση). Οι standard εξαιρέσεις είναι ενσωματωμένα (built-in) αναγνωριστικά (όχι δεσμευμένες λέξεις-κλειδιά).

Η υπόλοιπη γραμμή παρέχει λεπτομέρειες με βάση τον τύπο της εξαίρεσης και το τι την προκάλεσε.

Το προηγούμενο μέρος του μηνύματος σφάλματος εμφανίζει το περιβάλλον όπου συνέβη η εξαίρεση, με τη μορφή ανίχνευσης στοίβας. Γενικά περιέχει μια στοίβα ανίχνευσης γραμμών πηγής∙ ωστόσο, δεν θα εμφανίζει γραμμές που διαβάζονται από standard είσοδο.

Το @ref{1e1e,,Built-in Exceptions} παραθέτει τις ενσωματωμένες εξαιρέσεις και τις έννοιές τους.

@node Διαχείριση Εξαιρέσεων,Raising Εξαιρέσεων,Exceptions Εξαιρέσεις,Σφάλματα και Εξαιρέσεις
@anchor{tutorial/errors handling-exceptions}@anchor{2266}@anchor{tutorial/errors tut-handling}@anchor{21e7}
@subsection Διαχείριση Εξαιρέσεων


Είναι δυνατό να γραφτεί κώδικας που χειρίζεται επιλεγμένες εξαιρέσεις. Κοιτάξτε το ακόλουθο παράδειγμα, το οποίο ζητά από τον χρήστη να εισάγει έναν έγκυρο ακέραιο αριθμό, αλλά επιτρέπει στον χρήστη να διακόψει το πρόγραμμα (χρησιμοποιώντας @code{Control}-@code{C} ή ό,τι υποστηρίζει το λειτουργικό σύστημα)· σημειώστε ότι μια διακοπή που δημιουργείται από τον χρήστη σηματοδοτείται κάνοντας raise την εξαίρεση @ref{d96,,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

Η δήλωση @ref{ad6,,try} λειτουργεί ως εξής.


@itemize *

@item 
Πρώτον, εκτελείται η `try clause' (η πρόταση(εις) μεταξύ των λέξεων-κλειδιών @ref{ad6,,try} and @ref{447,,except}).

@item 
Εάν δεν προκύψει εξαίρεση, η `except clause' παραλείπεται και η εκτέλεση της πρότασης @ref{ad6,,try} ολοκληρώνεται.

@item 
Εάν παρουσιαστεί μια εξαίρεση κατά την εκτέλεση της πρότασης @ref{ad6,,try}, η υπόλοιπη πρόταση παραλείπεται.  Στη συνέχεια, εάν ο τύπος της ταιριάζει με την εξαίρεση που ονομάζεται από τη λέξη-κλειδί @ref{447,,except}, η `except clause' εκτελείται, και στη συνέχεια η εκτέλεση συνεχίζεται μετά το μπλοκ try/except.

@item 
Εάν προκύψει μια εξαίρεση που δεν ταιριάζει με την εξαίρεση που αναφέρεται στην `except clause', μεταβιβάζεται σε εξωτερικές εντολές @ref{ad6,,try} · εάν δεν βρεθεί κανένας χειριστής, είναι μια `unhandled exception' και η εκτέλεση σταματά με μήνυμα σφάλματος.
@end itemize

A @ref{ad6,,try} statement may have more than one `except clause', to specify
handlers for different exceptions.  At most one handler will be executed.
Handlers only handle exceptions that occur in the corresponding `try clause',
not in other handlers of the same @code{try} statement.  An `except clause'
may name multiple exceptions, for example:

@example
... except RuntimeError, TypeError, NameError:
...     pass
@end example

Μια κλάση σε μια πρόταση @ref{447,,except} ταιριάζει με εξαιρέσεις που είναι στιγμιότυπα της ίδιας της κλάσης ή μιας από τις παραγόμενες κλάσεις της (αλλά όχι το αντίστροφο — μια `except clause' που παραθέτει μια παράγωγη κλάση δεν ταιριάζει με τις παρουσίες των βασικών της κλάσεων). Για παράδειγμα, ο ακόλουθος κώδικας θα εκτυπώσει τα B, C, D με αυτή τη σειρά:

@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

Σημειώστε ότι εάν οι `except clauses' είχαν αντιστραφεί (με το @code{except B} πρώτα), θα είχε εκτυπωθεί B, B, B — ενεργοποιείται η πρώτη αντιστοίχιση `except clause'.

Όταν προκύπτει μια εξαίρεση, μπορεί να έχει συσχετισμένες τιμές, γνωστές και ως `ορίσματα' της εξαίρεσης. Η παρουσία και οι τύποι των ορισμάτων εξαρτώνται από τον τύπο εξαίρεσης.

Το `except clause' μπορεί να καθορίσει μια μεταβλητή μετά το όνομα της εξαίρεσης.  Η μεταβλητή συνδέεται με το στιγμιότυπο της εξαίρεσης η οποία συνήθως έχει ένα χαρακτηριστικό @code{args} που αποθηκεύει τα ορίσματα. Για ευκολία, οι ενσωματωμένοι (builtin) τύποι εξαίρεσης ορίζουν @ref{a0f,,__str__()} για να εκτυπώσετε όλα τα ορίσματα χωρίς ρητή πρόσβαση στο @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

Η έξοδος της εξαίρεσης @ref{a0f,,__str__()} εκτυπώνεται ως το τελευταίο μέρος (“λεπτομέρεια”) του μηνύματος για μη χειριζόμενες εξαιρέσεις.

Η @ref{9b9,,BaseException} είναι η κοινή βασική κλάση όλων των εξαιρέσεων. Μια από τις υποκατηγορίες της, @ref{d9e,,Exception}, είναι η βασική κλάση όλων των μη μοιραίων εξαιρέσεων. Εξαιρέσεις που δεν είναι υποκλάσεις του @code{Exception} δεν αντιμετωπίζονται συνήθως, επειδή χρησιμοποιούνται για να υποδείξουν ότι το πρόγραμμα πρέπει να τερματιστεί. Περιλαμβάνουν το @ref{10f7,,SystemExit} το οποίο αυξάνεται από το @ref{4ff,,sys.exit()} και το @ref{d96,,KeyboardInterrupt} το οποίο γίνεται raise όταν ο χρήστης επιθυμεί να διακόψει την εκτέλεση του προγράμματος.

Η @ref{d9e,,Exception} μπορεί να χρησιμοποιηθεί ως μπαλαντέρ που πιάνει (σχεδόν) τα πάντα. Ωστόσο, είναι καλή πρακτική να είμαστε όσο το δυνατόν πιο συγκεκριμένοι με τους τύπους εξαιρέσεων που σκοπεύουμε να χειριστούμε και να επιτρέπουμε τυχόν απροσδόκητες εξαιρέσεις που εξαπλώνονται.

Το πιο κοινό μοτίβο για το χειρισμό @ref{d9e,,Exception} είναι να εκτυπώσετε ή να καταγράψετε την εξαίρεση και στη συνέχεια να την επαναφέρετε (επιτρέποντας σε έναν καλούντα να χειριστεί και την εξαίρεση):

@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

Η πρόταση @ref{ad6,,try} … @ref{447,,except} έχει ένα προαιρετικό `else clause', το οποίο, όταν υπάρχει, πρέπει να ακολουθεί όλες τις `except clauses'.  Είναι χρήσιμο για κώδικα που πρέπει να εκτελεστεί εάν το `try clause' δεν κάνει raise μια εξαίρεση. Για παράδειγμα:

@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

Η χρήση της πρότασης @code{else} είναι καλύτερη από την προσθήκη πρόσθετου κώδικα στην πρόταση @ref{ad6,,try}, επειδή αποφεύγει την κατά λάθος σύλληψη μιας εξαίρεσης που δεν προέκυψε από τον κώδικα που προστατεύεται από την πρόταση @code{try} … @code{except}.

Οι χειριστές εξαιρέσεων δεν χειρίζονται μόνο τις εξαιρέσεις που εμφανίζονται αμέσως στη `try clause', αλλά και εκείνες που εμφανίζονται μέσα σε συναρτήσεις που καλούνται (ακόμη και έμμεσα) στην `try clause'. Για παράδειγμα:

@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 Raising Εξαιρέσεων,Αλυσιδωτές Εξαιρέσεις,Διαχείριση Εξαιρέσεων,Σφάλματα και Εξαιρέσεις
@anchor{tutorial/errors raising-exceptions}@anchor{2267}@anchor{tutorial/errors tut-raising}@anchor{2268}
@subsection Raising Εξαιρέσεων


Η δήλωση @ref{9e4,,raise} επιτρέπει στον προγραμματιστή να αναγκάσει να εμφανιστεί μια καθορισμένη εξαίρεση. Για  παράδειγμα:

@example
>>> raise NameError('HiThere')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    raise NameError('HiThere')
NameError: HiThere
@end example

Το μοναδικό όρισμα στο @ref{9e4,,raise} υποδεικνύει την εξαίρεση που πρέπει να γίνει raise. Αυτή πρέπει να είναι είτε μια παρουσία εξαίρεσης ή μια εξαίρεση κλάση (μια κλάση που προέρχεται από @ref{9b9,,BaseException}, όπως @ref{d9e,,Exception} ή μία από τις υποκλάσεις της). Εάν περάσει μια κλάση εξαίρεσης, θα δημιουργηθεί σιωπηρά καλώντας τον constructor της χωρίς ορίσματα:

@example
κάνει raise ένα ValueError # συντομογραφία για το 'raise ValueError()'
@end example

Εάν πρέπει να προσδιορίσετε εάν έχει εγγραφεί μια εξαίρεση, αλλά δεν σκοπεύετε να τη χειριστείτε, μια απλούστερη μορφή της δήλωσης @ref{9e4,,raise} σας επιτρέπει να κάνετε ξανά raise την εξαίρεση:

@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 Αλυσιδωτές Εξαιρέσεις,Εξαιρέσεις που καθορίζονται από το χρήστη,Raising Εξαιρέσεων,Σφάλματα και Εξαιρέσεις
@anchor{tutorial/errors exception-chaining}@anchor{2269}@anchor{tutorial/errors tut-exception-chaining}@anchor{226a}
@subsection Αλυσιδωτές Εξαιρέσεις


Εάν παρουσιαστεί μια μη χειριζόμενη (unhandled) εξαίρεση μέσα σε μια ενότητα @ref{447,,except}, θα επισυνάψει την εξαίρεση που θα χειριστεί και θα συμπεριληφθεί στο μήνυμα σφάλματος:

@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

Για να υποδείξετε ότι μια εξαίρεση είναι άμεση συνέπεια μιας άλλης, η πρόταση @ref{9e4,,raise} επιτρέπει μια προαιρετική πρόταση @code{from}:

@example
# Το exc πρέπει να είναι παράδειγμα εξαίρεσης ή None.
κάνει raise το RuntimeError από exc
@end example

Αυτό μπορεί να είναι χρήσιμο όταν μετασχηματίζεται εξαιρέσεις. Για παράδειγμα:

@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

Επιτρέπει επίσης την απενεργοποίηση της αυτόματης αλυσίδας εξαιρέσεων χρησιμοποιώντας @code{from None} idiom:

@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

Για περισσότερες πληροφορίες σχετικά με την μηχανική αλυσίδων, δείτε @ref{1e1e,,Built-in Exceptions}.

@node Εξαιρέσεις που καθορίζονται από το χρήστη,Καθορισμός ενεργειών καθαρισμού,Αλυσιδωτές Εξαιρέσεις,Σφάλματα και Εξαιρέσεις
@anchor{tutorial/errors tut-userexceptions}@anchor{226b}@anchor{tutorial/errors user-defined-exceptions}@anchor{226c}
@subsection Εξαιρέσεις που καθορίζονται από το χρήστη


Τα  προγράμματα μπορούν να ονομάσουν τις δικές τους εξαιρέσεις δημιουργώντας μια νέα κλάση εξαιρέσεων (δείτε @ref{21ef,,Κλάσεις} για περισσότερα σχετικά με τις κλάσεις Python).  Οι εξαιρέσεις θα πρέπει συνήθως να προέρχονται από την κλάση @ref{d9e,,Exception}, είτε άμεσα είτε έμμεσα.

Μπορούν να οριστούν κλάσεις εξαίρεσης που κάνουν οτιδήποτε μπορεί να κάνει οποιαδήποτε άλλη κλάση, αλλά συνήθως διατηρούνται απλές, συχνά προσφέρουν μόνο έναν αριθμό χαρακτηριστικών που επιτρέπουν την εξαγωγή πληροφοριών σχετικά με το σφάλμα από τους χειριστές για την εξαίρεση.

Οι περισσότερες εξαιρέσεις ορίζονται με ονόματα που τελειώνουν σε «Error», παρόμοια με την ονομασία των τυπικών εξαιρέσεων.

Πολλά standard modules ορίζουν τις δικές τους εξαιρέσεις για την αναφορά σφαλμάτων που μπορεί να προκύψουν σε συναρτήσεις που ορίζουν.

@node Καθορισμός ενεργειών καθαρισμού,Προκαθορισμένες ενέργειες καθαρισμού,Εξαιρέσεις που καθορίζονται από το χρήστη,Σφάλματα και Εξαιρέσεις
@anchor{tutorial/errors defining-clean-up-actions}@anchor{226d}@anchor{tutorial/errors tut-cleanup}@anchor{226e}
@subsection Καθορισμός ενεργειών καθαρισμού


Η δήλωση @ref{ad6,,try} έχει μια άλλη προαιρετική πρόταση που προορίζεται να ορίσει ενέργειες καθαρισμού που πρέπει να εκτελεστούν υπό οποιεσδήποτε συνθήκες.  Για παράδειγμα:

@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

Εάν υπάρχει μια πρόταση @ref{44c,,finally}, η πρόταση @code{finally} θα εκτελεστεί ως η τελευταία εργασία πριν από την ολοκλήρωση της πρότασης @ref{ad6,,try}. Η πρόταση @code{finally} εκτελείται είτε όχι η πρόταση @code{try} παράγει μια εξαίρεση. Τα ακόλουθα σημεία συζητούν πιο περίπλοκες περιπτώσεις όταν εμφανίζεται μια εξαίρεση:


@itemize *

@item 
Εάν παρουσιαστεί μια εξαίρεση κατά την εκτέλεση της πρότασης @code{try}, η εξαίρεση μπορεί να αντιμετωπιστεί από μια πρόταση @ref{447,,except}, Εάν η εξαίρεση δεν αντιμετωπίζεται από μια πρόταση @code{except}, η εξαίρεση γίνεται ξανά raise μετά την εκτέλεση της πρότασης @code{finally}.

@item 
Μια εξαίρεση θα μπορούσε να προκύψει κατά την εκτέλεση μιας πρότασης @code{except} ή @code{else}. Και πάλι, η εξαίρεση τίθεται ξανά μετά την εκτέλεση της πρότασης @code{finally}.

@item 
Εάν η πρόταση @code{finally} εκτελέσει μια πρόταση @ref{428,,break}, @ref{429,,continue} ή @ref{44b,,return}, οι εξαιρέσεις δεν γίνονται raise εκ νέου. Αυτό μπορεί να προκαλέσει σύγχυση και ως εκ τούτου αποθαρρύνεται. Από την έκδοση 3.14, ο μεταγλωττιστής εκπέμπει μια @ref{44a,,SyntaxWarning} για αυτό (δείτε 
@geindex Python Enhancement Proposals; PEP 765
PEP 765@footnote{https://peps.python.org/pep-0765/}).

@item 
Εάν η πρόταση @code{try} φτάσει σε μια δήλωση @ref{428,,break}, @ref{429,,continue} ή @ref{44b,,return}, η πρόταση @code{finally} θα εκτελεστεί ακριβώς πριν από τα @code{break}, @code{continue} or @code{return} της εκτέλεσης της δήλωσης.

@item 
Εάν μια πρόταση @code{finally} περιλαμβάνει μια δήλωση @code{return}, η τιμή που επιστρέφεται θα είναι αυτή από την πρόταση @code{finally} της δήλωσης της @code{return}, και όχι η τιμή από τη δήλωση @code{try} της πρότασης @code{return}. Αυτό μπορεί να προκαλέσει σύγχυση και επομένως αποθαρρύνεται. Από την έκδοση 3.14, ο μεταγλωττιστής εκπέμπει ένα @ref{44a,,SyntaxWarning} για αυτό (δείτε 
@geindex Python Enhancement Proposals; PEP 765
PEP 765@footnote{https://peps.python.org/pep-0765/}).
@end itemize

Για παράδειγμα:

@example
>>> def bool_return():
...     try:
...         return True
...     finally:
...         return False
...
>>> bool_return()
False
@end example

Ένα πιο περίπλοκο παράδειγμα:

@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

Όπως μπορείτε να δείτε, η πρόταση @ref{44c,,finally} εκτελείται σε οποιαδήποτε περίπτωση.  Το @ref{291,,TypeError} που δημιουργείται με τη διαίρεση δύο συμβολοσειρών δεν χειρίζεται από την πρόταση @ref{447,,except} και επομένως γίνεται ξανά raise μετά την εκτέλεση του όρου @code{finally}.

Στις εφαρμογές του πραγματικού κόσμου, η πρόταση @ref{44c,,finally} είναι χρήσιμη για την απελευθέρωση εξωτερικών πόρων (όπως αρχεία ή συνδέσεις δικτύου), ανεξάρτητα από το εάν η χρήση του πόρου ήταν επιτυχής.

@node Προκαθορισμένες ενέργειες καθαρισμού,Raising και Χειρισμός Πολλαπλών Άσχετων Εξαιρέσεων,Καθορισμός ενεργειών καθαρισμού,Σφάλματα και Εξαιρέσεις
@anchor{tutorial/errors predefined-clean-up-actions}@anchor{226f}@anchor{tutorial/errors tut-cleanup-with}@anchor{2270}
@subsection Προκαθορισμένες ενέργειες καθαρισμού


Μερικά αντικείμενα ορίζουν τις τυπικές ενέργειες καθαρισμού που πρέπει να αναλαμβάνονται όταν το αντικείμενο δεν χρειάζεται πλέον, ανεξάρτητα από το εάν η λειτουργία που χρησιμοποιεί το αντικείμενο πέτυχε ή απέτυχε. Κοιτάξτε το ακόλουθο αντικείμενο, το οποίο προσπαθεί να ανοίξει ένα αρχείο και να εκτυπώσει τα περιεχόμενα του στην οθόνη.

@example
for line in open("myfile.txt"):
    print(line, end="")
@end example

Το πρόβλημα με αυτόν τον κώδικα είναι ότι αφήνει το αρχείο ανοιχτό για απροσδιόριστο χρονικό διάστημα μετά την ολοκλήρωση της εκτέλεσης αυτού του τμήματος του κώδικα. Αυτό δεν είναι πρόβλημα σε απλά σενάρια, αλλά μπορεί να είναι πρόβλημα για μεγαλύτερες εφαρμογές. Η δήλωση @ref{20a,,with} επιτρέπει σε αντικείμενα όπως αρχεία να χρησιμοποιούνται με τρόπο που διασφαλίζει ότι καθαρίζονται πάντα άμεσα και σωστά.

@example
with open("myfile.txt") as f:
    for line in f:
        print(line, end="")
@end example

Μετά την εκτέλεση της πρότασης, το αρχείο `f' είναι πάντα κλειστό, ακόμα και αν παρουσιάστηκε πρόβλημα κατά την επεξεργασία των γραμμών. Τα αντικείμενα που, όπως τα αρχεία παρέχουν προκαθορισμένες ενέργειες καθαρισμού θα το υποδεικνύουν στην τεκμηρίωση τους.

@node Raising και Χειρισμός Πολλαπλών Άσχετων Εξαιρέσεων,Εμπλουτίζοντας τις Εξαιρέσεις με Σημειώσεις,Προκαθορισμένες ενέργειες καθαρισμού,Σφάλματα και Εξαιρέσεις
@anchor{tutorial/errors raising-and-handling-multiple-unrelated-exceptions}@anchor{2271}@anchor{tutorial/errors tut-exception-groups}@anchor{2272}
@subsection Raising και Χειρισμός Πολλαπλών Άσχετων Εξαιρέσεων


Υπάρχουν περιπτώσεις όπου είναι απαραίτητο να αναφερθούν πολλές εξαιρέσεις που έχουν συμβεί. Αυτό συμβαίνει συχνά σε πλαίσια ταυτόχρονης χρήσης, όταν πολλές εργασίες μπορεί να έχουνε αποτύχει παράλληλα, αλλά υπάρχουν και άλλες περιπτώσεις χρήσης όπου είναι επιθυμητό να συνεχιστεί η εκτέλεση και η συλλογή πολλαπλών σφαλμάτων αντί να κάνει raise την πρώτη εξαίρεση.

Η ενσωματωμένη (builtin) @ref{6d8,,ExceptionGroup} αναδιπλώνει μια λίστα με παρουσίες εξαιρέσεων ώστε να μπορούν να αυξηθούν μαζί. Είναι μια εξαίρεση από μόνη της, επομένως μπορεί να συλληφθεί όπως κάθε άλλη εξαίρεση.

@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'>: there were problems (2 sub-exceptions)
>>>
@end example

Χρησιμοποιώντας @code{except*} αντί για @code{except}, μπορούμε επιλεκτικά να χειριστούμε μόνο τις εξαιρέσεις στην ομάδα που αντιστοιχούν σε έναν συγκεκριμένο τύπο. Στο παρακάτω παράδειγμα, το οποίο δείχνει μια ένθετη ομάδα εξαιρέσεων, κάθε πρόταση @code{except*} εξάγει από τις εξαιρέσεις της ομάδας ενός συγκεκριμένου τύπου, ενώ αφήνει όλες τις άλλες εξαιρέσεις να διαδοθούν σε άλλες προτάσεις και τελικά να ξαναγίνουν raise.

@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

Λάβετε υπόψη ότι οι εξαιρέσεις που είναι ένθετες σε μια ομάδα εξαιρέσεων πρέπει να είναι στιγμιότυπα, όχι τύποι. Αυτό συμβαίνει επειδή στην πράξη οι εξαιρέσεις θα ήταν συνήθως αυτές που έχουν ήδη αναφερθεί και καταγραφεί από το πρόγραμμα, σύμφωνα με το ακόλουθο μοτίβο:

@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 Εμπλουτίζοντας τις Εξαιρέσεις με Σημειώσεις,,Raising και Χειρισμός Πολλαπλών Άσχετων Εξαιρέσεων,Σφάλματα και Εξαιρέσεις
@anchor{tutorial/errors enriching-exceptions-with-notes}@anchor{2273}@anchor{tutorial/errors tut-exception-notes}@anchor{2274}
@subsection Εμπλουτίζοντας τις Εξαιρέσεις με Σημειώσεις


Όταν δημιουργείται μια εξαίρεση προκειμένου να γίνει raise, συνήθως αρχικοποιείται με πληροφορίες που περιγράφουν το σφάλμα που έχει προκύψει. Υπάρχουν περιπτώσεις όπου είναι χρήσιμο να προστεθούν πληροφορίες μετά την σύλληψη της εξαίρεσης. Για το σκοπό αυτό, οι εξαιρέσεις έχουνε μια μέθοδο @code{add_note(note)} που δέχεται μια συμβολοσειρά και την προσθέτει στη λίστα σημειώσεων της εξαίρεσης. Η standard απόδοση παρακολούθησης περιλαμβάνει όλες τις σημειώσεις, με τη σειρά που προστέθηκα, μετά την εξαίρεση.

@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

Για παράδειγμα, όταν συλλέγουμε εξαιρέσεις σε μια ομάδα εξαιρέσεων, μπορεί να θέλουμε να προσθέσουμε πληροφορίες περιβάλλοντος για τα μεμονωμένα σφάλματα. Στην συνέχεια κάθε εξαίρεση στην ομάδα έχει μια σημείωση που υποδεικνύει πότε έχει συμβεί αυτό το σφάλμα.

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Κλάσεις,Brief tour of the standard library,Σφάλματα και Εξαιρέσεις,Οδηγός εκμάθησης Python
@anchor{tutorial/classes doc}@anchor{2275}@anchor{tutorial/classes classes}@anchor{2276}@anchor{tutorial/classes translation-repo}@anchor{2277}@anchor{tutorial/classes tut-classes}@anchor{21ef}
@section Κλάσεις


Οι κλάσεις παρέχουν ένα μέσο ομαδοποίησης δεδομένων και λειτουργικότητας. Η δημιουργία μιας νέας κλάσης δημιουργεί έναν νέο `τύπο' αντικειμένου, επιτρέποντας νέα `στιγμιότυπα' αυτού του τύπου που πρόκειται να γίνουν. Κάθε στιγμιότυπο κλάσης μπορεί να έχει χαρακτηριστικά που συνδέονται με αυτό για τη διατήρηση της κατάστασής του. Τα στιγμιότυπα κλάσης μπορούν να έχουν επίσης μεθόδους (που ορίζονται από την κλάση του) για την τροποποίηση της κατάστασής του.

Σε σύγκριση με άλλες γλώσσες προγραμματισμού, ο μηχανισμός κλάσης της Python προσθέτει κλάσεις με ελάχιστο νέο συντακτικό και σημασιολογία. Είναι ένα μείγμα των μηχανισμών κλάσεων που βρέθηκαν στη C++ και στο Modula-3. Οι κλάσεις της Python παρέχουν όλα τα standard χαρακτηριστικά του Αντικειμενοστραφούς Προγραμματισμού: ο μηχανισμός της κληρονομικότητας της κλάσης επιτρέπει την ύπαρξη πολλαπλών βασικών κλάσεων, μια παραγόμενη κλάση να μπορεί να παρακάμψει οποιεσδήποτε μεθόδους της βασικής κλάσης ή κλάσεων, και μια μέθοδος να μπορεί να καλέσει τη μέθοδο μίας βασικής κλάσης με το ίδιο όνομα. Τα αντικείμενα μπορούν να περιέχουν αυθαίρετα ποσά και είδη δεδομένων. Όπως ισχύει για τα modules, οι κλάσεις συμμετέχουν στη δυναμική φύση της Python: δημιουργούνται κατά το χρόνο εκτέλεσης και μπορούν να τροποποιηθούν περαιτέρω μετά τη δημιουργία.

Στην ορολογία της C++, συνήθως τα μέλη της κλάσης (συμπεριλαμβανομένων των μελών δεδομένων) είναι `δημόσια' (εκτός από βλέπε παρακάτω @ref{2278,,Ιδιωτικές Μεταβλητές}), και όλες οι συμμετέχουσες συναρτήσεις είναι `εικονικές'. Όπως και στο Modula-3, δεν υπάρχουν συντομογραφίες για την αναφορά στα μέλη του αντικειμένου από τις μεθόδους του: η μέθοδος δηλώνεται με ρητό πρώτο όρισμα που αντιπροσωπεύει το αντικείμενο, το οποίο παρέχεται έμμεσα από την κλήση. Όπως και στο Smalltalk, οι ίδιες οι κλάσεις είναι αντικείμενα.Αυτό παρέχει σημασιολογία για εισαγωγή και μετονομασία. Σε αντίθεση με τις γλώσσες C++ και Modula-3, οι built-in τύποι μπορούν να χρησιμοποιηθούν ως βασικές κλάσεις για επέκταση από τον χρήστη. Επίσης, όπως στην C++, οι περισσότεροι built-in τελεστές με ειδική σύνταξη (αριθμητικοί τελεστές, εγγραφή κ.λπ.) μπορούν να επαναπροσδιοριστούν για τα στιγμιότυπα κλάσης.

(Ελλείψει καθολικής αποδεκτής ορολογίας για να μιλήσω για τις κλάσεις, θα κάνω περιστασιακή χρήση όρων από τη Smalltalk και τη C++. Θα χρησιμοποιούσα όρους  από τη Modula-3, καθώς η αντικειμενοστραφής σημασιολογία του είναι πιο κοντά σε αυτήν της Python από ότι της C++, Αλλά πιστεύω ότι λίγοι αναγνώστες το έχουν ακούσει.)

@menu
* Λίγα λόγια για Ονόματα και Αντικείμενα:: 
* Εμβέλεια και Πεδία Ονομάτων στην Python:: 
* Μια πρώτη ματιά στις Κλάσεις:: 
* Τυχαίες Παρατηρήσεις:: 
* Κληρονομικότητα:: 
* Ιδιωτικές Μεταβλητές:: 
* Μικροπράγματα:: 
* Επαναλήπτες:: 
* Γεννήτορες (Generators): Γεννήτορες Generators. 
* Εκφράσεις Γεννήτορων:: 

@end menu

@node Λίγα λόγια για Ονόματα και Αντικείμενα,Εμβέλεια και Πεδία Ονομάτων στην Python,,Κλάσεις
@anchor{tutorial/classes a-word-about-names-and-objects}@anchor{2279}@anchor{tutorial/classes tut-object}@anchor{227a}
@subsection Λίγα λόγια για Ονόματα και Αντικείμενα


Τα αντικείμενα έχουν μοναδικότητα και πολλά ονόματα (σε πολλαπλά πεδία) μπορούν να συνδεθούν στο ίδιο αντικείμενο. Αυτό είναι γνωστό ως ψευδώνυμο σε άλλες γλώσσες.Αυτό συνήθως δεν εκτιμάται με μια πρώτη ματιά στην Python και μπορεί να αγνοείται με ασφάλεια όταν ασχολείται με αμετάβλητους βασικούς τύπους (αριθμοί, συμβολοσειρές, πλειάδες (tuples)). Ωστόσο, το ψευδώνυμο έχει μια πιθανώς εκπληκτική επίδραση στη σημασιολογία του κώδικα της Python που περιλαμβάνει ευμετάβλητα αντικείμενα όπως λίστες, λεξικά, και τους περισσότερους άλλους τύπους. Αυτό χρησιμοποιείται συνήθως προς όφελος του προγράμματος, δεδομένου ότι τα ψευδώνυμα συμπεριφέρονται σαν δείκτες από ορισμένες απόψεις. Για παράδειγμα, η μετάδοση ενός αντικειμένου είναι ανέξοδη αφού μόνο ένας δείκτης περνά από την υλοποίηση, και αν μια συνάρτηση τροποποιεί ένα αντικείμενο που έχει περάσει ως όρισμα, ο καλών θα δει την αλλαγή — αυτό εξαλείφει την ανάγκη για δύο διαφορετικούς μηχανισμούς μετάδοσης ορισμάτων όπως στην Pascal.

@node Εμβέλεια και Πεδία Ονομάτων στην Python,Μια πρώτη ματιά στις Κλάσεις,Λίγα λόγια για Ονόματα και Αντικείμενα,Κλάσεις
@anchor{tutorial/classes python-scopes-and-namespaces}@anchor{227b}@anchor{tutorial/classes tut-scopes}@anchor{222f}
@subsection Εμβέλεια και Πεδία Ονομάτων στην Python


Πριν από την εισαγωγή των κλάσεων, πρέπει πρώτα να σας πω κάτι για τους κανόνες εμβέλειας της Python. Οι ορισμοί των κλάσεων παίζουν μερικά ξεκάθαρα κόλπα με τα πεδία ονομάτων και πρέπει να γνωρίζετε πώς λειτουργούν πλήρως τα πεδία ονομάτων και η εμβέλεια για να κατανοήσετε πλήρως τι συμβαίνει. Παρεμπιπτόντως, η γνώση για αυτό το θέμα είναι χρήσιμη για κάθε προχωρημένο προγραμματιστή της Python.

Ας ξεκινήσουμε με ορισμένους ορισμούς.

Ένας `πεδίο ονομάτων (namespace)' είναι μια αντιστοίχιση από ονόματα σε αντικείμενα. Τα περισσότερα πεδία ονομάτων υλοποιούνται επί του παρόντος ως λεξικά Python, αλλά αυτό συνήθως δεν γίνεται αντιληπτό με κανέναν τρόπο (εκτός από την απόδοση) και μπορεί να αλλάξει στο μέλλον. Παραδείγματα πεδίων ονομάτων είναι: το σύνολο των ενσωματωμένων ονομάτων (που περιέχει συναρτήσεις όπως @ref{227c,,abs()} και ενσωματωμένα ονόματα εξαιρέσεων)∙ τα καθολικά ονόματα σε ένα module και τα τοπικά ονόματα σε μια επίκληση συνάρτησης. Κατά μία έννοια το σύνολο των χαρακτηριστικών ενός αντικειμένου σχηματίζει επίσης ένα πεδίο ονομάτων. Το σημαντικό πράγμα που πρέπει να γνωρίζετε για τα πεδία ονομάτων είναι ότι δεν υπάρχει καμία απολύτως σχέση μεταξύ ονομάτων σε διαφορετικά πεδία ονομάτων, για παράδειγμα, δύο διαφορετικά modules μπορεί και τα δύο να ορίσουν μια συνάρτηση @code{maximize} χωρίς σύγχυση — χρήστες των modules πρέπει να την προσθέσουν με το όνομα του module.

Παρεμπιπτόντως, χρησιμοποιώ τη λέξη `attribute' για οποιοδήποτε όνομα που ακολουθεί μια τελεία — για παράδειγμα, στην έκφραση @code{z.real}, το @code{real} είναι ένα attribute του αντικειμένου @code{z}. Αυστηρά μιλώντας, οι αναφορές σε ονόματα των modules είναι αναφορές σε attributes: στην έκφραση @code{modname.funcname}, το @code{modname} είναι ένα module αντικείμενο  και το @code{funcname} είναι ένα attribute του αντικειμένου. Σε αυτήν την περίπτωση συμβαίνει να υπάρχει μια απλή αντιστοίχιση μεταξύ των attributes των modules και των καθολικών ονομάτων που ορίζονται στο module: μοιράζονται τον ίδιο χώρο ονομάτων! @footnote{
Εκτός από ένα πράγμα. Τα αντικείμενα του module έχουν ένα μυστικό χαρακτηριστικό μόνο για ανάγνωση που καλείται @ref{1bf,,__dict__} το οποίο επιστρέφει το λεξικό που χρησιμοποιείται για την υλοποίηση του χώρου ονομάτων του module.Το όνομα @code{__dict__} είναι ένα χαρακτηριστικό αλλά όχι καθολικό όνομα. Προφανώς, η χρήση αυτού παραβιάζει την αφαίρεση υλοποίησης χώρου ονομάτων και θα πρέπει να περιορίζεται σε πράγματα όπως τα ύστερα προγράμματα εντοπισμού σφαλμάτων.
}

Τα attributes μπορεί να είναι μόνο για ανάγνωση ή εγγράψιμα. Στην τελευταία περίπτωση, είναι δυνατή η ανάθεση attributes. Τα attributes των modules είναι εγγράψιμα: μπορείτε να γράψετε @code{modname.the_answer = 42}. Τα εγγράψιμα attributes μπορούν επίσης να διαγραφούν με την δήλωση @ref{1d1d,,del}. Για παράδειγμα, @code{del modname.the_answer} θα αφαιρέσει το attribute @code{the_answer} από το αντικείμενο που ονομάστηκε από το @code{modname}.

Οι χώροι ονομάτων δημιουργούνται σε διαφορετικές στιγμές και έχουν διαφορετική διάρκεια ζωής.Ο χώρος ονομάτων που περιέχει τα built-in ονόματα δημιουργείται κατά την εκκίνηση του διερμηνέα της Python και δεν διαγράφεται ποτέ. Ο καθολικός χώρος ονομάτων για ένα module δημιουργείται όταν διαβάζεται ο ορισμός του module. Κανονικά, οι χώροι ονομάτων των modules διαρκούν επίσης μέχρι να τερματιστεί ο διερμηνέας. Οι δηλώσεις που εκτελούνται από την επίκληση ανώτατου επιπέδου του διερμηνέα, είτε διαβάζονται από ένα script είτε διαδραστικά, θεωρούνται μέρος ενός module που ονομάζεται @ref{1,,__main__}, επομένως έχουν τον δικό τους καθολικό χώρο ονομάτων. (Τα ενσωματωμένα ονόματα στην πραγματικότητα υπάρχουν επίσης σε ένα module,αυτό ονομάζεται @ref{13,,builtins}.)

Ο τοπικός χώρος ονομάτων για μια συνάρτηση δημιουργείται όταν καλείται η συνάρτηση, και διαγράφεται όταν η συνάρτηση επιστρέφει ή δημιουργεί μια εξαίρεση που δεν αντιμετωπίζεται στην συνάρτηση. (Στην πραγματικότητα, η λήθη θα ήταν καλύτερος τρόπος για να περιγράψουμε τι πραγματικά συμβαίνει.) Φυσικά, οι επαναλαμβανόμενες επικλήσεις έχουν το δικό τους τοπικό χώρο ονομάτων.

Η εμβέλεια είναι μια περιοχή κειμένου ενός προγράμματος Python όπου ένας χώρος ονομάτων είναι άμεσα προσβάσιμος. Το «Άμεση πρόσβαση» εδώ σημαίνει ότι μια ανεπιφύλακτη αναφορά σε ένα όνομα προσπαθεί να βρει το όνομα στον χώρο ονομάτων.

Παρόλο που τα πεδία προσδιορίζονται στατικά, χρησιμοποιούνται δυναμικά. Σε οποιοδήποτε χρόνο κατά την διάρκεια της εκτέλεσης, υπάρχουν 3 ή 4 ένθετα πεδία των οποίων οι χώροι ονομάτων είναι άμεσα προσβάσιμοι:


@itemize *

@item 
η ενδότερη εμβέλεια, η οποία αναζητείται πρώτα, περιέχει τα τοπικά ονόματα

@item 
η εμβέλεια οποιωνδήποτε εσωκλειόμενων συναρτήσεων, τα οποία αναζητούνται ξεκινώντας από την πλησιέστερη εσωκλειόμενη εμβέλεια, περιέχει μη τοπικά, αλλά και μη καθολικά ονόματα

@item 
η επόμενη προς την τελευταία εμβέλεια περιέχει τα τρέχοντα καθολικά ονόματα του module

@item 
η πιο απομακρυσμένη εμβέλεια (που έγινε τελευταία αναζήτηση) είναι ο χώρος ονομάτων που περιέχει built-in ονόματα
@end itemize

Εάν ένα όνομα έχει δηλωθεί ως καθολικό, τότε όλες οι αναφορές και οι εκχωρήσεις πηγαίνουν απευθείας στο επόμενο προς το τελευταίο πεδίο που περιέχει τα καθολικά ονόματα του module. Για την επανασύνδεση μεταβλητών που βρίσκονται εκτός της ενδότερης εμβέλειας ,μπορεί να χρησιμοποιηθεί η δήλωση του @ref{164c,,nonlocal} . Εάν δεν δηλωθούν ως μη τοπικές, αυτές οι μεταβλητές είναι μόνο για ανάγνωση (μια προσπάθεια εγγραφής σε μια τέτοια μεταβλητή θα δημιουργήσει απλώς μια `νέα' τοπική μεταβλητή στην ενδότερη εμβέλεια, αφήνοντας αμετάβλητη την εξωτερική μεταβλητή με το ίδιο όνομα ).

Συνήθως, η τοπική εμβέλεια παραπέμπει στα τοπικά ονόματα της (κείμενης) τρέχουσας συνάρτησης. Εκτός συναρτήσεων, η τοπική εμβέλεια αναφέρεται στον ίδιο χώρο ονομάτων με την καθολική εμβέλεια: τον χώρο ονομάτων του module.Οι ορισμοί κλάσεων τοποθετούν έναν ακόμη χώρο ονομάτων στην τοπική εμβέλεια.

Είναι σημαντικό να συνειδητοποιήσουμε ότι οι εμβέλειες καθορίζονται με κείμενο: η καθολική εμβέλεια μιας συνάρτησης που ορίζεται σε ένα module είναι ο χώρος ονομάτων αυτού του module ανεξάρτητα από το πού ή με ποιο ψευδώνυμο καλείται η συνάρτηση. Από την άλλη πλευρά, η πραγματική αναζήτηση ονομάτων γίνεται δυναμικά, κατά το χρόνο εκτέλεσης — ωστόσο, ο ορισμός της γλώσσας εξελίσσεται προς τη στατική ανάλυση ονομάτων, την ώρα της «μεταγλώττισης», επομένως μην βασίζεστε σε δυναμική ανάλυση ονόματος! (Στην πραγματικότητα, οι τοπικές μεταβλητές έχουν ήδη καθοριστεί στατικά.)

Μια ιδιαίτερη ιδιορρυθμία της Python είναι ότι – αν οι δηλώσεις @ref{6b5,,global} ή @ref{164c,,nonlocal} δεν είναι σε ισχύ – οι εκχωρήσεις στα ονόματα πηγαίνουν πάντα στην ενδότερη εμβέλεια. Οι εκχωρήσεις δεν αντιγράφουν δεδομένα — απλώς δεσμεύουν ονόματα σε αντικείμενα. Το ίδιο ισχύει και για τις διαγραφές: η δήλωση @cite{del x} αφαιρεί την σύνδεση του @code{x} από τον χώρο ονομάτων που αναφέρεται από την τοπική εμβέλεια. Στην πραγματικότητα, όλες οι λειτουργίες που εισάγουν νέα ονόματα χρησιμοποιούν την τοπική εμβέλεια: συγκεκριμένα οι δηλώσεις, @ref{9da,,import} και οι ορισμοί συναρτήσεων δεσμεύουν το όνομα του module ή της συνάρτησης στην τοπική εμβέλεια.

Η δήλωση @ref{6b5,,global} μπορεί να χρησιμοποιηθεί για να υποδείξει ότι συγκεκριμένες μεταβλητές ζουν στην καθολική εμβέλεια και θα πρέπει να ανακάμψουν εκεί. Η δήλωση @ref{164c,,nonlocal} υποδηλώνει ότι συγκεκριμένες μεταβλητές ζουν σε μια εσώκλειστη εμβέλεια και θα πρέπει να ανακάμψουν εκεί.

@menu
* Παράδειγμα Εμβέλειας και Χώρων Ονομάτων:: 

@end menu

@node Παράδειγμα Εμβέλειας και Χώρων Ονομάτων,,,Εμβέλεια και Πεδία Ονομάτων στην Python
@anchor{tutorial/classes scopes-and-namespaces-example}@anchor{227d}@anchor{tutorial/classes tut-scopeexample}@anchor{227e}
@subsubsection Παράδειγμα Εμβέλειας και Χώρων Ονομάτων


Αυτό είναι ένα παράδειγμα που δείχνει τον τρόπο αναφοράς στα διαφορετικά πεδία και χώρους ονομάτων και πώς τα @ref{6b5,,global} και @ref{164c,,nonlocal} επηρεάζουν τα variable binding:

@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

Το αποτέλεσμα του κώδικα στο παράδειγμα είναι:

@example
After local assignment: test spam
After nonlocal assignment: nonlocal spam
After global assignment: nonlocal spam
In global scope: global spam
@end example

Σημειώστε πώς η εκχώρηση `τοπική' (η οποία είναι προεπιλεγμένη) δεν άλλαξε την δέσμευση `scope_test''s  του `spam'. Η εκχώρηση @ref{164c,,nonlocal} άλλαξε την δέσμευση του `scope_test''s του `spam' και η εκχώρηση του @ref{6b5,,global} άλλαξε τη δέσμευση σε επίπεδο module.

Μπορείτε επίσης να δείτε ότι δεν υπήρχε προηγούμενη δέσμευση για `spam' πριν από την εκχώρηση @ref{6b5,,global}..

@node Μια πρώτη ματιά στις Κλάσεις,Τυχαίες Παρατηρήσεις,Εμβέλεια και Πεδία Ονομάτων στην Python,Κλάσεις
@anchor{tutorial/classes a-first-look-at-classes}@anchor{227f}@anchor{tutorial/classes tut-firstclasses}@anchor{220a}
@subsection Μια πρώτη ματιά στις Κλάσεις


Οι Κλάσεις εισάγουν λίγη νέα σύνταξη, τρεις νέους τύπους αντικειμένων και κάποια νέα σημασιολογία.

@menu
* Σύνταξη Ορισμού Κλάσης:: 
* Αντικείμενα Κλάσης:: 
* Αντικείμενα Στιγμιοτύπων:: 
* Αντικείμενα Μεθόδου:: 
* Μεταβλητές Κλάσης και Στιγμιότυπου:: 

@end menu

@node Σύνταξη Ορισμού Κλάσης,Αντικείμενα Κλάσης,,Μια πρώτη ματιά στις Κλάσεις
@anchor{tutorial/classes class-definition-syntax}@anchor{2280}@anchor{tutorial/classes tut-classdefinition}@anchor{2281}
@subsubsection Σύνταξη Ορισμού Κλάσης


Η απλούστερη μορφή ορισμού κλάσης μοιάζει με αυτό:

@example
class ClassName:
    <statement-1>
    .
    .
    .
    <statement-N>
@end example

Ορισμοί κλάσεων, όπως ορισμοί συναρτήσεων (@ref{17fc,,def} δηλώσεις) πρέπει να εκτελεστούν προτού έχουν οποιοδήποτε αποτέλεσμα. (Θα μπορούσατε να τοποθετήσετε έναν ορισμό κλάσης σε έναν κλάδο μιας δήλωσης @ref{322,,if} ή μέσα σε μια συνάρτηση.)

Στην πράξη, οι δηλώσεις μέσα σε έναν ορισμό κλάσης συνήθως θα είναι ορισμοί συναρτήσεων, αλλά επιτρέπονται άλλες δηλώσεις και μερικές φορές χρήσιμες — θα επανέλθουμε σε αυτό αργότερα. Οι ορισμοί συναρτήσεων μέσα σε μια κλάση συνήθως έχουν μια περίεργη μορφή λίστας ορισμάτων, που υπαγορεύεται από τις συμβάσεις κλήσης για μεθόδους — και πάλι, αυτό εξηγείται αργότερα.

Όταν εισάγεται ένας ορισμός κλάσης, δημιουργείται ένας νέος χώρος ονομάτων και χρησιμοποιείται ως τοπική εμβέλεια — επομένως, όλες οι εκχωρήσεις σε τοπικές μεταβλητές πηγαίνουν σε αυτόν τον νέο χώρο ονομάτων. Συγκεκριμένα, οι ορισμοί συναρτήσεων δεσμεύουν το όνομα της νέας συνάρτησης εδώ.

Όταν ένας ορισμός κλάσης αφήνεται κανονικά (μέσω του τέλους),δημιουργείται ένα `αντικείμενο κλάσης'. Αυτό είναι βασικά ένα περιτύλιγμα γύρω από τα περιεχόμενα του χώρου ονομάτων που δημιουργήθηκε από τον ορισμό κλάσης. θα μάθουμε περισσότερα για τα αντικείμενα κλάσης στην επόμενη ενότητα.Η αρχική τοπική εμβέλεια(αυτό που ίσχυε λίγο πριν από την εισαγωγή του ορισμού της κλάσης) αποκαθίσταται και το αντικείμενο κλάσης δεσμεύεται εδώ στο όνομα κλάσης που δίνεται στην κεφαλίδα ορισμού κλάσης (@code{ClassName} στο παράδειγμα).

@node Αντικείμενα Κλάσης,Αντικείμενα Στιγμιοτύπων,Σύνταξη Ορισμού Κλάσης,Μια πρώτη ματιά στις Κλάσεις
@anchor{tutorial/classes class-objects}@anchor{2282}@anchor{tutorial/classes tut-classobjects}@anchor{2283}
@subsubsection Αντικείμενα Κλάσης


Τα αντικείμενα κλάσης υποστηρίζουν δύο είδη πράξεων: αναφορές χαρακτηριστικών και στιγμιότυπο.

Οι `Αναφορές χαρακτηριστικών' χρησιμοποιούν την τυπική σύνταξη που χρησιμοποιείται για όλα τις αναφορές χαρακτηριστικών στην Python: @code{obj.name}. Τα έγκυρα ονόματα χαρακτηριστικών είναι όλα τα ονόματα που βρίσκονταν στον χώρο ονομάτων της κλάσης όταν δημιουργήθηκε το αντικείμενο της κλάσης. Έτσι, αν ο ορισμός της κλάσης έμοιαζε ως εξής:

@example
class MyClass:
    """A simple example class"""
    i = 12345

    def f(self):
        return 'hello world'
@end example

τότε τα @cite{MyClass.i} και @cite{MyClass.f} είναι έγκυρες αναφορές χαρακτηριστικών, επιστρέφοντας έναν ακέραιο και ένα αντικείμενο συνάρτησης, αντίστοιχα.Τα attributes κλάσης μπορούν επίσης να εκχωρηθούν, ώστε να μπορείτε να αλλάξετε την τιμή του @cite{MyClass.i} ανά ανάθεση. Το @ref{2284,,__doc__} είναι επίσης ένα έγκυρο χαρακτηριστικό, επιστρέφοντας το docstring που ανήκει στην κλάση: @code{"Ένα απλό παράδειγμα κλάσης"}.

Η κλάση `στιγμιότυπο' χρησιμοποιεί σημειογραφία συνάρτησης. Απλώς προσποιηθείτε ότι το αντικείμενο της κλάσης είναι μια συνάρτηση χωρίς παραμέτρους που επιστρέφει ένα νέο στιγμιότυπο της κλάσης.Για παράδειγμα (υποθέτοντας την παραπάνω κλάση):

@example
x = MyClass()
@end example

δημιουργεί ένα νέο `στιγμιότυπο' της κλάσης και εκχωρεί αυτό το αντικείμενο στην τοπική μεταβλητή @code{x}.

Η λειτουργία του στιγμιότυπου («calling» ένα αντικείμενο κλάσης) δημιουργεί ένα κενό αντικείμενο. Σε πολλές κλάσεις αρέσει να δημιουργούν αντικείμενα με στιγμιότυπα προσαρμοσμένα σε μια συγκεκριμένη αρχική κατάσταση. Επομένως μια κλάση μπορεί να ορίσει μια ειδική μέθοδο με το όνομα @ref{2fa,,__init__()}, όπως αυτό:

@example
def __init__(self):
    self.data = []
@end example

Όταν μια κλάση ορίζει μια μέθοδο @ref{2fa,,__init__()}, το στιγμιότυπο κλάσης καλεί αυτόματα @code{__init__()} για το στιγμιότυπο κλάσης που δημιουργήθηκε πρόσφατα. Έτσι σε αυτό το παράδειγμα,ένα νέο, αρχικοποιημένο στιγμιότυπο μπορεί να ληφθεί από:

@example
x = MyClass()
@end example

Φυσικά, η μέθοδος @ref{2fa,,__init__()} μπορεί να έχει ορίσματα για μεγαλύτερη ευελιξία. Σε αυτήν την περίπτωση, τα ορίσματα που δίνονται στον τελεστή στιγμιότυπου κλάσης μεταβιβάζονται σε @code{__init__()}. Για παράδειγμα,

@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 Αντικείμενα Στιγμιοτύπων,Αντικείμενα Μεθόδου,Αντικείμενα Κλάσης,Μια πρώτη ματιά στις Κλάσεις
@anchor{tutorial/classes instance-objects}@anchor{2285}@anchor{tutorial/classes tut-instanceobjects}@anchor{2286}
@subsubsection Αντικείμενα Στιγμιοτύπων


Τώρα τι μπορούμε να κάνουμε με τα αντικείμενα στιγμιοτύπων; Οι μόνες λειτουργίες που γίνονται κατανοητές από τα αντικείμενα στιγμιοτύπων είναι οι αναφορές χαρακτηριστικών. Υπάρχουν δύο είδη έγκυρων ονομάτων attributes: attributes και μέθοδοι δεδομένων.

`Τα χαρακτηριστικά δεδομένων' αντιστοιχούν στις «μεταβλητές στιγμιότυπου» στο Smalltalk και στα «μέλη δεδομένων» στη C++. Τα χαρακτηριστικά δεδομένων δεν χρειάζεται να δηλωθούν, όπως και οι τοπικές μεταβλητές, εμφανίζονται όταν εκχωρούνται για πρώτη φορά. Για παράδειγμα, εάν το @code{x} είναι στιγμιότυπο της @code{MyClass} που δημιουργήθηκε παραπάνω, το ακόλουθο κομμάτι κώδικα θα εκτυπώσει την τιμή @code{16}, χωρίς να αφήσει ίχνος:

@example
x.counter = 1
while x.counter < 10:
    x.counter = x.counter * 2
print(x.counter)
del x.counter
@end example

Το άλλο είδος αναφοράς χαρακτηριστικού στιγμιότυπου είναι μια `μέθοδος'. Μια μέθοδος είναι μια συνάρτηση που «ανήκει» σε ένα αντικείμενο.

@geindex αντικείμενο;μέθοδος

Τα έγκυρα ονόματα μεθόδων ενός αντικειμένου στιγμιότυπου εξαρτώνται από την κλάση του. Εξ ορισμού, όλα τα χαρακτηριστικά μιας κλάσης που είναι αντικείμενα συνάρτησης ορίζουν τις αντίστοιχες μεθόδους των στιγμιοτύπων της. Έτσι στο παράδειγμά μας, το @cite{x.f} είναι μια έγκυρη αναφορά μεθόδου, αφού το @cite{MyClass.f} είναι συνάρτηση, αλλά το @cite{x.i} δεν είναι αφού το @cite{MyClass.i} δεν είναι. Αλλά το @cite{x.f} δεν είναι το ίδιο πράγμα με το @cite{MyClass.f} — είναι ένα `αντικείμενο μεθόδου', όχι ένα αντικείμενο συνάρτησης.

@node Αντικείμενα Μεθόδου,Μεταβλητές Κλάσης και Στιγμιότυπου,Αντικείμενα Στιγμιοτύπων,Μια πρώτη ματιά στις Κλάσεις
@anchor{tutorial/classes method-objects}@anchor{2287}@anchor{tutorial/classes tut-methodobjects}@anchor{2288}
@subsubsection Αντικείμενα Μεθόδου


Συνήθως, μια μέθοδος καλείται αμέσως μετά τη δέσμευσή της:

@example
x.f()
@end example

Αν @code{x = MyClass()}, όπως παραπάνω, αυτό θα επιστρέψει τη συμβολοσειρά @code{'hello world'}. Ωστόσο, δεν είναι απαραίτητο να καλέσετε μια μέθοδο αμέσως: το @code{x.f} είναι ένα αντικείμενο μεθόδου και μπορεί να αποθηκευτεί και να κληθεί αργότερα. Για παράδειγμα:

@example
xf = x.f
while True:
    print(xf())
@end example

θα συνεχίσει να εκτυπώνει το @code{hello world} μέχρι το τέλος του χρόνου.

Τι ακριβώς συμβαίνει όταν καλείται μια μέθοδος; Ίσως έχετε παρατηρήσει ότι @code{x.f()} κλήθηκε χωρίς όρισμα παραπάνω, παρόλο που ο ορισμός της συνάρτησης για @code{f()} καθόριζε ένα όρισμα. Τι συνέβη με το όρισμα; Σίγουρα η Python δημιουργεί μια εξαίρεση όταν μια συνάρτηση που απαιτεί όρισμα καλείται χωρίς — ακόμα κι αν το όρισμα δεν χρησιμοποιείται στην πραγματικότητα..

Στην πραγματικότητα, μπορεί να έχετε μαντέψει την απάντηση: το ιδιαίτερο με τις μεθόδους είναι ότι το αντικείμενο του στιγμιότυπου μεταβιβάζεται ως το πρώτο όρισμα της συνάρτησης. Στο παράδειγμά μας, η κλήση @code{x.f()} είναι ακριβώς ισοδύναμη με το @code{MyClass.f(x)}. Γενικά, η κλήση μιας μεθόδου με μια λίστα από `n' ορίσματα ισοδυναμεί με την κλήση της αντίστοιχης συνάρτησης με μια λίστα ορισμάτων που δημιουργείται με την εισαγωγή του αντικειμένου στιγμιότυπου της μεθόδου πριν από το πρώτο όρισμα.

Γενικά, οι μέθοδοι λειτουργούν ως εξής. Όταν γίνεται αναφορά σε ένα χαρακτηριστικό μη δεδομένων ενός στιγμιότυπου, γίνεται η αναζήτηση της κλάσης του στιγμιότυπου. Εάν το όνομα υποδηλώνει ένα έγκυρο χαρακτηριστικό κλάσης που είναι αντικείμενο συνάρτησης, οι αναφορές τόσο στο αντικείμενο στιγμιότυπου όσο και στο αντικείμενο συνάρτησης συσκευάζονται σε ένα αντικείμενο μεθόδου. Όταν το αντικείμενο της μεθόδου καλείται με μια λίστα ορισμάτων,δημιουργείται μια νέα λίστα ορισμάτων από το αντικείμενο στιγμιότυπου και τη λίστα ορισμάτων, και το αντικείμενο συνάρτησης καλείται με αυτήν τη νέα λίστα ορισμάτων.

@node Μεταβλητές Κλάσης και Στιγμιότυπου,,Αντικείμενα Μεθόδου,Μια πρώτη ματιά στις Κλάσεις
@anchor{tutorial/classes class-and-instance-variables}@anchor{2289}@anchor{tutorial/classes tut-class-and-instance-variables}@anchor{228a}
@subsubsection Μεταβλητές Κλάσης και Στιγμιότυπου


Σε γενικές γραμμές, οι μεταβλητές στιγμιότυπου προορίζονται για δεδομένα μοναδικά για κάθε στιγμιότυπο και οι μεταβλητές κλάσης είναι για χαρακτηριστικά και μεθόδους που μοιράζονται όλα τα στιγμιότυπα της κλάσης:

@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

As discussed in @ref{227a,,Λίγα λόγια για Ονόματα και Αντικείμενα}, shared data can have possibly surprising
effects involving @ref{21d1,,mutable} objects such as lists and dictionaries.
For example, the `tricks' list in the following code should not be used as a
class variable because just a single list would be shared by all `Dog'
instances:

@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

Ο σωστός σχεδιασμός της κλάσης θα πρέπει να χρησιμοποιεί μια μεταβλητή στιγμιότυπου αντί:

@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 Τυχαίες Παρατηρήσεις,Κληρονομικότητα,Μια πρώτη ματιά στις Κλάσεις,Κλάσεις
@anchor{tutorial/classes random-remarks}@anchor{228b}@anchor{tutorial/classes tut-remarks}@anchor{228c}
@subsection Τυχαίες Παρατηρήσεις


@c These should perhaps be placed more carefully...

Αν το ίδιο όνομα χαρακτηριστικού εμφανίζεται και σε ένα στιγμιότυπο και σε μια κλάση, τότε η αναζήτηση χαρακτηριστικών δίνει προτεραιότητα στο στιγμιότυπο:

@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

Τα χαρακτηριστικά δεδομένων μπορούν να αναφέρονται με μεθόδους καθώς και από απλούς χρήστες («πελάτες») ενός αντικειμένου. Με άλλα λόγια, οι κλάσεις δεν μπορούν να χρησιμοποιηθούν για την υλοποίηση καθαρών αφηρημένων τύπων δεδομένων. Στην πραγματικότητα, τίποτα στην Python δεν καθιστά δυνατή την επιβολή της απόκρυψης δεδομένων — όλα βασίζονται σε σύμβαση. (από την άλλη πλευρά, η εφαρμογή Python, γραμμένη σε C, μπορεί να αποκρύψει εντελώς τις λεπτομέρειες υλοποίησης και να ελέγξει την πρόσβαση σε ένα αντικείμενο εάν είναι απαραίτητο αυτό μπορεί να χρησιμοποιηθεί από επεκτάσεις στην Python γραμμένες σε C.)

Οι χρήστες θα πρέπει να χρησιμοποιούν τα χαρακτηριστικά δεδομένων με προσοχή — οι χρήστες ενδέχεται να μπερδέψουν τα αμετάβλητα που διατηρούνται από τις μεθόδους σφραγίζοντας τα χαρακτηριστικά των δεδομένων τους. Λάβετε υπόψη ότι οι χρήστες μπορούν να προσθέσουν δικά τους χαρακτηριστικά δεδομένων σε ένα αντικείμενο στιγμιότυπου χωρίς να επηρεάσουν την εγκυρότητα των μεθόδων, εφόσον αποφεύγονται οι συγκρούσεις ονομάτων — και πάλι, μια σύμβαση ονομασίας μπορεί να σώσει πολλούς πονοκεφάλους εδώ.

Δεν υπάρχει συντομογραφία για την αναφορά χαρακτηριστικών δεδομένων (ή άλλων μεθόδων!) μέσα από τις μεθόδους. Διαπιστώνω ότι αυτό στην πραγματικότητα αυξάνει  την αναγνωσιμότητα των μεθόδων: δεν υπάρχει καμία πιθανότητα σύγχυσης τοπικών μεταβλητών και των μεταβλητών παραδείγματος όταν εξετάζουμε μια μέθοδο.

Συχνά, το πρώτο όρισμα μιας μεθόδου ονομάζεται @cite{self}. Αυτό δεν είναι τίποτα περισσότερο από μια σύμβαση: το όνομα @cite{self} δεν έχει καμία απολύτως ιδιαίτερη σημασία για την Python. Σημειώστε, ωστόσο, ότι αν δεν ακολουθήσετε τη σύμβαση ο κώδικάς σας μπορεί να είναι λιγότερο ευανάγνωστος σε άλλους προγραμματιστές Python, και είναι επίσης κατανοητό ότι μπορεί να γραφτεί ένα πρόγραμμα `class browser' που να βασίζεται σε μια τέτοια σύμβαση.

Κάθε αντικείμενο συνάρτησης που είναι χαρακτηριστικό κλάσης ορίζει μια μέθοδο για στιγμιότυπα αυτής της κλάσης. Δεν είναι απαραίτητο ο ορισμός της συνάρτησης να περικλείεται με κείμενο στον ορισμό της κλάσης: η αντιστοίχηση ενός αντικειμένου συνάρτησης σε μια τοπική μεταβλητή της κλάσης είναι επίσης εντάξει. Για παράδειγμα:

@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

Τώρα τα @code{f}, @code{g} και @code{h} είναι όλα χαρακτηριστικά της κλάσης @code{C} που αναφέρονται σε αντικείμενα συνάρτησης, και κατά συνέπεια είναι όλες μέθοδοι στιγμιοτύπων του @code{C} — Το @code{h} είναι ακριβώς ισοδύναμο με το @code{g}. Σημειώστε ότι αυτή η πρακτική συνήθως χρησιμεύει μόνο για να μπερδέψει τον αναγνώστη ενός προγράμματος.

Οι μέθοδοι μπορούν να καλούν άλλες μεθόδους χρησιμοποιώντας χαρακτηριστικά μεθόδου του 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

Οι μέθοδοι μπορεί να αναφέρονται σε καθολικά ονόματα με τον ίδιο τρόπο όπως οι συνηθισμένες συναρτήσεις.Η καθολική εμβέλεια που σχετίζεται με μια μέθοδο είναι το module που περιέχει τον ορισμό της. (Μια κλάση δεν χρησιμοποιείται ποτέ ως καθολική εμβέλεια.) Αν και σπάνια συναντά κανείς έναν καλό λόγο για τη χρήση καθολικών δεδομένων σε μια μέθοδο, υπάρχουν πολλές Νόμιμες χρήσεις της καθολικής εμβέλειας: για ένα πράγμα, οι λειτουργίες και οι λειτουργικές μονάδες που εισάγονται στην καθολική εμβέλεια μπορούν να χρησιμοποιηθούν από μεθόδους, καθώς και συναρτήσεις και κλάσεις που ορίζονται σε αυτό. Συνήθως, η κλάση που περιέχει τη μέθοδο ορίζεται από μόνη της σε αυτή την καθολική εμβέλεια, και στην επόμενη ενότητα θα βρούμε μερικούς καλούς λόγους για τους οποίους μια μέθοδος θα ήθελε να αναφέρει τη δική της κλάση.

Κάθε τιμή είναι ένα αντικείμενο και επομένως έχει μια `κλάση' (ονομάζεται επίσης `τύπος' της). Αποθηκεύεται ως @code{object.__class__}.

@node Κληρονομικότητα,Ιδιωτικές Μεταβλητές,Τυχαίες Παρατηρήσεις,Κλάσεις
@anchor{tutorial/classes inheritance}@anchor{228d}@anchor{tutorial/classes tut-inheritance}@anchor{228e}
@subsection Κληρονομικότητα


Φυσικά, ένα χαρακτηριστικό γλώσσας δεν θα ήταν αντάξιο του ονόματος «class» χωρίς την υποστήριξη της κληρονομικότητας. Η σύνταξη για έναν παραγόμενο ορισμό κλάσης μοιάζει με αυτό:

@example
class DerivedClassName(BaseClassName):
    <statement-1>
    .
    .
    .
    <statement-N>
@end example

Το όνομα @code{BaseClassName} πρέπει να οριστεί σε έναν χώρο ονομάτων προσβάσιμο από το πεδίο που περιέχει τον παραγόμενο ορισμό κλάσης. Στη θέση ενός ονόματος βασικής κλάσης, επιτρέπονται και άλλες αυθαίρετες εκφράσεις. Αυτό μπορεί να είναι χρήσιμο, για παράδειγμα, όταν η βασική κλάση ορίζεται σε άλλη module:

@example
class DerivedClassName(modname.BaseClassName):
@end example

Η εκτέλεση ενός παραγόμενου ορισμού κλάσης προχωρά το ίδιο όπως για μια βασική κλάση. Όταν το αντικείμενο της κλάσης κατασκευάζεται, η βασική κλάση απομνημονεύεται.Αυτό χρησιμοποιείται για την επίλυση αναφορών χαρακτηριστικών: εάν ένα ζητούμενο χαρακτηριστικό δεν βρεθεί στην κλάση, η αναζήτηση προχωρά στην αναζήτηση στη βασική κλάση. Αυτός ο κανόνας εφαρμόζεται αναδρομικά εάν η ίδια η βασική κλάση προέρχεται από κάποια άλλη κλάση.

Δεν υπάρχει τίποτα το ιδιαίτερο σχετικά με την δημιουργία στιγμιότυπου παραγόμενων κλάσεων: @code{DerivedClassName()} δημιουργεί ένα νέο στιγμιότυπο της κλάσης. Οι αναφορές μεθόδων επιλύονται ως εξής: γίνεται αναζήτηση του αντίστοιχου χαρακτηριστικού κλάσης, κατεβαίνοντας προς τα κάτω στην αλυσίδα των βασικών κλάσεων εάν είναι απαραίτητο, και η αναφορά της μεθόδου είναι έγκυρη εάν αυτό αποδίδει ένα αντικείμενο συνάρτησης.

Οι παράγωγες κλάσεις ενδέχεται να παρακάμπτουν τις μεθόδους των βασικών τους κλάσεων. Επειδή οι μέθοδοι δεν έχουν ειδικά προνόμια όταν καλούν άλλες μεθόδους του ίδιου αντικειμένου, μια μέθοδος μιας βασικής κλάσης που καλεί μια άλλη μέθοδο που ορίζεται στην ίδια βασική κλάση μπορεί να καταλήξει να καλεί μια μέθοδο μιας παραγόμενης κλάσης που την αντικαθιστά.(Για προγραμματιστές C++: όλες οι μέθοδοι στην Python είναι ουσιαστικά «εικονικές».)

Μια υπερισχύουσα μέθοδος σε μια παραγόμενη κλάση μπορεί στην πραγματικότητα να θέλει να επεκτείνει αντί να αντικαταστήσει απλώς τη μέθοδο βασικής κλάσης με το ίδιο όνομα. Υπάρχει ένας απλός τρόπος για να καλέσετε τη μέθοδο βασικής κλάσης απευθείας: απλώς καλέστε το @code{BaseClassName.methodname(self, arguments)}. Αυτό είναι περιστασιακά χρήσιμο στους χρήστες (Λάβετε υπόψη ότι αυτό λειτουργεί μόνο εάν η βασική κλάση είναι προσβάσιμη ως @code{BaseClassName} στην καθολική εμβέλεια.)

Η Python έχει δύο (ενσωματωμένες) built-in συναρτήσεις που λειτουργούν με κληρονομικότητα:


@itemize *

@item 
Χρησιμοποιήστε το @ref{2ef,,isinstance()} για να ελέγξετε τον τύπο ενός στιγμιότυπου: το @code{isinstance(obj, int)} θα είναι @code{True} μόνο εάν το @code{obj.__class__} είναι @ref{326,,int} ή προέρχεται από κάποια κλάση από @code{int}.

@item 
Χρησιμοποιήστε το @ref{2f0,,issubclass()} για να ελέγξετε την κληρονομικότητα κλάσης: Το @code{issubclass(bool, int)} είναι @code{True} αφού το @ref{5ef,,bool} είναι υποκλάση του @ref{326,,int}. Ωστόσο, το @code{issubclass(float, int)} είναι @code{False} αφού το @ref{327,,float} δεν είναι υποκλάση του @code{int}.
@end itemize

@menu
* Πολλαπλή Κληρονομικότητα:: 

@end menu

@node Πολλαπλή Κληρονομικότητα,,,Κληρονομικότητα
@anchor{tutorial/classes multiple-inheritance}@anchor{228f}@anchor{tutorial/classes tut-multiple}@anchor{2290}
@subsubsection Πολλαπλή Κληρονομικότητα


Η Python υποστηρίζει επίσης μια μορφή πολλαπλής κληρονομικότητας. Ένας ορισμός κλάσης με πολλαπλές βασικές κλάσεις μοιάζει με αυτό:

@example
class DerivedClassName(Base1, Base2, Base3):
    <statement-1>
    .
    .
    .
    <statement-N>
@end example

Για τους περισσότερους σκοπούς, στις πιο απλές περιπτώσεις, μπορείτε να σκεφτείτε την αναζήτηση χαρακτηριστικών που κληρονομήθηκαν από μια γονική κλάση ως depth-first, από αριστερά προς τα δεξιά, χωρίς αναζήτηση δύο φορές στην ίδια κλάση όπου υπάρχει επικάλυψη στην ιεραρχία. Έτσι, εάν δεν βρεθεί ένα χαρακτηριστικό στο @code{DerivedClassName}, αναζητείται στο @code{Base1} και μετά (αναδρομικά) στις βασικές κλάσεις του @code{Base1}, και αν δεν βρέθηκε εκεί,αναζητήθηκε στο @code{Base2}, και ούτω καθεξής.

Στην πραγματικότητα, είναι λίγο πιο περίπλοκο από αυτό. Η σειρά ανάλυσης της μεθόδου αλλάζει δυναμικά για να υποστηρίξει συνεργατικές κλήσεις σε @ref{443,,super()}. Αυτή η προσέγγιση είναι γνωστή σε ορισμένες άλλες γλώσσες πολλαπλής κληρονομικότητας ως call-next-method και είναι πιο ισχυρή από τη σούπερ κλήση που βρίσκεται σε γλώσσες μεμονωμένης κληρονομικότητας.

Η δυναμική σειρά είναι απαραίτητη επειδή όλες οι περιπτώσεις πολλαπλής κληρονομικότητας εμφανίζουν μία ή περισσότερες σχέσεις διαμαντιών (όπου τουλάχιστον μια από τις γονικές κλάσεις μπορεί να προσπελαστεί μέσω πολλαπλών διαδρομών από την κατώτατη κλάση). Για παράδειγμα, όλες οι κλάσεις κληρονομούν από @ref{e4d,,object}, επομένως κάθε περίπτωση πολλαπλής κληρονομικότητας παρέχει περισσότερες από μία διαδρομές για να φτάσετε στο @code{object}. Για να μην υπάρχει πρόσβαση στις βασικές κλάσεις περισσότερες από μία φορές, ο δυναμικός αλγόριθμος γραμμικοποιεί τη σειρά αναζήτησης με τρόπο που διατηρεί τη σειρά από αριστερά προς τα δεξιά-που καθορίζεται σε κάθε κλάση, που καλεί κάθε γονέα μόνο μία φορά, και που είναι μονότονος (που σημαίνει ότι μια κλάση μπορεί να γίνει υπό-κλάση χωρίς να επηρεαστεί η σειρά προτεραιότητας των γονέων της). Συνολικά, αυτές οι ιδιότητες καθιστούν δυνατό τον σχεδιασμό αξιόπιστων και επεκτάσιμων κλάσεων με πολλαπλή κληρονομικότητα. Για περισσότερες λεπτομέρειες, δείτε @ref{184c,,The Python 2.3 Method Resolution Order}.

In some cases multiple inheritance is not allowed; see @ref{2291,,Multiple inheritance}
for details.

@node Ιδιωτικές Μεταβλητές,Μικροπράγματα,Κληρονομικότητα,Κλάσεις
@anchor{tutorial/classes private-variables}@anchor{2292}@anchor{tutorial/classes tut-private}@anchor{2278}
@subsection Ιδιωτικές Μεταβλητές


Οι μεταβλητές στιγμιοτύπου «Private» στις οποίες δεν είναι δυνατή η πρόσβαση εκτός από το εσωτερικό ενός αντικειμένου,δεν υπάρχουν στην Python. Ωστόσο, υπάρχει μια σύμβαση που ακολουθείται από τον περισσότερο Python κώδικα: ένα όνομα με πρόθεμα κάτω παύλα (π.χ. @code{_spam}) θα πρέπει να αντιμετωπίζεται ως μη δημόσιο μέρος του API (είτε πρόκειται για συνάρτηση,μέθοδο ή μέλος δεδομένων). Θα πρέπει να θεωρείται ως λεπτομέρεια υλοποίησης και υπόκειται σε αλλαγές χωρίς προειδοποίηση.

@geindex όνομα;συντριβή

Δεδομένου ότι υπάρχει μια έγκυρη περίπτωση χρήσης για ιδιωτικά μέλη της κλάσης (δηλαδή για να αποφευχθούν συγκρούσεις ονομάτων με ονόματα που ορίζονται από υποκλάσεις), υπάρχει περιορισμένη υποστήριξη για έναν τέτοιο μηχανισμό, που ονομάζεται `name mangling'. Οποιοδήποτε αναγνωριστικό της φόρμας @code{__spam} (τουλάχιστον δύο προπορευόμενες κάτω παύλες, το πολύ μια στη συνέχεια κάτω παύλα) αντικαθίσταται με κείμενο με το @code{_classname__spam}, όπου το @code{classname} είναι το όνομα της τρέχουσας τάξης με την πρώτη υπογράμμιση stripped. Αυτό το mangling γίνεται χωρίς να λαμβάνεται υπόψη η συντακτική θέση του του αναγνωριστικού, αρκεί να εμφανίζεται εντός του ορισμού μιας κλάσης.


@subsubheading Δείτε επίσης


Οι @ref{2293,,προδιαγραφές παραποίησης ιδιωτικού ονόματος} για λεπτομέρειες και ειδικές περιπτώσεις.


Η παραβίαση ονομάτων είναι χρήσιμη για να επιτρέπεται στις υποκλάσεις να παρακάμπτουν μεθόδους χωρίς να διακόπτουν τις κλήσεις μεθόδων ενδοκλάσεων. Για παράδειγμα:

@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

Το παραπάνω παράδειγμα θα λειτουργούσε ακόμα και αν το @code{MappingSubclass} εισήγαγε ένα αναγνωριστικό @code{__update} αφού αντικαταστάθηκε με το @code{_Mapping__update} στην κλάση @code{Mapping} και με το @code{_MappingSubclass__update} στη κλάση @code{MappingSubclass} αντίστοιχα.

Λάβετε υπόψη ότι οι κανόνες παραβίασης έχουν σχεδιαστεί κυρίως για την αποφυγή ατυχημάτων.Εξακολουθεί να είναι δυνατή η πρόσβαση ή η τροποποίηση μιας μεταβλητής που θεωρείται ιδιωτική. Αυτό μπορεί να είναι χρήσιμο ακόμη και σε ειδικές περιπτώσεις, όπως στο πρόγραμμα εντοπισμού σφαλμάτων(debugger).

Σημειώστε ότι ο κώδικας που μεταβιβάστηκε στο @code{exec()} ή στο @code{eval()} δεν θεωρεί ότι το το όνομα κλάσης της κλάσης επίκλησης να είναι η τρέχουσα κλάση. Αυτό είναι παρόμοιο με το αποτέλεσμα της @code{καθολικής} δήλωσης , το αποτέλεσμα της οποίας επίσης περιορίζεται στον κώδικα που έχει μεταγλωττιστεί μαζί(byte-compiled). Ο ίδιος περιορισμός ισχύει για τα @code{getattr()}, @code{setattr()} και @code{delattr()}, καθώς και όταν γίνεται αναφορά απευθείας στο @code{__dict__}.

@node Μικροπράγματα,Επαναλήπτες,Ιδιωτικές Μεταβλητές,Κλάσεις
@anchor{tutorial/classes odds-and-ends}@anchor{2294}@anchor{tutorial/classes tut-odds}@anchor{2295}
@subsection Μικροπράγματα


Μερικές φορές είναι χρήσιμο να έχετε έναν τύπο δεδομένων παρόμοιο με τον Pascal «record» ή C «struct», ομαδοποιώντας μερικά επώνυμα στοιχεία δεδομένων. Η ιδιωματική προσέγγιση είναι η χρήση @ref{32,,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

Ένα κομμάτι κώδικα Python που αναμένει έναν συγκεκριμένο αφηρημένο τύπο δεδομένων μπορεί συχνά να περάσει σε μια κλάση που μιμείται τις μεθόδους αυτού του τύπου δεδομένων. Για παράδειγμα, εάν έχετε μια συνάρτηση που μορφοποιεί ορισμένα δεδομένα από ένα αντικείμενο αρχείου, μπορείτε να ορίσετε μια κλάση με μεθόδους @ref{225b,,read()} και @ref{2296,,readline()} που λαμβάνουν τα δεδομένα από ένα buffer συμβολοσειρών αντ” αυτού, και περάστε το ως όρισμα.

@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.)

@ref{2297,,Instance method objects} έχουν επίσης χαρακτηριστικά: @ref{176b,,m.__self__} είναι το αντικείμενο παρουσίας με τη μέθοδο @code{m()}, και @ref{16a1,,m.__func__} είναι το @ref{79b,,αντικείμενο συνάρτησης} που αντιστοιχεί στη μέθοδο.

@node Επαναλήπτες,Γεννήτορες Generators,Μικροπράγματα,Κλάσεις
@anchor{tutorial/classes iterators}@anchor{2298}@anchor{tutorial/classes tut-iterators}@anchor{2299}
@subsection Επαναλήπτες


Μέχρι τώρα πιθανότατα έχετε παρατηρήσει ότι τα περισσότερα αντικείμενα container μπορούν να επαναληφθούν χρησιμοποιώντας μια δήλωση @ref{321,,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

Αυτό το στυλ πρόσβασης είναι σαφές, συνοπτικό και βολικό. Η χρήση των Iterators διαπερνά και ενοποιεί την Python. Στο παρασκήνιο, η δήλωση @ref{321,,for} καλεί @ref{bb4,,iter()} στο αντικείμενο container. Η συνάρτηση επιστρέφει ένα αντικείμενο iterator που ορίζει τη μέθοδο @ref{1672,,__next__()} η οποία έχει πρόσβαση σε στοιχεία στο container ένα κάθε φορά. Όταν δεν υπάρχουν άλλα στοιχεία, το @code{__next__()} δημιουργεί μια @ref{fba,,StopIteration} εξαίρεση που λέει τον βρόχο @code{for} να τερματιστεί. Μπορείτε να καλέσετε τη μέθοδο @code{__next__()} χρησιμοποιώντας την ενσωματωμένη συνάρτηση @ref{bb5,,next()}. Αυτό το παράδειγμα δείχνει πώς λειτουργούν όλα:

@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

Έχοντας δει τους μηχανισμούς πίσω από το πρωτόκολλο iterator, είναι εύκολο να προσθέσετε συμπεριφορά iterator στις κλάσεις σας. Ορίστε μια μέθοδο @ref{229a,,__iter__()} που επιστρέφει ένα αντικείμενο με μια μέθοδο @ref{1672,,__next__()}. Εάν η κλάση ορίζει @code{__next__()}, τότε το @code{__iter__()} μπορεί απλώς να επιστρέψει @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 Γεννήτορες Generators,Εκφράσεις Γεννήτορων,Επαναλήπτες,Κλάσεις
@anchor{tutorial/classes generators}@anchor{229b}@anchor{tutorial/classes tut-generators}@anchor{229c}
@subsection Γεννήτορες (Generators)


@ref{1409,,Generators} είναι ένα απλό και ισχυρό εργαλείο για τη δημιουργία iterators. Είναι γραμμένες σαν κανονικές συναρτήσεις αλλά χρησιμοποιούν τη @ref{d93,,yield} όποτε θέλουν να επιστρέψουν δεδομένα. Κάθε φορά που καλείται @ref{bb5,,next()} σε αυτό, ο generator συνεχίζει από εκεί που σταμάτησε (θυμάται όλες τις τιμές δεδομένων και ποια δήλωση εκτελέστηκε τελευταία). Ένα παράδειγμα δείχνει ότι οι generators μπορεί να είναι ασήμαντα εύκολο να δημιουργηθούν:

@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

Οτιδήποτε μπορεί να γίνει με generators μπορεί να γίνει και με iterators που βασίζονται σε κλάσεις, όπως περιγράφεται στην προηγούμενη ενότητα. Αυτό που κάνει τους generators τόσο συμπαγείς είναι ότι οι μέθοδοι @ref{229d,,__iter__()} και @ref{229e,,__next__()} δημιουργούνται αυτόματα.

Ένα άλλο βασικό χαρακτηριστικό είναι ότι οι τοπικές μεταβλητές και η κατάσταση εκτέλεσης αποθηκεύονται αυτόματα μεταξύ των κλήσεων. Αυτό έκανε τη συνάρτηση πιο εύκολη στην γραφή και πολύ πιο ξεκάθαρη από μια προσέγγιση που χρησιμοποιεί μεταβλητές παράδειγμα όπως @code{self.index} και @code{self.data}.

Εκτός από την αυτόματη δημιουργία μεθόδου και την αποθήκευση της κατάστασης του προγράμματος, όταν οι generators τερματίζονται, εγείρουν αυτόματα την εξαίρεση @ref{fba,,StopIteration}. Σε συνδυασμό, αυτά τα χαρακτηριστικά καθιστούν εύκολη τη δημιουργία επαναλήψεων χωρίς περισσότερη προσπάθεια από τη σύνταξη μιας κανονικής συνάρτησης.

@node Εκφράσεις Γεννήτορων,,Γεννήτορες Generators,Κλάσεις
@anchor{tutorial/classes generator-expressions}@anchor{229f}@anchor{tutorial/classes tut-genexps}@anchor{22a0}
@subsection Εκφράσεις Γεννήτορων


Ορισμένοι απλοί generators μπορούν να κωδικοποιηθούν συνοπτικά ως εκφράσεις χρησιμοποιώντας μια σύνταξη παρόμοια με τις list comprehensions, αλλά με παρενθέσεις αντί για αγκύλες. Αυτές οι εκφράσεις έχουν σχεδιαστεί για καταστάσεις όπου ο generator χρησιμοποιείται αμέσως από μια περικλείουσα συνάρτηση. Οι εκφράσεις generator είναι πιο συμπαγείς αλλά λιγότερο ευέλικτες από τους ορισμούς πλήρους generator και τείνουν να είναι περισσότερο φιλικό προς τη μνήμη από αντίστοιχα list comprehensions.

Παραδείγματα:

@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']

>>> x = [[1,2,3], [], [4, 5]]
>>> g = (*i for i in x)
>>> list(g)
[1, 2, 3, 4, 5]
@end example

In most cases, generator expressions must be wrapped in parentheses.  As a
special case, however, when provided as the sole argument to a function (as in
the examples involving @code{sum}, @code{set}, @code{max}, and @code{list} above), the
generator expression does not need to be wrapped in an additional set of
parentheses.  That is to say, the following two pieces of code are semantically
equivalent:

@example
>>> f(x for x in y)
>>> f((x for x in y))
@end example

as are the following:

@example
>>> f(*x for x in y)
>>> f((*x for x in y))
@end example

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Brief tour of the standard library,Brief tour of the standard library — part II,Κλάσεις,Οδηγός εκμάθησης Python
@anchor{tutorial/stdlib doc}@anchor{22a1}@anchor{tutorial/stdlib brief-tour-of-the-standard-library}@anchor{22a2}@anchor{tutorial/stdlib translation-repo}@anchor{22a3}@anchor{tutorial/stdlib tut-brieftour}@anchor{22a4}
@section Brief tour of the standard library


@menu
* Operating system interface:: 
* File wildcards:: 
* Command-line arguments:: 
* Error output redirection and program termination:: 
* String pattern matching:: 
* Μαθηματικά:: 
* Internet access:: 
* Dates and times:: 
* Data compression:: 
* Performance measurement:: 
* Quality control:: 
* Batteries included:: 

@end menu

@node Operating system interface,File wildcards,,Brief tour of the standard library
@anchor{tutorial/stdlib operating-system-interface}@anchor{22a5}@anchor{tutorial/stdlib tut-os-interface}@anchor{22a6}
@subsection Operating system interface


Το module @ref{a5,,os} παρέχει δεκάδες λειτουργίες για αλληλεπίδραση με το λειτουργικό σύστημα:

@example
>>> import os
>>> os.getcwd()      # Return the current working directory
'C:\\Python316'
>>> os.chdir('/server/accesslogs')   # Change current working directory
>>> os.system('mkdir today')   # Run the command mkdir in the system shell
0
@end example

Βεβαιωθείτε ότι χρησιμοποιείτε το στυλ @code{import os} αντί για το @code{from os import *}.  Αυτό θα κρατήσει το @ref{114b,,os.open()} υπό τη σκίαση της ενσωματωμένης συνάρτησης @ref{32b,,open()} που λειτουργεί πολύ διαφορετικά.

@geindex ενσωματωμένες συναρτήσεις;βοήθεια

Οι ενσωματωμένες συναρτήσεις @ref{a23,,dir()} και @ref{ca9,,help()} είναι χρήσιμες ως διαδραστικά βοηθήματα για εργασία με μεγάλα modules όπως @ref{a5,,os}:

@example
>>> import os
>>> dir(os)
<επιστρέφει μια λίστα από όλες τις συναρτήσεις module>
>>> help(os)
<επιστρέφει μια εκτενή σελίδα εγχειριδίου που δημιουργήθηκε από τα docstrings του module>
@end example

Για καθημερινές διαχειριστικές εργασίες σε αρχεία και καταλόγους, το module @ref{cd,,shutil} παρέχει μια διεπαφή υψηλότερου επιπέδου που είναι πιο εύκολη στην χρήση:

@example
>>> import shutil
>>> shutil.copyfile('data.db', 'archive.db')
'archive.db'
>>> shutil.move('/build/executables', 'installdir')
'installdir'
@end example

@node File wildcards,Command-line arguments,Operating system interface,Brief tour of the standard library
@anchor{tutorial/stdlib file-wildcards}@anchor{22a7}@anchor{tutorial/stdlib tut-file-wildcards}@anchor{22a8}
@subsection File wildcards


Το module @ref{67,,glob} παρέχει μια λειτουργία για τη δημιουργία λιστών αρχείων από αναζητήσεις με χαρακτήρες μπαλαντέρ καταλόγου:

@example
>>> import glob
>>> glob.glob('*.py')
['primes.py', 'random.py', 'quote.py']
@end example

@node Command-line arguments,Error output redirection and program termination,File wildcards,Brief tour of the standard library
@anchor{tutorial/stdlib command-line-arguments}@anchor{22a9}@anchor{tutorial/stdlib tut-command-line-arguments}@anchor{22aa}
@subsection Command-line arguments


Τα κοινά scripts βοηθητικών προγραμμάτων συχνά χρειάζονται να επεξεργάζονται ορίσματα γραμμής εντολών. Αυτά τα ορίσματα αποθηκεύονται στο χαρακτηριστικό `argv' του module @ref{e2,,sys} ως λίστα.  Για παράδειγμα, ας πάρουμε το ακόλουθο αρχείο @code{demo.py}:

@example
# File demo.py
import sys
print(sys.argv)
@end example

Εδώ είναι το αποτέλεσμα από την εκτέλεση του @code{python demo.py one two three} στη γραμμή εντολών:

@example
['demo.py', 'one', 'two', 'three']
@end example

Το module @ref{7,,argparse} παρέχει έναν πιο εξελιγμένο μηχανισμό για την επεξεργασία ορισμάτων γραμμής εντολών.  Το ακόλουθο script εξάγει ένα ή περισσότερα ονόματα αρχείων και έναν προαιρετικό αριθμό γραμμών που θα εμφανιστούν:

@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

Όταν εκτελείται στη γραμμή εντολών το @code{python top.py --lines=5 alpha.txt beta.txt}, το script ορίζει το @code{args.lines} σε @code{5} και το  @code{args.filenames} σε @code{['alpha.txt', 'beta.txt']}.

@node Error output redirection and program termination,String pattern matching,Command-line arguments,Brief tour of the standard library
@anchor{tutorial/stdlib error-output-redirection-and-program-termination}@anchor{22ab}@anchor{tutorial/stdlib tut-stderr}@anchor{22ac}
@subsection Error output redirection and program termination


Το module @ref{e2,,sys} έχει επίσης χαρακτηριστικά για `stdin', `stdout', και `stderr'. Το τελευταίο είναι χρήσιμο για την εκπομπή προειδοποιήσεων και μηνυμάτων σφαλμάτων ώστε να είναι ορατά ακόμα και όταν το `stdout' έχει ανακατευθυνθεί:

@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

Ο πιο άμεσος τρόπος για να τερματίσετε ένα script είναι να χρησιμοποιήσετε το @code{sys.exit()}.

@node String pattern matching,Μαθηματικά,Error output redirection and program termination,Brief tour of the standard library
@anchor{tutorial/stdlib string-pattern-matching}@anchor{22ad}@anchor{tutorial/stdlib tut-string-pattern-matching}@anchor{22ae}
@subsection String pattern matching


Το module @ref{c1,,re} παρέχει εργαλεία κανονική έκφρασης για προηγμένη επεξεργασία συμβολοσειρών. Για πολύπλοκη αντιστοίχιση και χειρισμό, οι τυπικές εκφράσεις προσφέρουν συνοπτικές, βελτιστοποιημένες λύσεις:

@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

Όταν χρειάζονται μόνο απλές δυνατότητες, προτιμώνται οι μέθοδοι συμβολοσειρών, επειδή είναι ευκολότερες στην ανάγνωση και τον εντοπισμό σφαλμάτων:

@example
>>> 'tea for too'.replace('too', 'two')
'tea for two'
@end example

@node Μαθηματικά,Internet access,String pattern matching,Brief tour of the standard library
@anchor{tutorial/stdlib mathematics}@anchor{22af}@anchor{tutorial/stdlib tut-mathematics}@anchor{22b0}
@subsection Μαθηματικά


Το module @ref{91,,math} δίνει πρόσβαση στις υποκείμενες συναρτήσεις της βιβλιοθήκης C για μαθηματικά κινητής υποδιαστολής:

@example
>>> import math
>>> math.cos(math.pi / 4)
0.70710678118654757
>>> math.log(1024, 2)
10.0
@end example

Το module @ref{c0,,random} παρέχει εργαλεία για να κάνουμε τυχαίες επιλογές:

@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

Το module @ref{da,,statistics} υπολογίζει βασικές στατιστικές ιδιότητες (μέσος όρος, διάμεσος, διακύμανση, κ.λπ.) αριθμητικών δεδομένων:

@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

Το έργο SciPy <@indicateurl{https://scipy.org}> έχει πολλές άλλες ενότητες για αριθμητικούς υπολογισμούς.

@node Internet access,Dates and times,Μαθηματικά,Brief tour of the standard library
@anchor{tutorial/stdlib internet-access}@anchor{22b1}@anchor{tutorial/stdlib tut-internet-access}@anchor{22b2}
@subsection Internet access


Υπάρχει ένας αριθμός modules για πρόσβαση στο διαδίκτυο και επεξεργασία πρωτοκόλλων διαδικτύου. Δύο από τα πιο απλά είναι το @ref{114,,urllib.request} για να την ανάκτηση δεδομένων από διευθύνσεις URL και το @ref{d2,,smtplib} για την αποστολή αλληλογραφίας:

@example
>>> from urllib.request import urlopen
>>> with urlopen('https://docs.python.org/3/') as response:
...     for line in response:
...         line = line.decode()             # Convert bytes to a str
...         if 'updated' in line:
...             print(line.rstrip())         # Remove trailing newline
...
      Last updated on Nov 11, 2025 (20:11 UTC).

>>> 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

(Σημειώστε ότι το δεύτερο παράδειγμα χρειάζεται διακομιστή αλληλογραφίας που εκτελείται σε localhost.)

@node Dates and times,Data compression,Internet access,Brief tour of the standard library
@anchor{tutorial/stdlib dates-and-times}@anchor{22b3}@anchor{tutorial/stdlib tut-dates-and-times}@anchor{22b4}
@subsection Dates and times


Το module @ref{33,,datetime} παρέχει κλάσεις για χειρισμό ημερομηνιών και ωρών με απλούς και σύνθετους τρόπους. Ενώ υποστηρίζεται η αριθμητική ημερομηνία και ώρα, η υλοποίηση εστιάζεται στην αποτελεσματική εξαγωγή μελών για μορφοποίηση και χειρισμό εξόδου.  Το module επίσης υποστηρίζει αντικείμενα που έχουν επίγνωση ζώνης ώρας.

@example
>>> # dates are easily constructed and formatted
>>> import datetime as dt
>>> now = dt.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 = dt.date(1964, 7, 31)
>>> age = now - birthday
>>> age.days
14368
@end example

@node Data compression,Performance measurement,Dates and times,Brief tour of the standard library
@anchor{tutorial/stdlib data-compression}@anchor{22b5}@anchor{tutorial/stdlib tut-data-compression}@anchor{22b6}
@subsection Data compression


Οι συνήθεις μορφές αρχειοθέτησης και συμπίεσης δεδομένων υποστηρίζονται άμεσα από modules όπως: @ref{13c,,zlib}, @ref{6a,,gzip}, @ref{14,,bz2}, @ref{8d,,lzma}, @ref{13a,,zipfile} και @ref{e7,,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 Performance measurement,Quality control,Data compression,Brief tour of the standard library
@anchor{tutorial/stdlib performance-measurement}@anchor{22b7}@anchor{tutorial/stdlib tut-performance-measurement}@anchor{22b8}
@subsection Performance measurement


Ορισμένοι χρήστες Python αναπτύσσουν βαθύ ενδιαφέρον να γνωρίζουν τη σχετική απόδοση διαφορετικών προσεγγίσεων στο ίδιο πρόβλημα. Η Python παρέχει ένα εργαλείο μέτρησης που απαντά σε αυτές τις ερωτήσεις αμέσως.

Για παράδειγμα, μπορεί να είναι δελεαστικό να χρησιμοποιήσετε τη δυνατότητα tuple packing και unpacking αντί της παραδοσιακής προσέγγισης για την εναλλαγή ορισμάτων. Το module @ref{f8,,timeit} δείχνει γρήγορα ένα ταπεινό πλεονέκτημα απόδοσης:

@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

Σε αντίθεση με το λεπτό επίπεδο ευκρίνειας του @ref{f8,,timeit}, τα modules @ref{b4,,profile} και @ref{b8,,pstats} παρέχουν εργαλεία για τον εντοπισμό κρίσιμων χρονικών τμημάτων σε μεγαλύτερα μπλοκ κώδικα.

@node Quality control,Batteries included,Performance measurement,Brief tour of the standard library
@anchor{tutorial/stdlib quality-control}@anchor{22b9}@anchor{tutorial/stdlib tut-quality-control}@anchor{22ba}
@subsection Quality control


Μια καλή προσέγγιση για την ανάπτυξη λογισμικού υψηλής ποιότητας είναι να γράφονται tests για κάθε λειτουργία καθώς αναπτύσσεται και να εκτελούνται συχνά αυτά τα tests κατά τη διαδικασία ανάπτυξης.

Το module @ref{3d,,doctest} παρέχει ένα εργαλείο για τη σάρωση ενός module και την επικύρωση tests που είναι ενσωματωμένες στις συμβολοσειρές εγγράφων ενός προγράμματος.  Η κατασκευή του test είναι τόσο απλή όσο η αποκοπή και επικόλληση μιας τυπικής κλήσης μαζί με τα αποτελέσματα της στη συμβολοσειρά εγγράφων. Αυτό βελτιώνει την τεκμηρίωση παρέχοντας στον χρήστη ένα παράδειγμα και επιτρέπει στην ενότητα doctest να βεβαιωθεί ότι ο κώδικας παραμένει πιστός στην τεκμηρίωση:

@example
def average(values):
    """Υπολογίζει έναν αριθμητικό μέσο για μια λίστα από αριθμούς.

    >>> print(average([20, 30, 70]))
    40.0
    """
    return sum(values) / len(values)

import doctest
doctest.testmod()   # automatically validate the embedded tests
@end example

Το module @ref{10f,,unittest} δεν είναι τόσο εύκολο όσο το module @ref{3d,,doctest}, αλλά επιτρέπει τη διατήρηση ενός πιο ολοκληρωμένου συνόλου tests σε ξεχωριστό αρχείο:

@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 Batteries included,,Quality control,Brief tour of the standard library
@anchor{tutorial/stdlib batteries-included}@anchor{22bb}@anchor{tutorial/stdlib tut-batteries-included}@anchor{22bc}
@subsection Batteries included


Η Python έχει μια φιλοσοφία «συμπεριλαμβάνονται μπαταρίες».  Αυτό φαίνεται καλύτερα μέσα από τις εξελιγμένες και ισχυρές δυνατότητες των μεγαλύτερων πακέτων της. Για παράδειγμα:


@itemize *

@item 
Τα modules @ref{137,,xmlrpc.client} και @ref{138,,xmlrpc.server} καθιστούν την υλοποίηση κλήσεων απομακρυσμένων διαδικασιών σε μια σχεδόν ασήμαντη εργασία.  Παρά τα ονόματα των modules, δεν απαιτείται άμεση γνώση ή χειρισμός της XML.

@item 
Το πακέτο @ref{3e,,email} είναι μια βιβλιοθήκη για τη διαχείριση μηνυμάτων ηλεκτρονικού ταχυδρομείου, συμπεριλαμβανομένων MIME και άλλων μηνυμάτων εγγράφων που βασίζονται σε 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}. Σε αντίθεση με τα @ref{d2,,smtplib} και @ref{b1,,poplib} που στην πραγματικότητα στέλνουν και λαμβάνουν μηνύματα, το πακέτο email έχει ένα πλήρες σύνολο εργαλείων για τη δημιουργία ή την αποκωδικοποίηση πολύπλοκων δομών μηνυμάτων (συμπεριλαμβανομένων των συνημμένων) και για την εφαρμογή κωδικοποίηση και πρωτόκολλο κεφαλίδων στο διαδίκτυο.

@item 
Το πακέτο @ref{85,,json} παρέχει ισχυρή υποστήριξη για την ανάλυση αυτής της δημοφιλούς μορφής ανταλλαγής δεδομένων.  Το module @ref{2c,,csv} υποστηρίζει την άμεση ανάγνωση και εγγραφή αρχείων σε μορφή τιμής διαχωρισμένου με κόμματα, που συνήθως υποστηρίζεται από βάσεις δεδομένων και υπολογιστικά φύλλα.  Η XML επεξεργασία υποστηρίζεται από τα πακέτα @ref{12e,,xml.etree.ElementTree}, @ref{12a,,xml.dom} και @ref{132,,xml.sax}. Μαζί, αυτές οι μονάδες και τα πακέτα απλοποιούν σημαντικά την ανταλλαγή δεδομένων μεταξύ εφαρμογών Python και άλλων εργαλείων.

@item 
Το module @ref{d7,,sqlite3} αποτελεί έναν wrapper για τη βιβλιοθήκη της βάσης δεδομένων SQLite, παρέχοντας μια συνεχής βάση δεδομένων που μπορεί να ενημερωθεί και να προσπελαστεί χρησιμοποιώντας ελαφρώς μη τυπική σύνταξη SQL.

@item 
Η διεθνοποίηση υποστηρίζεται από έναν αριθμό modules, συμπεριλαμβανομένων των @ref{66,,gettext}, @ref{89,,locale}, και το πακέτο @ref{1c,,codecs}.
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Brief tour of the standard library — part II,Εικονικά Περιβάλλοντα και πακέτα,Brief tour of the standard library,Οδηγός εκμάθησης Python
@anchor{tutorial/stdlib2 doc}@anchor{22bd}@anchor{tutorial/stdlib2 brief-tour-of-the-standard-library-part-ii}@anchor{22be}@anchor{tutorial/stdlib2 translation-repo}@anchor{22bf}@anchor{tutorial/stdlib2 tut-brieftourtwo}@anchor{22c0}
@section Brief tour of the standard library — part II


Αυτή η δεύτερη περιήγηση καλύπτει τα πιο προηγμένα modules που υποστηρίζουν επαγγελματικές ανάγκες προγραμματισμού.  Αυτά τα modules σπάνια εμφανίζονται σε μικρά scripts.

@menu
* Output formatting:: 
* Templating:: 
* Working with binary data record layouts:: 
* Multi-threading: Multi-threading<2>. 
* Logging:: 
* Weak references:: 
* Tools for working with lists:: 
* Decimal floating-point arithmetic:: 

@end menu

@node Output formatting,Templating,,Brief tour of the standard library — part II
@anchor{tutorial/stdlib2 output-formatting}@anchor{22c1}@anchor{tutorial/stdlib2 tut-output-formatting}@anchor{22c2}
@subsection Output formatting


Το module @ref{c3,,reprlib} παρέχει μια έκδοση του @ref{45b,,repr()} προσαρμοσμένη για συντομευμένες εμφανίσεις μεγάλων ή βαθιά ένθετων containers:

@example
>>> import reprlib
>>> reprlib.repr(set('supercalifragilisticexpialidocious'))
"@{'a', 'c', 'd', 'e', 'f', 'g', ...@}"
@end example

Το module @ref{b3,,pprint} προσφέρει πιο εξελιγμένο έλεγχο της εκτύπωσης τόσο των ενσωματωμένων (built-in) και των καθορισμένων από τον χρήστη αντικειμένων με τρόπο που είναι ευανάγνωστο από τον διερμηνέα. Όταν το αποτέλεσμα είναι μεγαλύτερο από μία γραμμή, ο «pretty printer» προσθέτει αλλαγές γραμμής και εσοχές για να εμφανιστεί πιο ξεκάθαρα η δομή δεδομένων:

@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

Το module @ref{f5,,textwrap} μορφοποιεί τις παραγράφους του κειμένου ώστε να ταιριάζει σε ένα δεδομένο πλάτος οθόνης:

@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

Το module @ref{89,,locale} έχει πρόσβαση σε μια βάση δεδομένων μορφών δεδομένων συγκεκριμένης κουλτούρας. Το χαρακτηριστικό ομαδοποίησης της συνάρτησης μορφοποίησης της τοπικής ρύθμισης παρέχει έναν άμεσο τρόπο μορφοποίησης αριθμών με διαχωριστικά ομάδων:

@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 Templating,Working with binary data record layouts,Output formatting,Brief tour of the standard library — part II
@anchor{tutorial/stdlib2 templating}@anchor{22c3}@anchor{tutorial/stdlib2 tut-templating}@anchor{22c4}
@subsection Templating


Το module @ref{db,,string} περιλαμβάνει μια ευέλικτη κλάση @ref{a77,,Template} με απλοποιημένη σύνταξη κατάλληλη για επεξεργασία από τελικούς χρήστες.  Αυτό επιτρέπει στους χρήστες να προσαρμόζουν τις εφαρμογές τους χωρίς να χρειάζεται να αλλάξουν την εφαρμογή.

Η μορφή χρησιμοποιεί ονόματα κράτησης θέσης που σχηματίζονται από @code{$} με έγκυρα αναγνωριστικά Python (αλφαριθμητικούς χαρακτήρες και κάτω παύλες).  Περιβάλλοντας το placeholder με αγκύλες επιτρέπει να ακολουθείται από περισσότερα αλφαριθμητικά γράμματα χωρίς ενδιάμεσα κενά.  Γράφοντας @code{$$} δημιουργεί ένα ενιαίο @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

Η μέθοδος @ref{22c5,,substitute()} κάνει raise ένα @ref{7df,,KeyError} όταν ένα placeholder δεν παρέχεται σε ένα λεξικό ή ένα όρισμα λέξης-κλειδιού.  Για εφαρμογές στυλ συγχώνευσης mail, τα δεδομένα που παρέχονται από τον χρήστη ενδέχεται να είναι ελλιπή και η μέθοδος @ref{22c6,,safe_substitute()} μπορεί να είναι πιο κατάλληλη — θα αφήσει αμετάβλητα τα placeholders εάν λείπουν δεδομένα:

@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

Οι υποκατηγορίες προτύπων μπορούν να καθορίσουν έναν προσαρμοσμένο οριοθέτη.  Για παράδειγμα, ένα batch πρόγραμμα μετονομασίας για ένα πρόγραμμα περιήγησης φωτογραφιών μπορεί να επιλέξει να χρησιμοποιεί σύμβολα ποσοστού για placeholders όπως η τρέχουσα ημερομηνία, ο αριθμός ακολουθίας εικόνων ή η μορφή αρχείου:

@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

Μια άλλη εφαρμογή για templating είναι ο διαχωρισμός της λογικής του προγράμματος από τις λεπτομέρειες πολλαπλών μορφών εξόδου.  Αυτό καθιστά δυνατή την αντικατάσταση προσαρμοσμένων προτύπων για αρχεία XML, αναφορές απλού κειμένου και αναφορές ιστού HTML.

@node Working with binary data record layouts,Multi-threading<2>,Templating,Brief tour of the standard library — part II
@anchor{tutorial/stdlib2 tut-binary-formats}@anchor{22c7}@anchor{tutorial/stdlib2 working-with-binary-data-record-layouts}@anchor{22c8}
@subsection Working with binary data record layouts


Το module @ref{de,,struct} παρέχει τις συναρτήσεις @ref{161b,,pack()} και @ref{1a82,,unpack()} για εργασία με μορφές δυαδικών (binary) εγγραφών μεταβλητού μήκους.  Το ακόλουθο παράδειγμα δείχνει πως να κάνετε μια λούπα μέσω των πληροφοριών κεφαλίδας στο ένα αρχείο ZIP χωρίς τη χρήση του module @ref{13a,,zipfile}.  Οι κωδικοί πακέτου @code{"H"} και @code{"I"} αντιπροσωπεύουν αριθμούς χωρίς υπογραφή δύο και τεσσάρων byte αντίστοιχα.  Το @code{"<"} υποδηλώνει ότι είναι τυπικού μεγέθους και σε σειρά byte λίγο endian:

@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 Multi-threading<2>,Logging,Working with binary data record layouts,Brief tour of the standard library — part II
@anchor{tutorial/stdlib2 multi-threading}@anchor{22c9}@anchor{tutorial/stdlib2 tut-multi-threading}@anchor{22ca}
@subsection Multi-threading


Το threading είναι μια τεχνική για την αποσύνδεση εργασιών που είναι διαδοχικά εξαρτώμενες.  Τα νήματα μπορούν να χρησιμοποιηθούν για την βελτίωση της ανταπόκρισης των εφαρμογών που δέχονται είσοδο από τον χρήστη ενώ άλλες εργασίες εκτελούνται στο παρασκήνιο.  Μια σχετική περίπτωση χρήσης εκτελεί I/O παράλληλα με υπολογισμούς στο άλλο νήμα.

Ο ακόλουθος κώδικας δείχνει πως το module υψηλού επιπέδου @ref{f6,,threading} μπορεί να εκτελεί εργασίες στο παρασκήνιο ενώ το κύριο πρόγραμμα συνεχίζει να εκτελείται:

@example
import threading, zipfile

class AsyncZip(threading.Thread):
    def __init__(self, infile, outfile):
        super().__init__()
        self.infile = infile
        self.outfile = outfile

    def run(self):
        with zipfile.ZipFile(self.outfile, 'w', zipfile.ZIP_DEFLATED) as f:
            f.write(self.infile)
        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

Η κύρια πρόκληση των εφαρμογών πολλαπλών νημάτων είναι ο συντονισμός νημάτων που μοιράζονται δεδομένα ή άλλους πόρους.  Για το σκοπό αυτό, το thread module παρέχει έναν αριθμό πρωτόγονων συγχρονισμού, συμπεριλαμβανομένων locks, events, μεταβλητών συνθηκών, και semaphores.

Ενώ αυτά τα εργαλεία είναι ισχυρά, μικρά σφάλματα σχεδιασμού μπορεί να οδηγήσουν σε προβλήματα που είναι δύσκολο να αναπαραχθούν.  Επομένως, η προτιμώμενη προσέγγιση στον συντονισμό εργασιών είναι να συγκεντρωθεί όλη η πρόσβαση σε έναν πόρο σε ένα μόνο νήμα και στη συνέχεια να χρησιμοποιηθεί το module @ref{be,,queue}, για τροφοδοτήσει αυτό το νήμα με αιτήματα από άλλα νήματα. Οι εφαρμογές που χρησιμοποιούν αντικείμενα @ref{1738,,Queue} για επικοινωνία και συντονισμό μεταξύ νημάτων είναι πιο εύκολο να σχεδιαστούν, είναι πιο ευανάγνωστες και πιο αξιόπιστες.

@node Logging,Weak references,Multi-threading<2>,Brief tour of the standard library — part II
@anchor{tutorial/stdlib2 logging}@anchor{22cb}@anchor{tutorial/stdlib2 tut-logging}@anchor{22cc}
@subsection Logging


Το module @ref{8a,,logging} προσφέρει ένα πλήρως εξοπλισμένο και ευέλικτο σύστημα καταγραφής. Στην απλούστερη μορφή του, τα μηνύματα καταγραφής αποστέλλονται σε ένα αρχείο ή στο @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

Αυτό παράγει την ακόλουθη έξοδο:

@example
WARNING:root:Warning:config file server.conf not found
ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down
@end example

Από default (προεπιλογή), τα ενημερωτικά μηνύματα και τα μηνύματα εντοπισμού σφαλμάτων αποκρύπτονται και η έξοδος αποστέλλεται σε τυπικό σφάλμα.  Άλλες επιλογές εξόδου περιλαμβάνουν δρομολόγηση μηνυμάτων μέσω email, datagrams, υποδοχών (sockets), ή σε HTTP διακομιστή (server).  Τα νέα φίλτρα μπορούν να επιλέξουν διαφορετική δρομολόγηση με βάση την προτεραιότητα του μηνύματος: @ref{22cd,,DEBUG}, @ref{22ce,,INFO}, @ref{22cf,,WARNING}, @ref{22d0,,ERROR}, και @ref{22d1,,CRITICAL}.

Το σύστημα logging μπορεί να διαμορφωθεί απευθείας από την Python ή μπορεί να φορτωθεί από ένα επεξεργάσιμο αρχείο διαμόρφωσης για προσαρμοσμένη καταγραφή χωρίς την τροποποίηση της εφαρμογής.

@node Weak references,Tools for working with lists,Logging,Brief tour of the standard library — part II
@anchor{tutorial/stdlib2 tut-weak-references}@anchor{22d2}@anchor{tutorial/stdlib2 weak-references}@anchor{22d3}
@subsection Weak references


Η Python κάνει αυτόματη διαχείριση μνήμης (καταμέτρηση αναφορών για τα περισσότερα αντικείμενα και @ref{19de,,garbage collection} για την εξάλειψη των κύκλων).  Η μνήμη ελευθερώνεται λίγο μετά την κατάργηση της τελευταίας αναφοράς σε αυτήν.

Αυτή η προσέγγιση λειτουργεί καλά για τις περισσότερες εφαρμογές, αλλά περιστασιακά υπάρχει ανάγκη παρακολούθησης αντικειμένων μόνο εφόσον χρησιμοποιούνται από κάτι άλλο.  Δυστυχώς, η παρακολούθηση τους δημιουργεί μια αναφορά που τα κάνει μόνιμα. Το module @ref{11d,,weakref} παρέχει εργαλεία για την παρακολούθηση αντικειμένων χωρίς τη δημιουργία αναφοράς.  Όταν το αντικείμενο δεν χρειάζεται πλέον, αφαιρείται αυτόματα από έναν πίνακα ασθενούς αναφοράς και ενεργοποιείται μια επιστροφή κλήσης για αντικείμενα ασθενούς αναφοράς:

@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:/python316/lib/weakref.py", line 46, in __getitem__
    o = self.data[key]()
KeyError: 'primary'
@end example

@node Tools for working with lists,Decimal floating-point arithmetic,Weak references,Brief tour of the standard library — part II
@anchor{tutorial/stdlib2 tools-for-working-with-lists}@anchor{22d4}@anchor{tutorial/stdlib2 tut-list-tools}@anchor{22d5}
@subsection Tools for working with lists


Πολλές ανάγκες δομών δεδομένων μπορούν να καλυφθούν με τον ενσωματωμένο τύπο λίστας. Ωστόσο, μερικές φορές υπάρχει ανάγκη για εναλλακτικές υλοποιήσεις με διαφορετικούς συμβιβασμούς απόδοσης.

Το module @ref{8,,array} παρέχει ένα αντικείμενο @ref{6c5,,array} που μοιάζει με μια λίστα που αποθηκεύει μόνο ομοιογενή δεδομένα και τα αποθηκεύει με πιο συμπαγή τρόπο.  Το ακόλουθο παράδειγμα δείχνει έναν πίνακα αριθμών που είναι αποθηκευμένοι ως δύο byte ανυπόγραφων δυαδικών (binary) αριθμών (κωδικός τύπου @code{"H"}) αντί για τα συνηθισμένα 16 byte ανά καταχώρηση για κανονικές λίστες αντικειμένων τύπου Python int:

@example
>>> from array import array
>>> a = array('H', [4000, 10, 700, 22222])
>>> sum(a)
26932
>>> a[1:3]
array('H', [10, 700])
@end example

Το module @ref{1e,,collections} παρέχει ένα αντικείμενο @ref{9d6,,deque} που μοιάζει με λίστα με ταχύτερα προσαρτήματα και αναδύεται από την αριστερή πλευρά αλλά με πιο αργές αναζητήσεις στη μέση. Αυτά τα αντικείμενα είναι κατάλληλα για υλοποίηση ουρών και αναζητήσεων σε πρώτο δέντρο εύρους:

@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

Εκτός από τις εναλλακτικές υλοποιήσεις λιστών, η βιβλιοθήκη προσφέρει επίσης και άλλα εργαλεία όπως το module @ref{12,,bisect} με συναρτήσεις για τον χειρισμό ταξινομημένων λιστών:

@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

Το module @ref{6c,,heapq} παρέχει λειτουργίες για την υλοποίηση σωρών (heaps) που βασίζονται σε κανονικές λίστες.  Η καταχώριση με την χαμηλότερη τιμή διατηρείται πάντα στη θέση μηδέν.  Αυτό είναι χρήσιμο για εφαρμογές που έχουν επανειλημμένα πρόσβαση στο μικρότερο στοιχείο αλλά δεν θέλουν να εκτελέσουν μια πλήρη ταξινόμηση λίστας:

@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,,Tools for working with lists,Brief tour of the standard library — part II
@anchor{tutorial/stdlib2 decimal-floating-point-arithmetic}@anchor{22d6}@anchor{tutorial/stdlib2 tut-decimal-fp}@anchor{22d7}
@subsection Decimal floating-point arithmetic


Το module @ref{39,,decimal} προσφέρουν έναν τύπο δεδομένων @ref{1c2,,Decimal} για δεκαδική αριθμητική κινητής υποδιαστολής.  Σε σύγκριση με την ενσωματωμένη (built-in) εφαρμογή @ref{327,,float} του δυαδικού κινητής υποδιαστολής, η κλάση είναι ιδιαίτερα χρήσιμη για


@itemize *

@item 
οικονομικές εφαρμογές και άλλες χρήσεις που απαιτούν ακριβή δεκαδική αναπαράσταση,

@item 
έλεγχος για την ακρίβεια,

@item 
έλεγχος της στρογγυλοποίησης για την εκπλήρωση νομικών ή κανονιστικών απαιτήσεων,

@item 
παρακολούθηση σημαντικών δεκαδικών ψηφίων, ή

@item 
εφαρμογές όπου ο χρήστης αναμένει ότι τα αποτελέσματα ταιριάζουν με υπολογισμούς που έγιναν με το χέρι.
@end itemize

Για παράδειγμα, ο υπολογισμός ενός φόρου 5% σε χρέωση τηλεφώνου 70 λεπτών δίνει διαφορετικά αποτελέσματα σε δεκαδική κινητή υποδιαστολή και σε δυαδική (binary) κινητή υποδιαστολή. Η διαφορά γίνεται σημαντική εάν τα αποτελέσματα στρογγυλοποιηθούν στο πλησιέστερο λεπτό:

@example
>>> from decimal import *
>>> round(Decimal('0.70') * Decimal('1.05'), 2)
Decimal('0.74')
>>> round(.70 * 1.05, 2)
0.73
@end example

Το αποτέλεσμα @ref{1c2,,Decimal} διατηρεί ένα μηδέν στο τέλος, συνάγοντας αυτόματα τη σημασία τεσσάρων θέσεων από πολλαπλάσια με σημασία δύο θέσεων.  Το δεκαδικό αναπαράγει τα μαθηματικά όπως γίνονται με το χέρι και αποφεύγει ζητήματα που μπορεί να προκύψουν όταν η δυαδική κινητή υποδιαστολή δεν μπορεί να αντιπροσωπεύει ακριβώς τις δεκαδικές ποσότητες.

Η ακριβής αναπαράσταση επιτρέπει στην κλάση @ref{1c2,,Decimal} να εκτελεί υπολογισμούς modulo και δοκιμές ισότητας που είναι ακατάλληλες για δυαδική κινητή υποδιαστολή:

@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

Το module @ref{39,,decimal} παρέχει αριθμητική με όση ακρίβεια χρειάζεται:

@example
>>> getcontext().prec = 36
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857')
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Εικονικά Περιβάλλοντα και πακέτα,Και τώρα τι;,Brief tour of the standard library — part II,Οδηγός εκμάθησης Python
@anchor{tutorial/venv doc}@anchor{22d8}@anchor{tutorial/venv translation-repo}@anchor{22d9}@anchor{tutorial/venv tut-venv}@anchor{22da}@anchor{tutorial/venv virtual-environments-and-packages}@anchor{22db}
@section Εικονικά Περιβάλλοντα και πακέτα


@menu
* Εισαγωγή:: 
* Δημιουργία εικονικών περιβάλλοντων:: 
* Διαχείριση Πακέτων με το pip:: 

@end menu

@node Εισαγωγή,Δημιουργία εικονικών περιβάλλοντων,,Εικονικά Περιβάλλοντα και πακέτα
@anchor{tutorial/venv introduction}@anchor{22dc}
@subsection Εισαγωγή


Οι εφαρμογές Python συχνά χρησιμοποιούν πακέτα και modules που δεν αποτελούν μέρος της τυπικής βιβλιοθήκης.  Οι εφαρμογές μερικές φορές χρειάζονται μια συγκεκριμένη έκδοση μιας βιβλιοθήκης, επειδή η εφαρμογή μπορεί να απαιτεί την επιδιόρθωση ενός συγκεκριμένου σφάλματος ή επειδή η εφαρμογή έχει γραφεί χρησιμοποιώντας μια ξεπερασμένη έκδοση της διεπαφής της βιβλιοθήκης.

Αυτό σημαίνει ότι μπορεί να μην είναι δυνατό για μία εγκατάσταση Python να πληροί τις απαιτήσεις κάθε εφαρμογής.  Εάν η εφαρμογή A χρειάζεται την έκδοση 1.0 ενός συγκεκριμένου module, αλλά η εφαρμογή B χρειάζεται την έκδοση 2.0, τότε οι απαιτήσεις βρίσκονται σε σύγκρουση και η εγκατάσταση της έκδοσης 1.0 ή 2.0 θα αφήσει μια εφαρμογή ανίκανη να εκτελεστεί.

Η λύση για αυτό το πρόβλημα είναι να δημιουργήσετε ένα @ref{22dd,,virtual environment}, ένα αυτόνομο δέντρο καταλόγου που περιέχει μια εγκατάσταση Python για μια συγκεκριμένη έκδοση της Python, καθώς και έναν αριθμό πρόσθετων πακέτων.

Διαφορετικές εφαρμογές μπορούν στη συνέχεια να χρησιμοποιούν διαφορετικά εικονικά περιβάλλοντα.  Για να επιλύσετε το προηγούμενο παράδειγμα αντικρουόμενων απαιτήσεων, η εφαρμογή A μπορεί να έχει το δικό της εικονικό περιβάλλον με εγκατεστημένη την έκδοση 1.0 ενώ η εφαρμογή B έχει άλλο εικονικό περιβάλλον με την έκδοση 2.0.  Εάν η εφαρμογή B απαιτεί αναβάθμιση βιβλιοθήκης στην έκδοση 3.0, αυτό δεν θα επηρεάσει το περιβάλλον της εφαρμογής A.

@node Δημιουργία εικονικών περιβάλλοντων,Διαχείριση Πακέτων με το pip,Εισαγωγή,Εικονικά Περιβάλλοντα και πακέτα
@anchor{tutorial/venv creating-virtual-environments}@anchor{22de}
@subsection Δημιουργία εικονικών περιβάλλοντων


Το module που χρησιμοποιείται για τη δημιουργία και τη διαχείριση εικονικών περιβαλλόντων ονομάζεται @ref{11a,,venv}.  Το @code{venv} θα εγκαταστήσει την έκδοση Python από την οποία εκτελέστηκε η εντολή (όπως αναφέρεται από την επιλογή @ref{10d5,,--version}). Για παράδειγμα, η εκτέλεση της εντολής με το @code{python3.12} θα εγκαταστήσει την έκδοση 3.12.

Για να δημιουργήσετε ένα εικονικό περιβάλλον, αποφασίστε έναν φάκελο όπου θέλετε να το τοποθετήσετε και εκτελέστε το module @ref{11a,,venv} ως ένα script με τη διαδρομή καταλόγου:

@example
python -m venv tutorial-env
@end example

Αυτό θα δημιουργήσει τον κατάλογο @code{tutorial-env} εάν δεν υπάρχει, και επίσης θα δημιουργήσει καταλόγους μέσα σε αυτόν που περιέχουν ένα αντίγραφο του interpreter της Python και διάφορα υποστηρικτικά αρχεία.

Μια κοινή τοποθεσία καταλόγου για ένα εικονικό περιβάλλον είναι @code{.venv}. Αυτό το όνομα κρατά τον κατάλογο συνήθως κρυμμένο στο shell σας και συνεπώς μακριά από τη διαδρομή, ενώ του δίνει ένα όνομα που εξηγεί γιατί υπάρχει ο κατάλογος. Αποτρέπει επίσης τη σύγκρουση με αρχεία ορισμού μεταβλητών περιβάλλοντος @code{.env} που υποστηρίζουν ορισμένα εργαλεία.

Μόλις δημιουργήσετε ένα εικονικό περιβάλλον, μπορεί να το ενεργοποιήσετε.

Σε Windows, εκτελέστε:

@example
tutorial-env\Scripts\activate
@end example

Σε Unix ή MacOS, εκτελέστε:

@example
source tutorial-env/bin/activate
@end example

(Αυτό το script είναι γραμμένο για το bash shell.  Εάν χρησιμοποιείτε τα shells @code{csh} ή @code{fish}, υπάρχουν εναλλακτικά scripts που θα πρέπει να χρησιμοποιούνται αντί αυτών, όπως @code{activate.csh} και @code{activate.fish}.)

Η ενεργοποίηση του εικονικού περιβάλλοντος θα αλλάξει το prompt του shell σας για να δείξει ποιο εικονικό περιβάλλον χρησιμοποιείτε και θα τροποποιήσει το περιβάλλον έτσι ώστε η εκτέλεση της @code{python} να σας δώσει τη συγκεκριμένη έκδοση και εγκατάσταση της Python. Για παράδειγμα:

@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

Για να απενεργοποιήσετε ένα εικονικό περιβάλλον, πληκτρολογήστε:

@example
απενεργοποίηση
@end example

μέσα στο terminal.

@node Διαχείριση Πακέτων με το pip,,Δημιουργία εικονικών περιβάλλοντων,Εικονικά Περιβάλλοντα και πακέτα
@anchor{tutorial/venv managing-packages-with-pip}@anchor{22df}
@subsection Διαχείριση Πακέτων με το pip


Μπορείτε να εγκαταστήσετε, να αναβαθμίσετε και να αφαιρέσετε πακέτα χρησιμοποιώντας ένα πρόγραμμα που ονομάζεται @code{pip}.  Από προεπιλογή το @code{pip} θα εγκαταστήσει πακέτα από το Python Package Index@footnote{https://pypi.org}.  Εσείς μπορείτε να περιηγηθείτε στο Python Package Index μεταβαίνοντας σε αυτό στο πρόγραμμα περιήγησης σας.

Το @code{pip} έχει έναν αριθμό υποεντολών: «install», «uninstall», «freeze», κ.λπ. (Συμβουλευτείτε τον οδηγό @ref{12a6,,Installing Python modules} για πλήρη τεκμηρίωση για το @code{pip}.)

Μπορείτε να εγκαταστήσετε την τελευταία έκδοση ενός πακέτου προσδιορίζοντας ένα όνομα ενός πακέτου:

@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

Μπορείτε επίσης να εγκαταστήσετε μια συγκεκριμένη έκδοση ενός πακέτου δίνοντας το όνομα του πακέτου ακολουθούμενο από @code{==} και τον αριθμό έκδοσης:

@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

Εάν εκτελέσετε ξανά αυτήν την εντολή, το @code{pip} θα παρατηρήσει ότι η ζητούμενη έκδοση είναι ήδη εγκατεστημένη και δεν θα κάνει τίποτα.  Μπορείτε να δώσετε έναν διαφορετικό αριθμός έκδοσης για να λάβετε αυτήν την έκδοση ή μπορείτε να εκτελέσετε το @code{python -m pip install --upgrade} για να αναβαθμίσετε το πακέτο στην πιο πρόσφατη έκδοση:

@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} συνοδευόμενο από ένα ή περισσότερα ονόματα πακέτου θα διαγράψει τα πακέτα από το εικονικό περιβάλλον.

Το @code{python -m pip show} θα εμφανίσει πληροφορίες σχετικά με ένα συγκεκριμένο πακέτο:

@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} θα εμφανίσει όλα τα πακέτα που είναι εγκατεστημένα στο εικονικό περιβάλλον:

@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} θα δημιουργήσει μια παρόμοια λίστα με τα εγκατεστημένα πακέτα, αλλά η έξοδος χρησιμοποιεί τη μορφή που αναμένει το @code{python -m pip install}. Μια κοινή σύμβαση είναι να τοποθετήσετε αυτήν τη λίστα σε ένα @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

Το @code{requirements.txt} μπορεί στη συνέχεια να δημοσιευθεί στον έλεγχο έκδοσης και να διατεθεί ως μέρος μιας εφαρμογής.  Οι χρήστες μπορούν στη συνέχεια να εγκαταστήσουν όλα τα απαραίτητα πακέτα με το @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} έχει πολλές περισσότερες επιλογές.  Συμβουλευτείτε τον οδηγό @ref{12a6,,Installing Python modules} για πλήρη τεκμηρίωση για το @code{pip}.  Όταν έχετε γράψει ένα πακέτο και θέλετε να το κάνετε διαθέσιμο στο Ευρετήριο Πακέτων Python, συμβουλευτείτε τον Python packaging user guide@footnote{https://packaging.python.org/en/latest/tutorials/packaging-projects/}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Και τώρα τι;,Διαδραστική Επεξεργασία Input και Αντικατάσταση Ιστορικού,Εικονικά Περιβάλλοντα και πακέτα,Οδηγός εκμάθησης Python
@anchor{tutorial/whatnow doc}@anchor{22e0}@anchor{tutorial/whatnow translation-repo}@anchor{22e1}@anchor{tutorial/whatnow tut-whatnow}@anchor{22e2}@anchor{tutorial/whatnow what-now}@anchor{22e3}
@section Και τώρα τι;


Η ανάγνωση αυτού του διδακτικού υλικού πιθανότατα ενίσχυσε το ενδιαφέρον σας για τη χρήση της Python — θα πρέπει να είστε πρόθυμοι να εφαρμόσετε την Python για την επίλυση των προβλημάτων του πραγματικού σας κόσμου.  Που πρέπει να πάτε για να μάθετε περισσότερα;

Αυτό το διδακτικό υλικό είναι μέρος του συνόλου τεκμηρίωσης της Python.   Μερικά άλλα έγγραφα του συνόλου είναι:


@itemize *

@item 
@ref{3f7,,The Python Standard Library}:

Θα πρέπει να περιηγηθείτε σε αυτό το εγχειρίδιο, το οποίο παρέχει πλήρες (αν και συνοπτικό) υλικό σχετικά με τους τύπους, τις συναρτήσεις, και τα modules στην standard βιβλιοθήκη.  Η standard διανομή Python περιλαμβάνει `πολύ' πρόσθετο κώδικα. Υπάρχουν modules για ανάγνωση ηλεκτρονικού γραμματοκιβωτίου Unix, ανάκτηση εγγράφων μέσω HTTP, δημιουργία τυχαίων αριθμών, ανάλυση επιλογών γραμμής εντολών, συμπίεση δεδομένων και πολλές εργασίες.  Το Skimming μέσω της βιβλιοθήκης θα σας δώσει μια ιδέα για το τι είναι διαθέσιμο.

@item 
@ref{12a6,,Installing Python modules} εξηγεί πως να εγκαταστήσετε πρόσθετα modules γραμμένα από άλλους χρήστες Python.

@item 
@ref{3f8,,Εγχειρίδιο Αναφοράς της Γλώσσας Python}: Μια λεπτομερής εξήγηση της σύνταξης και της σημασιολογίας.  Είναι βαριά ανάγνωση, αλλά είναι χρήσιμο ως πλήρης οδηγός για την ίδια τη γλώσσα.
@end itemize

Περισσότερα Βοηθήματα για Python:


@itemize *

@item 
@indicateurl{https://www.python.org}:  Ο κύριος ιστότοπος της Python.  Περιέχει κώδικα, τεκμηρίωση, και δείκτες που σχετίζονται με την Python στο web.

@item 
@indicateurl{https://docs.python.org}:  Γρήγορη πρόσβαση στην τεκμηρίωση της Python.

@item 
@indicateurl{https://pypi.org}: Το ευρετήριο Πακέτων Python, που προηγουμένως ονομαζόταν επίσης Τυροκομείο @footnote{
«Cheese Shop» is a Monty Python sketch: a customer enters a cheese shop,
but whatever cheese he asks for, the clerk says it’s missing.
}, είναι ένα ευρετήριο Python modules που έχουν δημιουργηθεί από χρήστες που είναι διαθέσιμα για λήψη.  Μόλις ξεκινήσετε την κυκλοφορία του κώδικα, μπορείτε να τον καταχωρήσετε εδώ για το βρουν άλλοι.

@item 
@indicateurl{https://code.activestate.com/recipes/langs/python/}: Το Python Cookbook είναι μια αρκετά μεγάλη συλλογή παραδειγμάτων κώδικα, μεγαλύτερα modules και χρήσιμα scripts. Ιδιαίτερα αξιοσημείωτες συνεισφορές συλλέγονται σε ένα βιβλίο με τίτλο Python Cookbook (O’Reilly & Associates, ISBN 0-596-00797-3.)

@item 
@indicateurl{https://pyvideo.org} συλλέγει συνδέσμους προς βίντεο που σχετίζονται με την Python από συνέδρια και συναντήσεις ομάδων χρηστών.

@item 
@indicateurl{https://scipy.org}: Το έργο Scientific Python περιλαμβάνει modules για γρήγορους υπολογισμούς και χειρισμούς πινάκων συν μια σειρά από πακέτα για πράγματα όπως η γραμμική άλγεβρα, οι μετασχηματισμοί Fourier, οι μη γραμμικοί λύτες, οι κατανομές τυχαίνω αριθμών, η στατιστική ανάλυση και τα λοιπά παρόμοια.
@end itemize

Για ερωτήσεις και αναφορές προβλημάτων που σχετίζονται με Python, μπορείτε να δημοσιεύσετε στην ομάδα συζήτησης @code{comp.lang.python}, ή να τις στείλετε στη λίστα αλληλογραφίας στην διεύθυνση @email{python-list@@python.org}.  Η ομάδα συζήτησης και η λίστα αλληλογραφίας είναι gatewayed , έτσι ώστε τα μηνύματα που δημοσιεύονται στο ένα θα προωθούνται αυτόματα στο άλλο.  Υπάρχουν εκατοντάδες αναρτήσεις την ημέρα, που κάνουν (και απαντούν) ερωτήσεις, προτείνουν νέες δυνατότητες και ανακοινώνουν νέα modules. Τα αρχεία της λίστα αλληλογραφίας είναι διαθέσιμα στη διεύθυνση @indicateurl{https://mail.python.org/pipermail/}.

Πριν από τη δημοσίευση, φροντίστε να ελέγξετε τη λίστα με @ref{22e4,,Frequently Asked Questions} (σε συντομογραφία FAQ).  Οι FAQ ερωτήσεις απαντούν σε πολλές από τις ερωτήσεις που εμφανίζονται ξανά και ξανά και μπορεί να περιέχουν ήδη τη λύση για το πρόβλημά σας.

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Διαδραστική Επεξεργασία Input και Αντικατάσταση Ιστορικού,Αριθμητική Κινητής Υποδιαστολής Ζητήματα και Περιορισμοί,Και τώρα τι;,Οδηγός εκμάθησης Python
@anchor{tutorial/interactive doc}@anchor{22e5}@anchor{tutorial/interactive interactive-input-editing-and-history-substitution}@anchor{22e6}@anchor{tutorial/interactive translation-repo}@anchor{22e7}@anchor{tutorial/interactive tut-interacting}@anchor{21b8}
@section Διαδραστική Επεξεργασία Input και Αντικατάσταση Ιστορικού


Ορισμένες εκδόσεις του interpreter της Python υποστηρίζουν την επεξεργασία του τρέχοντος input και την αντικατάσταση του ιστορικού, παρόμοια με τις λειτουργίες που βρίσκονται στο κέλυφος Korn και στο κέλυφος GNU Bash.  Αυτό υλοποιείται χρησιμοποιώντας τη βιβλιοθήκη GNU Readline@footnote{https://tiswww.case.edu/php/chet/readline/rltop.html}, η οποία υποστηρίζει διάφορα στυλ επεξεργασίας.  Αυτή η βιβλιοθήκη έχει τη δική της τεκμηρίωση που δεν θα αντιγράψουμε εδώ.

@menu
* Συμπλήρωση Tab και Επεξεργασία Ιστορικού:: 
* Εναλλακτικές λύσεις για τον Διαδραστικό Interpreter:: 

@end menu

@node Συμπλήρωση Tab και Επεξεργασία Ιστορικού,Εναλλακτικές λύσεις για τον Διαδραστικό Interpreter,,Διαδραστική Επεξεργασία Input και Αντικατάσταση Ιστορικού
@anchor{tutorial/interactive tab-completion-and-history-editing}@anchor{22e8}@anchor{tutorial/interactive tut-keybindings}@anchor{22e9}
@subsection Συμπλήρωση Tab και Επεξεργασία Ιστορικού


Η ολοκλήρωση των ονομάτων των μεταβλητών και των modules @ref{1372,,ενεργοποιείται αυτόματα} κατά την εκκίνηση του interpreter, έτσι ώστε το κλειδί @code{Tab} να καλεί τη συνάρτηση ολοκλήρωσης∙ κοιτάζει τα ονόματα δηλώσεων της Python, τις τρέχουσες τοπικές μεταβλητές, και τα διαθέσιμα ονόματα των modules.  Για dotted εκφράσεις, όπως @code{string.a}, θα αξιολογήσει την έκφραση μέχρι το τελικό @code{'.'} και στη συνέχεια θα προτείνει συμπληρώσεις από τα χαρακτηριστικά του αντικειμένου που προκύπτει.  Σημειώστε ότι αυτό μπορεί να εκτελέσει κώδικα που ορίζεται από την εφαρμογή εάν ένα αντικείμενο με μια μέθοδο @ref{8e3,,__getattr__()} είναι μέρος της πρότασης.  Η προεπιλεγμένη διαμόρφωση αποθηκεύει επίσης το ιστορικό σας σε ένα αρχείο με το όνομα @code{.python_history} στον κατάλογο του χρήστης σας.  Το ιστορικό θα είναι ξανά διαθέσιμο κατά την επόμενη συνεδρία διαδραστικού interpreter.

@node Εναλλακτικές λύσεις για τον Διαδραστικό Interpreter,,Συμπλήρωση Tab και Επεξεργασία Ιστορικού,Διαδραστική Επεξεργασία Input και Αντικατάσταση Ιστορικού
@anchor{tutorial/interactive alternatives-to-the-interactive-interpreter}@anchor{22ea}@anchor{tutorial/interactive tut-commentary}@anchor{22eb}
@subsection Εναλλακτικές λύσεις για τον Διαδραστικό Interpreter


Αυτή η λειτουργία είναι ένα τεράστιο βήμα προς τα εμπρός σε σύγκριση με τις προηγούμενες εκδόσεις του διερμηνέα∙ ωστόσο, παραμένουν μερικές επιθυμίες: Θα ήταν ωραίο να προταθεί η κατάλληλη εσοχή στις γραμμές συνέχειας (ο parser γνωρίζει εάν ένα @ref{22ec,,INDENT} token απαιτείται στη συνέχεια).  Ο μηχανισμός ολοκλήρωσης μπορεί να χρησιμοποιήσει τον πίνακα συμβόλων του διερμηνέα.  Θα ήταν επίσης χρήσιμη μια εντολή για να ελέγξετε (ή ακόμα και να προτείνετε) αντίστοιχες παρενθέσεις, εισαγωγικά κ.λπ.

Ένας εναλλακτικός, βελτιωμένος, διαδραστικός interpreter που υπάρχει εδώ και αρκετό καιρό είναι το IPython@footnote{https://ipython.org/}, το οποίο διαθέτει συμπλήρωση tab, εξερεύνηση αντικειμένων και προηγμένη διαχείριση ιστορικού.  Μπορεί επίσης να προσαρμοστεί πλήρως και να ενσωματωθεί σε άλλες εφαρμογές.  Ένα άλλο παρόμοιο βελτιωμένο διαδραστικό περιβάλλον είναι το bpython@footnote{https://bpython-interpreter.org/}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c import math
@c from fractions import Fraction

@node Αριθμητική Κινητής Υποδιαστολής Ζητήματα και Περιορισμοί,Παράρτημα,Διαδραστική Επεξεργασία Input και Αντικατάσταση Ιστορικού,Οδηγός εκμάθησης Python
@anchor{tutorial/floatingpoint doc}@anchor{22ed}@anchor{tutorial/floatingpoint floating-point-arithmetic-issues-and-limitations}@anchor{22ee}@anchor{tutorial/floatingpoint translation-repo}@anchor{22ef}@anchor{tutorial/floatingpoint tut-fp-issues}@anchor{22f0}
@section Αριθμητική Κινητής Υποδιαστολής:  Ζητήματα και Περιορισμοί


Οι αριθμοί κινητής υποδιαστολής αντιπροσωπεύονται στο υλικό του υπολογιστή ως κλάσματα με βάση το 2 (δυαδικά).  Για παράδειγμα, το `δεκαδικό' κλάσμα @code{0.625} έχει τιμή 6/10 + 2/100 + 5/1000, και με τον ίδιο τρόπο το `δυαδικό' κλάσμα @code{0.101} έχει τιμή 1/2 + 0/4 + 1/8. Αυτά τα δύο κλάσματα έχουν πανομοιότυπες τιμές, η μόνη πραγματική διαφορά είναι ότι το πρώτο είναι γραμμένο με κλασματικό συμβολισμό με βάση το 10, και το δεύτερο με βάση το 2.

Δυστυχώς, τα περισσότερα δεκαδικά κλάσματα δεν μπορούν να αναπαρασταθούν ακριβώς ως κλάσματα.  Η συνέπεια είναι ότι, γενικά, οι δεκαδικοί αριθμοί κινητής υποδιαστολής που εισάγετε προσεγγίζονται μόνο από τους δυαδικούς αριθμούς κινητής υποδιαστολής που είναι πράγματι αποθηκευμένοι στο μηχάνημα.

Το πρόβλημα είναι πιο κατανοητό στην αρχή με βάση το 10.  Θεωρήστε το κλάσμα 1/3.  Μπορεί να το προσεγγίσετε ως κλάσμα βάσης 10:

@example
0.3
@end example

ή, καλύτερα,

@example
0.33
@end example

ή, καλύτερα,

@example
0.333
@end example

και ούτω καθεξής.  Όσα ψηφία και αν είστε διατεθειμένοι να γράψετε, το αποτέλεσμα δεν θα είναι ποτέ ακριβώς το 1/3, αλλά θα είναι μια ολοένα και καλύτερη προσέγγιση του 1/3.

Με τον ίδιο τρόπο, ανεξάρτητα από το πόσα ψηφία βάσης 2 είστε διατεθειμένοι να χρησιμοποιήσετε, η δεκαδική τιμή 0,1 δεν μπορεί να αναπαρασταθεί ακριβώς ως κλάσμα βάση 2.  Στη βάση 2, το 1/10 είναι το κλάσμα που επαναλαμβάνεται

@example
0.0001100110011001100110011001100110011001100110011...
@end example

Σταματήστε σε οποιονδήποτε πεπερασμένο αριθμό bit και λαμβάνετε μια προσέγγιση.  Στις περισσότερες μηχανές σήμερα, οι floats προσεγγίζονται χρησιμοποιώντας τα πρώτα 53 bit ξεκινώντας από το πιο σημαντικό bit και με τον παρανομαστή ως δύναμη του δύο.  Στην περίπτωση του 1/10, το δυαδικό κλάσμα είναι @code{3602879701896397 / 2 ** 55} που είναι κοντά αλλά όχι ακριβώς ίσο με την πραγματική τιμή του 1/10.

Πολλοί χρήστες δεν γνωρίζουν την προσέγγιση λόγω του τρόπου με τον οποίο εμφανίζονται οι τιμές.  Η Python εκτυπώνει μόνο μια δεκαδική προσέγγιση στην πραγματική δεκαδική τιμή της δυαδικής προσέγγισης που είναι αποθηκευμένη από το μηχάνημα.  Στα περισσότερα μηχανήματα,  αν η Python τύπωνε την πραγματική δεκαδική τιμή της δυαδικής προσέγγισης που είναι αποθηκευμένη για 0,1, θα πρέπει να εμφανίζει:

@example
>>> 0.1
0.1000000000000000055511151231257827021181583404541015625
@end example

Αυτά είναι περισσότερα ψηφία από όσα βρίσκουν χρήσιμα οι περισσότεροι, επομένως η Python διατηρεί τον αριθμό των διαχειρίσιμων ψηφίων εμφανίζοντας μια στρογγυλεμένη τιμή αντ” αυτού:

@example
>>> 1 / 10
0.1
@end example

Απλώς θυμηθείτε, παρόλο που το εκτυπωμένο αποτέλεσμα μοιάζει με την ακριβή τιμή του 1/10, η πραγματική αποθηκευμένη τιμή είναι το πλησιέστερο αναπαραστάσιμο δυαδικό κλάσμα.

Είναι ενδιαφέρον ότι υπάρχουν πολλοί διαφορετικοί δεκαδικοί αριθμοί που μοιράζονται το ίδιο πλησιέστερο κατά προσέγγιση δυαδικό κλάσμα.  Για παράδειγμα, οι αριθμοί @code{0.1} και @code{0.1000000000000000055511151231257827021181583404541015625} είναι όλα κατά προσέγγιση με @code{3602879701896397 / 2 ** 55}.  Δεδομένου ότι όλες αυτές οι δεκαδικές τιμές μοιράζονται την ίδια προσέγγιση, οποιαδήποτε από αυτές θα μπορούσε να εμφανιστεί διατηρώντας παράλληλα το αμετάβλητο @code{eval(repr(x)) == x}.

Ιστορικά, το prompt της Python και η ενσωματωμένη συνάρτηση @ref{45b,,repr()} θα επέλεγε αυτό με 17 σημαντικά ψηφία, @code{0.10000000000000001}.   Ξεκινώντας με την Python 3.1, η Python (στα περισσότερα συστήματα) είναι πλέον σε θέση να επιλέξει το συντομότερο από αυτά και απλά εμφανίζει το @code{0.1}.

Λάβετε υπόψη ότι αυτό είναι στην ίδια τη φύση του δυαδικού κινητής υποδιαστολής: αυτό δεν είναι σφάλμα στην Python, ούτε είναι σφάλμα στον κώδικα σας.  Θα δείτε το ίδιο πράγμα σε όλες τις γλώσσες που υποστηρίζουν την αριθμητική κινητής υποδιαστολής του υλικού σας (αν και ορισμένες γλώσσες μπορεί να μην `εμφανίζουν' τη διαφορά από προεπιλογή ή σε όλες τις λειτουργίες εξόδου).

Για πιο ευχάριστη απόδοση, μπορεί να θέλετε να χρησιμοποιήσετε μορφοποίηση συμβολοσειράς για να δημιουργήσετε έναν περιορισμένο αριθμό σημαντικών ψηφίων:

@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

Είναι σημαντικό να συνειδητοποιήσουμε ότι αυτό είναι, με την πραγματική έννοια, μια ψευδαίσθηση: απλά στρογγυλεύετε την `παρουσίαση' της πραγματικής αξίας του μηχανήματος.

Μια ψευδαίσθηση μπορεί να γεννήσει μια άλλη.  Για παράδειγμα, καθώς το 0,1 δεν είναι ακριβώς το 1/10, το άθροισμα τριών τιμών του 0,1 μπορεί να μην αποφέρει ακριβώς 0,3:

@example
>>> 0.1 + 0.1 + 0.1 == 0.3
False
@end example

Επίσης, εφόσον το 0.1 δεν μπορεί να πλησιάσει την ακριβή τιμή του 1/10 και το 0.3 δεν μπορεί να πλησιάσει την ακριβή τιμή του 3/10, τότε η προ-στρογγυλοποίηση με τη συνάρτηση @ref{167f,,round()} δεν μπορεί να βοηθήσει:

@example
>>> round(0.1, 1) + round(0.1, 1) + round(0.1, 1) == round(0.3, 1)
False
@end example

Αν και οι αριθμοί δεν μπορούν να γίνουν πιο κοντά στις προβλεπόμενες ακριβείς τιμές τους, η συνάρτηση @ref{1169,,math.isclose()} μπορεί να είναι χρήσιμη για τη σύγκριση ανακριβών τιμών:

@example
>>> math.isclose(0.1 + 0.1 + 0.1, 0.3)
True
@end example

Εναλλακτικά, η συνάρτηση @ref{167f,,round()} μπορεί να χρησιμοποιηθεί για τη σύγκριση χονδρικών προσεγγίσεων:

@example
>>> round(math.pi, ndigits=2) == round(22 / 7, ndigits=2)
True
@end example

Η αριθμητική δυαδικής κινητής υποδιαστολής επιφυλάσσει πολλές εκπλήξεις όπως αυτή.  Το πρόβλημα με το «0.1» εξηγείται λεπτομερώς παρακάτω, στην ενότητα «Σφάλμα Αναπαράστασης».  Δείτε Παραδείγματα προβλημάτων κινητής υποδιαστολής@footnote{https://jvns.ca/blog/2023/01/13/examples-of-¨floating-point-problems/} για μια ευχάριστη περίληψη του τρόπου λειτουργίας της δυαδικής κινητής υποδιαστολής και των ειδών προβλημάτων που αντιμετωπίζονται συνήθως στην πράξη.  Δείτε επίσης @cite{Οι κίνδυνοι του Floating Point <http://www.indowsway.com/floatingpoint.htm>`_} για μια πιο ολοκληρωμένη περιγραφή άλλων κοινών εκπλήξεων.

Όπως λέει αυτό κοντά στο τέλος, «δεν υπάρχουν εύκολες απαντήσεις.»  Ωστόσο, μην είστε υπερβολικά επιφυλακτικοί με την κινητή υποδιαστολή!  Τα σφάλματα στις λειτουργίες κινητής υποδιαστολής Python κληρονομούνται από το υλικό κινητής υποδιαστολής και στα περισσότερα μηχανήματα δεν είναι της τάξης του 1 σε 2**53 ανά πράξη.  Αυτό είναι παραπάνω από επαρκές για τις περισσότερες εργασίες, αλλά πρέπει να έχετε κατά νου ότι δεν είναι δεκαδική αριθμητική και ότι κάθε λειτουργία float μπορεί να υποστεί νέο σφάλμα στρογγυλοποίησης.

Ενώ υπάρχουν παθολογικές περιπτώσεις, για την πιο περιστασιακή χρήση της αριθμητικής κινητής υποδιαστολής, θα δείτε στο τέλος το αποτέλεσμα που περιμένετε εάν απλώς στρογγυλοποιήσετε την εμφάνιση των τελικών αποτελεσμάτων σας στον αριθμό των δεκαδικών ψηφίων που περιμένετε. Το @ref{1df,,str()} συνήθως αρκεί, και για καλύτερο έλεγχο δείτε τους προσδιοριστές μορφής της μεθόδου @ref{a12,,str.format()} σε @ref{173f,,Format string syntax}.

Για περιπτώσεις χρήσης που απαιτούν ακριβή δεκαδική αναπαράσταση, δοκιμάστε να χρησιμοποιήσετε το module @ref{39,,decimal} που εφαρμόζει δεκαδική αριθμητική κατάλληλη για λογιστικές εφαρμογές και εφαρμογές υψηλής ακριβείας.

Μια άλλη μορφή ακριβούς αριθμητικής υποστηρίζεται από το module @ref{60,,fractions}, η οποία υλοποιεί την αριθμητική με βάση τους ορθολογικούς αριθμούς (έτσι οι αριθμοί όπως το 1/3 μπορούν να αναπαρασταθούν ακριβώς).

Εάν είστε ένα εντατικός χρήστης πράξεων κινητής υποδιαστολής, θα πρέπει να ρίξετε μια ματιά στο πακέτο NumPy και πολλά άλλα πακέτα για μαθηματικές και στατιστικές πράξεις που παρέχονται από το project SciPy. Δείτε <@indicateurl{https://scipy.org}>.

Η Python παρέχει εργαλεία που μπορεί να βοηθήσουν σε εκείνες τις σπάνιες περιπτώσεις που πραγματικά θέλετε να μάθετε την ακριβή τιμή ενός float.  Η μέθοδος @ref{22f1,,float.as_integer_ratio()} εκφράζει την τιμή ενός float ως κλάσμα:

@example
>>> x = 3.14159
>>> x.as_integer_ratio()
(3537115888337719, 1125899906842624)
@end example

Δεδομένου ότι η αναλογία είναι ακριβής, μπορεί να χρησιμοποιηθεί για την αναδημιουργία χωρίς απώλειες της αρχικής τιμής:

@example
>>> x == 3537115888337719 / 1125899906842624
True
@end example

Η μέθοδος @ref{22f2,,float.hex()} εκφράζει ένα float σε δεκαεξαδικό (βάση 16), δίνοντας πάλι την ακριβή τιμή που έχει αποθηκευτεί στον υπολογιστή σας:

@example
>>> x.hex()
'0x1.921f9f01b866ep+1'
@end example

Αυτή η ακριβής δεκαεξαδική αναπαράσταση μπορεί να χρησιμοποιηθεί για την ανακατασκευή της τιμής float ακριβώς:

@example
>>> x == float.fromhex('0x1.921f9f01b866ep+1')
True
@end example

Δεδομένου ότι η αναπαράσταση είναι ακριβής, είναι χρήσιμη για την αξιόπιστη μεταφορά τιμών σε διαφορετικές εκδόσεις της Python (ανεξαρτησία πλατφόρμας) και την ανταλλαγή δεδομένων με άλλες γλώσσες που υποστηρίζουν την ίδια μορφή (όπως Java και C99).

Ένα άλλο χρήσιμο εργαλείο είναι η συνάρτηση @ref{881,,sum()} που βοηθά στον μετριασμό της απώλειας ακρίβειας κατά την άθροιση. Χρησιμοποιεί εκτεταμένη ακρίβεια για ενδιάμεσα βήματα στρογγυλοποίησης καθώς οι τιμές προστίθενται σε ένα τρέχον σύνολο.  Αυτό μπορεί να κάνει τη διαφορά στη συνολική ακρίβεια, ώστε τα σφάλματα να μην συσσωρεύονται στο σημείο που επηρεάζουν το τελικό σύνολο:

@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

Το @ref{1777,,math.fsum()} πηγαίνει πιο μακριά και παρακολουθεί όλα τα «χαμένα ψηφία» καθώς οι τιμές προστίθενται σε ένα τρέχον σύνολο, έτσι ώστε το αποτέλεσμα να έχει μόνο μία στρογγυλοποίηση.  Αυτό είναι πιο αργό από το @ref{881,,sum()} αλλά θα είναι πιο ακριβές σε ασυνήθιστες περιπτώσεις όπου οι είσοδοι μεγάλου μεγέθους ακυρώνουν η μία την άλλη αφήνοντας ένα τελικό άθροισμα κοντά στο μηδέν:

@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
* Σφάλμα Αναπαράστασης:: 

@end menu

@node Σφάλμα Αναπαράστασης,,,Αριθμητική Κινητής Υποδιαστολής Ζητήματα και Περιορισμοί
@anchor{tutorial/floatingpoint representation-error}@anchor{22f3}@anchor{tutorial/floatingpoint tut-fp-error}@anchor{22f4}
@subsection Σφάλμα Αναπαράστασης


Αυτή η ενότητα εξηγεί το παράδειγμα «0.1» λεπτομερώς και δείχνει πώς μπορείτε να εκτελέσετε μια ακριβή ανάλυση περιπτώσεων όπως αυτή μόνοι σας.  Υποτίθεται ότι έχετε βασική εξοικείωση με την αναπαράσταση δυαδικής κινητής υποδιαστολής.

Το `Σφάλμα αναπαράστασης (Representation error)' αναφέρεται στο γεγονός ότι ορισμένα (τα περισσότερα, στην πραγματικότητα) δεκαδικά κλάσματα δεν μπορούν να αναπαρασταθούν ακριβώς ως δυαδικά (βάση 2) κλάσματα.  Αυτός είναι ο κύριος λόγος για τον οποίο η Python (ή Perl, C, C++, Java, Fortran, και πολλές άλλες) συχνά δεν εμφανίζουν τον ακριβή δεκαδικό αριθμό που περιμένετε.

Γιατί συμβαίνει αυτό;  Το 1/10 δεν μπορεί να αναπαρασταθεί ακριβώς ως δυαδικό κλάσμα.  Από το 2000 τουλάχιστον, σχεδόν όλες οι μηχανές χρησιμοποιούν δυαδική αριθμητική κινητής υποδιαστολής IEEE 754 και σχεδόν όλες οι πλατφόρμες αντιστοιχίζουν τα Python floats σε IEEE binary64 «διπλής ακρίβειας» τιμές. Οι τιμές του IEEE 754 binary64 περιέχουν 53 bits ακρίβειας, επομένως κατά την είσοδο ο υπολογιστής προσπαθεί να μετατρέψει το 0,1 στο πλησιέστερο κλάσμα που μπορεί να έχει τη μορφή `J'/2**`N' όπου `J' είναι ένας ακέραιος που περιέχει ακριβώς 53 bits.  Ξαναγράφεται

@example
1 / 10 ~= J / (2**N)
@end example

ως

@example
J ~= 2**N / 10
@end example

και υπενθυμίζοντας ότι το `J' έχει ακριβώς 53 bits (είναι @code{>= 2**52} αλλά @code{< 2**53}), η καλύτερη τιμή για το `N' είναι 56:

@example
>>> 2**52 <=  2**56 // 10  < 2**53
True
@end example

Δηλαδή, το 56 είναι η μόνη τιμή για το `N' που αφήνει το `J' με ακριβώς 53 bits.  Η καλύτερη δυνατή τιμή για το `J' είναι τότε αυτό το πηλίκο στρογγυλοποιημένο:

@example
>>> q, r = divmod(2**56, 10)
>>> r
6
@end example

Δεδομένου ότι το υπόλοιπο είναι περισσότερο από το μισό του 10, η καλύτερη προσέγγιση επιτυγχάνεται με στρογγυλοποίηση προς τα επάνω:

@example
>>> q+1
7205759403792794
@end example

Ως εκ τούτου, η καλύτερη δυνατή προσέγγιση στο 1/10 στο IEEE 754 διπλής ακρίβειας είναι:

@example
7205759403792794 / 2 ** 56
@end example

Η διαίρεση του αριθμητή και του παρονομαστή με δύο μειώνει το κλάσμα σε:

@example
3602879701896397 / 2 ** 55
@end example

Λάβετε υπόψη ότι από τη στιγμή που κάναμε στρογγυλοποίηση, αυτό είναι στην πραγματικότητα λίγο μεγαλύτερο από το 1/10· αν δεν είχαμε στρογγυλοποιήσει προς τα πάνω, το πηλίκο θα ήταν λίγο μικρότερο από το 1/10.  Αλλά σε καμία περίπτωση δεν μπορεί να είναι `ακριβώς' 1/10!

Έτσι ο υπολογιστής δεν «βλέπει» ποτέ 1/10:  αυτό που βλέπει είναι το ακριβές κλάσμα που δίνεται παραπάνω, η καλύτερη διπλή προσέγγιση IEEE 754 που μπορεί να πάρει:

@example
>>> 0.1 * 2 ** 55
3602879701896397.0
@end example

Αν πολλαπλασιάσουμε αυτό το κλάσμα με 10**55, μπορούμε να δούμε την τιμή με 55 δεκαδικά ψηφία:

@example
>>> 3602879701896397 * 10 ** 55 // 2 ** 55
1000000000000000055511151231257827021181583404541015625
@end example

που σημαίνει ότι ο ακριβής αριθμός που είναι αποθηκευμένος στον υπολογιστή είναι ίσος με την δεκαδική τιμή 0.1000000000000000055511151231257827021181583404541015625.  Αντί να εμφανιστεί η πλήρης τιμή, πολλές γλώσσες (συμπεριλαμβανομένων των παλαιότερων εκδόσεων της Python), στρογγυλοποιούν το αποτέλεσμα σε 17 σημαντικά ψηφία:

@example
>>> format(0.1, '.17f')
'0.10000000000000001'
@end example

Τα modules @ref{60,,fractions} και @ref{39,,decimal} κάνουν αυτούς τους υπολογισμούς εύκολους:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Παράρτημα,,Αριθμητική Κινητής Υποδιαστολής Ζητήματα και Περιορισμοί,Οδηγός εκμάθησης Python
@anchor{tutorial/appendix doc}@anchor{22f5}@anchor{tutorial/appendix appendix}@anchor{22f6}@anchor{tutorial/appendix translation-repo}@anchor{22f7}@anchor{tutorial/appendix tut-appendix}@anchor{22f8}
@section Παράρτημα


@menu
* Διαδραστική Λειτουργία:: 

@end menu

@node Διαδραστική Λειτουργία,,,Παράρτημα
@anchor{tutorial/appendix interactive-mode}@anchor{22f9}@anchor{tutorial/appendix tut-interac}@anchor{6a0}
@subsection Διαδραστική Λειτουργία


Υπάρχουν δύο παραλλαγές του διαδραστικού @ref{69d,,REPL}.  Ο κλασικός βασικός διερμηνέας υποστηρίζει σε όλες τις πλατφόρμες με ελάχιστες δυνατότητες ελέγχου γραμμής.

Since Python 3.13, a new interactive shell is used by default.
This one supports color, multiline editing, history browsing, and
paste mode.  To disable color, see @ref{1af,,Controlling color} for
details.  Function keys provide some additional functionality.
@code{F1} enters the interactive help browser @ref{bd,,pydoc}.
@code{F2} allows for browsing command-line history with neither output nor the
@ref{69e,,>>>} and @ref{69f,,…} prompts. @code{F3} enters «paste mode», which
makes pasting larger blocks of code easier. Press @code{F3} to return to
the regular prompt.

Όταν χρησιμοποιείτε το νέο διαδραστικό κέλυφος, βγείτε από το shell πληκτρολογώντας @code{exit} or @code{quit}. Η προσθήκη παρενθέσεων κλήσης μετά από αυτές τις εντολές δεν απαιτείται.

Εάν το νέο διαδραστικό shell δεν είναι επιθυμητό, μπορεί να απενεργοποιηθεί μέσω της μεταβλητής περιβάλλοντος 
@geindex PYTHON_BASIC_REPL
@geindex μεταβλητή περιβάλλοντος; PYTHON_BASIC_REPL
@ref{452,,PYTHON_BASIC_REPL}.

@menu
* Διαχείριση Σφαλμάτων:: 
* Εκτελέσιμα Python Scripts:: 
* Το διαδραστικό αρχείο εκκίνησης:: 
* Τα Modules Προσαρμογής:: 

@end menu

@node Διαχείριση Σφαλμάτων,Εκτελέσιμα Python Scripts,,Διαδραστική Λειτουργία
@anchor{tutorial/appendix error-handling}@anchor{22fa}@anchor{tutorial/appendix tut-error}@anchor{22fb}
@subsubsection Διαχείριση Σφαλμάτων


Όταν παρουσιαστεί ένα σφάλμα, ο interpreter εμφανίζει ένα μήνυμα σφάλματος και ένα stack trace. Στη διαδραστική λειτουργία, στη συνέχεια επιστρέφει στην κύρια γραμμή εντολών∙ όταν η είσοδος προέρχεται από ένα αρχείο, εξέρχεται με κατάσταση εξόδου μη μηδενική μετά την εκτύπωση του stack trace.  (Οι εξαιρέσεις που αντιμετωπίζονται από μια εντολή @ref{447,,except} σε ένα @ref{ad6,,try} μπλοκ, δεν είναι σφάλματα σε αυτό το πλαίσιο.)  Ορισμένα σφάλματα είναι άνευ όρων μοιραία και προκαλούν έξοδο με κατάσταση εξόδου μη μηδενική.  Αυτό ισχύει για εσωτερικές ασυνέπειες και ορισμένες περιπτώσεις εξάντλησης της μνήμης.  Όλα τα μηνύματα σφάλματος εγγράφονται στην τυπική ροή σφαλμάτων∙ η κανονική έξοδος από τις εκτελεσμένες εντολές γράφεται στην τυπική έξοδο.

Πληκτρολογώντας τον χαρακτήρα διακοπής (συνήθως @code{Control}-@code{C} ή @code{Delete}) στην κύρια ή δευτερεύουσα γραμμή εντολών ακυρώνει την είσοδο και επιστρέφει στην κύρια γραμμή εντολών. @footnote{
Ένα πρόβλημα με το πακέτο GNU Readline μπορεί να το αποτρέψει.
} Πληκτρολογώντας μια διακοπή ενώ εκτελείται μια εντολή δημιουργείται η εξαίρεση @ref{d96,,KeyboardInterrupt}, η οποία μπορεί να αντιμετωπιστεί από μια πρόταση @ref{ad6,,try}.

@node Εκτελέσιμα Python Scripts,Το διαδραστικό αρχείο εκκίνησης,Διαχείριση Σφαλμάτων,Διαδραστική Λειτουργία
@anchor{tutorial/appendix executable-python-scripts}@anchor{22fc}@anchor{tutorial/appendix tut-scripts}@anchor{21c0}
@subsubsection Εκτελέσιμα Python Scripts


Στα συστήματα BSD’ish Unix systems, τα Python scripts μπορούν να γίνουν άμεσα εκτελέσιμα, όπως τα shell scripts, βάζοντας τη γραμμή:

@example
#!/usr/bin/env python3
@end example

(υποθέτοντας ότι ο interpreter βρίσκεται στο 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} του χρήστη) στην αρχή του σεναρίου και δίνοντας στο αρχείο μια εκτελέσιμη λειτουργία.  Το @code{#!} πρέπει να είναι οι δύο πρώτοι χαρακτήρες του αρχείου.  Σε ορισμένες πλατφόρμες, αυτή η πρώτη γραμμή πρέπει να τελειώνει με μια γραμμή τύπου Unix που τελειώνει με μια γραμμή τύπου Unix που τελειώνει (@code{'\n'}), όχι με γραμμή Windows (@code{'\r\n'}).  Σημειώστε ότι ο χαρακτήρας κατακερματισμού, , @code{'#'}, χρησιμοποιείται για την έναρξη ενός σχολίου στην Python.

Το script μπορεί να δοθεί μια εκτελέσιμη λειτουργία ή άδεια, χρησιμοποιώντας την εντολή @code{chmod}.

@example
$ chmod +x myscript.py
@end example

Στα συστήματα Windows, δεν υπάρχει η έννοια της «εκτελέσιμη λειτουργίας».  Το πρόγραμμα εγκατάστασης της Python συσχετίζει αυτόματα τα αρχεία @code{.py} με το @code{python.exe} έτσι ώστε να εκτελείται ένα διπλό κλικ σε ένα αρχείο Python ως script.  Η επέκταση μπορεί επίσης να είναι @code{.pyw}, σε αυτήν την περίπτωση, το παράθυρο της κονσόλας που εμφανίζεται συνήθως αποκρύπτεται.

@node Το διαδραστικό αρχείο εκκίνησης,Τα Modules Προσαρμογής,Εκτελέσιμα Python Scripts,Διαδραστική Λειτουργία
@anchor{tutorial/appendix the-interactive-startup-file}@anchor{22fd}@anchor{tutorial/appendix tut-startup}@anchor{22fe}
@subsubsection Το διαδραστικό αρχείο εκκίνησης


Όταν χρησιμοποιείτε την Python διαδραστικά, είναι συχνά βολικό να εκτελούνται ορισμένες τυπικές εντολές κάθε φορά που ξεκινά ο interpreter.  Μπορείτε να το κάνετε αυτό ορίζοντας μια μεταβλητή περιβάλλοντος με το όνομα 
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP} στο όνομα ενός αρχείου που περιέχει τις εντολές εκκίνησης σας.  Αυτό είναι παρόμοιο με το χαρακτηριστικό @code{.profile} στα Unix shells.

Αυτό το αρχείο διαβάζεται μόνο σε διαδραστικές συνεδρίες, όχι όταν η Python διαβάζει εντολές από ένα script, και όχι όταν το @code{/dev/tty} δίνεται ως η ρητή πηγή εντολών (η οποία κατά τα άλλα συμπεριφέρεται σαν μια διαδραστική συνεδρία).  Εκτελείται στον ίδιο χώρο ονομάτων όπου εκτελούνται αλληλεπιδραστικές εντολές, έτσι ώστε τα αντικείμενα που ορίζει ή εισάγει να μπορούν να χρησιμοποιηθούν χωρίς επιφύλαξη στη διαδραστική περίοδο λειτουργίας. Μπορείτε επίσης να αλλάξετε τις προτροπές @code{sys.ps1} και @code{sys.ps2} σε αυτό το αρχείο.

Εάν θέλετε να διαβάσετε ένα επιπλέον αρχείο εκκίνησης από τον τρέχοντα κατάλογο, μπορείτε να το προγραμματίσετε στο καθολικό αρχείο εκκίνησης χρησιμοποιώντας κώδικα όπως @code{if os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read())}.  Εάν θέλετε να χρησιμοποιήσετε το αρχείο εκκίνησης σε ένα σενάριο, πρέπει να το κάνετε ρητά στο 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 Προσαρμογής,,Το διαδραστικό αρχείο εκκίνησης,Διαδραστική Λειτουργία
@anchor{tutorial/appendix the-customization-modules}@anchor{22ff}@anchor{tutorial/appendix tut-customize}@anchor{2300}
@subsubsection Τα Modules Προσαρμογής


Η Python παρέχει δύο άγκιστρα για να σας επιτρέψει να την προσαρμόσετε: 
@geindex sitecustomize
sitecustomize και 
@geindex usercustomize
usercustomize.  Για να δείτε πώς λειτουργεί, πρέπει πρώτα να βρείτε τη θέση του καταλόγου πακέτων ιστοτόπων χρήστη.  Ξεκινήστε την Python και εκτελέσετε αυτός ο κώδικας:

@example
>>> import site
>>> site.getusersitepackages()
'/home/user/.local/lib/python3.x/site-packages'
@end example

Τώρα μπορείτε να δημιουργήσετε ένα αρχείο με το όνομα @code{usercustomize.py} σε αυτόν τον κατάλογο και να βάλετε ό,τι θέλετε σε αυτόν.  Θα επηρεάσει κάθε επίκληση της Python, εκτός εάν ξεκινήσει με την επιλογή @ref{1732,,-s} απενεργοποιήστε την αυτόματη εισαγωγή.

Το 
@geindex sitecustomize
sitecustomize λειτουργεί με τον ίδιο τρόπο, αλλά συνήθως δημιουργείται από έναν διαχειριστή του υπολογιστή στον παγκόσμιο κατάλογο πακέτων τοποθεσιών και εισάγεται πριν από το 
@geindex usercustomize
usercustomize.  Δείτε την τεκμηρίωση του module @ref{cf,,site} για περισσότερες λεπτομέρειες.

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Ρύθμιση και Χρήση της Python,Εγχειρίδιο Αναφοράς της Γλώσσας Python,Οδηγός εκμάθησης Python,Top
@anchor{using/index doc}@anchor{2301}@anchor{using/index python-setup-and-usage}@anchor{2302}@anchor{using/index translation-repo}@anchor{2303}@anchor{using/index using-index}@anchor{2304}
@chapter Ρύθμιση και Χρήση της Python


Αυτό το μέρος της τεκμηρίωσης είναι αφιερωμένο σε γενικές πληροφορίες σχετικά με τη ρύθμιση του περιβάλλοντος της Python σε διαφορετικές πλατφόρμες, την εκκίνηση του διερμηνέα και πράγματα που κάνουν το να δουλεύεις με την Python ευκολότερα.

@c ATTENTION: You probably should update Misc/python.man, too, if you modify
@c this file.

@menu
* Command line and environment: Command line and environment<2>. 
* Χρήση της Python σε πλατφόρμες Unix:: 
* Configure Python:: 
* Χρησιμοποιώντας Python στα Windows:: 
* Χρησιμοποιώντας Python σε macOS:: 
* Χρήση της Python σε Android:: 
* Χρήση Python σε iOS:: 
* Επεξεργαστές Κειμένου και IDEs:: 

@end menu

@node Command line and environment<2>,Χρήση της Python σε πλατφόρμες Unix,,Ρύθμιση και Χρήση της Python
@anchor{using/cmdline doc}@anchor{2305}@anchor{using/cmdline command-line-and-environment}@anchor{2306}@anchor{using/cmdline using-on-general}@anchor{1f98}
@section Command line and environment


The CPython interpreter scans the command line and the environment for various
settings.

`Λεπτομέρεια υλοποίησης CPython:' Other implementations” command line schemes may differ.  See
@ref{2307,,Εναλλακτικές Υλοποιήσεις} for further resources.

@menu
* Command line:: 
* Environment variables:: 

@end menu

@node Command line,Environment variables,,Command line and environment<2>
@anchor{using/cmdline command-line}@anchor{2308}@anchor{using/cmdline using-on-cmdline}@anchor{13b0}
@subsection Command line


When invoking Python, you may specify any of these options:

@example
python [-bBdEhiIOPqRsSuvVWx?] [-c command | -m module-name | script | - ] [args]
@end example

The most common use case is, of course, a simple invocation of a script:

@example
python myscript.py
@end example

@menu
* Interface options:: 
* Generic options:: 
* Miscellaneous options:: 
* Controlling color:: 

@end menu

@node Interface options,Generic options,,Command line
@anchor{using/cmdline interface-options}@anchor{2309}@anchor{using/cmdline using-on-interface-options}@anchor{230a}
@subsubsection Interface options


The interpreter interface resembles that of the UNIX shell, but provides some
additional methods of invocation:


@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}-@code{D} on UNIX or @code{Ctrl}-@code{Z,} @code{Enter} on Windows) is read.
For more on interactive mode, see @ref{6a0,,Διαδραστική Λειτουργία}.

@item 
When called with a file name argument or with a file as standard input, it
reads and executes a script from that file.

@item 
When called with a directory name argument, it reads and executes an
appropriately named script from that directory.

@item 
When called with @code{-c command}, it executes the Python statement(s) given as
`command'.  Here `command' may contain multiple statements separated by
newlines.

@item 
When called with @code{-m module-name}, the given module is located on the
Python module path and executed as a script.
@end itemize

In non-interactive mode, the entire input is parsed before it is executed.

An interface option terminates the list of options consumed by the interpreter,
all consecutive arguments will end up in @ref{1609,,sys.argv} – note that the first
element, subscript zero (@code{sys.argv[0]}), is a string reflecting the program’s
source.

@geindex command line option; -c
@anchor{using/cmdline cmdoption-c}@anchor{445}
@deffn {Option} @w{-}c <command>

Execute the Python code in `command'.  `command' can be one or more
statements separated by newlines, with significant leading whitespace as in
normal module code.

If this option is given, the first element of @ref{1609,,sys.argv} will be
@code{"-c"} and the current directory will be added to the start of
@ref{194,,sys.path} (allowing modules in that directory to be imported as top
level modules).

Raises an @ref{1e65,,auditing event} @code{cpython.run_command} with argument @code{command}.


Άλλαξε στην έκδοση 3.14: `command' is automatically dedented before execution.

@end deffn

@geindex command line option; -m
@anchor{using/cmdline cmdoption-m}@anchor{4ca}
@deffn {Option} @w{-}m <module@w{-}name>

Search @ref{194,,sys.path} for the named module and execute its contents as
the @ref{1,,__main__} module.

Since the argument is a `module' name, you must not give a file extension
(@code{.py}).  The module name should be a valid absolute Python module name, but
the implementation may not always enforce this (e.g. it may allow you to
use a name that includes a hyphen).

Package names (including namespace packages) are also permitted. When a
package name is supplied instead
of a normal module, the interpreter will execute @code{<pkg>.__main__} as
the main module. This behaviour is deliberately similar to the handling
of directories and zipfiles that are passed to the interpreter as the
script argument.

@cartouche
@quotation Σημείωση 
This option cannot be used with built-in modules and extension modules
written in C, since they do not have Python module files. However, it
can still be used for precompiled modules, even if the original source
file is not available.
@end quotation
@end cartouche

If this option is given, the first element of @ref{1609,,sys.argv} will be the
full path to the module file (while the module file is being located, the
first element will be set to @code{"-m"}). As with the @ref{445,,-c} option,
the current directory will be added to the start of @ref{194,,sys.path}.

@ref{d28,,-I} option can  be used to run the script in isolated mode where
@ref{194,,sys.path} contains neither the current directory nor the user’s
site-packages directory. All @code{PYTHON*} environment variables are
ignored, too.

Many standard library modules contain code that is invoked on their execution
as a script.  An example is the @ref{f8,,timeit} module:

@example
python -m timeit -s "setup here" "benchmarked code here"
python -m timeit -h # for details
@end example

Raises an @ref{1e65,,auditing event} @code{cpython.run_module} with argument @code{module-name}.


@subsubheading Δείτε επίσης



@table @asis

@item @ref{1901,,runpy.run_module()}

Equivalent functionality directly available to Python code
@end table

@geindex Python Enhancement Proposals; PEP 338
PEP 338@footnote{https://peps.python.org/pep-0338/} – Executing modules as scripts



Άλλαξε στην έκδοση 3.1: Supply the package name to run a @code{__main__} submodule.



Άλλαξε στην έκδοση 3.4: namespace packages are also supported

@end deffn

@anchor{using/cmdline cmdarg-dash}@anchor{230b}
@deffn {Describe} @w{-}

Read commands from standard input (@ref{94a,,sys.stdin}).  If standard input is
a terminal, @ref{187d,,-i} is implied.

If this option is given, the first element of @ref{1609,,sys.argv} will be
@code{"-"} and the current directory will be added to the start of
@ref{194,,sys.path}.

Raises an @ref{1e65,,auditing event} @code{cpython.run_stdin} with no arguments.
@end deffn

@anchor{using/cmdline cmdarg-script}@anchor{230c}
@deffn {Describe} <script>

Execute the Python code contained in `script', which must be a filesystem
path (absolute or relative) referring to either a Python file, a directory
containing a @code{__main__.py} file, or a zipfile containing a
@code{__main__.py} file.

If this option is given, the first element of @ref{1609,,sys.argv} will be the
script name as given on the command line.

If the script name refers directly to a Python file, the directory
containing that file is added to the start of @ref{194,,sys.path}, and the
file is executed as the @ref{1,,__main__} module.

If the script name refers to a directory or zipfile, the script name is
added to the start of @ref{194,,sys.path} and the @code{__main__.py} file in
that location is executed as the @ref{1,,__main__} module.

@ref{d28,,-I} option can  be used to run the script in isolated mode where
@ref{194,,sys.path} contains neither the script’s directory nor the user’s
site-packages directory. All @code{PYTHON*} environment variables are
ignored, too.

Raises an @ref{1e65,,auditing event} @code{cpython.run_file} with argument @code{filename}.


@subsubheading Δείτε επίσης



@table @asis

@item @ref{6ae,,runpy.run_path()}

Equivalent functionality directly available to Python code
@end table

@end deffn

If no interface option is given, @ref{187d,,-i} is implied, @code{sys.argv[0]} is
an empty string (@code{""}) and the current directory will be added to the
start of @ref{194,,sys.path}.  Also, tab-completion and history editing is
automatically enabled, if available on your platform (see
@ref{1372,,Readline configuration}).


@subsubheading Δείτε επίσης


@ref{21b5,,Κάνοντας invoke τον Interpreter}



Άλλαξε στην έκδοση 3.4: Automatic enabling of tab-completion and history editing.


@node Generic options,Miscellaneous options,Interface options,Command line
@anchor{using/cmdline generic-options}@anchor{230d}@anchor{using/cmdline using-on-generic-options}@anchor{230e}
@subsubsection Generic options


@geindex command line option; -?
@geindex command line option; -h
@geindex command line option; --help
@anchor{using/cmdline cmdoption-0}@anchor{17ca}
@deffn {Option} @w{-}?
@anchor{using/cmdline cmdoption-h}@anchor{230f}
@deffnx {Option} @w{-}h
@anchor{using/cmdline cmdoption-help}@anchor{9e7}
@deffnx {Option} @w{-}@w{-}help

Print a short description of all command line options and corresponding
environment variables and exit.
@end deffn

@geindex command line option; --help-env
@anchor{using/cmdline cmdoption-help-env}@anchor{9e9}
@deffn {Option} @w{-}@w{-}help@w{-}env

Print a short description of Python-specific environment variables
and exit.


Added in version 3.11.

@end deffn

@geindex command line option; --help-xoptions
@anchor{using/cmdline cmdoption-help-xoptions}@anchor{9ea}
@deffn {Option} @w{-}@w{-}help@w{-}xoptions

Print a description of implementation-specific @ref{178,,-X} options
and exit.


Added in version 3.11.

@end deffn

@geindex command line option; --help-all
@anchor{using/cmdline cmdoption-help-all}@anchor{9eb}
@deffn {Option} @w{-}@w{-}help@w{-}all

Print complete usage information and exit.


Added in version 3.11.

@end deffn

@geindex command line option; -V
@geindex command line option; --version
@anchor{using/cmdline cmdoption-V}@anchor{6a7}
@deffn {Option} @w{-}V
@anchor{using/cmdline cmdoption-version}@anchor{10d5}
@deffnx {Option} @w{-}@w{-}version

Print the Python version number and exit.  Example output could be:

@example
Python 3.8.0b2+
@end example

When given twice, print more information about the build, like:

@example
Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]
@end example


Added in version 3.6: The @code{-VV} option.

@end deffn

@node Miscellaneous options,Controlling color,Generic options,Command line
@anchor{using/cmdline miscellaneous-options}@anchor{2310}@anchor{using/cmdline using-on-misc-options}@anchor{13b1}
@subsubsection Miscellaneous options


@geindex command line option; -b
@anchor{using/cmdline cmdoption-b}@anchor{2ed}
@deffn {Option} @w{-}b

Issue a warning when converting @ref{1c7,,bytes} or @ref{1c6,,bytearray} to
@ref{1df,,str} without specifying encoding or comparing @code{bytes} or
@code{bytearray} with @code{str} or @code{bytes} with @ref{326,,int}.
Issue an error when the option is given twice (@code{-bb}).


Άλλαξε στην έκδοση 3.5: Affects also comparisons of @ref{1c7,,bytes} with @ref{326,,int}.



Αποσύρθηκε στην έκδοση 3.15: Deprecate @ref{2ed,,-b} and @code{-bb} command line options
and schedule them to become no-op in Python 3.17.
These were primarily helpers for the Python 2 -> 3 transition.
Starting with Python 3.17, no @ref{2ee,,BytesWarning} will be raised
for these cases; use a type checker instead.

@end deffn

@geindex command line option; -B
@anchor{using/cmdline cmdoption-B}@anchor{1770}
@deffn {Option} @w{-}B

If given, Python won’t try to write @code{.pyc} files on the
import of source modules.  See also 
@geindex PYTHONDONTWRITEBYTECODE
@geindex μεταβλητή περιβάλλοντος; PYTHONDONTWRITEBYTECODE
@ref{1771,,PYTHONDONTWRITEBYTECODE}.
@end deffn

@geindex command line option; --check-hash-based-pycs
@anchor{using/cmdline cmdoption-check-hash-based-pycs}@anchor{2311}
@deffn {Option} @w{-}@w{-}check@w{-}hash@w{-}based@w{-}pycs default|always|never

Control the validation behavior of hash-based @code{.pyc} files. See
@ref{9e3,,Ακύρωση cached bytecode}. When set to @code{default}, checked and unchecked
hash-based bytecode cache files are validated according to their default
semantics. When set to @code{always}, all hash-based @code{.pyc} files, whether
checked or unchecked, are validated against their corresponding source
file. When set to @code{never}, hash-based @code{.pyc} files are not validated
against their corresponding source files.

The semantics of timestamp-based @code{.pyc} files are unaffected by this
option.
@end deffn

@geindex command line option; -d
@anchor{using/cmdline cmdoption-d}@anchor{2312}
@deffn {Option} @w{-}d

Turn on parser debugging output (for expert only).
See also the 
@geindex PYTHONDEBUG
@geindex μεταβλητή περιβάλλοντος; PYTHONDEBUG
@ref{2313,,PYTHONDEBUG} environment variable.

This option requires a @ref{3dc,,debug build of Python}, otherwise
it’s ignored.
@end deffn

@geindex command line option; -E
@anchor{using/cmdline cmdoption-E}@anchor{d27}
@deffn {Option} @w{-}E

Ignore all @code{PYTHON*} environment variables, e.g.
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} and 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME}, that might be set.

See also the @ref{9a3,,-P} and @ref{d28,,-I} (isolated) options.
@end deffn

@geindex command line option; -i
@anchor{using/cmdline cmdoption-i}@anchor{187d}
@deffn {Option} @w{-}i

Enter interactive mode after execution.

Using the @ref{187d,,-i} option will enter interactive mode in any of the following circumstances:


@itemize *

@item 
When a script is passed as first argument

@item 
When the @ref{445,,-c} option is used

@item 
When the @ref{4ca,,-m} option is used
@end itemize

Interactive mode will start even when @ref{94a,,sys.stdin} does not appear to be a terminal. The
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP} file is not read.

This can be useful to inspect global variables or a stack trace when a script
raises an exception.  See also 
@geindex PYTHONINSPECT
@geindex μεταβλητή περιβάλλοντος; PYTHONINSPECT
@ref{187c,,PYTHONINSPECT}.
@end deffn

@geindex command line option; -I
@anchor{using/cmdline cmdoption-I}@anchor{d28}
@deffn {Option} @w{-}I

Run Python in isolated mode. This also implies @ref{d27,,-E}, @ref{9a3,,-P}
and @ref{1732,,-s} options.

In isolated mode @ref{194,,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.


Added in version 3.4.

@end deffn

@geindex command line option; -O
@anchor{using/cmdline cmdoption-O}@anchor{431}
@deffn {Option} @w{-}O

Remove assert statements and any code conditional on the value of
@ref{bb7,,__debug__}.  Augment the filename for compiled
(@ref{6b3,,bytecode}) files by adding @code{.opt-1} before the @code{.pyc}
extension (see 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/}).  See also 
@geindex PYTHONOPTIMIZE
@geindex μεταβλητή περιβάλλοντος; PYTHONOPTIMIZE
@ref{2314,,PYTHONOPTIMIZE}.


Άλλαξε στην έκδοση 3.5: Modify @code{.pyc} filenames according to 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/}.

@end deffn

@geindex command line option; -OO
@anchor{using/cmdline cmdoption-OO}@anchor{116e}
@deffn {Option} @w{-}OO

Do @ref{431,,-O} and also discard docstrings.  Augment the filename
for compiled (@ref{6b3,,bytecode}) files by adding @code{.opt-2} before the
@code{.pyc} extension (see 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/}).


Άλλαξε στην έκδοση 3.5: Modify @code{.pyc} filenames according to 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/}.

@end deffn

@geindex command line option; -P
@anchor{using/cmdline cmdoption-P}@anchor{9a3}
@deffn {Option} @w{-}P

Don’t prepend a potentially unsafe path to @ref{194,,sys.path}:


@itemize *

@item 
@code{python -m module} command line: Don’t prepend the current working
directory.

@item 
@code{python script.py} command line: Don’t 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: Don’t prepend an
empty string, which means the current working directory.
@end itemize

See also the 
@geindex PYTHONSAFEPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONSAFEPATH
@ref{9a4,,PYTHONSAFEPATH} environment variable, and @ref{d27,,-E}
and @ref{d28,,-I} (isolated) options.


Added in version 3.11.

@end deffn

@geindex command line option; -q
@anchor{using/cmdline cmdoption-q}@anchor{1994}
@deffn {Option} @w{-}q

Don’t display the copyright and version messages even in interactive mode.


Added in version 3.2.

@end deffn

@geindex command line option; -R
@anchor{using/cmdline cmdoption-R}@anchor{2065}
@deffn {Option} @w{-}R

Turn on hash randomization. This option only has an effect if the
@geindex PYTHONHASHSEED
@geindex μεταβλητή περιβάλλοντος; PYTHONHASHSEED
@ref{1425,,PYTHONHASHSEED} environment variable is set to anything other
than @code{random}, since hash randomization is enabled by default.

On previous versions of Python, this option turns on hash randomization,
so that the @ref{ec1,,__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{https://ocert.org/advisories/ocert-2011-003.html} for details.

@geindex PYTHONHASHSEED
@geindex μεταβλητή περιβάλλοντος; PYTHONHASHSEED
@ref{1425,,PYTHONHASHSEED} allows you to set a fixed value for the hash
seed secret.


Added in version 3.2.3.



Άλλαξε στην έκδοση 3.7: The option is no longer ignored.

@end deffn

@geindex command line option; -s
@anchor{using/cmdline cmdoption-s}@anchor{1732}
@deffn {Option} @w{-}s

Don’t add the @ref{2315,,user site-packages directory} to
@ref{194,,sys.path}.

See also 
@geindex PYTHONNOUSERSITE
@geindex μεταβλητή περιβάλλοντος; PYTHONNOUSERSITE
@ref{1733,,PYTHONNOUSERSITE}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 370
PEP 370@footnote{https://peps.python.org/pep-0370/} – Per user site-packages directory

@end deffn

@geindex command line option; -S
@anchor{using/cmdline cmdoption-S}@anchor{1551}
@deffn {Option} @w{-}S

Disable the import of the module @ref{cf,,site} and the site-dependent
manipulations of @ref{194,,sys.path} that it entails.  Also disable these
manipulations if @code{site} is explicitly imported later (call
@ref{2316,,site.main()} if you want them to be triggered).
@end deffn

@geindex command line option; -u
@anchor{using/cmdline cmdoption-u}@anchor{1f7f}
@deffn {Option} @w{-}u

Force the stdout and stderr streams to be unbuffered.  This option has no
effect on the stdin stream.

See also 
@geindex PYTHONUNBUFFERED
@geindex μεταβλητή περιβάλλοντος; PYTHONUNBUFFERED
@ref{1f80,,PYTHONUNBUFFERED}.


Άλλαξε στην έκδοση 3.7: The text layer of the stdout and stderr streams now is unbuffered.

@end deffn

@geindex command line option; -v
@anchor{using/cmdline cmdoption-v}@anchor{17c7}
@deffn {Option} @w{-}v

Print a message each time a module is initialized, showing the place
(filename or built-in module) from which it is loaded.  When given twice
(@code{-vv}), print a message for each file that is checked for when
searching for a module.  Also provides information on module cleanup at exit.


Άλλαξε στην έκδοση 3.10: The @ref{cf,,site} module reports the site-specific paths
and @code{.pth} files being processed.


See also 
@geindex PYTHONVERBOSE
@geindex μεταβλητή περιβάλλοντος; PYTHONVERBOSE
@ref{2317,,PYTHONVERBOSE}.
@end deffn

@geindex command line option; -W
@anchor{using/cmdline using-on-warnings}@anchor{2318}@anchor{using/cmdline cmdoption-W}@anchor{1c0}
@deffn {Option} @w{-}W arg

Warning control. Python’s warning machinery by default prints warning
messages to @ref{d05,,sys.stderr}.

The simplest settings apply a particular action unconditionally to all
warnings emitted by a process (even those that are otherwise ignored by
default):

@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

The action names can be abbreviated as desired and the interpreter will
resolve them to the appropriate action name. For example, @code{-Wi} is the
same as @code{-Wignore}.

The full form of argument is:

@example
action:message:category:module:lineno
@end example

Empty fields match all values; trailing empty fields may be omitted. For
example @code{-W ignore::DeprecationWarning} ignores all DeprecationWarning
warnings.

The `action' field is as explained above but only applies to warnings that
match the remaining fields.

The `message' field must match the start of the warning message;
this match is case-insensitive.
If it starts and ends with a forward slash (@code{/}), it specifies
a regular expression, otherwise it specifies a literal string.

The `category' field matches the warning category
(ex: @code{DeprecationWarning}). This must be a class name; the match test
whether the actual warning category of the message is a subclass of the
specified warning category.

The `module' field matches the (fully qualified) module name; this match is
case-sensitive.
If it starts and ends with a forward slash (@code{/}), it specifies
a regular expression that the start of the fully qualified module name
must match, otherwise it specifies a literal string that the fully
qualified module name must be equal to.

The `lineno' field matches the line number, where zero matches all line
numbers and is thus equivalent to an omitted line number.

Multiple @ref{1c0,,-W} options can be given; when a warning matches more than
one option, the action for the last matching option is performed. Invalid
@code{-W} options are ignored (though, a warning message is printed about
invalid options when the first warning is issued).

Warnings can also be controlled using the 
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,PYTHONWARNINGS}
environment variable and from within a Python program using the
@ref{11b,,warnings} module. For example, the @ref{184b,,warnings.filterwarnings()}
function can be used to use a regular expression on the warning message.

See @ref{1cc,,Το Φίλτρο Προειδοποιήσεων} and @ref{2319,,Περιγραφή Φίλτρων Προειδοποιήσεων} for more
details.


Άλλαξε στην έκδοση 3.15: Added regular expression support for `message' and `module'.

@end deffn

@geindex command line option; -x
@anchor{using/cmdline cmdoption-x}@anchor{231a}
@deffn {Option} @w{-}x

Skip the first line of the source, allowing use of non-Unix forms of
@code{#!cmd}.  This is intended for a DOS specific hack only.
@end deffn

@geindex command line option; -X
@anchor{using/cmdline cmdoption-X}@anchor{178}
@deffn {Option} @w{-}X

Reserved for various implementation-specific options.  CPython currently
defines the following possible values:


@itemize *

@item 
@code{-X faulthandler} to enable @ref{5b,,faulthandler}.
See also 
@geindex PYTHONFAULTHANDLER
@geindex μεταβλητή περιβάλλοντος; PYTHONFAULTHANDLER
@ref{142d,,PYTHONFAULTHANDLER}.


Added in version 3.3.


@item 
@code{-X showrefcount} to output the total reference count and number of used
memory blocks when the program finishes or after each statement in the
interactive interpreter. This only works on @ref{3dc,,debug builds}.


Added in version 3.4.


@item 
@code{-X tracemalloc} to start tracing Python memory allocations using the
@ref{108,,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{231b,,tracemalloc.start()} and 
@geindex PYTHONTRACEMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONTRACEMALLOC
@ref{231c,,PYTHONTRACEMALLOC}
for more information.


Added in version 3.4.


@item 
@code{-X int_max_str_digits} configures the @ref{9ec,,integer string conversion length limitation}.  See also
@geindex PYTHONINTMAXSTRDIGITS
@geindex μεταβλητή περιβάλλοντος; PYTHONINTMAXSTRDIGITS
@ref{1d38,,PYTHONINTMAXSTRDIGITS}.


Added in version 3.11.


@item 
@code{-X importtime} to show how long each import takes. It shows module
name, cumulative time (including nested imports) and self time (excluding
nested imports).  Note that its output may be broken in multi-threaded
application.  Typical usage is @code{python -X importtime -c 'import asyncio'}.

@code{-X importtime=2} enables additional output that indicates when an
imported module has already been loaded.  In such cases, the string
@code{cached} will be printed in both time columns.

See also 
@geindex PYTHONPROFILEIMPORTTIME
@geindex μεταβλητή περιβάλλοντος; PYTHONPROFILEIMPORTTIME
@ref{ebb,,PYTHONPROFILEIMPORTTIME}.


Added in version 3.7.



Άλλαξε στην έκδοση 3.14: Added @code{-X importtime=2} to also trace imports of loaded modules,
and reserved values other than @code{1} and @code{2} for future use.


@item 
@code{-X dev}: enable @ref{70d,,Python Development Mode}, introducing
additional runtime checks that are too expensive to be enabled by
default.  See also 
@geindex PYTHONDEVMODE
@geindex μεταβλητή περιβάλλοντος; PYTHONDEVMODE
@ref{eb5,,PYTHONDEVMODE}.


Added in version 3.7.


@item 
@code{-X utf8} enables the @ref{a46,,Python UTF-8 Mode}.
@code{-X utf8=0} explicitly disables @ref{a46,,Python UTF-8 Mode}
(even when it would otherwise activate automatically).
See also 
@geindex PYTHONUTF8
@geindex μεταβλητή περιβάλλοντος; PYTHONUTF8
@ref{1ad,,PYTHONUTF8}.


Added in version 3.7.


@item 
@code{-X pycache_prefix=PATH} enables writing @code{.pyc} files to a parallel
tree rooted at the given directory instead of to the code tree. See also
@geindex PYTHONPYCACHEPREFIX
@geindex μεταβλητή περιβάλλοντος; PYTHONPYCACHEPREFIX
@ref{d6c,,PYTHONPYCACHEPREFIX}.


Added in version 3.8.


@item 
@code{-X warn_default_encoding} issues a @ref{231d,,EncodingWarning} when the
locale-specific default encoding is used for opening files.
See also 
@geindex PYTHONWARNDEFAULTENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNDEFAULTENCODING
@ref{b9d,,PYTHONWARNDEFAULTENCODING}.


Added in version 3.10.


@item 
@code{-X no_debug_ranges} disables the inclusion of the tables mapping extra
location information (end line, start column offset and end column offset)
to every instruction in code objects. This is useful when smaller code
objects and pyc files are desired as well as suppressing the extra visual
location indicators when the interpreter displays tracebacks. See also
@geindex PYTHONNODEBUGRANGES
@geindex μεταβλητή περιβάλλοντος; PYTHONNODEBUGRANGES
@ref{9b5,,PYTHONNODEBUGRANGES}.


Added in 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 μεταβλητή περιβάλλοντος; PYTHON_FROZEN_MODULES
@ref{6b6,,PYTHON_FROZEN_MODULES}.


Added in 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 μεταβλητή περιβάλλοντος; PYTHONPERFSUPPORT
@ref{884,,PYTHONPERFSUPPORT} and @ref{6b7,,Python support for the perf map compatible profilers}.


Added in 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 μεταβλητή περιβάλλοντος; PYTHON_PERF_JIT_SUPPORT
@ref{6b8,,PYTHON_PERF_JIT_SUPPORT}
and @ref{6b7,,Python support for the perf map compatible profilers}.


Added in version 3.13.


@item 
@code{-X disable_remote_debug} disables the remote debugging support as described
in 
@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/}.  This includes both the functionality to schedule code for
execution in another process and the functionality to receive code for
execution in the current process.

This option is only available on some platforms and will do nothing
if is not supported on the current system. See also
@geindex PYTHON_DISABLE_REMOTE_DEBUG
@geindex μεταβλητή περιβάλλοντος; PYTHON_DISABLE_REMOTE_DEBUG
@ref{419,,PYTHON_DISABLE_REMOTE_DEBUG} and 
@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/}.


Added in version 3.14.


@item 
@code{-X cpu_count=@var{n}} overrides @ref{6e1,,os.cpu_count()},
@ref{6e0,,os.process_cpu_count()}, and @ref{1319,,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 μεταβλητή περιβάλλοντος; PYTHON_CPU_COUNT
@ref{721,,PYTHON_CPU_COUNT}.
If `n' is @code{default}, nothing is overridden.


Added in version 3.13.


@item 
@code{-X presite=@var{module}} or @code{-X presite=@var{module:func}} specifies
an entry point that should be executed before the @ref{cf,,site} module is
executed and before the
@ref{1,,__main__} module exists.  Therefore, the imported module isn’t
@code{__main__}. This can be used to execute code early during Python
initialization. Python needs to be @ref{3dc,,built in debug mode}
for this option to exist.  See also 
@geindex PYTHON_PRESITE
@geindex μεταβλητή περιβάλλοντος; PYTHON_PRESITE
@ref{18ff,,PYTHON_PRESITE}.


Άλλαξε στην έκδοση 3.15: Accept also @code{module:func} entry point format.



Added in 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{6a5,,--disable-gil}. See also 
@geindex PYTHON_GIL
@geindex μεταβλητή περιβάλλοντος; PYTHON_GIL
@ref{6a6,,PYTHON_GIL} and
@ref{67f,,Free-threaded CPython}.


Added in version 3.13.


@item 
@code{-X thread_inherit_context=@var{0,1}} causes @ref{420,,Thread}
to, by default, use a copy of context of the caller of
@code{Thread.start()} when starting.  Otherwise, threads will start
with an empty context.  If unset, the value of this option defaults
to @code{1} on free-threaded builds and to @code{0} otherwise.  See also
@geindex PYTHON_THREAD_INHERIT_CONTEXT
@geindex μεταβλητή περιβάλλοντος; PYTHON_THREAD_INHERIT_CONTEXT
@ref{1a90,,PYTHON_THREAD_INHERIT_CONTEXT}.


Added in version 3.14.


@item 
@code{-X context_aware_warnings=@var{0,1}} causes the
@ref{423,,warnings.catch_warnings} context manager to use a
@ref{1a9d,,ContextVar} to store warnings filter state.  If
unset, the value of this option defaults to @code{1} on free-threaded builds
and to @code{0} otherwise.  See also 
@geindex PYTHON_CONTEXT_AWARE_WARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHON_CONTEXT_AWARE_WARNINGS
@ref{1a83,,PYTHON_CONTEXT_AWARE_WARNINGS}.


Added in version 3.14.


@item 
@code{-X pathconfig_warnings=@var{0,1}} if true (@code{1}) then
@ref{1953,,The initialization of the sys.path module search path} is allowed to log warnings into stderr.
If false (@code{0}) suppress these warnings. Set to true by default.
See also 
@geindex PYTHON_PATHCONFIG_WARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHON_PATHCONFIG_WARNINGS
@ref{1952,,PYTHON_PATHCONFIG_WARNINGS}.


Added in version 3.15.


@item 
@code{-X tlbc=@var{0,1}} enables (1, the default) or disables (0) thread-local
bytecode in builds configured with @ref{6a5,,--disable-gil}.  When disabled,
this also disables the specializing interpreter.  See also
@geindex PYTHON_TLBC
@geindex μεταβλητή περιβάλλοντος; PYTHON_TLBC
@ref{231e,,PYTHON_TLBC}.


Added in version 3.14.


@item 
@code{-X lazy_imports=@var{all,none,normal}} controls lazy import behavior.
@code{all} makes all imports lazy by default, @code{none} disables lazy imports
entirely (even explicit @code{lazy} statements become eager), and @code{normal}
(the default) respects the @code{lazy} keyword in source code.
See also 
@geindex PYTHON_LAZY_IMPORTS
@geindex μεταβλητή περιβάλλοντος; PYTHON_LAZY_IMPORTS
@ref{179,,PYTHON_LAZY_IMPORTS}.


Added in version 3.15.

@end itemize

It also allows passing arbitrary values and retrieving them through the
@ref{231f,,sys._xoptions} dictionary.


Added in version 3.2.



Άλλαξε στην έκδοση 3.9: Removed the @code{-X showalloccount} option.



Άλλαξε στην έκδοση 3.10: Removed the @code{-X oldparser} option.

@end deffn


Removed in version 3.14: @code{-J} is no longer reserved for use by Jython@footnote{https://www.jython.org/},
and now has no special meaning.


@node Controlling color,,Miscellaneous options,Command line
@anchor{using/cmdline controlling-color}@anchor{2320}@anchor{using/cmdline using-on-controlling-color}@anchor{1af}
@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 μεταβλητή περιβάλλοντος; PYTHON_COLORS
@ref{687,,PYTHON_COLORS} environment variable can be used. This variable takes
precedence over @code{NO_COLOR}, which in turn takes precedence over
@code{FORCE_COLOR}.

@node Environment variables,,Command line,Command line and environment<2>
@anchor{using/cmdline environment-variables}@anchor{2321}@anchor{using/cmdline using-on-envvars}@anchor{9e8}
@subsection Environment variables


These environment variables influence Python’s behavior, they are processed
before the command-line switches other than -E or -I.  It is customary that
command-line switches override environmental variables where there is a
conflict.

@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@anchor{using/cmdline envvar-PYTHONHOME}@anchor{3ad}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONHOME

Change the location of the standard Python libraries.  By default, the
libraries are searched in @code{`prefix'/lib/python`version'} and
@code{`exec_prefix'/lib/python`version'}, where @code{`prefix'} and
@code{`exec_prefix'} are installation-dependent directories, both defaulting
to @code{/usr/local}.

When 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} is set to a single directory, its value replaces
both @code{`prefix'} and @code{`exec_prefix'}.  To specify different values
for these, set 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@code{PYTHONHOME} to @code{`prefix':`exec_prefix'}.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@anchor{using/cmdline envvar-PYTHONPATH}@anchor{13c6}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONPATH

Augment the default search path for module files.  The format is the same as
the shell’s 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}: one or more directory pathnames separated by
@ref{2322,,os.pathsep} (e.g. colons on Unix or semicolons on Windows).
Non-existent directories are silently ignored.

In addition to normal directories, individual 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} entries
may refer to zipfiles containing pure Python modules (in either source or
compiled form). Extension modules cannot be imported from zipfiles.

The default search path is installation dependent, but generally begins with
@code{`prefix'/lib/python`version'} (see 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} above).  It
is `always' appended to 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH}.

An additional directory will be inserted in the search path in front of
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} as described above under
@ref{230a,,Interface options}. The search path can be manipulated from
within a Python program as the variable @ref{194,,sys.path}.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONSAFEPATH
@anchor{using/cmdline envvar-PYTHONSAFEPATH}@anchor{9a4}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONSAFEPATH

If this is set to a non-empty string, don’t prepend a potentially unsafe
path to @ref{194,,sys.path}: see the @ref{9a3,,-P} option for details.


Added in version 3.11.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONPLATLIBDIR
@anchor{using/cmdline envvar-PYTHONPLATLIBDIR}@anchor{1f18}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONPLATLIBDIR

If this is set to a non-empty string, it overrides the @ref{2a9,,sys.platlibdir}
value.


Added in version 3.9.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@anchor{using/cmdline envvar-PYTHONSTARTUP}@anchor{453}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONSTARTUP

If this is the name of a readable file, the Python commands in that file are
executed before the first prompt is displayed in interactive mode.  The file
is executed in the same namespace where interactive commands are executed so
that objects defined or imported in it can be used without qualification in
the interactive session.  You can also change the prompts @ref{2323,,sys.ps1} and
@ref{2324,,sys.ps2} and the hook @ref{1371,,sys.__interactivehook__} in this file.


Raises an @ref{1e65,,auditing event} @code{cpython.run_startup} with
the filename as the argument when called on startup.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONOPTIMIZE
@anchor{using/cmdline envvar-PYTHONOPTIMIZE}@anchor{2314}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONOPTIMIZE

If this is set to a non-empty string it is equivalent to specifying the
@ref{431,,-O} option.  If set to an integer, it is equivalent to specifying
@code{-O} multiple times.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONBREAKPOINT
@anchor{using/cmdline envvar-PYTHONBREAKPOINT}@anchor{ea0}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONBREAKPOINT

If this is set, it names a callable using dotted-path notation.  The module
containing the callable will be imported and then the callable will be run
by the default implementation of @ref{e9f,,sys.breakpointhook()} which itself is
called by built-in @ref{4f9,,breakpoint()}.  If not set, or set to the empty
string, it is equivalent to the value «pdb.set_trace».  Setting this to the
string «0» causes the default implementation of @code{sys.breakpointhook()}
to do nothing but return immediately.


Added in version 3.7.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONDEBUG
@anchor{using/cmdline envvar-PYTHONDEBUG}@anchor{2313}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONDEBUG

If this is set to a non-empty string it is equivalent to specifying the
@ref{2312,,-d} option.  If set to an integer, it is equivalent to specifying
@code{-d} multiple times.

This environment variable requires a @ref{3dc,,debug build of Python}, otherwise it’s ignored.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONINSPECT
@anchor{using/cmdline envvar-PYTHONINSPECT}@anchor{187c}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONINSPECT

If this is set to a non-empty string it is equivalent to specifying the
@ref{187d,,-i} option.

This variable can also be modified by Python code using @ref{4e5,,os.environ}
to force inspect mode on program termination.

Raises an @ref{1e65,,auditing event} @code{cpython.run_stdin} with no arguments.


Άλλαξε στην έκδοση 3.12.5: (also 3.11.10, 3.10.15, 3.9.20, and 3.8.20)
Emits audit events.



Άλλαξε στην έκδοση 3.13: Uses PyREPL if possible, in which case 
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP} is
also executed. Emits audit events.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONUNBUFFERED
@anchor{using/cmdline envvar-PYTHONUNBUFFERED}@anchor{1f80}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONUNBUFFERED

If this is set to a non-empty string it is equivalent to specifying the
@ref{1f7f,,-u} option.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONVERBOSE
@anchor{using/cmdline envvar-PYTHONVERBOSE}@anchor{2317}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONVERBOSE

If this is set to a non-empty string it is equivalent to specifying the
@ref{17c7,,-v} option.  If set to an integer, it is equivalent to specifying
@code{-v} multiple times.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONCASEOK
@anchor{using/cmdline envvar-PYTHONCASEOK}@anchor{d26}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONCASEOK

If this is set, Python ignores case in @ref{9da,,import} statements.  This
only works on Windows and macOS.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONDONTWRITEBYTECODE
@anchor{using/cmdline envvar-PYTHONDONTWRITEBYTECODE}@anchor{1771}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONDONTWRITEBYTECODE

If this is set to a non-empty string, Python won’t try to write @code{.pyc}
files on the import of source modules.  This is equivalent to
specifying the @ref{1770,,-B} option.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONPYCACHEPREFIX
@anchor{using/cmdline envvar-PYTHONPYCACHEPREFIX}@anchor{d6c}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONPYCACHEPREFIX

If this is set, Python will write @code{.pyc} files in a mirror directory tree
at this path, instead of in @code{__pycache__} directories within the source
tree. This is equivalent to specifying the @ref{178,,-X}
@code{pycache_prefix=PATH} option.


Added in version 3.8.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONHASHSEED
@anchor{using/cmdline envvar-PYTHONHASHSEED}@anchor{1425}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONHASHSEED

If this variable is not set or set to @code{random}, a random value is used
to seed the hashes of str and bytes objects.

If 
@geindex PYTHONHASHSEED
@geindex μεταβλητή περιβάλλοντος; PYTHONHASHSEED
@ref{1425,,PYTHONHASHSEED} is set to an integer value, it is used as a fixed
seed for generating the hash() of the types covered by the hash
randomization.

Its purpose is to allow repeatable hashing, such as for selftests for the
interpreter itself, or to allow a cluster of python processes to share hash
values.

The integer must be a decimal number in the range [0,4294967295].  Specifying
the value 0 will disable hash randomization.


Added in version 3.2.3.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONINTMAXSTRDIGITS
@anchor{using/cmdline envvar-PYTHONINTMAXSTRDIGITS}@anchor{1d38}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONINTMAXSTRDIGITS

If this variable is set to an integer, it is used to configure the
interpreter’s global @ref{9ec,,integer string conversion length limitation}.


Added in version 3.11.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONIOENCODING
@anchor{using/cmdline envvar-PYTHONIOENCODING}@anchor{13b3}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONIOENCODING

If this is set before running the interpreter, it overrides the encoding used
for stdin/stdout/stderr, in the syntax @code{encodingname:errorhandler}.  Both
the @code{encodingname} and the @code{:errorhandler} parts are optional and have
the same meaning as in @ref{ca7,,str.encode()}.

For stderr, the @code{:errorhandler} part is ignored; the handler will always be
@code{'backslashreplace'}.


Άλλαξε στην έκδοση 3.4: The @code{encodingname} part is now optional.



Άλλαξε στην έκδοση 3.6: On Windows, the encoding specified by this variable is ignored for interactive
console buffers unless 
@geindex PYTHONLEGACYWINDOWSSTDIO
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSSTDIO
@ref{1019,,PYTHONLEGACYWINDOWSSTDIO} is also specified.
Files and pipes redirected through the standard streams are not affected.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONNOUSERSITE
@anchor{using/cmdline envvar-PYTHONNOUSERSITE}@anchor{1733}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONNOUSERSITE

This is equivalent to the @ref{1732,,-s} option.  If this is set, Python won’t
add the @ref{2315,,user site-packages directory} to
@ref{194,,sys.path}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 370
PEP 370@footnote{https://peps.python.org/pep-0370/} – Per user site-packages directory

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONUSERBASE
@anchor{using/cmdline envvar-PYTHONUSERBASE}@anchor{1731}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONUSERBASE

Defines the @ref{16c1,,user base directory}, which is used to
compute the path of the @ref{2315,,user site-packages directory}
and @ref{2325,,installation paths} for
@code{python -m pip install --user}.

To disable the user site-packages, see 
@geindex PYTHONNOUSERSITE
@geindex μεταβλητή περιβάλλοντος; PYTHONNOUSERSITE
@ref{1733,,PYTHONNOUSERSITE} or the @ref{1732,,-s}
option.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 370
PEP 370@footnote{https://peps.python.org/pep-0370/} – Per user site-packages directory

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONEXECUTABLE
@anchor{using/cmdline envvar-PYTHONEXECUTABLE}@anchor{2326}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONEXECUTABLE

If this environment variable is set, @code{sys.argv[0]} will be set to its
value instead of the value got through the C runtime.  Only works on
macOS.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@anchor{using/cmdline envvar-PYTHONWARNINGS}@anchor{1c1}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONWARNINGS

This is equivalent to the @ref{1c0,,-W} option. If set to a comma
separated string, it is equivalent to specifying @code{-W} multiple
times, with filters later in the list taking precedence over those earlier
in the list.

The simplest settings apply a particular action unconditionally to all
warnings emitted by a process (even those that are otherwise ignored by
default):

@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

See @ref{1cc,,Το Φίλτρο Προειδοποιήσεων} and @ref{2319,,Περιγραφή Φίλτρων Προειδοποιήσεων} for more
details.


Άλλαξε στην έκδοση 3.15: Added regular expression support for `message' and `module'.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONFAULTHANDLER
@anchor{using/cmdline envvar-PYTHONFAULTHANDLER}@anchor{142d}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONFAULTHANDLER

If this environment variable is set to a non-empty string,
@ref{219,,faulthandler.enable()} is called at startup: install a handler for
@ref{1428,,SIGSEGV}, @ref{1429,,SIGFPE},
@ref{142a,,SIGABRT}, @ref{142b,,SIGBUS} and
@ref{142c,,SIGILL} signals to dump the Python traceback.
This is equivalent to @ref{178,,-X} @code{faulthandler} option.


Added in version 3.3.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONTRACEMALLOC
@anchor{using/cmdline envvar-PYTHONTRACEMALLOC}@anchor{231c}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONTRACEMALLOC

If this environment variable is set to a non-empty string, start tracing
Python memory allocations using the @ref{108,,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{231b,,tracemalloc.start()} function for more information.
This is equivalent to setting the @ref{178,,-X} @code{tracemalloc} option.


Added in version 3.4.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONPROFILEIMPORTTIME
@anchor{using/cmdline envvar-PYTHONPROFILEIMPORTTIME}@anchor{ebb}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONPROFILEIMPORTTIME

If this environment variable is set to @code{1}, Python will show
how long each import takes. If set to @code{2}, Python will include output for
imported modules that have already been loaded.
This is equivalent to setting the @ref{178,,-X} @code{importtime} option.


Added in version 3.7.



Άλλαξε στην έκδοση 3.14: Added @code{PYTHONPROFILEIMPORTTIME=2} to also trace imports of loaded modules.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONASYNCIODEBUG
@anchor{using/cmdline envvar-PYTHONASYNCIODEBUG}@anchor{2327}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONASYNCIODEBUG

If this environment variable is set to a non-empty string, enable the
@ref{2328,,debug mode} of the @ref{b,,asyncio} module.


Added in version 3.4.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOC
@anchor{using/cmdline envvar-PYTHONMALLOC}@anchor{1022}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONMALLOC

Set the Python memory allocators and/or install debug hooks.

Set the family of memory allocators used by Python:


@itemize *

@item 
@code{default}: use the @ref{2329,,default memory allocators}.

@item 
@code{malloc}: use the @code{malloc()} function of the C library
for all domains (@ref{232a,,PYMEM_DOMAIN_RAW}, @ref{1027,,PYMEM_DOMAIN_MEM},
@ref{1025,,PYMEM_DOMAIN_OBJ}).

@item 
@code{pymalloc}: use the @ref{3da,,pymalloc allocator} for
@ref{1027,,PYMEM_DOMAIN_MEM} and @ref{1025,,PYMEM_DOMAIN_OBJ} domains and use
the @code{malloc()} function for the @ref{232a,,PYMEM_DOMAIN_RAW} domain.

@item 
@code{mimalloc}: use the @ref{232b,,mimalloc allocator} for
@ref{1027,,PYMEM_DOMAIN_MEM} and @ref{1025,,PYMEM_DOMAIN_OBJ} domains and use
the @code{malloc()} function for the @ref{232a,,PYMEM_DOMAIN_RAW} domain.
@end itemize

Install @ref{232c,,debug hooks}:


@itemize *

@item 
@code{debug}: install debug hooks on top of the @ref{2329,,default memory allocators}.

@item 
@code{malloc_debug}: same as @code{malloc} but also install debug hooks.

@item 
@code{pymalloc_debug}: same as @code{pymalloc} but also install debug hooks.

@item 
@code{mimalloc_debug}: same as @code{mimalloc} but also install debug hooks.
@end itemize

@cartouche
@quotation Σημείωση 
In the @ref{487,,free-threaded} build, the @code{malloc},
@code{malloc_debug}, @code{pymalloc}, and @code{pymalloc_debug} values are not
supported.  Only @code{default}, @code{debug}, @code{mimalloc}, and
@code{mimalloc_debug} are accepted.
@end quotation
@end cartouche


Added in version 3.6.



Άλλαξε στην έκδοση 3.7: Added the @code{"default"} allocator.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOCSTATS
@anchor{using/cmdline envvar-PYTHONMALLOCSTATS}@anchor{2124}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONMALLOCSTATS

If set to a non-empty string, Python will print statistics of the
@ref{3da,,pymalloc memory allocator} or the
@ref{232b,,mimalloc memory allocator} (whichever is in use)
every time a new object arena is created, and on shutdown.

This variable is ignored if the 
@geindex PYTHONMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,PYTHONMALLOC} environment variable
is used to force the @code{malloc()} allocator of the C library, or if
Python is configured without both @code{pymalloc} and @code{mimalloc} support.


Άλλαξε στην έκδοση 3.6: This variable can now also be used on Python compiled in release mode.
It now has no effect if set to an empty string.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_PYMALLOC_HUGEPAGES
@anchor{using/cmdline envvar-PYTHON_PYMALLOC_HUGEPAGES}@anchor{3db}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_PYMALLOC_HUGEPAGES

If set to a non-zero integer, enable huge page support for
@ref{3da,,pymalloc} arenas.  Set to @code{0} or unset to disable.
Python must be compiled with @ref{3d9,,--with-pymalloc-hugepages} for this
variable to have any effect.

When enabled, arena allocation uses @code{MAP_HUGETLB} (Linux) or
@code{MEM_LARGE_PAGES} (Windows) with automatic fallback to regular pages if
huge pages are not available.

@cartouche
@quotation Προειδοποίηση 
On Linux, if the huge-page pool is exhausted, page faults — including
copy-on-write faults triggered by @ref{6bd,,os.fork()} — deliver @code{SIGBUS}
and kill the process.  Only enable this in environments where the
huge-page pool is properly sized and fork-safety is not a concern.

On Windows you need a special privilege. See the
Windows documentation for large pages@footnote{https://learn.microsoft.com/windows/win32/memory/large-page-support}
for details. Python will fail on startup if the required privilege
SeLockMemoryPrivilege@footnote{https://learn.microsoft.com/previous-versions/windows/it-pro/windows-10/security/threat-protection/security-policy-settings/lock-pages-in-memory}
is not held by the user.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@anchor{using/cmdline envvar-PYTHONLEGACYWINDOWSFSENCODING}@anchor{30f}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONLEGACYWINDOWSFSENCODING

If set to a non-empty string, the default @ref{948,,filesystem encoding and error handler} mode will revert to their pre-3.6 values of “mbcs” and
“replace”, respectively.  Otherwise, the new defaults “utf-8” and
“surrogatepass” are used.

This may also be enabled at runtime with
@ref{30e,,sys._enablelegacywindowsfsencoding()}.

@ref{232d,,Διαθεσιμότητα}: Windows.


Added in version 3.6: See 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} for more details.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSSTDIO
@anchor{using/cmdline envvar-PYTHONLEGACYWINDOWSSTDIO}@anchor{1019}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONLEGACYWINDOWSSTDIO

If set to a non-empty string, does not use the new console reader and
writer. This means that Unicode characters will be encoded according to
the active console code page, rather than using utf-8.

This variable is ignored if the standard streams are redirected (to files
or pipes) rather than referring to console buffers.

@ref{232d,,Διαθεσιμότητα}: Windows.


Added in version 3.6.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONCOERCECLOCALE
@anchor{using/cmdline envvar-PYTHONCOERCECLOCALE}@anchor{e9b}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONCOERCECLOCALE

If set to the value @code{0}, causes the main Python command line application
to skip coercing the legacy ASCII-based C and POSIX locales to a more
capable UTF-8 based alternative.

If this variable is `not' set (or is set to a value other than @code{0}), the
@code{LC_ALL} locale override environment variable is also not set, and the
current locale reported for the @code{LC_CTYPE} category is either the default
@code{C} locale, or else the explicitly ASCII-based @code{POSIX} locale, then the
Python CLI will attempt to configure the following locales for the
@code{LC_CTYPE} category in the order listed before loading the interpreter
runtime:


@itemize *

@item 
@code{C.UTF-8}

@item 
@code{C.utf8}

@item 
@code{UTF-8}
@end itemize

If setting one of these locale categories succeeds, then the @code{LC_CTYPE}
environment variable will also be set accordingly in the current process
environment before the Python runtime is initialized. This ensures that in
addition to being seen by both the interpreter itself and other locale-aware
components running in the same process (such as the GNU @code{readline}
library), the updated setting is also seen in subprocesses (regardless of
whether or not those processes are running a Python interpreter), as well as
in operations that query the environment rather than the current C locale
(such as Python’s own @ref{233,,locale.getdefaultlocale()}).

Configuring one of these locales (either explicitly or via the above
implicit locale coercion) automatically enables the @code{surrogateescape}
@ref{1d6c,,error handler} for @ref{94a,,sys.stdin} and
@ref{e9c,,sys.stdout} (@ref{d05,,sys.stderr} continues to use @code{backslashreplace}
as it does in any other locale). This stream handling behavior can be
overridden using 
@geindex PYTHONIOENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONIOENCODING
@ref{13b3,,PYTHONIOENCODING} as usual.

For debugging purposes, setting @code{PYTHONCOERCECLOCALE=warn} will cause
Python to emit warning messages on @code{stderr} if either the locale coercion
activates, or else if a locale that `would' have triggered coercion is
still active when the Python runtime is initialized.

Also note that even when locale coercion is disabled, or when it fails to
find a suitable target locale, 
@geindex PYTHONUTF8
@geindex μεταβλητή περιβάλλοντος; PYTHONUTF8
@ref{1ad,,PYTHONUTF8} will still activate by
default in legacy ASCII-based locales. Both features must be disabled in
order to force the interpreter to use @code{ASCII} instead of @code{UTF-8} for
system interfaces.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.7: See 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/} for more details.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONDEVMODE
@anchor{using/cmdline envvar-PYTHONDEVMODE}@anchor{eb5}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONDEVMODE

If this environment variable is set to a non-empty string, enable
@ref{70d,,Python Development Mode}, introducing additional runtime
checks that are too expensive to be enabled by default.
This is equivalent to setting the @ref{178,,-X} @code{dev} option.


Added in version 3.7.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONUTF8
@anchor{using/cmdline envvar-PYTHONUTF8}@anchor{1ad}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONUTF8

If set to @code{1}, enable the @ref{a46,,Python UTF-8 Mode}.

If set to @code{0}, disable the @ref{a46,,Python UTF-8 Mode}.

Setting any other non-empty string causes an error during interpreter
initialisation.


Added in version 3.7.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONWARNDEFAULTENCODING
@anchor{using/cmdline envvar-PYTHONWARNDEFAULTENCODING}@anchor{b9d}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONWARNDEFAULTENCODING

If this environment variable is set to a non-empty string, issue a
@ref{231d,,EncodingWarning} when the locale-specific default encoding is used.

See @ref{1ac,,Opt-in EncodingWarning} for details.


Added in version 3.10.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONNODEBUGRANGES
@anchor{using/cmdline envvar-PYTHONNODEBUGRANGES}@anchor{9b5}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONNODEBUGRANGES

If this variable is set, it disables the inclusion of the tables mapping
extra location information (end line, start column offset and end column
offset) to every instruction in code objects. This is useful when smaller
code objects and pyc files are desired as well as suppressing the extra visual
location indicators when the interpreter displays tracebacks.


Added in version 3.11.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONPERFSUPPORT
@anchor{using/cmdline envvar-PYTHONPERFSUPPORT}@anchor{884}
@deffn {Μεταβλητή Περιβάλλοντος} 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{178,,-X perf} command-line option
and @ref{6b7,,Python support for the perf map compatible profilers}.


Added in version 3.12.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_PERF_JIT_SUPPORT
@anchor{using/cmdline envvar-PYTHON_PERF_JIT_SUPPORT}@anchor{6b8}
@deffn {Μεταβλητή Περιβάλλοντος} 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{178,,-X perf_jit} command-line option
and @ref{6b7,,Python support for the perf map compatible profilers}.


Added in version 3.13.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_DISABLE_REMOTE_DEBUG
@anchor{using/cmdline envvar-PYTHON_DISABLE_REMOTE_DEBUG}@anchor{419}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_DISABLE_REMOTE_DEBUG

If this variable is set to a non-empty string, it disables the remote
debugging feature described in 
@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/}. This includes both the functionality
to schedule code for execution in another process and the functionality to
receive code for execution in the current process.

See also the @ref{178,,-X disable_remote_debug} command-line option.


Added in version 3.14.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_CPU_COUNT
@anchor{using/cmdline envvar-PYTHON_CPU_COUNT}@anchor{721}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_CPU_COUNT

If this variable is set to a positive integer, it overrides the return
values of @ref{6e1,,os.cpu_count()} and @ref{6e0,,os.process_cpu_count()}.

See also the @ref{178,,-X cpu_count} command-line option.


Added in version 3.13.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_FROZEN_MODULES
@anchor{using/cmdline envvar-PYTHON_FROZEN_MODULES}@anchor{6b6}
@deffn {Μεταβλητή Περιβάλλοντος} 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{178,,-X frozen_modules} command-line option.


Added in version 3.13.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_COLORS
@anchor{using/cmdline envvar-PYTHON_COLORS}@anchor{687}
@deffn {Μεταβλητή Περιβάλλοντος} 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{1af,,Controlling color}.


Added in version 3.13.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_BASIC_REPL
@anchor{using/cmdline envvar-PYTHON_BASIC_REPL}@anchor{452}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_BASIC_REPL

If this variable is set to any value, the interpreter will not attempt to
load the Python-based @ref{69d,,REPL} that requires @ref{c2,,readline}, and will
instead use the traditional parser-based REPL.


Added in version 3.13.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_BASIC_COMPLETER
@anchor{using/cmdline envvar-PYTHON_BASIC_COMPLETER}@anchor{1d6}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_BASIC_COMPLETER

If this variable is set to any value, PyREPL will use @ref{c5,,rlcompleter} to
implement tab completion, instead of the default one which uses colors.


Added in version 3.15.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_HISTORY
@anchor{using/cmdline envvar-PYTHON_HISTORY}@anchor{6b9}
@deffn {Μεταβλητή Περιβάλλοντος} 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).


Added in version 3.13.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_GIL
@anchor{using/cmdline envvar-PYTHON_GIL}@anchor{6a6}
@deffn {Μεταβλητή Περιβάλλοντος} 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{6a5,,--disable-gil} build option).

See also the @ref{178,,-X gil} command-line option, which takes
precedence over this variable, and @ref{67f,,Free-threaded CPython}.


Added in version 3.13.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_THREAD_INHERIT_CONTEXT
@anchor{using/cmdline envvar-PYTHON_THREAD_INHERIT_CONTEXT}@anchor{1a90}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_THREAD_INHERIT_CONTEXT

If this variable is set to @code{1} then @ref{420,,Thread} will,
by default, use a copy of context of the caller of @code{Thread.start()}
when starting.  Otherwise, new threads will start with an empty context.
If unset, this variable defaults to @code{1} on free-threaded builds and to
@code{0} otherwise.  See also @ref{178,,-X thread_inherit_context}.


Added in version 3.14.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_CONTEXT_AWARE_WARNINGS
@anchor{using/cmdline envvar-PYTHON_CONTEXT_AWARE_WARNINGS}@anchor{1a83}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_CONTEXT_AWARE_WARNINGS

If set to @code{1} then the @ref{423,,warnings.catch_warnings} context
manager will use a @ref{1a9d,,ContextVar} to store warnings
filter state.  If unset, this variable defaults to @code{1} on
free-threaded builds and to @code{0} otherwise.  See @ref{178,,-X context_aware_warnings}.


Added in version 3.14.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_PATHCONFIG_WARNINGS
@anchor{using/cmdline envvar-PYTHON_PATHCONFIG_WARNINGS}@anchor{1952}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_PATHCONFIG_WARNINGS

If true (@code{1}) then @ref{1953,,The initialization of the sys.path module search path} is allowed to log warnings into
stderr. If false (@code{0}) suppress these warnings. Set to true by default.
See also @ref{178,,-X pathconfig_warnings}.


Added in version 3.15.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_JIT
@anchor{using/cmdline envvar-PYTHON_JIT}@anchor{660}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_JIT

On builds where experimental just-in-time compilation is available, this
variable can force the JIT to be disabled (@code{0}) or enabled (@code{1}) at
interpreter startup.


Added in version 3.13.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_TLBC
@anchor{using/cmdline envvar-PYTHON_TLBC}@anchor{231e}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_TLBC

If set to @code{1} enables thread-local bytecode. If set to @code{0} thread-local
bytecode and the specializing interpreter are disabled.  Only applies to
builds configured with @ref{6a5,,--disable-gil}.

See also the @ref{178,,-X tlbc} command-line option.


Added in version 3.14.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_LAZY_IMPORTS
@anchor{using/cmdline envvar-PYTHON_LAZY_IMPORTS}@anchor{179}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_LAZY_IMPORTS

Controls lazy import behavior. Accepts three values: @code{all} makes all
imports lazy by default, @code{none} disables lazy imports entirely (even
explicit @code{lazy} statements become eager), and @code{normal} (the default)
respects the @code{lazy} keyword in source code.

See also the @ref{178,,-X lazy_imports} command-line option.


Added in version 3.15.

@end deffn

@menu
* Debug-mode variables:: 

@end menu

@node Debug-mode variables,,,Environment variables
@anchor{using/cmdline debug-mode-variables}@anchor{232e}
@subsubsection Debug-mode variables


@geindex μεταβλητή περιβάλλοντος; PYTHONDUMPREFS
@anchor{using/cmdline envvar-PYTHONDUMPREFS}@anchor{d6f}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONDUMPREFS

If set, Python will dump objects and reference counts still alive after
shutting down the interpreter.

Needs Python configured with the @ref{828,,--with-trace-refs} build option.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHONDUMPREFSFILE
@anchor{using/cmdline envvar-PYTHONDUMPREFSFILE}@anchor{1e36}
@deffn {Μεταβλητή Περιβάλλοντος} 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{828,,--with-trace-refs} build option.


Added in version 3.11.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PYTHON_PRESITE
@anchor{using/cmdline envvar-PYTHON_PRESITE}@anchor{18ff}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_PRESITE

If this variable is set to a module, that module will be imported
early in the interpreter lifecycle, before the @ref{cf,,site} module is
executed, and before the @ref{1,,__main__} module is created.
Therefore, the imported module is not treated as @code{__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{178,,-X presite} command-line option,
which takes precedence over this variable.

Needs Python configured with the @ref{853,,--with-pydebug} build option.


Άλλαξε στην έκδοση 3.15: Accept also @code{module:func} entry point format.



Added in version 3.13.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Χρήση της Python σε πλατφόρμες Unix,Configure Python,Command line and environment<2>,Ρύθμιση και Χρήση της Python
@anchor{using/unix doc}@anchor{232f}@anchor{using/unix translation-repo}@anchor{2330}@anchor{using/unix using-on-unix}@anchor{2331}@anchor{using/unix using-python-on-unix-platforms}@anchor{2332}
@section Χρήση της Python σε πλατφόρμες Unix


@menu
* Λήψη και εγκατάσταση της πιο πρόσφατης έκδοσης Python:: 
* Μεταγλώττιση της Python:: 
* Διαδρομές και αρχεία που σχετίζονται με την Python:: 
* Διάφορα:: 
* Custom OpenSSL:: 

@end menu

@node Λήψη και εγκατάσταση της πιο πρόσφατης έκδοσης Python,Μεταγλώττιση της Python,,Χρήση της Python σε πλατφόρμες Unix
@anchor{using/unix getting-and-installing-the-latest-version-of-python}@anchor{2333}
@subsection Λήψη και εγκατάσταση της πιο πρόσφατης έκδοσης Python


@menu
* Σε Linux:: 
* Σε FreeBSD και OpenBSD:: 

@end menu

@node Σε Linux,Σε FreeBSD και OpenBSD,,Λήψη και εγκατάσταση της πιο πρόσφατης έκδοσης Python
@anchor{using/unix on-linux}@anchor{2334}
@subsubsection Σε Linux


Η Python είναι προεγκατεστημένη στις περισσότερες διανομές Linux, ενώ διατίθεται ως πακέτο σε όλες τις υπόλοιπες.  Ωστόσο, υπάρχουν ορισμένα χαρακτηριστικά που μπορεί να θέλετε να χρησιμοποιήσετε, τα οποία δεν είναι διαθέσιμα στο πακέτο της διανομής σας.  Μπορείτε να κάνετε compile την πιο πρόσφατη έκδοση της Python από τον πηγαίο κώδικα.

Στην περίπτωση που η πιο πρόσφατη έκδοση Python δεν είναι προεγκατεστημένη και επίσης δεν ανήκει στα αποθετήρια, μπορείτε να δημιουργήσετε πακέτα για τη δική σας διανομή.  Δείτε τα παρακάτω links:


@subsubheading Δείτε επίσης



@table @asis

@item @indicateurl{https://www.debian.org/doc/manuals/maint-guide/first.en.html}

για τους χρήστες του Debian

@item @indicateurl{https://en.opensuse.org/Portal:Packaging}

για τους χρήστες του OpenSuse

@item @indicateurl{https://docs.fedoraproject.org/en-US/package-maintainers/Packaging_Tutorial_GNU_Hello/}

για τους χρήστες του Fedora

@item @indicateurl{https://slackbook.org/html/package-management-making-packages.html}

για τους χρήστες του Slackware
@end table


@menu
* Εγκατάσταση του IDLE:: 

@end menu

@node Εγκατάσταση του IDLE,,,Σε Linux
@anchor{using/unix installing-idle}@anchor{2335}@anchor{using/unix installing-idle-on-linux}@anchor{2336}
@subsubsection Εγκατάσταση του IDLE


Σε μερικές περιπτώσεις, το IDLE μπορεί να μην περιλαμβάνεται στην εγκατάσταση της Python.


@itemize *

@item 
Για τους χρήστες του Debian και του Ubuntu:

@example
sudo apt update
sudo apt install idle
@end example

@item 
Για τους χρήστες των Fedora, RHEL, και CentOS:

@example
sudo dnf install python3-idle
@end example

@item 
Για τους χρήστες των SUSE και OpenSUSE:

@example
sudo zypper install python3-idle
@end example

@item 
Για τους χρήστες του Alpine Linux:

@example
sudo apk add python3-idle
@end example
@end itemize

@node Σε FreeBSD και OpenBSD,,Σε Linux,Λήψη και εγκατάσταση της πιο πρόσφατης έκδοσης Python
@anchor{using/unix on-freebsd-and-openbsd}@anchor{2337}
@subsubsection Σε FreeBSD και OpenBSD



@itemize *

@item 
Χρήστες του FreeBSD, για την προσθήκη του πακέτου χρησιμοποιήστε:

@example
pkg install python3
@end example

@item 
Χρήστες του OpenBSD, για την προσθήκη του πακέτου χρησιμοποιήστε:

@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

Για παράδειγμα, χρήστες του i386 κάνουν λήψη της έκδοσης 2.5.1 χρησιμοποιώντας:

@example
pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/i386/python-2.5.1p2.tgz
@end example
@end itemize

@node Μεταγλώττιση της Python,Διαδρομές και αρχεία που σχετίζονται με την Python,Λήψη και εγκατάσταση της πιο πρόσφατης έκδοσης Python,Χρήση της Python σε πλατφόρμες Unix
@anchor{using/unix building-python}@anchor{2338}@anchor{using/unix building-python-on-unix}@anchor{12a4}
@subsection Μεταγλώττιση της Python



@subsubheading Δείτε επίσης


Αν θέλετε να συνεισφέρετε στο CPython, ανατρέξτε στον devguide@footnote{https://devguide.python.org/getting-started/setup-building/}, που περιλαμβάνει οδηγίες μεταγλώττισης και άλλες συμβουλές για τη ρύθμιση του περιβάλλοντος.


Αν θέλετε να κάνετε compile το CPython μόνοι σας, το πρώτο πράγμα που πρέπει να κάνετε είναι να πάρετε τον πηγαίο κώδικα@footnote{https://www.python.org/downloads/source/}. Μπορείτε να κατεβάσετε είτε τον πηγαίο κώδικα της τελευταίας έκδοσης είτε απλά να πάρετε έναν καινούργιο clone@footnote{https://devguide.python.org/setup/#get-the-source-code}.  Θα χρειαστεί επίσης να εγκαταστήσετε τις @ref{2339,,build requirements}.

Η διαδικασία της μεταγλώττισης απαρτίζεται από τις συνήθεις εντολές:

@example
./configure
make
make install
@end example

Το @ref{233a,,Configuration options} και οι όροι για συγκεκριμένες πλατφόρμες Unix τεκμηριώνονται εκτενώς στο αρχείο README.rst@footnote{https://github.com/python/cpython/tree/main/README.rst} στην βάση του πηγαίου δέντρου της Python.

@cartouche
@quotation Προειδοποίηση 
Το @code{make install} μπορεί να αντικαταστήσει ή να μεταμφιέσει το @code{python3} σε δυαδικό. Επομένως προτείνεται το @code{make altinstall} σε σχέση με το @code{make install} που μπορεί να εγκαταστήσει μόνο το @code{`exec_prefix'/bin/python`version'}.
@end quotation
@end cartouche

@node Διαδρομές και αρχεία που σχετίζονται με την Python,Διάφορα,Μεταγλώττιση της Python,Χρήση της Python σε πλατφόρμες Unix
@anchor{using/unix python-related-paths-and-files}@anchor{233b}
@subsection Διαδρομές και αρχεία που σχετίζονται με την Python


Αυτά ενδέχεται να διαφέρουν ανάλογα με τις τοπικές συμβάσεις εγκατάστασης∙ τα @ref{233c,,prefix} και @ref{233d,,exec_prefix} εξαρτώνται από την εγκατάσταση και θα πρέπει να ερμηνεύονται όπως για το λογισμικό GNU∙ μπορεί να είναι τα ίδια.

Για παράδειγμα, στα περισσότερα Linux συστήματα, η προεπιλογή είναι και για τα δύο @code{/usr}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

File/directory

@tab

Που σημαίνει

@item

@code{`exec_prefix'/bin/python3}

@tab

Προτεινόμενη θέση του διερμηνέα.

@item

@code{`prefix'/lib/python`version'},
@code{`exec_prefix'/lib/python`version'}

@tab

Προτεινόμενες θέσεις για τους καταλόγους που περιέχουν τα βασικά modules.

@item

@code{`prefix'/include/python`version'},
@code{`exec_prefix'/include/python`version'}

@tab

Προτεινόμενες θέσεις των καταλόγων που περιέχουν τα αρχεία κεφαλίδων (include files) που απαιτούνται για την ανάπτυξη επεκτάσεων της Python και την ενσωμάτωση του διερμηνέα.

@end multitable


@node Διάφορα,Custom OpenSSL,Διαδρομές και αρχεία που σχετίζονται με την Python,Χρήση της Python σε πλατφόρμες Unix
@anchor{using/unix miscellaneous}@anchor{233e}
@subsection Διάφορα


Για να εκτελείτε εύκολα τα Python scripts σε συστήματα Unix, πρέπει να τα κάνετε εκτελέσιμα, για παράδειγμα με

@example
$ chmod +x script
@end example

και να προσθέσετε μια κατάλληλη γραμμή Shebang στην αρχή του script.  Μια καλή επιλογή είναι συνήθως

@example
#!/usr/bin/env python3
@end example

που κάνει αναζήτηση για τον διερμηνέα της Python σε ολόκληρο το 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}.  Ωστόσο, ορισμένα Unices μπορεί να μην έχουν την εντολή @code{env}, οπότε μπορεί να χρειαστεί να κωδικοποιήσετε το @code{/usr/bin/python3} ως διαδρομή του διερμηνέα.

Για να χρησιμοποιήσετε εντολές shell στα Python script σας, δείτε την ενότητα @ref{df,,subprocess}.

@node Custom OpenSSL,,Διάφορα,Χρήση της Python σε πλατφόρμες Unix
@anchor{using/unix custom-openssl}@anchor{233f}@anchor{using/unix unix-custom-openssl}@anchor{2340}
@subsection Custom OpenSSL



@enumerate 

@item 
Για να χρησιμοποιήσετε τις ρυθμίσεις του OpenSSL και το αποθετήριο εμπιστοσύνης συστήματος, εντοπίστε τον κατάλογο με το αρχείο @code{openssl.cnf} ή τον συμβολικό σύνδεσμο στο @code{/etc}. Στις περισσότερες διανομές το αρχείο βρίσκεται είτε στο @code{/etc/ssl} είτε στο @code{/etc/pki/tls}. Ο κατάλογος θα πρέπει επίσης να περιέχει ένα αρχείο @code{cert.pem} και/ή έναν κατάλογο @code{certs}.

@example
$ find /etc/ -name openssl.cnf -printf "%h\n"
/etc/ssl
@end example

@item 
Λήψη, δημιουργία και εγκατάσταση του OenSSL. Βεβαιωθείτε ότι χρησιμοποιείτε το @code{install_sw} και όχι το @code{install}. Ο στόχος @code{install_sw} δεν παρακάμπτει το αρχείο @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 
Μεταγλώττιση της Python με προσαρμοσμένο OpenSSL (δείτε τις επιλογές configure @code{----with-openssl} και @code{----with-openssl-rpath})

@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 Σημείωση 
Οι διορθωτικές εκδόσεις του OpenSSL έχουν μια δυαδική διεπαφή εφαρμογής (ABI) συμβατή προς τα πίσω. Δεν χρειάζεται να κάνετε compile εκ νέου την Python για να ενημερώσετε το OpenSSL. Αρκεί να αντικαταστήσετε την προσαρμοσμένη εγκατάσταση του OpenSSL με μια νεότερη έκδοση.
@end quotation
@end cartouche

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Configure Python,Χρησιμοποιώντας Python στα Windows,Χρήση της Python σε πλατφόρμες Unix,Ρύθμιση και Χρήση της Python
@anchor{using/configure doc}@anchor{2341}@anchor{using/configure configure-python}@anchor{2342}@anchor{using/configure translation-repo}@anchor{2343}
@section Configure Python


@menu
* Build Requirements:: 
* Generated files:: 
* Configure Options:: 
* Python Build System:: 
* Compiler and linker flags:: 

@end menu

@node Build Requirements,Generated files,,Configure Python
@anchor{using/configure build-requirements}@anchor{2339}@anchor{using/configure id1}@anchor{2344}
@subsection Build Requirements


To build CPython, you will need:


@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.
@end itemize


Άλλαξε στην έκδοση 3.5: On Windows, Visual Studio 2015 or later is now required.



Άλλαξε στην έκδοση 3.6: Selected C99 features, like @code{<stdint.h>} and @code{static inline} functions,
are now required.



Άλλαξε στην έκδοση 3.7: Thread support is now required.



Άλλαξε στην έκδοση 3.11: C11 compiler, IEEE 754 and NaN support are now required.
On Windows, Visual Studio 2017 or later is 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».

@menu
* Requirements for optional modules:: 

@end menu

@node Requirements for optional modules,,,Build Requirements
@anchor{using/configure optional-module-requirements}@anchor{2345}@anchor{using/configure requirements-for-optional-modules}@anchor{2346}
@subsubsection Requirements for optional modules


Some @ref{2347,,optional modules} of the standard library
require third-party libraries installed for development
(for example, header files must be available).

Missing requirements are reported in the @code{configure} output.
Modules that are missing due to missing dependencies are listed near the end
of the @code{make} output,
sometimes using an internal name, for example, @code{_ctypes} for @ref{2d,,ctypes}
module.

If you distribute a CPython interpreter without optional modules,
it’s best practice to advise users, who generally expect that
standard library modules are available.

Dependencies to build optional modules are:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Dependency

@tab

Minimum version

@tab

Python module

@item

libbz2@footnote{https://sourceware.org/bzip2/}

@tab

@tab

@ref{14,,bz2}

@item

libffi@footnote{https://sourceware.org/libffi/}

@tab

3.3.0 recommended

@tab

@ref{2d,,ctypes}

@item

liblzma@footnote{https://tukaani.org/xz/}

@tab

@tab

@ref{8d,,lzma}

@item

libmpdec@footnote{https://www.bytereef.org/mpdecimal/doc/libmpdec/}

@tab

2.5.0

@tab

@ref{39,,decimal} @footnote{
If `libmpdec' is not available, the @ref{39,,decimal} module will use
a pure-Python implementation.
See @ref{3d6,,--with-system-libmpdec} for details.
}

@item

libreadline@footnote{https://tiswww.case.edu/php/chet/readline/rltop.html} or
libedit@footnote{https://www.thrysoee.dk/editline/} @footnote{
See @ref{2348,,--with-readline} for choosing the backend for the
@ref{c2,,readline} module.
}

@tab

@tab

@ref{c2,,readline}

@item

libuuid@footnote{https://linux.die.net/man/3/libuuid}

@tab

@tab

@code{_uuid} @footnote{
The @ref{119,,uuid} module uses @code{_uuid} to generate «safe» UUIDs.
See the module documentation for details.
}

@item

ncurses@footnote{https://gnu.org/software/ncurses/ncurses.html} @footnote{
The @ref{2e,,curses} module requires the @code{libncurses} or @code{libncursesw}
library.
The @ref{30,,curses.panel} module additionally requires the @code{libpanel} or
@code{libpanelw} library.
}

@tab

@tab

@ref{2e,,curses}

@item

OpenSSL@footnote{https://openssl-library.org/}

@tab


@display
3.0.18 recommended@w{ }
(1.1.1 minimum)@w{ }
@end display



@tab

@ref{d8,,ssl}, @ref{6b,,hashlib} @footnote{
If OpenSSL is not available, the @ref{6b,,hashlib} module will use
bundled implementations of several hash functions.
See @ref{2349,,--with-builtin-hashlib-hashes} for `forcing' usage of OpenSSL.
}

@item

SQLite@footnote{https://sqlite.org/}

@tab

3.15.2

@tab

@ref{d7,,sqlite3}

@item

Tcl/Tk@footnote{https://www.tcl-lang.org/}

@tab

8.5.12

@tab

@ref{f9,,tkinter}, @ref{13be,,IDLE}, @ref{10a,,turtle}

@item

zlib@footnote{https://www.zlib.net}

@tab

1.2.2.1

@tab

@ref{13c,,zlib}, @ref{6a,,gzip}, @ref{58,,ensurepip}

@item

zstd@footnote{https://facebook.github.io/zstd/}

@tab

1.4.5

@tab

@ref{23,,compression.zstd}

@end multitable


Note that the table does not include all optional modules; in particular,
platform-specific modules like @ref{11f,,winreg} are not listed here.


@subsubheading Δείτε επίσης



@itemize *

@item 
The devguide@footnote{https://devguide.python.org/getting-started/setup-building/#install-dependencies}
includes a full list of dependencies required to build all modules and
instructions on how to install them on common platforms.

@item 
@ref{1d2b,,--with-system-expat} allows building with an external
libexpat@footnote{https://libexpat.github.io/} library.

@item 
@ref{234a,,Options for third-party dependencies}
@end itemize



Άλλαξε στην έκδοση 3.1: Tcl/Tk version 8.3.1 is now required for @ref{f9,,tkinter}.



Άλλαξε στην έκδοση 3.5: Tcl/Tk version 8.4 is now required for @ref{f9,,tkinter}.



Άλλαξε στην έκδοση 3.7: OpenSSL 1.0.2 is now required for @ref{6b,,hashlib} and @ref{d8,,ssl}.



Άλλαξε στην έκδοση 3.10: OpenSSL 1.1.1 is now required for @ref{6b,,hashlib} and @ref{d8,,ssl}.
SQLite 3.7.15 is now required for @ref{d7,,sqlite3}.



Άλλαξε στην έκδοση 3.11: Tcl/Tk version 8.5.12 is now required for @ref{f9,,tkinter}.



Άλλαξε στην έκδοση 3.13: SQLite 3.15.2 is now required for @ref{d7,,sqlite3}.


@node Generated files,Configure Options,Build Requirements,Configure Python
@anchor{using/configure generated-files}@anchor{234b}
@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{234c}
@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 versions of the
tools used.
The container that CPython uses has
Autoconf@footnote{https://gnu.org/software/autoconf} 2.72,
@code{aclocal} from Automake@footnote{https://www.gnu.org/software/automake} 1.16.5,
and pkg-config@footnote{https://www.freedesktop.org/wiki/Software/pkg-config/} 1.8.1.


Άλλαξε στην έκδοση 3.13: Autoconf 2.71 and aclocal 1.16.5 and are now used to regenerate
@code{configure}.



Άλλαξε στην έκδοση 3.14: Autoconf 2.72 is now used to regenerate @code{configure}.


@node Configure Options,Python Build System,Generated files,Configure Python
@anchor{using/configure configure-options}@anchor{233a}@anchor{using/configure id12}@anchor{234d}
@subsection Configure Options


List all @code{configure} script options using:

@example
./configure --help
@end example

See also the @code{Misc/SpecialBuilds.txt} in the Python source distribution.

@menu
* General Options:: 
* C compiler options:: 
* Linker options:: 
* Options for third-party dependencies:: 
* WebAssembly Options:: 
* Install Options:: 
* Performance options:: 
* Python Debug Build:: 
* Debug options:: 
* Linker options: Linker options<2>. 
* Libraries options:: 
* Security Options:: 
* macOS Options:: 
* iOS Options:: 
* Cross Compiling Options:: 

@end menu

@node General Options,C compiler options,,Configure Options
@anchor{using/configure general-options}@anchor{234e}
@subsubsection General Options


@geindex command line option; --enable-loadable-sqlite-extensions
@anchor{using/configure cmdoption-enable-loadable-sqlite-extensions}@anchor{234f}
@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{d7,,sqlite3} module.

See the @ref{c17,,sqlite3.Connection.enable_load_extension()} method of the
@ref{d7,,sqlite3} module.


Added in version 3.6.

@end deffn

@geindex command line option; --disable-ipv6
@anchor{using/configure cmdoption-disable-ipv6}@anchor{2350}
@deffn {Option} @w{-}@w{-}disable@w{-}ipv6

Disable IPv6 support (enabled by default if supported), see the
@ref{d4,,socket} module.
@end deffn

@geindex command line option; --enable-big-digits
@anchor{using/configure cmdoption-enable-big-digits}@anchor{b31}
@deffn {Option} @w{-}@w{-}enable@w{-}big@w{-}digits=[15|30]

Define the size in bits of Python @ref{326,,int} digits: 15 or 30 bits.

By default, the digit size is 30.

Define the @code{PYLONG_BITS_IN_DIGIT} to @code{15} or @code{30}.

See @ref{1638,,sys.int_info.bits_per_digit}.
@end deffn

@geindex command line option; --with-suffix
@anchor{using/configure cmdoption-with-suffix}@anchor{2351}
@deffn {Option} @w{-}@w{-}with@w{-}suffix=SUFFIX

Set the Python executable suffix to `SUFFIX'.

The default suffix is @code{.exe} on Windows and macOS (@code{python.exe}
executable), @code{.js} on Emscripten node, @code{.html} on Emscripten browser,
@code{.wasm} on WASI, and an empty string on other platforms (@code{python}
executable).


Άλλαξε στην έκδοση 3.11: The default suffix on WASM platform is one of @code{.js}, @code{.html}
or @code{.wasm}.

@end deffn

@geindex command line option; --with-tzpath
@anchor{using/configure cmdoption-with-tzpath}@anchor{2352}
@deffn {Option} @w{-}@w{-}with@w{-}tzpath=<list of absolute paths separated by pathsep>

Select the default time zone search path for @ref{2353,,zoneinfo.TZPATH}.
See the @ref{2354,,Compile-time configuration} of the @ref{13d,,zoneinfo} module.

Default: @code{/usr/share/zoneinfo:/usr/lib/zoneinfo:/usr/share/lib/zoneinfo:/etc/zoneinfo}.

See @ref{2322,,os.pathsep} path separator.


Added in version 3.9.

@end deffn

@geindex command line option; --without-decimal-contextvar
@anchor{using/configure cmdoption-without-decimal-contextvar}@anchor{2355}
@deffn {Option} @w{-}@w{-}without@w{-}decimal@w{-}contextvar

Build the @code{_decimal} extension module using a thread-local context rather
than a coroutine-local context (default), see the @ref{39,,decimal} module.

See @ref{2356,,decimal.HAVE_CONTEXTVAR} and the @ref{28,,contextvars} module.


Added in version 3.9.

@end deffn

@geindex command line option; --with-dbmliborder
@anchor{using/configure cmdoption-with-dbmliborder}@anchor{2357}
@deffn {Option} @w{-}@w{-}with@w{-}dbmliborder=<list of backend names>

Override order to check db backends for the @ref{34,,dbm} module

A valid value is a colon (@code{:}) separated string with the backend names:


@itemize *

@item 
@code{ndbm};

@item 
@code{gdbm};

@item 
@code{bdb}.
@end itemize
@end deffn

@geindex command line option; --without-c-locale-coercion
@anchor{using/configure cmdoption-without-c-locale-coercion}@anchor{2358}
@deffn {Option} @w{-}@w{-}without@w{-}c@w{-}locale@w{-}coercion

Disable C locale coercion to a UTF-8 based locale (enabled by default).

Don’t define the @code{PY_COERCE_C_LOCALE} macro.

See 
@geindex PYTHONCOERCECLOCALE
@geindex μεταβλητή περιβάλλοντος; PYTHONCOERCECLOCALE
@ref{e9b,,PYTHONCOERCECLOCALE} and the 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/}.
@end deffn

@geindex command line option; --with-platlibdir
@anchor{using/configure cmdoption-with-platlibdir}@anchor{19bd}
@deffn {Option} @w{-}@w{-}with@w{-}platlibdir=DIRNAME

Python library directory name (default is @code{lib}).

Fedora and SuSE use @code{lib64} on 64-bit platforms.

See @ref{2a9,,sys.platlibdir}.


Added in version 3.9.

@end deffn

@geindex command line option; --with-wheel-pkg-dir
@anchor{using/configure cmdoption-with-wheel-pkg-dir}@anchor{c63}
@deffn {Option} @w{-}@w{-}with@w{-}wheel@w{-}pkg@w{-}dir=PATH

Directory of wheel packages used by the @ref{58,,ensurepip} module
(none by default).

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.


Added in version 3.10.

@end deffn

@geindex command line option; --with-pkg-config
@anchor{using/configure cmdoption-with-pkg-config}@anchor{2359}
@deffn {Option} @w{-}@w{-}with@w{-}pkg@w{-}config=[check|yes|no]

Whether configure should use @code{pkg-config} to detect build
dependencies.


@itemize *

@item 
@code{check} (default): @code{pkg-config} is optional

@item 
@code{yes}: @code{pkg-config} is mandatory

@item 
@code{no}: configure does not use @code{pkg-config} even when present
@end itemize


Added in version 3.11.

@end deffn

@geindex command line option; --with-missing-stdlib-config
@anchor{using/configure cmdoption-with-missing-stdlib-config}@anchor{3d7}
@deffn {Option} @w{-}@w{-}with@w{-}missing@w{-}stdlib@w{-}config=FILE

Path to a JSON@footnote{https://www.json.org/json-en.html} configuration file
containing custom error messages for missing @ref{3d8,,standard library} modules.

This option is intended for Python distributors who wish to provide
distribution-specific guidance when users encounter standard library
modules that are missing or packaged separately.

The JSON file should map missing module names to custom error message strings.
For example, if your distribution packages @ref{f9,,tkinter} and
@ref{3,,_tkinter} separately and excludes @code{_gdbm} for legal reasons,
the configuration could contain:

@example
@{
    "_gdbm": "The '_gdbm' module is not available in this distribution",
    "tkinter": "Install the python-tk package to use tkinter",
    "_tkinter": "Install the python-tk package to use tkinter",
@}
@end example


Added in version 3.15.

@end deffn

@geindex command line option; --enable-pystats
@anchor{using/configure cmdoption-enable-pystats}@anchor{1d36}
@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{178,,-X pystats} command line option.

@item 
Add @code{PYTHONSTATS} environment variable.

@item 
Define the @code{Py_STATS} macro.

@item 
Add functions to the @ref{e2,,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.

Use @code{Tools/scripts/summarize_stats.py} to read the stats.

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


Added in version 3.11.

@end deffn

@geindex command line option; --disable-gil
@anchor{using/configure free-threading-build}@anchor{235a}@anchor{using/configure cmdoption-disable-gil}@anchor{6a5}
@deffn {Option} @w{-}@w{-}disable@w{-}gil

@geindex Py_GIL_DISABLED (C macro)
@anchor{using/configure c Py_GIL_DISABLED}@anchor{191e}
Enables support for running Python without the @ref{685,,global interpreter lock} (GIL): @ref{198,,free-threaded build}.

Defines the @code{Py_GIL_DISABLED} macro and adds @code{"t"} to
@ref{e28,,sys.abiflags}.

See @ref{67f,,Free-threaded CPython} for more detail.


Added in version 3.13.

@end deffn

@geindex command line option; --enable-experimental-jit
@anchor{using/configure cmdoption-enable-experimental-jit}@anchor{661}
@deffn {Option} @w{-}@w{-}enable@w{-}experimental@w{-}jit=[no|yes|yes@w{-}off|interpreter]

Indicate how to integrate the @ref{406,,experimental just-in-time compiler}.


@itemize *

@item 
@code{no}: Don’t build the JIT.

@item 
@code{yes}: Enable the JIT. To disable it at runtime, set the environment
variable 
@geindex PYTHON_JIT
@geindex μεταβλητή περιβάλλοντος; PYTHON_JIT
@ref{660,,PYTHON_JIT=0}.

@item 
@code{yes-off}: Build the JIT, but disable it by default. To enable it at
runtime, set the environment variable 
@geindex PYTHON_JIT
@geindex μεταβλητή περιβάλλοντος; PYTHON_JIT
@ref{660,,PYTHON_JIT=1}.

@item 
@code{interpreter}: Enable the «JIT interpreter» (only useful for those
debugging the JIT itself). To disable it at runtime, set the environment
variable 
@geindex PYTHON_JIT
@geindex μεταβλητή περιβάλλοντος; PYTHON_JIT
@ref{660,,PYTHON_JIT=0}.
@end itemize

@code{--enable-experimental-jit=no} is the default behavior if the option is not
provided, and @code{--enable-experimental-jit} is shorthand for
@code{--enable-experimental-jit=yes}.  See @code{Tools/jit/README.md} for more
information, including how to install the necessary build-time dependencies.

@cartouche
@quotation Σημείωση 
When building CPython with JIT enabled, ensure that your system has Python 3.11 or later installed.
@end quotation
@end cartouche


Added in version 3.13.

@end deffn

@geindex command line option; PKG_CONFIG
@anchor{using/configure cmdoption-arg-PKG_CONFIG}@anchor{235b}
@deffn {Option} PKG_CONFIG

Path to @code{pkg-config} utility.
@end deffn

@geindex command line option; PKG_CONFIG_LIBDIR
@anchor{using/configure cmdoption-arg-PKG_CONFIG_LIBDIR}@anchor{235c}
@deffn {Option} PKG_CONFIG_LIBDIR
@end deffn

@geindex command line option; PKG_CONFIG_PATH
@anchor{using/configure cmdoption-arg-PKG_CONFIG_PATH}@anchor{235d}
@deffn {Option} PKG_CONFIG_PATH

@code{pkg-config} options.
@end deffn

@geindex command line option; --disable-epoll
@anchor{using/configure cmdoption-disable-epoll}@anchor{193a}
@deffn {Option} @w{-}@w{-}disable@w{-}epoll

Build without @code{epoll}, meaning that @ref{133d,,select.epoll()} will not be
present even if the system provides an
@code{epoll_create@footnote{https://manpages.debian.org/epoll_create(2)}} function.
This may be used on systems where @code{epoll_create} or
@code{epoll_create1@footnote{https://manpages.debian.org/epoll_create1(2)}} is available
but incompatible with Linux semantics.


Added in version 3.15.

@end deffn

@node C compiler options,Linker options,General Options,Configure Options
@anchor{using/configure c-compiler-options}@anchor{235e}
@subsubsection C compiler options


@geindex command line option; CC
@anchor{using/configure cmdoption-arg-CC}@anchor{235f}
@deffn {Option} CC

C compiler command.
@end deffn

@geindex command line option; CFLAGS
@anchor{using/configure cmdoption-arg-CFLAGS}@anchor{2360}
@deffn {Option} CFLAGS

C compiler flags.
@end deffn

@geindex command line option; CPP
@anchor{using/configure cmdoption-arg-CPP}@anchor{2361}
@deffn {Option} CPP

C preprocessor command.
@end deffn

@geindex command line option; CPPFLAGS
@anchor{using/configure cmdoption-arg-CPPFLAGS}@anchor{2362}
@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,Configure Options
@anchor{using/configure linker-options}@anchor{2363}
@subsubsection Linker options


@geindex command line option; LDFLAGS
@anchor{using/configure cmdoption-arg-LDFLAGS}@anchor{2364}
@deffn {Option} LDFLAGS

Linker flags, e.g. @code{-L@var{library_directory}}.
@end deffn

@geindex command line option; LIBS
@anchor{using/configure cmdoption-arg-LIBS}@anchor{2365}
@deffn {Option} LIBS

Libraries to pass to the linker, e.g. @code{-l@var{library}}.
@end deffn

@geindex command line option; MACHDEP
@anchor{using/configure cmdoption-arg-MACHDEP}@anchor{2366}
@deffn {Option} MACHDEP

Name for machine-dependent library files.
@end deffn

@node Options for third-party dependencies,WebAssembly Options,Linker options,Configure Options
@anchor{using/configure configure-options-for-dependencies}@anchor{234a}@anchor{using/configure options-for-third-party-dependencies}@anchor{2367}
@subsubsection Options for third-party dependencies



Added in version 3.11.


@geindex command line option; BZIP2_CFLAGS
@anchor{using/configure cmdoption-arg-BZIP2_CFLAGS}@anchor{2368}
@deffn {Option} BZIP2_CFLAGS
@end deffn

@geindex command line option; BZIP2_LIBS
@anchor{using/configure cmdoption-arg-BZIP2_LIBS}@anchor{2369}
@deffn {Option} BZIP2_LIBS

C compiler and linker flags to link Python to @code{libbz2}, used by @ref{14,,bz2}
module, overriding @code{pkg-config}.
@end deffn

@geindex command line option; CURSES_CFLAGS
@anchor{using/configure cmdoption-arg-CURSES_CFLAGS}@anchor{236a}
@deffn {Option} CURSES_CFLAGS
@end deffn

@geindex command line option; CURSES_LIBS
@anchor{using/configure cmdoption-arg-CURSES_LIBS}@anchor{236b}
@deffn {Option} CURSES_LIBS

C compiler and linker flags for @code{libncurses} or @code{libncursesw}, used by
@ref{2e,,curses} module, overriding @code{pkg-config}.
@end deffn

@geindex command line option; GDBM_CFLAGS
@anchor{using/configure cmdoption-arg-GDBM_CFLAGS}@anchor{236c}
@deffn {Option} GDBM_CFLAGS
@end deffn

@geindex command line option; GDBM_LIBS
@anchor{using/configure cmdoption-arg-GDBM_LIBS}@anchor{236d}
@deffn {Option} GDBM_LIBS

C compiler and linker flags for @code{gdbm}.
@end deffn

@geindex command line option; LIBEDIT_CFLAGS
@anchor{using/configure cmdoption-arg-LIBEDIT_CFLAGS}@anchor{236e}
@deffn {Option} LIBEDIT_CFLAGS
@end deffn

@geindex command line option; LIBEDIT_LIBS
@anchor{using/configure cmdoption-arg-LIBEDIT_LIBS}@anchor{236f}
@deffn {Option} LIBEDIT_LIBS

C compiler and linker flags for @code{libedit}, used by @ref{c2,,readline} module,
overriding @code{pkg-config}.
@end deffn

@geindex command line option; LIBFFI_CFLAGS
@anchor{using/configure cmdoption-arg-LIBFFI_CFLAGS}@anchor{2370}
@deffn {Option} LIBFFI_CFLAGS
@end deffn

@geindex command line option; LIBFFI_LIBS
@anchor{using/configure cmdoption-arg-LIBFFI_LIBS}@anchor{2371}
@deffn {Option} LIBFFI_LIBS

C compiler and linker flags for @code{libffi}, used by @ref{2d,,ctypes} module,
overriding @code{pkg-config}.
@end deffn

@geindex command line option; LIBMPDEC_CFLAGS
@anchor{using/configure cmdoption-arg-LIBMPDEC_CFLAGS}@anchor{2372}
@deffn {Option} LIBMPDEC_CFLAGS
@end deffn

@geindex command line option; LIBMPDEC_LIBS
@anchor{using/configure cmdoption-arg-LIBMPDEC_LIBS}@anchor{2373}
@deffn {Option} LIBMPDEC_LIBS

C compiler and linker flags for @code{libmpdec}, used by @ref{39,,decimal} module,
overriding @code{pkg-config}.

@cartouche
@quotation Σημείωση 
These environment variables have no effect unless
@ref{3d6,,--with-system-libmpdec} is specified.
@end quotation
@end cartouche
@end deffn

@geindex command line option; LIBLZMA_CFLAGS
@anchor{using/configure cmdoption-arg-LIBLZMA_CFLAGS}@anchor{2374}
@deffn {Option} LIBLZMA_CFLAGS
@end deffn

@geindex command line option; LIBLZMA_LIBS
@anchor{using/configure cmdoption-arg-LIBLZMA_LIBS}@anchor{2375}
@deffn {Option} LIBLZMA_LIBS

C compiler and linker flags for @code{liblzma}, used by @ref{8d,,lzma} module,
overriding @code{pkg-config}.
@end deffn

@geindex command line option; LIBREADLINE_CFLAGS
@anchor{using/configure cmdoption-arg-LIBREADLINE_CFLAGS}@anchor{2376}
@deffn {Option} LIBREADLINE_CFLAGS
@end deffn

@geindex command line option; LIBREADLINE_LIBS
@anchor{using/configure cmdoption-arg-LIBREADLINE_LIBS}@anchor{2377}
@deffn {Option} LIBREADLINE_LIBS

C compiler and linker flags for @code{libreadline}, used by @ref{c2,,readline}
module, overriding @code{pkg-config}.
@end deffn

@geindex command line option; LIBSQLITE3_CFLAGS
@anchor{using/configure cmdoption-arg-LIBSQLITE3_CFLAGS}@anchor{2378}
@deffn {Option} LIBSQLITE3_CFLAGS
@end deffn

@geindex command line option; LIBSQLITE3_LIBS
@anchor{using/configure cmdoption-arg-LIBSQLITE3_LIBS}@anchor{2379}
@deffn {Option} LIBSQLITE3_LIBS

C compiler and linker flags for @code{libsqlite3}, used by @ref{d7,,sqlite3}
module, overriding @code{pkg-config}.
@end deffn

@geindex command line option; LIBUUID_CFLAGS
@anchor{using/configure cmdoption-arg-LIBUUID_CFLAGS}@anchor{237a}
@deffn {Option} LIBUUID_CFLAGS
@end deffn

@geindex command line option; LIBUUID_LIBS
@anchor{using/configure cmdoption-arg-LIBUUID_LIBS}@anchor{237b}
@deffn {Option} LIBUUID_LIBS

C compiler and linker flags for @code{libuuid}, used by @ref{119,,uuid} module,
overriding @code{pkg-config}.
@end deffn

@geindex command line option; LIBZSTD_CFLAGS
@anchor{using/configure cmdoption-arg-LIBZSTD_CFLAGS}@anchor{237c}
@deffn {Option} LIBZSTD_CFLAGS
@end deffn

@geindex command line option; LIBZSTD_LIBS
@anchor{using/configure cmdoption-arg-LIBZSTD_LIBS}@anchor{237d}
@deffn {Option} LIBZSTD_LIBS

C compiler and linker flags for @code{libzstd}, used by @ref{23,,compression.zstd} module,
overriding @code{pkg-config}.


Added in version 3.14.

@end deffn

@geindex command line option; PANEL_CFLAGS
@anchor{using/configure cmdoption-arg-PANEL_CFLAGS}@anchor{237e}
@deffn {Option} PANEL_CFLAGS
@end deffn

@geindex command line option; PANEL_LIBS
@anchor{using/configure cmdoption-arg-PANEL_LIBS}@anchor{237f}
@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{30,,curses.panel} module, overriding @code{pkg-config}.
@end deffn

@geindex command line option; TCLTK_CFLAGS
@anchor{using/configure cmdoption-arg-TCLTK_CFLAGS}@anchor{2380}
@deffn {Option} TCLTK_CFLAGS
@end deffn

@geindex command line option; TCLTK_LIBS
@anchor{using/configure cmdoption-arg-TCLTK_LIBS}@anchor{2381}
@deffn {Option} TCLTK_LIBS

C compiler and linker flags for TCLTK, overriding @code{pkg-config}.
@end deffn

@geindex command line option; ZLIB_CFLAGS
@anchor{using/configure cmdoption-arg-ZLIB_CFLAGS}@anchor{2382}
@deffn {Option} ZLIB_CFLAGS
@end deffn

@geindex command line option; ZLIB_LIBS
@anchor{using/configure cmdoption-arg-ZLIB_LIBS}@anchor{2383}
@deffn {Option} ZLIB_LIBS

C compiler and linker flags for @code{libzlib}, used by @ref{6a,,gzip} module,
overriding @code{pkg-config}.
@end deffn

@node WebAssembly Options,Install Options,Options for third-party dependencies,Configure Options
@anchor{using/configure webassembly-options}@anchor{2384}
@subsubsection WebAssembly Options


@geindex command line option; --enable-wasm-dynamic-linking
@anchor{using/configure cmdoption-enable-wasm-dynamic-linking}@anchor{1db8}
@deffn {Option} @w{-}@w{-}enable@w{-}wasm@w{-}dynamic@w{-}linking

Turn on dynamic linking support for WASM.

Dynamic linking enables @code{dlopen}. File size of the executable
increases due to limited dead code elimination and additional features.


Added in version 3.11.

@end deffn

@geindex command line option; --enable-wasm-pthreads
@anchor{using/configure cmdoption-enable-wasm-pthreads}@anchor{1d89}
@deffn {Option} @w{-}@w{-}enable@w{-}wasm@w{-}pthreads

Turn on pthreads support for WASM.


Added in version 3.11.

@end deffn

@node Install Options,Performance options,WebAssembly Options,Configure Options
@anchor{using/configure install-options}@anchor{2385}
@subsubsection Install Options


@geindex command line option; --prefix
@anchor{using/configure cmdoption-prefix}@anchor{233c}
@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{3ab,,sys.prefix}.

As an example, one can use @code{--prefix="$HOME/.local/"} to install
a Python in its home directory.
@end deffn

@geindex command line option; --exec-prefix
@anchor{using/configure cmdoption-exec-prefix}@anchor{233d}
@deffn {Option} @w{-}@w{-}exec@w{-}prefix=EPREFIX

Install architecture-dependent files in EPREFIX, defaults to @ref{233c,,--prefix}.

This value can be retrieved at runtime using @ref{3a8,,sys.exec_prefix}.
@end deffn

@geindex command line option; --disable-test-modules
@anchor{using/configure cmdoption-disable-test-modules}@anchor{c62}
@deffn {Option} @w{-}@w{-}disable@w{-}test@w{-}modules

Don’t build nor install test modules, like the @ref{eb,,test} package or the
@code{_testcapi} extension module (built and installed by default).


Added in version 3.10.

@end deffn

@geindex command line option; --with-ensurepip
@anchor{using/configure cmdoption-with-ensurepip}@anchor{2386}
@deffn {Option} @w{-}@w{-}with@w{-}ensurepip=[upgrade|install|no]

Select the @ref{58,,ensurepip} command run on Python installation:


@itemize *

@item 
@code{upgrade} (default): run @code{python -m ensurepip --altinstall --upgrade}
command.

@item 
@code{install}: run @code{python -m ensurepip --altinstall} command;

@item 
@code{no}: don’t run ensurepip;
@end itemize


Added in version 3.6.

@end deffn

@node Performance options,Python Debug Build,Install Options,Configure Options
@anchor{using/configure performance-options}@anchor{2387}
@subsubsection Performance options


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 command line option; --enable-optimizations
@anchor{using/configure cmdoption-enable-optimizations}@anchor{c39}
@deffn {Option} @w{-}@w{-}enable@w{-}optimizations

Enable Profile Guided Optimization (PGO) using 
@geindex PROFILE_TASK
@geindex μεταβλητή περιβάλλοντος; PROFILE_TASK
@ref{1c84,,PROFILE_TASK}
(disabled by default).

The C compiler Clang requires @code{llvm-profdata} program for PGO. On
macOS, GCC also requires it: GCC is just an alias to Clang on macOS.

Disable also semantic interposition in libpython if @code{--enable-shared} and
GCC is used: add @code{-fno-semantic-interposition} to the compiler and linker
flags.

@cartouche
@quotation Σημείωση 
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 μεταβλητή περιβάλλοντος; CFLAGS
@ref{1859,,CFLAGS}.
@end quotation
@end cartouche


Added in version 3.6.



Άλλαξε στην έκδοση 3.10: Use @code{-fno-semantic-interposition} on GCC.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PROFILE_TASK
@anchor{using/configure envvar-PROFILE_TASK}@anchor{1c84}
@deffn {Μεταβλητή Περιβάλλοντος} PROFILE_TASK

Environment variable used in the Makefile: Python command line arguments for
the PGO generation task.

Default: @code{-m test --pgo --timeout=$(TESTTIMEOUT)}.


Added in version 3.8.



Άλλαξε στην έκδοση 3.13: Task failure is no longer ignored silently.

@end deffn

@geindex command line option; --with-lto
@anchor{using/configure cmdoption-with-lto}@anchor{b30}
@deffn {Option} @w{-}@w{-}with@w{-}lto=[full|thin|no|yes]

Enable Link Time Optimization (LTO) in any build (disabled by default).

The C compiler Clang requires @code{llvm-ar} for LTO (@code{ar} on macOS), as well
as an LTO-aware linker (@code{ld.gold} or @code{lld}).


Added in version 3.6.



Added in version 3.11: To use ThinLTO feature, use @code{--with-lto=thin} on Clang.



Άλλαξε στην έκδοση 3.12: Use ThinLTO as the default optimization policy on Clang if the compiler accepts the flag.

@end deffn

@geindex command line option; --enable-bolt
@anchor{using/configure cmdoption-enable-bolt}@anchor{2388}
@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.


Added in version 3.12.

@end deffn

@geindex command line option; BOLT_APPLY_FLAGS
@anchor{using/configure cmdoption-arg-BOLT_APPLY_FLAGS}@anchor{2389}
@deffn {Option} BOLT_APPLY_FLAGS

Arguments to @code{llvm-bolt} when creating a BOLT optimized binary@footnote{https://github.com/facebookarchive/BOLT}.


Added in version 3.12.

@end deffn

@geindex command line option; BOLT_INSTRUMENT_FLAGS
@anchor{using/configure cmdoption-arg-BOLT_INSTRUMENT_FLAGS}@anchor{238a}
@deffn {Option} BOLT_INSTRUMENT_FLAGS

Arguments to @code{llvm-bolt} when instrumenting binaries.


Added in version 3.12.

@end deffn

@geindex command line option; --with-computed-gotos
@anchor{using/configure cmdoption-with-computed-gotos}@anchor{238b}
@deffn {Option} @w{-}@w{-}with@w{-}computed@w{-}gotos

Enable computed gotos in evaluation loop (enabled by default on supported
compilers).
@end deffn

@geindex command line option; --with-tail-call-interp
@anchor{using/configure cmdoption-with-tail-call-interp}@anchor{41c}
@deffn {Option} @w{-}@w{-}with@w{-}tail@w{-}call@w{-}interp

Enable interpreters using tail calls in CPython. If enabled, enabling PGO
(@ref{c39,,--enable-optimizations}) is highly recommended. This option specifically
requires a C compiler with proper tail call support, and the
preserve_none@footnote{https://clang.llvm.org/docs/AttributeReference.html#preserve-none}
calling convention. For example, Clang 19 and newer supports this feature.


Added in version 3.14.

@end deffn

@geindex command line option; --without-frame-pointers
@anchor{using/configure cmdoption-without-frame-pointers}@anchor{3dd}
@deffn {Option} @w{-}@w{-}without@w{-}frame@w{-}pointers

Disable frame pointers, which are enabled by default (see 
@geindex Python Enhancement Proposals; PEP 831
PEP 831@footnote{https://peps.python.org/pep-0831/}).

By default, the build appends flags to generate frame or backchain
pointers to @code{BASECFLAGS}:


@itemize -

@item 
@code{-fno-omit-frame-pointer} and/or @code{-mno-omit-leaf-frame-pointer}
are added when the compiler supports them.

@item 
@code{-marm} and/or @code{-mno-thumb} is added on 32-bit ARM when supported,

@item 
on s390x platforms, when supported, @code{-mbackchain} is added `instead'.
of the above frame pointer flags.

@item 
on ppc64le platforms, no compiler flags is needed since the power ABI
requires that compilers maintain a back chain by default.
@end itemize

Frame pointers enable profilers, debuggers, and system tracing tools
(@code{perf}, @code{eBPF}, @code{dtrace}, @code{gdb}) to walk the C call stack
without DWARF metadata. The flags propagate to third-party C
extensions through @ref{e4,,sysconfig}. On compilers that do not
understand them, the build silently skips them.

Downstream packagers and authors of native libraries built with
custom build systems should set the same flags so the unwind chain
stays unbroken across all native frames.


Added in version 3.15.

@end deffn

@geindex command line option; --without-mimalloc
@anchor{using/configure cmdoption-without-mimalloc}@anchor{238c}
@deffn {Option} @w{-}@w{-}without@w{-}mimalloc

Disable the fast @ref{232b,,mimalloc} allocator
(enabled by default).

This option cannot be used together with @ref{6a5,,--disable-gil}
because the @ref{487,,free-threaded} build requires mimalloc.

See also 
@geindex PYTHONMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,PYTHONMALLOC} environment variable.
@end deffn

@geindex command line option; --without-pymalloc
@anchor{using/configure cmdoption-without-pymalloc}@anchor{238d}
@deffn {Option} @w{-}@w{-}without@w{-}pymalloc

Disable the specialized Python memory allocator @ref{3da,,pymalloc}
(enabled by default).

See also 
@geindex PYTHONMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,PYTHONMALLOC} environment variable.
@end deffn

@geindex command line option; --with-pymalloc-hugepages
@anchor{using/configure cmdoption-with-pymalloc-hugepages}@anchor{3d9}
@deffn {Option} @w{-}@w{-}with@w{-}pymalloc@w{-}hugepages

Enable huge page support for @ref{3da,,pymalloc} arenas (disabled by
default). When enabled, the arena size on 64-bit platforms is increased to
2 MiB and arena allocation uses @code{MAP_HUGETLB} (Linux) or
@code{MEM_LARGE_PAGES} (Windows) with automatic fallback to regular pages.

Even when compiled with this option, huge pages are `not' used at runtime
unless the 
@geindex PYTHON_PYMALLOC_HUGEPAGES
@geindex μεταβλητή περιβάλλοντος; PYTHON_PYMALLOC_HUGEPAGES
@ref{3db,,PYTHON_PYMALLOC_HUGEPAGES} environment variable is set
to @code{1}. This opt-in is required because huge pages


@itemize *

@item 
carry risks on Linux: if the huge-page pool is exhausted, page faults
(including copy-on-write faults after @ref{6bd,,os.fork()}) deliver @code{SIGBUS}
and kill the process.

@item 
need a special privilege on Windows. See the Windows documentation for large pages@footnote{https://learn.microsoft.com/windows/win32/memory/large-page-support}
for details. Python will fail on startup if the required privilege
SeLockMemoryPrivilege@footnote{https://learn.microsoft.com/previous-versions/windows/it-pro/windows-10/security/threat-protection/security-policy-settings/lock-pages-in-memory}
is not held by the user.
@end itemize

The configure script checks that the platform supports @code{MAP_HUGETLB}
and emits a warning if it is not available.

On Windows, use the @code{--pymalloc-hugepages} flag with @code{build.bat} or
set the @code{UsePymallocHugepages} MSBuild property.


Added in version 3.15.

@end deffn

@geindex command line option; --without-doc-strings
@anchor{using/configure cmdoption-without-doc-strings}@anchor{238e}
@deffn {Option} @w{-}@w{-}without@w{-}doc@w{-}strings

Disable static documentation strings to reduce the memory footprint (enabled
by default). Documentation strings defined in Python are not affected.

Don’t define the @code{WITH_DOC_STRINGS} macro.

See the @code{PyDoc_STRVAR()} macro.
@end deffn

@geindex command line option; --enable-profiling
@anchor{using/configure cmdoption-enable-profiling}@anchor{238f}
@deffn {Option} @w{-}@w{-}enable@w{-}profiling

Enable C-level code profiling with @code{gprof} (disabled by default).
@end deffn

@geindex command line option; --with-strict-overflow
@anchor{using/configure cmdoption-with-strict-overflow}@anchor{1cd2}
@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

@geindex command line option; --without-remote-debug
@anchor{using/configure cmdoption-without-remote-debug}@anchor{41a}
@deffn {Option} @w{-}@w{-}without@w{-}remote@w{-}debug

Deactivate remote debugging support described in 
@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/} (enabled by default).
When this flag is provided the code that allows the interpreter to schedule the
execution of a Python file in a separate process as described in 
@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/} is
not compiled. This includes both the functionality to schedule code to be executed
and the functionality to receive code to be executed.

@geindex Py_REMOTE_DEBUG (C macro)
@anchor{using/configure c Py_REMOTE_DEBUG}@anchor{2390}
@deffn {C Μακροεντολή} Py_REMOTE_DEBUG

This macro is defined by default, unless Python is configured with
@ref{41a,,--without-remote-debug}.

Note that even if the macro is defined, remote debugging may not be
available (for example, on an incompatible platform).
@end deffn


Added in version 3.14.

@end deffn

@node Python Debug Build,Debug options,Performance options,Configure Options
@anchor{using/configure debug-build}@anchor{3dc}@anchor{using/configure python-debug-build}@anchor{2391}
@subsubsection Python Debug Build


A debug build is Python built with the @ref{853,,--with-pydebug} configure
option.

Effects of a debug build:


@itemize *

@item 
Display all warnings by default: the list of default warning filters is empty
in the @ref{11b,,warnings} module.

@item 
Add @code{d} to @ref{e28,,sys.abiflags}.

@item 
Add @code{sys.gettotalrefcount()} function.

@item 
Add @ref{178,,-X showrefcount} command line option.

@item 
Add @ref{2312,,-d} command line option and 
@geindex PYTHONDEBUG
@geindex μεταβλητή περιβάλλοντος; PYTHONDEBUG
@ref{2313,,PYTHONDEBUG} environment
variable to debug the parser.

@item 
Add support for the @code{__lltrace__} variable: enable low-level tracing in the
bytecode evaluation loop if the variable is defined.

@item 
Install @ref{2329,,debug hooks on memory allocators}
to detect buffer overflow and other memory errors.

@item 
Define @code{Py_DEBUG} and @code{Py_REF_DEBUG} macros.

@item 
Add runtime checks: code surrounded by @code{#ifdef Py_DEBUG} and @code{#endif}.
Enable @code{assert(...)} and @code{_PyObject_ASSERT(...)} assertions: don’t set
the @code{NDEBUG} macro (see also the @ref{820,,--with-assertions} configure
option). Main runtime checks:


@itemize *

@item 
Add sanity checks on the function arguments.

@item 
Unicode and int objects are created with their memory filled with a pattern
to detect usage of uninitialized objects.

@item 
Ensure that functions which can clear or replace the current exception are
not called with an exception raised.

@item 
Check that deallocator functions don’t change the current exception.

@item 
The garbage collector (@ref{44f,,gc.collect()} function) runs some basic checks
on objects consistency.

@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

See also the @ref{70d,,Python Development Mode} and the
@ref{828,,--with-trace-refs} configure option.


Άλλαξε στην έκδοση 3.8: Release builds are now ABI compatible with debug builds: defining the
@code{Py_DEBUG} macro no longer implies the @code{Py_TRACE_REFS} macro (see the
@ref{828,,--with-trace-refs} option). However, debug builds still expose
more symbols than release builds and code built against a debug build is not
necessarily compatible with a release build.


@node Debug options,Linker options<2>,Python Debug Build,Configure Options
@anchor{using/configure debug-options}@anchor{2392}
@subsubsection Debug options


@geindex command line option; --with-pydebug
@anchor{using/configure cmdoption-with-pydebug}@anchor{853}
@deffn {Option} @w{-}@w{-}with@w{-}pydebug

@ref{3dc,,Build Python in debug mode}: define the @code{Py_DEBUG}
macro (disabled by default).
@end deffn

@geindex command line option; --with-trace-refs
@anchor{using/configure cmdoption-with-trace-refs}@anchor{828}
@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{516,,sys.getobjects()} function.

@item 
Add 
@geindex PYTHONDUMPREFS
@geindex μεταβλητή περιβάλλοντος; PYTHONDUMPREFS
@ref{d6f,,PYTHONDUMPREFS} environment variable.
@end itemize

The 
@geindex PYTHONDUMPREFS
@geindex μεταβλητή περιβάλλοντος; PYTHONDUMPREFS
@ref{d6f,,PYTHONDUMPREFS} environment variable can be used to dump
objects and reference counts still alive at Python exit.

@ref{b5f,,Statically allocated objects} are not traced.


Added in version 3.8.



Άλλαξε στην έκδοση 3.13: This build is now ABI compatible with release build and @ref{3dc,,debug build}.

@end deffn

@geindex command line option; --with-assertions
@anchor{using/configure cmdoption-with-assertions}@anchor{820}
@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 μεταβλητή περιβάλλοντος; OPT
@ref{2393,,OPT} compiler
variable.

See also the @ref{853,,--with-pydebug} option (@ref{3dc,,debug build}) which also enables assertions.


Added in version 3.6.

@end deffn

@geindex command line option; --with-valgrind
@anchor{using/configure cmdoption-with-valgrind}@anchor{2394}
@deffn {Option} @w{-}@w{-}with@w{-}valgrind

Enable Valgrind support (default is no).
@end deffn

@geindex command line option; --with-dtrace
@anchor{using/configure cmdoption-with-dtrace}@anchor{2395}
@deffn {Option} @w{-}@w{-}with@w{-}dtrace

Enable DTrace support (default is no).

See @ref{102a,,Instrumenting CPython with DTrace and SystemTap}.


Added in version 3.6.

@end deffn

@geindex command line option; --with-address-sanitizer
@anchor{using/configure cmdoption-with-address-sanitizer}@anchor{2396}
@deffn {Option} @w{-}@w{-}with@w{-}address@w{-}sanitizer

Enable AddressSanitizer memory error detector, @code{asan} (default is no).
To improve ASan detection capabilities you may also want to combine this
with @ref{238d,,--without-pymalloc} to disable the specialized small-object
allocator whose allocations are not tracked by ASan.


Added in version 3.6.

@end deffn

@geindex command line option; --with-memory-sanitizer
@anchor{using/configure cmdoption-with-memory-sanitizer}@anchor{2397}
@deffn {Option} @w{-}@w{-}with@w{-}memory@w{-}sanitizer

Enable MemorySanitizer allocation error detector, @code{msan} (default is no).


Added in version 3.6.

@end deffn

@geindex command line option; --with-undefined-behavior-sanitizer
@anchor{using/configure cmdoption-with-undefined-behavior-sanitizer}@anchor{2398}
@deffn {Option} @w{-}@w{-}with@w{-}undefined@w{-}behavior@w{-}sanitizer

Enable UndefinedBehaviorSanitizer undefined behaviour detector, @code{ubsan}
(default is no).


Added in version 3.6.

@end deffn

@geindex command line option; --with-thread-sanitizer
@anchor{using/configure cmdoption-with-thread-sanitizer}@anchor{2399}
@deffn {Option} @w{-}@w{-}with@w{-}thread@w{-}sanitizer

Enable ThreadSanitizer data race detector, @code{tsan}
(default is no).


Added in version 3.13.

@end deffn

@node Linker options<2>,Libraries options,Debug options,Configure Options
@anchor{using/configure id13}@anchor{239a}
@subsubsection Linker options


@geindex command line option; --enable-shared
@anchor{using/configure cmdoption-enable-shared}@anchor{c3a}
@deffn {Option} @w{-}@w{-}enable@w{-}shared

Enable building a shared Python library: @code{libpython} (default is no).
@end deffn

@geindex command line option; --without-static-libpython
@anchor{using/configure cmdoption-without-static-libpython}@anchor{c64}
@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).


Added in version 3.10.

@end deffn

@geindex command line option; --enable-static-libpython-for-interpreter
@anchor{using/configure cmdoption-enable-static-libpython-for-interpreter}@anchor{1918}
@deffn {Option} @w{-}@w{-}enable@w{-}static@w{-}libpython@w{-}for@w{-}interpreter

Do not link the Python interpreter binary (@code{python3}) against the
shared Python library; instead, statically link the interpreter
against @code{libpython} as if @code{--enable-shared} had not been used,
but continue to build the shared @code{libpython} (for use by other
programs).

This option does nothing if @code{--enable-shared} is not used.

The default (when @code{-enable-shared} is used) is to link the Python
interpreter against the built shared library.


Added in version 3.15.

@end deffn

@node Libraries options,Security Options,Linker options<2>,Configure Options
@anchor{using/configure libraries-options}@anchor{239b}
@subsubsection Libraries options


@geindex command line option; --with-libs
@anchor{using/configure cmdoption-with-libs}@anchor{239c}
@deffn {Option} @w{-}@w{-}with@w{-}libs='lib1 ...'

Link against additional libraries (default is no).
@end deffn

@geindex command line option; --with-system-expat
@anchor{using/configure cmdoption-with-system-expat}@anchor{1d2b}
@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 command line option; --with-system-libmpdec
@anchor{using/configure cmdoption-with-system-libmpdec}@anchor{3d6}
@deffn {Option} @w{-}@w{-}with@w{-}system@w{-}libmpdec

Build the @code{_decimal} extension module using an installed @code{mpdecimal}
library, see the @ref{39,,decimal} module (default is yes).


Added in version 3.3.



Άλλαξε στην έκδοση 3.13: Default to using the installed @code{mpdecimal} library.



Άλλαξε στην έκδοση 3.15: A bundled copy of the library will no longer be selected
implicitly if an installed @code{mpdecimal} library is not found.
In Python 3.15 only, it can still be selected explicitly using
@code{--with-system-libmpdec=no} or @code{--without-system-libmpdec}.



Καταργήθηκε από την έκδοση 3.13, αφαιρέθηκε στην έκδοση 3.16: A copy of the @code{mpdecimal} library sources will no longer be distributed
with Python 3.16.



@subsubheading Δείτε επίσης


@ref{2372,,LIBMPDEC_CFLAGS} and @ref{2373,,LIBMPDEC_LIBS}.

@end deffn

@geindex command line option; --with-readline
@anchor{using/configure cmdoption-with-readline}@anchor{2348}
@deffn {Option} @w{-}@w{-}with@w{-}readline=readline|editline

Designate a backend library for the @ref{c2,,readline} module.


@itemize *

@item 
readline: Use readline as the backend.

@item 
editline: Use editline as the backend.
@end itemize


Added in version 3.10.

@end deffn

@geindex command line option; --without-readline
@anchor{using/configure cmdoption-without-readline}@anchor{239d}
@deffn {Option} @w{-}@w{-}without@w{-}readline

Don’t build the @ref{c2,,readline} module (built by default).

Don’t define the @code{HAVE_LIBREADLINE} macro.


Added in version 3.10.

@end deffn

@geindex command line option; --with-libm
@anchor{using/configure cmdoption-with-libm}@anchor{239e}
@deffn {Option} @w{-}@w{-}with@w{-}libm=STRING

Override @code{libm} math library to `STRING' (default is system-dependent).
@end deffn

@geindex command line option; --with-libc
@anchor{using/configure cmdoption-with-libc}@anchor{239f}
@deffn {Option} @w{-}@w{-}with@w{-}libc=STRING

Override @code{libc} C library to `STRING' (default is system-dependent).
@end deffn

@geindex command line option; --with-openssl
@anchor{using/configure cmdoption-with-openssl}@anchor{23a0}
@deffn {Option} @w{-}@w{-}with@w{-}openssl=DIR

Root of the OpenSSL directory.


Added in version 3.7.

@end deffn

@geindex command line option; --with-openssl-rpath
@anchor{using/configure cmdoption-with-openssl-rpath}@anchor{c65}
@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{23a0,,--with-openssl} and
@code{pkg-config};

@item 
`DIR': set an explicit rpath.
@end itemize


Added in version 3.10.

@end deffn

@node Security Options,macOS Options,Libraries options,Configure Options
@anchor{using/configure security-options}@anchor{23a1}
@subsubsection Security Options


@geindex command line option; --with-hash-algorithm
@anchor{using/configure cmdoption-with-hash-algorithm}@anchor{23a2}
@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


Added in version 3.4.



Added in version 3.11: @code{siphash13} is added and it is the new default.

@end deffn

@geindex command line option; --with-builtin-hashlib-hashes
@anchor{using/configure cmdoption-with-builtin-hashlib-hashes}@anchor{2349}
@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


Added in version 3.9.

@end deffn

@geindex command line option; --with-ssl-default-suites
@anchor{using/configure cmdoption-with-ssl-default-suites}@anchor{23a3}
@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{d8,,ssl} module.


Added in version 3.7.



Άλλαξε στην έκδοση 3.10: The settings @code{python} and `STRING' also set TLS 1.2 as minimum
protocol version.

@end deffn

@geindex command line option; --disable-safety
@anchor{using/configure cmdoption-disable-safety}@anchor{658}
@deffn {Option} @w{-}@w{-}disable@w{-}safety

Disable compiler options that are recommended by OpenSSF@footnote{https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Compiler-Hardening-Guides/Compiler-Options-Hardening-Guide-for-C-and-C++.md} for security reasons with no performance overhead.
If this option is not enabled, CPython will be built based on safety compiler options with no slow down.
When this option is enabled, CPython will not be built with the compiler options listed below.

The following compiler options are disabled with @code{--disable-safety}:


@itemize *

@item 
-fstack-protector-strong@footnote{https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Compiler-Hardening-Guides/Compiler-Options-Hardening-Guide-for-C-and-C++.md#enable-run-time-checks-for-stack-based-buffer-overflows}: Enable run-time checks for stack-based buffer overflows.

@item 
-Wtrampolines@footnote{https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Compiler-Hardening-Guides/Compiler-Options-Hardening-Guide-for-C-and-C++.md#enable-warning-about-trampolines-that-require-executable-stacks}: Enable warnings about trampolines that require executable stacks.
@end itemize


Added in version 3.14.

@end deffn

@geindex command line option; --enable-slower-safety
@anchor{using/configure cmdoption-enable-slower-safety}@anchor{659}
@deffn {Option} @w{-}@w{-}enable@w{-}slower@w{-}safety

Enable compiler options that are recommended by OpenSSF@footnote{https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Compiler-Hardening-Guides/Compiler-Options-Hardening-Guide-for-C-and-C++.md} for security reasons which require overhead.
If this option is not enabled, CPython will not be built based on safety compiler options which performance impact.
When this option is enabled, CPython will be built with the compiler options listed below.

The following compiler options are enabled with @code{--enable-slower-safety}:


@itemize *

@item 
-D_FORTIFY_SOURCE=3@footnote{https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Compiler-Hardening-Guides/Compiler-Options-Hardening-Guide-for-C-and-C++.md#fortify-sources-for-unsafe-libc-usage-and-buffer-overflows}: Fortify sources with compile- and run-time checks for unsafe libc usage and buffer overflows.
@end itemize


Added in version 3.14.

@end deffn

@node macOS Options,iOS Options,Security Options,Configure Options
@anchor{using/configure macos-options}@anchor{23a4}
@subsubsection macOS Options


See Mac/README.rst@footnote{https://github.com/python/cpython/tree/main/Mac/README.rst}.

@geindex command line option; --enable-universalsdk
@anchor{using/configure cmdoption-enable-universalsdk}@anchor{d34}
@deffn {Option} @w{-}@w{-}enable@w{-}universalsdk
@end deffn

@geindex command line option; --enable-universalsdk
@anchor{using/configure cmdoption-0}@anchor{23a5}
@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 command line option; --enable-framework
@anchor{using/configure cmdoption-enable-framework}@anchor{23a6}
@deffn {Option} @w{-}@w{-}enable@w{-}framework
@end deffn

@geindex command line option; --enable-framework
@anchor{using/configure cmdoption-1}@anchor{23a7}
@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 command line option; --with-universal-archs
@anchor{using/configure cmdoption-with-universal-archs}@anchor{23a8}
@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{d34,,--enable-universalsdk} is set.

Options:


@itemize *

@item 
@code{universal2} (x86-64 and arm64);

@item 
@code{32-bit} (PPC and i386);

@item 
@code{64-bit}  (PPC64 and x86-64);

@item 
@code{3-way} (i386, PPC and x86-64);

@item 
@code{intel} (i386 and x86-64);

@item 
@code{intel-32} (i386);

@item 
@code{intel-64} (x86-64);

@item 
@code{all}  (PPC, i386, PPC64 and x86-64).
@end itemize

Note that values for this configuration item are `not' the same as the
identifiers used for universal binary wheels on macOS. See the Python
Packaging User Guide for details on the packaging platform compatibility tags used on macOS@footnote{https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/#macos}
@end deffn

@geindex command line option; --with-framework-name
@anchor{using/configure cmdoption-with-framework-name}@anchor{23a9}
@deffn {Option} @w{-}@w{-}with@w{-}framework@w{-}name=FRAMEWORK

Specify the name for the python framework on macOS only valid when
@ref{23a6,,--enable-framework} is set (default: @code{Python}).
@end deffn

@geindex command line option; --with-app-store-compliance
@anchor{using/configure cmdoption-with-app-store-compliance}@anchor{1ba4}
@deffn {Option} @w{-}@w{-}with@w{-}app@w{-}store@w{-}compliance
@end deffn

@geindex command line option; --with-app-store-compliance
@anchor{using/configure cmdoption-2}@anchor{23aa}
@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.


Added in version 3.13.

@end deffn

@node iOS Options,Cross Compiling Options,macOS Options,Configure Options
@anchor{using/configure ios-options}@anchor{23ab}
@subsubsection iOS Options


See iOS/README.rst@footnote{https://github.com/python/cpython/tree/main/iOS/README.rst}.

@geindex command line option; --enable-framework
@anchor{using/configure cmdoption-3}@anchor{23ac}
@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 command line option; --with-framework-name
@anchor{using/configure cmdoption-4}@anchor{23ad}
@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,Configure Options
@anchor{using/configure cross-compiling-options}@anchor{23ae}
@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 command line option; --build
@anchor{using/configure cmdoption-build}@anchor{23af}
@deffn {Option} @w{-}@w{-}build=BUILD

configure for building on BUILD, usually guessed by @code{config.guess}.
@end deffn

@geindex command line option; --host
@anchor{using/configure cmdoption-host}@anchor{23b0}
@deffn {Option} @w{-}@w{-}host=HOST

cross-compile to build programs to run on HOST (target platform)
@end deffn

@geindex command line option; --with-build-python
@anchor{using/configure cmdoption-with-build-python}@anchor{23b1}
@deffn {Option} @w{-}@w{-}with@w{-}build@w{-}python=path/to/python

path to build @code{python} binary for cross compiling


Added in version 3.11.

@end deffn

@geindex command line option; CONFIG_SITE
@anchor{using/configure cmdoption-arg-CONFIG_SITE}@anchor{23b2}
@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 command line option; HOSTRUNNER
@anchor{using/configure cmdoption-arg-HOSTRUNNER}@anchor{23b3}
@deffn {Option} HOSTRUNNER

Program to run CPython for the host platform for cross-compilation.


Added in 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,Configure Options,Configure Python
@anchor{using/configure python-build-system}@anchor{23b4}
@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{23b5}
@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{23b6}
@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{23b7}
@subsubsection Main Makefile targets


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

@end menu

@node make,make platform,,Main Makefile targets
@anchor{using/configure make}@anchor{23b8}
@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} (chosen if the host platform matches @code{wasm32-wasi*} or
@code{wasm32-emscripten})

@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{23b9}
@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{23ba}
@subsubsection make profile-opt


Build Python using profile-guided optimization (PGO).  You can use the
configure @ref{c39,,--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{23bb}
@subsubsection make clean


Remove built files.

@node make distclean,make install,make clean,Main Makefile targets
@anchor{using/configure make-distclean}@anchor{23bc}
@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{23bd}
@subsubsection make install


Build the @code{all} target and install Python.

@node make test,make ci,make install,Main Makefile targets
@anchor{using/configure make-test}@anchor{23be}
@subsubsection make test


Build the @code{all} target and run the Python test suite with the
@code{--fast-ci} option without GUI tests. 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 ci,make buildbottest,make test,Main Makefile targets
@anchor{using/configure make-ci}@anchor{23bf}
@subsubsection make ci


This is similar to @code{make test}, but uses the @code{-ugui} to also run GUI tests.


Added in version 3.14.


@node make buildbottest,make regen-all,make ci,Main Makefile targets
@anchor{using/configure make-buildbottest}@anchor{23c0}
@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{23c1}
@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{234b,,generated files}.

@node C extensions,,Main Makefile targets,Python Build System
@anchor{using/configure c-extensions}@anchor{23c2}
@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{1875,,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{1bd,,ImportError} on import.

@node Compiler and linker flags,,Python Build System,Configure Python
@anchor{using/configure compiler-and-linker-flags}@anchor{23c3}
@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{23c4}
@subsubsection Preprocessor flags


@geindex μεταβλητή περιβάλλοντος; CONFIGURE_CPPFLAGS
@anchor{using/configure envvar-CONFIGURE_CPPFLAGS}@anchor{23c5}
@deffn {Μεταβλητή Περιβάλλοντος} CONFIGURE_CPPFLAGS

Value of 
@geindex CPPFLAGS
@geindex μεταβλητή περιβάλλοντος; CPPFLAGS
@ref{185b,,CPPFLAGS} variable passed to the @code{./configure} script.


Added in version 3.6.

@end deffn

@geindex μεταβλητή περιβάλλοντος; CPPFLAGS
@anchor{using/configure envvar-CPPFLAGS}@anchor{185b}
@deffn {Μεταβλητή Περιβάλλοντος} 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 μεταβλητή περιβάλλοντος; CPPFLAGS
@ref{185b,,CPPFLAGS} and 
@geindex LDFLAGS
@geindex μεταβλητή περιβάλλοντος; LDFLAGS
@ref{185a,,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 μεταβλητή περιβάλλοντος; BASECPPFLAGS
@anchor{using/configure envvar-BASECPPFLAGS}@anchor{23c6}
@deffn {Μεταβλητή Περιβάλλοντος} BASECPPFLAGS


Added in version 3.4.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PY_CPPFLAGS
@anchor{using/configure envvar-PY_CPPFLAGS}@anchor{23c7}
@deffn {Μεταβλητή Περιβάλλοντος} PY_CPPFLAGS

Extra preprocessor flags added for building the interpreter object files.

Default: @code{$(BASECPPFLAGS) -I. -I$(srcdir)/Include $(CONFIGURE_CPPFLAGS) $(CPPFLAGS)}.


Added in version 3.2.

@end deffn

@node Compiler flags,Linker flags,Preprocessor flags,Compiler and linker flags
@anchor{using/configure compiler-flags}@anchor{23c8}
@subsubsection Compiler flags


@geindex μεταβλητή περιβάλλοντος; CC
@anchor{using/configure envvar-CC}@anchor{1858}
@deffn {Μεταβλητή Περιβάλλοντος} CC

C compiler command.

Example: @code{gcc -pthread}.
@end deffn

@geindex μεταβλητή περιβάλλοντος; CXX
@anchor{using/configure envvar-CXX}@anchor{23c9}
@deffn {Μεταβλητή Περιβάλλοντος} CXX

C++ compiler command.

Example: @code{g++ -pthread}.
@end deffn

@geindex μεταβλητή περιβάλλοντος; CFLAGS
@anchor{using/configure envvar-CFLAGS}@anchor{1859}
@deffn {Μεταβλητή Περιβάλλοντος} CFLAGS

C compiler flags.
@end deffn

@geindex μεταβλητή περιβάλλοντος; CFLAGS_NODIST
@anchor{using/configure envvar-CFLAGS_NODIST}@anchor{23ca}
@deffn {Μεταβλητή Περιβάλλοντος} CFLAGS_NODIST

@geindex CFLAGS_NODIST
@geindex μεταβλητή περιβάλλοντος; CFLAGS_NODIST
@ref{23ca,,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 μεταβλητή περιβάλλοντος; CFLAGS
@ref{1859,,CFLAGS} once Python is installed (gh-65320@footnote{https://github.com/python/cpython/issues/65320}).

In particular, 
@geindex CFLAGS
@geindex μεταβλητή περιβάλλοντος; CFLAGS
@ref{1859,,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 μεταβλητή περιβάλλοντος; CFLAGS
@ref{1859,,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


Added in version 3.5.

@end deffn

@geindex μεταβλητή περιβάλλοντος; COMPILEALL_OPTS
@anchor{using/configure envvar-COMPILEALL_OPTS}@anchor{23cb}
@deffn {Μεταβλητή Περιβάλλοντος} COMPILEALL_OPTS

Options passed to the @ref{21,,compileall} command line when building PYC files
in @code{make install}. Default: @code{-j0}.


Added in version 3.12.

@end deffn

@geindex μεταβλητή περιβάλλοντος; EXTRA_CFLAGS
@anchor{using/configure envvar-EXTRA_CFLAGS}@anchor{23cc}
@deffn {Μεταβλητή Περιβάλλοντος} EXTRA_CFLAGS

Extra C compiler flags.
@end deffn

@geindex μεταβλητή περιβάλλοντος; CONFIGURE_CFLAGS
@anchor{using/configure envvar-CONFIGURE_CFLAGS}@anchor{23cd}
@deffn {Μεταβλητή Περιβάλλοντος} CONFIGURE_CFLAGS

Value of 
@geindex CFLAGS
@geindex μεταβλητή περιβάλλοντος; CFLAGS
@ref{1859,,CFLAGS} variable passed to the @code{./configure}
script.


Added in version 3.2.

@end deffn

@geindex μεταβλητή περιβάλλοντος; CONFIGURE_CFLAGS_NODIST
@anchor{using/configure envvar-CONFIGURE_CFLAGS_NODIST}@anchor{23ce}
@deffn {Μεταβλητή Περιβάλλοντος} CONFIGURE_CFLAGS_NODIST

Value of 
@geindex CFLAGS_NODIST
@geindex μεταβλητή περιβάλλοντος; CFLAGS_NODIST
@ref{23ca,,CFLAGS_NODIST} variable passed to the @code{./configure}
script.


Added in version 3.5.

@end deffn

@geindex μεταβλητή περιβάλλοντος; BASECFLAGS
@anchor{using/configure envvar-BASECFLAGS}@anchor{23cf}
@deffn {Μεταβλητή Περιβάλλοντος} BASECFLAGS

Base compiler flags.
@end deffn

@geindex μεταβλητή περιβάλλοντος; OPT
@anchor{using/configure envvar-OPT}@anchor{2393}
@deffn {Μεταβλητή Περιβάλλοντος} OPT

Optimization flags.
@end deffn

@geindex μεταβλητή περιβάλλοντος; CFLAGS_ALIASING
@anchor{using/configure envvar-CFLAGS_ALIASING}@anchor{23d0}
@deffn {Μεταβλητή Περιβάλλοντος} CFLAGS_ALIASING

Strict or non-strict aliasing flags used to compile @code{Python/dtoa.c}.


Added in version 3.7.

@end deffn

@geindex μεταβλητή περιβάλλοντος; CFLAGS_CEVAL
@anchor{using/configure envvar-CFLAGS_CEVAL}@anchor{23d1}
@deffn {Μεταβλητή Περιβάλλοντος} CFLAGS_CEVAL

Flags used to compile @code{Python/ceval.c}.


Added in version 3.14.5.

@end deffn

@geindex μεταβλητή περιβάλλοντος; CCSHARED
@anchor{using/configure envvar-CCSHARED}@anchor{23d2}
@deffn {Μεταβλητή Περιβάλλοντος} CCSHARED

Compiler flags used to build a shared library.

For example, @code{-fPIC} is used on Linux and on BSD.
@end deffn

@geindex μεταβλητή περιβάλλοντος; CFLAGSFORSHARED
@anchor{using/configure envvar-CFLAGSFORSHARED}@anchor{23d3}
@deffn {Μεταβλητή Περιβάλλοντος} CFLAGSFORSHARED

Extra C flags added for building the interpreter object files.

Default: @code{$(CCSHARED)} when @ref{c3a,,--enable-shared} is used, or an empty
string otherwise.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PY_CFLAGS
@anchor{using/configure envvar-PY_CFLAGS}@anchor{23d4}
@deffn {Μεταβλητή Περιβάλλοντος} PY_CFLAGS

Default: @code{$(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS)}.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PY_CFLAGS_NODIST
@anchor{using/configure envvar-PY_CFLAGS_NODIST}@anchor{23d5}
@deffn {Μεταβλητή Περιβάλλοντος} PY_CFLAGS_NODIST

Default: @code{$(CONFIGURE_CFLAGS_NODIST) $(CFLAGS_NODIST) -I$(srcdir)/Include/internal}.


Added in version 3.5.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PY_STDMODULE_CFLAGS
@anchor{using/configure envvar-PY_STDMODULE_CFLAGS}@anchor{23d6}
@deffn {Μεταβλητή Περιβάλλοντος} PY_STDMODULE_CFLAGS

C flags used for building the interpreter object files.

Default: @code{$(PY_CFLAGS) $(PY_CFLAGS_NODIST) $(PY_CPPFLAGS) $(CFLAGSFORSHARED)}.


Added in version 3.7.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PY_CORE_CFLAGS
@anchor{using/configure envvar-PY_CORE_CFLAGS}@anchor{23d7}
@deffn {Μεταβλητή Περιβάλλοντος} PY_CORE_CFLAGS

Default: @code{$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE}.


Added in version 3.2.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PY_BUILTIN_MODULE_CFLAGS
@anchor{using/configure envvar-PY_BUILTIN_MODULE_CFLAGS}@anchor{23d8}
@deffn {Μεταβλητή Περιβάλλοντος} PY_BUILTIN_MODULE_CFLAGS

Compiler flags to build a standard library extension module as a built-in
module, like the @ref{b2,,posix} module.

Default: @code{$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN}.


Added in version 3.8.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PURIFY
@anchor{using/configure envvar-PURIFY}@anchor{23d9}
@deffn {Μεταβλητή Περιβάλλοντος} 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{23da}
@subsubsection Linker flags


@geindex μεταβλητή περιβάλλοντος; LINKCC
@anchor{using/configure envvar-LINKCC}@anchor{23db}
@deffn {Μεταβλητή Περιβάλλοντος} LINKCC

Linker command used to build programs like @code{python} and @code{_testembed}.

Default: @code{$(PURIFY) $(CC)}.
@end deffn

@geindex μεταβλητή περιβάλλοντος; CONFIGURE_LDFLAGS
@anchor{using/configure envvar-CONFIGURE_LDFLAGS}@anchor{23dc}
@deffn {Μεταβλητή Περιβάλλοντος} CONFIGURE_LDFLAGS

Value of 
@geindex LDFLAGS
@geindex μεταβλητή περιβάλλοντος; LDFLAGS
@ref{185a,,LDFLAGS} variable passed to the @code{./configure} script.

Avoid assigning 
@geindex CFLAGS
@geindex μεταβλητή περιβάλλοντος; CFLAGS
@ref{1859,,CFLAGS}, 
@geindex LDFLAGS
@geindex μεταβλητή περιβάλλοντος; LDFLAGS
@ref{185a,,LDFLAGS}, etc. so users can use
them on the command line to append to these values without stomping the
pre-set values.


Added in version 3.2.

@end deffn

@geindex μεταβλητή περιβάλλοντος; LDFLAGS_NODIST
@anchor{using/configure envvar-LDFLAGS_NODIST}@anchor{23dd}
@deffn {Μεταβλητή Περιβάλλοντος} LDFLAGS_NODIST

@geindex LDFLAGS_NODIST
@geindex μεταβλητή περιβάλλοντος; LDFLAGS_NODIST
@ref{23dd,,LDFLAGS_NODIST} is used in the same manner as
@geindex CFLAGS_NODIST
@geindex μεταβλητή περιβάλλοντος; CFLAGS_NODIST
@ref{23ca,,CFLAGS_NODIST}.  Use it when a linker flag should `not' be part of
@geindex LDFLAGS
@geindex μεταβλητή περιβάλλοντος; LDFLAGS
@ref{185a,,LDFLAGS} once Python is installed (gh-65320@footnote{https://github.com/python/cpython/issues/65320}).

In particular, 
@geindex LDFLAGS
@geindex μεταβλητή περιβάλλοντος; LDFLAGS
@ref{185a,,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 μεταβλητή περιβάλλοντος; LDFLAGS
@ref{185a,,LDFLAGS} would take precedence over user- and package-supplied @code{-L}
flags.
@end itemize
@end deffn

@geindex μεταβλητή περιβάλλοντος; CONFIGURE_LDFLAGS_NODIST
@anchor{using/configure envvar-CONFIGURE_LDFLAGS_NODIST}@anchor{23de}
@deffn {Μεταβλητή Περιβάλλοντος} CONFIGURE_LDFLAGS_NODIST

Value of 
@geindex LDFLAGS_NODIST
@geindex μεταβλητή περιβάλλοντος; LDFLAGS_NODIST
@ref{23dd,,LDFLAGS_NODIST} variable passed to the @code{./configure}
script.


Added in version 3.8.

@end deffn

@geindex μεταβλητή περιβάλλοντος; LDFLAGS
@anchor{using/configure envvar-LDFLAGS}@anchor{185a}
@deffn {Μεταβλητή Περιβάλλοντος} LDFLAGS

Linker flags, e.g. @code{-L@var{lib_dir}} if you have libraries in a nonstandard
directory `lib_dir'.

Both 
@geindex CPPFLAGS
@geindex μεταβλητή περιβάλλοντος; CPPFLAGS
@ref{185b,,CPPFLAGS} and 
@geindex LDFLAGS
@geindex μεταβλητή περιβάλλοντος; LDFLAGS
@ref{185a,,LDFLAGS} need to contain the shell’s
value to be able to build extension modules using the
directories specified in the environment variables.

Please consider using @code{EXE_LDFLAGS} if the supplied linker flags are
executable specific, e.g. GCC’s @code{-pie} flag.
@end deffn

@geindex μεταβλητή περιβάλλοντος; LIBS
@anchor{using/configure envvar-LIBS}@anchor{23df}
@deffn {Μεταβλητή Περιβάλλοντος} LIBS

Linker flags to pass libraries to the linker when linking the Python
executable.

Example: @code{-lrt}.
@end deffn

@geindex μεταβλητή περιβάλλοντος; LDSHARED
@anchor{using/configure envvar-LDSHARED}@anchor{23e0}
@deffn {Μεταβλητή Περιβάλλοντος} LDSHARED

Command to build a shared library.

Default: @code{@@LDSHARED@@ $(PY_LDFLAGS)}.
@end deffn

@geindex μεταβλητή περιβάλλοντος; BLDSHARED
@anchor{using/configure envvar-BLDSHARED}@anchor{23e1}
@deffn {Μεταβλητή Περιβάλλοντος} BLDSHARED

Command to build @code{libpython} shared library.

Default: @code{@@BLDSHARED@@ $(PY_CORE_LDFLAGS)}.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PY_LDFLAGS
@anchor{using/configure envvar-PY_LDFLAGS}@anchor{23e2}
@deffn {Μεταβλητή Περιβάλλοντος} PY_LDFLAGS

Default: @code{$(CONFIGURE_LDFLAGS) $(LDFLAGS)}.
@end deffn

@geindex μεταβλητή περιβάλλοντος; PY_LDFLAGS_NODIST
@anchor{using/configure envvar-PY_LDFLAGS_NODIST}@anchor{23e3}
@deffn {Μεταβλητή Περιβάλλοντος} PY_LDFLAGS_NODIST

Default: @code{$(CONFIGURE_LDFLAGS_NODIST) $(LDFLAGS_NODIST)}.


Added in version 3.8.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PY_CORE_LDFLAGS
@anchor{using/configure envvar-PY_CORE_LDFLAGS}@anchor{23e4}
@deffn {Μεταβλητή Περιβάλλοντος} PY_CORE_LDFLAGS

Linker flags used for building the interpreter object files.


Added in version 3.8.

@end deffn

@geindex μεταβλητή περιβάλλοντος; EXE_LDFLAGS
@anchor{using/configure envvar-EXE_LDFLAGS}@anchor{23e5}
@deffn {Μεταβλητή Περιβάλλοντος} EXE_LDFLAGS

Linker flags used for building executable targets such as the
interpreter. If supplied, 
@geindex PY_CORE_EXE_LDFLAGS
@geindex μεταβλητή περιβάλλοντος; PY_CORE_EXE_LDFLAGS
@ref{23e6,,PY_CORE_EXE_LDFLAGS}
will be used in replacement of 
@geindex PY_CORE_LDFLAGS
@geindex μεταβλητή περιβάλλοντος; PY_CORE_LDFLAGS
@ref{23e4,,PY_CORE_LDFLAGS}.


Added in version 3.15.

@end deffn

@geindex μεταβλητή περιβάλλοντος; CONFIGURE_EXE_LDFLAGS
@anchor{using/configure envvar-CONFIGURE_EXE_LDFLAGS}@anchor{23e7}
@deffn {Μεταβλητή Περιβάλλοντος} CONFIGURE_EXE_LDFLAGS

Value of 
@geindex EXE_LDFLAGS
@geindex μεταβλητή περιβάλλοντος; EXE_LDFLAGS
@ref{23e5,,EXE_LDFLAGS} variable passed to the @code{./configure}
script.


Added in version 3.15.

@end deffn

@geindex μεταβλητή περιβάλλοντος; PY_CORE_EXE_LDFLAGS
@anchor{using/configure envvar-PY_CORE_EXE_LDFLAGS}@anchor{23e6}
@deffn {Μεταβλητή Περιβάλλοντος} PY_CORE_EXE_LDFLAGS

Linker flags used for building the interpreter and
executable targets.

Default: @code{$(PY_CORE_LDFLAGS)}


Added in version 3.15.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Χρησιμοποιώντας Python στα Windows,Χρησιμοποιώντας Python σε macOS,Configure Python,Ρύθμιση και Χρήση της Python
@anchor{using/windows doc}@anchor{23e8}@anchor{using/windows translation-repo}@anchor{23e9}@anchor{using/windows using-on-windows}@anchor{e6d}@anchor{using/windows using-python-on-windows}@anchor{23ea}
@section Χρησιμοποιώντας Python στα Windows


Αυτό το έγγραφο στοχεύει να δώσει μια επισκόπηση της συμπεριφοράς των Windows που πρέπει να γνωρίζετε, όταν χρησιμοποιείτε την Python στα Microsoft Windows.

Σε αντίθεση με τα περισσότερα συστήματα και υπηρεσίες Unix, τα Windows δεν περιλαμβάνουν μια υποστηριζόμενη από το σύστημα εγκατάσταση της Python. Αντίθετα, η Python μπορεί να αποκτηθεί από αρκετούς διανομείς, συμπεριλαμβανομένης της άμεσης λήψης από την ομάδα CPython. Κάθε διανομή Python θα έχει τα δικά της πλεονεκτήματα και μειονεκτήματα, ωστόσο, η συνέπεια με άλλα εργαλεία που χρησιμοποιείτε είναι γενικά ένα αξιόλογο πλεονέκτημα. Πριν δεσμευτείτε στη διαδικασία που περιγράφεται εδώ, συνιστούμε να ερευνήσετε τα υπάρχοντα εργαλεία σας για να δείτε αν μπορούν να παρέχουν την Python απευθείας.

Για να αποκτήσετε την Python από την ομάδα CPython, χρησιμοποιήστε τον Python Install Manager. Αυτό είναι ένα αυτόνομο εργαλείο που καθιστά την Python διαθέσιμη ως παγκόσμιες εντολές στον υπολογιστή σας με Windows, ενσωματώνεται με το σύστημα και υποστηρίζει ενημερώσεις με την πάροδο του χρόνου. Μπορείτε να κατεβάσετε τον Python Install Manager από το python.org/downloads@footnote{https://www.python.org/downloads/} ή μέσω του Microsoft Store app@footnote{https://apps.microsoft.com/detail/9NQ7512CXL7T}.

Μόλις εγκαταστήσετε τον Python Install Manager, η παγκόσμια εντολή @code{python} μπορεί να χρησιμοποιηθεί από οποιοδήποτε τερματικό για να εκκινήσει την τρέχουσα τελευταία έκδοση της Python. Αυτή η έκδοση μπορεί να αλλάξει με την πάροδο του χρόνου καθώς προσθέτετε ή αφαιρείτε διαφορετικές εκδόσεις, και η εντολή @code{py list} θα δείξει ποια είναι η τρέχουσα.

Γενικά, συνιστούμε να δημιουργήσετε ένα @ref{22da,,εικονικό περιβάλλον} για κάθε έργο και να εκτελέσετε @code{<env>\Scripts\Activate} στο τερματικό σας για να το χρησιμοποιήσετε. Αυτό παρέχει απομόνωση μεταξύ των έργων, συνέπεια με την πάροδο του χρόνου και διασφαλίζει ότι οι επιπλέον εντολές που προστίθενται από τα πακέτα είναι επίσης διαθέσιμες στη συνεδρία σας. Δημιουργήστε ένα εικονικό περιβάλλον χρησιμοποιώντας @code{python -m venv <env path>}.

Εάν οι εντολές @code{python} ή @code{py} δεν φαίνεται να λειτουργούν, παρακαλούμε δείτε την ενότητα @ref{23eb,,Επίλυση προβλημάτων} παρακάτω. Υπάρχουν μερικές φορές επιπλέον χειροκίνητα βήματα που απαιτούνται για τη διαμόρφωση του υπολογιστή σας.

Εκτός από τη χρήση του διαχειριστή εγκατάστασης Python, η Python μπορεί επίσης να αποκτηθεί ως πακέτο NuGet. Δείτε @ref{23ec,,Τα πακέτα nuget.org} παρακάτω για περισσότερες πληροφορίες σχετικά με αυτά τα πακέτα.

Οι ενσωματώσιμες διανομές είναι ελάχιστα πακέτα της Python κατάλληλα για ενσωμάτωση σε μεγαλύτερες εφαρμογές. Μπορούν να εγκατασταθούν χρησιμοποιώντας τον διαχειριστή εγκατάστασης Python. Δείτε @ref{23ed,,Το ενσωματωμένο πακέτο} παρακάτω για περισσότερες πληροφορίες σχετικά με αυτά τα πακέτα.
@anchor{using/windows pymanager}@anchor{23ee}@anchor{using/windows windows-store}@anchor{21b6}@anchor{using/windows setting-envvars}@anchor{21b7}@anchor{using/windows windows-path-mod}@anchor{13f9}
@menu
* Διαχειριστής εγκατάστασης Python:: 
* Το ενσωματωμένο πακέτο:: 
* Τα πακέτα nuget.org: Τα πακέτα nuget org. 
* Εναλλακτικά πακέτα:: 
* Υποστηριζόμενες εκδόσεις των Windows:: 
* Αφαίρεση του περιορισμού MAX_PATH:: 
* Λειτουργία UTF-8:: 
* Εύρεση modules:: 
* Πρόσθετα modules:: 
* Μεταγλώττιση Python στα Windows:: 
* Το πλήρες πρόγραμμα εγκατάστασης:: 
* Το πρόγραμμα εκκίνησης Python για Windows (Απαρχαιωμένο): Το πρόγραμμα εκκίνησης Python για Windows Απαρχαιωμένο. 

@end menu

@node Διαχειριστής εγκατάστασης Python,Το ενσωματωμένο πακέτο,,Χρησιμοποιώντας Python στα Windows
@anchor{using/windows launcher}@anchor{9bc}@anchor{using/windows python-install-manager}@anchor{23ef}
@subsection Διαχειριστής εγκατάστασης Python


@menu
* Εγκατάσταση:: 
* Βασική χρήση:: 
* Εντολή βοήθειας:: 
* Καταχώριση χρόνων εκτέλεσης:: 
* Εγκαθιστώντας χρόνους εκτέλεσης:: 
* Εγκαταστάσεις εκτός σύνδεσης:: 
* Απεγκατάσταση χρόνων εκτέλεσης:: 
* Διαμόρφωση:: 
* Γραμμές Shebang:: 
* Προχωρημένη εγκατάσταση:: 
* Διαχειριστική διαμόρφωση:: 
* Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα:: 
* Index signatures:: 
* Αντιμετώπιση προβλημάτων:: 

@end menu

@node Εγκατάσταση,Βασική χρήση,,Διαχειριστής εγκατάστασης Python
@anchor{using/windows installation}@anchor{23f0}
@subsubsection Εγκατάσταση


Ο διαχειριστής εγκατάστασης Python μπορεί να εγκατασταθεί από την εφαρμογή Microsoft Store app@footnote{https://apps.microsoft.com/detail/9NQ7512CXL7T}  ή να ληφθεί και να εγκατασταθεί από το python.org/downloads@footnote{https://www.python.org/downloads/}. Οι δύο εκδόσεις είναι ταυτόσημες.

Για να εγκαταστήσετε μέσω του Store, απλώς κάντε κλικ στο «Εγκατάσταση». Αφού ολοκληρωθεί, ανοίξτε ένα τερματικό και πληκτρολογήστε @code{python} για να ξεκινήσετε.

Για να εγκαταστήσετε το αρχείο που κατεβάσατε από το python.org, είτε κάντε διπλό κλικ και επιλέξτε «Εγκατάσταση», είτε εκτελέστε @code{Add-AppxPackage <διαδρομή προς MSIX>} στα Windows Powershell.

Μετά την εγκατάσταση, οι εντολές @code{python}, @code{py} και @code{pymanager} θα πρέπει να είναι διαθέσιμες. Αν έχετε υπάρχουσες εγκαταστάσεις της Python, ή έχετε τροποποιήσει τη μεταβλητή 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}, ίσως χρειαστεί να τις αφαιρέσετε ή να αναιρέσετε τις τροποποιήσεις. Δείτε @ref{23eb,,Αντιμετώπιση προβλημάτων} για περισσότερη βοήθεια σχετικά με την αποκατάσταση μη λειτουργικών εντολών.

Όταν εγκαθιστάτε για πρώτη φορά ένα runtime, πιθανότατα θα σας ζητηθεί να προσθέσετε έναν φάκελο στη μεταβλητή 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}. Αυτό είναι προαιρετικό, αν προτιμάτε να χρησιμοποιήσετε την εντολή @code{py}, αλλά προσφέρεται για όσους προτιμούν να είναι διαθέσιμη η πλήρης γκάμα ψευδωνύμων (όπως το @code{python3.14.exe}). Ο φάκελος θα είναι @code{%LocalAppData%\Python\bin} από προεπιλογή, αλλά μπορεί να προσαρμοστεί από έναν διαχειριστή. Κάντε κλικ στο Έναρξη και αναζητήστε «Επεξεργασία μεταβλητών περιβάλλοντος για τον λογαριασμό σας» για τη σελίδα ρυθμίσεων συστήματος για να προσθέσετε τη διαδρομή.

Κάθε runtime της Python που εγκαθιστάτε θα έχει το δικό του φάκελο για σενάρια. Αυτά πρέπει επίσης να προστεθούν στη μεταβλητή 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} αν θέλετε να τα χρησιμοποιήσετε.

Ο διαχειριστής εγκατάστασης Python θα ενημερώνεται αυτόματα σε νέες εκδόσεις. Αυτό δεν επηρεάζει καμία εγκατάσταση runtime της Python. Η απεγκατάσταση του διαχειριστή εγκατάστασης Python δεν απεγκαθιστά καμία εγκατάσταση runtime της Python.

Εάν δεν μπορείτε να εγκαταστήσετε ένα MSIX στο πλαίσιο σας, για παράδειγμα, χρησιμοποιείτε λογισμικό αυτοματοποιημένης ανάπτυξης που δεν το υποστηρίζει, ή στοχεύετε τα Windows Server 2019, παρακαλώ δείτε @ref{23f1,,Προχωρημένη εγκατάσταση} παρακάτω για περισσότερες πληροφορίες.

@node Βασική χρήση,Εντολή βοήθειας,Εγκατάσταση,Διαχειριστής εγκατάστασης Python
@anchor{using/windows basic-use}@anchor{23f2}
@subsubsection Βασική χρήση


Η συνιστώμενη εντολή για την εκκίνηση της Python είναι @code{python}, η οποία θα εκκινήσει είτε την έκδοση που ζητείται από το σενάριο που εκκινείται, είτε ένα ενεργό εικονικό περιβάλλον, είτε την προεπιλεγμένη εγκατεστημένη έκδοση, η οποία θα είναι η τελευταία σταθερή έκδοση εκτός αν έχει ρυθμιστεί διαφορετικά. Εάν δεν ζητηθεί συγκεκριμένα καμία έκδοση και δεν είναι εγκατεστημένες καθόλου εκδόσεις, η τρέχουσα τελευταία έκδοση θα εγκατασταθεί αυτόματα.

Για όλα τα σενάρια που περιλαμβάνουν πολλαπλές εκδόσεις runtime, η συνιστώμενη εντολή είναι @code{py}. Αυτή μπορεί να χρησιμοποιηθεί οπουδήποτε αντί για @code{python} ή τον παλαιότερο εκκινητή @code{py.exe}. Από προεπιλογή, το @code{py} ταιριάζει με τη συμπεριφορά του @code{python}, αλλά επιτρέπει επίσης επιλογές γραμμής εντολών για την επιλογή μιας συγκεκριμένης έκδοσης, καθώς και υποεντολές για τη διαχείριση εγκαταστάσεων. Αυτές περιγράφονται λεπτομερώς παρακάτω.

Because the @code{py} command may already be taken by the previous version, there
is also an unambiguous @code{pymanager} command. Scripted installs that are
intending to use Python install manager should consider using @code{pymanager}, due
to the lower chance of encountering a conflict with existing installs. The only
difference between the two commands is when running without any arguments:
@code{py} will launch your default interpreter, while @code{pymanager} will display
help (@code{pymanager exec ...} provides equivalent behaviour to @code{py ...}).

Κάθε μία από αυτές τις εντολές έχει επίσης μια έκδοση με παράθυρο που αποφεύγει τη δημιουργία ενός παραθύρου κονσόλας. Αυτές είναι οι @code{pyw}, @code{pythonw} και @code{pymanagerw}. Μια εντολή @code{python3} περιλαμβάνεται επίσης που μιμείται την εντολή @code{python}. Είναι σχεδιασμένη να συλλαμβάνει τυχαίες χρήσεις της τυπικής εντολής POSIX σε Windows, αλλά δεν προορίζεται να χρησιμοποιείται ευρέως ή να συνιστάται.

Για να εκκινήσετε το προεπιλεγμένο χρόνο εκτέλεσης σας, εκτελέστε το @code{python} ή το @code{py} με τα ορίσματα που θέλετε να περαστούν στο χρόνο εκτέλεσης (όπως αρχεία σεναρίων ή το module για εκκίνηση):

@example
$> py
...
$> python my-script.py
...
$> py -m this
...
@end example

Ο προεπιλεγμένος χρόνος εκτέλεσης μπορεί να παρακαμφθεί με τη μεταβλητή περιβάλλοντος 
@geindex PYTHON_MANAGER_DEFAULT
@geindex μεταβλητή περιβάλλοντος; PYTHON_MANAGER_DEFAULT
@ref{23f3,,PYTHON_MANAGER_DEFAULT}, ή ένα αρχείο διαμόρφωσης. Δείτε @ref{23f4,,Διαμόρφωση} για πληροφορίες σχετικά με τις ρυθμίσεις διαμόρφωσης.

Για να εκκινήσετε ένα συγκεκριμένο χρόνο εκτέλεσης, η εντολή @code{py} δέχεται μια επιλογή @code{-V:<TAG>}. Αυτή η επιλογή πρέπει να καθοριστεί πριν από οποιεσδήποτε άλλες. Το tag είναι μέρος ή όλο το αναγνωριστικό για το χρόνο εκτέλεσης. Για αυτά από την ομάδα CPython, μοιάζει με την έκδοση, πιθανώς με την πλατφόρμα. Για λόγους συμβατότητας, το @code{V:} μπορεί να παραλειφθεί σε περιπτώσεις όπου το tag αναφέρεται σε μια επίσημη έκδοση και ξεκινά με @code{3}.

@example
$> py -V:3.14 ...
$> py -V:3-arm64 ...
@end example

Οι χρόνοι εκτέλεσης από άλλους διανομείς μπορεί να απαιτούν να συμπεριληφθεί και η `εταιρεία'. Αυτό θα πρέπει να διαχωρίζεται από το tag με μια κάθετο, και μπορεί να είναι ένα πρόθεμα. Η καθορισμός της εταιρείας είναι προαιρετικός όταν είναι @code{PythonCore}, και η καθορισμός του tag είναι προαιρετικός (αλλά όχι η κάθετος) όταν θέλετε την τελευταία έκδοση για μια συγκεκριμένη εταιρεία.

@example
$> py -V:Distributor\1.0 ...
$> py -V:distrib/ ...
@end example

Εάν δεν καθοριστεί καμία έκδοση, αλλά περαστεί ένα αρχείο σεναρίου, το σενάριο θα επιθεωρηθεί για μια `shebang line'. Αυτό είναι μια ειδική μορφή για την πρώτη γραμμή σε ένα αρχείο που επιτρέπει την παράκαμψη της εντολής. Δείτε @ref{23f5,,Γραμμές Shebang} για περισσότερες πληροφορίες. Όταν δεν υπάρχει shebang line, ή δεν μπορεί να επιλυθεί, το σενάριο θα εκκινήσει με το προεπιλεγμένο χρόνο εκτέλεσης.

Εάν τρέχετε σε ένα ενεργό εικονικό περιβάλλον, δεν έχετε ζητήσει μια συγκεκριμένη έκδοση, και δεν υπάρχει shebang line, το προεπιλεγμένο runtime θα είναι αυτό το εικονικό περιβάλλον.Σε αυτό το σενάριο, η εντολή @code{python} πιθανότατα είχε ήδη παρακαμφθεί και κανένας από αυτούς τους ελέγχους δεν συνέβη. Ωστόσο, αυτή η συμπεριφορά διασφαλίζει ότι η εντολή @code{py} μπορεί να χρησιμοποιηθεί εναλλακτικά.

When no runtimes are installed, any launch command will try to install the
requested version and launch it. However, after any version is installed, only
the @code{py exec ...} and @code{pymanager exec ...} commands will install if the
requested version is absent. Other forms of commands will display an error and
direct you to use @code{py install} first.

@node Εντολή βοήθειας,Καταχώριση χρόνων εκτέλεσης,Βασική χρήση,Διαχειριστής εγκατάστασης Python
@anchor{using/windows command-help}@anchor{23f6}
@subsubsection Εντολή βοήθειας


Η εντολή @code{py help} θα εμφανίσει την πλήρη λίστα των υποστηριζόμενων εντολών, μαζί με τις επιλογές τους. Οποιαδήποτε εντολή μπορεί να περάσει την επιλογή @code{-?} για να εμφανίσει τη βοήθειά της, ή το όνομά της μπορεί να περαστεί στην εντολή @code{py help}.

@example
$> py help
$> py help install
$> py install /?
@end example

Όλες οι εντολές υποστηρίζουν μερικές κοινές επιλογές, οι οποίες θα εμφανιστούν από το @code{py help}. Αυτές οι επιλογές πρέπει να καθοριστούν μετά από οποιοδήποτε υποεντολή. Ο καθορισμός του @code{-v} ή @code{--verbose} θα αυξήσει την ποσότητα της εμφανιζόμενης εξόδου, και @code{-vv} θα την αυξήσει περαιτέρω για σκοπούς αποσφαλμάτωσης. Η μετάβαση του @code{-q} ή @code{--quiet} θα μειώσει την έξοδο, και @code{-qq} θα την μειώσει περαιτέρω.

Η επιλογή @code{--config=<PATH>} επιτρέπει τον καθορισμό ενός αρχείου διαμόρφωσης για να παρακαμφθούν πολλές ρυθμίσεις ταυτόχρονα. Δείτε @ref{23f4,,Διαμόρφωση} παρακάτω για περισσότερες πληροφορίες σχετικά με αυτά τα αρχεία.

@node Καταχώριση χρόνων εκτέλεσης,Εγκαθιστώντας χρόνους εκτέλεσης,Εντολή βοήθειας,Διαχειριστής εγκατάστασης Python
@anchor{using/windows listing-runtimes}@anchor{23f7}
@subsubsection Καταχώριση χρόνων εκτέλεσης


@example
$> py list [-f=|--format=<FMT>] [-1|--one] [--online|-s=|--source=<URL>] [<TAG>...]
@end example

Η λίστα των εγκατεστημένων χρόνων εκτέλεσης μπορεί να προβληθεί χρησιμοποιώντας το @code{py list}. Μπορεί να προστεθεί ένα φίλτρο με τη μορφή ενός ή περισσότερων tags (με ή χωρίς καθοριστή εταιρείας), και το καθένα μπορεί να περιλαμβάνει ένα πρόθεμα @code{<}, @code{<=}, @code{>=} ή @code{>} για περιορισμό σε μια περιοχή.

Ένα εύρος μορφών υποστηρίζεται, και μπορεί να περαστεί ως η επιλογή @code{--format=<FMT>} ή @code{-f <FMT>}. Οι μορφές περιλαμβάνουν @code{table} (μια φιλική προς το χρήστη προβολή πίνακα), @code{csv} (πίνακας με κόμμα-διαχωρισμό), @code{json} (ένα μόνο JSON blob), @code{jsonl} (ένα JSON blob ανά αποτέλεσμα), @code{exe} (μόνο η διαδρομή εκτελέσιμου), @code{prefix} (μόνο η διαδρομή προθέματος).

Το @code{--one} ή @code{-1} εμφανίζει μόνο ένα αποτέλεσμα. Εάν περιλαμβάνεται ο προεπιλεγμένος χρόνος εκτέλεσης, θα είναι αυτός. Διαφορετικά, εμφανίζεται το «καλύτερο» αποτέλεσμα (το «καλύτερο» είναι σκόπιμα ασαφώς ορισμένο, αλλά συνήθως θα είναι η πιο πρόσφατη έκδοση). Το αποτέλεσμα που εμφανίζεται από το @code{py list --one <TAG>} θα ταιριάξει με το χρόνο εκτέλεσης που θα εκκινηθεί από το @code{py -V:<TAG>}.

Η επιλογή @code{--only-managed} εξαιρεί αποτελέσματα που δεν εγκαταστάθηκαν από τον διαχειριστή εγκατάστασης Python. Αυτό είναι χρήσιμο κατά τον προσδιορισμό των χρόνων εκτέλεσης που μπορούν να ενημερωθούν ή να απεγκατασταθούν μέσω της εντολής @code{py}.

Η επιλογή @code{--online} είναι συντομογραφία για τη μετάβαση του @code{--source=<URL>} με την προεπιλεγμένη πηγή. Η μετάβαση οποιασδήποτε από αυτές τις επιλογές θα αναζητήσει στο διαδικτυακό ευρετήριο για χρόνους εκτέλεσης που μπορούν να εγκατασταθούν. Το αποτέλεσμα που εμφανίζεται από το @code{py list --online --one <TAG>} θα ταιριάξει με το χρόνο εκτέλεσης που θα εγκατασταθεί από το @code{py install <TAG>}.

@example
$> py list --online 3.14
@end example

Για συμβατότητα με τον παλιό εκκινητή, οι εντολές @code{--list}, @code{--list-paths}, @code{-0} και @code{-0p} (π.χ. @code{py -0p}) διατηρούνται. Δεν επιτρέπουν πρόσθετες επιλογές, και θα παράγουν έξοδο σε παλιά μορφή.

@node Εγκαθιστώντας χρόνους εκτέλεσης,Εγκαταστάσεις εκτός σύνδεσης,Καταχώριση χρόνων εκτέλεσης,Διαχειριστής εγκατάστασης Python
@anchor{using/windows installing-runtimes}@anchor{23f8}
@subsubsection Εγκαθιστώντας χρόνους εκτέλεσης


@example
$> py install [-s=|--source=<URL>] [-f|--force] [-u|--update] [--dry-run] [<TAG>...]
@end example

Νέες εκδόσεις χρόνων εκτέλεσης μπορούν να προστεθούν χρησιμοποιώντας το @code{py install}. Μπορεί να καθοριστεί ένα ή περισσότερα tags, και το ειδικό tag @code{default} μπορεί να χρησιμοποιηθεί για την επιλογή του προεπιλεγμένου. Οι περιοχές δεν υποστηρίζονται για εγκατάσταση.

Η επιλογή @code{--source=<URL>} επιτρέπει την παράκαμψη του διαδικτυακού ευρετηρίου που χρησιμοποιείται για την απόκτηση χρόνων εκτέλεσης. Αυτό μπορεί να χρησιμοποιηθεί με ευρετήριο εκτός σύνδεσης, όπως φαίνεται στο @ref{23f9,,Εγκαταστάσεις εκτός σύνδεσης}.

Περνώντας την επιλογή @code{--force} θα αγνοήσει τυχόν αρχεία στην προσωρινή μνήμη και θα αφαιρέσει οποιαδήποτε υπάρχουσα εγκατάσταση για να την αντικαταστήσει με την καθορισμένη.

Περνώντας την επιλογή @code{--update} θα αντικαταστήσει υπάρχουσες εγκαταστάσεις εάν η νέα έκδοση είναι νεότερη. Διαφορετικά, θα παραμείνουν. Εάν δεν παρέχονται tags με το @code{--update}, όλες οι εγκαταστάσεις που διαχειρίζεται ο διαχειριστής εγκατάστασης Python θα ενημερωθούν εάν υπάρχουν νεότερες εκδόσεις. Οι ενημερώσεις θα αφαιρέσουν τυχόν τροποποιήσεις που έγιναν στην εγκατάσταση, συμπεριλαμβανομένων των παγκοσμίως εγκατεστημένων πακέτων, αλλά τα εικονικά περιβάλλοντα θα συνεχίσουν να λειτουργούν.

Περνώντας την επιλογή @code{--dry-run} θα δημιουργήσει έξοδο και αρχεία καταγραφής, αλλά δεν θα τροποποιήσει καμία εγκατάσταση.

Passing @code{--refresh} will update all registrations for installed runtimes. This
will recreate Start menu shortcuts, registry keys, and global aliases (such as
@code{python3.14.exe} or for any installed scripts). These are automatically
refreshed on installation of any runtime, but may need to be manually refreshed
after installing packages.

In addition to the above options, the @code{--target} option will extract the
runtime to the specified directory instead of doing a normal install.
This is useful for embedding runtimes into larger applications.
Unlike a normal install, @code{py} will not be aware of the extracted runtime,
and no Start menu or other shortcuts will be created.
To launch the runtime, directly execute the main executable (typically
@code{python.exe}) in the target directory.

@example
$> py install ... [-t=|--target=<PATH>] <TAG>
@end example

The @code{py exec} command will install the requested runtime if it is not already
present. This is controlled by the @code{automatic_install} configuration
(
@geindex PYTHON_MANAGER_AUTOMATIC_INSTALL
@geindex μεταβλητή περιβάλλοντος; PYTHON_MANAGER_AUTOMATIC_INSTALL
@ref{23fa,,PYTHON_MANAGER_AUTOMATIC_INSTALL}), and is enabled by default.
If no runtimes are available at all, all launch commands will do an automatic
install if the configuration setting allows. This is to ensure a good experience
for new users, but should not generally be relied on rather than using the
@code{py exec} command or explicit install commands.

@node Εγκαταστάσεις εκτός σύνδεσης,Απεγκατάσταση χρόνων εκτέλεσης,Εγκαθιστώντας χρόνους εκτέλεσης,Διαχειριστής εγκατάστασης Python
@anchor{using/windows offline-installs}@anchor{23fb}@anchor{using/windows pymanager-offline}@anchor{23f9}
@subsubsection Εγκαταστάσεις εκτός σύνδεσης


Για να πραγματοποιήσετε εγκαταστάσεις εκτός σύνδεσης της Python, θα χρειαστεί πρώτα να δημιουργήσετε ένα ευρετήριο εκτός σύνδεσης σε ένα μηχάνημα που έχει πρόσβαση στο δίκτυο.

@example
$> py install --download=<PATH> ... <TAG>...
@end example

Η επιλογή @code{--download=<PATH>} θα κατεβάσει τα πακέτα για τα καταχωρημένα tags και θα δημιουργήσει έναν κατάλογο που τα περιέχει και ένα αρχείο @code{index.json} κατάλληλο για μεταγενέστερη εγκατάσταση. Ολόκληρος αυτός ο κατάλογος μπορεί να μετακινηθεί στο μηχάνημα εκτός σύνδεσης και να χρησιμοποιηθεί για την εγκατάσταση ενός ή περισσότερων από τους παρεχόμενους χρόνους εκτέλεσης:

@example
$> py install --source="<PATH>\index.json" <TAG>...
@end example

Ο διαχειριστής εγκατάστασης Python μπορεί να εγκατασταθεί κατεβάζοντας τον εγκαταστάτη του και μεταφέροντάς τον σε άλλο μηχάνημα πριν την εγκατάσταση.

Διαφορετικά, τα αρχεία ZIP σε έναν κατάλογο ευρετηρίου εκτός σύνδεσης μπορούν απλά να μεταφερθούν σε άλλο μηχάνημα και να εξαχθούν. Αυτό δεν θα καταχωρήσει την εγκατάσταση με κανέναν τρόπο, και έτσι πρέπει να εκκινηθεί αναφερόμενο απευθείας στα εκτελέσιμα αρχεία στον εξαγόμενο φάκελο, αλλά μερικές φορές είναι μια προτιμότερη προσέγγιση σε περιπτώσεις όπου η εγκατάσταση του διαχειριστή εγκατάστασης Python δεν είναι δυνατή ή βολική.

Με αυτόν τον τρόπο, οι χρόνοι εκτέλεσης της Python μπορούν να εγκατασταθούν και να διαχειριστούν σε ένα μηχάνημα χωρίς πρόσβαση στο διαδίκτυο.

@node Απεγκατάσταση χρόνων εκτέλεσης,Διαμόρφωση,Εγκαταστάσεις εκτός σύνδεσης,Διαχειριστής εγκατάστασης Python
@anchor{using/windows uninstalling-runtimes}@anchor{23fc}
@subsubsection Απεγκατάσταση χρόνων εκτέλεσης


@example
$> py uninstall [-y|--yes] <TAG>...
@end example

Οι χρόνοι εκτέλεσης μπορούν να αφαιρεθούν χρησιμοποιώντας την εντολή @code{py uninstall}. Πρέπει να καθοριστούν μία ή περισσότερες ετικέτες. Οι περιοχές δεν υποστηρίζονται εδώ.

Η επιλογή @code{--yes} παρακάμπτει την προτροπή επιβεβαίωσης πριν από την απεγκατάσταση.

Διαφορετικά από το να περάσετε ετικέτες μεμονωμένα, μπορεί να καθοριστεί η επιλογή @code{--purge}. Αυτό θα αφαιρέσει όλους τους χρόνους εκτέλεσης που διαχειρίζεται ο διαχειριστής εγκατάστασης Python, συμπεριλαμβανομένου του καθαρισμού του μενού Έναρξης, του μητρώου και τυχόν προσωρινών αποθηκεύσεων λήψης. Οι χρόνοι εκτέλεσης που δεν εγκαταστάθηκαν από τον διαχειριστή εγκατάστασης Python δεν θα επηρεαστούν, και ούτε τα χειροκίνητα δημιουργημένα αρχεία διαμόρφωσης.

@example
$> py uninstall [-y|--yes] --purge
@end example

Ο διαχειριστής εγκατάστασης Python μπορεί να απεγκατασταθεί μέσω της σελίδας ρυθμίσεων των Windows «Εγκατεστημένες εφαρμογές». Αυτό δεν αφαιρεί κανέναν χρόνο εκτέλεσης, και θα εξακολουθούν να είναι χρησιμοποιήσιμοι, αν και οι παγκόσμιες εντολές @code{python} και @code{py} θα αφαιρεθούν. Η επανεγκατάσταση του διαχειριστή εγκατάστασης Python θα σας επιτρέψει να διαχειριστείτε αυτούς τους χρόνους εκτέλεσης ξανά. Για να καθαρίσετε πλήρως όλους τους χρόνους εκτέλεσης Python, εκτελέστε με @code{--purge} πριν από την απεγκατάσταση του διαχειριστή εγκατάστασης Python.

@node Διαμόρφωση,Γραμμές Shebang,Απεγκατάσταση χρόνων εκτέλεσης,Διαχειριστής εγκατάστασης Python
@anchor{using/windows configuration}@anchor{23fd}@anchor{using/windows pymanager-config}@anchor{23f4}
@subsubsection Διαμόρφωση


Ο διαχειριστής εγκατάστασης Python διαμορφώνεται με μια ιεραρχία αρχείων διαμόρφωσης, μεταβλητών περιβάλλοντος, επιλογών γραμμής εντολών, και ρυθμίσεων μητρώου. Γενικά, τα αρχεία διαμόρφωσης έχουν τη δυνατότητα να διαμορφώσουν τα πάντα, συμπεριλαμβανομένης της τοποθεσίας άλλων αρχείων διαμόρφωσης, ενώ οι ρυθμίσεις μητρώου είναι μόνο για διαχειριστές και θα παρακάμψουν τα αρχεία διαμόρφωσης.

Αυτή η ενότητα θα περιγράψει τις προεπιλογές, αλλά να γνωρίζετε ότι οι τροποποιημένες ή παρακαμφθείσες εγκαταστάσεις μπορεί να επιλύσουν τις ρυθμίσεις διαφορετικά.

A global configuration file may be configured by an administrator, and would be
read first. The user configuration file is stored at
@code{%AppData%\Python\pymanager.json}
(note that this location is under @code{Roaming}, not @code{Local}) and is read next,
overwriting any settings from earlier files. An additional configuration file
may be specified as the @code{PYTHON_MANAGER_CONFIG} environment variable or the
@code{--config} command line option (but not both).
These locations may be modified by administrative customization options listed
later.

Οι ακόλουθες ρυθμίσεις είναι αυτές που θεωρούνται πιθανό να τροποποιηθούν σε κανονική χρήση. Οι επόμενες ενότητες απαριθμούν αυτές που προορίζονται για διοικητική προσαρμογή.

@c Sphinx bug with text writer; remove widths & caption temporarily

@c :widths: 2, 2, 4

@subsubheading Τυπικές επιλογές διαμόρφωσης



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Κλειδί Διαμόρφωσης

@tab

Μεταβλητή Περιβάλλοντος

@tab

Περιγραφή

@item

@code{default_tag}

@tab

@geindex μεταβλητή περιβάλλοντος; PYTHON_MANAGER_DEFAULT
@anchor{using/windows envvar-PYTHON_MANAGER_DEFAULT}@anchor{23f3}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_MANAGER_DEFAULT
@end deffn

@tab

Η προτιμώμενη προεπιλεγμένη έκδοση για εκκίνηση ή εγκατάσταση. Κατά προεπιλογή, αυτό ερμηνεύεται ως η πιο πρόσφατη μη-προκαταρκτική έκδοση από την ομάδα CPython.

@item

@code{default_platform}

@tab

@code{PYTHON_MANAGER_DEFAULT_PLATFORM}

@tab

Η προτιμώμενη προεπιλεγμένη πλατφόρμα για εκκίνηση ή εγκατάσταση. Αυτό αντιμετωπίζεται ως κατάληξη στο καθορισμένο tag, έτσι ώστε το @code{py -V:3.14} θα προτιμούσε μια εγκατάσταση για το @code{3.14-64} εάν υπάρχει (και το @code{default_platform} είναι @code{-64}), αλλά θα χρησιμοποιούσε το @code{3.14} εάν δεν υπάρχει εγκατάσταση με tag.

@item

@code{logs_dir}

@tab

@code{PYTHON_MANAGER_LOGS}

@tab

Η τοποθεσία όπου γράφονται τα αρχεία καταγραφής. Κατά προεπιλογή, @code{%TEMP%}.

@item

@code{automatic_install}

@tab

@geindex μεταβλητή περιβάλλοντος; PYTHON_MANAGER_AUTOMATIC_INSTALL
@anchor{using/windows envvar-PYTHON_MANAGER_AUTOMATIC_INSTALL}@anchor{23fa}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHON_MANAGER_AUTOMATIC_INSTALL
@end deffn

@tab

True to allow automatic installs when using @code{py exec} to launch (or
@code{py} when no runtimes are installed yet).
Other commands will not automatically install, regardless of this
setting.
By default, true.

@item

@code{include_unmanaged}

@tab

@code{PYTHON_MANAGER_INCLUDE_UNMANAGED}

@tab

True για να επιτρέπεται η καταχώριση και η εκκίνηση χρόνων εκτέλεσης που δεν εγκαταστάθηκαν από τον διαχειριστή εγκατάστασης Python, ή false για να τους εξαιρέσετε. Κατά προεπιλογή, true.

@item

@code{shebang_can_run_anything}

@tab

@code{PYTHON_MANAGER_SHEBANG_CAN_RUN_ANYTHING}

@tab

True για να επιτρέπεται στις shebangs σε αρχεία @code{.py} να εκκινούν εφαρμογές εκτός από χρόνους εκτέλεσης Python, ή false για να το αποτρέψετε. Κατά προεπιλογή, true.

@item

@code{log_level}

@tab

@code{PYMANAGER_VERBOSE}, @code{PYMANAGER_DEBUG}

@tab

Ορίζει το προεπιλεγμένο επίπεδο εξόδου (0-50). Κατά προεπιλογή, 20. Χαμηλότερες τιμές παράγουν περισσότερη έξοδο. Οι μεταβλητές περιβάλλοντος είναι boolean, και μπορεί να παράγουν επιπλέον έξοδο κατά την εκκίνηση που αργότερα καταστέλλεται από άλλες ρυθμίσεις.

@item

@code{confirm}

@tab

@code{PYTHON_MANAGER_CONFIRM}

@tab

True για να επιβεβαιώσετε ορισμένες ενέργειες πριν τις εκτελέσετε (όπως η απεγκατάσταση), ή false για να παραλείψετε την επιβεβαίωση. Κατά προεπιλογή, true.

@item

@code{install.source}

@tab

@code{PYTHON_MANAGER_SOURCE_URL}

@tab

Αντικαταστήστε την πηγή του δείκτη για να αποκτήσετε νέες εγκαταστάσεις.

@item

@code{install.enable_entrypoints}

@tab

(none)

@tab

True to generate global commands for installed packages (such as
@code{pip.exe}). These are defined by the packages themselves.
If set to false, only the Python interpreter has global commands created.
By default, true. You should run @code{py install --refresh} after changing
this setting.

@item

@code{list.format}

@tab

@code{PYTHON_MANAGER_LIST_FORMAT}

@tab

Καθορίστε την προεπιλεγμένη μορφή που χρησιμοποιείται από την εντολή @code{py list}. Κατά προεπιλογή, @code{table}.

@item

@code{install_dir}

@tab

(none)

@tab

Καθορίστε τον ριζικό κατάλογο στον οποίο θα εγκατασταθούν οι χρόνοι εκτέλεσης. Εάν αλλάξετε αυτήν τη ρύθμιση, οι προηγουμένως εγκατεστημένοι χρόνοι εκτέλεσης δεν θα είναι χρησιμοποιήσιμοι εκτός εάν τους μετακινήσετε στη νέα τοποθεσία.

@item

@code{global_dir}

@tab

(none)

@tab

Specify the directory where global commands (such as @code{python3.14.exe}
and @code{pip.exe}) are stored.
This directory should be added to your 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} to make the
commands available from your terminal.

@item

@code{download_dir}

@tab

(none)

@tab

Καθορίστε τον κατάλογο όπου αποθηκεύονται τα αρχεία που έχουν ληφθεί. Αυτός ο κατάλογος είναι μια προσωρινή μνήμη και μπορεί να καθαριστεί από καιρό σε καιρό.

@end multitable


Τα ονόματα με τελείες θα πρέπει να είναι εμφωλευμένα μέσα σε αντικείμενα JSON, για παράδειγμα, @code{list.format} θα καθοριζόταν ως @code{@{"list": @{"format": "table"@}@}}.

@node Γραμμές Shebang,Προχωρημένη εγκατάσταση,Διαμόρφωση,Διαχειριστής εγκατάστασης Python
@anchor{using/windows pymanager-shebang}@anchor{23f5}@anchor{using/windows shebang-lines}@anchor{23fe}
@subsubsection Γραμμές Shebang


Εάν η πρώτη γραμμή ενός αρχείου σεναρίου ξεκινά με @code{#!}, είναι γνωστή ως γραμμή «shebang». Τα Linux και άλλα λειτουργικά συστήματα παρόμοια με το Unix έχουν ενσωματωμένη υποστήριξη για τέτοιες γραμμές και χρησιμοποιούνται συνήθως σε τέτοια συστήματα για να υποδείξουν πώς πρέπει να εκτελεστεί ένα script. Οι εντολές @code{python} και @code{py} επιτρέπουν την ίδια δυνατότητα να χρησιμοποιηθεί με scripts Python στα Windows.

Για να επιτρέψετε στις γραμμές shebang σε σενάρια Python να είναι φορητές μεταξύ Unix και Windows, υποστηρίζονται αρκετές “εικονικές” εντολές για να καθορίσετε ποιο διερμηνέα να χρησιμοποιήσετε. Οι υποστηριζόμενες εικονικές εντολές είναι:


@itemize *

@item 
@code{/usr/bin/env <ALIAS>}

@item 
@code{/usr/bin/env -S <ALIAS>}

@item 
@code{/usr/bin/<ALIAS>}

@item 
@code{/usr/local/bin/<ALIAS>}

@item 
@code{<ALIAS>}
@end itemize

Για παράδειγμα, εάν η πρώτη γραμμή του script σας ξεκινά με

@example
#! /usr/bin/python
@end example

Η προεπιλεγμένη Python ή ένα ενεργό εικονικό περιβάλλον θα εντοπιστεί και θα χρησιμοποιηθεί. Καθώς πολλά Python scripts που έχουν γραφεί για να λειτουργούν σε Unix θα έχουν ήδη αυτή τη γραμμή, θα διαπιστώσετε ότι αυτά τα σενάρια μπορούν να χρησιμοποιηθούν από τον εκκινητή χωρίς τροποποίηση. Εάν γράφετε ένα νέο σενάριο στα Windows που ελπίζετε να είναι χρήσιμο σε Unix, θα πρέπει να χρησιμοποιήσετε μία από τις γραμμές shebang που ξεκινούν με @code{/usr}.

Οποιαδήποτε από τις παραπάνω εικονικές εντολές μπορούν να έχουν το @code{<ALIAS>} αντικατασταθεί από ένα ψευδώνυμο από μια εγκατεστημένη runtime. Δηλαδή, οποιαδήποτε εντολή που δημιουργείται στον παγκόσμιο κατάλογο ψευδωνύμων (τον οποίο μπορεί να έχετε προσθέσει στη μεταβλητή περιβάλλοντος 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}) μπορεί να χρησιμοποιηθεί σε ένα shebang, ακόμη και αν δεν είναι στο 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}. Αυτό επιτρέπει τη χρήση shebangs όπως @code{/usr/bin/python3.12} για να επιλέξετε μια συγκεκριμένη runtime.

Εάν δεν υπάρχουν εγκατεστημένοι χρόνοι εκτέλεσης, ή εάν η αυτόματη εγκατάσταση είναι ενεργοποιημένη, ο ζητούμενος χρόνος εκτέλεσης θα εγκατασταθεί εάν είναι απαραίτητο. Δείτε @ref{23f4,,Διαμόρφωση} για πληροφορίες σχετικά με τις ρυθμίσεις διαμόρφωσης.

Η μορφή shebang γραμμής @code{/usr/bin/env} θα αναζητήσει επίσης τη μεταβλητή περιβάλλοντος 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} για μη αναγνωρισμένες εντολές. Αυτό αντιστοιχεί στη συμπεριφορά του προγράμματος Unix @code{env}, το οποίο εκτελεί την ίδια αναζήτηση, αλλά προτιμά την εκκίνηση γνωστών εντολών Python. Μπορεί να εμφανιστεί μια προειδοποίηση κατά την αναζήτηση για αυθαίρετα εκτελέσιμα αρχεία, και αυτή η αναζήτηση μπορεί να απενεργοποιηθεί από την επιλογή διαμόρφωσης @code{shebang_can_run_anything}.

Οι γραμμές shebang που δεν ταιριάζουν με κανένα από τα πρότυπα αντιμετωπίζονται ως `Windows' διαδρομές εκτελέσιμων αρχείων που είναι απόλυτες ή σχετικές προς τον κατάλογο που περιέχει το αρχείο σεναρίου. Αυτό είναι μια ευκολία για σενάρια μόνο για Windows, όπως αυτά που δημιουργούνται από έναν εγκαταστάτη, καθώς η συμπεριφορά δεν είναι συμβατή με κελύφη τύπου Unix. Αυτές οι διαδρομές μπορεί να είναι σε εισαγωγικά, και μπορεί να περιλαμβάνουν πολλαπλά ορίσματα, μετά τα οποία θα προστεθεί η διαδρομή προς το σενάριο και τυχόν πρόσθετα ορίσματα. Αυτή η λειτουργικότητα μπορεί να απενεργοποιηθεί από την επιλογή διαμόρφωσης @code{shebang_can_run_anything}.

@cartouche
@quotation Σημείωση 
Η συμπεριφορά των shebangs στον διαχειριστή εγκατάστασης Python είναι λεπτά διαφορετική από τον προηγούμενο εκκινητή @code{py.exe}, και οι παλιές επιλογές διαμόρφωσης δεν ισχύουν πλέον. Εάν βασίζεστε συγκεκριμένα στην παλιά συμπεριφορά ή διαμόρφωση, συνιστούμε την εγκατάσταση του legacy launcher@footnote{https://www.python.org/ftp/python/3.14.0/win32/launcher.msi}. Η εντολή @code{py} του legacy launcher θα παρακάμψει αυτήν του PyManager από προεπιλογή, και θα χρειαστεί να χρησιμοποιήσετε τις εντολές @code{pymanager} για εγκατάσταση και απεγκατάσταση.
@end quotation
@end cartouche

@node Προχωρημένη εγκατάσταση,Διαχειριστική διαμόρφωση,Γραμμές Shebang,Διαχειριστής εγκατάστασης Python
@anchor{using/windows advanced-installation}@anchor{23ff}@anchor{using/windows pymanager-advancedinstall}@anchor{23f1}
@subsubsection Προχωρημένη εγκατάσταση


Για καταστάσεις όπου ένα MSIX δεν μπορεί να εγκατασταθεί, όπως ορισμένες παλαιότερες πλατφόρμες διανομής για διαχειριστές, υπάρχει ένα MSI διαθέσιμο από τη σελίδα λήψεων του python.org. Αυτό το MSI δεν έχει διεπαφή χρήστη, και μπορεί μόνο να πραγματοποιήσει εγκαταστάσεις ανά μηχάνημα στην προεπιλεγμένη τοποθεσία στα Program Files. Θα προσπαθήσει να τροποποιήσει τη συστημική μεταβλητή 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} για να συμπεριλάβει αυτή την τοποθεσία εγκατάστασης, αλλά βεβαιωθείτε ότι το επαληθεύετε στη διαμόρφωσή σας.

@cartouche
@quotation Σημείωση 
Τα Windows Server 2019 είναι η μόνη έκδοση των Windows που υποστηρίζει η CPython και δεν υποστηρίζει MSIX. Για τα Windows Server 2019, θα πρέπει να χρησιμοποιήσετε το MSI.
@end quotation
@end cartouche

Να γνωρίζετε ότι το πακέτο MSI δεν περιλαμβάνει κανέναν χρόνο εκτέλεσης, και έτσι δεν είναι κατάλληλο για εγκαταστάσεις σε περιβάλλοντα χωρίς σύνδεση στο διαδίκτυο χωρίς επίσης τη δημιουργία ενός ευρετηρίου εγκατάστασης χωρίς σύνδεση. Δείτε @ref{23f9,,Εγκαταστάσεις εκτός σύνδεσης} και @ref{2400,,Διαχειριστική διαμόρφωση} για πληροφορίες σχετικά με τη διαχείριση αυτών των σεναρίων.

Οι χρόνοι εκτέλεσης που εγκαθίστανται από το MSI κοινοποιούνται με αυτούς που εγκαθίστανται από το MSIX, και είναι όλοι μόνο ανά χρήστη. Ο διαχειριστής εγκατάστασης Python δεν υποστηρίζει την εγκατάσταση χρόνων εκτέλεσης ανά μηχάνημα. Για να μιμηθείτε μια εγκατάσταση ανά μηχάνημα, μπορείτε να χρησιμοποιήσετε το @code{py install --target=<shared location>} ως διαχειριστής και να προσθέσετε τις δικές σας τροποποιήσεις σε 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}, το μητρώο, ή το μενού Έναρξης.

Όταν το MSIX είναι εγκατεστημένο, αλλά οι εντολές δεν είναι διαθέσιμες στη 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} μεταβλητή περιβάλλοντος, μπορούν να βρεθούν στο @code{%LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_3847v3x7pw1km} ή @code{%LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0}, ανάλογα με το αν εγκαταστάθηκε από το python.org ή μέσω του Windows Store. Η προσπάθεια εκτέλεσης του εκτελέσιμου απευθείας από τα Program Files δεν συνιστάται.

Για να εγκαταστήσετε προγραμματιστικά τον διαχειριστή εγκατάστασης Python, είναι πιο εύκολο να χρησιμοποιήσετε το WinGet, το οποίο περιλαμβάνεται σε όλες τις υποστηριζόμενες εκδόσεις των Windows:

@example
$> winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity

# Optionally run the configuration checker and accept all changes
$> py install --configure -y
@end example

Για να κατεβάσετε τον διαχειριστή εγκατάστασης Python και να τον εγκαταστήσετε σε άλλο μηχάνημα, η ακόλουθη εντολή WinGet θα κατεβάσει τα απαιτούμενα αρχεία από το Store στον κατάλογο Λήψεις σας (προσθέστε @code{-d <location>} για να προσαρμόσετε την τοποθεσία εξόδου). Αυτό επίσης δημιουργεί ένα αρχείο YAML που φαίνεται να είναι περιττό, καθώς το κατεβασμένο MSIX μπορεί να εγκατασταθεί με την εκκίνηση ή τη χρήση των παρακάτω εντολών.

@example
$> winget download 9NQ7512CXL7T -e --skip-license --accept-package-agreements --accept-source-agreements
@end example

Για να εγκαταστήσετε ή να απεγκαταστήσετε προγραμματιστικά ένα MSIX χρησιμοποιώντας μόνο το PowerShell, συνιστώνται τα PowerShell cmdlets Add-AppxPackage@footnote{https://learn.microsoft.com/powershell/module/appx/add-appxpackage} και Remove-AppxPackage@footnote{https://learn.microsoft.com/powershell/module/appx/remove-appxpackage}:

@example
$> Add-AppxPackage C:\Downloads\python-manager-25.0.msix
...
$> Get-AppxPackage PythonSoftwareFoundation.PythonManager | Remove-AppxPackage
@end example

Η τελευταία έκδοση μπορεί να ληφθεί και να εγκατασταθεί από τα Windows με τη μετάδοση του αρχείου AppInstaller στην εντολή Add-AppxPackage. Αυτό εγκαθιστά χρησιμοποιώντας το MSIX στο python.org, και συνιστάται μόνο για περιπτώσεις όπου η εγκατάσταση μέσω του Store (διαδραστικά ή χρησιμοποιώντας το WinGet) δεν είναι δυνατή.

@example
$> Add-AppxPackage -AppInstallerFile https://www.python.org/ftp/python/pymanager/pymanager.appinstaller
@end example

Άλλα εργαλεία και API μπορούν επίσης να χρησιμοποιηθούν για την παροχή ενός πακέτου MSIX για όλους τους χρήστες σε μια μηχανή, αλλά η Python δεν θεωρεί αυτό ένα υποστηριζόμενο σενάριο. Προτείνουμε να εξετάσετε το PowerShell Add-AppxProvisionedPackage@footnote{https://learn.microsoft.com/powershell/module/dism/add-appxprovisionedpackage} cmdlet, την εγγενή κλάση Windows PackageManager@footnote{https://learn.microsoft.com/uwp/api/windows.management.deployment.packagemanager}, ή την τεκμηρίωση και υποστήριξη για το εργαλείο ανάπτυξής σας.

Ανεξάρτητα από τη μέθοδο εγκατάστασης, οι χρήστες θα πρέπει να εγκαταστήσουν τις δικές τους αντίγραφα της Python, καθώς δεν υπάρχει τρόπος να ενεργοποιηθούν αυτές οι εγκαταστάσεις χωρίς να είναι συνδεδεμένος χρήστης. Όταν χρησιμοποιείτε το MSIX, η τελευταία έκδοση της Python θα είναι διαθέσιμη για όλους τους χρήστες για εγκατάσταση χωρίς πρόσβαση στο δίκτυο.

Σημειώστε ότι το MSIX που μπορεί να ληφθεί από το Store και από τον ιστότοπο της Python είναι ελαφρώς διαφορετικό και δεν μπορούν να εγκατασταθούν ταυτόχρονα. Όπου είναι δυνατόν, προτείνουμε τη χρήση των παραπάνω εντολών WinGet για τη λήψη του πακέτου από το Store για να μειωθεί ο κίνδυνος ρύθμισης συγκρουόμενων εγκαταστάσεων. Δεν υπάρχουν περιορισμοί αδειοδότησης στον διαχειριστή εγκατάστασης Python που να εμποδίζουν τη χρήση του πακέτου Store με αυτόν τον τρόπο.

@node Διαχειριστική διαμόρφωση,Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα,Προχωρημένη εγκατάσταση,Διαχειριστής εγκατάστασης Python
@anchor{using/windows administrative-configuration}@anchor{2401}@anchor{using/windows pymanager-admin-config}@anchor{2400}
@subsubsection Διαχειριστική διαμόρφωση


Υπάρχουν πολλές επιλογές που μπορεί να είναι χρήσιμες για τους διαχειριστές για να υπερκαλύψουν τη διαμόρφωση του διαχειριστή εγκατάστασης Python. Αυτές μπορούν να χρησιμοποιηθούν για την παροχή τοπικής προσωρινής αποθήκευσης, την απενεργοποίηση ορισμένων τύπων συντομεύσεων, την υπερκάλυψη ενσωματωμένου περιεχομένου. Όλες οι παραπάνω επιλογές διαμόρφωσης μπορούν να οριστούν, καθώς και αυτές παρακάτω.

Οι επιλογές διαμόρφωσης μπορούν να υπερκαλυφθούν στο μητρώο ρυθμίζοντας τιμές κάτω από @code{HKEY_LOCAL_MACHINE\Software\Policies\Python\PyManager}, όπου το όνομα της τιμής ταιριάζει με το κλειδί διαμόρφωσης και ο τύπος τιμής είναι @code{REG_SZ}. Σημειώστε ότι αυτό το κλειδί μπορεί να προσαρμοστεί, αλλά μόνο τροποποιώντας το βασικό αρχείο διαμόρφωσης που διανέμεται με τον διαχειριστή εγκατάστασης Python. Ωστόσο, συνιστούμε, ωστόσο, ότι οι τιμές μητρώου χρησιμοποιούνται μόνο για να ορίσουν @code{base_config} σε ένα αρχείο JSON που περιέχει το πλήρες σύνολο των υπερκαλύψεων. Οι υπερκαλύψεις κλειδιών μητρώου θα αντικαταστήσουν οποιαδήποτε άλλη ρυθμισμένη ρύθμιση, ενώ @code{base_config} επιτρέπει στους χρήστες να τροποποιούν περαιτέρω ρυθμίσεις που μπορεί να χρειαστούν.

Σημειώστε ότι οι περισσότερες ρυθμίσεις με μεταβλητές περιβάλλοντος υποστηρίζουν αυτές τις μεταβλητές επειδή η προεπιλεγμένη ρύθμισή τους καθορίζει τη μεταβλητή. Εάν τις υπερκαλύψετε, η μεταβλητή περιβάλλοντος δεν θα λειτουργεί πλέον, εκτός εάν την υπερκαλύψετε με άλλη. Για παράδειγμα, η προεπιλεγμένη τιμή του @code{confirm} είναι κυριολεκτικά @code{%PYTHON_MANAGER_CONFIRM%}, η οποία θα επιλύσει τη μεταβλητή κατά το χρόνο φόρτωσης. Εάν υπερκαλύψετε την τιμή σε @code{yes}, τότε η μεταβλητή περιβάλλοντος δεν θα χρησιμοποιείται πλέον. Εάν υπερκαλύψετε την τιμή σε @code{%CONFIRM%}, τότε θα χρησιμοποιηθεί αυτή η μεταβλητή περιβάλλοντος.

Οι ρυθμίσεις διαμόρφωσης που είναι διαδρομές ερμηνεύονται ως σχετικές με τον κατάλογο που περιέχει το αρχείο διαμόρφωσης που τις καθόρισε.

@c Sphinx bug with text writer; remove widths & caption temporarily

@c :widths: 1, 4

@subsubheading Διαχειριστικές επιλογές διαμόρφωσης



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Κλειδί Διαμόρφωσης

@tab

Περιγραφή

@item

@code{base_config}

@tab

Το αρχείο διαμόρφωσης με την υψηλότερη προτεραιότητα για ανάγνωση. Σημειώστε ότι μόνο το ενσωματωμένο αρχείο διαμόρφωσης και το μητρώο μπορούν να τροποποιήσουν αυτήν τη ρύθμιση.

@item

@code{user_config}

@tab

Το δεύτερο αρχείο διαμόρφωσης για ανάγνωση.

@item

@code{additional_config}

@tab

Το τρίτο αρχείο διαμόρφωσης για ανάγνωση.

@item

@code{registry_override_key}

@tab

Τοποθεσία μητρώου για έλεγχο για υπερκαλύψεις. Σημειώστε ότι μόνο το ενσωματωμένο αρχείο διαμόρφωσης μπορεί να τροποποιήσει αυτήν τη ρύθμιση.

@item

@code{bundled_dir}

@tab

Κατάλογος μόνο για ανάγνωση που περιέχει τοπικά αποθηκευμένα αρχεία.

@item

@code{install.fallback_source}

@tab

Διαδρομή ή URL σε έναν ευρετήριο για συμβουλή όταν δεν είναι δυνατή η πρόσβαση στον κύριο ευρετήριο.

@item

@code{install.enable_shortcut_kinds}

@tab

Λίστα με κόμμα διαχωρισμένων ειδών συντομεύσεων για να επιτρέπονται (π.χ. @code{"pep514,start"}). Οι ενεργοποιημένες συντομεύσεις ενδέχεται ακόμη να απενεργοποιηθούν από το @code{disable_shortcut_kinds}.

@item

@code{install.disable_shortcut_kinds}

@tab

Λίστα με κόμμα διαχωρισμένων ειδών συντομεύσεων για να εξαιρούνται (π.χ. @code{"pep514,start"}). Οι απενεργοποιημένες συντομεύσεις δεν επανενεργοποιούνται από το @code{enable_shortcut_kinds}.

@item

@code{install.hard_link_entrypoints}

@tab

True to use hard links for global shortcuts to save disk space. If false,
each shortcut executable is copied instead. After changing this setting,
you must run @code{py install --refresh --force} to update existing
commands.
By default, true. Disabling this may be necessary for troubleshooting or
systems that have issues with file links.

@item

@code{pep514_root}

@tab

Τοποθεσία μητρώου για ανάγνωση και εγγραφή καταχωρήσεων PEP 514. Από προεπιλογή, @code{HKEY_CURRENT_USER\Software\Python}.

@item

@code{start_folder}

@tab

Φάκελος μενού Έναρξης για εγγραφή συντομεύσεων. Από προεπιλογή, @code{Python}. Αυτή η διαδρομή είναι σχετική με το φάκελο Προγράμματα του χρήστη.

@item

@code{virtual_env}

@tab

Διαδρομή προς το ενεργό εικονικό περιβάλλον. Από προεπιλογή, αυτό είναι @code{%VIRTUAL_ENV%}, αλλά μπορεί να οριστεί κενό για να απενεργοποιηθεί η ανίχνευση venv.

@item

@code{shebang_can_run_anything_silently}

@tab

True για να καταστείλει ορατές προειδοποιήσεις όταν ένα shebang εκκινεί μια εφαρμογή εκτός από μια εκτελέσιμη Python.

@item

@code{source_settings}

@tab

A mapping from source URL to settings specific to that index.
When multiple configuration files include this section, URL settings are
added or overwritten, but individual settings are not merged.
These settings are currently only for @ref{2402,,index signatures}.

@end multitable


@node Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα,Index signatures,Διαχειριστική διαμόρφωση,Διαχειριστής εγκατάστασης Python
@anchor{using/windows install-freethreaded-windows}@anchor{6a3}@anchor{using/windows installing-free-threaded-binaries}@anchor{2403}
@subsubsection Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα



Added in version 3.13.


Οι προ-κατασκευασμένες διανομές της έκδοσης με ελεύθερα νήματα είναι διαθέσιμες με την εγκατάσταση ετικετών με το επίθημα @code{t}.

@example
$> py install 3.14t
$> py install 3.14t-arm64
$> py install 3.14t-32
@end example

Αυτό θα εγκαταστήσει και θα καταχωρήσει ως κανονικό. Εάν δεν έχετε άλλες εκτελέσιμες εγκαταστάσεις, τότε το @code{python} θα εκκινήσει αυτήν. Αλλιώς, θα χρειαστεί να χρησιμοποιήσετε το @code{py -V:3.14t ...} ή, εάν έχετε προσθέσει τον παγκόσμιο κατάλογο ψευδωνύμων στη μεταβλητή περιβάλλοντος 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}, τις εντολές @code{python3.14t.exe}.

@node Index signatures,Αντιμετώπιση προβλημάτων,Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα,Διαχειριστής εγκατάστασης Python
@anchor{using/windows pymanager-index-signatures}@anchor{2402}
@subsubsection Index signatures



Added in version 26.2.


Index files may be signed to detect tampering. A signature is a catalog file
at the same URL as the index with @code{.cat} added to the filename. The catalog
file should contain the hash of its matching index file, and should be signed
with a valid Authenticode signature. This allows standard tooling (on Windows)
to generate a signature, and any certificate may be used as long as the client
operating system already trusts its certification authority (root CA).

Index signatures are only downloaded and checked when the local configuration’s
@code{source_settings} section includes the index URL and @code{requires_signature} is
true, or the index JSON contains @code{requires_signature} set to true. When the
setting exists in local configuration, even when false, settings in the index
are ignored.

As well as requiring a valid signature, the @code{required_root_subject} and
@code{required_publisher_subject} settings can further restrict acceptable
signatures based on the certificate Subject fields. Any attribute specified in
the configuration must match the attribute in the certificate (additional
attributes in the certificate are ignored). Typical attributes are @code{CN=} for
the common name, @code{O=} for the organizational unit, and @code{C=} for the
publisher’s country.

Finally, the @code{required_publisher_eku} setting allows requiring that a specific
Enhanced Key Usage (EKU) has been assigned to the publisher certificate. For
example, the EKU @code{1.3.6.1.5.5.7.3.3} indicates that the certificate was
intended for code signing (as opposed to server or client authentication).
In combination with a specific root CA, this provides another mechanism to
verify a legitimate signature.

This is an example @code{source_settings} section from a configuration file. In
this case, the publisher of the feed is uniquely identified by the combination
of the Microsoft Identity Verification root and the EKU assigned by that root.
The signature for this case would be found at
@code{https://www.python.org/ftp/python/index-windows.json.cat}.

@example
@{
  "source_settings": @{
    "https://www.python.org/ftp/python/index-windows.json": @{
      "requires_signature": true,
      "required_root_subject": "CN=Microsoft Identity Verification Root Certificate Authority 2020",
      "required_publisher_subject": "CN=Python Software Foundation",
      "required_publisher_eku": "1.3.6.1.4.1.311.97.608394634.79987812.305991749.578777327"
    @}
  @}
@}
@end example

The same settings could be specified in the @code{index.json} file instead. In this
case, the root and EKU are omitted, meaning that the signature must be valid and
have a specific common name in the publisher’s certificate, but no other checks
are used.

@example
@{
  "requires_signature": true,
  "required_publisher_subject": "CN=Python Software Foundation",
  "versions": [
    // ...
  ]
@}
@end example

When settings from inside a feed are used, the user is notified and the settings
are shown in the log file or verbose output. It is recommended to copy these
settings into a local configuration file for feeds that will be used frequently,
so that unauthorised modifications to the feed cannot disable verification.

It is not possible to override the location of the signature file in the feed or
through a configuration file. Administrators can provide their own
@code{source_settings} in a mandatory configuration file (see
@ref{2400,,Διαχειριστική διαμόρφωση}).

If signature validation fails, you will be notified and prompted to continue.
When interactive confirmation is not allowed (for example, because @code{--yes} was
specified), it will always abort. To use a feed with invalid configuration in
this scenario, you must provide a configuration file that disables signature
checking for that feed.

@example
"source_settings": @{
  "https://www.example.com/feed-with-invalid-signature.json": @{
    "requires_signature": false
  @}
@}
@end example

@node Αντιμετώπιση προβλημάτων,,Index signatures,Διαχειριστής εγκατάστασης Python
@anchor{using/windows pymanager-troubleshoot}@anchor{23eb}@anchor{using/windows troubleshooting}@anchor{2404}
@subsubsection Αντιμετώπιση προβλημάτων


If your Python install manager does not seem to be working correctly, please
work through these tests and fixes to see if it helps. If not, please report an
issue at our bug tracker@footnote{https://github.com/python/pymanager/issues},
including any relevant log files (written to your @code{%TEMP%} directory by
default).

@c Sphinx bug with text writer; remove widths & caption temporarily

@c :widths: 1, 1

@subsubheading Αντιμετώπιση προβλημάτων



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Σύμπτωμα

@tab

Πράγματα που μπορείτε να δοκιμάσετε

@item

το @code{python} μου δίνει σφάλμα «command not found» ή ανοίγει την εφαρμογή Store όταν το πληκτρολογώ στο τερματικό μου.

@tab

Εγκαταστήσατε το @ref{23ee,,install the Python install manager}

@item

@tab

Κάντε κλικ στο Έναρξη, ανοίξτε το «Διαχείριση εκτέλεσης εφαρμογών» και ελέγξτε ότι τα aliases για το «Python (default)» είναι ενεργοποιημένα. Εάν ήδη είναι, δοκιμάστε να τα απενεργοποιήσετε και να τα ενεργοποιήσετε ξανά για να ανανεώσετε την εντολή. Οι εντολές «Python (default windowed)» και «Python install manager» ενδέχεται επίσης να χρειάζονται ανανέωση.

@item

@tab

Ελέγξτε ότι οι εντολές @code{py} και @code{pymanager} λειτουργούν.

@item

@tab

Ensure your 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} variable contains the entry for
@code{%UserProfile%\AppData\Local\Microsoft\WindowsApps}.
The operating system includes this entry once by default, after other
user paths. If removed, shortcuts will not be found.

@item

Το @code{py} μου δίνει σφάλμα «command not found» όταν το πληκτρολογώ στο τερματικό μου.

@tab

Εγκαταστήσατε το @ref{23ee,,install the Python install manager}

@item

@tab

Κάντε κλικ στο Έναρξη, ανοίξτε το «Διαχείριση εκτέλεσης εφαρμογών» και ελέγξτε ότι τα aliases για το «Python (default)» είναι ενεργοποιημένα. Εάν ήδη είναι, δοκιμάστε να τα απενεργοποιήσετε και να τα ενεργοποιήσετε ξανά για να ανανεώσετε την εντολή. Οι εντολές «Python (default windowed)» και «Python install manager» ενδέχεται επίσης να χρειάζονται ανανέωση.

@item

@tab

Ensure your 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} variable contains the entry for
@code{%UserProfile%\AppData\Local\Microsoft\WindowsApps}.
The operating system includes this entry once by default, after other
user paths. If removed, shortcuts will not be found.

@item

το @code{py} μου δίνει σφάλμα «can’t open file» όταν πληκτρολογώ εντολές στο τερματικό μου.

@tab

Αυτό συνήθως σημαίνει ότι έχετε εγκαταστήσει τον παλιό launcher και έχει προτεραιότητα έναντι του διαχειριστή εγκατάστασης Python. Για να το αφαιρέσετε, κάντε κλικ στο Έναρξη, ανοίξτε το «Εγκατεστημένες εφαρμογές», αναζητήστε το «Python launcher» και απεγκαταστήστε το.

@item

η @code{python} δεν ξεκινά το ίδιο runtime με το @code{py}

@tab

Κάντε κλικ στο Έναρξη, ανοίξτε το «Εγκατεστημένες εφαρμογές», αναζητήστε τους υπάρχοντες Python runtimes και είτε αφαιρέστε τους είτε τροποποιήστε και απενεργοποιήστε τις επιλογές 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}.

@item

@tab

Κάντε κλικ στο Έναρξη, ανοίξτε το «Διαχείριση εκτέλεσης εφαρμογών» και ελέγξτε ότι το alias @code{python.exe} είναι ρυθμισμένο σε «Python (default)»

@item

@code{python} και @code{py} δεν ξεκινούν το runtime που περιμένω

@tab

Ελέγξτε τη μεταβλητή περιβάλλοντος 
@geindex PYTHON_MANAGER_DEFAULT
@geindex μεταβλητή περιβάλλοντος; PYTHON_MANAGER_DEFAULT
@ref{23f3,,PYTHON_MANAGER_DEFAULT} ή τη διαμόρφωση @code{default_tag}. Η εντολή @code{py list} θα εμφανίσει την προεπιλογή σας με βάση αυτές τις ρυθμίσεις.

@item

@tab

Εγκαταστάσεις που διαχειρίζονται από τον διαχειριστή εγκατάστασης Python θα επιλεγούν πριν από τις μη διαχειριζόμενες εγκαταστάσεις. Χρησιμοποιήστε το @code{py install} για να εγκαταστήσετε το runtime που περιμένετε, ή διαμορφώστε την προεπιλεγμένη ετικέτα σας.

@item

@tab

Prerelease and experimental installs that are not managed by the Python
install manager may be chosen ahead of stable releases.
Configure your default tag or uninstall the prerelease runtime
and reinstall it using @code{py install}.

@item

@code{pythonw} ή @code{pyw} δεν ξεκινούν το ίδιο runtime με το @code{python} ή το @code{py}

@tab

Κάντε κλικ στο Έναρξη, ανοίξτε το «Διαχείριση εκτέλεσης εφαρμογών» και ελέγξτε ότι τα aliases σας @code{pythonw.exe} και @code{pyw.exe} είναι συνεπή με τα άλλα.

@item

Το @code{pip} μου δίνει σφάλμα «command not found» όταν το πληκτρολογώ στο τερματικό μου.

@tab

Έχετε ενεργοποιήσει ένα εικονικό περιβάλλον; Εκτελέστε το script @code{.venv\Scripts\activate} στο τερματικό σας για να το ενεργοποιήσετε.

@item

@tab

The package may be available but missing the generated executable.
We recommend using the @code{python -m pip} command instead.
Running @code{py install --refresh} and ensuring that the global shortcuts
directory is on 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} (it will be shown in the command output if
it is not) should make commands such as @code{pip} (and other installed
packages) available.

@item

I installed a package with @code{pip} but its command is not found.

@tab

Έχετε ενεργοποιήσει ένα εικονικό περιβάλλον; Εκτελέστε το script @code{.venv\Scripts\activate} στο τερματικό σας για να το ενεργοποιήσετε.

@item

@tab

New packages do not automatically have global shortcuts created by the
Python install manager. Similarly, uninstalled packages do not have their
shortcuts removed.
Run @code{py install --refresh} to update the global shortcuts for newly
installed packages.

@item

Πληκτρολογώντας @code{script-name.py} στο τερματικό ανοίγει σε νέο παράθυρο.

@tab

Αυτή είναι μια γνωστή περιορισμός του λειτουργικού συστήματος. Είτε καθορίστε @code{py} πριν από το όνομα του script, δημιουργήστε ένα αρχείο batch που περιέχει @code{@@py "%~dpn0.py" %*} με το ίδιο όνομα με το script, είτε εγκαταστήστε τον legacy launcher@footnote{https://www.python.org/ftp/python/3.14.0/win32/launcher.msi} και επιλέξτε τον ως την συσχέτιση για τα scripts.

@item

Το drag-dropping αρχείων σε ένα script δεν λειτουργεί

@tab

Αυτή είναι μια γνωστή περιορισμός του λειτουργικού συστήματος. Υποστηρίζεται με τον legacy launcher@footnote{https://www.python.org/ftp/python/3.14.0/win32/launcher.msi}, ή με τον διαχειριστή εγκατάστασης Python όταν εγκαθίσταται από το MSI.

@item

I have installed the Python install manager multiple times.

@tab

It is possible to install from the Store or WinGet, from the MSIX on
the Python website, and from the MSI, all at once.
They are all compatible and will share configuration and runtimes.

@item

@tab

See the earlier @ref{23f1,,Προχωρημένη εγκατάσταση} section for ways to
uninstall the install manager other than the typical Installed Apps
(Add and Remove Programs) settings page.

@item

My old @code{py.ini} settings no longer work.

@tab

The new Python install manager no longer supports this configuration file
or its settings, and so it will be ignored.
See @ref{23f4,,Διαμόρφωση} for information about configuration settings.

@end multitable


@node Το ενσωματωμένο πακέτο,Τα πακέτα nuget org,Διαχειριστής εγκατάστασης Python,Χρησιμοποιώντας Python στα Windows
@anchor{using/windows the-embeddable-package}@anchor{2405}@anchor{using/windows windows-embeddable}@anchor{23ed}
@subsection Το ενσωματωμένο πακέτο



Added in version 3.5.


Η ενσωματωμένη διανομή είναι ένα αρχείο ZIP που περιέχει ένα ελάχιστο περιβάλλον Python. Προορίζεται για δράση ως μέρος μιας άλλης εφαρμογής, αντί να έχει άμεση πρόσβαση από τους τελικούς χρήστες.

Για να εγκαταστήσετε μια ενσωματωμένη διανομή, προτείνουμε τη χρήση του @code{py install} με την επιλογή @code{--target}:

@example
$> py install 3.14-embed --target=<directory>
@end example

Όταν εξάγεται, η ενσωματωμένη διανομή απομονώνεται (σχεδόν) πλήρως από το σύστημα του χρήστη, συμπεριλαμβανομένων μεταβλητών περιβάλλοντος, ρυθμίσεων μητρώου συστήματος και εγκατεστημένων πακέτων. Η τυπική βιβλιοθήκη περιλαμβάνεται ως προ-μεταγλωττισμένα και βελτιστοποιημένα αρχεία @code{.pyc} σε ένα ZIP και @code{python3.dll}, @code{python313.dll}, @code{python.exe} και @code{pythonw.exe} παρέχονται όλα. Το Tcl/tk (συμπεριλαμβανομένων όλων των εξαρτημένων, όπως το Idle), το pip και η τεκμηρίωση Python δεν συμπεριλαμβάνονται.

Ένα προεπιλεγμένο αρχείο @code{._pth} περιλαμβάνεται, το οποίο περιορίζει περαιτέρω τις προεπιλεγμένες διαδρομές αναζήτησης (όπως περιγράφεται παρακάτω στο @ref{fdf,,Εύρεση modules}). Αυτό το αρχείο προορίζεται για τροποποίηση από ενσωματωτές όπως είναι απαραίτητο.

Τα πακέτα τρίτων θα πρέπει να εγκατασταθούν από το πρόγραμμα εγκατάστασης της εφαρμογής παράλληλα με την ενσωματωμένη διανομή. Η χρήση pip για τη διαχείριση εξαρτήσεων όπως για μια κανονική εγκατάσταση Python δεν υποστηρίζεται με αυτήν τη διανομή, αν και με λίγη προσοχή μπορεί να είναι δυνατό, να συμπεριληφθεί και να χρησιμοποιηθεί το pip για αυτόματες ενημερώσεις. Γενικά, τα πακέτα τρίτων θα πρέπει να αντιμετωπίζονται ως μέρος της εφαρμογής («vendoring»), έτσι ώστε ο προγραμματιστής να μπορεί να διασφαλίσει τη συμβατότητα με νεότερες εκδόσεις προτού παρέχει ενημερώσεις στους χρήστες.

Οι δύο προτεινόμενες περιπτώσεις χρήσης για αυτήν τη διανομή περιγράφονται παρακάτω.

@menu
* Εφαρμογή Python:: 
* Ενσωμάτωση Python:: 

@end menu

@node Εφαρμογή Python,Ενσωμάτωση Python,,Το ενσωματωμένο πακέτο
@anchor{using/windows python-application}@anchor{2406}
@subsubsection Εφαρμογή Python


Μια εφαρμογή γραμμένη σε Python δεν απαιτεί απαραίτητα από τους χρήστες να γνωρίζουν αυτό το γεγονός. Η ενσωματωμένη διανομή μπορεί να χρησιμοποιηθεί σε αυτήν την περίπτωση για να συμπεριλάβει μια ιδιωτική έκδοση της Python σε ένα πακέτο εγκατάστασης. Ανάλογα με το πόσο διαφανές θα πρέπει να είναι (ή αντίστροφα, πόσο επαγγελματικό θα έπρεπε να φαίνεται), υπάρχουν δύο επιλογές.

Η χρήση ενός εξειδικευμένου εκτελέσιμου ως προγράμματος εκκίνησης απαιτεί κάποια κωδικοποίηση, αλλά παρέχει την πιο διαφανής εμπειρία για τους χρήστες. Με έναν προσαρμοσμένο πρόγραμμα εκκίνησης, δεν υπάρχουν προφανείς ενδείξεις ότι το πρόγραμμα εκτελείται σε Python: τα εικονίδια μπορούν να προσαρμοστούν, οι πληροφορίες εταιρείας και έκδοσης μπορούν να καθορίζεται και οι συσχετισμοί αρχείων συμπεριφέρονται σωστά. Στις περισσότερες περιπτώσεις, ένα προσαρμοσμένο πρόγραμμα εκκίνησης θα πρέπει απλώς να μην μπορεί να καλεί το @code{Py_Main} με μια σκληρά κωδικοποιημένη γραμμή εντολών.

Η απλούστερη προσέγγιση είναι να παρέχετε ένα αρχείο δέσμης ή μια συντόμευση που δημιουργείται που καλεί απευθείας το @code{python.exe} ή το @code{pythonw.exe} με τα απαιτούμενα ορίσματα γραμμής εντολών. Σε αυτήν την περίπτωση, η εφαρμογή φαίνεται να είναι Python και όχι το πραγματικό της όνομα, και οι χρήστες μπορεί να έχουν πρόβλημα να το ξεχωρίσουν από άλλες διεργασίες Python που εκτελούνται ή συσχετίσεις αρχείων.

Με την τελευταία προσέγγιση, τα πακέτα θα πρέπει να εγκατασταθούν ως κατάλογοι μαζί με το εκτελέσιμο Python για να διασφαλιστεί ότι είναι διαθέσιμα στην διαδρομή. Με το εξειδικευμένο πρόγραμμα εκκίνησης τα πακέτα μπορούν να βρίσκονται σε άλλες τοποθεσίες, καθώς υπάρχει η ευκαιρία να καθοριστεί η διαδρομή αναζήτησης πριν από την εκκίνηση της εφαρμογής.

@node Ενσωμάτωση Python,,Εφαρμογή Python,Το ενσωματωμένο πακέτο
@anchor{using/windows embedding-python}@anchor{2407}
@subsubsection Ενσωμάτωση Python


Οι εφαρμογές που είναι γραμμένες σε εγγενή κώδικα απαιτούν συχνά κάποια μορφή scripting γλώσσας και η ενσωματωμένη διανομή Python μπορεί να χρησιμοποιηθεί για αυτόν τον σκοπό. Γενικά, η πλειονότητα της εφαρμογής είναι σε εγγενή κώδικα και κάποιο μέρος είτε θα καλέσει το @code{python.exe} ή θα χρησιμοποιήσει απευθείας το @code{python3.dll}. Και στις δύο περιπτώσεις, η εξαγωγή της ενσωματωμένης διανομής σε έναν υποκατάλογο της εγκατάστασης της εφαρμογής αρκεί για να παρέχει έναν διερμηνέα Python με δυνατότητα φόρτωσης.

Όπως και με τη χρήση της εφαρμογής, τα πακέτα μπορούν να εγκατασταθούν σε οποιαδήποτε τοποθεσία, καθώς υπάρχει η ευκαιρία να καθορίσουν διαδρομές αναζήτησης πριν αρχικοποιηθεί ο διερμηνέας. Διαφορετικά , δεν υπάρχουν θεμελιώδεις διαφορές μεταξύ της χρήσης της ενσωματωμένης διανομή και μιας κανονικής εγκατάστασης.

@node Τα πακέτα nuget org,Εναλλακτικά πακέτα,Το ενσωματωμένο πακέτο,Χρησιμοποιώντας Python στα Windows
@anchor{using/windows the-nuget-org-packages}@anchor{2408}@anchor{using/windows windows-nuget}@anchor{23ec}
@subsection Τα πακέτα nuget.org



Added in version 3.5.2.


Το πακέτο nuget.org είναι ένα περιβάλλον Python μειωμένου μεγέθους που προορίζεται για χρήση σε συνεχή ενοποίηση και δημιουργία συστημάτων που δεν έχουν εγκατάσταση Python. Ενώ το nuget είναι «ο διαχειριστής πακέτων για .NET», λειτουργεί επίσης τέλεια για πακέτα που περιέχουν εργαλεία χρόνου κατασκευής.

Επισκεφτείτε το nuget.org@footnote{https://www.nuget.org/} για τις πιο ενημερωμένες πληροφορίες σχετικά με τη χρήση του nuget. Αυτό που ακολουθεί είναι μια περίληψη που είναι επαρκής για προγραμματιστές Python.

Το εργαλείο γραμμής εντολών @code{nuget.exe} μπορεί να ληφθεί απευθείας από το @code{https://aka.ms/nugetclidl}, για παράδειγμα, χρησιμοποιώντας curl ή PowerShell. Με το εργαλείο, η πιο πρόσφατη έκδοση της Python για μηχανήματα 64-bit ή 32-bit εγκαθίστανται χρησιμοποιώντας:

@example
nuget.exe install python -ExcludeVersion -OutputDirectory .
nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .
@end example

Για να επιλέξετε μια συγκεκριμένη έκδοση, προσθέστε ένα @code{-Version 3.x.y}. Ο κατάλογος εξόδου μπορεί να αλλάξει από @code{.}, και το πακέτο να εγκατασταθεί σε έναν υποκατάλογο. Από προεπιλογή, ο υποκατάλογος ονομάζεται όπως και το πακέτο, και χωρίς την επιλογή @code{-ExcludeVersion}, αυτό το όνομα θα περιλαμβάνει τη συγκεκριμένη έκδοση που έχει εγκατασταθεί. Μέσα στον υποκατάλογο υπάρχει ένας κατάλογος @code{tools} που περιέχει την εγκατάσταση 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

Γενικά, τα πακέτα nuget δεν μπορούν να αναβαθμιστούν και οι νεότερες εκδόσεις θα πρέπει να εγκατασταθούν δίπλα-δίπλα και να αναφέρονται χρησιμοποιώντας την πλήρη διαδρομή. Εναλλακτικά, διαγράψτε τον κατάλογο πακέτων με μη αυτόματο τρόπο και εγκαταστήστε τον ξανά. Πολλά συστήματα CI θα το κάνουν αυτόματα εάν δεν διατηρούν αρχεία μεταξύ των εκδόσεων.

Δίπλα στον κατάλογο @code{tools} υπάρχει ένας κατάλογος @code{build\native}. Αυτός περιέχει ένα αρχείο ιδιοτήτων MSBuild @code{python.props} που μπορεί να χρησιμοποιηθεί σε ένα έργο C++ για αναφορά στην εγκατάσταση της Python. Η συμπερίληψη των ρυθμίσεων θα χρησιμοποιεί αυτόματα τις κεφαλίδες και θα εισάγει βιβλιοθήκες στο build σας.

Οι σελίδες πληροφοριών πακέτων στο nuget.org είναι www.nuget.org/packages/python@footnote{https://www.nuget.org/packages/python} για την έκδοση 64 bit, www.nuget.org/packages/pythonx86@footnote{https://www.nuget.org/packages/pythonx86} για την έκδοση 32 bit και www.nuget.org/packages/pythonarm64@footnote{https://www.nuget.org/packages/pythonarm64} για την έκδοση ARM64.

@menu
* Πακέτα με ελεύθερα νήματα:: 

@end menu

@node Πακέτα με ελεύθερα νήματα,,,Τα πακέτα nuget org
@anchor{using/windows free-threaded-packages}@anchor{2409}
@subsubsection Πακέτα με ελεύθερα νήματα



Added in version 3.13.


Πακέτα που περιέχουν ελεύθερα νήματα ονομάζονται python-freethreaded@footnote{https://www.nuget.org/packages/python-freethreaded} για την έκδοση 64 bit, pythonx86-freethreaded@footnote{https://www.nuget.org/packages/pythonx86-freethreaded} για την έκδοση 32 bit και pythonarm64-freethreaded@footnote{https://www.nuget.org/packages/pythonarm64-freethreaded} για την έκδοση ARM64. Αυτά τα πακέτα περιέχουν τόσο τα σημεία εισόδου @code{python3.13t.exe} όσο και @code{python.exe}, και τα δύο από τα οποία εκτελούν ελεύθερα νήματα.

@node Εναλλακτικά πακέτα,Υποστηριζόμενες εκδόσεις των Windows,Τα πακέτα nuget org,Χρησιμοποιώντας Python στα Windows
@anchor{using/windows alternative-bundles}@anchor{240a}
@subsection Εναλλακτικά πακέτα


Εκτός από την τυπική διανομή CPython, υπάρχουν τροποποιημένα πακέτα που περιλαμβάνουν πρόσθετες λειτουργίες.  Ακολουθεί μια λίστα με δημοφιλείς εκδόσεις και τα βασικά χαρακτηριστικά τους:


@table @asis

@item ActivePython@footnote{https://www.activestate.com/products/python/}

Πρόγραμμα εγκατάστασης με συμβατότητα πολλαπλών πλατφορμών, τεκμηρίωση, PyWin32

@item Anaconda@footnote{https://www.anaconda.com/download/}

Δημοφιλείς επιστημονικά modules (όπως το numpy, scipy και pandas) και ο διαχειριστής πακέτων @code{conda}.

@item Enthought Deployment Manager@footnote{https://www.enthought.com/edm/}

«Η επόμενη γενικά Διαχειριστή Περιβάλλοντος και Πακέτων Python».

Προηγουμένως, η Enthought παρείχε το Canopy, αλλά έφτασε στο τέλος της ζωής του το 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/}

Διανομή ειδικά για Windows με προκατασκευασμένα επιστημονικά πακέτα και εργαλεία για την κατασκευή πακέτων.
@end table

Λάβετε υπόψη ότι αυτά τα πακέτα ενδέχεται να μην περιλαμβάνουν τις πιο πρόσφατες εκδόσεις της Python ή άλλες βιβλιοθήκες και δεν διατηρούνται ή υποστηρίζονται από την βασική ομάδα της Python.

@node Υποστηριζόμενες εκδόσεις των Windows,Αφαίρεση του περιορισμού MAX_PATH,Εναλλακτικά πακέτα,Χρησιμοποιώντας Python στα Windows
@anchor{using/windows supported-windows-versions}@anchor{240b}
@subsection Υποστηριζόμενες εκδόσεις των Windows


Όπως ορίζεται στο 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/}, μια έκδοση Python υποστηρίζει μόνο μια πλατφόρμα Windows, ενώ η Microsoft θεωρεί την πλατφόρμα υπό εκτεταμένη υποστήριξη. Αυτό σημαίνει ότι η Python 3.16 υποστηρίζει Windows 8.1 και νεότερες εκδόσεις. Εάν χρειάζεστε υποστήριξη Windows 7, εγκαταστήστε την Python 3.8. Εάν χρειάζεστε υποστήριξη Windows 8.1, εγκαταστήστε την Python 3.12.

@node Αφαίρεση του περιορισμού MAX_PATH,Λειτουργία UTF-8,Υποστηριζόμενες εκδόσεις των Windows,Χρησιμοποιώντας Python στα Windows
@anchor{using/windows max-path}@anchor{fff}@anchor{using/windows removing-the-max-path-limitation}@anchor{240c}
@subsection Αφαίρεση του περιορισμού MAX_PATH


Τα Windows έχουν ιστορικά περιορισμένα μήκη διαδρομής στους 260 χαρακτήρες. Αυτό σήμαινε ότι διαδρομές μεγαλύτερες από αυτό δεν θα επιλύονταν και θα προέκυπταν σφάλματα.

Στις πιο πρόσφατες εκδόσεις των Windows, αυτός ο περιορισμός μπορεί να επεκταθεί σε πάνω από 32.000 χαρακτήρες. Ο διαχειριστής σας θα πρέπει να ενεργοποιήσει την πολιτική ομάδας «Ενεργοποίηση μακρών διαδρομών Win32» ή να ορίσει το @code{LongPathsEnabled} σε @code{1} στο κλειδί μητρώου @code{HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem}.

Αυτό επιτρέπει στη συνάρτηση @ref{32b,,open()}, στο module @ref{a5,,os} και στις περισσότερες άλλες λειτουργίες διαδρομής να αποδέχονται και να επιστρέφουν διαδρομές μεγαλύτερες από 260 χαρακτήρες.

Μετά την αλλαγή της παραπάνω επιλογής, δεν απαιτείται περαιτέρω διαμόρφωση.

@node Λειτουργία UTF-8,Εύρεση modules,Αφαίρεση του περιορισμού MAX_PATH,Χρησιμοποιώντας Python στα Windows
@anchor{using/windows utf-8-mode}@anchor{240d}@anchor{using/windows win-utf8-mode}@anchor{240e}
@subsection Λειτουργία UTF-8



Added in version 3.7.



Άλλαξε στην έκδοση 3.15: Python UTF-8 mode is now enabled by default (
@geindex Python Enhancement Proposals; PEP 686
PEP 686@footnote{https://peps.python.org/pep-0686/}).


Τα Windows εξακολουθούν να χρησιμοποιούν κωδικοποιήσεις παλαιού τύπου για την κωδικοποίηση του συστήματος (τη σελίδα κώδικα ANSI).  Η Python τη χρησιμοποιεί για την προεπιλεγμένη κωδικοποίηση αρχείων κειμένου (π.χ. @ref{a45,,locale.getencoding()}).

Αυτό μπορεί να προκαλέσει προβλήματα επειδή το UTF-8 χρησιμοποιείται ευρέως στο διαδίκτυο και στα περισσότερα συστήματα Unix, συμπεριλαμβανομένου του WSL (Windows Subsystem for Linux).

The @ref{a46,,Python UTF-8 Mode}, enabled by default, can help by
changing the default text encoding to UTF-8.
When the @ref{a46,,UTF-8 mode} is enabled, you can still use the
system encoding (the ANSI Code Page) via the «mbcs» codec.

You can disable the @ref{a46,,Python UTF-8 Mode} via
the @code{-X utf8=0} command line option, or the @code{PYTHONUTF8=0} environment
variable.  See 
@geindex PYTHONUTF8
@geindex μεταβλητή περιβάλλοντος; PYTHONUTF8
@ref{1ad,,PYTHONUTF8} for disabling UTF-8 mode, and
@ref{21b7,,Διαχειριστής εγκατάστασης Python} for how to modify environment variables.

@cartouche
@quotation Συμβουλή 
Adding @code{PYTHONUTF8=@{0,1@}} to the default environment variables
will affect all Python 3.7+ applications on your system.
If you have any Python 3.7+ applications which rely on the legacy
system encoding, it is recommended to set the environment variable
temporarily or use the @code{-X utf8} command line option.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Ακόμη και όταν η λειτουργία UTF-8 είναι απενεργοποιημένη, η Python χρησιμοποιεί το UTF-8 από προεπιλογή στα Windows για:


@itemize *

@item 
I/O κονσόλας με τυπικό I/O (δείτε το 
@geindex Python Enhancement Proposals; PEP 528
PEP 528@footnote{https://peps.python.org/pep-0528/} για λεπτομέρειες).

@item 
Το @ref{948,,filesystem encoding} (δείτε το 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} για λεπτομέρειες).
@end itemize
@end quotation
@end cartouche

@node Εύρεση modules,Πρόσθετα modules,Λειτουργία UTF-8,Χρησιμοποιώντας Python στα Windows
@anchor{using/windows finding-modules}@anchor{240f}@anchor{using/windows windows-finding-modules}@anchor{fdf}
@subsection Εύρεση modules


Αυτές οι σημειώσεις συμπληρώνουν την περιγραφή @ref{1953,,The initialization of the sys.path module search path} με λεπτομερείς σημειώσεις των Windows.

Όταν δεν βρεθεί αρχείο @code{._pth}, συμπληρώνεται έτσι το @ref{194,,sys.path} στα Windows:


@itemize *

@item 
Μια κενή καταχώρηση προστίθεται στην αρχή, η οποία αντιστοιχεί στον τρέχοντα κατάλογο.

@item 
Εάν υπάρχει η μεταβλητή περιβάλλοντος 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH}, όπως περιγράφεται στο @ref{9e8,,Environment variables}, οι εγγραφές της προστίθενται στη συνέχεια.  Σημειώστε ότι στα Windows, οι διαδρομές σε αυτήν τη μεταβλητή πρέπει να διαχωρίζονται με ερωτηματικά, για να γίνει διάκριση από την άνω και κάτω τελεία που χρησιμοποιείται στα αναγνωριστικά μονάδων δίσκου (@code{C:\} κλπ.).

@item 
Μπορούν να προστεθούν επιπλέον «διαδρομές εφαρμογής» στο μητρώο ως δευτερεύοντα κλειδιά του @code{\SOFTWARE\Python\PythonCore@{version@}\PythonPath} κάτω από τις κυψέλες @code{HKEY_CURRENT_USER} και @code{HKEY_LOCAL_MACHINE}.  Τα δευτερεύοντα κλειδιά που έχουν ως προεπιλεγμένη τιμή συμβολοσειρές διαδρομής οριοθετημένη με ερωτηματικό θα προκαλέσει την προσθήκη κάθε διαδρομής στο @ref{194,,sys.path}.  (Λάβετε υπόψη ότι όλα τα γνωστά προγράμματα εγκατάστασης χρησιμοποιούν μόνο HKLM, επομένως το HKCU είναι συνήθως κενό.)

@item 
Εάν έχει οριστεί η μεταβλητή περιβάλλοντος 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME}, θεωρείται ότι είναι «Python Home».  Διαφορετικά, η διαδρομή του κύριου εκτελέσιμου Python χρησιμοποιείται για τον εντοπισμό ενός «αρχείου ορόσημο» (είτε @code{Lib\os.py} ή @code{pythonXY.zip}) για να συμπεράνουμε το «Python Home». Αν βρεθεί ένα Python home, οι σχετικοί υποκατάλογοι που προστέθηκαν στο @ref{194,,sys.path} (@code{Lib}, @code{plat-win}, κ.λπ.) βασίζονται σε αυτόν τον φάκελο.  Διαφορετικά, η διαδρομή του πυρήνα της Python δημιουργείται από το PythonPath που είναι αποθηκευμένο στο μητρώο.

@item 
Εάν δεν μπορεί να εντοπιστεί το Python Home, δεν καθορίζεται 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} στο περιβάλλον και δεν μπορούν να βρεθούν καταχωρίσεις μητρώου, χρησιμοποιείται μια προεπιλεγμένη διαδρομή με σχετικές καταχωρήσεις (π.χ. @code{.\Lib;.\plat-win}, κλπ).
@end itemize

Εάν ένα αρχείο @code{pyvenv.cfg} βρίσκεται δίπλα στο κύριο εκτελέσιμο αρχείο ή στον κατάλογο ένα επίπεδο πάνω από το εκτελέσιμο αρχείο, ισχύουν οι ακόλουθες παραλλαγές:


@itemize *

@item 
Εάν το @code{home} είναι μια απόλυτη διαδρομή και το 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} δεν έχει οριστεί, αυτή η διαδρομή χρησιμοποιείται αντί για τη διαδρομή προς το κύριο εκτελέσιμο κατά την εξαγωγή της αρχικής τοποθεσίας.
@end itemize

Το τελικό αποτέλεσμα όλων αυτών είναι:


@itemize *

@item 
Όταν εκτελείται το @code{python.exe}, ή οποιοδήποτε άλλο .exe στον κύριο κατάλογο της Python (είτε μια εγκατεστημένη έκδοση, είτε απευθείας από τον κατάλογο PCbuild), συνάγεται η διαδρομή του πυρήνα και οι βασικές διαφορές στο μητρώο αγνοούνται.  Άλλες «διαδρομές εφαρμογής» στο μητρώο διαβάζονται πάντα.

@item 
Όταν η Python φιλοξενείται σε άλλο .exe (διαφορετικός κατάλογος, ενσωματωμένος μέσω COM, κ.λπ.), το «Python Home» δεν θα συναχθεί επομένως χρησιμοποιείται η βασική διαδρομή από το μητρώο.  Άλλες «διαδρομές εφαρμογής» στο μητρώο διαβάζονται πάντα.

@item 
Εάν η Python δεν μπορεί να βρει το home της και δεν υπάρχει τιμή μητρώου (frozen .exe, κάποια πολύ περίεργη εγκατάσταση) λαμβάνετε μια διαδρομή με κάποιες προεπιλεγμένες, αλλά σχετικές, διαδρομές.
@end itemize

Για όσους θέλουν να ενσωματώσουν την Python στην εφαρμογή ή την διανομή τους, οι ακόλουθες συμβουλές θα αποτρέψουν τις διενέξεις με άλλες εγκαταστάσεις:


@itemize *

@item 
Συμπεριλάβετε ένα αρχείο @code{._pth} δίπλα στο εκτελέσιμο αρχείο σας που περιέχει τους καταλόγους που θέλετε να συμπεριλάβετε. Αυτό θα αγνοήσει τις διαδρομές που παρατίθενται στο μητρώο και τις μεταβλητές περιβάλλοντος και θα αγνοήσει επίσης το @ref{cf,,site} εκτός εάν αναφέρεται το @code{import site}.

@item 
Εάν φορτώνετε το @code{python3.dll} ή το @code{python37.dll} στο δικό σας εκτελέσιμο αρχείο, ορίστε ρητά το @ref{834,,PyConfig.module_search_paths} πριν από το @ref{60a,,Py_InitializeFromConfig()}.

@item 
Διαγράψτε και/ή αντικαταστήστε το 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} και ορίστε το 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} πριν από την εκκίνηση του @code{python.exe} από την εφαρμογή σας.

@item 
Εάν δεν μπορείτε να χρησιμοποιήσετε τις προηγούμενες προτάσεις (για παράδειγμα, είστε μια διανομή που επιτρέπει στους χρήστες να εκτελούν απευθείας το @code{python.exe}), βεβαιωθείτε ότι το αρχείο ορόσημο (@code{Lib\os.py}) υπάρχει στον κατάλογο εγκατάστασης σας. (Λάβετε υπόψη ότι δεν θα εντοπιστεί σε ένα αρχείο ZIP, αλλά θα εντοπιστεί ένα αρχείο ZIP με το σωστό όνομα.)
@end itemize

Αυτά θα διασφαλίσουν ότι τα αρχεία σε μια εγκατάσταση σε όλο το σύστημα δεν θα υπερισχύουν του αντιγράφου της τυπικής βιβλιοθήκης που συνοδεύει την εφαρμογή σας. Διαφορετικά, οι χρήστες σας ενδέχεται να αντιμετωπίσουν προβλήματα με τη χρήση της εφαρμογής σας. Λάβετε υπόψη ότι η πρώτη πρόταση είναι η καλύτερη, καθώς τα άλλα μπορεί να εξακολουθούν να είναι επιρρεπή σε μη τυπικές διαδρομές στο μητρώο και στα πακέτα ιστοτόπων χρηστών.


Άλλαξε στην έκδοση 3.6: Προσθήκη υποστήριξης αρχείου @code{._pth} και καταργείται η επιλογή  @code{applocal} από το @code{pyvenv.cfg}.



Άλλαξε στην έκδοση 3.6: Προσθήκη @code{python`XX'.zip} ως πιθανό ορόσημο όταν βρίσκεται ακριβώς δίπλα στο εκτελέσιμο αρχείο.



Αποσύρθηκε στην έκδοση 3.6: Τα modules που καθορίζονται στο μητρώο στην περιοχή @code{Modules} (όχι @code{PythonPath}) μπορούν να εισαχθούν από το @ref{10e2,,importlib.machinery.WindowsRegistryFinder}. Αυτό το πρόγραμμα εύρεσης είναι ενεργοποιημένο στα Windows σε 3.6.0 και παλαιότερες εκδόσεις, αλλά ενδέχεται να πρέπει να προστεθεί ρητά στο @ref{10e3,,sys.meta_path} στο μέλλον.


@node Πρόσθετα modules,Μεταγλώττιση Python στα Windows,Εύρεση modules,Χρησιμοποιώντας Python στα Windows
@anchor{using/windows additional-modules}@anchor{2410}
@subsection Πρόσθετα modules


Αν και η Python στοχεύει να είναι φορητή σε όλες τις πλατφόρμες, υπάρχουν δυνατότητες που είναι μοναδικές για τα Windows.  Μερικά modules, τόσο στην τυπική βιβλιοθήκη όσο και στην εξωτερική, και αποσπάσματα υπάρχουν για χρήση αυτών των δυνατοτήτων.

Τα τυπικά modules ειδικά για Windows τεκμηριώνονται στο @ref{2411,,MS Windows Specific Services}.

@menu
* PyWin32:: 
* cx_Freeze:: 

@end menu

@node PyWin32,cx_Freeze,,Πρόσθετα modules
@anchor{using/windows pywin32}@anchor{2412}
@subsubsection PyWin32


Το module PyWin32@footnote{https://pypi.org/project/pywin32} του Mark Hammond είναι μια συλλογή από modules για προηγμένη υποστήριξη ειδικά για Windows.  Αυτό περιλαμβάνει βοηθητικά προγράμματα για:


@itemize *

@item 
Component Object Model@footnote{https://docs.microsoft.com/en-us/windows/win32/com/component-object-model--com--portal} (COM)

@item 
Win32 API κλήσεις

@item 
Μητρώο

@item 
Μητρώο συμβάντων

@item 
Τα Microsoft Foundation Classes@footnote{https://docs.microsoft.com/en-us/cpp/mfc/mfc-desktop-applications} (MFC) διεπαφές χρήστη
@end itemize

Το PythonWin@footnote{https://web.archive.org/web/20060524042422/https://www.python.org/windows/pythonwin/} είναι ένα δείγμα εφαρμογής MFC που αποστέλλεται με το PyWin32.  Είναι ένα ενσωματωμένο IDE με ενσωματωμένο πρόγραμμα εντοπισμού σφαλμάτων.


@subsubheading Δείτε επίσης



@table @asis

@item Win32 How Do I...?@footnote{http://timgolden.me.uk/python/win32_how_do_i.html}

από τον Tim Golden

@item Python and COM@footnote{https://www.boddie.org.uk/python/COM.html}

από τους David και Paul Boddie
@end table


@node cx_Freeze,,PyWin32,Πρόσθετα modules
@anchor{using/windows cx-freeze}@anchor{2413}
@subsubsection cx_Freeze


Το cx_Freeze@footnote{https://cx-freeze.readthedocs.io/en/latest/} αναδιπλώνει Python scripts σε εκτελέσιμα προγράμματα των Windows (@code{`*'.exe} αρχεία). Όταν το κάνετε αυτό, μπορείτε να διανείμετε την εφαρμογή σας χωρίς να απαιτείται από τους χρήστες σας να εγκαταστήσουν την Python.

@node Μεταγλώττιση Python στα Windows,Το πλήρες πρόγραμμα εγκατάστασης,Πρόσθετα modules,Χρησιμοποιώντας Python στα Windows
@anchor{using/windows compiling-python-on-windows}@anchor{2414}
@subsection Μεταγλώττιση Python στα Windows


Εάν θέλετε να μεταγλωττίσετε μόνοι σας το CPython, το πρώτο πράγμα που πρέπει να κάνετε είναι να λάβετε το source@footnote{https://www.python.org/downloads/source/}. Μπορείτε να κάνετε λήψη είτε τον πηγαίο κώδικα της πιο πρόσφατης έκδοσης είτε απλώς να πάρετε μια φρέσκια έκδοση checkout@footnote{https://devguide.python.org/setup/#get-the-source-code}.

Το δέντρο προέλευσης περιέχει μια λύση έκδοσης και αρχεία έργου για το Microsoft Visual Studio, που είναι ο μεταγλωττιστής που χρησιμοποιείται για τη δημιουργία των επίσημων εκδόσεων Python. Αυτά τα αρχεία βρίσκονται στον κατάλογο @code{PCbuild}.

Ελέγξτε το @code{PCbuild/readme.txt} για γενικές πληροφορίες σχετικά με τη διαδικασία κατασκευής.

Για modules επέκτασης, συμβουλευτείτε το @ref{2415,,Building C and C++ Extensions on Windows}.

@node Το πλήρες πρόγραμμα εγκατάστασης,Το πρόγραμμα εκκίνησης Python για Windows Απαρχαιωμένο,Μεταγλώττιση Python στα Windows,Χρησιμοποιώντας Python στα Windows
@anchor{using/windows the-full-installer-deprecated}@anchor{2416}@anchor{using/windows windows-full}@anchor{2417}
@subsection Το πλήρες πρόγραμμα εγκατάστασης



Αποσύρθηκε στην έκδοση 3.14: Αυτό το πρόγραμμα εγκατάστασης έχει αποσυρθεί από την έκδοση 3.14 και δεν θα παραχθεί για την Python 3.16 ή νεότερη έκδοση. Δείτε το @ref{23ee,,Διαχειριστής εγκατάστασης Python} για το σύγχρονο πρόγραμμα εγκατάστασης.


@menu
* Βήματα Εγκατάστασης:: 
* Αφαίρεση του περιορισμού MAX_PATH: Αφαίρεση του περιορισμού MAX_PATH<2>. 
* Εγκατάσταση χωρίς περιβάλλον διεπαφής χρήστη:: 
* Εγκατάσταση χωρίς λήψη:: 
* Τροποποίηση εγκατάστασης:: 
* Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα: Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα<2>. 

@end menu

@node Βήματα Εγκατάστασης,Αφαίρεση του περιορισμού MAX_PATH<2>,,Το πλήρες πρόγραμμα εγκατάστασης
@anchor{using/windows installation-steps}@anchor{2418}
@subsubsection Βήματα Εγκατάστασης


Τέσσερα προγράμματα εγκατάστασης Python 3.16 είναι διαθέσιμα για λήψη - δύο το καθένα για τις εκδόσεις 32-bit και 64-bit του διερμηνέα. Το `πρόγραμμα εγκατάστασης web' είναι μια αρχική λήψη και θα πραγματοποιήσει αυτόματα λήψη των απαιτούμενων στοιχείων, όπως απαιτείται. Το `πρόγραμμα εγκατάστασης εκτός σύνδεσης' περιλαμβάνει τα στοιχεία που είναι απαραίτητα για μια προεπιλεγμένη εγκατάσταση και απαιτεί μόνο σύνδεση στο διαδίκτυο για προαιρετικές λειτουργίες. Δείτε το @ref{2419,,Εγκατάσταση χωρίς λήψη} για άλλους τρόπους αποφυγής λήψης κατά την εγκατάσταση.

Μετά την εκκίνηση του προγράμματος εγκατάστασης, μπορεί να επιλέγει μία από τις δύο επιλογές:

@image{python-figures/win_installer,,,,png}

Εάν επιλέξετε «Install Now»:


@itemize *

@item 
`Δεν' θα χρειάζεται να είστε διαχειριστής (εκτός εάν απαιτείται ενημέρωση συστήματος για τη Βιβλιοθήκη C Runtime ή εγκαταστήσετε το @ref{9bc,,Διαχειριστής εγκατάστασης Python} για όλους τους χρήστες)

@item 
Η Python θα εγκατασταθεί στον κατάλογο του χρήστη σας

@item 
Το @ref{9bc,,Διαχειριστής εγκατάστασης Python} θα εγκατασταθεί σύμφωνα με την επιλογή στο κάτω μέρος της πρώτης σελίδας

@item 
Θα εγκατασταθεί η τυπική βιβλιοθήκη, η δοκιμαστική σουίτα, ο εκκινητής και το pip

@item 
Εάν επιλεγεί, ο κατάλογος εγκατάστασης θα προστεθεί στο 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} σας

@item 
Οι συντομεύσεις θα είναι ορατές μόνο για τον τρέχοντα χρήστη
@end itemize

Επιλέγοντας «Customize installation» θα σας επιτρέψει να επιλέξετε τις λειτουργίες προς εγκατάσταση, τη θέση εγκατάστασης και άλλες επιλογές ή ενέργειες μετά την εγκατάσταση. Για να εγκαταστήσετε σύμβολα εντοπισμού σφαλμάτων ή δυαδικά αρχεία, θα χρειαστεί να χρησιμοποιήσετε αυτήν την επιλογή.

Για να εκτελέσετε μια εγκατάσταση για όλους τους χρήστες, θα πρέπει να επιλέξετε «Customize installation». Σε αυτήν την περίπτωση:


@itemize *

@item 
Ενδέχεται να σας ζητηθεί να παρέχετε διαπιστευτήρια διαχείρισης ή έγκριση

@item 
Η Python θα εγκατασταθεί στον κατάλογο Program Files

@item 
Το @ref{9bc,,Διαχειριστής εγκατάστασης Python} θα εγκατασταθεί στον κατάλογο των Windows

@item 
Προαιρετικά χαρακτηριστικά μπορούν να επιλεγούν κατά την εγκατάσταση

@item 
Η τυπική βιβλιοθήκη μπορεί να προ-μεταγλωττιστεί σε bytecode

@item 
Εάν επιλεγεί, ο κατάλογος εγκατάστασης θα προστεθεί στο σύστημα 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}

@item 
Οι συντομεύσεις είναι διαθέσιμες για όλους τους χρήστες
@end itemize

@node Αφαίρεση του περιορισμού MAX_PATH<2>,Εγκατάσταση χωρίς περιβάλλον διεπαφής χρήστη,Βήματα Εγκατάστασης,Το πλήρες πρόγραμμα εγκατάστασης
@anchor{using/windows id2}@anchor{241a}
@subsubsection Αφαίρεση του περιορισμού MAX_PATH


Τα Windows έχουν ιστορικά περιορισμένα μήκη διαδρομής στους 260 χαρακτήρες. Αυτό σήμαινε ότι διαδρομές μεγαλύτερες από αυτό δεν θα επιλύονταν και θα προέκυπταν σφάλματα.

Στις πιο πρόσφατες εκδόσεις των Windows, αυτός ο περιορισμός μπορεί να επεκταθεί σε περίπου 32.000 χαρακτήρες. Ο διαχειριστής σας θα πρέπει να ενεργοποιήσει την πολιτική ομάδας «Enable Win32 long paths», ή να ορίσει @code{LongPathsEnabled} σε @code{1} το κλειδί μητρώου @code{HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem}.

Αυτό επιτρέπει στη συνάρτηση @ref{32b,,open()}, στο module @ref{a5,,os} και στις περισσότερες άλλες λειτουργίες διαδρομής να αποδέχονται και να επιστρέφουν διαδρομές μεγαλύτερες από 260 χαρακτήρες.

Μετά την αλλαγή της παραπάνω επιλογής, δεν απαιτείται περαιτέρω διαμόρφωση.


Άλλαξε στην έκδοση 3.6: Η υποστήριξη για μεγάλες διαδρομές ήταν ενεργοποιημένη στην Python.


@node Εγκατάσταση χωρίς περιβάλλον διεπαφής χρήστη,Εγκατάσταση χωρίς λήψη,Αφαίρεση του περιορισμού MAX_PATH<2>,Το πλήρες πρόγραμμα εγκατάστασης
@anchor{using/windows install-quiet-option}@anchor{9e5}@anchor{using/windows installing-without-ui}@anchor{241b}
@subsubsection Εγκατάσταση χωρίς περιβάλλον διεπαφής χρήστη


Όλες οι διαθέσιμες επιλογές στη διεπαφή χρήστη του προγράμματος εγκατάστασης μπορούν επίσης να καθοριστούν από τη γραμμή εντολών, επιτρέποντας στους εγκαταστάτες με script να αναπαράγουν μια εγκατάσταση σε πολλά μηχανήματα χωρίς αλληλεπίδραση με τον χρήστη. Αυτές οι επιλογές μπορούν επίσης να οριστούν χωρίς να καταργηθεί η διεπαφή χρήστη προκειμένου να αλλάξουν ορισμένες από τις προεπιλογές.

Οι ακόλουθες επιλογές (που βρίσκονται εκτελώντας το πρόγραμμα εγκατάστασης με @code{/?}) μπορούν να περάσουν στο πρόγραμμα εγκατάστασης:


@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Όνομα

@tab

Περιγραφή

@item

/passive

@tab

για εμφάνιση προόδου χωρίς να απαιτείται αλληλεπίδραση με τον χρήστη

@item

/quiet

@tab

για εγκατάσταση/απεγκατάσταση χωρίς εμφάνιση διεπαφής χρήστη

@item

/simple

@tab

για να αποτρέψετε την προσαρμογή του χρήστη

@item

/uninstall

@tab

για να αφαιρέσετε την Python (χωρίς επιβεβαίωση)

@item

/layout [κατάλογος]

@tab

για προ-λήψη όλων των στοιχείων

@item

/log [όνομα αρχείου]

@tab

για να καθορίσετε τη θέση των αρχείων καταγραφής

@end multitable


Όλες οι άλλες επιλογές μεταβιβάζονται ως @code{name=value}, όπου η τιμή είναι συνήθως @code{0} για να απενεργοποιήσετε ένα χαρακτηριστικό, @code{1} για να ενεργοποιήσετε ένα χαρακτηριστικό ή μια διαδρομή. Η πλήρης λίστα των διαθέσιμων επιλογών φαίνεται παρακάτω.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Όνομα

@tab

Περιγραφή

@tab

Προεπιλογή

@item

InstallAllUsers

@tab

Εκτέλεση εγκατάστασης σε όλο το σύστημα.

@tab

0

@item

TargetDir

@tab

Ο κατάλογος εγκατάστασης

@tab

Επιλέχθηκε με βάση το InstallAllUsers

@item

DefaultAllUsersTargetDir

@tab

Ο προεπιλεγμένος κατάλογος εγκατάστασης για τις εγκαταστάσεις όλων των χρηστών

@tab

@code{%ProgramFiles%\Python X.Y} or @code{%ProgramFiles(x86)%\Python X.Y}

@item

DefaultJustForMeTargetDir

@tab

Ο προεπιλεγμένος κατάλογος εγκατάστασης για εξατομικευμένες εγκαταστάσεις

@tab

@code{%LocalAppData%\Programs\Python\PythonXY} or
@code{%LocalAppData%\Programs\Python\PythonXY-32} or
@code{%LocalAppData%\Programs\Python\PythonXY-64}

@item

DefaultCustomTargetDir

@tab

Ο προεπιλεγμένος κατάλογος προσαρμοσμένης εγκατάστασης που εμφανίζεται στο UI

@tab

(empty)

@item

AssociateFiles

@tab

Δημιουργήστε συσχετίσεις αρχείων εάν είναι επίσης εγκατεστημένο το πρόγραμμα εκκίνησης.

@tab

1

@item

CompileAll

@tab

Μεταγλώττιση όλων των αρχείων @code{.py} σε @code{.pyc}.

@tab

0

@item

PrependPath

@tab

Προετοιμάστε τους καταλόγους εγκατάστασης και Scripts στο 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} και προσθέστε το @code{.PY} στο 
@geindex PATHEXT
@geindex μεταβλητή περιβάλλοντος; PATHEXT
@code{PATHEXT}

@tab

0

@item

AppendPath

@tab

Προσθήκη καταλόγων εγκατάστασης και Scripts σε 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} και προσθήκη @code{.PY} σε 
@geindex PATHEXT
@geindex μεταβλητή περιβάλλοντος; PATHEXT
@code{PATHEXT}

@tab

0

@item

Συντομεύσεις

@tab

Δημιουργήστε συντομεύσεις για τον διερμηνέα, την τεκμηρίωση και το IDLE εάν είναι εγκατεστημένα.

@tab

1

@item

Include_doc

@tab

Εγκαταστήστε το εγχειρίδιο της Python

@tab

1

@item

Include_debug

@tab

Εγκαταστήστε δυαδικά αρχεία εντοπισμού σφαλμάτων

@tab

0

@item

Include_dev

@tab

Εγκατάσταση κεφαλίδων και βιβλιοθηκών προγραμματιστή. Η παράλειψη αυτού μπορεί να οδηγήσει σε μη χρησιμοποιήσιμη εγκατάσταση.

@tab

1

@item

Include_exe

@tab

Εγκατάσταση @code{python.exe} και σχετικών αρχείων. Η παράλειψη αυτού μπορεί να οδηγήσει σε μη χρησιμοποιήσιμη εγκατάσταση.

@tab

1

@item

Include_launcher

@tab

Εγκαταστήστε το @ref{9bc,,Διαχειριστής εγκατάστασης Python}.

@tab

1

@item

InstallLauncherAllUsers

@tab

Εγκαθιστά το πρόγραμμα εκκίνησης για όλους του χρήστες. Επίσης, απαιτείται η ρύθμιση @code{Include_launcher} να τεθεί σε 1

@tab

1

@item

Include_lib

@tab

Εγκαταστήστε τυπικά module βιβλιοθήκης και επέκτασης. Η παράλειψη αυτού μπορεί να οδηγήσει σε μη χρησιμοποιήσιμη εγκατάσταση.

@tab

1

@item

Include_pip

@tab

Εγκαταστήστε το πακέτο pip και setuptools

@tab

1

@item

Include_symbols

@tab

Εγκατάσταση συμβόλων εντοπισμού σφαλμάτων (@code{*.pdb})

@tab

0

@item

Include_tcltk

@tab

Εγκατάσταση υποστήριξης Tcl/Tk και IDLE

@tab

1

@item

Include_test

@tab

Εγκαταστήστε την τυπική σουίτα δοκιμών βιβλιοθήκης

@tab

1

@item

Include_tools

@tab

Εγκαταστήστε βοηθητικά scripts

@tab

1

@item

LauncherOnly

@tab

Εγκαθιστά μόνο το πρόγραμμα εκκίνησης. Αυτό θα παρακάμψει τις περισσότερες άλλες επιλογές.

@tab

0

@item

SimpleInstall

@tab

Απενεργοποιήστε τις περισσότερες διεπαφές εγκατάστασης

@tab

0

@item

SimpleInstallDescription

@tab

Ένα προσαρμοσμένο μήνυμα που θα εμφανίζεται όταν χρησιμοποιείται το απλοποιημένο περιβάλλον διεπαφής χρήστη.

@tab

(empty)

@end multitable


Για παράδειγμα, για να εγκαταστήσετε αθόρυβα μια προεπιλεγμένη εγκατάσταση Python σε όλο το σύστημα, θα μπορούσατε να χρησιμοποιήσετε την ακόλουθη εντολή (από μια ανυψωμένη γραμμή εντολών):

@example
python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0
@end example

Για να επιτρέψετε στους χρήστες να εγκαταστήσουν εύκολα ένα προσωπικό αντίγραφο της Python χωρίς τη δοκιμαστική σουίτα, θα μπορούσατε να παρέχετε μια συντόμευση με την ακόλουθη εντολή. Αυτή θα εμφανίσει μια απλοποιημένη αρχική σελίδα και θα απαγορεύσει την προσαρμογή:

@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

(Λάβετε υπόψη ότι η παράλειψη της εφαρμογής εκκίνησης παραλείπει επίσης συσχετίσεις αρχείων και συνίσταται μόνο για εγκαταστάσεις ανά χρήστη όταν υπάρχει επίσης εγκατάσταση σε όλο το σύστημα που περιλάμβανε τη λειτουργία εκκίνησης.)

Οι επιλογές που αναφέρονται παραπάνω μπορούν επίσης να παρέχονται σε ένα αρχείο με το όνομα @code{unattend.xml} δίπλα στο εκτελέσιμο αρχείο. Αυτό το αρχείο καθορίζει μια λίστα επιλογών και τιμών. Όταν μια τιμή παρέχεται ως χαρακτηριστικό, θα μετατραπεί σε αριθμό εάν είναι δυνατόν. Οι τιμές που παρέχονται ως κείμενο στοιχείου παραμένουν πάντα ως συμβολοσειρές. Αυτό το αρχείο παραδείγματος ορίζει τις ίδιες επιλογές με το προηγούμενο παράδειγμα:

@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 Εγκατάσταση χωρίς λήψη,Τροποποίηση εγκατάστασης,Εγκατάσταση χωρίς περιβάλλον διεπαφής χρήστη,Το πλήρες πρόγραμμα εγκατάστασης
@anchor{using/windows install-layout-option}@anchor{2419}@anchor{using/windows installing-without-downloading}@anchor{241c}
@subsubsection Εγκατάσταση χωρίς λήψη


Καθώς ορισμένες δυνατότητες της Python δεν περιλαμβάνονται στην αρχική λήψη του προγράμματος εγκατάστασης, η επιλογή αυτών των δυνατοτήτων ενδέχεται να απαιτεί σύνδεση στο διαδίκτυο.  Για να αποφευχθεί αυτή η ανάγκη, όλα τα πιθανά στοιχεία μπορούν να ληφθούν κατ” απαίτηση για να δημιουργηθεί μια πλήρης `διάταξη' που δεν θα απαιτεί πλέον μια σύνδεση στο Διαδίκτυο, ανεξάρτητα από τις επιλεγμένες δυνατότητες. Λάβετε υπόψη ότι αυτή η λήψη μπορεί να είναι μεγαλύτερη από την απαιτούμενη, αλλά όπου πρόκειται να πραγματοποιηθεί μεγάλος αριθμός εγκαταστάσεων, είναι πολύ χρήσιμο να έχετε ένα αντίγραφο προσωρινής αποθήκευσης.

Εκτελέστε την ακόλουθη εντολή από τη Γραμμή Εντολών για λήψη όλων των πιθανών απαιτούμενων αρχείων.  Θυμηθείτε να αντικαταστήσετε το @code{python-3.9.0.exe} για το πραγματικό όνομα του προγράμματος εγκατάστασης και να δημιουργήσετε διατάξεις στους δικούς τους καταλόγους για να αποφύγετε συγκρούσεις μεταξύ αρχείων με το ίδιο όνομα.

@example
python-3.9.0.exe /layout [optional target directory]
@end example

Μπορείτε επίσης να καθορίσετε την επιλογή @code{/quiet} για απόκρυψη της εμφάνισης προόδου.

@node Τροποποίηση εγκατάστασης,Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα<2>,Εγκατάσταση χωρίς λήψη,Το πλήρες πρόγραμμα εγκατάστασης
@anchor{using/windows modifying-an-install}@anchor{241d}
@subsubsection Τροποποίηση εγκατάστασης


Μόλις εγκατασταθεί η Python, μπορείτε να προσθέσετε ή να αφαιρέσετε λειτουργίες μέσω του εργαλείου Προγράμματα και Δυνατότητες που είναι μέρος των Windows. Επιλέξτε την καταχώρηση Python και επιλέξτε «Κατάργηση εγκατάστασης/Αλλαγή» για να ανοίξετε το πρόγραμμα εγκατάστασης σε λειτουργία συντήρησης.

Η «Αλλαγή» σάς επιτρέπει να προσθέτετε ή να αφαιρείτε λειτουργίες τροποποιώντας τα πλαίσια ελέγχου - τα αμετάβλητα πλαίσια ελέγχου δεν θα εγκαταστήσουν ή θα αφαιρέσουν τίποτα. Ορισμένες επιλογές δεν μπορούν να αλλάξουν σε αυτήν τη λειτουργία, όπως ο κατάλογος εγκατάστασης· για να τις τροποποιήσετε, θα χρειαστεί αν αφαιρέσετε και, στη συνέχεια να επανεγκαταστήσετε ξανά την Python.

Η «Επιδιόρθωση» θα επαληθεύσει όλα τα αρχεία που πρέπει να εγκατασταθούν χρησιμοποιώντας τις τρέχουσες ρυθμίσεις και θα αντικαταστήσει όσα έχουν αφαιρεθεί ή τροποποιηθεί.

Η «Κατάργηση εγκατάστασης» θα καταργήσει πλήρως την Python, με εξαίρεση το @ref{9bc,,Διαχειριστής εγκατάστασης Python}, το οποίο έχει τη δική του καταχώριση στο Προγράμματα και Δυνατότητες.

@node Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα<2>,,Τροποποίηση εγκατάστασης,Το πλήρες πρόγραμμα εγκατάστασης
@anchor{using/windows id3}@anchor{241e}
@subsubsection Εγκατάσταση Δυαδικών Αρχείων με Ελεύθερα Νήματα



Added in version 3.13.


Για να εγκαταστήσετε προ-κατασκευασμένα δυαδικά αρχεία με ενεργοποιημένο το free-threading (δείτε το 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}), θα πρέπει να επιλέξετε «Προσαρμοσμένη εγκατάσταση». Η δεύτερη σελίδα επιλογών περιλαμβάνει το πλαίσιο επιλογής «Λήψη δυαδικών αρχείων με ελεύθερο νήμα».

@image{python-figures/win_install_freethreaded,,,,png}

Η επιλογή αυτής της επιλογής θα κατεβάσει και θα εγκαταστήσει πρόσθετα δυαδικά αρχεία στην ίδια τοποθεσία με την κύρια εγκατάσταση Python. Το κύριο εκτελέσιμο αρχείο ονομάζεται @code{python3.13t.exe}, και άλλα δυαδικά αρχεία είτε λαμβάνουν μια κατάληξη @code{t} είτε μια πλήρη κατάληξη ABI. Τα αρχεία πηγαίου κώδικα Python και οι ενσωματωμένες εξαρτήσεις τρίτων μοιράζονται με την κύρια εγκατάσταση.

Η έκδοση με ελεύθερο νήμα καταχωρείται ως κανονική εγκατάσταση Python με την ετικέτα @code{3.13t} (με κατάληξη @code{-32} ή @code{-arm64} ως κανονική για αυτές τις πλατφόρμες). Αυτό επιτρέπει στα εργαλεία να την ανακαλύψουν και για το @ref{9bc,,Διαχειριστής εγκατάστασης Python} να υποστηρίζει το @code{py.exe -3.13t}. Σημειώστε ότι το πρόγραμμα εκκίνησης θα ερμηνεύσει το @code{py.exe -3} (ή ένα shebang @code{python3}) ως «την τελευταία εγκατάσταση 3.x», η οποία θα προτιμήσει τα δυαδικά αρχεία με ελεύθερο νήμα έναντι των κανονικών, ενώ το @code{py.exe -3.13} δεν θα το κάνει. Εάν χρησιμοποιείτε το σύντομο στυλ επιλογής, μπορεί να προτιμάτε να μην εγκαταστήσετε τα δυαδικά αρχεία με ελεύθερο νήμα αυτή τη στιγμή.

Για να καθορίσετε την επιλογή εγκατάστασης στη γραμμή εντολών, χρησιμοποιήστε @code{Include_freethreaded=1}. Δείτε @ref{2419,,Εγκατάσταση χωρίς λήψη} για οδηγίες σχετικά με την προληπτική λήψη των πρόσθετων δυαδικών αρχείων για εγκατάσταση εκτός σύνδεσης. Οι επιλογές για την συμπερίληψη συμβόλων και δυαδικών αρχείων εντοπισμού σφαλμάτων ισχύουν επίσης για τις κατασκευές με ελεύθερο νήμα.

Τα δυαδικά αρχεία με ελεύθερο νήμα είναι επίσης διαθέσιμα @ref{23ec,,στο nuget.org}.

@node Το πρόγραμμα εκκίνησης Python για Windows Απαρχαιωμένο,,Το πλήρες πρόγραμμα εγκατάστασης,Χρησιμοποιώντας Python στα Windows
@anchor{using/windows python-launcher-for-windows-deprecated}@anchor{241f}
@subsection Το πρόγραμμα εκκίνησης Python για Windows (Απαρχαιωμένο)



Αποσύρθηκε στην έκδοση 3.14: Το πρόγραμμα εκκίνησης και αυτή η τεκμηρίωση έχουν αντικατασταθεί από το Python Install Manager που περιγράφεται παραπάνω. Αυτό διατηρείται προσωρινά για ιστορικό ενδιαφέρον.



Added in version 3.3.


Το πρόγραμμα εκκίνησης Python για Windows είναι ένα βοηθητικό πρόγραμμα που βοηθά στον εντοπισμό και την εκτέλεση διαφορετικών εκδόσεων Python.  Επιτρέπει στα scripts (ή στη γραμμή εντολών) να υποδείξουν μια προτίμηση για μια συγκεκριμένη έκδοση Python και θα εντοπίσουν και θα εκτελέσουν αυτήν την έκδοση.

Σε αντίθεση με τη μεταβλητή 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}, το πρόγραμμα εκκίνησης θα επιλέξει σωστά την καταλληλότερη έκδοση της Python. Θα προτιμήσει τις εγκαταστάσεις ανά χρήστη έναντι των εγκαταστάσεων σε όλο το σύστημα και τις παραγγελίες ανά έκδοση γλώσσας αντί να χρησιμοποιεί την πιο πρόσφατα εγκατεστημένη έκδοση.

Το πρόγραμμα εκκίνησης προσδιορίστηκε αρχικά στο 
@geindex Python Enhancement Proposals; PEP 397
PEP 397@footnote{https://peps.python.org/pep-0397/}.

@menu
* Ξεκινώντας:: 
* Γραμμές Shebang: Γραμμές Shebang<2>. 
* Ορίσματα στις γραμμές shebang:: 
* Προσαρμογή:: 
* Διαγνωστικά:: 
* Dry run:: 
* Εγκατάσταση κατ” απαίτηση:: 
* Επιστρεφόμενοι κωδικοί:: 

@end menu

@node Ξεκινώντας,Γραμμές Shebang<2>,,Το πρόγραμμα εκκίνησης Python για Windows Απαρχαιωμένο
@anchor{using/windows getting-started}@anchor{2420}
@subsubsection Ξεκινώντας


@menu
* Από τη γραμμή εντολών:: 
* Εικονικά Περιβάλλοντα:: 
* Από ένα script:: 
* Από συσχετίσεις αρχείων:: 

@end menu

@node Από τη γραμμή εντολών,Εικονικά Περιβάλλοντα,,Ξεκινώντας
@anchor{using/windows from-the-command-line}@anchor{2421}
@subsubsection Από τη γραμμή εντολών



Άλλαξε στην έκδοση 3.6.


Εγκαταστάσεις σε όλο το σύστημα της Python 3.3 και νεότερες εκδόσεις θα τοποθετήσουν το πρόγραμμα εκκίνησης στο 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}. Το πρόγραμμα εκκίνησης είναι συμβατό με όλες τις διαθέσιμες εκδόσεις της Python, επομένως δεν έχει σημασία ποια έκδοση είναι εγκατεστημένη. Για να ελέγξτε ότι το πρόγραμμα εκκίνησης είναι διαθέσιμο, εκτελέστε την ακόλουθη εντολή στη Γραμμή Εντολών:

@example
py
@end example

Θα πρέπει να διαπιστώσετε ότι η πιο πρόσφατη έκδοση της Python που έχετε εγκαταστήσει έχει ξεκινήσει - μπορεί να βγει κανονικά και τυχόν πρόσθετα ορίσματα γραμμής εντολών που καθορίστηκαν θα σταλούν απευθείας στην Python.

Εάν έχετε εγκαταστήσει πολλές εκδόσεις της Python (π.χ. 3.7 και 3.16) θα έχετε παρατηρήσει ότι ξεκίνησε η Python 3.16 - για να εκκινήσετε την Python 3.7, δοκιμάστε την εντολή:

@example
py -3.7
@end example

Αν θέλετε την πιο πρόσφατη έκδοση της Python 2 που έχετε εγκαταστήσει, δοκιμάστε την εντολή:

@example
py -2
@end example

Αν δείτε το ακόλουθο σφάλμα, δεν έχετε εγκαταστήσει τον εκκινητή (launcher):

@example
Το 'py' δεν αναγνωρίζεται ως εσωτερική ή εξωτερική εντολή,
λειτουργικό πρόγραμμα ή αρχείο παρτίδας.
@end example

Η εντολή:

@example
py --list
@end example

εμφανίζει τις τρέχουσες εγκατεστημένες εκδόσεις της Python.

Το όρισμα @code{-x.y} είναι η σύντομη μορφή του ορίσματος @code{-V:Company/Tag}, το οποίο επιτρέπει την επιλογή ενός συγκεκριμένου χρόνου εκτέλεσης Python, συμπεριλαμβανομένων εκείνων που μπορεί να έχουν προέλθει από κάπου διαφορετικά από το python.org. Οποιοσδήποτε χρόνος εκτέλεσης έχει καταχωρηθεί ακολουθώντας το 
@geindex Python Enhancement Proposals; PEP 514
PEP 514@footnote{https://peps.python.org/pep-0514/} θα είναι ανιχνεύσιμος. Η εντολή @code{--list} παραθέτει όλους τους διαθέσιμους χρόνους εκτέλεσης χρησιμοποιώντας τη μορφή @code{-V:}.

Όταν χρησιμοποιείται το όρισμα @code{-V:}, ο καθορισμός της Εταιρείας θα περιορίσει την επιλογή σε χρόνους εκτέλεσης από αυτόν τον πάροχο, ενώ ο καθορισμός μόνο της ετικέτας θα επιλέγεται από όλους τους παρόχους. Σημειώστε ότι η παράλειψη της καθέτου (slash) συνεπάγεται μια ετικέτα:

@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

Η σύντομη μορφή του ορίσματος (@code{-3}) επιλέγει μόνο από τις βασικές εκδόσεις Python, και όχι άλλες διανομές. Ωστόσο, η μεγαλύτερη μορφή (@code{-V:3}) θα επιλέξει από οποιαδήποτε.

Η εταιρεία έχει αντιστοιχιστεί στην πλήρη συμβολοσειρά, χωρίς διάκριση πεζών-κεφαλαίων. Η ετικέτα αντιστοιχίζεται είτε με την πλήρη συμβολοσειρά είτε με ένα πρόθεμα, με την προϋπόθεση ότι ο επόμενος χαρακτήρας είναι μια τελεία ή μια παύλα. Αυτό επιτρέπει την αντιστοίχιση του @code{-V:3.1} με το @code{3.1-32}, αλλά όχι @code{3.10}. Οι ετικέτες ταξινομούνται με αριθμητική σειρά (@code{3.10} είναι νεότερο από @code{3.1}), αλλά συγκρίνονται χρησιμοποιώντας κείμενο (@code{-V:3.01} δεν ταιριάζει με το @code{3.1}).

@node Εικονικά Περιβάλλοντα,Από ένα script,Από τη γραμμή εντολών,Ξεκινώντας
@anchor{using/windows virtual-environments}@anchor{2422}
@subsubsection Εικονικά Περιβάλλοντα



Added in version 3.5.


Εάν το πρόγραμμα εγκατάστασης εκτελείται χωρίς ρητές προδιαγραφές έκδοσης Python και ένα εικονικό περιβάλλον (δημιουργημένο με το τυπικό module βιβλιοθήκης @ref{11a,,venv} ή το εξωτερικό εργαλείο @code{virtualenv}) ενεργό, το πρόγραμμα εκκίνησης θα εκτελέσει τον διερμηνέα του εικονικού περιβάλλοντος αντί για το καθολικό.  Για να εκτελέσετε τον καθολικό διερμηνέα, είτε απενεργοποιήστε το εικονικό περιβάλλον είτε καθορίστε ρητά την καθολική έκδοση Python.

@node Από ένα script,Από συσχετίσεις αρχείων,Εικονικά Περιβάλλοντα,Ξεκινώντας
@anchor{using/windows from-a-script}@anchor{2423}
@subsubsection Από ένα script


Ας δημιουργήσουμε ένα δοκιμαστικό Python script - δημιουργήστε ένα αρχείο που ονομάζεται @code{hello.py} με τα ακόλουθα περιεχόμενα

@example
#! python
import sys
sys.stdout.write("hello from Python %s\n" % (sys.version,))
@end example

Από τον κατάλογο στον οποίο ζει το hello.py, εκτελέστε την εντολή:

@example
py hello.py
@end example

Θα πρέπει να παρατηρήσετε ότι ο αριθμός έκδοσης της τελευταίας εγκατάστασης Python 2.x έχει εκτυπωθεί.  Τώρα δοκιμάστε να αλλάξετε την πρώτη γραμμή σε:

@example
#! python3
@end example

Η επανεκτέλεση της εντολής θα πρέπει τώρα να εκτυπώσει τις πιο πρόσφατες πληροφορίες Python 3.x. Όπως και με τα παραπάνω παραδείγματα γραμμής εντολών, μπορείτε να καθορίσετε έναν πιο σαφή προσδιορισμό έκδοσης.  Υποθέτοντας ότι έχετε εγκαταστήσει την Python 3.7, δοκιμάστε να αλλάξετε την πρώτη γραμμή σε @code{#! python3.7} και θα πρέπει να βρείτε τυπωμένες τις πληροφορίες της έκδοσης 3.7.

Λάβετε υπόψη ότι σε αντίθεση με τη διαδραστική χρήση, ένα γυμνό «python» θα χρησιμοποιεί την πιο πρόσφατη έκδοση της Python 2.x που έχετε εγκαταστήσει.  Αυτή είναι μια συμβατότητα προς τα πίσω και για συμβατότητα με Unix, όπου συνήθως αναφέρεται η εντολή @code{python} στην Python 2.

@node Από συσχετίσεις αρχείων,,Από ένα script,Ξεκινώντας
@anchor{using/windows from-file-associations}@anchor{2424}
@subsubsection Από συσχετίσεις αρχείων


Το πρόγραμμα εκκίνησης θα έπρεπε να είχε συσχετιστεί με αρχεία Python (δηλαδή αρχεία @code{.py}, @code{.pyw}, @code{.pyc}) όταν εγκαταστάθηκε.  Αυτό σημαίνει ότι όταν κάνετε διπλό κλικ σε ένα από αυτά τα αρχεία από τον Windows Explorer, το πρόγραμμα εκκίνησης θα χρησιμοποιηθεί και επομένως μπορείτε να χρησιμοποιήσετε τις ίδιες ευκολίες που περιγράφονται παραπάνω για να έχετε το script να καθορίζει ποια έκδοση θα χρησιμοποιηθεί.

Το βασικό πλεονέκτημα αυτού είναι ότι ένας μεμονωμένο πρόγραμμα εκκίνησης μπορεί να υποστηρίξει πολλές εκδόσεις Python ταυτόχρονα, ανάλογα με τα περιεχόμενα της πρώτης γραμμής.

@node Γραμμές Shebang<2>,Ορίσματα στις γραμμές shebang,Ξεκινώντας,Το πρόγραμμα εκκίνησης Python για Windows Απαρχαιωμένο
@anchor{using/windows id4}@anchor{2425}
@subsubsection Γραμμές Shebang


Εάν η πρώτη γραμμή ενός script αρχείου ξεκινά με @code{#!}, είναι γνωστή ως γραμμή «shebang».  Το Linux και άλλα Unix λειτουργικά συστήματα έχουν εγγενή υποστήριξη για τέτοιες γραμμές και χρησιμοποιούνται συνήθως σε τέτοιες γραμμές συστήματα για να υποδείξουν πως πρέπει να εκτελεστεί ένα script.  Αυτό το πρόγραμμα εκκίνησης επιτρέπει τη χρήση των ίδιων εγκαταστάσεων με Python scripts στα Windows και τα παραπάνω παραδείγματα δείχνουν τη χρήση τους.

Για να επιτραπεί στις γραμμές shebang σε Python scripts να είναι φορητές μεταξύ Unix και Windows, αυτό το πρόγραμμα εκκίνησης υποστηρίζει έναν αριθμό “εικονικών” εντολών για να καθορίσει ποιος διερμηνέας θα χρησιμοποιηθεί.  Οι υποστηριζόμενες εικονικές εντολές είναι:


@itemize *

@item 
@code{/usr/bin/env}

@item 
@code{/usr/bin/python}

@item 
@code{/usr/local/bin/python}

@item 
@code{python}
@end itemize

Για παράδειγμα, εάν η πρώτη γραμμή του script σας ξεκινά με

@example
#! /usr/bin/python
@end example

Η προεπιλεγμένη Python ή ένα ενεργό εικονικό περιβάλλον θα εντοπιστεί και θα χρησιμοποιηθεί. Καθώς πολλά Python scripts που έχουν γραφεί για να λειτουργούν σε Unix θα έχουν ήδη αυτή τη γραμμή, θα διαπιστώσετε ότι αυτά τα σενάρια μπορούν να χρησιμοποιηθούν από τον εκκινητή χωρίς τροποποίηση. Εάν γράφετε ένα νέο σενάριο στα Windows που ελπίζετε να είναι χρήσιμο σε Unix, θα πρέπει να χρησιμοποιήσετε μία από τις γραμμές shebang που ξεκινούν με @code{/usr}.

Οποιαδήποτε από τις παραπάνω εικονικές εντολές μπορεί να προστεθεί με μια ρητή έκδοση (είτε μόνο η κύρια έκδοση, είτε η κύρια και δευτερεύουσα έκδοση). Επιπλέον, η έκδοση 32-bit μπορεί να ζητηθεί προσθέτοντας «-32» μετά τη δευτερεύουσα έκδοση. Δηλαδή @code{/usr/bin/python3.7-32} θα ζητήσει τη χρήση της python 3.7. Εάν ένα εικονικό περιβάλλον είναι ενεργό, η έκδοση θα αγνοηθεί και θα χρησιμοποιηθεί το περιβάλλον.


Added in version 3.7: Ξεκινώντας με το πρόγραμμα εκκίνησης Python 3.7, είναι δυνατό να ζητηθεί η έκδοση 64-bit με το επίθημα «-64». Επιπλέον, είναι δυνατό να καθοριστεί μια κύρια έκδοση και μια αρχιτεκτονική χωρίς  δευτερεύοντα (δηλαδή @code{/usr/bin/python3-64}).



Άλλαξε στην έκδοση 3.11: Το επίθημα «-64» έχει καταργηθεί, και τώρα υποδηλώνει «οποιαδήποτε αρχιτεκτονική που δεν είναι αποδεδειγμένα i386/32-bit». Για να ζητήσετε ένα συγκεκριμένο περιβάλλον, χρησιμοποιήστε το νέο @code{-V:@var{TAG}} όρισμα με την πλήρη ετικέτα.



Άλλαξε στην έκδοση 3.13: Οι εικονικές εντολές που αναφέρονται σε @code{python} προτιμούν πλέον ένα ενεργό εικονικό περιβάλλον αντί να αναζητούν το 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}. Αυτό χειρίζεται περιπτώσεις όπου το shebang καθορίζει @code{/usr/bin/env python3} αλλά το @code{python3.exe} δεν υπάρχει στο ενεργό περιβάλλον.


Η φόρμα @code{/usr/bin/env} της γραμμής shebang έχει μια επιπλέον ειδική ιδιότητα. Πριν αναζητήσετε εγκατεστημένους διερμηνείς Python, αυτή η φόρμα θα αναζητήσει στο εκτελέσιμο αρχείο 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} για ένα εκτελέσιμο αρχείο Python που ταιριάζει με το όνομα που παρέχεται ως το πρώτο όρισμα. Αυτό αντιστοιχεί στη συμπεριφορά του προγράμματος Unix @code{env}, το οποίο εκτελεί μια αναζήτηση 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}. Εάν δεν μπορεί να βρεθεί ένα εκτελέσιμο αρχείο που ταιριάζει με το πρώτο όρισμα μετά την εντολή @code{env}, αλλά το όρισμα ξεκινά με @code{python}, ο χειρισμός του θα γίνει όπως περιγράφεται για τις άλλες εικονικές εντολές. Η μεταβλητή περιβάλλοντος @code{PYLAUNCHER_NO_SEARCH_PATH} μπορεί να οριστεί (σε οποιαδήποτε τιμή) για να παραλείψει αυτήν την αναζήτηση για 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}.

Οι γραμμές Shebang που δεν ταιριάζουν με κανένα από αυτά τα μοτίβα αναζητούνται στην ενότητα @code{[commands]} του προγράμματος εκκίνησης @ref{2426,,.INI file}. Αυτό μπορεί να χρησιμοποιηθεί για τον χειρισμό ορισμένων εντολών με τρόπο που να έχει νόημα για το σύστημά σας. Το όνομα της εντολής πρέπει να είναι ένα μεμονωμένο όρισμα (δεν υπάρχουν κενά στο εκτελέσιμο αρχείο shebang) και η τιμή που αντικαθίσταται είναι η πλήρης διαδρομή προς το εκτελέσιμο (τα πρόσθετα ορίσματα που καθορίζονται στο .INI θα αναφέρονται ως μέρος του ονόματος αρχείου).

@example
[commands]
/bin/xpython=C:\Program Files\XPython\python.exe
@end example

Οποιεσδήποτε εντολές που δεν βρίσκονται στο αρχείο .INI αντιμετωπίζονται ως εκτελέσιμες διαδρομές `Windows' που είναι απόλυτες ή σχετικές με τον κατάλογο που περιέχει το script αρχείο. Αυτό είναι μια ευκολία για σενάρια μόνο για Windows, όπως αυτά που δημιουργούνται από ένα πρόγραμμα εγκατάστασης, δεδομένου ότι η συμπεριφορά δεν είναι συμβατή με κελύφη τύπου Unix. Αυτές οι διαδρομές μπορεί να αναφέρονται και μπορεί να περιλαμβάνουν πολλαπλά ορίσματα, μετά τη διαδρομή προς το script και θα προσαρτηθούν τυχόν πρόσθετα ορίσματα.

@node Ορίσματα στις γραμμές shebang,Προσαρμογή,Γραμμές Shebang<2>,Το πρόγραμμα εκκίνησης Python για Windows Απαρχαιωμένο
@anchor{using/windows arguments-in-shebang-lines}@anchor{2427}
@subsubsection Ορίσματα στις γραμμές shebang


Οι γραμμές shebang μπορούν επίσης να καθορίσουν πρόσθετες επιλογές που θα μεταβιβαστούν στον διερμηνέα Python.  Για παράδειγμα, εάν έχετε μια γραμμή shebang:

@example
#! /usr/bin/python -v
@end example

Στη συνέχεια, η Python θα ξεκινήσει με την επιλογή @code{-v}

@node Προσαρμογή,Διαγνωστικά,Ορίσματα στις γραμμές shebang,Το πρόγραμμα εκκίνησης Python για Windows Απαρχαιωμένο
@anchor{using/windows customization}@anchor{2428}
@subsubsection Προσαρμογή


@menu
* Προσαρμογή μέσω αρχείων INI:: 
* Προσαρμογή προεπιλεγμένων εκδόσεων Python:: 

@end menu

@node Προσαρμογή μέσω αρχείων INI,Προσαρμογή προεπιλεγμένων εκδόσεων Python,,Προσαρμογή
@anchor{using/windows customization-via-ini-files}@anchor{2429}@anchor{using/windows launcher-ini}@anchor{2426}
@subsubsection Προσαρμογή μέσω αρχείων INI


Θα γίνει αναζήτηση δύο αρχείων .ini από το πρόγραμμα εκκίνησης - @code{py.ini} στον κατάλογο δεδομένων εφαρμογής του τρέχοντος χρήστη (@code{%LOCALAPPDATA%} ή @code{$env:LocalAppData}) και @code{py.ini} στον ίδιο κατάλογο με το πρόγραμμα εκκίνησης. Τα ίδια αρχεία .ini χρησιμοποιούνται τόσο για την έκδοση “κονσόλας” του προγράμματος εκκίνησης (π.χ. py.exe) όσο και για την έκδοση “windows” (δηλ. pyw.exe).

Η προσαρμογή που καθορίζεται στον «κατάλογο εφαρμογών» θα έχει προτεραιότητα έναντι αυτής που βρίσκεται δίπλα στο εκτελέσιμο αρχείο, επομένως ένας χρήστης, ο οποίος ενδέχεται να μην έχει πρόσβαση εγγραφής στο αρχείο .ini δίπλα στο πρόγραμμα εκκίνησης, μπορεί να παρακάμψει εντολές σε αυτό το καθολικό .ini αρχείο.

@node Προσαρμογή προεπιλεγμένων εκδόσεων Python,,Προσαρμογή μέσω αρχείων INI,Προσαρμογή
@anchor{using/windows customizing-default-python-versions}@anchor{242a}
@subsubsection Προσαρμογή προεπιλεγμένων εκδόσεων Python


Σε ορισμένες περιπτώσεις, ένας προσδιορισμός έκδοσης μπορεί να συμπεριληφθεί σε μια εντολή για να υπαγορεύσει ποια έκδοση της Python θα χρησιμοποιηθεί από την εντολή. Ένας προσδιοριστής έκδοσης ξεκινά με τον αριθμό κύριας έκδοσης και μπορεί προαιρετικά να ακολουθείται από μια τελεία (“.”) και ένας δευτερεύων προσδιοριστής έκδοσης. Επιπλέον, είναι δυνατό να καθοριστεί εάν θα ζητηθεί υλοποίηση 32 ή 64 bit προσθέτοντας «-32» ή «-64».

Για παράδειγμα, μια γραμμή shebang του @code{#!python} δεν έχει προσδιοριστικό έκδοσης, ενώ το @code{#!python3} έχει έναν προσδιορισμό έκδοσης που καθορίζει μόνο μια κύρια έκδοση.

Εάν δεν βρεθούν κριτήρια έκδοσης σε μια εντολή, η μεταβλητή περιβάλλοντος @code{PY_PYTHON} μπορεί να οριστεί για να καθορίσει τον προσδιορισμό της προεπιλεγμένης έκδοσης. Εάν δεν έχει οριστεί, η προεπιλογή είναι «3», «3.7», «3.7-32» ή «3.7-64». (Σημειώστε ότι η επιλογή «-64» είναι διαθέσιμη μόνο με το πρόγραμμα εκκίνησης που περιλαμβάνεται στην Python 3.7 ή νεότερη έκδοση.)

Εάν δεν βρεθούν περιορισμοί δευτερεύουσας έκδοσης, η μεταβλητή περιβάλλοντος @code{PY_PYTHON@{major@}} (όπου @code{@{major@}} είναι ο προσδιορισμός της τρέχουσας κύριας έκδοσης όπως προσδιορίζεται παραπάνω) μπορεί να οριστεί για να καθορίσει την πλήρη έκδοση. Εάν όχι αν βρεθεί τέτοια επιλογή, ο εκκινητής θα απαριθμήσει τις εγκατεστημένες εκδόσεις Python και θα χρησιμοποιήσει την πιο πρόσφατη δευτερεύουσα έκδοση που βρέθηκε για την κύρια έκδοση, η οποία είναι πιθανό, αν και δεν είναι εγγυημένη, να είναι η πιο πρόσφατα εγκατεστημένη έκδοση σε αυτήν την οικογένεια.

Σε Windows 64-bit με εγκατεστημένες υλοποιήσεις 32-bit και 64-bit της ίδιας (κύριας.δευτερεύουσας) έκδοσης Python, η έκδοση 64-bit θα προτιμάται πάντα. Αυτό θα ισχύει τόσο για 32-bit όσο και για 64-bit υλοποιήσεις του προγράμματος εκκίνησης - ένα πρόγραμμα εκκίνησης 32-bit θα προτιμήσει να εκτελέσει μια εγκατάσταση Python 64-bit της καθορισμένης έκδοσης, εάν είναι διαθέσιμη. Αυτό είναι έτσι, ώστε η συμπεριφορά του προγράμματος εκκίνησης μπορεί να προβλεφθεί γνωρίζοντας μόνο ποιες εκδόσεις είναι εγκατεστημένες στον υπολογιστή και χωρίς να λαμβάνεται υπόψη η σειρά με την οποία εγκαταστάθηκαν (δηλαδή, χωρίς να γνωρίζουμε εάν μια έκδοση 32 ή 64-bit της Python και το αντίστοιχο πρόγραμμα εκκίνησης εγκαταστάθηκε τελευταίο). Όπως σημειώθηκε παραπάνω, ένα προαιρετικό επίθημα «-32» ή «-64» μπορεί να χρησιμοποιηθεί σε έναν προσδιοριστή έκδοσης για την αλλαγή αυτής της συμπεριφοράς.

Παραδείγματα:


@itemize *

@item 
Εάν δεν οριστούν σχετικές επιλογές, οι εντολές @code{python} και @code{python2} θα χρησιμοποιήσουν την πιο πρόσφατη εγκατεστημένη έκδοση Python 2.x και η εντολή @code{python3} θα χρησιμοποιήσει την πιο πρόσφατη εγκατεστημένη Python 3.x.

@item 
Η εντολή @code{python3.7} δεν θα συμβουλευτεί καμία απολύτως επιλογή καθώς οι εκδόσεις είναι πλήρως καθορισμένες.

@item 
Εάν @code{PY_PYTHON=3}, οι εντολές @code{python} και @code{python3} θα χρησιμοποιούν και οι δύο την πιο πρόσφατη εγκατεστημένη έκδοση Python 3.

@item 
Εάν @code{PY_PYTHON=3.7-32}, η εντολή @code{python} θα χρησιμοποιήσει την υλοποίηση 32-bit του 3.7 ενώ η εντολή @code{python3} θα χρησιμοποιήσει την πιο πρόσφατη εγκατεστημένη Python (Το PY_PYTHON δεν θεωρήθηκε καθόλου καθώς καθορίστηκε μια κύρια έκδοση.)

@item 
Εάν @code{PY_PYTHON=3} και @code{PY_PYTHON3=3.7}, οι εντολές @code{python} και @code{python3} θα χρησιμοποιούν και οι δύο συγκεκριμένα την 3.7
@end itemize

Εκτός από τις μεταβλητές περιβάλλοντος, οι ίδιες ρυθμίσεις μπορούν να διαμορφωθούν στο αρχείο .INI που χρησιμοποιείται από το πρόγραμμα εκκίνησης.  Η ενότητα στο αρχείο INI ονομάζεται @code{[defaults]} και το όνομα του κλειδιού θα είναι το ίδιο με τις μεταβλητές περιβάλλοντος χωρίς το αρχικό πρόθεμα @code{PY_} (και σημειώστε ότι τα ονόματα κλειδιών στο αρχείο INI δεν έχουν διάκριση πεζών-κεφαλαίων.)  Τα περιεχόμενα μιας μεταβλητής περιβάλλοντος θα αντικαταστήσουν τα στοιχεία που καθορίζονται στο αρχείο INI.

Για παράδειγμα:


@itemize *

@item 
Η ρύθμιση @code{PY_PYTHON=3.7} είναι ισοδύναμη με το αρχείο INI που περιέχει:
@end itemize

@example
[defaults]
python=3.7
@end example


@itemize *

@item 
Η ρύθμιση @code{PY_PYTHON=3} και @code{PY_PYTHON3=3.7} ισοδυναμεί με το αρχείο INI που περιέχει:
@end itemize

@example
[defaults]
python=3
python3=3.7
@end example

@node Διαγνωστικά,Dry run,Προσαρμογή,Το πρόγραμμα εκκίνησης Python για Windows Απαρχαιωμένο
@anchor{using/windows diagnostics}@anchor{242b}
@subsubsection Διαγνωστικά


Εάν μια μεταβλητή περιβάλλοντος @code{PYLAUNCHER_DEBUG} έχει οριστεί (σε οποιαδήποτε τιμή), το πρόγραμμα εκκίνησης θα εκτυπώσει διαγνωστικές πληροφορίες στο stderr (δηλαδή στην κονσόλα). Ενώ αυτές οι πληροφορίες καταφέρνουν να είναι ταυτόχρονα αναλυτικές `και', θα πρέπει να επιτρέπουν για να δείτε ποιες εκδόσεις της Python εντοπίστηκαν, γιατί επιλέχθηκε μια συγκεκριμένη έκδοση και η ακριβής γραμμή εντολών που χρησιμοποιήθηκε για την εκτέλεση του στόχου Python. Προορίζεται κυρίως για δοκιμή και εντοπισμό σφαλμάτων.

@node Dry run,Εγκατάσταση κατ” απαίτηση,Διαγνωστικά,Το πρόγραμμα εκκίνησης Python για Windows Απαρχαιωμένο
@anchor{using/windows dry-run}@anchor{242c}
@subsubsection Dry run


Εάν μια μεταβλητή περιβάλλοντος @code{PYLAUNCHER_DRYRUN} έχει οριστεί (σε οποιαδήποτε τιμή), το πρόγραμμα εκκίνησης θα δώσει την εντολή που θα εκτελούσε, αλλά δεν θα εκκινήσει πραγματικά την Python. Αυτό μπορεί να είναι χρήσιμο για εργαλεία που θέλουν να χρησιμοποιήσουν το πρόγραμμα εκκίνησης για να εντοπιστεί και να εκκινηθεί απευθείας η Python. Σημειώστε ότι η εντολή που είναι γραμμένη στην τυπική έξοδο κωδικοποιείται πάντα με χρήση UTF-8 και ενδέχεται να μην αποδίδεται σωστά στην κονσόλα.

@node Εγκατάσταση κατ” απαίτηση,Επιστρεφόμενοι κωδικοί,Dry run,Το πρόγραμμα εκκίνησης Python για Windows Απαρχαιωμένο
@anchor{using/windows install-on-demand}@anchor{242d}
@subsubsection Εγκατάσταση κατ” απαίτηση


Εάν μια μεταβλητή περιβάλλοντος @code{PYLAUNCHER_ALLOW_INSTALL} έχει οριστεί (σε οποιαδήποτε τιμή), και η ζητούμενη έκδοση Python δεν είναι εγκατεστημένη αλλά είναι διαθέσιμη στο Microsoft Store, το πρόγραμμα εκκίνησης θα επιχειρήσει να την εγκαταστήσει. Αυτό μπορεί να απαιτεί την ολοκλήρωση της αλληλεπίδρασης του χρήστη και ίσως χρειαστεί να εκτελέσετε ξανά την εντολή.

Μια πρόσθετη μεταβλητή @code{PYLAUNCHER_ALWAYS_INSTALL} αναγκάζει το πρόγραμμα εκκίνησης να προσπαθεί πάντα να εγκαταστήσει την Python, ακόμα κι αν εντοπιστεί. Αυτό προορίζεται κυρίως για δοκιμή (και θα πρέπει να χρησιμοποιείται με το @code{PYLAUNCHER_DRYRUN}).

@node Επιστρεφόμενοι κωδικοί,,Εγκατάσταση κατ” απαίτηση,Το πρόγραμμα εκκίνησης Python για Windows Απαρχαιωμένο
@anchor{using/windows return-codes}@anchor{242e}
@subsubsection Επιστρεφόμενοι κωδικοί


Οι ακόλουθοι κωδικοί εξόδου μπορεί να επιστραφούν από τον εκκινητή Python. Δυστυχώς, δεν υπάρχει τρόπος να διακρίνουμε αυτούς από τον κωδικό εξόδου της ίδιας της Python.

Τα ονόματα των κωδικών είναι όπως χρησιμοποιούνται στις πηγές και είναι μόνο για αναφορά. Δεν υπάρχει τρόπος πρόσβασης ή επίλυσης τους εκτός από την ανάγνωση αυτής της σελίδας. Οι καταχωρήσεις παρατίθενται με αλφαβητική σειρά των ονομάτων.


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Όνομα

@tab

Τιμή

@tab

Περιγραφή

@item

RC_BAD_VENV_CFG

@tab

107

@tab

Βρέθηκε ένα @code{pyvenv.cfg} αλλά είναι κατεστραμμένο.

@item

RC_CREATE_PROCESS

@tab

101

@tab

Απέτυχε η εκκίνηση της Python.

@item

RC_INSTALLING

@tab

111

@tab

Ξεκίνησε μια εγκατάσταση, αλλά η εντολή θα πρέπει να εκτελεστεί ξανά μετά την ολοκλήρωση της.

@item

RC_INTERNAL_ERROR

@tab

109

@tab

Απροσδόκητο σφάλμα. Αναφέρετε ένα σφάλμα.

@item

RC_NO_COMMANDLINE

@tab

108

@tab

Δεν είναι δυνατή η λήψη της γραμμής εντολών από το λειτουργικό σύστημα.

@item

RC_NO_PYTHON

@tab

103

@tab

Δεν είναι δυνατός ο εντοπισμός της ζητούμενης έκδοσης.

@item

RC_NO_VENV_CFG

@tab

106

@tab

Απαιτήθηκε ένα @code{pyvenv.cfg} αλλά δεν βρέθηκε.

@end multitable


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Χρησιμοποιώντας Python σε macOS,Χρήση της Python σε Android,Χρησιμοποιώντας Python στα Windows,Ρύθμιση και Χρήση της Python
@anchor{using/mac doc}@anchor{242f}@anchor{using/mac translation-repo}@anchor{2430}@anchor{using/mac using-on-mac}@anchor{2431}@anchor{using/mac using-python-on-macos}@anchor{2432}
@section Χρησιμοποιώντας Python σε macOS


Αυτό το έγγραφο αποσκοπεί στο να δώσει μια επισκόπηση της συμπεριφοράς που σχετίζεται με το macOS που θα πρέπει να γνωρίζετε για να ξεκινήσετε με την Python σε υπολογιστές Mac. Η Python σε Mac που εκτελεί macOS είναι πολύ παρόμοια με την Python σε άλλες πλατφόρμες που προέρχονται από το Unix, αλλά υπάρχουν κάποιες διαφορές στην εγκατάσταση και κάποιες δυνατότητες.

Υπάρχουν διάφοροι τρόποι για να αποκτήσετε και να εγκαταστήσετε την Python για macOS. Προκατασκευασμένες εκδόσεις των πιο πρόσφατων εκδόσεων της Python είναι διαθέσιμες από έναν αριθμό διανομέων. Πολλές από αυτές τις πληροφορίες περιγράφουν τη χρήση της Python που παρέχονται από την ομάδα κυκλοφορίας CPython για λήψη από την ιστοσελίδα python.org@footnote{https://www.python.org/downloads/}. Δείτε @ref{2433,,Εναλλακτικές Διανομές} για μερικές άλλες επιλογές.
@anchor{using/mac getting-osx}@anchor{2434}
@menu
* Χρησιμοποιώντας Python για macOS από το python.org: Χρησιμοποιώντας Python για macOS από το python org. 
* Εναλλακτικές Διανομές:: 
* Εγκατάσταση πρόσθετων πακέτων Python:: 
* Προγραμματισμός GUI:: 
* Προχωρημένα θέματα:: 
* Άλλοι πόροι:: 

@end menu

@node Χρησιμοποιώντας Python για macOS από το python org,Εναλλακτικές Διανομές,,Χρησιμοποιώντας Python σε macOS
@anchor{using/mac getting-and-installing-macpython}@anchor{2435}@anchor{using/mac using-python-for-macos-from-python-org}@anchor{2436}
@subsection Χρησιμοποιώντας Python για macOS από το @code{python.org}


@menu
* Βήματα εγκατάστασης:: 
* Πώς να εκτελέσετε ένα σενάριο Python:: 

@end menu

@node Βήματα εγκατάστασης,Πώς να εκτελέσετε ένα σενάριο Python,,Χρησιμοποιώντας Python για macOS από το python org
@anchor{using/mac installation-steps}@anchor{2437}
@subsubsection Βήματα εγκατάστασης


Για τρέχουσες εκδόσεις Python@footnote{https://www.python.org/downloads/} (εκτός από αυτές που είναι σε κατάσταση @code{security}), η ομάδα κυκλοφορίας παράγει ένα `Python για macOS' πακέτο εγκατάστασης για κάθε νέα κυκλοφορία. Μια λίστα διαθέσιμων εγκαταστατών είναι διαθέσιμη εδώ@footnote{https://www.python.org/downloads/macos/}. Συνιστούμε τη χρήση της πιο πρόσφατης υποστηριζόμενης έκδοσης Python όπου είναι δυνατόν. Οι τρέχοντες εγκαταστάτες παρέχουν μια universal2 binary@footnote{https://en.wikipedia.org/wiki/Universal_binary} έκδοση της Python που εκτελείται εγγενώς σε όλους τους υπολογιστές Mac (Apple Silicon και Intel) που υποστηρίζονται από μια ευρεία γκάμα εκδόσεων macOS, αυτή τη στιγμή συνήθως από τουλάχιστον `macOS 10.15 Catalina' και μετά.

Το αρχείο που κατεβάσατε είναι ένα τυπικό αρχείο πακέτου εγκατάστασης macOS (@code{.pkg}). Οι πληροφορίες ακεραιότητας αρχείου (έλεγχος ταυτότητας, μέγεθος, υπογραφή sigstore κ.λπ.) για κάθε αρχείο περιλαμβάνονται στη σελίδα λήψης κυκλοφορίας. Τα πακέτα εγκατάστασης και το περιεχόμενό τους είναι υπογεγραμμένα και επικυρωμένα με @code{Python Software Foundation} Apple Developer ID πιστοποιητικά για να ικανοποιούν τις απαιτήσεις macOS Gatekeeper@footnote{https://support.apple.com/en-us/102445}.

Για μια τυπική εγκατάσταση, κάντε διπλό κλικ στο αρχείο πακέτου εγκατάστασης που κατεβάσατε. Αυτό θα πρέπει να εκκινήσει την τυπική εφαρμογή εγκατάστασης macOS και να εμφανίσει το πρώτο από αρκετά βήματα παραθύρου εγκατάστασης.

@image{python-figures/mac_installer_01_introduction,,,,png}

Κάνοντας κλικ στο κουμπί `Continue' εμφανίζεται το `Read Me' για αυτόν τον εγκαταστάτη. Εκτός από άλλες σημαντικές πληροφορίες, το `Read Me' καταγράφει ποια έκδοση Python πρόκειται να εγκατασταθεί και σε ποιες εκδόσεις macOS υποστηρίζεται. Ίσως χρειαστεί να κάνετε κύλιση για να διαβάσετε ολόκληρο το αρχείο. Από προεπιλογή, αυτό το `Read Me' θα εγκατασταθεί επίσης στο @code{/Applications/Python 3.16/} και θα είναι διαθέσιμο για ανάγνωση οποιαδήποτε στιγμή.

@image{python-figures/mac_installer_02_readme,,,,png}

Κάνοντας κλικ στο `Continue' προχωρά στην εμφάνιση της άδειας για την Python και για άλλο περιλαμβανόμενο λογισμικό. Στη συνέχεια θα χρειαστεί να `Συμφωνήσετε' με τους όρους άδειας πριν προχωρήσετε στο επόμενο βήμα. Αυτό το αρχείο άδειας θα εγκατασταθεί επίσης και θα είναι διαθέσιμο για ανάγνωση αργότερα.

@image{python-figures/mac_installer_03_license,,,,png}

Αφού γίνουν αποδεκτοί οι όροι άδειας, το επόμενο βήμα είναι η εμφάνιση `Τύπος Εγκατάστασης'. Για τις περισσότερες χρήσεις, το τυπικό σύνολο λειτουργιών εγκατάστασης είναι κατάλληλο.

@image{python-figures/mac_installer_04_installation_type,,,,png}

Πατώντας το κουμπί `Customize', μπορείτε να επιλέξετε να παραλείψετε ή να επιλέξετε ορισμένα πακέτα του εγκαταστάτη. Κάντε κλικ σε κάθε όνομα πακέτου για να δείτε μια περιγραφή του τι εγκαθιστά. Για να εγκαταστήσετε επίσης υποστήριξη για την προαιρετική δυνατότητα χωρίς νήματα, δείτε @ref{6a4,,Εγκατάσταση εκδόσεων Free-threaded}.

@image{python-figures/mac_installer_05_custom_install,,,,png}

Σε κάθε περίπτωση, κάνοντας κλικ στο `Install' θα ξεκινήσει η διαδικασία εγκατάστασης ζητώντας άδεια για την εγκατάσταση νέου λογισμικού. Ένα όνομα χρήστη macOS με @code{Administrator} δικαιώματα είναι απαραίτητο καθώς η εγκατεστημένη Python θα είναι διαθέσιμη σε όλους τους χρήστες του Mac.

Όταν ολοκληρωθεί η εγκατάσταση, θα εμφανιστεί το παράθυρο `Περίληψη'.

@image{python-figures/mac_installer_06_summary,,,,png}

Διπλό κλικ στο εικονίδιο ή το αρχείο @code{Install Certificates.command} στο παράθυρο @code{/Applications/Python 3.16/} για να ολοκληρώσετε την εγκατάσταση.

@image{python-figures/mac_installer_07_applications,,,,png}

Αυτό θα ανοίξει ένα προσωρινό παράθυρο κελύφους @code{Terminal} που θα χρησιμοποιήσει τη νέα Python για να κατεβάσει και να εγκαταστήσει ριζικούς πιστοποιητικούς SSL για τη χρήση του.

@image{python-figures/mac_installer_08_install_certificates,,,,png}

Εάν εμφανιστεί @code{Successfully installed certifi} και @code{update complete} στο παράθυρο τερματικού, η εγκατάσταση είναι ολοκληρωμένη. Κλείστε αυτό το παράθυρο τερματικού και το παράθυρο εγκαταστάτη.

Μια προεπιλεγμένη εγκατάσταση θα περιλαμβάνει:


@itemize *

@item 
Ένας @code{Python 3.16} φάκελος στον φάκελο @code{Applications}. Εδώ θα βρείτε το @code{IDLE}, το περιβάλλον ανάπτυξης που είναι τυπικό μέρος των επίσημων διανομών Python∙ και το @code{Python Launcher}, το οποίο χειρίζεται τα διπλά κλικ σε Python scripts από το macOS Finder@footnote{https://support.apple.com/en-us/HT201732}.

@item 
Ένα πλαίσιο @code{/Library/Frameworks/Python.framework}, το οποίο περιλαμβάνει τον εκτελέσιμο κώδικα Python και τις βιβλιοθήκες. Το πρόγραμμα εγκατάστασης προσθέτει αυτήν την τοποθεσία στο shell path σας. Για να απεγκαταστήσετε την Python, μπορείτε να αφαιρέσετε αυτά τα τρία πράγματα. Symlinks στον εκτελέσιμο κώδικα Python τοποθετούνται στο @code{/usr/local/bin/}.
@end itemize

@cartouche
@quotation Σημείωση 
Οι πρόσφατες εκδόσεις του macOS περιλαμβάνουν μια εντολή @code{python3} στο @code{/usr/bin/python3} που συνδέεται με μια συνήθως παλαιότερη και ελλιπή έκδοση της Python που παρέχεται από και για χρήση από τα εργαλεία ανάπτυξης της Apple, @code{Xcode} ή τα @code{Command Line Tools for  Xcode}. Δεν θα πρέπει ποτέ να τροποποιήσετε ή να προσπαθήσετε να διαγράψετε αυτήν την εγκατάσταση, καθώς ελέγχεται από την Apple και χρησιμοποιείται από το λογισμικό που παρέχεται από την Apple ή από τρίτους. Εάν επιλέξετε να εγκαταστήσετε μια νεότερη έκδοση Python από το @code{python.org}, θα έχετε δύο διαφορετικές αλλά λειτουργικές εγκαταστάσεις Python στον υπολογιστή σας που μπορούν να συνυπάρχουν. Οι προεπιλεγμένες επιλογές εγκατάστασης θα πρέπει να διασφαλίσουν ότι η @code{python3} θα χρησιμοποιηθεί αντί της συστήματος @code{python3}.
@end quotation
@end cartouche

@node Πώς να εκτελέσετε ένα σενάριο Python,,Βήματα εγκατάστασης,Χρησιμοποιώντας Python για macOS από το python org
@anchor{using/mac how-to-run-a-python-script}@anchor{2438}
@subsubsection Πώς να εκτελέσετε ένα σενάριο Python


Υπάρχουν δύο τρόποι για να καλέσετε τον διερμηνέα Python. Εάν είστε εξοικειωμένοι με τη χρήση ενός κελύφους Unix σε ένα παράθυρο τερματικού, μπορείτε να καλέσετε @code{python3.16} ή @code{python3} προαιρετικά ακολουθούμενο από μία ή περισσότερες επιλογές γραμμής εντολών (περιγράφεται στο @ref{1f98,,Command line and environment}). Το εγχειρίδιο Python έχει επίσης μια χρήσιμη ενότητα σχετικά με @ref{6a0,,using Python interactively from a shell}.

Μπορείτε επίσης να καλέσετε τον ερμηνευτή μέσω ενός ενσωματωμένου αναπτυξιακού περιβάλλοντος. @ref{13be,,IDLE — Python editor and shell} είναι ένας βασικός επεξεργαστής και περιβάλλον ερμηνευτή που περιλαμβάνεται με την τυπική διανομή Python. Το @code{IDLE} περιλαμβάνει ένα μενού Βοήθειας που σας επιτρέπει να αποκτήσετε πρόσβαση στην τεκμηρίωση Python. Εάν είστε εντελώς νέοι στην Python, μπορείτε να διαβάσετε την εισαγωγή του εγχειριδίου σε αυτό το έγγραφο.

Υπάρχουν πολλοί άλλοι επεξεργαστές και IDE διαθέσιμοι, δείτε @ref{2439,,Επεξεργαστές Κειμένου και IDEs} για περισσότερες πληροφορίες.

Για να εκτελέσετε ένα αρχείο script Python από το παράθυρο τερματικού, μπορείτε να καλέσετε τον ερμηνευτή με το όνομα του αρχείου script:

@quotation

@code{python3.16} @code{myscript.py}
@end quotation

Για να εκτελέσετε το script σας από το Finder, μπορείτε είτε:


@itemize *

@item 
Σύρετε το στο @code{Python Launcher}.

@item 
Επιλέξτε το @code{Python Launcher} ως την προεπιλεγμένη εφαρμογή για να ανοίξετε το script σας (ή οποιοδήποτε @code{.py} script) μέσω του παραθύρου πληροφοριών Finder και κάντε διπλό κλικ σε αυτό. Το @code{Python Launcher} έχει διάφορες προτιμήσεις για να ελέγξει πώς εκκινείται το script σας. Η επιλογή-μεταφορά σας επιτρέπει να αλλάξετε αυτά για μία κλήση ή χρησιμοποιήστε το μενού @code{Προτιμήσεις} για να αλλάξετε τα πράγματα παγκοσμίως.
@end itemize

Να είστε προσεκτικοί ότι η εκτέλεση του script απευθείας από το macOS Finder μπορεί να παράγει διαφορετικά αποτελέσματα από την εκτέλεση από ένα παράθυρο τερματικού καθώς το script δεν θα εκτελείται στο συνήθη περιβάλλον κελύφους που περιλαμβάνει οποιαδήποτε ρύθμιση μεταβλητών περιβάλλοντος σε προφίλ κελύφους. Και, όπως με οποιοδήποτε άλλο script ή πρόγραμμα, να είστε σίγουροι για το τι πρόκειται να εκτελέσετε.

@node Εναλλακτικές Διανομές,Εγκατάσταση πρόσθετων πακέτων Python,Χρησιμοποιώντας Python για macOS από το python org,Χρησιμοποιώντας Python σε macOS
@anchor{using/mac alternative-bundles}@anchor{2433}@anchor{using/mac alternative-distributions}@anchor{243a}
@subsection Εναλλακτικές Διανομές


Εκτός από τον τυπικό εγκαταστάτη @code{python.org} για macOS, υπάρχουν τρίτες διανομές για macOS που μπορεί να περιλαμβάνουν πρόσθετη λειτουργικότητα. Ορισμένες δημοφιλείς διανομές και τα βασικά χαρακτηριστικά τους:


@table @asis

@item ActivePython@footnote{https://www.activestate.com/products/python/}

Εγκαταστάτης με συμβατότητα πολλών πλατφορμών, τεκμηρίωση

@item Anaconda@footnote{https://www.anaconda.com/download/}

Δημοφιλή επιστημονικά modules (όπως numpy, scipy και pandas) και ο @code{conda} διαχειριστής πακέτων.

@item Homebrew@footnote{https://brew.sh}

Διαχειριστής πακέτων για macOS που περιλαμβάνει πολλές εκδόσεις Python και πολλά τρίτα πακέτα Python (συμπεριλαμβανομένων των numpy, scipy και pandas).

@item MacPorts@footnote{https://www.macports.org}

Ένας άλλος διαχειριστής πακέτων για macOS που περιλαμβάνει πολλές εκδόσεις Python και πολλά τρίτα πακέτα Python. Μπορεί να περιλαμβάνει προ-κατασκευασμένες εκδόσεις της Python και πολλά πακέτα για παλαιότερες εκδόσεις του macOS.
@end table

Σημειώστε ότι οι διανομές ενδέχεται να μην περιλαμβάνουν τις τελευταίες εκδόσεις της Python ή άλλων βιβλιοθηκών και δεν υποστηρίζονται ή συντηρούνται από την κύρια ομάδα Python.

@node Εγκατάσταση πρόσθετων πακέτων Python,Προγραμματισμός GUI,Εναλλακτικές Διανομές,Χρησιμοποιώντας Python σε macOS
@anchor{using/mac installing-additional-python-packages}@anchor{243b}@anchor{using/mac mac-package-manager}@anchor{243c}
@subsection Εγκατάσταση πρόσθετων πακέτων Python


Ανατρέξτε στον Python Packaging User Guide@footnote{https://packaging.python.org/en/latest/tutorials/installing-packages/} για περισσότερες πληροφορίες.
@anchor{using/mac osx-gui-scripts}@anchor{243d}
@node Προγραμματισμός GUI,Προχωρημένα θέματα,Εγκατάσταση πρόσθετων πακέτων Python,Χρησιμοποιώντας Python σε macOS
@anchor{using/mac gui-programming}@anchor{243e}@anchor{using/mac gui-programming-on-the-mac}@anchor{243f}
@subsection Προγραμματισμός GUI


Υπάρχουν πολλές επιλογές για την κατασκευή εφαρμογών GUI στον Mac με Python.

Η τυπική βιβλιοθήκη GUI Python είναι @ref{f9,,tkinter}, βασισμένη στο διαλειτουργικό εργαλείο Tk (@indicateurl{https://www.tcl.tk}). Μια εγγενής έκδοση Tk macOS περιλαμβάνεται με τον εγκαταστάτη.

Το `PyObjC' είναι ένα Python binding στο πλαίσιο Objective-C/Cocoa της Apple. Πληροφορίες σχετικά με το PyObjC είναι διαθέσιμες από pyobjc@footnote{https://pypi.org/project/pyobjc/}.

Ένας αριθμός εναλλακτικών εργαλείων GUI macOS είναι διαθέσιμος, συμπεριλαμβανομένων:


@itemize *

@item 
PySide@footnote{https://www.qt.io/qt-for-python}: Επίσημα Python bindings στο Qt GUI toolkit@footnote{https://wiki.qt.io/Qt_for_Python}.

@item 
PyQt@footnote{https://riverbankcomputing.com/software/pyqt/}: Εναλλακτικά Python bindings στο Qt.

@item 
Kivy@footnote{https://kivy.org}: Ένα διαλειτουργικό εργαλείο GUI που υποστηρίζει desktop και mobile πλατφόρμες.

@item 
Toga@footnote{https://toga.readthedocs.io}: Μέρος του BeeWare Project@footnote{https://beeware.org}; υποστηρίζει εφαρμογές desktop, mobile, web και κονσόλας εφαρμογές.

@item 
wxPython@footnote{https://wxpython.org}: Ένα διαλειτουργικό εργαλείο που υποστηρίζει desktop πλατφόρμες.
@end itemize

@node Προχωρημένα θέματα,Άλλοι πόροι,Προγραμματισμός GUI,Χρησιμοποιώντας Python σε macOS
@anchor{using/mac advanced-topics}@anchor{2440}
@subsection Προχωρημένα θέματα


@menu
* Εγκατάσταση εκδόσεων Free-threaded:: 
* Εγκατάσταση χρησιμοποιώντας τη γραμμή εντολών:: 
* Διανομή εφαρμογών Python:: 
* Συμμόρφωση App Store:: 

@end menu

@node Εγκατάσταση εκδόσεων Free-threaded,Εγκατάσταση χρησιμοποιώντας τη γραμμή εντολών,,Προχωρημένα θέματα
@anchor{using/mac install-freethreaded-macos}@anchor{6a4}@anchor{using/mac installing-free-threaded-binaries}@anchor{2441}
@subsubsection Εγκατάσταση εκδόσεων Free-threaded



Added in version 3.13.


Το πακέτο εγκατάστασης @code{python.org} @ref{2435,,Python for macOS} μπορεί προαιρετικά να εγκαταστήσει μια επιπλέον έκδοση της Python 3.16 που υποστηρίζει 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}, την πειραματική δυνατότητα ελεύθερης νηματοποίησης (threading) (εκτέλεση με το @ref{685,,global interpreter lock} απενεργοποιημένο). Ελέγξτε τη σελίδα κυκλοφορίας στο @code{python.org} για πιθανές ενημερωμένες πληροφορίες.

Η λειτουργία ελεύθερου νήματος λειτουργεί και συνεχίζει να βελτιώνεται, αλλά υπάρχει κάποια πρόσθετη επιβάρυνση στα φορτία εργασίας μονού νήματος σε σύγκριση με την κανονική έκδοση. Επιπλέον, τα πακέτα τρίτων κατασκευαστών, ιδίως αυτά με @ref{2442,,extension module}, ενδέχεται να μην είναι έτοιμα για χρήση σε μια έκδοση ελεύθερου νήματος και θα ενεργοποιήσουν ξανά το @ref{411,,GIL}. Επομένως, η υποστήριξη για ελεύθερη νηματοποποίησης δεν εγκαθίστανται από προεπιλογή. Είναι συσκευασμένη ως ξεχωριστή επιλογή εγκατάστασης, διαθέσιμη κάνοντας κλικ το κουμπί `Customize' στο βήμα `Installation Type' του προγράμματος εγκατάστασης όπως περιγράφεται παραπάνω.

@image{python-figures/mac_installer_09_custom_install_free_threaded,,,,png}

Εάν το πλαίσιο δίπλα στο όνομα πακέτου `Free-threaded Python' είναι επιλεγμένο, θα εγκατασταθεί επίσης ένα ξεχωριστό @code{PythonT.framework} δίπλα στο κανονικό @code{Python.framework} στο @code{/Library/Frameworks}. Αυτή η διαμόρφωση επιτρέπει σε μια έκδοση Python 3.16 ελεύθερης νηματοποίησης να συγκατοικεί στο σύστημά σας με μια παραδοσιακή (μόνο GIL) Python 3.16 έκδοση με ελάχιστο κίνδυνο κατά την εγκατάσταση ή τη δοκιμή. Αυτή η διάταξη εγκατάστασης είναι πειραματική και υπόκειται σε αλλαγές σε μελλοντικές εκδόσεις.

Γνωστές προφυλάξεις και περιορισμοί:


@itemize -

@item 
To `UNIX command-line tools' πακέτο, το οποίο επιλέγεται από προεπιλογή, θα εγκαταστήσει συνδέσμους στο @code{/usr/local/bin} για @code{python3.16t}, τον ερμηνευτή ελεύθερης νηματοποίησης και @code{python3.16t-config}, ένα βοηθητικό πρόγραμμα διαμόρφωσης που μπορεί να είναι χρήσιμο για κατασκευαστές πακέτων. Δεδομένου ότι το @code{/usr/local/bin} περιλαμβάνεται συνήθως στη μεταβλητή περιβάλλοντος @code{PATH} του κελύφους σας, στις περισσότερες περιπτώσεις δεν θα χρειαστούν αλλαγές στις μεταβλητές περιβάλλοντος @code{PATH} για να χρησιμοποιήσετε @code{python3.16t}.

@item 
Για αυτήν την έκδοση, το πακέτο `Shell profile updater' και το @code{Update Shell Profile.command} στο @code{/Applications/Python 3.16/}  δεν υποστηρίζουν το πακέτο ελεύθερης νηματοποίησης.

@item 
Η έκδοση ελεύθερης νηματοποίησης και η παραδοσιακή έκδοση έχουν ξεχωριστές διαδρομές αναζήτησης και ξεχωριστούς καταλόγους @code{site-packages}, οπότε, από προεπιλογή, εάν χρειάζεστε ένα πακέτο διαθέσιμο και στις δύο εκδόσεις, μπορεί να χρειαστεί να εγκατασταθεί και στις δύο. Το πακέτο ελεύθερης νηματοποίησης θα εγκαταστήσει μια ξεχωριστή έκδοση του @code{pip} για χρήση με @code{python3.16t}.


@itemize -

@item 
Για να εγκαταστήσετε ένα πακέτο χρησιμοποιώντας @code{pip} χωρίς @code{venv}:

@example
python3.16t -m pip install <package_name>
@end example
@end itemize

@item 
Όταν εργάζεστε με πολλές Python περιβάλλοντα, είναι συνήθως ασφαλέστερο και ευκολότερο να @ref{22da,,create and use virtual environments}. Αυτό μπορεί να αποφύγει πιθανά ονόματα εντολών συγκρούσεων και σύγχυση σχετικά με το ποια Python είναι σε χρήση:

@example
python3.16t -m venv <venv_name>
@end example

τότε @code{activate}.

@item 
Για να εκτελέσετε μια έκδοση ελεύθερης νηματοποίησης του IDLE:

@example
python3.16t -m idlelib
@end example

@item 
Οι ερμηνευτές και στις δύο εκδόσεις ανταγωνίζονται στις ίδιες @ref{9e8,,PYTHON environment variables} που μπορεί να έχουν απροσδόκητα αποτελέσματα, για παράδειγμα, εάν έχετε ρυθμίσει το @code{PYTHONPATH} σε ένα προφίλ κελύφους. Εάν είναι απαραίτητο, υπάρχουν @ref{230a,,command line options} όπως @code{-E} για να αγνοήσετε αυτές τις μεταβλητές περιβάλλοντος.

@item 
Η έκδοση ελεύθερης νηματοποίησης συνδέεται με τις βιβλιοθήκες κοινής χρήσης τρίτων, όπως @code{OpenSSL} και @code{Tk}, που είναι εγκατεστημένες στο παραδοσιακό πλαίσιο. Αυτό σημαίνει ότι και οι δύο εκδόσεις μοιράζονται επίσης ένα σύνολο πιστοποιητικών εμπιστοσύνης όπως εγκαθίστανται από το @code{Install Certificates.command} script, επομένως χρειάζεται να εκτελείται μόνο μία φορά.

@item 
Εάν δεν μπορείτε να εξαρτηθείτε από το σύνδεσμο στο @code{/usr/local/bin} που δείχνει στην έκδοση @code{python3.16t} ελεύθερης νηματοποίησης (για παράδειγμα, εάν θέλετε να εγκαταστήσετε τη δική σας έκδοση εκεί ή κάποια άλλη διανομή το κάνει), μπορείτε να ορίσετε ρητά τη μεταβλητή περιβάλλοντος @code{PATH} του κελύφους σας για να περιλαμβάνει το κατάλογο @code{bin} του πλαισίου @code{PythonT}:

@example
export PATH="/Library/Frameworks/PythonT.framework/Versions/3.16/bin":"$PATH"
@end example

Η παραδοσιακή εγκατάσταση πλαισίου από προεπιλογή κάνει κάτι παρόμοιο, εκτός από το @code{Python.framework}. Να είστε προσεκτικοί ότι η παρουσία και των δύο καταλόγων @code{bin} πλαισίου στο @code{PATH} μπορεί να οδηγήσει σε σύγχυση εάν υπάρχουν διπλά ονόματα όπως @code{python3.16} και στις δύο∙ ποιο χρησιμοποιείται στην πραγματικότητα εξαρτάται από τη σειρά που εμφανίζονται στο @code{PATH}. Οι εντολές @code{which python3.x} ή @code{which python3.xt} μπορούν να δείξουν ποια διαδρομή χρησιμοποιείται. Η χρήση εικονικών περιβαλλόντων μπορεί να βοηθήσει στην αποφυγή τέτοιων αμφισημιών. Μια άλλη επιλογή μπορεί να είναι η δημιουργία ενός κελύφους @code{alias} στον επιθυμητό διερμηνέα, όπως:

@example
alias py3.16="/Library/Frameworks/Python.framework/Versions/3.16/bin/python3.16"
alias py3.16t="/Library/Frameworks/PythonT.framework/Versions/3.16/bin/python3.16t"
@end example
@end itemize

@node Εγκατάσταση χρησιμοποιώντας τη γραμμή εντολών,Διανομή εφαρμογών Python,Εγκατάσταση εκδόσεων Free-threaded,Προχωρημένα θέματα
@anchor{using/mac installing-using-the-command-line}@anchor{2443}
@subsubsection Εγκατάσταση χρησιμοποιώντας τη γραμμή εντολών


Εάν θέλετε να χρησιμοποιήσετε αυτοματισμό για να εγκαταστήσετε το πακέτο εγκατάστασης @code{python.org} (παρά να χρησιμοποιήσετε την οικεία εφαρμογή @code{Installer} GUI macOS), το βοηθητικό πρόγραμμα @code{installer} γραμμής εντολών macOS σας επιτρέπει να επιλέξετε μη προεπιλεγμένες επιλογές, επίσης. Εάν δεν είστε εξοικειωμένοι με το @code{installer}, μπορεί να είναι κάπως κρυπτικό (βλ. @code{man installer} για περισσότερες πληροφορίες). Ως παράδειγμα, το παρακάτω απόσπασμα κώδικα δείχνει έναν τρόπο να το κάνετε, χρησιμοποιώντας την έκδοση @code{3.16.0b2} και επιλέγοντας την επιλογή διερμηνέα ελεύθερης νηματοποίησης:

@example
RELEASE="python-3.160b2-macos11.pkg"

# download installer pkg
curl -O https://www.python.org/ftp/python/3.16.0/$@{RELEASE@}

# create installer choicechanges to customize the install:
#    enable the PythonTFramework-3.16 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.16</string>
        </dict>
</array>
</plist>
EOF

sudo installer -pkg ./$@{RELEASE@} -applyChoiceChangesXML ./choicechanges.plist -target /
@end example

Μπορείτε στη συνέχεια να ελέγξετε ότι και οι δύο εγκαταστάτες είναι διαθέσιμοι με κάτι σαν:

@example
$ # test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled
$ /usr/local/bin/python3.16t -VV
Python 3.16.0b2 free-threading build (v3.16.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.16 -VV
Python 3.16.0b2 (v3.16.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.16t -VV
Python 3.16.0b2 free-threading build (v3.16.0b2:3a83b172af, Jun  5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
$ python3.16 -VV
Python 3.16.0b2 (v3.16.0b2:3a83b172af, Jun  5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
@end example

@cartouche
@quotation Σημείωση 
Τα τρέχοντα προγράμματα εγκατάστασης @code{python.org} εγκαθίστανται μόνο σε καθορισμένες τοποθεσίες όπως @code{/Library/Frameworks/}, @code{/Applications} και @code{/usr/local/bin}. Δεν μπορείτε να χρησιμοποιήσετε την επιλογή @code{-domain} του @code{installer} για να εγκαταστήσετε σε άλλες τοποθεσίες.
@end quotation
@end cartouche

@node Διανομή εφαρμογών Python,Συμμόρφωση App Store,Εγκατάσταση χρησιμοποιώντας τη γραμμή εντολών,Προχωρημένα θέματα
@anchor{using/mac distributing-python-applications}@anchor{2444}@anchor{using/mac distributing-python-applications-on-the-mac}@anchor{2445}
@subsubsection Διανομή εφαρμογών Python


Υπάρχει μια σειρά εργαλείων για τη μετατροπή του κώδικα Python σας σε μια αυτόνομη διανεμόμενη εφαρμογή:


@itemize *

@item 
py2app@footnote{https://pypi.org/project/py2app/}: Υποστηρίζει τη δημιουργία macOS @code{.app} πακέτων από ένα έργο Python.

@item 
Briefcase@footnote{https://briefcase.readthedocs.io}: Μέρος του BeeWare Project@footnote{https://beeware.org}; ένα εργαλείο διανομής πολλαπλών πλατφορμών που υποστηρίζει τη δημιουργία @code{.app} πακέτων σε macOS, καθώς και τη διαχείριση υπογραφής και πιστοποίησης.

@item 
PyInstaller@footnote{https://pyinstaller.org/}: Ένα εργαλείο διανομής πολλαπλών πλατφορμών που δημιουργεί ένα μόνο αρχείο ή φάκελο ως διανεμόμενο αντικείμενο.
@end itemize

@node Συμμόρφωση App Store,,Διανομή εφαρμογών Python,Προχωρημένα θέματα
@anchor{using/mac app-store-compliance}@anchor{2446}
@subsubsection Συμμόρφωση App Store


Οι εφαρμογές που υποβάλλονται για διανομή μέσω του macOS App Store πρέπει να περάσουν τη διαδικασία αναθεώρησης εφαρμογών της Apple. Αυτή η διαδικασία περιλαμβάνει ένα σύνολο αυτοματοποιημένων κανόνων επικύρωσης που ελέγχουν το υποβληθέν πακέτο εφαρμογής για προβληματικό κώδικα.

Η βιβλιοθήκη προτύπων Python περιέχει κάποιον κώδικα που είναι γνωστό ότι παραβιάζει αυτούς τους αυτοματοποιημένους κανόνες. Ενώ αυτές οι παραβιάσεις φαίνεται να είναι ψευδώς θετικές, οι κανόνες αναθεώρησης της Apple δεν μπορούν να αμφισβητηθούν. Επομένως, είναι απαραίτητο να τροποποιηθεί η βιβλιοθήκη προτύπων Python για να περάσει μια εφαρμογή την αναθεώρηση του App Store.

Το δέντρο πηγών Python περιέχει ένα αρχείο patch@footnote{https://github.com/python/cpython/tree/main/Mac/Resources/app-store-compliance.patch} που θα αφαιρέσει όλο τον κώδικα που είναι γνωστό ότι προκαλεί προβλήματα με τη διαδικασία αναθεώρησης του App Store. Αυτή η επιδιόρθωση εφαρμόζεται αυτόματα όταν η CPython διαμορφώνεται με την @ref{1ba4,,--with-app-store-compliance} επιλογή.

Αυτή η επιδιόρθωση δεν απαιτείται κανονικά για τη χρήση της CPython σε Mac. Ούτε απαιτείται εάν διανέμετε μια εφαρμογή `εκτός' του macOS App Store. Απαιτείται `μόνο' εάν χρησιμοποιείτε το macOS App Store ως κανάλι διανομής.

@node Άλλοι πόροι,,Προχωρημένα θέματα,Χρησιμοποιώντας Python σε macOS
@anchor{using/mac other-resources}@anchor{2447}
@subsection Άλλοι πόροι


Η python.org Help page@footnote{https://www.python.org/about/help/} έχει συνδέσμους σε πολλούς χρήσιμους πόρους. Η Pythonmac-SIG mailing list@footnote{https://www.python.org/community/sigs/current/pythonmac-sig/} είναι ένας άλλος πόρος υποστήριξης ειδικά για χρήστες και προγραμματιστές Python στο Mac.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Χρήση της Python σε Android,Χρήση Python σε iOS,Χρησιμοποιώντας Python σε macOS,Ρύθμιση και Χρήση της Python
@anchor{using/android doc}@anchor{2448}@anchor{using/android translation-repo}@anchor{2449}@anchor{using/android using-android}@anchor{244a}@anchor{using/android using-python-on-android}@anchor{244b}
@section Χρήση της Python σε Android


Η Python σε Android διαφέρει από την Python σε πλατφόρμες επιτραπέζιων υπολογιστών. Σε μια πλατφόρμα επιτραπέζιων υπολογιστών, η Python εγκαθίσταται γενικά ως πόρος συστήματος που μπορεί να χρησιμοποιηθεί από οποιονδήποτε χρήστη αυτού του υπολογιστή. Οι χρήστες στη συνέχεια αλληλεπιδρούν με την Python εκτελώντας ένα εκτελέσιμο @code{python} και εισάγοντας εντολές σε μια διαδραστική γραμμή εντολών ή εκτελώντας ένα Python script.

Στο Android, δεν υπάρχει η έννοια της εγκατάστασης ως πόρου συστήματος. Η μόνη μονάδα διανομής λογισμικού είναι μια «εφαρμογή». Δεν υπάρχει κονσόλα όπου θα μπορούσατε να εκτελέσετε ένα εκτελέσιμο αρχείο @code{python}, ή να αλληλεπιδράσετε με ένα Python REPL.

Ως αποτέλεσμα, ο μόνος τρόπος για να χρησιμοποιήσετε την Python σε Android είναι σε ενσωματωμένη λειτουργία – δηλαδή, γράφοντας μια εγγενή εφαρμογή Android, ενσωματώνοντας έναν διερμηνέα Python χρησιμοποιώντας το @code{libpython}, και καλώντας κώδικα Python χρησιμοποιώντας το @ref{244c,,Python embedding API}. Ο πλήρης διερμηνέας Python, η τυπική βιβλιοθήκη, και όλος ο κώδικας Python συσκευάζονται στη συνέχεια στην εφαρμογή σας για δική της ιδιωτική χρήση.

Η τυπική βιβλιοθήκη της Python έχει κάποιες αξιοσημείωτες παραλείψεις και περιορισμούς στο Android. Δείτε τον @ref{244d,,API availability guide} για λεπτομέρειες.

@menu
* Προσθήκη της Python σε μια εφαρμογή Android:: 
* Δημιουργία ενός πακέτου Python για Android:: 

@end menu

@node Προσθήκη της Python σε μια εφαρμογή Android,Δημιουργία ενός πακέτου Python για Android,,Χρήση της Python σε Android
@anchor{using/android adding-python-to-an-android-app}@anchor{244e}
@subsection Προσθήκη της Python σε μια εφαρμογή Android


Η πλειονότητα των ατόμων που προγραμματίζουν εφαρμογές θα πρέπει να χρησιμοποιούν ένα από τα ακόλουθα εργαλεία, τα οποία παρέχουν ευκολότερη εμπειρία:


@itemize *

@item 
Briefcase@footnote{https://briefcase.beeware.org}, from the BeeWare project

@item 
Buildozer@footnote{https://buildozer.readthedocs.io}, από το έργο Kivy

@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

Αν θέλετε να τα κάνετε όλα αυτά χειροκίνητα, συνεχίστε την ανάγνωση. Μπορείτε να χρησιμοποιήσετε την εντολή testbed app@footnote{https://github.com/python/cpython/tree/main/Android/testbed} ως οδηγό· κάθε βήμα παρακάτω περιέχει έναν σύνδεσμο προς το σχετικό αρχείο.


@itemize *

@item 
Πρώτον, αποκτήστε μια έκδοση της Python για Android:


@itemize *

@item 
Ο ευκολότερος τρόπος είναι να κατεβάσετε μια έκδοση Android από το python.org@footnote{https://www.python.org/downloads/android/}. Ο φάκελος @code{prefix} που αναφέρεται παρακάτω βρίσκεται στο ανώτατο επίπεδο του πακέτου.

@item 
Ή αν θέλετε να το δημιουργήσετε μόνοι σας, ακολουθήστε τις οδηγίες στο αρχείο:source:@cite{Android/README.md}. Ο φάκελος @code{prefix} θα δημιουργηθεί κάτω από το @code{cross-build/@var{HOST}}.
@end itemize

@item 
Προσθέστε κώδικα στο αρχείο σας build.gradle@footnote{https://github.com/python/cpython/tree/main/Android/testbed/app/build.gradle.kts} για να αντιγράψετε τα ακόλουθα στοιχεία στο έργο σας. Όλα εκτός από τον δικό σας κώδικα Python μπορούν να αντιγραφούν από το @code{prefix/lib}:


@itemize *

@item 
Στις JNI βιβλιοθήκες σας:


@itemize *

@item 
@code{libpython*.*.so}

@item 
@code{lib*_python.so} (εξωτερικές βιβλιοθήκες όπως το OpenSSL)
@end itemize

@item 
Στα στοιχεία σας:


@itemize *

@item 
@code{python*.*} (η τυπική βιβλιοθήκη της Python)

@item 
@code{python*.*/site-packages} (ο δικός σας Python κώδικας)
@end itemize
@end itemize

@item 
Προσθέστε κώδικα στην εφαρμογή σας για να εξαγάγετε τα στοιχεία στο σύστημα αρχείων@footnote{https://github.com/python/cpython/tree/main/Android/testbed/app/src/main/java/org/python/testbed/MainActivity.kt}.

@item 
Προσθέστε κώδικα στην εφαρμογή σας για να ξεκινήσετε την Python σε ενσωματωμένη λειτουργία@footnote{https://github.com/python/cpython/tree/main/Android/testbed/app/src/main/c/main_activity.c}. Αυτός θα πρέπει να είναι κώδικας C που καλείται μέσω JNI.
@end itemize

@node Δημιουργία ενός πακέτου Python για Android,,Προσθήκη της Python σε μια εφαρμογή Android,Χρήση της Python σε Android
@anchor{using/android building-a-python-package-for-android}@anchor{244f}
@subsection Δημιουργία ενός πακέτου Python για Android


Τα πακέτα Python μπορούν να δημιουργηθούν για Android ως wheels και να κυκλοφορήσουν στο PyPI. Το προτεινόμενο εργαλείο για αυτό είναι το cibuildwheel@footnote{https://cibuildwheel.pypa.io/en/stable/platforms/#android}, το οποίο αυτοματοποιεί όλες τις λεπτομέρειες του στησίματος ενός περιβάλλοντος διασταυρούμενης μεταγλώττισης, της δημιουργίας του wheel και της δοκιμής του σε έναν εξομοιωτή.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Χρήση Python σε iOS,Επεξεργαστές Κειμένου και IDEs,Χρήση της Python σε Android,Ρύθμιση και Χρήση της Python
@anchor{using/ios doc}@anchor{2450}@anchor{using/ios translation-repo}@anchor{2451}@anchor{using/ios using-ios}@anchor{2452}@anchor{using/ios using-python-on-ios}@anchor{2453}
@section Χρήση Python σε iOS


@*Συγγραφείς: 
Russell Keith-Magee (2024-03)


Η Python σε iOS διαφέρει από την Python σε πλατφόρμες επιτραπέζιων υπολογιστών. Σε μια πλατφόρμα επιτραπέζιων υπολογιστών, η Python εγκαθίσταται γενικά ως πόρος συστήματος που μπορεί να χρησιμοποιηθεί από οποιονδήποτε χρήστη αυτού του υπολογιστή. Στη συνέχεια, οι χρήστες αλληλεπιδρούν με την Python εκτελώντας ένα εκτελέσιμο αρχείο @code{python} και εισάγοντας εντολές σε μια διαδραστική γραμμή εντολών ή εκτελώντας ένα Python script.

Στο iOS, δεν υπάρχει η έννοια της εγκατάστασης ως πόρου συστήματος. Η μόνη μονάδα διανομής λογισμικού είναι μια «εφαρμογή». Επίσης, δεν υπάρχει κονσόλα που θα μπορούσατε να εκτελέσετε ένα εκτελέσιμο αρχείο @code{python} ή να αλληλεπιδράσετε με ένα Python REPL.

Ως αποτέλεσμα, ο μόνος τρόπος για να χρησιμοποιήσετε την Python σε iOS είναι σε ενσωματωμένη λειτουργία - δηλαδή, γράφοντας μια εγγενή εφαρμογή iOS και ενσωματώνοντας έναν διερμηνέα Python χρησιμοποιώντας το @code{libPython}, και καλώντας κώδικα Python χρησιμοποιώντας το @ref{244c,,Python embedding API}. Ο πλήρης διερμηνέας Python, η τυπική βιβλιοθήκη και όλος ο κώδικας Python σας συσκευάζονται στην συνέχεια ως αυτόνομο πακέτο που μπορεί να διανεμηθεί μέσω του iOS App Store.

Αν θέλετε να πειραματιστείτε για πρώτη φορά με τη σύνταξη μιας εφαρμογής iOS σε Python, έργα όπως BeeWare@footnote{https://beeware.org} και Kivy@footnote{https://kivy.org} θα σας προσφέρουν μια πολύ πιο προσιτή εμπειρία χρήστη. Αυτά τα έργα διαχειρίζονται τις πολυπλοκότητες που σχετίζονται με την εκτέλεση ενός έργου iOS, επομένως χρειάζεται να ασχοληθείτε μόνο με τον ίδιο τον κώδικα Python.

@menu
* Python κατά τον χρόνο εκτέλεσης σε iOS:: 
* Εγκατάσταση της Python σε iOS:: 
* Συμμόρφωση με το App Store:: 

@end menu

@node Python κατά τον χρόνο εκτέλεσης σε iOS,Εγκατάσταση της Python σε iOS,,Χρήση Python σε iOS
@anchor{using/ios python-at-runtime-on-ios}@anchor{2454}
@subsection Python κατά τον χρόνο εκτέλεσης σε iOS


@menu
* Συμβατότητα έκδοσης iOS:: 
* Αναγνώριση πλατφόρμας:: 
* Διαθεσιμότητα τυπικής βιβλιοθήκης:: 
* Δυαδικά modules επέκτασης:: 
* Δυαδικά αρχεία προσομοίωσης μεταγλωττιστή:: 

@end menu

@node Συμβατότητα έκδοσης iOS,Αναγνώριση πλατφόρμας,,Python κατά τον χρόνο εκτέλεσης σε iOS
@anchor{using/ios ios-version-compatibility}@anchor{2455}
@subsubsection Συμβατότητα έκδοσης iOS


Η ελάχιστη υποστηριζόμενη έκδοση iOS καθορίζεται κατά τη στιγμή της μεταγλώττισης, χρησιμοποιώντας την επιλογή @ref{23b0,,--host} για τη @code{ρύθμιση} παραμέτρων. Από προεπιλογή, όταν μεταγλωττίζεται για iOS, η Python θα μεταγλωττίζεται με μια ελάχιστη υποστηριζόμενη έκδοση iOS 13.0. Για να χρησιμοποιήστε μια διαφορετική ελάχιστη έκδοση iOS, δώστε τον αριθμό έκδοσης ως μέρος του ορίσματος @code{--host} - για παράδειγμα, το @code{--host=arm64-apple-ios15.4-simulator} θα μεταγλωττίσει μια έκδοση προσομοιωτή ARM64 με στόχο ανάπτυξης 15.4.

@node Αναγνώριση πλατφόρμας,Διαθεσιμότητα τυπικής βιβλιοθήκης,Συμβατότητα έκδοσης iOS,Python κατά τον χρόνο εκτέλεσης σε iOS
@anchor{using/ios platform-identification}@anchor{2456}
@subsubsection Αναγνώριση πλατφόρμας


Κατά την εκτέλεση σε iOS, το @code{sys.platform} θα αναφέρεται ως @code{ios}. Αυτή η τιμή θα επιστραφεί σε ένα iPhone ή iPad, ανεξάρτητα από το αν η εφαρμογή εκτελείται στον προσομοιωτή ή σε μια φυσική συσκευή.

Πληροφορίες σχετικά με το συγκεκριμένο περιβάλλον εκτέλεσης, συμπεριλαμβανομένης της έκδοσης iOS, του μοντέλου συσκευής και του εάν η συσκευή είναι προσομοιωτής, μπορούν να ληφθούν χρησιμοποιώντας την @ref{2457,,platform.ios_ver()}. Η @ref{2458,,platform.system()} θα αναφέρει @code{iOS} ή @code{iPadOS}, ανάλογα με τη συσκευή.

Η @ref{14c2,,os.uname()} αναφέρει λεπτομέρειες σε επίπεδο πυρήνα∙ θα αναφέρει ένα όνομα @code{Darwin}.

@node Διαθεσιμότητα τυπικής βιβλιοθήκης,Δυαδικά modules επέκτασης,Αναγνώριση πλατφόρμας,Python κατά τον χρόνο εκτέλεσης σε iOS
@anchor{using/ios standard-library-availability}@anchor{2459}
@subsubsection Διαθεσιμότητα τυπικής βιβλιοθήκης


Η τυπική βιβλιοθήκη Python έχει κάποιες αξιοσημείωτες παραλείψεις και περιορισμούς στο iOS. Δείτε στον οδηγό διαθεσιμότητας @ref{244d,,API availability guide for iOS} για λεπτομέρειες.

@node Δυαδικά modules επέκτασης,Δυαδικά αρχεία προσομοίωσης μεταγλωττιστή,Διαθεσιμότητα τυπικής βιβλιοθήκης,Python κατά τον χρόνο εκτέλεσης σε iOS
@anchor{using/ios binary-extension-modules}@anchor{245a}
@subsubsection Δυαδικά modules επέκτασης


Μια αξιοσημείωτη διαφορά σχετικά με το iOS ως πλατφόρμα είναι ότι η διανομή του App Store επιβάλλει αυστηρές απαιτήσεις σχετικά με τη συσκευασία μιας εφαρμογής. Μία από αυτές τις απαιτήσεις διέπει τον τρόπο διανομής των δυαδικών modules επέκτασης.

Το iOS App Store απαιτεί από `όλα' τα δυαδικά modules σε μια εφαρμογή iOS να είναι δυναμικές βιβλιοθήκες, που να περιέχονται σε ένα πλαίσιο με κατάλληλα μεταδεδομένα, αποθηκευμένα στον φάκελο @code{Frameworks} της συσκευασμένης εφαρμογής. Μπορεί να υπάρχει μόνο ένα δυαδικό αρχείο ανά πλαίσιο, και δεν μπορεί να υπάρχει εκτελέσιμο υλικό εκτός του φακέλου @code{Frameworks}.

Αυτό έρχεται σε αντίθεση με τη συνήθη προσέγγιση Python για τη διανομή δυαδικών αρχείων, η οποία επιτρέπει τη φόρτωση μιας δυαδικής επέκτασης module από οποιαδήποτε τοποθεσία στο @code{sys.path}. Για να διασφαλιστεί η συμμόρφωση με τις πολιτικές του App Store, ένα ενεργό iOS πρέπει να επεξεργαστεί εκ των υστέρων τυχόν πακέτα Python, μετατρέποντας τις δυαδικές μονάδες @code{.so} σε μεμονωμένα αυτόνομα πλαίσια με κατάλληλα μεταδεδομένα και υπογραφή. Για λεπτομέρειες σχετικά με τον τρόπο εκτέλεσης αυτή της μετα-επεξεργασίας, ανατρέξτε στον οδηγό @ref{245b,,adding Python to your project}.

Για να βοηθηθεί η Python στην ανακάλυψη δυαδικών αρχείων στη νέα τους θέση, το αρχικό αρχείο @code{.so} στο @code{sys.path} αντικαθίσταται με ένα αρχείο @code{.fwork}. Αυτό το αρχείο είναι ένα αρχείο κειμένου που περιέχει τη θέση του δυαδικού αρχείου του framework, σε σχέση με το app bundle. Για να επιτραπεί στο framework να επιστρέψει στην αρχική του θέση, το framework πρέπει να περιέχει ένα αρχείο @code{.origin} που περιέχει τη θέση του αρχείου @code{.fwork}, σε σχέση με το app bundle.

Για παράδειγμα, εξετάστε την περίπτωση μιας εντολής εισαγωγής @code{from foo.bar import _whiz}, όπου το @code{_whiz} υλοποιείται με το δυαδικό module @code{sources/foo/bar/_whiz.abi3.so}, με το @code{sources} να είναι η τοποθεσία που έχει καταχωρηθεί στο @code{sys.path}, σε σχέση με το bundle της εφαρμογής. Αυτό το module `πρέπει' να διανεμηθεί ως @code{Frameworks/foo.bar._whiz.framework/foo.bar._whiz} (δημιουργώντας το όνομα του framework από την πλήρη διαδρομή εισαγωγής του module), με ένα αρχείο @code{Info.plist} στον φάκελο @code{.framework} που να ταυτοποιεί το δυαδικό ως framework. Το module @code{foo.bar._whiz} θα εκπροσωπείται στην αρχική του τοποθεσία με ένα αρχείο δείκτη @code{sources/foo/bar/_whiz.abi3.fwork}, το οποίο περιέχει τη διαδρομή @code{Frameworks/foo.bar._whiz/foo.bar._whiz}. Το framework θα περιέχει επίσης το @code{Frameworks/foo.bar._whiz.framework/foo.bar._whiz.origin}, το οποίο περιέχει τη διαδρομή προς το αρχείο @code{.fwork}.

Κατά την εκτέλεση σε iOS, ο διερμηνέας της Python θα εγκαταστήσει μια @ref{245c,,AppleFrameworkLoader}, η οποία μπορεί να διαβάζει και να εισάγει αρχεία @code{.fwork}. Μόλις εισαχθεί, το χαρακτηριστικό @code{__file__} του δυαδικού module θα αναφέρει ως τοποθεσία το αρχείο @code{.fwork}. Ωστόσο, η @ref{245d,,ModuleSpec} για το φορτωμένο module θα αναφέρει ως @code{origin} την τοποθεσία του δυαδικού αρχείου στον φάκελο του framework.

@node Δυαδικά αρχεία προσομοίωσης μεταγλωττιστή,,Δυαδικά modules επέκτασης,Python κατά τον χρόνο εκτέλεσης σε iOS
@anchor{using/ios compiler-stub-binaries}@anchor{245e}
@subsubsection Δυαδικά αρχεία προσομοίωσης μεταγλωττιστή


Το Xcode δεν παρέχει άμεσα ξεχωριστούς μεταγλωττιστές για iOS· αντ’ αυτού, χρησιμοποιεί ένα script @code{xcrun} που επιλύει την πλήρη διαδρομή του μεταγλωττιστή (π.χ. @code{xcrun --sdk iphoneos clang} για να πάρετε τον @code{clang} για μια συσκευή iPhone). Ωστόσο, η χρήση αυτού του script δημιουργεί δύο προβλήματα:


@itemize *

@item 
Η έξοδος του @code{xcrun} περιλαμβάνει διαδρομές που εξαρτώνται από τη συγκεκριμένη μηχανή, με αποτέλεσμα ένα module sysconfig να μην μπορεί να κοινοποιηθεί μεταξύ διαφορετικών χρηστών· και

@item 
Αυτό έχει ως αποτέλεσμα οι ορισμοί των @code{CC}/@code{CPP}/@code{LD}/@code{AR} να περιλαμβάνουν κενά. Υπάρχουν πολλά εργαλεία στο οικοσύστημα της C που υποθέτουν ότι η εντολή μπορεί να χωριστεί στον πρώτο κενό χαρακτήρα ώστε να βρεθεί η διαδρομή προς το εκτελέσιμο του μεταγλωττιστή∙ κάτι που δεν ισχύει όταν χρησιμοποιείται το @code{xcrun}.
@end itemize

Για να αποφευχθούν αυτά τα προβλήματα, η Python παρέχει stubs για αυτά τα εργαλεία. Αυτά τα stubs είναι wrapper scripts κελύφους που τυλίγουν τα υποκείμενα εργαλεία του @code{xcrun}, και διανέμονται σε έναν φάκελο @code{bin} μαζί με το μεταγλωττισμένο iOS framework. Αυτά τα scripts μπορούν να προσαρμοστούν σε διαφορετικές τοποθεσίες, και πάντα θα δείχνουν στις σωστές τοπικές διαδρομές του συστήματος. Συμπεριλαμβάνοντας αυτά τα scripts στο φάκελο bin που συνοδεύει ένα framework, το περιεχόμενο του module @code{sysconfig} γίνεται χρήσιμο για τους τελικούς χρήστες, ώστε να μπορούν να μεταγλωττίζουν τα δικά τους modules. Όταν μεταγλωττίζετε τρίτα modules Python για iOS, πρέπει να βεβαιωθείτε ότι αυτά τα stub binaries είναι στο path σας.

@node Εγκατάσταση της Python σε iOS,Συμμόρφωση με το App Store,Python κατά τον χρόνο εκτέλεσης σε iOS,Χρήση Python σε iOS
@anchor{using/ios installing-python-on-ios}@anchor{245f}
@subsection Εγκατάσταση της Python σε iOS


@menu
* Εργαλεία για την κατασκευή εφαρμογών iOS:: 
* Προσθήκη Python σε ένα έργο iOS:: 
* Δοκιμή ενός πακέτου Python:: 

@end menu

@node Εργαλεία για την κατασκευή εφαρμογών iOS,Προσθήκη Python σε ένα έργο iOS,,Εγκατάσταση της Python σε iOS
@anchor{using/ios tools-for-building-ios-apps}@anchor{2460}
@subsubsection Εργαλεία για την κατασκευή εφαρμογών iOS


Η κατασκευή εφαρμογών για iOS απαιτεί τη χρήση των εργαλείων Xcode της Apple.Συνιστάται έντονα να χρησιμοποιείτε την πιο πρόσφατη σταθερή έκδοση του Xcode. Αυτό θα απαιτήσει να έχετε την πιο πρόσφατη (ή τη δεύτερη πιο πρόσφατη) έκδοση του macOS, καθώς η Apple δεν υποστηρίζει παλαιότερες εκδόσεις macOS με νέες εκδόσεις Xcode. Τα εργαλεία γραμμής εντολών Xcode δεν επαρκούν για ανάπτυξη iOS∙ χρειάζεται μια `πλήρης' εγκατάσταση του Xcode.

Αν θέλετε να τρέξετε τον κώδικά σας στον προσομοιωτή iOS, θα χρειαστεί επίσης να εγκαταστήσετε μια Πλατφόρμα Προσομοίωσης iOS. Κατά την πρώτη εκκίνηση του Xcode, θα σας ζητηθεί να επιλέξετε μια Πλατφόρμα Προσομοίωσης iOS. Εναλλακτικά, μπορείτε να προσθέσετε μια Πλατφόρμα προσομοίωσηςiOS επιλέγοντας την από την καρτέλα Platforms στο πάνελ ρυθμίσεων του Xcode.

@node Προσθήκη Python σε ένα έργο iOS,Δοκιμή ενός πακέτου Python,Εργαλεία για την κατασκευή εφαρμογών iOS,Εγκατάσταση της Python σε iOS
@anchor{using/ios adding-ios}@anchor{245b}@anchor{using/ios adding-python-to-an-ios-project}@anchor{2461}
@subsubsection Προσθήκη Python σε ένα έργο iOS


Η Python μπορεί να προστεθεί σε οποιοδήποτε έργο iOS, χρησιμοποιώντας είτε Swift είτε Objective C. Τα ακόλουθα παραδείγματα θα χρησιμοποιήσουν Objective C∙ εάν χρησιμοποιείτε Swift, μπορεί να σας φανεί χρήσιμη μια βιβλιοθήκη όπως το PythonKit@footnote{https://github.com/pvieito/PythonKit} .

Για να προσθέσετε Python σε ένα έργο iOS Xcode:


@enumerate 

@item 
Δημιουργήστε ή αποκτήστε ένα Python @code{XCFramework}. Δείτε τις οδηγίες στο iOS/README.rst@footnote{https://github.com/python/cpython/tree/main/iOS/README.rst} (στη διανομή πηγαίου κώδικα CPython) για λεπτομέρειες σχετικά με τον τρόπο δημιουργίας ενός Python @code{XCFramework}. Κατ” ελάχιστον, θα χρειαστείτε μια έκδοση που υποστηρίζει το @code{arm64-apple-ios}, καθώς και ένα από τα @code{arm64-apple-ios-simulator} ή @code{x86_64-apple-ios-simulator}.

@item 
Μεταφέρετε το @code{XCframework} στο iOS έργο σας. Στις ακόλουθες οδηγίες, θα υποθέσουμε ότι έχετε αποθέσει το @code{XCframework} στη ρίζα του έργου σας ωστόσο, μπορείτε να χρησιμοποιήσετε οποιαδήποτε άλλη τοποθεσία θέλετε προσαρμόζοντας τις διαδρομές όπως απαιτείται.

@item 
Προσθέστε τον κώδικα της εφαρμογής σας ως φάκελο στο έργο σας στο Xcode. Στις παρακάτω οδηγίες, θα υποθέσουμε ότι ο κώδικας του χρήστη βρίσκεται σε έναν φάκελο με όνομα @code{app} στη ριζική τοποθεσία του έργου σας· μπορείτε να χρησιμοποιήσετε οποιαδήποτε άλλη τοποθεσία, προσαρμόζοντας αναλόγως τις διαδρομές. Βεβαιωθείτε ότι αυτός ο φάκελος έχει συσχετιστεί με τον στόχο (target) της εφαρμογής σας.

@item 
Επιλέξτε τον στόχο της εφαρμογής επιλέγοντας τον ριζικό κόμβο του έργου σας στο Xcode και στη συνέχεια το όνομα του στόχου στην πλαϊνή στήλη που εμφανίζεται.

@item 
Στις ρυθμίσεις  «General» , κάτω από «Frameworks, Libraries and Embedded Content», προσθέστε το @code{Python.xcframework}, με επιλεγμένη την επιλογή «Embed & Sign»

@item 
Στην καρτέλα «Build Settings» , τροποποιήστε τα εξής


@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 
Προσθέστε ένα βήμα κατασκευής που αντιγράφει τη βασική βιβλιοθήκη Python στην εφαρμογή σας. Στην καρτέλα «Build Phases», προσθέστε ένα νέο βήμα κατασκευής «Run Script» `πριν' από το βήμα «Embed Frameworks», αλλά `μετά' το βήμα «Copy Bundle Resources». Ονομάστε το βήμα «Install Target Specific Python Standard Library», απενεργοποιήστε το πλαίσιο επιλογής «Based on dependency analysis» και ορίστε το περιεχόμενο του script ως εξής:

@example
set -e
source $PROJECT_DIR/Python.xcframework/build/build_utils.sh
install_python Python.xcframework app
@end example

Εάν έχετε τοποθετήσει το XCframework κάπου αλλού εκτός από τη ρίζα του έργου σας, τροποποιήστε τη διαδρομή στο πρώτο όρισμα.

@item 
Προσθέστε κώδικα Objective C για να αρχικοποιήσετε και να χρησιμοποιήσετε έναν διερμηνέα Python σε ενσωματωμένη λειτουργία. Θα πρέπει να βεβαιωθείτε ότι:


@itemize *

@item 
Η λειτουργία UTF-8 (@ref{630,,PyPreConfig.utf8_mode}) είναι `ενεργοποιημένη' ∙

@item 
Το Buffered stdio (@ref{624,,PyConfig.buffered_stdio}) είναι `απενεργοποιημένο' ∙

@item 
Η εγγραφή bytecode (@ref{620,,PyConfig.write_bytecode}) είναι `απενεργοποιημένη' ∙

@item 
Οι χειριστές σημάτων (@ref{c91,,PyConfig.install_signal_handlers}) είναι `ενεργοποιημένοι' ∙

@item 
Η καταγραφή συστήματος (@ref{2462,,PyConfig.use_system_logger}) είναι `ενεργοποιημένη' (προαιρετική, αλλά συνίσταται ανεπιφύλακτα∙ είναι ενεργοποιημένη από προεπιλογή)∙

@item 
Το 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} για τον διερμηνέα έχει ρυθμιστεί ώστε να δείχνει στον υποφάκελο @code{python} της δέσμης της εφαρμογής σας∙ και

@item 
Το 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} για τον διερμηνέα περιλαμβάνει:


@itemize -

@item 
τον υποφάκελο @code{python/lib/python3.X} της δέσμης της εφαρμογής σας,

@item 
τον υποφάκελο @code{python/lib/python3.X/lib-dynload} της δέσμης της εφαρμογής σας, και

@item 
τον υποφάκελο @code{app} της δέσμης της εφαρμογής σας
@end itemize
@end itemize

Η τοποθεσία της εφαρμογής σας στο πακέτο μπορεί να προσδιοριστεί χρησιμοποιώντας την εντολή @code{[[NSBundle mainBundle] resourcePath]}.
@end enumerate

Τα βήματα 7 και 8 αυτών των οδηγιών υποθέτουν ότι έχετε έναν μόνο φάκελο με καθαρό κώδικα εφαρμογής Python, με όνομα @code{app}. Εάν έχετε δυαδικά modules τρίτων στην εφαρμογή σας, θα απαιτηθούν επιπλέον βήματα:


@itemize *

@item 
Πρέπει να βεβαιωθείτε ότι τυχόν φάκελοι που περιέχουν δυαδικά αρχεία τρίτων είναι είτε συσχετισμένοι με τον στόχο της εφαρμογής είτε αντιγραμμένοι ως μέρος του βήματος 7. Το βήμα 7 θα πρέπει επίσης να καθαρίσει τυχόν δυαδικά αρχεία που δεν είναι κατάλληλα για την πλατφόρμα στην οποία στοχεύει μια συγκεκριμένη έκδοση (δηλαδή, να διαγράψει τυχόν δυαδικά αρχεία συσκευής εάν δημιουργείτε μια εφαρμογή που στοχεύει τον προσομοιωτή).

@item 
Εάν χρησιμοποιείτε ξεχωριστό φάκελο για πακέτα τρίτων, βεβαιωθείτε ότι ο φάκελος προστίθεται στο τέλος της κλήσης προς το @code{install_python} στο βήμα 7, και ως μέρος της διαμόρφωσης 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} στο βήμα 8.

@item 
Εάν οποιοιδήποτε από τους φακέλους που περιέχουν πακέτα τρίτων θα περιέχουν αρχεία @code{.pth}, θα πρέπει να προσθέσετε αυτόν τον φάκελο ως `site directory' (χρησιμοποιώντας τη @ref{2463,,site.addsitedir()}), αντί να τον προσθέσετε απευθείας στο 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} ή στο @ref{194,,sys.path}.
@end itemize

@node Δοκιμή ενός πακέτου Python,,Προσθήκη Python σε ένα έργο iOS,Εγκατάσταση της Python σε iOS
@anchor{using/ios testing-a-python-package}@anchor{2464}
@subsubsection Δοκιμή ενός πακέτου Python


Το δένδρο πηγαίου κώδικα της CPython περιέχει το a testbed project@footnote{https://github.com/python/cpython/tree/main/iOS/testbed} που χρησιμοποιείται για την εκτέλεση της σουίτας δοκιμών CPython στον προσομοιωτή iOS. Αυτό το δοκιμαστικό πλαίσιο μπορεί επίσης να χρησιμοποιηθεί ως έργο δοκιμαστικής πλατφόρμας για την εκτέλεση της σουίτας δοκιμών της βιβλιοθήκης Python σε iOS.

Αφού δημιουργήσετε ή αποκτήσετε ένα iOS XCFramework (δείτε το iOS/README.rst@footnote{https://github.com/python/cpython/tree/main/iOS/README.rst} για λεπτομέρειες), δημιουργήστε ένα κλώνο του έργου δοκιμαστικής πλατφόρμας Python iOS. Εάν χρησιμοποιήσατε το script κατασκευής @code{Apple} για να δημιουργήσετε το XCframework, μπορείτε να εκτελέσετε:

@example
$ python cross-build/iOS/testbed clone --app <path/to/module1> --app <path/to/module2> app-testbed
@end example

Ή, εάν έχετε δημιουργήσει το δικό σας XCframework, εκτελώντας:

@example
$ python Apple/testbed clone --platform iOS --framework <path/to/Python.xcframework> --app <path/to/module1> --app <path/to/module2> app-testbed
@end example

Οποιοιδήποτε φάκελοι καθοριστούν με το flag @code{--app} θα αντιγραφούν στο κλωνοποιημένο έργο testbed. Το τελικό testbed θα δημιουργηθεί στον φάκελο @code{app-testbed}. Σε αυτό το παράδειγμα, τα @code{module1} και @code{module2} θα είναι module που μπορούν να εισαχθούν κατά τον χρόνο εκτέλεσης. Αν το έργο σας έχει επιπλέον εξαρτήσεις μπορείτε να τις εγκαταστήσετε στον φάκελο @code{app-testbed/Testbed/app_packages} (χρησιμοποιώντας το @code{pip install --target app-testbed/Testbed/app_packages} ή παρόμοια εντολή).

Μπορείτε στη συνέχεια να χρησιμοποιήσετε το φάκελο @code{app-testbed} για να εκτελέσετε τη σουίτα δοκιμών για την εφαρμογή σας. Για παράδειγμα, εάν το @code{module1.tests} ήταν το σημείο εισόδου για τη σουίτα δοκιμών σας, θα μπορούσατε να εκτελέσετε:

@example
$ python app-testbed run -- module1.tests
@end example

Αυτό ισοδυναμεί με την εκτέλεση της εντολής @code{python -m module1.tests} σε μια έκδοση Python για επιτραπέζιους υπολογιστές. Οποιαδήποτε ορίσματα μετά το @code{--} θα περαστούν στο testbed σαν να ήταν ορίσματα στην εντολή @code{python -m} σε έναν επιτραπέζιο υπολογιστή.

Μπορείτε επίσης να ανοίξετε το έργο δοκιμαστικής πλατφόρμας στο Xcode εκτελώντας:

@example
$ open app-testbed/iOSTestbed.xcodeproj
@end example

Αυτό θα σας επιτρέψει να χρησιμοποιήσετε την πλήρη σουίτα εργαλείων Xcode για τον εντοπισμό σφαλμάτων.

Τα ορίσματα που χρησιμοποιούνται για την εκτέλεση της σουίτας δοκιμών ορίζονται ως μέρος του σχεδίου δοκιμών. Για να τροποποιήσετε το σχέδιο δοκιμών, επιλέξτε τον κόμβο του σχεδίου δοκιμών στο δέντρο του έργου (θα πρέπει να είναι το πρώτο παιδί του ριζικού κόμβου) και επιλέξτε την καρτέλα «Configurations». Τροποποιήστε την τιμή «Arguments Passed On Launch» για να αλλάξετε τα ορίσματα δοκιμής.

Το σχέδιο δοκιμών απενεργοποιεί επίσης τις παράλληλες δοκιμές και καθορίζει τη χρήση του αρχείου @code{Testbed.lldbinit} για την παροχή διαμόρφωσης του αποσφαλματωτή. Η προεπιλεγμένη διαμόρφωση του αποσφαλματωτή απενεργοποιεί τους αυτόματους σημερινούς σταθμούς (breakpoints) στα σήματα @code{SIGINT}, @code{SIGUSR1}, @code{SIGUSR2}, και @code{SIGXFSZ}.

@node Συμμόρφωση με το App Store,,Εγκατάσταση της Python σε iOS,Χρήση Python σε iOS
@anchor{using/ios app-store-compliance}@anchor{2465}
@subsection Συμμόρφωση με το App Store


Ο μόνος μηχανισμός για τη διανομή εφαρμογών σε τρίτες συσκευές iOS είναι η υποβολή της εφαρμογής στο iOS App Store∙ οι εφαρμογές που υποβάλλονται για διανομή πρέπει να περάσουν τη διαδικασία αξιολόγησης εφαρμογών της Apple. Αυτή η διαδικασία περιλαμβάνει ένα σύνολο αυτοματοποιημένων κανόνων επικύρωσης που ελέγχουν τη δέσμη της υποβληθείσας εφαρμογής για προβληματικό κώδικα. Υπάρχουν ορισμένα βήματα που πρέπει να ληφθούν για να διασφαλιστεί ότι η εφαρμογή σας θα μπορεί να περάσει αυτά τα βήματα επικύρωσης.

@menu
* Κώδικας ασύμβατος με την τυπική βιβλιοθήκη:: 
* Δηλώσεις απορρήτου:: 

@end menu

@node Κώδικας ασύμβατος με την τυπική βιβλιοθήκη,Δηλώσεις απορρήτου,,Συμμόρφωση με το App Store
@anchor{using/ios incompatible-code-in-the-standard-library}@anchor{2466}
@subsubsection Κώδικας ασύμβατος με την τυπική βιβλιοθήκη


Η τυπική βιβλιοθήκη Python περιέχει κώδικα που είναι γνωστό ότι παραβιάζει αυτούς τους αυτοματοποιημένους κανόνες. Ενώ αυτές οι παραβιάσεις φαίνεται να είναι ψευδώς θετικές, οι κανόνες αξιολόγησης της Apple δεν μπορούν να αμφισβητηθούν∙ επομένως, είναι απαραίτητο να τροποποιήσετε την τυπική βιβλιοθήκη Python για να περάσει μια εφαρμογή την αξιολόγηση του App Store.

Το δένδρο πηγαίου κώδικα της Python περιέχει a patch file@footnote{https://github.com/python/cpython/tree/main/Mac/Resources/app-store-compliance.patch} που θα αφαιρέσει όλον τον κώδικα που είναι γνωστό ότι προκαλεί προβλήματα με τη διαδικασία αξιολόγησης του App Store. Αυτό το patch εφαρμόζεται αυτόματα κατά την κατασκευή για iOS.

@node Δηλώσεις απορρήτου,,Κώδικας ασύμβατος με την τυπική βιβλιοθήκη,Συμμόρφωση με το App Store
@anchor{using/ios privacy-manifests}@anchor{2467}
@subsubsection Δηλώσεις απορρήτου


Τον Απρίλιο του 2025, η Apple εισήγαγε μια απαίτηση για ορισμένες βιβλιοθήκες τρίτων κατασκευαστών να παρέχουν μια Δήλωση Απορρήτου@footnote{https://developer.apple.com/support/third-party-SDK-requirements}. Ως αποτέλεσμα, εάν έχετε ένα δυαδικό module που χρησιμοποιεί μία από τις επηρεαζόμενες βιβλιοθήκες, πρέπει να παρέχετε ένα αρχείο @code{.xcprivacy} για αυτήν τη βιβλιοθήκη. Το OpenSSL είναι μία βιβλιοθήκη που επηρεάζεται από αυτήν την απαίτηση, αλλά υπάρχουν και άλλες.

Εάν παράγετε ένα δυαδικό module με το όνομα @code{mymodule.so}, και χρησιμοποιήσετε το script κατασκευής Xcode που περιγράφεται στο βήμα 8 παραπάνω, μπορείτε να τοποθετήσετε ένα αρχείο @code{mymodule.xcprivacy} δίπλα στο @code{mymodule.so}, και η δήλωση απορρήτου θα εγκατασταθεί στην απαιτούμενη τοποθεσία όταν το δυαδικό module μετατραπεί σε framework.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Επεξεργαστές Κειμένου και IDEs,,Χρήση Python σε iOS,Ρύθμιση και Χρήση της Python
@anchor{using/editors doc}@anchor{2468}@anchor{using/editors editors}@anchor{2439}@anchor{using/editors editors-and-ides}@anchor{2469}@anchor{using/editors translation-repo}@anchor{246a}
@section Επεξεργαστές Κειμένου και IDEs


Υπάρχουν αρκετά IDEs που υποστηρίζουν τη γλώσσα προγραμματισμού Python. Αρκετοί επεξεργαστές κειμένου και IDEs παρέχουν επισήμανση σύνταξης, εργαλεία αποσφαλμάτωσης και ελέγχους 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/}.

@menu
* IDLE — Επεξεργαστής και shell της Python:: 
* Άλλοι Επεξεργαστές Κειμένου και IDEs:: 

@end menu

@node IDLE — Επεξεργαστής και shell της Python,Άλλοι Επεξεργαστές Κειμένου και IDEs,,Επεξεργαστές Κειμένου και IDEs
@anchor{using/editors idle-python-editor-and-shell}@anchor{246b}
@subsection IDLE — Επεξεργαστής και shell της Python


Το IDLE είναι το Ολοκληρωμένο Περιβάλλον Ανάπτυξης και Εκμάθησης της Python και γενικά συνοδεύει τις εγκαταστάσεις της Python. Αν χρησιμοποιείτε Linux και δεν έχετε εγκατεστημένο το IDLE δείτε @ref{2336,,Installing IDLE on Linux}. Για περισσότερες πληροφορίες δείτε το @ref{13be,,IDLE docs}.

@node Άλλοι Επεξεργαστές Κειμένου και IDEs,,IDLE — Επεξεργαστής και shell της Python,Επεξεργαστές Κειμένου και IDEs
@anchor{using/editors other-editors-and-ides}@anchor{246c}
@subsection Άλλοι Επεξεργαστές Κειμένου και IDEs


Το wiki της κοινότητας της Python έχει πληροφορίες που έχουν υποβληθεί από την κοινότητα σχετικά με τους επεξεργαστές κειμένου και IDEs. Παρακαλούμε μεταβείτε στο Python Editors@footnote{https://wiki.python.org/moin/PythonEditors} και Integrated Development Environments@footnote{https://wiki.python.org/moin/IntegratedDevelopmentEnvironments} για ένα πλήρη κατάλογο.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Εγχειρίδιο Αναφοράς της Γλώσσας Python,The Python Standard Library,Ρύθμιση και Χρήση της Python,Top
@anchor{reference/index doc}@anchor{246d}@anchor{reference/index reference-index}@anchor{3f8}@anchor{reference/index the-python-language-reference}@anchor{246e}@anchor{reference/index translation-repo}@anchor{246f}
@chapter Εγχειρίδιο Αναφοράς της Γλώσσας Python


Αυτό το εγχειρίδιο αναφοράς περιγράφει τη σύνταξη και τη «βασική σημασιολογία» της γλώσσας. Είναι συνοπτικό, αλλά προσπαθεί να είναι ακριβές και πλήρες. Η σημασιολογία των μη απαραίτητων ενσωματωμένων τύπων αντικειμένων και των ενσωματωμένων συναρτήσεων και modules περιγράφεται στη @ref{3f7,,The Python Standard Library}. Για μια άτυπη εισαγωγή στη γλώσσα, ανατρέξτε στο @ref{21a9,,Οδηγός εκμάθησης Python}. Για προγραμματιστές C ή C++, υπάρχουν δύο επιπλέον εγχειρίδια: το @ref{21aa,,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python} περιγράφει τη συνολική εικόνα του τρόπου συγγραφής ενός module επέκτασης της Python και το @ref{21ab,,Python/C API reference manual} περιγράφει λεπτομερώς τις διεπαφές που είναι διαθέσιμες στους προγραμματιστές C/C++.

@menu
* Εισαγωγή: Εισαγωγή<2>. 
* Λεξική ανάλυση:: 
* Μοντέλο Δεδομένων:: 
* Μοντέλο εκτέλεσης:: 
* Το σύστημα εισαγωγής:: 
* Expressions:: 
* Απλές εντολές:: 
* Compound statements:: 
* Συστατικά ανωτάτου επιπέδου:: 
* Πλήρης προδιαγραφή γραμματικής:: 

@end menu

@node Εισαγωγή<2>,Λεξική ανάλυση,,Εγχειρίδιο Αναφοράς της Γλώσσας Python
@anchor{reference/introduction doc}@anchor{2470}@anchor{reference/introduction id1}@anchor{2471}@anchor{reference/introduction introduction}@anchor{2472}
@section Εισαγωγή


Αυτό το εγχειρίδιο αναφοράς περιγράφει την γλώσσα προγραμματισμού Python. Δεν προορίζεται ως εγχειρίδιο εκμάθησης.

Στην προσπάθεια το έγγραφο αυτό να είναι όσο το δυνατόν πιο ακριβές, επιλέχθηκε αρχικά η Αγγλική γλώσσα, και ύστερα μεταφράστηκε στην Ελληνική, και όχι οι επίσημες προδιαγραφές, με εξαίρεση την συντακτική και λεξιλογική ανάλυση. Αυτό θα πρέπει να κάνει το έγγραφο πιο κατανοητό στον μέσο αναγνώστη, αλλά θα αφήσει χώρο για αμφισημίες. Συνεπώς, αν ερχόσουν από τον Άρη και προσπαθούσες να υλοποιήσεις ξανά την Python από το έγγραφο αυτό και μόνο, μάλλον θα χρειαζόταν να μαντέψεις κάποια πράγματα και για την ακρίβεια ίσως θα κατέληγες να υλοποιείς μια τελείως διαφορετική γλώσσα. Από την άλλη πλευρά, αν χρησιμοποιείς την Python και αναρωτιέσαι ποιοι είναι οι ακριβείς κανόνες σχετικά με έναν συγκεκριμένο τομέα της γλώσσας, τότε σίγουρα θα τους βρεις εδώ πέρα. Αν θα ήθελες να δεις έναν πιο επίσημο ορισμό της γλώσσας, ίσως θα μπορούσες να προσφέρεις λίγο από τον χρόνο σου — ή να φτιάξεις μια μηχανή κλωνοποίησης :-).

Είναι επικίνδυνο να προσθέσουμε πολλές λεπτομέρειες υλοποίησης σε ένα έγγραφο αναφοράς μίας γλώσσας — η υλοποίηση δύναται να αλλάξει, και άλλες υλοποιήσεις της ίδιας γλώσσας μπορεί να λειτουργούν διαφορετικά. Από την άλλη, η CPython είναι μία υλοποίηση της Python με ευρεία χρήση (ωστόσο εναλλακτικές υλοποιήσεις συνεχίζουν να υποστηρίζονται), και οι συγκεκριμένες της ιδιομορφίες ενίοτε αξίζουν αναφορά, ειδικά εκεί που η υλοποίηση επιβάλλει επιπρόσθετους περιορισμούς. Επομένως, θα βρεις σύντομες «σημειώσεις υλοποίησης» σε διάφορα μέρη του κειμένου.

Κάθε υλοποίηση της Python συνοδεύεται από έναν αριθμό ενσωματωμένων και πρότυπων module. Αυτές είναι καταγεγραμμένες στο @ref{3f7,,The Python Standard Library}. Κάποια ενσωματωμένα module αναφέρονται όταν αλληλεπιδρούν με έναν σημαντικό τρόπο με τον ορισμό της γλώσσας.

@menu
* Εναλλακτικές Υλοποιήσεις:: 
* Σημειογραφία:: 

@end menu

@node Εναλλακτικές Υλοποιήσεις,Σημειογραφία,,Εισαγωγή<2>
@anchor{reference/introduction alternate-implementations}@anchor{2473}@anchor{reference/introduction implementations}@anchor{2307}
@subsection Εναλλακτικές Υλοποιήσεις


Παρόλο που υπάρχει μία υλοποίηση της Python που είναι μακράν η πιο διάσημη, υπάρχουν εναλλακτικές υλοποιήσεις που έχουν ιδιαίτερο ενδιαφέρον για διάφορους ανθρώπους.

Γνωστές υλοποιήσεις περιλαμβάνουν:


@table @asis

@item CPython

Αυτή είναι η πρωτότυπη και η πιο καλοδιατηρημένη υλοποίηση της Python, γραμμένη στην C. Νέες λειτουργίες της γλώσσας συνήθως εμφανίζονται πρώτα εδώ.

@item Jython

Η υλοποίηση της Python στην Java. Αυτή η υλοποίηση μπορεί να χρησιμοποιηθεί ως γλώσσα δέσμης ενεργειών για εφαρμογές στην Java, ή μπορεί να χρησιμοποιηθεί για να δημιουργήσει εφαρμογές με τη χρήση των βιβλιοθηκών των κλάσεων της Java. Συχνά επίσης χρησιμοποιείται για να δημιουργήσει τεστ για τις βιβλιοθήκες της Java. Περισσότερες πληροφορίες μπορείτε να βρείτε στην ιστοσελίδα της Jython@footnote{https://www.jython.org/}.

@item Python για το .NET

Αυτή η υλοποίηση στην πραγματικότητα χρησιμοποιεί την υλοποίηση CPython, αλλά είναι μία διαχειριζόμενη εφαρμογή του .NET και κάνει διαθέσιμες τις .NET βιβλιοθήκες. Δημιουργήθηκε από τον `Brian Lloyd'. Για περισσότερες πληροφορίες, δείτε την αρχική σελίδα της Python για το .NET@footnote{https://pythonnet.github.io/}.

@item IronPython

Μια εναλλακτική Python για το .NET. Σε αντίθεση με το Python.NET, αυτή είναι μία ολοκληρωμένη υλοποίηση της Python που παράγει IL, και κάνει μεταγλώττιση του κώδικα της Python απευθείας στη γλώσσα assembly του .NET. Δημιουργήθηκε από τον Jim Hugunin, τον πρωτότυπο δημιουργό της Jython. Για περισσότερες πληροφορίες δείτε την ιστοσελίδα της IronPython@footnote{https://ironpython.net/}.

@item PyPy

Μια υλοποίηση της Python γραμμένη εξ ολοκλήρου σε Python. Υποστηρίζει αρκετές προηγμένες λειτουργίες που δεν υπάρχουν σε άλλες υλοποιήσεις όπως υποστήριξη για stackless και τον μεταγλωττιστή Just in Time. Ένας από τους στόχους του πρότζεκτ είναι να ενθαρρύνει τον πειραματισμό με την ίδια την γλώσσα κάνοντας πιο εύκολη την τροποποίηση του διερμηνέα (αφού είναι γραμμένος στην Python). Περισσότερες πληροφορίες είναι διαθέσιμες στην αρχική σελίδα του PyPy πρότζεκτ@footnote{https://www.pypy.org/}.
@end table

Κάθε μία από αυτές τις υλοποιήσεις διαφοροποιούνται με κάποιον τρόπο από την γλώσσα όπως καταγράφεται σε αυτό το εγχειρίδιο, ή εισάγει συγκεκριμένη πληροφορία πέρα από ό,τι καλύπτουν τα πρότυπα έγγραφα της Python. Παρακαλώ να συμβουλευτείτε το έγγραφο της συγκεκριμένης υλοποίησης για να προσδιορίσετε τι άλλο χρειάζεται να ξέρετε σχετικά με την συγκεκριμένη υλοποίηση που χρησιμοποιείτε.

@node Σημειογραφία,,Εναλλακτικές Υλοποιήσεις,Εισαγωγή<2>
@anchor{reference/introduction id2}@anchor{2474}@anchor{reference/introduction notation}@anchor{2475}
@subsection Σημειογραφία


@geindex BNF
@geindex γραμματική
@geindex συντακτικό
@geindex σημειογραφία

Οι περιγραφές στην λεξιλογική ανάλυση και σύνταξη χρησιμοποιούν μια γραμματική σημειογραφία που είναι μείγμα των EBNF@footnote{https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form} και PEG@footnote{https://en.wikipedia.org/wiki/Parsing_expression_grammar}. Για παράδειγμα:

@example
@anchor{reference/introduction grammar-token-notation-name}@anchor{2476}name:   @ref{2477,,letter} (@ref{2477,,letter} | @ref{2478,,digit} | "_")*
@anchor{reference/introduction grammar-token-notation-letter}@anchor{2477}letter: "a"..."z" | "A"..."Z"
@anchor{reference/introduction grammar-token-notation-digit}@anchor{2478}digit:  "0"..."9"
@end example

Σε αυτό το παράδειγμα, η πρώτη γραμμή αναφέρει ότι ένα @code{name} είναι ένα @code{letter} ακολουθούμενο από μια ακολουθία μηδενός ή περισσότερων @code{γραμμάτος}ων, @code{ψηφίο}α, και κάτω παύλων. Ένα @code{letter} με τη σειρά του είναι οποιοσδήποτε από τους μεμονωμένους χαρακτήρες @code{'a'} έως @code{'z'} και @code{A} έως @code{Z} ∙ ένα @code{digit} είναι ένας μεμονωμένος χαρακτήρας από @code{0} έως @code{9}.

Κάθε κανόνας ξεκινά με ένα όνομα (το οποίο προσδιορίζει τον κανόνα που ορίζεται) ακολουθούμενο από άνω κάτω τελεία, @code{:}. Ο ορισμός στα δεξιά της άνω και κάτω τελείας χρησιμοποιεί τα ακόλουθα στοιχεία σύνταξης:


@itemize *

@item 
@code{name}: Ένα όνομα αναφέρεται σε έναν άλλο κανόνα, Όπου είναι δυνατόν, είναι ένας σύνδεσμος προς τον ορισμό του κανόνα.


@itemize *

@item 
@code{TOKEN}: Ένα κεφαλαίο όνομα αναφέρεται σε ένα @ref{2479,,token}. Για τους σκοπούς των γραμματικών ορισμών, τα tokens είναι το ίδιο με τους κανόνες.
@end itemize

@item 
@code{"text"}, @code{'text'}: Το κείμενο σε μονά ή διπλά εισαγωγικά πρέπει να ταιριάζει κυριολεκτικά (χωρίς τα εισαγωγικά). Ο τύπος του εισαγωγικού επιλέγεται ανάλογα με τη σημασία του @code{text}:


@itemize *

@item 
@code{'if'}: Ένα όνομα σε μονά εισαγωγικά υποδηλώνει μια @ref{247a,,keyword}.

@item 
@code{"case"}: Ένα όνομα σε διπλά εισαγωγικά υποδηλώνει ένα @ref{be6,,soft-keyword}.

@item 
@code{'@@'}: Ένα σύμβολο που δεν περιέχει γράμμα σε μονά εισαγωγικά υποδηλώνει ένα @ref{247b,,OP} token, δηλαδή, ένα @ref{247c,,delimiter} ή @ref{247d,,operator}.
@end itemize

@item 
@code{e1 e2}: Τα στοιχεία που χωρίζονται μόνο με κενό υποδηλώνουν μια ακολουθία. Εδώ, το @code{e1} πρέπει να ακολουθείται από το @code{e2}.

@item 
@code{e1 | e2}: Χρησιμοποιείται μια κάθετη γραμμή για τον διαχωρισμό των εναλλακτικών λύσεων. Υποδηλώνει την «διατεταγμένη επιλογή» του PEG: εάν το @code{e1} ταιριάζει, το @code{e2} δεν λαμβάνεται υπόψη. Στις παραδοσιακές γραμματικές του PEG, αυτό γράφεται ως κάθετος, @code{/}, αντί για κάθετη γραμμή. Δείτε το 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/} για περισσότερες πληροφορίες και λεπτομέρειες.

@item 
@code{e*}: Ένας αστερίσκος σημαίνει μηδέν ή περισσότερες επαναλήψεις του προηγούμενοι στοιχείου.

@item 
@code{e+}: Ομοίως, ένα συν σημαίνει μία ή περισσότερες επαναλήψεις.

@item 
@code{[e]}: Μια φράση που περικλείεται σε αγκύλες σημαίνει μηδέν ή μία εμφάνιση. Με άλλα λόγια, η φράση που περικλείεται είναι προαιρετική.

@item 
@code{e?}: Ένα ερωτηματικό έχει ακριβώς την ίδια σημασία με τις αγκύλες: το προηγούμενο στοιχείο είναι προαιρετικό.

@item 
@code{(e)}: Οι παρενθέσεις χρησιμοποιούνται για ομαδοποίηση.
@end itemize

Η ακόλουθη σημειογραφία χρησιμοποιείται μόνο σε @ref{247e,,λεξιλογικούς ορισμούς}.


@itemize *

@item 
@code{"a"..."z"}: Δύο κυριολεκτικοί χαρακτήρες διαχωρισμένοι από τρεις τελείες σημαίνουν την επιλογή οποιουδήποτε μεμονωμένου χαρακτήρα στο δεδομένο (συμπεριλαμβανομένου) εύρος χαρακτήρων ASCII.

@item 
@code{<...>}: Μια φράση μέσα σε γωνιακές αγκύλες δίνει μια άτυπη περιγραφή του αντίστοιχου συμβόλου (για παράδειγμα @code{<any ASCII character except "\">}), ή μια συντομογραφία που ορίζεται σε κοντινό κείμενο (για παράδειγμα, @code{<Lu>}).
@end itemize
@anchor{reference/introduction lexical-lookaheads}@anchor{247f}
Ορισμοί επίσης χρησιμοποιούν `lookaheads', που υποδεικνύουν ότι ένα στοιχείο πρέπει (ή δεν πρέπει) να ταιριάζει σε μια δεδομένη θέση, αλλά χωρίς να καταναλώνει οποιαδήποτε είσοδο:


@itemize *

@item 
@code{&e}: μια θετική προοπτική (δηλαδή, το @code{e} απαιτείται να ταιριάζει)

@item 
@code{!e}: μια αρνητική προοπτική (δηλαδή, το @code{e} απαιτείται `να μην' ταιριάζει)
@end itemize

Οι μοναδιαίοι τελεστές (@code{*}, @code{+}, @code{?}) συνδέονται όσο το δυνατόν πιο σφιχτά∙ η κάθετη γραμμή (@code{|}) συνδέεται πιο χαλαρά.

Το κενό έχει νόημα μόνο για τον διαχωρισμό των διακριτικών.

Οι κανόνες συνήθως περιέχονται σε μία μόνο γραμμή, αλλά οι κανόνες που είναι πολύ μεγάλοι μπορούν να αναδιπλωθούν.

@example
@anchor{reference/introduction grammar-token-notation-literal}@anchor{2480}literal: stringliteral | bytesliteral
         | integer | floatnumber | imagnumber
@end example

Εναλλακτικά, οι κανόνες μπορούν να μορφοποιηθούν με την πρώτη γραμμή να τελειών στην άνω και κάτω τελεία και κάθε εναλλακτική να ξεκινά με μια κάθετη γραμμή σε μια νέα γραμμή. Για παράδειγμα:

@example
@anchor{reference/introduction grammar-token-notation-alt-literal}@anchor{2481}literal:
   | stringliteral
   | bytesliteral
   | integer
   | floatnumber
   | imagnumber
@end example

Αυτό `δεν' σημαίνει ότι υπάρχει μια κενή πρώτη εναλλακτική λύση.

@geindex λεξιλογικοί ορισμοί

@menu
* Λεξικοί και Συντακτικοί ορισμοί:: 

@end menu

@node Λεξικοί και Συντακτικοί ορισμοί,,,Σημειογραφία
@anchor{reference/introduction lexical-and-syntactic-definitions}@anchor{2482}@anchor{reference/introduction notation-lexical-vs-syntactic}@anchor{247e}
@subsubsection Λεξικοί και Συντακτικοί ορισμοί


Υπάρχει κάποια διαφορά μεταξύ της `λεξικής' και της `συντακτικής' ανάλυσης: ο @ref{2483,,lexical analyzer} λειτουργεί στους μεμονωμένους χαρακτήρες της πηγής εισόδου, ενώ ο `αναλυτής' (συντακτικός αναλυτής) λειτουργεί στη ροή των @ref{2479,,tokens} που δημιουργούνται από τη λεξική ανάλυση. Ωστόσο, σε ορισμένες περιπτώσεις το ακριβές όριο μεταξύ των δύο φάσεων είναι μια λεπτομέρεια υλοποίησης της CPython.

Η πρακτική διαφορά μεταξύ των δύο είναι ότι στους `λεξιλογικούς' ορισμούς, όλα τα κενά είναι σημαντικά. Ο λεξικός αναλυτής @ref{2484,,discards} όλα τα κενά που δεν μετατρέπονται σε διακριτικά όπως @ref{22ec,,token.INDENT} ή @ref{2485,,NEWLINE}. Οι `συντακτικοί' ορισμοί χρησιμοποιούν στη συνέχεια αυτά τα διακριτικά, αντί για τους χαρακτήρες προέλευσης.

Αυτή η τεκμηρίωση χρησιμοποιεί την ίδια γραμματική BNF και για τα δύο στυλ ορισμών. Όλες οι χρήσεις του BNF στο επόμενο κεφάλαιο (@ref{2486,,Λεξική ανάλυση}) είναι λεξιλογικοί ορισμοί∙ οι χρήσεις στα επόμενα κεφάλαια είναι συντακτικοί ορισμοί.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Λεξική ανάλυση,Μοντέλο Δεδομένων,Εισαγωγή<2>,Εγχειρίδιο Αναφοράς της Γλώσσας Python
@anchor{reference/lexical_analysis doc}@anchor{2487}@anchor{reference/lexical_analysis lexical}@anchor{2486}@anchor{reference/lexical_analysis lexical-analysis}@anchor{2488}@anchor{reference/lexical_analysis translation-repo}@anchor{2489}
@section Λεξική ανάλυση


@geindex λεξική ανάλυση
@geindex αναλυτής (parser)
@geindex token

Ένα πρόγραμμα Python διαβάζεται από έναν `αναλυτή (parser)'. Η είσοδος του αναλυτή είναι μια ροή από @ref{2479,,tokens}, που παράγεται από τον `λεξικό αναλυτή' (γνωστό και ως `tokenizer'). Αυτό το κεφάλαιο περιγράφει πώς ο λεξικός αναλυτής παράγει αυτά τα tokens.

Ο λεξικός αναλυτής καθορίζει την @ref{248a,,κωδικοποίηση} του κειμένου του προγράμματος (UTF-8 από προεπιλογή) και αποκωδικοποιεί το κείμενο σε @ref{248b,,χαρακτήρες πηγής}. Αν το κείμενο δεν μπορεί να αποκωδικοποιηθεί, γίνεται raise ένα @ref{17e,,SyntaxError}.

Στη συνέχεια, ο λεξικός αναλυτής χρησιμοποιεί τους χαρακτήρες προέλευσης για να δημιουργήσει μια ροή από tokens. Ο τύπος ενός παραγόμενου token γενικά εξαρτάται από τον επόμενο χαρακτήρα πηγής που πρόκειται να επεξεργαστεί. Αντίστοιχα, άλλες ειδικές συμπεριφορές του αναλυτή εξαρτώνται από τον πρώτο χαρακτήρα πηγής που δεν έχει ακόμη επεξεργαστεί. Ο παρακάτω πίνακας δίνει μια σύντομη σύνοψη αυτών των χαρακτήρων πηγής, με συνδέσμους προς τις ενότητες που περιέχουν περισσότερες πληροφορίες.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Χαρακτήρας

@tab

Επόμενο token (ή άλλη σχετική τεκμηρίωση)

@item


@itemize *

@item 
κενό

@item 
tab

@item 
αλλαγή σελίδας (formfeed)
@end itemize

@tab


@itemize *

@item 
@ref{2484,,Κενά διαστήματα}
@end itemize

@item


@itemize *

@item 
CR, LF
@end itemize

@tab


@itemize *

@item 
@ref{248c,,Νέα γραμμή}

@item 
@ref{248d,,Εσοχή}
@end itemize

@item


@itemize *

@item 
ανάστροφη κάθετος (backslash) (@code{\})
@end itemize

@tab


@itemize *

@item 
@ref{248e,,Ρητή συνένωση γραμμών}

@item 
(Σημαντική επίσης στις @ref{874,,ακολουθίες διαφυγής συμβολοσειρών})
@end itemize

@item


@itemize *

@item 
δίεση (@code{#})
@end itemize

@tab


@itemize *

@item 
@ref{248f,,Σχόλιο}
@end itemize

@item


@itemize *

@item 
εισαγωγικό (@code{'}, @code{"})
@end itemize

@tab


@itemize *

@item 
@ref{2490,,Συμβολοσειρά}
@end itemize

@item


@itemize *

@item 
γράμμα ASCII (@code{a}-@code{z}, @code{A}-@code{Z})

@item 
μη-ASCII χαρακτήρας
@end itemize

@tab


@itemize *

@item 
@ref{2491,,Όνομα}

@item 
Λεκτικό @ref{2490,,συμβολοσειράς ή bytes με πρόθεμα}
@end itemize

@item


@itemize *

@item 
κάτω παύλα (@code{_})
@end itemize

@tab


@itemize *

@item 
@ref{2491,,Όνομα}

@item 
(Μπορεί επίσης να αποτελεί μέρος @ref{2492,,αριθμητικών})
@end itemize

@item


@itemize *

@item 
αριθμός (@code{0}-@code{9})
@end itemize

@tab


@itemize *

@item 
@ref{2492,,Αριθμητικό}
@end itemize

@item


@itemize *

@item 
τελεία (@code{.})
@end itemize

@tab


@itemize *

@item 
@ref{2492,,Αριθμητικό}

@item 
@ref{247d,,Τελεστής}
@end itemize

@item


@itemize *

@item 
ερωτηματικό (@code{?})

@item 
σύμβολο δολαρίου (@code{$})

@item 
@c (the following uses zero-width space characters to render

@c a literal backquote)

ανάποδο εισαγωγικό (@code{​`​})

@item 
χαρακτήρας ελέγχου
@end itemize

@tab


@itemize *

@item 
Σφάλμα (εκτός λεκτικών συμβολοσειράς και σχολίων)
@end itemize

@item


@itemize *

@item 
άλλος εκτυπώσιμος χαρακτήρας
@end itemize

@tab


@itemize *

@item 
@ref{247d,,Τελεστής ή delimiter}
@end itemize

@item


@itemize *

@item 
τέλος αρχείου
@end itemize

@tab


@itemize *

@item 
@ref{2493,,Δείκτης τέλους}
@end itemize

@end multitable


@menu
* Δομή γραμμών:: 
* Άλλα tokens:: 
* Ονόματα (αναγνωριστικά και λέξεις-κλειδιά): Ονόματα αναγνωριστικά και λέξεις-κλειδιά. 
* Λεκτικά:: 
* Λεκτικά συμβολοσειράς και Bytes:: 
* Αριθμητικά λεκτικά:: 
* Τελεστές και οριοθέτες:: 

@end menu

@node Δομή γραμμών,Άλλα tokens,,Λεξική ανάλυση
@anchor{reference/lexical_analysis id1}@anchor{2494}@anchor{reference/lexical_analysis line-structure}@anchor{248c}
@subsection Δομή γραμμών


@geindex δομή γραμμών

Ένα πρόγραμμα Python χωρίζεται σε έναν αριθμό από `λογικές γραμμές'.

@menu
* Λογικές γραμμές:: 
* Φυσικές γραμμές:: 
* Σχόλια:: 
* Δηλώσεις κωδικοποίησης:: 
* Ρητή συνένωση γραμμών:: 
* Έμμεση συνένωση γραμμών:: 
* Κενές γραμμές:: 
* Εσοχή:: 
* Κενοί χαρακτήρες μεταξύ των tokens:: 
* Δείκτης τέλους:: 

@end menu

@node Λογικές γραμμές,Φυσικές γραμμές,,Δομή γραμμών
@anchor{reference/lexical_analysis id2}@anchor{2495}@anchor{reference/lexical_analysis logical-lines}@anchor{2496}
@subsubsection Λογικές γραμμές


@geindex λογική γραμμή
@geindex φυσική γραμμή
@geindex συνένωση γραμμών
@geindex token NEWLINE

Το τέλος μιας λογικής γραμμής αναπαρίσταται από το token @ref{2485,,NEWLINE}. Οι εντολές δεν μπορούν να διασχίσουν τα όρια λογικών γραμμών, εκτός αν το @code{NEWLINE} επιτρέπεται από τη σύνταξη (π.χ. μεταξύ εντολών σε σύνθετες εντολές). Μια λογική γραμμή κατασκευάζεται από μία ή περισσότερες `φυσικές γραμμές' ακολουθώντας τους κανόνες `συνένωσης γραμμών' @ref{248e,,ρητής} ή @ref{2497,,έμμεσης}.

@node Φυσικές γραμμές,Σχόλια,Λογικές γραμμές,Δομή γραμμών
@anchor{reference/lexical_analysis id3}@anchor{2498}@anchor{reference/lexical_analysis physical-lines}@anchor{2499}
@subsubsection Φυσικές γραμμές


Μια φυσική γραμμή είναι μια ακολουθία χαρακτήρων που τερματίζεται από μία από τις παρακάτω ακολουθίες τέλους γραμμής:


@itemize *

@item 
τη μορφή Unix που χρησιμοποιεί ASCII LF (linefeed),

@item 
τη μορφή Windows που χρησιμοποιεί την ASCII ακολουθία CR LF (return ακολουθούμενο από linefeed),

@item 
τη μορφή “Classic Mac OS@footnote{https://en.wikipedia.org/wiki/Classic_Mac_OS}” που χρησιμοποιεί τον χαρακτήρα ASCII CR (return).
@end itemize

Ανεξάρτητα από την πλατφόρμα, καθεμία από αυτές τις ακολουθίες αντικαθίσταται από έναν μόνο χαρακτήρα ASCII LF (linefeed). (Αυτό γίνεται ακόμη και μέσα σε @ref{2490,,συμβολοσειρές}.) Κάθε γραμμή μπορεί να χρησιμοποιεί οποιαδήποτε από τις ακολουθίες· δεν χρειάζεται να είναι συνεπείς μέσα στο ίδιο αρχείο.

Το τέλος της εισόδου λειτουργεί επίσης ως έμμεσο τέλος για την τελευταία φυσική γραμμή.

Τυπικά:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-newline}@anchor{249a}newline: <ASCII LF> | <ASCII CR> <ASCII LF> | <ASCII CR>
@end example

@node Σχόλια,Δηλώσεις κωδικοποίησης,Φυσικές γραμμές,Δομή γραμμών
@anchor{reference/lexical_analysis comments}@anchor{248f}@anchor{reference/lexical_analysis id5}@anchor{249b}
@subsubsection Σχόλια


@geindex σχόλιο
@geindex χαρακτήρας δίεσης
@geindex # (δίεση);σχόλιο

Ένα σχόλιο ξεκινά με τον χαρακτήρα δίεσης (@code{#}) που δεν αποτελεί μέρος συμβολοσειράς και τελειώνει στο τέλος της φυσικής γραμμής. Ένα σχόλιο σηματοδοτεί το τέλος της λογικής γραμμής, εκτός αν εφαρμόζονται οι κανόνες έμμεσης συνένωσης γραμμών. Τα σχόλια αγνοούνται από τη σύνταξη.

@node Δηλώσεις κωδικοποίησης,Ρητή συνένωση γραμμών,Σχόλια,Δομή γραμμών
@anchor{reference/lexical_analysis encoding-declarations}@anchor{249c}@anchor{reference/lexical_analysis encodings}@anchor{248a}
@subsubsection Δηλώσεις κωδικοποίησης


@geindex σύνολο χαρακτήρων πηγής
@geindex δηλώσεις κωδικοποίησης (αρχείο πηγής)
@geindex # (δίεση);δήλωση κωδικοποίησης πηγής

Αν ένα σχόλιο στην πρώτη ή δεύτερη γραμμή ενός Python script ταιριάζει με την κανονική έκφραση (regular expression) @code{coding[=:]\s*([-\w.]+)}, τότε το σχόλιο επεξεργάζεται ως δήλωση κωδικοποίησης· η πρώτη ομάδα αυτής της έκφρασης ονομάζει την κωδικοποίηση του αρχείου πηγαίου κώδικα. Η δήλωση κωδικοποίησης πρέπει να εμφανίζεται μόνη της σε μια γραμμή. Αν βρίσκεται στη δεύτερη γραμμή, τότε η πρώτη γραμμή πρέπει να περιέχει μόνο σχόλιο. Οι προτεινόμενες μορφές δήλωσης κωδικοποίησης είναι

@example
# -*- coding: <encoding-name> -*-
@end example

η οποία αναγνωρίζεται επίσης από το GNU Emacs, και

@example
# vim:fileencoding=<encoding-name>
@end example

η οποία αναγνωρίζεται από το VIM του Bram Moolenaar.

Αν δεν βρεθεί δήλωση κωδικοποίησης, η προεπιλεγμένη κωδικοποίηση είναι UTF-8. Αν η έμμεση ή ρητή κωδικοποίηση ενός αρχείου είναι UTF-8, ένα αρχικό UTF-8 byte-order mark (@code{b'\xef\xbb\xbf'}) αγνοείται αντί να θεωρείται σφάλμα σύνταξης.

Αν δηλωθεί κωδικοποίηση, το όνομά της πρέπει να αναγνωρίζεται από την Python (βλ. @ref{1171,,Standard Encodings}). Η κωδικοποίηση χρησιμοποιείται για όλη τη λεξική ανάλυση, συμπεριλαμβανομένων λεκτικών συμβολοσειράς, σχολίων και αναγνωριστικών.
@anchor{reference/lexical_analysis lexical-source-character}@anchor{248b}
Όλη η λεξική ανάλυση, συμπεριλαμβανομένων λεκτικών συμβολοσειράς, σχολίων και αναγνωριστικών, γίνεται πάνω σε κείμενο Unicode που έχει αποκωδικοποιηθεί με την κωδικοποίηση πηγής. Οποιοδήποτε σημείο κώδικα Unicode, εκτός από τον χαρακτήρα ελέγχου NUL, μπορεί να εμφανιστεί σε πηγαίο κώδικα Python.

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-source_character}@anchor{249d}source_character:  <any Unicode code point, except NUL>
@end example

@node Ρητή συνένωση γραμμών,Έμμεση συνένωση γραμμών,Δηλώσεις κωδικοποίησης,Δομή γραμμών
@anchor{reference/lexical_analysis explicit-joining}@anchor{248e}@anchor{reference/lexical_analysis explicit-line-joining}@anchor{249e}
@subsubsection Ρητή συνένωση γραμμών


@geindex φυσική γραμμή
@geindex συνένωση γραμμών
@geindex συνέχιση γραμμής
@geindex χαρακτήρας ανάστροφης καθέτου

Δύο ή περισσότερες φυσικές γραμμές μπορούν να ενωθούν σε λογικές γραμμές χρησιμοποιώντας χαρακτήρες ανάστροφης καθέτου (@code{\}), ως εξής: όταν μια φυσική γραμμή τελειώνει με ανάστροφη κάθετο που δεν αποτελεί μέρος λεκτικού συμβολοσειράς ή σχολίου, ενώνεται με την επόμενη σχηματίζοντας μία λογική γραμμή, διαγράφοντας την ανάστροφη κάθετο και τον ακόλουθο χαρακτήρα τέλους γραμμής. Για παράδειγμα:

@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

Μια γραμμή που τελειώνει με ανάστροφη κάθετο δεν μπορεί να περιέχει σχόλιο. Η ανάστροφη κάθετος δεν συνεχίζει ένα σχόλιο. Η ανάστροφη κάθετος δεν συνεχίζει ένα token, εκτός από λεκτικά συμβολοσειράς (δηλ. tokens διαφορετικά από λεκτικά συμβολοσειράς δεν μπορούν να «σπάσουν» σε περισσότερες φυσικές γραμμές με χρήση ανάστροφης καθέτου). Η ανάστροφη κάθετος είναι παράνομη οπουδήποτε αλλού σε μια γραμμή εκτός λεκτικού συμβολοσειράς.

@node Έμμεση συνένωση γραμμών,Κενές γραμμές,Ρητή συνένωση γραμμών,Δομή γραμμών
@anchor{reference/lexical_analysis implicit-joining}@anchor{2497}@anchor{reference/lexical_analysis implicit-line-joining}@anchor{249f}
@subsubsection Έμμεση συνένωση γραμμών


Εκφράσεις μέσα σε παρενθέσεις, αγκύλες ή άγκιστρα μπορούν να χωριστούν σε περισσότερες από μία φυσικές γραμμές χωρίς χρήση ανάστροφων καθέτων. Για παράδειγμα:

@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

Οι έμμεσα συνεχόμενες γραμμές μπορούν να περιέχουν σχόλια. Η εσοχή των γραμμών συνέχισης δεν είναι σημαντική. Επιτρέπονται κενές γραμμές συνέχισης. Δεν υπάρχει token NEWLINE ανάμεσα σε έμμεσα συνεχόμενες γραμμές. Έμμεσα συνεχόμενες γραμμές μπορούν επίσης να εμφανιστούν μέσα σε συμβολοσειρές τριπλών εισαγωγικών (βλ. παρακάτω)· σε αυτή την περίπτωση δεν μπορούν να περιέχουν σχόλια.

@node Κενές γραμμές,Εσοχή,Έμμεση συνένωση γραμμών,Δομή γραμμών
@anchor{reference/lexical_analysis blank-lines}@anchor{24a0}@anchor{reference/lexical_analysis id6}@anchor{24a1}
@subsubsection Κενές γραμμές


@geindex κενή γραμμή

Μια λογική γραμμή που περιέχει μόνο κενά, tabs, αλλαγές σελίδας και πιθανόν σχόλιο, αγνοείται (δηλ. δεν παράγεται token @ref{2485,,NEWLINE}). Κατά τη διαδραστική εισαγωγή εντολών, ο χειρισμός μιας κενής γραμμής μπορεί να διαφέρει ανάλογα με την υλοποίηση του read-eval-print loop. Στον τυπικό διαδραστικό διερμηνέα, μια εντελώς κενή λογική γραμμή (δηλ. που δεν περιέχει ούτε κενούς χαρακτήρες ούτε σχόλιο) τερματίζει μια εντολή πολλαπλών γραμμών.

@node Εσοχή,Κενοί χαρακτήρες μεταξύ των tokens,Κενές γραμμές,Δομή γραμμών
@anchor{reference/lexical_analysis id7}@anchor{24a2}@anchor{reference/lexical_analysis indentation}@anchor{248d}
@subsubsection Εσοχή


@geindex εσοχή
@geindex αρχικοί κενοί χαρακτήρες
@geindex κενό
@geindex tab
@geindex ομαδοποίηση
@geindex ομαδοποίηση εντολών

Οι αρχικοί κενοί χαρακτήρες (κενά και tabs) στην αρχή μιας λογικής γραμμής χρησιμοποιούνται για τον υπολογισμό του επιπέδου εσοχής της γραμμής, το οποίο με τη σειρά του χρησιμοποιείται για να καθοριστεί η ομαδοποίηση των εντολών.

Τα tabs αντικαθίστανται (από αριστερά προς τα δεξιά) από ένα έως οκτώ κενά έτσι ώστε το συνολικό πλήθος χαρακτήρων μέχρι και την αντικατάσταση να είναι πολλαπλάσιο του οκτώ (πρόκειται για τον ίδιο κανόνας που χρησιμοποιείται στο Unix). Το συνολικό πλήθος κενών πριν από τον πρώτο μη-κενό χαρακτήρα καθορίζει την εσοχή της γραμμής. Η εσοχή δεν μπορεί να «σπάσει» σε περισσότερες φυσικές γραμμές με χρήση ανάστροφων καθέτων· οι κενοί χαρακτήρες μέχρι την πρώτη ανάστροφη κάθετο καθορίζουν την εσοχή.

Η εσοχή απορρίπτεται ως ασυνεπής αν ένα αρχείο πηγαίου κώδικα αναμειγνύει tabs και κενά με τρόπο που κάνει το νόημα να εξαρτάται από το πόσα κενά αντιστοιχούν σε ένα tab· σε αυτή την περίπτωση γίνεται raise ένα @ref{950,,TabError}.

`Σημείωση συμβατότητας μεταξύ πλατφορμών:' λόγω της φύσης των επεξεργαστών κειμένου σε μη-UNIX πλατφόρμες, δεν είναι συνετό να χρησιμοποιείται μίξη κενών και tabs για την εσοχή μέσα στο ίδιο αρχείο πηγαίου κώδικα. Θα πρέπει επίσης να σημειωθεί ότι διαφορετικές πλατφόρμες ενδέχεται να περιορίζουν ρητά το μέγιστο επίπεδο εσοχής.

Ένας χαρακτήρας νέας γραμμής μπορεί να υπάρχει στην αρχή της γραμμής· θα αγνοηθεί για τους παραπάνω υπολογισμούς εσοχής. Χαρακτήρες νέας γραμμής που εμφανίζονται αλλού μέσα στους αρχικούς κενούς χαρακτήρες έχουν απροσδιόριστη επίδραση (για παράδειγμα, μπορεί να μηδενίσουν την καταμέτρηση κενών).

@geindex token INDENT
@geindex token DEDENT

Τα επίπεδα εσοχής διαδοχικών γραμμών χρησιμοποιούνται για τη δημιουργία των tokens @ref{22ec,,INDENT} και @ref{24a3,,DEDENT}, χρησιμοποιώντας μια στοίβα, ως εξής.

Πριν διαβαστεί η πρώτη γραμμή του αρχείου, ένα μοναδικό μηδενικό ωθείται στη στοίβα· αυτό δεν θα αφαιρεθεί ποτέ. Οι αριθμοί που ωθούνται στη στοίβα θα είναι πάντα αυστηρά αυξανόμενοι από κάτω προς τα πάνω. Στην αρχή κάθε λογικής γραμμής, το επίπεδο εσοχής της γραμμής συγκρίνεται με την κορυφή της στοίβας. Αν είναι ίσο, δεν συμβαίνει τίποτα. Αν είναι μεγαλύτερο, ωθείται στη στοίβα και παράγεται ένα token @code{INDENT}. Αν είναι μικρότερο, `πρέπει' να είναι ένας από τους αριθμούς που υπάρχουν στη στοίβα· όλοι οι μεγαλύτεροι αριθμοί αφαιρούνται (pop) και για κάθε αριθμό που αφαιρείται παράγεται ένα token @code{DEDENT}. Στο τέλος του αρχείου, παράγεται ένα token @code{DEDENT} για κάθε αριθμό που απομένει στη στοίβα και είναι μεγαλύτερος από το μηδέν.

Ακολουθεί ένα παράδειγμα (αν και μπερδεμένο) κώδικα Python με σωστή εσοχή:

@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

Το παρακάτω παράδειγμα δείχνει διάφορα σφάλματα εσοχής:

@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

(Στην πραγματικότητα, τα τρία πρώτα σφάλματα εντοπίζονται από τον parser· μόνο το τελευταίο σφάλμα εντοπίζεται από τον λεξικό αναλυτή — η εσοχή του @code{return r} δεν ταιριάζει με επίπεδο που αφαιρέθηκε από τη στοίβα.)

@node Κενοί χαρακτήρες μεταξύ των tokens,Δείκτης τέλους,Εσοχή,Δομή γραμμών
@anchor{reference/lexical_analysis whitespace}@anchor{2484}@anchor{reference/lexical_analysis whitespace-between-tokens}@anchor{24a4}
@subsubsection Κενοί χαρακτήρες μεταξύ των tokens


Except at the beginning of a logical line or in string literals, the whitespace
characters space, tab and formfeed can be used interchangeably to separate
tokens:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-whitespace}@anchor{24a5}whitespace:  ' ' | tab | formfeed
@end example

Whitespace is needed between two tokens only if their concatenation
could otherwise be interpreted as a different token. For example, @code{ab} is one
token, but @code{a b} is two tokens. However, @code{+a} and @code{+ a} both produce
two tokens, @code{+} and @code{a}, as @code{+a} is not a valid token.

@node Δείκτης τέλους,,Κενοί χαρακτήρες μεταξύ των tokens,Δομή γραμμών
@anchor{reference/lexical_analysis end-marker}@anchor{24a6}@anchor{reference/lexical_analysis endmarker-token}@anchor{2493}
@subsubsection Δείκτης τέλους


Στο τέλος μη-διαδραστικής εισόδου, ο λεξικός αναλυτής παράγει ένα token @ref{24a7,,ENDMARKER}.

@node Άλλα tokens,Ονόματα αναγνωριστικά και λέξεις-κλειδιά,Δομή γραμμών,Λεξική ανάλυση
@anchor{reference/lexical_analysis id8}@anchor{24a8}@anchor{reference/lexical_analysis other-tokens}@anchor{24a9}
@subsection Άλλα tokens


Εκτός από τα @ref{2485,,NEWLINE}, @ref{22ec,,INDENT} και @ref{24a3,,DEDENT}, υπάρχουν και οι εξής κατηγορίες tokens: `αναγνωριστικά' και `λέξεις-κλειδιά' (@ref{24aa,,NAME}), `λεκτικά' (όπως @ref{24ab,,NUMBER} και @ref{24ac,,STRING}) και άλλα σύμβολα (`τελεστές' και `οριοθέτες', @ref{247b,,OP}). Οι κενοί χαρακτήρες (εκτός από τους τερματιστές λογικής γραμμής που συζητήθηκαν νωρίτερα) δεν είναι tokens, αλλά χρησιμεύουν για τον διαχωρισμό των tokens. Όπου υπάρχει ασάφεια, ένα token αποτελείται από τη μεγαλύτερη δυνατή συμβολοσειρά που σχηματίζει έγκυρο token, όταν διαβάζεται από αριστερά προς τα δεξιά.

@node Ονόματα αναγνωριστικά και λέξεις-κλειδιά,Λεκτικά,Άλλα tokens,Λεξική ανάλυση
@anchor{reference/lexical_analysis identifiers}@anchor{2491}@anchor{reference/lexical_analysis names-identifiers-and-keywords}@anchor{24ad}
@subsection Ονόματα (αναγνωριστικά και λέξεις-κλειδιά)


@geindex αναγνωριστικό
@geindex όνομα

Τα tokens @ref{24aa,,NAME} αναπαριστούν `αναγνωριστικά', `λέξεις-κλειδιά' και `ήπιες λέξεις-κλειδιά'.

Τα ονόματα αποτελούνται από τους παρακάτω χαρακτήρες:


@itemize *

@item 
κεφαλαία και πεζά γράμματα (@code{A-Z} και @code{a-z}),

@item 
την κάτω παύλα (@code{_}),

@item 
ψηφία (@code{0} έως @code{9}), που δεν μπορούν να εμφανιστούν ως πρώτος χαρακτήρας, και

@item 
μη-ASCII χαρακτήρες. Έγκυρα ονόματα μπορούν να περιέχουν μόνο χαρακτήρες «γραμμάτων” και «ψηφίων”· δείτε @ref{24ae,,Μη-ASCII χαρακτήρες στα ονόματα} για λεπτομέρειες.
@end itemize

Τα ονόματα πρέπει να περιέχουν τουλάχιστον έναν χαρακτήρα, αλλά δεν έχουν ανώτατο όριο μήκους. Τα κεφαλαία/πεζά έχουν σημασία.

Τυπικά, τα ονόματα περιγράφονται από τους παρακάτω λεξικούς ορισμούς:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-NAME}@anchor{24af}NAME:          @ref{24b0,,name_start} @ref{24b1,,name_continue}*
@anchor{reference/lexical_analysis grammar-token-python-grammar-name_start}@anchor{24b0}name_start:    "a"..."z" | "A"..."Z" | "_" | <non-ASCII character>
@anchor{reference/lexical_analysis grammar-token-python-grammar-name_continue}@anchor{24b1}name_continue: name_start | "0"..."9"
@anchor{reference/lexical_analysis grammar-token-python-grammar-identifier}@anchor{24b2}identifier:    <@ref{24af,,NAME}, except keywords>
@end example

Σημειώστε ότι δεν είναι έγκυρα όλα τα ονόματα που ταιριάζουν σε αυτή τη γραμματική· δείτε @ref{24ae,,Μη-ASCII χαρακτήρες στα ονόματα} για λεπτομέρειες.

@menu
* Λέξεις-κλειδιά:: 
* Ήπιες λέξεις-κλειδιά:: 
* Δεσμευμένες κλάσεις αναγνωριστικών:: 
* Μη-ASCII χαρακτήρες στα ονόματα:: 

@end menu

@node Λέξεις-κλειδιά,Ήπιες λέξεις-κλειδιά,,Ονόματα αναγνωριστικά και λέξεις-κλειδιά
@anchor{reference/lexical_analysis id9}@anchor{24b3}@anchor{reference/lexical_analysis keywords}@anchor{247a}
@subsubsection Λέξεις-κλειδιά


@geindex λέξη-κλειδί
@geindex δεσμευμένη λέξη

Τα παρακάτω ονόματα χρησιμοποιούνται ως δεσμευμένες λέξεις, ή `λέξεις-κλειδιά' της γλώσσας, και δεν μπορούν να χρησιμοποιηθούν ως κοινά αναγνωριστικά. Πρέπει να γράφονται ακριβώς όπως εμφανίζονται εδώ:

@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 Ήπιες λέξεις-κλειδιά,Δεσμευμένες κλάσεις αναγνωριστικών,Λέξεις-κλειδιά,Ονόματα αναγνωριστικά και λέξεις-κλειδιά
@anchor{reference/lexical_analysis id10}@anchor{24b4}@anchor{reference/lexical_analysis soft-keywords}@anchor{be6}
@subsubsection Ήπιες λέξεις-κλειδιά


@geindex ήπια λέξη-κλειδί
@geindex λέξη-κλειδί


Added in version 3.10.


Κάποια ονόματα είναι δεσμευμένα μόνο σε συγκεκριμένα συμφραζόμενα. Αυτά είναι γνωστά ως `ήπιες λέξεις-κλειδιά':


@itemize -

@item 
@code{match}, @code{case} και @code{_}, όταν χρησιμοποιούνται στην εντολή @ref{1d4,,match}.

@item 
@code{type}, όταν χρησιμοποιείται στην εντολή @ref{85a,,type}.

@item 
@code{lazy}, when used before an @ref{9da,,import} statement.
@end itemize

Αυτά λειτουργούν συντακτικά ως λέξεις-κλειδιά στα συγκεκριμένα συμφραζόμενά τους, αλλά αυτή η διάκριση γίνεται στο επίπεδο του parser, όχι κατά το tokenizing.

Ως ήπιες λέξεις-κλειδιά, η χρήση τους στη γραμματική είναι δυνατή, ενώ ταυτόχρονα διατηρείται η συμβατότητα με υπάρχον κώδικα που χρησιμοποιεί αυτά τα ονόματα ως ονόματα αναγνωριστικών.


Άλλαξε στην έκδοση 3.12: Το @code{type} είναι πλέον ήπια λέξη-κλειδί.



Άλλαξε στην έκδοση 3.15: @code{lazy} is now a soft keyword.


@geindex _@comma{} αναγνωριστικά
@geindex __@comma{} αναγνωριστικά

@node Δεσμευμένες κλάσεις αναγνωριστικών,Μη-ASCII χαρακτήρες στα ονόματα,Ήπιες λέξεις-κλειδιά,Ονόματα αναγνωριστικά και λέξεις-κλειδιά
@anchor{reference/lexical_analysis id-classes}@anchor{24b5}@anchor{reference/lexical_analysis reserved-classes-of-identifiers}@anchor{24b6}
@subsubsection Δεσμευμένες κλάσεις αναγνωριστικών


Ορισμένες κλάσεις αναγνωριστικών (πέρα από τις λέξεις-κλειδιά) έχουν ειδικές σημασίες. Αυτές οι κλάσεις αναγνωρίζονται από τα μοτίβα κάτω παύλων στην αρχή και/ή στο τέλος:


@table @asis

@item @code{_*}

Δεν εισάγεται με @code{from module import *}.

@item @code{_}

Σε ένα μοτίβο @code{case} μέσα σε εντολή @ref{1d4,,match}, το @code{_} είναι @ref{be6,,ήπια λέξη-κλειδί} που δηλώνει ένα @ref{be7,,μπαλαντέρ}.

Ανεξάρτητα από αυτό, ο διαδραστικός διερμηνέας κάνει διαθέσιμο το αποτέλεσμα της τελευταίας αξιολόγησης στη μεταβλητή @code{_}. (Αποθηκεύεται στο module @ref{13,,builtins}, δίπλα σε ενσωματωμένες συναρτήσεις όπως το @code{print}.)

Αλλού, το @code{_} είναι ένα κανονικό αναγνωριστικό. Συχνά χρησιμοποιείται για να ονομάζει «ειδικά» αντικείμενα, αλλά δεν είναι ιδιαίτερο για την ίδια την Python.

@cartouche
@quotation Σημείωση 
Το όνομα @code{_} χρησιμοποιείται συχνά σε συνδυασμό με διεθνοποίηση· ανατρέξτε στην τεκμηρίωση του module @ref{66,,gettext} για περισσότερες πληροφορίες σχετικά με αυτή τη σύμβαση.

Χρησιμοποιείται επίσης συχνά για αχρησιμοποίητες μεταβλητές.
@end quotation
@end cartouche

@item @code{__*__}

Ονόματα ορισμένα από το σύστημα, ατύπως γνωστά ως ονόματα «dunder». Αυτά τα ονόματα ορίζονται από τον διερμηνέα και την υλοποίησή του (συμπεριλαμβανομένης της τυπικής βιβλιοθήκης). Τα τρέχοντα ονόματα συστήματος συζητούνται στην ενότητα @ref{102c,,Ειδικά ονόματα μεθόδων} και αλλού. Πιθανότατα θα οριστούν περισσότερα σε μελλοντικές εκδόσεις της Python. `Κάθε' χρήση ονομάτων @code{__*__}, σε οποιοδήποτε πλαίσιο, που δεν ακολουθεί ρητά τεκμηριωμένη χρήση, είναι πιθανό να «σπάσει» χωρίς προειδοποίηση.

@item @code{__*}

Ιδιωτικά ονόματα σε κλάση. Τα ονόματα αυτής της κατηγορίας, όταν χρησιμοποιούνται μέσα στο πλαίσιο ενός ορισμού κλάσης, ξαναγράφονται σε «παραμορφωμένη» (mangled) μορφή ώστε να αποφεύγονται συγκρούσεις ονομάτων μεταξύ «ιδιωτικών» γνωρισμάτων βασικών και παραγόμενων κλάσεων. Δείτε την ενότητα @ref{24b7,,Identifiers (Names)}.
@end table

@node Μη-ASCII χαρακτήρες στα ονόματα,,Δεσμευμένες κλάσεις αναγνωριστικών,Ονόματα αναγνωριστικά και λέξεις-κλειδιά
@anchor{reference/lexical_analysis lexical-names-nonascii}@anchor{24ae}@anchor{reference/lexical_analysis non-ascii-characters-in-names}@anchor{24b8}
@subsubsection Μη-ASCII χαρακτήρες στα ονόματα


Ονόματα που περιέχουν μη-ASCII χαρακτήρες χρειάζονται πρόσθετη κανονικοποίηση και επικύρωση πέρα από τους κανόνες και τη γραμματική που εξηγούνται @ref{2491,,παραπάνω}. Για παράδειγμα, τα @code{ř_1}, @code{蛇} ή @code{साँप} είναι έγκυρα ονόματα, αλλά τα @code{r〰2}, @code{€} ή @code{🐍} δεν είναι.

Αυτή η ενότητα εξηγεί τους ακριβείς κανόνες.

Όλα τα ονόματα μετατρέπονται στη normalization form@footnote{https://www.unicode.org/reports/tr15/#Norm_Forms} NFKC κατά την ανάλυση. Αυτό σημαίνει ότι, για παράδειγμα, ορισμένες τυπογραφικές παραλλαγές χαρακτήρων μετατρέπονται στη «βασική» τους μορφή. Για παράδειγμα, το @code{ﬁⁿₐˡᵢᶻₐᵗᵢᵒₙ} κανονικοποιείται σε @code{finalization}, οπότε η Python τα αντιμετωπίζει ως το ίδιο όνομα:

@example
>>> ﬁⁿₐˡᵢᶻₐᵗᵢᵒₙ = 3
>>> finalization
3
@end example

@cartouche
@quotation Σημείωση 
Η κανονικοποίηση γίνεται μόνο στο λεξικό επίπεδο. Συναρτήσεις χρόνου εκτέλεσης που δέχονται ονόματα ως `strings' γενικά δεν κανονικοποιούν τα ορίσματά τους. Για παράδειγμα, η μεταβλητή που ορίστηκε παραπάνω είναι προσβάσιμη κατά την εκτέλεση στο λεξικό @ref{1e01,,globals()} ως @code{globals()["finalization"]} αλλά όχι ως @code{globals()["ﬁⁿₐˡᵢᶻₐᵗᵢᵒₙ"]}.
@end quotation
@end cartouche

Όπως ακριβώς τα ονόματα που αποτελούνται μόνο από ASCII πρέπει να περιέχουν μόνο γράμματα, ψηφία και κάτω παύλα και δεν μπορούν να ξεκινούν με ψηφίο, έτσι και ένα έγκυρο όνομα πρέπει να ξεκινά με χαρακτήρα από το σύνολο`@w{`}xid_start`@w{`} τύπου γραμμάτων, και οι υπόλοιποι χαρακτήρες πρέπει να ανήκουν στο σύνολο @code{xid_continue} τύπου γραμμάτων και ψηφίων.

These sets are based on the `XID_Start' and `XID_Continue' sets as defined by the
Unicode standard annex UAX-31@footnote{https://www.unicode.org/reports/tr31/}.
Python’s @code{xid_start} additionally includes the underscore (@code{_}).
Note that Python does not necessarily conform to UAX-31@footnote{https://www.unicode.org/reports/tr31/}.

Μια μη-κανονιστική λίστα χαρακτήρων των συνόλων `XID_Start' και `XID_Continue' όπως ορίζονται από το Unicode είναι διαθέσιμη στο αρχείο DerivedCoreProperties.txt@footnote{https://www.unicode.org/Public/17.0.0/ucd/DerivedCoreProperties.txt} της Unicode Character Database. Για αναφορά, οι κανόνες κατασκευής για τα σύνολα @code{xid_*} δίνονται παρακάτω.

Το σύνολο @code{id_start} ορίζεται ως η ένωση των:


@itemize *

@item 
Κατηγορία Unicode @code{<Lu>} - κεφαλαία γράμματα (περιλαμβάνει @code{A} έως @code{Z})

@item 
Κατηγορία Unicode @code{<Ll>} - πεζά γράμματα (περιλαμβάνει @code{a} έως @code{z})

@item 
Κατηγορία Unicode @code{<Lt>} - γράμματα τύπου titlecase

@item 
Κατηγορία Unicode @code{<Lm>} - τροποποιητικά γράμματα

@item 
Κατηγορία Unicode @code{<Lo>} - άλλα γράμματα

@item 
Κατηγορία Unicode @code{<Nl>} - αριθμοί-γράμματα

@item 
@{@code{"_"}@} - η κάτω παύλα

@item 
@code{<Other_ID_Start>} - ένα ρητό σύνολο χαρακτήρων στο PropList.txt@footnote{https://www.unicode.org/Public/17.0.0/ucd/PropList.txt} για να υποστηρίζεται η συμβατότητα προς τα πίσω
@end itemize

Το σύνολο @code{xid_start} κατόπιν «κλείνει» αυτό το σύνολο υπό κανονικοποίηση NFKC, αφαιρώντας όλους τους χαρακτήρες των οποίων η κανονικοποίηση δεν είναι της μορφής @code{id_start id_continue*}.

Το σύνολο @code{id_continue} ορίζεται ως η ένωση των:


@itemize *

@item 
@code{id_start} (βλ. παραπάνω)

@item 
Κατηγορία Unicode @code{<Nd>} - δεκαδικοί αριθμοί (περιλαμβάνει @code{0} έως @code{9})

@item 
Κατηγορία Unicode @code{<Pc>} - σημεία στίξης σύνδεσης

@item 
Κατηγορία Unicode @code{<Mn>} - nonspacing marks

@item 
Κατηγορία Unicode @code{<Mc>} - συνδυαστικά σημάδια με απόσταση

@item 
@code{<Other_ID_Continue>} - ένα ακόμη ρητό σύνολο χαρακτήρων στο PropList.txt@footnote{https://www.unicode.org/Public/17.0.0/ucd/PropList.txt} για να υποστηρίζεται η συμβατότητα προς τα πίσω
@end itemize

Και πάλι, το @code{xid_continue} «κλείνει» αυτό το σύνολο υπό κανονικοποίηση NFKC.

Οι κατηγορίες Unicode χρησιμοποιούν την έκδοση της Unicode Character Database όπως περιλαμβάνεται στο module @ref{10e,,unicodedata}.


@subsubheading Δείτε επίσης



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 3131
PEP 3131@footnote{https://peps.python.org/pep-3131/} – Υποστήριξη μη-ASCII αναγνωριστικών

@item 
@geindex Python Enhancement Proposals; PEP 672
PEP 672@footnote{https://peps.python.org/pep-0672/} – Ζητήματα ασφάλειας σχετικά με το Unicode στην Python
@end itemize


@node Λεκτικά,Λεκτικά συμβολοσειράς και Bytes,Ονόματα αναγνωριστικά και λέξεις-κλειδιά,Λεξική ανάλυση
@anchor{reference/lexical_analysis id11}@anchor{24b9}@anchor{reference/lexical_analysis literals}@anchor{24ba}
@subsection Λεκτικά


@geindex λεκτικό
@geindex σταθερά

Τα λεκτικά είναι σημειογραφίες για σταθερές τιμές ορισμένων ενσωματωμένων τύπων.

Όσον αφορά τη λεξική ανάλυση, η Python έχει λεκτικά @ref{2490,,συμβολοσειράς@comma{} bytes} και @ref{2492,,αριθμητικά}.

Άλλα «λεκτικά» δηλώνονται λεξικά μέσω @ref{247a,,λέξεων-κλειδιών} (@code{None}, @code{True}, @code{False}) και του ειδικού @ref{24bb,,token έλλειψης} (@code{...}).

@geindex λεκτικό συμβολοσειράς
@geindex λεκτικό bytes
@geindex ASCII
@geindex ' (μονό εισαγωγικό);λεκτικό συμβολοσειράς
@geindex " (διπλό εισαγωγικό);λεκτικό συμβολοσειράς

@node Λεκτικά συμβολοσειράς και Bytes,Αριθμητικά λεκτικά,Λεκτικά,Λεξική ανάλυση
@anchor{reference/lexical_analysis string-and-bytes-literals}@anchor{24bc}@anchor{reference/lexical_analysis strings}@anchor{2490}
@subsection Λεκτικά συμβολοσειράς και Bytes


Τα λεκτικά συμβολοσειράς είναι κείμενο μέσα σε μονά εισαγωγικά (@code{'}) ή διπλά εισαγωγικά (@code{"}). Για παράδειγμα:

@example
"spam"
'eggs'
@end example

Το εισαγωγικό που χρησιμοποιείται για να ξεκινήσει το λεκτικό το τερματίζει, οπότε ένα λεκτικό συμβολοσειράς μπορεί να περιέχει μόνο το άλλο είδος εισαγωγικού (εκτός αν χρησιμοποιηθούν ακολουθίες διαφυγής, βλ. παρακάτω). Για παράδειγμα:

@example
'Say "Hello", please.'
"Don't do that!"
@end example

Πέρα από αυτόν τον περιορισμό, η επιλογή εισαγωγικού (@code{'} ή @code{"}) δεν επηρεάζει το πώς αναλύεται το λεκτικό.

Μέσα σε ένα λεκτικό συμβολοσειράς, ο χαρακτήρας ανάστροφης καθέτου (@code{\}) εισάγει μια `ακολουθία διαφυγής', η οποία έχει ειδική σημασία ανάλογα με τον χαρακτήρα που ακολουθεί την ανάστροφη κάθετο. Για παράδειγμα, το @code{\"} δηλώνει τον χαρακτήρα διπλού εισαγωγικού και `δεν' τερματίζει τη συμβολοσειρά:

@example
>>> print("Say \"Hello\" to everyone!")
Say "Hello" to everyone!
@end example

Δείτε παρακάτω τις @ref{874,,ακολουθίες διαφυγής} για την πλήρη λίστα τέτοιων ακολουθιών και περισσότερες λεπτομέρειες.

@geindex συμβολοσειρά τριπλού εισαγωγικού
@geindex """;λεκτικό συμβολοσειράς
@geindex '@w{'}';λεκτικό συμβολοσειράς

@menu
* Συμβολοσειρές τριπλού εισαγωγικού:: 
* Προθέματα συμβολοσειράς:: 
* Τυπική γραμματική:: 
* Ακολουθίες διαφυγής:: 
* Λεκτικά bytes:: 
* Λεκτικά raw συμβολοσειράς:: 
* f-strings:: 
* t-strings:: 
* Formal grammar for f-strings:: 

@end menu

@node Συμβολοσειρές τριπλού εισαγωγικού,Προθέματα συμβολοσειράς,,Λεκτικά συμβολοσειράς και Bytes
@anchor{reference/lexical_analysis triple-quoted-strings}@anchor{24bd}
@subsubsection Συμβολοσειρές τριπλού εισαγωγικού


Οι συμβολοσειρές μπορούν επίσης να περικλείονται σε αντίστοιχες ομάδες τριών μονών ή τριών διπλών εισαγωγικών. Αυτές συνήθως αναφέρονται ως `triple-quoted strings':

@example
"""This is a triple-quoted string."""
@end example

Σε λεκτικά τριπλών εισαγωγικών, επιτρέπονται (και διατηρούνται) εισαγωγικά χωρίς διαφυγή, με εξαίρεση ότι τρία εισαγωγικά χωρίς διαφυγή στη σειρά τερματίζουν το λεκτικό, αν είναι του ίδιου είδους (@code{'} ή @code{"}) με αυτό που χρησιμοποιήθηκε στην αρχή:

@example
"""This string has "quotes" inside."""
@end example

Επιτρέπονται επίσης (και διατηρούνται) νέες γραμμές χωρίς διαφυγή:

@example
'@w{'}'This triple-quoted string
continues on the next line.'@w{'}'
@end example

@geindex u';λεκτικό συμβολοσειράς
@geindex u";λεκτικό συμβολοσειράς

@node Προθέματα συμβολοσειράς,Τυπική γραμματική,Συμβολοσειρές τριπλού εισαγωγικού,Λεκτικά συμβολοσειράς και Bytes
@anchor{reference/lexical_analysis string-prefixes}@anchor{24be}
@subsubsection Προθέματα συμβολοσειράς


Τα λεκτικά συμβολοσειράς μπορούν να έχουν ένα προαιρετικό `prefix' που επηρεάζει το πώς αναλύεται το περιεχόμενο του λεκτικού, για παράδειγμα:

@example
b"data"
f'@{result=@}'
@end example

Τα επιτρεπόμενα προθέματα είναι:


@itemize *

@item 
@code{b}: @ref{24bf,,Λεκτικό bytes}

@item 
@code{r}: @ref{24c0,,Ακατέργαστη συμβολοσειρά (raw string)}

@item 
@code{f}: @ref{43a,,Λεκτικό μορφοποιημένης συμβολοσειράς} («f-string»)

@item 
@code{t}: @ref{1a50,,Λεκτικό συμβολοσειράς προτύπου} («t-string»)

@item 
@code{u}: Καμία επίδραση (επιτρέπεται για συμβατότητα προς τα πίσω)
@end itemize

Δείτε τις αντίστοιχες ενότητες για λεπτομέρειες σχετικά με κάθε τύπο.

Τα προθέματα δεν κάνουν διάκριση κεφαλαίων/πεζών (για παράδειγμα, το “@code{B}” λειτουργεί όπως το “@code{b}”). Το πρόθεμα “@code{r}” μπορεί να συνδυαστεί με “@code{f}”, “@code{t}” ή “@code{b}”, οπότε και τα “@code{fr}”, “@code{rf}”, “@code{tr}”, “@code{rt}”, “@code{br}” και “@code{rb}” είναι επίσης έγκυρα προθέματα.


Added in version 3.3: Το πρόθεμα @code{'rb'} για raw bytes λεκτικά έχει προστεθεί ως συνώνυμο του @code{'br'}.

Η υποστήριξη για το παλιό unicode λεκτικό (@code{u'value'}) επανεισήχθη για να απλοποιηθεί η συντήρηση κωδικών βάσεων που υποστηρίζουν ταυτόχρονα Python 2.x και 3.x. Δείτε το 
@geindex Python Enhancement Proposals; PEP 414
PEP 414@footnote{https://peps.python.org/pep-0414/} για περισσότερες πληροφορίες.


@node Τυπική γραμματική,Ακολουθίες διαφυγής,Προθέματα συμβολοσειράς,Λεκτικά συμβολοσειράς και Bytes
@anchor{reference/lexical_analysis formal-grammar}@anchor{24c1}
@subsubsection Τυπική γραμματική


Τα λεκτικά συμβολοσειράς, εκτός από τα @ref{43a,,«f-strings»} και @ref{1a50,,«t-strings»}, περιγράφονται από τους παρακάτω λεξικούς ορισμούς.

Αυτοί οι ορισμοί χρησιμοποιούν @ref{247f,,αρνητικά lookaheads} (@code{!}) για να υποδείξουν ότι ένα τελικό εισαγωγικό τερματίζει το λεκτικό.

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-STRING}@anchor{24c2}STRING:          [@ref{24c3,,stringprefix}] (@ref{24c4,,stringcontent})
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringprefix}@anchor{24c3}stringprefix:    <("r" | "u" | "b" | "br" | "rb"), case-insensitive>
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringcontent}@anchor{24c4}stringcontent:
   | "'@w{'}'" ( !"'@w{'}'" @ref{24c5,,longstringitem})* "'@w{'}'"
   | '"""' ( !'"""' @ref{24c5,,longstringitem})* '"""'
   | "'" ( !"'" @ref{24c6,,stringitem})* "'"
   | '"' ( !'"' @ref{24c6,,stringitem})* '"'
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringitem}@anchor{24c6}stringitem:      @ref{24c7,,stringchar} | @ref{24c8,,stringescapeseq}
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringchar}@anchor{24c7}stringchar:      <any @ref{249d,,source_character}, except backslash and newline>
@anchor{reference/lexical_analysis grammar-token-python-grammar-longstringitem}@anchor{24c5}longstringitem:  @ref{24c6,,stringitem} | newline
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringescapeseq}@anchor{24c8}stringescapeseq: "\" <any @ref{249d,,source_character}>
@end example

Σημειώστε ότι, όπως σε όλους τους λεξικούς ορισμούς, οι κενοί χαρακτήρες έχουν σημασία. Συγκεκριμένα, το πρόθεμα (αν υπάρχει) πρέπει να ακολουθείται αμέσως από το αρχικό εισαγωγικό.

@geindex φυσική γραμμή
@geindex ακολουθία διαφυγής
@geindex Standard C
@geindex C
@geindex \ (ανάστροφη κάθετος);ακολουθία διαφυγής
@geindex \\;ακολουθία διαφυγής
@geindex \a;ακολουθία διαφυγής
@geindex \b;ακολουθία διαφυγής
@geindex \f;ακολουθία διαφυγής
@geindex \n;ακολουθία διαφυγής
@geindex \r;ακολουθία διαφυγής
@geindex \t;ακολουθία διαφυγής
@geindex \v;ακολουθία διαφυγής
@geindex \x;ακολουθία διαφυγής
@geindex \N;ακολουθία διαφυγής
@geindex \u;ακολουθία διαφυγής
@geindex \U;ακολουθία διαφυγής

@node Ακολουθίες διαφυγής,Λεκτικά bytes,Τυπική γραμματική,Λεκτικά συμβολοσειράς και Bytes
@anchor{reference/lexical_analysis escape-sequences}@anchor{874}@anchor{reference/lexical_analysis id12}@anchor{24c9}
@subsubsection Ακολουθίες διαφυγής


Εκτός αν υπάρχει πρόθεμα “@code{r}” ή “@code{R}”, οι ακολουθίες διαφυγής σε λεκτικά συμβολοσειράς και bytes ερμηνεύονται με κανόνες παρόμοιους με αυτούς της Standard C. Οι αναγνωριζόμενες ακολουθίες διαφυγής είναι:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Ακολουθία διαφυγής

@tab

Σημασία

@item

@code{\}<newline>

@tab

@ref{24ca,,Αγνοημένο τέλος γραμμής}

@item

@code{\\}

@tab

@ref{24cb,,Ανάστροφη κάθετος}

@item

@code{\'}

@tab

@ref{24cb,,Μονό εισαγωγικό}

@item

@code{\"}

@tab

@ref{24cb,,Διπλό εισαγωγικό}

@item

@code{\a}

@tab

ASCII Bell (BEL)

@item

@code{\b}

@tab

ASCII Backspace (BS)

@item

@code{\f}

@tab

ASCII Formfeed (FF)

@item

@code{\n}

@tab

ASCII Linefeed (LF)

@item

@code{\r}

@tab

ASCII Carriage Return (CR)

@item

@code{\t}

@tab

ASCII Horizontal Tab (TAB)

@item

@code{\v}

@tab

ASCII Vertical Tab (VT)

@item

@code{\@var{ooo}}

@tab

@ref{24cc,,Οκταδικός χαρακτήρας}

@item

@code{\x@var{hh}}

@tab

@ref{24cd,,Δεκαεξαδικός χαρακτήρας}

@item

@code{\N@{@var{name}@}}

@tab

@ref{24ce,,Ονοματισμένος χαρακτήρας Unicode}

@item

@code{\u@var{xxxx}}

@tab

@ref{24cf,,Δεκαεξαδικός χαρακτήρας Unicode}

@item

@code{\U@var{xxxxxxxx}}

@tab

@ref{24cf,,Δεκαεξαδικός χαρακτήρας Unicode}

@end multitable


@menu
* Αγνοημένο τέλος γραμμής:: 
* Χαρακτήρες με διαφυγή:: 
* Οκταδικός χαρακτήρας:: 
* Δεκαεξαδικός χαρακτήρας:: 
* Ονοματισμένος χαρακτήρας Unicode:: 
* Δεκαεξαδικοί χαρακτήρες Unicode:: 
* Μη αναγνωρισμένες ακολουθίες διαφυγής:: 

@end menu

@node Αγνοημένο τέλος γραμμής,Χαρακτήρες με διαφυγή,,Ακολουθίες διαφυγής
@anchor{reference/lexical_analysis ignored-end-of-line}@anchor{24d0}@anchor{reference/lexical_analysis string-escape-ignore}@anchor{24ca}
@subsubsection Αγνοημένο τέλος γραμμής


Μπορεί να προστεθεί ανάστροφη κάθετος στο τέλος μιας γραμμής για να αγνοηθεί η νέα γραμμή:

@example
>>> 'This string will not include \
... backslashes or newline characters.'
'This string will not include backslashes or newline characters.'
@end example

Το ίδιο αποτέλεσμα μπορεί να επιτευχθεί με @ref{2490,,συμβολοσειρές τριπλού εισαγωγικού}, ή με παρενθέσεις και @ref{24d1,,συνένωση λεκτικών συμβολοσειράς}.

@node Χαρακτήρες με διαφυγή,Οκταδικός χαρακτήρας,Αγνοημένο τέλος γραμμής,Ακολουθίες διαφυγής
@anchor{reference/lexical_analysis escaped-characters}@anchor{24d2}@anchor{reference/lexical_analysis string-escape-escaped-char}@anchor{24cb}
@subsubsection Χαρακτήρες με διαφυγή


Για να συμπεριληφθεί μια ανάστροφη κάθετος σε λεκτικό συμβολοσειράς Python που δεν είναι @ref{24c0,,raw}, πρέπει να διπλασιαστεί. Η ακολουθία διαφυγής @code{\\} δηλώνει έναν μοναδικό χαρακτήρα ανάστροφης καθέτου:

@example
>>> print('C:\\Program Files')
C:\Program Files
@end example

Αντίστοιχα, οι ακολουθίες @code{\'} και @code{\"} δηλώνουν τον χαρακτήρα μονών και διπλών εισαγωγικών, αντίστοιχα:

@example
>>> print('\' and \"')
' and "
@end example

@node Οκταδικός χαρακτήρας,Δεκαεξαδικός χαρακτήρας,Χαρακτήρες με διαφυγή,Ακολουθίες διαφυγής
@anchor{reference/lexical_analysis octal-character}@anchor{24d3}@anchor{reference/lexical_analysis string-escape-oct}@anchor{24cc}
@subsubsection Οκταδικός χαρακτήρας


Η ακολουθία @code{\@var{ooo}} δηλώνει έναν `χαρακτήρα' με οκταδική (βάση 8) τιμή `ooo':

@example
>>> '\120'
'P'
@end example

Γίνονται δεκτά έως τρία οκταδικά ψηφία (0 έως 7).

Σε λεκτικό bytes, `χαρακτήρας' σημαίνει ένα `byte' με τη δεδομένη τιμή. Σε λεκτικό συμβολοσειράς, σημαίνει χαρακτήρας Unicode με τη δεδομένη τιμή.


Άλλαξε στην έκδοση 3.11: Οκταδικές διαφυγές με τιμή μεγαλύτερη από @code{0o377} (255) παράγουν ένα @ref{2c9,,DeprecationWarning}.



Άλλαξε στην έκδοση 3.12: Οκταδικές διαφυγές με τιμή μεγαλύτερη από @code{0o377} (255) παράγουν ένα @ref{44a,,SyntaxWarning}. Σε μελλοντική έκδοση της Python θα κάνουν raise @ref{17e,,SyntaxError}.


@node Δεκαεξαδικός χαρακτήρας,Ονοματισμένος χαρακτήρας Unicode,Οκταδικός χαρακτήρας,Ακολουθίες διαφυγής
@anchor{reference/lexical_analysis hexadecimal-character}@anchor{24d4}@anchor{reference/lexical_analysis string-escape-hex}@anchor{24cd}
@subsubsection Δεκαεξαδικός χαρακτήρας


Η ακολουθία @code{\x@var{hh}} δηλώνει έναν `χαρακτήρα' με δεκαεξαδική (βάση 16) τιμή `hh':

@example
>>> '\x50'
'P'
@end example

Σε αντίθεση με την Standard C, απαιτούνται ακριβώς δύο δεκαεξαδικά ψηφία.

Σε λεκτικό bytes, `χαρακτήρας' σημαίνει ένα `byte' με τη δεδομένη τιμή. Σε λεκτικό συμβολοσειράς, σημαίνει χαρακτήρας Unicode με τη δεδομένη τιμή.

@node Ονοματισμένος χαρακτήρας Unicode,Δεκαεξαδικοί χαρακτήρες Unicode,Δεκαεξαδικός χαρακτήρας,Ακολουθίες διαφυγής
@anchor{reference/lexical_analysis named-unicode-character}@anchor{24d5}@anchor{reference/lexical_analysis string-escape-named}@anchor{24ce}
@subsubsection Ονοματισμένος χαρακτήρας Unicode


Η ακολουθία @code{\N@{@var{name}@}} δηλώνει έναν χαρακτήρα Unicode με το δοσμένο `όνομα':

@example
>>> '\N@{LATIN CAPITAL LETTER P@}'
'P'
>>> '\N@{SNAKE@}'
'🐍'
@end example

Αυτή η ακολουθία δεν μπορεί να εμφανιστεί σε @ref{24bf,,λεκτικά bytes}.


Άλλαξε στην έκδοση 3.3: Support for name aliases@footnote{https://www.unicode.org/Public/17.0.0/ucd/NameAliases.txt}
has been added.


@node Δεκαεξαδικοί χαρακτήρες Unicode,Μη αναγνωρισμένες ακολουθίες διαφυγής,Ονοματισμένος χαρακτήρας Unicode,Ακολουθίες διαφυγής
@anchor{reference/lexical_analysis hexadecimal-unicode-characters}@anchor{24d6}@anchor{reference/lexical_analysis string-escape-long-hex}@anchor{24cf}
@subsubsection Δεκαεξαδικοί χαρακτήρες Unicode


Οι ακολουθίες @code{\u@var{xxxx}} και @code{\U@var{xxxxxxxx}} δηλώνουν τον χαρακτήρα Unicode με τη δεδομένη δεκαεξαδική (βάση 16) τιμή. Απαιτούνται ακριβώς τέσσερα ψηφία για το @code{\u} και ακριβώς οκτώ ψηφία για το @code{\U}. Η δεύτερη μπορεί να κωδικοποιήσει οποιονδήποτε χαρακτήρα Unicode.

@example
>>> '\u1234'
'ሴ'
>>> '\U0001f40d'
'🐍'
@end example

Αυτές οι ακολουθίες δεν μπορούν να εμφανιστούν σε @ref{24bf,,λεκτικά bytes}.

@geindex μη αναγνωρισμένη ακολουθία διαφυγής

@node Μη αναγνωρισμένες ακολουθίες διαφυγής,,Δεκαεξαδικοί χαρακτήρες Unicode,Ακολουθίες διαφυγής
@anchor{reference/lexical_analysis unrecognized-escape-sequences}@anchor{24d7}
@subsubsection Μη αναγνωρισμένες ακολουθίες διαφυγής


Σε αντίθεση με την Standard C, όλες οι μη αναγνωρισμένες ακολουθίες διαφυγής αφήνονται αμετάβλητες στη συμβολοσειρά, δηλαδή `η ανάστροφη κάθετος παραμένει στο αποτέλεσμα':

@example
>>> print('\q')
\q
>>> list('\q')
['\\', 'q']
@end example

Σημειώστε ότι για λεκτικά bytes, οι ακολουθίες διαφυγής που αναγνωρίζονται μόνο σε λεκτικά συμβολοσειράς (@code{\N...}, @code{\u...}, @code{\U...}) εμπίπτουν στην κατηγορία των μη αναγνωρισμένων διαφυγών.


Άλλαξε στην έκδοση 3.6: Οι μη αναγνωρισμένες ακολουθίες διαφυγής παράγουν ένα @ref{2c9,,DeprecationWarning}.



Άλλαξε στην έκδοση 3.12: Οι μη αναγνωρισμένες ακολουθίες διαφυγής παράγουν ένα @ref{44a,,SyntaxWarning}. Σε μελλοντική έκδοση της Python θα κάνουν raise @ref{17e,,SyntaxError}.


@geindex b';λεκτικό bytes
@geindex b";λεκτικό bytes

@node Λεκτικά bytes,Λεκτικά raw συμβολοσειράς,Ακολουθίες διαφυγής,Λεκτικά συμβολοσειράς και Bytes
@anchor{reference/lexical_analysis bytes-literal}@anchor{24bf}@anchor{reference/lexical_analysis bytes-literals}@anchor{24d8}
@subsubsection Λεκτικά bytes


Τα `Bytes literals' έχουν πάντα πρόθεμα “@code{b}” ή “@code{B}”· παράγουν ένα αντικείμενο του τύπου @ref{1c7,,bytes} αντί του @ref{1df,,str}. Μπορούν να περιέχουν μόνο χαρακτήρες ASCII· bytes με αριθμητική τιμή 128 ή μεγαλύτερη πρέπει να εκφράζονται με ακολουθίες διαφυγής (συνήθως @ref{24cd,,Δεκαεξαδικός χαρακτήρας} ή @ref{24cc,,Οκταδικός χαρακτήρας}):

@example
>>> b'\x89PNG\r\n\x1a\n'
b'\x89PNG\r\n\x1a\n'
>>> list(b'\x89PNG\r\n\x1a\n')
[137, 80, 78, 71, 13, 10, 26, 10]
@end example

Αντίστοιχα, ένα μηδενικό byte πρέπει να εκφράζεται με ακολουθία διαφυγής (συνήθως @code{\0} ή @code{\x00}).

@geindex r';λεκτικό raw συμβολοσειράς
@geindex r";λεκτικό raw συμβολοσειράς

@node Λεκτικά raw συμβολοσειράς,f-strings,Λεκτικά bytes,Λεκτικά συμβολοσειράς και Bytes
@anchor{reference/lexical_analysis raw-string-literals}@anchor{24d9}@anchor{reference/lexical_analysis raw-strings}@anchor{24c0}
@subsubsection Λεκτικά raw συμβολοσειράς


Τόσο τα λεκτικά συμβολοσειράς όσο και τα λεκτικά bytes μπορούν προαιρετικά να έχουν πρόθεμα το γράμμα “@code{r}” ή “@code{R}”· τέτοιες κατασκευές ονομάζονται `raw string literals' και `raw bytes literals' αντίστοιχα και αντιμετωπίζουν τις ανάστροφες καθέτους ως χαρακτήρες. Ως αποτέλεσμα, στα λεκτικά raw συμβολοσειράς, οι @ref{874,,ακολουθίες διαφυγής} δεν αντιμετωπίζονται ειδικά:

@example
>>> r'\d@{4@}-\d@{2@}-\d@{2@}'
'\\d@{4@}-\\d@{2@}-\\d@{2@}'
@end example

Ακόμη και σε ένα raw λεκτικό, τα εισαγωγικά μπορούν να «ξεφύγουν» (escape) με ανάστροφη κάθετο, αλλά η ανάστροφη κάθετος παραμένει στο αποτέλεσμα· για παράδειγμα, το @code{r"\""} είναι έγκυρο λεκτικό συμβολοσειράς που αποτελείται από δύο χαρακτήρες: μια ανάστροφη κάθετο και ένα διπλό εισαγωγικό· το @code{r"\"} δεν είναι έγκυρο λεκτικό συμβολοσειράς (ακόμη και μια raw συμβολοσειρά δεν μπορεί να τελειώνει με περιττό αριθμό ανάστροφων καθέτων). Συγκεκριμένα, `ένα raw λεκτικό δεν μπορεί να τελειώνει με μία μόνο ανάστροφη κάθετο' (αφού η ανάστροφη κάθετος θα διέφευγε τον επόμενο χαρακτήρα εισαγωγικού). Σημειώστε επίσης ότι μια μοναδική ανάστροφη κάθετος ακολουθούμενη από νέα γραμμή ερμηνεύονται ως μέρος του λεκτικού, `όχι' ως συνέχιση γραμμής.

@geindex λεκτικό μορφοποιημένης συμβολοσειράς
@geindex λεκτικό παρεμβαλλόμενης (interpolated) συμβολοσειράς
@geindex συμβολοσειρά;μορφοποιημένο λεκτικό
@geindex συμβολοσειρά;παρεμβαλλόμενο (interpolated) λεκτικό
@geindex f-string
@geindex fstring
@geindex f';λεκτικό μορφοποιημένης συμβολοσειράς
@geindex f";λεκτικό μορφοποιημένης συμβολοσειράς
@geindex @{@} (άγκιστρα);σε λεκτικό μορφοποιημένης συμβολοσειράς
@geindex ! (θαυμαστικό);σε λεκτικό μορφοποιημένης συμβολοσειράς
@geindex ; (άνω-κάτω τελεία);σε λεκτικό μορφοποιημένης συμβολοσειράς
@geindex = (ίσον);για βοήθεια στο debugging με χρήση λεκτικών συμβολοσειράς
@anchor{reference/lexical_analysis f-strings}@anchor{43a}
@node f-strings,t-strings,Λεκτικά raw συμβολοσειράς,Λεκτικά συμβολοσειράς και Bytes
@anchor{reference/lexical_analysis formatted-string-literals}@anchor{24da}@anchor{reference/lexical_analysis id13}@anchor{24db}
@subsubsection f-strings



Added in version 3.6.



Άλλαξε στην έκδοση 3.7: The @ref{432,,await} and @ref{e70,,async for} can be used in expressions
within f-strings.



Άλλαξε στην έκδοση 3.8: Added the debug specifier (@code{=})



Άλλαξε στην έκδοση 3.12: Many restrictions on expressions within f-strings have been removed.
Notably, nested strings, comments, and backslashes are now permitted.


A `formatted string literal' or `f-string' is a string literal
that is prefixed with “@code{f}” or “@code{F}”.
Unlike other string literals, f-strings do not have a constant value.
They may contain `replacement fields' delimited by curly braces @code{@{@}}.
Replacement fields contain expressions which are evaluated at run time.
For example:

@example
>>> who = 'nobody'
>>> nationality = 'Spanish'
>>> f'@{who.title()@} expects the @{nationality@} Inquisition!'
'Nobody expects the Spanish Inquisition!'
@end example

Any doubled curly braces (@code{@{@{} or @code{@}@}}) outside replacement fields
are replaced with the corresponding single curly brace:

@example
>>> print(f'@{@{...@}@}')
@{...@}
@end example

Other characters outside replacement fields are treated like in ordinary
string literals.
This means that escape sequences are decoded (except when a literal is
also marked as a raw string), and newlines are possible in triple-quoted
f-strings:

@example
>>> name = 'Galahad'
>>> favorite_color = 'blue'
>>> print(f'@{name@}:\t@{favorite_color@}')
Galahad:       blue
>>> print(rf"C:\Users\@{name@}")
C:\Users\Galahad
>>> print(f'@w{'}'Three shall be the number of the counting
... and the number of the counting shall be three.'@w{'}')
Three shall be the number of the counting
and the number of the counting shall be three.
@end example

Expressions in formatted string literals are treated like regular
Python expressions.
Each expression is evaluated in the context where the formatted string literal
appears, in order from left to right.
An empty expression is not allowed, and both @ref{1642,,lambda} and
assignment expressions @code{:=} must be surrounded by explicit parentheses:

@example
>>> f'@{(half := 1/2)@}, @{half * 42@}'
'0.5, 21.0'
@end example

Επιτρέπεται να επαναχρησιμοποιείται ο τύπος εισαγωγικών του εξωτερικού f-string μέσα σε ένα πεδίο αντικατάστασης:

@example
>>> a = dict(x=2)
>>> f"abc @{a["x"]@} def"
'abc 2 def'
@end example

Επιτρέπονται επίσης ανάστροφες καθέτοι μέσα σε πεδία αντικατάστασης και αξιολογούνται με τον ίδιο τρόπο όπως σε οποιοδήποτε άλλο πλαίσιο:

@example
>>> a = ["a", "b", "c"]
>>> print(f"List a contains:\n@{"\n".join(a)@}")
List a contains:
a
b
c
@end example

It is possible to nest f-strings:

@example
>>> name = 'world'
>>> f'Repeated:@{f' hello @{name@}' * 3@}'
'Repeated: hello world hello world hello world'
@end example

Portable Python programs should not use more than 5 levels of nesting.

`Λεπτομέρεια υλοποίησης CPython:' CPython does not limit nesting of f-strings.

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).
This means that replacement fields with comments must be closed in a
different line:

@example
>>> a = 2
>>> f"abc@{a  # This comment  @}"  continues until the end of the line
...       + 3@}"
'abc5'
@end example

After the expression, replacement fields may optionally contain:


@itemize *

@item 
a `debug specifier' – an equal sign (@code{=}), optionally surrounded by
whitespace on one or both sides;

@item 
a `conversion specifier' – @code{!s}, @code{!r} or @code{!a}; and/or

@item 
a `format specifier' prefixed with a colon (@code{:}).
@end itemize

See the @ref{24dc,,Standard Library section on f-strings}
for details on how these fields are evaluated.

As that section explains, `format specifiers' are passed as the second argument
to the @ref{439,,format()} function to format a replacement field value.
For example, they can be used to specify a field width and padding characters
using the @ref{6fe,,Format Specification Mini-Language}:

@example
>>> number = 14.3
>>> f'@{number:20.7f@}'
'          14.3000000'
@end example

Top-level format specifiers may include nested replacement fields:

@example
>>> field_size = 20
>>> precision = 7
>>> f'@{number:@{field_size@}.@{precision@}f@}'
'          14.3000000'
@end example

These nested fields may include their own conversion fields and
@ref{6fe,,format specifiers}:

@example
>>> number = 3
>>> f'@{number:@{field_size@}@}'
'                   3'
>>> f'@{number:@{field_size:05@}@}'
'00000000000000000003'
@end example

However, these nested fields may not include more deeply nested replacement
fields.

Formatted string literals cannot be used as @ref{24dd,,docstrings},
even if they do not include expressions:

@example
>>> def foo():
...     f"Not a docstring"
...
>>> print(foo.__doc__)
None
@end example


@subsubheading Δείτε επίσης



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 498
PEP 498@footnote{https://peps.python.org/pep-0498/} – Literal String Interpolation

@item 
@geindex Python Enhancement Proposals; PEP 701
PEP 701@footnote{https://peps.python.org/pep-0701/} – Syntactic formalization of f-strings

@item 
@ref{a12,,str.format()}, which uses a related format string mechanism.
@end itemize

@anchor{reference/lexical_analysis t-strings}@anchor{1a50}
@node t-strings,Formal grammar for f-strings,f-strings,Λεκτικά συμβολοσειράς και Bytes
@anchor{reference/lexical_analysis id14}@anchor{24de}@anchor{reference/lexical_analysis template-string-literals}@anchor{24df}
@subsubsection t-strings



Added in version 3.14.


A `template string literal' or `t-string' is a string literal
that is prefixed with “@code{t}” or “@code{T}”.
These strings follow the same syntax rules as
@ref{43a,,formatted string literals}.
For differences in evaluation rules, see the
@ref{24e0,,Standard Library section on t-strings}

@node Formal grammar for f-strings,,t-strings,Λεκτικά συμβολοσειράς και Bytes
@anchor{reference/lexical_analysis formal-grammar-for-f-strings}@anchor{24e1}
@subsubsection Formal grammar for f-strings


F-strings are handled partly by the @ref{2483,,lexical analyzer}, which produces the
tokens @ref{24e2,,FSTRING_START}, @ref{24e3,,FSTRING_MIDDLE}
and @ref{24e4,,FSTRING_END}, and partly by the parser, which handles
expressions in the replacement field.
The exact way the work is split is a CPython implementation detail.

Correspondingly, the f-string grammar is a mix of
@ref{247e,,lexical and syntactic definitions}.

Whitespace is significant in these situations:


@itemize *

@item 
There may be no whitespace in @ref{24e2,,FSTRING_START} (between
the prefix and quote).

@item 
Whitespace in @ref{24e3,,FSTRING_MIDDLE} is part of the literal
string contents.

@item 
In @code{fstring_replacement_field}, if @code{f_debug_specifier} is present,
all whitespace after the opening brace until the @code{f_debug_specifier},
as well as whitespace immediately following @code{f_debug_specifier},
is retained as part of the expression.

`Λεπτομέρεια υλοποίησης CPython:' The expression is not handled in the tokenization phase; it is
retrieved from the source code using locations of the @code{@{} token
and the token after @code{=}.
@end itemize

The @code{FSTRING_MIDDLE} definition uses
@ref{247f,,negative lookaheads} (@code{!})
to indicate special characters (backslash, newline, @code{@{}, @code{@}}) and
sequences (@code{f_quote}).

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-fstring}@anchor{24e5}fstring:    @ref{24e6,,FSTRING_START} @ref{24e7,,fstring_middle}* @ref{24e8,,FSTRING_END}

@anchor{reference/lexical_analysis grammar-token-python-grammar-FSTRING_START}@anchor{24e6}FSTRING_START:      @ref{24e9,,fstringprefix} ("'" | '"' | "'@w{'}'" | '"""')
@anchor{reference/lexical_analysis grammar-token-python-grammar-FSTRING_END}@anchor{24e8}FSTRING_END:        @ref{24ea,,f_quote}
@anchor{reference/lexical_analysis grammar-token-python-grammar-fstringprefix}@anchor{24e9}fstringprefix:      <("f" | "fr" | "rf"), case-insensitive>
@anchor{reference/lexical_analysis grammar-token-python-grammar-f_debug_specifier}@anchor{24eb}f_debug_specifier:  '='
@anchor{reference/lexical_analysis grammar-token-python-grammar-f_quote}@anchor{24ea}f_quote:            <the quote character(s) used in FSTRING_START>

@anchor{reference/lexical_analysis grammar-token-python-grammar-fstring_middle}@anchor{24e7}fstring_middle:
   | @ref{24ec,,fstring_replacement_field}
   | @ref{24ed,,FSTRING_MIDDLE}
@anchor{reference/lexical_analysis grammar-token-python-grammar-FSTRING_MIDDLE}@anchor{24ed}FSTRING_MIDDLE:
   | (!"\" !@ref{249a,,newline} !'@{' !'@}' !@ref{24ea,,f_quote}) @ref{249d,,source_character}
   | @ref{24c8,,stringescapeseq}
   | "@{@{"
   | "@}@}"
   | <newline, in triple-quoted f-strings only>
@anchor{reference/lexical_analysis grammar-token-python-grammar-fstring_replacement_field}@anchor{24ec}fstring_replacement_field:
   | '@{' @ref{24ee,,f_expression} [@ref{24eb,,f_debug_specifier}] [@ref{24ef,,fstring_conversion}]
         [@ref{24f0,,fstring_full_format_spec}] '@}'
@anchor{reference/lexical_analysis grammar-token-python-grammar-fstring_conversion}@anchor{24ef}fstring_conversion:
   | "!" ("s" | "r" | "a")
@anchor{reference/lexical_analysis grammar-token-python-grammar-fstring_full_format_spec}@anchor{24f0}fstring_full_format_spec:
   | ':' @ref{24f1,,fstring_format_spec}*
@anchor{reference/lexical_analysis grammar-token-python-grammar-fstring_format_spec}@anchor{24f1}fstring_format_spec:
   | @ref{24ed,,FSTRING_MIDDLE}
   | @ref{24ec,,fstring_replacement_field}
@anchor{reference/lexical_analysis grammar-token-python-grammar-f_expression}@anchor{24ee}f_expression:
   | ','.(@ref{24f2,,conditional_expression} | "*" @ref{24f3,,or_expr})+ [","]
   | @ref{24f4,,yield_expression}
@end example

@cartouche
@quotation Σημείωση 
In the above grammar snippet, the @code{f_quote} and @code{FSTRING_MIDDLE} rules
are context-sensitive – they depend on the contents of @code{FSTRING_START}
of the nearest enclosing @code{fstring}.

Constructing a more traditional formal grammar from this template is left
as an exercise for the reader.
@end quotation
@end cartouche

The grammar for t-strings is identical to the one for f-strings, with `t'
instead of `f' at the beginning of rule and token names and in the prefix.

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-tstring}@anchor{24f5}tstring:    TSTRING_START tstring_middle* TSTRING_END

<rest of the t-string grammar is omitted; see above>
@end example

@node Αριθμητικά λεκτικά,Τελεστές και οριοθέτες,Λεκτικά συμβολοσειράς και Bytes,Λεξική ανάλυση
@anchor{reference/lexical_analysis numbers}@anchor{2492}@anchor{reference/lexical_analysis numeric-literals}@anchor{24f6}
@subsection Αριθμητικά λεκτικά


@geindex αριθμός
@geindex αριθμητικό λεκτικό
@geindex λεκτικό ακεραίου
@geindex λεκτικό κινητής υποδιαστολής
@geindex δεκαεξαδικό λεκτικό
@geindex οκταδικό λεκτικό
@geindex δυαδικό λεκτικό
@geindex δεκαδικό λεκτικό
@geindex λεκτικό φανταστικού
@geindex λεκτικό μιγαδικού

Τα tokens @ref{24ab,,NUMBER} αναπαριστούν αριθμητικά λεκτικά, τα οποία είναι τριών τύπων: ακέραιοι, αριθμοί κινητής υποδιαστολής και φανταστικοί αριθμοί.

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-NUMBER}@anchor{24f7}NUMBER: @ref{24f8,,integer} | @ref{24f9,,floatnumber} | @ref{24fa,,imagnumber}
@end example

Η αριθμητική τιμή ενός αριθμητικού λεκτικού είναι η ίδια σαν να περνιόταν ως string στον αντίστοιχο constructor των @ref{326,,int}, @ref{327,,float} ή @ref{328,,complex}. Σημειώστε ότι δεν είναι όλες οι έγκυρες είσοδοι για αυτούς τους constructors και έγκυρα λεκτικά.

Τα αριθμητικά λεκτικά δεν περιλαμβάνουν πρόσημο· μια έκφραση όπως @code{-1} είναι στην πραγματικότητα μια έκφραση που αποτελείται από τον μοναδιαίο τελεστή “@code{-}” και το λεκτικό @code{1}.

@geindex 0b;λεκτικό ακεραίου
@geindex 0o;λεκτικό ακεραίου
@geindex 0x;λεκτικό ακεραίου
@geindex _ (κάτω παύλα);σε αριθμητικό λεκτικό

@menu
* Λεκτικά ακεραίων:: 
* Λεκτικά κινητής υποδιαστολής:: 
* Λεκτικά φανταστικών:: 

@end menu

@node Λεκτικά ακεραίων,Λεκτικά κινητής υποδιαστολής,,Αριθμητικά λεκτικά
@anchor{reference/lexical_analysis integer-literals}@anchor{24fb}@anchor{reference/lexical_analysis integers}@anchor{24fc}
@subsubsection Λεκτικά ακεραίων


Τα λεκτικά ακεραίων δηλώνουν ακέραιους αριθμούς. Για παράδειγμα:

@example
7
3
2147483647
@end example

Δεν υπάρχει όριο στο μήκος των ακεραίων πέρα από αυτό που μπορεί να αποθηκευτεί στη διαθέσιμη μνήμη:

@example
7922816251426433759354395033679228162514264337593543950336
@end example

Οι κάτω παύλες μπορούν να χρησιμοποιηθούν για ομαδοποίηση ψηφίων ώστε να βελτιώνεται η αναγνωσιμότητα, και αγνοούνται κατά τον υπολογισμό της αριθμητικής τιμής του λεκτικού. Για παράδειγμα, τα παρακάτω λεκτικά είναι ισοδύναμα:

@example
100_000_000_000
100000000000
1_00_00_00_00_000
@end example

Οι κάτω παύλες μπορούν να εμφανίζονται μόνο ανάμεσα σε ψηφία. Για παράδειγμα, τα @code{_123}, @code{321_} και @code{123__321} `δεν' είναι έγκυρα λεκτικά.

Οι ακέραιοι μπορούν να δηλωθούν ως δυαδικοί (βάση του 2), οκταδικοί (βάση του 8) ή δεκαεξαδικοί (βάση του 16) χρησιμοποιώντας τα προθέματα @code{0b}, @code{0o} και @code{0x}, αντίστοιχα. Τα δεκαεξαδικά ψηφία 10 έως 15 αναπαριστώνται από τα γράμματα @code{A}-@code{F}, χωρίς διάκριση κεφαλαίων/πεζών. Για παράδειγμα:

@example
0b100110111
0b_1110_0101
0o177
0o377
0xdeadbeef
0xDead_Beef
@end example

Μια κάτω παύλα μπορεί να ακολουθεί τον προσδιοριστή βάσης. Για παράδειγμα, το @code{0x_1f} είναι έγκυρο λεκτικό, αλλά τα @code{0_x1f} και @code{0x__1f} δεν είναι.

Δεν επιτρέπονται μηδενικά στην αρχή σε μη-μηδενικό δεκαδικό αριθμό. Για παράδειγμα, το @code{0123} δεν είναι έγκυρο λεκτικό. Αυτό γίνεται για να αποσαφηνίζεται η διάκριση με οκταδικά λεκτικά τύπου C, τα οποία η Python χρησιμοποιούσε πριν την έκδοση 3.0.

Τυπικά, τα λεκτικά ακεραίων περιγράφονται από τους παρακάτω λεξικούς ορισμούς:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-integer}@anchor{24f8}integer:      @ref{24fd,,decinteger} | @ref{24fe,,bininteger} | @ref{24ff,,octinteger} | @ref{2500,,hexinteger} | @ref{2501,,zerointeger}
@anchor{reference/lexical_analysis grammar-token-python-grammar-decinteger}@anchor{24fd}decinteger:   @ref{2502,,nonzerodigit} (["_"] @ref{2503,,digit})*
@anchor{reference/lexical_analysis grammar-token-python-grammar-bininteger}@anchor{24fe}bininteger:   "0" ("b" | "B") (["_"] @ref{2504,,bindigit})+
@anchor{reference/lexical_analysis grammar-token-python-grammar-octinteger}@anchor{24ff}octinteger:   "0" ("o" | "O") (["_"] @ref{2505,,octdigit})+
@anchor{reference/lexical_analysis grammar-token-python-grammar-hexinteger}@anchor{2500}hexinteger:   "0" ("x" | "X") (["_"] @ref{2506,,hexdigit})+
@anchor{reference/lexical_analysis grammar-token-python-grammar-zerointeger}@anchor{2501}zerointeger:  "0"+ (["_"] "0")*
@anchor{reference/lexical_analysis grammar-token-python-grammar-nonzerodigit}@anchor{2502}nonzerodigit: "1"..."9"
@anchor{reference/lexical_analysis grammar-token-python-grammar-digit}@anchor{2503}digit:        "0"..."9"
@anchor{reference/lexical_analysis grammar-token-python-grammar-bindigit}@anchor{2504}bindigit:     "0" | "1"
@anchor{reference/lexical_analysis grammar-token-python-grammar-octdigit}@anchor{2505}octdigit:     "0"..."7"
@anchor{reference/lexical_analysis grammar-token-python-grammar-hexdigit}@anchor{2506}hexdigit:     @ref{2503,,digit} | "a"..."f" | "A"..."F"
@end example


Άλλαξε στην έκδοση 3.6: Οι κάτω παύλες επιτρέπονται πλέον στα λεκτικά για σκοπούς ομαδοποίησης.


@geindex . (τελεία);σε αριθμητικό λεκτικό
@geindex e;σε αριθμητικό λεκτικό
@geindex _ (κάτω παύλα);σε αριθμητικό λεκτικό

@node Λεκτικά κινητής υποδιαστολής,Λεκτικά φανταστικών,Λεκτικά ακεραίων,Αριθμητικά λεκτικά
@anchor{reference/lexical_analysis floating}@anchor{2507}@anchor{reference/lexical_analysis floating-point-literals}@anchor{2508}
@subsubsection Λεκτικά κινητής υποδιαστολής


Τα λεκτικά κινητής υποδιαστολής (float), όπως @code{3.14} ή @code{1.5}, δηλώνουν @ref{2509,,προσεγγίσεις πραγματικών αριθμών}.

Αποτελούνται από `ακέραιο' και `κλασματικό' μέρος, το καθένα από δεκαδικά ψηφία. Τα μέρη χωρίζονται από τελεία, @code{.}:

@example
2.71828
4.0
@end example

Σε αντίθεση με τα λεκτικά ακεραίων, επιτρέπονται μηδενικά στην αρχή. Για παράδειγμα, το @code{077.010} είναι νόμιμο και δηλώνει τον ίδιο αριθμό με το @code{77.01}.

Όπως και στα λεκτικά ακεραίων, μονές κάτω παύλες μπορούν να εμφανίζονται ανάμεσα σε ψηφία για καλύτερη αναγνωσιμότητα:

@example
96_485.332_123
3.14_15_93
@end example

Κάθε ένα από αυτά τα μέρη μπορεί να είναι κενό, αλλά όχι και τα δύο. Για παράδειγμα:

@example
10.  # (ισοδύναμο με το 10.0)
.001  # (ισοδύναμο με το 0.001)
@end example

Προαιρετικά, το ακέραιο και το κλασματικό μέρος μπορεί να ακολουθούνται από έναν `εκθέτη': το γράμμα @code{e} ή @code{E}, ακολουθούμενο από προαιρετικό πρόσημο, @code{+} ή @code{-}, και έναν αριθμό στην ίδια μορφή με το ακέραιο και το κλασματικό μέρος. Το @code{e} ή @code{E} σημαίνει «επί δέκα υψωμένο στη δύναμη»:

@example
1.0e3  # (αντιπροσωπεύει το 1.0×10³, ή το 1000.0)
1.166e-5  # (αντιπροσωπεύει το 1.166×10⁻⁵, ή το 0.00001166)
6.02214076e+23  # (αντιπροσωπεύει το 6.02214076×10²³, ή το 602214076000000000000000.)
@end example

Σε floats που έχουν μόνο ακέραιο μέρος και εκθέτη, η υποδιαστολή μπορεί να παραλειφθεί:

@example
1e3  # (ισοδύναμο με το 1.e3 και το 1.0e3)
0e0  # (ισοδύναμο με το 0.)
@end example

Τυπικά, τα λεκτικά κινητής υποδιαστολής περιγράφονται από τους παρακάτω λεξικούς ορισμούς:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-floatnumber}@anchor{24f9}floatnumber:
   | @ref{250a,,digitpart} "." [@ref{250a,,digitpart}] [@ref{250b,,exponent}]
   | "." @ref{250a,,digitpart} [@ref{250b,,exponent}]
   | @ref{250a,,digitpart} @ref{250b,,exponent}
@anchor{reference/lexical_analysis grammar-token-python-grammar-digitpart}@anchor{250a}digitpart: @ref{2503,,digit} (["_"] @ref{2503,,digit})*
@anchor{reference/lexical_analysis grammar-token-python-grammar-exponent}@anchor{250b}exponent:  ("e" | "E") ["+" | "-"] @ref{250a,,digitpart}
@end example


Άλλαξε στην έκδοση 3.6: Οι κάτω παύλες επιτρέπονται πλέον στα λεκτικά για σκοπούς ομαδοποίησης.


@geindex j;σε αριθμητικό λεκτικό

@node Λεκτικά φανταστικών,,Λεκτικά κινητής υποδιαστολής,Αριθμητικά λεκτικά
@anchor{reference/lexical_analysis imaginary}@anchor{250c}@anchor{reference/lexical_analysis imaginary-literals}@anchor{250d}
@subsubsection Λεκτικά φανταστικών


Η Python έχει αντικείμενα @ref{21c9,,μιγαδικών αριθμών}, αλλά δεν έχει λεκτικά μιγαδικών. Αντί αυτού, τα `λεκτικά φανταστικών' δηλώνουν μιγαδικούς αριθμούς με μηδενικό πραγματικό μέρος.

Για παράδειγμα, στα μαθηματικά, ο μιγαδικός αριθμός 3+4.2`i' γράφεται ως ο πραγματικός αριθμός 3 συν ο φανταστικός αριθμός 4.2`i'. Η Python χρησιμοποιεί παρόμοια σύνταξη, με τη διαφορά ότι η φανταστική μονάδα γράφεται ως @code{j} αντί για `i':

@example
3+4.2j
@end example

Αυτή είναι μια έκφραση που αποτελείται από το @ref{24fc,,λεκτικό ακεραίου} @code{3}, τον @ref{247d,,τελεστή} “@code{+}” και το @ref{250c,,λεκτικό φανταστικού} @code{4.2j}. Εφόσον αυτά είναι τρία ξεχωριστά tokens, επιτρέπονται κενοί χαρακτήρες ανάμεσά τους:

@example
3 + 4.2j
@end example

Δεν επιτρέπονται κενοί χαρακτήρες `μέσα' σε κάθε token. Συγκεκριμένα, το επίθημα @code{j} δεν μπορεί να διαχωριστεί από τον αριθμό που προηγείται.

Ο αριθμός πριν από το @code{j} έχει την ίδια σύνταξη με ένα λεκτικό κινητής υποδιαστολής. Άρα, τα παρακάτω είναι έγκυρα λεκτικά φανταστικών:

@example
4.2j
3.14j
10.j
.001j
1e100j
3.14e-10j
3.14_15_93j
@end example

Σε αντίθεση με ένα λεκτικό κινητής υποδιαστολής, η υποδιαστολή μπορεί να παραλειφθεί αν ο φανταστικός αριθμός έχει μόνο ακέραιο μέρος. Ο αριθμός εξακολουθεί να αξιολογείται ως αριθμός κινητής υποδιαστολής, όχι ως ακέραιος:

@example
10j
0j
1000000000000000000000000j   # ισοδύναμο με το 1e+24j
@end example

Το επίθημα @code{j} δεν κάνει διάκριση κεφαλαίων/πεζών. Αυτό σημαίνει ότι μπορείτε να χρησιμοποιήσετε @code{J} αντί αυτού:

@example
3.14J   # ισοδύναμο με το 3.14j
@end example

Τυπικά, τα λεκτικά φανταστικών περιγράφονται από τον παρακάτω λεξικό ορισμό:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-imagnumber}@anchor{24fa}imagnumber: (@ref{24f9,,floatnumber} | @ref{250a,,digitpart}) ("j" | "J")
@end example
@anchor{reference/lexical_analysis delimiters}@anchor{247c}@anchor{reference/lexical_analysis operators}@anchor{247d}
@node Τελεστές και οριοθέτες,,Αριθμητικά λεκτικά,Λεξική ανάλυση
@anchor{reference/lexical_analysis lexical-ellipsis}@anchor{24bb}@anchor{reference/lexical_analysis operators-and-delimiters}@anchor{250e}
@subsection Τελεστές και οριοθέτες


@geindex τελεστές
@geindex οριοθέτες

Η παρακάτω γραμματική ορίζει tokens `operator' και `delimiter', δηλαδή τον γενικό τύπο token @ref{247b,,OP}. Μια @ref{250f,,λίστα αυτών των tokens και των ονομάτων τους} είναι επίσης διαθέσιμη στην τεκμηρίωση του module @code{token}.

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-OP}@anchor{2510}OP:
   | assignment_operator
   | bitwise_operator
   | comparison_operator
   | enclosing_delimiter
   | other_delimiter
   | arithmetic_operator
   | "..."
   | other_op

@anchor{reference/lexical_analysis grammar-token-python-grammar-assignment_operator}@anchor{2511}assignment_operator:   "+=" | "-=" | "*=" | "**=" | "/="  | "//=" | "%=" |
                       "&=" | "|=" | "^=" | "<<=" | ">>=" | "@@="  | ":="
@anchor{reference/lexical_analysis grammar-token-python-grammar-bitwise_operator}@anchor{2512}bitwise_operator:      "&"  | "|"  | "^"  | "~"   | "<<"  | ">>"
@anchor{reference/lexical_analysis grammar-token-python-grammar-comparison_operator}@anchor{2513}comparison_operator:   "<=" | ">=" | "<"  | ">"   | "=="  | "!="
@anchor{reference/lexical_analysis grammar-token-python-grammar-enclosing_delimiter}@anchor{2514}enclosing_delimiter:   "("  | ")"  | "["  | "]"   | "@{"   | "@}"
@anchor{reference/lexical_analysis grammar-token-python-grammar-other_delimiter}@anchor{2515}other_delimiter:       ","  | ":"  | "!"  | ";"   | "="   | "->"
@anchor{reference/lexical_analysis grammar-token-python-grammar-arithmetic_operator}@anchor{2516}arithmetic_operator:   "+"  | "-"  | "**" | "*"   | "//"  | "/"   | "%"
@anchor{reference/lexical_analysis grammar-token-python-grammar-other_op}@anchor{2517}other_op:              "."  | "@@"
@end example

@cartouche
@quotation Σημείωση 
Γενικά, οι `τελεστές' χρησιμοποιούνται για να συνδυάζουν @ref{2518,,εκφράσεις}, ενώ οι `οριοθέτες' εξυπηρετούν άλλους σκοπούς. Ωστόσο, δεν υπάρχει σαφής, τυπική διάκριση μεταξύ των δύο κατηγοριών.

Κάποια tokens μπορούν να λειτουργούν είτε ως τελεστές είτε ως οριοθέτες, ανάλογα με τη χρήση. Για παράδειγμα, το @code{*} είναι και τελεστής πολλαπλασιασμού και οριοθέτης που χρησιμοποιείται για unpacking ακολουθιών, και το @code{@@} είναι και πολλαπλασιασμός πινάκων και οριοθέτης που εισάγει decorators.

Για ορισμένα tokens, η διάκριση δεν είναι ξεκάθαρη. Για παράδειγμα, κάποιοι θεωρούν τα @code{.}, @code{(} και @code{)} ως οριοθέτες, ενώ άλλοι τα βλέπουν ως τον τελεστή @ref{f8f,,getattr()} και τον/τους τελεστή/τελεστές κλήσης συνάρτησης.

Κάποιοι τελεστές της Python, όπως @code{and}, @code{or} και @code{not in}, χρησιμοποιούν tokens @ref{247a,,λέξεων-κλειδιών} αντί για «σύμβολα» (operator tokens).
@end quotation
@end cartouche

A sequence of three consecutive periods (@code{...}) has a special
meaning as an @ref{2519,,Ellipsis} literal.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Μοντέλο Δεδομένων,Μοντέλο εκτέλεσης,Λεξική ανάλυση,Εγχειρίδιο Αναφοράς της Γλώσσας Python
@anchor{reference/datamodel doc}@anchor{251a}@anchor{reference/datamodel data-model}@anchor{251b}@anchor{reference/datamodel datamodel}@anchor{1f4e}@anchor{reference/datamodel translation-repo}@anchor{251c}
@section Μοντέλο Δεδομένων


@menu
* Αντικείμενα@comma{} τιμές και τύποι: Αντικείμενα τιμές και τύποι. 
* Η τυπική ιεραρχία τύπου:: 
* Ειδικά ονόματα μεθόδων:: 
* Coroutines:: 

@end menu

@node Αντικείμενα τιμές και τύποι,Η τυπική ιεραρχία τύπου,,Μοντέλο Δεδομένων
@anchor{reference/datamodel objects}@anchor{251d}@anchor{reference/datamodel objects-values-and-types}@anchor{251e}
@subsection Αντικείμενα, τιμές και τύποι


@geindex αντικείμενο
@geindex δεδομένα

Το `Objects' είναι μια αφαιρετική αναπαράσταση της Python για τα δεδομένα.  Όλα τα δεδομένα σε ένα Python πρόγραμμα αναπαριστώνται από αντικείμενα ή από συσχετίσεις μεταξύ αντικειμένων. Ακόμη και ο κώδικας αναπαρίσταται από αντικείμενα.

@geindex ενσωματωμένη συνάρτηση;αναγνωριστικό
@geindex ενσωματωμένη συνάρτηση;τύπος
@geindex ταυτότητα ενός αντικειμένου
@geindex τιμή ενός αντικειμένου
@geindex τύπος ενός αντικειμένου
@geindex ευμετάβλητο αντικείμενο
@geindex αμετάβλητο αντικείμενο

Κάθε αντικείμενο έχει μια ταυτότητα, έναν τύπο και μια τιμή.  Η `ταυτότητα' ενός αντικειμένου δεν αλλάζει ποτέ αφού δημιουργηθεί∙ μπορείτε να το σκεφτείτε ως τη διεύθυνση του αντικειμένου στη μνήμη.  Ο τελεστής @ref{324,,is} συγκρίνει την ταυτότητα δύο αντικειμένων∙ η συνάρτηση @ref{17c5,,id()} επιστρέφει έναν ακέραιο αριθμό που αντιπροσωπεύει την ταυτότητά του.

Για την CPython, το @code{id(x)} είναι η διεύθυνση μνήμης όπου είναι αποθηκευμένο το @code{x}.

Ο τύπος ενός αντικειμένου καθορίζει τις λειτουργίες που υποστηρίζει το αντικείμενο (π.χ., «έχει μήκος;») και ορίζει επίσης τις πιθανές τιμές για αντικείμενα αυτού του τύπου.  Η συνάρτηση @ref{186,,type()} επιστρέφει τον τύπο ενός αντικειμένου (που είναι το ίδιο το αντικείμενο).  Όπως και η ταυτότητά, το `type' ενός αντικειμένου είναι επίσης αμετάβλητο. @footnote{
Αυτό `είναι' δυνατό σε ορισμένες περιπτώσεις να αλλάξει ο τύπος ενός αντικειμένου, υπό ορισμένες ελεγχόμενες συνθήκες. Γενικά δεν είναι καλή ιδέα όμως, καθώς μπορεί να οδηγήσει σε κάποια πολύ περίεργη συμπεριφορά εάν γίνει λάθος χειρισμός.
}

Η `τιμή' ορισμένων αντικειμένων μπορεί να αλλάξει.  Τα αντικείμενα των οποίων η τιμή μπορεί να αλλάξει λέγονται `μεταβλητά*∙ τα αντικείμενα των οποίων η τιμή είναι αμετάβλητη μόλις δημιουργηθούν ονομάζονται *αμετάβλητα'. (Η τιμή ενός αμετάβλητου container αντικειμένου που περιέχει μια αναφορά σε ένα μεταβλητό αντικείμενο μπορεί να αλλάξει όταν αλλάξει η τιμή του τελευταίου.  Ωστόσο, το container δεν μπορεί να θεωρείται ακόμα αμετάβλητο, επειδή η συλλογή δεν μπορεί να αλλάξει.  Έτσι, η αμετάβλητη δεν είναι αυστηρά ίδια με την αμετάβλητη τιμή, είναι πιο λεπτή.) Η μεταβλητότητα ενός αντικειμένου καθορίζεται από τον τύπο του∙ για παράδειγμα οι αριθμοί, οι συμβολοσειρές και οι πλειάδες είναι αμετάβλητα, ενώ τα λεξικά και οι λίστες είναι μεταβλητά.

@geindex συλλογή σκουπιδιών
@geindex καταμέτρηση αναφοράς
@geindex απρόσιτο αντικείμενο

Τα αντικείμενα δεν καταστρέφονται ποτέ ρητά∙ ωστόσο, όταν γίνονται απρόσιτα μπορεί να συλλεχθούν ως σκουπίδια.  Μια υλοποίηση επιτρέπεται να αναβάλει τη συλλογή σκουπιδιών ή να την παραλείψει εντελώς — είναι θέμα ποιότητας υλοποίησης πώς θα υλοποιηθεί η συλλογή απορριμμάτων, εφόσον δεν συλλέγονται αντικείμενα που είναι ακόμα προσβάσιμα.

Η CPython χρησιμοποιεί επί του παρόντος ένα σχήμα μέτρησης αναφορών με (προαιρετικό) καθυστερημένο εντοπισμό κυκλικά συνδεδεμένων σκουπιδιών, το οποίο συλλέγει τα περισσότερα αντικείμενα μόλις γίνουν απρόσιτα, αλλά δεν είναι εγγυημένο ότι συλλέγει σκουπίδια που κάνουν κυκλικές αναφορές.  Δείτε την τεκμηρίωση του module @ref{63,,gc} για πληροφορίες σχετικά με τον έλεγχο της συλλογής κυκλικών σκουπιδιών. Άλλες υλοποιήσεις ενεργούν διαφορετικά και η CPython μπορεί να αλλάξει. Μην εξαρτάστε από την άμεση οριστικοποίηση των αντικειμένων όταν γίνονται απρόσιτα (έτσι θα πρέπει πάντα να κλείνετε ρητά τα αρχεία).

Λάβετε υπόψη ότι η χρήση των υπηρεσιών ανίχνευσης ή εντοπισμού σφαλμάτων της υλοποίησης μπορεί να διατηρήσει ζωντανά αντικείμενα που κανονικά θα μπορούσαν να συλλεχθούν. Επίσης σημειώστε ότι η σύλληψη μιας εξαίρεσης με μια δήλωση @ref{ad6,,try}…@ref{447,,except}, μπορεί να κρατήσει ζωντανά αντικείμενα.

Ορισμένα αντικείμενα περιέχουν αναφορές σε «εξωτερικούς» πόρους, όπως ανοιχτά αρχεία ή παράθυρα.  Είναι κατανοητό ότι αυτοί οι πόροι ελευθερώνονται όταν το αντικείμενο συλλέγεται από σκουπίδια, αλλά επειδή η συλλογή απορριμμάτων δεν είναι εγγυημένη, τέτοια αντικείμενα παρέχουν επίσης έναν σαφή τρόπο απελευθέρωσης του εξωτερικού πόρου, συνήθως μια μέθοδο @code{close()}. Συνιστώνται προγράμματα για τη ρητό κλείσιμο τέτοιων αντικειμένων.  Η δήλωση @ref{ad6,,try}…@ref{44c,,finally} και η δήλωση @ref{20a,,with} παρέχουν βολικούς τρόπους για να το κάνετε αυτό.

@geindex κοντέινερ

Μερικά αντικείμενα περιέχουν αναφορές σε άλλα αντικείμενα· αυτά ονομάζονται `containers'. Παραδείγματα containers είναι πλειάδες, λίστες και λεξικά. Οι αναφορές αποτελούν μέρος της τιμής ενός container. Στις περισσότερες περιπτώσεις, όταν μιλάμε για την αξία ενός container, υπονοούμε τις τιμές, όχι τις ταυτότητες των αντικειμένων που περιέχονται. Ωστόσο, όταν μιλάμε για τη μεταβλητότητα ενός δοχείου υπονοούνται μόνο οι ταυτότητες των αμέσως περιεχομένων αντικειμένων. Έτσι, εάν ένα αμετάβλητο container (όπως μια πλειάδα) περιέχει μια αναφορά σε ένα μεταβλητό αντικείμενο, η τιμή του αλλάζει εάν αυτό το μεταβλητό αντικείμενο αλλάξει.

Οι τύποι επηρεάζουν σχεδόν όλες τις πτυχές της συμπεριφοράς των αντικειμένων.  Ακόμη και η σημασία της ταυτότητας αντικειμένου επηρεάζεται κατά κάποιο τρόπο: για αμετάβλητους τύπους, οι πράξεις που υπολογίζουν νέες τιμές μπορούν στην πραγματικότητα να επιστρέψουν μια αναφορά σε οποιοδήποτε υπάρχον αντικείμενο με τον ίδιο τύπο και τιμή, ενώ για μεταβλητά αντικείμενα αυτό δεν επιτρέπεται. Π.χ., μετά από @code{a = 1; b = 1}, τα `a' και `b' μπορεί να αναφέρονται ή να μην αναφέρονται στο ίδιο αντικείμενο με την τιμή ένα, ανάλογα με την υλοποίηση. Αυτό συμβαίνει επειδή το @ref{326,,int} είναι ένας αμετάβλητος τύπος, επομένως η αναφορά στο @code{1} μπορεί να επαναχρησιμοποιηθεί. Αυτή η συμπεριφορά εξαρτάται από την υλοποίηση που χρησιμοποιείται, επομένως δεν πρέπει να βασίζεστε σε αυτήν, αλλά είναι κάτι που πρέπει να γνωρίζετε όταν χρησιμοποιείτε δοκιμές ταυτότητας αντικειμένων. Ωστόσο, μετά από @code{c = []; d = []}, `c' και `d' είναι εγγυημένα ότι αναφέρονται σε δύο διαφορετικές, μοναδικές, νεοδημιουργημένες κενές λίστες. (Σημειώστε ότι το @code{e = f = []} αντιστοιχίζει το `ίδιο' αντικείμενο τόσο στο `e' όσο και στο `f'.)

@node Η τυπική ιεραρχία τύπου,Ειδικά ονόματα μεθόδων,Αντικείμενα τιμές και τύποι,Μοντέλο Δεδομένων
@anchor{reference/datamodel the-standard-type-hierarchy}@anchor{251f}@anchor{reference/datamodel types}@anchor{2520}
@subsection Η τυπική ιεραρχία τύπου


@geindex τύπος
@geindex δεδομένα;τύπος
@geindex τύπος;ιεραρχία
@geindex επέκταση;module
@geindex C;γλώσσα

Ακολουθεί μια λίστα με τους τύπους που είναι ενσωματωμένοι στην Python.  Τα modules επέκτασης (γραμμένες σε C, Java, ή άλλες γλώσσες, ανάλογα με την υλοποίηση) μπορούν να ορίσουν πρόσθετους τύπους. Οι μελλοντικές εκδόσεις της Python ενδέχεται να προσθέσουν τύπους στην ιεραρχία τύπων (π.χ. ορθολογικοί αριθμοί, αποτελεσματικά αποθηκευμένοι πίνακες ακεραίων κ.λπ.), ν και αντ” αυτού παρέχονται τυπικές βιβλιοθήκες.

@geindex χαρακτηριστικό
@geindex ειδικό;χαρακτηριστικό
@geindex γενικό;ειδικό;χαρακτηριστικό

Ορισμένες από τις παρακάτω περιγραφές τύπων περιέχουν μια παράγραφο με “ειδικά χαρακτηριστικά.”  Αυτά είναι χαρακτηριστικά που παρέχουν πρόσβαση στην υλοποίηση και δεν προορίζονται για γενική χρήση ο ορισμός τους μπορεί να αλλάξει στο μέλλον.

@menu
* None:: 
* NotImplemented:: 
* Ellipsis:: 
* numbers.Number: numbers Number. 
* Ακολουθίες:: 
* Σύνολο τύπων:: 
* Αντιστοιχίσεις:: 
* Τύποι με δυνατότητα κλήσης:: 
* Modules: Modules<3>. 
* Προσαρμοσμένες κλάσεις:: 
* Στιγμιότυπα κλάσης:: 
* Αντικείμενα εισόδου/εξόδου (γνωστά και ως αντικείμενα αρχείου): Αντικείμενα εισόδου/εξόδου γνωστά και ως αντικείμενα αρχείου. 
* Εσωτερικοί τύποι:: 

@end menu

@node None,NotImplemented,,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel none}@anchor{2521}
@subsubsection None


@geindex αντικείμενο;None

Αυτό ο τύπος έχει μια ενιαία τιμή.  Υπάρχει ένα μεμονωμένο αντικείμενο με αυτήν την τιμή. Η πρόσβαση σε αυτό το αντικείμενο γίνεται μέσω του ενσωματωμένου ονόματος @code{None}. Χρησιμοποιείται για να υποδηλώσει την απουσία τιμής σε πολλές περιπτώσεις, π.χ. επιστρέφεται από συναρτήσεις που δεν επιστρέφουν ρητά τίποτα. Η τιμή αλήθειας του είναι ψευδής.

@node NotImplemented,Ellipsis,None,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel notimplemented}@anchor{2522}
@subsubsection NotImplemented


@geindex αντικείμενο;NotImplemented

Αυτός ο τύπος έχει μια ενιαία τιμή.  Υπάρχει ένα μεμονωμένο αντικείμενο με αυτήν την τιμή. Η πρόσβαση σε αυτό το αντικείμενο γίνεται μέσω του ενσωματωμένου ονόματος @ref{440,,NotImplemented}. Οι αριθμητικές μέθοδοι και οι μέθοδοι εμπλουτισμένης σύγκρισης θα πρέπει να επιστρέφουν αυτήν την τιμή εάν δεν εφαρμόζουν τη λειτουργία για τους τελεστές που παρέχονται.  (Ο διερμηνέας θα δοκιμάσει την ανακλώμενη λειτουργία ή κάποια άλλη εναλλακτική, ανάλογα με τον τελεστή.)  Δεν πρέπει να αξιολογείται σε ένα boolean πλαίσιο.

Δείτε το @ref{2523,,Implementing the arithmetic operations} για περισσότερες λεπτομέρειες.


Άλλαξε στην έκδοση 3.9: Η αξιολόγηση του @ref{440,,NotImplemented} σε ένα boolean πλαίσιο έχει αποσυρθεί.



Άλλαξε στην έκδοση 3.14: Η αξιολόγηση του @ref{440,,NotImplemented} σε ένα boolean πλαίσιο τώρα κάνει raise μια @ref{291,,TypeError}. Προηγουμένως αξιολογούνταν σε @ref{fcc,,True} και εξέπεμπε μια @ref{2c9,,DeprecationWarning} από την Python 3.9.


@node Ellipsis,numbers Number,NotImplemented,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel ellipsis}@anchor{2524}
@subsubsection Ellipsis


@geindex αντικείμενο;Ellipsis
@geindex ...;ellipsis literal

Αυτός ο τύπος έχει μια ενιαία τιμή.  Υπάρχει ένα μεμονωμένο αντικείμενο με αυτή την τιμή. Η πρόσβαση σε αυτό το αντικείμενο γίνεται μέσω του literal @code{...} ή του ενσωματωμένου ονόματος @code{Ellipsis}.  Η τιμή αλήθειας του είναι αληθής.

@node numbers Number,Ακολουθίες,Ellipsis,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel numbers-number}@anchor{2525}
@subsubsection @code{numbers.Number}


@geindex αντικείμενο;αριθμητικό

Αυτά δημιουργούνται από αριθμητικά literals και επιστρέφονται ως αποτελέσματα από αριθμητικούς τελεστές και αριθμητικές ενσωματωμένες συναρτήσεις.  Τα αριθμητικά αντικείμενα είναι αμετάβλητα∙ μόλις δημιουργηθούν, η τιμή τους δεν αλλάζει ποτέ.  Οι αριθμοί Python φυσικά σχετίζονται στενά με τους μαθηματικούς αριθμούς, αλλά υπόκεινται στους περιορισμούς της αριθμητικής αναπαράστασης στους υπολογιστές.

Οι αναπαραστάσεις συμβολοσειρών των αριθμητικών κλάσεων, που υπολογίζονται από την @ref{1bc,,__repr__()} και από τη @ref{a0f,,__str__()}, έχουν τις ακόλουθες ιδιότητες:


@itemize *

@item 
Είναι έγκυρα αριθμητικά γράμματα τα οποία, όταν περάσουν στον κατασκευαστή της κλάσης τους, παράγουν ένα αντικείμενο που έχει την τιμή του αρχικού αριθμητικού.

@item 
Η αναπαράσταση είναι στη βάση του 10, όταν αυτό είναι εφικτό.

@item 
Τα προηγούμενα μηδενικά, ενδεχομένως με εξαίρεση ένα μόνο μηδέν πριν από μια υποδιαστολή, δεν εμφανίζονται.

@item 
Τα μηδενικά που ακολουθούν, ενδεχομένως με εξαίρεση ένα μεμονωμένο μηδέν μετά από μια υποδιαστολή, δεν εμφανίζονται.

@item 
Ένα πρόσημο εμφανίζεται μόνο όταν ο αριθμός είναι αρνητικός.
@end itemize

Η Python κάνει διάκριση μεταξύ ακεραίων, αριθμών κινητής υποδιαστολής και μιγαδικών αριθμών:

@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{2526}
@subsubsection @code{numbers.Integral}


@geindex αντικείμενο;ακέραιος

Αυτά αντιπροσωπεύουν στοιχεία από το μαθηματικό σύνολο ακεραίων (θετικών και αρνητικών).

@cartouche
@quotation Σημείωση 
@geindex ακέραιος;αναπαράσταση

Οι κανόνες για την αναπαράσταση ακεραίων έχουν σκοπό να δώσουν την πιο ουσιαστική ερμηνεία των πράξεων μετατόπισης και κάλυψης που περιλαμβάνουν αρνητικούς ακέραιους αριθμούς.
@end quotation
@end cartouche

Υπάρχουν δύο τύποι ακεραίων:


@table @asis

@item Ακέραιοι (@ref{326,,int})

Αυτές αντιπροσωπεύουν αριθμούς σε απεριόριστο εύρος, υπόκεινται μόνο στη διαθέσιμη (εικονική) μνήμη.  Για τους σκοπούς των λειτουργιών μετατόπισης και κάλυψης, θεωρείται μια δυαδική αναπαράσταση και οι αρνητικοί αριθμοί αντιπροσωπεύονται σε μια παραλλαγή του συμπληρώματος του 2 που δίνει την ψευδαίσθηση μιας άπειρης συμβολοσειράς bits από bits προσήμου που εκτείνονται προς τα αριστερά.

@item Booleans (@ref{5ef,,bool})

@geindex αντικείμενο;Boolean
@geindex False
@geindex True

Αυτά αντιπροσωπεύουν τις τιμές αλήθειας False και True.  Τα δύο αντικείμενα που αντιπροσωπεύουν τις τιμές @code{False} και @code{True} είναι τα μόνα Boolean αντικείμενα. Ο Boolean τύπος είναι ένας υποτύπος του ακεραίου τύπου και οι Boolean τιμές συμπεριφέρονται όπως οι τιμές 0 και 1, αντίστοιχα, σχεδόν σε όλα τα περιβάλλοντα, οι εξαιρέσεις που μετατρέπονται σε string είναι @code{"False"} ή @code{"True"} επιστρέφονται, αντίστοιχα.
@end table

@node numbers Real float,numbers Complex complex,numbers Integral,numbers Number
@anchor{reference/datamodel datamodel-float}@anchor{2509}@anchor{reference/datamodel numbers-real-float}@anchor{2527}
@subsubsection @code{numbers.Real} (@code{float})


@geindex αντικείμενο;κινητής υποδιαστολής
@geindex κινητής υποδιαστολής;αριθμός
@geindex C;γλώσσα
@geindex Java;γλώσσα

Αυτοί αντιπροσωπεύουν αριθμούς κινητής υποδιαστολής διπλής ακρίβειας σε επίπεδο μηχανής. Βρίσκεστε σε έλεος της υποκείμενης αρχιτεκτονικής μηχανής (και της εφαρμογής C ή Java) για το αποδεκτό εύρος και τον χειρισμό υπερχείλισης. Η Python δεν υποστηρίζει αριθμούς κινητής υποδιαστολής απλής ακρίβειας∙ η εξοικονόμηση στη χρήση επεξεργαστή και μνήμης που συνήθως είναι συνήθως ο λόγος για τη χρήση τους μειώνεται από την επιβάρυνση της χρήσης αντικειμένων στην Python, επομένως δεν υπάρχει λόγος να περιπλέκουμε τη γλώσσα με δύο είδη αριθμών κινητής υποδιαστολής.

@node numbers Complex complex,,numbers Real float,numbers Number
@anchor{reference/datamodel numbers-complex-complex}@anchor{2528}
@subsubsection @code{numbers.Complex} (@code{complex})


@geindex αντικείμενο;complex
@geindex complex;αριθμός

Αυτοί αντιπροσωπεύουν μιγαδικούς αριθμούς ως ζεύγος αριθμών κινητής υποδιαστολής διπλής ακρίβειας σε επίπεδο μηχανής.  Ισχύουν οι ίδιες προειδοποιήσεις όπως και για τους αριθμούς κινητής υποδιαστολής. Τα πραγματικά και τα φανταστικά μέρη ενός μιγαδικού αριθμού @code{z} μπορούν να ανακτηθούν μέσω των χαρακτηριστικών @code{z.real} και @code{z.imag} μόνο για ανάγνωση.

@node Ακολουθίες,Σύνολο τύπων,numbers Number,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel datamodel-sequences}@anchor{2529}@anchor{reference/datamodel sequences}@anchor{252a}
@subsubsection Ακολουθίες


@geindex ενσωματωμένη συνάρτηση;len
@geindex αντικείμενο;ακολουθία
@geindex λειτουργία ευρετηρίου
@geindex επιλογή αντικειμένου
@geindex εγγραφή

Αυτά αντιπροσωπεύουν πεπερασμένα διατεταγμένα σύνολα ευρετηριασμένα με μη αρνητικούς αριθμούς. Η ενσωματωμένη συνάρτηση @ref{a1f,,len()} επιστρέφει τον αριθμός των στοιχείων μιας ακολουθίας. Όταν το μήκος μια ακολουθίας είναι `n', το σύνολο δεικτών περιέχει τους αριθμούς 0, 1, …, `n'-1.  Το στοιχείο `i' της ακολουθίας `a' επιλέγεται από το @code{a[i]}. Ορισμένες ακολουθίες, συμπεριλαμβανομένων των ενσωματωμένων ακολουθιών, ερμηνεύουν αρνητικούς δείκτες προσθέτοντας το μήκος της ακολουθίας. Για παράδειγμα, το @code{a[-2]} ισούται με @code{a[n-2]}, το δεύτερο έως το τελευταίο στοιχείο της ακολουθίας a με μήκος @code{n}.

The resulting value must be a nonnegative integer less than the number of items
in the sequence. If it is not, an @ref{18d7,,IndexError} is raised.

@geindex τμηματοποίηση
@geindex start (χαρακτηριστικό αντικειμένου slice)
@geindex stop (χαρακτηριστικό αντικειμένου slice)
@geindex step (χαρακτηριστικό αντικειμένου slice)

Sequences also support slicing: @code{a[start:stop]} selects all items with index `k' such
that `start' @code{<=} `k' @code{<} `stop'.  When used as an expression, a slice is a
sequence of the same type. The comment above about negative subscripts also applies
to negative slice positions.
Note that no error is raised if a slice position is less than zero or larger
than the length of the sequence.

If `start' is missing or @ref{a65,,None}, slicing behaves as if `start' was zero.
If `stop' is missing or @code{None}, slicing behaves as if `stop' was equal to
the length of the sequence.

Ορισμένες ακολουθίες υποστηρίζουν επίσης την «εκτεταμένη τμηματοποίηση» με μια τρίτη παράμετρο «βήμα»: το @code{a[i:j:k]} επιλέγει όλα τα στοιχεία του `a' με ευρετήριο `x' όπου @code{x = i + n*k}, `n' @code{>=} @code{0} και `i' @code{<=} `x' @code{<} `j'.

Οι ακολουθίες διακρίνονται ανάλογα με τη μεταβλητότητά τους:

@menu
* Αμετάβλητες ακολουθίες:: 
* Μεταβλητές ακολουθίες:: 

@end menu

@node Αμετάβλητες ακολουθίες,Μεταβλητές ακολουθίες,,Ακολουθίες
@anchor{reference/datamodel immutable-sequences}@anchor{252b}
@subsubsection Αμετάβλητες ακολουθίες


@geindex αντικείμενο;αμετάβλητη ακολουθία
@geindex αντικείμενο;αμετάβλητο

Ένα αντικείμενο ενός τύπου αμετάβλητης ακολουθίας δεν μπορεί να αλλάξει μόλις δημιουργηθεί.  (Εάν το αντικείμενο περιέχει αναφορές σε άλλα αντικείμενα, αυτά τα άλλα αντικείμενα μπορεί να είναι μεταβλητά και μπορεί να αλλάξουν∙ ωστόσο, η συλλογή αντικειμένων που αναφέρονται απευθείας από ένα αμετάβλητο αντικείμενο δεν μπορεί να αλλάξει.)

Οι ακόλουθοι τύποι είναι αμετάβλητες ακολουθίες:

@geindex συμβολοσειρά;αμετάβλητες ακολουθίες


@table @asis

@item Συμβολοσειρές

@geindex ενσωματωμένη συνάρτηση;chr
@geindex ενσωματωμένη συνάρτηση;ord
@geindex χαρακτήρας
@geindex συμβολοσειρά;item
@geindex Unicode

A string (@ref{1df,,str}) is a sequence of values that represent
`characters', or more formally, `Unicode code points'.
All the code points in the range @code{0} to @code{0x10FFFF} can be
represented in a string.

Python doesn’t have a dedicated `character' type.
Instead, every code point in the string is represented as a string
object with length @code{1}.

The built-in function @ref{252c,,ord()}
converts a code point from its string form to an integer in the
range @code{0} to @code{0x10FFFF}; @ref{1bf8,,chr()} converts an integer in the range
@code{0} to @code{0x10FFFF} to the corresponding length @code{1} string object.
@ref{ca7,,str.encode()} can be used to convert a @ref{1df,,str} to
@ref{1c7,,bytes} using the given text encoding, and
@ref{ca8,,bytes.decode()} can be used to achieve the opposite.

@item Πλειάδες (Tuples)

@geindex αντικείμενο;πλειάδα
@geindex singleton;πλειάδα
@geindex empty;πλειάδα

The items of a @ref{1ce,,tuple} are arbitrary Python objects. Tuples of two or
more items are formed by comma-separated lists of expressions.  A tuple
of one item (a “singleton”) can be formed by affixing a comma to an
expression (an expression by itself does not create a tuple, since
parentheses must be usable for grouping of expressions).  An empty
tuple can be formed by an empty pair of parentheses.

@item Bytes

@geindex bytes
@geindex byte

A @ref{1c7,,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{1c7,,bytes()} constructor
can be used to create bytes objects.  Also, bytes objects can be
decoded to strings via the @ref{ca8,,decode()} method.
@end table

@node Μεταβλητές ακολουθίες,,Αμετάβλητες ακολουθίες,Ακολουθίες
@anchor{reference/datamodel mutable-sequences}@anchor{252d}
@subsubsection Μεταβλητές ακολουθίες


@geindex αντικείμενο;ευμετάβλητη ακολουθία
@geindex αντικείμενο;ευμετάβλητο
@geindex εκχώρηση;δήλωση
@geindex εγγραφή
@geindex τμηματοποίηση

Οι μεταβλητές ακολουθίες μπορούν να αλλάξουν αφού δημιουργηθούν.  Οι σημειώσεις εγγραφής και τμηματοποίησης μπορούν να χρησιμοποιηθούν ως στόχος εκχώρησης και δηλώσεων @ref{1d1d,,del} (delete).

@cartouche
@quotation Σημείωση 
@geindex module;πίνακας

@geindex module;συλλογές

Τα modules @ref{1e,,collections} και @ref{8,,array} παρέχουν πρόσθετα παραδείγματα μεταβλητών τύπων ακολουθιών.
@end quotation
@end cartouche

Υπάρχουν επί του παρόντος δύο εγγενείς τύποι μεταβλητών ακολουθιών:


@table @asis

@item Λίστες

@geindex αντικείμενο;λίστα

Τα στοιχεία μιας λίστας είναι αυθαίρετα αντικείμενα Python.  Οι λίστες σχηματίζονται τοποθετώντας μια λίστα εκφράσεων διαχωρισμένων με κόμματα σε αγκύλες. (Σημειώστε ότι δεν χρειάζονται ειδικές περιπτώσεις για να σχηματιστούν λίστες μήκους 0 ή 1.)

@item Πίνακες Byte

@geindex πίνακας byte

Ένα αντικείμενο bytearray είναι ένα ευμετάβλητος πίνακας. Δημιουργούνται από τον ενσωματωμένο κατασκευαστή @ref{1c6,,bytearray()}.  Εκτός από το ότι είναι μεταβλητοί (και επομένως μη κατακερματισμένοι), οι πίνακες byte κατά τα άλλα παρέχουν την ίδια διεπαφή και λειτουργικότητα με τα αμετάβλητα αντικείμενα @ref{1c7,,bytes}.
@end table

@node Σύνολο τύπων,Αντιστοιχίσεις,Ακολουθίες,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel set-types}@anchor{252e}
@subsubsection Σύνολο τύπων


@geindex ενσωματωμένη συνάρτηση;len
@geindex αντικείμενο;τύπος συνόλου

Αυτά αντιπροσωπεύουν μη διατεταγμένα, πεπερασμένα, σύνολα μοναδικών, αμετάβλητων αντικειμένων. Ως εκ τούτου, δεν μπορούν να ευρετηριοποιηθούν από κανένα δείκτη. Ωστόσο, μπορούν να επαναληφθούν και η ενσωματωμένη συνάρτηση @ref{a1f,,len()} επιστρέφει τον αριθμό των στοιχείων σε ένα σύνολο. Συνήθεις χρήσεις για τα σύνολα είναι ο γρήγορος έλεγχος ιδιότητας μέλους, η αφαίρεση διπλότυπων από μια αλληλουχία, μη συνδυαστική λειτουργία, και συμμετρική διαφορά.

Για τα στοιχεία συνόλου ισχύουν οι ίδιοι κανόνες αμετάβλητης όπως και για τα κλειδιά λεξικού. Λάβετε υπόψη ότι οι αριθμητικοί τύποι λειτουργία στους κανονικούς κανόνες για αριθμητική σύγκριση: εάν δύο αριθμοί συγκρίνονται ίσοι (π.χ. @code{1} και @code{1.0}), μόνο ένας από αυτούς μπορεί να περιέχεται σε ένα σύνολο.

Υπάρχουν επί του παρόντος δύο εγγενείς τύποι συνόλων:


@table @asis

@item Σύνολα

@geindex αντικείμενο;σύνολο

These represent a mutable set. They are created by the built-in @ref{42b,,set()}
constructor and can be modified afterwards by several methods, such as
@ref{252f,,add()}.

@item Frozen σύνολα

@geindex αντικείμενο;αμετάβλητο σύνολο

Αυτά αντιπροσωπεύουν ένα αμετάβλητο σύνολο.  Δημιουργούνται από τον ενσωματωμένο κατασκευαστή @ref{9d4,,frozenset()}. Καθώς ένα παγωμένο σύνολο είναι αμετάβλητο και το @ref{183,,hashable}, μπορεί να χρησιμοποιηθεί ξανά ως στοιχείο ενός άλλου συνόλου ή ως κλειδί λεξικού.
@end table

@node Αντιστοιχίσεις,Τύποι με δυνατότητα κλήσης,Σύνολο τύπων,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel datamodel-mappings}@anchor{2530}@anchor{reference/datamodel mappings}@anchor{2531}
@subsubsection Αντιστοιχίσεις


@geindex ενσωματωμένη συνάρτηση;len
@geindex εγγραφή
@geindex αντικείμενο;αντιστοίχιση

Αυτά αντιπροσωπεύουν πεπερασμένα σύνολα αντικειμένων που ευρετηριάζονται από αυθαίρετα σύνολα ευρετηρίου. Ο συμβολικός συμβολισμός @code{a[k]} επιλέγει το στοιχείο που ευρετηριάζεται με @code{k} από την αντιστοίχιση @code{a} · αυτό μπορεί να χρησιμοποιηθεί σε εκφράσεις και ως στόχος αναθέσεων ή δηλώσεων @ref{1d1d,,del}. Η ενσωματωμένη συνάρτηση @ref{a1f,,len()} επιστρέφει τον αριθμό των στοιχείων σε μια αντιστοίχιση.

Υπάρχει επί του παρόντος ένας ενιαίος εγγενής τύπος αντιστοίχισης:

@menu
* Λεξικά:: 

@end menu

@node Λεξικά,,,Αντιστοιχίσεις
@anchor{reference/datamodel dictionaries}@anchor{2532}
@subsubsection Λεξικά


@geindex αντικείμενο;λεξικό

Αυτά αντιπροσωπεύουν πεπερασμένα σύνολα αντικειμένων που ευρετηριάζονται με σχεδόν αυθαίρετες τιμές.  Οι μόνοι τύποι τιμών που δεν είναι αποδεκτοί ως κλειδιά είναι τιμές που περιέχουν λίστες ή λεξικά ή άλλους μεταβλητούς τύπους που συγκρίνονται με βάση την τιμή και όχι με την ταυτότητα αντικειμένου, ο λόγος είναι ότι η αποτελεσματική υλοποίηση λεξικών απαιτεί τιμή κατακερματισμού ενός κλειδιού να παραμένει σταθερή. Οι αριθμητικοί τύποι που χρησιμοποιούνται για κλειδιά υπακούουν στους κανονικούς κανόνες για αριθμητική σύγκριση: εάν δύο αριθμοί συγκρίνονται ίσοι (π.χ. @code{1} και @code{1.0}), τότε μπορούν να χρησιμοποιηθούν εναλλακτικά για την ευρετηρίαση της ίδιας καταχώρησης λεξικού.

Τα λεξικά διατηρούν τη σειρά εισαγωγής, πράγμα που σημαίνει ότι τα κλειδιά θα παράγονται με την ίδια σειρά που προστέθηκαν διαδοχικά στο λεξικό. Η αντικατάσταση ενός υπάρχοντος κλειδιού δεν αλλάζει τη σειρά, ωστόσο η αφαίρεση ενός κλειδιού και η επανεισαγωγή του θα προσθέσει στο τέλος αντί να διατηρήσει την παλιά του θέση.

Τα λεξικά είναι μεταβλητά· μπορούν να δημιουργηθούν με τη σημείωση @code{@{...@}} (βλ. ενότητα @ref{1138,,Dictionary displays}).

@geindex module;dbm.ndbm
@geindex module;dbm.gnu

Τα modules επέκτασης @ref{37,,dbm.ndbm} και @ref{36,,dbm.gnu} παρέχουν πρόσθετα παραδείγματα τύπων αντιστοίχισης, όπως και το module @ref{1e,,collections}.


Άλλαξε στην έκδοση 3.7: Τα λεξικά δεν διατήρησαν τη σειρά εισαγωγής σε εκδόσεις της Python πριν από την 3.6. Στη CPython 3.6, η σειρά εισαγωγής διατηρήθηκε, αλλά θεωρήθηκε ως λεπτομέρεια υλοποίησης εκείνη τη στιγμή και όχι ως εγγύηση γλώσσας.


@node Τύποι με δυνατότητα κλήσης,Modules<3>,Αντιστοιχίσεις,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel callable-types}@anchor{2533}
@subsubsection Τύποι με δυνατότητα κλήσης


@geindex αντικείμενο;με δυνατότητα κλήσης
@geindex συνάρτηση;κλήση
@geindex εκτέλεση
@geindex συνάρτηση;παράμετρος

Αυτοί είναι οι τύποι στους οποίους μπορεί να εφαρμοστεί η λειτουργία κλήσης συνάρτησης (βλ. ενότητα @ref{1136,,Calls}) :

@menu
* Συναρτήσεις που ορίζονται από τον χρήστη:: 
* Μέθοδοι Στιγμιοτύπου:: 
* Generator Συναρτήσεις:: 
* Coroutine συναρτήσεις:: 
* Asynchronous generator συναρτήσεις:: 
* Ενσωματωμένες συναρτήσεις:: 
* Ενσωματωμένες μεθόδους:: 
* Κλάσεις: Κλάσεις<2>. 
* Στιγμιότυπα Κλάσης:: 

@end menu

@node Συναρτήσεις που ορίζονται από τον χρήστη,Μέθοδοι Στιγμιοτύπου,,Τύποι με δυνατότητα κλήσης
@anchor{reference/datamodel user-defined-funcs}@anchor{79b}@anchor{reference/datamodel user-defined-functions}@anchor{2534}
@subsubsection Συναρτήσεις που ορίζονται από τον χρήστη


@geindex ορισμένο από τον χρήστη;συνάρτηση
@geindex αντικείμενο;συνάρτηση
@geindex αντικείμενο;συνάρτηση ορισμένη από τον χρήστη

Ένα αντικείμενο συνάρτησης που ορίζεται από τον χρήστη δημιουργείται από έναν ορισμό συνάρτησης (βλ. ενότητα @ref{2206,,Function definitions}).  Θα πρέπει να καλείται με μια λίστα ορισμών που περιέχει τον ίδιο αριθμό στοιχείων με την επίσημη λίστα παραμέτρων της συνάρτησης.

@menu
* Ειδικά χαρακτηριστικά μόνο για ανάγνωση:: 
* Ειδικά εγγράψιμα χαρακτηριστικά:: 

@end menu

@node Ειδικά χαρακτηριστικά μόνο για ανάγνωση,Ειδικά εγγράψιμα χαρακτηριστικά,,Συναρτήσεις που ορίζονται από τον χρήστη
@anchor{reference/datamodel special-read-only-attributes}@anchor{2535}
@subsubsection Ειδικά χαρακτηριστικά μόνο για ανάγνωση


@geindex __builtins__ (function attribute)
@geindex __closure__ (χαρακτηριστικό συνάρτησης)
@geindex __globals__ (χαρακτηριστικό συνάρτησης)
@geindex global;πεδίο ονομάτων


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Χαρακτηριστικό

@tab

Έννοια

@item

@geindex __builtins__ (ιδιότητα της function)
@anchor{reference/datamodel function __builtins__}@anchor{2536}
@deffn {Ιδιότητα} function.__builtins__
@end deffn

@tab

A reference to the @ref{188,,dictionary} that holds the function’s
builtins namespace.


Added in version 3.10.


@item

@geindex __globals__ (ιδιότητα της function)
@anchor{reference/datamodel function __globals__}@anchor{1678}
@deffn {Ιδιότητα} function.__globals__
@end deffn

@tab

Μια αναφορά στη @ref{188,,dictionary} που περιέχει τις @ref{2537,,global variables} – τον καθολικό χώρο ονομάτων του module στην οποία ορίστηκε η συνάρτηση.

@item

@geindex __closure__ (ιδιότητα της function)
@anchor{reference/datamodel function __closure__}@anchor{1675}
@deffn {Ιδιότητα} function.__closure__
@end deffn

@tab

Το @code{None} ή μια @ref{1ce,,tuple} από κελιά που περιέχουν δεσμεύσεις για τα ονόματα που καθορίζονται στο χαρακτηριστικό @ref{2538,,co_freevars} του @ref{79c,,code object} της συνάρτησης.

Ένα αντικείμενο κελιού έχει το χαρακτηριστικό @code{cell_contents}. Αυτό μπορεί να χρησιμοποιηθεί για να ληφθεί η τιμή του κελιού, καθώς και να οριστεί η τιμή.

@end multitable


@node Ειδικά εγγράψιμα χαρακτηριστικά,,Ειδικά χαρακτηριστικά μόνο για ανάγνωση,Συναρτήσεις που ορίζονται από τον χρήστη
@anchor{reference/datamodel special-writable-attributes}@anchor{2539}
@subsubsection Ειδικά εγγράψιμα χαρακτηριστικά


@geindex __doc__ (χαρακτηριστικό συνάρτησης)
@geindex __name__ (χαρακτηριστικό συνάρτησης)
@geindex __module__ (χαρακτηριστικό συνάρτησης)
@geindex __dict__ (χαρακτηριστικό συνάρτησης)
@geindex __defaults__ (χαρακτηριστικό συνάρτησης)
@geindex __code__ (χαρακτηριστικό συνάρτησης)
@geindex __annotations__ (χαρακτηριστικό συνάρτησης)
@geindex __annotate__ (χαρακτηριστικό συνάρτησης)
@geindex __kwdefaults__ (χαρακτηριστικό συνάρτησης)
@geindex __type_params__ (χαρακτηριστικό συνάρτησης)

Τα περισσότερα από αυτά τα χαρακτηριστικά ελέγχουν τον τύπο της εκχωρημένης τιμής:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Χαρακτηριστικό

@tab

Έννοια

@item

@geindex __doc__ (ιδιότητα της function)
@anchor{reference/datamodel function __doc__}@anchor{1582}
@deffn {Ιδιότητα} function.__doc__
@end deffn

@tab

Η συμβολοσειρά τεκμηρίωσης της συνάρτηση ή @code{None} εάν δεν είναι διαθέσιμη.

@item

@geindex __name__ (ιδιότητα της function)
@anchor{reference/datamodel function __name__}@anchor{1679}
@deffn {Ιδιότητα} function.__name__
@end deffn

@tab

Το όνομα της συνάρτησης. Δείτε επίσης @ref{140e,,__name__ attributes}.

@item

@geindex __qualname__ (ιδιότητα της function)
@anchor{reference/datamodel function __qualname__}@anchor{253a}
@deffn {Ιδιότητα} function.__qualname__
@end deffn

@tab

Η συνάρτηση είναι @ref{1f19,,qualified name}. Δείτε επίσης @ref{140d,,__qualname__ attributes}.


Added in version 3.3.


@item

@geindex __module__ (ιδιότητα της function)
@anchor{reference/datamodel function __module__}@anchor{253b}
@deffn {Ιδιότητα} function.__module__
@end deffn

@tab

Το όνομα του module στην οποία ορίστηκε η συνάρτηση ή @code{None} εάν δεν είναι διαθέσιμη.

@item

@geindex __defaults__ (ιδιότητα της function)
@anchor{reference/datamodel function __defaults__}@anchor{1676}
@deffn {Ιδιότητα} function.__defaults__
@end deffn

@tab

Ένα @ref{1ce,,tuple} που περιέχει προεπιλεγμένες τιμές @ref{253c,,parameter} για εκείνες τις παραμέτρους που έχουν προεπιλογές ή @code{None} εάν καμία παράμετρος δεν έχει προεπιλεγμένη τιμή.

@item

@geindex __code__ (ιδιότητα της function)
@anchor{reference/datamodel function __code__}@anchor{79c}
@deffn {Ιδιότητα} function.__code__
@end deffn

@tab

Το αντικείμενο @ref{6eb,,code object} που αντιπροσωπεύει το μεταγλωττισμένο σώμα συνάρτησης.

@item

@geindex __dict__ (ιδιότητα της function)
@anchor{reference/datamodel function __dict__}@anchor{1677}
@deffn {Ιδιότητα} function.__dict__
@end deffn

@tab

Ο χώρος ονομάτων που υποστηρίζει  αυθαίρετα χαρακτηριστικά συνάρτησης. Δείτε επίσης @ref{1bf,,__dict__ attributes}.

@item

@geindex __annotations__ (ιδιότητα της function)
@anchor{reference/datamodel function __annotations__}@anchor{1581}
@deffn {Ιδιότητα} function.__annotations__
@end deffn

@tab

Μια @ref{188,,dictionary} που περιέχει annotations για @ref{253c,,parameters}. Τα κλειδιά του λεξικού είναι τα ονόματα των παραμέτρων και @code{'return'}, για το annotation επιστροφής, εάν παρέχεται. Δείτε επίσης: @ref{66b,,object.__annotations__}.


Άλλαξε στην έκδοση 3.14: Τα annotations πλέον @ref{872,,lazily evaluated}. Βλ. 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/}.


@item

@geindex __annotate__ (ιδιότητα της function)
@anchor{reference/datamodel function __annotate__}@anchor{253d}
@deffn {Ιδιότητα} function.__annotate__
@end deffn

@tab

Η @ref{40a,,annotate function} για αυτή τη συνάρτηση ή @code{None} εάν η συνάρτηση δεν έχει annotations. Δείτε @ref{1b95,,object.__annotate__}.


Added in version 3.14.


@item

@geindex __kwdefaults__ (ιδιότητα της function)
@anchor{reference/datamodel function __kwdefaults__}@anchor{13d0}
@deffn {Ιδιότητα} function.__kwdefaults__
@end deffn

@tab

Μια @ref{188,,dictionary} που περιέχει προεπιλογές για λέξεις-κλειδιά μόνο @ref{253c,,parameters}.

@item

@geindex __type_params__ (ιδιότητα της function)
@anchor{reference/datamodel function __type_params__}@anchor{253e}
@deffn {Ιδιότητα} function.__type_params__
@end deffn

@tab

Μια @ref{1ce,,tuple} που περιέχει τις παραμέτρους @ref{7a5,,type parameters} μιας @ref{86f,,generic function}.


Added in version 3.12.


@end multitable


Τα αντικείμενα συναρτήσεων υποστηρίζουν επίσης τη λήψη και τον καθορισμό αυθαίρετων χαρακτηριστικών , τα οποία μπορούν να χρησιμοποιηθούν, για παράδειγμα, για την επισύναψη μεταδεδομένων σε συναρτήσεις.  Η τυπική σημειογραφία σημείων χαρακτηριστικών χρησιμοποιείται για τη λήψη και τον ορισμό τέτοιων χαρακτηριστικών.

Η τρέχουσα υλοποίηση του CPython υποστηρίζει μόνο χαρακτηριστικά συναρτήσεων σε συναρτήσεις που καθορίζονται από τον χρήστη. Τα χαρακτηριστικά συναρτήσεων σε @ref{253f,,built-in functions} ενδέχεται να υποστηρίζονται στο μέλλον.

Μπορούν να ανακτηθούν πρόσθετες πληροφορίες σχετικά με τον ορισμό μιας συνάρτησης από το αντικείμενο @ref{6eb,,code object} (προσβάσιμο μέσω του χαρακτηριστικού @ref{79c,,__code__}).

@node Μέθοδοι Στιγμιοτύπου,Generator Συναρτήσεις,Συναρτήσεις που ορίζονται από τον χρήστη,Τύποι με δυνατότητα κλήσης
@anchor{reference/datamodel id2}@anchor{2540}@anchor{reference/datamodel instance-methods}@anchor{2297}
@subsubsection Μέθοδοι Στιγμιοτύπου


@geindex αντικείμενο;μέθοδος
@geindex αντικείμενο;μέθοδος ορισμένη από τον χρήστη
@geindex ορισμένο από τον χρήστη;μέθοδος

Ένα αντικείμενο μεθόδου στιγμιοτύπου συνδυάζει μια κλάση, ένα στιγμιότυπο κλάσης και οποιοδήποτε αντικείμενο που μπορεί να κληθεί (συνήθως μια συνάρτηση που ορίζεται από τον χρήστη.)

@geindex __func__ (χαρακτηριστικό μεθόδου)
@geindex __self__ (χαρακτηριστικό μεθόδου)
@geindex __doc__ (χαρακτηριστικό μεθόδου)
@geindex __name__ (χαρακτηριστικό μεθόδου)
@geindex __module__ (χαρακτηριστικό μεθόδου)

Ειδικά χαρακτηριστικά μόνο για ανάγνωση:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex __self__ (ιδιότητα της method)
@anchor{reference/datamodel method __self__}@anchor{176b}
@deffn {Ιδιότητα} method.__self__
@end deffn

@tab

Αναφέρεται στο αντικείμενο στιγμιοτύπου κλάσης στο οποίο βρίσκεται η μέθοδος @ref{2541,,bound}

@item

@geindex __func__ (ιδιότητα της method)
@anchor{reference/datamodel method __func__}@anchor{16a1}
@deffn {Ιδιότητα} method.__func__
@end deffn

@tab

Αναφέρεται στο αρχικό @ref{79b,,function object}

@item

@geindex __doc__ (ιδιότητα της method)
@anchor{reference/datamodel method __doc__}@anchor{2542}
@deffn {Ιδιότητα} method.__doc__
@end deffn

@tab

Η τεκμηρίωση της μεθόδου (ίδια με την @ref{1582,,method.__func__.__doc__}). Μια @ref{1df,,string} εάν η αρχική συνάρτηση είχε docstring, αλλιώς @code{None}.

@item

@geindex __name__ (ιδιότητα της method)
@anchor{reference/datamodel method __name__}@anchor{2543}
@deffn {Ιδιότητα} method.__name__
@end deffn

@tab

Το όνομα της μεθόδου (ίδιο με το @ref{1679,,method.__func__.__name__})

@item

@geindex __module__ (ιδιότητα της method)
@anchor{reference/datamodel method __module__}@anchor{2544}
@deffn {Ιδιότητα} method.__module__
@end deffn

@tab

Το όνομα του module στην οποία ορίστηκε η μέθοδος, ή @code{None} εάν δεν είναι διαθέσιμη.

@end multitable


Οι μέθοδοι υποστηρίζουν επίσης την πρόσβαση (αλλά όχι τη ρύθμιση) των αυθαίρετων χαρακτηριστικών συνάρτησης στο υποκείμενο αντικείμενο @ref{79b,,function object}.

Τα αντικείμενα μεθόδου που ορίζονται από το χρήστη μπορούν να δημιουργηθούν όταν λαμβάνεται ένα χαρακτηριστικό μιας κλάσης (ίσως μέσω ενός στιγμιοτύπου αυτής της κλάσης), εάν αυτό το χαρακτηριστικό είναι ένα αντικείμενο @ref{79b,,function object} ή ένα αντικείμενο @ref{69a,,classmethod}.
@anchor{reference/datamodel method-binding}@anchor{2541}
Όταν δημιουργείται ένα αντικείμενο μεθόδου στιγμιοτύπου ανακτώντας ένα αντικείμενο @ref{79b,,function object} που ορίζεται από το χρήστη από μια κλάση, το χαρακτηριστικό @ref{176b,,__self__} είναι το στιγμιότυπο και το αντικείμενό της μεθόδου λέγεται ότι είναι `δεσμευμένο'.  Το χαρακτηριστικό @ref{16a1,,__func__} της νέας μεθόδου είναι το αρχικό αντικείμενο συνάρτησης.

Όταν ένα αντικείμενο μεθόδου παρουσίας δημιουργείται με ανάκτηση ενός αντικειμένου @ref{69a,,classmethod} από μια κλάση ή στιγμιότυπο, το χαρακτηριστικό @ref{176b,,__self__} είναι η ίδια κλάση και το χαρακτηριστικό @ref{16a1,,__func__} είναι το αντικείμενο συνάρτησης που βρίσκεται κάτω από τη μέθοδο κλάσης.

Όταν καλείται ένα αντικείμενο μεθόδου στιγμιοτύπου, καλείται η υποκείμενη συνάρτηση (@ref{16a1,,__func__}), εισάγοντας το στιγμιότυπο κλάσης (@ref{176b,,__self__}) μπροστά από τη λίστα ορισμάτων.  Για παράδειγμα, όταν η @code{C} είναι μια κλάση που περιέχει έναν ορισμό για μια συνάρτηση @code{f()}, και το @code{x} είναι ένα στιγμιότυπο της @code{C}, η κλήση του @code{x.f(1)} ισοδυναμεί με την κλήση του @code{C.f(x, 1)}.

Όταν ένα αντικείμενο μεθόδου στιγμιοτύπου προέρχεται από ένα αντικείμενο @ref{69a,,classmethod}, το «στιγμιότυπο κλάσης» που είναι αποθηκευμένο στη @ref{176b,,__self__} θα είναι στη πραγματικότητα η ίδια η κλάση, έτσι ώστε η κλήση είτε του @code{x.f(1)} ή του @code{C.f(1)} ισοδυναμεί με την κλήση του @code{f(C,1)} όπου το @code{f} είναι η υποκείμενη συνάρτηση.

Είναι σημαντικό να σημειωθεί ότι οι συναρτήσεις που ορίζονται από το χρήστη και είναι χαρακτηριστικό ενός στιγμιοτύπου μιας κλάσης δεν μετατρέπονται σε δεσμευμένες μεθόδους∙ Αυτό συμβαίνει `μόνο' όταν η συνάρτηση είναι χαρακτηριστικό της κλάσης.

@node Generator Συναρτήσεις,Coroutine συναρτήσεις,Μέθοδοι Στιγμιοτύπου,Τύποι με δυνατότητα κλήσης
@anchor{reference/datamodel generator-functions}@anchor{2545}
@subsubsection Generator Συναρτήσεις


@geindex γεννήτρια;συνάρτηση
@geindex γεννήτρια;iterator

Μια συνάρτηση ή μέθοδος που χρησιμοποιεί τη δήλωση @ref{d93,,yield} (βλ. ενότητα @ref{d93,,Η εντολή yield}) ονομάζεται `generator function'.  Μια τέτοια συνάρτηση, όταν καλείται, επιστρέφει πάντα ένα αντικείμενο @ref{6ce,,iterator} που μπορεί να χρησιμοποιηθεί για την εκτέλεση του σώματος της συνάρτησης: καλώντας τη μέθοδο @ref{1672,,iterator.__next__()} του iterator θα προκαλέσει την εκτέλεση της συνάρτησης έως ότου παρέχει μια τιμή χρησιμοποιώντας τη δήλωση @code{yield}.  Όταν η συνάρτηση εκτελεί μια δήλωση @ref{44b,,return} ή πέσει στο τέλος, γίνεται raise μια εξαίρεση @ref{fba,,StopIteration} και ο iterator θα έχει φτάσει στο τέλος του συνόλου τιμών που θα επιστραφεί.

@node Coroutine συναρτήσεις,Asynchronous generator συναρτήσεις,Generator Συναρτήσεις,Τύποι με δυνατότητα κλήσης
@anchor{reference/datamodel coroutine-functions}@anchor{2546}
@subsubsection Coroutine συναρτήσεις


@geindex coroutine;συνάρτηση

Μια συνάρτηση ή μέθοδος που ορίζεται χρησιμοποιώντας @ref{9cf,,async def} ονομάζεται μια `coroutine function'.  Μια τέτοια συνάρτηση, όταν καλείται, επιστρέφει ένα αντικείμενο @ref{8a2,,coroutine}.  Μπορεί να περιέχει εκφράσεις @ref{432,,await}, καθώς και @ref{20b,,async with} και @ref{e70,,async for}. Δείτε επίσης την ενότητα @ref{2547,,Coroutine Αντικείμενα}.

@node Asynchronous generator συναρτήσεις,Ενσωματωμένες συναρτήσεις,Coroutine συναρτήσεις,Τύποι με δυνατότητα κλήσης
@anchor{reference/datamodel asynchronous-generator-functions}@anchor{2548}
@subsubsection Asynchronous generator συναρτήσεις


@geindex ασύγχρονη γεννήτρια;συνάρτηση
@geindex ασύγχρονη γεννήτρια;ασύγχρονος iterator

Μια συνάρτηση ή μέθοδος που ορίζεται χρησιμοποιώντας @ref{9cf,,async def} και που χρησιμοποιεί την πρόταση @ref{d93,,yield} ονομάζεται `asynchronous generator function'.  Μια τέτοια συνάρτηση, όταν καλείται, επιστρέφει ένα αντικείμενο @ref{6cd,,asynchronous iterator} που μπορεί να χρησιμοποιηθεί σε μια δήλωση @ref{e70,,async for} για την εκτέλεση του σώματος της συνάρτησης.

Η κλήση της μεθόδου @ref{1aa7,,aiterator.__anext__} του ασύγχρονου iterator θα επιστρέψει ένα @ref{6cf,,awaitable} το οποίο όταν αναμένεται θα εκτελεστεί έως ότου δώσει μια τιμή χρησιμοποιώντας την έκφραση @ref{d93,,yield}.  Όταν η συνάρτηση εκτελεί μια κενή εντολή @ref{44b,,return} ή πέφτει στο τέλος, γίνεται raise μια εξαίρεση @ref{1ffe,,StopAsyncIteration} και ο ασύγχρονος iterator θα έχει φτάσει στο τέλος του συνόλου τιμών που θα αποδοθούν.

@node Ενσωματωμένες συναρτήσεις,Ενσωματωμένες μεθόδους,Asynchronous generator συναρτήσεις,Τύποι με δυνατότητα κλήσης
@anchor{reference/datamodel built-in-functions}@anchor{2549}@anchor{reference/datamodel builtin-functions}@anchor{253f}
@subsubsection Ενσωματωμένες συναρτήσεις


@geindex αντικείμενο;ενσωματωμένη συνάρτηση
@geindex αντικείμενο;συνάρτηση
@geindex C;γλώσσα

Ένα αντικείμενο ενσωματωμένης συνάρτησης είναι ένας wrapper γύρω από μια συνάρτηση C.  Παραδείγματα ενσωματωμένων συναρτήσεων είναι οι @ref{a1f,,len()} και @ref{1860,,math.sin()} (@ref{91,,math} είναι ένα ενσωματωμένο module). Ο αριθμός και ο τύπος των ορισμάτων καθορίζονται από τη συνάρτηση C. Ειδικά χαρακτηριστικά μόνο για ανάγνωση:


@itemize *

@item 
Η @code{__doc__} είναι η συμβολοσειρά τεκμηρίωσης της συνάρτησης, ή @code{None} εάν δεν είναι διαθέσιμη . Δείτε @ref{1582,,function.__doc__}.

@item 
Η @code{__name__} είναι το όνομα της συνάρτησης. Δείτε @ref{1679,,function.__name__}.

@item 
Η @code{__self__} έχει οριστεί σε @code{None} (αλλά δείτε το επόμενο στοιχείο).

@item 
Η @code{__module__} είναι το όνομα του module στην οποία ορίστηκε η συνάρτηση ή @code{None} εάν δεν είναι διαθέσιμη. Δείτε @ref{253b,,function.__module__}.
@end itemize

@node Ενσωματωμένες μεθόδους,Κλάσεις<2>,Ενσωματωμένες συναρτήσεις,Τύποι με δυνατότητα κλήσης
@anchor{reference/datamodel built-in-methods}@anchor{254a}@anchor{reference/datamodel builtin-methods}@anchor{254b}
@subsubsection Ενσωματωμένες μεθόδους


@geindex αντικείμενο;ενσωματωμένη μέθοδος
@geindex αντικείμενο;μέθοδος
@geindex built-in;μέθοδος

Αυτή είναι πραγματικά μια διαφορετική μεταμφίεση μιας ενσωματωμένης συνάρτησης, αυτή τη φορά που περιέχει ένα αντικείμενο που μεταβιβάστηκε στη συνάρτηση C ως ένα έμμεσο επιπλέον όρισμα. Ένα παράδειγμα ενσωματωμένης μεθόδου είναι η @code{alist.append()}, υποθέτοντας ότι το `alist' είναι αντικείμενο λίστας. Σε αυτήν την περίπτωση, το ειδικό χαρακτηριστικό μόνο για ανάγνωση @code{__self__} ορίζεται στο αντικείμενο που συμβολίζεται με `alist'. (Το χαρακτηριστικό έχει την ίδια σημασιολογία με το @ref{176b,,other instance methods}.)

@node Κλάσεις<2>,Στιγμιότυπα Κλάσης,Ενσωματωμένες μεθόδους,Τύποι με δυνατότητα κλήσης
@anchor{reference/datamodel classes}@anchor{254c}@anchor{reference/datamodel id3}@anchor{254d}
@subsubsection Κλάσεις


Οι κλάσεις μπορούν να κληθούν.  Αυτά τα αντικείμενα λειτουργούν κανονικά ως εργοστάσια (factories) για νέα στιγμιότυπα του εαυτού τους, αλλά είναι δυνατές παραλλαγές για τύπους κλάσεων που παρακάμπτουν το @ref{982,,__new__()}.  Τα ορίσματα της κλήσης μεταβιβάζονται στην @code{__new__()} και, στην τυπική περίπτωση, στη @ref{2fa,,__init__()} για να αρχικοποιηθεί το νέο στιγμιότυπο.

@node Στιγμιότυπα Κλάσης,,Κλάσεις<2>,Τύποι με δυνατότητα κλήσης
@anchor{reference/datamodel class-instances}@anchor{254e}
@subsubsection Στιγμιότυπα Κλάσης


Τα στιγμιότυπα αυθαίρετων κλάσεων μπορούν να έχουν την δυνατότητα κλήσης ορίζοντας μια μέθοδο @ref{961,,__call__()} στην κλάση τους.

@node Modules<3>,Προσαρμοσμένες κλάσεις,Τύποι με δυνατότητα κλήσης,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel module-objects}@anchor{254f}@anchor{reference/datamodel modules}@anchor{2550}
@subsubsection Modules


@geindex δήλωση;import
@geindex αντικείμενο;module

Τα modules είναι μια βασική οργανωτική μονάδα κώδικα Python, και δημιουργούνται από το @ref{2551,,import system} όπως καλείται είτε από τη δήλωση @ref{9da,,import} είτε με κλήση συναρτήσεων όπως @ref{927,,importlib.import_module()} και το ενσωματωμένο @ref{ca6,,__import__()}.  Ένα αντικείμενο module έχει έναν χώρο ονομάτων που υλοποιείται από ένα αντικείμενο @ref{188,,dictionary} (αυτό είναι το λεξικό που αναφέρεται από τη συνάρτηση @ref{1678,,__globals__} των συναρτήσεων που ορίζονται στο module).  Οι αναφορές χαρακτηριστικών μεταφράζονται σε αναζητήσεις σε αυτό το λεξικό, π.χ., το @code{m.x} ισοδυναμεί με @code{m.__dict__["x"]}. Ένα αντικείμενο module δεν περιέχει το αντικείμενο κώδικα που χρησιμοποιείται για την προετοιμασία του module (καθώς δεν χρειάζεται μόλις ολοκληρωθεί η προετοιμασία).

Η εκχώρηση χαρακτηριστικών ενημερώνει το λεξικό χώρου ονομάτων του module, π.χ., @code{m.x = 1} ισοδυναμεί με @code{m.__dict__["x"] = 1}.

@geindex __name__ (χαρακτηριστικό module)
@geindex __spec__ (χαρακτηριστικό module)
@geindex __package__ (χαρακτηριστικό module)
@geindex __loader__ (χαρακτηριστικό module)
@geindex __path__ (χαρακτηριστικό module)
@geindex __file__ (χαρακτηριστικό module)
@geindex __doc__ (χαρακτηριστικό module)
@geindex __annotations__ (χαρακτηριστικό module)
@geindex __annotate__ (χαρακτηριστικό module)
@geindex __lazy_modules__ (module attribute)
@geindex module;πεδίο ονομάτων

@menu
* Χαρακτηριστικά που σχετίζονται με εισαγωγή σε αντικείμενα modules:: 
* Άλλα εγγράφως χαρακτηριστικά σε αντικείμενα μονάδων:: 
* Λεξικά Modules:: 

@end menu

@node Χαρακτηριστικά που σχετίζονται με εισαγωγή σε αντικείμενα modules,Άλλα εγγράφως χαρακτηριστικά σε αντικείμενα μονάδων,,Modules<3>
@anchor{reference/datamodel import-mod-attrs}@anchor{2552}@anchor{reference/datamodel import-related-attributes-on-module-objects}@anchor{2553}
@subsubsection Χαρακτηριστικά που σχετίζονται με εισαγωγή σε αντικείμενα modules


Τα αντικείμενα modules έχουν τα ακόλουθα χαρακτηριστικά που σχετίζονται με το @ref{2551,,import system}. Όταν δημιουργείται ένα module με τη χρήση του μηχανήματος που σχετίζεται με το σύστημα εισαγωγής, αυτά τα χαρακτηριστικά συμπληρώνονται με βάση το @ref{2554,,spec} του module, προτού το @ref{1c30,,loader} εκτελέσει και φορτώσει το module.

Για να δημιουργήσετε ένα module δυναμικά αντί να χρησιμοποιήσετε το σύστημα εισαγωγής, συνίσταται να χρησιμοποιήσετε τη @ref{11c6,,importlib.util.module_from_spec()}, η οποία θα ορίσει τα διάφορα ελεγχόμενα από εισαγωγή χαρακτηριστικών σε κατάλληλες τιμές. Είναι επίσης δυνατό να χρησιμοποιηθεί ο κατασκευαστής @ref{11c7,,types.ModuleType} για τη δημιουργία modules απευθείας, αλλά αυτή η τεχνική είναι πιο επιρρεπής σε σφάλματα, καθώς τα περισσότερα χαρακτηριστικά πρέπει να οριστούν χειροκίνητα στο αντικείμενο του module αφού δημιουργηθεί κατά τη χρήση αυτής της προσέγγισης.

@cartouche
@quotation Προσοχή 
Με εξαίρεση το @ref{172f,,__name__}, `συνίσταται ανεπιφύλακτα' να βασίζεστε στο @ref{2555,,__spec__} και στα χαρακτηριστικά του αντί για οποιοδήποτε από τα άλλα μεμονωμένα χαρακτηριστικά που αναφέρονται σε αυτήν την υποενότητα. Σημειώστε ότι η ενημέρωση ενός χαρακτηριστικού στο @code{__spec__} δεν θα ενημερώσει το αντίστοιχο χαρακτηριστικό στο ίδιο το module:

@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__ (ιδιότητα της module)
@anchor{reference/datamodel module __name__}@anchor{172f}
@deffn {Ιδιότητα} module.__name__

Το όνομα που χρησιμοποιείται για την μοναδική αναγνώριση της ενότητας στο σύστημα εισαγωγής. Για ένα άμεσο εκτελούμενο module, αυτό θα οριστεί σε @code{"__main__"}.

Αυτό το χαρακτηριστικό πρέπει να οριστεί στο πλήρως προσδιορισμένο όνομα του module. Αναμένεται να ταιριάζει με την τιμή @ref{2556,,module.__spec__.name}.
@end deffn

@geindex __spec__ (ιδιότητα της module)
@anchor{reference/datamodel module __spec__}@anchor{2555}
@deffn {Ιδιότητα} module.__spec__

Μια εγγραφή της κατάστασης του module που σχετίζεται με το σύστημα εισαγωγής.

Ορίστε την παράμετρο @ref{245d,,module spec} που χρησιμοποιήθηκε κατά την εισαγωγή της ενότητας. Δείτε το @ref{2557,,Module specs} για περισσότερες λεπτομέρειες.


Added in version 3.4.

@end deffn

@geindex __package__ (ιδιότητα της module)
@anchor{reference/datamodel module __package__}@anchor{58c}
@deffn {Ιδιότητα} module.__package__

Το @ref{4c1,,package} στο οποίο ανήκει μια ενότητα.

Εάν το module είναι ανώτατου επιπέδου (δηλαδή, δεν αποτελεί μέρος κάποιου συγκεκριμένου πακέτου), τότε το χαρακτηριστικό θα πρέπει να οριστεί σε @code{'@w{'}} (η κενή συμβολοσειρά). Διαφορετικά, θα πρέπει να οριστεί το όνομα του πακέτου της ενότητας (το οποίο μπορεί να είναι ίσο με @ref{172f,,module.__name__} εάν η ίδια η ενότητα είναι πακέτο). Δείτε 
@geindex Python Enhancement Proposals; PEP 366
PEP 366@footnote{https://peps.python.org/pep-0366/} για περισσότερες λεπτομέρειες.

Αυτό το χαρακτηριστικό χρησιμοποιείται αντί για το @ref{172f,,__name__} για την υπολογισμό σαφών σχετικών εισαγωγών για τα κύρια modules. Η προεπιλεγμένη τιμή είναι @code{None} για modules που δημιουργούνται δυναμικά χρησιμοποιώντας τον κατασκευαστή @ref{11c7,,types.ModuleType} ∙ χρησιμοποιήστε το @ref{11c6,,importlib.util.module_from_spec()} για να βεβαιωθείτε ότι το χαρακτηριστικό έχει οριστεί σε @ref{1df,,str}.

Συνίσταται ανεπιφύλακτα να χρησιμοποιείτε την εντολή @ref{58d,,module.__spec__.parent} αντί για την εντολή @code{module.__package__}. Η εντολή @ref{58c,,__package__} χρησιμοποιείται πλέον μόνο ως εφεδρική εντολή εάν η εντολή @code{__spec__.parent} δεν έχει οριστεί και αυτή η εφεδρική διαδρομή έχει καταργηθεί.


Άλλαξε στην έκδοση 3.4: Αυτό το χαρακτηριστικό έχει πλέον την προεπιλεγμένη τιμή @code{None} για modules που δημιουργούνται δυναμικά χρησιμοποιώντας τον κατασκευαστή @ref{11c7,,types.ModuleType}. Προηγουμένως, το χαρακτηριστικό ήταν προαιρετικό.



Άλλαξε στην έκδοση 3.6: Η τιμή του @code{__package__} αναμένεται να είναι η ίδια με την τιμή του @ref{58d,,__spec__.parent}. Το @ref{58c,,__package__} χρησιμοποιείται πλέον μόνο ως εφεδρική τιμή κατά την ανάλυση εισαγωγής εάν δεν έχει οριστεί το @code{__spec__.parent}.



Άλλαξε στην έκδοση 3.10: Η @ref{907,,ImportWarning} γίνεται raised εάν η ανάλυση εισαγωγής επανέλθει σε @code{__package__} αντί για @ref{58d,,__spec__.parent}.



Άλλαξε στην έκδοση 3.12: Γίνεται @ref{2c9,,DeprecationWarning} αντί για @ref{907,,ImportWarning} κατά την επιστροφή στο @code{__package__} κατά την επίλυση της εισαγωγής.



Καταργήθηκε από την έκδοση 3.13, αφαιρέθηκε στην έκδοση 3.15: Το @code{__package__} θα πάψει να ορίζεται ή να λαμβάνεται υπόψη από το σύστημα εισαγωγής ή την τυπική βιβλιοθήκη.

@end deffn

@geindex __loader__ (ιδιότητα της module)
@anchor{reference/datamodel module __loader__}@anchor{2ff}
@deffn {Ιδιότητα} module.__loader__

Το αντικείμενο @ref{1c30,,loader} που χρησιμοποίησε ο μηχανισμός εισαγωγής για τη φόρτωση του module.

Αυτό το χαρακτηριστικό είναι κυρίως χρήσιμο για ενδοσκόπηση, αλλά μπορεί να χρησιμοποιηθεί για πρόσθετη λειτουργικότητα ειδικά για τον loader, για παράδειγμα για τη λήψη δεδομένων που σχετίζονται με έναν loader.

Το @code{__loader__} έχει προεπιλεγμένη τιμή @code{None} για modules που δημιουργούνται δυναμικά χρησιμοποιώντας τον κατασκευαστή @ref{11c7,,types.ModuleType} ∙ χρησιμοποιήστε τη @ref{11c6,,importlib.util.module_from_spec()} για να βεβαιωθείτε ότι το χαρακτηριστικό έχει οριστεί σε ένα αντικείμενο @ref{1c30,,loader}.

Συνίσταται ανεπιφύλακτα να χρησιμοποιείτε την εντολή @ref{300,,module.__spec__.loader} αντί για την εντολή @code{module.__loader__}.


Άλλαξε στην έκδοση 3.4: Αυτό το χαρακτηριστικό έχει πλέον την προεπιλεγμένη τιμή @code{None} για modules που δημιουργούνται δυναμικά χρησιμοποιώντας τον κατασκευαστή @ref{11c7,,types.ModuleType}. Προηγουμένως, το χαρακτηριστικό ήταν προαιρετικό.



Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.16: Ο ορισμός του @code{__loader__} σε ένα module χωρίς τον αντίστοιχο ορισμό του @code{__spec__.loader} θεωρείται παρωχημένος. Στην Python 3.16, το @code{__loader__} θα πάψει να ορίζεται η να λαμβάνεται υπόψη από το σύστημα εισαγωγής ή την τυπική βιβλιοθήκη.

@end deffn

@geindex __path__ (ιδιότητα της module)
@anchor{reference/datamodel module __path__}@anchor{2243}
@deffn {Ιδιότητα} module.__path__

Μια (ενδεχομένως κενή) @ref{8ff,,sequence} από συμβολοσειρές που απαριθμεί τις τοποθεσίες όπου θα εντοπιστούν τα submodules του πακέτου. Modules που δεν είναι πακέτα δεν θα πρέπει να έχουν το χαρακτηριστικό @code{__path__}. Δείτε το @ref{2558,,Χαρακτηριστικά __path__ στα modules} για περισσότερες λεπτομέρειες.

Συνίσταται `ισχυρά' να χρησιμοποιείτε το @ref{2559,,module.__spec__.submodule_search_locations} αντί για το @code{module.__path__}.
@end deffn

@geindex __file__ (ιδιότητα της module)
@anchor{reference/datamodel module __file__}@anchor{255a}
@deffn {Ιδιότητα} module.__file__

@code{__file__} is an optional attribute that
may or may not be set. Both attributes should be a @ref{1df,,str} when they
are available.

An optional attribute, @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{2551,,import system} may opt to leave it unset if it
has no semantic meaning (for example, a module loaded from a database).


Καταργήθηκε από την έκδοση 3.13, αφαιρέθηκε στην έκδοση 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.



Άλλαξε στην έκδοση 3.15: @code{__cached__} is no longer set.

@end deffn

@node Άλλα εγγράφως χαρακτηριστικά σε αντικείμενα μονάδων,Λεξικά Modules,Χαρακτηριστικά που σχετίζονται με εισαγωγή σε αντικείμενα modules,Modules<3>
@anchor{reference/datamodel other-writable-attributes-on-module-objects}@anchor{255b}
@subsubsection Άλλα εγγράφως χαρακτηριστικά σε αντικείμενα μονάδων


Εκτός από τα χαρακτηριστικά που σχετίζονται με τις εισαγωγές που αναφέρονται παραπάνω, τα αντικείμενα της μονάδας έχουν επίσης τα ακόλουθα δικαιολογημένα χαρακτηριστικά:

@geindex __doc__ (ιδιότητα της module)
@anchor{reference/datamodel module __doc__}@anchor{1de7}
@deffn {Ιδιότητα} module.__doc__

Η συμβολοσειρά τεκμηρίωσης του module, ή @code{None} αν δεν είναι διαθέσιμη. Δείτε επίσης: @ref{cf4,,__doc__ attributes}.
@end deffn

@geindex __annotations__ (ιδιότητα της module)
@anchor{reference/datamodel module __annotations__}@anchor{255c}
@deffn {Ιδιότητα} module.__annotations__

Ένα λεξικό που περιέχει @ref{110a,,variable annotations} που συλλέγονται κατά την εκτέλεση του σώματος του module.  Για τις βέλτιστες πρακτικές σχετικά με την εργασία με @code{__annotations__}, δείτε το @ref{6,,annotationlib}.


Άλλαξε στην έκδοση 3.14: Τα annotations πλέον @ref{872,,lazily evaluated}. Βλ. 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/}.

@end deffn

@geindex __annotate__ (ιδιότητα της module)
@anchor{reference/datamodel module __annotate__}@anchor{255d}
@deffn {Ιδιότητα} module.__annotate__

Η @ref{40a,,annotate function} για αυτό το module, ή @code{None} εάν το module δεν έχει annotations. Δείτε επίσης: @ref{1b95,,__annotate__} attributes.


Added in version 3.14.

@end deffn

@geindex __lazy_modules__ (ιδιότητα της module)
@anchor{reference/datamodel module __lazy_modules__}@anchor{17f}
@deffn {Ιδιότητα} module.__lazy_modules__

A container (an object implementing @ref{175c,,__contains__()}) of fully
qualified module name strings.  When defined
at module scope, any regular @ref{9da,,import} statement in that module whose
target module name appears in this container is treated as a
@ref{255e,,lazy import}, as if the @ref{177,,lazy} keyword had
been used.  Imports inside functions, class bodies, or
@ref{ad6,,try}/@ref{447,,except}/@ref{44c,,finally} blocks are unaffected.

See @ref{255f,,Compatibility via __lazy_modules__} for details and examples.


Added in version 3.15.

@end deffn

@node Λεξικά Modules,,Άλλα εγγράφως χαρακτηριστικά σε αντικείμενα μονάδων,Modules<3>
@anchor{reference/datamodel module-dictionaries}@anchor{2560}
@subsubsection Λεξικά Modules


Τα αντικείμενα module έχουν επίσης την ακόλουθη ειδική ιδιότητα μόνο για ανάγνωση:

@geindex __dict__ (χαρακτηριστικό module)

@geindex __dict__ (ιδιότητα της module)
@anchor{reference/datamodel module __dict__}@anchor{2561}
@deffn {Ιδιότητα} module.__dict__

Ο χώρος ονομάτων του module ως αντικείμενο λεξικού. Μοναδικά μεταξύ των χαρακτηριστικών που αναφέρονται εδώ, το @code{__dict__} δεν μπορεί να προσπελαστεί ως καθολική μεταβλητή από μέσα σε ένα module∙ μπορεί να προσπελαστεί μόνο ως χαρακτηριστικό σε αντικείμενα module.

Λόγω του τρόπου με τον οποίο η CPython διαγράφει τα λεξικά των modules το λεξικό του module θα διαγραφεί όταν το module πέσει εκτός πεδίου εφαρμογής, ακόμα κι αν το λεξικό εξακολουθεί να έχει ζωντανές αναφορές.  Για να αποφύγετε αυτό, αντιγράψτε το λεξικό ή κρατήστε το module ενώ χρησιμοποιείται απευθείας το λεξικό της.
@end deffn

@node Προσαρμοσμένες κλάσεις,Στιγμιότυπα κλάσης,Modules<3>,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel class-attrs-and-methods}@anchor{2562}@anchor{reference/datamodel custom-classes}@anchor{2563}
@subsubsection Προσαρμοσμένες κλάσεις


Οι τύποι προσαρμοσμένων κλάσεων δημιουργούνται συνήθως από ορισμούς κλάσεων (βλ. ενότητα @ref{167c,,Class definitions}).  Μια κλάση έχει έναν χώρο ονομάτων που υλοποιείται από ένα αντικείμενο λεξικού. Οι αναφορές χαρακτηριστικών κλάσης μεταφράζονται σε αναζητήσεις σε αυτό το λεξικό, π.χ., το @code{C.x} μεταφράζεται σε @code{C.__dict__["x"]} (αν και άλλα μέσα για τα οποία επιτρέπεται ο αριθμός των θέσεων υπάρχουν). Όταν το όνομα του χαρακτηριστικού δεν βρίσκεται εκεί, η αναζήτηση χαρακτηριστικών συνεχίζεται στις βασικές κλάσεις. Αυτή η αναζήτηση των βασικών κλάσεων χρησιμοποιεί τη σειρά ανάλυσης της μεθόδου C3 η οποία συμπεριφέρεται σωστά ακόμη και με την παρουσία δομών κληρονομικότητας «διαμάντι» όπου υπάρχουν πολλαπλές διαδρομές κληρονομικότητας που οδηγούν πίσω σε έναν κοινό πρόγονο. Πρόσθετε λεπτομέρειες για το C3 MRO που χρησιμοποιείται από την Python μπορείτε να βρείτε στην διεύθυνση @ref{184c,,The Python 2.3 Method Resolution Order}.

@geindex αντικείμενο;κλάση
@geindex αντικείμενο;στιγμιότυπο κλάσης
@geindex αντικείμενο;στιγμιότυπο
@geindex αντικείμενα κλάσης;κλήση
@geindex κοντέινερ
@geindex αντικείμενο;λεξικό
@geindex κλάση;χαρακτηριστικό

Όταν μια αναφορά χαρακτηριστικού κλάσης (για την κλάση @code{C}, ας πούμε) θα έδινε ένα αντικείμενο μεθόδου κλάσης, μετατρέπεται σε ένα αντικείμενο μεθόδου παρουσίας του οποίου το χαρακτηριστικό @ref{176b,,__self__} είναι @code{C}. Όταν θα έδινε ένα αντικείμενο @ref{666,,staticmethod}, μετατρέπεται στο αντικείμενο που είναι wrapped από το αντικείμενο στατικής μεθόδου. Δείτε την ενότητα @ref{100d,,Υλοποίηση Περιγραφέων} για έναν άλλο τρόπο με το οποίο τα χαρακτηριστικά που ανακτώνται από μια κλάση μπορεί να διαφέρουν από αυτά που πραγματικά περιέχονται στο @ref{1bf,,__dict__} της.

@geindex κλάση;χαρακτηριστικό;εκχώρηση

Οι αναθέσεις χαρακτηριστικών κλάσης ενημερώνουν το λεξικό της κλάσης, ποτέ το λεξικό μιας βασικής κλάσης.

@geindex αντικείμενα κλάσης;κλήση

Ένα αντικείμενο κλάσης μπορεί να κληθεί (δείτε παραπάνω) για να δώσει ένα στιγμιότυπο κλάσης (δείτε παρακάτω).

@menu
* Ειδικά χαρακτηριστικά:: 
* Ειδικές μέθοδοι:: 

@end menu

@node Ειδικά χαρακτηριστικά,Ειδικές μέθοδοι,,Προσαρμοσμένες κλάσεις
@anchor{reference/datamodel special-attributes}@anchor{2564}
@subsubsection Ειδικά χαρακτηριστικά


@geindex __name__ (χαρακτηριστικό κλάσης)
@geindex __module__ (χαρακτηριστικό κλάσης)
@geindex __dict__ (χαρακτηριστικό κλάσης)
@geindex __bases__ (χαρακτηριστικό κλάσης)
@geindex __base__ (χαρακτηριστικό κλάσης)
@geindex __doc__ (χαρακτηριστικό κλάσης)
@geindex __annotations__ (χαρακτηριστικό κλάσης)
@geindex __annotate__ (χαρακτηριστικό κλάσης)
@geindex __type_params__ (χαρακτηριστικό κλάσης)
@geindex __static_attributes__ (χαρακτηριστικό κλάσης)
@geindex __firstlineno__ (χαρακτηριστικό κλάσης)


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Χαρακτηριστικό

@tab

Έννοια

@item

@geindex __name__ (ιδιότητα της type)
@anchor{reference/datamodel type __name__}@anchor{184d}
@deffn {Ιδιότητα} type.__name__
@end deffn

@tab

Το όνομα της κλάσης, Δείτε επίσης: @ref{140e,,__name__ attributes}.

@item

@geindex __qualname__ (ιδιότητα της type)
@anchor{reference/datamodel type __qualname__}@anchor{2565}
@deffn {Ιδιότητα} type.__qualname__
@end deffn

@tab

Το @ref{1f19,,qualified name} της κλάσης. Δείτε επίσης: @ref{140d,,__qualname__ attributes}.

@item

@geindex __module__ (ιδιότητα της type)
@anchor{reference/datamodel type __module__}@anchor{80b}
@deffn {Ιδιότητα} type.__module__
@end deffn

@tab

Το όνομα του module στην οποία ορίστηκε η κλάση.

@item

@geindex __dict__ (ιδιότητα της type)
@anchor{reference/datamodel type __dict__}@anchor{101b}
@deffn {Ιδιότητα} type.__dict__
@end deffn

@tab

Μια @ref{189,,mapping proxy} που παρέχει μια προβολή μόνο για ανάγνωση του χώρου ονομάτων της κλάσης. Δείτε επίσης: @ref{1bf,,__dict__ attributes}.

@item

@geindex __bases__ (ιδιότητα της type)
@anchor{reference/datamodel type __bases__}@anchor{184e}
@deffn {Ιδιότητα} type.__bases__
@end deffn

@tab

Μια @ref{1ce,,tuple} που περιέχει τις βάσεις της κλάσης. Στις περισσότερες περιπτώσεις, για μια κλάση που ορίζεται ως @code{class X(A, B, C)}, το @code{X.__bases__} θα είναι ακριβώς ίσο με @code{(A, B, C)}.

@item

@geindex __base__ (ιδιότητα της type)
@anchor{reference/datamodel type __base__}@anchor{2566}
@deffn {Ιδιότητα} type.__base__
@end deffn

@tab

Η μοναδική βασική κλάση στην αλυσίδα κληρονομικότητας που είναι υπεύθυνη για τη διάταξη μνήμης των στιγμιοτύπων. Αυτό το χαρακτηριστικό αντιστοιχεί στο @ref{2567,,tp_base} σε επίπεδο C.

@item

@geindex __doc__ (ιδιότητα της type)
@anchor{reference/datamodel type __doc__}@anchor{2284}
@deffn {Ιδιότητα} type.__doc__
@end deffn

@tab

Η συμβολοσειρά τεκμηρίωσης της κλάσης ή @code{None} εάν δεν έχει οριστεί. Δεν κληρονομείται από υποκλάσεις.

@item

@geindex __annotations__ (ιδιότητα της type)
@anchor{reference/datamodel type __annotations__}@anchor{1a64}
@deffn {Ιδιότητα} type.__annotations__
@end deffn

@tab

Ένα λεξικό που περιέχει @ref{110a,,variable annotations} που συλλέγονται κατά την εκτέλεση του σώματος της κλάσης. Δείτε επίσης: @ref{66b,,__annotations__ attributes}.

Για βέλτιστες πρακτικές σχετικά με την εργασία με @ref{66b,,__annotations__}, δείτε το @ref{6,,annotationlib}. Χρησιμοποιήστε την @ref{66c,,annotationlib.get_annotations()} αντί να έχετε άμεση πρόσβαση σε αυτό το χαρακτηριστικό.

@cartouche
@quotation Προειδοποίηση 
Η πρόσβαση στο χαρακτηριστικό @code{__annotations__} απευθείας σε ένα αντικείμενο κλάσης ενδέχεται να επιστρέψει annotations για τη λάθος κλάση, συγκεκριμένα σε ορισμένες περιπτώσεις όπου η κλάση, η βασική της κλάση ή μια μετακλάση ορίζεται με το @code{from __future__ import annotations}. Δείτε το 
@geindex Python Enhancement Proposals; PEP 749#pep749-metaclasses
749@footnote{https://peps.python.org/pep-0749/#pep749-metaclasses} για λεπτομέρειες.

Αυτό το χαρακτηριστικό δεν υπάρχει σε ορισμένες ενσωματωμένες κλάσεις. Σε προσαρμοσμένες κλάσεις χωρίς @code{__annotations__}, είναι ένα κενό λεξικό.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.14: Τα annotations πλέον @ref{872,,lazily evaluated}. Βλ. 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/}.


@item

@geindex __annotate__() (μέθοδος της type)
@anchor{reference/datamodel type __annotate__}@anchor{1a8f}
@deffn {Μέθοδος} type.__annotate__ ()
@end deffn

@tab

Η @ref{40a,,annotate function} για αυτή την κλάση, ή @code{None} εάν η κλάση δεν έχει annotations. Δείτε επίσης: @ref{1b95,,__annotate__ attributes}.


Added in version 3.14.


@item

@geindex __type_params__ (ιδιότητα της type)
@anchor{reference/datamodel type __type_params__}@anchor{2568}
@deffn {Ιδιότητα} type.__type_params__
@end deffn

@tab

Μια @ref{1ce,,tuple} που περιέχει τις @ref{7a5,,type parameters} μιας @ref{86e,,generic class}.


Added in version 3.12.


@item

@geindex __static_attributes__ (ιδιότητα της type)
@anchor{reference/datamodel type __static_attributes__}@anchor{688}
@deffn {Ιδιότητα} type.__static_attributes__
@end deffn

@tab

Ένα @ref{1ce,,tuple} που περιέχει ονόματα χαρακτηριστικών αυτής της κλάσης τα οποία ανατίθενται μέσω του @code{self.X} από οποιαδήποτε συνάρτηση στο σώμα της.


Added in version 3.13.


@item

@geindex __firstlineno__ (ιδιότητα της type)
@anchor{reference/datamodel type __firstlineno__}@anchor{689}
@deffn {Ιδιότητα} type.__firstlineno__
@end deffn

@tab

Ο αριθμός γραμμής της πρώτης γραμμής του ορισμού της κλάσης, συμπεριλαμβανομένων των διακοσμητών. Ο ορισμός του χαρακτηριστικού @ref{80b,,__module__} αφαιρεί το @code{__firstlineno__} από το λεξικό του τύπου.


Added in version 3.13.


@item

@geindex __mro__ (ιδιότητα της type)
@anchor{reference/datamodel type __mro__}@anchor{2569}
@deffn {Ιδιότητα} type.__mro__
@end deffn

@tab

Η @ref{1ce,,tuple} των κλάσεων που λαμβάνονται υπόψη κατά την αναζήτηση βασικών κλάσεων κατά την ανάλυση της μεθόδου.

@end multitable


@node Ειδικές μέθοδοι,,Ειδικά χαρακτηριστικά,Προσαρμοσμένες κλάσεις
@anchor{reference/datamodel special-methods}@anchor{256a}
@subsubsection Ειδικές μέθοδοι


Εκτός από τα ειδικά χαρακτηριστικά που περιγράφονται παραπάνω, όλες οι κλάσεις Python έχουν επίσης διαθέσιμες τις ακόλουθες δύο μεθόδους:

@geindex mro() (μέθοδος της type)
@anchor{reference/datamodel type mro}@anchor{256b}
@deffn {Μέθοδος} type.mro ()

Αυτή η μέθοδος μπορεί να παρακαμφθεί από μια μετακλάση για να προσαρμόσετε τη σειρά ανάλυσης της μεθόδου για τις παρουσίες της.  Καλείται κατά την έναρξη της κλάσης και το αποτέλεσμα της αποθηκεύεται στο @ref{2569,,__mro__}.
@end deffn

@geindex __subclasses__() (μέθοδος της type)
@anchor{reference/datamodel type __subclasses__}@anchor{978}
@deffn {Μέθοδος} type.__subclasses__ ()

Κάθε κλάση διατηρεί μια λίστα με ασθενείς αναφορές στις άμεσες υποκλάσεις της. Αυτή η μέθοδος επιστρέφει μια λίστα με όλες αυτές τις αναφορές που εξακολουθούν να είναι ενεργές. Η λίστα είναι με σειρά ορισμού. Παράδειγμα:

@example
>>> class A: pass
>>> class B(A): pass
>>> A.__subclasses__()
[<class 'B'>]
@end example
@end deffn

@node Στιγμιότυπα κλάσης,Αντικείμενα εισόδου/εξόδου γνωστά και ως αντικείμενα αρχείου,Προσαρμοσμένες κλάσεις,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel id4}@anchor{256c}
@subsubsection Στιγμιότυπα κλάσης


@geindex αντικείμενο;στιγμιότυπο κλάσης
@geindex αντικείμενο;στιγμιότυπο
@geindex κλάση;στιγμιότυπο
@geindex στιγμιότυπο κλάσης;χαρακτηριστικό

Ένα στιγμιότυπο κλάσης δημιουργείται καλώντας ένα αντικείμενο κλάσης (δείτε παραπάνω).  Ένα στιγμιότυπο κλάσης έχει έναν χώρο ονομάτων που υλοποιείται ως λεξικό που είναι το πρώτο μέρος στο οποίο αναζητούνται οι αναφορές χαρακτηριστικών. Όταν ένα χαρακτηριστικό δεν βρίσκεται εκεί και η κλάση του στιγμιοτύπου έχει ένα χαρακτηριστικό με αυτό το όνομα, η αναζήτηση συνεχίζεται με τα χαρακτηριστικά κλάσης.  Εάν βρεθεί ένα χαρακτηριστικό κλάσης που είναι ένα αντικείμενο συνάρτησης που ορίζεται από το χρήστη, μετατρέπεται σε ένα αντικείμενο μεθόδου στιγμιοτύπου του οποίου το χαρακτηριστικό @ref{176b,,__self__} είναι το στιγμιότυπο.  Τα αντικείμενα στατικής μεθόδου και μεθόδου κλάσης μετασχηματίζονται επίσης· δείτε παραπάνω στην ενότητα «Κλάσεις».  Δείτε την ενότητα @ref{100d,,Υλοποίηση Περιγραφέων} για έναν άλλο τρόπο με τον οποίο τα χαρακτηριστικά μιας κλάσης που ανακτώνται μέσω των στιγμιοτύπων της μπορεί να διαφέρουν από τα αντικείμενα που είναι πραγματικά αποθηκευμένα στο @ref{1bf,,__dict__} της κλάσης.  Εάν δεν βρεθεί χαρακτηριστικό κλάσης και η κλάση του αντικειμένου έχει μια μέθοδο @ref{8e3,,__getattr__()}, αυτή καλείται να ικανοποιήσει την αναζήτηση.

@geindex στιγμιότυπο κλάσης;χαρακτηριστικό;εκχώρηση

Οι αναθέσεις χαρακτηριστικών ενημερώνουν το λεξικό της παρουσίας και πότε το λεξικό μιας κλάσης.  Εάν η κλάση έχει μια μέθοδο @ref{256d,,__setattr__()} ή @ref{256e,,__delattr__()}, καλείται  αντί  να ενημερώνεται απευθείας το λεξικό του στιγμιοτύπου.

@geindex αντικείμενο;αριθμητικό
@geindex αντικείμενο;ακολουθία
@geindex αντικείμενο;αντιστοίχιση

Τα στιγμιότυπα κλάσεων μπορούν να προσποιηθούν ότι είναι αριθμοί, ακολουθίες ή αντιστοιχίσεις εάν έχουν μεθόδους με συγκεκριμένα ειδικά ονόματα.  Δείτε την ενότητα @ref{102c,,Ειδικά ονόματα μεθόδων}.

@menu
* Ειδικά χαρακτηριστικά: Ειδικά χαρακτηριστικά<2>. 

@end menu

@node Ειδικά χαρακτηριστικά<2>,,,Στιγμιότυπα κλάσης
@anchor{reference/datamodel id5}@anchor{256f}
@subsubsection Ειδικά χαρακτηριστικά


@geindex __dict__ (χαρακτηριστικό στιγμιοτύπου)
@geindex __class__ (χαρακτηριστικό στιγμιοτύπου)

@geindex __class__ (ιδιότητα της object)
@anchor{reference/datamodel object __class__}@anchor{184f}
@deffn {Ιδιότητα} object.__class__

Η κλάση στην οποία ανήκει ένα στιγμιότυπο κλάσης.
@end deffn

@geindex __dict__ (ιδιότητα της object)
@anchor{reference/datamodel object __dict__}@anchor{1bf}
@deffn {Ιδιότητα} object.__dict__

Ένα λεξικό ή άλλο αντικείμενο αντιστοίχισης που χρησιμοποιείται για την αποθήκευση των (εγγράψιμων) χαρακτηριστικών ενός αντικειμένου. Δεν έχουν όλα τα στιγμιότυπα ένα χαρακτηριστικό @code{__dict__} ∙ δείτε την ενότητα για τα @ref{1cd,,__slots__} για περισσότερες λεπτομέρειες.
@end deffn

@node Αντικείμενα εισόδου/εξόδου γνωστά και ως αντικείμενα αρχείου,Εσωτερικοί τύποι,Στιγμιότυπα κλάσης,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel i-o-objects-also-known-as-file-objects}@anchor{2570}
@subsubsection Αντικείμενα εισόδου/εξόδου (γνωστά και ως αντικείμενα αρχείου)


@geindex ενσωματωμένη συνάρτηση;open
@geindex module;io
@geindex popen() (στο module os)
@geindex makefile() (μέθοδος socket)
@geindex sys.stdin
@geindex sys.stdout
@geindex sys.stderr
@geindex stdio
@geindex stdin (στο module sys)
@geindex stdout (στο module sys)
@geindex stderr (στο module sys)

Ένα αντικείμενο @ref{156c,,file object} αντιπροσωπεύει ένα ανοιχτό αρχείο.  Διάφορες συντομεύσεις είναι διαθέσιμες για τη δημιουργία αντικειμένων αρχείου: η ενσωματωμένη συνάρτηση @ref{32b,,open()}, και επίσης @ref{585,,os.popen()}, @ref{2571,,os.fdopen()}, και τη μέθοδο @ref{1548,,makefile()} των αντικειμένων socket (και ίσως από άλλες συναρτήσεις ή μεθόδους που παρέχονται από modules επέκτασης).

File objects implement common methods, listed below, to simplify usage in
generic code. They are expected to be @ref{2572,,Με τους Διαχειριστές Περιβάλλοντος Δήλωσης}.

Τα αντικείμενα @code{sys.stdin}, @code{sys.stdout} και @code{sys.stderr} αρχικοποιούνται για να αρχειοθετούν αντικείμενα που αντιστοιχούν στις τυπικές ροές εισόδου, εξόδου και σφαλμάτων του διερμηνέα· είναι όλα ανοιχτά σε λειτουργία κειμένου και επομένως ακολουθούν τη διεπαφή που ορίζεται από την αφηρημένη κλάση @ref{a84,,io.TextIOBase}.

@geindex read() (μέθοδος της file)
@anchor{reference/datamodel file read}@anchor{2573}
@deffn {Μέθοδος} file.read (size=-1, /)

Retrieve up to `size' data from the file. As a convenience if `size' is
unspecified or -1 retrieve all data available.
@end deffn

@geindex write() (μέθοδος της file)
@anchor{reference/datamodel file write}@anchor{2574}
@deffn {Μέθοδος} file.write (data, /)

Store `data' to the file.
@end deffn

@geindex close() (μέθοδος της file)
@anchor{reference/datamodel file close}@anchor{2575}
@deffn {Μέθοδος} file.close ()

Flush any buffers and close the underlying file.
@end deffn

@node Εσωτερικοί τύποι,,Αντικείμενα εισόδου/εξόδου γνωστά και ως αντικείμενα αρχείου,Η τυπική ιεραρχία τύπου
@anchor{reference/datamodel internal-types}@anchor{2576}
@subsubsection Εσωτερικοί τύποι


@geindex εσωτερικός τύπος
@geindex τύποι@comma{} εσωτερικό

Μερικοί τύποι που χρησιμοποιούνται εσωτερικά από τον διερμηνέα εκτίθενται στο χρήστη. Οι ορισμοί τους μπορεί να αλλάξουν με μελλοντικές εκδόσεις του διερμηνέα, αλλά αναφέρονται εδώ για πληρότητα.

@menu
* Αντικείμενα κώδικα:: 
* Πλαίσιο αντικειμένων:: 
* Αντικείμενα ανίχνευσης:: 
* Αντικείμενα τμηματοποίησης:: 
* Αντικείμενα στατικών μεθόδων:: 
* Αντικείμενα μεθόδων κλάσεων:: 

@end menu

@node Αντικείμενα κώδικα,Πλαίσιο αντικειμένων,,Εσωτερικοί τύποι
@anchor{reference/datamodel code-objects}@anchor{6eb}@anchor{reference/datamodel id6}@anchor{2577}
@subsubsection Αντικείμενα κώδικα


@geindex bytecode
@geindex αντικείμενο;code
@geindex code object

Τα αντικείμενα κώδικα αντιπροσωπεύουν `byte-compiled' εκτελέσιμο κώδικα Python, ή @ref{6b3,,bytecode}. Η διαφορά μεταξύ ενός αντικειμένου κώδικα και ενός αντικειμένου συνάρτησης είναι ότι το αντικείμενο συνάρτησης περιέχει μια ρητή αναφορά στα καθολικά της συνάρτησης (το module στο οποίο ορίστηκε), ενώ ένα αντικείμενο κώδικα δεν περιέχει πλαίσιο· επίσης, οι προεπιλεγμένες τιμές ορίσματος αποθηκεύονται στο αντικείμενο συνάρτησης, όχι στο αντικείμενο κώδικα (επειδή αντιπροσωπεύουν τιμές που υπολογίζονται κατά τον χρόνο εκτέλεσης).  Σε αντίθεση με τα αντικείμενα συνάρτησης, τα αντικείμενα κώδικα είναι αμετάβλητα και δεν περιέχουν αναφορές (άμεσα ή έμμεσα) σε μεταβλητά αντικείμενα.

@geindex co_argcount (χαρακτηριστικό code object)
@geindex co_posonlyargcount (χαρακτηριστικό code object)
@geindex co_kwonlyargcount (χαρακτηριστικό code object)
@geindex co_code (χαρακτηριστικό code object)
@geindex co_consts (χαρακτηριστικό code object)
@geindex co_filename (χαρακτηριστικό code object)
@geindex co_firstlineno (χαρακτηριστικό code object)
@geindex co_flags (χαρακτηριστικό code object)
@geindex co_name (χαρακτηριστικό code object)
@geindex co_names (χαρακτηριστικό code object)
@geindex co_nlocals (χαρακτηριστικό code object)
@geindex co_stacksize (χαρακτηριστικό code object)
@geindex co_varnames (χαρακτηριστικό code object)
@geindex co_cellvars (χαρακτηριστικό code object)
@geindex co_freevars (χαρακτηριστικό code object)
@geindex co_qualname (χαρακτηριστικό code object)

@menu
* Ειδικά χαρακτηριστικά μόνο για ανάγνωση: Ειδικά χαρακτηριστικά μόνο για ανάγνωση<2>. 
* Μέθοδοι σε αντικείμενα κώδικα:: 

@end menu

@node Ειδικά χαρακτηριστικά μόνο για ανάγνωση<2>,Μέθοδοι σε αντικείμενα κώδικα,,Αντικείμενα κώδικα
@anchor{reference/datamodel id7}@anchor{2578}
@subsubsection Ειδικά χαρακτηριστικά μόνο για ανάγνωση



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex co_name (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_name}@anchor{2579}
@deffn {Ιδιότητα} codeobject.co_name
@end deffn

@tab

Το όνομα της συνάρτησης

@item

@geindex co_qualname (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_qualname}@anchor{257a}
@deffn {Ιδιότητα} codeobject.co_qualname
@end deffn

@tab

Το πλήρως αναγνωρισμένο όνομα συνάρτησης


Added in version 3.11.


@item

@geindex co_argcount (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_argcount}@anchor{257b}
@deffn {Ιδιότητα} codeobject.co_argcount
@end deffn

@tab

Ο συνολικός αριθμός των θέσεων @ref{253c,,parameters} (συμπεριλαμβανομένων των παραμέτρων μόνο θέσης και παραμέτρων με προεπιλεγμένες τιμές) που έχει η συνάρτηση

@item

@geindex co_posonlyargcount (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_posonlyargcount}@anchor{257c}
@deffn {Ιδιότητα} codeobject.co_posonlyargcount
@end deffn

@tab

Ο αριθμός των @ref{253c,,parameters} θέσεως (συμπεριλαμβανομένων ορισμάτων με προεπιλεγμένες τιμές) που έχει η συνάρτηση

@item

@geindex co_kwonlyargcount (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_kwonlyargcount}@anchor{257d}
@deffn {Ιδιότητα} codeobject.co_kwonlyargcount
@end deffn

@tab

Ο αριθμός των @ref{253c,,parameters} λέξεων κλειδιών (συμπεριλαμβανομένων ορισμάτων με προεπιλεγμένες τιμές) που έχει η συνάρτηση

@item

@geindex co_nlocals (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_nlocals}@anchor{257e}
@deffn {Ιδιότητα} codeobject.co_nlocals
@end deffn

@tab

Ο αριθμός των @ref{2537,,local variables} που χρησιμοποιούνται από τη συνάρτηση (συμπεριλαμβανομένων των παραμέτρων)

@item

@geindex co_varnames (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_varnames}@anchor{257f}
@deffn {Ιδιότητα} codeobject.co_varnames
@end deffn

@tab

Μια @ref{1ce,,tuple} που περιέχει τα  ονόματα των τοπικών μεταβλητών στη συνάρτηση (ξεκινώντας με τα ονόματα των παραμέτρων)

@item

@geindex co_cellvars (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_cellvars}@anchor{2580}
@deffn {Ιδιότητα} codeobject.co_cellvars
@end deffn

@tab

Ένα @ref{1ce,,tuple} που περιέχει τα ονόματα των @ref{2537,,local variables} που αναφέρονται από τουλάχιστον ένα @ref{2581,,nested scope} μέσα στη συνάρτηση

@item

@geindex co_freevars (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_freevars}@anchor{2538}
@deffn {Ιδιότητα} codeobject.co_freevars
@end deffn

@tab

Ένα @ref{1ce,,tuple} που περιέχει τα ονόματα των @ref{1ab7,,free (closure) variables} που αναφέρεται από ένα @ref{2581,,nested scope} σε ένα εξωτερικό πλαίσιο. Δείτε επίσης το @ref{1675,,function.__closure__}.

Σημείωση: οι αναφορές σε καθολικά και ενσωματωμένα ονόματα `δεν' περιλαμβάνονται.

@item

@geindex co_code (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_code}@anchor{2582}
@deffn {Ιδιότητα} codeobject.co_code
@end deffn

@tab

Μια συμβολοσειρά που αντιπροσωπεύει την ακολουθία εντολών @ref{6b3,,bytecode} στη συνάρτηση

@item

@geindex co_consts (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_consts}@anchor{1abf}
@deffn {Ιδιότητα} codeobject.co_consts
@end deffn

@tab

Μια @ref{1ce,,tuple} που περιέχει τα literals που χρησιμοποιούνται από το @ref{6b3,,bytecode} στη συνάρτηση

@item

@geindex co_names (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_names}@anchor{2583}
@deffn {Ιδιότητα} codeobject.co_names
@end deffn

@tab

Μια @ref{1ce,,tuple} που περιέχει τα ονόματα που χρησιμοποιούνται από τον @ref{6b3,,bytecode} στην συνάρτηση

@item

@geindex co_filename (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_filename}@anchor{1712}
@deffn {Ιδιότητα} codeobject.co_filename
@end deffn

@tab

Το όνομα του αρχείου από το οποίο συντάχθηκε ο κώδικας

@item

@geindex co_firstlineno (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_firstlineno}@anchor{2584}
@deffn {Ιδιότητα} codeobject.co_firstlineno
@end deffn

@tab

Ο αριθμός γραμμής της πρώτης γραμμής της συνάρτησης

@item

@geindex co_stacksize (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_stacksize}@anchor{2585}
@deffn {Ιδιότητα} codeobject.co_stacksize
@end deffn

@tab

Το απαιτούμενο μέγεθος στοίβας του αντικειμένου κώδικα

@item

@geindex co_flags (ιδιότητα της codeobject)
@anchor{reference/datamodel codeobject co_flags}@anchor{1afc}
@deffn {Ιδιότητα} codeobject.co_flags
@end deffn

@tab

Μια @ref{326,,integer} που κωδικοποιεί έναν αριθμό flags για τον διερμηνέα.

@end multitable


@geindex αντικείμενο;γεννήτρια

Τα ακόλουθα flag bits ορίζονται για @ref{1afc,,co_flags}: το bit @code{0x04} ορίζεται εάν η συνάρτηση χρησιμοποιεί τη σύνταξη @code{*arguments} για να αποδεχτεί έναν αυθαίρετο αριθμό ορισμάτων θέσης· το bit @code{0x08} ορίζεται εάν η συνάρτηση χρησιμοποιεί τη σύνταξη @code{**keywords} για να δέχεται αυθαίρετα ορίσματα λέξεων-κλειδιών· το bit @code{0x20} ορίζεται εάν η συνάρτηση είναι γεννήτρια. Δείτε το @ref{2586,,Code Objects Bit Flags} για λεπτομέρειες σχετικά με τη σημασιολογία κάθε σημαίας που μπορεί να υπάρχει.

Οι δηλώσεις μελλοντικών δυνατοτήτων (για παράδειγμα, @code{from __future__ import division}) χρησιμοποιούν επίσης bits στο @ref{1afc,,co_flags} για να υποδείξουν εάν ένα αντικείμενο κώδικα έχει συνταχθεί με μια συγκεκριμένη ενεργοποιημένη δυνατότητα. Δείτε το @ref{2587,,compiler_flag}.

Άλλα bits στο @ref{1afc,,co_flags} είναι δεσμευμένα για εσωτερική χρήση.

@geindex κείμενο τεκμηρίωσης

Εάν ένα αντικείμενο κώδικα αντιπροσωπεύει μια συνάρτηση και έχει μια συμβολοσειρά τεκμηρίωσης, το bit @ref{2588,,CO_HAS_DOCSTRING} ορίζεται στο @ref{1afc,,co_flags} και το πρώτο στοιχείο στο @ref{1abf,,co_consts} είναι η συμβολοσειρά τεκμηρίωσης της συνάρτησης.

@node Μέθοδοι σε αντικείμενα κώδικα,,Ειδικά χαρακτηριστικά μόνο για ανάγνωση<2>,Αντικείμενα κώδικα
@anchor{reference/datamodel methods-on-code-objects}@anchor{2589}
@subsubsection Μέθοδοι σε αντικείμενα κώδικα


@geindex co_positions() (μέθοδος της codeobject)
@anchor{reference/datamodel codeobject co_positions}@anchor{9b2}
@deffn {Μέθοδος} codeobject.co_positions ()

Επιστρέφει έναν iterable πάνω από τις θέσεις του πηγαίου κώδικα κάθε εντολής @ref{6b3,,bytecode} στο αντικείμενο κώδικα.

Ο iterator επιστρέφει @ref{1ce,,tuple}s που περιέχει το @code{(start_line, end_line, start_column, end_column)}. Η πλειάδα `i-th' αντιστοιχεί στη θέση του πηγαίου κώδικα που μεταγλωττίστηκε στην εντολή `i-th'. Οι πληροφορίες στηλών είναι μετατοπίσεις utf-8 byte με ευρετήριο 0 στη δεδομένη γραμμή πηγής.

Αυτές οι πληροφορίες θέσης μπορεί να λείπουν. Μια μη εξαντλητική λίστα περιπτώσεων όπου αυτό μπορεί να συμβεί:


@itemize -

@item 
Εκτέλεση του διερμηνέα με @ref{178,,-X} @code{no_debug_ranges}.

@item 
Φόρτωση ενός αρχείου pyc που έχει μεταγλωττιστεί κατά τη χρήση του @ref{178,,-X} @code{no_debug_ranges}.

@item 
Τοποθετεί τις πλειάδες που αντιστοιχούν σε τεχνικές οδηγίες.

@item 
Αριθμοί γραμμών και στηλών που δεν μπορούν να αναπαρασταθούν λόγω περιορισμών για την υλοποίηση.
@end itemize

Όταν συμβαίνει αυτό, ορισμένα η όλα τα πολλαπλά στοιχεία μπορεί να είναι @ref{a65,,None}.


Added in version 3.11.


@cartouche
@quotation Σημείωση 
Αυτή η δυνατότητα απαιτεί αποθήκευση θέσεων στηλών σε αντικείμενα κώδικα που μπορεί να οδηγήσει σε μικρή αύξηση της χρήσης δίσκου των μεταγλωττισμένων αρχείων Python ή της χρήσης μνήμης διερμηνέα. Για να αποφύγετε την αποθήκευση των επιπλέον πληροφοριών ή/και να απενεργοποιήσετε την εκτύπωση των επιπλέον πληροφοριών παρακολούθησης, μπορεί να χρησιμοποιηθεί η σημαία (flag) γραμμής εντολών @ref{178,,-X} @code{no_debug_ranges} ή η μεταβλητή περιβάλλοντος 
@geindex PYTHONNODEBUGRANGES
@geindex μεταβλητή περιβάλλοντος; PYTHONNODEBUGRANGES
@ref{9b5,,PYTHONNODEBUGRANGES}.
@end quotation
@end cartouche
@end deffn

@geindex co_lines() (μέθοδος της codeobject)
@anchor{reference/datamodel codeobject co_lines}@anchor{32d}
@deffn {Μέθοδος} codeobject.co_lines ()

Επιστρέφει έναν iterator που παράγει πληροφορίες σχετικά με διαδοχικά εύρη @ref{6b3,,bytecode}s. Κάθε στοιχείο που αποδίδεται είναι μια @code{(start, end, lineno)} @ref{1ce,,tuple}:


@itemize *

@item 
Το @code{start} (ένα @ref{326,,int}) αναπαριστά τη μετατόπιση (συμπεριλαμβανομένης) της έναρξης του εύρους @ref{6b3,,bytecode}

@item 
Το @code{end} (ένα @ref{326,,int}) αναπαριστά τη μετατόπιση (αποκλειστική) του τέλους του εύρους @ref{6b3,,bytecode}

@item 
Το @code{lineno} είναι ένα @ref{326,,int} που αναπαριστά τον αριθμό γραμμής του εύρους @ref{6b3,,bytecode} ή @code{None} εάν τα bytecodes στη δεδομένη περιοχή δεν έχουν αριθμό γραμμής
@end itemize

Τα στοιχεία που θα προκύψουν θα έχουν τις ακόλουθες ιδιότητες:


@itemize *

@item 
Το πρώτο εύρος που θα προκύψει θα έχει ένα @code{start} 0.

@item 
Τα εύρη @code{(start, end)} θα είναι μη φθίνουσες και διαδοχικές. Δηλαδή, για οποιοδήποτε ζεύγος @ref{1ce,,tuple}s, το @code{start} του δεύτερου θα είναι ίσο με το το @code{end} του πρώτου.

@item 
Κανένα εύρος δεν θα είναι προς τα πίσω: @code{end >= start} για όλες τις τριάδες.

@item 
Το τελευταίο @ref{1ce,,tuple} που θα αποφέρει θα έχει @code{end} ίσο με το μέγεθος του @ref{6b3,,bytecode}.
@end itemize

Εύρος μηδενικού πλάτους, όπου @code{start == end}, επιτρέπονται. Τα εύρη μηδενικού πλάτους χρησιμοποιούνται για γραμμές που υπάρχουν στον πηγαίο κώδικα, αλλά έχουν εξαλειφθεί από τον μεταγλωττιστή @ref{6b3,,bytecode}.


Added in version 3.10.



@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 626

@item PEP 626@footnote{https://peps.python.org/pep-0626/} - Ακριβείς αριθμοί γραμμών για εντοπισμό σφαλμάτων και άλλα εργαλεία.

Το PEP που εισήγαγε τη μέθοδο @code{co_lines()}.
@end table

@end deffn

@geindex replace() (μέθοδος της codeobject)
@anchor{reference/datamodel codeobject replace}@anchor{258a}
@deffn {Μέθοδος} codeobject.replace (**kwargs)

Επιστρέφει ένα αντίγραφο του αντικειμένου κώδικα με νέες τιμές για τα καθορισμένα πεδία.

Τα αντικείμενα κώδικα υποστηρίζονται επίσης από τη γενική συνάρτηση @ref{45a,,copy.replace()}.


Added in version 3.8.

@end deffn

@node Πλαίσιο αντικειμένων,Αντικείμενα ανίχνευσης,Αντικείμενα κώδικα,Εσωτερικοί τύποι
@anchor{reference/datamodel frame-objects}@anchor{acd}@anchor{reference/datamodel id8}@anchor{258b}
@subsubsection Πλαίσιο αντικειμένων


@geindex αντικείμενο;frame

Τα αντικείμενα πλαισίου αναπαριστούν πλαίσια εκτέλεσης.  Μπορούν να εμφανίζονται σε @ref{eba,,traceback objects}, και επίσης μεταβιβάζονται σε καταχωρημένες συναρτήσεις ανίχνευσης.

@geindex f_back (χαρακτηριστικό frame)
@geindex f_code (χαρακτηριστικό frame)
@geindex f_globals (χαρακτηριστικό frame)
@geindex f_locals (χαρακτηριστικό frame)
@geindex f_lasti (χαρακτηριστικό frame)
@geindex f_builtins (χαρακτηριστικό frame)
@geindex f_generator (χαρακτηριστικό frame)

@menu
* Ειδικά χαρακτηριστικά μόνο για ανάγνωση: Ειδικά χαρακτηριστικά μόνο για ανάγνωση<3>. 
* Ειδικά εγγράψιμα χαρακτηριστικά: Ειδικά εγγράψιμα χαρακτηριστικά<2>. 
* Μέθοδοι αντικειμένων πλαισίου:: 

@end menu

@node Ειδικά χαρακτηριστικά μόνο για ανάγνωση<3>,Ειδικά εγγράψιμα χαρακτηριστικά<2>,,Πλαίσιο αντικειμένων
@anchor{reference/datamodel id9}@anchor{258c}
@subsubsection Ειδικά χαρακτηριστικά μόνο για ανάγνωση



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex f_back (ιδιότητα της frame)
@anchor{reference/datamodel frame f_back}@anchor{b6b}
@deffn {Ιδιότητα} frame.f_back
@end deffn

@tab

Δείχνει το προηγούμενο πλαίσιο στοίβας (προς από εκεί  που καλείται), ή @code{None} αν αυτό είναι το πλαίσιο της κάτω στοίβας

@item

@geindex f_code (ιδιότητα της frame)
@anchor{reference/datamodel frame f_code}@anchor{258d}
@deffn {Ιδιότητα} frame.f_code
@end deffn

@tab

Το αντικείμενο @ref{6eb,,code object} εκτελείται σε αυτό το πλαίσιο. Η πρόσβαση σε αυτό το χαρακτηριστικό κάνει raise σε ένα συμβάν @ref{1e65,,auditing event} @code{object.__getattr__} με ορίσματα @code{obj} και @code{"f_code"}.

@item

@geindex f_locals (ιδιότητα της frame)
@anchor{reference/datamodel frame f_locals}@anchor{28d}
@deffn {Ιδιότητα} frame.f_locals
@end deffn

@tab

Η αντιστοίχιση που χρησιμοποιείται από το πλαίσιο για την αναζήτηση @ref{2537,,local variables}. Εάν το πλαίσιο αναφέρεται σε ένα @ref{6ad,,optimized scope}, αυτό μπορεί να επιστρέψει ένα αντικείμενο proxy write-through.


Άλλαξε στην έκδοση 3.13: Επιστρέφει ένα proxy για βελτιστοποιημένα πλαίσια.


@item

@geindex f_globals (ιδιότητα της frame)
@anchor{reference/datamodel frame f_globals}@anchor{258e}
@deffn {Ιδιότητα} frame.f_globals
@end deffn

@tab

Το λεξικό που χρησιμοποιείται από το πλαίσιο για την αναζήτηση @ref{2537,,global variables}

@item

@geindex f_builtins (ιδιότητα της frame)
@anchor{reference/datamodel frame f_builtins}@anchor{258f}
@deffn {Ιδιότητα} frame.f_builtins
@end deffn

@tab

Το λεξικό που χρησιμοποιείται από το πλαίσιο για την αναζήτηση @ref{2537,,built-in (intrinsic) names}

@item

@geindex f_lasti (ιδιότητα της frame)
@anchor{reference/datamodel frame f_lasti}@anchor{c5e}
@deffn {Ιδιότητα} frame.f_lasti
@end deffn

@tab

Η «ακριβής εντολή» του αντικειμένου πλαισίου (αυτό είναι ένα ευρετήριο στη συμβολοσειρά @ref{6b3,,bytecode} του αντικειμένου @ref{6eb,,code object})

@item

@geindex f_generator (ιδιότητα της frame)
@anchor{reference/datamodel frame f_generator}@anchor{2590}
@deffn {Ιδιότητα} frame.f_generator
@end deffn

@tab

Το αντικείμενο @ref{1409,,generator} ή @ref{8a2,,coroutine} που κατέχει αυτό το πλαίσιο, ή @code{None} εάν το πλαίσιο είναι μια κανονική συνάρτηση.


Added in version 3.14.


@end multitable


@geindex f_trace (χαρακτηριστικό frame)
@geindex f_trace_lines (χαρακτηριστικό frame)
@geindex f_trace_opcodes (χαρακτηριστικό frame)
@geindex f_lineno (χαρακτηριστικό frame)

@node Ειδικά εγγράψιμα χαρακτηριστικά<2>,Μέθοδοι αντικειμένων πλαισίου,Ειδικά χαρακτηριστικά μόνο για ανάγνωση<3>,Πλαίσιο αντικειμένων
@anchor{reference/datamodel id10}@anchor{2591}
@subsubsection Ειδικά εγγράψιμα χαρακτηριστικά



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex f_trace (ιδιότητα της frame)
@anchor{reference/datamodel frame f_trace}@anchor{2592}
@deffn {Ιδιότητα} frame.f_trace
@end deffn

@tab

Εάν όχι @code{None}, αυτή είναι μια συνάρτηση που καλείται για διάφορα συμβάντα κατά την εκτέλεση κώδικα (αυτό χρησιμοποιείται από προγράμματα εντοπισμού σφαλμάτων). Κανονικά ένα συμβάν ενεργοποιείται για κάθε νέα γραμμή πηγαίου κώδικα (δείτε @ref{f9b,,f_trace_lines}).

@item

@geindex f_trace_lines (ιδιότητα της frame)
@anchor{reference/datamodel frame f_trace_lines}@anchor{f9b}
@deffn {Ιδιότητα} frame.f_trace_lines
@end deffn

@tab

Ορίστε αυτό το χαρακτηριστικό σε @ref{ef5,,False} για να απενεργοποιήσετε την ενεργοποίηση ενός συμβάντος ανίχνευσης για κάθε γραμμή πηγαίου κώδικα.

@item

@geindex f_trace_opcodes (ιδιότητα της frame)
@anchor{reference/datamodel frame f_trace_opcodes}@anchor{f9c}
@deffn {Ιδιότητα} frame.f_trace_opcodes
@end deffn

@tab

Ορίζει αυτό το χαρακτηριστικό σε @ref{fcc,,True} για να επιτρέψετε να ζητηθούν συμβάντα ανά opcode. Σημειώστε ότι αυτό μπορεί να οδηγήσει σε απροσδιόριστη συμπεριφορά διερμηνέα εάν οι εξαιρέσεις που προκύπτουν από τη συνάρτηση ανίχνευσης διαφεύγουν στη συνάρτηση που παρακολουθείται.

@item

@geindex f_lineno (ιδιότητα της frame)
@anchor{reference/datamodel frame f_lineno}@anchor{b8d}
@deffn {Ιδιότητα} frame.f_lineno
@end deffn

@tab

Ο τρέχων αριθμός γραμμής του πλαισίου – η εγγραφή σε αυτό μέσα από μια συνάρτηση ανίχνευσης μεταβαίνει στη δεδομένη γραμμή (μόνο για το πιο κάτω πλαίσιο).  Ένας εντοπισμός σφαλμάτων μπορεί να εφαρμόσει μια εντολή Μετάβασης (γνωστή και ως Ορισμός Επόμενης Δήλωσης) γράφοντας σε αυτό το χαρακτηριστικό.

@end multitable


@node Μέθοδοι αντικειμένων πλαισίου,,Ειδικά εγγράψιμα χαρακτηριστικά<2>,Πλαίσιο αντικειμένων
@anchor{reference/datamodel frame-object-methods}@anchor{2593}
@subsubsection Μέθοδοι αντικειμένων πλαισίου


Τα αντικείμενα πλαισίου υποστηρίζουν μια μέθοδο:

@geindex clear() (μέθοδος της frame)
@anchor{reference/datamodel frame clear}@anchor{784}
@deffn {Μέθοδος} frame.clear ()

Αυτή η μέθοδος διαγράφει όλες τις αναφορές σε @ref{2537,,local variables} που τηρούνται από το πλαίσιο.  Επίσης, εάν το πλαίσιο ανήκε σε ένα @ref{1409,,generator}, η γεννήτρια έχει οριστικοποιηθεί.  Αυτό βοηθά στη διακοπή των κύκλων αναφοράς που περιλαμβάνουν αντικείμενα πλαισίου (για παράδειγμα, όταν γίνεται catch μια @ref{1e1e,,exception} και αποθηκεύετε το @ref{eba,,traceback} για μετέπειτα χρήση).

Η @ref{30d,,RuntimeError} γίνεται raise εάν το πλαίσιο εκτελείται ή αναστέλλεται.


Added in version 3.4.



Άλλαξε στην έκδοση 3.13: Η προσπάθεια εκκαθάρισης ενός ανασταλμένου πλαισίου κάνει raise @ref{30d,,RuntimeError} (όπως πάντα συμβαίνει για τα εκτελούμενα πλαίσια).

@end deffn

@node Αντικείμενα ανίχνευσης,Αντικείμενα τμηματοποίησης,Πλαίσιο αντικειμένων,Εσωτερικοί τύποι
@anchor{reference/datamodel id11}@anchor{2594}@anchor{reference/datamodel traceback-objects}@anchor{eba}
@subsubsection Αντικείμενα ανίχνευσης


@geindex αντικείμενο;traceback
@geindex stack;trace
@geindex exception;χειριστής
@geindex execution;stack
@geindex exc_info (στο module sys)
@geindex last_traceback (στο module sys)
@geindex sys.exc_info
@geindex sys.exception
@geindex sys.last_traceback

Τα αντικείμενα ανίχνευσης αντιπροσωπεύουν το ίχνος στοίβας μιας @ref{2261,,exception}. Ένα αντικείμενο traceback δημιουργείται σιωπηρά όταν εμφανίζεται μια εξαίρεση και μπορεί επίσης να δημιουργηθεί ρητά καλώντας το @ref{eb8,,types.TracebackType}.


Άλλαξε στην έκδοση 3.7: Τα αντικείμενα Traceback μπορούν τώρα να δημιουργηθούν ρητά από τον κώδικα Python.


Για εμμέσως δημιουργημένα tracebacks, όταν η αναζήτηση για έναν χειριστή εξαιρέσεων ξετυλίγει τη στοίβα εκτέλεσης, σε κάθε επίπεδο ξετυλίγματος εισάγεται ένα αντικείμενο traceback μπροστά από το τρέχον traceback.  Όταν εισάγεται ένα χειριστής εξαίρεσης, το ίχνος στοίβας διατίθεται στο πρόγραμμα. (Δείτε την ενότητα @ref{ad6,,The try statement}.) Είναι προσβάσιμο ως το τρίτο στοιχείο της πλειάδα που επιστρέφεται από το @ref{a7a,,sys.exc_info()} και έχει ως το χαρακτηριστικό @ref{166b,,__traceback__} της εξαίρεσης που έχει εντοπιστεί.

Όταν το πρόγραμμα δεν περιέχει ον κατάλληλο χειριστή, το ίχνος στοίβας γράφεται (όμορφα μορφοποιημένο) στην τυπική ροή σφαλμάτων· εάν ο διερμηνέα είναι διαδραστικός, διατίθεται επίσης στον χρήστη ως @ref{8d1,,sys.last_traceback}.

Για ρητά δημιουργημένα tracebacks, εναπόκειται στον δημιουργό του traceback να καθορίσει πως θα πρέπει να συνδεθούν, τα χαρακτηριστικά @ref{eb9,,tb_next} για να σχηματίσουν ένα ίχνος πλήρους στοίβας.

@geindex tb_frame (χαρακτηριστικό traceback)
@geindex tb_lineno (χαρακτηριστικό traceback)
@geindex tb_lasti (χαρακτηριστικό traceback)
@geindex δήλωση;try

Ειδικά χαρακτηριστικά μόνο για ανάγνωση:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex tb_frame (ιδιότητα της traceback)
@anchor{reference/datamodel traceback tb_frame}@anchor{2595}
@deffn {Ιδιότητα} traceback.tb_frame
@end deffn

@tab

Δείχνει την εκτέλεση @ref{acd,,frame} του τρέχοντος επιπέδου.

Η πρόσβαση σε αυτό το χαρακτηριστικό κάνει raise ένα @ref{1e65,,auditing event} @code{object.__getattr__} με ορίσματα @code{obj} και @code{"tb_frame"}.

@item

@geindex tb_lineno (ιδιότητα της traceback)
@anchor{reference/datamodel traceback tb_lineno}@anchor{2596}
@deffn {Ιδιότητα} traceback.tb_lineno
@end deffn

@tab

Δίνει τον αριθμό γραμμής όπου προέκυψε η εξαίρεση

@item

@geindex tb_lasti (ιδιότητα της traceback)
@anchor{reference/datamodel traceback tb_lasti}@anchor{2597}
@deffn {Ιδιότητα} traceback.tb_lasti
@end deffn

@tab

Δηλώνει την «ακριβή οδηγία».

@end multitable


Ο αριθμός γραμμής και η τελευταία εντολή στο traceback μπορεί να διαφέρουν από τον αριθμό γραμμής του αντικειμένου @ref{acd,,frame object} εάν η εξαίρεση εμφανίστηκε σε μια πρόταση @ref{ad6,,try} χωρίς αντιστοίχιση εκτός από τον όρο ή με έναν όρο @ref{44c,,finally}.

@geindex tb_next (χαρακτηριστικό traceback)

@geindex tb_next (ιδιότητα της traceback)
@anchor{reference/datamodel traceback tb_next}@anchor{eb9}
@deffn {Ιδιότητα} traceback.tb_next

Το ειδικό εγγράψιμο χαρακτηριστικό @code{tb_next} είναι το επόμενο επίπεδο στο ίχνος στοίβας (προς το πλαίσιο όπου σημειώθηκε η εξαίρεση), ή @code{None} εάν δεν υπάρχει επόμενο επίπεδο.


Άλλαξε στην έκδοση 3.7: Αυτό το χαρακτηριστικό είναι τώρα εγγράψιμο

@end deffn

@node Αντικείμενα τμηματοποίησης,Αντικείμενα στατικών μεθόδων,Αντικείμενα ανίχνευσης,Εσωτερικοί τύποι
@anchor{reference/datamodel slice-objects}@anchor{2598}
@subsubsection Αντικείμενα τμηματοποίησης


@geindex ενσωματωμένη συνάρτηση;slice

Τα αντικείμενα τμηματοποίησης χρησιμοποιούνται για να αναπαραστήσουν τμήματα για μεθόδους @ref{787,,__getitem__()}.  Δημιουργούνται επίσης από την ενσωματωμένη συνάρτηση @ref{1d0,,slice()}.


Added in version 3.15: The @ref{1d0,,slice()} type now supports @ref{2599,,subscription}. For
example, @code{slice[float]} may be used in type annotations to indicate a slice
containing @ref{327,,float} objects.


@geindex start (χαρακτηριστικό αντικειμένου slice)
@geindex stop (χαρακτηριστικό αντικειμένου slice)
@geindex step (χαρακτηριστικό αντικειμένου slice)

Ειδικά χαρακτηριστικά μόνο για ανάγνωση: το @ref{259a,,start} είναι το κάτω όριο∙ το @ref{259b,,stop} είναι το άνω όριο∙ και το @ref{259c,,step} είναι το βήμα∙ κάθε ένα είναι @code{None} αν παραλειφθεί.  Τα χαρακτηριστικά μπορούν να έχουν οποιονδήποτε τύπο.

Τα αντικείμενα slice υποστηρίζουν μια μέθοδο:

@geindex indices() (μέθοδος της slice)
@anchor{reference/datamodel slice indices}@anchor{13cf}
@deffn {Μέθοδος} slice.indices (self, length)

Αυτή η μέθοδος παίρνει ένα μόνο ακέραιο όρισμα `length' και υπολογίζει πληροφορίες σχετικά το slice που θα περιέγραφε το αντικείμενο slice εάν εφαρμοστεί σε μια ακολουθία στοιχείων `length'.  Επιστρέφει μια πλειάδα τριών ακεραίων αριθμών∙ αντίστοιχα αυτοί είναι δείκτες `start' και `stop' και το `step' ή το μήκος του βήματος του τμήματος. Οι δείκτες που λείπουν ή είναι εκτός ορίων αντιμετωπίζονται με τρόπο που συνάδει με τα κανονικά slices.
@end deffn

@node Αντικείμενα στατικών μεθόδων,Αντικείμενα μεθόδων κλάσεων,Αντικείμενα τμηματοποίησης,Εσωτερικοί τύποι
@anchor{reference/datamodel static-method-objects}@anchor{259d}
@subsubsection Αντικείμενα στατικών μεθόδων


Τα αντικείμενα στατικής μεθόδου παρέχουν έναν τρόπο εξουδετέρωσης του μετασχηματισμού αντικειμένων συνάρτησης σε αντικείμενα μεθόδου που περιγράφονται παραπάνω. Ένα αντικείμενο στατικής μεθόδου είναι ένα περιτύλιγμα γύρω από οποιοδήποτε άλλο αντικείμενο , συνήθως ένα αντικείμενο μεθόδου που ορίζεται από το χρήστη. Όταν ένα αντικείμενο στατικής μεθόδου ανακτάται από μια κλάση ή ένα στιγμιότυπο κλάσης, το αντικείμενο που επιστρέφεται στην πραγματικότητα είναι το τυλιγμένο αντικείμενο, το οποίο δεν υπόκειται σε περαιτέρω μετασχηματισμό. Τα αντικείμενα στατικής μεθόδου μπορούν επίσης να κληθούν. Τα αντικείμενα στατικής μεθόδου δημιουργούνται από τον ενσωματωμένο κατασκευαστή @ref{666,,staticmethod()}.

@node Αντικείμενα μεθόδων κλάσεων,,Αντικείμενα στατικών μεθόδων,Εσωτερικοί τύποι
@anchor{reference/datamodel class-method-objects}@anchor{259e}
@subsubsection Αντικείμενα μεθόδων κλάσεων


Ένα αντικείμενο μεθόδου κλάσης, όπως ένα αντικείμενο στατικής μεθόδου, είναι ένα περιτύλιγμα γύρω από ένα άλλο αντικείμενο που αλλάζει τον τρόπο με τον οποίο ανακτάται αυτό το αντικείμενο από κλάσεις και στιγμιότυπα κλάσεων. Η συμπεριφορά των αντικειμένων της μεθόδου κλάσης κατά την ανάκτηση αυτή περιγράφεται παραπάνω, στην ενότητα @ref{2297,,«instance methods»}. Τα αντικείμενα της μεθόδου κλάσης δημιουργούνται από τον ενσωματωμένο κατασκευαστή @ref{69a,,classmethod()}.

@node Ειδικά ονόματα μεθόδων,Coroutines,Η τυπική ιεραρχία τύπου,Μοντέλο Δεδομένων
@anchor{reference/datamodel special-method-names}@anchor{259f}@anchor{reference/datamodel specialnames}@anchor{102c}
@subsection Ειδικά ονόματα μεθόδων


@geindex τελεστής;υπερφόρτωση
@geindex __getitem__() (μέθοδος αντικειμένου αντιστοίχισης)

Μια κλάση μπορεί να εφαρμόσει ορισμένες πράξεις που καλούνται από ειδική σύνταξη (όπως αριθμητικές πράξεις ή εγγραφή και κοπή) ορίζονται μεθόδους με ειδικά ονόματα. Αυτή είναι η προσέγγιση της Python για το `operator overloading', επιτρέποντας στις κλάσεις να ορίσουν τη δική τους συμπεριφορά σε σχέση με τους τελεστές γλώσσας.  Για παράδειγμα, εάν μια κλάση ορίζει μια μέθοδο με το όνομα @ref{787,,__getitem__()}, και το @code{x} είναι ένα στιγμιότυπο αυτής της κλάσης, τότε το @code{x[i]} είναι περίπου ισοδύναμο με το @code{type(x).__getitem__(x, i)}. Εκτός από τις περιπτώσεις που αναφέρονται, οι προσπάθειες εκτέλεσης μιας λειτουργίας δημιουργούν εξαίρεση όταν δεν ορίζεται κατάλληλη μέθοδος (συνήθως @ref{1a9,,AttributeError} ή @ref{291,,TypeError}).

Ο ορισμός μιας ειδική μεθόδου σε @code{None} σημαίνει ότι η αντίστοιχη λειτουργία δεν είναι διαθέσιμη.  Για παράδειγμα, εάν μια κλάση ορίσει την @ref{102d,,__iter__()} σε @code{None} η κλάση δεν είναι iterable, επομένως η κλήση @ref{bb4,,iter()} στα στιγμιότυπα της θα κάνει raise μια @ref{291,,TypeError} (χωρίς να επιστρέψουμε στο @ref{787,,__getitem__()}). @footnote{
Οι μέθοδοι @ref{ec1,,__hash__()}, @ref{102d,,__iter__()}, @ref{1049,,__reversed__()}, @ref{175c,,__contains__()}, @ref{b21,,__class_getitem__()} και @ref{1010,,__fspath__()} έχουν ειδικό χειρισμό για αυτό. Άλλες θα εξακολουθούν να κάνουν raise ένα @ref{291,,TypeError}, αλλά μπορεί να το κάνουν με την αξιοποίηση της συμπεριφοράς ότι το @code{None} δεν είναι καλούμενο.
}

Κατά την υλοποίηση μιας κλάσης που προσομοιώνει οποιονδήποτε ενσωματωμένο τύπο, είναι σημαντικό η εξομοίωση να υλοποιείται μόνο στο βαθμό που έχει νόημα για το αντικείμενο που μοντελοποιείται.  Για παράδειγμα, ορισμένες ακολουθίες μπορεί να λειτουργούν καλά με την ανάκτηση μεμονωμένων στοιχείων, αλλά η εξαγωγή ενός τμήματος μπορεί να μην έχει νόημα.  (Ένα παράδειγμα αυτού είναι η διεπαφή @ref{25a0,,NodeList} στο Μοντέλο Αντικειμένου Εγγράφου του W3C.)

@menu
* Βασική προσαρμογή:: 
* Προσαρμογή πρόσβασης χαρακτηριστικών:: 
* Προσαρμογή δημιουργίας κλάσης:: 
* Προσαρμογή ελέγχων παρουσίας και υποκλάσης:: 
* Εξομοίωση γενικών τύπων:: 
* Εξομοίωση αντικειμένων με δυνατότητα κλήσης:: 
* Εξομοίωση τύπων κοντέινερ:: 
* Εξομοίωση αριθμητικών τύπων:: 
* Με τους Διαχειριστές Περιβάλλοντος Δήλωσης:: 
* Προσαρμογή ορισμάτων θέσης στην αντιστοίχιση προτύπων κλάσης:: 
* Εξομοίωση τύπων buffer:: 
* Annotations:: 
* Αναζήτηση ειδικής μεθόδου:: 

@end menu

@node Βασική προσαρμογή,Προσαρμογή πρόσβασης χαρακτηριστικών,,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel basic-customization}@anchor{25a1}@anchor{reference/datamodel customization}@anchor{25a2}
@subsubsection Βασική προσαρμογή


@geindex __new__() (μέθοδος της object)
@anchor{reference/datamodel object __new__}@anchor{982}
@deffn {Μέθοδος} object.__new__ (cls[, ...])

@geindex δημιουργία υποκλάσης;αμετάβλητοι τύποι

Καλείται για τη δημιουργία ενός νέου στιγμιοτύπου κλάσης `cls'. Η @ref{982,,__new__()}  είναι μια στατική μέθοδος (ειδική περίπτωση, επομένως δεν χρειάζεται να τη δηλώνετε ως τέτοια) που παίρνει την κλάση της οποίας ζητήθηκε ένα στιγμιότυπο ως πρώτο όρισμα.  Τα υπόλοιπα ορίσματα είναι αυτά που μεταβιβάζονται στην έκφραση του κατασκευαστή αντικειμένου (η κλήση στην κλάση). Η επιστρεφόμενη τιμή του @code{__new__()} θα πρέπει να είναι το νέο στιγμιότυπο αντικειμένου (συνήθως ένα στιγμιότυπο του `cls').

Οι τυπικές υλοποιήσεις δημιουργούν ένα νέο στιγμιότυπο κλάσης επικαλώντας τη μέθοδο @ref{982,,__new__()} της υπερκλάσης χρησιμοποιώντας @code{super().__new__(cls[, ...])} με κατάλληλα ορίσματα και στη συνέχεια τροποποιώντας τη νεο-δημιουργηθείσα παρουσία όπως απαιτείται πριν την επιστρέψει.

Εάν το @ref{982,,__new__()} καλείται κατά την κατασκευή αντικειμένου και επιστρέφει ένα στιγμιότυπο του `cls', τότε η μέθοδος @ref{2fa,,__init__()} του νέου στιγμιοτύπου θα κληθεί όπως @code{__init__(self[, ...])}, όπου το `self' είναι το νέο στιγμιότυπο και τα υπόλοιπα ορίσματα είναι τα ίδια με αυτά που διαβιβάστηκαν στον κατασκευαστή του αντικειμένου.

Εάν το @ref{982,,__new__()} δεν επιστρέφει ένα στιγμιότυπο του `cls', τότε η μέθοδος @ref{2fa,,__init__()} του νέου στιγμιοτύπου δεν θα κληθεί.

Το @ref{982,,__new__()} προορίζεται κυρίως για να επιτρέψει σε υποκλάσεις αμετάβλητων τύπων (όπως int, str, ή tuple) να προσαρμόσουν τη δημιουργία στιγμιοτύπων. Επίσης συνήθως παρακάμπτεται σε προσαρμοσμένες μετακλάσεις προκειμένου να προσαρμόσουν τη δημιουργία κλάσεων.
@end deffn

@geindex __init__() (μέθοδος της object)
@anchor{reference/datamodel object __init__}@anchor{2fa}
@deffn {Μέθοδος} object.__init__ (self[, ...])

@geindex κλάση;constructor

Καλείται μετά τη δημιουργία του στιγμιοτύπου (από @ref{982,,__new__()}), αλλά πριν επιστραφεί εκεί που καλέστηκε.  Τα ορίσματα είναι αυτά που μεταβιβάζονται στην έκφραση του κατασκευαστή κλάσης.  Εάν μια κλάση βάσης έχει μια μέθοδο @ref{2fa,,__init__()}, η μέθοδος @code{__init__()} της παραγόμενης κλάσης, εάν υπάρχει πρέπει να την καλέσει ρητά για να διασφαλιστεί η σωστή προετοιμασία του τμήματος της βασικής κλάσης του στιγμιοτύπου∙ για παράδειγμα: @code{super().__init__([args...])}.

Επειδή τα @ref{982,,__new__()} και @ref{2fa,,__init__()} συνεργάζονται για την κατασκευή αντικειμένων (@code{__new__()} για να το δημιουργήσετε, και @code{__init__()} για να το προσαρμόσετε), δεν επιτρέπεται να επιστραφεί καμία τιμή μη-@code{None} από το @code{__init__()} ∙ αν το κάνετε αυτό, θα εμφανιστεί ένα @ref{291,,TypeError} κατά το χρόνο εκτέλεσης.
@end deffn

@geindex __del__() (μέθοδος της object)
@anchor{reference/datamodel object __del__}@anchor{13a6}
@deffn {Μέθοδος} object.__del__ (self)

@geindex destructor
@geindex finalizer
@geindex δήλωση;del

Καλείται όταν το παράδειγμα πρόκειται να καταστραφεί.  Αυτό ονομάζεται επίσης τελικό ή (κακώς) καταστροφέας.  Εάν μια βασική κλάση έχει μια μέθοδο @ref{13a6,,__del__()}, η μέθοδος @code{__del__()} της παράγωγης κλάσης, εάν υπάρχει, πρέπει να την καλέσει ρητά για να διασφαλιστεί η σωστή διαγραφή του τμήματος της βασικής κλάσης του στιγμιοτύπου.

Είναι δυνατό (αν και δεν συνίσταται!) η μέθοδος @ref{13a6,,__del__()} να αναβάλει την καταστροφή του στιγμιότυπου δημιουργώντας μια νέα αναφορά σε αυτό. Αυτό ονομάζεται αντικείμενο `ανάσταση (resurrection)'. Εξαρτάται από την υλοποίηση εάν το @code{__del__()} καλείται δεύτερη φορά όταν ένα αναστημένο αντικείμενο πρόκειται να καταστραφεί εξαρτάται από την υλοποίηση∙ η τρέχουσα υλοποίηση του @ref{ae3,,CPython} την καλεί μόνο μία φορά.

Δεν είναι εγγυημένο ότι οι μέθοδοι @ref{13a6,,__del__()} καλούνται για αντικείμενα που εξακολουθούν να υπάρχουν κατά την έξοδο του διερμηνέα. Η @ref{e3e,,weakref.finalize} παρέχει έναν απλό τρόπο για την καταχώριση μιας συνάρτησης καθαρισμού που θα καλείται όταν ένα αντικείμενο συλλέγεται από τα σκουπίδια.

@cartouche
@quotation Σημείωση 
Το @code{del x} δεν καλεί απευθείας το @code{x.__del__()} —  το πρώτο μειώνει το πλήθος αναφοράς για το @code{x} κατά ένα και το δεύτερο καλείται μόνο όταν το πλήθος αναφοράς του @code{x} φτάσει στο μηδέν.
@end quotation
@end cartouche

Είναι δυνατό για έναν κύκλο αναφοράς να εμποδίσει το πλήθος αναφοράς ενός να μηδενιστεί.  Σε αυτήν την περίπτωσης, ο κύκλος θα εντοπιστεί αργότερα και θα διαγραφεί από τον @ref{19de,,cyclic garbage collector}. Μια κοινή αιτία κύκλων αναφοράς είναι όταν μια εξαίρεση έχει εντοπιστεί σε μια τοπική μεταβλητή. Στη συνέχεια, τα τοπικά του πλαισίου αναφέρονται στην εξαίρεση, η οποία αναφέρεται στο δικό του traceback, το οποίο αναφέρεται στους τοπικούς αριθμούς όλων των καρέ που έχουν εντοπιστεί στο traceback.


@subsubheading Δείτε επίσης


Τεκμηρίωση για το module @ref{63,,gc}.


@cartouche
@quotation Προειδοποίηση 
Λόγω των επισφαλών συνθηκών υπό τις οποίες καλούνται οι μέθοδοι @ref{13a6,,__del__()}, οι εξαιρέσεις που προκύπτουν κατά την εκτέλεση τους αγνοούνται και αντ” αυτού εκτυπώνεται μια προειδοποίηση στο @code{sys.stderr}. Ειδικότερα:


@itemize *

@item 
Η @ref{13a6,,__del__()} μπορεί να καλεστεί, όταν καλείται αυθαίρετος κώδικα, συμπεριλαμβανομένου οποιουδήποτε αυθαίρετου νήματος.  Εάν η @code{__del__()} χρειάζεται να κλειδώσει ή να επικαλεστεί οποιονδήποτε άλλο πόρο αποκλεισμού, μπορεί να είναι αδιέξοδο καθώς ο πόρος μπορεί να έχει ήδη ληφθεί από τον κώδικα που διακόπτεται για να εκτελεστεί @code{__del__()}.

@item 
Η @ref{13a6,,__del__()} μπορεί να εκτελεστεί κατά τη διάρκεια του τερματισμού λειτουργίας του διερμηνέα.  Κατά συνέπεια, οι καθολικές μεταβλητές στις οποίες χρειάζεται πρόσβαση (συμπεριλαμβανομένων άλλως modules) μπορεί να έχουν ήδη διαγραφεί ή να έχουν οριστεί σε @code{None}. Η Python εγγυάται ότι τα καθολικά των οποίων το όνομα αρχίζει με μία μόνο υπογράμμιση διαγράφονται από το module τους πριν διαγραφούν άλλα καθολικά∙ εάν δεν υπάρχουν άλλες αναφορές σε τέτοια καθολικά, αυτό μπορεί να βοηθήσει στη διασφάλιση ότι τα εισαγόμενα modules εξακολουθούν να είναι διαθέσιμες τη στιγμή που καλείται η μέθοδος @code{__del__()}.
@end itemize
@end quotation
@end cartouche

@geindex repr() (ενσωματωμένη συνάρτηση);__repr__() (μέθοδος αντικειμένου)
@end deffn

@geindex __repr__() (μέθοδος της object)
@anchor{reference/datamodel object __repr__}@anchor{1bc}
@deffn {Μέθοδος} object.__repr__ (self)

Καλείται από την ενσωματωμένη συνάρτηση @ref{45b,,repr()} για τον υπολογισμό της «official» αναπαράστασης συμβολοσειράς ενός αντικειμένου. Εάν είναι δυνατόν, αυτό θα πρέπει να μοιάζει με μια έγκυρη έκφραση Python που θα μπορούσε να χρησιμοποιηθεί για την αναδημιουργία ενός αντικειμένου με την ίδια τιμή (δεδομένου ενός κατάλληλου περιβάλλοντος). Εάν αυτό δεν είναι δυνατό, θα πρέπει να επιστραφεί μια συμβολοσειρά της μορφής @code{<...κάποια χρήσιμη περιγραφή...>}. Η τιμή επιστροφής πρέπει να είναι αντικείμενο συμβολοσειράς. Εάν μια κλάση ορίζει @ref{1bc,,__repr__()} αλλά όχι @ref{a0f,,__str__()}, τότε η @code{__repr__()} χρησιμοποιείται επίσης όταν απαιτείται μια «ανεπίσημη» αναπαράσταση συμβολοσειράς στιγμιοτύπων αυτής της κλάσης.

Αυτό χρησιμοποιείται συνήθως για εντοπισμός σφαλμάτων, επομένως είναι σημαντικό η αναπαράσταση να είναι πλούσια σε πληροφορίες και ξεκάθαρη. Μια προεπιλεγμένη υλοποίηση παρέχεται από την ίδια την κλάση @ref{e4d,,object}.

@geindex συμβολοσειρά;__str__() (μέθοδος αντικειμένου)
@geindex format() (ενσωματωμένη συνάρτηση);__str__() (μέθοδος αντικειμένου)
@geindex print() (ενσωματωμένη συνάρτηση);__str__() (μέθοδος αντικειμένου)
@end deffn

@geindex __str__() (μέθοδος της object)
@anchor{reference/datamodel object __str__}@anchor{a0f}
@deffn {Μέθοδος} object.__str__ (self)

Καλείται από @ref{1df,,str(object)} και τις ενσωματωμένες συναρτήσεις @ref{a10,,__format__()} και @ref{131f,,print()} για τον υπολογισμό της «ανεπίσημης» ή ωραίας εκτύπωσης συμβολοσειράς ενός αντικειμένου. Η τιμή που επιστρέφεται πρέπει να είναι ένα αντικείμενο @ref{21cd,,string}.

Αυτή η μέθοδος διαφέρει από τη @ref{1bc,,object.__repr__()} στο ότι δεν υπάρχει καμία προσδοκία ότι η @ref{a0f,,__str__()} θα επιστρέψει μια έγκυρη έκφραση Python: μπορεί να χρησιμοποιηθεί μια πιο βολική ή συνοπτική αναπαράσταση.

Η προεπιλεγμένη υλοποίηση που ορίζεται από τον ενσωματωμένο τύπο @ref{e4d,,object} καλεί την @ref{1bc,,object.__repr__()}.

@c XXX what about subclasses of string?
@end deffn

@geindex __bytes__() (μέθοδος της object)
@anchor{reference/datamodel object __bytes__}@anchor{9df}
@deffn {Μέθοδος} object.__bytes__ (self)

@geindex ενσωματωμένη συνάρτηση;bytes

Καλείται από @ref{2087,,bytes} για να υπολογιστεί μια παράσταση συμβολοσειράς byte ενός αντικειμένου. Αυτό θα πρέπει να επιστρέψει ένα @ref{1c7,,bytes} αντικείμενο. Η ίδια κλάση @ref{e4d,,object} δεν παρέχει αυτήν τη μέθοδο.

@geindex συμβολοσειρά;__format__() (μέθοδος αντικειμένου)
@geindex συμβολοσειρά;μετατροπή
@geindex ενσωματωμένη συνάρτηση;print
@end deffn

@geindex __format__() (μέθοδος της object)
@anchor{reference/datamodel object __format__}@anchor{a10}
@deffn {Μέθοδος} object.__format__ (self, format_spec)

Καλείται από την ενσωματωμένη συνάρτηση @ref{439,,format()} και κατ” επέκταση, αξιολόγηση των @ref{43a,,formatted string literals} και της μεθόδου @ref{a12,,str.format()}, για την παραγωγή μιας «μορφοποιημένης» συμβολοσειράς αναπαράστασης ενός αντικειμένου. Το όρισμα `format_spec' είναι μια συμβολοσειρά που περιέχει μια περιγραφή των επιλογών μορφοποίησης που επιθυμείτε. Η ερμηνεία του ορίσματος `format_spec' εξαρτάται από τον τύπο που υλοποιεί τη @ref{a10,,__format__()}, ωστόσο οι περισσότερες κλάσεις είτε θα αναθέσουν τη μορφοποίηση σε έναν από τους ενσωματωμένους τύπους είτε θα χρησιμοποιήσουν παρόμοια σύνταξη επιλογής μορφοποίησης.

Δείτε το @ref{6fe,,Format specification mini-language} για μια περιγραφή της τυπικής σύνταξης μορφοποίησης.

Η τιμή επιστροφής πρέπει να είναι αντικείμενο συμβολοσειράς.

Η προεπιλεγμένη υλοποίηση από την κλάση @ref{e4d,,object} θα πρέπει να λάβει μια κενή συμβολοσειρά `format_spec'. Αναθέτει την εντολή σε @ref{a0f,,__str__()}.


Άλλαξε στην έκδοση 3.4: Η ίδια μέθοδος __format__ του @code{object} κάνει raise μια @ref{291,,TypeError} εάν περάσει οποιαδήποτε μη κενή συμβολοσειρά.



Άλλαξε στην έκδοση 3.7: Το @code{object.__format__(x, '@w{'})} είναι πλέον ισοδύναμο με το @code{str(x)} αντί για το @code{format(str(x), '@w{'})}.

@end deffn

@geindex __lt__() (μέθοδος της object)
@geindex __le__() (μέθοδος της object)
@geindex __eq__() (μέθοδος της object)
@geindex __ne__() (μέθοδος της object)
@geindex __gt__() (μέθοδος της object)
@geindex __ge__() (μέθοδος της object)
@anchor{reference/datamodel richcmpfuncs}@anchor{25a3}@anchor{reference/datamodel object __lt__}@anchor{1645}
@deffn {Μέθοδος} object.__lt__ (self, other)
@anchor{reference/datamodel object __le__}@anchor{16af}
@deffnx {Μέθοδος} object.__le__ (self, other)
@anchor{reference/datamodel object __eq__}@anchor{ec0}
@deffnx {Μέθοδος} object.__eq__ (self, other)
@anchor{reference/datamodel object __ne__}@anchor{18b9}
@deffnx {Μέθοδος} object.__ne__ (self, other)
@anchor{reference/datamodel object __gt__}@anchor{16b0}
@deffnx {Μέθοδος} object.__gt__ (self, other)
@anchor{reference/datamodel object __ge__}@anchor{16b1}
@deffnx {Μέθοδος} object.__ge__ (self, other)

@geindex συγκρίσεις

Αυτές είναι οι λεγόμενες μέθοδοι «πλούσιας σύγκρισης (rich comparison)». Η αντιστοιχία μεταξύ των συμβόλων των τελεστών και των ονομάτων των μεθόδων έχει ως εξής: @code{x<y} καλεί @code{x.__lt__(y)}, @code{x<=y} καλεί @code{x.__le__(y)}, @code{x==y} καλεί @code{x.__eq__(y)}, @code{x!=y} καλεί @code{x.__ne__(y)}, @code{x>y} καλεί @code{x.__gt__(y)}, και @code{x>=y} καλεί @code{x.__ge__(y)}.

Μια μέθοδος πλούσια σύγκρισης μπορεί να επιστρέψει το singleton @ref{440,,NotImplemented} εάν δεν υλοποιήσει τη λειτουργία για ένα δεδομένο ζεύγος ορισμάτων. Σύμφωνα με τη σύμβαση, επιστρέφονται οι τιμές @code{False} και @code{True} για μια επιτυχημένη σύγκριση. Ωστόσο, αυτές οι μέθοδοι μπορούν αν επιστρέψουν οποιαδήποτε τιμή, επομένως εάν ο τελεστής σύγκρισης χρησιμοποιείται σε ένα Boolean περιβάλλον (π.χ., στη συνθήκη μιας πρότασης @code{if}), η Python θα καλέσει τη συνάρτηση @ref{5ef,,bool()} στην τιμή για να προσδιορίσει εάν το αποτέλεσμα είναι αληθές ή ψευδές.

Από προεπιλογή, το @code{object} υλοποιεί την @ref{ec0,,__eq__()} χρησιμοποιώντας την @code{is}, επιστρέφοντας @ref{440,,NotImplemented} σε περίπτωση ψευδούς σύγκρισης: @code{True if x is y else NotImplemented}. Για την @ref{18b9,,__ne__()}, από προεπιλογή αναθέτει σε @code{__eq__()} και αντιστρέφει το αποτέλεσμα εκτός αν είναι @code{NotImplemented}. Δεν υπάρχουν άλλες σιωπηρές σχέσεις μεταξύ των τελεστών σύγκρισης ή των προεπιλεγμένων υλοποιήσεων∙ για παράδειγμα, το αληθές του @code{(x<y or x==y)} δεν συνεπάγεται @code{x<=y}. Για να δημιουργήσετε αυτόματα λειτουργίες ταξινόμησης από μία μόνο ριζική λειτουργία, ανατρέξτε στο @ref{12ed,,functools.total_ordering()}.

Από προεπιλογή, η κλάση @ref{e4d,,object} παρέχει υλοποιήσεις συμβατές με @ref{1e17,,Value comparisons}: η ισότητα συγκρίνει σύμφωνα με την ταυτότητά του αντικειμένου και οι συγκρίσεις κατά σειρά κάνουν raise @ref{291,,TypeError}. Κάθε προεπιλεγμένη μέθοδος μπορεί να δημιουργήσει αυτά τα αποτελέσματα απευθείας, αλλά μπορεί επίσης να επιστρέψει την τιμή @ref{440,,NotImplemented}.

Δείτε την παράγραφο σχετικά με το @ref{ec1,,__hash__()} για μερικές σημαντικές σημειώσεις σχετικά με τη δημιουργία αντικειμένων @ref{183,,hashable} τα οποία υποστηρίζουν προσαρμοσμένες λειτουργίες σύγκρισης και μπορούν να χρησιμοποιηθούν ως κλειδιά λεξικού.

Δεν υπάρχουν εκδόσεις αυτών των μεθόδων με εναλλασσόμενα ορίσματα (που χρησιμοποιούνται όταν το αριστερό όρισμα δεν υποστηρίζει τη λειτουργία, αλλά το δεξί όρισμα υποστηρίζει)∙ αντίθετα, οι @ref{1645,,__lt__()} και @ref{16b0,,__gt__()} είναι η αντανάκλαση η μία της άλλης, οι @ref{16af,,__le__()} και @ref{16b1,,__ge__()} είναι η αντανάκλαση η μία της άλλης, και οι @ref{ec0,,__eq__()} και @ref{18b9,,__ne__()} είναι η δική τους αντανάκλαση. Εάν οι τελεστέοι είναι διαφορετικών τύπων και ο τύπος του δεξιού τελεστέου είναι μια άμεση ή έμμεση υποκλάση του τύπου του αριστερού τελεστέου, η ανακλώμενη μέθοδος του δεξιού τελεστέου έχει προτεραιότητα, διαφορετικά η μέθοδος του αριστερού τελεστέου έχει προτεραιότητα. Η εικονική υποκλάση δεν λαμβάνεται υπόψη.

Όταν καμία κατάλληλη μέθοδος δεν επιστρέφει καμία τιμή εκτός από την @ref{440,,NotImplemented}, οι τελεστές @code{==} και @code{!=} θα επιστρέψουν στις τιμές @code{is} και @code{is not}, αντίστοιχα.
@end deffn

@geindex __hash__() (μέθοδος της object)
@anchor{reference/datamodel object __hash__}@anchor{ec1}
@deffn {Μέθοδος} object.__hash__ (self)

@geindex αντικείμενο;λεξικό
@geindex ενσωματωμένη συνάρτηση;hash

Καλείται από την ενσωματωμένη συνάρτηση @ref{9e2,,hash()} και για λειτουργίες σε μέλη κατακερματισμένων συλλόγων, συμπεριλαμβανομένων των @ref{42b,,set}, @ref{9d4,,frozenset}, and @ref{188,,dict}. Η μέθοδος @code{__hash__()} θα πρέπει να επιστρέφει έναν ακέραιο αριθμό. Η μόνη απαιτούμενη ιδιότητα είναι ότι τα αντικείμενα που συγκρίνονται ίσα έχουν την ίδια τιμή κατακερματισμού. Συνίσταται να αναμειγνύεται τις τιμές κατακερματισμού των στοιχείων του αντικειμένου που παίζουν επίσης ρόλο στη σύγκριση αντικειμένων, συσκευάζοντας τα σε μια πλειάδα και κατακερματίζοντας την πλειάδα. Παράδειγμα:

@example
def __hash__(self):
    return hash((self.name, self.nick, self.color))
@end example

@cartouche
@quotation Σημείωση 
Η @ref{9e2,,hash()} περικόπτει την τιμή που επιστρέφεται από την προσαρμοσμένη μέθοδο @ref{ec1,,__hash__()} ενός αντικειμένου στο μέγεθος @ref{e24,,Py_ssize_t}.  Αυτό είναι συνήθως 8 byte σε εκδόσεις 64-bit και 4 byte σε εκδόσεις 32-bit.  Εάν η @code{__hash__()} ενός αντικειμένου πρέπει να διαλειτουργήσει σε εκδόσεις διαφορικών μεγεθών bit, φροντίστε να ελέγξετε το πλάτος σε όλες τις υποστηριζόμενες εκδόσεις.  Ένας εύκολος τρόπος για να το κάνετε αυτό είναι με την @code{python -c "import sys; print(sys.hash_info.width)"}.
@end quotation
@end cartouche

Εάν μια κλάση δεν ορίζει μια μέθοδο @ref{ec0,,__eq__()}, δεν θα πρέπει να ορίζει ούτε μια λειτουργία @ref{ec1,,__hash__()} ∙ εάν ορίζει τη @code{__eq__()} αλλά όχι τη @code{__hash__()}, τα στιγμιότυπα της δεν θα είναι χρησιμοποιήσιμες ως στοιχεία σε συλλογές που μπορούν να κατακερματιστούν.  Εάν μια κλάση ορίζει αντικείμενα που μπορούν να μεταβληθούν και υλοποιεί μια μέθοδο @code{__eq__()}, δεν θα πρέπει να υλοποιεί τη @code{__hash__()}, καθώς η υλοποίηση των συλλογών @ref{183,,hashable} απαιτεί η τιμή hash ενός κλειδιού να είναι αμετάβλητη (εάν η τιμή hash του αντικειμένου αλλάξει, θα βρίσκεται σε λάθος κάδο hash).

Οι κλάσεις που ορίζονται από τον χρήστη έχουν από προεπιλογή τις μεθόδους @ref{ec0,,__eq__()} και @ref{ec1,,__hash__()} από προεπιλογή (κληρονομούνται από την κλάση @ref{e4d,,object}) ∙ με αυτές, όλα τα αντικείμενα συγκρίνονται άνισα (εκτός από τον εαυτό τους) και το @code{x.__hash__()} επιστρέφει μια κατάλληλη τιμή έτσι ώστε το @code{x == y} να υπονοεί ότι το @code{x is y} και @code{hash(x) == hash(y)}.

Μια κλάση που παρακάμπτει τη @ref{ec0,,__eq__()} και δεν ορίζει τη @ref{ec1,,__hash__()} θα έχει τη @code{__hash__()} της έμμεσα ορισμένο σε @code{None}. Όταν η μέθοδος @code{__hash__()} μιας κλάσης είναι @code{None}, τα στιγμιότυπα της κλάσης θα κάνουν raise μια κατάλληλη @ref{291,,TypeError} όταν ένα πρόγραμμα επιχειρήσει να ανακτήσει την τιμή κατακερματισμού τους και θα αναγνωρίσουν επίσης σωστά ως μη κατακερματιζόμενες κατά τον έλεγχο του @code{isinstance(obj, collections.abc.Hashable)}.

Εάν μια κλάση που παρακάμπτει την @ref{ec0,,__eq__()} χρειάζεται να διατηρήσει την υλοποίηση της @ref{ec1,,__hash__()} από μια γονική κλάση, ο διερμηνέας πρέπει να ενημερωθεί ρητά για αυτό ορίζονται την @code{__hash__ = <ParentClass>.__hash__}.

Εάν μια κλάση που δεν παρακάμπτει τη @ref{ec0,,__eq__()} επιθυμεί να καταστείλει την υποστήριξη κατακερματισμού, θα πρέπει να συμπεριλάβει το @code{__hash__ = None} στον ορισμός της κλάσης. Μια κλάση που ορίζει τη δικιά της @ref{ec1,,__hash__()} που κάνει raise μια @ref{291,,TypeError} θα αναγνωριστεί εσφαλμένα ως μια κλάση που μπορεί να κατακερματιστεί από μια κλήση @code{isinstance(obj, collections.abc.Hashable)}.

@cartouche
@quotation Σημείωση 
Από προεπιλογή, οι τιμές @ref{ec1,,__hash__()} των αντικειμένων str και bytes είναι «salted» με μια απρόβλεπτη τυχαία τιμή.  Παρόλο που παραμένουν σταθερές μέσα σε μια μεμονωμένη διεργασία Python, δεν είναι προβλέψιμες μεταξύ επαναλαμβανόμενων κλήσεων της 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{https://ocert.org/advisories/ocert-2011-003.html} for details.

Η αλλαγή των τιμών κατακερματισμού επηρεάζει τη σειρά επανάληψης των συνόλων. Η Python δεν έχει δώσει ποτέ εγγυήσεις σχετικά με αυτήν τη σειρά (και συνήθως ποικίλει μεταξύ εκδόσεων 32-bit και 64-bit).

Δείτε επίσης 
@geindex PYTHONHASHSEED
@geindex μεταβλητή περιβάλλοντος; PYTHONHASHSEED
@ref{1425,,PYTHONHASHSEED}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: Η τυχαιοποίηση κατακερματισμού είναι ενεργοποιημένη από προεπιλογή.

@end deffn

@geindex __bool__() (μέθοδος της object)
@anchor{reference/datamodel object __bool__}@anchor{167a}
@deffn {Μέθοδος} object.__bool__ (self)

@geindex __len__() (μέθοδος αντιστοίχισης αντικειμένου)

Καλείται για την υλοποίηση ελέγχου τιμών αλήθειας και την ενσωματωμένη λειτουργία @code{bool()} ∙ θα πρέπει να επιστρέφει @code{False} ή @code{True}.  Όταν αυτή η μέθοδος δεν έχει οριστεί, καλείται η @ref{1989,,__len__()}, εάν έχει οριστεί, και το αντικείμενο θεωρείται αληθές εάν το αποτέλεσμα του είναι μη μηδενικό.  Εάν μια κλάση δεν ορίζει ούτε @code{__len__()} ούτε @code{__bool__()}, (κάτι που ισχύει για την ίδια την κλάση @ref{e4d,,object}), όλα τα στιγμιότυπα της θεωρούνται αληθείς.
@end deffn

@node Προσαρμογή πρόσβασης χαρακτηριστικών,Προσαρμογή δημιουργίας κλάσης,Βασική προσαρμογή,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel attribute-access}@anchor{25a4}@anchor{reference/datamodel customizing-attribute-access}@anchor{25a5}
@subsubsection Προσαρμογή πρόσβασης χαρακτηριστικών


Οι ακόλουθες μέθοδοι μπορούν αν οριστούν για την προσαρμογή της έννοιας της πρόσβασης χαρακτηριστικών (χρήση, ανάθεση ή διαγραφή του @code{x.name}) για στιγμιότυπα κλάσης.

@c XXX explain how descriptors interfere here!

@geindex __getattr__() (μέθοδος της object)
@anchor{reference/datamodel object __getattr__}@anchor{8e3}
@deffn {Μέθοδος} object.__getattr__ (self, name)

Καλείται όταν η πρόσβαση προεπιλεγμένου χαρακτηριστικού αποτυγχάνει με μια @ref{1a9,,AttributeError} (είτε η @ref{f90,,__getattribute__()} κάνει raise μια @code{AttributeError} επειδή το `name' δεν είναι χαρακτηριστικό στιγμιοτύπου ή χαρακτηριστικό στο δέντρο κλάσης για το @code{self} ∙ ή η @ref{188a,,__get__()} μια ιδιότητας `name' κάνει raise μια @code{AttributeError}).  Αυτή η μέθοδος θα πρέπει είτε να επιστρέψει την (υπολογισμένη) τιμή του χαρακτηριστικού είτε να κάνει raise μια εξαίρεση @code{AttributeError}. Η ίδια η κλάση @ref{e4d,,object} δεν παρέχει αυτήν τη μέθοδο.

Σημειώστε ότι εάν το χαρακτηριστικό βρεθεί μέσω του κανονικού μηχανισμού, η @ref{8e3,,__getattr__()} δεν καλείται.  (Αυτή είναι μια σκόπιμη ασυμμετρία μεταξύ της @code{__getattr__()} και της @ref{256d,,__setattr__()}.) Αυτό γίνεται τόσο για λόγους αποδοτικότητας όσο και επειδή διαφορετικά η @code{__getattr__()} δεν θα είχε κανέναν τρόπο να έχει πρόσβαση σε άλλα χαρακτηριστικά του στιγμιοτύπου.  Σημειώστε ότι τουλάχιστον για τις μεταβλητές στιγμιοτύπου, μπορείτε να αναλάβετε πλήρη έλεγχο εισάγοντας καμία τιμή στο λεξικό χαρακτηριστικών στιγμιοτύπου (αλλά αντίθετα εισάγοντάς τις σε ένα άλλο αντικείμενο).  Δείτε την παρακάτω μέθοδο @ref{f90,,__getattribute__()} για έναν τρόπο να έχετε πραγματικά πλήρη έλεγχο της πρόσβασης σε χαρακτηριστικά.
@end deffn

@geindex __getattribute__() (μέθοδος της object)
@anchor{reference/datamodel object __getattribute__}@anchor{f90}
@deffn {Μέθοδος} object.__getattribute__ (self, name)

Καλείται χωρίς προϋποθέσεις για την υλοποίηση της πρόσβασης σε χαρακτηριστικά για στιγμιότυπα κλάσης. Αν η κλάση ορίζει επίσης τη μέθοδο @ref{8e3,,__getattr__()}, αυτή δεν θα κληθεί εκτός αν η @ref{f90,,__getattribute__()} την καλέσει ρητά ή κάνει raise μια εξαίρεση @ref{1a9,,AttributeError}. Αυτή η μέθοδος πρέπει να επιστρέφει την (υπολογισμένη) τιμή του χαρακτηριστικού ή να κάνει raise μια εξαίρεση @code{AttributeError}. Για να αποφευχθεί η ατέρμονη αναδρομή μέσα σε αυτή τη μέθοδο, η υλοποίηση της πρέπει πάντα να καλεί τη μέθοδο της βασικής κλάσης με το ίδιο όνομα για να έχει πρόσβαση σε οποιαδήποτε ιδιότητα χρειάζεται, για παράδειγμα @code{object.__getattribute__(self, name)}.

@cartouche
@quotation Σημείωση 
Αυτή η μέθοδος μπορεί ακόμα να παρακαμφθεί κατά την αναζήτηση ειδικών μεθόδων ως αποτέλεσμα σιωπηρής επίκλησης μέσω σύνταξης γλώσσας ή @ref{253f,,built-in functions}. Βλ. @ref{25a6,,Αναζήτηση ειδικής μεθόδου}.
@end quotation
@end cartouche

Για συγκεκριμένες προσβάσεις ευαίσθητων χαρακτηριστικών, δημιουργεί ένα @ref{1e65,,auditing event} @code{object.__getattr__} με ορίσματα @code{obj} και @code{name}.
@end deffn

@geindex __setattr__() (μέθοδος της object)
@anchor{reference/datamodel object __setattr__}@anchor{256d}
@deffn {Μέθοδος} object.__setattr__ (self, name, value)

Καλείται όταν επιχειρείται εκχώρηση χαρακτηριστικού.  Αυτό καλείται αντί για τον κανονικό μηχανισμό (δηλαδή αποθήκευση της τιμής στο λεξικό στιγμιοτύπου). Το `name' είναι το όνομα του χαρακτηριστικού, `value' είναι η τιμή που θα του εκχωρηθεί.

Εάν η @ref{256d,,__setattr__()} θέλει να εκχωρήσει σε ένα χαρακτηριστικό στιγμιοτύπου, θα πρέπει να καλέσει τη μέθοδο της βασικής κλάσης με το ίδιο όνομα, για παράδειγμα, @code{object.__setattr__(self, name, value)}.

Για ορισμένες εκχωρήσεις ευαίσθητων χαρακτηριστικών, γίνεται raise μια @ref{1e65,,auditing event} @code{object.__setattr__} με ορίσματα @code{obj}, @code{name}, @code{value}.
@end deffn

@geindex __delattr__() (μέθοδος της object)
@anchor{reference/datamodel object __delattr__}@anchor{256e}
@deffn {Μέθοδος} object.__delattr__ (self, name)

Όπως η @ref{256d,,__setattr__()} αλλά για διαγραφή χαρακτηριστικών αντί για ανάθεση.  Αυτό θα πρέπει να εφαρμοστεί μόνο εάν το @code{del obj.name} έχει νόημα για το αντικείμενο.

Για ορισμένες διαγραφές ευαίσθητων χαρακτηριστικών, κάνει raise ένα @ref{1e65,,auditing event} @code{object.__delattr__} με ορίσματα @code{obj} και @code{name}.
@end deffn

@geindex __dir__() (μέθοδος της object)
@anchor{reference/datamodel object __dir__}@anchor{1935}
@deffn {Μέθοδος} object.__dir__ (self)

Καλείται όταν η @ref{a23,,dir()} καλείται στο αντικείμενο. Πρέπει να επιστραφεί ένα iterable. Η @code{dir()} μετατρέπει το iterable που επιστρέφεται σε λίστα και τον ταξινομεί.
@end deffn

@menu
* Προσαρμογή πρόσβασης χαρακτηριστικών module:: 
* Υλοποίηση Περιγραφέων:: 
* Κλήση Descriptors:: 
* __slots__: __slots__<2>. 

@end menu

@node Προσαρμογή πρόσβασης χαρακτηριστικών module,Υλοποίηση Περιγραφέων,,Προσαρμογή πρόσβασης χαρακτηριστικών
@anchor{reference/datamodel customizing-module-attribute-access}@anchor{25a7}
@subsubsection Προσαρμογή πρόσβασης χαρακτηριστικών module


@geindex __getattr__ (χαρακτηριστικό module)
@geindex __dir__ (χαρακτηριστικό module)
@geindex __class__ (χαρακτηριστικό module)

@geindex __getattr__() (μέθοδος της module)
@geindex __dir__() (μέθοδος της module)
@anchor{reference/datamodel module __getattr__}@anchor{ea6}
@deffn {Μέθοδος} module.__getattr__ ()
@anchor{reference/datamodel module __dir__}@anchor{ea7}
@deffnx {Μέθοδος} module.__dir__ ()
@end deffn

Οι ειδικές ονομασίες @code{__getattr__} και @code{__dir__} μπορούν επίσης να χρησιμοποιηθούν για την προσαρμογή της πρόσβασης στα χαρακτηριστικά του module. Η συνάρτηση @code{__getattr__} στο επίπεδο του module πρέπει να δέχεται ένα όρισμα, το οποίο είναι το όνομα ενός χαρακτηριστικού, και να επιστρέφει την υπολογισμένη τιμή ή να κάνει raise μια εξαίρεση @ref{1a9,,AttributeError}. Εάν ένα χαρακτηριστικό δεν βρεθεί σε ένα αντικείμενο module μέσω της κανονικής αναζήτησης, δηλαδή με τη μέθοδο @ref{f90,,object.__getattribute__()}, τότε η μέθοδος @code{__getattr__} αναζητείται στο λεξικό @code{__dict__} του module πριν γίνει raise η εξαίρεση @code{AttributeError}. Αν βρεθεί, καλείται με το όνομα της ιδιότητας και το αποτέλεσμα επιστρέφεται.

Η συνάρτηση @code{__dir__} δεν πρέπει να δέχεται ορίσματα και να επιστρέφει μια επαναλαμβανόμενη σειρά συμβολοσειρών που αντιπροσωπεύει τα ονόματα που είναι προσβάσιμα στο module. Εάν υπάρχει, αυτή η συνάρτηση παρακάμπτει την τυπική αναζήτηση @ref{a23,,dir()} σε ένα module.

@geindex __class__ (ιδιότητα της module)
@anchor{reference/datamodel module __class__}@anchor{25a8}
@deffn {Ιδιότητα} module.__class__
@end deffn

Για μια πιο λεπτομερή προσαρμογή της συμπεριφοράς του module (ρύθμιση χαρακτηριστικών, ιδιοτήτων κλπ.), μπορεί κανείς να ορίσει το χαρακτηριστικό @code{__class__} ενός αντικειμένου module σε μια υποκλάση @ref{11c7,,types.ModuleType}. Για παράδειγμα:

@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 Σημείωση 
Ο καθορισμός του module @code{__getattr__} και η ρύθμιση του module @code{__class__} επηρεάζουν μόνο τις αναζητήσεις που πραγματοποιούνται με χρήση της σύνταξης πρόσβασης χαρακτηριστικών – η απευθείας πρόσβαση στα καθολικά του module (είτε μέσω κώδικας εντός του module, είτε μέσω αναφοράς στο λεξικό καθολικών του module) δεν επηρεάζεται.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.5: Το χαρακτηριστικό @code{__class__} του module είναι πλέον εγγράψιμο.



Added in version 3.7: Τα χαρακτηριστικά @code{__getattr__} και @code{__dir__} του module.



@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 562

@item PEP 562@footnote{https://peps.python.org/pep-0562/} - Module __getattr__ and __dir__

Περιγράφει τις συναρτήσεις @code{__getattr__} και @code{__dir__} σε modules.
@end table


@node Υλοποίηση Περιγραφέων,Κλήση Descriptors,Προσαρμογή πρόσβασης χαρακτηριστικών module,Προσαρμογή πρόσβασης χαρακτηριστικών
@anchor{reference/datamodel descriptors}@anchor{100d}@anchor{reference/datamodel implementing-descriptors}@anchor{25a9}
@subsubsection Υλοποίηση Περιγραφέων


Οι παρακάτω μέθοδοι ισχύουν μόνο όταν ένα στιγμιότυπο της κλάσης που περιέχει τη μέθοδο (μια λεγόμενη κλάση `περιγραφέα') εμφανίζεται μια `ιδιοκτήτρια' κλάση (ο περιγραφέας πρέπει να βρίσκεται είτε στο λεξικό της κλάσης της ιδιοκτήτριας είτε στο λεξικό κλάσης κάποιου από τους γονείς της).  Στα παρακάτω παραδείγματα, «το χαρακτηριστικό» αναφέρεται στο χαρακτηριστικό του οποίου το όνομα είναι το κλειδί της ιδιότητας στο @ref{1bf,,__dict__} της ιδιοκτήτριας κλάσης.  Η ίδια η κλάση @ref{e4d,,object} δεν υλοποιεί κανένα από αυτά τα πρωτόκολλα.

@geindex __get__() (μέθοδος της object)
@anchor{reference/datamodel object __get__}@anchor{188a}
@deffn {Μέθοδος} object.__get__ (self, instance, owner=None)

Καλείται για να ληφθεί η ιδιότητα της ιδιοκτήτρια κλάσης (πρόσβαση σε χαρακτηριστικό κλάσης) ή ενός στιγμιοτύπου αυτή της κλάση (πρόσβαση σε χαρακτηριστικό στιγμιοτύπου). Η προαιρετική παράμετρος `owner' είναι η ιδιοκτήτρια κλάση, ενώ η `instance' είναι το στιγμιότυπο μέσω της οποίας έγινε πρόσβαση στο χαρακτηριστικό, ή @code{None} όταν η πρόσβαση στο χαρακτηριστικό έγινε μέσω της `owner'.

Αυτή η μέθοδος πρέπει να επιστρέφει την υπολογισμένη τιμή του χαρακτηριστικού ή να κάνει raise μια @ref{1a9,,AttributeError} εξαίρεση.

Το 
@geindex Python Enhancement Proposals; PEP 252
PEP 252@footnote{https://peps.python.org/pep-0252/} ορίζει ότι η μέθοδος @ref{188a,,__get__()} μπορεί να καλείται με ένα ή δύο ορίσματα.  Οι ενσωματωμένοι περιγραφείς της Python υποστηρίζουν αυτή την προδιαγραφή∙ ωστόσο, είναι πιθανό κάποια εργαλεία τρίτων να έχουν περιγραφείς που απαιτούν και τα δύο ορίσματα. Η ενσωματωμένη υλοποίηση της Python για τη μέθοδο @ref{f90,,__getattribute__()} περνάει πάντα και τα δύο ορίσματα, είτε είναι απαραίτητα είτε όχι.
@end deffn

@geindex __set__() (μέθοδος της object)
@anchor{reference/datamodel object __set__}@anchor{25aa}
@deffn {Μέθοδος} object.__set__ (self, instance, value)

Καλείται για να οριστεί το χαρακτηριστικό σε ένα στιγμιότυπο `instance' της ιδιοκτήτρια κλάσης σε μια νέα τιμή, `value'.

Σημείωση, η προσθήκη της @ref{25aa,,__set__()} ή @ref{1b64,,__delete__()} αλλάζει το είδος του περιγραφέα σε έναν «περιγραφέα δεδομένων».  Δείτε το @ref{25ab,,Κλήση Descriptors} για περισσότερες λεπτομέρειες.
@end deffn

@geindex __delete__() (μέθοδος της object)
@anchor{reference/datamodel object __delete__}@anchor{1b64}
@deffn {Μέθοδος} object.__delete__ (self, instance)

Καλείται για να διαγραφεί το χαρακτηριστικό σε ένα στιγμιότυπο `instance' της ιδιοκτήτρια κλάσης.
@end deffn

Τα στιγμιότυπα περιγραφέων μπορείς επίσης να έχουν διαθέσιμο το χαρακτηριστικό @code{__objclass__}:

@geindex __objclass__ (ιδιότητα της object)
@anchor{reference/datamodel object __objclass__}@anchor{25ac}
@deffn {Ιδιότητα} object.__objclass__

Το χαρακτηριστικό @code{__objclass__} ερμηνεύεται από το module @ref{81,,inspect} ως ένδειξη κλάσης στην οποία ορίστηκε το αντικείμενο (η κατάλληλη ρύθμιση αυτής μπορεί να βοηθήσει στην ανάκτηση πληροφοριών κατά την εκτέλεση για δυναμικά χαρακτηριστικά κλάσεων). Για αυτά που μπορούν να κληθούν, μπορεί να υποδεικνύει ότι ένα στιγμιότυπο του δεδομένου τύπου (ή μιας υποκλάσης του) αναμένεται ή απαιτείται ως το πρώτο όρισμα θέσεως (για παράδειγμα, η CPython θέτει αυτήν την ιδιότητα για μη δεσμευμένες μεθόδους που έχουν υλοποιηθεί σε C).
@end deffn

@node Κλήση Descriptors,__slots__<2>,Υλοποίηση Περιγραφέων,Προσαρμογή πρόσβασης χαρακτηριστικών
@anchor{reference/datamodel descriptor-invocation}@anchor{25ab}@anchor{reference/datamodel invoking-descriptors}@anchor{25ad}
@subsubsection Κλήση Descriptors


Γενικά, ένας descriptor είναι ένα χαρακτηριστικό αντικειμένου με «συμπεριφορά δέσμευσης», δηλαδή μια ιδιότητα της οποίας η πρόσβαση έχει παρακαμφθεί μέσω μεθόδων του πρωτοκόλλου περιγραφέα @ref{188a,,__get__()}, @ref{25aa,,__set__()}, και @ref{1b64,,__delete__()}. Αν οποιαδήποτε από αυτές τις μεθόδους έχει οριστεί για ένα αντικείμενο, τότε το αντικείμενο αυτό θεωρείται descriptor.

Η προεπιλεγμένη συμπεριφορά για την πρόσβαση χαρακτηριστικών είναι η ανάκτηση, ο ορισμός, ή η διαγραφή του χαρακτηριστικού από το λεξικό ενός αντικειμένου. Για παράδειγμα, το @code{a.x} έχει μια αλυσίδα αναζήτησης που ξεκινά με @code{a.__dict__['x']}, στη συνέχεια με @code{type(a).__dict__['x']} και συνεχίζει στις βασικές κατηγορίες του @code{type(a)} εξαιρουμένων των μετακλάσεων.

Ωστόσο, εάν η τιμή αναζήτησης είναι ένα αντικείμενο που ορίζει μία από τις μεθόδους περιγραφής, τότε η Python μπορεί να παρακάμψει την προεπιλεγμένη συμπεριφορά και να επικαλεστεί τη μέθοδο περιγραφής. Το πού συμβαίνει αυτό στην αλυσίδα προτεραιότητας εξαρτάται από το ποιες μέθοδοι περιγραφής ορίστηκαν και πώς ονομάστηκαν.

Το σημείο εκκίνηση για την επίκληση του περιγραφέα είναι ένα δεσμευτικό, @code{a.x}. Ο τρόπος συναρμολόγησης των ορισμάτων εξαρτάται από το @code{a}:


@table @asis

@item Απευθείας Κλήση

Η απλούστερη και λιγότερο συνηθισμένη κλήση είναι όταν ο κωδικός χρήστη καλεί απευθείας μια μέθοδο περιγραφής:    @code{x.__get__(a)}.

@item Δέσμευση Στιγμιοτύπου

Εάν δεσμεύεται σε ένα στιγμιότυπο αντικειμένου, το @code{a.x} μετατρέπεται στην κλήση: @code{type(a).__dict__['x'].__get__(a, type(a))}.

@item Δέσμευση Κλάσης

Εάν δεσμεύεται σε μια κλάση, το @code{A.x} μετατρέπεται στην κλήση: @code{A.__dict__['x'].__get__(None, A)}.

@item Υπερ-Δέσμευση

Μια διακεκομμένη αναζήτηση όπως @code{super(A, a).x} αναζητά το @code{a.__class__.__mro__} για μια βασική κλάση @code{B} μετά το @code{A} και, στη συνέχεια, επιστρέφει το @code{B.__dict__['x'].__get__(a, A)}.  Εάν δεν είναι περιγραφέας, το @code{x} επιστρέφεται αμετάβλητο.
@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

Για δεσμεύσεις στιγμιοτύπου, η προτεραιότητα της κλήση του περιγραφέα εξαρτάται από το ποιες μέθοδοι περιγραφέα έχουν οριστεί.  Ένα περιγραφέας μπορεί να ορίσει οποιονδήποτε συνδυασμό των @ref{188a,,__get__()}, @ref{25aa,,__set__()} και @ref{1b64,,__delete__()}. Αν δεν ορίσει τη μέθοδο @code{__get__()}, τότε η πρόσβαση στην ιδιότητα θα επιστρέψει το ίδιο το αντικείμενο του περιγραφέα, εκτός αν υπάρχει τιμή στο λεξικό στιγμιοτύπου του αντικειμένου. Αν ο περιγραφέας ορίζει τη μέθοδο @code{__set__()} και/ή @code{__delete__()}, θεωρείται περιγραφέας δεδομένων∙ αν δεν ορίζει καμία από τις δύο, είναι μη-περιγραφέας δεδομένων. Συνήθως, οι περιγραφείς δεδομένων ορίζουν και τις δύο @code{__get__()} και @code{__set__()}, ενώ οι μη-περιγραφείς δεδομένων έχουν μόνο τη μέθοδο @code{__get__()}. Οι περιγραφείς δεδομένων που έχουν ορίσει @code{__get__()} και @code{__set__()} (και/ή @code{__delete__()}) υπερισχύουν πάντα από έναν επαναπροσδιορισμό στο λεξικό στιγμιοτύπου. Αντίθετα, οι μη περιγραφείς δεδομένων μπορούν να παρακαμφθούν από στιγμιότυπα.

Οι μέθοδοι Python (συμπεριλαμβανομένων εκείνων που είναι διακοσμημένες με @ref{666,,@@staticmethod} και @ref{69a,,@@classmethod}) υλοποιούνται ως περιγραφέα χωρίς δεδομένα. Αντίστοιχα, τα στιγμιότυπα μπορούν να επαναπροσδιορίσουν και να παρακάμψουν μεθόδους. Αυτό επιτρέπει σε μεμονωμένα στιγμιότυπα να αποκτήσουν συμπεριφορές που διαφέρουν από άλλα στιγμιότυπα της ίδιας κλάσης.

Η συνάρτηση @ref{6bb,,property()} υλοποιείται ως περιγραφέας δεδομένων. Συνεπώς, οι περιπτώσεις δεν μπορούν να παρακάμψουν τη συμπεριφορά μιας ιδιότητας.

@node __slots__<2>,,Κλήση Descriptors,Προσαρμογή πρόσβασης χαρακτηριστικών
@anchor{reference/datamodel id13}@anchor{25ae}@anchor{reference/datamodel slots}@anchor{1cd}
@subsubsection __slots__


Το `__slots__' μας επιτρέπει να δηλώνουμε ρητά τα μέλη δεδομένων (όπως ιδιότητες) και να αρνηθούμε τη δημιουργία των @ref{1bf,,__dict__} και `__weakref__' (εκτός εάν δηλώνεται ρητά στο `__slots__' ή είναι διαθέσιμο σε έναν γονέα.)

Ο χώρος που εξοικονομείται χρησιμοποιώντας @ref{1bf,,__dict__} μπορεί να είναι σημαντικός. Η ταχύτητα αναζήτησης χαρακτηριστικών μπορεί επίσης να βελτιωθεί σημαντικά.

@geindex object.__slots__ (ενσωματωμένη μεταβλητή)
@anchor{reference/datamodel object __slots__}@anchor{188d}
@deffn {Δεδομένα} object.__slots__

Σε αυτήν την μεταβλητή κλάσης μπορεί να εκχωρηθεί μια συμβολοσειρά, iterable ή ακολουθία συμβολοσειρών με ονόματα μεταβλητών που χρησιμοποιούνται από στιγμιότυπα. Το `__slots__' διατηρεί χώρο για τις δηλωμένες μεταβλητές και αποτρέπει την αυτόματη δημιουργία των @ref{1bf,,__dict__} και `__weakref__' για κάθε περίπτωση.
@end deffn
@anchor{reference/datamodel datamodel-note-slots}@anchor{25af}
Σημειώσεις σχετικά με τη χρήση `__slots__':


@itemize *

@item 
Όταν γίνεται κληρονομιά από μια κλάση χωρίς `__slots__', το χαρακτηριστικό @ref{1bf,,__dict__} και `__weakref__' των στιγμιοτύπων θα είναι πάντα προσβάσιμο.

@item 
Χωρίς μια μεταβλητή @ref{1bf,,__dict__}, τα στιγμιότυπα δεν μπορούν να αντιστοιχιστούν σε νέες μεταβλητές που δεν αναφέρονται στον ορισμό `__slots__'.  Οι προσπάθειες αντιστοίχισης σε ένα όνομα μεταβλητής εκτός λίστας κάνουν raise τη @ref{1a9,,AttributeError}. Εάν είναι επιθυμητή η δυναμική αντιστοίχιση νέων μεταβλητών, τότε προσθέστε το @code{'__dict__'} στην ακολουθία συμβολοσειρών στη δήλωση `__slots__'.

@item 
Χωρίς μια μεταβλητή `__weakref__' για κάθε στιγμιότυπο, οι κλάσεις που ορίζουν `__slots__' δεν υποστηρίζουν @ref{11d,,weak references} στα στιγμιότυπα τους. Εάν απαιτείται αδύναμη υποστήριξη για αδύναμες αναφορές, τότε προσθέστε το @code{'__weakref__'} στην ακολουθία των συμβολοσειρών στη δήλωση των `__slots__'.

@item 
Τα `__slots__' υλοποιούνται σε επίπεδα κλάσης με τη δημιουργία @ref{100d,,descriptors} για κάθε όνομα μεταβλητής.  Ως ένα αποτέλεσμα, οι ιδιότητες της κλάσης δεν μπορούν να χρησιμοποιηθούν για να ορίσουν προεπιλεγμένες τιμές για μεταβλητές στιγμιοτύπων που έχουν δηλωθεί μέσω  `__slots__' ∙ διαφορετικά, το χαρακτηριστικό της κλάσης θα αντικαθιστούσε την ανάθεση του descriptor.

@item 
Η ενέργεια μιας δήλωσης `__slots__' δεν περιορίζεται μόνο στην κλάση όπου ορίζεται. Τα `__slots__' που δηλώνονται σε γονικές κλάσεις είναι διαθέσιμα και στις θυγατρικές κλάσεις. Ωστόσο, οι θυγατρικές κλάσεις θα αποκτήσουν ένα @ref{1bf,,__dict__} και `__weakref__', εκτός αν δηλώσουν και οι ίδιες `__slots__' (τα οποία θα πρέπει να περιέχουν μόνο τα `επιπλέον' ονόματα slots).

@item 
Αν μια κλάση ορίσει ένα slot που έχει ήδη οριστεί σε μια γονική κλάση, τότε η μεταβλητή στιγμιοτύπου που ορίζεται από το slot της γονικής κλάσης γίνεται μη προσβάσιμη (εκτός αν ανακτηθεί απευθείας ο descriptor της από τη γονική κλάση). Αυτό καθιστά το νόημα του προγράμματος ασαφές.  Στο μέλλον, μπορεί να προστεθεί έλεγχος που να αποτρέπει κάτι τέτοιο.

@item 
@ref{291,,TypeError} will be raised if `__slots__' other than `__dict__' and
`__weakref__' are defined for a class derived from a
@ref{25b0,,"variable-length" built-in type} such as
@ref{326,,int}, @ref{1c7,,bytes}, and @ref{186,,type}, except @ref{1ce,,tuple}.

@item 
Οποιαδήποτε μη συμβολοσειρά @ref{15ce,,iterable} μπορεί να εκχωρηθεί σε `__slots__'.

@item 
Αν χρησιμοποιηθεί μια @ref{188,,dictionary} για την ανάθεση των `__slots__', τα κλειδιά του λεξικού θα χρησιμοποιηθούν ως ονόματα των slots. Οι τιμές του λεξικού μπορούν να χρησιμοποιηθούν για να παρέχουν τεκμηρίωση (docstrings) για κάθε ιδιότητα ξεχωριστά, η οποία θα αναγνωρίζεται από τη συνάρτηση @ref{22c,,inspect.getdoc()} και θα εμφανίζεται στην έξοδο της @ref{ca9,,help()}.

@item 
Η ανάθεση στη @ref{184f,,__class__} λειτουργεί μόνο αν και οι δύο κλάσεις έχουν τα ίδια `__slots__'.

@item 
@ref{2291,,Multiple inheritance} with multiple slotted parent
classes can be used,
but only one parent is allowed to have attributes created by slots
(the other bases must have empty slot layouts) - violations raise
@ref{291,,TypeError}.

@item 
Εάν χρησιμοποιείται ένας @ref{6ce,,iterator} για `__slots__' τότε δημιουργείται ένας @ref{21f,,descriptor} για κάθε μία από τις τιμές του iterator. Ωστόσο, το χαρακτηριστικό `__slots__' θα είναι ένας κενός iterator.
@end itemize


Άλλαξε στην έκδοση 3.15: Allowed defining the `__dict__' and `__weakref__' `__slots__' for any class.
Allowed defining any `__slots__' for a class derived from @ref{1ce,,tuple}.


@node Προσαρμογή δημιουργίας κλάσης,Προσαρμογή ελέγχων παρουσίας και υποκλάσης,Προσαρμογή πρόσβασης χαρακτηριστικών,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel class-customization}@anchor{1009}@anchor{reference/datamodel customizing-class-creation}@anchor{25b1}
@subsubsection Προσαρμογή δημιουργίας κλάσης


Όποτε μια κλάση κληρονομεί από μια άλλη κλάση, τη @ref{a22,,__init_subclass__()} καλείται μια γονική κλάση. Με αυτόν τον τρόπο, είναι δυνατόν να γραφτούν κλάσεις που αλλάζουν τη συμπεριφορά των υποκλάσεων. Αυτό σχετίζεται στενά με τους decorators των κλάσεων, αλλά όπου οι decorators κλάσεων επηρεάζουν μόνο τη συγκεκριμένη κλάση στην οποία εφαρμόζονται, το @code{__init_subclass__} ισχύει αποκλειστικά για μελλοντικές υποκλάσεις της κλάσης που ορίζουν τη μέθοδο.

@geindex __init_subclass__() (μέθοδος κλάσης της object)
@anchor{reference/datamodel object __init_subclass__}@anchor{a22}
@deffn {Μέθοδος} classmethod object.__init_subclass__ (cls)

Αυτή η μέθοδος καλείται κάθε φορά που η κλάση περιέχει υποκλάση. Το `cls' είναι τότε η νέα υποκλάση. Εάν οριστεί ως μια κανονική μέθοδος στιγμιοτύπου, αυτή η μέθοδος μετατρέπεται σιωπηρά σε μέθοδο κλάσης.

Τα ορίσματα λέξεων-κλειδιών που δίνονται σε μια νέα κλάση μεταβιβάζονται στη @code{__init_subclass__}. Για συμβατότητα με άλλες κλάσεις που χρησιμοποιούν @code{__init_subclass__}, θα πρέπει να αφαιρεθούν τα απαραίτητα ορίσματα λέξεων-κλειδιών και να περάσουν τα άλλα στη βασική κλάση, όπως στο:

@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

Η προεπιλεγμένη υλοποίηση @code{object.__init_subclass__} δεν κάνει τίποτα, αλλά δημιουργεί ένα σφάλμα εάν καλείται με οποιαδήποτε ορίσματα.

@cartouche
@quotation Σημείωση 
Η υπόδειξη μετακλάσης @code{metaclass} καταναλώνεται από τα υπόλοιπα μηχανήματα τύπου και δεν μεταβιβάζεται ποτέ στις υλοποιήσεις @code{__init_subclass__}. Η πραγματική μετακλάση (και όχι η ρητή υπόδειξη) μπορεί να προσπελαστεί ως @code{type(cls)}.
@end quotation
@end cartouche


Added in version 3.6.

@end deffn

Όταν δημιουργείται μια κλάση, η @code{type.__new__()} σαρώνει τις μεταβλητές κλάσης και πραγματοποιεί επανάκληση σε εκείνες με ένα @ref{100c,,__set_name__()} hook.

@geindex __set_name__() (μέθοδος της object)
@anchor{reference/datamodel object __set_name__}@anchor{100c}
@deffn {Μέθοδος} object.__set_name__ (self, owner, name)

Καλείται αυτόματα τη στιγμή που δημιουργείται η ιδιοκτήτρια κλάση `owner'. Το αντικείμενο έχει εκχωρηθεί στο `name' σε αυτήν την κλάση:

@example
class A:
    x = C()  # Automatically calls: x.__set_name__(A, 'x')
@end example

Εάν η μεταβλητή κλάσης εκχωρηθεί μετά τη δημιουργία της κλάσης, η @ref{100c,,__set_name__()} δεν θα κληθεί αυτόματα. Εάν χρειάζεται, η @code{__set_name__()} μπορεί να κληθεί απευθείας:

@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

Δείτε το @ref{1008,,Δημιουργία αντικειμένου κλάσης} για περισσότερες λεπτομέρειες.


Added in version 3.6.

@end deffn

@menu
* Μετα-κλάσεις:: 
* Επίλυση εγγραφών MRO:: 
* Προσδιορισμός της κατάλληλης μετακλάσης:: 
* Προετοιμασία του χώρου ονομάτων της κλάσης:: 
* Εκτέλεση του σώματος της κλάσης:: 
* Δημιουργία αντικειμένου κλάσης:: 
* Χρήσεις για μετακλάσεις:: 

@end menu

@node Μετα-κλάσεις,Επίλυση εγγραφών MRO,,Προσαρμογή δημιουργίας κλάσης
@anchor{reference/datamodel id14}@anchor{25b2}@anchor{reference/datamodel metaclasses}@anchor{25b3}
@subsubsection Μετα-κλάσεις


@geindex μετακλάση
@geindex ενσωματωμένη συνάρτηση;τύπος
@geindex = (ισοδυναμεί);ορισμός κλάσης

Από προεπιλογή, οι κλάσεις κατασκευάζονται χρησιμοποιώντας @ref{186,,type()}. Το σώμα κλάσης εκτελείται σε νέο χώρο ονομάτων και το όνομα της κλάσης συνδέεται τοπικά με το αποτέλεσμα του @code{type(name, bases, namespace)}.

Η διαδικασία δημιουργία κλάσης μπορεί να προσαρμοστεί μεταβιβάζοντας το όρισμα λέξης-κλειδιού @code{metaclass} στη γραμμή ορισμού κλάσης ή κληρονομώντας από μια υπάρχουσα κλάση που περιλάμβανε ένα τέτοιο όρισμα. Στο παρακάτω παράδειγμα, τόσο το @code{MyClass} και @code{MySubclass} είναι περιπτώσεις του @code{Meta}:

@example
class Meta(type):
    pass

class MyClass(metaclass=Meta):
    pass

class MySubclass(MyClass):
    pass
@end example

Οποιαδήποτε άλλα ορίσματα λέξης-κλειδιού που καθορίζονται στον ορισμό κλάσης μεταβιβάζονται σε όλες τις λειτουργίες μετακλάσης που περιγράφονται παρακάτω.

Όταν εκτελείται ένας ορισμός κλάσης, εμφανίζονται τα ακόλουθα βήματα:


@itemize *

@item 
Οι εγγραφές MRO επιλύονται∙

@item 
καθορίζεται η κατάλληλη μετακλάση∙

@item 
προετοιμάζεται ο χώρος ονομάτων της κλάσης∙

@item 
εκτελείται το σώμα της κλάσης∙

@item 
δημιουργείται το αντικείμενο της κλάσης.
@end itemize

@node Επίλυση εγγραφών MRO,Προσδιορισμός της κατάλληλης μετακλάσης,Μετα-κλάσεις,Προσαρμογή δημιουργίας κλάσης
@anchor{reference/datamodel resolving-mro-entries}@anchor{25b4}
@subsubsection Επίλυση εγγραφών MRO


@geindex __mro_entries__() (μέθοδος της object)
@anchor{reference/datamodel object __mro_entries__}@anchor{eb1}
@deffn {Μέθοδος} object.__mro_entries__ (self, bases)

Εάν μια βάση που εμφανίζεται σε ένα ορισμό κλάσης δεν είναι ένα στιγμιότυπο της @ref{186,,type}, τότε γίνεται αναζήτηση στη βάση μιας @code{__mro_entries__()} μεθόδου. Εάν βρεθεί μια μέθοδος @code{__mro_entries__()}, η βάση αντικαθίσταται με το αποτέλεσμα μιας κλήσης στο @code{__mro_entries__()} κατά τη δημιουργία της κλάσης. Η μέθοδος καλείται με την αρχική πλειάδα βάσεων μεταβιβασμένη στην παράμετρο `bases' και πρέπει να επιστρέψει μια πλειάδα κλάσεων που θα χρησιμοποιηθούν αντί για τη βάση. Η πλειάδα που επιστράφηκε μπορεί να είναι κενή: σε αυτές τις περιπτώσεις, η αρχική βάση αγνοείται.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item @ref{f5b,,types.resolve_bases()}

Επιλύστε δυναμικά βάσεις που δεν είναι στιγμιότυπα του @ref{186,,type}.

@item @ref{8de,,types.get_original_bases()}

Ανακτήσετε τις «αρχικές βάσεις» μιας κλάσης πριν από τις τροποποιήσεις από @ref{eb1,,__mro_entries__()}.

@geindex Python Enhancement Proposals; PEP 560

@item PEP 560@footnote{https://peps.python.org/pep-0560/}

Βασική υποστήριξη για modules τύπων και γενικούς τύπους.
@end table


@node Προσδιορισμός της κατάλληλης μετακλάσης,Προετοιμασία του χώρου ονομάτων της κλάσης,Επίλυση εγγραφών MRO,Προσαρμογή δημιουργίας κλάσης
@anchor{reference/datamodel determining-the-appropriate-metaclass}@anchor{25b5}@anchor{reference/datamodel metaclass-determination}@anchor{25b6}
@subsubsection Προσδιορισμός της κατάλληλης μετακλάσης


@geindex υπόδειξη μετακλάσης

Η κατάλληλη μετακλάση για έναν ορισμό κλάσης καθορίζεται ως εξής:


@itemize *

@item 
εάν δεν δίνονται βάσεις και καμία ρητή μετακλάση, τότε χρησιμοποιείται η @ref{186,,type()} ∙

@item 
εάν δοθεί μια ρητή μετακλάση και `δεν' είναι ένα στιγμιότυπο της @ref{186,,type()}, τότε χρησιμοποιείται απευθείας ως μετακλάση∙

@item 
εάν ένα στιγμιότυπο της @ref{186,,type()} δίνεται ως ρητή μετακλάση ή ορίζονται βάσεις, τότε χρησιμοποιείται η πιο παραγόμενη μετακλάση.
@end itemize

Η πιο παραγόμενη μετακλάση επιλέγεται από τη ρητά καθορισμένη μετακλάση (εάν υπάρχει) και τις μετακλάσεις (δηλαδή @code{type(cls)}) όλων των καθορισμένων βασικών κλάσεων. Η πιο παραγόμενη μετακλάση είναι αυτή που είναι υπο-τύπος `όλων' αυτών των υποψήφιων μετακλάσεων. Εάν καμία από τις υποψήφιες μετακλάσεις δεν πληροί αυτό το κριτήριο, τότε ο ορισμός της κλάσης θα αποτύχει με @code{TypeError}.

@node Προετοιμασία του χώρου ονομάτων της κλάσης,Εκτέλεση του σώματος της κλάσης,Προσδιορισμός της κατάλληλης μετακλάσης,Προσαρμογή δημιουργίας κλάσης
@anchor{reference/datamodel prepare}@anchor{101c}@anchor{reference/datamodel preparing-the-class-namespace}@anchor{25b7}
@subsubsection Προετοιμασία του χώρου ονομάτων της κλάσης


@geindex __prepare__ (μέθοδος μετακλάσης)

Μόλις εντοπιστεί η κατάλληλη μετακλάση, τότε προετοιμάζεται ο χώρος ονομάτων της κλάσης. Εάν η μετακλάση έχει ένα χαρακτηριστικό @code{__prepare__}, ονομάζεται @code{namespace = metaclass.__prepare__(name, bases, **kwds)} (όπου τα πρόσθετα ορίσματα λέξης-κλειδιού, εάν υπάρχουν, προέρχονται από τον ορισμό της κλάσης). Η μέθοδος @code{__prepare__} θα πρέπει να υλοποιηθεί ως μέθοδος @ref{69a,,classmethod}. Ο χώρος ονομάτων που επιστρέφεται από το @code{__prepare__} μεταβιβάζεται στο @code{__new__}, αλλά όταν δημιουργείται το τελικό αντικείμενο κλάσης, ο χώρος ονομάτων αντιγράφεται σε ένα νέο @code{dict}.

Εάν η μετακλάση δεν έχει χαρακτηριστικό @code{__prepare__}, τότε ο χώρος ονομάτων κλάσης αρχικοποιείται ως κενή ταξινομημένη αντιστοίχιση.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 3115

@item PEP 3115@footnote{https://peps.python.org/pep-3115/} - Μετακλάσεις στην Python 3000

Παρουσιάστηκε το άγκιστρο χώρου ονομάτων @code{__prepare__}
@end table


@node Εκτέλεση του σώματος της κλάσης,Δημιουργία αντικειμένου κλάσης,Προετοιμασία του χώρου ονομάτων της κλάσης,Προσαρμογή δημιουργίας κλάσης
@anchor{reference/datamodel executing-the-class-body}@anchor{25b8}
@subsubsection Εκτέλεση του σώματος της κλάσης


@geindex κλάση;σώμα

Το σώμα της κλάσης εκτελείται (περίπου) ως @code{exec(body, globals(), namespace)}. Η βασική διαφορά από μια κανονική κλήση στην @ref{185,,exec()} είναι ότι το λεξικό πεδίο εφαρμογής επιτρέπει στο σώμα της κλάσης (συμπεριλαμβανομένων οποιωνδήποτε μεθόδων) να παραπέμπει σε ονόματα από το τρέχον και το εξωτερικό πεδίο εφαρμογής όταν ο ορισμός κλάσης εμφανίζεται μέσα σε μια συνάρτηση.

Ωστόσο, ακόμα και όταν ο ορισμός της κλάσης εμφανίζεται μέσα στη συνάρτηση, οι μέθοδοι που ορίζονται μέσα στην κλάση εξακολουθούν να μην μπορούν να δουν ονόματα που ορίζονται στο πεδίο της κλάσης. Οι μεταβλητές κλάσης πρέπει να είναι προσβάσιμες μέσω της πρώτης παραμέτρου των μεθόδων στιγμιοτύπου ή κλάσης ή μέσω της σιωπηρής αναφοράς @code{__class__} με λεξικό που περιγράφεται στην επόμενη ενότητα.

@node Δημιουργία αντικειμένου κλάσης,Χρήσεις για μετακλάσεις,Εκτέλεση του σώματος της κλάσης,Προσαρμογή δημιουργίας κλάσης
@anchor{reference/datamodel class-object-creation}@anchor{1008}@anchor{reference/datamodel creating-the-class-object}@anchor{25b9}
@subsubsection Δημιουργία αντικειμένου κλάσης


@geindex __class__ (κελί που περιέχει μέθοδο)
@geindex __classcell__ (καταχώρηση στο namespace της κλάσης)

Μόλις ο χώρος ονομάτων της κλάσης έχει συμπληρωθεί εκτελώντας το σώμα της κλάσης, το αντικείμενο της κλάσης δημιουργείται καλώντας @code{metaclass(name, bases, namespace, **kwds)} (οι πρόσθετε λέξεις-κλειδιά που μεταβιβάζονται εδώ είναι οι ίδιες με αυτές που διαβιβάζονται στο @code{__prepare__}).

Αυτό το αντικείμενο κλάσης είναι αυτό που θα αναφέρεται με τη μορφή μηδενικού ορίσματος του @ref{443,,super()}. Το @code{__class__} είναι μια σιωπηρή αναφορά κλεισίματος που δημιουργείται από τον μεταγλωττιστή εάν οποιεσδήποτε μέθοδοι σε ένα σώμα κλάσης αναφέρονται είτε σε @code{__class__} είτε σε @code{super}. Αυτό επιτρέπει στη μορφή μηδενικού ορίσματος του @code{super()} να προσδιορίζει σωστά την κλάση που ορίζεται με βάση το λεξικό πεδίο εφαρμογής, ενώ η κλάση ή το παράδειγμα που χρησιμοποιήθηκε για την πραγματοποίηση της τρέχουσας κλήσης προσδιορίζεται με βάση το πρώτο όρισμα που μεταβιβάστηκε στη μέθοδο.

Στη CPython 3.6 και μεταγενέστερα, το κελί @code{__class__} μεταβιβάζεται στην μετακλάση ως μια καταχώρηση @code{__classcell__} στον χώρο ονομάτων της κλάσης. Εάν υπάρχει, αυτό πρέπει να διαδοθεί μέχρι την κλήση @code{type.__new__}, προκειμένου η κλάση να έχει ως αποτέλεσμα να αρχικοποιηθεί σωστά ώστε να γίνει σωστά. Αν δεν το κάνετε αυτό θα έχει ως αποτέλεσμα μια @ref{30d,,RuntimeError} στην Python 3.8.

Κατά τη χρήση της προεπιλεγμένης μετακλάσης @ref{186,,type} ή οποιασδήποτε μετακλάσης που τελικά καλεί @code{type.__new__}, τα ακόλουθα πρόσθετα βήματα προσαρμογής καλούνται μετά τη δημιουργία του αντικείμενου κλάσης:


@enumerate 

@item 
Η μέθοδος @code{type.__new__} συλλέγει όλα τα χαρακτηριστικά στον χώρο ονομάτων της κλάσης που ορίζουν μια μέθοδο @ref{100c,,__set_name__()} ∙

@item 
Αυτές οι μέθοδοι @code{__set_name__} καλούνται με την κλάση που ορίζεται και το εκχωρημένο όνομα του συγκεκριμένου χαρακτηριστικού∙

@item 
Το άγκιστρο @ref{a22,,__init_subclass__()} καλείται στον άμεσο γονέα της νέας κλάσης στη σειρά ανάλυσης της μεθόδου.
@end enumerate

Αφού δημιουργηθεί το αντικείμενο κλάσης, μεταβιβάζεται στους decorators κλάσης που περιλαμβάνονται στον ορισμό της κλάσης (εάν υπάρχει) και το αντικείμενο που προκύπτει δεσμεύεται στον τοπικό χώρο ονομάτων ως η καθορισμένη κλάση.

Όταν δημιουργείται μια νέα κλάση από @code{type.__new__}, το αντικείμενο που παρέχεται ως παράμετρος στο χώρο ονομάτων αντιγράφεται σε μια νέα ταξινομημένη αντιστοίχιση και το αρχικό αντικείμενο απορρίπτεται. Το νέο αντίγραφο τυλίγεται σε έναν διακομιστή μεσολάβησης μόνο για ανάγνωση, ο οποίος γίνεται το χαρακτηριστικό @ref{101b,,__dict__} του αντικειμένου κλάσης.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 3135

@item PEP 3135@footnote{https://peps.python.org/pep-3135/} - Νέο super

Περιγράφει την σιωπηρή αναφορά κλεισίματος @code{__class__}
@end table


@node Χρήσεις για μετακλάσεις,,Δημιουργία αντικειμένου κλάσης,Προσαρμογή δημιουργίας κλάσης
@anchor{reference/datamodel uses-for-metaclasses}@anchor{25ba}
@subsubsection Χρήσεις για μετακλάσεις


Οι πιθανές χρήσεις για μετακλάσεις είναι απεριόριστες. Ορισμένες ιδέες που έχουν διερευνηθεί περιλαμβάνουν το enum, την καταγραφή, τον έλεγχο διεπαφής, την αυτόματα ανάθεση την αυτόματη δημιουργία ιδιοτήτων, τους διακομιστές μεσολάβησης, τα πλαίσια και το αυτόματο κλείδωμα/συγχρονισμό πόρων.

@node Προσαρμογή ελέγχων παρουσίας και υποκλάσης,Εξομοίωση γενικών τύπων,Προσαρμογή δημιουργίας κλάσης,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel customizing-instance-and-subclass-checks}@anchor{25bb}
@subsubsection Προσαρμογή ελέγχων παρουσίας και υποκλάσης


Οι ακόλουθες μέθοδοι χρησιμοποιούνται για την παράκαμψη της προεπιλεγμένης συμπεριφοράς των ενσωματωμένων συναρτήσεων @ref{2ef,,isinstance()} και @ref{2f0,,issubclass()}.

Συγκεκριμένα, η μετακλάση @ref{12c9,,abc.ABCMeta} υλοποιεί αυτές τις μεθόδους προκειμένου να επιτρέψει την προσθήκη Αφηρημένων Βασικών Κλάσεων (ABCs) ως «εικονικές βασικές κλάσεις» σε οποιαδήποτε κλάση ή τύπο (συμπεριλαμβανομένων των ενσωματωμένων τύπων), συμπεριλαμβανομένων άλλων ABCs.

@geindex __instancecheck__() (μέθοδος της type)
@anchor{reference/datamodel type __instancecheck__}@anchor{25bc}
@deffn {Μέθοδος} type.__instancecheck__ (self, instance)

Επιστρέφετε true εάν το `instance' θα πρέπει να θεωρείται ένα (άμεσο ή έμμεσο) στιγμιότυπο της `class'. Εάν ορίζεται, καλείται να υλοποιήσει @code{isinstance(instance, class)}.
@end deffn

@geindex __subclasscheck__() (μέθοδος της type)
@anchor{reference/datamodel type __subclasscheck__}@anchor{25bd}
@deffn {Μέθοδος} type.__subclasscheck__ (self, subclass)

Επιστρέφετε true εάν η `subclass' πρέπει να θεωρείται μια (άμεση ή έμμεση) υποκλάση της `class'.  Εάν ορίζεται, καλείται να υλοποιήσει @code{issubclass(subclass, class)}.
@end deffn

Λάβετε υπόψη ότι αυτές οι μέθοδοι αναζητούνται στον τύπο (μετακλάση) μιας κλάσης.  Δεν μπορούν να οριστούν ως μέθοδοι κλάσης στην πραγματική κλάση.  Αυτό είναι σύμφωνο με την αναζήτηση ειδικών μεθόδων που καλούνται σε στιγμιότυπα, μόνο σε αυτήν την περίπτωση το ίδιο στιγμιότυπο είναι μια κλάση.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 3119

@item PEP 3119@footnote{https://peps.python.org/pep-3119/} - Εισάγοντας τις Αφηρημένες Βασικές Κλάσεις

Περιλαμβάνει την προδιαγραφή για την προσαρμογή της συμπεριφορά της @ref{2ef,,isinstance()} και της @ref{2f0,,issubclass()} μέσω των @ref{25bc,,__instancecheck__()} και @ref{25bd,,__subclasscheck__()}, με κίνητρο για αυτήν τη λειτουργικότητα στο πλαίσιο της προσθήκης Αφηρημένης Βασικής Κλάσης (δείτε το module @ref{4,,abc}) στη γλώσσα.
@end table


@node Εξομοίωση γενικών τύπων,Εξομοίωση αντικειμένων με δυνατότητα κλήσης,Προσαρμογή ελέγχων παρουσίας και υποκλάσης,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel emulating-generic-types}@anchor{25be}
@subsubsection Εξομοίωση γενικών τύπων


Όταν χρησιμοποιείτε το @ref{409,,type annotations}, είναι συχνά χρήσιμο να `παραμετροποιήσετε' έναν @ref{1d1,,generic type} χρησιμοποιώντας τον συμβολισμό σε αγκύλες της Python. Για παράδειγμα, το annotation @code{list[int]} μπορεί να χρησιμοποιηθεί για να υποδηλώσει μια @ref{4d9,,list} στην οποία όλα τα στοιχεία της κλάσης είναι τύπου @ref{326,,int}.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 484

@item PEP 484@footnote{https://peps.python.org/pep-0484/} - Τύπος Hints

Εισάγοντας το πλαίσιο της Python για τύπους annotations

@item @ref{a9f,,Generic Alias Types}

Τεκμηρίωση για αντικείμενα που αντιπροσωπεύουν παραμετροποιημένες γενικές κλάσεις

@item @ref{25bf,,Generics}, @ref{8df,,user-defined generics} και @ref{19f2,,typing.Generic}

Τεκμηρίωση για τον τρόπο υλοποίησης γενικών κλάσεων που μπορούν να παραμετροποιηθούν κατά το χρόνο εκτέλεσης και να κατανοηθούν από στατικούς ελεγκτές τύπων.
@end table


Μια κλάση `γενικά' μπορεί να παραμετροποιηθεί μόνο εάν ορίζει την ειδική μέθοδο κλάσης @code{__class_getitem__()}.

@geindex __class_getitem__() (μέθοδος κλάσης της object)
@anchor{reference/datamodel object __class_getitem__}@anchor{b21}
@deffn {Μέθοδος} classmethod object.__class_getitem__ (cls, key)

Επιστρέφετε ένα αντικείμενο που αντιπροσωπεύει την εξειδίκευση μιας γενικής κλάσης κατά ορίσματα τύπου που βρίσκονται στο `key'.

Όταν ορίζεται σε μια κλάση, το @code{__class_getitem__()} είναι αυτόματα μέθοδος κλάσης. Ως εκ τούτου, δεν χρειάζεται να γίνει decorated με @ref{69a,,@@classmethod} όταν ορίζεται.
@end deffn

@menu
* Ο σκοπός του __class_getitem__:: 
* __class_getitem__ έναντι __getitem__:: 

@end menu

@node Ο σκοπός του __class_getitem__,__class_getitem__ έναντι __getitem__,,Εξομοίωση γενικών τύπων
@anchor{reference/datamodel the-purpose-of-class-getitem}@anchor{25c0}
@subsubsection Ο σκοπός του `__class_getitem__'


Ο σκοπός της @ref{b21,,__class_getitem__()} είναι να επιτρέψει την παραμετροποίηση χρόνου εκτέλεσης των γενικών κλάσεων τυπικής βιβλιοθήκης προκειμένου να εφαρμοστούν πιο εύκολα @ref{25c1,,type hints} σε αυτές τις κλάσεις.

Για να εφαρμόσουν προσαρμοσμένες γενικές κλάσεις που μπορούν να παραμετροποιηθούν κατά το χρόνο εκτέλεσης και να κατανοηθούν από στατικούς ελεγκτές τύπων, οι χρήστες θα πρέπει είτε να κληρονομήσουν από μια τυπική κλάση βιβλιοθήκης που ήδη υλοποιεί τη @ref{b21,,__class_getitem__()}, είτε να κληρονομήσουν από την @ref{19f2,,typing.Generic}, η οποία έχει τη δική της υλοποίηση του @code{__class_getitem__()}.

Προσαρμοσμένες υλοποιήσεις της @ref{b21,,__class_getitem__()} σε κλάσεις που ορίζονται εκτός της τυπικής βιβλιοθήκης ενδέχεται να μην είναι κατανοητές από ελεγκτές τύπων τρίτου μέρους, όπως το mypy. Η χρήση @code{__class_getitem__()} σε οποιαδήποτε κλάση για άλλους σκοπούς εκτός από την υπόδειξη τύπων δεν ενθαρρύνεται.

@node __class_getitem__ έναντι __getitem__,,Ο σκοπός του __class_getitem__,Εξομοίωση γενικών τύπων
@anchor{reference/datamodel class-getitem-versus-getitem}@anchor{25c2}@anchor{reference/datamodel classgetitem-versus-getitem}@anchor{25c3}
@subsubsection `__class_getitem__' έναντι `__getitem__'


Συνήθως, η @ref{2599,,subscription} ενός αντικειμένου που χρησιμοποιεί αγκύλες θα καλεί τη μέθοδο του στιγμιοτύπου @ref{787,,__getitem__()} που ορίζεται στην κλάση του αντικειμένου. Ωστόσο, εάν το αντικείμενο που εγγράφεται είναι το ίδιο μια κλάση, η μέθοδος της κλάσης @ref{b21,,__class_getitem__()} μπορεί να κληθεί αντί να γίνει. Το @code{__class_getitem__()} θα πρέπει να επιστρέψει ένα αντικείμενο @ref{a9f,,GenericAlias}, εάν έχει οριστεί σωστά.

Παρουσιάζεται με το @ref{25c4,,expression} @code{obj[x]}, ο διερμηνέας Python ακολουθεί κάτι σαν την ακόλουθη διαδικασία για να αποφασίσει εάν θα πρέπει να κληθεί @ref{787,,__getitem__()} ή @ref{b21,,__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

Στην Python, όλες οι κλάσεις είναι οι ίδιες παρουσίες άλλων κλάσεων. Η κλάση μιας κλάσης είναι γνωστή ως @ref{25c5,,metaclass} αυτής της κλάσης, και οι περισσότερες κλάσεις έχουν ως μετακλάση την κλάση @ref{186,,type}. Η @code{type} δεν ορίζει το @ref{787,,__getitem__()}, πράγμα που σημαίνει ότι εκφράσεις όπως @code{list[int]}, @code{dict[str, float]} και @code{tuple[str, bytes]} έχουν ως αποτέλεσμα την κλήση της @ref{b21,,__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

Ωστόσο, εάν μια κλάση έχει μια προσαρμοσμένη μετακλάση που ορίζει @ref{787,,__getitem__()}, η εγγραφή στην κλάση μπορεί να οδηγήσει σε διαφορετική συμπεριφορά. Ένα παράδειγμα αυτού μπορεί να βρεθεί στο module @ref{59,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 560

@item PEP 560@footnote{https://peps.python.org/pep-0560/} - Βασική υποστήριξη για module πληκτρολόγησης και γενικούς τύπους

Παρουσίαση της @ref{b21,,__class_getitem__()}, και περιγραφή του πότε ένα @ref{2599,,subscription} έχει ως αποτέλεσμα την κλήση @code{__class_getitem__()} αντί για @ref{787,,__getitem__()}
@end table


@node Εξομοίωση αντικειμένων με δυνατότητα κλήσης,Εξομοίωση τύπων κοντέινερ,Εξομοίωση γενικών τύπων,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel emulating-callable-objects}@anchor{25c6}@anchor{reference/datamodel id15}@anchor{25c7}
@subsubsection Εξομοίωση αντικειμένων με δυνατότητα κλήσης


@geindex __call__() (μέθοδος της object)
@anchor{reference/datamodel object __call__}@anchor{961}
@deffn {Μέθοδος} object.__call__ (self[, args...])

@geindex κλήση;στιγμιότυπο

Καλείται όταν το στιγμιότυπο «καλείται» ως συνάρτηση∙ εάν αυτή η μέθοδος οριστεί, το @code{x(arg1, arg2, ...)} μεταφράζεται χονδρικά σε @code{type(x).__call__(x, arg1, ...)}. Η ίδια η κλάση @ref{e4d,,object} δεν παρέχει αυτήν τη μέθοδο.
@end deffn

@node Εξομοίωση τύπων κοντέινερ,Εξομοίωση αριθμητικών τύπων,Εξομοίωση αντικειμένων με δυνατότητα κλήσης,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel emulating-container-types}@anchor{25c8}@anchor{reference/datamodel sequence-types}@anchor{25c9}
@subsubsection Εξομοίωση τύπων κοντέινερ


Οι ακόλουθες μέθοδοι μπορούν να οριστούν για την υλοποίηση αντικειμένων κοντέινερ. Καμία από αυτές δεν παρέχεται από την ίδια την κλάση @ref{e4d,,object}. Τα κοντέινερ είναι συνήθως @ref{8ff,,sequences} (όπως @ref{4d9,,lists} ή @ref{1ce,,tuples}) ή @ref{1564,,mappings} (όπως @ref{25ca,,dictionaries}), αλλά τα λεξικά μπορούν επίσης να αντιπροσωπεύουν άλλα κοντέινερ.  Το πρώτο σύνολο μεθόδων χρησιμοποιείται είτε για την εξομοίωση μιας ακολουθίας είτε για την εξομοίωση μιας αντιστοίχισης∙ η διαφορά είναι ότι για μια ακολουθία, τα επιτρεπόμενα κλειδιά θα πρέπει να είναι οι ακέραιοι `k' για τους οποίους @code{0 <= k < N} όπου `N' είναι το μήκος της ακολουθίας, ή αντικείμενα @ref{1d0,,slice}, τα οποία ορίζουν ένα εύρος στοιχείων.  Συνίσταται επίσης οι αντιστοιχίσεις να παρέχουν τις μεθόδους @code{keys()}, @code{values()}, @code{items()}, @code{get()}, @code{clear()}, @code{setdefault()}, @code{pop()}, @code{popitem()}, @code{copy()}, και @code{update()} όπου συμπεριφέρονται παρόμοια με εκείνα για τα τυπικά αντικείμενα @ref{188,,dictionary} της Python.  Το module @ref{1f,,collections.abc} παρέχει μια @ref{1459,,MutableMapping} @ref{155f,,abstract base class} για να βοηθήσει στη δημιουργία αυτών των μεθόδων από ένα βασικό σύνολο @ref{787,,__getitem__()}, @ref{1670,,__setitem__()}, @ref{1671,,__delitem__()}, και @code{keys()}.

Οι μεταβλητές ακολουθίες θα πρέπει να παρέχουν μεθόδους @ref{25cb,,append()}, @ref{25cc,,clear()}, @ref{25cd,,count()}, @ref{25ce,,extend()}, @ref{1b8b,,index()}, @ref{25cf,,insert()}, @ref{25d0,,pop()}, @ref{1b8c,,remove()}, και @ref{25d1,,reverse()}, όπως τα πρότυπα Python @ref{4d9,,list} αντικείμενα. Τέλος, οι τύποι ακολουθιών θα πρέπει να υλοποιούν πρόσθεση (που σημαίνει συνένωση) και πολλαπλασιασμό (δηλαδή επανάληψη) ορίζοντας τις μεθόδους @ref{25d2,,__add__()}, @ref{25d3,,__radd__()}, @ref{25d4,,__iadd__()}, @ref{25d5,,__mul__()}, @ref{25d6,,__rmul__()} και @ref{25d7,,__imul__()} που περιγράφονται παρακάτω∙ δεν θα πρέπει να ορίζουν άλλους αριθμητικούς τελεστές.

Αυτό συνίσταται τόσο οι αντιστοιχίσεις όσο και οι ακολουθίες να εφαρμόζουν τη μέθοδο @ref{175c,,__contains__()} για να επιτρέπεται η αποτελεσματική χρήση του τελεστή @code{in} ∙ για αντιστοιχίσεις, το @code{in} θα πρέπει να αναζητήσει τα κλειδιά της αντιστοίχισης∙ για ακολουθίες θα πρέπει να αναζητήσει τις τιμές.  Συνίσταται περαιτέρω τόσο οι αντιστοιχίσεις όσο και οι ακολουθίες να εφαρμόζουν τη μέθοδο @ref{102d,,__iter__()} για να επιτρέπεται η αποτελεσματική επανάληψη μέσω του κοντέινερ∙ για αντιστοιχίσεις, η @code{__iter__()} θα πρέπει να επαναλαμβάνεται μέσω των κλειδιών του αντικειμένου∙ για ακολουθίες, θα πρέπει να επαναλαμβάνεται μέσω των τιμών.

@geindex __len__() (μέθοδος της object)
@anchor{reference/datamodel object __len__}@anchor{1989}
@deffn {Μέθοδος} object.__len__ (self)

@geindex ενσωματωμένη συνάρτηση;len
@geindex __bool__() (μέθοδος αντικειμένου)

Καλείται για την υλοποίηση της ενσωματωμένης συνάρτησης @ref{a1f,,len()}.  Θα πρέπει να επιστρέψει το μήκος του αντικειμένου, ένας ακέραιος αριθμός @code{>=} 0.  Επίσης, ένα αντικείμενο που δεν ορίζει μια μέθοδο @ref{167a,,__bool__()} και του οποίου η μέθοδος @code{__len__()} επιστρέφει μηδέν, θεωρείται ψευδές σε ένα Boolean περιβάλλον.

Στο CPython, το μήκος απαιτείται να είναι το πολύ @ref{156e,,sys.maxsize}. Εάν το μήκος είναι μεγαλύτερο από @code{sys.maxsize} ορισμένες δυνατότητες (όπως @ref{a1f,,len()}) ενδέχεται να αυξήσουν το @ref{c57,,OverflowError}.  Για να αποφευχθεί να γίνει raise @code{OverflowError} από τον έλεγχο τιμής αλήθειας, ένα αντικείμενο πρέπει να ορίσει μια μέθοδο @ref{167a,,__bool__()}.
@end deffn

@geindex __length_hint__() (μέθοδος της object)
@anchor{reference/datamodel object __length_hint__}@anchor{12bc}
@deffn {Μέθοδος} object.__length_hint__ (self)

Καλείται για υλοποίηση @ref{1317,,operator.length_hint()}. Θα πρέπει να επιστρέψει ένα εκτιμώμενο μήκος για το αντικείμενο (το οποίο μπορεί να είναι μεγαλύτερο ή μικρότερο από το πραγματικό μήκος). Το μήκος πρέπει να είναι ένας ακέραιος αριθμός @code{>=} 0. Η τιμή επιστροφής μπορεί επίσης να είναι @ref{440,,NotImplemented}, η οποία αντιμετωπίζεται με τον ίδιο τρόπο σαν να μην υπήρχε καθόλου η μέθοδος @code{__length_hint__}. Αυτή η μέθοδος είναι καθαρά βελτιστοποίηση και δεν απαιτείται ποτέ για ορθότητα.


Added in version 3.4.

@end deffn

@geindex __getitem__() (μέθοδος της object)
@anchor{reference/datamodel object __getitem__}@anchor{787}
@deffn {Μέθοδος} object.__getitem__ (self, subscript)

Called to implement `subscription', that is, @code{self[subscript]}.
See @ref{2599,,Subscriptions and slicings} for details on the syntax.

There are two types of built-in objects that support subscription
via @code{__getitem__()}:


@itemize -

@item 
`sequences', where `subscript' (also called
@ref{25d8,,index}) should be an integer or a @ref{1d0,,slice} object.
See the @ref{2529,,sequence documentation} for the expected
behavior, including handling @code{slice} objects and negative indices.

@item 
`mappings', where `subscript' is also called the @ref{25d9,,key}.
See @ref{2530,,mapping documentation} for the expected
behavior.
@end itemize

If `subscript' is of an inappropriate type, @code{__getitem__()}
should raise @ref{291,,TypeError}.
If `subscript' has an inappropriate value, @code{__getitem__()}
should raise an @ref{25da,,LookupError} or one of its subclasses
(@ref{18d7,,IndexError} for sequences; @ref{7df,,KeyError} for mappings).

@geindex αντικείμενο;slice

@cartouche
@quotation Σημείωση 
Slicing is handled by @code{__getitem__()}, @ref{1670,,__setitem__()},
and @ref{1671,,__delitem__()}.
A call like

@example
a[1:2] = b
@end example

μεταφράζεται σε

@example
a[slice(1, 2, None)] = b
@end example

and so forth. Missing slice items are always filled in with @code{None}.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
The sequence iteration protocol (used, for example, in @ref{321,,for}
loops), expects that an @ref{18d7,,IndexError} will be raised for illegal
indexes to allow proper detection of the end of a sequence.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
When @ref{2599,,subscripting} a `class', the special
class method @ref{b21,,__class_getitem__()} may be called instead of
@code{__getitem__()}. See @ref{25c3,,__class_getitem__ έναντι __getitem__} for more
details.
@end quotation
@end cartouche
@end deffn

@geindex __setitem__() (μέθοδος της object)
@anchor{reference/datamodel object __setitem__}@anchor{1670}
@deffn {Μέθοδος} object.__setitem__ (self, key, value)

Καλείται για την υλοποίηση της ανάθεσης στο @code{self[key]}. Ίδια σημείωση με το @ref{787,,__getitem__()}. Αυτό θα πρέπει να εφαρμοστεί μόνο για αντιστοιχίσεις εάν τα αντικείμενα υποστηρίζουν αλλαγές στις τιμές για κλειδιά ή εάν μπορούν να προστεθούν νέα κλειδιά ή για ακολουθίες εάν μπορούν να αντικατασταθούν στοιχεία.  Θα πρέπει να δημιουργηθούν οι ίδιες εξαιρέσεις για ακατάλληλες τιμές `key' όπως και για τη μέθοδο @code{__getitem__()}.
@end deffn

@geindex __delitem__() (μέθοδος της object)
@anchor{reference/datamodel object __delitem__}@anchor{1671}
@deffn {Μέθοδος} object.__delitem__ (self, key)

Κλήθηκε για την υλοποίηση της διαγραφής του @code{self[key]}. Ίδια σημείωση με το @ref{787,,__getitem__()}.  Αυτό θα πρέπει να εφαρμόζεται μόνο για αντιστοιχίσεις εάν τα αντικείμενα υποστηρίζουν την αφαίρεση πλήκτρων ή για ακολουθίες εάν μπορούν να αφαιρεθούν στοιχεία από την ακολουθία.  Θα πρέπει να δημιουργηθούν οι ίδιες εξαιρέσεις για ακατάλληλες τιμές `key' όπως και για τη μέθοδο @code{__getitem__()}.
@end deffn

@geindex __missing__() (μέθοδος της object)
@anchor{reference/datamodel object __missing__}@anchor{1566}
@deffn {Μέθοδος} object.__missing__ (self, key)

Κλήθηκε από @ref{188,,dict}.@ref{787,,__getitem__()} για την υλοποίηση του @code{self[key]} για υποκλάσεις dict όταν το κλειδί δεν υπάρχει στο λεξικό.
@end deffn

@geindex __iter__() (μέθοδος της object)
@anchor{reference/datamodel object __iter__}@anchor{102d}
@deffn {Μέθοδος} object.__iter__ (self)

Αυτή η μέθοδος καλείται όταν απαιτείται ένας @ref{6ce,,iterator} για ένα κοντέινερ. Αυτή η μέθοδος θα πρέπει να επιστρέψει ένα νέο αντικείμενο iterator που μπορεί να επαναλάβει όλα τα αντικείμενα στο κοντέινερ.  Για αντιστοιχίσεις, θα πρέπει να επαναλαμβάνεται πάνω από τα κλειδιά του κοντέινερ.
@end deffn

@geindex __reversed__() (μέθοδος της object)
@anchor{reference/datamodel object __reversed__}@anchor{1049}
@deffn {Μέθοδος} object.__reversed__ (self)

Καλείται (εάν υπάρχει) από την ενσωματωμένη @ref{c3c,,reversed()} για την υλοποίηση της αντίστροφης επανάληψης.  Θα πρέπει να επιστρέψει ένα νέο iterator αντικείμενο που επαναλαμβάνεται πάνω από όλα τα αντικείμενα στο κοντέινερ με αντίστροφη σειρά.

Εάν η μέθοδος @ref{1049,,__reversed__()} δεν παρέχεται, η ενσωματωμένη @ref{c3c,,reversed()} θα χρησιμοποιήσει το πρωτόκολλο ακολουθίας (@ref{1989,,__len__()} και @ref{787,,__getitem__()}).  Τα αντικείμενα που υποστηρίζουν το πρωτόκολλο ακολουθίας θα πρέπει να παρέχουν μόνο τη @code{__reversed__()} εάν μπορούν να παρέχουν μια υλοποίηση που είναι πιο αποτελεσματική από αυτή που παρέχεται από τη @code{reversed()}.
@end deffn

Οι τελεστές τεστ ιδιότητας μέλους (@ref{323,,in} και @ref{a20,,not in}) συνήθως υλοποιούνται ως επανάληψη μέσω ενός κοντέινερ. Ωστόσο, τα αντικείμενα κοντέινερ μπορούν να παρέχουν την ακόλουθη ειδική μέθοδο μια μια αποτελεσματική υλοποίηση, η οποία επίσης δεν απαιτεί το αντικείμενο να είναι επαναλαμβανόμενο.

@geindex __contains__() (μέθοδος της object)
@anchor{reference/datamodel object __contains__}@anchor{175c}
@deffn {Μέθοδος} object.__contains__ (self, item)

Καλείται για την εφαρμογή τελεστών δοκιμής ιδιότητας μέλους.  Θα πρέπει να επιστρέψει true εάν το `item' είναι στο `self', false διαφορετικά.  Για την αντιστοίχιση αντικειμένων, αυτό θα πρέπει να λαμβάνει υπόψη τα κλειδιά της αντιστοίχισης αντί για τις τιμές ή τα ζεύγη κλειδιών-στοιχείων.

Για αντικείμενα που δεν ορίζουν @ref{175c,,__contains__()}, το τεστ ιδιότητας δοκιμάζει πρώτα την επανάληψη μέσω @ref{102d,,__iter__()}, και μετά το παλιό πρωτόκολλο επανάληψης ακολουθίας μέσω @ref{787,,__getitem__()}, δείτε @ref{25db,,this section in the language reference}.
@end deffn

@node Εξομοίωση αριθμητικών τύπων,Με τους Διαχειριστές Περιβάλλοντος Δήλωσης,Εξομοίωση τύπων κοντέινερ,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel emulating-numeric-types}@anchor{25dc}@anchor{reference/datamodel numeric-types}@anchor{25dd}
@subsubsection Εξομοίωση αριθμητικών τύπων


Οι ακόλουθες μέθοδοι μπορούν να οριστούν για την εξομοίωση αριθμητικών αντικειμένων. Οι μέθοδοι που αντιστοιχούν σε πράξεις που δεν υποστηρίζονται από το συγκεκριμένο είδος αριθμού που υλοποιείται (π.χ. λειτουργίες bitwise για μη ακέραιους αριθμούς) θα πρέπει να παραμείνουν απροσδιόριστες.

@geindex __add__() (μέθοδος της object)
@geindex __sub__() (μέθοδος της object)
@geindex __mul__() (μέθοδος της object)
@geindex __matmul__() (μέθοδος της object)
@geindex __truediv__() (μέθοδος της object)
@geindex __floordiv__() (μέθοδος της object)
@geindex __mod__() (μέθοδος της object)
@geindex __divmod__() (μέθοδος της object)
@geindex __pow__() (μέθοδος της object)
@geindex __lshift__() (μέθοδος της object)
@geindex __rshift__() (μέθοδος της object)
@geindex __and__() (μέθοδος της object)
@geindex __xor__() (μέθοδος της object)
@geindex __or__() (μέθοδος της object)
@anchor{reference/datamodel object __add__}@anchor{25d2}
@deffn {Μέθοδος} object.__add__ (self, other)
@anchor{reference/datamodel object __sub__}@anchor{25de}
@deffnx {Μέθοδος} object.__sub__ (self, other)
@anchor{reference/datamodel object __mul__}@anchor{25d5}
@deffnx {Μέθοδος} object.__mul__ (self, other)
@anchor{reference/datamodel object __matmul__}@anchor{1132}
@deffnx {Μέθοδος} object.__matmul__ (self, other)
@anchor{reference/datamodel object __truediv__}@anchor{1241}
@deffnx {Μέθοδος} object.__truediv__ (self, other)
@anchor{reference/datamodel object __floordiv__}@anchor{1896}
@deffnx {Μέθοδος} object.__floordiv__ (self, other)
@anchor{reference/datamodel object __mod__}@anchor{25df}
@deffnx {Μέθοδος} object.__mod__ (self, other)
@anchor{reference/datamodel object __divmod__}@anchor{1242}
@deffnx {Μέθοδος} object.__divmod__ (self, other)
@anchor{reference/datamodel object __pow__}@anchor{bb1}
@deffnx {Μέθοδος} object.__pow__ (self, other[, modulo])
@anchor{reference/datamodel object __lshift__}@anchor{25e0}
@deffnx {Μέθοδος} object.__lshift__ (self, other)
@anchor{reference/datamodel object __rshift__}@anchor{25e1}
@deffnx {Μέθοδος} object.__rshift__ (self, other)
@anchor{reference/datamodel object __and__}@anchor{25e2}
@deffnx {Μέθοδος} object.__and__ (self, other)
@anchor{reference/datamodel object __xor__}@anchor{25e3}
@deffnx {Μέθοδος} object.__xor__ (self, other)
@anchor{reference/datamodel object __or__}@anchor{25e4}
@deffnx {Μέθοδος} object.__or__ (self, other)

@geindex ενσωματωμένη συνάρτηση;divmod
@geindex ενσωματωμένη συνάρτηση;pow
@geindex ενσωματωμένη συνάρτηση;pow

Αυτές οι μέθοδοι καλούνται να υλοποιήσουν τις δυαδικές αριθμητικές λειτουργίες (@code{+}, @code{-}, @code{*}, @code{@@}, @code{/}, @code{//}, @code{%}, @ref{d6a,,divmod()}, @ref{441,,pow()}, @code{**}, @code{<<}, @code{>>}, @code{&}, @code{^}, @code{|}). Για παράδειγμα, για να αξιολογηθεί η έκφραση @code{x + y}, όπου `x' είναι ένα στιγμιότυπο μιας κλάσης που έχει μια μέθοδο @ref{25d2,,__add__()}, καλείται το @code{type(x).__add__(x, y)}.  Η μέθοδος @ref{1242,,__divmod__()} θα πρέπει να είναι ισοδύναμη με τη χρήση των @ref{1896,,__floordiv__()} και @ref{25df,,__mod__()}; δεν θα πρέπει να σχετίζεται με τη @ref{1241,,__truediv__()}. Σημειώστε ότι η @ref{bb1,,__pow__()} θα πρέπει να ορίζεται ώστε να δέχεται ένα προαιρετικό τρίτο όρισμα εάν υποστηρίζεται η τριών ορισμάτων έκδοση της ενσωματωμένης συνάρτησης @code{pow()}.

Εάν μία από αυτές τις μεθόδους δεν υποστηρίζει τη λειτουργία με τα παρεχόμενα ορίσματα, θα πρέπει να επιστρέψει @ref{440,,NotImplemented}.
@end deffn

@geindex __radd__() (μέθοδος της object)
@geindex __rsub__() (μέθοδος της object)
@geindex __rmul__() (μέθοδος της object)
@geindex __rmatmul__() (μέθοδος της object)
@geindex __rtruediv__() (μέθοδος της object)
@geindex __rfloordiv__() (μέθοδος της object)
@geindex __rmod__() (μέθοδος της object)
@geindex __rdivmod__() (μέθοδος της object)
@geindex __rpow__() (μέθοδος της object)
@geindex __rlshift__() (μέθοδος της object)
@geindex __rrshift__() (μέθοδος της object)
@geindex __rand__() (μέθοδος της object)
@geindex __rxor__() (μέθοδος της object)
@geindex __ror__() (μέθοδος της object)
@anchor{reference/datamodel object __radd__}@anchor{25d3}
@deffn {Μέθοδος} object.__radd__ (self, other)
@anchor{reference/datamodel object __rsub__}@anchor{25e5}
@deffnx {Μέθοδος} object.__rsub__ (self, other)
@anchor{reference/datamodel object __rmul__}@anchor{25d6}
@deffnx {Μέθοδος} object.__rmul__ (self, other)
@anchor{reference/datamodel object __rmatmul__}@anchor{1133}
@deffnx {Μέθοδος} object.__rmatmul__ (self, other)
@anchor{reference/datamodel object __rtruediv__}@anchor{25e6}
@deffnx {Μέθοδος} object.__rtruediv__ (self, other)
@anchor{reference/datamodel object __rfloordiv__}@anchor{25e7}
@deffnx {Μέθοδος} object.__rfloordiv__ (self, other)
@anchor{reference/datamodel object __rmod__}@anchor{118e}
@deffnx {Μέθοδος} object.__rmod__ (self, other)
@anchor{reference/datamodel object __rdivmod__}@anchor{25e8}
@deffnx {Μέθοδος} object.__rdivmod__ (self, other)
@anchor{reference/datamodel object __rpow__}@anchor{442}
@deffnx {Μέθοδος} object.__rpow__ (self, other[, modulo])
@anchor{reference/datamodel object __rlshift__}@anchor{25e9}
@deffnx {Μέθοδος} object.__rlshift__ (self, other)
@anchor{reference/datamodel object __rrshift__}@anchor{25ea}
@deffnx {Μέθοδος} object.__rrshift__ (self, other)
@anchor{reference/datamodel object __rand__}@anchor{25eb}
@deffnx {Μέθοδος} object.__rand__ (self, other)
@anchor{reference/datamodel object __rxor__}@anchor{25ec}
@deffnx {Μέθοδος} object.__rxor__ (self, other)
@anchor{reference/datamodel object __ror__}@anchor{25ed}
@deffnx {Μέθοδος} object.__ror__ (self, other)

@geindex ενσωματωμένη συνάρτηση;divmod
@geindex ενσωματωμένη συνάρτηση;pow

Αυτές οι μέθοδοι καλούνται να υλοποιήσουν τις δυαδικές αριθμητικές λειτουργίες (@code{+}, @code{-}, @code{*}, @code{@@}, @code{/}, @code{//}, @code{%}, @ref{d6a,,divmod()}, @ref{441,,pow()}, @code{**}, @code{<<}, @code{>>}, @code{&}, @code{^}, @code{|}) με ανακλώμενους (ανταλλαγμένους) τελεστές.  Αυτές οι λειτουργίες καλούνται μόνο εάν οι τελεστές είναι διαφορετικών τύπων, όταν ο αριστερός τελεστής δεν υποστηρίζει την αντίστοιχη λειτουργία @footnote{
Το «Δεν υποστηρίζει» εδώ σημαίνει ότι η κλάση δεν έχει τέτοια μέθοδο ή η μέθοδος επιστρέφει @ref{440,,NotImplemented}.  Μην ορίσετε τη μέθοδο σε @code{None} εάν θέλετε να αναγκάσετε την επιστροφή στη μέθοδο ανακλώμενης του δεξιού τελεστή-αυτό θα έχει το αντίθετο αποτέλεσμα του ρητού `μπλοκαρίσματος' αυτού του εναλλακτικού.
}, ή η κλάση του δεξιού τελεστή προέρχεται από την κλάση του αριστερού τελεστή. @footnote{
Για τελεστές του ίδιου τύπου, θεωρείται ότι εάν η μη ανακλώμενη μέθοδος (όπως @ref{25d2,,__add__()}) αποτύχει τότε η λειτουργία δεν υποστηρίζεται, γι” αυτό δεν καλείται η ανακλώμενη μέθοδος.
} Για παράδειγμα, για να αξιολογηθεί η έκφραση @code{x - y}, όπου `y' είναι ένα στιγμιότυπο μιας κλάσης που έχει μια μέθοδο @ref{25e5,,__rsub__()}, καλείται το @code{type(y).__rsub__(y, x)} εάν το @code{type(x).__sub__(x, y)} επιστρέψει @ref{440,,NotImplemented} ή το @code{type(y)} είναι υποκλάση του @code{type(x)}. @footnote{
Εάν ο τύπος του δεξιού τελεστή είναι υποκλάση του τύπου του αριστερού τελεστή, η προτεραιότητα της ανακλώμενης μεθόδου επιτρέπει στις υποκλάσεις να υπερισχύουν των λειτουργιών των προγόνων τους.
}

Σημειώστε ότι η @ref{442,,__rpow__()} θα πρέπει να ορίζεται ώστε να δέχεται ένα προαιρετικό τρίτο όρισμα εάν υποστηρίζεται η τριών ορισμάτων έκδοση της ενσωματωμένης συνάρτησης @ref{441,,pow()}.


Άλλαξε στην έκδοση 3.14: Η τριών ορισμάτων @ref{441,,pow()} τώρα προσπαθεί να καλέσει τη @ref{442,,__rpow__()} εάν είναι απαραίτητο. Παλαιότερα καλούνταν μόνο στη δύο ορισμάτων @code{pow()} και στον δυαδικό τελεστή δύναμης.


@cartouche
@quotation Σημείωση 
Εάν ο τύπος του δεξιού τελεστή είναι υποκλάση του τύπου του αριστερού τελεστή και αυτή η υποκλάση παρέχει μια διαφορετική υλοποίηση της ανακλώμενης μεθόδου για τη λειτουργία, αυτή η μέθοδος θα κληθεί πριν από τη μη ανακλώμενη μέθοδο του αριστερού τελεστή. Αυτή η συμπεριφορά επιτρέπει στις υποκλάσεις να παρακάμπτουν τις πράξεις των προγόνων τους.
@end quotation
@end cartouche
@end deffn

@geindex __iadd__() (μέθοδος της object)
@geindex __isub__() (μέθοδος της object)
@geindex __imul__() (μέθοδος της object)
@geindex __imatmul__() (μέθοδος της object)
@geindex __itruediv__() (μέθοδος της object)
@geindex __ifloordiv__() (μέθοδος της object)
@geindex __imod__() (μέθοδος της object)
@geindex __ipow__() (μέθοδος της object)
@geindex __ilshift__() (μέθοδος της object)
@geindex __irshift__() (μέθοδος της object)
@geindex __iand__() (μέθοδος της object)
@geindex __ixor__() (μέθοδος της object)
@geindex __ior__() (μέθοδος της object)
@anchor{reference/datamodel object __iadd__}@anchor{25d4}
@deffn {Μέθοδος} object.__iadd__ (self, other)
@anchor{reference/datamodel object __isub__}@anchor{25ee}
@deffnx {Μέθοδος} object.__isub__ (self, other)
@anchor{reference/datamodel object __imul__}@anchor{25d7}
@deffnx {Μέθοδος} object.__imul__ (self, other)
@anchor{reference/datamodel object __imatmul__}@anchor{1134}
@deffnx {Μέθοδος} object.__imatmul__ (self, other)
@anchor{reference/datamodel object __itruediv__}@anchor{25ef}
@deffnx {Μέθοδος} object.__itruediv__ (self, other)
@anchor{reference/datamodel object __ifloordiv__}@anchor{25f0}
@deffnx {Μέθοδος} object.__ifloordiv__ (self, other)
@anchor{reference/datamodel object __imod__}@anchor{25f1}
@deffnx {Μέθοδος} object.__imod__ (self, other)
@anchor{reference/datamodel object __ipow__}@anchor{bb0}
@deffnx {Μέθοδος} object.__ipow__ (self, other[, modulo])
@anchor{reference/datamodel object __ilshift__}@anchor{25f2}
@deffnx {Μέθοδος} object.__ilshift__ (self, other)
@anchor{reference/datamodel object __irshift__}@anchor{25f3}
@deffnx {Μέθοδος} object.__irshift__ (self, other)
@anchor{reference/datamodel object __iand__}@anchor{25f4}
@deffnx {Μέθοδος} object.__iand__ (self, other)
@anchor{reference/datamodel object __ixor__}@anchor{25f5}
@deffnx {Μέθοδος} object.__ixor__ (self, other)
@anchor{reference/datamodel object __ior__}@anchor{25f6}
@deffnx {Μέθοδος} object.__ior__ (self, other)

Αυτές οι μέθοδοι καλούνται να υλοποιήσουν τις επαυξημένες αριθμητικές εκχωρήσεις (@code{+=}, @code{-=}, @code{*=}, @code{@@=}, @code{/=}, @code{//=}, @code{%=}, @code{**=}, @code{<<=}, @code{>>=}, @code{&=}, @code{^=}, @code{|=}). Αυτές οι μέθοδοι θα πρέπει να προσπαθήσουν να κάνουν τη λειτουργία επιτόπου (τροποποίηση `self') και να επιστρέψουν το αποτέλεσμα (το οποίο θα μπορούσε, αλλά δεν χρειάζεται να είναι, `self'). Εάν δεν έχει οριστεί μια συγκεκριμένη μέθοδος ή εάν αυτή η μέθοδος επιστρέψει @ref{440,,NotImplemented}, η επαυξημένη ανάθεση επανέρχεται στις κανονικές μεθόδους. Για παράδειγμα, εάν το `x' είναι ένα στιγμιότυπο μιας κλάσης με μια μέθοδο @ref{25d4,,__iadd__()}, το @code{x += y} ισοδυναμεί @code{x = x.__iadd__(y)} . Εάν το @code{__iadd__()} δεν υπάρχει, ή εάν το @code{x.__iadd__(y)} επιστρέφει @code{NotImplemented}, τα @code{x.__add__(y)} και @code{y.__radd__(x)} θεωρούνται, όπως και με την αξιολόγηση του. Σε ορισμένες περιπτώσεις, η επαυξημένη ανάθεση μπορεί να οδηγήσει σε απροσδόκητα σφάλματα (δείτε @ref{25f7,,Γιατί το a_tuple[i] += [“item”] δημιουργεί μια εξαίρεση όταν λειτουργεί η προσθήκη;}), αλλά αυτή η συμπεριφορά είναι στην πραγματικότητα μέρος του μοντέλου δεδομένων.
@end deffn

@geindex __neg__() (μέθοδος της object)
@geindex __pos__() (μέθοδος της object)
@geindex __abs__() (μέθοδος της object)
@geindex __invert__() (μέθοδος της object)
@anchor{reference/datamodel object __neg__}@anchor{25f8}
@deffn {Μέθοδος} object.__neg__ (self)
@anchor{reference/datamodel object __pos__}@anchor{25f9}
@deffnx {Μέθοδος} object.__pos__ (self)
@anchor{reference/datamodel object __abs__}@anchor{25fa}
@deffnx {Μέθοδος} object.__abs__ (self)
@anchor{reference/datamodel object __invert__}@anchor{25fb}
@deffnx {Μέθοδος} object.__invert__ (self)

@geindex ενσωματωμένη συνάρτηση;abs

Καλείται για την υλοποίηση μονομερών αριθμητικών πράξεων (@code{-}, @code{+}, @ref{227c,,abs()} και @code{~}).
@end deffn

@geindex __complex__() (μέθοδος της object)
@geindex __int__() (μέθοδος της object)
@geindex __float__() (μέθοδος της object)
@anchor{reference/datamodel object __complex__}@anchor{9de}
@deffn {Μέθοδος} object.__complex__ (self)
@anchor{reference/datamodel object __int__}@anchor{43c}
@deffnx {Μέθοδος} object.__int__ (self)
@anchor{reference/datamodel object __float__}@anchor{d92}
@deffnx {Μέθοδος} object.__float__ (self)

@geindex ενσωματωμένη συνάρτηση;complex
@geindex ενσωματωμένη συνάρτηση;int
@geindex ενσωματωμένη συνάρτηση;float

Καλείται για την υλοποίηση των ενσωματωμένων συναρτήσεων @ref{328,,complex()}, @ref{326,,int()} και @ref{327,,float()}.  Θα πρέπει να επιστρέψει μια τιμή του κατάλληλου τύπου.
@end deffn

@geindex __index__() (μέθοδος της object)
@anchor{reference/datamodel object __index__}@anchor{43d}
@deffn {Μέθοδος} object.__index__ (self)

Καλείται για υλοποίηση @ref{1ec8,,operator.index()}, και όποτε η Python χρειάζεται να μετατρέψει χωρίς απώλειες το αριθμητικό αντικείμενο σε ένα ακέραιο αντικείμενο (όπως στη λειτουργία τμηματοποίησης ή στις ενσωματωμένες συναρτήσεις @ref{164d,,bin()}, @ref{1674,,hex()} και @ref{1673,,oct()}). Η παρουσία αυτής της μεθόδου υποδεικνύει ότι το αριθμητικό αντικείμενο είναι ακέραιου τύπου.  Πρέπει να επιστρέψει έναν ακέραιο αριθμό.

Εάν οι @ref{43c,,__int__()}, @ref{d92,,__float__()} και @ref{9de,,__complex__()} δεν ορίζονται, τότε οι αντίστοιχες ενσωματωμένες συναρτήσεις @ref{326,,int()}, @ref{327,,float()} και @ref{328,,complex()} επιστρέφουν στο @ref{43d,,__index__()}.
@end deffn

@geindex __round__() (μέθοδος της object)
@geindex __trunc__() (μέθοδος της object)
@geindex __floor__() (μέθοδος της object)
@geindex __ceil__() (μέθοδος της object)
@anchor{reference/datamodel object __round__}@anchor{25fc}
@deffn {Μέθοδος} object.__round__ (self[, ndigits])
@anchor{reference/datamodel object __trunc__}@anchor{43b}
@deffnx {Μέθοδος} object.__trunc__ (self)
@anchor{reference/datamodel object __floor__}@anchor{25fd}
@deffnx {Μέθοδος} object.__floor__ (self)
@anchor{reference/datamodel object __ceil__}@anchor{25fe}
@deffnx {Μέθοδος} object.__ceil__ (self)

@geindex ενσωματωμένη συνάρτηση;round

Καλείται για την υλοποίηση της ενσωματωμένης συνάρτησης @ref{167f,,round()} και @ref{91,,math} συναρτήσεις @ref{1762,,trunc()}, @ref{1760,,floor()} και @ref{1761,,ceil()}. Εκτός εάν το `ndigits' μεταβιβαστεί στο @code{__round__()} όλες αυτές οι μέθοδοι θα πρέπει να επιστρέψουν την τιμή του αντικειμένου που περικόπτεται σε μια @ref{25ff,,Integral} (συνήθως ένα @ref{326,,int}).


Άλλαξε στην έκδοση 3.14: Η @ref{326,,int()} δεν αναθέτει πλέον στη μέθοδο @ref{43b,,__trunc__()}.

@end deffn

@node Με τους Διαχειριστές Περιβάλλοντος Δήλωσης,Προσαρμογή ορισμάτων θέσης στην αντιστοίχιση προτύπων κλάσης,Εξομοίωση αριθμητικών τύπων,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel context-managers}@anchor{2572}@anchor{reference/datamodel with-statement-context-managers}@anchor{2600}
@subsubsection Με τους Διαχειριστές Περιβάλλοντος Δήλωσης


Ένα `context manager' είναι ένα αντικείμενο που ορίζει το περιβάλλον χρόνου εκτέλεσης που θα καθοριστεί κατά την εκτέλεση μιας πρότασης @ref{20a,,with}. Ο διαχειριστής περιβάλλοντος χειρίζεται την είσοδο και την έξοδο από το επιθυμητό  περιβάλλον χρόνου εκτέλεσης για την εκτέλεση του μπλοκ κώδικα. Οι διαχειριστές περιβάλλοντος συνήθως καλούνται χρησιμοποιώντας τη δήλωση @code{with} (που περιγράφεται στην ενότητα @ref{20a,,The with statement}), αλλά μπορούν επίσης να χρησιμοποιηθούν με απευθείας επίκληση των μεθόδων τους.

@geindex δήλωση;with
@geindex διαχειριστής περιβάλλοντος

Οι τυπικές χρήσεις των διαχειριστών περιβάλλοντος περιλαμβάνουν την αποθήκευση και την επαναφορά διαφόρων ειδών καθολικών καταστάσεων, το κλείδωμα και το ξεκλείδωμα πόρων, το κλείσιμο των ανοιχτών αρχείων κ.λπ.

Για περισσότερες πληροφορίες σχετικά με τους διαχειριστές περιβάλλοντος, ανατρέξτε στο @ref{2601,,Τύποι Διαχείρισης Περιεχομένου}. Η ίδια η κλάση @ref{e4d,,object} δεν παρέχει τις μεθόδους διαχειριστή περιβάλλοντος.

@geindex __enter__() (μέθοδος της object)
@anchor{reference/datamodel object __enter__}@anchor{9c6}
@deffn {Μέθοδος} object.__enter__ (self)

Εισαγάγετε το περιβάλλον χρόνου εκτέλεσης που σχετίζεται με αυτό το αντικείμενο. Η δήλωση @ref{20a,,with} θα δεσμεύσει την επιστρεφόμενη τιμή αυτής της μεθόδου με τους στόχους που καθορίζονται στον όρο @code{as} της πρότασης, εάν υπάρχει.
@end deffn

@geindex __exit__() (μέθοδος της object)
@anchor{reference/datamodel object __exit__}@anchor{16a5}
@deffn {Μέθοδος} object.__exit__ (self, exc_type, exc_value, traceback)

Έξοδος από το περιβάλλον χρόνου εκτέλεσης που σχετίζεται με αυτό το αντικείμενο. Οι παράμετροι περιγράφουν την εξαίρεση που προκάλεσε την έξοδο από το περιβάλλον. Εάν το περιβάλλον είχε βγει χωρίς εξαίρεση, και τα τρία ορίσματα θα είναι @ref{a65,,None}.

Εάν παρέχεται μια εξαίρεση και η μέθοδος επιθυμεί να καταργήσει την εξαίρεση (δηλαδή, να αποτρέψει τη διάδοση της), θα πρέπει να επιστρέψει μια πραγματική τιμή. Διαφορετικά, η εξαίρεση θα διεκπεραιωθεί κανονικά κατά την έξοδο από αυτήν τη μέθοδο.

Λάβετε υπόψη ότι οι μέθοδοι @ref{16a5,,__exit__()} δεν θα πρέπει να επαναφέρουν την εξαίρεση που μεταβιβάστηκε∙ αυτή είναι ευθύνη του καλούντος.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 343

@item PEP 343@footnote{https://peps.python.org/pep-0343/} - Η πρόταση «with»

Οι προδιαγραφές, το υπόβαθρο και τα παραδείγματα για τη δήλωση Python @ref{20a,,with}.
@end table


@node Προσαρμογή ορισμάτων θέσης στην αντιστοίχιση προτύπων κλάσης,Εξομοίωση τύπων buffer,Με τους Διαχειριστές Περιβάλλοντος Δήλωσης,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel class-pattern-matching}@anchor{2602}@anchor{reference/datamodel customizing-positional-arguments-in-class-pattern-matching}@anchor{2603}
@subsubsection Προσαρμογή ορισμάτων θέσης στην αντιστοίχιση προτύπων κλάσης


Όταν χρησιμοποιείται ένα όνομα κλάσης σε ένα μοτίβο, τα ορίσματα θέσης στο μοτίβο δεν επιτρέπονται από προεπιλογή, δηλαδή @code{case MyClass(x, y)} δεν είναι συνήθως έγκυρη χωρίς ειδική υποστήριξη στο @code{MyClass}. Για να μπορέσει να χρησιμοποιήσει αυτό το είδος μοτίβου, η κλάση πρέπει να ορίσει ένα χαρακτηριστικό `__match_args__'.

@geindex object.__match_args__ (ενσωματωμένη μεταβλητή)
@anchor{reference/datamodel object __match_args__}@anchor{1e6c}
@deffn {Δεδομένα} object.__match_args__

Σε αυτήν την μεταβλητή κλάσης μπορεί να εκχωρηθεί μια πλειάδα συμβολοσειρών. Όταν αυτή η κλάση χρησιμοποιείται σε ένα μοτίβο κλάσης με ορίσματα θέσης, κάθε όρισμα θέσης θα μετατραπεί σε όρισμα λέξης-κλειδιού, χρησιμοποιώντας την αντίστοιχη τιμή στο `__match_args__' ως λέξη-κλειδί. Η απουσία αυτού του χαρακτηριστικού ισοδυναμεί με τη ρύθμιση του σε @code{()}.
@end deffn

Για παράδειγμα, εάν το @code{MyClass.__match_args__} είναι @code{("left", "center", "right")} αυτό σημαίνει ότι το @code{case MyClass(x, y)} ισοδυναμεί με @code{case MyClass(left=x, center=y)}. Σημειώστε ότι ο αριθμός των ορισμάτων στο μοτίβο πρέπει να είναι μικρότερος ή ίσος με τον αριθμό των στοιχείων στο `__match_args__' ∙ αν είναι μεγαλύτερο, η προσπάθεια αντιστοίχισης μοτίβου θα κάνει raise μια @ref{291,,TypeError}.


Added in version 3.10.



@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 634

@item PEP 634@footnote{https://peps.python.org/pep-0634/} - Αντιστοίχιση δομικών προτύπων

Η προδιαγραφή για τη δήλωση Python @code{match}.
@end table


@node Εξομοίωση τύπων buffer,Annotations,Προσαρμογή ορισμάτων θέσης στην αντιστοίχιση προτύπων κλάσης,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel emulating-buffer-types}@anchor{2604}@anchor{reference/datamodel python-buffer-protocol}@anchor{2605}
@subsubsection Εξομοίωση τύπων buffer


Το πρωτόκολλο @ref{311,,buffer protocol} παρέχει έναν τρόπο για τα αντικείμενα της Python να εκθέτουν αποτελεσματική πρόσβαση σε έναν πίνακα μνήμης χαμηλού επιπέδου. Αυτό το πρωτόκολλο υλοποιείται από ενσωματωμένους τύπους όπως @ref{1c7,,bytes} και @ref{1d2,,memoryview}, και οι βιβλιοθήκες τρίτων μπορούν να ορίσουν πρόσθετους τύπους buffer.

Ενώ οι τύπου buffer συνήθως υλοποιούνται σε C, είναι επίσης δυνατή η υλοποίηση του πρωτοκόλλου στην Python.

@geindex __buffer__() (μέθοδος της object)
@anchor{reference/datamodel object __buffer__}@anchor{879}
@deffn {Μέθοδος} object.__buffer__ (self, flags)

Καλείται όταν ζητείται buffer από τον `self' (για παράδειγμα, από τον κατασκευαστή @ref{1d2,,memoryview}). Το όρισμα `flags' είναι ένας ακέραιος αριθμός που αντιπροσωπεύει το είδος της προσωρινής μνήμης που ζητήθηκε, επηρεάζοντας για παράδειγμα εάν η προσωρινή μνήμη που επιστρέφεται είναι μόνο για ανάγνωση ή για εγγράψιμο. Η @ref{87a,,inspect.BufferFlags} παρέχει έναν βολικό τρόπο ερμηνείας των flags. Η μέθοδος πρέπει να επιστρέψει ένα αντικείμενο @code{memoryview}.

`Thread safety:' In @ref{487,,free-threaded} Python,
implementations must manage any internal export counter using atomic
operations. The method must be safe to call concurrently from multiple
threads, and the returned buffer’s underlying data must remain valid
until the corresponding @ref{1c6b,,__release_buffer__()} call
completes. See @ref{2606,,Thread safety for memoryview objects} for details.
@end deffn

@geindex __release_buffer__() (μέθοδος της object)
@anchor{reference/datamodel object __release_buffer__}@anchor{1c6b}
@deffn {Μέθοδος} object.__release_buffer__ (self, buffer)

Called when a buffer is no longer needed. The `buffer' argument is a
@ref{1d2,,memoryview} object that was previously returned by
@ref{879,,__buffer__()}. The method must release any resources associated
with the buffer. This method should return @code{None}.

`Thread safety:' In @ref{487,,free-threaded} Python,
any export counter decrement must use atomic operations. Resource
cleanup must be thread-safe, as the final release may race with
concurrent releases from other threads.

Buffer objects that do not need to perform any cleanup are not required
to implement this method.
@end deffn


Added in version 3.12.



@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 688

@item PEP 688@footnote{https://peps.python.org/pep-0688/} - Κάνοντας το πρωτόκολλο buffer προσβάσιμο στην Python

Παρουσιάζει τις μεθόδους Python @code{__buffer__} και @code{__release_buffer__}.

@item @ref{312,,collections.abc.Buffer}

ABC για τύπους buffer.
@end table


@node Annotations,Αναζήτηση ειδικής μεθόδου,Εξομοίωση τύπων buffer,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel annotations}@anchor{2607}
@subsubsection Annotations


Οι συναρτήσεις, οι κλάσεις και τα προγράμματα μπορεί να περιέχουν @ref{409,,annotations}, που είναι ένας τρόπος να συσχετιστεί πληροφορία (συνήθως @ref{25c1,,type hints}) με ένα σύμβολο.

@geindex __annotations__ (ιδιότητα της object)
@anchor{reference/datamodel object __annotations__}@anchor{66b}
@deffn {Ιδιότητα} object.__annotations__

Αυτό το χαρακτηριστικό περιέχει τα annotations για ένα αντικείμενο. Είναι @ref{872,,lazily evaluated}, οπότε η πρόσβαση στο χαρακτηριστικό μπορεί να εκτελέσει αυθαίρετο κώδικα και να κάνει raise εξαιρέσεις. Εάν η αξιολόγηση είναι επιτυχής, το χαρακτηριστικό ορίζεται σε ένα λεξικό που αντιστοιχεί από ονόματα μεταβλητών σε annotations.


Άλλαξε στην έκδοση 3.14: Τα annotations αξιολογούνται πλέον τεμπέλικα.

@end deffn

@geindex __annotate__() (μέθοδος της object)
@anchor{reference/datamodel object __annotate__}@anchor{1b95}
@deffn {Μέθοδος} object.__annotate__ (format)

Ένα @ref{40a,,annotate function}. Επιστρέφει ένα νέο αντικείμενο λεξικού που αντιστοιχεί ονόματα χαρακτηριστικών/παραμέτρων στις τιμές των annotations τους.

Λαμβάνει μια παράμετρο μορφής που καθορίζει τη μορφή στην οποία θα πρέπει να παρέχονται οι τιμές των annotations. Πρέπει να είναι μέλος της @ref{4be,,annotationlib.Format} enum, ή ένας ακέραιος αριθμός με τιμή που αντιστοιχεί σε μέλος της enum.

Εάν μια annotate συνάρτηση δεν υποστηρίζει την ζητούμενη μορφή, πρέπει να κάνει raise @ref{59a,,NotImplementedError}. Οι annotate συναρτήσεις πρέπει πάντα να υποστηρίζουν τη μορφή @ref{40b,,VALUE} ∙ δεν πρέπει να κάνουν raise @ref{59a,,NotImplementedError()} όταν καλούνται με αυτή τη μορφή.

Όταν καλείται με τη μορφή @ref{40b,,VALUE}, μια annotate συνάρτηση μπορεί να κάνει raise @ref{665,,NameError} ∙ δεν πρέπει να κάνει raise @code{NameError} όταν καλείται ζητώντας οποιαδήποτε άλλη μορφή.

Εάν ένα αντικείμενο δεν έχει κανένα annotation, το @ref{1b95,,__annotate__} θα πρέπει κατά προτίμηση να ορίζεται σε @code{None} (δεν μπορεί να διαγραφεί), αντί να ορίζεται σε μια συνάρτηση που επιστρέφει ένα κενό dict.


Added in version 3.14.

@end deffn


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 649

@item PEP 649@footnote{https://peps.python.org/pep-0649/} — Τεμπέλικη αξιολόγηση annotation χρησιμοποιώντας descriptors

Παρουσιάζει την τεμπέλικη αξιολόγηση των annotations και τη συνάρτηση @code{__annotate__}.
@end table


@node Αναζήτηση ειδικής μεθόδου,,Annotations,Ειδικά ονόματα μεθόδων
@anchor{reference/datamodel special-lookup}@anchor{25a6}@anchor{reference/datamodel special-method-lookup}@anchor{2608}
@subsubsection Αναζήτηση ειδικής μεθόδου


Για προσαρμοσμένες κλάσεις, οι σιωπηρές επικλήσεις ειδικών μεθόδων είναι εγγυημένο ότι θα λειτουργούν σωστά μόνο εάν ορίζονται στον τύπο ενός αντικειμένου και όχι στο λεξικό στιγμιοτύπου του αντικειμένου. Αυτή η συμπεριφορά είναι ο λόγος για τον οποίο ο ακόλουθος κώδικας κάνει raise μια εξαίρεση:

@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

Η λογική πίσω από αυτήν τη συμπεριφορά έγκειται σε μια σειρά ειδικών μεθόδων όπως @ref{ec1,,__hash__()} και @ref{1bc,,__repr__()} που υλοποιούνται από όλα τα αντικείμενα, συμπεριλαμβανομένων των αντικειμένων τύπου. Εάν η σιωπηρή αναζήτηση αυτών των μεθόδων χρησιμοποιούσε τη συμβατική διαδικασία αναζήτησης, θα αποτύγχανε όταν καλούνταν στο ίδιο το αντικείμενο τύπου:

@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

Η εσφαλμένη προσπάθειας επίκλησης μιας μη δεσμευμένης μεθόδου μιας κλάσης με αυτόν τον τρόπο αναφέρεται μερικές φορές ως “σύγχυση μετακλάσης”, και αποφεύγεται με παράκαμψη της παρουσίας κατά την αναζήτηση ειδικών μεθόδων:

@example
>>> type(1).__hash__(1) == hash(1)
True
>>> type(int).__hash__(int) == hash(int)
True
@end example

Εκτός από την παράκαμψη οποιωνδήποτε χαρακτηριστικών στιγμιοτύπου για λόγους ορθότητας, η σιωπηρή αναζήτηση ειδική μεθόδου γενικά παρακάμπτει επίσης τη μέθοδο @ref{f90,,__getattribute__()} ακόμη και της μετακλάσης του αντικειμένου:

@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

Η παράκαμψη του μηχανισμού @ref{f90,,__getattribute__()} με αυτόν τον τρόπο παρέχει σημαντικά περιθώρια για βελτιστοποιήσεις ταχύτητας εντός του διερμηνέα, με κόστος κάποιας ευελιξίας στον χειρισμό ειδικών μεθόδων (η ειδική μέθοδος `πρέπει' να οριστεί στο ίδιο το αντικείμενο κλάσης για να καλείται με συνέπεια από τον διερμηνέα).

@geindex coroutine

@node Coroutines,,Ειδικά ονόματα μεθόδων,Μοντέλο Δεδομένων
@anchor{reference/datamodel coroutines}@anchor{2609}
@subsection Coroutines


@menu
* Awaitable Αντικείμενα:: 
* Coroutine Αντικείμενα:: 
* Ασύγχρονοι Iterators:: 
* Ασύγχρονοι Διαχειριστές Περιβάλλοντος:: 

@end menu

@node Awaitable Αντικείμενα,Coroutine Αντικείμενα,,Coroutines
@anchor{reference/datamodel awaitable-objects}@anchor{260a}
@subsubsection Awaitable Αντικείμενα


Ένα αντικείμενο @ref{6cf,,awaitable} εφαρμόζει γενικά μια μέθοδο @ref{112e,,__await__()}. Τα @ref{8a2,,Coroutine objects} που επιστρέφονται από τις @ref{9cf,,async def} συναρτήσεις είναι awaitable.

@cartouche
@quotation Σημείωση 
Τα αντικείμενα @ref{f9e,,generator iterator} που επιστράφηκαν από γεννήτριες διακοσμημένες με @ref{1239,,types.coroutine()} είναι επίσης awaitable, αλλά δεν εφαρμόζουν το @ref{112e,,__await__()}.
@end quotation
@end cartouche

@geindex __await__() (μέθοδος της object)
@anchor{reference/datamodel object __await__}@anchor{112e}
@deffn {Μέθοδος} object.__await__ (self)

Πρέπει να επιστρέψει ένα @ref{6ce,,iterator}.  Θα πρέπει να χρησιμοποιείται για την υλοποίηση @ref{6cf,,awaitable} αντικειμένων.  Για παράδειγμα, η @ref{f8b,,asyncio.Future} υλοποιεί αυτήν την μέθοδο ώστε να είναι συμβατή με την έκφραση @ref{432,,await}. Η ίδια η κλάση @ref{e4d,,object} δεν είναι αναμονή και δεν παρέχει αυτήν τη μέθοδο.

@cartouche
@quotation Σημείωση 
Η γλώσσα δεν θέτει  κανέναν περιορισμό στον τύπο ή την τιμή των αντικειμένων που παράγονται από τον iterator που επιστρέφεται από το @code{__await__}, καθώς αυτό αφορά συγκεκριμένα την υλοποίηση του πλαισίου ασύγχρονης εκτέλεσης (π.χ. @ref{b,,asyncio}) που θα διαχειρίζεται το @ref{6cf,,awaitable} αντικείμενο.
@end quotation
@end cartouche
@end deffn


Added in version 3.5.



@subsubheading Δείτε επίσης


Το 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} για πρόσθετες πληροφορίες σχετικά με τα awaitable αντικείμενα.


@node Coroutine Αντικείμενα,Ασύγχρονοι Iterators,Awaitable Αντικείμενα,Coroutines
@anchor{reference/datamodel coroutine-objects}@anchor{2547}@anchor{reference/datamodel id19}@anchor{260b}
@subsubsection Coroutine Αντικείμενα


Τα @ref{8a2,,Coroutine objects} είναι @ref{6cf,,awaitable} αντικείμενα. Η εκτέλεση μιας coroutine μπορεί να ελεγχθεί καλώντας το @ref{112e,,__await__()} και επαναλαμβάνοντας το αποτέλεσμα.  Όταν η coroutine ολοκληρώσει την εκτέλεση και επιστρέψει ο iterator κάνει raise την @ref{fba,,StopIteration}, και το χαρακτηριστικό @ref{260c,,value} της εξαίρεσης διατηρεί την τιμή επιστροφής.  Εάν η coroutine εγείρει μια εξαίρεση, αυτή διαδίδεται από τον iterator.  Οι coroutines δεν πρέπει να κάνουν raise ανεξέλεγκτες εξαιρέσεις @code{StopIteration}.

Οι coroutines έχουν επίσης τις μεθόδου που αναφέρονται παρακάτω, οι οποίες είναι ανάλογες με αυτές των γεννητριών (βλ. @ref{260d,,Generator-iterator methods}).  Ωστόσο, σε αντίθεση με τις γεννήτριες, οι coroutines δεν υποστηρίζουν άμεσα την επανάληψη.


Άλλαξε στην έκδοση 3.5.2: Είναι ένα @ref{30d,,RuntimeError} να περιμένει κανείς σε μια coroutine περισσότερες από μία φορές.


@geindex send() (μέθοδος της coroutine)
@anchor{reference/datamodel coroutine send}@anchor{260e}
@deffn {Μέθοδος} coroutine.send (value)

Ξεκινά ή συνεχίζει την εκτέλεση της coroutine.  Εάν η `τιμή' είναι @code{None}, αυτό ισοδυναμεί με την προώθηση του iterator που επιστρέφεται @ref{112e,,__await__()}.  Εάν η `τιμή' δεν είναι @code{None}, αυτή η μέθοδος εκχωρεί στη μέθοδο @ref{260f,,send()} του iterator που προκάλεσε την αναστολή της coroutine.  Το αποτέλεσμα (επιστρεφόμενη τιμή, @ref{fba,,StopIteration}, ή άλλη εξαίρεση) είναι το ίδιο όπως όταν γίνεται επανάληψη πάνω από την τιμή επιστροφής @code{__await__()} , που περιγράφεται παραπάνω.
@end deffn

@geindex throw() (μέθοδος της coroutine)
@anchor{reference/datamodel coroutine throw}@anchor{904}
@deffn {Μέθοδος} coroutine.throw (value)

@deffnx {Μέθοδος} coroutine.throw (type[, value[, traceback]])

Κάνει Raise την καθορισμένη εξαίρεση στην coroutine.  Αυτή η μέθοδος εκχωρεί στη μέθοδο @ref{905,,throw()} του iterator που προκάλεσε την αναστολή της coroutine, εάν διαθέτει τέτοια μέθοδο.  Διαφορετικά, η εξαίρεση γίνεται raise στο σημείο αναστολής.  Το αποτέλεσμα (επιστρεφόμενη τιμή, @ref{fba,,StopIteration}, ή άλλη εξαίρεση) είναι το ίδιο όπως όταν γίνεται επανάληψη πάνω από την τιμή επιστροφής @ref{112e,,__await__()}, που περιγράφεται παραπάνω.  Εάν η εξαίρεση δεν περιλαμβάνεται στην coroutine, διαδίδεται πίσω από εκεί που καλέστηκε.


Άλλαξε στην έκδοση 3.12: Η δεύτερη υπογραφή (type[, value[, traceback]])  έχει καταργηθεί και μπορεί να αφαιρεθεί σε μια μελλοντική έκδοση της Python.

@end deffn

@geindex close() (μέθοδος της coroutine)
@anchor{reference/datamodel coroutine close}@anchor{2610}
@deffn {Μέθοδος} coroutine.close ()

Προκαλεί τον καθαρισμό και την έξοδο της coroutine.  Εάν η coroutine τεθεί σε αναστολή, αυτή η μέθοδος εκχωρεί πρώτα στην μέθοδο @ref{199e,,close()} του iterator που προκάλεσε την αναστολή της coroutine, εάν έχει τέτοια μέθοδο.  Στη συνέχεια, σηκώνει το @ref{176a,,GeneratorExit} στο σημείο αναστολής, με αποτέλεσμα η coroutine να καθαριστεί αμέσως. Τέλος, η coroutine επισημαίνεται ότι έχει τελειώσει την εκτέλεση, ακόμα κι αν δεν ξεκίνησε ποτέ.

Τα αντικείμενα coroutine κλείνουν αυτόματα χρησιμοποιώντας την παραπάνω διαδικασία όταν πρόκειται να καταστραφούν.
@end deffn

@node Ασύγχρονοι Iterators,Ασύγχρονοι Διαχειριστές Περιβάλλοντος,Coroutine Αντικείμενα,Coroutines
@anchor{reference/datamodel async-iterators}@anchor{1130}@anchor{reference/datamodel asynchronous-iterators}@anchor{2611}
@subsubsection Ασύγχρονοι Iterators


Ένας `ασύγχρονος iterator' μπορεί να καλέσει ασύγχρονο κώδικα με τη μέθοδο @code{__anext__}.

Οι ασύγχρονοι iterators μπορούν να χρησιμοποιηθούν σε μια δήλωση @ref{e70,,async for}.

Η ίδια η κλάση @ref{e4d,,object} δεν παρέχει αυτές τις μεθόδους.

@geindex __aiter__() (μέθοδος της object)
@anchor{reference/datamodel object __aiter__}@anchor{fbb}
@deffn {Μέθοδος} object.__aiter__ (self)

Πρέπει να επιστρέψει ένα αντικείμενο `ασύγχρονου iterator'.
@end deffn

@geindex __anext__() (μέθοδος της object)
@anchor{reference/datamodel object __anext__}@anchor{1aa7}
@deffn {Μέθοδος} object.__anext__ (self)

Πρέπει να επιστρέψει ένα `αναμενόμενο' που θα έχει ως αποτέλεσμα μια επόμενη τιμή iterator.  Θα πρέπει να κάνει raise ένα σφάλμα @ref{1ffe,,StopAsyncIteration} όταν τελειώσει η επανάληψη.
@end deffn

Παράδειγμα σύγχρονου iterator αντικειμένου:

@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


Added in version 3.5.



Άλλαξε στην έκδοση 3.7: Πριν από την Python 3.7, η @ref{fbb,,__aiter__()} θα μπορούσε να επιστρέψει ένα `αναμενόμενο' που θα επιλύονται σε ένα @ref{6cd,,asynchronous iterator}.

Ξεκινώντας με την Python 3.7, η @ref{fbb,,__aiter__()}  πρέπει να επιστρέψει ένα ασύγχρονο αντικείμενο iterator.  Εάν επιστρέφει οτιδήποτε άλλο θα έχει ως αποτέλεσμα ένα σφάλμα @ref{291,,TypeError}.


@node Ασύγχρονοι Διαχειριστές Περιβάλλοντος,,Ασύγχρονοι Iterators,Coroutines
@anchor{reference/datamodel async-context-managers}@anchor{9f3}@anchor{reference/datamodel asynchronous-context-managers}@anchor{2612}
@subsubsection Ασύγχρονοι Διαχειριστές Περιβάλλοντος


Ένας `ασύγχρονος διαχειριστής περιβάλλοντος' είναι ένα `διαχειριστής περιβάλλοντος' που μπορεί να αναστείλει την εκτέλεση στις μεθόδους @code{__aenter__} και @code{__aexit__}.

Οι ασύγχρονοι διαχειριστές περιβάλλοντος μπορούν να χρησιμοποιηθούν σε μια δήλωση @ref{20b,,async with}.

Η ίδια η κλάση @ref{e4d,,object} δεν παρέχει αυτές τις μεθόδους.

@geindex __aenter__() (μέθοδος της object)
@anchor{reference/datamodel object __aenter__}@anchor{2613}
@deffn {Μέθοδος} object.__aenter__ (self)

Σημασιολογικά παρόμοια με @ref{9c6,,__enter__()}, η μόνη διαφορά είναι ότι πρέπει να επιστρέψει ένα `awaitable'.
@end deffn

@geindex __aexit__() (μέθοδος της object)
@anchor{reference/datamodel object __aexit__}@anchor{1bad}
@deffn {Μέθοδος} object.__aexit__ (self, exc_type, exc_value, traceback)

Σημασιολογικά παρόμοια με @ref{16a5,,__exit__()}, η μόνη διαφορά είναι ότι πρέπει να επιστρέψει ένα `awaitable'.
@end deffn

Ένα παράδειγμα κλάσης ασύγχρονης διαχείρισης περιβάλλοντος:

@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


Added in version 3.5.


@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Μοντέλο εκτέλεσης,Το σύστημα εισαγωγής,Μοντέλο Δεδομένων,Εγχειρίδιο Αναφοράς της Γλώσσας Python
@anchor{reference/executionmodel doc}@anchor{2614}@anchor{reference/executionmodel execmodel}@anchor{2615}@anchor{reference/executionmodel execution-model}@anchor{2616}@anchor{reference/executionmodel translation-repo}@anchor{2617}
@section Μοντέλο εκτέλεσης


@geindex μοντέλο εκτέλεσης
@geindex κώδικας;μπλοκ

@menu
* Δομή ενός προγράμματος:: 
* Ονομασία και σύνδεση:: 
* Εξαιρέσεις:: 
* Συστατικά χρόνου εκτέλεσης:: 

@end menu

@node Δομή ενός προγράμματος,Ονομασία και σύνδεση,,Μοντέλο εκτέλεσης
@anchor{reference/executionmodel prog-structure}@anchor{2618}@anchor{reference/executionmodel structure-of-a-program}@anchor{2619}
@subsection Δομή ενός προγράμματος


@geindex μπλοκ

Ένα πρόγραμμα Python αποτελείται από μπλοκ κώδικα. Ένα `μπλοκ' είναι ένα κομμάτι κειμένου προγράμματος Python που εκτελείται ως μια μονάδα. Τα παρακάτω είναι μπλοκ: ένα module, το σώμα μιας συνάρτησης, ο ένας ορισμός κλάσης. Κάθε εντολή που πληκτρολογείται διαδραστικά αποτελεί μπλοκ. Ένα αρχείο δέσμης ενεργειών (ένα αρχείο που δίνεται ως τυπική είσοδος στο διερμηνέα ή καθορίζεται ως όρισμα γραμμής εντολών στον διερμηνέα) είναι ένα μπλοκ κώδικα. Μια script εντολή (μια εντολή που καθορίζεται στο διερμηνέα με την επιλογή @ref{445,,-c}) είναι ένα μπλοκ κώδικα. Μια ενότητα που εκτελείται ως ανωτέρου επιπέδου script (ως module @code{__main__}) από τη γραμμή εντολών χρησιμοποιώντας ένα όρισμα @ref{4ca,,-m} όρισμα είναι επίσης ένα μπλοκ κώδικα. Το όρισμα συμβολοσειράς που περνάει στις ενσωματωμένες συναρτήσεις @ref{184,,eval()} και @ref{185,,exec()} είναι ένα μπλοκ κώδικα.

@geindex εκτέλεση;πλαίσιο

Ένα μπλοκ κώδικα εκτελείται σε ένα `πλαίσιο εκτέλεσης'. Ένα πλαίσιο περιέχει ορισμένες πληροφορίες διαχείρισης (που χρησιμοποιούνται για αποσφαλμάτωση) και καθορίζει που και πως συνεχίζεται η εκτέλεση μετά την ολοκλήρωση της εκτέλεσης του μπλοκ κώδικα.

@node Ονομασία και σύνδεση,Εξαιρέσεις,Δομή ενός προγράμματος,Μοντέλο εκτέλεσης
@anchor{reference/executionmodel naming}@anchor{2537}@anchor{reference/executionmodel naming-and-binding}@anchor{261a}
@subsection Ονομασία και σύνδεση


@geindex χώρος ονομάτων
@geindex πεδίο

@menu
* Σύνδεση ονομάτων:: 
* Επίλυση ονομάτων:: 
* Σημειογραφία πεδία:: 
* Καθυστερημένη εκτίμηση:: 
* Ενσωματωμένες συναρτήσεις και περιορισμένη εκτέλεση:: 
* Αλληλεπίδραση με δυναμικές λειτουργίες:: 

@end menu

@node Σύνδεση ονομάτων,Επίλυση ονομάτων,,Ονομασία και σύνδεση
@anchor{reference/executionmodel bind-names}@anchor{261b}@anchor{reference/executionmodel binding-of-names}@anchor{261c}
@subsubsection Σύνδεση ονομάτων


@geindex όνομα
@geindex σύνδεση;όνομα

`Names' αναφέρονται σε αντικείμενα. Τα ονόματα εισάγονται μέσω λειτουργιών δέσμευσης ονομάτων.

@geindex από;δήλωση εισαγωγής

Οι παρακάτω δομές δεσμεύουν ονόματα:


@itemize *

@item 
τυπικές παράμετροι συναρτήσεων,

@item 
ορισμοί κλάσεων,

@item 
ορισμοί συναρτήσεων

@item 
εκφράσεις ανάθεσης

@item 
@ref{261d,,targets} που είναι αναγνωριστικά αν εμφανίζονται σε μια ανάθεση:


@itemize +

@item 
επικεφαλίδα βρόχου @ref{321,,for},

@item 
μετά το @code{as} σε μια δήλωση @ref{20a,,with}, σε ρήτρα @ref{447,,except}, σε ρήτρα @ref{448,,except*} ή στο as-pattern κατά τη δομική αντιστοίχησης μοτίβων,

@item 
σε ένα στιγμιότυπο μοτίβου κατά τη δομική αντιστοίχησης μοτίβων
@end itemize

@item 
δηλώσεις @ref{9da,,import}.

@item 
δηλώσεις @ref{85a,,type}.

@item 
@ref{7a5,,λίστες παραμέτρων τύπου}.
@end itemize

Η δήλωση @code{import} της μορφής @code{from ... import *} συνδέει όλα τα ονόματα που ορίζονται στο εισαγόμενο module, εκτός από αυτά που ξεκινούν με μια κάτω παύλα. Αυτή η μορφή μπορεί να χρησιμοποιηθεί μόνο στο επίπεδο του module.

Ένας στόχος που εμφανίζεται σε μια δήλωση @ref{1d1d,,del} θεωρείται επίσης δεσμευμένος για αυτό τον σκοπό (αν και η πραγματική σημασιολογία είναι να αποσυνδέσει το όνομα).

Κάθε δήλωση ανάθεσης ή εισαγωγής συμβαίνει μέσα σε ένα μπλοκ που ορίζεται από έναν ορισμό κλάσης ή συνάρτησης ή στο επίπεδο του module (το μπλοκ κώδικα ανώτατου επιπέδου).

@geindex ελεύθερη;μεταβλητή

Αν ένα όνομα δεσμεύεται σε ένα μπλοκ, είναι μια τοπική μεταβλητή αυτού του μπλοκ, εκτός αν δηλωθεί ως @ref{164c,,nonlocal} ή @ref{6b5,,global}. Αν ένα όνομα δεσμεύεται στο επίπεδο του module, είναι μια καθολική μεταβλητή. (Οι μεταβλητές του μπλοκ του module είναι ταυτόχρονα τοπικές και καθολικές.) Αν μια μεταβλητή χρησιμοποιείται σε ένα μπλοκ κώδικα αλλά δεν ορίζεται εκεί, είναι μια @ref{261e,,free variable}.

Κάθε εμφάνιση ενός ονόματος στο κείμενο του προγράμματος αναφέρεται στη `binding' αυτού του ονόματος που καθορίζεται από τους παρακάτω κανόνες επίλυσης ονομάτων.

@node Επίλυση ονομάτων,Σημειογραφία πεδία,Σύνδεση ονομάτων,Ονομασία και σύνδεση
@anchor{reference/executionmodel resolution-of-names}@anchor{261f}@anchor{reference/executionmodel resolve-names}@anchor{2620}
@subsubsection Επίλυση ονομάτων


@geindex πεδίο

Ένα `scope' ορίζει την ορατότητα ενός ονόματος μέσα σε ένα μπλοκ. Αν μια τοπική μεταβλητή οριστεί σε ένα μπλοκ, το πεδίο της περιλαμβάνει το μπλοκ αυτό. Αν ο ορισμός συμβαίνει σε ένα μπλοκ συνάρτησης, το πεδίο επεκτείνεται σε οποιαδήποτε μπλοκ περιέχονται μέσα σε αυτό που την ορίζει, εκτός αν ένα περιεχόμενο μπλοκ εισάγει διαφορετική σύνδεση για το όνομα.

@geindex περιβάλλον

Όταν ένα όνομα χρησιμοποιείται σε ένα μπλοκ κώδικα, επιλύεται χρησιμοποιώντας το πλησιέστερο περιβάλλον πεδίο. Το σύνολο όλων των πεδίων που είναι ορατά σε ένα μπλοκ κώδικα ονομάζεται `environment' του μπλοκ.

@geindex NameError (ενσωματωμένη εξαίρεση)
@geindex UnboundLocalError

Όταν ένα όνομα δεν βρίσκεται καθόλου, γίνεται raise μια εξαίρεση @ref{665,,NameError}. Αν το τρέχον πεδίο είναι πεδίο συνάρτησης και το όνομα αναφέρεται σε μια τοπική μεταβλητή που δεν έχει ακόμα δεσμευτεί σε κάποια τιμή στο σημείο που χρησιμοποιείται το όνομα, γίνεται raise μια εξαίρεση @ref{18d8,,UnboundLocalError}. Η @code{UnboundLocalError} είναι μια υποκλάση της @code{NameError}.

Αν μια λειτουργία σύνδεσης ονομάτων συμβεί οπουδήποτε μέσα σε ένα μπλοκ κώδικα, όλες οι χρήσεις του ονόματος μέσα στο μπλοκ αντιμετωπίζονται ως αναφορές στο τρέχον μπλοκ. Αυτό μπορεί να οδηγήσει σε σφάλματα όταν ένα όνομα χρησιμοποιείται μέσα σε ένα μπλοκ πριν δεσμευτεί. Αυτός ο κανόνας είναι λεπτός. Η Python δεν διαθέτει δηλώσεις και επιτρέπει τις λειτουργίες σύνδεση ονομάτων να συμβαίνουν οπουδήποτε μέσα σε ένα μπλοκ κώδικα. Οι τοπικές μεταβλητές ενός μπλοκ κώδικα μπορούν να προσδιοριστούν σαρώνοντας ολόκληρο το κείμενο του μπλοκ για λειτουργίες σύνδεσης ονομάτων. Δείτε @ref{2621,,την εγγραφή στο FAQ για το UnboundLocalError} για παραδείγματα.

Αν η δήλωση @ref{6b5,,global} εμφανιστεί μέσα σε ένα μπλοκ, όλες οι χρήσεις των ονομάτων που καθορίζονται στη δήλωση αναφέρονται στις συνδέσεις αυτών των ονομάτων στον χώρο ονομάτων ανώτατου επιπέδου. Τα ονόματα επιλύονται στον χώρο ανώτατου επιπέδου αναζητώντας πρώτα στον καθολικό χώρο ονομάτων, δηλαδή τον χώρο ονομάτων του module που περιέχει το μπλοκ κώδικα, και στη συνέχεια στο χώρο ονομάτων των builtins, τον χώρο ονομάτων του module @ref{13,,builtins}. Ο καθολικός χώρος ονομάτων αναζητείται πρώτος. Αν τα ονόματα δεν βρεθούν εκεί, γίνεται αναζήτηση του ενσωματωμένου χώρου ονομάτων. Εάν τα ονόματα δεν βρίσκονται επίσης στον ενσωματωμένο χώρο ονομάτων, δημιουργούνται νέες μεταβλητές στον καθολικό χώρο ονομάτων. Η καθολική δήλωση πρέπει να προηγείται όλων των χρήσεων των ονομάτων που αναφέρονται.

Η δήλωση @ref{6b5,,global} έχει το ίδιο πεδίο με μια λειτουργία σύνδεσης ονόματος στο ίδιο μπλοκ. Αν το πλησιέστερο περιβάλλον πεδίου για μια ελεύθερη μεταβλητή περιέχει μια δήλωση global, η ελεύθερη μεταβλητή αντιμετωπίζεται ως καθολική.

@c XXX say more about "nonlocal" semantics here

Η δήλωση @ref{164c,,nonlocal} προκαλεί τα αντίστοιχα ονόματα να αναφέρονται σε προηγουμένως δεσμευμένες μεταβλητές στο πλησιέστερο περιβάλλον πεδίου συνάρτησης. Μια εξαίρεση @ref{17e,,SyntaxError} εγείρεται κατά το χρόνο μεταγλώττισης αν το συγκεκριμένο δεν υπάρχει σε κανένα περιβάλλον πεδίου συνάρτησης. @ref{7a5,,Οι παράμετροι τύπου} δεν μπορούν να δεσμευτούν εκ νέου με τη δήλωση @code{nonlocal}.

@geindex module;__main__

Ο χώρος ονομάτων για ένα module δημιουργείται αυτόματα την πρώτη φορά που το module εισάγεται Το κύριο module για ένα script ονομάζεται πάντα @ref{1,,__main__}.

Τα μπλοκ ορισμού κλάσεων και τα ορίσματα στις συναρτήσεις @ref{185,,exec()} και @ref{184,,eval()} είναι ειδικές περιπτώσεις στο πλαίσιο της επίλυσης ονομάτων. Ένας ορισμός κλάσης είναι μια εκτελέσιμη δήλωση που μπορεί να χρησιμοποιεί και να ορίζει ονόματα. Αυτές οι αναφορές ακολουθούν τους κανονικούς κανόνες επίλυσης ονομάτων, με την εξαίρεση ότι οι αδέσμευτες τοπικές μεταβλητές αναζητούνται στον καθολικό χώρο ονομάτων. Ο χώρος ονομάτων του ορισμού της κλάσης γίνεται το λεξικό χαρακτηριστικών της κλάσης. Το πεδίο των ονομάτων που ορίζονται σε ένα μπλοκ κλάσης περιορίζεται στο μπλοκ της κλάσης· δεν επεκτείνεται στα μπλοκ κώδικα των μεθόδων. Αυτό περιλαμβάνει συνθέσεις και εκφράσεις γεννητριών, αλλά δεν περιλαμβάνει @ref{6b4,,πεδία σημειώσεων}, τα οποία έχουν πρόσβαση στα περιβάλλοντα πεδία της περιβάλλουσας κλάσης. Αυτό σημαίνει ότι το παρακάτω θα αποτύχει:

@example
class A:
    a = 42
    b = list(a + i for i in range(10))
@end example

Ωστόσο, το παρακάτω θα επιτύχει:

@example
class A:
    type Alias = Nested
    class Nested: pass

print(A.Alias.__value__)  # <type 'A.Nested'>
@end example

@node Σημειογραφία πεδία,Καθυστερημένη εκτίμηση,Επίλυση ονομάτων,Ονομασία και σύνδεση
@anchor{reference/executionmodel annotation-scopes}@anchor{6b4}@anchor{reference/executionmodel id1}@anchor{2622}
@subsubsection Σημειογραφία πεδία


Τα @ref{409,,Annotations}, @ref{7a5,,Οι λίστες παραμέτρων τύπου} και οι δηλώσεις @ref{85a,,type} εισάγουν `πεδία σημειογραφίας', τα οποία συμπεριφέρονται κυρίως όπως τα πεδία συναρτήσεων, αλλά με κάποιες εξαιρέσεις που συζητούνται παρακάτω.

Τα πεδία σημειογραφίας χρησιμοποιούνται στα παρακάτω συμφραζόμενα:


@itemize *

@item 
@ref{2207,,Function annotations}.

@item 
@ref{110a,,Variable annotations}.

@item 
Λίστες παραμέτρων τύπου για @ref{871,,generic type aliases}.

@item 
Λίστες τύπου παραμέτρου για @ref{86f,,generic functions}. Οι σημειογραφίες μιας γενικής συνάρτησης εκτελούνται μέσα στο πεδίο σημειώσεων, αλλά οι προεπιλογές και οι διακοσμητές της όχι.

@item 
Λίστες παραμέτρων τύπου για @ref{86e,,generic classes}. Οι βασικές κλάσεις και τα ορίσματα λέξεων-κλειδιών μιας γενικής κλάσης εκτελούνται μέσα στο πεδίο σημειώσεων, αλλά οι διακοσμητές της όχι.

@item 
Τα όρια, οι περιορισμοί  οι προεπιλεγμένες τιμές για παραμέτρους τύπου (@ref{872,,lazily evaluated}).

@item 
Η τιμή των ψευδωνύμων τύπου (@ref{872,,lazily evaluated}).
@end itemize

Τα πεδία σημειογραφίας διαφέρουν από τα πεδία συναρτήσεων με τους εξής τρόπους:


@itemize *

@item 
Τα πεδία σημειογραφίας έχουν πρόσβαση στον χώρο ονομάτων της περιβάλλουσας κλάσης. Αν ένα πεδίο σημειογραφίας βρίσκεται αμέσως μέσα σε έναν χώρο κλάσης ή μέσα σε ένα άλλο πεδίο σημειογραφίας που βρίσκεται αμέσως μέσα σε έναν χώρο κλάσης, ο κώδικας στο πεδίο σημειογραφίας μπορεί να χρησιμοποιεί ονόματα που έχουν οριστεί στον χώρο της κλάσης σαν να εκτελούνταν απευθείας στο σώμα της κλάσης. Αυτό έρχεται σε αντίθεση με τις κανονικές συναρτήσεις που ορίζονται μέσα σε κλάσεις, οι οποίες δεν μπορούν να έχουν πρόσβαση σε ονόματα που έχουν οριστεί στο χώρο της κλάσης.

@item 
Οι εκφράσεις σε πεδία σημειογραφίας δεν μπορούν να περιέχουν τις εκφράσεις @ref{d93,,yield}, @code{yield from}, @ref{432,,await} ή @ref{2623,,;=} εκφράσεις. (Αυτές οι εκφράσεις επιτρέπονται σε άλλα πεδία που περιέχονται μέσα στο πεδίο σημειογραφίας.)

@item 
Τα ονόματα που ορίζονται σε πεδία σημειογραφίας δεν μπορούν να δεσμευτούν εκ νέου με δηλώσεις @ref{164c,,nonlocal} σε εσωτερικά πεδία. Αυτό περιλαμβάνει μόνο παραμέτρους τύπου, καθώς και κανένα άλλο συντακτικό στοιχείο που μπορεί να εμφανιστεί μέσα σε πεδία σημειώσεων δεν μπορεί να εισαγάγει νέα ονόματα.

@item 
Ενώ τα πεδία σημειογραφίας έχουν ένα εσωτερικό όνομα, αυτό το όνομα δεν αντικατοπτρίζεται στο @ref{1f19,,qualified name} των αντικειμένων που ορίζονται μέσα στο πεδίο.Αντίθετα, το @ref{140d,,__qualname__} αυτών των αντικειμένων είναι σαν το αντικείμενο να είχε οριστεί στο περιβάλλων πεδίο.
@end itemize


Added in version 3.12: Τα πεδία σημειώσεων εισήχθησαν στην Python 3.12 ως μέρος του 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.



Άλλαξε στην έκδοση 3.13: Οι περιοχές σχολίων τύπου χρησιμοποιούνται επίσης για τις προεπιλεγμένες τιμές παραμέτρων τύπου, όπως εισάγεται από το 
@geindex Python Enhancement Proposals; PEP 696
PEP 696@footnote{https://peps.python.org/pep-0696/}.



Άλλαξε στην έκδοση 3.14: Οι περιοχές σχολίων τύπου χρησιμοποιούνται επίσης για τα annotations, όπως εισάγεται από το 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/} and 
@geindex Python Enhancement Proposals; PEP 749
PEP 749@footnote{https://peps.python.org/pep-0749/}.


@node Καθυστερημένη εκτίμηση,Ενσωματωμένες συναρτήσεις και περιορισμένη εκτέλεση,Σημειογραφία πεδία,Ονομασία και σύνδεση
@anchor{reference/executionmodel id2}@anchor{2624}@anchor{reference/executionmodel lazy-evaluation}@anchor{872}
@subsubsection Καθυστερημένη εκτίμηση


Τα περισσότερα πεδία annotation `αξιολογούνται νωχελικά'. Αυτό περιλαμβάνει annotations, τις τιμές των ψευδωνύμων τύπου που δημιουργούνται μέσω της δήλωσης @ref{85a,,type} και τα όρια, τους περιορισμούς και τις προεπιλεγμένες τιμές των μεταβλητών τύπου που δημιουργούνται μέσω της σύνταξης παραμέτρων @ref{7a5,,type parameter syntax}. Αυτό σημαίνει ότι δεν αξιολογούνται όταν δημιουργείται το ψευδώνυμο τύπου ή η μεταβλητή τύπου ή όταν δημιουργείται το αντικείμενο που φέρει σχολιασμούς. Αντίθετα, αξιολογούνται μόνο όταν είναι απαραίτητο, για παράδειγμα όταν γίνεται πρόσβαση στο χαρακτηριστικό @code{__value__} σε ένα ψευδώνυμο τύπου.

Παράδειγμα:

@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

Εδώ η εξαίρεση εγείρεται μόνο όταν γίνει πρόσβαση στο χαρακτηριστικό @code{__value__} του ψευδωνύμου τύπου ή στο χαρακτηριστικό @code{__bound__} της μεταβλητής τύπου.

Αυτή η συμπεριφορά είναι κυρίως χρήσιμη για αναφορές σε τύπους που δεν έχουν ακόμη οριστεί κατά τη δημιουργία του ψευδωνύμου τύπου ή της μεταβλητής τύπου. Για παράδειγμα, η καθυστερημένη εκτίμηση επιτρέπει τη δημιουργία αμοιβαίων αναδρομικών ψευδωνύμων τύπων:

@example
from typing import Literal

type SimpleExpr = int | Parenthesized
type Parenthesized = tuple[Literal["("], Expr, Literal[")"]]
type Expr = SimpleExpr | tuple[SimpleExpr, Literal["+", "-"], Expr]
@end example

Οι τιμές που αξιολογούνται καθυστερημένα αξιολογούνται στο @ref{6b4,,πεδίο σημειογραφίας}, που σημαίνει ότι τα ονόματα που εμφανίζονται μέσα στην καθυστερημένα αξιολογούμενη τιμή αναζητούνται σαν να χρησιμοποιήθηκαν στο αμέσως περιβάλλον πεδίο.


Added in version 3.12.


@node Ενσωματωμένες συναρτήσεις και περιορισμένη εκτέλεση,Αλληλεπίδραση με δυναμικές λειτουργίες,Καθυστερημένη εκτίμηση,Ονομασία και σύνδεση
@anchor{reference/executionmodel builtins-and-restricted-execution}@anchor{2625}@anchor{reference/executionmodel restrict-exec}@anchor{2626}
@subsubsection Ενσωματωμένες συναρτήσεις και περιορισμένη εκτέλεση


@geindex περιορισμένη;εκτέλεση

Οι χρήστες δεν θα πρέπει να τροποποιούν το @code{__builtins__}· είναι αυστηρά μια λεπτομέρεια υλοποίησης. Οι χρήστες που θέλουν να παρακάμψουν τιμές στον χώρο ονομάτων των ενσωματωμένων συναρτήσεων θα πρέπει να κάνουν @ref{9da,,import} το module @ref{13,,builtins} και να τροποποιούν τα χαρακτηριστικά του κατάλληλα.

Ο χώρος ονομάτων των ενσωματωμένων συναρτήσεων που σχετίζεται με την εκτέλεση ενός μπλοκ κώδικα βρίσκεται στην πραγματικότητα μέσω αναζήτησης του ονόματος @code{__builtins__} στον καθολικό του χώρο ονομάτων· αυτό θα πρέπει να είναι ένα λεξικό ή ένα module (στη δεύτερη περίπτωση χρησιμοποιείται το λεξικό του module). Από προεπιλογή, όταν βρισκόμαστε στο module @ref{1,,__main__}, το @code{__builtins__} είναι το ενσωματωμένο module @ref{13,,builtins}· όταν βρισκόμαστε σε οποιοδήποτε άλλο module, το @code{__builtins__} είναι ένα ψευδώνυμο για το λεξικό του ίδιου του module @code{builtins}.

@node Αλληλεπίδραση με δυναμικές λειτουργίες,,Ενσωματωμένες συναρτήσεις και περιορισμένη εκτέλεση,Ονομασία και σύνδεση
@anchor{reference/executionmodel dynamic-features}@anchor{2627}@anchor{reference/executionmodel interaction-with-dynamic-features}@anchor{2628}
@subsubsection Αλληλεπίδραση με δυναμικές λειτουργίες


Η επίλυση ονομάτων των ελεύθερων μεταβλητών συμβαίνει κατά το χρόνο εκτέλεσης, όχι κατά το χρόνο μεταγλώττισης. Αυτό σημαίνει ότι ο παρακάτω κώδικας θα εκτυπώσει το 42:

@example
i = 10
def f():
    print(i)
i = 42
f()
@end example

@c XXX from * also invalid with relative imports (at least currently)

Οι συναρτήσεις @ref{184,,eval()} και @ref{185,,exec()} δεν έχουν πρόσβαση στο πλήρες περιβάλλον για την επίλυση ονομάτων. Τα ονόματα μπορεί να επιλύονται στους τοπικούς και καθολικούς χώρους ονομάτων του καλούντος. Οι ελεύθερες μεταβλητές δεν επιλύονται στο πλησιέστερο περιβάλλον πεδίου, αλλά στον καθολικό χώρο ονομάτων. @footnote{
Αυτός ο περιορισμός προκύπτει επειδή ο κώδικας που εκτελείται από αυτές τις λειτουργίες δεν είναι διαθέσιμος τη στιγμή που το module μεταγλωττίζεται.
} Οι συναρτήσεις @code{exec()} και @code{eval()} έχουν προαιρετικά ορίσματα για να παρακάμψουν τους καθολικούς και τοπικούς χώρους ονομάτων. Αν καθοριστεί μόνο ένας χώρος ονομάτων, χρησιμοποιείται και για τους δύο.

@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 Εξαιρέσεις,Συστατικά χρόνου εκτέλεσης,Ονομασία και σύνδεση,Μοντέλο εκτέλεσης
@anchor{reference/executionmodel exceptions}@anchor{2629}@anchor{reference/executionmodel id4}@anchor{262a}
@subsection Εξαιρέσεις


@geindex εξαίρεση

@geindex κάνει raise μια εξαίρεση
@geindex διαχειρίζεται μια εξαίρεση
@geindex διαχειριστής εξαιρέσεων
@geindex σφάλματα
@geindex διαχείριση σφαλμάτων

Οι εξαιρέσεις είναι ένας τρόπος διακοπής της κανονικής ροής ελέγχου ενός μπλοκ κώδικα, προκειμένου να αντιμετωπιστούν σφάλματα ή άλλες εξαιρετικές συνθήκες. Μια εξαίρεση `γίνεται raise' στο σημείο όπου εντοπίζεται το σφάλμα· μπορεί να `αντιμετωπιστεί' από το περιβάλλον μπλοκ κώδικα ή από οποιοδήποτε μπλοκ κώδικα που άμεσα ή έμμεσα εκτέλεσε το μπλοκ κώδικα όπου συνέβη το σφάλμα.

Ο διερμηνέας της Python εγείρει μια εξαίρεση όταν εντοπίσει ένα σφάλμα κατά την εκτέλεση(όπως η διαίρεση με το μηδέν). Ένα πρόγραμμα Python μπορεί επίσης να εγείρει ρητά μια  εξαίρεση με τη δήλωση @ref{9e4,,raise}. Οι διαχειριστές εξαιρέσεων καθορίζονται με τη δήλωση @ref{ad6,,try} … @ref{447,,except}. Η ρήτρα @ref{44c,,finally} μιας τέτοιας δήλωσης μπορεί να χρησιμοποιηθεί για να καθοριστεί κώδικας καθαρισμού, ο οποίος δεν διαχειρίζεται την εξαίρεση αλλά εκτελείται ανεξάρτητα από το αν προηγήθηκε εξαίρεση ή όχι στον προηγούμενο κώδικα.

@geindex μοντέλο τερματισμού

Η Python χρησιμοποιεί το μοντέλο διαχείρισης σφαλμάτων «τερματισμού»: ένας διαχειριστής εξαιρέσεων μπορεί να διαπιστώσει τι συνέβη και να συνεχίσει την εκτέλεση σε ένα εξωτερικό επίπεδο, αλλά δεν μπορεί να διορθώσει την αιτία του σφάλματος και να επαναλάβει τη λειτουργία που απέτυχε (εκτός αν επανεισαχθεί το προβληματικό κομμάτι κώδικα από την αρχή).

@geindex SystemExit (ενσωματωμένη εξαίρεση)

Όταν μια εξαίρεση δεν αντιμετωπιστεί καθόλου, ο διερμηνέας τερματίζει την εκτέλεση του προγράμματος ή επιστρέφει στον διαδραστικό κύριο βρόχο του. Και στις δύο περιπτώσεις, εκτυπώνει το ίχνος της στοίβας, εκτός αν η εξαίρεση είναι @ref{10f7,,SystemExit}.

Οι εξαιρέσεις αναγνωρίζονται από στιγμιότυπα κλάσεων. Η ρήτρα @ref{447,,except} επιλέγεται ανάλογα με την κλάση του στιγμιότυπου: πρέπει να αναφέρεται στην κλάση του στιγμιότυπου ή σε μια @ref{155f,,μη εικονική βασική κλάση} αυτής. Το στιγμιότυπο μπορεί να παραληφθεί από τον διαχειριστή και να μεταφέρει πρόσθετες πληροφορίες σχετικά με την εξαιρετική συνθήκη.

@cartouche
@quotation Σημείωση 
Τα μηνύματα εξαιρέσεων δεν αποτελούν μέρος του API της Python. Το περιεχόμενό τους μπορεί να αλλάξει από τη μία έκδοση της Python στην επόμενη χωρίς προειδοποίηση και δεν θα πρέπει να βασίζεται σε αυτά ο κώδικας που θα εκτελεστεί σε πολλαπλές εκδόσεις του διερμηνέα.
@end quotation
@end cartouche

Δείτε επίσης την περιγραφή της δήλωσης @ref{ad6,,try} στην ενότητα @ref{ad6,,The try statement} και της δήλωσης @ref{9e4,,raise} στην ενότητα @ref{9e4,,Η εντολή raise}.

@node Συστατικά χρόνου εκτέλεσης,,Εξαιρέσεις,Μοντέλο εκτέλεσης
@anchor{reference/executionmodel execcomponents}@anchor{262b}@anchor{reference/executionmodel runtime-components}@anchor{262c}
@subsection Συστατικά χρόνου εκτέλεσης


@menu
* Γενικό μοντέλο υπολογισμού:: 
* Μοντέλο χρόνου εκτέλεσης της Python:: 

@end menu

@node Γενικό μοντέλο υπολογισμού,Μοντέλο χρόνου εκτέλεσης της Python,,Συστατικά χρόνου εκτέλεσης
@anchor{reference/executionmodel general-computing-model}@anchor{262d}
@subsubsection Γενικό μοντέλο υπολογισμού


Το μοντέλο εκτέλεσης της Python δεν λειτουργεί σε κενό. Εκτελείται σε μια μηχανή υποδοχής και μέσω του περιβάλλοντος χρόνου εκτέλεσης αυτής της υποδοχής, συμπεριλαμβανομένου του λειτουργικού της συστήματος (OS), αν υπάρχει. Όταν εκτελείται ένα πρόγραμμα, τα εννοιολογικά επίπεδα του τρόπου με τον οποίο εκτελείται στην υποδοχή μοιάζουν κάπως έτσι:

@quotation


@display
`μηχανή υποδοχής'@w{ }
@display
`διαδικασία' (παγκόσμιοι πόροι)@w{ }
@display
`νήμα' (εκτελεί κώδικα μηχανής)@w{ }
@end display
@end display
@end display


@end quotation

Κάθε διαδικασία αντιπροσωπεύει ένα πρόγραμμα που εκτελείται στην υποδοχή. Σκεφτείτε κάθε διαδικασία ως το δεδομένο μέρος του προγράμματός της. Σκεφτείτε τα νήματα της διαδικασίας ως το εκτελεστικό μέρος του προγράμματος. Αυτή η διάκριση θα είναι σημαντική για την κατανόηση του εννοιολογικού χρόνου εκτέλεσης της Python.

Η διαδικασία, ως το δεδομένο μέρος, είναι το εκτελεστικό πλαίσιο στο οποίο εκτελείται το πρόγραμμα. Αποτελείται κυρίως από το σύνολο των πόρων που ανατίθενται στο πρόγραμμα από την υποδοχή, συμπεριλαμβανομένης της μνήμης, των σημάτων, των χειριστηρίων αρχείων, των υποδοχών και των μεταβλητών περιβάλλοντος.

Οι διαδικασίες είναι απομονωμένες και ανεξάρτητες η μία από την άλλη. (Το ίδιο ισχύει και για τις υποδοχές.) Η υποδοχή διαχειρίζεται την πρόσβαση της διαδικασίας στους ανατεθειμένους πόρους της, εκτός από τον συντονισμό μεταξύ διαδικασιών.

Κάθε νήμα αντιπροσωπεύει την πραγματική εκτέλεση του κώδικα μηχανής του προγράμματος, που εκτελείται σε σχέση με τους πόρους που έχουν ανατεθεί στη διαδικασία του προγράμματος. Είναι αυστηρά στην υποδοχή ο τρόπος και ο χρόνος με τον οποίο πραγματοποιείται αυτή η εκτέλεση.

Από την άποψη της Python, ένα πρόγραμμα ξεκινά πάντα με ακριβώς ένα νήμα. Ωστόσο, το πρόγραμμα μπορεί να αναπτυχθεί για να εκτελείται σε πολλαπλά ταυτόχρονα νήματα. Δεν υποστηρίζουν όλοι οι οικοδεσπότες πολλαπλά νήματα ανά διαδικασία, αλλά οι περισσότεροι το κάνουν. Σε αντίθεση με τις διαδικασίες, τα νήματα σε μια διαδικασία δεν είναι απομονωμένα και ανεξάρτητα το ένα από το άλλο. Συγκεκριμένα, όλα τα νήματα σε μια διαδικασία μοιράζονται όλους τους πόρους της διαδικασίας.

Το θεμελιώδες σημείο των νημάτων είναι ότι το καθένα `εκτελείται' ανεξάρτητα, ταυτόχρονα με τα άλλα. Αυτό μπορεί να είναι μόνο εννοιολογικά ταυτόχρονα («concurrently») ή φυσικά («in parallel»). Σε κάθε περίπτωση, τα νήματα εκτελούνται αποτελεσματικά με μη συγχρονισμένο ρυθμό.

@cartouche
@quotation Σημείωση 
Αυτός ο μη συγχρονισμένος ρυθμός σημαίνει ότι δεν εγγυάται ότι η μνήμη της διαδικασίας θα παραμείνει συνεπής για τον κώδικα που εκτελείται σε οποιοδήποτε δοσμένο νήμα. Επομένως, τα πολυνηματικά προγράμματα πρέπει να φροντίζουν να συντονίζουν την πρόσβαση σε σκόπιμα κοινόχρηστους πόρους. Ομοίως, πρέπει να φροντίζουν να είναι απόλυτα επιμελείς ώστε να μην έχουν πρόσβαση σε `άλλους' πόρους σε πολλαπλά νήματα· διαφορετικά, δύο νήματα που εκτελούνται ταυτόχρονα μπορεί να παρεμβαίνουν κατά λάθος στη χρήση κάποιων κοινόχρηστων δεδομένων. Όλα αυτά ισχύουν τόσο για προγράμματα Python όσο και για τον χρόνο εκτέλεσης της Python.

Το κόστος αυτής της ευρείας, μη δομημένης απαίτησης είναι το αντάλλαγμα για τον τύπο της ακατέργαστης ταυτόχρονης εκτέλεσης που παρέχουν τα νήματα. Η εναλλακτική λύση στην απαιτούμενη πειθαρχία γενικά σημαίνει την αντιμετώπιση μη ντετερμινιστικών σφαλμάτων και διαφθοράς δεδομένων.
@end quotation
@end cartouche

@node Μοντέλο χρόνου εκτέλεσης της Python,,Γενικό μοντέλο υπολογισμού,Συστατικά χρόνου εκτέλεσης
@anchor{reference/executionmodel python-runtime-model}@anchor{262e}
@subsubsection Μοντέλο χρόνου εκτέλεσης της Python


Τα ίδια εννοιολογικά επίπεδα ισχύουν για κάθε πρόγραμμα Python, με μερικά επιπλέον επίπεδα δεδομένων συγκεκριμένα για την Python:

@quotation


@display
`μηχανή υποδοχής'@w{ }
@display
`διαδικασία' (παγκόσμιοι πόροι)@w{ }
@display
Παγκόσμιος χρόνος εκτέλεσης της Python (`κατάσταση')@w{ }
@display
Διερμηνέας Python (`κατάσταση')@w{ }
@display
`thread' (εκτελεί bytecode Python και «C-API»)@w{ }
@display
`Κατάσταση' νήματος Python@w{ }
@end display
@end display
@end display
@end display
@end display
@end display


@end quotation

Σε εννοιολογικό επίπεδο: όταν ξεκινά ένα πρόγραμμα Python, μοιάζει ακριβώς με αυτό το διάγραμμα, με ένα από κάθε στοιχείο. Ο χρόνος εκτέλεσης μπορεί να αναπτυχθεί ώστε να περιλαμβάνει πολλαπλούς διερμηνείς, και κάθε διερμηνέας μπορεί να αναπτυχθεί ώστε να περιλαμβάνει πολλαπλές καταστάσεις νημάτων.

@cartouche
@quotation Σημείωση 
Μια υλοποίηση της Python δεν θα υλοποιήσει απαραίτητα τα επίπεδα χρόνου εκτέλεσης με διακριτό ή ακόμη και συγκεκριμένο τρόπο. Η μόνη εξαίρεση είναι τα σημεία όπου τα διακριτά επίπεδα καθορίζονται άμεσα ή εκτίθενται στους χρήστες, όπως μέσω του module @ref{f6,,threading}.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Ο αρχικός διερμηνέας ονομάζεται συνήθως ο «κύριος» διερμηνέας. Ορισμένες υλοποιήσεις της Python, όπως η CPython, αναθέτουν ειδικούς ρόλους στον κύριο διερμηνέα.

Ομοίως, το νήμα υποδοχής όπου αρχικοποιήθηκε ο χρόνος εκτέλεσης είναι γνωστό ως το «κύριο» νήμα. Μπορεί να είναι διαφορετικό από το αρχικό νήμα της διαδικασίας, αν και συχνά είναι το ίδιο. Σε ορισμένες περιπτώσεις, το «κύριο νήμα» μπορεί να είναι ακόμη πιο συγκεκριμένο και να αναφέρεται στην αρχική κατάσταση νήματος. Ένας χρόνος εκτέλεσης της Python μπορεί να αναθέσει συγκεκριμένες ευθύνες στο κύριο νήμα, όπως η διαχείριση σημάτων.
@end quotation
@end cartouche

Συνολικά, ο χρόνος εκτέλεσης της Python αποτελείται από την παγκόσμια κατάσταση χρόνου εκτέλεσης, τους διερμηνείς και τις καταστάσεις νημάτων. Ο χρόνος εκτέλεσης διασφαλίζει ότι όλη αυτή η κατάσταση παραμένει συνεπής κατά τη διάρκειά της ζωής του, ιδιαίτερα όταν χρησιμοποιείται με πολλαπλά νήματα υποδοχής.

Ο παγκόσμιος χρόνος εκτέλεσης, σε εννοιολογικό επίπεδο, είναι απλώς ένα σύνολο διερμηνέων. Ενώ αυτοί οι διερμηνείς είναι διαφορετικά απομονωμένοι και ανεξάρτητοι ο ένας από τον άλλον, μπορεί να μοιράζονται ορισμένα δεδομένα ή άλλους πόρους. Ο χρόνος εκτέλεσης είναι υπεύθυνος για τη διαχείριση αυτών των παγκόσμιων πόρων με ασφάλεια. Η πραγματική φύση και διαχείριση αυτών των πόρων είναι συγκεκριμένη για την υλοποίηση. Τελικά, η εξωτερική χρησιμότητα του παγκόσμιου χρόνου εκτέλεσης περιορίζεται στη διαχείριση διερμηνέων.

Σε αντίθεση, ένας «διερμηνέας» είναι εννοιολογικά αυτό που θα σκεφτόμασταν κανονικά ως ο (πλήρως εξοπλισμένος) «χρόνος εκτέλεσης της Python». Όταν ο κώδικας μηχανής που εκτελείται σε ένα νήμα υποδοχής αλληλεπιδράει με τον χρόνο εκτέλεσης της Python, καλεί την Python στο πλαίσιο ενός συγκεκριμένου διερμηνέα.

@cartouche
@quotation Σημείωση 
Ο όρος «διερμηνέας» εδώ δεν είναι ο ίδιος με τον «διερμηνέα bytecode», που είναι αυτός που εκτελείται τακτικά σε νήματα, εκτελώντας μεταγλωττισμένο κώδικα Python.

Σε έναν ιδανικό κόσμο, ο όρος «χρόνος εκτέλεσης της Python» θα αναφερόταν σε αυτό που τώρα ονομάζουμε «διερμηνέα». Ωστόσο, έχει ονομαστεί «διερμηνέας» τουλάχιστον από την εισαγωγή του το 1997 (CPython:a027efa5b@footnote{https://github.com/python/cpython/commit/a027efa5b}).
@end quotation
@end cartouche

Κάθε διερμηνέας ενσωματώνει πλήρως όλη την κατάσταση που δεν είναι παγκόσμια για τη διαδικασία και δεν είναι ειδική για το νήμα που χρειάζεται ο χρόνος εκτέλεσης της Python για να λειτουργήσει. Σημαντικά, η κατάσταση του διερμηνέα διατηρείται μεταξύ των χρήσεων. Περιλαμβάνει θεμελιώδη δεδομένα όπως το @ref{19ba,,sys.modules}. Ο χρόνος εκτέλεσης διασφαλίζει ότι πολλαπλά νήματα που χρησιμοποιούν τον ίδιο διερμηνέα θα τον μοιράζονται με ασφάλεια μεταξύ τους.

Μια υλοποίηση της Python μπορεί να υποστηρίζει τη χρήση πολλαπλών διερμηνέων ταυτόχρονα στην ίδια διαδικασία. Είναι ανεξάρτητοι και απομονωμένοι ο ένας από τον άλλον. Για παράδειγμα, κάθε διερμηνέας έχει το δικό του @ref{19ba,,sys.modules}.

Για το χρόνο εκτέλεσης ειδικό για τα νήματα, κάθε διερμηνέας έχει ένα σύνολο καταστάσεων νημάτων, τις οποίες διαχειρίζεται, με τον ίδιο τρόπο που ο παγκόσμιος χρόνος εκτέλεσης περιέχει ένα σύνολο διερμηνέων. Μπορεί να έχει καταστάσεις νημάτων για όσα νήματα υποδοχής χρειάζεται. Μπορεί ακόμη και να έχει πολλαπλές καταστάσεις νημάτων για το ίδιο νήμα υποδοχής, αν και αυτό δεν είναι τόσο συνηθισμένο.

Κάθε κατάσταση νήματος, εννοιολογικά, έχει όλα τα δεδομένα χρόνου εκτέλεσης ειδικά για το νήμα που χρειάζεται ένας διερμηνέας για να λειτουργήσει σε ένα νήμα υποδοχής. Η κατάσταση νήματος περιλαμβάνει την τρέχουσα εξαίρεση που έγινε raise και τη στοίβα κλήσεων Python του νήματος. Μπορεί να περιλαμβάνει και άλλους πόρους ειδικούς για το νήμα.

@cartouche
@quotation Σημείωση 
Ο όρος «νήμα Python» μπορεί μερικές φορές να αναφέρεται σε μια κατάσταση νήματος, αλλά συνήθως σημαίνει ένα νήμα που δημιουργείται χρησιμοποιώντας το module @ref{f6,,threading}.
@end quotation
@end cartouche

Κάθε κατάσταση νήματος, κατά τη διάρκεια της ζωής της, συνδέεται πάντα με ακριβώς έναν διερμηνέα και ακριβώς ένα νήμα υποδοχής. Θα χρησιμοποιηθεί μόνο σε αυτό το νήμα και με αυτόν τον διερμηνέα.

Πολλαπλές καταστάσεις νημάτων μπορεί να συνδέονται με το ίδιο νήμα υποδοχής, είτε για διαφορετικούς διερμηνείς είτε ακόμη και για τον ίδιο διερμηνέα. Ωστόσο, για οποιοδήποτε δεδομένο νήμα υποδοχής, μόνο μία από τις καταστάσεις νημάτων που συνδέονται με αυτό μπορεί να χρησιμοποιηθεί από το νήμα τη φορά.

Οι καταστάσεις νημάτων είναι απομονωμένες και ανεξάρτητες η μία από την άλλη και δεν μοιράζονται κανένα δεδομένο, εκτός από το ενδεχόμενο να μοιράζονται έναν διερμηνέα και αντικείμενα ή άλλους πόρους που ανήκουν σε αυτόν τον διερμηνέα.

Μόλις εκτελείται ένα πρόγραμμα, μπορούν να δημιουργηθούν νέα νήματα Python χρησιμοποιώντας το module @ref{f6,,threading} (σε πλατφόρμες και υλοποιήσεις Python που υποστηρίζουν νήματα). Μπορούν να δημιουργηθούν επιπλέον διαδικασίες χρησιμοποιώντας τα modules @ref{a5,,os}, @ref{df,,subprocess} και @ref{98,,multiprocessing}. Οι διερμηνείς μπορούν να δημιουργηθούν και να χρησιμοποιηθούν με το module @ref{25,,interpreters}. Οι συναρτήσεις-συνεργάτες (async) μπορούν να εκτελεστούν χρησιμοποιώντας το @ref{b,,asyncio} σε κάθε διερμηνέα, συνήθως μόνο σε ένα νήμα (συχνά το κύριο νήμα).

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Το σύστημα εισαγωγής,Expressions,Μοντέλο εκτέλεσης,Εγχειρίδιο Αναφοράς της Γλώσσας Python
@anchor{reference/import doc}@anchor{262f}@anchor{reference/import importsystem}@anchor{2551}@anchor{reference/import the-import-system}@anchor{2630}@anchor{reference/import translation-repo}@anchor{2631}
@section Το σύστημα εισαγωγής


@geindex μηχανισμός εισαγωγής

Ο κώδικας Python σε ένα @ref{1be7,,module} αποκτά πρόσβαση στον κώδικα ενός άλλου module μέσω της διαδικασίας του @ref{2632,,importing}. Η δήλωση @ref{9da,,import} είναι ο πιο συνηθισμένος τρόπος ενεργοποίησης του μηχανισμού import, αλλά δεν είναι ο μόνος. Συναρτήσεις όπως η @ref{927,,importlib.import_module()} και η ενσωματωμένη @ref{ca6,,__import__()} μπορούν επίσης να χρησιμοποιηθούν για την ενεργοποίηση του μηχανισμού εισαγωγής.

Η δήλωση @ref{9da,,import} συνδυάζει δύο λειτουργίες· αναζητά το module με το συγκεκριμένο όνομα και στη συνέχεια συνδέει τα αποτελέσματα αυτής της αναζήτησης σε ένα όνομα στο τοπικό scope. Η λειτουργία αναζήτησης της δήλωσης @code{import} ορίζεται ως κλήση της συνάρτησης @ref{ca6,,__import__()}, με τα κατάλληλα ορίσματα. Η τιμή επιστροφής της @code{__import__()} χρησιμοποιείται για να εκτελεστεί η λειτουργία δέσμευσης ονόματος της δήλωσης @code{import}. Δείτε τη δήλωση @code{import} για τις ακριβείς λεπτομέρειες αυτής της λειτουργίας.

Μια άμεση κλήση της @ref{ca6,,__import__()} εκτελεί μόνο την αναζήτηση του module και, αν βρεθεί, τη λειτουργία δημιουργίας του. Παρότι μπορεί να προκύψουν ορισμένες παρενέργειες, όπως η εισαγωγή των γονικών πακέτων και η ενημέρωση διάφορων προσωρινών μνημών (συμπεριλαμβανομένου του @ref{19ba,,sys.modules}), μόνο η δήλωση @ref{9da,,import} εκτελεί λειτουργία δέσμευσης ονόματος.

Όταν εκτελείται μια δήλωση @ref{9da,,import}, καλείται η τυπική ενσωματωμένη συνάρτηση @ref{ca6,,__import__()}. Άλλοι μηχανισμοί ενεργοποίησης του συστήματος εισαγωγής (όπως η @ref{927,,importlib.import_module()}) μπορεί να επιλέξουν να παρακάμψουν τη @code{__import__()} και να χρησιμοποιήσουν δικές τους λύσεις για την υλοποίηση της σημασιολογίας της εισαγωγής.

Όταν εισάγεται ένα module για πρώτη φορά, η Python το αναζητά και, αν το βρει, δημιουργεί ένα αντικείμενο module @footnote{
Δείτε την @ref{11c7,,types.ModuleType}.
}, αρχικοποιώντας το. Αν το module με το συγκεκριμένο όνομα δεν μπορεί να βρεθεί, γίνεται raise η εξαίρεση @ref{1be,,ModuleNotFoundError}. Η Python υλοποιεί διάφορες στρατηγικές αναζήτησης για το module όταν ενεργοποιείται ο μηχανισμός εισαγωγής. Αυτές οι στρατηγικές μπορούν να τροποποιηθούν και να επεκταθούν μέσω διάφορων hooks που περιγράφονται στις παρακάτω ενότητες.


Άλλαξε στην έκδοση 3.3: Το σύστημα εισαγωγής έχει ενημερωθεί ώστε να υλοποιεί πλήρως τη δεύτερη φάση του 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}. Δεν υπάρχει πλέον κανένας έμμεσος μηχανισμός εισαγωγής - ο πλήρης μηχανισμός εισαγωγής εκτίθεται μέσω του @ref{10e3,,sys.meta_path}. Επιπλέον, έχει υλοποιηθεί εγγενής υποστήριξη για namespace packages (βλ. 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}).


@menu
* importlib: importlib<10>. 
* Πακέτα: Πακέτα<2>. 
* Αναζήτηση:: 
* Φόρτωση:: 
* Finder βασισμένος στη διαδρομή:: 
* Αντικατάσταση του τυπικού συστήματος εισαγωγής:: 
* Σχετικές εισαγωγές σε πακέτα:: 
* Ειδικές περιπτώσεις για το __main__:: 
* Αναφορές:: 

@end menu

@node importlib<10>,Πακέτα<2>,,Το σύστημα εισαγωγής
@anchor{reference/import importlib}@anchor{2633}
@subsection @code{importlib}


Το module @ref{7a,,importlib} παρέχει ένα πλούσιο API για αλληλεπίδραση με το σύστημα εισαγωγής. Για παράδειγμα, η @ref{927,,importlib.import_module()} παρέχει ένα προτεινόμενο, απλούστερο API από την ενσωματωμένη @ref{ca6,,__import__()} για την ενεργοποίηση του μηχανισμού εισαγωγής. Ανατρέξτε στην τεκμηρίωση της βιβλιοθήκης @code{importlib} για περισσότερες λεπτομέρειες.

@node Πακέτα<2>,Αναζήτηση,importlib<10>,Το σύστημα εισαγωγής
@anchor{reference/import packages}@anchor{2634}
@subsection Πακέτα


@geindex πακέτο

Η Python έχει μόνο έναν τύπο αντικειμένου module, και όλα τα modules είναι αυτού του τύπου, ανεξάρτητα από το αν το module υλοποιείται σε Python, C ή κάτι άλλο. Για να βοηθήσει στην οργάνωση των modules και να παρέχει μια ιεραρχία ονοματοδοσίας, η Python διαθέτει την έννοια των @ref{4c1,,packages}.

Μπορείτε να σκεφτείτε τα packages ως φακέλους σε ένα σύστημα αρχείων και τα modules ως αρχεία μέσα σε φακέλους, αλλά μην πάρετε αυτή την αναλογία κυριολεκτικά, καθώς packages και modules δεν είναι απαραίτητο να προέρχονται από το σύστημα αρχείων. Για τους σκοπούς αυτής της τεκμηρίωσης, θα χρησιμοποιήσουμε αυτή τη βολική αναλογία φακέλων και αρχείων. Όπως οι φάκελοι του συστήματος αρχείων, τα packages οργανώνονται ιεραρχικά, και μπορούν να περιέχουν subpackages, καθώς και κανονικά modules.

Είναι σημαντικό να έχετε υπόψη ότι όλα τα packages είναι modules, αλλά δεν είναι όλα τα modules packages. Με άλλα λόγια, τα packages είναι απλώς ένας ειδικός τύπος module. Συγκεκριμένα, οποιοδήποτε module περιέχει το χαρακτηριστικό @code{__path__} θεωρείται package.

Όλα τα modules έχουν ένα όνομα. Τα ονόματα των subpackages διαχωρίζονται από το όνομα του γονικού package με τελεία, αντίστοιχα με τη συνηθισμένη σύνταξη πρόσβασης σε χαρακτηριστικά στην Python. Έτσι, μπορεί να έχετε ένα package με όνομα @ref{3e,,email}, το οποίο με τη σειρά του έχει ένα subpackage με όνομα @ref{48,,email.mime} και ένα module μέσα σε αυτό το subpackage με όνομα @ref{50,,email.mime.text}.

@menu
* Κανονικά πακέτα:: 
* Namespace πακέτα:: 

@end menu

@node Κανονικά πακέτα,Namespace πακέτα,,Πακέτα<2>
@anchor{reference/import regular-packages}@anchor{2635}
@subsubsection Κανονικά πακέτα


@geindex πακέτο;κανονικό

Η Python ορίζει δύο τύπους packages: τα @ref{2636,,regular packages} και τα @ref{52e,,namespace packages}. Τα regular packages είναι τα παραδοσιακά packages όπως υπήρχαν στην Python 3.2 και παλαιότερα. Ένα regular package υλοποιείται συνήθως ως φάκελος που περιέχει ένα αρχείο @code{__init__.py}. Όταν εισάγεται ένα regular package, το αρχείο @code{__init__.py} εκτελείται έμμεσα, και τα αντικείμενα που ορίζει δεσμεύονται σε ονόματα στο namespace του package. Το @code{__init__.py} μπορεί να περιέχει τον ίδιο κώδικα Python που μπορεί να περιέχει οποιοδήποτε άλλο module, και η Python θα προσθέσει ορισμένα επιπλέον χαρακτηριστικά στο module όταν εισάγεται.

Για παράδειγμα, η ακόλουθη διάταξη στο σύστημα αρχείων ορίζει ένα package ανωτέρου επιπέδου @code{parent} με τρία subpackages:

@example
parent/
    __init__.py
    one/
        __init__.py
    two/
        __init__.py
    three/
        __init__.py
@end example

Η εισαγωγή του @code{parent.one} θα εκτελέσει έμμεσα τα @code{parent/__init__.py} και @code{parent/one/__init__.py}. Μετέπειτα εισαγωγές του @code{parent.two} ή του @code{parent.three} θα εκτελέσουν τα @code{parent/two/__init__.py} και @code{parent/three/__init__.py} αντίστοιχα.

@node Namespace πακέτα,,Κανονικά πακέτα,Πακέτα<2>
@anchor{reference/import namespace-packages}@anchor{2637}@anchor{reference/import reference-namespace-package}@anchor{2638}
@subsubsection Namespace πακέτα


@geindex πακέτο;namespace
@geindex πακέτο;τμήμα (portion)

Ένα namespace πακέτο είναι ένας συνδυασμός από διάφορα @ref{2639,,portions}, όπου κάθε portion συνεισφέρει ένα subpackage στο γονικό πακέτο. Τα portions μπορεί να βρίσκονται σε διαφορετικές τοποθεσίες στο σύστημα αρχείων. Μπορεί επίσης να βρίσκονται σε zip αρχεία, στο δίκτυο ή οπουδήποτε αλλού αναζητά η Python κατά την εισαγωγή. Τα namespace πακέτα μπορεί να αντιστοιχούν ή να μην αντιστοιχούν άμεσα σε αντικείμενα στο σύστημα αρχείων· μπορεί να είναι «εικονικά» modules που δεν έχουν συγκεκριμένη φυσική αναπαράσταση.

Τα namespace πακέτα δεν χρησιμοποιούν μια συνηθισμένη λίστα για το χαρακτηριστικό @code{__path__}. Αντί γι’ αυτό χρησιμοποιούν έναν προσαρμοσμένο iterable τύπο, ο οποίος θα εκτελέσει αυτόματα μία νέα αναζήτηση για portions του πακέτου στην επόμενη προσπάθεια εισαγωγής μέσα σε αυτό το πακέτο, αν αλλάξει το path του γονικού πακέτου (ή το @ref{194,,sys.path} για πακέτο ανωτέρου επιπέδου).

Με τα namespace πακέτα, δεν υπάρχει αρχείο @code{parent/__init__.py}. Στην πράξη, μπορεί να βρεθούν πολλοί φάκελοι @code{parent} κατά την αναζήτηση εισαγωγής, όπου ο καθένας παρέχεται από διαφορετικό portion. Έτσι, το @code{parent/one} ενδέχεται να μην βρίσκεται φυσικά δίπλα στο @code{parent/two}. Σε αυτή την περίπτωση, η Python θα δημιουργήσει ένα namespace πακέτο για το πακέτο ανωτέρου επιπέδου @code{parent} κάθε φορά που γίνεται εισαγωγή αυτού ή κάποιου από τα subpackages του.

Δείτε επίσης το 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} για την προδιαγραφή των namespace πακέτων.

@node Αναζήτηση,Φόρτωση,Πακέτα<2>,Το σύστημα εισαγωγής
@anchor{reference/import searching}@anchor{263a}
@subsection Αναζήτηση


Για να ξεκινήσει η αναζήτηση, η Python χρειάζεται το @ref{1f19,,πλήρως αναγνωρισμένο} όνομα του module (ή του πακέτου, αλλά για τους σκοπούς αυτής της συζήτησης η διαφορά δεν έχει σημασία) που εισάγεται. Αυτό το όνομα μπορεί να προέρχεται από διάφορα ορίσματα της δήλωσης @ref{9da,,import} ή από τις παραμέτρους των συναρτήσεων @ref{927,,importlib.import_module()} ή @ref{ca6,,__import__()}.

Αυτό το όνομα θα χρησιμοποιηθεί σε διάφορες φάσεις της αναζήτησης import και μπορεί να είναι μια διαδρομή με τελείες προς ένα submodule, π.χ. @code{foo.bar.baz}. Σε αυτή την περίπτωση, η Python πρώτα προσπαθεί να εισάγει το @code{foo}, μετά το @code{foo.bar} και τέλος το @code{foo.bar.baz}. Αν αποτύχει κάποιες από τις ενδιάμεσες εισαγωγές, γίνεται raise η @ref{1be,,ModuleNotFoundError}.

@menu
* Η προσωρινή μνήμη του module:: 
* Finders και loaders:: 
* Εισαγωγή hooks:: 
* Το meta path:: 

@end menu

@node Η προσωρινή μνήμη του module,Finders και loaders,,Αναζήτηση
@anchor{reference/import the-module-cache}@anchor{263b}
@subsubsection Η προσωρινή μνήμη του module


@geindex sys.modules

Το πρώτο σημείο που ελέγχεται κατά την αναζήτηση εισαγωγής είναι το @ref{19ba,,sys.modules}. Αυτή η αντιστοίχιση λειτουργεί ως προσωρινή μνήμη όλων των modules που έχουν εισαχθεί στο παρελθόν, συμπεριλαμβανομένων των ενδιάμεσων διαδρομών. Έτσι, αν το @code{foo.bar.baz} είχε εισαχθεί προηγουμένως, το @code{sys.modules} θα περιέχει εγγραφές για τα @code{foo}, @code{foo.bar} και @code{foo.bar.baz}. Κάθε κλειδί θα έχει ως τιμή το αντίστοιχο αντικείμενο module.

Κατά την εισαγωγή, το όνομα του module αναζητείται στο @ref{19ba,,sys.modules} και, αν υπάρχει, η συσχετισμένη τιμή είναι το module που ικανοποιεί την εισαγωγή και η διαδικασία ολοκληρώνεται. Ωστόσο, αν η τιμή είναι @code{None}, τότε γίνεται raise το @ref{1be,,ModuleNotFoundError}. Αν το όνομα του module λείπει, η Python θα συνεχίσει να αναζητά το module.

Το @ref{19ba,,sys.modules} είναι εγγράψιμο. Η διαγραφή ενός κλειδιού μπορεί να μην καταστρέψει το αντίστοιχο module (καθώς άλλα modules μπορεί να κρατούν αναφορές σε αυτό), αλλά θα ακυρώσει την εγγραφή της προσωρινής μνήμης για το module με το συγκεκριμένο όνομα, προκαλώντας την Python να το αναζητήσει ξανά στην επόμενο εισαγωγή. Το κλειδί μπορεί επίσης να οριστεί σε @code{None}, αναγκάζοντας την επόμενο εισαγωγή του module να καταλήξει σε @ref{1be,,ModuleNotFoundError}.

Προσοχή όμως: αν κρατήσετε μια αναφορά στο αντικείμενο module, ακυρώσετε την εγγραφή του στην προσωρινή μνήμη του @ref{19ba,,sys.modules} και μετά ξανακάνετε εισαγωγή το module με το ίδιο όνομα, τα δύο αντικείμενα module `δεν' θα είναι τα ίδια. Αντίθετα, η @ref{928,,importlib.reload()} θα επαναχρησιμοποιήσει το `ίδιο' αντικείμενο module και απλώς θα επαναρχικοποιήσει τα περιεχόμενά του εκτελώντας ξανά τον κώδικα του module.

@node Finders και loaders,Εισαγωγή hooks,Η προσωρινή μνήμη του module,Αναζήτηση
@anchor{reference/import finders-and-loaders}@anchor{263c}@anchor{reference/import id2}@anchor{263d}
@subsubsection Finders και loaders


@geindex finder
@geindex loader
@geindex module spec

Αν το module με το συγκεκριμένο όνομα δεν βρεθεί στο @ref{19ba,,sys.modules}, τότε ενεργοποιείται το πρωτόκολλο εισαγωγής της Python για να βρεθεί και να φορτωθεί το module. Αυτό το πρωτόκολλο αποτελείται από δύο εννοιολογικά αντικείμενα: @ref{263e,,finders} και @ref{1c30,,loaders}. Ο ρόλος ενός finder είναι να καθορίσει αν μπορεί να βρει το module με το συγκεκριμένο όνομα, χρησιμοποιώντας όποια στρατηγική γνωρίζει. Αντικείμενα που υλοποιούν και τις δύο αυτές διεπαφές αναφέρονται ως @ref{263f,,importers} - επιστρέφουν τον εαυτό τους όταν διαπιστώσουν ότι μπορούν να φορτώσουν το ζητούμενο module.

Η Python περιλαμβάνει αρκετούς προεπιλεγμένους finders και importers. Το πρώτο γνωρίζει πώς να εντοπίζει built-in modules, και το δεύτερο πώς να εντοπίζει παγωμένα (frozen) modules. Ένας τρίτος προεπιλεγμένος finder αναζητά modules σε ένα @ref{2640,,import path}. Το import path είναι μια λίστα από τοποθεσίες που μπορεί να είναι διαδρομές του συστήματος αρχείων ή zip αρχεία. Μπορεί επίσης να επεκταθεί ώστε να αναζητά οποιονδήποτε εντοπίσιμο πόρο, όπως αυτούς που προσδιορίζονται από URLs.

Ο μηχανισμός εισαγωγής είναι επεκτάσιμος, επομένως μπορούν να προστεθούν νέοι finders ώστε να επεκταθεί το εύρος και η κάλυψη της αναζήτησης των modules.

Οι finders δεν φορτώνουν πραγματικά τα modules. Αν μπορούν να βρουν το module με το συγκεκριμένο όνομα, επιστρέφουν ένα `module spec', δηλαδή μια ενθυλάκωση της πληροφορίας που σχετίζεται με την εισαγωγή του module, την οποία ο μηχανισμός εισαγωγής χρησιμοποιεί στη συνέχεια για να φορτώσει το module.

Οι ακόλουθες ενότητες περιγράφουν πιο αναλυτικά το πρωτόκολλο για finders και loaders, συμπεριλαμβανομένου του πώς μπορείτε να δημιουργήσετε και να καταχωρίσετε νέους, ώστε να επεκτείνετε τον μηχανισμό εισαγωγής.


Άλλαξε στην έκδοση 3.4: Σε παλαιότερες εκδόσεις της Python, οι finders επέστρεφαν απευθείας @ref{1c30,,loaders}, ενώ τώρα επιστρέφουν module specs που `περιέχουν' loaders. Οι loaders εξακολουθούν να χρησιμοποιούνται κατά την εισαγωγή, αλλά έχουν λιγότερες ευθύνες.


@node Εισαγωγή hooks,Το meta path,Finders και loaders,Αναζήτηση
@anchor{reference/import import-hooks}@anchor{2641}
@subsubsection Εισαγωγή hooks


@geindex hooks εισαγωγής
@geindex meta hooks
@geindex hooks διαδρομής
@geindex hooks;εισαγωγή
@geindex hooks;meta
@geindex hooks;διαδρομή

Ο μηχανισμός εισαγωγής είναι σχεδιασμένος ώστε να είναι επεκτάσιμος· ο βασικός μηχανισμός για αυτό είναι η `εισαγωγή hooks'. Υπάρχουν δύο τύποι εισαγωγής hooks: `meta hooks' και `import path hooks'.

Τα meta hooks καλούνται στην αρχή της επεξεργασίας εισαγωγής, πριν συμβεί οποιαδήποτε άλλη επεξεργασία εισαγωγής, εκτός από την αναζήτηση στην προσωρινή μνήμη του @ref{19ba,,sys.modules}. Αυτό επιτρέπει στα meta hooks να υπερκαλύπτουν την επεξεργασία του @ref{194,,sys.path}, τα παγωμένα modules ή ακόμη και τα built-in modules. Τα meta hooks καταχωρίζονται προσθέτοντας νέα αντικείμενα finder στο @ref{10e3,,sys.meta_path}, όπως περιγράφεται παρακάτω.

Τα import path hooks καλούνται ως μέρος της επεξεργασίας του @ref{194,,sys.path} (ή του @code{package.__path__}), στο σημείο όπου συναντάται το αντίστοιχο στοιχείο διαδρομής. Τα import path hooks καταχωρίζονται προσθέτοντας νέα callables στο @ref{13cd,,sys.path_hooks}, όπως περιγράφεται παρακάτω.

@node Το meta path,,Εισαγωγή hooks,Αναζήτηση
@anchor{reference/import the-meta-path}@anchor{2642}
@subsubsection Το meta path


@geindex sys.meta_path
@geindex finder;find_spec

Όταν το module με το συγκεκριμένο όνομα δεν βρεθεί στο @ref{19ba,,sys.modules}, η Python στη συνέχεια το αναζητά στο @ref{10e3,,sys.meta_path}, το οποίο περιέχει μια λίστα από meta path finder αντικείμενα. Αυτοί οι finders ερωτώνται με τη σειρά για να διαπιστωθεί αν γνωρίζουν πώς να χειριστούν το module. Οι meta path finders πρέπει να υλοποιούν μια μέθοδο με όνομα @ref{c3f,,find_spec()}, η οποία λαμβάνει τρία ορίσματα: ένα όνομα, ένα import path και (προαιρετικά) ένα target module. Ο meta path finder μπορεί να χρησιμοποιήσει οποιαδήποτε στρατηγική θέλει για να καθορίσει αν μπορεί να χειριστεί το module ή όχι.

Αν ο meta path finder γνωρίζει πώς να χειριστεί το module, επιστρέφει ένα spec αντικείμενο. Αν δεν μπορεί να χειριστεί το module, επιστρέφει @code{None}. Αν η επεξεργασία του @ref{10e3,,sys.meta_path} φτάσει στο τέλος της λίστας χωρίς να επιστραφεί spec, τότε γίνεται raise το @ref{1be,,ModuleNotFoundError}. Οποιεσδήποτε άλλες εξαιρέσεις γίνονται raise απλώς προωθούνται προς τα πάνω, τερματίζοντας τη διαδικασία εισαγωγής.

Η μέθοδος @ref{c3f,,find_spec()} των meta path finders καλείται με δύο ή τρία ορίσματα. Το πρώτο είναι το πλήρως αναγνωρισμένο όνομα του module που εισάγεται, π.χ. @code{foo.bar.baz}. Το δεύτερο όρισμα είναι οι καταχωρήσεις διαδρομής που θα χρησιμοποιηθούν για την αναζήτηση του module. Για modules ανωτέρου επιπέδου, το δεύτερο όρισμα είναι @code{None}, αλλά για submodules ή subpackages, είναι η τιμή του χαρακτηριστικού @code{__path__} του γονικού πακέτου. Αν δεν είναι δυνατή η πρόσβαση στο κατάλληλο @code{__path__}, γίνεται raise το @ref{1be,,ModuleNotFoundError}. Το τρίτο όρισμα είναι ένα υπάρχον αντικείμενο module που θα αποτελέσει αργότερα τον στόχο της φόρτωσης. Το σύστημα εισαγωγής περνά target module μόνο κατά την επαναφόρτωση.

Το meta path μπορεί να διασχιστεί πολλές φορές για ένα μόνο αίτημα εισαγωγής. Για παράδειγμα, υποθέτοντας ότι κανένα από τα εμπλεκόμενα modules δεν έχει ήδη προστεθεί στην προσωρινή μνήμη, η εισαγωγή του @code{foo.bar.baz} θα εκτελέσει πρώτα μία εισαγωγή ανωτέρου επιπέδου, καλώντας το @code{mpf.find_spec("foo", None, None)} σε κάθε meta path finder (@code{mpf}). Αφού εισαχθεί το @code{foo}, το @code{foo.bar} θα εισαχθεί διασχίζοντας το meta path για δεύτερη φορά, καλώντας την @code{mpf.find_spec("foo.bar", foo.__path__, None)}. Μόλις γίνει η εισαγωγή του @code{foo.bar}, η τελική διάσχιση θα καλέσει το @code{mpf.find_spec("foo.bar.baz", foo.bar.__path__, None)}.

Ορισμένοι meta path finders υποστηρίζουν μόνο εισαγωγές ανωτέρου επιπέδου. Αυτοί οι importers θα επιστρέφουν πάντα @code{None} όταν ως δεύτερο όρισμα περάσει οτιδήποτε άλλο εκτός από @code{None}.

Το προεπιλεγμένο @ref{10e3,,sys.meta_path} της Python έχει τρεις meta path finders: έναν που γνωρίζει πώς να εισάγει ενσωματωμένα modules, έναν που γνωρίζει πώς να εισάγει παγωμένα modules, και έναν που γνωρίζει πώς να εισάγει modules από ένα @ref{2640,,import path} (δηλ. τον @ref{2643,,path based finder}).


Άλλαξε στην έκδοση 3.4: Η μέθοδος @ref{c3f,,find_spec()} των meta path finders αντικατέστησε τη @code{find_module()}, η οποία πλέον χαρακτηριστεί ως απαρχαιωμένη. Αν και θα συνεχίσει να λειτουργεί χωρίς αλλαγές, ο μηχανισμός εισαγωγής θα τη δοκιμάζει μόνο αν ο finder δεν υλοποιεί τη @code{find_spec()}.



Άλλαξε στην έκδοση 3.10: Η χρήση της @code{find_module()} από το σύστημα εισαγωγής πλέον κάνει raise την @ref{907,,ImportWarning}.



Άλλαξε στην έκδοση 3.12: Η @code{find_module()} έχει αφαιρεθεί. Χρησιμοποιήστε την @ref{c3f,,find_spec()} στη θέση της.


@node Φόρτωση,Finder βασισμένος στη διαδρομή,Αναζήτηση,Το σύστημα εισαγωγής
@anchor{reference/import loading}@anchor{2644}
@subsection Φόρτωση


Αν και όταν βρεθεί ένα module spec, ο μηχανισμός εισαγωγής θα το χρησιμοποιήσει (και τον loader που περιέχει) για να φορτώσει το module. Ακολουθεί μια προσέγγιση του τι συμβαίνει στο στάδιο φόρτωσης του import:

@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

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

Σημειώστε τις ακόλουθες λεπτομέρειες:


@itemize *

@item 
Αν υπάρχει ήδη ένα αντικείμενο module με το συγκεκριμένο όνομα στο @ref{19ba,,sys.modules}, το import θα το έχει ήδη επιστρέψει.

@item 
Το module θα υπάρχει στο @ref{19ba,,sys.modules} πριν ο loader εκτελέσει τον κώδικα του module. Αυτό είναι κρίσιμο, επειδή ο κώδικας του module μπορεί (άμεσα ή έμμεσα) να εισάγει τον εαυτό του· η προσθήκη του στο @code{sys.modules} εκ των προτέρων αποτρέπει ατέρμονη αναδρομή στη χειρότερη περίπτωση και πολλαπλή φόρτωση στην καλύτερη.

@item 
Αν η φόρτωση αποτύχει, το module που απέτυχε – και μόνο αυτό – αφαιρείται από το @ref{19ba,,sys.modules}. Οποιοδήποτε module βρίσκεται ήδη στην προσωρινή μνήμη του @code{sys.modules}, καθώς και οποιοδήποτε module φορτώθηκε επιτυχώς ως παρενέργεια, πρέπει να παραμείνει στην προσωρινή μνήμη. Αυτό έρχεται σε αντίθεση με την επαναφόρτωση, όπου ακόμη και το module που αποτυγχάνει παραμένει στο @code{sys.modules}.

@item 
Αφού δημιουργηθεί το module αλλά πριν την εκτέλεση, ο μηχανισμός εισαγωγής ορίζει τα χαρακτηριστικά του module που σχετίζονται με την εισαγωγή («_init_module_attrs» στο παραπάνω παράδειγμα ψευδοκώδικα), όπως συνοψίζεται σε μια @ref{2552,,μεταγενέστερη ενότητα}.

@item 
Η εκτέλεση του module είναι η κρίσιμη στιγμή της φόρτωσης κατά την οποία γεμίζει το namespace του module. Η εκτέλεση ανατίθεται εξ ολοκλήρου στον loader, ο οποίος αποφασίζει τι θα συμπληρωθεί και με ποιον τρόπο.

@item 
Το module που δημιουργείται κατά τη φόρτωση και περνά στη exec_module() ενδέχεται να μην είναι αυτό που επιστρέφεται στο τέλος του import @footnote{
Η υλοποίηση του importlib αποφεύγει να χρησιμοποιεί απευθείας την τιμή επιστροφής. Αντ’ αυτού, λαμβάνει το αντικείμενο module αναζητώντας το όνομα του module στο @ref{19ba,,sys.modules}. Έμμεση συνέπεια αυτού είναι ότι ένα εισηγμένο module μπορεί να αντικαταστήσει τον εαυτό του στο @code{sys.modules}. Αυτή είναι μία ειδική συμπεριφορά της συγκεκριμένης υλοποίησης και δεν είναι εγγυημένο ότι λειτουργεί σε άλλες υλοποιήσεις της Python.
}.
@end itemize


Άλλαξε στην έκδοση 3.4: The import system has taken over the boilerplate responsibilities of
loaders.  These were previously performed by the
@code{importlib.abc.Loader.load_module} method.



Άλλαξε στην έκδοση 3.15: The @code{load_module} method is no longer used.


@menu
* Loaders:: 
* Submodules:: 
* Module specs:: 
* Χαρακτηριστικά __path__ στα modules:: 
* Reprs των modules:: 
* Ακύρωση cached bytecode:: 

@end menu

@node Loaders,Submodules,,Φόρτωση
@anchor{reference/import loaders}@anchor{2645}
@subsubsection Loaders


Οι module loaders παρέχουν την κρίσιμη λειτουργία της φόρτωσης: την εκτέλεση του module. Ο μηχανισμός εισαγωγής καλεί τη μέθοδο @ref{c40,,importlib.abc.Loader.exec_module()} με ένα μόνο όρισμα, το αντικείμενο module που θα εκτελεστεί. Οποιαδήποτε τιμή επιστρέφει η @code{exec_module()} αγνοείται.

Οι loaders πρέπει να ικανοποιούν τις ακόλουθες απαιτήσεις:


@itemize *

@item 
Αν το module είναι Python module (σε αντίθεση με ένα ενσωματωμένο module ή δυναμικά φορτωμένη επέκταση), ο loader θα πρέπει να εκτελέσει τον κώδικα του module στο καθολικό namespace του module (@code{module.__dict__}).

@item 
Αν ο loader δεν μπορεί να εκτελέσει το module, θα πρέπει να κάνει raise το @ref{1bd,,ImportError}, αν και οποιαδήποτε άλλη εξαίρεση γίνει raise κατά τη @ref{c40,,exec_module()} θα προωθηθεί προς τα πάνω.
@end itemize

Σε πολλές περιπτώσεις, ο finder και ο loader μπορεί να είναι το ίδιο αντικείμενο· σε αυτές τις περιπτώσεις, η μέθοδος @ref{c3f,,find_spec()} απλώς θα επιστρέψει ένα spec με τον loader ορισμένο σε @code{self}.

Οι module loaders μπορούν, προαιρετικά, να δημιουργούν το αντικείμενο module κατά τη φόρτωση υλοποιώντας μια μέθοδο @ref{106f,,create_module()}. Παίρνει ένα όρισμα, το module spec, και επιστρέφει το νέο αντικείμενο module που θα χρησιμοποιηθεί κατά τη φόρτωση. Η @code{create_module()} δεν χρειάζεται να ορίσει χαρακτηριστικά στο αντικείμενο module. Αν η μέθοδος επιστρέψει @code{None}, ο μηχανισμός εισαγωγής θα δημιουργήσει ο ίδιος το νέο module.


Added in version 3.4: Η μέθοδος @ref{106f,,create_module()} των loaders.



Άλλαξε στην έκδοση 3.4: The @code{importlib.abc.Loader.load_module} method was replaced by
@ref{c40,,exec_module()} and the import
machinery assumed all the boilerplate responsibilities of loading.

Για συμβατότητα με υπάρχοντες loaders, ο μηχανισμός εισαγωγής θα χρησιμοποιήσει τη μέθοδο @code{load_module()} αν υπάρχει και ο loader δεν υλοποιεί την @code{exec_module()}. Ωστόσο, η @code{load_module()} είναι απαρχαιωμένη και οι loaders θα πρέπει να υλοποιούν την @code{exec_module()}.

Η μέθοδος @code{load_module()} πρέπει να υλοποιεί όλη την τυποποιημένη λειτουργικότητα φόρτωσης που περιγράφεται παραπάνω, επιπλέον της εκτέλεσης του module. Ισχύουν οι ίδιοι περιορισμοί, με κάποιες επιπλέον διευκρινίσεις:


@itemize *

@item 
Αν υπάρχει ήδη αντικείμενο module με το συγκεκριμένο όνομα στο @ref{19ba,,sys.modules}, ο loader πρέπει να χρησιμοποιήσει αυτό το υπάρχον module. (Διαφορετικά, η @ref{928,,importlib.reload()} δεν θα λειτουργεί σωστά.) Αν το module με το συγκεκριμένο όνομα δεν υπάρχει στο @code{sys.modules}, ο loader πρέπει να δημιουργήσει νέο αντικείμενο module και να το προσθέσει στο @code{sys.modules}.

@item 
Το module `πρέπει' να υπάρχει στο @ref{19ba,,sys.modules} πριν ο loader εκτελέσει τον κώδικα του module, ώστε να αποτραπεί ατέρμονη αναδρομή ή πολλαπλή φόρτωση.

@item 
Αν η φόρτωση αποτύχει, ο loader πρέπει να αφαιρέσει οποιαδήποτε modules έχει εισάγει στο @ref{19ba,,sys.modules}, αλλά πρέπει να αφαιρέσει `μόνο' το/τα module(s) που απέτυχαν, και μόνο αν ο loader έχει φορτώσει τα module(s) αυτά ρητά.
@end itemize



Άλλαξε στην έκδοση 3.5: Γίνεται raise η @ref{2c9,,DeprecationWarning} όταν ορίζεται η @code{exec_module()} αλλά δεν ορίζεται η @code{create_module()}.



Άλλαξε στην έκδοση 3.6: Γίνεται raise το @ref{1bd,,ImportError} όταν ορίζεται η @code{exec_module()} αλλά δεν ορίζεται η @code{create_module()}.



Άλλαξε στην έκδοση 3.10: Η χρήση της @code{load_module()} θα κάνει raise την @ref{907,,ImportWarning}.


@node Submodules,Module specs,Loaders,Φόρτωση
@anchor{reference/import submodules}@anchor{2646}
@subsubsection Submodules


Όταν ένα submodule φορτώνεται με οποιονδήποτε μηχανισμό (π.χ. @code{importlib} APIs, τις δηλώσεις @code{import} ή @code{import-from}, ή την ενσωματωμένη @code{__import__()}), δημιουργείται μια δέσμευση στο namespace του γονικού module προς το αντικείμενο του submodule. Για παράδειγμα, αν το πακέτο @code{spam} έχει submodule @code{foo}, μετά την εισαγωγή του @code{spam.foo}, το @code{spam} θα έχει ένα χαρακτηριστικό @code{foo} που είναι δεσμευμένο στο submodule. Ας πούμε ότι έχετε την ακόλουθη δομή φακέλων:

@example
spam/
    __init__.py
    foo.py
@end example

και το @code{spam/__init__.py} περιέχει την ακόλουθη γραμμή:

@example
from .foo import Foo
@end example

τότε, η εκτέλεση των παρακάτω δημιουργεί δεσμεύσεις ονομάτων για τα @code{foo} και @code{Foo} στο 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

Με δεδομένους τους γνώριμους κανόνες δέσμευσης ονομάτων της Python, αυτό μπορεί να φαίνεται παράξενο, αλλά στην πραγματικότητα είναι θεμελιώδες χαρακτηριστικό του συστήματος εισαγωγής. Η αμετάβλητη συνθήκη είναι ότι, αν έχετε @code{sys.modules['spam']} και @code{sys.modules['spam.foo']} (όπως θα είχατε μετά την παραπάνω εισαγωγή), το δεύτερο πρέπει να εμφανίζεται ως το χαρακτηριστικό @code{foo} του πρώτου.

@node Module specs,Χαρακτηριστικά __path__ στα modules,Submodules,Φόρτωση
@anchor{reference/import id4}@anchor{2647}@anchor{reference/import module-specs}@anchor{2557}
@subsubsection Module specs


Ο μηχανισμός εισαγωγής χρησιμοποιεί ποικιλία πληροφοριών για κάθε module κατά την εισαγωγή, ειδικά πριν τη φόρτωση. Οι περισσότερες από αυτές τις πληροφορίες είναι κοινές για όλα τα modules. Ο σκοπός του spec ενός module είναι να ενθυλακώσει αυτή την πληροφορία που σχετίζεται με την εισαγωγή, σε βάση ανά module.

Η χρήση ενός spec κατά την εισαγωγή επιτρέπει τη μεταφορά κατάστασης μεταξύ των συστατικών του συστήματος εισαγωγής, π.χ. μεταξύ του finder που δημιουργεί το module spec και του loader που το εκτελεί. Το σημαντικότερο είναι ότι επιτρέπει στον μηχανισμό εισαγωγής να εκτελεί τις τυποποιημένες λειτουργίες φόρτωσης, ενώ χωρίς module spec αυτή η ευθύνη ανήκε στον loader.

Το spec του module εκτίθεται ως @ref{2555,,module.__spec__}. Η κατάλληλη ρύθμιση του @code{__spec__} ισχύει εξίσου για @ref{2648,,modules που αρχικοποιούνται κατά την εκκίνηση του διερμηνέα}. Η μόνη εξαίρεση είναι το @code{__main__}, όπου το @code{__spec__} @ref{2649,,τίθεται σε None σε ορισμένες περιπτώσεις}.

Δείτε την @ref{245d,,ModuleSpec} για λεπτομέρειες σχετικά με τα περιεχόμενα του module spec.


Added in version 3.4.


@node Χαρακτηριστικά __path__ στα modules,Reprs των modules,Module specs,Φόρτωση
@anchor{reference/import package-path-rules}@anchor{2558}@anchor{reference/import path-attributes-on-modules}@anchor{264a}
@subsubsection Χαρακτηριστικά __path__ στα modules


Το χαρακτηριστικό @ref{2243,,__path__} θα πρέπει να είναι μια (ενδεχομένως κενή) @ref{8ff,,sequence} από συμβολοσειρές που απαριθμούν τις τοποθεσίες όπου θα βρεθούν τα submodules του πακέτου. Εξ ορισμού, αν ένα module έχει χαρακτηριστικό @code{__path__}, τότε είναι @ref{4c1,,package}.

Το χαρακτηριστικό @ref{2243,,__path__} ενός πακέτου χρησιμοποιείται κατά την εισαγωγή των subpackages του. Μέσα στον μηχανισμό εισαγωγής, λειτουργεί παρόμοια με το @ref{194,,sys.path}, δηλαδή παρέχει μια λίστα τοποθεσιών στις οποίες αναζητούνται modules κατά την εισαγωγή. Ωστόσο, το @code{__path__} είναι συνήθως πολύ πιο περιορισμένο από το @code{sys.path}.

Οι ίδιοι κανόνες που ισχύουν για το @ref{194,,sys.path} ισχύουν επίσης και για το @code{__path__} ενός πακέτου. Τα @ref{13cd,,sys.path_hooks} (που περιγράφονται παρακάτω) λαμβάνονται υπόψη κατά τη διάσχιση του @code{__path__} ενός πακέτου.

Το αρχείο @code{__init__.py} ενός πακέτου μπορεί να ορίζει ή να τροποποιεί το χαρακτηριστικό @ref{2243,,__path__} του πακέτου, και αυτός ήταν συνήθως ο τρόπος με τον οποίο υλοποιούνταν τα namespace πακέτα πριν το 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}. Με την υιοθέτηση του 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}, τα namespace πακέτα δεν χρειάζεται πλέον να παρέχουν αρχεία @code{__init__.py} που περιέχουν μόνο κώδικα χειρισμού του @code{__path__}· ο μηχανισμός εισαγωγής ορίζει αυτόματα σωστά το @code{__path__} για το namespace πακέτο.

@node Reprs των modules,Ακύρωση cached bytecode,Χαρακτηριστικά __path__ στα modules,Φόρτωση
@anchor{reference/import module-reprs}@anchor{264b}
@subsubsection Reprs των modules


Από προεπιλογή, όλα τα modules έχουν ένα χρησιμοποιήσιμο repr· ωστόσο, ανάλογα με τα χαρακτηριστικά που ορίζονται παραπάνω και στο spec του module, μπορείτε να ελέγχετε πιο ρητά το repr των αντικειμένων module.

Αν το module έχει spec (@code{__spec__}), ο μηχανισμός εισαγωγής θα προσπαθήσει να παράγει repr από αυτό. Αν αυτό αποτύχει ή δεν υπάρχει spec, το σύστημα εισαγωγής θα δημιουργήσει ένα προεπιλεγμένο repr χρησιμοποιώντας όποια πληροφορία είναι διαθέσιμη στο module. Θα προσπαθήσει να χρησιμοποιήσει τα @code{module.__name__}, @code{module.__file__} και @code{module.__loader__} ως είσοδο για το repr, με προεπιλογές για οποιαδήποτε πληροφορία λείπει.

Ακολουθούν οι ακριβείς κανόνες που χρησιμοποιούνται:


@itemize *

@item 
Αν το module έχει χαρακτηριστικό @code{__spec__}, οι πληροφορίες στο spec χρησιμοποιούνται για να παραχθεί το repr. Λαμβάνονται υπόψη τα χαρακτηριστικά «name», «loader», «origin» και «has_location».

@item 
Αν το module έχει χαρακτηριστικό @code{__file__}, αυτό χρησιμοποιείται ως μέρος του repr του module.

@item 
Αν το module δεν έχει @code{__file__} αλλά έχει @code{__loader__} που δεν είναι @code{None}, τότε το repr του loader χρησιμοποιείται ως μέρος του repr του module.

@item 
Διαφορετικά, χρησιμοποιείται απλώς το @code{__name__} του module στο repr.
@end itemize


Άλλαξε στην έκδοση 3.12: Η χρήση της @code{module_repr()}, η οποία ήταν δηλωμένη ως απαρχαιωμένη από την Python 3.4, αφαιρέθηκε στην Python 3.12 και δεν καλείται πλέον κατά την επίλυση του repr ενός module.


@node Ακύρωση cached bytecode,,Reprs των modules,Φόρτωση
@anchor{reference/import cached-bytecode-invalidation}@anchor{264c}@anchor{reference/import pyc-invalidation}@anchor{9e3}
@subsubsection Ακύρωση cached bytecode


Πριν η Python φορτώσει cached bytecode από ένα αρχείο @code{.pyc}, ελέγχει αν η προσωρινή μνήμη είναι ενημερωμένη σε σχέση με το πηγαίο αρχείο @code{.py}. Από προεπιλογή, η Python το κάνει αυτό αποθηκεύοντας τη χρονική σήμανση της τελευταίας τροποποίησης και το μέγεθος του πηγαίου αρχείου στο αρχείο προσωρινής μνήμης κατά την εγγραφή του. Κατά το χρόνο εκτέλεσης, το σύστημα εισαγωγής επικυρώνει το αρχείο προσωρινής μνήμης ελέγχοντας τα αποθηκευμένα μεταδεδομένα του αρχείου προσωρινής μνήμης σε σχέση με τα μεταδεδομένα του πηγαίου αρχείου.

Η Python υποστηρίζει επίσης αρχεία προσωρινής μνήμης βασισμένα σε hash, τα οποία αποθηκεύουν ένα hash του περιεχομένου του πηγαίου αρχείου αντί για τα μεταδεδομένα του. Υπάρχουν δύο παραλλαγές των @code{.pyc} αρχείων βασισμένων σε hash: checked και unchecked. Για τα checked @code{.pyc} αρχεία που βασίζονται σε hash, η Python επικυρώνει το αρχείο προσωρινής μνήμης δημιουργώντας hash του πηγαίου αρχείου και συγκρίνοντας το αποτέλεσμα με το hash στο αρχείο προσωρινής μνήμης. Αν ένα checked αρχείο προσωρινής μνήμης βασισμένο σε hash βρεθεί μη έγκυρο, η Python το αναδημιουργεί και γράφει ένα νέο checked αρχείο προσωρινής μνήμης βασισμένο σε hash. Για τα unchecked @code{.pyc} αρχεία βασισμένα σε hash, η Python απλώς θεωρεί ότι το αρχείο προσωρινής μνήμης είναι έγκυρο αν υπάρχει. Η συμπεριφορά επικύρωσης των  @code{.pyc} αρχείων βασισμένων σε hash μπορεί να υπερκαλυφθεί με τη σημαία @ref{2311,,--check-hash-based-pycs}.


Άλλαξε στην έκδοση 3.7: Προστέθηκαν`@w{`}.pyc`@w{`} αρχεία βασισμένα σε hash. Προηγουμένως, η Python υποστήριζε μόνο ακύρωση των bytecode caches με βάση χρονικές σημάνσεις.


@node Finder βασισμένος στη διαδρομή,Αντικατάσταση του τυπικού συστήματος εισαγωγής,Φόρτωση,Το σύστημα εισαγωγής
@anchor{reference/import the-path-based-finder}@anchor{264d}
@subsection Finder βασισμένος στη διαδρομή


@geindex path based finder

Όπως αναφέρθηκε προηγουμένως, η Python συνοδεύεται από αρκετούς προεπιλεγμένους meta path finders. Ένας από αυτούς, που ονομάζεται @ref{2643,,path based finder} (@ref{13cc,,PathFinder}), αναζητά σε ένα @ref{2640,,import path}, το οποίο περιέχει μια λίστα από @ref{264e,,path entries}. Κάθε path entry ονομάζει μια τοποθεσία όπου θα αναζητηθούν modules.

Ο ίδιος ο path based finder δεν «γνωρίζει» πώς να εισάγει οτιδήποτε. Αντ’ αυτού, διασχίζει τις επιμέρους καταχωρήσεις διαδρομής, συσχετίζοντας το καθένα με έναν finder καταχώρησης διαδρομής που γνωρίζει πώς να χειριστεί αυτόν τον συγκεκριμένο τύπο διαδρομής.

Το προεπιλεγμένο σύνολο finders καταχώρησης διαδρομής υλοποιεί όλη τη σημασιολογία για την εύρεση των modules στο σύστημα αρχείων, χειριζόμενο ειδικούς τύπους αρχείων όπως πηγαίο κώδικα Python (αρχεία @code{.py}), byte code Python (αρχεία @code{.pyc}) και κοινόχρηστες βιβλιοθήκες (π.χ. αρχεία @code{.so}). Όταν υποστηρίζεται από το module @ref{13b,,zipimport} της τυπικής βιβλιοθήκης, οι προεπιλεγμένοι finders καταχώρησης διαδρομής χειρίζονται επίσης τη φόρτωση όλων αυτών των τύπων αρχείων (εκτός από κοινόχρηστες βιβλιοθήκες) από zipfiles.

Οι καταχωρήσεις διαδρομής δεν χρειάζεται να περιορίζονται σε τοποθεσίες του συστήματος αρχείων. Μπορούν να αναφέρονται σε URLs, σε ερωτήματα βάσεων δεδομένων ή σε οποιαδήποτε άλλη τοποθεσία που μπορεί να εκφραστεί ως συμβολοσειρά.

Ο path based finder παρέχει επιπλέον hooks και πρωτόκολλα ώστε να μπορείτε να επεκτείνετε και να προσαρμόσετε τους τύπους των καταχωρήσεων διαδρομής που μπορούν να αναζητηθούν. Για παράδειγμα, αν θέλατε να υποστηρίξετε καταχωρήσεις διαδρομής ως δικτυακά URLs, θα μπορούσατε να γράψετε ένα hook που υλοποιεί HTTP σημασιολογία για να βρίσκει modules στο διαδίκτυο. Αυτό το hook (ένα callable) θα επέστρεφε έναν @ref{1419,,path entry finder} που υποστηρίζει το πρωτόκολλο που περιγράφεται παρακάτω, και στη συνέχεια θα χρησιμοποιούνταν για να ληφθεί ένας loader για το module από το διαδίκτυο.

Μια προειδοποίηση: αυτή η ενότητα και η προηγούμενη χρησιμοποιούν και οι δύο τον όρο `finder', διακρίνοντάς τους με τους όρους @ref{1418,,meta path finder} και @ref{1419,,path entry finder}. Αυτοί οι δύο τύποι finders είναι πολύ παρόμοιοι, υποστηρίζουν παρόμοια πρωτόκολλα και λειτουργούν με παρόμοιο τρόπο κατά τη διαδικασία εισαγωγής, αλλά είναι σημαντικό να θυμάστε ότι έχουν λεπτές διαφορές. Συγκεκριμένα, οι meta path finders λειτουργούν στην αρχή της διαδικασίας εισαγωγής, όπως καθορίζεται από τη διάσχιση του @ref{10e3,,sys.meta_path}.

Αντίθετα, οι path entry finders είναι κατά κάποιον τρόπο μια λεπτομέρεια υλοποίησης του path based finder και, στην πραγματικότητα, αν ο path based finder αφαιρούνταν από το @ref{10e3,,sys.meta_path}, δεν θα ενεργοποιούνταν καθόλου η σημασιολογία των finders καταχώρησης διαδρομής.

@menu
* Finders καταχώρησης διαδρομής (Path entry finders): Finders καταχώρησης διαδρομής Path entry finders. 
* Πρωτόκολλο path entry finder:: 

@end menu

@node Finders καταχώρησης διαδρομής Path entry finders,Πρωτόκολλο path entry finder,,Finder βασισμένος στη διαδρομή
@anchor{reference/import path-entry-finders}@anchor{264f}
@subsubsection Finders καταχώρησης διαδρομής (Path entry finders)


@geindex sys.path
@geindex sys.path_hooks
@geindex sys.path_importer_cache
@geindex PYTHONPATH

Ο @ref{2643,,path based finder} είναι υπεύθυνος για την εύρεση και φόρτωση Python modules και πακέτων των οποίων η τοποθεσία καθορίζεται με μία συμβολοσειρά @ref{264e,,path entry}. Οι περισσότερες καταχωρήσεις διαδρομής (path entries) δηλώνουν τοποθεσίες στο σύστημα αρχείων, αλλά δεν περιορίζονται απαραίτητα σε αυτό.

Ως ένα meta path finder, ο @ref{2643,,path based finder} υλοποιεί το πρωτόκολλο @ref{c3f,,find_spec()} που περιγράφηκε προηγουμένως, ωστόσο εκθέτει επιπλέον hooks που μπορούν να χρησιμοποιηθούν για να προσαρμόσετε το πώς βρίσκονται και φορτώνονται τα modules από το @ref{2640,,import path}.

Τρεις μεταβλητές χρησιμοποιούνται από τον @ref{2643,,path based finder}: @ref{194,,sys.path}, @ref{13cd,,sys.path_hooks} και @ref{9db,,sys.path_importer_cache}. Επίσης χρησιμοποιούνται τα χαρακτηριστικά @code{__path__} σε αντικείμενα πακέτου. Αυτά παρέχουν επιπλέον τρόπους παραμετροποίησης του μηχανισμού εισαγωγής.

Το @ref{194,,sys.path} περιέχει μια λίστα από συμβολοσειρές που παρέχουν τοποθεσίες αναζήτησης για modules και πακέτα. Αρχικοποιείται από τη μεταβλητή περιβάλλοντος 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} και από διάφορες άλλες προεπιλογές που εξαρτώνται από την εγκατάσταση και την υλοποίηση. Οι εγγραφές στο @code{sys.path} μπορεί να είναι φάκελοι στο σύστημα αρχείων, zip αρχεία και ενδεχομένως άλλες «τοποθεσίες» (βλ. το module @ref{cf,,site}) στις οποίες πρέπει να γίνει αναζήτηση για modules, όπως URLs ή ερωτήματα βάσεων δεδομένων. Στο @code{sys.path} θα πρέπει να υπάρχουν μόνο συμβολοσειρές· όλοι οι άλλοι τύποι δεδομένων αγνοούνται.

Ο @ref{2643,,path based finder} είναι @ref{1418,,meta path finder}, επομένως ο μηχανισμός εισαγωγής ξεκινά την αναζήτηση στο @ref{2640,,import path} καλώντας τη μέθοδο @ref{13ba,,find_spec()} του path based finder, όπως περιγράφηκε προηγουμένως. Όταν δοθεί το όρισμα @code{path} στη @code{find_spec()}, αυτό θα είναι μια λίστα από συμβολοσειρές διαδρομής προς διάσχιση - συνήθως το χαρακτηριστικό @code{__path__} ενός πακέτου για εισαγωγή μέσα σε εκείνο το πακέτο. Αν το όρισμα @code{path} είναι @code{None}, αυτό υποδηλώνει εισαγωγή ανωτέρου επιπέδου και χρησιμοποιείται το @ref{194,,sys.path}.

Ο path based finder επαναλαμβάνεται πάνω σε κάθε εγγραφή στη διαδρομή αναζήτησης και, για καθεμία, αναζητά έναν κατάλληλο @ref{1419,,path entry finder} (@ref{c45,,PathEntryFinder}) για τη συγκεκριμένη καταχώρηση διαδρομής. Επειδή αυτό μπορεί να είναι δαπανηρή λειτουργία (π.χ. μπορεί να υπάρχει overhead από κλήσεις @code{stat()} για αυτή την αναζήτηση), ο path based finder διατηρεί μια προσωρινή μνήμη που αντιστοιχίζει καταχωρήσεις διαδρομής σε path entry finders. Αυτή η προσωρινή μνήμη διατηρείται στο @ref{9db,,sys.path_importer_cache} (παρά το όνομα, αυτή η προσωρινή μνήμη αποθηκεύει αντικείμενα finder και όχι μόνο @ref{263f,,importer} αντικείμενα). Με αυτόν τον τρόπο, η ακριβή αναζήτηση για τον @ref{264e,,path entry} μιας συγκεκριμένης τοποθεσίας path entry finder χρειάζεται να γίνει μόνο μία φορά. Ο κώδικας του χρήστη μπορεί να αφαιρεί εγγραφές από το @code{sys.path_importer_cache}, αναγκάζοντας τον path based finder να εκτελέσει ξανά την αναζήτηση.

Αν η καταχώρηση διαδρομής δεν υπάρχει στην προσωρινή μνήμη, ο path based finder επαναλαμβάνεται πάνω σε κάθε callable στο @ref{13cd,,sys.path_hooks}. Κάθε @ref{2650,,path entry hook} σε αυτή τη λίστα καλείται με ένα μόνο όρισμα: την καταχώρηση διαδρομής που θα αναζητηθεί. Αυτό το callable μπορεί είτε να επιστρέψει έναν @ref{1419,,path entry finder} που μπορεί να χειριστεί την καταχώρηση διαδρομής, είτε να κάνει raise ένα @ref{1bd,,ImportError}. Το @code{ImportError} χρησιμοποιείται από τον path based finder για να δηλώσει ότι το hook δεν μπορεί να βρει path entry finder για το συγκεκριμένο @ref{264e,,path entry}. Η εξαίρεση αγνοείται και η επανάληψη στο @ref{2640,,import path} συνεχίζεται. Το hook θα πρέπει να αναμένει είτε συμβολοσειρά είτε αντικείμενο bytes· η κωδικοποίηση των bytes αντικειμένων επαφίεται στο hook (π.χ. μπορεί να είναι μία κωδικοποίηση του συστήματος αρχείων, UTF-8 ή κάτι άλλο), και αν το hook δεν μπορεί να κάνει αποκωδικοποίηση το όρισμα, θα πρέπει να κάνει raise ένα @code{ImportError}.

Αν η επανάληψη στο @ref{13cd,,sys.path_hooks} ολοκληρωθεί χωρίς να επιστραφεί @ref{1419,,path entry finder}, τότε η μέθοδος @ref{13ba,,find_spec()} του path based finder θα αποθηκεύσει @code{None} στο @ref{9db,,sys.path_importer_cache} (για να δηλώσει ότι δεν υπάρχει finder για αυτή την καταχώρηση διαδρομής) και θα επιστρέψει @code{None}, δηλώνοντας ότι αυτός ο @ref{1418,,meta path finder} δεν μπόρεσε να βρει το module.

Αν `επιστραφεί' ένας @ref{1419,,path entry finder} από κάποιο από τα @ref{2650,,path entry hook} callables στο @ref{13cd,,sys.path_hooks}, τότε χρησιμοποιείται το ακόλουθο πρωτόκολλο για να ζητηθεί από τον finder ένα module spec, το οποίο στη συνέχεια χρησιμοποιείται κατά τη φόρτωση του module.

Ο τρέχων κατάλογος εργασίας – που δηλώνεται με κενή συμβολοσειρά – αντιμετωπίζεται λίγο διαφορετικά από τις άλλες εγγραφές στο @ref{194,,sys.path}. Πρώτον, αν δεν μπορεί να προσδιοριστεί ή αν διαπιστωθεί ότι δεν υπάρχει, δεν αποθηκεύεται τιμή στο @ref{9db,,sys.path_importer_cache}. Δεύτερον, η τιμή για τον τρέχοντα κατάλογο εργασίας αναζητείται εκ νέου για κάθε αναζήτηση module. Τρίτον, η διαδρομή που χρησιμοποιείται για το @code{sys.path_importer_cache} και επιστρέφεται από τη @ref{13ba,,importlib.machinery.PathFinder.find_spec()} θα είναι ο πραγματικός τρέχων κατάλογος εργασίας και όχι η κενή συμβολοσειρά.

@node Πρωτόκολλο path entry finder,,Finders καταχώρησης διαδρομής Path entry finders,Finder βασισμένος στη διαδρομή
@anchor{reference/import path-entry-finder-protocol}@anchor{2651}
@subsubsection Πρωτόκολλο path entry finder


Για να υποστηρίζεται η εισαγωγή των modules και των αρχικοποιημένων πακέτων, καθώς και για τη συνεισφορά portions σε namespace πακέτα, οι path entry finders πρέπει να υλοποιούν τη μέθοδο @ref{c42,,find_spec()}.

Η @ref{c42,,find_spec()} παίρνει δύο ορίσματα: το πλήρως αναγνωρισμένο όνομα του module που εισάγεται και το (προαιρετικό) target module. Η @code{find_spec()} επιστρέφει ένα πλήρως συμπληρωμένο spec για το module. Αυτό το spec θα έχει πάντα ορισμένο το «loader» (με μία εξαίρεση).

Για να δηλώσει στον μηχανισμό εισαγωγής ότι το spec αναπαριστά ένα namespace @ref{2639,,portion}, ο path entry finder ορίζει το @code{submodule_search_locations} σε μια λίστα που περιέχει το portion.


Άλλαξε στην έκδοση 3.4: Η @ref{c42,,find_spec()} αντικατέστησε τις @code{find_loader()} και @code{find_module()}, οι οποίες έχουν πλέον χαρακτηριστεί ως απαρχαιωμένες, αλλά θα χρησιμοποιηθούν αν δεν ορίζεται η @code{find_spec()}.

Παλαιότεροι path entry finders μπορεί να υλοποιούν μία από αυτές τις δύο απαρχαιωμένες μεθόδους αντί για την @code{find_spec()}. Οι μέθοδοι αυτές εξακολουθούν να γίνονται δεκτές για λόγους συμβατότητας προς τα πίσω. Ωστόσο, αν ο path entry finder υλοποιεί @code{find_spec()}, οι παλιές μέθοδοι αγνοούνται.

Η @code{find_loader()} παίρνει ένα όρισμα, το πλήρως αναγνωρισμένο όνομα του module που εισάγεται. Η @code{find_loader()} επιστρέφει ένα tuple όπου το πρώτο στοιχείο είναι ο loader και το δεύτερο στοιχείο είναι ένα namespace @ref{2639,,portion}.

Για συμβατότητα προς τα πίσω με άλλες υλοποιήσεις του πρωτοκόλλου εισαγωγής, πολλοί path entry finders υποστηρίζουν επίσης την ίδια παραδοσιακή μέθοδο @code{find_module()} που υποστηρίζουν και οι meta path finders. Ωστόσο, οι μέθοδοι @code{find_module()} των path entry finders δεν καλούνται ποτέ με όρισμα @code{path} (αναμένεται να έχουν καταγράψει την κατάλληλη πληροφορία διαδρομής από την αρχική κλήση του path hook).

Η μέθοδος @code{find_module()} στους path entry finders έχει χαρακτηριστεί ως απαρχαιωμένη, καθώς δεν επιτρέπει στον path entry finder να συνεισφέρει portions σε namespace πακέτα. Αν ένας path entry finder διαθέτει και @code{find_loader()} και @code{find_module()}, το σύστημα εισαγωγής θα καλεί πάντα την @code{find_loader()} αντί για την @code{find_module()}.



Άλλαξε στην έκδοση 3.10: Οι κλήσεις των @code{find_module()} και @code{find_loader()} από το σύστημα εισαγωγής θα κάνουν raise μία @ref{907,,ImportWarning}.



Άλλαξε στην έκδοση 3.12: Οι @code{find_module()} και @code{find_loader()} έχουν αφαιρεθεί.


@node Αντικατάσταση του τυπικού συστήματος εισαγωγής,Σχετικές εισαγωγές σε πακέτα,Finder βασισμένος στη διαδρομή,Το σύστημα εισαγωγής
@anchor{reference/import replacing-the-standard-import-system}@anchor{2652}
@subsection Αντικατάσταση του τυπικού συστήματος εισαγωγής


Ο πιο αξιόπιστος μηχανισμός για την αντικατάσταση ολόκληρου του συστήματος εισαγωγής είναι η διαγραφή των προεπιλεγμένων περιεχομένων του @ref{10e3,,sys.meta_path}, αντικαθιστώντας τα πλήρως με ένα προσαρμοσμένο hook μετά-διαδρομής.

If it is acceptable to only alter the behaviour of import statements
without affecting other APIs that access the import system, then replacing
the builtin @ref{ca6,,__import__()} function may be sufficient.

Για να αποτρέψετε επιλεκτικά την εισαγωγή ορισμένων modules από ένα hook νωρίς στη μεταδιαδρομή (αντί να απενεργοποιήσετε πλήρως το τυπικό σύστημα εισαγωγής), αρκεί να κάνετε raise το @ref{1be,,ModuleNotFoundError} απευθείας από τη @ref{c3f,,find_spec()} αντί να επιστρέψετε @code{None}. Το @code{None} δηλώνει ότι η αναζήτηση στη μεταδιαδρομή πρέπει να συνεχιστεί, ενώ η υποβολή αιτήματος εξαίρεσης την τερματίζει άμεσα.

@node Σχετικές εισαγωγές σε πακέτα,Ειδικές περιπτώσεις για το __main__,Αντικατάσταση του τυπικού συστήματος εισαγωγής,Το σύστημα εισαγωγής
@anchor{reference/import package-relative-imports}@anchor{2653}@anchor{reference/import relativeimports}@anchor{2654}
@subsection Σχετικές εισαγωγές σε πακέτα


Οι σχετικές εισαγωγές χρησιμοποιούν τελείες στην αρχή. Μια και μόνο τελεία στην αρχή δηλώνει σχετική εισαγωγή που ξεκινά από το τρέχον πακέτο. Δύο ή περισσότερες τελείες δηλώνουν σχετική εισαγωγή προς το/τα γονικό/ά του τρέχοντος πακέτου, ένα επίπεδο ανά τελεία μετά την πρώτη. Για παράδειγμα, με την ακόλουθη διάταξη πακέτου:

@example
package/
    __init__.py
    subpackage1/
        __init__.py
        moduleX.py
        moduleY.py
    subpackage2/
        __init__.py
        moduleZ.py
    moduleA.py
@end example

Είτε στο @code{subpackage1/moduleX.py} είτε στο @code{subpackage1/__init__.py}, τα παρακάτω είναι έγκυρες σχετικές εισαγωγές:

@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

Οι απόλυτες εισαγωγές μπορούν να χρησιμοποιούν είτε τη σύνταξη @code{import <>} είτε τη @code{from <> import <>}, αλλά οι σχετικές εισαγωγές μπορούν να χρησιμοποιούν μόνο τη δεύτερη μορφή· ο λόγος είναι ότι:

@example
import XXX.YYY.ZZZ
@end example

θα πρέπει να εκθέτει το @code{XXX.YYY.ZZZ} ως χρησιμοποιήσιμη έκφραση, αλλά το .moduleY δεν είναι έγκυρη έκφραση.

@node Ειδικές περιπτώσεις για το __main__,Αναφορές,Σχετικές εισαγωγές σε πακέτα,Το σύστημα εισαγωγής
@anchor{reference/import import-dunder-main}@anchor{2655}@anchor{reference/import special-considerations-for-main}@anchor{2656}
@subsection Ειδικές περιπτώσεις για το __main__


Το module @ref{1,,__main__} είναι μια ειδική περίπτωση σε σχέση με το σύστημα εισαγωγής της Python. Όπως σημειώνεται @ref{2648,,αλλού}, το @code{__main__} αρχικοποιείται απευθείας κατά την εκκίνηση του διερμηνέα, όπως και τα @ref{e2,,sys} και @ref{13,,builtins}. Ωστόσο, σε αντίθεση με αυτά τα δύο, δεν χαρακτηρίζεται αυστηρά ως ενσωματωμένο module. Αυτό συμβαίνει επειδή ο τρόπος με τον οποίο αρχικοποιείται το @code{__main__} εξαρτάται από τις σημαίες και άλλες επιλογές με τις οποίες καλείται ο διερμηνέας.

@menu
* __main__.__spec__: __main__ __spec__. 

@end menu

@node __main__ __spec__,,,Ειδικές περιπτώσεις για το __main__
@anchor{reference/import id5}@anchor{2657}@anchor{reference/import main-spec}@anchor{2649}
@subsubsection __main__.__spec__


Ανάλογα με το πώς αρχικοποιείται το @ref{1,,__main__}, το @code{__main__.__spec__} ορίζεται κατάλληλα ή σε @code{None}.

Όταν η Python ξεκινά με την επιλογή @ref{4ca,,-m}, το @code{__spec__} ορίζεται στο module spec του αντίστοιχου module ή πακέτου. Το @code{__spec__} συμπληρώνεται επίσης όταν το module @code{__main__} φορτώνεται ως μέρος της εκτέλεσης ενός καταλόγου, zipfile ή άλλης εγγραφής του @ref{194,,sys.path}.

Στις @ref{230a,,υπόλοιπες περιπτώσεις} το @code{__main__.__spec__} ορίζεται σε @code{None}, καθώς ο κώδικας που χρησιμοποιείται για να γεμίσει το @ref{1,,__main__} δεν αντιστοιχεί άμεσα σε εισαγόμενο module:


@itemize -

@item 
διαδραστική προτροπή

@item 
επιλογή @ref{445,,-c}

@item 
εκτέλεση από stdin

@item 
εκτέλεση απευθείας από το αρχείο πηγαίου κώδικα ή bytecode
@end itemize

Σημειώστε ότι στην τελευταία περίπτωση το @code{__main__.__spec__} είναι πάντα @code{None}, `ακόμη κι αν' το αρχείο θα μπορούσε τεχνικά να εισαχθεί απευθείας ως module. Χρησιμοποιήστε το switch @ref{4ca,,-m} αν χρειάζεστε έγκυρα module μεταδεδομένων στο @ref{1,,__main__}.

Σημειώστε επίσης ότι ακόμη κι όταν το @code{__main__} αντιστοιχεί σε εισαγόμενα module και το @code{__main__.__spec__} ορίζεται ανάλογα, εξακολουθούν να θεωρούνται `διακριτά' modules. Αυτό οφείλεται στο ότι μπλοκ κώδικα που προστατεύονται από ελέγχους @code{if __name__ == "__main__":} εκτελούνται μόνο όταν το module χρησιμοποιείται για να γεμίσει το namespace του @code{__main__}, και όχι κατά την κανονική εισαγωγή.

@node Αναφορές,,Ειδικές περιπτώσεις για το __main__,Το σύστημα εισαγωγής
@anchor{reference/import references}@anchor{2658}
@subsection Αναφορές


Ο μηχανισμός εισαγωγής έχει εξελιχθεί σημαντικά από τα πρώτα χρόνια της Python. Η αρχική προδιαγραφή για πακέτα@footnote{https://www.python.org/doc/essays/packages/} είναι ακόμη διαθέσιμη προς ανάγνωση, αν και ορισμένες λεπτομέρειες έχουν αλλάξει από τότε που γράφτηκε αυτό το κείμενο.

Η αρχική προδιαγραφή για το @ref{10e3,,sys.meta_path} ήταν το 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}, με μεταγενέστερη επέκταση στο 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}.

Το 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} εισήγαγε τα @ref{52e,,namespace πακέτα} στην Python 3.3. Το 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} εισήγαγε επίσης το πρωτόκολλο @code{find_loader()} ως εναλλακτική της @code{find_module()}.

Το 
@geindex Python Enhancement Proposals; PEP 366
PEP 366@footnote{https://peps.python.org/pep-0366/} περιγράφει την προσθήκη του χαρακτηριστικού @code{__package__} για ρητές σχετικές εισαγωγές σε κύρια modules.

Το 
@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/} εισήγαγε απόλυτες και ρητές σχετικές εισαγωγές και αρχικά πρότεινε το @code{__name__} για τη σημασιολογία που το 
@geindex Python Enhancement Proposals; PEP 366
PEP 366@footnote{https://peps.python.org/pep-0366/} τελικά όρισε για το @code{__package__}.

Το 
@geindex Python Enhancement Proposals; PEP 338
PEP 338@footnote{https://peps.python.org/pep-0338/} ορίζει την εκτέλεση modules ως scripts.

Το 
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/} προσθέτει την ενθυλάκωση της κατάστασης εισαγωγής ανά module σε spec αντικείμενα. Επίσης μεταφέρει το μεγαλύτερο μέρος των τυποποιημένων ευθυνών των loaders πίσω στον μηχανισμό εισαγωγής. Αυτές οι αλλαγές επιτρέπουν την απόσυρση αρκετών APIs στο σύστημα εισαγωγής και επίσης την προσθήκη νέων μεθόδων σε finders και loaders.

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Expressions,Απλές εντολές,Το σύστημα εισαγωγής,Εγχειρίδιο Αναφοράς της Γλώσσας Python
@anchor{reference/expressions doc}@anchor{2659}@anchor{reference/expressions expressions}@anchor{2518}@anchor{reference/expressions id1}@anchor{265a}@anchor{reference/expressions translation-repo}@anchor{265b}
@section Expressions


@geindex expression
@geindex BNF

This chapter explains the meaning of the elements of expressions in Python.

`Syntax Notes:' In this and the following chapters,
@ref{2475,,grammar notation} will be used to describe syntax,
not lexical analysis.

When (one alternative of) a syntax rule has the form:

@example
@anchor{reference/expressions grammar-token-python-grammar-name}@anchor{265c}name: othername
@end example

and no semantics are given, the semantics of this form of @code{name} are the same
as for @code{othername}.

@menu
* Arithmetic conversions:: 
* Atoms:: 
* Primaries:: 
* Await expression:: 
* The power operator:: 
* Unary arithmetic and bitwise operations:: 
* Binary arithmetic operations:: 
* Shifting operations:: 
* Binary bitwise operations:: 
* Comparisons:: 
* Boolean operations:: 
* Assignment expressions: Assignment expressions<2>. 
* Conditional expressions:: 
* Lambdas:: 
* Expression lists:: 
* Evaluation order:: 
* Operator precedence:: 

@end menu

@node Arithmetic conversions,Atoms,,Expressions
@anchor{reference/expressions arithmetic-conversions}@anchor{265d}@anchor{reference/expressions conversions}@anchor{265e}
@subsection Arithmetic conversions


@geindex arithmetic;conversion

When a description of an arithmetic operator below uses the phrase «the numeric
arguments are converted to a common real type», this means that the operator
implementation for built-in numeric types works as described in the
@ref{265f,,Numeric Types} section of the standard
library documentation.

Some additional rules apply for certain operators and non-numeric operands
(for example, a string as a left argument to the @code{%} operator).
Extensions must define their own conversion behavior.

@node Atoms,Primaries,Arithmetic conversions,Expressions
@anchor{reference/expressions atoms}@anchor{2660}@anchor{reference/expressions id2}@anchor{2661}
@subsection Atoms


@geindex atom

Atoms are the most basic elements of expressions.
The simplest atoms are @ref{2491,,names} or literals.
Forms enclosed in parentheses, brackets or braces are also categorized
syntactically as atoms.

Formally, the syntax for atoms is:

@example
@anchor{reference/expressions grammar-token-python-grammar-atom}@anchor{2662}atom:
   | 'True'
   | 'False'
   | 'None'
   | '...'
   | @ref{24b2,,identifier}
   | @ref{2663,,literal}
   | @ref{2664,,enclosure}
@anchor{reference/expressions grammar-token-python-grammar-enclosure}@anchor{2664}enclosure:
   | @ref{2665,,parenth_form}
   | @ref{2666,,list_display}
   | @ref{2667,,dict_display}
   | @ref{2668,,set_display}
   | @ref{2669,,generator_expression}
   | @ref{266a,,yield_atom}
@end example

@menu
* Built-in constants:: 
* Identifiers (Names): Identifiers Names. 
* Literals:: 
* Parenthesized forms:: 
* Displays for lists@comma{} sets and dictionaries: Displays for lists sets and dictionaries. 
* List displays:: 
* Set displays:: 
* Dictionary displays:: 
* Generator expressions:: 
* Yield expressions:: 

@end menu

@node Built-in constants,Identifiers Names,,Atoms
@anchor{reference/expressions atom-singletons}@anchor{266b}@anchor{reference/expressions built-in-constants}@anchor{266c}
@subsubsection Built-in constants


The keywords @code{True}, @code{False}, and @code{None} name
@ref{266d,,built-in constants}.
The token @code{...} names the @ref{2519,,Ellipsis} constant.

Evaluation of these atoms yields the corresponding value.

@cartouche
@quotation Σημείωση 
Several more built-in constants are available as global variables,
but only the ones mentioned here are @ref{247a,,keywords}.
In particular, these names cannot be reassigned or used as attributes:

@example
>>> False = 123
  File "<input>", line 1
   False = 123
   ^^^^^
SyntaxError: cannot assign to False
@end example
@end quotation
@end cartouche

@node Identifiers Names,Literals,Built-in constants,Atoms
@anchor{reference/expressions atom-identifiers}@anchor{24b7}@anchor{reference/expressions identifiers-names}@anchor{266e}
@subsubsection Identifiers (Names)


@geindex name
@geindex identifier

An identifier occurring as an atom is a name.  See section @ref{2491,,Ονόματα (αναγνωριστικά και λέξεις-κλειδιά)}
for lexical definition and section @ref{2537,,Ονομασία και σύνδεση} for documentation of naming and
binding.

@geindex exception;NameError

When the name is bound to an object, evaluation of the atom yields that object.
When a name is not bound, an attempt to evaluate it raises a @ref{665,,NameError}
exception.

@geindex name;mangling
@geindex private;names
@anchor{reference/expressions private-name-mangling}@anchor{2293}
@menu
* Private name mangling:: 

@end menu

@node Private name mangling,,,Identifiers Names
@anchor{reference/expressions id3}@anchor{266f}
@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 Δείτε επίσης


The @ref{167c,,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{140e,,__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 Literals,Parenthesized forms,Identifiers Names,Atoms
@anchor{reference/expressions atom-literals}@anchor{2670}@anchor{reference/expressions literals}@anchor{2671}
@subsubsection Literals


@geindex literal

A `literal' is a textual representation of a value.
Python supports numeric, string and bytes literals.
@ref{43a,,Format strings} and @ref{1a50,,template strings}
are treated as string literals.

Numeric literals consist of a single @ref{24f7,,NUMBER}
token, which names an integer, floating-point number, or an imaginary number.
See the @ref{2492,,Αριθμητικά λεκτικά} section in Lexical analysis documentation for details.

String and bytes literals may consist of several tokens.
See section @ref{24d1,,String literal concatenation} for details.

Note that negative and complex numbers, like @code{-3} or @code{3+4.2j},
are syntactically not literals, but @ref{2672,,unary} or
@ref{2673,,binary} arithmetic operations involving the @code{-} or @code{+}
operator.

Evaluation of a literal yields an object of the given type
(@ref{326,,int}, @ref{327,,float}, @ref{328,,complex}, @ref{1df,,str},
@ref{1c7,,bytes}, or @ref{415,,Template}) with the given value.
The value may be approximated in the case of floating-point
and imaginary literals.

The formal grammar for literals is:

@example
@anchor{reference/expressions grammar-token-python-grammar-literal}@anchor{2663}literal: @ref{2674,,strings} | @ref{24f7,,NUMBER}
@end example

@geindex immutable;data;type
@geindex immutable;object

@menu
* Literals and object identity:: 
* String literal concatenation:: 

@end menu

@node Literals and object identity,String literal concatenation,,Literals
@anchor{reference/expressions literals-and-object-identity}@anchor{2675}
@subsubsection Literals and object identity


All literals correspond to immutable data types, and hence the object’s identity
is less important than its value.  Multiple evaluations of literals with the
same value (either the same occurrence in the program text or a different
occurrence) may obtain the same object or a different object with the same
value.

@cartouche
@quotation CPython implementation detail 
For example, in CPython, `small' integers with the same value evaluate
to the same object:

@example
>>> x = 7
>>> y = 7
>>> x is y
True
@end example

However, large integers evaluate to different objects:

@example
>>> x = 123456789
>>> y = 123456789
>>> x is y
False
@end example

This behavior may change in future versions of CPython.
In particular, the boundary between «small» and «large» integers has
already changed in the past.

CPython will emit a @ref{44a,,SyntaxWarning} when you compare literals
using @code{is}:

@example
>>> x = 7
>>> x is 7
<input>:1: SyntaxWarning: "is" with 'int' literal. Did you mean "=="?
True
@end example

See @ref{2676,,Πότε μπορώ να βασιστώ σε δοκιμές ταυτότητας με τον τελεστή is;} for more information.
@end quotation
@end cartouche

@ref{1a50,,Template strings} are immutable but may reference mutable
objects as @ref{416,,Interpolation} values.
For the purposes of this section, two t-strings have the «same value» if
both their structure and the `identity' of the values match.

`Λεπτομέρεια υλοποίησης CPython:' Currently, each evaluation of a template string results in
a different object.

@node String literal concatenation,,Literals and object identity,Literals
@anchor{reference/expressions string-concatenation}@anchor{24d1}@anchor{reference/expressions string-literal-concatenation}@anchor{2677}
@subsubsection String literal concatenation


Multiple adjacent string or bytes literals, possibly
using different quoting conventions, are allowed, and their meaning is the same
as their concatenation:

@example
>>> "hello" 'world'
"helloworld"
@end example

This feature is defined at the syntactical level, so it only works with literals.
To concatenate string expressions at run time, the “+” operator may be used:

@example
>>> greeting = "Hello"
>>> space = " "
>>> name = "Blaise"
>>> print(greeting + space + name)   # not: print(greeting space name)
Hello Blaise
@end example

Literal concatenation can freely mix raw strings, triple-quoted strings,
and formatted string literals.
For example:

@example
>>> "Hello" r', ' f"@{name@}!"
"Hello, Blaise!"
@end example

This feature can be used to reduce the number of backslashes
needed, to split long strings conveniently across long lines, or even to add
comments to parts of strings. For example:

@example
re.compile("[A-Za-z_]"       # letter or underscore
           "[A-Za-z0-9_]*"   # letter, digit or underscore
          )
@end example

However, bytes literals may only be combined with other byte literals;
not with string literals of any kind.
Also, template string literals may only be combined with other template
string literals:

@example
>>> t"Hello" t"@{name@}!"
Template(strings=('Hello', '!'), interpolations=(...))
@end example

Formally:

@example
@anchor{reference/expressions grammar-token-python-grammar-strings}@anchor{2674}strings: (@ref{24c2,,STRING} | @ref{24e5,,fstring})+ | @ref{24f5,,tstring}+
@end example

@node Parenthesized forms,Displays for lists sets and dictionaries,Literals,Atoms
@anchor{reference/expressions parenthesized}@anchor{2678}@anchor{reference/expressions parenthesized-forms}@anchor{2679}
@subsubsection Parenthesized forms


@geindex parenthesized form
@geindex () (parentheses);tuple display

A parenthesized form is an optional expression list enclosed in parentheses:

@example
@anchor{reference/expressions grammar-token-python-grammar-parenth_form}@anchor{2665}parenth_form: "(" [@ref{267a,,starred_expression}] ")"
@end example

A parenthesized expression list yields whatever that expression list yields: if
the list contains at least one comma, it yields a tuple; otherwise, it yields
the single expression that makes up the expression list.

@geindex empty;tuple

An empty pair of parentheses yields an empty tuple object.  Since tuples are
immutable, the same rules as for literals apply (i.e., two occurrences of the empty
tuple may or may not yield the same object).

@geindex comma
@geindex @comma{} (comma)

Note that tuples are not formed by the parentheses, but rather by use of the
comma.  The exception is the empty tuple, for which parentheses `are'
required — allowing unparenthesized «nothing» in expressions would cause
ambiguities and allow common typos to pass uncaught.

@node Displays for lists sets and dictionaries,List displays,Parenthesized forms,Atoms
@anchor{reference/expressions comprehensions}@anchor{9ce}@anchor{reference/expressions displays-for-lists-sets-and-dictionaries}@anchor{267b}
@subsubsection Displays for lists, sets and dictionaries


@geindex comprehensions

For constructing a list, a set or a dictionary Python provides special syntax
called «displays», each of them in two flavors:


@itemize *

@item 
either the container contents are listed explicitly, or

@item 
they are computed via a set of looping and filtering instructions, called a
`comprehension'.
@end itemize

@geindex for;in comprehensions
@geindex if;in comprehensions
@geindex async for;in comprehensions

Common syntax elements for comprehensions are:

@example
@anchor{reference/expressions grammar-token-python-grammar-comprehension}@anchor{267c}comprehension: @ref{267d,,flexible_expression} @ref{267e,,comp_for}
@anchor{reference/expressions grammar-token-python-grammar-comp_for}@anchor{267e}comp_for:      ["async"] "for" @ref{267f,,target_list} "in" @ref{2680,,or_test} [@ref{2681,,comp_iter}]
@anchor{reference/expressions grammar-token-python-grammar-comp_iter}@anchor{2681}comp_iter:     @ref{267e,,comp_for} | @ref{2682,,comp_if}
@anchor{reference/expressions grammar-token-python-grammar-comp_if}@anchor{2682}comp_if:       "if" @ref{2680,,or_test} [@ref{2681,,comp_iter}]
@end example

The comprehension consists of a single expression followed by at least one
@code{for} clause and zero or more @code{for} or @code{if}
clauses.  In this case, the elements of the new container are those that would
be produced by considering each of the @code{for} or @code{if}
clauses a block, nesting from left to right, and evaluating the expression to
produce an element each time the innermost block is reached.  If the expression
is starred, the result will instead be unpacked to produce zero or more
elements.

However, aside from the iterable expression in the leftmost @code{for} clause,
the comprehension is executed in a separate implicitly nested scope. This ensures
that names assigned to in the target list don’t «leak» into the enclosing scope.

The iterable expression in the leftmost @code{for} clause is evaluated
directly in the enclosing scope and then passed as an argument to the implicitly
nested scope. Subsequent @code{for} clauses and any filter condition in the
leftmost @code{for} clause cannot be evaluated in the enclosing scope as
they may depend on the values obtained from the leftmost iterable. For example:
@code{[x*y for x in range(10) for y in range(x, x+10)]}.

To ensure the comprehension always results in a container of the appropriate
type, @code{yield} and @code{yield from} expressions are prohibited in the implicitly
nested scope.

@geindex await;in comprehensions

Since Python 3.6, in an @ref{9cf,,async def} function, an @code{async for}
clause may be used to iterate over a @ref{6cd,,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{432,,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/}.


Added in version 3.6: Asynchronous comprehensions were introduced.



Άλλαξε στην έκδοση 3.8: @code{yield} and @code{yield from} prohibited in the implicitly nested scope.



Άλλαξε στην έκδοση 3.11: Asynchronous comprehensions are now allowed inside comprehensions in
asynchronous functions. Outer comprehensions implicitly become
asynchronous.



Άλλαξε στην έκδοση 3.15: Unpacking with the @code{*} operator is now allowed in the expression.


@node List displays,Set displays,Displays for lists sets and dictionaries,Atoms
@anchor{reference/expressions list-displays}@anchor{2683}@anchor{reference/expressions lists}@anchor{2684}
@subsubsection List displays


@geindex list;display
@geindex list;comprehensions
@geindex empty;list
@geindex object;list
@geindex [] (square brackets);list expression
@geindex @comma{} (comma);expression list

A list display is a possibly empty series of expressions enclosed in square
brackets:

@example
@anchor{reference/expressions grammar-token-python-grammar-list_display}@anchor{2666}list_display: "[" [@ref{2685,,flexible_expression_list} | @ref{267c,,comprehension}] "]"
@end example

A list display yields a new list object, the contents being specified by either
a list of expressions or a comprehension.  When a comma-separated list of
expressions is supplied, its elements are evaluated from left to right and
placed into the list object in that order.  When a comprehension is supplied,
the list is constructed from the elements resulting from the comprehension.

@node Set displays,Dictionary displays,List displays,Atoms
@anchor{reference/expressions set}@anchor{2686}@anchor{reference/expressions set-displays}@anchor{2687}
@subsubsection Set displays


@geindex set;display
@geindex set;comprehensions
@geindex object;set
@geindex @{@} (curly brackets);set expression
@geindex @comma{} (comma);expression list

A set display is denoted by curly braces and distinguishable from dictionary
displays by the lack of colons separating keys and values:

@example
@anchor{reference/expressions grammar-token-python-grammar-set_display}@anchor{2668}set_display: "@{" (@ref{2685,,flexible_expression_list} | @ref{267c,,comprehension}) "@}"
@end example

A set display yields a new mutable set object, the contents being specified by
either a sequence of expressions or a comprehension.  When a comma-separated
list of expressions is supplied, its elements are evaluated from left to right
and added to the set object.  When a comprehension is supplied, the set is
constructed from the elements resulting from the comprehension.

An empty set cannot be constructed with @code{@{@}}; this literal constructs an empty
dictionary.

@node Dictionary displays,Generator expressions,Set displays,Atoms
@anchor{reference/expressions dict}@anchor{1138}@anchor{reference/expressions dictionary-displays}@anchor{2688}
@subsubsection Dictionary displays


@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

A dictionary display is a possibly empty series of dict items (key/value pairs)
enclosed in curly braces:

@example
@anchor{reference/expressions grammar-token-python-grammar-dict_display}@anchor{2667}dict_display:       "@{" [@ref{2689,,dict_item_list} | @ref{268a,,dict_comprehension}] "@}"
@anchor{reference/expressions grammar-token-python-grammar-dict_item_list}@anchor{2689}dict_item_list:     @ref{268b,,dict_item} ("," @ref{268b,,dict_item})* [","]
@anchor{reference/expressions grammar-token-python-grammar-dict_comprehension}@anchor{268a}dict_comprehension: @ref{268b,,dict_item} @ref{267e,,comp_for}
@anchor{reference/expressions grammar-token-python-grammar-dict_item}@anchor{268b}dict_item:          @ref{42a,,expression} ":" @ref{42a,,expression} | "**" @ref{24f3,,or_expr}
@end example

A dictionary display yields a new dictionary object.

If a comma-separated sequence of dict items is given, they are evaluated
from left to right to define the entries of the dictionary: each key object is
used as a key into the dictionary to store the corresponding value.  This means
that you can specify the same key multiple times in the dict item list, and the
final dictionary’s value for that key will be the last one given.

@geindex unpacking;dictionary
@geindex **;in dictionary displays

A double asterisk @code{**} denotes `dictionary unpacking'.
Its operand must be a @ref{1564,,mapping}.  Each mapping item is added
to the new dictionary.  Later values replace values already set by
earlier dict items and earlier dictionary unpackings.


Added in version 3.5: Unpacking into dictionary displays, originally proposed by 
@geindex Python Enhancement Proposals; PEP 448
PEP 448@footnote{https://peps.python.org/pep-0448/}.


A dict comprehension may take one of two forms:


@itemize -

@item 
The first form  uses two expressions separated with a colon followed by the
usual «for» and «if» clauses.  When the comprehension is run, the resulting
key and value elements are inserted in the new dictionary in the order they
are produced.

@item 
The second form uses a single expression prefixed by the @code{**} dictionary
unpacking operator followed by the usual «for» and «if» clauses.  When the
comprehension is evaluated, the expression is evaluated and then unpacked,
inserting zero or more key/value pairs into the new dictionary.
@end itemize

Both forms of dictionary comprehension retain the property that if the same key
is specified multiple times, the associated value in the resulting dictionary
will be the last one specified.

@geindex immutable;object
@geindex hashable

Restrictions on the types of the key values are listed earlier in section
@ref{2520,,Η τυπική ιεραρχία τύπου}.  (To summarize, the key type should be @ref{183,,hashable}, which excludes
all mutable objects.)  Clashes between duplicate keys are not detected; the last
value (textually rightmost in the display) stored for a given key value
prevails.


Άλλαξε στην έκδοση 3.8: Prior to Python 3.8, in dict comprehensions, the evaluation order of key
and value was not well-defined.  In CPython, the value was evaluated before
the key.  Starting with 3.8, the key is evaluated before the value, as
proposed by 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/}.



Άλλαξε στην έκδοση 3.15: Unpacking with the @code{**} operator is now allowed in dictionary comprehensions.


@node Generator expressions,Yield expressions,Dictionary displays,Atoms
@anchor{reference/expressions generator-expressions}@anchor{268c}@anchor{reference/expressions genexpr}@anchor{268d}
@subsubsection Generator expressions


@geindex generator;expression
@geindex object;generator
@geindex () (parentheses);generator expression

A generator expression is a compact generator notation in parentheses:

@example
@anchor{reference/expressions grammar-token-python-grammar-generator_expression}@anchor{2669}generator_expression: "(" @ref{267d,,flexible_expression} @ref{267e,,comp_for} ")"
@end example

A generator expression yields a new generator object.  Its syntax is the same as
for comprehensions, except that it is enclosed in parentheses instead of
brackets or curly braces.

Variables used in the generator expression are evaluated lazily when the
@ref{229e,,__next__()} method is called for the generator object (in the same
fashion as normal generators).  However, the iterable expression in the
leftmost @code{for} clause is immediately evaluated, and the
@ref{6ce,,iterator} is immediately created for that iterable, so that an error
produced while creating the iterator will be emitted at the point where the generator expression
is defined, rather than at the point where the first value is retrieved.
Subsequent @code{for} clauses and any filter condition in the leftmost
@code{for} clause cannot be evaluated in the enclosing scope as they may
depend on the values obtained from the leftmost iterable. For example:
@code{(x*y for x in range(10) for y in range(x, x+10))}.

The parentheses can be omitted on calls with only one argument.  See section
@ref{1136,,Calls} for details.

To avoid interfering with the expected operation of the generator expression
itself, @code{yield} and @code{yield from} expressions are prohibited in the
implicitly defined generator.

If a generator expression contains either @code{async for}
clauses or @ref{432,,await} expressions it is called an
`asynchronous generator expression'.  An asynchronous generator
expression returns a new asynchronous generator object,
which is an asynchronous iterator (see @ref{1130,,Ασύγχρονοι Iterators}).


Added in version 3.6: Asynchronous generator expressions were introduced.



Άλλαξε στην έκδοση 3.7: Prior to Python 3.7, asynchronous generator expressions could
only appear in @ref{9cf,,async def} coroutines.  Starting
with 3.7, any function can use asynchronous generator expressions.



Άλλαξε στην έκδοση 3.8: @code{yield} and @code{yield from} prohibited in the implicitly nested scope.


@node Yield expressions,,Generator expressions,Atoms
@anchor{reference/expressions yield-expressions}@anchor{268e}@anchor{reference/expressions yieldexpr}@anchor{268f}
@subsubsection Yield expressions


@geindex keyword;yield
@geindex keyword;from
@geindex yield;expression
@geindex generator;function

@example
@anchor{reference/expressions grammar-token-python-grammar-yield_atom}@anchor{266a}yield_atom:       "(" @ref{24f4,,yield_expression} ")"
@anchor{reference/expressions grammar-token-python-grammar-yield_from}@anchor{2690}yield_from:       "yield" "from" @ref{42a,,expression}
@anchor{reference/expressions grammar-token-python-grammar-yield_expression}@anchor{24f4}yield_expression: "yield" @ref{2691,,yield_list} | @ref{2690,,yield_from}
@end example

The yield expression is used when defining a @ref{1409,,generator} function
or an @ref{2692,,asynchronous generator} function and
thus can only be used in the body of a function definition.  Using a yield
expression in a function’s body causes that function to be a generator function,
and using it in an @ref{9cf,,async def} function’s body causes that
coroutine function to be an asynchronous generator function. For example:

@example
def gen():  # defines a generator function
    yield 123

async def agen(): # defines an asynchronous generator function
    yield 123
@end example

Due to their side effects on the containing scope, @code{yield} expressions
are not permitted as part of the implicitly defined scopes used to
implement comprehensions and generator expressions.


Άλλαξε στην έκδοση 3.8: Yield expressions prohibited in the implicitly nested scopes used to
implement comprehensions and generator expressions.


Generator functions are described below, while asynchronous generator
functions are described separately in section
@ref{2693,,Asynchronous generator functions}.

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{2691,,yield_list}
to the generator’s caller,
or @code{None} if @code{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{229e,,__next__()} is used
(typically via either a @ref{321,,for} or the @ref{bb5,,next()} builtin) then the
result is @ref{a65,,None}.  Otherwise, if @ref{260f,,send()} is used, then
the result will be the value passed in to that method.

@geindex coroutine

All of this makes generator functions quite similar to coroutines; they yield
multiple times, they have more than one entry point and their execution can be
suspended.  The only difference is that a generator function cannot control
where the execution should continue after it yields; the control is always
transferred to the generator’s caller.

Yield expressions are allowed anywhere in a @ref{ad6,,try} construct.  If the
generator is not resumed before it is
finalized (by reaching a zero reference count or by being garbage collected),
the generator-iterator’s @ref{199e,,close()} method will be called,
allowing any pending @ref{44c,,finally} clauses to execute.

@geindex from;yield from expression

When @code{yield from <expr>} is used, the supplied expression must be an
iterable. The values produced by iterating that iterable are passed directly
to the caller of the current generator’s methods. Any values passed in with
@ref{260f,,send()} and any exceptions passed in with
@ref{905,,throw()} are passed to the underlying iterator if it has the
appropriate methods.  If this is not the case, then @code{send()}
will raise @ref{1a9,,AttributeError} or @ref{291,,TypeError}, while
@code{throw()} will just raise the passed in exception immediately.

When the underlying iterator is complete, the @ref{260c,,value}
attribute of the raised @ref{fba,,StopIteration} instance becomes the value of
the yield expression. It can be either set explicitly when raising
@code{StopIteration}, or automatically when the subiterator is a generator
(by returning a value from the subgenerator).


Άλλαξε στην έκδοση 3.3: Added @code{yield from <expr>} to delegate control flow to a subiterator.


The parentheses may be omitted when the yield expression is the sole expression
on the right hand side of an assignment statement.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 255

@item PEP 255@footnote{https://peps.python.org/pep-0255/} - Simple Generators

The proposal for adding generators and the @ref{d93,,yield} statement to Python.

@geindex Python Enhancement Proposals; PEP 342

@item PEP 342@footnote{https://peps.python.org/pep-0342/} - Coroutines via Enhanced Generators

The proposal to enhance the API and syntax of generators, making them
usable as simple coroutines.

@geindex Python Enhancement Proposals; PEP 380

@item PEP 380@footnote{https://peps.python.org/pep-0380/} - Syntax for Delegating to a Subgenerator

The proposal to introduce the @ref{2690,,yield_from} syntax,
making delegation to subgenerators easy.

@geindex Python Enhancement Proposals; PEP 525

@item PEP 525@footnote{https://peps.python.org/pep-0525/} - Asynchronous Generators

The proposal that expanded on 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} by adding generator capabilities to
coroutine functions.
@end table


@geindex object;generator

@menu
* Generator-iterator methods:: 
* Examples:: 
* Asynchronous generator functions:: 
* Asynchronous generator-iterator methods:: 

@end menu

@node Generator-iterator methods,Examples,,Yield expressions
@anchor{reference/expressions generator-iterator-methods}@anchor{2694}@anchor{reference/expressions generator-methods}@anchor{260d}
@subsubsection Generator-iterator methods


This subsection describes the methods of a generator iterator.  They can
be used to control the execution of a generator function.

Note that calling any of the generator methods below when the generator
is already executing raises a @ref{277,,ValueError} exception.

@geindex exception;StopIteration

@geindex __next__() (μέθοδος της generator)
@anchor{reference/expressions generator __next__}@anchor{229e}
@deffn {Μέθοδος} 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
@code{__next__()} method, the current yield expression always
evaluates to @ref{a65,,None}.  The execution then continues to the next yield
expression, where the generator is suspended again, and the value of the
@ref{2691,,yield_list} is returned to @code{__next__()}”s
caller.  If the generator exits without yielding another value, a
@ref{fba,,StopIteration} exception is raised.

This method is normally called implicitly, e.g. by a @ref{321,,for} loop, or
by the built-in @ref{bb5,,next()} function.
@end deffn

@geindex send() (μέθοδος της generator)
@anchor{reference/expressions generator send}@anchor{260f}
@deffn {Μέθοδος} generator.send (value)

Resumes the execution and «sends» a value into the generator function.  The
`value' argument becomes the result of the current yield expression.  The
@code{send()} method returns the next value yielded by the generator, or
raises @ref{fba,,StopIteration} if the generator exits without yielding another
value.  When @code{send()} is called to start the generator, it must be called
with @ref{a65,,None} as the argument, because there is no yield expression that
could receive the value.
@end deffn

@geindex throw() (μέθοδος της generator)
@anchor{reference/expressions generator throw}@anchor{905}
@deffn {Μέθοδος} generator.throw (value)

@deffnx {Μέθοδος} generator.throw (type[, value[, traceback]])

Raises an exception at the point where the generator was paused,
and returns the next value yielded by the generator function.  If the generator
exits without yielding another value, a @ref{fba,,StopIteration} exception is
raised.  If the generator function does not catch the passed-in exception, or
raises a different exception, then that exception propagates to the caller.

In typical use, this is called with a single exception instance similar to the
way the @ref{9e4,,raise} keyword is used.

For backwards compatibility, however, the second signature is
supported, following a convention from older versions of Python.
The `type' argument should be an exception class, and `value'
should be an exception instance. If the `value' is not provided, the
`type' constructor is called to get an instance. If `traceback'
is provided, it is set on the exception, otherwise any existing
@ref{166b,,__traceback__} attribute stored in `value' may
be cleared.


Άλλαξε στην έκδοση 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() (μέθοδος της generator)
@anchor{reference/expressions generator close}@anchor{199e}
@deffn {Μέθοδος} generator.close ()

Raises a @ref{176a,,GeneratorExit} exception at the point where the generator
function was paused (equivalent to calling @code{throw(GeneratorExit)}).
The exception is raised by the yield expression where the generator was paused.
If the generator function catches the exception and returns a
value, this value is returned from @code{close()}.  If the generator function
is already closed, or raises @code{GeneratorExit} (by not catching the
exception), @code{close()} returns @ref{a65,,None}.  If the generator yields a
value, a @ref{30d,,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, @code{close()} returns
@code{None} and has no other effect.


Άλλαξε στην έκδοση 3.13: If a generator returns a value upon being closed, the value is returned
by @code{close()}.

@end deffn

@geindex yield;examples

@node Examples,Asynchronous generator functions,Generator-iterator methods,Yield expressions
@anchor{reference/expressions examples}@anchor{2695}
@subsubsection Examples


Here is a simple example that demonstrates the behavior of generators and
generator functions:

@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

For examples using @code{yield from}, see @ref{13e2,,PEP 380; Syntax for Delegating to a Subgenerator} in «What’s New in
Python.»

@node Asynchronous generator functions,Asynchronous generator-iterator methods,Examples,Yield expressions
@anchor{reference/expressions asynchronous-generator-functions}@anchor{2693}@anchor{reference/expressions id4}@anchor{2696}
@subsubsection Asynchronous generator functions


The presence of a yield expression in a function or method defined using
@ref{9cf,,async def} further defines the function as an
@ref{2692,,asynchronous generator} function.

When an asynchronous generator function is called, it returns an
asynchronous iterator known as an asynchronous generator object.
That object then controls the execution of the generator function.
An asynchronous generator object is typically used in an
@ref{e70,,async for} statement in a coroutine function analogously to
how a generator object would be used in a @ref{321,,for} statement.

Calling one of the asynchronous generator’s methods returns an @ref{6cf,,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{2691,,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{2697,,__anext__()} is used then the result is @ref{a65,,None}. Otherwise, if
@ref{cab,,asend()} is used, then the result will be the value passed in to that
method.

If an asynchronous generator happens to exit early by @ref{428,,break}, the caller
task being cancelled, or other exceptions, the generator’s async cleanup code
will run and possibly raise exceptions or access context variables in an
unexpected context–perhaps after the lifetime of tasks it depends, or
during the event loop shutdown when the async-generator garbage collection hook
is called.
To prevent this, the caller must explicitly close the async generator by calling
@ref{caa,,aclose()} method to finalize the generator and ultimately detach it
from the event loop.

In an asynchronous generator function, yield expressions are allowed anywhere
in a @ref{ad6,,try} construct. However, if an asynchronous generator is not
resumed before it is finalized (by reaching a zero reference count or by
being garbage collected), then a yield expression within a @code{try}
construct could result in a failure to execute pending @ref{44c,,finally}
clauses.  In this case, it is the responsibility of the event loop or
scheduler running the asynchronous generator to call the asynchronous
generator-iterator’s @ref{caa,,aclose()} method and run the resulting
coroutine object, thus allowing any pending @code{finally} clauses
to execute.

To take care of finalization upon event loop termination, an event loop should
define a `finalizer' function which takes an asynchronous generator-iterator and
presumably calls @ref{caa,,aclose()} and executes the coroutine.
This  `finalizer' may be registered by calling @ref{1baa,,sys.set_asyncgen_hooks()}.
When first iterated over, an asynchronous generator-iterator will store the
registered `finalizer' to be called upon finalization. For a reference example
of a `finalizer' method see the implementation of
@code{asyncio.Loop.shutdown_asyncgens} in Lib/asyncio/base_events.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/base_events.py}.

The expression @code{yield from <expr>} is a syntax error when used in an
asynchronous generator function.

@geindex object;asynchronous-generator

@node Asynchronous generator-iterator methods,,Asynchronous generator functions,Yield expressions
@anchor{reference/expressions asynchronous-generator-iterator-methods}@anchor{2698}@anchor{reference/expressions asynchronous-generator-methods}@anchor{2699}
@subsubsection Asynchronous generator-iterator methods


This subsection describes the methods of an asynchronous generator iterator,
which are used to control the execution of a generator function.

@geindex exception;StopAsyncIteration

@geindex __anext__() (μέθοδος της agen)
@anchor{reference/expressions agen __anext__}@anchor{2697}
@deffn {Μέθοδος} async 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 @code{__anext__()}
method, the current yield expression always evaluates to @ref{a65,,None} in the
returned awaitable, which when run will continue to the next yield
expression. The value of the @ref{2691,,yield_list} of the
yield expression is the value of the @ref{fba,,StopIteration} exception raised by
the completing coroutine.  If the asynchronous generator exits without
yielding another value, the awaitable instead raises a
@ref{1ffe,,StopAsyncIteration} exception, signalling that the asynchronous
iteration has completed.

This method is normally called implicitly by a @ref{e70,,async for} loop.
@end deffn

@geindex asend() (μέθοδος της agen)
@anchor{reference/expressions agen asend}@anchor{cab}
@deffn {Μέθοδος} async agen.asend (value)

Returns an awaitable which when run resumes the execution of the
asynchronous generator. As with the @ref{260f,,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 @code{asend()} method will return the next
value yielded by the generator as the value of the raised
@ref{fba,,StopIteration}, or raises @ref{1ffe,,StopAsyncIteration} if the
asynchronous generator exits without yielding another value.  When
@code{asend()} is called to start the asynchronous
generator, it must be called with @ref{a65,,None} as the argument,
because there is no yield expression that could receive the value.
@end deffn

@geindex athrow() (μέθοδος της agen)
@anchor{reference/expressions agen athrow}@anchor{906}
@deffn {Μέθοδος} async agen.athrow (value)

@deffnx {Μέθοδος} async agen.athrow (type[, value[, traceback]])

Returns an awaitable that raises an exception of type @code{type} at the point
where the asynchronous generator was paused, and returns the next value
yielded by the generator function as the value of the raised
@ref{fba,,StopIteration} exception.  If the asynchronous generator exits
without yielding another value, a @ref{1ffe,,StopAsyncIteration} exception is
raised by the awaitable.
If the generator function does not catch the passed-in exception, or
raises a different exception, then when the awaitable is run that exception
propagates to the caller of the awaitable.


Άλλαξε στην έκδοση 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() (μέθοδος της agen)
@anchor{reference/expressions agen aclose}@anchor{caa}
@deffn {Μέθοδος} async agen.aclose ()

Returns an awaitable that when run will throw a @ref{176a,,GeneratorExit} into
the asynchronous generator function at the point where it was paused.
If the asynchronous generator function then exits gracefully, is already
closed, or raises @code{GeneratorExit} (by not catching the exception),
then the returned awaitable will raise a @ref{fba,,StopIteration} exception.
Any further awaitables returned by subsequent calls to the asynchronous
generator will raise a @ref{1ffe,,StopAsyncIteration} exception.  If the
asynchronous generator yields a value, a @ref{30d,,RuntimeError} is raised
by the awaitable.  If the asynchronous generator raises any other exception,
it is propagated to the caller of the awaitable.  If the asynchronous
generator has already exited due to an exception or normal exit, then
further calls to @code{aclose()} will return an awaitable that does nothing.
@end deffn

@node Primaries,Await expression,Atoms,Expressions
@anchor{reference/expressions id5}@anchor{269a}@anchor{reference/expressions primaries}@anchor{269b}
@subsection Primaries


@geindex primary

Primaries represent the most tightly bound operations of the language. Their
syntax is:

@example
@anchor{reference/expressions grammar-token-python-grammar-primary}@anchor{269c}primary: @ref{2662,,atom} | @ref{269d,,attributeref} | @ref{269e,,subscription} | @ref{269f,,call}
@end example

@menu
* Attribute references:: 
* Subscriptions and slicings:: 
* Calls:: 

@end menu

@node Attribute references,Subscriptions and slicings,,Primaries
@anchor{reference/expressions attribute-references}@anchor{26a0}@anchor{reference/expressions id6}@anchor{26a1}
@subsubsection Attribute references


@geindex attribute;reference
@geindex . (dot);attribute reference

An attribute reference is a primary followed by a period and a name:

@example
@anchor{reference/expressions grammar-token-python-grammar-attributeref}@anchor{269d}attributeref: @ref{269c,,primary} "." @ref{24b2,,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{f90,,__getattribute__()} method or the @ref{8e3,,__getattr__()}
method.  The @code{__getattribute__()} method is called first and either
returns a value or raises @ref{1a9,,AttributeError} if the attribute is not
available.

If an @ref{1a9,,AttributeError} is raised and the object has a @code{__getattr__()}
method, that method is called as a fallback.

@node Subscriptions and slicings,Calls,Attribute references,Primaries
@anchor{reference/expressions subscriptions}@anchor{2599}@anchor{reference/expressions subscriptions-and-slicings}@anchor{26a2}
@subsubsection Subscriptions and slicings


@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

The `subscription' syntax is usually used for selecting an element from a
@ref{25c9,,container} – for example, to get a value from
a @ref{188,,dict}:

@example
>>> digits_by_name = @{'one': 1, 'two': 2@}
>>> digits_by_name['two']  # Subscripting a dictionary using the key 'two'
2
@end example

In the subscription syntax, the object being subscribed – a
@ref{269b,,primary} – is followed by a `subscript' in
square brackets.
In the simplest case, the subscript is a single expression.

Depending on the type of the object being subscribed, the subscript is
sometimes called a @ref{25d9,,key} (for mappings), @ref{25d8,,index} (for sequences),
or `type argument' (for @ref{1d1,,generic types}).
Syntactically, these are all equivalent:

@example
>>> colors = ['red', 'blue', 'green', 'black']
>>> colors[3]  # Subscripting a list using the index 3
'black'

>>> list[str]  # Parameterizing the list type using the type argument str
list[str]
@end example

At runtime, the interpreter will evaluate the primary and
the subscript, and call the primary’s @ref{787,,__getitem__()} or
@ref{b21,,__class_getitem__()} @ref{1e57,,special method} with the subscript
as argument.
For more details on which of these methods is called, see
@ref{25c3,,__class_getitem__ έναντι __getitem__}.

To show how subscription works, we can define a custom object that
implements @ref{787,,__getitem__()} and prints out the value of
the subscript:

@example
>>> class SubscriptionDemo:
...     def __getitem__(self, key):
...         print(f'subscripted with: @{key!r@}')
...
>>> demo = SubscriptionDemo()
>>> demo[1]
subscripted with: 1
>>> demo['a' * 3]
subscripted with: 'aaa'
@end example

See @ref{787,,__getitem__()} documentation for how built-in types handle
subscription.

Subscriptions may also be used as targets in @ref{261d,,assignment} or
@ref{1d1d,,deletion} statements.
In these cases, the interpreter will call the subscripted object’s
@ref{1670,,__setitem__()} or @ref{1671,,__delitem__()}
@ref{1e57,,special method}, respectively, instead of @ref{787,,__getitem__()}.

@example
>>> colors = ['red', 'blue', 'green', 'black']
>>> colors[3] = 'white'  # Setting item at index
>>> colors
['red', 'blue', 'green', 'white']
>>> del colors[3]  # Deleting item at index 3
>>> colors
['red', 'blue', 'green']
@end example

All advanced forms of `subscript' documented in the following sections
are also usable for assignment and deletion.

@geindex slicing
@geindex slice
@geindex ; (colon);slicing
@geindex @comma{} (comma);slicing

@geindex object;sequence
@geindex object;string
@geindex object;tuple
@geindex object;list

@menu
* Slicings:: 
* Comma-separated subscripts:: 
* «Starred» subscriptions:: 
* Formal subscription grammar:: 

@end menu

@node Slicings,Comma-separated subscripts,,Subscriptions and slicings
@anchor{reference/expressions id7}@anchor{26a3}@anchor{reference/expressions slicings}@anchor{26a4}
@subsubsection Slicings


A more advanced form of subscription, `slicing', is commonly used
to extract a portion of a @ref{2529,,sequence}.
In this form, the subscript is a @ref{26a5,,slice}: up to three
expressions separated by colons.
Any of the expressions may be omitted, but a slice must contain at least one
colon:

@example
>>> number_names = ['zero', 'one', 'two', 'three', 'four', 'five']
>>> number_names[1:3]
['one', 'two']
>>> number_names[1:]
['one', 'two', 'three', 'four', 'five']
>>> number_names[:3]
['zero', 'one', 'two']
>>> number_names[:]
['zero', 'one', 'two', 'three', 'four', 'five']
>>> number_names[::2]
['zero', 'two', 'four']
>>> number_names[:-3]
['zero', 'one', 'two']
>>> del number_names[4:]
>>> number_names
['zero', 'one', 'two', 'three']
@end example

When a slice is evaluated, the interpreter constructs a @ref{1d0,,slice} object
whose @ref{259a,,start}, @ref{259b,,stop} and
@ref{259c,,step} attributes, respectively, are the results of the
expressions between the colons.
Any missing expression evaluates to @ref{a65,,None}.
This @code{slice} object is then passed to the @ref{787,,__getitem__()}
or @ref{b21,,__class_getitem__()} @ref{1e57,,special method}, as above.

@example
# continuing with the SubscriptionDemo instance defined above:
>>> demo[2:3]
subscripted with: slice(2, 3, None)
>>> demo[::'spam']
subscripted with: slice(None, None, 'spam')
@end example

@node Comma-separated subscripts,«Starred» subscriptions,Slicings,Subscriptions and slicings
@anchor{reference/expressions comma-separated-subscripts}@anchor{26a6}
@subsubsection Comma-separated subscripts


The subscript can also be given as two or more comma-separated expressions
or slices:

@example
# continuing with the SubscriptionDemo instance defined above:
>>> demo[1, 2, 3]
subscripted with: (1, 2, 3)
>>> demo[1:2, 3]
subscripted with: (slice(1, 2, None), 3)
@end example

This form is commonly used with numerical libraries for slicing
multi-dimensional data.
In this case, the interpreter constructs a @ref{1ce,,tuple} of the results of the
expressions or slices, and passes this tuple to the @ref{787,,__getitem__()}
or @ref{b21,,__class_getitem__()} @ref{1e57,,special method}, as above.

The subscript may also be given as a single expression or slice followed
by a comma, to specify a one-element tuple:

@example
>>> demo['spam',]
subscripted with: ('spam',)
@end example

@node «Starred» subscriptions,Formal subscription grammar,Comma-separated subscripts,Subscriptions and slicings
@anchor{reference/expressions starred-subscriptions}@anchor{26a7}
@subsubsection «Starred» subscriptions



Added in version 3.11: Expressions in `tuple_slices' may be starred. See 
@geindex Python Enhancement Proposals; PEP 646
PEP 646@footnote{https://peps.python.org/pep-0646/}.


The subscript can also contain a starred expression.
In this case, the interpreter unpacks the result into a tuple, and passes
this tuple to @ref{787,,__getitem__()} or @ref{b21,,__class_getitem__()}:

@example
# continuing with the SubscriptionDemo instance defined above:
>>> demo[*range(10)]
subscripted with: (0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
@end example

Starred expressions may be combined with comma-separated expressions
and slices:

@example
>>> demo['a', 'b', *range(3), 'c']
subscripted with: ('a', 'b', 0, 1, 2, 'c')
@end example

@node Formal subscription grammar,,«Starred» subscriptions,Subscriptions and slicings
@anchor{reference/expressions formal-subscription-grammar}@anchor{26a8}
@subsubsection Formal subscription grammar


@example
@anchor{reference/expressions grammar-token-python-grammar-subscription}@anchor{269e}subscription:     @ref{269c,,primary} '[' @ref{26a9,,subscript} ']'
@anchor{reference/expressions grammar-token-python-grammar-subscript}@anchor{26a9}subscript:        @ref{26aa,,single_subscript} | @ref{26ab,,tuple_subscript}
@anchor{reference/expressions grammar-token-python-grammar-single_subscript}@anchor{26aa}single_subscript: @ref{26ac,,proper_slice} | @ref{2623,,assignment_expression}
@anchor{reference/expressions grammar-token-python-grammar-proper_slice}@anchor{26ac}proper_slice:     [@ref{42a,,expression}] ":" [@ref{42a,,expression}] [ ":" [@ref{42a,,expression}] ]
@anchor{reference/expressions grammar-token-python-grammar-tuple_subscript}@anchor{26ab}tuple_subscript:  ','.(@ref{26aa,,single_subscript} | @ref{267a,,starred_expression})+ [',']
@end example

Recall that the @code{|} operator @ref{2475,,denotes ordered choice}.
Specifically, in @code{subscript}, if both alternatives would match, the
first (@code{single_subscript}) has priority.

@geindex object;callable
@geindex call
@geindex argument;call semantics
@geindex () (parentheses);call
@geindex @comma{} (comma);argument list
@geindex = (equals);in function calls

@node Calls,,Subscriptions and slicings,Primaries
@anchor{reference/expressions calls}@anchor{1136}@anchor{reference/expressions id8}@anchor{26ad}
@subsubsection Calls


A call calls a callable object (e.g., a @ref{26ae,,function}) with a possibly empty
series of @ref{867,,arguments}:

@example
@anchor{reference/expressions grammar-token-python-grammar-call}@anchor{269f}call:                 @ref{269c,,primary} "(" [@ref{26af,,argument_list} [","] | @ref{267c,,comprehension}] ")"
@anchor{reference/expressions grammar-token-python-grammar-argument_list}@anchor{26af}argument_list:        @ref{26b0,,positional_arguments} ["," @ref{26b1,,starred_and_keywords}]
                        ["," @ref{26b2,,keywords_arguments}]
                      | @ref{26b1,,starred_and_keywords} ["," @ref{26b2,,keywords_arguments}]
                      | @ref{26b2,,keywords_arguments}
@anchor{reference/expressions grammar-token-python-grammar-positional_arguments}@anchor{26b0}positional_arguments: @ref{26b3,,positional_item} ("," @ref{26b3,,positional_item})*
@anchor{reference/expressions grammar-token-python-grammar-positional_item}@anchor{26b3}positional_item:      @ref{2623,,assignment_expression} | "*" @ref{42a,,expression}
@anchor{reference/expressions grammar-token-python-grammar-starred_and_keywords}@anchor{26b1}starred_and_keywords: ("*" @ref{42a,,expression} | @ref{26b4,,keyword_item})
                      ("," "*" @ref{42a,,expression} | "," @ref{26b4,,keyword_item})*
@anchor{reference/expressions grammar-token-python-grammar-keywords_arguments}@anchor{26b2}keywords_arguments:   (@ref{26b4,,keyword_item} | "**" @ref{42a,,expression})
                      ("," @ref{26b4,,keyword_item} | "," "**" @ref{42a,,expression})*
@anchor{reference/expressions grammar-token-python-grammar-keyword_item}@anchor{26b4}keyword_item:         @ref{24b2,,identifier} "=" @ref{42a,,expression}
@end example

An optional trailing comma may be present after the positional and keyword arguments
but does not affect the semantics.

@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{961,,__call__()} method are callable).  All
argument expressions are evaluated before the call is attempted.  Please refer
to section @ref{2206,,Function definitions} for the syntax of formal @ref{253c,,parameter} lists.

@c XXX update with kwonly args PEP

If keyword arguments are present, they are first converted to positional
arguments, as follows.  First, a list of unfilled slots is created for the
formal parameters.  If there are N positional arguments, they are placed in the
first N slots.  Next, for each keyword argument, the identifier is used to
determine the corresponding slot (if the identifier is the same as the first
formal parameter name, the first slot is used, and so on).  If the slot is
already filled, a @ref{291,,TypeError} exception is raised. Otherwise, the
argument is placed in the slot, filling it (even if the expression is
@code{None}, it fills the slot).  When all arguments have been processed, the slots
that are still unfilled are filled with the corresponding default value from the
function definition.  (Default values are calculated, once, when the function is
defined; thus, a mutable object such as a list or dictionary used as default
value will be shared by all calls that don’t specify an argument value for the
corresponding slot; this should usually be avoided.)  If there are any unfilled
slots for which no default value is specified, a @code{TypeError} exception is
raised.  Otherwise, the list of filled slots is used as the argument list for
the call.

`Λεπτομέρεια υλοποίησης CPython:' An implementation may provide built-in functions whose positional parameters
do not have names, even if they are “named” for the purpose of documentation,
and which therefore cannot be supplied by keyword.  In CPython, this is the
case for functions implemented in C that use @ref{3b1,,PyArg_ParseTuple()} to
parse their arguments.

If there are more positional arguments than there are formal parameter slots, a
@ref{291,,TypeError} exception is raised, unless a formal parameter using the syntax
@code{*identifier} is present; in this case, that formal parameter receives a tuple
containing the excess positional arguments (or an empty tuple if there were no
excess positional arguments).

If any keyword argument does not correspond to a formal parameter name, a
@ref{291,,TypeError} exception is raised, unless a formal parameter using the syntax
@code{**identifier} is present; in this case, that formal parameter receives a
dictionary containing the excess keyword arguments (using the keywords as keys
and the argument values as corresponding values), or a (new) empty dictionary if
there were no excess keyword arguments.

@geindex * (asterisk);in function calls
@geindex unpacking;in function calls

If the syntax @code{*expression} appears in the function call, @code{expression} must
evaluate to an @ref{15ce,,iterable}.  Elements from these iterables are
treated as if they were additional positional arguments.  For the call
@code{f(x1, x2, *y, x3, x4)}, if `y' evaluates to a sequence `y1', …, `yM',
this is equivalent to a call with M+4 positional arguments `x1', `x2',
`y1', …, `yM', `x3', `x4'.

A consequence of this is that although the @code{*expression} syntax may appear
`after' explicit keyword arguments, it is processed `before' the
keyword arguments (and any @code{**expression} arguments – see below).  So:

@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

It is unusual for both keyword arguments and the @code{*expression} syntax to be
used in the same call, so in practice this confusion does not often arise.

@geindex **;in function calls

If the syntax @code{**expression} appears in the function call, @code{expression} must
evaluate to a @ref{1564,,mapping}, the contents of which are treated as
additional keyword arguments. If a parameter matching a key has already been
given a value (by an explicit keyword argument, or from another unpacking),
a @ref{291,,TypeError} exception is raised.

When @code{**expression} is used, each key in this mapping must be
a string.
Each value from the mapping is assigned to the first formal parameter
eligible for keyword assignment whose name is equal to the key.
A key need not be a Python identifier (e.g. @code{"max-temp °F"} is acceptable,
although it will not match any formal parameter that could be declared).
If there is no match to a formal parameter
the key-value pair is collected by the @code{**} parameter, if there is one,
or if there is not, a @ref{291,,TypeError} exception is raised.

Formal parameters using the syntax @code{*identifier} or @code{**identifier} cannot be
used as positional argument slots or as keyword argument names.


Άλλαξε στην έκδοση 3.5: Function calls accept any number of @code{*} and @code{**} unpackings,
positional arguments may follow iterable unpackings (@code{*}),
and keyword arguments may follow dictionary unpackings (@code{**}).
Originally proposed by 
@geindex Python Enhancement Proposals; PEP 448
PEP 448@footnote{https://peps.python.org/pep-0448/}.


A call always returns some value, possibly @code{None}, unless it raises an
exception.  How this value is computed depends on the type of the callable
object.

If it is—


@table @asis

@item a user-defined function:

@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{2206,,Function definitions}.  When the code block
executes a @ref{44b,,return} statement, this specifies the return value of the
function call.  If execution reaches the end of the code block without
executing a @code{return} statement, the return value is @code{None}.

@item a built-in function or method:

@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

The result is up to the interpreter; see @ref{1601,,Ενσωματωμένες (Built-in) Συναρτήσεις} for the
descriptions of built-in functions and methods.

@item a class object:

@geindex object;class
@geindex class object;call

A new instance of that class is returned.

@item a class instance method:

@geindex object;class instance
@geindex object;instance
@geindex class instance;call

The corresponding user-defined function is called, with an argument list that is
one longer than the argument list of the call: the instance becomes the first
argument.

@item a class instance:

@geindex instance;call
@geindex __call__() (object method)

The class must define a @ref{961,,__call__()} method; the effect is then the same as
if that method was called.
@end table

@geindex keyword;await

@node Await expression,The power operator,Primaries,Expressions
@anchor{reference/expressions await}@anchor{432}@anchor{reference/expressions await-expression}@anchor{26b5}
@subsection Await expression


Suspend the execution of @ref{8a2,,coroutine} on an @ref{6cf,,awaitable} object.
Can only be used inside a @ref{112c,,coroutine function}.

@example
@anchor{reference/expressions grammar-token-python-grammar-await_expr}@anchor{26b6}await_expr: "await" @ref{269c,,primary}
@end example


Added in version 3.5.


@node The power operator,Unary arithmetic and bitwise operations,Await expression,Expressions
@anchor{reference/expressions power}@anchor{26b7}@anchor{reference/expressions the-power-operator}@anchor{26b8}
@subsection The power operator


@geindex power;operation
@geindex operator;**

The power operator binds more tightly than unary operators on its left; it binds
less tightly than unary operators on its right.  The syntax is:

@example
@anchor{reference/expressions grammar-token-python-grammar-power}@anchor{26b9}power: (@ref{26b6,,await_expr} | @ref{269c,,primary}) ["**" @ref{26ba,,u_expr}]
@end example

Thus, in an unparenthesized sequence of power and unary operators, the operators
are evaluated from right to left (this does not constrain the evaluation order
for the operands): @code{-1**2} results in @code{-1}.

The power operator has the same semantics as the built-in @ref{441,,pow()} function,
when called with two arguments: it yields its left argument raised to the power
of its right argument.
Numeric arguments are first @ref{265f,,converted to a common type},
and the result is of that type.

For int operands, the result has the same type as the operands unless the second
argument is negative; in that case, all arguments are converted to float and a
float result is delivered. For example, @code{10**2} returns @code{100}, but
@code{10**-2} returns @code{0.01}.

Raising @code{0.0} to a negative power results in a @ref{d11,,ZeroDivisionError}.
Raising a negative number to a fractional power results in a @ref{328,,complex}
number. (In earlier versions it raised a @ref{277,,ValueError}.)

This operation can be customized using the special @ref{bb1,,__pow__()} and
@ref{442,,__rpow__()} methods.

@node Unary arithmetic and bitwise operations,Binary arithmetic operations,The power operator,Expressions
@anchor{reference/expressions unary}@anchor{2672}@anchor{reference/expressions unary-arithmetic-and-bitwise-operations}@anchor{26bb}
@subsection Unary arithmetic and bitwise operations


@geindex unary;arithmetic;operation
@geindex unary;bitwise;operation

All unary arithmetic and bitwise operations have the same priority:

@example
@anchor{reference/expressions grammar-token-python-grammar-u_expr}@anchor{26ba}u_expr: @ref{26b9,,power} | "-" @ref{26ba,,u_expr} | "+" @ref{26ba,,u_expr} | "~" @ref{26ba,,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{25f8,,__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{25f9,,__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{25fb,,__invert__()} special method.

@geindex exception;TypeError

In all three cases, if the argument does not have the proper type, a
@ref{291,,TypeError} exception is raised.

@node Binary arithmetic operations,Shifting operations,Unary arithmetic and bitwise operations,Expressions
@anchor{reference/expressions binary}@anchor{2673}@anchor{reference/expressions binary-arithmetic-operations}@anchor{26bc}
@subsection Binary arithmetic operations


@geindex binary;arithmetic;operation

The binary arithmetic operations have the conventional priority levels.  Note
that some of these operations also apply to certain non-numeric types.  Apart
from the power operator, there are only two levels, one for multiplicative
operators and one for additive operators:

@example
@anchor{reference/expressions grammar-token-python-grammar-m_expr}@anchor{26bd}m_expr: @ref{26ba,,u_expr} | @ref{26bd,,m_expr} "*" @ref{26ba,,u_expr} | @ref{26bd,,m_expr} "@@" @ref{26bd,,m_expr} |
        @ref{26bd,,m_expr} "//" @ref{26ba,,u_expr} | @ref{26bd,,m_expr} "/" @ref{26ba,,u_expr} |
        @ref{26bd,,m_expr} "%" @ref{26ba,,u_expr}
@anchor{reference/expressions grammar-token-python-grammar-a_expr}@anchor{26be}a_expr: @ref{26bd,,m_expr} | @ref{26be,,a_expr} "+" @ref{26bd,,m_expr} | @ref{26be,,a_expr} "-" @ref{26bd,,m_expr}
@end example

@geindex multiplication
@geindex operator;* (asterisk)

The @code{*} (multiplication) operator yields the product of its arguments.  The
arguments must either both be numbers, or one argument must be an integer and
the other must be a sequence. In the former case, the numbers are
@ref{265f,,converted to a common real type} and then
multiplied together.  In the latter case, sequence repetition is performed;
a negative repetition factor yields an empty sequence.

This operation can be customized using the special @ref{25d5,,__mul__()} and
@ref{25d6,,__rmul__()} methods.


Άλλαξε στην έκδοση 3.14: If only one operand is a complex number, the other operand is converted
to a floating-point number.


@geindex matrix multiplication
@geindex operator;@@ (at)

The @code{@@} (at) operator is intended to be used for matrix multiplication.  No
builtin Python types implement this operator.

This operation can be customized using the special @ref{1132,,__matmul__()} and
@ref{1133,,__rmatmul__()} methods.


Added in version 3.5.


@geindex exception;ZeroDivisionError
@geindex division
@geindex operator;/ (slash)
@geindex operator;//

The @code{/} (division) and @code{//} (floor division) operators yield the quotient of
their arguments.  The numeric arguments are first
@ref{265f,,converted to a common type}.
Division of integers yields a float, while floor division of integers results in an
integer; the result is that of mathematical division with the “floor” function
applied to the result.  Division by zero raises the @ref{d11,,ZeroDivisionError}
exception.

The division operation can be customized using the special @ref{1241,,__truediv__()}
and @ref{25e6,,__rtruediv__()} methods.
The floor division operation can be customized using the special
@ref{1896,,__floordiv__()} and @ref{25e7,,__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
@ref{265f,,converted to a common type}.
A zero right argument raises the @ref{d11,,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{
While @code{abs(x%y) < abs(y)} is true mathematically, for floats it may not be
true numerically due to roundoff.  For example, and assuming a platform on which
a Python float is an IEEE 754 double-precision number, in order that @code{-1e-100 %
1e100} have the same sign as @code{1e100}, the computed result is @code{-1e-100 +
1e100}, which is numerically exactly equal to @code{1e100}.  The function
@ref{26bf,,math.fmod()} returns a result whose sign matches the sign of the
first argument instead, and so returns @code{-1e-100} in this case. Which approach
is more appropriate depends on the application.
}.

The floor division and modulo operators are connected by the following
identity: @code{x == (x//y)*y + (x%y)}.  Floor division and modulo are also
connected with the built-in function @ref{d6a,,divmod()}: @code{divmod(x, y) == (x//y,
x%y)}. @footnote{
If x is very close to an exact integer multiple of y, it’s possible for
@code{x//y} to be one larger than @code{(x-x%y)//y} due to rounding.  In such
cases, Python returns the latter result, in order to preserve that
@code{divmod(x,y)[0] * y + x % y} be very close to @code{x}.
}.

In addition to performing the modulo operation on numbers, the @code{%} operator is
also overloaded by string objects to perform old-style string formatting (also
known as interpolation).  The syntax for string formatting is described in the
Python Library Reference, section @ref{ab9,,printf-style String Formatting}.

The `modulo' operation can be customized using the special @ref{25df,,__mod__()}
and @ref{118e,,__rmod__()} methods.

The floor division operator, the modulo operator, and the @ref{d6a,,divmod()}
function are not defined for complex numbers.  Instead, convert to a
floating-point number using the @ref{227c,,abs()} function if appropriate.

@geindex addition
@geindex operator;+ (plus)
@geindex + (plus);binary operator

The @code{+} (addition) operator yields the sum of its arguments.  The arguments
must either both be numbers or both be sequences of the same type.  In the
former case, the numbers are
@ref{265f,,converted to a common real type} and then
added together.
In the latter case, the sequences are concatenated.

This operation can be customized using the special @ref{25d2,,__add__()} and
@ref{25d3,,__radd__()} methods.


Άλλαξε στην έκδοση 3.14: If only one operand is a complex number, the other operand is converted
to a floating-point number.


@geindex subtraction
@geindex operator;- (minus)
@geindex - (minus);binary operator

The @code{-} (subtraction) operator yields the difference of its arguments.
The numeric arguments are first
@ref{265f,,converted to a common real type}.

This operation can be customized using the special @ref{25de,,__sub__()} and
@ref{25e5,,__rsub__()} methods.


Άλλαξε στην έκδοση 3.14: If only one operand is a complex number, the other operand is converted
to a floating-point number.


@node Shifting operations,Binary bitwise operations,Binary arithmetic operations,Expressions
@anchor{reference/expressions shifting}@anchor{26c0}@anchor{reference/expressions shifting-operations}@anchor{26c1}
@subsection Shifting operations


@geindex shifting;operation
@geindex operator;<<
@geindex operator;>>

The shifting operations have lower priority than the arithmetic operations:

@example
@anchor{reference/expressions grammar-token-python-grammar-shift_expr}@anchor{26c2}shift_expr: @ref{26be,,a_expr} | @ref{26c2,,shift_expr} ("<<" | ">>") @ref{26be,,a_expr}
@end example

These operators accept integers as arguments.  They shift the first argument to
the left or right by the number of bits given by the second argument.

The left shift operation can be customized using the special @ref{25e0,,__lshift__()}
and @ref{25e9,,__rlshift__()} methods.
The right shift operation can be customized using the special @ref{25e1,,__rshift__()}
and @ref{25ea,,__rrshift__()} methods.

@geindex exception;ValueError

A right shift by `n' bits is defined as floor division by @code{pow(2,n)}.  A left
shift by `n' bits is defined as multiplication with @code{pow(2,n)}.

@node Binary bitwise operations,Comparisons,Shifting operations,Expressions
@anchor{reference/expressions binary-bitwise-operations}@anchor{26c3}@anchor{reference/expressions bitwise}@anchor{26c4}
@subsection Binary bitwise operations


@geindex binary;bitwise;operation

Each of the three bitwise operations has a different priority level:

@example
@anchor{reference/expressions grammar-token-python-grammar-and_expr}@anchor{26c5}and_expr: @ref{26c2,,shift_expr} | @ref{26c5,,and_expr} "&" @ref{26c2,,shift_expr}
@anchor{reference/expressions grammar-token-python-grammar-xor_expr}@anchor{26c6}xor_expr: @ref{26c5,,and_expr} | @ref{26c6,,xor_expr} "^" @ref{26c5,,and_expr}
@anchor{reference/expressions grammar-token-python-grammar-or_expr}@anchor{24f3}or_expr:  @ref{26c6,,xor_expr} | @ref{24f3,,or_expr} "|" @ref{26c6,,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{25e2,,__and__()} or
@ref{25eb,,__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{25e3,,__xor__()} or
@ref{25ec,,__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{25e4,,__or__()} or
@ref{25ed,,__ror__()} special methods.

@node Comparisons,Boolean operations,Binary bitwise operations,Expressions
@anchor{reference/expressions comparisons}@anchor{26c7}@anchor{reference/expressions id11}@anchor{26c8}
@subsection Comparisons


@geindex comparison
@geindex C;language
@geindex operator;< (less)
@geindex operator;> (greater)
@geindex operator;<=
@geindex operator;>=
@geindex operator;==
@geindex operator;!=

Unlike C, all comparison operations in Python have the same priority, which is
lower than that of any arithmetic, shifting or bitwise operation.  Also unlike
C, expressions like @code{a < b < c} have the interpretation that is conventional
in mathematics:

@example
@anchor{reference/expressions grammar-token-python-grammar-comparison}@anchor{26c9}comparison:    @ref{24f3,,or_expr} (@ref{26ca,,comp_operator} @ref{24f3,,or_expr})*
@anchor{reference/expressions grammar-token-python-grammar-comp_operator}@anchor{26ca}comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!="
               | "is" ["not"] | ["not"] "in"
@end example

Comparisons yield boolean values: @code{True} or @code{False}. Custom
`rich comparison methods' may return non-boolean values. In this case
Python will call @ref{5ef,,bool()} on such value in boolean contexts.

@geindex chaining;comparisons

Comparisons can be chained arbitrarily, e.g., @code{x < y <= z} is equivalent to
@code{x < y and y <= z}, except that @code{y} is evaluated only once (but in both
cases @code{z} is not evaluated at all when @code{x < y} is found to be false).

Formally, if `a', `b', `c', …, `y', `z' are expressions and `op1', `op2', …,
`opN' are comparison operators, then @code{a op1 b op2 c ... y opN z} is equivalent
to @code{a op1 b and b op2 c and ... y opN z}, except that each expression is
evaluated at most once.

Note that @code{a op1 b op2 c} doesn’t imply any kind of comparison between `a' and
`c', so that, e.g., @code{x < y > z} is perfectly legal (though perhaps not
pretty).

@menu
* Value comparisons:: 
* Membership test operations:: 
* Identity comparisons:: 

@end menu

@node Value comparisons,Membership test operations,,Comparisons
@anchor{reference/expressions expressions-value-comparisons}@anchor{1e17}@anchor{reference/expressions value-comparisons}@anchor{26cb}
@subsubsection Value comparisons


The operators @code{<}, @code{>}, @code{==}, @code{>=}, @code{<=}, and @code{!=} compare the
values of two objects.  The objects do not need to have the same type.

Chapter @ref{251d,,Αντικείμενα@comma{} τιμές και τύποι} states that objects have a value (in addition to type
and identity).  The value of an object is a rather abstract notion in Python:
For example, there is no canonical access method for an object’s value.  Also,
there is no requirement that the value of an object should be constructed in a
particular way, e.g. comprised of all its data attributes. Comparison operators
implement a particular notion of what the value of an object is.  One can think
of them as defining the value of an object indirectly, by means of their
comparison implementation.

Because all types are (direct or indirect) subtypes of @ref{e4d,,object}, they
inherit the default comparison behavior from @code{object}.  Types can
customize their comparison behavior by implementing
`rich comparison methods' like @ref{1645,,__lt__()}, described in
@ref{25a2,,Βασική προσαρμογή}.

The default behavior for equality comparison (@code{==} and @code{!=}) is based on
the identity of the objects.  Hence, equality comparison of instances with the
same identity results in equality, and equality comparison of instances with
different identities results in inequality.  A motivation for this default
behavior is the desire that all objects should be reflexive (i.e. @code{x is y}
implies @code{x == y}).

A default order comparison (@code{<}, @code{>}, @code{<=}, and @code{>=}) is not provided;
an attempt raises @ref{291,,TypeError}.  A motivation for this default behavior is
the lack of a similar invariant as for equality.

The behavior of the default equality comparison, that instances with different
identities are always unequal, may be in contrast to what types will need that
have a sensible definition of object value and value-based equality.  Such
types will need to customize their comparison behavior, and in fact, a number
of built-in types have done that.

The following list describes the comparison behavior of the most important
built-in types.


@itemize *

@item 
Numbers of built-in numeric types (@ref{21c9,,Αριμθητικοί Τύποι — int@comma{} float@comma{} complex}) and of the standard
library types @ref{1c3,,fractions.Fraction} and @ref{1c2,,decimal.Decimal} can be
compared within and across their types, with the restriction that complex
numbers do not support order comparison.  Within the limits of the types
involved, they compare mathematically (algorithmically) correct without loss
of precision.

The not-a-number values @code{float('NaN')} and @code{decimal.Decimal('NaN')} are
special.  Any ordered comparison of a number to a not-a-number value is false.
A counter-intuitive implication is that not-a-number values are not equal to
themselves.  For example, if @code{x = float('NaN')}, @code{3 < x}, @code{x < 3} and
@code{x == x} are all false, while @code{x != x} is true.  This behavior is
compliant with IEEE 754.

@item 
@code{None} and @ref{440,,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 
Binary sequences (instances of @ref{1c7,,bytes} or @ref{1c6,,bytearray}) can be
compared within and across their types.  They compare lexicographically using
the numeric values of their elements.

@item 
Strings (instances of @ref{1df,,str}) compare lexicographically using the
numerical Unicode code points (the result of the built-in function
@ref{252c,,ord()}) of their characters. @footnote{
The Unicode standard distinguishes between `code points'
(e.g. U+0041) and `abstract characters' (e.g. «LATIN CAPITAL LETTER A»).
While most abstract characters in Unicode are only represented using one
code point, there is a number of abstract characters that can in addition be
represented using a sequence of more than one code point.  For example, the
abstract character «LATIN CAPITAL LETTER C WITH CEDILLA» can be represented
as a single `precomposed character' at code position U+00C7, or as a
sequence of a `base character' at code position U+0043 (LATIN CAPITAL
LETTER C), followed by a `combining character' at code position U+0327
(COMBINING CEDILLA).

The comparison operators on strings compare at the level of Unicode code
points. This may be counter-intuitive to humans.  For example,
@code{"\u00C7" == "\u0043\u0327"} is @code{False}, even though both strings
represent the same abstract character «LATIN CAPITAL LETTER C WITH CEDILLA».

To compare strings at the level of abstract characters (that is, in a way
intuitive to humans), use @ref{ac2,,unicodedata.normalize()}.
}

Strings and binary sequences cannot be directly compared.

@item 
Sequences (instances of @ref{1ce,,tuple}, @ref{4d9,,list}, or @ref{d0f,,range}) can
be compared only within each of their types, with the restriction that ranges
do not support order comparison.  Equality comparison across these types
results in inequality, and ordering comparison across these types raises
@ref{291,,TypeError}.

Sequences compare lexicographically using comparison of corresponding
elements.  The built-in containers typically assume identical objects are
equal to themselves.  That lets them bypass equality tests for identical
objects to improve performance and to maintain their internal invariants.

Lexicographical comparison between built-in collections works as follows:


@itemize -

@item 
For two collections to compare equal, they must be of the same type, have
the same length, and each pair of corresponding elements must compare
equal (for example, @code{[1,2] == (1,2)} is false because the type is not the
same).

@item 
Collections that support order comparison are ordered the same as their
first unequal elements (for example, @code{[1,2,x] <= [1,2,y]} has the same
value as @code{x <= y}).  If a corresponding element does not exist, the
shorter collection is ordered first (for example, @code{[1,2] < [1,2,3]} is
true).
@end itemize

@item 
Mappings (instances of @ref{188,,dict}) compare equal if and only if they have
equal @code{(key, value)} pairs. Equality comparison of the keys and values
enforces reflexivity.

Order comparisons (@code{<}, @code{>}, @code{<=}, and @code{>=}) raise @ref{291,,TypeError}.

@item 
Sets (instances of @ref{42b,,set} or @ref{9d4,,frozenset}) can be compared within
and across their types.

They define order
comparison operators to mean subset and superset tests.  Those relations do
not define total orderings (for example, the two sets @code{@{1,2@}} and @code{@{2,3@}}
are not equal, nor subsets of one another, nor supersets of one
another).  Accordingly, sets are not appropriate arguments for functions
which depend on total ordering (for example, @ref{12b9,,min()}, @ref{12ba,,max()}, and
@ref{f8c,,sorted()} produce undefined results given a list of sets as inputs).

Comparison of sets enforces reflexivity of its elements.

@item 
Most other built-in types have no comparison methods implemented, so they
inherit the default comparison behavior.
@end itemize

User-defined classes that customize their comparison behavior should follow
some consistency rules, if possible:


@itemize *

@item 
Equality comparison should be reflexive.
In other words, identical objects should compare equal:

@quotation

@code{x is y} implies @code{x == y}
@end quotation

@item 
Comparison should be symmetric.
In other words, the following expressions should have the same result:

@quotation

@code{x == y} and @code{y == x}

@code{x != y} and @code{y != x}

@code{x < y} and @code{y > x}

@code{x <= y} and @code{y >= x}
@end quotation

@item 
Comparison should be transitive.
The following (non-exhaustive) examples illustrate that:

@quotation

@code{x > y and y > z} implies @code{x > z}

@code{x < y and y <= z} implies @code{x < z}
@end quotation

@item 
Inverse comparison should result in the boolean negation.
In other words, the following expressions should have the same result:

@quotation

@code{x == y} and @code{not x != y}

@code{x < y} and @code{not x >= y} (for total ordering)

@code{x > y} and @code{not x <= y} (for total ordering)
@end quotation

The last two expressions apply to totally ordered collections (e.g. to
sequences, but not to sets or mappings). See also the
@ref{12ed,,total_ordering()} decorator.

@item 
The @ref{9e2,,hash()} result should be consistent with equality.
Objects that are equal should either have the same hash value,
or be marked as unhashable.
@end itemize

Python does not enforce these consistency rules. In fact, the not-a-number
values are an example for not following these rules.
@anchor{reference/expressions in}@anchor{323}@anchor{reference/expressions not-in}@anchor{a20}
@node Membership test operations,Identity comparisons,Value comparisons,Comparisons
@anchor{reference/expressions membership-test-details}@anchor{25db}@anchor{reference/expressions membership-test-operations}@anchor{26cc}
@subsubsection Membership test operations


The operators @ref{323,,in} and @ref{a20,,not in} test for membership.  @code{x in
s} evaluates to @code{True} if `x' is a member of `s', and @code{False} otherwise.
@code{x not in s} returns the negation of @code{x in s}.  All built-in sequences and
set types support this as well as dictionary, for which @code{in} tests
whether the dictionary has a given key. For container types such as list, tuple,
set, frozenset, dict, or collections.deque, the expression @code{x in y} is equivalent
to @code{any(x is e or x == e for e in y)}.

For the string and bytes types, @code{x in y} is @code{True} if and only if `x' is a
substring of `y'.  An equivalent test is @code{y.find(x) != -1}.  Empty strings are
always considered to be a substring of any other string, so @code{"" in "abc"} will
return @code{True}.

For user-defined classes which define the @ref{175c,,__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{175c,,__contains__()} but do define
@ref{102d,,__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{323,,in} raised
that exception.

Lastly, the old-style iteration protocol is tried: if a class defines
@ref{787,,__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{18d7,,IndexError} exception.  (If any other exception is raised, it is as
if @ref{323,,in} raised that exception).

@geindex operator;in
@geindex operator;not in
@geindex membership;test
@geindex object;sequence

The operator @ref{a20,,not in} is defined to have the inverse truth value of
@ref{323,,in}.

@geindex operator;is
@geindex operator;is not
@geindex identity;test
@anchor{reference/expressions is}@anchor{324}
@node Identity comparisons,,Membership test operations,Comparisons
@anchor{reference/expressions identity-comparisons}@anchor{26cd}@anchor{reference/expressions is-not}@anchor{26ce}
@subsubsection Identity comparisons


The operators @ref{324,,is} and @ref{26ce,,is not} test for an object’s identity: @code{x
is y} is true if and only if `x' and `y' are the same object.  An Object’s identity
is determined using the @ref{17c5,,id()} function.  @code{x is not y} yields the inverse
truth value. @footnote{
Due to automatic garbage-collection, free lists, and the dynamic nature of
descriptors, you may notice seemingly unusual behaviour in certain uses of
the @ref{324,,is} operator, like those involving comparisons between instance
methods, or constants.  Check their documentation for more info.
}
@anchor{reference/expressions booleans}@anchor{26cf}@anchor{reference/expressions and}@anchor{31f}@anchor{reference/expressions or}@anchor{325}
@node Boolean operations,Assignment expressions<2>,Comparisons,Expressions
@anchor{reference/expressions boolean-operations}@anchor{26d0}@anchor{reference/expressions not}@anchor{26d1}
@subsection Boolean operations


@geindex Conditional;expression
@geindex Boolean;operation

@example
@anchor{reference/expressions grammar-token-python-grammar-or_test}@anchor{2680}or_test:  @ref{26d2,,and_test} | @ref{2680,,or_test} "or" @ref{26d2,,and_test}
@anchor{reference/expressions grammar-token-python-grammar-and_test}@anchor{26d2}and_test: @ref{26d3,,not_test} | @ref{26d2,,and_test} "and" @ref{26d3,,not_test}
@anchor{reference/expressions grammar-token-python-grammar-not_test}@anchor{26d3}not_test: @ref{26c9,,comparison} | "not" @ref{26d3,,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{167a,,__bool__()} method.

@geindex operator;not

The operator @ref{26d1,,not} yields @code{True} if its argument is false, @code{False}
otherwise.

@geindex operator;and

The expression @code{x and y} first evaluates `x'; if `x' is false, its value is
returned; otherwise, `y' is evaluated and the resulting value is returned.

@geindex operator;or

The expression @code{x or y} first evaluates `x'; if `x' is true, its value is
returned; otherwise, `y' is evaluated and the resulting value is returned.

Note that neither @ref{31f,,and} nor @ref{325,,or} restrict the value and type
they return to @code{False} and @code{True}, but rather return the last evaluated
argument.  This is sometimes useful, e.g., if @code{s} is a string that should be
replaced by a default value if it is empty, the expression @code{s or 'foo'} yields
the desired value.  Because @ref{26d1,,not} has to create a new value, it
returns a boolean value regardless of the type of its argument
(for example, @code{not 'foo'} produces @code{False} rather than @code{'@w{'}}.)

@geindex ;= (colon equals)
@geindex assignment expression
@geindex walrus operator
@geindex named expression
@geindex assignment;expression

@node Assignment expressions<2>,Conditional expressions,Boolean operations,Expressions
@anchor{reference/expressions assignment-expressions}@anchor{26d4}@anchor{reference/expressions id14}@anchor{26d5}
@subsection Assignment expressions


@example
@anchor{reference/expressions grammar-token-python-grammar-assignment_expression}@anchor{2623}assignment_expression: [@ref{24b2,,identifier} ":="] @ref{42a,,expression}
@end example

An assignment expression (sometimes also called a «named expression» or
«walrus») assigns an @ref{42a,,expression} to an
@ref{24b2,,identifier}, while also returning the value of the
@code{expression}.

One common use case is when handling matched regular expressions:

@example
if matching := pattern.search(data):
    do_something(matching)
@end example

Or, when processing a file stream in chunks:

@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.


Added in version 3.8: See 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/} for more details about assignment expressions.


@node Conditional expressions,Lambdas,Assignment expressions<2>,Expressions
@anchor{reference/expressions conditional-expressions}@anchor{26d6}@anchor{reference/expressions if-expr}@anchor{426}
@subsection Conditional expressions


@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{24f2}conditional_expression: @ref{2680,,or_test} ["if" @ref{2680,,or_test} "else" @ref{42a,,expression}]
@anchor{reference/expressions grammar-token-python-grammar-expression}@anchor{42a}expression:             @ref{24f2,,conditional_expression} | @ref{26d7,,lambda_expr}
@end example

A conditional expression (sometimes called a «ternary operator») is an
alternative to the if-else statement. As it is an expression, it returns a value
and can appear as a sub-expression.

The expression @code{x if C else y} first evaluates the condition, `C' rather than `x'.
If `C' is true, `x' is evaluated and its value is returned; otherwise, `y' is
evaluated and its value is returned.

See 
@geindex Python Enhancement Proposals; PEP 308
PEP 308@footnote{https://peps.python.org/pep-0308/} for more details about conditional expressions.
@anchor{reference/expressions lambdas}@anchor{26d8}
@node Lambdas,Expression lists,Conditional expressions,Expressions
@anchor{reference/expressions id15}@anchor{26d9}@anchor{reference/expressions lambda}@anchor{1642}
@subsection Lambdas


@geindex lambda;expression
@geindex lambda;form
@geindex anonymous;function
@geindex ; (colon);lambda expression

@example
@anchor{reference/expressions grammar-token-python-grammar-lambda_expr}@anchor{26d7}lambda_expr: "lambda" [@ref{26da,,parameter_list}] ":" @ref{42a,,expression}
@end example

Lambda expressions (sometimes called lambda forms) are used to create anonymous
functions. The expression @code{lambda parameters: expression} yields a function
object.  The unnamed object behaves like a function object defined with:

@example
def <lambda>(parameters):
    return expression
@end example

See section @ref{2206,,Function definitions} for the syntax of parameter lists.  Note that
functions created with lambda expressions cannot contain statements or
annotations.

@node Expression lists,Evaluation order,Lambdas,Expressions
@anchor{reference/expressions expression-lists}@anchor{26db}@anchor{reference/expressions exprlists}@anchor{1137}
@subsection Expression lists


@geindex expression;list
@geindex @comma{} (comma);expression list

@example
@anchor{reference/expressions grammar-token-python-grammar-starred_expression}@anchor{267a}starred_expression:       "*" @ref{24f3,,or_expr} | @ref{42a,,expression}
@anchor{reference/expressions grammar-token-python-grammar-flexible_expression}@anchor{267d}flexible_expression:      @ref{2623,,assignment_expression} | @ref{267a,,starred_expression}
@anchor{reference/expressions grammar-token-python-grammar-flexible_expression_list}@anchor{2685}flexible_expression_list: @ref{267d,,flexible_expression} ("," @ref{267d,,flexible_expression})* [","]
@anchor{reference/expressions grammar-token-python-grammar-starred_expression_list}@anchor{26dc}starred_expression_list:  @ref{267a,,starred_expression} ("," @ref{267a,,starred_expression})* [","]
@anchor{reference/expressions grammar-token-python-grammar-expression_list}@anchor{26dd}expression_list:          @ref{42a,,expression} ("," @ref{42a,,expression})* [","]
@anchor{reference/expressions grammar-token-python-grammar-yield_list}@anchor{2691}yield_list:               @ref{26dd,,expression_list} | @ref{267a,,starred_expression} "," [@ref{26dc,,starred_expression_list}]
@end example

@geindex object;tuple

Except when part of a list or set display, an expression list
containing at least one comma yields a tuple.  The length of
the tuple is the number of expressions in the list.  The expressions are
evaluated from left to right.

@geindex iterable;unpacking
@geindex * (asterisk);in expression lists

An asterisk @code{*} denotes `iterable unpacking'.  Its operand must be
an @ref{15ce,,iterable}.  The iterable is expanded into a sequence of items,
which are included in the new tuple, list, or set, at the site of
the unpacking.


Added in version 3.5: Iterable unpacking in expression lists, originally proposed by 
@geindex Python Enhancement Proposals; PEP 448
PEP 448@footnote{https://peps.python.org/pep-0448/}.



Added in 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 Evaluation order,Operator precedence,Expression lists,Expressions
@anchor{reference/expressions evalorder}@anchor{26de}@anchor{reference/expressions evaluation-order}@anchor{26df}
@subsection Evaluation order


@geindex evaluation;order

Python evaluates expressions from left to right.  Notice that while evaluating
an assignment, the right-hand side is evaluated before the left-hand side.

In the following lines, expressions will be evaluated in the arithmetic order of
their 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 Operator precedence,,Evaluation order,Expressions
@anchor{reference/expressions operator-precedence}@anchor{26e0}@anchor{reference/expressions operator-summary}@anchor{26e1}
@subsection Operator precedence


@geindex operator;precedence

The following table summarizes the operator precedence in Python, from highest
precedence (most binding) to lowest precedence (least binding).  Operators in
the same box have the same precedence.  Unless the syntax is explicitly given,
operators are binary.  Operators in the same box group left to right (except for
exponentiation and conditional expressions, which group from right to left).

Note that comparisons, membership tests, and identity tests, all have the same
precedence and have a left-to-right chaining feature as described in the
@ref{26c7,,Comparisons} section.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Operator

@tab

Description

@item

@code{(expressions...)},

@code{[expressions...]},
@code{@{key: value...@}},
@code{@{expressions...@}}

@tab

Binding or parenthesized
expression,
list display,
dictionary display,
set display

@item

@code{x[index]}, @code{x[index:index]}
@code{x(arguments...)}, @code{x.attribute}

@tab

Subscription (including slicing),
call, attribute reference

@item

@ref{432,,await x}

@tab

Await expression

@item

@code{**}

@tab

Exponentiation @footnote{
The power operator @code{**} binds less tightly than an arithmetic or
bitwise unary operator on its right, that is, @code{2**-1} is @code{0.5}.
}

@item

@code{+x}, @code{-x}, @code{~x}

@tab

Positive, negative, bitwise NOT

@item

@code{*}, @code{@@}, @code{/}, @code{//}, @code{%}

@tab

Multiplication, matrix
multiplication, division, floor
division, remainder @footnote{
The @code{%} operator is also used for string formatting; the same
precedence applies.
}

@item

@code{+}, @code{-}

@tab

Addition and subtraction

@item

@code{<<}, @code{>>}

@tab

Shifts

@item

@code{&}

@tab

Bitwise AND

@item

@code{^}

@tab

Bitwise XOR

@item

@code{|}

@tab

Bitwise OR

@item

@ref{323,,in}, @ref{a20,,not in},
@ref{324,,is}, @ref{26ce,,is not}, @code{<},
@code{<=}, @code{>}, @code{>=}, @code{!=}, @code{==}

@tab

Comparisons, including membership
tests and identity tests

@item

@ref{26d1,,not x}

@tab

Boolean NOT

@item

@ref{31f,,and}

@tab

Boolean AND

@item

@ref{325,,or}

@tab

Boolean OR

@item

@ref{426,,if} – @code{else}

@tab

Conditional expression

@item

@ref{1642,,lambda}

@tab

Lambda expression

@item

@code{:=}

@tab

Assignment expression

@end multitable


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Απλές εντολές,Compound statements,Expressions,Εγχειρίδιο Αναφοράς της Γλώσσας Python
@anchor{reference/simple_stmts doc}@anchor{26e2}@anchor{reference/simple_stmts simple}@anchor{26e3}@anchor{reference/simple_stmts simple-statements}@anchor{26e4}@anchor{reference/simple_stmts translation-repo}@anchor{26e5}
@section Απλές εντολές


@geindex απλό;δήλωση

Μια απλή εντολή περιλαμβάνεται σε μία μόνο λογική γραμμή. Πολλές απλές εντολές μπορεί να εμφανιστούν σε μία μόνο γραμμή χωρισμένες με ελληνικό ερωτηματικό. Η σύνταξη για απλές εντολές είναι:

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-simple_stmt}@anchor{26e6}simple_stmt: @ref{26e7,,expression_stmt}
             | @ref{26e8,,assert_stmt}
             | @ref{26e9,,assignment_stmt}
             | @ref{26ea,,augmented_assignment_stmt}
             | @ref{26eb,,annotated_assignment_stmt}
             | @ref{26ec,,pass_stmt}
             | @ref{26ed,,del_stmt}
             | @ref{26ee,,return_stmt}
             | @ref{26ef,,yield_stmt}
             | @ref{26f0,,raise_stmt}
             | @ref{26f1,,break_stmt}
             | @ref{26f2,,continue_stmt}
             | @ref{26f3,,import_stmt}
             | @ref{26f4,,future_stmt}
             | @ref{26f5,,global_stmt}
             | @ref{26f6,,nonlocal_stmt}
             | @ref{26f7,,type_stmt}
@end example

@menu
* Εντολές έκφρασης:: 
* Εντολές ανάθεσης:: 
* Η εντολή assert:: 
* Η έκφραση pass:: 
* Η εντολή del:: 
* Η εντολή return:: 
* Η εντολή yield:: 
* Η εντολή raise:: 
* Η εντολή break:: 
* Η εντολή continue:: 
* Η εντολή import:: 
* Η εντολή global:: 
* Η εντολή nonlocal:: 
* Η εντολή type:: 

@end menu

@node Εντολές έκφρασης,Εντολές ανάθεσης,,Απλές εντολές
@anchor{reference/simple_stmts expression-statements}@anchor{26f8}@anchor{reference/simple_stmts exprstmts}@anchor{26f9}
@subsection Εντολές έκφρασης


@geindex έκφραση;δήλωση
@geindex έκφραση;λίστα

@geindex έκφραση;λίστα

Οι εντολές έκφρασης χρησιμοποιούνται (κυρίως διαδραστικά) για τον υπολογισμό και την εγγραφή μιας τιμής, ή (συνήθως) για την κλήση μιας διαδικασίας (μια συνάρτηση που δεν επιστρέφει ουσιαστικό αποτέλεσμα· στην Python, οι διαδικασίες επιστρέφουν την τιμή @code{None}). Άλλες χρήσεις εντολών έκφρασης επιτρέπονται και είναι περιστασιακά χρήσιμες. Η σύνταξη μιας εντολή έκφρασης είναι:

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-expression_stmt}@anchor{26e7}expression_stmt: @ref{267a,,starred_expression}
@end example

Μια εντολή έκφρασης αξιολογεί τη λίστα εκφράσεων (που μπορεί να είναι μία μόνο έκφραση).

@geindex ενσωματωμένη συνάρτηση;repr
@geindex αντικείμενο;Κανένα
@geindex συμβολοσειρά;μετατροπή
@geindex έξοδος
@geindex πρότυπο;έξοδος
@geindex εγγραφή;τιμές
@geindex διαδικασία;κλήση

Σε διαδραστική λειτουργία, εάν η τιμή δεν είναι @code{None}, μετατρέπεται σε συμβολοσειρά χρησιμοποιώντας την ενσωματωμένη συνάρτηση @ref{45b,,repr()} και η προκύπτουσα συμβολοσειρά γράφεται στην τυπική έξοδο σε μια γραμμή από μόνη της (εκτός εάν το αποτέλεσμα είναι @code{None}, έτσι ώστε οι κλήσεις διαδικασίας να μην προκαλούν καμία έξοδο.)

@node Εντολές ανάθεσης,Η εντολή assert,Εντολές έκφρασης,Απλές εντολές
@anchor{reference/simple_stmts assignment}@anchor{261d}@anchor{reference/simple_stmts assignment-statements}@anchor{26fa}
@subsection Εντολές ανάθεσης


@geindex = (ισούται);εντολή ανάθεσης
@geindex ανάθεση;δήλωση
@geindex δέσμευση;όνομα
@geindex επαναδέσμευση;όνομα
@geindex αντικείμενο;μεταβλητός
@geindex χαρακτηριστικό;ανάθεση

Οι εντολές ανάθεσης χρησιμοποιούνται για την (επανα)δέσμευση ονομάτων σε τιμές και για την τροποποίηση χαρακτηριστικών ή στοιχείων μεταβλητών αντικειμένων:

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-assignment_stmt}@anchor{26e9}assignment_stmt: (@ref{267f,,target_list} "=")+ (@ref{267a,,starred_expression} | @ref{24f4,,yield_expression})
@anchor{reference/simple_stmts grammar-token-python-grammar-target_list}@anchor{267f}target_list:     @ref{26fb,,target} ("," @ref{26fb,,target})* [","]
@anchor{reference/simple_stmts grammar-token-python-grammar-target}@anchor{26fb}target:          @ref{24b2,,identifier}
                 | "(" [@ref{267f,,target_list}] ")"
                 | "[" [@ref{267f,,target_list}] "]"
                 | @ref{269d,,attributeref}
                 | @ref{269e,,subscription}
                 | "*" @ref{26fb,,target}
@end example

(See section @ref{269b,,Primaries} for the syntax definitions for `attributeref'
and `subscription'.)

Μια εντολή ανάθεσης αξιολογεί τη λίστα εκφράσεων (θυμηθείτε ότι αυτή μπορεί να είναι μια μεμονωμένη έκφραση ή μια λίστα διαχωρισμένη με κόμματα, με την τελευταία να αποδίδει μια πλειάδα) και αναθέτει το μεμονωμένο αντικείμενο που προκύπτει σε καθεμία από τις λίστες προορισμού, από τα αριστερά προς τα δεξιά.

@geindex στόχος
@geindex στόχος;λίστα

Assignment is defined recursively depending on the form of the target (list).
When a target is part of a mutable object (an attribute reference or
subscription), the mutable object must ultimately perform the assignment and
decide about its validity, and may raise an exception if the assignment is
unacceptable.  The rules observed by various types and the exceptions raised are
given with the definition of the object types (see section @ref{2520,,Η τυπική ιεραρχία τύπου}).

@geindex στόχος;λίστα;ανάθεση
@geindex @comma{} (κόμμα);στη λίστα προορισμού
@geindex * (αστερίσκος);στη λίστα προορισμού ανάθεσης
@geindex [] (αγκύλες);στη λίστα προορισμού ανάθεσης
@geindex () (παρενθέσεις);στη λίστα προορισμού ανάθεσης

Η ανάθεση ενός αντικειμένου σε μια λίστα προορισμού, προαιρετικά περικλεισμένη σε παρενθέσεις ή αγκύλες, ορίζεται αναδρομικά ως εξής.


@itemize *

@item 
Εάν η λίστα προορισμού είναι ένας μεμονωμένος στόχος χωρίς τελικό κόμμα, προαιρετικά σε παρενθέσεις, το αντικείμενο ανατίθεται σε αυτόν τον στόχο.

@item 
Διαφορετικά:


@itemize *

@item 
Εάν η λίστα προορισμού περιέχει έναν στόχο με πρόθεμα έναν αστερίσκο, που ονομάζεται «στόχος με αστερίσκο»: Το αντικείμενο πρέπει να είναι ένα iterable με τουλάχιστον τόσα στοιχεία όσα και οι στόχοι στη λίστα προορισμού, μείον ένα. Τα πρώτα στοιχεία του iterable ανατίθενται, από αριστερά προς τα δεξιά, στους στόχους πριν από τον στόχο με αστερίσκο. Τα τελικά στοιχεία του iterable ανατίθενται στους στόχους μετά τον στόχο με αστερίσκο. Μια λίστα με τα υπολειπόμενα στοιχεία του iterable ανατίθεται στη συνέχεια στον στόχο με αστερίσκο (η λίστα μπορεί να είναι κενή).

@item 
Διαφορετικά: Το αντικείμενο πρέπει να είναι ένα iterable με τον ίδιο αριθμό στοιχείων με τους στόχους στη λίστα προορισμού και τα στοιχεία ανατίθενται, από αριστερά προς τα δεξιά, στους αντίστοιχους στόχους.
@end itemize
@end itemize

Η ανάθεση ενός αντικειμένου σε έναν μεμονωμένο στόχο ορίζεται αναδρομικά ως εξής.


@itemize *

@item 
Εάν ο στόχος είναι ένα αναγνωριστικό (όνομα):


@itemize *

@item 
Εάν το όνομα δεν εμφανίζεται σε μια εντολή @ref{6b5,,global} ή @ref{164c,,nonlocal} στο τρέχον μπλοκ κώδικα: το όνομα δεσμεύεται στο αντικείμενο στον τρέχον τοπικό namespace.

@item 
Διαφορετικά: το όνομα δεσμεύεται στο αντικείμενο στο καθολικό namespace ή στο εξωτερικό namespace που καθορίζεται από το @ref{164c,,nonlocal}, αντίστοιχα.
@end itemize

@geindex καταστροφέας

Το όνομα επαναδεσμεύεται εάν ήταν ήδη δεσμευμένο. Αυτό μπορεί να προκαλέσει ο μετρητής αναφοράς για το αντικείμενο, που είχε προηγουμένως δεσμευτεί στο όνομα, να φτάσει στο μηδέν, προκαλώντας την απελευθέρωση του αντικειμένου και την κλήση του καταστροφέα του (εάν έχει).

@geindex χαρακτηριστικό;ανάθεση

@item 
Εάν ο στόχος είναι μια αναφορά χαρακτηριστικού: Η κύρια έκφραση στην αναφορά αξιολογείται. Θα πρέπει να αποδώσει ένα αντικείμενο με εκχωρήσιμα χαρακτηριστικά· εάν αυτό δεν συμβαίνει, προκαλείται @ref{291,,TypeError}. Στη συνέχεια, ζητείται από αυτό το αντικείμενο να αναθέσει το εκχωρημένο αντικείμενο στο δεδομένο χαρακτηριστικό· εάν δεν μπορεί να εκτελέσει την ανάθεση, προκαλεί μια εξαίρεση (συνήθως αλλά όχι απαραίτητα @ref{1a9,,AttributeError}).
@anchor{reference/simple_stmts attr-target-note}@anchor{26fc}
Σημείωση: Εάν το αντικείμενο είναι ένα στιγμιότυπο κλάσης και η αναφορά χαρακτηριστικού εμφανίζεται και στις δύο πλευρές του τελεστή ανάθεσης, η έκφραση στη δεξιά πλευρά, @code{a.x} μπορεί να έχει πρόσβαση είτε σε ένα χαρακτηριστικό στιγμιοτύπου είτε (εάν δεν υπάρχει χαρακτηριστικό στιγμιοτύπου) σε ένα χαρακτηριστικό κλάσης. Ο στόχος της αριστερής πλευράς @code{a.x} ορίζεται πάντα ως χαρακτηριστικό στιγμιοτύπου, δημιουργώντας το εάν είναι απαραίτητο. Έτσι, οι δύο εμφανίσεις του @code{a.x} δεν αναφέρονται απαραίτητα στο ίδιο χαρακτηριστικό: εάν η έκφραση στη δεξιά πλευρά αναφέρεται σε ένα χαρακτηριστικό κλάσης, η αριστερή πλευρά δημιουργεί ένα νέο χαρακτηριστικό στιγμιοτύπου ως στόχο της ανάθεσης:

@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

Αυτή η περιγραφή δεν ισχύει απαραίτητα για τα χαρακτηριστικά περιγραφέων, όπως οι ιδιότητες που δημιουργήθηκαν με το @ref{6bb,,property()}.

@geindex συνδρομή;ανάθεση
@geindex αντικείμενο;μεταβλητός

@item 
If the target is a subscription: The primary expression in the reference is
evaluated.
Next, the subscript expression is evaluated.
Then, the primary’s @ref{1670,,__setitem__()} method is called with
two arguments: the subscript and the assigned object.

Typically, @ref{1670,,__setitem__()} is defined on mutable sequence objects
(such as lists) and mapping objects (such as dictionaries), and behaves as
follows.

@geindex αντικείμενο;ακολουθία
@geindex αντικείμενο;λίστα

Εάν το πρωτεύον είναι ένα μεταβλητό αντικείμενο ακολουθίας (όπως μια λίστα), ο δείκτης πρέπει να αποδώσει έναν ακέραιο αριθμό. Εάν είναι αρνητικός, προστίθεται σε αυτόν το μήκος της ακολουθίας. Η προκύπτουσα τιμή πρέπει να είναι ένας μη αρνητικός ακέραιος μικρότερος από το μήκος της ακολουθίας και ζητείται από την ακολουθία να αναθέσει το εκχωρημένο αντικείμενο στο στοιχείο της με αυτόν τον δείκτη. Εάν ο δείκτης είναι εκτός εμβέλειας, γίνεται raise η @ref{18d7,,IndexError} (η ανάθεση σε μια ακολουθία με δείκτη δεν μπορεί να προσθέσει νέα στοιχεία σε μια λίστα).

@geindex αντικείμενο;χαρτογράφηση
@geindex αντικείμενο;λεξικό

Εάν το πρωτεύον είναι ένα αντικείμενο αντιστοίχισης (όπως ένα λεξικό), ο δείκτης πρέπει να έχει έναν τύπο συμβατό με τον τύπο κλειδιού της αντιστοίχισης και στη συνέχεια ζητείται από την αντιστοίχιση να δημιουργήσει ένα ζεύγος κλειδιού/τιμής που αντιστοιχίζει τον δείκτη στο εκχωρημένο αντικείμενο. Αυτό μπορεί είτε να αντικαταστήσει ένα υπάρχον ζεύγος κλειδιού/τιμής με την ίδια τιμή κλειδιού, είτε να εισαγάγει ένα νέο ζεύγος κλειδιού/τιμής (εάν δεν υπήρχε κλειδί με την ίδια τιμή).

@geindex τεμαχισμός;ανάθεση

If the target is a slicing: The primary expression should evaluate to
a mutable sequence object (such as a list).
The assigned object should be @ref{15ce,,iterable}.
The slicing’s lower and upper bounds should be integers; if they are @code{None}
(or not present), the defaults are zero and the sequence’s length.
If either bound is negative, the sequence’s length is added to it.  The
resulting bounds are clipped to lie between zero and the sequence’s length,
inclusive.  Finally, the sequence object is asked to replace the slice with
the items of the assigned sequence.  The length of the slice may be different
from the length of the assigned sequence, thus changing the length of the
target sequence, if the target sequence allows it.
@end itemize

Αν και ο ορισμός της ανάθεσης υπονοεί ότι οι επικαλύψεις μεταξύ της αριστερής και της δεξιάς πλευράς είναι «ταυτόχρονες» (για παράδειγμα, το @code{a, b = b, a} εναλλάσσει δύο μεταβλητές), οι επικαλύψεις `μέσα' στη συλλογή των μεταβλητών στις οποίες γίνεται ανάθεση συμβαίνουν από αριστερά προς τα δεξιά, προκαλώντας μερικές φορές σύγχυση. Για παράδειγμα, το ακόλουθο πρόγραμμα εκτυπώνει @code{[0, 2]}:

@example
x = [0, 1]
i = 0
i, x[i] = 1, 2 # το i ενημερώνεται, και στη συνέχεια ενημερώνεται το x[i]
print(x)
@end example


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 3132

@item PEP 3132@footnote{https://peps.python.org/pep-3132/} - Εκτεταμένη αποσυμπίεση επαναλαμβανόμενων

Η προδιαγραφή για τη δυνατότητα @code{*target}.
@end table


@menu
* Επαυξημένες εντολές ανάθεσης:: 
* Εντολές ανάθεσης με σχολιασμό:: 

@end menu

@node Επαυξημένες εντολές ανάθεσης,Εντολές ανάθεσης με σχολιασμό,,Εντολές ανάθεσης
@anchor{reference/simple_stmts augassign}@anchor{26fd}@anchor{reference/simple_stmts augmented-assignment-statements}@anchor{26fe}
@subsubsection Επαυξημένες εντολές ανάθεσης


@geindex επαυξημένος;ανάθεση
@geindex δήλωση;ανάθεση@comma{} επαυξημένη
@geindex +=;επαυξημένη ανάθεση
@geindex -=;επαυξημένη ανάθεση
@geindex *=;επαυξημένη ανάθεση
@geindex /=;επαυξημένη ανάθεση
@geindex %=;επαυξημένη ανάθεση
@geindex &=;επαυξημένη ανάθεση
@geindex ^=;επαυξημένη ανάθεση
@geindex |=;επαυξημένη ανάθεση
@geindex **=;επαυξημένη ανάθεση
@geindex //=;επαυξημένη ανάθεση
@geindex >>=;επαυξημένη ανάθεση
@geindex <<=;επαυξημένη ανάθεση

Η επαυξημένη ανάθεση είναι ο συνδυασμός, σε μία μόνο εντολή, μιας δυαδικής λειτουργίας και μιας εντολής ανάθεσης:

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-augmented_assignment_stmt}@anchor{26ea}augmented_assignment_stmt: @ref{26ff,,augtarget} @ref{2700,,augop} (@ref{26dd,,expression_list} | @ref{24f4,,yield_expression})
@anchor{reference/simple_stmts grammar-token-python-grammar-augtarget}@anchor{26ff}augtarget:                 @ref{24b2,,identifier} | @ref{269d,,attributeref} | @ref{269e,,subscription}
@anchor{reference/simple_stmts grammar-token-python-grammar-augop}@anchor{2700}augop:                     "+=" | "-=" | "*=" | "@@=" | "/=" | "//=" | "%=" | "**="
                           | ">>=" | "<<=" | "&=" | "^=" | "|="
@end example

(Ανατρέξτε στην ενότητα @ref{269b,,Primaries} για τους ορισμούς σύνταξης των τριών τελευταίων συμβόλων.)

Μια επαυξημένη ανάθεση αξιολογεί τον στόχο (ο οποίος, σε αντίθεση με τις κανονικές εντολές ανάθεσης, δεν μπορεί να είναι αποσυμπίεση) και τη λίστα εκφράσεων, εκτελεί τη δυαδική λειτουργία που είναι συγκεκριμένη για τον τύπο ανάθεσης στους δύο τελεστές και αναθέτει το αποτέλεσμα στον αρχικό στόχο. Ο στόχος αξιολογείται μόνο μία φορά.

Μια επαυξημένη εντολή ανάθεσης όπως @code{x += 1} μπορεί να ξαναγραφτεί ως @code{x = x + 1} για να επιτευχθεί ένα παρόμοιο, αλλά όχι ακριβώς ίσο αποτέλεσμα. Στην επαυξημένη έκδοση, το @code{x} αξιολογείται μόνο μία φορά. Επίσης, όταν είναι δυνατό, η πραγματική λειτουργία εκτελείται `επί τόπου', πράγμα που σημαίνει ότι αντί να δημιουργηθεί ένα νέο αντικείμενο και να ανατεθεί αυτό στον στόχο, το παλιό αντικείμενο τροποποιείται αντ” αυτού.

Σε αντίθεση με τις κανονικές αναθέσεις, οι επαυξημένες αναθέσεις αξιολογούν την αριστερή πλευρά `πριν' αξιολογήσουν τη δεξιά πλευρά. Για παράδειγμα, το @code{a[i] += f(x)} πρώτα αναζητά το @code{a[i]}, στη συνέχεια αξιολογεί το @code{f(x)} και εκτελεί την πρόσθεση, και τέλος, γράφει το αποτέλεσμα πίσω στο @code{a[i]}.

Με εξαίρεση την ανάθεση σε πλειάδες και πολλαπλούς στόχους σε μία μόνο εντολή, η ανάθεση που γίνεται από τις επαυξημένες εντολές ανάθεσης αντιμετωπίζεται με τον ίδιο τρόπο όπως οι κανονικές αναθέσεις. Ομοίως, με εξαίρεση την πιθανή συμπεριφορά `επί τόπου', η δυαδική λειτουργία που εκτελείται από την επαυξημένη ανάθεση είναι η ίδια με τις κανονικές δυαδικές λειτουργίες.

Για στόχους που είναι αναφορές χαρακτηριστικών, ισχύει η ίδια @ref{26fc,,caveat σχετικά με τα χαρακτηριστικά κλάσης και εμφάνισης} όπως και για τις κανονικές αναθέσεις.

@node Εντολές ανάθεσης με σχολιασμό,,Επαυξημένες εντολές ανάθεσης,Εντολές ανάθεσης
@anchor{reference/simple_stmts annassign}@anchor{2701}@anchor{reference/simple_stmts annotated-assignment-statements}@anchor{2702}
@subsubsection Εντολές ανάθεσης με σχολιασμό


@geindex σχολιασμένο;ανάθεση
@geindex δήλωση;ανάθεση@comma{} σχολιασμένη
@geindex ; (άνω και κάτω τελεία);σχολιασμένη μεταβλητή

Η ανάθεση @ref{110a,,Σχολιασμός} είναι ο συνδυασμός, σε μία μόνο εντολή, ενός σχολιασμού μεταβλητής ή χαρακτηριστικού και μιας προαιρετικής εντολής ανάθεσης:

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-annotated_assignment_stmt}@anchor{26eb}annotated_assignment_stmt: @ref{26ff,,augtarget} ":" @ref{42a,,expression}
                           ["=" (@ref{267a,,starred_expression} | @ref{24f4,,yield_expression})]
@end example

Η διαφορά από την κανονική @ref{261d,,Εντολές ανάθεσης} είναι ότι επιτρέπεται μόνο ένας στόχος.

Ο στόχος ανάθεσης θεωρείται «απλός» εάν αποτελείται από ένα μόνο όνομα που δεν περικλείεται σε παρενθέσεις. Για απλούς στόχους ανάθεσης, εάν βρίσκονται σε εμβέλεια κλάσης ή module, οι σχολιασμοί συγκεντρώνονται σε ένα @ref{6b4,,εύρος σχολιασμού} που αξιολογείται με καθυστέρηση. Οι σχολιασμοί μπορούν να αξιολογηθούν χρησιμοποιώντας το χαρακτηριστικό @ref{66b,,__annotations__} μιας κλάσης ή module ή χρησιμοποιώντας τις διευκολύνσεις στο module @ref{6,,annotationlib}.

Εάν ο στόχος ανάθεσης δεν είναι απλός (ένα χαρακτηριστικό, ένας κόμβος δείκτη ή ένα όνομα σε παρένθεση), ο σχολιασμός δεν αξιολογείται ποτέ.

Εάν ένα όνομα σχολιαστεί σε ένα εύρος συνάρτησης, τότε αυτό το όνομα είναι τοπικό γι’ αυτό το εύρος. Οι σχολιασμοί δεν αξιολογούνται και δεν αποθηκεύονται ποτέ σε εύρη συναρτήσεων.

Εάν υπάρχει η δεξιά πλευρά, μια σχολιασμένη ανάθεση εκτελεί την πραγματική ανάθεση σαν να μην υπήρχε σχολιασμός. Εάν η δεξιά πλευρά δεν υπάρχει για έναν στόχο έκφρασης, τότε ο διερμηνέας αξιολογεί τον στόχο εκτός από την τελευταία κλήση @ref{1670,,__setitem__()} ή @ref{256d,,__setattr__()}.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 526

@item PEP 526@footnote{https://peps.python.org/pep-0526/} - Σύνταξη για σχολιασμούς μεταβλητών

Η πρόταση που πρόσθεσε σύνταξη για τον σχολιασμό των τύπων των μεταβλητών (συμπεριλαμβανομένων των μεταβλητών κλάσης και των μεταβλητών εμφάνισης), αντί να τις εκφράζει μέσω σχολίων.

@geindex Python Enhancement Proposals; PEP 484

@item PEP 484@footnote{https://peps.python.org/pep-0484/} - Υποδείξεις τύπων

Η πρόταση που πρόσθεσε το module @ref{10d,,typing} για να παρέχει μια τυπική σύνταξη για σχολιασμούς τύπων που μπορούν να χρησιμοποιηθούν σε εργαλεία στατικής ανάλυσης και IDE.
@end table



Άλλαξε στην έκδοση 3.8: Πλέον, οι σχολιασμένες αναθέσεις επιτρέπουν τις ίδιες εκφράσεις στη δεξιά πλευρά με τις κανονικές αναθέσεις. Προηγουμένως, ορισμένες εκφράσεις (όπως οι εκφράσεις πλειάδας χωρίς παρενθέσεις) προκαλούσαν σφάλμα σύνταξης.



Άλλαξε στην έκδοση 3.14: Οι σχολιασμοί αξιολογούνται πλέον νωχελικά σε ένα ξεχωριστό @ref{6b4,,εύρος σχολιασμού}. Εάν ο στόχος της ανάθεσης δεν είναι απλός, οι σχολιασμοί δεν αξιολογούνται ποτέ.


@node Η εντολή assert,Η έκφραση pass,Εντολές ανάθεσης,Απλές εντολές
@anchor{reference/simple_stmts assert}@anchor{d31}@anchor{reference/simple_stmts the-assert-statement}@anchor{2703}
@subsection Η εντολή @code{assert}


@geindex δήλωση;assert
@geindex εντοπισμός σφαλμάτων;assertions
@geindex @comma{} (κόμμα);λίστα εκφράσεων

Οι εντολές @cite{assert} είναι ένας βολικός τρόπος για την εισαγωγή ισχυρισμών εντοπισμού σφαλμάτων σε ένα πρόγραμμα:

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-assert_stmt}@anchor{26e8}assert_stmt: "assert" @ref{42a,,expression} ["," @ref{42a,,expression}]
@end example

Η απλή μορφή, @code{assert expression}, είναι ισοδύναμη με

@example
if __debug__:
    if not expression: raise AssertionError
@end example

Η εκτεταμένη μορφή, @code{assert expression1, expression2}, είναι ισοδύναμη με

@example
if __debug__:
    if not expression1: raise AssertionError(expression2)
@end example

@geindex __debug__
@geindex εξαίρεση;AssertionError

Αυτές οι ισοδυναμίες υποθέτουν ότι οι @ref{bb7,,__debug__} και @ref{a97,,AssertionError} αναφέρονται στις ενσωματωμένες μεταβλητές με αυτά τα ονόματα. Στην τρέχουσα υλοποίηση, η ενσωματωμένη μεταβλητή @code{__debug__} είναι @code{True} υπό κανονικές συνθήκες, @code{False} όταν ζητείται βελτιστοποίηση (επιλογή γραμμής εντολών @ref{431,,-O}). Ο τρέχων γεννήτορας κώδικα δεν εκπέμπει κώδικα για μια εντολή @ref{d31,,assert} όταν ζητείται βελτιστοποίηση κατά τη μεταγλώττιση. Σημειώστε ότι δεν είναι απαραίτητο να συμπεριληφθεί ο πηγαίος κώδικας για την έκφραση που απέτυχε στο μήνυμα σφάλματος· θα εμφανιστεί ως μέρος της ανίχνευσης στοίβας.

Οι αναθέσεις στο @ref{bb7,,__debug__} είναι παράνομες. Η τιμή για την ενσωματωμένη μεταβλητή καθορίζεται κατά την έναρξη του διερμηνέα.

@node Η έκφραση pass,Η εντολή del,Η εντολή assert,Απλές εντολές
@anchor{reference/simple_stmts pass}@anchor{427}@anchor{reference/simple_stmts the-pass-statement}@anchor{2704}
@subsection Η έκφραση @code{pass}


@geindex δήλωση;pass
@geindex null;λειτουργία
@geindex null;λειτουργία

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-pass_stmt}@anchor{26ec}pass_stmt: "pass"
@end example

Η εντολή @ref{427,,pass} είναι μια κενή λειτουργία — όταν εκτελείται, δεν συμβαίνει τίποτα. Είναι χρήσιμη ως ένας placeholder όταν απαιτείται μια εντολή συντακτικά, αλλά δεν χρειάζεται να εκτελεστεί κώδικας, για παράδειγμα:

@example
def f(arg): pass    # μια συνάρτηση που δεν κάνει τίποτα (ακόμα)

class C: pass       # μια κλάση χωρίς μεθόδους (ακόμα)
@end example

@node Η εντολή del,Η εντολή return,Η έκφραση pass,Απλές εντολές
@anchor{reference/simple_stmts del}@anchor{1d1d}@anchor{reference/simple_stmts the-del-statement}@anchor{2705}
@subsection Η εντολή @code{del}


@geindex δήλωση;del
@geindex διαγραφή;στόχος
@geindex διαγραφή;στόχος;λίστα

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-del_stmt}@anchor{26ed}del_stmt: "del" @ref{267f,,target_list}
@end example

Η διαγραφή ορίζεται αναδρομικά με παρόμοιο τρόπο με τον τρόπο που ορίζεται η ανάθεση. Αντί να το εξηγήσουμε λεπτομερώς, εδώ είναι μερικές συμβουλές.

Η διαγραφή μιας λίστας προορισμού διαγράφει αναδρομικά κάθε στόχο, από τα αριστερά προς τα δεξιά.

@geindex δήλωση;global
@geindex αποδέσμευση;όνομα

Η διαγραφή ενός ονόματος καταργεί τη δέσμευση αυτού του ονόματος από το local ή το global namespace, ανάλογα με το αν το όνομα εμφανίζεται σε μια εντολή @ref{6b5,,global} στο ίδιο κομμάτι κώδικα. Η προσπάθεια διαγραφής ενός μη δεσμευμένου ονόματος κάνει raise μια εξαίρεση @ref{665,,NameError}.

@geindex χαρακτηριστικό;διαγραφή

Deletion of attribute references and subscriptions is passed to the
primary object involved; deletion of a slicing is in general equivalent to
assignment of an empty slice of the right type (but even this is determined by
the sliced object).


Άλλαξε στην έκδοση 3.2: Προηγουμένως, ήταν παράνομο να διαγραφεί ένα όνομα από το τοπικό namespace εάν εμφανίζεται ως ελεύθερη μεταβλητή σε ένα εμφωλευμένο μπλοκ.


@node Η εντολή return,Η εντολή yield,Η εντολή del,Απλές εντολές
@anchor{reference/simple_stmts return}@anchor{44b}@anchor{reference/simple_stmts the-return-statement}@anchor{2706}
@subsection Η εντολή @code{return}


@geindex δήλωση;επιστροφή
@geindex συνάρτηση;ορισμός
@geindex κλάση;ορισμός

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-return_stmt}@anchor{26ee}return_stmt: "return" [@ref{26dd,,expression_list}]
@end example

Η εντολή @ref{44b,,return} μπορεί να εμφανιστεί μόνο συντακτικά ενσωματωμένη σε έναν ορισμό συνάρτησης, όχι μέσα σε έναν εμφωλευμένο ορισμό κλάσης.

Εάν υπάρχει μια λίστα εκφράσεων, αξιολογείται, αλλιώς αντικαθίσταται με το @code{None}.

Η εντολή @ref{44b,,return} εξέρχεται από την τρέχουσα κλήση συνάρτησης με τη λίστα εκφράσεων (ή @code{None}) ως τιμή επιστροφής.

@geindex λέξη-κλειδί;finally

Όταν η εντολή @ref{44b,,return} μεταβιβάζει τον έλεγχο από μια εντολή @ref{ad6,,try} με μια ρήτρα @ref{44c,,finally}, αυτή η ρήτρα @code{finally} εκτελείται πριν από την πραγματική έξοδο από τη συνάρτηση.

Σε μια συνάρτηση generator, η εντολή @ref{44b,,return} υποδεικνύει ότι ο generator έχει ολοκληρωθεί και θα προκαλέσει την εξαίρεση @ref{fba,,StopIteration}. Η επιστρεφόμενη τιμή (εάν υπάρχει) χρησιμοποιείται ως όρισμα για την κατασκευή της @code{StopIteration} και γίνεται το χαρακτηριστικό @ref{260c,,StopIteration.value}.

Σε μια ασύγχρονη συνάρτηση generator, μια κενή εντολή @ref{44b,,return} υποδεικνύει ότι ο ασύγχρονος generator έχει ολοκληρωθεί και θα κάνει raise την εξαίρεση @ref{1ffe,,StopAsyncIteration}. Μια μη κενή εντολή @code{return} είναι συντακτικό σφάλμα σε μια ασύγχρονη συνάρτηση generator.

@node Η εντολή yield,Η εντολή raise,Η εντολή return,Απλές εντολές
@anchor{reference/simple_stmts the-yield-statement}@anchor{2707}@anchor{reference/simple_stmts yield}@anchor{d93}
@subsection Η εντολή @code{yield}


@geindex δήλωση;yield
@geindex generator;συνάρτηση
@geindex generator;iterator
@geindex συνάρτηση;generator
@geindex εξαίρεση;StopIteration

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-yield_stmt}@anchor{26ef}yield_stmt: @ref{24f4,,yield_expression}
@end example

Μια εντολή @ref{d93,,yield} είναι σημασιολογικά ισοδύναμη με μια @ref{268f,,yield expression}. Η εντολή @code{yield} μπορεί να χρησιμοποιηθεί για την παράλειψη των παρενθέσεων που διαφορετικά θα απαιτούνταν στην ισοδύναμη εντολή έκφρασης απόδοσης. Για παράδειγμα, οι εντολές απόδοσης

@example
yield <expr>
yield from <expr>
@end example

είναι ισοδύναμες με τις εντολές έκφρασης απόδοσης

@example
(yield <expr>)
(yield from <expr>)
@end example

Οι εκφράσεις και οι εντολές απόδοσης χρησιμοποιούνται μόνο κατά τον ορισμό μιας συνάρτησης @ref{1409,,generator} και χρησιμοποιούνται μόνο στο σώμα της συνάρτησης generator. Η χρήση της @ref{d93,,yield} σε έναν ορισμό συνάρτησης είναι αρκετή για να προκαλέσει αυτόν τον ορισμό να δημιουργήσει μια συνάρτηση generator αντί για μια κανονική συνάρτηση.

Για πλήρεις λεπτομέρειες της σημασιολογίας της @ref{d93,,yield}, ανατρέξτε στην ενότητα @ref{268f,,Yield expressions}.

@node Η εντολή raise,Η εντολή break,Η εντολή yield,Απλές εντολές
@anchor{reference/simple_stmts raise}@anchor{9e4}@anchor{reference/simple_stmts the-raise-statement}@anchor{2708}
@subsection Η εντολή @code{raise}


@geindex δήλωση;raise
@geindex εξαίρεση
@geindex δημιουργία;εξαίρεση
@geindex __traceback__ (χαρακτηριστικό εξαίρεσης)

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-raise_stmt}@anchor{26f0}raise_stmt: "raise" [@ref{42a,,expression} ["from" @ref{42a,,expression}]]
@end example

Εάν δεν υπάρχουν εκφράσεις, η @ref{9e4,,raise} επαναφέρει την εξαίρεση που αντιμετωπίζεται εκείνη τη στιγμή, η οποία είναι επίσης γνωστή ως `ενεργή εξαίρεση'. Εάν δεν υπάρχει προς το παρόν ενεργή εξαίρεση, εμφανίζεται μια εξαίρεση @ref{30d,,RuntimeError} που υποδεικνύει ότι πρόκειται για σφάλμα.

Διαφορετικά, η @ref{9e4,,raise} αξιολογεί την πρώτη έκφραση ως αντικείμενο στιγμιοτύπου. Πρέπει να είναι είτε υποκατηγορία είτε παράδειγμα της @ref{9b9,,BaseException}. Εάν είναι κλάση, το στιγμιότυπο της εξαίρεσης θα ληφθεί όταν χρειαστεί με τη δημιουργία της κλάσης χωρίς ορίσματα.

Ο `τύπος' της εξαίρεσης είναι η κλάση του στιγμιοτύπου της εξαίρεσης, η `τιμή' είναι το ίδιο το στιγμιότυπο.

@geindex αντικείμενο;ανίχνευση

Ένα αντικείμενο ανίχνευσης (traceback) δημιουργείται κανονικά αυτόματα όταν προκαλείται μια εξαίρεση και επισυνάπτεται σε αυτήν ως το χαρακτηριστικό @ref{166b,,__traceback__}. Μπορείτε να δημιουργήσετε μια εξαίρεση και να ορίσετε τη δική σας ανίχνευση σε ένα βήμα χρησιμοποιώντας τη μέθοδο εξαίρεσης @ref{2709,,with_traceback()} (η οποία επιστρέφει το ίδιο στιγμιότυπο εξαίρεσης, με το traceback του, ορισμένο στο όρισμά του), ως εξής:

@example
raise Exception("foo occurred").with_traceback(tracebackobj)
@end example

@geindex εξαίρεση;αλυσιδωτή
@geindex __cause__ (χαρακτηριστικό εξαίρεσης)
@geindex __context__ (χαρακτηριστικό εξαίρεσης)

Η ρήτρα @code{from} χρησιμοποιείται για την αλυσιδωτή εξαίρεση: εάν δοθεί, η δεύτερη `έκφραση' πρέπει να είναι μια άλλη κλάση εξαίρεσης ή στιγμιότυπο. Εάν η δεύτερη έκφραση είναι ένα παράδειγμα εξαίρεσης, θα επισυναφθεί στην εξαίρεση που δημιουργήθηκε ως χαρακτηριστικό @ref{166d,,__cause__} (το οποίο είναι εγγράψιμο). Εάν η έκφραση είναι μια κλάση εξαίρεσης, η κλάση θα δημιουργηθεί και το προκύπτον στιγμιότυπο εξαίρεσης θα επισυναφθεί στην εξαίρεση που δημιουργήθηκε ως χαρακτηριστικό @code{__cause__}. Εάν η εξαίρεση που δημιουργήθηκε δεν αντιμετωπιστεί, θα εκτυπωθούν και οι δύο εξαιρέσεις:

@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

Ένας παρόμοιος μηχανισμός λειτουργεί σιωπηρά εάν προκύψει μια νέα εξαίρεση όταν μια εξαίρεση αντιμετωπίζεται ήδη. Μια εξαίρεση μπορεί να αντιμετωπιστεί όταν χρησιμοποιείται μια ρήτρα @ref{447,,except} ή @ref{44c,,finally}, ή μια εντολή @ref{20a,,with}. Η προηγούμενη εξαίρεση επισυνάπτεται στη συνέχεια ως το χαρακτηριστικό @ref{166c,,__context__} της νέας εξαίρεσης:

@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

Η αλυσιδωτή εξαίρεση μπορεί να καταργηθεί ρητά, καθορίζοντας το @ref{a65,,None} στη ρήτρα @code{from}:

@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

Πρόσθετες πληροφορίες σχετικά με τις εξαιρέσεις μπορείτε να βρείτε στην ενότητα @ref{2629,,Εξαιρέσεις} και πληροφορίες σχετικά με τον χειρισμό εξαιρέσεων στην ενότητα @ref{ad6,,The try statement}.


Άλλαξε στην έκδοση 3.3: Το @ref{a65,,None} επιτρέπεται πλέον ως @code{Y} στο @code{raise X from Y}.

Προστέθηκε το χαρακτηριστικό @ref{270a,,__suppress_context__} για την κατάργηση της αυτόματης εμφάνισης του περιβάλλοντος της εξαίρεσης.



Άλλαξε στην έκδοση 3.11: Εάν η ανίχνευση της ενεργής εξαίρεσης τροποποιηθεί σε μια ρήτρα @ref{447,,except}, μια επακόλουθη εντολή @code{raise} επαναδημιουργεί την εξαίρεση με την τροποποιημένη ανίχνευση. Προηγουμένως, η εξαίρεση επαναδημιουργούνταν με την ανίχνευση που είχε όταν εντοπίστηκε.


@node Η εντολή break,Η εντολή continue,Η εντολή raise,Απλές εντολές
@anchor{reference/simple_stmts break}@anchor{428}@anchor{reference/simple_stmts the-break-statement}@anchor{270b}
@subsection Η εντολή @code{break}


@geindex δήλωση;break
@geindex δήλωση;for
@geindex δήλωση;while
@geindex βρόχος;δήλωση

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-break_stmt}@anchor{26f1}break_stmt: "break"
@end example

Η εντολή @ref{428,,break} μπορεί να εμφανιστεί μόνο συντακτικά ενσωματωμένη σε έναν βρόχο @ref{321,,for} ή @ref{1b86,,while}, αλλά όχι ενσωματωμένη σε έναν ορισμό συνάρτησης ή κλάσης μέσα σε αυτόν τον βρόχο.

@geindex λέξη-κλειδί;else
@geindex έλεγχος βρόχου;στόχος

Τερματίζει τον πλησιέστερο περικλείοντα βρόχο, παρακάμπτοντας την προαιρετική ρήτρα @code{else} εάν ο βρόχος έχει μία.

Εάν ένας βρόχος @ref{321,,for} τερματιστεί από την εντολή @ref{428,,break}, ο στόχος ελέγχου του βρόχου διατηρεί την τρέχουσα τιμή του.

@geindex λέξη-κλειδί;finally

Όταν η εντολή @ref{428,,break} μεταβιβάζει τον έλεγχο από μια εντολή @ref{ad6,,try} με μια ρήτρα @ref{44c,,finally}, αυτή η ρήτρα @code{finally} εκτελείται πριν από την πραγματική έξοδο από τον βρόχο.

@node Η εντολή continue,Η εντολή import,Η εντολή break,Απλές εντολές
@anchor{reference/simple_stmts continue}@anchor{429}@anchor{reference/simple_stmts the-continue-statement}@anchor{270c}
@subsection Η εντολή @code{continue}


@geindex δήλωση;continue
@geindex δήλωση;for
@geindex δήλωση;while
@geindex βρόχος;δήλωση
@geindex λέξη-κλειδί;finally

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-continue_stmt}@anchor{26f2}continue_stmt: "continue"
@end example

Η εντολή @ref{429,,continue} μπορεί να εμφανιστεί μόνο συντακτικά ενσωματωμένη σε έναν βρόχο @ref{321,,for} ή @ref{1b86,,while}, αλλά όχι ενσωματωμένη σε έναν ορισμό συνάρτησης ή κλάσης μέσα σε αυτόν τον βρόχο. Συνεχίζει με τον επόμενο κύκλο του πλησιέστερου περικλείοντος βρόχου.

Όταν η εντολή @ref{429,,continue} μεταβιβάζει τον έλεγχο από μια εντολή @ref{ad6,,try} με μια ρήτρα @ref{44c,,finally}, αυτή η ρήτρα @code{finally} εκτελείται πριν από την πραγματική έναρξη του επόμενου κύκλου του βρόχου.
@anchor{reference/simple_stmts import}@anchor{9da}
@node Η εντολή import,Η εντολή global,Η εντολή continue,Απλές εντολές
@anchor{reference/simple_stmts from}@anchor{1650}@anchor{reference/simple_stmts the-import-statement}@anchor{270d}
@subsection Η εντολή @code{import}


@geindex δήλωση;εισαγωγή
@geindex module;εισαγωγή
@geindex όνομα;δέσμευση
@geindex λέξη-κλειδί;from
@geindex λέξη-κλειδί;as
@geindex λέξη-κλειδί;lazy
@geindex εξαίρεση;ImportError
@geindex @comma{} (κόμμα);εντολή εισαγωγής

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-import_stmt}@anchor{26f3}import_stmt:     ["lazy"] "import" @ref{270e,,module} ["as" @ref{24b2,,identifier}] ("," @ref{270e,,module} ["as" @ref{24b2,,identifier}])*
                 | ["lazy"] "from" @ref{270f,,relative_module} "import" @ref{24b2,,identifier} ["as" @ref{24b2,,identifier}]
                 ("," @ref{24b2,,identifier} ["as" @ref{24b2,,identifier}])*
                 | ["lazy"] "from" @ref{270f,,relative_module} "import" "(" @ref{24b2,,identifier} ["as" @ref{24b2,,identifier}]
                 ("," @ref{24b2,,identifier} ["as" @ref{24b2,,identifier}])* [","] ")"
                 | "from" @ref{270f,,relative_module} "import" "*"
@anchor{reference/simple_stmts grammar-token-python-grammar-module}@anchor{270e}module:          (@ref{24b2,,identifier} ".")* @ref{24b2,,identifier}
@anchor{reference/simple_stmts grammar-token-python-grammar-relative_module}@anchor{270f}relative_module: "."* @ref{270e,,module} | "."+
@end example

Η βασική εντολή εισαγωγής (χωρίς ρήτρα @ref{1650,,from}) εκτελείται σε δύο βήματα:


@enumerate 

@item 
βρείτε ένα module, φορτώστε το και αρχικοποιήστε το εάν είναι απαραίτητο

@item 
define a name or names in the current namespace for the scope where
the @ref{9da,,import} statement occurs, just as an assignment statement
would (including @ref{6b5,,global} and @ref{164c,,nonlocal} semantics).
@end enumerate

Όταν η εντολή περιέχει πολλαπλές ρήτρες (διαχωρισμένες με κόμματα), τα δύο βήματα εκτελούνται ξεχωριστά για κάθε ρήτρα, σαν οι ρήτρες να είχαν διαχωριστεί σε μεμονωμένες εντολές εισαγωγής.

Οι λεπτομέρειες του πρώτου βήματος, η εύρεση και η φόρτωση των modules, περιγράφονται με περισσότερες λεπτομέρειες στην ενότητα για το @ref{2551,,σύστημα εισαγωγής}, το οποίο περιγράφει επίσης τους διάφορους τύπους πακέτων και modules που μπορούν να εισαχθούν, καθώς και όλα τα άγκιστρα που μπορούν να χρησιμοποιηθούν για την προσαρμογή του συστήματος εισαγωγής. Σημειώστε ότι οι αποτυχίες σε αυτό το βήμα μπορεί να υποδεικνύουν είτε ότι το module δεν ήταν δυνατό να εντοπιστεί, `ή' ότι παρουσιάστηκε σφάλμα κατά την αρχικοποίηση του module, συμπεριλαμβανομένης της εκτέλεσης του κώδικά του.

Εάν το ζητούμενο module ανακτηθεί με επιτυχία, θα είναι διαθέσιμο στο τοπικό namespace με έναν από τους τρεις τρόπους:

@geindex as;εντολή εισαγωγής


@itemize *

@item 
Εάν το όνομα του module ακολουθείται από @code{as}, τότε το όνομα που ακολουθεί το @code{as} δεσμεύεται απευθείας στο εισαγόμενο module.

@item 
Εάν δεν έχει καθοριστεί άλλο όνομα και το module που εισάγεται είναι ένα module ανώτατου επιπέδου, το όνομα του module δεσμεύεται στο τοπικό namespace ως αναφορά στο εισαγόμενο module

@item 
Εάν το module που εισάγεται `δεν' είναι ένα module ανώτατου επιπέδου, τότε το όνομα του πακέτου ανώτατου επιπέδου που περιέχει το module δεσμεύεται στο τοπικό namespace ως αναφορά στο πακέτο ανώτατου επιπέδου. Η πρόσβαση στο εισαγόμενο module πρέπει να γίνεται χρησιμοποιώντας το πλήρες ειδικευμένο όνομά του και όχι απευθείας
@end itemize

@geindex όνομα;δέσμευση
@geindex from;εντολή εισαγωγής

Η μορφή @ref{1650,,from} χρησιμοποιεί μια ελαφρώς πιο σύνθετη διαδικασία:


@enumerate 

@item 
βρείτε το module που καθορίζεται στη ρήτρα @ref{1650,,from}, φορτώστε το και αρχικοποιήστε το εάν είναι απαραίτητο·

@item 
για καθένα από τα αναγνωριστικά που καθορίζονται στις ρήτρες @ref{9da,,import}:


@enumerate 

@item 
ελέγξτε εάν το εισαγόμενο module έχει ένα χαρακτηριστικό με αυτό το όνομα

@item 
εάν όχι, προσπαθήστε να εισαγάγετε ένα submodule με αυτό το όνομα και, στη συνέχεια, ελέγξτε ξανά το εισαγόμενο module για αυτό το χαρακτηριστικό

@item 
εάν το χαρακτηριστικό δεν βρεθεί, γίνεται raise η @ref{1bd,,ImportError}.

@item 
otherwise, a reference to that value is stored in the current namespace,
using the name in the @code{as} clause if it is present,
otherwise using the attribute name
@end enumerate
@end enumerate

Παραδείγματα:

@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 * (αστερίσκος);εντολή εισαγωγής

Εάν η λίστα των αναγνωριστικών αντικατασταθεί από έναν αστερίσκο (@code{'*'}), όλα τα δημόσια ονόματα που ορίζονται στο module δεσμεύονται στο τοπικό namespace για το εύρος όπου εμφανίζεται η εντολή @ref{9da,,import}.

@geindex __all__ (προαιρετικό χαρακτηριστικό module)

@geindex __all__ (ιδιότητα της module)
@anchor{reference/simple_stmts module __all__}@anchor{10f6}
The `public names' defined by a module are determined by checking the module’s
namespace for a variable named @code{__all__}; if defined, it must be a sequence
of strings which are names defined or imported by that module.
Names containing non-ASCII characters must be in the normalization form@footnote{https://www.unicode.org/reports/tr15/#Norm_Forms}
NFKC; see @ref{24ae,,Μη-ASCII χαρακτήρες στα ονόματα} for details.  The names
given in @code{__all__} are all considered public and are required to exist.  If
@code{__all__} is not defined, the set of public names includes all names found
in the module’s namespace which do not begin with an underscore character
(@code{'_'}).  @code{__all__} should contain the entire public API. It is intended
to avoid accidentally exporting items that are not part of the API (such as
library modules which were imported and used within the module).

Η μορφή εισαγωγής με χαρακτήρα μπαλαντέρ — @code{from module import *} — επιτρέπεται μόνο σε επίπεδο module. Η προσπάθεια χρήσης της σε ορισμούς κλάσεων ή συναρτήσεων θα προκαλέσει @ref{17e,,SyntaxError}.

@geindex σχετικός;εισαγωγή

Κατά τον καθορισμό του module προς εισαγωγή, δεν χρειάζεται να καθορίσετε το απόλυτο όνομα του module. Όταν ένα module ή ένα πακέτο περιέχεται μέσα σε ένα άλλο πακέτο, είναι δυνατή η σχετική εισαγωγή μέσα στο ίδιο πακέτο ανώτατου επιπέδου χωρίς να χρειάζεται να αναφερθεί το όνομα του πακέτου. Χρησιμοποιώντας leading dots στο καθορισμένο module ή πακέτο μετά το @ref{1650,,from}, μπορείτε να καθορίσετε πόσο ψηλά θα διασχίσετε την τρέχουσα ιεραρχία πακέτων χωρίς να καθορίσετε ακριβή ονόματα. Ένα leading dot σημαίνει το τρέχον πακέτο όπου υπάρχει το module που πραγματοποιεί την εισαγωγή. Δύο leading dots σημαίνουν ένα επίπεδο πακέτου προς τα πάνω. Τρία leading dots είναι δύο επίπεδα προς τα πάνω, κ.λπ. Έτσι, εάν εκτελέσετε το @code{from . import mod} από ένα module στο πακέτο @code{pkg}, θα καταλήξετε να εισάγετε το @code{pkg.mod}. Εάν εκτελέσετε το @code{from ..subpkg2 import mod} από το @code{pkg.subpkg1}, θα εισαγάγετε το @code{pkg.subpkg2.mod}. Η προδιαγραφή για τις σχετικές εισαγωγές περιέχεται στην ενότητα @ref{2654,,Σχετικές εισαγωγές σε πακέτα}.

Η συνάρτηση @ref{927,,importlib.import_module()} παρέχεται για την υποστήριξη εφαρμογών που καθορίζουν δυναμικά τα modules που θα φορτωθούν.

Κάνει raise ένα @ref{1e65,,auditing event} @code{import} με ορίσματα @code{module}, @code{filename}, @code{sys.path}, @code{sys.meta_path}, @code{sys.path_hooks}.
@anchor{reference/simple_stmts lazy-imports}@anchor{255e}
@menu
* Lazy imports:: 
* Μελλοντικές δηλώσεις:: 

@end menu

@node Lazy imports,Μελλοντικές δηλώσεις,,Η εντολή import
@anchor{reference/simple_stmts id1}@anchor{2710}@anchor{reference/simple_stmts lazy}@anchor{177}
@subsubsection Lazy imports


@geindex lazy;εισαγωγή
@geindex lazy import

The @ref{177,,lazy} keyword is a @ref{be6,,soft keyword} that
only has special meaning when it appears immediately before an
@ref{9da,,import} or @ref{1650,,from} statement. When an import statement is
preceded by the @code{lazy} keyword, the import becomes `lazy': the
module is not loaded immediately at the import statement. Instead, a lazy
proxy object is created and bound to the name. The actual module is loaded
on first use of that name.

Lazy imports are only permitted at module scope. Using @ref{177,,lazy}
inside a function, class body, or
@ref{ad6,,try}/@ref{447,,except}/@ref{44c,,finally} block raises a
@ref{17e,,SyntaxError}. Star imports cannot be lazy (@code{lazy from module import
*} is a syntax error), and @ref{670,,future statements} cannot be
lazy.

When using @code{lazy from ... import}, each imported name is bound to a lazy
proxy object. The first access to any of these names triggers loading of the
entire module and resolves only that specific name to its actual value.
Other names remain as lazy proxies until they are accessed.

Example:

@example
lazy import json
import sys

print('json' in sys.modules)  # False - json module not yet loaded

# First use triggers loading
result = json.dumps(@{"hello": "world"@})

print('json' in sys.modules)  # True - now loaded
@end example

If an error occurs during module loading (such as @ref{1bd,,ImportError} or
@ref{17e,,SyntaxError}), it is raised at the point where the lazy import is first
used, not at the import statement itself.

See 
@geindex Python Enhancement Proposals; PEP 810
PEP 810@footnote{https://peps.python.org/pep-0810/} for the full specification of lazy imports.


Added in version 3.15.


@menu
* Compatibility via __lazy_modules__:: 

@end menu

@node Compatibility via __lazy_modules__,,,Lazy imports
@anchor{reference/simple_stmts compatibility-via-lazy-modules}@anchor{2711}@anchor{reference/simple_stmts lazy-modules-compat}@anchor{255f}
@subsubsection Compatibility via @code{__lazy_modules__}


@geindex __lazy_modules__

As an alternative to using the @ref{177,,lazy} keyword, a module can opt
into lazy loading for specific imports by defining a module-level
@ref{17f,,__lazy_modules__} variable.  When present, it must be a
container of fully qualified module name strings.  Any regular (non-@code{lazy})
@ref{9da,,import} statement at module scope whose target appears in
@code{__lazy_modules__} is treated as a lazy import, exactly as if the
@code{lazy} keyword had been used.

This provides a way to enable lazy loading for specific dependencies without
changing individual @code{import} statements. This is useful when supporting
Python versions older than 3.15 while using lazy imports in 3.15+:

@example
__lazy_modules__ = ["json", "pathlib"]

import json     # loaded lazily (name is in __lazy_modules__)
import os       # loaded eagerly (name not in __lazy_modules__)

import pathlib  # loaded lazily
@end example

Relative imports are resolved to their absolute name before the lookup, so
@code{__lazy_modules__} must always contain fully qualified module names.

For @code{from}-style imports, the relevant name is the module following
@code{from}, not the names of its members:

@example
# In mypackage/mymodule.py
__lazy_modules__ = ["mypackage", "mypackage.sub.utils"]

from . import helper         # loaded lazily: . resolves to mypackage
from .sub.utils import func  # loaded lazily: .sub.utils resolves to mypackage.sub.utils
import json                  # loaded eagerly (not in __lazy_modules__)
@end example

Imports inside functions, class bodies, or
@ref{ad6,,try}/@ref{447,,except}/@ref{44c,,finally} blocks are always eager,
regardless of @code{__lazy_modules__}.

Setting @code{-X lazy_imports=none} (or the 
@geindex PYTHON_LAZY_IMPORTS
@geindex μεταβλητή περιβάλλοντος; PYTHON_LAZY_IMPORTS
@ref{179,,PYTHON_LAZY_IMPORTS}
environment variable to @code{none}) overrides @code{__lazy_modules__} and
forces all imports to be eager.


Added in version 3.15.


@node Μελλοντικές δηλώσεις,,Lazy imports,Η εντολή import
@anchor{reference/simple_stmts future}@anchor{670}@anchor{reference/simple_stmts future-statements}@anchor{2712}
@subsubsection Μελλοντικές δηλώσεις


@geindex μελλοντικός;δήλωση
@geindex __future__;μελλοντική δήλωση

Μια `μελλοντική δήλωση' είναι μια οδηγία προς τον μεταγλωττιστή ότι ένα συγκεκριμένο module πρέπει να μεταγλωττιστεί χρησιμοποιώντας σύνταξη ή σημασιολογία που θα είναι διαθέσιμη σε μια καθορισμένη μελλοντική έκδοση της Python όπου η δυνατότητα γίνεται πρότυπο.

Η μελλοντική δήλωση προορίζεται να διευκολύνει τη μετάβαση σε μελλοντικές εκδόσεις της Python που εισάγουν ασύμβατες αλλαγές στη γλώσσα. Επιτρέπει τη χρήση των νέων δυνατοτήτων ανά module πριν από την έκδοση στην οποία η δυνατότητα γίνεται πρότυπο.

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-future_stmt}@anchor{26f4}future_stmt: "from" "__future__" "import" @ref{2713,,feature} ["as" @ref{24b2,,identifier}]
             ("," @ref{2713,,feature} ["as" @ref{24b2,,identifier}])*
             | "from" "__future__" "import" "(" @ref{2713,,feature} ["as" @ref{24b2,,identifier}]
             ("," @ref{2713,,feature} ["as" @ref{24b2,,identifier}])* [","] ")"
@anchor{reference/simple_stmts grammar-token-python-grammar-feature}@anchor{2713}feature:     @ref{24b2,,identifier}
@end example

Μια μελλοντική δήλωση πρέπει να εμφανίζεται κοντά στην κορυφή του module. Οι μόνες γραμμές που μπορούν να εμφανιστούν πριν από μια μελλοντική δήλωση είναι:


@itemize *

@item 
η συμβολοσειρά τεκμηρίωσης του module (εάν υπάρχει),

@item 
σχόλια,

@item 
κενές γραμμές, και

@item 
άλλες μελλοντικές δηλώσεις.
@end itemize

Η μόνη δυνατότητα που απαιτεί τη χρήση της μελλοντικής δήλωσης είναι τα @code{annotations} (ανατρέξτε στο 
@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/}).

Όλες οι ιστορικές δυνατότητες που ενεργοποιούνται από τη μελλοντική δήλωση εξακολουθούν να αναγνωρίζονται από την Python 3. Η λίστα περιλαμβάνει τα @code{absolute_import}, @code{division}, @code{generators}, @code{generator_stop}, @code{unicode_literals}, @code{print_function}, @code{nested_scopes} και @code{with_statement}. Είναι όλα περιττά επειδή είναι πάντα ενεργοποιημένα και διατηρούνται μόνο για λόγους συμβατότητας προς τα πίσω.

Μια μελλοντική δήλωση αναγνωρίζεται και αντιμετωπίζεται ειδικά κατά τη μεταγλώττιση: Οι αλλαγές στη σημασιολογία των βασικών δομών υλοποιούνται συχνά με τη δημιουργία διαφορετικού κώδικα. Μπορεί ακόμη και να συμβεί μια νέα δυνατότητα να εισάγει νέα ασύμβατη σύνταξη (όπως μια νέα δεσμευμένη λέξη), οπότε ο μεταγλωττιστής μπορεί να χρειαστεί να αναλύσει το module διαφορετικά. Τέτοιες αποφάσεις δεν μπορούν να αναβληθούν μέχρι το χρόνο εκτέλεσης.

Για κάθε δεδομένη έκδοση, ο μεταγλωττιστής γνωρίζει ποια ονόματα δυνατοτήτων έχουν οριστεί και προκαλεί σφάλμα μεταγλώττισης εάν μια μελλοντική δήλωση περιέχει μια δυνατότητα που δεν του είναι γνωστή.

Η άμεση σημασιολογία χρόνου εκτέλεσης είναι η ίδια όπως για κάθε εντολή εισαγωγής: υπάρχει ένα τυπικό module @ref{0,,__future__}, που περιγράφεται παρακάτω, και θα εισαχθεί με τον συνήθη τρόπο κατά την εκτέλεση της μελλοντικής δήλωσης.

Η ενδιαφέρουσα σημασιολογία χρόνου εκτέλεσης εξαρτάται από τη συγκεκριμένη δυνατότητα που ενεργοποιείται από τη μελλοντική δήλωση.

Σημειώστε ότι δεν υπάρχει τίποτα το ιδιαίτερο σχετικά με την εντολή:

@example
import __future__ [as name]
@end example

Αυτή δεν είναι μια μελλοντική δήλωση· είναι μια συνηθισμένη εντολή εισαγωγής χωρίς ειδικούς περιορισμούς σημασιολογίας ή σύνταξης.

Ο κώδικας που μεταγλωττίζεται από κλήσεις στις ενσωματωμένες συναρτήσεις @ref{185,,exec()} και @ref{1c8,,compile()} που εμφανίζονται σε ένα module @code{M} που περιέχει μια μελλοντική δήλωση θα χρησιμοποιήσει, από προεπιλογή, τη νέα σύνταξη ή σημασιολογία που σχετίζεται με τη μελλοντική δήλωση. Αυτό μπορεί να ελεγχθεί από προαιρετικά ορίσματα στο @code{compile()} — ανατρέξτε στην τεκμηρίωση αυτής της συνάρτησης για λεπτομέρειες.

Μια μελλοντική δήλωση που πληκτρολογείται σε μια διαδραστική γραμμή εντολών του διερμηνέα θα τεθεί σε ισχύ για το υπόλοιπο της περιόδου λειτουργίας του διερμηνέα. Εάν ένας διερμηνέας εκκινηθεί με την επιλογή @ref{187d,,-i}, του δοθεί ένα όνομα σεναρίου για εκτέλεση και το σενάριο περιλαμβάνει μια μελλοντική δήλωση, θα ισχύει στη διαδραστική συνεδρία που ξεκίνησε μετά την εκτέλεση του σεναρίου.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 236

@item PEP 236@footnote{https://peps.python.org/pep-0236/} - Επιστροφή στο __future__

Η αρχική πρόταση για τον μηχανισμό __future__.
@end table


@node Η εντολή global,Η εντολή nonlocal,Η εντολή import,Απλές εντολές
@anchor{reference/simple_stmts global}@anchor{6b5}@anchor{reference/simple_stmts the-global-statement}@anchor{2714}
@subsection Η εντολή @code{global}


@geindex δήλωση;global
@geindex global;όνομα;δέσμευση
@geindex @comma{} (κόμμα);λίστα αναγνωριστικών

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-global_stmt}@anchor{26f5}global_stmt: "global" @ref{24b2,,identifier} ("," @ref{24b2,,identifier})*
@end example

Η εντολή @ref{6b5,,global} προκαλεί την ερμηνεία των αναγραφόμενων αναγνωριστικών ως καθολικών (globals). Θα ήταν αδύνατο να γίνει ανάθεση σε μια καθολική μεταβλητή χωρίς το @code{global}, αν και οι ελεύθερες μεταβλητές μπορεί να αναφέρονται σε καθολικές μεταβλητές χωρίς να δηλωθούν καθολικές.

Η εντολή @code{global} ισχύει για ολόκληρο το τρέχον πεδίο (module, σώμα συνάρτησης ή ορισμός κλάσης). Ένα @ref{17e,,SyntaxError} προκαλείται εάν μια μεταβλητή χρησιμοποιηθεί ή ανατεθεί πριν από την καθολική της δήλωση στο πεδίο.

Σε επίπεδο module, όλες οι μεταβλητές είναι καθολικές (global), επομένως μια εντολή @code{global} δεν έχει κανένα αποτέλεσμα. Ωστόσο, οι μεταβλητές δεν πρέπει ακόμα να χρησιμοποιούνται ή να ανατίθενται πριν από τη δήλωσή τους με το @code{global}. Αυτή η απαίτηση δεν είναι τόσο ρητή στη διαδραστική γραμμή εντολών (@ref{69d,,REPL}).

@geindex ενσωματωμένη συνάρτηση;exec
@geindex ενσωματωμένη συνάρτηση;eval
@geindex ενσωματωμένη συνάρτηση;μεταγλώττιση

`Σημείωση προγραμματιστή:' Το @ref{6b5,,global} είναι μια οδηγία προς τον parser. Ισχύει μόνο για κώδικα που αναλύεται ταυτόχρονα με την εντολή @code{global}. Συγκεκριμένα, μια εντολή @code{global} που περιέχεται σε μια συμβολοσειρά ή αντικείμενο κώδικα που παρέχεται στην ενσωματωμένη συνάρτηση @ref{185,,exec()} δεν επηρεάζει το κομμάτι κώδικα `που περιέχει' την κλήση συνάρτησης και ο κώδικας που περιέχεται σε μια τέτοια συμβολοσειρά δεν επηρεάζεται από τις εντολές @code{global} στον κώδικα που περιέχει την κλήση συνάρτησης. Το ίδιο ισχύει για τις συναρτήσεις @ref{184,,eval()} και @ref{1c8,,compile()}.

@node Η εντολή nonlocal,Η εντολή type,Η εντολή global,Απλές εντολές
@anchor{reference/simple_stmts nonlocal}@anchor{164c}@anchor{reference/simple_stmts the-nonlocal-statement}@anchor{2715}
@subsection Η εντολή @code{nonlocal}


@geindex δήλωση;nonlocal
@geindex @comma{} (κόμμα);λίστα αναγνωριστικών

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-nonlocal_stmt}@anchor{26f6}nonlocal_stmt: "nonlocal" @ref{24b2,,identifier} ("," @ref{24b2,,identifier})*
@end example

Όταν ο ορισμός μιας συνάρτησης ή κλάσης είναι ενσωματωμένος (περικλείεται) στους ορισμούς άλλων συναρτήσεων, τα μη τοπικά του πεδία είναι τα τοπικά πεδία των περικλειόμενων συναρτήσεων. Η εντολή @ref{164c,,nonlocal} προκαλεί τα αναγραφόμενα αναγνωριστικά να αναφέρονται σε ονόματα που είχαν προηγουμένως δεσμευτεί σε μη τοπικά πεδία. Επιτρέπει στον ενθυλακωμένο κώδικα να επαναδεσμεύσει τέτοια μη τοπικά αναγνωριστικά. Εάν ένα όνομα είναι δεσμευμένο σε περισσότερα από ένα μη τοπικά πεδία, χρησιμοποιείται η πλησιέστερη δέσμευση. Εάν ένα όνομα δεν είναι δεσμευμένο σε κανένα μη τοπικό πεδίο, ή εάν δεν υπάρχει μη τοπικό πεδίο, γίνεται raise το @ref{17e,,SyntaxError}.

Η εντολή @ref{164c,,nonlocal} ισχύει για ολόκληρο το πεδίο ενός σώματος συνάρτησης ή κλάσης. Ένα @ref{17e,,SyntaxError} γίνεται raise εάν μια μεταβλητή χρησιμοποιηθεί ή ανατεθεί πριν από τη μη τοπική της δήλωση στο πεδίο.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 3104

@item PEP 3104@footnote{https://peps.python.org/pep-3104/} - Πρόσβαση σε ονόματα σε εξωτερικά πεδία

Η προδιαγραφή για την εντολή @ref{164c,,nonlocal}.
@end table


`Σημείωση προγραμματιστή:' Το @ref{164c,,nonlocal} είναι μια οδηγία προς τον parser και ισχύει μόνο για κώδικα που αναλύεται μαζί του. Ανατρέξτε στη σημείωση για την εντολή @ref{6b5,,global}.

@node Η εντολή type,,Η εντολή nonlocal,Απλές εντολές
@anchor{reference/simple_stmts the-type-statement}@anchor{2716}@anchor{reference/simple_stmts type}@anchor{85a}
@subsection Η εντολή @code{type}


@geindex δήλωση;τύπος

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-type_stmt}@anchor{26f7}type_stmt: 'type' @ref{24b2,,identifier} [@ref{2717,,type_params}] "=" @ref{42a,,expression}
@end example

Η εντολή @code{type} δηλώνει ένα ψευδώνυμο τύπου, το οποίο είναι ένα στιγμιότυπο του @ref{52a,,typing.TypeAliasType}.

Για παράδειγμα, η ακόλουθη εντολή δημιουργεί ένα ψευδώνυμο τύπου:

@example
type Point = tuple[float, float]
@end example

Αυτός ο κώδικας είναι περίπου ισοδύναμος με:

@example
annotation-def VALUE_OF_Point():
    return tuple[float, float]
Point = typing.TypeAliasType("Point", VALUE_OF_Point())
@end example

Το @code{annotation-def} υποδεικνύει ένα @ref{6b4,,πεδίο σχολιασμού}, το οποίο συμπεριφέρεται κυρίως σαν μια συνάρτηση, αλλά με αρκετές μικρές διαφορές.

Η τιμή του ψευδώνυμου τύπου αξιολογείται στο πεδίο σχολιασμού. Δεν αξιολογείται κατά τη δημιουργία του ψευδώνυμου τύπου, αλλά μόνο όταν η τιμή προσπελαστεί μέσω του χαρακτηριστικού @code{__value__} του ψευδώνυμου τύπου (ανατρέξτε στην @ref{872,,Καθυστερημένη εκτίμηση}). Αυτό επιτρέπει στο ψευδώνυμο τύπου να αναφέρεται σε ονόματα που δεν έχουν ακόμη οριστεί.

Τα ψευδώνυμα τύπων μπορούν να γίνουν generic προσθέτοντας μια @ref{7a5,,λιστα παραμέτρων τύπου} μετά το όνομα. Ανατρέξτε στα @ref{871,,Generic type aliases} για περισσότερα.

Το @code{type} είναι μια @ref{be6,,ήπια λέξη-κλειδί}.


Added in version 3.12.



@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 695

@item PEP 695@footnote{https://peps.python.org/pep-0695/} - Σύνταξη παραμέτρων τύπου

Εισήγαγε την εντολή @code{type} και τη σύνταξη για γενικές κλάσεις και συναρτήσεις.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Compound statements,Συστατικά ανωτάτου επιπέδου,Απλές εντολές,Εγχειρίδιο Αναφοράς της Γλώσσας Python
@anchor{reference/compound_stmts doc}@anchor{2718}@anchor{reference/compound_stmts compound}@anchor{2719}@anchor{reference/compound_stmts compound-statements}@anchor{271a}@anchor{reference/compound_stmts translation-repo}@anchor{271b}
@section Compound statements


@geindex compound;statement

Compound statements contain (groups of) other statements; they affect or control
the execution of those other statements in some way.  In general, compound
statements span multiple lines, although in simple incarnations a whole compound
statement may be contained in one line.

The @ref{322,,if}, @ref{1b86,,while} and @ref{321,,for} statements implement
traditional control flow constructs.  @ref{ad6,,try} specifies exception
handlers and/or cleanup code for a group of statements, while the
@ref{20a,,with} statement allows the execution of initialization and
finalization code around a block of code.  Function and class definitions are
also syntactically compound statements.

@geindex clause
@geindex suite
@geindex ; (semicolon)

A compound statement consists of one or more “clauses.”  A clause consists of a
header and a “suite.”  The clause headers of a particular compound statement are
all at the same indentation level. Each clause header begins with a uniquely
identifying keyword and ends with a colon.  A suite is a group of statements
controlled by a clause.  A suite can be one or more semicolon-separated simple
statements on the same line as the header, following the header’s colon, or it
can be one or more indented statements on subsequent lines.  Only the latter
form of a suite can contain nested compound statements; the following is illegal,
mostly because it wouldn’t be clear to which @ref{322,,if} clause a following
@ref{320,,else} clause would belong:

@example
if test1: if test2: print(x)
@end example

Also note that the semicolon binds tighter than the colon in this context, so
that in the following example, either all or none of the @ref{131f,,print()} calls are
executed:

@example
if x < y < z: print(x); print(y); print(z)
@end example

Summarizing:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-compound_stmt}@anchor{271c}compound_stmt: @ref{271d,,if_stmt}
               | @ref{271e,,while_stmt}
               | @ref{271f,,for_stmt}
               | @ref{2720,,try_stmt}
               | @ref{2721,,with_stmt}
               | @ref{2722,,match_stmt}
               | @ref{2723,,funcdef}
               | @ref{2724,,classdef}
               | @ref{2725,,async_with_stmt}
               | @ref{2726,,async_for_stmt}
               | @ref{2727,,async_funcdef}
@anchor{reference/compound_stmts grammar-token-python-grammar-suite}@anchor{2728}suite:         @ref{2729,,stmt_list} NEWLINE | NEWLINE INDENT @ref{272a,,statement}+ DEDENT
@anchor{reference/compound_stmts grammar-token-python-grammar-statement}@anchor{272a}statement:     @ref{2729,,stmt_list} NEWLINE | @ref{271c,,compound_stmt}
@anchor{reference/compound_stmts grammar-token-python-grammar-stmt_list}@anchor{2729}stmt_list:     @ref{26e6,,simple_stmt} (";" @ref{26e6,,simple_stmt})* [";"]
@end example

@geindex NEWLINE token
@geindex DEDENT token
@geindex dangling;else

Note that statements always end in a @code{NEWLINE} possibly followed by a
@code{DEDENT}.  Also note that optional continuation clauses always begin with a
keyword that cannot start a statement, thus there are no ambiguities (the
“dangling @ref{320,,else}” problem is solved in Python by requiring nested
@ref{322,,if} statements to be indented).

The formatting of the grammar rules in the following sections places each clause
on a separate line for clarity.
@anchor{reference/compound_stmts if}@anchor{322}@anchor{reference/compound_stmts elif}@anchor{425}
@menu
* The if statement:: 
* The while statement:: 
* The for statement:: 
* The try statement:: 
* The with statement:: 
* The match statement:: 
* Function definitions:: 
* Class definitions:: 
* Coroutines: Coroutines<2>. 
* Type parameter lists:: 
* Annotations: Annotations<2>. 

@end menu

@node The if statement,The while statement,,Compound statements
@anchor{reference/compound_stmts else}@anchor{320}@anchor{reference/compound_stmts the-if-statement}@anchor{272b}
@subsection The @code{if} statement


@geindex statement;if
@geindex keyword;elif
@geindex keyword;else
@geindex ; (colon);compound statement

The @ref{322,,if} statement is used for conditional execution:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-if_stmt}@anchor{271d}if_stmt: "if" @ref{2623,,assignment_expression} ":" @ref{2728,,suite}
         ("elif" @ref{2623,,assignment_expression} ":" @ref{2728,,suite})*
         ["else" ":" @ref{2728,,suite}]
@end example

It selects exactly one of the suites by evaluating the expressions one by one
until one is found to be true (see section @ref{26cf,,Boolean operations} for the definition of
true and false); then that suite is executed (and no other part of the
@ref{322,,if} statement is executed or evaluated).  If all expressions are
false, the suite of the @ref{320,,else} clause, if present, is executed.

@node The while statement,The for statement,The if statement,Compound statements
@anchor{reference/compound_stmts the-while-statement}@anchor{272c}@anchor{reference/compound_stmts while}@anchor{1b86}
@subsection The @code{while} statement


@geindex statement;while
@geindex keyword;else
@geindex loop;statement
@geindex ; (colon);compound statement

The @ref{1b86,,while} statement is used for repeated execution as long as an
expression is true:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-while_stmt}@anchor{271e}while_stmt: "while" @ref{2623,,assignment_expression} ":" @ref{2728,,suite}
            ["else" ":" @ref{2728,,suite}]
@end example

This repeatedly tests the expression and, if it is true, executes the first
suite; if the expression is false (which may be the first time it is tested) the
suite of the @code{else} clause, if present, is executed and the loop
terminates.

@geindex statement;break
@geindex statement;continue

A @ref{428,,break} statement executed in the first suite terminates the loop
without executing the @code{else} clause’s suite.  A @ref{429,,continue}
statement executed in the first suite skips the rest of the suite and goes back
to testing the expression.

@node The for statement,The try statement,The while statement,Compound statements
@anchor{reference/compound_stmts for}@anchor{321}@anchor{reference/compound_stmts the-for-statement}@anchor{272d}
@subsection The @code{for} statement


@geindex statement;for
@geindex keyword;in
@geindex keyword;else
@geindex target;list
@geindex loop;statement
@geindex object;sequence
@geindex ; (colon);compound statement

The @ref{321,,for} statement is used to iterate over the elements of a sequence
(such as a string, tuple or list) or other iterable object:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-for_stmt}@anchor{271f}for_stmt: "for" @ref{267f,,target_list} "in" @ref{26dc,,starred_expression_list} ":" @ref{2728,,suite}
          ["else" ":" @ref{2728,,suite}]
@end example

The @ref{26dc,,starred_expression_list} expression is evaluated
once; it should yield an @ref{15ce,,iterable} object. An @ref{6ce,,iterator} is
created for that iterable. The first item provided by the iterator is then
assigned to the target list using the standard rules for assignments
(see @ref{261d,,Εντολές ανάθεσης}), and the suite is executed. This repeats for each
item provided by the iterator. When the iterator is exhausted,
the suite in the @code{else} clause,
if present, is executed, and the loop terminates.

@geindex statement;break
@geindex statement;continue

A @ref{428,,break} statement executed in the first suite terminates the loop
without executing the @code{else} clause’s suite.  A @ref{429,,continue}
statement executed in the first suite skips the rest of the suite and continues
with the next item, or with the @code{else} clause if there is no next
item.

The for-loop makes assignments to the variables in the target list.
This overwrites all previous assignments to those variables including
those made in the suite of the for-loop:

@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

Names in the target list are not deleted when the loop is finished, but if the
sequence is empty, they will not have been assigned to at all by the loop.  Hint:
the built-in type @ref{d0f,,range()} represents immutable arithmetic sequences of integers.
For instance, iterating @code{range(3)} successively yields 0, 1, and then 2.


Άλλαξε στην έκδοση 3.11: Starred elements are now allowed in the expression list.


@node The try statement,The with statement,The for statement,Compound statements
@anchor{reference/compound_stmts the-try-statement}@anchor{272e}@anchor{reference/compound_stmts try}@anchor{ad6}
@subsection The @code{try} statement


@geindex statement;try
@geindex keyword;except
@geindex keyword;finally
@geindex keyword;else
@geindex keyword;as
@geindex ; (colon);compound statement

The @code{try} statement specifies exception handlers and/or cleanup code
for a group of statements:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-try_stmt}@anchor{2720}try_stmt:  @ref{272f,,try1_stmt} | @ref{2730,,try2_stmt} | @ref{2731,,try3_stmt}
@anchor{reference/compound_stmts grammar-token-python-grammar-try1_stmt}@anchor{272f}try1_stmt: "try" ":" @ref{2728,,suite}
           ("except" [@ref{42a,,expression} ["as" @ref{24b2,,identifier}]] ":" @ref{2728,,suite})+
           ["else" ":" @ref{2728,,suite}]
           ["finally" ":" @ref{2728,,suite}]
@anchor{reference/compound_stmts grammar-token-python-grammar-try2_stmt}@anchor{2730}try2_stmt: "try" ":" @ref{2728,,suite}
           ("except" "*" @ref{42a,,expression} ["as" @ref{24b2,,identifier}] ":" @ref{2728,,suite})+
           ["else" ":" @ref{2728,,suite}]
           ["finally" ":" @ref{2728,,suite}]
@anchor{reference/compound_stmts grammar-token-python-grammar-try3_stmt}@anchor{2731}try3_stmt: "try" ":" @ref{2728,,suite}
           "finally" ":" @ref{2728,,suite}
@end example

Additional information on exceptions can be found in section @ref{2629,,Εξαιρέσεις},
and information on using the @ref{9e4,,raise} statement to generate exceptions
may be found in section @ref{9e4,,Η εντολή raise}.


Άλλαξε στην έκδοση 3.14: Support for optionally dropping grouping parentheses when using multiple exception types. See 
@geindex Python Enhancement Proposals; PEP 758
PEP 758@footnote{https://peps.python.org/pep-0758/}.


@menu
* except clause:: 
* except* clause:: 
* else clause:: 
* finally clause:: 

@end menu

@node except clause,except* clause,,The try statement
@anchor{reference/compound_stmts except}@anchor{447}@anchor{reference/compound_stmts except-clause}@anchor{2732}
@subsubsection @code{except} clause


The @code{except} clause(s) specify one or more exception handlers. When no
exception occurs in the @ref{ad6,,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. Parentheses
can be dropped if multiple exception types are provided and the @code{as} clause is not used.
The raised exception matches an @code{except} clause whose expression evaluates
to the class or a @ref{155f,,non-virtual base class} of the exception object,
or to a tuple that contains such a class.

If no @code{except} clause matches the exception,
the search for an exception handler
continues in the surrounding code and on the invocation stack.  @footnote{
The exception is propagated to the invocation stack unless
there is a @ref{44c,,finally} clause which happens to raise another
exception. That new exception causes the old one to be lost.
}

If the evaluation of an expression
in the header of an @code{except} clause raises an exception,
the original search for a handler is canceled and a search starts for
the new exception in the surrounding code and on the call stack (it is treated
as if the entire @ref{ad6,,try} statement raised the exception).

@geindex as;except clause

When a matching @code{except} clause is found,
the exception is assigned to the target
specified after the @code{as} keyword in that @code{except} clause,
if present, and the @code{except} clause’s suite is executed.
All @code{except} clauses must have an executable block.
When the end of this block is reached, execution continues
normally after the entire @ref{ad6,,try} statement.
(This means that if two nested handlers exist for the same exception,
and the exception occurs in the @code{try} clause of the inner handler,
the outer handler will not handle the exception.)

When an exception has been assigned using @code{as target}, it is cleared at the
end of the @code{except} clause.  This is as if

@example
except E as N:
    foo
@end example

was translated to

@example
except E as N:
    try:
        foo
    finally:
        del N
@end example

This means the exception must be assigned to a different name to be able to
refer to it after the @code{except} clause.
Exceptions are cleared because with the
traceback attached to them, they form a reference cycle with the stack frame,
keeping all locals in that frame alive until the next garbage collection occurs.

@geindex module;sys
@geindex object;traceback

Before an @code{except} clause’s suite is executed,
the exception is stored in the @ref{e2,,sys} module, where it can be accessed
from within the body of the @code{except} clause by calling
@ref{a7b,,sys.exception()}. When leaving an exception handler, the exception
stored in the @code{sys} module is reset to its previous value:

@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 except* clause,else clause,except clause,The try statement
@anchor{reference/compound_stmts except-star}@anchor{448}@anchor{reference/compound_stmts id2}@anchor{2733}
@subsubsection @code{except*} clause


The @code{except*} clause(s) specify one or more handlers for groups of
exceptions (@ref{767,,BaseExceptionGroup} instances). A @ref{ad6,,try} statement
can have either @ref{447,,except} or @code{except*} clauses, but not both.
The exception type for matching is mandatory in the case of @code{except*},
so @code{except*:} is a syntax error. The type is interpreted as in the case of
@code{except}, but matching is performed on the exceptions contained in the
group that is being handled. An @ref{291,,TypeError} is raised if a matching
type is a subclass of @code{BaseExceptionGroup}, because that would have
ambiguous semantics.

When an exception group is raised in the try block, each @code{except*}
clause splits (see @ref{1af9,,split()}) it into the subgroups
of matching and non-matching exceptions. If the matching subgroup is not empty,
it becomes the handled exception (the value returned from @ref{a7b,,sys.exception()})
and assigned to the target of the @code{except*} clause (if there is one).
Then, the body of the @code{except*} clause executes. If the non-matching
subgroup is not empty, it is processed by the next @code{except*} in the
same manner. This continues until all exceptions in the group have been matched,
or the last @code{except*} clause has run.

After all @code{except*} clauses execute, the group of unhandled exceptions
is merged with any exceptions that were raised or re-raised from within
@code{except*} clauses. This merged exception group propagates on.:

@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 "<doctest default[0]>", line 2, in <module>
  |     raise ExceptionGroup("eg",
  |         [ValueError(1), TypeError(2), OSError(3), OSError(4)])
  | ExceptionGroup: eg (1 sub-exception)
  +-+---------------- 1 ----------------
    | ValueError: 1
    +------------------------------------
@end example

If the exception raised from the @ref{ad6,,try} block is not an exception group
and its type matches one of the @code{except*} clauses, it is caught and
wrapped by an exception group with an empty message string. This ensures that the
type of the target @code{e} is consistently @ref{767,,BaseExceptionGroup}:

@example
>>> try:
...     raise BlockingIOError
... except* BlockingIOError as e:
...     print(repr(e))
...
ExceptionGroup('@w{'}, (BlockingIOError(),))
@end example

@ref{428,,break}, @ref{429,,continue} and @ref{44b,,return}
cannot appear in an @code{except*} clause.

@geindex keyword;else
@geindex statement;return
@geindex statement;break
@geindex statement;continue

@node else clause,finally clause,except* clause,The try statement
@anchor{reference/compound_stmts else-clause}@anchor{2734}@anchor{reference/compound_stmts except-else}@anchor{2735}
@subsubsection @code{else} clause


The optional @code{else} clause is executed if the control flow leaves the
@ref{ad6,,try} suite, no exception was raised, and no @ref{44b,,return},
@ref{429,,continue}, or @ref{428,,break} statement was executed.  Exceptions in
the @code{else} clause are not handled by the preceding @ref{447,,except}
clauses.

@geindex keyword;finally

@node finally clause,,else clause,The try statement
@anchor{reference/compound_stmts finally}@anchor{44c}@anchor{reference/compound_stmts finally-clause}@anchor{2736}
@subsubsection @code{finally} clause


If @code{finally} is present, it specifies a “cleanup” handler.  The
@ref{ad6,,try} clause is executed, including any @ref{447,,except}
and @ref{2735,,else} clauses.
If an exception occurs in any of the clauses and is not handled,
the exception is temporarily saved.
The @code{finally} clause is executed.  If there is a saved exception
it is re-raised at the end of the @code{finally} clause.
If the @code{finally} clause raises another exception, the saved exception
is set as the context of the new exception.
If the @code{finally} clause executes a @ref{44b,,return}, @ref{428,,break}
or @ref{429,,continue} statement, the saved exception is discarded. For example,
this function returns 42.

@example
def f():
    try:
        1/0
    finally:
        return 42
@end example

The exception information is not available to the program during execution of
the @code{finally} clause.

@geindex statement;return
@geindex statement;break
@geindex statement;continue

When a @ref{44b,,return}, @ref{428,,break} or @ref{429,,continue} statement is
executed in the @ref{ad6,,try} suite of a @code{try}…@code{finally}
statement, the @code{finally} clause is also executed “on the way out.”

The return value of a function is determined by the last @ref{44b,,return}
statement executed.  Since the @code{finally} clause always executes, a
@code{return} statement executed in the @code{finally} clause will
always be the last one executed. The following function returns “finally”.

@example
def foo():
    try:
        return 'try'
    finally:
        return 'finally'
@end example


Άλλαξε στην έκδοση 3.8: Prior to Python 3.8, a @ref{429,,continue} statement was illegal in the
@code{finally} clause due to a problem with the implementation.



Άλλαξε στην έκδοση 3.14: The compiler emits a @ref{44a,,SyntaxWarning} when a @ref{44b,,return},
@ref{428,,break} or @ref{429,,continue} appears in a @code{finally}
block (see 
@geindex Python Enhancement Proposals; PEP 765
PEP 765@footnote{https://peps.python.org/pep-0765/}).

@anchor{reference/compound_stmts with}@anchor{20a}
@node The with statement,The match statement,The try statement,Compound statements
@anchor{reference/compound_stmts as}@anchor{2737}@anchor{reference/compound_stmts the-with-statement}@anchor{2738}
@subsection The @code{with} statement


@geindex statement;with
@geindex keyword;as
@geindex as;with statement
@geindex @comma{} (comma);with statement
@geindex ; (colon);compound statement

The @ref{20a,,with} statement is used to wrap the execution of a block with
methods defined by a context manager (see section @ref{2572,,Με τους Διαχειριστές Περιβάλλοντος Δήλωσης}).
This allows common @ref{ad6,,try}…@ref{447,,except}…@ref{44c,,finally}
usage patterns to be encapsulated for convenient reuse.

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-with_stmt}@anchor{2721}with_stmt:          "with" ( "(" @ref{2739,,with_stmt_contents} ","? ")" | @ref{2739,,with_stmt_contents} ) ":" @ref{2728,,suite}
@anchor{reference/compound_stmts grammar-token-python-grammar-with_stmt_contents}@anchor{2739}with_stmt_contents: @ref{273a,,with_item} ("," @ref{273a,,with_item})*
@anchor{reference/compound_stmts grammar-token-python-grammar-with_item}@anchor{273a}with_item:          @ref{42a,,expression} ["as" @ref{26fb,,target}]
@end example

The execution of the @ref{20a,,with} statement with one «item» proceeds as follows:


@enumerate 

@item 
The context expression (the expression given in the
@ref{273a,,with_item}) is evaluated to obtain a context manager.

@item 
The context manager’s @ref{9c6,,__enter__()} is loaded for later use.

@item 
The context manager’s @ref{16a5,,__exit__()} is loaded for later use.

@item 
The context manager’s @ref{9c6,,__enter__()} method is invoked.

@item 
If a target was included in the @ref{20a,,with} statement, the return value
from @ref{9c6,,__enter__()} is assigned to it.

@cartouche
@quotation Σημείωση 
The @ref{20a,,with} statement guarantees that if the @ref{9c6,,__enter__()}
method returns without an error, then @ref{16a5,,__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 
The suite is executed.

@item 
The context manager’s @ref{16a5,,__exit__()} method is invoked.  If an exception
caused the suite to be exited, its type, value, and traceback are passed as
arguments to @code{__exit__()}. Otherwise, three @ref{a65,,None} arguments are
supplied.

If the suite was exited due to an exception, and the return value from the
@ref{16a5,,__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{20a,,with} statement.

If the suite was exited for any reason other than an exception, the return
value from @ref{16a5,,__exit__()} is ignored, and execution proceeds at the normal
location for the kind of exit that was taken.
@end enumerate

The following code:

@example
with EXPRESSION as TARGET:
    SUITE
@end example

is semantically equivalent to:

@example
manager = (EXPRESSION)
enter = manager.__enter__
exit = manager.__exit__
value = enter()
hit_except = False

try:
    TARGET = value
    SUITE
except:
    hit_except = True
    if not exit(*sys.exc_info()):
        raise
finally:
    if not hit_except:
        exit(None, None, None)
@end example

except that implicit @ref{25a6,,special method lookup} is used
for @ref{9c6,,__enter__()} and @ref{16a5,,__exit__()}.

With more than one item, the context managers are processed as if multiple
@ref{20a,,with} statements were nested:

@example
with A() as a, B() as b:
    SUITE
@end example

is semantically equivalent to:

@example
with A() as a:
    with B() as b:
        SUITE
@end example

You can also write multi-item context managers in multiple lines if
the items are surrounded by parentheses. For example:

@example
with (
    A() as a,
    B() as b,
):
    SUITE
@end example


Άλλαξε στην έκδοση 3.1: Support for multiple context expressions.



Άλλαξε στην έκδοση 3.10: Support for using grouping parentheses to break the statement in multiple lines.



@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 343

@item PEP 343@footnote{https://peps.python.org/pep-0343/} - The «with» statement

The specification, background, and examples for the Python @ref{20a,,with}
statement.
@end table

@anchor{reference/compound_stmts match}@anchor{1d4}
@node The match statement,Function definitions,The with statement,Compound statements
@anchor{reference/compound_stmts case}@anchor{273b}@anchor{reference/compound_stmts the-match-statement}@anchor{273c}
@subsection The @code{match} statement


@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


Added in version 3.10.


The match statement is used for pattern matching.  Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-match_stmt}@anchor{2722}match_stmt:   'match' @ref{273d,,subject_expr} ":" NEWLINE INDENT @ref{273e,,case_block}+ DEDENT
@anchor{reference/compound_stmts grammar-token-python-grammar-subject_expr}@anchor{273d}subject_expr: `!star_named_expression` "," `!star_named_expressions`?
              | `!named_expression`
@anchor{reference/compound_stmts grammar-token-python-grammar-case_block}@anchor{273e}case_block:   'case' @ref{273f,,patterns} [@ref{2740,,guard}] ":" `!block`
@end example

@cartouche
@quotation Σημείωση 
This section uses single quotes to denote
@ref{be6,,soft keywords}.
@end quotation
@end cartouche

Pattern matching takes a pattern as input (following @code{case}) and a subject
value (following @code{match}).  The pattern (which may contain subpatterns) is
matched against the subject value.  The outcomes are:


@itemize *

@item 
A match success or failure (also termed a pattern success or failure).

@item 
Possible binding of matched values to a name.  The prerequisites for this are
further discussed below.
@end itemize

The @code{match} and @code{case} keywords are @ref{be6,,soft keywords}.


@subsubheading Δείτε επίσης



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/} – Structural Pattern Matching: Specification

@item 
@geindex Python Enhancement Proposals; PEP 636
PEP 636@footnote{https://peps.python.org/pep-0636/} – Structural Pattern Matching: Tutorial
@end itemize


@menu
* Overview:: 
* Guards:: 
* Irrefutable Case Blocks:: 
* Patterns:: 

@end menu

@node Overview,Guards,,The match statement
@anchor{reference/compound_stmts overview}@anchor{2741}
@subsubsection Overview


Here’s an overview of the logical flow of a match statement:


@enumerate 

@item 
The subject expression @code{subject_expr} is evaluated and a resulting subject
value obtained. If the subject expression contains a comma, a tuple is
constructed using @ref{2742,,the standard rules}.

@item 
Each pattern in a @code{case_block} is attempted to match with the subject value. The
specific rules for success or failure are described below. The match attempt can also
bind some or all of the standalone names within the pattern. The precise
pattern binding rules vary per pattern type and are
specified below.  `Name bindings made during a successful pattern match
outlive the executed block and can be used after the match statement'.

@cartouche
@quotation Σημείωση 
During failed pattern matches, some subpatterns may succeed.  Do not
rely on bindings being made for a failed match.  Conversely, do not
rely on variables remaining unchanged after a failed match.  The exact
behavior is dependent on implementation and may vary.  This is an
intentional decision made to allow different implementations to add
optimizations.
@end quotation
@end cartouche

@item 
If the pattern succeeds, the corresponding guard (if present) is evaluated. In
this case all name bindings are guaranteed to have happened.


@itemize *

@item 
If the guard evaluates as true or is missing, the @code{block} inside
@code{case_block} is executed.

@item 
Otherwise, the next @code{case_block} is attempted as described above.

@item 
If there are no further case blocks, the match statement is completed.
@end itemize
@end enumerate

@cartouche
@quotation Σημείωση 
Users should generally never rely on a pattern being evaluated.  Depending on
implementation, the interpreter may cache values or use other optimizations
which skip repeated evaluations.
@end quotation
@end cartouche

A sample match statement:

@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

In this case, @code{if flag} is a guard.  Read more about that in the next section.

@node Guards,Irrefutable Case Blocks,Overview,The match statement
@anchor{reference/compound_stmts guards}@anchor{2743}
@subsubsection Guards


@geindex guard

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-guard}@anchor{2740}guard: "if" `!named_expression`
@end example

A @code{guard} (which is part of the @code{case}) must succeed for code inside
the @code{case} block to execute.  It takes the form: @ref{322,,if} followed by an
expression.

The logical flow of a @code{case} block with a @code{guard} follows:


@enumerate 

@item 
Check that the pattern in the @code{case} block succeeded.  If the pattern
failed, the @code{guard} is not evaluated and the next @code{case} block is
checked.

@item 
If the pattern succeeded, evaluate the @code{guard}.


@itemize *

@item 
If the @code{guard} condition evaluates as true, the case block is
selected.

@item 
If the @code{guard} condition evaluates as false, the case block is not
selected.

@item 
If the @code{guard} raises an exception during evaluation, the exception
bubbles up.
@end itemize
@end enumerate

Guards are allowed to have side effects as they are expressions.  Guard
evaluation must proceed from the first to the last case block, one at a time,
skipping case blocks whose pattern(s) don’t all succeed. (I.e.,
guard evaluation must happen in order.) Guard evaluation must stop once a case
block is selected.

@node Irrefutable Case Blocks,Patterns,Guards,The match statement
@anchor{reference/compound_stmts irrefutable-case}@anchor{2744}@anchor{reference/compound_stmts irrefutable-case-blocks}@anchor{2745}
@subsubsection Irrefutable Case Blocks


@geindex irrefutable case block
@geindex case block

An irrefutable case block is a match-all case block.  A match statement may have
at most one irrefutable case block, and it must be last.

A case block is considered irrefutable if it has no guard and its pattern is
irrefutable.  A pattern is considered irrefutable if we can prove from its
syntax alone that it will always succeed.  Only the following patterns are
irrefutable:


@itemize *

@item 
@ref{2746,,AS Patterns} whose left-hand side is irrefutable

@item 
@ref{2747,,OR Patterns} containing at least one irrefutable pattern

@item 
@ref{2748,,Capture Patterns}

@item 
@ref{be7,,Wildcard Patterns}

@item 
parenthesized irrefutable patterns
@end itemize

@node Patterns,,Irrefutable Case Blocks,The match statement
@anchor{reference/compound_stmts patterns}@anchor{2749}
@subsubsection Patterns


@geindex ! patterns
@geindex AS pattern@comma{} OR pattern@comma{} capture pattern@comma{} wildcard pattern

@cartouche
@quotation Σημείωση 
This section uses grammar notations beyond standard EBNF:


@itemize *

@item 
the notation @code{SEP.RULE+} is shorthand for @code{RULE (SEP RULE)*}

@item 
the notation @code{!RULE} is shorthand for a negative lookahead assertion
@end itemize
@end quotation
@end cartouche

The top-level syntax for @code{patterns} is:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-patterns}@anchor{273f}patterns:       @ref{274a,,open_sequence_pattern} | @ref{274b,,pattern}
@anchor{reference/compound_stmts grammar-token-python-grammar-pattern}@anchor{274b}pattern:        @ref{274c,,as_pattern} | @ref{274d,,or_pattern}
@anchor{reference/compound_stmts grammar-token-python-grammar-closed_pattern}@anchor{274e}closed_pattern: | @ref{274f,,literal_pattern}
                | @ref{2750,,capture_pattern}
                | @ref{2751,,wildcard_pattern}
                | @ref{2752,,value_pattern}
                | @ref{2753,,group_pattern}
                | @ref{2754,,sequence_pattern}
                | @ref{2755,,mapping_pattern}
                | @ref{2756,,class_pattern}
@end example

The descriptions below will include a description «in simple terms» of what a pattern
does for illustration purposes (credits to Raymond Hettinger for a document that
inspired most of the descriptions). Note that these descriptions are purely for
illustration purposes and `may not' reflect
the underlying implementation.  Furthermore, they do not cover all valid forms.

@menu
* OR Patterns:: 
* AS Patterns:: 
* Literal Patterns:: 
* Capture Patterns:: 
* Wildcard Patterns:: 
* Value Patterns:: 
* Group Patterns:: 
* Sequence Patterns:: 
* Mapping Patterns:: 
* Class Patterns:: 

@end menu

@node OR Patterns,AS Patterns,,Patterns
@anchor{reference/compound_stmts id3}@anchor{2757}@anchor{reference/compound_stmts or-patterns}@anchor{2747}
@subsubsection OR Patterns


An OR pattern is two or more patterns separated by vertical
bars @code{|}.  Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-or_pattern}@anchor{274d}or_pattern: "|".@ref{274e,,closed_pattern}+
@end example

Only the final subpattern may be @ref{2744,,irrefutable}, and each
subpattern must bind the same set of names to avoid ambiguity.

An OR pattern matches each of its subpatterns in turn to the subject value,
until one succeeds.  The OR pattern is then considered successful.  Otherwise,
if none of the subpatterns succeed, the OR pattern fails.

In simple terms, @code{P1 | P2 | ...} will try to match @code{P1}, if it fails it will try to
match @code{P2}, succeeding immediately if any succeeds, failing otherwise.

@node AS Patterns,Literal Patterns,OR Patterns,Patterns
@anchor{reference/compound_stmts as-patterns}@anchor{2746}@anchor{reference/compound_stmts id4}@anchor{2758}
@subsubsection AS Patterns


An AS pattern matches an OR pattern on the left of the @ref{2737,,as}
keyword against a subject.  Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-as_pattern}@anchor{274c}as_pattern: @ref{274d,,or_pattern} "as" @ref{2750,,capture_pattern}
@end example

If the OR pattern fails, the AS pattern fails.  Otherwise, the AS pattern binds
the subject to the name on the right of the as keyword and succeeds.
@code{capture_pattern} cannot be a @code{_}.

In simple terms @code{P as NAME} will match with @code{P}, and on success it will
set @code{NAME = <subject>}.

@node Literal Patterns,Capture Patterns,AS Patterns,Patterns
@anchor{reference/compound_stmts id5}@anchor{2759}@anchor{reference/compound_stmts literal-patterns}@anchor{275a}
@subsubsection Literal Patterns


A literal pattern corresponds to most
@ref{24ba,,literals} in Python.  Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-literal_pattern}@anchor{274f}literal_pattern: @ref{275b,,signed_number}
                 | @ref{275b,,signed_number} "+" NUMBER
                 | @ref{275b,,signed_number} "-" NUMBER
                 | @ref{2674,,strings}
                 | "None"
                 | "True"
                 | "False"
@anchor{reference/compound_stmts grammar-token-python-grammar-signed_number}@anchor{275b}signed_number:   ["+" | "-"] NUMBER
@end example

The rule @code{strings} and the token @code{NUMBER} are defined in the
@ref{275c,,standard Python grammar}.  Triple-quoted strings are
supported.  Raw strings and byte strings are supported.  @ref{43a,,f-strings}
and @ref{1a50,,t-strings} are not supported.

The forms @code{signed_number '+' NUMBER} and @code{signed_number '-' NUMBER} are
for expressing @ref{250c,,complex numbers}; they require a real number
on the left and an imaginary number on the right. E.g. @code{3 + 4j}.

In simple terms, @code{LITERAL} will succeed only if @code{<subject> == LITERAL}. For
the singletons @code{None}, @code{True} and @code{False}, the @ref{324,,is} operator is used.

@node Capture Patterns,Wildcard Patterns,Literal Patterns,Patterns
@anchor{reference/compound_stmts capture-patterns}@anchor{2748}@anchor{reference/compound_stmts id6}@anchor{275d}
@subsubsection Capture Patterns


A capture pattern binds the subject value to a name.
Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-capture_pattern}@anchor{2750}capture_pattern: !'_' NAME
@end example

A single underscore @code{_} is not a capture pattern (this is what @code{!'_'}
expresses). It is instead treated as a
@ref{2751,,wildcard_pattern}.

In a given pattern, a given name can only be bound once.  E.g.
@code{case x, x: ...} is invalid while @code{case [x] | x: ...} is allowed.

Capture patterns always succeed.  The binding follows scoping rules
established by the assignment expression operator in 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/}; the
name becomes a local variable in the closest containing function scope unless
there’s an applicable @ref{6b5,,global} or @ref{164c,,nonlocal} statement.

In simple terms @code{NAME} will always succeed and it will set @code{NAME = <subject>}.

@node Wildcard Patterns,Value Patterns,Capture Patterns,Patterns
@anchor{reference/compound_stmts id7}@anchor{275e}@anchor{reference/compound_stmts wildcard-patterns}@anchor{be7}
@subsubsection Wildcard Patterns


A wildcard pattern always succeeds (matches anything)
and binds no name.  Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-wildcard_pattern}@anchor{2751}wildcard_pattern: '_'
@end example

@code{_} is a @ref{be6,,soft keyword} within any pattern,
but only within patterns.  It is an identifier, as usual, even within
@code{match} subject expressions, @code{guard}s, and @code{case} blocks.

In simple terms, @code{_} will always succeed.

@node Value Patterns,Group Patterns,Wildcard Patterns,Patterns
@anchor{reference/compound_stmts id8}@anchor{275f}@anchor{reference/compound_stmts value-patterns}@anchor{2760}
@subsubsection Value Patterns


A value pattern represents a named value in Python.
Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-value_pattern}@anchor{2752}value_pattern: @ref{2761,,attr}
@anchor{reference/compound_stmts grammar-token-python-grammar-attr}@anchor{2761}attr:          @ref{2762,,name_or_attr} "." NAME
@anchor{reference/compound_stmts grammar-token-python-grammar-name_or_attr}@anchor{2762}name_or_attr:  @ref{2761,,attr} | NAME
@end example

The dotted name in the pattern is looked up using standard Python
@ref{2620,,name resolution rules}.  The pattern succeeds if the
value found compares equal to the subject value (using the @code{==} equality
operator).

In simple terms @code{NAME1.NAME2} will succeed only if @code{<subject> == NAME1.NAME2}

@cartouche
@quotation Σημείωση 
If the same value occurs multiple times in the same match statement, the
interpreter may cache the first value found and reuse it rather than repeat
the same lookup.  This cache is strictly tied to a given execution of a
given match statement.
@end quotation
@end cartouche

@node Group Patterns,Sequence Patterns,Value Patterns,Patterns
@anchor{reference/compound_stmts group-patterns}@anchor{2763}@anchor{reference/compound_stmts id9}@anchor{2764}
@subsubsection Group Patterns


A group pattern allows users to add parentheses around patterns to
emphasize the intended grouping.  Otherwise, it has no additional syntax.
Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-group_pattern}@anchor{2753}group_pattern: "(" @ref{274b,,pattern} ")"
@end example

In simple terms @code{(P)} has the same effect as @code{P}.

@node Sequence Patterns,Mapping Patterns,Group Patterns,Patterns
@anchor{reference/compound_stmts id10}@anchor{2765}@anchor{reference/compound_stmts sequence-patterns}@anchor{2766}
@subsubsection Sequence Patterns


A sequence pattern contains several subpatterns to be matched against sequence elements.
The syntax is similar to the unpacking of a list or tuple.

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-sequence_pattern}@anchor{2754}sequence_pattern:       "[" [@ref{2767,,maybe_sequence_pattern}] "]"
                        | "(" [@ref{274a,,open_sequence_pattern}] ")"
@anchor{reference/compound_stmts grammar-token-python-grammar-open_sequence_pattern}@anchor{274a}open_sequence_pattern:  @ref{2768,,maybe_star_pattern} "," [@ref{2767,,maybe_sequence_pattern}]
@anchor{reference/compound_stmts grammar-token-python-grammar-maybe_sequence_pattern}@anchor{2767}maybe_sequence_pattern: ",".@ref{2768,,maybe_star_pattern}+ ","?
@anchor{reference/compound_stmts grammar-token-python-grammar-maybe_star_pattern}@anchor{2768}maybe_star_pattern:     @ref{2769,,star_pattern} | @ref{274b,,pattern}
@anchor{reference/compound_stmts grammar-token-python-grammar-star_pattern}@anchor{2769}star_pattern:           "*" (@ref{2750,,capture_pattern} | @ref{2751,,wildcard_pattern})
@end example

There is no difference if parentheses  or square brackets
are used for sequence patterns (i.e. @code{(...)} vs @code{[...]} ).

@cartouche
@quotation Σημείωση 
A single pattern enclosed in parentheses without a trailing comma
(e.g. @code{(3 | 4)}) is a @ref{2763,,group pattern}.
While a single pattern enclosed in square brackets (e.g. @code{[3 | 4]}) is
still a sequence pattern.
@end quotation
@end cartouche

At most one star subpattern may be in a sequence pattern.  The star subpattern
may occur in any position. If no star subpattern is present, the sequence
pattern is a fixed-length sequence pattern; otherwise it is a variable-length
sequence pattern.

The following is the logical flow for matching a sequence pattern against a
subject value:


@enumerate 

@item 
If the subject value is not a sequence @footnote{
In pattern matching, a sequence is defined as one of the following:


@itemize *

@item 
a class that inherits from @ref{156d,,collections.abc.Sequence}

@item 
a Python class that has been registered as @ref{156d,,collections.abc.Sequence}

@item 
a builtin class that has its (CPython) @ref{1e50,,Py_TPFLAGS_SEQUENCE} bit set

@item 
a class that inherits from any of the above
@end itemize

The following standard library classes are sequences:


@itemize *

@item 
@ref{6c5,,array.array}

@item 
@ref{9d6,,collections.deque}

@item 
@ref{4d9,,list}

@item 
@ref{1d2,,memoryview}

@item 
@ref{d0f,,range}

@item 
@ref{1ce,,tuple}
@end itemize

@cartouche
@quotation Σημείωση 
Subject values of type @code{str}, @code{bytes}, and @code{bytearray}
do not match sequence patterns.
@end quotation
@end cartouche
}, the sequence pattern
fails.

@item 
If the subject value is an instance of @code{str}, @code{bytes} or @code{bytearray}
the sequence pattern fails.

@item 
The subsequent steps depend on whether the sequence pattern is fixed or
variable-length.

If the sequence pattern is fixed-length:


@enumerate 

@item 
If the length of the subject sequence is not equal to the number of
subpatterns, the sequence pattern fails

@item 
Subpatterns in the sequence pattern are matched to their corresponding
items in the subject sequence from left to right.  Matching stops as soon
as a subpattern fails.  If all subpatterns succeed in matching their
corresponding item, the sequence pattern succeeds.
@end enumerate

Otherwise, if the sequence pattern is variable-length:


@enumerate 

@item 
If the length of the subject sequence is less than the number of non-star
subpatterns, the sequence pattern fails.

@item 
The leading non-star subpatterns are matched to their corresponding items
as for fixed-length sequences.

@item 
If the previous step succeeds, the star subpattern matches a list formed
of the remaining subject items, excluding the remaining items
corresponding to non-star subpatterns following the star subpattern.

@item 
Remaining non-star subpatterns are matched to their corresponding subject
items, as for a fixed-length sequence.
@end enumerate

@cartouche
@quotation Σημείωση 
The length of the subject sequence is obtained via
@ref{a1f,,len()} (i.e. via the @ref{1989,,__len__()} protocol).
This length may be cached by the interpreter in a similar manner as
@ref{2760,,value patterns}.
@end quotation
@end cartouche
@end enumerate

In simple terms @code{[P1, P2, P3,} … @code{, P<N>]} matches only if all the following
happens:


@itemize *

@item 
check @code{<subject>} is a sequence

@item 
@code{len(subject) == <N>}

@item 
@code{P1} matches @code{<subject>[0]} (note that this match can also bind names)

@item 
@code{P2} matches @code{<subject>[1]} (note that this match can also bind names)

@item 
… and so on for the corresponding pattern/element.
@end itemize

@node Mapping Patterns,Class Patterns,Sequence Patterns,Patterns
@anchor{reference/compound_stmts id12}@anchor{276a}@anchor{reference/compound_stmts mapping-patterns}@anchor{276b}
@subsubsection Mapping Patterns


A mapping pattern contains one or more key-value patterns.  The syntax is
similar to the construction of a dictionary.
Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-mapping_pattern}@anchor{2755}mapping_pattern:     "@{" [@ref{276c,,items_pattern}] "@}"
@anchor{reference/compound_stmts grammar-token-python-grammar-items_pattern}@anchor{276c}items_pattern:       ",".@ref{276d,,key_value_pattern}+ ","?
@anchor{reference/compound_stmts grammar-token-python-grammar-key_value_pattern}@anchor{276d}key_value_pattern:   (@ref{274f,,literal_pattern} | @ref{2752,,value_pattern}) ":" @ref{274b,,pattern}
                     | @ref{276e,,double_star_pattern}
@anchor{reference/compound_stmts grammar-token-python-grammar-double_star_pattern}@anchor{276e}double_star_pattern: "**" @ref{2750,,capture_pattern}
@end example

At most one double star pattern may be in a mapping pattern.  The double star
pattern must be the last subpattern in the mapping pattern.

Duplicate keys in mapping patterns are disallowed. Duplicate literal keys will
raise a @ref{17e,,SyntaxError}. Two keys that otherwise have the same value will
raise a @ref{277,,ValueError} at runtime.

The following is the logical flow for matching a mapping pattern against a
subject value:


@enumerate 

@item 
If the subject value is not a mapping @footnote{
In pattern matching, a mapping is defined as one of the following:


@itemize *

@item 
a class that inherits from @ref{c9c,,collections.abc.Mapping}

@item 
a Python class that has been registered as @ref{c9c,,collections.abc.Mapping}

@item 
a builtin class that has its (CPython) @ref{1e4f,,Py_TPFLAGS_MAPPING} bit set

@item 
a class that inherits from any of the above
@end itemize

The standard library classes @ref{188,,dict} and @ref{189,,types.MappingProxyType}
are mappings.
},the mapping pattern fails.

@item 
If every key given in the mapping pattern is present in the subject mapping,
and the pattern for each key matches the corresponding item of the subject
mapping, the mapping pattern succeeds.

@item 
If duplicate keys are detected in the mapping pattern, the pattern is
considered invalid. A @ref{17e,,SyntaxError} is raised for duplicate literal
values; or a @ref{277,,ValueError} for named keys of the same value.
@end enumerate

@cartouche
@quotation Σημείωση 
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 @ref{1566,,__missing__()}
or @ref{787,,__getitem__()}.
@end quotation
@end cartouche

In simple terms @code{@{KEY1: P1, KEY2: P2, ... @}} matches only if all the following
happens:


@itemize *

@item 
check @code{<subject>} is a mapping

@item 
@code{KEY1 in <subject>}

@item 
@code{P1} matches @code{<subject>[KEY1]}

@item 
… and so on for the corresponding KEY/pattern pair.
@end itemize

@node Class Patterns,,Mapping Patterns,Patterns
@anchor{reference/compound_stmts class-patterns}@anchor{276f}@anchor{reference/compound_stmts id14}@anchor{2770}
@subsubsection Class Patterns


A class pattern represents a class and its positional and keyword arguments
(if any).  Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-class_pattern}@anchor{2756}class_pattern:       @ref{2762,,name_or_attr} "(" [@ref{2771,,pattern_arguments} ","?] ")"
@anchor{reference/compound_stmts grammar-token-python-grammar-pattern_arguments}@anchor{2771}pattern_arguments:   @ref{2772,,positional_patterns} ["," @ref{2773,,keyword_patterns}]
                     | @ref{2773,,keyword_patterns}
@anchor{reference/compound_stmts grammar-token-python-grammar-positional_patterns}@anchor{2772}positional_patterns: ",".@ref{274b,,pattern}+
@anchor{reference/compound_stmts grammar-token-python-grammar-keyword_patterns}@anchor{2773}keyword_patterns:    ",".@ref{2774,,keyword_pattern}+
@anchor{reference/compound_stmts grammar-token-python-grammar-keyword_pattern}@anchor{2774}keyword_pattern:     NAME "=" @ref{274b,,pattern}
@end example

The same keyword should not be repeated in class patterns.

The following is the logical flow for matching a class pattern against a
subject value:


@enumerate 

@item 
If @code{name_or_attr} is not an instance of the builtin @ref{186,,type} , raise
@ref{291,,TypeError}.

@item 
If the subject value is not an instance of @code{name_or_attr} (tested via
@ref{2ef,,isinstance()}), the class pattern fails.

@item 
If no pattern arguments are present, the pattern succeeds.  Otherwise,
the subsequent steps depend on whether keyword or positional argument patterns
are present.

For a number of built-in types (specified below), a single positional
subpattern is accepted which will match the entire subject; for these types
keyword patterns also work as for other types.

If only keyword patterns are present, they are processed as follows,
one by one:


@enumerate 

@item 
The keyword is looked up as an attribute on the subject.


@itemize *

@item 
If this raises an exception other than @ref{1a9,,AttributeError}, the
exception bubbles up.

@item 
If this raises @ref{1a9,,AttributeError}, the class pattern has failed.

@item 
Else, the subpattern associated with the keyword pattern is matched
against the subject’s attribute value.  If this fails, the class
pattern fails; if this succeeds, the match proceeds to the next keyword.
@end itemize

@item 
If all keyword patterns succeed, the class pattern succeeds.
@end enumerate

If any positional patterns are present, they are converted to keyword
patterns using the @ref{1e6c,,__match_args__} attribute on the class
@code{name_or_attr} before matching:


@enumerate 

@item 
The equivalent of @code{getattr(cls, "__match_args__", ())} is called.


@itemize *

@item 
If this raises an exception, the exception bubbles up.

@item 
If the returned value is not a tuple, the conversion fails and
@ref{291,,TypeError} is raised.

@item 
If there are more positional patterns than @code{len(cls.__match_args__)},
@ref{291,,TypeError} is raised.

@item 
Otherwise, positional pattern @code{i} is converted to a keyword pattern
using @code{__match_args__[i]} as the keyword.  @code{__match_args__[i]} must
be a string; if not @ref{291,,TypeError} is raised.

@item 
If there are duplicate keywords, @ref{291,,TypeError} is raised.
@end itemize


@subsubheading Δείτε επίσης


@ref{2602,,Προσαρμογή ορισμάτων θέσης στην αντιστοίχιση προτύπων κλάσης}


@item 
Once all positional patterns have been converted to keyword patterns,
the match proceeds as if there were only keyword patterns.
@end enumerate

For the following built-in types the handling of positional subpatterns is
different:


@itemize *

@item 
@ref{5ef,,bool}

@item 
@ref{1c6,,bytearray}

@item 
@ref{1c7,,bytes}

@item 
@ref{188,,dict}

@item 
@ref{327,,float}

@item 
@ref{9d4,,frozenset}

@item 
@ref{326,,int}

@item 
@ref{4d9,,list}

@item 
@ref{42b,,set}

@item 
@ref{1df,,str}

@item 
@ref{1ce,,tuple}
@end itemize

These classes accept a single positional argument, and the pattern there is matched
against the whole object rather than an attribute. For example @code{int(0|1)} matches
the value @code{0}, but not the value @code{0.0}.
@end enumerate

In simple terms @code{CLS(P1, attr=P2)} matches only if the following happens:


@itemize *

@item 
@code{isinstance(<subject>, CLS)}

@item 
convert @code{P1} to a keyword pattern using @code{CLS.__match_args__}

@item 
For each keyword argument @code{attr=P2}:


@itemize *

@item 
@code{hasattr(<subject>, "attr")}

@item 
@code{P2} matches @code{<subject>.attr}
@end itemize

@item 
… and so on for the corresponding keyword argument/pattern pair.
@end itemize


@subsubheading Δείτε επίσης



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/} – Structural Pattern Matching: Specification

@item 
@geindex Python Enhancement Proposals; PEP 636
PEP 636@footnote{https://peps.python.org/pep-0636/} – Structural Pattern Matching: Tutorial
@end itemize


@geindex parameter;function definition
@anchor{reference/compound_stmts function}@anchor{2206}
@node Function definitions,Class definitions,The match statement,Compound statements
@anchor{reference/compound_stmts def}@anchor{17fc}@anchor{reference/compound_stmts function-definitions}@anchor{2775}
@subsection Function definitions


@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

A function definition defines a user-defined function object (see section
@ref{2520,,Η τυπική ιεραρχία τύπου}):

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-funcdef}@anchor{2723}funcdef:                   [@ref{2776,,decorators}] "def" @ref{2777,,funcname} [@ref{2717,,type_params}] "(" [@ref{26da,,parameter_list}] ")"
                           ["->" @ref{42a,,expression}] ":" @ref{2728,,suite}
@anchor{reference/compound_stmts grammar-token-python-grammar-decorators}@anchor{2776}decorators:                @ref{2778,,decorator}+
@anchor{reference/compound_stmts grammar-token-python-grammar-decorator}@anchor{2778}decorator:                 "@@" @ref{2623,,assignment_expression} NEWLINE
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter_list}@anchor{26da}parameter_list:            @ref{2779,,defparameter} ("," @ref{2779,,defparameter})* "," "/" ["," [@ref{277a,,parameter_list_no_posonly}]]
                             | @ref{277a,,parameter_list_no_posonly}
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter_list_no_posonly}@anchor{277a}parameter_list_no_posonly: @ref{2779,,defparameter} ("," @ref{2779,,defparameter})* ["," [@ref{277b,,parameter_list_starargs}]]
                           | @ref{277b,,parameter_list_starargs}
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter_list_starargs}@anchor{277b}parameter_list_starargs:   "*" [@ref{277c,,star_parameter}] ("," @ref{2779,,defparameter})* ["," [@ref{277d,,parameter_star_kwargs}]]
                           | "*" ("," @ref{2779,,defparameter})+ ["," [@ref{277d,,parameter_star_kwargs}]]
                           | @ref{277d,,parameter_star_kwargs}
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter_star_kwargs}@anchor{277d}parameter_star_kwargs:     "**" @ref{277e,,parameter} [","]
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter}@anchor{277e}parameter:                 @ref{24b2,,identifier} [":" @ref{42a,,expression}]
@anchor{reference/compound_stmts grammar-token-python-grammar-star_parameter}@anchor{277c}star_parameter:            @ref{24b2,,identifier} [":" ["*"] @ref{42a,,expression}]
@anchor{reference/compound_stmts grammar-token-python-grammar-defparameter}@anchor{2779}defparameter:              @ref{277e,,parameter} ["=" @ref{42a,,expression}]
@anchor{reference/compound_stmts grammar-token-python-grammar-funcname}@anchor{2777}funcname:                  @ref{24b2,,identifier}
@end example

A function definition is an executable statement.  Its execution binds the
function name in the current local namespace to a function object (a wrapper
around the executable code for the function).  This function object contains a
reference to the current global namespace as the global namespace to be used
when the function is called.

The function definition does not execute the function body; this gets executed
only when the function is called. @footnote{
A string literal appearing as the first statement in the function body is
transformed into the function’s @ref{1582,,__doc__} attribute and
therefore the function’s @ref{24dd,,docstring}.
}

@geindex @@ (at);function definition

A function definition may be wrapped by one or more @ref{b18,,decorator} expressions.
Decorator expressions are evaluated when the function is defined, in the scope
that contains the function definition.  The result must be a callable, which is
invoked with the function object as the only argument. The returned value is
bound to the function name instead of the function object.  Multiple decorators
are applied in nested fashion. For example, the following code

@example
@@f1(arg)
@@f2
def func(): pass
@end example

is roughly equivalent to

@example
def func(): pass
func = f1(arg)(f2(func))
@end example

except that the original function is not temporarily bound to the name @code{func}.


Άλλαξε στην έκδοση 3.9: Functions may be decorated with any valid
@ref{2623,,assignment_expression}. Previously, the grammar was
much more restrictive; see 
@geindex Python Enhancement Proposals; PEP 614
PEP 614@footnote{https://peps.python.org/pep-0614/} for details.


A list of @ref{7a5,,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{253e,,__type_params__}
attribute. See @ref{86f,,Generic functions} for more.


Άλλαξε στην έκδοση 3.12: Type parameter lists are new in Python 3.12.


@geindex default;parameter;value
@geindex argument;function definition
@geindex = (equals);function definition

When one or more @ref{253c,,parameters} have the form `parameter' @code{=}
`expression', the function is said to have «default parameter values.»  For a
parameter with a default value, the corresponding @ref{867,,argument} may be
omitted from a call, in which
case the parameter’s default value is substituted.  If a parameter has a default
value, all following parameters up until the «@code{*}» must also have a default
value — this is a syntactic restriction that is not expressed by the grammar.

`Default parameter values are evaluated from left to right when the function
definition is executed.' This means that the expression is evaluated once, when
the function is defined, and that the same «pre-computed» value is used for each
call.  This is especially important to understand when a default parameter value is a
mutable object, such as a list or a dictionary: if the function modifies the
object (e.g. by appending an item to a list), the default parameter value is in effect
modified.  This is generally not what was intended.  A way around this is to use
@code{None} as the default, and explicitly test for it in the body of the function,
e.g.:

@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

Function call semantics are described in more detail in section @ref{1136,,Calls}. A
function call always assigns values to all parameters mentioned in the parameter
list, either from positional arguments, from keyword arguments, or from default
values.  If the form «@code{*identifier}» is present, it is initialized to a tuple
receiving any excess positional parameters, defaulting to the empty tuple.
If the form «@code{**identifier}» is present, it is initialized to a new
ordered mapping receiving any excess keyword arguments, defaulting to a
new empty mapping of the same type.  Parameters after «@code{*}» or
«@code{*identifier}» are keyword-only parameters and may only be passed
by keyword arguments.  Parameters before «@code{/}» are positional-only parameters
and may only be passed by positional arguments.


Άλλαξε στην έκδοση 3.8: The @code{/} function parameter syntax may be used to indicate positional-only
parameters. See 
@geindex Python Enhancement Proposals; PEP 570
PEP 570@footnote{https://peps.python.org/pep-0570/} for details.


@geindex function;annotations
@geindex ->;function annotations
@geindex ; (colon);function annotations

Parameters may have an @ref{2207,,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. See @ref{277f,,Annotations} for more information on annotations.


Άλλαξε στην έκδοση 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

It is also possible to create anonymous functions (functions not bound to a
name), for immediate use in expressions.  This uses lambda expressions, described in
section @ref{1642,,Lambdas}.  Note that the lambda expression is merely a shorthand for a
simplified function definition; a function defined in a «@ref{17fc,,def}»
statement can be passed around or assigned to another name just like a function
defined by a lambda expression.  The «@code{def}» form is actually more powerful
since it allows the execution of multiple statements and annotations.

`Programmer’s note:' Functions are first-class objects.  A «@code{def}» statement
executed inside a function definition defines a local function that can be
returned or passed around.  Free variables used in the nested function can
access the local variables of the function containing the def.  See section
@ref{2537,,Ονομασία και σύνδεση} for details.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 3107

@item PEP 3107@footnote{https://peps.python.org/pep-3107/} - Function Annotations

The original specification for function annotations.

@geindex Python Enhancement Proposals; PEP 484

@item PEP 484@footnote{https://peps.python.org/pep-0484/} - Type Hints

Definition of a standard meaning for annotations: type hints.

@geindex Python Enhancement Proposals; PEP 526

@item PEP 526@footnote{https://peps.python.org/pep-0526/} - Syntax for Variable Annotations

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/} - Postponed Evaluation of Annotations

Support for forward references within annotations by preserving
annotations in a string form at runtime instead of eager evaluation.

@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 Class definitions,Coroutines<2>,Function definitions,Compound statements
@anchor{reference/compound_stmts class}@anchor{167c}@anchor{reference/compound_stmts class-definitions}@anchor{2780}
@subsection Class definitions


@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

A class definition defines a class object (see section @ref{2520,,Η τυπική ιεραρχία τύπου}):

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-classdef}@anchor{2724}classdef:    [@ref{2776,,decorators}] "class" @ref{2781,,classname} [@ref{2717,,type_params}] [@ref{2782,,inheritance}] ":" @ref{2728,,suite}
@anchor{reference/compound_stmts grammar-token-python-grammar-inheritance}@anchor{2782}inheritance: "(" [@ref{26af,,argument_list}] ")"
@anchor{reference/compound_stmts grammar-token-python-grammar-classname}@anchor{2781}classname:   @ref{24b2,,identifier}
@end example

A class definition is an executable statement.  The inheritance list usually
gives a list of base classes (see @ref{25b3,,Μετα-κλάσεις} for more advanced uses), so
each item in the list should evaluate to a class object which allows
subclassing.  Classes without an inheritance list inherit, by default, from the
base class @ref{e4d,,object}; hence,

@example
class Foo:
    pass
@end example

is equivalent to

@example
class Foo(object):
    pass
@end example

There may be one or more base classes; see @ref{2291,,Multiple inheritance} below for more
information.

The class’s suite is then executed in a new execution frame (see @ref{2537,,Ονομασία και σύνδεση}),
using a newly created local namespace and the original global namespace.
(Usually, the suite contains mostly function definitions.)  When the class’s
suite finishes execution, its execution frame is discarded but its local
namespace is saved. @footnote{
A string literal appearing as the first statement in the class body is
transformed into the namespace’s @ref{2284,,__doc__} item and therefore
the class’s @ref{24dd,,docstring}.
} A class object is then created using the inheritance
list for the base classes and the saved local namespace for the attribute
dictionary.  The class name is bound to this class object in the original local
namespace.

The order in which attributes are defined in the class body is preserved
in the new class’s @ref{101b,,__dict__}.  Note that this is reliable only right
after the class is created and only for classes that were defined using
the definition syntax.

Class creation can be customized heavily using @ref{25b3,,metaclasses}.

@geindex @@ (at);class definition

Classes can also be decorated: just like when decorating functions,

@example
@@f1(arg)
@@f2
class Foo: pass
@end example

is roughly equivalent to

@example
class Foo: pass
Foo = f1(arg)(f2(Foo))
@end example

The evaluation rules for the decorator expressions are the same as for function
decorators.  The result is then bound to the class name.


Άλλαξε στην έκδοση 3.9: Classes may be decorated with any valid
@ref{2623,,assignment_expression}. Previously, the grammar was
much more restrictive; see 
@geindex Python Enhancement Proposals; PEP 614
PEP 614@footnote{https://peps.python.org/pep-0614/} for details.


A list of @ref{7a5,,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{2568,,__type_params__} attribute. See @ref{86e,,Generic classes} for more.


Άλλαξε στην έκδοση 3.12: Type parameter lists are new in Python 3.12.


`Programmer’s note:' Variables defined in the class definition are class
attributes; they are shared by instances.  Instance attributes can be set in a
method with @code{self.name = value}.  Both class and instance attributes are
accessible through the notation «@code{self.name}», and an instance attribute hides
a class attribute with the same name when accessed in this way.  Class
attributes can be used as defaults for instance attributes, but using mutable
values there can lead to unexpected results.  @ref{100d,,Descriptors}
can be used to create instance variables with different implementation details.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 3115

@item PEP 3115@footnote{https://peps.python.org/pep-3115/} - Metaclasses in Python 3000

The proposal that changed the declaration of metaclasses to the current
syntax, and the semantics for how classes with metaclasses are
constructed.

@geindex Python Enhancement Proposals; PEP 3129

@item PEP 3129@footnote{https://peps.python.org/pep-3129/} - Class Decorators

The proposal that added class decorators.  Function and method decorators
were introduced in 
@geindex Python Enhancement Proposals; PEP 318
PEP 318@footnote{https://peps.python.org/pep-0318/}.
@end table


@menu
* Multiple inheritance:: 

@end menu

@node Multiple inheritance,,,Class definitions
@anchor{reference/compound_stmts id17}@anchor{2783}@anchor{reference/compound_stmts multiple-inheritance}@anchor{2291}
@subsubsection Multiple inheritance


Python classes may have multiple base classes, a technique known as
`multiple inheritance'.  The base classes are specified in the class definition
by listing them in parentheses after the class name, separated by commas.
For example, the following class definition:

@example
>>> class A: pass
>>> class B: pass
>>> class C(A, B): pass
@end example

defines a class @code{C} that inherits from classes @code{A} and @code{B}.

The @ref{2784,,method resolution order} (MRO) is the order in which base classes are
searched when looking up an attribute on a class. See @ref{184c,,The Python 2.3 Method Resolution Order} for a
description of how Python determines the MRO for a class.

Multiple inheritance is not always allowed. Attempting to define a class with multiple
inheritance will raise an error if one of the bases does not allow subclassing, if a consistent MRO
cannot be created, if no valid metaclass can be determined, or if there is an instance
layout conflict. We’ll discuss each of these in turn.

First, all base classes must allow subclassing. While most classes allow subclassing,
some built-in classes do not, such as @ref{5ef,,bool}:

@example
>>> class SubBool(bool):  # TypeError
...    pass
Traceback (most recent call last):
   ...
TypeError: type 'bool' is not an acceptable base type
@end example

In the resolved MRO of a class, the class’s bases appear in the order they were
specified in the class’s bases list. Additionally, the MRO always lists a child
class before any of its bases. A class definition will fail if it is impossible to
resolve a consistent MRO that satisfies these rules from the list of bases provided:

@example
>>> class Base: pass
>>> class Child(Base): pass
>>> class Grandchild(Base, Child): pass  # TypeError
Traceback (most recent call last):
   ...
TypeError: Cannot create a consistent method resolution order (MRO) for bases Base, Child
@end example

In the MRO of @code{Grandchild}, @code{Base} must appear before @code{Child} because it is first
in the base class list, but it must also appear after @code{Child} because it is a parent of
@code{Child}. This is a contradiction, so the class cannot be defined.

If some of the bases have a custom @ref{25c5,,metaclass}, the metaclass of the resulting class
is chosen among the metaclasses of the bases and the explicitly specified metaclass of the
child class. It must be a metaclass that is a subclass of
all other candidate metaclasses. If no such metaclass exists among the candidates,
the class cannot be created, as explained in @ref{25b6,,Προσδιορισμός της κατάλληλης μετακλάσης}.

Finally, the instance layouts of the bases must be compatible. This means that it must be
possible to compute a `solid base' for the class. Exactly which classes are solid bases
depends on the Python implementation.

`Λεπτομέρεια υλοποίησης CPython:' In CPython, a class is a solid base if it has a
nonempty @ref{188d,,__slots__} definition.
Many but not all classes defined in C are also solid bases, including most
builtins (such as @ref{326,,int} or @ref{9b9,,BaseException})
but excluding most concrete @ref{d9e,,Exception} classes. Generally, a C class
is a solid base if its underlying struct is different in size from its base class.

Every class has a solid base. @ref{e4d,,object}, the base class, has itself as its solid base.
If there is a single base, the child class’s solid base is that class if it is a solid base,
or else the base class’s solid base. If there are multiple bases, we first find the solid base
for each base class to produce a list of candidate solid bases. If there is a unique solid base
that is a subclass of all others, then that class is the solid base. Otherwise, class creation
fails.

Example:

@example
>>> class Solid1:
...    __slots__ = ("solid1",)
>>>
>>> class Solid2:
...    __slots__ = ("solid2",)
>>>
>>> class SolidChild(Solid1):
...    __slots__ = ("solid_child",)
>>>
>>> class C1:  # solid base is `object`
...    pass
>>>
>>> # OK: solid bases are `Solid1` and `object`, and `Solid1` is a subclass of `object`.
>>> class C2(Solid1, C1):  # solid base is `Solid1`
...    pass
>>>
>>> # OK: solid bases are `SolidChild` and `Solid1`, and `SolidChild` is a subclass of `Solid1`.
>>> class C3(SolidChild, Solid1):  # solid base is `SolidChild`
...    pass
>>>
>>> # Error: solid bases are `Solid1` and `Solid2`, but neither is a subclass of the other.
>>> class C4(Solid1, Solid2):  # error: no single solid base
...    pass
Traceback (most recent call last):
  ...
TypeError: multiple bases have instance lay-out conflict
@end example

@node Coroutines<2>,Type parameter lists,Class definitions,Compound statements
@anchor{reference/compound_stmts async}@anchor{b19}@anchor{reference/compound_stmts coroutines}@anchor{2785}
@subsection Coroutines



Added in version 3.5.


@geindex statement;async def

@menu
* Coroutine function definition:: 
* The async for statement:: 
* The async with statement:: 

@end menu

@node Coroutine function definition,The async for statement,,Coroutines<2>
@anchor{reference/compound_stmts async-def}@anchor{9cf}@anchor{reference/compound_stmts coroutine-function-definition}@anchor{2786}
@subsubsection Coroutine function definition


@example
@anchor{reference/compound_stmts grammar-token-python-grammar-async_funcdef}@anchor{2727}async_funcdef: [@ref{2776,,decorators}] "async" "def" @ref{2777,,funcname} "(" [@ref{26da,,parameter_list}] ")"
               ["->" @ref{42a,,expression}] ":" @ref{2728,,suite}
@end example

@geindex keyword;async
@geindex keyword;await

Execution of Python coroutines can be suspended and resumed at many points
(see @ref{8a2,,coroutine}). @ref{432,,await} expressions, @ref{e70,,async for} and
@ref{20b,,async with} can only be used in the body of a coroutine function.

Functions defined with @code{async def} syntax are always coroutine functions,
even if they do not contain @code{await} or @code{async} keywords.

It is a @ref{17e,,SyntaxError} to use a @code{yield from} expression inside the body
of a coroutine function.

An example of a coroutine function:

@example
async def func(param1, param2):
    do_stuff()
    await some_coroutine()
@end example


Άλλαξε στην έκδοση 3.7: @code{await} and @code{async} are now keywords; previously they were only
treated as such inside the body of a coroutine function.


@geindex statement;async for

@node The async for statement,The async with statement,Coroutine function definition,Coroutines<2>
@anchor{reference/compound_stmts async-for}@anchor{e70}@anchor{reference/compound_stmts the-async-for-statement}@anchor{2787}
@subsubsection The @code{async for} statement


@example
@anchor{reference/compound_stmts grammar-token-python-grammar-async_for_stmt}@anchor{2726}async_for_stmt: "async" @ref{271f,,for_stmt}
@end example

An @ref{112d,,asynchronous iterable} provides an @code{__aiter__} method that directly
returns an @ref{6cd,,asynchronous iterator}, which can call asynchronous code in
its @code{__anext__} method.

The @code{async for} statement allows convenient iteration over asynchronous
iterables.

The following code:

@example
async for TARGET in ITER:
    SUITE
else:
    SUITE2
@end example

Is semantically equivalent to:

@example
iter = (ITER).__aiter__()
running = True

while running:
    try:
        TARGET = await iter.__anext__()
    except StopAsyncIteration:
        running = False
    else:
        SUITE
else:
    SUITE2
@end example

except that implicit @ref{25a6,,special method lookup} is used
for @ref{fbb,,__aiter__()} and @ref{1aa7,,__anext__()}.

It is a @ref{17e,,SyntaxError} to use an @code{async for} statement outside the
body of a coroutine function.

@geindex statement;async with

@node The async with statement,,The async for statement,Coroutines<2>
@anchor{reference/compound_stmts async-with}@anchor{20b}@anchor{reference/compound_stmts the-async-with-statement}@anchor{2788}
@subsubsection The @code{async with} statement


@example
@anchor{reference/compound_stmts grammar-token-python-grammar-async_with_stmt}@anchor{2725}async_with_stmt: "async" @ref{2721,,with_stmt}
@end example

An @ref{9d2,,asynchronous context manager} is a @ref{478,,context manager} that is
able to suspend execution in its `enter' and `exit' methods.

The following code:

@example
async with EXPRESSION as TARGET:
    SUITE
@end example

is semantically equivalent to:

@example
manager = (EXPRESSION)
aenter = manager.__aenter__
aexit = manager.__aexit__
value = await aenter()
hit_except = False

try:
    TARGET = value
    SUITE
except:
    hit_except = True
    if not await aexit(*sys.exc_info()):
        raise
finally:
    if not hit_except:
        await aexit(None, None, None)
@end example

except that implicit @ref{25a6,,special method lookup} is used
for @ref{2613,,__aenter__()} and @ref{1bad,,__aexit__()}.

It is a @ref{17e,,SyntaxError} to use an @code{async with} statement outside the
body of a coroutine function.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 492

@item PEP 492@footnote{https://peps.python.org/pep-0492/} - Coroutines with async and await syntax

The proposal that made coroutines a proper standalone concept in Python,
and added supporting syntax.
@end table


@node Type parameter lists,Annotations<2>,Coroutines<2>,Compound statements
@anchor{reference/compound_stmts type-parameter-lists}@anchor{2789}@anchor{reference/compound_stmts type-params}@anchor{7a5}
@subsection Type parameter lists



Added in version 3.12.



Άλλαξε στην έκδοση 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{2717}type_params:  "[" @ref{278a,,type_param} ("," @ref{278a,,type_param})* "]"
@anchor{reference/compound_stmts grammar-token-python-grammar-type_param}@anchor{278a}type_param:   @ref{278b,,typevar} | @ref{278c,,typevartuple} | @ref{278d,,paramspec}
@anchor{reference/compound_stmts grammar-token-python-grammar-typevar}@anchor{278b}typevar:      @ref{24b2,,identifier} (":" @ref{42a,,expression})? ("=" @ref{42a,,expression})?
@anchor{reference/compound_stmts grammar-token-python-grammar-typevartuple}@anchor{278c}typevartuple: "*" @ref{24b2,,identifier} ("=" @ref{42a,,expression})?
@anchor{reference/compound_stmts grammar-token-python-grammar-paramspec}@anchor{278d}paramspec:    "**" @ref{24b2,,identifier} ("=" @ref{42a,,expression})?
@end example

@ref{17fc,,Functions} (including @ref{9cf,,coroutines}),
@ref{167c,,classes} and @ref{85a,,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{6b4,,annotation scope}) that
wraps the creation of the generic object.

Generic functions, classes, and type aliases have a
@ref{278e,,__type_params__} attribute listing their type parameters.

Type parameters come in three kinds:


@itemize *

@item 
@ref{294,,typing.TypeVar}, introduced by a plain name (e.g., @code{T}). Semantically, this
represents a single type to a type checker.

@item 
@ref{293,,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{295,,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{294,,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{6b4,,annotation scope}.

@ref{293,,typing.TypeVarTuple}s and @ref{295,,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{6b4,,annotation scope}. If no default value is specified
for a type parameter, the @code{__default__} attribute is set to the special
sentinel object @ref{76a,,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{86f}@anchor{reference/compound_stmts id18}@anchor{278f}
@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{6b4,,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{10d,,typing} module, but creates an instance of
@ref{294,,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{872,,lazy evaluation} of the
@ref{294,,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{86e}@anchor{reference/compound_stmts id19}@anchor{2790}
@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{6b4,,annotation scope}, and the name
@code{TYPE_PARAMS_OF_Bag} is not actually bound at runtime.

Generic classes implicitly inherit from @ref{19f2,,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{871}@anchor{reference/compound_stmts id20}@anchor{2791}
@subsubsection Generic type aliases


The @ref{85a,,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{872,,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{6b4,,annotation scope}. The capitalized names
like @code{TYPE_PARAMS_OF_ListOrSet} are not actually bound at runtime.

@node Annotations<2>,,Type parameter lists,Compound statements
@anchor{reference/compound_stmts annotations}@anchor{277f}@anchor{reference/compound_stmts id21}@anchor{2792}
@subsection Annotations



Άλλαξε στην έκδοση 3.14: Annotations are now lazily evaluated by default.


Variables and function parameters may carry @ref{409,,annotations},
created by adding a colon after the name, followed by an expression:

@example
x: annotation = 1
def f(param: annotation): ...
@end example

Functions may also carry a return annotation following an arrow:

@example
def f() -> annotation: ...
@end example

Annotations are conventionally used for @ref{25c1,,type hints}, but this
is not enforced by the language, and in general annotations may contain arbitrary
expressions. The presence of annotations does not change the runtime semantics of
the code, except if some mechanism is used that introspects and uses the annotations
(such as @ref{32,,dataclasses} or @ref{a2a,,functools.singledispatch()}).

By default, annotations are lazily evaluated in an @ref{6b4,,annotation scope}.
This means that they are not evaluated when the code containing the annotation is evaluated.
Instead, the interpreter saves information that can be used to evaluate the annotation later
if requested. The @ref{6,,annotationlib} module provides tools for evaluating annotations.

If the @ref{670,,future statement} @code{from __future__ import annotations} is present,
all annotations are instead stored as strings:

@example
>>> from __future__ import annotations
>>> def f(param: annotation): ...
>>> f.__annotations__
@{'param': 'annotation'@}
@end example

This future statement will be deprecated and removed in a future version of Python,
but not before Python 3.13 reaches its end of life (see 
@geindex Python Enhancement Proposals; PEP 749
PEP 749@footnote{https://peps.python.org/pep-0749/}).
When it is used, introspection tools like
@ref{66c,,annotationlib.get_annotations()} and @ref{a9e,,typing.get_type_hints()} are
less likely to be able to resolve annotations at runtime.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Συστατικά ανωτάτου επιπέδου,Πλήρης προδιαγραφή γραμματικής,Compound statements,Εγχειρίδιο Αναφοράς της Γλώσσας Python
@anchor{reference/toplevel_components doc}@anchor{2793}@anchor{reference/toplevel_components top-level}@anchor{2794}@anchor{reference/toplevel_components top-level-components}@anchor{2795}@anchor{reference/toplevel_components translation-repo}@anchor{2796}
@section Συστατικά ανωτάτου επιπέδου


@geindex διερμηνέας

Ο διερμηνέας της Python μπορεί να λάβει την είσοδό του από διάφορες πηγές: από ένα script που του δίνεται ως τυπική είσοδος ή ως όρισμα προγράμματος, πληκτρολογημένο διαδραστικά, από ένα αρχείο πηγαίου κώδικα που περιέχει ένα module, κ.λπ. Αυτό το κεφάλαιο παραθέτει τη σύνταξη που χρησιμοποιείται σε αυτές τις περιπτώσεις.

@menu
* Πλήρη προγράμματα Python:: 
* Είσοδος από αρχείο:: 
* Διαδραστική είσοδος:: 
* Είσοδος έκφρασης:: 

@end menu

@node Πλήρη προγράμματα Python,Είσοδος από αρχείο,,Συστατικά ανωτάτου επιπέδου
@anchor{reference/toplevel_components complete-python-programs}@anchor{2797}@anchor{reference/toplevel_components programs}@anchor{2648}
@subsection Πλήρη προγράμματα Python


@geindex πρόγραμμα

@geindex module;sys
@geindex module;__main__
@geindex module;builtins

Αν και μια προδιαγραφή γλώσσας δεν χρειάζεται να ορίζει τον τρόπο κλήσης του διερμηνέα της γλώσσας, είναι χρήσιμο να υπάρχει η έννοια ενός πλήρους Python προγράμματος. Ένα πλήρες πρόγραμμα Python εκτελείται σε ένα ελάχιστα αρχικοποιημένο περιβάλλον: όλα τα ενσωματωμένα και τυπικά modules είναι διαθέσιμα, αλλά κανένα δεν έχει αρχικοποιηθεί, εκτός από τα @ref{e2,,sys} (διάφορες υπηρεσίες του συστήματος), @ref{13,,builtins} (ενσωματωμένες συναρτήσεις, εξαιρέσεις και @code{None}) και το @ref{1,,__main__}. Το τελευταίο χρησιμοποιείται για να παρέχει τον τοπικό και καθολικό χώρο ονομάτων για την εκτέλεση του πλήρους προγράμματος.

Η σύνταξη για ένα πλήρες πρόγραμμα Python είναι αυτή της εισόδου από αρχείο, που περιγράφεται στην επόμενη ενότητα.

@geindex διαδραστική λειτουργία
@geindex module;__main__

Ο διερμηνέας μπορεί επίσης να κληθεί σε διαδραστική λειτουργία· σε αυτήν την περίπτωση, δεν διαβάζει και δεν εκτελεί ένα πλήρες πρόγραμμα αλλά διαβάζει και εκτελεί μία εντολή (πιθανώς σύνθετη) κάθε φορά. Το αρχικό περιβάλλον είναι πανομοιότυπο με αυτό ενός πλήρους προγράμματος· κάθε εντολή εκτελείται στον χώρο ονομάτων του @ref{1,,__main__}.

@geindex UNIX
@geindex Windows
@geindex γραμμή εντολών
@geindex τυπική είσοδος

Ένα πλήρες πρόγραμμα μπορεί να δοθεί στον διερμηνέα με τρεις μορφές: με την επιλογή γραμμής εντολών @ref{445,,-c} `string', ως αρχείο που δίνεται ως το πρώτο όρισμα της γραμμής εντολών, ή ως τυπική είσοδος. Εάν το αρχείο ή η τυπική είσοδος είναι μια συσκευή tty, ο διερμηνέας εισέρχεται σε διαδραστική λειτουργία· διαφορετικά, εκτελεί το αρχείο ως πλήρες πρόγραμμα.

@node Είσοδος από αρχείο,Διαδραστική είσοδος,Πλήρη προγράμματα Python,Συστατικά ανωτάτου επιπέδου
@anchor{reference/toplevel_components file-input}@anchor{2798}@anchor{reference/toplevel_components id1}@anchor{2799}
@subsection Είσοδος από αρχείο


Όλη η είσοδος που διαβάζεται από μη διαδραστικά αρχεία έχει την ίδια μορφή:

@example
@anchor{reference/toplevel_components grammar-token-python-grammar-file_input}@anchor{279a}file_input: (NEWLINE | @ref{272a,,statement})* ENDMARKER
@end example

Αυτή η σύνταξη χρησιμοποιείται στις ακόλουθες περιπτώσεις:


@itemize *

@item 
κατά την ανάλυση ενός πλήρους προγράμματος Python (από αρχείο ή από συμβολοσειρά)·

@item 
κατά την ανάλυση ενός module·

@item 
κατά την ανάλυση μιας συμβολοσειράς που δίνεται στη συνάρτηση @ref{185,,exec()}·
@end itemize

@node Διαδραστική είσοδος,Είσοδος έκφρασης,Είσοδος από αρχείο,Συστατικά ανωτάτου επιπέδου
@anchor{reference/toplevel_components interactive}@anchor{279b}@anchor{reference/toplevel_components interactive-input}@anchor{279c}
@subsection Διαδραστική είσοδος


Η είσοδος σε διαδραστική λειτουργία αναλύεται χρησιμοποιώντας την ακόλουθη γραμματική:

@example
@anchor{reference/toplevel_components grammar-token-python-grammar-interactive_input}@anchor{279d}interactive_input: [@ref{2729,,stmt_list}] NEWLINE | @ref{271c,,compound_stmt} NEWLINE | ENDMARKER
@end example

Σημειώστε ότι μια (ανωτάτου επιπέδου) σύνθετη εντολή πρέπει να ακολουθείται από μια κενή γραμμή σε διαδραστική λειτουργία· αυτό είναι απαραίτητο για να βοηθήσει τον αναλυτή να εντοπίσει το τέλος της εισόδου.

@node Είσοδος έκφρασης,,Διαδραστική είσοδος,Συστατικά ανωτάτου επιπέδου
@anchor{reference/toplevel_components expression-input}@anchor{279e}@anchor{reference/toplevel_components id2}@anchor{279f}
@subsection Είσοδος έκφρασης


@geindex είσοδος

@geindex ενσωματωμένη συνάρτηση;eval

Η @ref{184,,eval()} χρησιμοποιείται για την είσοδο των εκφράσεων. Αγνοεί τα αρχικά κενά. Το όρισμα συμβολοσειράς στη @code{eval()} πρέπει να έχει την ακόλουθη μορφή:

@example
@anchor{reference/toplevel_components grammar-token-python-grammar-eval_input}@anchor{27a0}eval_input: @ref{26dd,,expression_list} NEWLINE* ENDMARKER
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Πλήρης προδιαγραφή γραμματικής,,Συστατικά ανωτάτου επιπέδου,Εγχειρίδιο Αναφοράς της Γλώσσας Python
@anchor{reference/grammar doc}@anchor{275c}@anchor{reference/grammar full-grammar-specification}@anchor{27a1}@anchor{reference/grammar id1}@anchor{27a2}@anchor{reference/grammar translation-repo}@anchor{27a3}
@section Πλήρης προδιαγραφή γραμματικής


Αυτή είναι η πλήρης γραμματική της Python, που προέρχεται απευθείας από τη γραμματική που χρησιμοποιείται για τη δημιουργία του αναλυτή CPython (βλ. Grammar/python.gram@footnote{https://github.com/python/cpython/tree/main/Grammar/python.gram}). Η έκδοση αυτή παραλείπει λεπτομέρειες που σχετίζονται με τη δημιουργία κώδικα και την ανάκτηση από σφάλματα.

Η σημειογραφία που χρησιμοποιείται εδώ είναι η ίδια με τα προηγούμενα έγγραφα και περιγράφεται στην ενότητα @ref{2475,,notation}, εκτός από μερικές επιπλέον επιπλοκές:


@itemize *

@item 
@code{~} («cut»): commit to the current alternative; fail the rule
if the alternative fails to parse

Python mainly uses cuts for optimizations or improved error
messages. They often appear to be useless in the listing below.

@c see gh-143054, and CutValidator in the source, if you want to change this:

Cuts currently don’t appear inside parentheses, brackets, lookaheads
and similar.
Their behavior in these contexts is deliberately left unspecified.
@end itemize

@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 @{ _PyPegen_register_stmts(p ,
                           (asdl_stmt_seq*)_PyPegen_singleton_seq(p, a)
                        ) @}
    | a[asdl_stmt_seq*]=simple_stmts @{ a @}

single_compound_stmt[asdl_stmt_seq*]:
    | a=compound_stmt @{
        _PyPegen_register_stmts(p, (asdl_stmt_seq*)_PyPegen_singleton_seq(p, a)) @}

statement_newline[asdl_stmt_seq*]:
    | a=single_compound_stmt NEWLINE @{ 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
    | &('import' | 'from' | "lazy") import_stmt
    | e=star_expressions @{ _PyAST_Expr(e, EXTRA) @}
    | &'return' return_stmt
    | &'raise' raise_stmt
    | &'pass' pass_stmt
    | &'del' del_stmt
    | &'yield' yield_stmt
    | &'assert' assert_stmt
    | &'break' break_stmt
    | &'continue' continue_stmt
    | &'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=annotated_rhs !'=' tc=[TYPE_COMMENT] @{
         _PyAST_Assign(a, b, NEW_TYPE_COMMENT(p, tc), EXTRA) @}
    | a=single_target b=augassign ~ c=annotated_rhs @{
         _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 'from' b=expression @{ _PyAST_Raise(a, b, EXTRA) @}
    | invalid_raise_stmt
    | 'raise' a=expression @{ _PyAST_Raise(a, NULL, EXTRA) @}
    | 'raise' @{ _PyAST_Raise(NULL, NULL, EXTRA) @}

pass_stmt[stmt_ty]:
    | 'pass' @{ _PyAST_Pass(EXTRA) @}

break_stmt[stmt_ty]:
    | 'break' @{ _PyAST_Break(EXTRA) @}

continue_stmt[stmt_ty]:
    | 'continue' @{ _PyAST_Continue(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]:
    | invalid_assert_stmt
    | 'assert' a=expression b=[',' z=expression @{ z @}] @{ _PyAST_Assert(a, b, EXTRA) @}

import_stmt[stmt_ty](memo):
    | invalid_import
    | import_name
    | import_from

# Import statements
# -----------------

import_name[stmt_ty]:
    | lazy="lazy"? 'import' a=dotted_as_names @{ _PyAST_Import(a, lazy ? 1 : 0, EXTRA) @}

# note below: the ('.' | '...') is necessary because '...' is tokenized as ELLIPSIS
import_from[stmt_ty]:
    | lazy="lazy"? 'from' a=('.' | '...')* b=dotted_name 'import' c=import_from_targets @{
        _PyPegen_checked_future_import(p, b->v.Name.id, c, _PyPegen_seq_count_dots(a), lazy, EXTRA) @}
    | lazy="lazy"? 'from' a=('.' | '...')+ 'import' b=import_from_targets @{
        _PyAST_ImportFrom(NULL, b, _PyPegen_seq_count_dots(a), lazy ? 1 : 0, 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]:
    | invalid_import_from_as_name
    | 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]:
    | invalid_dotted_as_name
    | 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 ':' b=block @{
        _PyAST_ExceptHandler(e, NULL, b, EXTRA) @}
    | 'except' e=expression 'as' t=NAME ':' b=block @{
        _PyAST_ExceptHandler(e, ((expr_ty) t)->v.Name.id, b, EXTRA) @}
    | 'except' e=expressions ':' b=block @{
        CHECK_VERSION(
            excepthandler_ty,
            14,
            "except expressions without parentheses are",
            _PyAST_ExceptHandler(e, 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 ':' b=block @{
        _PyAST_ExceptHandler(e, NULL, b, EXTRA) @}
    | 'except' '*' e=expression 'as' t=NAME ':' b=block @{
        _PyAST_ExceptHandler(e, ((expr_ty) t)->v.Name.id, b, EXTRA) @}
    | 'except' '*' e=expressions ':' b=block @{
        CHECK_VERSION(
            excepthandler_ty,
            14,
            "except expressions without parentheses are",
            _PyAST_ExceptHandler(e,  NULL, b, EXTRA)) @}
    | invalid_except_star_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
    | &(STRING|FSTRING_START|TSTRING_START) 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 @{ number @}
    | '-' number=NUMBER @{ _PyAST_UnaryOp(USub, number, EXTRA) @}

signed_real_number[expr_ty]:
    | real_number
    | '+' real=real_number @{ real @}
    | '-' 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) @}
    | '+' 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) @}
    | invalid_mapping_pattern

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) @}
    | invalid_type_param
    | '*' a=NAME b=[type_param_starred_default] @{ _PyAST_TypeVarTuple(a->v.Name.id, b, EXTRA) @}
    | '**' 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_if_expression
    | invalid_expression
    | invalid_legacy_expression
    | if_expression
    | disjunction
    | lambdef

if_expression[expr_ty]:
    | a=disjunction 'if' b=disjunction 'else' c=expression @{ _PyAST_IfExp(b, a, c, EXTRA) @}

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_expressions_sequence[asdl_expr_seq*]: a[asdl_expr_seq*]=','.star_named_expression_sequence+ [','] @{ a @}

star_named_expression[expr_ty]:
    | '*' a=bitwise_or @{ _PyAST_Starred(a, Load, EXTRA) @}
    | named_expression

star_named_expression_sequence[expr_ty]:
    | invalid_starred_expression_unpacking_sequence
    | star_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|TSTRING_START) strings
    | NUMBER
    | &'(' (genexp | tuple | group)
    | &'[' (listcomp | list)
    | &'@{' (dictcomp | setcomp | dict | set)
    | '...' @{ _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_fstring_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) @}

tstring_format_spec_replacement_field[expr_ty]:
    | '@{' a=annotated_rhs debug_expr='='? conversion=[fstring_conversion] format=[tstring_full_format_spec] rbrace='@}' @{
        _PyPegen_formatted_value(p, a, debug_expr, conversion, format, rbrace, EXTRA) @}
    | invalid_tstring_replacement_field
tstring_format_spec[expr_ty]:
    | t=TSTRING_MIDDLE @{ _PyPegen_decoded_constant_from_token(p, t) @}
    | tstring_format_spec_replacement_field
tstring_full_format_spec[ResultTokenWithMetadata*]:
    | colon=':' spec=tstring_format_spec* @{ _PyPegen_setup_full_format_spec(p, colon, (asdl_expr_seq *) spec, EXTRA) @}
tstring_replacement_field[expr_ty]:
    | '@{' a=annotated_rhs debug_expr='='? conversion=[fstring_conversion] format=[tstring_full_format_spec] rbrace='@}' @{
        _PyPegen_interpolation(p, a, debug_expr, conversion, format, rbrace, EXTRA) @}
    | invalid_tstring_replacement_field
tstring_middle[expr_ty]:
    | tstring_replacement_field
    | t=TSTRING_MIDDLE @{ _PyPegen_constant_from_token(p, t) @}
tstring[expr_ty] (memo):
    | a=TSTRING_START b=tstring_middle* c=TSTRING_END @{
        CHECK_VERSION(
            expr_ty,
            14,
            "t-strings are",
            _PyPegen_template_str(p, a, (asdl_expr_seq*)b, c)) @}

string[expr_ty]: s[Token*]=STRING @{ _PyPegen_constant_from_string(p, s) @}
strings[expr_ty] (memo):
    | invalid_string_tstring_concat
    | a[asdl_expr_seq*]=(fstring|string)+ @{ _PyPegen_concatenate_strings(p, a, EXTRA) @}
    | a[asdl_expr_seq*]=tstring+ @{ _PyPegen_concatenate_tstrings(p, a, EXTRA) @}

list[expr_ty]:
    | '[' a=[star_named_expressions_sequence] ']' @{ _PyAST_List(a, Load, EXTRA) @}

tuple[expr_ty]:
    | '(' a=[y=star_named_expression_sequence ',' z=[star_named_expressions_sequence] @{ _PyPegen_seq_insert_in_front(p, y, z) @} ] ')' @{
        _PyAST_Tuple(a, Load, EXTRA) @}

set[expr_ty]: '@{' a=star_named_expressions_sequence '@}' @{ _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) @}
    | invalid_for_if_clause
    | invalid_for_target

listcomp[expr_ty]:
    | '[' a=star_named_expression b=for_if_clauses ']' @{ _PyAST_ListComp(a, b, EXTRA) @}
    | invalid_comprehension

setcomp[expr_ty]:
    | '@{' a=star_named_expression b=for_if_clauses '@}' @{ _PyAST_SetComp(a, b, EXTRA) @}
    | invalid_comprehension

genexp[expr_ty]:
    | '(' a=( assignment_expression | expression !':=' | starred_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) @}
    | '@{' '**' a=expression b=for_if_clauses '@}' @{ _PyAST_DictComp(a, NULL, b, EXTRA) @}

# 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_unpacking
    | '*' a=expression @{ _PyAST_Starred(a, Load, EXTRA) @}
    | invalid_starred_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_type_param:
    | '*' 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 colon=':' e=expression @{
            RAISE_SYNTAX_ERROR_STARTING_FROM(colon, e->kind == Tuple_kind
                ? "cannot use constraints with ParamSpec"
                : "cannot use bound with ParamSpec")
        @}

invalid_expression:
   |  STRING a=(!STRING expression_without_invalid)+ STRING @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE( PyPegen_first_item(a, expr_ty), PyPegen_last_item(a, expr_ty),
        "invalid syntax. Is this intended to be part of the string?") @}
    # !(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_raise_error_for_missing_comma(p, a, b) @}
   | a=disjunction 'if' b=disjunction !('else'|':') @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "expected 'else' after 'if' expression") @}
   | a=disjunction 'if' b=disjunction 'else' !expression @{
        RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("expected expression after 'else', but statement is given") @}
   | a[stmt_ty]=(pass_stmt|break_stmt|continue_stmt) 'if' b=disjunction 'else' c=simple_stmt @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION (a, "expected expression before 'if', but statement is given") @}
   | a='lambda' [lambda_params] b=':' &FSTRING_MIDDLE  @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "f-string: lambda expressions are not allowed without parentheses") @}
   | a='lambda' [lambda_params] b=':' &TSTRING_MIDDLE  @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "t-string: lambda expressions are not allowed without parentheses") @}

invalid_if_expression:
   | disjunction 'if' b=disjunction 'else' a='*' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "cannot unpack only part of a conditional expression") @}
   | disjunction 'if' b=disjunction 'else' a='**' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "cannot use dict unpacking on only part of a conditional expression") @}

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_raise_stmt:
    | a='raise' b='from' @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "did you forget an expression between 'raise' and 'from'?") @}
    | 'raise' expression a='from' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "did you forget an expression after 'from'?") @}
invalid_del_stmt:
    | 'del' a=star_expressions @{
        RAISE_SYNTAX_ERROR_INVALID_TARGET(DEL_TARGETS, a) @}
invalid_assert_stmt:
    | 'assert' a=expression '=' b=expression @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(
            a, b,
            "cannot assign to %s here. Maybe you meant '==' instead of '='?",
            _PyPegen_get_expr_name(a)) @}
    | 'assert' expression ',' a=expression '=' b=expression @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(
            a, b,
            "cannot assign to %s here. Maybe you meant '==' instead of '='?",
            _PyPegen_get_expr_name(a)) @}
    | 'assert' a=expression ':=' b=expression @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(
            a, b,
            "cannot use named expression without parentheses here") @}
    | 'assert' expression ',' a=expression ':=' b=expression @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(
            a, b,
            "cannot use named expression without parentheses here") @}
invalid_block:
    | NEWLINE !INDENT @{ RAISE_INDENTATION_ERROR("expected an indented block") @}
invalid_comprehension:
    | '[' a='**' b=expression for_if_clauses @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "cannot use dict unpacking in list comprehension") @}
    | '(' a='**' b=expression for_if_clauses @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "cannot use dict unpacking in generator expression") @}
    | ('[' | '@{') 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_parameters:
    | a="/" ',' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "at least one parameter 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 parameters must follow bare *") @}
    | '*' ',' TYPE_COMMENT @{ RAISE_SYNTAX_ERROR("bare * has associated type comment") @}
    | '*' param a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "var-positional parameter cannot have default value") @}
    | '*' (param_no_default | ',') param_maybe_default* a='*' (param_no_default | ',') @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "* may appear only once") @}
invalid_kwds:
    | '**' param a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "var-keyword parameter cannot have default value") @}
    | '**' param ',' a=param @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "parameters cannot follow var-keyword parameter") @}
    | '**' param ',' a[Token*]=('*'|'**'|'/') @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "parameters cannot follow var-keyword parameter") @}
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 parameter 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 parameters must follow bare *") @}
    | '*' lambda_param a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "var-positional parameter cannot have default value") @}
    | '*' (lambda_param_no_default | ',') lambda_param_maybe_default* a='*' (lambda_param_no_default | ',') @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "* may appear only once") @}
invalid_lambda_kwds:
    | '**' lambda_param a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "var-keyword parameter cannot have default value") @}
    | '**' lambda_param ',' a=lambda_param @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "parameters cannot follow var-keyword parameter") @}
    | '**' lambda_param ',' a[Token*]=('*'|'**'|'/') @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "parameters cannot follow var-keyword parameter") @}
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_if_clause:
    | 'async'? 'for' (bitwise_or (',' bitwise_or)* [',']) !'in' @{
        RAISE_SYNTAX_ERROR("'in' expected after for-loop variables") @}

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_dotted_as_name:
    | dotted_name 'as' !(NAME (',' | ')' | ';' | NEWLINE)) a=expression @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a,
            "cannot use %s as import target", _PyPegen_get_expr_name(a)) @}
invalid_import_from_as_name:
    | NAME 'as' !(NAME (',' | ')' | ';' | NEWLINE)) a=expression @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a,
            "cannot use %s as import target", _PyPegen_get_expr_name(a)) @}

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])+ trailing=',' ':' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(trailing, "the last 'with' item has a trailing comma") @}
    | ['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 when using 'as'") @}
    | a='except' expression ['as' NAME ] NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
    | a='except' NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
    | 'except' expression 'as' a=expression ':' block @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(
            a, "cannot use except statement with %s", _PyPegen_get_expr_name(a)) @}
invalid_except_star_stmt:
    | 'except' '*' a=expression ',' expressions 'as' NAME  ':' @{
        RAISE_SYNTAX_ERROR_STARTING_FROM(a, "multiple exception types must be parenthesized when using 'as'") @}
    | a='except' '*' expression ['as' NAME ] NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
    | a='except' '*' (NEWLINE | ':') @{ RAISE_SYNTAX_ERROR("expected one or more exception types") @}
    | 'except' '*' expression 'as' a=expression ':' block @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(
            a, "cannot use except* statement with %s", _PyPegen_get_expr_name(a)) @}
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) @}
    | a="case" patterns guard? b=':' block @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(
            a, b,
            "case statement must be inside match statement") @}
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' a=expression @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(
            a, "cannot use %s as pattern target", _PyPegen_get_expr_name(a)) @}
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_mapping_pattern:
    | '@{' (items_pattern ',')? rest=double_star_pattern ',' items_pattern ','? '@}' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(
        rest,
        "double star pattern must be the last (right-most) subpattern in the mapping pattern") @}
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) @}
    | 'else' ':' block 'elif' @{ RAISE_SYNTAX_ERROR("'elif' block follows an 'else' block")@}
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:
    | invalid_kvpair_unpacking [',']
    | ','.double_starred_kvpair+ ',' (invalid_kvpair | invalid_kvpair_unpacking)
    | expression a=':' &('@}'|',') @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "expression expected after dictionary key and ':'") @}
invalid_kvpair_unpacking:
    | a='**' b=if_expression @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "invalid double starred expression. Did you forget to wrap the conditional expression in parentheses?") @}
    | a='*' b=bitwise_or ':' expression @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "cannot use a starred expression in a dictionary key") @}
    | a='**' b=bitwise_or ':' expression @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "cannot use dict unpacking in a dictionary key") @}
    | expression ':' a='*' b=bitwise_or @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "cannot use a starred expression in a dictionary value") @}
    | expression ':' a='**' b=bitwise_or @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "cannot use dict unpacking in a dictionary value") @}
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='**' bitwise_or @{ RAISE_SYNTAX_ERROR_STARTING_FROM(a, "cannot use dict unpacking in a dictionary value") @}
    | expression a=':' &('@}'|',') @{RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "expression expected after dictionary key and ':'") @}
invalid_starred_expression_unpacking:
    | a='*' b=if_expression @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "invalid starred expression. Did you forget to wrap the conditional expression in parentheses?") @}
    | a='*' expression '=' b=expression @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "cannot assign to iterable argument unpacking") @}
invalid_starred_expression_unpacking_sequence:
    | a='**' bitwise_or @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "cannot use dict unpacking here") @}
    | invalid_starred_expression_unpacking
invalid_starred_expression:
    | '*' @{ RAISE_SYNTAX_ERROR("Invalid star expression") @}
invalid_fstring_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_fstring_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_fstring_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_tstring_replacement_field:
    | '@{' a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "t-string: valid expression required before '='") @}
    | '@{' a='!' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "t-string: valid expression required before '!'") @}
    | '@{' a=':' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "t-string: valid expression required before ':'") @}
    | '@{' a='@}' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "t-string: valid expression required before '@}'") @}
    | '@{' !annotated_rhs @{ RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("t-string: expecting a valid expression after '@{'") @}
    | '@{' annotated_rhs !('=' | '!' | ':' | '@}') @{
        PyErr_Occurred() ? NULL : RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("t-string: expecting '=', or '!', or ':', or '@}'") @}
    | '@{' annotated_rhs '=' !('!' | ':' | '@}') @{
        PyErr_Occurred() ? NULL : RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("t-string: expecting '!', or ':', or '@}'") @}
    | '@{' annotated_rhs '='? invalid_tstring_conversion_character
    | '@{' annotated_rhs '='? ['!' NAME] !(':' | '@}') @{
        PyErr_Occurred() ? NULL : RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("t-string: expecting ':' or '@}'") @}
    | '@{' annotated_rhs '='? ['!' NAME] ':' fstring_format_spec* !'@}' @{
        PyErr_Occurred() ? NULL : RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("t-string: expecting '@}', or format specs") @}
    | '@{' annotated_rhs '='? ['!' NAME] !'@}' @{
        PyErr_Occurred() ? NULL : RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("t-string: expecting '@}'") @}

invalid_tstring_conversion_character:
    | '!' &(':' | '@}') @{ RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("t-string: missing conversion character") @}
    | '!' !NAME @{ RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("t-string: invalid conversion character") @}

invalid_string_tstring_concat:
    | a=(fstring|string)+ b[expr_ty]=tstring @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(PyPegen_last_item(a, expr_ty), b, "cannot mix t-string literals with string or bytes literals") @}
    | a=tstring+ b[expr_ty]=(fstring|string) @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(PyPegen_last_item(a, expr_ty), b, "cannot mix t-string literals with string or bytes literals") @}

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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node The Python Standard Library,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python,Εγχειρίδιο Αναφοράς της Γλώσσας Python,Top
@anchor{library/index doc}@anchor{27a4}@anchor{library/index library-index}@anchor{3f7}@anchor{library/index the-python-standard-library}@anchor{27a5}@anchor{library/index translation-repo}@anchor{27a6}
@chapter The Python Standard Library


While @ref{3f8,,Εγχειρίδιο Αναφοράς της Γλώσσας Python} describes the exact syntax and
semantics of the Python language, this library reference manual
describes the standard library that is distributed with Python. It also
describes some of the optional components that are commonly included
in Python distributions.

Python’s standard library is very extensive, offering a wide range of
facilities as indicated by the long table of contents listed below. The
library contains built-in modules (written in C) that provide access to
system functionality such as file I/O that would otherwise be
inaccessible to Python programmers, as well as modules written in Python
that provide standardized solutions for many problems that occur in
everyday programming. Some of these modules are explicitly designed to
encourage and enhance the portability of Python programs by abstracting
away platform-specifics into platform-neutral APIs.

The Python installers for the Windows platform usually include
the entire standard library and often also include many additional
components. For Unix-like operating systems Python is normally provided
as a collection of packages, so it may be necessary to use the packaging
tools provided with the operating system to obtain some or all of the
optional components.

In addition to the standard library, there is an active collection of
hundreds of thousands of components (from individual programs and modules to
packages and entire application development frameworks), available from
the 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<4>. 
* Ενσωματωμένες (Built-in) Συναρτήσεις: Ενσωματωμένες Built-in Συναρτήσεις. 
* Built-in Constants:: 
* Τύποι Built-in:: 
* Built-in Exceptions:: 
* Thread Safety Guarantees:: 
* Text Processing Services:: 
* Υπηρεσίες Δυαδικών Δεδομένων:: 
* Data Types:: 
* Αριθμητικά και Μαθηματικά Modules:: 
* Functional Programming Modules:: 
* File and Directory Access:: 
* Data Persistence:: 
* Data Compression and Archiving:: 
* File Formats:: 
* Cryptographic Services:: 
* Generic Operating System Services:: 
* Command-line interface libraries:: 
* Concurrent Execution:: 
* Networking and Interprocess Communication:: 
* Internet Data Handling:: 
* Structured Markup Processing Tools:: 
* Πρωτόκολλα Internet και Υποστήριξη:: 
* Multimedia Services:: 
* Internationalization:: 
* Γραφικές επαφές χρηστών με το Tk:: 
* Εργαλεία Ανάπτυξης:: 
* Debugging and profiling:: 
* Software Packaging and Distribution:: 
* Python Runtime Services:: 
* Custom Python Interpreters:: 
* Importing Modules:: 
* Python Language Services:: 
* MS Windows Specific Services:: 
* Unix-specific services:: 
* Command-line interface (Διεπαφή Γραμμής Εντολών) (CLI) για modules: Command-line interface Διεπαφή Γραμμής Εντολών CLI για modules. 
* Superseded modules:: 
* Removed Modules:: 
* Security Considerations: Security Considerations<3>. 

@end menu

@node Introduction<4>,Ενσωματωμένες Built-in Συναρτήσεις,,The Python Standard Library
@anchor{library/intro doc}@anchor{27a7}@anchor{library/intro introduction}@anchor{27a8}@anchor{library/intro library-intro}@anchor{27a9}
@section Introduction


The «Python library» contains several different kinds of components.

It contains data types that would normally be considered part of the «core» of a
language, such as numbers and lists.  For these types, the Python language core
defines the form of literals and places some constraints on their semantics, but
does not fully define the semantics.  (On the other hand, the language core does
define syntactic properties like the spelling and priorities of operators.)

The library also contains built-in functions and exceptions — objects that can
be used by all Python code without the need of an @ref{9da,,import} statement.
Some of these are defined by the core language, but many are not essential for
the core semantics and are only described here.

The bulk of the library, however, consists of a collection of modules. There are
many ways to dissect this collection.  Some modules are written in C and built
in to the Python interpreter; others are written in Python and imported in
source form.  Some modules provide interfaces that are highly specific to
Python, like printing a stack trace; some provide interfaces that are specific
to particular operating systems, such as access to specific hardware; others
provide interfaces that are specific to a particular application domain, like
the World Wide Web. Some modules are available in all versions and ports of
Python; others are only available when the underlying system supports or
requires them; yet others are available only when a particular configuration
option was chosen at the time when Python was compiled and installed.

This manual is organized «from the inside out:» it first describes the built-in
functions, data types and exceptions, and finally the modules, grouped in
chapters of related modules.

This means that if you start reading this manual from the start, and skip to the
next chapter when you get bored, you will get a reasonable overview of the
available modules and application areas that are supported by the Python
library.  Of course, you don’t `have' to read it like a novel — you can also
browse the table of contents (in front of the manual), or look for a specific
function, module or term in the index (in the back).  And finally, if you enjoy
learning about random subjects, you choose a random page number (see module
@ref{c0,,random}) and read a section or two.  Regardless of the order in which you
read the sections of this manual, it helps to start with chapter
@ref{1601,,Ενσωματωμένες (Built-in) Συναρτήσεις}, as the remainder of the manual assumes familiarity with
this material.

Let the show begin!

@menu
* Notes on availability:: 

@end menu

@node Notes on availability,,,Introduction<4>
@anchor{library/intro availability}@anchor{232d}@anchor{library/intro notes-on-availability}@anchor{27aa}
@subsection Notes on availability



@itemize *

@item 
An «Availability: Unix» note means that this function is commonly found on
Unix systems.  It does not make any claims about its existence on a specific
operating system.

@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 
If an availability note contains both a minimum Kernel version and a minimum
libc version, then both conditions must hold. For example a feature with note
`Availability: Linux >= 3.17 with glibc >= 2.27' requires both Linux 3.17 or
newer and glibc 2.27 or newer.
@end itemize

@menu
* WebAssembly platforms:: 
* Mobile platforms:: 

@end menu

@node WebAssembly platforms,Mobile platforms,,Notes on availability
@anchor{library/intro wasm-availability}@anchor{1d67}@anchor{library/intro webassembly-platforms}@anchor{27ab}
@subsubsection WebAssembly platforms


The WebAssembly@footnote{https://webassembly.org/} platforms @code{wasm32-emscripten} (Emscripten@footnote{https://emscripten.org/}) and
@code{wasm32-wasi} (WASI@footnote{https://wasi.dev/}) provide a subset of POSIX APIs. WebAssembly runtimes
and browsers are sandboxed and have limited access to the host and external
resources. Any Python standard library module that uses processes, threading,
networking, signals, or other forms of inter-process communication (IPC), is
either not available or may not work as on other Unix-like systems. File I/O,
file system, and Unix permission-related functions are restricted, too.
Emscripten does not permit blocking I/O. Other blocking operations like
@ref{a8c,,sleep()} block the browser event loop.

The properties and behavior of Python on WebAssembly platforms depend on the
Emscripten@footnote{https://emscripten.org/}-SDK or WASI@footnote{https://wasi.dev/}-SDK version, WASM runtimes (browser, NodeJS,
wasmtime@footnote{https://wasmtime.dev/}), and Python build time flags. WebAssembly, Emscripten, and WASI
are evolving standards; some features like networking may be
supported in the future.

For Python in the browser, users should consider Pyodide@footnote{https://pyodide.org/} or PyScript@footnote{https://pyscript.net/}.
PyScript is built on top of Pyodide, which itself is built on top of
CPython and Emscripten. Pyodide provides access to browsers” JavaScript and
DOM APIs as well as limited networking capabilities with JavaScript’s
@code{XMLHttpRequest} and @code{Fetch} APIs.


@itemize *

@item 
Process-related APIs are not available or always fail with an error. That
includes APIs that spawn new processes (@ref{6bd,,fork()},
@ref{14a5,,execve()}), wait for processes (@ref{1153,,waitpid()}), send signals
(@ref{170c,,kill()}), or otherwise interact with processes. The
@ref{df,,subprocess} is importable but does not work.

@item 
The @ref{d4,,socket} module is available, but is limited and behaves
differently from other platforms. On Emscripten, sockets are always
non-blocking and require additional JavaScript code and helpers on the
server to proxy TCP through WebSockets; see Emscripten Networking@footnote{https://emscripten.org/docs/porting/networking.html}
for more information. WASI snapshot preview 1 only permits sockets from an
existing file descriptor.

@item 
Some functions are stubs that either don’t do anything and always return
hardcoded values.

@item 
Functions related to file descriptors, file permissions, file ownership, and
links are limited and don’t support some operations. For example, WASI does
not permit symlinks with absolute file names.
@end itemize
@anchor{library/intro mobile-availability}@anchor{244d}
@node Mobile platforms,,WebAssembly platforms,Notes on availability
@anchor{library/intro ios-availability}@anchor{27ac}@anchor{library/intro mobile-platforms}@anchor{27ad}
@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{244c,,Python embedding API}. For more details, see
@ref{244a,,Χρήση της Python σε Android} and @ref{2452,,Χρήση Python σε 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{98,,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{2e,,curses} and @ref{c2,,readline}) are not available on mobile platforms.
@end itemize
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c XXX document all delegations to __special__ methods

@node Ενσωματωμένες Built-in Συναρτήσεις,Built-in Constants,Introduction<4>,The Python Standard Library
@anchor{library/functions doc}@anchor{27ae}@anchor{library/functions built-in-funcs}@anchor{1601}@anchor{library/functions built-in-functions}@anchor{27af}@anchor{library/functions translation-repo}@anchor{27b0}
@section Ενσωματωμένες (Built-in) Συναρτήσεις


O interpreter της Python έχει έναν αριθμό από συναρτήσεις και τύπους ενσωματωμένους (built-in) σε αυτόν, που είναι πάντα διαθέσιμα.  Παρατίθενται εδώ με αλφαβητική σειρά.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Ενσωματωμένες (Built-in) Συναρτήσεις

@tab

@tab

@tab

@item


@display
`A'@w{ }
@ref{227c,,abs()}@w{ }
@ref{bb2,,aiter()}@w{ }
@ref{17c4,,all()}@w{ }
@ref{bb3,,anext()}@w{ }
@ref{17c3,,any()}@w{ }
@ref{1789,,ascii()}@w{ }
@w{ }
`B'@w{ }
@ref{164d,,bin()}@w{ }
@ref{5ef,,bool()}@w{ }
@ref{4f9,,breakpoint()}@w{ }
@ref{2088,,bytearray()}@w{ }
@ref{2087,,bytes()}@w{ }
@w{ }
`C'@w{ }
@ref{156f,,callable()}@w{ }
@ref{1bf8,,chr()}@w{ }
@ref{69a,,classmethod()}@w{ }
@ref{1c8,,compile()}@w{ }
@ref{328,,complex()}@w{ }
@w{ }
`D'@w{ }
@ref{1aa,,delattr()}@w{ }
@ref{27b1,,dict()}@w{ }
@ref{a23,,dir()}@w{ }
@ref{d6a,,divmod()}@w{ }
@w{ }
@end display



@tab


@display
`E'@w{ }
@ref{1823,,enumerate()}@w{ }
@ref{184,,eval()}@w{ }
@ref{185,,exec()}@w{ }
@w{ }
`F'@w{ }
@ref{c3b,,filter()}@w{ }
@ref{327,,float()}@w{ }
@ref{439,,format()}@w{ }
@ref{27b2,,frozenset()}@w{ }
@w{ }
`G'@w{ }
@ref{f8f,,getattr()}@w{ }
@ref{1e01,,globals()}@w{ }
@w{ }
`H'@w{ }
@ref{8e2,,hasattr()}@w{ }
@ref{9e2,,hash()}@w{ }
@ref{ca9,,help()}@w{ }
@ref{1674,,hex()}@w{ }
@w{ }
`I'@w{ }
@ref{17c5,,id()}@w{ }
@ref{167d,,input()}@w{ }
@ref{326,,int()}@w{ }
@ref{2ef,,isinstance()}@w{ }
@ref{2f0,,issubclass()}@w{ }
@ref{bb4,,iter()}@w{ }
@end display



@tab


@display
`L'@w{ }
@ref{a1f,,len()}@w{ }
@ref{27b3,,list()}@w{ }
@ref{28b,,locals()}@w{ }
@w{ }
`M'@w{ }
@ref{43e,,map()}@w{ }
@ref{12ba,,max()}@w{ }
@ref{27b4,,memoryview()}@w{ }
@ref{12b9,,min()}@w{ }
@w{ }
`N'@w{ }
@ref{bb5,,next()}@w{ }
@w{ }
`O'@w{ }
@ref{e4d,,object()}@w{ }
@ref{1673,,oct()}@w{ }
@ref{32b,,open()}@w{ }
@ref{252c,,ord()}@w{ }
@w{ }
`P'@w{ }
@ref{441,,pow()}@w{ }
@ref{131f,,print()}@w{ }
@ref{6bb,,property()}@w{ }
@w{ }
@w{ }
@w{ }
@w{ }
@end display



@tab


@display
`R'@w{ }
@ref{27b5,,range()}@w{ }
@ref{45b,,repr()}@w{ }
@ref{c3c,,reversed()}@w{ }
@ref{167f,,round()}@w{ }
@w{ }
`S'@w{ }
@ref{27b6,,set()}@w{ }
@ref{27b7,,setattr()}@w{ }
@ref{18b,,sentinel()}@w{ }
@ref{1d0,,slice()}@w{ }
@ref{f8c,,sorted()}@w{ }
@ref{666,,staticmethod()}@w{ }
@ref{27b8,,str()}@w{ }
@ref{881,,sum()}@w{ }
@ref{443,,super()}@w{ }
`T'@w{ }
@ref{27b9,,tuple()}@w{ }
@ref{186,,type()}@w{ }
@w{ }
`V'@w{ }
@ref{2011,,vars()}@w{ }
@w{ }
`Z'@w{ }
@ref{43f,,zip()}@w{ }
@w{ }
`_'@w{ }
@ref{ca6,,__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{227c}
@deffn {Συνάρτηση} abs (number, /)

Επιστρέφει την απόλυτη τιμή ενός αριθμού. Το όρισμα μπορεί να είναι ένας ακέραιος, ένας αριθμός κινητής υποδιαστολής, ή ένα αντικείμενο που υλοποιεί την @ref{25fa,,__abs__()}. Εάν το όρισμα είναι ένας μιγαδικός αριθμός επιστρέφεται το μέγεθός του.
@end deffn

@geindex built-in function; aiter()
@anchor{library/functions aiter}@anchor{bb2}
@deffn {Συνάρτηση} aiter (async_iterable, /)

Επιστρέφεται ένας @ref{6cd,,asynchronous iterator} για ένα @ref{112d,,asynchronous iterable}. Ισοδυναμεί με την κλήση του @code{x.__aiter__()}.

Σημείωση: Σε αντίθεση με το @ref{bb4,,iter()}, το @ref{bb2,,aiter()} δεν έχει παραλλαγή 2 ορισμάτων.


Added in version 3.10.

@end deffn

@geindex built-in function; all()
@anchor{library/functions all}@anchor{17c4}
@deffn {Συνάρτηση} all (iterable, /)

Επιστρέφει @code{True} εάν όλα τα στοιχεία του `iterable' είναι true (ή εάν το iterable είναι κενό).  Ισοδυναμεί με:

@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{bb3}
@deffn {Συνάρτηση} awaitable anext (async_iterator, /)

@deffnx {Συνάρτηση} awaitable anext (async_iterator, default, /)

Όταν αναμένεται, επιστρέφεται το επόμενο στοιχείο από το @ref{6cd,,asynchronous iterator}, ή `default' (προεπιλογή) εάν δίνεται και ο iterator έχει εξαντληθεί.

Αυτό είναι μια ασύγχρονη παραλλαγή της ενσωματωμένης συνάρτησης @ref{bb5,,next()}, και συμπεριφέρεται παρόμοια.

Αυτό καλεί την μέθοδο @ref{1aa7,,__anext__()} του `async_iterator', επιστρέφοντας ένα @ref{6cf,,awaitable}. Αναμένοντας αυτό, επιστρέφει την επόμενη τιμή του iterator. Αν δίνεται το `default' (προεπιλογή), αυτό επιστρέφεται εάν ο iterator έχει εξαντληθεί, αλλιώς γίνεται raise ένα @ref{1ffe,,StopAsyncIteration}.


Added in version 3.10.

@end deffn

@geindex built-in function; any()
@anchor{library/functions any}@anchor{17c3}
@deffn {Συνάρτηση} any (iterable, /)

Επιστρέφει @code{True} εάν οποιοδήποτε στοιχείο του `iterable' είναι αληθές.  Εάν το iterable είναι κενό, επιστρέφει @code{False}.  Ισοδυναμεί με:

@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{1789}
@deffn {Συνάρτηση} ascii (object, /)

Όπως η @ref{45b,,repr()}, επιστρέφει μια συμβολοσειρά που περιέχει μια εκτυπώσιμη απεικόνιση ενός αντικειμένου, αλλά αναιρεί τους μη-ASCII χαρακτήρες στη συμβολοσειρά που επιστρέφεται από το @code{repr()} χρησιμοποιώντας @code{\x}, @code{\u}, ή @code{\U} αποδράσεις.  Αυτό παράγει μια συμβολοσειρά παρόμοια με αυτή που επιστρέφεται από την @code{repr()} στην Python 2.
@end deffn

@geindex built-in function; bin()
@anchor{library/functions bin}@anchor{164d}
@deffn {Συνάρτηση} bin (integer, /)

Μετατροπή ενός ακέραιου αριθμού σε μια δυαδική συμβολοσειρά με πρόθεμα «0b». Το αποτέλεσμα είναι μια έγκυρη έκφραση Python. Εάν το `integer' δεν είναι αντικείμενο της Python @ref{326,,int}, πρέπει να οριστεί μια μέθοδος @ref{43d,,__index__()} που επιστρέφει έναν ακέραιο αριθμό. Κάποια παραδείγματα:

@example
>>> bin(3)
'0b11'
>>> bin(-10)
'-0b1010'
@end example

Εάν το πρόθεμα «0b» είναι επιθυμητό ή όχι, μπορείτε να χρησιμοποιήσετε έναν από τους παρακάτω τρόπους.

@example
>>> format(14, '#b'), format(14, 'b')
('0b1110', '1110')
>>> f'@{14:#b@}', f'@{14:b@}'
('0b1110', '1110')
@end example

See also @ref{1987,,enum.bin()} to represent negative values as twos-complement.

Δείτε επίσης τη @ref{439,,format()} για περισσότερες πληροφορίες.
@end deffn

@geindex bool (ενσωματωμένη κλάση)
@anchor{library/functions bool}@anchor{5ef}
@deffn {Κλάση} bool (object=False, /)

Επιστρέφετε μια δυαδική τιμή, π.χ. μία από τις τιμές @code{True} ή @code{False}.  Το όρισμα μετατρέπεται χρησιμοποιώντας την τυπική @ref{1a80,,truth testing procedure}.  Εάν το όρισμα είναι ψευδές ή παραλειφθεί, αυτό επιστρέφει @code{False} ∙ διαφορετικά, επιστρέφει @code{True}.  Η κλάση @ref{5ef,,bool} είναι μια υποκλάση της @ref{326,,int} (βλ. @ref{21c9,,Αριμθητικοί Τύποι — int@comma{} float@comma{} complex}). Δεν μπορεί να γίνει περαιτέρω υποκλάση.  Οι μόνες περιπτώσεις είναι @code{False} και @code{True} (βλ. @ref{27ba,,Τύπος Boolean - bool}).

@geindex Boolean;τύπος


Άλλαξε στην έκδοση 3.7: Η παράμετρος είναι πλέον μόνο παράμετρος θέσης.

@end deffn

@geindex built-in function; breakpoint()
@anchor{library/functions breakpoint}@anchor{4f9}
@deffn {Συνάρτηση} breakpoint (*args, **kws)

Αυτή η συνάρτηση μας μεταφέρει στο πρόγραμμα εντοπισμού σφαλμάτων στην τοποθεσία της κλήσης.  Συγκεκριμένα, καλεί το @ref{e9f,,sys.breakpointhook()}, περνώντας απευθείας τα @code{args} και @code{kws}. Από προεπιλογή, το @code{sys.breakpointhook()} καλεί την @ref{4fa,,pdb.set_trace()} χωρίς να περιμένει ορίσματα.  Σε αυτήν την περίπτωση, είναι καθαρά μια βολική συνάρτηση, επομένως δεν χρειάζεται να εισάγετε ρητά το @ref{aa,,pdb} ή να πληκτρολογήσετε τόσο πολύ κώδικα.  Ωστόσο η @code{sys.breakpointhook()} μπορεί να ρυθμιστεί σε κάποια άλλη συνάρτηση και το @ref{4f9,,breakpoint()} θα το καλέσει αυτόματα, επιτρέποντας σας να πέσετε στο πρόγραμμα εντοπισμού σφαλμάτων της επιλογής σας. Εάν η @code{sys.breakpointhook()} δεν είναι προσβάσιμη, αυτή η συνάρτηση θα κάνει raise το @ref{30d,,RuntimeError}.

Από προεπιλογή, η συμπεριφορά της @ref{4f9,,breakpoint()} μπορεί να αλλάξει με την μεταβλητή περιβάλλοντος 
@geindex PYTHONBREAKPOINT
@geindex μεταβλητή περιβάλλοντος; PYTHONBREAKPOINT
@ref{ea0,,PYTHONBREAKPOINT}. Βλ. την @ref{e9f,,sys.breakpointhook()} για λεπτομέρειες χρήσης.

Λάβετε υπόψη ότι αυτό δεν είναι εγγυημένο εάν η @ref{e9f,,sys.breakpointhook()} έχει αντικατασταθεί.

Εγείρει ένα @ref{1e65,,auditing event} @code{builtins.breakpoint} με όρισμα @code{breakpointhook}.


Added in version 3.7.

@end deffn

@anchor{library/functions func-bytearray}@anchor{2088}
@deffn {Κλάση} bytearray (source=b'@w{'})

@deffnx {Κλάση} bytearray (source, encoding, errors='strict')

Επιστρέφετε ένας νέος πίνακας από bytes.  Η κλάση @ref{1c6,,bytearray} είναι μια μεταβλητή ακολουθία ακεραίων στο εύρος 0 <= x < 256.  Έχει τις περισσότερες από τις συνήθεις μεθόδους μεταβλητών ακολουθιών, που περιγράφονται στο @ref{27bb,,Τύποι Μεταβλητών Ακολουθιών (Sequences)}, καθώς και τις περισσότερες μεθόδους που έχει ο τύπος @ref{1c7,,bytes}, δείτε @ref{27bc,,Λειτουργίες Bytes και Bytearray}.

Η προαιρετική παράμετρος `source' μπορεί να χρησιμοποιηθεί για την αρχικοποίηση του πίνακα με μερικούς διαφορετικούς τρόπους:


@itemize *

@item 
Εάν είναι `string', πρέπει επίσης να δώσετε τις παραμέτρους `encoding' (και προαιρετικά, `errors')∙ η @ref{1c6,,bytearray()} στη συνέχεια μετατρέπει τη συμβολοσειρά σε byte χρησιμοποιώντας @ref{ca7,,str.encode()}.

@item 
Εάν είναι `integer', ο πίνακας θα έχει αυτό το μέγεθος και θα αρχικοποιηθεί με null bytes.

@item 
Εάν είναι αντικείμενο που συμμορφώνεται με το @ref{311,,buffer interface}, θα χρησιμοποιηθεί μια προσωρινή μνήμη μόνο για ανάγνωση του αντικείμενου για την προετοιμασία του πίνακα με τα bytes.

@item 
Εάν είναι `iterable', πρέπει να είναι ένας iterable ακεραίων στο εύρος @code{0 <= x < 256}, οι οποίοι χρησιμοποιούνται ως αρχικά περιεχόμενα του πίνακα.
@end itemize

Χωρίς όρισμα δημιουργείται ένας πίνακας μεγέθους 0.

Βλ. επίσης @ref{27bd,,Τύποι δυαδικής ακολουθίας — bytes@comma{} bytearray@comma{} memoryview} και @ref{27be,,Αντικείμενα Bytearray}.
@end deffn

@anchor{library/functions func-bytes}@anchor{2087}
@deffn {Κλάση} bytes (source=b'@w{'})

@deffnx {Κλάση} bytes (source, encoding, errors='strict')

Επιστρέφεται ένα νέο αντικείμενο «bytes», που είναι μια αμετάβλητη ακολουθία ακεραίων στο εύρος @code{0 <= x < 256}.  Η @ref{1c7,,bytes} είναι μια αμετάβλητη έκδοση του @ref{1c6,,bytearray} – έχει τις ίδιες μεθόδους χωρίς μετάλλαξη και την ίδια συμπεριφορά ευρετηριοποίησης και τεμαχισμού.

Συνεπώς, τα ορίσματα του constructor ερμηνεύονται ως @ref{1c6,,bytearray()}.

Τα αντικείμενα bytes μπορούν επίσης να δημιουργηθούν με literals, βλέπε @ref{2490,,Λεκτικά συμβολοσειράς και Bytes}.

Βλέπε επίσης @ref{27bd,,Τύποι δυαδικής ακολουθίας — bytes@comma{} bytearray@comma{} memoryview}, @ref{27bf,,Αντικείμενα Bytes}, και @ref{27bc,,Λειτουργίες Bytes και Bytearray}.
@end deffn

@geindex built-in function; callable()
@anchor{library/functions callable}@anchor{156f}
@deffn {Συνάρτηση} callable (object, /)

Επιστρέφει @ref{fcc,,True} εάν το όρισμα `object' εμφανίζεται ως callable, και @ref{ef5,,False} εάν όχι.  Εάν αυτό επιστρέψει @code{True}, είναι ακόμα πιθανό μια κλήση να αποτύχει, αλλά εάν είναι @code{False}, η κλήση του `object' δεν θα πετύχει ποτέ. Σημειώστε ότι οι κλάσεις μπορούν να κληθούν (η κλήση μιας κλάσης επιστρέφει ένα νέο instance). Τα instances μπορούν να κληθούν αν η κλάση τους έχει τη μέθοδο @ref{961,,__call__()}.


Added in version 3.2: Αυτή η συνάρτηση πρώτα αφαιρέθηκε στην Python 3.0 και στη συνέχεια επανήλθε στην Python 3.2.

@end deffn

@geindex built-in function; chr()
@anchor{library/functions chr}@anchor{1bf8}
@deffn {Συνάρτηση} chr (codepoint, /)

Επιστρέφει τη συμβολοσειρά που αναπαριστά έναν χαρακτήρα με το συγκεκριμένο Unicode code point. Για παράδειγμα, το @code{chr(97)} επιστρέφει τη συμβολοσειρά @code{'a'}, ενώ το @code{chr(8364)} επιστρέφει τη συμβολοσειρά @code{'€'}.  Αυτό είναι το αντίστροφο της @ref{252c,,ord()}.

Το έγκυρο εύρος για το όρισμα είναι από 0 έως 1,114,111 (0x10FFFF στη βάση 16).  Το @ref{277,,ValueError} θα γίνει raise εάν είναι εκτός αυτού του εύρους.
@end deffn

@geindex built-in function; classmethod()
@anchor{library/functions classmethod}@anchor{69a}
@deffn {Συνάρτηση} @@classmethod

Μετατροπή μιας μεθόδου σε μέθοδο κλάσης.

Μια μέθοδος κλάσης λαμβάνει την κλάση ως σιωπηρό πρώτο όρισμα, όπως μια instance μέθοδος λαμβάνει το instance. Για να δηλώσετε μια μέθοδο κλάσης, χρησιμοποιήστε αυτό το ιδίωμα:

@example
class C:
    @@classmethod
    def f(cls, arg1, arg2): ...
@end example

Η φόρμα @code{@@classmethod} είναι μια συνάρτηση @ref{b18,,decorator} – βλέπε @ref{2206,,Function definitions} για λεπτομέρειες.

Μια μέθοδος κλάσης μπορεί να κληθεί είτε στην κλάση (όπως @code{C.f()}) είτε σε ένα instance (όπως @code{C().f()}).  Το instance αγνοείται εκτός από την κλάση της. Εάν μια μέθοδος κλάσης καλείται για μια παραγόμενη κλάση, το αντικείμενο παραγόμενης κλάσης μεταβιβάζεται ως το υπονοούμενο πρώτο όρισμα.

Οι μέθοδοι κλάσης διαφέρουν από τις στατικές μεθόδους C++ ή Java. Αν θέλετε, ανατρέξτε στο @ref{666,,staticmethod()} σε αυτήν την ενότητα. Για περισσότερες πληροφορίες σχετικά με τις μεθόδους κλάσης, ανατρέξτε στο @ref{2520,,Η τυπική ιεραρχία τύπου}.


Άλλαξε στην έκδοση 3.9: Οι μέθοδοι κλάσης μπορούν πλέον να αναδιπλώσουν άλλους @ref{21f,,descriptors} όπως η @ref{6bb,,property()}.



Άλλαξε στην έκδοση 3.10: Οι μέθοδοι κλάσης κληρονομούν πλέον τα χαρακτηριστικά της μεθόδους (@ref{253b,,__module__}, @ref{1679,,__name__}, @ref{253a,,__qualname__}, @ref{1582,,__doc__} and @ref{1581,,__annotations__}) και έχουν ένα νέο χαρακτηριστικό @code{__wrapped__}.



Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13: Οι μέθοδοι κλάσης δεν μπορούν πλέον να κάνουν wrap άλλους @ref{21f,,descriptors} όπως @ref{6bb,,property()}.

@end deffn

@geindex built-in function; compile()
@anchor{library/functions compile}@anchor{1c8}
@deffn {Συνάρτηση} compile (source, filename, mode, flags=0, dont_inherit=False, optimize=-1, *, module=None)

Μεταγλωττίστε το `source' σε έναν κώδικα ή αντικείμενο AST.  Τα αντικείμενα κώδικα μπορούν να εκτελεστούν από @ref{185,,exec()} ή @ref{184,,eval()}.  Η `source' μπορεί να είναι είτε μια κανονική συμβολοσειρά, μια συμβολοσειρά byte ή μια συμβολοσειρά AST αντικείμενου.  Ανατρέξτε στην τεκμηρίωση του module @ref{9,,ast} για πληροφορίες σχετικά με τον τρόπο εργασίας με αντικείμενα AST.

Το όρισμα `filename' θα πρέπει να δίνει το αρχείο από το οποίο διαβάζεται ο κώδικας∙ να περάσει κάποια αναγνωρίσιμη τιμή εάν δεν διαβαστεί από ένα αρχείο (χρησιμοποιείται συνήθως @code{'<string>'}).

Το όρισμα `mode' καθορίζει το είδος του κώδικα που πρέπει να μεταγλωττιστεί∙ μπορεί να είναι @code{'exec'} εάν η `source' αποτελείται από μια ακολουθία δηλώσεων, @code{'eval'} εάν αποτελείται από μία μόνο έκφραση, ή @code{'single'} εάν αποτελείται από μία μόνο διαδραστική πρόταση (στην τελευταία περίπτωση, θα εκτυπωθούν δηλώσεις έκφρασης που αξιολογούνται σε κάτι διαφορετικό από @code{None}).

Τα προαιρετικά ορίσματα `flags' και `dont_inherit' ελέγχουν ποιες @ref{27c0,,compiler options} θα πρέπει να ενεργοποιηθούν και ποιες @ref{670,,future features} θα πρέπει να επιτρέπονται. Εάν δεν υπάρχει καμία (ή και οι δύο είναι μηδέν) ο κώδικας μεταγλωττίζεται με τα ίδια flags που επηρεάζουν τον κώδικα που καλεί @ref{1c8,,compile()}. Εάν το όρισμα `flags' δίνεται και το `dont_inherit' δεν είναι (ή είναι μηδέν), τότε οι επιλογές του μεταγλωττιστή και οι μελλοντικές δηλώσεις που καθορίζονται από το όρισμα `flags' χρησιμοποιούνται ανεξάρτητα από αυτές που θα χρησιμοποιούνταν ούτως ή άλλως. Εάν το `dont_inherit' είναι ένα μη μηδενικός ακέραιος, τότε το όρισμα `flags' είναι αυτό – οι σημαίες (μελλοντικές δυνατότητες και επιλογές μεταγλωττιστή) στον περιβάλλοντα κώδικα αγνοούνται.

Οι επιλογές του μεταγλωττιστή και οι μελλοντικές εντολές καθορίζονται από bits που μπορούν να συνδυαστούν κατά bit ORed μαζί για να καθορίσουν πολλές επιλογές. Το πεδίο bit που απαιτείται για το καθορισμό ενός δεδομένου μελλοντικού χαρακτηριστικού μπορεί να βρεθεί ως το χαρακτηριστικό @ref{2587,,compiler_flag} στο @ref{27c1,,_Feature} instance του module @ref{0,,__future__}. @ref{27c0,,Compiler flags} μπορούν να βρεθούν στο module @ref{9,,ast}, με το πρόθεμα @code{PyCF_}.

Το όρισμα `optimize' καθορίζει το επίπεδο βελτιστοποίησης του μεταγλωττιστή∙ η προεπιλεγμένη τιμή @code{-1} επιλέγει το επίπεδο βελτιστοποίησης του διερμηνέα όπως δίνεται από τις επιλογές @ref{431,,-O}.  Τα ρητά επίπεδα είναι @code{0} (χωρίς βελτιστοποίηση∙ το @code{__debug__} είναι αληθές), @code{1} (οι ισχυρισμοί καταργήθηκαν, το @code{__debug__} είναι ψευδές) ή @code{2} (οι συμβολοσειρές εγγραφών καταργήθηκαν επίσης).

The optional argument `module' specifies the module name.
It is needed to unambiguous @ref{1cc,,filter} syntax warnings
by module name.

This function raises @ref{17e,,SyntaxError} or @ref{277,,ValueError} if the compiled
source is invalid.

Εάν θέλετε να αναλύσετε τον κώδικα Python στην αναπαράσταση του AST, δείτε το @ref{1c9,,ast.parse()}.

Κάνει raise ένα @ref{1e65,,auditing event} @code{compile} με ορίσματα @code{source} και @code{filename}. Αυτό το συμβάν μπορεί επίσης να προκύψει από έμμεση μεταγλώττιση.

@cartouche
@quotation Σημείωση 
Κατά τη μεταγλώττιση μιας συμβολοσειράς με κωδικό πολλαπλών γραμμών στη λειτουργία @code{'single'} ή @code{'eval'}, η είσοδος πρέπει να τερματίζεται με τουλάχιστον έναν χαρακτήρα νέας γραμμής.  Αυτό γίνεται για να διευκολυνθεί ο εντοπισμός μη ολοκληρωμένων και ολοκληρωμένων δηλώσεων στο module @ref{1b,,code}.
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
Είναι δυνατό να καταρρεύσει ο interpreter της Python με μια αρκετά μεγάλη/σύνθετη συμβολοσειρά κατά τη μεταγλώττιση σε ένα αντικείμενο AST λόγω περιορισμών βάθους στοίβας στον μεταγλωττιστή AST της Python.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.2: Επιτρέπεται η χρήση νέων γραμμών Windows και Mac.  Επίσης, η εισαγωγή στη λειτουργία @code{'exec'} δεν χρειάζεται πλέον να τελειώνει σε νέα γραμμή.  Προστέθηκε η παράμετρος `optimize'.



Άλλαξε στην έκδοση 3.5: Προηγουμένως, το @ref{291,,TypeError} έγινε raise όταν null bytes συναντήθηκαν στο `source'.



Added in version 3.8: @code{ast.PyCF_ALLOW_TOP_LEVEL_AWAIT} μπορεί τώρα να μεταβιβαστεί σε σημαίες για να ενεργοποιηθεί η υποστήριξη για @code{await}, @code{async for}, και @code{async with}.



Added in version 3.15: Added the `module' parameter.

@end deffn

@geindex complex (ενσωματωμένη κλάση)
@anchor{library/functions complex}@anchor{328}
@deffn {Κλάση} complex (number=0, /)

@deffnx {Κλάση} complex (string, /)

@deffnx {Κλάση} complex (real=0, imag=0)

Μετατρέπει μια συμβολοσειρά ή έναν αριθμό σε έναν μιγαδικό αριθμό ή δημιουργεί έναν μιγαδικό αριθμός από πραγματικά και φανταστικά μέρη.

Παραδείγματα:

@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

Αν το όρισμα είναι συμβολοσειρά, πρέπει να περιέχει είτε ένα πραγματικό μέρος (στην ίδια μορφή όπως για το @ref{327,,float()}) είτε ένα φανταστικό μέρος (στην ίδια μορφή αλλά με επίθημα @code{'j'} ή @code{'J'}) ή και πραγματικά και φανταστικά μέρη (το πρόσημο του φανταστικού τμήματος είναι υποχρεωτικό σε αυτήν την περίπτωση). Η συμβολοσειρά μπορεί προαιρετικά να περιβάλλεται από κενά διαστήματα και τις στρογγυλές παρενθέσεις @code{'('} και @code{')'} οι οποίες αγνοούνται. Η συμβολοσειρά δεν πρέπει να περιέχει κενό διάστημα μεταξύ των @code{'+'}, @code{'-'} του επιθέματος @code{'j'} ή @code{'J'} και του δεκαδικού αριθμού. Για παράδειγμα, το @code{complex('1+2j')} είναι εντάξει, αλλά το @code{complex('1 + 2j')} κάνει raise μια @ref{277,,ValueError}. Πιο συγκεκριμένα, η είσοδος πρέπει να συμμορφώνεται με τον κανόνας παραγωγής @ref{27c2,,complexvalue} στην ακόλουθη γραμματική, αφού αφαιρεθούν οι παρενθέσεις και οι χαρακτήρες του κενών διαστημάτων στο τέλος:

@example
@anchor{library/functions grammar-token-float-complexvalue}@anchor{27c2}complexvalue: @ref{27c3,,floatvalue} |
              @ref{27c3,,floatvalue} ("j" | "J") |
              @ref{27c3,,floatvalue} @ref{27c4,,sign} @ref{27c5,,absfloatvalue} ("j" | "J")
@end example

Εάν το όρισμα είναι αριθμός, ο κατασκευαστής χρησιμεύει ως αριθμητική μετατροπή όπως @ref{326,,int} και @ref{327,,float}. Για ένα γενικό αντικείμενο Python @code{x}, το @code{complex(x)} εκχωρεί στο @code{x.__complex__()}. Εάν το @ref{9de,,__complex__()} δεν έχει οριστεί, τότε επιστρέφει στο @ref{d92,,__float__()}. Εάν το @code{__float__()} δεν έχει οριστεί τότε επιστρέφει στο @ref{43d,,__index__()}.

Εάν παρέχονται δύο ορίσματα ή χρησιμοποιούνται ορίσματα λέξης-κλειδιού, κάθε όρισμα μπορεί να είναι οποιουδήποτε αριθμητικού τύπου (συμπεριλαμβανομένων των μιγαδικών). Εάν και τα δύο ορίσματα είναι πραγματικοί αριθμοί, επιστρέψτε έναν μιγαδικό αριθμό με το πραγματικό στοιχείο `real' και το φανταστικό στοιχείο `imag'. Εάν και τα δύο ορίσματα είναι μιγαδικοί αριθμοί, επιστρέψτε έναν μιγαδικό αριθμό με το πραγματικό στοιχείο @code{real.real-imag.imag} και @code{real.imag+imag.real}. Αν ένα από τα ορίσματα είναι πραγματικός αριθμός, χρησιμοποιείται μόνο το πραγματικό στοιχείο στις παραπάνω εκφράσεις.

Δείτε επίσης την @ref{438,,complex.from_number()} που δέχεται μόνο ένα αριθμητικό όρισμα.

Εάν παραληφθούν όλα τα ορίσματα, επιστρέφει @code{0j}.

Ο μιγαδικός τύπος περιγράφεται στο @ref{21c9,,Αριμθητικοί Τύποι — int@comma{} float@comma{} complex}.


Άλλαξε στην έκδοση 3.6: Επιτρέπεται η ομαδοποίηση ψηφίων με κάτω παύλες όπως στα literals του κώδικα.



Άλλαξε στην έκδοση 3.8: Επιστρέφει πίσω στη @ref{43d,,__index__()} εάν η @ref{9de,,__complex__()} και η @ref{d92,,__float__()} δεν ορίζονται.



Αποσύρθηκε στην έκδοση 3.14: Η διαβίβαση ενός μιγαδικού αριθμού ως το `real' ή `imag' όρισμα έχει πλέον καταργηθεί∙ θα πρέπει να διαβιβάζεται μόνο ως ένα μοναδικό όρισμα θέσης.

@end deffn

@geindex built-in function; delattr()
@anchor{library/functions delattr}@anchor{1aa}
@deffn {Συνάρτηση} delattr (object, name, /)

Αυτό είναι σχετικό της @ref{27b7,,setattr()}.  Τα ορίσματα είναι ένα αντικείμενο και μια συμβολοσειρά.  Η συμβολοσειρά πρέπει να είναι το όνομα ενός από τα χαρακτηριστικά του αντικειμένου.  Η συνάρτηση διαγράφει το επώνυμο χαρακτηριστικό, υπό την προϋπόθεση ότι το αντικείμενο το επιτρέπει. Για παράδειγμα, το @code{delattr(x, 'foobar')} είναι ισοδύναμο με το @code{del x.foobar}. Το `name' δεν χρειάζεται να είναι αναγνωριστικό της Python (δείτε @code{setattr()}).
@end deffn

@anchor{library/functions func-dict}@anchor{27b1}
@deffn {Κλάση} dict (**kwargs)

@deffnx {Κλάση} dict (mapping, /, **kwargs)

@deffnx {Κλάση} dict (iterable, /, **kwargs)

Δημιουργεί ένα νέο λεξικό.  Το αντικείμενο @ref{188,,dict} είναι η κλάση λεξικού. Δείτε το @code{dict} και το @ref{e8c,,Mapping types — dict@comma{} frozendict} για τεκμηρίωση σχετικά με αυτή την κατηγορία.

Για άλλα containers, δείτε τις ενσωματωμένες κλάσεις @ref{4d9,,list}, @ref{42b,,set}, και @ref{1ce,,tuple}, καθώς και το module @ref{1e,,collections}.
@end deffn

@geindex built-in function; dir()
@anchor{library/functions dir}@anchor{a23}
@deffn {Συνάρτηση} dir ()

@deffnx {Συνάρτηση} dir (object, /)

Χωρίς ορίσματα, επιστρέφει τη λίστα ονομάτων στο τρέχον τοπικό πεδίο.  Με ένα όρισμα, προσπαθεί να επιστρέψει μια λίστα έγκυρων χαρακτηριστικών για αυτό το αντικείμενο.

Εάν το αντικείμενο έχει μία μέθοδο με το όνομα @ref{1935,,__dir__()}, αυτή η μέθοδος θα καλείται και πρέπει να επιστρέψει μια λίστα από χαρακτηριστικά. Αυτό επιτρέπει τα αντικείμενα που υλοποιούν μια εξατομικευμένη συνάρτηση @ref{8e3,,__getattr__()} or @ref{f90,,__getattribute__()} για την προσαρμογή του τρόπου με τον οποίο η @ref{a23,,dir()} αναφέρει τα χαρακτηριστικά.

Εάν το αντικείμενο δεν παρέχει την @ref{1935,,__dir__()}, η συνάρτηση προσπαθεί να συλλέξει πληροφορίες από το χαρακτηριστικό @ref{1bf,,__dict__} του αντικειμένου, εάν έχει οριστεί, και από το αντικείμενο του τύπου του.  Η λίστα που παράγεται ως αποτέλεσμα δεν είναι απαραίτητα πλήρης και μπορεί να είναι ανακριβής όταν το αντικείμενο έχει εξατομικευμένη @ref{8e3,,__getattr__()}.

Ο προεπιλεγμένος μηχανισμός @ref{a23,,dir()} συμπεριφέρεται διαφορετικά με διαφορετικούς τύπους αντικειμένων, καθώς προσπαθεί να παράγει τις πιο σχετικές και όχι τις πιο ολοκληρωμένες πληροφορίες:


@itemize *

@item 
Εάν το αντικείμενο είναι module τύπου αντικειμένου, η λίστα περιέχει τα ονόματα των χαρακτηριστικών του module.

@item 
Εάν το αντικείμενο είναι ένας τύπος ή κλάση αντικειμένου, η λίστα περιέχει τα ονόματα των χαρακτηριστικών του, και αναδρομικά τα χαρακτηριστικά της βάσεώς του.

@item 
Εναλλακτικά, η λίστα περιέχει τα ονόματα των χαρακτηριστικών του αντικειμένου, τα ονόματα των χαρακτηριστικών της κλάσης, και αναδρομικά τα χαρακτηριστικά της κλάσης βάσεως της κλάσης.
@end itemize

Η παραγόμενη λίστα είναι ταξινομημένη αλφαβητικά.  Για παράδειγμα:

@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__', '__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 Σημείωση 
Επειδή η @ref{a23,,dir()} παρέχεται κυρίως ως ευκολία για χρήση σε μια διαδραστική γραμμή εντολών, προσπαθεί να παρέχει ένα ενδιαφέρον σύνολο ονομάτων περισσότερα από οτιδήποτε προσπαθεί να παρέχει ένα αυστηρό ή με συνέπεια, καθορισμένο σύνολο ονομάτων, και η λεπτομερής συμπεριφορά του μπορεί να αλλάξει μεταξύ των εκδόσεων.  Για παράδειγμα, τα χαρακτηριστικά μετακλάσης δεν βρίσκονται στη λίστα αποτελεσμάτων όταν το όρισμα είναι μια κλάση.
@end quotation
@end cartouche
@end deffn

@geindex built-in function; divmod()
@anchor{library/functions divmod}@anchor{d6a}
@deffn {Συνάρτηση} divmod (a, b, /)

Λαμβάνει δύο (μη μιγαδικούς) αριθμούς ως ορίσματα και επιστρέφει ένα ζεύγος αριθμών που αποτελείται από το πηλίκο και το υπόλοιπο τους όταν χρησιμοποιείται σε διαίρεση ακεραίου αριθμού.  Με μεικτούς τύπους τελεστών, ισχύουν οι κανόνες για δυαδικούς τελεστές αριθμητικής.  Για ακέραιους αριθμούς, το αποτέλεσμα είναι το ίδιο με @code{(a // b, a % b)}. Για αριθμούς κινητής υποδιαστολής το αποτέλεσμα είναι @code{(q, a % b)}, όπου το `q' είναι συνήθως @code{math.floor(a / b)} αλλά μπορεί να είναι μικρότερο κατά 1.  Σε κάθε περίπτωση, το @code{q * b + a % b} είναι πολύ κοντά στο `a', αν το @code{a % b} δεν είναι μηδενικό, έχει το ίδιο πρόσημο όπως το `b', και @code{0 <= abs(a % b) < abs(b)}.
@end deffn

@geindex built-in function; enumerate()
@anchor{library/functions enumerate}@anchor{1823}
@deffn {Συνάρτηση} enumerate (iterable, start=0)

Επιστρέφει ένα αντικείμενο απαρίθμησης.  Το `iterable' πρέπει να είναι μια ακολουθία, ένα @ref{6ce,,iterator}, ή κάποιο άλλο αντικείμενο που υποστηρίζει το iteration. Η μέθοδος @ref{1672,,__next__()} του iterator που επιστρέφεται από το @ref{1823,,enumerate()} επιστρέφει μια πλειάδα (tuple) που περιέχει μια καταμέτρηση (από το `start' που είναι με προεπιλογή στο 0) και τις τιμές που λαμβάνονται από την επανάληψη πάνω στο `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

Ισοδύναμο με:

@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{27c6}@anchor{library/functions eval}@anchor{184}
@deffn {Συνάρτηση} eval (source, /, globals=None, locals=None)

@*Παράμετροι: 

@itemize *

@item 
@code{source} (@ref{1df,,str} | @ref{6eb,,code object}) – Μια έκφραση Python.

@item 
@code{globals} (@ref{188,,dict} | @ref{182,,frozendict} | @code{None}) – Το καθολικό namespace (προεπιλογή: @code{None}).

@item 
@code{locals} (@ref{1564,,mapping} | @code{None}) – Το τοπικό namespace (προεπιλογή: @code{None}).
@end itemize


@*Επιστρέφει: 
Το αποτέλεσμα της αξιολογούμενης έκφρασης.


@*κάνει raise: 
Τα συντακτικά σφάλματα αναφέρονται ως εξαιρέσεις.


@cartouche
@quotation Προειδοποίηση 
This function executes arbitrary code. Calling it with
untrusted user-supplied input will lead to security vulnerabilities.
@end quotation
@end cartouche

The `source' 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{13,,builtins} is
inserted under that key before `source' is parsed.
Overriding @code{__builtins__} can be used to restrict or change the available
names, but this is `not' a security mechanism: the executed code can
still access all builtins.
If the `locals' mapping is omitted it defaults to the
`globals' dictionary.  If both mappings are omitted, the source is
executed with the `globals' and `locals' in the environment where
@code{eval()} is called.  Note, `eval()' will only have access to the
@ref{2581,,nested scopes} (non-locals) in the enclosing
environment if they are already referenced in the scope that is calling
@code{eval()} (e.g. via a @ref{164c,,nonlocal} statement).

Παράδειγμα:

@example
>>> x = 1
>>> eval('x+1')
2
@end example

Αυτή η συνάρτηση μπορεί επίσης να χρησιμοποιηθεί για την εκτέλεση αυθαίρετων αντικειμένων κώδικα (όπως αυτά που δημιουργούνται από την @ref{1c8,,compile()}).  Σε αυτή την περίπτωση, μεταβιβάζει ένα αντικείμενο κώδικα αντί για μια συμβολοσειρά.  Εάν το αντικείμενο κώδικα έχει μεταγλωττιστεί με @code{'exec'} ως το όρισμα `mode', η επιστρεφόμενη τιμή του @ref{184,,eval()}'s θα είναι @code{None}.

Συμβουλές: η δυναμική εκτέλεση εντολών υποστηρίζεται από την συνάρτηση @ref{185,,exec()}.  Οι συναρτήσεις @ref{1e01,,globals()} και @ref{28b,,locals()} επιστρέφουν το τρέχον global και local λεξικό, αντίστοιχα, το οποίο μπορεί να είναι χρήσιμο για μεταβίβαση γύρω από τη χρήση από τις @ref{184,,eval()} ή @code{exec()}.

Εάν η δεδομένη πηγή είναι μια συμβολοσειρά, τότε αφαιρούνται τα κενά και τα tabs που προηγούνται ή έπονται.

See @ref{fd7,,ast.literal_eval()} for a function to evaluate strings
with expressions containing only literals.

Κάνει raise ένα @ref{1e65,,auditing event} @code{exec} με το αντικείμενο κώδικα ως όρισμα. Μπορεί επίσης να εμφανιστούν συμβάντα μεταγλώττισης κώδικα.


Άλλαξε στην έκδοση 3.13: Τα ορίσματα `globals' και `locals' υποστηρίζονται πλέον και ως ορίσματα λέξεων-κλειδιών.



Άλλαξε στην έκδοση 3.13: Η σημασιολογία του προεπιλεγμένου ονόματος χώρου `locals' έχει τροποποιηθεί, όπως περιγράφεται για την ενσωματωμένη συνάρτηση @ref{28b,,locals()}.



Άλλαξε στην έκδοση 3.15: `globals' can now be a @ref{182,,frozendict}.

@end deffn

@geindex ενσωματωμένη συνάρτηση;exec

@geindex built-in function; exec()
@anchor{library/functions exec}@anchor{185}
@deffn {Συνάρτηση} exec (source, /, globals=None, locals=None, *, closure=None)

@cartouche
@quotation Προειδοποίηση 
This function executes arbitrary code. Calling it with
untrusted user-supplied input will lead to security vulnerabilities.
@end quotation
@end cartouche

Αυτή η συνάρτηση υποστηρίζει δυναμική εκτέλεση κώδικα Python. Το `source' πρέπει να είναι είτε μια συμβολοσειρά (string) είτε ένα αντικείμενο κώδικα.  Εάν είναι μια συμβολοσειρά, η συμβολοσειρά αναλύεται ως μια σουίτα δηλώσεων Python που στη συνέχεια εκτελείται (εκτός εάν παρουσιαστεί σφάλμα σύνταξης). @footnote{
Λάβετε υπόψη ότι ο αναλυτής δέχεται μόνο τη σύμβαση τέλους γραμμής τύπου Unix. Εάν διαβάζετε τον κώδικα από ένα αρχείο βεβαιωθείτε ότι χρησιμοποιείτε την λειτουργία μετατροπής νέας γραμμής για την μετατροπή νέων γραμμών σε στυλ Windows ή Mac.
} Εάν πρόκειται για ένα αντικείμενο κώδικα, απλά εκτελείται.  Σε όλες τις περιπτώσεις, ο κώδικας που εκτελείται αναμένεται να είναι έγκυρος ως είσοδος αρχείου (δείτε την ενότητα @ref{2798,,Είσοδος από αρχείο} στο Εγχειρίδιο Αναφοράς). Λάβετε υπόψη ότι οι εντολές @ref{164c,,nonlocal}, @ref{d93,,yield},  και @ref{44b,,return} δεν μπορούν να χρησιμοποιηθούν εκτός των ορισμών συναρτήσεων, ακόμη και στο πλαίσιο του κώδικα που διαβιβάζεται στη @ref{185,,exec()}. Η επιστρεφόμενη τιμή είναι @code{None}.

Σε όλες τις περιπτώσεις, εάν παραληφθούν τα προαιρετικά μέρη, ο κώδικας εκτελείται στο τρέχον εύρος.  Εάν παρέχεται μόνο `globals', πρέπει να είναι ένα λεξικό (και όχι μια υποκατηγορία λεξικού), το οποίο θα χρησιμοποιείται και για τις δύο μεταβλητές αντίστοιχα.  Εάν παρέχονται τα `locals' μπορεί να είναι οποιοδήποτε αντικείμενο αντιστοίχισης.  Να θυμάστε ότι σε επίπεδο module, τα globals και locals είναι το ίδιο λεξικό.

@cartouche
@quotation Σημείωση 
Όταν η @code{exec} λαμβάνει δύο ξεχωριστά αντικείμενα ως `globals' και `locals', ο κώδικας εκτελείται σαν να ήταν ενσωματωμένος σε ορισμό κλάσης. Αυτό σημαίνει ότι συναρτήσεις και κλάσεις που ορίζονται στον εκτελούμενο κώδικα δεν θα έχουν πρόσβαση σε μεταβλητές που έχουν οριστεί στο ανώτερο επίπεδο (καθώς αυτές οι «ανωτέρου επιπέδου» μεταβλητές θεωρούνται ως μεταβλητές κλάσης, όπως συμβαίνει μέσα σε έναν ορισμό κλάσης).
@end quotation
@end cartouche

If the `globals' dictionary does not contain a value for the key
@code{__builtins__}, a reference to the dictionary of the built-in module
@ref{13,,builtins} is inserted under that key.
Overriding @code{__builtins__} can be used to restrict or change the available
names, but this is `not' a security mechanism: the executed code can
still access all builtins.

Το όρισμα `closure' καθορίζει ένα clossure–μια πλειάδα από cellvars. Είναι έγκυρο μόνο όταν το `object' είναι ένα αντικείμενο κώδικα που περιέχει @ref{1ab7,,free (closure) variables}. Το μήκος της πλειάδας πρέπει να ταιριάζει ακριβώς με το μήκος το χαρακτηριστικό @ref{2538,,co_freevars} του αντικειμένου κώδικα.

Κάνει raise ένα @ref{1e65,,auditing event} @code{exec} με το αντικείμενο κώδικα ως όρισμα. Μπορεί επίσης να εμφανιστούν συμβάντα μεταγλώττισης κώδικα.

@cartouche
@quotation Σημείωση 
Οι ενσωματωμένες συναρτήσεις @ref{1e01,,globals()} και @ref{28b,,locals()} επιστρέφουν το τρέχον χώρο ονομάτων global και local, αντίστοιχα, που μπορεί να είναι χρήσιμο για χρήση ως δεύτερο και τρίτο όρισμα στο @ref{185,,exec()}.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Το προεπιλεγμένο `locals' ενεργεί όπως περιγράφεται για τη συνάρτηση @ref{28b,,locals()} παρακάτω. Δώστε ρητά ένα λεξικό `locals' αν χρειάζεται να δείτε τις επιδράσεις του κώδικα `locals' μετά την επιστροφή της συνάρτησης @ref{185,,exec()}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.11: Προστέθηκε η παράμετρος `closure'.



Άλλαξε στην έκδοση 3.13: Τα ορίσματα `globals' και `locals' υποστηρίζονται πλέον και ως ορίσματα λέξεων-κλειδιών.



Άλλαξε στην έκδοση 3.13: Η σημασιολογία του προεπιλεγμένου ονόματος χώρου `locals' έχει τροποποιηθεί, όπως περιγράφεται για την ενσωματωμένη συνάρτηση @ref{28b,,locals()}.



Άλλαξε στην έκδοση 3.15: `globals' can now be a @ref{182,,frozendict}.

@end deffn

@geindex built-in function; filter()
@anchor{library/functions filter}@anchor{c3b}
@deffn {Συνάρτηση} filter (function, iterable, /)

Δημιουργεί έναν iterator από εκείνα τα στοιχεία του `iterable' για τα οποία η `function' είναι αληθής.  Το `iterable' μπορεί να είναι είτε μια ακολουθία, ένα container που υποστηρίζει iteration, ή ένας iterator.  Εάν η `function' είναι @code{None}, η συνάρτηση ταυτότητας υποτίθεται, δηλαδή, όλα τα στοιχεία του `iterable' που είναι ψευδή αφαιρούνται.

Λάβετε υπόψη ότι το @code{filter(function, iterable)} είναι ισοδύναμο με την έκφραση της γεννήτριας @code{(item for item in iterable if function(item))} εάν η συνάρτηση δεν είναι @code{None} και @code{(item for item in iterable if item)} εάν η συνάρτηση είναι @code{None}.

Βλ. @ref{27c7,,itertools.filterfalse()} για τη συμπληρωματική συνάρτηση που επιστρέφει στοιχεία του `iterable' για τα οποία η `function' είναι ψευδής.
@end deffn

@geindex float (ενσωματωμένη κλάση)
@anchor{library/functions float}@anchor{327}
@deffn {Κλάση} float (number=0.0, /)

@deffnx {Κλάση} float (string, /)

@geindex NaN
@geindex Άπειρο

Επιστέφει έναν αριθμό κινητής υποδιαστολής που κατασκευάστηκε από έναν αριθμό ή μια συμβολοσειρά.

Παραδείγματα:

@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

Εάν το όρισμα είναι συμβολοσειρά (string), θα πρέπει να περιέχει έναν δεκαδικό αριθμό, προαιρετικά πριν από ένα σύμβολο και προαιρετικά ενσωματωμένο σε κενό διάστημα.  Το προαιρετικό πρόσημο μπορεί να είναι @code{'+'} ή @code{'-'} ∙ ένα σύμβολο @code{'+'} δεν έχει καμία επίδραση στην τιμή που παράγεται.  Το όρισμα μπορεί επίσης να είναι μια συμβολοσειρά που αντιπροσωπεύει ένα NaN (not-a-number), ή θετικό η αρνητικό άπειρο. Πιο συγκεκριμένα, η είσοδος πρέπει να συμμορφώνεται με τον κανόνα παραγωγής @ref{27c3,,floatvalue} στην ακόλουθη γραμματική, αφού αφαιρεθούν οι χαρακτήρες κενού διαστήματος που έπονται και προηγούνται:

@example
@anchor{library/functions grammar-token-float-sign}@anchor{27c4}sign:          "+" | "-"
@anchor{library/functions grammar-token-float-infinity}@anchor{27c8}infinity:      "Infinity" | "inf"
@anchor{library/functions grammar-token-float-nan}@anchor{27c9}nan:           "nan"
@anchor{library/functions grammar-token-float-digit}@anchor{27ca}digit:         <a Unicode decimal digit, i.e. characters in Unicode general category Nd>
@anchor{library/functions grammar-token-float-digitpart}@anchor{27cb}digitpart:     @ref{27ca,,digit} (["_"] @ref{27ca,,digit})*
@anchor{library/functions grammar-token-float-number}@anchor{27cc}number:        [@ref{27cb,,digitpart}] "." @ref{27cb,,digitpart} | @ref{27cb,,digitpart} ["."]
@anchor{library/functions grammar-token-float-exponent}@anchor{27cd}exponent:      ("e" | "E") [@ref{27c4,,sign}] @ref{27cb,,digitpart}
@anchor{library/functions grammar-token-float-floatnumber}@anchor{27ce}floatnumber:   @ref{27cc,,number} [@ref{27cd,,exponent}]
@anchor{library/functions grammar-token-float-absfloatvalue}@anchor{27c5}absfloatvalue: @ref{27ce,,floatnumber} | @ref{27c8,,infinity} | @ref{27c9,,nan}
@anchor{library/functions grammar-token-float-floatvalue}@anchor{27c3}floatvalue:    [@ref{27c4,,sign}] @ref{27c5,,absfloatvalue}
@end example

Τα πεζά/κεφαλαία δεν είναι σημαντικά, επομένως, για παράδειγμα, «inf», «Inf», «INFINITY», και «iNfINity» είναι όλες αποδεκτές ορθογραφίες για το θετικό άπειρο.

Διαφορετικά, εάν το όρισμα είναι ακέραιος ή αριθμός κινητής υποδιαστολής, επιστρέφεται ένας αριθμός κινητής υποδιαστολής με την ίδια τιμή (εντός της ακρίβειας κινητής υποδιαστολής της Python). Εάν το όρισμα βρίσκεται εκτός του εύρους ενός float της Python θα γίνει raise ένα @ref{c57,,OverflowError}.

Για ένα γενικό αντικείμενο Python @code{x}, @code{float(x)} εκχωρεί στο @code{x.__float__()}.  Εάν το @ref{d92,,__float__()} δεν έχει οριστεί, τότε επιστρέφει στο @ref{43d,,__index__()}.

Δείτε επίσης τη @ref{437,,float.from_number()} που δέχεται μόνο αριθμητικό όρισμα.

Εάν δεν δοθεί όρισμα, επιστρέφεται το @code{0.0}.

Ο τύπος float περιγράφεται στο @ref{21c9,,Αριμθητικοί Τύποι — int@comma{} float@comma{} complex}.


Άλλαξε στην έκδοση 3.6: Επιτρέπεται η ομαδοποίηση ψηφίων με κάτω παύλες όπως στα literals του κώδικα.



Άλλαξε στην έκδοση 3.7: Η παράμετρος είναι πλέον μόνο παράμετρος θέσης.



Άλλαξε στην έκδοση 3.8: Επιστρέφει στο @ref{43d,,__index__()} εάν το @ref{d92,,__float__()} δεν έχει οριστεί.

@end deffn

@geindex __format__
@geindex string;format() (ενσωματωμένη συνάρτηση)

@geindex built-in function; format()
@anchor{library/functions format}@anchor{439}
@deffn {Συνάρτηση} format (value, format_spec='@w{'}, /)

Μετατρέπει ένα `value' σε μια αναπαράσταση «formatted», όπως ελέγχεται από το `format_spec'.  Η ερμηνεία του `format_spec' θα εξαρτηθεί από τον τύπο του ορίσματος `value' ∙ ωστόσο υπάρχει μια τυπική σύνταξη μορφοποίησης που χρησιμοποιείται από τους περισσότερους ενσωματωμένους τύπους: @ref{6fe,,Format specification mini-language}.

Η προεπιλεγμένη `format_spec' είναι μια κενή συμβολοσειρά που συνήθως δίνει το ίδιο αποτέλεσμα με την κλήση του @ref{1df,,str(value)}.

Μια κλήση στο @code{format(value, format_spec)} μεταφράζεται σε @code{type(value).__format__(value, format_spec)} το οποίο παρακάμπτει το instance του λεξικού κατά την αναζήτηση της τιμής της μεθόδου @ref{a10,,__format__()}. Μια εξαίρεση @ref{291,,TypeError} γίνεται raise εάν η αναζήτηση της μεθόδου φτάσει στο @ref{e4d,,object} και το `format_spec' δεν είναι κενό ή εάν είτε το `format_spec' είτε η τιμή επιστροφής δεν είναι συμβολοσειρές.


Άλλαξε στην έκδοση 3.4: Το @code{object().__format__(format_spec)} κάνει raise το @ref{291,,TypeError} εάν το `format_spec' δεν είναι κενή συμβολοσειρά.

@end deffn

@anchor{library/functions func-frozenset}@anchor{27b2}
@deffn {Κλάση} frozenset (iterable=(), /)

Επιστρέφει ένα νέο αντικείμενο @ref{9d4,,frozenset}, προαιρετικά με στοιχεία που λαμβάνονται από το `iterable'.  Το @code{frozenset} είναι μια ενσωματωμένη κλάση.  Δείτε το @code{frozenset} και το @ref{2220,,Τύποι Συνόλου (Set) — set@comma{} frozenset} για τεκμηρίωση αυτής της κλάσης.

Για άλλα containers, ανατρέξτε στις ενσωματωμένες κλάσεις @ref{42b,,set}, @ref{4d9,,list}, @ref{1ce,,tuple}, και @ref{188,,dict}, καθώς και το module @ref{1e,,collections}.
@end deffn

@geindex built-in function; getattr()
@anchor{library/functions getattr}@anchor{f8f}
@deffn {Συνάρτηση} getattr (object, name, /)

@deffnx {Συνάρτηση} getattr (object, name, default, /)

Επιστρέφει την τιμή του ονομασμένου χαρακτηριστικού του `object'  Το `name' πρέπει να είναι μια συμβολοσειρά. Εάν η συμβολοσειρά είναι το όνομα ενός από τα χαρακτηριστικά του αντικειμένου, το αποτέλεσμα είναι η τιμή αυτού του χαρακτηριστικού.  Για παράδειγμα, @code{getattr(x, 'foobar')} είναι ισοδύναμο με το @code{x.foobar}.  Εάν το χαρακτηριστικό γνώρισμα δεν υπάρχει, το `default' επιστρέφεται εάν παρέχεται, διαφορετικά γίνεται raise το @ref{1a9,,AttributeError}.  Το `name' δεν χρειάζεται να είναι αναγνωριστικό Python (δείτε @ref{27b7,,setattr()}).

@cartouche
@quotation Σημείωση 
Δεδομένου ότι το @ref{2293,,private name mangling} συμβαίνει κατά τη στιγμή της μεταγλώττισης, πρέπει κανείς να παραμορφώνει χειροκίνητα το όνομα ενός ιδιωτικού χαρακτηριστικού (χαρακτηριστικά με δύο κορυφαίες υπογραμμίσεις) για να ανακτήσει με @ref{f8f,,getattr()}.
@end quotation
@end cartouche
@end deffn

@geindex built-in function; globals()
@anchor{library/functions globals}@anchor{1e01}
@deffn {Συνάρτηση} globals ()

Επιστρέφει το λεξικό που υλοποιεί τον τρέχοντα χώρο ονομάτων του module. Για κώδικα εντός συναρτήσεων, αυτό ορίζεται όταν ορίζεται η συνάρτηση και παραμένει το ίδιο ανεξάρτητη από το που καλείται η συνάρτηση.
@end deffn

@geindex built-in function; hasattr()
@anchor{library/functions hasattr}@anchor{8e2}
@deffn {Συνάρτηση} hasattr (object, name, /)

Τα ορίσματα είναι ένα αντικείμενο και μια συμβολοσειρά (string).  Το αποτέλεσμα είναι @code{True} εάν η συμβολοσειρά είναι το όνομα ενός από τα χαρακτηριστικά του αντικειμένου, @code{False} εάν όχι. (Αυτό υλοποιείται καλώντας το @code{getattr(object, name)} και να δούμε αν γίνεται raise ένα @ref{1a9,,AttributeError} ή όχι.)
@end deffn

@geindex built-in function; hash()
@anchor{library/functions hash}@anchor{9e2}
@deffn {Συνάρτηση} hash (object, /)

Επιστρέφει την τιμή κατακερματισμού του αντικειμένου (αν έχει).  Οι τιμές κατακερματισμού είναι ακέραιοι.  Χρησιμοποιούνται για τη γρήγορη σύγκριση των κλειδιών του λεξικού κατά τη διάρκεια μιας αναζήτησης λεξικού.  Οι αριθμητικές τιμές που συγκρίνονται ίσες έχουν την ίδια τιμή κατακερματισμού (ακόμα και αν είναι διαφορετικοί τύποι, όπως συμβαίνει για τα 1 και 1.0).

@cartouche
@quotation Σημείωση 
Για αντικείμενα με προσαρμοσμένες μεθόδους @ref{ec1,,__hash__()}, σημειώστε ότι το @ref{9e2,,hash()} περικόπτει την τιμή επιστροφής με βάση το πλάτος bit του υπολογιστή.
@end quotation
@end cartouche
@end deffn

@geindex built-in function; help()
@anchor{library/functions help}@anchor{ca9}
@deffn {Συνάρτηση} help ()

@deffnx {Συνάρτηση} help (request)

Καλείται το ενσωματωμένο (built-in) σύστημα βοήθειας.  (Αυτή η συνάρτηση προορίζεται για διαδραστική χρήση.)  Εάν δεν δοθεί όρισμα, το διαδραστικό σύστημα βοήθειας ξεκινά την κονσόλα του interpreter.  Εάν το όρισμα είναι μια συμβολοσειρά, τότε η συμβολοσειρά αναζητείται ως όνομα ενός module, μιας συνάρτησης, μια κλάσης μιας μεθόδου, μιας λέξης κλειδιού ή θέματος τεκμηρίωσης και μια σελίδα βοήθειας εκτυπώνεται στην κονσόλα.  Εάν το όρισμα είναι οποιοδήποτε άλλο είδος αντικειμένου, δημιουργείται μια σελίδα βοήθειας στο αντικείμενο.

Λάβετε υπόψη ότι εάν εμφανίζεται μια κάθετος (/) στη λίστα παραμέτρων μιας συνάρτησης κατά την κλήση @ref{ca9,,help()}, σημαίνει ότι οι παράμετροι πριν από την κάθετο είναι μόνο θέσης. Για περισσότερες πληροφορίες, βλέπε @ref{27cf,,the FAQ entry on positional-only parameters}.

Αυτή η συνάρτηση προστίθεται στον ενσωματωμένο χώρο ονομάτων από το module @ref{cf,,site}.


Άλλαξε στην έκδοση 3.4: Οι αλλαγές σε @ref{bd,,pydoc} και @ref{81,,inspect} σημαίνουν ότι οι αναφερόμενες υπογραφές για callables είναι πλέον πιο ολοκληρωμένες και συνεπείς.

@end deffn

@geindex built-in function; hex()
@anchor{library/functions hex}@anchor{1674}
@deffn {Συνάρτηση} hex (integer, /)

Μετατροπή ενός ακεραίου αριθμού σε μια πεζή δεκαεξαδική συμβολοσειρά (string) με πρόθεμα το «0x». Εάν το `integer' δεν είναι αντικείμενο Python @ref{326,,int}, πρέπει να ορίσει μια μέθοδο @ref{43d,,__index__()} που επιστρέφει έναν ακέραιο αριθμό. Κάποια παραδείγματα:

@example
>>> hex(255)
'0xff'
>>> hex(-42)
'-0x2a'
@end example

Εάν θέλετε να μετατρέψετε έναν ακέραιο αριθμό σε μια κεφαλαία ή πεζή δεκαεξαδική συμβολοσειρά (string) με πρόθεμα ή όχι, μπορείτε να χρησιμοποιήσετε έναν από τους παρακάτω τρόπους:

@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

Δείτε επίσης τη @ref{439,,format()} για περισσότερες πληροφορίες.

Δείτε επίσης τη @ref{326,,int()} για τη μετατροπή μιας δεκαεξαδικής συμβολοσειράς σε ακέραιο χρησιμοποιώντας μια βάση του 16.

@cartouche
@quotation Σημείωση 
Για να αποκτήσετε μια αναπαράσταση δεκαεξαδικής συμβολοσειράς για ένα float, χρησιμοποιήστε τη μέθοδο @ref{22f2,,float.hex()}.
@end quotation
@end cartouche
@end deffn

@geindex built-in function; id()
@anchor{library/functions id}@anchor{17c5}
@deffn {Συνάρτηση} id (object, /)

Επιστρέφει την «ταυτότητα» ενός αντικειμένου.  Αυτό είναι ένα ακέραιος αριθμός που εγγυάται ότι είναι μοναδικός και σταθερός για αυτό το αντικείμενο κατά τη διάρκεια της ζωής του. Δύο αντικείμενα με μη επικαλυπτόμενες διάρκειες ζωής μπορεί να έχουν την ίδια τιμή @ref{17c5,,id()}.

Αυτό είναι η διεύθυνση του αντικειμένου στην μνήμη.

Εγείρει ένα @ref{1e65,,auditing event} @code{builtins.id} με όρισμα @code{id}.
@end deffn

@geindex built-in function; input()
@anchor{library/functions input}@anchor{167d}
@deffn {Συνάρτηση} input ()

@deffnx {Συνάρτηση} input (prompt, /)

Εάν υπάρχει το όρισμα `prompt', γράφεται στην τυπική έξοδο χωρίς μια νέα γραμμή μετάδοσης.  Στη συνέχεια, η συνάρτηση διαβάζει μια γραμμή από την είσοδο, τη μετατρέπει σε μια συμβολοσειρά (με την αφαίρεση μιας νέας γραμμής) και την επιστρέφει.  Όταν διαβάζεται το EOF, γίνεται raise η @ref{167e,,EOFError}.  Παράδειγμα:

@example
>>> s = input('--> ')
--> Monty Python's Flying Circus
>>> s
"Monty Python's Flying Circus"
@end example

Εάν έχει φορτωθεί το module @ref{c2,,readline}, τότε η @ref{167d,,input()} θα το χρησιμοποιήσει για να παρέχει περίπλοκες λειτουργίες επεξεργασίας γραμμής και ιστορικού.

Κάνει raise  ένα @ref{1e65,,auditing event} @code{builtins.input} με όρισμα @code{prompt} προτού διαβάσει την είσοδο

Κάνει raise  ένα @ref{1e65,,auditing event} @code{builtins.input/result} με το αποτέλεσμα μετά την επιτυχή ανάγνωση των δεδομένων.
@end deffn

@geindex int (ενσωματωμένη κλάση)
@anchor{library/functions int}@anchor{326}
@deffn {Κλάση} int (number=0, /)

@deffnx {Κλάση} int (string, /, base=10)

Επιστέφει έναν αριθμό κινητής υποδιαστολής που κατασκευάστηκε από έναν αριθμό ή μια συμβολοσειρά, ή επιστρέφει @code{0} εάν δεν δίνεται κάποιο όρισμα.

Παραδείγματα:

@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

Εάν το όρισμα ορίζει @ref{43c,,__int__()}, @code{int(x)} επιστρέφει @code{x.__int__()}.  Εάν το όρισμα ορίζει @ref{43d,,__index__()}, επιστρέφει @code{x.__index__()}. Για αριθμούς κινητής υποδιαστολής, αυτό περικόπτεται προς το μηδέν.

Εάν το όρισμα δεν είναι αριθμός ή εάν δίνεται `base', τότε πρέπει να είναι μια συμβολοσειρά , @ref{1c7,,bytes}, ή @ref{1c6,,bytearray} που αντιπροσωπεύει έναν ακέραιο αριθμό στην ρίζα `base'.  Προαιρετικά, η συμβολοσειρά μπορεί να προηγείται από @code{+} ή @code{-} (χωρίς κενό ενδιάμεσο), να έχει αρχικά μηδενικά, να περιβάλλεται από κενό διάστημα και να έχει μονές υπογραμμίσεις διάσπαρτες μεταξύ των ψηφίων.

Μια συμβολοσειρά (string) ακέραιου αριθμού βάσης n περιέχει ψηφία, καθένα από τα οποία αντιπροσωπεύει μια τιμή από το 0 έως το n-1. Οι τιμές 0–9 μπορούν να αναπαρασταθούν με οποιοδήποτε δεκαδικό ψηφίο Unicode. Οι τιμές 10–35 μπορούν να αναπαρασταθούν με @code{a} ως το @code{z} (ή @code{A} ως το @code{Z}). Η προεπιλεγμένη `base' είναι 10. Οι επιτρεπόμενες βάσεις είναι 0 και 2–36. Οι συμβολοσειρές βάσης -2, -8 και -16 μπορούν προαιρετικά να έχουν το πρόθεμα @code{0b}/@code{0B}, @code{0o}/@code{0O}, ή @code{0x}/@code{0X}, όπως και με ακέραιους αριθμούς στον κώδικα.  Για την βάση 0, η συμβολοσειρά ερμηνεύεται με παρόμοιο τρόπο με έναν @ref{24fc,,integer literal in code}, στο ότι η πραγματική βάση είναι 2, 8, 10 ή 16 όπως προσδιορίζεται από το πρόθεμα. Η βάση 0 δεν επιτρέπει επίσης τα μηδενικά στην αρχή : @code{int('010', 0)} δεν είναι εφικτό, ενώ το @code{int('010')} και @code{int('010', 8)} είναι.

Ο ακέραιος τύπος περιγράφεται στο @ref{21c9,,Αριμθητικοί Τύποι — int@comma{} float@comma{} complex}.


Άλλαξε στην έκδοση 3.4: Εάν το `base' δεν είναι ένα instance της @ref{326,,int} και το `base' αντικείμενο έχει μια μέθοδο @ref{43d,,base.__index__}, αυτή η μέθοδος καλείται για να αποκτήσει τον ακέραιο της βάσης.  Προηγούμενες εκδόσεις χρησιμοποιούσαν την @ref{43c,,base.__int__} αντί της @code{base.__index__}.



Άλλαξε στην έκδοση 3.6: Επιτρέπεται η ομαδοποίηση ψηφίων με κάτω παύλες όπως στα literals του κώδικα.



Άλλαξε στην έκδοση 3.7: Η πρώτη παράμετρος είναι πλέον μόνο θέσεως.



Άλλαξε στην έκδοση 3.8: Επιστρέφει πίσω στη @ref{43d,,__index__()} αν η @ref{43c,,__int__()} δεν έχει οριστεί.



Άλλαξε στην έκδοση 3.11: Οι είσοδοι συμβολοσειράς και οι αναπαραστάσεις συμβολοσειρών @ref{326,,int} μπορούν να περιοριστούν για να αποφευχθούν επιθέσεις άρνησης υπηρεσίας. Μια @ref{277,,ValueError} γίνεται raise όταν γίνεται υπέρβαση του ορίου κατά τη μετατροπή μιας συμβολοσειράς σε μια @code{int} ή κατά τη μετατροπή ενός @code{int} σε μια συμβολοσειρά θα υπερβεί το όριο. Δείτε την τεκμηρίωση @ref{9ec,,integer string conversion length limitation}.



Άλλαξε στην έκδοση 3.14: Η @ref{326,,int()} δεν αναθέτει πλέον στη μέθοδο @ref{43b,,__trunc__()}.

@end deffn

@geindex built-in function; isinstance()
@anchor{library/functions isinstance}@anchor{2ef}
@deffn {Συνάρτηση} isinstance (object, classinfo, /)

Επιστρέφει @code{True} εάν το όρισμα `object' είναι ένα instance του ορίσματος `classinfo' , ή μιας (άμεσης, έμμεσης ή @ref{155f,,virtual}) υποκλάσης αυτού.  Εάν το `object' δεν είναι ένα αντικείμενο του δεδομένου τύπου, η συνάρτηση θα επιστρέφει πάντα @code{False}. Εάν το `classinfo' είναι μια πλειάδα τύπου αντικειμένων (ή αναδρομικά, άλλες τέτοιες πλειάδες) ή μια @ref{ba2,,Τύπος Ένωσης} πολλαπλών τύπων, επιστρέφει @code{True} εάν το `object' είναι ένα instance οποιουδήποτε από τους τύπους. Εάν το `classinfo' δεν είναι ένα τύπος ή μια πλειάδα τύπων και τέτοιες πλειάδες, γίνεται raise μια εξαίρεση @ref{291,,TypeError}. Η @code{TypeError} δεν μπορεί να γίνει raise για μη έγκυρο τύπο, εάν ένας προηγούμενος έλεγχος είναι επιτυχής.


Άλλαξε στην έκδοση 3.10: Το `classinfo' μπορεί να είναι ένα @ref{ba2,,Τύπος Ένωσης}.

@end deffn

@geindex built-in function; issubclass()
@anchor{library/functions issubclass}@anchor{2f0}
@deffn {Συνάρτηση} issubclass (cls, classinfo, /)

Return @code{True} if `cls' is a subclass (direct, indirect, or @ref{155f,,virtual}) of `classinfo'.  A
class is considered a subclass of itself. `classinfo' may be a tuple of class
objects (or recursively, other such tuples)
or a @ref{ba2,,Τύπος Ένωσης}, in which case return @code{True} if `cls' is a
subclass of any entry in `classinfo'.  In any other case, a @ref{291,,TypeError}
exception is raised.


Άλλαξε στην έκδοση 3.10: Το `classinfo' μπορεί να είναι ένα @ref{ba2,,Τύπος Ένωσης}.

@end deffn

@geindex built-in function; iter()
@anchor{library/functions iter}@anchor{bb4}
@deffn {Συνάρτηση} iter (iterable, /)

@deffnx {Συνάρτηση} iter (callable, sentinel, /)

Επιστρέφετε ένα αντικείμενο @ref{6ce,,iterator}.  Το πρώτο όρισμα ερμηνεύεται πολύ διαφορετικά ανάλογα με την παρουσία του δεύτερου ορίσματος. Χωρίς δεύτερο όρισμα, το μόνο όρισμα πρέπει να είναι ένα αντικείμενο συλλογής που υποστηρίζει το πρωτόκολλο @ref{15ce,,iterable} (τη μέθοδο @ref{102d,,__iter__()}), ή πρέπει να υποστηρίζει το πρωτόκολλο ακολουθίας (τη μέθοδο @ref{787,,__getitem__()} με ακέραια ορίσματα που ξεκινούν από το @code{0}).  Εάν δεν υποστηρίζει κανένα από αυτά τα πρωτόκολλα, γίνεται raise μια @ref{291,,TypeError}. Εάν το δεύτερο όρισμα, `sentinel', δίνεται, τότε το πρώτο όρισμα πρέπει να είναι ένα callable αντικείμενο.  Ο iterator που δημιουργείται σε αυτή την περίπτωση θα καλεί το `callable' χωρίς ορίσματα για κάθε κλήση της μεθόδου @ref{1672,,__next__()} του; εάν η τιμή που επιστρέφεται είναι ίση με το `sentinel', θα γίνει raise μια @ref{fba,,StopIteration}, διαφορετικά η τιμή θα επιστραφεί.

Δείτε επίσης @ref{27d0,,Τύποι Iterator}.

Μια χρήσιμη εφαρμογή της δεύτερης μορφής του @ref{bb4,,iter()} είναι η κατασκευή ενός block-reader. Για παράδειγμα, η ανάγνωση μπλοκ σταθερού πλάτους από ένα δυαδικό αρχείο βάσης δεδομένων μέχρι να φτάσει στο τέλος του αρχείου:

@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{a1f}
@deffn {Συνάρτηση} len (object, /)

Επιστρέφει το μήκος (τον αριθμό των ειδών-περιεχομένων) ενός αντικειμένου.  Το όρισμα μπορεί να είναι μια ακολουθία (όπως μια συμβολοσειρά, bytes, πλειάδα, λίστα, ή εύρος) ή μια συλλογή (όπως ένα λεξικό, ένα σετ, ή ένα παγωμένο σετ).

Το @code{len} κάνει raise μια @ref{c57,,OverflowError} σε μήκη τα οποία είναι μεγαλύτερα από @ref{156e,,sys.maxsize}, όπως @ref{d0f,,range(2 ** 100)}.
@end deffn

@anchor{library/functions func-list}@anchor{27b3}
@deffn {Κλάση} list (iterable=(), /)

Αντί να είναι συνάρτηση, το @ref{4d9,,list} είναι στην πραγματικότητα ένας μεταβλητός τύπος ακολουθίας, όπως τεκμηριώνεται στα @ref{2210,,Λίστες} και @ref{221d,,Τύποι Ακολουθίας (Sequence) — list@comma{} tuple@comma{} range}.
@end deffn

@geindex built-in function; locals()
@anchor{library/functions locals}@anchor{28b}
@deffn {Συνάρτηση} locals ()

Επιστρέφει ένα αντικείμενο αντιστοίχισης που αναπαριστά τον τρέχοντα τοπικό πίνακα συμβόλων, με τα ονόματα μεταβλητών ως κλειδιά και τις αντίστοιχες τιμές στις οποίες είναι δεσμευμένες ως τιμές.

Στο επίπεδο module, καθώς και όταν χρησιμοποιείται η @ref{185,,exec()} ή η @ref{184,,eval()} με έναν μόνο χώρο ονομάτων, αυτή η συνάρτηση επιστρέφει τον ίδιο χώρο ονομάτων με τη @ref{1e01,,globals()}.

Στο πεδίο ορισμού κλάσης, επιστρέφει τον χώρο ονομάτων που θα περαστεί στον κατασκευαστή της μετακλάσης.

Όταν χρησιμοποιείται η @code{exec()} ή η @code{eval()} με ξεχωριστά local και global ορίσματα, επιστρέφει στον τοπικό χώρο ονομάτων που περάστηκε στην κλήση της συνάρτησης.

Σε όλες τις παραπάνω περιπτώσεις, κάθε κλήση της @code{locals()} σε ένα συγκεκριμένο πλαίσιο εκτέλεσης θα επιστρέφει το `ίδιο' αντικείμενο αντιστοίχισης. Οι αλλαγές που γίνονται μέσω του αντικειμένου αντιστοίχισης που επιστρέφεται από την @code{locals()} θα είναι ορατές ως τοπικές μεταβλητές που ανατίθενται, επανακαθορίζονται ή διαγράφονται, και η ανάθεση, επανακαθορισμός ή διαγραφή τοπικών μεταβλητών θα επηρεάζει άμεσα τα περιεχόμενα του επιστρεφόμενου αντικειμένου αντιστοίχισης.

Σε ένα @ref{6ad,,optimized scope} (όπως οι συναρτήσεις, οι γεννήτριες και οι συναρτήσεις συνεργασίας), κάθε κλήση της @code{locals()} επιστρέφει ένα νέο λεξικό που περιέχει τις τρέχουσες δεσμεύσεις των τοπικών μεταβλητών της συνάρτησης καθώς και οποιεσδήποτε αναφορές σε μη τοπικά κελιά. Σε αυτή την περίπτωση, οι αλλαγές στις δεσμεύσεις ονομάτων που γίνονται μέσω του επιστρεφόμενου λεξικού `δεν' εγγράφονται πίσω στις αντίστοιχες τοπικές μεταβλητές ή μη τοπικές αναφορές, και η ανάθεση, επανακαθορισμός ή διαγραφή τοπικών ή μη τοπικών μεταβλητών `δεν' επηρεάζει το περιεχόμενο των λεξικών που είχαν επιστραφεί προηγουμένως.

Καλώντας την @code{locals()} ως μέρος μιας σύμπτυξης (comprehension) που βρίσκεται σε μια συνάρτηση, γεννήτρια ή coroutine είναι ισοδύναμη με την κλήση της στο περιβάλλον που περικλείει την την σύμπτυξη, με τη διαφορά ότι οι αρχικοποιημένες μεταβλητές επανάληψης της σύμπτυξης θα περιλαμβάνονται στο αποτέλεσμα. Σε άλλα πεδία ορατότητας, η συμπεριφορά είναι σαν η σύμπτυξη να εκτελείται ως μια εμφωλευμένη συνάρτηση.

Καλώντας την @code{locals()} ως μέρος μιας έκφρασης γεννήτριας είναι ισοδύναμη με την κλήση της μέσα σε μια εμφωλευμένη συνάρτηση γεννήτριας.


Άλλαξε στην έκδοση 3.12: Η συμπεριφορά της @code{locals()} μέσα σε μια έκφραση σύμπτυξης έχει ενημερωθεί όπως περιγράφεται στην 
@geindex Python Enhancement Proposals; PEP 709
PEP 709@footnote{https://peps.python.org/pep-0709/}.



Άλλαξε στην έκδοση 3.13: Στο πλαίσιο της 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}, τα σημασιολογικά χαρακτηριστικά της τροποποίησης των αντικειμένων αντιστοιχίσεων που επιστρέφονται από αυτήν τη συνάρτηση έχουν πλέον οριστεί. Η συμπεριφορά σε @ref{6ad,,optimized scopes} είναι πλέον όπως περιγράφεται παραπάνω. Πέραν του ότι πλέον είναι ορισμένη, η συμπεριφορά σε άλλα πεδία παραμένει αμετάβλητη σε σχέση με προηγούμενες εκδόσεις.

@end deffn

@geindex built-in function; map()
@anchor{library/functions map}@anchor{43e}
@deffn {Συνάρτηση} map (function, iterable, /, *iterables, strict=False)

Επιστρέφει έναν iterator που εφαρμόζει `function' σε κάθε στοιχείο του `iterable', δίνοντας τα αποτελέσματα.  Εάν περάσουν επιπλέον ορίσματα `iterables', η `function' πρέπει να λάβει τόσα ορίσματα και να εφαρμόζεται στα στοιχεία από όλα τα iterables παράλληλα.  Με πολλαπλούς iterables, ο iterator σταματά όταν εξαντληθεί ο συντομότερος iterable. Εάν το `strict' είναι @code{True} και μία από τα iterables εξαντληθεί πριν από τις άλλες, γίνεται raise μια @ref{277,,ValueError}. Για περιπτώσεις όπου οι είσοδοι συνάρτησης είναι ήδη διατεταγμένες σε πλειάδες ορισμάτων, βλέπε @ref{1490,,itertools.starmap()}.


Άλλαξε στην έκδοση 3.14: Προστέθηκε η παράμετρος `strict'.

@end deffn

@geindex built-in function; max()
@anchor{library/functions max}@anchor{12ba}
@deffn {Συνάρτηση} max (iterable, /, *, key=None)

@deffnx {Συνάρτηση} max (iterable, /, *, default, key=None)

@deffnx {Συνάρτηση} max (arg1, arg2, /, *args, key=None)

Επιστρέφει το μεγαλύτερο στοιχείο σε ένα iterable ή το μεγαλύτερο από δύο ή περισσότερα ορίσματα.

Εάν παρέχεται ένα όρισμα θέσης, θα πρέπει να είναι ένα @ref{15ce,,iterable}. Επιστρέφεται το μεγαλύτερο στοιχείο στο iterable.  Εάν παρέχονται δύο ή περισσότερα ορίσματα θέσης, επιστρέφεται το μεγαλύτερο από τα ορίσματα θέσης.

Υπάρχουν δύο προαιρετικά ορίσματα τύπου λέξη-κλειδί. Το όρισμα `key' καθορίζει μια συνάρτηση ταξινόμησης ενός ορίσματος όπως αυτή χρησιμοποιείται για το @ref{f8d,,list.sort()}. Το όρισμα `default' καθορίζει ένα αντικείμενο που θα επιστρέψει εάν το iterable που παρέχεται είναι κενό. Εάν το iterable είναι κενό και το `default' δεν παρέχεται, γίνεται raise μια @ref{277,,ValueError}.

Εάν πολλά στοιχεία είναι μέγιστα, η συνάρτηση επιστρέφει το πρώτο που συναντήθηκε.  Αυτό είναι σύμφωνο με άλλα εργαλεία διατήρησης σταθερότητας ταξινόμησης όπως @code{sorted(iterable, key=keyfunc, reverse=True)[0]} και @code{heapq.nlargest(1, iterable, key=keyfunc)}.


Άλλαξε στην έκδοση 3.4: Προστέθηκε η παράμετρος μόνο λέξης-κλειδί `default'.



Άλλαξε στην έκδοση 3.8: Το `key' μπορεί να είναι @code{None}.

@end deffn

@anchor{library/functions func-memoryview}@anchor{27b4}
@deffn {Κλάση} memoryview (object)

Επιστρέφει ένα αντικείμενο «memory view» που δημιουργήθηκε από το συγκεκριμένο όρισμα.  Βλέπε @ref{27d1,,Όψεις Μνήμης} για περισσότερες λεπτομέρειες.
@end deffn

@geindex built-in function; min()
@anchor{library/functions min}@anchor{12b9}
@deffn {Συνάρτηση} min (iterable, /, *, key=None)

@deffnx {Συνάρτηση} min (iterable, /, *, default, key=None)

@deffnx {Συνάρτηση} min (arg1, arg2, /, *args, key=None)

Επιστρέφει το μικρότερο στοιχείο σε έναν iterable ή το μικρότερο από δύο ή περισσότερα ορίσματα.

Εάν παρέχεται ένα όρισμα θέσης, θα πρέπει να είναι ένα @ref{15ce,,iterable}. Επιστρέφει το μικρότερο στοιχείο στον iterable.  Εάν παρέχονται δύο ή περισσότερα ορίσματα θέσης, επιστρέφεται το μικρότερο από τα ορίσματα θέσης.

Υπάρχουν δύο προαιρετικά ορίσματα τύπου λέξη-κλειδί. Το όρισμα `key' καθορίζει μια συνάρτηση ταξινόμησης ενός ορίσματος όπως αυτή χρησιμοποιείται για το @ref{f8d,,list.sort()}. Το όρισμα `default' καθορίζει ένα αντικείμενο που θα επιστρέψει εάν το iterable που παρέχεται είναι κενό. Εάν το iterable είναι κενό και το `default' δεν παρέχεται, γίνεται raise μια @ref{277,,ValueError}.

Εάν πολλά στοιχεία είναι ελάχιστα, η συνάρτηση επιστρέφει το πρώτο που συναντήθηκε.  Αυτό είναι σύμφωνο με άλλα εργαλεία διατήρησης σταθερότητας ταξινόμησης, όπως @code{sorted(iterable, key=keyfunc)[0]} και @code{heapq.nsmallest(1, iterable, key=keyfunc)}.


Άλλαξε στην έκδοση 3.4: Προστέθηκε η παράμετρος μόνο λέξης-κλειδί `default'.



Άλλαξε στην έκδοση 3.8: Το `key' μπορεί να είναι @code{None}.

@end deffn

@geindex built-in function; next()
@anchor{library/functions next}@anchor{bb5}
@deffn {Συνάρτηση} next (iterator, /)

@deffnx {Συνάρτηση} next (iterator, default, /)

Ανάκτηση του επόμενου στοιχείο από το @ref{6ce,,iterator} καλώντας τη μέθοδο @ref{1672,,__next__()}.  Εάν δοθεί `default', επιστρέφεται εάν ο iterator έχει εξαντληθεί, διαφορετικά γίνεται raise μια @ref{fba,,StopIteration}.
@end deffn

@geindex object (ενσωματωμένη κλάση)
@anchor{library/functions object}@anchor{e4d}
@deffn {Κλάση} object

Αυτή είναι η τελική βασική κλάση όλων των άλλων κλάσεων. Έχει μεθόδους που είναι κοινές σε όλες τις περιπτώσεις κλάσεων Python. Όταν καλείται ο κατασκευαστής, επιστρέφει ένα νέο αντικείμενο χωρίς χαρακτηριστικά. Ο κατασκευαστής δεν δέχεται ορίσματα.

@cartouche
@quotation Σημείωση 
Τα στιγμιότυπα @ref{e4d,,object} `δεν' έχουν χαρακτηριστικά @ref{1bf,,__dict__}, επομένως δεν μπορείτε να εκχωρήσετε αυθαίρετα χαρακτηριστικά σε ένα στιγμιότυπο του @code{object}.
@end quotation
@end cartouche
@end deffn

@geindex built-in function; oct()
@anchor{library/functions oct}@anchor{1673}
@deffn {Συνάρτηση} oct (integer, /)

Μετατρέπει έναν ακέραιο αριθμό σε μια οκταδική συμβολοσειρά με πρόθεμα «0o». Το αποτέλεσμα είναι μια έγκυρη έκφραση Python. Εάν το `integer'  δεν είναι ένα αντικείμενο Python @ref{326,,int}, πρέπει να ορίσει μια μέθοδο @ref{43d,,__index__()} που επιστρέφει έναν ακέραιο αριθμό. Για παράδειγμα:

@example
>>> oct(8)
'0o10'
>>> oct(-56)
'-0o70'
@end example

Εάν θέλετε να μετατρέψετε έναν ακέραιο αριθμό σε οκταδική συμβολοσειρά είτε με το πρόθεμα «0o» είτε όχι, μπορείτε να χρησιμοποιήσετε έναν από τους παρακάτω τρόπους.

@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

Δείτε επίσης τη @ref{439,,format()} για περισσότερες πληροφορίες.
@end deffn

@geindex αντικείμενο αρχείου;open() ενσωματωμένη συνάρτηση

@geindex built-in function; open()
@anchor{library/functions open}@anchor{32b}
@deffn {Συνάρτηση} open (file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

Ανοίγει το `file' και επιστρέφει ένα αντίστοιχο @ref{156c,,file object}. Εάν το αρχείο δεν μπορεί να ανοίξει, γίνεται raise μια @ref{53c,,OSError}. Δείτε το @ref{2255,,Ανάγνωση και Εγγραφή Αρχείων} για περισσότερα παραδείγματα χρήσης αυτής της συνάρτησης.

Το `αρχείο' είναι ένα @ref{79f,,path-like object} που δίνει το όνομα διαδρομής (απόλυτο ή σε σχέση με τον τρέχοντα κατάλογο εργασίας) του αρχείου που θα ανοίξει ή ένας ακέραιος περιγραφέας αρχείου του αρχείου που πρόκειται να αναδιπλωθεί.  (Εάν δίνεται ένας περιγραφέας αρχείου, κλείνει όταν το επιστρεφόμενο αντικείμενο I/O είναι κλειστό εκτός εάν `closefd' έχει οριστεί ως @code{False}.)

Το `mode' είναι μια προαιρετική συμβολοσειρά που καθορίζει τη λειτουργία στην οποία ανοίγει το αρχείο.  Από προεπιλογή είναι @code{'r'} που σημαίνει ανοιχτό για ανάγνωση σε λειτουργία κειμένου. Άλλες κοινές τιμές είναι @code{'w'} για εγγραφή (περικοπή του αρχείου εάν υπάρχει ήδη), @code{'x'} για αποκλειστική δημιουργία και @code{'a'} για προσθήκη (κάτι που σε `μερικά' συστήματα Unix, σημαίνει ότι `όλες' οι εγγραφές προσαρτώνται στο τέλος του αρχείου ανεξάρτητα από την τρέχουσα θέση αναζήτησης).  Στη λειτουργία κειμένου, εάν δεν έχει καθοριστεί το `encoding', η κωδικοποίηση που χρησιμοποιείται εξαρτάται από την πλατφόρμα: @ref{a45,,locale.getencoding()} καλείται για να ληφθεί η τρέχουσα κωδικοποίηση τοπικών ρυθμίσεων. (Για την ανάγνωση και την εγγραφή ακατέργαστων bytes χρησιμοποιείται δυαδική λειτουργία και αφήνουν το `encoding' απροσδιόριστο.)  Οι διαθέσιμες λειτουργίες είναι:

@geindex αρχείο;λειτουργίες
@anchor{library/functions filemodes}@anchor{27d2}

@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Χαρακτήρας

@tab

Έννοια

@item

@code{'r'}

@tab

άνοιγμα για ανάγνωση (default)

@item

@code{'w'}

@tab

άνοιγμα για εγγραφή, περικόπτοντας πρώτα το αρχείο

@item

@code{'x'}

@tab

άνοιγμα για αποκλειστική δημιουργία, αποτυγχάνοντας εάν το αρχείο υπάρχει ήδη

@item

@code{'a'}

@tab

άνοιγμα για εγγραφή, προσαρτάται στο τέλος του αρχείου εάν υπάρχει

@item

@code{'b'}

@tab

δυαδική (binary) λειτουργία

@item

@code{'t'}

@tab

λειτουργία κειμένου (default)

@item

@code{'+'}

@tab

άνοιγμα για ενημέρωση (ανάγνωση και εγγραφή)

@end multitable


Η προεπιλεγμένη λειτουργία είναι @code{'r'} (ανοίγει για ανάγνωση κειμένου, συνώνυμο του @code{'rt'}). Οι λειτουργίες @code{'w+'} και @code{'w+b'} ανοίγει και περικόβει το αρχείο.  Οι λειτουργίες @code{'r+'} and @code{'r+b'} ανοίγουν το αρχείο χωρίς περικοπή.

Όπως αναφέρεται στο @ref{27d3,,Overview}, η Python κάνει διάκριση μεταξύ δυαδικού και κειμένου I/O.  Τα αρχεία που ανοίγουν σε δυαδική λειτουργία (συμπεριλαμβανομένου του @code{'b'} στο όρισμα `mode') επιστρέφουν τα περιεχόμενα ως @ref{1c7,,bytes} αντικείμενα χωρίς αποκωδικοποίηση.  Στη λειτουργία κειμένου (η προεπιλογή, ή όταν το @code{'t'} περιλαμβάνεται στο όρισμα `mode'), τα περιεχόμενα του αρχείου επιστρέφονται ως @ref{1df,,str}, τα bytes έχουν πρώτα αποκωδικοποιηθεί χρησιμοποιώντας μια εξαρτώμενη από πλατφόρμα κωδικοποίηση ή χρήση της καθορισμένης `κωδικοποίησης' εάν δίνεται.

@cartouche
@quotation Σημείωση 
Η Python δεν εξαρτάται από την έννοια των αρχείων κειμένου του υποκείμενου λειτουργικού συστήματος∙ όλη η επεξεργασία γίνεται από την ίδια την Python και επομένως είναι ανεξάρτητη από την πλατφόρμα.
@end quotation
@end cartouche

To `buffering' είναι ένας προαιρετικός ακέραιος που χρησιμοποιείται για το ορισμό της πολιτικής αποθήκευσης στην προσωρινή μνήμη.  Περνάει το 0 για να απενεργοποιήσετε την προσωρινή μνήμη (επιτρέπεται μόνο σε δυαδική λειτουργία), το 1 για να επιλέξετε προσωρινή αποθήκευση γραμμής (μπορεί να χρησιμοποιηθεί μόνο όταν γράφετε σε λειτουργία κειμένου) και έναν ακέραιο > 1 για να υποδείξει το μέγεθος σε byte μιας προσωρινής μνήμης τμημάτων σταθερού μεγέθους. Λάβετε υπόψη ότι ο καθορισμός ενός μεγέθους buffer με αυτόν τον τρόπο ισχύει για I/O με δυαδική προσωρινή μνήμη, αλλά το @code{TextIOWrapper} (δηλαδή, τα αρχεία που ανοίγουν με @code{mode='r+'}) θα έχουνε άλλη αποθήκευση. Για να απενεργοποιήσετε την προσωρινή αποθήκευση στο @code{TextIOWrapper}, εξετάστε το ενδεχόμενο να χρησιμοποιήσετε μια @code{write_through} σημαία για @ref{f06,,io.TextIOWrapper.reconfigure()}. Όταν δεν δίνεται όρισμα `buffering', η προεπιλεγμένη πολιτική προσωρινής αποθήκευσης λειτουργεί ως εξής:


@itemize *

@item 
Τα δυαδικά αρχεία αποθηκεύονται στην προσωρινή μνήμη σε κομμάτια σταθερού μεγέθους∙ το μέγεθος του buffer είναι @code{max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE)} όταν το μέγεθος μπλοκ της συσκευής είναι διαθέσιμο. Στα περισσότερα συστήματα, το buffer θα έχει συνήθως μήκος 128 kilobytes.

@item 
«Interactive» αρχεία κειμένου (αρχεία για τα οποία το @ref{2258,,isatty()} επιστρέφει @code{True}) χρησιμοποιούν αποθήκευση γραμμής.  Άλλα αρχεία κειμένου χρησιμοποιούν την πολιτική που περιγράφεται παραπάνω για δυαδικά αρχεία.
@end itemize

Το `encoding' είναι το όνομα της κωδικοποίησης που χρησιμοποιείται για την αποκωδικοποίηση ή την κωδικοποίηση του αρχείου. Θα πρέπει να χρησιμοποιείται μόνο σε λειτουργία κειμένου.  Η προεπιλεγμένη κωδικοποίηση εξαρτάται από την πλατφόρμα (οτιδήποτε επιστρέφει η @ref{a45,,locale.getencoding()}), αλλά οποιοδήποτε @ref{27d4,,text encoding} που υποστηρίζεται από την Python. Δείτε το module @ref{1c,,codecs} για τη λίστα των υποστηριζόμενων κωδικοποιήσεων.

`errors' is an optional string that specifies how encoding and decoding
errors are to be handled—this cannot be used in binary mode.
A variety of standard error handlers are available,
though any error handling name that has been registered with
@ref{183d,,codecs.register_error()} is also valid.  The standard names
can be found in @ref{1d6c,,Error Handlers}.

@geindex καθολικές νέες γραμμές;open() ενσωματωμένη συνάρτηση
@anchor{library/functions open-newline-parameter}@anchor{b26}
Το `newline' καθορίζει τον τρόπο ανάλυσης χαρακτήρων νέας γραμμής από τη ροή. Μπορεί να είναι και @code{None}, @code{'@w{'}}, @code{'\n'}, @code{'\r'}, και @code{'\r\n'}.  Λειτουργεί ως εξής:


@itemize *

@item 
Κατά την ανάγνωση εισόδου από την ροή, εάν το `newline' είναι @code{None}, η καθολική λειτουργία νέων γραμμών είναι ενεργοποιημένη.  Οι γραμμές στην είσοδο μπορούν να τελειώνουν σε @code{'\n'}, @code{'\r'}, ή @code{'\r\n'}, και αυτά μεταφράζονται σε @code{'\n'} πριν επιστραφούν στον καλούντα.  Εάν είναι @code{'@w{'}}, η καθολική λειτουργία νέων γραμμών είναι ενεργοποιημένη, αλλά οι καταλήξεις γραμμών επιστρέφονται στον καλούντα αμετάφραστα.  Εάν έχει κάποια από τις άλλες νόμιμες τιμές, οι γραμμές εισόδου τερματίζονται μόνο από τη δεδομένη συμβολοσειρά και η κατάληξη γραμμής επιστρέφεται στον καλούντα αμετάφραστη.

@item 
Κατά την εγγραφή εξόδου στη ροή, εάν το `newline' είναι @code{None}, τυχόν χαρακτήρες @code{'\n'} μεταφράζονται στο διαχωριστικό προεπιλεγμένων γραμμών του συστήματος, @ref{27d5,,os.linesep}.  Εάν το `newline' είναι @code{'@w{'}} ή @code{'\n'}, δεν πραγματοποιείται μετάφραση εάν το `newline' είναι οποιαδήποτε από τις άλλες νόμιμες τιμές, γράφονται οποιοιδήποτε χαρακτήρες @code{'\n'} μεταφράζονται στη δεδομένη συμβολοσειρά.
@end itemize

Εάν το `closefd' είναι @code{False} και έχει δοθεί ένας περιγραφέας αρχείου αντί για ένα όνομα αρχείου, ο υποκειμενικός περιγραφέας αρχείου θα παραμείνει ανοιχτός όταν το αρχείο κλείσει.  Εάν δοθεί ένα όνομα αρχείου το `closefd' πρέπει να είναι @code{True} (η προεπιλογή)∙ διαφορετικά, θα προκύψει ένα σφάλμα.

Ένα προσαρμοσμένο πρόγραμμα ανοίγματος μπορεί να χρησιμοποιηθεί μεταβιβάζοντας ένα callable ως `opener'. Ο υποκείμενος περιγραφέας αρχείου για το αντικείμενο αρχείου λαμβάνεται στη συνέχεια καλώντας το `opener' με (`file', `flags').  Το `opener' πρέπει να επιστρέψει ένα περιγραφέα ανοιχτού αρχείου (περνώντας @ref{114b,,os.open} ως `opener' έχει ως αποτέλεσμα λειτουργικότητας παρόμοια με το να περάσουμε το @code{None}).

Το νέο δημιουργημένο αρχείο είναι @ref{12aa,,non-inheritable}.

Το παρακάτω παράδειγμα χρησιμοποιεί την παράμετρο @ref{1496,,dir_fd} της συνάρτησης @ref{114b,,os.open()} για να ανοίξει ένα αρχείο σε σχέση με έναν δεδομένο κατάλογο:

@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

Ο τύπος του @ref{156c,,file object} που επιστρέφεται από τη συνάρτηση @ref{32b,,open()} εξαρτάται από τη λειτουργία.  Όταν το @code{open()} χρησιμοποιείται για το άνοιγμα ενός αρχείου σε λειτουργία κειμένου (@code{'w'}, @code{'r'}, @code{'wt'}, @code{'rt'}, κ.λπ.), επιστρέφει μια υποκλάση του @ref{a84,,io.TextIOBase} (specifically @ref{b9c,,io.TextIOWrapper}).  Όταν χρησιμοποιείται για το άνοιγμα ενός αρχείου σε δυαδική λειτουργία με προσωρινή αποθήκευση, η κλάση που επιστρέφεται είναι μια υποκλάση του @ref{a83,,io.BufferedIOBase}.  Η ακριβής κλάση ποικίλλει: σε λειτουργία δυαδικής ανάγνωσης, επιστρέφει ένα @ref{15b5,,io.BufferedReader} ∙ σε δυαδικές καταστάσεις εγγραφής και δυαδικής προσθήκης, επιστρέφει ένα @ref{1754,,io.BufferedWriter}, και στη λειτουργία ανάγνωσης/εγγραφής, επιστρέφει ένα @ref{1755,,io.BufferedRandom}.  Όταν η προσωρινή αποθήκευση είναι απενεργοποιημένη, επιστρέφεται, η ακατέργαστη ροή , μια υποκλάση @ref{147c,,io.RawIOBase}, @ref{16b4,,io.FileIO}.

@geindex γραμμική προσωρινή μνήμη I/O
@geindex unbuffered I/O
@geindex μέγεθος bugger@comma{} I/O
@geindex Έλεγχος I/O;buffering
@geindex δυαδική (binary) λειτουργία
@geindex λειτουργία κειμένου
@geindex module;sys

Δείτε επίσης τις ενότητες διαχείρισης αρχείων, όπως @ref{5e,,fileinput}, @ref{82,,io} (όπου ορίζεται η @ref{32b,,open()}), @ref{a5,,os}, @ref{a6,,os.path}, @ref{e9,,tempfile}, και @ref{cd,,shutil}.

Κάνει raise ένα @ref{1e65,,auditing event} @code{open} με ορίσματα @code{path}, @code{mode}, @code{flags}.

Τα ορίσματα @code{mode} και @code{flags} μπορεί να έχουν τροποποιηθεί ή να έχουν συναχθεί από την αρχική κλήση.


Άλλαξε στην έκδοση 3.3: 


@itemize *

@item 
Προστέθηκε η παράμετρος `opener'.

@item 
Προστέθηκε η λειτουργία @code{'x'}.

@item 
Το @ref{13fb,,IOError} γινόταν raise παλιά, τώρα είναι ψευδώνυμο του @ref{53c,,OSError}.

@item 
Το @ref{13c9,,FileExistsError} γίνεται raise τώρα εάν το αρχείο που ανοίγει σε λειτουργία αποκλειστικής δημιουργίας (@code{'x'}) υπάρχει ήδη.
@end itemize



Άλλαξε στην έκδοση 3.4: 


@itemize *

@item 
Το αρχείο είναι πλέον μη κληρονομικό.
@end itemize



Άλλαξε στην έκδοση 3.5: 


@itemize *

@item 
Εάν η κλήση συστήματος διακοπεί και ο χειριστής σήματος δεν κάνει raise μια εξαίρεση, η συνάρτηση επαναλαμβάνει τώρα την κλήση συστήματος αντί να κάνει raise μια εξαίρεση @ref{1141,,InterruptedError} (δείτε το 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} για το σκεπτικό).

@item 
Προστέθηκε το πρόγραμμα χειρισμού σφαλμάτων @code{'namereplace'}.
@end itemize



Άλλαξε στην έκδοση 3.6: 


@itemize *

@item 
Προστέθηκε υποστήριξη για την αποδοχή αντικειμένων που υλοποιούν @ref{100f,,os.PathLike}.

@item 
Στα Windows, το άνοιγμα μιας προσωρινής μνήμης κονσόλας μπορεί να επιστρέψει μια υποκλάση του @ref{147c,,io.RawIOBase} εκτός από το @ref{16b4,,io.FileIO}.
@end itemize



Άλλαξε στην έκδοση 3.11: Η λειτουργία @code{'U'} έχει αφαιρεθεί.

@end deffn

@geindex built-in function; ord()
@anchor{library/functions ord}@anchor{252c}
@deffn {Συνάρτηση} ord (character, /)

Επιστρέφει την αριθμητική τιμή (ordinal) ενός χαρακτήρα.

Εάν το όρισμα είναι μια συμβολοσειρά ενός χαρακτήρα, επιστρέφει το σημείο κώδικα Unicode αυτού του χαρακτήρα.  Για παράδειγμα, το @code{ord('a')} επιστρέφει τον ακέραιο @code{97} και το @code{ord('€')} (σημείο ευρώ) επιστρέφει το @code{8364}.  Αυτό είναι το αντίστροφο του @ref{1bf8,,chr()}.

Εάν το όρισμα είναι ένα αντικείμενο @ref{1c7,,bytes} ή @ref{1c6,,bytearray} μήκους 1, επιστρέφει την τιμή του μεμονωμένου byte. Για παράδειγμα, το @code{ord(b'a')} επιστρέφει τον ακέραιο @code{97}.
@end deffn

@geindex built-in function; pow()
@anchor{library/functions pow}@anchor{441}
@deffn {Συνάρτηση} pow (base, exp, mod=None)

Επιστρέφει `base' στην δύναμη `exp*∙ εάν υπάρχει το *mod', επιστρέφει `base' στην δύναμη `exp', modulo `mod' (υπολογίζεται πιο αποτελεσματικά από το @code{pow(base, exp) % mod}). Η φόρμα δύο ορισμάτων @code{pow(base, exp)} ισοδυναμεί με τη χρήση του τελεστή δύναμης: @code{base**exp}.

Όταν τα ορίσματα είναι ενσωματωμένοι αριθμητικοί τύποι με μεικτούς τύπους ισχύουν οι κανόνες εξαναγκασμού για δυαδικούς τελεστές αριθμητικής.  Για του τελεστές @ref{326,,int}, το αποτέλεσμα έχει τον ίδιο τύπο με τους τελεστές (μετά τον εξαναγκασμό), εκτός εάν το δεύτερο όρισμα είναι αρνητικό∙ σε αυτή την περίπτωση, όλα τα ορίσματα μετατρέπονται σε float και επιστρέφεται ένα αποτέλεσμα τύπους float.  Για παράδειγμα, @code{pow(10, 2)} επιστρέφει @code{100}, αλλά το @code{pow(10, -2)} επιστρέφει @code{0.01}.  Για μια αρνητική βάση τύπου @code{int} ή @ref{327,,float} και έναν μη αναπόσπαστο εκθέτη, παραδίδεται ένα μιγαδικό αποτέλεσμα.  Για παράδειγμα, @code{pow(-9, 0.5)} επιστρέφει μια τιμή κοντά στο @code{3j}. Ενώ, για μια αρνητική βάση τύπου @code{int} ή @code{float} με αναπόσπαστο εκθέτη, παραδίδεται ένα αποτέλεσμα float. Για παράδειγμα, το @code{pow(-9, 2.0)} επιστρέφει το @code{81.0}.

Για τους τελεστές της @ref{326,,int} `base' και `exp', εάν υπάρχει `mod', το `mod' πρέπει επίσης να είναι ακεραίου τύπου και το `mod' πρέπει να είναι μη μηδενικό. Εάν υπάρχει `mod' και το `exp' είναι αρνητικό, το `base' πρέπει να είναι σχετικά πρώτο στο `mod'. Σε αυτήν την περίπτωση , επιστρέφεται το @code{pow(inv_base, -exp, mod)}, όπου το `inv_base' είναι αντίστροφο του `base' modulo `mod'.

Ακολουθεί ένα παράδειγμα υπολογισμού ενός αντίστροφου για το @code{38} modulo @code{97}:

@example
>>> pow(38, -1, mod=97)
23
>>> 23 * 38 % 97 == 1
True
@end example


Άλλαξε στην έκδοση 3.8: Για του τελεστές @ref{326,,int}, η μορφή τριών ορισμών του @code{pow} επιτρέπει τώρα το δεύτερο όρισμα να είναι αρνητικό, επιτρέποντας τον υπολογισμό των αρθρωτών αντίστροφων.



Άλλαξε στην έκδοση 3.8: Επιτρέπονται ορίσματα keyword.  Παλαιότερα, υποστηρίζονταν μόνο ορίσματα θέσης.

@end deffn

@geindex built-in function; print()
@anchor{library/functions print}@anchor{131f}
@deffn {Συνάρτηση} print (*objects, sep=' ', end='\n', file=None, flush=False)

Εκτυπώνει `objects' στην ροή κειμένου `file', χωρισμένα με `sep' και ακολουθούμενα από `end'. Τα `sep', `end', `file', και `flush', εάν υπάρχουν, πρέπει να δίνονται ως ορίσματα keyword.

Όλα τα μη keyword ορίσματα μετατρέπονται σε συμβολοσειρές όπως κάνει η @ref{1df,,str()} και γράφονται στη ροή, χωρισμένα με `sep' και ακολουθούνται από `end'.  Και τα δύο `sep' και `end' πρέπει να είναι συμβολοσειρές∙ μπορεί επίσης να είναι @code{None}, που σημαίνει ότι θα χρησιμοποιηθούν οι προεπιλεγμένες τιμές.  Εάν δεν δίνονται `αντικείμενα', η @ref{131f,,print()} θα γράψει απλά `end'.

Το όρισμα `file' πρέπει να είναι αντικείμενο με μια μέθοδο @code{write(string)} ∙ εάν δεν υπάρχει ή είναι @code{None}, θα χρησιμοποιηθεί το @ref{e9c,,sys.stdout}.  Επειδή τα τυπωμένα ορίσματα μετατρέπονται σε συμβολοσειρές κειμένου, η @ref{131f,,print()} δεν μπορεί να χρησιμοποιηθεί με αντικείμενα αρχείου δυαδικής λειτουργίας.  Για αυτά, χρησιμοποιούμε το @code{file.write(...)}.

Η προσωρινή αποθήκευση εξόδου καθορίζεται συνήθως από το `αρχείο'. Ωστόσο, εάν το `flush' είναι αληθές, η ροή ξεπλένεται αναγκαστικά.


Άλλαξε στην έκδοση 3.3: Προστέθηκε το όρισμα keyword `flush'.

@end deffn

@geindex property (ενσωματωμένη κλάση)
@anchor{library/functions property}@anchor{6bb}
@deffn {Κλάση} property (fget=None, fset=None, fdel=None, doc=None)

Επιστρέφει ένα χαρακτηριστικό ιδιότητας.

Το `fget' είναι μια συνάρτηση για τη λήψη μιας τιμής χαρακτηριστικού.  Το `fset' είναι μια συνάρτηση για τον ορισμό μιας τιμής χαρακτηριστικού. Το `fdel' είναι μια συνάρτηση για τη διαγραφή μιας τιμής χαρακτηριστικού.  Και το `doc' δημιουργεί μια συμβολοσειρά εγγράφων για το χαρακτηριστικό.

Μια τυπική χρήση είναι ο ορισμός ενός διαχειριζόμενου χαρακτηριστικού @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

Εάν το `c' είναι ένα instance του `C', το @code{c.x} θα καλέσει τον λήπτη, το @code{c.x = value} θα καλέσει τον ρυθμιστή, και το @code{del c.x} τον διαγραφέα.

Εάν δίνεται, το `doc' θα είναι το docstring του χαρακτηριστικού ιδιότητας. Διαφορετικά , η ιδιότητα θα αντιγράψει τη συμβολοσειρά του `fget' (εάν υπάρχει).  Αυτό καθιστά δυνατή τη δημιουργία ιδιοτήτων μόνο για ανάγνωση, εύκολα χρησιμοποιώντας τη @ref{6bb,,property()} ως @ref{b18,,decorator}:

@example
class Parrot:
    def __init__(self):
        self._voltage = 100000

    @@property
    def voltage(self):
        """Get the current voltage."""
        return self._voltage
@end example

Ο decorator @code{@@property} μετατρέπει την μέθοδο @code{voltage()} σε «getter» για ένα χαρακτηριστικό μόνο για ανάγνωση με το ίδιο όνομα, και ορίζει τη συμβολοσειρά εγγράφων για `voltage' σε «Get the current voltage.»

@geindex built-in function; property.getter()
@anchor{library/functions property getter}@anchor{1be2}
@deffn {Συνάρτηση} @@getter
@end deffn

@geindex built-in function; property.setter()
@anchor{library/functions property setter}@anchor{1be3}
@deffn {Συνάρτηση} @@setter
@end deffn

@geindex built-in function; property.deleter()
@anchor{library/functions property deleter}@anchor{1be4}
@deffn {Συνάρτηση} @@deleter

Ένα αντικείμενο ιδιότητας έχει μεθόδους @code{getter}, @code{setter}, και @code{deleter} που μπορούν να χρησιμοποιηθούν ως διακοσμητές που δημιουργούν ένα αντίγραφο της ιδιότητας με την αντίστοιχη συνάρτηση accessor που έχει οριστεί στον decorator.  Αυτό εξηγείται καλύτερα με ένα παράδειγμα:

@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

Αυτός ο κώδικας είναι ακριβώς ισοδύναμος με το πρώτο παράδειγμα.  Φροντίστε να δώσετε στις πρόσθετες συναρτήσεις το ίδιο όνομα με την αρχική ιδιότητα (@code{x} σε αυτήν την περίπτωση.)

Το επιστρεφόμενο αντικείμενο ιδιότητας έχει επίσης τα χαρακτηριστικά @code{fget}, @code{fset}, και @code{fdel} που αντιστοιχούν στα ορίσματα του κατασκευαστή.
@end deffn


Άλλαξε στην έκδοση 3.5: Τα `docstrings' των αντικειμένων ιδιότητας είναι πλέον εγγράψιμες.


@geindex __name__ (ιδιότητα της property)
@anchor{library/functions property __name__}@anchor{6ba}
@deffn {Ιδιότητα} __name__

Χαρακτηριστικό που περιέχει το όνομα της ιδιότητας. Το όνομα της ιδιότητας μπορεί να αλλάξει κατά την εκτέλεση.


Added in version 3.13.

@end deffn
@end deffn

@anchor{library/functions func-range}@anchor{27b5}
@deffn {Κλάση} range (stop, /)

@deffnx {Κλάση} range (start, stop, step=1, /)

Αντί να είναι συνάρτηση, το @ref{d0f,,range} είναι στην πραγματικότητα ένας αμετάβλητος τύπος ακολουθίας, όπως τεκμηριώνεται στα @ref{27d6,,Εύρη (Ranges)} και @ref{221d,,Τύποι Ακολουθίας (Sequence) — list@comma{} tuple@comma{} range}.
@end deffn

@geindex built-in function; repr()
@anchor{library/functions repr}@anchor{45b}
@deffn {Συνάρτηση} repr (object, /)

Επιστρέφει μια συμβολοσειρά που περιέχει μια εκτυπώσιμη αναπαράσταση ενός αντικειμένου.  Για πολλούς τύπους, αυτή η συνάρτηση κάνει μια προσπάθεια να επιστρέψει μια συμβολοσειρά που θα απέδιδε ένα αντικείμενο με την ίδια τιμή όταν μεταβιβαζόταν στο @ref{184,,eval()} ∙ διαφορετικά, η αναπαράσταση είναι μια συμβολοσειρά που περικλείεται σε αγκύλες που περιέχει το όνομα του τύπου του αντικειμένου μαζί με πρόσθετες πληροφορίες που συχνά περιλαμβάνουν το όνομα και τη διεύθυνση του αντικειμένου.  Μια κλάση μπορεί να ελέγξει τι επιστρέφει αυτή η συνάρτηση για τις οντότητες της ορίζοντας μια μέθοδο @ref{1bc,,__repr__()}. Εάν η @ref{18c1,,sys.displayhook()} δεν είναι προσβάσιμη, αυτή η συνάρτηση θα κάνει raise το @ref{30d,,RuntimeError}.

Αυτή η κλάση έχει μια προσαρμοσμένη αναπαράσταση που μπορεί να αξιολογηθεί:

@example
class Person:
   def __init__(self, name, age):
      self.name = name
      self.age = age

   def __repr__(self):
      return f"Person(@{self.name!r@}, @{self.age!r@})"
@end example
@end deffn

@geindex built-in function; reversed()
@anchor{library/functions reversed}@anchor{c3c}
@deffn {Συνάρτηση} reversed (object, /)

Επιστρέφει ένα αντίστροφο @ref{6ce,,iterator}. Το όρισμα πρέπει να είναι ένα αντικείμενο το οποίο έχει μια μέθοδο @ref{1049,,__reversed__()} ή υποστηρίζει το πρωτόκολλο ακολουθίας (τη μέθοδο @ref{1989,,__len__()} και τη μέθοδο @ref{787,,__getitem__()} με ακέραια ορίσματα που ξεκινούν από το 0).
@end deffn

@geindex built-in function; round()
@anchor{library/functions round}@anchor{167f}
@deffn {Συνάρτηση} round (number, ndigits=None)

Επιστρέφει τον `number' στρογγυλοποιημένο σε `ndigits' ακρίβεια μετά την υποδιαστολή.  Εάν το `ndigits' παραληφθεί ή είναι @code{None}, επιστρέφει τον πλησιέστερο ακέραιο αριθμό στην είσοδό του.

Για του ενσωματωμένους τύπους που υποστηρίζουν τη @ref{167f,,round()}, οι τιμές στρογγυλοποιούνται στο πλησιέστερο πολλαπλάσιο του 10 στην δύναμη μείον `ndigits*∙ εάν δύο πολλαπλάσια είναι εξίσου κοντά, η στρογγυλοποίηση γίνεται προς την άρτια επιλογή (έτσι, για παράδειγμα, τόσο το `@w{`}round(0.5)`@w{`} και `@w{`}round(-0.5)`@w{`} είναι `@w{`}0`@w{`}, και `@w{`}round(1.5)`@w{`} είναι `@w{`}2`@w{`}).  Οποιαδήποτε ακέραια τιμή είναι έγκυρη για *ndigits' (θετική, μηδενική, ή αρνητική).  Η επιστρεφόμενη τιμή είναι ακέραιος εάν το `ndigits' παραλειφθεί ή είναι @code{None}. Διαφορετικά, η τιμή επιστροφής έχει τον ίδιο τύπο με το `number'.

Για ένα γενικό αντικείμενο Python @code{number}, @code{round} εκχωρεί στο @code{number.__round__}.

@cartouche
@quotation Σημείωση 
Η συμπεριφορά του @ref{167f,,round()} για floats μπορεί να είναι εκπληκτική: για παράδειγμα, το @code{round(2.675, 2)} δίνει @code{2.67} αντί για το αναμενόμενο @code{2.68}. Αυτό δεν είναι bug: είναι αποτέλεσμα του γεγονότος ότι τα περισσότερα δεκαδικά κλάσματα δεν μπορούν να αναπαρασταθούν ακριβώς ως float.  Δείτε το @ref{22f0,,Αριθμητική Κινητής Υποδιαστολής; Ζητήματα και Περιορισμοί} για περισσότερες πληροφορίες.
@end quotation
@end cartouche
@end deffn

@anchor{library/functions func-set}@anchor{27b6}
@deffn {Κλάση} set (iterable=(), /)

Επιστρέφει ένα νέο αντικείμενο @ref{42b,,set}, προαιρετικά με στοιχεία που λαμβάνονται από το `iterable'.  Το @code{set} είναι μια ενσωματωμένη κλάση.  Δείτε @code{set} και @ref{2220,,Τύποι Συνόλου (Set) — set@comma{} frozenset} για τεκμηρίωση αυτής της κλάσης.

Για άλλα containers, δείτε τις ενσωματωμένες κλάσεις @ref{9d4,,frozenset}, @ref{4d9,,list}, @ref{1ce,,tuple}, και @ref{188,,dict}, καθώς και το module @ref{1e,,collections}.
@end deffn

@geindex built-in function; setattr()
@anchor{library/functions setattr}@anchor{27b7}
@deffn {Συνάρτηση} setattr (object, name, value, /)

Αυτό είναι το αντίστοιχο τους @ref{f8f,,getattr()}.  Τα ορίσματα είναι ένα αντικείμενο, μια συμβολοσειρά και μια αυθαίρετη τιμή.  Η συμβολοσειρά μπορεί να ονομάσει ένα υπάρχον χαρακτηριστικό ή ένα νέο χαρακτηριστικό. Η συνάρτηση εκχωρεί την τιμή στο χαρακτηριστικό, με την προϋπόθεση ότι το αντικείμενο το επιτρέπει.  Για παράδειγμα @code{setattr(x, 'foobar', 123)} ισοδυναμεί με το @code{x.foobar = 123}.

Το `name' δεν χρειάζεται να είναι αναγνωριστικό Python όπως ορίζεται στο @ref{2491,,Ονόματα (αναγνωριστικά και λέξεις-κλειδιά)} , εκτός εάν το αντικείμενο επιλέξει να το επιβάλει αυτό, για παράδειγμα σε ένα προσαρμοσμένο @ref{f90,,__getattribute__()} ή μέσω @ref{188d,,__slots__}. Ένα χαρακτηριστικό του οποίου το όνομα δεν είναι αναγνωριστικό δεν θα είναι προσβάσιμο χρησιμοποιώντας τη σημειογραφία, αλλά είναι προσβάσιμο μέσω του @ref{f8f,,getattr()} κ.λπ..

@cartouche
@quotation Σημείωση 
Δεδομένου ότι το @ref{2293,,private name mangling} συμβαίνει κατά τη στιγμή της μεταγλώττισης, πρέπει κανείς να παραμορφώσει με μη αυτόματο τρόπο το όνομα ενός ιδιωτικού χαρακτηριστικού (χαρακτηριστικά με δύο προπορευόμενες κάτω παύλες) για να το ορίσει με @ref{27b7,,setattr()}.
@end quotation
@end cartouche
@end deffn

@geindex sentinel (ενσωματωμένη κλάση)
@anchor{library/functions sentinel}@anchor{18b}
@deffn {Κλάση} sentinel (name, /)

Return a new unique sentinel object.  `name' must be a @ref{1df,,str}, and is
used as the returned object’s representation:

@example
>>> MISSING = sentinel("MISSING")
>>> MISSING
MISSING
@end example

Sentinel objects are truthy and compare equal only to themselves.  They are
intended to be compared with the @ref{324,,is} operator.

@code{sentinel} does not support subclassing.

Shallow and deep copies of a sentinel object return the object itself.

Sentinels are conventionally assigned to a variable with a matching name.
Sentinels defined in this way can be used in @ref{25c1,,type hints}:

@example
MISSING = sentinel("MISSING")

def next_value(default: int | MISSING = MISSING):
    ...
@end example

Sentinel objects support the @ref{26c4,,|} operator for use in type expressions.

@ref{ab,,Pickling} is supported for sentinel objects that are
placed in the global scope of a module under a name matching the sentinel’s
name, and for sentinels placed in class scopes with a name matching the
@ref{1f19,,qualified name} of the sentinel. Other sentinels, such as those
defined in a function scope, are not picklable. The identity of the sentinel is preserved
after pickling:

@example
import pickle

PICKLABLE = sentinel("PICKLABLE")

assert pickle.loads(pickle.dumps(PICKLABLE)) is PICKLABLE

class Cls:
    PICKLABLE = sentinel("Cls.PICKLABLE")

assert pickle.loads(pickle.dumps(Cls.PICKLABLE)) is Cls.PICKLABLE
@end example

Sentinel objects have the following attributes:

@geindex __name__ (ιδιότητα της sentinel)
@anchor{library/functions sentinel __name__}@anchor{27d7}
@deffn {Ιδιότητα} __name__

The sentinel’s name.
@end deffn

@geindex __module__ (ιδιότητα της sentinel)
@anchor{library/functions sentinel __module__}@anchor{27d8}
@deffn {Ιδιότητα} __module__

The name of the module where the sentinel was created.
@end deffn


Added in version 3.15.

@end deffn

@geindex slice (ενσωματωμένη κλάση)
@anchor{library/functions slice}@anchor{1d0}
@deffn {Κλάση} slice (stop, /)

@deffnx {Κλάση} slice (start, stop, step=None, /)

Επιστρέφετε ένα αντικείμενο @ref{26a5,,slice} που αντιπροσωπεύει το σύνολο των δεικτών που καθορίζονται από το @code{range(start, stop, step)}.  Τα ορίσματα `start' και `step' είναι από προεπιλογή @code{None}.

Slice objects are also generated when @ref{26a4,,slicing syntax}
is used.  For example: @code{a[start:stop:step]} or @code{a[start:stop, i]}.

See @ref{f09,,itertools.islice()} for an alternate version that returns an
@ref{6ce,,iterator}.

@geindex start (ιδιότητα της slice)
@geindex stop (ιδιότητα της slice)
@geindex step (ιδιότητα της slice)
@anchor{library/functions slice start}@anchor{259a}
@deffn {Ιδιότητα} start
@anchor{library/functions slice stop}@anchor{259b}
@deffnx {Ιδιότητα} stop
@anchor{library/functions slice step}@anchor{259c}
@deffnx {Ιδιότητα} step

These read-only attributes are set to 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


Άλλαξε στην έκδοση 3.12: Τα αντικείμενα slice είναι πλέον @ref{183,,hashable} (με την προϋπόθεση @ref{259a,,start}, @ref{259b,,stop}, και @ref{259c,,step} μπορούν να κατακερματιστούν).

@end deffn

@geindex built-in function; sorted()
@anchor{library/functions sorted}@anchor{f8c}
@deffn {Συνάρτηση} sorted (iterable, /, *, key=None, reverse=False)

Επιστρέφει μια νέα ταξινομημένη λίστα από τα στοιχεία στο `iterable'.

Έχει δύο προαιρετικά ορίσματα που πρέπει να καθοριστούν ως ορίσματα λέξεων-κλειδιών.

Το `key' καθορίζει μια συνάρτηση ενός ορίσματος που χρησιμοποιείται για την εξαγωγή ενός κλειδιού σύγκρισης από κάθε στοιχείο στο `iterable' (για παράδειγμα, @code{key=str.lower}).  Η προεπιλεγμένη τιμή είναι @code{None} (συγκρίνει τα στοιχεία απευθείας).

Το `reverse' είναι μια δυαδική τιμή.  Εάν οριστεί σε @code{True}, τότε τα στοιχεία της λίστας ταξινομούνται σαν να είχε αντιστραφεί κάθε σύγκριση.

Χρησιμοποιήστε το @ref{1583,,functools.cmp_to_key()} για να μετατρέψετε μια συνάρτηση `cmp' παλιού τύπου σε συνάρτηση `key'.

Η ενσωματωμένη συνάρτηση @ref{f8c,,sorted()} είναι εγγυημένη ότι είναι σταθερή. Μια ταξινόμηση είναι σταθερή εάν εγγυάται ότι δεν θα αλλάξει η σχετική σειρά των στοιχείων που συγκρίνονται ίσα — αυτό είναι χρήσιμο για ταξινόμηση σε πολλαπλά περάσματα (για παράδειγμα, ταξινόμηση ανά τμήμα, μετά ανά μισθολογικό βαθμό).

Ο αλγόριθμος ταξινόμησης χρησιμοποιεί μόνο συγκρίσεις @code{<} μεταξύ στοιχείων.  Ενώ ο ορισμός μιας μεθόδου @ref{1645,,__lt__()} αρκεί για την ταξινόμηση, το 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/} συνιστά και τις έξι @ref{26c7,,rich comparisons} που θα εφαρμοστούν.  Αυτό θα βοηθήσει στην αποφυγή σφαλμάτων κατά τη χρήση των ίδιων δεδομένων με άλλα εργαλεία διάταξης, όπως @ref{12ba,,max()} που βασίζονται σε διαφορετική υποκείμενη μέθοδο.  Η υλοποίηση και των έξι συγκρίσεων βοηθά επίσης στην αποφυγή σύγχυσης για συγκρίσεις μικτού τύπου που μπορούν να καλέσουν την ανακλώμενη μέθοδο @ref{16b0,,__gt__()}.

Για παραδείγματα ταξινόμησης και ένα σύντομο σεμινάριο ταξινόμησης, ανατρέξτε στο @ref{27d9,,Sorting Techniques}.
@end deffn

@geindex built-in function; staticmethod()
@anchor{library/functions staticmethod}@anchor{666}
@deffn {Συνάρτηση} @@staticmethod

Μετατροπή μιας μεθόδου σε στατική μέθοδο.

Μια στατική μέθοδος δεν λαμβάνει ένα σιωπηρό πρώτο όρισμα.  Για να δηλώσετε μια στατική μέθοδο, χρησιμοποιήστε αυτό το ιδίωμα:

@example
class C:
    @@staticmethod
    def f(arg1, arg2, argN): ...
@end example

Η φόρμα @code{@@staticmethod} είναι μια συνάρτηση @ref{b18,,decorator} – δείτε @ref{2206,,Function definitions} για λεπτομέρειες.

Μια στατική μέθοδος μπορεί να κληθεί είτε στην κλάση (όπως @code{C.f()}) είτε σε ένα instance (όπως @code{C().f()}). Επιπλέον, η στατική μέθοδος @ref{21f,,descriptor} μπορεί επίσης να κληθεί, επομένως μπορεί να χρησιμοποιηθεί στον ορισμός της κλάσης (όπως @code{f()}).

Οι στατικές μέθοδοι στην Python είναι παρόμοιες με αυτές που βρίσκονται στην Java ή στη C++. Επίσης, ανατρέξτε στη @ref{69a,,classmethod()} για μια παραλλαγή που είναι χρήσιμη για τη δημιουργία εναλλακτικών κατασκευαστών κλάσεων.

Όπως όλοι οι διακοσμητές, είναι επίσης δυνατό να καλέσετε την @code{staticmethod} ως κανονική συνάρτηση και να κάνετε κάτι με το αποτέλεσμά της.  Αυτό είναι απαραίτητο σε ορισμένες περιπτώσεις όπου χρειάζεστε μια αναφορά σε μια συνάρτηση από ένα σώμα κλάσης και θέλετε να αποφύγετε την αυτόματη μετατροπή σε instance μέθοδο.  Για αυτές τις περιπτώσεις, χρησιμοποιήστε αυτό το ιδίωμα:

@example
def regular_function():
    ...

class C:
    method = staticmethod(regular_function)
@end example

Για περισσότερες πληροφορίες σχετικά με τις στατικές μεθόδους, δείτε το @ref{2520,,Η τυπική ιεραρχία τύπου}.


Άλλαξε στην έκδοση 3.10: Οι στατικές μέθοδοι κληρονομούν πλέον τα χαρακτηριστικά της μεθόδου (@ref{253b,,__module__}, @ref{1679,,__name__}, @ref{253a,,__qualname__}, @ref{1582,,__doc__} και @ref{1581,,__annotations__}),, έχουν ένα νέο χαρακτηριστικό @code{__wrapped__}, και μπορούν πλέον να καλούνται ως κανονικές λειτουργίες.

@end deffn

@geindex string;str() (ενσωματωμένη συνάρτηση)

@anchor{library/functions func-str}@anchor{27b8}
@deffn {Κλάση} str (*, encoding='utf-8', errors='strict')

@deffnx {Κλάση} str (object)

@deffnx {Κλάση} str (object, encoding, errors='strict')

@deffnx {Κλάση} str (object, *, errors)

Επιστρέφει μια έκδοση @ref{1df,,str} του `object'.  Δείτε @ref{1df,,str()} για λεπτομέρειες.

Το @code{str} είναι η ενσωματωμένη συμβολοσειρά @ref{1ef2,,class}.  Για γενικές πληροφορίες σχετικά με τις συμβολοσειρές, ανατρέξτε @ref{21cd,,Τύπος Ακολουθίας (Sequence) Κειμένου — str}.
@end deffn

@geindex built-in function; sum()
@anchor{library/functions sum}@anchor{881}
@deffn {Συνάρτηση} sum (iterable, /, start=0)

Αθροίζει το `start' και τα στοιχεία ενός `iterable' από αριστερά προς δεξιά και επιστρέφει το σύνολο.  Τα στοιχεία του `iterable' είναι συνήθως αριθμοί και η τιμή έναρξης δεν επιτρέπεται να είναι συμβολοσειρά.

Για ορισμένες περιπτώσεις χρήσης, υπάρχουν καλές εναλλακτικές λύσεις για το @ref{881,,sum()}. Ο προτιμώμενος, γρήγορος τρόπος για να συνδέσετε μια ακολουθία συμβολοσειρών είναι καλώντας @code{'@w{'}.join(sequence)}.  Για να προσθέσετε τιμές κινητής υποδιαστολής με εκτεταμένη ακρίβεια, δείτε @ref{1777,,math.fsum()}.  Για να συνδυάσετε μια σειρά iterable, σκεφτείτε να χρησιμοποιήσετε το @ref{190,,itertools.chain()}.


Άλλαξε στην έκδοση 3.8: Η παράμετρος `start' μπορεί να καθοριστεί ως όρισμα keyword.



Άλλαξε στην έκδοση 3.12: Η άθροιση των floats άλλαξε σε έναν αλγόριθμο που δίνει μεγαλύτερη ακρίβεια και καλύτερη αντιμεταθετικότητα στις περισσότερες κατασκευές.



Άλλαξε στην έκδοση 3.14: Προστέθηκε εξειδίκευση για άθροιση συμπλεγμάτων, χρησιμοποιώντας τον ίδιο αλγόριθμο όπως για την άθροιση των float.

@end deffn

@geindex super (ενσωματωμένη κλάση)
@anchor{library/functions super}@anchor{443}
@deffn {Κλάση} super

@deffnx {Κλάση} super (type, object_or_type=None, /)

Επιστρέφει ένα αντικείμενο διακομιστή μεσολάβησης που εκχωρεί κλήσεις μεθόδου σε μια γονική ή αδερφή κλάση `type'.  Αυτό είναι χρήσιμο για την πρόσβαση σε μεταβιβασμένες μεθόδους που έχουν παρακαμφθεί σε μια κλάση.

Το `object_or_type' καθορίζει το @ref{2784,,method resolution order} που θα αναζητηθεί.  Η αναζήτηση ξεκινά από την κλάση αμέσως μετά τον `type'.

Για παράδειγμα, εάν @ref{2569,,__mro__} του `object_or_type' είναι @code{D -> B -> C -> A -> object} και η τιμή του `type' είναι @code{B}, τότε η @ref{443,,super()} αναζητά @code{C -> A -> object}.

Το χαρακτηριστικό @ref{2569,,__mro__} της κλάσης που αντιστοιχεί σε λίστες του `object_or_type' παραθέτει τη σειρά αναζήτησης ανάλυσης μεθόδου που χρησιμοποιείται και από τις @ref{f8f,,getattr()} και @ref{443,,super()}.  Το χαρακτηριστικό είναι δυναμικό και μπορεί να αλλάξει κάθε φορά που ενημερώνεται η ιεραρχία κληρονομικότητας.

Εάν το δεύτερο όρισμα παραλειφθεί, το υπεραντικείμενο που επιστράφηκε δεν είναι δεσμευμένο.  Εάν το δεύτερο όρισμα είναι αντικείμενο, @code{isinstance(obj, type)} πρέπει να είναι αληθές.  Εάν το δεύτερο όρισμα είναι ένας τύπος, το @code{issubclass(type2, type)} πρέπει να είναι αληθές (αυτό είναι χρήσιμο για μεθόδους κλάσης).

Όταν καλείται απευθείας μέσα σε μια κανονική μέθοδο μιας κλάσης, και τα δύο ορίσματα μπορούν να παραλειφθούν («χωρίς ορίσματα @code{super()}»). Σε αυτή την περίπτωση, το `type' είναι η περιβάλλουσα κλάση και το `obj' είναι το πρώτο όρισμα της αμέσως περιβάλλουσας συνάρτησης (συνήθως @code{self}). (Αυτό σημαίνει ότι η @code{super()} χωρίς ορίσματα δεν θα λειτουργήσει όπως αναμένεται μέσα σε φωλιασμένες συναρτήσεις, συμπεριλαμβανομένων και των γεννητριών εκφράσεων, οι οποίες δημιουργούν έμμεσα φωλιασμένες συναρτήσεις.)

Υπάρχουν δύο τυπικές περιπτώσεις χρήσης για το `super'.  Σε μια ιεραρχία κλάσεων με ενιαία κληρονομικότητα, το `super' μπορεί να χρησιμοποιηθεί για να αναφέρεται σε γονικές κλάσεις χωρίς να τις ονομάζει ρητά, καθιστώντας έτσι τον κώδικα πιο διατηρήσιμο.  Αυτή η χρήση είναι πολύ παράλληλη με τη χρήση του `super' σε άλλες γλώσσες προγραμματισμού.

Η δεύτερη περίπτωση χρήσης είναι η υποστήριξη πολλαπλής κληρονομικότητας συνεργασίας σε ένα δυναμικό περιβάλλον εκτέλεσης.  Αυτή η περίπτωση χρήσης είναι μοναδική για την Python και δεν βρίσκεται σε στατικά μεταγλωττισμένες γλώσσες ή γλώσσες που υποστηρίζουν μόνο μεμονωμένη κληρονομικότητα.  Αυτό καθιστά δυνατή την υλοποίηση «διαγραμμάτων διαμαντιών» όπου πολλές βασικές κλάσεις υλοποιούν την ίδια μέθοδο.  Ο καλός σχεδιασμός υπαγορεύει ότι τέτοιες υλοποιήσεις έχουν την ίδια υπογραφή κλήσης σε κάθε περίπτωση (επειδή η σειρά των κλήσεων καθορίζεται κατά τον χρόνο εκτέλεσης, επειδή αυτή η σειρά προσαρμόζεται στις αλλαγές στην ιεραρχία κλάσεων και επειδή αυτή η διάταξη μπορεί να περιλαμβάνει αδερφικές κλάσεις πριν από τον χρόνο εκτέλεσης).

Και για τις δύο περιπτώσεις χρήσης, μια τυπική κλήση υπερκλάσης μοιάζει με αυτό:

@example
class C(B):
    def method(self, arg):
        super().method(arg)    # This does the same thing as:
                               # super(C, self).method(arg)
@end example

Εκτός από τις αναζητήσεις μεθόδων, το @ref{443,,super()} λειτουργεί επίσης για αναζητήσεις χαρακτηριστικών.  Μια πιθανή περίπτωση χρήσης για αυτό είναι η κλήση @ref{21f,,descriptors} σε μια κλάση γονέα ή αδελφού.

Λάβετε υπόψη ότι το @ref{443,,super()} υλοποιείται ως μέρος της διαδικασίας δέσμευσης για ρητές αναζητήσεις χαρακτηριστικών με κουκκίδες όπως @code{super().__getitem__(name)}. Το κάνει εφαρμόζοντας τη δικιά του μέθοδο @ref{f90,,__getattribute__()} για αναζήτηση κλάσεων με προβλέψιμη σειρά που υποστηρίζει πολλαπλή κληρονομικότητα. Συνεπώς, η @code{super()} δεν έχει οριστεί για σιωπηρές αναζητήσεις που χρησιμοποιούν δηλώσεις ή τελεστές όπως @code{super()[name]}.

Λάβετε επίσης υπόψη ότι, εκτός από τη μορφή μηδενικού ορίσματος, η @ref{443,,super()} δεν περιορίζεται στη χρήση μεθόδων εντός.  Η φόρμα δύο ορισμάτων καθορίζει ακριβώς τα ορίσματα και κάνει τις κατάλληλες αναφορές.  Η φόρμα μηδενικού ορίσματος λειτουργεί μόνο μέσα σε έναν ορισμό κλάσης, καθώς ο μεταγλωττιστής συμπληρώνει τις απαραίτητες λεπτομέρειες για την σωστή ανάκτηση της κλάσης που ορίζεται, καθώς και για την πρόσβαση στην τρέχουσα παρουσία για συνηθισμένες μεθόδους.

Για πρακτικές προτάσεις σχετικά με το πώς να σχεδιάσετε συνεργατικές τάξεις χρησιμοποιώντας το @ref{443,,super()}, ανατρέξτε οδηγός χρήσης super()@footnote{https://rhettinger.wordpress.com/2011/05/26/super-considered-super/}.


Άλλαξε στην έκδοση 3.14: Τα αντικείμενα @ref{443,,super} είναι πλέον @ref{ab,,pickleable} και @ref{29,,copyable}.

@end deffn

@anchor{library/functions func-tuple}@anchor{27b9}
@deffn {Κλάση} tuple (iterable=(), /)

Αντί να είναι συνάρτηση, το @ref{1ce,,tuple} είναι στην πραγματικότητα ένα αμετάβλητος τύπος ακολουθίας, όπως τεκμηριώνεται στα @ref{2742,,Πλειάδες (Tuples)} και @ref{221d,,Τύποι Ακολουθίας (Sequence) — list@comma{} tuple@comma{} range}.
@end deffn

@geindex type (ενσωματωμένη κλάση)
@anchor{library/functions type}@anchor{186}
@deffn {Κλάση} type (object, /)

@deffnx {Κλάση} type (name, bases, dict, /, **kwargs)

@geindex αντικείμενο;τύπος

Με ένα όρισμα, επιστρέψτε τον τύπο ενός `object'.  Η τιμή που επιστρέφεται είναι ένα αντικείμενο τύπου και γενικά το ίδιο αντικείμενο με αυτό που επιστρέφεται από το @ref{184f,,object.__class__}.

Η ενσωματωμένη συνάρτηση @ref{2ef,,isinstance()} συνίσταται για τη δοκιμή του τύπου ενός αντικειμένου, επειδή λαμβάνει υπόψη τις υποκλάσεις.

Με τρία ορίσματα, επιστρέφει ένα αντικείμενο νέου τύπου.  Αυτή είναι ουσιαστικά μια δυναμική μορφή της δήλωσης @ref{167c,,class}. Η συμβολοσειρά `name' είναι το όνομα της κλάσης και γίνεται το χαρακτηριστικό @ref{184d,,__name__}. Η πλειάδα `bases' περιέχει τις βασικές κλάσεις και γίνεται το χαρακτηριστικό @ref{184e,,__bases__} ∙ αν είναι κενό, προστίθεται το @ref{e4d,,object}, η τελική βάση όλων των κλάσεων.  Το λεξικό `dict' περιέχει ορισμούς χαρακτηριστικών και μεθόδων για το σώμα της κλάσης∙ μπορεί να αντιγραφεί ή να προσαρμοστεί πριν γίνει το χαρακτηριστικό @ref{101b,,__dict__}. Οι ακόλουθες δύο προτάσεις δημιουργούν πανομοιότυπα αντικείμενα @code{type}:

@example
>>> class X:
...     a = 1
...
>>> X = type('X', (), dict(a=1))
@end example

Δείτε επίσης:


@itemize *

@item 
@ref{2562,,Τεκμηρίωση για χαρακτηριστικά και μεθόδους σε κλάσεις}.

@item 
@ref{27da,,Τύποι Αντικειμένων}
@end itemize

Τα ορίσματα λέξεων-κλειδιών που παρέχονται στη φόρμα τριών ορισμάτων μεταβιβάζονται στον κατάλληλο μηχανισμό μετακλάσης (συνήθως @ref{a22,,__init_subclass__()}) με τον ίδιο τρόπο που θα έκαναν οι λέξεις-κλειδιά στον ορισμό μιας κλάσης (εκτός από το `metaclass').

Δείτε επίσης @ref{1009,,Προσαρμογή δημιουργίας κλάσης}.


Άλλαξε στην έκδοση 3.6: Οι υποκλάσης της @code{type} που δεν αντικαθιστούν το @code{type.__new__} δεν μπορούν πλέον να χρησιμοποιούν τη φόρμα ενός επιχειρήματος για να λάβουν τον τύπο ενός αντικειμένου.



Άλλαξε στην έκδοση 3.15: `dict' can now be a @ref{182,,frozendict}.

@end deffn

@geindex built-in function; vars()
@anchor{library/functions vars}@anchor{2011}
@deffn {Συνάρτηση} vars ()

@deffnx {Συνάρτηση} vars (object, /)

Επιστρέφει το χαρακτηριστικό @ref{1bf,,__dict__} για ένα module, κλάση, στιγμιότυπο, ή οποιοδήποτε άλλο αντικείμενο με ένα χαρακτηριστικό @code{__dict__}.

Αντικείμενα όπως modules και instances έχουν ένα χαρακτηριστικό @ref{1bf,,__dict__} με δυνατότητα ενημέρωσης∙ ωστόσο, άλλα αντικείμενα μπορεί να έχουν περιορισμούς εγγραφής στα χαρακτηριστικά τους @code{__dict__} (για παράδειγμα, οι κλάσεις χρησιμοποιούν ένα @ref{189,,types.MappingProxyType} για την αποτροπή άμεσων ενημερώσεων λεξικού).

Χωρίς ένα όρισμα, @ref{2011,,vars()} συμπεριφέρεται όπως @ref{28b,,locals()}.

Μια εξαίρεση @ref{291,,TypeError} γίνεται raise εάν ένα αντικείμενο έχει καθοριστεί αλλά δεν έχει ένα χαρακτηριστικό @ref{1bf,,__dict__} (για παράδειγμα, εάν η κλάση του ορίζει το @ref{188d,,__slots__} χαρακτηριστικό).


Άλλαξε στην έκδοση 3.13: Το αποτέλεσμα της κλήσης αυτής της συνάρτησης χωρίς ένα όρισμα έχει ενημερωθεί, όπως περιγράφεται για τη ενσωματωμένη @ref{28b,,locals()}.

@end deffn

@geindex built-in function; zip()
@anchor{library/functions zip}@anchor{43f}
@deffn {Συνάρτηση} zip (*iterables, strict=False)

Επανάληψη σε πολλούς iterables παράλληλα, δημιουργώντας πλειάδες με ένα αντικείμενο από το καθένα.

Παράδειγμα:

@example
>>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']):
...     print(item)
...
(1, 'sugar')
(2, 'spice')
(3, 'everything nice')
@end example

Πιο τυπικά: η @ref{43f,,zip()} επιστρέφει έναν iterator πλειάδων, όπου η `i'-η πλειάδα περιέχει το `i'-ο στοιχείο από κάθε ένα από τους επαναλήψιμους ορισμάτων.

Ένας άλλος τρόπος για να σκεφτείτε τη @ref{43f,,zip()} είναι ότι μετατρέπει τις γραμμές σε στήλες, και τις στήλες σε γραμμές.  Αυτό είναι παρόμοιο με μεταφορά μιας μήτρας@footnote{https://en.wikipedia.org/wiki/Transpose}.

Το @ref{43f,,zip()} είναι τεμπέλης: Τα στοιχεία δεν θα υποβληθούν σε επεξεργασία μέχρι να επαναληφθεί ο iterable, π.χ. με έναν βρόχο @code{for} ή με αναδίπλωση σε μια @ref{4d9,,list}.

Ένα πράγμα που πρέπει να λάβετε υπόψη είναι ότι τα iterables που μεταβιβάστηκαν στη @ref{43f,,zip()} θα μπορούσαν να έχουνε διαφορετικά μήκη∙ μερικές φορές από το σχεδιασμό και μερικές φορές λόγω ενός σφάλματος στον κώδικα που προετοίμασε αυτά τα iterables.  Η Python προσφέρει τρεις διαφορετικές προσεγγίσεις για την αντιμετώπιση αυτού του ζητήματος:


@itemize *

@item 
Από default, η @ref{43f,,zip()} σταματά όταν εξαντληθεί ο συντομότερος iterable. Αυτό θα αγνοήσει τα υπόλοιπα στοιχεία στους μεγαλύτερους iterables, κόβοντας το αποτέλεσμα στο μήκος του συντομότερου iterable:

@example
>>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum']))
[(0, 'fee'), (1, 'fi'), (2, 'fo')]
@end example

@item 
Η @ref{43f,,zip()} χρησιμοποιείται συχνά σε περιπτώσεις όπου τα iterables υποτίθεται ότι έχουν ίσο μήκος.  Σε τέτοιες περιπτώσεις, συνίσταται η χρήση της επιλογής @code{strict=True}. Η έξοδος είναι ίδια με την κανονική @code{zip()}:

@example
>>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))
[('a', 1), ('b', 2), ('c', 3)]
@end example

Σε αντίθεση με την προεπιλεγμένη συμπεριφορά, γίνεται raise ένα @ref{277,,ValueError} εάν ένα iterable εξαντληθεί πριν από τα άλλα:

@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

Χωρίς το όρισμα @code{strict=True}, κάθε σφάλμα που οδηγεί σε επαναλαμβανόμενα μήκη διαφορετικού μήκους θα τεθεί σε σίγαση, πιθανώς να εμφανίζεται ως δυσεύρετο σφάλμα σε άλλο μέρος του προγράμματος.

@item 
Οι μικρότεροι iterables μπορούν να συμπληρωθούν σε μια σταθερή τιμή ώστε όλα τα iterables να έχουνε το ίδιο μήκος.  Αυτό γίνεται από το @ref{1643,,itertools.zip_longest()}.
@end itemize

Περιπτώσεις άκρων: Με ένα μόνο επαναληπτικό όρισμα, η @ref{43f,,zip()} επιστρέφει έναν iterator 1-πλειάδων.  Χωρίς ορίσματα, επιστρέφει έναν κενό iterator.

Συμβουλές και κόλπα:


@itemize *

@item 
Η σειρά αξιολόγησης από αριστερά προς τα δεξιά των iterables είναι εγγυημένη. Αυτό καθιστά δυνατό ένα ιδίωμα για την ομαδοποίηση μιας σειράς δεδομένων σε ομάδες n-μήκους χρησιμοποιώντας @code{zip(*[iter(s)]*n, strict=True)}.  Αυτό επαναλαμβάνει τις `ίδιες' επαναλήψεις @code{n} φορές έτσι ώστε κάθε πλειάδα εξόδου να έχει το αποτέλεσμα των κλήσεων @code{n} προς τον επαναλήπτη. Αυτό έχει ως αποτέλεσμα τη διαίρεση της εισόδου σε κομμάτια μήκους.

@item 
Η @ref{43f,,zip()} σε συνδυασμό με τον τελεστή @code{*} μπορεί να χρησιμοποιηθεί για την αποσυμπίεση μιας λίστας:

@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


Άλλαξε στην έκδοση 3.10: Προστέθηκε το όρισμα  @code{strict}.

@end deffn

@geindex built-in function; __import__()
@anchor{library/functions import__}@anchor{ca6}
@deffn {Συνάρτηση} __import__ (name, globals=None, locals=None, fromlist=(), level=0)

@geindex δήλωση;import
@geindex module;builtins

@cartouche
@quotation Σημείωση 
Αυτή είναι μια προηγμένη συνάρτηση που δεν χρειάζεται στον καθημερινό προγραμματισμό της Python, σε αντίθεση με το @ref{927,,importlib.import_module()}.
@end quotation
@end cartouche

Αυτή η συνάρτηση καλείται από τη δήλωση @ref{9da,,import}.  Μπορεί να αντικατασταθεί (με εισαγωγή του module @ref{13,,builtins} και αντιστοίχιση σε @code{builtins.__import__}) προκειμένου να αλλάξει η σημασιολογία της δήλωσης @code{import}, αλλά αυτό αποθαρρύνεται `σθεναρά', καθώς είναι συνήθως απλούστερο να χρησιμοποιήσετε τα άγκιστρα εισαγωγής (δείτε 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}) για την επίτευξη των ίδιων στόχων και δεν προκαλεί προβλήματα με τον κώδικα που προϋποθέτει την χρήση της προεπιλεγμένης υλοποίησης εισαγωγής.  Η άμεση χρήση του @ref{ca6,,__import__()} επίσης αποθαρρύνεται υπέρ του @ref{927,,importlib.import_module()}.

Η συνάρτηση εισάγει το module `name', χρησιμοποιώντας πιθανώς τα δεδομένα `globals' και `locals' για να καθορίσει τον τρόπο ερμηνείας του ονόματος σε ένα πλαίσιο πακέτου. Η `fromlist' δίνει τα ονόματα των αντικειμένων ή των υπομονάδων που θα πρέπει να εισαχθούν από το module που δίνεται από το `name'.  Η τυπική υλοποίηση δεν χρησιμοποιεί καθόλου το όρισμα `locals' και χρησιμοποιεί τα `globals' της μόνο για να προσδιορίσει το πλαίσιο του πακέτου της δήλωσης @ref{9da,,import}.

Το `level' καθορίζει εάν θα χρησιμοποιηθούν απόλυτες ή σχετικές εισαγωγές. Το @code{0} (η προεπιλογή) σημαίνει μόνο απόλυτες εισαγωγές.  Οι θετικές τιμές για το `level' υποδεικνύουν τον αριθμό των γονικών καταλόγων προς αναζήτηση σε σχέση με τον κατάλογο του module που καλεί την @ref{ca6,,__import__()} (δείτε το 
@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/} για λεπτομέρειες).

Όταν η μεταβλητή `name' είναι της μορφής @code{package.module}, κανονικά, επιστρέφεται το πακέτο ανωτάτου επιπέδου (το όνομα μέχρι την πρώτη κουκκίδα), `όχι' το module που ονομάζεται `name'.  Ωστόσο, όταν δίνεται ένα μη κενό όρισμα `fromlist', επιστρέφεται το module με το όνομα `name'.

Για παράδειγμα, η δήλωση @code{import spam} καταλήγει σε bytecode που μοιάζει με τον ακόλουθο κώδικα:

@example
spam = __import__('spam', globals(), locals(), [], 0)
@end example

Η δήλωση @code{import spam.ham} καταλήγει σε αυτήν την κλήση:

@example
spam = __import__('spam.ham', globals(), locals(), [], 0)
@end example

Σημειώστε πως το @ref{ca6,,__import__()} επιστρέφει το ανωτάτου επιπέδου module εδώ, επειδή αυτό είναι το αντικείμενο που συνδέεται με ένα όνομα με τη δήλωση @ref{9da,,import}.

Από την άλλη πλευρά, η δήλωση @code{from spam.ham import eggs, sausage as saus} καταλήγει σε

@example
_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
eggs = _temp.eggs
saus = _temp.sausage
@end example

Εδώ, το module @code{spam.ham} επιστρέφεται από τη @ref{ca6,,__import__()}.  Από αυτό το αντικείμενο, τα ονόματα προς εισαγωγή ανακτώνται και εκχωρούνται στα αντίστοιχα ονόματά τους.

Εάν θέλετε απλώς να εισάγετε ένα module (ενδεχομένως μέσα σε ένα πακέτο) με το όνομα, χρησιμοποιήστε το @ref{927,,importlib.import_module()}.


Άλλαξε στην έκδοση 3.3: Αρνητικές τιμές για το `level' δεν υποστηρίζονται πλέον (το οποίο επίσης αλλάζει την προεπιλεγμένη τιμή σε 0).



Άλλαξε στην έκδοση 3.9: Όταν χρησιμοποιούνται επιλογές της γραμμής εντολών @ref{d27,,-E} ή @ref{d28,,-I}, τότε η μεταβλητή περιβάλλοντος 
@geindex PYTHONCASEOK
@geindex μεταβλητή περιβάλλοντος; PYTHONCASEOK
@ref{d26,,PYTHONCASEOK} δεν λαμβάνεται υπόψιν.

@end deffn

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Built-in Constants,Τύποι Built-in,Ενσωματωμένες Built-in Συναρτήσεις,The Python Standard Library
@anchor{library/constants doc}@anchor{27db}@anchor{library/constants built-in-constants}@anchor{27dc}@anchor{library/constants built-in-consts}@anchor{266d}@anchor{library/constants translation-repo}@anchor{27dd}
@section Built-in Constants


A small number of constants live in the built-in namespace.  They are:

@geindex False (ενσωματωμένη μεταβλητή)
@anchor{library/constants False}@anchor{ef5}
@deffn {Δεδομένα} False

The false value of the @ref{5ef,,bool} type. Assignments to @code{False}
are illegal and raise a @ref{17e,,SyntaxError}.
@end deffn

@geindex True (ενσωματωμένη μεταβλητή)
@anchor{library/constants True}@anchor{fcc}
@deffn {Δεδομένα} True

The true value of the @ref{5ef,,bool} type. Assignments to @code{True}
are illegal and raise a @ref{17e,,SyntaxError}.
@end deffn

@geindex None (ενσωματωμένη μεταβλητή)
@anchor{library/constants None}@anchor{a65}
@deffn {Δεδομένα} 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{17e,,SyntaxError}.
@code{None} is the sole instance of the @ref{c2a,,NoneType} type.
@end deffn

@geindex NotImplemented (ενσωματωμένη μεταβλητή)
@anchor{library/constants NotImplemented}@anchor{440}
@deffn {Δεδομένα} NotImplemented

A special value which should be returned by the binary special methods
(e.g. @ref{ec0,,__eq__()}, @ref{1645,,__lt__()}, @ref{25d2,,__add__()}, @ref{25e5,,__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{25d7,,__imul__()}, @ref{25f4,,__iand__()}, etc.) for the same purpose.
It should not be evaluated in a boolean context.
@code{NotImplemented} is the sole instance of the @ref{c2b,,types.NotImplementedType} type.

@cartouche
@quotation Σημείωση 
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.

See @ref{2523,,Implementing the arithmetic operations} for examples.
@end quotation
@end cartouche

@cartouche
@quotation Προσοχή 
@code{NotImplemented} and @code{NotImplementedError} are not
interchangeable. This constant should only be used as described
above; see @ref{59a,,NotImplementedError} for details on correct usage
of the exception.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.9: Evaluating @code{NotImplemented} in a boolean context was deprecated.



Άλλαξε στην έκδοση 3.14: Evaluating @code{NotImplemented} in a boolean context now raises a @ref{291,,TypeError}.
It previously evaluated to @ref{fcc,,True} and emitted a @ref{2c9,,DeprecationWarning}
since Python 3.9.

@end deffn

@geindex ...;ellipsis literal

@geindex Ellipsis (ενσωματωμένη μεταβλητή)
@anchor{library/constants Ellipsis}@anchor{2519}
@deffn {Δεδομένα} Ellipsis

The same as the ellipsis literal «@code{...}», an object frequently used to
indicate that something is omitted. Assignment to @code{Ellipsis} is possible, but
assignment to  @code{...} raises a @ref{17e,,SyntaxError}.
@code{Ellipsis} is the sole instance of the @ref{c29,,types.EllipsisType} type.
@end deffn

@geindex __debug__ (ενσωματωμένη μεταβλητή)
@anchor{library/constants debug__}@anchor{bb7}
@deffn {Δεδομένα} __debug__

This constant is true if Python was not started with an @ref{431,,-O} option.
See also the @ref{d31,,assert} statement.
@end deffn

@cartouche
@quotation Σημείωση 
The names @ref{a65,,None}, @ref{ef5,,False}, @ref{fcc,,True} and @ref{bb7,,__debug__}
cannot be reassigned (assignments to them, even as an attribute name, raise
@ref{17e,,SyntaxError}), so they can be considered «true» constants.
@end quotation
@end cartouche

@menu
* Constants added by the site module:: 

@end menu

@node Constants added by the site module,,,Built-in Constants
@anchor{library/constants constants-added-by-the-site-module}@anchor{27de}@anchor{library/constants site-consts}@anchor{27df}
@subsection Constants added by the @code{site} module


The @ref{cf,,site} module (which is imported automatically during startup, except
if the @ref{1551,,-S} command-line option is given) adds several constants to the
built-in namespace.  They are useful for the interactive interpreter shell and
should not be used in programs.

@geindex quit (ενσωματωμένη μεταβλητή)
@geindex exit (ενσωματωμένη μεταβλητή)
@anchor{library/constants quit}@anchor{27e0}
@deffn {Δεδομένα} quit (code=None)
@anchor{library/constants exit}@anchor{27e1}
@deffnx {Δεδομένα} exit (code=None)

Objects that when printed, print a message like «Use quit() or Ctrl-D
(i.e. EOF) to exit», and when accessed directly in the interactive
interpreter or called as functions, raise @ref{10f7,,SystemExit} with the
specified exit code.
@end deffn


@deffn {Δεδομένα} help

Object that when printed, prints the message «Type help() for interactive
help, or help(object) for help about object.», and when accessed directly
in the interactive interpreter, invokes the built-in help system
(see @ref{ca9,,help()}).
@end deffn

@geindex copyright (ενσωματωμένη μεταβλητή)
@geindex credits (ενσωματωμένη μεταβλητή)
@anchor{library/constants copyright}@anchor{1983}
@deffn {Δεδομένα} copyright
@anchor{library/constants credits}@anchor{1984}
@deffnx {Δεδομένα} credits

Objects that when printed or called, print the text of copyright or
credits, respectively.
@end deffn

@geindex license (ενσωματωμένη μεταβλητή)
@anchor{library/constants license}@anchor{1982}
@deffn {Δεδομένα} license

Object that when printed, prints the message «Type license() to see the
full license text», and when called, displays the full license text in a
pager-like fashion (one screen at a time).
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c XXX: reference/datamodel and this have quite a few overlaps!

@node Τύποι Built-in,Built-in Exceptions,Built-in Constants,The Python Standard Library
@anchor{library/stdtypes doc}@anchor{27e2}@anchor{library/stdtypes bltin-types}@anchor{27e3}@anchor{library/stdtypes built-in-types}@anchor{27e4}@anchor{library/stdtypes translation-repo}@anchor{27e5}
@section Τύποι Built-in


Οι παρακάτω κατηγορίες περιγράφουν τους standard τύπους που είναι ενσωματωμένοι (built) μέσα στον interpreter.

@geindex ενσωματωμένοι (built-in) τύποι;τύποι

Οι κύριοι ενσωματωμένοι (built) τύποι είναι αριθμοί, ακολουθίες, αντιστοιχίσεις (mappings), κλάσεις, instances και exceptions.

Ορισμένες collection κλάσεις είναι μεταβλητές (mutable). Οι μέθοδοι που προσθέτουν, αφαιρούν ή αναδιατάσσουν τα μέλη τους και δεν επιστρέφουν ένα συγκεκριμένο αντικείμενο, ποτέ δεν επιστρέφουν το ίδιο collection instance αλλά @code{None}.

Ορισμένες λειτουργίες υποστηρίζονται από διάφορους τύπους αντικειμένων· ειδικότερα, σχεδόν όλα τα αντικείμενα μπορούν να συγκριθούν ως προς την ισότητα, να ελεγχθούν για την έγκυρη τιμή και να μετατραπούν σε συμβολοσειρά (string) (με τη συνάρτηση @ref{45b,,repr()} ή την ελαφρώς διαφορετική συνάρτηση @ref{1df,,str()}). Η τελευταία συνάρτηση χρησιμοποιείται έμμεσα όταν ένα αντικείμενο γράφεται από τη συνάρτηση @ref{131f,,print()}.

@menu
* Έλεγχος Έγκυρης Τιμής:: 
* Λογικές (Boolean) Πράξεις — and@comma{} or@comma{} not: Λογικές Boolean Πράξεις — and or not. 
* Συγκρίσεις:: 
* Αριμθητικοί Τύποι — int@comma{} float@comma{} complex: Αριμθητικοί Τύποι — int float complex. 
* Τύπος Boolean - bool:: 
* Τύποι Iterator:: 
* Τύποι Ακολουθίας (Sequence) — list@comma{} tuple@comma{} range: Τύποι Ακολουθίας Sequence — list tuple range. 
* Σύνοψη μεθόδων τύπου κειμένου και δυαδική ακολουθίας:: 
* Τύπος Ακολουθίας (Sequence) Κειμένου — str: Τύπος Ακολουθίας Sequence Κειμένου — str. 
* Τύποι δυαδικής ακολουθίας — bytes@comma{} bytearray@comma{} memoryview: Τύποι δυαδικής ακολουθίας — bytes bytearray memoryview. 
* Τύποι Συνόλου (Set) — set@comma{} frozenset: Τύποι Συνόλου Set — set frozenset. 
* Mapping types — dict@comma{} frozendict: Mapping types — dict frozendict. 
* Τύποι Διαχείρισης Περιεχομένου:: 
* Τύποι Annotation τύπου — Generic Alias@comma{} Union: Τύποι Annotation τύπου — Generic Alias Union. 
* Άλλοι Ενσωματωμένοι (built-in) Τύποι: Άλλοι Ενσωματωμένοι built-in Τύποι. 
* Ειδικά Χαρακτηριστικά:: 
* Περιορισμός μήκους μετατροπής συμβολοσειράς ακέραιου αριθμού:: 

@end menu

@node Έλεγχος Έγκυρης Τιμής,Λογικές Boolean Πράξεις — and or not,,Τύποι Built-in
@anchor{library/stdtypes truth}@anchor{1a80}@anchor{library/stdtypes truth-value-testing}@anchor{27e6}
@subsection Έλεγχος Έγκυρης Τιμής


@geindex statement;if
@geindex statement;while
@geindex αληθές;τιμή
@geindex Boolean;λειτουργίες
@geindex false

Οποιοδήποτε αντικείμενο μπορεί να ελεγχθεί ως προς την εγκυρότητα της τιμής του, για χρήση σε @ref{322,,if} ή @ref{1b86,,while} συνθήκη ή ως τελεστής των λογικών πράξεων παρακάτω.

@geindex true

By default, an object is considered true unless its class defines either a
@ref{167a,,__bool__()} method that returns @code{False} or a
@ref{1989,,__len__()} method that
returns zero, when called with the object. @footnote{
Πρόσθετε πληροφορίες σχετικά με αυτές τις ειδικές μεθόδους μπορείτε να βρείτε στο Εγχειρίδιο Αναφοράς Python (@ref{25a2,,Βασική προσαρμογή}).
} If one of the methods raises an
exception when called, the exception is propagated and the object does
not have a truth value (for example, @ref{440,,NotImplemented}).
Here are most of the built-in objects considered false:

@geindex None (Ενσωματωμένο (Built-in) αντικείμενο)
@geindex False (Ενσωματωμένο (Built-in) αντικείμενο)


@itemize *

@item 
σταθερές που έχουν οριστεί ως false: @code{None} και @code{False}

@item 
μηδέν οποιουδήποτε αριθμητικού τύπου: @code{0}, @code{0,0}, @code{0j}, @code{Decimanl(0)}, @code{Fraction(0, 1)}

@item 
κενές ακολουθίες και collections: @code{'@w{'}}, @code{()}, @code{[]}, @code{@{@}}, @code{set()}, @code{range(0)}
@end itemize

@geindex τελεστής;or
@geindex τελεστής;and
@geindex False
@geindex True

Οι πράξεις και οι ενσωματωμένες (built-in) συναρτήσεις που έχουν αποτέλεσμα Boolean πάντα επιστρέφουν @code{0} ή @code{False} για false και @code{1} ή @code{True} για true, εκτός εάν δηλώνεται διαφορετικά. (Σημαντική εξαίρεση: οι λογικές (Boolean) πράξεις @code{or} και @code{and} επιστρέφουν πάντα έναν από τους τελεστές τους.)

@node Λογικές Boolean Πράξεις — and or not,Συγκρίσεις,Έλεγχος Έγκυρης Τιμής,Τύποι Built-in
@anchor{library/stdtypes boolean}@anchor{27e7}@anchor{library/stdtypes boolean-operations-and-or-not}@anchor{27e8}
@subsection Λογικές (Boolean) Πράξεις —  @code{and}, @code{or}, @code{not}


@geindex Boolean;λειτουργίες

Αυτές είναι οι λογικές (Boolean) πράξεις, ταξινομημένες βάσει προτεραιότητας:


@multitable {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Πράξη

@tab

Αποτέλεσμα

@tab

Σημειώσεις

@item

@code{x or y}

@tab

αν το `x' είναι true, τότε `x', αλλιώς `y'

@tab

(1)

@item

@code{x and y}

@tab

αν το `x' είναι false, τότε `x', αλλιώς `y'

@tab

(2)

@item

@code{not x}

@tab

if `x' είναι false, τότε @code{True}, αλλιώς @code{False}

@tab

(3)

@end multitable


@geindex τελεστής;and
@geindex τελεστής;or
@geindex τελεστής;not

Σημειώσεις:


@enumerate 

@item 
Αυτός είναι ένας τελεστής μικρού κυκλώματος, επομένως αξιολογεί μόνο το δεύτερο όρισμα αν το πρώτο είναι false.

@item 
Αυτός είναι ένας τελεστής μικρού κυκλώματος, επομένως αξιολογεί μόνο το δεύτερο όρισμα αν το πρώτο είναι true.

@item 
To @code{not} έχει χαμηλότερη προτεραιότητα από τους μη λογικούς (non-Boolean) τελεστές, οπότε το @code{not a == b} μεταφράζεται σαν @code{not (a==b)}, και το @code{a == not b} είναι συντακτικό σφάλμα.
@end enumerate

@node Συγκρίσεις,Αριμθητικοί Τύποι — int float complex,Λογικές Boolean Πράξεις — and or not,Τύποι Built-in
@anchor{library/stdtypes comparisons}@anchor{27e9}@anchor{library/stdtypes stdcomparisons}@anchor{27ea}
@subsection Συγκρίσεις


@geindex αλυσίδα;συγκρίσεις
@geindex τελεστής;σύγκριση
@geindex τελεστής;==
@geindex τελεστής;< (μικρότερο)
@geindex τελεστής;<=
@geindex τελεστής;> (μεγαλύτερο)
@geindex τελεστής;>=
@geindex τελεστής;!=
@geindex τελεστής;is
@geindex τελεστής;is not

Υπάρχουν οκτώ πράξεις σύγκρισης στην Python. Όλες έχουν την ίδια προτεραιότητα (η οποία είναι υψηλότερη από αυτή των λογικών (Boolean) πράξεων). Οι συγκρίσεις μπορεί να αλυσοδεθούν αυθαίρετα· για παράδειγμα, το @code{x < y <= z} ισοδυναμεί με @code{x < y και y <= z}, εκτός από το ότι το `y' αξιολογείται μόνο μία φορά (αλλά και στις δύο περιπτώσεις το `z' δεν αξιολογείται καθόλου όταν το @code{x < y} είναι false).

Αυτός ο πίνακας συνοψίζει τις πράξεις σύγκρισης:


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Πράξη

@tab

Έννοια

@item

@code{<}

@tab

αυστηρά μικρότερο από

@item

@code{<=}

@tab

μικρότερο από ή ίσο

@item

@code{>}

@tab

αυστηρά μεγαλύτερο από

@item

@code{>=}

@tab

μεγαλύτερο από ή ίσο

@item

@code{==}

@tab

ίσο

@item

@code{!=}

@tab

διάφορο

@item

@code{is}

@tab

ταυτότητα αντικειμένου

@item

@code{is not}

@tab

αρνητική ταυτότητα αντικειμένου

@end multitable


@geindex αντικείμενο;αριθμητικό
@geindex αντικείμενα;συγκρίνοντας

Unless stated otherwise, objects of different types never compare equal.
The @code{==} operator is always defined but for some object types (for example,
class objects) is equivalent to @ref{324,,is}. The @code{<}, @code{<=}, @code{>} and @code{>=}
operators are only defined where they make sense; for example, they raise a
@ref{291,,TypeError} exception when one of the arguments is a complex number.

@geindex __eq__() (μέθοδος στιγμιοτύπου)
@geindex __ne__() (μέθοδος στιγμιοτύπου)
@geindex __lt__() (μέθοδος στιγμιοτύπου)
@geindex __le__() (μέθοδος στιγμιοτύπου)
@geindex __gt__() (μέθοδος στιγμιοτύπου)
@geindex __ge__() (μέθοδος στιγμιοτύπου)

Μη πανομοιότυπα instances μιας κλάσης συνήθως συγκρίνονται ως μη ίσα εκτός εάν το η κλάση ορίζει τη μέθοδο @ref{ec0,,__eq__()}.

Τα instances μιας κλάσης δεν μπορούν να ταξινομηθούν σε σχέση με άλλα instances της ίδιας κλάσης, ή άλλους τύπους του αντικειμένου, εκτός εάν η κλάση ορίζει αρκετές από τις μεθόδους @ref{1645,,__lt__()}, @ref{16af,,__le__()}, @ref{16b0,,__gt__()}, και @ref{16b1,,__ge__()} (γενικά, @code{__lt__()} και @ref{ec0,,__eq__()} είναι αρκετά, αν θέλετε τις συμβατικές έννοιες των τελεστών σύγκρισης).

Η συμπεριφορά των τελεστών @ref{324,,is} και @ref{26ce,,is not} δεν μπορεί να είναι προσαρμοσμένη· επίσης, μπορούν να εφαρμοστούν σε οποιαδήποτε δύο αντικείμενα και ποτέ να μην δημιουργήσουν μία εξαίρεση.

@geindex τελεστής;in
@geindex τελεστής;not in

Δύο ακόμη πράξεις με την ίδια συντακτική προτεραιότητα, @ref{323,,in} και @ref{a20,,not in}, υποστηρίζονται από τύπους που είναι @ref{15ce,,iterable} ή υλοποιούν τη μέθοδο @ref{175c,,__contains__()}.

@node Αριμθητικοί Τύποι — int float complex,Τύπος Boolean - bool,Συγκρίσεις,Τύποι Built-in
@anchor{library/stdtypes numeric-types-int-float-complex}@anchor{27eb}@anchor{library/stdtypes typesnumeric}@anchor{21c9}
@subsection Αριμθητικοί Τύποι — @code{int}, @code{float}, @code{complex}


@geindex αντικείμενο;αριθμητικό
@geindex αντικείμενο;Boolean
@geindex αντικείμενο;ακέραιος
@geindex αντικείμενο;κινητής υποδιαστολής
@geindex αντικείμενο;μιγαδικός αριθμός
@geindex C;γλώσσα

Υπάρχουν τρεις διαφορετικοί αριθμητικοί τύποι: `integers', `floating point numbers' και `complex numbers'. Επιπλέον, τα Booleans είναι υπό-τύπος ακεραίων (integers). Οι ακέραιοι αριθμοί έχουν απεριόριστη ακρίβεια. Οι Αριθμοί κινητής υποδιαστολής (floating point numbers) συνήθως υλοποιούνται χρησιμοποιώντας το double στη C· πληροφορίες σχετικά με την ακρίβεια και την εσωτερική αναπαράσταση αριθμών κινητής υποδιαστολής για το μηχάνημα στο οποίο εκτελείται το πρόγραμμά σας είναι διαθέσιμο στο @ref{1fbf,,sys.float_info}. Οι μιγαδικοί αριθμοί (complex numbers) έχουν ένα πραγματικό και φανταστικό μέρος, κάθε ένα από τα οποία ένας αριθμός κινητής υποδιαστολής. Για να εξαγάγετε αυτά τα μέρη από έναν μιγαδικό αριθμό `z', χρησιμοποιήστε @code{z.real} και @code{z.imag}. (Η standard βιβλιοθήκη περιλαμβάνει τους πρόσθετους αριθμητικούς τύπους @ref{1c3,,fractions.Fraction}, για ορθολογικούς, και @ref{1c2,,decimal.Decimal}, για αριθμούς κινητής υποδιαστολής με ακρίβεια που ορίζει ο χρήστης.)

@geindex αριθμητικό;literals
@geindex ακέραιος;literals
@geindex κινητής υποδιαστολής;literals
@geindex μιγαδικός αριθμός;literals
@geindex δεκαεξαδικό;literals
@geindex οκταδικό;literals
@geindex δυαδικό;literals

Οι αριθμοί δημιουργούνται με αριθμητικά γράμματα ή ως αποτέλεσμα ενσωματωμένων (built-in) συναρτήσεων και τελεστών. Ακέραιοι αριθμοί (συμπεριλαμβανομένων του εξαδικού, του οκταδικού και των δυαδικοί αριθμών) αποδίδουν ακέραιους αριθμούς. Αριθμητικά που περιέχουν δεκαδικό  ή εκθέτη παράγουν αριθμούς κινητής υποδιαστολής. Η προσάρτηση του @code{'j'} ή του @code{'J'} σε ένα αριθμητικό παράγει έναν φανταστικό αριθμό (έναν μιγαδικό αριθμό με μηδενικό πραγματικό μέρος) το οποίο μπορείτε να προσθέσετε σε έναν ακέραιο ή κινητής υποδιαστολής για να πάρετε έναν μιγαδικό αριθμό με πραγματικό και φανταστικό μέρος.

Μπορούν να χρησιμοποιηθούν οι κατασκευαστές @ref{326,,int()}, @ref{327,,float()} και @ref{328,,complex()} για να παράγουν αριθμούς συγκεκριμένου τύπου.

@geindex αριθμητικό
@geindex ενσωματωμένες (built-in) συναρτήσεις;int
@geindex ενσωματωμένες (built-in) συναρτήσεις;float
@geindex ενσωματωμένες (built-in) συναρτήσεις;complex
@geindex τελεστής;+ (συν)
@geindex + (συν);τελεστής unary
@geindex + (συν);δυαδικός τελεστής
@geindex τελεστής;- (πλην)
@geindex - (πλην);τελεστής unary
@geindex - (πλην);δυαδικός τελεστής
@geindex τελεστής;* (αστερίσκος)
@geindex τελεστής;/ (κάθετος)
@geindex τελεστής;//
@geindex τελεστής;% (τοις εκατό)
@geindex τελεστής;**
@anchor{library/stdtypes stdtypes-mixed-arithmetic}@anchor{265f}
Python fully supports mixed arithmetic: when a binary arithmetic operator has
operands of different built-in numeric types, the operand with the «narrower»
type is widened to that of the other:


@itemize *

@item 
If both arguments are complex numbers, no conversion is performed;

@item 
if either argument is a complex or a floating-point number, the other is
converted to a floating-point number;

@item 
otherwise, both must be integers and no conversion is necessary.
@end itemize

Arithmetic with complex and real operands is defined by the usual mathematical
formula, for example:

@example
x + complex(u, v) = complex(x + u, v)
x * complex(u, v) = complex(x * u, x * v)
@end example

Μια σύγκριση μεταξύ αριθμών διαφορετικών τύπων συμπεριφέρεται σαν να συγκρίνονται οι ακριβείς τιμές αυτών των αριθμών. @footnote{
Σαν συνέπεια, η λίστα @code{[1, 2]} θεωρείται ίση με @code{[1.0, 2.0]}, και ομοίως για πλειάδες (tuples).
}

Όλοι οι αριθμητικοί τύποι (εκτός των μιγαδικών) υποστηρίζουν τις ακόλουθες πράξεις (για προτεραιότητες των πράξεων, βλέπε @ref{26e1,,Operator precedence}):


@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Πράξη

@tab

Αποτέλεσμα

@tab

Σημειώσεις

@tab

Ολόκληρη τεκμηρίωση

@item

@code{x + y}

@tab

άθροισμα του `x' και `y'

@tab

@tab

@item

@code{x - y}

@tab

διαφορά του `x' και `y'

@tab

@tab

@item

@code{x * y}

@tab

γινόμενο των `x' και `y'

@tab

@tab

@item

@code{x / y}

@tab

πηλίκο των `x' και `y'

@tab

@tab

@item

@code{x // y}

@tab

ακέραιο μέρος του πηλίκου των `x' και `y'

@tab

(1)(2)

@tab

@item

@code{x % y}

@tab

υπόλοιπο του @code{x / y}

@tab

(2)

@tab

@item

@code{-x}

@tab

`x' αρνητικό

@tab

@tab

@item

@code{+x}

@tab

`x' αμετάβλητο

@tab

@tab

@item

@code{abs(x)}

@tab

απόλυτη τιμή ή μέγεθος του `x'

@tab

@tab

@ref{227c,,abs()}

@item

@code{int(x)}

@tab

μετατροπή του `x' σε ακέραιο

@tab

(3)(6)

@tab

@ref{326,,int()}

@item

@code{float(x)}

@tab

μετατροπή του `x' σε κινητής υποδιαστολής

@tab

(4)(6)

@tab

@ref{327,,float()}

@item

@code{complex(re, im)}

@tab

ένας μιγαδικός αριθμός με πραγματικό μέρος `re', φανταστικό μέρος `im'. Το `im' μετατρέπεται αυτόματα σε μηδέν.

@tab

(6)

@tab

@ref{328,,complex()}

@item

@code{c.conjugate()}

@tab

συζυγές του μιγαδικού αριθμού `c'

@tab

@tab

@item

@code{divmod(x, y)}

@tab

το ζευγάρι @code{(x // y, x % y)}

@tab

(2)

@tab

@ref{d6a,,divmod()}

@item

@code{pow(x, y)}

@tab

`x' σε δύναμη του `y'

@tab

(5)

@tab

@ref{441,,pow()}

@item

@code{x ** y}

@tab

`x' σε δύναμη του `y'

@tab

(5)

@tab

@end multitable


@geindex λειτουργίες on;αριθμητικό;τύποι
@geindex conjugate() (μέθοδος μιγαδικών αριθμών)

Σημειώσεις:


@enumerate 

@item 
Αναφέρεται επίσης ως διαίρεση ακέραιου αριθμού. Για τελεστές τύπου @ref{326,,int}, το αποτέλεσμα έχει τύπο @code{int}. Για τελεστές τύπου @ref{327,,float}, το αποτέλεσμα έχει τύπο @code{float}. Γενικά, το αποτέλεσμα είναι ένας ολόκληρος ακέραιος αριθμός, αν και ο τύπος του αποτελέσματος δεν είναι απαραίτητα @code{int}. Το αποτέλεσμα είναι πάντα στρογγυλεμένο προς το μείον άπειρο: @code{1//2} είναι @code{0}, @code{(-1)//2} είναι @code{-1}, @code{1//(-2)} είναι @code{-1}, και @code{(-1)//(-2)} είναι @code{0}.

@item 
Όχι για μιγαδικούς αριθμούς. Αντίθετα μετατρέψτε σε float χρησιμοποιώντας @ref{227c,,abs()} εάν είναι εφαρμόσιμο.

@item 
@geindex module;math
@geindex floor() (στο module math)
@geindex ceil() (στο module math)
@geindex trunc() (στο module math)
@geindex αριθμητικό;μετατροπές

Η μετατροπή από @ref{327,,float} σε @ref{326,,int} περικόπτει, απορρίπτοντας το κλασματικό μέρος. Δείτε τις συναρτήσεις @ref{1760,,math.floor()} και @ref{1761,,math.ceil()} για εναλλακτικές μετατροπές.

@item 
το float δέχεται επίσης τις συμβολοσειρές (strings) «nan» και «inf» με ένα προαιρετικό πρόθεμα «+» ή «-» για το Not a Number (NaN - Όχι αριθμός) και θετικό ή αρνητικό άπειρο.

@item 
Η Python ορίζει το @code{pow(0, 0)} και το @code{0 ** 0} ως @code{1}, όπως συνηθίζεται για τις γλώσσες προγραμματισμού.

@item 
Τα αριθμητικά κυριολεκτικά (numeric literals) που γίνονται δεκτά περιλαμβάνουν τα ψηφία @code{0} έως @code{9} ή οποιοδήποτε ισοδύναμο Unicode (σημεία κώδικα με την ιδιότητα @code{Nd}).

Δείτε το Thε Unicode Standard@footnote{https://unicode.org/Public/UNIDATA/extracted/DerivedNumericType.txt} για μια πλήρη λίστα σημείων κώδικα με το @code{Nd} property.
@end enumerate

Όλοι οι τύποι @ref{27ec,,numbers.Real} (@ref{326,,int} και @ref{327,,float}) επίσης περιλαμβάνουν τις ακόλουθες λειτουργίες:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Πράξη

@tab

Αποτέλεσμα

@item

@ref{1762,,math.trunc(x)}

@tab

`x' μετατρέπεται σε @ref{25ff,,Integral}

@item

@ref{167f,,round(x[@comma{} n])}

@tab

`x' στρογγυλοποιημένο σε `n' ψηφία, στρογγυλοποιώντας το μισό σε ζυγό. Εάν το `n' παραλειφθεί, το default του είναι το 0.

@item

@ref{1760,,math.floor(x)}

@tab

το μεγαλύτερο @ref{25ff,,Integral} <= `x'

@item

@ref{1761,,math.ceil(x)}

@tab

το μικρότερο @ref{25ff,,Integral} >= `x'

@end multitable


Για περαιτέρω αριθμητικές πράξεις δείτε τα modules @ref{91,,math} και @ref{19,,cmath}.

@c XXXJH exceptions: overflow (when? what operations?) zerodivision

@menu
* Bitwise Πράξεις σε Ακέραιους Τύπους:: 
* Περαιτέρω Μέθοδοι των Ακέραιων Τύπων:: 
* Περαιτέρω Μέθοδοι για Float:: 
* Περαιτέρω Μέθοδοι για Μιγαδικούς:: 
* Κατακερματισμός των αριθμητικών τύπων:: 

@end menu

@node Bitwise Πράξεις σε Ακέραιους Τύπους,Περαιτέρω Μέθοδοι των Ακέραιων Τύπων,,Αριμθητικοί Τύποι — int float complex
@anchor{library/stdtypes bitstring-ops}@anchor{27ed}@anchor{library/stdtypes bitwise-operations-on-integer-types}@anchor{27ee}
@subsubsection Bitwise Πράξεις σε Ακέραιους Τύπους


@geindex λειτουργίες on;ακέραιος;τύποι
@geindex δυαδικά;λειτουργίες
@geindex μετατόπιση (shifting);λειτουργίες
@geindex συγκάλυψη (masking);λειτουργίες
@geindex τελεστής;| (κάθετη μπάρα)
@geindex τελεστής;^ (caret)
@geindex τελεστής;& (ampersand)
@geindex τελεστής;<<
@geindex τελεστής;>>
@geindex τελεστής;~ (περισπωμένη)

Οι πράξεις bitwise έχουν νόημα μόνο για ακέραιους αριθμούς. Το αποτέλεσμα των bitwise πράξεων υπολογίζεται σαν να εκτελείται σε συμπλήρωμα ως προς δύο με άπειρο αριθμό bits πρόσημου.

Οι προτεραιότητες των δυαδικών πράξεων bitwise είναι όλες χαμηλότερες από τις αριθμητικές πράξεις και υψηλότερες από τις συγκρίσεις· η μοναδιαία πράξη @code{~} έχει την ίδια προτεραιότητα με τις άλλες μοναδιαίες αριθμητικές πράξεις (@code{+} και @code{-}).

Αυτός ο πίνακας παραθέτει όλες τις bitwise πράξεις ταξινομημένες σε αύξουσα σειρά:


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 
@headitem

Πράξη

@tab

Αποτέλεσμα

@tab

Σημειώσεις

@item

@code{x | y}

@tab

bitwise `or' των `x' και `y'

@tab

(4)

@item

@code{x ^ y}

@tab

bitwise `exclusive or' των `x' και `y'

@tab

(4)

@item

@code{x & y}

@tab

bitwise `and' των `x' και `y'

@tab

(4)

@item

@code{x << n}

@tab

`x' ολισθημένο (shifted) αριστερά κατά `n' bits

@tab

(1)(2)

@item

@code{x >> n}

@tab

`x' ολισθημένο (shifted) δεξιά κατά `n' bits

@tab

(1)(3)

@item

@code{~x}

@tab

τα bits του `x' αντιστραμμένα

@tab

@end multitable


Σημειώσεις:


@enumerate 

@item 
Οι μετρήσεις αρνητικών ολισθήσεων (negative shift) είναι άκυρες και κάνουν raise @ref{277,,ValueError}.

@item 
Μια αριστερή ολίσθηση (shift) κατά `n' bits ισοδυναμεί με πολλαπλασιασμό με @code{pow(2, n)}.

@item 
Μια δεξιά ολίσθηση (shift) κατά `n' bits ισοδυναμεί με διαίρεση πατώματος με @code{pow(2, n)}.

@item 
Η εκτέλεση αυτών των υπολογισμών με τουλάχιστον ένα επιπλέον bit επέκτασης πρόσημου σε μια αναπαράσταση ενός πεπερασμένου συμπληρώματος ως προς δύο (ένα ωφέλιμο bit-width @code{1 + max(x.bit_length(), y.bit_length())} ή περισσότερο) είναι αρκετό για να πάρει το ίδιο αποτέλεσμα σαν να υπήρχε ένας άπειρος αριθμός bits πρόσημου.
@end enumerate

@node Περαιτέρω Μέθοδοι των Ακέραιων Τύπων,Περαιτέρω Μέθοδοι για Float,Bitwise Πράξεις σε Ακέραιους Τύπους,Αριμθητικοί Τύποι — int float complex
@anchor{library/stdtypes additional-methods-on-integer-types}@anchor{27ef}
@subsubsection Περαιτέρω Μέθοδοι των Ακέραιων Τύπων


Ο τύπος int υλοποιεί την @ref{25ff,,numbers.Integral} @ref{155f,,abstract base class}. Επιπλέον, παρέχει μερικές ακόμη μεθόδους:

@geindex bit_length() (μέθοδος της int)
@anchor{library/stdtypes int bit_length}@anchor{27f0}
@deffn {Μέθοδος} int.bit_length ()

Επιστρέφει τον αριθμό των bits που είναι απαραίτητος για να αναπαραστήσει έναν ακέραιο σε δυαδικό, αποκλείοντας το πρόσημο και τα αρχικά μηδέν:

@example
>>> n = -37
>>> bin(n)
'-0b100101'
>>> n.bit_length()
6
@end example

Πιο συγκεκριμένα, εάν το @code{x} είναι μη μηδενικό, τότε το @code{x.bit_length()} είναι μοναδικός θετικός αριθμός @code{k} έτσι ώστε @code{2**(k-1) <= abs(x) < 2**k}. Ισοδύναμα, όταν το @code{abs(x)} είναι αρκετά μικρό για να έχει ένα σωστά στρογγυλοποιημένο λογάριθμο, τότε @code{k = 1 + int(log(abs(x), 2))}. Εάν το @code{x} είναι μηδέν, τότε το @code{x.bit_length()} επιστρέφει @code{0}.

Ισοδύναμο με:

@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


Added in version 3.1.

@end deffn

@geindex bit_count() (μέθοδος της int)
@anchor{library/stdtypes int bit_count}@anchor{bac}
@deffn {Μέθοδος} int.bit_count ()

Επιστρέφει τον αριθμό των μονάδων στην δυαδική αναπαράσταση της απόλυτης τιμής του ακεραίου. Αυτό είναι επίσης γνωστό ως το μέτρημα πληθυσμού (population count). Παράδειγμα:

@example
>>> n = 19
>>> bin(n)
'0b10011'
>>> n.bit_count()
3
>>> (-n).bit_count()
3
@end example

Ισοδύναμο με:

@example
def bit_count(self):
    return bin(self).count("1")
@end example


Added in version 3.10.

@end deffn

@geindex to_bytes() (μέθοδος της int)
@anchor{library/stdtypes int to_bytes}@anchor{1e29}
@deffn {Μέθοδος} int.to_bytes (length=1, byteorder='big', *, signed=False)

Επιστρέφει ένα πίνακα από bytes που αναπαριστούν έναν ακέραιο.

@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

Ο ακέραιος αναπαρίσταται χρησιμοποιώντας `length' bytes και η προεπιλεγμένη του τιμή (default) είναι 1.  Ένα @ref{c57,,OverflowError} γίνεται raise αν ο ακέραιος αριθμός δεν δύναται να αναπαρασταθεί με τον αριθμό bytes που δόθηκε.

Το όρισμα `byteorder' καθορίζει τη σειρά των byte που χρησιμοποιούνται για την αναπαράσταση του ακέραιου αριθμού, και έχουν προεπιλεγμένη τιμή (default) @code{"big"}. Εάν το `byteorder' είναι @code{"big"}, το πιο σημαντικό byte βρίσκεται στην αρχή του πίνακα των bytes. Εάν το `byteorder' είναι @code{"little"}, το πιο σημαντικό byte βρίσκεται στο τέλος του πίνακα των bytes.

Το όρισμα `signed' καθορίζει εάν το συμπλήρωμα ως προς δύο χρησιμοποιείται για να αντιπροσωπεύσει τον ακέραιο. Εάν το `signed' είναι @code{False} και έχει δοθεί ένας αρνητικός ακέραιος, γίνεται raise ένα @ref{c57,,OverflowError}. Η προεπιλεγμένη τιμή (default) για το `signed' είναι @code{False}.

Οι προεπιλεγμένες τιμές (defaults) μπορούν να χρησιμοποιηθούν για να μετατρέψουν βολικά έναν ακέραιο σε ένα μόνο byte αντικείμενο:

@example
>>> (65).to_bytes()
b'A'
@end example

Ωστόσο, όταν χρησιμοποιείτε προεπιλεγμένα ορίσματα, μην προσπαθήσετε να μετατρέψετε μια τιμή μεγαλύτερη από 255 ή διαφορετικά θα λάβετε ένα @ref{c57,,OverflowError}.

Ισοδύναμο με:

@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


Added in version 3.2.



Άλλαξε στην έκδοση 3.11: Προστιθέμενες προεπιλεγμένες τιμές (defaults) ορίσματος για @code{length} και @code{byteorder}.

@end deffn

@geindex from_bytes() (μέθοδος κλάσης της int)
@anchor{library/stdtypes int from_bytes}@anchor{198e}
@deffn {Μέθοδος} classmethod int.from_bytes (bytes, byteorder='big', *, signed=False)

Επιστρέφει έναν ακέραιο που αναπαρίσταται από τον δοσμένο πίνακα των bytes.

@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

Το όρισμα `bytes' πρέπει είτε να είναι ένα @ref{436,,bytes-like object} είτε ένα iterable που παράγει bytes.

Το όρισμα `byteorder' καθορίζει τη σειρά byte που χρησιμοποιείται για την αναπαράσταση του ακέραιου αριθμού, και η προεπιλεγμένη τιμή (default) είναι @code{"big"}. Εάν το `byteorder' είναι @code{"big"}, το το πιο σημαντικό byte βρίσκεται στην αρχή του πίνακα των bytes. Εάν το `byteorder' είναι @code{"little"}, το πιο σημαντικό byte βρίσκεται στο τέλος του πίνακα των bytes. Για να ζητήσετε την εγγενή σειρά των bytes του host συστήματος, χρησιμοποιήστε το @ref{27f1,,sys.byteorder} ως τιμή της σειράς byte.

Το όρισμα `signed' υποδεικνύει εάν το συμπλήρωμα ως προς δύο χρησιμοποιείται για να αντιπροσωπεύσει τον ακέραιο.

Ισοδύναμο με:

@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


Added in version 3.2.



Άλλαξε στην έκδοση 3.11: Προστιθέμενη προεπιλεγμένη τιμή (default) ορίσματος για το @code{byteorder}.

@end deffn

@geindex as_integer_ratio() (μέθοδος της int)
@anchor{library/stdtypes int as_integer_ratio}@anchor{d91}
@deffn {Μέθοδος} int.as_integer_ratio ()

Επιστρέφει ένα ζεύγος ακεραίων των οποίων η αναλογία είναι ίση με τον αρχικό ακέραιο και έχει θετικό παρονομαστή. Ο ακέραιος λόγος ακεραίων (ολόκληρων αριθμών) είναι πάντα ο ακέραιος αριθμός ως αριθμητής και το @code{1} ως παρονομαστής.


Added in version 3.8.

@end deffn

@geindex is_integer() (μέθοδος της int)
@anchor{library/stdtypes int is_integer}@anchor{1cea}
@deffn {Μέθοδος} int.is_integer ()

Επιστρέφει @code{True}. Υπάρχει για συμβατότητα τύπου duck με @ref{27f2,,float.is_integer()}.


Added in version 3.12.

@end deffn

@node Περαιτέρω Μέθοδοι για Float,Περαιτέρω Μέθοδοι για Μιγαδικούς,Περαιτέρω Μέθοδοι των Ακέραιων Τύπων,Αριμθητικοί Τύποι — int float complex
@anchor{library/stdtypes additional-methods-on-float}@anchor{27f3}
@subsubsection Περαιτέρω Μέθοδοι για Float


Ο τύπος float (κινητής υποδιαστολής) υλοποιεί την @ref{27ec,,numbers.Real} @ref{155f,,abstract base class}. Ο float έχει επίσης τις ακόλουθες πρόσθετες μεθόδους.

@geindex from_number() (μέθοδος κλάσης της float)
@anchor{library/stdtypes float from_number}@anchor{437}
@deffn {Μέθοδος} classmethod float.from_number (x)

Μέθοδος κλάσης για την επιστροφή ενός αριθμού κινητής υποδιαστολής που κατασκευάζεται από έναν αριθμό `x'.

Εάν το όρισμα είναι ακέραιος ή αριθμός κινητής υποδιαστολής, επιστρέφεται ένας αριθμός κινητής υποδιαστολής με την ίδια τιμή (εντός της ακρίβειας κινητής υποδιαστολής της Python). Εάν το όρισμα βρίσκεται εκτός του εύρους ενός Python float, θα κάνει raise μια @ref{c57,,OverflowError}.

Για ένα γενικό αντικείμενο Python @code{x}, @code{float.from_number(x)} ανατίθεται στο @code{x.__float__()}. Εάν η @ref{d92,,__float__()} δεν έχει οριστεί, τότε επιστρέφει στη @ref{43d,,__index__()}.


Added in version 3.14.

@end deffn

@geindex as_integer_ratio() (μέθοδος της float)
@anchor{library/stdtypes float as_integer_ratio}@anchor{22f1}
@deffn {Μέθοδος} float.as_integer_ratio ()

Επιστρέφει ένα ζεύγος ακεραίων των οποίων η αναλογία είναι ακριβώς ίση με το αρχικό float. Ο λόγος είναι στο χαμηλότερο επίπεδο και έχει θετικό παρονομαστή. Κάνει raise @ref{c57,,OverflowError} στα άπειρα και ένα @ref{277,,ValueError} για NaNs.
@end deffn

@geindex is_integer() (μέθοδος της float)
@anchor{library/stdtypes float is_integer}@anchor{27f2}
@deffn {Μέθοδος} float.is_integer ()

Επιστρέφει @code{True} εάν το float instance είναι πεπερασμένο με ακέραια τιμή και @code{False} διαφορετικά:

@example
>>> (-2.0).is_integer()
True
>>> (3.2).is_integer()
False
@end example
@end deffn

Δύο μέθοδοι υποστηρίζουν τη μετατροπή από και προς δεκαεξαδικές συμβολοσειρές (strings). Αφού τα floats της Python αποθηκεύονται εσωτερικά ως δυαδικοί αριθμοί, η μετατροπή ενός float προς ή από μια `δεκαδική' συμβολοσειρά συνήθως περιλαμβάνει ένα μικρό σφάλμα στρογγυλοποίησης. Αντιθέτως, οι δεκαεξαδικές συμβολοσειρές επιτρέπουν ακριβή αναπαράσταση και συγκεκριμενοποίηση των αριθμών κινητής υποδιαστολής. Αυτό μπορεί να είναι χρήσιμο κατά το debugging και στην αριθμητική.

@geindex hex() (μέθοδος της float)
@anchor{library/stdtypes float hex}@anchor{22f2}
@deffn {Μέθοδος} float.hex ()

Επιστρέφει μια αναπαράσταση ενός αριθμού κινητής υποδιαστολής ως δεκαεξαδική συμβολοσειρά (string).  Για πεπερασμένους αριθμούς κινητής υποδιαστολής, αυτή η αναπαράσταση θα περιλαμβάνει πάντα ένα προπορευόμενο @code{0x} και ένα τελευταίο @code{p} και εκθέτη.
@end deffn

@geindex fromhex() (μέθοδος κλάσης της float)
@anchor{library/stdtypes float fromhex}@anchor{27f4}
@deffn {Μέθοδος} classmethod float.fromhex (s)

Μέθοδος κλάσης για την επιστροφή του float που αντιπροσωπεύεται από μια δεκαεξαδική συμβολοσειρά (string) `s'.  Η συμβολοσειρά `s' μπορεί να έχει κενό διάστημα που στην αρχή ή το τέλος.
@end deffn

Σημειώστε ότι το @ref{22f2,,float.hex()} είναι ένα instance method, ενώ το @ref{27f4,,float.fromhex()} είναι μια μέθοδος κλάσης.

Μια δεκαεξαδική συμβολοσειρά (string) έχει τη μορφή:

@example
[sign] ['0x'] integer ['.' fraction] ['p' exponent]
@end example

όπου το προαιρετικό @code{sign} μπορεί να είναι είτε @code{+} ή @code{-}, @code{integer} και @code{fraction} είναι συμβολοσειρές (strings) δεκαεξαδικών ψηφίων και ο @code{exponent} (εκθέτης) είναι ένας δεκαδικός ακέραιος με προαιρετικό πρόσημο. Τα πεζά ή κεφαλαία δεν είναι σημαντικά και πρέπει να υπάρχει τουλάχιστον ένα δεκαεξαδικό ψηφίο είτε στον ακέραιο είτε στο κλάσμα. Αυτή η σύνταξη είναι παρόμοια με τη σύνταξη που καθορίζεται στην ενότητα 6.4.4.2 του προτύπου C99, καθώς και στη σύνταξη που χρησιμοποιείται στην Java 1.5 και μετά. Ιδιαίτερα, η έξοδος του @ref{22f2,,float.hex()} μπορεί να χρησιμοποιηθεί ως δεκαεξαδικό Κυριολεκτική κινητής υποδιαστολής σε κώδικα C ή Java, και παράχθηκαν δεκαεξαδικές συμβολοσειρές με τον χαρακτήρα μορφής @code{%a} της C ή το @cite{Double.toHexString} της Java είναι αποδεκτά από το @ref{27f4,,float.fromhex()}.

Σημειώστε ότι ο εκθέτης είναι γραμμένος με δεκαδικό και όχι δεκαεξαδικό και ότι δίνει τη δύναμη του 2 με την οποία πολλαπλασιάζεται ο συντελεστής. Για παράδειγμα, η δεκαεξαδική συμβολοσειρά (string) @code{0x3.a7p10} αντιπροσωπεύει τον αριθμό κινητής υποδιαστολής @code{(3 + 10./16 + 7./16**2) * 2,0**10}, ή @code{3740,0}:

@example
>>> float.fromhex('0x3.a7p10')
3740.0
@end example

Η εφαρμογή της αντίστροφης μετατροπής σε @code{3740.0} δίνει μία διαφορετική δεκαεξαδική συμβολοσειρά (string) που αντιπροσωπεύει τον ίδιο αριθμό:

@example
>>> float.hex(3740.0)
'0x1.d380000000000p+11'
@end example

@node Περαιτέρω Μέθοδοι για Μιγαδικούς,Κατακερματισμός των αριθμητικών τύπων,Περαιτέρω Μέθοδοι για Float,Αριμθητικοί Τύποι — int float complex
@anchor{library/stdtypes additional-methods-on-complex}@anchor{27f5}
@subsubsection Περαιτέρω Μέθοδοι για Μιγαδικούς


Ο τύπος @code{complex} υλοποιεί την @ref{27f6,,numbers.Complex} @ref{155f,,abstract base class}. Η @code{complex} έχει επίσης τις ακόλουθες πρόσθετε μεθόδους.

@geindex from_number() (μέθοδος κλάσης της complex)
@anchor{library/stdtypes complex from_number}@anchor{438}
@deffn {Μέθοδος} classmethod complex.from_number (x)

Μέθοδος κλάσης για τη μετατροπή ενός αριθμούς σε ένα μιγαδικό αριθμός.

Για ένα γενικό αντικείμενο Python @code{x}, @code{complex.from_number(x)} ανατίθεται στο @code{x.__complex__()}. Εάν η @ref{9de,,__complex__()} δεν έχει οριστεί, τότε επιστρέφει @ref{d92,,__float__()}. Εάν η @code{__float__()} δεν έχει οριστεί, τότε επιστρέφει στη @ref{43d,,__index__()}.


Added in version 3.14.

@end deffn

@node Κατακερματισμός των αριθμητικών τύπων,,Περαιτέρω Μέθοδοι για Μιγαδικούς,Αριμθητικοί Τύποι — int float complex
@anchor{library/stdtypes hashing-of-numeric-types}@anchor{27f7}@anchor{library/stdtypes numeric-hash}@anchor{27f8}
@subsubsection Κατακερματισμός των αριθμητικών τύπων


Για αριθμούς @code{x} και @code{y}, πιθανώς διαφορετικών τύπων, είναι προαπαιτούμενο ότι @code{hash(x) == hash(y)} όποτε @code{x == y} (δείτε την τεκμηρίωση για την μέθοδο @ref{ec1,,__hash__()} για περισσότερες λεπτομέρειες). Για την ευκολότερη εφαρμογή και αποτελεσματικότητα σε ένα εύρος αριθμητικών τύπων (συμπεριλαμβανομένων των @ref{326,,int}, @ref{327,,float}, @ref{1c2,,decimal.Decimal} και @ref{1c3,,fractions.Fraction}) o κατακερματισμός της Python για αριθμητικούς τύπους βασίζεται σε μία μόνο μαθηματική συνάρτηση που ορίζεται για οποιονδήποτε ρητό αριθμό, και ως εκ τούτου ισχύει για όλα τα instances @code{int} και @code{fractions.Fraction} και όλα πεπερασμένα instances @code{float} και @code{decimal.Decimal}. Ουσιαστικά, αυτή η συνάρτηση δίνεται από το modulo μείωσης @code{P} για ένα σταθερό πρώτο @code{P}. Η τιμή του @code{P} διατίθεται στην Python ως χαρακτηριστικό @ref{27f9,,modulus} του @ref{13a8,,sys.hash_info}.

Αυτή τη στιγμή, ο πρώτος που χρησιμοποιείται είναι @code{P = 2**31 - 1} σε μηχανήματα με μήκους 32-bit C και @code{P = 2**61 - 1} σε μηχανήματα με μήκους 64-bit C.

Εδώ οι κανόνες λεπτομερώς:


@itemize -

@item 
Αν το @code{x = m / n} είναι ένας μη αρνητικός ρητός αριθμός και το @code{n} δεν διαιρείται από @code{P}, ορίστε το @code{hash(x)} ως @code{m * invmod(n, P) % P}, όπου το @code{invmod(n, P)} μας δίνει το αντίστροφο του modulo @code{n} @code{P}.

@item 
Αν το @code{x = m / n} είναι ένας μη αρνητικός ρητός αριθμός και το @code{n} διαιρείται με το @code{P} (αλλά το @code{m} όχι) τότε το @code{n} δεν έχει αντίστροφο modulo @code{P} και ο κανόνας παραπάνω δεν ισχύει. Σε αυτήν την περίπτωση ορίστε το @code{hash(x)} ως σταθερή τιμή @code{sys.hash_info.inf}.

@item 
Αν @code{x = m / n} είναι ένας αρνητικός ρητός αριθμός τότε το @code{hash(x)} ορίζεται ως @code{-hash(-x)}.  Αν το hash που προκύπτει είναι @code{-1}, αντικαθίσταται με @code{-2}.

@item 
Οι συγκεκριμένες τιμές των @code{sys.hash_info.inf} και @code{-sys.hash_info.inf} χρησιμοποιούνται ως τιμές κατακερματισμού για το θετικό άπειρο ή το αρνητικό άπειρο (αντίστοιχα).

@item 
Για έναν @ref{328,,complex} αριθμό @code{z}, οι τιμές κατακερματισμού των πραγματικών και φανταστικών μερών συνδυάζονται με τον υπολογισμό @code{hash(z.real) + sys.hash_info.imag * hash(z.imag)}, μειωμένο modulo @code{2**sys.hash_info.width} έτσι ώστε να βρίσκεται στο @code{range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1))}.  Και πάλι, αν το αποτέλεσμα είναι @code{-1}, αντικαθίσταται με @code{-2}.
@end itemize

Για να αποσαφηνίσουμε τους παραπάνω κανόνες, εδώ είναι ένα παράδειγμα κώδικα της Python, ισοδύναμο με το built-in hash, για τον υπολογισμό του hash ενός ρητού αριθμού, @ref{327,,float}, ή @ref{328,,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{27fa}
@node Τύπος Boolean - bool,Τύποι Iterator,Αριμθητικοί Τύποι — int float complex,Τύποι Built-in
@anchor{library/stdtypes boolean-type-bool}@anchor{27fb}@anchor{library/stdtypes typebool}@anchor{27ba}
@subsection Τύπος Boolean - @code{bool}


Οι λογικές τιμές (Booleans) αντιπροσωπεύουν τιμές αλήθειας. Ο τύπος @ref{5ef,,bool} έχει ακριβώς δύο σταθερές τιμές: @code{True} και @code{False}.

@geindex False
@geindex True
@geindex Boolean;τιμές

Η ενσωματωμένη συνάρτηση @ref{5ef,,bool()} μετατρέπει οποιαδήποτε τιμή σε λογική (boolean), αν η τιμή μπορεί να ερμηνευτεί ως τιμή αλήθειας (βλέπε παραπάνω ενότητα @ref{1a80,,Έλεγχος Έγκυρης Τιμής}).

Για λογικές πράξεις, χρησιμοποιήστε τους τελεστές @ref{27e7,,boolean} @code{and}, @code{or} και @code{not}. Κατά την εφαρμογή των bitwise τελεστών @code{&}, @code{|}, @code{^} σε δύο booleans, επιστρέφουν ένα bool ισοδύναμο με τις λογικές πράξεις «and», «or», «xor». Ωστόσο, οι λογικοί τελεστές @code{and}, @code{or} και @code{!=} θα πρέπει να προτιμώνται έναντι των @code{&}, @code{|} και @code{^}.


Αποσύρθηκε στην έκδοση 3.12: Η χρήση του bitwise inversion τελεστή @code{~} είναι ξεπερασμένη και κάνει raise ένα σφάλμα στην Python 3.16.


Η @ref{5ef,,bool} είναι υποκλάση της @ref{326,,int} (βλέπε @ref{21c9,,Αριμθητικοί Τύποι — int@comma{} float@comma{} complex}). Σε πολλά αριθμητικά περιβάλλοντα, τα @code{False} και @code{True} συμπεριφέρονται όπως οι ακέραιοι αριθμοί 0 και 1, αντίστοιχα. Ωστόσο, δεν συνιστάται να βασίζεστε σε αυτό· πιο αναλυτικά κάντε μετατροπή χρησιμοποιώντας τη @ref{326,,int()} αντ” αυτού.

@node Τύποι Iterator,Τύποι Ακολουθίας Sequence — list tuple range,Τύπος Boolean - bool,Τύποι Built-in
@anchor{library/stdtypes iterator-types}@anchor{27fc}@anchor{library/stdtypes typeiter}@anchor{27d0}
@subsection Τύποι Iterator


@geindex πρωτόκολλο iterator
@geindex πρωτόκολλο;iterator
@geindex sequence;iteration
@geindex container;iteration over

Η Python υποστηρίζει την έννοια της επανάληψης σε containers.  Αυτό υλοποιείται χρησιμοποιώντας δύο διαφορετικές μεθόδους· αυτές χρησιμοποιούνται για να επιτρέψουν σε κλάσεις που ορίζονται από το χρήστη να να υποστηρίζουν την επανάληψη.  Οι ακολουθίες (sequences), που περιγράφονται παρακάτω με περισσότερες λεπτομέρειες, πάντα υποστηρίζουν τις μεθόδους επανάληψης.

Μια μέθοδος πρέπει να οριστεί για τα container αντικείμενα ώστε να παρέχει @ref{15ce,,iterable} υποστήριξη:

@c XXX duplicated in reference/datamodel!

@geindex __iter__() (μέθοδος της container)
@anchor{library/stdtypes container __iter__}@anchor{229a}
@deffn {Μέθοδος} container.__iter__ ()

Επιστρέφει ένα αντικείμενο @ref{6ce,,iterator}.  Το αντικείμενο απαιτείται να υποστηρίζει το πρωτόκολλο επαναλήψεων που περιγράφεται παρακάτω.  Εάν ένας container υποστηρίζει διαφορετικούς τύπους της επανάληψης, μπορούν να παρασχεθούν πρόσθετες μέθοδοι για να ζητηθούν συγκεκριμένοι iterators για αυτούς τους τύπους επανάληψης.  (Ένα παράδειγμα αντικειμένου που υποστηρίζει πολλαπλές μορφές επανάληψης θα ήταν μια δενδρική δομή που υποστηρίζει και αμφότερες τις breadth-first και depth-first μορφές).  Αυτή η μέθοδος αντιστοιχεί στη μέθοδο @ref{1891,,tp_iter} της δομής τύπου για αντικείμενα Python στο API της Python/C.
@end deffn

Τα ίδια τα αντικείμενα επαναλήψεων απαιτείται να υποστηρίζουν τις ακόλουθες δύο μεθόδους, οι οποίες από κοινού αποτελούν το `iterator protocol':

@geindex __iter__() (μέθοδος της iterator)
@anchor{library/stdtypes iterator __iter__}@anchor{229d}
@deffn {Μέθοδος} iterator.__iter__ ()

Επιστρέφει το ίδιο το αντικείμενο @ref{6ce,,iterator}.  Αυτό απαιτείται ώστε να επιτραπεί η χρησιμοποίηση τόσο των containers, όσο και των iterators με τα statements @ref{321,,for} και @ref{323,,in}.  Αυτή η μέθοδος αντιστοιχεί στη δομή @ref{1891,,tp_iter} των αντικειμένων της Python στο Python/C API.
@end deffn

@geindex __next__() (μέθοδος της iterator)
@anchor{library/stdtypes iterator __next__}@anchor{1672}
@deffn {Μέθοδος} iterator.__next__ ()

Επιστρέφει το επόμενο στοιχείο από τον @ref{6ce,,iterator}.  Εάν δεν υπάρχουν άλλα στοιχεία, κάνει raise την εξαίρεση @ref{fba,,StopIteration}.  Αυτή η μέθοδος αντιστοιχεί στην δομή @ref{1892,,tp_iternext} των αντικειμένων της Python στο API της Python/C.
@end deffn

Η Python ορίζει διάφορα αντικείμενα iterator για την υποστήριξη της επανάληψης πάνω σε γενικούς και συγκεκριμένους τύπους ακολουθιών (sequences), λεξικά (dictionaries) και άλλες πιο εξειδικευμένες μορφές.  Οι συγκεκριμένοι τύποι δεν είναι σημαντικοί πέρα από την υλοποίησή του iterator πρωτοκόλλου.

Μόλις η μέθοδος @ref{1672,,__next__()} ενός iterator κάνει raise ένα @ref{fba,,StopIteration}, πρέπει να συνεχίσει να το κάνει σε επόμενες κλήσεις. Υλοποιήσεις που δεν υπακούν σε αυτή την ιδιότητα θεωρούνται εσφαλμένες.

@menu
* Τύποι Generator:: 

@end menu

@node Τύποι Generator,,,Τύποι Iterator
@anchor{library/stdtypes generator-types}@anchor{27fd}@anchor{library/stdtypes id3}@anchor{27fe}
@subsubsection Τύποι Generator


Οι @ref{1409,,generator}s της Python παρέχουν έναν βολικό τρόπο για να υλοποιήσετε το iterator πρωτόκολλο.  Εάν η μέθοδος @ref{102d,,__iter__()} ενός container αντικειμένου είναι υλοποιημένη ως generator, θα επιστρέψει αυτόματα ένα αντικείμενο iterator (τεχνικά, ένα αντικείμενο generator) που παρέχει τις @ref{229d,,__iter__()} και @ref{229e,,__next__()} μεθόδους. Περισσότερες πληροφορίες σχετικά με τους generators μπορείτε να βρείτε στην @ref{268f,,the documentation for the yield expression}.

@node Τύποι Ακολουθίας Sequence — list tuple range,Σύνοψη μεθόδων τύπου κειμένου και δυαδική ακολουθίας,Τύποι Iterator,Τύποι Built-in
@anchor{library/stdtypes sequence-types-list-tuple-range}@anchor{27ff}@anchor{library/stdtypes typesseq}@anchor{221d}
@subsection Τύποι Ακολουθίας (Sequence) — @code{list}, @code{tuple}, @code{range}


Υπάρχουν τρεις βασικοί τύποι ακολουθιών: lists (λίστες), tuples (πλειάδες) και range objects (αντικείμενα εύρους). Πρόσθετοι τύποι ακολουθίας προσαρμοσμένοι για την επεξεργασία @ref{27bd,,binary data} και @ref{21cd,,text strings} περιγράφονται σε ειδικές ενότητες.

@menu
* Κοινές Λειτουργίες Ακολουθιών (Sequences): Κοινές Λειτουργίες Ακολουθιών Sequences. 
* Τύποι Αμετάβλητων Ακολουθιών (Sequences): Τύποι Αμετάβλητων Ακολουθιών Sequences. 
* Τύποι Μεταβλητών Ακολουθιών (Sequences): Τύποι Μεταβλητών Ακολουθιών Sequences. 
* Λίστες: Λίστες<2>. 
* Πλειάδες (Tuples): Πλειάδες Tuples. 
* Εύρη (Ranges): Εύρη Ranges. 

@end menu

@node Κοινές Λειτουργίες Ακολουθιών Sequences,Τύποι Αμετάβλητων Ακολουθιών Sequences,,Τύποι Ακολουθίας Sequence — list tuple range
@anchor{library/stdtypes common-sequence-operations}@anchor{2800}@anchor{library/stdtypes typesseq-common}@anchor{2801}
@subsubsection Κοινές Λειτουργίες Ακολουθιών (Sequences)


@geindex αντικείμενο;sequence

Οι λειτουργίες του παρακάτω πίνακα υποστηρίζονται από τους περισσότερους τύπους ακολουθιών, τόσο μεταβλητών (mutable) όσο και αμετάβλητων (immutable). Η @ref{156d,,collections.abc.Sequence} ABC παρέχεται για να διευκολύνει τη σωστή υλοποίηση αυτών των πράξεων σε προσαρμοσμένους τύπους ακολουθίας.

Αυτός ο πίνακας απαριθμεί τις λειτουργίες ακολουθίας ταξινομημένες κατά αύξουσα προτεραιότητα.  Στον πίνακα, τα `s' και `t' είναι ακολουθίες του ίδιου τύπου, τα `n', `i', `j' και `k' είναι ακέραιοι αριθμοί και το `x' είναι ένα αυθαίρετο αντικείμενο που πληροί οποιονδήποτε τύπο και περιορισμούς τιμής που επιβάλλονται από το `s'.

Οι πράξεις @code{in} και @code{not in} έχουν τις ίδιες προτεραιότητες με τις πράξεις σύγκρισης. Οι πράξεις @code{+} (συνένωση) και @code{*} (επανάληψη) έχουν την ίδια προτεραιότητα με τις αντίστοιχες αριθμητικές πράξεις. @footnote{
Πρέπει να έχουν, αφού ο parser δεν μπορεί να ξεχωρίσει τον τύπο των τελεστών.
}

@geindex λειτουργίες on;sequence;τύποι
@geindex ενσωματωμένες (built-in) συναρτήσεις;len
@geindex ενσωματωμένες (built-in) συναρτήσεις;min
@geindex ενσωματωμένες (built-in) συναρτήσεις;max
@geindex concatenation;λειτουργία
@geindex επανάληψη;λειτουργία
@geindex subscript;λειτουργία
@geindex slice;λειτουργία
@geindex τελεστής;in
@geindex τελεστής;not in


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 
@headitem

Πράξη

@tab

Αποτέλεσμα

@tab

Σημειώσεις

@item

@code{x in s}

@tab

@code{True} αν ένα στοιχείο του `s' είναι ίσο με το `x', αλλιώς @code{False}

@tab

(1)

@item

@code{x not in s}

@tab

@code{False} αν ένα στοιχείο του `s' είναι ίσο με το `x', αλλιώς @code{True}

@tab

(1)

@item

@code{s + t}

@tab

η συνένωση του `s' και `t'

@tab

(6)(7)

@item

@code{s * n} ή @code{n * s}

@tab

ίσο με την πρόσθεση του `s' στον εαυτό του `n' φορές

@tab

(2)(7)

@item

@code{s[i]}

@tab

`i'ο στοιχείο του `s', αρχή το 0

@tab

(3)(8)

@item

@code{s[i:j]}

@tab

slice (υποσύνολο) του `s' από το `i' μέχρι το `j'

@tab

(3)(4)

@item

@code{s[i:j:k]}

@tab

slice (υποσύνολο) του `s' από το `i' μέχρι το `j' με βήμα `k'

@tab

(3)(5)

@item

@code{len(s)}

@tab

μήκος του `s'

@tab

@item

@code{min(s)}

@tab

μικρότερο αντικείμενο του `s'

@tab

@item

@code{max(s)}

@tab

μεγαλύτερο αντικείμενο του `s'

@tab

@end multitable


Οι ακολουθίες (sequences) του ίδιου τύπου υποστηρίζουν επίσης συγκρίσεις.  Ειδικότερα, τα tuples (πλειάδες) και οι λίστες συγκρίνονται λεξικογραφικά συγκρίνοντας τα αντίστοιχα στοιχεία. Αυτό σημαίνει ότι για να συγκρίνουμε ίσα, κάθε στοιχείο πρέπει να συγκρίνεται ως ίσο με το αντίστοιχό του, οι δύο ακολουθίες πρέπει να είναι του ίδιου τύπου και να έχουν το ίδιο μήκος.  (Για πλήρεις λεπτομέρειες δείτε την αναφορά @ref{26c7,,Comparisons}.)

@geindex loop;πάνω από μεταβλητή ακολουθίας
@geindex μεταβλητή ακολουθίας;loop over

Εμπρόσθιοι και αντίστροφοι iterators πάνω σε μεταβλητές ακολουθίες έχουν πρόσβαση σε τιμές χρησιμοποιώντας ένα δείκτη.  Αυτός ο δείκτης θα συνεχίσει να βαδίζει προς τα εμπρός (ή προς τα πίσω) ακόμα και αν η υποκείμενη ακολουθία μεταλλάσσεται.  Ο iterator τερματίζει μόνο όταν ένα @ref{18d7,,IndexError} ή ένα @ref{fba,,StopIteration} γίνει raise (ή όταν ο δείκτης πέσει κάτω από το μηδέν).

Σημειώσεις:


@enumerate 

@item 
Ενώ οι πράξεις @code{in} και @code{not in} χρησιμοποιούνται γενικά μόνο για απλό έλεγχο containment (αν στοιχείο περιέχεται σε μια δομή), ορισμένες εξειδικευμένες ακολουθίες (όπως όπως οι @ref{1df,,str}, @ref{1c7,,bytes} και @ref{1c6,,bytearray}) τις χρησιμοποιούν επίσης για subsequence testing (έλεγχο υποακολουθίας):

@example
>>> "gg" in "eggs"
True
@end example

@item 
Τιμές του `n' μικρότερες από το @code{0} αντιμετωπίζονται ως @code{0} (που δίνει μια κενή ακολουθία του ίδιου τύπου με `s').  Σημειώστε ότι τα στοιχεία της ακολουθίας `s' δεν αντιγράφονται· αναφέρονται πολλές φορές.  Αυτό συχνά στοιχειώνει τα άτομα που ξεκινούν με Python- σκεφτείτε:

@example
>>> lists = [[]] * 3
>>> lists
[[], [], []]
>>> lists[0].append(3)
>>> lists
[[3], [3], [3]]
@end example

Αυτό που συνέβη είναι ότι το @code{[[]]} είναι μια λίστα ενός στοιχείου που περιέχει μία κενή λίστα, οπότε και τα τρία στοιχεία της @code{[[]] * 3} είναι αναφορές σε αυτή τη μία κενή λίστα.  Η τροποποίηση οποιουδήποτε από τα στοιχεία της @code{lists} τροποποιεί αυτή τη μοναδική λίστα. Μπορείτε να δημιουργήσετε μια λίστα από διαφορετικές λίστες με αυτόν τον τρόπο:

@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

Περαιτέρω επεξήγηση είναι διαθέσιμη στο λήμμα FAQ @ref{2802,,Πως φτιάχνω μια πολυδιάστατη λίστα;}.

@item 
Εάν το `i' ή το `j' είναι αρνητικό, ο δείκτης είναι σχετικός με το τέλος της ακολουθίας `s': το @code{len(s) + i} ή το @code{len(s) + j} αντικαθίσταται.  Σημειώστε όμως ότι το @code{-0} εξακολουθεί να είναι @code{0}.

@item 
The slice of `s' from `i' to `j' is defined as the sequence of items with
index `k' such that @code{i <= k < j}.


@itemize *

@item 
If `i' is omitted or @code{None}, use @code{0}.

@item 
If `j' is omitted or @code{None}, use @code{len(s)}.

@item 
If `i' or `j' is less than @code{-len(s)}, use @code{0}.

@item 
If `i' or `j' is greater than @code{len(s)}, use @code{len(s)}.

@item 
If `i' is greater than or equal to `j', the slice is empty.
@end itemize

@item 
Το υποσύνολο (slice) του `s' από `i' έως `j' με βήμα `k' ορίζεται ως η ακολουθία των στοιχείων με δείκτη @code{x = i + n*k} τέτοια ώστε @code{0 <= n < (j-i)/k}.  Με άλλα λόγια, οι δείκτες είναι @code{i}, @code{i+k}, @code{i+2*k}, @code{i+3*k} και ούτω καθεξής, σταματώντας όταν φτάσουμε στο `j' (αλλά ποτέ δεν περιλαμβάνει το `j').  Όταν το `k' είναι θετικό, τα `i' και `j' μειώνονται σε @code{len(s)} αν είναι μεγαλύτερα. Όταν το `k' είναι αρνητικό, τα `i' και `j' μειώνονται σε @code{len(s) - 1} αν είναι μεγαλύτερα.  Εάν τα `i' ή `j' παραλείπονται ή είναι @code{None}, γίνονται τιμές «end» (το τέλος εξαρτάται από το πρόσημο του `k').  Σημειώστε ότι το `k' δεν μπορεί να είναι μηδέν. Εάν το `k' είναι @code{None}, αντιμετωπίζεται όπως το @code{1}.

@item 
Η συνένωση αμετάβλητων ακολουθιών (immutable sequences) οδηγεί πάντα σε ένα νέο αντικείμενο.  Αυτό σημαίνει ότι η δημιουργία μιας ακολουθίας με επαναλαμβανόμενη συνένωση θα έχει τετραγωνικό κόστος χρόνου εκτέλεσης (runtime cost) στο συνολικό μήκος της ακολουθίας.  Για να πάρετε ένα γραμμικό κόστος χρόνου εκτέλεσης (runtime cost), πρέπει να μεταβείτε σε μία από τις παρακάτω εναλλακτικές λύσεις:


@itemize *

@item 
αν συνενώνεται αντικείμενα @ref{1df,,str}, μπορείτε να δημιουργήσετε μια λίστα και να χρησιμοποιήσετε την @ref{2803,,str.join()} στο τέλος ή αλλιώς να γράψετε σε ένα @ref{12d4,,io.StringIO} instance και ανακτήσετε την τιμή της όταν ολοκληρωθεί

@item 
αν συνενώνεται αντικείμενα @ref{1c7,,bytes}, μπορείτε να χρησιμοποιήσετε παρόμοια τη μέθοδο @ref{2804,,bytes.join()} ή @ref{1255,,io.BytesIO}, ή μπορείτε να κάνετε in-place συνένωση (concatenation) με ένα @ref{1c6,,bytearray} αντικείμενο. Τα αντικείμενα @code{bytearray} είναι μεταβλητά και έχουν έναν αποτελεσματικό μηχανισμό συνολικής κατανομής (overallocation)

@item 
αν συνενώνεται αντικείμενα @ref{1ce,,tuple}, επεκτείνετε μια @ref{4d9,,list} αντ” αυτού

@item 
για άλλους τύπους, ερευνήστε τη σχετική τεκμηρίωση των κλάσεων
@end itemize

@item 
Ορισμένοι τύποι ακολουθιών (όπως @ref{d0f,,range}) υποστηρίζουν μόνο ακολουθίες στοιχείων που ακολουθούν συγκεκριμένα μοτίβα, και ως εκ τούτου δεν υποστηρίζουν ακολουθία συνένωση ή επανάληψη.

@item 
Μια @ref{18d7,,IndexError} γίνεται raise εάν το `i' βρίσκεται εκτός του εύρους ακολουθίας.
@end enumerate

@subsubheading Μέθοδοι Ακολουθίας


Οι τύποι ακολουθίας υποστηρίζουν επίσης τις ακόλουθες μεθόδους:


@geindex count() (μέθοδος της sequence)
@anchor{library/stdtypes list count}@anchor{1768}@anchor{library/stdtypes sequence count}@anchor{25cd}
@deffn {Μέθοδος} sequence.count (value, /)

Επιστρέφει το συνολικό αριθμό των εμφανίσεων του `value' μέσα στην `sequence'.
@end deffn


@geindex index() (μέθοδος της sequence)
@anchor{library/stdtypes list index}@anchor{1767}@anchor{library/stdtypes sequence index}@anchor{1b8b}
@deffn {Μέθοδος} sequence.index (value[, start[, stop]])

Επιστρέφει το δείκτη της πρώτης εμφάνισης του `value' μέσα στην `sequence'.

Κάνει raise μια @ref{277,,ValueError} αν το `value' δεν μπορεί να βρεθεί μέσα στην `sequence'.

Τα ορίσματα `start' ή `stop' επιτρέπουν αποδοτική αναζήτηση υποτμημάτων της ακολουθίας, ξεκινώντας από το `start' και τελειώνοντας στο `stop'. Αυτό είναι περίπου ισοδύναμο με το @code{start + sequence[start:stop].index(value)}, μόνο που δεν αντιγράφονται δεδομένα.

@cartouche
@quotation Προσοχή 
Δεν υποστηρίζουν όλοι οι τύποι ακολουθιών τη χρήση των ορισμάτων `start' και `stop'.
@end quotation
@end cartouche
@end deffn

@node Τύποι Αμετάβλητων Ακολουθιών Sequences,Τύποι Μεταβλητών Ακολουθιών Sequences,Κοινές Λειτουργίες Ακολουθιών Sequences,Τύποι Ακολουθίας Sequence — list tuple range
@anchor{library/stdtypes immutable-sequence-types}@anchor{2805}@anchor{library/stdtypes typesseq-immutable}@anchor{2806}
@subsubsection Τύποι Αμετάβλητων Ακολουθιών (Sequences)


@geindex αμετάβλητο;sequence;τύποι
@geindex αντικείμενο;πλειάδα (tuple)
@geindex ενσωματωμένες (built-in) συναρτήσεις;hash

Η μόνη λειτουργία που υλοποιούν οι αμετάβλητοι γενικοί τύποι ακολουθίας που δεν είναι υλοποιημένοι από μεταβλητούς τύπους ακολουθίας, είναι η υποστήριξη της @ref{9e2,,hash()} built-in.

Αυτή η υποστήριξη επιτρέπει αμετάβλητες ακολουθίες, όπως οι περιπτώσεις των @ref{1ce,,tuple}, να χρησιμοποιούνται ως κλειδιά @ref{188,,dict} και να αποθηκεύονται σε @ref{42b,,set} και @ref{9d4,,frozenset} instances.

Η προσπάθεια κατακερματισμού μιας αμετάβλητης ακολουθίας που περιέχει μη κατακερματιστέες (unhashable) τιμές θα οδηγήσει σε @ref{291,,TypeError}.

@node Τύποι Μεταβλητών Ακολουθιών Sequences,Λίστες<2>,Τύποι Αμετάβλητων Ακολουθιών Sequences,Τύποι Ακολουθίας Sequence — list tuple range
@anchor{library/stdtypes mutable-sequence-types}@anchor{2807}@anchor{library/stdtypes typesseq-mutable}@anchor{27bb}
@subsubsection Τύποι Μεταβλητών Ακολουθιών (Sequences)


@geindex ευμετάβλητο;sequence;τύποι
@geindex αντικείμενο;λίστα
@geindex αντικείμενο;bytearray

Οι λειτουργίες του ακόλουθου πίνακα ορίζονται σε μεταβλητούς τύπους ακολουθίας. Η @ref{6c6,,collections.abc.MutableSequence} ABC παρέχεται για να κάνει ευκολότερη την σωστή υλοποίηση αυτών των λειτουργιών σε προσαρμοσμένους τύπους ακολουθιών.

Στον πίνακα το `s' είναι ένα instance ενός μεταβλητού τύπου ακολουθίας, το `t' είναι οποιοδήποτε iterable αντικείμενο και το `x' είναι ένα αυθαίρετο αντικείμενο που πληροί οποιονδήποτε τύπο και περιορισμούς τιμής που επιβάλλονται από το `s' (για παράδειγμα, το @ref{1c6,,bytearray} δέχεται μόνο ακέραιους που πληρούν τον περιορισμό @code{0 <= x <= 255}).

@geindex λειτουργίες on;sequence;τύποι
@geindex λειτουργίες on;λίστα;τύπος
@geindex subscript;εκχώρηση
@geindex slice;εκχώρηση
@geindex statement;del


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Πράξη

@tab

Αποτέλεσμα

@tab

Σημειώσεις

@item

@code{s[i] = x}

@tab

το στοιχείο `i' του `s' αντικαθίσταται από το `x'

@tab

@item

@code{del s[i]}

@tab

αφαιρεί το στοιχείο `i' από το `s'

@tab

@item

@code{s[i:j] = t}

@tab

το υποσύνολο (slice) του `s' από το `i' έως το `j' αντικαθίσταται από τα περιεχόμενα του iterable `t'

@tab

@item

@code{del s[i:j]}

@tab

αφαιρεί τα στοιχεία της @code{s[i:j]} από τη λίστα (παρόμοια όπως @code{s[i:j] = []})

@tab

@item

@code{s[i:j:k] = t}

@tab

τα στοιχεία του @code{s[i:j:k]} αντικαθίστανται από εκείνα του `t'

@tab

(1)

@item

@code{del s[i:j:k]}

@tab

αφαιρεί τα στοιχεία του @code{s[i:j:k]} από τη λίστα

@tab

@item

@code{s += t}

@tab

επεκτείνει το `s' με τα περιεχόμενα του `t' (ως επί το πλείστον το ίδιο με το @code{s[len(s):len(s)] = t})

@tab

@item

@code{s *= n}

@tab

ενημερώνει το `s' με το περιεχόμενό του επαναλαμβανόμενο `n' φορές

@tab

(2)

@end multitable


Σημειώσεις:


@enumerate 

@item 
Αν το `k' δεν είναι ίσο με @code{1}, το `t' πρέπει να έχει το ίδιο μήκος με το τμήμα που αντικαθιστά.

@item 
Η τιμή `n' είναι ένας ακέραιος αριθμός ή ένα αντικείμενο που υλοποιεί την @ref{43d,,__index__()}.  Οι μηδενικές και αρνητικές τιμές του `n' καθαρίζουν την ακολουθία.  Τα στοιχεία της ακολουθίας δεν αντιγράφονται· αναφέρονται πολλές φορές, όπως εξηγείται για το @code{s * n`} στο @ref{2801,,Κοινές Λειτουργίες Ακολουθιών (Sequences)}.
@end enumerate

@subsubheading Μέθοδοι Μεταβλητών Ακολουθιών (Sequences)


Οι τύποι μεταβλητών ακολουθιών υποστηρίζουν επίσης τις ακόλουθες μεθόδους:


@geindex append() (μέθοδος της sequence)
@anchor{library/stdtypes bytearray append}@anchor{1748}@anchor{library/stdtypes sequence append}@anchor{25cb}
@deffn {Μέθοδος} sequence.append (value, /)

Append `value' to the end of the sequence.
This is equivalent to writing @code{seq[len(seq):len(seq)] = [value]}.
@end deffn


@geindex clear() (μέθοδος της sequence)
@anchor{library/stdtypes bytearray clear}@anchor{2808}@anchor{library/stdtypes sequence clear}@anchor{25cc}
@deffn {Μέθοδος} sequence.clear ()


Added in version 3.3.


Αφαιρεί όλα τα στοιχεία από την `sequence'. Αυτό είναι ισοδύναμο με το να γράψουμε @code{del sequence[:]}.
@end deffn


@geindex copy() (μέθοδος της sequence)
@anchor{library/stdtypes bytearray copy}@anchor{2809}@anchor{library/stdtypes sequence copy}@anchor{280a}
@deffn {Μέθοδος} sequence.copy ()


Added in version 3.3.


Δημιουργεί ένα shallow αντίγραφο του `sequence'. Αυτό είναι ισοδύναμο με το να γράψουμε @code{sequence[:]}.

@cartouche
@quotation Συμβουλή 
Η μέθοδος @code{copy()} δεν είναι μέρος της @ref{6c6,,MutableSequence} @ref{12c8,,ABC}, αλλά οι περισσότερους συγκεκριμένοι μεταβλητοί τύποι ακολουθιών την παρέχουν.
@end quotation
@end cartouche
@end deffn


@geindex extend() (μέθοδος της sequence)
@anchor{library/stdtypes bytearray extend}@anchor{198b}@anchor{library/stdtypes sequence extend}@anchor{25ce}
@deffn {Μέθοδος} sequence.extend (iterable, /)

Επεκτείνει το `sequence' με τα περιεχόμενα του `iterable'. Για το μεγαλύτερο μέρος, αυτό είναι το ίδιο με το να γράψουμε @code{seq[len(seq):len(seq)] = iterable}.
@end deffn


@geindex insert() (μέθοδος της sequence)
@anchor{library/stdtypes bytearray insert}@anchor{280b}@anchor{library/stdtypes sequence insert}@anchor{25cf}
@deffn {Μέθοδος} sequence.insert (index, value, /)

Εισάγει το `value' στην `sequence' στη δοθείσα θέση `index'. Αυτό είναι ισοδύναμο με το να γράψουμε @code{sequence[index:index] = [value]}.
@end deffn


@geindex pop() (μέθοδος της sequence)
@anchor{library/stdtypes bytearray pop}@anchor{1749}@anchor{library/stdtypes sequence pop}@anchor{25d0}
@deffn {Μέθοδος} sequence.pop (index=-1, /)

Ανακτά το στοιχείο στη θέση `index' και το αφαιρεί επίσης από την `sequence'. Εξ ορισμού, το τελευταίο στοιχείο στην `sequence' αφαιρείται και επιστρέφεται.
@end deffn


@geindex remove() (μέθοδος της sequence)
@anchor{library/stdtypes bytearray remove}@anchor{280c}@anchor{library/stdtypes sequence remove}@anchor{1b8c}
@deffn {Μέθοδος} sequence.remove (value, /)

Αφαιρεί το πρώτο στοιχείο από την `sequence' όπου @code{sequence[i] == value}.

Κάνει raise μια @ref{277,,ValueError} αν το `value' δεν μπορεί να βρεθεί μέσα στην `sequence'.
@end deffn


@geindex reverse() (μέθοδος της sequence)
@anchor{library/stdtypes bytearray reverse}@anchor{174a}@anchor{library/stdtypes sequence reverse}@anchor{25d1}
@deffn {Μέθοδος} sequence.reverse ()

Αντιστρέφει τα στοιχεία της `sequence' στη θέση της. Αυτή η μέθοδος διατηρεί την οικονομία χώρου κατά την αντιστροφή μιας μεγάλης ακολουθίας. Για να θυμίζει στους χρήστες ότι λειτουργεί με παρενέργεια, επιστρέφει το @code{None}.
@end deffn

@node Λίστες<2>,Πλειάδες Tuples,Τύποι Μεταβλητών Ακολουθιών Sequences,Τύποι Ακολουθίας Sequence — list tuple range
@anchor{library/stdtypes lists}@anchor{280d}@anchor{library/stdtypes typesseq-list}@anchor{2210}
@subsubsection Λίστες


@geindex αντικείμενο;λίστα

Οι λίστες είναι μεταβλητές ακολουθίες, που συνήθως χρησιμοποιούνται για την αποθήκευση συλλογών ομοιογενών στοιχείων (όπου ο ακριβής βαθμός ομοιότητας ποικίλλει ανάλογα με εφαρμογή).

@geindex list (ενσωματωμένη κλάση)
@anchor{library/stdtypes list}@anchor{4d9}
@deffn {Κλάση} list (iterable=(), /)

Οι λίστες μπορούν να κατασκευαστούν με διάφορους τρόπους:


@itemize *

@item 
Χρησιμοποιείστε ένα ζεύγος αγκυλών για να δηλώσετε την κενή λίστα: @code{[]}

@item 
Χρησιμοποιώντας αγκύλες, διαχωρίζοντας τα στοιχεία με κόμματα: @code{[a]}, @code{[a, b, c]}

@item 
Χρήση ενός list comprehension: @code{[x for x in iterable]}

@item 
Χρήση του κατασκευαστή τύπου (type constructor): @code{list()} ή @code{list(iterable)}
@end itemize

Ο κατασκευαστής (constructor) δημιουργεί μια λίστα της οποίας τα στοιχεία είναι τα ίδια και με την ίδια σειρά όπως τα στοιχεία του `iterable'.  Το `iterable' μπορεί να είναι είτε μια ακολουθία, είτε ένας container που υποστηρίζει την επανάληψη, ή ένα αντικείμενο iterator.  Εάν το `iterable' είναι ήδη μια λίστα, δημιουργείται ένα αντίγραφο και επιστρέφεται, παρόμοια με την @code{iterable[:]}. Για παράδειγμα, η @code{list('abc')} επιστρέφει @code{['a', 'b', 'c']} και η @code{list( (1, 2, 3) )} επιστρέφει @code{[1, 2, 3]}. Αν δεν δοθεί κανένα όρισμα, ο κατασκευαστής δημιουργεί μία νέα κενή λίστα, @code{[]}.

Πολλές άλλες λειτουργίες παράγουν επίσης λίστες, συμπεριλαμβανομένης της built-in @ref{f8c,,sorted()}.

Οι λίστες υλοποιούν όλες τις @ref{2801,,common} και @ref{27bb,,mutable} λειτουργίες ακολουθίας. Οι λίστες παρέχουν επίσης την ακόλουθη πρόσθετη μέθοδο:

@geindex sort() (μέθοδος της list)
@anchor{library/stdtypes list sort}@anchor{f8d}
@deffn {Μέθοδος} sort (*, key=None, reverse=False)

Αυτή η μέθοδος ταξινομεί τη λίστα, χρησιμοποιώντας μόνο συγκρίσεις @code{<} μεταξύ στοιχείων. Οι εξαιρέσεις δεν καταστέλλονται - αν αποτύχει κάποια πράξη σύγκρισης, ολόκληρη η λειτουργία ταξινόμησης θα αποτύχει (και η λίστα θα παραμείνει πιθανότατα σε μια μερικώς τροποποιημένη κατάσταση).

η @ref{f8d,,sort()} δέχεται δύο ορίσματα που μπορούν να περάσουν μόνο με τη λέξη-κλειδί (@ref{7a3,,keyword-only arguments}):

το `key' καθορίζει μια συνάρτηση ενός ορίσματος που χρησιμοποιείται για την εξαγωγή ενός κλειδιού σύγκρισης (comparison key) από κάθε στοιχείο της λίστας (για παράδειγμα, @code{key=str.lower}). Το κλειδί που αντιστοιχεί σε κάθε στοιχείο της λίστας υπολογίζεται μία φορά και στη συνέχεια χρησιμοποιείται για ολόκληρη τη διαδικασία ταξινόμησης. Η προεπιλεγμένη τιμή (default) @code{None} σημαίνει ότι τα στοιχεία της λίστας ταξινομούνται απευθείας χωρίς να υπολογίζεται ξεχωριστή τιμή κλειδιού.

Το utility @ref{1583,,functools.cmp_to_key()} είναι διαθέσιμο για τη μετατροπή μια συνάρτηση `cmp' στυλ 2.x σε συνάρτηση `key'.

η `reverse' είναι μια λογική (boolean) τιμή.  Αν τεθεί σε @code{True}, τότε τα στοιχεία της λίστας ταξινομούνται σαν να ήταν αντίστροφη κάθε σύγκριση.

Αυτή η μέθοδος τροποποιεί την ακολουθία για εξοικονόμηση χώρου κατά την ταξινόμηση μιας μεγάλης ακολουθίας.  Nα υπενθυμίσουμε στους χρήστες ότι λειτουργεί με παρενέργεια, δεν επιστρέφει την ταξινομημένη ακολουθία (χρησιμοποιήστε την @ref{f8c,,sorted()} για να ζητήσετε μια νέα περίπτωση ταξινομημένης λίστας).

Η μέθοδος @ref{f8d,,sort()} είναι εγγυημένα σταθερή.  Μια ταξινόμηση είναι σταθερή αν εγγυάται ότι δεν θα αλλάξει τη σχετική σειρά των στοιχείων που συγκρίνουν ίσα — αυτό είναι χρήσιμο για την ταξινόμηση σε πολλαπλά περάσματα (για παράδειγμα, ταξινόμηση κατά τμήμα, στη συνέχεια με βάση το μισθολογικό κλιμάκιο κτλ).

Για παραδείγματα ταξινόμησης και ένα σύντομο tutorial, δείτε @ref{27d9,,Sorting Techniques}.

Ενώ μια λίστα ταξινομείται, το αποτέλεσμα της προσπάθειας μετάλλαξης, ή ακόμα και η επιθεώρηση, της λίστας είναι απροσδιόριστη.  Η υλοποίηση της Python στη C κάνει την λίστα να εμφανίζεται κενή για όλη τη διάρκεια, και κάνει raise @ref{277,,ValueError} αν ανιχνεύσει ότι η λίστα έχει μεταλλαχθεί κατά τη διάρκεια μιας ταξινόμησης.
@end deffn
@end deffn


@subsubheading Δείτε επίσης


For detailed information on thread-safety guarantees for @ref{4d9,,list}
objects, see @ref{280e,,Thread safety for list objects}.


@node Πλειάδες Tuples,Εύρη Ranges,Λίστες<2>,Τύποι Ακολουθίας Sequence — list tuple range
@anchor{library/stdtypes tuples}@anchor{280f}@anchor{library/stdtypes typesseq-tuple}@anchor{2742}
@subsubsection Πλειάδες (Tuples)


@geindex αντικείμενο;πλειάδα (tuple)

Οι πλειάδες (tuples) είναι αμετάβλητες ακολουθίες, που συνήθως χρησιμοποιούνται για την αποθήκευση συλλογών ετερογενών δεδομένων (όπως οι 2-tuples που παράγονται από την built-in @ref{1823,,enumerate()}). Τα tuples χρησιμοποιούνται επίσης για περιπτώσεις όπου μια αμετάβλητη ακολουθία ομοιογενών δεδομένων (όπως για παράδειγμα για να επιτρέπεται η αποθήκευση σε ένα @ref{42b,,set} ή σε ένα @ref{188,,dict} instance).

@geindex tuple (ενσωματωμένη κλάση)
@anchor{library/stdtypes tuple}@anchor{1ce}
@deffn {Κλάση} tuple (iterable=(), /)

Οι πλειάδες (tuples) μπορούν να κατασκευαστούν με διάφορους τρόπους:


@itemize *

@item 
Χρήση ενός ζεύγους παρενθέσεων για να δηλωθεί το κενό tuple (πλειάδα): @code{()}

@item 
Χρήση ενός κόμματος στο τέλος για ένα μοναδικό tuple (πλειάδα): @code{a,} ή @code{(a,)}

@item 
Διαχωρισμός στοιχείων με κόμμα: @code{a, b, c} ή @code{(a, b, c)}

@item 
Χρήση του ενσωματωμένου @ref{1ce,,tuple()}: @code{tuple()} ή @code{tuple(iterable)}
@end itemize

Ο κατασκευαστής (constructor) δημιουργεί μια πλειάδα (tuple) του οποίου τα στοιχεία είναι τα ίδια και στην ίδια σειρά με τα στοιχεία του `iterable'.  Η `iterable' μπορεί να είναι είτε μια ακολουθία, είτε έναν container που υποστηρίζει την επανάληψη, ή ένα αντικείμενο iterator.  Εάν το `iterable' είναι ήδη ένα tuple, επιστρέφεται αμετάβλητο. Για παράδειγμα, το @code{tuple('abc')} επιστρέφει @code{('a', 'b', 'c')} και το @code{tuple( [1, 2, 3] )} επιστρέφει @code{(1, 2, 3)}. Αν δεν δοθεί κανένα όρισμα, ο κατασκευαστής δημιουργεί μια ένα κενό tuple, @code{()}.

Σημειώστε ότι στην πραγματικότητα το κόμμα είναι αυτό που κάνει ένα tuple (πλειάδα), όχι οι παρενθέσεις. Οι παρενθέσεις είναι προαιρετικές, εκτός από την περίπτωση κενού tuple ή όταν χρειάζονται για την αποφυγή συντακτικής ασάφειας. Για παράδειγμα, η @code{f(a, b, c)} είναι μια κλήση συνάρτησης με τρία ορίσματα, ενώ η @code{f((a, b, c))} είναι μια συνάρτηση κλήση συνάρτησης με ένα 3-tuple ως μοναδικό όρισμα.

Τα Tuples υλοποιούν όλες τις πράξεις ακολουθιών @ref{2801,,common}.
@end deffn

Για ετερογενείς συλλογές δεδομένων όπου η πρόσβαση με βάση το όνομα είναι σαφέστερη από την πρόσβαση με βάση το δείκτη, το @ref{1cf,,collections.namedtuple()} μπορεί να είναι μια πιο κατάλληλη επιλογή από ένα απλό αντικείμενο tuple (πλειάδα).

@node Εύρη Ranges,,Πλειάδες Tuples,Τύποι Ακολουθίας Sequence — list tuple range
@anchor{library/stdtypes ranges}@anchor{2810}@anchor{library/stdtypes typesseq-range}@anchor{27d6}
@subsubsection Εύρη (Ranges)


@geindex αντικείμενο;range

Ο τύπος @ref{d0f,,range} αναπαριστά μια αμετάβλητη ακολουθία αριθμών και συνήθως χρησιμοποιείται για την επανάληψη ενός συγκεκριμένου αριθμού επαναλήψεων σε βρόχους @ref{321,,for}.

@geindex range (ενσωματωμένη κλάση)
@anchor{library/stdtypes range}@anchor{d0f}
@deffn {Κλάση} range (stop, /)

@deffnx {Κλάση} range (start, stop, step=1, /)

Τα ορίσματα του  κατασκευαστή εύρους (range constructor) πρέπει να είναι ακέραιοι αριθμοί (είτε της built-in @ref{326,,int} ή οποιοδήποτε αντικείμενο που υλοποιεί την ειδική μέθοδο @ref{43d,,__index__()}). Εάν το όρισμα `step' παραλείπεται, το προεπιλογή (default) είναι @code{1}. Εάν το όρισμα `start' παραλείπεται, το προεπιλογή (default) είναι @code{0}. Εάν το `step' είναι μηδέν, γίνεται raise ένα @ref{277,,ValueError}.

Για ένα θετικό `βήμα', τα περιεχόμενα του range (εύρους) @code{r} καθορίζονται από τον τύπο @code{r[i] = start + step*i} όπου @code{i >= 0} και @code{r[i] < stop}.

Για ένα αρνητικό `βήμα', τα περιεχόμενα του εύρους (range) εξακολουθούν να καθορίζονται από τον τύπο @code{r[i] = start + step*i}, αλλά οι περιορισμοί είναι @code{i >= 0} και @code{r[i] > stop}.

Ένα αντικείμενο range θα είναι άδειο εάν το @code{r[0]} δεν πληροί τον περιορισμό τιμής. Τα ranges υποστηρίζουν αρνητικούς δείκτες, αλλά αυτοί ερμηνεύονται ως δείκτες από το τέλος της ακολουθίας που καθορίζεται από τους θετικούς δείκτες.

Τα ranges που περιέχουν απόλυτες τιμές μεγαλύτερες από @ref{156e,,sys.maxsize} είναι επιτρεπτά, αλλά ορισμένα χαρακτηριστικά (όπως @ref{a1f,,len()}) μπορεί να κάνουν raise @ref{c57,,OverflowError}.

Παραδείγματα 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

Τα ranges υλοποιούν όλες τις ακολουθίες @ref{2801,,common} εκτός από τη συνένωση και την επανάληψη (λόγω του γεγονότος ότι τα range αντικείμενα μπορούν να αναπαριστούν μόνο ακολουθίες που ακολουθούν ένα αυστηρό μοτίβο και η επανάληψη και η συνένωση συνήθως παραβιάζουν αυτό το πρότυπο).

@geindex start (ιδιότητα της range)
@anchor{library/stdtypes range start}@anchor{2811}
@deffn {Ιδιότητα} start

Η τιμή της παραμέτρου `start' (ή @code{0} αν η παράμετρος δεν παρέχεται)
@end deffn

@geindex stop (ιδιότητα της range)
@anchor{library/stdtypes range stop}@anchor{2812}
@deffn {Ιδιότητα} stop

Η τιμή της παραμέτρου `stop'
@end deffn

@geindex step (ιδιότητα της range)
@anchor{library/stdtypes range step}@anchor{2813}
@deffn {Ιδιότητα} step

Η τιμή της παραμέτρου `step' (ή @code{1} αν η παράμετρος δεν παρέχεται)
@end deffn
@end deffn

Το πλεονέκτημα του τύπου @ref{d0f,,range} έναντι ενός κανονικού τύπου @ref{4d9,,list} ή @ref{1ce,,tuple} είναι ότι ένα αντικείμενο @code{range} θα παίρνει πάντα το ίδιο (μικρό) ποσό μνήμης, ανεξάρτητα από το μέγεθος του range που αντιπροσωπεύει (μιας και αποθηκεύει μόνο τις τιμές @code{start}, @code{stop} και @code{step}, υπολογίζοντας τα μεμονωμένα στοιχεία και τις υποπεριοχές όπως απαιτείται).

Τα αντικείμενα range υλοποιούν την @ref{156d,,collections.abc.Sequence} ABC, και παρέχουν χαρακτηριστικά όπως δοκιμές περιορισμού, αναζήτηση δείκτη στοιχείου, τεμαχισμό και υποστήριξη αρνητικών δεικτών (βλ. @ref{221d,,Τύποι Ακολουθίας (Sequence) — 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

Ο έλεγχος των αντικειμένων range για ισότητα με @code{==} και @code{!=} τα συγκρίνει ως ακολουθίες.  Δηλαδή, δύο αντικείμενα range θεωρούνται ίσα αν αντιπροσωπεύουν την ίδια ακολουθία τιμών.  (Σημειώστε ότι δύο αντικείμενα range που συγκρίνονται ως ίσα μπορεί να έχουν διαφορετικά @ref{2811,,start}, @ref{2812,,stop} και @ref{2813,,step} χαρακτηριστικά, για παράδειγμα @code{range(0) == range(2, 1, 3)} ή @code{range(0, 3, 2) == range(0, 4, 2)}.)


Άλλαξε στην έκδοση 3.2: Υλοποιείστε την ακολουθία ABC. Υποστηρίξτε την τμηματοποίηση και τους αρνητικούς δείκτες. Δοκιμάστε τα @ref{326,,int} αντικείμενα για συμμετοχή σε σταθερό χρόνο αντί της επανάληψης σε όλα τα αντικείμενα.



Άλλαξε στην έκδοση 3.3: Ορίστε τα “==” και “!=” για να συγκρίνετε αντικείμενα range με βάση την ακολουθία των τιμών που ορίζουν (αντί να συγκρίνουν με βάση την ταυτότητα του αντικειμένου).

Προστέθηκαν τα @ref{2811,,start}, @ref{2812,,stop} και @ref{2813,,step} attributes.



@subsubheading Δείτε επίσης



@itemize *

@item 
Η συνταγή linspace@footnote{https://code.activestate.com/recipes/579000-equally-spaced-numbers-linspace/} δείχνει πώς να υλοποιήσετε μια lazy έκδοση του range κατάλληλη για εφαρμογές κινητής υποδιαστολής.
@end itemize


@geindex string;τύπος ακολουθίας κειμένου
@geindex str (ενσωματωμένη (built-in) κλάση);(βλ. επίσης string)
@geindex αντικείμενο;string

@node Σύνοψη μεθόδων τύπου κειμένου και δυαδική ακολουθίας,Τύπος Ακολουθίας Sequence Κειμένου — str,Τύποι Ακολουθίας Sequence — list tuple range,Τύποι Built-in
@anchor{library/stdtypes text-and-binary-sequence-type-methods-summary}@anchor{2814}@anchor{library/stdtypes text-methods-summary}@anchor{2815}
@subsection Σύνοψη μεθόδων τύπου κειμένου και δυαδική ακολουθίας


Ο παρακάτω πίνακας συνοψίζει τις μεθόδους τύπων κειμένου και δυαδική ακολουθίας ανά κατηγορία.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xx} {xx} {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xx} {xx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Κατηγορία

@tab

@ref{1df,,str} methods

@tab

@tab

@tab

@tab

οι μέθοδοι @ref{1c7,,bytes} και @ref{1c6,,bytearray}

@tab

@tab

@tab

@item

Μορφοποίηση

@tab

@ref{a12,,str.format()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{1190,,str.format_map()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{43a,,f-strings}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{ab9,,printf-style String Formatting}

@tab

@tab

@tab

@tab

@ref{113a,,Μορφοποίηση Bytes τύπου printf}

@tab

@tab

@tab

@item

Αναζήτηση και Αντικατάσταση

@tab

@ref{1259,,str.find()}

@tab

@ref{125a,,str.rfind()}

@tab

@tab

@tab

@ref{1dcd,,bytes.find()}

@tab

@ref{1dce,,bytes.rfind()}

@tab

@tab

@item

@ref{1bc6,,str.index()}

@tab

@ref{15fc,,str.rindex()}

@tab

@tab

@tab

@ref{2816,,bytes.index()}

@tab

@ref{2817,,bytes.rindex()}

@tab

@tab

@item

@ref{1279,,str.startswith()}

@tab

@tab

@tab

@tab

@ref{2818,,bytes.startswith()}

@tab

@tab

@tab

@item

@ref{127a,,str.endswith()}

@tab

@tab

@tab

@tab

@ref{2819,,bytes.endswith()}

@tab

@tab

@tab

@item

@ref{1b93,,str.count()}

@tab

@tab

@tab

@tab

@ref{1b94,,bytes.count()}

@tab

@tab

@tab

@item

@ref{6c0,,str.replace()}

@tab

@tab

@tab

@tab

@ref{1d3,,bytes.replace()}

@tab

@tab

@tab

@item

Διαχωρισμός και Ένωση

@tab

@ref{125b,,str.split()}

@tab

@tab

@ref{15fa,,str.rsplit()}

@tab

@tab

@ref{281a,,bytes.split()}

@tab

@tab

@ref{281b,,bytes.rsplit()}

@tab

@item

@ref{15fb,,str.splitlines()}

@tab

@tab

@tab

@tab

@ref{281c,,bytes.splitlines()}

@tab

@tab

@tab

@item

@ref{125c,,str.partition()}

@tab

@tab

@tab

@tab

@ref{281d,,bytes.partition()}

@tab

@tab

@tab

@item

@ref{15fd,,str.rpartition()}

@tab

@tab

@tab

@tab

@ref{281e,,bytes.rpartition()}

@tab

@tab

@tab

@item

@ref{2803,,str.join()}

@tab

@tab

@tab

@tab

@ref{2804,,bytes.join()}

@tab

@tab

@tab

@item

Ταξινόμηση Συμβολοσειρών

@tab

@ref{281f,,str.isalpha()}

@tab

@tab

@tab

@tab

@ref{2820,,bytes.isalpha()}

@tab

@tab

@tab

@item

@ref{2821,,str.isdecimal()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{2822,,str.isdigit()}

@tab

@tab

@tab

@tab

@ref{2823,,bytes.isdigit()}

@tab

@tab

@tab

@item

@ref{2824,,str.isnumeric()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{2825,,str.isalnum()}

@tab

@tab

@tab

@tab

@ref{2826,,bytes.isalnum()}

@tab

@tab

@tab

@item

@ref{1f3a,,str.isidentifier()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{2827,,str.islower()}

@tab

@tab

@tab

@tab

@ref{2828,,bytes.islower()}

@tab

@tab

@tab

@item

@ref{2829,,str.isupper()}

@tab

@tab

@tab

@tab

@ref{282a,,bytes.isupper()}

@tab

@tab

@tab

@item

@ref{282b,,str.istitle()}

@tab

@tab

@tab

@tab

@ref{282c,,bytes.istitle()}

@tab

@tab

@tab

@item

@ref{282d,,str.isspace()}

@tab

@tab

@tab

@tab

@ref{282e,,bytes.isspace()}

@tab

@tab

@tab

@item

@ref{1191,,str.isprintable()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

Χειρισμός υποθέσεων

@tab

@ref{1965,,str.lower()}

@tab

@tab

@tab

@tab

@ref{282f,,bytes.lower()}

@tab

@tab

@tab

@item

@ref{2830,,str.upper()}

@tab

@tab

@tab

@tab

@ref{2831,,bytes.upper()}

@tab

@tab

@tab

@item

@ref{118f,,str.casefold()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{2832,,str.capitalize()}

@tab

@tab

@tab

@tab

@ref{2833,,bytes.capitalize()}

@tab

@tab

@tab

@item

@ref{2834,,str.title()}

@tab

@tab

@tab

@tab

@ref{2835,,bytes.title()}

@tab

@tab

@tab

@item

@ref{2836,,str.swapcase()}

@tab

@tab

@tab

@tab

@ref{2837,,bytes.swapcase()}

@tab

@tab

@tab

@item

Συμπλήρωση και Αφαίρεση

@tab

@ref{2251,,str.ljust()}

@tab

@tab

@ref{2250,,str.rjust()}

@tab

@tab

@ref{2838,,bytes.ljust()}

@tab

@tab

@ref{2839,,bytes.rjust()}

@tab

@item

@ref{2252,,str.center()}

@tab

@tab

@tab

@tab

@ref{283a,,bytes.center()}

@tab

@tab

@tab

@item

@ref{283b,,str.expandtabs()}

@tab

@tab

@tab

@tab

@ref{283c,,bytes.expandtabs()}

@tab

@tab

@tab

@item

@ref{1851,,str.strip()}

@tab

@tab

@tab

@tab

@ref{283d,,bytes.strip()}

@tab

@tab

@tab

@item

@ref{1852,,str.lstrip()}

@tab

@tab

@tab

@ref{1853,,str.rstrip()}

@tab

@ref{283e,,bytes.lstrip()}

@tab

@tab

@tab

@ref{283f,,bytes.rstrip()}

@item

Μετάφραση και Κωδικοποίηση

@tab

@ref{1979,,str.translate()}

@tab

@tab

@tab

@tab

@ref{196d,,bytes.translate()}

@tab

@tab

@tab

@item

@ref{187,,str.maketrans()}

@tab

@tab

@tab

@tab

@ref{1619,,bytes.maketrans()}

@tab

@tab

@tab

@item

@ref{ca7,,str.encode()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@tab

@tab

@tab

@tab

@ref{ca8,,bytes.decode()}

@tab

@tab

@tab

@end multitable


@node Τύπος Ακολουθίας Sequence Κειμένου — str,Τύποι δυαδικής ακολουθίας — bytes bytearray memoryview,Σύνοψη μεθόδων τύπου κειμένου και δυαδική ακολουθίας,Τύποι Built-in
@anchor{library/stdtypes text-sequence-type-str}@anchor{2840}@anchor{library/stdtypes textseq}@anchor{21cd}
@subsection Τύπος Ακολουθίας (Sequence) Κειμένου — @code{str}


Τα δεδομένα κειμένου στην Python αντιμετωπίζονται με αντικείμενα @ref{1df,,str} ή `strings'. Τα αλφαριθμητικά (strings) είναι αμετάβλητες @ref{221d,,sequences} των Unicode points.  Τα αλφαριθμητικά γράφονται με διάφορους τρόπους:


@itemize *

@item 
Απλά εισαγωγικά: @code{'allows embedded "double" quotes'}

@item 
Διπλά εισαγωγικά: @code{'allows embedded "double" quotes'}

@item 
Τριπλά εισαγωγικά: @code{'@w{'}'Three single quotes'@w{'}'}, @code{"""Three double quotes"""}
@end itemize

Τα αλφαριθμητικά σε τριπλά εισαγωγικά μπορούν να καλύπτουν πολλές γραμμές - όλα τα σχετικά κενά θα συμπεριληφθούν στο αλφαριθμητικό.

Τα Αλφαριθμητικά (strings) που αποτελούν μέρος μιας ενιαίας έκφρασης και έχουν μόνο κενά μεταξύ τους, θα μετατραπούν σιωπηρά σε ένα ενιαίο αλφαριθμητικό literal. Δηλαδή, @code{("spam " "eggs") == "spam eggs"}.

Δείτε τα @ref{2490,,Λεκτικά συμβολοσειράς και Bytes} για περισσότερες πληροφορίες σχετικά με τις διάφορες μορφές των αλφαριθμητικών, συμπεριλαμβανομένων των υποστηριζόμενων ακολουθιών @ref{874,,escape sequences}, και του @code{r} («raw») πρόθεμα που απενεργοποιεί την επεξεργασία των περισσότερων ακολουθιών διαφυγής.

Τα αλφαριθμητικά (strings) μπορούν επίσης να δημιουργηθούν από άλλα αντικείμενα χρησιμοποιώντας τον constructor @ref{1df,,str}.

Εφόσον δεν υπάρχει ξεχωριστός τύπος «character», το indexing μιας συμβολοσειράς (string) παράγει συμβολοσειρές μήκους 1. Δηλαδή, για μια μη κενή συμβολοσειρά `s', @code{s[0] == s[0:1]}.

@geindex αντικείμενο;io.StringIO

Δεν υπάρχει επίσης μεταβλητός τύπος συμβολοσειράς (string), αλλά το @ref{2803,,str.join()} ή το @ref{12d4,,io.StringIO} μπορεί να χρησιμοποιηθεί για την αποτελεσματική κατασκευή συμβολοσειρών από πολλαπλά μέρη.


Άλλαξε στην έκδοση 3.3: Για συμβατότητα προς τα πίσω (backwards compatibility) με τη σειρά Python 2, το πρόθεμα @code{u} είναι επιτρεπτό και πάλι σε αλφαριθμητικά. Δεν έχει καμία επίδραση στη σημασία των αλφαριθμητικών και δεν μπορεί να συνδυαστεί με το πρόθεμα @code{r}.


@geindex string;str (ενσωματωμένη (built-in) κλάση)

@geindex str (ενσωματωμένη κλάση)
@anchor{library/stdtypes str}@anchor{1df}
@deffn {Κλάση} str (*, encoding='utf-8', errors='strict')

@deffnx {Κλάση} str (object)

@deffnx {Κλάση} str (object, encoding, errors='strict')

@deffnx {Κλάση} str (object, *, errors)

Επιστρέφει μια έκδοση @ref{21cd,,string} του `object'.  Αν το `object' δεν παρέχεται, επιστρέφει κενό αλφαριθμητικό.  Διαφορετικά, η συμπεριφορά της @code{str()} εξαρτάται από το αν δίνεται `encoding' ή `errors', ως εξής.

Αν δεν έχει δοθεί ούτε `encoding' ούτε `errors', το @code{str(object)} επιστρέφει @ref{a0f,,type(object).__str__(object)}, το οποίο είναι το «informal» ή ωραία εκτυπώσιμη αναπαράσταση συμβολοσειράς (string) του `object'.  Για αντικείμενα συμβολοσειράς, είναι η ίδια η συμβολοσειρά.  Εάν το `object' δεν έχει την @code{__str__()}, τότε η @ref{1df,,str()} επιστρέφει τη μέθοδο @ref{45b,,repr(object)}.

@geindex πρωτόκολλο buffer;str (ενσωματωμένη (built-in) κλάση)
@geindex bytes;str (ενσωματωμένη (built-in) κλάση)

Εάν δίνεται τουλάχιστον ένα από τα `encoding' ή `errors', το `object' θα πρέπει να είναι ένα @ref{436,,bytes-like object} (π.χ. @ref{1c7,,bytes} ή @ref{1c6,,bytearray}).  Σε αυτή την περίπτωση, αν το `object' είναι ένα αντικείμενο @code{bytes} (ή @code{bytearray}), τότε το @code{str(bytes, encoding, errors)} είναι ισοδύναμο με το @ref{ca8,,bytes.decode(encoding@comma{} errors)}.  Διαφορετικά, το αντικείμενο bytes που υποκρύπτει το αντικείμενο buffer λαμβάνεται πριν από την κλήση του @code{bytes.decode()}.  Δείτε @ref{27bd,,Τύποι δυαδικής ακολουθίας — bytes@comma{} bytearray@comma{} memoryview} και @ref{311,,Buffer Protocol} για πληροφορίες σχετικά με τα αντικείμενα buffer.

Πέρασμα ενός αντικειμένου @ref{1c7,,bytes} στο @ref{1df,,str()} χωρίς το `encoding' ή το `errors' ορίσματα εμπίπτει στην πρώτη περίπτωση επιστροφής της άτυπης αναπαράστασης συμβολοσειράς (string) (δείτε επίσης την επιλογή @ref{2ed,,-b} της γραμμής εντολών για Python).  Για παράδειγμα:

@example
>>> str(b'Zoot!')
"b'Zoot!'"
@end example

Για περισσότερες πληροφορίες σχετικά με την κλάση @code{str} και τις μεθόδους της, δείτε @ref{21cd,,Τύπος Ακολουθίας (Sequence) Κειμένου — str} και την ενότητα @ref{21ce,,Μέθοδοι Συμβολοσειράς (String)} παρακάτω.  Για την παραγωγή μορφοποιημένων συμβολοσειρών (string), ανατρέξτε στις ενότητες @ref{43a,,f-strings} και @ref{173f,,Format string syntax}.  Επιπλέον, δείτε την ενότητα @ref{2841,,Text Processing Services}.
@end deffn

@geindex string;μέθοδοι

@menu
* Μέθοδοι Συμβολοσειράς (String): Μέθοδοι Συμβολοσειράς String. 
* Διαμορφωμένες Κυριολεκτικές Συμβολοσειρές (f-strings): Διαμορφωμένες Κυριολεκτικές Συμβολοσειρές f-strings. 
* Template String Literals (t-strings): Template String Literals t-strings. 
* printf-style String Formatting:: 

@end menu

@node Μέθοδοι Συμβολοσειράς String,Διαμορφωμένες Κυριολεκτικές Συμβολοσειρές f-strings,,Τύπος Ακολουθίας Sequence Κειμένου — str
@anchor{library/stdtypes id5}@anchor{2842}@anchor{library/stdtypes string-methods}@anchor{21ce}
@subsubsection Μέθοδοι Συμβολοσειράς (String)


@geindex module;re

Οι συμβολοσειρές (string) υλοποιούν όλες τις λειτουργίες των @ref{2801,,common} ακολουθιών, μαζί με τις πρόσθετες μεθόδους που περιγράφονται παρακάτω.

Οι συμβολοσειρές (string) υποστηρίζουν επίσης δύο στυλ μορφοποίησης συμβολοσειρών, το ένα παρέχει ένα μεγάλο βαθμό ευελιξίας και προσαρμογής (βλέπε @ref{a12,,str.format()}, @ref{173f,,Format string syntax} και @ref{2843,,Custom string formatting}) και το άλλο βασίζεται στο στυλ μορφοποίησης @code{printf} της C που χειρίζεται ένα στενότερο εύρος τύπων και είναι λίγο πιο δύσκολο να χρησιμοποιηθεί σωστά, αλλά είναι συχνά ταχύτερο για τις περιπτώσεις που μπορεί να χειριστεί (@ref{ab9,,printf-style String Formatting}).

Το τμήμα @ref{2844,,Text Processing Services} της πρότυπης βιβλιοθήκης καλύπτει έναν αριθμό από άλλες ενότητες που παρέχουν διάφορες βοηθητικές υπηρεσίες που σχετίζονται με το κείμενο (συμπεριλαμβανομένης της υποστήριξης των κανονικών εκφράσεων στην ενότητα @ref{c1,,re}).

@geindex capitalize() (μέθοδος της str)
@anchor{library/stdtypes str capitalize}@anchor{2832}
@deffn {Μέθοδος} str.capitalize ()

Επιστρέφει ένα αντίγραφο της συμβολοσειράς (string) με τον πρώτο χαρακτήρα κεφαλαίο και τα υπόλοιπα με πεζά γράμματα.


Άλλαξε στην έκδοση 3.8: Ο πρώτος χαρακτήρας τίθεται τώρα σε titlecase αντί για uppercase. Αυτό σημαίνει ότι χαρακτήρες όπως οι διγράφοι (digraphs) θα έχουν μόνο το πρώτο γράμμα τους με κεφαλαίο, αντί για όλους τους χαρακτήρες.

@end deffn

@geindex casefold() (μέθοδος της str)
@anchor{library/stdtypes str casefold}@anchor{118f}
@deffn {Μέθοδος} str.casefold ()

Επιστρέφει ένα αντίγραφο της συμβολοσειράς (string) σε casefolded μορφή. Οι casefolded συμβολοσειρές μπορούν να χρησιμοποιηθούν για caseless matching.

Casefolding is similar to lowercasing but more aggressive because it is
intended to remove all case distinctions in a string. For example, the German
lowercase letter @code{'ß'} is equivalent to @code{"ss"}. Since it is already
lowercase, @ref{1965,,lower()} would do nothing to @code{'ß'}; @code{casefold()}
converts it to @code{"ss"}.
For example:

@example
>>> 'straße'.lower()
'straße'
>>> 'straße'.casefold()
'strasse'
@end example

The casefolding algorithm is described in section 3.13.3 'Default Case Folding' of the Unicode Standard@footnote{https://www.unicode.org/versions/Unicode17.0.0/core-spec/chapter-3/#G53253}.


Added in version 3.3.

@end deffn

@geindex center() (μέθοδος της str)
@anchor{library/stdtypes str center}@anchor{2252}
@deffn {Μέθοδος} str.center (width, fillchar=' ', /)

Επιστρέφει ένα κεντραρισμένο σε μια συμβολοσειρά (string) μήκους `width'. Το padding γίνεται με τη χρήση του καθορισμένου `fillchar' (το default είναι ένα κενό ASCII). Η αρχική συμβολοσειρά επιστρέφεται εάν το `width' είναι μικρότερο ή ίσο με το @code{len(s)}.  Για παράδειγμα:

@example
>>> 'Python'.center(10)
'  Python  '
>>> 'Python'.center(10, '-')
'--Python--'
>>> 'Python'.center(4)
'Python'
@end example
@end deffn

@geindex count() (μέθοδος της str)
@anchor{library/stdtypes str count}@anchor{1b93}
@deffn {Μέθοδος} str.count (sub[, start[, end]])

Επιστρέφει τον αριθμό των μη επικαλυπτόμενων (non-overalpping) εμφανίσεων της υποομάδας `sub' στο εύρος [`start', `end'].  Τα προαιρετικά ορίσματα `start' και `end' ερμηνεύονται όπως στο slice notation.

Αν το `sub' είναι κενό, επιστρέφει τον αριθμό των κενών συμβολοσειρών (strings) μεταξύ των χαρακτήρων που είναι το μήκος της συμβολοσειράς συν ένα. Για παράδειγμα:

@example
>>> 'spam, spam, spam'.count('spam')
3
>>> 'spam, spam, spam'.count('spam', 5)
2
>>> 'spam, spam, spam'.count('spam', 5, 10)
1
>>> 'spam, spam, spam'.count('eggs')
0
>>> 'spam, spam, spam'.count('@w{'})
17
@end example
@end deffn

@geindex encode() (μέθοδος της str)
@anchor{library/stdtypes str encode}@anchor{ca7}
@deffn {Μέθοδος} str.encode (encoding='utf-8', errors='strict')

Επιστρέφει την συμβολοσειρά (string) κωδικοποιημένη σε @ref{1c7,,bytes}.

το `encoding' έχει default σε @code{'utf-8'}- δείτε @ref{1171,,Standard Encodings} για πιθανές τιμές.

το `errors' ελέγχει τον τρόπο χειρισμού των σφαλμάτων κωδικοποίησης. Εάν είναι @code{'strict'} (το default), τότε γίνεται raise μια εξαίρεση @ref{675,,UnicodeError}. Άλλες πιθανές τιμές είναι τα @code{'ignore'}, @code{'replace'}, @code{'xmlcharrefreplace'}, @code{'backslashreplace'} και οποιοδήποτε άλλο όνομα που έχει καταχωρηθεί μέσω του @ref{183d,,codecs.register_error()}. Δείτε το @ref{1d6c,,Error Handlers} για λεπτομέρειες.

Για λόγους απόδοσης, η τιμή των `errors' δεν ελέγχεται ως προς την εγκυρότητα εκτός αν όντως προκύψει σφάλμα κωδικοποίησης, αν το @ref{70d,,Python Development Mode} είναι ενεργοποιημένο ή αν ένα @ref{3dc,,debug build} χρησιμοποιείται. Για παράδειγμα:

@example
>>> encoded_str_to_bytes = 'Python'.encode()
>>> type(encoded_str_to_bytes)
<class 'bytes'>
>>> encoded_str_to_bytes
b'Python'
@end example


Άλλαξε στην έκδοση 3.1: Επιπρόσθετη υποστήριξη για keyword ορίσματα.



Άλλαξε στην έκδοση 3.9: Η τιμή του όρου `errors' ελέγχεται τώρα στο @ref{70d,,Python Development Mode} και στο @ref{3dc,,debug mode}.

@end deffn

@geindex endswith() (μέθοδος της str)
@anchor{library/stdtypes str endswith}@anchor{127a}
@deffn {Μέθοδος} str.endswith (suffix[, start[, end]])

Επιστρέφει @code{True} αν η συμβολοσειρά (string) τελειώνει με το καθορισμένο `suffix', αλλιώς επιστρέφει @code{False}.  Το `suffix' μπορεί επίσης να είναι ένα tuple (πλειάδα) από επιθέματα που πρέπει να αναζητηθούν.  Με το προαιρετικό `start', το τεστ αρχίζει από αυτή τη θέση.  Με το προαιρετικό `end', η σύγκριση σταματά σε αυτή τη θέση. Χρησιμοποιώντας `start' και `end' είναι ισοδύναμο με την @code{str[start:end].endswith(suffix)}. Για παράδειγμα:

@example
>>> 'Python'.endswith('on')
True
>>> 'a tuple of suffixes'.endswith(('at', 'in'))
False
>>> 'a tuple of suffixes'.endswith(('at', 'es'))
True
>>> 'Python is amazing'.endswith('is', 0, 9)
True
@end example

Δείτε επίσης @ref{1279,,startswith()} και @ref{ca2,,removesuffix()}.
@end deffn

@geindex expandtabs() (μέθοδος της str)
@anchor{library/stdtypes str expandtabs}@anchor{283b}
@deffn {Μέθοδος} str.expandtabs (tabsize=8)

Επιστρέφει ένα αντίγραφο της συμβολοσειράς (string) όπου όλοι οι χαρακτήρες tab αντικαθίστανται από έναν ή περισσότερα κενά, ανάλογα με την τρέχουσα στήλη και το δεδομένο μέγεθος των tabs.  Οι θέσεις tab εμφανίζονται κάθε `tabsize' χαρακτήρες (το default είναι 8, δίνοντας tab θέσεις στις στήλες 0, 8, 16 κ.ο.κ.).  Για την επέκταση της συμβολοσειράς, η τρέχουσα στήλη μηδενίζεται και η συμβολοσειρά εξετάζεται χαρακτήρας προς χαρακτήρα.  Εάν ο χαρακτήρας είναι tab (@code{\t}), εισάγονται ένας ή περισσότεροι χαρακτήρες κενών στο αποτέλεσμα μέχρι η τρέχουσα στήλη να είναι ίση με την επόμενη θέση tab. (Ο ίδιος ο χαρακτήρας tab δεν αντιγράφεται.) Εάν ο χαρακτήρας είναι νέα γραμμή (@code{\n}) ή return (@code{\r}), αντιγράφεται και η τρέχουσα στήλη επαναφέρεται στο μηδέν.  Οποιοσδήποτε άλλος χαρακτήρας αντιγράφεται αμετάβλητος και η τρέχουσα στήλη αυξάνεται κατά ένα, ανεξάρτητα από τον τρόπο αναπαράστασης του χαρακτήρα όταν τυπώνεται. Για παράδειγμα:

@example
>>> '01\t012\t0123\t01234'.expandtabs()
'01      012     0123    01234'
>>> '01\t012\t0123\t01234'.expandtabs(4)
'01  012 0123    01234'
>>> print('01\t012\n0123\t01234'.expandtabs(4))
01  012
0123    01234
@end example
@end deffn

@geindex find() (μέθοδος της str)
@anchor{library/stdtypes str find}@anchor{1259}
@deffn {Μέθοδος} str.find (sub[, start[, end]])

Επιστρέφει τον χαμηλότερο δείκτη στη συμβολοσειρά (string) όπου η υπό-συμβολοσειρά `sub' βρίσκεται μέσα στο υποσύνολο (slice) @code{s[start:end]}.  Τα προαιρετικά ορίσματα `start' και `end' ερμηνεύονται όπως στο notation του υποσυνόλου.  Επιστρέφει @code{-1} αν δεν βρεθεί το `sub'. Για παράδειγμα:

@example
>>> 'spam, spam, spam'.find('sp')
0
>>> 'spam, spam, spam'.find('sp', 5)
6
@end example

Δείτε επίσης @ref{125a,,rfind()} και @ref{1bc6,,index()}.

@cartouche
@quotation Σημείωση 
Η μέθοδος @ref{1259,,find()} θα πρέπει να χρησιμοποιείται μόνο αν πρέπει να γνωρίζετε τη θέση του `sub'.  Για να ελέγξετε αν το `sub' είναι υποσύνολο ή όχι, χρησιμοποιήστε τον τελεστή @ref{323,,in}:

@example
>>> 'Py' in 'Python'
True
@end example
@end quotation
@end cartouche
@end deffn

@geindex format() (μέθοδος της str)
@anchor{library/stdtypes str format}@anchor{a12}
@deffn {Μέθοδος} str.format (*args, **kwargs)

Εκτέλεση μιας λειτουργίας μορφοποίησης συμβολοσειράς (string formatting).  Η συμβολοσειρά στην οποία αυτή η μέθοδος καλείται μπορεί να περιέχει κυριολεκτικό κείμενο ή πεδία αντικατάστασης που οριοθετούνται από αγκύλες @code{@{@}}.  Κάθε πεδίο αντικατάστασης περιέχει είτε τον αριθμητικό δείκτη ενός ορίσματος θέσης, είτε το όνομα ενός keyword ορίσματος.  Επιστρέφει ένα αντίγραφο της συμβολοσειράς όπου κάθε πεδίο αντικατάστασης αντικαθίσταται με την τιμή της συμβολοσειράς του αντίστοιχου ορίσματος. Για παράδειγμα:

@example
>>> "The sum of 1 + 2 is @{0@}".format(1+2)
'The sum of 1 + 2 is 3'
>>> "The sum of @{a@} + @{b@} is @{answer@}".format(answer=1+2, a=1, b=2)
'The sum of 1 + 2 is 3'
>>> "@{1@} expects the @{0@} Inquisition!".format("Spanish", "Nobody")
'Nobody expects the Spanish Inquisition!'
@end example

Δείτε το @ref{173f,,Format string syntax} για μια περιγραφή των διαφόρων επιλογών μορφοποίησης που μπορούν να καθοριστούν στην μορφοποίηση συμβολοσειρών (format strings).

@cartouche
@quotation Σημείωση 
Κατά τη μορφοποίηση ενός αριθμού (@ref{326,,int}, @ref{327,,float}, @ref{328,,complex}, @ref{1c2,,decimal.Decimal} και υποκλάσεις) με τον τύπο @code{n} (π.χ.: @code{'@{:n@}'.format(1234)}, η συνάρτηση θέτει προσωρινά την τοποθεσία @code{LC_CTYPE} στην τοποθεσία @code{LC_NUMERIC} για την αποκωδικοποίηση των @code{decimal_point} και @code{thousands_sep} πεδίων του @code{localeconv()} αν είναι μη ASCII ή μεγαλύτερα από 1 byte, και το locale @code{LC_NUMERIC} είναι διαφορετικό από το locale @code{LC_CTYPE}.  Αυτή η προσωρινή αλλαγή επηρεάζει και άλλα νήματα (threads).
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.7: Κατά τη μορφοποίηση ενός αριθμού με τον τύπο @code{n}, η συνάρτηση θέτει προσωρινά το locale @code{LC_CTYPE} στο locale @code{LC_NUMERIC} σε κάποιες περιπτώσεις.

@end deffn

@geindex format_map() (μέθοδος της str)
@anchor{library/stdtypes str format_map}@anchor{1190}
@deffn {Μέθοδος} str.format_map (mapping, /)

Παρόμοιο με το @code{str.format(**mapping)}, εκτός από το ότι χρησιμοποιείται το @code{mapping} απευθείας και δεν αντιγράφεται σε μια @ref{188,,dict}.  Αυτό είναι χρήσιμο αν για παράδειγμα το @code{mapping} είναι μια υποκλάση του 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


Added in version 3.2.

@end deffn

@geindex index() (μέθοδος της str)
@anchor{library/stdtypes str index}@anchor{1bc6}
@deffn {Μέθοδος} str.index (sub[, start[, end]])

Like @ref{1259,,find()}, but raise @ref{277,,ValueError} when the substring is
not found. For example:

@example
>>> 'spam, spam, spam'.index('spam')
0
>>> 'spam, spam, spam'.index('eggs')
Traceback (most recent call last):
  File "<python-input-0>", line 1, in <module>
    'spam, spam, spam'.index('eggs')
    ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
ValueError: substring not found
@end example

See also @ref{15fc,,rindex()}.
@end deffn

@geindex isalnum() (μέθοδος της str)
@anchor{library/stdtypes str isalnum}@anchor{2825}
@deffn {Μέθοδος} str.isalnum ()

Return @code{True} if all characters in the string are alphanumeric and there is at
least one character, @code{False} otherwise.  A character @code{c} is alphanumeric if one
of the following returns @code{True}: @code{c.isalpha()}, @code{c.isdecimal()},
@code{c.isdigit()}, or @code{c.isnumeric()}. For example:

@example
>>> 'abc123'.isalnum()
True
>>> 'abc123!@@#'.isalnum()
False
>>> '@w{'}.isalnum()
False
>>> ' '.isalnum()
False
@end example
@end deffn

@geindex isalpha() (μέθοδος της str)
@anchor{library/stdtypes str isalpha}@anchor{281f}
@deffn {Μέθοδος} 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/Unicode17.0.0/core-spec/chapter-4/#G91002}.
For example:

@example
>>> 'Letters and spaces'.isalpha()
False
>>> 'LettersOnly'.isalpha()
True
>>> 'µ'.isalpha()  # non-ASCII characters can be considered alphabetical too
True
@end example

Δείτε @ref{2845,,Unicode Properties}.
@end deffn

@geindex isascii() (μέθοδος της str)
@anchor{library/stdtypes str isascii}@anchor{eb7}
@deffn {Μέθοδος} str.isascii ()

Επιστρέφει @code{True} εάν η συμβολοσειρά (string) είναι κενή ή όλοι οι χαρακτήρες της συμβολοσειράς είναι ASCII, αλλιώς @code{False}. Οι χαρακτήρες ASCII έχουν σημεία κωδικοποίησης στην περιοχή U+0000-U+007F. Για παράδειγμα:

@example
>>> 'ASCII characters'.isascii()
True
>>> 'µ'.isascii()
False
@end example


Added in version 3.7.

@end deffn

@geindex isdecimal() (μέθοδος της str)
@anchor{library/stdtypes str isdecimal}@anchor{2821}
@deffn {Μέθοδος} str.isdecimal ()

Επιστρέφει @code{True} αν όλοι οι χαρακτήρες στη συμβολοσειρά (string) είναι δεκαδικοί χαρακτήρες και υπάρχει τουλάχιστον ένας χαρακτήρας, διαφορετικά @code{False}. Οι δεκαδικοί χαρακτήρες είναι αυτοί που μπορούν να χρησιμοποιηθούν για το σχηματισμό αριθμών στη βάση 10, π.χ. U+0660, ARABIC-INDIC DIGIT ZERO.  Επίσημα ένας δεκαδικός χαρακτήρας είναι ένας χαρακτήρας του Unicode General Category «Nd». Για παράδειγμα:

@example
>>> '0123456789'.isdecimal()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isdecimal()  # Arabic-Indic digits zero to nine
True
>>> 'alphabetic'.isdecimal()
False
@end example
@end deffn

@geindex isdigit() (μέθοδος της str)
@anchor{library/stdtypes str isdigit}@anchor{2822}
@deffn {Μέθοδος} str.isdigit ()

Επιστρέφει @code{True} αν όλοι οι χαρακτήρες στη συμβολοσειρά είναι ψηφία και υπάρχει τουλάχιστον ένας χαρακτήρας, διαφορετικά @code{False}.  Τα ψηφία περιλαμβάνουν δεκαδικούς χαρακτήρες και ψηφία που χρειάζονται ειδικό χειρισμό, όπως τα compatibility superscript ψηφία. Αυτό καλύπτει τα ψηφία που δεν μπορούν να χρησιμοποιηθούν για το σχηματισμό αριθμών στη βάση 10, όπως οι αριθμοί Kharosthi.  Τυπικά, ένα ψηφίο είναι ένας χαρακτήρας που έχει την τιμή της ιδιότητας Numeric_Type=Digit ή Numeric_Type=Decimal.
@end deffn

@geindex isidentifier() (μέθοδος της str)
@anchor{library/stdtypes str isidentifier}@anchor{1f3a}
@deffn {Μέθοδος} str.isidentifier ()

Επιστρέφει @code{True} αν η συμβολοσειρά είναι έγκυρο αναγνωριστικό σύμφωνα με το ορισμό της γλώσσας, ενότητα @ref{2491,,Ονόματα (αναγνωριστικά και λέξεις-κλειδιά)}.

το @ref{2846,,keyword.iskeyword()} μπορεί να χρησιμοποιηθεί για να ελέγξει αν η συμβολοσειρά @code{s} είναι ένα δεσμευμένο αναγνωριστικό, όπως τα @ref{17fc,,def} και @ref{167c,,class}.

Παράδειγμα

@example
>>> from keyword import iskeyword

>>> 'hello'.isidentifier(), iskeyword('hello')
(True, False)
>>> 'def'.isidentifier(), iskeyword('def')
(True, True)
@end example
@end deffn

@geindex islower() (μέθοδος της str)
@anchor{library/stdtypes str islower}@anchor{2827}
@deffn {Μέθοδος} str.islower ()

Επιστρέφει @code{True} αν όλοι οι χαρακτήρες @footnote{
Οι χαρακτήρες με πεζά είναι αυτοί με την ιδιότητα γενικής κατηγορίας να είναι ένας από τους «Lu» (Γράμμα, κεφαλαίο), «Ll» (Γράμμα, πεζά), ή «Lt» (Γράμμα, κεφαλαία).
} στο αλφαριθμητικό (string) είναι πεζοί και υπάρχει τουλάχιστον ένας cased χαρακτήρας, αλλιώς @code{False}.
@end deffn

@geindex isnumeric() (μέθοδος της str)
@anchor{library/stdtypes str isnumeric}@anchor{2824}
@deffn {Μέθοδος} str.isnumeric ()

Return @code{True} if all characters in the string are numeric
characters, and there is at least one character, @code{False}
otherwise. Numeric characters include digit characters, and all characters
that have the Unicode numeric value property, e.g. U+2155,
VULGAR FRACTION ONE FIFTH.  Formally, numeric characters are those with the property
value Numeric_Type=Digit, Numeric_Type=Decimal or Numeric_Type=Numeric.
For example:

@example
>>> '0123456789'.isnumeric()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isnumeric()  # Arabic-indic digit zero to nine
True
>>> '⅕'.isnumeric()  # Vulgar fraction one fifth
True
>>> '²'.isdecimal(), '²'.isdigit(),  '²'.isnumeric()
(False, True, True)
@end example

See also @ref{2821,,isdecimal()} and @ref{2822,,isdigit()}. Numeric characters are
a superset of decimal numbers.
@end deffn

@geindex isprintable() (μέθοδος της str)
@anchor{library/stdtypes str isprintable}@anchor{1191}
@deffn {Μέθοδος} str.isprintable ()

Επιστρέφει @code{True} αν όλοι οι χαρακτήρες στη συμβολοσειρά μπορούν να εκτυπωθούν, @code{False} εάν περιέχει τουλάχιστον έναν μη εκτυπώσιμο χαρακτήρα.

Εδώ «εκτυπώσιμος» σημαίνει ότι ο χαρακτήρας είναι κατάλληλος για την @ref{45b,,repr()} για χρήση στην έξοδο του∙ το «μη εκτυπώσιμος» σημαίνει ότι ο χαρακτήρας στη @code{repr()} στους ενσωματωμένους τύπους θα διαφεύγει εξαγωνικά από τον χαρακτήρα. Δεν έχει καμία σχέση με τον χειρισμό συμβολοσειρών που γράφονται σε @ref{e9c,,sys.stdout} ή @ref{d05,,sys.stderr}.

Οι εκτυπώσιμοι χαρακτήρες είναι αυτοί που στη βάση δεδομένων χαρακτήρων Unicode (βλ. @ref{10e,,unicodedata}) έχουν μια γενική κατηγορία στην ομάδα Γράμμα, Σήμα, Αριθμός, Σημεία στίξης ή Σύμβολο (L, M, N, P ή S), συν το διάστημα ASCII 0x20. Οι μη εκτυπώσιμοι χαρακτήρες είναι αυτοί που βρίσκονται στο χώρο Διαχωρισμού ομάδας ή Άλλο (Z ή CII).

Για παράδειγμα:

@example
>>> '@w{'}.isprintable(), ' '.isprintable()
(True, True)
>>> '\t'.isprintable(), '\n'.isprintable()
(False, False)
@end example

See also @ref{282d,,isspace()}.
@end deffn

@geindex isspace() (μέθοδος της str)
@anchor{library/stdtypes str isspace}@anchor{282d}
@deffn {Μέθοδος} str.isspace ()

Επιστρέφει @code{True} αν υπάρχουν μόνο χαρακτήρες κενού (whitespace) στο αλφαριθμητικό (string) και υπάρχει τουλάχιστον ένας χαρακτήρας, διαφορετικά @code{False}.

Για παράδειγμα:

@example
>>> '@w{'}.isspace()
False
>>> ' '.isspace()
True
>>> '\t\n'.isspace() # TAB and BREAK LINE
True
>>> '\u3000'.isspace() # IDEOGRAPHIC SPACE
True
@end example

Ένας χαρακτήρας είναι `whitespace' εάν στη βάση δεδομένων χαρακτήρων Unicode (βλέπε @ref{10e,,unicodedata}), είτε η γενική κατηγορία του είναι @code{Zs} («Separator, space»), είτε η αμφίδρομη κατηγορία του είναι μία από τις κατηγορίες @code{WS}, @code{B}, ή @code{S}.

See also @ref{1191,,isprintable()}.
@end deffn

@geindex istitle() (μέθοδος της str)
@anchor{library/stdtypes str istitle}@anchor{282b}
@deffn {Μέθοδος} str.istitle ()

Επιστρέφει @code{True} αν η συμβολοσειρά (string) είναι μια titlecased συμβολοσειρά και υπάρχει τουλάχιστον ένας χαρακτήρας, για παράδειγμα, οι κεφαλαίοι χαρακτήρες μπορούν να ακολουθούν μόνο τους uncased χαρακτήρες και οι πεζοί χαρακτήρες μόνο cased χαρακτήρες.  Διαφορετικά, επιστρέφει @code{False}.

Για παράδειγμα:

@example
>>> 'Spam, Spam, Spam'.istitle()
True
>>> 'spam, spam, spam'.istitle()
False
>>> 'SPAM, SPAM, SPAM'.istitle()
False
@end example

Δείτε επίσης @ref{2834,,title()}.
@end deffn

@geindex isupper() (μέθοδος της str)
@anchor{library/stdtypes str isupper}@anchor{2829}
@deffn {Μέθοδος} str.isupper ()

Επιστρέφει @code{True} αν όλοι οι χαρακτήρες @footnote{
Οι χαρακτήρες με πεζά είναι αυτοί με την ιδιότητα γενικής κατηγορίας να είναι ένας από τους «Lu» (Γράμμα, κεφαλαίο), «Ll» (Γράμμα, πεζά), ή «Lt» (Γράμμα, κεφαλαία).
} στο αλφαριθμητικό είναι κεφαλαίοι και υπάρχει τουλάχιστον ένας cased χαρακτήρας, διαφορετικά @code{False}.

@example
>>> 'BANANA'.isupper()
True
>>> 'banana'.isupper()
False
>>> 'baNana'.isupper()
False
>>> ' '.isupper()
False
@end example
@end deffn

@geindex join() (μέθοδος της str)
@anchor{library/stdtypes meth-str-join}@anchor{2847}@anchor{library/stdtypes str join}@anchor{2803}
@deffn {Μέθοδος} str.join (iterable, /)

Επιστρέφει μια συμβολοσειρά (string) που είναι η συνένωση των συμβολοσειρών στο `iterable'. Ένα @ref{291,,TypeError} θα γίνει raise αν υπάρχουν τιμές μη συμβολοσειράς (non-string) στο `iterable', συμπεριλαμβανομένων των αντικειμένων @ref{1c7,,bytes}.  Το διαχωριστικό μεταξύ των στοιχείων είναι η συμβολοσειρά που παρέχει αυτή η μέθοδος. Για παράδειγμα:

@example
>>> ', '.join(['spam', 'spam', 'spam'])
'spam, spam, spam'
>>> '-'.join('Python')
'P-y-t-h-o-n'
@end example

Δείτε επίσης @ref{125b,,split()}.
@end deffn

@geindex ljust() (μέθοδος της str)
@anchor{library/stdtypes str ljust}@anchor{2251}
@deffn {Μέθοδος} str.ljust (width, fillchar=' ', /)

Επιστρέφει τη συμβολοσειρά (string) με αριστερή ευθυγράμμιση σε μια συμβολοσειρά μήκους `width'. Το padding γίνεται με τη χρήση του καθορισμένου `fillchar' (το default είναι ένα κενό ASCII). Η αρχική συμβολοσειρά επιστρέφεται εάν το `width' είναι μικρότερο ή ίσο με το @code{len(s)}.

Για παράδειγμα:

@example
>>> 'Python'.ljust(10)
'Python    '
>>> 'Python'.ljust(10, '.')
'Python....'
>>> 'Monty Python'.ljust(10, '.')
'Monty Python'
@end example

See also @ref{2250,,rjust()}.
@end deffn

@geindex lower() (μέθοδος της str)
@anchor{library/stdtypes str lower}@anchor{1965}
@deffn {Μέθοδος} str.lower ()

Return a copy of the string with all the cased characters @footnote{
Οι χαρακτήρες με πεζά είναι αυτοί με την ιδιότητα γενικής κατηγορίας να είναι ένας από τους «Lu» (Γράμμα, κεφαλαίο), «Ll» (Γράμμα, πεζά), ή «Lt» (Γράμμα, κεφαλαία).
} converted to
lowercase. For example:

@example
>>> 'Lower Method Example'.lower()
'lower method example'
@end example

The lowercasing algorithm used is described in section 3.13.2 'Default Case Conversion' of the Unicode Standard@footnote{https://www.unicode.org/versions/Unicode17.0.0/core-spec/chapter-3/#G34078}.
@end deffn

@geindex lstrip() (μέθοδος της str)
@anchor{library/stdtypes str lstrip}@anchor{1852}
@deffn {Μέθοδος} str.lstrip (chars=None, /)

Επιστρέφει ένα αντίγραφο της συμβολοσειράς (string) με την αφαίρεση των αρχικών χαρακτήρων.  Τα `chars' είναι μια συμβολοσειρά  που καθορίζει το σύνολο των χαρακτήρων που πρέπει να αφαιρεθούν.  Εάν παραλειφθεί ή είναι @code{None}, το όρισμα `chars' έχει ως default την αφαίρεση των κενών χαρακτήρων.  Το όρισμα `chars' δεν είναι ένα πρόθεμα· οπότε, όλοι οι συνδυασμοί των τιμών του αφαιρούνται:

@example
>>> '   spacious   '.lstrip()
'spacious   '
>>> 'www.example.com'.lstrip('cmowz.')
'example.com'
@end example

Δείτε την @ref{ca1,,str.removeprefix()} για μια μέθοδο που θα αφαιρέσει ένα μόνο πρόθεμα συμβολοσειράς (string) αντί για όλο το σύνολο των χαρακτήρων.  Για παράδειγμα:

@example
>>> 'Arthur: three!'.lstrip('Arthur: ')
'ee!'
>>> 'Arthur: three!'.removeprefix('Arthur: ')
'three!'
@end example
@end deffn

@geindex maketrans() (στατική μέθοδος της str)
@anchor{library/stdtypes str maketrans}@anchor{187}
@deffn {Μέθοδος} static str.maketrans (dict, /)

@deffnx {Μέθοδος} static str.maketrans (from, to, remove='@w{'}, /)

Αυτή η στατική μέθοδος επιστρέφει έναν πίνακα μεταφράσεων που μπορεί να χρησιμοποιηθεί για το @ref{1979,,str.translate()}.

Εάν υπάρχει μόνο ένα όρισμα, πρέπει να είναι ένα λεξικό αντιστοίχισης Unicode ordinals (ακέραιοι αριθμοί) ή χαρακτήρες (συμβολοσειρές - strings μήκους 1) σε ordinals Unicode, συμβολοσειρές (αυθαίρετου μήκους) ή @code{None}.  Τα κλειδιά χαρακτήρων τότε θα μετατραπούν σε κανονικούς αριθμούς.

Εάν υπάρχουν δύο ορίσματα, πρέπει να είναι συμβολοσειρές (strings) ίσου μήκους και στο λεξικό (dictionary) που θα προκύψει, κάθε χαρακτήρας στο `from' θα αντιστοιχιστεί στο χαρακτήρα στην ίδια θέση στο `to'. Αν υπάρχει τρίτο όρισμα, πρέπει να είναι συμβολοσειρά, του οποίου οι χαρακτήρες θα αντιστοιχιστούν στο αποτέλεσμα σε @code{None}.


Άλλαξε στην έκδοση 3.15: `dict' can now be a @ref{182,,frozendict}.

@end deffn

@geindex partition() (μέθοδος της str)
@anchor{library/stdtypes str partition}@anchor{125c}
@deffn {Μέθοδος} str.partition (sep, /)

Διαχωρίστε τη συμβολοσειρά (string) στην πρώτη εμφάνιση του `sep', και επιστρέφει ένα 3-tuple που περιέχει το μέρος πριν από το διαχωριστικό, το ίδιο το διαχωριστικό και το μέρος μετά το διαχωριστικό.  Αν ο διαχωριστής δεν βρεθεί, επιστρέφει ένα 3-σύνολο που περιέχει την ίδια τη συμβολοσειρά, ακολουθούμενη από δύο κενές συμβολοσειρές.

Για παράδειγμα:

@example
>>> 'Monty Python'.partition(' ')
('Monty', ' ', 'Python')
>>> "Monty Python's Flying Circus".partition(' ')
('Monty', ' ', "Python's Flying Circus")
>>> 'Monty Python'.partition('-')
('Monty Python', '@w{'}, '@w{'})
@end example

See also @ref{15fd,,rpartition()}.
@end deffn

@geindex removeprefix() (μέθοδος της str)
@anchor{library/stdtypes str removeprefix}@anchor{ca1}
@deffn {Μέθοδος} str.removeprefix (prefix, /)

If the string starts with the `prefix' string, return
@code{string[len(prefix):]}. Otherwise, return a copy of the original
string:

@example
>>> 'TestHook'.removeprefix('Test')
'Hook'
>>> 'BaseTestCase'.removeprefix('Test')
'BaseTestCase'
@end example


Added in version 3.9.


See also @ref{ca2,,removesuffix()} and @ref{1279,,startswith()}.
@end deffn

@geindex removesuffix() (μέθοδος της str)
@anchor{library/stdtypes str removesuffix}@anchor{ca2}
@deffn {Μέθοδος} str.removesuffix (suffix, /)

If the string ends with the `suffix' string and that `suffix' is not empty,
return @code{string[:-len(suffix)]}. Otherwise, return a copy of the
original string:

@example
>>> 'MiscTests'.removesuffix('Tests')
'Misc'
>>> 'TmpDirMixin'.removesuffix('Tests')
'TmpDirMixin'
@end example


Added in version 3.9.


See also @ref{ca1,,removeprefix()} and @ref{127a,,endswith()}.
@end deffn

@geindex replace() (μέθοδος της str)
@anchor{library/stdtypes str replace}@anchor{6c0}
@deffn {Μέθοδος} 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.
For example:

@example
>>> 'spam, spam, spam'.replace('spam', 'eggs')
'eggs, eggs, eggs'
>>> 'spam, spam, spam'.replace('spam', 'eggs', 1)
'eggs, spam, spam'
@end example


Άλλαξε στην έκδοση 3.13: Το `count' υποστηρίζεται πλέον ως όρισμα λέξης-κλειδιού.

@end deffn

@geindex rfind() (μέθοδος της str)
@anchor{library/stdtypes str rfind}@anchor{125a}
@deffn {Μέθοδος} str.rfind (sub[, start[, end]])

Return the highest index in the string where substring `sub' is found, such
that `sub' is contained within @code{s[start:end]}.  Optional arguments `start'
and `end' are interpreted as in slice notation.  Return @code{-1} on failure.
For example:

@example
>>> 'spam, spam, spam'.rfind('sp')
12
>>> 'spam, spam, spam'.rfind('sp', 0, 10)
6
@end example

See also @ref{1259,,find()} and @ref{15fc,,rindex()}.
@end deffn

@geindex rindex() (μέθοδος της str)
@anchor{library/stdtypes str rindex}@anchor{15fc}
@deffn {Μέθοδος} str.rindex (sub[, start[, end]])

Like @ref{125a,,rfind()} but raises @ref{277,,ValueError} when the substring `sub' is not
found.
For example:

@example
>>> 'spam, spam, spam'.rindex('spam')
12
>>> 'spam, spam, spam'.rindex('eggs')
Traceback (most recent call last):
  File "<stdin-0>", line 1, in <module>
    'spam, spam, spam'.rindex('eggs')
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
ValueError: substring not found
@end example

See also @ref{1bc6,,index()} and @ref{1259,,find()}.
@end deffn

@geindex rjust() (μέθοδος της str)
@anchor{library/stdtypes str rjust}@anchor{2250}
@deffn {Μέθοδος} str.rjust (width, fillchar=' ', /)

Επιστρέφει τη συμβολοσειρά (string) με δεξιό προσανατολισμό σε μια συμβολοσειρά μήκους `width'. Το padding γίνεται χρησιμοποιώντας το καθορισμένο `fillchar' (η προεπιλογή είναι ένα διάστημα ASCII). Η αρχική συμβολοσειρά επιστρέφεται εάν το `width' είναι μικρότερο ή ίσο με @code{len(s)}.

Για παράδειγμα:

@example
>>> 'Python'.rjust(10)
'    Python'
>>> 'Python'.rjust(10, '.')
'....Python'
>>> 'Monty Python'.rjust(10, '.')
'Monty Python'
@end example

See also @ref{2251,,ljust()} and @ref{1854,,zfill()}.
@end deffn

@geindex rpartition() (μέθοδος της str)
@anchor{library/stdtypes str rpartition}@anchor{15fd}
@deffn {Μέθοδος} str.rpartition (sep, /)

Διαχωρίζει τη συμβολοσειρά (string) στην τελευταία εμφάνιση του `sep' και επιστρέφει ένα 3-tuple που περιέχει το τμήμα πριν από το διαχωριστικό, το ίδιο το διαχωριστικό και το μέρος μετά το διαχωριστικό.  Εάν το διαχωριστικό δεν βρεθεί, επιστρέφει ένα 3-tuple που περιέχει δύο κενές συμβολοσειρές, ακολουθούμενες από την ίδια τη συμβολοσειρά.

Για παράδειγμα:

@example
>>> 'Monty Python'.rpartition(' ')
('Monty', ' ', 'Python')
>>> "Monty Python's Flying Circus".rpartition(' ')
("Monty Python's Flying", ' ', 'Circus')
>>> 'Monty Python'.rpartition('-')
('@w{'}, '@w{'}, 'Monty Python')
@end example

See also @ref{125c,,partition()}.
@end deffn

@geindex rsplit() (μέθοδος της str)
@anchor{library/stdtypes str rsplit}@anchor{15fa}
@deffn {Μέθοδος} str.rsplit (sep=None, maxsplit=-1)

Επιστρέφει μια λίστα με τις λέξεις στη συμβολοσειρά (string), χρησιμοποιώντας το `sep' ως οριοθέτη. Εάν δοθεί το `maxsplit', θα γίνουν το πολύ `maxsplit' διαχωρισμοί, ξεκινώντας από τα δεξιά.  Εάν το `sep' δεν έχει καθοριστεί ή είναι @code{None}, οποιοδήποτε κενό διάστημα γίνεται διαχωριστικό. Εκτός από το διαχωρισμό από τα δεξιά, η @ref{15fa,,rsplit()} συμπεριφέρεται όπως η @ref{125b,,split()} που περιγράφεται λεπτομερώς παρακάτω.
@end deffn

@geindex rstrip() (μέθοδος της str)
@anchor{library/stdtypes str rstrip}@anchor{1853}
@deffn {Μέθοδος} str.rstrip (chars=None, /)

Return a copy of the string with trailing characters removed.  The `chars'
argument is a string specifying the set of characters to be removed.  If omitted
or @code{None}, the `chars' argument defaults to removing whitespace.  The `chars'
argument is not a suffix; rather, all combinations of its values are stripped.
For example:

@example
>>> '   spacious   '.rstrip()
'   spacious'
>>> 'mississippi'.rstrip('ipz')
'mississ'
@end example

See @ref{ca2,,removesuffix()} for a method that will remove a single suffix
string rather than all of a set of characters.  For example:

@example
>>> 'Monty Python'.rstrip(' Python')
'M'
>>> 'Monty Python'.removesuffix(' Python')
'Monty'
@end example

See also @ref{1851,,strip()}.
@end deffn

@geindex split() (μέθοδος της str)
@anchor{library/stdtypes str split}@anchor{125b}
@deffn {Μέθοδος} str.split (sep=None, maxsplit=-1)

Επιστρέφει μια λίστα με τις λέξεις της συμβολοσειράς (string), χρησιμοποιώντας το `sep' ως διαχωριστικό.  Αν δοθεί το `maxsplit', γίνονται το πολύ `maxsplit' διαχωρισμοί (έτσι, η λίστα θα έχει το πολύ @code{maxsplit+1} στοιχεία).  Εάν το `maxsplit' δεν καθοριστεί ή είναι @code{-1}, τότε δεν υπάρχει όριο στον αριθμό των διαχωρισμών (γίνονται όλες οι πιθανές διασπάσεις).

Αν δοθεί το `sep', οι διαδοχικά οριοθέτες δεν ομαδοποιούνται μαζί και θεωρείται ότι οριοθετούν κενές συμβολοσειρές (strings) (για παράδειγμα, το @code{'1,,2'.split(',')} επιστρέφει @code{['1', '@w{'}, '2']}).  Το όρισμα `sep' μπορεί να αποτελείται από πολλούς χαρακτήρες ως μεμονωμένο οριοθέτη (για διαχωρισμό με πολλαπλούς οριοθέτες, χρησιμοποιήστε την @ref{7a0,,re.split()}). Ο διαχωρισμός μιας κενής συμβολοσειράς με ένα καθορισμένο διαχωριστικό επιστρέφει το @code{['@w{'}]}.

Για παράδειγμα:

@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

Αν το `sep' καθοριστεί ή είναι @code{None}, εφαρμόζεται ένας διαφορετικός αλγόριθμος διαχωρισμού: οι εμφανίσεις διαδοχικών κενών θεωρούνται ως ένα ενιαίο διαχωριστικό, και το αποτέλεσμα δεν θα περιέχει κενές συμβολοσειρές (strings) στην αρχή ή στο τέλος, αν η συμβολοσειρά έχει κενό διάστημα στην αρχή ή στο τέλος.  Κατά συνέπεια, η διάσπαση μιας κενής συμβολοσειράς ή μιας συμβολοσειράς που αποτελείται μόνο από κενά διαστήματα με ένα @code{None} ως διαχωριστικό επιστρέφει @code{[]}.

Για παράδειγμα:

@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

Εάν δεν καθοριστεί `sep' ή είναι @code{None} και το `maxsplit' είναι @code{0}, λαμβάνοντας υπόψη μόνο οι πρώτες εκτελέσεις διαδοχικού κενού διαστήματος.

Για παράδειγμα:

@example
>>> "".split(None, 0)
[]
>>> "   ".split(None, 0)
[]
>>> "   foo   ".split(maxsplit=0)
['foo   ']
@end example

Δείτε επίσης @ref{2803,,join()}.
@end deffn

@geindex καθολικές νέες γραμμές;μέθοδος str.splitlines

@geindex splitlines() (μέθοδος της str)
@anchor{library/stdtypes str splitlines}@anchor{15fb}
@deffn {Μέθοδος} str.splitlines (keepends=False)

Επιστρέφει μια λίστα με τις γραμμές της συμβολοσειράς (string), διαχωρίζοντας στα όρια των γραμμών.  Τα διαχωριστικά των γραμμών δεν περιλαμβάνονται στην νέα λίστα, εκτός αν δοθεί το `keepends' και είναι true.

Αυτή η μέθοδος διαχωρίζει στα ακόλουθα όρια γραμμών.  Πιο συγκεκριμένα, τα όρια είναι ένα υπερσύνολο του @ref{10f1,,universal newlines}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Αναπαράσταση

@tab

Περιγραφή

@item

@code{\n}

@tab

Line Feed

@item

@code{\r}

@tab

Carriage Return

@item

@code{\r\n}

@tab

Carriage Return + Line Feed

@item

@code{\v} or @code{\x0b}

@tab

Line Tabulation

@item

@code{\f} or @code{\x0c}

@tab

Form Feed

@item

@code{\x1c}

@tab

Διαχωριστής Αρχείου

@item

@code{\x1d}

@tab

Διαχωριστής Group

@item

@code{\x1e}

@tab

Διαχωριστής Εγγραφών

@item

@code{\x85}

@tab

Επόμενη Γραμμή (C1 Control Code)

@item

@code{\u2028}

@tab

Διαχωριστής Γραμμής

@item

@code{\u2029}

@tab

Διαχωριστής Παραγράφου

@end multitable



Άλλαξε στην έκδοση 3.2: Τα @code{\v} και @code{\f} προστίθενται στην λίστα ορίων των γραμμών.


Για παράδειγμα:

@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

Σε αντίθεση με την @ref{125b,,split()} όταν δίνεται μια συμβολοσειρά (string) οριοθέτησης `sep', αυτή η μέθοδος επιστρέφει μια κενή λίστα για το κενό αλφαριθμητικό, και μια τερματικό break γραμμής δεν οδηγεί σε μια επιπλέον γραμμή:

@example
>>> "".splitlines()
[]
>>> "One line\n".splitlines()
['One line']
@end example

Συγκριτικά, η @code{split('\n')} δίνει:

@example
>>> '@w{'}.split('\n')
['@w{'}]
>>> 'Two lines\n'.split('\n')
['Two lines', '@w{'}]
@end example
@end deffn

@geindex startswith() (μέθοδος της str)
@anchor{library/stdtypes str startswith}@anchor{1279}
@deffn {Μέθοδος} str.startswith (prefix[, start[, end]])

Επιστρέφει @code{True} αν η συμβολοσειρά (string) αρχίζει με το `prefix', αλλιώς επιστρέφει @code{False}. Το `prefix' μπορεί επίσης να είναι μια πλειάδα (tuple) prefix προς αναζήτηση.  Με το προαιρετικό `start', ελέγχεται το αλφαριθμητικό που αρχίζει από τη συγκεκριμένη θέση.  Με το προαιρετικό `end', σταματά η σύγκριση της συμβολοσειράς σε αυτή τη θέση.

Για παράδειγμα:

@example
>>> 'Python'.startswith('Py')
True
>>> 'a tuple of prefixes'.startswith(('at', 'a'))
True
>>> 'Python is amazing'.startswith('is', 7)
True
@end example

See also @ref{127a,,endswith()} and @ref{ca1,,removeprefix()}.
@end deffn

@geindex strip() (μέθοδος της str)
@anchor{library/stdtypes str strip}@anchor{1851}
@deffn {Μέθοδος} str.strip (chars=None, /)

Return a copy of the string with the leading and trailing characters removed.
The `chars' argument is a string specifying the set of characters to be removed.
If omitted or @code{None}, the `chars' argument defaults to removing whitespace.
The `chars' argument is not a prefix or suffix; rather, all combinations of its
values are stripped.

Για παράδειγμα:

@example
>>> '   spacious   '.strip()
'spacious'
>>> 'www.example.com'.strip('cmowz.')
'example'
@end example

The outermost leading and trailing `chars' argument values are stripped
from the string. Characters are removed from the leading end until
reaching a string character that is not contained in the set of
characters in `chars'. A similar action takes place on the trailing end.

Για παράδειγμα:

@example
>>> comment_string = '#....... Section 3.2.1 Issue #32 .......'
>>> comment_string.strip('.#! ')
'Section 3.2.1 Issue #32'
@end example

See also @ref{1853,,rstrip()}.
@end deffn

@geindex swapcase() (μέθοδος της str)
@anchor{library/stdtypes str swapcase}@anchor{2836}
@deffn {Μέθοδος} str.swapcase ()

Return a copy of the string with uppercase characters converted to lowercase and
vice versa. For example:

@example
>>> 'Hello World'.swapcase()
'hELLO wORLD'
@end example

Note that it is not necessarily true that @code{s.swapcase().swapcase() == s}.
For example:

@example
>>> 'straße'.swapcase().swapcase()
'strasse'
@end example

See also @ref{1965,,str.lower()} and @ref{2830,,str.upper()}.
@end deffn

@geindex title() (μέθοδος της str)
@anchor{library/stdtypes str title}@anchor{2834}
@deffn {Μέθοδος} str.title ()

Επιστρέφει μια titlecased έκδοση της συμβολοσειράς, όπου οι λέξεις ξεκινούν με ένα κεφαλαίο χαρακτήρα και οι υπόλοιποι χαρακτήρες είναι πεζοί.

Για παράδειγμα:

@example
>>> 'Hello world'.title()
'Hello World'
@end example

Ο αλγόριθμος χρησιμοποιεί έναν απλό, ανεξάρτητο από τη γλώσσα, ορισμό μιας λέξης ως group διαδοχικών γραμμάτων.  Ο ορισμός λειτουργεί σε πολλά contexts, αλλά σημαίνει ότι οι απόστροφοι σε συναιρέσεις και κτητικές λέξεις αποτελούν όρια λέξεων, που μπορεί να μην είναι το επιθυμητό αποτέλεσμα:

@example
>>> "they're bill's friends from the UK".title()
"They'Re Bill'S Friends From The Uk"
@end example

Η συνάρτηση @ref{2848,,string.capwords()} δεν έχει αυτό το πρόβλημα, καθώς χωρίζει τις λέξεις μόνο σε κενά.

Εναλλακτικά, μπορεί να κατασκευαστεί μια λύση για τις αποστρόφους χρησιμοποιώντας κανονικές εκφράσεις:

@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

Δείτε επίσης @ref{282b,,istitle()}.
@end deffn

@geindex translate() (μέθοδος της str)
@anchor{library/stdtypes str translate}@anchor{1979}
@deffn {Μέθοδος} str.translate (table, /)

Επιστρέφει ένα αντίγραφο της συμβολοσειράς (string) στο οποίο κάθε χαρακτήρας έχει αντιστοιχιστεί μέσω του πίνακα μετάφρασης.  Ο πίνακας πρέπει να είναι ένα αντικείμενο που υλοποιεί ευρετηριοποίηση μέσω της @ref{787,,__getitem__()}, συνήθως ένα @ref{1564,,mapping} ή ένα @ref{8ff,,sequence}.  Όταν το indexing γίνεται με ένα Unicode ordinal (ένας ακέραιος), το αντικείμενο του πίνακα μπορεί να κάνει οποιοδήποτε από τα ακόλουθα: να επιστρέψει ένα Unicode ordinal ή μια συμβολοσειρά (string), να αντιστοιχίσει τον χαρακτήρα σε έναν ή περισσότερους άλλους χαρακτήρες· να επιστρέψει @code{None}, για να διαγράψει τον χαρακτήρα από τη συμβολοσειρά που επιστρέφεται· ή να κάνει raise ένα @ref{25da,,LookupError}, για να αντιστοιχίσει τον χαρακτήρα στον εαυτό του.

Μπορείτε να χρησιμοποιήσετε το @ref{187,,str.maketrans()} για να δημιουργήσετε ένα χάρτη μετάφρασης αντιστοίχισης από χαρακτήρα-σε-χαρακτήρα σε διαφορετικές μορφές.

The following example uses a mapping to replace @code{'a'} with @code{'X'},
@code{'b'} with @code{'Y'}, and delete @code{'c'}:

@example
>>> 'abc123'.translate(@{ord('a'): 'X', ord('b'): 'Y', ord('c'): None@})
'XY123'
@end example

Δείτε επίσης την ενότητα @ref{1c,,codecs} για μια πιο ευέλικτη προσέγγιση σε προσαρμοσμένα mappings χαρακτήρων.
@end deffn

@geindex upper() (μέθοδος της str)
@anchor{library/stdtypes str upper}@anchor{2830}
@deffn {Μέθοδος} str.upper ()

Επιστρέφει ένα αντίγραφο της συμβολοσειράς (string) με όλους τους χαρακτήρες @footnote{
Οι χαρακτήρες με πεζά είναι αυτοί με την ιδιότητα γενικής κατηγορίας να είναι ένας από τους «Lu» (Γράμμα, κεφαλαίο), «Ll» (Γράμμα, πεζά), ή «Lt» (Γράμμα, κεφαλαία).
} που έχουν μετατραπεί σε κεφαλαία.  Σημειώστε ότι το @code{s.upper().isupper()} μπορεί να είναι @code{False} αν το @code{s} περιέχει χαρακτήρες χωρίς πεζά γράμματα ή αν η κατηγορία Unicode του προκύπτοντος χαρακτήρα(ων) δεν είναι  «Lu» (Γράμμα, κεφαλαίο), αλλά π.χ. «Lt» (Γράμμα, titlecase).

The uppercasing algorithm used is described in section 3.13.2 'Default Case Conversion' of the Unicode Standard@footnote{https://www.unicode.org/versions/Unicode17.0.0/core-spec/chapter-3/#G34078}.
@end deffn

@geindex zfill() (μέθοδος της str)
@anchor{library/stdtypes str zfill}@anchor{1854}
@deffn {Μέθοδος} str.zfill (width, /)

Επιστρέφει ένα αντίγραφο της συμβολοσειράς (string) που έμεινε γεμάτη με ψηφία ASCII @code{'0'`} για να δημιουργήσει μία συμβολοσειρά μήκους `width'. Χειρίζεται ένα leading sign prefix (@code{'+'}/@code{'-'}) εισάγοντας την συμπλήρωση `μετά' τον χαρακτήρα sign αντί για πριν. Η αρχική συμβολοσειρά επιστρέφεται εάν το `width' είναι μικρότερο ή ίσο με @code{len(s)}.

Για παράδειγμα:

@example
>>> "42".zfill(5)
'00042'
>>> "-42".zfill(5)
'-0042'
@end example

See also @ref{2250,,rjust()}.
@end deffn

@geindex ! μορφοποιημένη συμβολοσειρά κυριολεκτικής μορφής
@geindex μορφοποιημένες συμβολοσειρές κυριολεξίας
@geindex ! f-string
@geindex string
@geindex fstring
@geindex συμβολοσειρά κυριολεξίας με παρεμβολή
@geindex string;μορφοποιημένη κυριολεξία
@geindex string;κυριολεκτικό με παρεμβολή
@geindex @{@} (αγκύλες);μέσα σε μορφοποιημένη συμβολοσειρά
@geindex ! (Θαυμαστικό);μέσα σε μορφοποιημένη συμβολοσειρά
@geindex ; (άνω κάτω τελεία);μέσα σε μορφοποιημένη συμβολοσειρά
@geindex = (ίσο);για βοήθεια στην αποσφαλμάτωση μέσω κυριολεκτικών συμβολοσειρών

@node Διαμορφωμένες Κυριολεκτικές Συμβολοσειρές f-strings,Template String Literals t-strings,Μέθοδοι Συμβολοσειράς String,Τύπος Ακολουθίας Sequence Κειμένου — str
@anchor{library/stdtypes formatted-string-literals-f-strings}@anchor{2849}@anchor{library/stdtypes stdtypes-fstrings}@anchor{24dc}
@subsubsection Διαμορφωμένες Κυριολεκτικές Συμβολοσειρές (f-strings)



Added in version 3.6.



Άλλαξε στην έκδοση 3.7: Τα @ref{432,,await} και @ref{e70,,async for} μπορούν να χρησιμοποιηθούν σε εκφράσεις μέσα σε f-strings.



Άλλαξε στην έκδοση 3.8: Added the debug specifier (@code{=})



Άλλαξε στην έκδοση 3.12: Πολλοί περιορισμοί στις εκφράσεις μέσα σε f-strings έχουν αφαιρεθεί. Ιδιαίτερα, πλέον επιτρέπονται οι εμφωλευμένες συμβολοσειρές, τα σχόλια και οι κάθετοι.


An `f-string' (formally a `formatted string literal') is
a string literal that is prefixed with @code{f} or @code{F}.
This type of string literal allows embedding the results of arbitrary Python
expressions within `replacement fields', which are delimited by curly
brackets (@code{@{@}}).
Each replacement field must contain an expression, optionally followed by:


@itemize *

@item 
a `debug specifier' – an equal sign (@code{=});

@item 
a `conversion specifier' – @code{!s}, @code{!r} or @code{!a}; and/or

@item 
a `format specifier' prefixed with a colon (@code{:}).
@end itemize

See the @ref{43a,,Lexical Analysis section on f-strings} for details
on the syntax of these fields.

@menu
* Debug specifier:: 
* Conversion specifier:: 
* Format specifier:: 

@end menu

@node Debug specifier,Conversion specifier,,Διαμορφωμένες Κυριολεκτικές Συμβολοσειρές f-strings
@anchor{library/stdtypes debug-specifier}@anchor{284a}
@subsubsection Debug specifier



Added in version 3.8.


If a debug specifier – an equal sign (@code{=}) – appears after the replacement
field expression, the resulting f-string will contain the expression’s source,
the equal sign, and the value of the expression.
This is often useful for debugging:

@example
>>> number = 14.3
>>> f'@{number=@}'
'number=14.3'
@end example

Whitespace before, inside and after the expression, as well as whitespace
after the equal sign, is significant — it is retained in the result:

@example
>>> f'@{ number  -  4  = @}'
' number  -  4  = 10.3'
@end example

@node Conversion specifier,Format specifier,Debug specifier,Διαμορφωμένες Κυριολεκτικές Συμβολοσειρές f-strings
@anchor{library/stdtypes conversion-specifier}@anchor{284b}
@subsubsection Conversion specifier


By default, the value of a replacement field expression is converted to
a string using @ref{1df,,str()}:

@example
>>> from fractions import Fraction
>>> one_third = Fraction(1, 3)
>>> f'@{one_third@}'
'1/3'
@end example

When a debug specifier but no format specifier is used, the default conversion
instead uses @ref{45b,,repr()}:

@example
>>> f'@{one_third = @}'
'one_third = Fraction(1, 3)'
@end example

The conversion can be specified explicitly using one of these specifiers:


@itemize *

@item 
@code{!s} for @ref{1df,,str()}

@item 
@code{!r} for @ref{45b,,repr()}

@item 
@code{!a} for @ref{1789,,ascii()}
@end itemize

Για παράδειγμα:

@example
>>> str(one_third)
'1/3'
>>> repr(one_third)
'Fraction(1, 3)'

>>> f'@{one_third!s@} is @{one_third!r@}'
'1/3 is Fraction(1, 3)'

>>> string = "¡kočka 😸!"
>>> ascii(string)
"'\\xa1ko\\u010dka \\U0001f638!'"

>>> f'@{string = !a@}'
"string = '\\xa1ko\\u010dka \\U0001f638!'"
@end example

@node Format specifier,,Conversion specifier,Διαμορφωμένες Κυριολεκτικές Συμβολοσειρές f-strings
@anchor{library/stdtypes format-specifier}@anchor{284c}
@subsubsection Format specifier


After the expression has been evaluated, and possibly converted using an
explicit conversion specifier, it is formatted using the @ref{439,,format()} function.
If the replacement field includes a `format specifier' introduced by a colon
(@code{:}), the specifier is passed to @code{format()} as the second argument.
The result of @code{format()} is then used as the final value for the
replacement field. For example:

@example
>>> from fractions import Fraction
>>> one_third = Fraction(1, 3)
>>> f'@{one_third:.6f@}'
'0.333333'
>>> f'@{one_third:_^+10@}'
'___+1/3___'
>>> >>> f'@{one_third!r:_^20@}'
'___Fraction(1, 3)___'
>>> f'@{one_third = :~>10@}~'
'one_third = ~~~~~~~1/3~'
@end example

@node Template String Literals t-strings,printf-style String Formatting,Διαμορφωμένες Κυριολεκτικές Συμβολοσειρές f-strings,Τύπος Ακολουθίας Sequence Κειμένου — str
@anchor{library/stdtypes stdtypes-tstrings}@anchor{24e0}@anchor{library/stdtypes template-string-literals-t-strings}@anchor{284d}
@subsubsection Template String Literals (t-strings)


An `t-string' (formally a `template string literal') is
a string literal that is prefixed with @code{t} or @code{T}.

These strings follow the same syntax and evaluation rules as
@ref{24dc,,formatted string literals},
with for the following differences:


@itemize *

@item 
Rather than evaluating to a @code{str} object, template string literals evaluate
to a @ref{415,,string.templatelib.Template} object.

@item 
The @ref{439,,format()} protocol is not used.
Instead, the format specifier and conversions (if any) are passed to
a new @ref{416,,Interpolation} object that is created
for each evaluated expression.
It is up to code that processes the resulting @ref{415,,Template}
object to decide how to handle format specifiers and conversions.

@item 
Format specifiers containing nested replacement fields are evaluated eagerly,
prior to being passed to the @ref{416,,Interpolation} object.
For instance, an interpolation of the form @code{@{amount:.@{precision@}f@}} will
evaluate the inner expression @code{@{precision@}} to determine the value of the
@code{format_spec} attribute.
If @code{precision} were to be @code{2}, the resulting format specifier
would be @code{'.2f'}.

@item 
When the equals sign @code{'='} is provided in an interpolation expression,
the text of the expression is appended to the literal string that precedes
the relevant interpolation.
This includes the equals sign and any surrounding whitespace.
The @code{Interpolation} instance for the expression will be created as
normal, except that @ref{284e,,conversion} will
be set to “@code{r}” (@ref{45b,,repr()}) by default.
If an explicit conversion or format specifier are provided,
this will override the default behaviour.
@end itemize

@node printf-style String Formatting,,Template String Literals t-strings,Τύπος Ακολουθίας Sequence Κειμένου — str
@anchor{library/stdtypes old-string-formatting}@anchor{ab9}@anchor{library/stdtypes printf-style-string-formatting}@anchor{284f}
@subsubsection @code{printf}-style String Formatting


@geindex μορφοποίηση@comma{} string (%)
@geindex παρεμβολή@comma{} string (%)
@geindex string;μορφοποίηση@comma{} printf
@geindex string;παρεμβολή@comma{} printf
@geindex μορφοποίηση σε στυλ printf
@geindex μορφοποίηση σε στυλ sprintf
@geindex % (τοις εκατό);μορφοποίηση σε στυλ printf

@cartouche
@quotation Σημείωση 
Οι λειτουργίες μορφοποίησης που περιγράφονται εδώ παρουσιάζουν μια ποικιλία ιδιορρυθμιών που οδηγούν σε μια σειρά από κοινά σφάλματα (όπως η αποτυχία εμφάνισης των πλειάδων και των λεξικών σωστά).

Η χρήση των @ref{43a,,formatted string literals}, της διεπαφής @ref{a12,,str.format()} ή της @ref{a77,,string.Template} μπορεί να βοηθήσει στην αποφυγή αυτών των σφαλμάτων. Καθεμία από αυτές τις εναλλακτικές προσφέρει τους δικούς της συμβιβασμούς και πλεονεκτήματα ως προς την απλότητα, την ευελιξία και/ή την επεκτασιμότητα.
@end quotation
@end cartouche

Τα αντικείμενα string έχουν μια μοναδική ενσωματωμένη λειτουργία: τον τελεστή @code{%} (modulo). Αυτός είναι επίσης γνωστός ως τελεστής `formatting' ή * interpolation*. Δεδομένων των @code{format % values} (όπου `format' είναι μία συμβολοσειρά), @code{%} οι προδιαγραφές μετατροπής στο `format' αντικαθίστανται από μηδέν ή περισσότερα στοιχεία των `values'. Το αποτέλεσμα είναι παρόμοιο με τη χρήση του @code{sprintf()} στη γλώσσα C. Για παράδειγμα:

@example
>>> print('%s has %d quote types.' % ('Python', 2))
Python has 2 quote types.
@end example

Εάν το `format' απαιτεί ένα μεμονωμένο όρισμα, το `values' μπορεί να είναι ένα μεμονωμένο non-tuple αντικείμενο. @footnote{
Για να μορφοποιήσετε μόνο μια πλειάδα (tuple) θα πρέπει επομένως να παρέχετε μια πλειάδα singleton της οποίας το μόνο στοιχείο είναι η πλειάδα που πρόκειται να μορφοποιηθεί.
} Διαφορετικά, τα `values' πρέπει να είναι ένα tuple με ακριβώς τον ίδιο αριθμό των στοιχείων που καθορίζονται από το format string ή ένα μεμονωμένο αντικείμενο αντιστοίχισης (για παράδειγμα, ένα λεξικό).

@geindex () (παρενθέσεις);σε μορφοποίηση σε στυλ printf
@geindex * (αστερίσκος);σε μορφοποίηση σε στυλ printf
@geindex . (τελεία);σε μορφοποίηση σε στυλ printf

Ένας προσδιοριστής μετατροπής περιέχει δύο ή περισσότερους χαρακτήρες και έχει τους εξής components, οι οποίοι πρέπει να εμφανίζονται με αυτή τη σειρά:


@enumerate 

@item 
Ο χαρακτήρας @code{`%'@w{'}}, που σηματοδοτεί την αρχή του προσδιοριστή.

@item 
Κλειδί mapping (προαιρετικό), που αποτελείται από μια ακολουθία χαρακτήρων σε παρένθεση (για παράδειγμα, @code{(somename)}).

@item 
Δείκτες μετατροπής (προαιρετικό), που επηρεάζουν το αποτέλεσμα κάποιων τύπων μετατροπής.

@item 
Ελάχιστο πλάτος πεδίου (προαιρετικό). Εάν ορίζεται ως @code{'*'} (αστερίσκος), το πραγματικό πλάτος διαβάζεται από το επόμενο στοιχείο του tuple στα `values', και το αντικείμενο προς μετατροπή έρχεται μετά από το ελάχιστο πλάτος πεδίου και το προαιρετικό precision.

@item 
Ακρίβεια (προαιρετικό), δίνεται ως @code{'.'} (τελεία) ακολουθούμενη από το precision.Εάν ορίζεται ως @code{'*'} (αστερίσκος), το πραγματικό precision διαβάζεται από το επόμενο στοιχείο του tuple στα `values', και η τιμή προς μετατροπή έρχεται μετά το precision.

@item 
Μετατροπέας του length (προαιρετικό).

@item 
Τύπος conversion.
@end enumerate

Όταν το σωστό όρισμα είναι ένα λεξικό (ή άλλος τύπος αντιστοίχισης), τότε οι μορφές στη συμβολοσειρά `πρέπει' να περιλαμβάνουν ένα κλειδί αντιστοίχισης σε παρένθεση σε αυτό το λεξικό που εισήχθη αμέσως μετά τον χαρακτήρα @code{'%'}. Το κλειδί αντιστοίχισης επιλέγει την τιμή που θα μορφοποιηθεί από την αντιστοίχιση.  Για παράδειγμα:

@example
>>> print('%(language)s has %(number)03d quote types.' %
...       @{'language': "Python", "number": 2@})
Python has 002 quote types.
@end example

Σε αυτήν την περίπτωση δεν μπορεί να υπάρχουν προσδιοριστές @code{*} σε μια μορφή (καθώς απαιτούν μια διαδοχική λίστα παραμέτρων).

Οι δείκτες μετατροπής είναι:

@geindex # (δίεση);σε μορφοποίηση σε στυλ printf
@geindex - (πλην);σε μορφοποίηση σε στυλ printf
@geindex + (συν);σε μορφοποίηση σε στυλ printf
@geindex διάστημα;σε μορφοποίηση σε στυλ printf


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Flag

@tab

Έννοια

@item

@code{'#'}

@tab

Οι μετατροπή τιμής θα χρησιμοποιήσει την «εναλλακτική φόρμα» (όπου ορίζεται παρακάτω).

@item

@code{'0'}

@tab

Η μετατροπή θα έχει μηδενική συμπλήρωση για αριθμητικές τιμές.

@item

@code{'-'}

@tab

Η τιμή μετατροπής αφήνεται προσαρμοσμένη (παρακάμπτει τη μετατροπή @code{'0'} εάν δίνονται και τα δύο).

@item

@code{' '}

@tab

(ένα κενό) Πρέπει να προστεθεί ένα κενό πριν από έναν θετικό αριθμό (ή κενή συμβολοσειρά) που παράγεται από μια υπογεγραμμένη μετατροπή.

@item

@code{'+'}

@tab

Ένα χαρακτήρας προσήμου (@code{'+'} ή @code{'-'}) θα προηγείται της μετατροπής (παρακάμπτει ένα «κενό» δείκτη).

@end multitable


Ένας τροποποιητής μήκους (@code{h}, @code{l}, or @code{L}) μπορεί να υπάρχει, αλλά αγνοείται καθώς δεν είναι απαραίτητος για την Python – οπότε π.χ. @code{%ld} είναι πανομοιότυπο σε @code{%d}.

Οι τύποι μετατροπής είναι:


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Μετατροπή

@tab

Έννοια

@tab

Σημειώσεις

@item

@code{'d'}

@tab

Υπογεγραμμένος δεκαδικός ακέραιος.

@tab

@item

@code{'i'}

@tab

Υπογεγραμμένος δεκαδικός ακέραιος.

@tab

@item

@code{'o'}

@tab

Υπογεγραμμένη οκταδική τιμή.

@tab

(1)

@item

@code{'u'}

@tab

Απαρχαιωμένος τύπος – είναι πανομοιότυπος με το @code{'d'}.

@tab

(6)

@item

@code{'x'}

@tab

Υπογεγραμμένο δεκαεξαδικό (πεζά).

@tab

(2)

@item

@code{'X'}

@tab

Υπογεγραμμένο δεκαεξαδικό (κεφαλαίο).

@tab

(2)

@item

@code{'e'}

@tab

Εκθετική μορφή κινητής υποδιαστολής (πεζά)

@tab

(3)

@item

@code{'E'}

@tab

Εκθετική μορφή κινητής υποδιαστολής (κεφαλαία)

@tab

(3)

@item

@code{'f'}

@tab

Δεκαδική μορφή κινητής υποδιαστολής.

@tab

(3)

@item

@code{'F'}

@tab

Δεκαδική μορφή κινητής υποδιαστολής.

@tab

(3)

@item

@code{'g'}

@tab

Μορφή κινητής υποδιαστολής. Χρησιμοποιεί εκθετική μορφή πεζών αν ο εκθέτης είναι μικρότερος από -4 ή όχι μικρότερος από την ακρίβεια, διαφορετικά χρησιμοποιεί δεκαδική μορφή.

@tab

(4)

@item

@code{'G'}

@tab

Μορφή κινητής υποδιαστολής. Χρησιμοποιεί εκθετική μορφή κεφαλαίων εάν ο εκθέτης είναι μικρότερος από -4 ή όχι μικρότερος από την ακρίβεια, διαφορετικά χρησιμοποιεί δεκαδική μορφή.

@tab

(4)

@item

@code{'c'}

@tab

Μεμονωμένος χαρακτήρας (δέχεται ακέραιο ή μονό χαρακτήρα συμβολοσειράς).

@tab

@item

@code{'r'}

@tab

Συμβολοσειρά (μετατρέπει οποιοδήποτε αντικείμενο Python χρησιμοποιώντας @ref{45b,,repr()}).

@tab

(5)

@item

@code{'s'}

@tab

Συμβολοσειρά (μετατρέπει οποιοδήποτε αντικείμενο Python χρησιμοποιώντας @ref{1df,,str()}).

@tab

(5)

@item

@code{'a'}

@tab

Συμβολοσειρά (μετατρέπει οποιοδήποτε αντικείμενο Python χρησιμοποιώντας @ref{1789,,ascii()}).

@tab

(5)

@item

@code{'%'}

@tab

Κανένα όρισμα δεν μετατρέπεται, έχει ως αποτέλεσμα έναν χαρακτήρα @code{'%'} το αποτέλεσμα.

@tab

@end multitable


For floating-point formats, the result should be correctly rounded to a given
precision @code{p} of digits after the decimal point.  The rounding mode matches
that of the @ref{167f,,round()} builtin.

Σημειώσεις:


@enumerate 

@item 
Η εναλλακτική μορφή προκαλεί την εισαγωγή ενός πρώτου οκταδικού προσδιοριστή (@code{'0o'}) πριν από το πρώτο ψηφίο.

@item 
Η εναλλακτική φόρμα προκαλεί την εισαγωγή ενός αρχικού @code{'0x'} ή @code{'0X'} (ανάλογα με το εάν χρησιμοποιήθηκε η μορφή @code{'x'} ή @code{'X'}) πριν το πρώτο ψηφίο.

@item 
Η εναλλακτική μορφή κάνει το αποτέλεσμα να περιέχει πάντα μια υποδιαστολή, ακόμα κι αν δεν ακολουθούν ψηφία.

Η ακρίβεια καθορίζει τον αριθμό των ψηφίων μετά την υποδιαστολή και ορίζεται από προεπιλογή ως 6.

@item 
Η εναλλακτική μορφή κάνει το αποτέλεσμα να περιέχει πάντα μια υποδιαστολή και τα μηδενικά στο τέλος δεν αφαιρούνται όπως θα ήταν διαφορετικά.

Η ακρίβεια καθορίζει τον αριθμό των σημαντικών ψηφίων πριν και μετά την υποδιαστολή και ορίζει το 6.

@item 
Εάν η ακρίβεια είναι @code{N}, η έξοδος περικόπτεται σε @code{N} χαρακτήρες.

@item 
Βλέπε 
@geindex Python Enhancement Proposals; PEP 237
PEP 237@footnote{https://peps.python.org/pep-0237/}.
@end enumerate

Δεδομένου ότι οι συμβολοσειρές Python έχουν ρητό μήκος, οι @code{%s} μετατροπές δεν υποθέτουν ότι το @code{'\0'} είναι το τέλος της συμβολοσειράς.

@c XXX Examples?


Άλλαξε στην έκδοση 3.1: Οι μετατροπείς @code{%f} για αριθμούς των οποίων η απόλυτη τιμή είναι μεγαλύτερη από 1e50 δεν αντικαθίστανται πλέον από μετατροπές @code{%g}.


@geindex πρωτόκολλο buffer;τύπος δυαδικών ακολουθιών

@node Τύποι δυαδικής ακολουθίας — bytes bytearray memoryview,Τύποι Συνόλου Set — set frozenset,Τύπος Ακολουθίας Sequence Κειμένου — str,Τύποι Built-in
@anchor{library/stdtypes binary-sequence-types-bytes-bytearray-memoryview}@anchor{2850}@anchor{library/stdtypes binaryseq}@anchor{27bd}
@subsection Τύποι δυαδικής ακολουθίας — @code{bytes}, @code{bytearray}, @code{memoryview}


@geindex αντικείμενο;bytes
@geindex αντικείμενο;bytearray
@geindex αντικείμενο;memoryview
@geindex module;πίνακας

Οι βασικοί ενσωματωμένοι (built-in) τύποι για τον χειρισμό δυαδικών δεδομένων είναι @ref{1c7,,bytes} και @ref{1c6,,bytearray}. Υποστηρίζονται από τη @ref{1d2,,memoryview} που χρησιμοποιεί το πρωτόκολλο @ref{311,,buffer protocol} για την πρόσβαση στη μνήμη άλλων δυαδικών αντικειμένων χωρίς να χρειάζεται η δημιουργία αντιγράφου.

Το module @ref{8,,array} υποστηρίζει αποδοτική αποθήκευση για βασικούς τύπους δεδομένων όπως 32-bit ακέραιους και IEEE754 διπλής ακρίβειας κινητής υποδιαστολής τιμές.

@menu
* Αντικείμενα Bytes:: 
* Αντικείμενα Bytearray:: 
* Λειτουργίες Bytes και Bytearray:: 
* Μορφοποίηση Bytes τύπου printf:: 
* Όψεις Μνήμης:: 

@end menu

@node Αντικείμενα Bytes,Αντικείμενα Bytearray,,Τύποι δυαδικής ακολουθίας — bytes bytearray memoryview
@anchor{library/stdtypes bytes-objects}@anchor{2851}@anchor{library/stdtypes typebytes}@anchor{27bf}
@subsubsection Αντικείμενα Bytes


@geindex αντικείμενο;bytes

Τα αντικείμενα bytes είναι αμετάβλητες ακολουθίες μεμονωμένων bytes. Δεδομένου ότι πολλά κύρια δυαδικά πρωτόκολλα βασίζονται στην κωδικοποίηση κειμένου ASCII, τα αντικείμενα bytes προσφέρουν διάφορες μεθόδους που ισχύουν μόνο όταν εργάζονται με δεδομένα συμβατά με ASCII και σχετίζονται στενά με αντικείμενα συμβολοσειρών σε μια ποικιλία διαφόρων τρόπων.

@geindex bytes (ενσωματωμένη κλάση)
@anchor{library/stdtypes bytes}@anchor{1c7}
@deffn {Κλάση} bytes (source=b'@w{'})

@deffnx {Κλάση} bytes (source, encoding, errors='strict')

Πρώτον, η σύνταξη για τα bytes literals είναι σε μεγάλο βαθμό η ίδια με αυτή για τα literals συμβολοσειρών, με τη διαφορά ότι προστίθεται ένα πρόθεμα @code{b}:


@itemize *

@item 
Μονά εισαγωγικά: @code{b'ακόμα επιτρέπει ενσωματωμένα "διπλά" εισαγωγικά'}

@item 
Διπλά εισαγωγικά: @code{b"εξακολουθεί να επιτρέπει ενσωματωμένα 'μονά' εισαγωγικά"}

@item 
Τριπλά εισαγωγικά: @code{b'@w{'}'3 μονά εισαγωγικά'@w{'}'}, @code{b"""3 διπλά εισαγωγικά"""}
@end itemize

Επιτρέπονται μόνο χαρακτήρες ASCII σε bytes literals (ανεξάρτητα από τη δηλωμένη κωδικοποίηση του πηγαίου κώδικα). Τυχόν δυαδικές τιμές, πάνω από 127, πρέπει να εισαχθούν σε bytes literals χρησιμοποιώντας την κατάλληλη ακολουθία διαφυγής χαρακτήρων.

Όπως και με τα literals συμβολοσειρών, τα bytes literals μπορούν επίσης να χρησιμοποιήσουν ένα πρόθεμα @code{r} για να απενεργοποιήσουν την επεξεργασία των ακολουθιών διαφυγής χαρακτήρων. Βλέπε @ref{2490,,Λεκτικά συμβολοσειράς και Bytes} για περισσότερες πληροφορίες σχετικά με τις διάφορες μορφές bytes literal, συμπεριλαμβανομένων των υποστηριζόμενων ακολουθιών διαφυγής χαρακτήρων.

Ενώ τα bytes literals και οι αναπαραστάσεις βασίζονται σε κείμενο ASCII, τα αντικείμενα bytes συμπεριφέρονται στην πραγματικότητα σαν αμετάβλητες ακολουθίες ακεραίων με κάθε τιμή στην ακολουθία περιορισμένη έτσι ώστε @code{0 <= x < 256} (προσπάθειες παραβίασης αυτού του περιορισμού θα κάνουν raise την @ref{277,,ValueError}). Αυτό γίνεται σκόπιμα για να τονιστεί ότι, ενώ πολλές δυαδικές μορφές περιλαμβάνουν στοιχεία που βασίζονται σε ASCII και μπορούν να χρησιμοποιηθούν χρήσιμα με ορισμένους αλγορίθμους προσανατολισμένους στο κείμενο, αυτό δεν ισχύει γενικά για αυθαίρετα δυαδικά δεδομένα (τυφλή εφαρμογή αλγορίθμων επεξεργασίας κειμένου σε δυαδικές μορφές δεδομένων που δεν είναι συμβατές με ASCII συνήθως οδηγεί σε καταστροφή δεδομένων).

Εκτός από τις literal μορφές, τα αντικείμενα bytes μπορούν να δημιουργηθούν με πολλούς άλλους τρόπους:


@itemize *

@item 
Ένα μηδενικό αντικείμενο bytes με καθορισμένο μήκος: @code{bytes(10)}

@item 
Από ένα iterable ακεραίων αριθμών: @code{bytes(range(20))}

@item 
Αντιγραφή υπαρχόντων δυαδικών δεδομένων μέσω του πρωτοκόλλου buffer:  @code{bytes(obj)}
@end itemize

Δείτε επίσης το ενσωματωμένο @ref{2087,,bytes}.

Δεδομένου ότι 2 δεκαεξαδικά ψηφία αντιστοιχούν ακριβώς σε ένα μόνο byte, οι δεκαεξαδικοί αριθμοί είναι μια συνήθως χρησιμοποιούμενη μορφή για την περιγραφή δυαδικών δεδομένων. Συνεπώς, ο τύπος bytes έχει μια πρόσθετη μέθοδο κλάσης για την ανάγνωση δεδομένων σε αυτήν την μορφή:

@geindex fromhex() (μέθοδος κλάσης της bytes)
@anchor{library/stdtypes bytes fromhex}@anchor{434}
@deffn {Μέθοδος} classmethod fromhex (string, /)

Αυτή η μέθοδος κλάσης @ref{1c7,,bytes} επιστρέφει ένα αντικείμενο bytes, αποκωδικοποιώντας το δεδομένο αντικείμενο συμβολοσειράς.  Η συμβολοσειρά πρέπει να περιέχει δύο δεκαεξαδικά ψηφία ανά byte, με το κενό διάστημα ASCII να αγνοείται.

@example
>>> bytes.fromhex('2Ef0 F1f2  ')
b'.\xf0\xf1\xf2'
@end example


Άλλαξε στην έκδοση 3.7: Το @ref{434,,bytes.fromhex()} παρακάμπτει πλέον όλα τα κενά ASCII στη συμβολοσειρά, όχι μόνο τα κενά.



Άλλαξε στην έκδοση 3.14: Η @ref{434,,bytes.fromhex()} δέχεται πλέον ASCII @ref{1c7,,bytes} και @ref{436,,bytes-like objects} ως είσοδο.

@end deffn

Υπάρχει μια συνάρτηση αντίστροφης μετατροπής για τη μετατροπή ενός αντικειμένου bytes στην δεκαεξαδική του αναπαράσταση.

@geindex hex() (μέθοδος της bytes)
@anchor{library/stdtypes bytes hex}@anchor{111e}
@deffn {Μέθοδος} hex (*, bytes_per_sep=1)

@deffnx {Μέθοδος} hex (sep, bytes_per_sep=1)

Επιστρέφετε ένα αντικείμενο συμβολοσειράς που περιέχει δύο δεκαεξαδικά ψηφία για κάθε byte στο στιγμιότυπο.

@example
>>> b'\xf0\xf1\xf2'.hex()
'f0f1f2'
@end example

Εάν θέλετε να κάνετε τη δεκαεξαδική συμβολοσειρά πιο ευανάγνωστη, μπορείτε να καθορίσετε μια παράμετρο διαχωρισμού χαρακτήρων `sep' που θα συμπεριληφθεί στην έξοδο. Από προεπιλογή, αυτό το διαχωριστικό θα περιλαμβάνεται μεταξύ κάθε byte. Μια δεύτερη προαιρετική παράμετρος `bytes_per_sep' ελέγχει τα διαστήματα. Οι θετικές τιμές υπολογίζουν τη θέση του διαχωριστή από τα δεξιά, οι αρνητικές τιμές από τα αριστερά.

@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


Added in version 3.5.



Άλλαξε στην έκδοση 3.8: Η @ref{111e,,bytes.hex()} υποστηρίζει πλέον προαιρετικές παραμέτρους `sep' και `bytes_per_sep' για την εισαγωγή διαχωριστικών μεταξύ των byte στην έξοδο δεκαεξαδικού.

@end deffn
@end deffn

Δεδομένου ότι τα αντικείμενα bytes είναι ακολουθίες ακεραίων αριθμών (όμοια με μια πλειάδα (tuple)), για ένα αντικείμενο bytes `b', το @code{b[0]} θα είναι ένας ακέραιος αριθμός, ενώ το @code{b[0:1]} θα είναι ένα αντικείμενο bytes μήκους 1. (Αυτό έρχεται σε αντίθεση με τις συμβολοσειρές κειμένου, όπου τόσο η λειτουργία πρόσβασης ως ευρετήριο όσο και η λειτουργία τμηματοποίησης θα παράγουν μια συμβολοσειρά μήκους 1)

Η αναπαράσταση αντικειμένων bytes χρησιμοποιεί την literal μορφή (@code{b'...'}) , καθώς είναι συχνά πιο χρήσιμη από π.χ. @code{bytes([46, 46, 46])}.  Μπορείτε πάντα να μετατρέψετε ένα αντικείμενο bytes σε μια λίστα ακέραιων αριθμών που χρησιμοποιούν @code{list(b)}.

@node Αντικείμενα Bytearray,Λειτουργίες Bytes και Bytearray,Αντικείμενα Bytes,Τύποι δυαδικής ακολουθίας — bytes bytearray memoryview
@anchor{library/stdtypes bytearray-objects}@anchor{2852}@anchor{library/stdtypes typebytearray}@anchor{27be}
@subsubsection Αντικείμενα Bytearray


@geindex αντικείμενο;bytearray

Τα αντικείμενα @ref{1c6,,bytearray} είναι ένα μεταβλητό, αντίστοιχο, των αντικειμένων @ref{1c7,,bytes}.

@geindex bytearray (ενσωματωμένη κλάση)
@anchor{library/stdtypes bytearray}@anchor{1c6}
@deffn {Κλάση} bytearray (source=b'@w{'})

@deffnx {Κλάση} bytearray (source, encoding, errors='strict')

Δεν υπάρχει αποκλειστική literal σύνταξη για αντικείμενα bytearray, αντίθετα δημιουργούνται πάντα καλώντας τον constructor:


@itemize *

@item 
Δημιουργία ενός κενού στιγμιοτύπου: @code{bytearray()}

@item 
Δημιουργία μηδενικού στιγμιοτύπου με δεδομένο μήκος: @code{bytearray(10)}

@item 
Από έναν iterable αριθμό ακεραίων: @code{bytearray(range(20))}

@item 
Αντιγραφή υπαρχόντων δυαδικών δεδομένων μέσω του πρωτοκόλλου buffer:  @code{bytearray(b'Hi!')}
@end itemize

Καθώς τα αντικείμενα του bytearray είναι μεταβλητά, υποστηρίζουν τις λειτουργίες της ακολουθίας @ref{27bb,,mutable} επιπλέον των κοινών λειτουργιών bytes και bytearray που περιγράφονται στο @ref{27bc,,Λειτουργίες Bytes και Bytearray}.

Δείτε επίσης το ενσωματωμένο @ref{2088,,bytearray}.

Δεδομένου ότι 2 δεκαεξαδικά ψηφία αντιστοιχούν ακριβώς σε ένα μόνο byte, οι δεκαεξαδικοί αριθμοί είναι συνήθως χρησιμοποιούμενη μορφή για την περιγραφή δυαδικών δεδομένων. Συνεπώς, ο τύπος bytearray έχει μια πρόσθετη μέθοδο κλάσης για την ανάγνωση δεδομένων σε αυτήν την μορφή:

@geindex fromhex() (μέθοδος κλάσης της bytearray)
@anchor{library/stdtypes bytearray fromhex}@anchor{435}
@deffn {Μέθοδος} classmethod fromhex (string, /)

Αυτή η μέθοδος κλάσης @ref{1c6,,bytearray} επιστρέφει αντικείμενο bytearray, αποκωδικοποιώντας το δεδομένο αντικείμενο συμβολοσειράς.  Η συμβολοσειρά πρέπει να περιέχει δύο δεκαεξαδικά ψηφία ανά byte, με το κενό διάστημα ASCII να αγνοείται.

@example
>>> bytearray.fromhex('2Ef0 F1f2  ')
bytearray(b'.\xf0\xf1\xf2')
@end example


Άλλαξε στην έκδοση 3.7: Το @ref{435,,bytearray.fromhex()} παρακάμπτει τώρα όλα τα κενά ASCII στη συμβολοσειρά, όχι μόνο τα κενά.



Άλλαξε στην έκδοση 3.14: Η @ref{435,,bytearray.fromhex()} δέχεται πλέον το ASCII @ref{1c7,,bytes} και @ref{436,,bytes-like objects} ως είσοδο.

@end deffn

Υπάρχει μια συνάρτηση αντίστροφης μετατροπής για να μετατρέψει ένα αντικείμενο bytearray στη δεκαεξαδική αναπαράσταση του.

@geindex hex() (μέθοδος της bytearray)
@anchor{library/stdtypes bytearray hex}@anchor{111f}
@deffn {Μέθοδος} hex (*, bytes_per_sep=1)

@deffnx {Μέθοδος} hex (sep, bytes_per_sep=1)

Επιστρέφετε ένα αντικείμενο συμβολοσειράς που περιέχει δύο δεκαεξαδικά ψηφία για κάθε byte στο στιγμιότυπο.

@example
>>> bytearray(b'\xf0\xf1\xf2').hex()
'f0f1f2'
@end example


Added in version 3.5.



Άλλαξε στην έκδοση 3.8: Παρόμοια με το @ref{111e,,bytes.hex()}, το @ref{111f,,bytearray.hex()} υποστηρίζει τώρα προαιρετικές παραμέτρους `sep' και `bytes_per_sep' για την εισαγωγή διαχωριστικών μεταξύ των byte στην δεκαεξαδική έξοδο.

@end deffn

@geindex resize() (μέθοδος της bytearray)
@anchor{library/stdtypes bytearray resize}@anchor{1928}
@deffn {Μέθοδος} resize (size, /)

Αλλάζει το μέγεθος του @ref{1c6,,bytearray} ώστε αν περιέχει `size' bytes. Το `size' πρέπει να είναι μεγαλύτερο ή ίσο με το 0.

Εάν η @ref{1c6,,bytearray} χρειάζεται να συρρικνωθεί, τα bytes πέραν του `size' περικόπτονται.

Εάν η @ref{1c6,,bytearray} χρειάζεται να αυξηθεί, όλα τα νέα bytes, αυτά που είναι πέρα από το `size', θα οριστούν σε null bytes.

Ισοδύναμο με:

@example
>>> def resize(ba, size):
...     if len(ba) > size:
...         del ba[size:]
...     else:
...         ba += b'\0' * (size - len(ba))
@end example

Παραδείγματα:

@example
>>> shrink = bytearray(b'abc')
>>> shrink.resize(1)
>>> (shrink, len(shrink))
(bytearray(b'a'), 1)
>>> grow = bytearray(b'abc')
>>> grow.resize(5)
>>> (grow, len(grow))
(bytearray(b'abc\x00\x00'), 5)
@end example


Added in version 3.14.

@end deffn

@geindex take_bytes() (μέθοδος της bytearray)
@anchor{library/stdtypes bytearray take_bytes}@anchor{1c5}
@deffn {Μέθοδος} take_bytes (n=None, /)

Remove the first `n' bytes from the bytearray and return them as an immutable
@ref{1c7,,bytes}.
By default (if `n' is @code{None}), return all bytes and clear the bytearray.

If `n' is negative, index from the end and take the first @ref{a1f,,len()}
plus `n' bytes. If `n' is out of bounds, raise @ref{18d7,,IndexError}.

Taking less than the full length will leave remaining bytes in the
@code{bytearray}, which requires a copy. If the remaining bytes should be
discarded, use @ref{1928,,resize()} or @ref{1d1d,,del} to truncate
then @ref{1c5,,take_bytes()} without a size.

`Λεπτομέρεια υλοποίησης CPython:' Taking all bytes is a zero-copy operation.


Added in version 3.15: See the @ref{1c4,,What’s New} entry for
common code patterns which can be optimized with
@code{bytearray.take_bytes()}.

@end deffn
@end deffn

Δεδομένου ότι τα αντικείμενα bytearray είναι ακολουθίες ακεραίων αριθμών (παρόμοια με μια λίστα), για ένα αντικείμενο bytearray `b', το @code{b[0]} θα είναι ένας ακέραιος αριθμός, ενώ το @code{b[0:1]} θα είναι ένα αντικείμενο bytearray μήκους 1.  (Αυτό έρχεται σε αντίθεση με τις συμβολοσειρές κειμένου, όπου τόσο το indexing και το slicing θα παράγουν μια συμβολοσειρά μήκους 1)

Η αναπαράσταση αντικειμένων bytearray χρησιμοποιεί τη μορφή bytes literal (@code{bytearray(b'...')}), καθώς είναι συχνά πιο χρήσιμη από π.χ. @code{bytearray([46, 46, 46])}.  Μπορείτε πάντα να μετατρέψετε ένα αντικείμενο bytearray σε λίστα ακεραίων χρησιμοποιώντας το @code{list(b)}.


@subsubheading Δείτε επίσης


For detailed information on thread-safety guarantees for @ref{1c6,,bytearray}
objects, see @ref{2853,,Thread safety for bytearray objects}.


@node Λειτουργίες Bytes και Bytearray,Μορφοποίηση Bytes τύπου printf,Αντικείμενα Bytearray,Τύποι δυαδικής ακολουθίας — bytes bytearray memoryview
@anchor{library/stdtypes bytes-and-bytearray-operations}@anchor{2854}@anchor{library/stdtypes bytes-methods}@anchor{27bc}
@subsubsection Λειτουργίες Bytes και Bytearray


@geindex bytes;μέθοδοι
@geindex bytearray;μέθοδοι

Τόσο τα byte όσο και τα αντικείμενα του πίνακα byte υποστηρίζουν τις λειτουργίες της ακολουθίας @ref{2801,,common}. Αλληλεπιδρούν όχι μόνο με τελεστές του ίδιου τύπου, αλλά και με οποιοδήποτε αντικείμενο @ref{436,,bytes-like object}. Λόγω αυτής της ευελιξίας, μπορούν να αναμειχθούν ελεύθερα σε λειτουργίες χωρίς να προκαλούνται σφάλματα. Ωστόσο, ο τύπος επιστροφής του αποτελέσματος μπορεί να εξαρτάται από τη σειρά των τελεστών.

@cartouche
@quotation Σημείωση 
Οι μέθοδοι στα bytes και τα αντικείμενα bytearray δεν δέχονται συμβολοσειρές ως ορίσματά τους, όπως και οι μέθοδοι σε συμβολοσειρές δεν δέχονται bytes ως ορίσματα.  Για παράδειγμα, πρέπει να γράψετε:

@example
a = "abc"
b = a.replace("a", "f")
@end example

και:

@example
a = b"abc"
b = a.replace(b"a", b"f")
@end example
@end quotation
@end cartouche

Ορισμένες λειτουργίες byte και bytearray προϋποθέτουν τη χρήση δυαδικών μορφών συμβατών με ASCII και, ως εκ τούτου, θα πρέπει να αποφεύγονται όταν εργάζεστε με αυθαίρετα δυαδικά δεδομένα. Αυτοί οι περιορισμοί καλύπτονται παρακάτω.

@cartouche
@quotation Σημείωση 
Η χρήση αυτών των λειτουργιών βασίζονται στο ASCII για τον χειρισμό δυαδικών δεδομένων που δεν είναι αποθηκευμένα σε μορφή που βασίζεται σε ASCII μπορεί να οδηγήσει σε καταστροφή δεδομένων.
@end quotation
@end cartouche

Οι ακόλουθες μέθοδοι σε byte και αντικείμενα bytearray μπορούν να χρησιμοποιηθούν με αυθαίρετα δυαδικά δεδομένα.

@geindex count() (μέθοδος της bytes)
@geindex count() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes count}@anchor{1b94}
@deffn {Μέθοδος} bytes.count (sub[, start[, end]])
@anchor{library/stdtypes bytearray count}@anchor{1995}
@deffnx {Μέθοδος} bytearray.count (sub[, start[, end]])

Επιστρέφει τον αριθμό των μη επικαλυπτόμενων εμφανίσεων της δευτερεύουσας ακολουθίας `sub' στο εύρος [`start', `end']. Τα προαιρετικά ορίσματα `start' και `end' ερμηνεύονται όπως στη σημειογραφία τμηματοποίησης.

Η υποακολουθία για αναζήτηση μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object} ή ένας ακέραιος αριθμός στην περιοχή από 0 έως 255.

Εάν το `sub' είναι κενό, επιστρέφει τον αριθμό των κενών τμημάτων μεταξύ των χαρακτήρων που είναι το μήκος του αντικειμένου bytes συν ένα.


Άλλαξε στην έκδοση 3.3: Επίσης αποδέχεται έναν ακέραιο αριθμό στο εύρος 0 έως 255 ως υποακολουθία.

@end deffn

@geindex removeprefix() (μέθοδος της bytes)
@geindex removeprefix() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes removeprefix}@anchor{2855}
@deffn {Μέθοδος} bytes.removeprefix (prefix, /)
@anchor{library/stdtypes bytearray removeprefix}@anchor{2856}
@deffnx {Μέθοδος} bytearray.removeprefix (prefix, /)

Εάν τα δυαδικά δεδομένα ξεκινούν με τη συμβολοσειρά `prefix', επιστρέφει @code{bytes[len(prefix):]}. Διαφορετικά επιστρέψτε ένα αντίγραφο των αρχικών δυαδικών δεδομένων:

@example
>>> b'TestHook'.removeprefix(b'Test')
b'Hook'
>>> b'BaseTestCase'.removeprefix(b'Test')
b'BaseTestCase'
@end example

Το `prefix' μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object}.

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche


Added in version 3.9.

@end deffn

@geindex removesuffix() (μέθοδος της bytes)
@geindex removesuffix() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes removesuffix}@anchor{2857}
@deffn {Μέθοδος} bytes.removesuffix (suffix, /)
@anchor{library/stdtypes bytearray removesuffix}@anchor{2858}
@deffnx {Μέθοδος} bytearray.removesuffix (suffix, /)

Εάν τα δυαδικά δεδομένα τελειώνουν με τη συμβολοσειρά `suffix' και αυτό το `suffix' δεν είναι κενό, επιστρέφει @code{bytes[:-len(suffix)]}.  Διαφορετικά, επιστρέφει ένα αντίγραφο των αρχικών δυαδικών δεδομένων:

@example
>>> b'MiscTests'.removesuffix(b'Tests')
b'Misc'
>>> b'TmpDirMixin'.removesuffix(b'Tests')
b'TmpDirMixin'
@end example

Το `suffix' μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object}.

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche


Added in version 3.9.

@end deffn

@geindex decode() (μέθοδος της bytes)
@geindex decode() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes decode}@anchor{ca8}
@deffn {Μέθοδος} bytes.decode (encoding='utf-8', errors='strict')
@anchor{library/stdtypes bytearray decode}@anchor{2859}
@deffnx {Μέθοδος} bytearray.decode (encoding='utf-8', errors='strict')

Επιστρέφει τα bytes που έχουν αποκωδικοποιηθεί σε μια @ref{1df,,str}.

το `encoding' έχει default σε @code{'utf-8'}- δείτε @ref{1171,,Standard Encodings} για πιθανές τιμές.

Το `errors' ελέγχει τον τρόπο χειρισμού των σφαλμάτων αποκωδικοποίησης. Εάν @code{'strict'} (η προεπιλογή), γίνεται raise μια εξαίρεση @ref{675,,UnicodeError}. Άλλες πιθανές τιμές είναι το @code{'ignore'}, @code{'replace'}, και οποιοδήποτε άλλο όνομα που έχει καταχωρηθεί από την @ref{183d,,codecs.register_error()}. Βλέπε @ref{1d6c,,Error Handlers} για λεπτομέρειες.

Για λόγους απόδοσης, η τιμή του `errors' δεν ελέγχεται ως προς την εγκυρότητα του, εκτός εάν παρουσιαστεί ένα σφάλμα αποκωδικοποίησης, είναι ενεργοποιημένο το @ref{70d,,Python Development Mode} ή χρησιμοποιείται ένα @ref{3dc,,debug build}.

@cartouche
@quotation Σημείωση 
Η μετάδοση του ορίσματος `encoding' στην @ref{1df,,str} επιτρέπει την αποκωδικοποίηση οποιουδήποτε @ref{436,,bytes-like object} απευθείας, χωρίς να χρειάζεται να δημιουργήσετε ένα προσωρινό αντικείμενο @code{bytes} ή @code{bytearray}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.1: Επιπρόσθετη υποστήριξη για keyword ορίσματα.



Άλλαξε στην έκδοση 3.9: Η τιμή του όρου `errors' ελέγχεται τώρα στο @ref{70d,,Python Development Mode} και στο @ref{3dc,,debug mode}.

@end deffn

@geindex endswith() (μέθοδος της bytes)
@geindex endswith() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes endswith}@anchor{2819}
@deffn {Μέθοδος} bytes.endswith (suffix[, start[, end]])
@anchor{library/stdtypes bytearray endswith}@anchor{1745}
@deffnx {Μέθοδος} bytearray.endswith (suffix[, start[, end]])

Επιστρέφει @code{True} εάν τα δυαδικά δεδομένα τελειώνουν με το καθορισμένο `suffix', διαφορετικά επιστρέφει @code{False}.  Το `suffix' μπορεί επίσης να είναι μια πλειάδα από επιθέματα που πρέπει να αναζητήσετε.  Με το προαιρετικό `start', η δοκιμή ξεκινά από αυτή τη θέση.  Με το προαιρετικό `end', σταματήστε να συγκρίνετε σε αυτή τη θέση.

Το(α) επίθεμα(τα) για αναζήτηση μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object}.
@end deffn

@geindex find() (μέθοδος της bytes)
@geindex find() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes find}@anchor{1dcd}
@deffn {Μέθοδος} bytes.find (sub[, start[, end]])
@anchor{library/stdtypes bytearray find}@anchor{1746}
@deffnx {Μέθοδος} bytearray.find (sub[, start[, end]])

Επιστρέφει το χαμηλότερο index στα δεδομένα όπου βρίσκεται η υποακολουθία `sub', έτσι ώστε το `sub' να περιέχεται  στο slice @code{s[start:end]}.  Τα προαιρετικά ορίσματα `start' και `end' ερμηνεύονται ως συμβολισμό τμηματοποίησης.  Επιστρέφει @code{-1} εάν το `sub' δεν βρεθεί.

Η υποακολουθία για αναζήτηση μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object} ή ένας ακέραιος αριθμός στην περιοχή από 0 έως 255.

@cartouche
@quotation Σημείωση 
Η μέθοδος @ref{1dcd,,find()} θα πρέπει να χρησιμοποιείται μόνο εάν χρειάζεται να γνωρίζετε τη θέση του `sub'.  Για να ελέγξετε εάν το `sub' είναι υποσυμβολοσειρά ή όχι, χρησιμοποιήστε τον τελεστή @ref{323,,in}:

@example
>>> b'Py' in b'Python'
True
@end example
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: Επίσης αποδέχεται έναν ακέραιο αριθμό στο εύρος 0 έως 255 ως υποακολουθία.

@end deffn

@geindex index() (μέθοδος της bytes)
@geindex index() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes index}@anchor{2816}
@deffn {Μέθοδος} bytes.index (sub[, start[, end]])
@anchor{library/stdtypes bytearray index}@anchor{1996}
@deffnx {Μέθοδος} bytearray.index (sub[, start[, end]])

Όπως η @ref{1dcd,,find()}, αλλά κάνει raise μια @ref{277,,ValueError} όταν δεν βρεθεί η δευτερεύουσα ακολουθία.

Η υποακολουθία για αναζήτηση μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object} ή ένας ακέραιος αριθμός στην περιοχή από 0 έως 255.


Άλλαξε στην έκδοση 3.3: Επίσης αποδέχεται έναν ακέραιο αριθμό στο εύρος 0 έως 255 ως υποακολουθία.

@end deffn

@geindex join() (μέθοδος της bytes)
@geindex join() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes join}@anchor{2804}
@deffn {Μέθοδος} bytes.join (iterable, /)
@anchor{library/stdtypes bytearray join}@anchor{285a}
@deffnx {Μέθοδος} bytearray.join (iterable, /)

Επιστρέφει ένα αντικείμενο bytes ή bytearray που είναι η συνένωση των δυαδικών ακολουθιών δεδομένων στο `iterable'.  Μια @ref{291,,TypeError} θα γίνει raise εάν υπάρχουν τιμές στο `iterable' που δεν είναι σαν @ref{436,,bytes-like objects}, συμπεριλαμβανομένων των αντικειμένων @ref{1df,,str}.  Το διαχωριστικό μεταξύ των στοιχειών είναι τα περιεχόμενα των byte ή του αντικειμένου bytearray που παρέχει αυτή τη μέθοδο.
@end deffn

@geindex maketrans() (στατική μέθοδος της bytes)
@geindex maketrans() (στατική μέθοδος της bytearray)
@anchor{library/stdtypes bytes maketrans}@anchor{1619}
@deffn {Μέθοδος} static bytes.maketrans (from, to, /)
@anchor{library/stdtypes bytearray maketrans}@anchor{161a}
@deffnx {Μέθοδος} static bytearray.maketrans (from, to, /)

Αυτή η στατική μέθοδος επιστρέφει έναν πίνακα μετάφρασης που μπορεί να χρησιμοποιηθεί για την @ref{196d,,bytes.translate()} που θα αντιστοιχίσει κάθε χαρακτήρα στο `from' στον χαρακτήρα στην ίδια θέση στο `to'· τα `from' και `to' πρέπει να είναι και τα δύο @ref{436,,bytes-like objects} και να έχουν το ίδιο μήκος.


Added in version 3.1.

@end deffn

@geindex partition() (μέθοδος της bytes)
@geindex partition() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes partition}@anchor{281d}
@deffn {Μέθοδος} bytes.partition (sep, /)
@anchor{library/stdtypes bytearray partition}@anchor{285b}
@deffnx {Μέθοδος} bytearray.partition (sep, /)

Διαχωρίζει την ακολουθία κατά την πρώτη εμφάνιση του `sep', και επιστρέφει μια 3-πλειάδα που περιέχει το τμήμα πριν από το διαχωριστικό ή το αντίγραφο του bytearray του και το τμήμα μετά το διαχωριστικό. Εάν δεν βρεθεί το διαχωριστικό, επιστρέφει μια 3-πλειάδα που περιέχει ένα αντίγραφο της αρχικής ακολουθίας, ακολουθούμενη από δύο κενά byte ή αντικείμενα bytearray.

Το διαχωριστικό για αναζήτηση μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object}.
@end deffn

@geindex replace() (μέθοδος της bytes)
@geindex replace() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes replace}@anchor{1d3}
@deffn {Μέθοδος} bytes.replace (old, new, /, count=-1)
@anchor{library/stdtypes bytearray replace}@anchor{285c}
@deffnx {Μέθοδος} bytearray.replace (old, new, /, count=-1)

Return a copy of the sequence with all occurrences of subsequence `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.

Η ακολουθία για αναζήτηση και αντικατάσταση της μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object}.

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.15: Το `count' υποστηρίζεται πλέον ως όρισμα λέξης-κλειδιού.

@end deffn

@geindex rfind() (μέθοδος της bytes)
@geindex rfind() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes rfind}@anchor{1dce}
@deffn {Μέθοδος} bytes.rfind (sub[, start[, end]])
@anchor{library/stdtypes bytearray rfind}@anchor{1747}
@deffnx {Μέθοδος} bytearray.rfind (sub[, start[, end]])

Επιστρέφει τον υψηλότερο δείκτη στην ακολουθία όπου βρίσκεται η υποακολουθία `sub', έτσι ώστε το `sub' να περιέχεται στο @code{s[start:end]}.  Τα προαιρετικά ορίσματα `start' και `end' ερμηνεύονται με συμβολισμό τμηματοποίησης. Επιστρέφει @code{-1} σε περίπτωση αποτυχίας.

Η υποακολουθία για αναζήτηση μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object} ή ένας ακέραιος αριθμός στην περιοχή από 0 έως 255.


Άλλαξε στην έκδοση 3.3: Επίσης αποδέχεται έναν ακέραιο αριθμό στο εύρος 0 έως 255 ως υποακολουθία.

@end deffn

@geindex rindex() (μέθοδος της bytes)
@geindex rindex() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes rindex}@anchor{2817}
@deffn {Μέθοδος} bytes.rindex (sub[, start[, end]])
@anchor{library/stdtypes bytearray rindex}@anchor{1997}
@deffnx {Μέθοδος} bytearray.rindex (sub[, start[, end]])

Όπως η @ref{1dce,,rfind()} αλλά κάνει raise μια @ref{277,,ValueError} όταν δεν βρεθεί η υποακολουθία `sub'.

Η υποακολουθία για αναζήτηση μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object} ή ένας ακέραιος αριθμός στην περιοχή από 0 έως 255.


Άλλαξε στην έκδοση 3.3: Επίσης αποδέχεται έναν ακέραιο αριθμό στο εύρος 0 έως 255 ως υποακολουθία.

@end deffn

@geindex rpartition() (μέθοδος της bytes)
@geindex rpartition() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes rpartition}@anchor{281e}
@deffn {Μέθοδος} bytes.rpartition (sep, /)
@anchor{library/stdtypes bytearray rpartition}@anchor{285d}
@deffnx {Μέθοδος} bytearray.rpartition (sep, /)

Διαχωρίζει την ακολουθία στην τελευταία εμφάνιση του `sep', και επιστρέφει μια 3-πλειάδα που περιέχει το τμήμα πριν από το διαχωριστικό, το ίδιο το διαχωριστικό ή το αντίγραφο του bytearray και το τμήμα μετά το διαχωριστικό. Εάν δεν βρεθεί το διαχωριστικό επιστρέφει μια 3-πλειάδα που περιέχει δύο κενά byte ή αντικείμενα bytearray, ακολουθούμενα από ένα αντίγραφο της αρχικής ακολουθίας.

Το διαχωριστικό για αναζήτηση μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object}.
@end deffn

@geindex startswith() (μέθοδος της bytes)
@geindex startswith() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes startswith}@anchor{2818}
@deffn {Μέθοδος} bytes.startswith (prefix[, start[, end]])
@anchor{library/stdtypes bytearray startswith}@anchor{1744}
@deffnx {Μέθοδος} bytearray.startswith (prefix[, start[, end]])

Επιστρέφει @code{True} εάν τα δυαδικά δεδομένα ξεκινούν με το καθορισμένο `prefix', διαφορετικά επιστρέφει @code{False}. Το `prefix' μπορεί επίσης να είναι μια πλειάδα από προθέματα προς αναζήτηση.  Με το προαιρετικό `start', η δοκιμή ξεκινά από αυτή τη θέση.  Με το προαιρετικό `end', σταματάει να συγκρίνει σε αυτή τη θέση.

Το(α) πρόθεμα(τα) για αναζήτηση μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object}.
@end deffn

@geindex translate() (μέθοδος της bytes)
@geindex translate() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes translate}@anchor{196d}
@deffn {Μέθοδος} bytes.translate (table, /, delete=b'@w{'})
@anchor{library/stdtypes bytearray translate}@anchor{16a0}
@deffnx {Μέθοδος} bytearray.translate (table, /, delete=b'@w{'})

Επιστρέφει ένα αντίγραφο των bytes ή του αντικειμένου bytearray όπου αφαιρούνται όλα τα byte που εμφανίζονται στο προαιρετικό όρισμα `delete' και τα υπόλοιπα byte έχουν αντιστοιχιστεί μέσω του δεδομένου πίνακα μετάφρασης, ο οποίος πρέπει να είναι ένα αντικείμενο bytes μήκους 256.

Μπορείτε να χρησιμοποιήσετε τη μέθοδο @ref{1619,,bytes.maketrans()} για να δημιουργήσετε έναν πίνακα μετάφρασης.

Ορίζει το όρισμα `table' σε @code{None} για μεταφράσεις που διαγράφουν μόνο χαρακτήρες:

@example
>>> b'read this short text'.translate(None, b'aeiou')
b'rd ths shrt txt'
@end example


Άλλαξε στην έκδοση 3.6: Το `delete' υποστηρίζεται πλέον ως όρισμα λέξης-κλειδιού.

@end deffn

Οι ακόλουθες μέθοδοι σε byte και bytearray αντικείμενα έχουν προεπιλεγμένες συμπεριφορές που προϋποθέτουν τη χρήση δυαδικών μορφών συμβατών με ASCII, αλλά μπορούν να χρησιμοποιηθούν με αυθαίρετα δυαδικά δεδομένα περνώντας κατάλληλα ορίσματα. Σημειώστε ότι όλες οι μέθοδοι bytearray σε αυτήν την ενότητα `δεν' λειτουργούν στη θέση τους και όμως παράγουν νέα αντικείμενα.

@geindex center() (μέθοδος της bytes)
@geindex center() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes center}@anchor{283a}
@deffn {Μέθοδος} bytes.center (width, fillbyte=b' ', /)
@anchor{library/stdtypes bytearray center}@anchor{285e}
@deffnx {Μέθοδος} bytearray.center (width, fillbyte=b' ', /)

Επιστρέφει ένα αντίγραφο του αντικειμένου με κέντρο σε μια ακολουθία μήκους `width'. Η συμπλήρωση πραγματοποιείται χρησιμοποιώντας το καθορισμένο `fillbyte' (η προεπιλογή είναι ένα διάστημα ASCII). Για αντικείμενα @ref{1c7,,bytes}, η αρχική ακολουθία επιστρέφεται εάν το `width' είναι μικρότερο ή ίσο με @code{len(s)}.

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

@geindex ljust() (μέθοδος της bytes)
@geindex ljust() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes ljust}@anchor{2838}
@deffn {Μέθοδος} bytes.ljust (width, fillbyte=b' ', /)
@anchor{library/stdtypes bytearray ljust}@anchor{285f}
@deffnx {Μέθοδος} bytearray.ljust (width, fillbyte=b' ', /)

Επιστρέφει ένα αντίγραφο του αντικειμένου αριστερά ευθυγραμμισμένο σε μια ακολουθία μήκους `width'. Η συμπλήρωση πραγματοποιείται χρησιμοποιώντας το καθορισμένο `fillbyte' (η προεπιλογή είναι ένα διάστημα ASCII). Για αντικείμενα @ref{1c7,,bytes}, η αρχική ακολουθία επιστρέφεται εάν το `width' είναι μικρότερο ή ίσο με @code{len(s)}.

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

@geindex lstrip() (μέθοδος της bytes)
@geindex lstrip() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes lstrip}@anchor{283e}
@deffn {Μέθοδος} bytes.lstrip (bytes=None, /)
@anchor{library/stdtypes bytearray lstrip}@anchor{2860}
@deffnx {Μέθοδος} bytearray.lstrip (bytes=None, /)

Επιστρέφει ένα αντίγραφο της ακολουθίας με καθορισμένα βασικά byte που έχουν αφαιρεθεί.  Το όρισμα `bytes' είναι μια δυαδική ακολουθία που καθορίζει το σύνολο των τιμών byte που πρέπει να αφαιρεθούν. Εάν παραληφθεί ή είναι @code{None}, το όρισμα `bytes' έχει ως προεπιλογή την αφαίρεση  του κενού διαστήματος  ASCII.  Το όρισμα `bytes' δεν είναι πρόθεμα∙ αλλά οι συνδυασμοί των τιμών του αφαιρούνται:

@example
>>> b'   spacious   '.lstrip()
b'spacious   '
>>> b'www.example.com'.lstrip(b'cmowz.')
b'example.com'
@end example

Η δυαδική ακολουθία τιμών byte προς κατάργηση μπορεί να είναι οποιαδήποτε @ref{436,,bytes-like object}. Βλέπε @ref{2855,,removeprefix()} για μια μέθοδο που θα αφαιρέσει μια μεμονωμένη συμβολοσειρά προθέματος αντί όλο το σύνολο χαρακτήρων.  Για παράδειγμα:

@example
>>> b'Arthur: three!'.lstrip(b'Arthur: ')
b'ee!'
>>> b'Arthur: three!'.removeprefix(b'Arthur: ')
b'three!'
@end example

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

@geindex rjust() (μέθοδος της bytes)
@geindex rjust() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes rjust}@anchor{2839}
@deffn {Μέθοδος} bytes.rjust (width, fillbyte=b' ', /)
@anchor{library/stdtypes bytearray rjust}@anchor{2861}
@deffnx {Μέθοδος} bytearray.rjust (width, fillbyte=b' ', /)

Επιστρέφει ένα αντίγραφο του αντικειμένου ευθυγραμμισμένο δεξιά που δικαιολογείται σε μια ακολουθία μήκους `width'. Η συμπλήρωση πραγματοποιείται χρησιμοποιώντας το καθορισμένο `fillbyte' (η προεπιλογή είναι ένα διάστημα ASCII). Για αντικείμενα @ref{1c7,,bytes}, η αρχική ακολουθία επιστρέφεται εάν το `width' είναι μικρότερο ή ίσο με @code{len(s)}.

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

@geindex rsplit() (μέθοδος της bytes)
@geindex rsplit() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes rsplit}@anchor{281b}
@deffn {Μέθοδος} bytes.rsplit (sep=None, maxsplit=-1)
@anchor{library/stdtypes bytearray rsplit}@anchor{199a}
@deffnx {Μέθοδος} bytearray.rsplit (sep=None, maxsplit=-1)

Διαχωρίζει τη δυαδική ακολουθία σε υποακολουθίες του ίδιου τύπου, χρησιμοποιώντας το `sep' ως συμβολοσειρά οριοθέτησης. Εάν δοθεί `maxsplit', γίνονται το πολύ `maxsplit' διαχωρισμοί, οι `rightmost'.  Εάν δεν καθορίζεται `sep' ή @code{None}, οποιαδήποτε υποακολουθία που αποτελείται αποκλειστικά από κενό διάστημα ASCII είναι διαχωριστικό, εκτός από το διαχωρισμό από τα δεξιά, η @ref{199a,,rsplit()} συμπεριφέρεται όπως @ref{1999,,split()} που περιγράφεται λεπτομερώς παρακάτω.
@end deffn

@geindex rstrip() (μέθοδος της bytes)
@geindex rstrip() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes rstrip}@anchor{283f}
@deffn {Μέθοδος} bytes.rstrip (bytes=None, /)
@anchor{library/stdtypes bytearray rstrip}@anchor{2862}
@deffnx {Μέθοδος} bytearray.rstrip (bytes=None, /)

Επιστρέφει ένα αντίγραφο της ακολουθίας με τα καθορισμένα δευτερεύοντα bytes που έχουν αφαιρεθεί.  Το όρισμα `bytes' είναι μια δυαδική ακολουθία που καθορίζει το σύνολο των τιμών byte που πρέπει να αφαιρεθούν. Εάν παραληφθεί ή είναι @code{None}, το όρισμα `bytes' έχει ως προεπιλογή την αφαίρεση του κενού διαστήματος ASCII.  Το όρισμα `bytes' δεν είναι επίθημα, αλλά αφαιρούνται όλοι οι συνδυασμοί των τιμών του:

@example
>>> b'   spacious   '.rstrip()
b'   spacious'
>>> b'mississippi'.rstrip(b'ipz')
b'mississ'
@end example

Η δυαδική ακολουθία τιμών byte προς κατάργηση μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object}.  Βλέπε τη @ref{2857,,removesuffix()} για μια μέθοδο που θα αφαιρέσει μια συμβολοσειρά επιθέματος και όχι όλο το σύνολο χαρακτήρων.  Για παράδειγμα:

@example
>>> b'Monty Python'.rstrip(b' Python')
b'M'
>>> b'Monty Python'.removesuffix(b' Python')
b'Monty'
@end example

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

@geindex split() (μέθοδος της bytes)
@geindex split() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes split}@anchor{281a}
@deffn {Μέθοδος} bytes.split (sep=None, maxsplit=-1)
@anchor{library/stdtypes bytearray split}@anchor{1999}
@deffnx {Μέθοδος} bytearray.split (sep=None, maxsplit=-1)

Διαχωρίζει την δυαδική ακολουθία σε υποακολουθίες του ίδιου τύπου, χρησιμοποιώντας το `sep' ως συμβολοσειρά οριοθέτησης Εάν δοθεί `maxsplit' και μη αρνητικό, γίνονται το πολύ `maxsplit' διαχωρισμοί (άρα, η λίστα θα έχε το πολύ @code{maxsplit+1} στοιχεία).  Εάν το `maxsplit' δεν έχει καθοριστεί ή είναι @code{-1}, τότε δεν υπάρχει όριο στον αριθμό των διαχωρισμών (όλες οι πιθανές διασπάσεις γίνονται).

Αν δοθεί το `sep', οι διαδοχικοί οριοθέτες δεν ομαδοποιούνται και θεωρείται ότι οριοθετούν κενές υποακολουθίες (για παράδειγμα, @code{b'1,,2'.split(b',')} επιστρέφει το @code{[b'1', b'@w{'}, b'2']}).  Το όρισμα `sep' μπορεί να αποτελείται από μια ακολουθία πολλών byte ως μεμονωμένο οριοθέτη. Ο διαχωρισμός μιας κενής ακολουθίας με ένα καθορισμένο διαχωριστικό επιστρέφει το @code{[b'@w{'}]} ή το @code{[bytearray(b'@w{'})]} ανάλογα με τον τύπο του αντικειμένου που χωρίζεται. Το όρισμα `sep' μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object}.

Για παράδειγμα:

@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

Εάν το `sep' δεν έχει καθοριστεί ή είναι @code{None}, εφαρμόζεται ένας διαφορετικός αλγόριθμος διαχωρισμού: οι εκτελέσεις διαδοχικών κενών διαστημάτων ASCII θεωρούνται ως ένα ενιαίο διαχωριστικό, και το αποτέλεσμα δεν θα περιέχει κενές συμβολοσειρές στην αρχή ή στο τέλος, εάν η ακολουθία έχει κενό που έπεται ή προηγείται. Κατά συνέπεια, ο διαχωρισμός μιας κενής ακολουθίας ή μιας ακολουθίας που αποτελείται αποκλειστικά από κενό διάστημα ASCII χωρίς καθορισμένο διαχωριστικό επιστρέφει το @code{[]}.

Για παράδειγμα:

@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() (μέθοδος της bytes)
@geindex strip() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes strip}@anchor{283d}
@deffn {Μέθοδος} bytes.strip (bytes=None, /)
@anchor{library/stdtypes bytearray strip}@anchor{2863}
@deffnx {Μέθοδος} bytearray.strip (bytes=None, /)

Επιστρέφει ένα αντίγραφο της ακολουθίας με τα καθορισμένα bytes που προηγούνται και τα bytes που έπονται. Το όρισμα `bytes' είναι μια δυαδική ακολουθία που καθορίζει το σύνολο των τιμών byte που πρέπει να αφαιρεθούν. Εάν παραλείπεται ή είναι @code{None}, το όρισμα `bytes' από προεπιλογή αφαιρεί το ASCII λευκό διάστημα. To όρισμα `bytes' δεν είναι πρόθεμα ή επίθημα, αλλά αφαιρούνται όλοι οι συνδυασμοί των τιμών του:

@example
>>> b'   spacious   '.strip()
b'spacious'
>>> b'www.example.com'.strip(b'cmowz.')
b'example'
@end example

Η δυαδική ακολουθία τιμών byte προς αφαίρεση μπορεί να είναι οποιοδήποτε @ref{436,,bytes-like object}.

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

Οι ακόλουθες μέθοδοι σε byte και αντικείμενα bytearray προϋποθέτουν τη χρήση δυαδικών μορφών συμβατών με ASCII και δεν πρέπει να εφαρμόζονται σε αυθαίρετα δυαδικά δεδομένα. Σημειώστε ότι όλες οι μέθοδοι bytearray σε αυτήν την ενότητα `δεν' λειτουργούν στη θέση τους και αντ” αυτού παράγουν νέα αντικείμενα.

@geindex capitalize() (μέθοδος της bytes)
@geindex capitalize() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes capitalize}@anchor{2833}
@deffn {Μέθοδος} bytes.capitalize ()
@anchor{library/stdtypes bytearray capitalize}@anchor{2864}
@deffnx {Μέθοδος} bytearray.capitalize ()

Επιστρέφει ένα αντίγραφο της ακολουθίας με κάθε byte να ερμηνεύεται ως ένας χαρακτήρας ASCII, και το πρώτο byte γραμμένο με κεφαλαία και το υπόλοιπο με πεζά. Οι τιμές των byte που δεν είναι ASCII μεταβιβάζονται αμετάβλητες.

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

@geindex expandtabs() (μέθοδος της bytes)
@geindex expandtabs() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes expandtabs}@anchor{283c}
@deffn {Μέθοδος} bytes.expandtabs (tabsize=8)
@anchor{library/stdtypes bytearray expandtabs}@anchor{2865}
@deffnx {Μέθοδος} bytearray.expandtabs (tabsize=8)

Επιστρέφει ένα αντίγραφο της ακολουθίας όπου όλοι οι tab χαρακτήρες ASCII αντικαθίστανται από ένα ή περισσότερα κενά ASCII, ανάλογα με την τρέχουσα στήλη και το δεδομένο μέγεθος tab.  Οι θέσεις των tab εμφανίζονται κάθε `tabsize' bytes (η προεπιλογή είναι 8, δίνοντας θέσεις καρτελών στις στήλες 0, 8, 16 και ούτω καθεξής).  Για την επέκταση της ακολουθίας, η τρέχουσα στήλη ορίζεται στο μηδέν και η ακολουθία εξετάζεται byte προς byte.  Εάν το byte είναι tab χαρακτήρας ASCII (@code{b'\t'}), ένας ή περισσότεροι χαρακτήρες διαστήματος εισάγονται στο αποτέλεσμα έως ότου η τρέχουσα στήλη ισούται με την επόμενη θέση tab. (Ο ίδιος tab χαρακτήρας δεν αντιγράφεται.)  Εάν το τρέχον byte είναι μια νέα γραμμή ASCII (@code{b'\n'}), αντιγράφεται και η τρέχουσα στήλη επαναφέρεται στο μηδέν.  Οποιαδήποτε άλλη τιμή byte αντιγράφεται αμετάβλητη και η τρέχουσα στήλη προσαυξάνεται κατά ένα, ανεξάρτητα από το πώς αναπαρίσταται η τιμή byte όταν εκτυπώνεται:

@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 Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

@geindex isalnum() (μέθοδος της bytes)
@geindex isalnum() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes isalnum}@anchor{2826}
@deffn {Μέθοδος} bytes.isalnum ()
@anchor{library/stdtypes bytearray isalnum}@anchor{2866}
@deffnx {Μέθοδος} bytearray.isalnum ()

Επιστρέφει @code{True} εάν όλα τα byte της ακολουθίας είναι αλφαβητικοί χαρακτήρες ASCII ή ASCII δεκαδικά ψηφία και η ακολουθία δεν είναι κενή, @code{False} διαφορετικά. Οι αλφαβητικοί χαρακτήρες ASCII είναι εκείνες οι τιμές byte στην ακολουθία @code{b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'}. Τα δεκαδικά ψηφία ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b'0123456789'}.

Για παράδειγμα:

@example
>>> b'ABCabc1'.isalnum()
True
>>> b'ABC abc1'.isalnum()
False
@end example
@end deffn

@geindex isalpha() (μέθοδος της bytes)
@geindex isalpha() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes isalpha}@anchor{2820}
@deffn {Μέθοδος} bytes.isalpha ()
@anchor{library/stdtypes bytearray isalpha}@anchor{2867}
@deffnx {Μέθοδος} bytearray.isalpha ()

Επιστρέφει @code{True} εάν όλα τα bytes της ακολουθίας είναι αλφαβητικοί χαρακτήρες ASCII και η ακολουθία δεν είναι κενή, @code{False} διαφορετικά.  Οι αλφαβητικοί χαρακτήρες ASCII είναι εκείνες οι τιμές bytes στην ακολουθία @code{b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'}.

Για παράδειγμα:

@example
>>> b'ABCabc'.isalpha()
True
>>> b'ABCabc1'.isalpha()
False
@end example
@end deffn

@geindex isascii() (μέθοδος της bytes)
@geindex isascii() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes isascii}@anchor{2868}
@deffn {Μέθοδος} bytes.isascii ()
@anchor{library/stdtypes bytearray isascii}@anchor{2869}
@deffnx {Μέθοδος} bytearray.isascii ()

Επιστρέφει @code{True} εάν η ακολουθία είναι κενή ή όλα τα byte της ακολουθίας είναι ASCII, @code{False} διαφορετικά. Τα bytes ASCII βρίσκονται στο εύρος 0-0x7F.


Added in version 3.7.

@end deffn

@geindex isdigit() (μέθοδος της bytes)
@geindex isdigit() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes isdigit}@anchor{2823}
@deffn {Μέθοδος} bytes.isdigit ()
@anchor{library/stdtypes bytearray isdigit}@anchor{286a}
@deffnx {Μέθοδος} bytearray.isdigit ()

Επιστρέφει @code{True} εάν όλα τα bytes στην ακολουθία είναι δεκαδικά ψηφία ASCII και η ακολουθία δεν είναι κενή, @code{False} διαφορετικά. Τα δεκαδικά ψηφία ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b'0123456789'}.

Για παράδειγμα:

@example
>>> b'1234'.isdigit()
True
>>> b'1.23'.isdigit()
False
@end example
@end deffn

@geindex islower() (μέθοδος της bytes)
@geindex islower() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes islower}@anchor{2828}
@deffn {Μέθοδος} bytes.islower ()
@anchor{library/stdtypes bytearray islower}@anchor{286b}
@deffnx {Μέθοδος} bytearray.islower ()

Επιστρέφει @code{True} εάν υπάρχει τουλάχιστον ένας πεζός χαρακτήρας ASCII στην ακολουθία και κανένας κεφαλαίος χαρακτήρας ASCII, @code{False} διαφορετικά.

Για παράδειγμα:

@example
>>> b'hello world'.islower()
True
>>> b'Hello world'.islower()
False
@end example

Οι πεζοί χαρακτήρες ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b'abcdefghijklmnopqrstuvwxyz'}. Οι κεφαλαίοι χαρακτήρες ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.
@end deffn

@geindex isspace() (μέθοδος της bytes)
@geindex isspace() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes isspace}@anchor{282e}
@deffn {Μέθοδος} bytes.isspace ()
@anchor{library/stdtypes bytearray isspace}@anchor{286c}
@deffnx {Μέθοδος} bytearray.isspace ()

Επιστρέφει @code{True} εάν όλα τα byte στην ακολουθία είναι κενά ASCII και η ακολουθία δεν είναι κενή, @code{False} διαφορετικά.  Οι χαρακτήρες κενού διαστήματος ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b' \t\n\r\x0b\f'} (κενό, tab, νέα γραμμή, επιστροφή μεταφοράς, κάθετο tab, μορφή ροής).
@end deffn

@geindex istitle() (μέθοδος της bytes)
@geindex istitle() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes istitle}@anchor{282c}
@deffn {Μέθοδος} bytes.istitle ()
@anchor{library/stdtypes bytearray istitle}@anchor{286d}
@deffnx {Μέθοδος} bytearray.istitle ()

Επιστρέφει @code{True} εάν η ακολουθία είναι ASCII κεφαλαία τίτλου (δηλαδή τα πρώτα γράμματα των λέξεων κεφαλαία) και η ακολουθία δεν είναι κενή, @code{False} διαφορετικά. Δείτε @ref{2835,,bytes.title()} για περισσότερες λεπτομέρειες σχετικά με τον ορισμό του «titlecase».

Για παράδειγμα:

@example
>>> b'Hello World'.istitle()
True
>>> b'Hello world'.istitle()
False
@end example
@end deffn

@geindex isupper() (μέθοδος της bytes)
@geindex isupper() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes isupper}@anchor{282a}
@deffn {Μέθοδος} bytes.isupper ()
@anchor{library/stdtypes bytearray isupper}@anchor{286e}
@deffnx {Μέθοδος} bytearray.isupper ()

Επιστρέφει @code{True} εάν υπάρχει τουλάχιστον ένας κεφαλαίος αλφαβητικός χαρακτήρας ASCII στην ακολουθία και κανένας πεζός χαρακτήρας ASCII, διαφορετικά @code{False}.

Για παράδειγμα:

@example
>>> b'HELLO WORLD'.isupper()
True
>>> b'Hello world'.isupper()
False
@end example

Οι πεζοί χαρακτήρες ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b'abcdefghijklmnopqrstuvwxyz'}. Οι κεφαλαίοι χαρακτήρες ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.
@end deffn

@geindex lower() (μέθοδος της bytes)
@geindex lower() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes lower}@anchor{282f}
@deffn {Μέθοδος} bytes.lower ()
@anchor{library/stdtypes bytearray lower}@anchor{286f}
@deffnx {Μέθοδος} bytearray.lower ()

Επιστρέφει ένα αντίγραφο της ακολουθίας με όλους τους κεφαλαίους χαρακτήρες ASCII να έχουν μετατραπεί στα ισοδύναμα πεζά.

Για παράδειγμα:

@example
>>> b'Hello World'.lower()
b'hello world'
@end example

Οι πεζοί χαρακτήρες ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b'abcdefghijklmnopqrstuvwxyz'}. Οι κεφαλαίοι χαρακτήρες ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

@geindex καθολικές νέες γραμμές;bytes.splitlines μέθοδος
@geindex καθολικές νέες γραμμές;bytearray.splitlines μέθοδος

@geindex splitlines() (μέθοδος της bytes)
@geindex splitlines() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes splitlines}@anchor{281c}
@deffn {Μέθοδος} bytes.splitlines (keepends=False)
@anchor{library/stdtypes bytearray splitlines}@anchor{2870}
@deffnx {Μέθοδος} bytearray.splitlines (keepends=False)

Επιστρέφει μια λίστα με τις γραμμές στη δυαδική ακολουθία, σπάζοντας τα όρια γραμμής του ASCII. Αυτή η μέθοδος χρησιμοποιεί την προσέγγιση @ref{10f1,,universal newlines} για τον διαχωρισμό των γραμμών. Οι αλλαγές γραμμής δεν περιλαμβάνονται στη λίστα που προκύπτει εκτός εάν δοθεί `keepends' και είναι αληθής.

Για παράδειγμα:

@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

Σε αντίθεση με το @ref{281a,,split()} όταν δίνεται μια οριοθετημένη συμβολοσειρά `sep', αυτή η μέθοδος επιστρέφει μια κενή λίστα για την κενή συμβολοσειρά και μια αλλαγή γραμμής τερματικού δεν οδηγεί σε μια επιπλέον γραμμή:

@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() (μέθοδος της bytes)
@geindex swapcase() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes swapcase}@anchor{2837}
@deffn {Μέθοδος} bytes.swapcase ()
@anchor{library/stdtypes bytearray swapcase}@anchor{2871}
@deffnx {Μέθοδος} bytearray.swapcase ()

Επιστρέφει ένα αντίγραφο της ακολουθίας με όλους τους πεζούς χαρακτήρες ASCII να έχουν μετατραπεί στο αντίστοιχο ισοδύναμο κεφαλαίο και αντίστροφα.

Για παράδειγμα:

@example
>>> b'Hello World'.swapcase()
b'hELLO wORLD'
@end example

Οι πεζοί χαρακτήρες ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b'abcdefghijklmnopqrstuvwxyz'}. Οι κεφαλαίοι χαρακτήρες ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.

Σε αντίθεση με το @ref{2836,,str.swapcase()}, συμβαίνει πάντα ότι @code{bin.swapcase().swapcase() == bin} για τις δυαδικές εκδόσεις. Οι μετατροπές κεφαλαίων είναι συμμετρικές στο ASCII, παρόλο που αυτό δεν ισχύει γενικά για αυθαίρετα σημεία Unicode κώδικα.

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

@geindex title() (μέθοδος της bytes)
@geindex title() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes title}@anchor{2835}
@deffn {Μέθοδος} bytes.title ()
@anchor{library/stdtypes bytearray title}@anchor{2872}
@deffnx {Μέθοδος} bytearray.title ()

Επιστρέφει μια έκδοση με κεφαλαία τίτλου (δηλαδή τα πρώτα γράμματα των λέξεων κεφαλαία) της δυαδικής ακολουθίας όπου οι λέξεις ξεκινούν με κεφαλαίο χαρακτήρα ASCII και οι υπόλοιποι χαρακτήρες είναι πεζοί. Οι τιμές byte χωρίς κεφαλαία γράμματα παραμένουν χωρίς τροποποίηση.

Για παράδειγμα:

@example
>>> b'Hello world'.title()
b'Hello World'
@end example

Οι πεζοί χαρακτήρες ASCII είναι εκείνες οι τιμές byte στην ακολουθία @code{b'abcdefghijklmnopqrstuvwxyz'}. Οι κεφαλαίο χαρακτήρες ASCII είναι εκείνες οι τιμές byte στην ακολουθία @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. Όλες οι άλλες τιμές byte είναι χωρίς κεφαλαία.

Ο αλγόριθμος χρησιμοποιεί έναν απλό, ανεξάρτητο από τη γλώσσα, ορισμό μιας λέξης ως group διαδοχικών γραμμάτων.  Ο ορισμός λειτουργεί σε πολλά contexts, αλλά σημαίνει ότι οι απόστροφοι σε συναιρέσεις και κτητικές λέξεις αποτελούν όρια λέξεων, που μπορεί να μην είναι το επιθυμητό αποτέλεσμα:

@example
>>> b"they're bill's friends from the UK".title()
b"They'Re Bill'S Friends From The Uk"
@end example

Μια λύση για αποστρόφους μπορεί να δημιουργηθεί χρησιμοποιώντας κανονικές εκφράσεις:

@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 Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

@geindex upper() (μέθοδος της bytes)
@geindex upper() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes upper}@anchor{2831}
@deffn {Μέθοδος} bytes.upper ()
@anchor{library/stdtypes bytearray upper}@anchor{2873}
@deffnx {Μέθοδος} bytearray.upper ()

Επιστρέφει ένα αντίγραφο της ακολουθίας με όλους τους πεζούς χαρακτήρες ASCII να έχουν μετατραπεί στο αντίστοιχο ισοδύναμο κεφαλαίο.

Για παράδειγμα:

@example
>>> b'Hello World'.upper()
b'HELLO WORLD'
@end example

Οι πεζοί χαρακτήρες ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b'abcdefghijklmnopqrstuvwxyz'}. Οι κεφαλαίοι χαρακτήρες ASCII είναι αυτές οι τιμές byte στην ακολουθία @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

@geindex zfill() (μέθοδος της bytes)
@geindex zfill() (μέθοδος της bytearray)
@anchor{library/stdtypes bytes zfill}@anchor{2874}
@deffn {Μέθοδος} bytes.zfill (width, /)
@anchor{library/stdtypes bytearray zfill}@anchor{2875}
@deffnx {Μέθοδος} bytearray.zfill (width, /)

Επιστρέφει ένα αντίγραφο της ακολουθίας που έχει απομείνει γεμάτο με ψηφία ASCII @code{b'0'} για να δημιουργήσετε μια ακολουθία μήκους `width'. Ένα πρόθεμα προπορευόμενου σήματος (@code{b'+'}/ @code{b'-'}) αντιμετωπίζεται με την εισαγωγή της συμπλήρωσης του `after' χαρακτήρα προσήμου και όχι πριν. Για αντικείμενα @ref{1c7,,bytes}, η αρχική ακολουθία επιστρέφεται εάν το `width' είναι μικρότερο ή ίσο με @code{len(seq)}.

Για παράδειγμα:

@example
>>> b"42".zfill(5)
b'00042'
>>> b"-42".zfill(5)
b'-0042'
@end example

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche
@end deffn

@node Μορφοποίηση Bytes τύπου printf,Όψεις Μνήμης,Λειτουργίες Bytes και Bytearray,Τύποι δυαδικής ακολουθίας — bytes bytearray memoryview
@anchor{library/stdtypes bytes-formatting}@anchor{113a}@anchor{library/stdtypes printf-style-bytes-formatting}@anchor{2876}
@subsubsection Μορφοποίηση Bytes τύπου @code{printf}


@geindex μορφοποίηση;bytes (%)
@geindex μορφοποίηση;bytearray (%)
@geindex μεταβολή;bytes (%)
@geindex μεταβολή;bytearray (%)
@geindex bytes;μορφοποίηση
@geindex bytearray;μορφοποίηση
@geindex bytes;μεταβολή
@geindex bytearray;μεταβολή
@geindex μορφοποίηση σε στυλ printf
@geindex μορφοποίηση σε στυλ sprintf
@geindex % (τοις εκατό);μορφοποίηση σε στυλ printf

@cartouche
@quotation Σημείωση 
Οι λειτουργίες μορφοποίησης που περιγράφονται εδώ παρουσιάζουν μια ποικιλία ιδιορρυθμιών που οδηγούν σε μια σειρά από κοινά σφάλματα (όπως η αποτυχία εμφάνισης των πλειάδων και των λεξικών σωστά).  Εάν η τιμή που εκτυπώνεται μπορεί να είναι πλειάδα ή λεξικό, κάντε το wrap σε μια πλειάδα.
@end quotation
@end cartouche

Τα αντικείμενα bytes (@code{bytes}/@code{bytearray}) έχουν μια μοναδική ενσωματωμένη λειτουργία: τον τελεστή @code{%} (modulo). Αυτό είναι επίσης γνωστό ως τελεστής bytes `formatting' ή `interpolation'. Δεδομένων των @code{format % values} (όπου το `format' είναι αντικείμενο bytes), οι προδιαγραφές μετατροπής @code{%} σε `format' αντικαθιστά με μηδέν ή περισσότερα στοιχεία `values'. Το αποτέλεσμα είναι παρόμοιο με τη χρήση του @code{sprintf()} στη γλώσσας C.

Εάν το `format' απαιτεί ένα μεμονωμένο όρισμα, το `values' μπορεί να είναι ένα μεμονωμένο μη πολλαπλό αντικείμενο. @footnote{
Για να μορφοποιήσετε μόνο μια πλειάδα (tuple) θα πρέπει επομένως να παρέχετε μια πλειάδα singleton της οποίας το μόνο στοιχείο είναι η πλειάδα που πρόκειται να μορφοποιηθεί.
} Διαφορετικά, το `values' πρέπει να είναι πλειάδα με ακριβώς τον αριθμό των στοιχείων που καθορίζονται από το αντικείμενο μορφής bytes ή μεμονωμένο mapping αντικείμενο (για παράδειγμα, ένα λεξικό).

@geindex () (παρενθέσεις);σε μορφοποίηση σε στυλ printf
@geindex * (αστερίσκος);σε μορφοποίηση σε στυλ printf
@geindex . (τελεία);σε μορφοποίηση σε στυλ printf

Ένας προσδιοριστής μετατροπής περιέχει δύο ή περισσότερους χαρακτήρες και έχει τους εξής components, οι οποίοι πρέπει να εμφανίζονται με αυτή τη σειρά:


@enumerate 

@item 
Ο χαρακτήρας @code{`%'@w{'}}, που σηματοδοτεί την αρχή του προσδιοριστή.

@item 
Κλειδί mapping (προαιρετικό), που αποτελείται από μια ακολουθία χαρακτήρων σε παρένθεση (για παράδειγμα, @code{(somename)}).

@item 
Δείκτες μετατροπής (προαιρετικό), που επηρεάζουν το αποτέλεσμα κάποιων τύπων μετατροπής.

@item 
Ελάχιστο πλάτος πεδίου (προαιρετικό). Εάν ορίζεται ως @code{'*'} (αστερίσκος), το πραγματικό πλάτος διαβάζεται από το επόμενο στοιχείο του tuple στα `values', και το αντικείμενο προς μετατροπή έρχεται μετά από το ελάχιστο πλάτος πεδίου και το προαιρετικό precision.

@item 
Ακρίβεια (προαιρετικό), δίνεται ως @code{'.'} (τελεία) ακολουθούμενη από το precision.Εάν ορίζεται ως @code{'*'} (αστερίσκος), το πραγματικό precision διαβάζεται από το επόμενο στοιχείο του tuple στα `values', και η τιμή προς μετατροπή έρχεται μετά το precision.

@item 
Μετατροπέας του length (προαιρετικό).

@item 
Τύπος conversion.
@end enumerate

Όταν το σωστό όρισμα είναι ένα λεξικό (ή άλλος τύπος αντιστοίχισης), τότε οι μορφές στο αντικείμενο bytes `πρέπει' να περιλαμβάνουν ένα κλειδί αντιστοίχισης σε παρένθεση σε αυτό το λεξικό που έχει εισαχθεί αμέσως μετά τον χαρακτήρα @code{'%'}. Το κλειδί αντιστοίχισης επιλέγει την τιμή που θα μορφοποιηθεί από την αντιστοίχιση.  Για παράδειγμα:

@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

Σε αυτήν την περίπτωση δεν μπορεί να υπάρχουν προσδιοριστές @code{*} σε μια μορφή (καθώς απαιτούν μια διαδοχική λίστα παραμέτρων).

Οι δείκτες μετατροπής είναι:

@geindex # (δίεση);σε μορφοποίηση σε στυλ printf
@geindex - (πλην);σε μορφοποίηση σε στυλ printf
@geindex + (συν);σε μορφοποίηση σε στυλ printf
@geindex διάστημα;σε μορφοποίηση σε στυλ printf


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Flag

@tab

Έννοια

@item

@code{'#'}

@tab

Οι μετατροπή τιμής θα χρησιμοποιήσει την «εναλλακτική φόρμα» (όπου ορίζεται παρακάτω).

@item

@code{'0'}

@tab

Η μετατροπή θα έχει μηδενική συμπλήρωση για αριθμητικές τιμές.

@item

@code{'-'}

@tab

Η τιμή μετατροπής αφήνεται προσαρμοσμένη (παρακάμπτει τη μετατροπή @code{'0'} εάν δίνονται και τα δύο).

@item

@code{' '}

@tab

(ένα κενό) Πρέπει να προστεθεί ένα κενό πριν από έναν θετικό αριθμό (ή κενή συμβολοσειρά) που παράγεται από μια υπογεγραμμένη μετατροπή.

@item

@code{'+'}

@tab

Ένα χαρακτήρας προσήμου (@code{'+'} ή @code{'-'}) θα προηγείται της μετατροπής (παρακάμπτει ένα «κενό» δείκτη).

@end multitable


Ένας τροποποιητής μήκους (@code{h}, @code{l}, or @code{L}) μπορεί να υπάρχει, αλλά αγνοείται καθώς δεν είναι απαραίτητος για την Python – οπότε π.χ. @code{%ld} είναι πανομοιότυπο σε @code{%d}.

Οι τύποι μετατροπής είναι:


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Μετατροπή

@tab

Έννοια

@tab

Σημειώσεις

@item

@code{'d'}

@tab

Υπογεγραμμένος δεκαδικός ακέραιος.

@tab

@item

@code{'i'}

@tab

Υπογεγραμμένος δεκαδικός ακέραιος.

@tab

@item

@code{'o'}

@tab

Υπογεγραμμένη οκταδική τιμή.

@tab

(1)

@item

@code{'u'}

@tab

Απαρχαιωμένος τύπος – είναι πανομοιότυπος με το @code{'d'}.

@tab

(8)

@item

@code{'x'}

@tab

Υπογεγραμμένο δεκαεξαδικό (πεζά).

@tab

(2)

@item

@code{'X'}

@tab

Υπογεγραμμένο δεκαεξαδικό (κεφαλαίο).

@tab

(2)

@item

@code{'e'}

@tab

Εκθετική μορφή κινητής υποδιαστολής (πεζά)

@tab

(3)

@item

@code{'E'}

@tab

Εκθετική μορφή κινητής υποδιαστολής (κεφαλαία)

@tab

(3)

@item

@code{'f'}

@tab

Δεκαδική μορφή κινητής υποδιαστολής.

@tab

(3)

@item

@code{'F'}

@tab

Δεκαδική μορφή κινητής υποδιαστολής.

@tab

(3)

@item

@code{'g'}

@tab

Μορφή κινητής υποδιαστολής. Χρησιμοποιεί εκθετική μορφή πεζών αν ο εκθέτης είναι μικρότερος από -4 ή όχι μικρότερος από την ακρίβεια, διαφορετικά χρησιμοποιεί δεκαδική μορφή.

@tab

(4)

@item

@code{'G'}

@tab

Μορφή κινητής υποδιαστολής. Χρησιμοποιεί εκθετική μορφή κεφαλαίων εάν ο εκθέτης είναι μικρότερος από -4 ή όχι μικρότερος από την ακρίβεια, διαφορετικά χρησιμοποιεί δεκαδική μορφή.

@tab

(4)

@item

@code{'c'}

@tab

Μονό byte (δέχεται ακέραια ή μεμονωμένα byte αντικείμενα).

@tab

@item

@code{'b'}

@tab

Bytes (κάθε αντικείμενο που ακολουθεί το @ref{311,,buffer protocol} ή έχει @ref{9df,,__bytes__()}).

@tab

(5)

@item

@code{'s'}

@tab

Το @code{'s'} είναι ένα ψευδώνυμο για το @code{'b'} και θα πρέπει να χρησιμοποιείται μόνο για κώδικα βάσει Python2/3.

@tab

(6)

@item

@code{'a'}

@tab

Bytes (μετατρέπει οποιοδήποτε αντικείμενο Python χρησιμοποιώντας @code{repr(obj).encode('ascii', 'backslashreplace')}).

@tab

(5)

@item

@code{'r'}

@tab

Το @code{'r'} είναι ένα ψευδώνυμο για @code{'a'} και θα πρέπει να χρησιμοποιείται μόνο για βάσεις κώδικα Python2/3.

@tab

(7)

@item

@code{'%'}

@tab

Κανένα όρισμα δεν μετατρέπεται, έχει ως αποτέλεσμα έναν χαρακτήρα @code{'%'} το αποτέλεσμα.

@tab

@end multitable


Σημειώσεις:


@enumerate 

@item 
Η εναλλακτική μορφή προκαλεί την εισαγωγή ενός πρώτου οκταδικού προσδιοριστή (@code{'0o'}) πριν από το πρώτο ψηφίο.

@item 
Η εναλλακτική φόρμα προκαλεί την εισαγωγή ενός αρχικού @code{'0x'} ή @code{'0X'} (ανάλογα με το εάν χρησιμοποιήθηκε η μορφή @code{'x'} ή @code{'X'}) πριν το πρώτο ψηφίο.

@item 
Η εναλλακτική μορφή κάνει το αποτέλεσμα να περιέχει πάντα μια υποδιαστολή, ακόμα κι αν δεν ακολουθούν ψηφία.

Η ακρίβεια καθορίζει τον αριθμό των ψηφίων μετά την υποδιαστολή και ορίζεται από προεπιλογή ως 6.

@item 
Η εναλλακτική μορφή κάνει το αποτέλεσμα να περιέχει πάντα μια υποδιαστολή και τα μηδενικά στο τέλος δεν αφαιρούνται όπως θα ήταν διαφορετικά.

Η ακρίβεια καθορίζει τον αριθμό των σημαντικών ψηφίων πριν και μετά την υποδιαστολή και ορίζει το 6.

@item 
Εάν η ακρίβεια είναι @code{N}, η έξοδος περικόπτεται σε @code{N} χαρακτήρες.

@item 
Το @code{b'%s'} έχει καταργηθεί, αλλά δεν θα αφαιρεθεί κατά τη διάρκεια της σειράς 3.x.

@item 
Το @code{b'%r'} έχει καταργηθεί, αλλά δεν θα αφαιρεθεί κατά τη διάρκεια της σειράς 3.x.

@item 
Βλέπε 
@geindex Python Enhancement Proposals; PEP 237
PEP 237@footnote{https://peps.python.org/pep-0237/}.
@end enumerate

@cartouche
@quotation Σημείωση 
Η έκδοση bytearray αυτής της μεθόδου `δεν' λειτουργεί στη θέση της - παράγει πάντα ένα νέο αντικείμενο, ακόμα και αν δεν έγιναν αλλαγές.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 461
PEP 461@footnote{https://peps.python.org/pep-0461/} - Προσθήκη % για μορφοποίηση σε bytes και bytearray



Added in version 3.5.


@node Όψεις Μνήμης,,Μορφοποίηση Bytes τύπου printf,Τύποι δυαδικής ακολουθίας — bytes bytearray memoryview
@anchor{library/stdtypes memory-views}@anchor{2877}@anchor{library/stdtypes typememoryview}@anchor{27d1}
@subsubsection Όψεις Μνήμης


Τα αντικείμενα @ref{1d2,,memoryview} επιτρέπουν στον κώδικα Python να έχει πρόσβαση στα εσωτερικά δεδομένα ενός αντικειμένου που υποστηρίζει το πρωτόκολλο @ref{311,,buffer protocol} χωρίς αντιγραφή.

@geindex memoryview (ενσωματωμένη κλάση)
@anchor{library/stdtypes memoryview}@anchor{1d2}
@deffn {Κλάση} memoryview (object)

Δημιουργεί μια @ref{1d2,,memoryview} που αναφέρεται στο `object'.  Το `object' πρέπει να υποστηρίζει το πρωτόκολλο buffer.  Τα ενσωματωμένα αντικείμενα που υποστηρίζουν το πρωτόκολλο buffer περιλαμβάνουν @ref{1c7,,bytes} και @ref{1c6,,bytearray}.

Μια @ref{1d2,,memoryview} έχει την έννοια ενός `στοιχείου', το οποίο είναι η μονάδα ατομικής μνήμης που χειρίζεται το αρχικό `object'.  Για πολλούς απλούς τύπους όπως @ref{1c7,,bytes} και @ref{1c6,,bytearray}, ένα στοιχείο είναι ένα μεμονωμένο byte, αλλά άλλοι τύποι όπως @ref{6c5,,array.array} μπορεί να έχουν μεγαλύτερα στοιχεία.

@code{len(view)} is equal to the length of @ref{2878,,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.


Άλλαξε στην έκδοση 3.12: Εάν @code{view.ndim == 0}, το @code{len(view)} τώρα κάνει raise μια @ref{291,,TypeError} αντί να επιστρέψει 1.


Το χαρακτηριστικό @ref{2879,,itemsize} θα σας δώσει τον αριθμό των byte σε ένα μόνο στοιχείο.

Μια @ref{1d2,,memoryview} υποστηρίζει λειτουργίες τμηματοποίησης και πρόσβαση μέσω ευρετηρίου στα δεδομένα του. Μια μονοδιάστατη τμηματοποίηση θα έχει ως αποτέλεσμα μια δευτερεύουσα προβολή:

@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

Εάν το @ref{287a,,format} είναι ένας από τους προσδιοριστές εγγενούς μορφής από το module @ref{de,,struct}, η πρόσβαση μέσω ευρετηρίου με έναν ακέραιο ή μια πλειάδα (tuple) ακεραίων υποστηρίζεται επίσης και επιστρέφει ένα μεμονωμένο `στοιχείο' με το σωστό τύπο.  Τα μονοδιάστατα memoryviews μπορούν να γίνουν indexed με έναν ακέραιο ή έναν ακέραιο πλειάδα (tuple).  Τα πολυδιάστατα memoryviews μπορούν αν γίνουν indexed με πλειάδες (tuples) ακριβώς `ndim' ακεραίων όπου `ndim' είναι ο αριθμός των διαστάσεων.  Τα μηδενικών διαστάσεων memoryviews μπορούν να γίνουν indexed με την κενή πλειάδα (tuple).

Ακολουθεί ένα παράδειγμα με μη-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

Εάν το βασικό αντικείμενο είναι εγγράψιμο, το memoryview υποστηρίζει μονοδιάστατη εκχώρηση τμηματοποίησης. Δεν επιτρέπεται η αλλαγή μεγέθους:

@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

Τα μονοδιάστατα memoryviews των τύπων @ref{183,,hashable} (μόνο για ανάγνωση) με μορφές “B”, “b” ή “c” μπορούν επίσης να κατακερματιστούν. Ο κατακερματισμός ορίζεται ως @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


Άλλαξε στην έκδοση 3.3: Τα μονοδιάστατα memoryviews μπορούν πλέον να τμηματοποιηθούν. Τα μονοδιάστατα memoryviews με μορφές “B”, “b” ή “c” είναι πλέον @ref{183,,hashable}.



Άλλαξε στην έκδοση 3.4: το memoryview εγγράφεται πλέον αυτόματα με @ref{156d,,collections.abc.Sequence}



Άλλαξε στην έκδοση 3.5: τα memoryviews μπορούν τώρα να γίνουν ευρετηριοποίηση με πλειάδα (tuple) ακεραίων.



Άλλαξε στην έκδοση 3.14: το memoryview είναι πλέον ένα @ref{1d1,,generic type}.


το @ref{1d2,,memoryview} έχει διάφορες μεθόδους:

@geindex __eq__() (μέθοδος της memoryview)
@anchor{library/stdtypes memoryview __eq__}@anchor{287b}
@deffn {Μέθοδος} __eq__ (exporter)

Ένα memoryview και ένας εξαγωγέας 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/} είναι ίσοι εάν τα σχήματα τους είναι ισοδύναμα και εάν όλες οι αντίστοιχες τιμές είναι ίσες όταν οι αντίστοιχοι κωδικοί μορφής των τελεστών ερμηνεύονται χρησιμοποιώντας τη σύνταξη @ref{de,,struct}.

Για το υποσύνολο του @ref{de,,struct} οι συμβολοσειρές μορφής που υποστηρίζονται αυτή τη στιγμή από το @ref{2878,,tolist()}, @code{v} και @code{w} είναι ίσες εάν @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

Εάν καμία συμβολοσειρά μορφής δεν υποστηρίζεται από το module @ref{de,,struct}, τότε τα αντικείμενα θα συγκρίνονται πάντα ως άνισα (ακόμα και αν οι συμβολοσειρές μορφοποίησης και τα περιεχόμενα της προσωρινής μνήμης είναι πανομοιότυπα):

@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

Λάβετε υπόψη ότι, όπως και με τους αριθμούς κινητής υποδιαστολής, @code{v is w} `δεν' σημαίνει @code{v == w} για αντικείμενα memoryview.


Άλλαξε στην έκδοση 3.3: Οι προηγούμενες εκδόσεις συνέκριναν την ακατέργαστη μνήμη αγνοώντας τη μορφή του στοιχείου και τη δομή του λογικού πίνακα.

@end deffn

@geindex tobytes() (μέθοδος της memoryview)
@anchor{library/stdtypes memoryview tobytes}@anchor{287c}
@deffn {Μέθοδος} tobytes (order='C')

Επιστρέφει τα δεδομένα στο buffer ως ένα bytestring.  Αυτό ισοδυναμεί με την κλήση του κατασκευαστή @ref{1c7,,bytes} στο memoryview.

@example
>>> m = memoryview(b"abc")
>>> m.tobytes()
b'abc'
>>> bytes(m)
b'abc'
@end example

Για μη συνεχόμενους πίνακες, το αποτέλεσμα είναι ίσο με την αναπαράσταση της ισοπεδωμένης λίστας με όλα τα στοιχεία να μετατρέπονται σε bytes. Η @ref{287c,,tobytes()} υποστηρίζει όλες τις συμβολοσειρές μορφής, συμπεριλαμβανομένων εκείνων που δεν είναι στη σύνταξη του module @ref{de,,struct}.


Added in version 3.8: Το `order' μπορεί να είναι @{“C”, “F”, “A”@}.  Όταν το `order' είναι “C” ή “F”, τα δεδομένα του αρχικού πίνακα μετατρέπονται σε C ή σε σειρά Fortran. Για συνεχόμενες όψεις, το “A” επιστρέφει ένα ακριβές αντίγραφο της φυσικής μνήμης. Συγκεκριμένα, διατηρείται σειρά Fortran στη μνήμη. Για μη συνεχόμενες προβολές, τα δεδομένα μετατρέπονται πρώτα σε C. Το `order=None' είναι το ίδιο με το `order=”C”'.

@end deffn

@geindex hex() (μέθοδος της memoryview)
@anchor{library/stdtypes memoryview hex}@anchor{1120}
@deffn {Μέθοδος} hex (*, bytes_per_sep=1)

@deffnx {Μέθοδος} hex (sep, bytes_per_sep=1)

Επιστρέφει ένα αντικείμενο συμβολοσειράς που περιέχει δύο δεκαεξαδικά ψηφία για κάθε byte στο buffer.

@example
>>> m = memoryview(b"abc")
>>> m.hex()
'616263'
@end example


Added in version 3.5.



Άλλαξε στην έκδοση 3.8: Παρόμοιο με το @ref{111e,,bytes.hex()}, το @ref{1120,,memoryview.hex()} τώρα υποστηρίζει προαιρετικές παραμέτρους `sep' και `bytes_per_sep' για να εισάγετε διαχωριστικά μεταξύ των byte στην εξαγωγή δεκαεξαδικού.

@end deffn

@geindex tolist() (μέθοδος της memoryview)
@anchor{library/stdtypes memoryview tolist}@anchor{2878}
@deffn {Μέθοδος} tolist ()

Επιστρέψτε τα δεδομένα στο buffer ως λίστα στοιχείων.

@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


Άλλαξε στην έκδοση 3.3: Η @ref{2878,,tolist()} υποστηρίζει πλέον όλες τις εγγενείς μορφές μεμονωμένων χαρακτήρων στη σύνταξη του @ref{de,,struct}, καθώς και πολυδιάστατες αναπαραστάσεις.

@end deffn

@geindex toreadonly() (μέθοδος της memoryview)
@anchor{library/stdtypes memoryview toreadonly}@anchor{287d}
@deffn {Μέθοδος} toreadonly ()

Επιστρέφει μια έκδοση μόνο για ανάγνωση του αντικειμένου memoryview.  Το αρχικό αντικείμενο memoryview είναι αμετάβλητο.

@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


Added in version 3.8.

@end deffn

@geindex release() (μέθοδος της memoryview)
@anchor{library/stdtypes memoryview release}@anchor{1567}
@deffn {Μέθοδος} release ()

Απελευθερώνει το υποκείμενο buffer που εκτίθεται από το αντικείμενο memoryview.  Πολλά αντικείμενα πραγματοποιούν ειδικές ενέργειες όταν διατηρείται μια προβολή σε αυτά (για παράδειγμα, μια @ref{1c6,,bytearray} θα απαγόρευε προσωρινά την αλλαγή μεγέθους)· επομένως, η κλήση της release() είναι βολική για την κατάργηση αυτών των περιορισμών (και απελευθερώνει οποιουσδήποτε αιωρούμενους πόρους) το συντομότερο δυνατό.

Μετά την κλήση αυτής της μεθόδου, οποιαδήποτε περαιτέρω λειτουργία στην προβολή δημιουργεί μια @ref{277,,ValueError} (εκτός από την ίδια την @ref{1567,,release()} που μπορεί να κληθεί πολλές φορές):

@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

Το πρωτόκολλο διαχείρισης περιεχομένου μπορεί να χρησιμοποιηθεί για παρόμοιο αποτέλεσμα, χρησιμοποιώντας τη δήλωση @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


Added in version 3.2.

@end deffn

@geindex cast() (μέθοδος της memoryview)
@anchor{library/stdtypes memoryview cast}@anchor{18fc}
@deffn {Μέθοδος} cast (format, /)

@deffnx {Μέθοδος} cast (format, shape, /)

Μορφοποιεί ένα memoryview σε νέα μορφή ή σχήμα. Το `shape' είναι από προεπιλογή @code{[byte_length//new_itemsize]}, που σημαίνει ότι η προβολή αποτελέσματος θα είναι μονοδιάστατη. Η επιστρεφόμενη τιμή είναι ένα νέο memoryview, αλλά το ίδιο το buffer δεν αντιγράφεται. Οι υποστηριζόμενες μετατροπές είναι 1D -> C-@ref{287e,,contiguous} και C-contiguous -> 1D.

Η μορφή προορισμού περιορίζεται σε μια εγγενή μορφή μεμονωμένου στοιχείου στη σύνταξη @ref{de,,struct}. Μία από τις μορφές πρέπει να είναι μορφή byte (“B”, “b” ή “c”). Το μήκος byte του αποτελέσματος πρέπει να είναι το ίδιο με το αρχικό μήκος. Σημειώστε ότι όλα τα μήκη byte μπορεί να εξαρτώνται από το λειτουργικό σύστημα.

Μορφοποίηση από 1D/long σε 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

Μορφοποίηση από 1D/unsigned bytes σε 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

Μορφοποίηση από 1D/bytes σε 3D/ints σε 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

Μορφοποίηση από 1D/unsigned long σε 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


Added in version 3.3.



Άλλαξε στην έκδοση 3.5: Η πηγαία μορφή δεν είναι πλέον περιορισμένη κατά τη μορφοποίηση σε μια όψη byte.

@end deffn

@geindex count() (μέθοδος της memoryview)
@anchor{library/stdtypes memoryview count}@anchor{1b17}
@deffn {Μέθοδος} count (value, /)

Μετράει τον αριθμό των εμφανίσεων του `value'.


Added in version 3.14.

@end deffn

@geindex index() (μέθοδος της memoryview)
@anchor{library/stdtypes memoryview index}@anchor{1b16}
@deffn {Μέθοδος} index (value, start=0, stop=sys.maxsize, /)

Επιστρέφει τον δείκτη της πρώτης εμφάνισης του `value' (στην ή μετά τον δείκτη `start' και πριν από τον δείκτη `stop').

Κάνει raise μια @ref{277,,ValueError} αν δεν μπορεί να βρεθεί η τιμή `value'.


Added in version 3.14.

@end deffn

Υπάρχουν επίσης αρκετά διαθέσιμα χαρακτηριστικά μόνο για ανάγνωση:

@geindex obj (ιδιότητα της memoryview)
@anchor{library/stdtypes memoryview obj}@anchor{287f}
@deffn {Ιδιότητα} obj

Το βασικό αντικείμενο του memoryview:

@example
>>> b  = bytearray(b'xyz')
>>> m = memoryview(b)
>>> m.obj is b
True
@end example


Added in version 3.3.

@end deffn

@geindex nbytes (ιδιότητα της memoryview)
@anchor{library/stdtypes memoryview nbytes}@anchor{2880}
@deffn {Ιδιότητα} nbytes

@code{nbytes == product(shape) * itemsize == len(m.tobytes())}. Αυτή είναι η ποσότητα χώρου σε byte που θα χρησιμοποιούσε ο πίνακας σε μια συνεχόμενη αναπαράσταση. Δεν ισούται απαραίτητα με @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

Πολυδιάστατοι πίνακες:

@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


Added in version 3.3.

@end deffn

@geindex readonly (ιδιότητα της memoryview)
@anchor{library/stdtypes memoryview readonly}@anchor{2881}
@deffn {Ιδιότητα} readonly

Ένα bool που υποδεικνύει εάν η μνήμη είναι μόνο για ανάγνωση.
@end deffn

@geindex format (ιδιότητα της memoryview)
@anchor{library/stdtypes memoryview format}@anchor{287a}
@deffn {Ιδιότητα} format

Μια συμβολοσειρά που περιέχει τη μορφή (σε module style @ref{de,,struct}) για κάθε στοιχείο σε μια όψη. Μπορεί να δημιουργηθεί ένα memoryview από εξαγωγείς με συμβολοσειρές αυθαίρετης μορφής, αλλά ορισμένες μέθοδοι (π.χ. @ref{2878,,tolist()}) είναι περιορισμένες σε εγγενείς μορφές ενός στοιχείου.


Άλλαξε στην έκδοση 3.3: η μορφή @code{'B'} αντιμετωπίζεται πλέον σύμφωνα με τη σύνταξη ενός struct module. Αυτό σημαίνει ότι @code{memoryview(b'abc')[0] == b'abc'[0] == 97}.

@end deffn

@geindex itemsize (ιδιότητα της memoryview)
@anchor{library/stdtypes memoryview itemsize}@anchor{2879}
@deffn {Ιδιότητα} itemsize

Το μέγεθος σε bytes κάθε στοιχείου στο memoryview:

@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 (ιδιότητα της memoryview)
@anchor{library/stdtypes memoryview ndim}@anchor{2882}
@deffn {Ιδιότητα} ndim

Ένα ακέραιος αριθμός που δείχνει πόσες διαστάσεις ενός πολυδιάστατου πίνακα αντιπροσωπεύει η μνήμη.
@end deffn

@geindex shape (ιδιότητα της memoryview)
@anchor{library/stdtypes memoryview shape}@anchor{2883}
@deffn {Ιδιότητα} shape

Μια πλειάδα (tuple) ακεραίων με μήκος @ref{2882,,ndim} δίνοντας το σχήμα της μνήμης ως πίνακα N-διαστάσεων.


Άλλαξε στην έκδοση 3.3: Μια κενή πλειάδα (tuple) αντί για @code{None} όταν ndim = 0.

@end deffn

@geindex strides (ιδιότητα της memoryview)
@anchor{library/stdtypes memoryview strides}@anchor{2884}
@deffn {Ιδιότητα} strides

Μια πλειάδα ακεραίων με μήκος @ref{2882,,ndim} που δίνει το μέγεθος σε bytes για την πρόσβαση σε κάθε στοιχείο για κάθε διάσταση του πίνακα.


Άλλαξε στην έκδοση 3.3: Μια κενή πλειάδα (tuple) αντί για @code{None} όταν ndim = 0.

@end deffn

@geindex suboffsets (ιδιότητα της memoryview)
@anchor{library/stdtypes memoryview suboffsets}@anchor{2885}
@deffn {Ιδιότητα} suboffsets

Χρησιμοποιείται εσωτερικά για συστοιχίες τύπου PIL. Η τιμή είναι μόνο ενημερωτική.
@end deffn

@geindex c_contiguous (ιδιότητα της memoryview)
@anchor{library/stdtypes memoryview c_contiguous}@anchor{2886}
@deffn {Ιδιότητα} c_contiguous

Ένα bool που υποδεικνύει εάν η μνήμη είναι C-@ref{287e,,contiguous}.


Added in version 3.3.

@end deffn

@geindex f_contiguous (ιδιότητα της memoryview)
@anchor{library/stdtypes memoryview f_contiguous}@anchor{2887}
@deffn {Ιδιότητα} f_contiguous

Ένα bool που υποδεικνύει εάν η μνήμη είναι Fortran @ref{287e,,contiguous}.


Added in version 3.3.

@end deffn

@geindex contiguous (ιδιότητα της memoryview)
@anchor{library/stdtypes memoryview contiguous}@anchor{2888}
@deffn {Ιδιότητα} contiguous

Ένα bool που υποδεικνύει εάν η μνήμη είναι @ref{287e,,contiguous}.


Added in version 3.3.

@end deffn
@end deffn

For information on the thread safety of @ref{1d2,,memoryview} objects in
the @ref{198,,free-threaded build}, see @ref{2606,,Thread safety for memoryview objects}.

@node Τύποι Συνόλου Set — set frozenset,Mapping types — dict frozendict,Τύποι δυαδικής ακολουθίας — bytes bytearray memoryview,Τύποι Built-in
@anchor{library/stdtypes set-types-set-frozenset}@anchor{2889}@anchor{library/stdtypes types-set}@anchor{2220}
@subsection Τύποι Συνόλου (Set) — @code{set}, @code{frozenset}


@geindex αντικείμενο;set

Ένα αντικείμενο `set' είναι μια μη ταξινομημένη συλλογή από διακριτά αντικείμενα @ref{183,,hashable}. Οι συνήθεις χρήσεις περιλαμβάνουν τη δοκιμή ιδιότητας μέλους, την αφαίρεση διπλότυπων από μια ακολουθία και τον υπολογισμό μαθηματικών πράξεων όπως τομή, ένωση, διαφορά, και συμμετρική διαφορά. (Για άλλα containers, δείτε τις ενσωματωμένες κλάσεις @ref{188,,dict}, @ref{4d9,,list}, και @ref{1ce,,tuple} και το module @ref{1e,,collections}).

Όπως και άλλες συλλογές, τα σύνολα (sets) υποστηρίζουν @code{x in set}, @code{len(set)}, και @code{for x in set}.  Όντως μια μη ταξινομημένη συλλογή, τα σύνολα δεν καταγράφουν τη θέση του στοιχείου ή τη σειρά εισαγωγής.  Συνεπώς, τα σύνολα (sets) δεν υποστηρίζουν λειτουργίες ευρετηριοποίησης, τμηματοποίησης ή άλλη συμπεριφορά ακολουθίας.

There are currently two built-in set types, @ref{42b,,set} and @ref{9d4,,frozenset}.
The @code{set} type is mutable — the contents can be changed using methods
like @ref{252f,,add()} and @ref{288a,,remove()}.
Since it is mutable, it has no hash value and cannot be used as
either a dictionary key or as an element of another set.
The @code{frozenset} type is immutable and @ref{183,,hashable} —
its contents cannot be altered after it is created;
it can therefore be used as a dictionary key or as an element of another set.

Μπορούν να δημιουργηθούν μη κενά σύνολα (όχι παγωμένα σύνολα (frozensets)) τοποθετώντας μια λίστα στοιχείων διαχωρισμένων με κόμμα μέσα σε αγκύλες, για παράδειγμα: @code{@{'jack', 'sjoerd'@}}, επιπλέον με τη χρήση του constructor του @ref{42b,,set}.

Οι constructors και για τις δύο κλάσεις λειτουργούν το ίδιο:

@geindex set (ενσωματωμένη κλάση)
@geindex frozenset (ενσωματωμένη κλάση)
@anchor{library/stdtypes set}@anchor{42b}
@deffn {Κλάση} set (iterable=(), /)
@anchor{library/stdtypes frozenset}@anchor{9d4}
@deffnx {Κλάση} frozenset (iterable=(), /)

Επιστρέφει ένα νέο σύνολο (set) ή ένα παγωμένο σύνολο (frozenset) των οποίων τα στοιχεία έχουν ληφθεί από το `iterable'.  Τα στοιχεία ενός συνόλου πρέπει να είναι @ref{183,,hashable}.  Για να αναπαραστήσουν σύνολα συνόλων, τα εσωτερικά σύνολα πρέπει να είναι @ref{9d4,,frozenset} αντικείμενα.  Εάν δεν έχει καθοριστεί το `iterable', επιστρέφεται ένα νέο κενό σύνολο.
@end deffn

Τα σύνολα μπορούν να δημιουργηθούν με διάφορους τρόπους:


@itemize *

@item 
Χρησιμοποιώντας μια λίστα στοιχείων διαχωρισμένη με κόμματα: @code{@{'jack', 'sjoerd'@}}

@item 
Χρησιμοποιώντας ένα set comprehension: @code{@{c for c in 'abracadabra' if c not in 'abc'@}}

@item 
Χρησιμοποιώντας τον τύπο constructor: @code{set()}, @code{set('foobar')}, @code{set(['a', 'b', 'foo'])}
@end itemize

Τα στιγμιότυπα των @ref{42b,,set} και @ref{9d4,,frozenset} παρέχουν τις ακόλουθες λειτουργίες:


@deffn {Describe} len(s)

Επιστρέφει τον αριθμό των στοιχείων στο σύνολο `s' (πληθικότητα του `s').
@end deffn


@deffn {Describe} x in s

Ελέγχει αν το `x' είναι μέρος στο `s'.
@end deffn


@deffn {Describe} x not in s

Ελέγχει αν το `x' δεν είναι μέρος στο `s'.
@end deffn

@geindex isdisjoint() (μέθοδος της frozenset)
@geindex isdisjoint() (μέθοδος της set)
@anchor{library/stdtypes frozenset isdisjoint}@anchor{288b}
@deffn {Μέθοδος} frozenset.isdisjoint (other, /)
@anchor{library/stdtypes set isdisjoint}@anchor{288c}
@deffnx {Μέθοδος} set.isdisjoint (other, /)

Επιστρέφει @code{True} εάν το σύνολο δεν έχει κοινά στοιχεία με το `other'.  Τα σύνολα είναι ασύνδετα εάν και μόνο εάν η τομή τους είναι το κενό σύνολο.
@end deffn

@geindex issubset() (μέθοδος της frozenset)
@geindex issubset() (μέθοδος της set)
@anchor{library/stdtypes frozenset issubset}@anchor{288d}
@deffn {Μέθοδος} frozenset.issubset (other, /)
@anchor{library/stdtypes set issubset}@anchor{288e}
@deffnx {Μέθοδος} set.issubset (other, /)
@end deffn


@deffn {Describe} set <= other

Ελέγχει εάν κάθε στοιχείο στο σύνολο βρίσκεται στο `other'.
@end deffn


@deffn {Describe} set < other

Ελέγχει εάν το σύνολο είναι σωστό υποσύνολο του `other', δηλαδή, @code{set <= other and set != other}.
@end deffn

@geindex issuperset() (μέθοδος της frozenset)
@geindex issuperset() (μέθοδος της set)
@anchor{library/stdtypes frozenset issuperset}@anchor{288f}
@deffn {Μέθοδος} frozenset.issuperset (other, /)
@anchor{library/stdtypes set issuperset}@anchor{1d81}
@deffnx {Μέθοδος} set.issuperset (other, /)
@end deffn


@deffn {Describe} set >= other

Ελέγχει αν κάθε στοιχείο του `other' είναι στο σύνολο.
@end deffn


@deffn {Describe} set > other

Ελέγχει αν το σύνολο είναι σωστό υπερσύνολο του `other', δηλαδή, @code{set >= other and set != other}.
@end deffn

@geindex union() (μέθοδος της frozenset)
@geindex union() (μέθοδος της set)
@anchor{library/stdtypes frozenset union}@anchor{1825}
@deffn {Μέθοδος} frozenset.union (*others)
@anchor{library/stdtypes set union}@anchor{2890}
@deffnx {Μέθοδος} set.union (*others)
@end deffn


@deffn {Describe} set | other | ...

Επιστρέφει ένα νέο σύνολο με στοιχεία από το σύνολο και όλα τα άλλα.
@end deffn

@geindex intersection() (μέθοδος της frozenset)
@geindex intersection() (μέθοδος της set)
@anchor{library/stdtypes frozenset intersection}@anchor{1826}
@deffn {Μέθοδος} frozenset.intersection (*others)
@anchor{library/stdtypes set intersection}@anchor{1d80}
@deffnx {Μέθοδος} set.intersection (*others)
@end deffn


@deffn {Describe} set & other & ...

Επιστρέφει ένα νέο σύνολο με στοιχεία κοινά στο σύνολο και σε όλα τα άλλα.
@end deffn

@geindex difference() (μέθοδος της frozenset)
@geindex difference() (μέθοδος της set)
@anchor{library/stdtypes frozenset difference}@anchor{2891}
@deffn {Μέθοδος} frozenset.difference (*others)
@anchor{library/stdtypes set difference}@anchor{2892}
@deffnx {Μέθοδος} set.difference (*others)
@end deffn


@deffn {Describe} set @w{-} other @w{-} ...

Επιστρέφει ένα νέο σύνολο με στοιχεία στο σύνολο που δεν υπάρχουν στα άλλα.
@end deffn

@geindex symmetric_difference() (μέθοδος της frozenset)
@geindex symmetric_difference() (μέθοδος της set)
@anchor{library/stdtypes frozenset symmetric_difference}@anchor{2893}
@deffn {Μέθοδος} frozenset.symmetric_difference (other, /)
@anchor{library/stdtypes set symmetric_difference}@anchor{2894}
@deffnx {Μέθοδος} set.symmetric_difference (other, /)
@end deffn


@deffn {Describe} set ^ other

Επιστρέφει ένα νέο σύνολο με στοιχεία είτε στο σύνολο είτε στο `other' αλλά όχι και στα δύο.
@end deffn

@geindex copy() (μέθοδος της frozenset)
@geindex copy() (μέθοδος της set)
@anchor{library/stdtypes frozenset copy}@anchor{2895}
@deffn {Μέθοδος} frozenset.copy ()
@anchor{library/stdtypes set copy}@anchor{2896}
@deffnx {Μέθοδος} set.copy ()

Επιστρέφει ένα ρηχό αντίγραφο του συνόλου.
@end deffn

Note, the non-operator versions of @ref{1825,,union()},
@ref{1826,,intersection()}, @ref{2891,,difference()}, @ref{2893,,symmetric_difference()}, @ref{288d,,issubset()}, and
@ref{288f,,issuperset()} methods will accept any iterable as an argument.  In
contrast, their operator based counterparts require their arguments to be
sets.  This precludes error-prone constructions like @code{set('abc') & 'cbs'}
in favor of the more readable @code{set('abc').intersection('cbs')}.

Τόσο το @ref{42b,,set} και @ref{9d4,,frozenset} υποστηρίζουν τη σύγκριση μεταξύ συνόλων. Δύο σύνολα είναι ίσα εάν και μόνο εάν κάθε στοιχείο κάθε συνόλου περιέχεται στο άλλο (το καθένα είναι υποσύνολο του άλλου). Ένα σύνολο είναι μικρότερο από ένα άλλο σύνολο εάν και μόνο αν το πρώτο σύνολο είναι σωστό υποσύνολο του δεύτερου συνόλου (είναι υποσύνολο, αλλά δεν είναι ίσο), ένα σύνολο είναι μεγαλύτερο από ένα άλλο σύνολο, αν και μόνο αν το πρώτο σύνολο είναι σωστό υπερσύνολο του δεύτερου συνόλου (είναι υπερσύνολο αλλά δεν είναι ίσο).

Τα στιγμιότυπα της @ref{42b,,set} συγκρίνονται με τα στιγμιότυπα της @ref{9d4,,frozenset} με βάση τα μέλη τους.  Για παράδειγμα, το @code{set('abc') == frozenset('abc')} επιστρέφει @code{True} και το ίδιο συμβαίνει και με το @code{set('abc') in set([frozenset('abc')])}.

Οι συγκρίσεις υποσυνόλου και ισότητας δεν γενικεύονται σε μια συνάρτηση ολικής ταξινόμησης.  Για παράδειγμα, οποιαδήποτε δύο μη κενά συνεχή σύνολα δεν είναι ίσα και δεν είναι υποσύνολα το ένα του άλλου, επομένως `όλα' τα ακόλουθα επιστρέφουν @code{False}: @code{a<b}, @code{a==b}, or @code{a>b}.

Δεδομένου ότι τα σύνολα ορίζουν μόνο μερική σειρά (σχέσεις υποσυνόλων), η έξοδος της μεθόδου @ref{f8d,,list.sort()} δεν έχει οριστεί για λίστες συνόλων.

Τα στοιχεία συνόλου, όπως τα κλειδιά λεξικού, πρέπει να είναι @ref{183,,hashable}.

Δυαδικές πράξεις που συνδυάζουν στιγμιότυπα @ref{42b,,set} με @ref{9d4,,frozenset} επιστρέφουν τον τύπο του πρώτου τελεστή.  Για παράδειγμα: @code{frozenset('ab') | set('bc')} επιστρέφει ένα στιγμιότυπο του @code{frozenset}.

Ο παρακάτω πίνακας παραθέτει λειτουργίες που είναι διαθέσιμες για @ref{42b,,set} που δεν ισχύουν για αμετάβλητα στιγμιότυπα της @ref{9d4,,frozenset}:

@geindex update() (μέθοδος της set)
@anchor{library/stdtypes set update}@anchor{2897}
@deffn {Μέθοδος} set.update (*others)
@end deffn


@deffn {Describe} set |= other | ...

Ενημερώνει το σύνολο (set), προσθέτοντας στοιχεία από όλα τα άλλα.
@end deffn

@geindex intersection_update() (μέθοδος της set)
@anchor{library/stdtypes set intersection_update}@anchor{1827}
@deffn {Μέθοδος} set.intersection_update (*others)
@end deffn


@deffn {Describe} set &= other & ...

Ενημερώνει το σύνολο, διατηρώντας μόνο τα στοιχεία που βρίσκονται σε αυτό και όλα τα άλλα.
@end deffn

@geindex difference_update() (μέθοδος της set)
@anchor{library/stdtypes set difference_update}@anchor{2898}
@deffn {Μέθοδος} set.difference_update (*others)
@end deffn


@deffn {Describe} set @w{-}= other | ...

Ενημερώνει το σύνολο, αφαιρώντας στοιχεία που βρίσκονται σε άλλα.
@end deffn

@geindex symmetric_difference_update() (μέθοδος της set)
@anchor{library/stdtypes set symmetric_difference_update}@anchor{1828}
@deffn {Μέθοδος} set.symmetric_difference_update (other, /)
@end deffn


@deffn {Describe} set ^= other

Ενημερώνει το σύνολο, διατηρώντας μόνο τα στοιχεία που βρίσκονται σε κάθε σύνολο, αλλά όχι και στα δύο.
@end deffn

@geindex add() (μέθοδος της set)
@anchor{library/stdtypes set add}@anchor{252f}
@deffn {Μέθοδος} set.add (elem, /)

Προσθέτει το στοιχείο `elem' στο σύνολο.
@end deffn

@geindex remove() (μέθοδος της set)
@anchor{library/stdtypes set remove}@anchor{288a}
@deffn {Μέθοδος} set.remove (elem, /)

Αφαιρεί το στοιχείο `elem' από το σύνολο.  Κάνει raise τη @ref{7df,,KeyError} εάν το `elem' δεν περιέχεται στο σύνολο.
@end deffn

@geindex discard() (μέθοδος της set)
@anchor{library/stdtypes set discard}@anchor{2899}
@deffn {Μέθοδος} set.discard (elem, /)

Αφαιρεί το στοιχείο `elem' από το σύνολο εάν υπάρχει.
@end deffn

@geindex pop() (μέθοδος της set)
@anchor{library/stdtypes set pop}@anchor{289a}
@deffn {Μέθοδος} set.pop ()

Αφαιρεί και επιστρέφει ένα αυθαίρετο στοιχείο από το σύνολο.  Κάνει raise μια @ref{7df,,KeyError} εάν το σύνολο είναι κενό.
@end deffn

@geindex clear() (μέθοδος της set)
@anchor{library/stdtypes set clear}@anchor{289b}
@deffn {Μέθοδος} set.clear ()

Αφαιρεί όλα τα στοιχεία από το σύνολο (set).
@end deffn

Note, the non-operator versions of the @ref{2897,,update()},
@ref{1827,,intersection_update()}, @ref{2898,,difference_update()}, and
@ref{1828,,symmetric_difference_update()} methods will accept any iterable as an
argument.

Note, the `elem' argument to the @ref{175c,,__contains__()},
@ref{288a,,remove()}, and
@ref{2899,,discard()} methods may be a set.  To support searching for an equivalent
frozenset, a temporary one is created from `elem'.


@subsubheading Δείτε επίσης


For detailed information on thread-safety guarantees for @ref{42b,,set}
objects, see @ref{289c,,Thread safety for set objects}.


@node Mapping types — dict frozendict,Τύποι Διαχείρισης Περιεχομένου,Τύποι Συνόλου Set — set frozenset,Τύποι Built-in
@anchor{library/stdtypes mapping-types-dict-frozendict}@anchor{289d}@anchor{library/stdtypes typesmapping}@anchor{e8c}
@subsection Mapping types — @code{dict}, @code{frozendict}


@geindex αντικείμενο;αντιστοίχιση
@geindex αντικείμενο;λεξικό
@geindex λειτουργίες on;αντιστοίχιση;τύποι
@geindex λειτουργίες on;λεξικό;τύπος
@geindex statement;del
@geindex ενσωματωμένες (built-in) συναρτήσεις;len

A @ref{1564,,mapping} object maps @ref{183,,hashable} values to arbitrary objects.
There are currently two standard mapping types, the `dictionary' and
@ref{182,,frozendict}.
(For other containers see the built-in
@ref{4d9,,list}, @ref{42b,,set}, and @ref{1ce,,tuple} classes, and the
@ref{1e,,collections} module.)

Τα κλειδιά ενός λεξικού είναι `σχεδόν' αυθαίρετες τιμές.  Οι τιμές που δεν είναι @ref{183,,hashable}, δηλαδή, τιμές που περιέχουν λίστες, λεξικά ή άλλους μεταβλητούς τύπους (που συγκρίνονται βάσει τιμής και όχι βάσει ταυτότητας αντικειμένου) δεν μπορούν να χρησιμοποιηθούν ως κλειδιά. Οι τιμές που συγκρίνονται ίσες (όπως @code{1}, @code{1.0}, και @code{True}) μπορούν να χρησιμοποιηθούν εναλλακτικά για το index της ίδιας καταχώρισης λεξικού.

@geindex dict (ενσωματωμένη κλάση)
@anchor{library/stdtypes dict}@anchor{188}
@deffn {Κλάση} dict (**kwargs)

@deffnx {Κλάση} dict (mapping, /, **kwargs)

@deffnx {Κλάση} dict (iterable, /, **kwargs)

Επιστρέφει ένα νέο λεξικό που έχει αρχικοποιηθεί από ένα προαιρετικό όρισμα θέσης και ένα πιθανό κενό σύνολο ορισμάτων λέξεων-κλειδιών.

Τα λεξικά μπορούν να δημιουργηθούν με διάφορους τρόπους:


@itemize *

@item 
Χρησιμοποιήστε μια λίστα διαχωρισμένων με κόμματα ζευγών @code{key: value} μέσα σε αγκύλες: @code{@{'jack': 4098, 'sjoerd': 4127@}} or @code{@{4098: 'jack', 4127: 'sjoerd'@}}

@item 
Χρησιμοποιήστε ένα comprehension λεξικού: @code{@{@}}, @code{@{x: x ** 2 for x in range(10)@}}

@item 
Χρησιμοποιήστε τον κατασκευαστή τύπου: @code{dict()}, @code{dict([('foo', 100), ('bar', 200)])}, @code{dict(foo=100, bar=200)}
@end itemize

Εάν δεν δοθεί όρισμα θέσης, δημιουργείται ένα κενό λεξικό. Εάν δοθεί ένα όρισμα θέσης και ορίζει μια μέθοδο @code{keys()}, δημιουργείται ένα λεξικό καλώντας το @ref{787,,__getitem__()} στο όρισμα με κάθε κλειδί που επιστρέφεται από τη μέθοδο. Διαφορετικά, το όρισμα θέσης πρέπει να είναι ένα αντικείμενο @ref{15ce,,iterable}. Κάθε στοιχείο στο iterable πρέπει από μόνο του να είναι ένας iterable με ακριβώς δύο στοιχεία. Το πρώτο στοιχείο κάθε στοιχείου γίνεται κλειδί στο νέο λεξικό και το δεύτερο στοιχείο η αντίστοιχη τιμή. Εάν ένα κλειδί εμφανίζεται περισσότερες από μία φορές, η τελευταία τιμή για αυτό το κλειδί γίνεται η αντίστοιχη τιμή στο νέο λεξικό.

Εάν δίνονται ορίσματα λέξης-κλειδιού, τα ορίσματα λέξης-κλειδιού και οι τιμές τους προστίθενται στο λεξικό που δημιουργήθηκε από το όρισμα θέσης.  Εάν υπάρχει ήδη ένα κλειδί που προστίθεται, η τιμή από το όρισμα λέξης-κλειδιού αντικαθιστά την τιμή από το όρισμα θέσης.

Τα λεξικά συγκρίνονται ως ίσα εάν και μόνο εάν έχουν τα ίδια ζεύγη @code{(key, value)} (ανεξάρτητα από τη σειρά). Οι συγκρίσεις διάταξης (“<”, “<=”, “>=”, “>”) κάνουν raise την @ref{291,,TypeError}.  Για να επεξηγηθεί η δημιουργία λεξικού και η ισότητα, τα ακόλουθα παραδείγματα επιστρέφουν όλα ένα λεξικό ίσο με @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

Η παροχή ορισμάτων λέξεων-κλειδιών όπως στο πρώτο παράδειγμα λειτουργεί μόνο για κλειδιά που είναι έγκυρα αναγνωριστικά Python.  Διαφορετικά, μπορούν να χρησιμοποιηθούν οποιαδήποτε έγκυρα κλειδιά.

Τα λεξικά διατηρούν τη σειρά εισαγωγής.  Σημειώστε ότι η ενημέρωση ενός κλειδιού δεν επηρεάζει τη σειρά.  Τα κλειδιά που προστέθηκαν μετά τη διαγραφή εισάγονται στο τέλος.

@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


Άλλαξε στην έκδοση 3.7: Η σειρά λεξικού είναι εγγυημένη ότι είναι η σειρά εισαγωγής.  Αυτή η συμπεριφορά ήταν μια λεπτομέρεια υλοποίηση της CPython από την έκδοση 3.6.


Αυτές είναι οι λειτουργίες που υποστηρίζουν τα λεξικά (και επομένως, θα πρέπει να υποστηρίζουν και προσαρμοσμένους τύπους αντιστοίχισης επίσης):


@deffn {Describe} list(d)

Επιστρέφει μια λίστα με όλα τα κλειδιά που χρησιμοποιούνται στο λεξικό `d'.
@end deffn


@deffn {Describe} len(d)

Επιστρέφει τον αριθμό των στοιχείων στο λεξικό `d'.
@end deffn


@deffn {Describe} d[key]

Επιστρέφει το στοιχείο του `d' με το κλειδί `key'.  Κάνει raise μια @ref{7df,,KeyError} εάν το `key' δεν υπάρχει για να αντιστοιχηθεί.

@geindex __missing__()

Εάν μια υποκλάση ενός λεξικού ορίζει μια μέθοδο @ref{1566,,__missing__()} και το `key' δεν υπάρχει, η λειτουργία @code{d[key]} καλεί αυτήν την μέθοδο με το κλειδί `key' ως όρισμα. Στη συνέχεια, η λειτουργία @code{d[key]} επιστρέφει ή κάνει raise ό, τι επιστρέφεται ή γίνεται raise από την κλήση @code{__missing__(key)}. Καμία άλλη λειτουργία ή μέθοδος δεν επικαλεί την @code{__missing__()}. Εάν το @code{__missing__()} δεν έχει οριστεί, γίνεται raise @ref{7df,,KeyError}. To @code{__missing__()} πρέπει να είναι μέθοδος∙ δεν μπορεί να είναι ένα στιγμιότυπο μεταβλητής:

@example
>>> class Counter(dict):
...     def __missing__(self, key):
...         return 0
...
>>> c = Counter()
>>> c['red']
0
>>> c['red'] += 1
>>> c['red']
1
@end example

Το παραπάνω παράδειγμα δείχνει μέρος της υλοποίησης του @ref{204,,collections.Counter}.  Μια διαφορετική μέθοδος @code{__missing__()} χρησιμοποιείται από την @ref{1565,,collections.defaultdict}.
@end deffn


@deffn {Describe} d[key] = value

Ορίζει το @code{d[key]} στο `value'.
@end deffn


@deffn {Describe} del d[key]

Αφαιρεί το @code{d[key]} από το `d'.  Κάνει raise ένα @ref{7df,,KeyError} εάν το `key' δεν υπάρχει για αντιστοίχιση.
@end deffn


@deffn {Describe} key in d

Επιστρέφει @code{True} εάν το `d' έχει ένα κλειδί `key', διαφορετικά @code{False}.
@end deffn


@deffn {Describe} key not in d

Ισοδυναμεί με @code{not key in d}.
@end deffn


@deffn {Describe} iter(d)

Επιστρέφει έναν iterator πάνω από τα κλειδιά του λεξικού.  Αυτή είναι μια συντόμευση για @code{iter(d.keys())}.
@end deffn

@geindex clear() (μέθοδος της dict)
@anchor{library/stdtypes dict clear}@anchor{1954}
@deffn {Μέθοδος} clear ()

Αφαιρεί όλα τα στοιχεία από το λεξικό.
@end deffn

@geindex copy() (μέθοδος της dict)
@anchor{library/stdtypes dict copy}@anchor{f8e}
@deffn {Μέθοδος} copy ()

Επιστρέφει ένα ρηχό αντίγραφο του λεξικού.
@end deffn

@geindex fromkeys() (μέθοδος κλάσης της dict)
@anchor{library/stdtypes dict fromkeys}@anchor{4da}
@deffn {Μέθοδος} classmethod fromkeys (iterable, value=None, /)

Δημιουργεί ένα νέο λεξικό με κλειδιά από το `iterable' και τιμές ως `value'.

Το @ref{4da,,fromkeys()} είναι μια μέθοδος κλάσης που επιστρέφει ένα νέο λεξικό. Η τιμή `value' ορίζεται από προεπιλογή σε @code{None}.  Όλες οι τιμές αναφέρονται σε ένα μόνο στιγμιότυπο, επομένως γενικά δεν έχει νόημα για το `value' να είναι μεταβλητό αντικείμενο, όπως μια κενή λίστα.  Για να λάβετε διαφορετικές τιμές, χρησιμοποιήστε αντ” αυτού ένα @ref{1138,,dict comprehension}.
@end deffn

@geindex get() (μέθοδος της dict)
@anchor{library/stdtypes dict get}@anchor{2223}
@deffn {Μέθοδος} get (key, default=None, /)

Επιστρέφει την τιμή για το `key' εάν το `key' είναι στο λεξικό, αλλιώς `default'. Εάν το `default' δεν δίνεται, ορίζεται από προεπιλογή σε @code{None}, έτσι ώστε αυτή η μέθοδος να μην κάνει raise μια @ref{7df,,KeyError}.
@end deffn

@geindex items() (μέθοδος της dict)
@anchor{library/stdtypes dict items}@anchor{baf}
@deffn {Μέθοδος} items ()

Επιστρέφει μια νέα όψη των στοιχείων του λεξικού (@code{(key, value)} ζεύγη). Δείτε την @ref{289e,,documentation of view objects}.
@end deffn

@geindex keys() (μέθοδος της dict)
@anchor{library/stdtypes dict keys}@anchor{bad}
@deffn {Μέθοδος} keys ()

Επιστρέφει μια νέα όψη των κλειδιών του λεξικού.  Δείτε το @ref{289e,,documentation of view objects}.
@end deffn

@geindex pop() (μέθοδος της dict)
@anchor{library/stdtypes dict pop}@anchor{7de}
@deffn {Μέθοδος} pop (key, /)

@deffnx {Μέθοδος} pop (key, default, /)

Εάν το `key' βρίσκεται στο λεξικό, αφαιρείται και επιστρέφει την τιμή του, διαφορετικά επιστρέφει `default'.  Εάν `default' δεν δίνεται και το `key' δεν είναι στο λεξικό, γίνεται raise ένα @ref{7df,,KeyError}.
@end deffn

@geindex popitem() (μέθοδος της dict)
@anchor{library/stdtypes dict popitem}@anchor{18c8}
@deffn {Μέθοδος} popitem ()

Αφαιρεί και επιστρέφει ένα ζεύγος @code{(key, value)} από το λεξικό. Τα ζεύγη επιστρέφονται με τη σειρά @abbr{LIFO,last-in@comma{} first-out}.

Η μέθοδος @ref{18c8,,popitem()} είναι χρήσιμη για καταστροφική επανάληψη σε ένα λεξικό, όπως χρησιμοποιείται συχνά σε αλγόριθμους συνόλου.  Εάν το λεξικό είναι κενό, η κλήση της @code{popitem()} κάνει raise ένα @ref{7df,,KeyError}.


Άλλαξε στην έκδοση 3.7: Η σειρά LIFO είναι πλέον εγγυημένη. Σε προηγούμενες εκδόσεις, η @ref{18c8,,popitem()} επιστρέφει ένα αυθαίρετο ζεύγος κλειδιού/τιμής.

@end deffn


@deffn {Describe} reversed(d)

Επιστρέφει έναν αντίστροφο iterator πάνω από τα κλειδιά του λεξικού. Αυτή είναι μια συντόμευση για @code{reversed(d.keys())}.


Added in version 3.8.

@end deffn

@geindex setdefault() (μέθοδος της dict)
@anchor{library/stdtypes dict setdefault}@anchor{1421}
@deffn {Μέθοδος} setdefault (key, default=None, /)

Εάν το `key' βρίσκεται στο λεξικό, επιστρέφει την τιμή του.  Εάν όχι, εισάγετε το `key' με τιμή `default' και επιστρέφει `default'.  Το `default' από προεπιλογή είναι @code{None}.
@end deffn

@geindex update() (μέθοδος της dict)
@anchor{library/stdtypes dict update}@anchor{1807}
@deffn {Μέθοδος} update (**kwargs)

@deffnx {Μέθοδος} update (mapping, /, **kwargs)

@deffnx {Μέθοδος} update (iterable, /, **kwargs)

Ενημερώνει το λεξικό με τα ζεύγη κλειδιών/τιμών από το `mapping' ή `iterable' και `kwargs', αντικαθιστώντας τα υπάρχοντα κλειδιά.  Επιστρέφει @code{None}.

Η @ref{1807,,update()} δέχεται είτε ένα άλλο αντικείμενο με τη μέθοδο @code{keys()} (στην περίπτωση αυτή το @ref{787,,__getitem__()} καλείται με κάθε κλειδί που επιστρέφεται από τη μέθοδο) είτε ένα iterable από ζεύγη κλειδιών/τιμών (ως πλειάδες ή άλλα iterables μήκους δύο). Εάν καθορίζονται ορίσματα λέξεων-κλειδιών, το λεξικό ενημερώνεται στη συνέχεια με αυτά τα ζεύγη κλειδιών/τιμών: @code{d.update(red=1, blue=2)}.
@end deffn

@geindex values() (μέθοδος της dict)
@anchor{library/stdtypes dict values}@anchor{bae}
@deffn {Μέθοδος} values ()

Επιστρέφει μια νέα όψη των τιμών του λεξικού.  Δείτε την @ref{289e,,documentation of view objects}.

Μια σύγκριση ισότητας μεταξύ μιας όψης @code{dict.values()} και μιας άλλης θα επιστρέφει πάντα @code{False}. Αυτό ισχύει επίσης όταν συγκρίνετε το @code{dict.values()} με τον εαυτό της:

@example
>>> d = @{'a': 1@}
>>> d.values() == d.values()
False
@end example
@end deffn


@deffn {Describe} d | other

Δημιουργεί ένα νέο λεξικό με τα συγχωνευμένα κλειδιά και τις τιμές των `d' και `other', τα οποία πρέπει να είναι και τα δύο λεξικά. Οι τιμές του `other' έχουν προτεραιότητα όταν τα κλειδιά των `d' και `other' είναι κοινά.


Added in version 3.9.

@end deffn


@deffn {Describe} d |= other

Ενημερώνει το λεξικό `d' με κλειδιά και τιμές από το `other', που μπορεί να είναι είτε @ref{1564,,mapping} είτε @ref{15ce,,iterable} ζευγάρι κλειδιών/τιμών. Οι τιμές του `other' έχουν προτεραιότητα όταν τα κλειδιά των το `d' και `other' είναι κοινά.


Added in version 3.9.

@end deffn

Τα λεξικά και οι όψεις λεξικών είναι αναστρέψιμες.

@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


Άλλαξε στην έκδοση 3.8: Τα λεξικά είναι πλέον αναστρέψιμα.



@subsubheading Δείτε επίσης


@ref{182,,frozendict} and @ref{189,,types.MappingProxyType} can be used to
create a read-only view of a @code{dict}.

@end deffn


@subsubheading Δείτε επίσης


For detailed information on thread-safety guarantees for @ref{188,,dict}
objects, see @ref{289f,,Thread safety for dict objects}.


@menu
* Αντικείμενα όψης λεξικού:: 
* Frozen dictionaries:: 

@end menu

@node Αντικείμενα όψης λεξικού,Frozen dictionaries,,Mapping types — dict frozendict
@anchor{library/stdtypes dict-views}@anchor{289e}@anchor{library/stdtypes dictionary-view-objects}@anchor{28a0}
@subsubsection Αντικείμενα όψης λεξικού


Τα αντικείμενα που επιστρέφονται από τις @ref{bad,,dict.keys()}, @ref{bae,,dict.values()} and @ref{baf,,dict.items()} είναι `όψεις αντικειμένων (view objects)'.  Παρέχουν μια δυναμική όψη στις εγγραφές του λεξικού, που σημαίνει ότι όταν αλλάζει το λεξικό, η όψη αντικατοπτρίζει αυτές τις αλλαγές.

Οι όψεις λεξικού μπορούν να γίνουν iterate για την απόδοση των αντίστοιχων δεδομένων τους και την υποστήριξη ελέγχων για το αν είναι μέρος του:


@deffn {Describe} len(dictview)

Επιστρέφει τον αριθμό των καταχωρήσεων στο λεξικό.
@end deffn


@deffn {Describe} iter(dictview)

Επιστρέφει έναν iterator πάνω στα κλειδιά, τις τιμές ή τα στοιχεία (που αντιπροσωπεύονται ως πλειάδες (tuples) του @code{(key, value)} στο λεξικό.

Τα κλειδιά και οι τιμές επαναλαμβάνονται με την σειρά εισαγωγής. Αυτό επιτρέπει τη δημιουργία ζευγών @code{(value, key)} χρησιμοποιώντας τη @ref{43f,,zip()}: @code{pairs = zip(d.values(), d.keys())}.  Ένας άλλος τρόπος είναι να δημιουργήσετε την ίδια λίστα είναι @code{pairs = [(v, k) for (k, v) in d.items()]}.

Το iterate όψεων κατά την προσθήκη ή τη διαγραφή καταχωρήσεων στο λεξικό μπορεί να κάνει raise μια @ref{30d,,RuntimeError} ή να αποτύχει το iterate σε όλες τις καταχωρήσεις.


Άλλαξε στην έκδοση 3.7: Η σειρά λεξικού είναι εγγυημένη σειρά εισαγωγής.

@end deffn


@deffn {Describe} x in dictview

Επιστρέφει @code{True} εάν το `x' βρίσκεται στα κλειδιά του λεξικού, τις τιμές ή τα στοιχεία του υποκείμενου λεξικού (στην τελευταία περίπτωση, το `x' θα πρέπει να είναι μια @code{(key, value)} πλειάδα (tuple)).
@end deffn


@deffn {Describe} reversed(dictview)

Επιστρέφει έναν αντίστροφο iterator πάνω στα κλειδιά, τις τιμές ή τα στοιχεία του λεξικού. Η όψη θα γίνει iterate με την αντίστροφη σειρά από την εισαγωγή.


Άλλαξε στην έκδοση 3.8: Οι όψεις λεξικού είναι πλέον αναστρέψιμες.

@end deffn


@deffn {Describe} dictview.mapping

Επιστρέφει μια @ref{189,,types.MappingProxyType} που αναδιπλώνει το αρχικό λεξικό στο οποίο αναφέρεται η όψη.


Added in version 3.10.

@end deffn

Οι όψεις κλειδιών μοιάζουν με σύνολο καθώς οι καταχωρίσεις τους είναι μοναδικές και @ref{183,,hashable}. Οι όψεις στοιχείων έχουν επίσης λειτουργίες που μοιάζουν με σύνολο, καθώς τα ζεύγη (κλειδί, τιμή) είναι μοναδικά και τα κλειδιά μπορούν να κατακερματιστούν. Εάν όλες οι τιμές σε μία όψη στοιχείων μπορούν επίσης να κατακερματιστούν, τότε η όψη στοιχείων μπορεί να διαλειτουργήσει με άλλα σύνολα. (Οι όψεις  τιμών δεν αντιμετωπίζονται ως σύνολο, καθώς οι καταχωρίσεις δεν είναι γενικά μοναδικές.)  Για όψεις που μοιάζουν με σύνολο, όλες οι λειτουργίες που ορίζονται για την αφηρημένη βασική κλάση @ref{28a1,,collections.abc.Set} είναι διαθέσιμες (για παράδειγμα, @code{==}, @code{<}, ή @code{^}).  Κατά τη χρήση τελεστών συνόλου, οι όψεις που μοιάζουν με σύνολο δέχονται οποιοδήποτε iterable ως άλλο τελεστή, σε αντίθεση με τα σύνολα που δέχονται μόνο σύνολα ως είσοδο.

Ένα παράδειγμα χρήσης όψης λεξικού:

@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 Frozen dictionaries,,Αντικείμενα όψης λεξικού,Mapping types — dict frozendict
@anchor{library/stdtypes frozen-dictionaries}@anchor{28a2}
@subsubsection Frozen dictionaries


@geindex frozendict (ενσωματωμένη κλάση)
@anchor{library/stdtypes frozendict}@anchor{182}
@deffn {Κλάση} frozendict (**kwargs)

@deffnx {Κλάση} frozendict (mapping, /, **kwargs)

@deffnx {Κλάση} frozendict (iterable, /, **kwargs)

Return a new frozen dictionary initialized from an optional positional
argument and a possibly empty set of keyword arguments.

A @code{frozendict} has a similar API to the @ref{188,,dict} API, with the
following differences:


@itemize *

@item 
@code{dict} has more methods than @code{frozendict}:

@quotation


@itemize *

@item 
@code{__delitem__()}

@item 
@code{__setitem__()}

@item 
@ref{1954,,clear()}

@item 
@ref{7de,,pop()}

@item 
@ref{18c8,,popitem()}

@item 
@ref{1421,,setdefault()}

@item 
@ref{1807,,update()}
@end itemize
@end quotation

@item 
A @code{frozendict} can be hashed with @code{hash(frozendict)} if all keys and
values can be hashed.

@item 
@code{frozendict |= other} does not modify the @code{frozendict} in-place but
creates a new frozen dictionary.
@end itemize

@code{frozendict} is not a @code{dict} subclass but inherits directly
from @code{object}.


Added in version 3.15.

@end deffn

@node Τύποι Διαχείρισης Περιεχομένου,Τύποι Annotation τύπου — Generic Alias Union,Mapping types — dict frozendict,Τύποι Built-in
@anchor{library/stdtypes context-manager-types}@anchor{28a3}@anchor{library/stdtypes typecontextmanager}@anchor{2601}
@subsection Τύποι Διαχείρισης Περιεχομένου


@geindex διαχειριστής περιεχομένου
@geindex πρωτόκολλο διαχειριστή περιεχομένου
@geindex πρωτόκολλο;διαχείριση περιεχομένου

Η δήλωση @ref{20a,,with} της Python υποστηρίζει την έννοια ενός περιεχομένου χρόνου εκτέλεσης που ορίζεται από έναν διαχειριστή περιεχομένου.  Αυτό υλοποιείται χρησιμοποιώντας ένα ζεύγος μεθόδων που επιτρέπουν σε κλάσεις που ορίζονται από το χρήστη να ορίζουν περιεχόμενο χρόνου εκτέλεσης που εισάγεται πριν από την εκτέλεση του σώματος της δήλωσης και να κάνει έξοδο όταν τερματιστεί η δήλωση:

@geindex __enter__() (μέθοδος της contextmanager)
@anchor{library/stdtypes contextmanager __enter__}@anchor{28a4}
@deffn {Μέθοδος} contextmanager.__enter__ ()

Εισάγει το περιεχόμενο εκτέλεσης και επιστρέφει είτε αυτό το αντικείμενο είτε ένα άλλο που σχετίζεται με το περιεχόμενο χρόνου εκτέλεσης. Η τιμή που επιστρέφεται από αυτήν την μέθοδο είναι δεσμευμένη στο αναγνωριστικό στην πρόταση @code{as} των δηλώσεων @ref{20a,,with} διαχείρισης περιεχομένου.

Ένα παράδειγμα ενός διαχειριστή περιεχομένου που επιστρέφει ο ίδιος είναι ένα @ref{156c,,file object}. Τα αντικείμενα αρχείου επιστρέφουν μόνα τους από __enter__() για να επιτρέψουν στο @ref{32b,,open()} να χρησιμοποιηθεί ως έκφραση περιεχομένου σε μια δήλωση @ref{20a,,with}.

Ένα παράδειγμα διαχείρισης περιεχομένου που επιστρέφει ένα σχετικό αντικείμενο είναι αυτό που επιστρέφεται από το @ref{172b,,decimal.localcontext()}. Αυτοί οι διαχειριστές ορίζουν το ενεργό δεκαδικό περιεχόμενο σε ένα αντίγραφο του αρχικού δεκαδικού περιεχομένου και στη συνέχεια επιστρέφουν το αντίγραφο. Αυτό επιτρέπει την πραγματοποίηση αλλαγών στο τρέχον δεκαδικό πλαίσιο στο σώμα της δήλωσης @ref{20a,,with}, χωρίς να επηρεάζεται ο κώδικας εκτός της δήλωσης @code{with}.
@end deffn

@geindex __exit__() (μέθοδος της contextmanager)
@anchor{library/stdtypes contextmanager __exit__}@anchor{28a5}
@deffn {Μέθοδος} contextmanager.__exit__ (exc_type, exc_val, exc_tb)

Τερματίζει από το περιεχόμενο χρόνου εκτέλεσης και επιστρέφει ένα Boolean δείκτη που υποδεικνύει εάν κάποια εξαίρεση που προέκυψε θα πρέπει να καταργηθεί. Εάν προκύψει μια εξαίρεση κατά την εκτέλεση του σώματος της δήλωσης @ref{20a,,with}, τα ορίσματα περιέχουν τον τύπο εξαίρεσης, την τιμή και τις πληροφορίες ανίχνευσης. Διαφορετικά, και τα τρία ορίσματα είναι @code{None}.

Returning a true value from this method will cause the @ref{20a,,with} statement
to suppress the exception and continue execution with the statement immediately
following the @code{with} statement. Otherwise the exception continues
propagating after this method has finished executing.

If this method raises an exception while handling an earlier exception from the
@ref{20a,,with} block, the new exception is raised, and the original exception
is stored in its @ref{166c,,__context__} attribute.

Η εξαίρεση που διαβιβάστηκε δεν θα πρέπει ποτέ να επανατοποθετηθεί ρητά - αντίθετα, αυτή η μέθοδος θα πρέπει να επιστρέψει μια ψευδή τιμή για να υποδείξει ότι η μέθοδος ολοκληρώθηκε με επιτυχία και δεν θέλει να αποκρύψει την εξαίρεση που έχει γίνει raise. Αυτό επιτρέπει στον κώδικα διαχείρισης περιεχομένου να εντοπίζει εύκολα εάν μια μέθοδος @ref{16a5,,__exit__()} έχει  πράγματι αποτύχει.
@end deffn

Η Python ορίζει  αρκετούς διαχειριστές περιεχομένου για να υποστηρίζουν τον εύκολο συγχρονισμό νημάτων, το  άμεσο κλείσιμο αρχείων ή άλλων αντικειμένων και τον απλούστερο χειρισμό του ενεργού δεκαδικού αριθμητικού περιεχομένου. Οι συγκεκριμένοι τύποι δεν αντιμετωπίζονται ειδικά πέρα από την εφαρμογή τους πρωτοκόλλου διαχείρισης περιεχομένου. Δείτε το module @ref{27,,contextlib} για μερικά παραδείγματα.

Οι decorators της Python @ref{1409,,generator}s και @ref{20e,,contextlib.contextmanager} παρέχουν έναν βολικό τρόπο υλοποίησης αυτών των πρωτοκόλλων.  Εάν μια συνάρτηση γεννήτριας είναι decorated με τον @code{contextlib.contextmanager} decorator, θα επιστρέψει έναν διαχειριστή περιεχομένου που εφαρμόζει τις απαραίτητες μεθόδους @ref{28a4,,__enter__()} και @ref{28a5,,__exit__()}, αντί του iterator που παράγεται από μια undecorated συνάρτηση γεννήτριας.

Λάβετε υπόψη ότι δεν υπάρχει συγκεκριμένη υποδοχή για καμία από αυτές τις μεθόδους στη δομή τύπου για αντικείμενα Python στο Python/C API. Οι τύποι επεκτάσεων που θέλουν να ορίσουν αυτές τις μεθόδους πρέπει να τις παρέχουν ως μια κανονική μέθοδο προσβάσιμη στην Python. Σε σύγκριση με την επιβάρυνση της ρύθμισης στο πλαίσιο του χρόνου εκτέλεσης, η επιβάρυνση μιας απλής αναζήτησης κλάσης λεξικού είναι αμελητέα.

@node Τύποι Annotation τύπου — Generic Alias Union,Άλλοι Ενσωματωμένοι built-in Τύποι,Τύποι Διαχείρισης Περιεχομένου,Τύποι Built-in
@anchor{library/stdtypes type-annotation-types-generic-alias-union}@anchor{28a6}
@subsection Τύποι Annotation τύπου — Generic Alias, Union


@geindex annotation;type annotation; type hint

Οι βασικοί ενσωματωμένοι τύποι για @ref{409,,type annotations} είναι @ref{a9f,,Generic Alias} και @ref{ba2,,Union}.

@menu
* Τύπος Generic Alias:: 
* Τύπος Ένωσης:: 

@end menu

@node Τύπος Generic Alias,Τύπος Ένωσης,,Τύποι Annotation τύπου — Generic Alias Union
@anchor{library/stdtypes generic-alias-type}@anchor{28a7}@anchor{library/stdtypes types-genericalias}@anchor{a9f}
@subsubsection Τύπος Generic Alias


@geindex αντικείμενο;GenericAlias
@geindex Generic;Alias

Τα αντικείμενα @code{GenericAlias} δημιουργούνται γενικά με @ref{2599,,subscripting} κλάση. Χρησιμοποιούνται πιο συχνά με @ref{25c9,,container classes}, όπως @ref{4d9,,list} ή @ref{188,,dict}.Για παράδειγμα, το @code{list[int]} είναι ένα αντικείμενο @code{GenericAlias} που δημιουργήθηκε με την εγγραφή της κλάσης @code{list} με το όρισμα @ref{326,,int}. Τα αντικείμενα @code{GenericAlias} προορίζονται κυρίως για χρήση με @ref{409,,type annotations}.

@cartouche
@quotation Σημείωση 
Γενικά είναι δυνατή η εγγραφή μιας κλάσης μόνο εάν η κλάση εφαρμόζει την ειδική μέθοδο @ref{b21,,__class_getitem__()}.
@end quotation
@end cartouche

Ένα αντικείμενο @code{GenericAlias} λειτουργεί ως διακομιστής μεσολάβησης (proxy) για έναν @ref{1d1,,generic type}, υλοποιώντας `parameterized generics'.

Για μια κλάση container, το(α) όρισμα(τα) που παρέχει σε μια @ref{2599,,subscription} της κλάσης μπορεί να υποδεικνύει τον(ους) τύπο(ους) των στοιχείων που περιέχει ένα αντικείμενο. Για παράδειγμα, το @code{set[bytes]} μπορεί να χρησιμοποιηθεί σε annotations τύπου για  να υποδηλώσει ένα @ref{42b,,set} στο  οποίο όλα τα στοιχεία είναι τύπου @ref{1c7,,bytes}.

Για μια κλάση που ορίζει @ref{b21,,__class_getitem__()} αλλά δεν είναι container, τα ορίσματα που παρέχονται σε μια συνδρομή της κλάσης θα υποδεικνύουν συχνά τον τύπο ή τους τύπους επιστροφής μιας ή περισσότερων μεθόδων που ορίζονται σε ένα αντικείμενο. Για παράδειγμα, το @ref{c1,,regular expressions} μπορούν να χρησιμοποιηθούν τόσο στον τύπο δεδομένων @ref{1df,,str} όσο και στον τύπο δεδομένων @ref{1c7,,bytes}:


@itemize *

@item 
Εάν @code{x = re.search('foo', 'foo')}, το @code{x} θα είναι ένα αντικείμενο @ref{1332,,re.Match} όπου επιστρέφονται οι τιμές του το @code{x.group(0)} και το @code{x[0]} θα είναι και τα δύο τύπου @ref{1df,,str}. Μπορούμε να αναπαραστήσουμε αυτό το είδος  αντικειμένου σε σχολιασμούς τύπου με το @code{GenericAlias} @code{re.Match[str]}.

@item 
Εάν @code{y = re.search(b'bar', b'bar')}, (σημειώστε το @code{b} για @ref{1c7,,bytes}), το @code{y} θα είναι επίσης μια παρουσία του @code{re.Match}, αλλά οι επιστρεφόμενες τιμές των @code{y.group(0)} και @code{y[0]} θα είναι και οι δύο τύπου @code{bytes}. Στους τύπους annotations, θα αντιπροσωπεύαμε αυτήν την ποικιλία αντικειμένων @ref{1332,,re.Match} με το @code{re.Match[bytes]}.
@end itemize

Τα αντικείμενα @code{GenericAlias} είναι στιγμιότυπα της κλάσης @ref{bc7,,types.GenericAlias}, τα οποία μπορούν επίσης να χρησιμοποιηθούν για την δημιουργία αντικειμένων @code{GenericAlias} απευθείας.


@deffn {Describe} T[X, Y, ...]

Δημιουργεί ένα @code{GenericAlias} που αντιπροσωπεύει έναν τύπο @code{T} παραμετροποιημένο από τύπους `X', `Y', και άλλα ανάλογα με το @code{T} που χρησιμοποιείται. Για παράδειγμα, μια συνάρτηση που αναμένει μια @ref{4d9,,list} που περιέχει στοιχεία της  @ref{327,,float}:

@example
def average(values: list[float]) -> float:
    return sum(values) / len(values)
@end example

Ένα άλλο παράδειγμα για αντικείμενα @ref{1564,,mapping}, χρησιμοποιώντας ένα @ref{188,,dict},που είναι ένας generic τύπος που αναμένει δύο παραμέτρους τύπου που αντιπροσωπεύουν τον τύπο κλειδιού και τον τύπο τιμής.  Σε αυτό το παράδειγμα, η συνάρτηση αναμένει ένα @code{dict} με κλειδιά τύπου @ref{1df,,str} και τιμές τύπου @ref{326,,int}:

@example
def send_post_request(url: str, body: dict[str, int]) -> None:
    ...
@end example
@end deffn

Οι ενσωματωμένες συναρτήσεις (built-in) @ref{2ef,,isinstance()} και @ref{2f0,,issubclass()} δεν δέχονται τους τύπους @code{GenericAlias} για το δεύτερο όρισμά τους:

@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

Ο χρόνος εκτέλεσης Python δεν επιβάλλει @ref{409,,type annotations}. Αυτό επεκτείνεται σε generic τύπους και στις παραμέτρους τύπου τους. Κατά τη δημιουργία ενός αντικειμένου container από ένα @code{GenericAlias}, τα στοιχεία στο container δεν ελέγχονται ως προς τον τύπο τους. Για παράδειγμα, ο ακόλουθος κώδικας αποθαρρύνεται, αλλά θα εκτελεστεί χωρίς σφάλματα:

@example
>>> t = list[str]
>>> t([1, 2, 3])
[1, 2, 3]
@end example

Επιπλέον, τα παραμετροποιημένα generics διαγράφουν τις παραμέτρους τύπου κατά τη δημιουργία αντικειμένου:

@example
>>> t = list[str]
>>> type(t)
<class 'types.GenericAlias'>

>>> l = t()
>>> type(l)
<class 'list'>
@end example

Η κλήση @ref{45b,,repr()} ή @ref{1df,,str()} σε ένα generic δείχνει τον παραμετροποιημένο τύπο:

@example
>>> repr(list[int])
'list[int]'

>>> str(list[int])
'list[int]'
@end example

Η μέθοδος @ref{787,,__getitem__()} των generic containers θα κάνει raise μια εξαίρεση για την απαγόρευση λαθών όπως @code{dict[str][str]}:

@example
>>> dict[str][str]
Traceback (most recent call last):
  ...
TypeError: dict[str] is not a generic class
@end example

Ωστόσο, τέτοιες εκφράσεις είναι έγκυρες όταν χρησιμοποιούνται μεταβλητές τύπου @ref{25bf,,type variables}.  Το ευρετήριο πρέπει να έχει τόσα στοιχεία όσα και τα στοιχεία μεταβλητής τύπου στο αντικείμενο @code{GenericAlias} @ref{28a8,,__args__}.

@example
>>> from typing import TypeVar
>>> Y = TypeVar('Y')
>>> dict[str, Y][int]
dict[str, int]
@end example

@menu
* Τυπικές Γενικές Κλάσεις:: 
* Ειδικά Χαρακτηριστικά αντικειμένων GenericAlias:: 

@end menu

@node Τυπικές Γενικές Κλάσεις,Ειδικά Χαρακτηριστικά αντικειμένων GenericAlias,,Τύπος Generic Alias
@anchor{library/stdtypes standard-generic-classes}@anchor{28a9}
@subsubsection Τυπικές Γενικές Κλάσεις


Οι ακόλουθες τυπικές κλάσεις βιβλιοθήκης υποστηρίζουν γενικά παραμετροποιημένα. Αυτή η λίστα δεν είναι εξαντλητική.


@itemize *

@item 
@ref{1ce,,tuple}

@item 
@ref{4d9,,list}

@item 
@ref{188,,dict}

@item 
@ref{42b,,set}

@item 
@ref{182,,frozendict}

@item 
@ref{9d4,,frozenset}

@item 
@ref{186,,type}

@item 
@ref{f8b,,asyncio.Future}

@item 
@ref{460,,asyncio.Task}

@item 
@ref{9d6,,collections.deque}

@item 
@ref{1565,,collections.defaultdict}

@item 
@ref{9d5,,collections.OrderedDict}

@item 
@ref{204,,collections.Counter}

@item 
@ref{fdb,,collections.ChainMap}

@item 
@ref{1194,,collections.abc.Awaitable}

@item 
@ref{1195,,collections.abc.Coroutine}

@item 
@ref{1197,,collections.abc.AsyncIterable}

@item 
@ref{1196,,collections.abc.AsyncIterator}

@item 
@ref{104a,,collections.abc.AsyncGenerator}

@item 
@ref{28aa,,collections.abc.Iterable}

@item 
@ref{28ab,,collections.abc.Iterator}

@item 
@ref{1193,,collections.abc.Generator}

@item 
@ref{1048,,collections.abc.Reversible}

@item 
@ref{28ac,,collections.abc.Container}

@item 
@ref{1047,,collections.abc.Collection}

@item 
@ref{bc6,,collections.abc.Callable}

@item 
@ref{28a1,,collections.abc.Set}

@item 
@ref{28ad,,collections.abc.MutableSet}

@item 
@ref{c9c,,collections.abc.Mapping}

@item 
@ref{1459,,collections.abc.MutableMapping}

@item 
@ref{156d,,collections.abc.Sequence}

@item 
@ref{6c6,,collections.abc.MutableSequence}

@item 
@ref{2cb,,collections.abc.ByteString}

@item 
@ref{28ae,,collections.abc.MappingView}

@item 
@ref{28af,,collections.abc.KeysView}

@item 
@ref{28b0,,collections.abc.ItemsView}

@item 
@ref{28b1,,collections.abc.ValuesView}

@item 
@ref{104d,,contextlib.AbstractContextManager}

@item 
@ref{eeb,,contextlib.AbstractAsyncContextManager}

@item 
@ref{1b6e,,dataclasses.Field}

@item 
@ref{94e,,functools.cached_property}

@item 
@ref{4a7,,functools.partialmethod}

@item 
@ref{100f,,os.PathLike}

@item 
@ref{28b2,,queue.LifoQueue}

@item 
@ref{1738,,queue.Queue}

@item 
@ref{28b3,,queue.PriorityQueue}

@item 
@ref{f27,,queue.SimpleQueue}

@item 
@ref{1331,,re.Pattern}

@item 
@ref{1332,,re.Match}

@item 
@ref{28b4,,shelve.BsdDbShelf}

@item 
@ref{28b5,,shelve.DbfilenameShelf}

@item 
@ref{1344,,shelve.Shelf}

@item 
@ref{189,,types.MappingProxyType}

@item 
@ref{1b44,,weakref.WeakKeyDictionary}

@item 
@ref{1398,,weakref.WeakMethod}

@item 
@ref{9d7,,weakref.WeakSet}

@item 
@ref{1b45,,weakref.WeakValueDictionary}
@end itemize

@node Ειδικά Χαρακτηριστικά αντικειμένων GenericAlias,,Τυπικές Γενικές Κλάσεις,Τύπος Generic Alias
@anchor{library/stdtypes special-attributes-of-genericalias-objects}@anchor{28b6}
@subsubsection Ειδικά Χαρακτηριστικά αντικειμένων @code{GenericAlias}


Όλα τα παραμετροποιημένα generics εφαρμόζουν ειδικά χαρακτηριστικά μόνο για ανάγνωση.

@geindex __origin__ (ιδιότητα της genericalias)
@anchor{library/stdtypes genericalias __origin__}@anchor{28b7}
@deffn {Ιδιότητα} genericalias.__origin__

Αυτό το χαρακτηριστικό δείχνει στη μη παραμετροποιημένη γενική κλάση:

@example
>>> list[int].__origin__
<class 'list'>
@end example
@end deffn

@geindex __args__ (ιδιότητα της genericalias)
@anchor{library/stdtypes genericalias __args__}@anchor{28a8}
@deffn {Ιδιότητα} genericalias.__args__

Αυτό το χαρακτηριστικό είναι μια @ref{1ce,,tuple} (πιθανώς μήκους 1) generic τύπων που μεταβιβάστηκαν στο αρχικό @ref{b21,,__class_getitem__()} της generic κλάσης:

@example
>>> dict[str, list[int]].__args__
(<class 'str'>, list[int])
@end example
@end deffn

@geindex __parameters__ (ιδιότητα της genericalias)
@anchor{library/stdtypes genericalias __parameters__}@anchor{28b8}
@deffn {Ιδιότητα} genericalias.__parameters__

Αυτό το χαρακτηριστικό είναι μία νωχελικά υπολογισμένη πλειάδα (tuple) (πιθανώς κενή) μεταβλητών μοναδικού τύπου που βρίσκονται στο @code{__args__}:

@example
>>> from typing import TypeVar

>>> T = TypeVar('T')
>>> list[T].__parameters__
(~T,)
@end example

@cartouche
@quotation Σημείωση 
Ένα αντικείμενο @code{GenericAlias} με παραμέτρους @ref{295,,typing.ParamSpec} ενδέχεται να μην έχει σωστές @code{__parameters__} μετά την αντικατάσταση επειδή το @code{typing.ParamSpec} προορίζεται κυρίως για έλεγχο στατικού τύπου.
@end quotation
@end cartouche
@end deffn

@geindex __unpacked__ (ιδιότητα της genericalias)
@anchor{library/stdtypes genericalias __unpacked__}@anchor{28b9}
@deffn {Ιδιότητα} genericalias.__unpacked__

Ένα boolean που ισχύει αν το alias έχει αποσυμπιεστεί χρησιμοποιώντας τον τελεστή @code{*} (δείτε το @ref{293,,TypeVarTuple}).


Added in version 3.11.

@end deffn


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 484

@item PEP 484@footnote{https://peps.python.org/pep-0484/} - Type Hints

Παρουσιάζοντας το framework της Python για τύπους annotations.

@geindex Python Enhancement Proposals; PEP 585

@item PEP 585@footnote{https://peps.python.org/pep-0585/} - Τύπος Generics Συμβουλών στις Τυπικές Συλλογές

Εισαγωγή της δυνατότητας εγγενούς παραμετροποίησης κλάσεων τυπικής βιβλιοθήκης, υπό την προϋπόθεση ότι εφαρμόζουν τη μέθοδο ειδικής κλάσης @ref{b21,,__class_getitem__()}.

@item Τα @ref{25bf,,Generics}, @ref{8df,,user-defined generics} και @ref{19f2,,typing.Generic}

Τεκμηρίωση για τον τρόπο υλοποίησης generic κλάσεων που μπορούν να παραμετροποιηθούν κατά το χρόνο εκτέλεσης και να κατανοηθούν από στατικούς ελεγκτές τύπων.
@end table



Added in version 3.9.


@node Τύπος Ένωσης,,Τύπος Generic Alias,Τύποι Annotation τύπου — Generic Alias Union
@anchor{library/stdtypes types-union}@anchor{ba2}@anchor{library/stdtypes union-type}@anchor{28ba}
@subsubsection Τύπος Ένωσης


@geindex αντικείμενο;Ένωση
@geindex ένωση;τύπος

Ένα αντικείμενο ένωσης διατηρεί την τιμή της λειτουργίας @code{|} (bitwise or) σε πολλαπλά αντικείμενα @ref{27da,,type objects}.  Αυτοί οι τύποι προορίζονται κυρίως για @ref{409,,type annotations}. Η έκφραση τύπου ένωσης επιτρέπει την καθαρότερη σύνταξη υποδείξεων σε σύγκριση με την εγγραφή @ref{341,,typing.Union}.


@deffn {Describe} X | Y | ...

Ορίζει ένα αντικείμενο ένωσης που περιέχει τύπους `X', `Y', και ούτω καθεξής. Το @code{X | Y} σημαίνει είτε X είτε Y.  Είναι ισοδύναμο με το @code{typing.Union[X, Y]}. Για παράδειγμα, η ακόλουθη συνάρτηση αναμένει ένα όρισμα τύπου @ref{326,,int} or @ref{327,,float}:

@example
def square(number: int | float) -> int | float:
    return number ** 2
@end example

@cartouche
@quotation Σημείωση 
Ο τελεστής @code{|} δεν μπορεί να χρησιμοποιηθεί κατά το χρόνο εκτέλεσης για να ορίσει ενώσεις όπου ένα ή περισσότερα μέλη είναι μια μπροστινή αναφορά. Για  παράδειγμα το @code{int | "Foo"}, όπου το @code{"Foo"} είναι μια αναφορά σε μια κλάση που δεν έχει ακόμη καθοριστεί, θα αποτύχει κατά το χρόνο εκτέλεσης. Για ενώσεις που περιλαμβάνουν μπροστινές αναφορές, παρουσιάζει ολόκληρη την έκφραση ως συμβολοσειρά, π.χ. @code{"int | Foo"}.
@end quotation
@end cartouche
@end deffn


@deffn {Describe} union_object == other

Τα αντικείμενα ένωσης μπορούν να ελεγχθούν για ισότητα με άλλα αντικείμενα ένωσης.  Λεπτομέρειες:


@itemize *

@item 
Οι ενώσεις των ενώσεων ισοπεδώνονται:

@example
(int | str) | float == int | str | float
@end example

@item 
Οι περιττοί τύποι καταργούνται:

@example
int | str | int == int | str
@end example

@item 
Κατά τη σύγκριση των ενώσεων, η σειρά αγνοείται:

@example
int | str == str | int
@end example

@item 
Δημιουργεί στιγμιότυπα της @ref{341,,typing.Union}:

@example
int | str == typing.Union[int, str]
type(int | str) is typing.Union
@end example

@item 
Οι προαιρετικοί τύποι μπορούν να γραφτούν ως ένωση με @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)

Οι κλήσεις σε @ref{2ef,,isinstance()} και @ref{2f0,,issubclass()} υποστηρίζονται επίσης με ένα αντικείμενο ένωσης:

@example
>>> isinstance("", int | str)
True
@end example

Ωστόσο, το @ref{a9f,,parameterized generics} σε αντικείμενα ένωσης δεν μπορούν να ελεγχθούν:

@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

Ο τύπος που εκτίθεται από τον χρήστη για το αντικείμενο ένωσης μπορεί να προσπελαστεί από το @ref{341,,typing.Union} και να χρησιμοποιηθεί για ελέγχους @ref{2ef,,isinstance()}:

@example
>>> import typing
>>> isinstance(int | str, typing.Union)
True
>>> typing.Union()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot create 'typing.Union' instances
@end example

@cartouche
@quotation Σημείωση 
Η μέθοδος @code{__or__()} για αντικείμενα τύπου προστέθηκε για να υποστηρίξει τη σύνταξη @code{X | Y}.  Εάν μια μετακλάση υλοποιεί @code{__or__()}, η Ένωση μπορεί να την παρακάμψει:

@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 Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/} – Το PEP προτείνει τη σύνταξη @code{X | Y} και τον τύπο Ένωση.



Added in version 3.10.



Άλλαξε στην έκδοση 3.14: Τα αντικείμενα Union είναι πλέον στιγμιότυπα του @ref{341,,typing.Union}. Προηγουμένως, ήταν στιγμιότυπα της @ref{527,,types.UnionType}, το οποίο παραμείνει ένα ψευδώνυμο για τη @code{typing.Union}.


@node Άλλοι Ενσωματωμένοι built-in Τύποι,Ειδικά Χαρακτηριστικά,Τύποι Annotation τύπου — Generic Alias Union,Τύποι Built-in
@anchor{library/stdtypes other-built-in-types}@anchor{28bb}@anchor{library/stdtypes typesother}@anchor{28bc}
@subsection Άλλοι Ενσωματωμένοι (built-in) Τύποι


Ο διερμηνέας υποστηρίζει πολλά άλλα είδη αντικειμένων. Τα περισσότερα από αυτά υποστηρίζουν μόνο μία ή δύο λειτουργίες.

@menu
* Modules: Modules<4>. 
* Κλάσεις και Στιγμιότυπα Κλάσης:: 
* Συναρτήσεις:: 
* Μέθοδοι:: 
* Αντικείμενα Κώδικα:: 
* Τύποι Αντικειμένων:: 
* Το Αντικείμενο Null:: 
* Το αντικείμενο Ellipsis:: 
* Το NotImplemented Αντικείμενο:: 
* Εσωτερικά Αντικείμενα:: 

@end menu

@node Modules<4>,Κλάσεις και Στιγμιότυπα Κλάσης,,Άλλοι Ενσωματωμένοι built-in Τύποι
@anchor{library/stdtypes modules}@anchor{28bd}@anchor{library/stdtypes typesmodules}@anchor{28be}
@subsubsection Modules


Η μόνη ειδική λειτουργία σε ένα module είναι η πρόσβαση χαρακτηριστικών: @code{m.name}, όπου το `m' είναι ένα module και το `name' έχει πρόσβαση σε ένα όνομα που ορίζεται στον πίνακα συμβόλων του `m'. Τα χαρακτηριστικά του module μπορούν να εκχωρηθούν.  (Σημειώστε ότι η δήλωση @ref{9da,,import} δεν είναι, αυστηρά, μια λειτουργία σε ένα αντικείμενο module· το @code{import foo} δεν απαιτεί να υπάρχει ένα αντικείμενο module με το όνομα `foo' αλλά απαιτεί έναν (εξωτερικό) `definition' για ένα module που ονομάζεται `foo' κάπου.)

Ένα ειδικό χαρακτηριστικό κάθε module είναι @ref{1bf,,__dict__}. Αυτό είναι το λεξικό που περιέχει τον πίνακα συμβόλων της ενότητας. Η τροποποίηση αυτού του λεξικού θα αλλάξει στην πραγματικότητα τον πίνακα συμβόλων του module, αλλά η απευθείας εκχώρηση στο χαρακτηριστικό @code{__dict__} δεν είναι δυνατή (μπορείτε να γράψετε @code{m.__dict__['a'] = 1}, που ορίζει το @code{m.a} να είναι @code{1}, αλλά δεν μπορείτε να γράψετε @code{m.__dict__ = @{@}}).  Δεν συνίσταται η απευθείας τροποποίηση του @code{__dict__}.

Τα modules που είναι ενσωματωμένες στον διερμηνέα γράφονται ως εξής: @code{<module 'sys' (built-in)>}.  Εάν φορτωθούν από ένα αρχείο, γράφονται ως @code{<module 'os' from '/usr/local/lib/pythonX.Y/os.pyc'>}.

@node Κλάσεις και Στιγμιότυπα Κλάσης,Συναρτήσεις,Modules<4>,Άλλοι Ενσωματωμένοι built-in Τύποι
@anchor{library/stdtypes classes-and-class-instances}@anchor{28bf}@anchor{library/stdtypes typesobjects}@anchor{28c0}
@subsubsection Κλάσεις και Στιγμιότυπα Κλάσης


Δείτε @ref{251d,,Αντικείμενα@comma{} τιμές και τύποι} και @ref{167c,,Class definitions} για αυτά.

@node Συναρτήσεις,Μέθοδοι,Κλάσεις και Στιγμιότυπα Κλάσης,Άλλοι Ενσωματωμένοι built-in Τύποι
@anchor{library/stdtypes functions}@anchor{28c1}@anchor{library/stdtypes typesfunctions}@anchor{28c2}
@subsubsection Συναρτήσεις


Τα αντικείμενα συναρτήσεων δημιουργούνται από ορισμούς συναρτήσεων.  Η μόνη λειτουργία σε ένα αντικείμενο συνάρτησης είναι να το ονομάσουμε: @code{func(argument-list)}.

Υπάρχουν πραγματικά δύο είδη αντικειμένων συναρτήσεων: ενσωματωμένες συναρτήσεις και συναρτήσεις που καθορίζονται από τον χρήστη.  Και οι δύο υποστηρίζουν την ίδια λειτουργία (για να καλέσετε τη συνάρτηση), αλλά η υλοποίηση είναι διαφορετική, εξ ου και οι διαφορετικοί τύποι αντικειμένων.

Δείτε το @ref{2206,,Function definitions} για περισσότερες πληροφορίες.

@node Μέθοδοι,Αντικείμενα Κώδικα,Συναρτήσεις,Άλλοι Ενσωματωμένοι built-in Τύποι
@anchor{library/stdtypes methods}@anchor{28c3}@anchor{library/stdtypes typesmethods}@anchor{28c4}
@subsubsection Μέθοδοι


@geindex αντικείμενο;μέθοδος

Οι μέθοδοι είναι συναρτήσεις που καλούνται χρησιμοποιώντας το notation χαρακτηριστικών. Υπάρχουν δύο είδη: @ref{254b,,built-in methods} (όπως η @ref{aba,,append()} στις λίστες) και @ref{2297,,class instance method}. Οι ενσωματωμένες μέθοδοι περιγράφονται με τους τύπους που τις υποστηρίζουν.

Εάν αποκτήσετε πρόσβαση σε μια μέθοδο (μια συνάρτηση που ορίζεται μια namespace κλάση) μέσω ενός στιγμιοτύπου, λαμβάνετε ένα ειδικό αντικείμενο: ένα αντικείμενο `bound method' (ονομάζεται επίσης @ref{2297,,instance method}). Όταν καλείται, θα προσθέσει το όρισμα @code{self} στη λίστα ορισμάτων.  Οι δεσμευμένες μέθοδοι έχουν δύο ειδικά χαρακτηριστικά μόνο για ανάγνωση: @ref{176b,,m.__self__} είναι το αντικείμενο στο οποίο λειτουργεί η μέθοδος και @ref{16a1,,m.__func__} είναι η συνάρτηση που υλοποιεί την μέθοδο.  Η κλήση του @code{m(arg-1, arg-2, ..., arg-n)} είναι απολύτως ισοδύναμη με την κλήση του @code{m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)}.

Όπως τα @ref{79b,,function objects}, τα αντικείμενα δεσμευμένης μεθόδου υποστηρίζουν τη λήψη αυθαίρετων χαρακτηριστικών. Ωστόσο, δεδομένου ότι τα χαρακτηριστικά της μεθόδου αποθηκεύονται στην πραγματικότητα στο υποκείμενο αντικείμενο συνάρτησης (@ref{16a1,,method.__func__}), ο ορισμός χαρακτηριστικών μεθόδου σε δεσμευμένες μεθόδους δεν επιτρέπεται.  Η προσπάθεια ορισμού ενός χαρακτηριστικού σε μια μέθοδο έχει ως αποτέλεσμα να γίνει raise η @ref{1a9,,AttributeError}.  Για να ορίσετε ένα χαρακτηριστικό μεθόδου πρέπει να το ορίσετε ρητά στο υποκείμενο αντικείμενο συνάρτησης:

@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

Δείτε το @ref{2297,,Μέθοδοι Στιγμιοτύπου} για περισσότερες πληροφορίες.

@geindex αντικείμενο;κώδικας
@geindex αντικείμενο κώδικα

@node Αντικείμενα Κώδικα,Τύποι Αντικειμένων,Μέθοδοι,Άλλοι Ενσωματωμένοι built-in Τύποι
@anchor{library/stdtypes bltin-code-objects}@anchor{28c5}@anchor{library/stdtypes code-objects}@anchor{28c6}
@subsubsection Αντικείμενα Κώδικα


@geindex ενσωματωμένες (built-in) συναρτήσεις;compile
@geindex __code__ (χαρακτηριστικό αντικείμενου συνάρτησης)

Τα αντικείμενα κώδικα χρησιμοποιούνται από την υλοποίηση για να αναπαραστήσουν τον «ψευδο-μεταγλωττισμένο» εκτελέσιμο κώδικα Python, όπως ένα σώμα συνάρτησης. Διαφέρουν από τα αντικείμενα συνάρτησης επειδή δεν περιέχουν αναφορά στο παγκόσμιο (global) περιβάλλον εκτέλεσης τους.  Τα αντικείμενα κώδικα επιστρέφονται από την ενσωματωμένη συνάρτηση @ref{1c8,,compile()} και μπορεί να εξαχθεί από τα αντικείμενα συνάρτησης μέσω του χαρακτηριστικού τους @ref{79c,,__code__}. Δείτε επίσης το module @ref{1b,,code}.

Η πρόσβαση στη @ref{79c,,__code__} κάνει raise ένα @ref{1e65,,auditing event} @code{object.__getattr__} με ορίσματα @code{obj} και @code{"__code__"}.

@geindex ενσωματωμένες (built-in) συναρτήσεις;exec
@geindex ενσωματωμένες (built-in) συναρτήσεις;eval

Ένα αντικείμενο κώδικα μπορεί να εκτελεστεί ή να αξιολογηθεί περνώντας το (αντί για πηγαία συμβολοσειρά) στις ενσωματωμένες συναρτήσεις @ref{185,,exec()} ή @ref{184,,eval()}.

Δείτε @ref{2520,,Η τυπική ιεραρχία τύπου} για περισσότερες πληροφορίες.

@node Τύποι Αντικειμένων,Το Αντικείμενο Null,Αντικείμενα Κώδικα,Άλλοι Ενσωματωμένοι built-in Τύποι
@anchor{library/stdtypes bltin-type-objects}@anchor{27da}@anchor{library/stdtypes type-objects}@anchor{28c7}
@subsubsection Τύποι Αντικειμένων


@geindex ενσωματωμένες (built-in) συναρτήσεις;τύπος
@geindex module;τύποι

Τα αντικείμενα τύπου αντιπροσωπεύουν τους διάφορους τύπους αντικειμένων.  Ο τύπος ενός αντικειμένου προσεγγίζεται από την ενσωματωμένη συνάρτηση @ref{186,,type()}.  Δεν υπάρχουν ειδικές λειτουργίες στους τύπους.  Το τυπικό (standard) module @ref{10c,,types} ορίζει ονόματα για όλους τους τυπικούς ενσωματωμένους τύπους.

Οι τύποι γράφονται ως εξής: @code{<class 'int'>}.

@node Το Αντικείμενο Null,Το αντικείμενο Ellipsis,Τύποι Αντικειμένων,Άλλοι Ενσωματωμένοι built-in Τύποι
@anchor{library/stdtypes bltin-null-object}@anchor{28c8}@anchor{library/stdtypes the-null-object}@anchor{28c9}
@subsubsection Το Αντικείμενο Null


Αυτό το αντικείμενο επιστρέφεται από συναρτήσεις που δεν επιστρέφουν ρητά μια τιμή.  Δεν υποστηρίζει ειδικές λειτουργίες.  Υπάρχει ακριβώς ένα μηδενικό αντικείμενο, που ονομάζεται @code{None} (ένα ενσωματωμένο όνομα).  Το @code{type(None)()} παράγει το ίδιο singleton.

Γράφεται ως @code{None}.

@geindex ...;ellipsis literal

@node Το αντικείμενο Ellipsis,Το NotImplemented Αντικείμενο,Το Αντικείμενο Null,Άλλοι Ενσωματωμένοι built-in Τύποι
@anchor{library/stdtypes bltin-ellipsis-object}@anchor{21ea}@anchor{library/stdtypes the-ellipsis-object}@anchor{28ca}
@subsubsection Το αντικείμενο Ellipsis


Αυτό το αντικείμενο χρησιμοποιείται συχνά για να δηλωθεί ότι κάτι παραλείπεται. Δεν υποστηρίζει καμία ειδική λειτουργία. Υπάρχει ακριβώς ένα αντικείμενο ellipsis, με το όνομα @ref{2519,,Ellipsis} (ένα ενσωματωμένο όνομα). Το @code{type(Ellipsis)()} παράγει το μοναδικό αντικείμενο @code{Ellipsis}.

Γράφεται ως @code{Ellipsis} ή @code{...}.

Στην τυπική χρήση, το @code{...} ως αντικείμενο @code{Ellipsis} εμφανίζεται σε μερικές διαφορετικές θέσεις, για παράδειγμα:


@itemize -

@item 
Σε υποδείξεις τύπου, όπως @ref{28cb,,callable arguments} ή @ref{28cc,,tuple elements}.

@item 
Ως το σώμα μιας συνάρτησης αντί για μια @ref{21e9,,pass statement}.

@item 
Σε βιβλιοθήκες τρίτων, όπως το Numpy's slicing and striding@footnote{https://numpy.org/doc/stable/user/basics.indexing.html#slicing-and-striding}.
@end itemize

Η Python χρησιμοποιεί επίσης τρεις τελείες με τρόπους που δεν είναι αντικείμενα @code{Ellipsis}, για παράδειγμα:


@itemize -

@item 
Το @ref{1810,,ELLIPSIS} του doctest, ως ένα μοτίβο για ελλιπές περιεχόμενο.

@item 
Το προεπιλεγμένο προτρεπτικό της Python στο @ref{451,,interactive} κέλυφος όταν η μερική είσοδος είναι ανολοκλήρωτη.
@end itemize

Τέλος, η τεκμηρίωση της Python χρησιμοποιεί συχνά τρεις τελείες στην παραδοσιακή αγγλική χρήση για να δηλώσει παραλειπόμενο περιεχόμενο, ακόμα και σε παραδείγματα κώδικα που τις χρησιμοποιούν και ως @code{Ellipsis}.

@node Το NotImplemented Αντικείμενο,Εσωτερικά Αντικείμενα,Το αντικείμενο Ellipsis,Άλλοι Ενσωματωμένοι built-in Τύποι
@anchor{library/stdtypes bltin-notimplemented-object}@anchor{28cd}@anchor{library/stdtypes the-notimplemented-object}@anchor{28ce}
@subsubsection Το NotImplemented Αντικείμενο


Αυτό το αντικείμενο επιστρέφεται από συγκρίσεις και δυαδικές λειτουργίες όταν τους ζητείται να λειτουργήσουν σε τύπους που δεν υποστηρίζουν. Δείτε το @ref{26c7,,Comparisons} για περισσότερες πληροφορίες.  Υπάρχει ακριβώς ένα αντικείμενο @ref{440,,NotImplemented}. Το @code{type(NotImplemented)()} παράγει το στιγμιότυπο singleton.

Είναι γραμμένο ως @code{NotImplemented}.

@node Εσωτερικά Αντικείμενα,,Το NotImplemented Αντικείμενο,Άλλοι Ενσωματωμένοι built-in Τύποι
@anchor{library/stdtypes internal-objects}@anchor{28cf}@anchor{library/stdtypes typesinternal}@anchor{28d0}
@subsubsection Εσωτερικά Αντικείμενα


Δείτε @ref{2520,,Η τυπική ιεραρχία τύπου} για αυτές τις πληροφορίες.  Περιγράφει @ref{acd,,stack frame objects}, @ref{eba,,traceback objects}, και αντικείμενα τμηματοποίησης.

@node Ειδικά Χαρακτηριστικά,Περιορισμός μήκους μετατροπής συμβολοσειράς ακέραιου αριθμού,Άλλοι Ενσωματωμένοι built-in Τύποι,Τύποι Built-in
@anchor{library/stdtypes special-attributes}@anchor{28d1}@anchor{library/stdtypes specialattrs}@anchor{28d2}
@subsection Ειδικά Χαρακτηριστικά


Η υλοποίηση προσθέτει μερικά ειδικά χαρακτηριστικά μόνο για ανάγνωση σε διάφορους τύπους αντικειμένων, όπου είναι σχετικά.  Ορισμένα από αυτά δεν αναφέρονται από την ενσωματωμένη συνάρτηση @ref{a23,,dir()}.

@geindex __name__ (ιδιότητα της definition)
@anchor{library/stdtypes definition __name__}@anchor{140e}
@deffn {Ιδιότητα} definition.__name__

Το όνομα της κλάσης, της συνάρτησης, της μεθόδου, του descriptor ή του στιγμιοτύπου generator.
@end deffn

@geindex __qualname__ (ιδιότητα της definition)
@anchor{library/stdtypes definition __qualname__}@anchor{140d}
@deffn {Ιδιότητα} definition.__qualname__

Το @ref{1f19,,qualified name} της κλάσης, της συνάρτησης, της μεθόδου, του descriptor, ή του στιγμιοτύπου generator.


Added in version 3.3.

@end deffn

@geindex __module__ (ιδιότητα της definition)
@anchor{library/stdtypes definition __module__}@anchor{28d3}
@deffn {Ιδιότητα} definition.__module__

Το όνομα του module στο οποίο ορίστηκε μια κλάση ή μια συνάρτηση.
@end deffn

@geindex __doc__ (ιδιότητα της definition)
@anchor{library/stdtypes definition __doc__}@anchor{cf4}
@deffn {Ιδιότητα} definition.__doc__

Η συμβολοσειρά τεκμηρίωσης μιας κλάσης ή συνάρτησης ή @code{None} εάν δεν έχει οριστεί.
@end deffn

@geindex __type_params__ (ιδιότητα της definition)
@anchor{library/stdtypes definition __type_params__}@anchor{278e}
@deffn {Ιδιότητα} definition.__type_params__

Οι παράμετροι @ref{7a5,,type parameters} των γενικών κλάσεων, συναρτήσεων και @ref{870,,type aliases}. Για κλάσεις και συναρτήσεις που δεν είναι γενικές, αυτή θα είναι μια κενή πλειάδα.


Added in version 3.12.

@end deffn

@node Περιορισμός μήκους μετατροπής συμβολοσειράς ακέραιου αριθμού,,Ειδικά Χαρακτηριστικά,Τύποι Built-in
@anchor{library/stdtypes int-max-str-digits}@anchor{9ec}@anchor{library/stdtypes integer-string-conversion-length-limitation}@anchor{28d4}
@subsection Περιορισμός μήκους μετατροπής συμβολοσειράς ακέραιου αριθμού


Η CPython έχει ένα παγκόσμιο όριο για τη μετατροπή μεταξύ @ref{326,,int} and @ref{1df,,str} για τον μετριασμό των επιθέσεων άρνησης υπηρεσίας. Αυτό το όριο ισχύει `μόνο' για δεκαδικές ή άλλες βάσεις αριθμών που δεν έχουν την δύναμη του δύο. Οι δεξαεξαδικές, οκταδικές, και δυαδικές μετατροπές είναι απεριόριστες. Το όριο μπορεί να διαμορφωθεί.

Ο τύπος @ref{326,,int} στην CPython είναι ένας αυθαίρετος αριθμός μήκους που είναι αποθηκευμένος σε δυαδική μορφή (κοινώς γνωστός ως «bignum»). Δεν υπάρχει αλγόριθμος που να μπορεί να μετατρέψει μια συμβολοσειρά σε δυαδικό ακέραιο ή δυαδικό ακέραιο σε μια συμβολοσειρά σε γραμμικό χρόνο, `εκτός' εάν η βάση είναι δύναμη του 2. Ακόμη και οι πιο γνωστοί αλγόριθμοι για τη βάση 10 έχουν υποτετραγωνική πολυπλοκότητα. Η μετατροπή μιας μεγάλης τιμής όπως @code{int('1' * 500_000)} μπορεί να διαρκέσει περισσότερο από ένα δευτερόλεπτο σε μια γρήγορη CPU.

Ο περιορισμός του μεγέθους μετατροπής προσφέρει έναν πρακτικό τρόπο αποφυγής του 
@geindex Common Vulnerabilities and Exposures; CVE 2020-10735
CVE 2020-10735@footnote{https://www.cve.org/CVERecord?id=CVE-2020-10735}.

Το όριο εφαρμόζεται στον αριθμό των ψηφιακών χαρακτήρων στη συμβολοσειρά εισόδου ή εξόδου όταν εμπλέκεται ένας μη γραμμικός αλγόριθμος μετατροπής.  Τα underscores και το πρόσημο δεν υπολογίζονται στο όριο.

Όταν μια λειτουργία υπερβαίνει το όριο, γίνεται raise μια @ref{277,,ValueError}:

@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

Το προεπιλεγμένο όριο είναι 4300 ψηφία όπως προβλέπεται στο @ref{1638,,sys.int_info.default_max_str_digits}. Το κατώτατο όριο που μπορεί να διαμορφωθεί είναι 640 ψηφία όπως προβλέπεται στο @code{sys.int_info.str_digits_check_threshold}.

Επαλήθευση:

@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


Added in version 3.11.


@menu
* Επηρεασμένα APIs:: 
* Διαμόρφωση ορίου:: 
* Προτεινόμενη διαμόρφωση:: 

@end menu

@node Επηρεασμένα APIs,Διαμόρφωση ορίου,,Περιορισμός μήκους μετατροπής συμβολοσειράς ακέραιου αριθμού
@anchor{library/stdtypes affected-apis}@anchor{28d5}
@subsubsection Επηρεασμένα APIs


Ο περιορισμός ισχύει μόνο για δυνητικά αργές μετατροπές μεταξύ @ref{326,,int} και @ref{1df,,str} ή @ref{1c7,,bytes}:


@itemize *

@item 
@code{int(string)} με default βάση το 10.

@item 
@code{int(string, base)} για όλες τις βάσεις που δεν είναι δύναμη του 2.

@item 
@code{str(integer)}.

@item 
@code{repr(integer)}.

@item 
οποιαδήποτε άλλη μετατροπή συμβολοσειράς στη βάση 10, για παράδειγμα @code{f"@{integer@}"}, @code{"@{@}".format(integer)}, ή @code{b"%d" % integer}.
@end itemize

Οι περιορισμοί δεν ισχύουν για συναρτήσεις με γραμμικό αλγόριθμο:


@itemize *

@item 
@code{int(string, base)} με βάση 2, 4, 8, 16, ή 32.

@item 
@ref{198e,,int.from_bytes()} και @ref{1e29,,int.to_bytes()}.

@item 
@ref{1674,,hex()}, @ref{1673,,oct()}, @ref{164d,,bin()}.

@item 
@ref{6fe,,Format specification mini-language} για δεκαεξαδικούς, οκταδικούς και δυαδικούς αριθμούς.

@item 
@ref{1df,,str} σε @ref{327,,float}.

@item 
@ref{1df,,str} σε @ref{1c2,,decimal.Decimal}.
@end itemize

@node Διαμόρφωση ορίου,Προτεινόμενη διαμόρφωση,Επηρεασμένα APIs,Περιορισμός μήκους μετατροπής συμβολοσειράς ακέραιου αριθμού
@anchor{library/stdtypes configuring-the-limit}@anchor{28d6}
@subsubsection Διαμόρφωση ορίου


Πριν από την εκκίνηση της Python, μπορείτε να χρησιμοποιήσετε μια μεταβλητή περιβάλλοντος ή ένα δείκτη γραμμής εντολών διερμηνέα για να διαμορφώσετε το όριο:


@itemize *

@item 
@geindex PYTHONINTMAXSTRDIGITS
@geindex μεταβλητή περιβάλλοντος; PYTHONINTMAXSTRDIGITS
@ref{1d38,,PYTHONINTMAXSTRDIGITS}, π.χ. @code{PYTHONINTMAXSTRDIGITS=640 python3} για να ορίσετε το όριο σε 640 ή @code{PYTHONINTMAXSTRDIGITS=0 python3} για να απενεργοποιήσετε τον περιορισμό.

@item 
@ref{178,,-X int_max_str_digits}, π.χ. @code{python3 -X int_max_str_digits=640}

@item 
Το @ref{28d7,,sys.flags.int_max_str_digits} περιέχει την τιμή 
@geindex PYTHONINTMAXSTRDIGITS
@geindex μεταβλητή περιβάλλοντος; PYTHONINTMAXSTRDIGITS
@ref{1d38,,PYTHONINTMAXSTRDIGITS} ή @ref{178,,-X int_max_str_digits}. Εάν και η επιλογή env var και η επιλογή  @code{-X} είναι καθορισμένη, η επιλογή @code{-X} έχει προτεραιότητα. Μια τιμή `-1' υποδεικνύει ότι και τα δύο δεν ορίστηκαν, επομένως χρησιμοποιήθηκε μια τιμή @ref{28d8,,sys.int_info.default_max_str_digits} κατά την προετοιμασία.
@end itemize

Από τον κώδικα, μπορείτε να επιθεωρήσετε το τρέχον όριο και να ορίσετε ένα νέο χρησιμοποιώντας αυτά τα @ref{e2,,sys} APIs:


@itemize *

@item 
Οι @ref{1a12,,sys.get_int_max_str_digits()} και @ref{1b11,,sys.set_int_max_str_digits()} είναι ένας getter και setter για το όριο σε όλο τον διερμηνέα. Οι δευτερεύοντες διερμηνείς έχουν το δικό τους όριο.
@end itemize

Πληροφορίες σχετικά με την προεπιλογή και το ελάχιστο μπορούν να βρεθούν στο @ref{1638,,sys.int_info}:


@itemize *

@item 
Το @ref{1638,,sys.int_info.default_max_str_digits} είναι το  μεταγλωττισμένο προεπιλεγμένο όριο.

@item 
Το @ref{1638,,sys.int_info.str_digits_check_threshold} είναι η χαμηλότερη αποδεκτή τιμή για το όριο (εκτός από το 0 που το απενεργοποιεί).
@end itemize


Added in version 3.11.


@cartouche
@quotation Προσοχή 
Ο ορισμός ενός χαμηλού ορίου `μπορεί' να οδηγήσει σε προβλήματα. Αν και σπάνιος, υπάρχει κώδικας που περιέχει ακέραιες σταθερές σε δεκαδικό αριθμό στην πηγή τους που υπερβαίνουν το ελάχιστο όριο. Συνέπεια της ρύθμισης του ορίου είναι ότι ο πηγαίος κώδικας Python που περιέχει δεκαδικούς ακέραιους αριθμούς μεγαλύτερους από το όριο θα αντιμετωπίσει σφάλμα κατά την ανάλυση, συνήθως κατά την εκκίνηση ή την ώρα της εισαγωγής ή ακόμα και κατά την εγκατάσταση - ανά πάσα στιγμή είναι ενημερωμένο @code{.pyc} δεν υπάρχει ήδη για τον κώδικα. Μια λύση για τον πηγαίο που περιέχει τόσο μεγάλες σταθερές είναι να τις μετατρέψετε σε δεκαεξαδική μορφή @code{0x} καθώς δεν έχει όριο.

Δοκιμάστε σχολαστικά την εφαρμογή σας εάν χρησιμοποιείτε χαμηλό όριο. Βεβαιωθείτε ότι οι δοκιμές σας εκτελούνται με το όριο που έχει οριστεί νωρίς μέσω του περιβάλλοντος ή του δείκτη, ώστε να ισχύει κατά την εκκίνηση και ακόμη και κατά τη διάρκεια οποιουδήποτε βήματος εγκατάστασης που μπορεί να καλέσει την Python για να μεταγλωττίσει εκ των προτέρων το @code{.py} πηγαίο σε αρχεία @code{.pyc}.
@end quotation
@end cartouche

@node Προτεινόμενη διαμόρφωση,,Διαμόρφωση ορίου,Περιορισμός μήκους μετατροπής συμβολοσειράς ακέραιου αριθμού
@anchor{library/stdtypes recommended-configuration}@anchor{28d9}
@subsubsection Προτεινόμενη διαμόρφωση


Το προεπιλεγμένο @ref{28d8,,sys.int_info.default_max_str_digits} αναμένεται να είναι λογικό για τις περισσότερες εφαρμογές. Εάν η εφαρμογή σας απαιτεί διαφορετικό όριο, ορίστε το από το κύριο σημείο εισόδου σας χρησιμοποιώντας τον συμβατό με τον κώδικα της έκδοσης Python, καθώς αυτά τα API προστέθηκαν στην ενημερωμένη έκδοση κώδικα ασφαλείας σε εκδόσεις πριν από την 3.12.

Παράδειγμα:

@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

Εάν πρέπει να το απενεργοποιήσετε εντελώς, ορίστε το σε @code{0}.

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Built-in Exceptions,Thread Safety Guarantees,Τύποι Built-in,The Python Standard Library
@anchor{library/exceptions doc}@anchor{28da}@anchor{library/exceptions bltin-exceptions}@anchor{1e1e}@anchor{library/exceptions built-in-exceptions}@anchor{28db}@anchor{library/exceptions translation-repo}@anchor{28dc}
@section Built-in Exceptions


@geindex statement;try
@geindex statement;except

In Python, all exceptions must be instances of a class that derives from
@ref{9b9,,BaseException}.  In a @ref{ad6,,try} statement with an @ref{447,,except}
clause that mentions a particular class, that clause also handles any exception
classes derived from that class (but not exception classes from which `it' is
derived).  Two exception classes that are not related via subclassing are never
equivalent, even if they have the same name.

@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.

User code can raise built-in exceptions.  This can be used to test an exception
handler or to report an error condition «just like» the situation in which the
interpreter raises the same exception; but beware that there is nothing to
prevent user code from raising an inappropriate error.

The built-in exception classes can be subclassed to define new exceptions;
programmers are encouraged to derive new exceptions from the @ref{d9e,,Exception}
class or one of its subclasses, and not from @ref{9b9,,BaseException}.  More
information on defining exceptions is available in the Python Tutorial under
@ref{226b,,Εξαιρέσεις που καθορίζονται από το χρήστη}.

@menu
* Exception context:: 
* Inheriting from built-in exceptions:: 
* Base classes:: 
* Concrete exceptions:: 
* Warnings:: 
* Exception groups:: 
* Exception hierarchy:: 

@end menu

@node Exception context,Inheriting from built-in exceptions,,Built-in Exceptions
@anchor{library/exceptions exception-context}@anchor{28dd}
@subsection Exception context


@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__ (ιδιότητα της BaseException)
@geindex __cause__ (ιδιότητα της BaseException)
@geindex __suppress_context__ (ιδιότητα της BaseException)
@anchor{library/exceptions BaseException __context__}@anchor{166c}
@deffn {Ιδιότητα} BaseException.__context__
@anchor{library/exceptions BaseException __cause__}@anchor{166d}
@deffnx {Ιδιότητα} BaseException.__cause__
@anchor{library/exceptions BaseException __suppress_context__}@anchor{270a}
@deffnx {Ιδιότητα} 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{447,,except} or
@ref{44c,,finally} clause, or a @ref{20a,,with} statement, is used.

This implicit exception context can be
supplemented with an explicit cause by using @code{from} with
@ref{9e4,,raise}:

@example
raise new_exc from original_exc
@end example

The expression following @ref{9e4,,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{7df,,KeyError} to @ref{1a9,,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{a65,,None} and @code{__suppress_context__} is false.

In either case, the exception itself is always shown after any chained
exceptions so that the final line of the traceback always shows the last
exception that was raised.
@end deffn

@node Inheriting from built-in exceptions,Base classes,Exception context,Built-in Exceptions
@anchor{library/exceptions inheriting-from-built-in-exceptions}@anchor{28de}
@subsection Inheriting from built-in exceptions


User code can create subclasses that inherit from an exception type.
It’s recommended to only subclass one exception type at a time to avoid
any possible conflicts between how the bases handle the @code{args}
attribute, as well as due to possible memory layout incompatibilities.

`Λεπτομέρεια υλοποίησης CPython:' Most built-in exceptions are implemented in C for efficiency, see:
Objects/exceptions.c@footnote{https://github.com/python/cpython/tree/main/Objects/exceptions.c}.  Some have custom memory layouts
which makes it impossible to create a subclass that inherits from
multiple exception types. The memory layout of a type is an implementation
detail and might change between Python versions, leading to new
conflicts in the future.  Therefore, it’s recommended to avoid
subclassing multiple exception types altogether.

@node Base classes,Concrete exceptions,Inheriting from built-in exceptions,Built-in Exceptions
@anchor{library/exceptions base-classes}@anchor{28df}
@subsection Base classes


The following exceptions are used mostly as base classes for other exceptions.

@geindex BaseException
@anchor{library/exceptions BaseException}@anchor{9b9}
@deffn {Εξαίρεση} BaseException

The base class for all built-in exceptions.  It is not meant to be directly
inherited by user-defined classes (for that, use @ref{d9e,,Exception}).  If
@ref{1df,,str()} is called on an instance of this class, the representation of
the argument(s) to the instance are returned, or the empty string when
there were no arguments.

@geindex args (ιδιότητα της BaseException)
@anchor{library/exceptions BaseException args}@anchor{972}
@deffn {Ιδιότητα} args

The tuple of arguments given to the exception constructor.  Some built-in
exceptions (like @ref{53c,,OSError}) expect a certain number of arguments and
assign a special meaning to the elements of this tuple, while others are
usually called only with a single string giving an error message.
@end deffn

@geindex with_traceback() (μέθοδος της BaseException)
@anchor{library/exceptions BaseException with_traceback}@anchor{2709}
@deffn {Μέθοδος} with_traceback (tb)

This method sets `tb' as the new traceback for the exception and returns
the exception object.  It was more commonly used before the exception
chaining features of 
@geindex Python Enhancement Proposals; PEP 3134
PEP 3134@footnote{https://peps.python.org/pep-3134/} became available.  The following example
shows how we can convert an instance of @code{SomeException} into an
instance of @code{OtherException} while preserving the traceback.  Once
raised, the current frame is pushed onto the traceback of the
@code{OtherException}, as would have happened to the traceback of the
original @code{SomeException} had we allowed it to propagate to the caller.

@example
try:
    ...
except SomeException:
    tb = sys.exception().__traceback__
    raise OtherException(...).with_traceback(tb)
@end example
@end deffn

@geindex __traceback__ (ιδιότητα της BaseException)
@anchor{library/exceptions BaseException __traceback__}@anchor{166b}
@deffn {Ιδιότητα} __traceback__

A writable field that holds the
@ref{eba,,traceback object} associated with this
exception. See also: @ref{9e4,,Η εντολή raise}.
@end deffn

@geindex add_note() (μέθοδος της BaseException)
@anchor{library/exceptions BaseException add_note}@anchor{9b8}
@deffn {Μέθοδος} 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{291,,TypeError} is raised if @code{note}
is not a string.


Added in version 3.11.

@end deffn

@geindex __notes__ (ιδιότητα της BaseException)
@anchor{library/exceptions BaseException __notes__}@anchor{28e0}
@deffn {Ιδιότητα} __notes__

A list of the notes of this exception, which were added with @ref{9b8,,add_note()}.
This attribute is created when @code{add_note()} is called.


Added in version 3.11.

@end deffn
@end deffn

@geindex Exception
@anchor{library/exceptions Exception}@anchor{d9e}
@deffn {Εξαίρεση} Exception

All built-in, non-system-exiting exceptions are derived from this class.  All
user-defined exceptions should also be derived from this class.
@end deffn

@geindex ArithmeticError
@anchor{library/exceptions ArithmeticError}@anchor{28e1}
@deffn {Εξαίρεση} ArithmeticError

The base class for those built-in exceptions that are raised for various
arithmetic errors: @ref{c57,,OverflowError}, @ref{d11,,ZeroDivisionError},
@ref{28e2,,FloatingPointError}.
@end deffn

@geindex BufferError
@anchor{library/exceptions BufferError}@anchor{1998}
@deffn {Εξαίρεση} BufferError

Raised when a @ref{311,,buffer} related operation cannot be
performed.
@end deffn

@geindex LookupError
@anchor{library/exceptions LookupError}@anchor{25da}
@deffn {Εξαίρεση} LookupError

The base class for the exceptions that are raised when a key or index used on
a mapping or sequence is invalid: @ref{18d7,,IndexError}, @ref{7df,,KeyError}.  This
can be raised directly by @ref{d2d,,codecs.lookup()}.
@end deffn

@node Concrete exceptions,Warnings,Base classes,Built-in Exceptions
@anchor{library/exceptions concrete-exceptions}@anchor{28e3}
@subsection Concrete exceptions


The following exceptions are the exceptions that are usually raised.

@geindex AssertionError
@anchor{library/exceptions AssertionError}@anchor{a97}
@deffn {Εξαίρεση} AssertionError

@geindex statement;assert

Raised when an @ref{d31,,assert} statement fails.
@end deffn

@geindex AttributeError
@anchor{library/exceptions AttributeError}@anchor{1a9}
@deffn {Εξαίρεση} AttributeError

Raised when an attribute reference (see @ref{26a0,,Attribute references}) or
assignment fails.  (When an object does not support attribute references or
attribute assignments at all, @ref{291,,TypeError} is raised.)

The optional `name' and `obj' keyword-only arguments
set the corresponding attributes:

@geindex name (ιδιότητα της AttributeError)
@anchor{library/exceptions AttributeError name}@anchor{28e4}
@deffn {Ιδιότητα} name

The name of the attribute that was attempted to be accessed.
@end deffn

@geindex obj (ιδιότητα της AttributeError)
@anchor{library/exceptions AttributeError obj}@anchor{28e5}
@deffn {Ιδιότητα} obj

The object that was accessed for the named attribute.
@end deffn


Άλλαξε στην έκδοση 3.10: Added the @ref{28e4,,name} and @ref{28e5,,obj} attributes.

@end deffn

@geindex EOFError
@anchor{library/exceptions EOFError}@anchor{167e}
@deffn {Εξαίρεση} EOFError

Raised when the @ref{167d,,input()} function hits an end-of-file condition (EOF)
without reading any data. (Note: the @ref{225b,,io.TextIOBase.read()} and
@ref{16ce,,io.IOBase.readline()} methods return an empty string when they hit EOF.)
@end deffn

@geindex FloatingPointError
@anchor{library/exceptions FloatingPointError}@anchor{28e2}
@deffn {Εξαίρεση} FloatingPointError

Not currently used.
@end deffn

@geindex GeneratorExit
@anchor{library/exceptions GeneratorExit}@anchor{176a}
@deffn {Εξαίρεση} GeneratorExit

Raised when a @ref{1409,,generator} or @ref{8a2,,coroutine} is closed;
see @ref{199e,,generator.close()} and @ref{2610,,coroutine.close()}.  It
directly inherits from @ref{9b9,,BaseException} instead of @ref{d9e,,Exception} since
it is technically not an error.
@end deffn

@geindex ImportError
@anchor{library/exceptions ImportError}@anchor{1bd}
@deffn {Εξαίρεση} ImportError

Raised when the @ref{9da,,import} statement has troubles trying to
load a module.  Also raised when the «from list» in @code{from ... import}
has a name that cannot be found.

The optional `name' and `path' keyword-only arguments
set the corresponding attributes:

@geindex name (ιδιότητα της ImportError)
@anchor{library/exceptions ImportError name}@anchor{1902}
@deffn {Ιδιότητα} name

The name of the module that was attempted to be imported.
@end deffn

@geindex path (ιδιότητα της ImportError)
@anchor{library/exceptions ImportError path}@anchor{28e6}
@deffn {Ιδιότητα} path

The path to any file which triggered the exception.
@end deffn


Άλλαξε στην έκδοση 3.3: Added the @ref{1902,,name} and @ref{28e6,,path} attributes.

@end deffn

@geindex ModuleNotFoundError
@anchor{library/exceptions ModuleNotFoundError}@anchor{1be}
@deffn {Εξαίρεση} ModuleNotFoundError

A subclass of @ref{1bd,,ImportError} which is raised by @ref{9da,,import}
when a module could not be located.  It is also raised when @code{None}
is found in @ref{19ba,,sys.modules}.


Added in version 3.6.

@end deffn

@geindex ImportCycleError
@anchor{library/exceptions ImportCycleError}@anchor{28e7}
@deffn {Εξαίρεση} ImportCycleError

A subclass of @ref{1bd,,ImportError} which is raised when a lazy import fails
because it (directly or indirectly) tries to import itself.


Added in version 3.15.

@end deffn

@geindex IndexError
@anchor{library/exceptions IndexError}@anchor{18d7}
@deffn {Εξαίρεση} IndexError

Raised when a sequence subscript is out of range.  (Slice indices are
silently truncated to fall in the allowed range; if an index is not an
integer, @ref{291,,TypeError} is raised.)

@c XXX xref to sequences
@end deffn

@geindex KeyError
@anchor{library/exceptions KeyError}@anchor{7df}
@deffn {Εξαίρεση} KeyError

Raised when a mapping (dictionary) key is not found in the set of existing keys.

@c XXX xref to mapping objects?
@end deffn

@geindex KeyboardInterrupt
@anchor{library/exceptions KeyboardInterrupt}@anchor{d96}
@deffn {Εξαίρεση} KeyboardInterrupt

Raised when the user hits the interrupt key (normally @code{Control}-@code{C} or
@code{Delete}).  During execution, a check for interrupts is made
regularly. The exception inherits from @ref{9b9,,BaseException} so as to not be
accidentally caught by code that catches @ref{d9e,,Exception} and thus prevent
the interpreter from exiting.

@cartouche
@quotation Σημείωση 
Catching a @code{KeyboardInterrupt} requires special consideration.
Because it can be raised at unpredictable points, it may, in some
circumstances, leave the running program in an inconsistent state. It is
generally best to allow @code{KeyboardInterrupt} to end the program as
quickly as possible or avoid raising it entirely. (See
@ref{28e8,,Note on Signal Handlers and Exceptions}.)
@end quotation
@end cartouche
@end deffn

@geindex MemoryError
@anchor{library/exceptions MemoryError}@anchor{18fa}
@deffn {Εξαίρεση} MemoryError

Raised when an operation runs out of memory but the situation may still be
rescued (by deleting some objects).  The associated value is a string indicating
what kind of (internal) operation ran out of memory. Note that because of the
underlying memory management architecture (C’s @code{malloc()} function), the
interpreter may not always be able to completely recover from this situation; it
nevertheless raises an exception so that a stack traceback can be printed, in
case a run-away program was the cause.
@end deffn

@geindex NameError
@anchor{library/exceptions NameError}@anchor{665}
@deffn {Εξαίρεση} NameError

Raised when a local or global name is not found.  This applies only to
unqualified names.  The associated value is an error message that includes the
name that could not be found.

The optional `name' keyword-only argument sets the attribute:

@geindex name (ιδιότητα της NameError)
@anchor{library/exceptions NameError name}@anchor{28e9}
@deffn {Ιδιότητα} name

The name of the variable that was attempted to be accessed.
@end deffn


Άλλαξε στην έκδοση 3.10: Added the @ref{28e9,,name} attribute.

@end deffn

@geindex NotImplementedError
@anchor{library/exceptions NotImplementedError}@anchor{59a}
@deffn {Εξαίρεση} NotImplementedError

This exception is derived from @ref{30d,,RuntimeError}.  In user defined base
classes, abstract methods should raise this exception when they require
derived classes to override the method, or while the class is being
developed to indicate that the real implementation still needs to be added.

@cartouche
@quotation Σημείωση 
It should not be used to indicate that an operator or method is not
meant to be supported at all – in that case either leave the operator /
method undefined or, if a subclass, set it to @ref{a65,,None}.
@end quotation
@end cartouche

@cartouche
@quotation Προσοχή 
@code{NotImplementedError} and @code{NotImplemented} are not
interchangeable. This exception should only be used as described
above; see @ref{440,,NotImplemented} for details on correct usage of
the built-in constant.
@end quotation
@end cartouche
@end deffn

@geindex OSError
@anchor{library/exceptions OSError}@anchor{53c}
@deffn {Εξαίρεση} OSError ([arg])

@deffnx {Εξαίρεση} OSError (errno, strerror[, filename[, winerror[, filename2]]])

@geindex module;errno

This exception is raised when a system function returns a system-related
error, including I/O failures such as «file not found» or «disk full»
(not for illegal argument types or other incidental errors).

The second form of the constructor sets the corresponding attributes,
described below.  The attributes default to @ref{a65,,None} if not
specified.  For backwards compatibility, if three arguments are passed,
the @ref{972,,args} attribute contains only a 2-tuple
of the first two constructor arguments.

The constructor often actually returns a subclass of @code{OSError}, as
described in @ref{28ea,,OS exceptions} below.  The particular subclass depends on
the final @ref{19ca,,errno} value.  This behaviour only occurs when
constructing @code{OSError} directly or via an alias, and is not
inherited when subclassing.

@geindex errno (ιδιότητα της OSError)
@anchor{library/exceptions OSError errno}@anchor{19ca}
@deffn {Ιδιότητα} errno

A numeric error code from the C variable @code{errno}.
@end deffn

@geindex winerror (ιδιότητα της OSError)
@anchor{library/exceptions OSError winerror}@anchor{28eb}
@deffn {Ιδιότητα} winerror

Under Windows, this gives you the native
Windows error code.  The @ref{19ca,,errno} attribute is then an approximate
translation, in POSIX terms, of that native error code.

Under Windows, if the `winerror' constructor argument is an integer,
the @ref{19ca,,errno} attribute is determined from the Windows error code,
and the `errno' argument is ignored.  On other platforms, the
`winerror' argument is ignored, and the @ref{28eb,,winerror} attribute
does not exist.
@end deffn

@geindex strerror (ιδιότητα της OSError)
@anchor{library/exceptions OSError strerror}@anchor{28ec}
@deffn {Ιδιότητα} strerror

The corresponding error message, as provided by
the operating system.  It is formatted by the C
functions @code{perror()} under POSIX, and @code{FormatMessage()}
under Windows.
@end deffn

@geindex filename (ιδιότητα της OSError)
@geindex filename2 (ιδιότητα της OSError)
@anchor{library/exceptions OSError filename}@anchor{28ed}
@deffn {Ιδιότητα} filename
@anchor{library/exceptions OSError filename2}@anchor{28ee}
@deffnx {Ιδιότητα} filename2

For exceptions that involve a file system path (such as @ref{32b,,open()} or
@ref{14a1,,os.unlink()}), @ref{28ed,,filename} is the file name passed to the function.
For functions that involve two file system paths (such as
@ref{149d,,os.rename()}), @ref{28ee,,filename2} corresponds to the second
file name passed to the function.
@end deffn


Άλλαξε στην έκδοση 3.3: @ref{13fc,,EnvironmentError}, @ref{13fb,,IOError}, @ref{13fd,,WindowsError},
@ref{13fe,,socket.error}, @ref{13ff,,select.error} and
@code{mmap.error} have been merged into @code{OSError}, and the
constructor may return a subclass.



Άλλαξε στην έκδοση 3.4: The @ref{28ed,,filename} attribute is now the original file name passed to
the function, instead of the name encoded to or decoded from the
@ref{948,,filesystem encoding and error handler}. Also, the `filename2'
constructor argument and attribute was added.

@end deffn

@geindex OverflowError
@anchor{library/exceptions OverflowError}@anchor{c57}
@deffn {Εξαίρεση} 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{18fa,,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{68a}
@deffn {Εξαίρεση} PythonFinalizationError

This exception is derived from @ref{30d,,RuntimeError}.  It is raised when
an operation is blocked during interpreter shutdown also known as
@ref{1a0,,Python finalization}.

Examples of operations which can be blocked with a
@code{PythonFinalizationError} during the Python finalization:


@itemize *

@item 
Creating a new Python thread.

@item 
@ref{158d,,Joining} a running daemon thread.

@item 
@ref{6bd,,os.fork()},

@item 
acquiring a lock such as @ref{1a10,,threading.Lock}, when it is known that
the operation would otherwise deadlock.
@end itemize

See also the @ref{e4f,,sys.is_finalizing()} function.


Added in version 3.13: Previously, a plain @ref{30d,,RuntimeError} was raised.



Άλλαξε στην έκδοση 3.14: @ref{158d,,threading.Thread.join()} can now raise this exception.



Άλλαξε στην έκδοση 3.15: This exception may be raised when acquiring @ref{1a10,,threading.Lock()}
or @ref{2df,,threading.RLock()}.

@end deffn

@geindex RecursionError
@anchor{library/exceptions RecursionError}@anchor{1121}
@deffn {Εξαίρεση} RecursionError

This exception is derived from @ref{30d,,RuntimeError}.  It is raised when the
interpreter detects that the maximum recursion depth (see
@ref{8d4,,sys.getrecursionlimit()}) is exceeded.


Added in version 3.5: Previously, a plain @ref{30d,,RuntimeError} was raised.

@end deffn

@geindex ReferenceError
@anchor{library/exceptions ReferenceError}@anchor{18af}
@deffn {Εξαίρεση} ReferenceError

This exception is raised when a weak reference proxy, created by the
@ref{e15,,weakref.proxy()} function, is used to access an attribute of the referent
after it has been garbage collected. For more information on weak references,
see the @ref{11d,,weakref} module.
@end deffn

@geindex RuntimeError
@anchor{library/exceptions RuntimeError}@anchor{30d}
@deffn {Εξαίρεση} RuntimeError

Raised when an error is detected that doesn’t fall in any of the other
categories.  The associated value is a string indicating what precisely went
wrong.
@end deffn

@geindex StopIteration
@anchor{library/exceptions StopIteration}@anchor{fba}
@deffn {Εξαίρεση} StopIteration

Raised by built-in function @ref{bb5,,next()} and an @ref{6ce,,iterator}'s
@ref{1672,,__next__()} method to signal that there are no further
items produced by the iterator.

@geindex value (ιδιότητα της StopIteration)
@anchor{library/exceptions StopIteration value}@anchor{260c}
@deffn {Ιδιότητα} value

The exception object has a single attribute @code{value}, which is
given as an argument when constructing the exception, and defaults
to @ref{a65,,None}.
@end deffn

When a @ref{1409,,generator} or @ref{8a2,,coroutine} function
returns, a new @code{StopIteration} instance is
raised, and the value returned by the function is used as the
@ref{260c,,value} parameter to the constructor of the exception.

If a generator code directly or indirectly raises @code{StopIteration},
it is converted into a @ref{30d,,RuntimeError} (retaining the
@code{StopIteration} as the new exception’s cause).


Άλλαξε στην έκδοση 3.3: Added @code{value} attribute and the ability for generator functions to
use it to return a value.



Άλλαξε στην έκδοση 3.5: Introduced the RuntimeError transformation via
@code{from __future__ import generator_stop}, see 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/}.



Άλλαξε στην έκδοση 3.7: Enable 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/} for all code by default: a @code{StopIteration}
error raised in a generator is transformed into a @ref{30d,,RuntimeError}.

@end deffn

@geindex StopAsyncIteration
@anchor{library/exceptions StopAsyncIteration}@anchor{1ffe}
@deffn {Εξαίρεση} StopAsyncIteration

Must be raised by @ref{1aa7,,__anext__()} method of an
@ref{6cd,,asynchronous iterator} object to stop the iteration.


Added in version 3.5.

@end deffn

@geindex SyntaxError
@anchor{library/exceptions SyntaxError}@anchor{17e}
@deffn {Εξαίρεση} SyntaxError (message, details)

Raised when the parser encounters a syntax error.  This may occur in an
@ref{9da,,import} statement, in a call to the built-in functions
@ref{1c8,,compile()}, @ref{185,,exec()},
or @ref{184,,eval()}, or when reading the initial script or standard input
(also interactively).

The @ref{1df,,str()} of the exception instance returns only the error message.
Details is a tuple whose members are also available as separate attributes.

@geindex filename (ιδιότητα της SyntaxError)
@anchor{library/exceptions SyntaxError filename}@anchor{28ef}
@deffn {Ιδιότητα} filename

The name of the file the syntax error occurred in.
@end deffn

@geindex lineno (ιδιότητα της SyntaxError)
@anchor{library/exceptions SyntaxError lineno}@anchor{28f0}
@deffn {Ιδιότητα} lineno

Which line number in the file the error occurred in. This is
1-indexed: the first line in the file has a @code{lineno} of 1.
@end deffn

@geindex offset (ιδιότητα της SyntaxError)
@anchor{library/exceptions SyntaxError offset}@anchor{28f1}
@deffn {Ιδιότητα} offset

The column in the line where the error occurred. This is
1-indexed: the first character in the line has an @code{offset} of 1.
@end deffn

@geindex text (ιδιότητα της SyntaxError)
@anchor{library/exceptions SyntaxError text}@anchor{28f2}
@deffn {Ιδιότητα} text

The source code text involved in the error.
@end deffn

@geindex end_lineno (ιδιότητα της SyntaxError)
@anchor{library/exceptions SyntaxError end_lineno}@anchor{28f3}
@deffn {Ιδιότητα} end_lineno

Which line number in the file the error occurred ends in. This is
1-indexed: the first line in the file has a @code{lineno} of 1.
@end deffn

@geindex end_offset (ιδιότητα της SyntaxError)
@anchor{library/exceptions SyntaxError end_offset}@anchor{28f4}
@deffn {Ιδιότητα} end_offset

The column in the end line where the error occurred finishes. This is
1-indexed: the first character in the line has an @code{offset} of 1.
@end deffn

For errors in f-string fields, the message is prefixed by «f-string: »
and the offsets are offsets in a text constructed from the replacement
expression.  For example, compiling f’Bad @{a b@} field” results in this
args attribute: (“f-string: …”, (“”, 1, 2, “(a b)n”, 1, 5)).


Άλλαξε στην έκδοση 3.10: Added the @ref{28f3,,end_lineno} and @ref{28f4,,end_offset} attributes.

@end deffn

@geindex IndentationError
@anchor{library/exceptions IndentationError}@anchor{b89}
@deffn {Εξαίρεση} IndentationError

Base class for syntax errors related to incorrect indentation.  This is a
subclass of @ref{17e,,SyntaxError}.
@end deffn

@geindex TabError
@anchor{library/exceptions TabError}@anchor{950}
@deffn {Εξαίρεση} TabError

Raised when indentation contains an inconsistent use of tabs and spaces.
This is a subclass of @ref{b89,,IndentationError}.
@end deffn

@geindex SystemError
@anchor{library/exceptions SystemError}@anchor{3ea}
@deffn {Εξαίρεση} SystemError

Raised when the interpreter finds an internal error, but the situation does not
look so serious to cause it to abandon all hope. The associated value is a
string indicating what went wrong (in low-level terms). In @ref{ae3,,CPython},
this could be raised by incorrectly using Python’s C API, such as returning
a @code{NULL} value without an exception set.

If you’re confident that this exception wasn’t your fault, or the fault of
a package you’re using, you should report this to the author or maintainer
of your Python interpreter.
Be sure to report the version of the Python interpreter (@code{sys.version}; it is
also printed at the start of an interactive Python session), the exact error
message (the exception’s associated value) and if possible the source of the
program that triggered the error.
@end deffn

@geindex SystemExit
@anchor{library/exceptions SystemExit}@anchor{10f7}
@deffn {Εξαίρεση} SystemExit

This exception is raised by the @ref{4ff,,sys.exit()} function.  It inherits from
@ref{9b9,,BaseException} instead of @ref{d9e,,Exception} so that it is not accidentally
caught by code that catches @code{Exception}.  This allows the exception to
properly propagate up and cause the interpreter to exit.  When it is not
handled, the Python interpreter exits; no stack traceback is printed.  The
constructor accepts the same optional argument passed to @code{sys.exit()}.
If the value is an integer, it specifies the system exit status (passed to
C’s @code{exit()} function); if it is @code{None}, the exit status is zero; if
it has another type (such as a string), the object’s value is printed and
the exit status is one.

A call to @ref{4ff,,sys.exit()} is translated into an exception so that clean-up
handlers (@ref{44c,,finally} clauses of @ref{ad6,,try} statements) can be
executed, and so that a debugger can execute a script without running the risk
of losing control.  The @ref{28f5,,os._exit()} function can be used if it is
absolutely positively necessary to exit immediately (for example, in the child
process after a call to @ref{6bd,,os.fork()}).

@geindex code (ιδιότητα της SystemExit)
@anchor{library/exceptions SystemExit code}@anchor{28f6}
@deffn {Ιδιότητα} code

The exit status or error message that is passed to the constructor.
(Defaults to @code{None}.)
@end deffn
@end deffn

@geindex TypeError
@anchor{library/exceptions TypeError}@anchor{291}
@deffn {Εξαίρεση} TypeError

Raised when an operation or function is applied to an object of inappropriate
type.  The associated value is a string giving details about the type mismatch.

This exception may be raised by user code to indicate that an attempted
operation on an object is not supported, and is not meant to be. If an object
is meant to support a given operation but has not yet provided an
implementation, @ref{59a,,NotImplementedError} is the proper exception to raise.

Passing arguments of the wrong type (e.g. passing a @ref{4d9,,list} when an
@ref{326,,int} is expected) should result in a @code{TypeError}, but passing
arguments with the wrong value (e.g. a number outside expected boundaries)
should result in a @ref{277,,ValueError}.
@end deffn

@geindex UnboundLocalError
@anchor{library/exceptions UnboundLocalError}@anchor{18d8}
@deffn {Εξαίρεση} UnboundLocalError

Raised when a reference is made to a local variable in a function or method, but
no value has been bound to that variable.  This is a subclass of
@ref{665,,NameError}.
@end deffn

@geindex UnicodeError
@anchor{library/exceptions UnicodeError}@anchor{675}
@deffn {Εξαίρεση} UnicodeError

Raised when a Unicode-related encoding or decoding error occurs.  It is a
subclass of @ref{277,,ValueError}.

@code{UnicodeError} has attributes that describe the encoding or decoding
error.  For example, @code{err.object[err.start:err.end]} gives the particular
invalid input that the codec failed on.

@geindex encoding (ιδιότητα της UnicodeError)
@anchor{library/exceptions UnicodeError encoding}@anchor{28f7}
@deffn {Ιδιότητα} encoding

The name of the encoding that raised the error.
@end deffn

@geindex reason (ιδιότητα της UnicodeError)
@anchor{library/exceptions UnicodeError reason}@anchor{28f8}
@deffn {Ιδιότητα} reason

A string describing the specific codec error.
@end deffn

@geindex object (ιδιότητα της UnicodeError)
@anchor{library/exceptions UnicodeError object}@anchor{1b1b}
@deffn {Ιδιότητα} object

The object the codec was attempting to encode or decode.
@end deffn

@geindex start (ιδιότητα της UnicodeError)
@anchor{library/exceptions UnicodeError start}@anchor{1ae1}
@deffn {Ιδιότητα} start

The first index of invalid data in @ref{e4d,,object}.

This value should not be negative as it is interpreted as an
absolute offset but this constraint is not enforced at runtime.
@end deffn

@geindex end (ιδιότητα της UnicodeError)
@anchor{library/exceptions UnicodeError end}@anchor{1ae2}
@deffn {Ιδιότητα} end

The index after the last invalid data in @ref{e4d,,object}.

This value should not be negative as it is interpreted as an
absolute offset but this constraint is not enforced at runtime.
@end deffn
@end deffn

@geindex UnicodeEncodeError
@anchor{library/exceptions UnicodeEncodeError}@anchor{a67}
@deffn {Εξαίρεση} UnicodeEncodeError

Raised when a Unicode-related error occurs during encoding.  It is a subclass of
@ref{675,,UnicodeError}.
@end deffn

@geindex UnicodeDecodeError
@anchor{library/exceptions UnicodeDecodeError}@anchor{dd7}
@deffn {Εξαίρεση} UnicodeDecodeError

Raised when a Unicode-related error occurs during decoding.  It is a subclass of
@ref{675,,UnicodeError}.
@end deffn

@geindex UnicodeTranslateError
@anchor{library/exceptions UnicodeTranslateError}@anchor{1b1c}
@deffn {Εξαίρεση} UnicodeTranslateError

Raised when a Unicode-related error occurs during translating.  It is a subclass
of @ref{675,,UnicodeError}.
@end deffn

@geindex ValueError
@anchor{library/exceptions ValueError}@anchor{277}
@deffn {Εξαίρεση} ValueError

Raised when an operation or function receives an argument that has the
right type but an inappropriate value, and the situation is not described by a
more precise exception such as @ref{18d7,,IndexError}.
@end deffn

@geindex ZeroDivisionError
@anchor{library/exceptions ZeroDivisionError}@anchor{d11}
@deffn {Εξαίρεση} ZeroDivisionError

Raised when the second argument of a division or modulo operation is zero.  The
associated value is a string indicating the type of the operands and the
operation.
@end deffn

The following exceptions are kept for compatibility with previous versions;
starting from Python 3.3, they are aliases of @ref{53c,,OSError}.

@geindex EnvironmentError
@anchor{library/exceptions EnvironmentError}@anchor{13fc}
@deffn {Εξαίρεση} EnvironmentError
@end deffn

@geindex IOError
@anchor{library/exceptions IOError}@anchor{13fb}
@deffn {Εξαίρεση} IOError
@end deffn

@geindex WindowsError
@anchor{library/exceptions WindowsError}@anchor{13fd}
@deffn {Εξαίρεση} WindowsError

Only available on Windows.
@end deffn

@menu
* OS exceptions:: 

@end menu

@node OS exceptions,,,Concrete exceptions
@anchor{library/exceptions os-exceptions}@anchor{28ea}
@subsubsection OS exceptions


The following exceptions are subclasses of @ref{53c,,OSError}, they get raised
depending on the system error code.

@geindex BlockingIOError
@anchor{library/exceptions BlockingIOError}@anchor{4c3}
@deffn {Εξαίρεση} BlockingIOError

Raised when an operation would block on an object (e.g. socket) set
for non-blocking operation.
Corresponds to @code{errno} @ref{28f9,,EAGAIN}, @ref{28fa,,EALREADY},
@ref{28fb,,EWOULDBLOCK} and @ref{28fc,,EINPROGRESS}.

In addition to those of @ref{53c,,OSError}, @code{BlockingIOError} can have
one more attribute:

@geindex characters_written (ιδιότητα της BlockingIOError)
@anchor{library/exceptions BlockingIOError characters_written}@anchor{28fd}
@deffn {Ιδιότητα} characters_written

An integer containing the number of `bytes' written to the stream
before it blocked. This attribute is available when using the
buffered I/O classes from the @ref{82,,io} module.
@end deffn
@end deffn

@geindex ChildProcessError
@anchor{library/exceptions ChildProcessError}@anchor{1400}
@deffn {Εξαίρεση} ChildProcessError

Raised when an operation on a child process failed.
Corresponds to @code{errno} @ref{28fe,,ECHILD}.
@end deffn

@geindex ConnectionError
@anchor{library/exceptions ConnectionError}@anchor{11bf}
@deffn {Εξαίρεση} ConnectionError

A base class for connection-related issues.

Subclasses are @ref{1404,,BrokenPipeError}, @ref{1405,,ConnectionAbortedError},
@ref{1406,,ConnectionRefusedError} and @ref{1407,,ConnectionResetError}.
@end deffn

@geindex BrokenPipeError
@anchor{library/exceptions BrokenPipeError}@anchor{1404}
@deffn {Εξαίρεση} BrokenPipeError

A subclass of @ref{11bf,,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{28ff,,EPIPE} and @ref{2900,,ESHUTDOWN}.
@end deffn

@geindex ConnectionAbortedError
@anchor{library/exceptions ConnectionAbortedError}@anchor{1405}
@deffn {Εξαίρεση} ConnectionAbortedError

A subclass of @ref{11bf,,ConnectionError}, raised when a connection attempt
is aborted by the peer.
Corresponds to @code{errno} @ref{2901,,ECONNABORTED}.
@end deffn

@geindex ConnectionRefusedError
@anchor{library/exceptions ConnectionRefusedError}@anchor{1406}
@deffn {Εξαίρεση} ConnectionRefusedError

A subclass of @ref{11bf,,ConnectionError}, raised when a connection attempt
is refused by the peer.
Corresponds to @code{errno} @ref{2902,,ECONNREFUSED}.
@end deffn

@geindex ConnectionResetError
@anchor{library/exceptions ConnectionResetError}@anchor{1407}
@deffn {Εξαίρεση} ConnectionResetError

A subclass of @ref{11bf,,ConnectionError}, raised when a connection is
reset by the peer.
Corresponds to @code{errno} @ref{2903,,ECONNRESET}.
@end deffn

@geindex FileExistsError
@anchor{library/exceptions FileExistsError}@anchor{13c9}
@deffn {Εξαίρεση} FileExistsError

Raised when trying to create a file or directory which already exists.
Corresponds to @code{errno} @ref{2904,,EEXIST}.
@end deffn

@geindex FileNotFoundError
@anchor{library/exceptions FileNotFoundError}@anchor{243}
@deffn {Εξαίρεση} FileNotFoundError

Raised when a file or directory is requested but doesn’t exist.
Corresponds to @code{errno} @ref{2905,,ENOENT}.
@end deffn

@geindex InterruptedError
@anchor{library/exceptions InterruptedError}@anchor{1141}
@deffn {Εξαίρεση} InterruptedError

Raised when a system call is interrupted by an incoming signal.
Corresponds to @code{errno} @ref{1140,,EINTR}.


Άλλαξε στην έκδοση 3.5: Python now retries system calls when a syscall is 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 @code{InterruptedError}.

@end deffn

@geindex IsADirectoryError
@anchor{library/exceptions IsADirectoryError}@anchor{1401}
@deffn {Εξαίρεση} IsADirectoryError

Raised when a file operation (such as @ref{149c,,os.remove()}) is requested
on a directory.
Corresponds to @code{errno} @ref{2906,,EISDIR}.
@end deffn

@geindex NotADirectoryError
@anchor{library/exceptions NotADirectoryError}@anchor{1402}
@deffn {Εξαίρεση} NotADirectoryError

Raised when a directory operation (such as @ref{14a6,,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{2907,,ENOTDIR}.
@end deffn

@geindex PermissionError
@anchor{library/exceptions PermissionError}@anchor{10f9}
@deffn {Εξαίρεση} PermissionError

Raised when trying to run an operation without the adequate access
rights - for example filesystem permissions.
Corresponds to @code{errno} @ref{2908,,EACCES},
@ref{1d54,,EPERM}, and @ref{1d3d,,ENOTCAPABLE}.


Άλλαξε στην έκδοση 3.11.1: WASI’s @ref{1d3d,,ENOTCAPABLE} is now mapped to
@code{PermissionError}.

@end deffn

@geindex ProcessLookupError
@anchor{library/exceptions ProcessLookupError}@anchor{1403}
@deffn {Εξαίρεση} ProcessLookupError

Raised when a given process doesn’t exist.
Corresponds to @code{errno} @ref{2909,,ESRCH}.
@end deffn

@geindex TimeoutError
@anchor{library/exceptions TimeoutError}@anchor{c0e}
@deffn {Εξαίρεση} TimeoutError

Raised when a system function timed out at the system level.
Corresponds to @code{errno} @ref{290a,,ETIMEDOUT}.
@end deffn


Added in version 3.3: All the above @ref{53c,,OSError} subclasses were added.



@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 3151
PEP 3151@footnote{https://peps.python.org/pep-3151/} - Reworking the OS and IO exception hierarchy


@node Warnings,Exception groups,Concrete exceptions,Built-in Exceptions
@anchor{library/exceptions warning-categories-as-exceptions}@anchor{290b}@anchor{library/exceptions warnings}@anchor{290c}
@subsection Warnings


The following exceptions are used as warning categories; see the
@ref{290d,,Κατηγορίες Προειδοποίησης} documentation for more details.

@geindex Warning
@anchor{library/exceptions Warning}@anchor{290e}
@deffn {Εξαίρεση} Warning

Base class for warning categories.
@end deffn

@geindex UserWarning
@anchor{library/exceptions UserWarning}@anchor{290f}
@deffn {Εξαίρεση} UserWarning

Base class for warnings generated by user code.
@end deffn

@geindex DeprecationWarning
@anchor{library/exceptions DeprecationWarning}@anchor{2c9}
@deffn {Εξαίρεση} DeprecationWarning

Base class for warnings about deprecated features when those warnings are
intended for other Python developers.

Ignored by the default warning filters, except in the @code{__main__} module
(
@geindex Python Enhancement Proposals; PEP 565
PEP 565@footnote{https://peps.python.org/pep-0565/}). Enabling the @ref{70d,,Python Development Mode} shows
this warning.

The deprecation policy is described in 
@geindex Python Enhancement Proposals; PEP 387
PEP 387@footnote{https://peps.python.org/pep-0387/}.
@end deffn

@geindex PendingDeprecationWarning
@anchor{library/exceptions PendingDeprecationWarning}@anchor{c9b}
@deffn {Εξαίρεση} PendingDeprecationWarning

Base class for warnings about features which are obsolete and
expected to be deprecated in the future, but are not deprecated
at the moment.

This class is rarely used as emitting a warning about a possible
upcoming deprecation is unusual, and @ref{2c9,,DeprecationWarning}
is preferred for already active deprecations.

Ignored by the default warning filters. Enabling the @ref{70d,,Python Development Mode} shows this warning.

The deprecation policy is described in 
@geindex Python Enhancement Proposals; PEP 387
PEP 387@footnote{https://peps.python.org/pep-0387/}.
@end deffn

@geindex SyntaxWarning
@anchor{library/exceptions SyntaxWarning}@anchor{44a}
@deffn {Εξαίρεση} SyntaxWarning

Base class for warnings about dubious syntax.

This warning is typically emitted when compiling Python source code, and usually won’t be reported
when running already compiled code.
@end deffn

@geindex RuntimeWarning
@anchor{library/exceptions RuntimeWarning}@anchor{6dd}
@deffn {Εξαίρεση} RuntimeWarning

Base class for warnings about dubious runtime behavior.
@end deffn

@geindex FutureWarning
@anchor{library/exceptions FutureWarning}@anchor{847}
@deffn {Εξαίρεση} FutureWarning

Base class for warnings about deprecated features when those warnings are
intended for end users of applications that are written in Python.
@end deffn

@geindex ImportWarning
@anchor{library/exceptions ImportWarning}@anchor{907}
@deffn {Εξαίρεση} ImportWarning

Base class for warnings about probable mistakes in module imports.

Ignored by the default warning filters. Enabling the @ref{70d,,Python Development Mode} shows this warning.
@end deffn

@geindex UnicodeWarning
@anchor{library/exceptions UnicodeWarning}@anchor{17c6}
@deffn {Εξαίρεση} UnicodeWarning

Base class for warnings related to Unicode.
@end deffn

@geindex EncodingWarning
@anchor{library/exceptions EncodingWarning}@anchor{231d}
@deffn {Εξαίρεση} EncodingWarning

Base class for warnings related to encodings.

See @ref{1ac,,Opt-in EncodingWarning} for details.


Added in version 3.10.

@end deffn

@geindex BytesWarning
@anchor{library/exceptions BytesWarning}@anchor{2ee}
@deffn {Εξαίρεση} BytesWarning

Base class for warnings related to @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
@end deffn

@geindex ResourceWarning
@anchor{library/exceptions ResourceWarning}@anchor{74f}
@deffn {Εξαίρεση} ResourceWarning

Base class for warnings related to resource usage.

Ignored by the default warning filters. Enabling the @ref{70d,,Python Development Mode} shows this warning.


Added in version 3.2.

@end deffn

@node Exception groups,Exception hierarchy,Warnings,Built-in Exceptions
@anchor{library/exceptions exception-groups}@anchor{2910}@anchor{library/exceptions lib-exception-groups}@anchor{2911}
@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{447,,except} like all other exceptions. In addition,
they are recognised by @ref{448,,except*}, which matches
their subgroups based on the types of the contained exceptions.

@geindex ExceptionGroup
@anchor{library/exceptions ExceptionGroup}@anchor{6d8}
@deffn {Εξαίρεση} ExceptionGroup (msg, excs)
@end deffn

@geindex BaseExceptionGroup
@anchor{library/exceptions BaseExceptionGroup}@anchor{767}
@deffn {Εξαίρεση} 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 @code{BaseExceptionGroup} extends @ref{9b9,,BaseException} and
it can wrap any exception, while @ref{6d8,,ExceptionGroup} extends @ref{d9e,,Exception}
and it can only wrap subclasses of @code{Exception}. This design is so that
@code{except Exception} catches an @code{ExceptionGroup} but not
@code{BaseExceptionGroup}.

The @code{BaseExceptionGroup} constructor returns an @ref{6d8,,ExceptionGroup}
rather than a @code{BaseExceptionGroup} if all contained exceptions are
@ref{d9e,,Exception} instances, so it can be used to make the selection
automatic. The @code{ExceptionGroup} constructor, on the other hand,
raises a @ref{291,,TypeError} if any contained exception is not an
@code{Exception} subclass.

`Λεπτομέρεια υλοποίησης CPython:' The @code{excs} parameter may be any sequence, but lists and tuples are
specifically processed more efficiently here. For optimal performance,
pass a tuple as @code{excs}.

@geindex message (ιδιότητα της BaseExceptionGroup)
@anchor{library/exceptions BaseExceptionGroup message}@anchor{2912}
@deffn {Ιδιότητα} message

The @code{msg} argument to the constructor. This is a read-only attribute.
@end deffn

@geindex exceptions (ιδιότητα της BaseExceptionGroup)
@anchor{library/exceptions BaseExceptionGroup exceptions}@anchor{2913}
@deffn {Ιδιότητα} 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() (μέθοδος της BaseExceptionGroup)
@anchor{library/exceptions BaseExceptionGroup subgroup}@anchor{1c40}
@deffn {Μέθοδος} 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{2912,,message},
@ref{166b,,__traceback__}, @ref{166d,,__cause__},
@ref{166c,,__context__} and
@ref{28e0,,__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.


Added in version 3.13: @code{condition} can be any callable which is not a type object.

@end deffn

@geindex split() (μέθοδος της BaseExceptionGroup)
@anchor{library/exceptions BaseExceptionGroup split}@anchor{1af9}
@deffn {Μέθοδος} split (condition)

Like @ref{1c40,,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() (μέθοδος της BaseExceptionGroup)
@anchor{library/exceptions BaseExceptionGroup derive}@anchor{1c3f}
@deffn {Μέθοδος} derive (excs)

Returns an exception group with the same @ref{2912,,message}, but which
wraps the exceptions in @code{excs}.

This method is used by @ref{1c40,,subgroup()} and @ref{1af9,,split()}, which
are used in various contexts to break up an exception group. A
subclass needs to override it in order to make @code{subgroup()}
and @code{split()} return instances of the subclass rather
than @ref{6d8,,ExceptionGroup}.

@ref{1c40,,subgroup()} and @ref{1af9,,split()} copy the
@ref{166b,,__traceback__},
@ref{166d,,__cause__}, @ref{166c,,__context__} and
@ref{28e0,,__notes__} fields from
the original exception group to the one returned by @code{derive()}, so
these fields do not need to be updated by @code{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 @code{BaseExceptionGroup} defines @ref{982,,__new__()}, so
subclasses that need a different constructor signature need to
override that rather than @ref{2fa,,__init__()}. For example, the following
defines an exception group subclass which accepts an exit_code 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{6d8,,ExceptionGroup}, any subclass of @code{BaseExceptionGroup} which
is also a subclass of @ref{d9e,,Exception} can only wrap instances of
@code{Exception}.


Added in version 3.11.

@end deffn

@node Exception hierarchy,,Exception groups,Built-in Exceptions
@anchor{library/exceptions exception-hierarchy}@anchor{2914}
@subsection Exception hierarchy


The class hierarchy for built-in exceptions is:

@example
BaseException
 ├── BaseExceptionGroup
 ├── GeneratorExit
 ├── KeyboardInterrupt
 ├── SystemExit
 └── Exception
      ├── ArithmeticError
      │    ├── FloatingPointError
      │    ├── OverflowError
      │    └── ZeroDivisionError
      ├── AssertionError
      ├── AttributeError
      ├── BufferError
      ├── EOFError
      ├── ExceptionGroup [BaseExceptionGroup]
      ├── ImportError
      │    └── ImportCycleError
      │    └── 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Thread Safety Guarantees,Text Processing Services,Built-in Exceptions,The Python Standard Library
@anchor{library/threadsafety doc}@anchor{2915}@anchor{library/threadsafety thread-safety-guarantees}@anchor{2916}@anchor{library/threadsafety threadsafety}@anchor{2917}@anchor{library/threadsafety translation-repo}@anchor{2918}
@section Thread Safety Guarantees


This page documents thread-safety guarantees for built-in types in Python’s
free-threaded build. The guarantees described here apply when using Python with
the @ref{411,,GIL} disabled (free-threaded mode). When the GIL is enabled, most
operations are implicitly serialized.

For general guidance on writing thread-safe code in free-threaded Python, see
@ref{2919,,Python support for free threading}.

@menu
* Thread safety levels:: 
* Thread safety for list objects:: 
* Thread safety for dict objects:: 
* Thread safety for set objects:: 
* Thread safety for bytearray objects:: 
* Thread safety for memoryview objects:: 

@end menu

@node Thread safety levels,Thread safety for list objects,,Thread Safety Guarantees
@anchor{library/threadsafety thread-safety-levels}@anchor{291a}@anchor{library/threadsafety threadsafety-levels}@anchor{291b}
@subsection Thread safety levels


The C API documentation uses the following levels to describe the thread
safety guarantees of each function. The levels are listed from least to
most safe.

@menu
* Incompatible:: 
* Compatible:: 
* Safe on distinct objects:: 
* Safe on shared objects:: 
* Atomic:: 

@end menu

@node Incompatible,Compatible,,Thread safety levels
@anchor{library/threadsafety incompatible}@anchor{291c}@anchor{library/threadsafety threadsafety-level-incompatible}@anchor{291d}
@subsubsection Incompatible


A function or operation that cannot be made safe for concurrent use even
with external synchronization. Incompatible code typically accesses
global state in an unsynchronized way and must only be called from a single
thread throughout the program’s lifetime.

Example: a function that modifies process-wide state such as signal handlers
or environment variables, where concurrent calls from any threads, even with
external locking, can conflict with the runtime or other libraries.

@node Compatible,Safe on distinct objects,Incompatible,Thread safety levels
@anchor{library/threadsafety compatible}@anchor{291e}@anchor{library/threadsafety threadsafety-level-compatible}@anchor{291f}
@subsubsection Compatible


A function or operation that is safe to call from multiple threads
`provided' the caller supplies appropriate external synchronization, for
example by holding a @ref{2920,,lock} for the duration of each call. Without
such synchronization, concurrent calls may produce @ref{2921,,race conditions} or @ref{2922,,data races}.

Example: a function that reads from or writes to an object whose internal
state is not protected by a lock. Callers must ensure that no two threads
access the same object at the same time.

@node Safe on distinct objects,Safe on shared objects,Compatible,Thread safety levels
@anchor{library/threadsafety safe-on-distinct-objects}@anchor{2923}@anchor{library/threadsafety threadsafety-level-distinct}@anchor{2924}
@subsubsection Safe on distinct objects


A function or operation that is safe to call from multiple threads without
external synchronization, as long as each thread operates on a `different'
object. Two threads may call the function at the same time, but they must
not pass the same object (or objects that share underlying state) as
arguments.

Example: a function that modifies fields of a struct using non-atomic
writes. Two threads can each call the function on their own struct
instance safely, but concurrent calls on the `same' instance require
external synchronization.

@node Safe on shared objects,Atomic,Safe on distinct objects,Thread safety levels
@anchor{library/threadsafety safe-on-shared-objects}@anchor{2925}@anchor{library/threadsafety threadsafety-level-shared}@anchor{2926}
@subsubsection Safe on shared objects


A function or operation that is safe for concurrent use on the `same'
object. The implementation uses internal synchronization (such as
@ref{2927,,per-object locks} or
@ref{2928,,critical sections}) to protect shared
mutable state, so callers do not need to supply their own locking.

Example: @ref{7f4,,PyList_GetItemRef()} can be called from multiple threads on the
same @ref{2929,,PyListObject} - it uses internal synchronization to serialize
access.

@node Atomic,,Safe on shared objects,Thread safety levels
@anchor{library/threadsafety atomic}@anchor{292a}@anchor{library/threadsafety threadsafety-level-atomic}@anchor{292b}
@subsubsection Atomic


A function or operation that appears @ref{292c,,atomic} with
respect to other threads - it executes instantaneously from the perspective
of other threads. This is the strongest form of thread safety.

Example: @ref{676,,PyMutex_IsLocked()} performs an atomic read of the mutex
state and can be called from any thread at any time.

@node Thread safety for list objects,Thread safety for dict objects,Thread safety levels,Thread Safety Guarantees
@anchor{library/threadsafety thread-safety-for-list-objects}@anchor{292d}@anchor{library/threadsafety thread-safety-list}@anchor{280e}
@subsection Thread safety for list objects


Reading a single element from a @ref{4d9,,list} is
@ref{292c,,atomic}:

@example
lst[i]   # list.__getitem__
@end example

The following methods traverse the list and use @ref{292c,,atomic}
reads of each item to perform their function. That means that they may
return results affected by concurrent modifications:

@example
item in lst
lst.index(item)
lst.count(item)
@end example

All of the above operations avoid acquiring @ref{2927,,per-object locks}. They do not block concurrent modifications. Other
operations that hold a lock will not block these from observing intermediate
states.

All other operations from here on block using the @ref{2927,,per-object lock}.

Writing a single item via @code{lst[i] = x} is safe to call from multiple
threads and will not corrupt the list.

The following operations return new objects and appear
@ref{292c,,atomic} to other threads:

@example
lst1 + lst2    # concatenates two lists into a new list
x * lst        # repeats lst x times into a new list
lst.copy()     # returns a shallow copy of the list
@end example

The following methods that only operate on a single element with no shifting
required are @ref{292c,,atomic}:

@example
lst.append(x)  # append to the end of the list, no shifting required
lst.pop()      # pop element from the end of the list, no shifting required
@end example

The @ref{7f9,,clear()} method is also @ref{292c,,atomic}.
Other threads cannot observe elements being removed.

The @ref{f8d,,sort()} method is not @ref{292c,,atomic}.
Other threads cannot observe intermediate states during sorting, but the
list appears empty for the duration of the sort.

The following operations may allow @ref{292e,,lock-free} operations to observe
intermediate states since they modify multiple elements in place:

@example
lst.insert(idx, item)  # shifts elements
lst.pop(idx)           # idx not at the end of the list, shifts elements
lst *= x               # copies elements in place
@end example

The @ref{1c61,,remove()} method may allow concurrent modifications since
element comparison may execute arbitrary Python code (via
@ref{ec0,,__eq__()}).

@ref{7f8,,extend()} is safe to call from multiple threads.  However, its
guarantees depend on the iterable passed to it. If it is a @ref{4d9,,list}, a
@ref{1ce,,tuple}, a @ref{42b,,set}, a @ref{9d4,,frozenset}, a @ref{188,,dict} or a
@ref{289e,,dictionary view object} (but not their subclasses), the
@code{extend} operation is safe from concurrent modifications to the iterable.
Otherwise, an iterator is created which can be concurrently modified by
another thread.  The same applies to inplace concatenation of a list with
other iterables when using @code{lst += iterable}.

Similarly, assigning to a list slice with @code{lst[i:j] = iterable} is safe
to call from multiple threads, but @code{iterable} is only locked when it is
also a @ref{4d9,,list} (but not its subclasses).

Operations that involve multiple accesses, as well as iteration, are never
atomic. For example:

@example
# NOT atomic: read-modify-write
lst[i] = lst[i] + 1

# NOT atomic: check-then-act
if lst:
    item = lst.pop()

# NOT thread-safe: iteration while modifying
for item in lst:
    process(item)  # another thread may modify lst
@end example

Consider external synchronization when sharing @ref{4d9,,list} instances
across threads.

@node Thread safety for dict objects,Thread safety for set objects,Thread safety for list objects,Thread Safety Guarantees
@anchor{library/threadsafety thread-safety-dict}@anchor{289f}@anchor{library/threadsafety thread-safety-for-dict-objects}@anchor{292f}
@subsection Thread safety for dict objects


Creating a dictionary with the @ref{188,,dict} constructor is atomic when the
argument to it is a @code{dict} or a @ref{1ce,,tuple}. When using the
@ref{4da,,dict.fromkeys()} method, dictionary creation is atomic when the
argument is a @code{dict}, @code{tuple}, @ref{42b,,set} or
@ref{9d4,,frozenset}.

The following operations and functions are @ref{292e,,lock-free} and
@ref{292c,,atomic}.

@example
d[key]       # dict.__getitem__
d.get(key)   # dict.get
key in d     # dict.__contains__
len(d)       # dict.__len__
@end example

All other operations from here on hold the @ref{2927,,per-object lock}.

Writing or removing a single item is safe to call from multiple threads
and will not corrupt the dictionary:

@example
d[key] = value        # write
del d[key]            # delete
d.pop(key)            # remove and return
d.popitem()           # remove and return last item
d.setdefault(key, v)  # insert if missing
@end example

These operations may compare keys using @ref{ec0,,__eq__()}, which can
execute arbitrary Python code. During such comparisons, the dictionary may
be modified by another thread. For built-in types like @ref{1df,,str},
@ref{326,,int}, and @ref{327,,float}, that implement @code{__eq__()} in C,
the underlying lock is not released during comparisons and this is not a
concern.

The following operations return new objects and hold the @ref{2927,,per-object lock}
for the duration of the operation:

@example
d.copy()      # returns a shallow copy of the dictionary
d | other     # merges two dicts into a new dict
d.keys()      # returns a new dict_keys view object
d.values()    # returns a new dict_values view object
d.items()     # returns a new dict_items view object
@end example

The @ref{1954,,clear()} method holds the lock for its duration. Other
threads cannot observe elements being removed.

The following operations lock both dictionaries. For @ref{1807,,update()}
and @code{|=}, this applies only when the other operand is a @ref{188,,dict}
that uses the standard dict iterator (but not subclasses that override
iteration). For equality comparison, this applies to @code{dict} and
its subclasses:

@example
d.update(other_dict)  # both locked when other_dict is a dict
d |= other_dict       # both locked when other_dict is a dict
d == other_dict       # both locked for dict and subclasses
@end example

All comparison operations also compare values using @ref{ec0,,__eq__()},
so for non-built-in types the lock may be released during comparison.

@ref{4da,,fromkeys()} locks both the new dictionary and the iterable
when the iterable is exactly a @ref{188,,dict}, @ref{42b,,set}, or
@ref{9d4,,frozenset} (not subclasses):

@example
dict.fromkeys(a_dict)      # locks both
dict.fromkeys(a_set)       # locks both
dict.fromkeys(a_frozenset) # locks both
@end example

When updating from a non-dict iterable, only the target dictionary is
locked. The iterable may be concurrently modified by another thread:

@example
d.update(iterable)        # iterable is not a dict: only d locked
d |= iterable             # iterable is not a dict: only d locked
dict.fromkeys(iterable)   # iterable is not a dict/set/frozenset: only result locked
@end example

Operations that involve multiple accesses, as well as iteration, are never
atomic:

@example
# NOT atomic: read-modify-write
d[key] = d[key] + 1

# NOT atomic: check-then-act (TOCTOU)
if key in d:
    del d[key]

# NOT thread-safe: iteration while modifying
for key, value in d.items():
    process(key)  # another thread may modify d
@end example

To avoid time-of-check to time-of-use (TOCTOU) issues, use atomic
operations or handle exceptions:

@example
# Use pop() with default instead of check-then-delete
d.pop(key, None)

# Or handle the exception
try:
    del d[key]
except KeyError:
    pass
@end example

To safely iterate over a dictionary that may be modified by another
thread, iterate over a copy:

@example
# Make a copy to iterate safely
for key, value in d.copy().items():
    process(key)
@end example

Consider external synchronization when sharing @ref{188,,dict} instances
across threads.

@node Thread safety for set objects,Thread safety for bytearray objects,Thread safety for dict objects,Thread Safety Guarantees
@anchor{library/threadsafety thread-safety-for-set-objects}@anchor{2930}@anchor{library/threadsafety thread-safety-set}@anchor{289c}
@subsection Thread safety for set objects


The @ref{a1f,,len()} function is lock-free and @ref{292c,,atomic}.

The following read operation is lock-free. It does not block concurrent
modifications and may observe intermediate states from operations that
hold the per-object lock:

@example
elem in s    # set.__contains__
@end example

This operation may compare elements using @ref{ec0,,__eq__()}, which can
execute arbitrary Python code. During such comparisons, the set may be
modified by another thread. For built-in types like @ref{1df,,str},
@ref{326,,int}, and @ref{327,,float}, @code{__eq__()} does not release the
underlying lock during comparisons and this is not a concern.

All other operations from here on hold the per-object lock.

Adding or removing a single element is safe to call from multiple threads
and will not corrupt the set:

@example
s.add(elem)      # add element
s.remove(elem)   # remove element, raise if missing
s.discard(elem)  # remove element if present
s.pop()          # remove and return arbitrary element
@end example

These operations also compare elements, so the same @ref{ec0,,__eq__()}
considerations as above apply.

The @ref{2896,,copy()} method returns a new object and holds the per-object lock
for the duration so that it is always atomic.

The @ref{289b,,clear()} method holds the lock for its duration. Other
threads cannot observe elements being removed.

The following operations only accept @ref{42b,,set} or @ref{9d4,,frozenset}
as operands and always lock both objects:

@example
s |= other                   # other must be set/frozenset
s &= other                   # other must be set/frozenset
s -= other                   # other must be set/frozenset
s ^= other                   # other must be set/frozenset
s & other                    # other must be set/frozenset
s | other                    # other must be set/frozenset
s - other                    # other must be set/frozenset
s ^ other                    # other must be set/frozenset
@end example

@ref{2897,,set.update()}, @ref{2890,,set.union()}, @ref{1d80,,set.intersection()} and
@ref{2892,,set.difference()} can take multiple iterables as arguments. They all
iterate through all the passed iterables and do the following:

@quotation


@itemize *

@item 

@table @asis

@item @ref{2897,,set.update()} and @ref{2890,,set.union()} lock both objects only when

the other operand is a @ref{42b,,set}, @ref{9d4,,frozenset}, or @ref{188,,dict}.
@end table

@item 

@table @asis

@item @ref{1d80,,set.intersection()} and @ref{2892,,set.difference()} always try to lock

all objects.
@end table
@end itemize
@end quotation

@ref{2894,,set.symmetric_difference()} tries to lock both objects.

The update variants of the above methods also have some differences between
them:

@quotation


@itemize *

@item 

@table @asis

@item @ref{2898,,set.difference_update()} and @ref{1827,,set.intersection_update()} try

to lock all objects one-by-one.
@end table

@item 

@table @asis

@item @ref{1828,,set.symmetric_difference_update()} only locks the arguments if it is

of type @ref{42b,,set}, @ref{9d4,,frozenset}, or @ref{188,,dict}.
@end table
@end itemize
@end quotation

The following methods always try to lock both objects:

@example
s.isdisjoint(other)          # both locked
s.issubset(other)            # both locked
s.issuperset(other)          # both locked
@end example

Operations that involve multiple accesses, as well as iteration, are never
atomic:

@example
# NOT atomic: check-then-act
if elem in s:
      s.remove(elem)

# NOT thread-safe: iteration while modifying
for elem in s:
      process(elem)  # another thread may modify s
@end example

Consider external synchronization when sharing @ref{42b,,set} instances
across threads.  See @ref{2919,,Python support for free threading} for more information.

@node Thread safety for bytearray objects,Thread safety for memoryview objects,Thread safety for set objects,Thread Safety Guarantees
@anchor{library/threadsafety thread-safety-bytearray}@anchor{2853}@anchor{library/threadsafety thread-safety-for-bytearray-objects}@anchor{2931}
@subsection Thread safety for bytearray objects


@quotation

The @ref{a1f,,len()} function is lock-free and @ref{292c,,atomic}.

Concatenation and comparisons use the buffer protocol, which prevents
resizing but does not hold the per-object lock. These operations may
observe intermediate states from concurrent modifications:

@example
ba + other    # may observe concurrent writes
ba == other   # may observe concurrent writes
ba < other    # may observe concurrent writes
@end example

All other operations from here on hold the per-object lock.

Reading a single element or slice is safe to call from multiple threads:

@example
ba[i]        # bytearray.__getitem__
ba[i:j]      # slice
@end example

The following operations are safe to call from multiple threads and will
not corrupt the bytearray:

@example
ba[i] = x         # write single byte
ba[i:j] = values  # write slice
ba.append(x)      # append single byte
ba.extend(other)  # extend with iterable
ba.insert(i, x)   # insert single byte
ba.pop()          # remove and return last byte
ba.pop(i)         # remove and return byte at index
ba.remove(x)      # remove first occurrence
ba.reverse()      # reverse in place
ba.clear()        # remove all bytes
@end example

Slice assignment locks both objects when `values' is a @ref{1c6,,bytearray}:

@example
ba[i:j] = other_bytearray  # both locked
@end example

The following operations return new objects and hold the per-object lock
for the duration:

@example
ba.copy()     # returns a shallow copy
ba * n        # repeat into new bytearray
@end example

The membership test holds the lock for its duration:

@example
x in ba       # bytearray.__contains__
@end example

All other bytearray methods (such as @ref{1746,,find()},
@ref{285c,,replace()}, @ref{1999,,split()},
@ref{2859,,decode()}, etc.) hold the per-object lock for their
duration.

Operations that involve multiple accesses, as well as iteration, are never
atomic:

@example
# NOT atomic: check-then-act
if x in ba:
    ba.remove(x)

# NOT thread-safe: iteration while modifying
for byte in ba:
    process(byte)  # another thread may modify ba
@end example

To safely iterate over a bytearray that may be modified by another
thread, iterate over a copy:

@example
# Make a copy to iterate safely
for byte in ba.copy():
    process(byte)
@end example

Consider external synchronization when sharing @ref{1c6,,bytearray} instances
across threads.  See @ref{2919,,Python support for free threading} for more information.
@end quotation

@node Thread safety for memoryview objects,,Thread safety for bytearray objects,Thread Safety Guarantees
@anchor{library/threadsafety thread-safety-for-memoryview-objects}@anchor{2932}@anchor{library/threadsafety thread-safety-memoryview}@anchor{2606}
@subsection Thread safety for memoryview objects


@ref{1d2,,memoryview} objects provide access to the internal data of an
underlying object without copying. Thread safety depends on both the
memoryview itself and the underlying buffer exporter.

The memoryview implementation uses atomic operations to track its own
exports in the @ref{198,,free-threaded build}. Creating and
releasing a memoryview are thread-safe. Attribute access (e.g.,
@ref{2883,,shape}, @ref{287a,,format}) reads fields that
are immutable for the lifetime of the memoryview, so concurrent reads
are safe as long as the memoryview has not been released.

However, the actual data accessed through the memoryview is owned by the
underlying object. Concurrent access to this data is only safe if the
underlying object supports it:


@itemize *

@item 
For immutable objects like @ref{1c7,,bytes}, concurrent reads through
multiple memoryviews are safe.

@item 
For mutable objects like @ref{1c6,,bytearray}, reading and writing the
same memory region from multiple threads without external
synchronization is not safe and may result in data corruption.
Note that even read-only memoryviews of mutable objects do not
prevent data races if the underlying object is modified from
another thread.
@end itemize

@example
# NOT safe: concurrent writes to the same buffer
data = bytearray(1000)
view = memoryview(data)
# Thread 1: view[0:500] = b'x' * 500
# Thread 2: view[0:500] = b'y' * 500
@end example

@example
# Safe: use a lock for concurrent access
import threading
lock = threading.Lock()
data = bytearray(1000)
view = memoryview(data)

with lock:
    view[0:500] = b'x' * 500
@end example

Resizing or reallocating the underlying object (such as calling
@ref{1928,,bytearray.resize()}) while a memoryview is exported raises
@ref{1998,,BufferError}. This is enforced regardless of threading.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)
@anchor{library/text stringservices}@anchor{2841}
@node Text Processing Services,Υπηρεσίες Δυαδικών Δεδομένων,Thread Safety Guarantees,The Python Standard Library
@anchor{library/text doc}@anchor{2933}@anchor{library/text text-processing-services}@anchor{2934}@anchor{library/text textservices}@anchor{2844}@anchor{library/text translation-repo}@anchor{2935}
@section Text Processing Services


The modules described in this chapter provide a wide range of string
manipulation operations and other text processing services.

The @ref{1c,,codecs} module described under @ref{2936,,Υπηρεσίες Δυαδικών Δεδομένων} is also
highly relevant to text processing. In addition, see the documentation for
Python’s built-in string type in @ref{21cd,,Τύπος Ακολουθίας (Sequence) Κειμένου — str}.

@menu
* string — Common string operations:: 
* string.templatelib — Support for template string literals: string templatelib — Support for template string literals. 
* re — Regular expression operations:: 
* difflib — Helpers for computing deltas:: 
* textwrap — Περιτύλιγμα και γέμισμα κειμένου:: 
* unicodedata — Unicode Database:: 
* stringprep — Internet String Preparation:: 
* readline — GNU readline interface:: 
* rlcompleter — Completion function for GNU readline:: 

@end menu

@node string — Common string operations,string templatelib — Support for template string literals,,Text Processing Services
@anchor{library/string doc}@anchor{2937}@anchor{library/string module-string}@anchor{db}@anchor{library/string string-common-string-operations}@anchor{2938}
@subsection @code{string} — Common string operations


@geindex module; string

`Source code:' Lib/string/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/string/__init__.py}


__________________________________________________________________



@subsubheading Δείτε επίσης


@ref{21cd,,Τύπος Ακολουθίας (Sequence) Κειμένου — str}

@ref{21ce,,Μέθοδοι Συμβολοσειράς (String)}


@menu
* String constants:: 
* Custom string formatting:: 
* Format string syntax:: 
* Template strings ($-strings): Template strings $-strings. 
* Helper functions:: 

@end menu

@node String constants,Custom string formatting,,string — Common string operations
@anchor{library/string string-constants}@anchor{2939}
@subsubsection String constants


The constants defined in this module are:

@geindex ascii_letters (στη μονάδα string)
@anchor{library/string string ascii_letters}@anchor{1668}
@deffn {Δεδομένα} string.ascii_letters

The concatenation of the @ref{293a,,ascii_lowercase} and @ref{293b,,ascii_uppercase}
constants described below.  This value is not locale-dependent.
@end deffn

@geindex ascii_lowercase (στη μονάδα string)
@anchor{library/string string ascii_lowercase}@anchor{293a}
@deffn {Δεδομένα} string.ascii_lowercase

The lowercase letters @code{'abcdefghijklmnopqrstuvwxyz'}.  This value is not
locale-dependent and will not change.
@end deffn

@geindex ascii_uppercase (στη μονάδα string)
@anchor{library/string string ascii_uppercase}@anchor{293b}
@deffn {Δεδομένα} string.ascii_uppercase

The uppercase letters @code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.  This value is not
locale-dependent and will not change.
@end deffn

@geindex digits (στη μονάδα string)
@anchor{library/string string digits}@anchor{293c}
@deffn {Δεδομένα} string.digits

The string @code{'0123456789'}.
@end deffn

@geindex hexdigits (στη μονάδα string)
@anchor{library/string string hexdigits}@anchor{293d}
@deffn {Δεδομένα} string.hexdigits

The string @code{'0123456789abcdefABCDEF'}.
@end deffn

@geindex octdigits (στη μονάδα string)
@anchor{library/string string octdigits}@anchor{293e}
@deffn {Δεδομένα} string.octdigits

The string @code{'01234567'}.
@end deffn

@geindex punctuation (στη μονάδα string)
@anchor{library/string string punctuation}@anchor{293f}
@deffn {Δεδομένα} string.punctuation

String of ASCII characters which are considered punctuation characters
in the @code{C} locale: @code{!"#$%&'()*+,-./:;<=>?@@[\]^_`@{|@}~}.
@end deffn

@geindex printable (στη μονάδα string)
@anchor{library/string string printable}@anchor{1ad8}
@deffn {Δεδομένα} string.printable

String of ASCII characters which are considered printable by Python.
This is a combination of @ref{293c,,digits}, @ref{1668,,ascii_letters},
@ref{293f,,punctuation}, and @ref{2940,,whitespace}.

@cartouche
@quotation Σημείωση 
By design, @ref{1191,,string.printable.isprintable()}
returns @ref{ef5,,False}. In particular, @code{string.printable} is not
printable in the POSIX sense (see @code{LC_CTYPE@footnote{https://manpages.debian.org/locale(5)}}).
@end quotation
@end cartouche
@end deffn

@geindex whitespace (στη μονάδα string)
@anchor{library/string string whitespace}@anchor{2940}
@deffn {Δεδομένα} string.whitespace

A string containing all ASCII characters that are considered whitespace.
This includes the characters space, tab, linefeed, return, formfeed, and
vertical tab.
@end deffn

@node Custom string formatting,Format string syntax,String constants,string — Common string operations
@anchor{library/string custom-string-formatting}@anchor{2941}@anchor{library/string string-formatting}@anchor{2843}
@subsubsection Custom string formatting


The built-in string class provides the ability to do complex variable
substitutions and value formatting via the @ref{a12,,format()} method described in
@geindex Python Enhancement Proposals; PEP 3101
PEP 3101@footnote{https://peps.python.org/pep-3101/}.  The @ref{126b,,Formatter} class in the @code{string} module allows
you to create and customize your own string formatting behaviors using the same
implementation as the built-in @code{format()} method.

@geindex Formatter (κλάση σε string)
@anchor{library/string string Formatter}@anchor{126b}
@deffn {Κλάση} string.Formatter

The @code{Formatter} class has the following public methods:

@geindex format() (μέθοδος της string.Formatter)
@anchor{library/string string Formatter format}@anchor{fbf}
@deffn {Μέθοδος} format (format_string, /, *args, **kwargs)

The primary API method.  It takes a format string and
an arbitrary set of positional and keyword arguments.
It is just a wrapper that calls @ref{2942,,vformat()}.


Άλλαξε στην έκδοση 3.7: A format string argument is now @ref{e47,,positional-only}.

@end deffn

@geindex vformat() (μέθοδος της string.Formatter)
@anchor{library/string string Formatter vformat}@anchor{2942}
@deffn {Μέθοδος} vformat (format_string, args, kwargs)

This function does the actual work of formatting.  It is exposed as a
separate function for cases where you want to pass in a predefined
dictionary of arguments, rather than unpacking and repacking the
dictionary as individual arguments using the @code{*args} and @code{**kwargs}
syntax.  @code{vformat()} does the work of breaking up the format string
into character data and replacement fields.  It calls the various
methods described below.
@end deffn

In addition, the @code{Formatter} defines a number of methods that are
intended to be replaced by subclasses:

@geindex parse() (μέθοδος της string.Formatter)
@anchor{library/string string Formatter parse}@anchor{2943}
@deffn {Μέθοδος} parse (format_string)

Loop over the format_string and return an iterable of tuples
(`literal_text', `field_name', `format_spec', `conversion').  This is used
by @ref{2942,,vformat()} to break the string into either literal text, or
replacement fields.

The values in the tuple conceptually represent a span of literal text
followed by a single replacement field.  If there is no literal text
(which can happen if two replacement fields occur consecutively), then
`literal_text' will be a zero-length string.  If there is no replacement
field, then the values of `field_name', `format_spec' and `conversion'
will be @code{None}. The value of `field_name' is unmodified and
auto-numbering of non-numbered positional fields is done by @ref{2942,,vformat()}.
@end deffn

@geindex get_field() (μέθοδος της string.Formatter)
@anchor{library/string string Formatter get_field}@anchor{2944}
@deffn {Μέθοδος} get_field (field_name, args, kwargs)

Given `field_name', convert it to an object to be formatted.
Auto-numbering of `field_name' returned from @ref{2943,,parse()} is done by
@ref{2942,,vformat()} before calling this method.  Returns a tuple (obj, used_key).
The default version takes strings of the form defined in 
@geindex Python Enhancement Proposals; PEP 3101
PEP 3101@footnote{https://peps.python.org/pep-3101/},
such as «0[name]» or «label.title». `args' and `kwargs' are as passed in to
@code{vformat()}. The return value `used_key' has the same meaning
as the `key' parameter to @ref{2945,,get_value()}.
@end deffn

@geindex get_value() (μέθοδος της string.Formatter)
@anchor{library/string string Formatter get_value}@anchor{2945}
@deffn {Μέθοδος} get_value (key, args, kwargs)

Retrieve a given field value.  The `key' argument will be either an
integer or a string.  If it is an integer, it represents the index of the
positional argument in `args'; if it is a string, then it represents a
named argument in `kwargs'.

The `args' parameter is set to the list of positional arguments to
@ref{2942,,vformat()}, and the `kwargs' parameter is set to the dictionary of
keyword arguments.

For compound field names, these functions are only called for the first
component of the field name; subsequent components are handled through
normal attribute and indexing operations.

So for example, the field expression “0.name” would cause
@code{get_value()} to be called with a `key' argument of 0.  The @code{name}
attribute will be looked up after @code{get_value()} returns by calling the
built-in @ref{f8f,,getattr()} function.

If the index or keyword refers to an item that does not exist, then an
@ref{18d7,,IndexError} or @ref{7df,,KeyError} should be raised.
@end deffn

@geindex check_unused_args() (μέθοδος της string.Formatter)
@anchor{library/string string Formatter check_unused_args}@anchor{2946}
@deffn {Μέθοδος} check_unused_args (used_args, args, kwargs)

Implement checking for unused arguments if desired.  The arguments to this
function is the set of all argument keys that were actually referred to in
the format string (integers for positional arguments, and strings for
named arguments), and a reference to the `args' and `kwargs' that was
passed to vformat.  The set of unused args can be calculated from these
parameters.  @code{check_unused_args()} is assumed to raise an exception if
the check fails.
@end deffn

@geindex format_field() (μέθοδος της string.Formatter)
@anchor{library/string string Formatter format_field}@anchor{2947}
@deffn {Μέθοδος} format_field (value, format_spec)

@code{format_field()} simply calls the global @ref{439,,format()} built-in.  The
method is provided so that subclasses can override it.
@end deffn

@geindex convert_field() (μέθοδος της string.Formatter)
@anchor{library/string string Formatter convert_field}@anchor{2948}
@deffn {Μέθοδος} convert_field (value, conversion)

Converts the value (returned by @ref{2944,,get_field()}) given a conversion type
(as in the tuple returned by the @ref{2943,,parse()} method).  The default
version understands “s” (str), “r” (repr) and “a” (ascii) conversion
types.
@end deffn
@end deffn

@node Format string syntax,Template strings $-strings,Custom string formatting,string — Common string operations
@anchor{library/string format-string-syntax}@anchor{2949}@anchor{library/string formatstrings}@anchor{173f}
@subsubsection Format string syntax


The @ref{a12,,str.format()} method and the @ref{126b,,Formatter} class share the same
syntax for format strings (although in the case of @code{Formatter},
subclasses can define their own format string syntax).  The syntax is
related to that of @ref{43a,,formatted string literals} and
@ref{1a50,,template string literals}, but it is less sophisticated
and, in particular, does not support arbitrary expressions in interpolations.

@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

Format strings contain «replacement fields» surrounded by curly braces @code{@{@}}.
Anything that is not contained in braces is considered literal text, which is
copied unchanged to the output.  If you need to include a brace character in the
literal text, it can be escaped by doubling: @code{@{@{} and @code{@}@}}.

The grammar for a replacement field is as follows:

@example
@anchor{library/string grammar-token-format-string-replacement_field}@anchor{294a}replacement_field: "@{" [@ref{294b,,field_name}] ["!" @ref{294c,,conversion}] [":" @ref{294d,,format_spec}] "@}"
@anchor{library/string grammar-token-format-string-field_name}@anchor{294b}field_name:        @ref{294e,,arg_name} ("." @ref{294f,,attribute_name} | "[" @ref{2950,,element_index} "]")*
@anchor{library/string grammar-token-format-string-arg_name}@anchor{294e}arg_name:          [@ref{24b2,,identifier} | @ref{2503,,digit}+]
@anchor{library/string grammar-token-format-string-attribute_name}@anchor{294f}attribute_name:    @ref{24b2,,identifier}
@anchor{library/string grammar-token-format-string-element_index}@anchor{2950}element_index:     @ref{2503,,digit}+ | @ref{2951,,index_string}
@anchor{library/string grammar-token-format-string-index_string}@anchor{2951}index_string:      <any source character except "]"> +
@anchor{library/string grammar-token-format-string-conversion}@anchor{294c}conversion:        "r" | "s" | "a"
@anchor{library/string grammar-token-format-string-format_spec}@anchor{294d}format_spec:       @ref{2952,,format-spec;format_spec}
@end example

In less formal terms, the replacement field can start with a `field_name' that specifies
the object whose value is to be formatted and inserted
into the output instead of the replacement field.
The `field_name' is optionally followed by a  `conversion' field, which is
preceded by an exclamation point @code{'!'}, and a `format_spec', which is preceded
by a colon @code{':'}.  These specify a non-default format for the replacement value.

See also the @ref{6fe,,Format specification mini-language} section.

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{2821,,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{f8f,,getattr()}, while an expression of the form @code{'[index]'}
does an index lookup using @ref{787,,__getitem__()}.


Άλλαξε στην έκδοση 3.1: The positional argument specifiers can be omitted for @ref{a12,,str.format()},
so @code{'@{@} @{@}'.format(a, b)} is equivalent to @code{'@{0@} @{1@}'.format(a, b)}.



Άλλαξε στην έκδοση 3.4: The positional argument specifiers can be omitted for @ref{126b,,Formatter}.


Some simple format string examples:

@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
@anchor{library/string formatstrings-conversion}@anchor{2953}
The `conversion' field causes a type coercion before formatting.  Normally, the
job of formatting a value is done by the @ref{a10,,__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 @code{__format__()}, the normal formatting logic
is bypassed.

Three conversion flags are currently supported: @code{'!s'} which calls @ref{1df,,str()}
on the value, @code{'!r'} which calls @ref{45b,,repr()} and @code{'!a'} which calls
@ref{1789,,ascii()}.

Some examples:

@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

The `format_spec' field contains a specification of how the value should be
presented, including such details as field width, alignment, padding, decimal
precision and so on.  Each value type can define its own «formatting
mini-language» or interpretation of the `format_spec'.

Most built-in types support a common formatting mini-language, which is
described in the next section.

A `format_spec' field can also include nested replacement fields within it.
These nested replacement fields may contain a field name, conversion flag
and format specification, but deeper nesting is
not allowed.  The replacement fields within the
format_spec are substituted before the `format_spec' string is interpreted.
This allows the formatting of a value to be dynamically specified.

See the @ref{2954,,Format examples} section for some examples.

@menu
* Format specification mini-language:: 
* Format examples:: 

@end menu

@node Format specification mini-language,Format examples,,Format string syntax
@anchor{library/string format-specification-mini-language}@anchor{2955}@anchor{library/string formatspec}@anchor{6fe}
@subsubsection Format specification mini-language


«Format specifications» are used within replacement fields contained within a
format string to define how individual values are presented (see
@ref{173f,,Format string syntax}, @ref{43a,,f-strings}, and @ref{1a50,,t-strings}).
They can also be passed directly to the built-in
@ref{439,,format()} function.  Each formattable type may define how the format
specification is to be interpreted.

Most built-in types implement the following options for format specifications,
although some of the formatting options are only supported by the numeric types.

A general convention is that an empty format specification produces
the same result as if you had called @ref{1df,,str()} on the value. A
non-empty format specification typically modifies the result.

The general form of a `standard format specifier' is:

@example
@anchor{library/string grammar-token-format-spec-format_spec}@anchor{2952}format_spec:             [@ref{2956,,options}][@ref{2957,,width_and_precision}][@ref{2958,,type}]
@anchor{library/string grammar-token-format-spec-options}@anchor{2956}options:                 [[@ref{2959,,fill}]@ref{295a,,align}][@ref{295b,,sign}]["z"]["#"]["0"]
@anchor{library/string grammar-token-format-spec-fill}@anchor{2959}fill:                    <any character>
@anchor{library/string grammar-token-format-spec-align}@anchor{295a}align:                   "<" | ">" | "=" | "^"
@anchor{library/string grammar-token-format-spec-sign}@anchor{295b}sign:                    "+" | "-" | " "
@anchor{library/string grammar-token-format-spec-width_and_precision}@anchor{2957}width_and_precision:     [@ref{295c,,width_with_grouping}][@ref{295d,,precision_with_grouping}]
@anchor{library/string grammar-token-format-spec-width_with_grouping}@anchor{295c}width_with_grouping:     [@ref{295e,,width}][@ref{295f,,grouping}]
@anchor{library/string grammar-token-format-spec-precision_with_grouping}@anchor{295d}precision_with_grouping: "." [@ref{2960,,precision}][@ref{295f,,grouping}] | "." @ref{295f,,grouping}
@anchor{library/string grammar-token-format-spec-width}@anchor{295e}width:                   @ref{2503,,digit}+
@anchor{library/string grammar-token-format-spec-precision}@anchor{2960}precision:               @ref{2503,,digit}+
@anchor{library/string grammar-token-format-spec-grouping}@anchor{295f}grouping:                "," | "_"
@anchor{library/string grammar-token-format-spec-type}@anchor{2958}type:                    "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g"
                         | "G" | "n" | "o" | "s" | "x" | "X" | "%"
@end example

If a valid `align' value is specified, it can be preceded by a `fill'
character that can be any character and defaults to a space if omitted.
It is not possible to use a literal curly brace (»@code{@{}» or «@code{@}}») as
the `fill' character in a @ref{43a,,formatted string literal} or when using the @ref{a12,,str.format()}
method.  However, it is possible to insert a curly brace
with a nested replacement field.  This limitation doesn’t
affect the @ref{439,,format()} function.

The meaning of the various alignment options is as follows:

@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

Meaning

@item

@code{'<'}

@tab

Forces the field to be left-aligned within the available
space (this is the default for most objects).

@item

@code{'>'}

@tab

Forces the field to be right-aligned within the
available space (this is the default for numbers).

@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{328,,complex}.
It becomes the default for numbers when “0” immediately
precedes the field width.

@item

@code{'^'}

@tab

Forces the field to be centered within the available
space.

@end multitable


Note that unless a minimum field width is defined, the field width will always
be the same size as the data to fill it, so that the alignment option has no
meaning in this case.

The `sign' option is only valid for number types, and can be one of the
following:

@geindex + (plus);in string formatting
@geindex - (minus);in string formatting
@geindex space;in string formatting


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Meaning

@item

@code{'+'}

@tab

Indicates that a sign should be used for both
positive as well as negative numbers.

@item

@code{'-'}

@tab

Indicates that a sign should be used only for negative
numbers (this is the default behavior).

@item

space

@tab

Indicates that a leading space should be used on
positive numbers, and a minus sign on negative numbers.

@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.


Άλλαξε στην έκδοση 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

The @code{'#'} option causes the «alternate form» to be used for the
conversion.  The alternate form is defined differently for different
types.  This option is only valid for integer, float and complex
types. For integers, when binary, octal, or hexadecimal output
is used, this option adds the respective prefix @code{'0b'}, @code{'0o'},
@code{'0x'}, or @code{'0X'} to the output value. For float and complex the
alternate form causes the result of the conversion to always contain a
decimal-point character, even if no digits follow it. Normally, a
decimal-point character appears in the result of these conversions
only if a digit follows it. In addition, for @code{'g'} and @code{'G'}
conversions, trailing zeros are not removed from the result.

The `width' is a decimal integer defining the minimum total field width,
including any prefixes, separators, and other formatting characters.
If not specified, then the field width will be determined by the content.

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{328,,complex}.  This is equivalent to a `fill' character of
@code{'0'} with an `alignment' type of @code{'='}.


Άλλαξε στην έκδοση 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.

The `grouping' option after `width' and `precision' fields specifies
a digit group separator for the integral and fractional parts
of a number respectively. It can be one of the following:

@geindex @comma{} (comma);in string formatting
@geindex _ (underscore);in string formatting


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Meaning

@item

@code{','}

@tab

Inserts a comma every 3 digits for
integer presentation type @code{'d'} and
floating-point presentation types, excluding @code{'n'}.
For other presentation types,
this option is not supported.

@item

@code{'_'}

@tab

Inserts an underscore every 3 digits for
integer presentation type @code{'d'} and
floating-point presentation types, excluding @code{'n'}.
For integer presentation types
@code{'b'}, @code{'o'}, @code{'x'}, and @code{'X'},
underscores are inserted every 4 digits.
For other presentation types,
this option is not supported.

@end multitable


For a locale aware separator, use the @code{'n'} presentation type instead.


Άλλαξε στην έκδοση 3.1: Added the @code{','} option (see also 
@geindex Python Enhancement Proposals; PEP 378
PEP 378@footnote{https://peps.python.org/pep-0378/}).



Άλλαξε στην έκδοση 3.6: Added the @code{'_'} option (see also 
@geindex Python Enhancement Proposals; PEP 515
PEP 515@footnote{https://peps.python.org/pep-0515/}).



Άλλαξε στην έκδοση 3.14: Support the `grouping' option for the fractional part.


Finally, the `type' determines how the data should be presented.

The available string presentation types are:

@quotation


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Type

@tab

Meaning

@item

@code{'s'}

@tab

String format. This is the default type for strings and
may be omitted.

@item

None

@tab

The same as @code{'s'}.

@end multitable

@end quotation

The available integer presentation types are:

@quotation


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Type

@tab

Meaning

@item

@code{'b'}

@tab

Binary format. Outputs the number in base 2.

@item

@code{'c'}

@tab

Character. Converts the integer to the corresponding
unicode character before printing.

@item

@code{'d'}

@tab

Decimal Integer. Outputs the number in base 10.

@item

@code{'o'}

@tab

Octal format. Outputs the number in base 8.

@item

@code{'x'}

@tab

Hex format. Outputs the number in base 16, using
lower-case letters for the digits above 9.

@item

@code{'X'}

@tab

Hex format. Outputs the number in base 16, using
upper-case letters for the digits above 9.
In case @code{'#'} is specified, the prefix @code{'0x'} will
be upper-cased to @code{'0X'} as well.

@item

@code{'n'}

@tab

Number. This is the same as @code{'d'}, except that it uses
the current locale setting to insert the appropriate
digit group separators.

@item

None

@tab

The same as @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{327,,float()} is used to convert the
integer to a floating-point number before formatting.

The available presentation types for @ref{327,,float} and
@ref{1c2,,Decimal} values are:

@quotation


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Type

@tab

Meaning

@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{327,,float}, and shows all coefficient digits
for @ref{1c2,,Decimal}.  If @code{p=0}, the decimal
point is omitted unless the @code{#} option is used.

For @ref{327,,float}, the exponent always contains at
least two digits, and is zero if the value is zero.

@item

@code{'E'}

@tab

Scientific notation. Same as @code{'e'} except it uses
an upper case “E” as the separator character.

@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{327,,float}, and uses a
precision large enough to show all coefficient digits
for @ref{1c2,,Decimal}.  If @code{p=0}, the decimal
point is omitted unless the @code{#} option is used.

@item

@code{'F'}

@tab

Fixed-point notation. Same as @code{'f'}, but converts
@code{nan} to  @code{NAN} and @code{inf} to @code{INF}.

@item

@code{'g'}

@tab

General format.  For a given precision @code{p >= 1},
this rounds the number to @code{p} significant digits and
then formats the result in either fixed-point format
or in scientific notation, depending on its magnitude.
A precision of @code{0} is treated as equivalent to a
precision of @code{1}.

The precise rules are as follows: suppose that the
result formatted with presentation type @code{'e'} and
precision @code{p-1} would have exponent @code{exp}.  Then,
if @code{m <= exp < p}, where @code{m} is -4 for floats and -6
for @ref{1c2,,Decimals}, the number is
formatted with presentation type @code{'f'} and precision
@code{p-1-exp}.  Otherwise, the number is formatted
with presentation type @code{'e'} and precision @code{p-1}.
In both cases insignificant trailing zeros are removed
from the significand, and the decimal point is also
removed if there are no remaining digits following it,
unless the @code{'#'} option is used.

With no precision given, uses a precision of @code{6}
significant digits for @ref{327,,float}. For
@ref{1c2,,Decimal}, the coefficient of the result
is formed from the coefficient digits of the value;
scientific notation is used for values smaller than
@code{1e-6} in absolute value and values where the place
value of the least significant digit is larger than 1,
and fixed-point notation is used otherwise.

Positive and negative infinity, positive and negative
zero, and nans, are formatted as @code{inf}, @code{-inf},
@code{0}, @code{-0} and @code{nan} respectively, regardless of
the precision.

@item

@code{'G'}

@tab

General format. Same as @code{'g'} except switches to
@code{'E'} if the number gets too large. The
representations of infinity and NaN are uppercased, too.

@item

@code{'n'}

@tab

Number. This is the same as @code{'g'}, except that it uses
the current locale setting to insert the appropriate
digit group separators
for the integral part of a number.

@item

@code{'%'}

@tab

Percentage. Multiplies the number by 100 and displays
in fixed (@code{'f'}) format, followed by a percent sign.

@item

None

@tab

For @ref{327,,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.

For @ref{1c2,,Decimal}, this is the same as
either @code{'g'} or @code{'G'} depending on the value of
@code{context.capitals} for the current decimal context.

The overall effect is to match the output of @ref{1df,,str()}
as altered by the other format modifiers.

@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{327,,float} matches that
of the @ref{167f,,round()} builtin.  For @ref{1c2,,Decimal}, the rounding
mode of the current @ref{2961,,context} will be used.

The available presentation types for @ref{328,,complex} are the same as those for
@ref{327,,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{1df,,str()} (complex numbers with
a non-zero real part are also surrounded by parentheses), possibly altered by
other format modifiers.

@node Format examples,,Format specification mini-language,Format string syntax
@anchor{library/string format-examples}@anchor{2962}@anchor{library/string formatexamples}@anchor{2954}
@subsubsection Format examples


This section contains examples of the @ref{a12,,str.format()} syntax and
comparison with the old @code{%}-formatting.

In most of the cases the syntax is similar to the old @code{%}-formatting, with the
addition of the @code{@{@}} and with @code{:} used instead of @code{%}.
For example, @code{'%03.2f'} can be translated to @code{'@{:03.2f@}'}.

The new format syntax also supports new and different options, shown in the
following examples.

Accessing arguments by 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

Accessing arguments by name:

@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

Accessing arguments” attributes:

@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

Accessing arguments” items:

@example
>>> coord = (3, 5)
>>> 'X: @{0[0]@};  Y: @{0[1]@}'.format(coord)
'X: 3;  Y: 5'
@end example

Replacing @code{%s} and @code{%r}:

@example
>>> "repr() shows quotes: @{!r@}; str() doesn't: @{!s@}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"
@end example

Aligning the text and specifying a width:

@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

Replacing @code{%+f}, @code{%-f}, and @code{% f} and specifying a sign:

@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

Replacing @code{%x} and @code{%o} and converting the value to different 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

Using the comma or the underscore as a digit group separator:

@example
>>> '@{:,@}'.format(1234567890)
'1,234,567,890'
>>> '@{:_@}'.format(1234567890)
'1_234_567_890'
>>> '@{:_b@}'.format(1234567890)
'100_1001_1001_0110_0000_0010_1101_0010'
>>> '@{:_x@}'.format(1234567890)
'4996_02d2'
>>> '@{:_@}'.format(123456789.123456789)
'123_456_789.12345679'
>>> '@{:.,@}'.format(123456789.123456789)
'123456789.123,456,79'
>>> '@{:,._@}'.format(123456789.123456789)
'123,456,789.123_456_79'
@end example

Expressing a percentage:

@example
>>> points = 19
>>> total = 22
>>> 'Correct answers: @{:.2%@}'.format(points/total)
'Correct answers: 86.36%'
@end example

Using type-specific formatting:

@example
>>> import datetime as dt
>>> d = dt.datetime(2010, 7, 4, 12, 15, 58)
>>> '@{:%Y-%m-%d %H:%M:%S@}'.format(d)
'2010-07-04 12:15:58'
@end example

Nesting arguments and more complex examples:

@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 Template strings $-strings,Helper functions,Format string syntax,string — Common string operations
@anchor{library/string template-strings-pep292}@anchor{2963}@anchor{library/string template-strings-strings}@anchor{2964}
@subsubsection Template strings ($-strings)


@cartouche
@quotation Σημείωση 
The feature described here was introduced in Python 2.4;
a simple templating method based upon regular expressions.
It predates @ref{a12,,str.format()}, @ref{43a,,formatted string literals},
and @ref{2965,,template string literals}.

It is unrelated to template string literals (t-strings),
which were introduced in Python 3.14.
These evaluate to  @ref{415,,string.templatelib.Template} objects,
found in the @ref{dc,,string.templatelib} module.
@end quotation
@end cartouche

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

Template strings support @code{$}-based substitutions, using the following rules:


@itemize *

@item 
@code{$$} is an escape; it is replaced with a single @code{$}.

@item 
@code{$identifier} names a substitution placeholder matching a mapping key of
@code{"identifier"}.  By default, @code{"identifier"} is restricted to any
case-insensitive ASCII alphanumeric string (including underscores) that
starts with an underscore or ASCII letter.  The first non-identifier
character after the @code{$} character terminates this placeholder
specification.

@item 
@code{$@{identifier@}} is equivalent to @code{$identifier}.  It is required when
valid identifier characters follow the placeholder but are not part of the
placeholder, such as @code{"$@{noun@}ification"}.
@end itemize

Any other appearance of @code{$} in the string will result in a @ref{277,,ValueError}
being raised.

The @code{string} module provides a @ref{a77,,Template} class that implements
these rules.  The methods of @code{Template} are:

@geindex Template (κλάση σε string)
@anchor{library/string string Template}@anchor{a77}
@deffn {Κλάση} string.Template (template)

The constructor takes a single argument which is the template string.

@geindex substitute() (μέθοδος της string.Template)
@anchor{library/string string Template substitute}@anchor{22c5}
@deffn {Μέθοδος} substitute (mapping=@{@}, /, **kwds)

Performs the template substitution, returning a new string.  `mapping' is
any dictionary-like object with keys that match the placeholders in the
template.  Alternatively, you can provide keyword arguments, where the
keywords are the placeholders.  When both `mapping' and `kwds' are given
and there are duplicates, the placeholders from `kwds' take precedence.
@end deffn

@geindex safe_substitute() (μέθοδος της string.Template)
@anchor{library/string string Template safe_substitute}@anchor{22c6}
@deffn {Μέθοδος} safe_substitute (mapping=@{@}, /, **kwds)

Like @ref{22c5,,substitute()}, except that if placeholders are missing from
`mapping' and `kwds', instead of raising a @ref{7df,,KeyError} exception, the
original placeholder will appear in the resulting string intact.  Also,
unlike with @code{substitute()}, any other appearances of the @code{$} will
simply return @code{$} instead of raising @ref{277,,ValueError}.

While other exceptions may still occur, this method is called «safe»
because it always tries to return a usable string instead of
raising an exception.  In another sense, @code{safe_substitute()} may be
anything other than safe, since it will silently ignore malformed
templates containing dangling delimiters, unmatched braces, or
placeholders that are not valid Python identifiers.
@end deffn

@geindex is_valid() (μέθοδος της string.Template)
@anchor{library/string string Template is_valid}@anchor{a76}
@deffn {Μέθοδος} is_valid ()

Returns @code{False} if the template has invalid placeholders that will cause
@ref{22c5,,substitute()} to raise @ref{277,,ValueError}.


Added in version 3.11.

@end deffn

@geindex get_identifiers() (μέθοδος της string.Template)
@anchor{library/string string Template get_identifiers}@anchor{a75}
@deffn {Μέθοδος} get_identifiers ()

Returns a list of the valid identifiers in the template, in the order
they first appear, ignoring any invalid identifiers.


Added in version 3.11.

@end deffn

@code{Template} instances also provide one public data attribute:

@geindex template (ιδιότητα της string.Template)
@anchor{library/string string Template template}@anchor{2966}
@deffn {Ιδιότητα} template

This is the object passed to the constructor’s `template' argument.  In
general, you shouldn’t change it, but read-only access is not enforced.
@end deffn
@end deffn

Here is an example of how to use a 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

Advanced usage: you can derive subclasses of @ref{a77,,Template} to customize
the placeholder syntax, delimiter character, or the entire regular expression
used to parse template strings.  To do this, you can override these class
attributes:


@itemize *

@item 
`delimiter' – This is the literal string describing a placeholder
introducing delimiter.  The default value is @code{$}.  Note that this should
`not' be a regular expression, as the implementation will call
@ref{fc8,,re.escape()} on this string as needed.  Note further that you cannot
change the delimiter after class creation (i.e. a different delimiter must
be set in the subclass’s class namespace).

@item 
`idpattern' – This is the regular expression describing the pattern for
non-braced placeholders.  The default value is the regular expression
@code{(?a:[_a-z][_a-z0-9]*)}.  If this is given and `braceidpattern' is
@code{None} this pattern will also apply to braced placeholders.

@cartouche
@quotation Σημείωση 
Since default `flags' is @code{re.IGNORECASE}, pattern @code{[a-z]} can match
with some non-ASCII characters. That’s why we use the local @code{a} flag
here.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.7: `braceidpattern' can be used to define separate patterns used inside and
outside the braces.


@item 
`braceidpattern' – This is like `idpattern' but describes the pattern for
braced placeholders.  Defaults to @code{None} which means to fall back to
`idpattern' (i.e. the same pattern is used both inside and outside braces).
If given, this allows you to define different patterns for braced and
unbraced placeholders.


Added in version 3.7.


@item 
`flags' – The regular expression flags that will be applied when compiling
the regular expression used for recognizing substitutions.  The default value
is @code{re.IGNORECASE}.  Note that @code{re.VERBOSE} will always be added to the
flags, so custom `idpattern's must follow conventions for verbose regular
expressions.


Added in version 3.2.

@end itemize

Alternatively, you can provide the entire regular expression pattern by
overriding the class attribute `pattern'.  If you do this, the value must be a
regular expression object with four named capturing groups.  The capturing
groups correspond to the rules given above, along with the invalid placeholder
rule:


@itemize *

@item 
`escaped' – This group matches the escape sequence, e.g. @code{$$}, in the
default pattern.

@item 
`named' – This group matches the unbraced placeholder name; it should not
include the delimiter in capturing group.

@item 
`braced' – This group matches the brace enclosed placeholder name; it should
not include either the delimiter or braces in the capturing group.

@item 
`invalid' – This group matches any other delimiter pattern (usually a single
delimiter), and it should appear last in the regular expression.
@end itemize

The methods on this class will raise @ref{277,,ValueError} if the pattern matches
the template without one of these named groups matching.

@node Helper functions,,Template strings $-strings,string — Common string operations
@anchor{library/string helper-functions}@anchor{2967}
@subsubsection Helper functions


@geindex capwords() (στη μονάδα string)
@anchor{library/string string capwords}@anchor{2848}
@deffn {Συνάρτηση} string.capwords (s, sep=None)

Split the argument into words using @ref{125b,,str.split()}, capitalize each word
using @ref{2832,,str.capitalize()}, and join the capitalized words using
@ref{2803,,str.join()}.  If the optional second argument `sep' is absent
or @code{None}, runs of whitespace characters are replaced by a single space
and leading and trailing whitespace are removed, otherwise `sep' is used to
split and join the words.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node string templatelib — Support for template string literals,re — Regular expression operations,string — Common string operations,Text Processing Services
@anchor{library/string templatelib doc}@anchor{2968}@anchor{library/string templatelib module-string templatelib}@anchor{dc}@anchor{library/string templatelib string-templatelib-support-for-template-string-literals}@anchor{2969}@anchor{library/string templatelib translation-repo}@anchor{296a}
@subsection @code{string.templatelib} — Support for template string literals


@geindex module; string.templatelib

`Source code:' Lib/string/templatelib.py@footnote{https://github.com/python/cpython/tree/main/Lib/string/templatelib.py}


__________________________________________________________________



@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{43a,,Format strings}

@item 
@ref{1a50,,Template string literal (t-string) syntax}

@item 
@geindex Python Enhancement Proposals; PEP 750
PEP 750@footnote{https://peps.python.org/pep-0750/}
@end itemize


@menu
* Template strings:: 
* Types:: 
* Helper functions: Helper functions<2>. 

@end menu

@node Template strings,Types,,string templatelib — Support for template string literals
@anchor{library/string templatelib id1}@anchor{296b}@anchor{library/string templatelib template-strings}@anchor{2965}
@subsubsection Template strings



Added in version 3.14.


Template strings are a mechanism for custom string processing.
They have the full flexibility of Python’s @ref{43a,,f-strings},
but return a @ref{415,,Template} instance that gives access
to the static and interpolated (in curly brackets) parts of a string
`before' they are combined.

To write a t-string, use a @code{'t'} prefix instead of an @code{'f'}, like so:

@example
>>> pi = 3.14
>>> t't-strings are new in Python @{pi!s@}!'
Template(
   strings=('t-strings are new in Python ', '!'),
   interpolations=(Interpolation(3.14, 'pi', 's', '@w{'}),)
)
@end example

@node Types,Helper functions<2>,Template strings,string templatelib — Support for template string literals
@anchor{library/string templatelib types}@anchor{296c}
@subsubsection Types


@geindex Template (κλάση σε string.templatelib)
@anchor{library/string templatelib string templatelib Template}@anchor{415}
@deffn {Κλάση} string.templatelib.Template

The @code{Template} class describes the contents of a template string.
It is immutable, meaning that attributes of a template cannot be reassigned.

The most common way to create a @code{Template} instance is to use the
@ref{1a50,,template string literal syntax}.
This syntax is identical to that of @ref{43a,,f-strings},
except that it uses a @code{t} prefix in place of an @code{f}:

@example
>>> cheese = 'Red Leicester'
>>> template = t"We're fresh out of @{cheese@}, sir."
>>> type(template)
<class 'string.templatelib.Template'>
@end example

Templates are stored as sequences of literal @ref{296d,,strings}
and dynamic @ref{296e,,interpolations}.
A @ref{296f,,values} attribute holds the values of the interpolations:

@example
>>> cheese = 'Camembert'
>>> template = t'Ah! We do have @{cheese@}.'
>>> template.strings
('Ah! We do have ', '.')
>>> template.interpolations
(Interpolation('Camembert', ...),)
>>> template.values
('Camembert',)
@end example

The @code{strings} tuple has one more element than @code{interpolations}
and @code{values}; the interpolations “belong” between the strings.
This may be easier to understand when tuples are aligned

@example
template.strings:  ('Ah! We do have ',              '.')
template.values:   (                   'Camembert',    )
@end example

@subsubheading Attributes


@geindex strings (ιδιότητα της string.templatelib.Template)
@anchor{library/string templatelib string templatelib Template strings}@anchor{296d}
@deffn {Ιδιότητα} strings: @ref{1ce,,tuple}[@ref{1df,,str}, ...]

A @ref{1ce,,tuple} of the static strings in the template.

@example
>>> cheese = 'Camembert'
>>> template = t'Ah! We do have @{cheese@}.'
>>> template.strings
('Ah! We do have ', '.')
@end example

Empty strings `are' included in the tuple:

@example
>>> response = 'We do have '
>>> cheese = 'Camembert'
>>> template = t'Ah! @{response@}@{cheese@}.'
>>> template.strings
('Ah! ', '@w{'}, '.')
@end example

The @code{strings} tuple is never empty, and always contains one more
string than the @code{interpolations} and @code{values} tuples:

@example
>>> t'@w{'}.strings
('@w{'},)
>>> t'@w{'}.values
()
>>> t'@{'cheese'@}'.strings
('@w{'}, '@w{'})
>>> t'@{'cheese'@}'.values
('cheese',)
@end example
@end deffn

@geindex interpolations (ιδιότητα της string.templatelib.Template)
@anchor{library/string templatelib string templatelib Template interpolations}@anchor{296e}
@deffn {Ιδιότητα} interpolations: @ref{1ce,,tuple}[@ref{416,,Interpolation}, ...]

A @ref{1ce,,tuple} of the interpolations in the template.

@example
>>> cheese = 'Camembert'
>>> template = t'Ah! We do have @{cheese@}.'
>>> template.interpolations
(Interpolation('Camembert', 'cheese', None, '@w{'}),)
@end example

The @code{interpolations} tuple may be empty and always contains one fewer
values than the @code{strings} tuple:

@example
>>> t'Red Leicester'.interpolations
()
@end example
@end deffn

@geindex values (ιδιότητα της string.templatelib.Template)
@anchor{library/string templatelib string templatelib Template values}@anchor{296f}
@deffn {Ιδιότητα} values: @ref{1ce,,tuple}[@ref{e4d,,object}, ...]

A tuple of all interpolated values in the template.

@example
>>> cheese = 'Camembert'
>>> template = t'Ah! We do have @{cheese@}.'
>>> template.values
('Camembert',)
@end example

The @code{values} tuple always has the same length as the
@code{interpolations} tuple. It is always equivalent to
@code{tuple(i.value for i in template.interpolations)}.
@end deffn

@subsubheading Methods


@geindex __new__() (μέθοδος της string.templatelib.Template)
@anchor{library/string templatelib string templatelib Template __new__}@anchor{2970}
@deffn {Μέθοδος} __new__ (*args: str | Interpolation)

While literal syntax is the most common way to create a @code{Template},
it is also possible to create them directly using the constructor:

@example
>>> from string.templatelib import Interpolation, Template
>>> cheese = 'Camembert'
>>> template = Template(
...     'Ah! We do have ', Interpolation(cheese, 'cheese'), '.'
... )
>>> list(template)
['Ah! We do have ', Interpolation('Camembert', 'cheese', None, '@w{'}), '.']
@end example

If multiple strings are passed consecutively, they will be concatenated
into a single value in the @ref{296d,,strings} attribute. For example,
the following code creates a @code{Template} with a single final string:

@example
>>> from string.templatelib import Template
>>> template = Template('Ah! We do have ', 'Camembert', '.')
>>> template.strings
('Ah! We do have Camembert.',)
@end example

If multiple interpolations are passed consecutively, they will be treated
as separate interpolations and an empty string will be inserted between them.
For example, the following code creates a template with empty placeholders
in the @ref{296d,,strings} attribute:

@example
>>> from string.templatelib import Interpolation, Template
>>> template = Template(
...     Interpolation('Camembert', 'cheese'),
...     Interpolation('.', 'punctuation'),
... )
>>> template.strings
('@w{'}, '@w{'}, '@w{'})
@end example
@end deffn


@deffn {Describe} iter(template)

Iterate over the template, yielding each non-empty string and
@ref{416,,Interpolation} in the correct order:

@example
>>> cheese = 'Camembert'
>>> list(t'Ah! We do have @{cheese@}.')
['Ah! We do have ', Interpolation('Camembert', 'cheese', None, '@w{'}), '.']
@end example

@cartouche
@quotation Προσοχή 
Empty strings are `not' included in the iteration:

@example
>>> response = 'We do have '
>>> cheese = 'Camembert'
>>> list(t'Ah! @{response@}@{cheese@}.')
['Ah! ',
 Interpolation('We do have ', 'response', None, '@w{'}),
 Interpolation('Camembert', 'cheese', None, '@w{'}),
 '.']
@end example
@end quotation
@end cartouche
@end deffn


@deffn {Describe} template + other

@deffnx {Describe} template += other

Concatenate this template with another, returning a new
@code{Template} instance:

@example
>>> cheese = 'Camembert'
>>> list(t'Ah! ' + t'We do have @{cheese@}.')
['Ah! We do have ', Interpolation('Camembert', 'cheese', None, '@w{'}), '.']
@end example

Concatenating a @code{Template} and a @code{str} is `not' supported.
This is because it is unclear whether the string should be treated as
a static string or an interpolation.
If you want to concatenate a @code{Template} with a string,
you should either wrap the string directly in a @code{Template}
(to treat it as a static string)
or use an @code{Interpolation} (to treat it as dynamic):

@example
>>> from string.templatelib import Interpolation, Template
>>> template = t'Ah! '
>>> # Treat 'We do have ' as a static string
>>> template += Template('We do have ')
>>> # Treat cheese as an interpolation
>>> cheese = 'Camembert'
>>> template += Template(Interpolation(cheese, 'cheese'))
>>> list(template)
['Ah! We do have ', Interpolation('Camembert', 'cheese', None, '@w{'})]
@end example
@end deffn
@end deffn

@geindex Interpolation (κλάση σε string.templatelib)
@anchor{library/string templatelib string templatelib Interpolation}@anchor{416}
@deffn {Κλάση} string.templatelib.Interpolation

The @code{Interpolation} type represents an expression inside a template string.
It is immutable, meaning that attributes of an interpolation cannot be reassigned.

Interpolations support pattern matching, allowing you to match against
their attributes with the @ref{1d4,,match statement}:

@example
>>> from string.templatelib import Interpolation
>>> interpolation = t'@{1. + 2.:.2f@}'.interpolations[0]
>>> interpolation
Interpolation(3.0, '1. + 2.', None, '.2f')
>>> match interpolation:
...     case Interpolation(value, expression, conversion, format_spec):
...         print(value, expression, conversion, format_spec, sep=' | ')
...
3.0 | 1. + 2. | None | .2f
@end example

@subsubheading Attributes


@geindex value (ιδιότητα της string.templatelib.Interpolation)
@anchor{library/string templatelib string templatelib Interpolation value}@anchor{2971}
@deffn {Ιδιότητα} value: @ref{e4d,,object}

The evaluated value of the interpolation.

@example
>>> t'@{1 + 2@}'.interpolations[0].value
3
@end example
@end deffn

@geindex expression (ιδιότητα της string.templatelib.Interpolation)
@anchor{library/string templatelib string templatelib Interpolation expression}@anchor{2972}
@deffn {Ιδιότητα} expression: @ref{1df,,str}

For interpolations created by t-string literals, @code{expression}
is the expression text found inside the curly brackets (@code{@{} & @code{@}}),
including any whitespace, excluding the curly brackets themselves,
and ending before the first @code{!}, @code{:}, or @code{=} if any is present.
For manually created interpolations, @code{expression} is the arbitrary
string provided when constructing the interpolation instance.

We recommend using valid Python expressions or the empty string for the
@code{expression} field of manually created @code{Interpolation}
instances, although this is not enforced at runtime.

@example
>>> t'@{1 + 2@}'.interpolations[0].expression
'1 + 2'
@end example
@end deffn

@geindex conversion (ιδιότητα της string.templatelib.Interpolation)
@anchor{library/string templatelib string templatelib Interpolation conversion}@anchor{284e}
@deffn {Ιδιότητα} conversion: @ref{c2d,,Literal}['a', 'r', 's'] | @ref{a65,,None}

The conversion to apply to the value, or @code{None}.

The @code{conversion} is the optional conversion to apply
to the value:

@example
>>> t'@{1 + 2!a@}'.interpolations[0].conversion
'a'
@end example

@cartouche
@quotation Σημείωση 
Unlike f-strings, where conversions are applied automatically,
the expected behavior with t-strings is that code that `processes' the
@code{Template} will decide how to interpret and whether to apply
the @code{conversion}.
For convenience, the @ref{2973,,convert()} function can be used to mimic
f-string conversion semantics.
@end quotation
@end cartouche
@end deffn

@geindex format_spec (ιδιότητα της string.templatelib.Interpolation)
@anchor{library/string templatelib string templatelib Interpolation format_spec}@anchor{2974}
@deffn {Ιδιότητα} format_spec: @ref{1df,,str}

The format specification to apply to the value.

The @code{format_spec} is an optional, arbitrary string
used as the format specification to present the value:

@example
>>> t'@{1 + 2:.2f@}'.interpolations[0].format_spec
'.2f'
@end example

@cartouche
@quotation Σημείωση 
Unlike f-strings, where format specifications are applied automatically
via the @ref{439,,format()} protocol, the expected behavior with
t-strings is that code that `processes' the interpolation will
decide how to interpret and whether to apply the format specification.
As a result, @code{format_spec} values in interpolations
can be arbitrary strings,
including those that do not conform to the @code{format()} protocol.
@end quotation
@end cartouche
@end deffn

@subsubheading Methods


@geindex __new__() (μέθοδος της string.templatelib.Interpolation)
@anchor{library/string templatelib string templatelib Interpolation __new__}@anchor{2975}
@deffn {Μέθοδος} __new__ (value: object, expression: str, conversion: Literal['a', 'r', 's'] | None = None, format_spec: str = '@w{'})

Create a new @code{Interpolation} object from component parts.

@*Παράμετροι: 

@itemize *

@item 
@code{value} – The evaluated, in-scope result of the interpolation.

@item 
@code{expression} – The text of a valid Python expression,
or an empty string.

@item 
@code{conversion} – The @ref{173f,,conversion} to be used,
one of @code{None}, @code{'a'}, @code{'r'}, or @code{'s'}.

@item 
@code{format_spec} – An optional, arbitrary string used as the
@ref{6fe,,format specification} to present the value.
@end itemize

@end deffn
@end deffn

@node Helper functions<2>,,Types,string templatelib — Support for template string literals
@anchor{library/string templatelib helper-functions}@anchor{2976}
@subsubsection Helper functions


@geindex convert() (στη μονάδα string.templatelib)
@anchor{library/string templatelib string templatelib convert}@anchor{2973}
@deffn {Συνάρτηση} string.templatelib.convert (obj, /, conversion)

Applies formatted string literal @ref{2953,,conversion}
semantics to the given object `obj'.
This is frequently useful for custom template string processing logic.

Three conversion flags are currently supported:


@itemize *

@item 
@code{'s'} which calls @ref{1df,,str()} on the value (like @code{!s}),

@item 
@code{'r'} which calls @ref{45b,,repr()} (like @code{!r}), and

@item 
@code{'a'} which calls @ref{1789,,ascii()} (like @code{!a}).
@end itemize

If the conversion flag is @code{None}, `obj' is returned unchanged.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node re — Regular expression operations,difflib — Helpers for computing deltas,string templatelib — Support for template string literals,Text Processing Services
@anchor{library/re doc}@anchor{2977}@anchor{library/re module-re}@anchor{c1}@anchor{library/re re-regular-expression-operations}@anchor{2978}@anchor{library/re translation-repo}@anchor{2979}
@subsection @code{re} — Regular expression operations


@geindex module; re

`Source code:' Lib/re/@footnote{https://github.com/python/cpython/tree/main/Lib/re/}


__________________________________________________________________


This module provides regular expression matching operations similar to
those found in Perl.

Both patterns and strings to be searched can be Unicode strings (@ref{1df,,str})
as well as 8-bit strings (@ref{1c7,,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{44a,,SyntaxWarning}
and in the future this will become a @ref{17e,,SyntaxError}. This behaviour
will happen even if it is a valid escape sequence for a regular expression.

The solution is to use Python’s raw string notation for regular expression
patterns; backslashes are not handled in any special way in a string literal
prefixed with @code{'r'}.  So @code{r"\n"} is a two-character string containing
@code{'\'} and @code{'n'}, while @code{"\n"} is a one-character string containing a
newline.  Usually patterns will be expressed in Python code using this raw
string notation.

It is important to note that most regular expression operations are available as
module-level functions and methods on
@ref{1331,,compiled regular expressions}.  The functions are shortcuts
that don’t require you to compile a regex object first, but miss some
fine-tuning parameters.


@subsubheading Δείτε επίσης


The third-party regex@footnote{https://pypi.org/project/regex/} module,
which has an API compatible with the standard library @code{re} module,
but offers additional functionality and a more thorough Unicode support.


@menu
* Regular expression syntax:: 
* Module contents:: 
* Regular expression objects:: 
* Match objects:: 
* Regular expression examples:: 

@end menu

@node Regular expression syntax,Module contents,,re — Regular expression operations
@anchor{library/re re-syntax}@anchor{b0c}@anchor{library/re regular-expression-syntax}@anchor{297a}
@subsubsection Regular expression syntax


A regular expression (or RE) specifies a set of strings that matches it; the
functions in this module let you check if a particular string matches a given
regular expression (or if a given regular expression matches a particular
string, which comes down to the same thing).

Regular expressions can be concatenated to form new regular expressions; if `A'
and `B' are both regular expressions, then `AB' is also a regular expression.
In general, if a string `p' matches `A' and another string `q' matches `B', the
string `pq' will match AB.  This holds unless `A' or `B' contain low precedence
operations; boundary conditions between `A' and `B'; or have numbered group
references.  Thus, complex expressions can easily be constructed from simpler
primitive expressions like the ones described here.  For details of the theory
and implementation of regular expressions, consult the Friedl book @ref{297b,,[Frie09]},
or almost any textbook about compiler construction.

A brief explanation of the format of regular expressions follows.  For further
information and a gentler presentation, consult the @ref{297c,,Regular expression HOWTO}.

Regular expressions can contain both special and ordinary characters. Most
ordinary characters, like @code{'A'}, @code{'a'}, or @code{'0'}, are the simplest regular
expressions; they simply match themselves.  You can concatenate ordinary
characters, so @code{last} matches the string @code{'last'}.  (In the rest of this
section, we’ll write RE’s in @code{this special style}, usually without quotes, and
strings to be matched @code{'in single quotes'}.)

Some characters, like @code{'|'} or @code{'('}, are special. Special
characters either stand for classes of ordinary characters, or affect
how the regular expressions around them are interpreted.

Repetition operators or quantifiers (@code{*}, @code{+}, @code{?}, @code{@{m,n@}}, etc) cannot be
directly nested. This avoids ambiguity with the non-greedy modifier suffix
@code{?}, and with other modifiers in other implementations. To apply a second
repetition to an inner repetition, parentheses may be used. For example,
the expression @code{(?:a@{6@})*} matches any multiple of six @code{'a'} characters.

The special characters are:

@geindex . (dot);in regular expressions


@table @asis

@item @code{.}

(Dot.)  In the default mode, this matches any character except a newline.  If
the @ref{297d,,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{^}

(Caret.)  Matches the start of the string, and in @ref{297e,,MULTILINE} mode also
matches immediately after each newline.
@end table

@geindex $ (dollar);in regular expressions


@table @asis

@item @code{$}

Matches the end of the string or just before the newline at the end of the
string, and in @ref{297e,,MULTILINE} mode also matches before a newline.  @code{foo}
matches both “foo” and “foobar”, while the regular expression @code{foo$} matches
only “foo”.  More interestingly, searching for @code{foo.$} in @code{'foo1\nfoo2\n'}
matches “foo2” normally, but “foo1” in @code{MULTILINE} mode; searching for
a single @code{$} in @code{'foo\n'} will find two (empty) matches: one just before
the newline, and one at the end of the string.
@end table

@geindex * (asterisk);in regular expressions


@table @asis

@item @code{*}

Causes the resulting RE to match 0 or more repetitions of the preceding RE, as
many repetitions as are possible.  @code{ab*} will match “a”, “ab”, or “a” followed
by any number of “b’s.
@end table

@geindex + (plus);in regular expressions


@table @asis

@item @code{+}

Causes the resulting RE to match 1 or more repetitions of the preceding RE.
@code{ab+} will match “a” followed by any non-zero number of “b’s; it will not
match just “a”.
@end table

@geindex ? (question mark);in regular expressions


@table @asis

@item @code{?}

Causes the resulting RE to match 0 or 1 repetitions of the preceding RE.
@code{ab?} will match either “a” or “ab”.
@end table

@geindex *?;in regular expressions
@geindex +?;in regular expressions
@geindex ??;in regular expressions


@table @asis

@item @code{*?}, @code{+?}, @code{??}

The @code{'*'}, @code{'+'}, and @code{'?'} quantifiers are all `greedy'; they match
as much text as possible.  Sometimes this behaviour isn’t desired; if the RE
@code{<.*>} is matched against @code{'<a> b <c>'}, it will match the entire
string, and not just @code{'<a>'}.  Adding @code{?} after the quantifier makes it
perform the match in `non-greedy' or `minimal' fashion; as `few'
characters as possible will be matched.  Using the RE @code{<.*?>} will match
only @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.


Added in version 3.11.

@end table

@geindex @{@} (curly brackets);in regular expressions


@table @asis

@item @code{@{m@}}

Specifies that exactly `m' copies of the previous RE should be matched; fewer
matches cause the entire RE not to match.  For example, @code{a@{6@}} will match
exactly six @code{'a'} characters, but not five.

@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.  For example,
@code{a@{3,5@}} will match from 3 to 5 @code{'a'} characters.  Omitting `m' specifies a
lower bound of zero,  and omitting `n' specifies an infinite upper bound.  As an
example, @code{a@{4,@}b} will match @code{'aaaab'} or a thousand @code{'a'} characters
followed by a @code{'b'}, but not @code{'aaab'}. The comma may not be omitted or the
modifier would be confused with the previously described form.

@item @code{@{m,n@}?}

Causes the resulting RE to match from `m' to `n' repetitions of the preceding
RE, attempting to match as `few' repetitions as possible.  This is the
non-greedy version of the previous quantifier.  For example, on the
6-character string @code{'aaaaaa'}, @code{a@{3,5@}} will match 5 @code{'a'} characters,
while @code{a@{3,5@}?} will only match 3 characters.

@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}
attempts 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@})}.


Added in version 3.11.

@end table

@geindex \ (backslash);in regular expressions


@table @asis

@item @code{\}

Either escapes special characters (permitting you to match characters like
@code{'*'}, @code{'?'}, and so forth), or signals a special sequence; special
sequences are discussed below.

If you’re not using a raw string to express the pattern, remember that Python
also uses the backslash as an escape sequence in string literals; if the escape
sequence isn’t recognized by Python’s parser, the backslash and subsequent
character are included in the resulting string.  However, if Python would
recognize the resulting sequence, the backslash should be repeated twice.  This
is complicated and hard to understand, so it’s highly recommended that you use
raw strings for all but the simplest expressions.
@end table

@geindex [] (square brackets);in regular expressions


@table @asis

@item @code{[]}

Used to indicate a set of characters.  In a set:


@itemize *

@item 
Characters can be listed individually, e.g. @code{[amk]} will match @code{'a'},
@code{'m'}, or @code{'k'}.
@end itemize

@geindex - (minus);in regular expressions


@itemize *

@item 
Ranges of characters can be indicated by giving two characters and separating
them by a @code{'-'}, for example @code{[a-z]} will match any lowercase ASCII letter,
@code{[0-5][0-9]} will match all the two-digits numbers from @code{00} to @code{59}, and
@code{[0-9A-Fa-f]} will match any hexadecimal digit.  If @code{-} is escaped (e.g.
@code{[a\-z]}) or if it’s placed as the first or last character
(e.g. @code{[-a]} or @code{[a-]}), it will match a literal @code{'-'}.

@item 
Special characters except backslash lose their special meaning inside sets.
For example,
@code{[(+*)]} will match any of the literal characters @code{'('}, @code{'+'},
@code{'*'}, or @code{')'}.
@end itemize

@geindex \ (backslash);in regular expressions


@itemize *

@item 
Backslash either escapes characters which have special meaning in a set
such as @code{'-'}, @code{']'}, @code{'^'} and @code{'\\'} itself or signals
a special sequence which represents a single character such as
@code{\xa0} or @code{\n} or a character class such as @code{\w} or @code{\S}
(defined below).
Note that @code{\b} represents a single «backspace» character,
not a word boundary as outside a set, and numeric escapes
such as @code{\1} are always octal escapes, not group references.
Special sequences which do not match a single character such as @code{\A}
and @code{\z} are not allowed.
@end itemize

@geindex ^ (caret);in regular expressions


@itemize *

@item 
Characters that are not within a range can be matched by `complementing'
the set.  If the first character of the set is @code{'^'}, all the characters
that are `not' in the set will be matched.  For example, @code{[^5]} will match
any character except @code{'5'}, and @code{[^^]} will match any character except
@code{'^'}.  @code{^} has no special meaning if it’s not the first character in
the set.

@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 
Support of nested sets and set operations as in Unicode Technical Standard #18@footnote{https://unicode.org/reports/tr18/} might be added in the future.  This would change the
syntax, so to facilitate this change a @ref{847,,FutureWarning} will be raised
in ambiguous cases for the time being.
That includes 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.
@end itemize


Άλλαξε στην έκδοση 3.7: @ref{847,,FutureWarning} is raised if a character set contains constructs
that will change semantically in the future.

@end table

@geindex | (vertical bar);in regular expressions


@table @asis

@item @code{|}

@code{A|B}, where `A' and `B' can be arbitrary REs, creates a regular expression that
will match either `A' or `B'.  An arbitrary number of REs can be separated by the
@code{'|'} in this way.  This can be used inside groups (see below) as well.  As
the target string is scanned, REs separated by @code{'|'} are tried from left to
right. When one pattern completely matches, that branch is accepted. This means
that once `A' matches, `B' will not be tested further, even if it would
produce a longer overall match.  In other words, the @code{'|'} operator is never
greedy.  To match a literal @code{'|'}, use @code{\|}, or enclose it inside a
character class, as in @code{[|]}.
@end table

@geindex () (parentheses);in regular expressions


@table @asis

@item @code{(...)}

Matches whatever regular expression is inside the parentheses, and indicates the
start and end of a group; the contents of a group can be retrieved after a match
has been performed, and can be matched later in the string with the @code{\number}
special sequence, described below.  To match the literals @code{'('} or @code{')'},
use @code{\(} or @code{\)}, or enclose them inside a character class: @code{[(]}, @code{[)]}.
@end table

@geindex (?;in regular expressions


@table @asis

@item @code{(?...)}

This is an extension notation (a @code{'?'} following a @code{'('} is not meaningful
otherwise).  The first character after the @code{'?'} determines what the meaning
and further syntax of the construct is. Extensions usually do not create a new
group; @code{(?P<name>...)} is the only exception to this rule. Following are the
currently supported extensions.

@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{297f,,re.A} (ASCII-only matching)

@item 
@ref{2980,,re.I} (ignore case)

@item 
@ref{2981,,re.L} (locale dependent)

@item 
@ref{2982,,re.M} (multi-line)

@item 
@ref{2983,,re.S} (dot matches all)

@item 
@ref{2984,,re.U} (Unicode matching)

@item 
@ref{2985,,re.X} (verbose)
@end itemize

(The flags are described in @ref{2986,,Module contents}.)
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{f93,,re.compile()} function.
Flags should be used first in the expression string.


Άλλαξε στην έκδοση 3.11: This construction can only be used at the start of the expression.

@end table

@geindex (?;;in regular expressions


@table @asis

@item @code{(?:...)}

A non-capturing version of regular parentheses.  Matches whatever regular
expression is inside the parentheses, but the substring matched by the group
`cannot' be retrieved after performing a match or referenced later in the
pattern.

@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{297f,,re.A} (ASCII-only matching)

@item 
@ref{2980,,re.I} (ignore case)

@item 
@ref{2981,,re.L} (locale dependent)

@item 
@ref{2982,,re.M} (multi-line)

@item 
@ref{2983,,re.S} (dot matches all)

@item 
@ref{2984,,re.U} (Unicode matching)

@item 
@ref{2985,,re.X} (verbose)
@end itemize

(The flags are described in @ref{2986,,Module contents}.)

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.


Added in version 3.6.



Άλλαξε στην έκδοση 3.7: The letters @code{'a'}, @code{'L'} and @code{'u'} also can be used in a group.


@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.


Added in 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{1c7,,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.

Named groups can be referenced in three contexts.  If the pattern is
@code{(?P<quote>['"]).*?(?P=quote)} (i.e. matching a string quoted with either
single or double quotes):


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Context of reference to group «quote»

@tab

Ways to reference it

@item

in the same pattern itself

@tab


@itemize *

@item 
@code{(?P=quote)} (as shown)

@item 
@code{\1}
@end itemize

@item

when processing match object `m'

@tab


@itemize *

@item 
@code{m.group('quote')}

@item 
@code{m.end('quote')} (etc.)
@end itemize

@item

in a string passed to the `repl'
argument of @code{re.sub()}

@tab


@itemize *

@item 
@code{\g<quote>}

@item 
@code{\g<1>}

@item 
@code{\1}
@end itemize

@end multitable



Άλλαξε στην έκδοση 3.12: In @ref{1c7,,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)}

A backreference to a named group; it matches whatever text was matched by the
earlier group named `name'.
@end table

@geindex (?#;in regular expressions


@table @asis

@item @code{(?#...)}

A comment; the contents of the parentheses are simply ignored.
@end table

@geindex (?=;in regular expressions


@table @asis

@item @code{(?=...)}

Matches if @code{...} matches next, but doesn’t consume any of the string.  This is
called a `lookahead assertion'.  For example, @code{Isaac (?=Asimov)} will match
@code{'Isaac '} only if it’s followed by @code{'Asimov'}.
@end table

@geindex (?!;in regular expressions


@table @asis

@item @code{(?!...)}

Matches if @code{...} doesn’t match next.  This is a `negative lookahead assertion'.
For example, @code{Isaac (?!Asimov)} will match @code{'Isaac '} only if it’s `not'
followed by @code{'Asimov'}.
@end table

@geindex (?<=;in regular expressions


@table @asis

@item @code{(?<=...)}

Matches if the current position in the string is preceded by a match for @code{...}
that ends at the current position.  This is called a `positive lookbehind
assertion'. @code{(?<=abc)def} will find a match in @code{'abcdef'}, since the
lookbehind will back up 3 characters and check if the contained pattern matches.
The contained pattern must only match strings of some fixed length, meaning that
@code{abc} or @code{a|b} are allowed, but @code{a*} and @code{a@{3,4@}} are not.  Note that
patterns which start with positive lookbehind assertions will not match at the
beginning of the string being searched; you will most likely want to use the
@ref{15d3,,search()} function rather than the @ref{24c,,match()} function:

@example
>>> import re
>>> m = re.search('(?<=abc)def', 'abcdef')
>>> m.group(0)
'def'
@end example

This example looks for a word following a hyphen:

@example
>>> m = re.search(r'(?<=-)\w+', 'spam-egg')
>>> m.group(0)
'egg'
@end example


Άλλαξε στην έκδοση 3.5: Added support for group references of fixed length.

@end table

@geindex (?<!;in regular expressions


@table @asis

@item @code{(?<!...)}

Matches if the current position in the string is not preceded by a match for
@code{...}.  This is called a `negative lookbehind assertion'.  Similar to
positive lookbehind assertions, the contained pattern must only match strings of
some fixed length.  Patterns which start with negative lookbehind assertions may
match at the beginning of the string being searched.
@end table

@geindex (?(;in regular expressions
@anchor{library/re re-conditional-expression}@anchor{1d26}

@table @asis

@item @code{(?(id/name)yes-pattern|no-pattern)}

Will try to match with @code{yes-pattern} if the group with given `id' or
`name' exists, and with @code{no-pattern} if it doesn’t. @code{no-pattern} is
optional and can be omitted. For example,
@code{(<)?(\w+@@\w+(?:\.\w+)+)(?(1)>|$)} is a poor email matching pattern, which
will match with @code{'<user@@host.com>'} as well as @code{'user@@host.com'}, but
not with @code{'<user@@host.com'} nor @code{'user@@host.com>'}.


Άλλαξε στην έκδοση 3.12: Group `id' can only contain ASCII digits.
In @ref{1c7,,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{2987}
The special sequences consist of @code{'\'} and a character from the list below.
If the ordinary character is not an ASCII digit or an ASCII letter, then the
resulting RE will match the second character.  For example, @code{\$} matches the
character @code{'$'}.

@geindex \ (backslash);in regular expressions


@table @asis

@item @code{\number}

Matches the contents of the group of the same number.  Groups are numbered
starting from 1.  For example, @code{(.+) \1} matches @code{'the the'} or @code{'55 55'},
but not @code{'thethe'} (note the space after the group).  This special sequence
can only be used to match one of the first 99 groups.  If the first digit of
`number' is 0, or `number' is 3 octal digits long, it will not be interpreted as
a group match, but as the character with octal value `number'. Inside the
@code{'['} and @code{']'} of a character class, all numeric escapes are treated as
characters.
@end table

@geindex \A;in regular expressions


@table @asis

@item @code{\A}

Matches only at the start of the string.
@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{a1d,,ASCII} flag.
Word boundaries are determined by the current locale
if the @ref{f29,,LOCALE} flag is used.

@cartouche
@quotation Σημείωση 
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{a1d,,ASCII} flag.
Word boundaries are determined by the current locale
if the @ref{f29,,LOCALE} flag is used.


Άλλαξε στην έκδοση 3.14: @code{\B} now matches empty input string.

@end table

@geindex \d;in regular expressions


@table @asis

@item @code{\d}


@table @asis

@item For Unicode (str) patterns:

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{a1d,,ASCII} flag is used.

@item For 8-bit (bytes) patterns:

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{a1d,,ASCII} flag is used.
@end table

@geindex \s;in regular expressions


@table @asis

@item @code{\s}


@table @asis

@item For Unicode (str) patterns:

Matches Unicode whitespace characters (as defined by @ref{282d,,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{a1d,,ASCII} flag is used.

@item For 8-bit (bytes) patterns:

Matches characters considered whitespace in the ASCII character set;
this is equivalent to @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{a1d,,ASCII} flag is used.
@end table

@geindex \w;in regular expressions


@table @asis

@item @code{\w}


@table @asis

@item For Unicode (str) patterns:

Matches Unicode word characters;
this includes all Unicode alphanumeric characters
(as defined by @ref{2825,,str.isalnum()}),
as well as the underscore (@code{_}).

Matches @code{[a-zA-Z0-9_]} if the @ref{a1d,,ASCII} flag is used.

@item For 8-bit (bytes) patterns:

Matches characters considered alphanumeric in the ASCII character set;
this is equivalent to @code{[a-zA-Z0-9_]}.
If the @ref{f29,,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{2825,,str.isalnum()} returns @code{False}.

Matches @code{[^a-zA-Z0-9_]} if the @ref{a1d,,ASCII} flag is used.

If the @ref{f29,,LOCALE} flag is used,
matches characters which are neither alphanumeric in the current locale
nor the underscore.
@end table

@geindex \z;in regular expressions
@geindex \Z;in regular expressions


@table @asis

@item @code{\z}

Matches only at the end of the string.


Added in version 3.14.


@item @code{\Z}

The same as @code{\z}.  For compatibility with old Python versions.
@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{874,,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

(Note that @code{\b} is used to represent word boundaries, and means «backspace»
only inside character classes.)

@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.

Octal escapes are included in a limited form.  If the first digit is a 0, or if
there are three octal digits, it is considered an octal escape. Otherwise, it is
a group reference.  As for string literals, octal escapes are always at most
three digits in length.


Άλλαξε στην έκδοση 3.3: The @code{'\u'} and @code{'\U'} escape sequences have been added.



Άλλαξε στην έκδοση 3.6: Unknown escapes consisting of @code{'\'} and an ASCII letter now are errors.



Άλλαξε στην έκδοση 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 Module contents,Regular expression objects,Regular expression syntax,re — Regular expression operations
@anchor{library/re contents-of-module-re}@anchor{2986}@anchor{library/re module-contents}@anchor{2988}
@subsubsection Module contents


The module defines several functions, constants, and an exception. Some of the
functions are simplified versions of the full featured methods for compiled
regular expressions.  Most non-trivial applications always use the compiled
form.

@menu
* Flags:: 
* Functions:: 
* Exceptions:: 

@end menu

@node Flags,Functions,,Module contents
@anchor{library/re flags}@anchor{2989}
@subsubsection Flags



Άλλαξε στην έκδοση 3.6: Flag constants are now instances of @ref{a1e,,RegexFlag}, which is a subclass of
@ref{105d,,enum.IntFlag}.


@geindex RegexFlag (κλάση σε re)
@anchor{library/re re RegexFlag}@anchor{a1e}
@deffn {Κλάση} re.RegexFlag

An @ref{105d,,enum.IntFlag} class containing the regex options listed below.


Added in version 3.11: - added to @code{__all__}

@end deffn

@geindex A (στη μονάδα re)
@geindex ASCII (στη μονάδα re)
@anchor{library/re re A}@anchor{297f}
@deffn {Δεδομένα} re.A
@anchor{library/re re ASCII}@anchor{a1d}
@deffnx {Δεδομένα} 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 Σημείωση 
The @ref{2984,,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{f2a,,UNICODE} and the inline flag @code{(?u)} are similarly redundant.
@end quotation
@end cartouche
@end deffn

@geindex DEBUG (στη μονάδα re)
@anchor{library/re re DEBUG}@anchor{298a}
@deffn {Δεδομένα} re.DEBUG

Display debug information about compiled expression.

No corresponding inline flag.
@end deffn

@geindex I (στη μονάδα re)
@geindex IGNORECASE (στη μονάδα re)
@anchor{library/re re I}@anchor{2980}
@deffn {Δεδομένα} re.I
@anchor{library/re re IGNORECASE}@anchor{1c9b}
@deffnx {Δεδομένα} 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{a1d,,ASCII} flag
is used to disable non-ASCII matches.
The current locale does not change the effect of this flag
unless the @ref{f29,,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{1c9b,,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{a1d,,ASCII} flag is used, only letters “a” to “z”
and “A” to “Z” are matched.
@end deffn

@geindex L (στη μονάδα re)
@geindex LOCALE (στη μονάδα re)
@anchor{library/re re L}@anchor{2981}
@deffn {Δεδομένα} re.L
@anchor{library/re re LOCALE}@anchor{f29}
@deffnx {Δεδομένα} 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 Προειδοποίηση 
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


Άλλαξε στην έκδοση 3.6: @ref{f29,,LOCALE} can be used only with bytes patterns
and is not compatible with @ref{a1d,,ASCII}.



Άλλαξε στην έκδοση 3.7: Compiled regular expression objects with the @ref{f29,,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 (στη μονάδα re)
@geindex MULTILINE (στη μονάδα re)
@anchor{library/re re M}@anchor{2982}
@deffn {Δεδομένα} re.M
@anchor{library/re re MULTILINE}@anchor{297e}
@deffnx {Δεδομένα} 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 (στη μονάδα re)
@anchor{library/re re NOFLAG}@anchor{298b}
@deffn {Δεδομένα} 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(pattern, text, flag=re.NOFLAG):
    return re.search(pattern, text, flag)
@end example


Added in version 3.11.

@end deffn

@geindex S (στη μονάδα re)
@geindex DOTALL (στη μονάδα re)
@anchor{library/re re S}@anchor{2983}
@deffn {Δεδομένα} re.S
@anchor{library/re re DOTALL}@anchor{297d}
@deffnx {Δεδομένα} 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 (στη μονάδα re)
@geindex UNICODE (στη μονάδα re)
@anchor{library/re re U}@anchor{2984}
@deffn {Δεδομένα} re.U
@anchor{library/re re UNICODE}@anchor{f2a}
@deffnx {Δεδομένα} 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{a1d,,ASCII} to restrict matching to ASCII characters instead.
@end deffn

@geindex X (στη μονάδα re)
@geindex VERBOSE (στη μονάδα re)
@anchor{library/re re X}@anchor{2985}
@deffn {Δεδομένα} re.X
@anchor{library/re re VERBOSE}@anchor{298c}
@deffnx {Δεδομένα} re.VERBOSE

@geindex # (hash);in regular expressions

This flag allows you to write regular expressions that look nicer and are
more readable by allowing you to visually separate logical sections of the
pattern and add comments. Whitespace within the pattern is ignored, except
when in a character class, or when preceded by an unescaped backslash,
or within tokens like @code{*?}, @code{(?:} or @code{(?P<...>}. For example, @code{(? :}
and @code{* ?} are not allowed.
When a line contains a @code{#} that is not in a character class and is not
preceded by an unescaped backslash, all characters from the leftmost such
@code{#} through the end of the line are ignored.

This means that the two following regular expression objects that match a
decimal number are functionally equal:

@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

Corresponds to the inline flag @code{(?x)}.
@end deffn

@node Functions,Exceptions,Flags,Module contents
@anchor{library/re functions}@anchor{298d}
@subsubsection Functions


@geindex compile() (στη μονάδα re)
@anchor{library/re re compile}@anchor{f93}
@deffn {Συνάρτηση} re.compile (pattern, flags=0)

Compile a regular expression pattern into a @ref{1331,,regular expression object}, which can be used for matching using its
@ref{24b,,prefixmatch()},
@ref{298e,,search()}, and other methods, described below.

The expression’s behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2989,,flags} variables, combined using bitwise OR
(the @code{|} operator).

The sequence

@example
prog = re.compile(pattern)
result = prog.search(string)
@end example

is equivalent to

@example
result = re.search(pattern, string)
@end example

but using @ref{f93,,re.compile()} and saving the resulting regular expression
object for reuse is more efficient when the expression will be used several
times in a single program.

@cartouche
@quotation Σημείωση 
The compiled versions of the most recent patterns passed to
@ref{f93,,re.compile()} and the module-level matching functions are cached, so
programs that use only a few regular expressions at a time needn’t worry
about compiling regular expressions.
@end quotation
@end cartouche
@end deffn

@geindex search() (στη μονάδα re)
@anchor{library/re re search}@anchor{15d3}
@deffn {Συνάρτηση} 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{1085,,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{2989,,flags} variables, combined using bitwise OR
(the @code{|} operator).
@end deffn

@geindex prefixmatch() (στη μονάδα re)
@anchor{library/re re prefixmatch}@anchor{24a}
@deffn {Συνάρτηση} re.prefixmatch (pattern, string, flags=0)

If zero or more characters at the beginning of `string' match the regular
expression `pattern', return a corresponding @ref{1085,,Match}.  Return
@code{None} if the string does not match the pattern; note that this is
different from a zero-length match.

@cartouche
@quotation Σημείωση 
Even in @ref{297e,,MULTILINE} mode, this will only match at the
beginning of the string and not at the beginning of each line.
@end quotation
@end cartouche

If you want to locate a match anywhere in `string', use @ref{15d3,,search()}
instead (see also @ref{298f,,search() vs. prefixmatch()}).

The expression’s behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2989,,flags} variables, combined using bitwise OR
(the @code{|} operator).

This function now has two names and has long been known as
@ref{24c,,match()}.  Use that name when you need to retain compatibility with
older Python versions.


Added in version 3.15.

@end deffn

@geindex match() (στη μονάδα re)
@anchor{library/re re match}@anchor{24c}
@deffn {Συνάρτηση} re.match (pattern, string, flags=0)


@ref{1a7,,Soft deprecated} since version 3.15: @ref{24c,,match()} has been soft deprecated in favor of
the alternate @ref{24a,,prefixmatch()} name of this API which is
more explicitly descriptive. Use it to better
express intent. The norm in other languages and regular expression
implementations is to use the term `match' to refer to the behavior of
what Python has always called @ref{15d3,,search()}.
See @ref{2f9,,prefixmatch() vs. match()}.

@end deffn

@geindex fullmatch() (στη μονάδα re)
@anchor{library/re re fullmatch}@anchor{132f}
@deffn {Συνάρτηση} re.fullmatch (pattern, string, flags=0)

If the whole `string' matches the regular expression `pattern', return a
corresponding @ref{1085,,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{2989,,flags} variables, combined using bitwise OR
(the @code{|} operator).


Added in version 3.4.

@end deffn

@geindex split() (στη μονάδα re)
@anchor{library/re re split}@anchor{7a0}
@deffn {Συνάρτηση} re.split (pattern, string, maxsplit=0, flags=0)

Split `string' by the occurrences of `pattern'.  If capturing parentheses are
used in `pattern', then the text of all groups in the pattern are also returned
as part of the resulting list. If `maxsplit' is nonzero, at most `maxsplit'
splits occur, and the remainder of the string is returned as the final element
of the list.

@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

If there are capturing groups in the separator and it matches at the start of
the string, the result will start with an empty string.  The same holds for
the end of the string:

@example
>>> re.split(r'(\W+)', '...words, words...')
['@w{'}, '...', 'words', ', ', 'words', '...', '@w{'}]
@end example

That way, separator components are always found at the same relative
indices within the result list.

Adjacent empty matches are not possible, but an empty match can occur
immediately after a non-empty match.

@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{2989,,flags} variables, combined using bitwise OR
(the @code{|} operator).


Άλλαξε στην έκδοση 3.1: Added the optional flags argument.



Άλλαξε στην έκδοση 3.7: Added support of splitting on a pattern that could match an empty string.



Αποσύρθηκε στην έκδοση 3.13: Passing `maxsplit' and `flags' as positional arguments is deprecated.
In future Python versions they will be
@ref{7a3,,keyword-only parameters}.

@end deffn

@geindex findall() (στη μονάδα re)
@anchor{library/re re findall}@anchor{13d2}
@deffn {Συνάρτηση} re.findall (pattern, string, flags=0)

Return all non-overlapping matches of `pattern' in `string', as a list of
strings or tuples.  The `string' is scanned left-to-right, and matches
are returned in the order found.  Empty matches are included in the result.

The result depends on the number of capturing groups in the pattern.
If there are no groups, return a list of strings matching the whole
pattern.  If there is exactly one group, return a list of strings
matching that group.  If multiple groups are present, return a list
of tuples of strings matching the groups.  Non-capturing groups do not
affect the form of the result.

@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{2989,,flags} variables, combined using bitwise OR
(the @code{|} operator).


Άλλαξε στην έκδοση 3.7: Non-empty matches can now start just after a previous empty match.

@end deffn

@geindex finditer() (στη μονάδα re)
@anchor{library/re re finditer}@anchor{189c}
@deffn {Συνάρτηση} re.finditer (pattern, string, flags=0)

Return an @ref{6ce,,iterator} yielding @ref{1085,,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{2989,,flags} variables, combined using bitwise OR
(the @code{|} operator).


Άλλαξε στην έκδοση 3.7: Non-empty matches can now start just after a previous empty match.

@end deffn

@geindex sub() (στη μονάδα re)
@anchor{library/re re sub}@anchor{7a1}
@deffn {Συνάρτηση} re.sub (pattern, repl, string, count=0, flags=0)

Return the string obtained by replacing the leftmost non-overlapping occurrences
of `pattern' in `string' by the replacement `repl'.  If the pattern isn’t found,
`string' is returned unchanged.  `repl' can be a string or a function; if it is
a string, any backslash escapes in it are processed.  That is, @code{\n} is
converted to a single newline character, @code{\r} is converted to a carriage return, and
so forth.  Unknown escapes of ASCII letters are reserved for future use and
treated as errors.  Other unknown escapes such as @code{\&} are left alone.
Backreferences, such
as @code{\6}, are replaced with the substring matched by group 6 in the pattern.
For example:

@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{1085,,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{194d,,Pattern}.

The optional argument `count' is the maximum number of pattern occurrences to be
replaced; `count' must be a non-negative integer.  If omitted or zero, all
occurrences will be replaced.

Adjacent empty matches are not possible, but an empty match can occur
immediately after a non-empty match.
As a result, @code{sub('x*', '-', 'abxd')} returns @code{'-a-b--d-'}
instead of @code{'-a-b-d-'}.

@geindex \g;in regular expressions

In string-type `repl' arguments, in addition to the character escapes and
backreferences described above,
@code{\g<name>} will use the substring matched by the group named @code{name}, as
defined by the @code{(?P<name>...)} syntax. @code{\g<number>} uses the corresponding
group number; @code{\g<2>} is therefore equivalent to @code{\2}, but isn’t ambiguous
in a replacement such as @code{\g<2>0}.  @code{\20} would be interpreted as a
reference to group 20, not a reference to group 2 followed by the literal
character @code{'0'}.  The backreference @code{\g<0>} substitutes in the entire
substring matched by the RE.

The expression’s behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2989,,flags} variables, combined using bitwise OR
(the @code{|} operator).


Άλλαξε στην έκδοση 3.1: Added the optional flags argument.



Άλλαξε στην έκδοση 3.5: Unmatched groups are replaced with an empty string.



Άλλαξε στην έκδοση 3.6: Unknown escapes in `pattern' consisting of @code{'\'} and an ASCII letter
now are errors.



Άλλαξε στην έκδοση 3.7: Unknown escapes in `repl' consisting of @code{'\'} and an ASCII letter
now are errors.
An empty match can occur immediately after a non-empty match.



Άλλαξε στην έκδοση 3.12: Group `id' can only contain ASCII digits.
In @ref{1c7,,bytes} replacement strings, group `name' can only contain bytes
in the ASCII range (@code{b'\x00'}-@code{b'\x7f'}).



Αποσύρθηκε στην έκδοση 3.13: Passing `count' and `flags' as positional arguments is deprecated.
In future Python versions they will be
@ref{7a3,,keyword-only parameters}.

@end deffn

@geindex subn() (στη μονάδα re)
@anchor{library/re re subn}@anchor{7a2}
@deffn {Συνάρτηση} re.subn (pattern, repl, string, count=0, flags=0)

Perform the same operation as @ref{7a1,,sub()}, but return a tuple @code{(new_string,
number_of_subs_made)}.

The expression’s behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2989,,flags} variables, combined using bitwise OR
(the @code{|} operator).
@end deffn

@geindex escape() (στη μονάδα re)
@anchor{library/re re escape}@anchor{fc8}
@deffn {Συνάρτηση} re.escape (pattern)

Escape special characters in `pattern'.
This is useful if you want to match an arbitrary literal string that may
have regular expression metacharacters in it.  For example:

@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

This function must not be used for the replacement string in @ref{7a1,,sub()}
and @ref{7a2,,subn()}, only backslashes should be escaped.  For example:

@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


Άλλαξε στην έκδοση 3.3: The @code{'_'} character is no longer escaped.



Άλλαξε στην έκδοση 3.7: Only characters that can have special meaning in a regular expression
are escaped. As a result, @code{'!'}, @code{'"'}, @code{'%'}, @code{"'"}, @code{','},
@code{'/'}, @code{':'}, @code{';'}, @code{'<'}, @code{'='}, @code{'>'}, @code{'@@'}, and
@code{"`"} are no longer escaped.

@end deffn

@geindex purge() (στη μονάδα re)
@anchor{library/re re purge}@anchor{2990}
@deffn {Συνάρτηση} re.purge ()

Clear the regular expression cache.
@end deffn

@node Exceptions,,Functions,Module contents
@anchor{library/re exceptions}@anchor{2991}
@subsubsection Exceptions


@geindex PatternError
@anchor{library/re re PatternError}@anchor{749}
@deffn {Εξαίρεση} 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 (ιδιότητα της re.PatternError)
@anchor{library/re re PatternError msg}@anchor{11fc}
@deffn {Ιδιότητα} msg

The unformatted error message.
@end deffn

@geindex pattern (ιδιότητα της re.PatternError)
@anchor{library/re re PatternError pattern}@anchor{11fd}
@deffn {Ιδιότητα} pattern

The regular expression pattern.
@end deffn

@geindex pos (ιδιότητα της re.PatternError)
@anchor{library/re re PatternError pos}@anchor{11fe}
@deffn {Ιδιότητα} pos

The index in `pattern' where compilation failed (may be @code{None}).
@end deffn

@geindex lineno (ιδιότητα της re.PatternError)
@anchor{library/re re PatternError lineno}@anchor{11ff}
@deffn {Ιδιότητα} lineno

The line corresponding to `pos' (may be @code{None}).
@end deffn

@geindex colno (ιδιότητα της re.PatternError)
@anchor{library/re re PatternError colno}@anchor{1200}
@deffn {Ιδιότητα} colno

The column corresponding to `pos' (may be @code{None}).
@end deffn


Άλλαξε στην έκδοση 3.5: Added additional attributes.



Άλλαξε στην έκδοση 3.13: @code{PatternError} was originally named @code{error}; the latter is kept as an alias for
backward compatibility.

@end deffn

@node Regular expression objects,Match objects,Module contents,re — Regular expression operations
@anchor{library/re re-objects}@anchor{1331}@anchor{library/re regular-expression-objects}@anchor{2992}
@subsubsection Regular expression objects


@geindex Pattern (κλάση σε re)
@anchor{library/re re Pattern}@anchor{194d}
@deffn {Κλάση} re.Pattern

Compiled regular expression object returned by @ref{f93,,re.compile()}.


Άλλαξε στην έκδοση 3.9: @ref{194d,,re.Pattern} supports @code{[]} to indicate a Unicode (str) or bytes pattern.
See @ref{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex search() (μέθοδος της re.Pattern)
@anchor{library/re re Pattern search}@anchor{298e}
@deffn {Μέθοδος} 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{1085,,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 optional second parameter `pos' gives an index in the string where the
search is to start; it defaults to @code{0}.  This is not completely equivalent to
slicing the string; the @code{'^'} pattern character matches at the real beginning
of the string and at positions just after a newline, but not necessarily at the
index where the search is to start.

The optional parameter `endpos' limits how far the string will be searched; it
will be as if the string is `endpos' characters long, so only the characters
from `pos' to @code{endpos - 1} will be searched for a match.  If `endpos' is less
than `pos', no match will be found; otherwise, if `rx' is a compiled regular
expression object, @code{rx.search(string, 0, 50)} is equivalent to
@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 prefixmatch() (μέθοδος της re.Pattern)
@anchor{library/re re Pattern prefixmatch}@anchor{24b}
@deffn {Μέθοδος} Pattern.prefixmatch (string[, pos[, endpos]])

If zero or more characters at the `beginning' of `string' match this regular
expression, return a corresponding @ref{1085,,Match}. Return @code{None} if the
string does not match the pattern; note that this is different from a
zero-length match.

Note that even in @ref{297e,,MULTILINE} mode, this will only match at the
beginning of the string and not at the beginning of each line.

The optional `pos' and `endpos' parameters have the same meaning as for the
@ref{298e,,search()} method.

@example
>>> pattern = re.compile("o")
>>> pattern.prefixmatch("dog")     # No match as "o" is not at the start of "dog".
>>> pattern.prefixmatch("dog", 1)  # Match as "o" is the 2nd character of "dog".
<re.Match object; span=(1, 2), match='o'>
@end example

If you want to locate a match anywhere in `string', use
@ref{298e,,search()} instead (see also @ref{298f,,search() vs. prefixmatch()}).

This method now has two names and has long been known as
@ref{24d,,match()}.  Use that name when you need to retain compatibility
with older Python versions.


Added in version 3.15.

@end deffn

@geindex match() (μέθοδος της re.Pattern)
@anchor{library/re re Pattern match}@anchor{24d}
@deffn {Μέθοδος} Pattern.match (string[, pos[, endpos]])


@ref{1a7,,Soft deprecated} since version 3.15: @code{match()} has been soft deprecated in favor of
the alternate @ref{24b,,prefixmatch()} name of this API which is
more explicitly descriptive. Use it to
better express intent. The norm in other languages and regular expression
implementations is to use the term `match' to refer to the behavior of
what Python has always called @ref{298e,,search()}.
See @ref{2f9,,prefixmatch() vs. match()}.

@end deffn

@geindex fullmatch() (μέθοδος της re.Pattern)
@anchor{library/re re Pattern fullmatch}@anchor{1330}
@deffn {Μέθοδος} Pattern.fullmatch (string[, pos[, endpos]])

If the whole `string' matches this regular expression, return a corresponding
@ref{1085,,Match}.  Return @code{None} if the string does not match the pattern;
note that this is different from a zero-length match.

The optional `pos' and `endpos' parameters have the same meaning as for the
@ref{298e,,search()} method.

@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


Added in version 3.4.

@end deffn

@geindex split() (μέθοδος της re.Pattern)
@anchor{library/re re Pattern split}@anchor{2993}
@deffn {Μέθοδος} Pattern.split (string, maxsplit=0)

Identical to the @ref{7a0,,split()} function, using the compiled pattern.
@end deffn

@geindex findall() (μέθοδος της re.Pattern)
@anchor{library/re re Pattern findall}@anchor{2994}
@deffn {Μέθοδος} Pattern.findall (string[, pos[, endpos]])

Similar to the @ref{13d2,,findall()} function, using the compiled pattern, but
also accepts optional `pos' and `endpos' parameters that limit the search
region like for @ref{15d3,,search()}.
@end deffn

@geindex finditer() (μέθοδος της re.Pattern)
@anchor{library/re re Pattern finditer}@anchor{2995}
@deffn {Μέθοδος} Pattern.finditer (string[, pos[, endpos]])

Similar to the @ref{189c,,finditer()} function, using the compiled pattern, but
also accepts optional `pos' and `endpos' parameters that limit the search
region like for @ref{15d3,,search()}.
@end deffn

@geindex sub() (μέθοδος της re.Pattern)
@anchor{library/re re Pattern sub}@anchor{2996}
@deffn {Μέθοδος} Pattern.sub (repl, string, count=0)

Identical to the @ref{7a1,,sub()} function, using the compiled pattern.
@end deffn

@geindex subn() (μέθοδος της re.Pattern)
@anchor{library/re re Pattern subn}@anchor{2997}
@deffn {Μέθοδος} Pattern.subn (repl, string, count=0)

Identical to the @ref{7a2,,subn()} function, using the compiled pattern.
@end deffn

@geindex flags (ιδιότητα της re.Pattern)
@anchor{library/re re Pattern flags}@anchor{2998}
@deffn {Ιδιότητα} Pattern.flags

The regex matching flags.  This is a combination of the flags given to
@ref{f93,,compile()}, any @code{(?...)} inline flags in the pattern, and implicit
flags such as @ref{f2a,,UNICODE} if the pattern is a Unicode string.
@end deffn

@geindex groups (ιδιότητα της re.Pattern)
@anchor{library/re re Pattern groups}@anchor{2999}
@deffn {Ιδιότητα} Pattern.groups

The number of capturing groups in the pattern.
@end deffn

@geindex groupindex (ιδιότητα της re.Pattern)
@anchor{library/re re Pattern groupindex}@anchor{299a}
@deffn {Ιδιότητα} Pattern.groupindex

A dictionary mapping any symbolic group names defined by @code{(?P<id>)} to group
numbers.  The dictionary is empty if no symbolic groups were used in the
pattern.
@end deffn

@geindex pattern (ιδιότητα της re.Pattern)
@anchor{library/re re Pattern pattern}@anchor{299b}
@deffn {Ιδιότητα} Pattern.pattern

The pattern string from which the pattern object was compiled.
@end deffn


Άλλαξε στην έκδοση 3.7: Added support of @ref{942,,copy.copy()} and @ref{f2b,,copy.deepcopy()}.  Compiled
regular expression objects are considered atomic.


@node Match objects,Regular expression examples,Regular expression objects,re — Regular expression operations
@anchor{library/re id3}@anchor{299c}@anchor{library/re match-objects}@anchor{1332}
@subsubsection Match objects


Match objects always have a boolean value of @code{True}.
Since @ref{24d,,match()} and @ref{298e,,search()} return @code{None}
when there is no match, you can test whether there was a match with a simple
@code{if} statement:

@example
if match := re.search(pattern, string):
    process(match)
@end example

@geindex Match (κλάση σε re)
@anchor{library/re re Match}@anchor{1085}
@deffn {Κλάση} re.Match

Match object returned by successful @code{match}es and @code{search}es.


Άλλαξε στην έκδοση 3.9: @ref{1085,,re.Match} supports @code{[]} to indicate a Unicode (str) or bytes match.
See @ref{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex expand() (μέθοδος της re.Match)
@anchor{library/re re Match expand}@anchor{299d}
@deffn {Μέθοδος} Match.expand (template)

Return the string obtained by doing backslash substitution on the template
string `template', as done by the @ref{2996,,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.


Άλλαξε στην έκδοση 3.5: Unmatched groups are replaced with an empty string.

@end deffn

@geindex group() (μέθοδος της re.Match)
@anchor{library/re re Match group}@anchor{13d3}
@deffn {Μέθοδος} Match.group ([group1, ...])

Returns one or more subgroups of the match.  If there is a single argument, the
result is a single string; if there are multiple arguments, the result is a
tuple with one item per argument. Without arguments, `group1' defaults to zero
(the whole match is returned). If a `groupN' argument is zero, the corresponding
return value is the entire matching string; if it is a positive integer, it is
the string matching the corresponding parenthesized group.  If a group number is
negative or larger than the number of groups defined in the pattern, an
@ref{18d7,,IndexError} exception is raised. If a group is contained in a
part of the pattern that did not match, the corresponding result is @code{None}.
If a group is contained in a part of the pattern that matched multiple times,
the last match is returned.

@example
>>> m = re.search(r"\A(\w+) (\w+)", "Norwegian Blue, pining for the fjords")
>>> m.group(0)       # The entire match
'Norwegian Blue'
>>> m.group(1)       # The first parenthesized subgroup.
'Norwegian'
>>> m.group(2)       # The second parenthesized subgroup.
'Blue'
>>> m.group(1, 2)    # Multiple arguments give us a tuple.
('Norwegian', 'Blue')
@end example

If the regular expression uses the @code{(?P<name>...)} syntax, the `groupN'
arguments may also be strings identifying groups by their group name.  If a
string argument is not used as a group name in the pattern, an @ref{18d7,,IndexError}
exception is raised.

A moderately complicated example:

@example
>>> m = re.search(r"(?P<adjective>\w+) (?P<animal>\w+)", "killer rabbit")
>>> m.group('adjective')
'killer'
>>> m.group('animal')
'rabbit'
@end example

Named groups can also be referred to by their index:

@example
>>> m.group(1)
'killer'
>>> m.group(2)
'rabbit'
@end example

If a group matches multiple times, only the last match is accessible:

@example
>>> m = re.search(r"(..)+", "a1b2c3")  # Matches 3 times.
>>> m.group(1)                         # Returns only the last match.
'c3'
@end example
@end deffn

@geindex __getitem__() (μέθοδος της re.Match)
@anchor{library/re re Match __getitem__}@anchor{299e}
@deffn {Μέθοδος} Match.__getitem__ (g)

This is identical to @code{m.group(g)}.  This allows easier access to
an individual group from a match:

@example
>>> m = re.search(r"(\w+) (\w+)", "Norwegian Blue, pining for the fjords")
>>> m[0]       # The entire match
'Norwegian Blue'
>>> m[1]       # The first parenthesized subgroup.
'Norwegian'
>>> m[2]       # The second parenthesized subgroup.
'Blue'
@end example

Named groups are supported as well:

@example
>>> m = re.search(r"(?P<adjective>\w+) (?P<animal>\w+)", "killer rabbit")
>>> m['adjective']
'killer'
>>> m['animal']
'rabbit'
@end example


Added in version 3.6.

@end deffn

@geindex groups() (μέθοδος της re.Match)
@anchor{library/re re Match groups}@anchor{13d4}
@deffn {Μέθοδος} Match.groups (default=None)

Return a tuple containing all the subgroups of the match, from 1 up to however
many groups are in the pattern.  The `default' argument is used for groups that
did not participate in the match; it defaults to @code{None}.

For example:

@example
>>> m = re.search(r"(\d+)\.(\d+)", "24.1632")
>>> m.groups()
('24', '1632')
@end example

If we make the decimal place and everything after it optional, not all groups
might participate in the match.  These groups will default to @code{None} unless
the `default' argument is given:

@example
>>> m = re.search(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() (μέθοδος της re.Match)
@anchor{library/re re Match groupdict}@anchor{299f}
@deffn {Μέθοδος} Match.groupdict (default=None)

Return a dictionary containing all the `named' subgroups of the match, keyed by
the subgroup name.  The `default' argument is used for groups that did not
participate in the match; it defaults to @code{None}.  For example:

@example
>>> m = re.search(r"(?P<adjective>\w+) (?P<animal>\w+)", "killer rabbit")
>>> m.groupdict()
@{'adjective': 'killer', 'animal': 'rabbit'@}
@end example
@end deffn

@geindex start() (μέθοδος της re.Match)
@geindex end() (μέθοδος της re.Match)
@anchor{library/re re Match start}@anchor{29a0}
@deffn {Μέθοδος} Match.start ([group])
@anchor{library/re re Match end}@anchor{29a1}
@deffnx {Μέθοδος} Match.end ([group])

Return the indices of the start and end of the substring matched by `group';
`group' defaults to zero (meaning the whole matched substring). Return @code{-1} if
`group' exists but did not contribute to the match.  For a match object `m', and
a group `g' that did contribute to the match, the substring matched by group `g'
(equivalent to @code{m.group(g)}) is

@example
m.string[m.start(g):m.end(g)]
@end example

Note that @code{m.start(group)} will equal @code{m.end(group)} if `group' matched a
null string.  For example, after @code{m = re.search('b(c?)', 'cba')},
@code{m.start(0)} is 1, @code{m.end(0)} is 2, @code{m.start(1)} and @code{m.end(1)} are both
2, and @code{m.start(2)} raises an @ref{18d7,,IndexError} exception.

An example that will remove `remove_this' from email addresses:

@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() (μέθοδος της re.Match)
@anchor{library/re re Match span}@anchor{29a2}
@deffn {Μέθοδος} Match.span ([group])

For a match `m', return the 2-tuple @code{(m.start(group), m.end(group))}. Note
that if `group' did not contribute to the match, this is @code{(-1, -1)}.
`group' defaults to zero, the entire match.
@end deffn

@geindex pos (ιδιότητα της re.Match)
@anchor{library/re re Match pos}@anchor{29a3}
@deffn {Ιδιότητα} Match.pos

The value of `pos' which was passed to the @ref{298e,,search()} or
@ref{24d,,match()} method of a @ref{1331,,regex object}.  This is
the index into the string at which the RE engine started looking for a match.
@end deffn

@geindex endpos (ιδιότητα της re.Match)
@anchor{library/re re Match endpos}@anchor{29a4}
@deffn {Ιδιότητα} Match.endpos

The value of `endpos' which was passed to the @ref{298e,,search()} or
@ref{24d,,match()} method of a @ref{1331,,regex object}.  This is
the index into the string beyond which the RE engine will not go.
@end deffn

@geindex lastindex (ιδιότητα της re.Match)
@anchor{library/re re Match lastindex}@anchor{29a5}
@deffn {Ιδιότητα} Match.lastindex

The integer index of the last matched capturing group, or @code{None} if no group
was matched at all. For example, the expressions @code{(a)b}, @code{((a)(b))}, and
@code{((ab))} will have @code{lastindex == 1} if applied to the string @code{'ab'}, while
the expression @code{(a)(b)} will have @code{lastindex == 2}, if applied to the same
string.
@end deffn

@geindex lastgroup (ιδιότητα της re.Match)
@anchor{library/re re Match lastgroup}@anchor{29a6}
@deffn {Ιδιότητα} Match.lastgroup

The name of the last matched capturing group, or @code{None} if the group didn’t
have a name, or if no group was matched at all.
@end deffn

@geindex re (ιδιότητα της re.Match)
@anchor{library/re re Match re}@anchor{29a7}
@deffn {Ιδιότητα} Match.re

The @ref{1331,,regular expression object} whose @ref{24d,,match()} or
@ref{298e,,search()} method produced this match instance.
@end deffn

@geindex string (ιδιότητα της re.Match)
@anchor{library/re re Match string}@anchor{29a8}
@deffn {Ιδιότητα} Match.string

The string passed to @ref{24d,,match()} or @ref{298e,,search()}.
@end deffn


Άλλαξε στην έκδοση 3.7: Added support of @ref{942,,copy.copy()} and @ref{f2b,,copy.deepcopy()}.  Match objects
are considered atomic.


@node Regular expression examples,,Match objects,re — Regular expression operations
@anchor{library/re re-examples}@anchor{1602}@anchor{library/re regular-expression-examples}@anchor{29a9}
@subsubsection Regular expression examples


@menu
* Checking for a pair:: 
* Simulating scanf(): Simulating scanf. 
* search() vs. prefixmatch(): search vs prefixmatch. 
* prefixmatch() vs. match(): prefixmatch vs match. 
* Making a phonebook:: 
* Text munging:: 
* Finding all adverbs:: 
* Finding all adverbs and their positions:: 
* Raw string notation:: 
* Writing a tokenizer:: 

@end menu

@node Checking for a pair,Simulating scanf,,Regular expression examples
@anchor{library/re checking-for-a-pair}@anchor{29aa}
@subsubsection Checking for a pair


In this example, we’ll use the following helper function to display match
objects a little more gracefully:

@example
def displaymatch(match):
    if match is None:
        return None
    return '<Match: %r, groups=%r>' % (match.group(), match.groups())
@end example

Suppose you are writing a poker program where a player’s hand is represented as
a 5-character string with each character representing a card, «a» for ace, «k»
for king, «q» for queen, «j» for jack, «t» for 10, and «2» through «9»
representing the card with that value.

To see if a given string is a valid hand, one could do the following:

@example
>>> valid_hand_re = re.compile(r"^[a2-9tjqk]@{5@}$")
>>> displaymatch(valid_hand_re.search("akt5q"))  # Valid.
"<Match: 'akt5q', groups=()>"
>>> displaymatch(valid_hand_re.search("akt5e"))  # Invalid.
>>> displaymatch(valid_hand_re.search("akt"))    # Invalid.
>>> displaymatch(valid_hand_re.search("727ak"))  # Valid.
"<Match: '727ak', groups=()>"
@end example

That last hand, @code{"727ak"}, contained a pair, or two of the same valued cards.
To match this with a regular expression, one could use backreferences as such:

@example
>>> pair_re = re.compile(r".*(.).*\1")
>>> displaymatch(pair_re.prefixmatch("717ak"))     # Pair of 7s.
"<Match: '717', groups=('7',)>"
>>> displaymatch(pair_re.prefixmatch("718ak"))     # No pairs.
>>> displaymatch(pair_re.prefixmatch("354aa"))     # Pair of aces.
"<Match: '354aa', groups=('a',)>"
@end example

To find out what card the pair consists of, one could use the
@ref{13d3,,group()} method of the match object in the following manner:

@example
>>> pair_re = re.compile(r".*(.).*\1")
>>> pair_re.prefixmatch("717ak").group(1)
'7'

# Error because prefixmatch() returns None, which doesn't have a group() method:
>>> pair_re.prefixmatch("718ak").group(1)
Traceback (most recent call last):
  File "<pyshell#23>", line 1, in <module>
    pair_re.prefixmatch("718ak").group(1)
AttributeError: 'NoneType' object has no attribute 'group'

>>> pair_re.prefixmatch("354aa").group(1)
'a'
@end example

@node Simulating scanf,search vs prefixmatch,Checking for a pair,Regular expression examples
@anchor{library/re simulating-scanf}@anchor{29ab}
@subsubsection Simulating 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

Regular Expression

@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


To extract the filename and numbers from a string like:

@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

The equivalent regular expression would be:

@example
(\S+) - (\d+) errors, (\d+) warnings
@end example

@node search vs prefixmatch,prefixmatch vs match,Simulating scanf,Regular expression examples
@anchor{library/re search-vs-match}@anchor{298f}@anchor{library/re search-vs-prefixmatch}@anchor{29ac}
@subsubsection search() vs. prefixmatch()


Python offers different primitive operations based on regular expressions:


@itemize +

@item 
@ref{24a,,re.prefixmatch()} checks for a match only at the beginning of the string

@item 
@ref{15d3,,re.search()} checks for a match anywhere in the string
(this is what Perl does by default)

@item 
@ref{132f,,re.fullmatch()} checks for entire string to be a match
@end itemize

For example:

@example
>>> re.prefixmatch("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

Regular expressions beginning with @code{'^'} can be used with @ref{15d3,,search()} to
restrict the match at the beginning of the string:

@example
>>> re.prefixmatch("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

Note however that in @ref{297e,,MULTILINE} mode @ref{24a,,prefixmatch()} only matches at the
beginning of the string, whereas using @ref{15d3,,search()} with a regular expression
beginning with @code{'^'} will match at the beginning of each line.

@example
>>> re.prefixmatch("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 prefixmatch vs match,Making a phonebook,search vs prefixmatch,Regular expression examples
@anchor{library/re id4}@anchor{29ad}@anchor{library/re prefixmatch-vs-match}@anchor{2f9}
@subsubsection prefixmatch() vs. match()


Why is the @ref{24c,,match()} function and method discouraged in
favor of the longer @ref{24a,,prefixmatch()} spelling?

Many other languages have gained regex support libraries since regular
expressions were added to Python. However in the most popular of those, they
use the term `match' in their APIs to mean the unanchored behavior provided in
Python by @ref{15d3,,search()}. Thus use of the plain term `match' can be
unclear to those used to other languages when reading or writing code and
not familiar with the Python API’s divergence from what otherwise become the
industry norm.

Quoting from the Zen Of Python (@code{python3 -m this}): `«Explicit is better than
implicit»'. Anyone reading the name @code{prefixmatch()} is likely to
understand the intended semantics. When reading @code{match()} there remains
a seed of doubt about the intended behavior to anyone not already familiar with
this old Python gotcha.

We `do not' plan to remove the older @code{match()} name,
as it has been used in code for over 30 years.
It has been @ref{1a7,,soft deprecated}:
code supporting older versions of Python should continue to use @code{match()},
while new code should prefer @code{prefixmatch()}.


Added in version 3.15: @code{prefixmatch()}



@ref{1a7,,Soft deprecated} since version 3.15: @code{match()}


@node Making a phonebook,Text munging,prefixmatch vs match,Regular expression examples
@anchor{library/re making-a-phonebook}@anchor{29ae}
@subsubsection Making a phonebook


@ref{7a0,,split()} splits a string into a list delimited by the passed pattern.  The
method is invaluable for converting textual data into data structures that can be
easily read and modified by Python as demonstrated in the following example that
creates a phonebook.

First, here is the input.  Normally it may come from a file, here we are using
triple-quoted string syntax

@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

The entries are separated by one or more newlines. Now we convert the string
into a list with each nonempty line having its own entry:

@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

Finally, split each entry into a list with first name, last name, telephone
number, and address.  We use the @code{maxsplit} parameter of @ref{7a0,,split()}
because the address has spaces, our splitting pattern, in it:

@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

The @code{:?} pattern matches the colon after the last name, so that it does not
occur in the result list.  With a @code{maxsplit} of @code{4}, we could separate the
house number from the street name:

@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 Text munging,Finding all adverbs,Making a phonebook,Regular expression examples
@anchor{library/re text-munging}@anchor{29af}
@subsubsection Text munging


@ref{7a1,,sub()} replaces every occurrence of a pattern with a string or the
result of a function.  This example demonstrates using @code{sub()} with
a function to «munge» text, or randomize the order of all the characters
in each word of a sentence except for the first and last characters:

@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 Finding all adverbs,Finding all adverbs and their positions,Text munging,Regular expression examples
@anchor{library/re finding-all-adverbs}@anchor{29b0}
@subsubsection Finding all adverbs


@ref{13d2,,findall()} matches `all' occurrences of a pattern, not just the first
one as @ref{15d3,,search()} does.  For example, if a writer wanted to
find all of the adverbs in some text, they might use @code{findall()} in
the following manner:

@example
>>> text = "He was carefully disguised but captured quickly by police."
>>> re.findall(r"\w+ly\b", text)
['carefully', 'quickly']
@end example

@node Finding all adverbs and their positions,Raw string notation,Finding all adverbs,Regular expression examples
@anchor{library/re finding-all-adverbs-and-their-positions}@anchor{29b1}
@subsubsection Finding all adverbs and their positions


If one wants more information about all matches of a pattern than the matched
text, @ref{189c,,finditer()} is useful as it provides @ref{1085,,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
@code{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 Raw string notation,Writing a tokenizer,Finding all adverbs and their positions,Regular expression examples
@anchor{library/re raw-string-notation}@anchor{29b2}
@subsubsection Raw string notation


Raw string notation (@code{r"text"}) keeps regular expressions sane.  Without it,
every backslash (@code{'\'}) in a regular expression would have to be prefixed with
another one to escape it.  For example, the two following lines of code are
functionally identical:

@example
>>> re.search(r"\W(.)\1\W", " ff ")
<re.Match object; span=(0, 4), match=' ff '>
>>> re.search("\\W(.)\\1\\W", " ff ")
<re.Match object; span=(0, 4), match=' ff '>
@end example

When one wants to match a literal backslash, it must be escaped in the regular
expression.  With raw string notation, this means @code{r"\\"}.  Without raw string
notation, one must use @code{"\\\\"}, making the following lines of code
functionally identical:

@example
>>> re.search(r"\\", r"\\")
<re.Match object; span=(0, 1), match='\\'>
>>> re.search("\\\\", r"\\")
<re.Match object; span=(0, 1), match='\\'>
@end example

@node Writing a tokenizer,,Raw string notation,Regular expression examples
@anchor{library/re writing-a-tokenizer}@anchor{29b3}
@subsubsection Writing a tokenizer


A tokenizer or scanner@footnote{https://en.wikipedia.org/wiki/Lexical_analysis}
analyzes a string to categorize groups of characters.  This is a useful first
step in writing a compiler or interpreter.

The text categories are specified with regular expressions.  The technique is
to combine those into a single master regular expression and to loop over
successive matches:

@example
from typing import NamedTuple
import re

class Token(NamedTuple):
    type: str
    value: int | float | 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

The tokenizer produces the following output:

@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{297b}@w{(Frie09)} 
Friedl, Jeffrey. Mastering Regular Expressions. 3rd ed., O’Reilly Media, 2009. The third edition of the book no longer covers Python at all, but the first edition covered writing good regular expression patterns in great detail.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node difflib — Helpers for computing deltas,textwrap — Περιτύλιγμα και γέμισμα κειμένου,re — Regular expression operations,Text Processing Services
@anchor{library/difflib doc}@anchor{29b4}@anchor{library/difflib difflib-helpers-for-computing-deltas}@anchor{29b5}@anchor{library/difflib module-difflib}@anchor{3a}@anchor{library/difflib translation-repo}@anchor{29b6}
@subsection @code{difflib} — Helpers for computing deltas


@geindex module; difflib

`Source code:' Lib/difflib.py@footnote{https://github.com/python/cpython/tree/main/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{5d,,filecmp} module.


@deffn {Κλάση} difflib.SequenceMatcher

This is a flexible class for comparing pairs of sequences of any type, so long
as the sequence elements are @ref{183,,hashable}.  The basic algorithm predates, and is a
little fancier than, an algorithm published in the late 1980’s by Ratcliff and
Obershelp under the hyperbolic name «gestalt pattern matching.»  The idea is to
find the longest contiguous matching subsequence that contains no «junk»
elements; these «junk» elements are ones that are uninteresting in some
sense, such as blank lines or whitespace.  (Handling junk is an
extension to the Ratcliff and Obershelp algorithm.) The same
idea is then applied recursively to the pieces of the sequences to the left and
to the right of the matching subsequence.  This does not yield minimal edit
sequences, but does tend to yield matches that «look right» to people.

`Timing:' The basic Ratcliff-Obershelp algorithm is cubic time in the worst
case and quadratic time in the expected case. @ref{13c2,,SequenceMatcher} is
quadratic time for the worst case and has expected-case behavior dependent in a
complicated way on how many elements the sequences have in common; best case
time is linear.

`Automatic junk heuristic:' @ref{13c2,,SequenceMatcher} supports a heuristic that
automatically treats certain sequence items as junk. The heuristic counts how many
times each individual item appears in the sequence. If an item’s duplicates (after
the first one) account for more than 1% of the sequence and the sequence is at least
200 items long, this item is marked as «popular» and is treated as junk for
the purpose of sequence matching. This heuristic can be turned off by setting
the @code{autojunk} argument to @code{False} when creating the @code{SequenceMatcher}.


Άλλαξε στην έκδοση 3.2: Added the `autojunk' parameter.

@end deffn

@geindex Differ (κλάση σε difflib)
@anchor{library/difflib difflib Differ}@anchor{29b7}
@deffn {Κλάση} difflib.Differ

This is a class for comparing sequences of lines of text, and producing
human-readable differences or deltas.  Differ uses @ref{13c2,,SequenceMatcher}
both to compare sequences of lines, and to compare sequences of characters
within similar (near-matching) lines.

Each line of a @code{Differ} delta begins with a two-letter code:


@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Code

@tab

Meaning

@item

@code{'- '}

@tab

line unique to sequence 1

@item

@code{'+ '}

@tab

line unique to sequence 2

@item

@code{'  '}

@tab

line common to both sequences

@item

@code{'? '}

@tab

line not present in either input sequence

@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 (κλάση σε difflib)
@anchor{library/difflib difflib HtmlDiff}@anchor{214}
@deffn {Κλάση} difflib.HtmlDiff

This class can be used to create an HTML table (or a complete HTML file
containing the table) showing a side by side, line by line comparison of text
with inter-line and intra-line change highlights.  The table can be generated in
either full or contextual difference mode.

The constructor for this class is:

@geindex __init__() (μέθοδος της difflib.HtmlDiff)
@anchor{library/difflib difflib HtmlDiff __init__}@anchor{29b8}
@deffn {Μέθοδος} __init__ (tabsize=8, wrapcolumn=None, linejunk=None, charjunk=IS_CHARACTER_JUNK)

Initializes instance of @code{HtmlDiff}.

`tabsize' is an optional keyword argument to specify tab stop spacing and
defaults to @code{8}.

`wrapcolumn' is an optional keyword to specify column number where lines are
broken and wrapped, defaults to @code{None} where lines are not wrapped.

`linejunk' and `charjunk' are optional keyword arguments passed into @ref{29b9,,ndiff()}
(used by @code{HtmlDiff} to generate the side by side HTML differences).  See
@code{ndiff()} documentation for argument default values and descriptions.
@end deffn

The following methods are public:

@geindex make_file() (μέθοδος της difflib.HtmlDiff)
@anchor{library/difflib difflib HtmlDiff make_file}@anchor{11a8}
@deffn {Μέθοδος} make_file (fromlines, tolines, fromdesc='@w{'}, todesc='@w{'}, context=False, numlines=5, *, charset='utf-8')

Compares `fromlines' and `tolines' (lists of strings) and returns a string which
is a complete HTML file containing a table showing line by line differences with
inter-line and intra-line changes highlighted.

`fromdesc' and `todesc' are optional keyword arguments to specify from/to file
column header strings (both default to an empty string).

`context' and `numlines' are both optional keyword arguments. Set `context' to
@code{True} when contextual differences are to be shown, else the default is
@code{False} to show the full files. `numlines' defaults to @code{5}.  When `context'
is @code{True} `numlines' controls the number of context lines which surround the
difference highlights.  When `context' is @code{False} `numlines' controls the
number of lines which are shown before a difference highlight when using the
«next» hyperlinks (setting to zero would cause the «next» hyperlinks to place
the next difference highlight at the top of the browser without any leading
context).

@cartouche
@quotation Σημείωση 
`fromdesc' and `todesc' are interpreted as unescaped HTML and should be
properly escaped while receiving input from untrusted sources.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.5: `charset' keyword-only argument was added.  The default charset of
HTML document changed from @code{'ISO-8859-1'} to @code{'utf-8'}.

@end deffn

@geindex make_table() (μέθοδος της difflib.HtmlDiff)
@anchor{library/difflib difflib HtmlDiff make_table}@anchor{29ba}
@deffn {Μέθοδος} make_table (fromlines, tolines, fromdesc='@w{'}, todesc='@w{'}, context=False, numlines=5)

Compares `fromlines' and `tolines' (lists of strings) and returns a string which
is a complete HTML table showing line by line differences with inter-line and
intra-line changes highlighted.

The arguments for this method are the same as those for the @ref{11a8,,make_file()}
method.
@end deffn
@end deffn

@geindex context_diff() (στη μονάδα difflib)
@anchor{library/difflib difflib context_diff}@anchor{1b97}
@deffn {Συνάρτηση} difflib.context_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{1409,,generator}
generating the delta lines) in context diff format.

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.

By default, the diff control lines (those with @code{***} or @code{---}) are created
with a trailing newline.  This is helpful so that inputs created from
@ref{29bb,,io.IOBase.readlines()} result in diffs that are suitable for use with
@ref{197c,,io.IOBase.writelines()} since both the inputs and outputs have trailing
newlines.

For inputs that do not have trailing newlines, set the `lineterm' argument to
@code{""} so that the output will be uniformly newline free.

The context 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
>>> 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

See @ref{29bc,,A command-line interface to difflib} for a more detailed example.
@end deffn

@geindex get_close_matches() (στη μονάδα difflib)
@anchor{library/difflib difflib get_close_matches}@anchor{197d}
@deffn {Συνάρτηση} 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() (στη μονάδα difflib)
@anchor{library/difflib difflib ndiff}@anchor{29b9}
@deffn {Συνάρτηση} difflib.ndiff (a, b, linejunk=None, charjunk=IS_CHARACTER_JUNK)

Compare `a' and `b' (lists of strings); return a @ref{29b7,,Differ}-style
delta (a @ref{1409,,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{552,,IS_LINE_JUNK()}, which filters out lines
without visible characters, except for at most one hash character (@code{'#'})
– however the underlying @ref{13c2,,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{29bd,,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() (στη μονάδα difflib)
@anchor{library/difflib difflib restore}@anchor{29be}
@deffn {Συνάρτηση} difflib.restore (sequence, which)

Return one of the two sequences that generated a delta.

Given a `sequence' produced by @ref{29bf,,Differ.compare()} or @ref{29b9,,ndiff()}, extract
lines originating from file 1 or 2 (parameter `which'), stripping off line
prefixes.

Example:

@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() (στη μονάδα difflib)
@anchor{library/difflib difflib unified_diff}@anchor{213}
@deffn {Συνάρτηση} difflib.unified_diff (a, b, fromfile='@w{'}, tofile='@w{'}, fromfiledate='@w{'}, tofiledate='@w{'}, n=3, lineterm='\n', *, color=False)

Compare `a' and `b' (lists of strings); return a delta (a @ref{1409,,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{29bb,,io.IOBase.readlines()} result in diffs that are suitable for use with
@ref{197c,,io.IOBase.writelines()} since both the inputs and outputs have trailing
newlines.

For inputs that do not have trailing newlines, set the `lineterm' argument to
@code{""} so that the output will be uniformly newline free.

Set `color' to @code{True} to enable output in color, similar to
@code{git diff --color}. Even if enabled, it can be
@ref{1af,,controlled using environment variables}.

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

See @ref{29bc,,A command-line interface to difflib} for a more detailed example.


Άλλαξε στην έκδοση 3.15: Added the `color' parameter.

@end deffn

@geindex diff_bytes() (στη μονάδα difflib)
@anchor{library/difflib difflib diff_bytes}@anchor{11a9}
@deffn {Συνάρτηση} 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{213,,unified_diff()} or
@ref{1b97,,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'.


Added in version 3.5.

@end deffn

@geindex IS_LINE_JUNK() (στη μονάδα difflib)
@anchor{library/difflib difflib IS_LINE_JUNK}@anchor{552}
@deffn {Συνάρτηση} 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{29b9,,ndiff()} in older versions.
@end deffn

@geindex IS_CHARACTER_JUNK() (στη μονάδα difflib)
@anchor{library/difflib difflib IS_CHARACTER_JUNK}@anchor{29bd}
@deffn {Συνάρτηση} 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{29b9,,ndiff()}.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Pattern Matching: The Gestalt Approach@footnote{https://jacobfilipp.com/DrDobbs/articles/DDJ/1988/8807/8807c/8807c.htm}

Discussion of a similar algorithm by John W. Ratcliff and D. E. Metzener. This
was published in Dr. Dobb’s Journal 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{29c0}@anchor{library/difflib sequencematcher-objects}@anchor{29c1}
@subsubsection SequenceMatcher objects


The @ref{13c2,,SequenceMatcher} class has this constructor:

@geindex SequenceMatcher (κλάση σε difflib)
@anchor{library/difflib difflib SequenceMatcher}@anchor{13c2}
@deffn {Κλάση} 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{183,,hashable}.

The optional argument `autojunk' can be used to disable the automatic junk
heuristic.


Άλλαξε στην έκδοση 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{29c2,,set_seqs()} or @ref{29c3,,set_seq2()}.


Added in version 3.2: The `bjunk' and `bpopular' attributes.


@code{SequenceMatcher} objects have the following methods:

@geindex set_seqs() (μέθοδος της difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher set_seqs}@anchor{29c2}
@deffn {Μέθοδος} set_seqs (a, b)

Set the two sequences to be compared.
@end deffn

@code{SequenceMatcher} computes and caches detailed information about the
second sequence, so if you want to compare one sequence against many
sequences, use @ref{29c3,,set_seq2()} to set the commonly used sequence once and
call @ref{29c4,,set_seq1()} repeatedly, once for each of the other sequences.

@geindex set_seq1() (μέθοδος της difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher set_seq1}@anchor{29c4}
@deffn {Μέθοδος} set_seq1 (a)

Set the first sequence to be compared.  The second sequence to be compared
is not changed.
@end deffn

@geindex set_seq2() (μέθοδος της difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher set_seq2}@anchor{29c3}
@deffn {Μέθοδος} 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() (μέθοδος της difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher find_longest_match}@anchor{1f3f}
@deffn {Μέθοδος} 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}, @code{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{a3d,,named tuple} @code{Match(a, b, size)}.


Άλλαξε στην έκδοση 3.9: Added default arguments.

@end deffn

@geindex get_matching_blocks() (μέθοδος της difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher get_matching_blocks}@anchor{29c5}
@deffn {Μέθοδος} 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() (μέθοδος της difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher get_opcodes}@anchor{29c6}
@deffn {Μέθοδος} 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

Value

@tab

Meaning

@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


For example:

@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() (μέθοδος της difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher get_grouped_opcodes}@anchor{29c7}
@deffn {Μέθοδος} get_grouped_opcodes (n=3)

Return a @ref{1409,,generator} of groups with up to `n' lines of context.

Starting with the groups returned by @ref{29c6,,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{29c6,,get_opcodes()}.
@end deffn

@geindex ratio() (μέθοδος της difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher ratio}@anchor{29c8}
@deffn {Μέθοδος} 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{29c5,,get_matching_blocks()} or
@ref{29c6,,get_opcodes()} hasn’t already been called, in which case you may want
to try @ref{29c9,,quick_ratio()} or @ref{29ca,,real_quick_ratio()} first to get an
upper bound.

@cartouche
@quotation Σημείωση 
Caution: The result of a @code{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() (μέθοδος της difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher quick_ratio}@anchor{29c9}
@deffn {Μέθοδος} quick_ratio ()

Return an upper bound on @ref{29c8,,ratio()} relatively quickly.
@end deffn

@geindex real_quick_ratio() (μέθοδος της difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher real_quick_ratio}@anchor{29ca}
@deffn {Μέθοδος} real_quick_ratio ()

Return an upper bound on @ref{29c8,,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{29c9,,quick_ratio()} and @ref{29ca,,real_quick_ratio()}
are always at least as large as @ref{29c8,,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{29cb}@anchor{library/difflib sequencematcher-examples}@anchor{29cc}
@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{29c8,,ratio()} returns a float in [0, 1], measuring the similarity of the
sequences.  As a rule of thumb, a @code{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{29c5,,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{29c5,,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{29c6,,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 Δείτε επίσης



@itemize *

@item 
The @ref{197d,,get_close_matches()} function in this module which shows how
simple code building on @ref{13c2,,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{13c2,,SequenceMatcher}.
@end itemize


@node Differ objects,Differ example,SequenceMatcher examples,difflib — Helpers for computing deltas
@anchor{library/difflib differ-objects}@anchor{29cd}@anchor{library/difflib id2}@anchor{29ce}
@subsubsection Differ objects


Note that @ref{29b7,,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{29b7,,Differ} class has this constructor:


@deffn {Κλάση} 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{1f3f,,find_longest_match()} method’s `isjunk'
parameter for an explanation.

@ref{29b7,,Differ} objects are used (deltas generated) via a single method:

@geindex compare() (μέθοδος της difflib.Differ)
@anchor{library/difflib difflib Differ compare}@anchor{29bf}
@deffn {Μέθοδος} 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{29bb,,readlines()} method of file-like objects.  The delta
generated also consists of newline-terminated strings, ready to be
printed as-is via the @ref{197c,,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{29cf}@anchor{library/difflib differ-examples}@anchor{29d0}
@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{29bb,,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{29b7,,Differ} object we may pass functions to
filter out line and character «junk.»  See the @ref{29b7,,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{29d1}@anchor{library/difflib difflib-interface}@anchor{29bc}
@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
import datetime as dt

def file_mtime(path):
    t = dt.datetime.fromtimestamp(os.stat(path).st_mtime,
                                  dt.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{29d2}
@subsubsection ndiff example


This example shows how to use @ref{29b9,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node textwrap — Περιτύλιγμα και γέμισμα κειμένου,unicodedata — Unicode Database,difflib — Helpers for computing deltas,Text Processing Services
@anchor{library/textwrap doc}@anchor{29d3}@anchor{library/textwrap module-textwrap}@anchor{f5}@anchor{library/textwrap textwrap-text-wrapping-and-filling}@anchor{29d4}@anchor{library/textwrap translation-repo}@anchor{29d5}
@subsection @code{textwrap} — Περιτύλιγμα και γέμισμα κειμένου


@geindex module; textwrap

`Πηγαίος κώδικας:' Lib/textwrap.py@footnote{https://github.com/python/cpython/tree/main/Lib/textwrap.py}


__________________________________________________________________


The @code{textwrap} module provides some convenience functions,
as well as @ref{1376,,TextWrapper}, the class that does all the work.
If you’re just wrapping or filling one or two text strings, the convenience
functions should be good enough; otherwise, you should use an instance of
@code{TextWrapper} for efficiency.

@geindex wrap() (στη μονάδα textwrap)
@anchor{library/textwrap textwrap wrap}@anchor{1869}
@deffn {Συνάρτηση} 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=' [...]')

Περιτυλίγει την ενιαία παράγραφο στο `text' (μία συμβολοσειρά) έτσι ώστε κάθε γραμμή να έχει το πολύ `width' αριθμό χαρακτήρες. Επιστρέφει μια λίστα με τις γραμμές εξόδου, χωρίς τελικούς χαρακτήρες νέας γραμμής.

Προαιρετικά ορίσματα λέξεων-κλειδιών αντιστοιχούν στις ιδιότητες στιγμιότυπου της @ref{1376,,TextWrapper}, που τεκμηριώνονται παρακάτω.

Δείτε τη μέθοδο @ref{29d6,,TextWrapper.wrap()} για πρόσθετες λεπτομέρειες σχετικά με το πώς συμπεριφέρεται η @ref{1869,,wrap()}.
@end deffn

@geindex fill() (στη μονάδα textwrap)
@anchor{library/textwrap textwrap fill}@anchor{1868}
@deffn {Συνάρτηση} 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=' [...]')

Γεμίζει την ενιαία παράγραφο στο `text' και επιστρέφει μια μοναδική συμβολοσειρά που περιέχει την γεμισμένη παράγραφο. Η @ref{1868,,fill()} είναι συντομογραφία για

@example
"\n".join(wrap(text, ...))
@end example

Συγκεκριμένα, η @ref{1868,,fill()} δέχεται ακριβώς τα ίδια ορίσματα λέξεων-κλειδιών με την @ref{1869,,wrap()}.
@end deffn

@geindex shorten() (στη μονάδα textwrap)
@anchor{library/textwrap textwrap shorten}@anchor{1379}
@deffn {Συνάρτηση} textwrap.shorten (text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')

Συμπτύξτε και περικόψτε το δοθέν `text' ώστε να χωράει στο δοθέν `width'.

Αρχικά, ο χώρος στο `text' συμπτύσσεται (όλος ο χώρος αντικαθίσταται με μονά κενά). Αν το αποτέλεσμα χωράει στο `width', επιστρέφεται. Διαφορετικά, αρκετές λέξεις απορρίπτονται από το τέλος ώστε οι υπόλοιπες λέξεις συν το `placeholder' να χωρούν μέσα στο `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

Προαιρετικά ορίσματα λέξεων-κλειδιών αντιστοιχούν στις ιδιότητες στιγμιότυπου της @ref{1376,,TextWrapper}, που τεκμηριώνονται παρακάτω. Σημειώστε ότι ο χώρος συμπτύσσεται πριν το κείμενο περαστεί στη συνάρτηση @ref{1868,,fill()} της @code{TextWrapper}, έτσι ώστε η αλλαγή της τιμής των @ref{29d7,,tabsize}, @ref{29d8,,expand_tabs}, @ref{29d9,,drop_whitespace} και @ref{29da,,replace_whitespace} να μην έχει καμία επίδραση.


Added in version 3.4.

@end deffn

@geindex dedent() (στη μονάδα textwrap)
@anchor{library/textwrap textwrap dedent}@anchor{55f}
@deffn {Συνάρτηση} textwrap.dedent (text)

Αφαιρεί οποιοδήποτε κοινό αρχικό κενό από κάθε γραμμή στο `text'.

Αυτό μπορεί να χρησιμοποιηθεί για να ευθυγραμμίσετε τις τριπλές παραθέσεις με την αριστερή άκρη της οθόνης, ενώ παρουσιάζονται στον πηγαίο κώδικα σε μορφή εσοχής.

Σημειώστε ότι τα tab και τα κενά θεωρούνται και τα δύο ως κενό, αλλά δεν είναι ίσα: οι γραμμές @code{"  hello"} και @code{"\thello"} θεωρούνται ότι δεν έχουν κοινό αρχικό κενό.

Οι γραμμές που περιέχουν μόνο κενό αγνοούνται στην είσοδο και κανονικοποιούνται σε έναν μόνο χαρακτήρα νέας γραμμής στην έξοδο.

Για παράδειγμα:

@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


Άλλαξε στην έκδοση 3.14: The @code{dedent()} function now correctly normalizes blank lines containing
only whitespace characters. Previously, the implementation only normalized
blank lines containing tabs and spaces.

@end deffn

@geindex indent() (στη μονάδα textwrap)
@anchor{library/textwrap textwrap indent}@anchor{77d}
@deffn {Συνάρτηση} textwrap.indent (text, prefix, predicate=None)

Προσθέτει το `prefix' στην αρχή των επιλεγμένων γραμμών στο `text'.

Οι γραμμές διαχωρίζονται καλώντας @code{text.splitlines(True)}.

Από προεπιλογή, το `prefix' προστίθεται σε όλες τις γραμμές που δεν αποτελούνται μόνο από κενό (συμπεριλαμβανομένων των χαρακτήρων τέλους γραμμής).

Για παράδειγμα:

@example
>>> s = 'hello\n\n \nworld'
>>> indent(s, '  ')
'  hello\n\n \n  world'
@end example

Το προαιρετικό όρισμα `predicate' μπορεί να χρησιμοποιηθεί για έλεγχο του ποια γραμμή θα έχει εσοχή. Για παράδειγμα, είναι εύκολο να προσθέσετε το `prefix' ακόμη και σε κενές γραμμές και γραμμές που περιέχουν μόνο κενό:

@example
>>> print(indent(s, '+ ', lambda line: True))
+ hello
+
+
+ world
@end example


Added in version 3.3.

@end deffn

Οι @ref{1869,,wrap()}, @ref{1868,,fill()} και @ref{1379,,shorten()} λειτουργούν δημιουργώντας ένα στιγμιότυπο της @ref{1376,,TextWrapper} και καλώντας μια μόνο μέθοδο σε αυτό. Αυτό το στιγμιότυπο δεν επαναχρησιμοποιείται, οπότε για εφαρμογές που επεξεργάζονται πολλά κείμενα χρησιμοποιώντας @code{wrap()} και/ή @code{fill()}, μπορεί να είναι πιο αποδοτικό να δημιουργήσετε το δικό σας αντικείμενο @code{TextWrapper}.

Το κείμενο προτιμάται να περιτυλίγεται σε κενά και αμέσως μετά τις παύλες σε λέξεις με παύλες· μόνο τότε θα σπάσουν οι μακριές λέξεις αν είναι αναγκαίο, εκτός εάν η @ref{29db,,TextWrapper.break_long_words} οριστεί σε false.

@geindex TextWrapper (κλάση σε textwrap)
@anchor{library/textwrap textwrap TextWrapper}@anchor{1376}
@deffn {Κλάση} textwrap.TextWrapper (**kwargs)

Ο κατασκευαστής της @ref{1376,,TextWrapper} δέχεται αρκετά προαιρετικά ορίσματα λέξεων-κλειδιών. Κάθε όρισμα λέξης-κλειδιού αντιστοιχεί σε μια ιδιότητα στιγμιότυπου, οπότε για παράδειγμα

@example
wrapper = TextWrapper(initial_indent="* ")
@end example

είναι το ίδιο με

@example
wrapper = TextWrapper()
wrapper.initial_indent = "* "
@end example

Μπορείτε να επαναχρησιμοποιήσετε το ίδιο αντικείμενο @ref{1376,,TextWrapper} πολλές φορές, και μπορείτε να αλλάξετε οποιαδήποτε από τις επιλογές του μέσω άμεσης ανάθεσης σε ιδιότητες στιγμιότυπου μεταξύ των χρήσεων.

Οι ιδιότητες στιγμιότυπου της @ref{1376,,TextWrapper} (και τα ορίσματα λέξεων-κλειδιών στον κατασκευαστή) είναι οι εξής:

@geindex width (ιδιότητα της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper width}@anchor{29dc}
@deffn {Ιδιότητα} width

(προεπιλογή: @code{70}) Το μέγιστο μήκος των περιτυλιγμένων γραμμών. Εφόσον δεν υπάρχουν μεμονωμένες λέξεις στο εισαγόμενο κείμενο μεγαλύτερες από @ref{29dc,,width}, η @ref{1376,,TextWrapper} εγγυάται ότι καμία γραμμή εξόδου δεν θα είναι μεγαλύτερη από @code{width} χαρακτήρες.
@end deffn

@geindex expand_tabs (ιδιότητα της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper expand_tabs}@anchor{29d8}
@deffn {Ιδιότητα} expand_tabs

(προεπιλογή: @code{True}) Αν είναι true, τότε όλοι οι χαρακτήρες tab στο `text' θα επεκταθούν σε κενά χρησιμοποιώντας τη μέθοδο @ref{283b,,expandtabs()} του `text'.
@end deffn

@geindex tabsize (ιδιότητα της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper tabsize}@anchor{29d7}
@deffn {Ιδιότητα} tabsize

(προεπιλογή: @code{8}) Αν @ref{29d8,,expand_tabs} είναι true, τότε όλοι οι χαρακτήρες tab στο `text' θα επεκταθούν σε μηδέν ή περισσότερα κενά, ανάλογα με την τρέχουσα στήλη και το δεδομένο μέγεθος tab.


Added in version 3.3.

@end deffn

@geindex replace_whitespace (ιδιότητα της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper replace_whitespace}@anchor{29da}
@deffn {Ιδιότητα} replace_whitespace

(προεπιλογή: @code{True}) Αν είναι true, μετά την επέκταση των tab αλλά πριν το περιτύλιγμα, η μέθοδος @ref{1869,,wrap()} θα αντικαταστήσει κάθε χαρακτήρα κενών με ένα μόνο κενό. Οι χαρακτήρες κενών που αντικαθίστανται είναι οι εξής: tab, νέα γραμμή, κάθετος, τροφοδότης μορφής και carriage return (@code{'\t\n\v\f\r'}).

@cartouche
@quotation Σημείωση 
(προεπιλογή: @code{True}) Αν το @ref{29d8,,expand_tabs} είναι false και το @ref{29da,,replace_whitespace} είναι true, κάθε χαρακτήρας tab θα αντικατασταθεί από ένα μόνο κενό, το οποίο `δεν είναι' το ίδιο με την επέκταση των tab.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Αν το @ref{29da,,replace_whitespace} είναι false, οι νέες γραμμές μπορεί να εμφανιστούν στη μέση μιας γραμμής και να προκαλέσουν παράξενα αποτελέσματα. Για αυτόν τον λόγο, το κείμενο θα πρέπει να διαχωρίζεται σε παραγράφους (χρησιμοποιώντας @ref{15fb,,str.splitlines()} ή παρόμοια) οι οποίες περιτυλίγονται ξεχωριστά.
@end quotation
@end cartouche
@end deffn

@geindex drop_whitespace (ιδιότητα της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper drop_whitespace}@anchor{29d9}
@deffn {Ιδιότητα} drop_whitespace

(προεπιλογή: @code{True}) Αν είναι true, το κενό στην αρχή και στο τέλος κάθε γραμμής (μετά το περιτύλιγμα αλλά πριν την εσοχή) αφαιρείται. Το κενό στην αρχή της παραγράφου, ωστόσο, δεν αφαιρείται αν ακολουθείται από μη κενό. Αν το κενό που αφαιρείται καταλαμβάνει ολόκληρη τη γραμμή, ολόκληρη η γραμμή αφαιρείται.
@end deffn

@geindex initial_indent (ιδιότητα της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper initial_indent}@anchor{29dd}
@deffn {Ιδιότητα} initial_indent

(προεπιλογή: @code{'@w{'}}) Συμβολοσειρά που θα προστεθεί στην αρχή της πρώτης γραμμής της περιτυλιγμένης εξόδου. Μετράει προς το μήκος της πρώτης γραμμής. Η κενή συμβολοσειρά δεν έχει εσοχή.
@end deffn

@geindex subsequent_indent (ιδιότητα της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper subsequent_indent}@anchor{29de}
@deffn {Ιδιότητα} subsequent_indent

(προεπιλογή: @code{'@w{'}}) Συμβολοσειρά που θα προστεθεί στην αρχή όλων των γραμμών της περιτυλιγμένης εξόδου εκτός από την πρώτη. Μετράει προς το μήκος κάθε γραμμής εκτός από την πρώτη.
@end deffn

@geindex fix_sentence_endings (ιδιότητα της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper fix_sentence_endings}@anchor{29df}
@deffn {Ιδιότητα} fix_sentence_endings

(προεπιλογή: @code{False}) Αν είναι true, η @ref{1376,,TextWrapper} προσπαθεί να ανιχνεύσει τα τέλη προτάσεων και να διασφαλίσει ότι οι προτάσεις διαχωρίζονται πάντα από ακριβώς δύο κενά. Αυτό είναι γενικά επιθυμητό για κείμενα σε γραμματοσειρά μονού διαστήματος. Ωστόσο, ο αλγόριθμος ανίχνευσης προτάσεων δεν είναι τέλειος: υποθέτει ότι ένα τέλος πρότασης αποτελείται από ένα πεζό γράμμα ακολουθούμενο από ένα από τα @code{'.'}, @code{'!'} ή @code{'?'}, πιθανώς ακολουθούμενο από ένα από τα @code{'"'} ή @code{"'"}, ακολουθούμενο από ένα κενό. Ένα πρόβλημα με αυτόν τον αλγόριθμο είναι ότι δεν μπορεί να ανιχνεύσει τη διαφορά μεταξύ «Dr.» στο

@example
[...] Dr. Frankenstein's monster [...]
@end example

and «Spot.» in

@example
[...] See Spot. See Spot run [...]
@end example

@ref{29df,,fix_sentence_endings} είναι false από προεπιλογή.

Δεδομένου ότι ο αλγόριθμος ανίχνευσης προτάσεων βασίζεται στο @code{string.lowercase} για τον ορισμό του «πεζού γράμματος», και μια σύμβαση χρήσης δύο κενών μετά από μια τελεία για τον διαχωρισμό των προτάσεων στην ίδια γραμμή, είναι συγκεκριμένος για κείμενα στα αγγλικά.
@end deffn

@geindex break_long_words (ιδιότητα της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper break_long_words}@anchor{29db}
@deffn {Ιδιότητα} break_long_words

(προεπιλογή: @code{True}) Αν είναι true, τότε οι λέξεις μεγαλύτερες από @ref{29dc,,width} θα σπάσουν για να διασφαλιστεί ότι καμία γραμμή δεν θα είναι μεγαλύτερη από @code{width}. Αν είναι false, οι μακριές λέξεις δεν θα σπάσουν, και μερικές γραμμές μπορεί να είναι μεγαλύτερες από @code{width}. (Οι μακριές λέξεις θα τοποθετηθούν σε μια γραμμή από μόνες τους, για να ελαχιστοποιηθεί το ποσό κατά το οποίο ξεπερνάται το @code{width}).
@end deffn

@geindex break_on_hyphens (ιδιότητα της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper break_on_hyphens}@anchor{29e0}
@deffn {Ιδιότητα} break_on_hyphens

(προεπιλογή: @code{True}) Αν είναι true, το περιτύλιγμα θα συμβαίνει προτιμότερα σε κενά και αμέσως μετά τις παύλες σε σύνθετες λέξεις, όπως είναι συνηθισμένο στα αγγλικά. Αν είναι false, μόνο τα κενά θα θεωρούνται ως πιθανές καλές θέσεις για διακοπές γραμμής, αλλά πρέπει να ορίσετε το @ref{29db,,break_long_words} σε false αν θέλετε πραγματικά αδιάσπαστες λέξεις. Η προεπιλεγμένη συμπεριφορά στις προηγούμενες εκδόσεις ήταν να επιτρέπεται πάντα η διάσπαση των λέξεων με παύλες.
@end deffn

@geindex max_lines (ιδιότητα της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper max_lines}@anchor{1377}
@deffn {Ιδιότητα} max_lines

(προεπιλογή: @code{None}) Αν δεν είναι @code{None}, τότε η έξοδος θα περιέχει το πολύ `max_lines' γραμμές, με το `placeholder' να εμφανίζεται στο τέλος της εξόδου.


Added in version 3.4.

@end deffn

@geindex ...;placeholder

@geindex placeholder (ιδιότητα της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper placeholder}@anchor{1378}
@deffn {Ιδιότητα} placeholder

(προεπιλογή: @code{' [...]'}) Συμβολοσειρά που θα εμφανίζεται στο τέλος του κειμένου εξόδου αν έχει περικοπεί.


Added in version 3.4.

@end deffn

Η @ref{1376,,TextWrapper} παρέχει επίσης μερικές δημόσιες μεθόδους, παρόμοιες με τις συναρτήσεις ευκολίας σε επίπεδο module:

@geindex wrap() (μέθοδος της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper wrap}@anchor{29d6}
@deffn {Μέθοδος} wrap (text)

Περιτυλίγει την ενιαία παράγραφο στο `text' (μία συμβολοσειρά) έτσι ώστε κάθε γραμμή να έχει το πολύ @ref{29dc,,width} χαρακτήρες. Όλες οι επιλογές περιτυλίγματος λαμβάνονται από τις ιδιότητες στιγμιότυπου της @ref{1376,,TextWrapper} κλάσης. Επιστρέφει μια λίστα με τις γραμμές εξόδου, χωρίς τελικούς χαρακτήρες νέας γραμμής. Αν η περιτυλιγμένη έξοδος δεν έχει περιεχόμενο, η επιστρεφόμενη λίστα είναι κενή.
@end deffn

@geindex fill() (μέθοδος της textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper fill}@anchor{29e1}
@deffn {Μέθοδος} fill (text)

Γεμίζει την ενιαία παράγραφο στο `text' και επιστρέφει μια μοναδική συμβολοσειρά που περιέχει την γεμισμένη παράγραφο.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node unicodedata — Unicode Database,stringprep — Internet String Preparation,textwrap — Περιτύλιγμα και γέμισμα κειμένου,Text Processing Services
@anchor{library/unicodedata doc}@anchor{29e2}@anchor{library/unicodedata module-unicodedata}@anchor{10e}@anchor{library/unicodedata translation-repo}@anchor{29e3}@anchor{library/unicodedata unicodedata-unicode-database}@anchor{29e4}
@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 17.0.0@footnote{https://www.unicode.org/Public/17.0.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:


@subsubheading Δείτε επίσης


The @ref{1649,,Unicode HOWTO} for more information about Unicode and how to use
this module.


@geindex lookup() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata lookup}@anchor{1420}
@deffn {Συνάρτηση} unicodedata.lookup (name, /)

Look up character by name.  If a character with the given name is found, return
the corresponding character.  If not found, @ref{7df,,KeyError} is raised.
For example:

@example
>>> unicodedata.lookup('LEFT CURLY BRACKET')
'@{'
@end example

The characters returned by this function are the same as those produced by
@code{\N} escape sequence in string literals. For example:

@example
>>> unicodedata.lookup('MIDDLE DOT') == '\N@{MIDDLE DOT@}'
True
@end example


Άλλαξε στην έκδοση 3.3: Support for name aliases @footnote{
@indicateurl{https://www.unicode.org/Public/17.0.0/ucd/NameAliases.txt}
} and named sequences @footnote{
@indicateurl{https://www.unicode.org/Public/17.0.0/ucd/NamedSequences.txt}
} has been added.

@end deffn

@geindex name() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata name}@anchor{29e5}
@deffn {Συνάρτηση} unicodedata.name (chr, default=None, /)

Returns the name assigned to the character `chr' as a string. If no
name is defined, `default' is returned, or, if not given, @ref{277,,ValueError} is
raised. For example:

@example
>>> unicodedata.name('½')
'VULGAR FRACTION ONE HALF'
>>> unicodedata.name('\uFFFF', 'fallback')
'fallback'
@end example
@end deffn

@geindex decimal() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata decimal}@anchor{29e6}
@deffn {Συνάρτηση} unicodedata.decimal (chr, default=None, /)

Returns the decimal value assigned to the character `chr' as integer.
If no such value is defined, `default' is returned, or, if not given,
@ref{277,,ValueError} is raised. For example:

@example
>>> unicodedata.decimal('\N@{ARABIC-INDIC DIGIT NINE@}')
9
>>> unicodedata.decimal('\N@{SUPERSCRIPT NINE@}', -1)
-1
@end example
@end deffn

@geindex digit() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata digit}@anchor{29e7}
@deffn {Συνάρτηση} unicodedata.digit (chr, default=None, /)

Returns the digit value assigned to the character `chr' as integer.
If no such value is defined, `default' is returned, or, if not given,
@ref{277,,ValueError} is raised:

@example
>>> unicodedata.digit('\N@{SUPERSCRIPT NINE@}')
9
@end example
@end deffn

@geindex numeric() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata numeric}@anchor{1607}
@deffn {Συνάρτηση} unicodedata.numeric (chr, default=None, /)

Returns the numeric value assigned to the character `chr' as float.
If no such value is defined, `default' is returned, or, if not given,
@ref{277,,ValueError} is raised:

@example
>>> unicodedata.numeric('½')
0.5
@end example
@end deffn

@geindex category() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata category}@anchor{29e8}
@deffn {Συνάρτηση} unicodedata.category (chr, /)

Returns the general category assigned to the character `chr' as
string. General category names consist of two letters.
See the General Category Values section of the Unicode Character Database documentation@footnote{https://www.unicode.org/reports/tr44/#General_Category_Values}
for a list of category codes. For example:

@example
>>> unicodedata.category('A')  # 'L'etter, 'u'ppercase
'Lu'
@end example
@end deffn

@geindex bidirectional() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata bidirectional}@anchor{1948}
@deffn {Συνάρτηση} unicodedata.bidirectional (chr, /)

Returns the bidirectional class assigned to the character `chr' as
string. If no such value is defined, an empty string is returned.
See the Bidirectional Class Values section of the Unicode Character Database@footnote{https://www.unicode.org/reports/tr44/#Bidi_Class_Values}
documentation for a list of bidirectional codes. For example:

@example
>>> unicodedata.bidirectional('\N@{ARABIC-INDIC DIGIT SEVEN@}') # 'A'rabic, 'N'umber
'AN'
@end example
@end deffn

@geindex combining() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata combining}@anchor{29e9}
@deffn {Συνάρτηση} unicodedata.combining (chr, /)

Returns the canonical combining class assigned to the character `chr'
as integer. Returns @code{0} if no combining class is defined.
See the Canonical Combining Class Values section of the Unicode Character Database@footnote{https://www.unicode.org/reports/tr44/#Canonical_Combining_Class_Values}
for more information.
@end deffn

@geindex east_asian_width() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata east_asian_width}@anchor{29ea}
@deffn {Συνάρτηση} unicodedata.east_asian_width (chr, /)

Returns the east asian width assigned to the character `chr' as
string. For a list of widths and or more information, see the
Unicode Standard Annex #11@footnote{https://www.unicode.org/reports/tr11/}.
@end deffn

@geindex block() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata block}@anchor{29d}
@deffn {Συνάρτηση} unicodedata.block (chr, /)

Returns the block@footnote{https://www.unicode.org/versions/Unicode17.0.0/core-spec/chapter-3/#G64189}
assigned to the character `chr'. For example:

@example
>>> unicodedata.block('S')
'Basic Latin'
@end example


Added in version 3.15.

@end deffn

@geindex mirrored() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata mirrored}@anchor{29eb}
@deffn {Συνάρτηση} unicodedata.mirrored (chr, /)

Returns the mirrored property assigned to the character `chr' as
integer. Returns @code{1} if the character has been identified as a «mirrored»
character in bidirectional text, @code{0} otherwise. For example:

@example
>>> unicodedata.mirrored('>')
1
@end example
@end deffn

@geindex isxidstart() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata isxidstart}@anchor{297}
@deffn {Συνάρτηση} unicodedata.isxidstart (chr, /)

Return @code{True} if `chr' is a valid identifier start per the
Unicode Standard Annex #31@footnote{https://www.unicode.org/reports/tr31/},
that is, it has the @code{XID_Start} property. Return @code{False} otherwise.
For example:

@example
>>> unicodedata.isxidstart('S')
True
>>> unicodedata.isxidstart('0')
False
@end example


Added in version 3.15.

@end deffn

@geindex isxidcontinue() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata isxidcontinue}@anchor{298}
@deffn {Συνάρτηση} unicodedata.isxidcontinue (chr, /)

Return @code{True} if `chr' is a valid identifier character per the
Unicode Standard Annex #31@footnote{https://www.unicode.org/reports/tr31/},
that is, it has the @code{XID_Continue} property. Return @code{False} otherwise.
For example:

@example
>>> unicodedata.isxidcontinue('S')
True
>>> unicodedata.isxidcontinue(' ')
False
@end example


Added in version 3.15.

@end deffn

@geindex decomposition() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata decomposition}@anchor{1946}
@deffn {Συνάρτηση} unicodedata.decomposition (chr, /)

Returns the character decomposition mapping assigned to the character
`chr' as string. An empty string is returned in case no such mapping is
defined. For example:

@example
>>> unicodedata.decomposition('Ã')
'0041 0303'
@end example
@end deffn

@geindex grapheme_cluster_break() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata grapheme_cluster_break}@anchor{29a}
@deffn {Συνάρτηση} unicodedata.grapheme_cluster_break (chr, /)

Returns the Grapheme_Cluster_Break property assigned to the character.


Added in version 3.15.

@end deffn

@geindex indic_conjunct_break() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata indic_conjunct_break}@anchor{29b}
@deffn {Συνάρτηση} unicodedata.indic_conjunct_break (chr, /)

Returns the Indic_Conjunct_Break property assigned to the character.


Added in version 3.15.

@end deffn

@geindex extended_pictographic() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata extended_pictographic}@anchor{29c}
@deffn {Συνάρτηση} unicodedata.extended_pictographic (chr, /)

Returns @code{True} if the character has the Extended_Pictographic property,
@code{False} otherwise.


Added in version 3.15.

@end deffn

@geindex normalize() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata normalize}@anchor{ac2}
@deffn {Συνάρτηση} unicodedata.normalize (form, unistr, /)

Return the normal form `form' for the Unicode string `unistr'. Valid values for
`form' are “NFC”, “NFKC”, “NFD”, and “NFKD”.

The Unicode standard defines various normalization forms of a Unicode string,
based on the definition of canonical equivalence and compatibility equivalence.
In Unicode, several characters can be expressed in various way. For example, the
character U+00C7 (LATIN CAPITAL LETTER C WITH CEDILLA) can also be expressed as
the sequence U+0043 (LATIN CAPITAL LETTER C) U+0327 (COMBINING CEDILLA).

For each character, there are two normal forms: normal form C and normal form D.
Normal form D (NFD) is also known as canonical decomposition, and translates
each character into its decomposed form. Normal form C (NFC) first applies a
canonical decomposition, then composes pre-combined characters again.

In addition to these two forms, there are two additional normal forms based on
compatibility equivalence. In Unicode, certain characters are supported which
normally would be unified with other characters. For example, U+2160 (ROMAN
NUMERAL ONE) is really the same thing as U+0049 (LATIN CAPITAL LETTER I).
However, it is supported in Unicode for compatibility with existing character
sets (for example, gb2312).

The normal form KD (NFKD) will apply the compatibility decomposition, that is,
replace all compatibility characters with their equivalents. The normal form KC
(NFKC) first applies the compatibility decomposition, followed by the canonical
composition.

Even if two unicode strings are normalized and look the same to
a human reader, if one has combining characters and the other
doesn’t, they may not compare equal.
@end deffn

@geindex is_normalized() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata is_normalized}@anchor{e0b}
@deffn {Συνάρτηση} 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”.


Added in version 3.8.

@end deffn

@geindex iter_graphemes() (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata iter_graphemes}@anchor{299}
@deffn {Συνάρτηση} unicodedata.iter_graphemes (unistr, start=0, end=sys.maxsize, /)

Returns an iterator to iterate over grapheme clusters.
With optional `start', iteration begins at that position.
With optional `end', iteration stops at that position.

Converting an emitted item to string returns a substring corresponding to
the grapheme cluster.
Its @code{start} and @code{end} attributes denote the start and end of
the grapheme cluster.

It uses extended grapheme cluster rules defined by Unicode
Standard Annex #29, "Unicode Text Segmentation"@footnote{https://www.unicode.org/reports/tr29/}.


Added in version 3.15.

@end deffn

In addition, the module exposes the following constant:

@geindex unidata_version (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata unidata_version}@anchor{29ec}
@deffn {Δεδομένα} unicodedata.unidata_version

The version of the Unicode database used in this module.
@end deffn

@geindex ucd_3_2_0 (στη μονάδα unicodedata)
@anchor{library/unicodedata unicodedata ucd_3_2_0}@anchor{17d6}
@deffn {Δεδομένα} unicodedata.ucd_3_2_0

This is an object that has most of the methods of the entire module, but uses the
Unicode database version 3.2 instead, for applications that require this
specific version of the Unicode database (such as IDNA).
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node stringprep — Internet String Preparation,readline — GNU readline interface,unicodedata — Unicode Database,Text Processing Services
@anchor{library/stringprep doc}@anchor{29ed}@anchor{library/stringprep module-stringprep}@anchor{dd}@anchor{library/stringprep stringprep-internet-string-preparation}@anchor{29ee}@anchor{library/stringprep translation-repo}@anchor{29ef}
@subsection @code{stringprep} — Internet String Preparation


@geindex module; stringprep

`Source code:' Lib/stringprep.py@footnote{https://github.com/python/cpython/tree/main/Lib/stringprep.py}


__________________________________________________________________


When identifying things (such as host names) in the internet, it is often
necessary to compare such identifications for «equality». Exactly how this
comparison is executed may depend on the application domain, e.g. whether it
should be case-insensitive or not. It may be also necessary to restrict the
possible identifications, to allow only identifications consisting of
«printable» characters.

@geindex RFC; RFC 3454
RFC 3454@footnote{https://datatracker.ietf.org/doc/html/rfc3454.html} defines a procedure for «preparing» Unicode strings in internet
protocols. Before passing strings onto the wire, they are processed with the
preparation procedure, after which they have a certain normalized form. The RFC
defines a set of tables, which can be combined into profiles. Each profile must
define which tables it uses, and what other optional parts of the @code{stringprep}
procedure are part of the profile. One example of a @code{stringprep} profile is
@code{nameprep}, which is used for internationalized domain names.

The module @code{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.

As a result, these tables are exposed as functions, not as data structures.
There are two kinds of tables in the RFC: sets and mappings. For a set,
@code{stringprep} provides the «characteristic function», i.e. a function that
returns @code{True} if the parameter is part of the set. For mappings, it provides the
mapping function: given the key, it returns the associated value. Below is a
list of all functions available in the module.

@geindex in_table_a1() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_a1}@anchor{29f0}
@deffn {Συνάρτηση} stringprep.in_table_a1 (code)

Determine whether `code' is in tableA.1 (Unassigned code points in Unicode 3.2).
@end deffn

@geindex in_table_b1() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_b1}@anchor{29f1}
@deffn {Συνάρτηση} stringprep.in_table_b1 (code)

Determine whether `code' is in tableB.1 (Commonly mapped to nothing).
@end deffn

@geindex map_table_b2() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep map_table_b2}@anchor{29f2}
@deffn {Συνάρτηση} stringprep.map_table_b2 (code)

Return the mapped value for `code' according to tableB.2 (Mapping for
case-folding used with NFKC).
@end deffn

@geindex map_table_b3() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep map_table_b3}@anchor{29f3}
@deffn {Συνάρτηση} stringprep.map_table_b3 (code)

Return the mapped value for `code' according to tableB.3 (Mapping for
case-folding used with no normalization).
@end deffn

@geindex in_table_c11() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c11}@anchor{29f4}
@deffn {Συνάρτηση} stringprep.in_table_c11 (code)

Determine whether `code' is in tableC.1.1  (ASCII space characters).
@end deffn

@geindex in_table_c12() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c12}@anchor{29f5}
@deffn {Συνάρτηση} stringprep.in_table_c12 (code)

Determine whether `code' is in tableC.1.2  (Non-ASCII space characters).
@end deffn

@geindex in_table_c11_c12() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c11_c12}@anchor{29f6}
@deffn {Συνάρτηση} stringprep.in_table_c11_c12 (code)

Determine whether `code' is in tableC.1  (Space characters, union of C.1.1 and
C.1.2).
@end deffn

@geindex in_table_c21() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c21}@anchor{29f7}
@deffn {Συνάρτηση} stringprep.in_table_c21 (code)

Determine whether `code' is in tableC.2.1  (ASCII control characters).
@end deffn

@geindex in_table_c22() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c22}@anchor{29f8}
@deffn {Συνάρτηση} stringprep.in_table_c22 (code)

Determine whether `code' is in tableC.2.2  (Non-ASCII control characters).
@end deffn

@geindex in_table_c21_c22() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c21_c22}@anchor{29f9}
@deffn {Συνάρτηση} stringprep.in_table_c21_c22 (code)

Determine whether `code' is in tableC.2  (Control characters, union of C.2.1 and
C.2.2).
@end deffn

@geindex in_table_c3() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c3}@anchor{29fa}
@deffn {Συνάρτηση} stringprep.in_table_c3 (code)

Determine whether `code' is in tableC.3  (Private use).
@end deffn

@geindex in_table_c4() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c4}@anchor{29fb}
@deffn {Συνάρτηση} stringprep.in_table_c4 (code)

Determine whether `code' is in tableC.4  (Non-character code points).
@end deffn

@geindex in_table_c5() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c5}@anchor{29fc}
@deffn {Συνάρτηση} stringprep.in_table_c5 (code)

Determine whether `code' is in tableC.5  (Surrogate codes).
@end deffn

@geindex in_table_c6() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c6}@anchor{29fd}
@deffn {Συνάρτηση} stringprep.in_table_c6 (code)

Determine whether `code' is in tableC.6  (Inappropriate for plain text).
@end deffn

@geindex in_table_c7() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c7}@anchor{29fe}
@deffn {Συνάρτηση} stringprep.in_table_c7 (code)

Determine whether `code' is in tableC.7  (Inappropriate for canonical
representation).
@end deffn

@geindex in_table_c8() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c8}@anchor{29ff}
@deffn {Συνάρτηση} stringprep.in_table_c8 (code)

Determine whether `code' is in tableC.8  (Change display properties or are
deprecated).
@end deffn

@geindex in_table_c9() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_c9}@anchor{2a00}
@deffn {Συνάρτηση} stringprep.in_table_c9 (code)

Determine whether `code' is in tableC.9  (Tagging characters).
@end deffn

@geindex in_table_d1() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_d1}@anchor{2a01}
@deffn {Συνάρτηση} stringprep.in_table_d1 (code)

Determine whether `code' is in tableD.1  (Characters with bidirectional property
«R» or «AL»).
@end deffn

@geindex in_table_d2() (στη μονάδα stringprep)
@anchor{library/stringprep stringprep in_table_d2}@anchor{2a02}
@deffn {Συνάρτηση} stringprep.in_table_d2 (code)

Determine whether `code' is in tableD.2  (Characters with bidirectional property
«L»).
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node readline — GNU readline interface,rlcompleter — Completion function for GNU readline,stringprep — Internet String Preparation,Text Processing Services
@anchor{library/readline doc}@anchor{2a03}@anchor{library/readline module-readline}@anchor{c2}@anchor{library/readline readline-gnu-readline-interface}@anchor{2a04}@anchor{library/readline translation-repo}@anchor{2a05}
@subsection @code{readline} — GNU readline interface


@geindex module; readline


__________________________________________________________________


The @code{readline} module defines a number of functions to facilitate
completion and reading/writing of history files from the Python interpreter.
This module can be used directly, or via the @ref{c5,,rlcompleter} module, which
supports completion of Python identifiers at the interactive prompt.  Settings
made using  this module affect the behaviour of both the interpreter’s
interactive prompt  and the prompts offered by the built-in @ref{167d,,input()}
function.

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{232d,,Διαθεσιμότητα}: not Android, not iOS, not WASI.

This module is not supported on @ref{244d,,mobile platforms}
or @ref{1d67,,WebAssembly platforms}.

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile

@ref{232d,,Διαθεσιμότητα}: Unix.

@cartouche
@quotation Σημείωση 
The underlying Readline library API may be implemented by
the @code{editline} (@code{libedit}) library instead of GNU readline.
On macOS the @code{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{1c2f,,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 (στη μονάδα readline)
@anchor{library/readline readline backend}@anchor{1c2f}
@deffn {Δεδομένα} readline.backend

The name of the underlying Readline library being used, either
@code{"readline"} or @code{"editline"}.


Added in version 3.13.

@end deffn

@menu
* Init file:: 
* Line buffer:: 
* History file:: 
* History list:: 
* Startup hooks:: 
* Completion:: 
* Example:: 

@end menu

@node Init file,Line buffer,,readline — GNU readline interface
@anchor{library/readline init-file}@anchor{2a06}
@subsubsection Init file


The following functions relate to the init file and user configuration:

@geindex parse_and_bind() (στη μονάδα readline)
@anchor{library/readline readline parse_and_bind}@anchor{2a07}
@deffn {Συνάρτηση} readline.parse_and_bind (string)

Execute the init line provided in the `string' argument. This calls
@code{rl_parse_and_bind()} in the underlying library.
@end deffn

@geindex read_init_file() (στη μονάδα readline)
@anchor{library/readline readline read_init_file}@anchor{19e0}
@deffn {Συνάρτηση} readline.read_init_file ([filename])

Execute a readline initialization file. The default filename is the last filename
used. This calls @code{rl_read_init_file()} in the underlying library.
It raises an @ref{1e65,,auditing event} @code{open} with the file name
if given, and @code{"<readline_init_file>"} otherwise, regardless of
which file the library resolves.


Άλλαξε στην έκδοση 3.14: The auditing event was added.

@end deffn

@node Line buffer,History file,Init file,readline — GNU readline interface
@anchor{library/readline line-buffer}@anchor{2a08}
@subsubsection Line buffer


The following functions operate on the line buffer:

@geindex get_line_buffer() (στη μονάδα readline)
@anchor{library/readline readline get_line_buffer}@anchor{2a09}
@deffn {Συνάρτηση} readline.get_line_buffer ()

Return the current contents of the line buffer (@code{rl_line_buffer}
in the underlying library).
@end deffn

@geindex insert_text() (στη μονάδα readline)
@anchor{library/readline readline insert_text}@anchor{2a0a}
@deffn {Συνάρτηση} readline.insert_text (string)

Insert text into the line buffer at the cursor position.  This calls
@code{rl_insert_text()} in the underlying library, but ignores
the return value.
@end deffn

@geindex redisplay() (στη μονάδα readline)
@anchor{library/readline readline redisplay}@anchor{1867}
@deffn {Συνάρτηση} readline.redisplay ()

Change what’s displayed on the screen to reflect the current contents of the
line buffer.  This calls @code{rl_redisplay()} in the underlying library.
@end deffn

@node History file,History list,Line buffer,readline — GNU readline interface
@anchor{library/readline history-file}@anchor{2a0b}
@subsubsection History file


The following functions operate on a history file:

@geindex read_history_file() (στη μονάδα readline)
@anchor{library/readline readline read_history_file}@anchor{19e1}
@deffn {Συνάρτηση} readline.read_history_file ([filename])

Load a readline history file, and append it to the history list.
The default filename is @code{~/.history}.  This calls
@code{read_history()} in the underlying library
and raises an @ref{1e65,,auditing event} @code{open} with the file
name if given and @code{"~/.history"} otherwise.


Άλλαξε στην έκδοση 3.14: The auditing event was added.

@end deffn

@geindex write_history_file() (στη μονάδα readline)
@anchor{library/readline readline write_history_file}@anchor{19e2}
@deffn {Συνάρτηση} readline.write_history_file ([filename])

Save the history list to a readline history file, overwriting any
existing file.  The default filename is @code{~/.history}.  This calls
@code{write_history()} in the underlying library and raises an
@ref{1e65,,auditing event} @code{open} with the file name if given and
@code{"~/.history"} otherwise.


Άλλαξε στην έκδοση 3.14: The auditing event was added.

@end deffn

@geindex append_history_file() (στη μονάδα readline)
@anchor{library/readline readline append_history_file}@anchor{1202}
@deffn {Συνάρτηση} readline.append_history_file (nelements[, filename])

Append the last `nelements' items of history to a file.  The default filename is
@code{~/.history}.  The file must already exist.  This calls
@code{append_history()} in the underlying library.  This function
only exists if Python was compiled for a version of the library
that supports it. It raises an @ref{1e65,,auditing event} @code{open}
with the file name if given and @code{"~/.history"} otherwise.


Added in version 3.5.



Άλλαξε στην έκδοση 3.14: The auditing event was added.

@end deffn

@geindex get_history_length() (στη μονάδα readline)
@geindex set_history_length() (στη μονάδα readline)
@anchor{library/readline readline get_history_length}@anchor{2a0c}
@deffn {Συνάρτηση} readline.get_history_length ()
@anchor{library/readline readline set_history_length}@anchor{1b41}
@deffnx {Συνάρτηση} readline.set_history_length (length)

Set or return the desired number of lines to save in the history file.
The @ref{19e2,,write_history_file()} function uses this value to truncate
the history file, by calling @code{history_truncate_file()} in
the underlying library.  Negative values imply
unlimited history file size.
@end deffn

@node History list,Startup hooks,History file,readline — GNU readline interface
@anchor{library/readline history-list}@anchor{2a0d}
@subsubsection History list


The following functions operate on a global history list:

@geindex clear_history() (στη μονάδα readline)
@anchor{library/readline readline clear_history}@anchor{2a0e}
@deffn {Συνάρτηση} readline.clear_history ()

Clear the current history.  This calls @code{clear_history()} in the
underlying library.  The Python function only exists if Python was
compiled for a version of the library that supports it.
@end deffn

@geindex get_current_history_length() (στη μονάδα readline)
@anchor{library/readline readline get_current_history_length}@anchor{1866}
@deffn {Συνάρτηση} readline.get_current_history_length ()

Return the number of items currently in the history.  (This is different from
@ref{2a0c,,get_history_length()}, which returns the maximum number of lines that will
be written to a history file.)
@end deffn

@geindex get_history_item() (στη μονάδα readline)
@anchor{library/readline readline get_history_item}@anchor{1865}
@deffn {Συνάρτηση} readline.get_history_item (index)

Return the current contents of history item at `index'.  The item index
is one-based.  This calls @code{history_get()} in the underlying library.
@end deffn

@geindex remove_history_item() (στη μονάδα readline)
@anchor{library/readline readline remove_history_item}@anchor{2a0f}
@deffn {Συνάρτηση} readline.remove_history_item (pos)

Remove history item specified by its position from the history.
The position is zero-based.  This calls @code{remove_history()} in
the underlying library.
@end deffn

@geindex replace_history_item() (στη μονάδα readline)
@anchor{library/readline readline replace_history_item}@anchor{2a10}
@deffn {Συνάρτηση} readline.replace_history_item (pos, line)

Replace history item specified by its position with `line'.
The position is zero-based.  This calls @code{replace_history_entry()}
in the underlying library.
@end deffn

@geindex add_history() (στη μονάδα readline)
@anchor{library/readline readline add_history}@anchor{2a11}
@deffn {Συνάρτηση} readline.add_history (line)

Append `line' to the history buffer, as if it was the last line typed.
This calls @code{add_history()} in the underlying library.
@end deffn

@geindex set_auto_history() (στη μονάδα readline)
@anchor{library/readline readline set_auto_history}@anchor{1087}
@deffn {Συνάρτηση} readline.set_auto_history (enabled)

Enable or disable automatic calls to @code{add_history()} when reading
input via readline.  The `enabled' argument should be a Boolean value
that when true, enables auto history, and that when false, disables
auto history.


Added in version 3.6.


`Λεπτομέρεια υλοποίησης CPython:' Auto history is enabled by default, and changes to this do not persist
across multiple sessions.
@end deffn

@node Startup hooks,Completion,History list,readline — GNU readline interface
@anchor{library/readline startup-hooks}@anchor{2a12}
@subsubsection Startup hooks


@geindex set_startup_hook() (στη μονάδα readline)
@anchor{library/readline readline set_startup_hook}@anchor{2a13}
@deffn {Συνάρτηση} readline.set_startup_hook ([function])

Set or remove the function invoked by the @code{rl_startup_hook}
callback of the underlying library.  If `function' is specified, it will
be used as the new hook function; if omitted or @code{None}, any function
already installed is removed.  The hook is called with no
arguments just before readline prints the first prompt.
@end deffn

@geindex set_pre_input_hook() (στη μονάδα readline)
@anchor{library/readline readline set_pre_input_hook}@anchor{2a14}
@deffn {Συνάρτηση} readline.set_pre_input_hook ([function])

Set or remove the function invoked by the @code{rl_pre_input_hook}
callback of the underlying library.  If `function' is specified, it will
be used as the new hook function; if omitted or @code{None}, any
function already installed is removed.  The hook is called
with no arguments after the first prompt has been printed and just before
readline starts reading input characters.  This function only exists
if Python was compiled for a version of the library that supports it.
@end deffn

@geindex get_pre_input_hook() (στη μονάδα readline)
@anchor{library/readline readline get_pre_input_hook}@anchor{19b4}
@deffn {Συνάρτηση} readline.get_pre_input_hook ()

Get the current pre-input hook function, or @code{None} if no pre-input hook
function has been set.  This function only exists if Python was compiled
for a version of the library that supports it.


Added in version 3.15.

@end deffn

@node Completion,Example,Startup hooks,readline — GNU readline interface
@anchor{library/readline completion}@anchor{2a15}@anchor{library/readline readline-completion}@anchor{2a16}
@subsubsection Completion


The following functions relate to implementing a custom word completion
function.  This is typically operated by the Tab key, and can suggest and
automatically complete a word being typed.  By default, Readline is set up
to be used by @ref{c5,,rlcompleter} to complete Python identifiers for
the interactive interpreter.  If the @code{readline} module is to be used
with a custom completer, a different set of word delimiters should be set.

@geindex set_completer() (στη μονάδα readline)
@anchor{library/readline readline set_completer}@anchor{2a17}
@deffn {Συνάρτηση} readline.set_completer ([function])

Set or remove the completer function.  If `function' is specified, it will be
used as the new completer function; if omitted or @code{None}, any completer
function already installed is removed.  The completer function is called as
@code{function(text, state)}, for `state' in @code{0}, @code{1}, @code{2}, …, until it
returns a non-string value.  It should return the next possible completion
starting with `text'.

The installed completer function is invoked by the `entry_func' callback
passed to @code{rl_completion_matches()} in the underlying library.
The `text' string comes from the first parameter to the
@code{rl_attempted_completion_function} callback of the
underlying library.
@end deffn

@geindex get_completer() (στη μονάδα readline)
@anchor{library/readline readline get_completer}@anchor{2a18}
@deffn {Συνάρτηση} readline.get_completer ()

Get the completer function, or @code{None} if no completer function has been set.
@end deffn

@geindex get_completion_type() (στη μονάδα readline)
@anchor{library/readline readline get_completion_type}@anchor{2a19}
@deffn {Συνάρτηση} readline.get_completion_type ()

Get the type of completion being attempted.  This returns the
@code{rl_completion_type} variable in the underlying library as
an integer.
@end deffn

@geindex get_begidx() (στη μονάδα readline)
@geindex get_endidx() (στη μονάδα readline)
@anchor{library/readline readline get_begidx}@anchor{1e9a}
@deffn {Συνάρτηση} readline.get_begidx ()
@anchor{library/readline readline get_endidx}@anchor{1e9b}
@deffnx {Συνάρτηση} 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() (στη μονάδα readline)
@geindex get_completer_delims() (στη μονάδα readline)
@anchor{library/readline readline set_completer_delims}@anchor{1c32}
@deffn {Συνάρτηση} readline.set_completer_delims (string)
@anchor{library/readline readline get_completer_delims}@anchor{2a1a}
@deffnx {Συνάρτηση} readline.get_completer_delims ()

Set or get the word delimiters for completion.  These determine the
start of the word to be considered for completion (the completion scope).
These functions access the @code{rl_completer_word_break_characters}
variable in the underlying library.
@end deffn

@geindex set_completion_display_matches_hook() (στη μονάδα readline)
@anchor{library/readline readline set_completion_display_matches_hook}@anchor{2a1b}
@deffn {Συνάρτηση} readline.set_completion_display_matches_hook ([function])

Set or remove the completion display function.  If `function' is
specified, it will be used as the new completion display function;
if omitted or @code{None}, any completion display function already
installed is removed.  This sets or clears the
@code{rl_completion_display_matches_hook} callback in the
underlying library.  The completion display function is called as
@code{function(substitution, [matches], longest_match_length)} once
each time matches need to be displayed.
@end deffn

@node Example,,Completion,readline — GNU readline interface
@anchor{library/readline example}@anchor{2a1c}@anchor{library/readline readline-example}@anchor{2a1d}
@subsubsection Example


The following example demonstrates how to use the @code{readline} module’s
history reading and writing functions to automatically load and save a history
file named @code{.python_history} from the user’s home directory.  The code
below would normally be executed automatically during interactive sessions
from the user’s 
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP} file.

@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

This code is actually automatically run when Python is run in
@ref{656,,interactive mode} (see @ref{1372,,Readline configuration}).

The following example achieves the same goal but supports concurrent interactive
sessions, by only appending the new history.

@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

The following example extends the @ref{2a1e,,code.InteractiveConsole} class to
support history save/restore.

@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

@cartouche
@quotation Σημείωση 
The new @ref{69d,,REPL} introduced in version 3.13 doesn’t support readline.
However, readline can still be used by setting the 
@geindex PYTHON_BASIC_REPL
@geindex μεταβλητή περιβάλλοντος; PYTHON_BASIC_REPL
@ref{452,,PYTHON_BASIC_REPL}
environment variable.
@end quotation
@end cartouche

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node rlcompleter — Completion function for GNU readline,,readline — GNU readline interface,Text Processing Services
@anchor{library/rlcompleter doc}@anchor{2a1f}@anchor{library/rlcompleter module-rlcompleter}@anchor{c5}@anchor{library/rlcompleter rlcompleter-completion-function-for-gnu-readline}@anchor{2a20}@anchor{library/rlcompleter translation-repo}@anchor{2a21}
@subsection @code{rlcompleter} — Completion function for GNU readline


@geindex module; rlcompleter

`Source code:' Lib/rlcompleter.py@footnote{https://github.com/python/cpython/tree/main/Lib/rlcompleter.py}


__________________________________________________________________


The @code{rlcompleter} module defines a completion function suitable to be
passed to @ref{2a17,,set_completer()} in the @ref{c2,,readline} module.

When this module is imported on a Unix platform with the @ref{c2,,readline} module
available, an instance of the @ref{1f20,,Completer} class is automatically created
and its @ref{2a22,,complete()} method is set as the
@ref{2a16,,readline completer}. The method provides
completion of valid Python @ref{2491,,identifiers and keywords}.

Example:

@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{656,,interactive mode}.  Unless Python is run with the
@ref{1551,,-S} option, the module is automatically imported and configured
(see @ref{1372,,Readline configuration}).

On platforms without @ref{c2,,readline}, the @ref{1f20,,Completer} class defined by
this module can still be used for custom purposes.

@geindex Completer (κλάση σε rlcompleter)
@anchor{library/rlcompleter completer-objects}@anchor{2a23}@anchor{library/rlcompleter rlcompleter Completer}@anchor{1f20}
@deffn {Κλάση} rlcompleter.Completer

Completer objects have the following method:

@geindex complete() (μέθοδος της rlcompleter.Completer)
@anchor{library/rlcompleter rlcompleter Completer complete}@anchor{2a22}
@deffn {Μέθοδος} complete (text, state)

Return the next possible completion for `text'.

When called by the @ref{c2,,readline} module, this method is called
successively with @code{state == 0, 1, 2, ...} until the method returns
@code{None}.

If called for `text' that doesn’t include a period character (@code{'.'}), it will
complete from names currently defined in @ref{1,,__main__}, @ref{13,,builtins} and
keywords (as defined by the @ref{87,,keyword} module).

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{8e3,,__getattr__()}) up to the last part, and find matches for the
rest via the @ref{a23,,dir()} function.  Any exception raised during the
evaluation of the expression is caught, silenced and @ref{a65,,None} is
returned.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Υπηρεσίες Δυαδικών Δεδομένων,Data Types,Text Processing Services,The Python Standard Library
@anchor{library/binary doc}@anchor{2a24}@anchor{library/binary binary-data-services}@anchor{2a25}@anchor{library/binary binaryservices}@anchor{2936}@anchor{library/binary translation-repo}@anchor{2a26}
@section Υπηρεσίες Δυαδικών Δεδομένων


Τα modules που περιγράφονται σε αυτό το κεφάλαιο παρέχουν βασικές λειτουργίες για τη διαχείριση δυαδικών δεδομένων. Άλλες λειτουργίες σε δυαδικά δεδομένα, ιδιαίτερα σε σχέση με μορφές αρχείων και δικτυακά πρωτόκολλα, περιγράφονται στις αντίστοιχες ενότητες.

Ορισμένες βιβλιοθήκες που περιγράφονται στο @ref{2844,,Text Processing Services} λειτουργούν επίσης με δυαδικές μορφές συμβατές με ASCII (για παράδειγμα, @ref{c1,,re}) ή με όλα τα δυαδικά δεδομένα (για παράδειγμα, @ref{3a,,difflib}).

Επιπλέον, δείτε την τεκμηρίωση για τους ενσωματωμένους τύπους δυαδικών δεδομένων της Python στο @ref{27bd,,Τύποι δυαδικής ακολουθίας — bytes@comma{} bytearray@comma{} memoryview}.

@menu
* struct — Ερμηνεία bytes ως πακετοποιημένα δυαδικά δεδομένα:: 
* codecs — Codec registry and base classes:: 

@end menu

@node struct — Ερμηνεία bytes ως πακετοποιημένα δυαδικά δεδομένα,codecs — Codec registry and base classes,,Υπηρεσίες Δυαδικών Δεδομένων
@anchor{library/struct doc}@anchor{2a27}@anchor{library/struct struct-interpret-bytes-as-packed-binary-data}@anchor{2a28}
@subsection @code{struct} — Ερμηνεία bytes ως πακετοποιημένα δυαδικά δεδομένα


@c from struct import *

@geindex module; struct
@anchor{library/struct module-struct}@anchor{de}
`Πηγαίος κώδικας:' Lib/struct.py@footnote{https://github.com/python/cpython/tree/main/Lib/struct.py}

@geindex C;δομές
@geindex πακετάρισμα;δυαδικό;δεδομένα


__________________________________________________________________


Αυτό το module μετατρέπει μεταξύ τιμών της Python και δομών της C που αναπαρίστανται ως αντικείμενα @ref{1c7,,bytes} της Python. Συμπαγείς @ref{2a29,,format strings} περιγράφουν τις προβλεπόμενες μετατροπές από/προς τιμές της Python. Οι συναρτήσεις και τα αντικείμενα του module μπορούν να χρησιμοποιηθούν για δύο κυρίως εφαρμογές: την ανταλλαγή δεδομένων με εξωτερικές πηγές (αρχεία ή συνδέσεις δικτύου) ή τη μεταφορά δεδομένων μεταξύ της εφαρμογής Python και του επιπέδου C.

@cartouche
@quotation Σημείωση 
Όταν δεν δίνεται χαρακτήρας προθέματος, η προεπιλεγμένη λειτουργία είναι η εγγενής (native mode). Πακετάρει ή αποσυμπιέζει δεδομένα με βάση την πλατφόρμα και τον μεταγλωττιστή με τον οποίο κατασκευάστηκε ο διερμηνέας της Python. Το αποτέλεσμα της συσκευασίας μιας δεδομένης δομής C περιλαμβάνει συμπληρωματικά bytes (pad bytes) που διατηρούν τη σωστή στοίχιση για τους εμπλεκόμενους τύπους C· παρομοίως, η στοίχιση λαμβάνεται υπόψη κατά την αποσυσκευασία. Αντίθετα, κατά την επικοινωνία δεδομένων με εξωτερικές πηγές, ο προγραμματιστής είναι υπεύθυνος για τον καθορισμό της σειράς byte και του συμπληρώματος μεταξύ των στοιχείων. Δείτε @ref{2a2a,,Διάταξη Byte@comma{} Μέγεθος και Στοίχιση} για λεπτομέρειες.
@end quotation
@end cartouche

Several @code{struct} functions (and methods of @ref{2fb,,Struct}) take a `buffer'
argument.  This refers to objects that implement the @ref{311,,Buffer Protocol} and
provide either a readable or read-writable buffer.  The most common types used
for that purpose are @ref{1c7,,bytes} and @ref{1c6,,bytearray}, but many other types
that can be viewed as an array of bytes implement the buffer protocol, so that
they can be read/filled without additional copying from a @code{bytes} object.

@menu
* Συναρτήσεις και εξαιρέσεις:: 
* Συμβολοσειρές μορφοποίησης:: 
* Εφαρμογές:: 
* Κλάσεις: Κλάσεις<3>. 

@end menu

@node Συναρτήσεις και εξαιρέσεις,Συμβολοσειρές μορφοποίησης,,struct — Ερμηνεία bytes ως πακετοποιημένα δυαδικά δεδομένα
@anchor{library/struct functions-and-exceptions}@anchor{2a2b}
@subsubsection Συναρτήσεις και εξαιρέσεις


Το module ορίζει την ακόλουθη εξαίρεση και συναρτήσεις:

@geindex error
@anchor{library/struct struct error}@anchor{16c8}
@deffn {Εξαίρεση} struct.error

Εξαίρεση που γίνεται raise σε διάφορες περιπτώσεις· το όρισμα είναι μια συμβολοσειρά που περιγράφει το σφάλμα.
@end deffn

@geindex pack() (στη μονάδα struct)
@anchor{library/struct struct pack}@anchor{161b}
@deffn {Συνάρτηση} struct.pack (format, v1, v2, ...)

Επιστρέφει ένα αντικείμενο τύπου bytes που περιέχει τις τιμές `v1', `v2', … πακεταρισμένες σύμφωνα με τη συμβολοσειρά μορφοποίησης `format'. Τα ορίσματα πρέπει να ταιριάζουν ακριβώς με τις απαιτούμενες τιμές της μορφοποίησης.
@end deffn

@geindex pack_into() (στη μονάδα struct)
@anchor{library/struct struct pack_into}@anchor{1966}
@deffn {Συνάρτηση} struct.pack_into (format, buffer, offset, v1, v2, ...)

Πακετάρει τις τιμές `v1', `v2', … σύμφωνα με τη συμβολοσειρά μορφοποίησης `format' και γράφει τα πακεταρισμένα bytes στον εγγράψιμο buffer `buffer' ξεκινώντας από τη θέση `offset'. Σημειώστε ότι το `offset' είναι υποχρεωτικό όρισμα.
@end deffn

@geindex unpack() (στη μονάδα struct)
@anchor{library/struct struct unpack}@anchor{1a82}
@deffn {Συνάρτηση} struct.unpack (format, buffer)

Αποσυμπιέζει από τον buffer `buffer' (ο οποίος υποτίθεται έχει πακεταριστεί με τη μέθοδο @code{pack(format, ...)}) σύμφωνα με την συμβολοσειρά μορφοποίησης `format'. Το αποτέλεσμα είναι μια πλειάδα, ακόμα κι αν περιέχει μόνο ένα στοιχείο. Το μέγεθος του buffer σε bytes πρέπει να ταιριάζει με το απαιτούμενο μέγεθος σύμφωνα με τη μορφή, όπως καθορίζεται από τη συνάρτηση @ref{1f9a,,calcsize()}.
@end deffn

@geindex unpack_from() (στη μονάδα struct)
@anchor{library/struct struct unpack_from}@anchor{2a2c}
@deffn {Συνάρτηση} struct.unpack_from (format, /, buffer, offset=0)

Αποσυμπιέζει από τον `buffer' ξεκινώντας από τη θέση `offset', σύμφωνα με τη συμβολοσειρά μορφοποίησης `format'.  Το αποτέλεσμα είναι μια πλειάδα, ακόμα κι αν περιέχει μόνο ένα στοιχείο. Το μέγεθος του buffer σε bytes, ξεκινώντας από τη θέση `offset', πρέπει να είναι τουλάχιστον το μέγεθος που απαιτείται από τη μορφή, όπως καθορίζεται από τη συνάρτηση @ref{1f9a,,calcsize()}.
@end deffn

@geindex iter_unpack() (στη μονάδα struct)
@anchor{library/struct struct iter_unpack}@anchor{1368}
@deffn {Συνάρτηση} struct.iter_unpack (format, buffer)

Αποσυμπιέζει επαναληπτικά από τον buffer `buffer' σύμφωνα με τη συμβολοσειρά μορφοποίησης `format'. Αυτή η συνάρτηση επιστρέφει έναν iterator ο οποίος θα διαβάσει κομμάτια ίδιου μεγέθους από τον buffer μέχρι να καταναλωθούν όλα τα περιεχόμενά του. Το μέγεθος του buffer σε bytes πρέπει να είναι πολλαπλάσιο του μεγέθους που απαιτείται από τη μορφή, όπως καθορίζεται από τη συνάρτηση @ref{1f9a,,calcsize()}.

Κάθε επανάληψη επιστρέφει μια πλειάδα σύμφωνα με τη συμβολοσειρά μορφοποίησης.


Added in version 3.4.

@end deffn

@geindex calcsize() (στη μονάδα struct)
@anchor{library/struct struct calcsize}@anchor{1f9a}
@deffn {Συνάρτηση} struct.calcsize (format)

Επιστρέφει το μέγεθος της δομής (και κατά συνέπεια του αντικειμένου bytes που παράγεται από το @code{pack(format, ...)}) που αντιστοιχεί στη συμβολοσειρά μορφοποίησης `format'.
@end deffn

@node Συμβολοσειρές μορφοποίησης,Εφαρμογές,Συναρτήσεις και εξαιρέσεις,struct — Ερμηνεία bytes ως πακετοποιημένα δυαδικά δεδομένα
@anchor{library/struct format-strings}@anchor{2a2d}@anchor{library/struct struct-format-strings}@anchor{2a29}
@subsubsection Συμβολοσειρές μορφοποίησης


Οι συμβολοσειρές μορφοποίησης περιγράφουν τη διάταξη των δεδομένων κατά την συσκευασία και αποσυσκευασία των δεδομένων. Δημιουργούνται από @ref{2a2e,,format characters}, οι οποίοι καθορίζουν τον τύπο των δεδομένων που συσκευάζονται/αποσυσκευάζονται. Επιπλέον, ειδικοί χαρακτήρες ελέγχουν την @ref{2a2a,,byte order@comma{} size and alignment}. Κάθε συμβολοσειρά μορφοποίησης αποτελείται από έναν προαιρετικό χαρακτήρα πρόθεμα που περιγράφει τις συνολικές ιδιότητες των δεδομένων και έναν ή περισσότερους χαρακτήρες μορφοποίησης που περιγράφουν τις πραγματικές τιμές δεδομένων και το συμπλήρωμα.

@menu
* Διάταξη Byte@comma{} Μέγεθος και Στοίχιση: Διάταξη Byte Μέγεθος και Στοίχιση. 
* Χαρακτήρες μορφής:: 
* Παραδείγματα:: 

@end menu

@node Διάταξη Byte Μέγεθος και Στοίχιση,Χαρακτήρες μορφής,,Συμβολοσειρές μορφοποίησης
@anchor{library/struct byte-order-size-and-alignment}@anchor{2a2f}@anchor{library/struct struct-alignment}@anchor{2a2a}
@subsubsection Διάταξη Byte, Μέγεθος και Στοίχιση


Από προεπιλογή, οι τύποι της C αναπαρίστανται στη φυσική μορφή και διάταξη byte της μηχανής και ευθυγραμμίζονται σωστά, παραλείποντας byte γεμίσματος εάν είναι απαραίτητο (σύμφωνα με τους κανόνες που χρησιμοποιεί ο μεταγλωττιστής C). Αυτή η συμπεριφορά επιλέγεται έτσι ώστε τα byte μιας συσκευασμένης δομής να αντιστοιχούν ακριβώς στη διάταξη μνήμης της αντίστοιχης δομής της C. Το αν θα χρησιμοποιηθεί φυσική διάταξη byte και γέμισμα ή τυποποιημένες μορφές εξαρτάται από την εφαρμογή.

@geindex @@ (παπάκι);στις συμβολοσειρές μορφοποίησης struct
@geindex = (ίσο);στις συμβολοσειρές μορφοποίησης struct
@geindex < (μικρότερο);στις συμβολοσειρές μορφοποίησης struct
@geindex > (μεγαλύτερο);στις συμβολοσειρές μορφοποίησης struct
@geindex ! (θαυμαστικό);στις συμβολοσειρές μορφοποίησης struct

Εναλλακτικά, ο πρώτος χαρακτήρας της συμβολοσειράς μορφοποίησης μπορεί να χρησιμοποιηθεί για να υποδείξει τη σειρά byte, το μέγεθος και την ευθυγράμμιση των συσκευασμένων δεδομένων, σύμφωνα με το παρακάτω πίνακα:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} {xxxxxxxxxxxxx} 
@headitem

Χαρακτήρας

@tab

Σειρά bytes

@tab

Μέγεθος

@tab

Στοίχιση

@item

@code{@@}

@tab

native

@tab

native

@tab

native

@item

@code{=}

@tab

native

@tab

τυπικό

@tab

κανένα

@item

@code{<}

@tab

little-endian

@tab

τυπικό

@tab

κανένα

@item

@code{>}

@tab

big-endian

@tab

τυπικό

@tab

κανένα

@item

@code{!}

@tab

δίκτυο (= big-endian)

@tab

τυπικό

@tab

κανένα

@end multitable


Αν ο πρώτος χαρακτήρας δεν είναι ένας από αυτούς, υποτίθεται @code{'@@'}.

@cartouche
@quotation Σημείωση 
Ο αριθμός 1023 (@code{0x3ff} σε δεκαεξαδική μορφή) έχει τις ακόλουθες αναπαραστάσεις σε byte:


@itemize *

@item 
@code{03 ff} σε big-endian (@code{>})

@item 
@code{ff 03} σε little-endian (@code{<})
@end itemize

Παράδειγμα Python:

@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 είναι big-endian ή little-endian, ανάλογα με το σύστημα υποδοχής. Για παράδειγμα, οι Intel x86, AMD64 (x86-64) και Apple M1 είναι little-endian, ενώ οι IBM z και πολλές παλαιότερες αρχιτεκτονικές είναι big-endian. Χρησιμοποιήστε τη μεταβλητή @ref{27f1,,sys.byteorder} για να ελέγξετε το endianness του συστήματος σας.

Το native μέγεθος και η στοίχιση καθορίζονται χρησιμοποιώντας την έκφραση @code{sizeof} του μεταγλωττιστή C. Αυτό συνδυάζεται πάντα με την native σειρά byte.

Το τυπικό μέγεθος εξαρτάται μόνο από τον χαρακτήρα μορφοποίησης· δείτε τον πίνακα στην ενότητα @ref{2a2e,,Χαρακτήρες μορφής}.

Σημειώστε τη διαφορά μεταξύ του @code{'@@'} και @code{'='}: και τα δύο χρησιμοποιούν τη native σειρά byte,  αλλά το μέγεθος και η στοίχιση του τελευταίου είναι τυποποιημένα.

Η μορφή @code{'!'} αντιπροσωπεύει τη σειρά byte του δικτύου, η οποία είναι πάντα big-endian όπως ορίζεται στο IETF RFC 1700@footnote{https://datatracker.ietf.org/doc/html/rfc1700}.

Δεν υπάρχει τρόπος να δηλωθεί non-native σειρά byte (να επιβληθεί εναλλαγή byte). Χρησιμοποιήστε την κατάλληλη επιλογή @code{'<'} ή @code{'>'}.

Σημειώσεις:


@enumerate 

@item 
Το συμπλήρωμα (padding) προστίθεται αυτόματα μόνο μεταξύ διαδοχικών μελών της δομής. Δεν προστίθεται συμπλήρωμα στην αρχή ή στο τέλος της κωδικοποιημένης δομής.

@item 
Δεν προστίθεται συμπλήρωμα όταν χρησιμοποιείται non-native μέγεθος και στοίχιση, π.χ. με “<”,”>”, “=”, και “!”.

@item 
Για να ευθυγραμμίσετε το τέλος μιας δομής με την απαίτηση στοίχισης ενός συγκεκριμένου τύπου, τελειώστε τη μορφή με τον κωδικό για αυτό τον τύπο με πλήθος επαναλήψεων μηδέν. Δείτε @ref{2a30,,Παραδείγματα}.
@end enumerate

@node Χαρακτήρες μορφής,Παραδείγματα,Διάταξη Byte Μέγεθος και Στοίχιση,Συμβολοσειρές μορφοποίησης
@anchor{library/struct format-characters}@anchor{2a2e}@anchor{library/struct id1}@anchor{2a31}
@subsubsection Χαρακτήρες μορφής


Οι χαρακτήρες μορφής έχουν την ακόλουθη σημασία· η μετατροπή μεταξύ τιμών C και Python είναι προφανής, δεδομένων των τύπων τους. Η στήλη “Τυπικό μέγεθος” αναφέρεται στο μέγεθος της συμπιεσμένης τιμής σε byte όταν χρησιμοποιείται τυπικό μέγεθος· δηλαδή, όταν η συμβολοσειρά μορφής ξεκινά με ένα από τα @code{'<'}, @code{'>'}, @code{'!'} or @code{'='}. Όταν χρησιμοποιείται το native μέγεθος, το μέγεθος της συμπιεσμένης τιμής εξαρτάται από την πλατφόρμα.


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

Μορφή

@tab

Τύπος C

@tab

Τύπος Python

@tab

Τυπικό μέγεθος

@tab

Σημειώσεις

@item

@code{x}

@tab

συμπληρωματικό byte

@tab

καμία τιμή

@tab

@tab

(7)

@item

@code{c}

@tab

char

@tab

bytes μήκους 1

@tab

1

@tab

@item

@code{b}

@tab

signed char

@tab

int

@tab

1

@tab

(2)

@item

@code{B}

@tab

unsigned char

@tab

int

@tab

1

@tab

(2)

@item

@code{?}

@tab

_Bool

@tab

bool

@tab

1

@tab

(1)

@item

@code{h}

@tab

short

@tab

int

@tab

2

@tab

(2)

@item

@code{H}

@tab

unsigned short

@tab

int

@tab

2

@tab

(2)

@item

@code{i}

@tab

int

@tab

int

@tab

4

@tab

(2)

@item

@code{I}

@tab

unsigned int

@tab

int

@tab

4

@tab

(2)

@item

@code{l}

@tab

long

@tab

int

@tab

4

@tab

(2)

@item

@code{L}

@tab

unsigned long

@tab

int

@tab

4

@tab

(2)

@item

@code{q}

@tab

long long

@tab

int

@tab

8

@tab

(2)

@item

@code{Q}

@tab

unsigned long long

@tab

int

@tab

8

@tab

(2)

@item

@code{n}

@tab

@code{ssize_t}

@tab

int

@tab

@tab

(2), (3)

@item

@code{N}

@tab

@code{size_t}

@tab

int

@tab

@tab

(2), (3)

@item

@code{e}

@tab

_Float16

@tab

float

@tab

2

@tab

(4), (6)

@item

@code{f}

@tab

float

@tab

float

@tab

4

@tab

(4)

@item

@code{d}

@tab

double

@tab

float

@tab

8

@tab

(4)

@item

@code{F}

@tab

float complex

@tab

μιγαδικός

@tab

8

@tab

(10)

@item

@code{D}

@tab

double complex

@tab

μιγαδικός

@tab

16

@tab

(10)

@item

@code{Zf}

@tab

float complex

@tab

μιγαδικός

@tab

8

@tab

(10)

@item

@code{Zd}

@tab

double complex

@tab

μιγαδικός

@tab

16

@tab

(10)

@item

@code{s}

@tab

char[]

@tab

bytes

@tab

@tab

(9)

@item

@code{p}

@tab

char[]

@tab

bytes

@tab

@tab

(8)

@item

@code{P}

@tab

void*

@tab

int

@tab

@tab

(2), (5)

@end multitable



Άλλαξε στην έκδοση 3.3: Προστέθηκε υποστήριξη για τις μορφές @code{'n'} και @code{'N'}.



Άλλαξε στην έκδοση 3.6: Προστέθηκε υποστήριξη για τη μορφή @code{'e'}.



Άλλαξε στην έκδοση 3.14: Προστέθηκε υποστήριξη για τις μορφές @code{'F'} και @code{'D'}.



Άλλαξε στην έκδοση 3.15: Added support for the @code{'Zf'} and @code{'Zd'} formats.



@subsubheading Δείτε επίσης


The @ref{8,,array} and @ref{2a32,,ctypes} modules,
as well as third-party modules like numpy@footnote{https://numpy.org/doc/stable/reference/arrays.interface.html#object.__array_interface__},
use similar – but slightly different – type codes.


Σημειώσεις:


@enumerate 

@item 
@geindex ? (ερωτηματικό);στις συμβολοσειρές μορφοποίησης struct

Ο κωδικός μετατροπής @code{'?'} αντιστοιχεί στον τύπο _Bool που ορίζεται από τα πρότυπα C από την έκδοση C99. Σε τυπική λειτουργία, αναπαρίσταται από ένα byte.

@item 
Όταν επιχειρείται η συσκευασία ενός μη ακέραιου αριθμού χρησιμοποιώντας οποιονδήποτε από τους κωδικούς μετατροπής ακεραίων, αν το αντικείμενο διαθέτει τη μέθοδο @ref{43d,,__index__()}, τότε καλείται αυτή η μέθοδος για τη μετατροπή του ορίσματος σε ακέραιο πριν από τη συσκευασία.


Άλλαξε στην έκδοση 3.2: Προστέθηκε η χρήση της μεθόδου @ref{43d,,__index__()} για μη ακέραιους αριθμούς.


@item 
Οι κωδικοί μετατροπής @code{'n'} και @code{'N'} είναι διαθέσιμοι μόνο για το native μέγεθος (επιλεγμένο ως προεπιλογή ή με τον χαρακτήρα διάταξης byte @code{'@@'}). Για το τυπικό μέγεθος, μπορείτε να χρησιμοποιήσετε οποιαδήποτε από τις άλλες μορφές ακέραιων που ταιριάζουν στην εφαρμογή σας.

@item 
Για τους κωδικούς μετατροπής @code{'f'}, @code{'d'} και @code{'e'}, η συσκευασμένη αναπαράσταση χρησιμοποιεί τη μορφή IEEE 754 binary32, binary64 ή binary16 (αντίστοιχα για @code{'f'}, @code{'d'} ή @code{'e'}), ανεξάρτητα από τη μορφή κινητής υποδιαστολής που χρησιμοποιεί η πλατφόρμα.

@item 
Ο χαρακτήρας μορφοποίησης @code{'P'} είναι διαθέσιμος μόνο για τη φυσική σειρά byte (επιλεγμένη ως προεπιλογή ή με τον χαρακτήρα σειράς byte @code{'@@'}). Ο χαρακτήρας σειράς byte @code{'='} επιλέγει τη χρήση little- ή big-endian σειράς με βάση το σύστημα. Το module struct δεν ερμηνεύει αυτό ως native σειρά, επομένως η μορφή @code{'P'} δεν είναι διαθέσιμη.

@item 
The IEEE 754 binary16 «half precision» type was introduced in the 2008
revision of the IEEE 754 standard@footnote{https://en.wikipedia.org/wiki/IEEE_754-2008_revision}. It has a sign
bit, a 5-bit exponent and 11-bit precision (with 10 bits explicitly stored),
and can represent numbers between approximately @code{6.1e-05} and @code{6.5e+04}
at full precision. This type is not widely supported by C compilers:
it’s available as _Float16 type, if the compiler supports the Annex H
of the C23 standard.  On a
typical machine, an unsigned short can be used for storage, but not for math
operations. See the Wikipedia page on the half-precision floating-point format@footnote{https://en.wikipedia.org/wiki/Half-precision_floating-point_format} for more information.

@item 
Κατά τη συσκευασία, το @code{'x'} εισάγει ένα NUL byte.

@item 
The @code{'p'} format character encodes a «Pascal string», meaning a short
variable-length string stored in a `fixed number of bytes', given by the count.
The first byte stored is the length of the string, or 255, whichever is
smaller.  The bytes of the string follow.  If the byte string passed in to
@ref{161b,,pack()} is too long (longer than the count minus 1), only the leading
@code{count-1} bytes of the string are stored.  If the byte string is shorter than
@code{count-1}, it is padded with null bytes so that exactly count bytes in all
are used.  Note that for @ref{1a82,,unpack()}, the @code{'p'} format character consumes
@code{count} bytes, but that the @code{bytes} object returned can never contain more than 255
bytes.
When packing, arguments of types @ref{1c7,,bytes} and @ref{1c6,,bytearray}
are accepted.

@item 
For the @code{'s'} format character, the count is interpreted as the length of the
byte string, 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{2a30,,Παραδείγματα}
for a concrete demonstration of the difference.)
If a count is not given, it defaults to 1.  For packing, the byte string is
truncated or padded with null bytes as appropriate to make it fit. For
unpacking, the resulting @code{bytes} object always has exactly the specified number
of bytes.  As a special case, @code{'0s'} means a single, empty byte string (while
@code{'0c'} means 0 characters).
When packing, arguments of types @ref{1c7,,bytes} and @ref{1c6,,bytearray}
are accepted.

@item 
For the @code{'F'} and @code{'D'} format characters, the packed representation uses
the IEEE 754 binary32 and binary64 format for components of the complex
number, regardless of the floating-point format used by the platform.
Note that complex types (@code{F}/@code{Zf} and @code{D}/@code{Zd}) are available unconditionally,
despite complex types being an optional feature in C.
As specified in the C11 standard, each complex type is represented by a
two-element C array containing, respectively, the real and imaginary parts.
@end enumerate

Ένας χαρακτήρας μορφοποίησης μπορεί να προηγείται από έναν ακέραιο αριθμό επαναλήψεων. Για παράδειγμα, η συμβολοσειρά μορφοποίησης @code{'4h'} σημαίνει ακριβώς το ίδιο με @code{'hhhh'}.

Οι χαρακτήρες κενού μεταξύ των μορφοποιήσεων αγνοούνται· ωστόσο, ένας αριθμός και η μορφή του δεν πρέπει να περιέχουν κενά.

Κατά το πακετάρισμα μιας τιμής @code{x} χρησιμοποιώντας μια από τις μορφές ακεραίων (@code{'b'}, @code{'B'}, @code{'h'}, @code{'H'}, @code{'i'}, @code{'I'}, @code{'l'}, @code{'L'}, @code{'q'}, @code{'Q'}), εάν το @code{x} είναι εκτός του έγκυρου εύρους για αυτήν τη μορφή, γίνεται raise μια εξαίρεση @ref{16c8,,struct.error}.


Άλλαξε στην έκδοση 3.1: Προηγουμένως, ορισμένες από τις μορφές ακεραίων περιτύλιγαν τιμές εκτός εύρους και εμφάνιζαν @ref{2c9,,DeprecationWarning} αντί για @ref{16c8,,struct.error}.


@geindex ? (ερωτηματικό);στις συμβολοσειρές μορφοποίησης struct

Για το χαρακτήρα μορφής @code{'?'}, η τιμή που επιστρέφεται είναι είτε @ref{fcc,,True} είτε @ref{ef5,,False}. Κατά την συσκευασία, χρησιμοποιείται η λογική τιμή του αντικειμένου-ορίσματος. Είτε 0 είτε 1 στη native ή τυπική αναπαράσταση του bool θα συσκευαστούν, και οποιαδήποτε μη μηδενική τιμή θα είναι @code{True} κατά την αποσυσκευασία.

@node Παραδείγματα,,Χαρακτήρες μορφής,Συμβολοσειρές μορφοποίησης
@anchor{library/struct examples}@anchor{2a33}@anchor{library/struct struct-examples}@anchor{2a30}
@subsubsection Παραδείγματα


@cartouche
@quotation Σημείωση 
Τα παραδείγματα native σειράς byte (που καθορίζονται από το πρόθεμα μορφής @code{'@@'} ή την απουσία οποιουδήποτε χαρακτήρα προθέματος) ενδέχεται να μην αντιστοιχούν σε αυτά που παράγει η μηχανή του αναγνώστη, καθώς αυτό εξαρτάται από την πλατφόρμα και τον μεταγλωττιστή.
@end quotation
@end cartouche

Συσκευασία και αποσυσκευασία ακεραίων τριών διαφορετικών μεγεθών, χρησιμοποιώντας διάταξη big endian:

@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

Προσπάθεια συσκευασίας ενός ακεραίου που είναι πολύ μεγάλος για το καθορισμένο πεδίο:

@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

Επιδεικνύει την διαφορά μεταξύ των χαρακτήρων μορφοποίησης @code{'s'} και @code{'c'}:

@example
>>> pack("@@ccc", b'1', b'2', b'3')
b'123'
>>> pack("@@3s", b'123')
b'123'
@end example

Τα αποσυσκευασμένα πεδία μπορούν να ονομαστούν είτε αναθέτοντάς τα σε μεταβλητές είτε περιτυλίγοντάς τα σε μια ονομασμένη πλειάδα:

@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

Η σειρά των χαρακτήρων μορφοποίησης μπορεί να επηρεάσει το μέγεθος σε κατάσταση native λειτουργίας, καθώς το συμπλήρωμα είναι έμμεσο. Σε τυπική λειτουργία, ο χρήστης είναι υπεύθυνος για την εισαγωγή οποιασδήποτε επιθυμητού συμπληρώματος. Σημειώστε στην πρώτη κλήση @code{pack} παρακάτω ότι προστέθηκαν τρία μηδενικά (NUL) bytes μετά την συσκευασμένη τιμή @code{'#'} για να ευθυγραμμιστεί ο επόμενος ακέραιος σε όριο τεσσάρων bytes. Σε αυτό το παράδειγμα, η έξοδος παράχθηκε σε έναν υπολογιστή με little endian αρχιτεκτονική:

@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

Η ακόλουθη μορφή @code{'llh0l'} έχει ως αποτέλεσμα την προσθήκη δύο bytes συμπλήρωσης στο τέλος, υποθέτοντας ότι οι μακροί ακέραιοι (longs) της πλατφόρμας ευθυγραμμίζονται σε όρια 4-byte:

@example
>>> pack('@@llh0l', 1, 2, 3)
b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'
@end example


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{8,,array}

Πακεταρισμένη δυαδική αποθήκευση ομοιογενών δεδομένων.

@item Module @ref{85,,json}

Κωδικοποιητής και αποκωδικοποιητής JSON.

@item Module @ref{ab,,pickle}

Σειριοποίηση αντικειμένων Python.
@end table


@node Εφαρμογές,Κλάσεις<3>,Συμβολοσειρές μορφοποίησης,struct — Ερμηνεία bytes ως πακετοποιημένα δυαδικά δεδομένα
@anchor{library/struct applications}@anchor{2a34}@anchor{library/struct id2}@anchor{2a35}
@subsubsection Εφαρμογές


Two main applications for the @code{struct} module exist, data
interchange between Python and C code within an application or another
application compiled using the same compiler (@ref{2a36,,native formats}), and
data interchange between applications using agreed upon data layout
(@ref{2a37,,standard formats}).  Generally speaking, the format strings
constructed for these two domains are distinct.

@menu
* Native Μορφές:: 
* Τυπικές μορφές:: 

@end menu

@node Native Μορφές,Τυπικές μορφές,,Εφαρμογές
@anchor{library/struct native-formats}@anchor{2a38}@anchor{library/struct struct-native-formats}@anchor{2a36}
@subsubsection Native Μορφές


Όταν κατασκευάζετε συμβολοσειρές μορφοποίησης που μιμούνται native διατάξεις, ο μεταγλωττιστής και η αρχιτεκτονική του μηχανήματος καθορίζουν τη σειρά των byte και τη συμπλήρωση. Σε τέτοιες περιπτώσεις, ο χαρακτήρας μορφής @code{@@} θα πρέπει να χρησιμοποιείται για να καθορίζει την native σειρά byte και τα μεγέθη δεδομένων. Τα εσωτερικά byte συμπλήρωσης εισάγονται συνήθως αυτόματα. Είναι πιθανό να χρειαστεί ένας κωδικός μορφοποίησης με επανάληψη μηδέν στο τέλος μιας συμβολοσειράς μορφοποίησης για να ευθυγραμμιστεί σωστά με τα όρια byte των διαδοχικών τμημάτων δεδομένων.

Εξετάστε αυτά τα δύο απλά παραδείγματα (σε έναν 64-bit, little-endian υπολογιστή):

@example
>>> calcsize('@@lhl')
24
>>> calcsize('@@llh')
18
@end example

Τα δεδομένα δεν συμπληρώνονται σε όριο 8 byte στο τέλος της δεύτερης συμβολοσειράς μορφοποίησης χωρίς τη χρήση επιπλέον συμπλήρωσης. Ένας κωδικός μορφοποίησης με επανάληψη μηδέν λύνει αυτό το πρόβλημα:

@example
>>> calcsize('@@llh0l')
24
@end example

Ο κωδικός μορφοποίησης @code{'x'} μπορεί να χρησιμοποιηθεί για να καθορίσει την επανάληψη, αλλά για native μορφές είναι προτιμότερο να χρησιμοποιείται ένας κωδικός μορφοποίησης με επανάληψη μηδέν, όπως @code{'0l'}.

Από προεπιλογή, χρησιμοποιείται η native σειρά byte και στοίχιση, αλλά είναι καλύτερο να είμαστε σαφείς και να χρησιμοποιούμε τον χαρακτήρα πρόθεμα @code{'@@'}.

@node Τυπικές μορφές,,Native Μορφές,Εφαρμογές
@anchor{library/struct standard-formats}@anchor{2a39}@anchor{library/struct struct-standard-formats}@anchor{2a37}
@subsubsection Τυπικές μορφές


Όταν ανταλλάσετε δεδομένα πέρα από τη διεργασία σας, όπως σε δικτύωση ή αποθήκευση, να είστε ακριβείς. Καθορίστε την ακριβή σειρά των byte, το μέγεθος και την ευθυγράμμιση. Μην υποθέτετε ότι ταιριάζουν με τη φυσική σειρά μιας συγκεκριμένης μηχανής. Για παράδειγμα, η σειρά byte του δικτύου είναι big-endian, ενώ πολλοί δημοφιλείς επεξεργαστές είναι little-endian. Ορίζοντας αυτό ρητά, ο χρήστης δεν χρειάζεται να ενδιαφέρεται για τις λεπτομέρειες της πλατφόρμας στην οποία εκτελείται ο κώδικας. Ο πρώτος χαρακτήρας πρέπει τυπικά να είναι @code{<} ή @code{>} (ή @code{!}). Η ευθύνη για την προσθήκη συμπληρωματικών byte ανήκει στον προγραμματιστή. Ο χαρακτήρας μορφής με μηδενική επανάληψη δεν θα λειτουργήσει. Αντ” αυτού, ο χρήστης πρέπει να προσθέτει ρητά byte @code{'x'} όπου απαιτείται. Επανεξετάζοντας τα παραδείγματα από την προηγούμενη ενότητα, έχουμε:

@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

Τα παραπάνω αποτελέσματα (εκτελεσμένα σε 64-bit μηχανή) δεν είναι εγγυημένο ότι θα ταιριάζουν όταν εκτελούνται σε διαφορετικές μηχανές. Για παράδειγμα, τα παρακάτω παραδείγματα εκτελέστηκαν σε 32-bit μηχανή:

@example
>>> calcsize('<qqh6x')
24
>>> calcsize('@@llh0l')
12
>>> pack('@@llh0l', 1, 2, 3) == pack('<qqh6x', 1, 2, 3)
False
@end example

@node Κλάσεις<3>,,Εφαρμογές,struct — Ερμηνεία bytes ως πακετοποιημένα δυαδικά δεδομένα
@anchor{library/struct classes}@anchor{2a3a}@anchor{library/struct struct-objects}@anchor{2a3b}
@subsubsection Κλάσεις


The @code{struct} module also defines the following type:

@geindex Struct (κλάση σε struct)
@anchor{library/struct struct Struct}@anchor{2fb}
@deffn {Κλάση} struct.Struct (format)

Επιστρέφει ένα νέο αντικείμενο Struct που γράφει και διαβάζει δυαδικά δεδομένα σύμφωνα με τη συμβολοσειρά μορφοποίησης `format'. Η δημιουργία ενός αντικειμένου @code{Struct} μια φορά και η κλήση των μεθόδων του είναι πιο αποδοτική από την κλήση συναρτήσεων σε επίπεδο module με την ίδια μορφή, καθώς η συμβολοσειρά μορφοποίησης μεταγλωττίζεται μόνο μία φορά.

@cartouche
@quotation Σημείωση 
Οι μεταγλωττισμένες εκδόσεις των πιο πρόσφατων συμβολοσειρών μορφοποίησης που περνούν στις συναρτήσεις του module αποθηκεύονται προσωρινά, επομένως τα προγράμματα που χρησιμοποιούν μόνο λίγες συμβολοσειρές μορφοποίησης δεν χρειάζεται να ανησυχούν για την επαναχρησιμοποίηση μιας μεμονωμένης περίπτωσης της κλάσης @ref{2fb,,Struct}.
@end quotation
@end cartouche

Τα μεταγλωττισμένα αντικείμενα Struct υποστηρίζουν τις ακόλουθες μεθόδους και ιδιότητες:

@geindex pack() (μέθοδος της struct.Struct)
@anchor{library/struct struct Struct pack}@anchor{2a3c}
@deffn {Μέθοδος} pack (v1, v2, ...)

Ταυτόσημο με τη συνάρτηση @ref{161b,,pack()}, χρησιμοποιώντας τη μεταγλωττισμένη μορφή. (@code{len(result)} θα είναι ίσο με @ref{2a3d,,size}.)
@end deffn

@geindex pack_into() (μέθοδος της struct.Struct)
@anchor{library/struct struct Struct pack_into}@anchor{2a3e}
@deffn {Μέθοδος} pack_into (buffer, offset, v1, v2, ...)

Ταυτόσημο με τη συνάρτηση @ref{1966,,pack_into()}, χρησιμοποιώντας τη μεταγλωττισμένη μορφή.
@end deffn

@geindex unpack() (μέθοδος της struct.Struct)
@anchor{library/struct struct Struct unpack}@anchor{2a3f}
@deffn {Μέθοδος} unpack (buffer)

Ταυτόσημο με τη συνάρτηση @ref{1a82,,unpack()}, χρησιμοποιώντας τη μεταγλωττισμένη μορφή. Το μέγεθος του buffer σε bytes πρέπει να είναι ίσο με @ref{2a3d,,size}.
@end deffn

@geindex unpack_from() (μέθοδος της struct.Struct)
@anchor{library/struct struct Struct unpack_from}@anchor{2a40}
@deffn {Μέθοδος} unpack_from (buffer, offset=0)

Ταυτόσημο με τη συνάρτηση @ref{2a2c,,unpack_from()}, χρησιμοποιώντας τη μεταγλωττισμένη μορφή. Το μέγεθος του buffer σε bytes, ξεκινώντας από τη θέση `offset', πρέπει να είναι τουλάχιστον @ref{2a3d,,size}.
@end deffn

@geindex iter_unpack() (μέθοδος της struct.Struct)
@anchor{library/struct struct Struct iter_unpack}@anchor{1369}
@deffn {Μέθοδος} iter_unpack (buffer)

Ταυτόσημο με τη συνάρτηση @ref{1368,,iter_unpack()}, χρησιμοποιώντας τη μεταγλωττισμένη μορφή. Το μέγεθος του buffer σε bytes πρέπει να είναι πολλαπλάσιο του @ref{2a3d,,size}.


Added in version 3.4.

@end deffn

@geindex format (ιδιότητα της struct.Struct)
@anchor{library/struct struct Struct format}@anchor{fc5}
@deffn {Ιδιότητα} format

Η συμβολοσειρά μορφής που χρησιμοποιήθηκε για τη δημιουργία αυτού του αντικειμένου Struct.


Άλλαξε στην έκδοση 3.7: Ο τύπος της συμβολοσειράς μορφής είναι πλέον @ref{1df,,str} αντί για @ref{1c7,,bytes}.

@end deffn

@geindex size (ιδιότητα της struct.Struct)
@anchor{library/struct struct Struct size}@anchor{2a3d}
@deffn {Ιδιότητα} size

Το υπολογισμένο μέγεθος της δομής (και κατά συνέπεια του αντικειμένου bytes που παράγεται από τη μέθοδο @ref{161b,,pack()}) που αντιστοιχεί στη @ref{439,,format}.
@end deffn


Άλλαξε στην έκδοση 3.13: Η `repr()' αναπαράσταση των δομών έχει αλλάξει.  Είναι πλέον:

@example
>>> Struct('i')
Struct('i')
@end example

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node codecs — Codec registry and base classes,,struct — Ερμηνεία bytes ως πακετοποιημένα δυαδικά δεδομένα,Υπηρεσίες Δυαδικών Δεδομένων
@anchor{library/codecs doc}@anchor{2a41}@anchor{library/codecs codecs-codec-registry-and-base-classes}@anchor{2a42}@anchor{library/codecs module-codecs}@anchor{1c}@anchor{library/codecs translation-repo}@anchor{2a43}
@subsection @code{codecs} — Codec registry and base classes


@geindex module; codecs

`Source code:' Lib/codecs.py@footnote{https://github.com/python/cpython/tree/main/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{27d4,,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
text encodings or with codecs that encode to
@ref{1c7,,bytes}.

The module defines the following functions for encoding and decoding with
any codec:

@geindex encode() (στη μονάδα codecs)
@anchor{library/codecs codecs encode}@anchor{12b2}
@deffn {Συνάρτηση} codecs.encode (obj, encoding='utf-8', errors='strict')

Encodes `obj' using the codec registered for `encoding'.

`Errors' may be given to set the desired error handling scheme. The
default error handler is @code{'strict'} meaning that encoding errors raise
@ref{277,,ValueError} (or a more codec specific subclass, such as
@ref{a67,,UnicodeEncodeError}). Refer to @ref{2a44,,Codec Base Classes} for more
information on codec error handling.
@end deffn

@geindex decode() (στη μονάδα codecs)
@anchor{library/codecs codecs decode}@anchor{12b3}
@deffn {Συνάρτηση} codecs.decode (obj, encoding='utf-8', errors='strict')

Decodes `obj' using the codec registered for `encoding'.

`Errors' may be given to set the desired error handling scheme. The
default error handler is @code{'strict'} meaning that decoding errors raise
@ref{277,,ValueError} (or a more codec specific subclass, such as
@ref{dd7,,UnicodeDecodeError}). Refer to @ref{2a44,,Codec Base Classes} for more
information on codec error handling.
@end deffn

@geindex charmap_build() (στη μονάδα codecs)
@anchor{library/codecs codecs charmap_build}@anchor{2a45}
@deffn {Συνάρτηση} codecs.charmap_build (string)

Return a mapping suitable for encoding with a custom single-byte encoding.
Given a @ref{1df,,str} `string' of up to 256 characters representing a
decoding table, returns either a compact internal mapping object
@code{EncodingMap} or a @ref{188,,dictionary} mapping character ordinals
to byte values. Raises a @ref{291,,TypeError} on invalid input.
@end deffn

The full details for each codec can also be looked up directly:

@geindex lookup() (στη μονάδα codecs)
@anchor{library/codecs codecs lookup}@anchor{d2d}
@deffn {Συνάρτηση} codecs.lookup (encoding, /)

Looks up the codec info in the Python codec registry and returns a
@ref{1c72,,CodecInfo} object as defined below.

This function first normalizes the `encoding': all ASCII letters are
converted to lower case, spaces are replaced with hyphens.
Then encoding is looked up in the registry’s cache. If not found, the list of
registered search functions is scanned. If no @ref{1c72,,CodecInfo} object is
found, a @ref{25da,,LookupError} is raised. Otherwise, the @code{CodecInfo} object
is stored in the cache and returned to the caller.


Άλλαξε στην έκδοση 3.9: Any characters except ASCII letters and digits and a dot are converted to underscore.



Άλλαξε στην έκδοση 3.15: No characters are converted to underscore anymore.
Spaces are converted to hyphens.

@end deffn

@geindex CodecInfo (κλάση σε codecs)
@anchor{library/codecs codecs CodecInfo}@anchor{1c72}
@deffn {Κλάση} codecs.CodecInfo (encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)

Codec details when looking up the codec registry. The constructor
arguments are stored in attributes of the same name:

@geindex name (ιδιότητα της codecs.CodecInfo)
@anchor{library/codecs codecs CodecInfo name}@anchor{2a46}
@deffn {Ιδιότητα} name

The name of the encoding.
@end deffn

@geindex encode (ιδιότητα της codecs.CodecInfo)
@geindex decode (ιδιότητα της codecs.CodecInfo)
@anchor{library/codecs codecs CodecInfo encode}@anchor{2a47}
@deffn {Ιδιότητα} encode
@anchor{library/codecs codecs CodecInfo decode}@anchor{2a48}
@deffnx {Ιδιότητα} decode

The stateless encoding and decoding functions. These must be
functions or methods which have the same interface as
the @ref{19ad,,encode()} and @ref{2a49,,decode()} methods of Codec
instances (see @ref{2a4a,,Codec Interface}).
The functions or methods are expected to work in a stateless mode.
@end deffn

@geindex incrementalencoder (ιδιότητα της codecs.CodecInfo)
@geindex incrementaldecoder (ιδιότητα της codecs.CodecInfo)
@anchor{library/codecs codecs CodecInfo incrementalencoder}@anchor{2a4b}
@deffn {Ιδιότητα} incrementalencoder
@anchor{library/codecs codecs CodecInfo incrementaldecoder}@anchor{2a4c}
@deffnx {Ιδιότητα} incrementaldecoder

Incremental encoder and decoder classes or factory functions.
These have to provide the interface defined by the base classes
@ref{2a4d,,IncrementalEncoder} and @ref{2a4e,,IncrementalDecoder},
respectively. Incremental codecs can maintain state.
@end deffn

@geindex streamwriter (ιδιότητα της codecs.CodecInfo)
@geindex streamreader (ιδιότητα της codecs.CodecInfo)
@anchor{library/codecs codecs CodecInfo streamwriter}@anchor{2a4f}
@deffn {Ιδιότητα} streamwriter
@anchor{library/codecs codecs CodecInfo streamreader}@anchor{2a50}
@deffnx {Ιδιότητα} streamreader

Stream writer and reader classes or factory functions. These have to
provide the interface defined by the base classes
@ref{2a51,,StreamWriter} and @ref{2a52,,StreamReader}, respectively.
Stream codecs can maintain state.
@end deffn
@end deffn

To simplify access to the various codec components, the module provides
these additional functions which use @ref{d2d,,lookup()} for the codec lookup:

@geindex getencoder() (στη μονάδα codecs)
@anchor{library/codecs codecs getencoder}@anchor{2a53}
@deffn {Συνάρτηση} codecs.getencoder (encoding)

Look up the codec for the given encoding and return its encoder function.

Raises a @ref{25da,,LookupError} in case the encoding cannot be found.
@end deffn

@geindex getdecoder() (στη μονάδα codecs)
@anchor{library/codecs codecs getdecoder}@anchor{2a54}
@deffn {Συνάρτηση} codecs.getdecoder (encoding)

Look up the codec for the given encoding and return its decoder function.

Raises a @ref{25da,,LookupError} in case the encoding cannot be found.
@end deffn

@geindex getincrementalencoder() (στη μονάδα codecs)
@anchor{library/codecs codecs getincrementalencoder}@anchor{2a55}
@deffn {Συνάρτηση} codecs.getincrementalencoder (encoding)

Look up the codec for the given encoding and return its incremental encoder
class or factory function.

Raises a @ref{25da,,LookupError} in case the encoding cannot be found or the codec
doesn’t support an incremental encoder.
@end deffn

@geindex getincrementaldecoder() (στη μονάδα codecs)
@anchor{library/codecs codecs getincrementaldecoder}@anchor{2a56}
@deffn {Συνάρτηση} codecs.getincrementaldecoder (encoding)

Look up the codec for the given encoding and return its incremental decoder
class or factory function.

Raises a @ref{25da,,LookupError} in case the encoding cannot be found or the codec
doesn’t support an incremental decoder.
@end deffn

@geindex getreader() (στη μονάδα codecs)
@anchor{library/codecs codecs getreader}@anchor{2a57}
@deffn {Συνάρτηση} codecs.getreader (encoding)

Look up the codec for the given encoding and return its @ref{2a52,,StreamReader}
class or factory function.

Raises a @ref{25da,,LookupError} in case the encoding cannot be found.
@end deffn

@geindex getwriter() (στη μονάδα codecs)
@anchor{library/codecs codecs getwriter}@anchor{2a58}
@deffn {Συνάρτηση} codecs.getwriter (encoding)

Look up the codec for the given encoding and return its @ref{2a51,,StreamWriter}
class or factory function.

Raises a @ref{25da,,LookupError} in case the encoding cannot be found.
@end deffn

Custom codecs are made available by registering a suitable codec search
function:

@geindex register() (στη μονάδα codecs)
@anchor{library/codecs codecs register}@anchor{2a59}
@deffn {Συνάρτηση} 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 spaces
converted to hyphens, and return a @ref{1c72,,CodecInfo} object.
In case a search function cannot find a given encoding, it should return
@code{None}.
@end deffn

@geindex unregister() (στη μονάδα codecs)
@anchor{library/codecs codecs unregister}@anchor{bc4}
@deffn {Συνάρτηση} codecs.unregister (search_function, /)

Unregister a codec search function and clear the registry’s cache.
If the search function is not registered, do nothing.


Added in version 3.10.

@end deffn

While the builtin @ref{32b,,open()} and the associated @ref{82,,io} module are the
recommended approach for working with encoded text files, this module
provides additional utility functions and classes that allow the use of a
wider range of codecs when working with binary files:

@geindex open() (στη μονάδα codecs)
@anchor{library/codecs codecs open}@anchor{32c}
@deffn {Συνάρτηση} codecs.open (filename, mode='r', encoding=None, errors='strict', buffering=-1)

Open an encoded file using the given `mode' and return an instance of
@ref{2a5a,,StreamReaderWriter}, providing transparent encoding/decoding.
The default file mode is @code{'r'}, meaning to open the file in read mode.

@cartouche
@quotation Σημείωση 
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
@code{open()} function; the @code{'b'} is automatically added.
@end quotation
@end cartouche

`encoding' specifies the encoding which is to be used for the file.
Any encoding that encodes to and decodes from bytes is allowed, and
the data types supported by the file methods depend on the codec used.

`errors' may be given to define the error handling. It defaults to @code{'strict'}
which causes a @ref{277,,ValueError} to be raised in case an encoding error occurs.

`buffering' has the same meaning as for the built-in @code{open()} function.
It defaults to -1 which means that the default buffer size will be used.


Άλλαξε στην έκδοση 3.11: The @code{'U'} mode has been removed.



Αποσύρθηκε στην έκδοση 3.14: @ref{32c,,codecs.open()} has been superseded by @code{open()}.

@end deffn

@geindex EncodedFile() (στη μονάδα codecs)
@anchor{library/codecs codecs EncodedFile}@anchor{2a5b}
@deffn {Συνάρτηση} codecs.EncodedFile (file, data_encoding, file_encoding=None, errors='strict')

Return a @ref{1fc3,,StreamRecoder} instance, a wrapped version of `file'
which provides transparent transcoding. The original file is closed
when the wrapped version is closed.

Data written to the wrapped file is decoded according to the given
`data_encoding' and then written to the original file as bytes using
`file_encoding'. Bytes read from the original file are decoded
according to `file_encoding', and the result is encoded
using `data_encoding'.

If `file_encoding' is not given, it defaults to `data_encoding'.

`errors' may be given to define the error handling. It defaults to
@code{'strict'}, which causes @ref{277,,ValueError} to be raised in case an encoding
error occurs.
@end deffn

@geindex iterencode() (στη μονάδα codecs)
@anchor{library/codecs codecs iterencode}@anchor{2a5c}
@deffn {Συνάρτηση} codecs.iterencode (iterator, encoding, errors='strict', **kwargs)

Uses an incremental encoder to iteratively encode the input provided by
`iterator'. `iterator' must yield @ref{1df,,str} objects.
This function is a @ref{1409,,generator}. The `errors' argument (as well as any
other keyword argument) is passed through to the incremental encoder.

This function requires that the codec accept text @ref{1df,,str} objects
to encode. Therefore it does not support bytes-to-bytes encoders such as
@code{base64_codec}.
@end deffn

@geindex iterdecode() (στη μονάδα codecs)
@anchor{library/codecs codecs iterdecode}@anchor{2a5d}
@deffn {Συνάρτηση} codecs.iterdecode (iterator, encoding, errors='strict', **kwargs)

Uses an incremental decoder to iteratively decode the input provided by
`iterator'. `iterator' must yield @ref{1c7,,bytes} objects.
This function is a @ref{1409,,generator}. The `errors' argument (as well as any
other keyword argument) is passed through to the incremental decoder.

This function requires that the codec accept @ref{1c7,,bytes} objects
to decode. Therefore it does not support text-to-text encoders such as
@code{rot_13}, although @code{rot_13} may be used equivalently with
@ref{2a5c,,iterencode()}.
@end deffn

@geindex readbuffer_encode() (στη μονάδα codecs)
@anchor{library/codecs codecs readbuffer_encode}@anchor{2a5e}
@deffn {Συνάρτηση} codecs.readbuffer_encode (buffer, errors=None, /)

Return a @ref{1ce,,tuple} containing the raw bytes of `buffer', a
@ref{311,,buffer-compatible object} or @ref{1df,,str}
(encoded to UTF-8 before processing), and their length in bytes.

The `errors' argument is ignored.

@example
>>> codecs.readbuffer_encode(b"Zito")
(b'Zito', 4)
@end example
@end deffn

The module also provides the following constants which are useful for reading
and writing to platform dependent files:

@geindex BOM (στη μονάδα codecs)
@geindex BOM_BE (στη μονάδα codecs)
@geindex BOM_LE (στη μονάδα codecs)
@geindex BOM_UTF8 (στη μονάδα codecs)
@geindex BOM_UTF16 (στη μονάδα codecs)
@geindex BOM_UTF16_BE (στη μονάδα codecs)
@geindex BOM_UTF16_LE (στη μονάδα codecs)
@geindex BOM_UTF32 (στη μονάδα codecs)
@geindex BOM_UTF32_BE (στη μονάδα codecs)
@geindex BOM_UTF32_LE (στη μονάδα codecs)
@anchor{library/codecs codecs BOM}@anchor{2a5f}
@deffn {Δεδομένα} codecs.BOM
@anchor{library/codecs codecs BOM_BE}@anchor{2a60}
@deffnx {Δεδομένα} codecs.BOM_BE
@anchor{library/codecs codecs BOM_LE}@anchor{2a61}
@deffnx {Δεδομένα} codecs.BOM_LE
@anchor{library/codecs codecs BOM_UTF8}@anchor{2a62}
@deffnx {Δεδομένα} codecs.BOM_UTF8
@anchor{library/codecs codecs BOM_UTF16}@anchor{2a63}
@deffnx {Δεδομένα} codecs.BOM_UTF16
@anchor{library/codecs codecs BOM_UTF16_BE}@anchor{2a64}
@deffnx {Δεδομένα} codecs.BOM_UTF16_BE
@anchor{library/codecs codecs BOM_UTF16_LE}@anchor{2a65}
@deffnx {Δεδομένα} codecs.BOM_UTF16_LE
@anchor{library/codecs codecs BOM_UTF32}@anchor{2a66}
@deffnx {Δεδομένα} codecs.BOM_UTF32
@anchor{library/codecs codecs BOM_UTF32_BE}@anchor{2a67}
@deffnx {Δεδομένα} codecs.BOM_UTF32_BE
@anchor{library/codecs codecs BOM_UTF32_LE}@anchor{2a68}
@deffnx {Δεδομένα} codecs.BOM_UTF32_LE

These constants define various byte sequences,
being Unicode byte order marks (BOMs) for several encodings. They are
used in UTF-16 and UTF-32 data streams to indicate the byte order used,
and in UTF-8 as a Unicode signature. @ref{2a63,,BOM_UTF16} is either
@ref{2a64,,BOM_UTF16_BE} or @ref{2a65,,BOM_UTF16_LE} depending on the platform’s
native byte order, @ref{2a5f,,BOM} is an alias for @code{BOM_UTF16},
@ref{2a61,,BOM_LE} for @code{BOM_UTF16_LE} and @ref{2a60,,BOM_BE} for
@code{BOM_UTF16_BE}. The others represent the BOM in UTF-8 and UTF-32
encodings.
@end deffn

@menu
* Codec Base Classes:: 
* Encodings and Unicode:: 
* Standard Encodings:: 
* Python Specific Encodings:: 
* encodings — Encodings package:: 
* encodings.idna — Internationalized Domain Names in Applications: encodings idna — Internationalized Domain Names in Applications. 
* encodings.mbcs — Windows ANSI codepage: encodings mbcs — Windows ANSI codepage. 
* encodings.utf_8_sig — UTF-8 codec with BOM signature: encodings utf_8_sig — UTF-8 codec with BOM signature. 

@end menu

@node Codec Base Classes,Encodings and Unicode,,codecs — Codec registry and base classes
@anchor{library/codecs codec-base-classes}@anchor{2a44}@anchor{library/codecs id1}@anchor{2a69}
@subsubsection Codec Base Classes


The @code{codecs} module defines a set of base classes which define the
interfaces for working with codec objects, and can also be used as the basis
for custom codec implementations.

Each codec has to define four interfaces to make it usable as codec in Python:
stateless encoder, stateless decoder, stream reader and stream writer. The
stream reader and writers typically reuse the stateless encoder/decoder to
implement the file protocols. Codec authors also need to define how the
codec will handle encoding and decoding errors.
@anchor{library/codecs surrogateescape}@anchor{2a6a}
@menu
* Error Handlers:: 
* Stateless Encoding and Decoding:: 
* Incremental Encoding and Decoding:: 
* Stream Encoding and Decoding:: 

@end menu

@node Error Handlers,Stateless Encoding and Decoding,,Codec Base Classes
@anchor{library/codecs error-handlers}@anchor{1d6c}@anchor{library/codecs id2}@anchor{2a6b}
@subsubsection Error Handlers


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{1171,,Standard Encodings} codecs:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Value

@tab

Meaning

@item

@code{'strict'}

@tab

Raise @ref{675,,UnicodeError} (or a subclass),
this is the default. Implemented in
@ref{2a6c,,strict_errors()}.

@item

@code{'ignore'}

@tab

Ignore the malformed data and continue without
further notice. Implemented in
@ref{2a6d,,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{1ae3,,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{1ae4,,backslashreplace_errors()}.

@item

@code{'surrogateescape'}

@tab

On decoding, replace byte with individual
surrogate code ranging from @code{U+DC80} to
@code{U+DCFF}. This code will then be turned
back into the same byte when the
@code{'surrogateescape'} error handler is used
when encoding the data. (See 
@geindex Python Enhancement Proposals; PEP 383
PEP 383@footnote{https://peps.python.org/pep-0383/} for
more.)

@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{27d4,,text encodings}):


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Value

@tab

Meaning

@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{1ae5,,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{2a6e,,namereplace_errors()}.

@end multitable


@geindex surrogatepass;error handler's name

In addition, the following error handler is specific to the given codecs:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Value

@tab

Codecs

@tab

Meaning

@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{1df,,str} as an error.

@end multitable



Added in version 3.1: The @code{'surrogateescape'} and @code{'surrogatepass'} error handlers.



Άλλαξε στην έκδοση 3.4: The @code{'surrogatepass'} error handler now works with utf-16* and utf-32*
codecs.



Added in version 3.5: The @code{'namereplace'} error handler.



Άλλαξε στην έκδοση 3.5: The @code{'backslashreplace'} error handler now works with decoding and
translating.


The set of allowed values can be extended by registering a new named error
handler:

@geindex register_error() (στη μονάδα codecs)
@anchor{library/codecs codecs register_error}@anchor{183d}
@deffn {Συνάρτηση} 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{a67,,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{1df,,str} or
@ref{1c7,,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{18d7,,IndexError} will be raised.

Decoding and translating works similarly, except @ref{dd7,,UnicodeDecodeError} or
@ref{1b1c,,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() (στη μονάδα codecs)
@anchor{library/codecs codecs lookup_error}@anchor{183e}
@deffn {Συνάρτηση} codecs.lookup_error (name, /)

Return the error handler previously registered under the name `name'.

Raises a @ref{25da,,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() (στη μονάδα codecs)
@anchor{library/codecs codecs strict_errors}@anchor{2a6c}
@deffn {Συνάρτηση} codecs.strict_errors (exception)

Implements the @code{'strict'} error handling.

Each encoding or decoding error raises a @ref{675,,UnicodeError}.
@end deffn

@geindex ignore_errors() (στη μονάδα codecs)
@anchor{library/codecs codecs ignore_errors}@anchor{2a6d}
@deffn {Συνάρτηση} 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() (στη μονάδα codecs)
@anchor{library/codecs codecs replace_errors}@anchor{1ae3}
@deffn {Συνάρτηση} 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() (στη μονάδα codecs)
@anchor{library/codecs codecs backslashreplace_errors}@anchor{1ae4}
@deffn {Συνάρτηση} 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}}.


Άλλαξε στην έκδοση 3.5: Works with decoding and translating.

@end deffn

@geindex xmlcharrefreplace_errors() (στη μονάδα codecs)
@anchor{library/codecs codecs xmlcharrefreplace_errors}@anchor{1ae5}
@deffn {Συνάρτηση} codecs.xmlcharrefreplace_errors (exception)

Implements the @code{'xmlcharrefreplace'} error handling (for encoding within
@ref{27d4,,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() (στη μονάδα codecs)
@anchor{library/codecs codecs namereplace_errors}@anchor{2a6e}
@deffn {Συνάρτηση} codecs.namereplace_errors (exception)

Implements the @code{'namereplace'} error handling (for encoding within
@ref{27d4,,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@}} .


Added in version 3.5.

@end deffn

@node Stateless Encoding and Decoding,Incremental Encoding and Decoding,Error Handlers,Codec Base Classes
@anchor{library/codecs codec-objects}@anchor{2a4a}@anchor{library/codecs stateless-encoding-and-decoding}@anchor{2a6f}
@subsubsection Stateless Encoding and Decoding


The base @ref{2a70,,Codec} class defines these methods which also define the
function interfaces of the stateless encoder and decoder:

@geindex Codec (κλάση σε codecs)
@anchor{library/codecs codecs Codec}@anchor{2a70}
@deffn {Κλάση} codecs.Codec

@geindex encode() (μέθοδος της codecs.Codec)
@anchor{library/codecs codecs Codec encode}@anchor{19ad}
@deffn {Μέθοδος} encode (input, errors='strict')

Encodes the object `input' and returns a tuple (output object, length consumed).
For instance, @ref{27d4,,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 @code{Codec} instance. Use
@ref{2a51,,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() (μέθοδος της codecs.Codec)
@anchor{library/codecs codecs Codec decode}@anchor{2a49}
@deffn {Μέθοδος} decode (input, errors='strict')

Decodes the object `input' and returns a tuple (output object, length
consumed). For instance, for a @ref{27d4,,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 @code{Codec} instance. Use
@ref{2a52,,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,Codec Base Classes
@anchor{library/codecs incremental-encoding-and-decoding}@anchor{2a71}
@subsubsection Incremental Encoding and Decoding


The @ref{2a4d,,IncrementalEncoder} and @ref{2a4e,,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{19ae,,encode()}/@ref{2a72,,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{19ae,,encode()}/@ref{2a72,,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{2a73}@anchor{library/codecs incrementalencoder-objects}@anchor{2a74}
@subsubsection IncrementalEncoder Objects


The @ref{2a4d,,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 (κλάση σε codecs)
@anchor{library/codecs codecs IncrementalEncoder}@anchor{2a4d}
@deffn {Κλάση} codecs.IncrementalEncoder (errors='strict')

Constructor for an @code{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 @code{IncrementalEncoder} may implement different error handling schemes
by providing the `errors' keyword argument. See @ref{1d6c,,Error Handlers} 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 @code{IncrementalEncoder}
object.

@geindex encode() (μέθοδος της codecs.IncrementalEncoder)
@anchor{library/codecs codecs IncrementalEncoder encode}@anchor{19ae}
@deffn {Μέθοδος} 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
@code{encode()} `final' must be true (the default is false).
@end deffn

@geindex reset() (μέθοδος της codecs.IncrementalEncoder)
@anchor{library/codecs codecs IncrementalEncoder reset}@anchor{2a75}
@deffn {Μέθοδος} 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() (μέθοδος της codecs.IncrementalEncoder)
@anchor{library/codecs codecs IncrementalEncoder getstate}@anchor{2a76}
@deffn {Μέθοδος} 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() (μέθοδος της codecs.IncrementalEncoder)
@anchor{library/codecs codecs IncrementalEncoder setstate}@anchor{2a77}
@deffn {Μέθοδος} setstate (state)

Set the state of the encoder to `state'. `state' must be an encoder state
returned by @ref{2a76,,getstate()}.
@end deffn
@end deffn

@node IncrementalDecoder Objects,,IncrementalEncoder Objects,Incremental Encoding and Decoding
@anchor{library/codecs incremental-decoder-objects}@anchor{2a78}@anchor{library/codecs incrementaldecoder-objects}@anchor{2a79}
@subsubsection IncrementalDecoder Objects


The @ref{2a4e,,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 (κλάση σε codecs)
@anchor{library/codecs codecs IncrementalDecoder}@anchor{2a4e}
@deffn {Κλάση} codecs.IncrementalDecoder (errors='strict')

Constructor for an @code{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 @code{IncrementalDecoder} may implement different error handling schemes
by providing the `errors' keyword argument. See @ref{1d6c,,Error Handlers} 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 @code{IncrementalDecoder}
object.

@geindex decode() (μέθοδος της codecs.IncrementalDecoder)
@anchor{library/codecs codecs IncrementalDecoder decode}@anchor{2a72}
@deffn {Μέθοδος} 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
@code{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() (μέθοδος της codecs.IncrementalDecoder)
@anchor{library/codecs codecs IncrementalDecoder reset}@anchor{2a7a}
@deffn {Μέθοδος} reset ()

Reset the decoder to the initial state.
@end deffn

@geindex getstate() (μέθοδος της codecs.IncrementalDecoder)
@anchor{library/codecs codecs IncrementalDecoder getstate}@anchor{2a7b}
@deffn {Μέθοδος} 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() (μέθοδος της codecs.IncrementalDecoder)
@anchor{library/codecs codecs IncrementalDecoder setstate}@anchor{2a7c}
@deffn {Μέθοδος} setstate (state)

Set the state of the decoder to `state'. `state' must be a decoder state
returned by @ref{2a7b,,getstate()}.
@end deffn
@end deffn

@node Stream Encoding and Decoding,,Incremental Encoding and Decoding,Codec Base Classes
@anchor{library/codecs stream-encoding-and-decoding}@anchor{2a7d}
@subsubsection Stream Encoding and Decoding


The @ref{2a51,,StreamWriter} and @ref{2a52,,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{2a7e}@anchor{library/codecs streamwriter-objects}@anchor{2a7f}
@subsubsection StreamWriter Objects


The @ref{2a51,,StreamWriter} class is a subclass of @ref{2a70,,Codec} and defines the
following methods which every stream writer must define in order to be
compatible with the Python codec registry.

@geindex StreamWriter (κλάση σε codecs)
@anchor{library/codecs codecs StreamWriter}@anchor{2a51}
@deffn {Κλάση} codecs.StreamWriter (stream, errors='strict')

Constructor for a @code{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 @code{StreamWriter} may implement different error handling schemes by
providing the `errors' keyword argument. See @ref{1d6c,,Error Handlers} 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 @code{StreamWriter} object.

@geindex write() (μέθοδος της codecs.StreamWriter)
@anchor{library/codecs codecs StreamWriter write}@anchor{2a80}
@deffn {Μέθοδος} write (object)

Writes the object’s contents encoded to the stream.
@end deffn

@geindex writelines() (μέθοδος της codecs.StreamWriter)
@anchor{library/codecs codecs StreamWriter writelines}@anchor{2a81}
@deffn {Μέθοδος} writelines (list)

Writes the concatenated iterable of strings to the stream (possibly by reusing
the @ref{2a80,,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() (μέθοδος της codecs.StreamWriter)
@anchor{library/codecs codecs StreamWriter reset}@anchor{2a82}
@deffn {Μέθοδος} 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{2a51,,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{2a83}@anchor{library/codecs streamreader-objects}@anchor{2a84}
@subsubsection StreamReader Objects


The @ref{2a52,,StreamReader} class is a subclass of @ref{2a70,,Codec} and defines the
following methods which every stream reader must define in order to be
compatible with the Python codec registry.

@geindex StreamReader (κλάση σε codecs)
@anchor{library/codecs codecs StreamReader}@anchor{2a52}
@deffn {Κλάση} codecs.StreamReader (stream, errors='strict')

Constructor for a @code{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 @code{StreamReader} may implement different error handling schemes by
providing the `errors' keyword argument. See @ref{1d6c,,Error Handlers} 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 @code{StreamReader} object.

The set of allowed values for the `errors' argument can be extended with
@ref{183d,,register_error()}.

@geindex read() (μέθοδος της codecs.StreamReader)
@anchor{library/codecs codecs StreamReader read}@anchor{2a85}
@deffn {Μέθοδος} 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{2a85,,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() (μέθοδος της codecs.StreamReader)
@anchor{library/codecs codecs StreamReader readline}@anchor{2a86}
@deffn {Μέθοδος} 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{2a85,,read()} method.

If `keepends' is false line-endings will be stripped from the lines
returned.
@end deffn

@geindex readlines() (μέθοδος της codecs.StreamReader)
@anchor{library/codecs codecs StreamReader readlines}@anchor{2a87}
@deffn {Μέθοδος} 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{12b3,,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{2a85,,read()} method.
@end deffn

@geindex reset() (μέθοδος της codecs.StreamReader)
@anchor{library/codecs codecs StreamReader reset}@anchor{2a88}
@deffn {Μέθοδος} 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{2a52,,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{2a89}@anchor{library/codecs streamreaderwriter-objects}@anchor{2a8a}
@subsubsection StreamReaderWriter Objects


The @ref{2a5a,,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{d2d,,lookup()} function to construct the instance.

@geindex StreamReaderWriter (κλάση σε codecs)
@anchor{library/codecs codecs StreamReaderWriter}@anchor{2a5a}
@deffn {Κλάση} codecs.StreamReaderWriter (stream, Reader, Writer, errors='strict')

Creates a @code{StreamReaderWriter} instance. `stream' must be a file-like
object. `Reader' and `Writer' must be factory functions or classes providing the
@ref{2a52,,StreamReader} and @ref{2a51,,StreamWriter} interface resp. Error handling
is done in the same way as defined for the stream readers and writers.
@end deffn

@ref{2a5a,,StreamReaderWriter} instances define the combined interfaces of
@ref{2a52,,StreamReader} and @ref{2a51,,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{2a8b}@anchor{library/codecs streamrecoder-objects}@anchor{2a8c}
@subsubsection StreamRecoder Objects


The @ref{1fc3,,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{d2d,,lookup()} function to construct the instance.

@geindex StreamRecoder (κλάση σε codecs)
@anchor{library/codecs codecs StreamRecoder}@anchor{1fc3}
@deffn {Κλάση} codecs.StreamRecoder (stream, encode, decode, Reader, Writer, errors='strict')

Creates a @code{StreamRecoder} instance which implements a two-way conversion:
`encode' and `decode' work on the frontend — the data visible to
code calling @ref{2a85,,read()} and @ref{2a80,,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{2a70,,Codec} interface. `Reader' and
`Writer' must be factory functions or classes providing objects of the
@ref{2a52,,StreamReader} and @ref{2a51,,StreamWriter} interface respectively.

Error handling is done in the same way as defined for the stream readers and
writers.
@end deffn

@ref{1fc3,,StreamRecoder} instances define the combined interfaces of
@ref{2a52,,StreamReader} and @ref{2a51,,StreamWriter} classes. They inherit all other
methods and attributes from the underlying stream.

@node Encodings and Unicode,Standard Encodings,Codec Base Classes,codecs — Codec registry and base classes
@anchor{library/codecs encodings-and-unicode}@anchor{2a8d}@anchor{library/codecs encodings-overview}@anchor{2a8e}
@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{27d4,,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{a67,,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, for example, you use @code{UTF-32-BE} on a little endian
machine you will always have to swap bytes on encoding and decoding.
Python’s @code{UTF-16} and @code{UTF-32} codecs avoid this problem by using the
platform’s native byte order when no BOM is present.
Python follows prevailing platform
practice, so native-endian data round-trips without redundant byte swapping,
even though the Unicode Standard defaults to big-endian when the byte order is
unspecified. When these bytes are read by a CPU with a different endianness,
the bytes have to be swapped. To be able to detect the endianness of a
@code{UTF-16} or @code{UTF-32} byte sequence, a BOM («Byte Order Mark») is used.
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.
When the first character of a @code{UTF-16} or @code{UTF-32} byte sequence is
@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{2a8f}@anchor{library/codecs standard-encodings}@anchor{1171}
@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 space or a hyphen instead of an underscore are also valid aliases
because they are equivalent when normalized by
@ref{313,,normalize_encoding()}. For example, @code{'utf-8'} is a valid
alias for the @code{'utf_8'} codec.

@cartouche
@quotation Σημείωση 
The below table lists the most common aliases, for a complete list
refer to the source aliases.py@footnote{https://github.com/python/cpython/tree/main/Lib/encodings/aliases.py} file.
@end quotation
@end cartouche

On Windows, @code{cpXXX} codecs are available for all code pages.
But only codecs listed in the following table are guaranteed to exist on
other platforms.

`Λεπτομέρεια υλοποίησης 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.


Άλλαξε στην έκδοση 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

English

@item

big5

@tab

big5-tw, csbig5

@tab

Traditional Chinese

@item

big5hkscs

@tab

big5-hkscs, hkscs

@tab

Traditional Chinese

@item

cp037

@tab

IBM037, IBM039

@tab

English

@item

cp273

@tab

273, IBM273, csIBM273

@tab

German


Added in version 3.4.


@item

cp424

@tab

EBCDIC-CP-HE, IBM424

@tab

Hebrew

@item

cp437

@tab

437, IBM437

@tab

English

@item

cp500

@tab

EBCDIC-CP-BE, EBCDIC-CP-CH,
IBM500

@tab

Western Europe

@item

cp720

@tab

@tab

Arabic

@item

cp737

@tab

@tab

Greek

@item

cp775

@tab

IBM775

@tab

Baltic languages

@item

cp850

@tab

850, IBM850

@tab

Western Europe

@item

cp852

@tab

852, IBM852

@tab

Central and Eastern Europe

@item

cp855

@tab

855, IBM855

@tab

Belarusian, Bulgarian,
Macedonian, Russian, Serbian

@item

cp856

@tab

@tab

Hebrew

@item

cp857

@tab

857, IBM857

@tab

Turkish

@item

cp858

@tab

858, IBM858

@tab

Western Europe

@item

cp860

@tab

860, IBM860

@tab

Portuguese

@item

cp861

@tab

861, CP-IS, IBM861

@tab

Icelandic

@item

cp862

@tab

862, IBM862

@tab

Hebrew

@item

cp863

@tab

863, IBM863

@tab

Canadian

@item

cp864

@tab

IBM864

@tab

Arabic

@item

cp865

@tab

865, IBM865

@tab

Danish, Norwegian

@item

cp866

@tab

866, IBM866

@tab

Russian

@item

cp869

@tab

869, CP-GR, IBM869

@tab

Greek

@item

cp874

@tab

@tab

Thai

@item

cp875

@tab

@tab

Greek

@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

Traditional Chinese

@item

cp1006

@tab

@tab

Urdu

@item

cp1026

@tab

ibm1026

@tab

Turkish

@item

cp1125

@tab

1125, ibm1125, cp866u, ruscii

@tab

Ukrainian


Added in version 3.4.


@item

cp1140

@tab

ibm1140

@tab

Western Europe

@item

cp1250

@tab

windows-1250

@tab

Central and Eastern Europe

@item

cp1251

@tab

windows-1251

@tab

Belarusian, Bulgarian,
Macedonian, Russian, Serbian

@item

cp1252

@tab

windows-1252

@tab

Western Europe

@item

cp1253

@tab

windows-1253

@tab

Greek

@item

cp1254

@tab

windows-1254

@tab

Turkish

@item

cp1255

@tab

windows-1255

@tab

Hebrew

@item

cp1256

@tab

windows-1256

@tab

Arabic

@item

cp1257

@tab

windows-1257

@tab

Baltic languages

@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

Western Europe

@item

iso8859_2

@tab

iso-8859-2, latin2, L2

@tab

Central and Eastern Europe

@item

iso8859_3

@tab

iso-8859-3, latin3, L3

@tab

Esperanto, Maltese

@item

iso8859_4

@tab

iso-8859-4, latin4, L4

@tab

Northern Europe

@item

iso8859_5

@tab

iso-8859-5, cyrillic

@tab

Belarusian, Bulgarian,
Macedonian, Russian, Serbian

@item

iso8859_6

@tab

iso-8859-6, arabic

@tab

Arabic

@item

iso8859_7

@tab

iso-8859-7, greek, greek8

@tab

Greek

@item

iso8859_8

@tab

iso-8859-8, hebrew

@tab

Hebrew

@item

iso8859_9

@tab

iso-8859-9, latin5, L5

@tab

Turkish

@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

Baltic languages

@item

iso8859_14

@tab

iso-8859-14, latin8, L8

@tab

Celtic languages

@item

iso8859_15

@tab

iso-8859-15, latin9, L9

@tab

Western Europe

@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

Russian

@item

koi8_t

@tab

@tab

Tajik


Added in version 3.5.


@item

koi8_u

@tab

@tab

Ukrainian

@item

kz1048

@tab

kz_1048, strk1048_2002, rk1048

@tab

Kazakh


Added in version 3.5.


@item

mac_cyrillic

@tab

maccyrillic

@tab

Belarusian, Bulgarian,
Macedonian, Russian, Serbian

@item

mac_greek

@tab

macgreek

@tab

Greek

@item

mac_iceland

@tab

maciceland

@tab

Icelandic

@item

mac_latin2

@tab

maclatin2, maccentraleurope,
mac_centeuro

@tab

Central and Eastern Europe

@item

mac_roman

@tab

macroman, macintosh

@tab

Western Europe

@item

mac_turkish

@tab

macturkish

@tab

Turkish

@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

utf8-sig

@tab

all languages

@end multitable



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.8: @code{cp65001} is now an alias to @code{utf_8}.



Άλλαξε στην έκδοση 3.14: On Windows, @code{cpXXX} codecs are now available for all code pages.


@node Python Specific Encodings,encodings — Encodings package,Standard Encodings,codecs — Codec registry and base classes
@anchor{library/codecs python-specific-encodings}@anchor{2a90}
@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:: 
* Standalone Codec Functions:: 
* Text Transforms:: 

@end menu

@node Text Encodings,Binary Transforms,,Python Specific Encodings
@anchor{library/codecs text-encodings}@anchor{2a91}
@subsubsection Text Encodings


The following codecs provide @ref{1df,,str} to @ref{1c7,,bytes} encoding and
@ref{436,,bytes-like object} to @code{str} decoding, similar to the Unicode text
encodings.


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Codec

@tab

Aliases

@tab

Meaning

@item

idna

@tab

@tab

Implement 
@geindex RFC; RFC 3490
RFC 3490@footnote{https://datatracker.ietf.org/doc/html/rfc3490.html},
see also
@ref{55,,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).


Added in 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

This Codec should only
be used for testing
purposes.

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



Άλλαξε στην έκδοση 3.8: «unicode_internal» codec is removed.


@node Binary Transforms,Standalone Codec Functions,Text Encodings,Python Specific Encodings
@anchor{library/codecs binary-transforms}@anchor{12b4}@anchor{library/codecs id4}@anchor{2a92}
@subsubsection Binary Transforms


The following codecs provide binary transforms: @ref{436,,bytes-like object}
to @ref{1c7,,bytes} mappings. They are not supported by @ref{ca8,,bytes.decode()}
(which only produces @ref{1df,,str} output).


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Codec

@tab

Aliases

@tab

Meaning

@tab

Encoder / decoder

@item

base64_codec @footnote{
In addition to @ref{436,,bytes-like objects},
@code{'base64_codec'} also accepts ASCII-only instances of @ref{1df,,str} for
decoding
}

@tab

base64, base_64

@tab

Convert the operand to
multiline MIME base64 (the
result always includes a
trailing @code{'\n'}).


Άλλαξε στην έκδοση 3.4: accepts any
@ref{436,,bytes-like object}
as input for encoding and
decoding


@tab

@ref{d1e,,base64.encodebytes()} /
@ref{d1f,,base64.decodebytes()}

@item

bz2_codec

@tab

bz2

@tab

Compress the operand using
bz2.

@tab

@ref{2a93,,bz2.compress()} /
@ref{143c,,bz2.decompress()}

@item

hex_codec

@tab

hex

@tab

Convert the operand to
hexadecimal
representation, with two
digits per byte.

@tab

@ref{192b,,binascii.b2a_hex()} /
@ref{1fe,,binascii.a2b_hex()}

@item

quopri_codec

@tab

quopri,
quotedprintable,
quoted_printable

@tab

Convert the operand to MIME
quoted printable.

@tab

@ref{2a94,,quopri.encode()} with
@code{quotetabs=True} /
@ref{2a95,,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{a2e,,zlib.compress()} /
@ref{10c8,,zlib.decompress()}

@end multitable



Added in version 3.2: Restoration of the binary transforms.



Άλλαξε στην έκδοση 3.4: Restoration of the aliases for the binary transforms.


@node Standalone Codec Functions,Text Transforms,Binary Transforms,Python Specific Encodings
@anchor{library/codecs id6}@anchor{2a96}@anchor{library/codecs standalone-codec-functions}@anchor{2a97}
@subsubsection Standalone Codec Functions


The following functions provide encoding and decoding functionality similar to codecs,
but are not available as named codecs through @ref{12b2,,codecs.encode()} or @ref{12b3,,codecs.decode()}.
They are used internally (for example, by @ref{ab,,pickle}) and behave similarly to the
@code{string_escape} codec that was removed in Python 3.

@geindex codecs.escape_encode() (στη μονάδα codecs)
@anchor{library/codecs codecs codecs escape_encode}@anchor{2a98}
@deffn {Συνάρτηση} codecs.escape_encode (input, errors=None)

Encode `input' using escape sequences. Similar to how @ref{45b,,repr()} on bytes
produces escaped byte values.

`input' must be a @ref{1c7,,bytes} object.

Returns a tuple @code{(output, length)} where `output' is a @ref{1c7,,bytes}
object and `length' is the number of bytes consumed.
@end deffn

@geindex codecs.escape_decode() (στη μονάδα codecs)
@anchor{library/codecs codecs codecs escape_decode}@anchor{2a99}
@deffn {Συνάρτηση} codecs.escape_decode (input, errors=None)

Decode `input' from escape sequences back to the original bytes.

`input' must be a @ref{436,,bytes-like object}.

Returns a tuple @code{(output, length)} where `output' is a @ref{1c7,,bytes}
object and `length' is the number of bytes consumed.
@end deffn

@node Text Transforms,,Standalone Codec Functions,Python Specific Encodings
@anchor{library/codecs id7}@anchor{2a9a}@anchor{library/codecs text-transforms}@anchor{12b5}
@subsubsection Text Transforms


The following codec provides a text transform: a @ref{1df,,str} to @code{str}
mapping. It is not supported by @ref{ca7,,str.encode()} (which only produces
@ref{1c7,,bytes} output).


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Codec

@tab

Aliases

@tab

Meaning

@item

rot_13

@tab

rot13

@tab

Return the Caesar-cypher
encryption of the
operand.

@end multitable



Added in version 3.2: Restoration of the @code{rot_13} text transform.



Άλλαξε στην έκδοση 3.4: Restoration of the @code{rot13} alias.


@node encodings — Encodings package,encodings idna — Internationalized Domain Names in Applications,Python Specific Encodings,codecs — Codec registry and base classes
@anchor{library/codecs encodings-encodings-package}@anchor{2a9b}@anchor{library/codecs module-encodings}@anchor{54}
@subsubsection @code{encodings} — Encodings package


@geindex module; encodings

This module implements the following functions:

@geindex normalize_encoding() (στη μονάδα encodings)
@anchor{library/codecs encodings normalize_encoding}@anchor{313}
@deffn {Συνάρτηση} encodings.normalize_encoding (encoding)

Normalize encoding name `encoding'.

Normalization works as follows: all non-alphanumeric characters except the
dot used for Python package names are collapsed and replaced with a single
underscore, leading and trailing underscores are removed.
For example, @code{'  -;#'} becomes @code{'_'}.

Note that `encoding' should be ASCII only.
@end deffn

@cartouche
@quotation Σημείωση 
The following functions should not be used directly, except for testing
purposes; @ref{d2d,,codecs.lookup()} should be used instead.
@end quotation
@end cartouche

@geindex search_function() (στη μονάδα encodings)
@anchor{library/codecs encodings search_function}@anchor{192f}
@deffn {Συνάρτηση} encodings.search_function (encoding)

Search for the codec module corresponding to the given encoding name
`encoding'.

This function first normalizes the `encoding' using
@ref{313,,normalize_encoding()}, then looks for a corresponding alias.
It attempts to import a codec module from the encodings package using either
the alias or the normalized name. If the module is found and defines a valid
@code{getregentry()} function that returns a @ref{1c72,,codecs.CodecInfo} object,
the codec is cached and returned.

If the codec module defines a @code{getaliases()} function any returned aliases
are registered for future use.
@end deffn

@geindex win32_code_page_search_function() (στη μονάδα encodings)
@anchor{library/codecs encodings win32_code_page_search_function}@anchor{2a9c}
@deffn {Συνάρτηση} encodings.win32_code_page_search_function (encoding)

Search for a Windows code page encoding `encoding' of the form @code{cpXXXX}.

If the code page is valid and supported, return a @ref{1c72,,codecs.CodecInfo}
object for it.

@ref{232d,,Διαθεσιμότητα}: Windows.


Added in version 3.14.

@end deffn

This module implements the following exception:

@geindex CodecRegistryError
@anchor{library/codecs encodings CodecRegistryError}@anchor{2a9d}
@deffn {Εξαίρεση} encodings.CodecRegistryError

Raised when a codec is invalid or incompatible.
@end deffn

@node encodings idna — Internationalized Domain Names in Applications,encodings mbcs — Windows ANSI codepage,encodings — Encodings package,codecs — Codec registry and base classes
@anchor{library/codecs encodings-idna-internationalized-domain-names-in-applications}@anchor{2a9e}@anchor{library/codecs module-encodings idna}@anchor{55}
@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{dd,,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{d4,,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{72,,http.client} and @ref{61,,ftplib}, accept Unicode host
names (@code{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 @code{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() (στη μονάδα encodings.idna)
@anchor{library/codecs encodings idna nameprep}@anchor{2a9f}
@deffn {Συνάρτηση} 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() (στη μονάδα encodings.idna)
@anchor{library/codecs encodings idna ToASCII}@anchor{2aa0}
@deffn {Συνάρτηση} 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() (στη μονάδα encodings.idna)
@anchor{library/codecs encodings idna ToUnicode}@anchor{2aa1}
@deffn {Συνάρτηση} 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{2aa2}@anchor{library/codecs module-encodings mbcs}@anchor{56}
@subsubsection @code{encodings.mbcs} — Windows ANSI codepage


@geindex module; encodings.mbcs

This module implements the ANSI codepage (CP_ACP).

@ref{232d,,Διαθεσιμότητα}: Windows.


Άλλαξε στην έκδοση 3.2: Before 3.2, the `errors' argument was ignored; @code{'replace'} was always used
to encode, and @code{'ignore'} to decode.



Άλλαξε στην έκδοση 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{2aa3}@anchor{library/codecs module-encodings utf_8_sig}@anchor{57}
@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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Data Types,Αριθμητικά και Μαθηματικά Modules,Υπηρεσίες Δυαδικών Δεδομένων,The Python Standard Library
@anchor{library/datatypes doc}@anchor{2aa4}@anchor{library/datatypes data-types}@anchor{2aa5}@anchor{library/datatypes datatypes}@anchor{2aa6}@anchor{library/datatypes translation-repo}@anchor{2aa7}
@section Data Types


The modules described in this chapter provide a variety of specialized data
types such as dates and times, fixed-type arrays, heap queues, double-ended
queues, and enumerations.

Python also provides some built-in data types, in particular,
@ref{188,,dict}, @ref{4d9,,list}, @ref{42b,,set} and @ref{9d4,,frozenset}, and
@ref{1ce,,tuple}.  The @ref{1df,,str} class is used to hold
Unicode strings, and the @ref{1c7,,bytes} and @ref{1c6,,bytearray} classes are used
to hold binary data.

The following modules are documented in this chapter:

@menu
* datetime — Basic date and time types:: 
* zoneinfo — IANA time zone support:: 
* calendar — General calendar-related functions:: 
* collections — Container datatypes:: 
* collections.abc — Αφηρημένες Βασικές Κλάσεις για Containers: collections abc — Αφηρημένες Βασικές Κλάσεις για Containers. 
* heapq — Heap queue algorithm:: 
* bisect — Array bisection algorithm:: 
* array — Efficient arrays of numeric values:: 
* weakref — Weak references:: 
* types — Δημιουργία δυναμικών τύπων και ονόματα για ενσωματωμένους τύπους:: 
* copy — Shallow and deep copy operations:: 
* pprint — Data pretty printer:: 
* reprlib — Alternate repr() implementation: reprlib — Alternate repr implementation. 
* enum — Support for enumerations:: 
* graphlib — Functionality to operate with graph-like structures:: 

@end menu

@node datetime — Basic date and time types,zoneinfo — IANA time zone support,,Data Types
@anchor{library/datetime doc}@anchor{2aa8}@anchor{library/datetime datetime-basic-date-and-time-types}@anchor{2aa9}@anchor{library/datetime module-datetime}@anchor{33}
@subsection @code{datetime} — Basic date and time types


@geindex module; datetime

`Source code:' Lib/datetime.py@footnote{https://github.com/python/cpython/tree/main/Lib/datetime.py}


__________________________________________________________________


The @code{datetime} module supplies classes for manipulating dates and times.

While date and time arithmetic is supported, the focus of the implementation is
on efficient attribute extraction for output formatting and manipulation.

@cartouche
@quotation Πρακτική συμβουλή 
Skip to @ref{2aaa,,the format codes}.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{15,,calendar}

General calendar related functions.

@item Module @ref{f7,,time}

Time access and conversions.

@item Module @ref{13d,,zoneinfo}

Concrete time zones representing the IANA time zone database.

@item Package dateutil@footnote{https://dateutil.readthedocs.io/en/stable/}

Third-party library with expanded time zone and parsing support.

@item Package DateType@footnote{https://pypi.org/project/DateType/}

Third-party library that introduces distinct static types to for example,
allow @ref{775,,static type checkers}
to differentiate between naive and aware datetimes.
@end table


@menu
* Aware and naive objects:: 
* Constants:: 
* Available types:: 
* timedelta objects:: 
* date objects:: 
* datetime objects:: 
* time objects:: 
* tzinfo objects:: 
* timezone objects:: 
* strftime() and strptime() behavior: strftime and strptime behavior. 

@end menu

@node Aware and naive objects,Constants,,datetime — Basic date and time types
@anchor{library/datetime aware-and-naive-objects}@anchor{2aab}@anchor{library/datetime datetime-naive-aware}@anchor{2aac}
@subsubsection Aware and naive objects


Date and time objects may be categorized as «aware» or «naive» depending on
whether or not they include time zone information.

With sufficient knowledge of applicable algorithmic and political time
adjustments, such as time zone and daylight saving time information,
an `aware' object can locate itself relative to other aware objects.
An aware object represents a specific moment in time that is not open to
interpretation. @footnote{
If, that is, we ignore the effects of relativity.
}

A `naive' object does not contain enough information to unambiguously locate
itself relative to other date/time objects. Whether a naive object represents
Coordinated Universal Time (UTC), local time, or time in some other time zone is
purely up to the program, just like it is up to the program whether a
particular number represents metres, miles, or mass. Naive objects are easy to
understand and to work with, at the cost of ignoring some aspects of reality.

For applications requiring aware objects, @ref{6e7,,datetime} and @ref{48e,,time}
objects have an optional time zone information attribute, @code{tzinfo}, that
can be set to an instance of a subclass of the abstract @code{tzinfo} class.
These @ref{9d8,,tzinfo} objects capture information about the offset from UTC
time, the time zone name, and whether daylight saving time is in effect.

Only one concrete @ref{9d8,,tzinfo} class, the @ref{146c,,timezone} class, is
supplied by the @code{datetime} module. The @code{timezone} class can
represent simple time zones with fixed offsets from UTC, such as UTC itself or
North American EST and EDT time zones. Supporting time zones at deeper levels of
detail is up to the application. The rules for time adjustment across the
world are more political than rational, change frequently, and there is no
standard suitable for every application aside from UTC.

@node Constants,Available types,Aware and naive objects,datetime — Basic date and time types
@anchor{library/datetime constants}@anchor{2aad}
@subsubsection Constants


The @code{datetime} module exports the following constants:

@geindex MINYEAR (στη μονάδα datetime)
@anchor{library/datetime datetime MINYEAR}@anchor{2aae}
@deffn {Δεδομένα} datetime.MINYEAR

The smallest year number allowed in a @ref{48d,,date} or @ref{6e7,,datetime} object.
@ref{2aae,,MINYEAR} is 1.
@end deffn

@geindex MAXYEAR (στη μονάδα datetime)
@anchor{library/datetime datetime MAXYEAR}@anchor{2aaf}
@deffn {Δεδομένα} datetime.MAXYEAR

The largest year number allowed in a @ref{48d,,date} or @ref{6e7,,datetime} object.
@ref{2aaf,,MAXYEAR} is 9999.
@end deffn

@geindex UTC (στη μονάδα datetime)
@anchor{library/datetime datetime UTC}@anchor{8fc}
@deffn {Δεδομένα} datetime.UTC

Alias for the UTC time zone singleton @ref{a07,,datetime.timezone.utc}.


Added in version 3.11.

@end deffn

@node Available types,timedelta objects,Constants,datetime — Basic date and time types
@anchor{library/datetime available-types}@anchor{2ab0}
@subsubsection Available types



@deffn {Κλάση} datetime.date

An idealized naive date, assuming the current Gregorian calendar always was, and
always will be, in effect. Attributes: @ref{2ab1,,year}, @ref{2ab2,,month}, and
@ref{2ab3,,day}.
@end deffn


@deffn {Κλάση} datetime.time

An idealized time, independent of any particular day, assuming that every day
has exactly 24*60*60 seconds.  (There is no notion of «leap seconds» here.)
Attributes: @ref{2ab4,,hour}, @ref{2ab5,,minute}, @ref{2ab6,,second}, @ref{2ab7,,microsecond},
and @ref{2ab8,,tzinfo}.
@end deffn


@deffn {Κλάση} datetime.datetime

A combination of a date and a time. Attributes: @ref{2ab9,,year}, @ref{2aba,,month},
@ref{2abb,,day}, @ref{2abc,,hour}, @ref{2abd,,minute}, @ref{2abe,,second}, @ref{2abf,,microsecond},
and @ref{2ac0,,tzinfo}.
@end deffn


@deffn {Κλάση} datetime.timedelta

A duration expressing the difference between two @ref{6e7,,datetime}
or @ref{48d,,date} instances to microsecond resolution.
@end deffn


@deffn {Κλάση} datetime.tzinfo

An abstract base class for time zone information objects. These are used by the
@ref{6e7,,datetime} and @ref{48e,,time} classes to provide a customizable notion of
time adjustment (for example, to account for time zone and/or daylight saving
time).
@end deffn


@deffn {Κλάση} datetime.timezone

A class that implements the @ref{9d8,,tzinfo} abstract base class as a
fixed offset from the UTC.


Added in version 3.2.

@end deffn

Objects of these types are immutable.

Subclass relationships:


@float Figure

@image{python-figures/datetime-inheritance,,,timedelta@comma{} tzinfo@comma{} time@comma{} and date inherit from object; timezone inherits from tzinfo; and datetime inherits from date.,svg}

@end float


@menu
* Common properties:: 
* Determining if an object is aware or naive:: 

@end menu

@node Common properties,Determining if an object is aware or naive,,Available types
@anchor{library/datetime common-properties}@anchor{2ac1}
@subsubsection Common properties


The @ref{48d,,date}, @ref{6e7,,datetime}, @ref{48e,,time}, and @ref{146c,,timezone} types
share these common features:


@itemize -

@item 
Objects of these types are immutable.

@item 
Objects of these types are @ref{183,,hashable}, meaning that they can be used as
dictionary keys.

@item 
Objects of these types support efficient pickling via the @ref{ab,,pickle} module.
@end itemize

@node Determining if an object is aware or naive,,Common properties,Available types
@anchor{library/datetime determining-if-an-object-is-aware-or-naive}@anchor{2ac2}
@subsubsection Determining if an object is aware or naive


Objects of the @ref{48d,,date} type are always naive.

An object of type @ref{48e,,time} or @ref{6e7,,datetime} may be aware or naive.

A @ref{6e7,,datetime} object @code{d} is aware if both of the following hold:


@enumerate 

@item 
@code{d.tzinfo} is not @code{None}

@item 
@code{d.tzinfo.utcoffset(d)} does not return @code{None}
@end enumerate

Otherwise, @code{d} is naive.

A @ref{48e,,time} object @code{t} is aware if both of the following hold:


@enumerate 

@item 
@code{t.tzinfo} is not @code{None}

@item 
@code{t.tzinfo.utcoffset(None)} does not return @code{None}.
@end enumerate

Otherwise, @code{t} is naive.

The distinction between aware and naive doesn’t apply to @ref{d94,,timedelta}
objects.

@node timedelta objects,date objects,Available types,datetime — Basic date and time types
@anchor{library/datetime datetime-timedelta}@anchor{2ac3}@anchor{library/datetime timedelta-objects}@anchor{2ac4}
@subsubsection @code{timedelta} objects


A @ref{d94,,timedelta} object represents a duration, the difference between two
@ref{6e7,,datetime} or @ref{48d,,date} instances.

@geindex timedelta (κλάση σε datetime)
@anchor{library/datetime datetime timedelta}@anchor{d94}
@deffn {Κλάση} datetime.timedelta (days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

All arguments are optional and default to 0. Arguments may be integers
or floats, and may be positive or negative.

Only `days', `seconds' and `microseconds' are stored internally.
Arguments are converted to those units:


@itemize *

@item 
A millisecond is converted to 1000 microseconds.

@item 
A minute is converted to 60 seconds.

@item 
An hour is converted to 3600 seconds.

@item 
A week is converted to 7 days.
@end itemize

and days, seconds and microseconds are then normalized so that the
representation is unique, with


@itemize *

@item 
@code{0 <= microseconds < 1000000}

@item 
@code{0 <= seconds < 3600*24} (the number of seconds in one day)

@item 
@code{-999999999 <= days <= 999999999}
@end itemize

The following example illustrates how any arguments besides
`days', `seconds' and `microseconds' are «merged» and normalized into those
three resulting attributes:

@example
>>> import datetime as dt
>>> delta = dt.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

@cartouche
@quotation Πρακτική συμβουλή 
@code{import datetime as dt} instead of @code{import datetime} or
@code{from datetime import datetime} to avoid confusion between the module
and the class. See How I Import Python’s datetime Module@footnote{https://adamj.eu/tech/2019/09/12/how-i-import-pythons-datetime-module/}.
@end quotation
@end cartouche

If any argument is a float and there are fractional microseconds,
the fractional microseconds left over from all arguments are
combined and their sum is rounded to the nearest microsecond using
round-half-to-even tiebreaker. If no argument is a float, the
conversion and normalization processes are exact (no information is
lost).

If the normalized value of days lies outside the indicated range,
@ref{c57,,OverflowError} is raised.

Note that normalization of negative values may be surprising at first. For
example:

@example
>>> import datetime as dt
>>> d = dt.timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)
@end example

Since the string representation of @code{timedelta} objects can be confusing,
use the following recipe to produce a more readable format:

@example
>>> def pretty_timedelta(td):
...     if td.days >= 0:
...         return str(td)
...     return f'-(@{-td!s@})'
...
>>> d = timedelta(hours=-1)
>>> str(d)  # not human-friendly
'-1 day, 23:00:00'
>>> pretty_timedelta(d)
'-(1:00:00)'
@end example
@end deffn

Class attributes:

@geindex min (ιδιότητα της datetime.timedelta)
@anchor{library/datetime datetime timedelta min}@anchor{2ac5}
@deffn {Ιδιότητα} timedelta.min

The most negative @ref{d94,,timedelta} object, @code{timedelta(-999999999)}.
@end deffn

@geindex max (ιδιότητα της datetime.timedelta)
@anchor{library/datetime datetime timedelta max}@anchor{2ac6}
@deffn {Ιδιότητα} timedelta.max

The most positive @ref{d94,,timedelta} object, @code{timedelta(days=999999999,
hours=23, minutes=59, seconds=59, microseconds=999999)}.
@end deffn

@geindex resolution (ιδιότητα της datetime.timedelta)
@anchor{library/datetime datetime timedelta resolution}@anchor{2ac7}
@deffn {Ιδιότητα} timedelta.resolution

The smallest possible difference between non-equal @ref{d94,,timedelta} objects,
@code{timedelta(microseconds=1)}.
@end deffn

Note that, because of normalization, @code{timedelta.max} is greater than @code{-timedelta.min}.
@code{-timedelta.max} is not representable as a @ref{d94,,timedelta} object.

Instance attributes (read-only):

@geindex days (ιδιότητα της datetime.timedelta)
@anchor{library/datetime datetime timedelta days}@anchor{2ac8}
@deffn {Ιδιότητα} timedelta.days

Between -999,999,999 and 999,999,999 inclusive.
@end deffn

@geindex seconds (ιδιότητα της datetime.timedelta)
@anchor{library/datetime datetime timedelta seconds}@anchor{2ac9}
@deffn {Ιδιότητα} timedelta.seconds

Between 0 and 86,399 inclusive.

@cartouche
@quotation Προσοχή 
It is a somewhat common bug for code to unintentionally use this attribute
when it is actually intended to get a @ref{16aa,,total_seconds()}
value instead:

@example
>>> import datetime as dt
>>> duration = dt.timedelta(seconds=11235813)
>>> duration.days, duration.seconds
(130, 3813)
>>> duration.total_seconds()
11235813.0
@end example
@end quotation
@end cartouche
@end deffn

@geindex microseconds (ιδιότητα της datetime.timedelta)
@anchor{library/datetime datetime timedelta microseconds}@anchor{2aca}
@deffn {Ιδιότητα} timedelta.microseconds

Between 0 and 999,999 inclusive.
@end deffn

Supported operations:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Operation

@tab

Result

@item

@code{t1 = t2 + t3}

@tab

Sum of @code{t2} and @code{t3}.
Afterwards @code{t1 - t2 == t3} and
@code{t1 - t3 == t2} are true. (1)

@item

@code{t1 = t2 - t3}

@tab

Difference of @code{t2}  and @code{t3}. Afterwards
@code{t1 == t2 - t3} and @code{t2 == t1 + t3} are
true. (1)(6)

@item

@code{t1 = t2 * i or t1 = i * t2}

@tab

Delta multiplied by an integer.
Afterwards @code{t1 // i == t2} is true,
provided @code{i != 0}.

@item

@tab

In general, @code{t1  * i == t1 * (i-1) + t1}
is true. (1)

@item

@code{t1 = t2 * f or t1 = f * t2}

@tab

Delta multiplied by a float. The result is
rounded to the nearest multiple of
timedelta.resolution using round-half-to-even.

@item

@code{f = t2 / t3}

@tab

Division (3) of overall duration @code{t2} by
interval unit @code{t3}. Returns a @ref{327,,float}
object.

@item

@code{t1 = t2 / f or t1 = t2 / i}

@tab

Delta divided by a float or an int. The result
is rounded to the nearest multiple of
timedelta.resolution using round-half-to-even.

@item

@code{t1 = t2 // i} or
@code{t1 = t2 // t3}

@tab

The floor is computed and the remainder (if
any) is thrown away. In the second case, an
integer is returned. (3)

@item

@code{t1 = t2 % t3}

@tab

The remainder is computed as a
@ref{d94,,timedelta} object. (3)

@item

@code{q, r = divmod(t1, t2)}

@tab

Computes the quotient and the remainder:
@code{q = t1 // t2} (3) and @code{r = t1 % t2}.
@code{q} is an integer and @code{r} is a
@ref{d94,,timedelta} object.

@item

@code{+t1}

@tab

Returns a @ref{d94,,timedelta} object with the
same value. (2)

@item

@code{-t1}

@tab

Equivalent to @code{timedelta(-t1.days,
-t1.seconds, -t1.microseconds)},
and to @code{t1 * -1}. (1)(4)

@item

@code{abs(t)}

@tab

Equivalent to @code{+t} when @code{t.days >= 0},
and to @code{-t} when @code{t.days < 0}. (2)

@item

@code{str(t)}

@tab

Returns a string in the form
@code{[D day[s], ][H]H:MM:SS[.UUUUUU]}, where D
is negative for negative @code{t}. (5)

@item

@code{repr(t)}

@tab

Returns a string representation of the
@ref{d94,,timedelta} object as a constructor
call with canonical attribute values.

@end multitable


Notes:


@enumerate 

@item 
This is exact but may overflow.

@item 
This is exact and cannot overflow.

@item 
Division by zero raises @ref{d11,,ZeroDivisionError}.

@item 
@code{-timedelta.max} is not representable as a @ref{d94,,timedelta} object.

@item 
String representations of @ref{d94,,timedelta} objects are normalized
similarly to their internal representation. This leads to somewhat
unusual results for negative timedeltas. For example:

@example
>>> timedelta(hours=-5)
datetime.timedelta(days=-1, seconds=68400)
>>> print(_)
-1 day, 19:00:00
@end example

@item 
The expression @code{t2 - t3} will always be equal to the expression @code{t2 + (-t3)} except
when t3 is equal to @code{timedelta.max}; in that case the former will produce a result
while the latter will overflow.
@end enumerate

In addition to the operations listed above, @ref{d94,,timedelta} objects support
certain additions and subtractions with @ref{48d,,date} and @ref{6e7,,datetime}
objects (see below).


Άλλαξε στην έκδοση 3.2: Floor division and true division of a @ref{d94,,timedelta} object by another
@code{timedelta} object are now supported, as are remainder operations and
the @ref{d6a,,divmod()} function. True division and multiplication of a
@code{timedelta} object by a @ref{327,,float} object are now supported.


@ref{d94,,timedelta} objects support equality and order comparisons.

In Boolean contexts, a @ref{d94,,timedelta} object is
considered to be true if and only if it isn’t equal to @code{timedelta(0)}.

Instance methods:

@geindex total_seconds() (μέθοδος της datetime.timedelta)
@anchor{library/datetime datetime timedelta total_seconds}@anchor{16aa}
@deffn {Μέθοδος} timedelta.total_seconds ()

Return the total number of seconds contained in the duration. Equivalent to
@code{td / timedelta(seconds=1)}. For interval units other than seconds, use the
division form directly (for example, @code{td / timedelta(microseconds=1)}).

Note that for very large time intervals (greater than 270 years on
most platforms) this method will lose microsecond accuracy.


Added in version 3.2.

@end deffn

@menu
* Examples of usage; timedelta: Examples of usage timedelta. 

@end menu

@node Examples of usage timedelta,,,timedelta objects
@anchor{library/datetime examples-of-usage-timedelta}@anchor{2acb}
@subsubsection Examples of usage: @code{timedelta}


An additional example of normalization:

@example
>>> # Components of another_year add up to exactly 365 days
>>> import datetime as dt
>>> year = dt.timedelta(days=365)
>>> another_year = dt.timedelta(weeks=40, days=84, hours=23,
...                             minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0
@end example

Examples of @ref{d94,,timedelta} arithmetic:

@example
>>> import datetime as dt
>>> year = dt.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 date objects,datetime objects,timedelta objects,datetime — Basic date and time types
@anchor{library/datetime date-objects}@anchor{2acc}@anchor{library/datetime datetime-date}@anchor{2acd}
@subsubsection @code{date} objects


A @ref{48d,,date} object represents a date (year, month and day) in an idealized
calendar, the current Gregorian calendar indefinitely extended in both
directions.

January 1 of year 1 is called day number 1, January 2 of year 1 is
called day number 2, and so on. @footnote{
This matches the definition of the «proleptic Gregorian» calendar in
Dershowitz and Reingold’s book `Calendrical Calculations',
where it’s the base calendar for all computations. See the book for
algorithms for converting between proleptic Gregorian ordinals and
many other calendar systems.
}

@geindex date (κλάση σε datetime)
@anchor{library/datetime datetime date}@anchor{48d}
@deffn {Κλάση} datetime.date (year, month, day)

All arguments are required. Arguments must be integers, in the following
ranges:


@itemize *

@item 
@code{MINYEAR <= year <= MAXYEAR}

@item 
@code{1 <= month <= 12}

@item 
@code{1 <= day <= number of days in the given month and year}
@end itemize

If an argument outside those ranges is given, @ref{277,,ValueError} is raised.
@end deffn

Other constructors, all class methods:

@geindex today() (μέθοδος κλάσης της datetime.date)
@anchor{library/datetime datetime date today}@anchor{186c}
@deffn {Μέθοδος} classmethod date.today ()

Return the current local date.

This is equivalent to @code{date.fromtimestamp(time.time())}.
@end deffn

@geindex fromtimestamp() (μέθοδος κλάσης της datetime.date)
@anchor{library/datetime datetime date fromtimestamp}@anchor{f92}
@deffn {Μέθοδος} classmethod date.fromtimestamp (timestamp)

Return the local date corresponding to the POSIX `timestamp', such as is
returned by @ref{75e,,time.time()}.

This may raise @ref{c57,,OverflowError}, if the timestamp is out
of the range of values supported by the platform C @code{localtime()}
function, and @ref{53c,,OSError} on @code{localtime()} failure.
It’s common for this to be restricted to years from 1970 through 2038. Note
that on non-POSIX systems that include leap seconds in their notion of a
timestamp, leap seconds are ignored by @code{fromtimestamp()}.


Άλλαξε στην έκδοση 3.3: Raise @ref{c57,,OverflowError} instead of @ref{277,,ValueError} if the timestamp
is out of the range of values supported by the platform C
@code{localtime()} function. Raise @ref{53c,,OSError} instead of
@code{ValueError} on @code{localtime()} failure.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timestamp', not only integer or float.

@end deffn

@geindex fromordinal() (μέθοδος κλάσης της datetime.date)
@anchor{library/datetime datetime date fromordinal}@anchor{f91}
@deffn {Μέθοδος} classmethod date.fromordinal (ordinal)

Return the date corresponding to the proleptic Gregorian `ordinal', where
January 1 of year 1 has ordinal 1.

@ref{277,,ValueError} is raised unless @code{1 <= ordinal <=
date.max.toordinal()}. For any date @code{d},
@code{date.fromordinal(d.toordinal()) == d}.
@end deffn

@geindex fromisoformat() (μέθοδος κλάσης της datetime.date)
@anchor{library/datetime datetime date fromisoformat}@anchor{a08}
@deffn {Μέθοδος} classmethod date.fromisoformat (date_string)

Return a @ref{48d,,date} corresponding to a `date_string' given in any valid
ISO 8601 format, with the following exceptions:


@enumerate 

@item 
Reduced precision dates are not currently supported (@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

Examples:

@example
>>> import datetime as dt
>>> dt.date.fromisoformat('2019-12-04')
datetime.date(2019, 12, 4)
>>> dt.date.fromisoformat('20191204')
datetime.date(2019, 12, 4)
>>> dt.date.fromisoformat('2021-W01-1')
datetime.date(2021, 1, 4)
@end example


Added in version 3.7.



Άλλαξε στην έκδοση 3.11: Previously, this method only supported the format @code{YYYY-MM-DD}.

@end deffn

@geindex fromisocalendar() (μέθοδος κλάσης της datetime.date)
@anchor{library/datetime datetime date fromisocalendar}@anchor{db0}
@deffn {Μέθοδος} classmethod date.fromisocalendar (year, week, day)

Return a @ref{48d,,date} corresponding to the ISO calendar date specified by
`year', `week' and `day'. This is the inverse of the function @ref{cc5,,date.isocalendar()}.


Added in version 3.8.

@end deffn

@geindex strptime() (μέθοδος κλάσης της datetime.date)
@anchor{library/datetime datetime date strptime}@anchor{48c}
@deffn {Μέθοδος} classmethod date.strptime (date_string, format)

Return a @ref{48d,,date} corresponding to `date_string', parsed according to
`format'. This is equivalent to:

@example
date(*(time.strptime(date_string, format)[0:3]))
@end example

@ref{277,,ValueError} is raised if the date_string and format
can’t be parsed by @ref{17cf,,time.strptime()} or if it returns a value which isn’t a
time tuple.  See also @ref{1d52,,strftime() and strptime() behavior} and
@ref{a08,,date.fromisoformat()}.

@cartouche
@quotation Σημείωση 
If `format' specifies a day of month (@code{%d}) without a year,
@ref{277,,ValueError} is raised.  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.
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
>>> import datetime as dt
>>> date_string = "02/29"
>>> when = dt.date.strptime(f"@{date_string@};1984", "%m/%d;%Y")  # Avoids leap year bug.
>>> when.strftime("%B %d")
'February 29'
@end example
@end quotation
@end cartouche


Added in version 3.14.

@end deffn

Class attributes:

@geindex min (ιδιότητα της datetime.date)
@anchor{library/datetime datetime date min}@anchor{2ace}
@deffn {Ιδιότητα} date.min

The earliest representable date, @code{date(MINYEAR, 1, 1)}.
@end deffn

@geindex max (ιδιότητα της datetime.date)
@anchor{library/datetime datetime date max}@anchor{2acf}
@deffn {Ιδιότητα} date.max

The latest representable date, @code{date(MAXYEAR, 12, 31)}.
@end deffn

@geindex resolution (ιδιότητα της datetime.date)
@anchor{library/datetime datetime date resolution}@anchor{2ad0}
@deffn {Ιδιότητα} date.resolution

The smallest possible difference between non-equal date objects,
@code{timedelta(days=1)}.
@end deffn

Instance attributes (read-only):

@geindex year (ιδιότητα της datetime.date)
@anchor{library/datetime datetime date year}@anchor{2ab1}
@deffn {Ιδιότητα} date.year

Between @ref{2aae,,MINYEAR} and @ref{2aaf,,MAXYEAR} inclusive.
@end deffn

@geindex month (ιδιότητα της datetime.date)
@anchor{library/datetime datetime date month}@anchor{2ab2}
@deffn {Ιδιότητα} date.month

Between 1 and 12 inclusive.
@end deffn

@geindex day (ιδιότητα της datetime.date)
@anchor{library/datetime datetime date day}@anchor{2ab3}
@deffn {Ιδιότητα} date.day

Between 1 and the number of days in the given month of the given year.
@end deffn

Supported operations:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Operation

@tab

Result

@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 
`date2' is moved forward in time if @code{timedelta.days > 0}, or backward if
@code{timedelta.days < 0}. Afterward @code{date2 - date1 == timedelta.days}.
@code{timedelta.seconds} and @code{timedelta.microseconds} are ignored.
@ref{c57,,OverflowError} is raised if @code{date2.year} would be smaller than
@ref{2aae,,MINYEAR} or larger than @ref{2aaf,,MAXYEAR}.

@item 
@code{timedelta.seconds} and @code{timedelta.microseconds} are ignored.

@item 
This is exact, and cannot overflow. @code{timedelta.seconds} and
@code{timedelta.microseconds} are 0, and @code{date2 + timedelta == date1} after.

@item 
@ref{48d,,date} objects are equal if they represent the same date.

@code{date} objects that are not also @ref{6e7,,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 @ref{48d,,date} object that is not also a
@ref{6e7,,datetime} instance and a @code{datetime} object raises
@ref{291,,TypeError}.
@end enumerate


Άλλαξε στην έκδοση 3.13: Comparison between @ref{6e7,,datetime} object and an instance of
the @ref{48d,,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.


In Boolean contexts, all @ref{48d,,date} objects are considered to be true.

Instance methods:

@geindex replace() (μέθοδος της datetime.date)
@anchor{library/datetime datetime date replace}@anchor{1c01}
@deffn {Μέθοδος} date.replace (year=self.year, month=self.month, day=self.day)

Return a new @ref{48d,,date} object with the same values, but with specified
parameters updated.

Example:

@example
>>> import datetime as dt
>>> d = dt.date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)
@end example

The generic function @ref{45a,,copy.replace()} also supports @ref{48d,,date}
objects.
@end deffn

@geindex timetuple() (μέθοδος της datetime.date)
@anchor{library/datetime datetime date timetuple}@anchor{2ad1}
@deffn {Μέθοδος} date.timetuple ()

Return a @ref{10a7,,time.struct_time} such as returned by @ref{189b,,time.localtime()}.

The hours, minutes and seconds are 0, and the DST flag is -1.

@code{d.timetuple()} is equivalent to:

@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() (μέθοδος της datetime.date)
@anchor{library/datetime datetime date toordinal}@anchor{2ad2}
@deffn {Μέθοδος} date.toordinal ()

Return the proleptic Gregorian ordinal of the date, where January 1 of year 1
has ordinal 1. For any @ref{48d,,date} object @code{d},
@code{date.fromordinal(d.toordinal()) == d}.
@end deffn

@geindex weekday() (μέθοδος της datetime.date)
@anchor{library/datetime datetime date weekday}@anchor{2ad3}
@deffn {Μέθοδος} date.weekday ()

Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
For example, @code{date(2002, 12, 4).weekday() == 2}, a Wednesday. See also
@ref{2ad4,,isoweekday()}.
@end deffn

@geindex isoweekday() (μέθοδος της datetime.date)
@anchor{library/datetime datetime date isoweekday}@anchor{2ad4}
@deffn {Μέθοδος} date.isoweekday ()

Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
For example, @code{date(2002, 12, 4).isoweekday() == 3}, a Wednesday. See also
@ref{2ad3,,weekday()}, @ref{cc5,,isocalendar()}.
@end deffn

@geindex isocalendar() (μέθοδος της datetime.date)
@anchor{library/datetime datetime date isocalendar}@anchor{cc5}
@deffn {Μέθοδος} date.isocalendar ()

Return a @ref{a3d,,named tuple} object with three components: @code{year},
@code{week} and @code{weekday}.

The ISO calendar is a widely used variant of the Gregorian calendar. @footnote{
See R. H. van Gent’s @uref{https://web.archive.org/web/20220531051136/https://webspace.science.uu.nl/~gent0113/calendar/isocalendar.htm,guide to the mathematics of the ISO 8601 calendar}
for a good explanation.
}

The ISO year consists of 52 or 53 full weeks, and where a week starts on a
Monday and ends on a Sunday. The first week of an ISO year is the first
(Gregorian) calendar week of a year containing a Thursday. This is called week
number 1, and the ISO year of that Thursday is the same as its Gregorian year.

For example, 2004 begins on a Thursday, so the first week of ISO year 2004
begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004:

@example
>>> import datetime as dt
>>> dt.date(2003, 12, 29).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=1)
>>> dt.date(2004, 1, 4).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=7)
@end example


Άλλαξε στην έκδοση 3.9: Result changed from a tuple to a @ref{a3d,,named tuple}.

@end deffn

@geindex isoformat() (μέθοδος της datetime.date)
@anchor{library/datetime datetime date isoformat}@anchor{2ad5}
@deffn {Μέθοδος} date.isoformat ()

Return a string representing the date in ISO 8601 format, @code{YYYY-MM-DD}:

@example
>>> import datetime as dt
>>> dt.date(2002, 12, 4).isoformat()
'2002-12-04'
@end example
@end deffn

@geindex __str__() (μέθοδος της datetime.date)
@anchor{library/datetime datetime date __str__}@anchor{2ad6}
@deffn {Μέθοδος} date.__str__ ()

For a date @code{d}, @code{str(d)} is equivalent to @code{d.isoformat()}.
@end deffn

@geindex ctime() (μέθοδος της datetime.date)
@anchor{library/datetime datetime date ctime}@anchor{2ad7}
@deffn {Μέθοδος} date.ctime ()

Return a string representing the date:

@example
>>> import datetime as dt
>>> dt.date(2002, 12, 4).ctime()
'Wed Dec  4 00:00:00 2002'
@end example

@code{d.ctime()} is equivalent to:

@example
time.ctime(time.mktime(d.timetuple()))
@end example

on platforms where the native C
@code{ctime()} function (which @ref{2ad8,,time.ctime()} invokes, but which
@code{date.ctime()} does not invoke) conforms to the C standard.
@end deffn

@geindex strftime() (μέθοδος της datetime.date)
@anchor{library/datetime datetime date strftime}@anchor{1052}
@deffn {Μέθοδος} date.strftime (format)

Return a string representing the date, controlled by an explicit format string.
Format codes referring to hours, minutes or seconds will see 0 values.
See also @ref{1d52,,strftime() and strptime() behavior} and @ref{2ad5,,date.isoformat()}.
@end deffn

@geindex __format__() (μέθοδος της datetime.date)
@anchor{library/datetime datetime date __format__}@anchor{2ad9}
@deffn {Μέθοδος} date.__format__ (format)

Same as @ref{1052,,date.strftime()}. This makes it possible to specify a format
string for a @ref{48d,,date} object in @ref{43a,,formatted string literals} and when using @ref{a12,,str.format()}.
See also @ref{1d52,,strftime() and strptime() behavior} and @ref{2ad5,,date.isoformat()}.
@end deffn

@menu
* Examples of usage; date: Examples of usage date. 

@end menu

@node Examples of usage date,,,date objects
@anchor{library/datetime examples-of-usage-date}@anchor{2ada}
@subsubsection Examples of usage: @code{date}


Example of counting days to an event:

@example
>>> import time
>>> import datetime as dt
>>> today = dt.date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == dt.date.fromtimestamp(time.time())
True
>>> my_birthday = dt.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

More examples of working with @ref{48d,,date}:

@example
>>> import datetime as dt
>>> d = dt.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 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 datetime objects,time objects,date objects,datetime — Basic date and time types
@anchor{library/datetime datetime-datetime}@anchor{2adb}@anchor{library/datetime datetime-objects}@anchor{2adc}
@subsubsection @code{datetime} objects


A @ref{6e7,,datetime} object is a single object containing all the information
from a @ref{48d,,date} object and a @ref{48e,,time} object.

Like a @ref{48d,,date} object, @ref{6e7,,datetime} assumes the current Gregorian
calendar extended in both directions; like a @ref{48e,,time} object,
@code{datetime} assumes there are exactly 3600*24 seconds in every day.

Constructor:

@geindex datetime (κλάση σε datetime)
@anchor{library/datetime datetime datetime}@anchor{6e7}
@deffn {Κλάση} datetime.datetime (year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

The `year', `month' and `day' arguments are required. `tzinfo' may be @code{None}, or an
instance of a @ref{9d8,,tzinfo} subclass. The remaining arguments must be integers
in the following ranges:


@itemize *

@item 
@code{MINYEAR <= year <= MAXYEAR},

@item 
@code{1 <= month <= 12},

@item 
@code{1 <= day <= number of days in the given month and year},

@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{277,,ValueError} is raised.


Άλλαξε στην έκδοση 3.6: Added the `fold' parameter.

@end deffn

Other constructors, all class methods:

@geindex today() (μέθοδος κλάσης της datetime.datetime)
@anchor{library/datetime datetime datetime today}@anchor{2add}
@deffn {Μέθοδος} classmethod datetime.today ()

Return the current local date and time, with @ref{2ac0,,tzinfo} @code{None}.

Equivalent to:

@example
datetime.fromtimestamp(time.time())
@end example

See also @ref{8fa,,now()}, @ref{8fb,,fromtimestamp()}.

This method is functionally equivalent to @ref{8fa,,now()}, but without a
@code{tz} parameter.
@end deffn

@geindex now() (μέθοδος κλάσης της datetime.datetime)
@anchor{library/datetime datetime datetime now}@anchor{8fa}
@deffn {Μέθοδος} classmethod datetime.now (tz=None)

Return the current local date and time.

If optional argument `tz' is @code{None}
or not specified, this is like @ref{2add,,today()}, but, if possible, supplies more
precision than can be gotten from going through a @ref{75e,,time.time()} timestamp
(for example, this may be possible on platforms supplying the C
@code{gettimeofday()} function).

If `tz' is not @code{None}, it must be an instance of a @ref{9d8,,tzinfo} subclass,
and the current date and time are converted to `tz'’s time zone.

This function is preferred over @ref{2add,,today()} and @ref{32e,,utcnow()}.

@cartouche
@quotation Σημείωση 
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() (μέθοδος κλάσης της datetime.datetime)
@anchor{library/datetime datetime datetime utcnow}@anchor{32e}
@deffn {Μέθοδος} classmethod datetime.utcnow ()

Return the current UTC date and time, with @ref{2ac0,,tzinfo} @code{None}.

This is like @ref{8fa,,now()}, but returns the current UTC date and time, as a naive
@ref{6e7,,datetime} object. An aware current UTC datetime can be obtained by
calling @code{datetime.now(timezone.utc)}. See also @code{now()}.

@cartouche
@quotation Προειδοποίηση 
Because naive @code{datetime} objects are treated by many @code{datetime} methods
as local times, it is preferred to use aware datetimes to represent times
in UTC. As such, the recommended way to create an object representing the
current time in UTC is by calling @code{datetime.now(timezone.utc)}.
@end quotation
@end cartouche


Αποσύρθηκε στην έκδοση 3.12: Use @ref{8fa,,datetime.now()} with @ref{8fc,,UTC} instead.

@end deffn

@geindex fromtimestamp() (μέθοδος κλάσης της datetime.datetime)
@anchor{library/datetime datetime datetime fromtimestamp}@anchor{8fb}
@deffn {Μέθοδος} classmethod datetime.fromtimestamp (timestamp, tz=None)

Return the local date and time corresponding to the POSIX timestamp, such as is
returned by @ref{75e,,time.time()}. If optional argument `tz' is @code{None} or not
specified, the timestamp is converted to the platform’s local date and time, and
the returned @ref{6e7,,datetime} object is naive.

If `tz' is not @code{None}, it must be an instance of a @ref{9d8,,tzinfo} subclass, and the
timestamp is converted to `tz'’s time zone.

@code{fromtimestamp()} may raise @ref{c57,,OverflowError}, if the timestamp is out of
the range of values supported by the platform C @code{localtime()} or
@code{gmtime()} functions, and @ref{53c,,OSError} on @code{localtime()} or
@code{gmtime()} failure.
It’s common for this to be restricted to years in
1970 through 2038. Note that on non-POSIX systems that include leap seconds in
their notion of a timestamp, leap seconds are ignored by @code{fromtimestamp()},
and then it’s possible to have two timestamps differing by a second that yield
identical @ref{6e7,,datetime} objects. This method is preferred over
@ref{32f,,utcfromtimestamp()}.


Άλλαξε στην έκδοση 3.3: Raise @ref{c57,,OverflowError} instead of @ref{277,,ValueError} if the timestamp
is out of the range of values supported by the platform C
@code{localtime()} or @code{gmtime()} functions. Raise @ref{53c,,OSError}
instead of @code{ValueError} on @code{localtime()} or @code{gmtime()}
failure.



Άλλαξε στην έκδοση 3.6: @code{fromtimestamp()} may return instances with @ref{1015,,fold} set to 1.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timestamp', not only integer or float.

@end deffn

@geindex utcfromtimestamp() (μέθοδος κλάσης της datetime.datetime)
@anchor{library/datetime datetime datetime utcfromtimestamp}@anchor{32f}
@deffn {Μέθοδος} classmethod datetime.utcfromtimestamp (timestamp)

Return the UTC @ref{6e7,,datetime} corresponding to the POSIX timestamp, with
@ref{2ac0,,tzinfo} @code{None}.  (The resulting object is naive.)

This may raise @ref{c57,,OverflowError}, if the timestamp is
out of the range of values supported by the platform C @code{gmtime()} function,
and @ref{53c,,OSError} on @code{gmtime()} failure.
It’s common for this to be restricted to years in 1970 through 2038.

To get an aware @ref{6e7,,datetime} object, call @ref{8fb,,fromtimestamp()}:

@example
datetime.fromtimestamp(timestamp, timezone.utc)
@end example

On the POSIX compliant platforms, it is equivalent to the following
expression:

@example
datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)
@end example

except the latter formula always supports the full years range: between
@ref{2aae,,MINYEAR} and @ref{2aaf,,MAXYEAR} inclusive.

@cartouche
@quotation Προειδοποίηση 
Because naive @code{datetime} objects are treated by many @code{datetime} methods
as local times, it is preferred to use aware datetimes to represent times
in UTC. As such, the recommended way to create an object representing a
specific timestamp in UTC is by calling
@code{datetime.fromtimestamp(timestamp, tz=timezone.utc)}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: Raise @ref{c57,,OverflowError} instead of @ref{277,,ValueError} if the timestamp
is out of the range of values supported by the platform C
@code{gmtime()} function. Raise @ref{53c,,OSError} instead of
@code{ValueError} on @code{gmtime()} failure.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timestamp', not only integer or float.



Αποσύρθηκε στην έκδοση 3.12: Use @ref{8fb,,datetime.fromtimestamp()} with @ref{8fc,,UTC} instead.

@end deffn

@geindex fromordinal() (μέθοδος κλάσης της datetime.datetime)
@anchor{library/datetime datetime datetime fromordinal}@anchor{2ade}
@deffn {Μέθοδος} classmethod datetime.fromordinal (ordinal)

Return the @ref{6e7,,datetime} corresponding to the proleptic Gregorian ordinal,
where January 1 of year 1 has ordinal 1. @ref{277,,ValueError} is raised unless
@code{1 <= ordinal <= datetime.max.toordinal()}. The hour, minute, second and
microsecond of the result are all 0, and @ref{2ac0,,tzinfo} is @code{None}.
@end deffn

@geindex combine() (μέθοδος κλάσης της datetime.datetime)
@anchor{library/datetime datetime datetime combine}@anchor{1053}
@deffn {Μέθοδος} classmethod datetime.combine (date, time, tzinfo=time.tzinfo)

Return a new @ref{6e7,,datetime} object whose date components are equal to the
given @ref{48d,,date} object’s, and whose time components
are equal to the given @ref{48e,,time} object’s. If the `tzinfo'
argument is provided, its value is used to set the @ref{2ac0,,tzinfo} attribute
of the result, otherwise the @ref{2ab8,,tzinfo} attribute of the `time' argument
is used.  If the `date' argument is a @code{datetime} object, its time components
and @code{tzinfo} attributes are ignored.

For any @ref{6e7,,datetime} object @code{d},
@code{d == datetime.combine(d.date(), d.time(), d.tzinfo)}.


Άλλαξε στην έκδοση 3.6: Added the `tzinfo' argument.

@end deffn

@geindex fromisoformat() (μέθοδος κλάσης της datetime.datetime)
@anchor{library/datetime datetime datetime fromisoformat}@anchor{a0a}
@deffn {Μέθοδος} classmethod datetime.fromisoformat (date_string)

Return a @ref{6e7,,datetime} corresponding to a `date_string' in any valid
ISO 8601 format, with the following exceptions:


@enumerate 

@item 
Time zone offsets may have fractional seconds.

@item 
The @code{T} separator may be replaced by any single unicode character.

@item 
Fractional hours and minutes are not supported.

@item 
Reduced precision dates are not currently supported (@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

Examples:

@example
>>> import datetime as dt
>>> dt.datetime.fromisoformat('2011-11-04')
datetime.datetime(2011, 11, 4, 0, 0)
>>> dt.datetime.fromisoformat('20111104')
datetime.datetime(2011, 11, 4, 0, 0)
>>> dt.datetime.fromisoformat('2011-11-04T00:05:23')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> dt.datetime.fromisoformat('2011-11-04T00:05:23Z')
datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)
>>> dt.datetime.fromisoformat('20111104T000523')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> dt.datetime.fromisoformat('2011-W01-2T00:05:23.283')
datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)
>>> dt.datetime.fromisoformat('2011-11-04 00:05:23.283')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)
>>> dt.datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)
>>> dt.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


Added in version 3.7.



Άλλαξε στην έκδοση 3.11: Previously, this method only supported formats that could be emitted by
@ref{2ad5,,date.isoformat()} or @ref{eef,,datetime.isoformat()}.

@end deffn

@geindex fromisocalendar() (μέθοδος κλάσης της datetime.datetime)
@anchor{library/datetime datetime datetime fromisocalendar}@anchor{db1}
@deffn {Μέθοδος} classmethod datetime.fromisocalendar (year, week, day)

Return a @ref{6e7,,datetime} corresponding to the ISO calendar date specified
by `year', `week' and `day'. The non-date components of the datetime are populated
with their normal default values. This is the inverse of the function
@ref{cc6,,datetime.isocalendar()}.


Added in version 3.8.

@end deffn

@geindex strptime() (μέθοδος κλάσης της datetime.datetime)
@anchor{library/datetime datetime datetime strptime}@anchor{2d2}
@deffn {Μέθοδος} classmethod datetime.strptime (date_string, format)

Return a @ref{6e7,,datetime} corresponding to `date_string', parsed according to
`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

@ref{277,,ValueError} is raised if the date_string and format
can’t be parsed by @ref{17cf,,time.strptime()} or if it returns a value which isn’t a
time tuple.  See also @ref{1d52,,strftime() and strptime() behavior} and
@ref{a0a,,datetime.fromisoformat()}.


Άλλαξε στην έκδοση 3.15: If `format' specifies a day of month (@code{%d}) without a year,
@ref{277,,ValueError} is raised.  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.
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
>>> import datetime as dt
>>> date_string = "02/29"
>>> when = dt.datetime.strptime(f"@{date_string@};1984", "%m/%d;%Y")  # Avoids leap year bug.
>>> when.strftime("%B %d")
'February 29'
@end example

@end deffn

Class attributes:

@geindex min (ιδιότητα της datetime.datetime)
@anchor{library/datetime datetime datetime min}@anchor{1d63}
@deffn {Ιδιότητα} datetime.min

The earliest representable @ref{6e7,,datetime}, @code{datetime(MINYEAR, 1, 1,
tzinfo=None)}.
@end deffn

@geindex max (ιδιότητα της datetime.datetime)
@anchor{library/datetime datetime datetime max}@anchor{2adf}
@deffn {Ιδιότητα} datetime.max

The latest representable @ref{6e7,,datetime}, @code{datetime(MAXYEAR, 12, 31, 23, 59,
59, 999999, tzinfo=None)}.
@end deffn

@geindex resolution (ιδιότητα της datetime.datetime)
@anchor{library/datetime datetime datetime resolution}@anchor{2ae0}
@deffn {Ιδιότητα} datetime.resolution

The smallest possible difference between non-equal @ref{6e7,,datetime} objects,
@code{timedelta(microseconds=1)}.
@end deffn

Instance attributes (read-only):

@geindex year (ιδιότητα της datetime.datetime)
@anchor{library/datetime datetime datetime year}@anchor{2ab9}
@deffn {Ιδιότητα} datetime.year

Between @ref{2aae,,MINYEAR} and @ref{2aaf,,MAXYEAR} inclusive.
@end deffn

@geindex month (ιδιότητα της datetime.datetime)
@anchor{library/datetime datetime datetime month}@anchor{2aba}
@deffn {Ιδιότητα} datetime.month

Between 1 and 12 inclusive.
@end deffn

@geindex day (ιδιότητα της datetime.datetime)
@anchor{library/datetime datetime datetime day}@anchor{2abb}
@deffn {Ιδιότητα} datetime.day

Between 1 and the number of days in the given month of the given year.
@end deffn

@geindex hour (ιδιότητα της datetime.datetime)
@anchor{library/datetime datetime datetime hour}@anchor{2abc}
@deffn {Ιδιότητα} datetime.hour

In @code{range(24)}.
@end deffn

@geindex minute (ιδιότητα της datetime.datetime)
@anchor{library/datetime datetime datetime minute}@anchor{2abd}
@deffn {Ιδιότητα} datetime.minute

In @code{range(60)}.
@end deffn

@geindex second (ιδιότητα της datetime.datetime)
@anchor{library/datetime datetime datetime second}@anchor{2abe}
@deffn {Ιδιότητα} datetime.second

In @code{range(60)}.
@end deffn

@geindex microsecond (ιδιότητα της datetime.datetime)
@anchor{library/datetime datetime datetime microsecond}@anchor{2abf}
@deffn {Ιδιότητα} datetime.microsecond

In @code{range(1000000)}.
@end deffn

@geindex tzinfo (ιδιότητα της datetime.datetime)
@anchor{library/datetime datetime datetime tzinfo}@anchor{2ac0}
@deffn {Ιδιότητα} datetime.tzinfo

The object passed as the `tzinfo' argument to the @ref{6e7,,datetime} constructor,
or @code{None} if none was passed.
@end deffn

@geindex fold (ιδιότητα της datetime.datetime)
@anchor{library/datetime datetime datetime fold}@anchor{1015}
@deffn {Ιδιότητα} 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.


Added in version 3.6.

@end deffn

Supported operations:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Operation

@tab

Result

@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{2ac0,,tzinfo} attribute as the input datetime, and
@code{datetime2 - datetime1 == timedelta} after. @ref{c57,,OverflowError} is raised if
@code{datetime2.year} would be smaller than @ref{2aae,,MINYEAR} or larger than
@ref{2aaf,,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{2ac0,,tzinfo} attribute as the input
datetime, and no time zone adjustments are done even if the input is aware.

@item 
Subtraction of a @ref{6e7,,datetime} from a @code{datetime} is defined only if
both operands are naive, or if both are aware. If one is aware and the other is
naive, @ref{291,,TypeError} is raised.

If both are naive, or both are aware and have the same @ref{2ac0,,tzinfo} attribute,
the @code{tzinfo} attributes are ignored, and the result is a @ref{d94,,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{2ac0,,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{6e7,,datetime} objects are equal if they represent the same date
and time, taking into account the time zone.

Naive and aware @ref{6e7,,datetime} objects are never equal.

If both comparands are aware, and have the same @code{tzinfo} attribute,
the @code{tzinfo} and @ref{1015,,fold} attributes are ignored and
the base datetimes are compared.
If both comparands are aware and have different @ref{2ac0,,tzinfo}
attributes, the comparison acts as comparands were first converted to UTC
datetimes except that the implementation never overflows.
@ref{6e7,,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{6e7,,datetime} objects
raises @ref{291,,TypeError}.

If both comparands are aware, and have the same @code{tzinfo} attribute,
the @code{tzinfo} and @ref{1015,,fold} attributes are ignored and
the base datetimes are compared.
If both comparands are aware and have different @ref{2ac0,,tzinfo}
attributes, the comparison acts as comparands were first converted to UTC
datetimes except that the implementation never overflows.
@end enumerate


Άλλαξε στην έκδοση 3.3: Equality comparisons between aware and naive @ref{6e7,,datetime}
instances don’t raise @ref{291,,TypeError}.



Άλλαξε στην έκδοση 3.13: Comparison between @ref{6e7,,datetime} object and an instance of
the @ref{48d,,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.


Instance methods:

@geindex date() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime date}@anchor{2ae1}
@deffn {Μέθοδος} datetime.date ()

Return @ref{48d,,date} object with same year, month and day.
@end deffn

@geindex time() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime time}@anchor{2ae2}
@deffn {Μέθοδος} datetime.time ()

Return @ref{48e,,time} object with same hour, minute, second, microsecond and fold.
@ref{2ac0,,tzinfo} is @code{None}. See also method @ref{2ae3,,timetz()}.


Άλλαξε στην έκδοση 3.6: The fold value is copied to the returned @ref{48e,,time} object.

@end deffn

@geindex timetz() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime timetz}@anchor{2ae3}
@deffn {Μέθοδος} datetime.timetz ()

Return @ref{48e,,time} object with same hour, minute, second, microsecond, fold, and
tzinfo attributes. See also method @ref{f7,,time()}.


Άλλαξε στην έκδοση 3.6: The fold value is copied to the returned @ref{48e,,time} object.

@end deffn

@geindex replace() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime replace}@anchor{186d}
@deffn {Μέθοδος} 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)

Return a new @ref{33,,datetime} object with the same attributes, but with
specified parameters updated. Note that @code{tzinfo=None} can be specified to
create a naive datetime from an aware datetime with no conversion of date
and time data.

@ref{6e7,,datetime} objects are also supported by generic function
@ref{45a,,copy.replace()}.


Άλλαξε στην έκδοση 3.6: Added the `fold' parameter.

@end deffn

@geindex astimezone() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime astimezone}@anchor{d95}
@deffn {Μέθοδος} datetime.astimezone (tz=None)

Return a @ref{6e7,,datetime} object with new @ref{2ac0,,tzinfo} attribute `tz',
adjusting the date and time data so the result is the same UTC time as
`self', but in `tz'’s local time.

If provided, `tz' must be an instance of a @ref{9d8,,tzinfo} subclass, and its
@ref{2ae4,,utcoffset()} and @ref{2ae5,,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{146c,,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{146c,,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)}.

Note that the default @ref{2ae6,,tzinfo.fromutc()} method can be overridden in a
@ref{9d8,,tzinfo} subclass to affect the result returned by @code{astimezone()}.
Ignoring error cases, @code{astimezone()} acts like:

@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


Άλλαξε στην έκδοση 3.3: `tz' now can be omitted.



Άλλαξε στην έκδοση 3.6: The @code{astimezone()} method can now be called on naive instances that
are presumed to represent system local time.

@end deffn

@geindex utcoffset() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime utcoffset}@anchor{2ae4}
@deffn {Μέθοδος} datetime.utcoffset ()

If @ref{2ac0,,tzinfo} is @code{None}, returns @code{None}, else returns
@code{self.tzinfo.utcoffset(self)}, and raises an exception if the latter doesn’t
return @code{None} or a @ref{d94,,timedelta} object with magnitude less than one day.


Άλλαξε στην έκδοση 3.7: The UTC offset is not restricted to a whole number of minutes.

@end deffn

@geindex dst() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime dst}@anchor{2ae5}
@deffn {Μέθοδος} datetime.dst ()

If @ref{2ac0,,tzinfo} is @code{None}, returns @code{None}, else returns
@code{self.tzinfo.dst(self)}, and raises an exception if the latter doesn’t return
@code{None} or a @ref{d94,,timedelta} object with magnitude less than one day.


Άλλαξε στην έκδοση 3.7: The DST offset is not restricted to a whole number of minutes.

@end deffn

@geindex tzname() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime tzname}@anchor{2ae7}
@deffn {Μέθοδος} datetime.tzname ()

If @ref{2ac0,,tzinfo} is @code{None}, returns @code{None}, else returns
@code{self.tzinfo.tzname(self)}, raises an exception if the latter doesn’t return
@code{None} or a string object,
@end deffn

@geindex timetuple() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime timetuple}@anchor{2ae8}
@deffn {Μέθοδος} datetime.timetuple ()

Return a @ref{10a7,,time.struct_time} such as returned by @ref{189b,,time.localtime()}.

@code{d.timetuple()} is equivalent to:

@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{2ae9,,tm_isdst} flag of the result is set according to the
@ref{2ae5,,dst()} method: @ref{2ac0,,tzinfo} is @code{None} or @code{dst()} returns
@code{None}, @code{tm_isdst} is set to @code{-1}; else if @code{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() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime utctimetuple}@anchor{2aea}
@deffn {Μέθοδος} datetime.utctimetuple ()

If @ref{6e7,,datetime} instance @code{d} is naive, this is the same as
@code{d.timetuple()} except that @ref{2ae9,,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{10a7,,time.struct_time} for the
normalized time is returned. @code{tm_isdst} is forced to 0. Note
that an @ref{c57,,OverflowError} may be raised if @code{d.year} was
@code{MINYEAR} or @code{MAXYEAR} and UTC adjustment spills over a year
boundary.

@cartouche
@quotation Προειδοποίηση 
Because naive @code{datetime} objects are treated by many @code{datetime} methods
as local times, it is preferred to use aware datetimes to represent times
in UTC; as a result, using @code{datetime.utctimetuple()} may give misleading
results. If you have a naive @code{datetime} representing UTC, use
@code{datetime.replace(tzinfo=timezone.utc)} to make it aware, at which point
you can use @ref{2ae8,,datetime.timetuple()}.
@end quotation
@end cartouche
@end deffn

@geindex toordinal() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime toordinal}@anchor{2aeb}
@deffn {Μέθοδος} datetime.toordinal ()

Return the proleptic Gregorian ordinal of the date. The same as
@code{self.date().toordinal()}.
@end deffn

@geindex timestamp() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime timestamp}@anchor{1447}
@deffn {Μέθοδος} datetime.timestamp ()

Return POSIX timestamp corresponding to the @ref{6e7,,datetime}
instance. The return value is a @ref{327,,float} similar to that
returned by @ref{75e,,time.time()}.

Naive @ref{6e7,,datetime} instances are assumed to represent local
time and this method relies on platform C functions to perform
the conversion. Since @code{datetime} supports a wider range of
values than the platform C functions on many platforms, this
method may raise @ref{c57,,OverflowError} or @ref{53c,,OSError} for times
far in the past or far in the future.

For aware @ref{6e7,,datetime} instances, the return value is computed
as:

@example
(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()
@end example

@cartouche
@quotation Σημείωση 
There is no method to obtain the POSIX timestamp directly from a
naive @ref{6e7,,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

or by calculating the timestamp directly:

@example
timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)
@end example
@end quotation
@end cartouche


Added in version 3.3.



Άλλαξε στην έκδοση 3.6: The @code{timestamp()} method uses the @ref{1015,,fold} attribute to
disambiguate the times during a repeated interval.



Άλλαξε στην έκδοση 3.6: This method no longer relies on the platform C @code{mktime()}
function to perform conversions.

@end deffn

@geindex weekday() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime weekday}@anchor{2aec}
@deffn {Μέθοδος} datetime.weekday ()

Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
The same as @code{self.date().weekday()}. See also @ref{2aed,,isoweekday()}.
@end deffn

@geindex isoweekday() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime isoweekday}@anchor{2aed}
@deffn {Μέθοδος} datetime.isoweekday ()

Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
The same as @code{self.date().isoweekday()}. See also @ref{2aec,,weekday()},
@ref{cc6,,isocalendar()}.
@end deffn

@geindex isocalendar() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime isocalendar}@anchor{cc6}
@deffn {Μέθοδος} datetime.isocalendar ()

Return a @ref{a3d,,named tuple} with three components: @code{year}, @code{week}
and @code{weekday}. The same as @code{self.date().isocalendar()}.
@end deffn

@geindex isoformat() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime isoformat}@anchor{eef}
@deffn {Μέθοδος} datetime.isoformat (sep='T', timespec='auto')

Return a string representing the date and time in ISO 8601 format:


@itemize -

@item 
@code{YYYY-MM-DDTHH:MM:SS.ffffff}, if @ref{2abf,,microsecond} is not 0

@item 
@code{YYYY-MM-DDTHH:MM:SS}, if @ref{2abf,,microsecond} is 0
@end itemize

If @ref{2ae4,,utcoffset()} does not return @code{None}, a string is
appended, giving the UTC offset:


@itemize -

@item 
@code{YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]}, if @ref{2abf,,microsecond}
is not 0

@item 
@code{YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]},  if @ref{2abf,,microsecond} is 0
@end itemize

Examples:

@example
>>> import datetime as dt
>>> dt.datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
'2019-05-18T15:17:08.132263'
>>> dt.datetime(2019, 5, 18, 15, 17, tzinfo=dt.timezone.utc).isoformat()
'2019-05-18T15:17:00+00:00'
@end example

The optional argument `sep' (default @code{'T'}) is a one-character separator,
placed between the date and time portions of the result. For example:

@example
>>> import datetime as dt
>>> class TZ(dt.tzinfo):
...     """A time zone with an arbitrary, constant -06:39 offset."""
...     def utcoffset(self, when):
...         return dt.timedelta(hours=-6, minutes=-39)
...
>>> dt.datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
>>> dt.datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
'2009-11-27T00:00:00.000100-06:39'
@end example

The optional argument `timespec' specifies the number of additional
components of the time to include (the default is @code{'auto'}).
It can be one of the following:


@itemize -

@item 
@code{'auto'}: Same as @code{'seconds'} if @ref{2abf,,microsecond} is 0,
same as @code{'microseconds'} otherwise.

@item 
@code{'hours'}: Include the @ref{2abc,,hour} in the two-digit @code{HH} format.

@item 
@code{'minutes'}: Include @ref{2abc,,hour} and @ref{2abd,,minute} in @code{HH:MM} format.

@item 
@code{'seconds'}: Include @ref{2abc,,hour}, @ref{2abd,,minute}, and @ref{2abe,,second}
in @code{HH:MM:SS} format.

@item 
@code{'milliseconds'}: Include full time, but truncate fractional second
part to milliseconds. @code{HH:MM:SS.sss} format.

@item 
@code{'microseconds'}: Include full time in @code{HH:MM:SS.ffffff} format.
@end itemize

@cartouche
@quotation Σημείωση 
Excluded time components are truncated, not rounded.
@end quotation
@end cartouche

@ref{277,,ValueError} will be raised on an invalid `timespec' argument:

@example
>>> import datetime as dt
>>> dt.datetime.now().isoformat(timespec='minutes')
'2002-12-25T00:00'
>>> my_datetime = dt.datetime(2015, 1, 1, 12, 30, 59, 0)
>>> my_datetime.isoformat(timespec='microseconds')
'2015-01-01T12:30:59.000000'
@end example


Άλλαξε στην έκδοση 3.6: Added the `timespec' parameter.

@end deffn

@geindex __str__() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime __str__}@anchor{2aee}
@deffn {Μέθοδος} datetime.__str__ ()

For a @ref{6e7,,datetime} instance @code{d}, @code{str(d)} is equivalent to
@code{d.isoformat(' ')}.
@end deffn

@geindex ctime() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime ctime}@anchor{2aef}
@deffn {Μέθοδος} datetime.ctime ()

Return a string representing the date and time:

@example
>>> import datetime as dt
>>> dt.datetime(2002, 12, 4, 20, 30, 40).ctime()
'Wed Dec  4 20:30:40 2002'
@end example

The output string will `not' include time zone information, regardless
of whether the input is aware or naive.

@code{d.ctime()} is equivalent to:

@example
time.ctime(time.mktime(d.timetuple()))
@end example

on platforms where the native C @code{ctime()} function
(which @ref{2ad8,,time.ctime()} invokes, but which
@code{datetime.ctime()} does not invoke) conforms to the C standard.
@end deffn

@geindex strftime() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime strftime}@anchor{1051}
@deffn {Μέθοδος} datetime.strftime (format)

Return a string representing the date and time,
controlled by an explicit format string.
See also @ref{1d52,,strftime() and strptime() behavior} and @ref{eef,,datetime.isoformat()}.
@end deffn

@geindex __format__() (μέθοδος της datetime.datetime)
@anchor{library/datetime datetime datetime __format__}@anchor{2af0}
@deffn {Μέθοδος} datetime.__format__ (format)

Same as @ref{1051,,datetime.strftime()}. This makes it possible to specify a format
string for a @ref{6e7,,datetime} object in @ref{43a,,formatted string literals} and when using @ref{a12,,str.format()}.
See also @ref{1d52,,strftime() and strptime() behavior} and @ref{eef,,datetime.isoformat()}.
@end deffn

@menu
* Examples of usage; datetime: Examples of usage datetime. 

@end menu

@node Examples of usage datetime,,,datetime objects
@anchor{library/datetime examples-of-usage-datetime}@anchor{2af1}
@subsubsection Examples of usage: @code{datetime}


Examples of working with @ref{6e7,,datetime} objects:

@example
>>> import datetime as dt

>>> # Using datetime.combine()
>>> d = dt.date(2005, 7, 14)
>>> t = dt.time(12, 30)
>>> dt.datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)

>>> # Using datetime.now()
>>> dt.datetime.now()
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> dt.datetime.now(dt.timezone.utc)
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)

>>> # Using datetime.strptime()
>>> my_datetime = dt.datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> my_datetime
datetime.datetime(2006, 11, 21, 16, 30)

>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = my_datetime.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 = my_datetime.isocalendar()
>>> for it in ic:
...     print(it)
...
2006    # ISO year
47      # ISO week
2       # ISO weekday

>>> # Formatting a datetime
>>> my_datetime.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(my_datetime, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'
@end example

The example below defines a @ref{9d8,,tzinfo} subclass capturing time zone
information for Kabul, Afghanistan, which used +4 UTC until 1945
and then +4:30 UTC thereafter:

@example
import datetime as dt

class KabulTz(dt.tzinfo):
    # Kabul used +4 until 1945, when they moved to +4:30
    UTC_MOVE_DATE = dt.datetime(1944, 12, 31, 20, tzinfo=dt.timezone.utc)

    def utcoffset(self, when):
        if when.year < 1945:
            return dt.timedelta(hours=4)
        elif (1945, 1, 1, 0, 0) <= when.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 when falls in the imaginary range, use fold to decide how
            # to resolve. See PEP 495.
            return dt.timedelta(hours=4, minutes=(30 if when.fold else 0))
        else:
            return dt.timedelta(hours=4, minutes=30)

    def fromutc(self, when):
        # Follow same validations as in datetime.tzinfo
        if not isinstance(when, dt.datetime):
            raise TypeError("fromutc() requires a datetime argument")
        if when.tzinfo is not self:
            raise ValueError("when.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 when.replace(tzinfo=dt.timezone.utc) >= self.UTC_MOVE_DATE:
            return when + dt.timedelta(hours=4, minutes=30)
        else:
            return when + dt.timedelta(hours=4)

    def dst(self, when):
        # Kabul does not observe daylight saving time.
        return dt.timedelta(0)

    def tzname(self, when):
        if when >= self.UTC_MOVE_DATE:
            return "+04:30"
        return "+04"
@end example

Usage of @code{KabulTz} from above:

@example
>>> tz1 = KabulTz()

>>> # Datetime before the change
>>> dt1 = dt.datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00

>>> # Datetime after the change
>>> dt2 = dt.datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00

>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(dt.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 time objects,tzinfo objects,datetime objects,datetime — Basic date and time types
@anchor{library/datetime datetime-time}@anchor{2af2}@anchor{library/datetime time-objects}@anchor{2af3}
@subsubsection @code{time} objects


A @ref{48e,,time} object represents a (local) time of day, independent of any particular
day, and subject to adjustment via a @ref{9d8,,tzinfo} object.

@geindex time (κλάση σε datetime)
@anchor{library/datetime datetime time}@anchor{48e}
@deffn {Κλάση} datetime.time (hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

All arguments are optional. `tzinfo' may be @code{None}, or an instance of a
@ref{9d8,,tzinfo} subclass. The remaining arguments must be integers in the
following ranges:


@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{277,,ValueError} is raised. All
default to 0 except `tzinfo', which defaults to @code{None}.
@end deffn

Class attributes:

@geindex min (ιδιότητα της datetime.time)
@anchor{library/datetime datetime time min}@anchor{2af4}
@deffn {Ιδιότητα} time.min

The earliest representable @ref{48e,,time}, @code{time(0, 0, 0, 0)}.
@end deffn

@geindex max (ιδιότητα της datetime.time)
@anchor{library/datetime datetime time max}@anchor{2af5}
@deffn {Ιδιότητα} time.max

The latest representable @ref{48e,,time}, @code{time(23, 59, 59, 999999)}.
@end deffn

@geindex resolution (ιδιότητα της datetime.time)
@anchor{library/datetime datetime time resolution}@anchor{2af6}
@deffn {Ιδιότητα} time.resolution

The smallest possible difference between non-equal @ref{48e,,time} objects,
@code{timedelta(microseconds=1)}, although note that arithmetic on
@code{time} objects is not supported.
@end deffn

Instance attributes (read-only):

@geindex hour (ιδιότητα της datetime.time)
@anchor{library/datetime datetime time hour}@anchor{2ab4}
@deffn {Ιδιότητα} time.hour

In @code{range(24)}.
@end deffn

@geindex minute (ιδιότητα της datetime.time)
@anchor{library/datetime datetime time minute}@anchor{2ab5}
@deffn {Ιδιότητα} time.minute

In @code{range(60)}.
@end deffn

@geindex second (ιδιότητα της datetime.time)
@anchor{library/datetime datetime time second}@anchor{2ab6}
@deffn {Ιδιότητα} time.second

In @code{range(60)}.
@end deffn

@geindex microsecond (ιδιότητα της datetime.time)
@anchor{library/datetime datetime time microsecond}@anchor{2ab7}
@deffn {Ιδιότητα} time.microsecond

In @code{range(1000000)}.
@end deffn

@geindex tzinfo (ιδιότητα της datetime.time)
@anchor{library/datetime datetime time tzinfo}@anchor{2ab8}
@deffn {Ιδιότητα} time.tzinfo

The object passed as the tzinfo argument to the @ref{48e,,time} constructor, or
@code{None} if none was passed.
@end deffn

@geindex fold (ιδιότητα της datetime.time)
@anchor{library/datetime datetime time fold}@anchor{1050}
@deffn {Ιδιότητα} 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.


Added in version 3.6.

@end deffn

@ref{48e,,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{291,,TypeError}.

If both comparands are aware, and have the same @ref{2ab8,,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()}).


Άλλαξε στην έκδοση 3.3: Equality comparisons between aware and naive @ref{48e,,time} instances
don’t raise @ref{291,,TypeError}.


In Boolean contexts, a @ref{48e,,time} object is always considered to be true.


Άλλαξε στην έκδοση 3.5: Before Python 3.5, a @ref{48e,,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 more
information.


Other constructors:

@geindex fromisoformat() (μέθοδος κλάσης της datetime.time)
@anchor{library/datetime datetime time fromisoformat}@anchor{a09}
@deffn {Μέθοδος} classmethod time.fromisoformat (time_string)

Return a @ref{48e,,time} corresponding to a `time_string' in any valid
ISO 8601 format, with the following exceptions:


@enumerate 

@item 
Time zone offsets may have fractional seconds.

@item 
The leading @code{T}, normally required in cases where there may be ambiguity between
a date and a time, is not required.

@item 
Fractional seconds may have any number of digits (anything beyond 6 will
be truncated).

@item 
Fractional hours and minutes are not supported.
@end enumerate

Examples:

@example
>>> import datetime as dt
>>> dt.time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
>>> dt.time.fromisoformat('T04:23:01')
datetime.time(4, 23, 1)
>>> dt.time.fromisoformat('T042301')
datetime.time(4, 23, 1)
>>> dt.time.fromisoformat('04:23:01.000384')
datetime.time(4, 23, 1, 384)
>>> dt.time.fromisoformat('04:23:01,000384')
datetime.time(4, 23, 1, 384)
>>> dt.time.fromisoformat('04:23:01+04:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
>>> dt.time.fromisoformat('04:23:01Z')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
>>> dt.time.fromisoformat('04:23:01+00:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
@end example


Added in version 3.7.



Άλλαξε στην έκδοση 3.11: Previously, this method only supported formats that could be emitted by
@ref{2af7,,time.isoformat()}.

@end deffn

@geindex strptime() (μέθοδος κλάσης της datetime.time)
@anchor{library/datetime datetime time strptime}@anchor{1a06}
@deffn {Μέθοδος} classmethod time.strptime (date_string, format)

Return a @ref{48e,,time} corresponding to `date_string', parsed according to
`format'.

If `format' does not contain microseconds or timezone information, this is equivalent to:

@example
time(*(time.strptime(date_string, format)[3:6]))
@end example

@ref{277,,ValueError} is raised if the `date_string' and `format'
cannot be parsed by @ref{17cf,,time.strptime()} or if it returns a value which is not a
time tuple.  See also @ref{1d52,,strftime() and strptime() behavior} and
@ref{a09,,time.fromisoformat()}.


Added in version 3.14.

@end deffn

Instance methods:

@geindex replace() (μέθοδος της datetime.time)
@anchor{library/datetime datetime time replace}@anchor{1c02}
@deffn {Μέθοδος} time.replace (hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

Return a new @ref{48e,,time} with the same values, but with specified
parameters updated. Note that @code{tzinfo=None} can be specified to create a
naive @code{time} from an aware @code{time}, without conversion of the
time data.

@ref{48e,,time} objects are also supported by generic function
@ref{45a,,copy.replace()}.


Άλλαξε στην έκδοση 3.6: Added the `fold' parameter.

@end deffn

@geindex isoformat() (μέθοδος της datetime.time)
@anchor{library/datetime datetime time isoformat}@anchor{2af7}
@deffn {Μέθοδος} time.isoformat (timespec='auto')

Return a string representing the time in ISO 8601 format, one of:


@itemize -

@item 
@code{HH:MM:SS.ffffff}, if @ref{2ab7,,microsecond} is not 0

@item 
@code{HH:MM:SS}, if @ref{2ab7,,microsecond} is 0

@item 
@code{HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]}, if @ref{2af8,,utcoffset()} does not return @code{None}

@item 
@code{HH:MM:SS+HH:MM[:SS[.ffffff]]}, if @ref{2ab7,,microsecond} is 0 and @ref{2af8,,utcoffset()} does not return @code{None}
@end itemize

The optional argument `timespec' specifies the number of additional
components of the time to include (the default is @code{'auto'}).
It can be one of the following:


@itemize -

@item 
@code{'auto'}: Same as @code{'seconds'} if @ref{2ab7,,microsecond} is 0,
same as @code{'microseconds'} otherwise.

@item 
@code{'hours'}: Include the @ref{2ab4,,hour} in the two-digit @code{HH} format.

@item 
@code{'minutes'}: Include @ref{2ab4,,hour} and @ref{2ab5,,minute} in @code{HH:MM} format.

@item 
@code{'seconds'}: Include @ref{2ab4,,hour}, @ref{2ab5,,minute}, and @ref{2ab6,,second}
in @code{HH:MM:SS} format.

@item 
@code{'milliseconds'}: Include full time, but truncate fractional second
part to milliseconds. @code{HH:MM:SS.sss} format.

@item 
@code{'microseconds'}: Include full time in @code{HH:MM:SS.ffffff} format.
@end itemize

@cartouche
@quotation Σημείωση 
Excluded time components are truncated, not rounded.
@end quotation
@end cartouche

@ref{277,,ValueError} will be raised on an invalid `timespec' argument.

Example:

@example
>>> import datetime as dt
>>> dt.time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
'12:34'
>>> my_time = dt.time(hour=12, minute=34, second=56, microsecond=0)
>>> my_time.isoformat(timespec='microseconds')
'12:34:56.000000'
>>> my_time.isoformat(timespec='auto')
'12:34:56'
@end example


Άλλαξε στην έκδοση 3.6: Added the `timespec' parameter.

@end deffn

@geindex __str__() (μέθοδος της datetime.time)
@anchor{library/datetime datetime time __str__}@anchor{2af9}
@deffn {Μέθοδος} time.__str__ ()

For a time @code{t}, @code{str(t)} is equivalent to @code{t.isoformat()}.
@end deffn

@geindex strftime() (μέθοδος της datetime.time)
@anchor{library/datetime datetime time strftime}@anchor{1cf7}
@deffn {Μέθοδος} time.strftime (format)

Return a string representing the time, controlled by an explicit format
string.  See also @ref{1d52,,strftime() and strptime() behavior} and @ref{2af7,,time.isoformat()}.
@end deffn

@geindex __format__() (μέθοδος της datetime.time)
@anchor{library/datetime datetime time __format__}@anchor{2afa}
@deffn {Μέθοδος} time.__format__ (format)

Same as @ref{1cf7,,time.strftime()}. This makes it possible to specify
a format string for a @ref{48e,,time} object in @ref{43a,,formatted string literals} and when using @ref{a12,,str.format()}.
See also @ref{1d52,,strftime() and strptime() behavior} and @ref{2af7,,time.isoformat()}.
@end deffn

@geindex utcoffset() (μέθοδος της datetime.time)
@anchor{library/datetime datetime time utcoffset}@anchor{2af8}
@deffn {Μέθοδος} time.utcoffset ()

If @ref{2ab8,,tzinfo} is @code{None}, returns @code{None}, else returns
@code{self.tzinfo.utcoffset(None)}, and raises an exception if the latter doesn’t
return @code{None} or a @ref{d94,,timedelta} object with magnitude less than one day.


Άλλαξε στην έκδοση 3.7: The UTC offset is not restricted to a whole number of minutes.

@end deffn

@geindex dst() (μέθοδος της datetime.time)
@anchor{library/datetime datetime time dst}@anchor{2afb}
@deffn {Μέθοδος} time.dst ()

If @ref{2ab8,,tzinfo} is @code{None}, returns @code{None}, else returns
@code{self.tzinfo.dst(None)}, and raises an exception if the latter doesn’t return
@code{None}, or a @ref{d94,,timedelta} object with magnitude less than one day.


Άλλαξε στην έκδοση 3.7: The DST offset is not restricted to a whole number of minutes.

@end deffn

@geindex tzname() (μέθοδος της datetime.time)
@anchor{library/datetime datetime time tzname}@anchor{2afc}
@deffn {Μέθοδος} time.tzname ()

If @ref{2ab8,,tzinfo} is @code{None}, returns @code{None}, else returns
@code{self.tzinfo.tzname(None)}, or raises an exception if the latter doesn’t
return @code{None} or a string object.
@end deffn

@menu
* Examples of usage; time: Examples of usage time. 

@end menu

@node Examples of usage time,,,time objects
@anchor{library/datetime examples-of-usage-time}@anchor{2afd}
@subsubsection Examples of usage: @code{time}


Examples of working with a @ref{48e,,time} object:

@example
>>> import datetime as dt
>>> class TZ1(dt.tzinfo):
...     def utcoffset(self, when):
...         return dt.timedelta(hours=1)
...     def dst(self, when):
...         return dt.timedelta(0)
...     def tzname(self, when):
...         return "+01:00"
...     def  __repr__(self):
...         return f"@{self.__class__.__name__@}()"
...
>>> t = dt.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 tzinfo objects,timezone objects,time objects,datetime — Basic date and time types
@anchor{library/datetime datetime-tzinfo}@anchor{2afe}@anchor{library/datetime tzinfo-objects}@anchor{2aff}
@subsubsection @code{tzinfo} objects


@geindex tzinfo (κλάση σε datetime)
@anchor{library/datetime datetime tzinfo}@anchor{9d8}
@deffn {Κλάση} datetime.tzinfo

This is an @ref{155f,,abstract base class}, meaning that this class should not be
instantiated directly.  Define a subclass of @code{tzinfo} to capture
information about a particular time zone.

An instance of (a concrete subclass of) @code{tzinfo} can be passed to the
constructors for @ref{6e7,,datetime} and @ref{48e,,time} objects. The latter objects
view their attributes as being in local time, and the @code{tzinfo} object
supports methods revealing offset of local time from UTC, the name of the time
zone, and DST offset, all relative to a date or time object passed to them.

You need to derive a concrete subclass, and (at least)
supply implementations of the standard @code{tzinfo} methods needed by the
@ref{6e7,,datetime} methods you use. The @code{datetime} module provides
@ref{146c,,timezone}, a simple concrete subclass of @code{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 @code{tzinfo} subclass must have an
@ref{2fa,,__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 @code{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() (μέθοδος της datetime.tzinfo)
@anchor{library/datetime datetime tzinfo utcoffset}@anchor{2b00}
@deffn {Μέθοδος} tzinfo.utcoffset (dt)

Return offset of local time from UTC, as a @ref{d94,,timedelta} object that is
positive east of UTC. If local time is west of UTC, this should be negative.

This represents the `total' offset from UTC; for example, if a
@ref{9d8,,tzinfo} object represents both time zone and DST adjustments,
@code{utcoffset()} should return their sum. If the UTC offset isn’t known,
return @code{None}. Else the value returned must be a @ref{d94,,timedelta} object
strictly between @code{-timedelta(hours=24)} and @code{timedelta(hours=24)}
(the magnitude of the offset must be less than one day). Most implementations
of @code{utcoffset()} will probably look like one of these two:

@example
return CONSTANT                 # fixed-offset class
return CONSTANT + self.dst(dt)  # daylight-aware class
@end example

If @code{utcoffset()} does not return @code{None}, @ref{2b01,,dst()} should not return
@code{None} either.

The default implementation of @code{utcoffset()} raises
@ref{59a,,NotImplementedError}.


Άλλαξε στην έκδοση 3.7: The UTC offset is not restricted to a whole number of minutes.

@end deffn

@geindex dst() (μέθοδος της datetime.tzinfo)
@anchor{library/datetime datetime tzinfo dst}@anchor{2b01}
@deffn {Μέθοδος} tzinfo.dst (dt)

Return the daylight saving time (DST) adjustment, as a @ref{d94,,timedelta}
object or
@code{None} if DST information isn’t known.

Return @code{timedelta(0)} if DST is not in effect.
If DST is in effect, return the offset as a @ref{d94,,timedelta} object
(see @ref{2b00,,utcoffset()} for details). Note that DST offset, if applicable, has
already been added to the UTC offset returned by @code{utcoffset()}, so there’s
no need to consult @code{dst()} unless you’re interested in obtaining DST info
separately. For example, @ref{2ae8,,datetime.timetuple()} calls its @ref{2ac0,,tzinfo}
attribute’s @code{dst()} method to determine how the @ref{2ae9,,tm_isdst} flag
should be set, and @ref{2ae6,,tzinfo.fromutc()} calls @code{dst()} to account for
DST changes when crossing time zones.

An instance `tz' of a @ref{9d8,,tzinfo} subclass that models both standard and
daylight times must be consistent in this sense:

@code{tz.utcoffset(dt) - tz.dst(dt)}

must return the same result for every @ref{6e7,,datetime} `dt' with @code{dt.tzinfo ==
tz}. For sane @code{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{d95,,datetime.astimezone()}
relies on this, but cannot detect violations; it’s the programmer’s
responsibility to ensure it. If a @code{tzinfo} subclass cannot guarantee
this, it may be able to override the default implementation of
@ref{2ae6,,tzinfo.fromutc()} to work correctly with @code{astimezone()} regardless.

Most implementations of @code{dst()} will probably look like one of these two:

@example
import datetime as dt

def dst(self, when):
    # a fixed-offset class:  doesn't account for DST
    return dt.timedelta(0)
@end example

or:

@example
import datetime as dt

def dst(self, when):
    # Code to set dston and dstoff to the time zone's DST
    # transition times based on the input when.year, and expressed
    # in standard local time.

    if dston <= when.replace(tzinfo=None) < dstoff:
        return dt.timedelta(hours=1)
    else:
        return dt.timedelta(0)
@end example

The default implementation of @code{dst()} raises @ref{59a,,NotImplementedError}.


Άλλαξε στην έκδοση 3.7: The DST offset is not restricted to a whole number of minutes.

@end deffn

@geindex tzname() (μέθοδος της datetime.tzinfo)
@anchor{library/datetime datetime tzinfo tzname}@anchor{2b02}
@deffn {Μέθοδος} tzinfo.tzname (dt)

Return the time zone name corresponding to the @ref{6e7,,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{9d8,,tzinfo}
subclasses will wish to return different names depending on the specific value
of `dt' passed, especially if the @code{tzinfo} class is accounting for
daylight time.

The default implementation of @code{tzname()} raises @ref{59a,,NotImplementedError}.
@end deffn

These methods are called by a @ref{6e7,,datetime} or @ref{48e,,time} object, in
response to their methods of the same names. A @code{datetime} object passes
itself as the argument, and a @code{time} object passes @code{None} as the
argument. A @ref{9d8,,tzinfo} subclass’s methods should therefore be prepared to
accept a `dt' argument of @code{None}, or of class @code{datetime}.

When @code{None} is passed, it’s up to the class designer to decide the best
response. For example, returning @code{None} is appropriate if the class wishes to
say that time objects don’t participate in the @ref{9d8,,tzinfo} protocols. It
may be more useful for @code{utcoffset(None)} to return the standard UTC offset, as
there is no other convention for discovering the standard offset.

When a @ref{6e7,,datetime} object is passed in response to a @code{datetime}
method, @code{dt.tzinfo} is the same object as `self'. @ref{9d8,,tzinfo} methods can
rely on this, unless user code calls @code{tzinfo} methods directly. The
intent is that the @code{tzinfo} methods interpret `dt' as being in local
time, and not need worry about objects in other time zones.

There is one more @ref{9d8,,tzinfo} method that a subclass may wish to override:

@geindex fromutc() (μέθοδος της datetime.tzinfo)
@anchor{library/datetime datetime tzinfo fromutc}@anchor{2ae6}
@deffn {Μέθοδος} tzinfo.fromutc (dt)

This is called from the default @ref{d95,,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 @code{fromutc()} is to adjust the date and time data, returning an
equivalent datetime in `self'’s local time.

Most @ref{9d8,,tzinfo} subclasses should be able to inherit the default
@code{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 @code{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{d95,,astimezone()} and
@code{fromutc()} may not produce the result you want if the result is one of the
hours straddling the moment the standard offset changes.

Skipping code for error cases, the default @code{fromutc()} implementation acts
like:

@example
import datetime as dt

def fromutc(self, when):
    # raise ValueError error if when.tzinfo is not self
    dtoff = when.utcoffset()
    dtdst = when.dst()
    # raise ValueError if dtoff is None or dtdst is None
    delta = dtoff - dtdst  # this is self's standard offset
    if delta:
        when += delta   # convert to standard local time
        dtdst = when.dst()
        # raise ValueError if dtdst is None
    if dtdst:
        return when + dtdst
    else:
        return when
@end example
@end deffn

In the following @code{tzinfo_examples.py} file there are some examples of
@ref{9d8,,tzinfo} classes:

@example
import datetime as dt

# 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

ZERO = dt.timedelta(0)
HOUR = dt.timedelta(hours=1)
SECOND = dt.timedelta(seconds=1)

STDOFFSET = dt.timedelta(seconds=-time.timezone)
if time.daylight:
    DSTOFFSET = dt.timedelta(seconds=-time.altzone)
else:
    DSTOFFSET = STDOFFSET

DSTDIFF = DSTOFFSET - STDOFFSET


class LocalTimezone(dt.tzinfo):

    def fromutc(self, when):
        assert when.tzinfo is self
        stamp = (when - 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 dt.datetime(*args, microsecond=when.microsecond,
                           tzinfo=self, fold=fold)

    def utcoffset(self, when):
        if self._isdst(when):
            return DSTOFFSET
        else:
            return STDOFFSET

    def dst(self, when):
        if self._isdst(when):
            return DSTDIFF
        else:
            return ZERO

    def tzname(self, when):
        return time.tzname[self._isdst(when)]

    def _isdst(self, when):
        tt = (when.year, when.month, when.day,
              when.hour, when.minute, when.second,
              when.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(when):
    days_to_go = 6 - when.weekday()
    if days_to_go:
        when += dt.timedelta(days_to_go)
    return when


# 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 = dt.datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = dt.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 = dt.datetime(1, 4, 1, 2)
DSTEND_1987_2006 = dt.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 = dt.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 (dt.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(dt.tzinfo):

    def __init__(self, hours, reprname, stdname, dstname):
        self.stdoffset = dt.timedelta(hours=hours)
        self.reprname = reprname
        self.stdname = stdname
        self.dstname = dstname

    def __repr__(self):
        return self.reprname

    def tzname(self, when):
        if self.dst(when):
            return self.dstname
        else:
            return self.stdname

    def utcoffset(self, when):
        return self.stdoffset + self.dst(when)

    def dst(self, when):
        if when is None or when.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 when.tzinfo is self.
            return ZERO
        assert when.tzinfo is self
        start, end = us_dst_range(when.year)
        # Can't compare naive to aware objects, so strip the timezone from
        # when first.
        when = when.replace(tzinfo=None)
        if start + HOUR <= when < end - HOUR:
            # DST is in effect.
            return HOUR
        if end - HOUR <= when < end:
            # Fold (an ambiguous hour): use when.fold to disambiguate.
            return ZERO if when.fold else HOUR
        if start <= when < start + HOUR:
            # Gap (a non-existent hour): reverse the fold rule.
            return HOUR if when.fold else ZERO
        # DST is off.
        return ZERO

    def fromutc(self, when):
        assert when.tzinfo is self
        start, end = us_dst_range(when.year)
        start = start.replace(tzinfo=self)
        end = end.replace(tzinfo=self)
        std_time = when + 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

Note that there are unavoidable subtleties twice per year in a @ref{9d8,,tzinfo}
subclass accounting for both standard and daylight time, at the DST transition
points. For concreteness, consider US Eastern (UTC -0500), where EDT begins the
minute after 1:59 (EST) on the second Sunday in March, and ends the minute after
1:59 (EDT) on the first Sunday in November:

@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

When DST starts (the «start» line), the local wall clock leaps from 1:59 to
3:00. A wall time of the form 2:MM doesn’t really make sense on that day, so
@code{astimezone(Eastern)} won’t deliver a result with @code{hour == 2} on the day DST
begins. For example, at the Spring forward transition of 2016, we get:

@example
>>> import datetime as dt
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = dt.datetime(2016, 3, 13, 5, tzinfo=dt.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{d95,,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{1015,,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
>>> import datetime as dt
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = dt.datetime(2016, 11, 6, 4, tzinfo=dt.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{6e7,,datetime} instances that differ only by the value of the
@ref{1015,,fold} attribute are considered equal in comparisons.

Applications that can’t bear wall-time ambiguities should explicitly check the
value of the @ref{1015,,fold} attribute or avoid using hybrid
@ref{9d8,,tzinfo} subclasses; there are no ambiguities when using @ref{146c,,timezone},
or any other fixed-offset @code{tzinfo} subclass (such as a class representing
only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).


@subsubheading Δείτε επίσης


@quotation


@table @asis

@item @ref{13d,,zoneinfo}

The @code{datetime} module has a basic @ref{146c,,timezone} class (for
handling arbitrary fixed offsets from UTC) and its @ref{a07,,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}

The Time Zone Database (often called tz, tzdata or zoneinfo) contains code
and data that represent the history of local time for many representative
locations around the globe. It is updated periodically to reflect changes
made by political bodies to time zone boundaries, UTC offsets, and
daylight-saving rules.
@end table


@node timezone objects,strftime and strptime behavior,tzinfo objects,datetime — Basic date and time types
@anchor{library/datetime datetime-timezone}@anchor{2b03}@anchor{library/datetime timezone-objects}@anchor{2b04}
@subsubsection @code{timezone} objects


The @ref{146c,,timezone} class is a subclass of @ref{9d8,,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 (κλάση σε datetime)
@anchor{library/datetime datetime timezone}@anchor{146c}
@deffn {Κλάση} datetime.timezone (offset[, name])

The `offset' argument must be specified as a @ref{d94,,timedelta}
object representing the difference between the local time and UTC. It must
be strictly between @code{-timedelta(hours=24)} and
@code{timedelta(hours=24)}, otherwise @ref{277,,ValueError} is raised.

The `name' argument is optional. If specified it must be a string that
will be used as the value returned by the @ref{2ae7,,datetime.tzname()} method.


Added in version 3.2.



Άλλαξε στην έκδοση 3.7: The UTC offset is not restricted to a whole number of minutes.

@end deffn

@geindex utcoffset() (μέθοδος της datetime.timezone)
@anchor{library/datetime datetime timezone utcoffset}@anchor{2b05}
@deffn {Μέθοδος} timezone.utcoffset (dt)

Return the fixed value specified when the @ref{146c,,timezone} instance is
constructed.

The `dt' argument is ignored. The return value is a @ref{d94,,timedelta}
instance equal to the difference between the local time and UTC.


Άλλαξε στην έκδοση 3.7: The UTC offset is not restricted to a whole number of minutes.

@end deffn

@geindex tzname() (μέθοδος της datetime.timezone)
@anchor{library/datetime datetime timezone tzname}@anchor{2b06}
@deffn {Μέθοδος} timezone.tzname (dt)

Return the fixed value specified when the @ref{146c,,timezone} instance
is constructed.

If `name' is not provided in the constructor, the name returned by
@code{tzname(dt)} is generated from the value of the @code{offset} as follows. If
`offset' is @code{timedelta(0)}, the name is «UTC», otherwise it is a string in
the format @code{UTC±HH:MM}, where ± is the sign of @code{offset}, HH and MM are
two digits of @code{offset.hours} and @code{offset.minutes} respectively.


Άλλαξε στην έκδοση 3.6: Name generated from @code{offset=timedelta(0)} is now plain @code{'UTC'}, not
@code{'UTC+00:00'}.

@end deffn

@geindex dst() (μέθοδος της datetime.timezone)
@anchor{library/datetime datetime timezone dst}@anchor{2b07}
@deffn {Μέθοδος} timezone.dst (dt)

Always returns @code{None}.
@end deffn

@geindex fromutc() (μέθοδος της datetime.timezone)
@anchor{library/datetime datetime timezone fromutc}@anchor{2b08}
@deffn {Μέθοδος} timezone.fromutc (dt)

Return @code{dt + offset}. The `dt' argument must be an aware
@ref{6e7,,datetime} instance, with @code{tzinfo} set to @code{self}.
@end deffn

Class attributes:

@geindex utc (ιδιότητα της datetime.timezone)
@anchor{library/datetime datetime timezone utc}@anchor{a07}
@deffn {Ιδιότητα} timezone.utc

The UTC time zone, @code{timezone(timedelta(0))}.
@end deffn

@geindex % (percent);datetime format

@node strftime and strptime behavior,,timezone objects,datetime — Basic date and time types
@anchor{library/datetime strftime-and-strptime-behavior}@anchor{2b09}@anchor{library/datetime strftime-strptime-behavior}@anchor{1d52}
@subsubsection @code{strftime()} and @code{strptime()} behavior


@ref{48d,,date}, @ref{6e7,,datetime}, and @ref{48e,,time} objects all support a
@code{strftime(format)} method, to create a string representing the time under the
control of an explicit format string.

Conversely, the @ref{48c,,date.strptime()}, @ref{2d2,,datetime.strptime()} and
@ref{17cf,,time.strptime()} class methods create an object from a string
representing the time and a corresponding format string.

The table below provides a high-level comparison of @ref{1051,,strftime()}
versus @ref{2d2,,strptime()}:


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@tab

@code{strftime}

@tab

@code{strptime}

@item

Usage

@tab

Convert object to a string according to a given format

@tab

Parse a string into an object given a corresponding format

@item

Type of method

@tab

Instance method

@tab

Class method

@item

Signature

@tab

@code{strftime(format)}

@tab

@code{strptime(date_string, format)}

@end multitable


@quotation
@anchor{library/datetime format-codes}@anchor{2aaa}
@end quotation

@menu
* strftime() and strptime() format codes: strftime and strptime format codes. 
* Technical detail:: 

@end menu

@node strftime and strptime format codes,Technical detail,,strftime and strptime behavior
@anchor{library/datetime strftime-and-strptime-format-codes}@anchor{2b0a}
@subsubsection @code{strftime()} and @code{strptime()} format codes


These methods accept format codes that can be used to parse and format dates:

@example
>>> import datetime as dt
>>> dt.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

The following is a list of all the format codes that the 2011 C standard
requires, and these work on all supported platforms.


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Directive

@tab

Meaning

@tab

Example

@tab

Notes

@item

@code{%a}

@tab

Weekday as locale’s
abbreviated name.

@tab


@display
Sun, Mon, …, Sat (en_US);@w{ }
So, Mo, …, Sa (de_DE)@w{ }
@end display



@tab

(1)

@item

@code{%A}

@tab

Weekday as locale’s full name.

@tab


@display
Sunday, Monday, …, Saturday (en_US);@w{ }
Sonntag, Montag, …, Samstag (de_DE)@w{ }
@end display



@tab

(1)

@item

@code{%b}

@tab

Month as locale’s abbreviated
name.

@tab


@display
Jan, Feb, …, Dec (en_US);@w{ }
Jan, Feb, …, Dez (de_DE)@w{ }
@end display



@tab

(1)

@item

@code{%B}

@tab

Month as locale’s full name.

@tab


@display
January, February, …, December (en_US);@w{ }
Januar, Februar, …, Dezember (de_DE)@w{ }
@end display



@tab

(1)

@item

@code{%c}

@tab

Locale’s appropriate date and
time representation.

@tab


@display
Tue Aug 16 21:30:00 1988 (en_US);@w{ }
Di 16 Aug 21:30:00 1988 (de_DE)@w{ }
@end display



@tab

(1)

@item

@code{%C}

@tab

The year divided by 100 and
truncated to an integer as a
zero-padded decimal number.

@tab

01, 02, …, 99

@tab

(0)

@item

@code{%d}

@tab

Day of the month as a
zero-padded decimal number.

@tab

01, 02, …, 31

@tab

(9),
(10)

@item

@code{%D}

@tab

Equivalent to @code{%m/%d/%y}.

@tab

11/28/25

@tab

(9)

@item

@code{%e}

@tab

The day of the month as a
space-padded decimal number.

@tab

␣1, ␣2, …, 31

@tab

(10)

@item

@code{%F}

@tab

Equivalent to @code{%Y-%m-%d},
the ISO 8601 format.

@tab

2025-10-11,
1001-12-30

@tab

@item

@code{%g}

@tab

Last 2 digits of ISO 8601 year
representing the year that
contains the greater part of
the ISO week (@code{%V}).

@tab

00, 01, …, 99

@tab

(0)

@item

@code{%G}

@tab

ISO 8601 year with century
representing the year that
contains the greater part of
the ISO week (@code{%V}).

@tab

0001, 0002, …, 2013,
2014, …, 9998, 9999

@tab

(8)

@item

@code{%h}

@tab

Equivalent to @code{%b}.

@tab

See @code{%b}.

@tab

(0)

@item

@code{%H}

@tab

Hour (24-hour clock) as a
zero-padded decimal number.

@tab

00, 01, …, 23

@tab

(9)

@item

@code{%I}

@tab

Hour (12-hour clock) as a
zero-padded decimal number.

@tab

01, 02, …, 12

@tab

(9)

@item

@code{%j}

@tab

Day of the year as a
zero-padded decimal number.

@tab

001, 002, …, 366

@tab

(9)

@item

@code{%m}

@tab

Month as a zero-padded
decimal number.

@tab

01, 02, …, 12

@tab

(9)

@item

@code{%M}

@tab

Minute as a zero-padded
decimal number.

@tab

00, 01, …, 59

@tab

(9)

@item

@code{%n}

@tab

The newline character
(@code{'\n'}). For
@code{strptime()}, zero or
more whitespace.

@tab

@code{\n}

@tab

@item

@code{%p}

@tab

Locale’s equivalent of either
AM or PM.

@tab


@display
AM, PM (en_US);@w{ }
am, pm (de_DE)@w{ }
@end display



@tab

(1),
(3)

@item

@code{%r}

@tab

Locale’s 12-hour clock time.

@tab

12:00:00 AM

@tab

(1),
(0)

@item

@code{%R}

@tab

Equivalent to @code{%H:%M}.

@tab

10:01

@tab

@item

@code{%S}

@tab

Second as a zero-padded
decimal number.

@tab

00, 01, …, 59

@tab

(4),
(9)

@item

@code{%t}

@tab

The tab character (@code{'\t'}).
For @code{strptime()},
zero or more whitespace.

@tab

@code{\t}

@tab

@item

@code{%T}

@tab

ISO 8601 time format,
equivalent to @code{%H:%M:%S}.

@tab

10:01:59

@tab

@item

@code{%u}

@tab

ISO 8601 weekday as a decimal
number where 1 is Monday.

@tab

1, 2, …, 7

@tab

@item

@code{%U}

@tab

Week number of the year
(Sunday as the first day of
the week) as a zero-padded
decimal number. All days in a
new year preceding the first
Sunday are considered to be in
week 0.

@tab

00, 01, …, 53

@tab

(7),
(9)

@item

@code{%V}

@tab

ISO 8601 week as a decimal
number with Monday as
the first day of the week.
Week 01 is the week containing
Jan 4.

@tab

01, 02, …, 53

@tab

(8),
(9)

@item

@code{%w}

@tab

Weekday as a decimal number,
where 0 is Sunday and 6 is
Saturday.

@tab

0, 1, …, 6

@tab

@item

@code{%W}

@tab

Week number of the year
(Monday as the first day of
the week) as a zero-padded
decimal number. All days in a
new year preceding the first
Monday are considered to be in
week 0.

@tab

00, 01, …, 53

@tab

(7),
(9)

@item

@code{%x}

@tab

Locale’s appropriate date
representation.

@tab


@display
08/16/88 (None);@w{ }
08/16/1988 (en_US);@w{ }
16.08.1988 (de_DE)@w{ }
@end display



@tab

(1)

@item

@code{%X}

@tab

Locale’s appropriate time
representation.

@tab


@display
21:30:00 (en_US);@w{ }
21:30:00 (de_DE)@w{ }
@end display



@tab

(1)

@item

@code{%y}

@tab

Year without century as a
zero-padded decimal number.

@tab

00, 01, …, 99

@tab

(9)

@item

@code{%Y}

@tab

Year with century as a decimal
number.

@tab

0001, 0002, …, 2013,
2014, …, 9998, 9999

@tab

(2)

@item

@code{%z}

@tab

UTC offset in the form
@code{±HHMM[SS[.ffffff]]} (empty
string if the object is
naive).

@tab

(empty), +0000,
-0400, +1030,
+063415,
-030712.345216

@tab

(6)

@item

@code{%Z}

@tab

Time zone name (empty string
if the object is naive).

@tab

(empty), UTC, GMT

@tab

(6)

@item

@code{%%}

@tab

A literal @code{'%'} character.

@tab

%

@tab

@end multitable


The ISO 8601 year and ISO 8601 week directives are not interchangeable
with the year and week number directives above. Calling @ref{2d2,,strptime()} with
incomplete or ambiguous ISO 8601 directives will raise a @ref{277,,ValueError}.

Several additional directives not required by the C11 standard are included for
convenience.


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Directive

@tab

Meaning

@tab

Example

@tab

Notes

@item

@code{%f}

@tab

Microsecond as a decimal
number, zero-padded to 6
digits.

@tab

000000, 000001, …,
999999

@tab

(5)

@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


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.


Added in version 3.6: @code{%G}, @code{%u} and @code{%V} were added.



Added in version 3.12: @code{%:z} was added for @ref{1051,,strftime()}.



Added in version 3.15: @code{%D}, @code{%F}, @code{%n}, @code{%t}, and @code{%:z} were added for
@ref{2d2,,strptime()}.


@node Technical detail,,strftime and strptime format codes,strftime and strptime behavior
@anchor{library/datetime technical-detail}@anchor{2b0b}
@subsubsection Technical detail


Broadly speaking, @code{d.strftime(fmt)} acts like the @ref{f7,,time} module’s
@code{time.strftime(fmt, d.timetuple())} although not all objects support a
@ref{2ad1,,timetuple()} method.

For the @ref{2d2,,datetime.strptime()} and @ref{48c,,date.strptime()} class methods,
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.

@cartouche
@quotation Σημείωση 
Format strings without separators can be ambiguous for parsing. For
example, with @code{%Y%m%d}, the string @code{2026111} may be parsed either as
@code{2026-11-01} or as @code{2026-01-11}.
Use separators to ensure the input is parsed as intended.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
When used to parse partial dates lacking a year, @ref{2d2,,datetime.strptime()}
and @ref{48c,,date.strptime()} will raise when encountering February 29 because
the default year of 1900 is `not' a leap year.  Always add a default leap
year to partial date strings before parsing.
@end quotation
@end cartouche

@c # doctest seems to turn the warning into an error which makes it
@c # show up and require matching and prevents the actual interesting
@c # exception from being raised.
@c # Manually apply the catch_warnings context manager
@c import warnings
@c catch_warnings = warnings.catch_warnings()
@c catch_warnings.__enter__()
@c warnings.simplefilter("ignore")

@c catch_warnings.__exit__()

@example
>>> import datetime as dt
>>> value = "2/29"
>>> dt.datetime.strptime(value, "%m/%d")
Traceback (most recent call last):
...
ValueError: day 29 must be in range 1..28 for month 2 in year 1900
>>> dt.datetime.strptime(f"1904 @{value@}", "%Y %m/%d")
datetime.datetime(1904, 2, 29, 0, 0)
@end example

Using @code{datetime.strptime(date_string, format)} is equivalent to:

@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{48e,,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{48d,,date} objects, the format codes for hours, minutes, seconds, and
microseconds should not be used, as @code{date} objects have no such
values. If they’re used anyway, 0 is substituted for them.

For the same reason, handling of format strings containing Unicode code points
that can’t be represented in the charset of the current locale is also
platform-dependent. On some platforms such code points are preserved intact in
the output, while on others @code{strftime} may raise @ref{675,,UnicodeError} or return
an empty string instead.

Notes:


@enumerate 0

@item 
This format code is currently unsupported by @ref{2d2,,strptime()}.

@item 
Because the format depends on the current locale, care should be taken when
making assumptions about the output value. Field orderings will vary (for
example, «month/day/year» versus «day/month/year»), and the output may
contain non-ASCII characters.

@item 
The @ref{2d2,,strptime()} method can parse years in the full [1, 9999] range, but
years < 1000 must be zero-filled to 4-digit width.


Άλλαξε στην έκδοση 3.2: In previous versions, @ref{1051,,strftime()} method was restricted to
years >= 1900.



Άλλαξε στην έκδοση 3.3: In version 3.2, @ref{1051,,strftime()} method was restricted to
years >= 1000.


@item 
When used with the @ref{2d2,,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{f7,,time} module, the @code{datetime} module does not support
leap seconds.

@item 
When used with the @ref{2d2,,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.

For an aware object:


@table @asis

@item @code{%z}

@ref{2ae4,,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
@code{utcoffset()} returns @code{timedelta(hours=-3, minutes=-30)}, @code{%z} is
replaced with the string @code{'-0330'}.
@end table


Άλλαξε στην έκδοση 3.7: The UTC offset is not restricted to a whole number of minutes.



Άλλαξε στην έκδοση 3.7: When the @code{%z} directive is provided to the  @ref{2d2,,strptime()} method,
the UTC offsets can have a colon as a separator between hours, minutes
and seconds.
For example, both @code{'+010000'} and @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}

When used with @ref{1051,,strftime()}, behaves exactly as @code{%z},
except that a colon separator is added between hours, minutes and seconds.

When used with @ref{2d2,,strptime()}, the UTC offset is `required'
to have a colon as a separator between hours, minutes and seconds.
For example, @code{'+01:00:00'} (but `not' @code{'+010000'}) will be parsed as
an offset of one hour. In addition, providing @code{'Z'} is identical to
@code{'+00:00'}.

@item @code{%Z}

In @ref{1051,,strftime()}, @code{%Z} is replaced by an empty string if
@ref{2ae7,,tzname()} returns @code{None}; otherwise @code{%Z} is replaced by the
returned value, which must be a string.

@ref{2d2,,strptime()} only accepts certain values for @code{%Z}:


@enumerate 

@item 
any value in @code{time.tzname} for your machine’s locale

@item 
the hard-coded values @code{UTC} and @code{GMT}
@end enumerate

So someone living in Japan may have @code{JST}, @code{UTC}, and @code{GMT} as
valid values, but probably not @code{EST}. It will raise @code{ValueError} for
invalid values.
@end table


Άλλαξε στην έκδοση 3.2: When the @code{%z} directive is provided to the @ref{2d2,,strptime()} method, an
aware @ref{6e7,,datetime} object will be produced. The @code{tzinfo} of the
result will be set to a @ref{146c,,timezone} instance.


@item 
When used with the @ref{2d2,,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{2d2,,strptime()} format string. Also note that @code{%G} and @code{%Y} are not
interchangeable.

@item 
When used with the @ref{2d2,,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{2d2,,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 (1900) is not a leap year.  Users run into that bug every leap year.

@example
>>> month_day = "02/29"
>>> dt.datetime.strptime(f"@{month_day@};1984", "%m/%d;%Y")  # No leap year bug.
datetime.datetime(1984, 2, 29, 0, 0)
@end example


Άλλαξε στην έκδοση 3.15: Using @code{%d} without a year now raises @ref{277,,ValueError}.



Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.17: @ref{2d2,,strptime()} calls using a format string containing
@code{%e} without a year now emit a @ref{2c9,,DeprecationWarning}.

@end enumerate

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node zoneinfo — IANA time zone support,calendar — General calendar-related functions,datetime — Basic date and time types,Data Types
@anchor{library/zoneinfo doc}@anchor{2b0c}@anchor{library/zoneinfo module-zoneinfo}@anchor{13d}@anchor{library/zoneinfo translation-repo}@anchor{2b0d}@anchor{library/zoneinfo zoneinfo-iana-time-zone-support}@anchor{2b0e}
@subsection @code{zoneinfo} — IANA time zone support


@geindex module; zoneinfo


Added in version 3.9.


`Source code:' Lib/zoneinfo@footnote{https://github.com/python/cpython/tree/main/Lib/zoneinfo}


__________________________________________________________________


The @code{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, @code{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 Δείτε επίσης



@table @asis

@item Module: @ref{33,,datetime}

Provides the @ref{48e,,time} and @ref{6e7,,datetime}
types with which the @ref{cb1,,ZoneInfo} class is designed to be used.

@item Package tzdata@footnote{https://pypi.org/project/tzdata/}

First-party package maintained by the CPython core developers to supply
time zone data via PyPI.
@end table


@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

@menu
* Using ZoneInfo:: 
* Data sources:: 
* The ZoneInfo class:: 
* Functions: Functions<2>. 
* Globals:: 
* Exceptions and warnings:: 

@end menu

@node Using ZoneInfo,Data sources,,zoneinfo — IANA time zone support
@anchor{library/zoneinfo using-zoneinfo}@anchor{2b0f}
@subsubsection Using @code{ZoneInfo}


@ref{cb1,,ZoneInfo} is a concrete implementation of the @ref{9d8,,datetime.tzinfo}
abstract base class, and is intended to be attached to @code{tzinfo}, either via
the constructor, the @ref{186d,,datetime.replace}
method or @ref{d95,,datetime.astimezone}:

@example
>>> from zoneinfo import ZoneInfo
>>> import datetime as dt

>>> when = dt.datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(when)
2020-10-31 12:00:00-07:00

>>> when.tzname()
'PDT'
@end example

Datetimes constructed in this way are compatible with datetime arithmetic and
handle daylight saving time transitions with no further intervention:

@example
>>> when_add = when + dt.timedelta(days=1)

>>> print(when_add)
2020-11-01 12:00:00-08:00

>>> when_add.tzname()
'PST'
@end example

These time zones also support the @ref{1015,,fold} attribute
introduced in 
@geindex Python Enhancement Proposals; PEP 495
PEP 495@footnote{https://peps.python.org/pep-0495/}.  During offset transitions which induce ambiguous
times (such as a daylight saving time to standard time transition), the offset
from `before' the transition is used when @code{fold=0}, and the offset `after'
the transition is used when @code{fold=1}, for example:

@example
>>> when = dt.datetime(2020, 11, 1, 1, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(when)
2020-11-01 01:00:00-07:00

>>> print(when.replace(fold=1))
2020-11-01 01:00:00-08:00
@end example

When converting from another time zone, the fold will be set to the correct
value:

@example
>>> LOS_ANGELES = ZoneInfo("America/Los_Angeles")
>>> when_utc = dt.datetime(2020, 11, 1, 8, tzinfo=dt.timezone.utc)

>>> # Before the PDT -> PST transition
>>> print(when_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00

>>> # After the PDT -> PST transition
>>> print((when_utc + dt.timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00
@end example

@node Data sources,The ZoneInfo class,Using ZoneInfo,zoneinfo — IANA time zone support
@anchor{library/zoneinfo data-sources}@anchor{2b10}
@subsubsection Data sources


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{cb1,,ZoneInfo} will raise
@ref{1a0f,,ZoneInfoNotFoundError}.

@menu
* Configuring the data sources:: 

@end menu

@node Configuring the data sources,,,Data sources
@anchor{library/zoneinfo configuring-the-data-sources}@anchor{2b11}@anchor{library/zoneinfo zoneinfo-data-configuration}@anchor{2b12}
@subsubsection Configuring the data sources


When @code{ZoneInfo(key)} is called, the constructor first searches the
directories specified in @ref{2353,,TZPATH} for a file matching @code{key}, and on
failure looks for a match in the tzdata package. This behavior can be
configured in three ways:


@enumerate 

@item 
The default @ref{2353,,TZPATH} when not otherwise specified can be configured at
@ref{2354,,compile time}.

@item 
@ref{2353,,TZPATH} can be configured using @ref{2b13,,an environment variable}.

@item 
At @ref{2b14,,runtime}, the search path can be
manipulated using the @ref{19ff,,reset_tzpath()} function.
@end enumerate

@menu
* Compile-time configuration:: 
* Environment configuration:: 
* Runtime configuration:: 

@end menu

@node Compile-time configuration,Environment configuration,,Configuring the data sources
@anchor{library/zoneinfo compile-time-configuration}@anchor{2b15}@anchor{library/zoneinfo zoneinfo-data-compile-time-config}@anchor{2354}
@subsubsection Compile-time configuration


The default @ref{2353,,TZPATH} includes several common deployment locations for the
time zone database (except on Windows, where there are no «well-known»
locations for time zone data). On POSIX systems, downstream distributors and
those building Python from source who know where their system
time zone data is deployed may change the default time zone path by specifying
the compile-time option @code{TZPATH} (or, more likely, the @ref{2352,,configure flag --with-tzpath}), which should be a string delimited by
@ref{2322,,os.pathsep}.

On all platforms, the configured value is available as the @code{TZPATH} key in
@ref{41e,,sysconfig.get_config_var()}.

@node Environment configuration,Runtime configuration,Compile-time configuration,Configuring the data sources
@anchor{library/zoneinfo environment-configuration}@anchor{2b16}@anchor{library/zoneinfo zoneinfo-data-environment-var}@anchor{2b13}
@subsubsection Environment configuration


When initializing @ref{2353,,TZPATH} (either at import time or whenever
@ref{19ff,,reset_tzpath()} is called with no arguments), the @code{zoneinfo} module will
use the environment variable @code{PYTHONTZPATH}, if it exists, to set the search
path.

@geindex μεταβλητή περιβάλλοντος; PYTHONTZPATH
@anchor{library/zoneinfo envvar-PYTHONTZPATH}@anchor{2b17}
@deffn {Μεταβλητή Περιβάλλοντος} PYTHONTZPATH

This is an @ref{2322,,os.pathsep}-separated string containing the time zone
search path to use. It must consist of only absolute rather than relative
paths. Relative components specified in @code{PYTHONTZPATH} will not be used,
but otherwise the behavior when a relative path is specified is
implementation-defined; CPython will raise @ref{2b18,,InvalidTZPathWarning}, but
other implementations are free to silently ignore the erroneous component
or raise an exception.
@end deffn

To set the system to ignore the system data and use the tzdata package
instead, set @code{PYTHONTZPATH=""}.

@node Runtime configuration,,Environment configuration,Configuring the data sources
@anchor{library/zoneinfo runtime-configuration}@anchor{2b19}@anchor{library/zoneinfo zoneinfo-data-runtime-config}@anchor{2b14}
@subsubsection Runtime configuration


The TZ search path can also be configured at runtime using the
@ref{19ff,,reset_tzpath()} function. This is generally not an advisable operation,
though it is reasonable to use it in test functions that require the use of a
specific time zone path (or require disabling access to the system time zones).

@node The ZoneInfo class,Functions<2>,Data sources,zoneinfo — IANA time zone support
@anchor{library/zoneinfo the-zoneinfo-class}@anchor{2b1a}
@subsubsection The @code{ZoneInfo} class


@geindex ZoneInfo (κλάση σε zoneinfo)
@anchor{library/zoneinfo zoneinfo ZoneInfo}@anchor{cb1}
@deffn {Κλάση} zoneinfo.ZoneInfo (key)

A concrete @ref{9d8,,datetime.tzinfo} subclass that represents an IANA time
zone specified by the string @code{key}. Calls to the primary constructor will
always return objects that compare identically; put another way, barring
cache invalidation via @ref{1934,,ZoneInfo.clear_cache()}, for all values of
@code{key}, the following assertion will always be true:

@example
a = ZoneInfo(key)
b = ZoneInfo(key)
assert a is b
@end example

@code{key} must be in the form of a relative, normalized POSIX path, with no
up-level references. The constructor will raise @ref{277,,ValueError} if a
non-conforming key is passed.

If no file matching @code{key} is found, the constructor will raise
@ref{1a0f,,ZoneInfoNotFoundError}.
@end deffn

The @code{ZoneInfo} class has two alternate constructors:

@geindex from_file() (μέθοδος κλάσης της zoneinfo.ZoneInfo)
@anchor{library/zoneinfo zoneinfo ZoneInfo from_file}@anchor{197e}
@deffn {Μέθοδος} classmethod ZoneInfo.from_file (file_obj, /, key=None)

Constructs a @code{ZoneInfo} object from a file-like object returning bytes
(e.g. a file opened in binary mode or an @ref{1255,,io.BytesIO} object).
Unlike the primary constructor, this always constructs a new object.

The @code{key} parameter sets the name of the zone for the purposes of
@ref{a0f,,__str__()} and @ref{1bc,,__repr__()}.

Objects created via this constructor cannot be pickled (see @ref{2b1b,,pickling}).

@ref{277,,ValueError} is raised if the data read from `file_obj' is not a valid
TZif file.
@end deffn

@geindex no_cache() (μέθοδος κλάσης της zoneinfo.ZoneInfo)
@anchor{library/zoneinfo zoneinfo ZoneInfo no_cache}@anchor{2b1c}
@deffn {Μέθοδος} classmethod ZoneInfo.no_cache (key)

An alternate constructor that bypasses the constructor’s cache. It is
identical to the primary constructor, but returns a new object on each
call. This is most likely to be useful for testing or demonstration
purposes, but it can also be used to create a system with a different cache
invalidation strategy.

Objects created via this constructor will also bypass the cache of a
deserializing process when unpickled.

@c TODO: Add "See `cache_behavior`_" reference when that section is ready.

@cartouche
@quotation Προσοχή 
Using this constructor may change the semantics of your datetimes in
surprising ways, only use it if you know that you need to.
@end quotation
@end cartouche
@end deffn

The following class methods are also available:

@geindex clear_cache() (μέθοδος κλάσης της zoneinfo.ZoneInfo)
@anchor{library/zoneinfo zoneinfo ZoneInfo clear_cache}@anchor{1934}
@deffn {Μέθοδος} classmethod ZoneInfo.clear_cache (*, only_keys=None)

A method for invalidating the cache on the @code{ZoneInfo} class. If no
arguments are passed, all caches are invalidated and the next call to
the primary constructor for each key will return a new instance.

If an iterable of key names is passed to the @code{only_keys} parameter, only
the specified keys will be removed from the cache. Keys passed to
@code{only_keys} but not found in the cache are ignored.

@c TODO: Add "See `cache_behavior`_" reference when that section is ready.

@cartouche
@quotation Προειδοποίηση 
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

The class has one attribute:

@geindex key (ιδιότητα της zoneinfo.ZoneInfo)
@anchor{library/zoneinfo zoneinfo ZoneInfo key}@anchor{2b1d}
@deffn {Ιδιότητα} ZoneInfo.key

This is a read-only @ref{2b1e,,attribute} that returns the value of @code{key}
passed to the constructor, which should be a lookup key in the IANA time
zone database (e.g. @code{America/New_York}, @code{Europe/Paris} or
@code{Asia/Tokyo}).

For zones constructed from file without specifying a @code{key} parameter,
this will be set to @code{None}.

@cartouche
@quotation Σημείωση 
Although it is a somewhat common practice to expose these to end users,
these values are designed to be primary keys for representing the
relevant zones and not necessarily user-facing elements.  Projects like
CLDR (the Unicode Common Locale Data Repository) can be used to get
more user-friendly strings from these keys.
@end quotation
@end cartouche
@end deffn

@menu
* String representations:: 
* Pickle serialization:: 

@end menu

@node String representations,Pickle serialization,,The ZoneInfo class
@anchor{library/zoneinfo string-representations}@anchor{2b1f}
@subsubsection String representations


The string representation returned when calling @ref{1df,,str} on a
@ref{cb1,,ZoneInfo} object defaults to using the @ref{2b1d,,ZoneInfo.key} attribute (see
the note on usage in the attribute documentation):

@example
>>> zone = ZoneInfo("Pacific/Kwajalein")
>>> str(zone)
'Pacific/Kwajalein'

>>> when = dt.datetime(2020, 4, 1, 3, 15, tzinfo=zone)
>>> f"@{when.isoformat()@} [@{when.tzinfo@}]"
'2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'
@end example

For objects constructed from a file without specifying a @code{key} parameter,
@code{str} falls back to calling @ref{45b,,repr()}. @code{ZoneInfo}’s @code{repr} is
implementation-defined and not necessarily stable between versions, but it is
guaranteed not to be a valid @code{ZoneInfo} key.

@node Pickle serialization,,String representations,The ZoneInfo class
@anchor{library/zoneinfo pickle-serialization}@anchor{2b20}@anchor{library/zoneinfo pickling}@anchor{2b1b}
@subsubsection Pickle serialization


Rather than serializing all transition data, @code{ZoneInfo} objects are
serialized by key, and @code{ZoneInfo} objects constructed from files (even those
with a value for @code{key} specified) cannot be pickled.

The behavior of a @code{ZoneInfo} file depends on how it was constructed:


@enumerate 

@item 
@code{ZoneInfo(key)}: When constructed with the primary constructor, a
@code{ZoneInfo} object is serialized by key, and when deserialized, the
deserializing process uses the primary and thus it is expected that these
are the same object as other references to the same time
zone.  For example, if @code{europe_berlin_pkl} is a string containing a pickle
constructed from @code{ZoneInfo("Europe/Berlin")}, one would expect the
following behavior:

@example
>>> a = ZoneInfo("Europe/Berlin")
>>> b = pickle.loads(europe_berlin_pkl)
>>> a is b
True
@end example

@item 
@code{ZoneInfo.no_cache(key)}: When constructed from the cache-bypassing
constructor, the @code{ZoneInfo} object is also serialized by key, but when
deserialized, the deserializing process uses the cache bypassing
constructor. If @code{europe_berlin_pkl_nc} is a string containing a pickle
constructed from @code{ZoneInfo.no_cache("Europe/Berlin")}, one would expect
the following behavior:

@example
>>> a = ZoneInfo("Europe/Berlin")
>>> b = pickle.loads(europe_berlin_pkl_nc)
>>> a is b
False
@end example

@item 
@code{ZoneInfo.from_file(file_obj, /, key=None)}: When constructed from a file, the
@code{ZoneInfo} object raises an exception on pickling. If an end user wants to
pickle a @code{ZoneInfo} constructed from a file, it is recommended that they
use a wrapper type or a custom serialization function: either serializing by
key or storing the contents of the file object and serializing that.
@end enumerate

This method of serialization requires that the time zone data for the required
key be available on both the serializing and deserializing side, similar to the
way that references to classes and functions are expected to exist in both the
serializing and deserializing environments. It also means that no guarantees
are made about the consistency of results when unpickling a @code{ZoneInfo}
pickled in an environment with a different version of the time zone data.

@node Functions<2>,Globals,The ZoneInfo class,zoneinfo — IANA time zone support
@anchor{library/zoneinfo functions}@anchor{2b21}
@subsubsection Functions


@geindex available_timezones() (στη μονάδα zoneinfo)
@anchor{library/zoneinfo zoneinfo available_timezones}@anchor{1f3c}
@deffn {Συνάρτηση} zoneinfo.available_timezones ()

Get a set containing all the valid keys for IANA time zones available
anywhere on the time zone path. This is recalculated on every call to the
function.

This function only includes canonical zone names and does not include
«special» zones such as those under the @code{posix/} and @code{right/}
directories, the @code{posixrules}  or the @code{localtime} zone.

@cartouche
@quotation Προσοχή 
This function may open a large number of files, as the best way to
determine if a file on the time zone path is a valid time zone is to
read the «magic string» at the beginning.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
These values are not designed to be exposed to end-users; for user
facing elements, applications should use something like CLDR (the
Unicode Common Locale Data Repository) to get more user-friendly
strings. See also the cautionary note on @ref{2b1d,,ZoneInfo.key}.
@end quotation
@end cartouche
@end deffn

@geindex reset_tzpath() (στη μονάδα zoneinfo)
@anchor{library/zoneinfo zoneinfo reset_tzpath}@anchor{19ff}
@deffn {Συνάρτηση} zoneinfo.reset_tzpath (to=None)

Sets or resets the time zone search path (@ref{2353,,TZPATH}) for the module.
When called with no arguments, @code{TZPATH} is set to the default value.

Calling @code{reset_tzpath} will not invalidate the @ref{cb1,,ZoneInfo} cache,
and so calls to the primary @code{ZoneInfo} constructor will only use the new
@code{TZPATH} in the case of a cache miss.

The @code{to} parameter must be a @ref{8ff,,sequence} of strings or
@ref{100f,,os.PathLike} and not a string, all of which must be absolute paths.
@ref{277,,ValueError} will be raised if something other than an absolute path
is passed.
@end deffn

@node Globals,Exceptions and warnings,Functions<2>,zoneinfo — IANA time zone support
@anchor{library/zoneinfo globals}@anchor{2b22}
@subsubsection Globals


@geindex TZPATH (στη μονάδα zoneinfo)
@anchor{library/zoneinfo zoneinfo TZPATH}@anchor{2353}
@deffn {Δεδομένα} zoneinfo.TZPATH

A read-only sequence representing the time zone search path – when
constructing a @code{ZoneInfo} from a key, the key is joined to each entry in
the @code{TZPATH}, and the first file found is used.

@code{TZPATH} may contain only absolute paths, never relative paths,
regardless of how it is configured.

The object that @code{zoneinfo.TZPATH} points to may change in response to a
call to @ref{19ff,,reset_tzpath()}, so it is recommended to use
@code{zoneinfo.TZPATH} rather than importing @code{TZPATH} from @code{zoneinfo} or
assigning a long-lived variable to @code{zoneinfo.TZPATH}.

For more information on configuring the time zone search path, see
@ref{2b12,,Configuring the data sources}.
@end deffn

@node Exceptions and warnings,,Globals,zoneinfo — IANA time zone support
@anchor{library/zoneinfo exceptions-and-warnings}@anchor{2b23}
@subsubsection Exceptions and warnings


@geindex ZoneInfoNotFoundError
@anchor{library/zoneinfo zoneinfo ZoneInfoNotFoundError}@anchor{1a0f}
@deffn {Εξαίρεση} zoneinfo.ZoneInfoNotFoundError

Raised when construction of a @ref{cb1,,ZoneInfo} object fails because the
specified key could not be found on the system. This is a subclass of
@ref{7df,,KeyError}.
@end deffn

@geindex InvalidTZPathWarning
@anchor{library/zoneinfo zoneinfo InvalidTZPathWarning}@anchor{2b18}
@deffn {Εξαίρεση} zoneinfo.InvalidTZPathWarning

Raised when 
@geindex PYTHONTZPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONTZPATH
@ref{2b17,,PYTHONTZPATH} contains an invalid component that will
be filtered out, such as a relative path.
@end deffn

@c Links and references:

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node calendar — General calendar-related functions,collections — Container datatypes,zoneinfo — IANA time zone support,Data Types
@anchor{library/calendar doc}@anchor{2b24}@anchor{library/calendar calendar-general-calendar-related-functions}@anchor{2b25}@anchor{library/calendar module-calendar}@anchor{15}@anchor{library/calendar translation-repo}@anchor{2b26}
@subsection @code{calendar} — General calendar-related functions


@geindex module; calendar

`Source code:' Lib/calendar.py@footnote{https://github.com/python/cpython/tree/main/Lib/calendar.py}


__________________________________________________________________


This module allows you to output calendars like the Unix @code{cal} program,
and provides additional useful functions related to the calendar. By default,
these calendars have Monday as the first day of the week, and Sunday as the last
(the European convention). Use @ref{2b27,,setfirstweekday()} to set the first day of
the week to Sunday (6) or to any other weekday.  Parameters that specify dates
are given as integers. For related
functionality, see also the @ref{33,,datetime} and @ref{f7,,time} modules.

The functions and classes defined in this module
use an idealized calendar, the current Gregorian calendar extended indefinitely
in both directions.  This matches the definition of the «proleptic Gregorian»
calendar in Dershowitz and Reingold’s book «Calendrical Calculations», where
it’s the base calendar for all computations.  Zero and negative years are
interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
2 BC, and so on.

@geindex Calendar (κλάση σε calendar)
@anchor{library/calendar calendar Calendar}@anchor{2b28}
@deffn {Κλάση} calendar.Calendar (firstweekday=0)

Creates a @code{Calendar} object. `firstweekday' is an integer specifying the
first day of the week. @ref{2b29,,MONDAY} is @code{0} (the default), @ref{2b2a,,SUNDAY} is @code{6}.

A @code{Calendar} object provides several methods that can be used for
preparing the calendar data for formatting. This class doesn’t do any formatting
itself. This is the job of subclasses.

@code{Calendar} instances have the following methods and attributes:

@geindex firstweekday (ιδιότητα της calendar.Calendar)
@anchor{library/calendar calendar Calendar firstweekday}@anchor{2b2b}
@deffn {Ιδιότητα} firstweekday

The first weekday as an integer (0–6).

This property can also be set and read using
@ref{2b2c,,setfirstweekday()} and
@ref{2b2d,,getfirstweekday()} respectively.
@end deffn

@geindex getfirstweekday() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar getfirstweekday}@anchor{2b2d}
@deffn {Μέθοδος} getfirstweekday ()

Return an @ref{326,,int} for the current first weekday (0–6).

Identical to reading the @ref{2b2b,,firstweekday} property.
@end deffn

@geindex setfirstweekday() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar setfirstweekday}@anchor{2b2c}
@deffn {Μέθοδος} setfirstweekday (firstweekday)

Set the first weekday to `firstweekday', passed as an @ref{326,,int} (0–6).

Identical to setting the @ref{2b2b,,firstweekday} property.
@end deffn

@geindex iterweekdays() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar iterweekdays}@anchor{2b2e}
@deffn {Μέθοδος} iterweekdays ()

Return an iterator for the weekday numbers that will be used for one
week.  The first value from the iterator will be the same as the value of
the @ref{2b2b,,firstweekday} property.
@end deffn

@geindex itermonthdates() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar itermonthdates}@anchor{fd8}
@deffn {Μέθοδος} itermonthdates (year, month)

Return an iterator for the month `month' (1–12) in the year `year'. This
iterator will return all days (as @ref{48d,,datetime.date} objects) for the
month and all days before the start of the month or after the end of the
month that are required to get a complete week.
@end deffn

@geindex itermonthdays() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar itermonthdays}@anchor{2b2f}
@deffn {Μέθοδος} itermonthdays (year, month)

Return an iterator for the month `month' in the year `year' similar to
@ref{fd8,,itermonthdates()}, but not restricted by the @ref{48d,,datetime.date}
range. Days returned will simply be day of the month numbers.  For the
days outside of the specified month, the day number is @code{0}.
@end deffn

@geindex itermonthdays2() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar itermonthdays2}@anchor{2b30}
@deffn {Μέθοδος} itermonthdays2 (year, month)

Return an iterator for the month `month' in the year `year' similar to
@ref{fd8,,itermonthdates()}, but not restricted by the @ref{48d,,datetime.date}
range. Days returned will be tuples consisting of a day of the month
number and a weekday number.
@end deffn

@geindex itermonthdays3() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar itermonthdays3}@anchor{fd9}
@deffn {Μέθοδος} itermonthdays3 (year, month)

Return an iterator for the month `month' in the year `year' similar to
@ref{fd8,,itermonthdates()}, but not restricted by the @ref{48d,,datetime.date}
range. Days returned will be tuples consisting of a year, a month and a day
of the month numbers.


Added in version 3.7.

@end deffn

@geindex itermonthdays4() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar itermonthdays4}@anchor{fda}
@deffn {Μέθοδος} itermonthdays4 (year, month)

Return an iterator for the month `month' in the year `year' similar to
@ref{fd8,,itermonthdates()}, but not restricted by the @ref{48d,,datetime.date}
range. Days returned will be tuples consisting of a year, a month, a day
of the month, and a day of the week numbers.


Added in version 3.7.

@end deffn

@geindex monthdatescalendar() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar monthdatescalendar}@anchor{2b31}
@deffn {Μέθοδος} monthdatescalendar (year, month)

Return a list of the weeks in the month `month' of the `year' as full
weeks.  Weeks are lists of seven @ref{48d,,datetime.date} objects.
@end deffn

@geindex monthdays2calendar() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar monthdays2calendar}@anchor{2b32}
@deffn {Μέθοδος} monthdays2calendar (year, month)

Return a list of the weeks in the month `month' of the `year' as full
weeks.  Weeks are lists of seven tuples of day numbers and weekday
numbers.
@end deffn

@geindex monthdayscalendar() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar monthdayscalendar}@anchor{2b33}
@deffn {Μέθοδος} monthdayscalendar (year, month)

Return a list of the weeks in the month `month' of the `year' as full
weeks.  Weeks are lists of seven day numbers.
@end deffn

@geindex yeardatescalendar() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar yeardatescalendar}@anchor{2b34}
@deffn {Μέθοδος} yeardatescalendar (year, width=3)

Return the data for the specified year ready for formatting. The return
value is a list of month rows. Each month row contains up to `width'
months (defaulting to 3). Each month contains between 4 and 6 weeks and
each week contains 1–7 days. Days are @ref{48d,,datetime.date} objects.
@end deffn

@geindex yeardays2calendar() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar yeardays2calendar}@anchor{2b35}
@deffn {Μέθοδος} yeardays2calendar (year, width=3)

Return the data for the specified year ready for formatting (similar to
@ref{2b34,,yeardatescalendar()}). Entries in the week lists are tuples of day
numbers and weekday numbers. Day numbers outside this month are zero.
@end deffn

@geindex yeardayscalendar() (μέθοδος της calendar.Calendar)
@anchor{library/calendar calendar Calendar yeardayscalendar}@anchor{2b36}
@deffn {Μέθοδος} yeardayscalendar (year, width=3)

Return the data for the specified year ready for formatting (similar to
@ref{2b34,,yeardatescalendar()}). Entries in the week lists are day numbers. Day
numbers outside this month are zero.
@end deffn
@end deffn

@geindex TextCalendar (κλάση σε calendar)
@anchor{library/calendar calendar TextCalendar}@anchor{1a3e}
@deffn {Κλάση} calendar.TextCalendar (firstweekday=0)

This class can be used to generate plain text calendars.

@code{TextCalendar} instances have the following methods:

@geindex prweek() (μέθοδος της calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar prweek}@anchor{2b37}
@deffn {Μέθοδος} prweek (theweek, width)

Print a week’s calendar as returned by @ref{2b38,,formatweek()} and without a
final newline.
@end deffn

@geindex formatday() (μέθοδος της calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatday}@anchor{2b39}
@deffn {Μέθοδος} 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() (μέθοδος της calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatweek}@anchor{2b38}
@deffn {Μέθοδος} 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{2b27,,setfirstweekday()} method.
@end deffn

@geindex formatweekday() (μέθοδος της calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatweekday}@anchor{2b3a}
@deffn {Μέθοδος} 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() (μέθοδος της calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatweekheader}@anchor{2b3b}
@deffn {Μέθοδος} 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() (μέθοδος της calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatmonth}@anchor{2b3c}
@deffn {Μέθοδος} formatmonth (theyear, themonth, w=0, l=0)

Return a month’s calendar in a multi-line string. If `w' is provided, it
specifies the width of the date columns, which are centered. If `l' is
given, it specifies the number of lines that each week will use. Depends
on the first weekday as specified in the constructor or set by the
@ref{2b27,,setfirstweekday()} method.
@end deffn

@geindex formatmonthname() (μέθοδος της calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatmonthname}@anchor{2b3d}
@deffn {Μέθοδος} 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() (μέθοδος της calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar prmonth}@anchor{2b3e}
@deffn {Μέθοδος} prmonth (theyear, themonth, w=0, l=0)

Print a month’s calendar as returned by @ref{2b3c,,formatmonth()}.
@end deffn

@geindex formatyear() (μέθοδος της calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatyear}@anchor{2b3f}
@deffn {Μέθοδος} formatyear (theyear, w=2, l=1, c=6, m=3)

Return a `m'-column calendar for an entire year as a multi-line string.
Optional parameters `w', `l', and `c' are for date column width, lines per
week, and number of spaces between month columns, respectively. Depends on
the first weekday as specified in the constructor or set by the
@ref{2b27,,setfirstweekday()} method.  The earliest year for which a calendar
can be generated is platform-dependent.
@end deffn

@geindex pryear() (μέθοδος της calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar pryear}@anchor{2b40}
@deffn {Μέθοδος} pryear (theyear, w=2, l=1, c=6, m=3)

Print the calendar for an entire year as returned by @ref{2b3f,,formatyear()}.
@end deffn
@end deffn

@geindex HTMLCalendar (κλάση σε calendar)
@anchor{library/calendar calendar HTMLCalendar}@anchor{202}
@deffn {Κλάση} calendar.HTMLCalendar (firstweekday=0)

This class can be used to generate HTML calendars.

@code{HTMLCalendar} instances have the following methods:

@geindex formatmonth() (μέθοδος της calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar formatmonth}@anchor{2b41}
@deffn {Μέθοδος} formatmonth (theyear, themonth, withyear=True)

Return a month’s calendar as an HTML table. If `withyear' is true the year
will be included in the header, otherwise just the month name will be
used.
@end deffn

@geindex formatyear() (μέθοδος της calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar formatyear}@anchor{2b42}
@deffn {Μέθοδος} formatyear (theyear, width=3)

Return a year’s calendar as an HTML table. `width' (defaulting to 3)
specifies the number of months per row.
@end deffn

@geindex formatyearpage() (μέθοδος της calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar formatyearpage}@anchor{2b43}
@deffn {Μέθοδος} formatyearpage (theyear, width=3, css='calendar.css', encoding=None)

Return a year’s calendar as a complete HTML page. `width' (defaulting to
3) specifies the number of months per row. `css' is the name for the
cascading style sheet to be used. @ref{a65,,None} can be passed if no style
sheet should be used. `encoding' specifies the encoding to be used for the
output (defaulting to @code{'utf-8'}).
@end deffn

@geindex formatmonthname() (μέθοδος της calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar formatmonthname}@anchor{2b44}
@deffn {Μέθοδος} 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} has the following attributes you can override to
customize the CSS classes used by the calendar:

@geindex cssclasses (ιδιότητα της calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclasses}@anchor{2b45}
@deffn {Ιδιότητα} cssclasses

A list of CSS classes used for each weekday. The default class list is:

@example
cssclasses = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
@end example

more styles can be added for each day:

@example
cssclasses = ["mon text-bold", "tue", "wed", "thu", "fri", "sat", "sun red"]
@end example

Note that the length of this list must be seven items.
@end deffn

@geindex cssclass_noday (ιδιότητα της calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclass_noday}@anchor{2b46}
@deffn {Ιδιότητα} cssclass_noday

The CSS class for a weekday occurring in the previous or coming month.


Added in version 3.7.

@end deffn

@geindex cssclasses_weekday_head (ιδιότητα της calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclasses_weekday_head}@anchor{2b47}
@deffn {Ιδιότητα} cssclasses_weekday_head

A list of CSS classes used for weekday names in the header row.
The default is the same as @ref{2b45,,cssclasses}.


Added in version 3.7.

@end deffn

@geindex cssclass_month_head (ιδιότητα της calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclass_month_head}@anchor{2b48}
@deffn {Ιδιότητα} cssclass_month_head

The month’s head CSS class (used by @ref{2b44,,formatmonthname()}).
The default value is @code{"month"}.


Added in version 3.7.

@end deffn

@geindex cssclass_month (ιδιότητα της calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclass_month}@anchor{2b49}
@deffn {Ιδιότητα} cssclass_month

The CSS class for the whole month’s table (used by @ref{2b41,,formatmonth()}).
The default value is @code{"month"}.


Added in version 3.7.

@end deffn

@geindex cssclass_year (ιδιότητα της calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclass_year}@anchor{2b4a}
@deffn {Ιδιότητα} cssclass_year

The CSS class for the whole year’s table of tables (used by
@ref{2b42,,formatyear()}). The default value is @code{"year"}.


Added in version 3.7.

@end deffn

@geindex cssclass_year_head (ιδιότητα της calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclass_year_head}@anchor{2b4b}
@deffn {Ιδιότητα} cssclass_year_head

The CSS class for the table head for the whole year (used by
@ref{2b42,,formatyear()}). The default value is @code{"year"}.


Added in version 3.7.

@end deffn

Note that although the naming for the above described class attributes is
singular (e.g. @code{cssclass_month} @code{cssclass_noday}), one can replace the
single CSS class with a space separated list of CSS classes, for example:

@example
"text-bold text-red"
@end example

Here is an example how @code{HTMLCalendar} can be customized:

@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 (κλάση σε calendar)
@anchor{library/calendar calendar LocaleTextCalendar}@anchor{b29}
@deffn {Κλάση} calendar.LocaleTextCalendar (firstweekday=0, locale=None)

This subclass of @ref{1a3e,,TextCalendar} can be passed a locale name in the
constructor and will return month and weekday names in the specified locale.
@end deffn

@geindex LocaleHTMLCalendar (κλάση σε calendar)
@anchor{library/calendar calendar LocaleHTMLCalendar}@anchor{b2a}
@deffn {Κλάση} calendar.LocaleHTMLCalendar (firstweekday=0, locale=None)

This subclass of @ref{202,,HTMLCalendar} can be passed a locale name in the
constructor and will return month and weekday names in the specified
locale.
@end deffn

@cartouche
@quotation Σημείωση 
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

For simple text calendars this module provides the following functions.

@geindex setfirstweekday() (στη μονάδα calendar)
@anchor{library/calendar calendar setfirstweekday}@anchor{2b27}
@deffn {Συνάρτηση} calendar.setfirstweekday (weekday)

Sets the weekday (@code{0} is Monday, @code{6} is Sunday) to start each week. The
values @ref{2b29,,MONDAY}, @ref{2b4c,,TUESDAY}, @ref{2b4d,,WEDNESDAY}, @ref{2b4e,,THURSDAY},
@ref{2b4f,,FRIDAY}, @ref{2b50,,SATURDAY}, and @ref{2b2a,,SUNDAY} are provided for
convenience. For example, to set the first weekday to Sunday:

@example
import calendar
calendar.setfirstweekday(calendar.SUNDAY)
@end example
@end deffn

@geindex firstweekday() (στη μονάδα calendar)
@anchor{library/calendar calendar firstweekday}@anchor{2b51}
@deffn {Συνάρτηση} calendar.firstweekday ()

Returns the current setting for the weekday to start each week.
@end deffn

@geindex isleap() (στη μονάδα calendar)
@anchor{library/calendar calendar isleap}@anchor{2b52}
@deffn {Συνάρτηση} calendar.isleap (year)

Returns @ref{fcc,,True} if `year' is a leap year, otherwise @ref{ef5,,False}.
@end deffn

@geindex leapdays() (στη μονάδα calendar)
@anchor{library/calendar calendar leapdays}@anchor{2b53}
@deffn {Συνάρτηση} calendar.leapdays (y1, y2)

Returns the number of leap years in the range from `y1' to `y2' (exclusive),
where `y1' and `y2' are years.

This function works for ranges spanning a century change.
@end deffn

@geindex weekday() (στη μονάδα calendar)
@anchor{library/calendar calendar weekday}@anchor{2b54}
@deffn {Συνάρτηση} calendar.weekday (year, month, day)

Returns the day of the week (@code{0} is Monday) for `year' (@code{1970}–…),
`month' (@code{1}–@code{12}), `day' (@code{1}–@code{31}).
@end deffn

@geindex weekheader() (στη μονάδα calendar)
@anchor{library/calendar calendar weekheader}@anchor{2b55}
@deffn {Συνάρτηση} calendar.weekheader (n)

Return a header containing abbreviated weekday names. `n' specifies the width in
characters for one weekday.
@end deffn

@geindex monthrange() (στη μονάδα calendar)
@anchor{library/calendar calendar monthrange}@anchor{2b56}
@deffn {Συνάρτηση} calendar.monthrange (year, month)

Returns weekday of first day of the month and number of days in month, for the
specified `year' and `month'.
@end deffn

@geindex monthcalendar() (στη μονάδα calendar)
@anchor{library/calendar calendar monthcalendar}@anchor{2b57}
@deffn {Συνάρτηση} calendar.monthcalendar (year, month)

Returns a matrix representing a month’s calendar.  Each row represents a week;
days outside of the month are represented by zeros. Each week begins with Monday
unless set by @ref{2b27,,setfirstweekday()}.
@end deffn

@geindex prmonth() (στη μονάδα calendar)
@anchor{library/calendar calendar prmonth}@anchor{2b58}
@deffn {Συνάρτηση} calendar.prmonth (theyear, themonth, w=0, l=0)

Prints a month’s calendar as returned by @ref{1b27,,month()}.
@end deffn

@geindex month() (στη μονάδα calendar)
@anchor{library/calendar calendar month}@anchor{1b27}
@deffn {Συνάρτηση} calendar.month (theyear, themonth, w=0, l=0)

Returns a month’s calendar in a multi-line string using the @ref{2b3c,,formatmonth()}
of the @ref{1a3e,,TextCalendar} class.
@end deffn

@geindex prcal() (στη μονάδα calendar)
@anchor{library/calendar calendar prcal}@anchor{2b59}
@deffn {Συνάρτηση} calendar.prcal (year, w=0, l=0, c=6, m=3)

Prints the calendar for an entire year as returned by  @ref{15,,calendar()}.
@end deffn

@geindex calendar() (στη μονάδα calendar)
@anchor{library/calendar calendar calendar}@anchor{2b5a}
@deffn {Συνάρτηση} 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{2b3f,,formatyear()} of the @ref{1a3e,,TextCalendar} class.
@end deffn

@geindex timegm() (στη μονάδα calendar)
@anchor{library/calendar calendar timegm}@anchor{2b5b}
@deffn {Συνάρτηση} calendar.timegm (tuple)

An unrelated but handy function that takes a time tuple such as returned by
the @ref{1569,,gmtime()} function in the @ref{f7,,time} module, and returns the
corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX
encoding.  In fact, @code{time.gmtime()} and @code{timegm()} are each other’s
inverse.
@end deffn

The @code{calendar} module exports the following data attributes:

@geindex day_name (στη μονάδα calendar)
@anchor{library/calendar calendar day_name}@anchor{2b5c}
@deffn {Δεδομένα} 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 (στη μονάδα calendar)
@anchor{library/calendar calendar day_abbr}@anchor{2b5d}
@deffn {Δεδομένα} 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 (στη μονάδα calendar)
@geindex TUESDAY (στη μονάδα calendar)
@geindex WEDNESDAY (στη μονάδα calendar)
@geindex THURSDAY (στη μονάδα calendar)
@geindex FRIDAY (στη μονάδα calendar)
@geindex SATURDAY (στη μονάδα calendar)
@geindex SUNDAY (στη μονάδα calendar)
@anchor{library/calendar calendar MONDAY}@anchor{2b29}
@deffn {Δεδομένα} calendar.MONDAY
@anchor{library/calendar calendar TUESDAY}@anchor{2b4c}
@deffnx {Δεδομένα} calendar.TUESDAY
@anchor{library/calendar calendar WEDNESDAY}@anchor{2b4d}
@deffnx {Δεδομένα} calendar.WEDNESDAY
@anchor{library/calendar calendar THURSDAY}@anchor{2b4e}
@deffnx {Δεδομένα} calendar.THURSDAY
@anchor{library/calendar calendar FRIDAY}@anchor{2b4f}
@deffnx {Δεδομένα} calendar.FRIDAY
@anchor{library/calendar calendar SATURDAY}@anchor{2b50}
@deffnx {Δεδομένα} calendar.SATURDAY
@anchor{library/calendar calendar SUNDAY}@anchor{2b2a}
@deffnx {Δεδομένα} calendar.SUNDAY

Aliases for the days of the week,
where @code{MONDAY} is @code{0} and @code{SUNDAY} is @code{6}.


Added in version 3.12.

@end deffn

@geindex Day (κλάση σε calendar)
@anchor{library/calendar calendar Day}@anchor{894}
@deffn {Κλάση} calendar.Day

Enumeration defining days of the week as integer constants.
The members of this enumeration are exported to the module scope as
@ref{2b29,,MONDAY} through @ref{2b2a,,SUNDAY}.


Added in version 3.12.

@end deffn

@geindex month_name (στη μονάδα calendar)
@anchor{library/calendar calendar month_name}@anchor{2b5e}
@deffn {Δεδομένα} 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

@cartouche
@quotation Προσοχή 
In locales with alternative month names forms, the @code{month_name} sequence
may not be suitable when a month name stands by itself and not as part of a date.
For instance, in Greek and in many Slavic and Baltic languages, @code{month_name}
will produce the month in genitive case. Use @ref{1a3f,,standalone_month_name} for a form
suitable for standalone use.
@end quotation
@end cartouche
@end deffn

@geindex month_abbr (στη μονάδα calendar)
@anchor{library/calendar calendar month_abbr}@anchor{2b5f}
@deffn {Δεδομένα} 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

@cartouche
@quotation Προσοχή 
In locales with alternative month names forms, the @code{month_abbr} sequence
may not be suitable when a month name stands by itself and not as part of a date.
Use @ref{1a40,,standalone_month_abbr} for a form suitable for standalone use.
@end quotation
@end cartouche
@end deffn

@geindex standalone_month_name (στη μονάδα calendar)
@anchor{library/calendar calendar standalone_month_name}@anchor{1a3f}
@deffn {Δεδομένα} calendar.standalone_month_name

A sequence that represents the months of the year in the current locale
in the standalone form if the locale provides one. Else it is equivalent
to @ref{2b5e,,month_name}.


Added in version 3.15.

@end deffn

@geindex standalone_month_abbr (στη μονάδα calendar)
@anchor{library/calendar calendar standalone_month_abbr}@anchor{1a40}
@deffn {Δεδομένα} calendar.standalone_month_abbr

A sequence that represents the abbreviated months of the year in the current
locale in the standalone form if the locale provides one. Else it is
equivalent to @ref{2b5f,,month_abbr}.


Added in version 3.15.

@end deffn

@geindex JANUARY (στη μονάδα calendar)
@geindex FEBRUARY (στη μονάδα calendar)
@geindex MARCH (στη μονάδα calendar)
@geindex APRIL (στη μονάδα calendar)
@geindex MAY (στη μονάδα calendar)
@geindex JUNE (στη μονάδα calendar)
@geindex JULY (στη μονάδα calendar)
@geindex AUGUST (στη μονάδα calendar)
@geindex SEPTEMBER (στη μονάδα calendar)
@geindex OCTOBER (στη μονάδα calendar)
@geindex NOVEMBER (στη μονάδα calendar)
@geindex DECEMBER (στη μονάδα calendar)
@anchor{library/calendar calendar JANUARY}@anchor{329}
@deffn {Δεδομένα} calendar.JANUARY
@anchor{library/calendar calendar FEBRUARY}@anchor{32a}
@deffnx {Δεδομένα} calendar.FEBRUARY
@anchor{library/calendar calendar MARCH}@anchor{2b60}
@deffnx {Δεδομένα} calendar.MARCH
@anchor{library/calendar calendar APRIL}@anchor{2b61}
@deffnx {Δεδομένα} calendar.APRIL
@anchor{library/calendar calendar MAY}@anchor{2b62}
@deffnx {Δεδομένα} calendar.MAY
@anchor{library/calendar calendar JUNE}@anchor{2b63}
@deffnx {Δεδομένα} calendar.JUNE
@anchor{library/calendar calendar JULY}@anchor{2b64}
@deffnx {Δεδομένα} calendar.JULY
@anchor{library/calendar calendar AUGUST}@anchor{2b65}
@deffnx {Δεδομένα} calendar.AUGUST
@anchor{library/calendar calendar SEPTEMBER}@anchor{2b66}
@deffnx {Δεδομένα} calendar.SEPTEMBER
@anchor{library/calendar calendar OCTOBER}@anchor{2b67}
@deffnx {Δεδομένα} calendar.OCTOBER
@anchor{library/calendar calendar NOVEMBER}@anchor{2b68}
@deffnx {Δεδομένα} calendar.NOVEMBER
@anchor{library/calendar calendar DECEMBER}@anchor{2b69}
@deffnx {Δεδομένα} calendar.DECEMBER

Aliases for the months of the year,
where @code{JANUARY} is @code{1} and @code{DECEMBER} is @code{12}.


Added in version 3.12.

@end deffn

@geindex Month (κλάση σε calendar)
@anchor{library/calendar calendar Month}@anchor{893}
@deffn {Κλάση} calendar.Month

Enumeration defining months of the year as integer constants.
The members of this enumeration are exported to the module scope as
@ref{329,,JANUARY} through @ref{2b69,,DECEMBER}.


Added in version 3.12.

@end deffn

The @code{calendar} module defines the following exceptions:

@geindex IllegalMonthError
@anchor{library/calendar calendar IllegalMonthError}@anchor{1915}
@deffn {Εξαίρεση} calendar.IllegalMonthError (month)

A subclass of @ref{277,,ValueError} and @ref{18d7,,IndexError},
raised when the given month number is outside of the range 1-12 (inclusive).


Άλλαξε στην έκδοση 3.12: @code{IllegalMonthError} is now also a subclass of
@ref{277,,ValueError}. New code should avoid catching
@ref{18d7,,IndexError}.


@geindex month (ιδιότητα της calendar.IllegalMonthError)
@anchor{library/calendar calendar IllegalMonthError month}@anchor{2b6a}
@deffn {Ιδιότητα} month

The invalid month number.
@end deffn
@end deffn

@geindex IllegalWeekdayError
@anchor{library/calendar calendar IllegalWeekdayError}@anchor{2b6b}
@deffn {Εξαίρεση} calendar.IllegalWeekdayError (weekday)

A subclass of @ref{277,,ValueError},
raised when the given weekday number is outside of the range 0-6 (inclusive).

@geindex weekday (ιδιότητα της calendar.IllegalWeekdayError)
@anchor{library/calendar calendar IllegalWeekdayError weekday}@anchor{2b6c}
@deffn {Ιδιότητα} weekday

The invalid weekday number.
@end deffn
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{33,,datetime}

Object-oriented interface to dates and times with similar functionality to the
@ref{f7,,time} module.

@item Module @ref{f7,,time}

Low-level time related functions.
@end table


@menu
* Command-line usage:: 

@end menu

@node Command-line usage,,,calendar — General calendar-related functions
@anchor{library/calendar calendar-cli}@anchor{201}@anchor{library/calendar command-line-usage}@anchor{2b6d}
@subsubsection Command-line usage



Added in version 2.5.


The @code{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

The following options are accepted:

@geindex calendar command line option; --help
@geindex calendar command line option; -h
@anchor{library/calendar cmdoption-calendar-help}@anchor{2b6e}@anchor{library/calendar cmdoption-calendar-h}@anchor{2b6f}
@deffn {Option} @w{-}@w{-}help, @w{-}h

Show the help message and exit.
@end deffn

@geindex calendar command line option; --locale
@geindex calendar command line option; -L
@anchor{library/calendar cmdoption-calendar-locale}@anchor{2b70}@anchor{library/calendar cmdoption-calendar-L}@anchor{2b71}
@deffn {Option} @w{-}@w{-}locale LOCALE, @w{-}L LOCALE

The locale to use for month and weekday names.
Defaults to English.
@end deffn

@geindex calendar command line option; --encoding
@geindex calendar command line option; -e
@anchor{library/calendar cmdoption-calendar-encoding}@anchor{2b72}@anchor{library/calendar cmdoption-calendar-e}@anchor{2b73}
@deffn {Option} @w{-}@w{-}encoding ENCODING, @w{-}e ENCODING

The encoding to use for output.
@ref{2b72,,--encoding} is required if @ref{2b70,,--locale} is set.
@end deffn

@geindex calendar command line option; --type
@geindex calendar command line option; -t
@anchor{library/calendar cmdoption-calendar-type}@anchor{2b74}@anchor{library/calendar cmdoption-calendar-t}@anchor{2b75}
@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 calendar command line option; --first-weekday
@geindex calendar command line option; -f
@anchor{library/calendar cmdoption-calendar-first-weekday}@anchor{2b76}@anchor{library/calendar cmdoption-calendar-f}@anchor{2b77}
@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.


Added in version 3.13.

@end deffn

@geindex calendar command line option; year
@anchor{library/calendar cmdoption-calendar-arg-year}@anchor{2b78}
@deffn {Option} year

The year to print the calendar for.
Defaults to the current year.
@end deffn

@geindex calendar command line option; month
@anchor{library/calendar cmdoption-calendar-arg-month}@anchor{2b79}
@deffn {Option} month

The month of the specified @ref{2b78,,year} to print the calendar for.
Must be a number between 1 and 12.
Defaults to printing a calendar for the full year.
@end deffn

`Text-mode options:'

@geindex calendar command line option; --width
@geindex calendar command line option; -w
@anchor{library/calendar cmdoption-calendar-width}@anchor{2b7a}@anchor{library/calendar cmdoption-calendar-w}@anchor{2b7b}
@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 calendar command line option; --lines
@geindex calendar command line option; -l
@anchor{library/calendar cmdoption-calendar-lines}@anchor{2b7c}@anchor{library/calendar cmdoption-calendar-l}@anchor{2b7d}
@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 calendar command line option; --spacing
@geindex calendar command line option; -s
@anchor{library/calendar cmdoption-calendar-spacing}@anchor{2b7e}@anchor{library/calendar cmdoption-calendar-s}@anchor{2b7f}
@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 calendar command line option; --months
@geindex calendar command line option; -m
@anchor{library/calendar cmdoption-calendar-months}@anchor{2b80}@anchor{library/calendar cmdoption-calendar-m}@anchor{2b81}
@deffn {Option} @w{-}@w{-}months MONTHS, @w{-}m MONTHS

The number of months printed per row.
Defaults to 3.
@end deffn


Άλλαξε στην έκδοση 3.14: By default, today’s date is highlighted in color and can be
@ref{1af,,controlled using environment variables}.



Άλλαξε στην έκδοση 3.15: By default, the month is now also highlighted in color, and
the days of the week are also in color. This behavior can be
@ref{1af,,controlled using environment variables}.


`HTML-mode options:'

@geindex calendar command line option; --css
@geindex calendar command line option; -c
@anchor{library/calendar cmdoption-calendar-css}@anchor{2b82}@anchor{library/calendar cmdoption-calendar-c}@anchor{2b83}
@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node collections — Container datatypes,collections abc — Αφηρημένες Βασικές Κλάσεις για Containers,calendar — General calendar-related functions,Data Types
@anchor{library/collections doc}@anchor{2b84}@anchor{library/collections collections-container-datatypes}@anchor{2b85}@anchor{library/collections module-collections}@anchor{1e}@anchor{library/collections translation-repo}@anchor{2b86}
@subsection @code{collections} — Container datatypes


@geindex module; collections

`Source code:' Lib/collections/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/collections/__init__.py}

@c from collections import *
@c import itertools
@c __name__ = '<doctest>'


__________________________________________________________________


This module implements specialized container datatypes providing alternatives to
Python’s general purpose built-in containers, @ref{188,,dict}, @ref{4d9,,list},
@ref{42b,,set}, and @ref{1ce,,tuple}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{1cf,,namedtuple()}

@tab

factory function for creating tuple subclasses with named fields

@item

@ref{9d6,,deque}

@tab

list-like container with fast appends and pops on either end

@item

@ref{fdb,,ChainMap}

@tab

dict-like class for creating a single view of multiple mappings

@item

@ref{204,,Counter}

@tab

dict subclass for counting @ref{183,,hashable} objects

@item

@ref{9d5,,OrderedDict}

@tab

dict subclass that remembers the order entries were added

@item

@ref{1565,,defaultdict}

@tab

dict subclass that calls a factory function to supply missing values

@item

@ref{192d,,UserDict}

@tab

wrapper around dictionary objects for easier dict subclassing

@item

@ref{1886,,UserList}

@tab

wrapper around list objects for easier list subclassing

@item

@ref{118c,,UserString}

@tab

wrapper around string objects for easier string subclassing

@end multitable


@menu
* ChainMap objects:: 
* Counter objects:: 
* deque objects:: 
* defaultdict objects:: 
* namedtuple() Factory Function for Tuples with Named Fields: namedtuple Factory Function for Tuples with Named Fields. 
* OrderedDict objects:: 
* UserDict objects:: 
* UserList objects:: 
* UserString objects:: 

@end menu

@node ChainMap objects,Counter objects,,collections — Container datatypes
@anchor{library/collections chainmap-objects}@anchor{2b87}
@subsubsection @code{ChainMap} objects



Added in version 3.3.


A @ref{fdb,,ChainMap} class is provided for quickly linking a number of mappings
so they can be treated as a single unit.  It is often much faster than creating
a new dictionary and running multiple @ref{1807,,update()} calls.

The class can be used to simulate nested scopes and is useful in templating.

@geindex ChainMap (κλάση σε collections)
@anchor{library/collections collections ChainMap}@anchor{fdb}
@deffn {Κλάση} collections.ChainMap (*maps)

A @code{ChainMap} groups multiple dicts or other mappings together to
create a single, updateable view.  If no `maps' are specified, a single empty
dictionary is provided so that a new chain always has at least one mapping.

The underlying mappings are stored in a list.  That list is public and can
be accessed or updated using the `maps' attribute.  There is no other state.

Lookups search the underlying mappings successively until a key is found.  In
contrast, writes, updates, and deletions only operate on the first mapping.

A @code{ChainMap} incorporates the underlying mappings by reference.  So, if
one of the underlying mappings gets updated, those changes will be reflected
in @code{ChainMap}.

All of the usual dictionary methods are supported.  In addition, there is a
`maps' attribute, a method for creating new subcontexts, and a property for
accessing all but the first mapping:

@geindex maps (ιδιότητα της collections.ChainMap)
@anchor{library/collections collections ChainMap maps}@anchor{2b88}
@deffn {Ιδιότητα} maps

A user updateable list of mappings.  The list is ordered from
first-searched to last-searched.  It is the only stored state and can
be modified to change which mappings are searched.  The list should
always contain at least one mapping.
@end deffn

@geindex new_child() (μέθοδος της collections.ChainMap)
@anchor{library/collections collections ChainMap new_child}@anchor{12d0}
@deffn {Μέθοδος} new_child (m=None, **kwargs)

Returns a new @code{ChainMap} containing a new map followed by
all of the maps in the current instance.  If @code{m} is specified,
it becomes the new map at the front of the list of mappings; if not
specified, an empty dict is used, so that a call to @code{d.new_child()}
is equivalent to: @code{ChainMap(@{@}, *d.maps)}. If any keyword arguments
are specified, they update passed map or new empty dict. This method
is used for creating subcontexts that can be updated without altering
values in any of the parent mappings.


Άλλαξε στην έκδοση 3.4: The optional @code{m} parameter was added.



Άλλαξε στην έκδοση 3.10: Keyword arguments support was added.

@end deffn

@geindex parents (ιδιότητα της collections.ChainMap)
@anchor{library/collections collections ChainMap parents}@anchor{2b89}
@deffn {Ιδιότητα} parents

Property returning a new @code{ChainMap} containing all of the maps in
the current instance except the first one.  This is useful for skipping
the first map in the search.  Use cases are similar to those for the
@ref{164c,,nonlocal} keyword used in @ref{2581,,nested scopes}.  The use cases also parallel those for the built-in
@ref{443,,super()} function.  A reference to @code{d.parents} is equivalent to:
@code{ChainMap(*d.maps[1:])}.
@end deffn

Note, the iteration order of a @code{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

This gives the same ordering as a series of @ref{1807,,dict.update()} calls
starting with the last mapping:

@example
>>> combined = baseline.copy()
>>> combined.update(adjustments)
>>> list(combined)
['music', 'art', 'opera']
@end example


Άλλαξε στην έκδοση 3.9: Added support for @code{|} and @code{|=} operators, specified in 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}.

@end deffn


@subsubheading Δείτε επίσης



@itemize *

@item 
The MultiContext class@footnote{https://github.com/enthought/codetools/blob/4.0.0/codetools/contexts/multi_context.py}
in the Enthought CodeTools package@footnote{https://github.com/enthought/codetools} has options to support
writing to any mapping in the chain.

@item 
Django’s Context class@footnote{https://github.com/django/django/blob/main/django/template/context.py}
for templating is a read-only chain of mappings.  It also features
pushing and popping of contexts similar to the
@ref{12d0,,new_child()} method and the
@ref{2b89,,parents} property.

@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 
A greatly simplified read-only version of Chainmap@footnote{https://code.activestate.com/recipes/305268/}.
@end itemize


@menu
* ChainMap Examples and Recipes:: 

@end menu

@node ChainMap Examples and Recipes,,,ChainMap objects
@anchor{library/collections chainmap-examples-and-recipes}@anchor{2b8a}
@subsubsection @code{ChainMap} Examples and Recipes


This section shows various approaches to working with chained maps.

Example of simulating Python’s internal lookup chain:

@example
import builtins
pylookup = ChainMap(locals(), globals(), vars(builtins))
@end example

Example of letting user specified command-line arguments take precedence over
environment variables which in turn take precedence over default values:

@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

Example patterns for using the @ref{fdb,,ChainMap} class to simulate nested
contexts:

@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

The @ref{fdb,,ChainMap} class only makes updates (writes and deletions) to the
first mapping in the chain while lookups will search the full chain.  However,
if deep writes and deletions are desired, it is easy to make a subclass that
updates keys found deeper in the chain:

@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 Counter objects,deque objects,ChainMap objects,collections — Container datatypes
@anchor{library/collections counter-objects}@anchor{2b8b}
@subsubsection @code{Counter} objects


A counter tool is provided to support convenient and rapid tallies.
For example:

@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 (κλάση σε collections)
@anchor{library/collections collections Counter}@anchor{204}
@deffn {Κλάση} collections.Counter (**kwargs)

@deffnx {Κλάση} collections.Counter (iterable, /, **kwargs)

@deffnx {Κλάση} collections.Counter (mapping, /, **kwargs)

A @code{Counter} is a @ref{188,,dict} subclass for counting @ref{183,,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 @code{Counter}
class is similar to bags or multisets in other languages.

Elements are counted from an `iterable' or initialized from another
`mapping' (or counter):

@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

Counter objects have a dictionary interface except that they return a zero
count for missing items instead of raising a @ref{7df,,KeyError}:

@example
>>> c = Counter(['eggs', 'ham'])
>>> c['bacon']                              # count of a missing element is zero
0
@end example

Setting a count to zero does not remove an element from a counter.
Use @code{del} to remove it entirely:

@example
>>> c['sausage'] = 0                        # counter entry with a zero count
>>> del c['sausage']                        # del actually removes the entry
@end example


Added in version 3.1.



Άλλαξε στην έκδοση 3.7: As a @ref{188,,dict} subclass, @code{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() (μέθοδος της collections.Counter)
@anchor{library/collections collections Counter elements}@anchor{16a8}
@deffn {Μέθοδος} elements ()

Return an iterator over elements repeating each as many times as its
count.  Elements are returned in the order first encountered. If an
element’s count is less than one, @code{elements()} will ignore it.

@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() (μέθοδος της collections.Counter)
@anchor{library/collections collections Counter most_common}@anchor{16a7}
@deffn {Μέθοδος} most_common (n=None)

Return a list of the `n' most common elements and their counts from the
most common to the least.  If `n' is omitted or @code{None},
@code{most_common()} returns `all' elements in the counter.
Elements with equal counts are ordered in the order first encountered:

@example
>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]
@end example
@end deffn

@geindex subtract() (μέθοδος της collections.Counter)
@anchor{library/collections collections Counter subtract}@anchor{1587}
@deffn {Μέθοδος} subtract (**kwargs)

@deffnx {Μέθοδος} subtract (iterable, /, **kwargs)

@deffnx {Μέθοδος} subtract (mapping, /, **kwargs)

Elements are subtracted from an `iterable' or from another `mapping'
(or counter).  Like @ref{1807,,dict.update()} but subtracts counts instead
of replacing them.  Both inputs and outputs may be zero or negative.

@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


Added in version 3.2.

@end deffn

@geindex total() (μέθοδος της collections.Counter)
@anchor{library/collections collections Counter total}@anchor{2b8c}
@deffn {Μέθοδος} total ()

Compute the sum of the counts.

@example
>>> c = Counter(a=10, b=5, c=0)
>>> c.total()
15
@end example


Added in version 3.10.

@end deffn

The usual dictionary methods are available for @code{Counter} objects
except for these two which work differently for counters:

@geindex fromkeys() (μέθοδος της collections.Counter)
@anchor{library/collections collections Counter fromkeys}@anchor{2b8d}
@deffn {Μέθοδος} fromkeys (iterable)

This class method is not implemented for @code{Counter} objects.
@end deffn

@geindex update() (μέθοδος της collections.Counter)
@anchor{library/collections collections Counter update}@anchor{197f}
@deffn {Μέθοδος} update (**kwargs)

@deffnx {Μέθοδος} update (iterable, /, **kwargs)

@deffnx {Μέθοδος} update (mapping, /, **kwargs)

Elements are counted from an `iterable' or added-in from another
`mapping' (or counter).  Like @ref{1807,,dict.update()} but adds counts
instead of replacing them.  Also, the `iterable' is expected to be a
sequence of elements, not a sequence of @code{(key, value)} pairs.
@end deffn
@end deffn

Counters support rich comparison operators for equality, subset, and
superset relationships: @code{==}, @code{!=}, @code{<}, @code{<=}, @code{>}, @code{>=}.
All of those tests treat missing elements as having zero counts so that
@code{Counter(a=1) == Counter(a=1, b=0)} returns true.


Άλλαξε στην έκδοση 3.10: Rich comparison operations were added.



Άλλαξε στην έκδοση 3.10: In equality tests, missing elements are treated as having zero counts.
Formerly, @code{Counter(a=3)} and @code{Counter(a=3, b=0)} were considered
distinct.


Common patterns for working with @ref{204,,Counter} objects:

@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{204,,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.  Symmetric difference returns the difference
between the maximum and minimum of the 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 below.

@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                       # max(c[x], d[x]) - min(c[x], d[x])
Counter(@{'a': 2, 'b': 1@})
>>> c == d                      # equality:  c[x] == d[x]
False
>>> c <= d                      # inclusion:  c[x] <= d[x]
False
@end example

Unary addition and subtraction are shortcuts for adding an empty counter
or subtracting from an empty counter.

@example
>>> c = Counter(a=2, b=-4)
>>> +c
Counter(@{'a': 2@})
>>> -c
Counter(@{'b': 4@})
@end example


Added in version 3.3: Added support for unary plus, unary minus, and in-place multiset operations.



Added in version 3.15: Added support for the symmetric difference multiset operation, @code{c ^ d}.


@cartouche
@quotation Σημείωση 
Counters were primarily designed to work with positive integers to represent
running counts; however, care was taken to not unnecessarily preclude use
cases needing other types or negative values.  To help with those use cases,
this section documents the minimum range and type restrictions.


@itemize *

@item 
The @ref{204,,Counter} class itself is a dictionary subclass with no
restrictions on its keys and values.  The values are intended to be numbers
representing counts, but you `could' store anything in the value field.

@item 
The @ref{16a7,,most_common()} method requires only that the values be orderable.

@item 
For in-place operations such as @code{c[key] += 1}, the value type need only
support addition and subtraction.  So fractions, floats, and decimals would
work and negative values are supported.  The same is also true for
@ref{197f,,update()} and @ref{1587,,subtract()} which allow negative and zero values
for both inputs and outputs.

@item 
The multiset methods are designed only for use cases with positive values.
The inputs may be negative or zero, but only outputs with positive values
are created.  There are no type restrictions, but the value type needs to
support addition, subtraction, and comparison.

@item 
The @ref{16a8,,elements()} method requires integer counts.  It ignores zero and
negative counts.
@end itemize
@end quotation
@end cartouche


@subsubheading Δείτε επίσης



@itemize *

@item 
Bag class@footnote{https://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html}
in Smalltalk.

@item 
Wikipedia entry for Multisets@footnote{https://en.wikipedia.org/wiki/Multiset}.

@item 
C++ multisets@footnote{http://www.java2s.com/Tutorial/Cpp/0380__set-multiset/Catalog0380__set-multiset.htm}
tutorial with examples.

@item 
For mathematical operations on multisets and their use cases, see
`Knuth, Donald. The Art of Computer Programming Volume II,
Section 4.6.3, Exercise 19'.

@item 
To enumerate all distinct multisets of a given size over a given set of
elements, see @ref{1626,,itertools.combinations_with_replacement()}:

@example
map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC
@end example
@end itemize


@node deque objects,defaultdict objects,Counter objects,collections — Container datatypes
@anchor{library/collections deque-objects}@anchor{2b8e}
@subsubsection @code{deque} objects


@geindex deque (κλάση σε collections)
@anchor{library/collections collections deque}@anchor{9d6}
@deffn {Κλάση} collections.deque ([iterable[, maxlen]])

Returns a new deque object initialized left-to-right (using @ref{2b8f,,append()}) with
data from `iterable'.  If `iterable' is not specified, the new deque is empty.

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{4d9,,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.

If `maxlen' is not specified or is @code{None}, deques may grow to an
arbitrary length.  Otherwise, the deque is bounded to the specified maximum
length.  Once a bounded length deque is full, when new items are added, a
corresponding number of items are discarded from the opposite end.  Bounded
length deques provide functionality similar to the @code{tail} filter in
Unix. They are also useful for tracking transactions and other pools of data
where only the most recent activity is of interest.

Deque objects support the following methods:

@geindex append() (μέθοδος της collections.deque)
@anchor{library/collections collections deque append}@anchor{2b8f}
@deffn {Μέθοδος} append (item, /)

Add `item' to the right side of the deque.
@end deffn

@geindex appendleft() (μέθοδος της collections.deque)
@anchor{library/collections collections deque appendleft}@anchor{2b90}
@deffn {Μέθοδος} appendleft (item, /)

Add `item' to the left side of the deque.
@end deffn

@geindex clear() (μέθοδος της collections.deque)
@anchor{library/collections collections deque clear}@anchor{2b91}
@deffn {Μέθοδος} clear ()

Remove all elements from the deque leaving it with length 0.
@end deffn

@geindex copy() (μέθοδος της collections.deque)
@anchor{library/collections collections deque copy}@anchor{118b}
@deffn {Μέθοδος} copy ()

Create a shallow copy of the deque.


Added in version 3.5.

@end deffn

@geindex count() (μέθοδος της collections.deque)
@anchor{library/collections collections deque count}@anchor{1589}
@deffn {Μέθοδος} count (value, /)

Count the number of deque elements equal to `value'.


Added in version 3.2.

@end deffn

@geindex extend() (μέθοδος της collections.deque)
@anchor{library/collections collections deque extend}@anchor{2b92}
@deffn {Μέθοδος} extend (iterable, /)

Extend the right side of the deque by appending elements from the iterable
argument.
@end deffn

@geindex extendleft() (μέθοδος της collections.deque)
@anchor{library/collections collections deque extendleft}@anchor{2b93}
@deffn {Μέθοδος} extendleft (iterable, /)

Extend the left side of the deque by appending elements from `iterable'.
Note, the series of left appends results in reversing the order of
elements in the iterable argument.
@end deffn

@geindex index() (μέθοδος της collections.deque)
@anchor{library/collections collections deque index}@anchor{1189}
@deffn {Μέθοδος} index (value[, start[, stop]])

Return the position of `value' in the deque (at or after index `start'
and before index `stop').  Returns the first match or raises
@ref{277,,ValueError} if not found.


Added in version 3.5.

@end deffn

@geindex insert() (μέθοδος της collections.deque)
@anchor{library/collections collections deque insert}@anchor{118a}
@deffn {Μέθοδος} insert (index, value, /)

Insert `value' into the deque at position `index'.

If the insertion would cause a bounded deque to grow beyond `maxlen',
an @ref{18d7,,IndexError} is raised.


Added in version 3.5.

@end deffn

@geindex pop() (μέθοδος της collections.deque)
@anchor{library/collections collections deque pop}@anchor{2b94}
@deffn {Μέθοδος} pop ()

Remove and return an element from the right side of the deque. If no
elements are present, raises an @ref{18d7,,IndexError}.
@end deffn

@geindex popleft() (μέθοδος της collections.deque)
@anchor{library/collections collections deque popleft}@anchor{2b95}
@deffn {Μέθοδος} popleft ()

Remove and return an element from the left side of the deque. If no
elements are present, raises an @ref{18d7,,IndexError}.
@end deffn

@geindex remove() (μέθοδος της collections.deque)
@anchor{library/collections collections deque remove}@anchor{1ec5}
@deffn {Μέθοδος} remove (value, /)

Remove the first occurrence of `value'.  If not found, raises a
@ref{277,,ValueError}.
@end deffn

@geindex reverse() (μέθοδος της collections.deque)
@anchor{library/collections collections deque reverse}@anchor{158a}
@deffn {Μέθοδος} reverse ()

Reverse the elements of the deque in-place and then return @code{None}.


Added in version 3.2.

@end deffn

@geindex rotate() (μέθοδος της collections.deque)
@anchor{library/collections collections deque rotate}@anchor{1e86}
@deffn {Μέθοδος} rotate (n=1, /)

Rotate the deque `n' steps to the right.  If `n' is negative, rotate
to the left.

When the deque is not empty, rotating one step to the right is equivalent
to @code{d.appendleft(d.pop())}, and rotating one step to the left is
equivalent to @code{d.append(d.popleft())}.
@end deffn

Deque objects also provide one read-only attribute:

@geindex maxlen (ιδιότητα της collections.deque)
@anchor{library/collections collections deque maxlen}@anchor{16a9}
@deffn {Ιδιότητα} maxlen

Maximum size of a deque or @code{None} if unbounded.


Added in 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{323,,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.

Starting in version 3.5, deques support @code{__add__()}, @code{__mul__()},
and @code{__imul__()}.

Example:

@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
* deque Recipes:: 

@end menu

@node deque Recipes,,,deque objects
@anchor{library/collections deque-recipes}@anchor{2b96}
@subsubsection @code{deque} Recipes


This section shows various approaches to working with deques.

Bounded length deques provide functionality similar to the @code{tail} filter
in 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

Another approach to using deques is to maintain a sequence of recently
added elements by appending to the right and popping to the left:

@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

A round-robin scheduler@footnote{https://en.wikipedia.org/wiki/Round-robin_scheduling} can be implemented with
input iterators stored in a @ref{9d6,,deque}.  Values are yielded from the active
iterator in position zero.  If that iterator is exhausted, it can be removed
with @ref{2b95,,popleft()}; otherwise, it can be cycled back to the end with
the @ref{1e86,,rotate()} method:

@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

The @ref{1e86,,rotate()} method provides a way to implement @ref{9d6,,deque} slicing and
deletion.  For example, a pure Python implementation of @code{del d[n]} relies on
the @code{rotate()} method to position elements to be popped:

@example
def delete_nth(d, n):
    d.rotate(-n)
    d.popleft()
    d.rotate(n)
@end example

To implement @ref{9d6,,deque} slicing, use a similar approach applying
@ref{1e86,,rotate()} to bring a target element to the left side of the deque. Remove
old entries with @ref{2b95,,popleft()}, add new entries with @ref{2b92,,extend()}, and then
reverse the rotation.
With minor variations on that approach, it is easy to implement Forth style
stack manipulations such as @code{dup}, @code{drop}, @code{swap}, @code{over}, @code{pick},
@code{rot}, and @code{roll}.

@node defaultdict objects,namedtuple Factory Function for Tuples with Named Fields,deque objects,collections — Container datatypes
@anchor{library/collections defaultdict-objects}@anchor{2b97}
@subsubsection @code{defaultdict} objects


@geindex defaultdict (κλάση σε collections)
@anchor{library/collections collections defaultdict}@anchor{1565}
@deffn {Κλάση} collections.defaultdict (default_factory=None, /, **kwargs)

@deffnx {Κλάση} collections.defaultdict (default_factory, mapping, /, **kwargs)

@deffnx {Κλάση} collections.defaultdict (default_factory, iterable, /, **kwargs)

Return a new dictionary-like object.  @code{defaultdict} is a subclass of the
built-in @ref{188,,dict} class.  It overrides one method and adds one writable
instance variable.  The remaining functionality is the same as for the
@code{dict} class and is not documented here.

The first argument provides the initial value for the @ref{2b98,,default_factory}
attribute; it defaults to @code{None}. All remaining arguments are treated the same
as if they were passed to the @ref{188,,dict} constructor, including keyword
arguments.

@code{defaultdict} objects support the following method in addition to the
standard @ref{188,,dict} operations:

@geindex __missing__() (μέθοδος της collections.defaultdict)
@anchor{library/collections collections defaultdict __missing__}@anchor{2b99}
@deffn {Μέθοδος} __missing__ (key, /)

If the @ref{2b98,,default_factory} attribute is @code{None}, this raises a
@ref{7df,,KeyError} exception with the `key' as argument.

If @ref{2b98,,default_factory} is not @code{None}, it is called without arguments
to provide a default value for the given `key', this value is inserted in
the dictionary for the `key', and returned.

If calling @ref{2b98,,default_factory} raises an exception this exception is
propagated unchanged.

This method is called by the @ref{787,,__getitem__()} method of the
@ref{188,,dict} class when the requested key is not found; whatever it
returns or raises is then returned or raised by @code{__getitem__()}.

Note that @code{__missing__()} is `not' called for any operations besides
@ref{787,,__getitem__()}. This means that @ref{2223,,get()} will, like
normal dictionaries, return @code{None} as a default rather than using
@ref{2b98,,default_factory}.
@end deffn

@code{defaultdict} objects support the following instance variable:

@geindex default_factory (ιδιότητα της collections.defaultdict)
@anchor{library/collections collections defaultdict default_factory}@anchor{2b98}
@deffn {Ιδιότητα} default_factory

This attribute is used by the @ref{2b99,,__missing__()} method;
it is initialized from the first argument to the constructor, if present,
or to @code{None}, if absent.
@end deffn


Άλλαξε στην έκδοση 3.9: Added merge (@code{|}) and update (@code{|=}) operators, specified in
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}.

@end deffn

@menu
* defaultdict Examples:: 

@end menu

@node defaultdict Examples,,,defaultdict objects
@anchor{library/collections defaultdict-examples}@anchor{2b9a}
@subsubsection @code{defaultdict} Examples


Using @ref{4d9,,list} as the @ref{2b98,,default_factory}, it is easy to group a
sequence of key-value pairs into a dictionary of lists:

@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{2b98,,default_factory}
function which returns an empty @ref{4d9,,list}.  The @ref{aba,,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{1421,,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

Setting the @ref{2b98,,default_factory} to @ref{326,,int} makes the
@ref{1565,,defaultdict} useful for counting (like a bag or multiset in other
languages):

@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

When a letter is first encountered, it is missing from the mapping, so the
@ref{2b98,,default_factory} function calls @ref{326,,int()} to supply a default count of
zero.  The increment operation then builds up the count for each letter.

The function @ref{326,,int()} which always returns zero is just a special case of
constant functions.  A faster and more flexible way to create constant functions
is to use a lambda function which can supply any constant value (not just
zero):

@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

Setting the @ref{2b98,,default_factory} to @ref{42b,,set} makes the
@ref{1565,,defaultdict} useful for building a dictionary of sets:

@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 Factory Function for Tuples with Named Fields,OrderedDict objects,defaultdict objects,collections — Container datatypes
@anchor{library/collections namedtuple-factory-function-for-tuples-with-named-fields}@anchor{2b9b}
@subsubsection @code{namedtuple()} Factory Function for Tuples with Named Fields


Named tuples assign meaning to each position in a tuple and allow for more readable,
self-documenting code.  They can be used wherever regular tuples are used, and
they add the ability to access fields by name instead of position index.

@geindex namedtuple() (στη μονάδα collections)
@anchor{library/collections collections namedtuple}@anchor{1cf}
@deffn {Συνάρτηση} collections.namedtuple (typename, field_names, *, rename=False, defaults=None, module=None)

Returns a new tuple subclass named `typename'.  The new subclass is used to
create tuple-like objects that have fields accessible by attribute lookup as
well as being indexable and iterable.  Instances of the subclass also have a
helpful docstring (with `typename' and `field_names') and a helpful
@ref{1bc,,__repr__()} method which lists the tuple contents in a @code{name=value}
format.

The `field_names' are a sequence of strings such as @code{['x', 'y']}.
Alternatively, `field_names' can be a single string with each fieldname
separated by whitespace and/or commas, for example @code{'x y'} or @code{'x, y'}.

Any valid Python identifier may be used for a fieldname except for names
starting with an underscore.  Valid identifiers consist of letters, digits,
and underscores but do not start with a digit or underscore and cannot be
a @ref{87,,keyword} such as `class', `for', `return', `global', `pass',
or `raise'.

If `rename' is true, invalid fieldnames are automatically replaced
with positional names.  For example, @code{['abc', 'def', 'ghi', 'abc']} is
converted to @code{['abc', '_1', 'ghi', '_3']}, eliminating the keyword
@code{def} and the duplicate fieldname @code{abc}.

`defaults' can be @code{None} or an @ref{15ce,,iterable} of default values.
Since fields with a default value must come after any fields without a
default, the `defaults' are applied to the rightmost parameters.  For
example, if the fieldnames are @code{['x', 'y', 'z']} and the defaults are
@code{(1, 2)}, then @code{x} will be a required argument, @code{y} will default to
@code{1}, and @code{z} will default to @code{2}.

If `module' is defined, the @ref{80b,,__module__} attribute of the
named tuple is set to that value.

Named tuple instances do not have per-instance dictionaries, so they are
lightweight and require no more memory than regular tuples.

To support pickling, the named tuple class should be assigned to a variable
that matches `typename'.


Άλλαξε στην έκδοση 3.1: Added support for `rename'.



Άλλαξε στην έκδοση 3.6: The `verbose' and `rename' parameters became
@ref{7a3,,keyword-only arguments}.



Άλλαξε στην έκδοση 3.6: Added the `module' parameter.



Άλλαξε στην έκδοση 3.7: Removed the `verbose' parameter and the @code{_source} attribute.



Άλλαξε στην έκδοση 3.7: Added the `defaults' parameter and the @ref{2b9c,,_field_defaults}
attribute.

@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

Named tuples are especially useful for assigning field names to result tuples returned
by the @ref{2c,,csv} or @ref{d7,,sqlite3} modules:

@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

In addition to the methods inherited from tuples, named tuples support
three additional methods and two attributes.  To prevent conflicts with
field names, the method and attribute names start with an underscore.

@geindex _make() (μέθοδος κλάσης της collections.somenamedtuple)
@anchor{library/collections collections somenamedtuple _make}@anchor{2b9d}
@deffn {Μέθοδος} classmethod somenamedtuple._make (iterable, /)

Class method that makes a new instance from an existing sequence or iterable.

@example
>>> t = [11, 22]
>>> Point._make(t)
Point(x=11, y=22)
@end example
@end deffn

@geindex _asdict() (μέθοδος της collections.somenamedtuple)
@anchor{library/collections collections somenamedtuple _asdict}@anchor{da5}
@deffn {Μέθοδος} somenamedtuple._asdict ()

Return a new @ref{188,,dict} which maps field names to their corresponding
values:

@example
>>> p = Point(x=11, y=22)
>>> p._asdict()
@{'x': 11, 'y': 22@}
@end example


Άλλαξε στην έκδοση 3.1: Returns an @ref{9d5,,OrderedDict} instead of a regular @ref{188,,dict}.



Άλλαξε στην έκδοση 3.8: Returns a regular @ref{188,,dict} instead of an @ref{9d5,,OrderedDict}.
As of Python 3.7, regular dicts are guaranteed to be ordered.  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())}.

@end deffn

@geindex _replace() (μέθοδος της collections.somenamedtuple)
@anchor{library/collections collections somenamedtuple _replace}@anchor{2b9e}
@deffn {Μέθοδος} somenamedtuple._replace (**kwargs)

Return a new instance of the named tuple replacing specified fields with new
values:

@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{45a,,copy.replace()}.


Άλλαξε στην έκδοση 3.13: Raise @ref{291,,TypeError} instead of @ref{277,,ValueError} for invalid
keyword arguments.

@end deffn

@geindex _fields (ιδιότητα της collections.somenamedtuple)
@anchor{library/collections collections somenamedtuple _fields}@anchor{2b9f}
@deffn {Ιδιότητα} somenamedtuple._fields

Tuple of strings listing the field names.  Useful for introspection
and for creating new named tuple types from existing named tuples.

@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 (ιδιότητα της collections.somenamedtuple)
@anchor{library/collections collections somenamedtuple _field_defaults}@anchor{2b9c}
@deffn {Ιδιότητα} somenamedtuple._field_defaults

Dictionary mapping field names to default values.

@example
>>> Account = namedtuple('Account', ['type', 'balance'], defaults=[0])
>>> Account._field_defaults
@{'balance': 0@}
>>> Account('premium')
Account(type='premium', balance=0)
@end example
@end deffn

To retrieve a field whose name is stored in a string, use the @ref{f8f,,getattr()}
function:

@example
>>> getattr(p, 'x')
11
@end example

To convert a dictionary to a named tuple, use the double-star-operator
(as described in @ref{21ff,,Unpacking Λίστες Ορισμάτων}):

@example
>>> d = @{'x': 11, 'y': 22@}
>>> Point(**d)
Point(x=11, y=22)
@end example

Since a named tuple is a regular Python class, it is easy to add or change
functionality with a subclass.  Here is how to add a calculated field and
a fixed-width print format:

@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

The subclass shown above sets @code{__slots__} to an empty tuple.  This helps
keep memory requirements low by preventing the creation of instance dictionaries.

Subclassing is not useful for adding new, stored fields.  Instead, simply
create a new named tuple type from the @ref{2b9f,,_fields} attribute:

@example
>>> Point3D = namedtuple('Point3D', Point._fields + ('z',))
@end example

Docstrings can be customized by making direct assignments to the @code{__doc__}
fields:

@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


Άλλαξε στην έκδοση 3.5: Property docstrings became writeable.



@subsubheading Δείτε επίσης



@itemize *

@item 
See @ref{2e4,,typing.NamedTuple} for a way to add type hints for named
tuples.  It also provides an elegant notation using the @ref{167c,,class}
keyword:

@example
class Component(NamedTuple):
    part_number: int
    weight: float
    description: Optional[str] = None
@end example

@item 
See @ref{6ea,,types.SimpleNamespace()} for a mutable namespace based on an
underlying dictionary instead of a tuple.

@item 
The @ref{32,,dataclasses} module provides a decorator and functions for
automatically adding generated special methods to user-defined classes.
@end itemize


@node OrderedDict objects,UserDict objects,namedtuple Factory Function for Tuples with Named Fields,collections — Container datatypes
@anchor{library/collections ordereddict-objects}@anchor{2ba0}
@subsubsection @code{OrderedDict} objects


Ordered dictionaries are just like regular dictionaries but have some extra
capabilities relating to ordering operations.  They have become less
important now that the built-in @ref{188,,dict} class gained the ability
to remember insertion order (this new behavior became guaranteed in
Python 3.7).

Some differences from @ref{188,,dict} still remain:


@itemize *

@item 
The regular @ref{188,,dict} was designed to be very good at mapping
operations.  Tracking insertion order was secondary.

@item 
The @ref{9d5,,OrderedDict} was designed to be good at reordering operations.
Space efficiency, iteration speed, and the performance of update
operations were secondary.

@item 
The @ref{9d5,,OrderedDict} algorithm can handle frequent reordering operations
better than @ref{188,,dict}.  As shown in the recipes below, this makes it
suitable for implementing various kinds of LRU caches.

@item 
The equality operation for @ref{9d5,,OrderedDict} checks for matching order.

A regular @ref{188,,dict} can emulate the order sensitive equality test with
@code{p == q and all(k1 == k2 for k1, k2 in zip(p, q))}.

@item 
The @ref{1692,,popitem()} method of @ref{9d5,,OrderedDict} has a different
signature.  It accepts an optional argument to specify which item is popped.

A regular @ref{188,,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{188,,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{9d5,,OrderedDict} has a @ref{1588,,move_to_end()} method to efficiently
reposition an element to an endpoint.

A regular @ref{188,,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{188,,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 
Until Python 3.8, @ref{188,,dict} lacked a @ref{1049,,__reversed__()} method.
@end itemize

@geindex OrderedDict (κλάση σε collections)
@anchor{library/collections collections OrderedDict}@anchor{9d5}
@deffn {Κλάση} collections.OrderedDict (**kwargs)

@deffnx {Κλάση} collections.OrderedDict (mapping, /, **kwargs)

@deffnx {Κλάση} collections.OrderedDict (iterable, /, **kwargs)

Return an instance of a @ref{188,,dict} subclass that has methods
specialized for rearranging dictionary order.


Added in version 3.1.


@geindex popitem() (μέθοδος της collections.OrderedDict)
@anchor{library/collections collections OrderedDict popitem}@anchor{1692}
@deffn {Μέθοδος} popitem (last=True)

The @code{popitem()} method for ordered dictionaries returns and removes a
(key, value) pair.  The pairs are returned in
@abbr{LIFO} order if `last' is true
or @abbr{FIFO,first-in@comma{} first-out} order if false.
@end deffn

@geindex move_to_end() (μέθοδος της collections.OrderedDict)
@anchor{library/collections collections OrderedDict move_to_end}@anchor{1588}
@deffn {Μέθοδος} 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{7df,,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


Added in version 3.2.

@end deffn
@end deffn

In addition to the usual mapping methods, ordered dictionaries also support
reverse iteration using @ref{c3c,,reversed()}.
@anchor{library/collections collections-ordereddict-eq}@anchor{1b60}
Equality tests between @ref{9d5,,OrderedDict} objects are order-sensitive
and are roughly equivalent to @code{list(od1.items())==list(od2.items())}.

Equality tests between @ref{9d5,,OrderedDict} objects and other
@ref{c9c,,Mapping} objects are order-insensitive like regular
dictionaries.  This allows @code{OrderedDict} objects to be substituted
anywhere a regular dictionary is used.


Άλλαξε στην έκδοση 3.5: The items, keys, and values @ref{2ba1,,views}
of @ref{9d5,,OrderedDict} now support reverse iteration using @ref{c3c,,reversed()}.



Άλλαξε στην έκδοση 3.6: With the acceptance of 
@geindex Python Enhancement Proposals; PEP 468
PEP 468@footnote{https://peps.python.org/pep-0468/}, order is retained for keyword arguments
passed to the @ref{9d5,,OrderedDict} constructor and its @ref{1807,,update()}
method.



Άλλαξε στην έκδοση 3.9: Added merge (@code{|}) and update (@code{|=}) operators, specified in 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}.


@menu
* OrderedDict Examples and Recipes:: 

@end menu

@node OrderedDict Examples and Recipes,,,OrderedDict objects
@anchor{library/collections ordereddict-examples-and-recipes}@anchor{2ba2}
@subsubsection @code{OrderedDict} Examples and Recipes


It is straightforward to create an ordered dictionary variant
that remembers the order the keys were `last' inserted.
If a new entry overwrites an existing entry, the
original insertion position is changed and moved to the end:

@example
class LastUpdatedOrderedDict(OrderedDict):
    'Store items in the order that the keys were last updated.'

    def __setitem__(self, key, value):
        super().__setitem__(key, value)
        self.move_to_end(key)
@end example

An @ref{9d5,,OrderedDict} would also be useful for implementing
variants of @ref{db3,,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 UserDict objects,UserList objects,OrderedDict objects,collections — Container datatypes
@anchor{library/collections userdict-objects}@anchor{2ba3}
@subsubsection @code{UserDict} objects


The class, @ref{192d,,UserDict} acts as a wrapper around dictionary objects.
The need for this class has been partially supplanted by the ability to
subclass directly from @ref{188,,dict}; however, this class can be easier
to work with because the underlying dictionary is accessible as an
attribute.

@geindex UserDict (κλάση σε collections)
@anchor{library/collections collections UserDict}@anchor{192d}
@deffn {Κλάση} collections.UserDict (**kwargs)

@deffnx {Κλάση} collections.UserDict (mapping, /, **kwargs)

@deffnx {Κλάση} collections.UserDict (iterable, /, **kwargs)

Class that simulates a dictionary.  The instance’s contents are kept in a
regular dictionary, which is accessible via the @ref{2ba4,,data} attribute of
@code{UserDict} instances.  If arguments are provided, they are used to
initialize @code{data}, like a regular dictionary.

In addition to supporting the methods and operations of mappings,
@code{UserDict} instances provide the following attribute:

@geindex data (ιδιότητα της collections.UserDict)
@anchor{library/collections collections UserDict data}@anchor{2ba4}
@deffn {Ιδιότητα} data

A real dictionary used to store the contents of the @code{UserDict}
class.
@end deffn

@code{UserDict} instances also override the following method:

@geindex popitem() (μέθοδος της collections.UserDict)
@anchor{library/collections collections UserDict popitem}@anchor{190c}
@deffn {Μέθοδος} popitem ()

Remove and return a @code{(key, value)} pair from the wrapped dictionary. Pairs are
returned in the same order as @code{data.popitem()}. (For the default
@ref{18c8,,dict.popitem()}, this order is @abbr{LIFO}.) If the
dictionary is empty, raises a @ref{7df,,KeyError}.
@end deffn
@end deffn

@node UserList objects,UserString objects,UserDict objects,collections — Container datatypes
@anchor{library/collections userlist-objects}@anchor{2ba5}
@subsubsection @code{UserList} objects


This class acts as a wrapper around list objects.  It is a useful base class
for your own list-like classes which can inherit from them and override
existing methods or add new ones.  In this way, one can add new behaviors to
lists.

The need for this class has been partially supplanted by the ability to
subclass directly from @ref{4d9,,list}; however, this class can be easier
to work with because the underlying list is accessible as an attribute.

@geindex UserList (κλάση σε collections)
@anchor{library/collections collections UserList}@anchor{1886}
@deffn {Κλάση} collections.UserList ([list])

Class that simulates a list.  The instance’s contents are kept in a regular
list, which is accessible via the @ref{2ba6,,data} attribute of @code{UserList}
instances.  The instance’s contents are initially set to a copy of `list',
defaulting to the empty list @code{[]}.  `list' can be any iterable, for
example a real Python list or a @code{UserList} object.

In addition to supporting the methods and operations of mutable sequences,
@code{UserList} instances provide the following attribute:

@geindex data (ιδιότητα της collections.UserList)
@anchor{library/collections collections UserList data}@anchor{2ba6}
@deffn {Ιδιότητα} data

A real @ref{4d9,,list} object used to store the contents of the
@code{UserList} class.
@end deffn
@end deffn

`Subclassing requirements:' Subclasses of @ref{1886,,UserList} are expected to
offer a constructor which can be called with either no arguments or one
argument.  List operations which return a new sequence attempt to create an
instance of the actual implementation class.  To do so, it assumes that the
constructor can be called with a single parameter, which is a sequence object
used as a data source.

If a derived class does not wish to comply with this requirement, all of the
special methods supported by this class will need to be overridden; please
consult the sources for information about the methods which need to be provided
in that case.

@node UserString objects,,UserList objects,collections — Container datatypes
@anchor{library/collections userstring-objects}@anchor{2ba7}
@subsubsection @code{UserString} objects


The class, @ref{118c,,UserString} acts as a wrapper around string objects.
The need for this class has been partially supplanted by the ability to
subclass directly from @ref{1df,,str}; however, this class can be easier
to work with because the underlying string is accessible as an
attribute.

@geindex UserString (κλάση σε collections)
@anchor{library/collections collections UserString}@anchor{118c}
@deffn {Κλάση} collections.UserString (seq)

Class that simulates a string object.  The instance’s
content is kept in a regular string object, which is accessible via the
@ref{2ba8,,data} attribute of @code{UserString} instances.  The instance’s
contents are initially set to a copy of `seq'.  The `seq' argument can
be any object which can be converted into a string using the built-in
@ref{1df,,str()} function.

In addition to supporting the methods and operations of strings,
@code{UserString} instances provide the following attribute:

@geindex data (ιδιότητα της collections.UserString)
@anchor{library/collections collections UserString data}@anchor{2ba8}
@deffn {Ιδιότητα} data

A real @ref{1df,,str} object used to store the contents of the
@code{UserString} class.
@end deffn


Άλλαξε στην έκδοση 3.5: New methods @code{__getnewargs__}, @code{__rmod__}, @code{casefold},
@code{format_map}, @code{isprintable}, and @code{maketrans}.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node collections abc — Αφηρημένες Βασικές Κλάσεις για Containers,heapq — Heap queue algorithm,collections — Container datatypes,Data Types
@anchor{library/collections abc doc}@anchor{2ba9}@anchor{library/collections abc collections-abc-abstract-base-classes-for-containers}@anchor{2baa}@anchor{library/collections abc module-collections abc}@anchor{1f}@anchor{library/collections abc translation-repo}@anchor{2bab}
@subsection @code{collections.abc} — Αφηρημένες Βασικές Κλάσεις για Containers


@geindex module; collections.abc


Added in version 3.3: Παλαιότερα, αυτό το module ήταν μέρος του @ref{1e,,collections} module.


`Πηγαίος κώδικας:' Lib/_collections_abc.py@footnote{https://github.com/python/cpython/tree/main/Lib/_collections_abc.py}

@c from collections.abc import *
@c import itertools
@c __name__ = '<doctest>'


__________________________________________________________________


Αυτό το module παρέχει @ref{155f,,αφηρημένες βασικές κλάσεις} που μπορούν να χρησιμοποιηθούν για να ελεγχθεί εάν μια κλάση παρέχει μια συγκεκριμένη διεπαφή· για παράδειγμα, εάν είναι @ref{183,,hashable} ή εάν είναι @ref{1564,,mapping}.

Ένας έλεγχος @ref{2f0,,issubclass()} ή @ref{2ef,,isinstance()} για μια διεπαφή λειτουργεί με έναν από τρεις τρόπους.


@enumerate 

@item 
Μια νέα γραμμένη κλάση μπορεί να κληρονομήσει άμεσα από τις αφηρημένες βασικές κλάσεις. Η κλάση πρέπει να παρέχει τις απαιτούμενες αφηρημένες μεθόδους. Οι υπόλοιπες μέθοδοι mixin προέρχονται από την κληρονομικότητα και μπορούν να παρακαμφθούν αν χρειάζεται. Άλλες μέθοδοι μπορούν να προστεθούν όταν είναι αναγκαίο:

@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

@item 
Υπάρχουσες κλάσεις και ενσωματωμένες κλάσεις μπορούν να καταχωρηθούν ως «εικονικές υποκλάσεις» των ABCs. Αυτές οι κλάσεις θα πρέπει να ορίζουν το πλήρες API, συμπεριλαμβανομένων όλων των αφηρημένων μεθόδων και όλων των μεθόδων mixin. Αυτό επιτρέπει στους χρήστες να βασίζονται στους ελέγχους @ref{2f0,,issubclass()} ή @ref{2ef,,isinstance()} για να καθορίσουν εάν υποστηρίζεται η πλήρης διεπαφή. Η εξαίρεση σε αυτό τον κανόνα είναι για τις μεθόδους που προσδιορίζονται αυτόματα από το υπόλοιπο 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

Σε αυτό το παράδειγμα, η κλάση @code{D} δεν χρειάζεται να ορίσει τις μεθόδους @code{__contains__}, @code{__iter__}, και @code{__reversed__} επειδή ο τελεστής @ref{26c7,,in-operator}, η λογική @ref{15ce,,iteration}, και η συνάρτηση @ref{c3c,,reversed()} χρησιμοποιούν αυτόματα τις μεθόδους @code{__getitem__} και @code{__len__}.

@item 
Ορισμένες απλές διεπαφές είναι άμεσα αναγνωρίσιμες από την παρουσία των απαιτούμενων μεθόδων (εκτός αν αυτές οι μέθοδοι έχουν οριστεί σε @ref{a65,,None}):

@example
class E:
    def __iter__(self): ...
    def __next__(self): ...
@end example

@example
>>> issubclass(E, Iterable)
True
>>> isinstance(E(), Iterable)
True
@end example

Οι σύνθετες διεπαφές δεν υποστηρίζουν αυτή την τελευταία τεχνική επειδή μια διεπαφή είναι κάτι περισσότερο από την παρουσία ονομάτων μεθόδων. Οι διεπαφές καθορίζουν τη σημασιολογία και τις σχέσεις μεταξύ των μεθόδων που δεν μπορούν να συναχθούν αποκλειστικά από την παρουσία συγκεκριμένων ονομάτων μεθόδων. Για παράδειγμα, η γνώση ότι μια κλάση παρέχει τις μεθόδους @code{__getitem__}, @code{__len__} και @code{__iter__} δεν είναι επαρκής για να διακρίνει μια κλάση @ref{156d,,Sequence} από μια κλάση @ref{c9c,,Mapping}.
@end enumerate


Added in version 3.9: Αυτές οι αφηρημένες κλάσεις υποστηρίζουν πλέον @code{[]}. Δείτε @ref{a9f,,Τύπος Generic Alias} και 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/}.


@menu
* Αφηρημένες Βασικές Κλάσεις Συλλογών:: 
* Αφηρημένες Βασικές Κλάσεις Συλλογών – Αναλυτικές Περιγραφές:: 
* Παραδείγματα και Συνταγές:: 

@end menu

@node Αφηρημένες Βασικές Κλάσεις Συλλογών,Αφηρημένες Βασικές Κλάσεις Συλλογών – Αναλυτικές Περιγραφές,,collections abc — Αφηρημένες Βασικές Κλάσεις για Containers
@anchor{library/collections abc collections-abstract-base-classes}@anchor{c4e}@anchor{library/collections abc id1}@anchor{2bac}
@subsubsection Αφηρημένες Βασικές Κλάσεις Συλλογών


Το collections module προσφέρει τις εξής @ref{155f,,ABCs}:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ABC

@tab

Κληρονομεί από

@tab

Αφηρημένες Μέθοδοι

@tab

Mixin Μέθοδοι

@item

@ref{28ac,,Container} @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@tab

@code{__contains__}

@tab

@item

@ref{902,,Hashable} @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@tab

@code{__hash__}

@tab

@item

@ref{28aa,,Iterable} @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
} @footnote{
Ο έλεγχος @code{isinstance(obj, Iterable)} εντοπίζει κλάσεις που είναι καταχωρημένες ως @ref{28aa,,Iterable} ή που έχουν την μέθοδο @ref{229a,,__iter__()}, αλλά δεν εντοπίζει τις κλάσεις που πραγματοποιούν επανάληψη με τη μέθοδο @ref{787,,__getitem__()}. Ο μόνος αξιόπιστος τρόπος για να προσδιοριστεί αν ένα αντικείμενο είναι @ref{15ce,,iterable} είναι να καλέσετε @code{iter(obj)}.
}

@tab

@tab

@code{__iter__}

@tab

@item

@ref{28ab,,Iterator} @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@ref{28aa,,Iterable}

@tab

@code{__next__}

@tab

@code{__iter__}

@item

@ref{1048,,Reversible} @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@ref{28aa,,Iterable}

@tab

@code{__reversed__}

@tab

@item

@ref{1193,,Generator}  @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@ref{28ab,,Iterator}

@tab

@code{send}, @code{throw}

@tab

@code{close}, @code{__iter__}, @code{__next__}

@item

@ref{903,,Sized}  @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@tab

@code{__len__}

@tab

@item

@ref{bc6,,Callable}  @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@tab

@code{__call__}

@tab

@item

@ref{1047,,Collection}  @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@ref{903,,Sized},
@ref{28aa,,Iterable},
@ref{28ac,,Container}

@tab

@code{__contains__},
@code{__iter__},
@code{__len__}

@tab

@item

@ref{156d,,Sequence}

@tab

@ref{1048,,Reversible},
@ref{1047,,Collection}

@tab

@code{__getitem__},
@code{__len__}

@tab

@code{__contains__}, @code{__iter__}, @code{__reversed__},
@code{index}, and @code{count}

@item

@ref{6c6,,MutableSequence}

@tab

@ref{156d,,Sequence}

@tab

@code{__getitem__},
@code{__setitem__},
@code{__delitem__},
@code{__len__},
@code{insert}

@tab

Κληρονομημένες @ref{156d,,Sequence} μέθοδοι και @code{append}, @code{clear}, @code{reverse}, @code{extend}, @code{pop}, @code{remove}, and @code{__iadd__}

@item

@ref{2cb,,ByteString}

@tab

@ref{156d,,Sequence}

@tab

@code{__getitem__},
@code{__len__}

@tab

Κληρονομημένες @ref{156d,,Sequence} μέθοδοι

@item

@ref{28a1,,Set}

@tab

@ref{1047,,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{__rsub__}, @code{__xor__}, @code{__rxor__} και @code{isdisjoint}

@item

@ref{28ad,,MutableSet}

@tab

@ref{28a1,,Set}

@tab

@code{__contains__},
@code{__iter__},
@code{__len__},
@code{add},
@code{discard}

@tab

Κληρονομημένες @ref{28a1,,Set} μέθοδοι και @code{clear}, @code{pop}, @code{remove}, @code{__ior__}, @code{__iand__}, @code{__ixor__}, και @code{__isub__}

@item

@ref{c9c,,Mapping}

@tab

@ref{1047,,Collection}

@tab

@code{__getitem__},
@code{__iter__},
@code{__len__}

@tab

@code{__contains__}, @code{keys}, @code{items}, @code{values}, @code{get}, @code{__eq__}, και @code{__ne__}

@item

@ref{1459,,MutableMapping}

@tab

@ref{c9c,,Mapping}

@tab

@code{__getitem__},
@code{__setitem__},
@code{__delitem__},
@code{__iter__},
@code{__len__}

@tab

Κληρονομημένες @ref{c9c,,Mapping} μέθοδοι και @code{pop}, @code{popitem}, @code{clear}, @code{update}, και @code{setdefault}

@item

@ref{28ae,,MappingView}

@tab

@ref{903,,Sized}

@tab

@tab

@code{__init__}, @code{__len__} and @code{__repr__}

@item

@ref{28b0,,ItemsView}

@tab

@ref{28ae,,MappingView},
@ref{28a1,,Set}

@tab

@tab

@code{__contains__},
@code{__iter__}

@item

@ref{28af,,KeysView}

@tab

@ref{28ae,,MappingView},
@ref{28a1,,Set}

@tab

@tab

@code{__contains__},
@code{__iter__}

@item

@ref{28b1,,ValuesView}

@tab

@ref{28ae,,MappingView},
@ref{1047,,Collection}

@tab

@tab

@code{__contains__}, @code{__iter__}

@item

@ref{1194,,Awaitable} @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@tab

@code{__await__}

@tab

@item

@ref{1195,,Coroutine} @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@ref{1194,,Awaitable}

@tab

@code{send}, @code{throw}

@tab

@code{close}

@item

@ref{1197,,AsyncIterable} @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@tab

@code{__aiter__}

@tab

@item

@ref{1196,,AsyncIterator} @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@ref{1197,,AsyncIterable}

@tab

@code{__anext__}

@tab

@code{__aiter__}

@item

@ref{104a,,AsyncGenerator} @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@ref{1196,,AsyncIterator}

@tab

@code{asend}, @code{athrow}

@tab

@code{aclose}, @code{__aiter__}, @code{__anext__}

@item

@ref{312,,Buffer} @footnote{
Αυτές οι ABCs παρακάμπτουν την μέθοδο @ref{2bad,,__subclasshook__()} για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε @ref{a65,,None}. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.
}

@tab

@tab

@code{__buffer__}

@tab

@end multitable


@subsubheading Υποσημειώσεις


@node Αφηρημένες Βασικές Κλάσεις Συλλογών – Αναλυτικές Περιγραφές,Παραδείγματα και Συνταγές,Αφηρημένες Βασικές Κλάσεις Συλλογών,collections abc — Αφηρημένες Βασικές Κλάσεις για Containers
@anchor{library/collections abc collections-abstract-base-classes-detailed-descriptions}@anchor{2bae}
@subsubsection Αφηρημένες Βασικές Κλάσεις Συλλογών – Αναλυτικές Περιγραφές


@geindex Container (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Container}@anchor{28ac}
@deffn {Κλάση} collections.abc.Container

ABC για κλάσεις που παρέχουν την μέθοδο @ref{175c,,__contains__()}.
@end deffn

@geindex Hashable (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Hashable}@anchor{902}
@deffn {Κλάση} collections.abc.Hashable

ABC για κλάσεις που παρέχουν την μέθοδο @ref{ec1,,__hash__()}.
@end deffn

@geindex Sized (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Sized}@anchor{903}
@deffn {Κλάση} collections.abc.Sized

ABC για κλάσεις που παρέχουν την μέθοδο @ref{1989,,__len__()}.
@end deffn

@geindex Callable (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Callable}@anchor{bc6}
@deffn {Κλάση} collections.abc.Callable

ABC για κλάσεις που παρέχουν την μέθοδο @ref{961,,__call__()}.

Ανατρέξτε στο @ref{28cb,,Annotating callable objects} για λεπτομέρειες σχετικά με τον τρόπο χρήσης του @code{Callable} σε τύπους annotations.
@end deffn

@geindex Iterable (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Iterable}@anchor{28aa}
@deffn {Κλάση} collections.abc.Iterable

ABC για κλάσεις που παρέχουν την μέθοδο @ref{229a,,__iter__()}.

Ο έλεγχος @code{isinstance(obj, Iterable)} εντοπίζει κλάσεις που είναι καταχωρημένες ως @ref{28aa,,Iterable} ή που διαθέτουν τη μέθοδο @ref{229a,,__iter__()}, αλλά δεν εντοπίζει κλάσεις που πραγματοποιούν επανάληψη με τη μέθοδο @ref{787,,__getitem__()}. Ο μόνος αξιόπιστος τρόπος για να προσδιοριστεί αν ένα αντικείμενο είναι @ref{15ce,,iterable} είναι να κληθεί @code{iter(obj)}.
@end deffn

@geindex Collection (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Collection}@anchor{1047}
@deffn {Κλάση} collections.abc.Collection

ABC για τις κλάσεις επαναλαμβανόμενων container με μέγεθος.


Added in version 3.6.

@end deffn

@geindex Iterator (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Iterator}@anchor{28ab}
@deffn {Κλάση} collections.abc.Iterator

ABC για κλάσεις που παρέχουν τις μεθόδους @ref{229d,,__iter__()} και @ref{1672,,__next__()}. Δείτε επίσης τον ορισμό του @ref{6ce,,iterator}.
@end deffn

@geindex Reversible (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Reversible}@anchor{1048}
@deffn {Κλάση} collections.abc.Reversible

ABC για τις επαναλαμβανόμενες κλάσεις που παρέχουν επίσης τη μέθοδο @ref{1049,,__reversed__()}.


Added in version 3.6.

@end deffn

@geindex Generator (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Generator}@anchor{1193}
@deffn {Κλάση} collections.abc.Generator

ABC για τις κλάσεις @ref{1409,,generator} που υλοποιούν το πρωτόκολλο που ορίζεται στο 
@geindex Python Enhancement Proposals; PEP 342
PEP 342@footnote{https://peps.python.org/pep-0342/} το οποίο επεκτείνει τους @ref{6ce,,iterators} με τις μεθόδους @ref{260f,,send()}, @ref{905,,throw()} και @ref{199e,,close()}.

Δείτε. @ref{2baf,,Annotating generators and coroutines} για λεπτομέρειες σχετικά με τη χρήση του @code{Generator} σε τύπους annotations.


Added in version 3.5.

@end deffn

@geindex Sequence (κλάση σε collections.abc)
@geindex MutableSequence (κλάση σε collections.abc)
@geindex ByteString (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Sequence}@anchor{156d}
@deffn {Κλάση} collections.abc.Sequence
@anchor{library/collections abc collections abc MutableSequence}@anchor{6c6}
@deffnx {Κλάση} collections.abc.MutableSequence
@anchor{library/collections abc collections abc ByteString}@anchor{2cb}
@deffnx {Κλάση} collections.abc.ByteString

ABCs μόνο για ανάγνωση (read-only) και mutable @ref{8ff,,sequences}.

Σημείωση υλοποίησης: Μερικές από τις μεθόδους mixin, όπως @ref{229a,,__iter__()}, @ref{1049,,__reversed__()} και @ref{1b8b,,index()}, κάνουν επανειλημμένες κλήσεις στην μέθοδο @ref{787,,__getitem__()}. Ως αποτέλεσμα, αν η @code{__getitem__()} είναι υλοποιημένη με σταθερή ταχύτητα πρόσβασης, οι μέθοδοι mixin θα έχουν γραμμική απόδοση∙ ωστόσο, αν η υποκείμενη μέθοδος είναι γραμμική (όπως θα ήταν με μια συνδεδεμένη λίστα), οι mixins θα έχουν τετραγωνική απόδοση και πιθανώς θα χρειαστεί να αντικατασταθούν.

@geindex index() (μέθοδος της collections.abc.ByteString)
@anchor{library/collections abc collections abc ByteString index}@anchor{2bb0}
@deffn {Μέθοδος} index (value, start=0, stop=None)

Επιστρέφει τον πρώτο δείκτη του `value'.

Κάνει raise μια @ref{277,,ValueError} αν η τιμή δεν είναι παρούσα.

Η υποστήριξη των ορισμάτων `start' και `stop' είναι προαιρετική, αλλά συνιστάται.


Άλλαξε στην έκδοση 3.5: Η μέθοδος @ref{1b8b,,index()} πρόσθεσε υποστήριξη για τα ορίσματα `stop' και `start'.

@end deffn


Καταργήθηκε από την έκδοση 3.12, θα αφαιρεθεί στην έκδοση 3.17: Η ABC @ref{2cb,,ByteString} έχει αποσυρθεί.

Χρησιμοποιήστε το @code{isinstance(obj, collections.abc.Buffer)} για να ελέγξετε αν το @code{obj} υλοποιεί το @ref{311,,buffer protocol} κατά το runtime. Για χρήση σε type annotations, είτε χρησιμοποιήστε την @ref{312,,Buffer} είτε μια ένωση που να καθορίζει ρητά τους τύπους που υποστηρίζει ο κώδικάς σας (π.χ., @code{bytes | bytearray | memoryview}).

Η @code{ByteString} προοριζόταν αρχικά να είναι μια αφηρημένη κλάση που θα λειτουργούσε ως υπερτύπος τόσο για την @ref{1c7,,bytes} όσο και για την @ref{1c6,,bytearray}. Ωστόσο, δεδομένου ότι η ABC δεν είχε καμία μέθοδο, η γνώση ότι ένα αντικείμενο ήταν στιγμιότυπο της @code{ByteString} δεν σας έλεγε ποτέ κάτι χρήσιμο για το αντικείμενο. Άλλοι κοινοί τύποι buffer όπως η @ref{1d2,,memoryview} επίσης δεν θεωρούνταν ποτέ ως υποτύποι της @code{ByteString} (ούτε κατά το runtime ούτε από στατικούς ελεγκτές τύπων).

Δείτε 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} για περισσότερες λεπτομέρειες.

@end deffn

@geindex Set (κλάση σε collections.abc)
@geindex MutableSet (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Set}@anchor{28a1}
@deffn {Κλάση} collections.abc.Set
@anchor{library/collections abc collections abc MutableSet}@anchor{28ad}
@deffnx {Κλάση} collections.abc.MutableSet

ABCs μόνο για ανάγνωση (read-only) και mutable @ref{2220,,sets}.
@end deffn

@geindex Mapping (κλάση σε collections.abc)
@geindex MutableMapping (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Mapping}@anchor{c9c}
@deffn {Κλάση} collections.abc.Mapping
@anchor{library/collections abc collections abc MutableMapping}@anchor{1459}
@deffnx {Κλάση} collections.abc.MutableMapping

ABCs μόνο για ανάγνωση (read-only) και mutable @ref{1564,,mappings}.
@end deffn

@geindex MappingView (κλάση σε collections.abc)
@geindex ItemsView (κλάση σε collections.abc)
@geindex KeysView (κλάση σε collections.abc)
@geindex ValuesView (κλάση σε collections.abc)
@anchor{library/collections abc collections abc MappingView}@anchor{28ae}
@deffn {Κλάση} collections.abc.MappingView
@anchor{library/collections abc collections abc ItemsView}@anchor{28b0}
@deffnx {Κλάση} collections.abc.ItemsView
@anchor{library/collections abc collections abc KeysView}@anchor{28af}
@deffnx {Κλάση} collections.abc.KeysView
@anchor{library/collections abc collections abc ValuesView}@anchor{28b1}
@deffnx {Κλάση} collections.abc.ValuesView

ABCs για αντιστοιχήσεις, στοιχεία, κλειδιά και τιμές @ref{2ba1,,views}.
@end deffn

@geindex Awaitable (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Awaitable}@anchor{1194}
@deffn {Κλάση} collections.abc.Awaitable

ABC για αντικείμενα @ref{6cf,,awaitable}, που μπορούν να χρησιμοποιηθούν σε εκφράσεις @ref{432,,await}. Οι προσαρμοσμένες υλοποιήσεις πρέπει να παρέχουν τη μέθοδο @ref{112e,,__await__()}.

Τα αντικείμενα @ref{8a2,,Coroutine} και τα στιγμιότυπα της κλάσης @ref{1195,,Coroutine} είναι όλα παραδείγματα αυτής της ABC.

@cartouche
@quotation Σημείωση 
Στην CPython, οι generator-based coroutines (@ref{1409,,generators} που είναι decorated με @ref{1239,,@@types.coroutine}) είναι `awaitables', αν και δεν διαθέτουν μέθοδο @ref{112e,,__await__()}. Η χρήση της @code{isinstance(gencoro, Awaitable)} γι” αυτές θα επιστρέψει @code{False}. Χρησιμοποιείτε τη συνάρτηση @ref{11cb,,inspect.isawaitable()} για να τις εντοπίσετε.
@end quotation
@end cartouche


Added in version 3.5.

@end deffn

@geindex Coroutine (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Coroutine}@anchor{1195}
@deffn {Κλάση} collections.abc.Coroutine

ABC για κλάσεις συμβατές με το @ref{8a2,,coroutine}. Αυτές υλοποιούν τις εξής μεθόδους, οι οποίες ορίζονται στο @ref{2547,,Coroutine Αντικείμενα}: @ref{260e,,send()}, @ref{904,,throw()}, και @ref{2610,,close()}. Οι προσαρμοσμένες υλοποιήσεις πρέπει επίσης να υλοποιούν τη μέθοδο @ref{112e,,__await__()}. Όλα τα @ref{1195,,Coroutine} στιγμιότυπα είναι επίσης στιγμιότυπα της κλάσης @ref{1194,,Awaitable}.

@cartouche
@quotation Σημείωση 
Στην CPython, οι generator-based coroutines (@ref{1409,,generators} που είναι διακοσμημένες με @ref{1239,,@@types.coroutine}) είναι `awaitables', αν και δεν έχουν τη μέθοδο @ref{112e,,__await__()}. Η χρήση της @code{isinstance (gencoro, Coroutine)} γι” αυτές θα επιστρέψει @code{False}. Χρησιμοποιείται η συνάρτηση @ref{11cb,,inspect.isawaitable()} για να εντοπιστούν.
@end quotation
@end cartouche

Βλ. @ref{2baf,,Annotating generators and coroutines} για λεπτομέρειες σχετικά με τη χρήση της @code{Coroutine} σε σχολιασμούς τύπου. Η διακύμανση και η σειρά των παραμέτρων τύπου αντιστοιχούν σε εκείνες της @ref{1193,,Generator}.


Added in version 3.5.

@end deffn

@geindex AsyncIterable (κλάση σε collections.abc)
@anchor{library/collections abc collections abc AsyncIterable}@anchor{1197}
@deffn {Κλάση} collections.abc.AsyncIterable

ABC για κλάσεις που παρέχουν μια μέθοδο @code{__aiter__}. Δείτε επίσης τον ορισμό του @ref{112d,,asynchronous iterable}.


Added in version 3.5.

@end deffn

@geindex AsyncIterator (κλάση σε collections.abc)
@anchor{library/collections abc collections abc AsyncIterator}@anchor{1196}
@deffn {Κλάση} collections.abc.AsyncIterator

ABC για κλάσεις που παρέχουν τις μεθόδους @code{__aiter__} και @code{__anext__}. Δείτε επίσης τον ορισμό του @ref{6cd,,asynchronous iterator}.


Added in version 3.5.

@end deffn

@geindex AsyncGenerator (κλάση σε collections.abc)
@anchor{library/collections abc collections abc AsyncGenerator}@anchor{104a}
@deffn {Κλάση} collections.abc.AsyncGenerator

ABC για κλάσεις @ref{2692,,asynchronous generator} που υλοποιούν το πρωτόκολλο που ορίζεται στο 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/} και 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.

Δείτε @ref{2baf,,Annotating generators and coroutines} για λεπτομέρειες σχετικά με τη χρήση του @code{AsyncGenerator} σε σχολιασμούς τύπου.


Added in version 3.6.

@end deffn

@geindex Buffer (κλάση σε collections.abc)
@anchor{library/collections abc collections abc Buffer}@anchor{312}
@deffn {Κλάση} collections.abc.Buffer

ABC για κλάσεις που παρέχουν τη μέθοδο @ref{879,,__buffer__()}, υλοποιώντας το @ref{311,,buffer protocol}. Δείτε το 
@geindex Python Enhancement Proposals; PEP 688
PEP 688@footnote{https://peps.python.org/pep-0688/}.


Added in version 3.12.

@end deffn

@node Παραδείγματα και Συνταγές,,Αφηρημένες Βασικές Κλάσεις Συλλογών – Αναλυτικές Περιγραφές,collections abc — Αφηρημένες Βασικές Κλάσεις για Containers
@anchor{library/collections abc examples-and-recipes}@anchor{2bb1}
@subsubsection Παραδείγματα και Συνταγές


Οι ABCs επιτρέπουν να ρωτήσουμε τις κλάσεις ή τα αντικείμενα αν παρέχουν συγκεκριμένη λειτουργικότητα, για παράδειγμα:

@example
size = None
if isinstance(myvar, collections.abc.Sized):
    size = len(myvar)
@end example

Μερικές από τις ABCs είναι επίσης χρήσιμες ως mixins που διευκολύνουν την ανάπτυξη κλάσεων που υποστηρίζουν τα APIs των container. Για παράδειγμα, για να γράψετε μια κλάση που υποστηρίζει το πλήρες API του @ref{28a1,,Set}, αρκεί να παρέχετε τις τρεις υποκείμενες αφηρημένες μεθόδους: @ref{175c,,__contains__()}, @ref{229a,,__iter__()}, και @ref{1989,,__len__()}. Η ABC παρέχει τις υπόλοιπες μεθόδους, όπως @code{__and__()} και @ref{288b,,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

Σημειώσεις για τη χρήση των @ref{28a1,,Set} και @ref{28ad,,MutableSet} ως mixin:


@enumerate 

@item 
Δεδομένου ότι ορισμένες λειτουργίες συνόλων δημιουργούν νέα σύνολα, οι προεπιλεγμένες μέθοδοι mixin χρειάζονται έναν τρόπο δημιουργίας νέων αντικειμένων από ένα @ref{15ce,,iterable}. Υποτίθεται ότι ο κατασκευαστής της κλάσης έχει μια υπογραφή της μορφής @code{ClassName(iterable)}. Αυτή η υπόθεση είναι αποσυνδεδεμένη σε μια εσωτερική @ref{69a,,classmethod} που ονομάζεται @code{_from_iterable()}, η οποία καλεί το @code{cls(iterable)} για να δημιουργήσει ένα νέο σύνολο. Εάν το mixin @ref{28a1,,Set} χρησιμοποιείται σε μια κλάση με διαφορετική υπογραφή κατασκευαστή, θα χρειαστεί να αντικαταστήσετε την @code{_from_iterable()} με μια μέθοδο κλάσης ή κανονική μέθοδο που μπορεί να δημιουργήσει νέα αντικείμενα από ένα όρισμα iterable.

@item 
Για να παρακάμψετε τις συγκρίσεις (πιθανότατα για λόγους απόδοσης, καθώς η σημασιολογία είναι καθορισμένη), ορίστε ξανά τις μεθόδους @ref{16af,,__le__()}, και @ref{16b1,,__ge__()}, και οι άλλες λειτουργίες θα ακολουθήσουν αυτόματα.

@item 
Το mixin @ref{28a1,,Set} παρέχει τη μέθοδο @code{_hash()} για να υπολογίσει μια τιμή κατακερματισμού για το σύνολο. Ωστόσο, η μέθοδος @ref{ec1,,__hash__()} δεν είναι ορισμένη, επειδή δεν είναι όλα τα σύνολα @ref{183,,hashable} ή αμετάβλητα. Για να προσθέσετε hashability σε ένα σύνολο χρησιμοποιώντας mixins, κληρονομήστε τόσο από τις κλάσεις @ref{28a1,,Set()} όσο και @ref{902,,Hashable()}, και στη συνέχεια ορίστε @code{__hash__ = Set._hash}.
@end enumerate


@subsubheading Δείτε επίσης



@itemize *

@item 
Συνταγή OrderedSet@footnote{https://code.activestate.com/recipes/576694/} για ένα παράδειγμα που βασίζεται στην κλάση @ref{28ad,,MutableSet}.

@item 
Για περισσότερα σχετικά με τις ABCs, δείτε το @ref{4,,abc} module και το 
@geindex Python Enhancement Proposals; PEP 3119
PEP 3119@footnote{https://peps.python.org/pep-3119/}.
@end itemize


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node heapq — Heap queue algorithm,bisect — Array bisection algorithm,collections abc — Αφηρημένες Βασικές Κλάσεις για Containers,Data Types
@anchor{library/heapq doc}@anchor{2bb2}@anchor{library/heapq heapq-heap-queue-algorithm}@anchor{2bb3}@anchor{library/heapq module-heapq}@anchor{6c}@anchor{library/heapq translation-repo}@anchor{2bb4}
@subsection @code{heapq} — Heap queue algorithm


@geindex module; heapq

`Source code:' Lib/heapq.py@footnote{https://github.com/python/cpython/tree/main/Lib/heapq.py}


__________________________________________________________________


This module provides an implementation of the heap queue algorithm, also known
as the priority queue algorithm.

Min-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.

For min-heaps, this implementation uses lists for which
@code{heap[k] <= heap[2*k+1]} and @code{heap[k] <= heap[2*k+2]} for all `k' for which
the compared elements exist.  Elements are counted from zero.  The interesting
property of a min-heap is that its smallest element is always the root,
@code{heap[0]}.

Max-heaps satisfy the reverse invariant: every parent node has a value
`greater' than any of its children.  These are implemented as lists for which
@code{maxheap[2*k+1] <= maxheap[k]} and @code{maxheap[2*k+2] <= maxheap[k]} for all
`k' for which the compared elements exist.
The root, @code{maxheap[0]}, contains the `largest' element;
@code{heap.sort(reverse=True)} maintains the max-heap invariant.

The @code{heapq} API differs from textbook heap algorithms in two aspects: (a)
We use zero-based indexing.  This makes the relationship between the index for
a node and the indexes for its children slightly less obvious, but is more
suitable since Python uses zero-based indexing. (b) Textbooks often focus on
max-heaps, due to their suitability for in-place sorting. Our implementation
favors min-heaps as they better correspond to Python @ref{4d9,,lists}.

These two aspects make it possible to view the heap as a regular Python list
without surprises: @code{heap[0]} is the smallest item, and @code{heap.sort()}
maintains the heap invariant!

Like @ref{f8d,,list.sort()}, this implementation uses only the @code{<} operator
for comparisons, for both min-heaps and max-heaps.

In the API below, and in this documentation, the unqualified term `heap'
generally refers to a min-heap.
The API for max-heaps is named using a @code{_max}  suffix.

To create a heap, use a list initialized as @code{[]}, or transform an existing list
into a min-heap or max-heap using the @ref{2bb5,,heapify()} or @ref{4af,,heapify_max()}
functions, respectively.

The following functions are provided for min-heaps:

@geindex heapify() (στη μονάδα heapq)
@anchor{library/heapq heapq heapify}@anchor{2bb5}
@deffn {Συνάρτηση} heapq.heapify (x)

Transform list `x' into a min-heap, in-place, in linear time.
@end deffn

@geindex heappush() (στη μονάδα heapq)
@anchor{library/heapq heapq heappush}@anchor{185e}
@deffn {Συνάρτηση} heapq.heappush (heap, item)

Push the value `item' onto the `heap', maintaining the min-heap invariant.
@end deffn

@geindex heappop() (στη μονάδα heapq)
@anchor{library/heapq heapq heappop}@anchor{185f}
@deffn {Συνάρτηση} heapq.heappop (heap)

Pop and return the smallest item from the `heap', maintaining the min-heap
invariant.  If the heap is empty, @ref{18d7,,IndexError} is raised.  To access the
smallest item without popping it, use @code{heap[0]}.
@end deffn

@geindex heappushpop() (στη μονάδα heapq)
@anchor{library/heapq heapq heappushpop}@anchor{2bb6}
@deffn {Συνάρτηση} heapq.heappushpop (heap, item)

Push `item' on the heap, then pop and return the smallest item from the
`heap'.  The combined action runs more efficiently than @ref{185e,,heappush()}
followed by a separate call to @ref{185f,,heappop()}.
@end deffn

@geindex heapreplace() (στη μονάδα heapq)
@anchor{library/heapq heapq heapreplace}@anchor{2bb7}
@deffn {Συνάρτηση} heapq.heapreplace (heap, item)

Pop and return the smallest item from the `heap', and also push the new `item'.
The heap size doesn’t change. If the heap is empty, @ref{18d7,,IndexError} is raised.

This one step operation is more efficient than a @ref{185f,,heappop()} followed by
@ref{185e,,heappush()} and can be more appropriate when using a fixed-size heap.
The pop/push combination always returns an element from the heap and replaces
it with `item'.

The value returned may be larger than the `item' added.  If that isn’t
desired, consider using @ref{2bb6,,heappushpop()} instead.  Its push/pop
combination returns the smaller of the two values, leaving the larger value
on the heap.
@end deffn

For max-heaps, the following functions are provided:

@geindex heapify_max() (στη μονάδα heapq)
@anchor{library/heapq heapq heapify_max}@anchor{4af}
@deffn {Συνάρτηση} heapq.heapify_max (x)

Transform list `x' into a max-heap, in-place, in linear time.


Added in version 3.14.

@end deffn

@geindex heappush_max() (στη μονάδα heapq)
@anchor{library/heapq heapq heappush_max}@anchor{4b0}
@deffn {Συνάρτηση} heapq.heappush_max (heap, item)

Push the value `item' onto the max-heap `heap', maintaining the max-heap
invariant.


Added in version 3.14.

@end deffn

@geindex heappop_max() (στη μονάδα heapq)
@anchor{library/heapq heapq heappop_max}@anchor{4b1}
@deffn {Συνάρτηση} heapq.heappop_max (heap)

Pop and return the largest item from the max-heap `heap', maintaining the
max-heap invariant.  If the max-heap is empty, @ref{18d7,,IndexError} is raised.
To access the largest item without popping it, use @code{maxheap[0]}.


Added in version 3.14.

@end deffn

@geindex heappushpop_max() (στη μονάδα heapq)
@anchor{library/heapq heapq heappushpop_max}@anchor{4b3}
@deffn {Συνάρτηση} heapq.heappushpop_max (heap, item)

Push `item' on the max-heap `heap', then pop and return the largest item
from `heap'.
The combined action runs more efficiently than @ref{4b0,,heappush_max()}
followed by a separate call to @ref{4b1,,heappop_max()}.


Added in version 3.14.

@end deffn

@geindex heapreplace_max() (στη μονάδα heapq)
@anchor{library/heapq heapq heapreplace_max}@anchor{4b2}
@deffn {Συνάρτηση} heapq.heapreplace_max (heap, item)

Pop and return the largest item from the max-heap `heap' and also push the
new `item'.
The max-heap size doesn’t change. If the max-heap is empty,
@ref{18d7,,IndexError} is raised.

The value returned may be smaller than the `item' added.  Refer to the
analogous function @ref{2bb7,,heapreplace()} for detailed usage notes.


Added in version 3.14.

@end deffn

The module also offers three general purpose functions based on heaps.

@geindex merge() (στη μονάδα heapq)
@anchor{library/heapq heapq merge}@anchor{11b9}
@deffn {Συνάρτηση} heapq.merge (*iterables, key=None, reverse=False)

Merge multiple sorted inputs into a single sorted output (for example, merge
timestamped entries from multiple log files).  Returns an @ref{6ce,,iterator}
over the sorted values.

Similar to @code{sorted(itertools.chain(*iterables))} but returns an iterable, does
not pull the data into memory all at once, and assumes that each of the input
streams is already sorted (smallest to largest).

Has two optional arguments which must be specified as keyword arguments.

`key' specifies a @ref{11ba,,key function} of one argument that is used to
extract a comparison key from each input element.  The default value is
@code{None} (compare the elements directly).

`reverse' is a boolean value.  If set to @code{True}, then the input elements
are merged as if each comparison were reversed. To achieve behavior similar
to @code{sorted(itertools.chain(*iterables), reverse=True)}, all iterables must
be sorted from largest to smallest.


Άλλαξε στην έκδοση 3.5: Added the optional `key' and `reverse' parameters.

@end deffn

@geindex nlargest() (στη μονάδα heapq)
@anchor{library/heapq heapq nlargest}@anchor{2bb8}
@deffn {Συνάρτηση} heapq.nlargest (n, iterable, key=None)

Return a list with the `n' largest elements from the dataset defined by
`iterable'.  `key', if provided, specifies a function of one argument that is
used to extract a comparison key from each element in `iterable' (for example,
@code{key=str.lower}).  Equivalent to:  @code{sorted(iterable, key=key,
reverse=True)[:n]}.
@end deffn

@geindex nsmallest() (στη μονάδα heapq)
@anchor{library/heapq heapq nsmallest}@anchor{2bb9}
@deffn {Συνάρτηση} heapq.nsmallest (n, iterable, key=None)

Return a list with the `n' smallest elements from the dataset defined by
`iterable'.  `key', if provided, specifies a function of one argument that is
used to extract a comparison key from each element in `iterable' (for example,
@code{key=str.lower}).  Equivalent to:  @code{sorted(iterable, key=key)[:n]}.
@end deffn

The latter two functions perform best for smaller values of `n'.  For larger
values, it is more efficient to use the @ref{f8c,,sorted()} function.  Also, when
@code{n==1}, it is more efficient to use the built-in @ref{12b9,,min()} and @ref{12ba,,max()}
functions.  If repeated usage of these functions is required, consider turning
the iterable into an actual heap.

@menu
* Basic Examples:: 
* Other Applications:: 
* Priority Queue Implementation Notes:: 
* Theory:: 

@end menu

@node Basic Examples,Other Applications,,heapq — Heap queue algorithm
@anchor{library/heapq basic-examples}@anchor{2bba}
@subsubsection Basic Examples


A heapsort@footnote{https://en.wikipedia.org/wiki/Heapsort} can be implemented by
pushing all values onto a heap and then popping off the smallest values one at a
time:

@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

This is similar to @code{sorted(iterable)}, but unlike @ref{f8c,,sorted()}, this
implementation is not stable.

Heap elements can be tuples.  This is useful for assigning comparison values
(such as task priorities) alongside the main record being tracked:

@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 Other Applications,Priority Queue Implementation Notes,Basic Examples,heapq — Heap queue algorithm
@anchor{library/heapq other-applications}@anchor{2bbb}
@subsubsection Other Applications


Medians@footnote{https://en.wikipedia.org/wiki/Median} are a measure of
central tendency for a set of numbers.  In distributions skewed by
outliers, the median provides a more stable estimate than an average
(arithmetic mean).  A running median is an online algorithm@footnote{https://en.wikipedia.org/wiki/Online_algorithm} that updates
continuously as new data arrives.

A running median can be efficiently implemented by balancing two heaps,
a max-heap for values at or below the midpoint and a min-heap for values
above the midpoint.  When the two heaps have the same size, the new
median is the average of the tops of the two heaps; otherwise, the
median is at the top of the larger heap:

@example
def running_median(iterable):
    "Yields the cumulative median of values seen so far."

    lo = []  # max-heap
    hi = []  # min-heap (same size as or one smaller than lo)

    for x in iterable:
        if len(lo) == len(hi):
            heappush_max(lo, heappushpop(hi, x))
            yield lo[0]
        else:
            heappush(hi, heappushpop_max(lo, x))
            yield (lo[0] + hi[0]) / 2
@end example

For example:

@example
>>> list(running_median([5.0, 9.0, 4.0, 12.0, 8.0, 9.0]))
[5.0, 7.0, 5.0, 7.0, 8.0, 8.5]
@end example

@node Priority Queue Implementation Notes,Theory,Other Applications,heapq — Heap queue algorithm
@anchor{library/heapq priority-queue-implementation-notes}@anchor{2bbc}
@subsubsection Priority Queue Implementation Notes


A priority queue@footnote{https://en.wikipedia.org/wiki/Priority_queue} is common use
for a heap, and it presents several implementation challenges:


@itemize *

@item 
Sort stability:  how do you get two tasks with equal priorities to be returned
in the order they were originally added?

@item 
Tuple comparison breaks for (priority, task) pairs if the priorities are equal
and the tasks do not have a default comparison order.

@item 
If the priority of a task changes, how do you move it to a new position in
the heap?

@item 
Or if a pending task needs to be deleted, how do you find it and remove it
from the queue?
@end itemize

A solution to the first two challenges is to store entries as 3-element list
including the priority, an entry count, and the task.  The entry count serves as
a tie-breaker so that two tasks with the same priority are returned in the order
they were added. And since no two entry counts are the same, the tuple
comparison will never attempt to directly compare two tasks.

Another solution to the problem of non-comparable tasks is to create a wrapper
class that ignores the task item and only compares the priority field:

@example
from dataclasses import dataclass, field
from typing import Any

@@dataclass(order=True)
class PrioritizedItem:
    priority: int
    item: Any=field(compare=False)
@end example

The remaining challenges revolve around finding a pending task and making
changes to its priority or removing it entirely.  Finding a task can be done
with a dictionary pointing to an entry in the queue.

Removing the entry or changing its priority is more difficult because it would
break the heap structure invariants.  So, a possible solution is to mark the
entry as removed and add a new entry with the revised priority:

@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 Theory,,Priority Queue Implementation Notes,heapq — Heap queue algorithm
@anchor{library/heapq theory}@anchor{2bbd}
@subsubsection Theory


Heaps are arrays for which @code{a[k] <= a[2*k+1]} and @code{a[k] <= a[2*k+2]} for all
`k', counting elements from 0.  For the sake of comparison, non-existing
elements are considered to be infinite.  The interesting property of a heap is
that @code{a[0]} is always its smallest element.

The strange invariant above is meant to be an efficient memory representation
for a tournament.  The numbers below are `k', not @code{a[k]}:


@float Figure

@image{python-figures/heapq-binary-tree,,,Example (min-heap) binary tree.,svg}

@end float


In the tree above, each cell `k' is topping @code{2*k+1} and @code{2*k+2}. In a usual
binary tournament we see in sports, each cell is the winner over the two cells
it tops, and we can trace the winner down the tree to see all opponents s/he
had.  However, in many computer applications of such tournaments, we do not need
to trace the history of a winner. To be more memory efficient, when a winner is
promoted, we try to replace it by something else at a lower level, and the rule
becomes that a cell and the two cells it tops contain three different items, but
the top cell «wins» over the two topped cells.

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.

A nice feature of this sort is that you can efficiently insert new items while
the sort is going on, provided that the inserted items are not «better» than the
last 0’th element you extracted.  This is especially useful in simulation
contexts, where the tree holds all incoming events, and the «win» condition
means the smallest scheduled time.  When an event schedules other events for
execution, they are scheduled into the future, so they can easily go into the
heap.  So, a heap is a good structure for implementing schedulers (this is what
I used for my MIDI sequencer :-).

Various structures for implementing schedulers have been extensively studied,
and heaps are good for this, as they are reasonably speedy, the speed is almost
constant, and the worst case is not much different than the average case.
However, there are other representations which are more efficient overall, yet
the worst cases might be terrible.

Heaps are also very useful in big disk sorts.  You most probably all know that a
big sort implies producing «runs» (which are pre-sorted sequences, whose size is
usually related to the amount of CPU memory), followed by a merging passes for
these runs, which merging is often very cleverly organised @footnote{
The disk balancing algorithms which are current, nowadays, are more annoying
than clever, and this is a consequence of the seeking capabilities of the disks.
On devices which cannot seek, like big tape drives, the story was quite
different, and one had to be very clever to ensure (far in advance) that each
tape movement will be the most effective possible (that is, will best
participate at «progressing» the merge).  Some tapes were even able to read
backwards, and this was also used to avoid the rewinding time. Believe me, real
good tape sorts were quite spectacular to watch! From all times, sorting has
always been a Great Art! :-)
}. It is very
important that the initial sort produces the longest runs possible.  Tournaments
are a good way to achieve that.  If, using all the memory available to hold a
tournament, you replace and percolate items that happen to fit the current run,
you’ll produce runs which are twice the size of the memory for random input, and
much better for input fuzzily ordered.

Moreover, if you output the 0’th item on disk and get an input which may not fit
in the current tournament (because the value «wins» over the last output value),
it cannot fit in the heap, so the size of the heap decreases.  The freed memory
could be cleverly reused immediately for progressively building a second heap,
which grows at exactly the same rate the first heap is melting.  When the first
heap completely vanishes, you switch heaps and start a new run.  Clever and
quite effective!

In a word, heaps are useful memory structures to know.  I use them in a few
applications, and I think it is good to keep a “heap” module around. :-)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node bisect — Array bisection algorithm,array — Efficient arrays of numeric values,heapq — Heap queue algorithm,Data Types
@anchor{library/bisect doc}@anchor{2bbe}@anchor{library/bisect bisect-array-bisection-algorithm}@anchor{2bbf}@anchor{library/bisect module-bisect}@anchor{12}@anchor{library/bisect translation-repo}@anchor{2bc0}
@subsection @code{bisect} — Array bisection algorithm


@geindex module; bisect

`Source code:' Lib/bisect.py@footnote{https://github.com/python/cpython/tree/main/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 @code{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{ec0,,__eq__()}
method to determine whether a value has been found.  Instead, the
functions only call the @ref{1645,,__lt__()} method and will return an insertion
point between values in an array.

@cartouche
@quotation Σημείωση 
The functions in this module are not thread-safe. If multiple threads
concurrently use @code{bisect} functions on the same sequence, this
may result in undefined behaviour. Likewise, if the provided sequence
is mutated by a different thread while a @code{bisect} function
is operating on it, the result is undefined. For example, using
@ref{2bc1,,insort_left()} on the same list from multiple threads
may result in the list becoming unsorted.
@end quotation
@end cartouche
@anchor{library/bisect bisect-functions}@anchor{2bc2}
The following functions are provided:

@geindex bisect_left() (στη μονάδα bisect)
@anchor{library/bisect bisect bisect_left}@anchor{2bc3}
@deffn {Συνάρτηση} bisect.bisect_left (a, x, lo=0, hi=len(a), *, key=None)

Locate the insertion point for `x' in `a' to maintain sorted order.
The parameters `lo' and `hi' may be used to specify a subset of the list
which should be considered; by default the entire list is used.  If `x' is
already present in `a', the insertion point will be before (to the left of)
any existing entries.  The return value is suitable for use as the first
parameter to @code{list.insert()} assuming that `a' is already sorted.

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{11ba,,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.


Άλλαξε στην έκδοση 3.10: Added the `key' parameter.

@end deffn

@geindex bisect_right() (στη μονάδα bisect)
@geindex bisect() (στη μονάδα bisect)
@anchor{library/bisect bisect bisect_right}@anchor{2bc4}
@deffn {Συνάρτηση} bisect.bisect_right (a, x, lo=0, hi=len(a), *, key=None)
@anchor{library/bisect bisect bisect}@anchor{2bc5}
@deffnx {Συνάρτηση} bisect.bisect (a, x, lo=0, hi=len(a), *, key=None)

Similar to @ref{2bc3,,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.


Άλλαξε στην έκδοση 3.10: Added the `key' parameter.

@end deffn

@geindex insort_left() (στη μονάδα bisect)
@anchor{library/bisect bisect insort_left}@anchor{2bc1}
@deffn {Συνάρτηση} bisect.insort_left (a, x, lo=0, hi=len(a), *, key=None)

Insert `x' in `a' in sorted order.

This function first runs @ref{2bc3,,bisect_left()} to locate an insertion point.
Next, it runs the @ref{25cf,,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.


Άλλαξε στην έκδοση 3.10: Added the `key' parameter.

@end deffn

@geindex insort_right() (στη μονάδα bisect)
@geindex insort() (στη μονάδα bisect)
@anchor{library/bisect bisect insort_right}@anchor{2bc6}
@deffn {Συνάρτηση} bisect.insort_right (a, x, lo=0, hi=len(a), *, key=None)
@anchor{library/bisect bisect insort}@anchor{2bc7}
@deffnx {Συνάρτηση} bisect.insort (a, x, lo=0, hi=len(a), *, key=None)

Similar to @ref{2bc1,,insort_left()}, but inserting `x' in `a' after any existing
entries of `x'.

This function first runs @ref{2bc4,,bisect_right()} to locate an insertion point.
Next, it runs the @ref{25cf,,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.


Άλλαξε στην έκδοση 3.10: Added the `key' parameter.

@end deffn

@menu
* Performance Notes:: 
* Searching Sorted Lists:: 
* Examples: Examples<2>. 

@end menu

@node Performance Notes,Searching Sorted Lists,,bisect — Array bisection algorithm
@anchor{library/bisect performance-notes}@anchor{2bc8}
@subsubsection Performance Notes


When writing time sensitive code using `bisect()' and `insort()', keep these
thoughts in mind:


@itemize *

@item 
Bisection is effective for searching ranges of values.
For locating specific values, dictionaries are more performant.

@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{1a08,,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 Δείτε επίσης



@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 
The SortedCollection recipe@footnote{https://code.activestate.com/recipes/577197-sortedcollection/} uses
bisect to build a full-featured collection class with straight-forward search
methods and support for a key-function.  The keys are precomputed to save
unnecessary calls to the key function during searches.
@end itemize


@node Searching Sorted Lists,Examples<2>,Performance Notes,bisect — Array bisection algorithm
@anchor{library/bisect searching-sorted-lists}@anchor{2bc9}
@subsubsection Searching Sorted Lists


The above @ref{2bc2,,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 Examples<2>,,Searching Sorted Lists,bisect — Array bisection algorithm
@anchor{library/bisect examples}@anchor{2bca}
@subsubsection Examples

@anchor{library/bisect bisect-example}@anchor{2bcb}
The @ref{2bc5,,bisect()} function can be useful for numeric table lookups. This
example uses @code{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)
...     i = bisect([60, 70, 80, 90], score)
...     return "FDCBA"[i]
...
>>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]
['F', 'A', 'C', 'C', 'B', 'A', 'A']
@end example

The @ref{2bc5,,bisect()} and @ref{2bc7,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node array — Efficient arrays of numeric values,weakref — Weak references,bisect — Array bisection algorithm,Data Types
@anchor{library/array doc}@anchor{2bcc}@anchor{library/array array-efficient-arrays-of-numeric-values}@anchor{2bcd}@anchor{library/array module-array}@anchor{8}@anchor{library/array translation-repo}@anchor{2bce}
@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, complex numbers.  Arrays are mutable @ref{8ff,,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

Type code

@tab

C Type

@tab

Python Type

@tab

Minimum size in bytes

@tab

Notes

@item

@code{'b'}

@tab

signed char

@tab

int

@tab

1

@tab

@item

@code{'B'}

@tab

unsigned char

@tab

int

@tab

1

@tab

@item

@code{'u'}

@tab

wchar_t

@tab

Unicode character

@tab

2

@tab

(1)

@item

@code{'w'}

@tab

Py_UCS4

@tab

Unicode character

@tab

4

@tab

(2)

@item

@code{'h'}

@tab

signed short

@tab

int

@tab

2

@tab

@item

@code{'H'}

@tab

unsigned short

@tab

int

@tab

2

@tab

@item

@code{'i'}

@tab

signed int

@tab

int

@tab

2

@tab

@item

@code{'I'}

@tab

unsigned int

@tab

int

@tab

2

@tab

@item

@code{'l'}

@tab

signed long

@tab

int

@tab

4

@tab

@item

@code{'L'}

@tab

unsigned long

@tab

int

@tab

4

@tab

@item

@code{'q'}

@tab

signed long long

@tab

int

@tab

8

@tab

@item

@code{'Q'}

@tab

unsigned long long

@tab

int

@tab

8

@tab

@item

@code{'e'}

@tab

_Float16

@tab

float

@tab

2

@tab

(3)

@item

@code{'f'}

@tab

float

@tab

float

@tab

4

@tab

@item

@code{'d'}

@tab

double

@tab

float

@tab

8

@tab

@item

@code{'Zf'}

@tab

float complex

@tab

complex

@tab

8

@tab

(4)

@item

@code{'Zd'}

@tab

double complex

@tab

complex

@tab

16

@tab

(4)

@end multitable


Notes:


@enumerate 

@item 
It can be 16 bits or 32 bits depending on the platform.


Άλλαξε στην έκδοση 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.



Καταργήθηκε από την έκδοση 3.3, αφαιρέθηκε στην έκδοση 3.16: Please migrate to @code{'w'} typecode.


@item 

Added in version 3.13.


@item 
The IEEE 754 binary16 «half precision» type was introduced in the 2008
revision of the IEEE 754 standard@footnote{https://en.wikipedia.org/wiki/IEEE_754-2008_revision}.
This type is not widely supported by C compilers.  It’s available
as _Float16 type, if the compiler supports the Annex H
of the C23 standard.


Added in version 3.15.


@item 
Complex types (@code{Zf} and @code{Zd}) are available unconditionally,
regardless on support for complex types (the Annex G of the C11 standard)
by the C compiler.
As specified in the C11 standard, each complex type is represented by a
two-element C array containing, respectively, the real and imaginary parts.


Added in version 3.15.

@end enumerate


@subsubheading Δείτε επίσης


The @ref{2a32,,ctypes} and
@ref{2a2e,,struct} modules,
as well as third-party modules like numpy@footnote{https://numpy.org/doc/stable/reference/arrays.interface.html#object.__array_interface__},
use similar – but slightly different – type codes.


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{2bcf,,array.itemsize} attribute.

The module defines the following item:

@geindex typecodes (στη μονάδα array)
@anchor{library/array array typecodes}@anchor{1de}
@deffn {Δεδομένα} array.typecodes

A tuple with all available type codes.


Άλλαξε στην έκδοση 3.15: The type changed from @ref{1df,,str} to @ref{1ce,,tuple}.

@end deffn

The module defines the following type:

@geindex array (κλάση σε array)
@anchor{library/array array array}@anchor{6c5}
@deffn {Κλάση} 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{1c7,,bytes}
or @ref{1c6,,bytearray} object, a Unicode string, or iterable over elements
of the appropriate type.

If given a @ref{1c7,,bytes} or @ref{1c6,,bytearray} object, the initializer
is passed to the new array’s @ref{1616,,frombytes()} method;
if given a Unicode string, the initializer is passed to the
@ref{2bd0,,fromunicode()} method;
otherwise, the initializer’s iterator is passed to the @ref{2bd1,,extend()} method
to add initial items to the array.

Array objects support the ordinary @ref{27bb,,mutable} @ref{8ff,,sequence} operations of indexing, slicing,
concatenation, and multiplication.  When using slice assignment, the assigned
value must be an array object with the same type code; in all other cases,
@ref{291,,TypeError} is raised. Array objects also implement the buffer interface,
and may be used wherever @ref{436,,bytes-like objects} are supported.

Raises an @ref{1e65,,auditing event} @code{array.__new__} with arguments @code{typecode}, @code{initializer}.

@geindex typecode (ιδιότητα της array.array)
@anchor{library/array array array typecode}@anchor{2bd2}
@deffn {Ιδιότητα} typecode

The typecode character used to create the array.
@end deffn

@geindex itemsize (ιδιότητα της array.array)
@anchor{library/array array array itemsize}@anchor{2bcf}
@deffn {Ιδιότητα} itemsize

The length in bytes of one array item in the internal representation.
@end deffn

@geindex append() (μέθοδος της array.array)
@anchor{library/array array array append}@anchor{2bd3}
@deffn {Μέθοδος} append (value, /)

Append a new item with the specified value to the end of the array.
@end deffn

@geindex buffer_info() (μέθοδος της array.array)
@anchor{library/array array array buffer_info}@anchor{2bd4}
@deffn {Μέθοδος} 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 Σημείωση 
When using array objects from code written in C or C++ (the only way to
effectively make use of this information), it makes more sense to use the buffer
interface supported by array objects.  This method is maintained for backward
compatibility and should be avoided in new code.  The buffer interface is
documented in @ref{311,,Buffer Protocol}.
@end quotation
@end cartouche
@end deffn

@geindex byteswap() (μέθοδος της array.array)
@anchor{library/array array array byteswap}@anchor{2bd5}
@deffn {Μέθοδος} byteswap ()

«Byteswap» all items of the array.  This is only supported for values which are
1, 2, 4, 8 or 16 bytes in size; for other types of values, @ref{30d,,RuntimeError} is
raised.  It is useful when reading data from a file written on a machine with a
different byte order.  Note, that for complex types the order of
components (the real part, followed by imaginary part) is preserved.
@end deffn

@geindex count() (μέθοδος της array.array)
@anchor{library/array array array count}@anchor{2bd6}
@deffn {Μέθοδος} count (value, /)

Return the number of occurrences of `value' in the array.
@end deffn

@geindex extend() (μέθοδος της array.array)
@anchor{library/array array array extend}@anchor{2bd1}
@deffn {Μέθοδος} extend (iterable, /)

Append items from `iterable' to the end of the array.  If `iterable' is another
array, it must have `exactly' the same type code; if not, @ref{291,,TypeError} will
be raised.  If `iterable' is not an array, it must be iterable and its elements
must be the right type to be appended to the array.
@end deffn

@geindex frombytes() (μέθοδος της array.array)
@anchor{library/array array array frombytes}@anchor{1616}
@deffn {Μέθοδος} frombytes (buffer, /)

Appends items from the @ref{436,,bytes-like object}, interpreting
its content as an array of machine values (as if it had been read
from a file using the @ref{1665,,fromfile()} method).


Added in version 3.2: @code{fromstring()} is renamed to @code{frombytes()} for clarity.

@end deffn

@geindex fromfile() (μέθοδος της array.array)
@anchor{library/array array array fromfile}@anchor{1665}
@deffn {Μέθοδος} fromfile (f, n, /)

Read `n' items (as machine values) from the @ref{156c,,file object} `f' and append
them to the end of the array.  If less than `n' items are available,
@ref{167e,,EOFError} is raised, but the items that were available are still
inserted into the array.
@end deffn

@geindex fromlist() (μέθοδος της array.array)
@anchor{library/array array array fromlist}@anchor{1964}
@deffn {Μέθοδος} fromlist (list, /)

Append items from the list.  This is equivalent to @code{for x in list:
a.append(x)} except that if there is a type error, the array is unchanged.
@end deffn

@geindex fromunicode() (μέθοδος της array.array)
@anchor{library/array array array fromunicode}@anchor{2bd0}
@deffn {Μέθοδος} fromunicode (ustr, /)

Extends this array with data from the given Unicode string.
The array must have type code @code{'u'} or @code{'w'}; otherwise a @ref{277,,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() (μέθοδος της array.array)
@anchor{library/array array array index}@anchor{bbe}
@deffn {Μέθοδος} index (value[, start[, stop]])

Return the smallest `i' such that `i' is the index of the first occurrence of
`value' in the array.  The optional arguments `start' and `stop' can be
specified to search for `value' within a subsection of the array.  Raise
@ref{277,,ValueError} if `value' is not found.


Άλλαξε στην έκδοση 3.10: Added optional `start' and `stop' parameters.

@end deffn

@geindex insert() (μέθοδος της array.array)
@anchor{library/array array array insert}@anchor{2bd7}
@deffn {Μέθοδος} insert (index, value, /)

Insert a new item `value' in the array before position `index'. Negative
values are treated as being relative to the end of the array.
@end deffn

@geindex pop() (μέθοδος της array.array)
@anchor{library/array array array pop}@anchor{2bd8}
@deffn {Μέθοδος} pop (index=-1, /)

Removes the item with the index `i' from the array and returns it. The optional
argument defaults to @code{-1}, so that by default the last item is removed and
returned.
@end deffn

@geindex remove() (μέθοδος της array.array)
@anchor{library/array array array remove}@anchor{2bd9}
@deffn {Μέθοδος} remove (value, /)

Remove the first occurrence of `value' from the array.
@end deffn

@geindex clear() (μέθοδος της array.array)
@anchor{library/array array array clear}@anchor{6c7}
@deffn {Μέθοδος} clear ()

Remove all elements from the array.


Added in version 3.13.

@end deffn

@geindex reverse() (μέθοδος της array.array)
@anchor{library/array array array reverse}@anchor{2bda}
@deffn {Μέθοδος} reverse ()

Reverse the order of the items in the array.
@end deffn

@geindex tobytes() (μέθοδος της array.array)
@anchor{library/array array array tobytes}@anchor{1615}
@deffn {Μέθοδος} tobytes ()

Convert the array to an array of machine values and return the bytes
representation (the same sequence of bytes that would be written to a file by
the @ref{1666,,tofile()} method.)


Added in version 3.2: @code{tostring()} is renamed to @code{tobytes()} for clarity.

@end deffn

@geindex tofile() (μέθοδος της array.array)
@anchor{library/array array array tofile}@anchor{1666}
@deffn {Μέθοδος} tofile (f, /)

Write all items (as machine values) to the @ref{156c,,file object} `f'.
@end deffn

@geindex tolist() (μέθοδος της array.array)
@anchor{library/array array array tolist}@anchor{2bdb}
@deffn {Μέθοδος} tolist ()

Convert the array to an ordinary list with the same items.
@end deffn

@geindex tounicode() (μέθοδος της array.array)
@anchor{library/array array array tounicode}@anchor{2bdc}
@deffn {Μέθοδος} tounicode ()

Convert the array to a Unicode string.  The array must have a type @code{'u'} or @code{'w'};
otherwise a @ref{277,,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{184,,eval()}, so long as the
@ref{6c5,,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 Δείτε επίσης



@table @asis

@item Module @ref{de,,struct}

Packing and unpacking of heterogeneous binary data.

@item NumPy@footnote{https://numpy.org/}

The NumPy package defines another array type.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node weakref — Weak references,types — Δημιουργία δυναμικών τύπων και ονόματα για ενσωματωμένους τύπους,array — Efficient arrays of numeric values,Data Types
@anchor{library/weakref doc}@anchor{2bdd}@anchor{library/weakref mod-weakref}@anchor{12bb}@anchor{library/weakref module-weakref}@anchor{11d}@anchor{library/weakref translation-repo}@anchor{2bde}@anchor{library/weakref weakref-weak-references}@anchor{2bdf}
@subsection @code{weakref} — Weak references


@geindex module; weakref

`Source code:' Lib/weakref.py@footnote{https://github.com/python/cpython/tree/main/Lib/weakref.py}


__________________________________________________________________


The @code{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{19de,,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{1b44,,WeakKeyDictionary} and @ref{1b45,,WeakValueDictionary} classes supplied by
the @code{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
@code{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{1b44,,WeakKeyDictionary} and @ref{1b45,,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{9d7,,WeakSet} implements the @ref{42b,,set} interface,
but keeps weak references to its elements, just like a
@code{WeakKeyDictionary} does.

@ref{e3e,,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{e3e,,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 @code{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{156c,,file objects}, @ref{1409,,generators},
type objects, sockets, arrays, deques, regular expression pattern objects, and code
objects.


Άλλαξε στην έκδοση 3.2: Added support for thread.lock, threading.Lock, and code objects.


Several built-in types such as @ref{4d9,,list} and @ref{188,,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

`Λεπτομέρεια υλοποίησης CPython:' Other built-in types such as @ref{1ce,,tuple} and @ref{326,,int} do not support weak
references even when subclassed.

Extension types can easily be made to support weak references; see
@ref{2be0,,Weak Reference Support}.

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{1cd,,__slots__ documentation} for details.

@geindex ref (κλάση σε weakref)
@anchor{library/weakref weakref ref}@anchor{1399}
@deffn {Κλάση} 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{a65,,None} to be
returned.  If `callback' is provided and not @code{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{13a6,,__del__()} method.

Weak references are @ref{183,,hashable} if the `object' is hashable.  They will
maintain their hash value even after the `object' was deleted.  If
@ref{9e2,,hash()} is called the first time only after the `object' was deleted,
the call will raise @ref{291,,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__ (ιδιότητα της weakref.ref)
@anchor{library/weakref weakref ref __callback__}@anchor{139a}
@deffn {Ιδιότητα} __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


Άλλαξε στην έκδοση 3.4: Added the @ref{139a,,__callback__} attribute.

@end deffn

@geindex proxy() (στη μονάδα weakref)
@anchor{library/weakref weakref proxy}@anchor{e15}
@deffn {Συνάρτηση} 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{183,,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{1399,,ref()} function.

Accessing an attribute of the proxy object after the referent is
garbage collected raises @ref{18af,,ReferenceError}.


Άλλαξε στην έκδοση 3.8: Extended the operator support on proxy objects to include the matrix
multiplication operators @code{@@} and @code{@@=}.

@end deffn

@geindex getweakrefcount() (στη μονάδα weakref)
@anchor{library/weakref weakref getweakrefcount}@anchor{2be1}
@deffn {Συνάρτηση} weakref.getweakrefcount (object)

Return the number of weak references and proxies which refer to `object'.
@end deffn

@geindex getweakrefs() (στη μονάδα weakref)
@anchor{library/weakref weakref getweakrefs}@anchor{2be2}
@deffn {Συνάρτηση} weakref.getweakrefs (object)

Return a list of all weak reference and proxy objects which refer to `object'.
@end deffn

@geindex WeakKeyDictionary (κλάση σε weakref)
@anchor{library/weakref weakref WeakKeyDictionary}@anchor{1b44}
@deffn {Κλάση} 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


Άλλαξε στην έκδοση 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{1b44,,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() (μέθοδος της weakref.WeakKeyDictionary)
@anchor{library/weakref weakref WeakKeyDictionary keyrefs}@anchor{2be3}
@deffn {Μέθοδος} WeakKeyDictionary.keyrefs ()

Return an iterable of the weak references to the keys.
@end deffn

@geindex WeakValueDictionary (κλάση σε weakref)
@anchor{library/weakref weakref WeakValueDictionary}@anchor{1b45}
@deffn {Κλάση} 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.


Άλλαξε στην έκδοση 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{1b45,,WeakValueDictionary} objects have an additional method that has the
same issues as the @ref{2be3,,WeakKeyDictionary.keyrefs()} method.

@geindex valuerefs() (μέθοδος της weakref.WeakValueDictionary)
@anchor{library/weakref weakref WeakValueDictionary valuerefs}@anchor{2be4}
@deffn {Μέθοδος} WeakValueDictionary.valuerefs ()

Return an iterable of the weak references to the values.
@end deffn

@geindex WeakSet (κλάση σε weakref)
@anchor{library/weakref weakref WeakSet}@anchor{9d7}
@deffn {Κλάση} 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 (κλάση σε weakref)
@anchor{library/weakref weakref WeakMethod}@anchor{1398}
@deffn {Κλάση} weakref.WeakMethod (method[, callback])

A custom @ref{1399,,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.  @code{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{1399,,ref()} function.


Added in version 3.4.

@end deffn

@geindex finalize (κλάση σε weakref)
@anchor{library/weakref weakref finalize}@anchor{e3e}
@deffn {Κλάση} 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{a65,,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{13a6,,__del__()} method or a weak reference’s
callback.

When the program exits, each remaining live finalizer is called
unless its @ref{d,,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{1a0,,interpreter shutdown} when module globals are liable to have
been replaced by @ref{a65,,None}.

@geindex __call__() (μέθοδος της weakref.finalize)
@anchor{library/weakref weakref finalize __call__}@anchor{2be5}
@deffn {Μέθοδος} __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{a65,,None}.
@end deffn

@geindex detach() (μέθοδος της weakref.finalize)
@anchor{library/weakref weakref finalize detach}@anchor{2be6}
@deffn {Μέθοδος} 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{a65,,None}.
@end deffn

@geindex peek() (μέθοδος της weakref.finalize)
@anchor{library/weakref weakref finalize peek}@anchor{2be7}
@deffn {Μέθοδος} peek ()

If `self' is alive then return the tuple @code{(obj, func, args,
kwargs)}.  If `self' is dead then return @ref{a65,,None}.
@end deffn

@geindex alive (ιδιότητα της weakref.finalize)
@anchor{library/weakref weakref finalize alive}@anchor{2be8}
@deffn {Ιδιότητα} alive

Property which is true if the finalizer is alive, false otherwise.
@end deffn

@geindex atexit (ιδιότητα της weakref.finalize)
@anchor{library/weakref weakref finalize atexit}@anchor{2be9}
@deffn {Ιδιότητα} atexit

A writable boolean property which by default is true.  When the
program exits, it calls all remaining live finalizers for which
@ref{2be9,,atexit} is true.  They are called in reverse order of
creation.
@end deffn

@cartouche
@quotation Σημείωση 
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


Added in version 3.4.

@end deffn

@geindex ReferenceType (στη μονάδα weakref)
@anchor{library/weakref weakref ReferenceType}@anchor{1d5b}
@deffn {Δεδομένα} weakref.ReferenceType

The type object for weak references objects.
@end deffn

@geindex ProxyType (στη μονάδα weakref)
@anchor{library/weakref weakref ProxyType}@anchor{1d5c}
@deffn {Δεδομένα} weakref.ProxyType

The type object for proxies of objects which are not callable.
@end deffn

@geindex CallableProxyType (στη μονάδα weakref)
@anchor{library/weakref weakref CallableProxyType}@anchor{1d5d}
@deffn {Δεδομένα} weakref.CallableProxyType

The type object for proxies of callable objects.
@end deffn

@geindex ProxyTypes (στη μονάδα weakref)
@anchor{library/weakref weakref ProxyTypes}@anchor{2bea}
@deffn {Δεδομένα} 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 Δείτε επίσης



@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
* Weak Reference Objects:: 
* Example: Example<2>. 
* Finalizer Objects:: 
* Comparing finalizers with __del__() methods: Comparing finalizers with __del__ methods. 

@end menu

@node Weak Reference Objects,Example<2>,,weakref — Weak references
@anchor{library/weakref weak-reference-objects}@anchor{2beb}@anchor{library/weakref weakref-objects}@anchor{2bec}
@subsubsection Weak Reference Objects


Weak reference objects have no methods and no attributes besides
@ref{139a,,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{a65,,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{1399,,ref} objects can be created through subclassing.
This is used in the implementation of the @ref{1b45,,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{1399,,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 Example<2>,Finalizer Objects,Weak Reference Objects,weakref — Weak references
@anchor{library/weakref example}@anchor{2bed}@anchor{library/weakref weakref-example}@anchor{2bee}
@subsubsection Example


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,Example<2>,weakref — Weak references
@anchor{library/weakref finalize-examples}@anchor{2bef}@anchor{library/weakref finalizer-objects}@anchor{2bf0}
@subsubsection Finalizer Objects


The main benefit of using @ref{e3e,,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{2be6,,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{2be9,,atexit} attribute to
@ref{ef5,,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{2bf1}
@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{13a6,,__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{13a6,,__del__()} methods no longer prevent
reference cycles from being garbage collected, and module globals are
no longer forced to @ref{a65,,None} during @ref{1a0,,interpreter shutdown}.
So this code should work without any issues on CPython.

However, handling of @ref{13a6,,__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 Σημείωση 
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{c54,,atexit.register()}, @code{try: ... finally: ...} and @code{with: ...}
do not guarantee that cleanup occurs either.
@end quotation
@end cartouche

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node types — Δημιουργία δυναμικών τύπων και ονόματα για ενσωματωμένους τύπους,copy — Shallow and deep copy operations,weakref — Weak references,Data Types
@anchor{library/types doc}@anchor{2bf2}@anchor{library/types module-types}@anchor{10c}@anchor{library/types translation-repo}@anchor{2bf3}@anchor{library/types types-dynamic-type-creation-and-names-for-built-in-types}@anchor{2bf4}
@subsection @code{types} — Δημιουργία δυναμικών τύπων και ονόματα για ενσωματωμένους τύπους


@geindex module; types

`Πηγαίος κώδικας:' Lib/types.py@footnote{https://github.com/python/cpython/tree/main/Lib/types.py}


__________________________________________________________________


Αυτό το module ορίζει συναρτήσεις βοηθητικού προγράμματος για να διευκολύνει τη δυναμική δημιουργία νέων τύπων.

Ορίζει επίσης ονόματα για κάποιους τύπους αντικειμένων που χρησιμοποιούνται από τον τυπικό διερμηνέα Python, αλλά δεν εκτίθενται ως ενσωματωμένα όπως οι @ref{326,,int} ή @ref{1df,,str}.

Τέλος, παρέχει κάποιες πρόσθετες κλάσεις και συναρτήσεις σχετικές με τους τύπους που δεν είναι αρκετά θεμελιώδεις ώστε να είναι ενσωματωμένες.

@menu
* Δημιουργία Δυναμικών Τύπων:: 
* Τυπικοί Τύποι Διερμηνέα:: 
* Πρόσθετες βοηθητικές κλάσεις και συναρτήσεις:: 
* Βοηθητικές Συναρτήσεις Coroutine:: 

@end menu

@node Δημιουργία Δυναμικών Τύπων,Τυπικοί Τύποι Διερμηνέα,,types — Δημιουργία δυναμικών τύπων και ονόματα για ενσωματωμένους τύπους
@anchor{library/types dynamic-type-creation}@anchor{2bf5}
@subsubsection Δημιουργία Δυναμικών Τύπων


@geindex new_class() (στη μονάδα types)
@anchor{library/types types new_class}@anchor{150c}
@deffn {Συνάρτηση} types.new_class (name, bases=(), kwds=None, exec_body=None)

Δημιουργεί ένα αντικείμενο κλάσης δυναμικά χρησιμοποιώντας την κατάλληλη μετακλάση.

Τα τρία πρώτα ορίσματα είναι τα στοιχεία που αποτελούν την επικεφαλίδα του ορισμού κλάσης: το όνομα της κλάσης, οι βάσεις κλάσης (με τη σειρά), τα ορίσματα λέξεων-κλειδιών (όπως @code{metaclass}).

Το όρισμα `exec_body' είναι μια συνάρτηση που χρησιμοποιείται για να γεμίσει το φρέσκο δημιουργημένο namespace κλάσης. Πρέπει να δέχεται το namespace της κλάσης ως μοναδικό όρισμα και να ενημερώνει άμεσα το namespace με τα περιεχόμενα της κλάσης. Αν δεν παρέχεται καμία συνάρτηση, έχει το ίδιο αποτέλεσμα με την παράδοση @code{lambda ns: None}.


Added in version 3.3.

@end deffn

@geindex prepare_class() (στη μονάδα types)
@anchor{library/types types prepare_class}@anchor{150d}
@deffn {Συνάρτηση} types.prepare_class (name, bases=(), kwds=None)

Υπολογίζει την κατάλληλη μετακλάση και δημιουργεί το namespace της κλάσης.

Τα ορίσματα είναι τα στοιχεία που αποτελούν την επικεφαλίδα του ορισμού κλάσης: το όνομα της κλάσης, οι βάσεις κλάσης (με τη σειρά) και τα ορίσματα λέξεων-κλειδιών (όπως @code{metaclass}).

Η επιστρεφόμενη τιμή είναι μια 3-πλειάδα: @code{metaclass, namespace, kwds}

`metaclass' είναι η κατάλληλη μετακλάση, `namespace' είναι το προετοιμασμένο namespace κλάσης και `kwds' είναι μια ενημερωμένη αντιγραφή του περασμένου ορίσματος `kwds' με οποιαδήποτε είσοδο @code{'metaclass'} αφαιρεθεί. Αν δεν περαστεί κανένα όρισμα `kwds', αυτό θα είναι ένα κενό dict.


Added in version 3.3.



Άλλαξε στην έκδοση 3.6: Η προεπιλεγμένη τιμή για το στοιχείο @code{namespace} της επιστρεφόμενης πλειάδας έχει αλλάξει. Τώρα χρησιμοποιείται μια χαρτογράφηση που διατηρεί τη σειρά εισαγωγής όταν η μετακλάση δεν έχει μέθοδο @code{__prepare__}.

@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item @ref{25b3,,Μετα-κλάσεις}

Πλήρεις λεπτομέρειες της διαδικασίας δημιουργίας κλάσης που υποστηρίζεται από αυτές τις συναρτήσεις

@geindex Python Enhancement Proposals; PEP 3115

@item PEP 3115@footnote{https://peps.python.org/pep-3115/} - Μετακλάσεις στην Python 3000

Εισήγαγε το hook namespace @code{__prepare__}
@end table


@geindex resolve_bases() (στη μονάδα types)
@anchor{library/types types resolve_bases}@anchor{f5b}
@deffn {Συνάρτηση} types.resolve_bases (bases)

Επιλύει τις καταχωρήσεις MRO δυναμικά όπως καθορίζεται από την 
@geindex Python Enhancement Proposals; PEP 560
PEP 560@footnote{https://peps.python.org/pep-0560/}.

Αυτή η συνάρτηση αναζητά στοιχεία στις `bases' που δεν είναι στιγμιότυπα της @ref{186,,type}, και επιστρέφει μια πλειάδα όπου κάθε τέτοιο αντικείμενο που έχει μια μέθοδο @ref{eb1,,__mro_entries__()} αντικαθίσταται με ένα αποσυσκευασμένο αποτέλεσμα της κλήσης αυτής της μεθόδου. Αν ένα στοιχείο `bases' είναι στιγμιότυπο της @code{type}, ή δεν έχει μια μέθοδο @code{__mro_entries__()}, τότε περιλαμβάνεται στην επιστρεφόμενη πλειάδα χωρίς αλλαγές.


Added in version 3.7.

@end deffn

@geindex get_original_bases() (στη μονάδα types)
@anchor{library/types types get_original_bases}@anchor{8de}
@deffn {Συνάρτηση} types.get_original_bases (cls, /)

Επιστρέφει την πλειάδα αντικειμένων που δόθηκαν αρχικά ως βάσεις του `cls' πριν κληθεί η μέθοδος @ref{eb1,,__mro_entries__()} σε οποιαδήποτε βάση (ακολουθώντας τους μηχανισμούς που καθορίζονται στην 
@geindex Python Enhancement Proposals; PEP 560
PEP 560@footnote{https://peps.python.org/pep-0560/}). Αυτό είναι χρήσιμο για την ανάλυση των @ref{8df,,Generics}.

Για κλάσεις που έχουν ένα χαρακτηριστικό @code{__orig_bases__}, αυτή η συνάρτηση επιστρέφει την τιμή του @code{cls.__orig_bases__}. Για κλάσεις χωρίς το χαρακτηριστικό @code{__orig_bases__}, επιστρέφεται @ref{184e,,cls.__bases__}.

Παραδείγματα:

@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


Added in version 3.12.

@end deffn


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 560
PEP 560@footnote{https://peps.python.org/pep-0560/} - Βασική υποστήριξη για το module typing και γενικούς τύπους


@node Τυπικοί Τύποι Διερμηνέα,Πρόσθετες βοηθητικές κλάσεις και συναρτήσεις,Δημιουργία Δυναμικών Τύπων,types — Δημιουργία δυναμικών τύπων και ονόματα για ενσωματωμένους τύπους
@anchor{library/types standard-interpreter-types}@anchor{2bf6}
@subsubsection Τυπικοί Τύποι Διερμηνέα


Αυτό το module παρέχει ονόματα για πολλούς από τους τύπους που απαιτούνται για να υλοποιηθεί ένας διερμηνέας Python. Αποφεύγει σκόπιμα να συμπεριλάβει κάποιους από τους τύπους που προκύπτουν μόνο παρεμπιπτόντως κατά τη διάρκεια της επεξεργασίας, όπως ο τύπος @code{listiterator}.

Τυπική χρήση αυτών των ονομάτων είναι για ελέγχους @ref{2ef,,isinstance()} ή @ref{2f0,,issubclass()}.

Αν δημιουργήσετε στιγμιότυπα από αυτούς τους τύπους, σημειώστε ότι οι υπογραφές μπορεί να διαφέρουν μεταξύ εκδόσεων Python.

Τυπικά ονόματα ορίζονται για τους παρακάτω τύπους:

@geindex NoneType (στη μονάδα types)
@anchor{library/types types NoneType}@anchor{c2a}
@deffn {Δεδομένα} types.NoneType

Ο τύπος του @ref{a65,,None}.


Added in version 3.10.

@end deffn

@geindex FunctionType (στη μονάδα types)
@geindex LambdaType (στη μονάδα types)
@anchor{library/types types FunctionType}@anchor{c59}
@deffn {Δεδομένα} types.FunctionType
@anchor{library/types types LambdaType}@anchor{2bf7}
@deffnx {Δεδομένα} types.LambdaType

Ο τύπος των συναρτήσεων που ορίζονται από τον χρήστη και των συναρτήσεων που δημιουργούνται από εκφράσεις @ref{1642,,lambda}.

Κάνει raise ένα @ref{1e65,,auditing event} @code{function.__new__} με το όρισμα @code{code}.

Το audit event συμβαίνει μόνο για άμεσες δημιουργίες αντικειμένων συναρτήσεων και δεν γίνεται raise κατά τη διάρκεια της κανονικής μεταγλώττισης.
@end deffn

@geindex GeneratorType (στη μονάδα types)
@anchor{library/types types GeneratorType}@anchor{1bb5}
@deffn {Δεδομένα} types.GeneratorType

Ο τύπος των αντικειμένων @ref{1409,,generator}-iterator, που δημιουργούνται από συναρτήσεις γεννητριών.
@end deffn

@geindex CoroutineType (στη μονάδα types)
@anchor{library/types types CoroutineType}@anchor{123a}
@deffn {Δεδομένα} types.CoroutineType

Ο τύπος των αντικειμένων @ref{8a2,,coroutine}, που δημιουργούνται από συναρτήσεις @ref{9cf,,async def}.


Added in version 3.5.

@end deffn

@geindex AsyncGeneratorType (στη μονάδα types)
@anchor{library/types types AsyncGeneratorType}@anchor{2bf8}
@deffn {Δεδομένα} types.AsyncGeneratorType

Ο τύπος των αντικειμένων @ref{2692,,asynchronous generator}-iterator, που δημιουργούνται από ασύγχρονες συναρτήσεις γεννητριών.


Added in version 3.6.

@end deffn

@geindex CodeType (κλάση σε types)
@anchor{library/types types CodeType}@anchor{2e1}
@deffn {Κλάση} types.CodeType (**kwargs)

@geindex built-in συνάρτηση;compile

Ο τύπος των @ref{6eb,,code objects} όπως επιστρέφεται από τη @ref{1c8,,compile()}.

Κάνει raise ένα @ref{1e65,,auditing event} @code{code.__new__} με τα ορίσματα @code{code}, @code{filename}, @code{name}, @code{argcount}, @code{posonlyargcount}, @code{kwonlyargcount}, @code{nlocals}, @code{stacksize}, @code{flags}.

Σημειώστε ότι τα ελεγχόμενα ορίσματα μπορεί να μην ταιριάζουν με τα ονόματα ή τις θέσεις που απαιτούνται από τον αρχικοποιητή. Το audit event συμβαίνει μόνο για άμεσες δημιουργίες αντικειμένων κώδικα και δεν γίνεται raise κατά τη διάρκεια της κανονικής μεταγλώττισης.
@end deffn

@geindex CellType (στη μονάδα types)
@anchor{library/types types CellType}@anchor{2bf9}
@deffn {Δεδομένα} types.CellType

Ο τύπος για τα αντικείμενα κελιών: τέτοια αντικείμενα χρησιμοποιούνται ως δοχεία για τις @ref{1ab7,,closure variables} μιας συνάρτησης.


Added in version 3.8.

@end deffn

@geindex MethodType (στη μονάδα types)
@anchor{library/types types MethodType}@anchor{1d7f}
@deffn {Δεδομένα} types.MethodType

Ο τύπος των μεθόδων των στιγμιοτύπων κλάσεων που ορίζονται από τον χρήστη.
@end deffn

@geindex BuiltinFunctionType (στη μονάδα types)
@geindex BuiltinMethodType (στη μονάδα types)
@anchor{library/types types BuiltinFunctionType}@anchor{2bfa}
@deffn {Δεδομένα} types.BuiltinFunctionType
@anchor{library/types types BuiltinMethodType}@anchor{2bfb}
@deffnx {Δεδομένα} types.BuiltinMethodType

Ο τύπος των ενσωματωμένων συναρτήσεων όπως @ref{a1f,,len()} ή @ref{4ff,,sys.exit()}, και μεθόδων ενσωματωμένων κλάσεων. (Εδώ, ο όρος «built-in» σημαίνει «γραμμένος σε C».)
@end deffn

@geindex WrapperDescriptorType (στη μονάδα types)
@anchor{library/types types WrapperDescriptorType}@anchor{f58}
@deffn {Δεδομένα} types.WrapperDescriptorType

Ο τύπος των μεθόδων κάποιων ενσωματωμένων τύπων δεδομένων και βάσεων κλάσεων όπως @ref{2fa,,object.__init__()} ή @ref{1645,,object.__lt__()}.


Added in version 3.7.

@end deffn

@geindex MethodWrapperType (στη μονάδα types)
@anchor{library/types types MethodWrapperType}@anchor{a3a}
@deffn {Δεδομένα} types.MethodWrapperType

Ο τύπος των `bound' μεθόδων κάποιων ενσωματωμένων τύπων δεδομένων και βάσεων κλάσεων. Για παράδειγμα είναι ο τύπος του @code{object().__str__}.


Added in version 3.7.

@end deffn

@geindex NotImplementedType (στη μονάδα types)
@anchor{library/types types NotImplementedType}@anchor{c2b}
@deffn {Δεδομένα} types.NotImplementedType

Ο τύπος του @ref{440,,NotImplemented}.


Added in version 3.10.

@end deffn

@geindex MethodDescriptorType (στη μονάδα types)
@anchor{library/types types MethodDescriptorType}@anchor{f59}
@deffn {Δεδομένα} types.MethodDescriptorType

Ο τύπος των μεθόδων κάποιων ενσωματωμένων τύπων δεδομένων όπως @ref{2803,,str.join()}.


Added in version 3.7.

@end deffn

@geindex ClassMethodDescriptorType (στη μονάδα types)
@anchor{library/types types ClassMethodDescriptorType}@anchor{f5a}
@deffn {Δεδομένα} types.ClassMethodDescriptorType

Ο τύπος των `unbound' μεθόδων κλάσης κάποιων ενσωματωμένων τύπων δεδομένων όπως @code{dict.__dict__['fromkeys']}.


Added in version 3.7.

@end deffn

@geindex ModuleType (κλάση σε types)
@anchor{library/types types ModuleType}@anchor{11c7}
@deffn {Κλάση} types.ModuleType (name, doc=None)

Ο τύπος των @ref{1be7,,modules}. Ο κατασκευαστής δέχεται το όνομα του module που θα δημιουργηθεί και προαιρετικά την @ref{24dd,,docstring} του.


@subsubheading Δείτε επίσης



@table @asis

@item @ref{254f,,Documentation on module objects}

Παρέχει λεπτομέρειες για τα ειδικά χαρακτηριστικά που μπορούν να βρεθούν σε στιγμιότυπα της @code{ModuleType}.

@item @ref{11c6,,importlib.util.module_from_spec()}

Τα modules που δημιουργούνται χρησιμοποιώντας τον κατασκευαστή @code{ModuleType} δημιουργούνται με πολλά από τα ειδικά χαρακτηριστικά τους μη ρυθμισμένα ή ρυθμισμένα σε προεπιλεγμένες τιμές. Η @code{module_from_spec()} παρέχει έναν πιο ανθεκτικό τρόπο δημιουργίας στιγμιοτύπων @code{ModuleType} που διασφαλίζει ότι τα διάφορα χαρακτηριστικά είναι ρυθμισμένα κατάλληλα.
@end table

@end deffn

@geindex EllipsisType (στη μονάδα types)
@anchor{library/types types EllipsisType}@anchor{c29}
@deffn {Δεδομένα} types.EllipsisType

Ο τύπος του @ref{2519,,Ellipsis}.


Added in version 3.10.

@end deffn

@geindex GenericAlias (κλάση σε types)
@anchor{library/types types GenericAlias}@anchor{bc7}
@deffn {Κλάση} types.GenericAlias (t_origin, t_args)

O τύπος των @ref{a9f,,parameterized generics} όπως το @code{list[int]}.

@code{t_origin} θα πρέπει να είναι μια μη παραμετροποιημένη γενική κλάση, όπως @code{list}, @code{tuple} ή @code{dict}. @code{t_args} θα πρέπει να είναι μια @ref{1ce,,tuple} (πιθανώς μήκους 1) τύπων που παραμετροποιούν το @code{t_origin}:

@example
>>> from types import GenericAlias

>>> list[int] == GenericAlias(list, (int,))
True
>>> dict[str, int] == GenericAlias(dict, (str, int))
True
@end example


Added in version 3.9.



Άλλαξε στην έκδοση 3.9.2: Αυτός ο τύπος μπορεί πλέον να κληρονομείται.



@subsubheading Δείτε επίσης



@table @asis

@item @ref{a9f,,Generic Alias Types}

Λεπτομερής τεκμηρίωση για τα στιγμιότυπα της @code{types.GenericAlias}

@geindex Python Enhancement Proposals; PEP 585

@item PEP 585@footnote{https://peps.python.org/pep-0585/} - Υποδείξεις τύπου Generics σε τυπικές συλλογές

Εισαγωγή στην κλάση @code{types.GenericAlias}
@end table

@end deffn

@geindex UnionType (κλάση σε types)
@anchor{library/types types UnionType}@anchor{527}
@deffn {Κλάση} types.UnionType

Ο τύπος των @ref{ba2,,union type expressions}.


Added in version 3.10.



Άλλαξε στην έκδοση 3.14: Αυτό είναι τώρα ένα ψευδώνυμο για την κλάση @ref{341,,typing.Union}.

@end deffn

@geindex TracebackType (κλάση σε types)
@anchor{library/types types TracebackType}@anchor{eb8}
@deffn {Κλάση} types.TracebackType (tb_next, tb_frame, tb_lasti, tb_lineno)

Ο τύπος των αντικειμένων traceback όπως αυτά που βρίσκονται στο @code{sys.exception().__traceback__}.

Δείτε @ref{eba,,the language reference} για λεπτομέρειες σχετικά με τα διαθέσιμα χαρακτηριστικά και τις λειτουργίες, καθώς και οδηγίες για τη δυναμική δημιουργία tracebacks.
@end deffn

@geindex FrameType (στη μονάδα types)
@anchor{library/types types FrameType}@anchor{1de6}
@deffn {Δεδομένα} types.FrameType

Ο τύπος των @ref{acd,,frame objects} όπως αυτά που βρίσκονται στο @ref{2595,,tb.tb_frame} αν το @code{tb} είναι ένα αντικείμενο traceback.
@end deffn

@geindex FrameLocalsProxyType (στη μονάδα types)
@anchor{library/types types FrameLocalsProxyType}@anchor{28c}
@deffn {Δεδομένα} types.FrameLocalsProxyType

The type of frame locals proxy objects, as found on the
@ref{28d,,frame.f_locals} attribute.


Added in version 3.15.



@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}

@end deffn

@geindex LazyImportType (στη μονάδα types)
@anchor{library/types types LazyImportType}@anchor{17d}
@deffn {Δεδομένα} types.LazyImportType

The type of lazy import proxy objects. These objects are created when a
module is lazily imported and serve as placeholders until the module is
actually accessed. This type can be used to detect lazy imports
programmatically.


Added in version 3.15.



@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 810
PEP 810@footnote{https://peps.python.org/pep-0810/}

@end deffn

@geindex GetSetDescriptorType (στη μονάδα types)
@anchor{library/types types GetSetDescriptorType}@anchor{2bfc}
@deffn {Δεδομένα} types.GetSetDescriptorType

Ο τύπος των αντικειμένων που ορίζονται σε επεκτάσιμα modules με @code{PyGetSetDef}, όπως @ref{28d,,FrameType.f_locals} ή @code{array.array.typecode}. Αυτός ο τύπος χρησιμοποιείται ως περιγραφέας για τα χαρακτηριστικά του αντικειμένου. Έχει τον ίδιο σκοπό με τον τύπο @ref{6bb,,property}, αλλά για κλάσεις που ορίζονται σε επεκτάσιμα modules.
@end deffn

@geindex MemberDescriptorType (στη μονάδα types)
@anchor{library/types types MemberDescriptorType}@anchor{2bfd}
@deffn {Δεδομένα} types.MemberDescriptorType

Ο τύπος των αντικειμένων που ορίζονται σε επεκτάσιμα modules με @code{PyMemberDef}, όπως το @code{datetime.timedelta.days}. Αυτός ο τύπος χρησιμοποιείται ως περιγραφέας για απλά μέλη δεδομένων C που χρησιμοποιούν τυπικές συναρτήσεις μετατροπής. Έχει τον ίδιο σκοπό με τον τύπο @ref{6bb,,property}, αλλά για κλάσεις που ορίζονται σε επεκτάσιμα modules.

Επιπλέον, όταν μια κλάση ορίζεται με ένα χαρακτηριστικό @ref{188d,,__slots__}, τότε για κάθε slot, θα προστεθεί ένα στιγμιότυπο της @code{MemberDescriptorType} ως χαρακτηριστικό στην κλάση. Αυτό επιτρέπει στο slot να εμφανίζεται στο @ref{101b,,__dict__} της κλάσης.

Σε άλλες υλοποιήσεις της Python, αυτός ο τύπος μπορεί να είναι ταυτόσημος με το @code{GetSetDescriptorType}.
@end deffn

@geindex MappingProxyType (κλάση σε types)
@anchor{library/types types MappingProxyType}@anchor{189}
@deffn {Κλάση} types.MappingProxyType (mapping)

Read-only αναγνωριστικό για μια αντιστοίχιση. Παρέχει μια δυναμική προβολή στις καταχωρήσεις της αντιστοίχισης, που σημαίνει ότι όταν η αντιστοίχιση αλλάζει, η προβολή αντικατοπτρίζει αυτές τις αλλαγές.


Added in version 3.3.



Άλλαξε στην έκδοση 3.9: Ενημερώθηκε για να υποστηρίζει τον νέο τελεστή ένωσης (@code{|}) από την 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}, ο οποίος απλά αναθέτει στην υποκείμενη αντιστοίχιση.



@deffn {Describe} key in proxy

Επιστρέφει @code{True} αν η υποκείμενη αντιστοίχιση έχει το κλειδί `key', αλλιώς @code{False}.
@end deffn


@deffn {Describe} proxy[key]

Επιστρέφει το στοιχείο της υποκείμενης αντιστοίχισης με το κλειδί `key'. Κάνει raise μια @ref{7df,,KeyError} αν το `key' δεν είναι στην υποκείμενη αντιστοίχιση.
@end deffn


@deffn {Describe} iter(proxy)

Επιστρέφει έναν iterator πάνω από τα κλειδιά της υποκείμενης αντιστοίχισης. Αυτό είναι μια συντόμευση για @code{iter(proxy.keys())}.
@end deffn


@deffn {Describe} len(proxy)

Επιστρέφει τον αριθμό των στοιχείων στην υποκείμενη αντιστοίχιση.
@end deffn

@geindex copy() (μέθοδος της types.MappingProxyType)
@anchor{library/types types MappingProxyType copy}@anchor{2bfe}
@deffn {Μέθοδος} copy ()

Επιστρέφει ένα ρηχό αντίγραφο της υποκείμενης αντιστοίχισης.
@end deffn

@geindex get() (μέθοδος της types.MappingProxyType)
@anchor{library/types types MappingProxyType get}@anchor{2bff}
@deffn {Μέθοδος} get (key[, default])

Επιστρέφει την τιμή για το `key' αν το `key' είναι στην υποκείμενη αντιστοίχιση, αλλιώς `default'. Αν το `default' δεν δοθεί, προεπιλέγεται σε @code{None}, έτσι ώστε αυτή η μέθοδος να μην κάνει ποτέ raise μια @ref{7df,,KeyError}.
@end deffn

@geindex items() (μέθοδος της types.MappingProxyType)
@anchor{library/types types MappingProxyType items}@anchor{2c00}
@deffn {Μέθοδος} items ()

Επιστρέφει μια νέα προβολή των στοιχείων της υποκείμενης αντιστοίχισης (ζεύγη @code{(key, value)}).
@end deffn

@geindex keys() (μέθοδος της types.MappingProxyType)
@anchor{library/types types MappingProxyType keys}@anchor{2c01}
@deffn {Μέθοδος} keys ()

Επιστρέφει μια νέα προβολή των κλειδιών της υποκείμενης αντιστοίχισης.
@end deffn

@geindex values() (μέθοδος της types.MappingProxyType)
@anchor{library/types types MappingProxyType values}@anchor{2c02}
@deffn {Μέθοδος} values ()

Επιστρέφει μια νέα προβολή των τιμών της υποκείμενης αντιστοίχισης.
@end deffn


@deffn {Describe} reversed(proxy)

Επιστρέφει έναν αντίστροφο iterator πάνω από τα κλειδιά της υποκείμενης αντιστοίχισης.


Added in version 3.9.

@end deffn


@deffn {Describe} hash(proxy)

Επιστρέφει ένα hash της υποκείμενης αντιστοίχισης.


Added in version 3.12.

@end deffn
@end deffn

@geindex CapsuleType (κλάση σε types)
@anchor{library/types types CapsuleType}@anchor{2c03}
@deffn {Κλάση} types.CapsuleType

Ο τύπος των @ref{2c04,,capsule objects}.


Added in version 3.13.

@end deffn

@node Πρόσθετες βοηθητικές κλάσεις και συναρτήσεις,Βοηθητικές Συναρτήσεις Coroutine,Τυπικοί Τύποι Διερμηνέα,types — Δημιουργία δυναμικών τύπων και ονόματα για ενσωματωμένους τύπους
@anchor{library/types additional-utility-classes-and-functions}@anchor{2c05}
@subsubsection Πρόσθετες βοηθητικές κλάσεις και συναρτήσεις


@geindex SimpleNamespace (κλάση σε types)
@anchor{library/types types SimpleNamespace}@anchor{6ea}
@deffn {Κλάση} types.SimpleNamespace

Απλή υποκλάση @ref{e4d,,object} που παρέχει πρόσβαση χαρακτηριστικών στο χώρο ονομάτων της, καθώς και μια σημαντική αναπαράσταση.

Σε αντίθεση με την @ref{e4d,,object}, με την @code{SimpleNamespace} μπορείτε να προσθέσετε και να αφαιρέσετε χαρακτηριστικά.

Τα αντικείμενα @ref{6ea,,SimpleNamespace} μπορούν να αρχικοποιηθούν με τον ίδιο τρόπο όπως η @ref{188,,dict}: είτε με ονόματα χαρακτηριστικών, είτε με ένα μόνο οριστικό όρισμα, είτε και με τα δύο. Όταν αρχικοποιούνται με ονόματα χαρακτηριστικών, αυτά προστίθενται απευθείας στο υποκείμενο χώρο ονομάτων. Εναλλακτικά, όταν αρχικοποιούνται με ένα οριστικό όρισμα, το υποκείμενο χώρο ονομάτων θα ενημερωθεί με ζεύγη κλειδιού-τιμής από αυτό το όρισμα (είτε ένα αντικείμενο αντιστοίχισης είτε ένα @ref{15ce,,iterable} αντικείμενο που παράγει ζεύγη κλειδιού-τιμής). Όλα αυτά τα κλειδιά πρέπει να είναι συμβολοσειρές.

Ο τύπος είναι περίπου ισοδύναμος με τον παρακάτω κώδικα:

@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} μπορεί να είναι χρήσιμο ως αντικατάσταση για το @code{class NS: pass}. Ωστόσο, για έναν δομημένο τύπο εγγραφής χρησιμοποιήστε @ref{1cf,,namedtuple()} αντί αυτού.

@code{SimpleNamespace} αντικείμενα υποστηρίζονται από την @ref{45a,,copy.replace()}.


Added in version 3.3.



Άλλαξε στην έκδοση 3.9: Η σειρά των χαρακτηριστικών στην αναπαράσταση άλλαξε από αλφαβητική σε εισαγωγή (όπως το @code{dict}).



Άλλαξε στην έκδοση 3.13: Προστέθηκε υποστήριξη για ένα προαιρετικό οριστικό όρισμα.

@end deffn

@geindex DynamicClassAttribute() (στη μονάδα types)
@anchor{library/types types DynamicClassAttribute}@anchor{a1b}
@deffn {Συνάρτηση} types.DynamicClassAttribute (fget=None, fset=None, fdel=None, doc=None)

Δρομολόγηση πρόσβασης χαρακτηριστικών σε μια κλάση στο __getattr__.

Αυτός είναι ένας περιγραφέας, που χρησιμοποιείται για τον ορισμό χαρακτηριστικών που δρουν διαφορετικά όταν προσπελάζονται μέσω ενός στιγμιότυπου και μέσω μιας κλάσης. Η πρόσβαση στο στιγμιότυπο παραμένει κανονική, αλλά η πρόσβαση σε ένα χαρακτηριστικό μέσω μιας κλάσης θα δρομολογηθεί στη μέθοδο __getattr__ της κλάσης. Αυτό γίνεται κάνοντας raise ένα AttributeError.

Αυτό επιτρέπει να έχετε ιδιότητες ενεργές σε ένα στιγμιότυπο και να έχετε εικονικά χαρακτηριστικά στην κλάση με το ίδιο όνομα (βλ. @ref{a21,,enum.Enum} για παράδειγμα).


Added in version 3.4.

@end deffn

@node Βοηθητικές Συναρτήσεις Coroutine,,Πρόσθετες βοηθητικές κλάσεις και συναρτήσεις,types — Δημιουργία δυναμικών τύπων και ονόματα για ενσωματωμένους τύπους
@anchor{library/types coroutine-utility-functions}@anchor{2c06}
@subsubsection Βοηθητικές Συναρτήσεις Coroutine


@geindex coroutine() (στη μονάδα types)
@anchor{library/types types coroutine}@anchor{1239}
@deffn {Συνάρτηση} types.coroutine (gen_func)

Αυτή η συνάρτηση μετατρέπει μια @ref{1409,,generator} συνάρτηση σε μια @ref{112c,,coroutine function} που επιστρέφει μια coroutine βασισμένη σε γεννήτρια. Η coroutine βασισμένη σε γεννήτρια είναι ακόμα ένας @ref{f9e,,generator iterator}, αλλά θεωρείται επίσης ότι είναι ένα αντικείμενο @ref{8a2,,coroutine} και είναι @ref{6cf,,awaitable}. Ωστόσο, δεν είναι απαραίτητο να υλοποιεί τη μέθοδο @ref{112e,,__await__()}.

Αν το `gen_func' είναι μια γεννήτρια συνάρτηση, θα τροποποιηθεί επιτόπου.

Αν το `gen_func' δεν είναι μια γεννήτρια συνάρτηση, θα τυλιχθεί. Αν επιστρέφει μια παρουσία της @ref{1193,,collections.abc.Generator}, το στιγμιότυπο θα τυλιχθεί σε ένα `awaitable' αντικείμενο proxy. Όλοι οι άλλοι τύποι αντικειμένων θα επιστραφούν όπως είναι.


Added in version 3.5.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node copy — Shallow and deep copy operations,pprint — Data pretty printer,types — Δημιουργία δυναμικών τύπων και ονόματα για ενσωματωμένους τύπους,Data Types
@anchor{library/copy doc}@anchor{2c07}@anchor{library/copy copy-shallow-and-deep-copy-operations}@anchor{2c08}@anchor{library/copy module-copy}@anchor{29}@anchor{library/copy translation-repo}@anchor{2c09}
@subsection @code{copy} — Shallow and deep copy operations


@geindex module; copy

`Source code:' Lib/copy.py@footnote{https://github.com/python/cpython/tree/main/Lib/copy.py}


__________________________________________________________________


Assignment statements in Python do not copy objects, they create bindings
between a target and an object. For collections that are mutable or contain
mutable items, a copy is sometimes needed so one can change one copy without
changing the other. This module provides generic shallow and deep copy
operations (explained below).

Interface summary:

@geindex copy() (στη μονάδα copy)
@anchor{library/copy copy copy}@anchor{942}
@deffn {Συνάρτηση} copy.copy (obj)

Return a shallow copy of `obj'.
@end deffn

@geindex deepcopy() (στη μονάδα copy)
@anchor{library/copy copy deepcopy}@anchor{f2b}
@deffn {Συνάρτηση} copy.deepcopy (obj[, memo])

Return a deep copy of `obj'.
@end deffn

@geindex replace() (στη μονάδα copy)
@anchor{library/copy copy replace}@anchor{45a}
@deffn {Συνάρτηση} copy.replace (obj, /, **changes)

Creates a new object of the same type as `obj', replacing fields with values
from `changes'.


Added in version 3.13.

@end deffn

@geindex Error
@anchor{library/copy copy Error}@anchor{2c0a}
@deffn {Εξαίρεση} copy.Error

Raised for module specific errors.
@end deffn
@anchor{library/copy shallow-vs-deep-copy}@anchor{21d2}
The difference between shallow and deep copying is only relevant for compound
objects (objects that contain other objects, like lists or class instances):


@itemize *

@item 
A `shallow copy' constructs a new compound object and then (to the extent
possible) inserts `references' into it to the objects found in the original.

@item 
A `deep copy' constructs a new compound object and then, recursively, inserts
`copies' into it of the objects found in the original.
@end itemize

Two problems often exist with deep copy operations that don’t exist with shallow
copy operations:


@itemize *

@item 
Recursive objects (compound objects that, directly or indirectly, contain a
reference to themselves) may cause a recursive loop.

@item 
Because deep copy copies everything it may copy too much, such as data
which is intended to be shared between copies.
@end itemize

The @ref{f2b,,deepcopy()} function avoids these problems by:


@itemize *

@item 
keeping a @code{memo} dictionary of objects already copied during the current
copying pass; and

@item 
letting user-defined classes override the copying operation or the set of
components copied.
@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{ab,,pickle} module.

Shallow copies of dictionaries can be made using @ref{f8e,,dict.copy()}, and
of lists by assigning a slice of the entire list, for example,
@code{copied_list = original_list[:]}.

@geindex module;pickle

Classes can use the same interfaces to control copying that they use to control
pickling.  See the description of module @ref{ab,,pickle} for information on these
methods.  In fact, the @code{copy} module uses the registered
pickle functions from the @ref{2a,,copyreg} module.

@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{1a4c,,__copy__()} and @ref{1909,,__deepcopy__()}.

@anchor{library/copy object __copy__}@anchor{1a4c}
@deffn {Μέθοδος} object.__copy__ (self)

Called to implement the shallow copy operation;
no additional arguments are passed.
@end deffn

@anchor{library/copy object __deepcopy__}@anchor{1909}
@deffn {Μέθοδος} 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{f2b,,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{942,,copy()} and @ref{f2b,,deepcopy()},
and only supports named tuples created by @ref{1cf,,namedtuple()},
@ref{32,,dataclasses}, and other classes which define method @ref{68b,,__replace__()}.

@anchor{library/copy object __replace__}@anchor{68b}
@deffn {Μέθοδος} object.__replace__ (self, /, **changes)

This method should create a new object of the same type,
replacing fields with values from `changes'.


Added in version 3.13.

@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{ab,,pickle}

Discussion of the special methods used to support object state retrieval and
restoration.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node pprint — Data pretty printer,reprlib — Alternate repr implementation,copy — Shallow and deep copy operations,Data Types
@anchor{library/pprint doc}@anchor{2c0b}@anchor{library/pprint module-pprint}@anchor{b3}@anchor{library/pprint pprint-data-pretty-printer}@anchor{2c0c}@anchor{library/pprint translation-repo}@anchor{2c0d}
@subsection @code{pprint} — Data pretty printer


@geindex module; pprint

`Source code:' Lib/pprint.py@footnote{https://github.com/python/cpython/tree/main/Lib/pprint.py}


__________________________________________________________________


The @code{pprint} module provides a capability to «pretty-print» arbitrary
Python data structures in a form which can be used as input to the interpreter.
If the formatted structures include objects which are not fundamental Python
types, the representation may not be loadable.  This may be the case if objects
such as files, sockets or classes are included, as well as many other
objects which are not representable as Python literals.

The formatted representation keeps objects on a single line if it can, and
breaks them onto multiple lines if they don’t fit within the allowed width,
adjustable by the `width' parameter defaulting to 88 characters.


Άλλαξε στην έκδοση 3.9: Added support for pretty-printing @ref{6ea,,types.SimpleNamespace}.



Άλλαξε στην έκδοση 3.10: Added support for pretty-printing @ref{6e6,,dataclasses.dataclass}.


@menu
* Functions: Functions<3>. 
* PrettyPrinter objects:: 
* Example: Example<3>. 

@end menu

@node Functions<3>,PrettyPrinter objects,,pprint — Data pretty printer
@anchor{library/pprint functions}@anchor{2c0e}@anchor{library/pprint pprint-functions}@anchor{2c0f}
@subsubsection Functions


@geindex pp() (στη μονάδα pprint)
@anchor{library/pprint pprint pp}@anchor{de7}
@deffn {Συνάρτηση} pprint.pp (object, stream=None, indent=4, width=88, depth=None, *, compact=False, sort_dicts=False, underscore_numbers=False)

Prints the formatted representation of `object', followed by a newline.
This function may be used in the interactive interpreter
instead of the @ref{131f,,print()} function for inspecting values.
Tip: you can reassign @code{print = pprint.pp} for use within a scope.

@*Παράμετροι: 

@itemize *

@item 
@code{object} – The object to be printed.

@item 
@code{stream} (@ref{19b1,,file-like object} | None) – A file-like object to which the output will be written
by calling its @code{write()} method.
If @code{None} (the default), @ref{e9c,,sys.stdout} is used.

@item 
@code{indent} (@ref{326,,int}) – The amount of indentation added for each nesting level.

@item 
@code{width} (@ref{326,,int}) – The desired maximum number of characters per line in the output.
If a structure cannot be formatted within the width constraint,
a best effort will be made.

@item 
@code{depth} (@ref{326,,int}@code{ | }@code{None}) – The number of nesting levels which may be printed.
If the data structure being printed is too deep,
the next contained level is replaced by @code{...}.
If @code{None} (the default), there is no constraint
on the depth of the objects being formatted.

@item 
@code{compact} (@ref{5ef,,bool}) – Control the way long @ref{8ff,,sequences} are formatted.
If @code{False} (the default),
opening parentheses and brackets will be followed by a newline and the
following content will be indented by one level, similar to
pretty-printed JSON.
If @code{True}, as many items as will fit within the `width'
will be formatted on each output line.

@item 
@code{sort_dicts} (@ref{5ef,,bool}) – If @code{True}, dictionaries will be formatted with
their keys sorted, otherwise
they will be displayed in insertion order (the default).

@item 
@code{underscore_numbers} (@ref{5ef,,bool}) – If @code{True},
integers will be formatted with the @code{_} character for a thousands separator,
otherwise underscores are not displayed (the default).
@end itemize


@example
>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff)
>>> pprint.pp(stuff, width=100)
[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']
@end example


Added in version 3.8.

@end deffn

@geindex pprint() (στη μονάδα pprint)
@anchor{library/pprint pprint pprint}@anchor{c01}
@deffn {Συνάρτηση} pprint.pprint (object, stream=None, indent=4, width=88, depth=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

Alias for @ref{de7,,pp()} with `sort_dicts' set to @code{True} by default,
which would automatically sort the dictionaries” keys,
you might want to use @code{pp()} instead where it is @code{False} by default.
@end deffn

@geindex pformat() (στη μονάδα pprint)
@anchor{library/pprint pprint pformat}@anchor{132a}
@deffn {Συνάρτηση} pprint.pformat (object, indent=4, width=88, depth=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

Return the formatted representation of `object' as a string.  `indent',
`width', `depth', `compact', `sort_dicts' and `underscore_numbers' are
passed to the @ref{1329,,PrettyPrinter} constructor as formatting parameters
and their meanings are as described in the documentation above.
@end deffn

@geindex isreadable() (στη μονάδα pprint)
@anchor{library/pprint pprint isreadable}@anchor{2c10}
@deffn {Συνάρτηση} pprint.isreadable (object)

@geindex built-in function;eval

Determine if the formatted representation of `object' is «readable», or can be
used to reconstruct the value using @ref{184,,eval()}.  This always returns @code{False}
for recursive objects.

@example
>>> pprint.isreadable(stuff)
False
@end example
@end deffn

@geindex isrecursive() (στη μονάδα pprint)
@anchor{library/pprint pprint isrecursive}@anchor{2c11}
@deffn {Συνάρτηση} pprint.isrecursive (object)

Determine if `object' requires a recursive representation.  This function is
subject to the same limitations as noted in @ref{2c12,,saferepr()} below and may raise an
@ref{1121,,RecursionError} if it fails to detect a recursive object.
@end deffn

@geindex saferepr() (στη μονάδα pprint)
@anchor{library/pprint pprint saferepr}@anchor{2c12}
@deffn {Συνάρτηση} pprint.saferepr (object)

Return a string representation of `object', protected against recursion in
some common data structures, namely instances of @ref{188,,dict}, @ref{4d9,,list}
and @ref{1ce,,tuple} or subclasses whose @code{__repr__} has not been overridden.  If the
representation of object exposes a recursive entry, the recursive reference
will be represented as @code{<Recursion on typename with id=number>}.  The
representation is not otherwise formatted.

@example
>>> pprint.saferepr(stuff)
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
@end example
@end deffn

@node PrettyPrinter objects,Example<3>,Functions<3>,pprint — Data pretty printer
@anchor{library/pprint id1}@anchor{2c13}@anchor{library/pprint prettyprinter-objects}@anchor{2c14}
@subsubsection PrettyPrinter objects


@geindex ...;placeholder

@geindex PrettyPrinter (κλάση σε pprint)
@anchor{library/pprint pprint PrettyPrinter}@anchor{1329}
@deffn {Κλάση} pprint.PrettyPrinter (indent=4, width=88, depth=None, stream=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

Construct a @code{PrettyPrinter} instance.

Arguments have the same meaning as for @ref{de7,,pp()}.
Note that they are in a different order, and that `sort_dicts' defaults to @code{True}.

@example
>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff[:])
>>> pp = pprint.PrettyPrinter()
>>> pp.pprint(stuff)
[
    ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
    'spam',
    'eggs',
    'lumberjack',
    'knights',
    'ni',
]
>>> pp = pprint.PrettyPrinter(indent=1, width=41, compact=True)
>>> pp.pprint(stuff)
[['spam', 'eggs', 'lumberjack',
  'knights', 'ni'],
 'spam', 'eggs', 'lumberjack', 'knights',
 'ni']
>>> pp = pprint.PrettyPrinter(width=41, indent=3)
>>> 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


Άλλαξε στην έκδοση 3.4: Added the `compact' parameter.



Άλλαξε στην έκδοση 3.8: Added the `sort_dicts' parameter.



Άλλαξε στην έκδοση 3.10: Added the `underscore_numbers' parameter.



Άλλαξε στην έκδοση 3.11: No longer attempts to write to @code{sys.stdout} if it is @code{None}.



Άλλαξε στην έκδοση 3.15: Changed default `indent' from 1 to 4
and default `width' from 80 to 88.
The default @code{compact=False} layout is now similar to
pretty-printed JSON, with opening parentheses and brackets
followed by a newline and the contents indented by one level.

@end deffn

@ref{1329,,PrettyPrinter} instances have the following methods:

@geindex pformat() (μέθοδος της pprint.PrettyPrinter)
@anchor{library/pprint pprint PrettyPrinter pformat}@anchor{2c15}
@deffn {Μέθοδος} PrettyPrinter.pformat (object)

Return the formatted representation of `object'.  This takes into account the
options passed to the @ref{1329,,PrettyPrinter} constructor.
@end deffn

@geindex pprint() (μέθοδος της pprint.PrettyPrinter)
@anchor{library/pprint pprint PrettyPrinter pprint}@anchor{2c16}
@deffn {Μέθοδος} PrettyPrinter.pprint (object)

Print the formatted representation of `object' on the configured stream,
followed by a newline.
@end deffn

The following methods provide the implementations for the corresponding
functions of the same names.  Using these methods on an instance is slightly
more efficient since new @ref{1329,,PrettyPrinter} objects don’t need to be
created.

@geindex isreadable() (μέθοδος της pprint.PrettyPrinter)
@anchor{library/pprint pprint PrettyPrinter isreadable}@anchor{2c17}
@deffn {Μέθοδος} PrettyPrinter.isreadable (object)

@geindex built-in function;eval

Determine if the formatted representation of the object is «readable,» or can be
used to reconstruct the value using @ref{184,,eval()}.  Note that this returns
@code{False} for recursive objects.  If the `depth' parameter of the
@ref{1329,,PrettyPrinter} is set and the object is deeper than allowed, this
returns @code{False}.
@end deffn

@geindex isrecursive() (μέθοδος της pprint.PrettyPrinter)
@anchor{library/pprint pprint PrettyPrinter isrecursive}@anchor{2c18}
@deffn {Μέθοδος} PrettyPrinter.isrecursive (object)

Determine if the object requires a recursive representation.
@end deffn

This method is provided as a hook to allow subclasses to modify the way objects
are converted to strings.  The default implementation uses the internals of the
@ref{2c12,,saferepr()} implementation.

@geindex format() (μέθοδος της pprint.PrettyPrinter)
@anchor{library/pprint pprint PrettyPrinter format}@anchor{1edc}
@deffn {Μέθοδος} PrettyPrinter.format (object, context, maxlevels, level)

Returns three values: the formatted version of `object' as a string, a flag
indicating whether the result is readable, and a flag indicating whether
recursion was detected.  The first argument is the object to be presented.  The
second is a dictionary which contains the @ref{17c5,,id()} of objects that are part of
the current presentation context (direct and indirect containers for `object'
that are affecting the presentation) as the keys; if an object needs to be
presented which is already represented in `context', the third return value
should be @code{True}.  Recursive calls to the @code{format()} method should add
additional entries for containers to this dictionary.  The third argument,
`maxlevels', gives the requested limit to recursion; this will be @code{0} if there
is no requested limit.  This argument should be passed unmodified to recursive
calls. The fourth argument, `level', gives the current level; recursive calls
should be passed a value less than that of the current call.
@end deffn

@node Example<3>,,PrettyPrinter objects,pprint — Data pretty printer
@anchor{library/pprint example}@anchor{2c19}@anchor{library/pprint pprint-example}@anchor{2c1a}
@subsubsection Example


To demonstrate several uses of the @ref{de7,,pp()} function and its parameters,
let’s fetch information about a project from 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

In its basic form, @ref{de7,,pp()} shows the whole object:

@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

The result can be limited to a certain `depth' (ellipsis is used for deeper
contents):

@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

Additionally, maximum character `width' can be suggested. If a long object
cannot be split, the specified width will be exceeded:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node reprlib — Alternate repr implementation,enum — Support for enumerations,pprint — Data pretty printer,Data Types
@anchor{library/reprlib doc}@anchor{2c1b}@anchor{library/reprlib module-reprlib}@anchor{c3}@anchor{library/reprlib reprlib-alternate-repr-implementation}@anchor{2c1c}@anchor{library/reprlib translation-repo}@anchor{2c1d}
@subsection @code{reprlib} — Alternate @code{repr()} implementation


@geindex module; reprlib

`Source code:' Lib/reprlib.py@footnote{https://github.com/python/cpython/tree/main/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 (κλάση σε reprlib)
@anchor{library/reprlib reprlib Repr}@anchor{2c1e}
@deffn {Κλάση} 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{45b,,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 @code{Repr} instance. Which means that the following
initialization:

@example
aRepr = reprlib.Repr(maxlevel=3)
@end example

Is equivalent to:

@example
aRepr = reprlib.Repr()
aRepr.maxlevel = 3
@end example

See section @ref{2c1f,,Repr Objects} for more information about @code{Repr}
attributes.


Άλλαξε στην έκδοση 3.12: Allow attributes to be set via keyword arguments.

@end deffn

@geindex aRepr (στη μονάδα reprlib)
@anchor{library/reprlib reprlib aRepr}@anchor{2c20}
@deffn {Δεδομένα} reprlib.aRepr

This is an instance of @ref{2c1e,,Repr} which is used to provide the
@ref{2c21,,repr()} function described below.  Changing the attributes of this
object will affect the size limits used by @code{repr()} and the Python
debugger.
@end deffn

@geindex repr() (στη μονάδα reprlib)
@anchor{library/reprlib reprlib repr}@anchor{2c21}
@deffn {Συνάρτηση} reprlib.repr (obj)

This is the @ref{2c22,,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{1bc,,__repr__()} and substituting a
placeholder string instead.

@geindex ...;placeholder

@geindex recursive_repr() (στη μονάδα reprlib)
@anchor{library/reprlib reprlib recursive_repr}@anchor{159c}
@deffn {Συνάρτηση} @@reprlib.recursive_repr (fillvalue='...')

Decorator for @ref{1bc,,__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


Added in 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{2c1f}@anchor{library/reprlib repr-objects}@anchor{2c23}
@subsubsection Repr Objects


@ref{2c1e,,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 (ιδιότητα της reprlib.Repr)
@anchor{library/reprlib reprlib Repr fillvalue}@anchor{2c24}
@deffn {Ιδιότητα} Repr.fillvalue

This string is displayed for recursive references. It defaults to
@code{...}.


Added in version 3.11.

@end deffn

@geindex maxlevel (ιδιότητα της reprlib.Repr)
@anchor{library/reprlib reprlib Repr maxlevel}@anchor{2c25}
@deffn {Ιδιότητα} Repr.maxlevel

Depth limit on the creation of recursive representations.  The default is @code{6}.
@end deffn

@geindex maxdict (ιδιότητα της reprlib.Repr)
@geindex maxlist (ιδιότητα της reprlib.Repr)
@geindex maxtuple (ιδιότητα της reprlib.Repr)
@geindex maxset (ιδιότητα της reprlib.Repr)
@geindex maxfrozenset (ιδιότητα της reprlib.Repr)
@geindex maxdeque (ιδιότητα της reprlib.Repr)
@geindex maxarray (ιδιότητα της reprlib.Repr)
@anchor{library/reprlib reprlib Repr maxdict}@anchor{2c26}
@deffn {Ιδιότητα} Repr.maxdict
@anchor{library/reprlib reprlib Repr maxlist}@anchor{2c27}
@deffnx {Ιδιότητα} Repr.maxlist
@anchor{library/reprlib reprlib Repr maxtuple}@anchor{2c28}
@deffnx {Ιδιότητα} Repr.maxtuple
@anchor{library/reprlib reprlib Repr maxset}@anchor{2c29}
@deffnx {Ιδιότητα} Repr.maxset
@anchor{library/reprlib reprlib Repr maxfrozenset}@anchor{2c2a}
@deffnx {Ιδιότητα} Repr.maxfrozenset
@anchor{library/reprlib reprlib Repr maxdeque}@anchor{2c2b}
@deffnx {Ιδιότητα} Repr.maxdeque
@anchor{library/reprlib reprlib Repr maxarray}@anchor{2c2c}
@deffnx {Ιδιότητα} Repr.maxarray

Limits on the number of entries represented for the named object type.  The
default is @code{4} for @ref{2c26,,maxdict}, @code{5} for @ref{2c2c,,maxarray}, and  @code{6} for
the others.
@end deffn

@geindex maxlong (ιδιότητα της reprlib.Repr)
@anchor{library/reprlib reprlib Repr maxlong}@anchor{2c2d}
@deffn {Ιδιότητα} 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 (ιδιότητα της reprlib.Repr)
@anchor{library/reprlib reprlib Repr maxstring}@anchor{2c2e}
@deffn {Ιδιότητα} 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 (ιδιότητα της reprlib.Repr)
@anchor{library/reprlib reprlib Repr maxother}@anchor{2c2f}
@deffn {Ιδιότητα} Repr.maxother

This limit is used to control the size of object types for which no specific
formatting method is available on the @ref{2c1e,,Repr} object. It is applied in a
similar manner as @ref{2c2e,,maxstring}.  The default is @code{20}.
@end deffn

@geindex indent (ιδιότητα της reprlib.Repr)
@anchor{library/reprlib reprlib Repr indent}@anchor{2c30}
@deffn {Ιδιότητα} 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{45b,,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 @code{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 @code{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


Added in version 3.12.

@end deffn

@geindex repr() (μέθοδος της reprlib.Repr)
@anchor{library/reprlib reprlib Repr repr}@anchor{2c22}
@deffn {Μέθοδος} Repr.repr (obj)

The equivalent to the built-in @ref{45b,,repr()} that uses the formatting imposed by
the instance.
@end deffn

@geindex repr1() (μέθοδος της reprlib.Repr)
@anchor{library/reprlib reprlib Repr repr1}@anchor{2c31}
@deffn {Μέθοδος} Repr.repr1 (obj, level)

Recursive implementation used by @ref{2c22,,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 @code{repr1()} to perform recursive formatting,
with @code{level - 1} for the value of `level' in the recursive  call.
@end deffn


@deffn {Μέθοδος} 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{2c31,,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{2c32}@anchor{library/reprlib subclassing-reprs}@anchor{2c33}
@subsubsection Subclassing Repr Objects


The use of dynamic dispatching by @ref{2c31,,Repr.repr1()} allows subclasses of
@ref{2c1e,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node enum — Support for enumerations,graphlib — Functionality to operate with graph-like structures,reprlib — Alternate repr implementation,Data Types
@anchor{library/enum doc}@anchor{2c34}@anchor{library/enum enum-support-for-enumerations}@anchor{2c35}@anchor{library/enum module-enum}@anchor{59}@anchor{library/enum translation-repo}@anchor{2c36}
@subsection @code{enum} — Support for enumerations


@geindex module; enum


Added in version 3.4.


`Source code:' Lib/enum.py@footnote{https://github.com/python/cpython/tree/main/Lib/enum.py}

@subsubheading Important



This page contains the API reference information. For tutorial
information and discussion of more advanced topics, see


@itemize *

@item 
@ref{2c37,,Basic Tutorial}

@item 
@ref{2c38,,Advanced Tutorial}

@item 
@ref{2c39,,Enum Cookbook}
@end itemize


__________________________________________________________________


An enumeration:


@itemize *

@item 
is a set of symbolic names (members) bound to unique values

@item 
can be iterated over to return its canonical (i.e. non-alias) members in
definition order

@item 
uses `call' syntax to return members by value

@item 
uses `index' syntax to return members by name
@end itemize

Enumerations are created either by using @ref{167c,,class} syntax, or by
using function-call syntax:

@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

Even though we can use @ref{167c,,class} syntax to create Enums, Enums
are not normal Python classes.  See
@ref{2c3a,,How are Enums different?} for more details.

@cartouche
@quotation Σημείωση 
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
* Module contents: Module contents<2>. 
* Data types:: 
* Utilities and decorators:: 
* Notes:: 

@end menu

@node Module contents<2>,Data types,,enum — Support for enumerations
@anchor{library/enum module-contents}@anchor{2c3b}
@subsubsection Module contents


@quotation

@ref{6fc,,EnumType}

@quotation

The @code{type} for Enum and its subclasses.
@end quotation

@ref{a21,,Enum}

@quotation

Base class for creating enumerated constants.
@end quotation

@ref{109d,,IntEnum}

@quotation

Base class for creating enumerated constants that are also
subclasses of @ref{326,,int}. (@ref{2c3c,,Notes})
@end quotation

@ref{a0d,,StrEnum}

@quotation

Base class for creating enumerated constants that are also
subclasses of @ref{1df,,str}. (@ref{2c3c,,Notes})
@end quotation

@ref{a14,,Flag}

@quotation

Base class for creating enumerated constants that can be combined using
the bitwise operations without losing their @ref{a14,,Flag} membership.
@end quotation

@ref{105d,,IntFlag}

@quotation

Base class for creating enumerated constants that can be combined using
the bitwise operators without losing their @ref{105d,,IntFlag} membership.
@code{IntFlag} members are also subclasses of @ref{326,,int}. (@ref{2c3c,,Notes})
@end quotation

@ref{a0e,,ReprEnum}

@quotation

Used by @ref{109d,,IntEnum}, @ref{a0d,,StrEnum}, and @ref{105d,,IntFlag}
to keep the @ref{1df,,str()} of the mixed-in type.
@end quotation

@ref{a17,,EnumCheck}

@quotation

An enumeration with the values @code{CONTINUOUS}, @code{NAMED_FLAGS}, and
@code{UNIQUE}, for use with @ref{a16,,verify()} to ensure various constraints
are met by a given enumeration.
@end quotation

@ref{a15,,FlagBoundary}

@quotation

An enumeration with the values @code{STRICT}, @code{CONFORM}, @code{EJECT}, and
@code{KEEP} which allows for more fine-grained control over how invalid values
are dealt with in an enumeration.
@end quotation

@ref{6fb,,EnumDict}

@quotation

A subclass of @ref{188,,dict} for use when subclassing @ref{6fc,,EnumType}.
@end quotation

@ref{105e,,auto}

@quotation

Instances are replaced with an appropriate value for Enum members.
@ref{a0d,,StrEnum} defaults to the lower-cased version of the member name,
while other Enums default to 1 and increase from there.
@end quotation

@ref{a1a,,property()}

@quotation

Allows @ref{a21,,Enum} members to have attributes without conflicting with
member names.  The @code{value} and @code{name} attributes are implemented this
way.
@end quotation

@ref{2c3d,,unique()}

@quotation

Enum class decorator that ensures only one name is bound to any one value.
@end quotation

@ref{a16,,verify()}

@quotation

Enum class decorator that checks user-selectable constraints on an
enumeration.
@end quotation

@ref{a18,,member()}

@quotation

Make @code{obj} a member.  Can be used as a decorator.
@end quotation

@ref{a19,,nonmember()}

@quotation

Do not make @code{obj} a member.  Can be used as a decorator.
@end quotation

@ref{a1c,,global_enum()}

@quotation

Modify the @ref{1df,,str()} and @ref{45b,,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{19cb,,show_flag_values()}

@quotation

Return a list of all power-of-two integers contained in a flag.
@end quotation

@ref{1987,,enum.bin()}

@quotation

Like built-in @ref{164d,,bin()}, except negative values are represented in
two’s complement, and the leading bit always indicates sign
(@code{0} implies positive, @code{1} implies negative).
@end quotation
@end quotation


Added in version 3.6: @code{Flag}, @code{IntFlag}, @code{auto}



Added in version 3.11: @code{StrEnum}, @code{EnumCheck}, @code{ReprEnum}, @code{FlagBoundary}, @code{property}, @code{member}, @code{nonmember}, @code{global_enum}, @code{show_flag_values}



Added in version 3.13: @code{EnumDict}



__________________________________________________________________


@node Data types,Utilities and decorators,Module contents<2>,enum — Support for enumerations
@anchor{library/enum data-types}@anchor{2c3e}
@subsubsection Data types


@geindex EnumType (κλάση σε enum)
@anchor{library/enum enum EnumType}@anchor{6fc}
@deffn {Κλάση} enum.EnumType

`EnumType' is the @ref{25c5,,metaclass} for `enum' enumerations.  It is possible
to subclass `EnumType' – see @ref{2c3f,,Subclassing EnumType}
for details.

@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.


Added in version 3.11: Before 3.11 @code{EnumType} was called @code{EnumMeta}, which is still available as an alias.


@geindex __call__() (μέθοδος της enum.EnumType)
@anchor{library/enum enum EnumType __call__}@anchor{2c40}
@deffn {Μέθοδος} __call__ (cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

This method is called in two different ways:


@itemize *

@item 
to look up an existing member:

@quotation

@*cls: 
The enum class being called.


@*value: 
The value to lookup.

@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: 
The enum class being called.


@*value: 
The name of the new Enum to create.


@*names: 
The names/values of the members for the new Enum.


@*module: 
The name of the module the new Enum is created in.


@*qualname: 
The actual location in the module where this Enum can be found.


@*type: 
A mix-in type for the new Enum.


@*start: 
The first integer value for the Enum (used by @ref{105e,,auto}).


@*boundary: 
How to handle out-of-range values from bit operations (@ref{a14,,Flag} only).

@end quotation
@end itemize
@end deffn

@geindex __contains__() (μέθοδος της enum.EnumType)
@anchor{library/enum enum EnumType __contains__}@anchor{2c41}
@deffn {Μέθοδος} __contains__ (cls, member)

Returns @code{True} if member belongs to the @code{cls}:

@example
>>> some_var = Color.RED
>>> some_var in Color
True
>>> Color.RED.value in Color
True
@end example


Άλλαξε στην έκδοση 3.12: Before Python 3.12, a @code{TypeError} is raised if a
non-Enum-member is used in a containment check.

@end deffn

@geindex __dir__() (μέθοδος της enum.EnumType)
@anchor{library/enum enum EnumType __dir__}@anchor{2c42}
@deffn {Μέθοδος} __dir__ (cls)

Returns @code{['__class__', '__doc__', '__members__', '__module__']} and the
names of the members in `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__() (μέθοδος της enum.EnumType)
@anchor{library/enum enum EnumType __getitem__}@anchor{2c43}
@deffn {Μέθοδος} __getitem__ (cls, name)

Returns the Enum member in `cls' matching `name', or raises a @ref{7df,,KeyError}:

@example
>>> Color['BLUE']
<Color.BLUE: 3>
@end example
@end deffn

@geindex __iter__() (μέθοδος της enum.EnumType)
@anchor{library/enum enum EnumType __iter__}@anchor{2c44}
@deffn {Μέθοδος} __iter__ (cls)

Returns each member in `cls' in definition order:

@example
>>> list(Color)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]
@end example
@end deffn

@geindex __len__() (μέθοδος της enum.EnumType)
@anchor{library/enum enum EnumType __len__}@anchor{2c45}
@deffn {Μέθοδος} __len__ (cls)

Returns the number of members in `cls':

@example
>>> len(Color)
3
@end example
@end deffn

@geindex __members__ (ιδιότητα της enum.EnumType)
@anchor{library/enum enum EnumType __members__}@anchor{2c46}
@deffn {Ιδιότητα} __members__

Returns a mapping of every enum name to its member, including aliases
@end deffn

@geindex __reversed__() (μέθοδος της enum.EnumType)
@anchor{library/enum enum EnumType __reversed__}@anchor{2c47}
@deffn {Μέθοδος} __reversed__ (cls)

Returns each member in `cls' in reverse definition order:

@example
>>> list(reversed(Color))
[<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]
@end example
@end deffn
@end deffn

@geindex Enum (κλάση σε enum)
@anchor{library/enum enum Enum}@anchor{a21}
@deffn {Κλάση} enum.Enum

`Enum' is the base class for all `enum' enumerations.

@geindex name (ιδιότητα της enum.Enum)
@anchor{library/enum enum Enum name}@anchor{2c48}
@deffn {Ιδιότητα} name

The name used to define the @code{Enum} member:

@example
>>> Color.BLUE.name
'BLUE'
@end example
@end deffn

@geindex value (ιδιότητα της enum.Enum)
@anchor{library/enum enum Enum value}@anchor{2c49}
@deffn {Ιδιότητα} value

The value given to the @code{Enum} member:

@example
>>> Color.RED.value
1
@end example

Value of the member, can be set in @ref{2c4a,,__new__()}.

@cartouche
@quotation Σημείωση 
Enum member values

Member values can be anything: @ref{326,,int}, @ref{1df,,str}, etc.  If
the exact value is unimportant you may use @ref{105e,,auto} instances and an
appropriate value will be chosen for you.  See @code{auto} for the
details.

While mutable/unhashable values, such as @ref{188,,dict}, @ref{4d9,,list} or
a mutable @ref{6e6,,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_ (ιδιότητα της enum.Enum)
@anchor{library/enum enum Enum _name_}@anchor{2c4b}
@deffn {Ιδιότητα} _name_

Name of the member.
@end deffn

@geindex _value_ (ιδιότητα της enum.Enum)
@anchor{library/enum enum Enum _value_}@anchor{2c4c}
@deffn {Ιδιότητα} _value_

Value of the member, can be set in @ref{2c4a,,__new__()}.
@end deffn

@geindex _order_ (ιδιότητα της enum.Enum)
@anchor{library/enum enum Enum _order_}@anchor{2c4d}
@deffn {Ιδιότητα} _order_

No longer used, kept for backward compatibility.
(class attribute, removed during class creation).

The @code{_order_} attribute can be provided to help keep Python 2 / Python 3 code in sync.
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 Σημείωση 
In Python 2 code the @code{_order_} attribute is necessary as definition
order is lost before it can be recorded.
@end quotation
@end cartouche


Added in version 3.6.

@end deffn

@geindex _ignore_ (ιδιότητα της enum.Enum)
@anchor{library/enum enum Enum _ignore_}@anchor{2c4e}
@deffn {Ιδιότητα} _ignore_

@code{_ignore_} is only used during creation and is removed from the
enumeration once creation is complete.

@code{_ignore_} is a list of names that will not become members, and whose
names will also be removed from the completed enumeration.  See
@ref{2c4f,,TimePeriod} for an example.


Added in version 3.7.

@end deffn

@geindex __dir__() (μέθοδος της enum.Enum)
@anchor{library/enum enum Enum __dir__}@anchor{1dfb}
@deffn {Μέθοδος} __dir__ (self)

Returns @code{['__class__', '__doc__', '__module__', 'name', 'value']} and
any public methods defined on `self.__class__':

@example
>>> from enum import Enum
>>> import datetime as dt
>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7
...     @@classmethod
...     def today(cls):
...         print(f'today is @{cls(dt.date.today().isoweekday()).name@}')
...
>>> dir(Weekday.SATURDAY)
['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value']
@end example
@end deffn

@geindex _generate_next_value_() (μέθοδος της enum.Enum)
@anchor{library/enum enum Enum _generate_next_value_}@anchor{2c50}
@deffn {Μέθοδος} _generate_next_value_ (name, start, count, last_values)

@quotation

@*name: 
The name of the member being defined (e.g. “RED”).


@*start: 
The start value for the Enum; the default is 1.


@*count: 
The number of members currently defined, not including this one.


@*last_values: 
A list of the previous values.

@end quotation

A `staticmethod' that is used to determine the next value returned by
@ref{105e,,auto}.

@cartouche
@quotation Σημείωση 
For standard @code{Enum} classes the next value chosen is the highest
value seen incremented by one.

For @ref{a14,,Flag} classes the next value chosen will be the next highest
power-of-two.
@end quotation
@end cartouche

This method may be overridden, e.g.:

@example
>>> from enum import auto, Enum
>>> 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


Added in version 3.6.



Άλλαξε στην έκδοση 3.13: Prior versions would use the last seen value instead of the highest value.

@end deffn

@geindex __init__() (μέθοδος της enum.Enum)
@anchor{library/enum enum Enum __init__}@anchor{2c51}
@deffn {Μέθοδος} __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__() (μέθοδος της enum.Enum)
@anchor{library/enum enum Enum __init_subclass__}@anchor{2c52}
@deffn {Μέθοδος} __init_subclass__ (cls, **kwds)

A `classmethod' that is used to further configure subsequent subclasses.
By default, does nothing.
@end deffn

@geindex _missing_() (μέθοδος της enum.Enum)
@anchor{library/enum enum Enum _missing_}@anchor{2c53}
@deffn {Μέθοδος} _missing_ (cls, value)

A `classmethod' for looking up values not found in `cls'.  By default it
does nothing, but can be overridden to implement custom search behavior:

@example
>>> from enum import auto, 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


Added in version 3.6.

@end deffn

@geindex __new__() (μέθοδος της enum.Enum)
@anchor{library/enum enum Enum __new__}@anchor{2c4a}
@deffn {Μέθοδος} __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 Σημείωση 
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__() (μέθοδος της enum.Enum)
@anchor{library/enum enum Enum __repr__}@anchor{1cf9}
@deffn {Μέθοδος} __repr__ (self)

Returns the string used for `repr()' calls.  By default, returns the
`Enum' name, member name, and value, but can be overridden:

@example
>>> from enum import auto, Enum
>>> 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__() (μέθοδος της enum.Enum)
@anchor{library/enum enum Enum __str__}@anchor{a13}
@deffn {Μέθοδος} __str__ (self)

Returns the string used for `str()' calls.  By default, returns the
`Enum' name and member name, but can be overridden:

@example
>>> from enum import auto, Enum
>>> 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__() (μέθοδος της enum.Enum)
@anchor{library/enum enum Enum __format__}@anchor{a11}
@deffn {Μέθοδος} __format__ (self)

Returns the string used for `format()' and `f-string' calls.  By default,
returns @ref{a13,,__str__()} return value, but can be overridden:

@example
>>> from enum import auto, Enum
>>> 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 Σημείωση 
Using @ref{105e,,auto} with @code{Enum} results in integers of increasing value,
starting with @code{1}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.12: Added @ref{1cf8,,Dataclass support}.


@geindex _add_alias_() (μέθοδος της enum.Enum)
@anchor{library/enum enum Enum _add_alias_}@anchor{2c54}
@deffn {Μέθοδος} _add_alias_ ()

Adds a new name as an alias to an existing member:

@example
>>> Color.RED._add_alias_("ERROR")
>>> Color.ERROR
<Color.RED: 1>
@end example

Raises a @ref{665,,NameError} if the name is already assigned to a different member.


Added in version 3.13.

@end deffn

@geindex _add_value_alias_() (μέθοδος της enum.Enum)
@anchor{library/enum enum Enum _add_value_alias_}@anchor{2c55}
@deffn {Μέθοδος} _add_value_alias_ ()

Adds a new value as an alias to an existing member:

@example
>>> Color.RED._add_value_alias_(42)
>>> Color(42)
<Color.RED: 1>
@end example


@display
Raises a @ref{277,,ValueError} if the value is already linked with a different member.@w{ }
See @ref{2c56,,MultiValueEnum} for an example.@w{ }
@end display




Added in version 3.13.

@end deffn
@end deffn

@geindex IntEnum (κλάση σε enum)
@anchor{library/enum enum IntEnum}@anchor{109d}
@deffn {Κλάση} enum.IntEnum

`IntEnum' is the same as @ref{a21,,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 Σημείωση 
Using @ref{105e,,auto} with @code{IntEnum} results in integers of increasing
value, starting with @code{1}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.11: @ref{a0f,,__str__()} is now @code{int.__str__()} to
better support the `replacement of existing constants' use-case.
@ref{a10,,__format__()} was already @code{int.__format__()} for that same reason.

@end deffn

@geindex StrEnum (κλάση σε enum)
@anchor{library/enum enum StrEnum}@anchor{a0d}
@deffn {Κλάση} enum.StrEnum

`StrEnum' is the same as @ref{a21,,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.

@example
>>> from enum import StrEnum, auto
>>> class Color(StrEnum):
...     RED = 'r'
...     GREEN = 'g'
...     BLUE = 'b'
...     UNKNOWN = auto()
...
>>> Color.RED
<Color.RED: 'r'>
>>> Color.UNKNOWN
<Color.UNKNOWN: 'unknown'>
>>> str(Color.UNKNOWN)
'unknown'
@end example

@cartouche
@quotation Σημείωση 
There are places in the stdlib that check for an exact @ref{1df,,str}
instead of a @code{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(MyStrEnum.MY_MEMBER)}.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Using @ref{105e,,auto} with @code{StrEnum} results in the lower-cased member
name as the value.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
@ref{a0f,,__str__()} is @code{str.__str__()} to better support the
`replacement of existing constants' use-case.  @ref{a10,,__format__()} is likewise
@code{str.__format__()} for that same reason.
@end quotation
@end cartouche


Added in version 3.11.

@end deffn

@geindex Flag (κλάση σε enum)
@anchor{library/enum enum Flag}@anchor{a14}
@deffn {Κλάση} enum.Flag

@code{Flag} is the same as @ref{a21,,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__() (μέθοδος της enum.Flag)
@anchor{library/enum enum Flag __contains__}@anchor{2c57}
@deffn {Μέθοδος} __contains__ (self, value)

Returns `True' if value is in 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 {Μέθοδος} __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


Added in version 3.11.

@end deffn


@deffn {Μέθοδος} __len__(self):

Returns number of members in flag:

@example
>>> len(Color.GREEN)
1
>>> len(white)
3
@end example


Added in version 3.11.

@end deffn


@deffn {Μέθοδος} __bool__(self):

Returns `True' if any members in flag, `False' otherwise:

@example
>>> bool(Color.GREEN)
True
>>> bool(white)
True
>>> black = Color(0)
>>> bool(black)
False
@end example
@end deffn

@geindex __or__() (μέθοδος της enum.Flag)
@anchor{library/enum enum Flag __or__}@anchor{2c58}
@deffn {Μέθοδος} __or__ (self, other)

Returns current flag binary or’ed with other:

@example
>>> Color.RED | Color.GREEN
<Color.RED|GREEN: 3>
@end example
@end deffn

@geindex __and__() (μέθοδος της enum.Flag)
@anchor{library/enum enum Flag __and__}@anchor{2c59}
@deffn {Μέθοδος} __and__ (self, other)

Returns current flag binary and’ed with other:

@example
>>> purple & white
<Color.RED|BLUE: 5>
>>> purple & Color.GREEN
<Color: 0>
@end example
@end deffn

@geindex __xor__() (μέθοδος της enum.Flag)
@anchor{library/enum enum Flag __xor__}@anchor{2c5a}
@deffn {Μέθοδος} __xor__ (self, other)

Returns current flag binary xor’ed with other:

@example
>>> purple ^ white
<Color.GREEN: 2>
>>> purple ^ Color.GREEN
<Color.RED|GREEN|BLUE: 7>
@end example
@end deffn


@deffn {Μέθοδος} __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_() (μέθοδος της enum.Flag)
@anchor{library/enum enum Flag _numeric_repr_}@anchor{2c5b}
@deffn {Μέθοδος} _numeric_repr_ ()

Function used to format any remaining unnamed numeric values.  Default is
the value’s repr; common choices are @ref{1674,,hex()} and @ref{1673,,oct()}.
@end deffn

@cartouche
@quotation Σημείωση 
Using @ref{105e,,auto} with @code{Flag} results in integers that are powers
of two, starting with @code{1}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.11: The `repr()' of zero-valued flags has changed.  It
is now:

@example
>>> Color(0)
<Color: 0>
@end example

@end deffn

@geindex IntFlag (κλάση σε enum)
@anchor{library/enum enum IntFlag}@anchor{105d}
@deffn {Κλάση} enum.IntFlag

@code{IntFlag} is the same as @ref{a14,,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

If any integer operation is performed with an `IntFlag' member, the result is
not an `IntFlag':

@example
>>> Color.RED + 2
3
@end example

If a @ref{a14,,Flag} operation is performed with an `IntFlag' member and:


@itemize *

@item 
the result is a valid `IntFlag': an `IntFlag' is returned

@item 
the result is not a valid `IntFlag': the result depends on the @ref{a15,,FlagBoundary} setting
@end itemize

The @ref{45b,,repr()} of unnamed zero-valued flags has changed.  It is now:

@example
>>> Color(0)
<Color: 0>
@end example

@cartouche
@quotation Σημείωση 
Using @ref{105e,,auto} with @code{IntFlag} results in integers that are powers
of two, starting with @code{1}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.11: @ref{a0f,,__str__()} is now @code{int.__str__()} to better support the
`replacement of existing constants' use-case.  @ref{a10,,__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{a14,,Flag} behavior.

@end deffn

@geindex ReprEnum (κλάση σε enum)
@anchor{library/enum enum ReprEnum}@anchor{a0e}
@deffn {Κλάση} enum.ReprEnum

@code{ReprEnum} uses the @ref{1cf9,,repr()} of @ref{a21,,Enum},
but the @ref{1df,,str()} of the mixed-in data type:


@itemize *

@item 
@code{int.__str__()} for @ref{109d,,IntEnum} and @ref{105d,,IntFlag}

@item 
@code{str.__str__()} for @ref{a0d,,StrEnum}
@end itemize

Inherit from @code{ReprEnum} to keep the @ref{1df,,str()} / @ref{439,,format()}
of the mixed-in data type instead of using the
@ref{a21,,Enum}-default @ref{a13,,str()}.


Added in version 3.11.

@end deffn

@geindex EnumCheck (κλάση σε enum)
@anchor{library/enum enum EnumCheck}@anchor{a17}
@deffn {Κλάση} enum.EnumCheck

`EnumCheck' contains the options used by the @ref{a16,,verify()} decorator to ensure
various constraints; failed constraints result in a @ref{277,,ValueError}.

@geindex UNIQUE (ιδιότητα της enum.EnumCheck)
@anchor{library/enum enum EnumCheck UNIQUE}@anchor{2c5c}
@deffn {Ιδιότητα} UNIQUE

Ensure that each value has only one name:

@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 (ιδιότητα της enum.EnumCheck)
@anchor{library/enum enum EnumCheck CONTINUOUS}@anchor{2c5d}
@deffn {Ιδιότητα} CONTINUOUS

Ensure that there are no missing values between the lowest-valued member
and the highest-valued member:

@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 (ιδιότητα της enum.EnumCheck)
@anchor{library/enum enum EnumCheck NAMED_FLAGS}@anchor{2c5e}
@deffn {Ιδιότητα} NAMED_FLAGS

Ensure that any flag groups/masks contain only named flags – useful when
values are specified instead of being generated by @ref{105e,,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 Σημείωση 
CONTINUOUS and NAMED_FLAGS are designed to work with integer-valued members.
@end quotation
@end cartouche


Added in version 3.11.

@end deffn

@geindex FlagBoundary (κλάση σε enum)
@anchor{library/enum enum FlagBoundary}@anchor{a15}
@deffn {Κλάση} enum.FlagBoundary

@code{FlagBoundary} controls how out-of-range values are handled in @ref{a14,,Flag} and its
subclasses.

@geindex STRICT (ιδιότητα της enum.FlagBoundary)
@anchor{library/enum enum FlagBoundary STRICT}@anchor{2c5f}
@deffn {Ιδιότητα} STRICT

Out-of-range values cause a @ref{277,,ValueError} to be raised. This is the
default for @ref{a14,,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 (ιδιότητα της enum.FlagBoundary)
@anchor{library/enum enum FlagBoundary CONFORM}@anchor{2c60}
@deffn {Ιδιότητα} CONFORM

Out-of-range values have invalid values removed, leaving a valid @ref{a14,,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 (ιδιότητα της enum.FlagBoundary)
@anchor{library/enum enum FlagBoundary EJECT}@anchor{2c61}
@deffn {Ιδιότητα} EJECT

Out-of-range values lose their @ref{a14,,Flag} membership and revert to @ref{326,,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 (ιδιότητα της enum.FlagBoundary)
@anchor{library/enum enum FlagBoundary KEEP}@anchor{2c62}
@deffn {Ιδιότητα} KEEP

Out-of-range values are kept, and the @ref{a14,,Flag} membership is kept.
This is the default for @ref{105d,,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


Added in version 3.11.

@end deffn

@geindex EnumDict (κλάση σε enum)
@anchor{library/enum enum EnumDict}@anchor{6fb}
@deffn {Κλάση} enum.EnumDict

`EnumDict' is a subclass of @ref{188,,dict} that is used as the namespace
for defining enum classes (see @ref{101c,,Προετοιμασία του χώρου ονομάτων της κλάσης}).
It is exposed to allow subclasses of @ref{6fc,,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{1459,,MutableMapping} interface
(@ref{1670,,__setitem__()} and @ref{1807,,update()}) is overridden.
It may be possible to bypass the checks using other @code{dict}
operations like @ref{25f6,,|=}.

@geindex member_names (ιδιότητα της enum.EnumDict)
@anchor{library/enum enum EnumDict member_names}@anchor{2c63}
@deffn {Ιδιότητα} member_names

A list of member names.
@end deffn


Added in version 3.13.

@end deffn


__________________________________________________________________


@menu
* Supported __dunder__ names:: 
* Supported _sunder_ names:: 

@end menu

@node Supported __dunder__ names,Supported _sunder_ names,,Data types
@anchor{library/enum enum-dunder-sunder}@anchor{2c64}@anchor{library/enum supported-dunder-names}@anchor{2c65}
@subsubsection Supported @code{__dunder__} names


@ref{2c46,,__members__} is a read-only ordered mapping of @code{member_name}:@code{member}
items.  It is only available on the class.

@ref{2c4a,,__new__()}, if specified, must create and return the enum members;
it is also a very good idea to set the member’s @ref{2c4c,,_value_} appropriately.
Once all the members are created it is no longer used.

@node Supported _sunder_ names,,Supported __dunder__ names,Data types
@anchor{library/enum supported-sunder-names}@anchor{2c66}
@subsubsection Supported @code{_sunder_} names



@itemize -

@item 
@ref{2c4b,,_name_} – name of the member

@item 
@ref{2c4c,,_value_} – value of the member; can be set in @code{__new__}

@item 
@ref{2c53,,_missing_()} – a lookup function used when a value is not found;
may be overridden

@item 
@ref{2c4e,,_ignore_} – a list of names, either as a @ref{4d9,,list} or a
@ref{1df,,str}, that will not be transformed into members, and will be removed
from the final class

@item 
@ref{2c4d,,_order_} – no longer used, kept for backward
compatibility (class attribute, removed during class creation)

@item 
@ref{2c50,,_generate_next_value_()} – used to get an appropriate value for
an enum member; may be overridden

@item 
@ref{2c54,,_add_alias_()} – adds a new name as an alias to an existing
member.

@item 
@ref{2c55,,_add_value_alias_()} – adds a new value as an alias to an
existing member.

@item 
While @code{_sunder_} names are generally reserved for the further development
of the @ref{a21,,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


Added in version 3.6: @code{_missing_}, @code{_order_}, @code{_generate_next_value_}



Added in version 3.7: @code{_ignore_}



Added in version 3.13: @code{_add_alias_}, @code{_add_value_alias_}, @code{_repr_*}



__________________________________________________________________


@node Utilities and decorators,Notes,Data types,enum — Support for enumerations
@anchor{library/enum ipython-s-rich-display}@anchor{2c67}@anchor{library/enum utilities-and-decorators}@anchor{2c68}
@subsubsection Utilities and decorators


@geindex auto (κλάση σε enum)
@anchor{library/enum enum auto}@anchor{105e}
@deffn {Κλάση} enum.auto

`auto' can be used in place of a value.  If used, the `Enum' machinery will
call an @ref{a21,,Enum}’s @ref{2c50,,_generate_next_value_()} to get an appropriate value.
For @code{Enum} and @ref{109d,,IntEnum} that appropriate value will be the highest value seen
plus one; for @ref{a14,,Flag} and @ref{105d,,IntFlag} it will be the first power-of-two greater
than the highest value seen; for @ref{a0d,,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, either by
itself or as part of a tuple:


@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{THIRD = [auto(), -3]} will `not' work (@code{[<auto instance>, -3]} is used to
create the @code{THIRD} enum member)
@end itemize


Άλλαξε στην έκδοση 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_} can be overridden to customize the values used by
`auto'.

@cartouche
@quotation Σημείωση 
In version 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() (στη μονάδα enum)
@anchor{library/enum enum property}@anchor{a1a}
@deffn {Συνάρτηση} @@enum.property

A decorator similar to the built-in `property', but specifically for
enumerations.  It allows member attributes to have the same names as members
themselves.

@cartouche
@quotation Σημείωση 
The `property' and the member must be defined in separate classes;
for example, the `value' and `name' attributes are defined in the
`Enum' class, and `Enum' subclasses can define members with the
names @code{value} and @code{name}.
@end quotation
@end cartouche


Added in version 3.11.

@end deffn

@geindex unique() (στη μονάδα enum)
@anchor{library/enum enum unique}@anchor{2c3d}
@deffn {Συνάρτηση} @@enum.unique

A @ref{167c,,class} decorator specifically for enumerations.  It searches an
enumeration’s @ref{2c46,,__members__}, gathering any aliases it finds; if any are
found @ref{277,,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() (στη μονάδα enum)
@anchor{library/enum enum verify}@anchor{a16}
@deffn {Συνάρτηση} @@enum.verify

A @ref{167c,,class} decorator specifically for enumerations.  Members from
@ref{a17,,EnumCheck} are used to specify which constraints should be checked
on the decorated enumeration.


Added in version 3.11.

@end deffn

@geindex member() (στη μονάδα enum)
@anchor{library/enum enum member}@anchor{a18}
@deffn {Συνάρτηση} @@enum.member

A decorator for use in enums: its target will become a member.


Added in version 3.11.

@end deffn

@geindex nonmember() (στη μονάδα enum)
@anchor{library/enum enum nonmember}@anchor{a19}
@deffn {Συνάρτηση} @@enum.nonmember

A decorator for use in enums: its target will not become a member.


Added in version 3.11.

@end deffn

@geindex global_enum() (στη μονάδα enum)
@anchor{library/enum enum global_enum}@anchor{a1c}
@deffn {Συνάρτηση} @@enum.global_enum

A decorator to change the @ref{1df,,str()} and @ref{45b,,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{a1e,,re.RegexFlag} for an example).


Added in version 3.11.

@end deffn

@geindex show_flag_values() (στη μονάδα enum)
@anchor{library/enum enum show_flag_values}@anchor{19cb}
@deffn {Συνάρτηση} enum.show_flag_values (value)

Return a list of all power-of-two integers contained in a flag `value'.


Added in version 3.11.

@end deffn

@geindex bin() (στη μονάδα enum)
@anchor{library/enum enum bin}@anchor{1987}
@deffn {Συνάρτηση} enum.bin (num, max_bits=None)

Like built-in @code{bin()}, except negative values are represented in
two’s complement, and the leading bit always indicates sign
(@code{0} implies positive, @code{1} implies negative).

@example
>>> import enum
>>> enum.bin(10)
'0b0 1010'
>>> enum.bin(~10)   # ~10 is -11
'0b1 0101'
@end example


Added in version 3.11.

@end deffn


__________________________________________________________________


@node Notes,,Utilities and decorators,enum — Support for enumerations
@anchor{library/enum notes}@anchor{2c3c}
@subsubsection Notes


@ref{109d,,IntEnum}, @ref{a0d,,StrEnum}, and @ref{105d,,IntFlag}

@quotation

These three enum types are designed to be drop-in replacements for existing
integer- and string-based values; as such, they have extra limitations:


@itemize -

@item 
@code{__str__} uses the value and not the name of the enum member

@item 
@code{__format__}, because it uses @code{__str__}, will also use the value of
the enum member instead of its name
@end itemize

If you do not need/want those limitations, you can either create your own
base class by mixing in the @code{int} or @code{str} type yourself:

@example
>>> from enum import Enum
>>> class MyIntEnum(int, Enum):
...     pass
@end example

or you can reassign the appropriate @ref{1df,,str()}, etc., in your enum:

@example
>>> from enum import Enum, IntEnum
>>> class MyIntEnum(IntEnum):
...     __str__ = Enum.__str__
@end example
@end quotation

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node graphlib — Functionality to operate with graph-like structures,,enum — Support for enumerations,Data Types
@anchor{library/graphlib doc}@anchor{2c69}@anchor{library/graphlib graphlib-functionality-to-operate-with-graph-like-structures}@anchor{2c6a}@anchor{library/graphlib module-graphlib}@anchor{68}@anchor{library/graphlib translation-repo}@anchor{2c6b}
@subsection @code{graphlib} — Functionality to operate with graph-like structures


@geindex module; graphlib

`Source code:' Lib/graphlib.py@footnote{https://github.com/python/cpython/tree/main/Lib/graphlib.py}

@c import graphlib
@c from graphlib import *


__________________________________________________________________


@geindex TopologicalSorter (κλάση σε graphlib)
@anchor{library/graphlib graphlib TopologicalSorter}@anchor{cb3}
@deffn {Κλάση} graphlib.TopologicalSorter (graph=None)

Provides functionality to topologically sort a graph of @ref{183,,hashable} nodes.

A topological order is a linear ordering of the vertices in a graph such that
for every directed edge u -> v from vertex u to vertex v, vertex u comes
before vertex v in the ordering. For instance, the vertices of the graph may
represent tasks to be performed, and the edges may represent constraints that
one task must be performed before another; in this example, a topological
ordering is just a valid sequence for the tasks. A complete topological
ordering is possible if and only if the graph has no directed cycles, that
is, if it is a directed acyclic graph.

If the optional `graph' argument is provided it must be a dictionary
representing a directed acyclic graph where the keys are nodes and the values
are iterables of all predecessors of that node in the graph (the nodes that
have edges that point to the value in the key). Additional nodes can be added
to the graph using the @ref{2c6c,,add()} method.

In the general case, the steps required to perform the sorting of a given
graph are as follows:


@itemize *

@item 
Create an instance of the @code{TopologicalSorter} with an optional
initial graph.

@item 
Add additional nodes to the graph.

@item 
Call @ref{4ad,,prepare()} on the graph.

@item 
While @ref{2c6d,,is_active()} is @code{True}, iterate over
the nodes returned by @ref{2c6e,,get_ready()} and
process them. Call @ref{2c6f,,done()} on each node as it
finishes processing.
@end itemize

In case just an immediate sorting of the nodes in the graph is required and
no parallelism is involved, the convenience method
@ref{2c70,,TopologicalSorter.static_order()} can be used directly:

@example
>>> graph = @{"D": @{"B", "C"@}, "C": @{"A"@}, "B": @{"A"@}@}
>>> ts = TopologicalSorter(graph)
>>> tuple(ts.static_order())
('A', 'C', 'B', 'D')
@end example

The class is designed to easily support parallel processing of the nodes as
they become ready. For instance:

@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() (μέθοδος της graphlib.TopologicalSorter)
@anchor{library/graphlib graphlib TopologicalSorter add}@anchor{2c6c}
@deffn {Μέθοδος} add (node, *predecessors)

Add a new node and its predecessors to the graph. Both the `node' and all
elements in `predecessors' must be @ref{183,,hashable}.

If called multiple times with the same node argument, the set of
dependencies will be the union of all dependencies passed in.

It is possible to add a node with no dependencies (`predecessors' is not
provided) or to provide a dependency twice. If a node that has not been
provided before is included among `predecessors' it will be automatically
added to the graph with no predecessors of its own.

Raises @ref{277,,ValueError} if called after @ref{4ad,,prepare()}.
@end deffn

@geindex prepare() (μέθοδος της graphlib.TopologicalSorter)
@anchor{library/graphlib graphlib TopologicalSorter prepare}@anchor{4ad}
@deffn {Μέθοδος} prepare ()

Mark the graph as finished and check for cycles in the graph. If any cycle
is detected, @ref{2c71,,CycleError} will be raised, but
@ref{2c6e,,get_ready()} can still be used to obtain as many
nodes as possible until cycles block more progress. After a call to this
function, the graph cannot be modified, and therefore no more nodes can be
added using @ref{2c6c,,add()}.

A @ref{277,,ValueError} will be raised if the sort has been started by
@ref{2c70,,static_order()} or @ref{2c6e,,get_ready()}.


Άλλαξε στην έκδοση 3.14: @code{prepare()} can now be called more than once as long as the sort has
not started. Previously this raised @ref{277,,ValueError}.

@end deffn

@geindex is_active() (μέθοδος της graphlib.TopologicalSorter)
@anchor{library/graphlib graphlib TopologicalSorter is_active}@anchor{2c6d}
@deffn {Μέθοδος} is_active ()

Returns @code{True} if more progress can be made and @code{False} otherwise.
Progress can be made if cycles do not block the resolution and either
there are still nodes ready that haven’t yet been returned by
@ref{2c6e,,TopologicalSorter.get_ready()} or the number of nodes marked
@ref{2c6f,,TopologicalSorter.done()} is less than the number that have been
returned by @code{TopologicalSorter.get_ready()}.

The @ref{167a,,__bool__()} method of this class defers to
this function, so instead of:

@example
if ts.is_active():
    ...
@end example

it is possible to simply do:

@example
if ts:
    ...
@end example

Raises @ref{277,,ValueError} if called without calling
@ref{4ad,,prepare()} previously.
@end deffn

@geindex done() (μέθοδος της graphlib.TopologicalSorter)
@anchor{library/graphlib graphlib TopologicalSorter done}@anchor{2c6f}
@deffn {Μέθοδος} done (*nodes)

Marks a set of nodes returned by @ref{2c6e,,TopologicalSorter.get_ready()} as
processed, unblocking any successor of each node in `nodes' for being
returned in the future by a call to @code{TopologicalSorter.get_ready()}.

Raises @ref{277,,ValueError} if any node in `nodes' has already been marked as
processed by a previous call to this method or if a node was not added to
the graph by using @ref{2c6c,,TopologicalSorter.add()}, if called without
calling @ref{4ad,,prepare()} or if node has not yet been
returned by @ref{2c6e,,get_ready()}.
@end deffn

@geindex get_ready() (μέθοδος της graphlib.TopologicalSorter)
@anchor{library/graphlib graphlib TopologicalSorter get_ready}@anchor{2c6e}
@deffn {Μέθοδος} get_ready ()

Returns a @code{tuple} with all the nodes that are ready. Initially it
returns all nodes with no predecessors, and once those are marked as
processed by calling @ref{2c6f,,TopologicalSorter.done()}, further calls will
return all new nodes that have all their predecessors already processed.
Once no more progress can be made, empty tuples are returned.

Raises @ref{277,,ValueError} if called without calling
@ref{4ad,,prepare()} previously.
@end deffn

@geindex static_order() (μέθοδος της graphlib.TopologicalSorter)
@anchor{library/graphlib graphlib TopologicalSorter static_order}@anchor{2c70}
@deffn {Μέθοδος} static_order ()

Returns an iterator object which will iterate over nodes in a topological
order. When using this method, @ref{4ad,,prepare()} and
@ref{2c6f,,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

The particular order that is returned may depend on the specific order in
which the items were inserted in the graph. For example:

@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

This is due to the fact that «0» and «2» are in the same level in the
graph (they would have been returned in the same call to
@ref{2c6e,,get_ready()}) and the order between them is
determined by the order of insertion.

If any cycle is detected, @ref{2c71,,CycleError} will be raised.
@end deffn


Added in version 3.9.

@end deffn

@menu
* Exceptions: Exceptions<2>. 

@end menu

@node Exceptions<2>,,,graphlib — Functionality to operate with graph-like structures
@anchor{library/graphlib exceptions}@anchor{2c72}
@subsubsection Exceptions


The @code{graphlib} module defines the following exception classes:

@geindex CycleError
@anchor{library/graphlib graphlib CycleError}@anchor{2c71}
@deffn {Εξαίρεση} graphlib.CycleError

Subclass of @ref{277,,ValueError} raised by @ref{4ad,,TopologicalSorter.prepare()} if cycles exist
in the working graph. If multiple cycles exist, only one undefined choice among them will
be reported and included in the exception.

The detected cycle can be accessed via the second element in the @ref{972,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Αριθμητικά και Μαθηματικά Modules,Functional Programming Modules,Data Types,The Python Standard Library
@anchor{library/numeric doc}@anchor{2c73}@anchor{library/numeric numeric}@anchor{2c74}@anchor{library/numeric numeric-and-mathematical-modules}@anchor{2c75}@anchor{library/numeric translation-repo}@anchor{2c76}
@section Αριθμητικά και Μαθηματικά Modules


Τα modules που περιγράφονται σε αυτό το κεφάλαιο παρέχουν αριθμητικές και μαθηματικές συναρτήσεις και τύπους δεδομένων. Το πακέτο @ref{a2,,numbers} ορίζει μια αφηρημένη ιεραρχία τύπων δεδομένων. Τα modules @ref{91,,math} και @ref{19,,cmath} περιέχουν διάφορες μαθηματικές συναρτήσεις για αριθμούς κινητής υποδιαστολής και μιγαδικούς αριθμούς. Το module @ref{39,,decimal} υποστηρίζει ακριβείς αναπαραστάσεις δεκαδικών αριθμών χρησιμοποιώντας αριθμητική αυθαίρετης ακρίβειας.

Τα ακόλουθα modules αναλύονται σε αυτό το κεφάλαιο

@menu
* numbers — Numeric abstract base classes:: 
* math — Mathematical functions:: 
* math.integer — integer-specific mathematics functions: math integer — integer-specific mathematics functions. 
* cmath — Mathematical functions for complex numbers:: 
* decimal — Decimal fixed-point and floating-point arithmetic:: 
* fractions — Rational numbers:: 
* random — Δημιουργία ψευδοτυχαίων αριθμών:: 
* statistics — Mathematical statistics functions:: 

@end menu

@node numbers — Numeric abstract base classes,math — Mathematical functions,,Αριθμητικά και Μαθηματικά Modules
@anchor{library/numbers doc}@anchor{2c77}@anchor{library/numbers module-numbers}@anchor{a2}@anchor{library/numbers numbers-numeric-abstract-base-classes}@anchor{2c78}
@subsection @code{numbers} — Numeric abstract base classes


@geindex module; numbers

`Source code:' Lib/numbers.py@footnote{https://github.com/python/cpython/tree/main/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{155f,,abstract base classes} which progressively define
more operations.  None of the types defined in this module are intended to be instantiated.

@geindex Number (κλάση σε numbers)
@anchor{library/numbers numbers Number}@anchor{2c79}
@deffn {Κλάση} numbers.Number

The root of the numeric hierarchy. If you just want to check if an argument
`x' is a number, without caring what kind, use @code{isinstance(x, Number)}.
@end deffn

@menu
* The numeric tower:: 
* Notes for type implementers:: 

@end menu

@node The numeric tower,Notes for type implementers,,numbers — Numeric abstract base classes
@anchor{library/numbers the-numeric-tower}@anchor{2c7a}
@subsubsection The numeric tower


@geindex Complex (κλάση σε numbers)
@anchor{library/numbers numbers Complex}@anchor{27f6}
@deffn {Κλάση} numbers.Complex

Subclasses of this type describe complex numbers and include the operations
that work on the built-in @ref{328,,complex} type. These are: conversions to
@code{complex} and @ref{5ef,,bool}, @ref{2c7b,,real}, @ref{2c7c,,imag}, @code{+},
@code{-}, @code{*}, @code{/}, @code{**}, @ref{227c,,abs()}, @ref{2c7d,,conjugate()}, @code{==}, and
@code{!=}. All except @code{-} and @code{!=} are abstract.

@geindex real (ιδιότητα της numbers.Complex)
@anchor{library/numbers numbers Complex real}@anchor{2c7b}
@deffn {Ιδιότητα} real

Abstract. Retrieves the real component of this number.
@end deffn

@geindex imag (ιδιότητα της numbers.Complex)
@anchor{library/numbers numbers Complex imag}@anchor{2c7c}
@deffn {Ιδιότητα} imag

Abstract. Retrieves the imaginary component of this number.
@end deffn

@geindex conjugate() (μέθοδος της numbers.Complex)
@anchor{library/numbers numbers Complex conjugate}@anchor{2c7d}
@deffn {Μέθοδος} abstractmethod conjugate ()

Abstract. Returns the complex conjugate. For example, @code{(1+3j).conjugate()
== (1-3j)}.
@end deffn
@end deffn

@geindex Real (κλάση σε numbers)
@anchor{library/numbers numbers Real}@anchor{27ec}
@deffn {Κλάση} numbers.Real

To @ref{27f6,,Complex}, @code{Real} adds the operations that work on real
numbers.

In short, those are: a conversion to @ref{327,,float}, @ref{1762,,math.trunc()},
@ref{167f,,round()}, @ref{1760,,math.floor()}, @ref{1761,,math.ceil()}, @ref{d6a,,divmod()}, @code{//},
@code{%}, @code{<}, @code{<=}, @code{>}, and @code{>=}.

Real also provides defaults for @ref{328,,complex()}, @ref{2c7b,,real},
@ref{2c7c,,imag}, and @ref{2c7d,,conjugate()}.
@end deffn

@geindex Rational (κλάση σε numbers)
@anchor{library/numbers numbers Rational}@anchor{1663}
@deffn {Κλάση} numbers.Rational

Subtypes @ref{27ec,,Real} and adds @ref{2c7e,,numerator} and
@ref{2c7f,,denominator} properties. It also provides a default for
@ref{327,,float()}.

The @ref{2c7e,,numerator} and @ref{2c7f,,denominator} values
should be instances of @ref{25ff,,Integral} and should be in lowest terms with
@code{denominator} positive.

@geindex numerator (ιδιότητα της numbers.Rational)
@anchor{library/numbers numbers Rational numerator}@anchor{2c7e}
@deffn {Ιδιότητα} numerator

Abstract.  The numerator of this rational number.
@end deffn

@geindex denominator (ιδιότητα της numbers.Rational)
@anchor{library/numbers numbers Rational denominator}@anchor{2c7f}
@deffn {Ιδιότητα} denominator

Abstract.  The denominator of this rational number.
@end deffn
@end deffn

@geindex Integral (κλάση σε numbers)
@anchor{library/numbers numbers Integral}@anchor{25ff}
@deffn {Κλάση} numbers.Integral

Subtypes @ref{1663,,Rational} and adds a conversion to @ref{326,,int}.  Provides
defaults for @ref{327,,float()}, @ref{2c7e,,numerator}, and
@ref{2c7f,,denominator}.  Adds abstract methods for @ref{441,,pow()} with
modulus and bit-string operations: @code{<<}, @code{>>}, @code{&}, @code{^}, @code{|},
@code{~}.
@end deffn

@node Notes for type implementers,,The numeric tower,numbers — Numeric abstract base classes
@anchor{library/numbers notes-for-type-implementers}@anchor{2c80}
@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{1c3,,fractions.Fraction}
implements @ref{9e2,,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
* Adding More Numeric ABCs:: 
* Implementing the arithmetic operations:: 

@end menu

@node Adding More Numeric ABCs,Implementing the arithmetic operations,,Notes for type implementers
@anchor{library/numbers adding-more-numeric-abcs}@anchor{2c81}
@subsubsection Adding More Numeric ABCs


There are, of course, more possible ABCs for numbers, and this would
be a poor hierarchy if it precluded the possibility of adding
those. You can add @code{MyFoo} between @ref{27f6,,Complex} and
@ref{27ec,,Real} with:

@example
class MyFoo(Complex): ...
MyFoo.register(Real)
@end example

@node Implementing the arithmetic operations,,Adding More Numeric ABCs,Notes for type implementers
@anchor{library/numbers id1}@anchor{2c82}@anchor{library/numbers implementing-the-arithmetic-operations}@anchor{2523}
@subsubsection Implementing the arithmetic operations


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{25ff,,Integral}, this
means that @ref{25d2,,__add__()} and @ref{25d3,,__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

There are 5 different cases for a mixed-type operation on subclasses
of @ref{27f6,,Complex}. I’ll refer to all of the above code that doesn’t
refer to @code{MyIntegral} and @code{OtherTypeIKnowAbout} as
«boilerplate». @code{a} will be an instance of @code{A}, which is a subtype
of @code{Complex} (@code{a : A <: Complex}), and @code{b : B <:
Complex}. I’ll consider @code{a + b}:


@enumerate 

@item 
If @code{A} defines an @ref{25d2,,__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{25d2,,__add__()}, we’d miss the possibility
that @code{B} defines a more intelligent @ref{25d3,,__radd__()}, so the
boilerplate should return @ref{440,,NotImplemented} from
@code{__add__()}. (Or @code{A} may not implement @code{__add__()} at
all.)

@item 
Then @code{B}’s @ref{25d3,,__radd__()} gets a chance. If it accepts
@code{a}, all is well.

@item 
If it falls back to the boilerplate, there are no more possible
methods to try, so this is where the default implementation
should live.

@item 
If @code{B <: A}, Python tries @code{B.__radd__} before
@code{A.__add__}. This is ok, because it was implemented with
knowledge of @code{A}, so it can handle those instances before
delegating to @ref{27f6,,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{328,,complex}, and both @ref{25d3,,__radd__()} s land there, so @code{a+b
== b+a}.

Because most of the operations on any given type will be very similar,
it can be useful to define a helper function which generates the
forward and reverse instances of any given operator. For example,
@ref{1c3,,fractions.Fraction} uses:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node math — Mathematical functions,math integer — integer-specific mathematics functions,numbers — Numeric abstract base classes,Αριθμητικά και Μαθηματικά Modules
@anchor{library/math doc}@anchor{2c83}@anchor{library/math math-mathematical-functions}@anchor{2c84}@anchor{library/math module-math}@anchor{91}@anchor{library/math translation-repo}@anchor{2c85}
@subsection @code{math} — Mathematical functions


@geindex module; math

@c from math import fsum


__________________________________________________________________


This module provides access to common mathematical functions and constants,
including those defined by the C standard.

These functions cannot be used with complex numbers; use the functions of the
same name from the @ref{19,,cmath} module if you require support for complex
numbers.  The distinction between functions which support complex numbers and
those which don’t is made since most users do not want to learn quite as much
mathematics as required to understand complex numbers.  Receiving an exception
instead of a complex result allows earlier detection of the unexpected complex
number used as a parameter, so that the programmer can determine how and why it
was generated in the first place.

The following functions are provided by this module.  Except when explicitly
noted otherwise, all return values are floats.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

`Floating point arithmetic'

@tab

@item

@ref{1761,,ceil(x)}

@tab

Ceiling of `x', the smallest integer greater than or equal to `x'

@item

@ref{2c86,,fabs(x)}

@tab

Absolute value of `x'

@item

@ref{1760,,floor(x)}

@tab

Floor of `x', the largest integer less than or equal to `x'

@item

@ref{718,,fma(x@comma{} y@comma{} z)}

@tab

Fused multiply-add operation: @code{(x * y) + z}

@item

@ref{237,,fmax(x@comma{} y)}

@tab

Maximum of two floating-point values

@item

@ref{238,,fmin(x@comma{} y)}

@tab

Minimum of two floating-point values

@item

@ref{26bf,,fmod(x@comma{} y)}

@tab

Remainder of division @code{x / y}

@item

@ref{2c87,,modf(x)}

@tab

Fractional and integer parts of `x'

@item

@ref{f10,,remainder(x@comma{} y)}

@tab

Remainder of `x' with respect to `y'

@item

@ref{1762,,trunc(x)}

@tab

Integer part of `x'

@item

`Floating point manipulation functions'

@tab

@item

@ref{1776,,copysign(x@comma{} y)}

@tab

Magnitude (absolute value) of `x' with the sign of `y'

@item

@ref{2c88,,frexp(x)}

@tab

Mantissa and exponent of `x'

@item

@ref{1169,,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{1594,,isfinite(x)}

@tab

Check if `x' is neither an infinity nor a NaN

@item

@ref{235,,isnormal(x)}

@tab

Check if `x' is a normal number

@item

@ref{236,,issubnormal(x)}

@tab

Check if `x' is a subnormal number

@item

@ref{1774,,isinf(x)}

@tab

Check if `x' is a positive or negative infinity

@item

@ref{1775,,isnan(x)}

@tab

Check if `x' is a NaN  (not a number)

@item

@ref{1a3d,,ldexp(x@comma{} i)}

@tab

@code{x * (2**i)}, inverse of function @ref{2c88,,frexp()}

@item

@ref{8a9,,nextafter(x@comma{} y@comma{} steps)}

@tab

Floating-point value `steps' steps after `x' towards `y'

@item

@ref{239,,signbit(x)}

@tab

Check if `x' is a negative number

@item

@ref{ce1,,ulp(x)}

@tab

Value of the least significant bit of `x'

@item

`Power, exponential and logarithmic functions'

@tab

@item

@ref{a51,,cbrt(x)}

@tab

Cube root of `x'

@item

@ref{16b8,,exp(x)}

@tab

`e' raised to the power `x'

@item

@ref{a50,,exp2(x)}

@tab

`2' raised to the power `x'

@item

@ref{1595,,expm1(x)}

@tab

`e' raised to the power `x', minus 1

@item

@ref{1862,,log(x@comma{} base)}

@tab

Logarithm of `x' to the given base (`e' by default)

@item

@ref{177b,,log1p(x)}

@tab

Natural logarithm of `1+x' (base `e')

@item

@ref{1487,,log2(x)}

@tab

Base-2 logarithm of `x'

@item

@ref{19dc,,log10(x)}

@tab

Base-10 logarithm of `x'

@item

@ref{a52,,pow(x@comma{} y)}

@tab

`x' raised to the power `y'

@item

@ref{dc8,,sqrt(x)}

@tab

Square root of `x'

@item

`Summation and product functions'

@tab

@item

@ref{dc4,,dist(p@comma{} q)}

@tab

Euclidean distance between two points `p' and `q' given as an iterable of coordinates

@item

@ref{1777,,fsum(iterable)}

@tab

Sum of values in the input `iterable'

@item

@ref{dc5,,hypot(*coordinates)}

@tab

Euclidean norm of an iterable of coordinates

@item

@ref{dc6,,prod(iterable@comma{} start)}

@tab

Product of elements in the input `iterable' with a `start' value

@item

@ref{8a8,,sumprod(p@comma{} q)}

@tab

Sum of products from two iterables `p' and `q'

@item

`Angular conversion'

@tab

@item

@ref{2c89,,degrees(x)}

@tab

Convert angle `x' from radians to degrees

@item

@ref{2c8a,,radians(x)}

@tab

Convert angle `x' from degrees to radians

@item

`Trigonometric functions'

@tab

@item

@ref{2c8b,,acos(x)}

@tab

Arc cosine of `x'

@item

@ref{2c8c,,asin(x)}

@tab

Arc sine of `x'

@item

@ref{2c8d,,atan(x)}

@tab

Arc tangent of `x'

@item

@ref{2c8e,,atan2(y@comma{} x)}

@tab

@code{atan(y / x)}

@item

@ref{1861,,cos(x)}

@tab

Cosine of `x'

@item

@ref{1860,,sin(x)}

@tab

Sine of `x'

@item

@ref{2c8f,,tan(x)}

@tab

Tangent of `x'

@item

`Hyperbolic functions'

@tab

@item

@ref{1778,,acosh(x)}

@tab

Inverse hyperbolic cosine of `x'

@item

@ref{1779,,asinh(x)}

@tab

Inverse hyperbolic sine of `x'

@item

@ref{177a,,atanh(x)}

@tab

Inverse hyperbolic tangent of `x'

@item

@ref{2c90,,cosh(x)}

@tab

Hyperbolic cosine of `x'

@item

@ref{2c91,,sinh(x)}

@tab

Hyperbolic sine of `x'

@item

@ref{2c92,,tanh(x)}

@tab

Hyperbolic tangent of `x'

@item

`Special functions'

@tab

@item

@ref{f98,,erf(x)}

@tab

Error function@footnote{https://en.wikipedia.org/wiki/Error_function} at `x'

@item

@ref{f99,,erfc(x)}

@tab

Complementary error function@footnote{https://en.wikipedia.org/wiki/Error_function} at `x'

@item

@ref{1596,,gamma(x)}

@tab

Gamma function@footnote{https://en.wikipedia.org/wiki/Gamma_function} at `x'

@item

@ref{1597,,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{2c93,,pi}

@tab

`π' = 3.141592…

@item

@ref{2c94,,e}

@tab

`e' = 2.718281…

@item

@ref{2c95,,tau}

@tab

`τ' = 2`π' = 6.283185…

@item

@ref{1043,,inf}

@tab

Positive infinity

@item

@ref{a53,,nan}

@tab

«Not a number» (NaN)

@end multitable


@menu
* Floating point arithmetic:: 
* Floating point manipulation functions:: 
* Power@comma{} exponential and logarithmic functions: Power exponential and logarithmic functions. 
* Summation and product functions:: 
* Angular conversion:: 
* Trigonometric functions:: 
* Hyperbolic functions:: 
* Special functions:: 
* Number-theoretic functions:: 
* Constants: Constants<2>. 

@end menu

@node Floating point arithmetic,Floating point manipulation functions,,math — Mathematical functions
@anchor{library/math floating-point-arithmetic}@anchor{2c96}
@subsubsection Floating point arithmetic


@geindex ceil() (στη μονάδα math)
@anchor{library/math math ceil}@anchor{1761}
@deffn {Συνάρτηση} 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{25fe,,x.__ceil__},
which should return an @ref{25ff,,Integral} value.
@end deffn

@geindex fabs() (στη μονάδα math)
@anchor{library/math math fabs}@anchor{2c86}
@deffn {Συνάρτηση} math.fabs (x)

Return the absolute value of `x'.
@end deffn

@geindex floor() (στη μονάδα math)
@anchor{library/math math floor}@anchor{1760}
@deffn {Συνάρτηση} 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{25fd,,x.__floor__}, which
should return an @ref{25ff,,Integral} value.
@end deffn

@geindex fma() (στη μονάδα math)
@anchor{library/math math fma}@anchor{718}
@deffn {Συνάρτηση} 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.


Added in version 3.13.

@end deffn

@geindex fmax() (στη μονάδα math)
@anchor{library/math math fmax}@anchor{237}
@deffn {Συνάρτηση} math.fmax (x, y)

Get the larger of two floating-point values, treating NaNs as missing data.

When both operands are (signed) NaNs or zeroes, return @code{nan} and @code{0}
respectively and the sign of the result is implementation-defined, that
is, @code{fmax()} is not required to be sensitive to the sign of such
operands (see Annex F of the C11 standard, §F.10.0.3 and §F.10.9.2).


Added in version 3.15.

@end deffn

@geindex fmin() (στη μονάδα math)
@anchor{library/math math fmin}@anchor{238}
@deffn {Συνάρτηση} math.fmin (x, y)

Get the smaller of two floating-point values, treating NaNs as missing data.

When both operands are (signed) NaNs or zeroes, return @code{nan} and @code{0}
respectively and the sign of the result is implementation-defined, that
is, @code{fmin()} is not required to be sensitive to the sign of such
operands (see Annex F of the C11 standard, §F.10.0.3 and §F.10.9.3).


Added in version 3.15.

@end deffn

@geindex fmod() (στη μονάδα math)
@anchor{library/math math fmod}@anchor{26bf}
@deffn {Συνάρτηση} 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 @code{fmod()} is generally preferred when working with
floats, while Python’s @code{x % y} is preferred when working with integers.
@end deffn

@geindex modf() (στη μονάδα math)
@anchor{library/math math modf}@anchor{2c87}
@deffn {Συνάρτηση} math.modf (x)

Return the fractional and integer parts of `x'.  Both results carry the sign
of `x' and are floats.

Note that @code{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() (στη μονάδα math)
@anchor{library/math math remainder}@anchor{f10}
@deffn {Συνάρτηση} math.remainder (x, y)

Return the IEEE 754-style remainder of `x' with respect to `y'.  For
finite `x' and finite nonzero `y', this is the difference @code{x - n*y},
where @code{n} is the closest integer to the exact value of the quotient @code{x /
y}.  If @code{x / y} is exactly halfway between two consecutive integers, the
nearest `even' integer is used for @code{n}.  The remainder @code{r = remainder(x,
y)} thus always satisfies @code{abs(r) <= 0.5 * abs(y)}.

Special cases follow IEEE 754: in particular, @code{remainder(x, math.inf)} is
`x' for any finite `x', and @code{remainder(x, 0)} and
@code{remainder(math.inf, x)} raise @ref{277,,ValueError} for any non-NaN `x'.
If the result of the remainder operation is zero, that zero will have
the same sign as `x'.

On platforms using IEEE 754 binary floating point, the result of this
operation is always exactly representable: no rounding error is introduced.


Added in version 3.7.

@end deffn

@geindex trunc() (στη μονάδα math)
@anchor{library/math math trunc}@anchor{1762}
@deffn {Συνάρτηση} math.trunc (x)

Return `x' with the fractional part
removed, leaving the integer part.  This rounds toward 0: @code{trunc()} is
equivalent to @ref{1760,,floor()} for positive `x', and equivalent to @ref{1761,,ceil()}
for negative `x'. If `x' is not a float, delegates to @ref{43b,,x.__trunc__}, which should return an @ref{25ff,,Integral} value.
@end deffn

For the @ref{1761,,ceil()}, @ref{1760,,floor()}, and @ref{2c87,,modf()} functions, note that `all'
floating-point numbers of sufficiently large magnitude are exact integers.
Python floats typically carry no more than 53 bits of precision (the same as the
platform C double type), in which case any float `x' with @code{abs(x) >= 2**52}
necessarily has no fractional bits.

@node Floating point manipulation functions,Power exponential and logarithmic functions,Floating point arithmetic,math — Mathematical functions
@anchor{library/math floating-point-manipulation-functions}@anchor{2c97}
@subsubsection Floating point manipulation functions


@geindex copysign() (στη μονάδα math)
@anchor{library/math math copysign}@anchor{1776}
@deffn {Συνάρτηση} math.copysign (x, y)

Return a float with the magnitude (absolute value) of `x' but the sign of
`y'.  On platforms that support signed zeros, @code{copysign(1.0, -0.0)}
returns `-1.0'.
@end deffn

@geindex frexp() (στη μονάδα math)
@anchor{library/math math frexp}@anchor{2c88}
@deffn {Συνάρτηση} math.frexp (x)

Return the mantissa and exponent of `x' as the pair @code{(m, e)}.  `m' is a float
and `e' is an integer such that @code{x == m * 2**e} exactly. If `x' is zero,
returns @code{(0.0, 0)}, otherwise @code{0.5 <= abs(m) < 1}.  This is used to «pick
apart» the internal representation of a float in a portable way.

Note that @code{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() (στη μονάδα math)
@anchor{library/math math isclose}@anchor{1169}
@deffn {Συνάρτηση} math.isclose (a, b, *, rel_tol=1e-09, abs_tol=0.0)

Return @code{True} if the values `a' and `b' are close to each other and
@code{False} otherwise.

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 nonzero @code{x} and
`rel_tol' less than @code{1.0}.  So add an appropriate positive `abs_tol' argument
to the call.

The IEEE 754 special values of @code{NaN}, @code{inf}, and @code{-inf} will be
handled according to IEEE rules.  Specifically, @code{NaN} is not considered
close to any other value, including @code{NaN}.  @code{inf} and @code{-inf} are only
considered close to themselves.


Added in version 3.5.



@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 485
PEP 485@footnote{https://peps.python.org/pep-0485/} – A function for testing approximate equality

@end deffn

@geindex isfinite() (στη μονάδα math)
@anchor{library/math math isfinite}@anchor{1594}
@deffn {Συνάρτηση} math.isfinite (x)

Return @code{True} if `x' is neither an infinity nor a NaN, and
@code{False} otherwise.  (Note that @code{0.0} `is' considered finite.)


Added in version 3.2.

@end deffn

@geindex isnormal() (στη μονάδα math)
@anchor{library/math math isnormal}@anchor{235}
@deffn {Συνάρτηση} math.isnormal (x)

Return @code{True} if `x' is a normal number, that is a finite
nonzero number that is not a subnormal (see @ref{236,,issubnormal()}).
Return @code{False} otherwise.


Added in version 3.15.

@end deffn

@geindex issubnormal() (στη μονάδα math)
@anchor{library/math math issubnormal}@anchor{236}
@deffn {Συνάρτηση} math.issubnormal (x)

Return @code{True} if `x' is a subnormal number, that is a finite
nonzero number with a magnitude smaller than @ref{2c98,,sys.float_info.min}.
Return @code{False} otherwise.


Added in version 3.15.

@end deffn

@geindex isinf() (στη μονάδα math)
@anchor{library/math math isinf}@anchor{1774}
@deffn {Συνάρτηση} math.isinf (x)

Return @code{True} if `x' is a positive or negative infinity, and
@code{False} otherwise.
@end deffn

@geindex isnan() (στη μονάδα math)
@anchor{library/math math isnan}@anchor{1775}
@deffn {Συνάρτηση} math.isnan (x)

Return @code{True} if `x' is a NaN (not a number), and @code{False} otherwise.
@end deffn

@geindex ldexp() (στη μονάδα math)
@anchor{library/math math ldexp}@anchor{1a3d}
@deffn {Συνάρτηση} math.ldexp (x, i)

Return @code{x * (2**i)}.  This is essentially the inverse of function
@ref{2c88,,frexp()}.
@end deffn

@geindex nextafter() (στη μονάδα math)
@anchor{library/math math nextafter}@anchor{8a9}
@deffn {Συνάρτηση} 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.

Examples:


@itemize *

@item 
@code{math.nextafter(x, math.inf)} goes up: towards positive infinity.

@item 
@code{math.nextafter(x, -math.inf)} goes down: towards minus infinity.

@item 
@code{math.nextafter(x, 0.0)} goes towards zero.

@item 
@code{math.nextafter(x, math.copysign(math.inf, x))} goes away from zero.
@end itemize

See also @ref{ce1,,math.ulp()}.


Added in version 3.9.



Άλλαξε στην έκδοση 3.12: Added the `steps' argument.

@end deffn

@geindex signbit() (στη μονάδα math)
@anchor{library/math math signbit}@anchor{239}
@deffn {Συνάρτηση} math.signbit (x)

Return @code{True} if the sign of `x' is negative and @code{False} otherwise.

This is useful to detect the sign bit of zeroes, infinities and NaNs.


Added in version 3.15.

@end deffn

@geindex ulp() (στη μονάδα math)
@anchor{library/math math ulp}@anchor{ce1}
@deffn {Συνάρτηση} 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{1fbf,,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{8a9,,math.nextafter()} and @ref{1fbf,,sys.float_info.epsilon}.


Added in 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{2c99}
@subsubsection Power, exponential and logarithmic functions


@geindex cbrt() (στη μονάδα math)
@anchor{library/math math cbrt}@anchor{a51}
@deffn {Συνάρτηση} math.cbrt (x)

Return the cube root of `x'.


Added in version 3.11.

@end deffn

@geindex exp() (στη μονάδα math)
@anchor{library/math math exp}@anchor{16b8}
@deffn {Συνάρτηση} math.exp (x)

Return `e' raised to the power `x', where `e' = 2.718281… is the base
of natural logarithms.  This is usually more accurate than @code{math.e ** x}
or @code{pow(math.e, x)}.
@end deffn

@geindex exp2() (στη μονάδα math)
@anchor{library/math math exp2}@anchor{a50}
@deffn {Συνάρτηση} math.exp2 (x)

Return `2' raised to the power `x'.


Added in version 3.11.

@end deffn

@geindex expm1() (στη μονάδα math)
@anchor{library/math math expm1}@anchor{1595}
@deffn {Συνάρτηση} 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 @code{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


Added in version 3.2.

@end deffn

@geindex log() (στη μονάδα math)
@anchor{library/math math log}@anchor{1862}
@deffn {Συνάρτηση} math.log (x[, base])

With one argument, return the natural logarithm of `x' (to base `e').

With two arguments, return the logarithm of `x' to the given `base',
calculated as @code{log(x)/log(base)}.
@end deffn

@geindex log1p() (στη μονάδα math)
@anchor{library/math math log1p}@anchor{177b}
@deffn {Συνάρτηση} math.log1p (x)

Return the natural logarithm of `1+x' (base `e'). The
result is calculated in a way which is accurate for `x' near zero.
@end deffn

@geindex log2() (στη μονάδα math)
@anchor{library/math math log2}@anchor{1487}
@deffn {Συνάρτηση} math.log2 (x)

Return the base-2 logarithm of `x'. This is usually more accurate than
@code{log(x, 2)}.


Added in version 3.3.



@subsubheading Δείτε επίσης


@ref{27f0,,int.bit_length()} returns the number of bits necessary to represent
an integer in binary, excluding the sign and leading zeros.

@end deffn

@geindex log10() (στη μονάδα math)
@anchor{library/math math log10}@anchor{19dc}
@deffn {Συνάρτηση} math.log10 (x)

Return the base-10 logarithm of `x'.  This is usually more accurate
than @code{log(x, 10)}.
@end deffn

@geindex pow() (στη μονάδα math)
@anchor{library/math math pow}@anchor{a52}
@deffn {Συνάρτηση} 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{277,,ValueError}.

Unlike the built-in @code{**} operator, @ref{a52,,math.pow()} converts both
its arguments to type @ref{327,,float}.  Use @code{**} or the built-in
@code{pow()} function for computing exact integer powers.


Άλλαξε στην έκδοση 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{277,,ValueError},
for consistency with IEEE 754.

@end deffn

@geindex sqrt() (στη μονάδα math)
@anchor{library/math math sqrt}@anchor{dc8}
@deffn {Συνάρτηση} math.sqrt (x)

Return the square root of `x'.
@end deffn

@node Summation and product functions,Angular conversion,Power exponential and logarithmic functions,math — Mathematical functions
@anchor{library/math summation-and-product-functions}@anchor{2c9a}
@subsubsection Summation and product functions


@geindex dist() (στη μονάδα math)
@anchor{library/math math dist}@anchor{dc4}
@deffn {Συνάρτηση} math.dist (p, q)

Return the Euclidean distance between two points `p' and `q', each
given as a sequence (or iterable) of coordinates.  The two points
must have the same dimension.

Roughly equivalent to:

@example
sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q, strict=True)))
@end example


Added in version 3.8.

@end deffn

@geindex fsum() (στη μονάδα math)
@anchor{library/math math fsum}@anchor{1777}
@deffn {Συνάρτηση} math.fsum (iterable)

Return an accurate floating-point sum of values in the iterable.  Avoids
loss of precision by tracking multiple intermediate partial sums.

The algorithm’s accuracy depends on IEEE-754 arithmetic guarantees and the
typical case where the rounding mode is half-even.  On some non-Windows
builds, the underlying C library uses extended precision addition and may
occasionally double-round an intermediate sum causing it to be off in its
least significant bit.

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() (στη μονάδα math)
@anchor{library/math math hypot}@anchor{dc5}
@deffn {Συνάρτηση} math.hypot (*coordinates)

Return the Euclidean norm, @code{sqrt(sum(x**2 for x in coordinates))}.
This is the length of the vector from the origin to the point
given by the coordinates.

For a two dimensional point @code{(x, y)}, this is equivalent to computing
the hypotenuse of a right triangle using the Pythagorean theorem,
@code{sqrt(x*x + y*y)}.


Άλλαξε στην έκδοση 3.8: Added support for n-dimensional points. Formerly, only the two
dimensional case was supported.



Άλλαξε στην έκδοση 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() (στη μονάδα math)
@anchor{library/math math prod}@anchor{dc6}
@deffn {Συνάρτηση} math.prod (iterable, *, start=1)

Calculate the product of all the elements in the input `iterable'.
The default `start' value for the product is @code{1}.

When the iterable is empty, return the start value.  This function is
intended specifically for use with numeric values and may reject
non-numeric types.


Added in version 3.8.

@end deffn

@geindex sumprod() (στη μονάδα math)
@anchor{library/math math sumprod}@anchor{8a8}
@deffn {Συνάρτηση} math.sumprod (p, q)

Return the sum of products of values from two iterables `p' and `q'.

Raises @ref{277,,ValueError} if the inputs do not have the same length.

Roughly equivalent to:

@example
sum(map(operator.mul, p, q, strict=True))
@end example

For float and mixed int/float inputs, the intermediate products
and sums are computed with extended precision.


Added in version 3.12.

@end deffn

@node Angular conversion,Trigonometric functions,Summation and product functions,math — Mathematical functions
@anchor{library/math angular-conversion}@anchor{2c9b}
@subsubsection Angular conversion


@geindex degrees() (στη μονάδα math)
@anchor{library/math math degrees}@anchor{2c89}
@deffn {Συνάρτηση} math.degrees (x)

Convert angle `x' from radians to degrees.
@end deffn

@geindex radians() (στη μονάδα math)
@anchor{library/math math radians}@anchor{2c8a}
@deffn {Συνάρτηση} math.radians (x)

Convert angle `x' from degrees to radians.
@end deffn

@node Trigonometric functions,Hyperbolic functions,Angular conversion,math — Mathematical functions
@anchor{library/math trigonometric-functions}@anchor{2c9c}
@subsubsection Trigonometric functions


@geindex acos() (στη μονάδα math)
@anchor{library/math math acos}@anchor{2c8b}
@deffn {Συνάρτηση} math.acos (x)

Return the arc cosine of `x', in radians. The result is between @code{0} and
@code{pi}.
@end deffn

@geindex asin() (στη μονάδα math)
@anchor{library/math math asin}@anchor{2c8c}
@deffn {Συνάρτηση} 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() (στη μονάδα math)
@anchor{library/math math atan}@anchor{2c8d}
@deffn {Συνάρτηση} 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() (στη μονάδα math)
@anchor{library/math math atan2}@anchor{2c8e}
@deffn {Συνάρτηση} math.atan2 (y, x)

Return @code{atan(y / x)}, in radians. The result is between @code{-pi} and @code{pi}.
The vector in the plane from the origin to point @code{(x, y)} makes this angle
with the positive X axis. The point of @code{atan2()} is that the signs of both
inputs are known to it, so it can compute the correct quadrant for the angle.
For example, @code{atan(1)} and @code{atan2(1, 1)} are both @code{pi/4}, but @code{atan2(-1,
-1)} is @code{-3*pi/4}.
@end deffn

@geindex cos() (στη μονάδα math)
@anchor{library/math math cos}@anchor{1861}
@deffn {Συνάρτηση} math.cos (x)

Return the cosine of `x' radians.
@end deffn

@geindex sin() (στη μονάδα math)
@anchor{library/math math sin}@anchor{1860}
@deffn {Συνάρτηση} math.sin (x)

Return the sine of `x' radians.
@end deffn

@geindex tan() (στη μονάδα math)
@anchor{library/math math tan}@anchor{2c8f}
@deffn {Συνάρτηση} math.tan (x)

Return the tangent of `x' radians.
@end deffn

@node Hyperbolic functions,Special functions,Trigonometric functions,math — Mathematical functions
@anchor{library/math hyperbolic-functions}@anchor{2c9d}
@subsubsection Hyperbolic functions


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() (στη μονάδα math)
@anchor{library/math math acosh}@anchor{1778}
@deffn {Συνάρτηση} math.acosh (x)

Return the inverse hyperbolic cosine of `x'.
@end deffn

@geindex asinh() (στη μονάδα math)
@anchor{library/math math asinh}@anchor{1779}
@deffn {Συνάρτηση} math.asinh (x)

Return the inverse hyperbolic sine of `x'.
@end deffn

@geindex atanh() (στη μονάδα math)
@anchor{library/math math atanh}@anchor{177a}
@deffn {Συνάρτηση} math.atanh (x)

Return the inverse hyperbolic tangent of `x'.
@end deffn

@geindex cosh() (στη μονάδα math)
@anchor{library/math math cosh}@anchor{2c90}
@deffn {Συνάρτηση} math.cosh (x)

Return the hyperbolic cosine of `x'.
@end deffn

@geindex sinh() (στη μονάδα math)
@anchor{library/math math sinh}@anchor{2c91}
@deffn {Συνάρτηση} math.sinh (x)

Return the hyperbolic sine of `x'.
@end deffn

@geindex tanh() (στη μονάδα math)
@anchor{library/math math tanh}@anchor{2c92}
@deffn {Συνάρτηση} math.tanh (x)

Return the hyperbolic tangent of `x'.
@end deffn

@node Special functions,Number-theoretic functions,Hyperbolic functions,math — Mathematical functions
@anchor{library/math special-functions}@anchor{2c9e}
@subsubsection Special functions


@geindex erf() (στη μονάδα math)
@anchor{library/math math erf}@anchor{f98}
@deffn {Συνάρτηση} math.erf (x)

Return the error function@footnote{https://en.wikipedia.org/wiki/Error_function} at
`x'.

The @code{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


Added in version 3.2.

@end deffn

@geindex erfc() (στη μονάδα math)
@anchor{library/math math erfc}@anchor{f99}
@deffn {Συνάρτηση} math.erfc (x)

Return the complementary error function at `x'.  The complementary error function@footnote{https://en.wikipedia.org/wiki/Error_function} is defined as
@code{1.0 - erf(x)}.  It is used for large values of `x' where a subtraction
from one would cause a loss of significance@footnote{https://en.wikipedia.org/wiki/Loss_of_significance}.


Added in version 3.2.

@end deffn

@geindex gamma() (στη μονάδα math)
@anchor{library/math math gamma}@anchor{1596}
@deffn {Συνάρτηση} math.gamma (x)

Return the Gamma function@footnote{https://en.wikipedia.org/wiki/Gamma_function} at
`x'.


Added in version 3.2.

@end deffn

@geindex lgamma() (στη μονάδα math)
@anchor{library/math math lgamma}@anchor{1597}
@deffn {Συνάρτηση} math.lgamma (x)

Return the natural logarithm of the absolute value of the Gamma
function at `x'.


Added in version 3.2.

@end deffn

@node Number-theoretic functions,Constants<2>,Special functions,math — Mathematical functions
@anchor{library/math number-theoretic-functions}@anchor{2c9f}
@subsubsection Number-theoretic functions


For backward compatibility, the @code{math} module provides also aliases of
the following functions from the @ref{92,,math.integer} module:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex comb() (στη μονάδα math)
@anchor{library/math math comb}@anchor{abd}
@ref{2ca0,,comb(n@comma{} k)}

@tab

Number of ways to choose `k' items from `n' items without repetition
and without order

@item

@geindex factorial() (στη μονάδα math)
@anchor{library/math math factorial}@anchor{d13}
@ref{2ca1,,factorial(n)}

@tab

`n' factorial

@item

@geindex gcd() (στη μονάδα math)
@anchor{library/math math gcd}@anchor{cdf}
@ref{2ca2,,gcd(*integers)}

@tab

Greatest common divisor of the integer arguments

@item

@geindex isqrt() (στη μονάδα math)
@anchor{library/math math isqrt}@anchor{dc7}
@ref{2ca3,,isqrt(n)}

@tab

Integer square root of a nonnegative integer `n'

@item

@geindex lcm() (στη μονάδα math)
@anchor{library/math math lcm}@anchor{ce0}
@ref{2ca4,,lcm(*integers)}

@tab

Least common multiple of the integer arguments

@item

@geindex perm() (στη μονάδα math)
@anchor{library/math math perm}@anchor{abe}
@ref{2ca5,,perm(n@comma{} k)}

@tab

Number of ways to choose `k' items from `n' items without repetition
and with order

@end multitable



Added in version 3.5: The @ref{cdf,,gcd()} function.



Added in version 3.8: The @ref{abd,,comb()}, @ref{abe,,perm()} and @ref{dc7,,isqrt()} functions.



Added in version 3.9: The @ref{ce0,,lcm()} function.



Άλλαξε στην έκδοση 3.9: Added support for an arbitrary number of arguments in the @ref{cdf,,gcd()}
function.
Formerly, only two arguments were supported.



Άλλαξε στην έκδοση 3.10: Floats with integral values (like @code{5.0}) are no longer accepted in the
@ref{d13,,factorial()} function.



@ref{1a7,,Soft deprecated} since version 3.15: Use the @ref{92,,math.integer} functions instead of these aliases.


@node Constants<2>,,Number-theoretic functions,math — Mathematical functions
@anchor{library/math constants}@anchor{2ca6}
@subsubsection Constants


@geindex pi (στη μονάδα math)
@anchor{library/math math pi}@anchor{2c93}
@deffn {Δεδομένα} math.pi

The mathematical constant `π' = 3.141592…, to available precision.
@end deffn

@geindex e (στη μονάδα math)
@anchor{library/math math e}@anchor{2c94}
@deffn {Δεδομένα} math.e

The mathematical constant `e' = 2.718281…, to available precision.
@end deffn

@geindex tau (στη μονάδα math)
@anchor{library/math math tau}@anchor{2c95}
@deffn {Δεδομένα} math.tau

The mathematical constant `τ' = 6.283185…, to available precision.
Tau is a circle constant equal to 2`π', the ratio of a circle’s circumference to
its radius. To learn more about Tau, check out Vi Hart’s video Pi is (still) Wrong@footnote{https://vimeo.com/147792667}, and start celebrating
Tau day@footnote{https://tauday.com/} by eating twice as much pie!


Added in version 3.6.

@end deffn

@geindex inf (στη μονάδα math)
@anchor{library/math math inf}@anchor{1043}
@deffn {Δεδομένα} math.inf

A floating-point positive infinity.  (For negative infinity, use
@code{-math.inf}.)  Equivalent to the output of @code{float('inf')}.


Added in version 3.5.

@end deffn

@geindex nan (στη μονάδα math)
@anchor{library/math math nan}@anchor{a53}
@deffn {Δεδομένα} 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{1775,,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


Added in version 3.5.



Άλλαξε στην έκδοση 3.11: It is now always available.

@end deffn

`Λεπτομέρεια υλοποίησης CPython:' The @code{math} module consists mostly of thin wrappers around the platform C
math library functions.  Behavior in exceptional cases follows Annex F of
the C99 standard where appropriate.  The current implementation will raise
@ref{277,,ValueError} for invalid operations like @code{sqrt(-1.0)} or @code{log(0.0)}
(where C99 Annex F recommends signaling invalid operation or divide-by-zero),
and @ref{c57,,OverflowError} for results that overflow (for example,
@code{exp(1000.0)}).  A NaN will not be returned from any of the functions
above unless one or more of the input arguments was a NaN; in that case,
most functions will return a NaN, but (again following C99 Annex F) there
are some exceptions to this rule, for example @code{pow(float('nan'), 0.0)} or
@code{hypot(float('nan'), float('inf'))}.

Note that Python makes no effort to distinguish signaling NaNs from
quiet NaNs, and behavior for signaling NaNs remains unspecified.
Typical behavior is to treat all NaNs as though they were quiet.


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{19,,cmath}

Complex number versions of many of these functions.

@item Module @ref{92,,math.integer}

Integer-specific mathematics functions.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node math integer — integer-specific mathematics functions,cmath — Mathematical functions for complex numbers,math — Mathematical functions,Αριθμητικά και Μαθηματικά Modules
@anchor{library/math integer doc}@anchor{2ca7}@anchor{library/math integer math-integer-integer-specific-mathematics-functions}@anchor{2ca8}@anchor{library/math integer module-math integer}@anchor{92}@anchor{library/math integer translation-repo}@anchor{2ca9}
@subsection @code{math.integer} — integer-specific mathematics functions


@geindex module; math.integer


Added in version 3.15.



__________________________________________________________________


This module provides access to the mathematical functions defined for integer arguments.
These functions accept integers and objects that implement the
@ref{43d,,__index__()} method which is used to convert the object to an integer
number.

The following functions are provided by this module.  All return values are
computed exactly and are integers.

@geindex comb() (στη μονάδα math.integer)
@anchor{library/math integer math integer comb}@anchor{2ca0}
@deffn {Συνάρτηση} math.integer.comb (n, k, /)

Return the number of ways to choose `k' items from `n' items without repetition
and without order.

Evaluates to @code{n! / (k! * (n - k)!)} when @code{k <= n} and evaluates
to zero when @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)ⁿ}.

Raises @ref{277,,ValueError} if either of the arguments are negative.
@end deffn

@geindex factorial() (στη μονάδα math.integer)
@anchor{library/math integer math integer factorial}@anchor{2ca1}
@deffn {Συνάρτηση} math.integer.factorial (n, /)

Return factorial of the nonnegative integer `n'.
@end deffn

@geindex gcd() (στη μονάδα math.integer)
@anchor{library/math integer math integer gcd}@anchor{2ca2}
@deffn {Συνάρτηση} math.integer.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}.
@end deffn

@geindex isqrt() (στη μονάδα math.integer)
@anchor{library/math integer math integer isqrt}@anchor{2ca3}
@deffn {Συνάρτηση} math.integer.isqrt (n, /)

Return the integer square root of the nonnegative integer `n'. This is the
floor of the exact square root of `n', or equivalently the greatest integer
`a' such that `a'² ≤ `n'.

For some applications, it may be more convenient to have the least integer
`a' such that `n' ≤ `a'², or in other words the ceiling of
the exact square root of `n'. For positive `n', this can be computed using
@code{a = 1 + isqrt(n - 1)}.
@end deffn

@geindex lcm() (στη μονάδα math.integer)
@anchor{library/math integer math integer lcm}@anchor{2ca4}
@deffn {Συνάρτηση} math.integer.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}.
@end deffn

@geindex perm() (στη μονάδα math.integer)
@anchor{library/math integer math integer perm}@anchor{2ca5}
@deffn {Συνάρτηση} math.integer.perm (n, k=None, /)

Return the number of ways to choose `k' items from `n' items
without repetition and with order.

Evaluates to @code{n! / (n - k)!} when @code{k <= n} and evaluates
to zero when @code{k > n}.

If `k' is not specified or is @code{None}, then `k' defaults to `n'
and the function returns @code{n!}.

Raises @ref{277,,ValueError} if either of the arguments are negative.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node cmath — Mathematical functions for complex numbers,decimal — Decimal fixed-point and floating-point arithmetic,math integer — integer-specific mathematics functions,Αριθμητικά και Μαθηματικά Modules
@anchor{library/cmath doc}@anchor{2caa}@anchor{library/cmath cmath-mathematical-functions-for-complex-numbers}@anchor{2cab}@anchor{library/cmath module-cmath}@anchor{19}@anchor{library/cmath translation-repo}@anchor{2cac}
@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{9de,,__complex__()} or a @ref{d92,,__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 Σημείωση 
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{2cad,,cmath.sqrt()} function has a branch cut along the
negative real axis. An argument of @code{-2-0j} is treated as
though it lies `below' the branch cut, and so gives a result on the negative
imaginary axis:

@example
>>> cmath.sqrt(-2-0j)
-1.4142135623730951j
@end example

But an argument of @code{-2+0j} is treated as though it lies above
the branch cut:

@example
>>> cmath.sqrt(-2+0j)
1.4142135623730951j
@end example
@end quotation
@end cartouche


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

`Conversions to and from polar coordinates'

@tab

@item

@ref{2cae,,phase(z)}

@tab

Return the phase of `z'

@item

@ref{2caf,,polar(z)}

@tab

Return the representation of `z' in polar coordinates

@item

@ref{2cb0,,rect(r@comma{} phi)}

@tab

Return the complex number `z' with polar coordinates `r' and `phi'

@item

`Power and logarithmic functions'

@tab

@item

@ref{2cb1,,exp(z)}

@tab

Return `e' raised to the power `z'

@item

@ref{2cb2,,log(z[@comma{} base])}

@tab

Return the logarithm of `z' to the given `base' (`e' by default)

@item

@ref{2cb3,,log10(z)}

@tab

Return the base-10 logarithm of `z'

@item

@ref{2cad,,sqrt(z)}

@tab

Return the square root of `z'

@item

`Trigonometric functions'

@tab

@item

@ref{2cb4,,acos(z)}

@tab

Return the arc cosine of `z'

@item

@ref{2cb5,,asin(z)}

@tab

Return the arc sine of `z'

@item

@ref{2cb6,,atan(z)}

@tab

Return the arc tangent of `z'

@item

@ref{2cb7,,cos(z)}

@tab

Return the cosine of `z'

@item

@ref{2cb8,,sin(z)}

@tab

Return the sine of `z'

@item

@ref{2cb9,,tan(z)}

@tab

Return the tangent of `z'

@item

`Hyperbolic functions'

@tab

@item

@ref{2cba,,acosh(z)}

@tab

Return the inverse hyperbolic cosine of `z'

@item

@ref{2cbb,,asinh(z)}

@tab

Return the inverse hyperbolic sine of `z'

@item

@ref{2cbc,,atanh(z)}

@tab

Return the inverse hyperbolic tangent of `z'

@item

@ref{2cbd,,cosh(z)}

@tab

Return the hyperbolic cosine of `z'

@item

@ref{2cbe,,sinh(z)}

@tab

Return the hyperbolic sine of `z'

@item

@ref{2cbf,,tanh(z)}

@tab

Return the hyperbolic tangent of `z'

@item

`Classification functions'

@tab

@item

@ref{2cc0,,isfinite(z)}

@tab

Check if all components of `z' are finite

@item

@ref{2cc1,,isinf(z)}

@tab

Check if any component of `z' is infinite

@item

@ref{2cc2,,isnan(z)}

@tab

Check if any component of `z' is a NaN

@item

@ref{116a,,isclose(a@comma{} b@comma{} *@comma{} rel_tol@comma{} abs_tol)}

@tab

Check if the values `a' and `b' are close to each other

@item

`Constants'

@tab

@item

@ref{2cc3,,pi}

@tab

`π' = 3.141592…

@item

@ref{2cc4,,e}

@tab

`e' = 2.718281…

@item

@ref{1040,,tau}

@tab

`τ' = 2`π' = 6.283185…

@item

@ref{1041,,inf}

@tab

Positive infinity

@item

@ref{1044,,infj}

@tab

Pure imaginary infinity

@item

@ref{1042,,nan}

@tab

«Not a number» (NaN)

@item

@ref{1045,,nanj}

@tab

Pure imaginary NaN

@end multitable


@menu
* Conversions to and from polar coordinates:: 
* Power and logarithmic functions:: 
* Trigonometric functions: Trigonometric functions<2>. 
* Hyperbolic functions: Hyperbolic functions<2>. 
* Classification functions:: 
* Constants: Constants<3>. 

@end menu

@node Conversions to and from polar coordinates,Power and logarithmic functions,,cmath — Mathematical functions for complex numbers
@anchor{library/cmath conversions-to-and-from-polar-coordinates}@anchor{2cc5}
@subsubsection Conversions to and from polar coordinates


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}.

`Polar coordinates' give an alternative way to represent a complex
number.  In polar coordinates, a complex number `z' is defined by the
modulus `r' and the phase angle `phi'. The modulus `r' is the distance
from `z' to the origin, while the phase `phi' is the counterclockwise
angle, measured in radians, from the positive x-axis to the line
segment that joins the origin to `z'.

The following functions can be used to convert from the native
rectangular coordinates to polar coordinates and back.

@geindex phase() (στη μονάδα cmath)
@anchor{library/cmath cmath phase}@anchor{2cae}
@deffn {Συνάρτηση} cmath.phase (z)

Return the phase of `z' (also known as the `argument' of `z'), as a float.
@code{phase(z)} is equivalent to @code{math.atan2(z.imag, z.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{z.imag}, even when @code{z.imag} is zero:

@example
>>> phase(-1+0j)
3.141592653589793
>>> phase(-1-0j)
-3.141592653589793
@end example
@end deffn

@cartouche
@quotation Σημείωση 
The modulus (absolute value) of a complex number `z' can be
computed using the built-in @ref{227c,,abs()} function.  There is no
separate @code{cmath} module function for this operation.
@end quotation
@end cartouche

@geindex polar() (στη μονάδα cmath)
@anchor{library/cmath cmath polar}@anchor{2caf}
@deffn {Συνάρτηση} cmath.polar (z)

Return the representation of `z' in polar coordinates.  Returns a
pair @code{(r, phi)} where `r' is the modulus of `z' and `phi' is the
phase of `z'.  @code{polar(z)} is equivalent to @code{(abs(z),
phase(z))}.
@end deffn

@geindex rect() (στη μονάδα cmath)
@anchor{library/cmath cmath rect}@anchor{2cb0}
@deffn {Συνάρτηση} cmath.rect (r, phi)

Return the complex number `z' with polar coordinates `r' and `phi'.
Equivalent to @code{complex(r * math.cos(phi), r * math.sin(phi))}.
@end deffn

@node Power and logarithmic functions,Trigonometric functions<2>,Conversions to and from polar coordinates,cmath — Mathematical functions for complex numbers
@anchor{library/cmath power-and-logarithmic-functions}@anchor{2cc6}
@subsubsection Power and logarithmic functions


@geindex exp() (στη μονάδα cmath)
@anchor{library/cmath cmath exp}@anchor{2cb1}
@deffn {Συνάρτηση} cmath.exp (z)

Return `e' raised to the power `z', where `e' is the base of natural
logarithms.
@end deffn

@geindex log() (στη μονάδα cmath)
@anchor{library/cmath cmath log}@anchor{2cb2}
@deffn {Συνάρτηση} cmath.log (z[, base])

Return the logarithm of `z' to the given `base'. If the `base' is not
specified, returns the natural logarithm of `z'. There is one branch cut,
from 0 along the negative real axis to -∞.
@end deffn

@geindex log10() (στη μονάδα cmath)
@anchor{library/cmath cmath log10}@anchor{2cb3}
@deffn {Συνάρτηση} cmath.log10 (z)

Return the base-10 logarithm of `z'. This has the same branch cut as
@ref{2cb2,,log()}.
@end deffn

@geindex sqrt() (στη μονάδα cmath)
@anchor{library/cmath cmath sqrt}@anchor{2cad}
@deffn {Συνάρτηση} cmath.sqrt (z)

Return the square root of `z'. This has the same branch cut as @ref{2cb2,,log()}.
@end deffn

@node Trigonometric functions<2>,Hyperbolic functions<2>,Power and logarithmic functions,cmath — Mathematical functions for complex numbers
@anchor{library/cmath trigonometric-functions}@anchor{2cc7}
@subsubsection Trigonometric functions


@geindex acos() (στη μονάδα cmath)
@anchor{library/cmath cmath acos}@anchor{2cb4}
@deffn {Συνάρτηση} cmath.acos (z)

Return the arc cosine of `z'. 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() (στη μονάδα cmath)
@anchor{library/cmath cmath asin}@anchor{2cb5}
@deffn {Συνάρτηση} cmath.asin (z)

Return the arc sine of `z'. This has the same branch cuts as @ref{2cb4,,acos()}.
@end deffn

@geindex atan() (στη μονάδα cmath)
@anchor{library/cmath cmath atan}@anchor{2cb6}
@deffn {Συνάρτηση} cmath.atan (z)

Return the arc tangent of `z'. 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() (στη μονάδα cmath)
@anchor{library/cmath cmath cos}@anchor{2cb7}
@deffn {Συνάρτηση} cmath.cos (z)

Return the cosine of `z'.
@end deffn

@geindex sin() (στη μονάδα cmath)
@anchor{library/cmath cmath sin}@anchor{2cb8}
@deffn {Συνάρτηση} cmath.sin (z)

Return the sine of `z'.
@end deffn

@geindex tan() (στη μονάδα cmath)
@anchor{library/cmath cmath tan}@anchor{2cb9}
@deffn {Συνάρτηση} cmath.tan (z)

Return the tangent of `z'.
@end deffn

@node Hyperbolic functions<2>,Classification functions,Trigonometric functions<2>,cmath — Mathematical functions for complex numbers
@anchor{library/cmath hyperbolic-functions}@anchor{2cc8}
@subsubsection Hyperbolic functions


@geindex acosh() (στη μονάδα cmath)
@anchor{library/cmath cmath acosh}@anchor{2cba}
@deffn {Συνάρτηση} cmath.acosh (z)

Return the inverse hyperbolic cosine of `z'. There is one branch cut,
extending left from 1 along the real axis to -∞.
@end deffn

@geindex asinh() (στη μονάδα cmath)
@anchor{library/cmath cmath asinh}@anchor{2cbb}
@deffn {Συνάρτηση} cmath.asinh (z)

Return the inverse hyperbolic sine of `z'. 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() (στη μονάδα cmath)
@anchor{library/cmath cmath atanh}@anchor{2cbc}
@deffn {Συνάρτηση} cmath.atanh (z)

Return the inverse hyperbolic tangent of `z'. 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() (στη μονάδα cmath)
@anchor{library/cmath cmath cosh}@anchor{2cbd}
@deffn {Συνάρτηση} cmath.cosh (z)

Return the hyperbolic cosine of `z'.
@end deffn

@geindex sinh() (στη μονάδα cmath)
@anchor{library/cmath cmath sinh}@anchor{2cbe}
@deffn {Συνάρτηση} cmath.sinh (z)

Return the hyperbolic sine of `z'.
@end deffn

@geindex tanh() (στη μονάδα cmath)
@anchor{library/cmath cmath tanh}@anchor{2cbf}
@deffn {Συνάρτηση} cmath.tanh (z)

Return the hyperbolic tangent of `z'.
@end deffn

@node Classification functions,Constants<3>,Hyperbolic functions<2>,cmath — Mathematical functions for complex numbers
@anchor{library/cmath classification-functions}@anchor{2cc9}
@subsubsection Classification functions


@geindex isfinite() (στη μονάδα cmath)
@anchor{library/cmath cmath isfinite}@anchor{2cc0}
@deffn {Συνάρτηση} cmath.isfinite (z)

Return @code{True} if both the real and imaginary parts of `z' are finite, and
@code{False} otherwise.


Added in version 3.2.

@end deffn

@geindex isinf() (στη μονάδα cmath)
@anchor{library/cmath cmath isinf}@anchor{2cc1}
@deffn {Συνάρτηση} cmath.isinf (z)

Return @code{True} if either the real or the imaginary part of `z' is an
infinity, and @code{False} otherwise.
@end deffn

@geindex isnan() (στη μονάδα cmath)
@anchor{library/cmath cmath isnan}@anchor{2cc2}
@deffn {Συνάρτηση} cmath.isnan (z)

Return @code{True} if either the real or the imaginary part of `z' is a NaN,
and @code{False} otherwise.
@end deffn

@geindex isclose() (στη μονάδα cmath)
@anchor{library/cmath cmath isclose}@anchor{116a}
@deffn {Συνάρτηση} cmath.isclose (a, b, *, rel_tol=1e-09, abs_tol=0.0)

Return @code{True} if the values `a' and `b' are close to each other and
@code{False} otherwise.

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.

The IEEE 754 special values of @code{NaN}, @code{inf}, and @code{-inf} will be
handled according to IEEE rules.  Specifically, @code{NaN} is not considered
close to any other value, including @code{NaN}.  @code{inf} and @code{-inf} are only
considered close to themselves.


Added in version 3.5.



@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 485
PEP 485@footnote{https://peps.python.org/pep-0485/} – A function for testing approximate equality

@end deffn

@node Constants<3>,,Classification functions,cmath — Mathematical functions for complex numbers
@anchor{library/cmath constants}@anchor{2cca}
@subsubsection Constants


@geindex pi (στη μονάδα cmath)
@anchor{library/cmath cmath pi}@anchor{2cc3}
@deffn {Δεδομένα} cmath.pi

The mathematical constant `π', as a float.
@end deffn

@geindex e (στη μονάδα cmath)
@anchor{library/cmath cmath e}@anchor{2cc4}
@deffn {Δεδομένα} cmath.e

The mathematical constant `e', as a float.
@end deffn

@geindex tau (στη μονάδα cmath)
@anchor{library/cmath cmath tau}@anchor{1040}
@deffn {Δεδομένα} cmath.tau

The mathematical constant `τ', as a float.


Added in version 3.6.

@end deffn

@geindex inf (στη μονάδα cmath)
@anchor{library/cmath cmath inf}@anchor{1041}
@deffn {Δεδομένα} cmath.inf

Floating-point positive infinity. Equivalent to @code{float('inf')}.


Added in version 3.6.

@end deffn

@geindex infj (στη μονάδα cmath)
@anchor{library/cmath cmath infj}@anchor{1044}
@deffn {Δεδομένα} cmath.infj

Complex number with zero real part and positive infinity imaginary
part. Equivalent to @code{complex(0.0, float('inf'))}.


Added in version 3.6.

@end deffn

@geindex nan (στη μονάδα cmath)
@anchor{library/cmath cmath nan}@anchor{1042}
@deffn {Δεδομένα} cmath.nan

A floating-point «not a number» (NaN) value.  Equivalent to
@code{float('nan')}. See also @ref{a53,,math.nan}.


Added in version 3.6.

@end deffn

@geindex nanj (στη μονάδα cmath)
@anchor{library/cmath cmath nanj}@anchor{1045}
@deffn {Δεδομένα} cmath.nanj

Complex number with zero real part and NaN imaginary part. Equivalent to
@code{complex(0.0, float('nan'))}.


Added in version 3.6.

@end deffn

@geindex module;math

Note that the selection of functions is similar, but not identical, to that in
module @ref{91,,math}.  The reason for having two modules is that some users aren’t
interested in complex numbers, and perhaps don’t even know what they are.  They
would rather have @code{math.sqrt(-1)} raise an exception than return a complex
number. Also note that the functions defined in @code{cmath} always return a
complex number, even if the answer can be expressed as a real number (in which
case the complex number has an imaginary part of zero).

A note on branch cuts: They are curves along which the given function fails to
be continuous.  They are a necessary feature of many complex functions.  It is
assumed that if you need to compute with complex functions, you will understand
about branch cuts.  Consult almost any (not too elementary) book on complex
variables for enlightenment.  For information of the proper choice of branch
cuts for numerical purposes, a good reference should be the following:


@subsubheading Δείτε επίσης


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.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node decimal — Decimal fixed-point and floating-point arithmetic,fractions — Rational numbers,cmath — Mathematical functions for complex numbers,Αριθμητικά και Μαθηματικά Modules
@anchor{library/decimal doc}@anchor{2ccb}@anchor{library/decimal decimal-decimal-fixed-point-and-floating-point-arithmetic}@anchor{2ccc}@anchor{library/decimal module-decimal}@anchor{39}@anchor{library/decimal translation-repo}@anchor{2ccd}
@subsection @code{decimal} — Decimal fixed-point and floating-point arithmetic


@geindex module; decimal

`Source code:' Lib/decimal.py@footnote{https://github.com/python/cpython/tree/main/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 @code{decimal} module provides support for fast correctly rounded
decimal floating-point arithmetic. It offers several advantages over the
@ref{327,,float} datatype:


@itemize *

@item 
Decimal «is based on a floating-point model@footnote{https://speleotrove.com/decimal/damodel.html#refnumber} which was designed
with people in mind, and necessarily has a paramount guiding principle –
computers must provide an arithmetic that works in the same way as the
arithmetic that people learn at school.» – excerpt from the decimal
arithmetic specification.

@item 
Decimal numbers can be represented exactly.  In contrast, numbers like
@code{1.1} and @code{2.2} do not have exact representations in binary
floating point. End users typically would not expect @code{1.1 + 2.2} to display
as @code{3.3000000000000003} as it does with binary floating point.

@item 
The exactness carries over into arithmetic.  In decimal floating point, @code{0.1
+ 0.1 + 0.1 - 0.3} is exactly equal to zero.  In binary floating point, the result
is @code{5.5511151231257827e-017}.  While near to zero, the differences
prevent reliable equality testing and differences can accumulate. For this
reason, decimal is preferred in accounting applications which have strict
equality invariants.

@item 
The decimal module incorporates a notion of significant places so that @code{1.30
+ 1.20} is @code{2.50}.  The trailing zero is kept to indicate significance.
This is the customary presentation for monetary applications. For
multiplication, the «schoolbook» approach uses all the figures in the
multiplicands.  For instance, @code{1.3 * 1.2} gives @code{1.56} while @code{1.30 *
1.20} gives @code{1.5600}.

@item 
Unlike hardware based binary floating point, the decimal module has a user
alterable precision (defaulting to 28 places) which can be as large as needed for
a given problem:

@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 
Both binary and decimal floating point are implemented in terms of published
standards.  While the built-in float type exposes only a modest portion of its
capabilities, the decimal module exposes all required parts of the standard.
When needed, the programmer has full control over rounding and signal handling.
This includes an option to enforce exact arithmetic by using exceptions
to block any inexact operations.

@item 
The decimal module was designed to support «without prejudice, both exact
unrounded decimal arithmetic (sometimes called fixed-point arithmetic)
and rounded floating-point arithmetic.»  – excerpt from the decimal
arithmetic specification.
@end itemize

The module design is centered around three concepts:  the decimal number, the
context for arithmetic, and signals.

A decimal number is immutable.  It has a sign, coefficient digits, and an
exponent.  To preserve significance, the coefficient digits do not truncate
trailing zeros.  Decimals also include special values such as
@code{Infinity}, @code{-Infinity}, and @code{NaN}.  The standard also
differentiates @code{-0} from @code{+0}.

The context for arithmetic is an environment specifying precision, rounding
rules, limits on exponents, flags indicating the results of operations, and trap
enablers which determine whether signals are treated as exceptions.  Rounding
options include @ref{2cce,,ROUND_CEILING}, @ref{2ccf,,ROUND_DOWN},
@ref{2cd0,,ROUND_FLOOR}, @ref{2cd1,,ROUND_HALF_DOWN}, @ref{2cd2,,ROUND_HALF_EVEN},
@ref{2cd3,,ROUND_HALF_UP}, @ref{2cd4,,ROUND_UP}, and @ref{2cd5,,ROUND_05UP}.

Signals are groups of exceptional conditions arising during the course of
computation.  Depending on the needs of the application, signals may be ignored,
considered as informational, or treated as exceptions. The signals in the
decimal module are: @ref{2cd6,,Clamped}, @ref{1455,,InvalidOperation},
@ref{2cd7,,DivisionByZero}, @ref{2cd8,,Inexact}, @ref{2cd9,,Rounded}, @ref{2cda,,Subnormal},
@ref{2cdb,,Overflow}, @ref{2cdc,,Underflow} and @ref{144a,,FloatOperation}.

For each signal there is a flag and a trap enabler.  When a signal is
encountered, its flag is set to one, then, if the trap enabler is
set to one, an exception is raised.  Flags are sticky, so the user needs to
reset them before monitoring a calculation.


@subsubheading Δείτε επίσης



@itemize *

@item 
IBM’s General Decimal Arithmetic Specification, The General Decimal Arithmetic Specification@footnote{https://speleotrove.com/decimal/decarith.html}.
@end itemize


@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@menu
* Quick-start tutorial:: 
* Decimal objects:: 
* Context objects:: 
* Constants: Constants<4>. 
* Rounding modes:: 
* Signals:: 
* Floating-point notes:: 
* Working with threads:: 
* Recipes:: 
* Decimal FAQ:: 

@end menu

@node Quick-start tutorial,Decimal objects,,decimal — Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-tutorial}@anchor{2cdd}@anchor{library/decimal quick-start-tutorial}@anchor{2cde}
@subsubsection Quick-start tutorial


The usual start to using decimals is importing the module, viewing the current
context with @ref{1b51,,getcontext()} and, if necessary, setting new values for
precision, rounding, or enabled traps:

@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

Decimal instances can be constructed from integers, strings, floats, or tuples.
Construction from an integer or a float performs an exact conversion of the
value of that integer or float.  Decimal numbers include special values such as
@code{NaN} which stands for «Not a number», positive and negative
@code{Infinity}, and @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

If the @ref{144a,,FloatOperation} signal is trapped, accidental mixing of
decimals and floats in constructors or ordering comparisons raises
an 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


Added in version 3.3.


The significance of a new Decimal is determined solely by the number of digits
input.  Context precision and rounding only come into play during arithmetic
operations.

@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

If the internal limits of the C version are exceeded, constructing
a decimal raises @ref{1455,,InvalidOperation}:

@example
>>> Decimal("1e9999999999999999999")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
decimal.InvalidOperation: [<class 'decimal.InvalidOperation'>]
@end example


Άλλαξε στην έκδοση 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

Decimals can be formatted (with @ref{439,,format()} built-in or @ref{43a,,f-strings}) in
fixed-point or scientific notation, using the same formatting syntax (see
@ref{6fe,,Format specification mini-language}) as builtin @ref{327,,float} type:

@example
>>> format(Decimal('2.675'), "f")
'2.675'
>>> format(Decimal('2.675'), ".2f")
'2.68'
>>> f"@{Decimal('2.675'):.2f@}"
'2.68'
>>> format(Decimal('2.675'), ".2e")
'2.68e+0'
>>> with localcontext() as ctx:
...     ctx.rounding = ROUND_DOWN
...     print(format(Decimal('2.675'), ".2f"))
...
2.67
@end example

And some mathematical functions are also available to 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

The @ref{145d,,quantize()} method rounds a number to a fixed exponent.  This method is
useful for monetary applications that often round results to a fixed number of
places:

@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

As shown above, the @ref{1b51,,getcontext()} function accesses the current context and
allows the settings to be changed.  This approach meets the needs of most
applications.

For more advanced work, it may be useful to create alternate contexts using the
@ref{145c,,Context()} constructor.  To make an alternate active, use the @ref{2cdf,,setcontext()}
function.

In accordance with the standard, the @code{decimal} module provides two ready to
use standard contexts, @ref{1451,,BasicContext} and @ref{1452,,ExtendedContext}. The
former is especially useful for debugging because many of the traps are
enabled:

@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

Contexts also have signal flags for monitoring exceptional conditions
encountered during computations.  The flags remain set until explicitly cleared,
so it is best to clear the flags before each set of monitored computations by
using the @ref{2ce0,,clear_flags()} method.

@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

The `flags' entry shows that the rational approximation to pi was
rounded (digits beyond the context precision were thrown away) and that the
result is inexact (some of the discarded digits were non-zero).

Individual traps are set using the dictionary in the @ref{145b,,traps}
attribute of a context:

@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

Most programs adjust the current context only once, at the beginning of the
program.  And, in many applications, data is converted to @ref{1c2,,Decimal} with
a single cast inside a loop.  With context set and decimals created, the bulk of
the program manipulates the data no differently than with other Python numeric
types.

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Decimal objects,Context objects,Quick-start tutorial,decimal — Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-decimal}@anchor{2ce1}@anchor{library/decimal decimal-objects}@anchor{2ce2}
@subsubsection Decimal objects


@geindex Decimal (κλάση σε decimal)
@anchor{library/decimal decimal Decimal}@anchor{1c2}
@deffn {Κλάση} decimal.Decimal (value='0', context=None)

Construct a new @code{Decimal} object based from `value'.

`value' can be an integer, string, tuple, @ref{327,,float}, or another @code{Decimal}
object. If no `value' is given, returns @code{Decimal('0')}.  If `value' is a
string, it should conform to the decimal numeric string syntax after leading
and trailing whitespace characters, as well as underscores throughout, are removed:

@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

Other Unicode decimal digits are also permitted where @code{digit}
appears above.  These include decimal digits from various other
alphabets (for example, Arabic-Indic and Devanāgarī digits) along
with the fullwidth digits @code{'\uff10'} through @code{'\uff19'}.
Case is not significant, so, for example, @code{inf}, @code{Inf}, @code{INFINITY},
and @code{iNfINity} are all acceptable spellings for positive infinity.

If `value' is a @ref{1ce,,tuple}, it should have three components, a sign
(@code{0} for positive or @code{1} for negative), a @code{tuple} of
digits, and an integer exponent. For example, @code{Decimal((0, (1, 4, 1, 4), -3))}
returns @code{Decimal('1.414')}.

If `value' is a @ref{327,,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')}.

The `context' precision does not affect how many digits are stored. That is
determined exclusively by the number of digits in `value'. For example,
@code{Decimal('3.00000')} records all five zeros even if the context precision is
only three.

The purpose of the `context' argument is determining what to do if `value' is a
malformed string.  If the context traps @ref{1455,,InvalidOperation}, an exception
is raised; otherwise, the constructor returns a new Decimal with the value of
@code{NaN}.

Once constructed, @code{Decimal} objects are immutable.


Άλλαξε στην έκδοση 3.2: The argument to the constructor is now permitted to be a @ref{327,,float}
instance.



Άλλαξε στην έκδοση 3.3: @ref{327,,float} arguments raise an exception if the @ref{144a,,FloatOperation}
trap is set. By default the trap is off.



Άλλαξε στην έκδοση 3.6: Underscores are allowed for grouping, as with integral and floating-point
literals in code.


Decimal floating-point objects share many properties with the other built-in
numeric types such as @ref{327,,float} and @ref{326,,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 @code{float} or
@code{int}).

There are some small differences between arithmetic on Decimal objects and
arithmetic on integers and floats.  When the remainder operator @code{%} is
applied to Decimal objects, the sign of the result is the sign of the
`dividend' rather than the sign of the divisor:

@example
>>> (-7) % 4
1
>>> Decimal(-7) % Decimal(4)
Decimal('-3')
@end example

The integer division operator @code{//} behaves analogously, returning the
integer part of the true quotient (truncating towards zero) rather than its
floor, so as to preserve the usual identity @code{x == (x // y) * y + x % y}:

@example
>>> -7 // 4
-2
>>> Decimal(-7) // Decimal(4)
Decimal('-1')
@end example

The @code{%} and @code{//} operators implement the @code{remainder} and
@code{divide-integer} operations (respectively) as described in the
specification.

Decimal objects cannot generally be combined with floats or
instances of @ref{1c3,,fractions.Fraction} in arithmetic operations:
an attempt to add a @code{Decimal} to a @ref{327,,float}, for
example, will raise a @ref{291,,TypeError}.  However, it is possible to
use Python’s comparison operators to compare a @code{Decimal}
instance @code{x} with another number @code{y}.  This avoids confusing results
when doing equality comparisons between numbers of different types.


Άλλαξε στην έκδοση 3.2: Mixed-type comparisons between @code{Decimal} instances and other
numeric types are now fully supported.


In addition to the standard numeric properties, decimal floating-point
objects also have a number of specialized methods:

@geindex adjusted() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal adjusted}@anchor{2ce3}
@deffn {Μέθοδος} adjusted ()

Return the adjusted exponent after shifting out the coefficient’s
rightmost digits until only the lead digit remains:
@code{Decimal('321e+5').adjusted()} returns seven.  Used for determining the
position of the most significant digit with respect to the decimal point.
@end deffn

@geindex as_integer_ratio() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal as_integer_ratio}@anchor{1055}
@deffn {Μέθοδος} as_integer_ratio ()

Return a pair @code{(n, d)} of integers that represent the given
@code{Decimal} instance as a fraction, in lowest terms and
with a positive denominator:

@example
>>> Decimal('-3.14').as_integer_ratio()
(-157, 50)
@end example

The conversion is exact.  Raise OverflowError on infinities and ValueError
on NaNs.
@end deffn


Added in version 3.6.


@geindex as_tuple() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal as_tuple}@anchor{2ce4}
@deffn {Μέθοδος} as_tuple ()

Return a @ref{a3d,,named tuple} representation of the number:
@code{DecimalTuple(sign, digits, exponent)}.
@end deffn

@geindex canonical() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal canonical}@anchor{2ce5}
@deffn {Μέθοδος} canonical ()

Return the canonical encoding of the argument.  Currently, the encoding of
a @code{Decimal} instance is always canonical, so this operation returns
its argument unchanged.
@end deffn

@geindex compare() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal compare}@anchor{2ce6}
@deffn {Μέθοδος} compare (other, context=None)

Compare the values of two Decimal instances.  @code{compare()} returns a
Decimal instance, and if either operand is a NaN then the result is a
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() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal compare_signal}@anchor{2ce7}
@deffn {Μέθοδος} compare_signal (other, context=None)

This operation is identical to the @ref{2ce6,,compare()} method, except that all
NaNs signal.  That is, if neither operand is a signaling NaN then any
quiet NaN operand is treated as though it were a signaling NaN.
@end deffn

@geindex compare_total() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal compare_total}@anchor{2ce8}
@deffn {Μέθοδος} compare_total (other, context=None)

Compare two operands using their abstract representation rather than their
numerical value.  Similar to the @ref{2ce6,,compare()} method, but the result
gives a total ordering on @code{Decimal} instances.  Two
@code{Decimal} instances with the same numeric value but different
representations compare unequal in this ordering:

@example
>>> Decimal('12.0').compare_total(Decimal('12'))
Decimal('-1')
@end example

Quiet and signaling NaNs are also included in the total ordering.  The
result of this function is @code{Decimal('0')} if both operands have the same
representation, @code{Decimal('-1')} if the first operand is lower in the
total order than the second, and @code{Decimal('1')} if the first operand is
higher in the total order than the second operand.  See the specification
for details of the total order.

This operation is unaffected by context and is quiet: no flags are changed
and no rounding is performed.  As an exception, the C version may raise
InvalidOperation if the second operand cannot be converted exactly.
@end deffn

@geindex compare_total_mag() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal compare_total_mag}@anchor{2ce9}
@deffn {Μέθοδος} compare_total_mag (other, context=None)

Compare two operands using their abstract representation rather than their
value as in @ref{2ce8,,compare_total()}, but ignoring the sign of each operand.
@code{x.compare_total_mag(y)} is equivalent to
@code{x.copy_abs().compare_total(y.copy_abs())}.

This operation is unaffected by context and is quiet: no flags are changed
and no rounding is performed.  As an exception, the C version may raise
InvalidOperation if the second operand cannot be converted exactly.
@end deffn

@geindex conjugate() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal conjugate}@anchor{2cea}
@deffn {Μέθοδος} conjugate ()

Just returns self, this method is only to comply with the Decimal
Specification.
@end deffn

@geindex copy_abs() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal copy_abs}@anchor{2ceb}
@deffn {Μέθοδος} copy_abs ()

Return the absolute value of the argument.  This operation is unaffected
by the context and is quiet: no flags are changed and no rounding is
performed.
@end deffn

@geindex copy_negate() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal copy_negate}@anchor{2cec}
@deffn {Μέθοδος} copy_negate ()

Return the negation of the argument.  This operation is unaffected by the
context and is quiet: no flags are changed and no rounding is performed.
@end deffn

@geindex copy_sign() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal copy_sign}@anchor{2ced}
@deffn {Μέθοδος} copy_sign (other, context=None)

Return a copy of the first operand with the sign set to be the same as the
sign of the second operand.  For example:

@example
>>> Decimal('2.3').copy_sign(Decimal('-1.5'))
Decimal('-2.3')
@end example

This operation is unaffected by context and is quiet: no flags are changed
and no rounding is performed.  As an exception, the C version may raise
InvalidOperation if the second operand cannot be converted exactly.
@end deffn

@geindex exp() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal exp}@anchor{1457}
@deffn {Μέθοδος} exp (context=None)

Return the value of the (natural) exponential function @code{e**x} at the
given number.  The result is correctly rounded using the
@ref{2cd2,,ROUND_HALF_EVEN} rounding mode.

@example
>>> Decimal(1).exp()
Decimal('2.718281828459045235360287471')
>>> Decimal(321).exp()
Decimal('2.561702493119680037517373933E+139')
@end example
@end deffn

@geindex from_float() (μέθοδος κλάσης της decimal.Decimal)
@anchor{library/decimal decimal Decimal from_float}@anchor{15ab}
@deffn {Μέθοδος} classmethod from_float (f, /)

Alternative constructor that only accepts instances of @ref{327,,float} or
@ref{326,,int}.

Note @code{Decimal.from_float(0.1)} is not the same as @code{Decimal('0.1')}.
Since 0.1 is not exactly representable in binary floating point, the
value is stored as the nearest representable value which is
@code{0x1.999999999999ap-4}.  That equivalent value in decimal is
@code{0.1000000000000000055511151231257827021181583404541015625}.

@cartouche
@quotation Σημείωση 
From Python 3.2 onwards, a @code{Decimal} instance
can also be constructed directly from a @ref{327,,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


Added in version 3.1.

@end deffn

@geindex from_number() (μέθοδος κλάσης της decimal.Decimal)
@anchor{library/decimal decimal Decimal from_number}@anchor{490}
@deffn {Μέθοδος} classmethod from_number (number, /)

Alternative constructor that only accepts instances of
@ref{327,,float}, @ref{326,,int} or @code{Decimal}, but not strings
or tuples.

@example
>>> Decimal.from_number(314)
Decimal('314')
>>> Decimal.from_number(0.1)
Decimal('0.1000000000000000055511151231257827021181583404541015625')
>>> Decimal.from_number(Decimal('3.14'))
Decimal('3.14')
@end example


Added in version 3.14.

@end deffn

@geindex fma() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal fma}@anchor{2cee}
@deffn {Μέθοδος} fma (other, third, context=None)

Fused multiply-add.  Return self*other+third with no rounding of the
intermediate product self*other.

@example
>>> Decimal(2).fma(3, 5)
Decimal('11')
@end example
@end deffn

@geindex is_canonical() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal is_canonical}@anchor{2cef}
@deffn {Μέθοδος} is_canonical ()

Return @ref{fcc,,True} if the argument is canonical and @ref{ef5,,False}
otherwise.  Currently, a @code{Decimal} instance is always canonical, so
this operation always returns @code{True}.
@end deffn

@geindex is_finite() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal is_finite}@anchor{2cf0}
@deffn {Μέθοδος} is_finite ()

Return @ref{fcc,,True} if the argument is a finite number, and
@ref{ef5,,False} if the argument is an infinity or a NaN.
@end deffn

@geindex is_infinite() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal is_infinite}@anchor{2cf1}
@deffn {Μέθοδος} is_infinite ()

Return @ref{fcc,,True} if the argument is either positive or negative
infinity and @ref{ef5,,False} otherwise.
@end deffn

@geindex is_nan() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal is_nan}@anchor{2cf2}
@deffn {Μέθοδος} is_nan ()

Return @ref{fcc,,True} if the argument is a (quiet or signaling) NaN and
@ref{ef5,,False} otherwise.
@end deffn

@geindex is_normal() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal is_normal}@anchor{2cf3}
@deffn {Μέθοδος} is_normal (context=None)

Return @ref{fcc,,True} if the argument is a `normal' finite number.  Return
@ref{ef5,,False} if the argument is zero, subnormal, infinite or a NaN.
@end deffn

@geindex is_qnan() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal is_qnan}@anchor{2cf4}
@deffn {Μέθοδος} is_qnan ()

Return @ref{fcc,,True} if the argument is a quiet NaN, and
@ref{ef5,,False} otherwise.
@end deffn

@geindex is_signed() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal is_signed}@anchor{2cf5}
@deffn {Μέθοδος} is_signed ()

Return @ref{fcc,,True} if the argument has a negative sign and
@ref{ef5,,False} otherwise.  Note that zeros and NaNs can both carry signs.
@end deffn

@geindex is_snan() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal is_snan}@anchor{2cf6}
@deffn {Μέθοδος} is_snan ()

Return @ref{fcc,,True} if the argument is a signaling NaN and @ref{ef5,,False}
otherwise.
@end deffn

@geindex is_subnormal() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal is_subnormal}@anchor{2cf7}
@deffn {Μέθοδος} is_subnormal (context=None)

Return @ref{fcc,,True} if the argument is subnormal, and @ref{ef5,,False}
otherwise.
@end deffn

@geindex is_zero() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal is_zero}@anchor{2cf8}
@deffn {Μέθοδος} is_zero ()

Return @ref{fcc,,True} if the argument is a (positive or negative) zero and
@ref{ef5,,False} otherwise.
@end deffn

@geindex ln() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal ln}@anchor{1458}
@deffn {Μέθοδος} ln (context=None)

Return the natural (base e) logarithm of the operand.  The result is
correctly rounded using the @ref{2cd2,,ROUND_HALF_EVEN} rounding mode.
@end deffn

@geindex log10() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal log10}@anchor{2cf9}
@deffn {Μέθοδος} log10 (context=None)

Return the base ten logarithm of the operand.  The result is correctly
rounded using the @ref{2cd2,,ROUND_HALF_EVEN} rounding mode.
@end deffn

@geindex logb() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal logb}@anchor{2cfa}
@deffn {Μέθοδος} logb (context=None)

For a nonzero number, return the adjusted exponent of its operand as a
@code{Decimal} instance.  If the operand is a zero then
@code{Decimal('-Infinity')} is returned and the @ref{2cd7,,DivisionByZero} flag
is raised.  If the operand is an infinity then @code{Decimal('Infinity')} is
returned.
@end deffn

@geindex logical_and() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal logical_and}@anchor{2cfb}
@deffn {Μέθοδος} logical_and (other, context=None)

@code{logical_and()} is a logical operation which takes two `logical
operands' (see @ref{2cfc,,Logical operands}).  The result is the
digit-wise @code{and} of the two operands.
@end deffn

@geindex logical_invert() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal logical_invert}@anchor{2cfd}
@deffn {Μέθοδος} logical_invert (context=None)

@code{logical_invert()} is a logical operation.  The
result is the digit-wise inversion of the operand.
@end deffn

@geindex logical_or() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal logical_or}@anchor{2cfe}
@deffn {Μέθοδος} logical_or (other, context=None)

@code{logical_or()} is a logical operation which takes two `logical
operands' (see @ref{2cfc,,Logical operands}).  The result is the
digit-wise @code{or} of the two operands.
@end deffn

@geindex logical_xor() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal logical_xor}@anchor{2cff}
@deffn {Μέθοδος} logical_xor (other, context=None)

@code{logical_xor()} is a logical operation which takes two `logical
operands' (see @ref{2cfc,,Logical operands}).  The result is the
digit-wise exclusive or of the two operands.
@end deffn

@geindex max() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal max}@anchor{2d00}
@deffn {Μέθοδος} max (other, context=None)

Like @code{max(self, other)} except that the context rounding rule is applied
before returning and that @code{NaN} values are either signaled or
ignored (depending on the context and whether they are signaling or
quiet).
@end deffn

@geindex max_mag() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal max_mag}@anchor{2d01}
@deffn {Μέθοδος} max_mag (other, context=None)

Similar to the @ref{2d00,,max()} method, but the comparison is done using the
absolute values of the operands.
@end deffn

@geindex min() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal min}@anchor{2d02}
@deffn {Μέθοδος} min (other, context=None)

Like @code{min(self, other)} except that the context rounding rule is applied
before returning and that @code{NaN} values are either signaled or
ignored (depending on the context and whether they are signaling or
quiet).
@end deffn

@geindex min_mag() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal min_mag}@anchor{2d03}
@deffn {Μέθοδος} min_mag (other, context=None)

Similar to the @ref{2d02,,min()} method, but the comparison is done using the
absolute values of the operands.
@end deffn

@geindex next_minus() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal next_minus}@anchor{2d04}
@deffn {Μέθοδος} next_minus (context=None)

Return the largest number representable in the given context (or in the
current thread’s context if no context is given) that is smaller than the
given operand.
@end deffn

@geindex next_plus() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal next_plus}@anchor{2d05}
@deffn {Μέθοδος} next_plus (context=None)

Return the smallest number representable in the given context (or in the
current thread’s context if no context is given) that is larger than the
given operand.
@end deffn

@geindex next_toward() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal next_toward}@anchor{2d06}
@deffn {Μέθοδος} next_toward (other, context=None)

If the two operands are unequal, return the number closest to the first
operand in the direction of the second operand.  If both operands are
numerically equal, return a copy of the first operand with the sign set to
be the same as the sign of the second operand.
@end deffn

@geindex normalize() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal normalize}@anchor{2d07}
@deffn {Μέθοδος} normalize (context=None)

Used for producing canonical values of an equivalence
class within either the current context or the specified context.

This has the same semantics as the unary plus operation, except that if
the final result is finite it is reduced to its simplest form, with all
trailing zeros removed and its sign preserved. That is, while the
coefficient is non-zero and a multiple of ten the coefficient is divided
by ten and the exponent is incremented by 1. Otherwise (the coefficient is
zero) the exponent is set to 0. In all cases the sign is unchanged.

For example, @code{Decimal('32.100')} and @code{Decimal('0.321000e+2')} both
normalize to the equivalent value @code{Decimal('32.1')}.

Note that rounding is applied `before' reducing to simplest form.

In the latest versions of the specification, this operation is also known
as @code{reduce}.
@end deffn

@geindex number_class() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal number_class}@anchor{2d08}
@deffn {Μέθοδος} number_class (context=None)

Return a string describing the `class' of the operand.  The returned value
is one of the following ten strings.


@itemize *

@item 
@code{"-Infinity"}, indicating that the operand is negative infinity.

@item 
@code{"-Normal"}, indicating that the operand is a negative normal number.

@item 
@code{"-Subnormal"}, indicating that the operand is negative and subnormal.

@item 
@code{"-Zero"}, indicating that the operand is a negative zero.

@item 
@code{"+Zero"}, indicating that the operand is a positive zero.

@item 
@code{"+Subnormal"}, indicating that the operand is positive and subnormal.

@item 
@code{"+Normal"}, indicating that the operand is a positive normal number.

@item 
@code{"+Infinity"}, indicating that the operand is positive infinity.

@item 
@code{"NaN"}, indicating that the operand is a quiet NaN (Not a Number).

@item 
@code{"sNaN"}, indicating that the operand is a signaling NaN.
@end itemize
@end deffn

@geindex quantize() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal quantize}@anchor{145d}
@deffn {Μέθοδος} quantize (exp, rounding=None, context=None)

Return a value equal to the first operand after rounding and having the
exponent of the second operand.

@example
>>> Decimal('1.41421356').quantize(Decimal('1.000'))
Decimal('1.414')
@end example

Unlike other operations, if the length of the coefficient after the
quantize operation would be greater than precision, then an
@ref{1455,,InvalidOperation} is signaled. This guarantees that, unless there
is an error condition, the quantized exponent is always equal to that of
the right-hand operand.

Also unlike other operations, quantize never signals Underflow, even if
the result is subnormal and inexact.

If the exponent of the second operand is larger than that of the first
then rounding may be necessary.  In this case, the rounding mode is
determined by the @code{rounding} argument if given, else by the given
@code{context} argument; if neither argument is given the rounding mode of
the current thread’s context is used.

An error is returned whenever the resulting exponent is greater than
@ref{1453,,Emax} or less than @ref{2d09,,Etiny()}.
@end deffn

@geindex radix() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal radix}@anchor{2d0a}
@deffn {Μέθοδος} radix ()

Return @code{Decimal(10)}, the radix (base) in which the @code{Decimal}
class does all its arithmetic.  Included for compatibility with the
specification.
@end deffn

@geindex remainder_near() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal remainder_near}@anchor{2d0b}
@deffn {Μέθοδος} remainder_near (other, context=None)

Return the remainder from dividing `self' by `other'.  This differs from
@code{self % other} in that the sign of the remainder is chosen so as to
minimize its absolute value.  More precisely, the return value is
@code{self - n * other} where @code{n} is the integer nearest to the exact
value of @code{self / other}, and if two integers are equally near then the
even one is chosen.

If the result is zero then its sign will be the sign of `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() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal rotate}@anchor{2d0c}
@deffn {Μέθοδος} rotate (other, context=None)

Return the result of rotating the digits of the first operand by an amount
specified by the second operand.  The second operand must be an integer in
the range -precision through precision.  The absolute value of the second
operand gives the number of places to rotate.  If the second operand is
positive then rotation is to the left; otherwise rotation is to the right.
The coefficient of the first operand is padded on the left with zeros to
length precision if necessary.  The sign and exponent of the first operand
are unchanged.
@end deffn

@geindex same_quantum() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal same_quantum}@anchor{2d0d}
@deffn {Μέθοδος} same_quantum (other, context=None)

Test whether self and other have the same exponent or whether both are
@code{NaN}.

This operation is unaffected by context and is quiet: no flags are changed
and no rounding is performed.  As an exception, the C version may raise
InvalidOperation if the second operand cannot be converted exactly.
@end deffn

@geindex scaleb() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal scaleb}@anchor{2d0e}
@deffn {Μέθοδος} scaleb (other, context=None)

Return the first operand with exponent adjusted by the second.
Equivalently, return the first operand multiplied by @code{10**other}.  The
second operand must be an integer.
@end deffn

@geindex shift() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal shift}@anchor{2d0f}
@deffn {Μέθοδος} shift (other, context=None)

Return the result of shifting the digits of the first operand by an amount
specified by the second operand.  The second operand must be an integer in
the range -precision through precision.  The absolute value of the second
operand gives the number of places to shift.  If the second operand is
positive then the shift is to the left; otherwise the shift is to the
right.  Digits shifted into the coefficient are zeros.  The sign and
exponent of the first operand are unchanged.
@end deffn

@geindex sqrt() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal sqrt}@anchor{2d10}
@deffn {Μέθοδος} sqrt (context=None)

Return the square root of the argument to full precision.
@end deffn

@geindex to_eng_string() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal to_eng_string}@anchor{2d11}
@deffn {Μέθοδος} to_eng_string (context=None)

Convert to a string, using engineering notation if an exponent is needed.

Engineering notation has an exponent which is a multiple of 3.  This
can leave up to 3 digits to the left of the decimal place and may
require the addition of either one or two trailing zeros.

For example, this converts @code{Decimal('123E+1')} to @code{Decimal('1.23E+3')}.
@end deffn

@geindex to_integral() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal to_integral}@anchor{2d12}
@deffn {Μέθοδος} to_integral (rounding=None, context=None)

Identical to the @ref{2d13,,to_integral_value()} method.  The @code{to_integral}
name has been kept for compatibility with older versions.
@end deffn

@geindex to_integral_exact() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal to_integral_exact}@anchor{2d14}
@deffn {Μέθοδος} to_integral_exact (rounding=None, context=None)

Round to the nearest integer, signaling @ref{2cd8,,Inexact} or
@ref{2cd9,,Rounded} as appropriate if rounding occurs.  The rounding mode is
determined by the @code{rounding} parameter if given, else by the given
@code{context}.  If neither parameter is given then the rounding mode of the
current context is used.
@end deffn

@geindex to_integral_value() (μέθοδος της decimal.Decimal)
@anchor{library/decimal decimal Decimal to_integral_value}@anchor{2d13}
@deffn {Μέθοδος} to_integral_value (rounding=None, context=None)

Round to the nearest integer without signaling @ref{2cd8,,Inexact} or
@ref{2cd9,,Rounded}.  If given, applies `rounding'; otherwise, uses the
rounding method in either the supplied `context' or the current context.
@end deffn

Decimal numbers can be rounded using the @ref{167f,,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{326,,int} to `number',
rounding ties to even, and ignoring the rounding mode of the
@code{Decimal} context.  Raises @ref{c57,,OverflowError} if `number' is an
infinity or @ref{277,,ValueError} if it is a (quiet or signaling) NaN.

If `ndigits' is an @ref{326,,int}, the context’s rounding mode is respected
and a @code{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{1455,,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

For example:

@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
* Logical operands:: 

@end menu

@node Logical operands,,,Decimal objects
@anchor{library/decimal logical-operands}@anchor{2d15}@anchor{library/decimal logical-operands-label}@anchor{2cfc}
@subsubsection Logical operands


The @ref{2cfb,,logical_and()}, @ref{2cfd,,logical_invert()}, @ref{2cfe,,logical_or()},
and @ref{2cff,,logical_xor()} methods expect their arguments to be `logical
operands'.  A `logical operand' is a @ref{1c2,,Decimal} instance whose
exponent and sign are both zero, and whose digits are all either
@code{0} or @code{1}.

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Context objects,Constants<4>,Decimal objects,decimal — Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal context-objects}@anchor{2d16}@anchor{library/decimal decimal-context}@anchor{2961}
@subsubsection Context objects


Contexts are environments for arithmetic operations.  They govern precision, set
rules for rounding, determine which signals are treated as exceptions, and limit
the range for exponents.

Each thread has its own current context which is accessed or changed using the
@ref{1b51,,getcontext()} and @ref{2cdf,,setcontext()} functions:

@geindex getcontext() (στη μονάδα decimal)
@anchor{library/decimal decimal getcontext}@anchor{1b51}
@deffn {Συνάρτηση} decimal.getcontext ()

Return the current context for the active thread.
@end deffn

@geindex setcontext() (στη μονάδα decimal)
@anchor{library/decimal decimal setcontext}@anchor{2cdf}
@deffn {Συνάρτηση} decimal.setcontext (c, /)

Set the current context for the active thread to `c'.
@end deffn

You can also use the @ref{20a,,with} statement and the @ref{172b,,localcontext()}
function to temporarily change the active context.

@geindex localcontext() (στη μονάδα decimal)
@anchor{library/decimal decimal localcontext}@anchor{172b}
@deffn {Συνάρτηση} decimal.localcontext (ctx=None, **kwargs)

Return a context manager that will set the current context for the active thread
to a copy of `ctx' on entry to the with-statement and restore the previous context
when exiting the with-statement. If no context is specified, a copy of the
current context is used.  The `kwargs' argument is used to set the attributes
of the new context.

For example, the following code sets the current decimal precision to 42 places,
performs a calculation, and then automatically restores the previous context:

@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

Using keyword arguments, the code would be the following:

@example
from decimal import localcontext

with localcontext(prec=42) as ctx:
    s = calculate_something()
s = +s
@end example

Raises @ref{291,,TypeError} if `kwargs' supplies an attribute that @ref{145c,,Context} doesn’t
support.  Raises either @code{TypeError} or @ref{277,,ValueError} if `kwargs' supplies an
invalid value for an attribute.


Άλλαξε στην έκδοση 3.11: @ref{172b,,localcontext()} now supports setting context attributes through the use of keyword arguments.

@end deffn

@geindex IEEEContext() (στη μονάδα decimal)
@anchor{library/decimal decimal IEEEContext}@anchor{491}
@deffn {Συνάρτηση} decimal.IEEEContext (bits)

Return a context object initialized to the proper values for one of the
IEEE interchange formats.  The argument must be a multiple of 32 and less
than @ref{2d17,,IEEE_CONTEXT_MAX_BITS}.


Added in version 3.14.

@end deffn

New contexts can also be created using the @ref{145c,,Context} constructor
described below. In addition, the module provides three pre-made contexts:

@geindex BasicContext (στη μονάδα decimal)
@anchor{library/decimal decimal BasicContext}@anchor{1451}
@deffn {Δεδομένα} decimal.BasicContext

This is a standard context defined by the General Decimal Arithmetic
Specification.  Precision is set to nine.  Rounding is set to
@ref{2cd3,,ROUND_HALF_UP}.  All flags are cleared.  All traps are enabled (treated
as exceptions) except @ref{2cd8,,Inexact}, @ref{2cd9,,Rounded}, and
@ref{2cda,,Subnormal}.

Because many of the traps are enabled, this context is useful for debugging.
@end deffn

@geindex ExtendedContext (στη μονάδα decimal)
@anchor{library/decimal decimal ExtendedContext}@anchor{1452}
@deffn {Δεδομένα} decimal.ExtendedContext

This is a standard context defined by the General Decimal Arithmetic
Specification.  Precision is set to nine.  Rounding is set to
@ref{2cd2,,ROUND_HALF_EVEN}.  All flags are cleared.  No traps are enabled (so that
exceptions are not raised during computations).

Because the traps are disabled, this context is useful for applications that
prefer to have result value of @code{NaN} or @code{Infinity} instead of
raising exceptions.  This allows an application to complete a run in the
presence of conditions that would otherwise halt the program.
@end deffn

@geindex DefaultContext (στη μονάδα decimal)
@anchor{library/decimal decimal DefaultContext}@anchor{1450}
@deffn {Δεδομένα} decimal.DefaultContext

This context is used by the @ref{145c,,Context} constructor as a prototype for new
contexts.  Changing a field (such a precision) has the effect of changing the
default for new contexts created by the @code{Context} constructor.

This context is most useful in multi-threaded environments.  Changing one of the
fields before threads are started has the effect of setting system-wide
defaults.  Changing the fields after threads have started is not recommended as
it would require thread synchronization to prevent race conditions.

In single threaded environments, it is preferable to not use this context at
all.  Instead, simply create contexts explicitly as described below.

The default values are @ref{2d18,,Context.prec}=@code{28},
@ref{2d19,,Context.rounding}=@ref{2cd2,,ROUND_HALF_EVEN},
and enabled traps for @ref{2cdb,,Overflow}, @ref{1455,,InvalidOperation}, and
@ref{2cd7,,DivisionByZero}.
@end deffn

In addition to the three supplied contexts, new contexts can be created with the
@ref{145c,,Context} constructor.

@geindex Context (κλάση σε decimal)
@anchor{library/decimal decimal Context}@anchor{145c}
@deffn {Κλάση} decimal.Context (prec=None, rounding=None, Emin=None, Emax=None, capitals=None, clamp=None, flags=None, traps=None)

Creates a new context.  If a field is not specified or is @ref{a65,,None}, the
default values are copied from the @ref{1450,,DefaultContext}.  If the `flags'
field is not specified or is @code{None}, all flags are cleared.

@geindex prec (ιδιότητα της decimal.Context)
@anchor{library/decimal decimal Context prec}@anchor{2d18}
@deffn {Ιδιότητα} prec

An integer in the range [@code{1}, @ref{144d,,MAX_PREC}] that sets
the precision for arithmetic operations in the context.
@end deffn

@geindex rounding (ιδιότητα της decimal.Context)
@anchor{library/decimal decimal Context rounding}@anchor{2d19}
@deffn {Ιδιότητα} rounding

One of the constants listed in the section @ref{2d1a,,Rounding Modes}.
@end deffn

@geindex traps (ιδιότητα της decimal.Context)
@geindex flags (ιδιότητα της decimal.Context)
@anchor{library/decimal decimal Context traps}@anchor{145b}
@deffn {Ιδιότητα} traps
@anchor{library/decimal decimal Context flags}@anchor{145a}
@deffnx {Ιδιότητα} flags

Lists of any signals to be set. Generally, new contexts should only set
traps and leave the flags clear.
@end deffn

@geindex Emin (ιδιότητα της decimal.Context)
@geindex Emax (ιδιότητα της decimal.Context)
@anchor{library/decimal decimal Context Emin}@anchor{1454}
@deffn {Ιδιότητα} Emin
@anchor{library/decimal decimal Context Emax}@anchor{1453}
@deffnx {Ιδιότητα} Emax

Integers specifying the outer limits allowable for exponents. `Emin' must
be in the range [@ref{144f,,MIN_EMIN}, @code{0}], `Emax' in the range
[@code{0}, @ref{144e,,MAX_EMAX}].
@end deffn

@geindex capitals (ιδιότητα της decimal.Context)
@anchor{library/decimal decimal Context capitals}@anchor{2d1b}
@deffn {Ιδιότητα} capitals

Either @code{0} or @code{1} (the default). If set to
@code{1}, exponents are printed with a capital @code{E}; otherwise, a
lowercase @code{e} is used: @code{Decimal('6.02e+23')}.
@end deffn

@geindex clamp (ιδιότητα της decimal.Context)
@anchor{library/decimal decimal Context clamp}@anchor{1547}
@deffn {Ιδιότητα} clamp

Either @code{0} (the default) or @code{1}.  If set to @code{1}, the exponent @code{e}
of a @ref{1c2,,Decimal} instance representable in this context is strictly
limited to the range @code{Emin - prec + 1 <= e <= Emax - prec + 1}.
If `clamp' is @code{0} then a weaker condition holds: the adjusted exponent of
the @code{Decimal} instance is at most @ref{1453,,Emax}.  When `clamp' is
@code{1}, a large normal number will, where possible, have its
exponent reduced and a corresponding number of zeros added to its
coefficient, in order to fit the exponent constraints; this
preserves the value of the number but loses information about
significant trailing zeros.  For example:

@example
>>> Context(prec=6, Emax=999, clamp=1).create_decimal('1.23e999')
Decimal('1.23000E+999')
@end example

A `clamp' value of @code{1} allows compatibility with the
fixed-width decimal interchange formats specified in IEEE 754.
@end deffn

The @code{Context} class defines several general purpose methods as well as
a large number of methods for doing arithmetic directly in a given context.
In addition, for each of the @ref{1c2,,Decimal} methods described above (with
the exception of the @ref{2ce3,,adjusted()} and @ref{2ce4,,as_tuple()} methods) there is
a corresponding @code{Context} method.  For example, for a @code{Context}
instance @code{C} and @code{Decimal} instance @code{x}, @code{C.exp(x)} is
equivalent to @code{x.exp(context=C)}.  Each @code{Context} method accepts a
Python integer (an instance of @ref{326,,int}) anywhere that a
Decimal instance is accepted.

@geindex clear_flags() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context clear_flags}@anchor{2ce0}
@deffn {Μέθοδος} clear_flags ()

Resets all of the flags to @code{0}.
@end deffn

@geindex clear_traps() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context clear_traps}@anchor{2d1c}
@deffn {Μέθοδος} clear_traps ()

Resets all of the traps to @code{0}.


Added in version 3.3.

@end deffn

@geindex copy() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context copy}@anchor{2d1d}
@deffn {Μέθοδος} copy ()

Return a duplicate of the context.
@end deffn

@geindex copy_decimal() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context copy_decimal}@anchor{2d1e}
@deffn {Μέθοδος} copy_decimal (num, /)

Return a copy of the Decimal instance num.
@end deffn

@geindex create_decimal() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context create_decimal}@anchor{1456}
@deffn {Μέθοδος} create_decimal (num='0', /)

Creates a new Decimal instance from `num' but using `self' as
context. Unlike the @ref{1c2,,Decimal} constructor, the context precision,
rounding method, flags, and traps are applied to the conversion.

This is useful because constants are often given to a greater precision
than is needed by the application.  Another benefit is that rounding
immediately eliminates unintended effects from digits beyond the current
precision. In the following example, using unrounded inputs means that
adding zero to a sum can change the result:

@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

This method implements the to-number operation of the IBM specification.
If the argument is a string, no leading or trailing whitespace or
underscores are permitted.
@end deffn

@geindex create_decimal_from_float() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context create_decimal_from_float}@anchor{2d1f}
@deffn {Μέθοδος} create_decimal_from_float (f, /)

Creates a new Decimal instance from a float `f' but rounding using `self'
as the context.  Unlike the @ref{15ab,,Decimal.from_float()} class method,
the context precision, rounding method, flags, and traps are applied to
the 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


Added in version 3.1.

@end deffn

@geindex Etiny() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context Etiny}@anchor{2d09}
@deffn {Μέθοδος} Etiny ()

Returns a value equal to @code{Emin - prec + 1} which is the minimum exponent
value for subnormal results.  When underflow occurs, the exponent is set
to @ref{2d09,,Etiny}.
@end deffn

@geindex Etop() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context Etop}@anchor{2d20}
@deffn {Μέθοδος} Etop ()

Returns a value equal to @code{Emax - prec + 1}.
@end deffn

The usual approach to working with decimals is to create @ref{1c2,,Decimal}
instances and then apply arithmetic operations which take place within the
current context for the active thread.  An alternative approach is to use
context methods for calculating within a specific context.  The methods are
similar to those for the @code{Decimal} class and are only briefly
recounted here.

@geindex abs() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context abs}@anchor{2d21}
@deffn {Μέθοδος} abs (x, /)

Returns the absolute value of `x'.
@end deffn

@geindex add() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context add}@anchor{2d22}
@deffn {Μέθοδος} add (x, y, /)

Return the sum of `x' and `y'.
@end deffn

@geindex canonical() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context canonical}@anchor{16ab}
@deffn {Μέθοδος} canonical (x, /)

Returns the same Decimal object `x'.
@end deffn

@geindex compare() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context compare}@anchor{2d23}
@deffn {Μέθοδος} compare (x, y, /)

Compares `x' and `y' numerically.
@end deffn

@geindex compare_signal() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context compare_signal}@anchor{2d24}
@deffn {Μέθοδος} compare_signal (x, y, /)

Compares the values of the two operands numerically.
@end deffn

@geindex compare_total() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context compare_total}@anchor{2d25}
@deffn {Μέθοδος} compare_total (x, y, /)

Compares two operands using their abstract representation.
@end deffn

@geindex compare_total_mag() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context compare_total_mag}@anchor{2d26}
@deffn {Μέθοδος} compare_total_mag (x, y, /)

Compares two operands using their abstract representation, ignoring sign.
@end deffn

@geindex copy_abs() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context copy_abs}@anchor{2d27}
@deffn {Μέθοδος} copy_abs (x, /)

Returns a copy of `x' with the sign set to 0.
@end deffn

@geindex copy_negate() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context copy_negate}@anchor{2d28}
@deffn {Μέθοδος} copy_negate (x, /)

Returns a copy of `x' with the sign inverted.
@end deffn

@geindex copy_sign() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context copy_sign}@anchor{2d29}
@deffn {Μέθοδος} copy_sign (x, y, /)

Copies the sign from `y' to `x'.
@end deffn

@geindex divide() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context divide}@anchor{2d2a}
@deffn {Μέθοδος} divide (x, y, /)

Return `x' divided by `y'.
@end deffn

@geindex divide_int() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context divide_int}@anchor{2d2b}
@deffn {Μέθοδος} divide_int (x, y, /)

Return `x' divided by `y', truncated to an integer.
@end deffn

@geindex divmod() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context divmod}@anchor{2d2c}
@deffn {Μέθοδος} divmod (x, y, /)

Divides two numbers and returns the integer part of the result.
@end deffn

@geindex exp() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context exp}@anchor{2d2d}
@deffn {Μέθοδος} exp (x, /)

Returns @code{e ** x}.
@end deffn

@geindex fma() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context fma}@anchor{2d2e}
@deffn {Μέθοδος} fma (x, y, z, /)

Returns `x' multiplied by `y', plus `z'.
@end deffn

@geindex is_canonical() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context is_canonical}@anchor{16ac}
@deffn {Μέθοδος} is_canonical (x, /)

Returns @code{True} if `x' is canonical; otherwise returns @code{False}.
@end deffn

@geindex is_finite() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context is_finite}@anchor{2d2f}
@deffn {Μέθοδος} is_finite (x, /)

Returns @code{True} if `x' is finite; otherwise returns @code{False}.
@end deffn

@geindex is_infinite() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context is_infinite}@anchor{2d30}
@deffn {Μέθοδος} is_infinite (x, /)

Returns @code{True} if `x' is infinite; otherwise returns @code{False}.
@end deffn

@geindex is_nan() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context is_nan}@anchor{2d31}
@deffn {Μέθοδος} is_nan (x, /)

Returns @code{True} if `x' is a qNaN or sNaN; otherwise returns @code{False}.
@end deffn

@geindex is_normal() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context is_normal}@anchor{2d32}
@deffn {Μέθοδος} is_normal (x, /)

Returns @code{True} if `x' is a normal number; otherwise returns @code{False}.
@end deffn

@geindex is_qnan() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context is_qnan}@anchor{2d33}
@deffn {Μέθοδος} is_qnan (x, /)

Returns @code{True} if `x' is a quiet NaN; otherwise returns @code{False}.
@end deffn

@geindex is_signed() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context is_signed}@anchor{2d34}
@deffn {Μέθοδος} is_signed (x, /)

Returns @code{True} if `x' is negative; otherwise returns @code{False}.
@end deffn

@geindex is_snan() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context is_snan}@anchor{2d35}
@deffn {Μέθοδος} is_snan (x, /)

Returns @code{True} if `x' is a signaling NaN; otherwise returns @code{False}.
@end deffn

@geindex is_subnormal() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context is_subnormal}@anchor{2d36}
@deffn {Μέθοδος} is_subnormal (x, /)

Returns @code{True} if `x' is subnormal; otherwise returns @code{False}.
@end deffn

@geindex is_zero() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context is_zero}@anchor{2d37}
@deffn {Μέθοδος} is_zero (x, /)

Returns @code{True} if `x' is a zero; otherwise returns @code{False}.
@end deffn

@geindex ln() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context ln}@anchor{2d38}
@deffn {Μέθοδος} ln (x, /)

Returns the natural (base e) logarithm of `x'.
@end deffn

@geindex log10() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context log10}@anchor{2d39}
@deffn {Μέθοδος} log10 (x, /)

Returns the base 10 logarithm of `x'.
@end deffn

@geindex logb() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context logb}@anchor{2d3a}
@deffn {Μέθοδος} logb (x, /)

Returns the exponent of the magnitude of the operand’s MSD.
@end deffn

@geindex logical_and() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context logical_and}@anchor{2d3b}
@deffn {Μέθοδος} logical_and (x, y, /)

Applies the logical operation `and' between each operand’s digits.
@end deffn

@geindex logical_invert() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context logical_invert}@anchor{2d3c}
@deffn {Μέθοδος} logical_invert (x, /)

Invert all the digits in `x'.
@end deffn

@geindex logical_or() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context logical_or}@anchor{2d3d}
@deffn {Μέθοδος} logical_or (x, y, /)

Applies the logical operation `or' between each operand’s digits.
@end deffn

@geindex logical_xor() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context logical_xor}@anchor{2d3e}
@deffn {Μέθοδος} logical_xor (x, y, /)

Applies the logical operation `xor' between each operand’s digits.
@end deffn

@geindex max() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context max}@anchor{2d3f}
@deffn {Μέθοδος} max (x, y, /)

Compares two values numerically and returns the maximum.
@end deffn

@geindex max_mag() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context max_mag}@anchor{2d40}
@deffn {Μέθοδος} max_mag (x, y, /)

Compares the values numerically with their sign ignored.
@end deffn

@geindex min() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context min}@anchor{2d41}
@deffn {Μέθοδος} min (x, y, /)

Compares two values numerically and returns the minimum.
@end deffn

@geindex min_mag() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context min_mag}@anchor{2d42}
@deffn {Μέθοδος} min_mag (x, y, /)

Compares the values numerically with their sign ignored.
@end deffn

@geindex minus() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context minus}@anchor{2d43}
@deffn {Μέθοδος} minus (x, /)

Minus corresponds to the unary prefix minus operator in Python.
@end deffn

@geindex multiply() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context multiply}@anchor{2d44}
@deffn {Μέθοδος} multiply (x, y, /)

Return the product of `x' and `y'.
@end deffn

@geindex next_minus() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context next_minus}@anchor{2d45}
@deffn {Μέθοδος} next_minus (x, /)

Returns the largest representable number smaller than `x'.
@end deffn

@geindex next_plus() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context next_plus}@anchor{2d46}
@deffn {Μέθοδος} next_plus (x, /)

Returns the smallest representable number larger than `x'.
@end deffn

@geindex next_toward() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context next_toward}@anchor{2d47}
@deffn {Μέθοδος} next_toward (x, y, /)

Returns the number closest to `x', in direction towards `y'.
@end deffn

@geindex normalize() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context normalize}@anchor{2d48}
@deffn {Μέθοδος} normalize (x, /)

Reduces `x' to its simplest form.
@end deffn

@geindex number_class() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context number_class}@anchor{2d49}
@deffn {Μέθοδος} number_class (x, /)

Returns an indication of the class of `x'.
@end deffn

@geindex plus() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context plus}@anchor{2d4a}
@deffn {Μέθοδος} plus (x, /)

Plus corresponds to the unary prefix plus operator in Python.  This
operation applies the context precision and rounding, so it is `not' an
identity operation.
@end deffn

@geindex power() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context power}@anchor{2d4b}
@deffn {Μέθοδος} power (x, y, modulo=None)

Return @code{x} to the power of @code{y}, reduced modulo @code{modulo} if given.

With two arguments, compute @code{x**y}.  If @code{x} is negative then @code{y}
must be integral.  The result will be inexact unless @code{y} is integral and
the result is finite and can be expressed exactly in “precision” digits.
The rounding mode of the context is used. Results are always correctly rounded
in the Python version.

@code{Decimal(0) ** Decimal(0)} results in @code{InvalidOperation}, and if @code{InvalidOperation}
is not trapped, then results in @code{Decimal('NaN')}.


Άλλαξε στην έκδοση 3.3: The C module computes @code{power()} in terms of the correctly rounded
@ref{2d2d,,exp()} and @ref{2d38,,ln()} functions. The result is well-defined but
only «almost always correctly rounded».


With three arguments, compute @code{(x**y) % modulo}.  For the three argument
form, the following restrictions on the arguments hold:


@itemize -

@item 
all three arguments must be integral

@item 
@code{y} must be nonnegative

@item 
at least one of @code{x} or @code{y} must be nonzero

@item 
@code{modulo} must be nonzero and have at most “precision” digits
@end itemize

The value resulting from @code{Context.power(x, y, modulo)} is
equal to the value that would be obtained by computing @code{(x**y)
% modulo} with unbounded precision, but is computed more
efficiently.  The exponent of the result is zero, regardless of
the exponents of @code{x}, @code{y} and @code{modulo}.  The result is
always exact.
@end deffn

@geindex quantize() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context quantize}@anchor{2d4c}
@deffn {Μέθοδος} quantize (x, y, /)

Returns a value equal to `x' (rounded), having the exponent of `y'.
@end deffn

@geindex radix() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context radix}@anchor{2d4d}
@deffn {Μέθοδος} radix ()

Just returns 10, as this is Decimal, :)
@end deffn

@geindex remainder() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context remainder}@anchor{2d4e}
@deffn {Μέθοδος} remainder (x, y, /)

Returns the remainder from integer division.

The sign of the result, if non-zero, is the same as that of the original
dividend.
@end deffn

@geindex remainder_near() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context remainder_near}@anchor{2d4f}
@deffn {Μέθοδος} remainder_near (x, y, /)

Returns @code{x - y * n}, where `n' is the integer nearest the exact value
of @code{x / y} (if the result is 0 then its sign will be the sign of `x').
@end deffn

@geindex rotate() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context rotate}@anchor{2d50}
@deffn {Μέθοδος} rotate (x, y, /)

Returns a rotated copy of `x', `y' times.
@end deffn

@geindex same_quantum() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context same_quantum}@anchor{2d51}
@deffn {Μέθοδος} same_quantum (x, y, /)

Returns @code{True} if the two operands have the same exponent.
@end deffn

@geindex scaleb() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context scaleb}@anchor{2d52}
@deffn {Μέθοδος} scaleb (x, y, /)

Returns the first operand after adding the second value its exp.
@end deffn

@geindex shift() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context shift}@anchor{2d53}
@deffn {Μέθοδος} shift (x, y, /)

Returns a shifted copy of `x', `y' times.
@end deffn

@geindex sqrt() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context sqrt}@anchor{2d54}
@deffn {Μέθοδος} sqrt (x, /)

Square root of a non-negative number to context precision.
@end deffn

@geindex subtract() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context subtract}@anchor{2d55}
@deffn {Μέθοδος} subtract (x, y, /)

Return the difference between `x' and `y'.
@end deffn

@geindex to_eng_string() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context to_eng_string}@anchor{2d56}
@deffn {Μέθοδος} to_eng_string (x, /)

Convert to a string, using engineering notation if an exponent is needed.

Engineering notation has an exponent which is a multiple of 3.  This
can leave up to 3 digits to the left of the decimal place and may
require the addition of either one or two trailing zeros.
@end deffn

@geindex to_integral_exact() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context to_integral_exact}@anchor{2d57}
@deffn {Μέθοδος} to_integral_exact (x, /)

Rounds to an integer.
@end deffn

@geindex to_sci_string() (μέθοδος της decimal.Context)
@anchor{library/decimal decimal Context to_sci_string}@anchor{2d58}
@deffn {Μέθοδος} to_sci_string (x, /)

Converts a number to a string using scientific notation.
@end deffn
@end deffn

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Constants<4>,Rounding modes,Context objects,decimal — Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal constants}@anchor{2d59}@anchor{library/decimal decimal-rounding-modes}@anchor{2d5a}
@subsubsection Constants


@geindex SPEC_VERSION (στη μονάδα decimal)
@anchor{library/decimal decimal SPEC_VERSION}@anchor{2fd}
@deffn {Δεδομένα} decimal.SPEC_VERSION

The highest version of the General Decimal Arithmetic
Specification that this implementation complies with.
See @indicateurl{https://speleotrove.com/decimal/decarith.html} for the specification.


Added in version 3.15.

@end deffn

The following constants are only relevant for the C module. They
are also included in the pure Python version for compatibility.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@tab

32-bit

@tab

64-bit

@item

@geindex MAX_PREC (στη μονάδα decimal)
@anchor{library/decimal decimal MAX_PREC}@anchor{144d}
@deffn {Δεδομένα} decimal.MAX_PREC
@end deffn

@tab

@code{425000000}

@tab

@code{999999999999999999}

@item

@geindex MAX_EMAX (στη μονάδα decimal)
@anchor{library/decimal decimal MAX_EMAX}@anchor{144e}
@deffn {Δεδομένα} decimal.MAX_EMAX
@end deffn

@tab

@code{425000000}

@tab

@code{999999999999999999}

@item

@geindex MIN_EMIN (στη μονάδα decimal)
@anchor{library/decimal decimal MIN_EMIN}@anchor{144f}
@deffn {Δεδομένα} decimal.MIN_EMIN
@end deffn

@tab

@code{-425000000}

@tab

@code{-999999999999999999}

@item

@geindex MIN_ETINY (στη μονάδα decimal)
@anchor{library/decimal decimal MIN_ETINY}@anchor{2d5b}
@deffn {Δεδομένα} decimal.MIN_ETINY
@end deffn

@tab

@code{-849999999}

@tab

@code{-1999999999999999997}

@item

@geindex IEEE_CONTEXT_MAX_BITS (στη μονάδα decimal)
@anchor{library/decimal decimal IEEE_CONTEXT_MAX_BITS}@anchor{2d17}
@deffn {Δεδομένα} decimal.IEEE_CONTEXT_MAX_BITS
@end deffn

@tab

@code{256}

@tab

@code{512}

@end multitable


@geindex HAVE_THREADS (στη μονάδα decimal)
@anchor{library/decimal decimal HAVE_THREADS}@anchor{144b}
@deffn {Δεδομένα} decimal.HAVE_THREADS

The value is @code{True}.  Deprecated, because Python now always has threads.


Αποσύρθηκε στην έκδοση 3.9.

@end deffn

@geindex HAVE_CONTEXTVAR (στη μονάδα decimal)
@anchor{library/decimal decimal HAVE_CONTEXTVAR}@anchor{2356}
@deffn {Δεδομένα} decimal.HAVE_CONTEXTVAR

The default value is @code{True}. If Python is @ref{2355,,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.


Added in version 3.8.3.

@end deffn

@node Rounding modes,Signals,Constants<4>,decimal — Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal rounding-modes}@anchor{2d1a}
@subsubsection Rounding modes


@geindex ROUND_CEILING (στη μονάδα decimal)
@anchor{library/decimal decimal ROUND_CEILING}@anchor{2cce}
@deffn {Δεδομένα} decimal.ROUND_CEILING

Round towards @code{Infinity}.
@end deffn

@geindex ROUND_DOWN (στη μονάδα decimal)
@anchor{library/decimal decimal ROUND_DOWN}@anchor{2ccf}
@deffn {Δεδομένα} decimal.ROUND_DOWN

Round towards zero.
@end deffn

@geindex ROUND_FLOOR (στη μονάδα decimal)
@anchor{library/decimal decimal ROUND_FLOOR}@anchor{2cd0}
@deffn {Δεδομένα} decimal.ROUND_FLOOR

Round towards @code{-Infinity}.
@end deffn

@geindex ROUND_HALF_DOWN (στη μονάδα decimal)
@anchor{library/decimal decimal ROUND_HALF_DOWN}@anchor{2cd1}
@deffn {Δεδομένα} decimal.ROUND_HALF_DOWN

Round to nearest with ties going towards zero.
@end deffn

@geindex ROUND_HALF_EVEN (στη μονάδα decimal)
@anchor{library/decimal decimal ROUND_HALF_EVEN}@anchor{2cd2}
@deffn {Δεδομένα} decimal.ROUND_HALF_EVEN

Round to nearest with ties going to nearest even integer.
@end deffn

@geindex ROUND_HALF_UP (στη μονάδα decimal)
@anchor{library/decimal decimal ROUND_HALF_UP}@anchor{2cd3}
@deffn {Δεδομένα} decimal.ROUND_HALF_UP

Round to nearest with ties going away from zero.
@end deffn

@geindex ROUND_UP (στη μονάδα decimal)
@anchor{library/decimal decimal ROUND_UP}@anchor{2cd4}
@deffn {Δεδομένα} decimal.ROUND_UP

Round away from zero.
@end deffn

@geindex ROUND_05UP (στη μονάδα decimal)
@anchor{library/decimal decimal ROUND_05UP}@anchor{2cd5}
@deffn {Δεδομένα} 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 Signals,Floating-point notes,Rounding modes,decimal — Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-signals}@anchor{2d5c}@anchor{library/decimal signals}@anchor{2d5d}
@subsubsection Signals


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{2cd7,,DivisionByZero} trap
is set, then a @ref{2cd7,,DivisionByZero} exception is raised upon encountering the
condition.

@geindex Clamped (κλάση σε decimal)
@anchor{library/decimal decimal Clamped}@anchor{2cd6}
@deffn {Κλάση} decimal.Clamped

Altered an exponent to fit representation constraints.

Typically, clamping occurs when an exponent falls outside the context’s
@ref{1454,,Emin} and @ref{1453,,Emax} limits.  If possible, the exponent is reduced to
fit by adding zeros to the coefficient.
@end deffn

@geindex DecimalException (κλάση σε decimal)
@anchor{library/decimal decimal DecimalException}@anchor{2d5e}
@deffn {Κλάση} decimal.DecimalException

Base class for other signals and a subclass of @ref{28e1,,ArithmeticError}.
@end deffn

@geindex DivisionByZero (κλάση σε decimal)
@anchor{library/decimal decimal DivisionByZero}@anchor{2cd7}
@deffn {Κλάση} 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 (κλάση σε decimal)
@anchor{library/decimal decimal Inexact}@anchor{2cd8}
@deffn {Κλάση} 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 (κλάση σε decimal)
@anchor{library/decimal decimal InvalidOperation}@anchor{1455}
@deffn {Κλάση} 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 (κλάση σε decimal)
@anchor{library/decimal decimal Overflow}@anchor{2cdb}
@deffn {Κλάση} decimal.Overflow

Numerical overflow.

Indicates the exponent is larger than @ref{1453,,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{2cd8,,Inexact} and @ref{2cd9,,Rounded}
are also signaled.
@end deffn

@geindex Rounded (κλάση σε decimal)
@anchor{library/decimal decimal Rounded}@anchor{2cd9}
@deffn {Κλάση} 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 (κλάση σε decimal)
@anchor{library/decimal decimal Subnormal}@anchor{2cda}
@deffn {Κλάση} decimal.Subnormal

Exponent was lower than @ref{1454,,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 (κλάση σε decimal)
@anchor{library/decimal decimal Underflow}@anchor{2cdc}
@deffn {Κλάση} decimal.Underflow

Numerical underflow with result rounded to zero.

Occurs when a subnormal result is pushed to zero by rounding. @ref{2cd8,,Inexact}
and @ref{2cda,,Subnormal} are also signaled.
@end deffn

@geindex FloatOperation (κλάση σε decimal)
@anchor{library/decimal decimal FloatOperation}@anchor{144a}
@deffn {Κλάση} 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{1c2,,Decimal} constructor,
@ref{1456,,create_decimal()} and all comparison operators.
Both conversion and comparisons are exact. Any occurrence of a mixed
operation is silently recorded by setting @code{FloatOperation} in the
context flags. Explicit conversions with @ref{15ab,,from_float()}
or @ref{2d1f,,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 @code{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,Signals,decimal — Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-notes}@anchor{2d5f}@anchor{library/decimal floating-point-notes}@anchor{2d60}
@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{2d61}
@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 @code{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{2d62}
@subsubsection Special values


The number system for the @code{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{2cd7,,DivisionByZero} signal is
not trapped.  Likewise, when the @ref{2cdb,,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{1455,,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{ef5,,False} (even when doing
@code{Decimal('NaN')==Decimal('NaN')}), while a test for inequality always returns
@ref{fcc,,True}.  An attempt to compare two Decimals using any of the @code{<},
@code{<=}, @code{>} or @code{>=} operators will raise the @ref{1455,,InvalidOperation} signal
if either operand is a @code{NaN}, and return @code{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{2ce6,,compare()}
and @ref{2ce7,,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,Recipes,Floating-point notes,decimal — Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-threads}@anchor{2d63}@anchor{library/decimal working-with-threads}@anchor{2d64}
@subsubsection Working with threads


The @ref{1b51,,getcontext()} function accesses a different @ref{145c,,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{2cdf,,setcontext()} function automatically assigns its target to
the current thread.

If @ref{2cdf,,setcontext()} has not been called before @ref{1b51,,getcontext()}, then
@code{getcontext()} will automatically create a new context for use in the
current thread.  New context objects have default values set from the
@ref{1450,,decimal.DefaultContext} object.

The @ref{41f,,sys.flags.thread_inherit_context} flag affects the context for
new threads.  If the flag is false, new threads will start with an empty
context.  In this case, @ref{1b51,,getcontext()} will create a new context object
when called and use the default values from `DefaultContext'.  If the flag
is true, new threads will start with a copy of context from the caller of
@ref{422,,threading.Thread.start()}.

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{1b51,,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 Recipes,Decimal FAQ,Working with threads,decimal — Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-recipes}@anchor{2d65}@anchor{library/decimal recipes}@anchor{2d66}
@subsubsection Recipes


Here are a few recipes that serve as utility functions and that demonstrate ways
to work with the @ref{1c2,,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 Decimal FAQ,,Recipes,decimal — Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-faq}@anchor{2d67}@anchor{library/decimal id1}@anchor{2d68}
@subsubsection Decimal FAQ


Q: It is cumbersome to type @code{decimal.Decimal('1234.5')}.  Is there a way to
minimize typing when using the interactive interpreter?

A: Some users abbreviate the constructor to just a single letter:

@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{145d,,quantize()} method rounds to a fixed number of decimal places. If
the @ref{2cd8,,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: Once I have valid two place inputs, how do I maintain that invariant
throughout an application?

A: Some operations like addition, subtraction, and multiplication by an integer
will automatically preserve fixed point.  Others operations, like division and
non-integer multiplication, will change the number of decimal places and need to
be followed-up with a @ref{145d,,quantize()} step:

@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

In developing fixed-point applications, it is convenient to define functions
to handle the @ref{145d,,quantize()} step:

@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{2d07,,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{1c2,,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{1456,,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{

Added in 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. @ref{1454,,Emin}
and @ref{1453,,Emax} should always be set to the maximum values, @ref{1547,,clamp}
should always be 0 (the default).  Setting @ref{2d18,,prec} requires some care.

The easiest approach for trying out bignum arithmetic is to use the maximum
value for @ref{2d18,,prec} as well @footnote{

Άλλαξε στην έκδοση 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{144d,,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 @ref{2d18,,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{2cd8,,Inexact} trap if all calculations
are expected to be exact.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node fractions — Rational numbers,random — Δημιουργία ψευδοτυχαίων αριθμών,decimal — Decimal fixed-point and floating-point arithmetic,Αριθμητικά και Μαθηματικά Modules
@anchor{library/fractions doc}@anchor{2d69}@anchor{library/fractions fractions-rational-numbers}@anchor{2d6a}@anchor{library/fractions module-fractions}@anchor{60}@anchor{library/fractions translation-repo}@anchor{2d6b}
@subsection @code{fractions} — Rational numbers


@geindex module; fractions

`Source code:' Lib/fractions.py@footnote{https://github.com/python/cpython/tree/main/Lib/fractions.py}


__________________________________________________________________


The @code{fractions} module provides support for rational number arithmetic.

A Fraction instance can be constructed from a pair of rational numbers, from
a single number, or from a string.

@geindex as_integer_ratio()

@geindex Fraction (κλάση σε fractions)
@anchor{library/fractions fractions Fraction}@anchor{1c3}
@deffn {Κλάση} fractions.Fraction (numerator=0, denominator=1)

@deffnx {Κλάση} fractions.Fraction (number)

@deffnx {Κλάση} fractions.Fraction (string)

The first version requires that `numerator' and `denominator' are instances
of @ref{1663,,numbers.Rational} and returns a new @code{Fraction} instance
with a value equal to @code{numerator/denominator}.
If `denominator' is zero, it raises a @ref{d11,,ZeroDivisionError}.

The second version requires that `number' is an instance of
@ref{1663,,numbers.Rational} or has the @code{as_integer_ratio()} method
(this includes @ref{327,,float} and @ref{1c2,,decimal.Decimal}).
It returns a @code{Fraction} instance with exactly the same value.
Assumed, that the @code{as_integer_ratio()} method returns a pair
of coprime integers and last one is positive.
Note that due to the
usual issues with binary point (see @ref{22f0,,Αριθμητική Κινητής Υποδιαστολής; Ζητήματα και Περιορισμοί}), 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{2d6c,,limit_denominator()} method below.)

The last version of the constructor expects a string.
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{327,,float} constructor is also
accepted by the @code{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 @code{Fraction} class inherits from the abstract base class
@ref{1663,,numbers.Rational}, and implements all of the methods and
operations from that class.  @code{Fraction} instances are @ref{183,,hashable},
and should be treated as immutable.  In addition,
@code{Fraction} has the following properties and methods:


Άλλαξε στην έκδοση 3.2: The @code{Fraction} constructor now accepts @ref{327,,float} and
@ref{1c2,,decimal.Decimal} instances.



Άλλαξε στην έκδοση 3.9: The @ref{cdf,,math.gcd()} function is now used to normalize the `numerator'
and `denominator'. @code{math.gcd()} always returns an @ref{326,,int} type.
Previously, the GCD type depended on `numerator' and `denominator'.



Άλλαξε στην έκδοση 3.11: Underscores are now permitted when creating a @code{Fraction} instance
from a string, following 
@geindex Python Enhancement Proposals; PEP 515
PEP 515@footnote{https://peps.python.org/pep-0515/} rules.



Άλλαξε στην έκδοση 3.11: @code{Fraction} implements @code{__int__} now to satisfy
@code{typing.SupportsInt} instance checks.



Άλλαξε στην έκδοση 3.12: Space is allowed around the slash for string inputs: @code{Fraction('2 / 3')}.



Άλλαξε στην έκδοση 3.12: @code{Fraction} instances now support float-style formatting, with
presentation types @code{"e"}, @code{"E"}, @code{"f"}, @code{"F"}, @code{"g"}, @code{"G"}
and @code{"%""}.



Άλλαξε στην έκδοση 3.13: Formatting of @code{Fraction} instances without a presentation type
now supports fill, alignment, sign handling, minimum width and grouping.



Άλλαξε στην έκδοση 3.14: The @code{Fraction} constructor now accepts any objects with the
@code{as_integer_ratio()} method.


@geindex numerator (ιδιότητα της fractions.Fraction)
@anchor{library/fractions fractions Fraction numerator}@anchor{2d6d}
@deffn {Ιδιότητα} numerator

Numerator of the Fraction in lowest term.
@end deffn

@geindex denominator (ιδιότητα της fractions.Fraction)
@anchor{library/fractions fractions Fraction denominator}@anchor{2d6e}
@deffn {Ιδιότητα} denominator

Denominator of the Fraction in lowest terms.
Guaranteed to be positive.
@end deffn

@geindex as_integer_ratio() (μέθοδος της fractions.Fraction)
@anchor{library/fractions fractions Fraction as_integer_ratio}@anchor{2d6f}
@deffn {Μέθοδος} 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.


Added in version 3.8.

@end deffn

@geindex is_integer() (μέθοδος της fractions.Fraction)
@anchor{library/fractions fractions Fraction is_integer}@anchor{2d70}
@deffn {Μέθοδος} is_integer ()

Return @code{True} if the Fraction is an integer.


Added in version 3.12.

@end deffn

@geindex from_float() (μέθοδος κλάσης της fractions.Fraction)
@anchor{library/fractions fractions Fraction from_float}@anchor{15ac}
@deffn {Μέθοδος} classmethod from_float (f)

Alternative constructor which only accepts instances of
@ref{327,,float} or @ref{25ff,,numbers.Integral}. Beware that
@code{Fraction.from_float(0.3)} is not the same value as @code{Fraction(3, 10)}.

@cartouche
@quotation Σημείωση 
From Python 3.2 onwards, you can also construct a
@code{Fraction} instance directly from a @ref{327,,float}.
@end quotation
@end cartouche
@end deffn

@geindex from_decimal() (μέθοδος κλάσης της fractions.Fraction)
@anchor{library/fractions fractions Fraction from_decimal}@anchor{15ad}
@deffn {Μέθοδος} classmethod from_decimal (dec)

Alternative constructor which only accepts instances of
@ref{1c2,,decimal.Decimal} or @ref{25ff,,numbers.Integral}.

@cartouche
@quotation Σημείωση 
From Python 3.2 onwards, you can also construct a
@code{Fraction} instance directly from a @ref{1c2,,decimal.Decimal}
instance.
@end quotation
@end cartouche
@end deffn

@geindex from_number() (μέθοδος κλάσης της fractions.Fraction)
@anchor{library/fractions fractions Fraction from_number}@anchor{4a3}
@deffn {Μέθοδος} classmethod from_number (number)

Alternative constructor which only accepts instances of
@ref{25ff,,numbers.Integral}, @ref{1663,,numbers.Rational},
@ref{327,,float} or @ref{1c2,,decimal.Decimal}, and objects with
the @code{as_integer_ratio()} method, but not strings.


Added in version 3.14.

@end deffn

@geindex limit_denominator() (μέθοδος της fractions.Fraction)
@anchor{library/fractions fractions Fraction limit_denominator}@anchor{2d6c}
@deffn {Μέθοδος} limit_denominator (max_denominator=1000000)

Finds and returns the closest @code{Fraction} to @code{self} that has
denominator at most max_denominator.  This method is useful for finding
rational approximations to a given floating-point number:

@example
>>> from fractions import Fraction
>>> Fraction('3.1415926535897932').limit_denominator(1000)
Fraction(355, 113)
@end example

or for recovering a rational number that’s represented as a float:

@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__() (μέθοδος της fractions.Fraction)
@anchor{library/fractions fractions Fraction __floor__}@anchor{1cf6}
@deffn {Μέθοδος} __floor__ ()

Returns the greatest @ref{326,,int} @code{<= self}.  This method can
also be accessed through the @ref{1760,,math.floor()} function:

@example
>>> from math import floor
>>> floor(Fraction(355, 113))
3
@end example
@end deffn

@geindex __ceil__() (μέθοδος της fractions.Fraction)
@anchor{library/fractions fractions Fraction __ceil__}@anchor{1cf5}
@deffn {Μέθοδος} __ceil__ ()

Returns the least @ref{326,,int} @code{>= self}.  This method can
also be accessed through the @ref{1761,,math.ceil()} function.
@end deffn

@geindex __round__() (μέθοδος της fractions.Fraction)
@anchor{library/fractions fractions Fraction __round__}@anchor{1cf4}
@deffn {Μέθοδος} __round__ ()

@deffnx {Μέθοδος} __round__ (ndigits)

The first version returns the nearest @ref{326,,int} to @code{self},
rounding half to even. The second version rounds @code{self} to the
nearest multiple of @code{Fraction(1, 10**ndigits)} (logically, if
@code{ndigits} is negative), again rounding half toward even.  This
method can also be accessed through the @ref{167f,,round()} function.
@end deffn

@geindex __format__() (μέθοδος της fractions.Fraction)
@anchor{library/fractions fractions Fraction __format__}@anchor{2d71}
@deffn {Μέθοδος} __format__ (format_spec, /)

Provides support for formatting of @code{Fraction} instances via the
@ref{a12,,str.format()} method, the @ref{439,,format()} built-in function, or
@ref{43a,,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{6fe,,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{327,,float} type in the @ref{6fe,,Format specification mini-language} section.

Here are some examples:

@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 Δείτε επίσης



@table @asis

@item Module @ref{a2,,numbers}

The abstract base classes making up the numeric tower.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node random — Δημιουργία ψευδοτυχαίων αριθμών,statistics — Mathematical statistics functions,fractions — Rational numbers,Αριθμητικά και Μαθηματικά Modules
@anchor{library/random doc}@anchor{2d72}@anchor{library/random module-random}@anchor{c0}@anchor{library/random random-generate-pseudo-random-numbers}@anchor{2d73}@anchor{library/random translation-repo}@anchor{2d74}
@subsection @code{random} — Δημιουργία ψευδοτυχαίων αριθμών


@geindex module; random

`Πηγαίος κώδικας:' Lib/random.py@footnote{https://github.com/python/cpython/tree/main/Lib/random.py}


__________________________________________________________________


Αυτό το module υλοποιεί ψευδοτυχαίες γεννήτριες αριθμών για διάφορες κατανομές.

Για ακέραιους, υπάρχει ομοιόμορφη επιλογή από ένα εύρος. Για ακολουθίες, υπάρχει ομοιόμορφη επιλογή ενός τυχαίου στοιχείου, μια συνάρτηση για την δημιουργία μιας τυχαίας παραλλαγής μιας λίστας στη θέση της, και μια συνάρτηση για τυχαία δειγματοληψία χωρίς αντικατάσταση.

Στην πραγματική γραμμή, υπάρχουν συναρτήσεις για τον υπολογισμό ομοιόμορφων, κανονικών (Gaussian), lognormal, αρνητικών εκθετικών, gamma και beta κατανομών. Για τη δημιουργία κατανομών γωνιών, διατίθεται η κατανομή von Mises.

Σχεδόν όλες οι συναρτήσεις του module εξαρτώνται από τη βασική συνάρτηση @ref{b2d,,random()}, η οποία παράγει έναν τυχαίο float ομοιόμορφα στο ημι-ανοιχτό εύρος @code{0.0 <= X < 1.0}. Η Python χρησιμοποιεί το Mersenne Twister ως βασική γεννήτρια. Παράγει floats με ακρίβεια 53-bit και έχει περίοδο 2**19937-1. Η υποκείμενη υλοποίηση σε C είναι τόσο γρήγορη όσο και ασφαλής για νήματα. Το Mersenne Twister είναι μια από τις πιο εκτενώς δοκιμασμένες γεννήτριες τυχαίων αριθμών που υπάρχουν. Ωστόσο, είναι εντελώς ντετερμινιστική, δεν είναι κατάλληλη για όλους τους σκοπούς και είναι εντελώς ακατάλληλη για κρυπτογραφικούς σκοπούς.

Οι συναρτήσεις που παρέχονται από αυτό το module είναι στην πραγματικότητα δεσμευμένες μέθοδοι ενός κρυφού στιγμιοτύπου της κλάσης @ref{1e53,,random.Random}. Μπορείτε να δημιουργήσετε τα δικά σας στιγμιότυπα της @ref{1e53,,Random} για να λάβετε γεννήτριες που δεν μοιράζονται κατάσταση.

Η κλάση @ref{1e53,,Random} μπορεί επίσης να υποκλαστεί αν θέλετε να χρησιμοποιήσετε μια διαφορετική βασική γεννήτρια της δικής σας επινόησης: δείτε την τεκμηρίωση για αυτή την κλάση για περισσότερες λεπτομέρειες.

The @code{random} module also provides the @ref{2d75,,SystemRandom} class which
uses the system function @ref{931,,os.urandom()} to generate random numbers
from sources provided by the operating system.

@cartouche
@quotation Προειδοποίηση 
Οι ψευδοτυχαίες γεννήτριες αυτού του module δεν πρέπει να χρησιμοποιούνται για σκοπούς ασφαλείας. Για ασφαλείς ή κρυπτογραφικούς σκοπούς, δείτε το module @ref{c8,,secrets}.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης


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, January pp.3–30 1998.

Complementary-Multiply-with-Carry recipe@footnote{https://code.activestate.com/recipes/576707-long-period-random-number-generator/} για μια συμβατή εναλλακτική γεννήτρια τυχαίων αριθμών με μεγάλη περίοδο και συγκριτικά απλές λειτουργίες ενημέρωσης.


@cartouche
@quotation Σημείωση 
Η παγκόσμια γεννήτρια τυχαίων αριθμών και τα στιγμιότυπα της κλάσης @ref{1e53,,Random} είναι ασφαλή για νήματα. Ωστόσο, στην ελεύθερη κατασκευή νημάτων, οι ταυτόχρονες κλήσεις στην παγκόσμια γεννήτρια ή στο ίδιο στιγμιότυπο της κλάσης @code{Random} μπορεί να συναντήσουν ανταγωνισμό και κακή απόδοση. Σκεφτείτε να χρησιμοποιήσετε ξεχωριστά στιγμιότυπα της κλάσης @code{Random} ανά νήμα αντίθετα.
@end quotation
@end cartouche

@menu
* Συναρτήσεις καταγραφής:: 
* Συναρτήσεις για bytes:: 
* Συναρτήσεις για ακέραιους:: 
* Συναρτήσεις για ακολουθίες:: 
* Διακριτές κατανομές:: 
* Πραγματικές κατανομές:: 
* Εναλλακτική Γεννήτρια:: 
* Σημειώσεις για την Αναπαραγωγιμότητα:: 
* Παραδείγματα: Παραδείγματα<2>. 
* Συνταγές:: 
* Χρήση από τη γραμμή εντολών:: 
* Παράδειγμα από τη γραμμή εντολών:: 

@end menu

@node Συναρτήσεις καταγραφής,Συναρτήσεις για bytes,,random — Δημιουργία ψευδοτυχαίων αριθμών
@anchor{library/random bookkeeping-functions}@anchor{2d76}
@subsubsection Συναρτήσεις καταγραφής


@geindex seed() (στη μονάδα random)
@anchor{library/random random seed}@anchor{1618}
@deffn {Συνάρτηση} random.seed (a=None, version=2)

Αρχικοποίηση της γεννήτριας τυχαίων αριθμών.

Αν το `a' παραλειφθεί ή είναι @code{None}, χρησιμοποιείται η τρέχουσα ώρα του συστήματος. Αν οι πηγές τυχαιότητας παρέχονται από το λειτουργικό σύστημα, χρησιμοποιούνται αντί της ώρας του συστήματος (δείτε τη λειτουργία @ref{931,,os.urandom()} για λεπτομέρειες σχετικά με τη διαθεσιμότητα).

If `a' is an int, its absolute value is used directly.

Με την έκδοση 2 (η προεπιλεγμένη), ένα αντικείμενο @ref{1df,,str}, @ref{1c7,,bytes}, ή @ref{1c6,,bytearray} μετατρέπεται σε @ref{326,,int} και χρησιμοποιούνται όλα τα bits του.

Με την έκδοση 1 (παρέχεται για την αναπαραγωγή τυχαίων ακολουθιών από παλαιότερες εκδόσεις της Python), ο αλγόριθμος για @ref{1df,,str} και @ref{1c7,,bytes} παράγει ένα στενότερο εύρος seeds.


Άλλαξε στην έκδοση 3.2: Μεταφέρθηκε στο σχήμα έκδοσης 2 που χρησιμοποιεί όλα τα bits σε ένα seed τύπου string.



Άλλαξε στην έκδοση 3.11: Το `seed' πρέπει να είναι ένας από τους ακόλουθους τύπους: @code{None}, @ref{326,,int}, @ref{327,,float}, @ref{1df,,str}, @ref{1c7,,bytes}, ή @ref{1c6,,bytearray}.

@end deffn

@geindex getstate() (στη μονάδα random)
@anchor{library/random random getstate}@anchor{2d77}
@deffn {Συνάρτηση} random.getstate ()

Επιστρέφει ένα αντικείμενο που καταγράφει την τρέχουσα εσωτερική κατάσταση της γεννήτριας. Αυτό το αντικείμενο μπορεί να περαστεί στη @ref{2d78,,setstate()} για να αποκαταστήσει την κατάσταση.
@end deffn

@geindex setstate() (στη μονάδα random)
@anchor{library/random random setstate}@anchor{2d78}
@deffn {Συνάρτηση} random.setstate (state)

Το `state' θα πρέπει να έχει αποκτηθεί από μια προηγούμενη κλήση στη @ref{2d77,,getstate()}, και η @ref{2d78,,setstate()} αποκαθιστά την εσωτερική κατάσταση της γεννήτριας σε αυτή που ήταν τη στιγμή που κλήθηκε η @code{getstate()}.
@end deffn

@node Συναρτήσεις για bytes,Συναρτήσεις για ακέραιους,Συναρτήσεις καταγραφής,random — Δημιουργία ψευδοτυχαίων αριθμών
@anchor{library/random functions-for-bytes}@anchor{2d79}
@subsubsection Συναρτήσεις για bytes


@geindex randbytes() (στη μονάδα random)
@anchor{library/random random randbytes}@anchor{1a36}
@deffn {Συνάρτηση} random.randbytes (n)

Δημιουργεί `n' τυχαία bytes.

Αυτή η μέθοδος δεν πρέπει να χρησιμοποιείται για τη δημιουργία ασφαλών tokens. Χρησιμοποιήστε αντί αυτού τη @ref{2d7a,,secrets.token_bytes()}.


Added in version 3.9.

@end deffn

@node Συναρτήσεις για ακέραιους,Συναρτήσεις για ακολουθίες,Συναρτήσεις για bytes,random — Δημιουργία ψευδοτυχαίων αριθμών
@anchor{library/random functions-for-integers}@anchor{2d7b}
@subsubsection Συναρτήσεις για ακέραιους


@geindex randrange() (στη μονάδα random)
@anchor{library/random random randrange}@anchor{c41}
@deffn {Συνάρτηση} random.randrange (stop)

@deffnx {Συνάρτηση} random.randrange (start, stop[, step])

Επιστρέφει ένα τυχαία επιλεγμένο στοιχείο από @code{range(start, stop, step)}.

Αυτό είναι περίπου ισοδύναμο με το @code{choice(range(start, stop, step))} αλλά υποστηρίζει αυθαίρετα μεγάλα εύρη και είναι βελτιστοποιημένο για κοινές περιπτώσεις.

Το μοτίβο των θέσεων παραμέτρων ταιριάζει με τη συνάρτηση @ref{d0f,,range()}.

Οι παράμετροι λέξεων-κλειδιών δεν πρέπει να χρησιμοποιούνται επειδή μπορούν να ερμηνευτούν με απροσδόκητους τρόπους. Για παράδειγμα, το @code{randrange(start=100)} ερμηνεύεται ως @code{randrange(0, 100, 1)}.


Άλλαξε στην έκδοση 3.2: Η μέθοδος @ref{c41,,randrange()} είναι πιο εξελιγμένη όσον αφορά την παραγωγή ομοιόμορφα κατανεμημένων τιμών. Προηγουμένως χρησιμοποιούσε ένα στυλ όπως @code{int(random()*n)}  το οποίο μπορούσε να παράγει ελαφρώς άνισες κατανομές.



Άλλαξε στην έκδοση 3.12: Η αυτόματη μετατροπή μη ακέραιων τύπων δεν υποστηρίζεται πλέον. Κλήσεις όπως @code{randrange(10.0)} και @code{randrange(Fraction(10, 1))} τώρα κάνουν raise μια @ref{291,,TypeError}.

@end deffn

@geindex randint() (στη μονάδα random)
@anchor{library/random random randint}@anchor{15d5}
@deffn {Συνάρτηση} random.randint (a, b)

Επιστρέφει έναν τυχαίο ακέραιο `N' τέτοιο ώστε @code{a <= N <= b}. Ψευδώνυμο για @code{randrange(a, b+1)}.
@end deffn

@geindex getrandbits() (στη μονάδα random)
@anchor{library/random random getrandbits}@anchor{13b6}
@deffn {Συνάρτηση} random.getrandbits (k)

Επιστρέφει έναν μη αρνητικό ακέραιο Python με `k' τυχαία bits. Αυτή η μέθοδος παρέχεται με την γεννήτρια Mersenne Twister και μερικές άλλες γεννήτριες μπορεί επίσης να την παρέχουν ως προαιρετικό μέρος του API. Όταν είναι διαθέσιμη, η @ref{13b6,,getrandbits()} επιτρέπει στην @ref{c41,,randrange()} να χειρίζεται αυθαίρετα μεγάλα εύρη.


Άλλαξε στην έκδοση 3.9: Αυτή η μέθοδος τώρα δέχεται το μηδέν για `k'.

@end deffn

@node Συναρτήσεις για ακολουθίες,Διακριτές κατανομές,Συναρτήσεις για ακέραιους,random — Δημιουργία ψευδοτυχαίων αριθμών
@anchor{library/random functions-for-sequences}@anchor{2d7c}
@subsubsection Συναρτήσεις για ακολουθίες


@geindex choice() (στη μονάδα random)
@anchor{library/random random choice}@anchor{15d6}
@deffn {Συνάρτηση} random.choice (seq)

Επιστρέφει ένα τυχαίο στοιχείο από την μη κενή ακολουθία `seq'. Αν το `seq' είναι κενό, κάνει raise μια @ref{18d7,,IndexError}.
@end deffn

@geindex choices() (στη μονάδα random)
@anchor{library/random random choices}@anchor{1083}
@deffn {Συνάρτηση} random.choices (population, weights=None, *, cum_weights=None, k=1)

Επιστρέφει μια λίστα μεγέθους `k' από στοιχεία επιλεγμένα από τον `πληθυσμό' με αντικατάσταση. Αν το `population' είναι κενό, κάνει raise μια @ref{18d7,,IndexError}.

Αν μια ακολουθία `weights' καθοριστεί, οι επιλογές γίνονται σύμφωνα με τα σχετικά βάρη. Εναλλακτικά, αν μια ακολουθία `cum_weights' δοθεί, οι επιλογές γίνονται σύμφωνα με τα σωρευτικά βάρη (ίσως υπολογισμένα χρησιμοποιώντας @ref{dbf,,itertools.accumulate()}). Για παράδειγμα, τα σχετικά βάρη @code{[10, 5, 30, 5]} είναι ισοδύναμα με τα σωρευτικά βάρη @code{[10, 15, 45, 50]}. Εσωτερικά, τα σχετικά βάρη μετατρέπονται σε σωρευτικά βάρη πριν από τις επιλογές, οπότε η παροχή των σωρευτικών βαρών εξοικονομεί εργασία.

Αν ούτε τα `weights' ούτε τα `cum_weights' καθοριστούν, οι επιλογές γίνονται με ίση πιθανότητα. Αν μια ακολουθία βαρών καθοριστεί, πρέπει να είναι του ίδιου μήκους με την ακολουθία του `πληθυσμού'. Είναι μια @ref{291,,TypeError} να καθορίσετε και τα δύο `weights' και `cum_weights'.

Τα `weights' ή `cum_weights' μπορούν να χρησιμοποιούν οποιονδήποτε αριθμητικό τύπο που συνεργάζεται με τις τιμές @ref{327,,float} που επιστρέφονται από τη @ref{c0,,random()} (αυτό περιλαμβάνει ακέραιους, floats και κλάσματα αλλά εξαιρεί τα δεκαδικά). Τα βάρη θεωρούνται μη αρνητικά και πεπερασμένα. Μια @ref{277,,ValueError} γίνεται raise αν όλα τα βάρη είναι μηδενικά.

Για ένα δεδομένο seed, η συνάρτηση @ref{1083,,choices()} με ίσα βάρη παράγει συνήθως μια διαφορετική ακολουθία από τις επαναλαμβανόμενες κλήσεις @ref{15d6,,choice()}. Ο αλγόριθμος που χρησιμοποιείται από τη @code{choices()} χρησιμοποιεί αριθμητική κινητής υποδιαστολής για εσωτερική συνέπεια και ταχύτητα. Ο αλγόριθμος που χρησιμοποιείται από τη @code{choice()} προεπιλέγει την ακέραια αριθμητική με επαναλαμβανόμενες επιλογές για να αποφύγει μικρές προκαταλήψεις από σφάλματα στρογγυλοποίησης.


Added in version 3.6.



Άλλαξε στην έκδοση 3.9: Κάνει raise μια @ref{277,,ValueError} αν όλα τα βάρη είναι μηδενικά.

@end deffn

@geindex shuffle() (στη μονάδα random)
@anchor{library/random random shuffle}@anchor{b2c}
@deffn {Συνάρτηση} random.shuffle (x)

Ανακατεύει την ακολουθία `x' στη θέση της.

Για να ανακατέψετε μια αμετάβλητη ακολουθία και να επιστρέψετε μια νέα ανακατεμένη λίστα, χρησιμοποιήστε @code{sample(x, k=len(x))} αντί αυτού.

Σημειώστε ότι ακόμη και για μικρό @code{len(x)}, ο συνολικός αριθμός επαναλήψεων του `x' μπορεί να αυξηθεί γρήγορα μεγαλύτερα από την περίοδο των περισσότερων γεννητριών τυχαίων αριθμών. Αυτό υποδηλώνει ότι οι περισσότερες επαναλήψεις μιας μεγάλης ακολουθίας δεν μπορούν ποτέ να παραχθούν. Για παράδειγμα, μια ακολουθία μήκους 2080 είναι η μεγαλύτερη που μπορεί να χωρέσει εντός της περιόδου της γεννήτριας τυχαίων αριθμών του Mersenne Twister.


Άλλαξε στην έκδοση 3.11: Αφαιρέθηκε η προαιρετική παράμετρος `random'.

@end deffn

@geindex sample() (στη μονάδα random)
@anchor{library/random random sample}@anchor{b2b}
@deffn {Συνάρτηση} random.sample (population, k, *, counts=None)

Επιστρέφει μια λίστα μήκους `k' από μοναδικά στοιχεία επιλεγμένα από την ακολουθία του πληθυσμού. Χρησιμοποιείται για τυχαία δειγματοληψία χωρίς αντικατάσταση.

Επιστρέφει μια νέα λίστα που περιέχει στοιχεία από τον πληθυσμό αφήνοντας την αρχική ακολουθία του πληθυσμού αμετάβλητη. Η προκύπτουσα λίστα είναι σε σειρά επιλογής έτσι ώστε όλα τα υπο-κομμάτια να είναι επίσης έγκυρα τυχαία δείγματα. Αυτό επιτρέπει στους νικητές της κλήρωσης (το δείγμα) να διαχωριστούν σε νικητές του μεγάλου βραβείου και δεύτερης θέσης (τα υπο-κομμάτια).

Τα μέλη του πληθυσμού δεν χρειάζεται να είναι @ref{183,,hashable} ή μοναδικά. Αν ο πληθυσμός περιέχει επαναλήψεις, τότε κάθε εμφάνιση είναι μια δυνατή επιλογή στο δείγμα.

Τα επαναλαμβανόμενα στοιχεία μπορούν να καθοριστούν ένα-ένα ή με την προαιρετική παράμετρο μόνο-για-λέξεις-κλειδιά `counts'. Για παράδειγμα, @code{sample(['red', 'blue'], counts=[4, 2], k=5)} είναι ισοδύναμο με @code{sample(['red', 'red', 'red', 'red', 'blue', 'blue'], k=5)}.

Για να επιλέξετε ένα δείγμα από ένα εύρος ακέραιων, χρησιμοποιήστε ένα @ref{d0f,,range()} αντικείμενο ως παράμετρο. Αυτό είναι ιδιαίτερα γρήγορο και αποδοτικό σε χώρο για δειγματοληψία από έναν μεγάλο πληθυσμό: @code{sample(range(10000000), k=60)}.

Αν το μέγεθος του δείγματος είναι μεγαλύτερο από το μέγεθος του πληθυσμού, γίνεται raise μια @ref{277,,ValueError}.


Άλλαξε στην έκδοση 3.9: Προστέθηκε η παράμετρος `counts'.



Άλλαξε στην έκδοση 3.11: Ο `πληθυσμός' πρέπει να είναι μια ακολουθία. Η αυτόματη μετατροπή συνόλων σε λίστες δεν υποστηρίζεται πλέον.

@end deffn

@node Διακριτές κατανομές,Πραγματικές κατανομές,Συναρτήσεις για ακολουθίες,random — Δημιουργία ψευδοτυχαίων αριθμών
@anchor{library/random discrete-distributions}@anchor{2d7d}
@subsubsection Διακριτές κατανομές


Η ακόλουθη συνάρτηση δημιουργεί μια διακριτή κατανομή.

@geindex binomialvariate() (στη μονάδα random)
@anchor{library/random random binomialvariate}@anchor{8c0}
@deffn {Συνάρτηση} random.binomialvariate (n=1, p=0.5)

Binomial distribution@footnote{https://mathworld.wolfram.com/BinomialDistribution.html}. Επιστρέφει τον αριθμό των επιτυχιών για `n' ανεξάρτητες δοκιμές με την πιθανότητα επιτυχίας σε κάθε δοκιμή να είναι `p':

Μαθηματικά ισοδύναμο με:

@example
sum(random() < p for i in range(n))
@end example

Ο αριθμός των δοκιμών `n' πρέπει να είναι ένας μη αρνητικός ακέραιος. Η πιθανότητα επιτυχίας `p' πρέπει να είναι μεταξύ @code{0.0 <= p <= 1.0}. Το αποτέλεσμα είναι ένας ακέραιος στο εύρος @code{0 <= X <= n}.


Added in version 3.12.

@end deffn

@node Πραγματικές κατανομές,Εναλλακτική Γεννήτρια,Διακριτές κατανομές,random — Δημιουργία ψευδοτυχαίων αριθμών
@anchor{library/random id1}@anchor{2d7e}@anchor{library/random real-valued-distributions}@anchor{2d7f}
@subsubsection Πραγματικές κατανομές


Οι ακόλουθες συναρτήσεις δημιουργούν συγκεκριμένες πραγματικές κατανομές. Οι παράμετροι των συναρτήσεων ονομάζονται όπως οι αντίστοιχες μεταβλητές στην εξίσωση της κατανομής, όπως χρησιμοποιείται στην κοινή μαθηματική πρακτική. Οι περισσότερες από αυτές τις εξισώσεις μπορούν να βρεθούν σε οποιοδήποτε εγχειρίδιο στατιστικής.

@geindex random() (στη μονάδα random)
@anchor{library/random random random}@anchor{b2d}
@deffn {Συνάρτηση} random.random ()

Επιστρέφει τον επόμενο τυχαίο αριθμό κινητής υποδιαστολής στο εύρος @code{0.0 <= X < 1.0}
@end deffn

@geindex uniform() (στη μονάδα random)
@anchor{library/random random uniform}@anchor{2d80}
@deffn {Συνάρτηση} random.uniform (a, b)

Επιστρέφει έναν τυχαίο αριθμό κινητής υποδιαστολής `N' τέτοιο ώστε @code{a <= N <= b} για @code{a <= b} και @code{b <= N <= a} για @code{b < a}.

Η τιμή του τελικού σημείου @code{b} μπορεί να περιλαμβάνεται ή όχι στο εύρος ανάλογα με τη στρογγυλοποίηση κινητής υποδιαστολής στην έκφραση @code{a + (b-a) * random()}.
@end deffn

@geindex triangular() (στη μονάδα random)
@anchor{library/random random triangular}@anchor{2d81}
@deffn {Συνάρτηση} random.triangular (low, high, mode)

Επιστρέφει έναν τυχαίο αριθμό κινητής υποδιαστολής `N' τέτοιο ώστε @code{low <= N <= high} και με το καθορισμένο `mode' μεταξύ αυτών των ορίων. Τα όρια `low' και `high' προεπιλέγονται στο μηδέν και το ένα. Η παράμετρος `mode' προεπιλέγεται στο μέσο όρο μεταξύ των ορίων, δίνοντας μια συμμετρική κατανομή.
@end deffn

@geindex betavariate() (στη μονάδα random)
@anchor{library/random random betavariate}@anchor{2d82}
@deffn {Συνάρτηση} random.betavariate (alpha, beta)

Κατανομή Beta. Οι συνθήκες για τις παραμέτρους είναι @code{alpha > 0} και @code{beta > 0}. Οι επιστρεφόμενες τιμές κυμαίνονται μεταξύ 0 και 1.
@end deffn

@geindex expovariate() (στη μονάδα random)
@anchor{library/random random expovariate}@anchor{8c1}
@deffn {Συνάρτηση} random.expovariate (lambd=1.0)

Εκθετική κατανομή. Το `lambd' είναι 1.0 διαιρεμένο με τον επιθυμητό μέσο όρο. Πρέπει να είναι μη μηδενικό. (Η παράμετρος θα ονομαζόταν «lambda», αλλά αυτό είναι μια δεσμευμένη λέξη στην Python.) Οι επιστρεφόμενες τιμές κυμαίνονται από 0 έως θετικό άπειρο αν το `lambd' είναι θετικό, και από αρνητικό άπειρο έως 0 αν το `lambd' είναι αρνητικό.


Άλλαξε στην έκδοση 3.12: Προστέθηκε η προεπιλεγμένη τιμή για το @code{lambd}.

@end deffn

@geindex gammavariate() (στη μονάδα random)
@anchor{library/random random gammavariate}@anchor{2d83}
@deffn {Συνάρτηση} random.gammavariate (alpha, beta)

Κατανομή Gamma. (`Όχι' η συνάρτηση gamma!) Οι παράμετροι σχήματος και κλίμακας, `alpha' και `beta', πρέπει να έχουν θετικές τιμές. (Οι συμβάσεις κλήσης διαφέρουν και μερικές πηγές ορίζουν το “beta” ως το αντίστροφο της κλίμακας).

Η συνάρτηση κατανομής πιθανότητας είναι:

@example
          x ** (alpha - 1) * math.exp(-x / beta)
pdf(x) =  --------------------------------------
            math.gamma(alpha) * beta ** alpha
@end example
@end deffn

@geindex gauss() (στη μονάδα random)
@anchor{library/random random gauss}@anchor{1dd1}
@deffn {Συνάρτηση} random.gauss (mu=0.0, sigma=1.0)

Κανονική κατανομή, επίσης γνωστή ως κατανομή Gaussian. Το `mu' είναι ο μέσος όρος, και το `sigma' είναι η τυπική απόκλιση. Αυτό είναι ελαφρώς ταχύτερο από τη συνάρτηση @ref{1dd2,,normalvariate()} που ορίζεται παρακάτω.

Σημείωση πολυνημάτωσης: Όταν δύο νήματα καλούν αυτή τη συνάρτηση ταυτόχρονα, είναι πιθανό να λάβουν την ίδια τιμή επιστροφής. Αυτό μπορεί να αποφευχθεί με τρεις τρόπους. 1) Κάθε νήμα να χρησιμοποιεί μια διαφορετική παρουσία της γεννήτριας τυχαίων αριθμών. 2) Να τοποθετήσετε κλειδώματα γύρω από όλες τις κλήσεις. 3) Να χρησιμοποιήσετε τη πιο αργή, αλλά ασφαλή για νήματα, συνάρτηση @ref{1dd2,,normalvariate()} αντί αυτού.


Άλλαξε στην έκδοση 3.11: Το `mu' και το `sigma' έχουν τώρα προεπιλεγμένες παραμέτρους.

@end deffn

@geindex lognormvariate() (στη μονάδα random)
@anchor{library/random random lognormvariate}@anchor{2d84}
@deffn {Συνάρτηση} random.lognormvariate (mu, sigma)

Κατανομή log normal. Αν πάρετε τον φυσικό λογάριθμο αυτής της κατανομής, θα πάρετε μια κανονική κατανομή με μέσο όρο `mu' και τυπική απόκλιση `sigma'. Το `mu' μπορεί να έχει οποιαδήποτε τιμή, και το `sigma' πρέπει να είναι μεγαλύτερο από το μηδέν.
@end deffn

@geindex normalvariate() (στη μονάδα random)
@anchor{library/random random normalvariate}@anchor{1dd2}
@deffn {Συνάρτηση} random.normalvariate (mu=0.0, sigma=1.0)

Κανονική κατανομή. Το `mu' είναι ο μέσος όρος, και το `sigma' είναι η τυπική απόκλιση.


Άλλαξε στην έκδοση 3.11: Το `mu' και το `sigma' έχουν τώρα προεπιλεγμένες παραμέτρους.

@end deffn

@geindex vonmisesvariate() (στη μονάδα random)
@anchor{library/random random vonmisesvariate}@anchor{2d85}
@deffn {Συνάρτηση} random.vonmisesvariate (mu, kappa)

Το `mu' είναι η μέση γωνία, εκφρασμένη σε ακτίνια μεταξύ 0 και 2*`pi', και `kappa' είναι η παράμετρος συγκέντρωσης, η οποία πρέπει να είναι μεγαλύτερη ή ίση με το μηδέν. Αν το `kappa' είναι ίσο με το μηδέν, αυτή η κατανομή μειώνεται σε μια ομοιόμορφη τυχαία γωνία στο εύρος 0 έως 2*`pi'.
@end deffn

@geindex paretovariate() (στη μονάδα random)
@anchor{library/random random paretovariate}@anchor{2d86}
@deffn {Συνάρτηση} random.paretovariate (alpha)

Κατανομή Pareto. Το `alpha' είναι η παράμετρος σχήματος.
@end deffn

@geindex weibullvariate() (στη μονάδα random)
@anchor{library/random random weibullvariate}@anchor{2d87}
@deffn {Συνάρτηση} random.weibullvariate (alpha, beta)

Κατανομή Weibull. Το `alpha' είναι η παράμετρος κλίμακας και το `beta' είναι η παράμετρος σχήματος.
@end deffn

@node Εναλλακτική Γεννήτρια,Σημειώσεις για την Αναπαραγωγιμότητα,Πραγματικές κατανομές,random — Δημιουργία ψευδοτυχαίων αριθμών
@anchor{library/random alternative-generator}@anchor{2d88}
@subsubsection Εναλλακτική Γεννήτρια


@geindex Random (κλάση σε random)
@anchor{library/random random Random}@anchor{1e53}
@deffn {Κλάση} random.Random ([seed])

Class that implements the default pseudo-random number generator used by the
@code{random} module.


Άλλαξε στην έκδοση 3.11: Προηγουμένως το `seed' μπορούσε να είναι οποιοδήποτε hashable αντικείμενο. Τώρα περιορίζεται σε: @code{None}, @ref{326,,int}, @ref{327,,float}, @ref{1df,,str}, @ref{1c7,,bytes}, ή @ref{1c6,,bytearray}.


Οι υποκλάσεις της @code{Random} θα πρέπει να αντικαταστήσουν τις παρακάτω μεθόδους αν επιθυμούν να χρησιμοποιήσουν μια διαφορετική βασική γεννήτρια:

@geindex seed() (μέθοδος της random.Random)
@anchor{library/random random Random seed}@anchor{1f5e}
@deffn {Μέθοδος} seed (a=None, version=2)

Αντικαταστήστε αυτή τη μέθοδο στις υποκλάσεις για να προσαρμόσετε τη @ref{1618,,seed()} συμπεριφορά των @code{Random} στιγμιότυπων.
@end deffn

@geindex getstate() (μέθοδος της random.Random)
@anchor{library/random random Random getstate}@anchor{2d89}
@deffn {Μέθοδος} getstate ()

Αντικαταστήστε αυτή τη μέθοδο στις υποκλάσεις για να προσαρμόσετε τη @ref{2d77,,getstate()} συμπεριφορά των @code{Random} στιγμιότυπων.
@end deffn

@geindex setstate() (μέθοδος της random.Random)
@anchor{library/random random Random setstate}@anchor{2d8a}
@deffn {Μέθοδος} setstate (state)

Αντικαταστήστε αυτή τη μέθοδο στις υποκλάσεις για να προσαρμόσετε τη @ref{2d78,,setstate()} συμπεριφορά των @code{Random} στιγμιότυπων.
@end deffn

@geindex random() (μέθοδος της random.Random)
@anchor{library/random random Random random}@anchor{2d8b}
@deffn {Μέθοδος} random ()

Αντικαταστήστε αυτή τη μέθοδο στις υποκλάσεις για να προσαρμόσετε τη @ref{b2d,,random()} συμπεριφορά των @code{Random} στιγμιότυπων.
@end deffn

Μια προαιρετική υποκλάση γεννήτριας μπορεί επίσης να παρέχει την ακόλουθη μέθοδο:

@geindex getrandbits() (μέθοδος της random.Random)
@anchor{library/random random Random getrandbits}@anchor{2d8c}
@deffn {Μέθοδος} getrandbits (k)

Αντικαταστήστε αυτή τη μέθοδο στις υποκλάσεις για να προσαρμόσετε τη @ref{13b6,,getrandbits()} συμπεριφορά των @code{Random} στιγμιότυπων.
@end deffn

@geindex randbytes() (μέθοδος της random.Random)
@anchor{library/random random Random randbytes}@anchor{cf6}
@deffn {Μέθοδος} randbytes (n)

Αντικαταστήστε αυτή τη μέθοδο στις υποκλάσεις για να προσαρμόσετε τη @ref{1a36,,randbytes()} συμπεριφορά των @code{Random} στιγμιότυπων.
@end deffn
@end deffn

@geindex SystemRandom (κλάση σε random)
@anchor{library/random random SystemRandom}@anchor{2d75}
@deffn {Κλάση} random.SystemRandom ([seed])

Κλάση που χρησιμοποιεί τη συνάρτηση @ref{931,,os.urandom()} για τη δημιουργία τυχαίων αριθμών από πηγές που παρέχονται από το λειτουργικό σύστημα. Δεν είναι διαθέσιμη σε όλα τα συστήματα. Δεν βασίζεται σε λογισμικό κατάσταση, και οι ακολουθίες δεν είναι αναπαραγωγίσιμες. Σύμφωνα με αυτό, η μέθοδος @ref{1618,,seed()} δεν έχει καμία επίδραση και αγνοείται. Οι μέθοδοι @ref{2d77,,getstate()} και @ref{2d78,,setstate()} προκαλούν @ref{59a,,NotImplementedError} αν κληθούν.
@end deffn

@node Σημειώσεις για την Αναπαραγωγιμότητα,Παραδείγματα<2>,Εναλλακτική Γεννήτρια,random — Δημιουργία ψευδοτυχαίων αριθμών
@anchor{library/random notes-on-reproducibility}@anchor{2d8d}
@subsubsection Σημειώσεις για την Αναπαραγωγιμότητα


Μερικές φορές είναι χρήσιμο να είναι δυνατή η αναπαραγωγή των ακολουθιών που παρέχονται από μια ψευδοτυχαία γεννήτρια αριθμών. Επαναχρησιμοποιώντας μια τιμή seed, η ίδια ακολουθία θα πρέπει να είναι αναπαραγωγίσιμη από εκτέλεση σε εκτέλεση, εφόσον δεν τρέχουν πολλαπλά νήματα ταυτόχρονα.

Οι περισσότεροι αλγόριθμοι και συναρτήσεις σποράς του module random υπόκεινται σε αλλαγές μεταξύ εκδόσεων της Python, αλλά δύο πτυχές εγγυώνται ότι δεν θα αλλάξουν:


@itemize *

@item 
Εάν προστεθεί μια νέα μέθοδος σποράς, τότε θα προσφέρεται ένας σπορέας συμβατός με παλαιότερες εκδόσεις.

@item 
Η μέθοδος @ref{2d8b,,random()} της γεννήτριας θα συνεχίσει να παράγει την ίδια ακολουθία όταν ο συμβατός σπορέας δίνεται την ίδια τιμή seed.
@end itemize

@node Παραδείγματα<2>,Συνταγές,Σημειώσεις για την Αναπαραγωγιμότητα,random — Δημιουργία ψευδοτυχαίων αριθμών
@anchor{library/random examples}@anchor{2d8e}@anchor{library/random random-examples}@anchor{1585}
@subsubsection Παραδείγματα


Βασικά παραδείγματα:

@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

Προσομοιώσεις:

@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

Παράδειγμα του statistical bootstrapping@footnote{https://en.wikipedia.org/wiki/Bootstrapping_(statistics)} χρησιμοποιώντας δειγματοληψία με αντικατάσταση για να εκτιμήσει ένα διάστημα εμπιστοσύνης για τον μέσο όρο ενός δείγματος:

@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

Παράδειγμα ενός resampling permutation test@footnote{https://en.wikipedia.org/wiki/Resampling_(statistics)#Permutation_tests} για να προσδιορίσει τη στατιστική σημασία ή την p-value@footnote{https://en.wikipedia.org/wiki/P-value} μιας παρατηρούμενης διαφοράς μεταξύ των επιδράσεων ενός φαρμάκου σε σύγκριση με ένα εικονικό φάρμακο:

@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

Προσομοίωση χρόνων άφιξης και παραδόσεων υπηρεσιών για μια ουρά πολλαπλών διακομιστών:

@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 Δείτε επίσης


Statistics for Hackers@footnote{https://www.youtube.com/watch?v=Iq9DzN6mvYA} ένα βίντεο σεμινάριο από τον Jake Vanderplas@footnote{https://us.pycon.org/2016/speaker/profile/295/} για στατιστική ανάλυση χρησιμοποιώντας μόνο μερικές θεμελιώδεις έννοιες όπως η προσομοίωση, η δειγματοληψία, η αναδιάταξη και η διασταύρωση επικύρωσης.

Economics Simulation@footnote{https://nbviewer.org/url/norvig.com/ipython/Economics.ipynb} μια προσομοίωση μιας αγοράς από τον Peter Norvig@footnote{https://norvig.com/bio.html} που δείχνει αποτελεσματική χρήση πολλών από τα εργαλεία και τις κατανομές που παρέχονται από αυτό το module (gauss, uniform, sample, betavariate, choice, triangular, και randrange).

A Concrete Introduction to Probability (using Python)@footnote{https://nbviewer.org/url/norvig.com/ipython/Probability.ipynb} ένα σεμινάριο από τον Peter Norvig@footnote{https://norvig.com/bio.html} που καλύπτει τα βασικά της θεωρίας πιθανοτήτων, πώς να γράψετε προσομοιώσεις, και πώς να εκτελέσετε ανάλυση δεδομένων χρησιμοποιώντας Python.


@node Συνταγές,Χρήση από τη γραμμή εντολών,Παραδείγματα<2>,random — Δημιουργία ψευδοτυχαίων αριθμών
@anchor{library/random recipes}@anchor{2d8f}
@subsubsection Συνταγές


These recipes show how to efficiently make random selections
from the combinatoric iterators in the @ref{84,,itertools} module
or the more-itertools@footnote{https://pypi.org/project/more-itertools/} project:

@example
import random

def random_product(*iterables, repeat=1):
    "Random selection from itertools.product(*iterables, repeat=repeat)"
    pools = tuple(map(tuple, iterables)) * 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)

def random_derangement(iterable):
    "Choose a permutation where no element stays in its original position."
    seq = tuple(iterable)
    if len(seq) < 2:
        if not seq:
            return ()
        raise IndexError('No derangments to choose from')
    perm = list(range(len(seq)))
    start = tuple(perm)
    while True:
        random.shuffle(perm)
        if all(p != q for p, q in zip(start, perm)):
            return tuple([seq[i] for i in perm])
@end example

@c >>> import random
@c 
@c 
@c >>> random.seed(8675309)
@c >>> random_product('ABCDEFG', repeat=5)
@c ('D', 'B', 'E', 'F', 'E')
@c 
@c 
@c >>> random.seed(8675309)
@c >>> random_permutation('ABCDEFG')
@c ('D', 'B', 'E', 'C', 'G', 'A', 'F')
@c >>> random_permutation('ABCDEFG', 5)
@c ('A', 'G', 'D', 'C', 'B')
@c 
@c 
@c >>> random.seed(8675309)
@c >>> random_combination('ABCDEFG', 7)
@c ('A', 'B', 'C', 'D', 'E', 'F', 'G')
@c >>> random_combination('ABCDEFG', 6)
@c ('A', 'B', 'C', 'D', 'F', 'G')
@c >>> random_combination('ABCDEFG', 5)
@c ('A', 'B', 'C', 'E', 'F')
@c >>> random_combination('ABCDEFG', 4)
@c ('B', 'C', 'D', 'G')
@c >>> random_combination('ABCDEFG', 3)
@c ('B', 'E', 'G')
@c >>> random_combination('ABCDEFG', 2)
@c ('E', 'G')
@c >>> random_combination('ABCDEFG', 1)
@c ('C',)
@c >>> random_combination('ABCDEFG', 0)
@c ()
@c 
@c 
@c >>> random.seed(8675309)
@c >>> random_combination_with_replacement('ABCDEFG', 7)
@c ('B', 'C', 'D', 'E', 'E', 'E', 'G')
@c >>> random_combination_with_replacement('ABCDEFG', 3)
@c ('A', 'B', 'E')
@c >>> random_combination_with_replacement('ABCDEFG', 2)
@c ('A', 'G')
@c >>> random_combination_with_replacement('ABCDEFG', 1)
@c ('E',)
@c >>> random_combination_with_replacement('ABCDEFG', 0)
@c ()
@c 
@c 
@c >>> random.seed(8675309)
@c >>> random_derangement('')
@c ()
@c >>> random_derangement('A')
@c Traceback (most recent call last):
@c ...
@c IndexError: No derangments to choose from
@c >>> random_derangement('AB')
@c ('B', 'A')
@c >>> random_derangement('ABC')
@c ('C', 'A', 'B')
@c >>> random_derangement('ABCD')
@c ('B', 'A', 'D', 'C')
@c >>> random_derangement('ABCDE')
@c ('B', 'C', 'A', 'E', 'D')
@c >>> # Identical inputs treated as distinct
@c >>> identical = 20
@c >>> random_derangement((10, identical, 30, identical))
@c (20, 30, 10, 20)

Η προεπιλεγμένη @ref{b2d,,random()} επιστρέφει πολλαπλάσια του 2⁻⁵³ στο διάστημα `0.0 ≤ x < 1.0'. Όλοι αυτοί οι αριθμοί είναι ομοιόμορφα κατανεμημένοι και είναι ακριβώς αναπαραστάσιμοι ως Python floats. Ωστόσο, πολλά άλλα αναπαραστάσιμα floats σε αυτό το διάστημα δεν είναι δυνατές επιλογές. Για παράδειγμα, @code{0.05954861408025609} δεν είναι πολλαπλάσιο του 2⁻⁵³.

Η παρακάτω συνταγή ακολουθεί μια διαφορετική προσέγγιση. Όλα τα floats στο διάστημα είναι δυνατές επιλογές. Η mantissa προέρχεται από μια ομοιόμορφη κατανομή ακεραίων στο διάστημα `2⁵² ≤ mantissa < 2⁵³'. Ο εκθέτης προέρχεται από μια γεωμετρική κατανομή όπου οι εκθέτες μικρότεροι από `−53' εμφανίζονται μισή φορά συχνότερα από τον επόμενο μεγαλύτερο εκθέτη.

@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

Όλες οι @ref{2d7f,,πραγματικές κατανομές} στην κλάση θα χρησιμοποιούν τη νέα μέθοδο:

@example
>>> fr = FullRandom()
>>> fr.random()
0.05954861408025609
>>> fr.expovariate(0.25)
8.87925541791544
@end example

Η συνταγή είναι εννοιολογικά ισοδύναμη με έναν αλγόριθμο που επιλέγει από όλα τα πολλαπλάσια του 2⁻¹⁰⁷⁴ στο διάστημα `0.0 ≤ x < 1.0'. Όλοι αυτοί οι αριθμοί είναι ομοιόμορφα κατανεμημένοι, αλλά οι περισσότεροι πρέπει να στρογγυλοποιηθούν προς τα κάτω στο πλησιέστερο αναπαραστάσιμο Python float. (Η τιμή 2⁻¹⁰⁷⁴ είναι το μικρότερο θετικό μη κανονικοποιημένο float και ισούται με @code{math.ulp(0.0)}.)


@subsubheading Δείτε επίσης


Generating Pseudo-random Floating-Point Values@footnote{https://allendowney.com/research/rand/downey07randfloat.pdf} ένα άρθρο του Allen B. Downey που περιγράφει τρόπους δημιουργίας πιο λεπτομερών floats από ό,τι παράγονται συνήθως από @ref{b2d,,random()}.


@node Χρήση από τη γραμμή εντολών,Παράδειγμα από τη γραμμή εντολών,Συνταγές,random — Δημιουργία ψευδοτυχαίων αριθμών
@anchor{library/random command-line-usage}@anchor{2d90}@anchor{library/random random-cli}@anchor{68d}
@subsubsection Χρήση από τη γραμμή εντολών



Added in version 3.13.


Το module @code{random} μπορεί να εκτελεστεί από τη γραμμή εντολών.

@example
python -m random [-h] [-c CHOICE [CHOICE ...] | -i N | -f N] [input ...]
@end example

Αποδέχεται τις παρακάτω επιλογές:

@geindex random command line option; -h
@geindex random command line option; --help
@anchor{library/random cmdoption-random-h}@anchor{2d91}@anchor{library/random cmdoption-random-help}@anchor{2d92}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Εμφανίζει το μήνυμα βοήθειας και εξέρχεται.
@end deffn

@geindex random command line option; -c
@geindex random command line option; --choice
@anchor{library/random cmdoption-random-c}@anchor{2d93}
@deffn {Option} @w{-}c CHOICE [CHOICE ...]
@anchor{library/random cmdoption-random-choice}@anchor{2d94}
@deffnx {Option} @w{-}@w{-}choice CHOICE [CHOICE ...]

Εκτυπώνει μια τυχαία επιλογή, χρησιμοποιώντας τη @ref{15d6,,choice()}.
@end deffn

@geindex random command line option; -i
@geindex random command line option; --integer
@anchor{library/random cmdoption-random-i}@anchor{2d95}
@deffn {Option} @w{-}i <N>
@anchor{library/random cmdoption-random-integer}@anchor{2d96}
@deffnx {Option} @w{-}@w{-}integer <N>

Εκτυπώνει έναν τυχαίο ακέραιο μεταξύ 1 και N συμπεριλαμβανομένου, χρησιμοποιώντας τη @ref{15d5,,randint()}.
@end deffn

@geindex random command line option; -f
@geindex random command line option; --float
@anchor{library/random cmdoption-random-f}@anchor{2d97}
@deffn {Option} @w{-}f <N>
@anchor{library/random cmdoption-random-float}@anchor{2d98}
@deffnx {Option} @w{-}@w{-}float <N>

Εκτυπώνει έναν τυχαίο αριθμό κινητής υποδιαστολής μεταξύ 0 και N συμπεριλαμβανομένου, χρησιμοποιώντας τη @ref{2d80,,uniform()}.
@end deffn

Εάν δεν δοθούν επιλογές, η έξοδος εξαρτάται από την είσοδο:


@itemize *

@item 
Συμβολοσειρά ή πολλαπλά: ίδια με την @ref{2d94,,--choice}.

@item 
Ακέραιος: ίδια με την @ref{2d96,,--integer}.

@item 
Αριθμός κινητής υποδιαστολής: ίδια με την @ref{2d98,,--float}.
@end itemize

@node Παράδειγμα από τη γραμμή εντολών,,Χρήση από τη γραμμή εντολών,random — Δημιουργία ψευδοτυχαίων αριθμών
@anchor{library/random command-line-example}@anchor{2d99}@anchor{library/random random-cli-example}@anchor{2d9a}
@subsubsection Παράδειγμα από τη γραμμή εντολών


Εδώ είναι μερικά παραδείγματα της διεπαφής γραμμής εντολών του @code{random}:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node statistics — Mathematical statistics functions,,random — Δημιουργία ψευδοτυχαίων αριθμών,Αριθμητικά και Μαθηματικά Modules
@anchor{library/statistics doc}@anchor{2d9b}@anchor{library/statistics module-statistics}@anchor{da}@anchor{library/statistics statistics-mathematical-statistics-functions}@anchor{2d9c}@anchor{library/statistics translation-repo}@anchor{2d9d}
@subsection @code{statistics} — Mathematical statistics functions


@geindex module; statistics


Added in version 3.4.


`Source code:' Lib/statistics.py@footnote{https://github.com/python/cpython/tree/main/Lib/statistics.py}

@c from statistics import *
@c import math
@c __name__ = '<doctest>'


__________________________________________________________________


This module provides functions for calculating mathematical statistics of
numeric (@ref{27ec,,Real}-valued) data.

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.

Unless explicitly noted, these functions support @ref{326,,int},
@ref{327,,float}, @ref{1c2,,Decimal} and @ref{1c3,,Fraction}.
Behaviour with other types (whether in the numeric tower or not) is
currently unsupported.  Collections with a mix of types are also undefined
and implementation-dependent.  If your input data consists of mixed types,
you may be able to use @ref{43e,,map()} to ensure a consistent result, for
example: @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
* Averages and measures of central location:: 
* Measures of spread:: 
* Statistics for relations between two inputs:: 
* Function details:: 
* Exceptions: Exceptions<3>. 
* NormalDist objects:: 
* Examples and Recipes:: 

@end menu

@node Averages and measures of central location,Measures of spread,,statistics — Mathematical statistics functions
@anchor{library/statistics averages-and-measures-of-central-location}@anchor{2d9e}
@subsubsection Averages and measures of central location


These functions calculate an average or typical value from a population
or sample.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{abf,,mean()}

@tab

Arithmetic mean («average») of data.

@item

@ref{df8,,fmean()}

@tab

Fast, floating-point arithmetic mean, with optional weighting.

@item

@ref{df9,,geometric_mean()}

@tab

Geometric mean of data.

@item

@ref{109f,,harmonic_mean()}

@tab

Harmonic mean of data.

@item

@ref{754,,kde()}

@tab

Estimate the probability density distribution of the data.

@item

@ref{755,,kde_random()}

@tab

Random sampling from the PDF generated by kde().

@item

@ref{2d9f,,median()}

@tab

Median (middle value) of data.

@item

@ref{2da0,,median_low()}

@tab

Low median of data.

@item

@ref{2da1,,median_high()}

@tab

High median of data.

@item

@ref{2da2,,median_grouped()}

@tab

Median (50th percentile) of grouped data.

@item

@ref{e54,,mode()}

@tab

Single mode (most common value) of discrete or nominal data.

@item

@ref{dfa,,multimode()}

@tab

List of modes (most common values) of discrete or nominal data.

@item

@ref{dfb,,quantiles()}

@tab

Divide data into intervals with equal probability.

@end multitable


@node Measures of spread,Statistics for relations between two inputs,Averages and measures of central location,statistics — Mathematical statistics functions
@anchor{library/statistics measures-of-spread}@anchor{2da3}
@subsubsection Measures of spread


These functions calculate a measure of how much the population or sample
tends to deviate from the typical or average values.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{19c6,,pstdev()}

@tab

Population standard deviation of data.

@item

@ref{2da4,,pvariance()}

@tab

Population variance of data.

@item

@ref{ac1,,stdev()}

@tab

Sample standard deviation of data.

@item

@ref{ac0,,variance()}

@tab

Sample variance of data.

@end multitable


@node Statistics for relations between two inputs,Function details,Measures of spread,statistics — Mathematical statistics functions
@anchor{library/statistics statistics-for-relations-between-two-inputs}@anchor{2da5}
@subsubsection Statistics for relations between two inputs


These functions calculate statistics regarding relations between two inputs.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{c09,,covariance()}

@tab

Sample covariance for two variables.

@item

@ref{8cc,,correlation()}

@tab

Pearson and Spearman’s correlation coefficients.

@item

@ref{c0a,,linear_regression()}

@tab

Slope and intercept for simple linear regression.

@end multitable


@node Function details,Exceptions<3>,Statistics for relations between two inputs,statistics — Mathematical statistics functions
@anchor{library/statistics function-details}@anchor{2da6}
@subsubsection Function details


Note: The functions do not require the data given to them to be sorted.
However, for reading convenience, most of the examples show sorted sequences.

@geindex mean() (στη μονάδα statistics)
@anchor{library/statistics statistics mean}@anchor{abf}
@deffn {Συνάρτηση} statistics.mean (data)

Return the sample arithmetic mean of `data' which can be a sequence or iterable.

The arithmetic mean is the sum of the data divided by the number of data
points.  It is commonly called «the average», although it is only one of many
different mathematical averages.  It is a measure of the central location of
the data.

If `data' is empty, @ref{2da7,,StatisticsError} will be raised.

Some examples of use:

@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 Σημείωση 
The mean is strongly affected by outliers@footnote{https://en.wikipedia.org/wiki/Outlier} and is not necessarily a
typical example of the data points. For a more robust, although less
efficient, measure of central tendency@footnote{https://en.wikipedia.org/wiki/Central_tendency}, see @ref{2d9f,,median()}.

The sample mean gives an unbiased estimate of the true population mean,
so that when taken on average over all the possible samples,
@code{mean(sample)} converges on the true mean of the entire population.  If
`data' represents the entire population rather than a sample, then
@code{mean(data)} is equivalent to calculating the true population mean μ.
@end quotation
@end cartouche
@end deffn

@geindex fmean() (στη μονάδα statistics)
@anchor{library/statistics statistics fmean}@anchor{df8}
@deffn {Συνάρτηση} statistics.fmean (data, weights=None)

Convert `data' to floats and compute the arithmetic mean.

This runs faster than the @ref{abf,,mean()} function and it always returns a
@ref{327,,float}.  The `data' may be a sequence or iterable.  If the input
dataset is empty, raises a @ref{2da7,,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{277,,ValueError} will be raised.


Added in version 3.8.



Άλλαξε στην έκδοση 3.11: Added support for `weights'.

@end deffn

@geindex geometric_mean() (στη μονάδα statistics)
@anchor{library/statistics statistics geometric_mean}@anchor{df9}
@deffn {Συνάρτηση} statistics.geometric_mean (data)

Convert `data' to floats and compute the geometric mean.

The geometric mean indicates the central tendency or typical value of the
`data' using the product of the values (as opposed to the arithmetic mean
which uses their sum).

Raises a @ref{2da7,,StatisticsError} if the input dataset is empty,
if it contains a zero, or if it contains a negative value.
The `data' may be a sequence or iterable.

No special efforts are made to achieve exact results.
(However, this may change in the future.)

@example
>>> round(geometric_mean([54, 24, 36]), 1)
36.0
@end example


Added in version 3.8.

@end deffn

@geindex harmonic_mean() (στη μονάδα statistics)
@anchor{library/statistics statistics harmonic_mean}@anchor{109f}
@deffn {Συνάρτηση} 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{abf,,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.

Suppose a car travels 10 km at 40 km/hr, then another 10 km at 60 km/hr.
What is the average speed?

@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{2da7,,StatisticsError} is raised if `data' is empty, any element
is less than zero, or if the weighted sum isn’t positive.

The current algorithm has an early-out when it encounters a zero
in the input.  This means that the subsequent inputs are not tested
for validity.  (This behavior may change in the future.)


Added in version 3.6.



Άλλαξε στην έκδοση 3.10: Added support for `weights'.

@end deffn

@geindex kde() (στη μονάδα statistics)
@anchor{library/statistics statistics kde}@anchor{754}
@deffn {Συνάρτηση} 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{2da7,,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 @code{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}


Added in version 3.13.

@end deffn

@geindex kde_random() (στη μονάδα statistics)
@anchor{library/statistics statistics kde_random}@anchor{755}
@deffn {Συνάρτηση} 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{2da7,,StatisticsError} will be raised if the `data' sequence is empty.

Continuing the example for @ref{754,,kde()}, we can use
@code{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


Added in version 3.13.

@end deffn

@geindex median() (στη μονάδα statistics)
@anchor{library/statistics statistics median}@anchor{2d9f}
@deffn {Συνάρτηση} statistics.median (data)

Return the median (middle value) of numeric data, using the common «mean of
middle two» method.  If `data' is empty, @ref{2da7,,StatisticsError} is raised.
`data' can be a sequence or iterable.

The median is a robust measure of central location and is less affected by
the presence of outliers.  When the number of data points is odd, the
middle data point is returned:

@example
>>> median([1, 3, 5])
3
@end example

When the number of data points is even, the median is interpolated by taking
the average of the two middle values:

@example
>>> median([1, 3, 5, 7])
4.0
@end example

This is suited for when your data is discrete, and you don’t mind that the
median may not be an actual data point.

If the data is ordinal (supports order operations) but not numeric (doesn’t
support addition), consider using @ref{2da0,,median_low()} or @ref{2da1,,median_high()}
instead.
@end deffn

@geindex median_low() (στη μονάδα statistics)
@anchor{library/statistics statistics median_low}@anchor{2da0}
@deffn {Συνάρτηση} statistics.median_low (data)

Return the low median of numeric data.  If `data' is empty,
@ref{2da7,,StatisticsError} is raised.  `data' can be a sequence or iterable.

The low median is always a member of the data set.  When the number of data
points is odd, the middle value is returned.  When it is even, the smaller of
the two middle values is returned.

@example
>>> median_low([1, 3, 5])
3
>>> median_low([1, 3, 5, 7])
3
@end example

Use the low median when your data are discrete and you prefer the median to
be an actual data point rather than interpolated.
@end deffn

@geindex median_high() (στη μονάδα statistics)
@anchor{library/statistics statistics median_high}@anchor{2da1}
@deffn {Συνάρτηση} statistics.median_high (data)

Return the high median of data.  If `data' is empty, @ref{2da7,,StatisticsError}
is raised.  `data' can be a sequence or iterable.

The high median is always a member of the data set.  When the number of data
points is odd, the middle value is returned.  When it is even, the larger of
the two middle values is returned.

@example
>>> median_high([1, 3, 5])
3
>>> median_high([1, 3, 5, 7])
5
@end example

Use the high median when your data are discrete and you prefer the median to
be an actual data point rather than interpolated.
@end deffn

@geindex median_grouped() (στη μονάδα statistics)
@anchor{library/statistics statistics median_grouped}@anchor{2da2}
@deffn {Συνάρτηση} 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{2d9f,,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
@code{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() (στη μονάδα statistics)
@anchor{library/statistics statistics mode}@anchor{e54}
@deffn {Συνάρτηση} statistics.mode (data)

Return the single most common data point from discrete or nominal `data'.
The mode (when it exists) is the most typical value and serves as a
measure of central location.

If there are multiple modes with the same frequency, returns the first one
encountered in the `data'.  If the smallest or largest of those is
desired instead, use @code{min(multimode(data))} or @code{max(multimode(data))}.
If the input `data' is empty, @ref{2da7,,StatisticsError} is raised.

@code{mode} assumes discrete data and returns a single value. This is the
standard treatment of the mode as commonly taught in schools:

@example
>>> mode([1, 1, 2, 3, 3, 3, 3, 4])
3
@end example

The mode is unique in that it is the only statistic in this package that
also applies to nominal (non-numeric) data:

@example
>>> mode(["red", "blue", "blue", "red", "green", "red", "red"])
'red'
@end example

Only hashable inputs are supported.  To handle type @ref{42b,,set},
consider casting to @ref{9d4,,frozenset}.  To handle type @ref{4d9,,list},
consider casting to @ref{1ce,,tuple}.  For mixed or nested inputs, consider
using this slower quadratic algorithm that only depends on equality tests:
@code{max(data, key=data.count)}.


Άλλαξε στην έκδοση 3.8: Now handles multimodal datasets by returning the first mode encountered.
Formerly, it raised @ref{2da7,,StatisticsError} when more than one mode was
found.

@end deffn

@geindex multimode() (στη μονάδα statistics)
@anchor{library/statistics statistics multimode}@anchor{dfa}
@deffn {Συνάρτηση} statistics.multimode (data)

Return a list of the most frequently occurring values in the order they
were first encountered in the `data'.  Will return more than one result if
there are multiple modes or an empty list if the `data' is empty:

@example
>>> multimode('aabbbbccddddeeffffgg')
['b', 'd', 'f']
>>> multimode('@w{'})
[]
@end example


Added in version 3.8.

@end deffn

@geindex pstdev() (στη μονάδα statistics)
@anchor{library/statistics statistics pstdev}@anchor{19c6}
@deffn {Συνάρτηση} statistics.pstdev (data, mu=None)

Return the population standard deviation (the square root of the population
variance).  See @ref{2da4,,pvariance()} for arguments and other details.

@example
>>> pstdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
0.986893273527251
@end example
@end deffn

@geindex pvariance() (στη μονάδα statistics)
@anchor{library/statistics statistics pvariance}@anchor{2da4}
@deffn {Συνάρτηση} statistics.pvariance (data, mu=None)

Return the population variance of `data', a non-empty sequence or iterable
of real-valued numbers.  Variance, or second moment about the mean, is a
measure of the variability (spread or dispersion) of data.  A large
variance indicates that the data is spread out; a small variance indicates
it is clustered closely around the mean.

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.

Use this function to calculate the variance from the entire population.  To
estimate the variance from a sample, the @ref{ac0,,variance()} function is usually
a better choice.

Raises @ref{2da7,,StatisticsError} if `data' is empty.

Examples:

@example
>>> data = [0.0, 0.25, 0.25, 1.25, 1.5, 1.75, 2.75, 3.25]
>>> pvariance(data)
1.25
@end example

If you have already calculated the mean of your data, you can pass it as the
optional second argument `mu' to avoid recalculation:

@example
>>> mu = mean(data)
>>> pvariance(data, mu)
1.25
@end example

Decimals and Fractions are supported:

@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 Σημείωση 
When called with the entire population, this gives the population variance
σ².  When called on a sample instead, this is the biased sample variance
s², also known as variance with N degrees of freedom.

If you somehow know the true population mean μ, you may use this
function to calculate the variance of a sample, giving the known
population mean as the second argument.  Provided the data points are a
random sample of the population, the result will be an unbiased estimate
of the population variance.
@end quotation
@end cartouche
@end deffn

@geindex stdev() (στη μονάδα statistics)
@anchor{library/statistics statistics stdev}@anchor{ac1}
@deffn {Συνάρτηση} statistics.stdev (data, xbar=None)

Return the sample standard deviation (the square root of the sample
variance).  See @ref{ac0,,variance()} for arguments and other details.

@example
>>> stdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
1.0810874155219827
@end example
@end deffn

@geindex variance() (στη μονάδα statistics)
@anchor{library/statistics statistics variance}@anchor{ac0}
@deffn {Συνάρτηση} statistics.variance (data, xbar=None)

Return the sample variance of `data', an iterable of at least two real-valued
numbers.  Variance, or second moment about the mean, is a measure of the
variability (spread or dispersion) of data.  A large variance indicates that
the data is spread out; a small variance indicates it is clustered closely
around the mean.

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.

Use this function when your data is a sample from a population. To calculate
the variance from the entire population, see @ref{2da4,,pvariance()}.

Raises @ref{2da7,,StatisticsError} if `data' has fewer than two values.

Examples:

@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

This function does not attempt to verify that you have passed the actual mean
as `xbar'.  Using arbitrary values for `xbar' can lead to invalid or
impossible results.

Decimal and Fraction values are supported:

@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 Σημείωση 
This is the sample variance s² with Bessel’s correction, also known as
variance with N-1 degrees of freedom.  Provided that the data points are
representative (e.g. independent and identically distributed), the result
should be an unbiased estimate of the true population variance.

If you somehow know the actual population mean μ you should pass it to the
@ref{2da4,,pvariance()} function as the `mu' parameter to get the variance of a
sample.
@end quotation
@end cartouche
@end deffn

@geindex quantiles() (στη μονάδα statistics)
@anchor{library/statistics statistics quantiles}@anchor{dfb}
@deffn {Συνάρτηση} statistics.quantiles (data, *, n=4, method='exclusive')

Divide `data' into `n' continuous intervals with equal probability.
Returns a list of @code{n - 1} cut points separating the intervals.

Set `n' to 4 for quartiles (the default).  Set `n' to 10 for deciles.  Set
`n' to 100 for percentiles which gives the 99 cuts points that separate
`data' into 100 equal sized groups.  Raises @ref{2da7,,StatisticsError} if `n'
is not least 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{2da7,,StatisticsError} if there is not at least one data point.

The cut points are linearly interpolated from the
two nearest data points.  For example, if a cut point falls one-third
of the distance between two sample values, @code{100} and @code{112}, the
cut-point will evaluate to @code{104}.

The `method' for computing quantiles can be varied depending on
whether the `data' includes or excludes the lowest and
highest possible values from the population.

The default `method' is «exclusive» and is used for data sampled from
a population that can have more extreme values than found in the
samples.  The portion of the population falling below the `i-th' of
`m' sorted data points is computed as @code{i / (m + 1)}.  Given nine
sample values, the method sorts them and assigns the following
percentiles: 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%.

Setting the `method' to «inclusive» is used for describing population
data or for samples that are known to include the most extreme values
from the population.  The minimum value in `data' is treated as the 0th
percentile and the maximum value is treated as the 100th percentile.
The portion of the population falling below the `i-th' of `m' sorted
data points is computed as @code{(i - 1) / (m - 1)}.  Given 11 sample
values, the method sorts them and assigns the following percentiles:
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


Added in version 3.8.



Άλλαξε στην έκδοση 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() (στη μονάδα statistics)
@anchor{library/statistics statistics covariance}@anchor{c09}
@deffn {Συνάρτηση} statistics.covariance (x, y, /)

Return the sample covariance of two sequence 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{2da7,,StatisticsError} is raised.

Examples:

@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


Added in version 3.10.

@end deffn

@geindex correlation() (στη μονάδα statistics)
@anchor{library/statistics statistics correlation}@anchor{8cc}
@deffn {Συνάρτηση} statistics.correlation (x, y, /, *, method='linear')

Return the Pearson's correlation coefficient@footnote{https://en.wikipedia.org/wiki/Pearson_correlation_coefficient}
for two sequence 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{2da7,,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


Added in version 3.10.



Άλλαξε στην έκδοση 3.12: Added support for Spearman’s rank correlation coefficient.

@end deffn

@geindex linear_regression() (στη μονάδα statistics)
@anchor{library/statistics statistics linear_regression}@anchor{c0a}
@deffn {Συνάρτηση} 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 sequences of the same length (no less than two), and
the independent variable `x' cannot be constant;
otherwise a @ref{2da7,,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{8cc,,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


Added in version 3.10.



Άλλαξε στην έκδοση 3.11: Added support for `proportional'.

@end deffn

@node Exceptions<3>,NormalDist objects,Function details,statistics — Mathematical statistics functions
@anchor{library/statistics exceptions}@anchor{2da8}
@subsubsection Exceptions


A single exception is defined:

@geindex StatisticsError
@anchor{library/statistics statistics StatisticsError}@anchor{2da7}
@deffn {Εξαίρεση} statistics.StatisticsError

Subclass of @ref{277,,ValueError} for statistics-related exceptions.
@end deffn

@node NormalDist objects,Examples and Recipes,Exceptions<3>,statistics — Mathematical statistics functions
@anchor{library/statistics normaldist-objects}@anchor{2da9}
@subsubsection @code{NormalDist} objects


@ref{dfc,,NormalDist} is a tool for creating and manipulating normal
distributions of a random variable@footnote{http://www.stat.yale.edu/Courses/1997-98/101/ranvar.htm}.  It is a
class that treats the mean and standard deviation of data
measurements as a single entity.

Normal distributions arise from the Central Limit Theorem@footnote{https://en.wikipedia.org/wiki/Central_limit_theorem} and have a wide range
of applications in statistics.

@geindex NormalDist (κλάση σε statistics)
@anchor{library/statistics statistics NormalDist}@anchor{dfc}
@deffn {Κλάση} statistics.NormalDist (mu=0.0, sigma=1.0)

Returns a new `NormalDist' object where `mu' represents the arithmetic mean@footnote{https://en.wikipedia.org/wiki/Arithmetic_mean} and `sigma'
represents the standard deviation@footnote{https://en.wikipedia.org/wiki/Standard_deviation}.

If `sigma' is negative, raises @ref{2da7,,StatisticsError}.

@geindex mean (ιδιότητα της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist mean}@anchor{2daa}
@deffn {Ιδιότητα} mean

A read-only property for the arithmetic mean@footnote{https://en.wikipedia.org/wiki/Arithmetic_mean} of a normal
distribution.
@end deffn

@geindex median (ιδιότητα της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist median}@anchor{2dab}
@deffn {Ιδιότητα} median

A read-only property for the median@footnote{https://en.wikipedia.org/wiki/Median} of a normal
distribution.
@end deffn

@geindex mode (ιδιότητα της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist mode}@anchor{2dac}
@deffn {Ιδιότητα} mode

A read-only property for the mode@footnote{https://en.wikipedia.org/wiki/Mode_(statistics)} of a normal
distribution.
@end deffn

@geindex stdev (ιδιότητα της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist stdev}@anchor{2dad}
@deffn {Ιδιότητα} stdev

A read-only property for the standard deviation@footnote{https://en.wikipedia.org/wiki/Standard_deviation} of a normal
distribution.
@end deffn

@geindex variance (ιδιότητα της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist variance}@anchor{2dae}
@deffn {Ιδιότητα} variance

A read-only property for the variance@footnote{https://en.wikipedia.org/wiki/Variance} of a normal
distribution. Equal to the square of the standard deviation.
@end deffn

@geindex from_samples() (μέθοδος κλάσης της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist from_samples}@anchor{2daf}
@deffn {Μέθοδος} classmethod from_samples (data)

Makes a normal distribution instance with `mu' and `sigma' parameters
estimated from the `data' using @ref{df8,,fmean()} and @ref{ac1,,stdev()}.

The `data' can be any @ref{15ce,,iterable} and should consist of values
that can be converted to type @ref{327,,float}.  If `data' does not
contain at least two elements, raises @ref{2da7,,StatisticsError} because it
takes at least one point to estimate a central value and at least two
points to estimate dispersion.
@end deffn

@geindex samples() (μέθοδος της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist samples}@anchor{2db0}
@deffn {Μέθοδος} samples (n, *, seed=None)

Generates `n' random samples for a given mean and standard deviation.
Returns a @ref{4d9,,list} of @ref{327,,float} values.

If `seed' is given, creates a new instance of the underlying random
number generator.  This is useful for creating reproducible results,
even in a multi-threading context.


Άλλαξε στην έκδοση 3.13.


Switched to a faster algorithm.  To reproduce samples from previous
versions, use @ref{1618,,random.seed()} and @ref{1dd1,,random.gauss()}.
@end deffn

@geindex pdf() (μέθοδος της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist pdf}@anchor{2db1}
@deffn {Μέθοδος} pdf (x)

Using a probability density function (pdf)@footnote{https://en.wikipedia.org/wiki/Probability_density_function}, compute
the relative likelihood that a random variable `X' will be near the
given value `x'.  Mathematically, it is the limit of the ratio @code{P(x <=
X < x+dx) / dx} as `dx' approaches zero.

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() (μέθοδος της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist cdf}@anchor{1a7b}
@deffn {Μέθοδος} cdf (x)

Using a cumulative distribution function (cdf)@footnote{https://en.wikipedia.org/wiki/Cumulative_distribution_function},
compute the probability that a random variable `X' will be less than or
equal to `x'.  Mathematically, it is written @code{P(X <= x)}.
@end deffn

@geindex inv_cdf() (μέθοδος της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist inv_cdf}@anchor{2db2}
@deffn {Μέθοδος} 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}.

Finds the value `x' of the random variable `X' such that the
probability of the variable being less than or equal to that value
equals the given probability `p'.
@end deffn

@geindex overlap() (μέθοδος της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist overlap}@anchor{2db3}
@deffn {Μέθοδος} overlap (other)

Measures the agreement between two normal probability distributions.
Returns a value between 0.0 and 1.0 giving the overlapping area for the two probability density functions@footnote{https://www.rasch.org/rmt/rmt101r.htm}.
@end deffn

@geindex quantiles() (μέθοδος της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist quantiles}@anchor{2db4}
@deffn {Μέθοδος} quantiles (n=4)

Divide the normal distribution into `n' continuous intervals with
equal probability.  Returns a list of (n - 1) cut points separating
the intervals.

Set `n' to 4 for quartiles (the default).  Set `n' to 10 for deciles.
Set `n' to 100 for percentiles which gives the 99 cuts points that
separate the normal distribution into 100 equal sized groups.
@end deffn

@geindex zscore() (μέθοδος της statistics.NormalDist)
@anchor{library/statistics statistics NormalDist zscore}@anchor{2db5}
@deffn {Μέθοδος} 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}.


Added in version 3.9.

@end deffn

Instances of @code{NormalDist} support addition, subtraction,
multiplication and division by a constant.  These operations
are used for translation and scaling.  For example:

@example
>>> temperature_february = NormalDist(5, 2.5)             # Celsius
>>> temperature_february * (9/5) + 32                     # Fahrenheit
NormalDist(mu=41.0, sigma=4.5)
@end example

Dividing a constant by an instance of @code{NormalDist} is not supported
because the result wouldn’t be normally distributed.

Since normal distributions arise from additive effects of independent
variables, it is possible to add and subtract two independent normally distributed random variables@footnote{https://en.wikipedia.org/wiki/Sum_of_normally_distributed_random_variables}
represented as instances of @code{NormalDist}.  For example:

@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


Added in version 3.8.

@end deffn

@node Examples and Recipes,,NormalDist objects,statistics — Mathematical statistics functions
@anchor{library/statistics examples-and-recipes}@anchor{2db6}
@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{2db7}
@subsubsection Classic probability problems


@ref{dfc,,NormalDist} readily solves classic probability problems.

For example, given historical data for SAT exams@footnote{https://nces.ed.gov/programs/digest/d17/tables/dt17_226.40.asp} showing
that scores are normally distributed with a mean of 1060 and a standard
deviation of 195, determine the percentage of students with test scores
between 1100 and 1200, after rounding to the nearest whole number:

@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

Find the quartiles@footnote{https://en.wikipedia.org/wiki/Quartile} and deciles@footnote{https://en.wikipedia.org/wiki/Decile} for the SAT scores:

@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{2db8}
@subsubsection Monte Carlo inputs for simulations


To estimate the distribution for a model that isn’t easy to solve
analytically, @ref{dfc,,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{2db9}
@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%.

For example, an open source conference has 750 attendees and two rooms with a
500 person capacity.  There is a talk about Python and another about Ruby.
In previous conferences, 65% of the attendees preferred to listen to Python
talks.  Assuming the population preferences haven’t changed, what is the
probability that the Python room will stay within its capacity limits?

@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{2dba}
@subsubsection Naive bayesian classifier


Normal distributions commonly arise in machine learning problems.

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.

We’re given a training dataset with measurements for eight people.  The
measurements are assumed to be normally distributed, so we summarize the data
with @ref{dfc,,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

Next, we encounter a new person whose feature measurements are known but whose
gender is unknown:

@example
>>> ht = 6.0        # height
>>> wt = 130        # weight
>>> fs = 8          # foot size
@end example

Starting with a 50% prior probability@footnote{https://en.wikipedia.org/wiki/Prior_probability} of being male or female,
we compute the posterior as the prior times the product of likelihoods for the
feature measurements given the gender:

@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

The final prediction goes to the largest posterior. This is known as the
maximum a posteriori@footnote{https://en.wikipedia.org/wiki/Maximum_a_posteriori_estimation} or 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;

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Functional Programming Modules,File and Directory Access,Αριθμητικά και Μαθηματικά Modules,The Python Standard Library
@anchor{library/functional doc}@anchor{2dbb}@anchor{library/functional functional-programming-modules}@anchor{2dbc}@anchor{library/functional translation-repo}@anchor{2dbd}
@section Functional Programming Modules


The modules described in this chapter provide functions and classes that support
a functional programming style, and general operations on callables.

The following modules are documented in this chapter:

@menu
* itertools — Functions creating iterators for efficient looping:: 
* functools — Higher-order functions and operations on callable objects:: 
* operator — Standard operators as functions:: 

@end menu

@node itertools — Functions creating iterators for efficient looping,functools — Higher-order functions and operations on callable objects,,Functional Programming Modules
@anchor{library/itertools doc}@anchor{2dbe}@anchor{library/itertools itertools-functions-creating-iterators-for-efficient-looping}@anchor{2dbf}@anchor{library/itertools module-itertools}@anchor{84}
@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


__________________________________________________________________


This module implements a number of @ref{6ce,,iterator} building blocks inspired
by constructs from APL, Haskell, and SML.  Each has been recast in a form
suitable for Python.

The module standardizes a core set of fast, memory efficient tools that are
useful by themselves or in combination.  Together, they form an «iterator
algebra» making it possible to construct specialized tools succinctly and
efficiently in pure Python.

For instance, SML provides a tabulation tool: @code{tabulate(f)} which produces a
sequence @code{f(0), f(1), ...}.  The same effect can be achieved in Python
by combining @ref{43e,,map()} and @ref{1628,,count()} to form @code{map(f, count())}.

`General iterators:'


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Iterator

@tab

Arguments

@tab

Results

@tab

Example

@item

@ref{dbf,,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{715,,batched()}

@tab

p, n

@tab

(p0, p1, …, p_n-1), …

@tab

@code{batched('ABCDEFG', n=3) → ABC DEF G}

@item

@ref{190,,chain()}

@tab

p, q, …

@tab

p0, p1, … plast, q0, q1, …

@tab

@code{chain('ABC', 'DEF') → A B C D E F}

@item

@ref{191,,chain.from_iterable()}

@tab

iterable

@tab

p0, p1, … plast, q0, q1, …

@tab

@code{chain.from_iterable(['ABC', 'DEF']) → A B C D E F}

@item

@ref{1627,,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{1628,,count()}

@tab

[start[, step]]

@tab

start, start+step, start+2*step, …

@tab

@code{count(10) → 10 11 12 13 14 ...}

@item

@ref{1a41,,cycle()}

@tab

p

@tab

p0, p1, … plast, p0, p1, …

@tab

@code{cycle('ABCD') → A B C D A B C D ...}

@item

@ref{2dc0,,dropwhile()}

@tab

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{27c7,,filterfalse()}

@tab

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{192a,,groupby()}

@tab

iterable[, key]

@tab

sub-iterators grouped by value of key(v)

@tab

@code{groupby(['A','B','DEF'], len) → (1, A B) (3, DEF)}

@item

@ref{f09,,islice()}

@tab

seq, [start,] stop [, step]

@tab

elements from seq[start:stop:step]

@tab

@code{islice('ABCDEFG', 2, None) → C D E F G}

@item

@ref{bee,,pairwise()}

@tab

iterable

@tab

(p[0], p[1]), (p[1], p[2])

@tab

@code{pairwise('ABCDEFG') → AB BC CD DE EF FG}

@item

@ref{1a81,,repeat()}

@tab

elem [,n]

@tab

elem, elem, elem, … endlessly or up to n times

@tab

@code{repeat(10, 3) → 10 10 10}

@item

@ref{1490,,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{2dc1,,takewhile()}

@tab

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{2dc2,,tee()}

@tab

it, n

@tab

it1, it2, … itn  splits one iterator into n

@tab

@code{tee('ABC', 2) → A B C, A B C}

@item

@ref{1643,,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


`Combinatoric iterators:'


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Iterator

@tab

Arguments

@tab

Results

@item

@ref{16b7,,product()}

@tab

p, q, … [repeat=1]

@tab

cartesian product, equivalent to a nested for-loop

@item

@ref{1961,,permutations()}

@tab

p[, r]

@tab

r-length tuples, all possible orderings, no repeated elements

@item

@ref{16b6,,combinations()}

@tab

p, r

@tab

r-length tuples, in sorted order, no repeated elements

@item

@ref{1626,,combinations_with_replacement()}

@tab

p, r

@tab

r-length tuples, in sorted order, with repeated elements

@end multitable



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Examples

@tab

Results

@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:: 
* Itertools Recipes:: 

@end menu

@node Itertool Functions,Itertools Recipes,,itertools — Functions creating iterators for efficient looping
@anchor{library/itertools itertool-functions}@anchor{2dc3}@anchor{library/itertools itertools-functions}@anchor{2dc4}
@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() (στη μονάδα itertools)
@anchor{library/itertools itertools accumulate}@anchor{dbf}
@deffn {Συνάρτηση} 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.

Roughly equivalent to:

@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{12b9,,min()}.
For a running maximum, set `function' to @ref{12ba,,max()}.
Or for a running product, set `function' to @ref{2dc5,,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

See @ref{153,,functools.reduce()} for a similar function that returns only the
final accumulated value.


Added in version 3.2.



Άλλαξε στην έκδοση 3.3: Added the optional `function' parameter.



Άλλαξε στην έκδοση 3.8: Added the optional `initial' parameter.

@end deffn

@geindex batched() (στη μονάδα itertools)
@anchor{library/itertools itertools batched}@anchor{715}
@deffn {Συνάρτηση} 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{277,,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

Roughly equivalent to:

@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


Added in version 3.12.



Άλλαξε στην έκδοση 3.13: Added the `strict' option.

@end deffn

@geindex chain() (στη μονάδα itertools)
@anchor{library/itertools itertools chain}@anchor{190}
@deffn {Συνάρτηση} 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() (μέθοδος κλάσης της itertools.chain)
@anchor{library/itertools itertools chain from_iterable}@anchor{191}
@deffn {Μέθοδος} classmethod chain.from_iterable (iterable)

Alternate constructor for @ref{190,,chain()}.  Gets chained inputs from a
single iterable argument that is evaluated lazily.  Roughly equivalent to:

@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() (στη μονάδα itertools)
@anchor{library/itertools itertools combinations}@anchor{16b6}
@deffn {Συνάρτηση} itertools.combinations (iterable, r)

Return `r' length subsequences of elements from the input `iterable'.

The output is a subsequence of @ref{16b7,,product()} keeping only entries that
are subsequences of the `iterable'.  The length of the output is given
by @ref{abd,,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.

Roughly equivalent to:

@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() (στη μονάδα itertools)
@anchor{library/itertools itertools combinations_with_replacement}@anchor{1626}
@deffn {Συνάρτηση} itertools.combinations_with_replacement (iterable, r)

Return `r' length subsequences of elements from the input `iterable'
allowing individual elements to be repeated more than once.

The output is a subsequence of @ref{16b7,,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.

Roughly equivalent to:

@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


Added in version 3.1.

@end deffn

@geindex compress() (στη μονάδα itertools)
@anchor{library/itertools itertools compress}@anchor{1627}
@deffn {Συνάρτηση} 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


Added in version 3.1.

@end deffn

@geindex count() (στη μονάδα itertools)
@anchor{library/itertools itertools count}@anchor{1628}
@deffn {Συνάρτηση} itertools.count (start=0, step=1)

Make an iterator that returns evenly spaced values beginning with
`start'. Can be used with @ref{43e,,map()} to generate consecutive data
points or with @ref{43f,,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())}.


Άλλαξε στην έκδοση 3.1: Added `step' argument and allowed non-integer arguments.

@end deffn

@geindex cycle() (στη μονάδα itertools)
@anchor{library/itertools itertools cycle}@anchor{1a41}
@deffn {Συνάρτηση} 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() (στη μονάδα itertools)
@anchor{library/itertools itertools dropwhile}@anchor{2dc0}
@deffn {Συνάρτηση} 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() (στη μονάδα itertools)
@anchor{library/itertools itertools filterfalse}@anchor{27c7}
@deffn {Συνάρτηση} 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() (στη μονάδα itertools)
@anchor{library/itertools itertools groupby}@anchor{192a}
@deffn {Συνάρτηση} itertools.groupby (iterable, key=None)

Make an iterator that returns consecutive keys and groups from the `iterable'.
The `key' is a function computing a key value for each element.  If not
specified or is @code{None}, `key' defaults to an identity function and returns
the element unchanged.  Generally, the iterable needs to already be sorted on
the same key function.

The operation of @code{groupby()} is similar to the @code{uniq} filter in Unix.  It
generates a break or new group every time the value of the key function changes
(which is why it is usually necessary to have sorted the data using the same key
function).  That behavior differs from SQL’s GROUP BY which aggregates common
elements regardless of their input order.

The returned group is itself an iterator that shares the underlying iterable
with @code{groupby()}.  Because the source is shared, when the @code{groupby()}
object is advanced, the previous group is no longer visible.  So, if that data
is needed later, it should be stored as a list:

@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

@code{groupby()} is roughly equivalent to:

@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() (στη μονάδα itertools)
@anchor{library/itertools itertools islice}@anchor{f09}
@deffn {Συνάρτηση} itertools.islice (iterable, stop)

@deffnx {Συνάρτηση} 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.

Roughly equivalent to:

@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() (στη μονάδα itertools)
@anchor{library/itertools itertools pairwise}@anchor{bee}
@deffn {Συνάρτηση} itertools.pairwise (iterable)

Return successive overlapping pairs taken from the input `iterable'.

The number of 2-tuples in the output iterator will be one fewer than the
number of inputs.  It will be empty if the input iterable has fewer than
two values.

Roughly equivalent to:

@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


Added in version 3.10.

@end deffn

@geindex permutations() (στη μονάδα itertools)
@anchor{library/itertools itertools permutations}@anchor{1961}
@deffn {Συνάρτηση} itertools.permutations (iterable, r=None)

Return successive `r' length permutations of elements@footnote{https://www.britannica.com/science/permutation} from the `iterable'.

If `r' is not specified or is @code{None}, then `r' defaults to the length
of the `iterable' and all possible full-length permutations
are generated.

The output is a subsequence of @ref{16b7,,product()} where entries with
repeated elements have been filtered out.  The length of the output is
given by @ref{abe,,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.

Roughly equivalent to:

@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() (στη μονάδα itertools)
@anchor{library/itertools itertools product}@anchor{16b7}
@deffn {Συνάρτηση} itertools.product (*iterables, repeat=1)

Cartesian product@footnote{https://en.wikipedia.org/wiki/Cartesian_product}
of the input iterables.

Roughly equivalent to nested for-loops in a generator expression. For example,
@code{product(A, B)} returns the same as @code{((x,y) for x in A for y in B)}.

The nested loops cycle like an odometer with the rightmost element advancing
on every iteration.  This pattern creates a lexicographic ordering so that if
the input’s iterables are sorted, the product tuples are emitted in sorted
order.

To compute the product of an iterable with itself, specify the number of
repetitions with the optional `repeat' keyword argument.  For example,
@code{product(A, repeat=4)} means the same as @code{product(A, A, A, A)}.

This function is roughly equivalent to the following code, except that the
actual implementation does not build up intermediate results in memory:

@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

Before @code{product()} runs, it completely consumes the input iterables,
keeping pools of values in memory to generate the products.  Accordingly,
it is only useful with finite inputs.
@end deffn

@geindex repeat() (στη μονάδα itertools)
@anchor{library/itertools itertools repeat}@anchor{1a81}
@deffn {Συνάρτηση} itertools.repeat (object[, times])

Make an iterator that returns `object' over and over again. Runs indefinitely
unless the `times' argument is specified.

Roughly equivalent to:

@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

A common use for `repeat' is to supply a stream of constant values to `map'
or `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() (στη μονάδα itertools)
@anchor{library/itertools itertools starmap}@anchor{1490}
@deffn {Συνάρτηση} itertools.starmap (function, iterable)

Make an iterator that computes the `function' using arguments obtained
from the `iterable'.  Used instead of @ref{43e,,map()} when argument
parameters have already been «pre-zipped» into tuples.

The difference between @ref{43e,,map()} and @code{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() (στη μονάδα itertools)
@anchor{library/itertools itertools takewhile}@anchor{2dc1}
@deffn {Συνάρτηση} 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() (στη μονάδα itertools)
@anchor{library/itertools itertools tee}@anchor{2dc2}
@deffn {Συνάρτηση} itertools.tee (iterable, n=2)

Return `n' independent iterators from a single iterable.

Roughly equivalent to:

@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 @code{tee()} call.  This «flattening step»
allows nested @code{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{30d,,RuntimeError} may be
raised when simultaneously using iterators returned by the same @code{tee()}
call, even if the original `iterable' is threadsafe.

This itertool may require significant auxiliary storage (depending on how
much temporary data needs to be stored). In general, if one iterator uses
most or all of the data before another iterator starts, it is faster to use
@ref{4d9,,list()} instead of @code{tee()}.
@end deffn

@geindex zip_longest() (στη μονάδα itertools)
@anchor{library/itertools itertools zip_longest}@anchor{1643}
@deffn {Συνάρτηση} 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.

Roughly equivalent to:

@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 @code{zip_longest()}
function should be wrapped with something that limits the number of calls
(for example @ref{f09,,islice()} or @ref{2dc1,,takewhile()}).
@end deffn

@node Itertools Recipes,,Itertool Functions,itertools — Functions creating iterators for efficient looping
@anchor{library/itertools id1}@anchor{2dc6}@anchor{library/itertools itertools-recipes}@anchor{1603}
@subsubsection Itertools Recipes


This section shows recipes for creating an extended toolset using the existing
itertools as building blocks.

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{a3,,operator} and @ref{1e,,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{derangements()}, 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{1409,,generators} which incur interpreter overhead.

@example
from itertools import (accumulate, batched, chain, combinations, compress,
     count, cycle, filterfalse, groupby, islice, permutations, product,
     repeat, starmap, tee, zip_longest)
from collections import Counter, deque
from contextlib import suppress
from functools import reduce
from heapq import heappush, heappushpop, heappush_max, heappushpop_max
from math import comb, isqrt, prod, sumprod
from operator import getitem, is_not, itemgetter, mul, neg, truediv


# ==== Basic one liners ====

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 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


# ==== Data pipelines ====

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', 3) → ABC BCD CDE DEF EFG
    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 derangements(iterable, r=None):
    "Produce r length permutations without fixed points."
    # derangements('ABCD') → BADC BCDA BDAC CADB CDAB CDBA DABC DCAB DCBA
    # Algorithm credited to Stefan Pochmann
    seq = tuple(iterable)
    pos = tuple(range(len(seq)))
    have_moved = map(map, repeat(is_not), repeat(pos), permutations(pos, r=r))
    valid_derangements = map(all, have_moved)
    return compress(permutations(seq, r=r), valid_derangements)

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()


# ==== Mathematical operations ====

def multinomial(*counts):
    "Number of distinct arrangements of a multiset."
    # Counter('abracadabra').values() → 5 2 2 1 1
    # multinomial(5, 2, 2, 1, 1) → 83160
    return prod(map(comb, accumulate(counts), counts))

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))


# ==== Matrix operations ====

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)


# ==== Polynomial arithmetic ====

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))


# ==== Number theory ====

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


# ==== Running statistics ====

def running_mean(iterable):
    "Average of values seen so far."
    # running_mean([37, 33, 38, 28]) → 37 35 36 34
    return map(truediv, accumulate(iterable), count(1))

def running_min(iterable):
    "Smallest of values seen so far."
    # running_min([37, 33, 38, 28]) → 37 33 33 28
    return accumulate(iterable, func=min)

def running_max(iterable):
    "Largest of values seen so far."
    # running_max([37, 33, 38, 28]) → 37 37 38 38
    return accumulate(iterable, func=max)

def running_median(iterable):
    "Median of values seen so far."
    # running_median([37, 33, 38, 28]) → 37 35 37 35
    read = iter(iterable).__next__
    lo = []  # max-heap
    hi = []  # min-heap the same size as or one smaller than lo
    with suppress(StopIteration):
        while True:
            heappush_max(lo, heappushpop(hi, read()))
            yield lo[0]
            heappush(hi, heappushpop_max(lo, read()))
            yield (lo[0] + hi[0]) / 2

def running_statistics(iterable):
    "Aggregate statistics for values seen so far."
    # Generate tuples:  (size, minimum, median, maximum, mean)
    t0, t1, t2, t3 = tee(iterable, 4)
    return zip(
        count(1),
        running_min(t0),
        running_median(t1),
        running_max(t2),
        running_mean(t3),
    )
@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 >>> 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 >>> ' '.join(map(''.join, derangements('ABCD')))
@c 'BADC BCDA BDAC CADB CDAB CDBA DABC DCAB DCBA'
@c >>> ' '.join(map(''.join, derangements('ABCD', 3)))
@c 'BAD BCA BCD BDA CAB CAD CDA CDB DAB DCA DCB'
@c >>> ' '.join(map(''.join, derangements('ABCD', 2)))
@c 'BA BC BD CA CD DA DC'
@c >>> ' '.join(map(''.join, derangements('ABCD', 1)))
@c 'B C D'
@c >>> ' '.join(map(''.join, derangements('ABCD', 0)))
@c ''
@c >>> # Compare number of derangements to https://oeis.org/A000166
@c >>> [len(list(derangements(range(n)))) for n in range(10)]
@c [1, 0, 1, 2, 9, 44, 265, 1854, 14833, 133496]
@c >>> # Verify that identical objects are treated as unique by position
@c >>> identical = 'X'
@c >>> distinct = 'x'
@c >>> seq1 = ('A', identical, 'B', identical)
@c >>> result1 = ' '.join(map(''.join, derangements(seq1)))
@c >>> result1
@c 'XAXB XBXA XXAB BAXX BXAX BXXA XAXB XBAX XBXA'
@c >>> seq2 = ('A', identical, 'B', distinct)
@c >>> result2 = ' '.join(map(''.join, derangements(seq2)))
@c >>> result2
@c 'XAxB XBxA XxAB BAxX BxAX BxXA xAXB xBAX xBXA'
@c >>> result1 == result2
@c False
@c >>> result1.casefold() == result2.casefold()
@c True
@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 
@c >>> multinomial(5, 2, 2, 1, 1)
@c 83160
@c >>> word = 'coffee'
@c >>> multinomial(*Counter(word).values()) == len(set(permutations(word)))
@c True
@c 
@c 
@c >>> list(running_mean([8.5, 9.5, 7.5, 6.5]))
@c [8.5, 9.0, 8.5, 8.0]
@c >>> list(running_mean([37, 33, 38, 28]))
@c [37.0, 35.0, 36.0, 34.0]
@c 
@c 
@c >>> list(running_min([37, 33, 38, 28]))
@c [37, 33, 33, 28]
@c 
@c 
@c >>> list(running_max([37, 33, 38, 28]))
@c [37, 37, 38, 38]
@c 
@c 
@c >>> list(running_median([37, 33, 38, 28]))
@c [37, 35.0, 37, 35.0]
@c 
@c 
@c >>> list(running_statistics([37, 33, 38, 28]))
@c [(1, 37, 37, 37, 37.0), (2, 33, 35.0, 37, 35.0), (3, 33, 37, 38, 36.0), (4, 28, 35.0, 38, 34.0)]

@c # Old recipes and their tests which are guaranteed to continue to work.
@c 
@c def tabulate(function, start=0):
@c     "Return function(0), function(1), ..."
@c     return map(function, count(start))
@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 >>> list(islice(tabulate(lambda x: 2*x), 4))
@c [0, 2, 4, 6]
@c 
@c 
@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]

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node functools — Higher-order functions and operations on callable objects,operator — Standard operators as functions,itertools — Functions creating iterators for efficient looping,Functional Programming Modules
@anchor{library/functools doc}@anchor{2dc7}@anchor{library/functools functools-higher-order-functions-and-operations-on-callable-objects}@anchor{2dc8}@anchor{library/functools module-functools}@anchor{62}@anchor{library/functools translation-repo}@anchor{2dc9}
@subsection @code{functools} — Higher-order functions and operations on callable objects


@geindex module; functools

`Source code:' Lib/functools.py@footnote{https://github.com/python/cpython/tree/main/Lib/functools.py}

@c import functools
@c from functools import *


__________________________________________________________________


The @code{functools} module is for higher-order functions: functions that act on
or return other functions. In general, any callable object can be treated as a
function for the purposes of this module.

The @code{functools} module defines the following functions:

@geindex cache() (στη μονάδα functools)
@anchor{library/functools functools cache}@anchor{1a08}
@deffn {Συνάρτηση} @@functools.cache (user_function)

Simple lightweight unbounded function cache.  Sometimes called
"memoize"@footnote{https://en.wikipedia.org/wiki/Memoization}.

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{db3,,lru_cache()} with a size limit.

For example:

@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)    # no new calls, just returns the cached result
120
>>> factorial(12)   # two new recursive calls, factorial(10) is 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.

Call-once behavior is not guaranteed because locks are not held during the
function call. Potentially another call with the same arguments could
occur while the first call is still running.


Added in version 3.9.

@end deffn

@geindex cached_property() (στη μονάδα functools)
@anchor{library/functools functools cached_property}@anchor{94e}
@deffn {Συνάρτηση} @@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{6bb,,property()}, with the addition of caching. Useful for expensive
computed properties of instances that are otherwise effectively immutable.

Example:

@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 @code{cached_property()} are somewhat different from
@ref{6bb,,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 @code{cached_property()} can also be achieved by
stacking @ref{6bb,,property()} on top of @ref{db3,,lru_cache()}. See
@ref{2dca,,Πώς μπορώ να αποθηκεύσω τις κλήσεις μεθόδου στην κρυφή μνήμη;} for more details on how this differs from @code{cached_property()}.


Added in version 3.8.



Άλλαξε στην έκδοση 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() (στη μονάδα functools)
@anchor{library/functools functools cmp_to_key}@anchor{1583}
@deffn {Συνάρτηση} functools.cmp_to_key (func)

Transform an old-style comparison function to a @ref{11ba,,key function}.  Used
with tools that accept key functions (such as @ref{f8c,,sorted()}, @ref{12b9,,min()},
@ref{12ba,,max()}, @ref{2bb8,,heapq.nlargest()}, @ref{2bb9,,heapq.nsmallest()},
@ref{192a,,itertools.groupby()}).  This function is primarily used as a transition
tool for programs being converted from Python 2 which supported the use of
comparison functions.

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.

Example:

@example
sorted(iterable, key=cmp_to_key(locale.strcoll))  # locale-aware sort order
@end example

For sorting examples and a brief sorting tutorial, see @ref{27d9,,Sorting Techniques}.


Added in version 3.2.

@end deffn

@geindex lru_cache() (στη μονάδα functools)
@anchor{library/functools functools lru_cache}@anchor{db3}
@deffn {Συνάρτηση} @@functools.lru_cache (user_function)

@deffnx {Συνάρτηση} @@functools.lru_cache (maxsize=128, typed=False)

Decorator to wrap a function with a memoizing callable that saves up to the
`maxsize' most recent calls.  It can save time when an expensive or I/O bound
function is periodically called with the same 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{183,,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.

If `user_function' is specified, it must be a callable. This allows the
`lru_cache' decorator to be applied directly to a user function, leaving
the `maxsize' at its default value of 128:

@example
@@lru_cache
def count_vowels(word):
    return sum(word.count(vowel) for vowel in 'AEIOUaeiou')
@end example

If `maxsize' is set to @code{None}, the LRU feature is disabled and the cache can
grow without bound.

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 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{188,,dict} showing the values for `maxsize'
and `typed'.  This is for information purposes only.  Mutating the values
has no effect.

@geindex cache_info() (μέθοδος της functools.lru_cache)
@anchor{library/functools functools lru_cache cache_info}@anchor{2dcb}
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{a3d,,named tuple} showing `hits', `misses',
`maxsize' and `currsize'.

@geindex cache_clear() (μέθοδος της functools.lru_cache)
@anchor{library/functools functools lru_cache cache_clear}@anchor{2dcc}
The decorator also provides a @code{cache_clear()} function for clearing or
invalidating the cache.

The original underlying function is accessible through the
@code{__wrapped__} attribute.  This is useful for introspection, for
bypassing the cache, or for rewrapping the function with a different cache.

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{2dca,,Πώς μπορώ να αποθηκεύσω τις κλήσεις μεθόδου στην κρυφή μνήμη;}

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().

Example of an LRU cache for static web content:

@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

Example of efficiently computing
Fibonacci numbers@footnote{https://en.wikipedia.org/wiki/Fibonacci_number}
using a cache to implement a
dynamic programming@footnote{https://en.wikipedia.org/wiki/Dynamic_programming}
technique:

@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


Added in version 3.2.



Άλλαξε στην έκδοση 3.3: Added the `typed' option.



Άλλαξε στην έκδοση 3.8: Added the `user_function' option.



Άλλαξε στην έκδοση 3.9: Added the function @code{cache_parameters()}

@end deffn

@geindex total_ordering() (στη μονάδα functools)
@anchor{library/functools functools total_ordering}@anchor{12ed}
@deffn {Συνάρτηση} @@functools.total_ordering

Given a class defining one or more rich comparison ordering methods, this
class decorator supplies the rest.  This simplifies the effort involved
in specifying all of the possible rich comparison operations:

The class must define one of @ref{1645,,__lt__()}, @ref{16af,,__le__()},
@ref{16b0,,__gt__()}, or @ref{16b1,,__ge__()}.
In addition, the class should supply an @ref{ec0,,__eq__()} method.

For example:

@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 Σημείωση 
While this decorator makes it easy to create well behaved totally
ordered types, it `does' come at the cost of slower execution and
more complex stack traces for the derived comparison methods. If
performance benchmarking indicates this is a bottleneck for a given
application, implementing all six rich comparison methods instead is
likely to provide an easy speed boost.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
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


Added in version 3.2.



Άλλαξε στην έκδοση 3.4: Returning @code{NotImplemented} from the underlying comparison function for
unrecognised types is now supported.

@end deffn

@geindex Placeholder (στη μονάδα functools)
@anchor{library/functools functools Placeholder}@anchor{4a5}
@deffn {Δεδομένα} functools.Placeholder

A singleton object used as a sentinel to reserve a place
for positional arguments when calling @ref{4a6,,partial()}
and @ref{4a7,,partialmethod()}.


Added in version 3.14.

@end deffn

@geindex partial() (στη μονάδα functools)
@anchor{library/functools functools partial}@anchor{4a6}
@deffn {Συνάρτηση} functools.partial (func, /, *args, **keywords)

Return a new @ref{4a8,,partial object} which when called
will behave like `func' called with the positional arguments `args'
and keyword arguments `keywords'. If more arguments are supplied to the
call, they are appended to `args'. If additional keyword arguments are
supplied, they extend and override `keywords'.
Roughly equivalent to:

@example
def partial(func, /, *args, **keywords):
    def newfunc(*more_args, **more_keywords):
        return func(*args, *more_args, **(keywords | more_keywords))
    newfunc.func = func
    newfunc.args = args
    newfunc.keywords = keywords
    return newfunc
@end example

The @code{partial()} function is used for partial function application which «freezes»
some portion of a function’s arguments and/or keywords resulting in a new object
with a simplified signature.  For example, @code{partial()} can be used to create
a callable that behaves like the @ref{326,,int()} function where the `base' argument
defaults to @code{2}:

@example
>>> basetwo = partial(int, base=2)
>>> basetwo.__doc__ = 'Convert base 2 string to an int.'
>>> basetwo('10010')
18
@end example

If @ref{4a5,,Placeholder} sentinels are present in `args', they will be filled first
when @code{partial()} is called. This makes it possible to pre-fill any positional
argument with a call to @code{partial()}; without @code{Placeholder},
only the chosen number of leading positional arguments can be pre-filled.

If any @code{Placeholder} sentinels are present, all must be filled at call time:

@example
>>> say_to_world = partial(print, Placeholder, Placeholder, "world!")
>>> say_to_world('Hello', 'dear')
Hello dear world!
@end example

Calling @code{say_to_world('Hello')} raises a @ref{291,,TypeError}, because
only one positional argument is provided, but there are two placeholders
that must be filled in.

If @code{partial()} is applied to an existing @code{partial()} object,
@code{Placeholder} sentinels of the input object are filled in with
new positional arguments.
A placeholder can be retained by inserting a new
@code{Placeholder} sentinel to the place held by a previous @code{Placeholder}:

@example
>>> from functools import partial, Placeholder as _
>>> remove = partial(str.replace, _, _, '@w{'})
>>> message = 'Hello, dear dear world!'
>>> remove(message, ' dear')
'Hello, world!'
>>> remove_dear = partial(remove, _, ' dear')
>>> remove_dear(message)
'Hello, world!'
>>> remove_first_dear = partial(remove_dear, _, 1)
>>> remove_first_dear(message)
'Hello, dear world!'
@end example

@code{Placeholder} cannot be passed to @code{partial()} as a keyword argument.


Άλλαξε στην έκδοση 3.14: Added support for @ref{4a5,,Placeholder} in positional arguments.

@end deffn

@geindex partialmethod (κλάση σε functools)
@anchor{library/functools functools partialmethod}@anchor{4a7}
@deffn {Κλάση} functools.partialmethod (func, /, *args, **keywords)

Return a new @code{partialmethod} descriptor which behaves
like @ref{4a6,,partial} except that it is designed to be used as a method
definition rather than being directly callable.

`func' must be a @ref{21f,,descriptor} or a callable (objects which are both,
like normal functions, are handled as descriptors).

When `func' is a descriptor (such as a normal Python function,
@ref{69a,,classmethod()}, @ref{666,,staticmethod()}, @ref{1433,,abstractmethod()} or
another instance of @code{partialmethod}), calls to @code{__get__} are
delegated to the underlying descriptor, and an appropriate
@ref{4a8,,partial object} returned as the result.

When `func' is a non-descriptor callable, an appropriate bound method is
created dynamically. This behaves like a normal Python function when
used as a method: the `self' argument will be inserted as the first
positional argument, even before the `args' and `keywords' supplied to
the @code{partialmethod} constructor.

Example:

@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


Added in version 3.4.

@end deffn

@geindex reduce() (στη μονάδα functools)
@anchor{library/functools functools reduce}@anchor{153}
@deffn {Συνάρτηση} 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.

Roughly equivalent to:

@example
initial_missing = sentinel('initial_missing')

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

See @ref{dbf,,itertools.accumulate()} for an iterator that yields all intermediate
values.


Άλλαξε στην έκδοση 3.14: `initial' is now supported as a keyword argument.

@end deffn

@geindex singledispatch() (στη μονάδα functools)
@anchor{library/functools functools singledispatch}@anchor{a2a}
@deffn {Συνάρτηση} @@functools.singledispatch

Transform a function into a @ref{db5,,single-dispatch} @ref{db4,,generic function}.

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

@geindex register() (μέθοδος της functools.singledispatch)
@anchor{library/functools functools singledispatch register}@anchor{2dcd}
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{341,,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

For code which doesn’t use type annotations, the appropriate type
argument can be passed explicitly to the decorator itself:

@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 Σημείωση 
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{2dce,,lambdas} and pre-existing functions,
the @ref{2dcd,,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 @ref{2dcd,,register()} attribute returns the undecorated function. This
enables decorator stacking, @ref{ab,,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

When called, the generic function dispatches on the type of the first
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{e4d,,object} type, which means it is used if no better
implementation is found.

If an implementation is registered to an @ref{155f,,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

To access all registered implementations, use the read-only @code{registry}
attribute:

@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


Added in version 3.4.



Άλλαξε στην έκδοση 3.7: The @ref{2dcd,,register()} attribute now supports using type annotations.



Άλλαξε στην έκδοση 3.11: The @ref{2dcd,,register()} attribute now supports
@ref{341,,typing.Union} as a type annotation.

@end deffn

@geindex singledispatchmethod (κλάση σε functools)
@anchor{library/functools functools singledispatchmethod}@anchor{21e}
@deffn {Κλάση} functools.singledispatchmethod (func)

Transform a method into a @ref{db5,,single-dispatch} @ref{db4,,generic function}.

To define a generic method, decorate it with the @code{@@singledispatchmethod}
decorator. When defining a method 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{69a,,@@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{666,,@@staticmethod}, @ref{1433,,@@~abc.abstractmethod}, and others.


Added in version 3.8.



Άλλαξε στην έκδοση 3.15: Added support of non-@ref{21f,,descriptor} callables.

@end deffn

@geindex update_wrapper() (στη μονάδα functools)
@anchor{library/functools functools update_wrapper}@anchor{13cb}
@deffn {Συνάρτηση} 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{253b,,__module__}, @ref{1679,,__name__},
@ref{253a,,__qualname__}, @ref{1581,,__annotations__},
@ref{253e,,__type_params__}, and @ref{1582,,__doc__}, the
documentation string) and @code{WRAPPER_UPDATES} (which updates the wrapper
function’s @ref{1677,,__dict__}, i.e. the instance dictionary).

To allow access to the original function for introspection and other purposes
(e.g. bypassing a caching decorator such as @ref{db3,,lru_cache()}), this function
automatically adds a @code{__wrapped__} attribute to the wrapper that refers to
the function being wrapped.

The main intended use for this function is in @ref{b18,,decorator} functions which
wrap the decorated function and return the wrapper. If the wrapper function is
not updated, the metadata of the returned function will reflect the wrapper
definition rather than the original function definition, which is typically less
than helpful.

@code{update_wrapper()} may be used with callables other than functions. Any
attributes named in `assigned' or `updated' that are missing from the object
being wrapped are ignored (i.e. this function will not attempt to set them
on the wrapper function). @ref{1a9,,AttributeError} is still raised if the
wrapper function itself is missing any attributes named in `updated'.


Άλλαξε στην έκδοση 3.2: The @code{__wrapped__} attribute is now automatically added.
The @ref{1581,,__annotations__} attribute is now copied by default.
Missing attributes no longer trigger an @ref{1a9,,AttributeError}.



Άλλαξε στην έκδοση 3.4: The @code{__wrapped__} attribute now always refers to the wrapped
function, even if that function defined a @code{__wrapped__} attribute.
(see bpo-17482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17482})



Άλλαξε στην έκδοση 3.12: The @ref{253e,,__type_params__} attribute is now copied by default.

@end deffn

@geindex wraps() (στη μονάδα functools)
@anchor{library/functools functools wraps}@anchor{1307}
@deffn {Συνάρτηση} @@functools.wraps (wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

This is a convenience function for invoking @ref{13cb,,update_wrapper()} as a
function decorator when defining a wrapper function.  It is equivalent to
@code{partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)}.
For example:

@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

Without the use of this decorator factory, the name of the example function
would have been @code{'wrapper'}, and the docstring of the original @code{example()}
would have been lost.
@end deffn

@menu
* partial Objects:: 

@end menu

@node partial Objects,,,functools — Higher-order functions and operations on callable objects
@anchor{library/functools id1}@anchor{2dcf}@anchor{library/functools partial-objects}@anchor{4a8}
@subsubsection @code{partial} Objects


@ref{4a6,,partial} objects are callable objects created by @ref{4a6,,partial()}. They
have three read-only attributes:

@geindex func (ιδιότητα της functools.partial)
@anchor{library/functools functools partial func}@anchor{2dd0}
@deffn {Ιδιότητα} partial.func

A callable object or function.  Calls to the @ref{4a6,,partial} object will be
forwarded to @ref{2dd0,,func} with new arguments and keywords.
@end deffn

@geindex args (ιδιότητα της functools.partial)
@anchor{library/functools functools partial args}@anchor{2dd1}
@deffn {Ιδιότητα} partial.args

The leftmost positional arguments that will be prepended to the positional
arguments provided to a @ref{4a6,,partial} object call.
@end deffn

@geindex keywords (ιδιότητα της functools.partial)
@anchor{library/functools functools partial keywords}@anchor{2dd2}
@deffn {Ιδιότητα} partial.keywords

The keyword arguments that will be supplied when the @ref{4a6,,partial} object is
called.
@end deffn

@ref{4a6,,partial} objects are like @ref{79b,,function objects} in that they are
callable, weak referenceable, and can have attributes.  There are some important
differences.  For instance, the @ref{140e,,__name__} and @ref{cf4,,__doc__} attributes
are not created automatically.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node operator — Standard operators as functions,,functools — Higher-order functions and operations on callable objects,Functional Programming Modules
@anchor{library/operator doc}@anchor{2dd3}@anchor{library/operator module-operator}@anchor{a3}@anchor{library/operator operator-standard-operators-as-functions}@anchor{2dd4}@anchor{library/operator translation-repo}@anchor{2dd5}
@subsection @code{operator} — Standard operators as functions


@geindex module; operator

`Source code:' Lib/operator.py@footnote{https://github.com/python/cpython/tree/main/Lib/operator.py}

@c import operator
@c from operator import itemgetter, iadd


__________________________________________________________________


The @code{operator} module exports a set of efficient functions corresponding to
the intrinsic operators of Python.  For example, @code{operator.add(x, y)} is
equivalent to the expression @code{x+y}. Many function names are those used for
special methods, without the double underscores.  For backward compatibility,
many of these have a variant with the double underscores kept. The variants
without the double underscores are preferred for clarity.

The functions fall into categories that perform object comparisons, logical
operations, mathematical operations and sequence operations.

The object comparison functions are useful for all objects, and are named after
the rich comparison operators they support:

@geindex lt() (στη μονάδα operator)
@geindex le() (στη μονάδα operator)
@geindex eq() (στη μονάδα operator)
@geindex ne() (στη μονάδα operator)
@geindex ge() (στη μονάδα operator)
@geindex gt() (στη μονάδα operator)
@geindex __lt__() (στη μονάδα operator)
@geindex __le__() (στη μονάδα operator)
@geindex __eq__() (στη μονάδα operator)
@geindex __ne__() (στη μονάδα operator)
@geindex __ge__() (στη μονάδα operator)
@geindex __gt__() (στη μονάδα operator)
@anchor{library/operator operator lt}@anchor{2dd6}
@deffn {Συνάρτηση} operator.lt (a, b)
@anchor{library/operator operator le}@anchor{2dd7}
@deffnx {Συνάρτηση} operator.le (a, b)
@anchor{library/operator operator eq}@anchor{2dd8}
@deffnx {Συνάρτηση} operator.eq (a, b)
@anchor{library/operator operator ne}@anchor{2dd9}
@deffnx {Συνάρτηση} operator.ne (a, b)
@anchor{library/operator operator ge}@anchor{2dda}
@deffnx {Συνάρτηση} operator.ge (a, b)
@anchor{library/operator operator gt}@anchor{2ddb}
@deffnx {Συνάρτηση} operator.gt (a, b)
@anchor{library/operator operator __lt__}@anchor{2ddc}
@deffnx {Συνάρτηση} operator.__lt__ (a, b)
@anchor{library/operator operator __le__}@anchor{2ddd}
@deffnx {Συνάρτηση} operator.__le__ (a, b)
@anchor{library/operator operator __eq__}@anchor{2dde}
@deffnx {Συνάρτηση} operator.__eq__ (a, b)
@anchor{library/operator operator __ne__}@anchor{2ddf}
@deffnx {Συνάρτηση} operator.__ne__ (a, b)
@anchor{library/operator operator __ge__}@anchor{2de0}
@deffnx {Συνάρτηση} operator.__ge__ (a, b)
@anchor{library/operator operator __gt__}@anchor{2de1}
@deffnx {Συνάρτηση} operator.__gt__ (a, b)

Perform «rich comparisons» between `a' and `b'. Specifically, @code{lt(a, b)} is
equivalent to @code{a < b}, @code{le(a, b)} is equivalent to @code{a <= b}, @code{eq(a,
b)} is equivalent to @code{a == b}, @code{ne(a, b)} is equivalent to @code{a != b},
@code{gt(a, b)} is equivalent to @code{a > b} and @code{ge(a, b)} is equivalent to @code{a
>= b}.  Note that these functions can return any value, which may
or may not be interpretable as a Boolean value.  See
@ref{26c7,,Comparisons} for more information about rich comparisons.
@end deffn

The logical operations are also generally applicable to all objects, and support
truth tests, identity tests, and boolean operations:

@geindex not_() (στη μονάδα operator)
@geindex __not__() (στη μονάδα operator)
@anchor{library/operator operator not_}@anchor{2de2}
@deffn {Συνάρτηση} operator.not_ (obj)
@anchor{library/operator operator __not__}@anchor{2de3}
@deffnx {Συνάρτηση} operator.__not__ (obj)

Return the outcome of @ref{26d1,,not} `obj'.  (Note that there is no
@code{__not__()} method for object instances; only the interpreter core defines
this operation.  The result is affected by the @ref{167a,,__bool__()} and
@ref{1989,,__len__()} methods.)
@end deffn

@geindex truth() (στη μονάδα operator)
@anchor{library/operator operator truth}@anchor{2de4}
@deffn {Συνάρτηση} operator.truth (obj)

Return @ref{fcc,,True} if `obj' is true, and @ref{ef5,,False} otherwise.  This is
equivalent to using the @ref{5ef,,bool} constructor.
@end deffn

@geindex is_() (στη μονάδα operator)
@anchor{library/operator operator is_}@anchor{2de5}
@deffn {Συνάρτηση} operator.is_ (a, b)

Return @code{a is b}.  Tests object identity.
@end deffn

@geindex is_not() (στη μονάδα operator)
@anchor{library/operator operator is_not}@anchor{2de6}
@deffn {Συνάρτηση} operator.is_not (a, b)

Return @code{a is not b}.  Tests object identity.
@end deffn

@geindex is_none() (στη μονάδα operator)
@anchor{library/operator operator is_none}@anchor{4e1}
@deffn {Συνάρτηση} operator.is_none (a)

Return @code{a is None}.  Tests object identity.


Added in version 3.14.

@end deffn

@geindex is_not_none() (στη μονάδα operator)
@anchor{library/operator operator is_not_none}@anchor{4e2}
@deffn {Συνάρτηση} operator.is_not_none (a)

Return @code{a is not None}.  Tests object identity.


Added in version 3.14.

@end deffn

The mathematical and bitwise operations are the most numerous:

@geindex abs() (στη μονάδα operator)
@geindex __abs__() (στη μονάδα operator)
@anchor{library/operator operator abs}@anchor{2de7}
@deffn {Συνάρτηση} operator.abs (obj)
@anchor{library/operator operator __abs__}@anchor{2de8}
@deffnx {Συνάρτηση} operator.__abs__ (obj)

Return the absolute value of `obj'.
@end deffn

@geindex add() (στη μονάδα operator)
@geindex __add__() (στη μονάδα operator)
@anchor{library/operator operator add}@anchor{2de9}
@deffn {Συνάρτηση} operator.add (a, b)
@anchor{library/operator operator __add__}@anchor{2dea}
@deffnx {Συνάρτηση} operator.__add__ (a, b)

Return @code{a + b}, for `a' and `b' numbers.
@end deffn

@geindex and_() (στη μονάδα operator)
@geindex __and__() (στη μονάδα operator)
@anchor{library/operator operator and_}@anchor{2deb}
@deffn {Συνάρτηση} operator.and_ (a, b)
@anchor{library/operator operator __and__}@anchor{2dec}
@deffnx {Συνάρτηση} operator.__and__ (a, b)

Return the bitwise and of `a' and `b'.
@end deffn

@geindex floordiv() (στη μονάδα operator)
@geindex __floordiv__() (στη μονάδα operator)
@anchor{library/operator operator floordiv}@anchor{2ded}
@deffn {Συνάρτηση} operator.floordiv (a, b)
@anchor{library/operator operator __floordiv__}@anchor{2dee}
@deffnx {Συνάρτηση} operator.__floordiv__ (a, b)

Return @code{a // b}.
@end deffn

@geindex index() (στη μονάδα operator)
@geindex __index__() (στη μονάδα operator)
@anchor{library/operator operator index}@anchor{1ec8}
@deffn {Συνάρτηση} operator.index (a)
@anchor{library/operator operator __index__}@anchor{2def}
@deffnx {Συνάρτηση} operator.__index__ (a)

Return `a' converted to an integer.  Equivalent to @code{a.__index__()}.


Άλλαξε στην έκδοση 3.10: The result always has exact type @ref{326,,int}.  Previously, the result
could have been an instance of a subclass of @code{int}.

@end deffn

@geindex inv() (στη μονάδα operator)
@geindex invert() (στη μονάδα operator)
@geindex __inv__() (στη μονάδα operator)
@geindex __invert__() (στη μονάδα operator)
@anchor{library/operator operator inv}@anchor{2df0}
@deffn {Συνάρτηση} operator.inv (obj)
@anchor{library/operator operator invert}@anchor{2df1}
@deffnx {Συνάρτηση} operator.invert (obj)
@anchor{library/operator operator __inv__}@anchor{2df2}
@deffnx {Συνάρτηση} operator.__inv__ (obj)
@anchor{library/operator operator __invert__}@anchor{2df3}
@deffnx {Συνάρτηση} operator.__invert__ (obj)

Return the bitwise inverse of the number `obj'.  This is equivalent to @code{~obj}.
@end deffn

@geindex lshift() (στη μονάδα operator)
@geindex __lshift__() (στη μονάδα operator)
@anchor{library/operator operator lshift}@anchor{2df4}
@deffn {Συνάρτηση} operator.lshift (a, b)
@anchor{library/operator operator __lshift__}@anchor{2df5}
@deffnx {Συνάρτηση} operator.__lshift__ (a, b)

Return `a' shifted left by `b'.
@end deffn

@geindex mod() (στη μονάδα operator)
@geindex __mod__() (στη μονάδα operator)
@anchor{library/operator operator mod}@anchor{2df6}
@deffn {Συνάρτηση} operator.mod (a, b)
@anchor{library/operator operator __mod__}@anchor{2df7}
@deffnx {Συνάρτηση} operator.__mod__ (a, b)

Return @code{a % b}.
@end deffn

@geindex mul() (στη μονάδα operator)
@geindex __mul__() (στη μονάδα operator)
@anchor{library/operator operator mul}@anchor{2dc5}
@deffn {Συνάρτηση} operator.mul (a, b)
@anchor{library/operator operator __mul__}@anchor{2df8}
@deffnx {Συνάρτηση} operator.__mul__ (a, b)

Return @code{a * b}, for `a' and `b' numbers.
@end deffn

@geindex matmul() (στη μονάδα operator)
@geindex __matmul__() (στη μονάδα operator)
@anchor{library/operator operator matmul}@anchor{11e8}
@deffn {Συνάρτηση} operator.matmul (a, b)
@anchor{library/operator operator __matmul__}@anchor{2df9}
@deffnx {Συνάρτηση} operator.__matmul__ (a, b)

Return @code{a @@ b}.


Added in version 3.5.

@end deffn

@geindex neg() (στη μονάδα operator)
@geindex __neg__() (στη μονάδα operator)
@anchor{library/operator operator neg}@anchor{2dfa}
@deffn {Συνάρτηση} operator.neg (obj)
@anchor{library/operator operator __neg__}@anchor{2dfb}
@deffnx {Συνάρτηση} operator.__neg__ (obj)

Return `obj' negated (@code{-obj}).
@end deffn

@geindex or_() (στη μονάδα operator)
@geindex __or__() (στη μονάδα operator)
@anchor{library/operator operator or_}@anchor{2dfc}
@deffn {Συνάρτηση} operator.or_ (a, b)
@anchor{library/operator operator __or__}@anchor{2dfd}
@deffnx {Συνάρτηση} operator.__or__ (a, b)

Return the bitwise or of `a' and `b'.
@end deffn

@geindex pos() (στη μονάδα operator)
@geindex __pos__() (στη μονάδα operator)
@anchor{library/operator operator pos}@anchor{2dfe}
@deffn {Συνάρτηση} operator.pos (obj)
@anchor{library/operator operator __pos__}@anchor{2dff}
@deffnx {Συνάρτηση} operator.__pos__ (obj)

Return `obj' positive (@code{+obj}).
@end deffn

@geindex pow() (στη μονάδα operator)
@geindex __pow__() (στη μονάδα operator)
@anchor{library/operator operator pow}@anchor{2e00}
@deffn {Συνάρτηση} operator.pow (a, b)
@anchor{library/operator operator __pow__}@anchor{2e01}
@deffnx {Συνάρτηση} operator.__pow__ (a, b)

Return @code{a ** b}, for `a' and `b' numbers.
@end deffn

@geindex rshift() (στη μονάδα operator)
@geindex __rshift__() (στη μονάδα operator)
@anchor{library/operator operator rshift}@anchor{2e02}
@deffn {Συνάρτηση} operator.rshift (a, b)
@anchor{library/operator operator __rshift__}@anchor{2e03}
@deffnx {Συνάρτηση} operator.__rshift__ (a, b)

Return `a' shifted right by `b'.
@end deffn

@geindex sub() (στη μονάδα operator)
@geindex __sub__() (στη μονάδα operator)
@anchor{library/operator operator sub}@anchor{2e04}
@deffn {Συνάρτηση} operator.sub (a, b)
@anchor{library/operator operator __sub__}@anchor{2e05}
@deffnx {Συνάρτηση} operator.__sub__ (a, b)

Return @code{a - b}.
@end deffn

@geindex truediv() (στη μονάδα operator)
@geindex __truediv__() (στη μονάδα operator)
@anchor{library/operator operator truediv}@anchor{2e06}
@deffn {Συνάρτηση} operator.truediv (a, b)
@anchor{library/operator operator __truediv__}@anchor{2e07}
@deffnx {Συνάρτηση} operator.__truediv__ (a, b)

Return @code{a / b} where 2/3 is .66 rather than 0.  This is also known as
«true» division.
@end deffn

@geindex xor() (στη μονάδα operator)
@geindex __xor__() (στη μονάδα operator)
@anchor{library/operator operator xor}@anchor{2e08}
@deffn {Συνάρτηση} operator.xor (a, b)
@anchor{library/operator operator __xor__}@anchor{2e09}
@deffnx {Συνάρτηση} operator.__xor__ (a, b)

Return the bitwise exclusive or of `a' and `b'.
@end deffn

Operations which work with sequences (some of them with mappings too) include:

@geindex concat() (στη μονάδα operator)
@geindex __concat__() (στη μονάδα operator)
@anchor{library/operator operator concat}@anchor{2e0a}
@deffn {Συνάρτηση} operator.concat (a, b)
@anchor{library/operator operator __concat__}@anchor{2e0b}
@deffnx {Συνάρτηση} operator.__concat__ (a, b)

Return @code{a + b} for `a' and `b' sequences.
@end deffn

@geindex contains() (στη μονάδα operator)
@geindex __contains__() (στη μονάδα operator)
@anchor{library/operator operator contains}@anchor{cac}
@deffn {Συνάρτηση} operator.contains (a, b)
@anchor{library/operator operator __contains__}@anchor{2e0c}
@deffnx {Συνάρτηση} operator.__contains__ (a, b)

Return the outcome of the test @code{b in a}. Note the reversed operands.
@end deffn

@geindex countOf() (στη μονάδα operator)
@anchor{library/operator operator countOf}@anchor{cae}
@deffn {Συνάρτηση} operator.countOf (a, b)

Return the number of occurrences of `b' in `a'.
@end deffn

@geindex delitem() (στη μονάδα operator)
@geindex __delitem__() (στη μονάδα operator)
@anchor{library/operator operator delitem}@anchor{2e0d}
@deffn {Συνάρτηση} operator.delitem (a, b)
@anchor{library/operator operator __delitem__}@anchor{2e0e}
@deffnx {Συνάρτηση} operator.__delitem__ (a, b)

Remove the value of `a' at index `b'.
@end deffn

@geindex getitem() (στη μονάδα operator)
@geindex __getitem__() (στη μονάδα operator)
@anchor{library/operator operator getitem}@anchor{2e0f}
@deffn {Συνάρτηση} operator.getitem (a, b)
@anchor{library/operator operator __getitem__}@anchor{2e10}
@deffnx {Συνάρτηση} operator.__getitem__ (a, b)

Return the value of `a' at index `b'.
@end deffn

@geindex indexOf() (στη μονάδα operator)
@anchor{library/operator operator indexOf}@anchor{cad}
@deffn {Συνάρτηση} operator.indexOf (a, b)

Return the index of the first of occurrence of `b' in `a'.
@end deffn

@geindex setitem() (στη μονάδα operator)
@geindex __setitem__() (στη μονάδα operator)
@anchor{library/operator operator setitem}@anchor{2e11}
@deffn {Συνάρτηση} operator.setitem (a, b, c)
@anchor{library/operator operator __setitem__}@anchor{2e12}
@deffnx {Συνάρτηση} operator.__setitem__ (a, b, c)

Set the value of `a' at index `b' to `c'.
@end deffn

@geindex length_hint() (στη μονάδα operator)
@anchor{library/operator operator length_hint}@anchor{1317}
@deffn {Συνάρτηση} operator.length_hint (obj, default=0)

Return an estimated length for the object `obj'. First try to return its
actual length, then an estimate using @ref{12bc,,object.__length_hint__()}, and
finally return the default value.


Added in version 3.4.

@end deffn

The following operation works with callables:

@geindex call() (στη μονάδα operator)
@geindex __call__() (στη μονάδα operator)
@anchor{library/operator operator call}@anchor{1e19}
@deffn {Συνάρτηση} operator.call (obj, /, *args, **kwargs)
@anchor{library/operator operator __call__}@anchor{2e13}
@deffnx {Συνάρτηση} operator.__call__ (obj, /, *args, **kwargs)

Return @code{obj(*args, **kwargs)}.


Added in version 3.11.

@end deffn

The @code{operator} module also defines tools for generalized attribute and item
lookups.  These are useful for making fast field extractors as arguments for
@ref{43e,,map()}, @ref{f8c,,sorted()}, @ref{192a,,itertools.groupby()}, or other functions that
expect a function argument.

@geindex attrgetter() (στη μονάδα operator)
@anchor{library/operator operator attrgetter}@anchor{11e6}
@deffn {Συνάρτηση} operator.attrgetter (attr)

@deffnx {Συνάρτηση} operator.attrgetter (*attrs)

Return a callable object that fetches `attr' from its operand.
If more than one attribute is requested, returns a tuple of attributes.
The attribute names can also contain dots. For example:


@itemize *

@item 
After @code{f = attrgetter('name')}, the call @code{f(b)} returns @code{b.name}.

@item 
After @code{f = attrgetter('name', 'date')}, the call @code{f(b)} returns
@code{(b.name, b.date)}.

@item 
After @code{f = attrgetter('name.first', 'name.last')}, the call @code{f(b)}
returns @code{(b.name.first, b.name.last)}.
@end itemize

Equivalent to:

@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() (στη μονάδα operator)
@anchor{library/operator operator itemgetter}@anchor{e26}
@deffn {Συνάρτηση} operator.itemgetter (item)

@deffnx {Συνάρτηση} operator.itemgetter (*items)

Return a callable object that fetches `item' from its operand using the
operand’s @ref{787,,__getitem__()} method.  If multiple items are specified,
returns a tuple of lookup values.  For example:


@itemize *

@item 
After @code{f = itemgetter(2)}, the call @code{f(r)} returns @code{r[2]}.

@item 
After @code{g = itemgetter(2, 5, 3)}, the call @code{g(r)} returns
@code{(r[2], r[5], r[3])}.
@end itemize

Equivalent to:

@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

The items can be any type accepted by the operand’s @ref{787,,__getitem__()}
method.  Dictionaries accept any @ref{183,,hashable} value.  Lists, tuples, and
strings accept an index or a slice:

@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

Example of using @code{itemgetter()} to retrieve specific fields from a
tuple record:

@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() (στη μονάδα operator)
@anchor{library/operator operator methodcaller}@anchor{11e7}
@deffn {Συνάρτηση} operator.methodcaller (name, /, *args, **kwargs)

Return a callable object that calls the method `name' on its operand.  If
additional arguments and/or keyword arguments are given, they will be given
to the method as well.  For example:


@itemize *

@item 
After @code{f = methodcaller('name')}, the call @code{f(b)} returns @code{b.name()}.

@item 
After @code{f = methodcaller('name', 'foo', bar=1)}, the call @code{f(b)}
returns @code{b.name('foo', bar=1)}.
@end itemize

Equivalent to:

@example
def methodcaller(name, /, *args, **kwargs):
    def caller(obj):
        return getattr(obj, name)(*args, **kwargs)
    return caller
@end example
@end deffn

@menu
* Mapping Operators to Functions:: 
* In-place Operators:: 

@end menu

@node Mapping Operators to Functions,In-place Operators,,operator — Standard operators as functions
@anchor{library/operator mapping-operators-to-functions}@anchor{2e14}@anchor{library/operator operator-map}@anchor{2e15}
@subsubsection Mapping Operators to Functions


This table shows how abstract operations correspond to operator symbols in the
Python syntax and the functions in the @code{operator} module.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Operation

@tab

Syntax

@tab

Function

@item

Addition

@tab

@code{a + b}

@tab

@code{add(a, b)}

@item

Concatenation

@tab

@code{seq1 + seq2}

@tab

@code{concat(seq1, seq2)}

@item

Containment Test

@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

Bitwise And

@tab

@code{a & b}

@tab

@code{and_(a, b)}

@item

Bitwise Exclusive Or

@tab

@code{a ^ b}

@tab

@code{xor(a, b)}

@item

Bitwise Inversion

@tab

@code{~ a}

@tab

@code{invert(a)}

@item

Bitwise Or

@tab

@code{a | b}

@tab

@code{or_(a, b)}

@item

Exponentiation

@tab

@code{a ** b}

@tab

@code{pow(a, b)}

@item

Identity

@tab

@code{a is b}

@tab

@code{is_(a, b)}

@item

Identity

@tab

@code{a is not b}

@tab

@code{is_not(a, b)}

@item

Identity

@tab

@code{a is None}

@tab

@code{is_none(a)}

@item

Identity

@tab

@code{a is not None}

@tab

@code{is_not_none(a)}

@item

Indexed Assignment

@tab

@code{obj[k] = v}

@tab

@code{setitem(obj, k, v)}

@item

Indexed Deletion

@tab

@code{del obj[k]}

@tab

@code{delitem(obj, k)}

@item

Indexing

@tab

@code{obj[k]}

@tab

@code{getitem(obj, k)}

@item

Left Shift

@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

Matrix Multiplication

@tab

@code{a @@ b}

@tab

@code{matmul(a, b)}

@item

Negation (Arithmetic)

@tab

@code{- a}

@tab

@code{neg(a)}

@item

Negation (Logical)

@tab

@code{not a}

@tab

@code{not_(a)}

@item

Positive

@tab

@code{+ a}

@tab

@code{pos(a)}

@item

Right Shift

@tab

@code{a >> b}

@tab

@code{rshift(a, b)}

@item

Slice Assignment

@tab

@code{seq[i:j] = values}

@tab

@code{setitem(seq, slice(i, j), values)}

@item

Slice Deletion

@tab

@code{del seq[i:j]}

@tab

@code{delitem(seq, slice(i, j))}

@item

Slicing

@tab

@code{seq[i:j]}

@tab

@code{getitem(seq, slice(i, j))}

@item

String Formatting

@tab

@code{s % obj}

@tab

@code{mod(s, obj)}

@item

Subtraction

@tab

@code{a - b}

@tab

@code{sub(a, b)}

@item

Truth Test

@tab

@code{obj}

@tab

@code{truth(obj)}

@item

Ordering

@tab

@code{a < b}

@tab

@code{lt(a, b)}

@item

Ordering

@tab

@code{a <= b}

@tab

@code{le(a, b)}

@item

Equality

@tab

@code{a == b}

@tab

@code{eq(a, b)}

@item

Difference

@tab

@code{a != b}

@tab

@code{ne(a, b)}

@item

Ordering

@tab

@code{a >= b}

@tab

@code{ge(a, b)}

@item

Ordering

@tab

@code{a > b}

@tab

@code{gt(a, b)}

@end multitable


@node In-place Operators,,Mapping Operators to Functions,operator — Standard operators as functions
@anchor{library/operator in-place-operators}@anchor{2e16}
@subsubsection In-place Operators


Many operations have an «in-place» version.  Listed below are functions
providing a more primitive access to in-place operators than the usual syntax
does; for example, the @ref{2e17,,statement} @code{x += y} is equivalent to
@code{x = operator.iadd(x, y)}.  Another way to put it is to say that
@code{z = operator.iadd(x, y)} is equivalent to the compound statement
@code{z = x; z += y}.

In those examples, note that when an in-place method is called, the computation
and assignment are performed in two separate steps.  The in-place functions
listed below only do the first step, calling the in-place method.  The second
step, assignment, is not handled.

For immutable targets such as strings, numbers, and tuples, the updated
value is computed, but not assigned back to the input variable:

@example
>>> a = 'hello'
>>> iadd(a, ' world')
'hello world'
>>> a
'hello'
@end example

For mutable targets such as lists and dictionaries, the in-place method
will perform the update, so no subsequent assignment is necessary:

@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() (στη μονάδα operator)
@geindex __iadd__() (στη μονάδα operator)
@anchor{library/operator operator iadd}@anchor{2e18}
@deffn {Συνάρτηση} operator.iadd (a, b)
@anchor{library/operator operator __iadd__}@anchor{2e19}
@deffnx {Συνάρτηση} operator.__iadd__ (a, b)

@code{a = iadd(a, b)} is equivalent to @code{a += b}.
@end deffn

@geindex iand() (στη μονάδα operator)
@geindex __iand__() (στη μονάδα operator)
@anchor{library/operator operator iand}@anchor{2e1a}
@deffn {Συνάρτηση} operator.iand (a, b)
@anchor{library/operator operator __iand__}@anchor{2e1b}
@deffnx {Συνάρτηση} operator.__iand__ (a, b)

@code{a = iand(a, b)} is equivalent to @code{a &= b}.
@end deffn

@geindex iconcat() (στη μονάδα operator)
@geindex __iconcat__() (στη μονάδα operator)
@anchor{library/operator operator iconcat}@anchor{2e1c}
@deffn {Συνάρτηση} operator.iconcat (a, b)
@anchor{library/operator operator __iconcat__}@anchor{2e1d}
@deffnx {Συνάρτηση} operator.__iconcat__ (a, b)

@code{a = iconcat(a, b)} is equivalent to @code{a += b} for `a' and `b' sequences.
@end deffn

@geindex ifloordiv() (στη μονάδα operator)
@geindex __ifloordiv__() (στη μονάδα operator)
@anchor{library/operator operator ifloordiv}@anchor{2e1e}
@deffn {Συνάρτηση} operator.ifloordiv (a, b)
@anchor{library/operator operator __ifloordiv__}@anchor{2e1f}
@deffnx {Συνάρτηση} operator.__ifloordiv__ (a, b)

@code{a = ifloordiv(a, b)} is equivalent to @code{a //= b}.
@end deffn

@geindex ilshift() (στη μονάδα operator)
@geindex __ilshift__() (στη μονάδα operator)
@anchor{library/operator operator ilshift}@anchor{2e20}
@deffn {Συνάρτηση} operator.ilshift (a, b)
@anchor{library/operator operator __ilshift__}@anchor{2e21}
@deffnx {Συνάρτηση} operator.__ilshift__ (a, b)

@code{a = ilshift(a, b)} is equivalent to @code{a <<= b}.
@end deffn

@geindex imod() (στη μονάδα operator)
@geindex __imod__() (στη μονάδα operator)
@anchor{library/operator operator imod}@anchor{2e22}
@deffn {Συνάρτηση} operator.imod (a, b)
@anchor{library/operator operator __imod__}@anchor{2e23}
@deffnx {Συνάρτηση} operator.__imod__ (a, b)

@code{a = imod(a, b)} is equivalent to @code{a %= b}.
@end deffn

@geindex imul() (στη μονάδα operator)
@geindex __imul__() (στη μονάδα operator)
@anchor{library/operator operator imul}@anchor{2e24}
@deffn {Συνάρτηση} operator.imul (a, b)
@anchor{library/operator operator __imul__}@anchor{2e25}
@deffnx {Συνάρτηση} operator.__imul__ (a, b)

@code{a = imul(a, b)} is equivalent to @code{a *= b}.
@end deffn

@geindex imatmul() (στη μονάδα operator)
@geindex __imatmul__() (στη μονάδα operator)
@anchor{library/operator operator imatmul}@anchor{11e9}
@deffn {Συνάρτηση} operator.imatmul (a, b)
@anchor{library/operator operator __imatmul__}@anchor{2e26}
@deffnx {Συνάρτηση} operator.__imatmul__ (a, b)

@code{a = imatmul(a, b)} is equivalent to @code{a @@= b}.


Added in version 3.5.

@end deffn

@geindex ior() (στη μονάδα operator)
@geindex __ior__() (στη μονάδα operator)
@anchor{library/operator operator ior}@anchor{2e27}
@deffn {Συνάρτηση} operator.ior (a, b)
@anchor{library/operator operator __ior__}@anchor{2e28}
@deffnx {Συνάρτηση} operator.__ior__ (a, b)

@code{a = ior(a, b)} is equivalent to @code{a |= b}.
@end deffn

@geindex ipow() (στη μονάδα operator)
@geindex __ipow__() (στη μονάδα operator)
@anchor{library/operator operator ipow}@anchor{2e29}
@deffn {Συνάρτηση} operator.ipow (a, b)
@anchor{library/operator operator __ipow__}@anchor{2e2a}
@deffnx {Συνάρτηση} operator.__ipow__ (a, b)

@code{a = ipow(a, b)} is equivalent to @code{a **= b}.
@end deffn

@geindex irshift() (στη μονάδα operator)
@geindex __irshift__() (στη μονάδα operator)
@anchor{library/operator operator irshift}@anchor{2e2b}
@deffn {Συνάρτηση} operator.irshift (a, b)
@anchor{library/operator operator __irshift__}@anchor{2e2c}
@deffnx {Συνάρτηση} operator.__irshift__ (a, b)

@code{a = irshift(a, b)} is equivalent to @code{a >>= b}.
@end deffn

@geindex isub() (στη μονάδα operator)
@geindex __isub__() (στη μονάδα operator)
@anchor{library/operator operator isub}@anchor{2e2d}
@deffn {Συνάρτηση} operator.isub (a, b)
@anchor{library/operator operator __isub__}@anchor{2e2e}
@deffnx {Συνάρτηση} operator.__isub__ (a, b)

@code{a = isub(a, b)} is equivalent to @code{a -= b}.
@end deffn

@geindex itruediv() (στη μονάδα operator)
@geindex __itruediv__() (στη μονάδα operator)
@anchor{library/operator operator itruediv}@anchor{2e2f}
@deffn {Συνάρτηση} operator.itruediv (a, b)
@anchor{library/operator operator __itruediv__}@anchor{2e30}
@deffnx {Συνάρτηση} operator.__itruediv__ (a, b)

@code{a = itruediv(a, b)} is equivalent to @code{a /= b}.
@end deffn

@geindex ixor() (στη μονάδα operator)
@geindex __ixor__() (στη μονάδα operator)
@anchor{library/operator operator ixor}@anchor{2e31}
@deffn {Συνάρτηση} operator.ixor (a, b)
@anchor{library/operator operator __ixor__}@anchor{2e32}
@deffnx {Συνάρτηση} operator.__ixor__ (a, b)

@code{a = ixor(a, b)} is equivalent to @code{a ^= b}.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node File and Directory Access,Data Persistence,Functional Programming Modules,The Python Standard Library
@anchor{library/filesys doc}@anchor{2e33}@anchor{library/filesys file-and-directory-access}@anchor{2e34}@anchor{library/filesys filesys}@anchor{2e35}@anchor{library/filesys translation-repo}@anchor{2e36}
@section File and Directory Access


The modules described in this chapter deal with disk files and directories.  For
example, there are modules for reading the properties of files, manipulating
paths in a portable way, and creating temporary files.  The full list of modules
in this chapter is:

@menu
* pathlib — Object-oriented filesystem paths:: 
* os.path — Common pathname manipulations: os path — Common pathname manipulations. 
* stat — Interpreting stat() results: stat — Interpreting stat results. 
* filecmp — File and Directory Comparisons:: 
* tempfile — Generate temporary files and directories:: 
* glob — Unix style pathname pattern expansion:: 
* fnmatch — Unix filename pattern matching:: 
* linecache — Random access to text lines:: 
* shutil — High-level file operations:: 

@end menu

@node pathlib — Object-oriented filesystem paths,os path — Common pathname manipulations,,File and Directory Access
@anchor{library/pathlib doc}@anchor{2e37}@anchor{library/pathlib module-pathlib}@anchor{a8}@anchor{library/pathlib pathlib-object-oriented-filesystem-paths}@anchor{2e38}
@subsection @code{pathlib} — Object-oriented filesystem paths


@geindex module; pathlib


Added in version 3.4.


`Source code:' Lib/pathlib/@footnote{https://github.com/python/cpython/tree/main/Lib/pathlib/}

@geindex path;operations


__________________________________________________________________


This module offers classes representing filesystem paths with semantics
appropriate for different operating systems.  Path classes are divided
between @ref{2e39,,pure paths}, which provide purely computational
operations without I/O, and @ref{2e3a,,concrete paths}, which
inherit from pure paths but also provide I/O operations.

@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}

If you’ve never used this module before or just aren’t sure which class is
right for your task, @ref{4ee,,Path} is most likely what you need. It instantiates
a @ref{2e3a,,concrete path} for the platform the code is running on.

Pure paths are useful in some special cases; for example:


@enumerate 

@item 
If you want to manipulate Windows paths on a Unix machine (or vice versa).
You cannot instantiate a @ref{2e3b,,WindowsPath} when running on Unix, but you
can instantiate @ref{1c7b,,PureWindowsPath}.

@item 
You want to make sure that your code only manipulates paths without actually
accessing the OS. In this case, instantiating one of the pure classes may be
useful since those simply don’t have any OS-accessing operations.
@end enumerate


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 428
PEP 428@footnote{https://peps.python.org/pep-0428/}: The pathlib module – object-oriented filesystem paths.



@subsubheading Δείτε επίσης


For low-level path manipulation on strings, you can also use the
@ref{a6,,os.path} module.


@menu
* Basic use:: 
* Exceptions: Exceptions<4>. 
* Pure paths:: 
* Concrete paths:: 
* Pattern language:: 
* Comparison to the glob module:: 
* Comparison to the os and os.path modules: Comparison to the os and os path modules. 
* Protocols:: 

@end menu

@node Basic use,Exceptions<4>,,pathlib — Object-oriented filesystem paths
@anchor{library/pathlib basic-use}@anchor{2e3c}
@subsubsection Basic use


Importing the main class:

@example
>>> from pathlib import Path
@end example

Listing subdirectories:

@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

Listing Python source files in this directory tree:

@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

Navigating inside a directory tree:

@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

Querying path properties:

@example
>>> q.exists()
True
>>> q.is_dir()
False
@end example

Opening a file:

@example
>>> with q.open() as f: f.readline()
...
'#!/bin/bash\n'
@end example

@node Exceptions<4>,Pure paths,Basic use,pathlib — Object-oriented filesystem paths
@anchor{library/pathlib exceptions}@anchor{2e3d}
@subsubsection Exceptions


@geindex UnsupportedOperation
@anchor{library/pathlib pathlib UnsupportedOperation}@anchor{736}
@deffn {Εξαίρεση} pathlib.UnsupportedOperation

An exception inheriting @ref{59a,,NotImplementedError} that is raised when an
unsupported operation is called on a path object.


Added in version 3.13.

@end deffn

@node Pure paths,Concrete paths,Exceptions<4>,pathlib — Object-oriented filesystem paths
@anchor{library/pathlib id1}@anchor{2e3e}@anchor{library/pathlib pure-paths}@anchor{2e39}
@subsubsection Pure paths


Pure path objects provide path-handling operations which don’t actually
access a filesystem.  There are three ways to access these classes, which
we also call `flavours':

@geindex PurePath (κλάση σε pathlib)
@anchor{library/pathlib pathlib PurePath}@anchor{8b6}
@deffn {Κλάση} pathlib.PurePath (*pathsegments)

A generic class that represents the system’s path flavour (instantiating
it creates either a @ref{2e3f,,PurePosixPath} or a @ref{1c7b,,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{100f,,os.PathLike} interface
where the @ref{1010,,__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

When `pathsegments' is empty, the current directory is assumed:

@example
>>> PurePath()
PurePosixPath('.')
@end example

If a segment is an absolute path, all previous segments are ignored
(like @ref{1a42,,os.path.join()}):

@example
>>> PurePath('/etc', '/usr', 'lib64')
PurePosixPath('/usr/lib64')
>>> PureWindowsPath('c:/Windows', 'd:bar')
PureWindowsPath('d:bar')
@end example

On Windows, the drive is not reset when a rooted relative path
segment (e.g., @code{r'\foo'}) is encountered:

@example
>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')
@end example

Spurious slashes and single dots are collapsed, but double dots (@code{'..'})
and leading double slashes (@code{'//'}) are not, since this would change the
meaning of a path for various reasons (e.g. symbolic links, UNC paths):

@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

(a naïve approach would make @code{PurePosixPath('foo/../bar')} equivalent
to @code{PurePosixPath('bar')}, which is wrong if @code{foo} is a symbolic link
to another directory)

Pure path objects implement the @ref{100f,,os.PathLike} interface, allowing them
to be used anywhere the interface is accepted.


Άλλαξε στην έκδοση 3.6: Added support for the @ref{100f,,os.PathLike} interface.

@end deffn

@geindex PurePosixPath (κλάση σε pathlib)
@anchor{library/pathlib pathlib PurePosixPath}@anchor{2e3f}
@deffn {Κλάση} pathlib.PurePosixPath (*pathsegments)

A subclass of @ref{8b6,,PurePath}, this path flavour represents non-Windows
filesystem paths:

@example
>>> PurePosixPath('/etc/hosts')
PurePosixPath('/etc/hosts')
@end example

`pathsegments' is specified similarly to @ref{8b6,,PurePath}.
@end deffn

@geindex PureWindowsPath (κλάση σε pathlib)
@anchor{library/pathlib pathlib PureWindowsPath}@anchor{1c7b}
@deffn {Κλάση} pathlib.PureWindowsPath (*pathsegments)

A subclass of @ref{8b6,,PurePath}, this path flavour represents Windows
filesystem paths, including 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' is specified similarly to @ref{8b6,,PurePath}.
@end deffn

Regardless of the system you’re running on, you can instantiate all of
these classes, since they don’t provide any operation that does system calls.

@menu
* General properties:: 
* Operators:: 
* Accessing individual parts:: 
* Methods and properties:: 

@end menu

@node General properties,Operators,,Pure paths
@anchor{library/pathlib general-properties}@anchor{2e40}
@subsubsection General properties


Paths are immutable and @ref{183,,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

Paths of a different flavour compare unequal and cannot be ordered:

@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 Operators,Accessing individual parts,General properties,Pure paths
@anchor{library/pathlib operators}@anchor{2e41}
@subsubsection Operators


The slash operator helps create child paths, like @ref{1a42,,os.path.join()}.
If the argument is an absolute path, the previous path is ignored.
On Windows, the drive is not reset when the argument is a rooted
relative path (e.g., @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

A path object can be used anywhere an object implementing @ref{100f,,os.PathLike}
is accepted:

@example
>>> import os
>>> p = PurePath('/etc')
>>> os.fspath(p)
'/etc'
@end example

The string representation of a path is the raw filesystem path itself
(in native form, e.g. with backslashes under Windows), which you can
pass to any function taking a file path as a string:

@example
>>> p = PurePath('/etc')
>>> str(p)
'/etc'
>>> p = PureWindowsPath('c:/Program Files')
>>> str(p)
'c:\\Program Files'
@end example

Similarly, calling @ref{1c7,,bytes} on a path gives the raw filesystem path as a
bytes object, as encoded by @ref{1013,,os.fsencode()}:

@example
>>> bytes(p)
b'/etc'
@end example

@cartouche
@quotation Σημείωση 
Calling @ref{1c7,,bytes} is only recommended under Unix.  Under Windows,
the unicode form is the canonical representation of filesystem paths.
@end quotation
@end cartouche

@node Accessing individual parts,Methods and properties,Operators,Pure paths
@anchor{library/pathlib accessing-individual-parts}@anchor{2e42}
@subsubsection Accessing individual parts


To access the individual «parts» (components) of a path, use the following
property:

@geindex parts (ιδιότητα της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath parts}@anchor{2e43}
@deffn {Ιδιότητα} PurePath.parts

A tuple giving access to the path’s various components:

@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

(note how the drive and local root are regrouped in a single part)
@end deffn

@node Methods and properties,,Accessing individual parts,Pure paths
@anchor{library/pathlib methods-and-properties}@anchor{2e44}
@subsubsection Methods and properties


@c from pathlib import PurePath, PurePosixPath, PureWindowsPath

Pure paths provide the following methods and properties:

@geindex parser (ιδιότητα της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath parser}@anchor{739}
@deffn {Ιδιότητα} PurePath.parser

The implementation of the @ref{a6,,os.path} module used for low-level path
parsing and joining: either @code{posixpath} or @code{ntpath}.


Added in version 3.13.

@end deffn

@geindex drive (ιδιότητα της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath drive}@anchor{2e45}
@deffn {Ιδιότητα} PurePath.drive

A string representing the drive letter or name, if any:

@example
>>> PureWindowsPath('c:/Program Files/').drive
'c:'
>>> PureWindowsPath('/Program Files/').drive
'@w{'}
>>> PurePosixPath('/etc').drive
'@w{'}
@end example

UNC shares are also considered drives:

@example
>>> PureWindowsPath('//host/share/foo.txt').drive
'\\\\host\\share'
@end example
@end deffn

@geindex root (ιδιότητα της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath root}@anchor{2e46}
@deffn {Ιδιότητα} PurePath.root

A string representing the (local or global) root, if any:

@example
>>> PureWindowsPath('c:/Program Files/').root
'\\'
>>> PureWindowsPath('c:Program Files/').root
'@w{'}
>>> PurePosixPath('/etc').root
'/'
@end example

UNC shares always have a root:

@example
>>> PureWindowsPath('//host/share').root
'\\'
@end example

If the path starts with more than two successive slashes,
@ref{2e3f,,PurePosixPath} collapses them:

@example
>>> PurePosixPath('//etc').root
'//'
>>> PurePosixPath('///etc').root
'/'
>>> PurePosixPath('////etc').root
'/'
@end example

@cartouche
@quotation Σημείωση 
This behavior conforms to `The Open Group Base Specifications Issue 6',
paragraph 4.11 Pathname Resolution@footnote{https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap04.html#tag_04_11}:

`«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 (ιδιότητα της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath anchor}@anchor{2e47}
@deffn {Ιδιότητα} PurePath.anchor

The concatenation of the drive and root:

@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 (ιδιότητα της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath parents}@anchor{bf9}
@deffn {Ιδιότητα} PurePath.parents

An immutable sequence providing access to the logical ancestors of
the path:

@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


Άλλαξε στην έκδοση 3.10: The parents sequence now supports @ref{26a5,,slices} and negative index values.

@end deffn

@geindex parent (ιδιότητα της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath parent}@anchor{1ca1}
@deffn {Ιδιότητα} PurePath.parent

The logical parent of the path:

@example
>>> p = PurePosixPath('/a/b/c/d')
>>> p.parent
PurePosixPath('/a/b/c')
@end example

You cannot go past an anchor, or empty path:

@example
>>> p = PurePosixPath('/')
>>> p.parent
PurePosixPath('/')
>>> p = PurePosixPath('.')
>>> p.parent
PurePosixPath('.')
@end example

@cartouche
@quotation Σημείωση 
This is a purely lexical operation, hence the following behaviour:

@example
>>> p = PurePosixPath('foo/..')
>>> p.parent
PurePosixPath('foo')
@end example

If you want to walk an arbitrary filesystem path upwards, it is
recommended to first call @ref{1c73,,Path.resolve()} so as to resolve
symlinks and eliminate @code{".."} components.
@end quotation
@end cartouche
@end deffn

@geindex name (ιδιότητα της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath name}@anchor{2e48}
@deffn {Ιδιότητα} PurePath.name

A string representing the final path component, excluding the drive and
root, if any:

@example
>>> PurePosixPath('my/library/setup.py').name
'setup.py'
@end example

UNC drive names are not considered:

@example
>>> PureWindowsPath('//some/share/setup.py').name
'setup.py'
>>> PureWindowsPath('//some/share').name
'@w{'}
@end example
@end deffn

@geindex suffix (ιδιότητα της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath suffix}@anchor{1b6b}
@deffn {Ιδιότητα} 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

This is commonly called the file extension.


Άλλαξε στην έκδοση 3.14: A single dot (»@code{.}») is considered a valid suffix.

@end deffn

@geindex suffixes (ιδιότητα της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath suffixes}@anchor{1b6c}
@deffn {Ιδιότητα} PurePath.suffixes

A list of the path’s suffixes, often called file extensions:

@example
>>> PurePosixPath('my/library.tar.gar').suffixes
['.tar', '.gar']
>>> PurePosixPath('my/library.tar.gz').suffixes
['.tar', '.gz']
>>> PurePosixPath('my/library').suffixes
[]
@end example


Άλλαξε στην έκδοση 3.14: A single dot (»@code{.}») is considered a valid suffix.

@end deffn

@geindex stem (ιδιότητα της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath stem}@anchor{2e49}
@deffn {Ιδιότητα} PurePath.stem

The final path component, without its suffix:

@example
>>> PurePosixPath('my/library.tar.gz').stem
'library.tar'
>>> PurePosixPath('my/library.tar').stem
'library'
>>> PurePosixPath('my/library').stem
'library'
@end example


Άλλαξε στην έκδοση 3.14: A single dot (»@code{.}») is considered a valid suffix.

@end deffn

@geindex as_posix() (μέθοδος της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath as_posix}@anchor{2e4a}
@deffn {Μέθοδος} PurePath.as_posix ()

Return a string representation of the path with forward slashes (@code{/}):

@example
>>> p = PureWindowsPath('c:\\windows')
>>> str(p)
'c:\\windows'
>>> p.as_posix()
'c:/windows'
@end example
@end deffn

@geindex is_absolute() (μέθοδος της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath is_absolute}@anchor{1ca0}
@deffn {Μέθοδος} PurePath.is_absolute ()

Return whether the path is absolute or not.  A path is considered absolute
if it has both a root and (if the flavour allows) a drive:

@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() (μέθοδος της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath is_relative_to}@anchor{576}
@deffn {Μέθοδος} PurePath.is_relative_to (other)

Return whether or not this path is relative to the `other' path.

@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


Added in version 3.9.



Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.14: Passing additional arguments is deprecated; if supplied, they are joined
with `other'.

@end deffn

@geindex joinpath() (μέθοδος της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath joinpath}@anchor{2e4b}
@deffn {Μέθοδος} 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() (μέθοδος της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath full_match}@anchor{738}
@deffn {Μέθοδος} 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 Δείτε επίσης


@ref{2e4c,,Pattern language} documentation.


As with other methods, case-sensitivity follows platform defaults:

@example
>>> PurePosixPath('b.py').full_match('*.PY')
False
>>> PureWindowsPath('b.py').full_match('*.PY')
True
@end example

Set `case_sensitive' to @code{True} or @code{False} to override this behaviour.


Added in version 3.13.

@end deffn

@geindex match() (μέθοδος της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath match}@anchor{8bc}
@deffn {Μέθοδος} 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{738,,full_match()}, but empty patterns
aren’t allowed (@ref{277,,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


Άλλαξε στην έκδοση 3.12: The `pattern' parameter accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.12: The `case_sensitive' parameter was added.

@end deffn

@geindex relative_to() (μέθοδος της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath relative_to}@anchor{575}
@deffn {Μέθοδος} 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{277,,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{277,,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 Προειδοποίηση 
This function is part of @ref{8b6,,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{1c73,,resolve()} first if
necessary to resolve symlinks.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.12: The `walk_up' parameter was added (old behavior is the same as @code{walk_up=False}).



Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.14: Passing additional positional arguments is deprecated; if supplied,
they are joined with `other'.

@end deffn

@geindex with_name() (μέθοδος της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath with_name}@anchor{1c6e}
@deffn {Μέθοδος} PurePath.with_name (name)

Return a new path with the @ref{2e48,,name} changed.  If the original path
doesn’t have a name, ValueError is raised:

@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() (μέθοδος της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath with_stem}@anchor{1be5}
@deffn {Μέθοδος} PurePath.with_stem (stem)

Return a new path with the @ref{2e49,,stem} changed.  If the original path
doesn’t have a name, ValueError is raised:

@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


Added in version 3.9.

@end deffn

@geindex with_suffix() (μέθοδος της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath with_suffix}@anchor{1b6a}
@deffn {Μέθοδος} PurePath.with_suffix (suffix)

Return a new path with the @ref{1b6b,,suffix} changed.  If the original path
doesn’t have a suffix, the new `suffix' is appended instead.  If the
`suffix' is an empty string, the original suffix is removed:

@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


Άλλαξε στην έκδοση 3.14: A single dot (»@code{.}») is considered a valid suffix. In previous
versions, @ref{277,,ValueError} is raised if a single dot is supplied.

@end deffn

@geindex with_segments() (μέθοδος της pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath with_segments}@anchor{8b7}
@deffn {Μέθοδος} 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{1ca1,,parent} and @ref{575,,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


Added in version 3.12.

@end deffn

@node Concrete paths,Pattern language,Pure paths,pathlib — Object-oriented filesystem paths
@anchor{library/pathlib concrete-paths}@anchor{2e3a}@anchor{library/pathlib id2}@anchor{2e4d}
@subsubsection Concrete paths


Concrete paths are subclasses of the pure path classes.  In addition to
operations provided by the latter, they also provide methods to do system
calls on path objects.  There are three ways to instantiate concrete paths:

@geindex Path (κλάση σε pathlib)
@anchor{library/pathlib pathlib Path}@anchor{4ee}
@deffn {Κλάση} pathlib.Path (*pathsegments)

A subclass of @ref{8b6,,PurePath}, this class represents concrete paths of
the system’s path flavour (instantiating it creates either a
@ref{2e4e,,PosixPath} or a @ref{2e3b,,WindowsPath}):

@example
>>> Path('setup.py')
PosixPath('setup.py')
@end example

`pathsegments' is specified similarly to @ref{8b6,,PurePath}.
@end deffn

@geindex PosixPath (κλάση σε pathlib)
@anchor{library/pathlib pathlib PosixPath}@anchor{2e4e}
@deffn {Κλάση} pathlib.PosixPath (*pathsegments)

A subclass of @ref{4ee,,Path} and @ref{2e3f,,PurePosixPath}, this class
represents concrete non-Windows filesystem paths:

@example
>>> PosixPath('/etc/hosts')
PosixPath('/etc/hosts')
@end example

`pathsegments' is specified similarly to @ref{8b6,,PurePath}.


Άλλαξε στην έκδοση 3.13: Raises @ref{736,,UnsupportedOperation} on Windows. In previous versions,
@ref{59a,,NotImplementedError} was raised instead.

@end deffn

@geindex WindowsPath (κλάση σε pathlib)
@anchor{library/pathlib pathlib WindowsPath}@anchor{2e3b}
@deffn {Κλάση} pathlib.WindowsPath (*pathsegments)

A subclass of @ref{4ee,,Path} and @ref{1c7b,,PureWindowsPath}, this class
represents concrete Windows filesystem paths:

@example
>>> WindowsPath('c:/', 'Users', 'Ximénez')
WindowsPath('c:/Users/Ximénez')
@end example

`pathsegments' is specified similarly to @ref{8b6,,PurePath}.


Άλλαξε στην έκδοση 3.13: Raises @ref{736,,UnsupportedOperation} on non-Windows platforms. In previous
versions, @ref{59a,,NotImplementedError} was raised instead.

@end deffn

You can only instantiate the class flavour that corresponds to your system
(allowing system calls on non-compatible path flavours could lead to
bugs or failures in your 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{53c,,OSError} if a system call fails
(for example because the path doesn’t exist).

@menu
* Parsing and generating URIs:: 
* Expanding and resolving paths:: 
* Querying file type and status:: 
* Reading and writing files:: 
* Reading directories:: 
* Creating files and directories:: 
* Copying@comma{} moving and deleting: Copying moving and deleting. 
* Permissions and ownership:: 

@end menu

@node Parsing and generating URIs,Expanding and resolving paths,,Concrete paths
@anchor{library/pathlib parsing-and-generating-uris}@anchor{2e4f}
@subsubsection Parsing and generating URIs


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 Σημείωση 
File URIs are not portable across machines with different
@ref{2e50,,filesystem encodings}.
@end quotation
@end cartouche

@geindex from_uri() (μέθοδος κλάσης της pathlib.Path)
@anchor{library/pathlib pathlib Path from_uri}@anchor{737}
@deffn {Μέθοδος} 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

Several variant forms are supported:

@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{277,,ValueError} is raised if the URI does not start with @code{file:}, or
the parsed path isn’t absolute.


Added in version 3.13.



Άλλαξε στην έκδοση 3.14: The URL authority is discarded if it matches the local hostname.
Otherwise, if the authority isn’t empty or @code{localhost}, then on
Windows a UNC path is returned (as before), and on other platforms a
@ref{277,,ValueError} is raised.

@end deffn

@geindex as_uri() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path as_uri}@anchor{587}
@deffn {Μέθοδος} Path.as_uri ()

Represent the path as a “file” URI.  @ref{277,,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


Καταργήθηκε από την έκδοση 3.14, θα αφαιρεθεί στην έκδοση 3.19: Calling this method from @ref{8b6,,PurePath} rather than @ref{4ee,,Path} is
possible but deprecated. The method’s use of @ref{1013,,os.fsencode()} makes
it strictly impure.

@end deffn

@node Expanding and resolving paths,Querying file type and status,Parsing and generating URIs,Concrete paths
@anchor{library/pathlib expanding-and-resolving-paths}@anchor{2e51}
@subsubsection Expanding and resolving paths


@geindex home() (μέθοδος κλάσης της pathlib.Path)
@anchor{library/pathlib pathlib Path home}@anchor{11f4}
@deffn {Μέθοδος} classmethod Path.home ()

Return a new path object representing the user’s home directory (as
returned by @ref{dd8,,os.path.expanduser()} with @code{~} construct). If the home
directory can’t be resolved, @ref{30d,,RuntimeError} is raised.

@example
>>> Path.home()
PosixPath('/home/antoine')
@end example


Added in version 3.5.

@end deffn

@geindex expanduser() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path expanduser}@anchor{11f3}
@deffn {Μέθοδος} Path.expanduser ()

Return a new path with expanded @code{~} and @code{~user} constructs,
as returned by @ref{dd8,,os.path.expanduser()}. If a home directory can’t be
resolved, @ref{30d,,RuntimeError} is raised.

@example
>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')
@end example


Added in version 3.5.

@end deffn

@geindex cwd() (μέθοδος κλάσης της pathlib.Path)
@anchor{library/pathlib pathlib Path cwd}@anchor{1c9f}
@deffn {Μέθοδος} classmethod Path.cwd ()

Return a new path object representing the current directory (as returned
by @ref{1b26,,os.getcwd()}):

@example
>>> Path.cwd()
PosixPath('/home/antoine/pathlib')
@end example
@end deffn

@geindex absolute() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path absolute}@anchor{1c2e}
@deffn {Μέθοδος} Path.absolute ()

Make the path absolute, without normalization or resolving symlinks.
Returns a new path object:

@example
>>> p = Path('tests')
>>> p
PosixPath('tests')
>>> p.absolute()
PosixPath('/home/antoine/pathlib/tests')
@end example
@end deffn

@geindex resolve() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path resolve}@anchor{1c73}
@deffn {Μέθοδος} Path.resolve (strict=False)

Make the path absolute, resolving any symlinks.  A new path object is
returned:

@example
>>> p = Path()
>>> p
PosixPath('.')
>>> p.resolve()
PosixPath('/home/antoine/pathlib')
@end example

«@code{..}» components are also eliminated (this is the only method to do so):

@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{53c,,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.


Άλλαξε στην έκδοση 3.6: The `strict' parameter was added (pre-3.6 behavior is strict).



Άλλαξε στην έκδοση 3.13: Symlink loops are treated like other errors: @ref{53c,,OSError} is raised in
strict mode, and no exception is raised in non-strict mode. In previous
versions, @ref{30d,,RuntimeError} is raised no matter the value of `strict'.

@end deffn

@geindex readlink() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path readlink}@anchor{cec}
@deffn {Μέθοδος} Path.readlink ()

Return the path to which the symbolic link points (as returned by
@ref{ced,,os.readlink()}):

@example
>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.readlink()
PosixPath('setup.py')
@end example


Added in version 3.9.



Άλλαξε στην έκδοση 3.13: Raises @ref{736,,UnsupportedOperation} if @ref{ced,,os.readlink()} is not
available. In previous versions, @ref{59a,,NotImplementedError} was raised.

@end deffn

@node Querying file type and status,Reading and writing files,Expanding and resolving paths,Concrete paths
@anchor{library/pathlib querying-file-type-and-status}@anchor{2e52}
@subsubsection Querying file type and status



Άλλαξε στην έκδοση 3.8: @ref{dda,,exists()}, @ref{73d,,is_dir()}, @ref{73c,,is_file()},
@ref{ddb,,is_mount()}, @ref{ddc,,is_symlink()},
@ref{ddd,,is_block_device()}, @ref{dde,,is_char_device()},
@ref{ddf,,is_fifo()}, @ref{de0,,is_socket()} now return @code{False}
instead of raising an exception for paths that contain characters
unrepresentable at the OS level.



Άλλαξε στην έκδοση 3.14: The methods given above now return @code{False} instead of raising any
@ref{53c,,OSError} exception from the operating system. In previous versions,
some kinds of @code{OSError} exception are raised, and others suppressed.
The new behaviour is consistent with @ref{dd2,,os.path.exists()},
@ref{dd4,,os.path.isdir()}, etc. Use @ref{bfc,,stat()} to retrieve the file
status without suppressing exceptions.


@geindex stat() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path stat}@anchor{bfc}
@deffn {Μέθοδος} Path.stat (*, follow_symlinks=True)

Return an @ref{1863,,os.stat_result} object containing information about this path, like @ref{4f5,,os.stat()}.
The result is looked up at each call to this method.

This method normally follows symlinks; to stat a symlink add the argument
@code{follow_symlinks=False}, or use @ref{2e53,,lstat()}.

@example
>>> p = Path('setup.py')
>>> p.stat().st_size
956
>>> p.stat().st_mtime
1327883547.852554
@end example


Άλλαξε στην έκδοση 3.10: The `follow_symlinks' parameter was added.

@end deffn

@geindex lstat() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path lstat}@anchor{2e53}
@deffn {Μέθοδος} Path.lstat ()

Like @ref{bfc,,Path.stat()} but, if the path points to a symbolic link, return
the symbolic link’s information rather than its target’s.
@end deffn

@geindex exists() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path exists}@anchor{dda}
@deffn {Μέθοδος} Path.exists (*, follow_symlinks=True)

Return @code{True} if the path points to an existing file or directory.
@code{False} will be returned if the path is invalid, inaccessible or missing.
Use @ref{bfc,,Path.stat()} to distinguish between these cases.

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


Άλλαξε στην έκδοση 3.12: The `follow_symlinks' parameter was added.

@end deffn

@geindex is_file() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path is_file}@anchor{73c}
@deffn {Μέθοδος} Path.is_file (*, follow_symlinks=True)

Return @code{True} if the path points to a regular file. @code{False} will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a regular file. Use @ref{bfc,,Path.stat()} to
distinguish between these cases.

This method normally follows symlinks; to exclude symlinks, add the
argument @code{follow_symlinks=False}.


Άλλαξε στην έκδοση 3.13: The `follow_symlinks' parameter was added.

@end deffn

@geindex is_dir() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path is_dir}@anchor{73d}
@deffn {Μέθοδος} Path.is_dir (*, follow_symlinks=True)

Return @code{True} if the path points to a directory. @code{False} will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a directory. Use @ref{bfc,,Path.stat()} to distinguish
between these cases.

This method normally follows symlinks; to exclude symlinks to directories,
add the argument @code{follow_symlinks=False}.


Άλλαξε στην έκδοση 3.13: The `follow_symlinks' parameter was added.

@end deffn

@geindex is_symlink() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path is_symlink}@anchor{ddc}
@deffn {Μέθοδος} Path.is_symlink ()

Return @code{True} if the path points to a symbolic link, even if that symlink
is broken. @code{False} will be returned if the path is invalid, inaccessible
or missing, or if it points to something other than a symbolic link. Use
@ref{bfc,,Path.stat()} to distinguish between these cases.
@end deffn

@geindex is_junction() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path is_junction}@anchor{8bb}
@deffn {Μέθοδος} 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.


Added in version 3.12.

@end deffn

@geindex is_mount() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path is_mount}@anchor{ddb}
@deffn {Μέθοδος} 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.


Added in version 3.7.



Άλλαξε στην έκδοση 3.12: Windows support was added.

@end deffn

@geindex is_socket() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path is_socket}@anchor{de0}
@deffn {Μέθοδος} Path.is_socket ()

Return @code{True} if the path points to a Unix socket. @code{False} will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a Unix socket. Use @ref{bfc,,Path.stat()} to
distinguish between these cases.
@end deffn

@geindex is_fifo() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path is_fifo}@anchor{ddf}
@deffn {Μέθοδος} Path.is_fifo ()

Return @code{True} if the path points to a FIFO. @code{False} will be returned if
the path is invalid, inaccessible or missing, or if it points to something
other than a FIFO. Use @ref{bfc,,Path.stat()} to distinguish between these
cases.
@end deffn

@geindex is_block_device() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path is_block_device}@anchor{ddd}
@deffn {Μέθοδος} Path.is_block_device ()

Return @code{True} if the path points to a block device. @code{False} will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a block device. Use @ref{bfc,,Path.stat()} to
distinguish between these cases.
@end deffn

@geindex is_char_device() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path is_char_device}@anchor{dde}
@deffn {Μέθοδος} Path.is_char_device ()

Return @code{True} if the path points to a character device. @code{False} will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a character device. Use @ref{bfc,,Path.stat()} to
distinguish between these cases.
@end deffn

@geindex samefile() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path samefile}@anchor{11f1}
@deffn {Μέθοδος} Path.samefile (other_path)

Return whether this path points to the same file as `other_path', which
can be either a Path object, or a string.  The semantics are similar
to @ref{131b,,os.path.samefile()} and @ref{131a,,os.path.samestat()}.

An @ref{53c,,OSError} can be raised if either file cannot be accessed for some
reason.

@example
>>> p = Path('spam')
>>> q = Path('eggs')
>>> p.samefile(q)
False
>>> p.samefile('spam')
True
@end example


Added in version 3.5.

@end deffn

@geindex info (ιδιότητα της pathlib.Path)
@anchor{library/pathlib pathlib Path info}@anchor{4f3}
@deffn {Ιδιότητα} Path.info

A @ref{4f4,,PathInfo} object that supports querying file type
information. The object exposes methods that cache their results, which can
help reduce the number of system calls needed when switching on file type.
For example:

@example
>>> p = Path('src')
>>> if p.info.is_symlink():
...     print('symlink')
... elif p.info.is_dir():
...     print('directory')
... elif p.info.exists():
...     print('something else')
... else:
...     print('not found')
...
directory
@end example

If the path was generated from @ref{4f6,,Path.iterdir()} then this attribute is
initialized with some information about the file type gleaned from scanning
the parent directory. Merely accessing @code{Path.info} does not perform
any filesystem queries.

To fetch up-to-date information, it’s best to call @ref{73d,,Path.is_dir()},
@ref{73c,,is_file()} and @ref{ddc,,is_symlink()} rather than methods of
this attribute. There is no way to reset the cache; instead you can create
a new path object with an empty info cache via @code{p = Path(p)}.


Added in version 3.14.

@end deffn

@node Reading and writing files,Reading directories,Querying file type and status,Concrete paths
@anchor{library/pathlib reading-and-writing-files}@anchor{2e54}
@subsubsection Reading and writing files


@geindex open() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path open}@anchor{2e55}
@deffn {Μέθοδος} Path.open (mode='r', buffering=-1, encoding=None, errors=None, newline=None)

Open the file pointed to by the path, like the built-in @ref{32b,,open()}
function does:

@example
>>> p = Path('setup.py')
>>> with p.open() as f:
...     f.readline()
...
'#!/usr/bin/env python3\n'
@end example
@end deffn

@geindex read_text() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path read_text}@anchor{11f6}
@deffn {Μέθοδος} Path.read_text (encoding=None, errors=None, newline=None)

Return the decoded contents of the pointed-to file as a string:

@example
>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'
@end example

The file is opened and then closed. The optional parameters have the same
meaning as in @ref{32b,,open()}.


Added in version 3.5.



Άλλαξε στην έκδοση 3.13: The `newline' parameter was added.

@end deffn

@geindex read_bytes() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path read_bytes}@anchor{55a}
@deffn {Μέθοδος} Path.read_bytes ()

Return the binary contents of the pointed-to file as a bytes object:

@example
>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'
@end example


Added in version 3.5.

@end deffn

@geindex write_text() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path write_text}@anchor{11f5}
@deffn {Μέθοδος} Path.write_text (data, encoding=None, errors=None, newline=None)

Open the file pointed to in text mode, write `data' to it, and close the
file:

@example
>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'
@end example

An existing file of the same name is overwritten. The optional parameters
have the same meaning as in @ref{32b,,open()}.


Added in version 3.5.



Άλλαξε στην έκδοση 3.10: The `newline' parameter was added.

@end deffn

@geindex write_bytes() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path write_bytes}@anchor{11f7}
@deffn {Μέθοδος} Path.write_bytes (data)

Open the file pointed to in bytes mode, write `data' to it, and close the
file:

@example
>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'
@end example

An existing file of the same name is overwritten.


Added in version 3.5.

@end deffn

@node Reading directories,Creating files and directories,Reading and writing files,Concrete paths
@anchor{library/pathlib reading-directories}@anchor{2e56}
@subsubsection Reading directories


@geindex iterdir() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path iterdir}@anchor{4f6}
@deffn {Μέθοδος} Path.iterdir ()

When the path points to a directory, yield path objects of the directory
contents:

@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.

If the path is not a directory or otherwise inaccessible, @ref{53c,,OSError} is
raised.
@end deffn

@geindex glob() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path glob}@anchor{73a}
@deffn {Μέθοδος} Path.glob (pattern, *, case_sensitive=None, recurse_symlinks=False)

Glob the given relative `pattern' in the directory represented by this path,
yielding all matching files (of any kind):

@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

@cartouche
@quotation Σημείωση 
The paths are returned in no particular order.
If you need a specific order, sort the results.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης


@ref{2e4c,,Pattern language} documentation.


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.

@cartouche
@quotation Σημείωση 
Any @ref{53c,,OSError} exceptions raised from scanning the filesystem are
suppressed. This includes @ref{10f9,,PermissionError} when accessing
directories without read permission.
@end quotation
@end cartouche

Raises an @ref{1e65,,auditing event} @code{pathlib.Path.glob} with arguments @code{self}, @code{pattern}.


Άλλαξε στην έκδοση 3.12: The `case_sensitive' parameter was added.



Άλλαξε στην έκδοση 3.13: The `recurse_symlinks' parameter was added.



Άλλαξε στην έκδοση 3.13: The `pattern' parameter accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.13: Any @ref{53c,,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() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path rglob}@anchor{73b}
@deffn {Μέθοδος} Path.rglob (pattern, *, case_sensitive=None, recurse_symlinks=False)

Glob the given relative `pattern' recursively.  This is like calling
@ref{73a,,Path.glob()} with «@code{**/}» added in front of the `pattern'.

@cartouche
@quotation Σημείωση 
The paths are returned in no particular order.
If you need a specific order, sort the results.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Any @ref{53c,,OSError} exceptions raised from scanning the filesystem are
suppressed. This includes @ref{10f9,,PermissionError} when accessing
directories without read permission.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης


@ref{2e4c,,Pattern language} and @ref{73a,,Path.glob()} documentation.


Raises an @ref{1e65,,auditing event} @code{pathlib.Path.rglob} with arguments @code{self}, @code{pattern}.


Άλλαξε στην έκδοση 3.12: The `case_sensitive' parameter was added.



Άλλαξε στην έκδοση 3.13: The `recurse_symlinks' parameter was added.



Άλλαξε στην έκδοση 3.13: The `pattern' parameter accepts a @ref{79f,,path-like object}.

@end deffn

@geindex walk() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path walk}@anchor{8b8}
@deffn {Μέθοδος} 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{4ee,,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{1d1d,,del} or slice assignment), and @code{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 @code{Path.walk()} about directories the caller creates or
renames before it resumes @code{Path.walk()} again. Modifying `dirnames' when
`top_down' is false has no effect on the behavior of @code{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{e23,,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{53c,,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, @code{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 Σημείωση 
Be aware that setting `follow_symlinks' to true can lead to infinite
recursion if a link points to a parent directory of itself. @code{Path.walk()}
does not keep track of the directories it has already visited.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
@code{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, @code{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 Σημείωση 
Unlike @ref{8b9,,os.walk()}, @code{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{335,,shutil.rmtree()}.
Walking the tree bottom-up is essential as @ref{2e57,,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


Added in version 3.12.

@end deffn

@node Creating files and directories,Copying moving and deleting,Reading directories,Concrete paths
@anchor{library/pathlib creating-files-and-directories}@anchor{2e58}
@subsubsection Creating files and directories


@geindex touch() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path touch}@anchor{2e59}
@deffn {Μέθοδος} 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{13c9,,FileExistsError} is raised.


@subsubheading Δείτε επίσης


The @ref{2e55,,open()}, @ref{11f5,,write_text()} and
@ref{11f7,,write_bytes()} methods are often used to create files.

@end deffn

@geindex mkdir() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path mkdir}@anchor{11f2}
@deffn {Μέθοδος} 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{13c9,,FileExistsError}
is raised.

If `parents' is true, any missing parents of this path are created
as needed; they are created with the default permissions without taking
`mode' into account (mimicking the POSIX @code{mkdir -p} command).

If `parents' is false (the default), a missing parent raises
@ref{243,,FileNotFoundError}.

If `exist_ok' is false (the default), @ref{13c9,,FileExistsError} is
raised if the target directory already exists.

If `exist_ok' is true, @ref{13c9,,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).


Άλλαξε στην έκδοση 3.5: The `exist_ok' parameter was added.

@end deffn

@geindex symlink_to() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path symlink_to}@anchor{bfb}
@deffn {Μέθοδος} 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 Σημείωση 
The order of arguments (link, target) is the reverse
of @ref{14a0,,os.symlink()}”s.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.13: Raises @ref{736,,UnsupportedOperation} if @ref{14a0,,os.symlink()} is not
available. In previous versions, @ref{59a,,NotImplementedError} was raised.

@end deffn

@geindex hardlink_to() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path hardlink_to}@anchor{bfa}
@deffn {Μέθοδος} Path.hardlink_to (target)

Make this path a hard link to the same file as `target'.

@cartouche
@quotation Σημείωση 
The order of arguments (link, target) is the reverse
of @ref{149b,,os.link()}”s.
@end quotation
@end cartouche


Added in version 3.10.



Άλλαξε στην έκδοση 3.13: Raises @ref{736,,UnsupportedOperation} if @ref{149b,,os.link()} is not
available. In previous versions, @ref{59a,,NotImplementedError} was raised.

@end deffn

@node Copying moving and deleting,Permissions and ownership,Creating files and directories,Concrete paths
@anchor{library/pathlib copying-moving-and-deleting}@anchor{2e5a}
@subsubsection Copying, moving and deleting


@geindex copy() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path copy}@anchor{4ef}
@deffn {Μέθοδος} Path.copy (target, *, follow_symlinks=True, preserve_metadata=False)

Copy this file or directory tree to the given `target', and return a new
@code{Path} instance pointing to `target'.

If the source is a file, the target will be replaced if it is an existing
file. If the source is a symlink and `follow_symlinks' is true (the
default), the symlink’s target is copied. Otherwise, the symlink is
recreated at the destination.

If `preserve_metadata' is false (the default), only directory structures
and file data are guaranteed to be copied. Set `preserve_metadata' to true
to ensure that file and directory permissions, flags, last access and
modification times, and extended attributes are copied where supported.
This argument has no effect when copying files on Windows (where
metadata is always preserved).

@cartouche
@quotation Σημείωση 
Where supported by the operating system and file system, this method
performs a lightweight copy, where data blocks are only copied when
modified. This is known as copy-on-write.
@end quotation
@end cartouche


Added in version 3.14.

@end deffn

@geindex copy_into() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path copy_into}@anchor{4f0}
@deffn {Μέθοδος} Path.copy_into (target_dir, *, follow_symlinks=True, preserve_metadata=False)

Copy this file or directory tree into the given `target_dir', which should
be an existing directory. Other arguments are handled identically to
@ref{4ef,,Path.copy()}. Returns a new @code{Path} instance pointing to the
copy.


Added in version 3.14.

@end deffn

@geindex rename() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path rename}@anchor{1ab5}
@deffn {Μέθοδος} 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{13c9,,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.

It is implemented in terms of @ref{149d,,os.rename()} and gives the same guarantees.


Άλλαξε στην έκδοση 3.8: Added return value, return the new @code{Path} instance.

@end deffn

@geindex replace() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path replace}@anchor{2e5b}
@deffn {Μέθοδος} 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.


Άλλαξε στην έκδοση 3.8: Added return value, return the new @code{Path} instance.

@end deffn

@geindex move() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path move}@anchor{4f1}
@deffn {Μέθοδος} Path.move (target)

Move this file or directory tree to the given `target', and return a new
@code{Path} instance pointing to `target'.

If the `target' doesn’t exist it will be created. If both this path and the
`target' are existing files, then the target is overwritten. If both paths
point to the same file or directory, or the `target' is a non-empty
directory, then @ref{53c,,OSError} is raised.

If both paths are on the same filesystem, the move is performed with
@ref{149e,,os.replace()}. Otherwise, this path is copied (preserving metadata and
symlinks) and then deleted.


Added in version 3.14.

@end deffn

@geindex move_into() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path move_into}@anchor{4f2}
@deffn {Μέθοδος} Path.move_into (target_dir)

Move this file or directory tree into the given `target_dir', which should
be an existing directory. Returns a new @code{Path} instance pointing to
the moved path.


Added in version 3.14.

@end deffn

@geindex unlink() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path unlink}@anchor{1fc4}
@deffn {Μέθοδος} Path.unlink (missing_ok=False)

Remove this file or symbolic link.  If the path points to a directory,
use @ref{2e57,,Path.rmdir()} instead.

If `missing_ok' is false (the default), @ref{243,,FileNotFoundError} is
raised if the path does not exist.

If `missing_ok' is true, @ref{243,,FileNotFoundError} exceptions will be
ignored (same behavior as the POSIX @code{rm -f} command).


Άλλαξε στην έκδοση 3.8: The `missing_ok' parameter was added.

@end deffn

@geindex rmdir() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path rmdir}@anchor{2e57}
@deffn {Μέθοδος} Path.rmdir ()

Remove this directory.  The directory must be empty.
@end deffn

@node Permissions and ownership,,Copying moving and deleting,Concrete paths
@anchor{library/pathlib permissions-and-ownership}@anchor{2e5c}
@subsubsection Permissions and ownership


@geindex owner() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path owner}@anchor{73e}
@deffn {Μέθοδος} Path.owner (*, follow_symlinks=True)

Return the name of the user owning the file. @ref{7df,,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}.


Άλλαξε στην έκδοση 3.13: Raises @ref{736,,UnsupportedOperation} if the @ref{ba,,pwd} module is not
available. In earlier versions, @ref{59a,,NotImplementedError} was raised.



Άλλαξε στην έκδοση 3.13: The `follow_symlinks' parameter was added.

@end deffn

@geindex group() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path group}@anchor{73f}
@deffn {Μέθοδος} Path.group (*, follow_symlinks=True)

Return the name of the group owning the file. @ref{7df,,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}.


Άλλαξε στην έκδοση 3.13: Raises @ref{736,,UnsupportedOperation} if the @ref{69,,grp} module is not
available. In earlier versions, @ref{59a,,NotImplementedError} was raised.



Άλλαξε στην έκδοση 3.13: The `follow_symlinks' parameter was added.

@end deffn

@geindex chmod() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path chmod}@anchor{bfd}
@deffn {Μέθοδος} Path.chmod (mode, *, follow_symlinks=True)

Change the file mode and permissions, like @ref{72c,,os.chmod()}.

This method normally follows symlinks. Some Unix flavours support changing
permissions on the symlink itself; on these platforms you may add the
argument @code{follow_symlinks=False}, or use @ref{2e5d,,lchmod()}.

@example
>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060
@end example


Άλλαξε στην έκδοση 3.10: The `follow_symlinks' parameter was added.

@end deffn

@geindex lchmod() (μέθοδος της pathlib.Path)
@anchor{library/pathlib pathlib Path lchmod}@anchor{2e5d}
@deffn {Μέθοδος} Path.lchmod (mode)

Like @ref{bfd,,Path.chmod()} but, if the path points to a symbolic link, the
symbolic link’s mode is changed rather than its target’s.
@end deffn

@node Pattern language,Comparison to the glob module,Concrete paths,pathlib — Object-oriented filesystem paths
@anchor{library/pathlib pathlib-pattern-language}@anchor{2e4c}@anchor{library/pathlib pattern-language}@anchor{2e5e}
@subsubsection Pattern language


The following wildcards are supported in patterns for
@ref{738,,full_match()}, @ref{73a,,glob()} and @ref{73b,,rglob()}:


@table @asis

@item @code{**} (entire segment)

Matches any number of file or directory segments, including zero.

@item @code{*} (entire segment)

Matches one file or directory segment.

@item @code{*} (part of a segment)

Matches any number of non-separator characters, including zero.

@item @code{?}

Matches one non-separator character.

@item @code{[seq]}

Matches one character in `seq', where `seq' is a sequence of characters.
Range expressions are supported; for example, @code{[a-z]} matches any lowercase ASCII letter.
Multiple ranges can be combined: @code{[a-zA-Z0-9_]} matches any ASCII letter, digit, or underscore.

@item @code{[!seq]}

Matches one character not in `seq', where `seq' follows the same rules as above.
@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

Pattern

@tab

Meaning

@item

«@code{**/*}»

@tab

Any path with at least one 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 Σημείωση 
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


Άλλαξε στην έκδοση 3.13: Globbing with a pattern that ends with «@code{**}» returns both files and
directories. In previous versions, only directories were returned.


In @ref{73a,,Path.glob()} and @ref{73b,,rglob()}, a trailing slash may be added to
the pattern to match only directories.


Άλλαξε στην έκδοση 3.11: Globbing with a pattern that ends with a pathname components separator
(@ref{a5a,,sep} or @ref{a5b,,altsep}) returns only directories.


@node Comparison to the glob module,Comparison to the os and os path modules,Pattern language,pathlib — Object-oriented filesystem paths
@anchor{library/pathlib comparison-to-the-glob-module}@anchor{2e5f}
@subsubsection Comparison to the @code{glob} module


The patterns accepted and results generated by @ref{73a,,Path.glob()} and
@ref{73b,,Path.rglob()} differ slightly from those by the @ref{67,,glob} module:


@enumerate 

@item 
Files beginning with a dot are not special in pathlib. This is
like passing @code{include_hidden=True} to @ref{2d4,,glob.glob()}.

@item 
«@code{**}» pattern components are always recursive in pathlib. This is like
passing @code{recursive=True} to @ref{2d4,,glob.glob()}.

@item 
«@code{**}» pattern components do not follow symlinks by default in pathlib.
This behaviour has no equivalent in @ref{2d4,,glob.glob()}, but you can pass
@code{recurse_symlinks=True} to @ref{73a,,Path.glob()} for compatible behaviour.

@item 
Like all @ref{8b6,,PurePath} and @ref{4ee,,Path} objects, the values returned
from @ref{73a,,Path.glob()} and @ref{73b,,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 Comparison to the os and os path modules,Protocols,Comparison to the glob module,pathlib — Object-oriented filesystem paths
@anchor{library/pathlib comparison-to-the-os-and-os-path-modules}@anchor{2e60}
@subsubsection Comparison to the @code{os} and @code{os.path} modules


pathlib implements path operations using @ref{8b6,,PurePath} and @ref{4ee,,Path}
objects, and so it’s said to be `object-oriented'. On the other hand, the
@ref{a5,,os} and @ref{a6,,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{a5,,os} and @ref{a6,,os.path} support @code{bytes} paths and
@ref{1496,,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{a5,,os} and
@ref{a6,,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{a6,,os.path}. For example, whereas @ref{16bf,,os.path.abspath()} eliminates
«@code{..}» segments from a path, which may change its meaning if symlinks are
involved, @ref{1c2e,,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 μεταβλητή περιβάλλοντος; 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{a6,,os.path}.

@menu
* Corresponding tools:: 

@end menu

@node Corresponding tools,,,Comparison to the os and os path modules
@anchor{library/pathlib corresponding-tools}@anchor{2e61}
@subsubsection Corresponding tools


Below is a table mapping various @ref{a5,,os} functions to their corresponding
@ref{8b6,,PurePath}/@ref{4ee,,Path} equivalent.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@ref{a5,,os} and @ref{a6,,os.path}

@tab

@code{pathlib}

@item

@ref{2e62,,os.path.dirname()}

@tab

@ref{1ca1,,PurePath.parent}

@item

@ref{2e63,,os.path.basename()}

@tab

@ref{2e48,,PurePath.name}

@item

@ref{1b6d,,os.path.splitext()}

@tab

@ref{2e49,,PurePath.stem}, @ref{1b6b,,PurePath.suffix}

@item

@ref{1a42,,os.path.join()}

@tab

@ref{2e4b,,PurePath.joinpath()}

@item

@ref{734,,os.path.isabs()}

@tab

@ref{1ca0,,PurePath.is_absolute()}

@item

@ref{8ba,,os.path.relpath()}

@tab

@ref{575,,PurePath.relative_to()} @footnote{
@ref{8ba,,os.path.relpath()} calls @ref{16bf,,abspath()} to make paths
absolute and remove «@code{..}» parts, whereas @ref{575,,PurePath.relative_to()}
is a lexical operation that raises @ref{277,,ValueError} when its inputs”
anchors differ (e.g. if one path is absolute and the other relative.)
}

@item

@ref{dd8,,os.path.expanduser()}

@tab

@ref{11f3,,Path.expanduser()} @footnote{
@ref{dd8,,os.path.expanduser()} returns the path unchanged if the home
directory can’t be resolved, whereas @ref{11f3,,Path.expanduser()} raises
@ref{30d,,RuntimeError}.
}

@item

@ref{241,,os.path.realpath()}

@tab

@ref{1c73,,Path.resolve()}

@item

@ref{16bf,,os.path.abspath()}

@tab

@ref{1c2e,,Path.absolute()} @footnote{
@ref{16bf,,os.path.abspath()} removes «@code{..}» components without resolving
symlinks, which may change the meaning of the path, whereas
@ref{1c2e,,Path.absolute()} leaves any «@code{..}» components in the path.
}

@item

@ref{dd2,,os.path.exists()}

@tab

@ref{dda,,Path.exists()}

@item

@ref{dd5,,os.path.isfile()}

@tab

@ref{73c,,Path.is_file()}

@item

@ref{dd4,,os.path.isdir()}

@tab

@ref{73d,,Path.is_dir()}

@item

@ref{dd0,,os.path.islink()}

@tab

@ref{ddc,,Path.is_symlink()}

@item

@ref{8b3,,os.path.isjunction()}

@tab

@ref{8bb,,Path.is_junction()}

@item

@ref{dd6,,os.path.ismount()}

@tab

@ref{ddb,,Path.is_mount()}

@item

@ref{131b,,os.path.samefile()}

@tab

@ref{11f1,,Path.samefile()}

@item

@ref{1b26,,os.getcwd()}

@tab

@ref{1c9f,,Path.cwd()}

@item

@ref{4f5,,os.stat()}

@tab

@ref{bfc,,Path.stat()}

@item

@ref{8b1,,os.lstat()}

@tab

@ref{2e53,,Path.lstat()}

@item

@ref{14a6,,os.listdir()}

@tab

@ref{4f6,,Path.iterdir()}

@item

@ref{8b9,,os.walk()}

@tab

@ref{8b8,,Path.walk()} @footnote{
@ref{8b9,,os.walk()} always follows symlinks when categorizing paths into
`dirnames' and `filenames', whereas @ref{8b8,,Path.walk()} categorizes all
symlinks into `filenames' when `follow_symlinks' is false (the default.)
}

@item

@ref{72e,,os.mkdir()}, @ref{72f,,os.makedirs()}

@tab

@ref{11f2,,Path.mkdir()}

@item

@ref{149b,,os.link()}

@tab

@ref{bfa,,Path.hardlink_to()}

@item

@ref{14a0,,os.symlink()}

@tab

@ref{bfb,,Path.symlink_to()}

@item

@ref{ced,,os.readlink()}

@tab

@ref{cec,,Path.readlink()}

@item

@ref{149d,,os.rename()}

@tab

@ref{1ab5,,Path.rename()}

@item

@ref{149e,,os.replace()}

@tab

@ref{2e5b,,Path.replace()}

@item

@ref{149c,,os.remove()}, @ref{14a1,,os.unlink()}

@tab

@ref{1fc4,,Path.unlink()}

@item

@ref{149f,,os.rmdir()}

@tab

@ref{2e57,,Path.rmdir()}

@item

@ref{72c,,os.chmod()}

@tab

@ref{bfd,,Path.chmod()}

@item

@ref{72b,,os.lchmod()}

@tab

@ref{2e5d,,Path.lchmod()}

@end multitable


@node Protocols,,Comparison to the os and os path modules,pathlib — Object-oriented filesystem paths
@anchor{library/pathlib module-pathlib types}@anchor{a9}@anchor{library/pathlib protocols}@anchor{2e64}
@subsubsection Protocols


@geindex module; pathlib.types

The @code{pathlib.types} module provides types for static type checking.


Added in version 3.14.


@geindex PathInfo (κλάση σε pathlib.types)
@anchor{library/pathlib pathlib types PathInfo}@anchor{4f4}
@deffn {Κλάση} pathlib.types.PathInfo

A @ref{76c,,typing.Protocol} describing the
@ref{4f3,,Path.info} attribute. Implementations may
return cached results from their methods.

@geindex exists() (μέθοδος της pathlib.types.PathInfo)
@anchor{library/pathlib pathlib types PathInfo exists}@anchor{2e65}
@deffn {Μέθοδος} exists (*, follow_symlinks=True)

Return @code{True} if the path is an existing file or directory, or any
other kind of file; return @code{False} if the path doesn’t exist.

If `follow_symlinks' is @code{False}, return @code{True} for symlinks without
checking if their targets exist.
@end deffn

@geindex is_dir() (μέθοδος της pathlib.types.PathInfo)
@anchor{library/pathlib pathlib types PathInfo is_dir}@anchor{2e66}
@deffn {Μέθοδος} is_dir (*, follow_symlinks=True)

Return @code{True} if the path is a directory, or a symbolic link pointing
to a directory; return @code{False} if the path is (or points to) any other
kind of file, or if it doesn’t exist.

If `follow_symlinks' is @code{False}, return @code{True} only if the path
is a directory (without following symlinks); return @code{False} if the
path is any other kind of file, or if it doesn’t exist.
@end deffn

@geindex is_file() (μέθοδος της pathlib.types.PathInfo)
@anchor{library/pathlib pathlib types PathInfo is_file}@anchor{2e67}
@deffn {Μέθοδος} is_file (*, follow_symlinks=True)

Return @code{True} if the path is a file, or a symbolic link pointing to
a file; return @code{False} if the path is (or points to) a directory or
other non-file, or if it doesn’t exist.

If `follow_symlinks' is @code{False}, return @code{True} only if the path
is a file (without following symlinks); return @code{False} if the path
is a directory or other non-file, or if it doesn’t exist.
@end deffn

@geindex is_symlink() (μέθοδος της pathlib.types.PathInfo)
@anchor{library/pathlib pathlib types PathInfo is_symlink}@anchor{2e68}
@deffn {Μέθοδος} is_symlink ()

Return @code{True} if the path is a symbolic link (even if broken); return
@code{False} if the path is a directory or any kind of file, or if it
doesn’t exist.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node os path — Common pathname manipulations,stat — Interpreting stat results,pathlib — Object-oriented filesystem paths,File and Directory Access
@anchor{library/os path doc}@anchor{2e69}@anchor{library/os path module-os path}@anchor{a6}@anchor{library/os path os-path-common-pathname-manipulations}@anchor{2e6a}@anchor{library/os path translation-repo}@anchor{2e6b}
@subsection @code{os.path} — Common pathname manipulations


@geindex module; os.path

`Source code:' Lib/genericpath.py@footnote{https://github.com/python/cpython/tree/main/Lib/genericpath.py}, Lib/posixpath.py@footnote{https://github.com/python/cpython/tree/main/Lib/posixpath.py} (for POSIX) and
Lib/ntpath.py@footnote{https://github.com/python/cpython/tree/main/Lib/ntpath.py} (for Windows).

@geindex path;operations


__________________________________________________________________


This module implements some useful functions on pathnames. To read or write
files see @ref{32b,,open()}, and for accessing the filesystem see the @ref{a5,,os}
module. The path parameters can be passed as strings, or bytes, or any object
implementing the @ref{100f,,os.PathLike} protocol.

Unlike a Unix shell, Python does not do any `automatic' path expansions.
Functions such as @ref{dd8,,expanduser()} and @ref{177c,,expandvars()} can be invoked
explicitly when an application desires shell-like path expansion.  (See also
the @ref{67,,glob} module.)


@subsubheading Δείτε επίσης


The @ref{a8,,pathlib} module offers high-level path objects.


@cartouche
@quotation Σημείωση 
All of these functions accept either only bytes or only string objects as
their parameters.  The result is an object of the same type, if a path or
file name is returned.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Since different operating systems have different path name conventions, there
are several versions of this module in the standard library.  The
@code{os.path} module is always the path module suitable for the operating
system Python is running on, and therefore usable for local paths.  However,
you can also import and use the individual modules if you want to manipulate
a path that is `always' in one of the different formats.  They all have the
same interface:


@itemize *

@item 
@code{posixpath} for UNIX-style paths

@item 
@code{ntpath} for Windows paths
@end itemize
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.8: @ref{dd2,,exists()}, @ref{dd3,,lexists()}, @ref{dd4,,isdir()}, @ref{dd5,,isfile()},
@ref{dd0,,islink()}, and @ref{dd6,,ismount()} now return @code{False} instead of
raising an exception for paths that contain characters or bytes
unrepresentable at the OS level.


@geindex abspath() (στη μονάδα os.path)
@anchor{library/os path os path abspath}@anchor{16bf}
@deffn {Συνάρτηση} os.path.abspath (path)

Return a normalized absolutized version of the pathname `path'. On most
platforms, this is equivalent to calling @code{normpath(join(os.getcwd(), path))}.


@subsubheading Δείτε επίσης


@ref{1a42,,os.path.join()} and @ref{16be,,os.path.normpath()}.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex basename() (στη μονάδα os.path)
@anchor{library/os path os path basename}@anchor{2e63}
@deffn {Συνάρτηση} os.path.basename (path, /)

Return the base name of pathname `path'.  This is the second element of the
pair returned by passing `path' to the function @ref{2e6c,,split()}.  Note that
the result of this function is different
from the Unix @code{basename} program; where @code{basename} for
@code{'/foo/bar/'} returns @code{'bar'}, the @code{basename()} function returns an
empty string (@code{'@w{'}}).


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex commonpath() (στη μονάδα os.path)
@anchor{library/os path os path commonpath}@anchor{334}
@deffn {Συνάρτηση} os.path.commonpath (paths)

Return the longest common sub-path of each pathname in the iterable
`paths'.  Raise @ref{277,,ValueError} if `paths' contain both absolute
and relative pathnames, if `paths' are on different drives, or
if `paths' is empty.  Unlike @ref{333,,commonprefix()}, this returns a
valid path.


Added in version 3.5.



Άλλαξε στην έκδοση 3.6: Accepts a sequence of @ref{79f,,path-like objects}.



Άλλαξε στην έκδοση 3.13: Any iterable can now be passed, rather than just sequences.

@end deffn

@geindex commonprefix() (στη μονάδα os.path)
@anchor{library/os path os path commonprefix}@anchor{333}
@deffn {Συνάρτηση} os.path.commonprefix (list, /)

Return the longest string prefix (taken character-by-character) that is a
prefix of all strings in `list'.  If `list' is empty, return the empty string
(@code{'@w{'}}).

@cartouche
@quotation Προειδοποίηση 
This function may return invalid paths because it works a
character at a time.
If you need a `common path prefix', then the algorithm
implemented in this function is not secure. Use
@ref{334,,commonpath()} for finding a common path prefix.

@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


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Αποσύρθηκε στην έκδοση 3.15: Deprecated in favor of @ref{334,,os.path.commonpath()} for path prefixes.
The @ref{333,,os.path.commonprefix()} function is being deprecated due to
having a misleading name and module. The function is not safe to use for
path prefixes despite being included in a module about path manipulation,
meaning it is easy to accidentally introduce path traversal
vulnerabilities into Python programs by using this function.

@end deffn

@geindex dirname() (στη μονάδα os.path)
@anchor{library/os path os path dirname}@anchor{2e62}
@deffn {Συνάρτηση} 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{2e6c,,split()}.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex exists() (στη μονάδα os.path)
@anchor{library/os path os path exists}@anchor{dd2}
@deffn {Συνάρτηση} 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{4f5,,os.stat()} on the requested file, even
if the `path' physically exists.


Άλλαξε στην έκδοση 3.3: `path' can now be an integer: @code{True} is returned if it is an
 open file descriptor, @code{False} otherwise.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex lexists() (στη μονάδα os.path)
@anchor{library/os path os path lexists}@anchor{dd3}
@deffn {Συνάρτηση} os.path.lexists (path)

Return @code{True} if `path' refers to an existing path, including
broken symbolic links.   Equivalent to @ref{dd2,,exists()} on platforms lacking
@ref{8b1,,os.lstat()}.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex ~ (tilde);home directory expansion

@geindex expanduser() (στη μονάδα os.path)
@anchor{library/os path os path expanduser}@anchor{dd8}
@deffn {Συνάρτηση} 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 μεταβλητή περιβάλλοντος; 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{ba,,pwd}. An initial @code{~user}
is looked up directly in the password directory.

On Windows, 
@geindex USERPROFILE
@geindex μεταβλητή περιβάλλοντος; USERPROFILE
@code{USERPROFILE} will be used if set, otherwise a combination
of 
@geindex HOMEPATH
@geindex μεταβλητή περιβάλλοντος; HOMEPATH
@code{HOMEPATH} and 
@geindex HOMEDRIVE
@geindex μεταβλητή περιβάλλοντος; 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 μεταβλητή περιβάλλοντος; 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.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.8: No longer uses 
@geindex HOME
@geindex μεταβλητή περιβάλλοντος; HOME
@code{HOME} on Windows.

@end deffn

@geindex $ (dollar);environment variables expansion
@geindex % (percent);environment variables expansion (Windows)

@geindex expandvars() (στη μονάδα os.path)
@anchor{library/os path os path expandvars}@anchor{177c}
@deffn {Συνάρτηση} 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@}}.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex getatime() (στη μονάδα os.path)
@anchor{library/os path os path getatime}@anchor{2e6d}
@deffn {Συνάρτηση} 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{f7,,time} module).  Raise
@ref{53c,,OSError} if the file does not exist or is inaccessible.
@end deffn

@geindex getmtime() (στη μονάδα os.path)
@anchor{library/os path os path getmtime}@anchor{2e6e}
@deffn {Συνάρτηση} 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{f7,,time} module).
Raise @ref{53c,,OSError} if the file does not exist or is inaccessible.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex getctime() (στη μονάδα os.path)
@anchor{library/os path os path getctime}@anchor{2e6f}
@deffn {Συνάρτηση} 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{f7,,time} module).  Raise @ref{53c,,OSError} if the file does not exist or
is inaccessible.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex getsize() (στη μονάδα os.path)
@anchor{library/os path os path getsize}@anchor{2e70}
@deffn {Συνάρτηση} os.path.getsize (path, /)

Return the size, in bytes, of `path'.  Raise @ref{53c,,OSError} if the file does
not exist or is inaccessible.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex isabs() (στη μονάδα os.path)
@anchor{library/os path os path isabs}@anchor{734}
@deffn {Συνάρτηση} 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.


@subsubheading Δείτε επίσης


@ref{16bf,,abspath()}



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.13: On Windows, returns @code{False} if the given path starts with exactly one
(back)slash.

@end deffn

@geindex isfile() (στη μονάδα os.path)
@anchor{library/os path os path isfile}@anchor{dd5}
@deffn {Συνάρτηση} os.path.isfile (path)

Return @code{True} if `path' is an @ref{dd2,,existing} regular file.
This follows symbolic links, so both @ref{dd0,,islink()} and @code{isfile()} can
be true for the same path.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex isdir() (στη μονάδα os.path)
@anchor{library/os path os path isdir}@anchor{dd4}
@deffn {Συνάρτηση} os.path.isdir (path, /)

Return @code{True} if `path' is an @ref{dd2,,existing} directory.  This
follows symbolic links, so both @ref{dd0,,islink()} and @code{isdir()} can be true
for the same path.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex isjunction() (στη μονάδα os.path)
@anchor{library/os path os path isjunction}@anchor{8b3}
@deffn {Συνάρτηση} os.path.isjunction (path)

Return @code{True} if `path' refers to an @ref{dd3,,existing} directory
entry that is a junction.  Always return @code{False} if junctions are not
supported on the current platform.


Added in version 3.12.

@end deffn

@geindex islink() (στη μονάδα os.path)
@anchor{library/os path os path islink}@anchor{dd0}
@deffn {Συνάρτηση} os.path.islink (path)

Return @code{True} if `path' refers to an @ref{dd2,,existing} directory
entry that is a symbolic link.  Always @code{False} if symbolic links are not
supported by the Python runtime.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex ismount() (στη μονάδα os.path)
@anchor{library/os path os path ismount}@anchor{dd6}
@deffn {Συνάρτηση} 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 Linux systems, it will always return @code{True} for btrfs
subvolumes, even if they aren’t mount points. 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.


Άλλαξε στην έκδοση 3.4: Added support for detecting non-root mount points on Windows.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex isdevdrive() (στη μονάδα os.path)
@anchor{library/os path os path isdevdrive}@anchor{1bcc}
@deffn {Συνάρτηση} 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.


Added in version 3.12.



Άλλαξε στην έκδοση 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() (στη μονάδα os.path)
@anchor{library/os path os path isreserved}@anchor{2d9}
@deffn {Συνάρτηση} 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 Σημείωση 
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{232d,,Διαθεσιμότητα}: Windows.


Added in version 3.13.

@end deffn

@geindex join() (στη μονάδα os.path)
@anchor{library/os path os path join}@anchor{1a42}
@deffn {Συνάρτηση} 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 Linux, for example:

@example
>>> os.path.join('/home/foo', 'bar')
'/home/foo/bar'
>>> os.path.join('/home/foo', '/home/bar')
'/home/bar'
@end example

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. For
example:

@example
>>> os.path.join('c:\\', 'foo')
'c:\\foo'
>>> os.path.join('c:\\foo', 'd:\\bar')
'd:\\bar'
@end example

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}.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object} for `path' and `paths'.

@end deffn

@geindex normcase() (στη μονάδα os.path)
@anchor{library/os path os path normcase}@anchor{2e71}
@deffn {Συνάρτηση} 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.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex normpath() (στη μονάδα os.path)
@anchor{library/os path os path normpath}@anchor{16be}
@deffn {Συνάρτηση} 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{2e71,,normcase()}.

@cartouche
@quotation Σημείωση 
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


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex realpath() (στη μονάδα os.path)
@anchor{library/os path os path realpath}@anchor{241}
@deffn {Συνάρτηση} 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}.

By default, the path is evaluated up to the first component that does not
exist, is a symlink loop, or whose evaluation raises @ref{53c,,OSError}.
All such components are appended unchanged to the existing part of the path.

Some errors that are handled this way include «access denied», «not a
directory», or «bad argument to internal function». Thus, the
resulting path may be missing or inaccessible, may still contain
links or loops, and may traverse non-directories.

This behavior can be modified by keyword arguments:

If `strict' is @code{True}, the first error encountered when evaluating the path is
re-raised.
In particular, @ref{243,,FileNotFoundError} is raised if `path' does not exist,
or another @ref{53c,,OSError} if it is otherwise inaccessible.
If `strict' is @ref{2e72,,ALL_BUT_LAST}, the last component of the path
is allowed to be missing, but all other errors are raised.

If `strict' is @ref{242,,os.path.ALLOW_MISSING}, errors other than
@ref{243,,FileNotFoundError} are re-raised (as with @code{strict=True}).
Thus, the returned path will not contain any symbolic links, but the named
file and some of its parent directories may be missing.

@cartouche
@quotation Σημείωση 
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


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.8: Symbolic links and junctions are now resolved on Windows.



Άλλαξε στην έκδοση 3.10: The `strict' parameter was added.



Άλλαξε στην έκδοση 3.15: The @ref{2e72,,ALL_BUT_LAST} and @ref{242,,ALLOW_MISSING} values for
the `strict' parameter was added.

@end deffn

@geindex ALL_BUT_LAST (στη μονάδα os.path)
@anchor{library/os path os path ALL_BUT_LAST}@anchor{2e72}
@deffn {Δεδομένα} os.path.ALL_BUT_LAST

Special value used for the `strict' argument in @ref{241,,realpath()}.


Added in version 3.15.

@end deffn

@geindex ALLOW_MISSING (στη μονάδα os.path)
@anchor{library/os path os path ALLOW_MISSING}@anchor{242}
@deffn {Δεδομένα} os.path.ALLOW_MISSING

Special value used for the `strict' argument in @ref{241,,realpath()}.


Added in version 3.15.

@end deffn

@geindex relpath() (στη μονάδα os.path)
@anchor{library/os path os path relpath}@anchor{8ba}
@deffn {Συνάρτηση} 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{277,,ValueError} is raised when `path' and `start'
are on different drives.

`start' defaults to @ref{2e73,,os.curdir}.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex samefile() (στη μονάδα os.path)
@anchor{library/os path os path samefile}@anchor{131b}
@deffn {Συνάρτηση} 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{4f5,,os.stat()} call on either pathname fails.


Άλλαξε στην έκδοση 3.2: Added Windows support.



Άλλαξε στην έκδοση 3.4: Windows now uses the same implementation as all other platforms.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex sameopenfile() (στη μονάδα os.path)
@anchor{library/os path os path sameopenfile}@anchor{2e74}
@deffn {Συνάρτηση} os.path.sameopenfile (fp1, fp2)

Return @code{True} if the file descriptors `fp1' and `fp2' refer to the same file.


Άλλαξε στην έκδοση 3.2: Added Windows support.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex samestat() (στη μονάδα os.path)
@anchor{library/os path os path samestat}@anchor{131a}
@deffn {Συνάρτηση} 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{1145,,os.fstat()},
@ref{8b1,,os.lstat()}, or @ref{4f5,,os.stat()}.  This function implements the
underlying comparison used by @ref{131b,,samefile()} and @ref{2e74,,sameopenfile()}.


Άλλαξε στην έκδοση 3.4: Added Windows support.

@end deffn

@geindex split() (στη μονάδα os.path)
@anchor{library/os path os path split}@anchor{2e6c}
@deffn {Συνάρτηση} 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{1a42,,join()},
@ref{2e62,,dirname()} and @ref{2e63,,basename()}.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex splitdrive() (στη μονάδα os.path)
@anchor{library/os path os path splitdrive}@anchor{fb4}
@deffn {Συνάρτηση} 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


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex splitroot() (στη μονάδα os.path)
@anchor{library/os path os path splitroot}@anchor{8b4}
@deffn {Συνάρτηση} 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


Added in version 3.12.

@end deffn

@geindex splitext() (στη μονάδα os.path)
@anchor{library/os path os path splitext}@anchor{1b6d}
@deffn {Συνάρτηση} 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


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex supports_unicode_filenames (στη μονάδα os.path)
@anchor{library/os path os path supports_unicode_filenames}@anchor{1830}
@deffn {Δεδομένα} 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node stat — Interpreting stat results,filecmp — File and Directory Comparisons,os path — Common pathname manipulations,File and Directory Access
@anchor{library/stat doc}@anchor{2e75}@anchor{library/stat module-stat}@anchor{d9}@anchor{library/stat stat-interpreting-stat-results}@anchor{2e76}@anchor{library/stat translation-repo}@anchor{2e77}
@subsection @code{stat} — Interpreting @code{stat()} results


@geindex module; stat

`Source code:' Lib/stat.py@footnote{https://github.com/python/cpython/tree/main/Lib/stat.py}


__________________________________________________________________


The @code{stat} module defines constants and functions for interpreting the
results of @ref{4f5,,os.stat()}, @ref{1145,,os.fstat()} and @ref{8b1,,os.lstat()} (if they
exist).  For complete details about the @code{stat()}, @code{fstat()} and
@code{lstat()} calls, consult the documentation for your system.


Άλλαξε στην έκδοση 3.4: The stat module is backed by a C implementation.


The @code{stat} module defines the following functions to test for specific file
types:

@geindex S_ISDIR() (στη μονάδα stat)
@anchor{library/stat stat S_ISDIR}@anchor{2e78}
@deffn {Συνάρτηση} stat.S_ISDIR (mode)

Return non-zero if the mode is from a directory.
@end deffn

@geindex S_ISCHR() (στη μονάδα stat)
@anchor{library/stat stat S_ISCHR}@anchor{2e79}
@deffn {Συνάρτηση} stat.S_ISCHR (mode)

Return non-zero if the mode is from a character special device file.
@end deffn

@geindex S_ISBLK() (στη μονάδα stat)
@anchor{library/stat stat S_ISBLK}@anchor{2e7a}
@deffn {Συνάρτηση} stat.S_ISBLK (mode)

Return non-zero if the mode is from a block special device file.
@end deffn

@geindex S_ISREG() (στη μονάδα stat)
@anchor{library/stat stat S_ISREG}@anchor{2e7b}
@deffn {Συνάρτηση} stat.S_ISREG (mode)

Return non-zero if the mode is from a regular file.
@end deffn

@geindex S_ISFIFO() (στη μονάδα stat)
@anchor{library/stat stat S_ISFIFO}@anchor{2e7c}
@deffn {Συνάρτηση} stat.S_ISFIFO (mode)

Return non-zero if the mode is from a FIFO (named pipe).
@end deffn

@geindex S_ISLNK() (στη μονάδα stat)
@anchor{library/stat stat S_ISLNK}@anchor{2e7d}
@deffn {Συνάρτηση} stat.S_ISLNK (mode)

Return non-zero if the mode is from a symbolic link.
@end deffn

@geindex S_ISSOCK() (στη μονάδα stat)
@anchor{library/stat stat S_ISSOCK}@anchor{2e7e}
@deffn {Συνάρτηση} stat.S_ISSOCK (mode)

Return non-zero if the mode is from a socket.
@end deffn

@geindex S_ISDOOR() (στη μονάδα stat)
@anchor{library/stat stat S_ISDOOR}@anchor{1f9c}
@deffn {Συνάρτηση} stat.S_ISDOOR (mode)

Return non-zero if the mode is from a door.


Added in version 3.4.

@end deffn

@geindex S_ISPORT() (στη μονάδα stat)
@anchor{library/stat stat S_ISPORT}@anchor{1f9d}
@deffn {Συνάρτηση} stat.S_ISPORT (mode)

Return non-zero if the mode is from an event port.


Added in version 3.4.

@end deffn

@geindex S_ISWHT() (στη μονάδα stat)
@anchor{library/stat stat S_ISWHT}@anchor{1f9e}
@deffn {Συνάρτηση} stat.S_ISWHT (mode)

Return non-zero if the mode is from a whiteout.


Added in version 3.4.

@end deffn

Two additional functions are defined for more general manipulation of the file’s
mode:

@geindex S_IMODE() (στη μονάδα stat)
@anchor{library/stat stat S_IMODE}@anchor{2e7f}
@deffn {Συνάρτηση} stat.S_IMODE (mode)

Return the portion of the file’s mode that can be set by
@ref{72c,,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() (στη μονάδα stat)
@anchor{library/stat stat S_IFMT}@anchor{2e80}
@deffn {Συνάρτηση} 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{a6,,os.path}, like the tests for block and character
devices.

Example:

@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() (στη μονάδα stat)
@anchor{library/stat stat filemode}@anchor{14f6}
@deffn {Συνάρτηση} stat.filemode (mode)

Convert a file’s mode to a string of the form “-rwxrwxrwx”.


Added in version 3.3.



Άλλαξε στην έκδοση 3.4: The function supports @ref{1364,,S_IFDOOR}, @ref{1365,,S_IFPORT} and
@ref{1366,,S_IFWHT}.

@end deffn

All the variables below are simply symbolic indexes into the 10-tuple returned
by @ref{4f5,,os.stat()}, @ref{1145,,os.fstat()} or @ref{8b1,,os.lstat()}.

@geindex ST_MODE (στη μονάδα stat)
@anchor{library/stat stat ST_MODE}@anchor{1363}
@deffn {Δεδομένα} stat.ST_MODE

Inode protection mode.
@end deffn

@geindex ST_INO (στη μονάδα stat)
@anchor{library/stat stat ST_INO}@anchor{2e81}
@deffn {Δεδομένα} stat.ST_INO

Inode number.
@end deffn

@geindex ST_DEV (στη μονάδα stat)
@anchor{library/stat stat ST_DEV}@anchor{2e82}
@deffn {Δεδομένα} stat.ST_DEV

Device inode resides on.
@end deffn

@geindex ST_NLINK (στη μονάδα stat)
@anchor{library/stat stat ST_NLINK}@anchor{2e83}
@deffn {Δεδομένα} stat.ST_NLINK

Number of links to the inode.
@end deffn

@geindex ST_UID (στη μονάδα stat)
@anchor{library/stat stat ST_UID}@anchor{2e84}
@deffn {Δεδομένα} stat.ST_UID

User id of the owner.
@end deffn

@geindex ST_GID (στη μονάδα stat)
@anchor{library/stat stat ST_GID}@anchor{2e85}
@deffn {Δεδομένα} stat.ST_GID

Group id of the owner.
@end deffn

@geindex ST_SIZE (στη μονάδα stat)
@anchor{library/stat stat ST_SIZE}@anchor{2e86}
@deffn {Δεδομένα} stat.ST_SIZE

Size in bytes of a plain file; amount of data waiting on some special files.
@end deffn

@geindex ST_ATIME (στη μονάδα stat)
@anchor{library/stat stat ST_ATIME}@anchor{2e87}
@deffn {Δεδομένα} stat.ST_ATIME

Time of last access.
@end deffn

@geindex ST_MTIME (στη μονάδα stat)
@anchor{library/stat stat ST_MTIME}@anchor{2e88}
@deffn {Δεδομένα} stat.ST_MTIME

Time of last modification.
@end deffn

@geindex ST_CTIME (στη μονάδα stat)
@anchor{library/stat stat ST_CTIME}@anchor{2e89}
@deffn {Δεδομένα} 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{4f5,,os.stat()},
@ref{1145,,os.fstat()}, or @ref{8b1,,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{1363,,ST_MODE} field.

Use of the functions above is more portable than use of the first set of flags:

@geindex S_IFSOCK (στη μονάδα stat)
@anchor{library/stat stat S_IFSOCK}@anchor{2e8a}
@deffn {Δεδομένα} stat.S_IFSOCK

Socket.
@end deffn

@geindex S_IFLNK (στη μονάδα stat)
@anchor{library/stat stat S_IFLNK}@anchor{2e8b}
@deffn {Δεδομένα} stat.S_IFLNK

Symbolic link.
@end deffn

@geindex S_IFREG (στη μονάδα stat)
@anchor{library/stat stat S_IFREG}@anchor{2e8c}
@deffn {Δεδομένα} stat.S_IFREG

Regular file.
@end deffn

@geindex S_IFBLK (στη μονάδα stat)
@anchor{library/stat stat S_IFBLK}@anchor{2e8d}
@deffn {Δεδομένα} stat.S_IFBLK

Block device.
@end deffn

@geindex S_IFDIR (στη μονάδα stat)
@anchor{library/stat stat S_IFDIR}@anchor{2e8e}
@deffn {Δεδομένα} stat.S_IFDIR

Directory.
@end deffn

@geindex S_IFCHR (στη μονάδα stat)
@anchor{library/stat stat S_IFCHR}@anchor{2e8f}
@deffn {Δεδομένα} stat.S_IFCHR

Character device.
@end deffn

@geindex S_IFIFO (στη μονάδα stat)
@anchor{library/stat stat S_IFIFO}@anchor{2e90}
@deffn {Δεδομένα} stat.S_IFIFO

FIFO.
@end deffn

@geindex S_IFDOOR (στη μονάδα stat)
@anchor{library/stat stat S_IFDOOR}@anchor{1364}
@deffn {Δεδομένα} stat.S_IFDOOR

Door.


Added in version 3.4.

@end deffn

@geindex S_IFPORT (στη μονάδα stat)
@anchor{library/stat stat S_IFPORT}@anchor{1365}
@deffn {Δεδομένα} stat.S_IFPORT

Event port.


Added in version 3.4.

@end deffn

@geindex S_IFWHT (στη μονάδα stat)
@anchor{library/stat stat S_IFWHT}@anchor{1366}
@deffn {Δεδομένα} stat.S_IFWHT

Whiteout.


Added in version 3.4.

@end deffn

@cartouche
@quotation Σημείωση 
@ref{1364,,S_IFDOOR}, @ref{1365,,S_IFPORT} or @ref{1366,,S_IFWHT} are defined as
0 when the platform does not have support for the file types.
@end quotation
@end cartouche

The following flags can also be used in the `mode' argument of @ref{72c,,os.chmod()}:

@geindex S_ISUID (στη μονάδα stat)
@anchor{library/stat stat S_ISUID}@anchor{2e91}
@deffn {Δεδομένα} stat.S_ISUID

Set UID bit.
@end deffn

@geindex S_ISGID (στη μονάδα stat)
@anchor{library/stat stat S_ISGID}@anchor{2e92}
@deffn {Δεδομένα} 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 @code{S_ISGID} bit set.  For a
file that does not have the group execution bit (@ref{2e93,,S_IXGRP})
set, the set-group-ID bit indicates mandatory file/record locking
(see also @ref{2e94,,S_ENFMT}).
@end deffn

@geindex S_ISVTX (στη μονάδα stat)
@anchor{library/stat stat S_ISVTX}@anchor{2e95}
@deffn {Δεδομένα} 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 (στη μονάδα stat)
@anchor{library/stat stat S_IRWXU}@anchor{2e96}
@deffn {Δεδομένα} stat.S_IRWXU

Mask for file owner permissions.
@end deffn

@geindex S_IRUSR (στη μονάδα stat)
@anchor{library/stat stat S_IRUSR}@anchor{2e97}
@deffn {Δεδομένα} stat.S_IRUSR

Owner has read permission.
@end deffn

@geindex S_IWUSR (στη μονάδα stat)
@anchor{library/stat stat S_IWUSR}@anchor{2e98}
@deffn {Δεδομένα} stat.S_IWUSR

Owner has write permission.
@end deffn

@geindex S_IXUSR (στη μονάδα stat)
@anchor{library/stat stat S_IXUSR}@anchor{2e99}
@deffn {Δεδομένα} stat.S_IXUSR

Owner has execute permission.
@end deffn

@geindex S_IRWXG (στη μονάδα stat)
@anchor{library/stat stat S_IRWXG}@anchor{2e9a}
@deffn {Δεδομένα} stat.S_IRWXG

Mask for group permissions.
@end deffn

@geindex S_IRGRP (στη μονάδα stat)
@anchor{library/stat stat S_IRGRP}@anchor{2e9b}
@deffn {Δεδομένα} stat.S_IRGRP

Group has read permission.
@end deffn

@geindex S_IWGRP (στη μονάδα stat)
@anchor{library/stat stat S_IWGRP}@anchor{2e9c}
@deffn {Δεδομένα} stat.S_IWGRP

Group has write permission.
@end deffn

@geindex S_IXGRP (στη μονάδα stat)
@anchor{library/stat stat S_IXGRP}@anchor{2e93}
@deffn {Δεδομένα} stat.S_IXGRP

Group has execute permission.
@end deffn

@geindex S_IRWXO (στη μονάδα stat)
@anchor{library/stat stat S_IRWXO}@anchor{2e9d}
@deffn {Δεδομένα} stat.S_IRWXO

Mask for permissions for others (not in group).
@end deffn

@geindex S_IROTH (στη μονάδα stat)
@anchor{library/stat stat S_IROTH}@anchor{2e9e}
@deffn {Δεδομένα} stat.S_IROTH

Others have read permission.
@end deffn

@geindex S_IWOTH (στη μονάδα stat)
@anchor{library/stat stat S_IWOTH}@anchor{2e9f}
@deffn {Δεδομένα} stat.S_IWOTH

Others have write permission.
@end deffn

@geindex S_IXOTH (στη μονάδα stat)
@anchor{library/stat stat S_IXOTH}@anchor{2ea0}
@deffn {Δεδομένα} stat.S_IXOTH

Others have execute permission.
@end deffn

@geindex S_ENFMT (στη μονάδα stat)
@anchor{library/stat stat S_ENFMT}@anchor{2e94}
@deffn {Δεδομένα} stat.S_ENFMT

System V file locking enforcement.  This flag is shared with @ref{2e92,,S_ISGID}:
file/record locking is enforced on files that do not have the group
execution bit (@ref{2e93,,S_IXGRP}) set.
@end deffn

@geindex S_IREAD (στη μονάδα stat)
@anchor{library/stat stat S_IREAD}@anchor{2ea1}
@deffn {Δεδομένα} stat.S_IREAD

Unix V7 synonym for @ref{2e97,,S_IRUSR}.
@end deffn

@geindex S_IWRITE (στη μονάδα stat)
@anchor{library/stat stat S_IWRITE}@anchor{2ea2}
@deffn {Δεδομένα} stat.S_IWRITE

Unix V7 synonym for @ref{2e98,,S_IWUSR}.
@end deffn

@geindex S_IEXEC (στη μονάδα stat)
@anchor{library/stat stat S_IEXEC}@anchor{2ea3}
@deffn {Δεδομένα} stat.S_IEXEC

Unix V7 synonym for @ref{2e99,,S_IXUSR}.
@end deffn

The following flags can be used in the `flags' argument of @ref{1499,,os.chflags()}:

@geindex UF_SETTABLE (στη μονάδα stat)
@anchor{library/stat stat UF_SETTABLE}@anchor{2ea4}
@deffn {Δεδομένα} stat.UF_SETTABLE

All user settable flags.


Added in version 3.13.

@end deffn

@geindex UF_NODUMP (στη μονάδα stat)
@anchor{library/stat stat UF_NODUMP}@anchor{2ea5}
@deffn {Δεδομένα} stat.UF_NODUMP

Do not dump the file.
@end deffn

@geindex UF_IMMUTABLE (στη μονάδα stat)
@anchor{library/stat stat UF_IMMUTABLE}@anchor{2ea6}
@deffn {Δεδομένα} stat.UF_IMMUTABLE

The file may not be changed.
@end deffn

@geindex UF_APPEND (στη μονάδα stat)
@anchor{library/stat stat UF_APPEND}@anchor{2ea7}
@deffn {Δεδομένα} stat.UF_APPEND

The file may only be appended to.
@end deffn

@geindex UF_OPAQUE (στη μονάδα stat)
@anchor{library/stat stat UF_OPAQUE}@anchor{2ea8}
@deffn {Δεδομένα} stat.UF_OPAQUE

The directory is opaque when viewed through a union stack.
@end deffn

@geindex UF_NOUNLINK (στη μονάδα stat)
@anchor{library/stat stat UF_NOUNLINK}@anchor{2ea9}
@deffn {Δεδομένα} stat.UF_NOUNLINK

The file may not be renamed or deleted.
@end deffn

@geindex UF_COMPRESSED (στη μονάδα stat)
@anchor{library/stat stat UF_COMPRESSED}@anchor{2eaa}
@deffn {Δεδομένα} stat.UF_COMPRESSED

The file is stored compressed (macOS 10.6+).
@end deffn

@geindex UF_TRACKED (στη μονάδα stat)
@anchor{library/stat stat UF_TRACKED}@anchor{2eab}
@deffn {Δεδομένα} stat.UF_TRACKED

Used for handling document IDs (macOS)


Added in version 3.13.

@end deffn

@geindex UF_DATAVAULT (στη μονάδα stat)
@anchor{library/stat stat UF_DATAVAULT}@anchor{2eac}
@deffn {Δεδομένα} stat.UF_DATAVAULT

The file needs an entitlement for reading or writing (macOS 10.13+)


Added in version 3.13.

@end deffn

@geindex UF_HIDDEN (στη μονάδα stat)
@anchor{library/stat stat UF_HIDDEN}@anchor{2ead}
@deffn {Δεδομένα} stat.UF_HIDDEN

The file should not be displayed in a GUI (macOS 10.5+).
@end deffn

@geindex SF_SETTABLE (στη μονάδα stat)
@anchor{library/stat stat SF_SETTABLE}@anchor{2eae}
@deffn {Δεδομένα} stat.SF_SETTABLE

All super-user changeable flags


Added in version 3.13.

@end deffn

@geindex SF_SUPPORTED (στη μονάδα stat)
@anchor{library/stat stat SF_SUPPORTED}@anchor{2eaf}
@deffn {Δεδομένα} stat.SF_SUPPORTED

All super-user supported flags

@ref{232d,,Διαθεσιμότητα}: macOS


Added in version 3.13.

@end deffn

@geindex SF_SYNTHETIC (στη μονάδα stat)
@anchor{library/stat stat SF_SYNTHETIC}@anchor{2eb0}
@deffn {Δεδομένα} stat.SF_SYNTHETIC

All super-user read-only synthetic flags

@ref{232d,,Διαθεσιμότητα}: macOS


Added in version 3.13.

@end deffn

@geindex SF_ARCHIVED (στη μονάδα stat)
@anchor{library/stat stat SF_ARCHIVED}@anchor{2eb1}
@deffn {Δεδομένα} stat.SF_ARCHIVED

The file may be archived.
@end deffn

@geindex SF_IMMUTABLE (στη μονάδα stat)
@anchor{library/stat stat SF_IMMUTABLE}@anchor{2eb2}
@deffn {Δεδομένα} stat.SF_IMMUTABLE

The file may not be changed.
@end deffn

@geindex SF_APPEND (στη μονάδα stat)
@anchor{library/stat stat SF_APPEND}@anchor{2eb3}
@deffn {Δεδομένα} stat.SF_APPEND

The file may only be appended to.
@end deffn

@geindex SF_RESTRICTED (στη μονάδα stat)
@anchor{library/stat stat SF_RESTRICTED}@anchor{2eb4}
@deffn {Δεδομένα} stat.SF_RESTRICTED

The file needs an entitlement to write to (macOS 10.13+)


Added in version 3.13.

@end deffn

@geindex SF_NOUNLINK (στη μονάδα stat)
@anchor{library/stat stat SF_NOUNLINK}@anchor{2eb5}
@deffn {Δεδομένα} stat.SF_NOUNLINK

The file may not be renamed or deleted.
@end deffn

@geindex SF_SNAPSHOT (στη μονάδα stat)
@anchor{library/stat stat SF_SNAPSHOT}@anchor{2eb6}
@deffn {Δεδομένα} stat.SF_SNAPSHOT

The file is a snapshot file.
@end deffn

@geindex SF_FIRMLINK (στη μονάδα stat)
@anchor{library/stat stat SF_FIRMLINK}@anchor{2eb7}
@deffn {Δεδομένα} stat.SF_FIRMLINK

The file is a firmlink (macOS 10.15+)


Added in version 3.13.

@end deffn

@geindex SF_DATALESS (στη μονάδα stat)
@anchor{library/stat stat SF_DATALESS}@anchor{2eb8}
@deffn {Δεδομένα} stat.SF_DATALESS

The file is a dataless object (macOS 10.15+)


Added in 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{4f5,,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 (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_COMPRESSED (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_DEVICE (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_DIRECTORY (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_ENCRYPTED (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_HIDDEN (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_INTEGRITY_STREAM (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_NORMAL (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_NO_SCRUB_DATA (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_OFFLINE (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_READONLY (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_REPARSE_POINT (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_SPARSE_FILE (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_SYSTEM (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_TEMPORARY (στη μονάδα stat)
@geindex FILE_ATTRIBUTE_VIRTUAL (στη μονάδα stat)
@anchor{library/stat stat FILE_ATTRIBUTE_ARCHIVE}@anchor{2eb9}
@deffn {Δεδομένα} stat.FILE_ATTRIBUTE_ARCHIVE
@anchor{library/stat stat FILE_ATTRIBUTE_COMPRESSED}@anchor{2eba}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_COMPRESSED
@anchor{library/stat stat FILE_ATTRIBUTE_DEVICE}@anchor{2ebb}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_DEVICE
@anchor{library/stat stat FILE_ATTRIBUTE_DIRECTORY}@anchor{2ebc}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_DIRECTORY
@anchor{library/stat stat FILE_ATTRIBUTE_ENCRYPTED}@anchor{2ebd}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_ENCRYPTED
@anchor{library/stat stat FILE_ATTRIBUTE_HIDDEN}@anchor{2ebe}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_HIDDEN
@anchor{library/stat stat FILE_ATTRIBUTE_INTEGRITY_STREAM}@anchor{2ebf}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_INTEGRITY_STREAM
@anchor{library/stat stat FILE_ATTRIBUTE_NORMAL}@anchor{2ec0}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_NORMAL
@anchor{library/stat stat FILE_ATTRIBUTE_NOT_CONTENT_INDEXED}@anchor{2ec1}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
@anchor{library/stat stat FILE_ATTRIBUTE_NO_SCRUB_DATA}@anchor{2ec2}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_NO_SCRUB_DATA
@anchor{library/stat stat FILE_ATTRIBUTE_OFFLINE}@anchor{2ec3}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_OFFLINE
@anchor{library/stat stat FILE_ATTRIBUTE_READONLY}@anchor{2ec4}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_READONLY
@anchor{library/stat stat FILE_ATTRIBUTE_REPARSE_POINT}@anchor{2ec5}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_REPARSE_POINT
@anchor{library/stat stat FILE_ATTRIBUTE_SPARSE_FILE}@anchor{2ec6}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_SPARSE_FILE
@anchor{library/stat stat FILE_ATTRIBUTE_SYSTEM}@anchor{2ec7}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_SYSTEM
@anchor{library/stat stat FILE_ATTRIBUTE_TEMPORARY}@anchor{2ec8}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_TEMPORARY
@anchor{library/stat stat FILE_ATTRIBUTE_VIRTUAL}@anchor{2ec9}
@deffnx {Δεδομένα} stat.FILE_ATTRIBUTE_VIRTUAL


Added in version 3.5.

@end deffn

On Windows, the following constants are available for comparing against the
@code{st_reparse_tag} member returned by @ref{8b1,,os.lstat()}. These are well-known
constants, but are not an exhaustive list.

@geindex IO_REPARSE_TAG_SYMLINK (στη μονάδα stat)
@geindex IO_REPARSE_TAG_MOUNT_POINT (στη μονάδα stat)
@geindex IO_REPARSE_TAG_APPEXECLINK (στη μονάδα stat)
@anchor{library/stat stat IO_REPARSE_TAG_SYMLINK}@anchor{2eca}
@deffn {Δεδομένα} stat.IO_REPARSE_TAG_SYMLINK
@anchor{library/stat stat IO_REPARSE_TAG_MOUNT_POINT}@anchor{2ecb}
@deffnx {Δεδομένα} stat.IO_REPARSE_TAG_MOUNT_POINT
@anchor{library/stat stat IO_REPARSE_TAG_APPEXECLINK}@anchor{2ecc}
@deffnx {Δεδομένα} stat.IO_REPARSE_TAG_APPEXECLINK


Added in version 3.8.

@end deffn

On Linux, the following file attribute constants are available for use when
testing bits in the @ref{2ecd,,stx_attributes} and
@ref{2ece,,stx_attributes_mask} members returned by
@ref{23f,,os.statx()}.  See the @code{statx(2)@footnote{https://manpages.debian.org/statx(2)}} man page for more detail on the
meaning of these constants.

@geindex STATX_ATTR_COMPRESSED (στη μονάδα stat)
@geindex STATX_ATTR_IMMUTABLE (στη μονάδα stat)
@geindex STATX_ATTR_APPEND (στη μονάδα stat)
@geindex STATX_ATTR_NODUMP (στη μονάδα stat)
@geindex STATX_ATTR_ENCRYPTED (στη μονάδα stat)
@geindex STATX_ATTR_AUTOMOUNT (στη μονάδα stat)
@geindex STATX_ATTR_MOUNT_ROOT (στη μονάδα stat)
@geindex STATX_ATTR_VERITY (στη μονάδα stat)
@geindex STATX_ATTR_DAX (στη μονάδα stat)
@geindex STATX_ATTR_WRITE_ATOMIC (στη μονάδα stat)
@anchor{library/stat stat STATX_ATTR_COMPRESSED}@anchor{2ecf}
@deffn {Δεδομένα} stat.STATX_ATTR_COMPRESSED
@anchor{library/stat stat STATX_ATTR_IMMUTABLE}@anchor{2ed0}
@deffnx {Δεδομένα} stat.STATX_ATTR_IMMUTABLE
@anchor{library/stat stat STATX_ATTR_APPEND}@anchor{2ed1}
@deffnx {Δεδομένα} stat.STATX_ATTR_APPEND
@anchor{library/stat stat STATX_ATTR_NODUMP}@anchor{2ed2}
@deffnx {Δεδομένα} stat.STATX_ATTR_NODUMP
@anchor{library/stat stat STATX_ATTR_ENCRYPTED}@anchor{2ed3}
@deffnx {Δεδομένα} stat.STATX_ATTR_ENCRYPTED
@anchor{library/stat stat STATX_ATTR_AUTOMOUNT}@anchor{2ed4}
@deffnx {Δεδομένα} stat.STATX_ATTR_AUTOMOUNT
@anchor{library/stat stat STATX_ATTR_MOUNT_ROOT}@anchor{2ed5}
@deffnx {Δεδομένα} stat.STATX_ATTR_MOUNT_ROOT
@anchor{library/stat stat STATX_ATTR_VERITY}@anchor{2ed6}
@deffnx {Δεδομένα} stat.STATX_ATTR_VERITY
@anchor{library/stat stat STATX_ATTR_DAX}@anchor{2ed7}
@deffnx {Δεδομένα} stat.STATX_ATTR_DAX
@anchor{library/stat stat STATX_ATTR_WRITE_ATOMIC}@anchor{2ed8}
@deffnx {Δεδομένα} stat.STATX_ATTR_WRITE_ATOMIC


Added in version 3.15.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node filecmp — File and Directory Comparisons,tempfile — Generate temporary files and directories,stat — Interpreting stat results,File and Directory Access
@anchor{library/filecmp doc}@anchor{2ed9}@anchor{library/filecmp filecmp-file-and-directory-comparisons}@anchor{2eda}@anchor{library/filecmp module-filecmp}@anchor{5d}@anchor{library/filecmp translation-repo}@anchor{2edb}
@subsection @code{filecmp} — File and Directory Comparisons


@geindex module; filecmp

`Source code:' Lib/filecmp.py@footnote{https://github.com/python/cpython/tree/main/Lib/filecmp.py}


__________________________________________________________________


The @code{filecmp} module defines functions to compare files and directories,
with various optional time/correctness trade-offs. For comparing files,
see also the @ref{3a,,difflib} module.

The @code{filecmp} module defines the following functions:

@geindex cmp() (στη μονάδα filecmp)
@anchor{library/filecmp filecmp cmp}@anchor{1be6}
@deffn {Συνάρτηση} filecmp.cmp (f1, f2, shallow=True)

Compare the files named `f1' and `f2', returning @code{True} if they seem equal,
@code{False} otherwise.

If `shallow' is true and the @ref{4f5,,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.

Note that no external programs are called from this function, giving it
portability and efficiency.

This function uses a cache for past comparisons and the results,
with cache entries invalidated if the @ref{4f5,,os.stat()} information for the
file changes.  The entire cache may be cleared using @ref{12e9,,clear_cache()}.
@end deffn

@geindex cmpfiles() (στη μονάδα filecmp)
@anchor{library/filecmp filecmp cmpfiles}@anchor{1b5d}
@deffn {Συνάρτηση} filecmp.cmpfiles (dir1, dir2, common, shallow=True)

Compare the files in the two directories `dir1' and `dir2' whose names are
given by `common'.

Returns three lists of file names: `match', `mismatch',
`errors'.  `match' contains the list of files that match, `mismatch' contains
the names of those that don’t, and `errors' lists the names of files which
could not be compared.  Files are listed in `errors' if they don’t exist in
one of the directories, the user lacks permission to read them or if the
comparison could not be done for some other reason.

The `shallow' parameter has the same meaning and default value as for
@ref{1be6,,filecmp.cmp()}.

For example, @code{cmpfiles('a', 'b', ['c', 'd/e'])} will compare @code{a/c} with
@code{b/c} and @code{a/d/e} with @code{b/d/e}.  @code{'c'} and @code{'d/e'} will each be in
one of the three returned lists.
@end deffn

@geindex clear_cache() (στη μονάδα filecmp)
@anchor{library/filecmp filecmp clear_cache}@anchor{12e9}
@deffn {Συνάρτηση} filecmp.clear_cache ()

Clear the filecmp cache. This may be useful if a file is compared so quickly
after it is modified that it is within the mtime resolution of
the underlying filesystem.


Added in version 3.4.

@end deffn

@menu
* The dircmp class:: 

@end menu

@node The dircmp class,,,filecmp — File and Directory Comparisons
@anchor{library/filecmp dircmp-objects}@anchor{2edc}@anchor{library/filecmp the-dircmp-class}@anchor{2edd}
@subsubsection The @code{dircmp} class


@geindex dircmp (κλάση σε filecmp)
@anchor{library/filecmp filecmp dircmp}@anchor{12eb}
@deffn {Κλάση} 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{12ea,,filecmp.DEFAULT_IGNORES}.  `hide' is a list of names to hide, and
defaults to @code{[os.curdir, os.pardir]}.

The @code{dircmp} class compares files by doing `shallow' comparisons
as described for @ref{1be6,,filecmp.cmp()} by default using the `shallow'
parameter.


Άλλαξε στην έκδοση 3.13: Added the `shallow' parameter.


The @code{dircmp} class provides the following methods:

@geindex report() (μέθοδος της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp report}@anchor{2ede}
@deffn {Μέθοδος} report ()

Print (to @ref{e9c,,sys.stdout}) a comparison between `a' and `b'.
@end deffn

@geindex report_partial_closure() (μέθοδος της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp report_partial_closure}@anchor{2edf}
@deffn {Μέθοδος} report_partial_closure ()

Print a comparison between `a' and `b' and common immediate
subdirectories.
@end deffn

@geindex report_full_closure() (μέθοδος της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp report_full_closure}@anchor{2ee0}
@deffn {Μέθοδος} report_full_closure ()

Print a comparison between `a' and `b' and common subdirectories
(recursively).
@end deffn

The @code{dircmp} class offers a number of interesting attributes that may be
used to get various bits of information about the directory trees being
compared.

Note that via @ref{8e3,,__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 (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp left}@anchor{2ee1}
@deffn {Ιδιότητα} left

The directory `a'.
@end deffn

@geindex right (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp right}@anchor{2ee2}
@deffn {Ιδιότητα} right

The directory `b'.
@end deffn

@geindex left_list (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp left_list}@anchor{2ee3}
@deffn {Ιδιότητα} left_list

Files and subdirectories in `a', filtered by `hide' and `ignore'.
@end deffn

@geindex right_list (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp right_list}@anchor{2ee4}
@deffn {Ιδιότητα} right_list

Files and subdirectories in `b', filtered by `hide' and `ignore'.
@end deffn

@geindex common (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp common}@anchor{2ee5}
@deffn {Ιδιότητα} common

Files and subdirectories in both `a' and `b'.
@end deffn

@geindex left_only (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp left_only}@anchor{2ee6}
@deffn {Ιδιότητα} left_only

Files and subdirectories only in `a'.
@end deffn

@geindex right_only (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp right_only}@anchor{2ee7}
@deffn {Ιδιότητα} right_only

Files and subdirectories only in `b'.
@end deffn

@geindex common_dirs (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp common_dirs}@anchor{2ee8}
@deffn {Ιδιότητα} common_dirs

Subdirectories in both `a' and `b'.
@end deffn

@geindex common_files (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp common_files}@anchor{2ee9}
@deffn {Ιδιότητα} common_files

Files in both `a' and `b'.
@end deffn

@geindex common_funny (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp common_funny}@anchor{2eea}
@deffn {Ιδιότητα} common_funny

Names in both `a' and `b', such that the type differs between the
directories, or names for which @ref{4f5,,os.stat()} reports an error.
@end deffn

@geindex same_files (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp same_files}@anchor{2eeb}
@deffn {Ιδιότητα} same_files

Files which are identical in both `a' and `b', using the class’s
file comparison operator.
@end deffn

@geindex diff_files (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp diff_files}@anchor{2eec}
@deffn {Ιδιότητα} diff_files

Files which are in both `a' and `b', whose contents differ according
to the class’s file comparison operator.
@end deffn

@geindex funny_files (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp funny_files}@anchor{2eed}
@deffn {Ιδιότητα} funny_files

Files which are in both `a' and `b', but could not be compared.
@end deffn

@geindex subdirs (ιδιότητα της filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp subdirs}@anchor{1eda}
@deffn {Ιδιότητα} subdirs

A dictionary mapping names in @ref{2ee8,,common_dirs} to @code{dircmp}
instances (or MyDirCmp instances if this instance is of type MyDirCmp, a
subclass of @code{dircmp}).


Άλλαξε στην έκδοση 3.10: Previously entries were always @code{dircmp} instances. Now entries
are the same type as `self', if `self' is a subclass of
@code{dircmp}.

@end deffn
@end deffn

@geindex DEFAULT_IGNORES (στη μονάδα filecmp)
@anchor{library/filecmp filecmp DEFAULT_IGNORES}@anchor{12ea}
@deffn {Δεδομένα} filecmp.DEFAULT_IGNORES


Added in version 3.4.


List of directories ignored by @ref{12eb,,dircmp} by default.
@end deffn

Here is a simplified example of using the @code{subdirs} attribute to search
recursively through two directories to show common different files:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tempfile — Generate temporary files and directories,glob — Unix style pathname pattern expansion,filecmp — File and Directory Comparisons,File and Directory Access
@anchor{library/tempfile doc}@anchor{2eee}@anchor{library/tempfile module-tempfile}@anchor{e9}@anchor{library/tempfile tempfile-generate-temporary-files-and-directories}@anchor{2eef}@anchor{library/tempfile translation-repo}@anchor{2ef0}
@subsection @code{tempfile} — Generate temporary files and directories


@geindex module; tempfile

`Source code:' Lib/tempfile.py@footnote{https://github.com/python/cpython/tree/main/Lib/tempfile.py}

@geindex temporary;file name
@geindex temporary;file


__________________________________________________________________


This module creates temporary files and directories.  It works on all
supported platforms. @ref{1a0d,,TemporaryFile}, @ref{8d6,,NamedTemporaryFile},
@ref{15da,,TemporaryDirectory}, and @ref{a82,,SpooledTemporaryFile} are high-level
interfaces which provide automatic cleanup and can be used as
@ref{478,,context managers}. @ref{2ef1,,mkstemp()} and
@ref{730,,mkdtemp()} are lower-level functions which require manual cleanup.

All the user-callable functions and constructors take additional arguments which
allow direct control over the location and name of temporary files and
directories. Files names used by this module include a string of
random characters which allows those files to be securely created in
shared temporary directories.
To maintain backward compatibility, the argument order is somewhat odd; it
is recommended to use keyword arguments for clarity.

The module defines the following user-callable items:

@geindex TemporaryFile() (στη μονάδα tempfile)
@anchor{library/tempfile tempfile TemporaryFile}@anchor{1a0d}
@deffn {Συνάρτηση} tempfile.TemporaryFile (mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

Return a @ref{19b1,,file-like object} that can be used as a temporary storage area.
The file is created securely, using the same rules as @ref{2ef1,,mkstemp()}. It will be destroyed as soon
as it is closed (including an implicit close when the object is garbage
collected).  Under Unix, the directory entry for the file is either not created at all or is removed
immediately after the file is created.  Other platforms do not support
this; your code should not rely on a temporary file created using this
function having or not having a visible name in the file system.

The resulting object can be used as a @ref{478,,context manager} (see
@ref{2ef2,,Examples}).  On completion of the context or
destruction of the file object the temporary file will be removed
from the filesystem.

The `mode' parameter defaults to @code{'w+b'} so that the file created can
be read and written without being closed.  Binary mode is used so that it
behaves consistently on all platforms without regard for the data that is
stored.  `buffering', `encoding', `errors' and `newline' are interpreted as for
@ref{32b,,open()}.

The `dir', `prefix' and `suffix' parameters have the same meaning and
defaults as with @ref{2ef1,,mkstemp()}.

The returned object is a true file object on POSIX platforms.  On other
platforms, it is a file-like object whose @code{file} attribute is the
underlying true file object.

The @ref{131d,,os.O_TMPFILE} flag is used if it is available and works
(Linux-specific, requires Linux kernel 3.11 or later).

On platforms that are neither Posix nor Cygwin, TemporaryFile is an alias
for NamedTemporaryFile.

Raises an @ref{1e65,,auditing event} @code{tempfile.mkstemp} with argument @code{fullpath}.


Άλλαξε στην έκδοση 3.5: The @ref{131d,,os.O_TMPFILE} flag is now used if available.



Άλλαξε στην έκδοση 3.8: Added `errors' parameter.

@end deffn

@geindex NamedTemporaryFile() (στη μονάδα tempfile)
@anchor{library/tempfile tempfile NamedTemporaryFile}@anchor{8d6}
@deffn {Συνάρτηση} 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{1a0d,,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{1a0d,,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{19b1,,file-like object} whose @code{file}
attribute is the underlying true file object. This file-like object
can be used in a @ref{20a,,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{1a0d,,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{19b1,,file-like object} is finalized. Deletion is not
always guaranteed in this case (see @ref{13a6,,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{20a,,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{114b,,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{32b,,open()}) must be closed before exiting the
context manager, else the @ref{14a1,,os.unlink()} call on context manager
exit will fail with a @ref{10f9,,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{14a1,,os.unlink()}
call on exit of the context manager will fail with a @ref{10f9,,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.

Raises an @ref{1e65,,auditing event} @code{tempfile.mkstemp} with argument @code{fullpath}.


Άλλαξε στην έκδοση 3.8: Added `errors' parameter.



Άλλαξε στην έκδοση 3.12: Added `delete_on_close' parameter.

@end deffn

@geindex SpooledTemporaryFile (κλάση σε tempfile)
@anchor{library/tempfile tempfile SpooledTemporaryFile}@anchor{a82}
@deffn {Κλάση} 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{1a0d,,TemporaryFile()} does, except that
data is spooled in memory until the file size exceeds `max_size', or
until the file’s @ref{19b2,,fileno()} method is called, at which point the
contents are written to disk and operation proceeds as with
@code{TemporaryFile()}.

@geindex rollover() (μέθοδος της tempfile.SpooledTemporaryFile)
@anchor{library/tempfile tempfile SpooledTemporaryFile rollover}@anchor{2ef3}
@deffn {Μέθοδος} 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{1255,,io.BytesIO} or @ref{b9c,,io.TextIOWrapper} object
(depending on whether binary or text `mode' was specified) or a true file
object, depending on whether @ref{2ef3,,rollover()} has been called.  This
file-like object can be used in a @ref{20a,,with} statement, just like
a normal file.


Άλλαξε στην έκδοση 3.3: the truncate method now accepts a `size' argument.



Άλλαξε στην έκδοση 3.8: Added `errors' parameter.



Άλλαξε στην έκδοση 3.11: Fully implements the @ref{a83,,io.BufferedIOBase} and
@ref{a84,,io.TextIOBase} abstract base classes (depending on whether binary
or text `mode' was specified).

@end deffn

@geindex TemporaryDirectory (κλάση σε tempfile)
@anchor{library/tempfile tempfile TemporaryDirectory}@anchor{15da}
@deffn {Κλάση} 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{730,,mkdtemp()}.
The resulting object can be used as a @ref{478,,context manager} (see
@ref{2ef2,,Examples}).  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 (ιδιότητα της tempfile.TemporaryDirectory)
@anchor{library/tempfile tempfile TemporaryDirectory name}@anchor{2ef4}
@deffn {Ιδιότητα} 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{478,,context manager}, the
@code{name} will be assigned to the target of the @code{as} clause in
the @ref{20a,,with} statement, if there is one.
@end deffn

@geindex cleanup() (μέθοδος της tempfile.TemporaryDirectory)
@anchor{library/tempfile tempfile TemporaryDirectory cleanup}@anchor{2ef5}
@deffn {Μέθοδος} 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{10f9,,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.

Raises an @ref{1e65,,auditing event} @code{tempfile.mkdtemp} with argument @code{fullpath}.


Added in version 3.2.



Άλλαξε στην έκδοση 3.10: Added `ignore_cleanup_errors' parameter.



Άλλαξε στην έκδοση 3.12: Added the `delete' parameter.

@end deffn

@geindex mkstemp() (στη μονάδα tempfile)
@anchor{library/tempfile tempfile mkstemp}@anchor{2ef1}
@deffn {Συνάρτηση} tempfile.mkstemp (suffix=None, prefix=None, dir=None, text=False)

Creates a temporary file in the most secure manner possible.  There are
no race conditions in the file’s creation, assuming that the platform
properly implements the @ref{1a0e,,os.O_EXCL} flag for @ref{114b,,os.open()}.  The
file is readable and writable only by the creating user ID.  If the
platform uses permission bits to indicate whether a file is executable,
the file is executable by no one.

The file descriptor is @ref{12aa,,not inherited by child processes}.

Unlike @ref{1a0d,,TemporaryFile()}, the user of @code{mkstemp()} is responsible
for deleting the temporary file when done with it.

If `suffix' is not @code{None}, the file name will end with that suffix,
otherwise there will be no suffix.  @code{mkstemp()} does not put a dot
between the file name and the suffix; if you need one, put it at the
beginning of `suffix'.

If `prefix' is not @code{None}, the file name will begin with that prefix;
otherwise, a default prefix is used.  The default is the return value of
@ref{2ef6,,gettempprefix()} or @ref{2ef7,,gettempprefixb()}, as appropriate.

If `dir' is not @code{None}, the file will be created in that directory;
otherwise, a default directory is used.  The default directory is chosen
from a platform-dependent list, but the user of the application can
control the directory location by setting the `TMPDIR', `TEMP' or `TMP'
environment variables.  There is thus no guarantee that the generated
filename will have any nice properties, such as not requiring quoting
when passed to external commands via @code{os.popen()}.

If any of `suffix', `prefix', and `dir' are not
@code{None}, they must be the same type.
If they are bytes, the returned name will be bytes instead of str.
If you want to force a bytes return value with otherwise default behavior,
pass @code{suffix=b'@w{'}}.

If `text' is specified and true, the file is opened in text mode.
Otherwise, (the default) the file is opened in binary mode.

@code{mkstemp()} returns a tuple containing an OS-level handle to an open
file (as would be returned by @ref{114b,,os.open()}) and the absolute pathname
of that file, in that order.

Raises an @ref{1e65,,auditing event} @code{tempfile.mkstemp} with argument @code{fullpath}.


Άλλαξε στην έκδοση 3.5: `suffix', `prefix', and `dir' may now be supplied in bytes in order to
obtain a bytes return value.  Prior to this, only str was allowed.
`suffix' and `prefix' now accept and default to @code{None} to cause
an appropriate default value to be used.



Άλλαξε στην έκδοση 3.6: The `dir' parameter now accepts a @ref{79f,,path-like object}.

@end deffn

@geindex mkdtemp() (στη μονάδα tempfile)
@anchor{library/tempfile tempfile mkdtemp}@anchor{730}
@deffn {Συνάρτηση} tempfile.mkdtemp (suffix=None, prefix=None, dir=None)

Creates a temporary directory in the most secure manner possible. There
are no race conditions in the directory’s creation.  The directory is
readable, writable, and searchable only by the creating user ID.

The user of @code{mkdtemp()} is responsible for deleting the temporary
directory and its contents when done with it.

The `prefix', `suffix', and `dir' arguments are the same as for
@ref{2ef1,,mkstemp()}.

@code{mkdtemp()} returns the absolute pathname of the new directory.

Raises an @ref{1e65,,auditing event} @code{tempfile.mkdtemp} with argument @code{fullpath}.


Άλλαξε στην έκδοση 3.5: `suffix', `prefix', and `dir' may now be supplied in bytes in order to
obtain a bytes return value.  Prior to this, only str was allowed.
`suffix' and `prefix' now accept and default to @code{None} to cause
an appropriate default value to be used.



Άλλαξε στην έκδοση 3.6: The `dir' parameter now accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.12: @code{mkdtemp()} now always returns an absolute path, even if `dir' is relative.

@end deffn

@geindex gettempdir() (στη μονάδα tempfile)
@anchor{library/tempfile tempfile gettempdir}@anchor{1e89}
@deffn {Συνάρτηση} tempfile.gettempdir ()

Return the name of the directory used for temporary files. This
defines the default value for the `dir' argument to all functions
in this module.

Python searches a standard list of directories to find one which
the calling user can create files in.  The list is:


@enumerate 

@item 
The directory named by the 
@geindex TMPDIR
@geindex μεταβλητή περιβάλλοντος; TMPDIR
@code{TMPDIR} environment variable.

@item 
The directory named by the 
@geindex TEMP
@geindex μεταβλητή περιβάλλοντος; TEMP
@code{TEMP} environment variable.

@item 
The directory named by the 
@geindex TMP
@geindex μεταβλητή περιβάλλοντος; TMP
@code{TMP} environment variable.

@item 
A platform-specific location:


@itemize *

@item 
On Windows, the directories @code{C:\TEMP}, @code{C:\TMP},
@code{\TEMP}, and @code{\TMP}, in that order.

@item 
On all other platforms, the directories @code{/tmp}, @code{/var/tmp}, and
@code{/usr/tmp}, in that order.
@end itemize

@item 
As a last resort, the current working directory.
@end enumerate

The result of this search is cached, see the description of
@ref{1e88,,tempdir} below.


Άλλαξε στην έκδοση 3.10: Always returns a str.  Previously it would return any @ref{1e88,,tempdir}
value regardless of type so long as it was not @code{None}.

@end deffn

@geindex gettempdirb() (στη μονάδα tempfile)
@anchor{library/tempfile tempfile gettempdirb}@anchor{1e8a}
@deffn {Συνάρτηση} tempfile.gettempdirb ()

Same as @ref{1e89,,gettempdir()} but the return value is in bytes.


Added in version 3.5.

@end deffn

@geindex gettempprefix() (στη μονάδα tempfile)
@anchor{library/tempfile tempfile gettempprefix}@anchor{2ef6}
@deffn {Συνάρτηση} tempfile.gettempprefix ()

Return the filename prefix used to create temporary files.  This does not
contain the directory component.
@end deffn

@geindex gettempprefixb() (στη μονάδα tempfile)
@anchor{library/tempfile tempfile gettempprefixb}@anchor{2ef7}
@deffn {Συνάρτηση} tempfile.gettempprefixb ()

Same as @ref{2ef6,,gettempprefix()} but the return value is in bytes.


Added in version 3.5.

@end deffn

The module uses a global variable to store the name of the directory
used for temporary files returned by @ref{1e89,,gettempdir()}.  It can be
set directly to override the selection process, but this is discouraged.
All functions in this module take a `dir' argument which can be used
to specify the directory. This is the recommended approach that does
not surprise other unsuspecting code by changing global API behavior.

@geindex tempdir (στη μονάδα tempfile)
@anchor{library/tempfile tempfile tempdir}@anchor{1e88}
@deffn {Δεδομένα} tempfile.tempdir

When set to a value other than @code{None}, this variable defines the
default value for the `dir' argument to the functions defined in this
module, including its type, bytes or str.  It cannot be a
@ref{79f,,path-like object}.

If @code{tempdir} is @code{None} (the default) at any call to any of the above
functions except @ref{2ef6,,gettempprefix()} it is initialized following the
algorithm described in @ref{1e89,,gettempdir()}.

@cartouche
@quotation Σημείωση 
Beware that if you set @code{tempdir} to a bytes value, there is a
nasty side effect: The global default return type of
@ref{2ef1,,mkstemp()} and @ref{730,,mkdtemp()} changes to bytes when no
explicit @code{prefix}, @code{suffix}, or @code{dir} arguments of type
str are supplied. Please do not write code expecting or
depending on this. This awkward behavior is maintained for
compatibility with the historical implementation.
@end quotation
@end cartouche
@end deffn

@menu
* Examples: Examples<3>. 
* Deprecated functions and variables:: 

@end menu

@node Examples<3>,Deprecated functions and variables,,tempfile — Generate temporary files and directories
@anchor{library/tempfile examples}@anchor{2ef8}@anchor{library/tempfile tempfile-examples}@anchor{2ef2}
@subsubsection Examples


Here are some examples of typical usage of the @code{tempfile} module:

@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 Deprecated functions and variables,,Examples<3>,tempfile — Generate temporary files and directories
@anchor{library/tempfile deprecated-functions-and-variables}@anchor{2ef9}@anchor{library/tempfile tempfile-mktemp-deprecated}@anchor{2efa}
@subsubsection Deprecated functions and variables


A historical way to create temporary files was to first generate a
file name with the @ref{1e27,,mktemp()} function and then create a file
using this name. Unfortunately this is not secure, because a different
process may create a file with this name in the time between the call
to @code{mktemp()} and the subsequent attempt to create the file by the
first process. The solution is to combine the two steps and create the
file immediately. This approach is used by @ref{2ef1,,mkstemp()} and the
other functions described above.

@geindex mktemp() (στη μονάδα tempfile)
@anchor{library/tempfile tempfile mktemp}@anchor{1e27}
@deffn {Συνάρτηση} tempfile.mktemp (suffix='@w{'}, prefix='tmp', dir=None)


Αποσύρθηκε στην έκδοση 2.3: Use @ref{2ef1,,mkstemp()} instead.


Return an absolute pathname of a file that did not exist at the time the
call is made.  The `prefix', `suffix', and `dir' arguments are similar
to those of @ref{2ef1,,mkstemp()}, except that bytes file names, @code{suffix=None}
and @code{prefix=None} are not supported.

@cartouche
@quotation Προειδοποίηση 
Use of this function may introduce a security hole in your program.  By
the time you get around to doing anything with the file name it returns,
someone else may have beaten you to the punch.  @code{mktemp()} usage can
be replaced easily with @ref{8d6,,NamedTemporaryFile()}, passing it the
@code{delete=False} parameter:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node glob — Unix style pathname pattern expansion,fnmatch — Unix filename pattern matching,tempfile — Generate temporary files and directories,File and Directory Access
@anchor{library/glob doc}@anchor{2efb}@anchor{library/glob glob-unix-style-pathname-pattern-expansion}@anchor{2efc}@anchor{library/glob module-glob}@anchor{67}@anchor{library/glob translation-repo}@anchor{2efd}
@subsection @code{glob} — Unix style pathname pattern expansion


@geindex module; glob

`Source code:' Lib/glob.py@footnote{https://github.com/python/cpython/tree/main/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 @code{glob} module finds pathnames
using pattern matching rules similar to the Unix shell.
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{e23,,os.scandir()} and @ref{1e4b,,fnmatch.fnmatch()} functions in concert, and
not by actually invoking a subshell.

@cartouche
@quotation Σημείωση 
The pathnames are returned in no particular order.  If you need a specific
order, sort the results.
@end quotation
@end cartouche

Files beginning with a dot (@code{.}) can only be matched by
patterns that also start with a dot,
unlike @ref{1e4b,,fnmatch.fnmatch()} or @ref{73a,,pathlib.Path.glob()}.
For tilde and shell variable expansion, use @ref{dd8,,os.path.expanduser()} and
@ref{177c,,os.path.expandvars()}.

For a literal match, wrap the meta-characters in brackets.
For example, @code{'[?]'} matches the character @code{'?'}.

The @code{glob} module defines the following functions:

@geindex glob() (στη μονάδα glob)
@anchor{library/glob glob glob}@anchor{2d4}
@deffn {Συνάρτηση} 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.

If `root_dir' is not @code{None}, it should be a @ref{79f,,path-like object}
specifying the root directory for searching.  It has the same effect on
@code{glob()} as changing the current directory before calling it.  If
`pathname' is relative, the result will contain paths relative to
`root_dir'.

This function can support @ref{1496,,paths relative to directory descriptors} with the `dir_fd' parameter.

@geindex **;in glob-style wildcards

If `recursive' is true, the pattern «@code{**}» will match any files and zero or
more directories, subdirectories and symbolic links to directories. If the
pattern is followed by an @ref{a5a,,os.sep} or @ref{a5b,,os.altsep} then files will not
match.

If `include_hidden' is true, «@code{**}» pattern will match hidden directories.

Raises an @ref{1e65,,auditing event} @code{glob.glob} with arguments @code{pathname}, @code{recursive}.

Raises an @ref{1e65,,auditing event} @code{glob.glob/2} with arguments @code{pathname}, @code{recursive}, @code{root_dir}, @code{dir_fd}.

@cartouche
@quotation Σημείωση 
Using the «@code{**}» pattern in large directory trees may consume
an inordinate amount of time.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
This function may return duplicate path names if `pathname'
contains multiple «@code{**}» patterns and `recursive' is true.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Any @ref{53c,,OSError} exceptions raised from scanning the filesystem are
suppressed. This includes @ref{10f9,,PermissionError} when accessing
directories without read permission.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.5: Support for recursive globs using «@code{**}».



Άλλαξε στην έκδοση 3.10: Added the `root_dir' and `dir_fd' parameters.



Άλλαξε στην έκδοση 3.11: Added the `include_hidden' parameter.

@end deffn

@geindex iglob() (στη μονάδα glob)
@anchor{library/glob glob iglob}@anchor{be1}
@deffn {Συνάρτηση} glob.iglob (pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)

Return an @ref{6ce,,iterator} which yields the same values as @ref{67,,glob()}
without actually storing them all simultaneously.

Raises an @ref{1e65,,auditing event} @code{glob.glob} with arguments @code{pathname}, @code{recursive}.

Raises an @ref{1e65,,auditing event} @code{glob.glob/2} with arguments @code{pathname}, @code{recursive}, @code{root_dir}, @code{dir_fd}.

@cartouche
@quotation Σημείωση 
This function may return duplicate path names if `pathname'
contains multiple «@code{**}» patterns and `recursive' is true.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Any @ref{53c,,OSError} exceptions raised from scanning the filesystem are
suppressed. This includes @ref{10f9,,PermissionError} when accessing
directories without read permission.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.5: Support for recursive globs using «@code{**}».



Άλλαξε στην έκδοση 3.10: Added the `root_dir' and `dir_fd' parameters.



Άλλαξε στην έκδοση 3.11: Added the `include_hidden' parameter.

@end deffn

@geindex escape() (στη μονάδα glob)
@anchor{library/glob glob escape}@anchor{12f0}
@deffn {Συνάρτηση} glob.escape (pathname)

Escape all special characters (@code{'?'}, @code{'*'} and @code{'['}).
This is useful if you want to match an arbitrary literal string that may
have special characters in it.  Special characters in drive/UNC
sharepoints are not escaped, e.g. on Windows
@code{escape('//?/c:/Quo vadis?.txt')} returns @code{'//?/c:/Quo vadis[?].txt'}.


Added in version 3.4.

@end deffn

@geindex translate() (στη μονάδα glob)
@anchor{library/glob glob translate}@anchor{700}
@deffn {Συνάρτηση} glob.translate (pathname, *, recursive=False, include_hidden=False, seps=None)

Convert the given path specification to a regular expression for use with
@ref{24a,,re.prefixmatch()}. The path specification can contain shell-style
wildcards.

For example:

@example
>>> import glob, re
>>>
>>> regex = glob.translate('**/*.txt', recursive=True, include_hidden=True)
>>> regex
'(?s:(?:.+/)?[^/]*\\.txt)\\z'
>>> reobj = re.compile(regex)
>>> reobj.prefixmatch('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{1a79,,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{a5a,,os.sep} and @ref{a5b,,altsep} (if available) are used.


@subsubheading Δείτε επίσης


@ref{738,,pathlib.PurePath.full_match()} and @ref{73a,,pathlib.Path.glob()}
methods, which call this function to implement pattern matching and
globbing.



Added in version 3.13.

@end deffn

@menu
* Examples: Examples<4>. 

@end menu

@node Examples<4>,,,glob — Unix style pathname pattern expansion
@anchor{library/glob examples}@anchor{2efe}
@subsubsection Examples


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{67,,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

If the directory contains files starting with @code{.} they won’t be matched by
default. For example, consider a directory containing @code{card.gif} and
@code{.card.gif}:

@example
>>> import glob
>>> glob.glob('*.gif')
['card.gif']
>>> glob.glob('.c*')
['.card.gif']
@end example


@subsubheading Δείτε επίσης


The @ref{5f,,fnmatch} module offers shell-style filename (not path) expansion.



@subsubheading Δείτε επίσης


The @ref{a8,,pathlib} module offers high-level path objects.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node fnmatch — Unix filename pattern matching,linecache — Random access to text lines,glob — Unix style pathname pattern expansion,File and Directory Access
@anchor{library/fnmatch doc}@anchor{2eff}@anchor{library/fnmatch fnmatch-unix-filename-pattern-matching}@anchor{2f00}@anchor{library/fnmatch module-fnmatch}@anchor{5f}@anchor{library/fnmatch translation-repo}@anchor{2f01}
@subsection @code{fnmatch} — Unix filename pattern matching


@geindex module; fnmatch

`Source code:' Lib/fnmatch.py@footnote{https://github.com/python/cpython/tree/main/Lib/fnmatch.py}

@geindex filenames;wildcard expansion

@geindex module;re


__________________________________________________________________


This module provides support for Unix shell-style wildcards, which are `not' the
same as regular expressions (which are documented in the @ref{c1,,re} module).  The
special characters used in shell-style wildcards are:

@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

Pattern

@tab

Meaning

@item

@code{*}

@tab

matches everything

@item

@code{?}

@tab

matches any single character

@item

@code{[seq]}

@tab

matches any character in `seq'

@item

@code{[!seq]}

@tab

matches any character not in `seq'

@end multitable


For a literal match, wrap the meta-characters in brackets.
For example, @code{'[?]'} matches the character @code{'?'}.

@geindex module;glob

Note that the filename separator (@code{'/'} on Unix) is `not' special to this
module.  See module @ref{67,,glob} for pathname expansion (@code{glob} uses
@ref{1e4d,,filter()} to match pathname segments).  Similarly, filenames starting with
a period are not special for this module, and are matched by the @code{*} and @code{?}
patterns.

Unless stated otherwise, «filename string» and «pattern string» either refer to
@ref{1df,,str} or @code{ISO-8859-1} encoded @ref{1c7,,bytes} objects. Note that the
functions documented below do not allow to mix a @code{bytes} pattern with
a @code{str} filename, and vice-versa.

Finally, note that @ref{db3,,functools.lru_cache()} with a `maxsize' of 32768
is used to cache the (typed) compiled regex patterns in the following
functions: @ref{5f,,fnmatch()}, @ref{1e4c,,fnmatchcase()}, @ref{1e4d,,filter()}, @ref{4a1,,filterfalse()}.

@geindex fnmatch() (στη μονάδα fnmatch)
@anchor{library/fnmatch fnmatch fnmatch}@anchor{1e4b}
@deffn {Συνάρτηση} 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{2e71,,os.path.normcase()}. @ref{1e4c,,fnmatchcase()} can be used to perform a
case-sensitive comparison, regardless of whether that’s standard for the
operating system.

This example will print all file names in the current directory with the
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() (στη μονάδα fnmatch)
@anchor{library/fnmatch fnmatch fnmatchcase}@anchor{1e4c}
@deffn {Συνάρτηση} 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{2e71,,os.path.normcase()}.
@end deffn

@geindex filter() (στη μονάδα fnmatch)
@anchor{library/fnmatch fnmatch filter}@anchor{1e4d}
@deffn {Συνάρτηση} fnmatch.filter (names, pat)

Construct a list from those elements of the @ref{15ce,,iterable} of filename
strings `names' that match the pattern string `pat'.
It is the same as @code{[n for n in names if fnmatch(n, pat)]},
but implemented more efficiently.
@end deffn

@geindex filterfalse() (στη μονάδα fnmatch)
@anchor{library/fnmatch fnmatch filterfalse}@anchor{4a1}
@deffn {Συνάρτηση} fnmatch.filterfalse (names, pat)

Construct a list from those elements of the @ref{15ce,,iterable} of filename
strings `names' that do not match the pattern string `pat'.
It is the same as @code{[n for n in names if not fnmatch(n, pat)]},
but implemented more efficiently.


Added in version 3.14.

@end deffn

@geindex translate() (στη μονάδα fnmatch)
@anchor{library/fnmatch fnmatch translate}@anchor{1a79}
@deffn {Συνάρτηση} fnmatch.translate (pat)

Return the shell-style pattern `pat' converted to a regular expression for
using with @ref{24a,,re.prefixmatch()}. The pattern is expected to be a
@ref{1df,,str}.

Example:

@example
>>> import fnmatch, re
>>>
>>> regex = fnmatch.translate('*.txt')
>>> regex
'(?s:.*\\.txt)\\z'
>>> reobj = re.compile(regex)
>>> reobj.prefixmatch('foobar.txt')
<re.Match object; span=(0, 10), match='foobar.txt'>
@end example
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{67,,glob}

Unix shell-style path expansion.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node linecache — Random access to text lines,shutil — High-level file operations,fnmatch — Unix filename pattern matching,File and Directory Access
@anchor{library/linecache doc}@anchor{2f02}@anchor{library/linecache linecache-random-access-to-text-lines}@anchor{2f03}@anchor{library/linecache module-linecache}@anchor{88}@anchor{library/linecache translation-repo}@anchor{2f04}
@subsection @code{linecache} — Random access to text lines


@geindex module; linecache

`Source code:' Lib/linecache.py@footnote{https://github.com/python/cpython/tree/main/Lib/linecache.py}


__________________________________________________________________


The @code{linecache} module allows one to get any line from a Python source file, while
attempting to optimize internally, using a cache, the common case where many
lines are read from a single file.  This is used by the @ref{107,,traceback} module
to retrieve source lines for inclusion in  the formatted traceback.

The @ref{2f05,,tokenize.open()} function is used to open files. This
function uses @ref{19ce,,tokenize.detect_encoding()} to get the encoding of the
file; in the absence of an encoding token, the file encoding defaults to UTF-8.

The @code{linecache} module defines the following functions:

@geindex getline() (στη μονάδα linecache)
@anchor{library/linecache linecache getline}@anchor{4cd}
@deffn {Συνάρτηση} linecache.getline (filename, lineno, module_globals=None)

Get line `lineno' from file named `filename'. This function will never raise an
exception — it will return @code{'@w{'}} on errors (the terminating newline character
will be included for lines that are found).

@geindex module;search;path

If `filename' indicates a frozen module (starting with @code{'<frozen '}), the function
will attempt to get the real file name from @code{module_globals['__file__']} if
`module_globals' is not @code{None}.

If a file named `filename' is not found, the function first checks
for a 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} @code{__loader__} in `module_globals'.
If there is such a loader and it defines a @code{get_source} method,
then that determines the source lines
(if @code{get_source()} returns @code{None}, then @code{'@w{'}} is returned).
Finally, if `filename' is a relative filename,
it is looked up relative to the entries in the module search path, @code{sys.path}.


Άλλαξε στην έκδοση 3.14: Support `filename' of frozen modules.

@end deffn

@geindex clearcache() (στη μονάδα linecache)
@anchor{library/linecache linecache clearcache}@anchor{2f06}
@deffn {Συνάρτηση} linecache.clearcache ()

Clear the cache.  Use this function if you no longer need lines from files
previously read using @ref{4cd,,getline()}.
@end deffn

@geindex checkcache() (στη μονάδα linecache)
@anchor{library/linecache linecache checkcache}@anchor{1b0b}
@deffn {Συνάρτηση} linecache.checkcache (filename=None)

Check the cache for validity.  Use this function if files in the cache  may have
changed on disk, and you require the updated version.  If `filename' is omitted,
it will check all the entries in the cache.
@end deffn

@geindex lazycache() (στη μονάδα linecache)
@anchor{library/linecache linecache lazycache}@anchor{11d7}
@deffn {Συνάρτηση} linecache.lazycache (filename, module_globals)

Capture enough detail about a non-file-based module to permit getting its
lines later via @ref{4cd,,getline()} even if `module_globals' is @code{None} in the later
call. This avoids doing I/O until a line is actually needed, without having
to carry the module globals around indefinitely.


Added in version 3.5.

@end deffn

Example:

@example
>>> import linecache
>>> linecache.getline(linecache.__file__, 8)
'import sys\n'
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node shutil — High-level file operations,,linecache — Random access to text lines,File and Directory Access
@anchor{library/shutil doc}@anchor{2f07}@anchor{library/shutil module-shutil}@anchor{cd}@anchor{library/shutil shutil-high-level-file-operations}@anchor{2f08}@anchor{library/shutil translation-repo}@anchor{2f09}
@subsection @code{shutil} — High-level file operations


@geindex module; shutil

`Source code:' Lib/shutil.py@footnote{https://github.com/python/cpython/tree/main/Lib/shutil.py}

@geindex file;copying
@geindex copying files


__________________________________________________________________


The @code{shutil} module offers a number of high-level operations on files and
collections of files.  In particular, functions are provided  which support file
copying and removal. For operations on individual files, see also the
@ref{a5,,os} module.

@cartouche
@quotation Προειδοποίηση 
Even the higher-level file copying functions (@ref{e1e,,shutil.copy()},
@ref{e1f,,shutil.copy2()}) cannot copy all file metadata.

On POSIX platforms, this means that file owner and group are lost as well
as ACLs.  On Mac OS, the resource fork and other metadata are not used.
This means that resources will be lost and file type and creator codes will
not be correct. On Windows, file owners, ACLs and alternate data streams
are not copied.
@end quotation
@end cartouche

@menu
* Directory and files operations:: 
* Archiving operations:: 
* Querying the size of the output terminal:: 

@end menu

@node Directory and files operations,Archiving operations,,shutil — High-level file operations
@anchor{library/shutil directory-and-files-operations}@anchor{2f0a}@anchor{library/shutil file-operations}@anchor{2f0b}
@subsubsection Directory and files operations


@geindex copyfileobj() (στη μονάδα shutil)
@anchor{library/shutil shutil copyfileobj}@anchor{e21}
@deffn {Συνάρτηση} shutil.copyfileobj (fsrc, fdst[, length])

Copy the contents of the @ref{156c,,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.

@code{copyfileobj()} will `not' guarantee that the destination stream has
been flushed on completion of the copy. If you want to read from the
destination at the completion of the copy operation (for example, reading
the contents of a temporary file that has been copied from a HTTP stream),
you must ensure that you have called @ref{19fa,,flush()} or
@ref{70b,,close()} on the file-like object before attempting to read
the destination file.
@end deffn

@geindex copyfile() (στη μονάδα shutil)
@anchor{library/shutil shutil copyfile}@anchor{e1d}
@deffn {Συνάρτηση} 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{79f,,path-like objects} or path names given as strings.

`dst' must be the complete target file name; look at @ref{e1e,,copy()}
for a copy that accepts a target directory path.  If `src' and `dst'
specify the same file, @ref{1347,,SameFileError} is raised.

The destination location must be writable; otherwise, an @ref{53c,,OSError}
exception will be raised. If `dst' already exists, it will be replaced.
Special files such as character or block devices and pipes cannot be
copied with this function.

If `follow_symlinks' is false and `src' is a symbolic link,
a new symbolic link will be created instead of copying the
file `src' points to.

Raises an @ref{1e65,,auditing event} @code{shutil.copyfile} with arguments @code{src}, @code{dst}.


Άλλαξε στην έκδοση 3.3: @ref{13fb,,IOError} used to be raised instead of @ref{53c,,OSError}.
Added `follow_symlinks' argument.
Now returns `dst'.



Άλλαξε στην έκδοση 3.4: Raise @ref{1347,,SameFileError} instead of @ref{1346,,Error}.  Since the former is
a subclass of the latter, this change is backward compatible.



Άλλαξε στην έκδοση 3.8: Platform-specific fast-copy syscalls may be used internally in order to
copy the file more efficiently. See
@ref{e22,,Platform-dependent efficient copy operations} section.

@end deffn

@geindex SpecialFileError
@anchor{library/shutil shutil SpecialFileError}@anchor{16c0}
@deffn {Εξαίρεση} shutil.SpecialFileError

This exception is raised when @ref{e1d,,copyfile()} or @ref{ded,,copytree()} attempt
to copy a named pipe.


Added in version 2.7.

@end deffn

@geindex SameFileError
@anchor{library/shutil shutil SameFileError}@anchor{1347}
@deffn {Εξαίρεση} shutil.SameFileError

This exception is raised if source and destination in @ref{e1d,,copyfile()}
are the same file.


Added in version 3.4.

@end deffn

@geindex copymode() (στη μονάδα shutil)
@anchor{library/shutil shutil copymode}@anchor{1c2c}
@deffn {Συνάρτηση} 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{79f,,path-like objects} or path names
given as strings.
If `follow_symlinks' is false, and both `src' and `dst' are symbolic links,
@code{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{14da,,copystat()} for more information.  If
@code{copymode()} cannot modify symbolic links on the local platform, and it
is asked to do so, it will do nothing and return.

Raises an @ref{1e65,,auditing event} @code{shutil.copymode} with arguments @code{src}, @code{dst}.


Άλλαξε στην έκδοση 3.3: Added `follow_symlinks' argument.

@end deffn

@geindex copystat() (στη μονάδα shutil)
@anchor{library/shutil shutil copystat}@anchor{14da}
@deffn {Συνάρτηση} 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, @code{copystat()} also copies the
«extended attributes» where possible.  The file contents, owner, and
group are unaffected.  `src' and `dst' are @ref{79f,,path-like objects} or path
names given as strings.

If `follow_symlinks' is false, and `src' and `dst' both
refer to symbolic links, @code{copystat()} will operate on
the symbolic links themselves rather than the files the
symbolic links refer to—reading the information from the
`src' symbolic link, and writing the information to the
`dst' symbolic link.

@cartouche
@quotation Σημείωση 
Not all platforms provide the ability to examine and
modify symbolic links.  Python itself can tell you what
functionality is locally available.


@itemize *

@item 
If @code{os.chmod in os.supports_follow_symlinks} is
@code{True}, @code{copystat()} can modify the permission
bits of a symbolic link.

@item 
If @code{os.utime in os.supports_follow_symlinks} is
@code{True}, @code{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}, @code{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,
@code{copystat()} will copy everything it can.
@code{copystat()} never returns failure.

Please see @ref{14a4,,os.supports_follow_symlinks}
for more information.
@end quotation
@end cartouche

Raises an @ref{1e65,,auditing event} @code{shutil.copystat} with arguments @code{src}, @code{dst}.


Άλλαξε στην έκδοση 3.3: Added `follow_symlinks' argument and support for Linux extended attributes.

@end deffn

@geindex copy() (στη μονάδα shutil)
@anchor{library/shutil shutil copy}@anchor{e1e}
@deffn {Συνάρτηση} shutil.copy (src, dst, *, follow_symlinks=True)

Copies the file `src' to the file or directory `dst'.  `src' and `dst'
should be @ref{79f,,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{e1e,,copy()} copies the file data and the file’s permission
mode (see @ref{72c,,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{e1f,,copy2()} instead.

Raises an @ref{1e65,,auditing event} @code{shutil.copyfile} with arguments @code{src}, @code{dst}.

Raises an @ref{1e65,,auditing event} @code{shutil.copymode} with arguments @code{src}, @code{dst}.


Άλλαξε στην έκδοση 3.3: Added `follow_symlinks' argument.
Now returns path to the newly created file.



Άλλαξε στην έκδοση 3.8: Platform-specific fast-copy syscalls may be used internally in order to
copy the file more efficiently. See
@ref{e22,,Platform-dependent efficient copy operations} section.

@end deffn

@geindex copy2() (στη μονάδα shutil)
@anchor{library/shutil shutil copy2}@anchor{e1f}
@deffn {Συνάρτηση} shutil.copy2 (src, dst, *, follow_symlinks=True)

Identical to @ref{e1e,,copy()} except that @code{copy2()}
also attempts to preserve file metadata.

When `follow_symlinks' is false, and `src' is a symbolic
link, @code{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, @code{copy2()} will preserve all the metadata
it can; @code{copy2()} never raises an exception because it
cannot preserve file metadata.

@code{copy2()} uses @ref{14da,,copystat()} to copy the file metadata.
Please see @code{copystat()} for more information
about platform support for modifying symbolic link metadata.

Raises an @ref{1e65,,auditing event} @code{shutil.copyfile} with arguments @code{src}, @code{dst}.

Raises an @ref{1e65,,auditing event} @code{shutil.copystat} with arguments @code{src}, @code{dst}.


Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.8: Platform-specific fast-copy syscalls may be used internally in order to
copy the file more efficiently. See
@ref{e22,,Platform-dependent efficient copy operations} section.

@end deffn

@geindex ignore_patterns() (στη μονάδα shutil)
@anchor{library/shutil shutil ignore_patterns}@anchor{2f0c}
@deffn {Συνάρτηση} shutil.ignore_patterns (*patterns)

This factory function creates a function that can be used as a callable for
@ref{ded,,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() (στη μονάδα shutil)
@anchor{library/shutil shutil copytree}@anchor{ded}
@deffn {Συνάρτηση} 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{14da,,copystat()},
individual files are copied using @ref{e1f,,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{1346,,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{14a0,,os.symlink()}.

If `ignore' is given, it must be a callable that will receive as its
arguments the directory being visited by @code{copytree()}, and a list of its
contents, as returned by @ref{14a6,,os.listdir()}.  Since @code{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{2f0c,,ignore_patterns()} can be used to create such a callable that
ignores names based on glob-style patterns.

If exception(s) occur, an @ref{1346,,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{e1f,,copy2()} is used, but any function
that supports the same signature (like @ref{e1e,,copy()}) can be used.

If `dirs_exist_ok' is false (the default) and `dst' already exists, a
@ref{13c9,,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{1e65,,auditing event} @code{shutil.copytree} with arguments @code{src}, @code{dst}.


Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.3: Copy metadata when `symlinks' is false.
Now returns `dst'.



Άλλαξε στην έκδοση 3.8: Platform-specific fast-copy syscalls may be used internally in order to
copy the file more efficiently. See
@ref{e22,,Platform-dependent efficient copy operations} section.



Άλλαξε στην έκδοση 3.8: Added the `dirs_exist_ok' parameter.

@end deffn

@geindex rmtree() (στη μονάδα shutil)
@anchor{library/shutil shutil rmtree}@anchor{335}
@deffn {Συνάρτηση} 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.

This function can support @ref{1496,,paths relative to directory descriptors}.

@cartouche
@quotation Σημείωση 
On platforms that support the necessary fd-based functions a symlink
attack resistant version of @code{rmtree()} is used by default.  On other
platforms, the @code{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{2f0d,,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{a7a,,sys.exc_info()}.


@subsubheading Δείτε επίσης


@ref{2f0e,,rmtree example} for an example of handling the removal
of a directory tree that contains read-only files.


Raises an @ref{1e65,,auditing event} @code{shutil.rmtree} with arguments @code{path}, @code{dir_fd}.


Άλλαξε στην έκδοση 3.3: Added a symlink attack resistant version that is used automatically
if platform supports fd-based functions.



Άλλαξε στην έκδοση 3.8: On Windows, will no longer delete the contents of a directory junction
before removing the junction.



Άλλαξε στην έκδοση 3.11: Added the `dir_fd' parameter.



Άλλαξε στην έκδοση 3.12: Added the `onexc' parameter, deprecated `onerror'.



Άλλαξε στην έκδοση 3.13: @code{rmtree()} now ignores @ref{243,,FileNotFoundError} exceptions for all
but the top-level path.
Exceptions other than @ref{53c,,OSError} and subclasses of @code{OSError}
are now always propagated to the caller.


@geindex avoids_symlink_attacks (ιδιότητα της shutil.rmtree)
@anchor{library/shutil shutil rmtree avoids_symlink_attacks}@anchor{2f0d}
@deffn {Ιδιότητα} rmtree.avoids_symlink_attacks

Indicates whether the current platform and implementation provides a
symlink attack resistant version of @code{rmtree()}.  Currently this is
only true for platforms supporting fd-based directory access functions.


Added in version 3.3.

@end deffn
@end deffn

@geindex move() (στη μονάδα shutil)
@anchor{library/shutil shutil move}@anchor{e20}
@deffn {Συνάρτηση} 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{149d,,os.rename()} semantics.

If the destination is on the current filesystem, then @ref{149d,,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{149d,,os.rename()} cannot be used.  If the source is a directory,
@ref{ded,,copytree()} is called, passing it the `copy_function'. The
default `copy_function' is @ref{e1f,,copy2()}.  Using @ref{e1e,,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{1e65,,auditing event} @code{shutil.move} with arguments @code{src}, @code{dst}.


Άλλαξε στην έκδοση 3.3: Added explicit symlink handling for foreign filesystems, thus adapting
it to the behavior of GNU’s @code{mv}.
Now returns `dst'.



Άλλαξε στην έκδοση 3.5: Added the `copy_function' keyword argument.



Άλλαξε στην έκδοση 3.8: Platform-specific fast-copy syscalls may be used internally in order to
copy the file more efficiently. See
@ref{e22,,Platform-dependent efficient copy operations} section.



Άλλαξε στην έκδοση 3.9: Accepts a @ref{79f,,path-like object} for both `src' and `dst'.

@end deffn

@geindex disk_usage() (στη μονάδα shutil)
@anchor{library/shutil shutil disk_usage}@anchor{14d9}
@deffn {Συνάρτηση} shutil.disk_usage (path)

Return disk usage statistics about the given path as a @ref{a3d,,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 Σημείωση 
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


Added in version 3.3.



Άλλαξε στην έκδοση 3.8: On Windows, `path' can now be a file or directory.


@ref{232d,,Διαθεσιμότητα}: Unix, Windows.
@end deffn

@geindex chown() (στη μονάδα shutil)
@anchor{library/shutil shutil chown}@anchor{74b}
@deffn {Συνάρτηση} 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{149a,,os.chown()}, the underlying function.

Raises an @ref{1e65,,auditing event} @code{shutil.chown} with arguments @code{path}, @code{user}, @code{group}.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.



Άλλαξε στην έκδοση 3.13: Added `dir_fd' and `follow_symlinks' parameters.

@end deffn

@geindex which() (στη μονάδα shutil)
@anchor{library/shutil shutil which}@anchor{8c4}
@deffn {Συνάρτηση} 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{1498,,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{2322,,os.pathsep}. When no `path' is specified, the
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} environment variable is read from @ref{4e5,,os.environ},
falling back to @ref{1fd3,,os.defpath} if it is not set.

If `cmd' contains a directory component, @code{which()} only checks the
specified path directly and does not search the directories listed in
`path' or in the system’s 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} environment variable.

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 μεταβλητή περιβάλλοντος; 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")}, @code{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


Added in version 3.3.



Άλλαξε στην έκδοση 3.8: The @ref{1c7,,bytes} type is now accepted.  If `cmd' type is
@code{bytes}, the result type is also @code{bytes}.



Άλλαξε στην έκδοση 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{1346}
@deffn {Εξαίρεση} shutil.Error

Subclass of @ref{53c,,OSError} collecting exceptions raised during a multi-file
operation. For @ref{ded,,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,,Directory and files operations
@anchor{library/shutil platform-dependent-efficient-copy-operations}@anchor{2f0f}@anchor{library/shutil shutil-platform-dependent-efficient-copy-operations}@anchor{e22}
@subsubsection Platform-dependent efficient copy operations


Starting from Python 3.8, all functions involving a file copy
(@ref{e1d,,copyfile()}, @ref{e1e,,copy()}, @ref{e1f,,copy2()},
@ref{ded,,copytree()}, and @ref{e20,,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{1ad5,,os.copy_file_range()} or @ref{ed3,,os.sendfile()} is used.

On Solaris @ref{ed3,,os.sendfile()} is used.

On Windows @ref{e1d,,shutil.copyfile()} uses a bigger default buffer size (1 MiB
instead of 64 KiB) and a @ref{1d2,,memoryview()}-based variant of
@ref{e21,,shutil.copyfileobj()} is used, which still reads and writes in a loop.
@ref{e1f,,shutil.copy2()} uses the native @code{CopyFile2} call on Windows, which is the most
efficient method, supports copy-on-write, and preserves metadata.

If the fast-copy operation fails and no data was written in the destination
file then shutil will silently fall back to less efficient
@ref{e21,,copyfileobj()} function internally.


Άλλαξε στην έκδοση 3.8.



Άλλαξε στην έκδοση 3.14: Solaris now uses @ref{ed3,,os.sendfile()}.



Άλλαξε στην έκδοση 3.14: Copy-on-write or server-side copy may be used internally via
@ref{1ad5,,os.copy_file_range()} on supported Linux filesystems.


@node copytree example,rmtree example,Platform-dependent efficient copy operations,Directory and files operations
@anchor{library/shutil copytree-example}@anchor{2f10}@anchor{library/shutil shutil-copytree-example}@anchor{2f11}
@subsubsection copytree example


An example that uses the @ref{2f0c,,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,Directory and files operations
@anchor{library/shutil rmtree-example}@anchor{2f12}@anchor{library/shutil shutil-rmtree-example}@anchor{2f0e}
@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,Directory and files operations,shutil — High-level file operations
@anchor{library/shutil archiving-operations}@anchor{15bf}@anchor{library/shutil id1}@anchor{2f13}
@subsubsection Archiving operations



Added in version 3.2.



Άλλαξε στην έκδοση 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{13a,,zipfile} and @ref{e7,,tarfile} modules.

@geindex make_archive() (στη μονάδα shutil)
@anchor{library/shutil shutil make_archive}@anchor{8c3}
@deffn {Συνάρτηση} 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 a string or @ref{79f,,path-like object} specifying 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{13c,,zlib} module is available), «tar», «gztar» (if the
@code{zlib} module is available), «bztar» (if the @ref{14,,bz2} module is
available), «xztar» (if the @ref{8d,,lzma} module is available), or «zstdtar»
(if the @ref{23,,compression.zstd} module is available).

`root_dir' is a string or @ref{79f,,path-like object} specifying 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 a string or @ref{79f,,path-like object} specifying a 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{2f14,,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{f0c,,logging.Logger}.

The `verbose' argument is unused and deprecated.

Raises an @ref{1e65,,auditing event} @code{shutil.make_archive} with arguments @code{base_name}, @code{format}, @code{root_dir}, @code{base_dir}.

@cartouche
@quotation Σημείωση 
This function is not thread-safe when custom archivers registered
with @ref{2f15,,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


Άλλαξε στην έκδοση 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"}.



Άλλαξε στην έκδοση 3.10.6: This function is now made thread-safe during creation of standard
@code{.zip} and tar archives.



Άλλαξε στην έκδοση 3.15: Accepts a @ref{79f,,path-like object} for `base_name', `root_dir' and
`base_dir'.

@end deffn

@geindex get_archive_formats() (στη μονάδα shutil)
@anchor{library/shutil shutil get_archive_formats}@anchor{2f16}
@deffn {Συνάρτηση} 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 @code{shutil} provides these formats:


@itemize -

@item 
`zip': ZIP file (if the @ref{13c,,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{13c,,zlib} module is available).

@item 
`bztar': bzip2’ed tar-file (if the @ref{14,,bz2} module is available).

@item 
`xztar': xz’ed tar-file (if the @ref{8d,,lzma} module is available).

@item 
`zstdtar': Zstandard compressed tar-file (if the @ref{23,,compression.zstd}
module is available).
@end itemize

You can register new formats or provide your own archiver for any existing
formats, by using @ref{2f15,,register_archive_format()}.
@end deffn

@geindex register_archive_format() (στη μονάδα shutil)
@anchor{library/shutil shutil register_archive_format}@anchor{2f15}
@deffn {Συνάρτηση} 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{2e73,,os.curdir}) to start archiving from.
Further arguments are passed as keyword arguments: `owner', `group',
`dry_run' and `logger' (as passed in @ref{8c3,,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{8c3,,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{2f16,,get_archive_formats()} which returns the
list of archivers.  Defaults to an empty string.


Άλλαξε στην έκδοση 3.12: Added support for functions supporting the `root_dir' argument.

@end deffn

@geindex unregister_archive_format() (στη μονάδα shutil)
@anchor{library/shutil shutil unregister_archive_format}@anchor{2f17}
@deffn {Συνάρτηση} shutil.unregister_archive_format (name)

Remove the archive format `name' from the list of supported formats.
@end deffn

@geindex unpack_archive() (στη μονάδα shutil)
@anchor{library/shutil shutil unpack_archive}@anchor{882}
@deffn {Συνάρτηση} 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»,
«xztar», or «zstdtar».  Or any other format registered with
@ref{2f18,,register_unpack_format()}.  If not provided, @code{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{277,,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 use @code{'data'} (default since Python
3.14), unless using features specific to tar and UNIX-like filesystems.
(See @ref{883,,Extraction filters} for details.)

Raises an @ref{1e65,,auditing event} @code{shutil.unpack_archive} with arguments @code{filename}, @code{extract_dir}, @code{format}.

@cartouche
@quotation Προειδοποίηση 
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 «..».

Since Python 3.14, the defaults for both built-in formats (zip and tar
files) will prevent the most dangerous of such security issues,
but will not prevent `all' unintended behavior.
Read the @ref{2f19,,Hints for further verification}
section for tar-specific details.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.7: Accepts a @ref{79f,,path-like object} for `filename' and `extract_dir'.



Άλλαξε στην έκδοση 3.12: Added the `filter' argument.

@end deffn

@geindex register_unpack_format() (στη μονάδα shutil)
@anchor{library/shutil shutil register_unpack_format}@anchor{2f18}
@deffn {Συνάρτηση} 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{882,,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{2f1a,,get_unpack_formats()} function.
@end deffn

@geindex unregister_unpack_format() (στη μονάδα shutil)
@anchor{library/shutil shutil unregister_unpack_format}@anchor{2f1b}
@deffn {Συνάρτηση} shutil.unregister_unpack_format (name)

Unregister an unpack format. `name' is the name of the format.
@end deffn

@geindex get_unpack_formats() (στη μονάδα shutil)
@anchor{library/shutil shutil get_unpack_formats}@anchor{2f1a}
@deffn {Συνάρτηση} 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 @code{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{13c,,zlib} module is available).

@item 
`bztar': bzip2’ed tar-file (if the @ref{14,,bz2} module is available).

@item 
`xztar': xz’ed tar-file (if the @ref{8d,,lzma} module is available).

@item 
`zstdtar': Zstandard compressed tar-file (if the @ref{23,,compression.zstd}
module is available).
@end itemize

You can register new formats or provide your own unpacker for any existing
formats, by using @ref{2f18,,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{2f1c}@anchor{library/shutil shutil-archiving-example}@anchor{2f1d}
@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{2f1e}@anchor{library/shutil shutil-archiving-example-with-basedir}@anchor{2f14}
@subsubsection Archiving example with `base_dir'


In this example, similar to the @ref{2f1d,,one above},
we show how to use @ref{8c3,,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/myarchive.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{2f1f}
@subsubsection Querying the size of the output terminal


@geindex get_terminal_size() (στη μονάδα shutil)
@anchor{library/shutil shutil get_terminal_size}@anchor{14af}
@deffn {Συνάρτηση} 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{2f20,,sys.__stdout__} is queried
by invoking @ref{14ae,,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{2f21,,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}.


Added in version 3.3.



Άλλαξε στην έκδοση 3.11: The @code{fallback} values are also used if @ref{14ae,,os.get_terminal_size()}
returns zeroes.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{a5,,os}

Operating system interfaces, including functions to work with files at a
lower level than Python @ref{156c,,file objects}.

@item Module @ref{82,,io}

Python’s built-in I/O library, including both abstract classes and
some concrete classes such as file I/O.

@item Built-in function @ref{32b,,open()}

The standard way to open files for reading and writing with Python.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Data Persistence,Data Compression and Archiving,File and Directory Access,The Python Standard Library
@anchor{library/persistence doc}@anchor{2f22}@anchor{library/persistence data-persistence}@anchor{2f23}@anchor{library/persistence persistence}@anchor{2f24}@anchor{library/persistence translation-repo}@anchor{2f25}
@section Data Persistence


The modules described in this chapter support storing Python data in a
persistent form on disk.  The @ref{ab,,pickle} and @ref{90,,marshal} modules can turn
many Python data types into a stream of bytes and then recreate the objects from
the bytes.  The various DBM-related modules support a family of hash-based file
formats that store a mapping of strings to other strings.

The list of modules described in this chapter is:

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

@end menu

@node pickle — Python object serialization,copyreg — Register pickle support functions,,Data Persistence
@anchor{library/pickle doc}@anchor{2f26}@anchor{library/pickle module-pickle}@anchor{ab}@anchor{library/pickle pickle-python-object-serialization}@anchor{2f27}
@subsection @code{pickle} — Python object serialization


@geindex module; pickle

`Source code:' Lib/pickle.py@footnote{https://github.com/python/cpython/tree/main/Lib/pickle.py}

@geindex persistence
@geindex persistent;objects
@geindex serializing;objects
@geindex marshalling;objects
@geindex flattening;objects
@geindex pickling;objects


__________________________________________________________________


The @code{pickle} module implements binary protocols for serializing and
de-serializing a Python object structure.  `«Pickling»' is the process
whereby a Python object hierarchy is converted into a byte stream, and
`«unpickling»' is the inverse operation, whereby a byte stream
(from a @ref{225d,,binary file} or @ref{436,,bytes-like object}) is converted
back into an object hierarchy.  Pickling (and unpickling) is alternatively
known as «serialization», «marshalling,» @footnote{
Don’t confuse this with the @ref{90,,marshal} module
} or «flattening»; however, to
avoid confusion, the terms used here are «pickling» and «unpickling».

@cartouche
@quotation Προειδοποίηση 
The @code{pickle} module `is not secure'. Only unpickle data you trust.

It is possible to construct malicious pickle data which will `execute
arbitrary code during unpickling'. Never unpickle data that could have come
from an untrusted source, or that could have been tampered with.

Consider signing data with @ref{6d,,hmac} if you need to ensure that it has not
been tampered with.

Safer serialization formats such as @ref{85,,json} may be more appropriate if
you are processing untrusted data. See @ref{2f28,,Comparison with json}.
@end quotation
@end cartouche

@menu
* Relationship to other Python modules:: 
* Data stream format:: 
* Module Interface:: 
* What can be pickled and unpickled?:: 
* Pickling Class Instances:: 
* Custom Reduction for Types@comma{} Functions@comma{} and Other Objects: Custom Reduction for Types Functions and Other Objects. 
* Out-of-band Buffers:: 
* Restricting Globals:: 
* Performance: Performance<2>. 
* Examples: Examples<5>. 
* Command-line interface:: 

@end menu

@node Relationship to other Python modules,Data stream format,,pickle — Python object serialization
@anchor{library/pickle relationship-to-other-python-modules}@anchor{2f29}
@subsubsection Relationship to other Python modules


@menu
* Comparison with marshal:: 
* Comparison with json:: 

@end menu

@node Comparison with marshal,Comparison with json,,Relationship to other Python modules
@anchor{library/pickle comparison-with-marshal}@anchor{2f2a}
@subsubsection Comparison with @code{marshal}


Python has a more primitive serialization module called @ref{90,,marshal}, but in
general @code{pickle} should always be the preferred way to serialize Python
objects.  @code{marshal} exists primarily to support Python’s @code{.pyc}
files.

The @code{pickle} module differs from @ref{90,,marshal} in several significant ways:


@itemize *

@item 
@ref{90,,marshal} cannot be used to serialize user-defined classes and their
instances.  @code{pickle} can save and restore class instances transparently,
however the class definition must be importable and live in the same module as
when the object was stored.

@item 
The @ref{90,,marshal} serialization format is not guaranteed to be portable
across Python versions.  Because its primary job in life is to support
@code{.pyc} files, the Python implementers reserve the right to change the
serialization format in non-backwards compatible ways should the need arise.
The @code{pickle} serialization format is guaranteed to be backwards compatible
across Python releases provided a compatible pickle protocol is chosen and
pickling and unpickling code deals with Python 2 to Python 3 type differences
if your data is crossing that unique breaking change language boundary.
@end itemize

@node Comparison with json,,Comparison with marshal,Relationship to other Python modules
@anchor{library/pickle comparison-with-json}@anchor{2f28}@anchor{library/pickle id2}@anchor{2f2b}
@subsubsection Comparison with @code{json}


There are fundamental differences between the pickle protocols and
JSON (JavaScript Object Notation)@footnote{https://json.org}:


@itemize *

@item 
JSON is a text serialization format (it outputs unicode text, although
most of the time it is then encoded to @code{utf-8}), while pickle is
a binary serialization format;

@item 
JSON is human-readable, while pickle is not;

@item 
JSON is interoperable and widely used outside of the Python ecosystem,
while pickle is Python-specific;

@item 
JSON, by default, can only represent a subset of the Python built-in
types, and no custom classes; pickle can represent an extremely large
number of Python types (many of them automatically, by clever usage
of Python’s introspection facilities; complex cases can be tackled by
implementing @ref{2f2c,,specific object APIs});

@item 
Unlike pickle, deserializing untrusted JSON does not in itself create an
arbitrary code execution vulnerability.
@end itemize


@subsubheading Δείτε επίσης


The @ref{85,,json} module: a standard library module allowing JSON
serialization and deserialization.


@node Data stream format,Module Interface,Relationship to other Python modules,pickle — Python object serialization
@anchor{library/pickle data-stream-format}@anchor{2f2d}@anchor{library/pickle pickle-protocols}@anchor{503}
@subsubsection Data stream format


@geindex External Data Representation

The data format used by @code{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.

By default, the @code{pickle} data format uses a relatively compact binary
representation.  If you need optimal size characteristics, you can efficiently
@ref{2f2e,,compress} pickled data.

The module @ref{ac,,pickletools} contains tools for analyzing data streams
generated by @code{pickle}.  @code{pickletools} source code has extensive
comments about opcodes used by pickle protocols.

There are currently 6 different protocols which can be used for pickling.
The higher the protocol used, the more recent the version of Python needed
to read the pickle produced.


@itemize *

@item 
Protocol version 0 is the original «human-readable» protocol and is
backwards compatible with earlier versions of Python.

@item 
Protocol version 1 is an old binary format which is also compatible with
earlier versions of Python.

@item 
Protocol version 2 was introduced in Python 2.3.  It provides much more
efficient pickling of @ref{2f2f,,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 
Protocol version 3 was added in Python 3.0.  It has explicit support for
@ref{1c7,,bytes} objects and cannot be unpickled by Python 2.x.  This was
the default protocol in Python 3.0–3.7.

@item 
Protocol version 4 was added in Python 3.4.  It adds support for very large
objects, pickling more kinds of objects, and some data format
optimizations.  This was the default protocol in Python 3.8–3.13.
Refer to 
@geindex Python Enhancement Proposals; PEP 3154
PEP 3154@footnote{https://peps.python.org/pep-3154/} for information about improvements brought by
protocol 4.

@item 
Protocol version 5 was added in Python 3.8.  It adds support for out-of-band
data and speedup for in-band data.  It is the default protocol starting with
Python 3.14.  Refer to 
@geindex Python Enhancement Proposals; PEP 574
PEP 574@footnote{https://peps.python.org/pep-0574/} for information about improvements brought
by protocol 5.
@end itemize

@cartouche
@quotation Σημείωση 
Serialization is a more primitive notion than persistence; although
@code{pickle} reads and writes file objects, it does not handle the issue of
naming persistent objects, nor the (even more complicated) issue of concurrent
access to persistent objects.  The @code{pickle} module can transform a complex
object into a byte stream and it can transform the byte stream into an object
with the same internal structure.  Perhaps the most obvious thing to do with
these byte streams is to write them onto a file, but it is also conceivable to
send them across a network or store them in a database.  The @ref{cb,,shelve}
module provides a simple interface to pickle and unpickle objects on
DBM-style database files.
@end quotation
@end cartouche

@node Module Interface,What can be pickled and unpickled?,Data stream format,pickle — Python object serialization
@anchor{library/pickle module-interface}@anchor{2f30}
@subsubsection Module Interface


To serialize an object hierarchy, you simply call the @ref{1846,,dumps()} function.
Similarly, to de-serialize a data stream, you call the @ref{10cb,,loads()} function.
However, if you want more control over serialization and de-serialization,
you can create a @ref{de2,,Pickler} or an @ref{1978,,Unpickler} object, respectively.

The @code{pickle} module provides the following constants:

@geindex HIGHEST_PROTOCOL (στη μονάδα pickle)
@anchor{library/pickle pickle HIGHEST_PROTOCOL}@anchor{1847}
@deffn {Δεδομένα} pickle.HIGHEST_PROTOCOL

An integer, the highest @ref{503,,protocol version}
available.  This value can be passed as a `protocol' value to functions
@ref{2f31,,dump()} and @ref{1846,,dumps()} as well as the @ref{de2,,Pickler}
constructor.
@end deffn

@geindex DEFAULT_PROTOCOL (στη μονάδα pickle)
@anchor{library/pickle pickle DEFAULT_PROTOCOL}@anchor{c07}
@deffn {Δεδομένα} pickle.DEFAULT_PROTOCOL

An integer, the default @ref{503,,protocol version} used
for pickling.  May be less than @ref{1847,,HIGHEST_PROTOCOL}.  Currently the
default protocol is 5, introduced in Python 3.8 and incompatible
with previous versions. This version 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.


Άλλαξε στην έκδοση 3.0: The default protocol is 3.



Άλλαξε στην έκδοση 3.8: The default protocol is 4.



Άλλαξε στην έκδοση 3.14: The default protocol is 5.

@end deffn

The @code{pickle} module provides the following functions to make the pickling
process more convenient:

@geindex dump() (στη μονάδα pickle)
@anchor{library/pickle pickle dump}@anchor{2f31}
@deffn {Συνάρτηση} pickle.dump (obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)

Write the pickled representation of the object `obj' to the open
@ref{156c,,file object} `file'.  This is equivalent to
@code{Pickler(file, protocol).dump(obj)}.

Arguments `file', `protocol', `fix_imports' and `buffer_callback' have
the same meaning as in the @ref{de2,,Pickler} constructor.


Άλλαξε στην έκδοση 3.8: The `buffer_callback' argument was added.

@end deffn

@geindex dumps() (στη μονάδα pickle)
@anchor{library/pickle pickle dumps}@anchor{1846}
@deffn {Συνάρτηση} pickle.dumps (obj, protocol=None, *, fix_imports=True, buffer_callback=None)

Return the pickled representation of the object `obj' as a @ref{1c7,,bytes} object,
instead of writing it to a file.

Arguments `protocol', `fix_imports' and `buffer_callback' have the same
meaning as in the @ref{de2,,Pickler} constructor.


Άλλαξε στην έκδοση 3.8: The `buffer_callback' argument was added.

@end deffn

@geindex load() (στη μονάδα pickle)
@anchor{library/pickle pickle load}@anchor{10ca}
@deffn {Συνάρτηση} pickle.load (file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

Read the pickled representation of an object from the open @ref{156c,,file object}
`file' and return the reconstituted object hierarchy specified therein.
This is equivalent to @code{Unpickler(file).load()}.

The protocol version of the pickle is detected automatically, so no
protocol argument is needed.  Bytes past the pickled representation
of the object are ignored.

Arguments `file', `fix_imports', `encoding', `errors', `strict' and `buffers'
have the same meaning as in the @ref{1978,,Unpickler} constructor.


Άλλαξε στην έκδοση 3.8: The `buffers' argument was added.

@end deffn

@geindex loads() (στη μονάδα pickle)
@anchor{library/pickle pickle loads}@anchor{10cb}
@deffn {Συνάρτηση} pickle.loads (data, /, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

Return the reconstituted object hierarchy of the pickled representation
`data' of an object. `data' must be a @ref{436,,bytes-like object}.

The protocol version of the pickle is detected automatically, so no
protocol argument is needed.  Bytes past the pickled representation
of the object are ignored.

Arguments `fix_imports', `encoding', `errors', `strict' and `buffers'
have the same meaning as in the @ref{1978,,Unpickler} constructor.


Άλλαξε στην έκδοση 3.8: The `buffers' argument was added.

@end deffn

The @code{pickle} module defines three exceptions:

@geindex PickleError
@anchor{library/pickle pickle PickleError}@anchor{2f32}
@deffn {Εξαίρεση} pickle.PickleError

Common base class for the other pickling exceptions.  It inherits from
@ref{d9e,,Exception}.
@end deffn

@geindex PicklingError
@anchor{library/pickle pickle PicklingError}@anchor{1b5a}
@deffn {Εξαίρεση} pickle.PicklingError

Error raised when an unpicklable object is encountered by @ref{de2,,Pickler}.
It inherits from @ref{2f32,,PickleError}.

Refer to @ref{2f33,,What can be pickled and unpickled?} to learn what kinds of objects can be
pickled.
@end deffn

@geindex UnpicklingError
@anchor{library/pickle pickle UnpicklingError}@anchor{2f34}
@deffn {Εξαίρεση} 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{2f32,,PickleError}.

Note that other exceptions may also be raised during unpickling, including
(but not necessarily limited to) AttributeError, EOFError, ImportError, and
IndexError.
@end deffn

The @code{pickle} module exports three classes, @ref{de2,,Pickler},
@ref{1978,,Unpickler} and @ref{1908,,PickleBuffer}:

@geindex Pickler (κλάση σε pickle)
@anchor{library/pickle pickle Pickler}@anchor{de2}
@deffn {Κλάση} pickle.Pickler (file, protocol=None, *, fix_imports=True, buffer_callback=None)

This takes a binary file for writing a pickle data stream.

The optional `protocol' argument, an integer, tells the pickler to use
the given protocol; supported protocols are 0 to @ref{1847,,HIGHEST_PROTOCOL}.
If not specified, the default is @ref{c07,,DEFAULT_PROTOCOL}.  If a negative
number is specified, @code{HIGHEST_PROTOCOL} is selected.

The `file' argument must have a write() method that accepts a single bytes
argument.  It can thus be an on-disk file opened for binary writing, an
@ref{1255,,io.BytesIO} instance, or any other custom object that meets this
interface.

If `fix_imports' is true and `protocol' is less than 3, pickle will try to
map the new Python 3 names to the old module names used in Python 2, so
that the pickle data stream is readable with Python 2.

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{2f35,,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.


Άλλαξε στην έκδοση 3.8: The `buffer_callback' argument was added.


@geindex dump() (μέθοδος της pickle.Pickler)
@anchor{library/pickle pickle Pickler dump}@anchor{2013}
@deffn {Μέθοδος} dump (obj)

Write the pickled representation of `obj' to the open file object given in
the constructor.
@end deffn

@geindex persistent_id() (μέθοδος της pickle.Pickler)
@anchor{library/pickle pickle Pickler persistent_id}@anchor{1b28}
@deffn {Μέθοδος} persistent_id (obj)

Do nothing by default.  This exists so a subclass can override it.

If @code{persistent_id()} returns @code{None}, `obj' is pickled as usual.  Any
other value causes @code{Pickler} to emit the returned value as a
persistent ID for `obj'.  The meaning of this persistent ID should be
defined by @ref{1b2f,,Unpickler.persistent_load()}.  Note that the value
returned by @code{persistent_id()} cannot itself have a persistent ID.

See @ref{2f36,,Persistence of External Objects} for details and examples of uses.


Άλλαξε στην έκδοση 3.13: Add the default implementation of this method in the C implementation
of @code{Pickler}.

@end deffn

@geindex dispatch_table (ιδιότητα της pickle.Pickler)
@anchor{library/pickle pickle Pickler dispatch_table}@anchor{14ce}
@deffn {Ιδιότητα} dispatch_table

A pickler object’s dispatch table is a registry of `reduction
functions' of the kind which can be declared using
@ref{2f37,,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{d97,,__reduce__()}
method.

By default, a pickler object will not have a
@ref{14ce,,dispatch_table} attribute, and it will instead use the
global dispatch table managed by the @ref{2a,,copyreg} module.
However, to customize the pickling for a specific pickler object
one can set the @code{dispatch_table} attribute to a dict-like
object.  Alternatively, if a subclass of @code{Pickler} has a
@code{dispatch_table} attribute then this will be used as the
default dispatch table for instances of that class.

See @ref{2f38,,Dispatch Tables} for usage examples.


Added in version 3.3.

@end deffn

@geindex reducer_override() (μέθοδος της pickle.Pickler)
@anchor{library/pickle pickle Pickler reducer_override}@anchor{de3}
@deffn {Μέθοδος} reducer_override (obj)

Special reducer that can be defined in @code{Pickler} subclasses. This
method has priority over any reducer in the @ref{14ce,,dispatch_table}.  It
should conform to the same interface as a @ref{d97,,__reduce__()} method, and
can optionally return @ref{440,,NotImplemented} to fallback on
@code{dispatch_table}-registered reducers to pickle @code{obj}.

For a detailed example, see @ref{2f39,,Custom Reduction for Types@comma{} Functions@comma{} and Other Objects}.


Added in version 3.8.

@end deffn

@geindex fast (ιδιότητα της pickle.Pickler)
@anchor{library/pickle pickle Pickler fast}@anchor{2f3a}
@deffn {Ιδιότητα} fast

Deprecated. Enable fast mode if set to a true value.  The fast mode
disables the usage of memo, therefore speeding the pickling process by not
generating superfluous PUT opcodes.  It should not be used with
self-referential objects, doing otherwise will cause @code{Pickler} to
recurse infinitely.

Use @ref{2f3b,,pickletools.optimize()} if you need more compact pickles.
@end deffn

@geindex clear_memo() (μέθοδος της pickle.Pickler)
@anchor{library/pickle pickle Pickler clear_memo}@anchor{2f3c}
@deffn {Μέθοδος} clear_memo ()

Clears the pickler’s «memo».

The memo is the data structure that remembers which objects the
pickler has already seen, so that shared or recursive objects
are pickled by reference and not by value.  This method is
useful when re-using picklers.
@end deffn
@end deffn

@geindex Unpickler (κλάση σε pickle)
@anchor{library/pickle pickle Unpickler}@anchor{1978}
@deffn {Κλάση} pickle.Unpickler (file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

This takes a binary file for reading a pickle data stream.

The protocol version of the pickle is detected automatically, so no
protocol argument is needed.

The argument `file' must have three methods, a read() method that takes an
integer argument, a readinto() method that takes a buffer argument
and a readline() method that requires no arguments, as in the
@ref{a83,,io.BufferedIOBase} interface.  Thus `file' can be an on-disk file
opened for binary reading, an @ref{1255,,io.BytesIO} object, or any other
custom object that meets this interface.

The optional arguments `fix_imports', `encoding' and `errors' are used
to control compatibility support for pickle stream generated by Python 2.
If `fix_imports' is true, pickle will try to map the old Python 2 names
to the new names used in Python 3.  The `encoding' and `errors' tell
pickle how to decode 8-bit string instances pickled by Python 2;
these default to “ASCII” and “strict”, respectively.  The `encoding' can
be “bytes” to read these 8-bit string instances as bytes objects.
Using @code{encoding='latin1'} is required for unpickling NumPy arrays and
instances of @ref{6e7,,datetime}, @ref{48d,,date} and
@ref{48e,,time} pickled by 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{de2,,Pickler}
was instantiated (or when @ref{2f31,,dump()} or @ref{1846,,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{2f35,,out-of-band} buffer view.  Such buffers have been
given in order to the `buffer_callback' of a Pickler object.


Άλλαξε στην έκδοση 3.8: The `buffers' argument was added.


@geindex load() (μέθοδος της pickle.Unpickler)
@anchor{library/pickle pickle Unpickler load}@anchor{2f3d}
@deffn {Μέθοδος} load ()

Read the pickled representation of an object from the open file object
given in the constructor, and return the reconstituted object hierarchy
specified therein.  Bytes past the pickled representation of the object
are ignored.
@end deffn

@geindex persistent_load() (μέθοδος της pickle.Unpickler)
@anchor{library/pickle pickle Unpickler persistent_load}@anchor{1b2f}
@deffn {Μέθοδος} persistent_load (pid)

Raise an @ref{2f34,,UnpicklingError} by default.

If defined, @code{persistent_load()} should return the object specified by
the persistent ID `pid'.  If an invalid persistent ID is encountered, an
@ref{2f34,,UnpicklingError} should be raised.

See @ref{2f36,,Persistence of External Objects} for details and examples of uses.


Άλλαξε στην έκδοση 3.13: Add the default implementation of this method in the C implementation
of @code{Unpickler}.

@end deffn

@geindex find_class() (μέθοδος της pickle.Unpickler)
@anchor{library/pickle pickle Unpickler find_class}@anchor{19b5}
@deffn {Μέθοδος} find_class (module, name)

Import `module' if necessary and return the object called `name' from it,
where the `module' and `name' arguments are @ref{1df,,str} objects.  Note,
unlike its name suggests, @code{find_class()} is also used for finding
functions.

Subclasses may override this to gain control over what type of objects and
how they can be loaded, potentially reducing security risks. Refer to
@ref{2f3e,,Restricting Globals} for details.

Raises an @ref{1e65,,auditing event} @code{pickle.find_class} with arguments @code{module}, @code{name}.
@end deffn
@end deffn

@geindex PickleBuffer (κλάση σε pickle)
@anchor{library/pickle pickle PickleBuffer}@anchor{1908}
@deffn {Κλάση} pickle.PickleBuffer (buffer)

A wrapper for a buffer representing picklable data.  `buffer' must be a
@ref{311,,buffer-providing} object, such as a
@ref{436,,bytes-like object} or a N-dimensional array.

@code{PickleBuffer} is itself a buffer provider, therefore it is
possible to pass it to other APIs expecting a buffer-providing object,
such as @ref{1d2,,memoryview}.

@code{PickleBuffer} objects can only be serialized using pickle
protocol 5 or higher.  They are eligible for
@ref{2f35,,out-of-band serialization}.


Added in version 3.8.


@geindex raw() (μέθοδος της pickle.PickleBuffer)
@anchor{library/pickle pickle PickleBuffer raw}@anchor{2f3f}
@deffn {Μέθοδος} raw ()

Return a @ref{1d2,,memoryview} of the memory area underlying this buffer.
The returned object is a one-dimensional, C-contiguous memoryview
with format @code{B} (unsigned bytes).  @ref{1998,,BufferError} is raised if
the buffer is neither C- nor Fortran-contiguous.
@end deffn

@geindex release() (μέθοδος της pickle.PickleBuffer)
@anchor{library/pickle pickle PickleBuffer release}@anchor{2f40}
@deffn {Μέθοδος} release ()

Release the underlying buffer exposed by the PickleBuffer object.
@end deffn
@end deffn

@node What can be pickled and unpickled?,Pickling Class Instances,Module Interface,pickle — Python object serialization
@anchor{library/pickle pickle-picklable}@anchor{2f33}@anchor{library/pickle what-can-be-pickled-and-unpickled}@anchor{2f41}
@subsubsection What can be pickled and unpickled?


The following types can be pickled:


@itemize *

@item 
built-in constants (@code{None}, @code{True}, @code{False}, @code{Ellipsis}, and
@ref{440,,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{17fc,,def}, not @ref{1642,,lambda});

@item 
classes accessible from the top level of a module;

@item 
instances of such classes for which the result of calling @ref{9d3,,__getstate__()}
is picklable  (see section @ref{2f2c,,Pickling Class Instances} for details).
@end itemize

Attempts to pickle unpicklable objects will raise the @ref{1b5a,,PicklingError}
exception; when this happens, an unspecified number of bytes may have already
been written to the underlying file.  Trying to pickle a highly recursive data
structure may exceed the maximum recursion depth, a @ref{1121,,RecursionError} will be
raised in this case.  You can carefully raise this limit with
@ref{8d3,,sys.setrecursionlimit()}.

Note that functions (built-in and user-defined) are pickled by fully
@ref{1f19,,qualified name}, not by value. @footnote{
This is why @ref{1642,,lambda} functions cannot be pickled:  all
@code{lambda} functions share the same name:  @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{
The exception raised will likely be an @ref{1bd,,ImportError} or an
@ref{1a9,,AttributeError} but it could be something else.
}

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{d98,,__setstate__()} method.

@node Pickling Class Instances,Custom Reduction for Types Functions and Other Objects,What can be pickled and unpickled?,pickle — Python object serialization
@anchor{library/pickle pickle-inst}@anchor{2f2c}@anchor{library/pickle pickling-class-instances}@anchor{2f42}
@subsubsection Pickling Class Instances


In this section, we describe the general mechanisms available to you to define,
customize, and control how class instances are pickled and unpickled.

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{2fa,,__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

Classes can alter the default behaviour by providing one or several special
methods:

@geindex __getnewargs_ex__() (μέθοδος της object)
@anchor{library/pickle object __getnewargs_ex__}@anchor{2f43}
@deffn {Μέθοδος} object.__getnewargs_ex__ ()

In protocols 2 and newer, classes that implement the
@code{__getnewargs_ex__()} method can dictate the values passed to the
@ref{982,,__new__()} method upon unpickling.  The method must return a pair
@code{(args, kwargs)} where `args' is a tuple of positional arguments
and `kwargs' a dictionary of named arguments for constructing the
object.  Those will be passed to the @code{__new__()} method upon
unpickling.

You should implement this method if the @ref{982,,__new__()} method of your
class requires keyword-only arguments.  Otherwise, it is recommended for
compatibility to implement @ref{118d,,__getnewargs__()}.


Άλλαξε στην έκδοση 3.6: @code{__getnewargs_ex__()} is now used in protocols 2 and 3.

@end deffn

@geindex __getnewargs__() (μέθοδος της object)
@anchor{library/pickle object __getnewargs__}@anchor{118d}
@deffn {Μέθοδος} object.__getnewargs__ ()

This method serves a similar purpose as @ref{2f43,,__getnewargs_ex__()}, but
supports only positional arguments.  It must return a tuple of arguments
@code{args} which will be passed to the @ref{982,,__new__()} method upon unpickling.

@code{__getnewargs__()} will not be called if @ref{2f43,,__getnewargs_ex__()} is
defined.


Άλλαξε στην έκδοση 3.6: Before Python 3.6, @code{__getnewargs__()} was called instead of
@ref{2f43,,__getnewargs_ex__()} in protocols 2 and 3.

@end deffn

@geindex __getstate__() (μέθοδος της object)
@anchor{library/pickle object __getstate__}@anchor{9d3}
@deffn {Μέθοδος} object.__getstate__ ()

Classes can further influence how their instances are pickled by overriding
the method @code{__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{1bf,,__dict__} and no
@ref{188d,,__slots__}, the default state is @code{None}.

@item 
For a class that has an instance @ref{1bf,,__dict__} and no
@ref{188d,,__slots__}, the default state is @code{self.__dict__}.

@item 
For a class that has an instance @ref{1bf,,__dict__} and
@ref{188d,,__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{188d,,__slots__} and no instance
@ref{1bf,,__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


Άλλαξε στην έκδοση 3.11: Added the default implementation of the @code{__getstate__()} method in the
@ref{e4d,,object} class.

@end deffn

@geindex __setstate__() (μέθοδος της object)
@anchor{library/pickle object __setstate__}@anchor{d98}
@deffn {Μέθοδος} object.__setstate__ (state)

Upon unpickling, if the class defines @code{__setstate__()}, it is called with
the unpickled state.  In that case, there is no requirement for the state
object to be a dictionary.  Otherwise, the pickled state must be a dictionary
and its items are assigned to the new instance’s dictionary.

@cartouche
@quotation Σημείωση 
If @ref{d97,,__reduce__()} returns a state with value @code{None} at pickling,
the @code{__setstate__()} method will not be called upon unpickling.
@end quotation
@end cartouche
@end deffn

Refer to the section @ref{2f44,,Handling Stateful Objects} for more information about how to use
the methods @ref{9d3,,__getstate__()} and @ref{d98,,__setstate__()}.

@cartouche
@quotation Σημείωση 
At unpickling time, some methods like @ref{8e3,,__getattr__()},
@ref{f90,,__getattribute__()}, or @ref{256d,,__setattr__()} may be called upon the
instance.  In case those methods rely on some internal invariant being
true, the type should implement @ref{982,,__new__()} to establish such an
invariant, as @ref{2fa,,__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{d97,,__reduce__()} special method.  The copy protocol provides a unified
interface for retrieving the data necessary for pickling and copying
objects. @footnote{
The @ref{29,,copy} module uses this protocol for shallow and deep copying
operations.
}

Although powerful, implementing @ref{d97,,__reduce__()} directly in your classes is
error prone.  For this reason, class designers should use the high-level
interface (i.e., @ref{2f43,,__getnewargs_ex__()}, @ref{9d3,,__getstate__()} and
@ref{d98,,__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__() (μέθοδος της object)
@anchor{library/pickle object __reduce__}@anchor{d97}
@deffn {Μέθοδος} object.__reduce__ ()

The interface is currently defined as follows.  The @code{__reduce__()} method
takes no argument and shall return either a string or preferably a tuple (the
returned object is often referred to as the «reduce value»).

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.

When a tuple is returned, it must be between two and six items long.
Optional items can either be omitted, or @code{None} can be provided as their
value.  The semantics of each item are in order:

@c XXX Mention __newobj__ special-case?


@itemize *

@item 
A callable object that will be called to create the initial version of the
object.

@item 
A tuple of arguments for the callable object.  An empty tuple must be given
if the callable does not accept any argument.

@item 
Optionally, the object’s state, which will be passed to the object’s
@ref{d98,,__setstate__()} method as previously described.  If the object has no
such method then, the value must be a dictionary and it will be added to
the object’s @ref{1bf,,__dict__} attribute.

@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{25cb,,append()}
and @ref{25ce,,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 
Optionally, an iterator (not a sequence) yielding successive key-value
pairs.  These items will be stored to the object using @code{obj[key] =
value}.  This is primarily used for dictionary subclasses, but may be used
by other classes as long as they implement @ref{1670,,__setitem__()}.

@item 
Optionally, a callable with a @code{(obj, state)} signature. This
callable allows the user to programmatically control the state-updating
behavior of a specific object, instead of using @code{obj}’s static
@ref{d98,,__setstate__()} method. If not @code{None}, this callable will have
priority over @code{obj}’s @code{__setstate__()}.


Added in version 3.8: The optional sixth tuple item, @code{(obj, state)}, was added.

@end itemize
@end deffn

@geindex __reduce_ex__() (μέθοδος της object)
@anchor{library/pickle object __reduce_ex__}@anchor{1b7e}
@deffn {Μέθοδος} object.__reduce_ex__ (protocol)

Alternatively, a @code{__reduce_ex__()} method may be defined.  The only
difference is this method should take a single integer argument, the protocol
version.  When defined, pickle will prefer it over the @ref{d97,,__reduce__()}
method.  In addition, @code{__reduce__()} automatically becomes a synonym for
the extended version.  The main use for this method is to provide
backwards-compatible reduce values for older Python releases.
@end deffn

@menu
* Persistence of External Objects:: 
* Dispatch Tables:: 
* Handling Stateful Objects:: 

@end menu

@node Persistence of External Objects,Dispatch Tables,,Pickling Class Instances
@anchor{library/pickle persistence-of-external-objects}@anchor{2f45}@anchor{library/pickle pickle-persistent}@anchor{2f36}
@subsubsection Persistence of External Objects


@geindex persistent_id (pickle protocol)
@geindex persistent_load (pickle protocol)

For the benefit of object persistence, the @code{pickle} module supports the
notion of a reference to an object outside the pickled data stream.  Such
objects are referenced by a persistent ID, which should be either a string of
alphanumeric characters (for protocol 0) @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.
} or just an arbitrary object (for
any newer protocol).

The resolution of such persistent IDs is not defined by the @code{pickle}
module; it will delegate this resolution to the user-defined methods on the
pickler and unpickler, @ref{1b28,,persistent_id()} and
@ref{1b2f,,persistent_load()} respectively.

To pickle objects that have an external persistent ID, the pickler must have a
custom @ref{1b28,,persistent_id()} method that takes an object as an
argument and returns either @code{None} or the persistent ID for that object.
When @code{None} is returned, the pickler simply pickles the object as normal.
When a persistent ID string is returned, the pickler will pickle that object,
along with a marker so that the unpickler will recognize it as a persistent ID.

To unpickle external objects, the unpickler must have a custom
@ref{1b2f,,persistent_load()} method that takes a persistent ID object and
returns the referenced object.

Here is a comprehensive example presenting how persistent ID can be used to
pickle external objects by reference.

@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 Dispatch Tables,Handling Stateful Objects,Persistence of External Objects,Pickling Class Instances
@anchor{library/pickle dispatch-tables}@anchor{2f46}@anchor{library/pickle pickle-dispatch}@anchor{2f38}
@subsubsection Dispatch Tables


If one wants to customize pickling of some classes without disturbing
any other code which depends on pickling, then one can create a
pickler with a private dispatch table.

The global dispatch table managed by the @ref{2a,,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.

For example

@example
f = io.BytesIO()
p = pickle.Pickler(f)
p.dispatch_table = copyreg.dispatch_table.copy()
p.dispatch_table[SomeClass] = reduce_SomeClass
@end example

creates an instance of @ref{de2,,pickle.Pickler} with a private dispatch
table which handles the @code{SomeClass} class specially.  Alternatively,
the 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{2a,,copyreg} module.

@node Handling Stateful Objects,,Dispatch Tables,Pickling Class Instances
@anchor{library/pickle handling-stateful-objects}@anchor{2f47}@anchor{library/pickle pickle-state}@anchor{2f44}
@subsubsection Handling Stateful Objects


@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

A sample usage might be something like this:

@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 Custom Reduction for Types Functions and Other Objects,Out-of-band Buffers,Pickling Class Instances,pickle — Python object serialization
@anchor{library/pickle custom-reduction-for-types-functions-and-other-objects}@anchor{2f48}@anchor{library/pickle reducer-override}@anchor{2f39}
@subsubsection Custom Reduction for Types, Functions, and Other Objects



Added in version 3.8.


Sometimes, @ref{14ce,,dispatch_table} may not be flexible enough.
In particular we may want to customize pickling based on another criterion
than the object’s type, or we may want to customize the pickling of
functions and classes.

For those cases, it is possible to subclass from the @ref{de2,,Pickler} class and
implement a @ref{de3,,reducer_override()} method. This method can return an
arbitrary reduction tuple (see @ref{d97,,__reduce__()}). It can alternatively return
@ref{440,,NotImplemented} to fallback to the traditional behavior.

If both the @ref{14ce,,dispatch_table} and
@ref{de3,,reducer_override()} are defined, then
@code{reducer_override()} method takes priority.

@cartouche
@quotation Σημείωση 
For performance reasons, @ref{de3,,reducer_override()} may not be
called for the following objects: @code{None}, @code{True}, @code{False}, and
exact instances of @ref{326,,int}, @ref{327,,float}, @ref{1c7,,bytes},
@ref{1df,,str}, @ref{188,,dict}, @ref{42b,,set}, @ref{9d4,,frozenset}, @ref{4d9,,list}
and @ref{1ce,,tuple}.
@end quotation
@end cartouche

Here is a simple example where we allow pickling and reconstructing
a given class:

@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 Out-of-band Buffers,Restricting Globals,Custom Reduction for Types Functions and Other Objects,pickle — Python object serialization
@anchor{library/pickle out-of-band-buffers}@anchor{2f49}@anchor{library/pickle pickle-oob}@anchor{2f35}
@subsubsection Out-of-band Buffers



Added in version 3.8.


In some contexts, the @code{pickle} module is used to transfer massive amounts
of data.  Therefore, it can be important to minimize the number of memory
copies, to preserve performance and resource consumption.  However, normal
operation of the @code{pickle} module, as it transforms a graph-like structure
of objects into a sequential stream of bytes, intrinsically involves copying
data to and from the pickle stream.

This constraint can be eschewed if both the `provider' (the implementation
of the object types to be transferred) and the `consumer' (the implementation
of the communications system) support the out-of-band transfer facilities
provided by pickle protocol 5 and higher.

@menu
* Provider API:: 
* Consumer API:: 
* Example: Example<4>. 

@end menu

@node Provider API,Consumer API,,Out-of-band Buffers
@anchor{library/pickle provider-api}@anchor{2f4a}
@subsubsection Provider API


The large data objects to be pickled must implement a @ref{1b7e,,__reduce_ex__()}
method specialized for protocol 5 and higher, which returns a
@ref{1908,,PickleBuffer} instance (instead of e.g. a @ref{1c7,,bytes} object)
for any large data.

A @ref{1908,,PickleBuffer} object `signals' that the underlying buffer is
eligible for out-of-band data transfer.  Those objects remain compatible
with normal usage of the @code{pickle} module.  However, consumers can also
opt-in to tell @code{pickle} that they will handle those buffers by
themselves.

@node Consumer API,Example<4>,Provider API,Out-of-band Buffers
@anchor{library/pickle consumer-api}@anchor{2f4b}
@subsubsection Consumer API


A communications system can enable custom handling of the @ref{1908,,PickleBuffer}
objects generated when serializing an object graph.

On the sending side, it needs to pass a `buffer_callback' argument to
@ref{de2,,Pickler} (or to the @ref{2f31,,dump()} or @ref{1846,,dumps()} function), which
will be called with each @ref{1908,,PickleBuffer} generated while pickling
the object graph.  Buffers accumulated by the `buffer_callback' will not
see their data copied into the pickle stream, only a cheap marker will be
inserted.

On the receiving side, it needs to pass a `buffers' argument to
@ref{1978,,Unpickler} (or to the @ref{10ca,,load()} or @ref{10cb,,loads()} function),
which is an iterable of the buffers which were passed to `buffer_callback'.
That iterable should produce buffers in the same order as they were passed
to `buffer_callback'.  Those buffers will provide the data expected by the
reconstructors of the objects whose pickling produced the original
@ref{1908,,PickleBuffer} objects.

Between the sending side and the receiving side, the communications system
is free to implement its own transfer mechanism for out-of-band buffers.
Potential optimizations include the use of shared memory or datatype-dependent
compression.

@node Example<4>,,Consumer API,Out-of-band Buffers
@anchor{library/pickle example}@anchor{2f4c}
@subsubsection Example


Here is a trivial example where we implement a @ref{1c6,,bytearray} subclass
able to participate in out-of-band buffer pickling:

@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

The reconstructor (the @code{_reconstruct} class method) returns the buffer’s
providing object if it has the right type.  This is an easy way to simulate
zero-copy behaviour on this toy example.

On the consumer side, we can pickle those objects the usual way, which
when unserialized will give us a copy of the original object:

@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

But if we pass a `buffer_callback' and then give back the accumulated
buffers when unserializing, we are able to get back the original object:

@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

This example is limited by the fact that @ref{1c6,,bytearray} allocates its
own memory: you cannot create a @code{bytearray} instance that is backed
by another object’s memory.  However, third-party datatypes such as NumPy
arrays do not have this limitation, and allow use of zero-copy pickling
(or making as few copies as possible) when transferring between distinct
processes or systems.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 574
PEP 574@footnote{https://peps.python.org/pep-0574/} – Pickle protocol 5 with out-of-band data


@node Restricting Globals,Performance<2>,Out-of-band Buffers,pickle — Python object serialization
@anchor{library/pickle pickle-restrict}@anchor{2f3e}@anchor{library/pickle restricting-globals}@anchor{2f4d}
@subsubsection Restricting Globals


@geindex find_class() (pickle protocol)

By default, unpickling will import any class or function that it finds in the
pickle data.  For many applications, this behaviour is unacceptable as it
permits the unpickler to import and invoke arbitrary code.  Just consider what
this hand-crafted pickle data stream does when loaded:

@example
>>> import pickle
>>> pickle.loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
hello world
0
@end example

In this example, the unpickler imports the @ref{17ff,,os.system()} function and then
apply the string argument «echo hello world».  Although this example is
inoffensive, it is not difficult to imagine one that could damage your system.

For this reason, you may want to control what gets unpickled by customizing
@ref{19b5,,Unpickler.find_class()}.  Unlike its name suggests,
@code{Unpickler.find_class()} is called whenever a global (i.e., a class or
a function) is requested.  Thus it is possible to either completely forbid
globals or restrict them to a safe subset.

Here is an example of an unpickler allowing only few safe classes from the
@ref{13,,builtins} module to be loaded:

@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()).

As our examples shows, you have to be careful with what you allow to be
unpickled.  Therefore if security is a concern, you may want to consider
alternatives such as the marshalling API in @ref{137,,xmlrpc.client} or
third-party solutions.

@node Performance<2>,Examples<5>,Restricting Globals,pickle — Python object serialization
@anchor{library/pickle performance}@anchor{2f4e}
@subsubsection Performance


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 @code{pickle} module has a transparent optimizer written in C.

@node Examples<5>,Command-line interface,Performance<2>,pickle — Python object serialization
@anchor{library/pickle examples}@anchor{2f4f}@anchor{library/pickle pickle-example}@anchor{2f50}
@subsubsection Examples


For the simplest code, use the @ref{2f31,,dump()} and @ref{10ca,,load()} functions.

@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

The following example reads the resulting pickled data.

@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).

@node Command-line interface,,Examples<5>,pickle — Python object serialization
@anchor{library/pickle command-line-interface}@anchor{2f51}@anchor{library/pickle pickle-cli}@anchor{2f52}
@subsubsection Command-line interface


The @code{pickle} module can be invoked as a script from the command line,
it will display contents of the pickle files. 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, see
@ref{2f53,,pickletools CLI usage}.

@example
python -m pickle pickle_file [pickle_file ...]
@end example

The following option is accepted:

@geindex pickle command line option; pickle_file
@anchor{library/pickle cmdoption-pickle-arg-pickle_file}@anchor{2f54}
@deffn {Option} pickle_file

A pickle file to read, or @code{-} to indicate reading from standard input.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{2a,,copyreg}

Pickle interface constructor registration for extension types.

@item Module @ref{ac,,pickletools}

Tools for working with and analyzing pickled data.

@item Module @ref{cb,,shelve}

Indexed databases of objects; uses @code{pickle}.

@item Module @ref{29,,copy}

Shallow and deep object copying.

@item Module @ref{90,,marshal}

High-performance serialization of built-in types.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node copyreg — Register pickle support functions,shelve — Python object persistence,pickle — Python object serialization,Data Persistence
@anchor{library/copyreg doc}@anchor{2f55}@anchor{library/copyreg copyreg-register-pickle-support-functions}@anchor{2f56}@anchor{library/copyreg module-copyreg}@anchor{2a}@anchor{library/copyreg translation-repo}@anchor{2f57}
@subsection @code{copyreg} — Register @code{pickle} support functions


@geindex module; copyreg

`Source code:' Lib/copyreg.py@footnote{https://github.com/python/cpython/tree/main/Lib/copyreg.py}

@geindex module;pickle
@geindex module;copy


__________________________________________________________________


The @code{copyreg} module offers a way to define functions used while pickling
specific objects.  The @ref{ab,,pickle} and @ref{29,,copy} modules use those functions
when pickling/copying those objects.  The module provides configuration
information about object constructors which are not classes.
Such constructors may be factory functions or class instances.

@geindex constructor() (στη μονάδα copyreg)
@anchor{library/copyreg copyreg constructor}@anchor{2f58}
@deffn {Συνάρτηση} copyreg.constructor (object)

Declares `object' to be a valid constructor.  If `object' is not callable (and
hence not valid as a constructor), raises @ref{291,,TypeError}.
@end deffn

@geindex pickle() (στη μονάδα copyreg)
@anchor{library/copyreg copyreg pickle}@anchor{2f37}
@deffn {Συνάρτηση} 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{14ce,,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{14ce,,dispatch_table} attribute of a pickler
object or subclass of @ref{de2,,pickle.Pickler} can also be used for
declaring reduction functions.
@end deffn

@menu
* Example: Example<5>. 

@end menu

@node Example<5>,,,copyreg — Register pickle support functions
@anchor{library/copyreg example}@anchor{2f59}
@subsubsection Example


The example below would like to show how to register a pickle function and how
it will be used:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node shelve — Python object persistence,marshal — Internal Python object serialization,copyreg — Register pickle support functions,Data Persistence
@anchor{library/shelve doc}@anchor{2f5a}@anchor{library/shelve module-shelve}@anchor{cb}@anchor{library/shelve shelve-python-object-persistence}@anchor{2f5b}@anchor{library/shelve translation-repo}@anchor{2f5c}
@subsection @code{shelve} — Python object persistence


@geindex module; shelve

`Source code:' Lib/shelve.py@footnote{https://github.com/python/cpython/tree/main/Lib/shelve.py}

@geindex module;pickle


__________________________________________________________________


A «shelf» is a persistent, dictionary-like object.  The difference with «dbm»
databases is that the values (not the keys!) in a shelf can be essentially
arbitrary Python objects — anything that the @ref{ab,,pickle} module can handle.
This includes most class instances, recursive data types, and objects containing
lots of shared  sub-objects.  The keys are ordinary strings.

@geindex open() (στη μονάδα shelve)
@anchor{library/shelve shelve open}@anchor{1c77}
@deffn {Συνάρτηση} shelve.open (filename, flag='c', protocol=None, writeback=False, *, serializer=None, deserializer=None)

Open a persistent dictionary.  The filename specified is the base filename for
the underlying database.  As a side-effect, an extension may be added to the
filename and more than one file may be created.  By default, the underlying
database file is opened for reading and writing.  The optional `flag' parameter
has the same interpretation as the `flag' parameter of @ref{12d7,,dbm.open()}.

By default, pickles created with @ref{c07,,pickle.DEFAULT_PROTOCOL} are used
to serialize values.  The version of the pickle protocol can be specified
with the `protocol' parameter.

Because of Python semantics, a shelf cannot know when a mutable
persistent-dictionary entry is modified.  By default modified objects are
written `only' when assigned to the shelf (see @ref{2f5d,,Example}).  If the
optional `writeback' parameter is set to @code{True}, all entries accessed are also
cached in memory, and written back on @ref{2f5e,,sync()} and
@ref{2f5f,,close()}; this can make it handier to mutate mutable entries in
the persistent dictionary, but, if many entries are accessed, it can consume
vast amounts of memory for the cache, and it can make the close operation
very slow since all accessed entries are written back (there is no way to
determine which accessed entries are mutable, nor which ones were actually
mutated).

By default, @code{shelve} uses @ref{1846,,pickle.dumps()} and @ref{10cb,,pickle.loads()}
for serializing and deserializing. This can be changed by supplying
`serializer' and `deserializer', respectively.

The `serializer' argument must be a callable which takes an object @code{obj}
and the `protocol' as inputs and returns the representation @code{obj} as a
@ref{436,,bytes-like object}; the `protocol' value may be ignored by the
serializer.

The `deserializer' argument must be a callable which takes a serialized object
given as a @ref{1c7,,bytes} object and returns the corresponding object.

A @ref{2f60,,ShelveError} is raised if `serializer' is given but `deserializer'
is not, or vice-versa.


Άλλαξε στην έκδοση 3.10: @ref{c07,,pickle.DEFAULT_PROTOCOL} is now used as the default pickle
protocol.



Άλλαξε στην έκδοση 3.11: Accepts @ref{79f,,path-like object} for filename.



Άλλαξε στην έκδοση 3.15: Accepts custom `serializer' and `deserializer' functions in place of
@ref{1846,,pickle.dumps()} and @ref{10cb,,pickle.loads()}.


@cartouche
@quotation Σημείωση 
Do not rely on the shelf being closed automatically; always call
@ref{2f5f,,close()} explicitly when you don’t need it any more, or
use @ref{1c77,,shelve.open()} as a context manager:

@example
with shelve.open('spam') as db:
    db['eggs'] = 'eggs'
@end example
@end quotation
@end cartouche
@end deffn
@anchor{library/shelve shelve-security}@anchor{2f61}
@cartouche
@quotation Προειδοποίηση 
Because the @code{shelve} module is backed by @ref{ab,,pickle}, it is insecure
to load a shelf from an untrusted source.  Like with pickle, loading a shelf
can execute arbitrary code.
@end quotation
@end cartouche

Shelf objects support most of the methods and operations supported by dictionaries
(except copying, constructors and operators @code{|} and @code{|=}).  This eases the
transition from dictionary based scripts to those requiring persistent storage.

Two additional methods are supported:

@geindex sync() (μέθοδος της shelve.Shelf)
@anchor{library/shelve shelve Shelf sync}@anchor{2f5e}
@deffn {Μέθοδος} Shelf.sync ()

Write back all entries in the cache if the shelf was opened with `writeback'
set to @ref{fcc,,True}.  Also empty the cache and synchronize the persistent
dictionary on disk, if feasible.  This is called automatically when
@ref{2f62,,reorganize()} is called or the shelf is closed with @ref{2f5f,,close()}.
@end deffn

@geindex reorganize() (μέθοδος της shelve.Shelf)
@anchor{library/shelve shelve Shelf reorganize}@anchor{2f62}
@deffn {Μέθοδος} Shelf.reorganize ()

Calls @ref{2f5e,,sync()} and attempts to shrink space used on disk by removing empty
space resulting from deletions.


Added in version 3.15.

@end deffn

@geindex close() (μέθοδος της shelve.Shelf)
@anchor{library/shelve shelve Shelf close}@anchor{2f5f}
@deffn {Μέθοδος} Shelf.close ()

Synchronize and close the persistent `dict' object.  Operations on a closed
shelf will fail with a @ref{277,,ValueError}.
@end deffn


@subsubheading Δείτε επίσης


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
* Restrictions:: 
* Example: Example<6>. 
* Exceptions: Exceptions<5>. 

@end menu

@node Restrictions,Example<6>,,shelve — Python object persistence
@anchor{library/shelve restrictions}@anchor{2f63}
@subsubsection Restrictions


@geindex module;dbm.ndbm
@geindex module;dbm.gnu


@itemize *

@item 
The choice of which database package will be used (such as @ref{37,,dbm.ndbm} or
@ref{36,,dbm.gnu}) depends on which interface is available.  Therefore it is not
safe to open the database directly using @ref{34,,dbm}.  The database is also
(unfortunately) subject to the limitations of @code{dbm}, if it is used —
this means that (the pickled representation of) the objects stored in the
database should be fairly small, and in rare cases key collisions may cause
the database to refuse updates.

@item 
The @code{shelve} module does not support `concurrent' read/write access to
shelved objects.  (Multiple simultaneous read accesses are safe.)  When a
program has a shelf open for writing, no other program should have it open for
reading or writing.  Unix file locking can be used to solve this, but this
differs across Unix versions and requires knowledge about the database
implementation used.

@item 
On macOS @ref{37,,dbm.ndbm} can silently corrupt the database file on updates,
which can cause hard crashes when trying to read from the database.

@item 
@ref{2f62,,Shelf.reorganize()} may not be available for all database packages and
may temporarily increase resource usage (especially disk space) when called.
Additionally, it will never run automatically and instead needs to be called
explicitly.
@end itemize

@geindex Shelf (κλάση σε shelve)
@anchor{library/shelve shelve Shelf}@anchor{1344}
@deffn {Κλάση} shelve.Shelf (dict, protocol=None, writeback=False, keyencoding='utf-8', *, serializer=None, deserializer=None)

A subclass of @ref{1459,,collections.abc.MutableMapping} which stores pickled
values in the `dict' object.

By default, pickles created with @ref{c07,,pickle.DEFAULT_PROTOCOL} are used
to serialize values.  The version of the pickle protocol can be specified
with the `protocol' parameter.  See the @ref{ab,,pickle} documentation for a
discussion of the pickle protocols.

If the `writeback' parameter is @code{True}, the object will hold a cache of all
entries accessed and write them back to the `dict' at sync and close times.
This allows natural operations on mutable entries, but can consume much more
memory and make sync and close take a long time.

The `keyencoding' parameter is the encoding used to encode keys before they
are used with the underlying dict.

The `serializer' and `deserializer' parameters have the same interpretation
as in @ref{1c77,,open()}.

A @code{Shelf} object can also be used as a context manager, in which
case it will be automatically closed when the @ref{20a,,with} block ends.


Άλλαξε στην έκδοση 3.2: Added the `keyencoding' parameter; previously, keys were always encoded in
UTF-8.



Άλλαξε στην έκδοση 3.4: Added context manager support.



Άλλαξε στην έκδοση 3.10: @ref{c07,,pickle.DEFAULT_PROTOCOL} is now used as the default pickle
protocol.



Άλλαξε στην έκδοση 3.15: Added the `serializer' and `deserializer' parameters.

@end deffn

@geindex BsdDbShelf (κλάση σε shelve)
@anchor{library/shelve shelve BsdDbShelf}@anchor{28b4}
@deffn {Κλάση} shelve.BsdDbShelf (dict, protocol=None, writeback=False, keyencoding='utf-8', *, serializer=None, deserializer=None)

A subclass of @ref{1344,,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', `keyencoding', `serializer' and `deserializer'
parameters have the same interpretation as in @ref{1c77,,open()}.


Άλλαξε στην έκδοση 3.15: Added the `serializer' and `deserializer' parameters.

@end deffn

@geindex DbfilenameShelf (κλάση σε shelve)
@anchor{library/shelve shelve DbfilenameShelf}@anchor{28b5}
@deffn {Κλάση} shelve.DbfilenameShelf (filename, flag='c', protocol=None, writeback=False, *, serializer=None, deserializer=None)

A subclass of @ref{1344,,Shelf} which accepts a `filename' instead of a dict-like
object.  The underlying file will be opened using @ref{12d7,,dbm.open()}.  By
default, the file will be created and opened for both read and write.  The
optional `flag' parameter has the same interpretation as for the
@ref{1c77,,open()} function.  The optional `protocol', `writeback', `serializer'
and `deserializer' parameters have the same interpretation as in
@ref{1c77,,open()}.


Άλλαξε στην έκδοση 3.15: Added the `serializer' and `deserializer' parameters.

@end deffn

@node Example<6>,Exceptions<5>,Restrictions,shelve — Python object persistence
@anchor{library/shelve example}@anchor{2f64}@anchor{library/shelve shelve-example}@anchor{2f5d}
@subsubsection Example


To summarize the interface (@code{key} is a string, @code{data} is an arbitrary
object):

@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

@node Exceptions<5>,,Example<6>,shelve — Python object persistence
@anchor{library/shelve exceptions}@anchor{2f65}
@subsubsection Exceptions


@geindex ShelveError
@anchor{library/shelve shelve ShelveError}@anchor{2f60}
@deffn {Εξαίρεση} shelve.ShelveError

Exception raised when one of the arguments `deserializer' and `serializer'
is missing in the @ref{1c77,,open()}, @ref{1344,,Shelf}, @ref{28b4,,BsdDbShelf}
and @ref{28b5,,DbfilenameShelf}.

The `deserializer' and `serializer' arguments must be given together.


Added in version 3.15.

@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{34,,dbm}

Generic interface to @code{dbm}-style databases.

@item Module @ref{ab,,pickle}

Object serialization used by @code{shelve}.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node marshal — Internal Python object serialization,dbm — Interfaces to Unix «databases»,shelve — Python object persistence,Data Persistence
@anchor{library/marshal doc}@anchor{2f66}@anchor{library/marshal marshal-internal-python-object-serialization}@anchor{2f67}@anchor{library/marshal module-marshal}@anchor{90}@anchor{library/marshal translation-repo}@anchor{2f68}
@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{
The name of this module stems from a bit of terminology used by the designers of
Modula-3 (amongst others), who use the term «marshalling» for shipping of data
around in a self-contained form. Strictly speaking, «to marshal» means to
convert some data from internal to external form (in an RPC buffer for instance)
and «unmarshalling» for the reverse process.
}

@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{ab,,pickle} and
@ref{cb,,shelve}.  The @code{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 @code{pickle} module instead – the
performance is comparable, version independence is guaranteed, and pickle
supports a substantially wider range of objects than marshal.

@cartouche
@quotation Προειδοποίηση 
The @code{marshal} module is not intended to be secure against erroneous or
maliciously constructed data.  Never unmarshal data received from an
untrusted or unauthenticated source.
@end quotation
@end cartouche

There are functions that read/write files as well as functions operating on
bytes-like objects.

@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:


@itemize *

@item 
Numeric types: @ref{326,,int}, @ref{5ef,,bool}, @ref{327,,float}, @ref{328,,complex}.

@item 
Strings (@ref{1df,,str}) and @ref{1c7,,bytes}.
@ref{436,,Bytes-like objects} like @ref{1c6,,bytearray} are
marshalled as @code{bytes}.

@item 
Containers: @ref{1ce,,tuple}, @ref{4d9,,list}, @ref{188,,dict}, @ref{182,,frozendict}
(since @ref{2f69,,version} 6), @ref{42b,,set}, @ref{9d4,,frozenset}, and
@ref{1d0,,slice} (since @code{version} 5).
It should be understood that these are supported only if the values contained
therein are themselves supported.
Recursive containers are supported since @code{version} 3.

@item 
The singletons @ref{a65,,None}, @ref{2519,,Ellipsis} and @ref{fba,,StopIteration}.

@item 
@ref{1b,,code} objects, if `allow_code' is true. See note above about
version dependence.
@end itemize


Άλλαξε στην έκδοση 3.4: 


@itemize *

@item 
Added format version 3, which supports marshalling recursive lists, sets
and dictionaries.

@item 
Added format version 4, which supports efficient representations
of short strings.
@end itemize



Άλλαξε στην έκδοση 3.14: Added format version 5, which allows marshalling slices.



Άλλαξε στην έκδοση 3.15: Added format version 6, which allows marshalling @ref{182,,frozendict}.


The module defines these functions:

@geindex dump() (στη μονάδα marshal)
@anchor{library/marshal marshal dump}@anchor{2f6a}
@deffn {Συνάρτηση} marshal.dump (value, file, version=version, /, *, allow_code=True)

Write the value on the open file.  The value must be a supported type.  The
file must be a writeable @ref{225d,,binary file}.

If the value has (or contains an object that has) an unsupported type, a
@ref{277,,ValueError} exception is raised — but garbage data will also be written
to the file.  The object will not be properly read back by @ref{1fe5,,load()}.
@ref{6eb,,Code objects} are only supported if `allow_code' is true.

The `version' argument indicates the data format that @code{dump} should use
(see below).

Raises an @ref{1e65,,auditing event} @code{marshal.dumps} with arguments @code{value}, @code{version}.


Άλλαξε στην έκδοση 3.13: Added the `allow_code' parameter.

@end deffn

@geindex load() (στη μονάδα marshal)
@anchor{library/marshal marshal load}@anchor{1fe5}
@deffn {Συνάρτηση} 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{167e,,EOFError}, @ref{277,,ValueError} or @ref{291,,TypeError}.
@ref{6eb,,Code objects} are only supported if `allow_code' is true.
The file must be a readable @ref{225d,,binary file}.

Raises an @ref{1e65,,auditing event} @code{marshal.load} with no arguments.

@cartouche
@quotation Σημείωση 
If an object containing an unsupported type was marshalled with @ref{2f6a,,dump()},
@code{load()} will substitute @code{None} for the unmarshallable type.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.13: Added the `allow_code' parameter.

@end deffn

@geindex dumps() (στη μονάδα marshal)
@anchor{library/marshal marshal dumps}@anchor{1256}
@deffn {Συνάρτηση} 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{277,,ValueError} exception if value
has (or contains an object that has) an unsupported type.
@ref{6eb,,Code objects} are only supported if `allow_code' is true.

The `version' argument indicates the data format that @code{dumps} should use
(see below).

Raises an @ref{1e65,,auditing event} @code{marshal.dumps} with arguments @code{value}, @code{version}.


Άλλαξε στην έκδοση 3.13: Added the `allow_code' parameter.

@end deffn

@geindex loads() (στη μονάδα marshal)
@anchor{library/marshal marshal loads}@anchor{2f6b}
@deffn {Συνάρτηση} marshal.loads (bytes, /, *, allow_code=True)

Convert the @ref{436,,bytes-like object} to a value.  If no valid value is found, raise
@ref{167e,,EOFError}, @ref{277,,ValueError} or @ref{291,,TypeError}.
@ref{6eb,,Code objects} are only supported if `allow_code' is true.
Extra bytes in the input are ignored.

Raises an @ref{1e65,,auditing event} @code{marshal.loads} with argument @code{bytes}.


Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.13: Added the `allow_code' parameter.

@end deffn

In addition, the following constants are defined:

@geindex version (στη μονάδα marshal)
@anchor{library/marshal marshal version}@anchor{2f69}
@deffn {Δεδομένα} marshal.version

Indicates the format that the module uses.
Version 0 is the historical first version; subsequent versions
add new features.
Generally, a new version becomes the default when it is introduced.


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Version

@tab

Available since

@tab

New features

@item

1

@tab

Python 2.4

@tab

Sharing interned strings

@item

2

@tab

Python 2.5

@tab

Binary representation of floats

@item

3

@tab

Python 3.4

@tab

Support for object instancing and recursion

@item

4

@tab

Python 3.4

@tab

Efficient representation of short strings

@item

5

@tab

Python 3.14

@tab

Support for @ref{1d0,,slice} objects

@item

6

@tab

Python 3.15

@tab

Support for @ref{182,,frozendict} objects

@end multitable

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node dbm — Interfaces to Unix «databases»,sqlite3 — DB-API 2 0 interface for SQLite databases,marshal — Internal Python object serialization,Data Persistence
@anchor{library/dbm doc}@anchor{2f6c}@anchor{library/dbm dbm-interfaces-to-unix-databases}@anchor{2f6d}@anchor{library/dbm module-dbm}@anchor{34}@anchor{library/dbm translation-repo}@anchor{2f6e}
@subsection @code{dbm} — Interfaces to Unix «databases»


@geindex module; dbm

`Source code:' Lib/dbm/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/dbm/__init__.py}


__________________________________________________________________


@code{dbm} is a generic interface to variants of the DBM database:


@itemize *

@item 
@ref{38,,dbm.sqlite3}

@item 
@ref{36,,dbm.gnu}

@item 
@ref{37,,dbm.ndbm}
@end itemize

If none of these modules are installed, the
slow-but-simple implementation in module @ref{35,,dbm.dumb} will be used. There
is a third party interface@footnote{https://www.jcea.es/programacion/pybsddb.htm} to
the Oracle Berkeley DB.

@cartouche
@quotation Σημείωση 
None of the underlying modules will automatically shrink the disk space used by
the database file. However, @ref{38,,dbm.sqlite3}, @ref{36,,dbm.gnu} and @ref{35,,dbm.dumb}
provide a @code{reorganize()} method that can be used for this purpose.
@end quotation
@end cartouche

@geindex error
@anchor{library/dbm dbm error}@anchor{2f6f}
@deffn {Εξαίρεση} dbm.error

A tuple containing the exceptions that can be raised by each of the supported
modules, with a unique exception also named @ref{2f6f,,dbm.error} as the first
item — the latter is used when @code{dbm.error} is raised.
@end deffn

@geindex whichdb() (στη μονάδα dbm)
@anchor{library/dbm dbm whichdb}@anchor{2f70}
@deffn {Συνάρτηση} dbm.whichdb (filename)

This function attempts to guess which of the several simple database modules
available — @ref{38,,dbm.sqlite3}, @ref{36,,dbm.gnu}, @ref{37,,dbm.ndbm},
or @ref{35,,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


Άλλαξε στην έκδοση 3.11: `filename' accepts a @ref{79f,,path-like object}.

@end deffn

@c Substitutions for the open() flag param docs;
@c all submodules use the same text.

@geindex open() (στη μονάδα dbm)
@anchor{library/dbm dbm open}@anchor{12d7}
@deffn {Συνάρτηση} dbm.open (file, flag='r', mode=0o666)

Open a database and return the corresponding database object.

@*Παράμετροι: 

@itemize *

@item 
@code{file} (@ref{79f,,path-like object}) – 
The database file to open.

If the database file already exists, the @ref{2f70,,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{1df,,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{326,,int}) – The Unix file access mode of the file (default: octal @code{0o666}),
used only when the database has to be created.
@end itemize



Άλλαξε στην έκδοση 3.11: `file' accepts a @ref{79f,,path-like object}.

@end deffn

The object returned by @ref{12d7,,open()} supports the basic
functionality of mutable @ref{1564,,mappings};
keys and their corresponding values can be stored, retrieved, and
deleted, and iteration, the @ref{323,,in} operator and methods @code{keys()},
@code{get()}, @code{setdefault()} and @code{clear()} are available.
The @code{keys()} method returns a list instead of a view object.
The @code{setdefault()} method requires two arguments.

Key and values are always stored as @ref{1c7,,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{20a,,with} statement, which
will automatically close them when done.


Άλλαξε στην έκδοση 3.2: @code{get()} and @code{setdefault()} methods are now available for all
@code{dbm} backends.



Άλλαξε στην έκδοση 3.4: Added native support for the context management protocol to the objects
returned by @ref{12d7,,open()}.



Άλλαξε στην έκδοση 3.8: Deleting a key from a read-only database raises a database module specific exception
instead of @ref{7df,,KeyError}.



Άλλαξε στην έκδοση 3.13: @code{clear()} methods are now available for all @code{dbm} backends.


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 Δείτε επίσης



@table @asis

@item Module @ref{cb,,shelve}

Persistence module which stores non-string data.
@end table


The individual submodules are described in the following sections.

@menu
* dbm.sqlite3 — SQLite backend for dbm: dbm sqlite3 — SQLite backend for dbm. 
* dbm.gnu — GNU database manager: dbm gnu — GNU database manager. 
* dbm.ndbm — New Database Manager: dbm ndbm — New Database Manager. 
* dbm.dumb — Portable DBM implementation: dbm dumb — 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{2f71}@anchor{library/dbm module-dbm sqlite3}@anchor{38}
@subsubsection @code{dbm.sqlite3} — SQLite backend for dbm


@geindex module; dbm.sqlite3


Added in version 3.13.


`Source code:' Lib/dbm/sqlite3.py@footnote{https://github.com/python/cpython/tree/main/Lib/dbm/sqlite3.py}


__________________________________________________________________


This module uses the standard library @ref{d7,,sqlite3} module to provide an
SQLite backend for the @code{dbm} module.
The files created by @code{dbm.sqlite3} can thus be opened by @code{sqlite3},
or any other SQLite browser, including the SQLite CLI.

@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

@geindex open() (στη μονάδα dbm.sqlite3)
@anchor{library/dbm dbm sqlite3 open}@anchor{2f72}
@deffn {Συνάρτηση} dbm.sqlite3.open (filename, /, flag='r', mode=0o666)

Open an SQLite database.

@*Παράμετροι: 

@itemize *

@item 
@code{filename} (@ref{79f,,path-like object}) – The path to the database to be opened.

@item 
@code{flag} (@ref{1df,,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


The returned database object behaves similar to a mutable @ref{1564,,mapping},
but the @code{keys()} method returns a list, and
the @code{setdefault()} method requires two arguments.
It also supports a «closing» context manager via the @ref{20a,,with} keyword.

The following methods are also provided:

@geindex close() (μέθοδος της dbm.sqlite3.sqlite3)
@anchor{library/dbm dbm sqlite3 sqlite3 close}@anchor{2f73}
@deffn {Μέθοδος} sqlite3.close ()

Close the SQLite database.
@end deffn

@geindex reorganize() (μέθοδος της dbm.sqlite3.sqlite3)
@anchor{library/dbm dbm sqlite3 sqlite3 reorganize}@anchor{2f74}
@deffn {Μέθοδος} sqlite3.reorganize ()

If you have carried out a lot of deletions and would like to shrink the space
used on disk, this method will reorganize the database; otherwise, deleted file
space will be kept and reused as new (key, value) pairs are added.

@cartouche
@quotation Σημείωση 
While reorganizing, as much as two times the size of the original database is required
in free disk space. However, be aware that this factor changes for each @code{dbm} submodule.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn
@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{2f75}@anchor{library/dbm module-dbm gnu}@anchor{36}
@subsubsection @code{dbm.gnu} — GNU database manager


@geindex module; dbm.gnu

`Source code:' Lib/dbm/gnu.py@footnote{https://github.com/python/cpython/tree/main/Lib/dbm/gnu.py}


__________________________________________________________________


The @code{dbm.gnu} module provides an interface to the @abbr{GDBM,GNU dbm}
library, similar to the @ref{37,,dbm.ndbm} module, but with additional
functionality like crash tolerance.

@cartouche
@quotation Σημείωση 
The file formats created by @code{dbm.gnu} and @ref{37,,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{232d,,Διαθεσιμότητα}: not Android, not iOS, not WASI.

This module is not supported on @ref{244d,,mobile platforms}
or @ref{1d67,,WebAssembly platforms}.

@ref{232d,,Διαθεσιμότητα}: Unix.

@geindex error
@anchor{library/dbm dbm gnu error}@anchor{e60}
@deffn {Εξαίρεση} dbm.gnu.error

Raised on @code{dbm.gnu}-specific errors, such as I/O errors. @ref{7df,,KeyError} is
raised for general mapping errors like specifying an incorrect key.
@end deffn

@geindex open_flags (στη μονάδα dbm.gnu)
@anchor{library/dbm dbm gnu open_flags}@anchor{2f76}
@deffn {Δεδομένα} dbm.gnu.open_flags

A string of characters the `flag' parameter of @ref{200e,,open()} supports.
@end deffn

@geindex open() (στη μονάδα dbm.gnu)
@anchor{library/dbm dbm gnu open}@anchor{200e}
@deffn {Συνάρτηση} dbm.gnu.open (filename, flag='r', mode=0o666, /)

Open a GDBM database and return a @code{gdbm} object.

@*Παράμετροι: 

@itemize *

@item 
@code{filename} (@ref{79f,,path-like object}) – The database file to open.

@item 
@code{flag} (@ref{1df,,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{2f76,,open_flags} member for a list of supported flag characters.


@item 
@code{mode} (@ref{326,,int}) – The Unix file access mode of the file (default: octal @code{0o666}),
used only when the database has to be created.
@end itemize


@*Προκαλεί: 
@ref{e60,,error} – If an invalid `flag' argument is passed.



Άλλαξε στην έκδοση 3.11: `filename' accepts a @ref{79f,,path-like object}.


@code{gdbm} objects behave similar to mutable @ref{1564,,mappings},
but methods @code{items()}, @code{values()}, @code{pop()}, @code{popitem()},
and @code{update()} are not supported,
the @code{keys()} method returns a list, and
the @code{setdefault()} method requires two arguments.
It also supports a «closing» context manager via the @ref{20a,,with} keyword.


Άλλαξε στην έκδοση 3.2: Added the @code{get()} and @code{setdefault()} methods.



Άλλαξε στην έκδοση 3.13: Added the @code{clear()} method.


The following methods are also provided:

@geindex close() (μέθοδος της dbm.gnu.gdbm)
@anchor{library/dbm dbm gnu gdbm close}@anchor{2f77}
@deffn {Μέθοδος} gdbm.close ()

Close the GDBM database.
@end deffn

@geindex firstkey() (μέθοδος της dbm.gnu.gdbm)
@anchor{library/dbm dbm gnu gdbm firstkey}@anchor{2f78}
@deffn {Μέθοδος} gdbm.firstkey ()

It’s possible to loop over every key in the database using this method  and the
@ref{2f79,,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() (μέθοδος της dbm.gnu.gdbm)
@anchor{library/dbm dbm gnu gdbm nextkey}@anchor{2f79}
@deffn {Μέθοδος} 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() (μέθοδος της dbm.gnu.gdbm)
@anchor{library/dbm dbm gnu gdbm reorganize}@anchor{2f7a}
@deffn {Μέθοδος} 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.

@cartouche
@quotation Σημείωση 
While reorganizing, as much as one time the size of the original database is required
in free disk space. However, be aware that this factor changes for each @code{dbm} submodule.
@end quotation
@end cartouche
@end deffn

@geindex sync() (μέθοδος της dbm.gnu.gdbm)
@anchor{library/dbm dbm gnu gdbm sync}@anchor{2f7b}
@deffn {Μέθοδος} 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
@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{2f7c}@anchor{library/dbm module-dbm ndbm}@anchor{37}
@subsubsection @code{dbm.ndbm} — New Database Manager


@geindex module; dbm.ndbm

`Source code:' Lib/dbm/ndbm.py@footnote{https://github.com/python/cpython/tree/main/Lib/dbm/ndbm.py}


__________________________________________________________________


The @code{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 Σημείωση 
The file formats created by @ref{36,,dbm.gnu} and @code{dbm.ndbm} are incompatible
and can not be used interchangeably.
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
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{232d,,Διαθεσιμότητα}: not Android, not iOS, not WASI.

This module is not supported on @ref{244d,,mobile platforms}
or @ref{1d67,,WebAssembly platforms}.

@ref{232d,,Διαθεσιμότητα}: Unix.

@geindex error
@anchor{library/dbm dbm ndbm error}@anchor{e61}
@deffn {Εξαίρεση} dbm.ndbm.error

Raised on @code{dbm.ndbm}-specific errors, such as I/O errors. @ref{7df,,KeyError} is raised
for general mapping errors like specifying an incorrect key.
@end deffn

@geindex library (στη μονάδα dbm.ndbm)
@anchor{library/dbm dbm ndbm library}@anchor{2f7d}
@deffn {Δεδομένα} dbm.ndbm.library

Name of the NDBM implementation library used.
@end deffn

@geindex open() (στη μονάδα dbm.ndbm)
@anchor{library/dbm dbm ndbm open}@anchor{200f}
@deffn {Συνάρτηση} dbm.ndbm.open (filename, flag='r', mode=0o666, /)

Open an NDBM database and return an @code{ndbm} object.

@*Παράμετροι: 

@itemize *

@item 
@code{filename} (@ref{79f,,path-like object}) – The basename of the database file
(without the @code{.dir} or @code{.pag} extensions).

@item 
@code{flag} (@ref{1df,,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{326,,int}) – The Unix file access mode of the file (default: octal @code{0o666}),
used only when the database has to be created.
@end itemize



Άλλαξε στην έκδοση 3.11: Accepts @ref{79f,,path-like object} for filename.


@code{ndbm} objects behave similar to mutable @ref{1564,,mappings},
but methods @code{items()}, @code{values()}, @code{pop()}, @code{popitem()},
and @code{update()} are not supported,
the @code{keys()} method returns a list, and
the @code{setdefault()} method requires two arguments.
It also supports a «closing» context manager via the @ref{20a,,with} keyword.


Άλλαξε στην έκδοση 3.2: Added the @code{get()} and @code{setdefault()} methods.



Άλλαξε στην έκδοση 3.13: Added the @code{clear()} method.


The following method is also provided:

@geindex close() (μέθοδος της dbm.ndbm.ndbm)
@anchor{library/dbm dbm ndbm ndbm close}@anchor{2f7e}
@deffn {Μέθοδος} ndbm.close ()

Close the NDBM database.
@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{2f7f}@anchor{library/dbm module-dbm dumb}@anchor{35}
@subsubsection @code{dbm.dumb} — Portable DBM implementation


@geindex module; dbm.dumb

`Source code:' Lib/dbm/dumb.py@footnote{https://github.com/python/cpython/tree/main/Lib/dbm/dumb.py}

@geindex databases

@cartouche
@quotation Σημείωση 
The @code{dbm.dumb} module is intended as a last resort fallback for the
@code{dbm} module when a more robust module is not available. The @code{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 @code{dbm.dumb} module provides a persistent @ref{188,,dict}-like
interface which is written entirely in Python.
Unlike other @code{dbm} backends, such as @ref{36,,dbm.gnu}, no
external library is required.

The @code{dbm.dumb} module defines the following:

@geindex error
@anchor{library/dbm dbm dumb error}@anchor{e5f}
@deffn {Εξαίρεση} dbm.dumb.error

Raised on @code{dbm.dumb}-specific errors, such as I/O errors.  @ref{7df,,KeyError} is
raised for general mapping errors like specifying an incorrect key.
@end deffn

@geindex open() (στη μονάδα dbm.dumb)
@anchor{library/dbm dbm dumb open}@anchor{e5c}
@deffn {Συνάρτηση} dbm.dumb.open (filename, flag='c', mode=0o666)

Open a @code{dbm.dumb} database.

@*Παράμετροι: 

@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{1df,,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{326,,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 Προειδοποίηση 
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

@cartouche
@quotation Προειδοποίηση 
@code{dbm.dumb} does not support concurrent read/write access. (Multiple
simultaneous read accesses are safe.) When a program has the database open
for writing, no other program should have it open for reading or writing.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.5: @ref{e5c,,open()} always creates a new database when `flag' is @code{'n'}.



Άλλαξε στην έκδοση 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'}.



Άλλαξε στην έκδοση 3.11: `filename' accepts a @ref{79f,,path-like object}.


The returned database object behaves similar to a mutable @ref{1564,,mapping},
but the @code{keys()} and @code{items()} methods return lists, and
the @code{setdefault()} method requires two arguments.
It also supports a «closing» context manager via the @ref{20a,,with} keyword.

The following methods are also provided:

@geindex close() (μέθοδος της dbm.dumb.dumbdbm)
@anchor{library/dbm dbm dumb dumbdbm close}@anchor{2f80}
@deffn {Μέθοδος} dumbdbm.close ()

Close the database.
@end deffn

@geindex reorganize() (μέθοδος της dbm.dumb.dumbdbm)
@anchor{library/dbm dbm dumb dumbdbm reorganize}@anchor{2f81}
@deffn {Μέθοδος} dumbdbm.reorganize ()

If you have carried out a lot of deletions and would like to shrink the space
used on disk, this method will reorganize the database; otherwise, deleted file
space will not be reused.

@cartouche
@quotation Σημείωση 
While reorganizing, no additional free disk space is required. However, be aware
that this factor changes for each @code{dbm} submodule.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn

@geindex sync() (μέθοδος της dbm.dumb.dumbdbm)
@anchor{library/dbm dbm dumb dumbdbm sync}@anchor{2f82}
@deffn {Μέθοδος} dumbdbm.sync ()

Synchronize the on-disk directory and data files.  This method is called
by the @ref{2f5e,,shelve.Shelf.sync()} method.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node sqlite3 — DB-API 2 0 interface for SQLite databases,,dbm — Interfaces to Unix «databases»,Data Persistence
@anchor{library/sqlite3 doc}@anchor{2f83}@anchor{library/sqlite3 module-sqlite3}@anchor{d7}@anchor{library/sqlite3 sqlite3-db-api-2-0-interface-for-sqlite-databases}@anchor{2f84}@anchor{library/sqlite3 translation-repo}@anchor{2f85}
@subsection @code{sqlite3} — DB-API 2.0 interface for SQLite databases


@geindex module; sqlite3

`Source code:' Lib/sqlite3/@footnote{https://github.com/python/cpython/tree/main/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{2f86}
SQLite is a C library that provides a lightweight disk-based database that
doesn’t require a separate server process and allows accessing the database
using a nonstandard variant of the SQL query language. Some applications can use
SQLite for internal data storage.  It’s also possible to prototype an
application using SQLite and then port the code to a larger database such as
PostgreSQL or 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 the third-party SQLite@footnote{https://sqlite.org/} library.

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile

This document includes four main sections:


@itemize *

@item 
@ref{2f87,,Tutorial} teaches how to use the @code{sqlite3} module.

@item 
@ref{2f88,,Reference} describes the classes and functions this module
defines.

@item 
@ref{2f89,,How-to guides} details how to handle specific tasks.

@item 
@ref{2f8a,,Explanation} provides in-depth background on
transaction control.
@end itemize


@subsubheading Δείτε επίσης



@table @asis

@item @indicateurl{https://www.sqlite.org}

The SQLite web page; the documentation describes the syntax and the
available data types for the supported SQL dialect.

@item @indicateurl{https://www.w3schools.com/sql/}

Tutorial, reference and examples for learning SQL syntax.

@geindex Python Enhancement Proposals; PEP 249

@item PEP 249@footnote{https://peps.python.org/pep-0249/} - Database API Specification 2.0

PEP written by Marc-André Lemburg.
@end table


@c We use the following practices 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
* Tutorial:: 
* Reference:: 
* How-to guides:: 
* Explanation:: 

@end menu

@node Tutorial,Reference,,sqlite3 — DB-API 2 0 interface for SQLite databases
@anchor{library/sqlite3 sqlite3-tutorial}@anchor{2f87}@anchor{library/sqlite3 tutorial}@anchor{2f8b}
@subsubsection Tutorial


In this tutorial, you will create a database of Monty Python movies
using basic @code{sqlite3} functionality.
It assumes a fundamental understanding of database concepts,
including cursors@footnote{https://en.wikipedia.org/wiki/Cursor_(databases)} and transactions@footnote{https://en.wikipedia.org/wiki/Database_transaction}.

First, we need to create a new database and open
a database connection to allow @code{sqlite3} to work with it.
Call @ref{3e0,,sqlite3.connect()} to create a connection to
the database @code{tutorial.db} in the current working directory,
implicitly creating it if it does not exist:

@example
import sqlite3
con = sqlite3.connect("tutorial.db")
@end example

The returned @ref{3df,,Connection} object @code{con}
represents the connection to the on-disk database.

In order to execute SQL statements and fetch results from SQL queries,
we will need to use a database cursor.
Call @ref{2f8c,,con.cursor()} to create the @ref{2f8d,,Cursor}:

@example
cur = con.cursor()
@end example

Now that we’ve got a database connection and a cursor,
we can create a database table @code{movie} with columns for title,
release year, and review score.
For simplicity, we can just use column names in the table declaration –
thanks to the flexible typing@footnote{https://www.sqlite.org/flextypegood.html} feature of SQLite,
specifying the data types is optional.
Execute the @code{CREATE TABLE} statement
by calling @ref{7a8,,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.

We can verify that the new table has been created by querying
the @code{sqlite_master} table built-in to SQLite,
which should now contain an entry for the @code{movie} table definition
(see The Schema Table@footnote{https://www.sqlite.org/schematab.html} for details).
Execute that query by calling @ref{7a8,,cur.execute(...)},
assign the result to @code{res},
and call @ref{2f8e,,res.fetchone()} to fetch the resulting row:

@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{1ce,,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

Now, add two rows of data supplied as SQL literals
by executing an @code{INSERT} statement,
once again by calling @ref{7a8,,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

The @code{INSERT} statement implicitly opens a transaction,
which needs to be committed before changes are saved in the database
(see @ref{2f8f,,Transaction control} for details).
Call @ref{2f90,,con.commit()} on the connection object
to commit the transaction:

@example
con.commit()
@end example

We can verify that the data was inserted correctly
by executing a @code{SELECT} query.
Use the now-familiar @ref{7a8,,cur.execute(...)} to
assign the result to @code{res},
and call @ref{2f91,,res.fetchall()} to return all resulting rows:

@example
>>> res = cur.execute("SELECT score FROM movie")
>>> res.fetchall()
[(8.2,), (7.5,)]
@end example

The result is a @ref{4d9,,list} of two @code{tuple}s, one per row,
each containing that row’s @code{score} value.

Now, insert three more rows by calling
@ref{7a9,,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

Notice that @code{?} placeholders are used to bind @code{data} to the query.
Always use placeholders instead of @ref{2249,,string formatting}
to bind Python values to SQL statements,
to avoid SQL injection attacks@footnote{https://en.wikipedia.org/wiki/SQL_injection}
(see @ref{7aa,,How to use placeholders to bind values in SQL queries} for more details).

We can verify that the new rows were inserted
by executing a @code{SELECT} query,
this time iterating over the results of the query:

@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

Each row is a two-item @ref{1ce,,tuple} of @code{(year, title)},
matching the columns selected in the query.

Finally, verify that the database has been written to disk
by calling @ref{750,,con.close()}
to close the existing connection, opening a new one,
creating a new cursor, then querying the database:

@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

You’ve now created an SQLite database using the @code{sqlite3} module,
inserted data and retrieved values from it in multiple ways.


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{2f89,,How-to guides} for further reading:


@itemize *

@item 
@ref{7aa,,How to use placeholders to bind values in SQL queries}

@item 
@ref{2f92,,How to adapt custom Python types to SQLite values}

@item 
@ref{2f93,,How to convert SQLite values to custom Python types}

@item 
@ref{1d69,,How to use the connection context manager}

@item 
@ref{2f94,,How to create and use row factories}
@end itemize

@item 
@ref{2f8a,,Explanation} for in-depth background on transaction control.
@end itemize


@node Reference,How-to guides,Tutorial,sqlite3 — DB-API 2 0 interface for SQLite databases
@anchor{library/sqlite3 reference}@anchor{2f95}@anchor{library/sqlite3 sqlite3-reference}@anchor{2f88}
@subsubsection Reference


@c We keep the old sqlite3-module-contents ref to prevent breaking links.
@anchor{library/sqlite3 sqlite3-module-contents}@anchor{2f96}
@menu
* Module functions:: 
* Module constants:: 
* Connection objects:: 
* Cursor objects:: 
* Row objects:: 
* Blob objects:: 
* PrepareProtocol objects:: 
* Exceptions: Exceptions<6>. 
* SQLite and Python types:: 
* Default adapters and converters (deprecated): Default adapters and converters deprecated. 
* Command-line interface: Command-line interface<2>. 

@end menu

@node Module functions,Module constants,,Reference
@anchor{library/sqlite3 module-functions}@anchor{2f97}@anchor{library/sqlite3 sqlite3-module-functions}@anchor{2f98}
@subsubsection Module functions


@geindex connect() (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 connect}@anchor{3e0}
@deffn {Συνάρτηση} 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)

Open a connection to an SQLite database.

@*Παράμετροι: 

@itemize *

@item 
@code{database} (@ref{79f,,path-like object}) – The path to the database file to be opened.
You can pass @code{":memory:"} to create an SQLite database existing only in memory@footnote{https://sqlite.org/inmemorydb.html}, and open a connection
to it.

@item 
@code{timeout} (@ref{327,,float}) – How many seconds the connection should wait before raising
an @ref{1e49,,OperationalError} when a table is locked.
If another connection opens a transaction to modify a table,
that table will be locked until the transaction is committed.
Default five seconds.

@item 
@code{detect_types} (@ref{326,,int}) – Control whether and how data types not
@ref{2f99,,natively supported by SQLite}
are looked up to be converted to Python types,
using the converters registered with @ref{2f9a,,register_converter()}.
Set it to any combination (using @code{|}, bitwise or) of
@ref{2f9b,,PARSE_DECLTYPES} and @ref{2f9c,,PARSE_COLNAMES}
to enable this.
Column names take precedence over declared types if both flags are set.
By default (@code{0}), type detection is disabled.

@item 
@code{isolation_level} (@ref{1df,,str}@code{ | }@code{None}) – Control legacy transaction handling behaviour.
See @ref{2f9d,,Connection.isolation_level} and
@ref{2f9e,,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{8c6,,Connection.autocommit} is set to
@ref{2f9f,,LEGACY_TRANSACTION_CONTROL} (the default).

@item 
@code{check_same_thread} (@ref{5ef,,bool}) – If @code{True} (default), @ref{57d,,ProgrammingError} will be raised
if the database connection is used by a thread
other than the one that created it.
If @code{False}, the connection may be accessed in multiple threads;
write operations may need to be serialized by the user
to avoid data corruption.
See @ref{a6c,,threadsafety} for more information.

@item 
@code{factory} (@ref{3df,,Connection}) – A custom subclass of @ref{3df,,Connection} to create the connection with,
if not the default @code{Connection} class.

@item 
@code{cached_statements} (@ref{326,,int}) – The number of statements that @code{sqlite3}
should internally cache for this connection, to avoid parsing overhead.
By default, 128 statements.

@item 
@code{uri} (@ref{5ef,,bool}) – If set to @code{True}, `database' is interpreted as a
@abbr{URI,Uniform Resource Identifier} with a file path
and an optional query string.
The scheme part `must' be @code{"file:"},
and the path can be relative or absolute.
The query string allows passing parameters to SQLite,
enabling various @ref{2fa0,,How to work with SQLite URIs}.

@item 
@code{autocommit} (@ref{5ef,,bool}) – Control 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/} transaction handling behaviour.
See @ref{8c6,,Connection.autocommit} and
@ref{8c7,,Transaction control via the autocommit attribute} for more information.
`autocommit' currently defaults to
@ref{2f9f,,LEGACY_TRANSACTION_CONTROL}.
The default will change to @code{False} in a future Python release.
@end itemize


@*Επιστρεφόμενος τύπος: 
@ref{3df,,Connection}


Raises an @ref{1e65,,auditing event} @code{sqlite3.connect} with argument @code{database}.

Raises an @ref{1e65,,auditing event} @code{sqlite3.connect/handle} with argument @code{connection_handle}.


Άλλαξε στην έκδοση 3.4: Added the `uri' parameter.



Άλλαξε στην έκδοση 3.7: `database' can now also be a @ref{79f,,path-like object}, not only a string.



Άλλαξε στην έκδοση 3.10: Added the @code{sqlite3.connect/handle} auditing event.



Άλλαξε στην έκδοση 3.12: Added the `autocommit' parameter.



Άλλαξε στην έκδοση 3.15: All parameters except `database' are now keyword-only.

@end deffn

@geindex complete_statement() (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 complete_statement}@anchor{2fa1}
@deffn {Συνάρτηση} sqlite3.complete_statement (statement)

Return @code{True} if the string `statement' appears to contain
one or more complete SQL statements.
No syntactic verification or parsing of any kind is performed,
other than checking that there are no unclosed string literals
and the statement is terminated by a semicolon.

For example:

@example
>>> sqlite3.complete_statement("SELECT foo FROM bar;")
True
>>> sqlite3.complete_statement("SELECT foo")
False
@end example

This function may be useful during command-line input
to determine if the entered text seems to form a complete SQL statement,
or if additional input is needed before calling @ref{7a8,,execute()}.

See @code{runsource()} in Lib/sqlite3/__main__.py@footnote{https://github.com/python/cpython/tree/main/Lib/sqlite3/__main__.py}
for real-world use.
@end deffn

@geindex enable_callback_tracebacks() (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 enable_callback_tracebacks}@anchor{2fa2}
@deffn {Συνάρτηση} sqlite3.enable_callback_tracebacks (flag, /)

Enable or disable callback tracebacks.
By default you will not get any tracebacks in user-defined functions,
aggregates, converters, authorizer callbacks etc. If you want to debug them,
you can call this function with `flag' set to @code{True}. Afterwards, you
will get tracebacks from callbacks on @ref{d05,,sys.stderr}. Use @code{False}
to disable the feature again.

@cartouche
@quotation Σημείωση 
Errors in user-defined function callbacks are logged as unraisable exceptions.
Use an @ref{70c,,unraisable hook handler} for
introspection of the failed callback.
@end quotation
@end cartouche
@end deffn

@geindex register_adapter() (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 register_adapter}@anchor{2fa3}
@deffn {Συνάρτηση} sqlite3.register_adapter (type, adapter, /)

Register an `adapter' @ref{2fa4,,callable} to adapt the Python type `type'
into an SQLite type.
The adapter is called with a Python object of type `type' as its sole
argument, and must return a value of a
@ref{2f99,,type that SQLite natively understands}.
@end deffn

@geindex register_converter() (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 register_converter}@anchor{2f9a}
@deffn {Συνάρτηση} sqlite3.register_converter (typename, converter, /)

Register the `converter' @ref{2fa4,,callable} to convert SQLite objects of type
`typename' into a Python object of a specific type.
The converter is invoked for all SQLite values of type `typename';
it is passed a @ref{1c7,,bytes} object and should return an object of the
desired Python type.
Consult the parameter `detect_types' of
@ref{3e0,,connect()} for information regarding how type detection works.

Note: `typename' and the name of the type in your query are matched
case-insensitively.
@end deffn

@node Module constants,Connection objects,Module functions,Reference
@anchor{library/sqlite3 module-constants}@anchor{2fa5}@anchor{library/sqlite3 sqlite3-module-constants}@anchor{2fa6}
@subsubsection Module constants


@geindex LEGACY_TRANSACTION_CONTROL (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 LEGACY_TRANSACTION_CONTROL}@anchor{2f9f}
@deffn {Δεδομένα} sqlite3.LEGACY_TRANSACTION_CONTROL

Set @ref{8c6,,autocommit} to this constant to select
old style (pre-Python 3.12) transaction control behaviour.
See @ref{2f9e,,Transaction control via the isolation_level attribute} for more information.
@end deffn

@geindex PARSE_DECLTYPES (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 PARSE_DECLTYPES}@anchor{2f9b}
@deffn {Δεδομένα} sqlite3.PARSE_DECLTYPES

Pass this flag value to the `detect_types' parameter of
@ref{3e0,,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{2f9c,,PARSE_COLNAMES} using the @code{|}
(bitwise or) operator.

@cartouche
@quotation Σημείωση 
Generated fields (for example @code{MAX(p)}) are returned as @ref{1df,,str}.
Use @code{PARSE_COLNAMES} to enforce types for such queries.
@end quotation
@end cartouche
@end deffn

@geindex PARSE_COLNAMES (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 PARSE_COLNAMES}@anchor{2f9c}
@deffn {Δεδομένα} sqlite3.PARSE_COLNAMES

Pass this flag value to the `detect_types' parameter of
@ref{3e0,,connect()} to look up a converter function by
using the type name, parsed from the query column name,
as the converter dictionary key.
The query column name must be wrapped in double quotes (@code{"})
and the type name must be wrapped in square brackets (@code{[]}).

@example
SELECT MAX(p) as "p [point]" FROM test;  ! will look up converter "point"
@end example

This flag may be combined with @ref{2f9b,,PARSE_DECLTYPES} using the @code{|}
(bitwise or) operator.
@end deffn

@geindex SQLITE_OK (στη μονάδα sqlite3)
@geindex SQLITE_DENY (στη μονάδα sqlite3)
@geindex SQLITE_IGNORE (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 SQLITE_OK}@anchor{2fa7}
@deffn {Δεδομένα} sqlite3.SQLITE_OK
@anchor{library/sqlite3 sqlite3 SQLITE_DENY}@anchor{2fa8}
@deffnx {Δεδομένα} sqlite3.SQLITE_DENY
@anchor{library/sqlite3 sqlite3 SQLITE_IGNORE}@anchor{2fa9}
@deffnx {Δεδομένα} sqlite3.SQLITE_IGNORE

Flags that should be returned by the `authorizer_callback' @ref{2fa4,,callable}
passed to @ref{3e3,,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 (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 apilevel}@anchor{2faa}
@deffn {Δεδομένα} 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 (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 paramstyle}@anchor{2fab}
@deffn {Δεδομένα} 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 Σημείωση 
The @code{named} DB-API parameter style is also supported.
@end quotation
@end cartouche
@end deffn

@geindex sqlite_version (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 sqlite_version}@anchor{57b}
@deffn {Δεδομένα} sqlite3.sqlite_version

Version number of the runtime SQLite library as a @ref{1df,,string}.
@end deffn

@geindex sqlite_version_info (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 sqlite_version_info}@anchor{57c}
@deffn {Δεδομένα} sqlite3.sqlite_version_info

Version number of the runtime SQLite library as a @ref{1ce,,tuple} of
@ref{326,,integers}.
@end deffn

@geindex SQLITE_KEYWORDS (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 SQLITE_KEYWORDS}@anchor{1a37}
@deffn {Δεδομένα} sqlite3.SQLITE_KEYWORDS

A @ref{1ce,,tuple} containing all SQLite keywords.

This constant is only available if Python was compiled with SQLite
3.24.0 or greater.


Added in version 3.15.

@end deffn

@geindex threadsafety (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3 threadsafety}@anchor{a6c}
@deffn {Δεδομένα} 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



Άλλαξε στην έκδοση 3.11: Set `threadsafety' dynamically instead of hard-coding it to @code{1}.

@end deffn

@geindex SQLITE_DBCONFIG_DEFENSIVE (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_DQS_DDL (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_DQS_DML (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_ENABLE_FKEY (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_ENABLE_QPSG (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_ENABLE_TRIGGER (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_ENABLE_VIEW (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_LEGACY_ALTER_TABLE (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_LEGACY_FILE_FORMAT (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_RESET_DATABASE (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_TRIGGER_EQP (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_TRUSTED_SCHEMA (στη μονάδα sqlite3)
@geindex SQLITE_DBCONFIG_WRITABLE_SCHEMA (στη μονάδα sqlite3)
@anchor{library/sqlite3 sqlite3-dbconfig-constants}@anchor{2fac}@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_DEFENSIVE}@anchor{2fad}
@deffn {Δεδομένα} sqlite3.SQLITE_DBCONFIG_DEFENSIVE
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_DQS_DDL}@anchor{2fae}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_DQS_DDL
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_DQS_DML}@anchor{2faf}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_DQS_DML
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_FKEY}@anchor{2fb0}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER}@anchor{2fb1}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION}@anchor{2fb2}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_QPSG}@anchor{2fb3}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_TRIGGER}@anchor{2fb4}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_VIEW}@anchor{2fb5}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_LEGACY_ALTER_TABLE}@anchor{2fb6}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_LEGACY_FILE_FORMAT}@anchor{2fb7}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE}@anchor{2fb8}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_RESET_DATABASE}@anchor{2fb9}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_RESET_DATABASE
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_TRIGGER_EQP}@anchor{2fba}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_TRUSTED_SCHEMA}@anchor{2fbb}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_WRITABLE_SCHEMA}@anchor{2fbc}
@deffnx {Δεδομένα} sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA

These constants are used for the @ref{8ca,,Connection.setconfig()}
and @ref{8c9,,getconfig()} methods.

The availability of these constants varies depending on the version of SQLite
Python was compiled with.


Added in version 3.12.



@subsubheading Δείτε επίσης



@table @asis

@item @indicateurl{https://www.sqlite.org/c3ref/c_dbconfig_defensive.html}

SQLite docs: Database Connection Configuration Options
@end table

@end deffn


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.14: The @code{version} and @code{version_info} constants.


@node Connection objects,Cursor objects,Module constants,Reference
@anchor{library/sqlite3 connection-objects}@anchor{2fbd}@anchor{library/sqlite3 sqlite3-connection-objects}@anchor{2fbe}
@subsubsection Connection objects


@geindex Connection (κλάση σε sqlite3)
@anchor{library/sqlite3 sqlite3 Connection}@anchor{3df}
@deffn {Κλάση} sqlite3.Connection

Each open SQLite database is represented by a @code{Connection} object,
which is created using @ref{3e0,,sqlite3.connect()}.
Their main purpose is creating @ref{2f8d,,Cursor} objects,
and @ref{2f8f,,Transaction control}.


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{2fbf,,How to use connection shortcut methods}

@item 
@ref{1d69,,How to use the connection context manager}
@end itemize



Άλλαξε στην έκδοση 3.13: A @ref{74f,,ResourceWarning} is emitted if @ref{750,,close()} is not called before
a @code{Connection} object is deleted.


An SQLite database connection has the following attributes and methods:

@geindex cursor() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection cursor}@anchor{2f8c}
@deffn {Μέθοδος} cursor (factory=Cursor)

Create and return a @ref{2f8d,,Cursor} object.
The cursor method accepts a single optional parameter `factory'. If
supplied, this must be a @ref{2fa4,,callable} returning
an instance of @code{Cursor} or its subclasses.
@end deffn

@geindex blobopen() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection blobopen}@anchor{a71}
@deffn {Μέθοδος} blobopen (table, column, rowid, /, *, readonly=False, name='main')

Open a @ref{a72,,Blob} handle to an existing
@abbr{BLOB,Binary Large OBject}.

@*Παράμετροι: 

@itemize *

@item 
@code{table} (@ref{1df,,str}) – The name of the table where the blob is located.

@item 
@code{column} (@ref{1df,,str}) – The name of the column where the blob is located.

@item 
@code{rowid} (@ref{326,,int}) – The row id where the blob is located.

@item 
@code{readonly} (@ref{5ef,,bool}) – Set to @code{True} if the blob should be opened without write
permissions.
Defaults to @code{False}.

@item 
@code{name} (@ref{1df,,str}) – The name of the database where the blob is located.
Defaults to @code{"main"}.
@end itemize


@*Προκαλεί: 
@ref{1e49,,OperationalError} – When trying to open a blob in a @code{WITHOUT ROWID} table.


@*Επιστρεφόμενος τύπος: 
@ref{a72,,Blob}


@cartouche
@quotation Σημείωση 
The blob size cannot be changed using the @ref{a72,,Blob} class.
Use the SQL function @code{zeroblob} to create a blob with a fixed size.
@end quotation
@end cartouche


Added in version 3.11.

@end deffn

@geindex commit() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection commit}@anchor{2f90}
@deffn {Μέθοδος} commit ()

Commit any pending transaction to the database.
If @ref{8c6,,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() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection rollback}@anchor{2fc0}
@deffn {Μέθοδος} rollback ()

Roll back to the start of any pending transaction.
If @ref{8c6,,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() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection close}@anchor{750}
@deffn {Μέθοδος} close ()

Close the database connection.
If @ref{8c6,,autocommit} is @code{False},
any pending transaction is implicitly rolled back.
If @code{autocommit} is @code{True} or @ref{2f9f,,LEGACY_TRANSACTION_CONTROL},
no implicit transaction control is executed.
Make sure to @ref{2f90,,commit()} before closing
to avoid losing pending changes.
@end deffn

@geindex execute() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection execute}@anchor{2fc1}
@deffn {Μέθοδος} execute (sql, parameters=(), /)

Create a new @ref{2f8d,,Cursor} object and call
@ref{7a8,,execute()} on it with the given `sql' and `parameters'.
Return the new cursor object.
@end deffn

@geindex executemany() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection executemany}@anchor{2fc2}
@deffn {Μέθοδος} executemany (sql, parameters, /)

Create a new @ref{2f8d,,Cursor} object and call
@ref{7a9,,executemany()} on it with the given `sql' and `parameters'.
Return the new cursor object.
@end deffn

@geindex executescript() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection executescript}@anchor{2fc3}
@deffn {Μέθοδος} executescript (sql_script, /)

Create a new @ref{2f8d,,Cursor} object and call
@ref{2fc4,,executescript()} on it with the given `sql_script'.
Return the new cursor object.
@end deffn

@geindex create_function() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection create_function}@anchor{3e1}
@deffn {Μέθοδος} create_function (name, narg, func, /, *, deterministic=False)

Create or remove a user-defined SQL function.

@*Παράμετροι: 

@itemize *

@item 
@code{name} (@ref{1df,,str}) – The name of the SQL function.

@item 
@code{narg} (@ref{326,,int}) – The number of arguments the SQL function can accept.
If @code{-1}, it may take any number of arguments.

@item 
@code{func} (@ref{2fc5,,callback} | None) – A @ref{2fa4,,callable} that is called when the SQL function is invoked.
The callable must return @ref{2f99,,a type natively supported by SQLite}.
Set to @code{None} to remove an existing SQL function.

@item 
@code{deterministic} (@ref{5ef,,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



Άλλαξε στην έκδοση 3.8: Added the `deterministic' parameter.



Άλλαξε στην έκδοση 3.15: The first three parameters are now positional-only.


Example:

@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
@end deffn

@geindex create_aggregate() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection create_aggregate}@anchor{3e2}
@deffn {Μέθοδος} create_aggregate (name, n_arg, aggregate_class, /)

Create or remove a user-defined SQL aggregate function.

@*Παράμετροι: 

@itemize *

@item 
@code{name} (@ref{1df,,str}) – The name of the SQL aggregate function.

@item 
@code{n_arg} (@ref{326,,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{1ef2,,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{2f99,,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



Άλλαξε στην έκδοση 3.15: All three parameters are now positional-only.


Example:

@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
@end deffn

@geindex create_window_function() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection create_window_function}@anchor{a70}
@deffn {Μέθοδος} create_window_function (name, num_params, aggregate_class, /)

Create or remove a user-defined aggregate window function.

@*Παράμετροι: 

@itemize *

@item 
@code{name} (@ref{1df,,str}) – The name of the SQL aggregate window function to create or remove.

@item 
@code{num_params} (@ref{326,,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{1ef2,,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{2f99,,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


@*Προκαλεί: 
@ref{2fc6,,NotSupportedError} – If used with a version of SQLite older than 3.25.0,
which does not support aggregate window functions.



Added in version 3.11.


Example:

@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() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection create_collation}@anchor{a66}
@deffn {Μέθοδος} create_collation (name, callable, /)

Create a collation named `name' using the collating function `callable'.
`callable' is passed two @ref{1df,,string} arguments,
and it should return an @ref{326,,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}.


Άλλαξε στην έκδοση 3.11: The collation name can contain any Unicode character.  Earlier, only
ASCII characters were allowed.

@end deffn

@geindex interrupt() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection interrupt}@anchor{2fc7}
@deffn {Μέθοδος} 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{1e49,,OperationalError}.
@end deffn

@geindex set_authorizer() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection set_authorizer}@anchor{3e3}
@deffn {Μέθοδος} set_authorizer (authorizer_callback, /)

Register @ref{2fa4,,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{2fa7,,SQLITE_OK},
@ref{2fa8,,SQLITE_DENY}, or @ref{2fa9,,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.


Άλλαξε στην έκδοση 3.11: Added support for disabling the authorizer using @code{None}.



Άλλαξε στην έκδοση 3.15: The only parameter is now positional-only.

@end deffn

@geindex set_progress_handler() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection set_progress_handler}@anchor{3e4}
@deffn {Μέθοδος} set_progress_handler (progress_handler, /, n)

Register @ref{2fa4,,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{2fc8,,DatabaseError}
exception.


Άλλαξε στην έκδοση 3.15: The first parameter is now positional-only.

@end deffn

@geindex set_trace_callback() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection set_trace_callback}@anchor{3e5}
@deffn {Μέθοδος} set_trace_callback (trace_callback, /)

Register @ref{2fa4,,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{1df,,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{7a8,,Cursor.execute()} methods.  Other sources include the
@ref{2f8f,,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 Σημείωση 
Exceptions raised in the trace callback are not propagated. As a
development and debugging aid, use
@ref{2fa2,,enable_callback_tracebacks()} to enable printing
tracebacks from exceptions raised in the trace callback.
@end quotation
@end cartouche


Added in version 3.3.



Άλλαξε στην έκδοση 3.15: The first parameter is now positional-only.

@end deffn

@geindex enable_load_extension() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection enable_load_extension}@anchor{c17}
@deffn {Μέθοδος} 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 Σημείωση 
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{234f,,--enable-loadable-sqlite-extensions} option
to @code{configure}.
@end quotation
@end cartouche

Raises an @ref{1e65,,auditing event} @code{sqlite3.enable_load_extension} with arguments @code{connection}, @code{enabled}.


Added in version 3.2.



Άλλαξε στην έκδοση 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() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection load_extension}@anchor{8c8}
@deffn {Μέθοδος} load_extension (path, /, *, entrypoint=None)

Load an SQLite extension from a shared library.
Enable extension loading with @ref{c17,,enable_load_extension()} before
calling this method.

@*Παράμετροι: 

@itemize *

@item 
@code{path} (@ref{1df,,str}) – The path to the SQLite extension.

@item 
@code{entrypoint} (@ref{1df,,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{1e65,,auditing event} @code{sqlite3.load_extension} with arguments @code{connection}, @code{path}.


Added in version 3.2.



Άλλαξε στην έκδοση 3.10: Added the @code{sqlite3.load_extension} auditing event.



Άλλαξε στην έκδοση 3.12: Added the `entrypoint' parameter.

@end deffn

@geindex iterdump() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection iterdump}@anchor{751}
@deffn {Μέθοδος} iterdump (*, filter=None)

Return an @ref{6ce,,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.

@*Παράμετροι: 
@code{filter} (@ref{1df,,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.


Example:

@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 Δείτε επίσης


@ref{2fc9,,How to handle non-UTF-8 text encodings}



Άλλαξε στην έκδοση 3.13: Added the `filter' parameter.

@end deffn

@geindex backup() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection backup}@anchor{f39}
@deffn {Μέθοδος} 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.

@*Παράμετροι: 

@itemize *

@item 
@code{target} (@ref{3df,,Connection}) – The database connection to save the backup to.

@item 
@code{pages} (@ref{326,,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{2fc5,,callback} | None) – If set to a @ref{2fa4,,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{1df,,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{327,,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


Added in version 3.7.



@subsubheading Δείτε επίσης


@ref{2fc9,,How to handle non-UTF-8 text encodings}

@end deffn

@geindex getlimit() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection getlimit}@anchor{a6b}
@deffn {Μέθοδος} getlimit (category, /)

Get a connection runtime limit.

@*Παράμετροι: 
@code{category} (@ref{326,,int}) – The SQLite limit category@footnote{https://www.sqlite.org/c3ref/c_limit_attached.html} to be queried.


@*Επιστρεφόμενος τύπος: 
@ref{326,,int}


@*Προκαλεί: 
@ref{57d,,ProgrammingError} – If `category' is not recognised by the underlying SQLite library.


Example, query the maximum length of an SQL statement
for @code{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


Added in version 3.11.

@end deffn

@geindex setlimit() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection setlimit}@anchor{a6a}
@deffn {Μέθοδος} 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.

@*Παράμετροι: 

@itemize *

@item 
@code{category} (@ref{326,,int}) – The SQLite limit category@footnote{https://www.sqlite.org/c3ref/c_limit_attached.html} to be set.

@item 
@code{limit} (@ref{326,,int}) – The value of the new limit.
If negative, the current limit is unchanged.
@end itemize


@*Επιστρεφόμενος τύπος: 
@ref{326,,int}


@*Προκαλεί: 
@ref{57d,,ProgrammingError} – If `category' is not recognised by the underlying SQLite library.


Example, limit the number of attached databases to 1
for @code{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()


Added in version 3.11.

@end deffn

@geindex getconfig() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection getconfig}@anchor{8c9}
@deffn {Μέθοδος} getconfig (op, /)

Query a boolean connection configuration option.

@*Παράμετροι: 
@code{op} (@ref{326,,int}) – A @ref{2fac,,SQLITE_DBCONFIG code}.


@*Επιστρεφόμενος τύπος: 
@ref{5ef,,bool}



Added in version 3.12.

@end deffn

@geindex setconfig() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection setconfig}@anchor{8ca}
@deffn {Μέθοδος} setconfig (op, enable=True, /)

Set a boolean connection configuration option.

@*Παράμετροι: 

@itemize *

@item 
@code{op} (@ref{326,,int}) – A @ref{2fac,,SQLITE_DBCONFIG code}.

@item 
@code{enable} (@ref{5ef,,bool}) – @code{True} if the configuration option should be enabled (default);
@code{False} if it should be disabled.
@end itemize



Added in version 3.12.

@end deffn

@geindex serialize() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection serialize}@anchor{a6e}
@deffn {Μέθοδος} serialize (*, name='main')

Serialize a database into a @ref{1c7,,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.

@*Παράμετροι: 
@code{name} (@ref{1df,,str}) – The database name to be serialized.
Defaults to @code{"main"}.


@*Επιστρεφόμενος τύπος: 
@ref{1c7,,bytes}


@cartouche
@quotation Σημείωση 
This method is only available if the underlying SQLite library has the
serialize API.
@end quotation
@end cartouche


Added in version 3.11.

@end deffn

@geindex deserialize() (μέθοδος της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection deserialize}@anchor{a6f}
@deffn {Μέθοδος} deserialize (data, /, *, name='main')

Deserialize a @ref{a6e,,serialized} database into a
@code{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'.

@*Παράμετροι: 

@itemize *

@item 
@code{data} (@ref{1c7,,bytes}) – A serialized database.

@item 
@code{name} (@ref{1df,,str}) – The database name to deserialize into.
Defaults to @code{"main"}.
@end itemize


@*Προκαλεί: 

@itemize *

@item 
@ref{1e49,,OperationalError} – If the database connection is currently involved in a read
transaction or a backup operation.

@item 
@ref{2fc8,,DatabaseError} – If `data' does not contain a valid SQLite database.

@item 
@ref{c57,,OverflowError} – If @ref{a1f,,len(data)} is larger than @code{2**63 - 1}.
@end itemize


@cartouche
@quotation Σημείωση 
This method is only available if the underlying SQLite library has the
deserialize API.
@end quotation
@end cartouche


Added in version 3.11.

@end deffn

@geindex autocommit (ιδιότητα της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection autocommit}@anchor{8c6}
@deffn {Ιδιότητα} 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{2f90,,commit()} and @ref{2fc0,,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{2f90,,commit()} and @ref{2fc0,,rollback()} have no effect in this mode.

@item 
@ref{2f9f,,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{2f9d,,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{8c7,,Transaction control via the autocommit attribute} for more details.

@cartouche
@quotation Σημείωση 
The @ref{2f9d,,isolation_level} attribute has no effect unless
@ref{8c6,,autocommit} is @ref{2f9f,,LEGACY_TRANSACTION_CONTROL}.
@end quotation
@end cartouche


Added in version 3.12.

@end deffn

@geindex in_transaction (ιδιότητα της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection in_transaction}@anchor{2fca}
@deffn {Ιδιότητα} 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.


Added in version 3.2.

@end deffn

@geindex isolation_level (ιδιότητα της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection isolation_level}@anchor{2f9d}
@deffn {Ιδιότητα} isolation_level

Controls the @ref{2f9e,,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{2f9e,,implicit transaction management} is performed.

If not overridden by the `isolation_level' parameter of @ref{3e0,,connect()},
the default is @code{""}, which is an alias for @code{"DEFERRED"}.

@cartouche
@quotation Σημείωση 
Using @ref{8c6,,autocommit} to control transaction handling is
recommended over using @code{isolation_level}.
@code{isolation_level} has no effect unless @code{autocommit} is
set to @ref{2f9f,,LEGACY_TRANSACTION_CONTROL} (the default).
@end quotation
@end cartouche
@end deffn

@geindex row_factory (ιδιότητα της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection row_factory}@anchor{1bb0}
@deffn {Ιδιότητα} row_factory

The initial @ref{2fcb,,row_factory}
for @ref{2f8d,,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{1ce,,tuple}.

See @ref{2f94,,How to create and use row factories} for more details.
@end deffn

@geindex text_factory (ιδιότητα της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection text_factory}@anchor{2fcc}
@deffn {Ιδιότητα} text_factory

A @ref{2fa4,,callable} that accepts a @ref{1c7,,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{1df,,str}.

See @ref{2fc9,,How to handle non-UTF-8 text encodings} for more details.
@end deffn

@geindex total_changes (ιδιότητα της sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection total_changes}@anchor{2fcd}
@deffn {Ιδιότητα} 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,Reference
@anchor{library/sqlite3 cursor-objects}@anchor{2fce}@anchor{library/sqlite3 sqlite3-cursor-objects}@anchor{2fcf}
@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{2f8c,,Connection.cursor()},
or by using any of the @ref{2fbf,,connection shortcut methods}.

Cursor objects are @ref{6ce,,iterators},
meaning that if you @ref{7a8,,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 (κλάση σε sqlite3)
@anchor{library/sqlite3 sqlite3 Cursor}@anchor{2f8d}
@deffn {Κλάση} sqlite3.Cursor

A @code{Cursor} instance has the following attributes and methods.

@geindex ? (question mark);in SQL statements

@geindex ; (colon);in SQL statements

@geindex execute() (μέθοδος της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor execute}@anchor{7a8}
@deffn {Μέθοδος} execute (sql, parameters=(), /)

Execute a single SQL statement,
optionally binding Python values using
@ref{7aa,,placeholders}.

@*Παράμετροι: 

@itemize *

@item 
@code{sql} (@ref{1df,,str}) – A single SQL statement.

@item 
@code{parameters} (@ref{188,,dict} | @ref{8ff,,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{7aa,,How to use placeholders to bind values in SQL queries}.
@end itemize


@*Προκαλεί: 
@ref{57d,,ProgrammingError} – When `sql' contains more than one SQL statement.
When @ref{7aa,,named placeholders} are used
and `parameters' is a sequence instead of a @ref{188,,dict}.


If @ref{8c6,,autocommit} is
@ref{2f9f,,LEGACY_TRANSACTION_CONTROL},
@ref{2f9d,,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'.


Άλλαξε στην έκδοση 3.14: @ref{57d,,ProgrammingError} is emitted if
@ref{7aa,,named placeholders} are used
and `parameters' is a sequence instead of a @ref{188,,dict}.


Use @ref{2fc4,,executescript()} to execute multiple SQL statements.
@end deffn

@geindex executemany() (μέθοδος της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor executemany}@anchor{7a9}
@deffn {Μέθοδος} executemany (sql, parameters, /)

For every item in `parameters',
repeatedly execute the @ref{7aa,,parameterized}
@abbr{DML,Data Manipulation Language} SQL statement `sql'.

Uses the same implicit transaction handling as @ref{7a8,,execute()}.

@*Παράμετροι: 

@itemize *

@item 
@code{sql} (@ref{1df,,str}) – A single SQL DML statement.

@item 
@code{parameters} (@ref{15ce,,iterable}) – An iterable of parameters to bind with
the placeholders in `sql'.
See @ref{7aa,,How to use placeholders to bind values in SQL queries}.
@end itemize


@*Προκαλεί: 
@ref{57d,,ProgrammingError} – When `sql' contains more than one SQL statement
or is not a DML statement,
When @ref{7aa,,named placeholders} are used
and the items in `parameters' are sequences instead of @ref{188,,dict}s.


Example:

@example
rows = [
    ("row1",),
    ("row2",),
]
# cur is an sqlite3.Cursor object
cur.executemany("INSERT INTO data VALUES(?)", rows)
@end example

@c con.close()

@cartouche
@quotation Σημείωση 
Any resulting rows are discarded,
including DML statements with RETURNING clauses@footnote{https://www.sqlite.org/lang_returning.html}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.14: @ref{57d,,ProgrammingError} is emitted if
@ref{7aa,,named placeholders} are used
and the items in `parameters' are sequences
instead of @ref{188,,dict}s.

@end deffn

@geindex executescript() (μέθοδος της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor executescript}@anchor{2fc4}
@deffn {Μέθοδος} executescript (sql_script, /)

Execute the SQL statements in `sql_script'.
If the @ref{8c6,,autocommit} is
@ref{2f9f,,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{1df,,string}.

Example:

@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() (μέθοδος της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor fetchone}@anchor{2f8e}
@deffn {Μέθοδος} fetchone ()

If @ref{2fcb,,row_factory} is @code{None},
return the next row query result set as a @ref{1ce,,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() (μέθοδος της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor fetchmany}@anchor{19ef}
@deffn {Μέθοδος} fetchmany (size=cursor.arraysize)

Return the next set of rows of a query result as a @ref{4d9,,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{19f0,,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 @code{fetchmany()} call to the next.


Άλλαξε στην έκδοση 3.15: Negative `size' values are rejected by raising @ref{277,,ValueError}.

@end deffn

@geindex fetchall() (μέθοδος της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor fetchall}@anchor{2f91}
@deffn {Μέθοδος} fetchall ()

Return all (remaining) rows of a query result as a @ref{4d9,,list}.
Return an empty list if no rows are available.
Note that the @ref{19f0,,arraysize} attribute can affect the performance of
this operation.
@end deffn

@geindex close() (μέθοδος της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor close}@anchor{2fd0}
@deffn {Μέθοδος} close ()

Close the cursor now (rather than whenever @code{__del__} is called).

The cursor will be unusable from this point forward; a @ref{57d,,ProgrammingError}
exception will be raised if any operation is attempted with the cursor.
@end deffn

@geindex setinputsizes() (μέθοδος της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor setinputsizes}@anchor{2fd1}
@deffn {Μέθοδος} setinputsizes (sizes, /)

Required by the DB-API. Does nothing in @code{sqlite3}.
@end deffn

@geindex setoutputsize() (μέθοδος της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor setoutputsize}@anchor{2fd2}
@deffn {Μέθοδος} setoutputsize (size, column=None, /)

Required by the DB-API. Does nothing in @code{sqlite3}.
@end deffn

@geindex arraysize (ιδιότητα της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor arraysize}@anchor{19f0}
@deffn {Ιδιότητα} arraysize

Read/write attribute that controls the number of rows returned by @ref{19ef,,fetchmany()}.
The default value is 1 which means a single row would be fetched per call.


Άλλαξε στην έκδοση 3.15: Negative values are rejected by raising @ref{277,,ValueError}.

@end deffn

@geindex connection (ιδιότητα της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor connection}@anchor{2fd3}
@deffn {Ιδιότητα} connection

Read-only attribute that provides the SQLite database @ref{3df,,Connection}
belonging to the cursor.  A @code{Cursor} object created by
calling @ref{2f8c,,con.cursor()} will have a
@ref{2fd3,,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 (ιδιότητα της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor description}@anchor{1ace}
@deffn {Ιδιότητα} 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 (ιδιότητα της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor lastrowid}@anchor{108e}
@deffn {Ιδιότητα} 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{7a8,,execute()} method.  For other statements, after
@ref{7a9,,executemany()} or @ref{2fc4,,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 Σημείωση 
Inserts into @code{WITHOUT ROWID} tables are not recorded.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.6: Added support for the @code{REPLACE} statement.

@end deffn

@geindex rowcount (ιδιότητα της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor rowcount}@anchor{1d5e}
@deffn {Ιδιότητα} 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{7a8,,execute()} and @ref{7a9,,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 (ιδιότητα της sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor row_factory}@anchor{2fcb}
@deffn {Ιδιότητα} row_factory

Control how a row fetched from this @code{Cursor} is represented.
If @code{None}, a row is represented as a @ref{1ce,,tuple}.
Can be set to the included @ref{1222,,sqlite3.Row};
or a @ref{2fa4,,callable} that accepts two arguments,
a @code{Cursor} object and the @code{tuple} of row values,
and returns a custom object representing an SQLite row.

Defaults to what @ref{1bb0,,Connection.row_factory} was set to
when the @code{Cursor} was created.
Assigning to this attribute does not affect
@code{Connection.row_factory} of the parent connection.

See @ref{2f94,,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{2fd4}
@node Row objects,Blob objects,Cursor objects,Reference
@anchor{library/sqlite3 row-objects}@anchor{2fd5}@anchor{library/sqlite3 sqlite3-row-objects}@anchor{2fd6}
@subsubsection Row objects


@geindex Row (κλάση σε sqlite3)
@anchor{library/sqlite3 sqlite3 Row}@anchor{1222}
@deffn {Κλάση} sqlite3.Row

A @code{Row} instance serves as a highly optimized
@ref{1bb0,,row_factory} for @ref{3df,,Connection} objects.
It supports iteration, equality testing, @ref{a1f,,len()},
and @ref{1564,,mapping} access by column name and index.

Two @code{Row} objects compare equal
if they have identical column names and values.

See @ref{2f94,,How to create and use row factories} for more details.

@geindex keys() (μέθοδος της sqlite3.Row)
@anchor{library/sqlite3 sqlite3 Row keys}@anchor{2fd7}
@deffn {Μέθοδος} keys ()

Return a @ref{4d9,,list} of column names as @ref{1df,,strings}.
Immediately after a query,
it is the first member of each tuple in @ref{1ace,,Cursor.description}.
@end deffn


Άλλαξε στην έκδοση 3.5: Added support of slicing.

@end deffn

@node Blob objects,PrepareProtocol objects,Row objects,Reference
@anchor{library/sqlite3 blob-objects}@anchor{2fd8}@anchor{library/sqlite3 sqlite3-blob-objects}@anchor{2fd9}
@subsubsection Blob objects


@geindex Blob (κλάση σε sqlite3)
@anchor{library/sqlite3 sqlite3 Blob}@anchor{a72}
@deffn {Κλάση} sqlite3.Blob


Added in version 3.11.


A @code{Blob} instance is a @ref{19b1,,file-like object}
that can read and write data in an SQLite @abbr{BLOB}.
Call @ref{a1f,,len(blob)} to get the size (number of bytes) of the blob.
Use indices and @ref{26a5,,slices} for direct access to the blob data.

Use the @code{Blob} as a @ref{478,,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() (μέθοδος της sqlite3.Blob)
@anchor{library/sqlite3 sqlite3 Blob close}@anchor{2fda}
@deffn {Μέθοδος} close ()

Close the blob.

The blob will be unusable from this point onward.  An
@ref{1e1c,,Error} (or subclass) exception will be raised if any
further operation is attempted with the blob.
@end deffn

@geindex read() (μέθοδος της sqlite3.Blob)
@anchor{library/sqlite3 sqlite3 Blob read}@anchor{2fdb}
@deffn {Μέθοδος} 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, @code{read()} will read until the end of
the blob.
@end deffn

@geindex write() (μέθοδος της sqlite3.Blob)
@anchor{library/sqlite3 sqlite3 Blob write}@anchor{2fdc}
@deffn {Μέθοδος} 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{277,,ValueError}.
@end deffn

@geindex tell() (μέθοδος της sqlite3.Blob)
@anchor{library/sqlite3 sqlite3 Blob tell}@anchor{2fdd}
@deffn {Μέθοδος} tell ()

Return the current access position of the blob.
@end deffn

@geindex seek() (μέθοδος της sqlite3.Blob)
@anchor{library/sqlite3 sqlite3 Blob seek}@anchor{2fde}
@deffn {Μέθοδος} seek (offset, origin=os.SEEK_SET, /)

Set the current access position of the blob to `offset'.  The `origin'
argument defaults to @ref{1632,,os.SEEK_SET} (absolute blob positioning).
Other values for `origin' are @ref{1633,,os.SEEK_CUR} (seek relative to the
current position) and @ref{1634,,os.SEEK_END} (seek relative to the blob’s
end).
@end deffn
@end deffn

@node PrepareProtocol objects,Exceptions<6>,Blob objects,Reference
@anchor{library/sqlite3 prepareprotocol-objects}@anchor{2fdf}
@subsubsection PrepareProtocol objects


@geindex PrepareProtocol (κλάση σε sqlite3)
@anchor{library/sqlite3 sqlite3 PrepareProtocol}@anchor{1d68}
@deffn {Κλάση} 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{2fe0,,adapt themselves} to @ref{2f99,,native SQLite types}.
@end deffn

@node Exceptions<6>,SQLite and Python types,PrepareProtocol objects,Reference
@anchor{library/sqlite3 exceptions}@anchor{2fe1}@anchor{library/sqlite3 sqlite3-exceptions}@anchor{2fe2}
@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{1db0}
@deffn {Εξαίρεση} 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{d9e,,Exception}.
@end deffn

@geindex Error
@anchor{library/sqlite3 sqlite3 Error}@anchor{1e1c}
@deffn {Εξαίρεση} sqlite3.Error

The base class of the other exceptions in this module.
Use this to catch all errors with one single @ref{447,,except} statement.
@code{Error} is a subclass of @ref{d9e,,Exception}.

If the exception originated from within the SQLite library,
the following two attributes are added to the exception:

@geindex sqlite_errorcode (ιδιότητα της sqlite3.Error)
@anchor{library/sqlite3 sqlite3 Error sqlite_errorcode}@anchor{a68}
@deffn {Ιδιότητα} sqlite_errorcode

The numeric error code from the
SQLite API@footnote{https://sqlite.org/rescode.html}


Added in version 3.11.

@end deffn

@geindex sqlite_errorname (ιδιότητα της sqlite3.Error)
@anchor{library/sqlite3 sqlite3 Error sqlite_errorname}@anchor{a69}
@deffn {Ιδιότητα} sqlite_errorname

The symbolic name of the numeric error code
from the SQLite API@footnote{https://sqlite.org/rescode.html}


Added in version 3.11.

@end deffn
@end deffn

@geindex InterfaceError
@anchor{library/sqlite3 sqlite3 InterfaceError}@anchor{a6d}
@deffn {Εξαίρεση} 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{1e1c,,Error}.
@end deffn

@geindex DatabaseError
@anchor{library/sqlite3 sqlite3 DatabaseError}@anchor{2fc8}
@deffn {Εξαίρεση} 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{1e1c,,Error}.
@end deffn

@geindex DataError
@anchor{library/sqlite3 sqlite3 DataError}@anchor{1e48}
@deffn {Εξαίρεση} 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{2fc8,,DatabaseError}.
@end deffn

@geindex OperationalError
@anchor{library/sqlite3 sqlite3 OperationalError}@anchor{1e49}
@deffn {Εξαίρεση} 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{2fc8,,DatabaseError}.
@end deffn

@geindex IntegrityError
@anchor{library/sqlite3 sqlite3 IntegrityError}@anchor{2fe3}
@deffn {Εξαίρεση} 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{2fc8,,DatabaseError}.
@end deffn

@geindex InternalError
@anchor{library/sqlite3 sqlite3 InternalError}@anchor{2fe4}
@deffn {Εξαίρεση} 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{2fc8,,DatabaseError}.
@end deffn

@geindex ProgrammingError
@anchor{library/sqlite3 sqlite3 ProgrammingError}@anchor{57d}
@deffn {Εξαίρεση} 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{3df,,Connection}.
@code{ProgrammingError} is a subclass of @ref{2fc8,,DatabaseError}.
@end deffn

@geindex NotSupportedError
@anchor{library/sqlite3 sqlite3 NotSupportedError}@anchor{2fc6}
@deffn {Εξαίρεση} 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{3e1,,create_function()}, if the underlying SQLite library
does not support deterministic functions.
@code{NotSupportedError} is a subclass of @ref{2fc8,,DatabaseError}.
@end deffn

@node SQLite and Python types,Default adapters and converters deprecated,Exceptions<6>,Reference
@anchor{library/sqlite3 sqlite-and-python-types}@anchor{2fe5}@anchor{library/sqlite3 sqlite3-types}@anchor{2f99}
@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

Python type

@tab

SQLite type

@item

@code{None}

@tab

@code{NULL}

@item

@ref{326,,int}

@tab

@code{INTEGER}

@item

@ref{327,,float}

@tab

@code{REAL}

@item

@ref{1df,,str}

@tab

@code{TEXT}

@item

@ref{1c7,,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

Python type

@item

@code{NULL}

@tab

@code{None}

@item

@code{INTEGER}

@tab

@ref{326,,int}

@item

@code{REAL}

@tab

@ref{327,,float}

@item

@code{TEXT}

@tab

depends on @ref{2fcc,,text_factory},
@ref{1df,,str} by default

@item

@code{BLOB}

@tab

@ref{1c7,,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{2f92,,object adapters},
and you can let the @code{sqlite3} module convert SQLite types to
Python types via @ref{2f93,,converters}.

@node Default adapters and converters deprecated,Command-line interface<2>,SQLite and Python types,Reference
@anchor{library/sqlite3 default-adapters-and-converters-deprecated}@anchor{2fe6}@anchor{library/sqlite3 sqlite3-default-converters}@anchor{8fd}
@subsubsection Default adapters and converters (deprecated)


@cartouche
@quotation Σημείωση 
The default adapters and converters are deprecated as of Python 3.12.
Instead, use the @ref{8fe,,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{48d,,datetime.date} objects to @ref{1df,,strings} in
ISO 8601@footnote{https://en.wikipedia.org/wiki/ISO_8601} format.

@item 
An adapter for @ref{6e7,,datetime.datetime} objects to strings in
ISO 8601 format.

@item 
A converter for @ref{2f93,,declared} «date» types to
@ref{48d,,datetime.date} objects.

@item 
A converter for declared «timestamp» types to
@ref{6e7,,datetime.datetime} objects.
Fractional parts will be truncated to 6 digits (microsecond precision).
@end itemize

@cartouche
@quotation Σημείωση 
The default «timestamp» converter ignores UTC offsets in the database and
always returns a naive @ref{6e7,,datetime.datetime} object. To preserve UTC
offsets in timestamps, either leave converters disabled, or register an
offset-aware converter with @ref{2f9a,,register_converter()}.
@end quotation
@end cartouche


Αποσύρθηκε στην έκδοση 3.12.


@node Command-line interface<2>,,Default adapters and converters deprecated,Reference
@anchor{library/sqlite3 command-line-interface}@anchor{2fe7}@anchor{library/sqlite3 sqlite3-cli}@anchor{257}
@subsubsection Command-line interface


The @code{sqlite3} module can be invoked as a script,
using the interpreter’s @ref{4ca,,-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 python--m-sqlite3-[-h]-[-v]-[filename]-[sql] command line option; -h
@geindex python--m-sqlite3-[-h]-[-v]-[filename]-[sql] command line option; --help
@anchor{library/sqlite3 cmdoption-python-m-sqlite3-h-v-filename-sql-h}@anchor{2fe8}@anchor{library/sqlite3 cmdoption-python-m-sqlite3-h-v-filename-sql-help}@anchor{2fe9}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Print CLI help.
@end deffn

@geindex python--m-sqlite3-[-h]-[-v]-[filename]-[sql] command line option; -v
@geindex python--m-sqlite3-[-h]-[-v]-[filename]-[sql] command line option; --version
@anchor{library/sqlite3 cmdoption-python-m-sqlite3-h-v-filename-sql-v}@anchor{2fea}@anchor{library/sqlite3 cmdoption-python-m-sqlite3-h-v-filename-sql-version}@anchor{2feb}
@deffn {Option} @w{-}v, @w{-}@w{-}version

Print underlying SQLite library version.
@end deffn


Added in version 3.12.


@node How-to guides,Explanation,Reference,sqlite3 — DB-API 2 0 interface for SQLite databases
@anchor{library/sqlite3 how-to-guides}@anchor{2fec}@anchor{library/sqlite3 sqlite3-howtos}@anchor{2f89}
@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{2fed}@anchor{library/sqlite3 sqlite3-placeholders}@anchor{7aa}
@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{1ce,,tuple} of values to the second
argument of the cursor’s @ref{7a8,,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{8ff,,sequence} whose length must match the number of placeholders,
or a @ref{57d,,ProgrammingError} is raised.
For the named style, `parameters' must be
an instance of a @ref{188,,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 Σημείωση 
@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{2fee}@anchor{library/sqlite3 sqlite3-adapters}@anchor{2f92}
@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{2f99,,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{2fef}@anchor{library/sqlite3 sqlite3-conform}@anchor{2fe0}
@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{1d68,,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{2ff0}
@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{2fa3,,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{2ff1}@anchor{library/sqlite3 sqlite3-converters}@anchor{2f93}
@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 Σημείωση 
Converter functions are `always' passed a @ref{1c7,,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{3e0,,connect()}. There are three options:


@itemize *

@item 
Implicit: set `detect_types' to @ref{2f9b,,PARSE_DECLTYPES}

@item 
Explicit: set `detect_types' to @ref{2f9c,,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{2ff2}@anchor{library/sqlite3 sqlite3-adapter-converter-recipes}@anchor{8fe}
@subsubsection Adapter and converter recipes


This section shows recipes for common adapters and converters.

@example
import datetime as dt
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.replace(tzinfo=None).isoformat()

def adapt_datetime_epoch(val):
    """Adapt datetime.datetime to Unix timestamp."""
    return int(val.timestamp())

sqlite3.register_adapter(dt.date, adapt_date_iso)
sqlite3.register_adapter(dt.datetime, adapt_datetime_iso)
sqlite3.register_adapter(dt.datetime, adapt_datetime_epoch)

def convert_date(val):
    """Convert ISO 8601 date to datetime.date object."""
    return dt.date.fromisoformat(val.decode())

def convert_datetime(val):
    """Convert ISO 8601 datetime to datetime.datetime object."""
    return dt.datetime.fromisoformat(val.decode())

def convert_timestamp(val):
    """Convert Unix epoch timestamp to datetime.datetime object."""
    return dt.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 when = dt.datetime(2019, 5, 18, 15, 17, 8, 123456)
@c 
@c assert adapt_date_iso(when.date()) == "2019-05-18"
@c assert convert_date(b"2019-05-18") == when.date()
@c 
@c assert adapt_datetime_iso(when) == "2019-05-18T15:17:08.123456"
@c assert convert_datetime(b"2019-05-18T15:17:08.123456") == when
@c 
@c # Using current time as fromtimestamp() returns local date/time.
@c # Dropping microseconds as adapt_datetime_epoch truncates fractional second part.
@c now = dt.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{2ff3}@anchor{library/sqlite3 sqlite3-connection-shortcuts}@anchor{2fbf}
@subsubsection How to use connection shortcut methods


Using the @ref{2fc1,,execute()},
@ref{2fc2,,executemany()}, and @ref{2fc3,,executescript()}
methods of the @ref{3df,,Connection} class, your code can
be written more concisely because you don’t have to create the (often
superfluous) @ref{2f8d,,Cursor} objects explicitly. Instead, the @code{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 @code{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{2ff4}@anchor{library/sqlite3 sqlite3-connection-context-manager}@anchor{1d69}
@subsubsection How to use the connection context manager


A @ref{3df,,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{20a,,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{8c6,,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{8c6,,autocommit} is @code{True},
the context manager does nothing.

@cartouche
@quotation Σημείωση 
The context manager neither implicitly opens a new transaction
nor closes the connection. If you need a closing context manager, consider
using @ref{3ec,,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{2ff5}@anchor{library/sqlite3 sqlite3-uri-tricks}@anchor{2fa0}
@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{1e49,,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{2ff6}@anchor{library/sqlite3 sqlite3-howto-row-factory}@anchor{2f94}
@subsubsection How to create and use row factories


By default, @code{sqlite3} represents each row as a @ref{1ce,,tuple}.
If a @code{tuple} does not suit your needs,
you can use the @ref{1222,,sqlite3.Row} class
or a custom @ref{2fcb,,row_factory}.

While @code{row_factory} exists as an attribute both on the
@ref{2f8d,,Cursor} and the @ref{3df,,Connection},
it is recommended to set @ref{1bb0,,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 Σημείωση 
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{2fcb,,row_factory}
that returns each row as a @ref{188,,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{a3d,,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{6e6,,dataclass}, or any other custom class,
instead of a @ref{1cf,,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{2ff7}@anchor{library/sqlite3 sqlite3-howto-encoding}@anchor{2fc9}
@subsubsection How to handle non-UTF-8 text encodings


By default, @code{sqlite3} uses @ref{1df,,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{2fcc,,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{3df,,Connection} instance @code{con}
connected to this database,
we can decode the Latin-2 encoded text using this @ref{2fcc,,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{1649,,Unicode HOWTO}:

@example
con.text_factory = lambda data: str(data, errors="surrogateescape")
@end example

@cartouche
@quotation Σημείωση 
The @code{sqlite3} module API does not support strings
containing surrogates.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης


@ref{1649,,Unicode HOWTO}


@node Explanation,,How-to guides,sqlite3 — DB-API 2 0 interface for SQLite databases
@anchor{library/sqlite3 explanation}@anchor{2ff8}@anchor{library/sqlite3 sqlite3-explanation}@anchor{2f8a}
@subsubsection Explanation

@anchor{library/sqlite3 sqlite3-transaction-control}@anchor{2ff9}
@menu
* Transaction control:: 

@end menu

@node Transaction control,,,Explanation
@anchor{library/sqlite3 sqlite3-controlling-transactions}@anchor{2f8f}@anchor{library/sqlite3 transaction-control}@anchor{2ffa}
@subsubsection Transaction control


@code{sqlite3} offers multiple methods of controlling whether,
when and how database transactions are opened and closed.
@ref{8c7,,Transaction control via the autocommit attribute} is recommended,
while @ref{2f9e,,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{8c7}@anchor{library/sqlite3 transaction-control-via-the-autocommit-attribute}@anchor{2ffb}
@subsubsection Transaction control via the @code{autocommit} attribute


The recommended way of controlling transaction behaviour is through
the @ref{8c6,,Connection.autocommit} attribute,
which should preferably be set using the `autocommit' parameter
of @ref{3e0,,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{3e0,,connect()}, @ref{2f90,,Connection.commit()}, and @ref{2fc0,,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{750,,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{2f90,,Connection.commit()} and @ref{2fc0,,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{8c6,,Connection.autocommit} attribute;
use @ref{2fca,,Connection.in_transaction} to query
the low-level SQLite autocommit mode.

Set `autocommit' to @ref{2f9f,,LEGACY_TRANSACTION_CONTROL}
to leave transaction control behaviour to the
@ref{2f9d,,Connection.isolation_level} attribute.
See @ref{2f9e,,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{2f9e}@anchor{library/sqlite3 transaction-control-via-the-isolation-level-attribute}@anchor{2ffc}
@subsubsection Transaction control via the @code{isolation_level} attribute


@cartouche
@quotation Σημείωση 
The recommended way of controlling transactions is via the
@ref{8c6,,autocommit} attribute.
See @ref{8c7,,Transaction control via the autocommit attribute}.
@end quotation
@end cartouche

If @ref{8c6,,Connection.autocommit} is set to
@ref{2f9f,,LEGACY_TRANSACTION_CONTROL} (the default),
transaction behaviour is controlled using
the @ref{2f9d,,Connection.isolation_level} attribute.
Otherwise, @code{isolation_level} has no effect.

If the connection attribute @ref{2f9d,,isolation_level}
is not @code{None},
new transactions are implicitly opened before
@ref{7a8,,execute()} and @ref{7a9,,executemany()} executes
@code{INSERT}, @code{UPDATE}, @code{DELETE}, or @code{REPLACE} statements;
for other statements, no implicit transaction handling is performed.
Use the @ref{2f90,,commit()} and @ref{2fc0,,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 @code{isolation_level} attribute.

If @ref{2f9d,,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{2fca,,in_transaction} attribute.

The @ref{2fc4,,executescript()} method implicitly commits
any pending transaction before execution of the given SQL script,
regardless of the value of @ref{2f9d,,isolation_level}.


Άλλαξε στην έκδοση 3.6: @code{sqlite3} used to implicitly commit an open transaction before DDL
statements.  This is no longer the case.



Άλλαξε στην έκδοση 3.12: The recommended way of controlling transactions is now via the
@ref{8c6,,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")

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Data Compression and Archiving,File Formats,Data Persistence,The Python Standard Library
@anchor{library/archiving doc}@anchor{2f2e}@anchor{library/archiving archiving}@anchor{2ffd}@anchor{library/archiving data-compression-and-archiving}@anchor{2ffe}@anchor{library/archiving translation-repo}@anchor{2fff}
@section Data Compression and Archiving


The modules described in this chapter support data compression with the zlib,
gzip, bzip2, lzma, and zstd algorithms, and the creation of ZIP- and tar-format
archives.  See also @ref{15bf,,Archiving operations} provided by the @ref{cd,,shutil}
module.

@menu
* The compression package:: 
* compression.zstd — Compression compatible with the Zstandard format: compression zstd — Compression compatible with the Zstandard format. 
* zlib — Compression compatible with gzip:: 
* gzip — Υποστήριξη για αρχεία gzip:: 
* bz2 — Support for bzip2 compression:: 
* lzma — Compression using the LZMA algorithm:: 
* zipfile — Work with ZIP archives:: 
* tarfile — Read and write tar archive files:: 

@end menu

@node The compression package,compression zstd — Compression compatible with the Zstandard format,,Data Compression and Archiving
@anchor{library/compression doc}@anchor{3000}@anchor{library/compression module-compression}@anchor{22}@anchor{library/compression the-compression-package}@anchor{3001}
@subsection The @code{compression} package


@geindex module; compression


Added in version 3.14.


The @code{compression} package contains the canonical compression modules
containing interfaces to several different compression algorithms. Some of
these modules have historically been available as separate modules; those will
continue to be available under their original names for compatibility reasons,
and will not be removed without a deprecation cycle. The use of modules in
@code{compression} is encouraged where practical.


@itemize *

@item 
@code{compression.bz2} – Re-exports @ref{14,,bz2}

@item 
@code{compression.gzip} – Re-exports @ref{6a,,gzip}

@item 
@code{compression.lzma} – Re-exports @ref{8d,,lzma}

@item 
@code{compression.zlib} – Re-exports @ref{13c,,zlib}

@item 
@ref{23,,compression.zstd} – Wrapper for the Zstandard compression library
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node compression zstd — Compression compatible with the Zstandard format,zlib — Compression compatible with gzip,The compression package,Data Compression and Archiving
@anchor{library/compression zstd doc}@anchor{3002}@anchor{library/compression zstd compression-zstd-compression-compatible-with-the-zstandard-format}@anchor{3003}@anchor{library/compression zstd module-compression zstd}@anchor{23}@anchor{library/compression zstd translation-repo}@anchor{3004}
@subsection @code{compression.zstd} — Compression compatible with the Zstandard format


@geindex module; compression.zstd


Added in version 3.14.


`Source code:' Lib/compression/zstd/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/compression/zstd/__init__.py}


__________________________________________________________________


This module provides classes and functions for compressing and decompressing
data using the Zstandard (or `zstd') compression algorithm. The
zstd manual@footnote{https://facebook.github.io/zstd/doc/api_manual_latest.html}
describes Zstandard as «a fast lossless compression algorithm, targeting
real-time compression scenarios at zlib-level and better compression ratios.»
Also included is a file interface that supports reading and writing the
contents of @code{.zst} files created by the @code{zstd} utility, as well as
raw zstd compressed streams.

The @code{compression.zstd} module contains:


@itemize *

@item 
The @ref{3005,,open()} function and @ref{3006,,ZstdFile} class for reading and
writing compressed files.

@item 
The @ref{3007,,ZstdCompressor} and @ref{190b,,ZstdDecompressor} classes for
incremental (de)compression.

@item 
The @ref{3008,,compress()} and @ref{3009,,decompress()} functions for one-shot
(de)compression.

@item 
The @ref{300a,,train_dict()} and @ref{300b,,finalize_dict()} functions and the
@ref{300c,,ZstdDict} class to train and manage Zstandard dictionaries.

@item 
The @ref{300d,,CompressionParameter}, @ref{300e,,DecompressionParameter}, and
@ref{300f,,Strategy} classes for setting advanced (de)compression parameters.
@end itemize

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile

@menu
* Exceptions: Exceptions<7>. 
* Reading and writing compressed files:: 
* Compressing and decompressing data in memory:: 
* Zstandard dictionaries:: 
* Advanced parameter control:: 
* Miscellaneous:: 
* Examples: Examples<6>. 

@end menu

@node Exceptions<7>,Reading and writing compressed files,,compression zstd — Compression compatible with the Zstandard format
@anchor{library/compression zstd exceptions}@anchor{3010}
@subsubsection Exceptions


@geindex ZstdError
@anchor{library/compression zstd compression zstd ZstdError}@anchor{3011}
@deffn {Εξαίρεση} compression.zstd.ZstdError

This exception is raised when an error occurs during compression or
decompression, or while initializing the (de)compressor state.
@end deffn

@node Reading and writing compressed files,Compressing and decompressing data in memory,Exceptions<7>,compression zstd — Compression compatible with the Zstandard format
@anchor{library/compression zstd reading-and-writing-compressed-files}@anchor{3012}
@subsubsection Reading and writing compressed files


@geindex open() (στη μονάδα compression.zstd)
@anchor{library/compression zstd compression zstd open}@anchor{3005}
@deffn {Συνάρτηση} compression.zstd.open (file, /, mode='rb', *, level=None, options=None, zstd_dict=None, encoding=None, errors=None, newline=None)

Open a Zstandard-compressed file in binary or text mode, returning a
@ref{156c,,file object}.

The `file' argument can be either a file name (given as a
@ref{1df,,str}, @ref{1c7,,bytes} or @ref{79f,,path-like}
object), in which case the named file is opened, or it can be an existing
file object to read from or write to.

The mode argument can be either @code{'rb'} for reading (default), @code{'wb'} for
overwriting, @code{'ab'} for appending, or @code{'xb'} for exclusive creation.
These can equivalently be given as @code{'r'}, @code{'w'}, @code{'a'}, and @code{'x'}
respectively. You may also open in text mode with @code{'rt'}, @code{'wt'},
@code{'at'}, and @code{'xt'} respectively.

When reading, the `options' argument can be a dictionary providing advanced
decompression parameters; see @ref{300e,,DecompressionParameter} for detailed
information about supported
parameters. The `zstd_dict' argument is a @ref{300c,,ZstdDict} instance to be
used during decompression. When reading, if the `level'
argument is not None, a @code{TypeError} will be raised.

When writing, the `options' argument can be a dictionary
providing advanced compression parameters; see
@ref{300d,,CompressionParameter} for detailed information about supported
parameters. The `level' argument is the compression level to use when
writing compressed data. Only one of `level' or `options' may be non-None.
The `zstd_dict' argument is a @ref{300c,,ZstdDict} instance to be used during
compression.

In binary mode, this function is equivalent to the @ref{3006,,ZstdFile}
constructor: @code{ZstdFile(file, mode, ...)}. In this case, the
`encoding', `errors', and `newline' parameters must not be provided.

In text mode, a @ref{3006,,ZstdFile} object is created, and wrapped in an
@ref{b9c,,io.TextIOWrapper} instance with the specified encoding, error
handling behavior, and line endings.
@end deffn

@geindex ZstdFile (κλάση σε compression.zstd)
@anchor{library/compression zstd compression zstd ZstdFile}@anchor{3006}
@deffn {Κλάση} compression.zstd.ZstdFile (file, /, mode='rb', *, level=None, options=None, zstd_dict=None)

Open a Zstandard-compressed file in binary mode.

A @code{ZstdFile} can wrap an already-open @ref{156c,,file object}, or operate
directly on a named file. The `file' argument specifies either the file
object to wrap, or the name of the file to open (as a @ref{1df,,str},
@ref{1c7,,bytes} or @ref{79f,,path-like} object). If
wrapping an existing file object, the wrapped file will not be closed when
the @code{ZstdFile} is closed.

The `mode' argument can be either @code{'rb'} for reading (default), @code{'wb'}
for overwriting, @code{'xb'} for exclusive creation, or @code{'ab'} for appending.
These can equivalently be given as @code{'r'}, @code{'w'}, @code{'x'} and @code{'a'}
respectively.

If `file' 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'}.

When reading, the `options' argument can be a dictionary
providing advanced decompression parameters; see
@ref{300e,,DecompressionParameter} for detailed information about supported
parameters. The `zstd_dict' argument is a @ref{300c,,ZstdDict} instance to be
used during decompression. When reading, if the `level'
argument is not None, a @code{TypeError} will be raised.

When writing, the `options' argument can be a dictionary
providing advanced compression parameters; see
@ref{300d,,CompressionParameter} for detailed information about supported
parameters. The `level' argument is the compression level to use when
writing compressed data. Only one of `level' or `options' may be passed. The
`zstd_dict' argument is a @ref{300c,,ZstdDict} instance to be used during
compression.

@code{ZstdFile} supports all the members specified by
@ref{a83,,io.BufferedIOBase}, except for @ref{3013,,detach()}
and @ref{16b5,,truncate()}.
Iteration and the @ref{20a,,with} statement are supported.

The following method and attributes are also provided:

@geindex peek() (μέθοδος της compression.zstd.ZstdFile)
@anchor{library/compression zstd compression zstd ZstdFile peek}@anchor{3014}
@deffn {Μέθοδος} peek (size=-1)

Return buffered data without advancing the file position. At least one
byte of data will be returned, unless EOF has been reached. The exact
number of bytes returned is unspecified (the `size' argument is ignored).

@cartouche
@quotation Σημείωση 
While calling @code{peek()} does not change the file position of
the @code{ZstdFile}, it may change the position of the underlying
file object (for example, if the @code{ZstdFile} was constructed by
passing a file object for `file').
@end quotation
@end cartouche
@end deffn

@geindex mode (ιδιότητα της compression.zstd.ZstdFile)
@anchor{library/compression zstd compression zstd ZstdFile mode}@anchor{3015}
@deffn {Ιδιότητα} mode

@code{'rb'} for reading and @code{'wb'} for writing.
@end deffn

@geindex name (ιδιότητα της compression.zstd.ZstdFile)
@anchor{library/compression zstd compression zstd ZstdFile name}@anchor{3016}
@deffn {Ιδιότητα} name

The name of the Zstandard file. Equivalent to the @ref{3017,,name}
attribute of the underlying @ref{156c,,file object}.
@end deffn
@end deffn

@node Compressing and decompressing data in memory,Zstandard dictionaries,Reading and writing compressed files,compression zstd — Compression compatible with the Zstandard format
@anchor{library/compression zstd compressing-and-decompressing-data-in-memory}@anchor{3018}
@subsubsection Compressing and decompressing data in memory


@geindex compress() (στη μονάδα compression.zstd)
@anchor{library/compression zstd compression zstd compress}@anchor{3008}
@deffn {Συνάρτηση} compression.zstd.compress (data, level=None, options=None, zstd_dict=None)

Compress `data' (a @ref{436,,bytes-like object}), returning the compressed
data as a @ref{1c7,,bytes} object.

The `level' argument is an integer controlling the level of
compression. `level' is an alternative to setting
@ref{3019,,CompressionParameter.compression_level} in `options'. Use
@ref{301a,,bounds()} on
@code{compression_level} to get the values that can
be passed for `level'. If advanced compression options are needed, the
`level' argument must be omitted and in the `options' dictionary the
@code{CompressionParameter.compression_level} parameter should be set.

The `options' argument is a Python dictionary containing advanced
compression parameters. The valid keys and values for compression parameters
are documented as part of the @ref{300d,,CompressionParameter} documentation.

The `zstd_dict' argument is an instance of @ref{300c,,ZstdDict}
containing trained data to improve compression efficiency. The
function @ref{300a,,train_dict()} can be used to generate a Zstandard dictionary.
@end deffn

@geindex decompress() (στη μονάδα compression.zstd)
@anchor{library/compression zstd compression zstd decompress}@anchor{3009}
@deffn {Συνάρτηση} compression.zstd.decompress (data, zstd_dict=None, options=None)

Decompress `data' (a @ref{436,,bytes-like object}), returning the uncompressed
data as a @ref{1c7,,bytes} object.

The `options' argument is a Python dictionary containing advanced
decompression parameters. The valid keys and values for compression
parameters are documented as part of the @ref{300e,,DecompressionParameter}
documentation.

The `zstd_dict' argument is an instance of @ref{300c,,ZstdDict}
containing trained data used during compression. This must be
the same Zstandard dictionary used during compression.

If `data' is the concatenation of multiple distinct compressed frames,
decompress all of these frames, and return the concatenation of the results.
@end deffn

@geindex ZstdCompressor (κλάση σε compression.zstd)
@anchor{library/compression zstd compression zstd ZstdCompressor}@anchor{3007}
@deffn {Κλάση} compression.zstd.ZstdCompressor (level=None, options=None, zstd_dict=None)

Create a compressor object, which can be used to compress data
incrementally.

For a more convenient way of compressing a single chunk of data, see the
module-level function @ref{3008,,compress()}.

The `level' argument is an integer controlling the level of
compression. `level' is an alternative to setting
@ref{3019,,CompressionParameter.compression_level} in `options'. Use
@ref{301a,,bounds()} on
@code{compression_level} to get the values that can
be passed for `level'. If advanced compression options are needed, the
`level' argument must be omitted and in the `options' dictionary the
@code{CompressionParameter.compression_level} parameter should be set.

The `options' argument is a Python dictionary containing advanced
compression parameters. The valid keys and values for compression parameters
are documented as part of the @ref{300d,,CompressionParameter} documentation.

The `zstd_dict' argument is an optional instance of @ref{300c,,ZstdDict}
containing trained data to improve compression efficiency. The
function @ref{300a,,train_dict()} can be used to generate a Zstandard dictionary.

@geindex compress() (μέθοδος της compression.zstd.ZstdCompressor)
@anchor{library/compression zstd compression zstd ZstdCompressor compress}@anchor{301b}
@deffn {Μέθοδος} compress (data, mode=ZstdCompressor.CONTINUE)

Compress `data' (a @ref{436,,bytes-like object}), returning a @ref{1c7,,bytes}
object with compressed data if possible, or otherwise an empty
@code{bytes} object. Some of `data' may be buffered internally, for
use in later calls to @code{compress()} and @ref{301c,,flush()}. The returned
data should be concatenated with the output of any previous calls to
@code{compress()}.

The `mode' argument is a @code{ZstdCompressor} attribute, either
@ref{301d,,CONTINUE}, @ref{301e,,FLUSH_BLOCK},
or @ref{301f,,FLUSH_FRAME}.

When all data has been provided to the compressor, call the
@ref{301c,,flush()} method to finish the compression process. If
@code{compress()} is called with `mode' set to @ref{301f,,FLUSH_FRAME},
@code{flush()} should not be called, as it would write out a new empty
frame.
@end deffn

@geindex flush() (μέθοδος της compression.zstd.ZstdCompressor)
@anchor{library/compression zstd compression zstd ZstdCompressor flush}@anchor{301c}
@deffn {Μέθοδος} flush (mode=ZstdCompressor.FLUSH_FRAME)

Finish the compression process, returning a @ref{1c7,,bytes} object
containing any data stored in the compressor’s internal buffers.

The `mode' argument is a @code{ZstdCompressor} attribute, either
@ref{301e,,FLUSH_BLOCK}, or @ref{301f,,FLUSH_FRAME}.
@end deffn

@geindex set_pledged_input_size() (μέθοδος της compression.zstd.ZstdCompressor)
@anchor{library/compression zstd compression zstd ZstdCompressor set_pledged_input_size}@anchor{3020}
@deffn {Μέθοδος} set_pledged_input_size (size)

Specify the amount of uncompressed data `size' that will be provided for
the next frame. `size' will be written into the frame header of the next
frame unless @ref{3021,,CompressionParameter.content_size_flag} is @code{False}
or @code{0}. A size of @code{0} means that the frame is empty. If `size' is
@code{None}, the frame header will omit the frame size. Frames that include
the uncompressed data size require less memory to decompress, especially
at higher compression levels.

If @ref{3022,,last_mode} is not @ref{301f,,FLUSH_FRAME}, a
@ref{277,,ValueError} is raised as the compressor is not at the start of
a frame. If the pledged size does not match the actual size of data
provided to @ref{301b,,compress()}, future calls to @code{compress()} or
@ref{301c,,flush()} may raise @ref{3011,,ZstdError} and the last chunk of data may
be lost.

After @ref{301c,,flush()} or @ref{301b,,compress()} are called with mode
@ref{301f,,FLUSH_FRAME}, the next frame will not include the frame size into
the header unless @code{set_pledged_input_size()} is called again.
@end deffn

@geindex CONTINUE (ιδιότητα της compression.zstd.ZstdCompressor)
@anchor{library/compression zstd compression zstd ZstdCompressor CONTINUE}@anchor{301d}
@deffn {Ιδιότητα} CONTINUE

Collect more data for compression, which may or may not generate output
immediately. This mode optimizes the compression ratio by maximizing the
amount of data per block and frame.
@end deffn

@geindex FLUSH_BLOCK (ιδιότητα της compression.zstd.ZstdCompressor)
@anchor{library/compression zstd compression zstd ZstdCompressor FLUSH_BLOCK}@anchor{301e}
@deffn {Ιδιότητα} FLUSH_BLOCK

Complete and write a block to the data stream. The data returned so far
can be immediately decompressed. Past data can still be referenced in
future blocks generated by calls to @ref{301b,,compress()},
improving compression.
@end deffn

@geindex FLUSH_FRAME (ιδιότητα της compression.zstd.ZstdCompressor)
@anchor{library/compression zstd compression zstd ZstdCompressor FLUSH_FRAME}@anchor{301f}
@deffn {Ιδιότητα} FLUSH_FRAME

Complete and write out a frame. Future data provided to
@ref{301b,,compress()} will be written into a new frame and
`cannot' reference past data.
@end deffn

@geindex last_mode (ιδιότητα της compression.zstd.ZstdCompressor)
@anchor{library/compression zstd compression zstd ZstdCompressor last_mode}@anchor{3022}
@deffn {Ιδιότητα} last_mode

The last mode passed to either @ref{301b,,compress()} or @ref{301c,,flush()}.
The value can be one of @ref{301d,,CONTINUE}, @ref{301e,,FLUSH_BLOCK}, or
@ref{301f,,FLUSH_FRAME}. The initial value is @code{FLUSH_FRAME},
signifying that the compressor is at the start of a new frame.
@end deffn
@end deffn

@geindex ZstdDecompressor (κλάση σε compression.zstd)
@anchor{library/compression zstd compression zstd ZstdDecompressor}@anchor{190b}
@deffn {Κλάση} compression.zstd.ZstdDecompressor (zstd_dict=None, options=None)

Create a decompressor object, which can be used to decompress data
incrementally.

For a more convenient way of decompressing an entire compressed stream at
once, see the module-level function @ref{3009,,decompress()}.

The `options' argument is a Python dictionary containing advanced
decompression parameters. The valid keys and values for compression
parameters are documented as part of the @ref{300e,,DecompressionParameter}
documentation.

The `zstd_dict' argument is an instance of @ref{300c,,ZstdDict}
containing trained data used during compression. This must be
the same Zstandard dictionary used during compression.

@cartouche
@quotation Σημείωση 
This class does not transparently handle inputs containing multiple
compressed frames, unlike the @ref{3009,,decompress()} function and
@ref{3006,,ZstdFile} class. To decompress a multi-frame input, you should
use @code{decompress()}, @code{ZstdFile} if working with a
@ref{156c,,file object}, or multiple @code{ZstdDecompressor} instances.
@end quotation
@end cartouche

@geindex decompress() (μέθοδος της compression.zstd.ZstdDecompressor)
@anchor{library/compression zstd compression zstd ZstdDecompressor decompress}@anchor{3023}
@deffn {Μέθοδος} decompress (data, max_length=-1)

Decompress `data' (a @ref{436,,bytes-like object}), returning
uncompressed data as bytes. Some of `data' may be buffered
internally, for use in later calls to @code{decompress()}.
The returned data should be concatenated with the output of any previous
calls to @code{decompress()}.

If `max_length' is non-negative, the method returns at most `max_length'
bytes of decompressed data. If this limit is reached and further
output can be produced (or EOF is reached), the @ref{3024,,needs_input}
attribute will be set to @code{False}. In this case, the next call to
@code{decompress()} may provide `data' as @code{b'@w{'}} to obtain
more of the output. The full content can thus be read like:

@example
process_output(d.decompress(data, max_length))
while not d.eof and not d.needs_input:
    process_output(d.decompress(b"", max_length))
@end example

If all of the input data was decompressed and returned (either
because this was less than `max_length' bytes, or because
`max_length' was negative), the @ref{3024,,needs_input} attribute
will be set to @code{True}.

Attempting to decompress data after the end of a frame will raise a
@ref{3011,,ZstdError}. Any data found after the end of the frame is ignored
and saved in the @ref{3025,,unused_data} attribute.
@end deffn

@geindex eof (ιδιότητα της compression.zstd.ZstdDecompressor)
@anchor{library/compression zstd compression zstd ZstdDecompressor eof}@anchor{3026}
@deffn {Ιδιότητα} eof

@code{True} if the end-of-stream marker has been reached.
@end deffn

@geindex unused_data (ιδιότητα της compression.zstd.ZstdDecompressor)
@anchor{library/compression zstd compression zstd ZstdDecompressor unused_data}@anchor{3025}
@deffn {Ιδιότητα} unused_data

Data found after the end of the compressed stream.

Before the end of the stream is reached, this will be @code{b'@w{'}}.
@end deffn

@geindex needs_input (ιδιότητα της compression.zstd.ZstdDecompressor)
@anchor{library/compression zstd compression zstd ZstdDecompressor needs_input}@anchor{3024}
@deffn {Ιδιότητα} needs_input

@code{False} if the @ref{3023,,decompress()} method can provide more
decompressed data before requiring new compressed input.
@end deffn
@end deffn

@node Zstandard dictionaries,Advanced parameter control,Compressing and decompressing data in memory,compression zstd — Compression compatible with the Zstandard format
@anchor{library/compression zstd zstandard-dictionaries}@anchor{3027}
@subsubsection Zstandard dictionaries


@geindex train_dict() (στη μονάδα compression.zstd)
@anchor{library/compression zstd compression zstd train_dict}@anchor{300a}
@deffn {Συνάρτηση} compression.zstd.train_dict (samples, dict_size)

Train a Zstandard dictionary, returning a @ref{300c,,ZstdDict} instance.
Zstandard dictionaries enable more efficient compression of smaller sizes
of data, which is traditionally difficult to compress due to less
repetition. If you are compressing multiple similar groups of data (such as
similar files), Zstandard dictionaries can improve compression ratios and
speed significantly.

The `samples' argument (an iterable of @ref{1c7,,bytes} objects), is the
population of samples used to train the Zstandard dictionary.

The `dict_size' argument, an integer, is the maximum size (in bytes) the
Zstandard dictionary should be. The Zstandard documentation suggests an
absolute maximum of no more than 100 KB, but the maximum can often be smaller
depending on the data. Larger dictionaries generally slow down compression,
but improve compression ratios. Smaller dictionaries lead to faster
compression, but reduce the compression ratio.
@end deffn

@geindex finalize_dict() (στη μονάδα compression.zstd)
@anchor{library/compression zstd compression zstd finalize_dict}@anchor{300b}
@deffn {Συνάρτηση} compression.zstd.finalize_dict (zstd_dict, /, samples, dict_size, level)

An advanced function for converting a «raw content» Zstandard dictionary into
a regular Zstandard dictionary. «Raw content» dictionaries are a sequence of
bytes that do not need to follow the structure of a normal Zstandard
dictionary.

The `zstd_dict' argument is a @ref{300c,,ZstdDict} instance with
the @ref{3028,,dict_content} containing the raw dictionary contents.

The `samples' argument (an iterable of @ref{1c7,,bytes} objects), contains
sample data for generating the Zstandard dictionary.

The `dict_size' argument, an integer, is the maximum size (in bytes) the
Zstandard dictionary should be. See @ref{300a,,train_dict()} for
suggestions on the maximum dictionary size.

The `level' argument (an integer) is the compression level expected to be
passed to the compressors using this dictionary. The dictionary information
varies for each compression level, so tuning for the proper compression
level can make compression more efficient.
@end deffn

@geindex ZstdDict (κλάση σε compression.zstd)
@anchor{library/compression zstd compression zstd ZstdDict}@anchor{300c}
@deffn {Κλάση} compression.zstd.ZstdDict (dict_content, /, *, is_raw=False)

A wrapper around Zstandard dictionaries. Dictionaries can be used to improve
the compression of many small chunks of data. Use @ref{300a,,train_dict()} if you
need to train a new dictionary from sample data.

The `dict_content' argument (a @ref{436,,bytes-like object}), is the already
trained dictionary information.

The `is_raw' argument, a boolean, is an advanced parameter controlling the
meaning of `dict_content'. @code{True} means `dict_content' is a «raw content»
dictionary, without any format restrictions. @code{False} means `dict_content'
is an ordinary Zstandard dictionary, created from Zstandard functions,
for example, @ref{300a,,train_dict()} or the external @code{zstd} CLI.

When passing a @code{ZstdDict} to a function, the
@code{as_digested_dict} and @code{as_undigested_dict} attributes can
control how the dictionary is loaded by passing them as the @code{zstd_dict}
argument, for example, @code{compress(data, zstd_dict=zd.as_digested_dict)}.
Digesting a dictionary is a costly operation that occurs when loading a
Zstandard dictionary. When making multiple calls to compression or
decompression, passing a digested dictionary will reduce the overhead of
loading the dictionary.

@quotation
Difference for compression



@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 
@headitem

@tab

Digested dictionary

@tab

Undigested dictionary

@item

Advanced parameters of the compressor which may be overridden by
the dictionary’s parameters

@tab

@code{window_log}, @code{hash_log}, @code{chain_log}, @code{search_log},
@code{min_match}, @code{target_length}, @code{strategy},
@code{enable_long_distance_matching}, @code{ldm_hash_log},
@code{ldm_min_match}, @code{ldm_bucket_size_log}, @code{ldm_hash_rate_log},
and some non-public parameters.

@tab

None

@item

@code{ZstdDict} internally caches the dictionary

@tab

Yes. It’s faster when loading a digested dictionary again with the
same compression level.

@tab

No. If you wish to load an undigested dictionary multiple times,
consider reusing a compressor object.

@end multitable

@end quotation

If passing a @code{ZstdDict} without any attribute, an undigested
dictionary is passed by default when compressing and a digested dictionary
is generated if necessary and passed by default when decompressing.

@quotation

@geindex dict_content (ιδιότητα της compression.zstd.ZstdDict)
@anchor{library/compression zstd compression zstd ZstdDict dict_content}@anchor{3028}
@deffn {Ιδιότητα} dict_content

The content of the Zstandard dictionary, a @code{bytes} object. It’s the
same as the `dict_content' argument in the @code{__init__} method. It can
be used with other programs, such as the @code{zstd} CLI program.
@end deffn

@geindex dict_id (ιδιότητα της compression.zstd.ZstdDict)
@anchor{library/compression zstd compression zstd ZstdDict dict_id}@anchor{3029}
@deffn {Ιδιότητα} dict_id

Identifier of the Zstandard dictionary, a non-negative int value.

Non-zero means the dictionary is ordinary, created by Zstandard
functions and following the Zstandard format.

@code{0} means a «raw content» dictionary, free of any format restriction,
used for advanced users.

@cartouche
@quotation Σημείωση 
The meaning of @code{0} for @code{ZstdDict.dict_id} is different
from the @code{dictionary_id} attribute to the @ref{302a,,get_frame_info()}
function.
@end quotation
@end cartouche
@end deffn

@geindex as_digested_dict (ιδιότητα της compression.zstd.ZstdDict)
@anchor{library/compression zstd compression zstd ZstdDict as_digested_dict}@anchor{302b}
@deffn {Ιδιότητα} as_digested_dict

Load as a digested dictionary.
@end deffn

@geindex as_undigested_dict (ιδιότητα της compression.zstd.ZstdDict)
@anchor{library/compression zstd compression zstd ZstdDict as_undigested_dict}@anchor{302c}
@deffn {Ιδιότητα} as_undigested_dict

Load as an undigested dictionary.
@end deffn
@end quotation
@end deffn

@node Advanced parameter control,Miscellaneous,Zstandard dictionaries,compression zstd — Compression compatible with the Zstandard format
@anchor{library/compression zstd advanced-parameter-control}@anchor{302d}
@subsubsection Advanced parameter control


@geindex CompressionParameter (κλάση σε compression.zstd)
@anchor{library/compression zstd compression zstd CompressionParameter}@anchor{300d}
@deffn {Κλάση} compression.zstd.CompressionParameter

An @ref{109d,,IntEnum} containing the advanced compression parameter
keys that can be used when compressing data.

The @ref{301a,,bounds()} method can be used on any attribute to get the valid
values for that parameter.

Parameters are optional; any omitted parameter will have it’s value selected
automatically.

Example getting the lower and upper bound of @ref{3019,,compression_level}:

@example
lower, upper = CompressionParameter.compression_level.bounds()
@end example

Example setting the @ref{302e,,window_log} to the maximum size:

@example
_lower, upper = CompressionParameter.window_log.bounds()
options = @{CompressionParameter.window_log: upper@}
compress(b'venezuelan beaver cheese', options=options)
@end example

@geindex bounds() (μέθοδος της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter bounds}@anchor{301a}
@deffn {Μέθοδος} bounds ()

Return the tuple of int bounds, @code{(lower, upper)}, of a compression
parameter. This method should be called on the attribute you wish to
retrieve the bounds of. For example, to get the valid values for
@ref{3019,,compression_level}, one may check the result of
@code{CompressionParameter.compression_level.bounds()}.

Both the lower and upper bounds are inclusive.
@end deffn

@geindex compression_level (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter compression_level}@anchor{3019}
@deffn {Ιδιότητα} compression_level

A high-level means of setting other compression parameters that affect
the speed and ratio of compressing data.

Regular compression levels are greater than @code{0}. Values greater than
@code{20} are considered «ultra» compression and require more memory than
other levels. Negative values can be used to trade off faster compression
for worse compression ratios.

Setting the level to zero uses @ref{302f,,COMPRESSION_LEVEL_DEFAULT}.
@end deffn

@geindex window_log (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter window_log}@anchor{302e}
@deffn {Ιδιότητα} window_log

Maximum allowed back-reference distance the compressor can use when
compressing data, expressed as power of two, @code{1 << window_log} bytes.
This parameter greatly influences the memory usage of compression. Higher
values require more memory but gain better compression values.

A value of zero causes the value to be selected automatically.
@end deffn

@geindex hash_log (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter hash_log}@anchor{3030}
@deffn {Ιδιότητα} hash_log

Size of the initial probe table, as a power of two. The resulting memory
usage is @code{1 << (hash_log+2)} bytes. Larger tables improve compression
ratio of strategies <= @ref{3031,,dfast}, and improve compression
speed of strategies > @code{dfast}.

A value of zero causes the value to be selected automatically.
@end deffn

@geindex chain_log (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter chain_log}@anchor{3032}
@deffn {Ιδιότητα} chain_log

Size of the multi-probe search table, as a power of two. The resulting
memory usage is @code{1 << (chain_log+2)} bytes. Larger tables result in
better and slower compression. This parameter has no effect for the
@ref{3033,,fast} strategy. It’s still useful when using
@ref{3031,,dfast} strategy, in which case it defines a secondary
probe table.

A value of zero causes the value to be selected automatically.
@end deffn

@geindex search_log (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter search_log}@anchor{3034}
@deffn {Ιδιότητα} search_log

Number of search attempts, as a power of two. More attempts result in
better and slower compression. This parameter is useless for
@ref{3033,,fast} and @ref{3031,,dfast} strategies.

A value of zero causes the value to be selected automatically.
@end deffn

@geindex min_match (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter min_match}@anchor{3035}
@deffn {Ιδιότητα} min_match

Minimum size of searched matches. Larger values increase compression and
decompression speed, but decrease ratio. Note that Zstandard can still
find matches of smaller size, it just tweaks its search algorithm to look
for this size and larger. For all strategies < @ref{3036,,btopt},
the effective minimum is @code{4}; for all strategies
> @ref{3033,,fast}, the effective maximum is @code{6}.

A value of zero causes the value to be selected automatically.
@end deffn

@geindex target_length (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter target_length}@anchor{3037}
@deffn {Ιδιότητα} target_length

The impact of this field depends on the selected @ref{300f,,Strategy}.

For strategies @ref{3036,,btopt}, @ref{3038,,btultra} and
@ref{3039,,btultra2}, the value is the length of a match
considered «good enough» to stop searching. Larger values make
compression ratios better, but compresses slower.

For strategy @ref{3033,,fast}, it is the distance between match
sampling. Larger values make compression faster, but with a worse
compression ratio.

A value of zero causes the value to be selected automatically.
@end deffn

@geindex strategy (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter strategy}@anchor{303a}
@deffn {Ιδιότητα} strategy

The higher the value of selected strategy, the more complex the
compression technique used by zstd, resulting in higher compression
ratios but slower compression.


@subsubheading Δείτε επίσης


@ref{300f,,Strategy}

@end deffn

@geindex enable_long_distance_matching (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter enable_long_distance_matching}@anchor{303b}
@deffn {Ιδιότητα} enable_long_distance_matching

Long distance matching can be used to improve compression for large
inputs by finding large matches at greater distances. It increases memory
usage and window size.

@code{True} or @code{1} enable long distance matching while @code{False} or @code{0}
disable it.

Enabling this parameter increases default
@ref{302e,,window_log} to 128 MiB except when expressly
set to a different value. This setting is enabled by default if
@code{window_log} >= 128 MiB and the compression
strategy >= @ref{3036,,btopt} (compression level 16+).
@end deffn

@geindex ldm_hash_log (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter ldm_hash_log}@anchor{303c}
@deffn {Ιδιότητα} ldm_hash_log

Size of the table for long distance matching, as a power of two. Larger
values increase memory usage and compression ratio, but decrease
compression speed.

A value of zero causes the value to be selected automatically.
@end deffn

@geindex ldm_min_match (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter ldm_min_match}@anchor{303d}
@deffn {Ιδιότητα} ldm_min_match

Minimum match size for long distance matcher. Larger or too small values
can often decrease the compression ratio.

A value of zero causes the value to be selected automatically.
@end deffn

@geindex ldm_bucket_size_log (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter ldm_bucket_size_log}@anchor{303e}
@deffn {Ιδιότητα} ldm_bucket_size_log

Log size of each bucket in the long distance matcher hash table for
collision resolution. Larger values improve collision resolution but
decrease compression speed.

A value of zero causes the value to be selected automatically.
@end deffn

@geindex ldm_hash_rate_log (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter ldm_hash_rate_log}@anchor{303f}
@deffn {Ιδιότητα} ldm_hash_rate_log

Frequency of inserting/looking up entries into the long distance matcher
hash table. Larger values improve compression speed. Deviating far from
the default value will likely result in a compression ratio decrease.

A value of zero causes the value to be selected automatically.
@end deffn

@geindex content_size_flag (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter content_size_flag}@anchor{3021}
@deffn {Ιδιότητα} content_size_flag

Write the size of the data to be compressed into the Zstandard frame
header when known prior to compressing.

This flag only takes effect under the following scenarios:


@itemize *

@item 
Calling @ref{3008,,compress()} for one-shot compression

@item 
Providing all of the data to be compressed in the frame in a single
@ref{301b,,ZstdCompressor.compress()} call, with the
@ref{301f,,ZstdCompressor.FLUSH_FRAME} mode.

@item 
Calling @ref{3020,,ZstdCompressor.set_pledged_input_size()} with the exact
amount of data that will be provided to the compressor prior to any
calls to @ref{301b,,ZstdCompressor.compress()} for the current frame.
@code{ZstdCompressor.set_pledged_input_size()} must be called for each
new frame.
@end itemize

All other compression calls may not write the size information into the
frame header.

@code{True} or @code{1} enable the content size flag while @code{False} or @code{0}
disable it.
@end deffn

@geindex checksum_flag (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter checksum_flag}@anchor{3040}
@deffn {Ιδιότητα} checksum_flag

A four-byte checksum using XXHash64 of the uncompressed content is
written at the end of each frame. Zstandard’s decompression code verifies
the checksum. If there is a mismatch a @ref{3011,,ZstdError} exception is
raised.

@code{True} or @code{1} enable checksum generation while @code{False} or @code{0}
disable it.
@end deffn

@geindex dict_id_flag (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter dict_id_flag}@anchor{3041}
@deffn {Ιδιότητα} dict_id_flag

When compressing with a @ref{300c,,ZstdDict}, the dictionary’s ID is written
into the frame header.

@code{True} or @code{1} enable storing the dictionary ID while @code{False} or
@code{0} disable it.
@end deffn

@geindex nb_workers (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter nb_workers}@anchor{3042}
@deffn {Ιδιότητα} nb_workers

Select how many threads will be spawned to compress in parallel. When
@code{nb_workers} > 0, enables multi-threaded compression, a value of
@code{1} means «one-thread multi-threaded mode». More workers improve speed,
but also increase memory usage and slightly reduce compression ratio.

A value of zero disables multi-threading.
@end deffn

@geindex job_size (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter job_size}@anchor{3043}
@deffn {Ιδιότητα} job_size

Size of a compression job, in bytes. This value is enforced only when
@ref{3042,,nb_workers} >= 1. Each compression job is
completed in parallel, so this value can indirectly impact the number of
active threads.

A value of zero causes the value to be selected automatically.
@end deffn

@geindex overlap_log (ιδιότητα της compression.zstd.CompressionParameter)
@anchor{library/compression zstd compression zstd CompressionParameter overlap_log}@anchor{3044}
@deffn {Ιδιότητα} overlap_log

Sets how much data is reloaded from previous jobs (threads) for new jobs
to be used by the look behind window during compression. This value is
only used when @ref{3042,,nb_workers} >= 1. Acceptable
values vary from 0 to 9.

@quotation


@itemize *

@item 
0 means dynamically set the overlap amount

@item 
1 means no overlap

@item 
9 means use a full window size from the previous job
@end itemize
@end quotation

Each increment halves/doubles the overlap size. «8» means an overlap of
@code{window_size/2}, «7» means an overlap of @code{window_size/4}, etc.
@end deffn
@end deffn

@geindex DecompressionParameter (κλάση σε compression.zstd)
@anchor{library/compression zstd compression zstd DecompressionParameter}@anchor{300e}
@deffn {Κλάση} compression.zstd.DecompressionParameter

An @ref{109d,,IntEnum} containing the advanced decompression parameter
keys that can be used when decompressing data. Parameters are optional; any
omitted parameter will have it’s value selected automatically.

The @ref{3045,,bounds()} method can be used on any attribute to get the valid
values for that parameter.

Example setting the @ref{3046,,window_log_max} to the maximum size:

@example
data = compress(b'Some very long buffer of bytes...')

_lower, upper = DecompressionParameter.window_log_max.bounds()

options = @{DecompressionParameter.window_log_max: upper@}
decompress(data, options=options)
@end example

@geindex bounds() (μέθοδος της compression.zstd.DecompressionParameter)
@anchor{library/compression zstd compression zstd DecompressionParameter bounds}@anchor{3045}
@deffn {Μέθοδος} bounds ()

Return the tuple of int bounds, @code{(lower, upper)}, of a decompression
parameter. This method should be called on the attribute you wish to
retrieve the bounds of.

Both the lower and upper bounds are inclusive.
@end deffn

@geindex window_log_max (ιδιότητα της compression.zstd.DecompressionParameter)
@anchor{library/compression zstd compression zstd DecompressionParameter window_log_max}@anchor{3046}
@deffn {Ιδιότητα} window_log_max

The base-two logarithm of the maximum size of the window used during
decompression. This can be useful to limit the amount of memory used when
decompressing data. A larger maximum window size leads to faster
decompression.

A value of zero causes the value to be selected automatically.
@end deffn
@end deffn

@geindex Strategy (κλάση σε compression.zstd)
@anchor{library/compression zstd compression zstd Strategy}@anchor{300f}
@deffn {Κλάση} compression.zstd.Strategy

An @ref{109d,,IntEnum} containing strategies for compression.
Higher-numbered strategies correspond to more complex and slower
compression.

@cartouche
@quotation Σημείωση 
The values of attributes of @code{Strategy} are not necessarily stable
across zstd versions. Only the ordering of the attributes may be relied
upon. The attributes are listed below in order.
@end quotation
@end cartouche

The following strategies are available:

@geindex fast (ιδιότητα της compression.zstd.Strategy)
@anchor{library/compression zstd compression zstd Strategy fast}@anchor{3033}
@deffn {Ιδιότητα} fast
@end deffn

@geindex dfast (ιδιότητα της compression.zstd.Strategy)
@anchor{library/compression zstd compression zstd Strategy dfast}@anchor{3031}
@deffn {Ιδιότητα} dfast
@end deffn

@geindex greedy (ιδιότητα της compression.zstd.Strategy)
@anchor{library/compression zstd compression zstd Strategy greedy}@anchor{3047}
@deffn {Ιδιότητα} greedy
@end deffn

@geindex lazy (ιδιότητα της compression.zstd.Strategy)
@anchor{library/compression zstd compression zstd Strategy lazy}@anchor{3048}
@deffn {Ιδιότητα} lazy
@end deffn

@geindex lazy2 (ιδιότητα της compression.zstd.Strategy)
@anchor{library/compression zstd compression zstd Strategy lazy2}@anchor{3049}
@deffn {Ιδιότητα} lazy2
@end deffn

@geindex btlazy2 (ιδιότητα της compression.zstd.Strategy)
@anchor{library/compression zstd compression zstd Strategy btlazy2}@anchor{304a}
@deffn {Ιδιότητα} btlazy2
@end deffn

@geindex btopt (ιδιότητα της compression.zstd.Strategy)
@anchor{library/compression zstd compression zstd Strategy btopt}@anchor{3036}
@deffn {Ιδιότητα} btopt
@end deffn

@geindex btultra (ιδιότητα της compression.zstd.Strategy)
@anchor{library/compression zstd compression zstd Strategy btultra}@anchor{3038}
@deffn {Ιδιότητα} btultra
@end deffn

@geindex btultra2 (ιδιότητα της compression.zstd.Strategy)
@anchor{library/compression zstd compression zstd Strategy btultra2}@anchor{3039}
@deffn {Ιδιότητα} btultra2
@end deffn
@end deffn

@node Miscellaneous,Examples<6>,Advanced parameter control,compression zstd — Compression compatible with the Zstandard format
@anchor{library/compression zstd miscellaneous}@anchor{304b}
@subsubsection Miscellaneous


@geindex get_frame_info() (στη μονάδα compression.zstd)
@anchor{library/compression zstd compression zstd get_frame_info}@anchor{302a}
@deffn {Συνάρτηση} compression.zstd.get_frame_info (frame_buffer)

Retrieve a @ref{304c,,FrameInfo} object containing metadata about a Zstandard
frame. Frames contain metadata related to the compressed data they hold.
@end deffn

@geindex FrameInfo (κλάση σε compression.zstd)
@anchor{library/compression zstd compression zstd FrameInfo}@anchor{304c}
@deffn {Κλάση} compression.zstd.FrameInfo

Metadata related to a Zstandard frame.

@geindex decompressed_size (ιδιότητα της compression.zstd.FrameInfo)
@anchor{library/compression zstd compression zstd FrameInfo decompressed_size}@anchor{304d}
@deffn {Ιδιότητα} decompressed_size

The size of the decompressed contents of the frame.
@end deffn

@geindex dictionary_id (ιδιότητα της compression.zstd.FrameInfo)
@anchor{library/compression zstd compression zstd FrameInfo dictionary_id}@anchor{304e}
@deffn {Ιδιότητα} dictionary_id

An integer representing the Zstandard dictionary ID needed for
decompressing the frame. @code{0} means the dictionary ID was not
recorded in the frame header. This may mean that a Zstandard dictionary
is not needed, or that the ID of a required dictionary was not recorded.
@end deffn
@end deffn

@geindex COMPRESSION_LEVEL_DEFAULT (στη μονάδα compression.zstd)
@anchor{library/compression zstd compression zstd COMPRESSION_LEVEL_DEFAULT}@anchor{302f}
@deffn {Ιδιότητα} compression.zstd.COMPRESSION_LEVEL_DEFAULT

The default compression level for Zstandard: @code{3}.
@end deffn

@geindex zstd_version_info (στη μονάδα compression.zstd)
@anchor{library/compression zstd compression zstd zstd_version_info}@anchor{304f}
@deffn {Ιδιότητα} compression.zstd.zstd_version_info

Version number of the runtime zstd library as a tuple of integers
(major, minor, release).
@end deffn

@node Examples<6>,,Miscellaneous,compression zstd — Compression compatible with the Zstandard format
@anchor{library/compression zstd examples}@anchor{3050}
@subsubsection Examples


Reading in a compressed file:

@example
from compression import zstd

with zstd.open("file.zst") as f:
    file_content = f.read()
@end example

Creating a compressed file:

@example
from compression import zstd

data = b"Insert Data Here"
with zstd.open("file.zst", "w") as f:
    f.write(data)
@end example

Compressing data in memory:

@example
from compression import zstd

data_in = b"Insert Data Here"
data_out = zstd.compress(data_in)
@end example

Incremental compression:

@example
from compression import zstd

comp = zstd.ZstdCompressor()
out1 = comp.compress(b"Some data\n")
out2 = comp.compress(b"Another piece of data\n")
out3 = comp.compress(b"Even more data\n")
out4 = comp.flush()
# Concatenate all the partial results:
result = b"".join([out1, out2, out3, out4])
@end example

Writing compressed data to an already-open file:

@example
from compression import zstd

with open("myfile", "wb") as f:
    f.write(b"This data will not be compressed\n")
    with zstd.open(f, "w") as zstf:
        zstf.write(b"This *will* be compressed\n")
    f.write(b"Not compressed\n")
@end example

Creating a compressed file using compression parameters:

@example
from compression import zstd

options = @{
   zstd.CompressionParameter.checksum_flag: 1
@}
with zstd.open("file.zst", "w", options=options) as f:
    f.write(b"Mind if I squeeze in?")
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node zlib — Compression compatible with gzip,gzip — Υποστήριξη για αρχεία gzip,compression zstd — Compression compatible with the Zstandard format,Data Compression and Archiving
@anchor{library/zlib doc}@anchor{3051}@anchor{library/zlib module-zlib}@anchor{13c}@anchor{library/zlib translation-repo}@anchor{3052}@anchor{library/zlib zlib-compression-compatible-with-gzip}@anchor{3053}
@subsection @code{zlib} — Compression compatible with @code{gzip}


@geindex module; zlib


__________________________________________________________________


For applications that require data compression, the functions in this module
allow compression and decompression, using the zlib library@footnote{https://www.zlib.net}.

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile

zlib’s functions have many options and often need to be used in a particular
order.  This documentation doesn’t attempt to cover all of the permutations;
consult the zlib manual@footnote{https://www.zlib.net/manual.html} for authoritative
information.

For reading and writing @code{.gz} files see the @ref{6a,,gzip} module.

The available exception and functions in this module are:

@geindex error
@anchor{library/zlib zlib error}@anchor{3054}
@deffn {Εξαίρεση} zlib.error

Exception raised on compression and decompression errors.
@end deffn

@geindex adler32() (στη μονάδα zlib)
@anchor{library/zlib zlib adler32}@anchor{1db4}
@deffn {Συνάρτηση} zlib.adler32 (data[, value])

Computes an Adler-32 checksum of `data'.  (An Adler-32 checksum is almost as
reliable as a CRC32 but can be computed much more quickly.)  The result
is an unsigned 32-bit integer.  If `value' is present, it is used as
the starting value of the checksum; otherwise, a default value of 1
is used.  Passing in `value' allows computing a running checksum over the
concatenation of several inputs.  The algorithm is not cryptographically
strong, and should not be used for authentication or digital signatures.  Since
the algorithm is designed for use as a checksum algorithm, it is not suitable
for use as a general hash algorithm.


Άλλαξε στην έκδοση 3.0: The result is always unsigned.

@end deffn

@geindex adler32_combine() (στη μονάδα zlib)
@anchor{library/zlib zlib adler32_combine}@anchor{2bc}
@deffn {Συνάρτηση} zlib.adler32_combine (adler1, adler2, len2, /)

Combine two Adler-32 checksums into one.

Given the Adler-32 checksum `adler1' of a sequence @code{A} and the
Adler-32 checksum `adler2' of a sequence @code{B} of length `len2',
return the Adler-32 checksum of @code{A} and @code{B} concatenated.

This function is typically useful to combine Adler-32 checksums
that were concurrently computed. To compute checksums sequentially, use
@ref{1db4,,adler32()} with the running checksum as the @code{value} argument.


Added in version 3.15.

@end deffn

@geindex compress() (στη μονάδα zlib)
@anchor{library/zlib zlib compress}@anchor{a2e}
@deffn {Συνάρτηση} zlib.compress (data, /, level=Z_DEFAULT_COMPRESSION, 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;
See @ref{3055,,Z_BEST_SPEED} (@code{1}), @ref{3056,,Z_BEST_COMPRESSION} (@code{9}),
@ref{3057,,Z_NO_COMPRESSION} (@code{0}), and the default,
@ref{3058,,Z_DEFAULT_COMPRESSION} (@code{-1}) for more information about these values.
@anchor{library/zlib compress-wbits}@anchor{3059}
The `wbits' argument controls the size of the history buffer (or the
«window size») used when compressing data, and whether a header and
trailer is included in the output.  It can take several ranges of values,
defaulting to @code{15} (@ref{305a,,MAX_WBITS}):


@itemize *

@item 
+9 to +15: The base-two logarithm of the window size, which
therefore ranges between 512 and 32768.  Larger values produce
better compression at the expense of greater memory usage.  The
resulting output will include a zlib-specific header and trailer.

@item 
−9 to −15: Uses the absolute value of `wbits' as the
window size logarithm, while producing a raw output stream with no
header or trailing checksum.

@item 
+25 to +31 = 16 + (9 to 15): Uses the low 4 bits of the value as the
window size logarithm, while including a basic @code{gzip} header
and trailing checksum in the output.
@end itemize

Raises the @ref{3054,,error} exception if any error occurs.


Άλλαξε στην έκδοση 3.6: `level' can now be used as a keyword parameter.



Άλλαξε στην έκδοση 3.11: The `wbits' parameter is now available to set window bits and
compression type.

@end deffn

@geindex compressobj() (στη μονάδα zlib)
@anchor{library/zlib zlib compressobj}@anchor{19fc}
@deffn {Συνάρτηση} zlib.compressobj (level=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

Returns a compression object, to be used for compressing data streams that won’t
fit into memory at once.

`level' is the compression level – an integer from @code{0} to @code{9} or @code{-1}.
See @ref{3055,,Z_BEST_SPEED} (@code{1}), @ref{3056,,Z_BEST_COMPRESSION} (@code{9}),
@ref{3057,,Z_NO_COMPRESSION} (@code{0}), and the default,
@ref{3058,,Z_DEFAULT_COMPRESSION} (@code{-1}) for more information about these values.

`method' is the compression algorithm. Currently, the only supported value is
@ref{305b,,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{3059,,described for compress()}.

The `memLevel' argument controls the amount of memory used for the
internal compression state. Valid values range from @code{1} to @code{9}.
Higher values use more memory, but are faster and produce smaller output.

`strategy' is used to tune the compression algorithm. Possible values are
@ref{305c,,Z_DEFAULT_STRATEGY}, @ref{305d,,Z_FILTERED}, @ref{305e,,Z_HUFFMAN_ONLY},
@ref{305f,,Z_RLE} and @ref{3060,,Z_FIXED}.

`zdict' is a predefined compression dictionary. This is a sequence of bytes
(such as a @ref{1c7,,bytes} object) containing subsequences that are expected
to occur frequently in the data that is to be compressed. Those subsequences
that are expected to be most common should come at the end of the dictionary.


Άλλαξε στην έκδοση 3.3: Added the `zdict' parameter and keyword argument support.

@end deffn

@geindex crc32() (στη μονάδα zlib)
@anchor{library/zlib zlib crc32}@anchor{1c18}
@deffn {Συνάρτηση} zlib.crc32 (data[, value])

@geindex Cyclic Redundancy Check
@geindex checksum;Cyclic Redundancy Check

Computes a CRC (Cyclic Redundancy Check) checksum of `data'. The
result is an unsigned 32-bit integer. If `value' is present, it is used
as the starting value of the checksum; otherwise, a default value of 0
is used.  Passing in `value' allows computing a running checksum over the
concatenation of several inputs.  The algorithm is not cryptographically
strong, and should not be used for authentication or digital signatures.  Since
the algorithm is designed for use as a checksum algorithm, it is not suitable
for use as a general hash algorithm.


Άλλαξε στην έκδοση 3.0: The result is always unsigned.

@end deffn

@geindex crc32_combine() (στη μονάδα zlib)
@anchor{library/zlib zlib crc32_combine}@anchor{2bd}
@deffn {Συνάρτηση} zlib.crc32_combine (crc1, crc2, len2, /)

Combine two CRC-32 checksums into one.

Given the CRC-32 checksum `crc1' of a sequence @code{A} and the
CRC-32 checksum `crc2' of a sequence @code{B} of length `len2',
return the CRC-32 checksum of @code{A} and @code{B} concatenated.

This function is typically useful to combine CRC-32 checksums
that were concurrently computed. To compute checksums sequentially, use
@ref{1c18,,crc32()} with the running checksum as the @code{value} argument.


Added in version 3.15.

@end deffn

@geindex decompress() (στη μονάδα zlib)
@anchor{library/zlib zlib decompress}@anchor{10c8}
@deffn {Συνάρτηση} zlib.decompress (data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

Decompresses the bytes in `data', returning a bytes object containing the
uncompressed data.  The `wbits' parameter depends on
the format of `data', and is discussed further below.
If `bufsize' is given, it is used as the initial size of the output
buffer.  Raises the @ref{3054,,error} exception if any error occurs.
@anchor{library/zlib decompress-wbits}@anchor{3061}
The `wbits' parameter controls the size of the history buffer
(or «window size»), and what header and trailer format is expected.
It is similar to the parameter for @ref{19fc,,compressobj()}, but accepts
more ranges of values:


@itemize *

@item 
+8 to +15: The base-two logarithm of the window size.  The input
must include a zlib header and trailer.

@item 
0: Automatically determine the window size from the zlib header.
Only supported since zlib 1.2.3.5.

@item 
−8 to −15: Uses the absolute value of `wbits' as the window size
logarithm.  The input must be a raw stream with no header or trailer.

@item 
+24 to +31 = 16 + (8 to 15): Uses the low 4 bits of the value as
the window size logarithm.  The input must include a gzip header and
trailer.

@item 
+40 to +47 = 32 + (8 to 15): Uses the low 4 bits of the value as
the window size logarithm, and automatically accepts either
the zlib or gzip format.
@end itemize

When decompressing a stream, the window size must not be smaller
than the size originally used to compress the stream; using a too-small
value may result in an @ref{3054,,error} exception. The default `wbits' value
corresponds to the largest window size and requires a zlib header and
trailer to be included.

`bufsize' is the initial size of the buffer used to hold decompressed data.  If
more space is required, the buffer size will be increased as needed, so you
don’t have to get this value exactly right; tuning it will only save a few calls
to @code{malloc()}.


Άλλαξε στην έκδοση 3.6: `wbits' and `bufsize' can be used as keyword arguments.

@end deffn

@geindex decompressobj() (στη μονάδα zlib)
@anchor{library/zlib zlib decompressobj}@anchor{19fd}
@deffn {Συνάρτηση} zlib.decompressobj (wbits=MAX_WBITS[, zdict])

Returns a decompression object, to be used for decompressing data streams that
won’t fit into memory at once.

The `wbits' parameter controls the size of the history buffer (or the
«window size»), and what header and trailer format is expected.  It has
the same meaning as @ref{3061,,described for decompress()}.

The `zdict' parameter specifies a predefined compression dictionary. If
provided, this must be the same dictionary as was used by the compressor that
produced the data that is to be decompressed.

@cartouche
@quotation Σημείωση 
If `zdict' is a mutable object (such as a @ref{1c6,,bytearray}), you must not
modify its contents between the call to @code{decompressobj()} and the first
call to the decompressor’s @code{decompress()} method.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: Added the `zdict' parameter.

@end deffn

Compression objects support the following methods:

@geindex compress() (μέθοδος της zlib.Compress)
@anchor{library/zlib zlib Compress compress}@anchor{3062}
@deffn {Μέθοδος} Compress.compress (data)

Compress `data', returning a bytes object containing compressed data for at least
part of the data in `data'.  This data should be concatenated to the output
produced by any preceding calls to the @code{compress()} method.  Some input may
be kept in internal buffers for later processing.
@end deffn

@geindex flush() (μέθοδος της zlib.Compress)
@anchor{library/zlib zlib Compress flush}@anchor{3063}
@deffn {Μέθοδος} Compress.flush ([mode])

All pending input is processed, and a bytes object containing the remaining compressed
output is returned.  `mode' can be selected from the constants
@ref{3064,,Z_NO_FLUSH}, @ref{3065,,Z_PARTIAL_FLUSH}, @ref{3066,,Z_SYNC_FLUSH},
@ref{3067,,Z_FULL_FLUSH}, @ref{3068,,Z_BLOCK}, or @ref{3069,,Z_FINISH},
defaulting to @code{Z_FINISH}.  Except @code{Z_FINISH}, all constants
allow compressing further bytestrings of data, while @code{Z_FINISH} finishes the
compressed stream and prevents compressing any more data.  After calling @code{flush()}
with `mode' set to @code{Z_FINISH}, the @ref{a2e,,compress()} method cannot be called again;
the only realistic action is to delete the object.
@end deffn

@geindex copy() (μέθοδος της zlib.Compress)
@anchor{library/zlib zlib Compress copy}@anchor{306a}
@deffn {Μέθοδος} Compress.copy ()

Returns a copy of the compression object.  This can be used to efficiently
compress a set of data that share a common initial prefix.
@end deffn


Άλλαξε στην έκδοση 3.8: Added @ref{942,,copy.copy()} and @ref{f2b,,copy.deepcopy()} support to compression
objects.


Decompression objects support the following methods and attributes:

@geindex unused_data (ιδιότητα της zlib.Decompress)
@anchor{library/zlib zlib Decompress unused_data}@anchor{306b}
@deffn {Ιδιότητα} Decompress.unused_data

A bytes object which contains any bytes past the end of the compressed data. That is,
this remains @code{b""} until the last byte that contains compression data is
available.  If the whole bytestring turned out to contain compressed data, this is
@code{b""}, an empty bytes object.
@end deffn

@geindex unconsumed_tail (ιδιότητα της zlib.Decompress)
@anchor{library/zlib zlib Decompress unconsumed_tail}@anchor{306c}
@deffn {Ιδιότητα} Decompress.unconsumed_tail

A bytes object that contains any data that was not consumed by the last
@ref{10c8,,decompress()} call because it exceeded the limit for the uncompressed data
buffer.  This data has not yet been seen by the zlib machinery, so you must feed
it (possibly with further data concatenated to it) back to a subsequent
@code{decompress()} method call in order to get correct output.
@end deffn

@geindex eof (ιδιότητα της zlib.Decompress)
@anchor{library/zlib zlib Decompress eof}@anchor{1516}
@deffn {Ιδιότητα} Decompress.eof

A boolean indicating whether the end of the compressed data stream has been
reached.

This makes it possible to distinguish between a properly formed compressed
stream, and an incomplete or truncated one.


Added in version 3.3.

@end deffn

@geindex decompress() (μέθοδος της zlib.Decompress)
@anchor{library/zlib zlib Decompress decompress}@anchor{306d}
@deffn {Μέθοδος} Decompress.decompress (data, max_length=0)

Decompress `data', returning a bytes object containing the uncompressed data
corresponding to at least part of the data in `string'.  This data should be
concatenated to the output produced by any preceding calls to the
@code{decompress()} method.  Some of the input data may be preserved in internal
buffers for later processing.

If the optional parameter `max_length' is non-zero then the return value will be
no longer than `max_length'. This may mean that not all of the compressed input
can be processed; and unconsumed data will be stored in the attribute
@ref{306c,,unconsumed_tail}. This bytestring must be passed to a subsequent call to
@code{decompress()} if decompression is to continue.  If `max_length' is zero
then the whole input is decompressed, and @code{unconsumed_tail} is empty.
For example, the full content could be read like:

@example
process_output(d.decompress(data, max_length))
while chunk := d.decompress(d.unconsumed_tail, max_length):
    process_output(chunk)
@end example


Άλλαξε στην έκδοση 3.6: `max_length' can be used as a keyword argument.

@end deffn

@geindex flush() (μέθοδος της zlib.Decompress)
@anchor{library/zlib zlib Decompress flush}@anchor{306e}
@deffn {Μέθοδος} Decompress.flush ([length])

All pending input is processed, and a bytes object containing the remaining
uncompressed output is returned.  After calling @code{flush()}, the
@ref{10c8,,decompress()} method cannot be called again; the only realistic action is
to delete the object.

The optional parameter `length' sets the initial size of the output buffer.
@end deffn

@geindex copy() (μέθοδος της zlib.Decompress)
@anchor{library/zlib zlib Decompress copy}@anchor{306f}
@deffn {Μέθοδος} Decompress.copy ()

Returns a copy of the decompression object.  This can be used to save the state
of the decompressor midway through the data stream in order to speed up random
seeks into the stream at a future point.
@end deffn


Άλλαξε στην έκδοση 3.8: Added @ref{942,,copy.copy()} and @ref{f2b,,copy.deepcopy()} support to decompression
objects.


The following constants are available to configure compression and decompression
behavior:

@geindex DEFLATED (στη μονάδα zlib)
@anchor{library/zlib zlib DEFLATED}@anchor{305b}
@deffn {Δεδομένα} zlib.DEFLATED

The deflate compression method.
@end deffn

@geindex MAX_WBITS (στη μονάδα zlib)
@anchor{library/zlib zlib MAX_WBITS}@anchor{305a}
@deffn {Δεδομένα} zlib.MAX_WBITS

The maximum window size, expressed as a power of 2.
For example, if @code{MAX_WBITS} is @code{15} it results in a window size
of @code{32 KiB}.
@end deffn

@geindex DEF_MEM_LEVEL (στη μονάδα zlib)
@anchor{library/zlib zlib DEF_MEM_LEVEL}@anchor{3070}
@deffn {Δεδομένα} zlib.DEF_MEM_LEVEL

The default memory level for compression objects.
@end deffn

@geindex DEF_BUF_SIZE (στη μονάδα zlib)
@anchor{library/zlib zlib DEF_BUF_SIZE}@anchor{3071}
@deffn {Δεδομένα} zlib.DEF_BUF_SIZE

The default buffer size for decompression operations.
@end deffn

@geindex Z_NO_COMPRESSION (στη μονάδα zlib)
@anchor{library/zlib zlib Z_NO_COMPRESSION}@anchor{3057}
@deffn {Δεδομένα} zlib.Z_NO_COMPRESSION

Compression level @code{0}; no compression.


Added in version 3.6.

@end deffn

@geindex Z_BEST_SPEED (στη μονάδα zlib)
@anchor{library/zlib zlib Z_BEST_SPEED}@anchor{3055}
@deffn {Δεδομένα} zlib.Z_BEST_SPEED

Compression level @code{1}; fastest and produces the least compression.
@end deffn

@geindex Z_BEST_COMPRESSION (στη μονάδα zlib)
@anchor{library/zlib zlib Z_BEST_COMPRESSION}@anchor{3056}
@deffn {Δεδομένα} zlib.Z_BEST_COMPRESSION

Compression level @code{9}; slowest and produces the most compression.
@end deffn

@geindex Z_DEFAULT_COMPRESSION (στη μονάδα zlib)
@anchor{library/zlib zlib Z_DEFAULT_COMPRESSION}@anchor{3058}
@deffn {Δεδομένα} zlib.Z_DEFAULT_COMPRESSION

Default compression level (@code{-1}); a compromise between speed and
compression. Currently equivalent to compression level @code{6}.
@end deffn

@geindex Z_DEFAULT_STRATEGY (στη μονάδα zlib)
@anchor{library/zlib zlib Z_DEFAULT_STRATEGY}@anchor{305c}
@deffn {Δεδομένα} zlib.Z_DEFAULT_STRATEGY

Default compression strategy, for normal data.
@end deffn

@geindex Z_FILTERED (στη μονάδα zlib)
@anchor{library/zlib zlib Z_FILTERED}@anchor{305d}
@deffn {Δεδομένα} zlib.Z_FILTERED

Compression strategy for data produced by a filter (or predictor).
@end deffn

@geindex Z_HUFFMAN_ONLY (στη μονάδα zlib)
@anchor{library/zlib zlib Z_HUFFMAN_ONLY}@anchor{305e}
@deffn {Δεδομένα} zlib.Z_HUFFMAN_ONLY

Compression strategy that forces Huffman coding only.
@end deffn

@geindex Z_RLE (στη μονάδα zlib)
@anchor{library/zlib zlib Z_RLE}@anchor{305f}
@deffn {Δεδομένα} zlib.Z_RLE

Compression strategy that limits match distances to one (run-length encoding).

This constant is only available if Python was compiled with zlib
1.2.0.1 or greater.


Added in version 3.6.

@end deffn

@geindex Z_FIXED (στη μονάδα zlib)
@anchor{library/zlib zlib Z_FIXED}@anchor{3060}
@deffn {Δεδομένα} zlib.Z_FIXED

Compression strategy that prevents the use of dynamic Huffman codes.

This constant is only available if Python was compiled with zlib
1.2.2.2 or greater.


Added in version 3.6.

@end deffn

@geindex Z_NO_FLUSH (στη μονάδα zlib)
@anchor{library/zlib zlib Z_NO_FLUSH}@anchor{3064}
@deffn {Δεδομένα} zlib.Z_NO_FLUSH

Flush mode @code{0}. No special flushing behavior.


Added in version 3.6.

@end deffn

@geindex Z_PARTIAL_FLUSH (στη μονάδα zlib)
@anchor{library/zlib zlib Z_PARTIAL_FLUSH}@anchor{3065}
@deffn {Δεδομένα} zlib.Z_PARTIAL_FLUSH

Flush mode @code{1}. Flush as much output as possible.
@end deffn

@geindex Z_SYNC_FLUSH (στη μονάδα zlib)
@anchor{library/zlib zlib Z_SYNC_FLUSH}@anchor{3066}
@deffn {Δεδομένα} zlib.Z_SYNC_FLUSH

Flush mode @code{2}. All output is flushed and the output is aligned to a byte boundary.
@end deffn

@geindex Z_FULL_FLUSH (στη μονάδα zlib)
@anchor{library/zlib zlib Z_FULL_FLUSH}@anchor{3067}
@deffn {Δεδομένα} zlib.Z_FULL_FLUSH

Flush mode @code{3}. All output is flushed and the compression state is reset.
@end deffn

@geindex Z_FINISH (στη μονάδα zlib)
@anchor{library/zlib zlib Z_FINISH}@anchor{3069}
@deffn {Δεδομένα} zlib.Z_FINISH

Flush mode @code{4}. All pending input is processed, no more input is expected.
@end deffn

@geindex Z_BLOCK (στη μονάδα zlib)
@anchor{library/zlib zlib Z_BLOCK}@anchor{3068}
@deffn {Δεδομένα} zlib.Z_BLOCK

Flush mode @code{5}. A deflate block is completed and emitted.

This constant is only available if Python was compiled with zlib
1.2.2.2 or greater.


Added in version 3.6.

@end deffn

@geindex Z_TREES (στη μονάδα zlib)
@anchor{library/zlib zlib Z_TREES}@anchor{3072}
@deffn {Δεδομένα} zlib.Z_TREES

Flush mode @code{6}, for inflate operations. Instructs inflate to return when
it gets to the next deflate block boundary.

This constant is only available if Python was compiled with zlib
1.2.3.4 or greater.


Added in version 3.6.

@end deffn

Information about the version of the zlib library in use is available through
the following constants:

@geindex ZLIB_VERSION (στη μονάδα zlib)
@anchor{library/zlib zlib ZLIB_VERSION}@anchor{3073}
@deffn {Δεδομένα} zlib.ZLIB_VERSION

The version string of the zlib library that was used for building the module.
This may be different from the zlib library actually used at runtime, which
is available as @ref{1517,,ZLIB_RUNTIME_VERSION}.
@end deffn

@geindex ZLIB_RUNTIME_VERSION (στη μονάδα zlib)
@anchor{library/zlib zlib ZLIB_RUNTIME_VERSION}@anchor{1517}
@deffn {Δεδομένα} zlib.ZLIB_RUNTIME_VERSION

The version string of the zlib library actually loaded by the interpreter.


Added in version 3.3.

@end deffn

@geindex ZLIBNG_VERSION (στη μονάδα zlib)
@anchor{library/zlib zlib ZLIBNG_VERSION}@anchor{3074}
@deffn {Δεδομένα} zlib.ZLIBNG_VERSION

The version string of the zlib-ng library that was used for building the
module if zlib-ng was used. When present, the @ref{3073,,ZLIB_VERSION} and
@ref{1517,,ZLIB_RUNTIME_VERSION} constants reflect the version of the zlib API
provided by zlib-ng.

If zlib-ng was not used to build the module, this constant will be absent.


Added in version 3.14.

@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{6a,,gzip}

Reading and writing @code{gzip}-format files.

@item @indicateurl{https://www.zlib.net}

The zlib library home page.

@item @indicateurl{https://www.zlib.net/manual.html}

The zlib manual explains  the semantics and usage of the library’s many
functions.
@end table

In case gzip (de)compression is a bottleneck, the python-isal@footnote{https://github.com/pycompression/python-isal}
package speeds up (de)compression with a mostly compatible API.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node gzip — Υποστήριξη για αρχεία gzip,bz2 — Support for bzip2 compression,zlib — Compression compatible with gzip,Data Compression and Archiving
@anchor{library/gzip doc}@anchor{3075}@anchor{library/gzip gzip-support-for-gzip-files}@anchor{3076}@anchor{library/gzip module-gzip}@anchor{6a}@anchor{library/gzip translation-repo}@anchor{3077}
@subsection @code{gzip} — Υποστήριξη για αρχεία @code{gzip}


@geindex module; gzip

`Πηγαίος κώδικας:' Lib/gzip.py@footnote{https://github.com/python/cpython/tree/main/Lib/gzip.py}


__________________________________________________________________


Αυτό το module παρέχει μια απλή διεπαφή για τη συμπίεση και αποσυμπίεση αρχείων όπως ακριβώς θα έκαναν τα προγράμματα της GNU @code{gzip} και @code{gunzip}.

Αυτό είναι ένα @ref{2347,,optional module}. Εάν λείπει από το αντίγραφο του CPython σας, αναζητήστε την τεκμηρίωση από τον διανομέα σας (δηλαδή, όποιος σας παρείχε την Python). Εάν είστε ο διανομέας, δείτε @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile

Η συμπίεση δεδομένων παρέχεται από το @ref{13c,,zlib} module.

The @code{gzip} module provides the @ref{849,,GzipFile} class, as well as the
@ref{3078,,open()}, @ref{a2d,,compress()} and @ref{15b4,,decompress()} convenience functions.
The @code{GzipFile} class reads and writes @code{gzip}-format files,
automatically compressing or decompressing the data so that it looks like an
ordinary @ref{156c,,file object}.

Σημειώστε ότι πρόσθετες μορφές αρχείων που μπορούν να αποσυμπιεστούν από τα προγράμματα @code{gzip} και @code{gunzip}, όπως αυτές που παράγονται από τα @code{compress} και @code{pack}, δεν υποστηρίζονται από αυτό το module.

Το module ορίζει τα ακόλουθα στοιχεία:

@geindex open() (στη μονάδα gzip)
@anchor{library/gzip gzip open}@anchor{3078}
@deffn {Συνάρτηση} gzip.open (filename, mode='rb', compresslevel=6, encoding=None, errors=None, newline=None)

Ανοίγει ένα gzip-συμπιεσμένο αρχείο σε δυαδική ή σε λειτουργία κειμένου, επιστρέφοντας ένα @ref{156c,,file object}.

Η παράμετρος `filename' μπορεί να είναι ένα πραγματικό όνομα αρχείου (ένα αντικείμενο @ref{1df,,str} ή @ref{1c7,,bytes}), ή ένα υπάρχον αντικείμενο αρχείου για ανάγνωση και εγγραφή.

Η παράμετρος `mode' μπορεί να είναι οποιαδήποτε από τις @code{'r'}. @code{'rb'}, @code{'a'}, @code{'ab'}, @code{'w'}, @code{'wb'}, @code{'x'} ή @code{'xb'} για δυαδική λειτουργία, ή @code{'rt'}, @code{'at'}, @code{'wt'} ή @code{'xt'} για λειτουργία κειμένου. Η προεπιλογή είναι το @code{'rb'}.

Η παράμετρος `compresslevel' είναι ένας ακέραιος από 0 έως 9, όπως και για τον constructor της κλάσης @ref{849,,GzipFile}.

Για δυαδική λειτουργία, αυτή η συνάρτηση είναι ισοδύναμη με τον constructor της κλάσης @ref{849,,GzipFile}: @code{GzipFile(filename, mode, compresslevel)}. Σε αυτή την περίπτωση, οι παράμετροι `encoding', `errors' και `newline' δεν πρέπει να παρέχονται.

Για τη λειτουργία κειμένου, δημιουργείται ένα αντικείμενο @ref{849,,GzipFile} και γίνεται wrap σε ένα στιγμιότυπο της κλάσης @ref{b9c,,io.TextIOWrapper} με την καθορισμένη κωδικοποίηση, τη συμπεριφορά διαχείρισης σφαλμάτων και το(α) τέλος(η) γραμμής.


Άλλαξε στην έκδοση 3.3: Προστέθηκε υποστήριξη για την παράμετρο `filename' ως αντικείμενο αρχείου, υποστήριξη για τη λειτουργία κειμένου, καθώς και οι παράμετροι `encoding', `errors' και `newline'.



Άλλαξε στην έκδοση 3.4: Προστέθηκε υποστήριξη για τις λειτουργίες @code{'x'}, @code{'xb'} και @code{'xt'}.



Άλλαξε στην έκδοση 3.6: Δέχεται ένα @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.15: The default compression level was reduced to 6 (down from 9).
It is the default level used by most compression tools and a better
tradeoff between speed and performance.

@end deffn

@geindex BadGzipFile
@anchor{library/gzip gzip BadGzipFile}@anchor{dba}
@deffn {Εξαίρεση} gzip.BadGzipFile

Μια εξαίρεση γίνεται raise για μη έγκυρα αρχεία gzip. Κληρονομεί από την @ref{53c,,OSError}. Οι εξαιρέσεις @ref{167e,,EOFError} και @ref{3054,,zlib.error} μπορούν επίσης να γίνουν raise για μη έγκυρα αρχεία gzip.


Added in version 3.8.

@end deffn

@geindex GzipFile (κλάση σε gzip)
@anchor{library/gzip gzip GzipFile}@anchor{849}
@deffn {Κλάση} gzip.GzipFile (filename=None, mode=None, compresslevel=6, fileobj=None, mtime=None)

Ο constructor της κλάσης @ref{849,,GzipFile}, η οποία προσομοιώνει τις περισσότερες μεθόδους ενός @ref{156c,,file object}, με εξαίρεση τη μέθοδο @ref{16b5,,truncate()}. Τουλάχιστον μια από τις παραμέτρους `fileobj' και `filename' πρέπει να έχει μια μη τετριμμένη τιμή.

Το νέο στιγμιότυπο της κλάσης βασίζεται στο `fileobj', το οποίο μπορεί να είναι ένα κανονικό αρχείο, ένα αντικείμενο @ref{1255,,io.BytesIO}, ή οποιοδήποτε άλλο αντικείμενο που προσομοιώνει αρχείο. Η προεπιλογή είναι @code{None}, οπότε στην περίπτωση αυτή το `filename' ανοίγεται για να παρέχει ένα αντικείμενο αρχείου.

Όταν το `fileobj' δεν είναι @code{None}, η παράμετρος `filename' χρησιμοποιείται μόνο για να συμπεριληφθεί στην επικεφαλίδα του αρχείου @code{gzip}, η οποία μπορεί να περιέχει το αρχικό όνομα του μη συμπιεσμένου αρχείου. Η προεπιλογή είναι το όνομα αρχείου του `fileobj', αν αυτό μπορεί να προσδιοριστεί· διαφορετικά, η προεπιλογή είναι η κενή συμβολοσειρά, και σε αυτή την περίπτωση το αρχικό όνομα αρχείου δεν περιλαμβάνεται στην επικεφαλίδα.

Η παράμετρος `mode' μπορεί να είναι οποιαδήποτε από τις @code{'r'}, @code{'rb'}, @code{'a'}, @code{'ab'}, @code{'w'}, @code{'wb'}, @code{'x'} ή @code{'xb'}, ανάλογα με το αν το αρχείο θα διαβαστεί ή θα γραφτεί. Η προεπιλογή είναι η λειτουργία του `fileobj', αν αυτό μπορεί να προσδιοριστεί· διαφορετικά, η προεπιλογή είναι @code{'rb'}. Σε μελλοντικές εκδόσεις της Python, η λειτουργία του `fileobj' δεν θα χρησιμοποιείται. Είναι καλύτερο να καθορίζεται πάντα η παράμετρος `mode' κατά την εγγραφή.

Σημειώστε ότι το αρχείο ανοίγει πάντα σε δυαδική λειτουργία. Για να ανοίξετε ένα συμπιεσμένο αρχείο σε λειτουργία κειμένου, χρησιμοποιήστε τη συνάρτηση @ref{3078,,open()} (ή κάντε wrap το @ref{849,,GzipFile} με ένα @ref{b9c,,io.TextIOWrapper}).

Η παράμετρος `compresslevel' είναι ένας ακέραιος από @code{0} έως @code{9} που ελέγχει το επίπεδο συμπίεσης· το @code{1} είναι το ταχύτερο και παράγει τη μικρότερη συμπίεση, ενώ το @code{9} είναι το πιο αργό και παράγει τη μεγαλύτερη συμπίεση. Το @code{0} σημαίνει καθόλου συμπίεση. Η προεπιλογή είναι το @code{9}.

Το προαιρετικό όρισμα `mtime' είναι η χρονική σήμανση που ζητείται από το gzip. Η ώρα είναι σε μορφή Unix, δηλαδή δευτερόλεπτα από τις 00:00:00 UTC, 1η Ιανουαρίου 1970. Εάν παραληφθεί το `mtime' ή @code{None}, χρησιμοποιείται η τρέχουσα ώρα. Χρησιμοποιήστε `mtime' = 0 για να δημιουργήσετε μια συμπιεσμένη ροή που δεν εξαρτάται από το χρόνο δημιουργίας.

Δείτε παρακάτω για το χαρακτηριστικό @ref{3079,,mtime} που ορίζεται κατά την αποσυμπίεση.

Η κλήση της μεθόδου @code{close()} ενός αντικειμένου @ref{849,,GzipFile} δεν κλείνει το `fileobj', καθώς μπορεί να θέλετε να προσθέσετε επιπλέον δεδομένα μετά τη συμπιεσμένη πληροφορία. Αυτό επιτρέπει επίσης να περάσετε ένα αντικείμενο @ref{1255,,io.BytesIO} ανοιγμένο για εγγραφή ως `fileobj' και να ανακτήσετε τον τελικό buffer μνήμης χρησιμοποιώντας τη μέθοδο @ref{307a,,getvalue()} του αντικειμένου @code{io.BytesIO}.

Η κλάση @ref{849,,GzipFile} υποστηρίζει τη διεπαφή @ref{a83,,io.BufferedIOBase}, συμπεριλαμβανομένης της δυνατότητας επανάληψης και της χρήσης με τη δήλωση @ref{20a,,with}. Μόνο η μέθοδος @ref{16b5,,truncate()} δεν είναι υλοποιημένη.

Η @ref{849,,GzipFile} παρέχει επίσης την ακόλουθη μέθοδο και ιδιότητα:

@geindex peek() (μέθοδος της gzip.GzipFile)
@anchor{library/gzip gzip GzipFile peek}@anchor{15b3}
@deffn {Μέθοδος} peek (n)

Διαβάζει `n' μη συμπιεσμένα bytes χωρίς να μετακινεί τη θέση του αρχείου. Ο αριθμός των bytes που επιστρέφονται μπορεί να είναι περισσότερα ή λιγότερα από τα ζητούμενα.

@cartouche
@quotation Σημείωση 
Αν και η κλήση της μεθόδου @ref{15b3,,peek()} δεν αλλάζει τη θέση του αρχείου του αντικειμένου @ref{849,,GzipFile}, μπορεί να αλλάξει τη θέση του υποκείμενου αντικειμένου αρχείου (π.χ. αν το @code{GzipFile} δημιουργήθηκε με την παράμετρο `fileobj').
@end quotation
@end cartouche


Added in version 3.2.

@end deffn

@geindex mode (ιδιότητα της gzip.GzipFile)
@anchor{library/gzip gzip GzipFile mode}@anchor{307b}
@deffn {Ιδιότητα} mode

@code{'rb'} για ανάγνωση και @code{'wb'} για εγγραφή.


Άλλαξε στην έκδοση 3.13: Σε προηγούμενες εκδόσεις αυτό ήταν ένα ακέραιος @code{1} ή @code{2}.

@end deffn

@geindex mtime (ιδιότητα της gzip.GzipFile)
@anchor{library/gzip gzip GzipFile mtime}@anchor{3079}
@deffn {Ιδιότητα} mtime

Κατά την αποσυμπίεση, αυτό το χαρακτηριστικό ορίζεται στην τελευταία σήμανση στην πιο πρόσφατα αναγνωσμένη κεφαλίδα.  Είναι ένας ακέραιος αριθμός, που κρατά τον αριθμό των δευτερολέπτων από την εποχή του Unix (00:00:00 UTC, 1 Ιανουαρίου, 1970). Η αρχική τιμή πριν από την ανάγνωση οποιωνδήποτε κεφαλίδων είναι @code{None}.
@end deffn

@geindex name (ιδιότητα της gzip.GzipFile)
@anchor{library/gzip gzip GzipFile name}@anchor{91c}
@deffn {Ιδιότητα} name

Η διαδρομή προς το αρχείο gzip στο δίσκο, ως @ref{1df,,str} ή @ref{1c7,,bytes}. Ισοδυναμεί με την έξοδο της συνάρτησης @ref{1011,,os.fspath()} για την αρχική διαδρομή εισόδου, χωρίς καμία άλλη κανονικοποίηση, επίλυση ή επέκταση.
@end deffn


Άλλαξε στην έκδοση 3.1: Προστέθηκε η υποστήριξη για τη δήλωση @ref{20a,,with}, μαζί με την παράμετρο `mtime' στον κατασκευαστή και την ιδιότητα @ref{3079,,mtime}.



Άλλαξε στην έκδοση 3.2: Προστέθηκε υποστήριξη για αρχεία με μηδενική συμπλήρωση και μη αναζητήσιμα αρχεία.



Άλλαξε στην έκδοση 3.3: Η μέθοδος @ref{307c,,io.BufferedIOBase.read1()} έχει πλέον υλοποιηθεί.



Άλλαξε στην έκδοση 3.4: Προστέθηκε υποστήριξη για τις λειτουργίες @code{'x'} και @code{'xb'}.



Άλλαξε στην έκδοση 3.5: Προστέθηκε υποστήριξη για εγγραφή αυθαίρετων @ref{436,,bytes-like objects}. Η μέθοδος @ref{16cd,,read()} δέχεται πλέον ένα όρισμα @code{None}.



Άλλαξε στην έκδοση 3.6: Δέχεται ένα @ref{79f,,path-like object}.



Αποσύρθηκε στην έκδοση 3.9: Το άνοιγμα ενός @ref{849,,GzipFile} για εγγραφή χωρίς να καθοριστεί η παράμετρος `mode' έχει καταργηθεί.



Άλλαξε στην έκδοση 3.12: Καταργήθηκε το χαρακτηριστικό @code{filename}, χρησιμοποιήστε το χαρακτηριστικό @ref{91c,,name} αντ” αυτού.



Άλλαξε στην έκδοση 3.15: The default compression level was reduced to 6 (down from 9).
It is the default level used by most compression tools and a better
tradeoff between speed and performance.

@end deffn

@geindex compress() (στη μονάδα gzip)
@anchor{library/gzip gzip compress}@anchor{a2d}
@deffn {Συνάρτηση} gzip.compress (data, compresslevel=6, *, mtime=0)

Συμπιέζει τα `data' και επιστρέφει ένα αντικείμενο @ref{1c7,,bytes} που περιέχει τα συμπιεσμένα δεδομένα. Οι παράμετροι `compresslevel' και `mtime' έχουν την ίδια σημασία όπως στον κατασκευαστή της κλάσης @ref{849,,GzipFile}, αλλά το `mtime' έχει προεπιλεγμένη τιμή 0 για αναπαραγώγιμη έξοδο.


Added in version 3.2.



Άλλαξε στην έκδοση 3.8: Προστέθηκε η παράμετρος `mtime' για αναπαραγώγιμη έξοδο.



Άλλαξε στην έκδοση 3.11: Η ταχύτητα βελτιώνεται με τη συμπίεση όλων των δεδομένων ταυτόχρονα αντί για ροή. Κλήσεις με `mtime' ρυθμισμένο σε @code{0} ανακατευθύνονται στη συνάρτηση @ref{a2e,,zlib.compress()} για καλύτερη απόδοση. Σε αυτή την περίπτωση, η έξοδος μπορεί να περιέχει μια τιμή byte «OS» στην κεφαλίδα gzip διαφορετική από 255 «unknown», όπως καθορίζεται από την υποκείμενη υλοποίηση της zlib.



Άλλαξε στην έκδοση 3.13: Το byte του λειτουργικού συστήματος κεφαλίδα gzip είναι εγγυημένο ότι θα ρυθμιστεί στο 255 όταν χρησιμοποιείται αυτή η συνάρτηση, όπως συνέβαινε στην έκδοση 3.10 και παλαιότερα.



Άλλαξε στην έκδοση 3.14: Η παράμετρος `mtime' έχει πλέον την προεπιλεγμένη τιμή 0 για αναπαραγώγιμη έξοδο. Για την προηγούμενη συμπεριφορά χρήστης της τρέχουσας ώρας, μεταβιβάστε στην παράμετρο `mtime' την τιμή @code{None}.



Άλλαξε στην έκδοση 3.15: The default compression level was reduced to 6 (down from 9).
It is the default level used by most compression tools and a better
tradeoff between speed and performance.

@end deffn

@geindex decompress() (στη μονάδα gzip)
@anchor{library/gzip gzip decompress}@anchor{15b4}
@deffn {Συνάρτηση} gzip.decompress (data)

Αποσυμπιέζει τα `data' και επιστρέφει ένα αντικείμενο @ref{1c7,,bytes} που περιέχει τα αποσυμπιεσμένα δεδομένα. Αυτή η συνάρτηση μπορεί να αποσυμπιέσει δεδομένα gzip πολλαπλών μελών (πολλαπλά μπλοκ gzip που έχουν ενωθεί μεταξύ τους). Όταν τα δεδομένα είναι βέβαιο ότι περιέχουν μόνο ένα μέλος, η συνάρτηση @ref{10c8,,zlib.decompress()} με `wbits' ρυθμισμένο σε 31 είναι ταχύτερη.


Added in version 3.2.



Άλλαξε στην έκδοση 3.11: Η ταχύτητα βελτιώνεται αποσυμπιέζοντας τα μέλη απευθείας στην μνήμη αντί να γίνεται αποσυμπίεση σε ροή.

@end deffn

@menu
* Παραδείγματα χρήσης:: 
* Διεπαφή Γραμμής Εντολών:: 

@end menu

@node Παραδείγματα χρήσης,Διεπαφή Γραμμής Εντολών,,gzip — Υποστήριξη για αρχεία gzip
@anchor{library/gzip examples-of-usage}@anchor{307d}@anchor{library/gzip gzip-usage-examples}@anchor{307e}
@subsubsection Παραδείγματα χρήσης


Παράδειγμα ανάγνωσης ενός συμπιεσμένου αρχείου:

@example
import gzip
with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
    file_content = f.read()
@end example

Παράδειγμα δημιουργίας ενός συμπιεσμένου αρχείου 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

Παράδειγμα συμπίεσης ενός υπάρχοντος αρχείου σε μορφή GZIP:

@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

Παράδειγμα συμπίεσης μιας δυαδικής συμβολοσειράς σε μορφή GZIP:

@example
import gzip
s_in = b"Lots of content here"
s_out = gzip.compress(s_in)
@end example


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{13c,,zlib}

Το βασικό module συμπίεσης δεδομένων που απαιτείται για την υποστήριξη της μορφής αρχείου @code{gzip}.
@end table

Σε περίπτωση που η (από)συμπίεση gzip είναι ένα σημείο συμφόρησης, το πακέτο python-isal@footnote{https://github.com/pycompression/python-isal} επιταχύνει την (από)συμπίεση με ένα ως επί το πλείστον συμβατό API.


@node Διεπαφή Γραμμής Εντολών,,Παραδείγματα χρήσης,gzip — Υποστήριξη για αρχεία gzip
@anchor{library/gzip command-line-interface}@anchor{307f}@anchor{library/gzip gzip-cli}@anchor{3080}
@subsubsection Διεπαφή Γραμμής Εντολών


The @code{gzip} module provides a simple command line interface to compress or
decompress files.

Once executed the @code{gzip} module keeps the input file(s).


Άλλαξε στην έκδοση 3.8: Προστέθηκε νέα διεπαφή γραμμής εντολών με οδηγίες χρήσης. Από προεπιλογή, όταν εκτελείτε την CLI, το προεπιλεγμένο επίπεδο συμπίεσης είναι 6.


@menu
* Επιλογές γραμμής εντολών:: 

@end menu

@node Επιλογές γραμμής εντολών,,,Διεπαφή Γραμμής Εντολών
@anchor{library/gzip command-line-options}@anchor{3081}
@subsubsection Επιλογές γραμμής εντολών


@geindex gzip command line option; file
@anchor{library/gzip cmdoption-gzip-arg-file}@anchor{3082}
@deffn {Option} file

Εάν δεν καθοριστεί το `file', η ανάγνωση γίνεται από το @ref{94a,,sys.stdin}.
@end deffn

@geindex gzip command line option; --fast
@anchor{library/gzip cmdoption-gzip-fast}@anchor{3083}
@deffn {Option} @w{-}@w{-}fast

Δηλώνει τη γρηγορότερη μέθοδο συμπίεσης (λιγότερη συμπίεση).
@end deffn

@geindex gzip command line option; --best
@anchor{library/gzip cmdoption-gzip-best}@anchor{3084}
@deffn {Option} @w{-}@w{-}best

Δηλώνει την βραδύτερη μέθοδο συμπίεσης (καλύτερη συμπίεση).
@end deffn

@geindex gzip command line option; -d
@geindex gzip command line option; --decompress
@anchor{library/gzip cmdoption-gzip-d}@anchor{3085}@anchor{library/gzip cmdoption-gzip-decompress}@anchor{3086}
@deffn {Option} @w{-}d, @w{-}@w{-}decompress

Αποσυμπιέζει το δοσμένο αρχείο.
@end deffn

@geindex gzip command line option; -h
@geindex gzip command line option; --help
@anchor{library/gzip cmdoption-gzip-h}@anchor{3087}@anchor{library/gzip cmdoption-gzip-help}@anchor{3088}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Εμφανίζει το μήνυμα βοήθειας.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node bz2 — Support for bzip2 compression,lzma — Compression using the LZMA algorithm,gzip — Υποστήριξη για αρχεία gzip,Data Compression and Archiving
@anchor{library/bz2 doc}@anchor{3089}@anchor{library/bz2 bz2-support-for-bzip2-compression}@anchor{308a}@anchor{library/bz2 module-bz2}@anchor{14}@anchor{library/bz2 translation-repo}@anchor{308b}
@subsection @code{bz2} — Support for @code{bzip2} compression


@geindex module; bz2

`Source code:' Lib/bz2.py@footnote{https://github.com/python/cpython/tree/main/Lib/bz2.py}


__________________________________________________________________


This module provides a comprehensive interface for compressing and
decompressing data using the bzip2 compression algorithm.

The @code{bz2} module contains:


@itemize *

@item 
The @ref{143b,,open()} function and @ref{c3d,,BZ2File} class for reading and
writing compressed files.

@item 
The @ref{1ccd,,BZ2Compressor} and @ref{18f9,,BZ2Decompressor} classes for
incremental (de)compression.

@item 
The @ref{2a93,,compress()} and @ref{143c,,decompress()} functions for one-shot
(de)compression.
@end itemize

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile

@menu
* (De)compression of files: De compression of files. 
* Incremental (de)compression: Incremental de compression. 
* One-shot (de)compression: One-shot de compression. 
* Examples of usage:: 

@end menu

@node De compression of files,Incremental de compression,,bz2 — Support for bzip2 compression
@anchor{library/bz2 de-compression-of-files}@anchor{308c}
@subsubsection (De)compression of files


@geindex open() (στη μονάδα bz2)
@anchor{library/bz2 bz2 open}@anchor{143b}
@deffn {Συνάρτηση} bz2.open (filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

Open a bzip2-compressed file in binary or text mode, returning a @ref{156c,,file object}.

As with the constructor for @ref{c3d,,BZ2File}, the `filename' argument can be
an actual filename (a @ref{1df,,str} or @ref{1c7,,bytes} object), or an existing
file object to read from or write to.

The `mode' argument can be any of @code{'r'}, @code{'rb'}, @code{'w'}, @code{'wb'},
@code{'x'}, @code{'xb'}, @code{'a'} or @code{'ab'} for binary mode, or @code{'rt'},
@code{'wt'}, @code{'xt'}, or @code{'at'} for text mode. The default is @code{'rb'}.

The `compresslevel' argument is an integer from 1 to 9, as for the
@ref{c3d,,BZ2File} constructor.

For binary mode, this function is equivalent to the @ref{c3d,,BZ2File}
constructor: @code{BZ2File(filename, mode, compresslevel=compresslevel)}. In
this case, the `encoding', `errors' and `newline' arguments must not be
provided.

For text mode, a @ref{c3d,,BZ2File} object is created, and wrapped in an
@ref{b9c,,io.TextIOWrapper} instance with the specified encoding, error
handling behavior, and line ending(s).


Added in version 3.3.



Άλλαξε στην έκδοση 3.4: The @code{'x'} (exclusive creation) mode was added.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex BZ2File (κλάση σε bz2)
@anchor{library/bz2 bz2 BZ2File}@anchor{c3d}
@deffn {Κλάση} bz2.BZ2File (filename, mode='r', *, compresslevel=9)

Open a bzip2-compressed file in binary mode.

If `filename' is a @ref{1df,,str} or @ref{1c7,,bytes} object, open the named file
directly. Otherwise, `filename' should be a @ref{156c,,file object}, which will
be used to read or write the compressed data.

The `mode' argument can be either @code{'r'} for reading (default), @code{'w'} for
overwriting, @code{'x'} for exclusive creation, or @code{'a'} for appending. These
can equivalently be given as @code{'rb'}, @code{'wb'}, @code{'xb'} and @code{'ab'}
respectively.

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'}.

If `mode' is @code{'w'} or @code{'a'}, `compresslevel' can be an integer between
@code{1} and @code{9} specifying the level of compression: @code{1} produces the
least compression, and @code{9} (default) produces the most compression.

If `mode' is @code{'r'}, the input file may be the concatenation of multiple
compressed streams.

@code{BZ2File} provides all of the members specified by the
@ref{a83,,io.BufferedIOBase}, except for @ref{3013,,detach()}
and @ref{16b5,,truncate()}.
Iteration and the @ref{20a,,with} statement are supported.

@code{BZ2File} also provides the following methods and attributes:

@geindex peek() (μέθοδος της bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File peek}@anchor{308d}
@deffn {Μέθοδος} peek ([n])

Return buffered data without advancing the file position. At least one
byte of data will be returned (unless at EOF). The exact number of bytes
returned is unspecified.

@cartouche
@quotation Σημείωση 
While calling @code{peek()} does not change the file position of
the @code{BZ2File}, it may change the position of the underlying file
object (e.g. if the @code{BZ2File} was constructed by passing a file
object for `filename').
@end quotation
@end cartouche


Added in version 3.3.

@end deffn

@geindex fileno() (μέθοδος της bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File fileno}@anchor{308e}
@deffn {Μέθοδος} fileno ()

Return the file descriptor for the underlying file.


Added in version 3.3.

@end deffn

@geindex readable() (μέθοδος της bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File readable}@anchor{308f}
@deffn {Μέθοδος} readable ()

Return whether the file was opened for reading.


Added in version 3.3.

@end deffn

@geindex seekable() (μέθοδος της bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File seekable}@anchor{3090}
@deffn {Μέθοδος} seekable ()

Return whether the file supports seeking.


Added in version 3.3.

@end deffn

@geindex writable() (μέθοδος της bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File writable}@anchor{3091}
@deffn {Μέθοδος} writable ()

Return whether the file was opened for writing.


Added in version 3.3.

@end deffn

@geindex read1() (μέθοδος της bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File read1}@anchor{3092}
@deffn {Μέθοδος} 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.


Added in version 3.3.

@end deffn

@geindex readinto() (μέθοδος της bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File readinto}@anchor{3093}
@deffn {Μέθοδος} readinto (b)

Read bytes into `b'.

Returns the number of bytes read (0 for EOF).


Added in version 3.3.

@end deffn

@geindex mode (ιδιότητα της bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File mode}@anchor{3094}
@deffn {Ιδιότητα} mode

@code{'rb'} for reading and @code{'wb'} for writing.


Added in version 3.13.

@end deffn

@geindex name (ιδιότητα της bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File name}@anchor{3095}
@deffn {Ιδιότητα} name

The bzip2 file name.  Equivalent to the @ref{3017,,name}
attribute of the underlying @ref{156c,,file object}.


Added in version 3.13.

@end deffn


Άλλαξε στην έκδοση 3.1: Support for the @ref{20a,,with} statement was added.



Άλλαξε στην έκδοση 3.3: Support was added for `filename' being a @ref{156c,,file object} instead of an
actual filename.

The @code{'a'} (append) mode was added, along with support for reading
multi-stream files.



Άλλαξε στην έκδοση 3.4: The @code{'x'} (exclusive creation) mode was added.



Άλλαξε στην έκδοση 3.5: The @ref{16cd,,read()} method now accepts an argument of
@code{None}.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.9: The `buffering' parameter has been removed. It was ignored and deprecated
since Python 3.0. Pass an open file object to control how the file is
opened.

The `compresslevel' parameter became keyword-only.



Άλλαξε στην έκδοση 3.10: This class is thread unsafe in the face of multiple simultaneous
readers or writers, just like its equivalent classes in @ref{6a,,gzip} and
@ref{8d,,lzma} have always been.

@end deffn

@node Incremental de compression,One-shot de compression,De compression of files,bz2 — Support for bzip2 compression
@anchor{library/bz2 incremental-de-compression}@anchor{3096}
@subsubsection Incremental (de)compression


@geindex BZ2Compressor (κλάση σε bz2)
@anchor{library/bz2 bz2 BZ2Compressor}@anchor{1ccd}
@deffn {Κλάση} bz2.BZ2Compressor (compresslevel=9)

Create a new compressor object. This object may be used to compress data
incrementally. For one-shot compression, use the @ref{2a93,,compress()} function
instead.

`compresslevel', if given, must be an integer between @code{1} and @code{9}. The
default is @code{9}.

@geindex compress() (μέθοδος της bz2.BZ2Compressor)
@anchor{library/bz2 bz2 BZ2Compressor compress}@anchor{3097}
@deffn {Μέθοδος} compress (data)

Provide data to the compressor object. Returns a chunk of compressed data
if possible, or an empty byte string otherwise.

When you have finished providing data to the compressor, call the
@ref{3098,,flush()} method to finish the compression process.
@end deffn

@geindex flush() (μέθοδος της bz2.BZ2Compressor)
@anchor{library/bz2 bz2 BZ2Compressor flush}@anchor{3098}
@deffn {Μέθοδος} flush ()

Finish the compression process. Returns the compressed data left in
internal buffers.

The compressor object may not be used after this method has been called.
@end deffn
@end deffn

@geindex BZ2Decompressor (κλάση σε bz2)
@anchor{library/bz2 bz2 BZ2Decompressor}@anchor{18f9}
@deffn {Κλάση} bz2.BZ2Decompressor

Create a new decompressor object. This object may be used to decompress data
incrementally. For one-shot compression, use the @ref{143c,,decompress()} function
instead.

@cartouche
@quotation Σημείωση 
This class does not transparently handle inputs containing multiple
compressed streams, unlike @ref{143c,,decompress()} and @ref{c3d,,BZ2File}. If
you need to decompress a multi-stream input with @code{BZ2Decompressor},
you must use a new decompressor for each stream.
@end quotation
@end cartouche

@geindex decompress() (μέθοδος της bz2.BZ2Decompressor)
@anchor{library/bz2 bz2 BZ2Decompressor decompress}@anchor{1183}
@deffn {Μέθοδος} decompress (data, max_length=-1)

Decompress `data' (a @ref{436,,bytes-like object}), returning
uncompressed data as bytes. Some of `data' may be buffered
internally, for use in later calls to @code{decompress()}. The
returned data should be concatenated with the output of any
previous calls to @code{decompress()}.

If `max_length' is nonnegative, returns at most `max_length'
bytes of decompressed data. If this limit is reached and further
output can be produced, the @ref{3099,,needs_input} attribute will
be set to @code{False}. In this case, the next call to
@code{decompress()} may provide `data' as @code{b'@w{'}} to obtain
more of the output.

If all of the input data was decompressed and returned (either
because this was less than `max_length' bytes, or because
`max_length' was negative), the @ref{3099,,needs_input} attribute
will be set to @code{True}.

Attempting to decompress data after the end of stream is reached
raises an @ref{167e,,EOFError}.  Any data found after the end of the
stream is ignored and saved in the @ref{309a,,unused_data} attribute.


Άλλαξε στην έκδοση 3.5: Added the `max_length' parameter.

@end deffn

@geindex eof (ιδιότητα της bz2.BZ2Decompressor)
@anchor{library/bz2 bz2 BZ2Decompressor eof}@anchor{309b}
@deffn {Ιδιότητα} eof

@code{True} if the end-of-stream marker has been reached.


Added in version 3.3.

@end deffn

@geindex unused_data (ιδιότητα της bz2.BZ2Decompressor)
@anchor{library/bz2 bz2 BZ2Decompressor unused_data}@anchor{309a}
@deffn {Ιδιότητα} unused_data

Data found after the end of the compressed stream.

If this attribute is accessed before the end of the stream has been
reached, its value will be @code{b'@w{'}}.
@end deffn

@geindex needs_input (ιδιότητα της bz2.BZ2Decompressor)
@anchor{library/bz2 bz2 BZ2Decompressor needs_input}@anchor{3099}
@deffn {Ιδιότητα} needs_input

@code{False} if the @ref{1183,,decompress()} method can provide more
decompressed data before requiring new uncompressed input.


Added in version 3.5.

@end deffn
@end deffn

@node One-shot de compression,Examples of usage,Incremental de compression,bz2 — Support for bzip2 compression
@anchor{library/bz2 one-shot-de-compression}@anchor{309c}
@subsubsection One-shot (de)compression


@geindex compress() (στη μονάδα bz2)
@anchor{library/bz2 bz2 compress}@anchor{2a93}
@deffn {Συνάρτηση} bz2.compress (data, compresslevel=9)

Compress `data', a @ref{436,,bytes-like object}.

`compresslevel', if given, must be an integer between @code{1} and @code{9}. The
default is @code{9}.

For incremental compression, use a @ref{1ccd,,BZ2Compressor} instead.
@end deffn

@geindex decompress() (στη μονάδα bz2)
@anchor{library/bz2 bz2 decompress}@anchor{143c}
@deffn {Συνάρτηση} bz2.decompress (data)

Decompress `data', a @ref{436,,bytes-like object}.

If `data' is the concatenation of multiple compressed streams, decompress
all of the streams.

For incremental decompression, use a @ref{18f9,,BZ2Decompressor} instead.


Άλλαξε στην έκδοση 3.3: Support for multi-stream inputs was added.

@end deffn

@node Examples of usage,,One-shot de compression,bz2 — Support for bzip2 compression
@anchor{library/bz2 bz2-usage-examples}@anchor{309d}@anchor{library/bz2 examples-of-usage}@anchor{309e}
@subsubsection Examples of usage


Below are some examples of typical usage of the @code{bz2} module.

Using @ref{2a93,,compress()} and @ref{143c,,decompress()} to demonstrate round-trip compression:

@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

Using @ref{1ccd,,BZ2Compressor} for incremental compression:

@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.

Writing and reading a bzip2-compressed file in binary mode:

@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")

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node lzma — Compression using the LZMA algorithm,zipfile — Work with ZIP archives,bz2 — Support for bzip2 compression,Data Compression and Archiving
@anchor{library/lzma doc}@anchor{309f}@anchor{library/lzma lzma-compression-using-the-lzma-algorithm}@anchor{30a0}@anchor{library/lzma module-lzma}@anchor{8d}@anchor{library/lzma translation-repo}@anchor{30a1}
@subsection @code{lzma} — Compression using the LZMA algorithm


@geindex module; lzma


Added in version 3.3.


`Source code:' Lib/lzma.py@footnote{https://github.com/python/cpython/tree/main/Lib/lzma.py}


__________________________________________________________________


This module provides classes and convenience functions for compressing and
decompressing data using the LZMA compression algorithm. Also included is a file
interface supporting the @code{.xz} and legacy @code{.lzma} file formats used by the
@code{xz} utility, as well as raw compressed streams.

The interface provided by this module is very similar to that of the @ref{14,,bz2}
module. Note that @ref{13b5,,LZMAFile} and @ref{c3d,,bz2.BZ2File} are `not'
thread-safe, so if you need to use a single @code{LZMAFile} instance
from multiple threads, it is necessary to protect it with a lock.

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile

@geindex LZMAError
@anchor{library/lzma lzma LZMAError}@anchor{30a2}
@deffn {Εξαίρεση} lzma.LZMAError

This exception is raised when an error occurs during compression or
decompression, or while initializing the compressor/decompressor state.
@end deffn

@menu
* Reading and writing compressed files: Reading and writing compressed files<2>. 
* Compressing and decompressing data in memory: Compressing and decompressing data in memory<2>. 
* Miscellaneous: Miscellaneous<2>. 
* Specifying custom filter chains:: 
* Examples: Examples<7>. 

@end menu

@node Reading and writing compressed files<2>,Compressing and decompressing data in memory<2>,,lzma — Compression using the LZMA algorithm
@anchor{library/lzma reading-and-writing-compressed-files}@anchor{30a3}
@subsubsection Reading and writing compressed files


@geindex open() (στη μονάδα lzma)
@anchor{library/lzma lzma open}@anchor{30a4}
@deffn {Συνάρτηση} 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{156c,,file object}.

The `filename' argument can be either an actual file name (given as a
@ref{1df,,str}, @ref{1c7,,bytes} or @ref{79f,,path-like} object), in
which case the named file is opened, or it can be an existing file object
to read from or write to.

The `mode' argument can be any of @code{"r"}, @code{"rb"}, @code{"w"}, @code{"wb"},
@code{"x"}, @code{"xb"}, @code{"a"} or @code{"ab"} for binary mode, or @code{"rt"},
@code{"wt"}, @code{"xt"}, or @code{"at"} for text mode. The default is @code{"rb"}.

When opening a file for reading, the `format' and `filters' arguments have
the same meanings as for @ref{18f8,,LZMADecompressor}. In this case, the `check'
and `preset' arguments should not be used.

When opening a file for writing, the `format', `check', `preset' and
`filters' arguments have the same meanings as for @ref{1ccc,,LZMACompressor}.

For binary mode, this function is equivalent to the @ref{13b5,,LZMAFile}
constructor: @code{LZMAFile(filename, mode, ...)}. In this case, the `encoding',
`errors' and `newline' arguments must not be provided.

For text mode, a @ref{13b5,,LZMAFile} object is created, and wrapped in an
@ref{b9c,,io.TextIOWrapper} instance with the specified encoding, error
handling behavior, and line ending(s).


Άλλαξε στην έκδοση 3.4: Added support for the @code{"x"}, @code{"xb"} and @code{"xt"} modes.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex LZMAFile (κλάση σε lzma)
@anchor{library/lzma lzma LZMAFile}@anchor{13b5}
@deffn {Κλάση} lzma.LZMAFile (filename=None, mode='r', *, format=None, check=-1, preset=None, filters=None)

Open an LZMA-compressed file in binary mode.

An @code{LZMAFile} can wrap an already-open @ref{156c,,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{1df,,str},
@ref{1c7,,bytes} or @ref{79f,,path-like} object). When wrapping an
existing file object, the wrapped file will not be closed when the
@code{LZMAFile} is closed.

The `mode' argument can be either @code{"r"} for reading (default), @code{"w"} for
overwriting, @code{"x"} for exclusive creation, or @code{"a"} for appending. These
can equivalently be given as @code{"rb"}, @code{"wb"}, @code{"xb"} and @code{"ab"}
respectively.

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"}.

When opening a file for reading, the input file may be the concatenation of
multiple separate compressed streams. These are transparently decoded as a
single logical stream.

When opening a file for reading, the `format' and `filters' arguments have
the same meanings as for @ref{18f8,,LZMADecompressor}. In this case, the `check'
and `preset' arguments should not be used.

When opening a file for writing, the `format', `check', `preset' and
`filters' arguments have the same meanings as for @ref{1ccc,,LZMACompressor}.

@code{LZMAFile} supports all the members specified by
@ref{a83,,io.BufferedIOBase}, except for @ref{3013,,detach()}
and @ref{16b5,,truncate()}.
Iteration and the @ref{20a,,with} statement are supported.

The following method and attributes are also provided:

@geindex peek() (μέθοδος της lzma.LZMAFile)
@anchor{library/lzma lzma LZMAFile peek}@anchor{30a5}
@deffn {Μέθοδος} peek (size=-1)

Return buffered data without advancing the file position. At least one
byte of data will be returned, unless EOF has been reached. The exact
number of bytes returned is unspecified (the `size' argument is ignored).

@cartouche
@quotation Σημείωση 
While calling @code{peek()} does not change the file position of
the @code{LZMAFile}, it may change the position of the underlying
file object (e.g. if the @code{LZMAFile} was constructed by passing a
file object for `filename').
@end quotation
@end cartouche
@end deffn

@geindex mode (ιδιότητα της lzma.LZMAFile)
@anchor{library/lzma lzma LZMAFile mode}@anchor{30a6}
@deffn {Ιδιότητα} mode

@code{'rb'} for reading and @code{'wb'} for writing.


Added in version 3.13.

@end deffn

@geindex name (ιδιότητα της lzma.LZMAFile)
@anchor{library/lzma lzma LZMAFile name}@anchor{30a7}
@deffn {Ιδιότητα} name

The lzma file name.  Equivalent to the @ref{3017,,name}
attribute of the underlying @ref{156c,,file object}.


Added in version 3.13.

@end deffn


Άλλαξε στην έκδοση 3.4: Added support for the @code{"x"} and @code{"xb"} modes.



Άλλαξε στην έκδοση 3.5: The @ref{16cd,,read()} method now accepts an argument of
@code{None}.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@node Compressing and decompressing data in memory<2>,Miscellaneous<2>,Reading and writing compressed files<2>,lzma — Compression using the LZMA algorithm
@anchor{library/lzma compressing-and-decompressing-data-in-memory}@anchor{30a8}
@subsubsection Compressing and decompressing data in memory


@geindex LZMACompressor (κλάση σε lzma)
@anchor{library/lzma lzma LZMACompressor}@anchor{1ccc}
@deffn {Κλάση} lzma.LZMACompressor (format=FORMAT_XZ, check=-1, preset=None, filters=None)

Create a compressor object, which can be used to compress data incrementally.

For a more convenient way of compressing a single chunk of data, see
@ref{30a9,,compress()}.

The `format' argument specifies what container format should be used.
Possible values are:


@itemize *

@item 

@table @asis

@item @code{FORMAT_XZ}: The @code{.xz} container format.

This is the default format.
@end table

@item 

@table @asis

@item @code{FORMAT_ALONE}: The legacy @code{.lzma} container format.

This format is more limited than @code{.xz} – it does not support integrity
checks or multiple filters.
@end table

@item 

@table @asis

@item @code{FORMAT_RAW}: A raw data stream, not using any container format.

This format specifier does not support integrity checks, and requires that
you always specify a custom filter chain (for both compression and
decompression). Additionally, data compressed in this manner cannot be
decompressed using @code{FORMAT_AUTO} (see @ref{18f8,,LZMADecompressor}).
@end table
@end itemize

The `check' argument specifies the type of integrity check to include in the
compressed data. This check is used when decompressing, to ensure that the
data has not been corrupted. Possible values are:


@itemize *

@item 
@code{CHECK_NONE}: No integrity check.
This is the default (and the only acceptable value) for
@code{FORMAT_ALONE} and @code{FORMAT_RAW}.

@item 
@code{CHECK_CRC32}: 32-bit Cyclic Redundancy Check.

@item 
@code{CHECK_CRC64}: 64-bit Cyclic Redundancy Check.
This is the default for @code{FORMAT_XZ}.

@item 
@code{CHECK_SHA256}: 256-bit Secure Hash Algorithm.
@end itemize

If the specified check is not supported, an @ref{30a2,,LZMAError} is raised.

The compression settings can be specified either as a preset compression
level (with the `preset' argument), or in detail as a custom filter chain
(with the `filters' argument).

The `preset' argument (if provided) should be an integer between @code{0} and
@code{9} (inclusive), optionally OR-ed with the constant
@code{PRESET_EXTREME}. If neither `preset' nor `filters' are given, the
default behavior is to use @code{PRESET_DEFAULT} (preset level @code{6}).
Higher presets produce smaller output, but make the compression process
slower.

@cartouche
@quotation Σημείωση 
In addition to being more CPU-intensive, compression with higher presets
also requires much more memory (and produces output that needs more memory
to decompress). With preset @code{9} for example, the overhead for an
@code{LZMACompressor} object can be as high as 800 MiB. For this reason,
it is generally best to stick with the default preset.
@end quotation
@end cartouche

The `filters' argument (if provided) should be a filter chain specifier.
See @ref{30aa,,Specifying custom filter chains} for details.

@geindex compress() (μέθοδος της lzma.LZMACompressor)
@anchor{library/lzma lzma LZMACompressor compress}@anchor{30ab}
@deffn {Μέθοδος} compress (data)

Compress `data' (a @ref{1c7,,bytes} object), returning a @code{bytes}
object containing compressed data for at least part of the input. Some of
`data' may be buffered internally, for use in later calls to
@code{compress()} and @ref{30ac,,flush()}. The returned data should be
concatenated with the output of any previous calls to @code{compress()}.
@end deffn

@geindex flush() (μέθοδος της lzma.LZMACompressor)
@anchor{library/lzma lzma LZMACompressor flush}@anchor{30ac}
@deffn {Μέθοδος} flush ()

Finish the compression process, returning a @ref{1c7,,bytes} object
containing any data stored in the compressor’s internal buffers.

The compressor cannot be used after this method has been called.
@end deffn
@end deffn

@geindex LZMADecompressor (κλάση σε lzma)
@anchor{library/lzma lzma LZMADecompressor}@anchor{18f8}
@deffn {Κλάση} lzma.LZMADecompressor (format=FORMAT_AUTO, memlimit=None, filters=None)

Create a decompressor object, which can be used to decompress data
incrementally.

For a more convenient way of decompressing an entire compressed stream at
once, see @ref{30ad,,decompress()}.

The `format' argument specifies the container format that should be used. The
default is @code{FORMAT_AUTO}, which can decompress both @code{.xz} and
@code{.lzma} files. Other possible values are @code{FORMAT_XZ},
@code{FORMAT_ALONE}, and @code{FORMAT_RAW}.

The `memlimit' argument specifies a limit (in bytes) on the amount of memory
that the decompressor can use. When this argument is used, decompression will
fail with an @ref{30a2,,LZMAError} if it is not possible to decompress the input
within the given memory limit.

The `filters' argument specifies the filter chain that was used to create
the stream being decompressed. This argument is required if `format' is
@code{FORMAT_RAW}, but should not be used for other formats.
See @ref{30aa,,Specifying custom filter chains} for more information about filter chains.

@cartouche
@quotation Σημείωση 
This class does not transparently handle inputs containing multiple
compressed streams, unlike @ref{30ad,,decompress()} and @ref{13b5,,LZMAFile}. To
decompress a multi-stream input with @code{LZMADecompressor}, you must
create a new decompressor for each stream.
@end quotation
@end cartouche

@geindex decompress() (μέθοδος της lzma.LZMADecompressor)
@anchor{library/lzma lzma LZMADecompressor decompress}@anchor{11e1}
@deffn {Μέθοδος} decompress (data, max_length=-1)

Decompress `data' (a @ref{436,,bytes-like object}), returning
uncompressed data as bytes. Some of `data' may be buffered
internally, for use in later calls to @code{decompress()}. The
returned data should be concatenated with the output of any
previous calls to @code{decompress()}.

If `max_length' is nonnegative, returns at most `max_length'
bytes of decompressed data. If this limit is reached and further
output can be produced, the @ref{30ae,,needs_input} attribute will
be set to @code{False}. In this case, the next call to
@code{decompress()} may provide `data' as @code{b'@w{'}} to obtain
more of the output.

If all of the input data was decompressed and returned (either
because this was less than `max_length' bytes, or because
`max_length' was negative), the @ref{30ae,,needs_input} attribute
will be set to @code{True}.

Attempting to decompress data after the end of stream is reached
raises an @ref{167e,,EOFError}.  Any data found after the end of the
stream is ignored and saved in the @ref{30af,,unused_data} attribute.


Άλλαξε στην έκδοση 3.5: Added the `max_length' parameter.

@end deffn

@geindex check (ιδιότητα της lzma.LZMADecompressor)
@anchor{library/lzma lzma LZMADecompressor check}@anchor{30b0}
@deffn {Ιδιότητα} check

The ID of the integrity check used by the input stream. This may be
@code{CHECK_UNKNOWN} until enough of the input has been decoded to
determine what integrity check it uses.
@end deffn

@geindex eof (ιδιότητα της lzma.LZMADecompressor)
@anchor{library/lzma lzma LZMADecompressor eof}@anchor{30b1}
@deffn {Ιδιότητα} eof

@code{True} if the end-of-stream marker has been reached.
@end deffn

@geindex unused_data (ιδιότητα της lzma.LZMADecompressor)
@anchor{library/lzma lzma LZMADecompressor unused_data}@anchor{30af}
@deffn {Ιδιότητα} unused_data

Data found after the end of the compressed stream.

Before the end of the stream is reached, this will be @code{b""}.
@end deffn

@geindex needs_input (ιδιότητα της lzma.LZMADecompressor)
@anchor{library/lzma lzma LZMADecompressor needs_input}@anchor{30ae}
@deffn {Ιδιότητα} needs_input

@code{False} if the @ref{11e1,,decompress()} method can provide more
decompressed data before requiring new uncompressed input.


Added in version 3.5.

@end deffn
@end deffn

@geindex compress() (στη μονάδα lzma)
@anchor{library/lzma lzma compress}@anchor{30a9}
@deffn {Συνάρτηση} lzma.compress (data, format=FORMAT_XZ, check=-1, preset=None, filters=None)

Compress `data' (a @ref{1c7,,bytes} object), returning the compressed data as a
@code{bytes} object.

See @ref{1ccc,,LZMACompressor} above for a description of the `format', `check',
`preset' and `filters' arguments.
@end deffn

@geindex decompress() (στη μονάδα lzma)
@anchor{library/lzma lzma decompress}@anchor{30ad}
@deffn {Συνάρτηση} lzma.decompress (data, format=FORMAT_AUTO, memlimit=None, filters=None)

Decompress `data' (a @ref{1c7,,bytes} object), returning the uncompressed data
as a @code{bytes} object.

If `data' is the concatenation of multiple distinct compressed streams,
decompress all of these streams, and return the concatenation of the results.

See @ref{18f8,,LZMADecompressor} above for a description of the `format',
`memlimit' and `filters' arguments.
@end deffn

@node Miscellaneous<2>,Specifying custom filter chains,Compressing and decompressing data in memory<2>,lzma — Compression using the LZMA algorithm
@anchor{library/lzma miscellaneous}@anchor{30b2}
@subsubsection Miscellaneous


@geindex is_check_supported() (στη μονάδα lzma)
@anchor{library/lzma lzma is_check_supported}@anchor{30b3}
@deffn {Συνάρτηση} lzma.is_check_supported (check)

Return @code{True} if the given integrity check is supported on this system.

@code{CHECK_NONE} and @code{CHECK_CRC32} are always supported.
@code{CHECK_CRC64} and @code{CHECK_SHA256} may be unavailable if you are
using a version of @code{liblzma} that was compiled with a limited
feature set.
@end deffn

@node Specifying custom filter chains,Examples<7>,Miscellaneous<2>,lzma — Compression using the LZMA algorithm
@anchor{library/lzma filter-chain-specs}@anchor{30aa}@anchor{library/lzma specifying-custom-filter-chains}@anchor{30b4}
@subsubsection Specifying custom filter chains


A filter chain specifier is a sequence of dictionaries, where each dictionary
contains the ID and options for a single filter. Each dictionary must contain
the key @code{"id"}, and may contain additional keys to specify filter-dependent
options. Valid filter IDs are as follows:


@itemize *

@item 
Compression filters:


@itemize *

@item 
@code{FILTER_LZMA1} (for use with @code{FORMAT_ALONE})

@item 
@code{FILTER_LZMA2} (for use with @code{FORMAT_XZ} and @code{FORMAT_RAW})
@end itemize

@item 
Delta filter:


@itemize *

@item 
@code{FILTER_DELTA}
@end itemize

@item 
Branch-Call-Jump (BCJ) filters:


@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

A filter chain can consist of up to 4 filters, and cannot be empty. The last
filter in the chain must be a compression filter, and any other filters must be
delta or BCJ filters.

Compression filters support the following options (specified as additional
entries in the dictionary representing the filter):


@itemize *

@item 
@code{preset}: A compression preset to use as a source of default values for
options that are not specified explicitly.

@item 
@code{dict_size}: Dictionary size in bytes. This should be between 4 KiB and
1.5 GiB (inclusive).

@item 
@code{lc}: Number of literal context bits.

@item 
@code{lp}: Number of literal position bits. The sum @code{lc + lp} must be at
most 4.

@item 
@code{pb}: Number of position bits; must be at most 4.

@item 
@code{mode}: @code{MODE_FAST} or @code{MODE_NORMAL}.

@item 
@code{nice_len}: What should be considered a «nice length» for a match.
This should be 273 or less.

@item 
@code{mf}: What match finder to use – @code{MF_HC3}, @code{MF_HC4},
@code{MF_BT2}, @code{MF_BT3}, or @code{MF_BT4}.

@item 
@code{depth}: Maximum search depth used by match finder. 0 (default) means to
select automatically based on other filter options.
@end itemize

The delta filter stores the differences between bytes, producing more repetitive
input for the compressor in certain circumstances. It supports one option,
@code{dist}. This indicates the distance between bytes to be subtracted. The
default is 1, i.e. take the differences between adjacent bytes.

The BCJ filters are intended to be applied to machine code. They convert
relative branches, calls and jumps in the code to use absolute addressing, with
the aim of increasing the redundancy that can be exploited by the compressor.
These filters support one option, @code{start_offset}. This specifies the address
that should be mapped to the beginning of the input data. The default is 0.

@node Examples<7>,,Specifying custom filter chains,lzma — Compression using the LZMA algorithm
@anchor{library/lzma examples}@anchor{30b5}
@subsubsection Examples


Reading in a compressed file:

@example
import lzma
with lzma.open("file.xz") as f:
    file_content = f.read()
@end example

Creating a compressed file:

@example
import lzma
data = b"Insert Data Here"
with lzma.open("file.xz", "w") as f:
    f.write(data)
@end example

Compressing data in memory:

@example
import lzma
data_in = b"Insert Data Here"
data_out = lzma.compress(data_in)
@end example

Incremental compression:

@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

Writing compressed data to an already-open file:

@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

Creating a compressed file using a custom filter chain:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node zipfile — Work with ZIP archives,tarfile — Read and write tar archive files,lzma — Compression using the LZMA algorithm,Data Compression and Archiving
@anchor{library/zipfile doc}@anchor{30b6}@anchor{library/zipfile module-zipfile}@anchor{13a}@anchor{library/zipfile translation-repo}@anchor{30b7}@anchor{library/zipfile zipfile-work-with-zip-archives}@anchor{30b8}
@subsection @code{zipfile} — Work with ZIP archives


@geindex module; zipfile

`Source code:' Lib/zipfile/@footnote{https://github.com/python/cpython/tree/main/Lib/zipfile/}


__________________________________________________________________


The ZIP file format is a common archive and compression standard. This module
provides tools to create, read, write, append, and list a ZIP file.  Any
advanced use of this module will require an understanding of the format, as
defined in PKZIP Application Note@footnote{https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT}.

This module does not handle multipart ZIP files.
It can handle ZIP files that use the ZIP64 extensions
(that is ZIP files that are more than 4 GiB in size).  It supports
decryption of encrypted files in ZIP archives, but it cannot
create an encrypted file.  Decryption is extremely slow as it is
implemented in native Python rather than C.

@c The following paragraph should be similar to ../includes/optional-module.rst

Handling compressed archives requires @ref{2347,,optional modules}
such as @ref{13c,,zlib}, @ref{14,,bz2}, @ref{8d,,lzma}, and @ref{23,,compression.zstd}.
If any of them are missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

The module defines the following items:

@geindex BadZipFile
@anchor{library/zipfile zipfile BadZipFile}@anchor{1d65}
@deffn {Εξαίρεση} zipfile.BadZipFile

The error raised for bad ZIP files.


Added in version 3.2.

@end deffn

@geindex BadZipfile
@anchor{library/zipfile zipfile BadZipfile}@anchor{30b9}
@deffn {Εξαίρεση} zipfile.BadZipfile

Alias of @ref{1d65,,BadZipFile}, for compatibility with older Python versions.


Αποσύρθηκε στην έκδοση 3.2.

@end deffn

@geindex LargeZipFile
@anchor{library/zipfile zipfile LargeZipFile}@anchor{30ba}
@deffn {Εξαίρεση} zipfile.LargeZipFile

The error raised when a ZIP file would require ZIP64 functionality but that has
not been enabled.
@end deffn


@deffn {Κλάση} zipfile.ZipFile

The class for reading and writing ZIP files.  See section
@ref{30bb,,ZipFile objects} for constructor details.
@end deffn


@deffn {Κλάση} zipfile.Path

Class that implements a subset of the interface provided by
@ref{4ee,,pathlib.Path}, including the full
@ref{572,,importlib.resources.abc.Traversable} interface.


Added in version 3.8.

@end deffn


@deffn {Κλάση} zipfile.PyZipFile

Class for creating ZIP archives containing Python libraries.
@end deffn

@geindex ZipInfo (κλάση σε zipfile)
@anchor{library/zipfile zipfile ZipInfo}@anchor{547}
@deffn {Κλάση} zipfile.ZipInfo (filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))

Class used to represent information about a member of an archive. Instances
of this class are returned by the @ref{30bc,,getinfo()} and @ref{30bd,,infolist()}
methods of @ref{ab1,,ZipFile} objects.  Most users of the @code{zipfile} module
will not need to create these, but only use those created by this
module. `filename' should be the full name of the archive member, and
`date_time' should be a tuple containing six fields which describe the time
of the last modification to the file; the fields are described in section
@ref{30be,,ZipInfo objects}.


Άλλαξε στην έκδοση 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.


@geindex _for_archive() (μέθοδος της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo _for_archive}@anchor{546}
@deffn {Μέθοδος} _for_archive (archive)

Resolve the date_time, compression attributes, and external attributes
to suitable defaults as used by @ref{548,,ZipFile.writestr()}.

Returns self for chaining.


Added in version 3.14.

@end deffn
@end deffn

@geindex is_zipfile() (στη μονάδα zipfile)
@anchor{library/zipfile zipfile is_zipfile}@anchor{16cf}
@deffn {Συνάρτηση} zipfile.is_zipfile (filename)

Returns @code{True} if `filename' is a valid ZIP file based on its magic number,
otherwise returns @code{False}.  `filename' may be a file or file-like object too.


Άλλαξε στην έκδοση 3.1: Support for file and file-like objects.

@end deffn

@geindex ZIP_STORED (στη μονάδα zipfile)
@anchor{library/zipfile zipfile ZIP_STORED}@anchor{30bf}
@deffn {Δεδομένα} zipfile.ZIP_STORED

The numeric constant for an uncompressed archive member.
@end deffn

@geindex ZIP_DEFLATED (στη μονάδα zipfile)
@anchor{library/zipfile zipfile ZIP_DEFLATED}@anchor{30c0}
@deffn {Δεδομένα} zipfile.ZIP_DEFLATED

The numeric constant for the usual ZIP compression method.  This requires the
@ref{13c,,zlib} module.
@end deffn

@geindex ZIP_BZIP2 (στη μονάδα zipfile)
@anchor{library/zipfile zipfile ZIP_BZIP2}@anchor{30c1}
@deffn {Δεδομένα} zipfile.ZIP_BZIP2

The numeric constant for the BZIP2 compression method.  This requires the
@ref{14,,bz2} module.


Added in version 3.3.

@end deffn

@geindex ZIP_LZMA (στη μονάδα zipfile)
@anchor{library/zipfile zipfile ZIP_LZMA}@anchor{30c2}
@deffn {Δεδομένα} zipfile.ZIP_LZMA

The numeric constant for the LZMA compression method.  This requires the
@ref{8d,,lzma} module.


Added in version 3.3.

@end deffn

@geindex ZIP_ZSTANDARD (στη μονάδα zipfile)
@anchor{library/zipfile zipfile ZIP_ZSTANDARD}@anchor{30c3}
@deffn {Δεδομένα} zipfile.ZIP_ZSTANDARD

The numeric constant for Zstandard compression. This requires the
@ref{23,,compression.zstd} module.

@cartouche
@quotation Σημείωση 
In APPNOTE 6.3.7, the method ID @code{20} was assigned to Zstandard
compression. This was changed in APPNOTE 6.3.8 to method ID @code{93} to
avoid conflicts, with method ID @code{20} being deprecated. For
compatibility, the @code{zipfile} module reads both method IDs but will
only write data with method ID @code{93}.
@end quotation
@end cartouche


Added in version 3.14.

@end deffn

@cartouche
@quotation Σημείωση 
The ZIP file format specification has included support for bzip2 compression
since 2001, for LZMA compression since 2006, and Zstandard compression since
2020. However, some tools (including older Python releases) do not support
these compression methods, and may either refuse to process the ZIP file
altogether, or fail to extract individual files.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης



@table @asis

@item PKZIP Application Note@footnote{https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT}

Documentation on the ZIP file format by Phil Katz, the creator of the format and
algorithms used.

@item Info-ZIP Home Page@footnote{https://infozip.sourceforge.net/}

Information about the Info-ZIP project’s ZIP archive programs and development
libraries.
@end table


@menu
* ZipFile objects:: 
* Path objects:: 
* PyZipFile objects:: 
* ZipInfo objects:: 
* Command-line interface: Command-line interface<3>. 
* Decompression pitfalls:: 

@end menu

@node ZipFile objects,Path objects,,zipfile — Work with ZIP archives
@anchor{library/zipfile id1}@anchor{30c4}@anchor{library/zipfile zipfile-objects}@anchor{30bb}
@subsubsection ZipFile objects


@geindex ZipFile (κλάση σε zipfile)
@anchor{library/zipfile zipfile ZipFile}@anchor{ab1}
@deffn {Κλάση} zipfile.ZipFile (file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None)

Open a ZIP file, where `file' can be a path to a file (a string), a
file-like object or a @ref{79f,,path-like object}.

The `mode' parameter should be @code{'r'} to read an existing
file, @code{'w'} to truncate and write a new file, @code{'a'} to append to an
existing file, or @code{'x'} to exclusively create and write a new file.
If `mode' is @code{'x'} and `file' refers to an existing file,
a @ref{13c9,,FileExistsError} will be raised.
If `mode' is @code{'a'} and `file' refers to an existing ZIP
file, then additional files are added to it.  If `file' does not refer to a
ZIP file, then a new ZIP archive is appended to the file.  This is meant for
adding a ZIP archive to another file (such as @code{python.exe}).  If
`mode' is @code{'a'} and the file does not exist at all, it is created.
If `mode' is @code{'r'} or @code{'a'}, the file should be seekable.

`compression' is the ZIP compression method to use when writing the archive,
and should be @ref{30bf,,ZIP_STORED}, @ref{30c0,,ZIP_DEFLATED},
@ref{30c1,,ZIP_BZIP2}, @ref{30c2,,ZIP_LZMA}, or @ref{30c3,,ZIP_ZSTANDARD};
unrecognized values will cause @ref{59a,,NotImplementedError} to be raised.  If
@code{ZIP_DEFLATED}, @code{ZIP_BZIP2}, @code{ZIP_LZMA}, or
@code{ZIP_ZSTANDARD} is specified but the corresponding module
(@ref{13c,,zlib}, @ref{14,,bz2}, @ref{8d,,lzma}, or @ref{23,,compression.zstd}) is not
available, @ref{30d,,RuntimeError} is raised. The default is @code{ZIP_STORED}.

If `allowZip64' is @code{True} (the default) zipfile will create ZIP files that
use the ZIP64 extensions when the zipfile is larger than 4 GiB. If it is
@code{false} @code{zipfile} will raise an exception when the ZIP file would
require ZIP64 extensions.

The `compresslevel' parameter controls the compression level to use when
writing files to the archive.
When using @ref{30bf,,ZIP_STORED} or @ref{30c2,,ZIP_LZMA} it has no effect.
When using @ref{30c0,,ZIP_DEFLATED} integers @code{0} through @code{9} are accepted
(see @ref{19fc,,zlib} for more information).
When using @ref{30c1,,ZIP_BZIP2} integers @code{1} through @code{9} are accepted
(see @ref{c3d,,bz2} for more information).
When using @ref{30c3,,ZIP_ZSTANDARD} integers @code{-131072} through @code{22} are
commonly accepted (see
@ref{3019,,CompressionParameter.compression_level}
for more on retrieving valid values and their meaning).

The `strict_timestamps' argument, when set to @code{False}, allows to
zip files older than 1980-01-01 at the cost of setting the
timestamp to 1980-01-01.
Similar behavior occurs with files newer than 2107-12-31,
the timestamp is also set to the limit.

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.

If the file is created with mode @code{'w'}, @code{'x'} or @code{'a'} and then
@ref{30c5,,closed} without adding any files to the archive, the appropriate
ZIP structures for an empty archive will be written to the file.

ZipFile is also a context manager and therefore supports the
@ref{20a,,with} statement.  In the example, `myzip' is closed after the
@code{with} statement’s suite is finished—even if an exception occurs:

@example
with ZipFile('spam.zip', 'w') as myzip:
    myzip.write('eggs.txt')
@end example

@cartouche
@quotation Σημείωση 
`metadata_encoding' is an instance-wide setting for the ZipFile.
It is not 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


Άλλαξε στην έκδοση 3.2: Added the ability to use @code{ZipFile} as a context manager.



Άλλαξε στην έκδοση 3.3: Added support for @ref{14,,bzip2} and @ref{8d,,lzma} compression.



Άλλαξε στην έκδοση 3.4: ZIP64 extensions are enabled by default.



Άλλαξε στην έκδοση 3.5: Added support for writing to unseekable streams.
Added support for the @code{'x'} mode.



Άλλαξε στην έκδοση 3.6: Previously, a plain @ref{30d,,RuntimeError} was raised for unrecognized
compression values.



Άλλαξε στην έκδοση 3.6.2: The `file' parameter accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.7: Add the `compresslevel' parameter.



Άλλαξε στην έκδοση 3.8: The `strict_timestamps' keyword-only parameter.



Άλλαξε στην έκδοση 3.11: Added support for specifying member name encoding for reading
metadata in the zipfile’s directory and file headers.

@end deffn

@geindex close() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile close}@anchor{30c5}
@deffn {Μέθοδος} ZipFile.close ()

Close the archive file.  You must call @code{close()} before exiting your program
or essential records will not be written.
@end deffn

@geindex getinfo() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile getinfo}@anchor{30bc}
@deffn {Μέθοδος} ZipFile.getinfo (name)

Return a @ref{547,,ZipInfo} object with information about the archive member
`name'.  Calling @code{getinfo()} for a name not currently contained in the
archive will raise a @ref{7df,,KeyError}.
@end deffn

@geindex infolist() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile infolist}@anchor{30bd}
@deffn {Μέθοδος} ZipFile.infolist ()

Return a list containing a @ref{547,,ZipInfo} object for each member of the
archive.  The objects are in the same order as their entries in the actual ZIP
file on disk if an existing archive was opened.
@end deffn

@geindex namelist() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile namelist}@anchor{30c6}
@deffn {Μέθοδος} ZipFile.namelist ()

Return a list of archive members by name.
@end deffn

@geindex open() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile open}@anchor{84a}
@deffn {Μέθοδος} 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{547,,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{1c7,,bytes} object.

@code{open()} is also a context manager and therefore supports the
@ref{20a,,with} statement:

@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{16cd,,read()}, @ref{16ce,,readline()},
@ref{29bb,,readlines()}, @ref{1631,,seek()},
@ref{174f,,tell()}, @ref{229a,,__iter__()}, @ref{1672,,__next__()}.
These objects can operate independently of the ZipFile.

With @code{mode='w'}, a writable file handle is returned, which supports the
@ref{1099,,write()} method.  While a writable file handle is open,
attempting to read or write other files in the ZIP file will raise a
@ref{277,,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.

When writing a file, if the file size is not known in advance but may exceed
2 GiB, pass @code{force_zip64=True} to ensure that the header format is
capable of supporting large files.  If the file size is known in advance,
construct a @ref{547,,ZipInfo} object with @ref{30c7,,file_size} set, and
use that as the `name' parameter.

@cartouche
@quotation Σημείωση 
The @code{open()}, @ref{30c8,,read()} and @ref{30c9,,extract()} methods can take a filename
or a @ref{547,,ZipInfo} object.  You will appreciate this when trying to read a
ZIP file that contains members with duplicate names.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.6: Removed support of @code{mode='U'}.  Use @ref{b9c,,io.TextIOWrapper} for reading
compressed text files in @ref{10f1,,universal newlines} mode.



Άλλαξε στην έκδοση 3.6: @code{ZipFile.open()} can now be used to write files into the archive with the
@code{mode='w'} option.



Άλλαξε στην έκδοση 3.6: Calling @code{open()} on a closed ZipFile will raise a @ref{277,,ValueError}.
Previously, a @ref{30d,,RuntimeError} was raised.



Άλλαξε στην έκδοση 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() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile extract}@anchor{30c9}
@deffn {Μέθοδος} 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{547,,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 @code{ZipInfo} object.
`pwd' is the password used for encrypted files as a @ref{1c7,,bytes} object.

Returns the normalized path created (a directory or new file).

@cartouche
@quotation Σημείωση 
If a member filename is an absolute path, a drive/UNC sharepoint and
leading (back)slashes will be stripped, e.g.: @code{///foo/bar} becomes
@code{foo/bar} on Unix, and @code{C:\foo\bar} becomes @code{foo\bar} on Windows.
And all @code{".."} components in a member filename will be removed, e.g.:
@code{../../foo../../ba..r} becomes @code{foo../ba..r}.  On Windows illegal
characters (@code{:}, @code{<}, @code{>}, @code{|}, @code{"}, @code{?}, and @code{*})
replaced by underscore (@code{_}).
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.6: Calling @code{extract()} on a closed ZipFile will raise a
@ref{277,,ValueError}.  Previously, a @ref{30d,,RuntimeError} was raised.



Άλλαξε στην έκδοση 3.6.2: The `path' parameter accepts a @ref{79f,,path-like object}.

@end deffn

@geindex extractall() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile extractall}@anchor{30ca}
@deffn {Μέθοδος} 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{30c6,,namelist()}.  `pwd' is the password
used for encrypted files as a @ref{1c7,,bytes} object.

@cartouche
@quotation Προειδοποίηση 
Never extract archives from untrusted sources without prior inspection.
It is possible that files are created outside of `path', e.g. members
that have absolute filenames starting with @code{"/"} or filenames with two
dots @code{".."}.  This module attempts to prevent that.
See @ref{30c9,,extract()} note.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.6: Calling @code{extractall()} on a closed ZipFile will raise a
@ref{277,,ValueError}.  Previously, a @ref{30d,,RuntimeError} was raised.



Άλλαξε στην έκδοση 3.6.2: The `path' parameter accepts a @ref{79f,,path-like object}.

@end deffn

@geindex printdir() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile printdir}@anchor{30cb}
@deffn {Μέθοδος} ZipFile.printdir ()

Print a table of contents for the archive to @code{sys.stdout}.
@end deffn

@geindex setpassword() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile setpassword}@anchor{30cc}
@deffn {Μέθοδος} ZipFile.setpassword (pwd)

Set `pwd' (a @ref{1c7,,bytes} object) as default password to extract encrypted files.
@end deffn

@geindex read() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile read}@anchor{30c8}
@deffn {Μέθοδος} 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{547,,ZipInfo} object.  The archive must be open for
read or append. `pwd' is the password used for encrypted files as a @ref{1c7,,bytes}
object and, if specified, overrides the default password set with @ref{30cc,,setpassword()}.
Calling @code{read()} on a ZipFile that uses a compression method other than
@ref{30bf,,ZIP_STORED}, @ref{30c0,,ZIP_DEFLATED}, @ref{30c1,,ZIP_BZIP2},
@ref{30c2,,ZIP_LZMA}, or @ref{30c3,,ZIP_ZSTANDARD} will raise a
@ref{59a,,NotImplementedError}. An error will also be raised if the
corresponding compression module is not available.


Άλλαξε στην έκδοση 3.6: Calling @code{read()} on a closed ZipFile will raise a @ref{277,,ValueError}.
Previously, a @ref{30d,,RuntimeError} was raised.

@end deffn

@geindex testzip() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile testzip}@anchor{30cd}
@deffn {Μέθοδος} ZipFile.testzip ()

Read all the files in the archive and check their CRC’s and file headers.
Return the name of the first bad file, or else return @code{None}.


Άλλαξε στην έκδοση 3.6: Calling @code{testzip()} on a closed ZipFile will raise a
@ref{277,,ValueError}.  Previously, a @ref{30d,,RuntimeError} was raised.

@end deffn

@geindex write() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile write}@anchor{1102}
@deffn {Μέθοδος} ZipFile.write (filename, arcname=None, compress_type=None, compresslevel=None)

Write the file named `filename' to the archive, giving it the archive name
`arcname' (by default, this will be the same as `filename', but without a drive
letter and with leading path separators removed).  If given, `compress_type'
overrides the value given for the `compression' parameter to the constructor for
the new entry. Similarly, `compresslevel' will override the constructor if
given.
The archive must be open with mode @code{'w'}, @code{'x'} or @code{'a'}.

@cartouche
@quotation Σημείωση 
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 Σημείωση 
Archive names should be relative to the archive root, that is, they should not
start with a path separator.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
If @code{arcname} (or @code{filename}, if @code{arcname} is  not given) contains a null
byte, the name of the file in the archive will be truncated at the null byte.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
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


Άλλαξε στην έκδοση 3.6: Calling @code{write()} on a ZipFile created with mode @code{'r'} or
a closed ZipFile will raise a @ref{277,,ValueError}.  Previously,
a @ref{30d,,RuntimeError} was raised.

@end deffn

@geindex writestr() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile writestr}@anchor{548}
@deffn {Μέθοδος} ZipFile.writestr (zinfo_or_arcname, data, compress_type=None, compresslevel=None)

Write a file into the archive.  The contents is `data', which may be either
a @ref{1df,,str} or a @ref{1c7,,bytes} instance; if it is a @code{str},
it is encoded as UTF-8 first.  `zinfo_or_arcname' is either the file
name it will be given in the archive, or a @ref{547,,ZipInfo} instance.  If it’s
an instance, at least the filename, date, and time must be given.  If it’s a
name, the date and time is set to the current date and time.
The archive must be opened with mode @code{'w'}, @code{'x'} or @code{'a'}.

If given, `compress_type' overrides the value given for the `compression'
parameter to the constructor for the new entry, or in the `zinfo_or_arcname'
(if that is a @ref{547,,ZipInfo} instance). Similarly, `compresslevel' will
override the constructor if given.

@cartouche
@quotation Σημείωση 
When passing a @ref{547,,ZipInfo} instance as the `zinfo_or_arcname' parameter,
the compression method used will be that specified in the `compress_type'
member of the given @code{ZipInfo} instance.  By default, the
@code{ZipInfo} constructor sets this member to @ref{30bf,,ZIP_STORED}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.2: The `compress_type' argument.



Άλλαξε στην έκδοση 3.6: Calling @code{writestr()} on a ZipFile created with mode @code{'r'} or
a closed ZipFile will raise a @ref{277,,ValueError}.  Previously,
a @ref{30d,,RuntimeError} was raised.



Άλλαξε στην έκδοση 3.14: Now respects the 
@geindex SOURCE_DATE_EPOCH
@geindex μεταβλητή περιβάλλοντος; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} environment variable.
If set, it uses this value as the modification timestamp for the file
written into the ZIP archive, instead of using the current time.

@end deffn

@geindex mkdir() (μέθοδος της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile mkdir}@anchor{ab2}
@deffn {Μέθοδος} 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{547,,ZipInfo} instance then the `mode' argument is ignored.

The archive must be opened with mode @code{'w'}, @code{'x'} or @code{'a'}.


Added in version 3.11.

@end deffn

The following data attributes are also available:

@geindex filename (ιδιότητα της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile filename}@anchor{30ce}
@deffn {Ιδιότητα} ZipFile.filename

Name of the ZIP file.
@end deffn

@geindex debug (ιδιότητα της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile debug}@anchor{30cf}
@deffn {Ιδιότητα} ZipFile.debug

The level of debug output to use.  This may be set from @code{0} (the default, no
output) to @code{3} (the most output).  Debugging information is written to
@code{sys.stdout}.
@end deffn

@geindex comment (ιδιότητα της zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile comment}@anchor{30d0}
@deffn {Ιδιότητα} ZipFile.comment

The comment associated with the ZIP file as a @ref{1c7,,bytes} object.
If assigning a comment to a
@ref{ab1,,ZipFile} instance created with mode @code{'w'}, @code{'x'} or @code{'a'},
it should be no longer than 65535 bytes.  Comments longer than this will be
truncated.
@end deffn

@node Path objects,PyZipFile objects,ZipFile objects,zipfile — Work with ZIP archives
@anchor{library/zipfile id2}@anchor{30d1}@anchor{library/zipfile path-objects}@anchor{30d2}
@subsubsection Path objects


@geindex Path (κλάση σε zipfile)
@anchor{library/zipfile zipfile Path}@anchor{ab6}
@deffn {Κλάση} zipfile.Path (root, at='@w{'})

Construct a Path object from a @code{root} zipfile (which may be a
@ref{ab1,,ZipFile} instance or @code{file} suitable for passing to
the @code{ZipFile} constructor).

@code{at} specifies the location of this Path within the zipfile,
e.g. “dir/file.txt”, “dir/”, or “”. Defaults to the empty string,
indicating the root.

@cartouche
@quotation Σημείωση 
The @code{Path} class does not sanitize filenames within the ZIP archive. Unlike
the @ref{30c9,,ZipFile.extract()} and @ref{30ca,,ZipFile.extractall()} methods, it is the
caller’s responsibility to validate or sanitize filenames to prevent path traversal
vulnerabilities (e.g., filenames containing «..» or absolute paths). When handling
untrusted archives, consider resolving filenames using @ref{16bf,,os.path.abspath()}
and checking against the target directory with @ref{334,,os.path.commonpath()}.
@end quotation
@end cartouche
@end deffn

Path objects expose the following features of @ref{4ee,,pathlib.Path}
objects:

Path objects are traversable using the @code{/} operator or @code{joinpath}.

@geindex name (ιδιότητα της zipfile.Path)
@anchor{library/zipfile zipfile Path name}@anchor{30d3}
@deffn {Ιδιότητα} Path.name

The final path component.
@end deffn

@geindex open() (μέθοδος της zipfile.Path)
@anchor{library/zipfile zipfile Path open}@anchor{1a13}
@deffn {Μέθοδος} Path.open (mode='r', *, pwd, **)

Invoke @ref{84a,,ZipFile.open()} on the current path.
Allows opening for read or write, text or binary
through supported modes: “r”, “w”, “rb”, “wb”.
Positional and keyword arguments are passed through to
@ref{b9c,,io.TextIOWrapper} when opened as text and
ignored otherwise.
@code{pwd} is the @code{pwd} parameter to
@code{ZipFile.open()}.


Άλλαξε στην έκδοση 3.9: Added support for text and binary modes for open. Default
mode is now text.



Άλλαξε στην έκδοση 3.11.2: The @code{encoding} parameter can be supplied as a positional argument
without causing a @ref{291,,TypeError}. As it could in 3.9. Code needing to
be compatible with unpatched 3.10 and 3.11 versions must pass all
@ref{b9c,,io.TextIOWrapper} arguments, @code{encoding} included, as keywords.

@end deffn

@geindex iterdir() (μέθοδος της zipfile.Path)
@anchor{library/zipfile zipfile Path iterdir}@anchor{30d4}
@deffn {Μέθοδος} Path.iterdir ()

Enumerate the children of the current directory.
@end deffn

@geindex is_dir() (μέθοδος της zipfile.Path)
@anchor{library/zipfile zipfile Path is_dir}@anchor{30d5}
@deffn {Μέθοδος} Path.is_dir ()

Return @code{True} if the current context references a directory.
@end deffn

@geindex is_file() (μέθοδος της zipfile.Path)
@anchor{library/zipfile zipfile Path is_file}@anchor{30d6}
@deffn {Μέθοδος} Path.is_file ()

Return @code{True} if the current context references a file.
@end deffn

@geindex is_symlink() (μέθοδος της zipfile.Path)
@anchor{library/zipfile zipfile Path is_symlink}@anchor{30d7}
@deffn {Μέθοδος} Path.is_symlink ()

Return @code{True} if the current context references a symbolic link.


Added in version 3.12.



Άλλαξε στην έκδοση 3.13: Previously, @code{is_symlink} would unconditionally return @code{False}.

@end deffn

@geindex exists() (μέθοδος της zipfile.Path)
@anchor{library/zipfile zipfile Path exists}@anchor{30d8}
@deffn {Μέθοδος} Path.exists ()

Return @code{True} if the current context references a file or
directory in the zip file.
@end deffn

@geindex Path.suffix (στη μονάδα zipfile)
@anchor{library/zipfile zipfile Path suffix}@anchor{ab4}
@deffn {Δεδομένα} Path.suffix

The last dot-separated portion of the final component, if any.
This is commonly called the file extension.


Added in version 3.11: Added @code{Path.suffix} property.

@end deffn

@geindex Path.stem (στη μονάδα zipfile)
@anchor{library/zipfile zipfile Path stem}@anchor{ab3}
@deffn {Δεδομένα} Path.stem

The final path component, without its suffix.


Added in version 3.11: Added @code{Path.stem} property.

@end deffn

@geindex Path.suffixes (στη μονάδα zipfile)
@anchor{library/zipfile zipfile Path suffixes}@anchor{ab5}
@deffn {Δεδομένα} Path.suffixes

A list of the path’s suffixes, commonly called file extensions.


Added in version 3.11: Added @code{Path.suffixes} property.

@end deffn

@geindex read_text() (μέθοδος της zipfile.Path)
@anchor{library/zipfile zipfile Path read_text}@anchor{1cdd}
@deffn {Μέθοδος} Path.read_text (*, **)

Read the current file as unicode text. Positional and
keyword arguments are passed through to
@ref{b9c,,io.TextIOWrapper} (except @code{buffer}, which is
implied by the context).


Άλλαξε στην έκδοση 3.11.2: The @code{encoding} parameter can be supplied as a positional argument
without causing a @ref{291,,TypeError}. As it could in 3.9. Code needing to
be compatible with unpatched 3.10 and 3.11 versions must pass all
@ref{b9c,,io.TextIOWrapper} arguments, @code{encoding} included, as keywords.

@end deffn

@geindex read_bytes() (μέθοδος της zipfile.Path)
@anchor{library/zipfile zipfile Path read_bytes}@anchor{30d9}
@deffn {Μέθοδος} Path.read_bytes ()

Read the current file as bytes.
@end deffn

@geindex joinpath() (μέθοδος της zipfile.Path)
@anchor{library/zipfile zipfile Path joinpath}@anchor{30da}
@deffn {Μέθοδος} 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


Άλλαξε στην έκδοση 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 PyZipFile objects,ZipInfo objects,Path objects,zipfile — Work with ZIP archives
@anchor{library/zipfile id3}@anchor{30db}@anchor{library/zipfile pyzipfile-objects}@anchor{30dc}
@subsubsection PyZipFile objects


The @ref{13a2,,PyZipFile} constructor takes the same parameters as the
@ref{ab1,,ZipFile} constructor, and one additional parameter, `optimize'.

@geindex PyZipFile (κλάση σε zipfile)
@anchor{library/zipfile zipfile PyZipFile}@anchor{13a2}
@deffn {Κλάση} zipfile.PyZipFile (file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)


Άλλαξε στην έκδοση 3.2: Added the `optimize' parameter.



Άλλαξε στην έκδοση 3.4: ZIP64 extensions are enabled by default.


Instances have one method in addition to those of @ref{ab1,,ZipFile} objects:

@geindex writepy() (μέθοδος της zipfile.PyZipFile)
@anchor{library/zipfile zipfile PyZipFile writepy}@anchor{13a1}
@deffn {Μέθοδος} writepy (pathname, basename='@w{'}, filterfunc=None)

Search for files @code{*.py} and add the corresponding file to the
archive.

If the `optimize' parameter to @code{PyZipFile} was not given or @code{-1},
the corresponding file is a @code{*.pyc} file, compiling if necessary.

If the `optimize' parameter to @code{PyZipFile} was @code{0}, @code{1} or
@code{2}, only files with that optimization level (see @ref{1c8,,compile()}) are
added to the archive, compiling if necessary.

If `pathname' is a file, the filename must end with @code{.py}, and
just the (corresponding @code{*.pyc}) file is added at the top level
(no path information).  If `pathname' is a file that does not end with
@code{.py}, a @ref{30d,,RuntimeError} will be raised.  If it is a directory,
and the directory is not a package directory, then all the files
@code{*.pyc} are added at the top level.  If the directory is a
package directory, then all @code{*.pyc} are added under the package
name as a file path, and if any subdirectories are package directories,
all of these are added recursively in sorted order.

`basename' is intended for internal use only.

`filterfunc', if given, must be a function taking a single string
argument.  It will be passed each path (including each individual full
file path) before it is added to the archive.  If `filterfunc' returns a
false value, the path will not be added, and if it is a directory its
contents will be ignored.  For example, if our test files are all either
in @code{test} directories or start with the string @code{test_}, we can use a
`filterfunc' to exclude them:

@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

The @code{writepy()} method makes archives with file names like
this:

@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


Άλλαξε στην έκδοση 3.4: Added the `filterfunc' parameter.



Άλλαξε στην έκδοση 3.6.2: The `pathname' parameter accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.7: Recursion sorts directory entries.

@end deffn
@end deffn

@node ZipInfo objects,Command-line interface<3>,PyZipFile objects,zipfile — Work with ZIP archives
@anchor{library/zipfile id4}@anchor{30dd}@anchor{library/zipfile zipinfo-objects}@anchor{30be}
@subsubsection ZipInfo objects


Instances of the @ref{547,,ZipInfo} class are returned by the @ref{30bc,,getinfo()} and
@ref{30bd,,infolist()} methods of @ref{ab1,,ZipFile} objects.  Each object stores
information about a single member of the ZIP archive.

There is one classmethod to make a @ref{547,,ZipInfo} instance for a filesystem
file:

@geindex from_file() (μέθοδος κλάσης της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo from_file}@anchor{10c5}
@deffn {Μέθοδος} classmethod ZipInfo.from_file (filename, arcname=None, *, strict_timestamps=True)

Construct a @ref{547,,ZipInfo} instance for a file on the filesystem, in
preparation for adding it to a zip file.

`filename' should be the path to a file or directory on the filesystem.

If `arcname' is specified, it is used as the name within the archive.
If `arcname' is not specified, the name will be the same as `filename', but
with any drive letter and leading path separators removed.

The `strict_timestamps' argument, when set to @code{False}, allows to
zip files older than 1980-01-01 at the cost of setting the
timestamp to 1980-01-01.
Similar behavior occurs with files newer than 2107-12-31,
the timestamp is also set to the limit.


Added in version 3.6.



Άλλαξε στην έκδοση 3.6.2: The `filename' parameter accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.8: Added the `strict_timestamps' keyword-only parameter.

@end deffn

Instances have the following methods and attributes:

@geindex is_dir() (μέθοδος της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo is_dir}@anchor{10c6}
@deffn {Μέθοδος} ZipInfo.is_dir ()

Return @code{True} if this archive member is a directory.

This uses the entry’s name: directories should always end with @code{/}.


Added in version 3.6.

@end deffn

@geindex filename (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo filename}@anchor{30de}
@deffn {Ιδιότητα} ZipInfo.filename

Name of the file in the archive.
@end deffn

@geindex date_time (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo date_time}@anchor{30df}
@deffn {Ιδιότητα} ZipInfo.date_time

The time and date of the last modification to the archive member.  This is a
tuple of six values representing the «last [modified] file time» and «last [modified] file date»
fields from the ZIP file’s central directory.

The tuple contains:


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Value

@item

@code{0}

@tab

Year (>= 1980)

@item

@code{1}

@tab

Month (one-based)

@item

@code{2}

@tab

Day of month (one-based)

@item

@code{3}

@tab

Hours (zero-based)

@item

@code{4}

@tab

Minutes (zero-based)

@item

@code{5}

@tab

Seconds (zero-based)

@end multitable


@cartouche
@quotation Σημείωση 
The ZIP format supports multiple timestamp fields in different locations
(central directory, extra fields for NTFS/UNIX systems, etc.). This attribute
specifically returns the timestamp from the central directory. The central
directory timestamp format in ZIP files does not support timestamps before
1980. While some extra field formats (such as UNIX timestamps) can represent
earlier dates, this attribute only returns the central directory timestamp.

The central directory timestamp is interpreted as representing local
time, rather than UTC time, to match the behavior of other zip tools.
@end quotation
@end cartouche
@end deffn

@geindex compress_type (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo compress_type}@anchor{30e0}
@deffn {Ιδιότητα} ZipInfo.compress_type

Type of compression for the archive member.
@end deffn

@geindex comment (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo comment}@anchor{30e1}
@deffn {Ιδιότητα} ZipInfo.comment

Comment for the individual archive member as a @ref{1c7,,bytes} object.
@end deffn

@geindex extra (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo extra}@anchor{30e2}
@deffn {Ιδιότητα} ZipInfo.extra

Expansion field data.  The PKZIP Application Note@footnote{https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT} contains
some comments on the internal structure of the data contained in this
@ref{1c7,,bytes} object.
@end deffn

@geindex create_system (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo create_system}@anchor{30e3}
@deffn {Ιδιότητα} ZipInfo.create_system

System which created ZIP archive.
@end deffn

@geindex create_version (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo create_version}@anchor{30e4}
@deffn {Ιδιότητα} ZipInfo.create_version

PKZIP version which created ZIP archive.
@end deffn

@geindex extract_version (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo extract_version}@anchor{30e5}
@deffn {Ιδιότητα} ZipInfo.extract_version

PKZIP version needed to extract archive.
@end deffn

@geindex reserved (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo reserved}@anchor{30e6}
@deffn {Ιδιότητα} ZipInfo.reserved

Must be zero.
@end deffn

@geindex flag_bits (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo flag_bits}@anchor{30e7}
@deffn {Ιδιότητα} ZipInfo.flag_bits

ZIP flag bits.
@end deffn

@geindex volume (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo volume}@anchor{30e8}
@deffn {Ιδιότητα} ZipInfo.volume

Volume number of file header.
@end deffn

@geindex internal_attr (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo internal_attr}@anchor{30e9}
@deffn {Ιδιότητα} ZipInfo.internal_attr

Internal attributes.
@end deffn

@geindex external_attr (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo external_attr}@anchor{30ea}
@deffn {Ιδιότητα} ZipInfo.external_attr

External file attributes.
@end deffn

@geindex header_offset (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo header_offset}@anchor{30eb}
@deffn {Ιδιότητα} ZipInfo.header_offset

Byte offset to the file header.
@end deffn

@geindex CRC (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo CRC}@anchor{30ec}
@deffn {Ιδιότητα} ZipInfo.CRC

CRC-32 of the uncompressed file.
@end deffn

@geindex compress_size (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo compress_size}@anchor{30ed}
@deffn {Ιδιότητα} ZipInfo.compress_size

Size of the compressed data.
@end deffn

@geindex file_size (ιδιότητα της zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo file_size}@anchor{30c7}
@deffn {Ιδιότητα} ZipInfo.file_size

Size of the uncompressed file.
@end deffn

@node Command-line interface<3>,Decompression pitfalls,ZipInfo objects,zipfile — Work with ZIP archives
@anchor{library/zipfile command-line-interface}@anchor{30ee}@anchor{library/zipfile zipfile-commandline}@anchor{30ef}
@subsubsection Command-line interface


The @code{zipfile} module provides a simple command-line interface to interact
with ZIP archives.

If you want to create a new ZIP archive, specify its name after the @ref{30f0,,-c}
option and then list the filename(s) that should be included:

@example
$ python -m zipfile -c monty.zip spam.txt eggs.txt
@end example

Passing a directory is also acceptable:

@example
$ python -m zipfile -c monty.zip life-of-brian_1979/
@end example

If you want to extract a ZIP archive into the specified directory, use
the @ref{30f1,,-e} option:

@example
$ python -m zipfile -e monty.zip target-dir/
@end example

For a list of the files in a ZIP archive, use the @ref{30f2,,-l} option:

@example
$ python -m zipfile -l monty.zip
@end example

@menu
* Command-line options:: 

@end menu

@node Command-line options,,,Command-line interface<3>
@anchor{library/zipfile command-line-options}@anchor{30f3}
@subsubsection Command-line options


@geindex zipfile command line option; -l
@geindex zipfile command line option; --list
@anchor{library/zipfile cmdoption-zipfile-l}@anchor{30f2}
@deffn {Option} @w{-}l <zipfile>
@anchor{library/zipfile cmdoption-zipfile-list}@anchor{30f4}
@deffnx {Option} @w{-}@w{-}list <zipfile>

List files in a zipfile.
@end deffn

@geindex zipfile command line option; -c
@geindex zipfile command line option; --create
@anchor{library/zipfile cmdoption-zipfile-c}@anchor{30f0}
@deffn {Option} @w{-}c <zipfile> <source1> ... <sourceN>
@anchor{library/zipfile cmdoption-zipfile-create}@anchor{30f5}
@deffnx {Option} @w{-}@w{-}create <zipfile> <source1> ... <sourceN>

Create zipfile from source files.
@end deffn

@geindex zipfile command line option; -e
@geindex zipfile command line option; --extract
@anchor{library/zipfile cmdoption-zipfile-e}@anchor{30f1}
@deffn {Option} @w{-}e <zipfile> <output_dir>
@anchor{library/zipfile cmdoption-zipfile-extract}@anchor{30f6}
@deffnx {Option} @w{-}@w{-}extract <zipfile> <output_dir>

Extract zipfile into target directory.
@end deffn

@geindex zipfile command line option; -t
@geindex zipfile command line option; --test
@anchor{library/zipfile cmdoption-zipfile-t}@anchor{30f7}
@deffn {Option} @w{-}t <zipfile>
@anchor{library/zipfile cmdoption-zipfile-test}@anchor{30f8}
@deffnx {Option} @w{-}@w{-}test <zipfile>

Test whether the zipfile is valid or not.
@end deffn

@geindex zipfile command line option; --metadata-encoding
@anchor{library/zipfile cmdoption-zipfile-metadata-encoding}@anchor{30f9}
@deffn {Option} @w{-}@w{-}metadata@w{-}encoding <encoding>

Specify encoding of member names for @ref{30f2,,-l}, @ref{30f1,,-e} and
@ref{30f7,,-t}.


Added in version 3.11.

@end deffn

@node Decompression pitfalls,,Command-line interface<3>,zipfile — Work with ZIP archives
@anchor{library/zipfile decompression-pitfalls}@anchor{30fa}
@subsubsection Decompression pitfalls


The extraction in zipfile module might fail due to some pitfalls listed below.

@menu
* From file itself:: 
* File system limitations:: 
* Resources limitations:: 
* Interruption:: 
* Default behaviors of extraction:: 

@end menu

@node From file itself,File system limitations,,Decompression pitfalls
@anchor{library/zipfile from-file-itself}@anchor{30fb}
@subsubsection From file itself


Decompression may fail due to incorrect password / CRC checksum / ZIP format or
unsupported compression method / decryption.

@node File system limitations,Resources limitations,From file itself,Decompression pitfalls
@anchor{library/zipfile file-system-limitations}@anchor{30fc}
@subsubsection File system limitations


Exceeding limitations on different file systems can cause decompression failed.
Such as allowable characters in the directory entries, length of the file name,
length of the pathname, size of a single file, and number of files, etc.

@node Resources limitations,Interruption,File system limitations,Decompression pitfalls
@anchor{library/zipfile resources-limitations}@anchor{30fd}@anchor{library/zipfile zipfile-resources-limitations}@anchor{30fe}
@subsubsection Resources limitations


The lack of memory or disk volume would lead to decompression
failed. For example, decompression bombs (aka ZIP bomb@footnote{https://en.wikipedia.org/wiki/Zip_bomb})
apply to zipfile library that can cause disk volume exhaustion.

@node Interruption,Default behaviors of extraction,Resources limitations,Decompression pitfalls
@anchor{library/zipfile interruption}@anchor{30ff}
@subsubsection Interruption


Interruption during the decompression, such as pressing control-C or killing the
decompression process may result in incomplete decompression of the archive.

@node Default behaviors of extraction,,Interruption,Decompression pitfalls
@anchor{library/zipfile default-behaviors-of-extraction}@anchor{3100}
@subsubsection Default behaviors of extraction


Not knowing the default extraction behaviors
can cause unexpected decompression results.
For example, when extracting the same archive twice,
it overwrites files without asking.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tarfile — Read and write tar archive files,,zipfile — Work with ZIP archives,Data Compression and Archiving
@anchor{library/tarfile doc}@anchor{3101}@anchor{library/tarfile module-tarfile}@anchor{e7}@anchor{library/tarfile tarfile-read-and-write-tar-archive-files}@anchor{3102}@anchor{library/tarfile translation-repo}@anchor{3103}
@subsection @code{tarfile} — Read and write tar archive files


@geindex module; tarfile

`Source code:' Lib/tarfile.py@footnote{https://github.com/python/cpython/tree/main/Lib/tarfile.py}


__________________________________________________________________


The @code{tarfile} module makes it possible to read and write tar
archives, including those using gzip, bz2 and lzma compression.
Use the @ref{13a,,zipfile} module to read or write @code{.zip} files, or the
higher-level functions in @ref{15bf,,shutil}.

Some facts and figures:


@itemize *

@item 
reads and writes @ref{6a,,gzip}, @ref{14,,bz2}, @ref{23,,compression.zstd}, and
@ref{8d,,lzma} compressed archives if the respective modules are available.

@c The following paragraph should be similar to ../includes/optional-module.rst

If any of these @ref{2347,,optional modules} are missing from
your copy of CPython, look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@item 
read/write support for the POSIX.1-1988 (ustar) format.

@item 
read/write support for the GNU tar format including `longname' and `longlink'
extensions, read-only support for all variants of the `sparse' extension
including restoration of sparse files.

@item 
read/write support for the POSIX.1-2001 (pax) format.

@item 
handles directories, regular files, hardlinks, symbolic links, fifos,
character devices and block devices and is able to acquire and restore file
information like timestamp, access permissions and owner.
@end itemize


Άλλαξε στην έκδοση 3.3: Added support for @ref{8d,,lzma} compression.



Άλλαξε στην έκδοση 3.12: Archives are extracted using a @ref{883,,filter},
which makes it possible to either limit surprising/dangerous features,
or to acknowledge that they are expected and the archive is fully trusted.



Άλλαξε στην έκδοση 3.14: Set the default extraction filter to @ref{279,,data},
which disallows some dangerous features such as links to absolute paths
or paths outside of the destination. Previously, the filter strategy
was equivalent to @ref{3104,,fully_trusted}.



Άλλαξε στην έκδοση 3.14: Added support for Zstandard compression using @ref{23,,compression.zstd}.


@geindex open() (στη μονάδα tarfile)
@anchor{library/tarfile tarfile open}@anchor{1228}
@deffn {Συνάρτηση} tarfile.open (name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

Return a @ref{15b7,,TarFile} object for the pathname `name'. For detailed
information on @code{TarFile} objects and the keyword arguments that are
allowed, see @ref{3105,,TarFile Objects}.

`mode' has to be a string of the form @code{'filemode[:compression]'}, it defaults
to @code{'r'}. Here is a full list of mode combinations:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

mode

@tab

action

@item

@code{'r'} or
@code{'r:*'}

@tab

Open for reading with transparent
compression (recommended).

@item

@code{'r:'}

@tab

Open for reading exclusively without
compression.

@item

@code{'r:gz'}

@tab

Open for reading with gzip compression.

@item

@code{'r:bz2'}

@tab

Open for reading with bzip2 compression.

@item

@code{'r:xz'}

@tab

Open for reading with lzma compression.

@item

@code{'r:zst'}

@tab

Open for reading with Zstandard compression.

@item

@code{'x'} or
@code{'x:'}

@tab

Create a tarfile exclusively without
compression.
Raise a @ref{13c9,,FileExistsError} exception
if it already exists.

@item

@code{'x:gz'}

@tab

Create a tarfile with gzip compression.
Raise a @ref{13c9,,FileExistsError} exception
if it already exists.

@item

@code{'x:bz2'}

@tab

Create a tarfile with bzip2 compression.
Raise a @ref{13c9,,FileExistsError} exception
if it already exists.

@item

@code{'x:xz'}

@tab

Create a tarfile with lzma compression.
Raise a @ref{13c9,,FileExistsError} exception
if it already exists.

@item

@code{'x:zst'}

@tab

Create a tarfile with Zstandard compression.
Raise a @ref{13c9,,FileExistsError} exception
if it already exists.

@item

@code{'a'} or
@code{'a:'}

@tab

Open for appending with no compression. The
file is created if it does not exist.

@item

@code{'w'} or
@code{'w:'}

@tab

Open for uncompressed writing.

@item

@code{'w:gz'}

@tab

Open for gzip compressed writing.

@item

@code{'w:bz2'}

@tab

Open for bzip2 compressed writing.

@item

@code{'w:xz'}

@tab

Open for lzma compressed writing.

@item

@code{'w:zst'}

@tab

Open for Zstandard compressed writing.

@end multitable


Note that @code{'a:gz'}, @code{'a:bz2'} or @code{'a:xz'} is not possible. If `mode'
is not suitable to open a certain (compressed) file for reading,
@ref{1e46,,ReadError} is raised. Use `mode' @code{'r'} to avoid this.  If a
compression method is not supported, @ref{3106,,CompressionError} is raised.

If `fileobj' is specified, it is used as an alternative to a @ref{156c,,file object}
opened in binary mode for `name'. It is supposed to be at position 0.

For modes @code{'w:gz'}, @code{'x:gz'}, @code{'w|gz'}, @code{'w:bz2'}, @code{'x:bz2'},
@code{'w|bz2'}, @ref{1228,,tarfile.open()} accepts the keyword argument
`compresslevel' (default @code{6}) to specify the compression level of the file.

For modes @code{'w:xz'}, @code{'x:xz'} and @code{'w|xz'}, @ref{1228,,tarfile.open()} accepts the
keyword argument `preset' to specify the compression level of the file.

For modes @code{'w:zst'}, @code{'x:zst'} and @code{'w|zst'}, @ref{1228,,tarfile.open()}
accepts the keyword argument `level' to specify the compression level of
the file. The keyword argument `options' may also be passed, providing
advanced Zstandard compression parameters described by
@ref{300d,,CompressionParameter}. The keyword argument
`zstd_dict' can be passed to provide a @ref{300c,,ZstdDict},
a Zstandard dictionary used to improve compression of smaller amounts of
data.

For modes @code{'w:gz'} and @code{'w|gz'}, @ref{1228,,tarfile.open()} accepts the
keyword argument `mtime' to create a gzip archive header with that mtime. By
default, the mtime is set to the time of creation of the archive.

For special purposes, there is a second format for `mode':
@code{'filemode|[compression]'}.  @ref{1228,,tarfile.open()} will return a @ref{15b7,,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{11d0,,read()} or @ref{174e,,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{156c,,file object} or a tape device.
However, such a @code{TarFile} object is limited in that it does
not allow random access, see @ref{3107,,Examples}.  The currently
possible modes:


@multitable {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Mode

@tab

Action

@item

@code{'r|*'}

@tab

Open a `stream' of tar blocks for reading
with transparent compression.

@item

@code{'r|'}

@tab

Open a `stream' of uncompressed tar blocks
for reading.

@item

@code{'r|gz'}

@tab

Open a gzip compressed `stream' for
reading.

@item

@code{'r|bz2'}

@tab

Open a bzip2 compressed `stream' for
reading.

@item

@code{'r|xz'}

@tab

Open an lzma compressed `stream' for
reading.

@item

@code{'r|zst'}

@tab

Open a Zstandard compressed `stream' for
reading.

@item

@code{'w|'}

@tab

Open an uncompressed `stream' for writing.

@item

@code{'w|gz'}

@tab

Open a gzip compressed `stream' for
writing.

@item

@code{'w|bz2'}

@tab

Open a bzip2 compressed `stream' for
writing.

@item

@code{'w|xz'}

@tab

Open an lzma compressed `stream' for
writing.

@item

@code{'w|zst'}

@tab

Open a Zstandard compressed `stream' for
writing.

@end multitable



Άλλαξε στην έκδοση 3.5: The @code{'x'} (exclusive creation) mode was added.



Άλλαξε στην έκδοση 3.6: The `name' parameter accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.12: The `compresslevel' keyword argument also works for streams.



Άλλαξε στην έκδοση 3.14: The `preset' keyword argument also works for streams.



Άλλαξε στην έκδοση 3.15: The default compression level was reduced to 6 (down from 9).
It is the default level used by most compression tools and a better
tradeoff between speed and performance.

@end deffn


@deffn {Κλάση} tarfile.TarFile

Class for reading and writing tar archives. Do not use this class directly:
use @ref{1228,,tarfile.open()} instead. See @ref{3105,,TarFile Objects}.
@end deffn

@geindex is_tarfile() (στη μονάδα tarfile)
@anchor{library/tarfile tarfile is_tarfile}@anchor{1dd4}
@deffn {Συνάρτηση} tarfile.is_tarfile (name)

Return @ref{fcc,,True} if `name' is a tar archive file, that the @code{tarfile}
module can read. `name' may be a @ref{1df,,str}, file, or file-like object.


Άλλαξε στην έκδοση 3.9: Support for file and file-like objects.

@end deffn

The @code{tarfile} module defines the following exceptions:

@geindex TarError
@anchor{library/tarfile tarfile TarError}@anchor{3108}
@deffn {Εξαίρεση} tarfile.TarError

Base class for all @code{tarfile} exceptions.
@end deffn

@geindex ReadError
@anchor{library/tarfile tarfile ReadError}@anchor{1e46}
@deffn {Εξαίρεση} tarfile.ReadError

Is raised when a tar archive is opened, that either cannot be handled by the
@code{tarfile} module or is somehow invalid.
@end deffn

@geindex CompressionError
@anchor{library/tarfile tarfile CompressionError}@anchor{3106}
@deffn {Εξαίρεση} tarfile.CompressionError

Is raised when a compression method is not supported or when the data cannot be
decoded properly.
@end deffn

@geindex StreamError
@anchor{library/tarfile tarfile StreamError}@anchor{3109}
@deffn {Εξαίρεση} tarfile.StreamError

Is raised for the limitations that are typical for stream-like @ref{15b7,,TarFile}
objects.
@end deffn

@geindex ExtractError
@anchor{library/tarfile tarfile ExtractError}@anchor{310a}
@deffn {Εξαίρεση} tarfile.ExtractError

Is raised for `non-fatal' errors when using @ref{27b,,TarFile.extract()}, but only if
@ref{27d,,TarFile.errorlevel}@code{== 2}.
@end deffn

@geindex HeaderError
@anchor{library/tarfile tarfile HeaderError}@anchor{310b}
@deffn {Εξαίρεση} tarfile.HeaderError

Is raised by @ref{310c,,TarInfo.frombuf()} if the buffer it gets is invalid.
@end deffn

@geindex FilterError
@anchor{library/tarfile tarfile FilterError}@anchor{310d}
@deffn {Εξαίρεση} tarfile.FilterError

Base class for members @ref{310e,,refused} by
filters.

@geindex tarinfo (ιδιότητα της tarfile.FilterError)
@anchor{library/tarfile tarfile FilterError tarinfo}@anchor{310f}
@deffn {Ιδιότητα} tarinfo

Information about the member that the filter refused to extract,
as @ref{3110,,TarInfo}.
@end deffn
@end deffn

@geindex AbsolutePathError
@anchor{library/tarfile tarfile AbsolutePathError}@anchor{3111}
@deffn {Εξαίρεση} tarfile.AbsolutePathError

Raised to refuse extracting a member with an absolute path.
@end deffn

@geindex OutsideDestinationError
@anchor{library/tarfile tarfile OutsideDestinationError}@anchor{3112}
@deffn {Εξαίρεση} tarfile.OutsideDestinationError

Raised to refuse extracting a member outside the destination directory.
@end deffn

@geindex SpecialFileError
@anchor{library/tarfile tarfile SpecialFileError}@anchor{3113}
@deffn {Εξαίρεση} 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{3114}
@deffn {Εξαίρεση} tarfile.AbsoluteLinkError

Raised to refuse extracting a symbolic link with an absolute path.
@end deffn

@geindex LinkOutsideDestinationError
@anchor{library/tarfile tarfile LinkOutsideDestinationError}@anchor{3115}
@deffn {Εξαίρεση} tarfile.LinkOutsideDestinationError

Raised to refuse extracting a symbolic link pointing outside the destination
directory.
@end deffn

@geindex LinkFallbackError
@anchor{library/tarfile tarfile LinkFallbackError}@anchor{27c}
@deffn {Εξαίρεση} tarfile.LinkFallbackError

Raised to refuse emulating a link (hard or symbolic) by extracting another
archive member, when that member would be rejected by the filter location.
The exception that was raised to reject the replacement member is available
as @code{BaseException.__context__}.


Added in version 3.15.

@end deffn

The following constants are available at the module level:

@geindex ENCODING (στη μονάδα tarfile)
@anchor{library/tarfile tarfile ENCODING}@anchor{3116}
@deffn {Δεδομένα} tarfile.ENCODING

The default character encoding: @code{'utf-8'} on Windows, the value returned by
@ref{1017,,sys.getfilesystemencoding()} otherwise.
@end deffn

@geindex REGTYPE (στη μονάδα tarfile)
@geindex AREGTYPE (στη μονάδα tarfile)
@anchor{library/tarfile tarfile REGTYPE}@anchor{3117}
@deffn {Δεδομένα} tarfile.REGTYPE
@anchor{library/tarfile tarfile AREGTYPE}@anchor{3118}
@deffnx {Δεδομένα} tarfile.AREGTYPE

A regular file @ref{3119,,type}.
@end deffn

@geindex LNKTYPE (στη μονάδα tarfile)
@anchor{library/tarfile tarfile LNKTYPE}@anchor{311a}
@deffn {Δεδομένα} tarfile.LNKTYPE

A link (inside tarfile) @ref{3119,,type}.
@end deffn

@geindex SYMTYPE (στη μονάδα tarfile)
@anchor{library/tarfile tarfile SYMTYPE}@anchor{311b}
@deffn {Δεδομένα} tarfile.SYMTYPE

A symbolic link @ref{3119,,type}.
@end deffn

@geindex CHRTYPE (στη μονάδα tarfile)
@anchor{library/tarfile tarfile CHRTYPE}@anchor{311c}
@deffn {Δεδομένα} tarfile.CHRTYPE

A character special device @ref{3119,,type}.
@end deffn

@geindex BLKTYPE (στη μονάδα tarfile)
@anchor{library/tarfile tarfile BLKTYPE}@anchor{311d}
@deffn {Δεδομένα} tarfile.BLKTYPE

A block special device @ref{3119,,type}.
@end deffn

@geindex DIRTYPE (στη μονάδα tarfile)
@anchor{library/tarfile tarfile DIRTYPE}@anchor{311e}
@deffn {Δεδομένα} tarfile.DIRTYPE

A directory @ref{3119,,type}.
@end deffn

@geindex FIFOTYPE (στη μονάδα tarfile)
@anchor{library/tarfile tarfile FIFOTYPE}@anchor{311f}
@deffn {Δεδομένα} tarfile.FIFOTYPE

A FIFO special device @ref{3119,,type}.
@end deffn

@geindex CONTTYPE (στη μονάδα tarfile)
@anchor{library/tarfile tarfile CONTTYPE}@anchor{3120}
@deffn {Δεδομένα} tarfile.CONTTYPE

A contiguous file @ref{3119,,type}.
@end deffn

@geindex GNUTYPE_LONGNAME (στη μονάδα tarfile)
@anchor{library/tarfile tarfile GNUTYPE_LONGNAME}@anchor{3121}
@deffn {Δεδομένα} tarfile.GNUTYPE_LONGNAME

A GNU tar longname @ref{3119,,type}.
@end deffn

@geindex GNUTYPE_LONGLINK (στη μονάδα tarfile)
@anchor{library/tarfile tarfile GNUTYPE_LONGLINK}@anchor{3122}
@deffn {Δεδομένα} tarfile.GNUTYPE_LONGLINK

A GNU tar longlink @ref{3119,,type}.
@end deffn

@geindex GNUTYPE_SPARSE (στη μονάδα tarfile)
@anchor{library/tarfile tarfile GNUTYPE_SPARSE}@anchor{3123}
@deffn {Δεδομένα} tarfile.GNUTYPE_SPARSE

A GNU tar sparse file @ref{3119,,type}.
@end deffn

Each of the following constants defines a tar archive format that the
@code{tarfile} module is able to create. See section @ref{3124,,Supported tar formats} for
details.

@geindex USTAR_FORMAT (στη μονάδα tarfile)
@anchor{library/tarfile tarfile USTAR_FORMAT}@anchor{3125}
@deffn {Δεδομένα} tarfile.USTAR_FORMAT

POSIX.1-1988 (ustar) format.
@end deffn

@geindex GNU_FORMAT (στη μονάδα tarfile)
@anchor{library/tarfile tarfile GNU_FORMAT}@anchor{3126}
@deffn {Δεδομένα} tarfile.GNU_FORMAT

GNU tar format.
@end deffn

@geindex PAX_FORMAT (στη μονάδα tarfile)
@anchor{library/tarfile tarfile PAX_FORMAT}@anchor{3127}
@deffn {Δεδομένα} tarfile.PAX_FORMAT

POSIX.1-2001 (pax) format.
@end deffn

@geindex DEFAULT_FORMAT (στη μονάδα tarfile)
@anchor{library/tarfile tarfile DEFAULT_FORMAT}@anchor{3128}
@deffn {Δεδομένα} tarfile.DEFAULT_FORMAT

The default format for creating archives. This is currently @ref{3127,,PAX_FORMAT}.


Άλλαξε στην έκδοση 3.8: The default format for new archives was changed to
@ref{3127,,PAX_FORMAT} from @ref{3126,,GNU_FORMAT}.

@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{13a,,zipfile}

Documentation of the @ref{13a,,zipfile} standard module.

@item @ref{15bf,,Archiving operations}

Documentation of the higher-level archiving facilities provided by the
standard @ref{cd,,shutil} module.

@item GNU tar manual@comma{} Basic Tar Format@footnote{https://www.gnu.org/software/tar/manual/html_node/Standard.html}

Documentation for tar archive files, including GNU tar extensions.
@end table


@menu
* TarFile Objects:: 
* TarInfo Objects:: 
* Extraction filters:: 
* Command-Line Interface:: 
* Examples: Examples<8>. 
* Supported tar formats:: 
* Unicode issues:: 

@end menu

@node TarFile Objects,TarInfo Objects,,tarfile — Read and write tar archive files
@anchor{library/tarfile id1}@anchor{3129}@anchor{library/tarfile tarfile-objects}@anchor{3105}
@subsubsection TarFile Objects


The @ref{15b7,,TarFile} object provides an interface to a tar archive. A tar
archive is a sequence of blocks. An archive member (a stored file) is made up of
a header block followed by data blocks. It is possible to store a file in a tar
archive several times. Each archive member is represented by a @ref{15b8,,TarInfo}
object, see @ref{3110,,TarInfo Objects} for details.

A @ref{15b7,,TarFile} object can be used as a context manager in a @ref{20a,,with}
statement. It will automatically be closed when the block is completed. Please
note that in the event of an exception an archive opened for writing will not
be finalized; only the internally used file object will be closed. See the
@ref{3107,,Examples} section for a use case.


Added in version 3.2: Added support for the context management protocol.


@geindex TarFile (κλάση σε tarfile)
@anchor{library/tarfile tarfile TarFile}@anchor{15b7}
@deffn {Κλάση} 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)

All following arguments are optional and can be accessed as instance attributes
as well.

`name' is the pathname of the archive. `name' may be a @ref{79f,,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.

`mode' is either @code{'r'} to read from an existing archive, @code{'a'} to append
data to an existing file, @code{'w'} to create a new file overwriting an existing
one, or @code{'x'} to create a new file only if it does not already exist.

If `fileobj' is given, it is used for reading or writing data. If it can be
determined, `mode' is overridden by `fileobj'’s mode. `fileobj' will be used
from position 0.

@cartouche
@quotation Σημείωση 
`fileobj' is not closed, when @code{TarFile} is closed.
@end quotation
@end cartouche

`format' controls the archive format for writing. It must be one of the constants
@ref{3125,,USTAR_FORMAT}, @ref{3126,,GNU_FORMAT} or @ref{3127,,PAX_FORMAT} that are
defined at module level. When reading, format will be automatically detected, even
if different formats are present in a single archive.

The `tarinfo' argument can be used to replace the default @ref{15b8,,TarInfo} class
with a different one.

If `dereference' is @ref{ef5,,False}, add symbolic and hard links to the archive. If it
is @ref{fcc,,True}, add the content of the target files to the archive. This has no
effect on systems that do not support symbolic links.

If `ignore_zeros' is @ref{ef5,,False}, treat an empty block as the end of the archive.
If it is @ref{fcc,,True}, skip empty (and invalid) blocks and try to get as many members
as possible. This is only useful for reading concatenated or damaged archives.

`debug' can be set from @code{0} (no debug messages) up to @code{3} (all debug
messages). The messages are written to @code{sys.stderr}.

`errorlevel' controls how extraction errors are handled,
see @ref{27d,,the corresponding attribute}.

The `encoding' and `errors' arguments define the character encoding to be
used for reading or writing the archive and how conversion errors are going
to be handled. The default settings will work for most users.
See section @ref{312a,,Unicode issues} for in-depth information.

The `pax_headers' argument is an optional dictionary of strings which
will be added as a pax global header if `format' is @ref{3127,,PAX_FORMAT}.

If `stream' is set to @ref{fcc,,True} then while reading the archive info about files
in the archive are not cached, saving memory.


Άλλαξε στην έκδοση 3.2: Use @code{'surrogateescape'} as the default for the `errors' argument.



Άλλαξε στην έκδοση 3.5: The @code{'x'} (exclusive creation) mode was added.



Άλλαξε στην έκδοση 3.6: The `name' parameter accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.13: Add the `stream' parameter.

@end deffn

@geindex open() (μέθοδος κλάσης της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile open}@anchor{1dd5}
@deffn {Μέθοδος} classmethod TarFile.open (...)

Alternative constructor. The @ref{1228,,tarfile.open()} function is actually a
shortcut to this classmethod.
@end deffn

@geindex getmember() (μέθοδος της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile getmember}@anchor{1de8}
@deffn {Μέθοδος} TarFile.getmember (name)

Return a @ref{15b8,,TarInfo} object for member `name'. If `name' can not be found
in the archive, @ref{7df,,KeyError} is raised.

@cartouche
@quotation Σημείωση 
If a member occurs more than once in the archive, its last occurrence is assumed
to be the most up-to-date version.
@end quotation
@end cartouche
@end deffn

@geindex getmembers() (μέθοδος της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile getmembers}@anchor{122a}
@deffn {Μέθοδος} TarFile.getmembers ()

Return the members of the archive as a list of @ref{15b8,,TarInfo} objects. The
list has the same order as the members in the archive.
@end deffn

@geindex getnames() (μέθοδος της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile getnames}@anchor{312b}
@deffn {Μέθοδος} TarFile.getnames ()

Return the members as a list of their names. It has the same order as the list
returned by @ref{122a,,getmembers()}.
@end deffn

@geindex list() (μέθοδος της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile list}@anchor{1229}
@deffn {Μέθοδος} TarFile.list (verbose=True, *, members=None)

Print a table of contents to @code{sys.stdout}. If `verbose' is @ref{ef5,,False},
only the names of the members are printed. If it is @ref{fcc,,True}, output
similar to that of @code{ls -l} is produced. If optional `members' is
given, it must be a subset of the list returned by @ref{122a,,getmembers()}.


Άλλαξε στην έκδοση 3.5: Added the `members' parameter.

@end deffn

@geindex next() (μέθοδος της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile next}@anchor{312c}
@deffn {Μέθοδος} TarFile.next ()

Return the next member of the archive as a @ref{15b8,,TarInfo} object, when
@ref{15b7,,TarFile} is opened for reading. Return @ref{a65,,None} if there is no more
available.
@end deffn

@geindex extractall() (μέθοδος της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile extractall}@anchor{27a}
@deffn {Μέθοδος} TarFile.extractall (path='.', members=None, *, numeric_owner=False, filter=None)

Extract all members from the archive to the current working directory or
directory `path'. If optional `members' is given, it must be a subset of the
list returned by @ref{122a,,getmembers()}. Directory information like owner,
modification time and permissions are set after all members have been extracted.
This is done to work around two problems: A directory’s modification time is
reset each time a file is created in it. And, if a directory’s permissions do
not allow writing, extracting files to it will fail.

If `numeric_owner' is @ref{fcc,,True}, the uid and gid numbers from the tarfile
are used to set the owner/group for the extracted files. Otherwise, the named
values from the tarfile are used.

The `filter' argument specifies how @code{members} are modified or rejected
before extraction.
See @ref{883,,Extraction filters} for details.
It is recommended to set this explicitly only if specific `tar' features
are required, or as @code{filter='data'} to support Python versions with a less
secure default (3.13 and lower).

@cartouche
@quotation Προειδοποίηση 
Never extract archives from untrusted sources without prior inspection.

Since Python 3.14, the default (@ref{279,,data}) will prevent
the most dangerous security issues.
However, it will not prevent `all' unintended or insecure behavior.
Read the @ref{883,,Extraction filters} section for details.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.5: Added the `numeric_owner' parameter.



Άλλαξε στην έκδοση 3.6: The `path' parameter accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.12: Added the `filter' parameter.



Άλλαξε στην έκδοση 3.14: The `filter' parameter now defaults to @code{'data'}.

@end deffn

@geindex extract() (μέθοδος της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile extract}@anchor{27b}
@deffn {Μέθοδος} TarFile.extract (member, path='@w{'}, set_attrs=True, *, numeric_owner=False, filter=None)

Extract a member from the archive to the current working directory, using its
full name. Its file information is extracted as accurately as possible. `member'
may be a filename or a @ref{15b8,,TarInfo} object. You can specify a different
directory using `path'. `path' may be a @ref{79f,,path-like object}.
File attributes (owner, mtime, mode) are set unless `set_attrs' is false.

The `numeric_owner' and `filter' arguments are the same as
for @ref{27a,,extractall()}.

@cartouche
@quotation Σημείωση 
The @code{extract()} method does not take care of several extraction issues.
In most cases you should consider using the @ref{27a,,extractall()} method.
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
Never extract archives from untrusted sources without prior inspection.
See the warning for @ref{27a,,extractall()} for details.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.2: Added the `set_attrs' parameter.



Άλλαξε στην έκδοση 3.5: Added the `numeric_owner' parameter.



Άλλαξε στην έκδοση 3.6: The `path' parameter accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.12: Added the `filter' parameter.

@end deffn

@geindex extractfile() (μέθοδος της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile extractfile}@anchor{312d}
@deffn {Μέθοδος} TarFile.extractfile (member)

Extract a member from the archive as a file object. `member' may be
a filename or a @ref{15b8,,TarInfo} object. If `member' is a regular file or
a link, an @ref{15b5,,io.BufferedReader} object is returned. For all other
existing members, @ref{a65,,None} is returned. If `member' does not appear
in the archive, @ref{7df,,KeyError} is raised.


Άλλαξε στην έκδοση 3.3: Return an @ref{15b5,,io.BufferedReader} object.



Άλλαξε στην έκδοση 3.13: The returned @ref{15b5,,io.BufferedReader} object has the @code{mode}
attribute which is always equal to @code{'rb'}.

@end deffn

@geindex errorlevel (ιδιότητα της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile errorlevel}@anchor{27d}
@deffn {Ιδιότητα} TarFile.errorlevel: @ref{326,,int}

If `errorlevel' is @code{0}, errors are ignored when using @ref{27b,,TarFile.extract()}
and @ref{27a,,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{53c,,OSError} or
@ref{310d,,FilterError} exceptions. If @code{2}, all `non-fatal' errors are raised
as @ref{3108,,TarError} exceptions as well.

Some exceptions, e.g. ones caused by wrong argument types or data
corruption, are always raised.

Custom @ref{883,,extraction filters}
should raise @ref{310d,,FilterError} for `fatal' errors
and @ref{310a,,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 (ιδιότητα της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile extraction_filter}@anchor{312e}
@deffn {Ιδιότητα} TarFile.extraction_filter


Added in version 3.12.


The @ref{883,,extraction filter} used
as a default for the `filter' argument of @ref{27b,,extract()}
and @ref{27a,,extractall()}.

The attribute may be @code{None} or a callable.
String names are not allowed for this attribute, unlike the `filter'
argument to @ref{27b,,extract()}.

If @code{extraction_filter} is @code{None} (the default), extraction methods
will use the @ref{279,,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{cf,,site configuration}.
To set a global default this way, a filter function needs to be wrapped in
@ref{666,,staticmethod()} to prevent injection of a @code{self} argument.


Άλλαξε στην έκδοση 3.14: The default filter is set to @ref{279,,data},
which disallows some dangerous features such as links to absolute paths
or paths outside of the destination.
Previously, the default was equivalent to
@ref{3104,,fully_trusted}.

@end deffn

@geindex add() (μέθοδος της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile add}@anchor{fb3}
@deffn {Μέθοδος} TarFile.add (name, arcname=None, recursive=True, *, filter=None)

Add the file `name' to the archive. `name' may be any type of file
(directory, fifo, symbolic link, etc.). If given, `arcname' specifies an
alternative name for the file in the archive. Directories are added
recursively by default. This can be avoided by setting `recursive' to
@ref{ef5,,False}. Recursion adds entries in sorted order.
If `filter' is given, it
should be a function that takes a @ref{15b8,,TarInfo} object argument and
returns the changed @code{TarInfo} object. If it instead returns
@ref{a65,,None} the @code{TarInfo} object will be excluded from the
archive. See @ref{3107,,Examples} for an example.


Άλλαξε στην έκδοση 3.2: Added the `filter' parameter.



Άλλαξε στην έκδοση 3.7: Recursion adds entries in sorted order.

@end deffn

@geindex addfile() (μέθοδος της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile addfile}@anchor{1bb2}
@deffn {Μέθοδος} TarFile.addfile (tarinfo, fileobj=None)

Add the @ref{15b8,,TarInfo} object `tarinfo' to the archive. If `tarinfo' represents
a non zero-size regular file, the `fileobj' argument should be a @ref{225d,,binary file},
and @code{tarinfo.size} bytes are read from it and added to the archive.  You can
create @code{TarInfo} objects directly, or by using @ref{312f,,gettarinfo()}.


Άλλαξε στην έκδοση 3.13: `fileobj' must be given for non-zero-sized regular files.

@end deffn

@geindex gettarinfo() (μέθοδος της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile gettarinfo}@anchor{312f}
@deffn {Μέθοδος} TarFile.gettarinfo (name=None, arcname=None, fileobj=None)

Create a @ref{15b8,,TarInfo} object from the result of @ref{4f5,,os.stat()} or
equivalent on an existing file.  The file is either named by `name', or
specified as a @ref{156c,,file object} `fileobj' with a file descriptor.
`name' may be a @ref{79f,,path-like object}.  If
given, `arcname' specifies an alternative name for the file in the
archive, otherwise, the name is taken from `fileobj'’s
@ref{3017,,name} attribute, or the `name' argument.  The name
should be a text string.

You can modify
some of the @ref{15b8,,TarInfo}’s attributes before you add it using @ref{1bb2,,addfile()}.
If the file object is not an ordinary file object positioned at the
beginning of the file, attributes such as @ref{3130,,size} may need
modifying.  This is the case for objects such as @ref{849,,GzipFile}.
The @ref{3131,,name} may also be modified, in which case `arcname'
could be a dummy string.


Άλλαξε στην έκδοση 3.6: The `name' parameter accepts a @ref{79f,,path-like object}.

@end deffn

@geindex close() (μέθοδος της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile close}@anchor{3132}
@deffn {Μέθοδος} TarFile.close ()

Close the @ref{15b7,,TarFile}. In write mode, two finishing zero blocks are
appended to the archive.
@end deffn

@geindex pax_headers (ιδιότητα της tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile pax_headers}@anchor{3133}
@deffn {Ιδιότητα} TarFile.pax_headers: @ref{188,,dict}

A dictionary containing key-value pairs of pax global headers.
@end deffn

@node TarInfo Objects,Extraction filters,TarFile Objects,tarfile — Read and write tar archive files
@anchor{library/tarfile id2}@anchor{3134}@anchor{library/tarfile tarinfo-objects}@anchor{3110}
@subsubsection TarInfo Objects


A @ref{15b8,,TarInfo} object represents one member in a @ref{15b7,,TarFile}. Aside
from storing all required attributes of a file (like file type, size, time,
permissions, owner etc.), it provides some useful methods to determine its type.
It does `not' contain the file’s data itself.

@ref{15b8,,TarInfo} objects are returned by @ref{15b7,,TarFile}’s methods
@ref{1de8,,getmember()}, @ref{122a,,getmembers()} and
@ref{312f,,gettarinfo()}.

Modifying the objects returned by @ref{1de8,,getmember()} or
@ref{122a,,getmembers()} will affect all subsequent
operations on the archive.
For cases where this is unwanted, you can use @ref{29,,copy.copy()} or
call the @ref{3135,,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{15b8,,TarInfo} methods handle @code{None} differently:


@itemize -

@item 
The @ref{27b,,extract()} or @ref{27a,,extractall()} methods will
ignore the corresponding metadata, leaving it set to a default.

@item 
@ref{1bb2,,addfile()} will fail.

@item 
@ref{1229,,list()} will print a placeholder string.
@end itemize

@geindex TarInfo (κλάση σε tarfile)
@anchor{library/tarfile tarfile TarInfo}@anchor{15b8}
@deffn {Κλάση} tarfile.TarInfo (name='@w{'})

Create a @code{TarInfo} object.
@end deffn

@geindex frombuf() (μέθοδος κλάσης της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo frombuf}@anchor{310c}
@deffn {Μέθοδος} classmethod TarInfo.frombuf (buf, encoding, errors)

Create and return a @ref{15b8,,TarInfo} object from string buffer `buf'.

Raises @ref{310b,,HeaderError} if the buffer is invalid.
@end deffn

@geindex fromtarfile() (μέθοδος κλάσης της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo fromtarfile}@anchor{3136}
@deffn {Μέθοδος} classmethod TarInfo.fromtarfile (tarfile)

Read the next member from the @ref{15b7,,TarFile} object `tarfile' and return it as
a @ref{15b8,,TarInfo} object.
@end deffn

@geindex tobuf() (μέθοδος της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo tobuf}@anchor{3137}
@deffn {Μέθοδος} TarInfo.tobuf (format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')

Create a string buffer from a @ref{15b8,,TarInfo} object. For information on the
arguments see the constructor of the @ref{15b7,,TarFile} class.


Άλλαξε στην έκδοση 3.2: Use @code{'surrogateescape'} as the default for the `errors' argument.

@end deffn

A @code{TarInfo} object has the following public data attributes:

@geindex name (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo name}@anchor{3131}
@deffn {Ιδιότητα} TarInfo.name: @ref{1df,,str}

Name of the archive member.
@end deffn

@geindex size (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo size}@anchor{3130}
@deffn {Ιδιότητα} TarInfo.size: @ref{326,,int}

Size in bytes.
@end deffn

@geindex mtime (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo mtime}@anchor{3138}
@deffn {Ιδιότητα} TarInfo.mtime: @ref{326,,int} | @ref{327,,float}

Time of last modification in seconds since the @ref{3139,,epoch},
as in @ref{313a,,os.stat_result.st_mtime}.


Άλλαξε στην έκδοση 3.12: Can be set to @code{None} for @ref{27b,,extract()} and
@ref{27a,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex mode (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo mode}@anchor{313b}
@deffn {Ιδιότητα} TarInfo.mode: @ref{326,,int}

Permission bits, as for @ref{72c,,os.chmod()}.


Άλλαξε στην έκδοση 3.12: Can be set to @code{None} for @ref{27b,,extract()} and
@ref{27a,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex type (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo type}@anchor{3119}
@deffn {Ιδιότητα} TarInfo.type

File type.  `type' is usually one of these constants: @ref{3117,,REGTYPE},
@ref{3118,,AREGTYPE}, @ref{311a,,LNKTYPE}, @ref{311b,,SYMTYPE}, @ref{311e,,DIRTYPE},
@ref{311f,,FIFOTYPE}, @ref{3120,,CONTTYPE}, @ref{311c,,CHRTYPE}, @ref{311d,,BLKTYPE},
@ref{3123,,GNUTYPE_SPARSE}.  To determine the type of a @ref{15b8,,TarInfo} object
more conveniently, use the @code{is*()} methods below.
@end deffn

@geindex linkname (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo linkname}@anchor{313c}
@deffn {Ιδιότητα} TarInfo.linkname: @ref{1df,,str}

Name of the target file name, which is only present in @ref{15b8,,TarInfo} objects
of type @ref{311a,,LNKTYPE} and @ref{311b,,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 (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo uid}@anchor{313d}
@deffn {Ιδιότητα} TarInfo.uid: @ref{326,,int}

User ID of the user who originally stored this member.


Άλλαξε στην έκδοση 3.12: Can be set to @code{None} for @ref{27b,,extract()} and
@ref{27a,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex gid (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo gid}@anchor{313e}
@deffn {Ιδιότητα} TarInfo.gid: @ref{326,,int}

Group ID of the user who originally stored this member.


Άλλαξε στην έκδοση 3.12: Can be set to @code{None} for @ref{27b,,extract()} and
@ref{27a,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex uname (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo uname}@anchor{313f}
@deffn {Ιδιότητα} TarInfo.uname: @ref{1df,,str}

User name.


Άλλαξε στην έκδοση 3.12: Can be set to @code{None} for @ref{27b,,extract()} and
@ref{27a,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex gname (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo gname}@anchor{3140}
@deffn {Ιδιότητα} TarInfo.gname: @ref{1df,,str}

Group name.


Άλλαξε στην έκδοση 3.12: Can be set to @code{None} for @ref{27b,,extract()} and
@ref{27a,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex chksum (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo chksum}@anchor{3141}
@deffn {Ιδιότητα} TarInfo.chksum: @ref{326,,int}

Header checksum.
@end deffn

@geindex devmajor (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo devmajor}@anchor{3142}
@deffn {Ιδιότητα} TarInfo.devmajor: @ref{326,,int}

Device major number.
@end deffn

@geindex devminor (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo devminor}@anchor{3143}
@deffn {Ιδιότητα} TarInfo.devminor: @ref{326,,int}

Device minor number.
@end deffn

@geindex offset (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo offset}@anchor{3144}
@deffn {Ιδιότητα} TarInfo.offset: @ref{326,,int}

The tar header starts here.
@end deffn

@geindex offset_data (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo offset_data}@anchor{3145}
@deffn {Ιδιότητα} TarInfo.offset_data: @ref{326,,int}

The file’s data starts here.
@end deffn

@geindex sparse (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo sparse}@anchor{3146}
@deffn {Ιδιότητα} TarInfo.sparse

Sparse member information.
@end deffn

@geindex pax_headers (ιδιότητα της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo pax_headers}@anchor{3147}
@deffn {Ιδιότητα} TarInfo.pax_headers: @ref{188,,dict}

A dictionary containing key-value pairs of an associated pax extended header.
@end deffn

@geindex replace() (μέθοδος της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo replace}@anchor{3135}
@deffn {Μέθοδος} TarInfo.replace (name=..., mtime=..., mode=..., linkname=..., uid=..., gid=..., uname=..., gname=..., deep=True)


Added in 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

A @ref{15b8,,TarInfo} object also provides some convenient query methods:

@geindex isfile() (μέθοδος της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo isfile}@anchor{3148}
@deffn {Μέθοδος} TarInfo.isfile ()

Return @ref{fcc,,True} if the @ref{15b8,,TarInfo} object is a regular file.
@end deffn

@geindex isreg() (μέθοδος της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo isreg}@anchor{3149}
@deffn {Μέθοδος} TarInfo.isreg ()

Same as @ref{3148,,isfile()}.
@end deffn

@geindex isdir() (μέθοδος της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo isdir}@anchor{314a}
@deffn {Μέθοδος} TarInfo.isdir ()

Return @ref{fcc,,True} if it is a directory.
@end deffn

@geindex issym() (μέθοδος της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo issym}@anchor{314b}
@deffn {Μέθοδος} TarInfo.issym ()

Return @ref{fcc,,True} if it is a symbolic link.
@end deffn

@geindex islnk() (μέθοδος της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo islnk}@anchor{314c}
@deffn {Μέθοδος} TarInfo.islnk ()

Return @ref{fcc,,True} if it is a hard link.
@end deffn

@geindex ischr() (μέθοδος της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo ischr}@anchor{314d}
@deffn {Μέθοδος} TarInfo.ischr ()

Return @ref{fcc,,True} if it is a character device.
@end deffn

@geindex isblk() (μέθοδος της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo isblk}@anchor{314e}
@deffn {Μέθοδος} TarInfo.isblk ()

Return @ref{fcc,,True} if it is a block device.
@end deffn

@geindex isfifo() (μέθοδος της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo isfifo}@anchor{314f}
@deffn {Μέθοδος} TarInfo.isfifo ()

Return @ref{fcc,,True} if it is a FIFO.
@end deffn

@geindex isdev() (μέθοδος της tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo isdev}@anchor{3150}
@deffn {Μέθοδος} TarInfo.isdev ()

Return @ref{fcc,,True} if it is one of character device, block device or FIFO.
@end deffn

@node Extraction filters,Command-Line Interface,TarInfo Objects,tarfile — Read and write tar archive files
@anchor{library/tarfile extraction-filters}@anchor{3151}@anchor{library/tarfile tarfile-extraction-filter}@anchor{883}
@subsubsection Extraction filters



Added in 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.

@cartouche
@quotation Προειδοποίηση 
None of the available filters blocks `all' dangerous archive features.
Never extract archives from untrusted sources without prior inspection.
See also @ref{2f19,,Hints for further verification}.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης



@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{27b,,TarFile.extract()} or @ref{27a,,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{3152,,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{279,,data_filter()} for details.

@item 
@code{None} (default): Use @ref{312e,,TarFile.extraction_filter}.

If that is also @code{None} (the default), the @code{'data'} filter will be used.

@quotation


Άλλαξε στην έκδοση 3.14: The default filter is set to @ref{279,,data}.
Previously, the default was equivalent to
@ref{3104,,fully_trusted}.

@end quotation

@item 
A callable which will be called for each extracted member with a
@ref{3110,,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{15b8,,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{27d,,errorlevel}.
Note that when extraction is aborted, @ref{27a,,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{3153}
@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() (στη μονάδα tarfile)
@anchor{library/tarfile tarfile fully_trusted_filter}@anchor{3104}
@deffn {Συνάρτηση} tarfile.fully_trusted_filter (member, path)

Return `member' unchanged.

This implements the @code{'fully_trusted'} filter.
@end deffn

@geindex tar_filter() (στη μονάδα tarfile)
@anchor{library/tarfile tarfile tar_filter}@anchor{3152}
@deffn {Συνάρτηση} tarfile.tar_filter (member, path)

Implements the @code{'tar'} filter.


@itemize -

@item 
Strip leading slashes (@code{/} and @ref{a5a,,os.sep}) from filenames.

@item 
@ref{310e,,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{3111,,AbsolutePathError}.

@item 
@ref{310e,,Refuse} to extract files whose absolute
path (after following symlinks) would end up outside the destination.
This raises @ref{3112,,OutsideDestinationError}.

@item 
Clear high mode bits (setuid, setgid, sticky) and group/other write bits
(@ref{2e9c,,S_IWGRP} | @ref{2e9f,,S_IWOTH}).
@end itemize

Return the modified @code{TarInfo} member.
@end deffn

@geindex data_filter() (στη μονάδα tarfile)
@anchor{library/tarfile tarfile data_filter}@anchor{279}
@deffn {Συνάρτηση} tarfile.data_filter (member, path)

Implements the @code{'data'} filter.
In addition to what @code{tar_filter} does:


@itemize -

@item 
Normalize link targets (@ref{313c,,TarInfo.linkname}) using
@ref{16be,,os.path.normpath()}.
Note that this removes internal @code{..} components, which may change the
meaning of the link if the path in @code{TarInfo.linkname} traverses
symbolic links.

@item 
@ref{310e,,Refuse} to extract links (hard or soft)
that link to absolute paths, or ones that link outside the destination.

This raises @ref{3114,,AbsoluteLinkError} or
@ref{3115,,LinkOutsideDestinationError}.

Note that such files are refused even on platforms that do not support
symbolic links.

@item 
@ref{310e,,Refuse} to extract device files
(including pipes).
This raises @ref{3113,,SpecialFileError}.

@item 
For regular files, including hard links:


@itemize -

@item 
Set the owner read and write permissions
(@ref{2e97,,S_IRUSR} | @ref{2e98,,S_IWUSR}).

@item 
Remove the group & other executable permission
(@ref{2e93,,S_IXGRP} | @ref{2ea0,,S_IXOTH})
if the owner doesn’t have it (@ref{2e99,,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.

Note that this filter does not block `all' dangerous archive features.
See @ref{2f19,,Hints for further verification}  for details.


Άλλαξε στην έκδοση 3.15: Link targets are now normalized.

@end deffn

@node Filter errors,Hints for further verification,Default named filters,Extraction filters
@anchor{library/tarfile filter-errors}@anchor{3154}@anchor{library/tarfile tarfile-extraction-refuse}@anchor{310e}
@subsubsection Filter errors


When a filter refuses to extract a file, it will raise an appropriate exception,
a subclass of @ref{310d,,FilterError}.
This will abort the extraction if @ref{27d,,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{3155}@anchor{library/tarfile tarfile-further-verification}@anchor{2f19}
@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{730,,new temporary directory}
to prevent e.g. exploiting pre-existing links, and to make it easier to
clean up after a failed extraction.

@item 
Disallow symbolic links if you do not need the functionality.

@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,
and so on).

@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{3156}
@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

or:

@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{3157}
@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 Command-Line Interface,Examples<8>,Extraction filters,tarfile — Read and write tar archive files
@anchor{library/tarfile command-line-interface}@anchor{3158}@anchor{library/tarfile tarfile-commandline}@anchor{1374}
@subsubsection Command-Line Interface



Added in version 3.4.


The @code{tarfile} module provides a simple command-line interface to interact
with tar archives.

If you want to create a new tar archive, specify its name after the @ref{3159,,-c}
option and then list the filename(s) that should be included:

@example
$ python -m tarfile -c monty.tar  spam.txt eggs.txt
@end example

Passing a directory is also acceptable:

@example
$ python -m tarfile -c monty.tar life-of-brian_1979/
@end example

If you want to extract a tar archive into the current directory, use
the @ref{315a,,-e} option:

@example
$ python -m tarfile -e monty.tar
@end example

You can also extract a tar archive into a different directory by passing the
directory’s name:

@example
$ python -m tarfile -e monty.tar  other-dir/
@end example

For a list of the files in a tar archive, use the @ref{315b,,-l} option:

@example
$ python -m tarfile -l monty.tar
@end example

@menu
* Command-line options: Command-line options<2>. 

@end menu

@node Command-line options<2>,,,Command-Line Interface
@anchor{library/tarfile command-line-options}@anchor{315c}
@subsubsection Command-line options


@geindex tarfile command line option; -l
@geindex tarfile command line option; --list
@anchor{library/tarfile cmdoption-tarfile-l}@anchor{315b}
@deffn {Option} @w{-}l <tarfile>
@anchor{library/tarfile cmdoption-tarfile-list}@anchor{315d}
@deffnx {Option} @w{-}@w{-}list <tarfile>

List files in a tarfile.
@end deffn

@geindex tarfile command line option; -c
@geindex tarfile command line option; --create
@anchor{library/tarfile cmdoption-tarfile-c}@anchor{3159}
@deffn {Option} @w{-}c <tarfile> <source1> ... <sourceN>
@anchor{library/tarfile cmdoption-tarfile-create}@anchor{315e}
@deffnx {Option} @w{-}@w{-}create <tarfile> <source1> ... <sourceN>

Create tarfile from source files.
@end deffn

@geindex tarfile command line option; -e
@geindex tarfile command line option; --extract
@anchor{library/tarfile cmdoption-tarfile-e}@anchor{315a}
@deffn {Option} @w{-}e <tarfile> [<output_dir>]
@anchor{library/tarfile cmdoption-tarfile-extract}@anchor{315f}
@deffnx {Option} @w{-}@w{-}extract <tarfile> [<output_dir>]

Extract tarfile into the current directory if `output_dir' is not specified.
@end deffn

@geindex tarfile command line option; -t
@geindex tarfile command line option; --test
@anchor{library/tarfile cmdoption-tarfile-t}@anchor{3160}
@deffn {Option} @w{-}t <tarfile>
@anchor{library/tarfile cmdoption-tarfile-test}@anchor{3161}
@deffnx {Option} @w{-}@w{-}test <tarfile>

Test whether the tarfile is valid or not.
@end deffn

@geindex tarfile command line option; -v
@geindex tarfile command line option; --verbose
@anchor{library/tarfile cmdoption-tarfile-v}@anchor{3162}@anchor{library/tarfile cmdoption-tarfile-verbose}@anchor{3163}
@deffn {Option} @w{-}v, @w{-}@w{-}verbose

Verbose output.
@end deffn

@geindex tarfile command line option; --filter
@anchor{library/tarfile cmdoption-tarfile-filter}@anchor{3164}
@deffn {Option} @w{-}@w{-}filter <filtername>

Specifies the `filter' for @code{--extract}.
See @ref{883,,Extraction filters} for details.
Only string names are accepted (that is, @code{fully_trusted}, @code{tar},
and @code{data}).
@end deffn

@node Examples<8>,Supported tar formats,Command-Line Interface,tarfile — Read and write tar archive files
@anchor{library/tarfile examples}@anchor{3165}@anchor{library/tarfile tar-examples}@anchor{3107}
@subsubsection Examples


@menu
* Reading examples:: 
* Writing examples:: 

@end menu

@node Reading examples,Writing examples,,Examples<8>
@anchor{library/tarfile reading-examples}@anchor{3166}
@subsubsection Reading examples


How to extract an entire tar archive to the current working directory:

@example
import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall(filter='data')
tar.close()
@end example

How to extract a subset of a tar archive with @ref{27a,,TarFile.extractall()} using
a generator function instead of a list:

@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

How to read a gzip compressed tar archive and display some member information:

@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

@node Writing examples,,Reading examples,Examples<8>
@anchor{library/tarfile writing-examples}@anchor{3167}
@subsubsection Writing examples


How to create an uncompressed tar archive from a list of filenames:

@example
import tarfile
tar = tarfile.open("sample.tar", "w")
for name in ["foo", "bar", "quux"]:
    tar.add(name)
tar.close()
@end example

The same example using the @ref{20a,,with} statement:

@example
import tarfile
with tarfile.open("sample.tar", "w") as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)
@end example

How to create and write an archive to stdout using
@ref{e9c,,sys.stdout.buffer} in the `fileobj' parameter
in @ref{fb3,,TarFile.add()}:

@example
import sys
import tarfile
with tarfile.open("sample.tar.gz", "w|gz", fileobj=sys.stdout.buffer) as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)
@end example

How to create an archive and reset the user information using the `filter'
parameter in @ref{fb3,,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 Supported tar formats,Unicode issues,Examples<8>,tarfile — Read and write tar archive files
@anchor{library/tarfile supported-tar-formats}@anchor{3168}@anchor{library/tarfile tar-formats}@anchor{3124}
@subsubsection Supported tar formats


There are three tar formats that can be created with the @code{tarfile} module:


@itemize *

@item 
The POSIX.1-1988 ustar format (@ref{3125,,USTAR_FORMAT}). It supports filenames
up to a length of at best 256 characters and linknames up to 100 characters.
The maximum file size is 8 GiB. This is an old and limited but widely
supported format.

@item 
The GNU tar format (@ref{3126,,GNU_FORMAT}). It supports long filenames and
linknames, files bigger than 8 GiB and sparse files. It is the de facto
standard on GNU/Linux systems. @code{tarfile} fully supports the GNU tar
extensions for long names, sparse file support is read-only.

@item 
The POSIX.1-2001 pax format (@ref{3127,,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.

It extends the existing `ustar' format with extra headers for information
that cannot be stored otherwise. There are two flavours of pax headers:
Extended headers only affect the subsequent file header, global
headers are valid for the complete archive and affect all following files.
All the data in a pax header is encoded in `UTF-8' for portability reasons.
@end itemize

There are some more variants of the tar format which can be read, but not
created:


@itemize *

@item 
The ancient V7 format. This is the first tar format from Unix Seventh Edition,
storing only regular files and directories. Names must not be longer than 100
characters, there is no user/group name information. Some archives have
miscalculated header checksums in case of fields with non-ASCII characters.

@item 
The SunOS tar extended format. This format is a variant of the POSIX.1-2001
pax format, but is not compatible.
@end itemize

@node Unicode issues,,Supported tar formats,tarfile — Read and write tar archive files
@anchor{library/tarfile tar-unicode}@anchor{312a}@anchor{library/tarfile unicode-issues}@anchor{3169}
@subsubsection Unicode issues


The tar format was originally conceived to make backups on tape drives with the
main focus on preserving file system information. Nowadays tar archives are
commonly used for file distribution and exchanging archives over networks. One
problem of the original format (which is the basis of all other formats) is
that there is no concept of supporting different character encodings. For
example, an ordinary tar archive created on a `UTF-8' system cannot be read
correctly on a `Latin-1' system if it contains non-`ASCII' characters. Textual
metadata (like filenames, linknames, user/group names) will appear damaged.
Unfortunately, there is no way to autodetect the encoding of an archive. The
pax format was designed to solve this problem. It stores non-ASCII metadata
using the universal character encoding `UTF-8'.

The details of character conversion in @code{tarfile} are controlled by the
`encoding' and `errors' keyword arguments of the @ref{15b7,,TarFile} class.

`encoding' defines the character encoding to use for the metadata in the
archive. The default value is @ref{1017,,sys.getfilesystemencoding()} or @code{'ascii'}
as a fallback. Depending on whether the archive is read or written, the
metadata must be either decoded or encoded. If `encoding' is not set
appropriately, this conversion may fail.

The `errors' argument defines how characters are treated that cannot be
converted. Possible values are listed in section @ref{1d6c,,Error Handlers}.
The default scheme is @code{'surrogateescape'} which Python also uses for its
file system calls, see @ref{316a,,File Names@comma{} Command Line Arguments@comma{} and Environment Variables}.

For @ref{3127,,PAX_FORMAT} archives (the default), `encoding' is generally not needed
because all the metadata is stored using `UTF-8'. `encoding' is only used in
the rare cases when binary pax headers are decoded or when strings with
surrogate characters are stored.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node File Formats,Cryptographic Services,Data Compression and Archiving,The Python Standard Library
@anchor{library/fileformats doc}@anchor{316b}@anchor{library/fileformats file-formats}@anchor{316c}@anchor{library/fileformats fileformats}@anchor{316d}@anchor{library/fileformats translation-repo}@anchor{316e}
@section File Formats


The modules described in this chapter parse various miscellaneous file formats
that aren’t markup languages and are not related to e-mail.

@menu
* csv — Ανάγνωση και Εγγραφή Αρχείων CSV:: 
* configparser — Configuration file parser:: 
* tomllib — Parse TOML files:: 
* netrc — netrc file processing:: 
* plistlib — Generate and parse Apple .plist files: plistlib — Generate and parse Apple plist files. 

@end menu

@node csv — Ανάγνωση και Εγγραφή Αρχείων CSV,configparser — Configuration file parser,,File Formats
@anchor{library/csv doc}@anchor{316f}@anchor{library/csv csv-csv-file-reading-and-writing}@anchor{3170}@anchor{library/csv module-csv}@anchor{2c}
@subsection @code{csv} — Ανάγνωση και Εγγραφή Αρχείων CSV


@geindex module; csv

`Πηγαίος κώδικας:' Lib/csv.py@footnote{https://github.com/python/cpython/tree/main/Lib/csv.py}

@geindex csv
@geindex δεδομένα;πίνακας


__________________________________________________________________


Το λεγόμενο CSV (Comma Separated Values) είναι η πιο κοινή μορφή εισαγωγής και εξαγωγής για υπολογιστικά φύλλα και βάσεις δεδομένων. Η μορφή CSV χρησιμοποιήθηκε για πολλά χρόνια πριν από τις προσπάθειες περιγραφής της μορφής με έναν τυποποιημένο τρόπο στο 
@geindex RFC; RFC 4180
RFC 4180@footnote{https://datatracker.ietf.org/doc/html/rfc4180.html}. Η έλλειψη ενός καλά καθορισμένου προτύπου σημαίνει ότι συχνά υπάρχουν λεπτές διαφορές στα δεδομένα που παράγονται και καταναλώνονται από διαφορετικές εφαρμογές. Αυτές οι διαφορές μπορούν να κάνουν ενοχλητική την επεξεργασία αρχείων CSV από πολλαπλές πηγές. Ωστόσο, ενώ οι διαχωριστές και οι χαρακτήρες παράθεσης ποικίλλουν, η συνολική μορφή είναι αρκετά παρόμοια ώστε να είναι δυνατό να γραφτεί ένα ενιαίο module που μπορεί να χειριστεί αποτελεσματικά αυτά τα δεδομένα, κρύβοντας τις λεπτομέρειες της ανάγνωσης και εγγραφής των δεδομένων από τον προγραμματιστή.

The @code{csv} module implements classes to read and write tabular data in CSV
format.  It allows programmers to say, «write this data in the format preferred
by Excel,» or «read data from this file which was generated by Excel,» without
knowing the precise details of the CSV format used by Excel.  Programmers can
also describe the CSV formats understood by other applications or define their
own special-purpose CSV formats.

The @code{csv} module’s @ref{898,,reader} and @ref{899,,writer} objects read and
write sequences.  Programmers can also read and write data in dictionary form
using the @ref{da9,,DictReader} and @ref{15a7,,DictWriter} classes.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 305

@item PEP 305@footnote{https://peps.python.org/pep-0305/} - API Αρχείων CSV

Η Πρόταση Βελτίωσης της Python που πρότεινε αυτή την προσθήκη στην Python.
@end table


@menu
* Περιεχόμενα του Module:: 
* Διάλεκτοι και Παράμετροι Μορφοποίησης:: 
* Αντικείμενα Αναγνώστη:: 
* Αντικείμενα Εγγραφέα:: 
* Παραδείγματα: Παραδείγματα<3>. 

@end menu

@node Περιεχόμενα του Module,Διάλεκτοι και Παράμετροι Μορφοποίησης,,csv — Ανάγνωση και Εγγραφή Αρχείων CSV
@anchor{library/csv csv-contents}@anchor{3171}@anchor{library/csv module-contents}@anchor{3172}
@subsubsection Περιεχόμενα του Module


The @code{csv} module defines the following functions:

@geindex καθολικές νέες γραμμές;συνάρτηση csv.reader

@geindex reader() (στη μονάδα csv)
@anchor{library/csv csv reader}@anchor{898}
@deffn {Συνάρτηση} csv.reader (csvfile, /, dialect='excel', **fmtparams)

Επιστρέφει ένα αντικείμενο @ref{3173,,reader} που θα επεξεργάζεται γραμμές από το δεδομένο `csvfile'. Ένα csvfile πρέπει να είναι μια ακολουθία από συμβολοσειρές, κάθε μια στη μορφή CSV που ορίζει ο αναγνώστης. Ένα csvfile είναι πιο συχνά ένα αντικείμενο παρόμοιο με αρχείο ή μια λίστα. Αν το `csvfile' είναι ένα αντικείμενο αρχείου, θα πρέπει να ανοιχτεί με @code{newline='@w{'}}. @footnote{
Αν δεν καθοριστεί @code{newline='@w{'}}, οι νέες γραμμές που ενσωματώνονται μέσα σε παρατεθειμένα πεδία δεν θα ερμηνευτούν σωστά, και σε πλατφόρμες που χρησιμοποιούν @code{\r\n} ως τερματισμούς γραμμών κατά την εγγραφή, θα προστίθεται ένα επιπλέον @code{\r}. Πρέπει πάντα να είναι ασφαλές να καθορίσετε @code{newline='@w{'}}, καθώς το module csv χειρίζεται μόνο του (@ref{10f1,,universal}) τη διαχείριση νέων γραμμών.
} Μια προαιρετική παράμετρος `dialect' μπορεί να δοθεί η οποία χρησιμοποιείται για τον ορισμό ενός συνόλου παραμέτρων ειδικών για μια συγκεκριμένη διάλεκτο CSV. Μπορεί να είναι ένα στιγμιότυπο μιας υποκλάσης της κλάσης @ref{1a3c,,Dialect} ή μια από τις συμβολοσειρές που επιστρέφει η συνάρτηση @ref{1d90,,list_dialects()}. Οι άλλες προαιρετικές παράμετροι `fmtparams' μπορούν να δοθούν για να αντικαταστήσουν μεμονωμένες παραμέτρους μορφοποίησης στην τρέχουσα διάλεκτο. Για πλήρεις λεπτομέρειες σχετικά με τις διαλέκτους και τις παραμέτρους μορφοποίησης, δείτε την ενότητα @ref{3174,,Διάλεκτοι και Παράμετροι Μορφοποίησης}.

Κάθε γραμμή που διαβάζεται από το αρχείο csv επιστρέφεται ως μια λίστα συμβολοσειρών. Δεν γίνεται αυτόματη μετατροπή τύπων δεδομένων εκτός αν οριστεί η επιλογή μορφοποίησης @ref{1b5f,,QUOTE_NONNUMERIC} (στην οποία περίπτωση τα μη παρατεθειμένα πεδία μετατρέπονται σε float).

Ένα σύντομο παράδειγμα χρήσης:

@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() (στη μονάδα csv)
@anchor{library/csv csv writer}@anchor{899}
@deffn {Συνάρτηση} csv.writer (csvfile, /, dialect='excel', **fmtparams)

Επιστρέφει ένα αντικείμενο writer υπεύθυνο για τη μετατροπή των δεδομένων του χρήστη σε διαχωρισμένες συμβολοσειρές στο δεδομένο αντικείμενο παρόμοιο με αρχείο. Το `csvfile' μπορεί να είναι οποιοδήποτε αντικείμενο με μια μέθοδο @ref{224a,,write()}. Αν το `csvfile' είναι ένα αντικείμενο αρχείου, θα πρέπει να ανοιχτεί με @code{newline='@w{'}} @footnote{
Αν δεν καθοριστεί @code{newline='@w{'}}, οι νέες γραμμές που ενσωματώνονται μέσα σε παρατεθειμένα πεδία δεν θα ερμηνευτούν σωστά, και σε πλατφόρμες που χρησιμοποιούν @code{\r\n} ως τερματισμούς γραμμών κατά την εγγραφή, θα προστίθεται ένα επιπλέον @code{\r}. Πρέπει πάντα να είναι ασφαλές να καθορίσετε @code{newline='@w{'}}, καθώς το module csv χειρίζεται μόνο του (@ref{10f1,,universal}) τη διαχείριση νέων γραμμών.
}. Μια προαιρετική παράμετρος `dialect' μπορεί να δοθεί η οποία χρησιμοποιείται για τον ορισμό ενός συνόλου παραμέτρων ειδικών για μια συγκεκριμένη διάλεκτο CSV. Μπορεί να είναι ένα στιγμιότυπο μιας υποκλάσης της κλάσης @ref{1a3c,,Dialect} ή μια από τις συμβολοσειρές που επιστρέφει η συνάρτηση @ref{1d90,,list_dialects()}. Οι άλλες προαιρετικές παράμετροι `fmtparams' μπορούν να δοθούν για να αντικαταστήσουν μεμονωμένες παραμέτρους μορφοποίησης στην τρέχουσα διάλεκτο. Για πλήρεις λεπτομέρειες σχετικά με τις διαλέκτους και τις παραμέτρους μορφοποίησης, δείτε την ενότητα @ref{3174,,Διάλεκτοι και Παράμετροι Μορφοποίησης}. Για να διευκολυνθεί όσο το δυνατόν περισσότερο η διασύνδεση με modules που υλοποιούν το DB API, η τιμή @ref{a65,,None} γράφεται ως η κενή συμβολοσειρά. Ενώ αυτή δεν είναι μια αντιστρέψιμη μετατροπή, διευκολύνει την εξαγωγή τιμών NULL SQL σε αρχεία CSV χωρίς προεπεξεργασία των δεδομένων που επιστρέφονται από μια κλήση @cite{cursor.fetch*}. Όλα τα άλλα μη-συμβολοσειριακά δεδομένα μετατρέπονται σε συμβολοσειρές με τη χρήση της @ref{1df,,str()} πριν γραφούν.

Ένα σύντομο παράδειγμα χρήσης:

@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() (στη μονάδα csv)
@anchor{library/csv csv register_dialect}@anchor{1b53}
@deffn {Συνάρτηση} csv.register_dialect (name, /, dialect='excel', **fmtparams)

Συσχετίζει το `dialect' με το `name'. Το `name' πρέπει να είναι μια συμβολοσειρά. Η διάλεκτος μπορεί να καθοριστεί είτε περνώντας μια υποκλάση της @ref{1a3c,,Dialect}, είτε με παραμέτρους `fmtparams' ως ορίσματα, είτε και τα δύο, με τις παραμέτρους `fmtparams' να αντικαθιστούν τις παραμέτρους της διαλέκτου. Για πλήρεις λεπτομέρειες σχετικά με τις διαλέκτους και τις παραμέτρους μορφοποίησης, δείτε την ενότητα @ref{3174,,Διάλεκτοι και Παράμετροι Μορφοποίησης}.
@end deffn

@geindex unregister_dialect() (στη μονάδα csv)
@anchor{library/csv csv unregister_dialect}@anchor{1d8f}
@deffn {Συνάρτηση} csv.unregister_dialect (name)

Διαγράφει τη διάλεκτο που συσχετίζεται με το `name' από το μητρώο διαλέκτων. Μια @ref{3175,,Error} γίνεται raise αν το `name' δεν είναι ένα καταχωρημένο όνομα διαλέκτου.
@end deffn

@geindex get_dialect() (στη μονάδα csv)
@anchor{library/csv csv get_dialect}@anchor{1d8e}
@deffn {Συνάρτηση} csv.get_dialect (name)

Επιστρέφει τη διάλεκτο που συσχετίζεται με το `name'. Μια @ref{3175,,Error} γίνεται raise αν το `name' δεν είναι ένα καταχωρημένο όνομα διαλέκτου. Αυτή η συνάρτηση επιστρέφει μια αμετάβλητη @ref{1a3c,,Dialect}.
@end deffn

@geindex list_dialects() (στη μονάδα csv)
@anchor{library/csv csv list_dialects}@anchor{1d90}
@deffn {Συνάρτηση} csv.list_dialects ()

Επιστρέφει τα ονόματα όλων των καταχωρημένων διαλέκτων.
@end deffn

@geindex field_size_limit() (στη μονάδα csv)
@anchor{library/csv csv field_size_limit}@anchor{1d8d}
@deffn {Συνάρτηση} csv.field_size_limit ()

@deffnx {Συνάρτηση} csv.field_size_limit (new_limit)

Επιστρέφει το τρέχον μέγιστο μέγεθος πεδίου που επιτρέπεται από τον αναλυτή. Αν δοθεί `new_limit', αυτό γίνεται το νέο όριο.
@end deffn

The @code{csv} module defines the following classes:

@geindex DictReader (κλάση σε csv)
@anchor{library/csv csv DictReader}@anchor{da9}
@deffn {Κλάση} csv.DictReader (f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)

Δημιουργεί ένα αντικείμενο που λειτουργεί όπως ένας κανονικός αναγνώστης αλλά χαρτογραφεί τις πληροφορίες σε κάθε γραμμή σε ένα @ref{188,,dict} των οποίων τα κλειδιά δίνονται από την προαιρετική παράμετρο `fieldnames'.

Η παράμετρος `fieldnames' είναι μια @ref{8ff,,sequence}. Αν το `fieldnames' έχει παραληφθεί, οι τιμές στην πρώτη γραμμή του αρχείου `f' θα χρησιμοποιηθούν ως τα ονόματα πεδίων και θα παραλειφθούν από τα αποτελέσματα. Αν το `fieldnames' παρέχεται, θα χρησιμοποιηθούν και η πρώτη γραμμή θα περιληφθεί στα αποτελέσματα. Ανεξάρτητα από το πώς καθορίζονται τα ονόματα πεδίων, το λεξικό διατηρεί την αρχική τους σειρά.

Αν μια γραμμή έχει περισσότερα πεδία από τα ονόματα πεδίων, τα υπόλοιπα δεδομένα τοποθετούνται σε μια λίστα και αποθηκεύονται με το όνομα πεδίου που καθορίζεται από το `restkey' (το οποίο προεπιλέγεται σε @code{None}). Αν μια μη-κενή γραμμή έχει λιγότερα πεδία από τα ονόματα πεδίων, οι ελλείπουσες τιμές συμπληρώνονται με την τιμή του `restval' (το οποίο προεπιλέγεται σε @code{None}).

Όλες οι άλλες προαιρετικές ή παράμετροι λέξεων-κλειδιών μεταβιβάζονται στο υποκείμενο αντικείμενο @ref{898,,reader}.

Αν το όρισμα που δίνεται στο `fieldnames' είναι ένας iterator, θα μετατραπεί σε μια @ref{4d9,,list}.


Άλλαξε στην έκδοση 3.6: Οι επιστρεφόμενες γραμμές είναι τώρα τύπου @code{OrderedDict}.



Άλλαξε στην έκδοση 3.8: Οι επιστρεφόμενες γραμμές είναι τώρα τύπου @ref{188,,dict}.


Ένα σύντομο παράδειγμα χρήσης:

@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 (κλάση σε csv)
@anchor{library/csv csv DictWriter}@anchor{15a7}
@deffn {Κλάση} csv.DictWriter (f, fieldnames, restval='@w{'}, extrasaction='raise', dialect='excel', *args, **kwds)

Δημιουργεί ένα αντικείμενο που λειτουργεί όπως ένας κανονικός εγγραφέας αλλά χαρτογραφεί λεξικά σε εξαγόμενες γραμμές. Η παράμετρος `fieldnames' είναι μια @ref{1f,,sequence} κλειδιών που προσδιορίζουν τη σειρά στην οποία οι τιμές στο λεξικό που περνιούνται στη μέθοδο @ref{11a1,,writerow()} γράφονται στο αρχείο `f'. Η προαιρετική παράμετρος `restval' καθορίζει την τιμή που θα γραφτεί αν από το λεξικό λείπει ένα κλειδί στα  `fieldnames'. Αν το λεξικό που περνιέται στη μέθοδο @code{writerow()} περιέχει ένα κλειδί που δεν βρίσκεται στα `fieldnames', η προαιρετική παράμετρος `extrasaction' υποδεικνύει ποια ενέργεια να ληφθεί. Αν οριστεί σε @code{'raise'}, η προεπιλεγμένη τιμή, γίνεται raise μια @ref{277,,ValueError}. Αν οριστεί σε @code{'ignore'}, οι επιπλέον τιμές στο λεξικό αγνοούνται. Οποιεσδήποτε άλλες προαιρετικές ή παράμετροι λέξεων-κλειδιών μεταβιβάζονται στο υποκείμενο αντικείμενο @ref{899,,writer}.

Σημειώστε ότι σε αντίθεση με την κλάση @ref{da9,,DictReader}, η παράμετρος @cite{*fieldnames*} της κλάσης @ref{15a7,,DictWriter} δεν είναι προαιρετική.

Αν το όρισμα που δίνεται στο `fieldnames' είναι ένας iterator, θα μετατραπεί σε μια @ref{4d9,,list}.

Ένα σύντομο παράδειγμα χρήσης:

@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 (κλάση σε csv)
@anchor{library/csv csv Dialect}@anchor{1a3c}
@deffn {Κλάση} csv.Dialect

Η κλάση @ref{1a3c,,Dialect} είναι μια κλάση κοντέινερ των οποίων τα χαρακτηριστικά περιέχουν πληροφορίες για το πώς να χειριστούν τα διπλά εισαγωγικά, τα κενά, τους διαχωριστές κ.λπ. Λόγω της έλλειψης αυστηρής προδιαγραφής CSV, διαφορετικές εφαρμογές παράγουν λεπτές διαφορές στα δεδομένα CSV. Τα στιγμιότυπα της @code{Dialect} καθορίζουν πώς συμπεριφέρονται τα αντικείμενα @ref{898,,reader} και @ref{899,,writer}.

Όλα τα διαθέσιμα ονόματα @ref{1a3c,,Dialect} επιστρέφονται από τη @ref{1d90,,list_dialects()}, και μπορούν να καταχωρηθούν με συγκεκριμένες κλάσεις @ref{898,,reader} και @ref{899,,writer} μέσω των συναρτήσεων αρχικοποίησης (@code{__init__}) τους όπως αυτό:

@example
import csv

with open('students.csv', 'w', newline='@w{'}) as csvfile:
    writer = csv.writer(csvfile, dialect='unix')
@end example
@end deffn

@geindex excel (κλάση σε csv)
@anchor{library/csv csv excel}@anchor{3176}
@deffn {Κλάση} csv.excel

Η κλάση @ref{3176,,excel} ορίζει τις συνήθεις ιδιότητες ενός αρχείου CSV που δημιουργείται από το Excel. Είναι καταχωρημένη με το όνομα διαλέκτου @code{'excel'}.
@end deffn

@geindex excel_tab (κλάση σε csv)
@anchor{library/csv csv excel_tab}@anchor{3177}
@deffn {Κλάση} csv.excel_tab

Η κλάση @ref{3177,,excel_tab} ορίζει τις συνήθεις ιδιότητες ενός αρχείου CSV που δημιουργείται από το Excel με διαχωριστικό TAB. Είναι καταχωρημένη με το όνομα διαλέκτου @code{'excel-tab'}.
@end deffn

@geindex unix_dialect (κλάση σε csv)
@anchor{library/csv csv unix_dialect}@anchor{15a6}
@deffn {Κλάση} csv.unix_dialect

Η κλάση @ref{15a6,,unix_dialect} ορίζει τις συνήθεις ιδιότητες ενός αρχείου CSV που δημιουργείται σε συστήματα UNIX, δηλαδή χρησιμοποιεί @code{'\n'} ως τερματιστή γραμμής και παραθέτει όλα τα πεδία. Είναι καταχωρημένη με το όνομα διαλέκτου @code{'unix'}.


Added in version 3.2.

@end deffn

@geindex Sniffer (κλάση σε csv)
@anchor{library/csv csv Sniffer}@anchor{3178}
@deffn {Κλάση} csv.Sniffer

Η κλάση @ref{3178,,Sniffer} χρησιμοποιείται για να προσδιορίσει τη μορφή ενός αρχείου CSV.

Η κλάση @ref{3178,,Sniffer} παρέχει δύο μεθόδους:

@geindex sniff() (μέθοδος της csv.Sniffer)
@anchor{library/csv csv Sniffer sniff}@anchor{2c2}
@deffn {Μέθοδος} sniff (sample, delimiters=None)

Αναλύει το δεδομένο `sample' και επιστρέφει μια υποκλάση της @ref{1a3c,,Dialect} που αντικατοπτρίζει τις παραμέτρους που βρέθηκαν. Αν η προαιρετική παράμετρος `delimiters' δοθεί, ερμηνεύεται ως μια συμβολοσειρά που περιέχει πιθανά έγκυρους χαρακτήρες διαχωρισμού.
@end deffn

@geindex has_header() (μέθοδος της csv.Sniffer)
@anchor{library/csv csv Sniffer has_header}@anchor{1e4e}
@deffn {Μέθοδος} has_header (sample)

Αναλύει το δείγμα κειμένου (που θεωρείται ότι είναι σε μορφή CSV) και επιστρέφει @ref{fcc,,True} αν η πρώτη γραμμή φαίνεται να είναι μια σειρά κεφαλίδων στηλών. Εξετάζοντας κάθε στήλη, ένα από τα δύο βασικά κριτήρια θα εξεταστεί για να εκτιμηθεί αν το δείγμα περιέχει κεφαλίδα:


@itemize -

@item 
η δεύτερη έως την n-οστή γραμμή περιέχει αριθμητικές τιμές

@item 
η δεύτερη έως την n-οστή γραμμή περιέχει συμβολοσειρές όπου τουλάχιστον μία τιμή έχει μήκος διαφορετικό από αυτό της υποτιθέμενης κεφαλίδας αυτής της στήλης.
@end itemize

Είκοσι μία γραμμές μετά την κεφαλίδα δειγματοληπτούνται· αν περισσότερες από τις μισές στήλες + γραμμές πληρούν τα κριτήρια, επιστρέφεται @ref{fcc,,True}.
@end deffn

@cartouche
@quotation Σημείωση 
Αυτή η μέθοδος είναι μια χονδροειδής ευρετική και μπορεί να παράγει τόσο ψευδώς θετικά όσο και ψευδώς αρνητικά αποτελέσματα.
@end quotation
@end cartouche
@end deffn

Ένα παράδειγμα χρήσης της @ref{3178,,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{3179}
The @code{csv} module defines the following constants:

@geindex QUOTE_ALL (στη μονάδα csv)
@anchor{library/csv csv QUOTE_ALL}@anchor{317a}
@deffn {Δεδομένα} csv.QUOTE_ALL

Οδηγεί τα αντικείμενα @ref{899,,writer} να παραθέτουν όλα τα πεδία.
@end deffn

@geindex QUOTE_MINIMAL (στη μονάδα csv)
@anchor{library/csv csv QUOTE_MINIMAL}@anchor{317b}
@deffn {Δεδομένα} csv.QUOTE_MINIMAL

Οδηγεί τα αντικείμενα @ref{899,,writer} να παραθέτουν μόνο εκείνα τα πεδία που περιέχουν ειδικούς χαρακτήρες όπως το `delimiter', `quotechar', @code{'\r'}, @code{'\n'} ή οποιονδήποτε από τους χαρακτήρες στο `lineterminator'.
@end deffn

@geindex QUOTE_NONNUMERIC (στη μονάδα csv)
@anchor{library/csv csv QUOTE_NONNUMERIC}@anchor{1b5f}
@deffn {Δεδομένα} csv.QUOTE_NONNUMERIC

Οδηγεί τα αντικείμενα @ref{899,,writer} να παραθέτουν όλα τα μη-αριθμητικά πεδία.

Οδηγεί τα αντικείμενα @ref{898,,reader} να μετατρέπουν όλα τα μη-παρατεθειμένα πεδία σε τύπο @ref{327,,float}.

@cartouche
@quotation Σημείωση 
Ορισμένοι αριθμητικοί τύποι, όπως @ref{5ef,,bool}, @ref{1c3,,Fraction}, ή @ref{109d,,IntEnum}, έχουν μια αναπαράσταση συμβολοσειράς που δεν μπορεί να μετατραπεί σε @ref{327,,float}. Δεν μπορούν να διαβαστούν σε λειτουργίες @ref{1b5f,,QUOTE_NONNUMERIC} και @ref{897,,QUOTE_STRINGS}.
@end quotation
@end cartouche
@end deffn

@geindex QUOTE_NONE (στη μονάδα csv)
@anchor{library/csv csv QUOTE_NONE}@anchor{317c}
@deffn {Δεδομένα} csv.QUOTE_NONE

Οδηγεί τα αντικείμενα @ref{899,,writer} να μην παραθέτουν ποτέ πεδία. Όταν ο τρέχων `delimiter', `quotechar', `escapechar', @code{'\r'}, @code{'\n'} ή οποιοσδήποτε από τους χαρακτήρες στο `lineterminator' εμφανίζεται στα δεδομένα εξόδου, προηγείται από τον τρέχοντα χαρακτήρα `escapechar'. Αν το `escapechar' δεν έχει οριστεί, ο εγγραφέας θα κάνει raise μια @ref{3175,,Error} αν συναντηθούν χαρακτήρες που απαιτούν απόδραση. Ορίστε το `quotechar' σε @code{None} για να αποτρέψετε την απόδρασή του.

Οδηγεί τα αντικείμενα @ref{898,,reader} να μην εκτελούν ειδική επεξεργασία των χαρακτήρων παράθεσης.
@end deffn

@geindex QUOTE_NOTNULL (στη μονάδα csv)
@anchor{library/csv csv QUOTE_NOTNULL}@anchor{896}
@deffn {Δεδομένα} csv.QUOTE_NOTNULL

Οδηγεί τα αντικείμενα @ref{899,,writer} να παραθέτουν όλα τα πεδία που δεν είναι @code{None}. Αυτό είναι παρόμοιο με @ref{317a,,QUOTE_ALL}, εκτός από το ότι αν μια τιμή πεδίου είναι @code{None}, γράφεται μια κενή (μη-παρατεθειμένη) συμβολοσειρά.

Οδηγεί τα αντικείμενα @ref{898,,reader} να ερμηνεύουν ένα κενό (μη-παρατεθειμένο) πεδίο ως @code{None} και να συμπεριφέρονται διαφορετικά ως @ref{317a,,QUOTE_ALL}.


Added in version 3.12.

@end deffn

@geindex QUOTE_STRINGS (στη μονάδα csv)
@anchor{library/csv csv QUOTE_STRINGS}@anchor{897}
@deffn {Δεδομένα} csv.QUOTE_STRINGS

Οδηγεί τα αντικείμενα @ref{899,,writer} να τοποθετούν πάντα εισαγωγικά γύρω από πεδία που είναι συμβολοσειρές. Αυτό είναι παρόμοιο με @ref{1b5f,,QUOTE_NONNUMERIC}, εκτός από το ότι αν μια τιμή πεδίου είναι @code{None}, γράφεται μια κενή (μη-παρατεθειμένη) συμβολοσειρά.

Οδηγεί τα αντικείμενα @ref{898,,reader} να ερμηνεύουν μια κενή (μη-παρατεθειμένη) συμβολοσειρά ως @code{None} και να συμπεριφέρονται διαφορετικά ως @ref{1b5f,,QUOTE_NONNUMERIC}.


Added in version 3.12.

@end deffn

The @code{csv} module defines the following exception:

@geindex Error
@anchor{library/csv csv Error}@anchor{3175}
@deffn {Εξαίρεση} csv.Error

Γίνεται raise από οποιαδήποτε από τις συναρτήσεις όταν ανιχνεύεται ένα σφάλμα.
@end deffn

@node Διάλεκτοι και Παράμετροι Μορφοποίησης,Αντικείμενα Αναγνώστη,Περιεχόμενα του Module,csv — Ανάγνωση και Εγγραφή Αρχείων CSV
@anchor{library/csv csv-fmt-params}@anchor{3174}@anchor{library/csv dialects-and-formatting-parameters}@anchor{317d}
@subsubsection Διάλεκτοι και Παράμετροι Μορφοποίησης


Για να διευκολυνθεί ο καθορισμός της μορφής των εγγραφών εισόδου και εξόδου, οι συγκεκριμένες παράμετροι μορφοποίησης ομαδοποιούνται σε διαλέκτους. Μια διάλεκτος είναι μια υποκλάση της κλάσης @ref{1a3c,,Dialect} που περιέχει διάφορα χαρακτηριστικά που περιγράφουν τη μορφή του αρχείου CSV. Κατά τη δημιουργία αντικειμένων @ref{898,,reader} ή @ref{899,,writer}, ο προγραμματιστής μπορεί να καθορίσει μια συμβολοσειρά ή μια υποκλάση της κλάσης @code{Dialect} ως παράμετρο διαλέκτου. Επιπλέον, αντί για ή εκτός από την παράμετρο `dialect', ο προγραμματιστής μπορεί επίσης να καθορίσει μεμονωμένες παραμέτρους μορφοποίησης, οι οποίες έχουν τα ίδια ονόματα με τα χαρακτηριστικά που ορίζονται παρακάτω για την κλάση @code{Dialect}.

Οι διάλεκτοι υποστηρίζουν τα παρακάτω χαρακτηριστικά:

@geindex delimiter (ιδιότητα της csv.Dialect)
@anchor{library/csv csv Dialect delimiter}@anchor{317e}
@deffn {Ιδιότητα} Dialect.delimiter

Μια συμβολοσειρά ενός χαρακτήρα που χρησιμοποιείται για να διαχωρίζει τα πεδία. Προεπιλογή είναι το @code{','}.
@end deffn

@geindex doublequote (ιδιότητα της csv.Dialect)
@anchor{library/csv csv Dialect doublequote}@anchor{317f}
@deffn {Ιδιότητα} Dialect.doublequote

Ελέγχει πώς οι περιπτώσεις του `quotechar' που εμφανίζονται μέσα σε ένα πεδίο θα παρατίθενται. Όταν είναι @ref{fcc,,True}, ο χαρακτήρας διπλασιάζεται. Όταν είναι @ref{ef5,,False}, το `escapechar' χρησιμοποιείται ως πρόθεμα στο `quotechar'. Προεπιλογή είναι το @code{True}.

Στην έξοδο, αν το `doublequote' είναι @ref{ef5,,False} και δεν έχει οριστεί `escapechar', γίνεται raise @ref{3175,,Error} αν βρεθεί ένα `quotechar' σε ένα πεδίο.
@end deffn

@geindex escapechar (ιδιότητα της csv.Dialect)
@anchor{library/csv csv Dialect escapechar}@anchor{3180}
@deffn {Ιδιότητα} Dialect.escapechar

Μια συμβολοσειρά ενός χαρακτήρα που χρησιμοποιείται από τον εγγραφέα για να διαφύγει χαρακτήρες που απαιτούν escape:

@quotation


@itemize *

@item 
το `delimiter', το `quotechar', @code{'\r'}, @code{'\n'} και οποιοσδήποτε από τους χαρακτήρες στο `lineterminator' διαφεύγουν αν το `quoting' έχει οριστεί σε @ref{317c,,QUOTE_NONE} ∙

@item 
το `quotechar' διαφεύγει αν το `doublequote' είναι @ref{ef5,,False} ∙

@item 
το ίδιο το `escapechar'.
@end itemize
@end quotation

Κατά την ανάγνωση, το `escapechar' αφαιρεί οποιαδήποτε ειδική σημασία από τον επόμενο χαρακτήρα. Προεπιλογή είναι το @ref{a65,,None}, που απενεργοποιεί το escaping.


Άλλαξε στην έκδοση 3.11: Ένα κενό `escapechar' δεν επιτρέπεται.

@end deffn

@geindex lineterminator (ιδιότητα της csv.Dialect)
@anchor{library/csv csv Dialect lineterminator}@anchor{3181}
@deffn {Ιδιότητα} Dialect.lineterminator

Η συμβολοσειρά που χρησιμοποιείται για να τερματίσει τις γραμμές που παράγονται από τον @ref{899,,writer}. Προεπιλογή είναι το @code{'\r\n'}.

@cartouche
@quotation Σημείωση 
Ο @ref{898,,reader} είναι σκληρά κωδικοποιημένος για να αναγνωρίζει είτε @code{'\r'} είτε @code{'\n'} ως τερματισμό γραμμής, και αγνοεί το `lineterminator'. Αυτή η συμπεριφορά μπορεί να αλλάξει στο μέλλον.
@end quotation
@end cartouche
@end deffn

@geindex quotechar (ιδιότητα της csv.Dialect)
@anchor{library/csv csv Dialect quotechar}@anchor{3182}
@deffn {Ιδιότητα} Dialect.quotechar

Μια συμβολοσειρά ενός χαρακτήρα που χρησιμοποιείται για να παραθέτει πεδία που περιέχουν ειδικούς χαρακτήρες, όπως το `delimiter' ή το `quotechar', ή που περιέχουν χαρακτήρες νέας γραμμής (@code{'\r'}, @code{'\n'} ή οποιοσδήποτε από τους χαρακτήρες στο `lineterminator'). Προεπιλογή είναι το @code{'"'}. Μπορεί να οριστεί σε @code{None} για να αποτραπεί το escaping του @code{'"'} αν το `quoting' έχει οριστεί σε @ref{317c,,QUOTE_NONE}.


Άλλαξε στην έκδοση 3.11: Ένα κενό `quotechar' δεν επιτρέπεται.

@end deffn

@geindex quoting (ιδιότητα της csv.Dialect)
@anchor{library/csv csv Dialect quoting}@anchor{3183}
@deffn {Ιδιότητα} Dialect.quoting

Ελέγχει πότε θα δημιουργούνται εισαγωγικά από τον εγγραφέα και θα αναγνωρίζονται από τον αναγνώστη. Μπορεί να πάρει οποιαδήποτε από τις σταθερές @ref{3179,,QUOTE_* constants} και προεπιλογή είναι το @ref{317b,,QUOTE_MINIMAL} αν το `quotechar' δεν είναι @code{None}, και το @ref{317c,,QUOTE_NONE} διαφορετικά.
@end deffn

@geindex skipinitialspace (ιδιότητα της csv.Dialect)
@anchor{library/csv csv Dialect skipinitialspace}@anchor{3184}
@deffn {Ιδιότητα} Dialect.skipinitialspace

Όταν είναι @ref{fcc,,True}, τα κενά που ακολουθούν άμεσα τον `delimiter' αγνοούνται. Η προεπιλογή είναι @ref{ef5,,False}. Όταν συνδυάζεται το @code{delimiter=' '} με το @code{skipinitialspace=True}, δεν επιτρέπονται μη παραθερισμένα κενά πεδία.
@end deffn

@geindex strict (ιδιότητα της csv.Dialect)
@anchor{library/csv csv Dialect strict}@anchor{3185}
@deffn {Ιδιότητα} Dialect.strict

Όταν είναι @code{True}, γίνεται raise η εξαίρεση @ref{3175,,Error} σε κακή είσοδο CSV. Η προεπιλογή είναι @code{False}.
@end deffn

@node Αντικείμενα Αναγνώστη,Αντικείμενα Εγγραφέα,Διάλεκτοι και Παράμετροι Μορφοποίησης,csv — Ανάγνωση και Εγγραφή Αρχείων CSV
@anchor{library/csv id3}@anchor{3186}@anchor{library/csv reader-objects}@anchor{3173}
@subsubsection Αντικείμενα Αναγνώστη


Τα αντικείμενα αναγνώστη (στιγμιότυπα της @ref{da9,,DictReader} και αντικείμενα που επιστρέφονται από τη συνάρτηση @ref{898,,reader()}) έχουν τις παρακάτω δημόσιες μεθόδους:

@geindex __next__() (μέθοδος της csv.csvreader)
@anchor{library/csv csv csvreader __next__}@anchor{3187}
@deffn {Μέθοδος} csvreader.__next__ ()

Επιστρέφει την επόμενη γραμμή του αντικειμένου iterable του αναγνώστη ως λίστα (αν το αντικείμενο επιστράφηκε από τη @ref{898,,reader()}) ή ως λεξικό (αν είναι ένα στιγμιότυπο @ref{da9,,DictReader}), αναλυμένο σύμφωνα με την τρέχουσα @ref{1a3c,,Dialect}. Συνήθως θα πρέπει να το καλέσετε ως @code{next(reader)}.
@end deffn

Τα αντικείμενα αναγνώστη έχουν τα παρακάτω δημόσια χαρακτηριστικά:

@geindex dialect (ιδιότητα της csv.csvreader)
@anchor{library/csv csv csvreader dialect}@anchor{3188}
@deffn {Ιδιότητα} csvreader.dialect

Ένα μόνο για ανάγνωση περιγραφικό χαρακτηριστικό της διαλέκτου που χρησιμοποιείται από τον αναλυτή.
@end deffn

@geindex line_num (ιδιότητα της csv.csvreader)
@anchor{library/csv csv csvreader line_num}@anchor{3189}
@deffn {Ιδιότητα} csvreader.line_num

Ο αριθμός των γραμμών που διαβάστηκαν από τον πηγαίο επαναληπτή. Αυτό δεν είναι το ίδιο με τον αριθμό των εγγραφών που επιστράφηκαν, καθώς οι εγγραφές μπορούν να εκτείνονται σε πολλές γραμμές.
@end deffn

Τα αντικείμενα DictReader έχουν το παρακάτω δημόσιο χαρακτηριστικό:

@geindex fieldnames (ιδιότητα της csv.DictReader)
@anchor{library/csv csv DictReader fieldnames}@anchor{318a}
@deffn {Ιδιότητα} DictReader.fieldnames

Αν δεν περαστεί ως παράμετρος κατά τη δημιουργία του αντικειμένου, αυτό το χαρακτηριστικό αρχικοποιείται κατά την πρώτη πρόσβαση ή όταν διαβαστεί η πρώτη εγγραφή από το αρχείο.
@end deffn

@node Αντικείμενα Εγγραφέα,Παραδείγματα<3>,Αντικείμενα Αναγνώστη,csv — Ανάγνωση και Εγγραφή Αρχείων CSV
@anchor{library/csv writer-objects}@anchor{318b}
@subsubsection Αντικείμενα Εγγραφέα


Τα αντικείμενα @ref{899,,writer} (στιγμιότυπα της @ref{15a7,,DictWriter} και αντικείμενα που επιστρέφονται από τη συνάρτηση @ref{899,,writer()}) έχουν τις παρακάτω δημόσιες μεθόδους. Ένα `row' πρέπει να είναι ένα επαναληπτικό αντικείμενο συμβολοσειρών ή αριθμών για τα αντικείμενα @code{writer} και ένα λεξικό που αντιστοιχεί τα ονόματα πεδίων σε συμβολοσειρές ή αριθμούς (με πέρασμα μέσω της συνάρτησης @ref{1df,,str()} πρώτα) για τα αντικείμενα @code{DictWriter}. Σημειώστε ότι οι σύνθετοι αριθμοί γράφονται περιβαλλόμενοι από παρενθέσεις. Αυτό μπορεί να προκαλέσει κάποια προβλήματα σε άλλα προγράμματα που διαβάζουν αρχεία CSV (υποθέτοντας ότι υποστηρίζουν σύνθετους αριθμούς καθόλου).

@geindex writerow() (μέθοδος της csv.csvwriter)
@anchor{library/csv csv csvwriter writerow}@anchor{11a1}
@deffn {Μέθοδος} csvwriter.writerow (row, /)

Γράφει την παράμετρο `row' στο αντικείμενο αρχείου του εγγραφέα, μορφοποιημένο σύμφωνα με την τρέχουσα @ref{1a3c,,Dialect}. Επιστρέφει την τιμή επιστροφής της κλήσης στη μέθοδο `write' του υποκείμενου αντικειμένου αρχείου.


Άλλαξε στην έκδοση 3.5: Προστέθηκε υποστήριξη για αυθαίρετα επαναληπτικά αντικείμενα.

@end deffn

@geindex writerows() (μέθοδος της csv.csvwriter)
@anchor{library/csv csv csvwriter writerows}@anchor{318c}
@deffn {Μέθοδος} csvwriter.writerows (rows, /)

Γράφει όλα τα στοιχεία στο `rows' (ένα επαναληπτικό αντικείμενο των `row' αντικειμένων όπως περιγράφεται παραπάνω) στο αντικείμενο αρχείου του εγγραφέα, μορφοποιημένο σύμφωνα με την τρέχουσα διάλεκτο.
@end deffn

Τα αντικείμενα εγγραφέα έχουν το παρακάτω δημόσιο χαρακτηριστικό:

@geindex dialect (ιδιότητα της csv.csvwriter)
@anchor{library/csv csv csvwriter dialect}@anchor{318d}
@deffn {Ιδιότητα} csvwriter.dialect

Ένα μόνο για ανάγνωση περιγραφικό χαρακτηριστικό της διαλέκτου που χρησιμοποιείται από τον εγγραφέα.
@end deffn

Τα αντικείμενα DictWriter έχουν την παρακάτω δημόσια μέθοδο:

@geindex writeheader() (μέθοδος της csv.DictWriter)
@anchor{library/csv csv DictWriter writeheader}@anchor{15a8}
@deffn {Μέθοδος} DictWriter.writeheader ()

Γράφει μια γραμμή με τα ονόματα πεδίων (όπως καθορίζονται στον κατασκευαστή) στο αντικείμενο αρχείου του εγγραφέα, μορφοποιημένο σύμφωνα με την τρέχουσα διάλεκτο. Επιστρέφει την τιμή επιστροφής της κλήσης @ref{11a1,,csvwriter.writerow()} που χρησιμοποιείται εσωτερικά.


Added in version 3.2.



Άλλαξε στην έκδοση 3.8: Η @ref{15a8,,writeheader()} τώρα επιστρέφει επίσης την τιμή που επιστρέφεται από τη μέθοδο @ref{11a1,,csvwriter.writerow()} που χρησιμοποιεί εσωτερικά.

@end deffn

@node Παραδείγματα<3>,,Αντικείμενα Εγγραφέα,csv — Ανάγνωση και Εγγραφή Αρχείων CSV
@anchor{library/csv csv-examples}@anchor{318e}@anchor{library/csv examples}@anchor{318f}
@subsubsection Παραδείγματα


Το πιο απλό παράδειγμα ανάγνωσης ενός αρχείου CSV:

@example
import csv
with open('some.csv', newline='@w{'}) as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)
@end example

Ανάγνωση ενός αρχείου με εναλλακτική μορφή:

@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

Το αντίστοιχο απλούστερο παράδειγμα εγγραφής είναι:

@example
import csv
with open('some.csv', 'w', newline='@w{'}) as f:
    writer = csv.writer(f)
    writer.writerows(someiterable)
@end example

Αφού η @ref{32b,,open()} χρησιμοποιείται για να ανοίξει ένα αρχείο CSV για ανάγνωση, το αρχείο θα αποκωδικοποιηθεί κατά προεπιλογή σε unicode χρησιμοποιώντας την προεπιλεγμένη κωδικοποίηση του συστήματος (βλ. @ref{a45,,locale.getencoding()}). Για να αποκωδικοποιήσετε ένα αρχείο χρησιμοποιώντας μια διαφορετική κωδικοποίηση, χρησιμοποιήστε το όρισμα @code{encoding} της 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

Το ίδιο ισχύει και για την εγγραφή σε κάτι άλλο εκτός από την προεπιλεγμένη κωδικοποίηση του συστήματος: καθορίστε το όρισμα κωδικοποίησης κατά το άνοιγμα του αρχείου εξόδου.

Καταχώρηση μιας νέας διαλέκτου:

@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

Μια ελαφρώς πιο προηγμένη χρήση του αναγνώστη — σύλληψη και αναφορά σφαλμάτων:

@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(f'file @{filename@}, line @{reader.line_num@}: @{e@}')
@end example

Και ενώ το module δεν υποστηρίζει άμεσα την ανάλυση συμβολοσειρών, μπορεί εύκολα να γίνει:

@example
import csv
for row in csv.reader(['one,two,three']):
    print(row)
@end example

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node configparser — Configuration file parser,tomllib — Parse TOML files,csv — Ανάγνωση και Εγγραφή Αρχείων CSV,File Formats
@anchor{library/configparser doc}@anchor{3190}@anchor{library/configparser configparser-configuration-file-parser}@anchor{3191}@anchor{library/configparser module-configparser}@anchor{26}@anchor{library/configparser translation-repo}@anchor{3192}
@subsection @code{configparser} — Configuration file parser


@geindex module; configparser

`Source code:' Lib/configparser.py@footnote{https://github.com/python/cpython/tree/main/Lib/configparser.py}

@geindex .ini;file
@geindex configuration;file
@geindex ini file
@geindex Windows ini file


__________________________________________________________________


This module provides the @ref{6e4,,ConfigParser} class which implements a basic
configuration language which provides a structure similar to what’s found in
Microsoft Windows INI files.  You can use this to write Python programs which
can be customized by end users easily.

@cartouche
@quotation Σημείωση 
This library does `not' interpret or write the value-type prefixes used in
the Windows Registry extended version of INI syntax.
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
Be cautious when parsing data from untrusted sources. A malicious
INI file 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


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{105,,tomllib}

TOML is a well-specified format for application configuration files.
It is specifically designed to be an improved version of INI.

@item Module @ref{cc,,shlex}

Support for creating Unix shell-like mini-languages which can also
be used for application configuration files.

@item Module @ref{85,,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
* Quick Start:: 
* Supported Datatypes:: 
* Fallback Values:: 
* Supported INI File Structure:: 
* Unnamed Sections:: 
* Interpolation of values:: 
* Mapping Protocol Access:: 
* Customizing Parser Behaviour:: 
* Legacy API Examples:: 
* ConfigParser Objects:: 
* RawConfigParser Objects:: 
* Exceptions: Exceptions<8>. 

@end menu

@node Quick Start,Supported Datatypes,,configparser — Configuration file parser
@anchor{library/configparser quick-start}@anchor{3193}
@subsubsection Quick Start


Let’s take a very basic configuration file that looks like this:

@example
[DEFAULT]
ServerAliveInterval = 45
Compression = yes
CompressionLevel = 9
ForwardX11 = yes

[forge.example]
User = hg

[topsecret.server.example]
Port = 50022
ForwardX11 = no
@end example

The structure of INI files is described @ref{3194,,in the following section}.  Essentially, the file
consists of sections, each of which contains keys with values.
@code{configparser} classes can read and write such files.  Let’s start by
creating the above configuration file programmatically.

@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

As you can see, we can treat a config parser much like a dictionary.
There are differences, @ref{3195,,outlined later}, but
the behavior is very close to what you would expect from a dictionary.

Now that we have created and saved a configuration file, let’s read it
back and explore the data it holds.

@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

As we can see above, the API is pretty straightforward.  The only bit of magic
involves the @code{DEFAULT} section which provides default values for all other
sections @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{3196,,Customizing Parser Behaviour} section.
}.  Note also that keys in sections are
case-insensitive and stored in lowercase @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{3196,,Customizing Parser Behaviour} section.
}.

It is possible to read several configurations into a single
@ref{6e4,,ConfigParser}, where the most recently added configuration has the
highest priority. Any conflicting keys are taken from the more recent
configuration while the previously existing keys are retained. The example
below reads in an @code{override.ini} file, which will override any conflicting
keys from the @code{example.ini} file.

@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

This behaviour is equivalent to a @ref{180a,,ConfigParser.read()} call with several
files passed to the `filenames' parameter.

@node Supported Datatypes,Fallback Values,Quick Start,configparser — Configuration file parser
@anchor{library/configparser supported-datatypes}@anchor{3197}
@subsubsection Supported Datatypes


Config parsers do not guess datatypes of values in configuration files, always
storing them internally as strings.  This means that if you need other
datatypes, you should convert on your own:

@example
>>> int(topsecret['Port'])
50022
>>> float(topsecret['CompressionLevel'])
9.0
@end example

Since this task is so common, config parsers provide a range of handy getter
methods to handle integers, floats and booleans.  The last one is the most
interesting because simply passing the value to @code{bool()} would do no good
since @code{bool('False')} is still @code{True}.  This is why config parsers also
provide @ref{3198,,getboolean()}.  This method is case-insensitive and
recognizes Boolean values from @code{'yes'}/@code{'no'}, @code{'on'}/@code{'off'},
@code{'true'}/@code{'false'} and @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{3196,,Customizing Parser Behaviour} section.
}.  For example:

@example
>>> topsecret.getboolean('ForwardX11')
False
>>> config['forge.example'].getboolean('ForwardX11')
True
>>> config.getboolean('forge.example', 'Compression')
True
@end example

Apart from @ref{3198,,getboolean()}, config parsers also
provide equivalent @ref{3199,,getint()} and
@ref{319a,,getfloat()} methods.  You can register your own
converters and customize the provided ones. @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{3196,,Customizing Parser Behaviour} section.
}

@node Fallback Values,Supported INI File Structure,Supported Datatypes,configparser — Configuration file parser
@anchor{library/configparser fallback-values}@anchor{319b}
@subsubsection Fallback Values


As with a dictionary, you can use a section’s @ref{1610,,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{1610,,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

The same @code{fallback} argument can be used with the
@ref{3199,,getint()}, @ref{319a,,getfloat()} and
@ref{3198,,getboolean()} methods, for example:

@example
>>> 'BatchMode' in topsecret
False
>>> topsecret.getboolean('BatchMode', fallback=True)
True
>>> config['DEFAULT']['BatchMode'] = 'no'
>>> topsecret.getboolean('BatchMode', fallback=True)
False
@end example

@node Supported INI File Structure,Unnamed Sections,Fallback Values,configparser — Configuration file parser
@anchor{library/configparser supported-ini-file-structure}@anchor{3194}
@subsubsection Supported INI File Structure


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{3196,,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{3196,,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{3196,,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.

By default, a valid section name can be any string that does not contain “\n”.
To change this, see @ref{319c,,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{199c,,UNNAMED_SECTION} as in
@code{config[UNNAMED_SECTION]}.

Configuration files may include comments, prefixed by specific
characters (@code{#} and @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{3196,,Customizing Parser Behaviour} section.
}).  Comments may appear on
their own on an otherwise empty line, possibly indented. @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{3196,,Customizing Parser Behaviour} section.
}

For example:

@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 of values,Supported INI File Structure,configparser — Configuration file parser
@anchor{library/configparser id10}@anchor{319d}@anchor{library/configparser unnamed-sections}@anchor{319e}
@subsubsection Unnamed Sections


The name of the first section (or unique) may be omitted and values
retrieved by the @ref{199c,,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 of values,Mapping Protocol Access,Unnamed Sections,configparser — Configuration file parser
@anchor{library/configparser interpolation-of-values}@anchor{319f}
@subsubsection Interpolation of values


On top of the core functionality, @ref{6e4,,ConfigParser} supports
interpolation.  This means values can be preprocessed before returning them
from @code{get()} calls.

@geindex % (percent);interpolation in configuration files

@geindex BasicInterpolation (κλάση σε configparser)
@anchor{library/configparser configparser BasicInterpolation}@anchor{b0a}
@deffn {Κλάση} configparser.BasicInterpolation

The default implementation used by @ref{6e4,,ConfigParser}.  It enables
values to contain format strings which refer to other values in the same
section, or values in the special default section @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{3196,,Customizing Parser Behaviour} section.
}.  Additional default
values can be provided on initialization.

For example:

@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

In the example above, @ref{6e4,,ConfigParser} with `interpolation' set to
@code{BasicInterpolation()} would resolve @code{%(home_dir)s} to the value of
@code{home_dir} (@code{/Users} in this case).  @code{%(my_dir)s} in effect would
resolve to @code{/Users/lumberjack}.  All interpolations are done on demand so
keys used in the chain of references do not have to be specified in any
specific order in the configuration file.

With @code{interpolation} set to @code{None}, the parser would simply return
@code{%(my_dir)s/Pictures} as the value of @code{my_pictures} and
@code{%(home_dir)s/lumberjack} as the value of @code{my_dir}.
@end deffn

@geindex $ (dollar);interpolation in configuration files

@geindex ExtendedInterpolation (κλάση σε configparser)
@anchor{library/configparser configparser ExtendedInterpolation}@anchor{b0b}
@deffn {Κλάση} configparser.ExtendedInterpolation

An alternative handler for interpolation which implements a more advanced
syntax, used for instance in @code{zc.buildout}.  Extended interpolation is
using @code{$@{section:option@}} to denote a value from a foreign section.
Interpolation can span multiple levels.  For convenience, if the
@code{section:} part is omitted, interpolation defaults to the current section
(and possibly the default values from the special section).

For example, the configuration specified above with basic interpolation,
would look like this with extended interpolation:

@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

Values from other sections can be fetched as well:

@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 Mapping Protocol Access,Customizing Parser Behaviour,Interpolation of values,configparser — Configuration file parser
@anchor{library/configparser mapping-protocol-access}@anchor{3195}
@subsubsection Mapping Protocol Access



Added in version 3.2.


Mapping protocol access is a generic name for functionality that enables using
custom objects as if they were dictionaries.  In case of @code{configparser},
the mapping interface implementation is using the
@code{parser['section']['option']} notation.

@code{parser['section']} in particular returns a proxy for the section’s data in
the parser.  This means that the values are not copied but they are taken from
the original parser on demand.  What’s even more important is that when values
are changed on a section proxy, they are actually mutated in the original
parser.

@code{configparser} objects behave as close to actual dictionaries as possible.
The mapping interface is complete and adheres to the
@ref{1459,,MutableMapping} ABC.
However, there are a few differences that should be taken into account:


@itemize *

@item 
By default, all keys in sections are accessible in a case-insensitive manner
@footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{3196,,Customizing Parser Behaviour} section.
}.  E.g. @code{for option in parser["section"]} yields only @code{optionxform}’ed
option key names.  This means lowercased keys by default.  At the same time,
for a section that holds the key @code{'a'}, both expressions return @code{True}:

@example
"a" in parser["section"]
"A" in parser["section"]
@end example

@item 
All sections include @code{DEFAULTSECT} values as well which means that
@code{.clear()} on a section may not leave the section visibly empty.  This is
because default values cannot be deleted from the section (because technically
they are not there).  If they are overridden in the section, deleting causes
the default value to be visible again.  Trying to delete a default value
causes a @ref{7df,,KeyError}.

@item 
@code{DEFAULTSECT} cannot be removed from the parser:


@itemize *

@item 
trying to delete it raises @ref{277,,ValueError},

@item 
@code{parser.clear()} leaves it intact,

@item 
@code{parser.popitem()} never returns it.
@end itemize

@item 
@code{parser.get(section, option, **kwargs)} - the second argument is `not'
a fallback value.  Note however that the section-level @code{get()} methods are
compatible both with the mapping protocol and the classic configparser API.

@item 
@code{parser.items()} is compatible with the mapping protocol (returns a list of
`section_name', `section_proxy' pairs including the DEFAULTSECT).  However,
this method can also be invoked with arguments: @code{parser.items(section, raw,
vars)}.  The latter call returns a list of `option', `value' pairs for
a specified @code{section}, with all interpolations expanded (unless
@code{raw=True} is provided).
@end itemize

The mapping protocol is implemented on top of the existing legacy API so that
subclasses overriding the original interface still should have mappings working
as expected.

@node Customizing Parser Behaviour,Legacy API Examples,Mapping Protocol Access,configparser — Configuration file parser
@anchor{library/configparser customizing-parser-behaviour}@anchor{3196}
@subsubsection Customizing Parser Behaviour


There are nearly as many INI format variants as there are applications using it.
@code{configparser} goes a long way to provide support for the largest sensible
set of INI styles available.  The default functionality is mainly dictated by
historical background and it’s very likely that you will want to customize some
of the features.

The most common way to change the way a specific config parser works is to use
the @code{__init__()} options:


@itemize *

@item 
`defaults', default value: @code{None}

This option accepts a dictionary of key-value pairs which will be initially
put in the @code{DEFAULT} section.  This makes for an elegant way to support
concise configuration files that don’t specify values which are the same as
the documented default.

Hint: if you want to specify default values for a specific section, use
@ref{31a0,,read_dict()} before you read the actual file.

@item 
`dict_type', default value: @ref{188,,dict}

This option has a major impact on how the mapping protocol will behave and how
the written configuration files look.  With the standard dictionary, every
section is stored in the order they were added to the parser.  Same goes for
options within sections.

An alternative dictionary type can be used for example to sort sections and
options on write-back.

Please note: there are ways to add a set of key-value pairs in a single
operation.  When you use a regular dictionary in those operations, the order
of the keys will be ordered.  For example:

@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', default value: @code{False}

Some configuration files are known to include settings without values, but
which otherwise conform to the syntax supported by @code{configparser}.  The
`allow_no_value' parameter to the constructor can be used to
indicate that such values should be accepted:

@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', default value: @code{('=', ':')}

Delimiters are substrings that delimit keys from values within a section.
The first occurrence of a delimiting substring on a line is considered
a delimiter.  This means values (but not keys) can contain the delimiters.

See also the `space_around_delimiters' argument to
@ref{475,,ConfigParser.write()}.

@item 
`comment_prefixes', default value: @code{('#', ';')}

@item 
`inline_comment_prefixes', default value: @code{None}

Comment prefixes are strings that indicate the start of a valid comment within
a config file. `comment_prefixes' are used only on otherwise empty lines
(optionally indented) whereas `inline_comment_prefixes' can be used after
every valid value (e.g. section names, options and empty lines as well).  By
default inline comments are disabled and @code{'#'} and @code{';'} are used as
prefixes for whole line comments.


Άλλαξε στην έκδοση 3.2: In previous versions of @code{configparser} behaviour matched
@code{comment_prefixes=('#',';')} and @code{inline_comment_prefixes=(';',)}.


Please note that config parsers don’t support escaping of comment prefixes so
using `inline_comment_prefixes' may prevent users from specifying option
values with characters used as comment prefixes.  When in doubt, avoid
setting `inline_comment_prefixes'.  In any circumstances, the only way of
storing comment prefix characters at the beginning of a line in multiline
values is to interpolate the prefix, for example:

@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 
`strict', default value: @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{915,,read_file()},
@ref{31a1,,read_string()} or @ref{31a0,,read_dict()}).  It is recommended to use strict
parsers in new applications.


Άλλαξε στην έκδοση 3.2: In previous versions of @code{configparser} behaviour matched
@code{strict=False}.


@item 
`empty_lines_in_values', default value: @code{True}

In config parsers, values can span multiple lines as long as they are
indented more than the key that holds them.  By default parsers also let
empty lines to be parts of values.  At the same time, keys can be arbitrarily
indented themselves to improve readability.  In consequence, when
configuration files get big and complex, it is easy for the user to lose
track of the file structure.  Take for instance:

@example
[Section]
key = multiline
  value with a gotcha

 this = is still a part of the multiline value of 'key'
@end example

This can be especially problematic for the user to see if she’s using a
proportional font to edit the file.  That is why when your application does
not need values with empty lines, you should consider disallowing them.  This
will make empty lines split keys every time.  In the example above, it would
produce two keys, @code{key} and @code{this}.

@item 
`default_section', default value: @code{configparser.DEFAULTSECT} (that is:
@code{"DEFAULT"})

The convention of allowing a special section of default values for other
sections or interpolation purposes is a powerful concept of this library,
letting users create complex declarative configurations.  This section is
normally called @code{"DEFAULT"} but this can be customized to point to any
other valid section name.  Some typical values include: @code{"general"} or
@code{"common"}.  The name provided is used for recognizing default sections
when reading from any source and is used when writing configuration back to
a file.  Its current value can be retrieved using the
@code{parser_instance.default_section} attribute and may be modified at runtime
(i.e. to convert files from one format to another).

@item 
`interpolation', default value: @code{configparser.BasicInterpolation}

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{319f,,dedicated documentation section}.
@ref{130e,,RawConfigParser} has a default value of @code{None}.

@item 
`converters', default value: not set

Config parsers provide option value getters that perform type conversion.  By
default @ref{3199,,getint()}, @ref{319a,,getfloat()}, and
@ref{3198,,getboolean()} are implemented.  Should other getters be
desirable, users may define them in a subclass or pass a dictionary where each
key is a name of the converter and each value is a callable implementing said
conversion.  For instance, passing @code{@{'decimal': decimal.Decimal@}} would add
@code{getdecimal()} on both the parser object and all section proxies.  In
other words, it will be possible to write both
@code{parser_instance.getdecimal('section', 'key', fallback=0)} and
@code{parser_instance['section'].getdecimal('key', 0)}.

If the converter needs to access the state of the parser, it can be
implemented as a method on a config parser subclass.  If the name of this
method starts with @code{get}, it will be available on all section proxies, in
the dict-compatible form (see the @code{getdecimal()} example above).
@end itemize

More advanced customization may be achieved by overriding default values of
these parser attributes.  The defaults are defined on the classes, so they may
be overridden by subclasses or by attribute assignment.

@geindex BOOLEAN_STATES (ιδιότητα της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser BOOLEAN_STATES}@anchor{31a2}
@deffn {Ιδιότητα} ConfigParser.BOOLEAN_STATES

By default when using @ref{3198,,getboolean()}, config parsers
consider the following values @code{True}: @code{'1'}, @code{'yes'}, @code{'true'},
@code{'on'} and the following values @code{False}: @code{'0'}, @code{'no'}, @code{'false'},
@code{'off'}.  You can override this by specifying a custom dictionary of strings
and their Boolean outcomes. For example:

@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 {Μέθοδος} 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 Σημείωση 
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 (ιδιότητα της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser SECTCRE}@anchor{319c}
@deffn {Ιδιότητα} 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 Σημείωση 
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,Customizing Parser Behaviour,configparser — Configuration file parser
@anchor{library/configparser legacy-api-examples}@anchor{31a3}
@subsubsection Legacy API Examples


Mainly because of backwards compatibility concerns, @code{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{6e4,,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{31a4}@anchor{library/configparser id13}@anchor{31a5}
@subsubsection ConfigParser Objects


@geindex ConfigParser (κλάση σε configparser)
@anchor{library/configparser configparser ConfigParser}@anchor{6e4}
@deffn {Κλάση} 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{1613,,DuplicateSectionError} or
@ref{1614,,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{319f,,dedicated documentation section}.

All option names used in interpolation will be passed through the
@ref{31a6,,optionxform()} method just like any other option name reference.  For
example, using the default implementation of @code{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{319e,,"Unnamed Sections" section}.

It is possible to read several configurations into a single
@code{ConfigParser}, where the most recently added configuration has the
highest priority. Any conflicting keys are taken from the more recent
configuration while the previously existing keys are retained. The example
below reads in an @code{override.ini} file, which will override any conflicting
keys from the @code{example.ini} file.

@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


Άλλαξε στην έκδοση 3.1: The default `dict_type' is @ref{9d5,,collections.OrderedDict}.



Άλλαξε στην έκδοση 3.2: `allow_no_value', `delimiters', `comment_prefixes', `strict',
`empty_lines_in_values', `default_section' and `interpolation' were
added.



Άλλαξε στην έκδοση 3.5: The `converters' argument was added.



Άλλαξε στην έκδοση 3.7: The `defaults' argument is read with @ref{31a0,,read_dict()},
providing consistent behavior across the parser: non-string
keys and values are implicitly converted to strings.



Άλλαξε στην έκδοση 3.8: The default `dict_type' is @ref{188,,dict}, since it now preserves
insertion order.



Άλλαξε στην έκδοση 3.13: Raise a @ref{31a7,,MultilineContinuationError} when `allow_no_value' is
@code{True}, and a key without a value is continued with an indented line.



Άλλαξε στην έκδοση 3.13: The `allow_unnamed_section' argument was added.


@geindex defaults() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser defaults}@anchor{31a8}
@deffn {Μέθοδος} defaults ()

Return a dictionary containing the instance-wide defaults.
@end deffn

@geindex sections() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser sections}@anchor{31a9}
@deffn {Μέθοδος} sections ()

Return a list of the sections available; the `default section' is not
included in the list.
@end deffn

@geindex add_section() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser add_section}@anchor{1612}
@deffn {Μέθοδος} add_section (section)

Add a section named `section' to the instance.  If a section by the given
name already exists, @ref{1613,,DuplicateSectionError} is raised.  If the
`default section' name is passed, @ref{277,,ValueError} is raised.  The name
of the section must be a string; if not, @ref{291,,TypeError} is raised.


Άλλαξε στην έκδοση 3.2: Non-string section names raise @ref{291,,TypeError}.

@end deffn

@geindex has_section() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser has_section}@anchor{31aa}
@deffn {Μέθοδος} has_section (section)

Indicates whether the named `section' is present in the configuration.
The `default section' is not acknowledged.
@end deffn

@geindex options() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser options}@anchor{31ab}
@deffn {Μέθοδος} options (section)

Return a list of options available in the specified `section'.
@end deffn

@geindex has_option() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser has_option}@anchor{31ac}
@deffn {Μέθοδος} has_option (section, option)

If the given `section' exists, and contains the given `option', return
@ref{fcc,,True}; otherwise return @ref{ef5,,False}.  If the specified
`section' is @ref{a65,,None} or an empty string, DEFAULT is assumed.
@end deffn

@geindex read() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser read}@anchor{180a}
@deffn {Μέθοδος} 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{1c7,,bytes} object or a
@ref{79f,,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 @code{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{915,,read_file()} before calling @code{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


Άλλαξε στην έκδοση 3.2: Added the `encoding' parameter.
Previously, all files were read using the default encoding for @ref{32b,,open()}.



Άλλαξε στην έκδοση 3.6.1: The `filenames' parameter accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.7: The `filenames' parameter accepts a @ref{1c7,,bytes} object.

@end deffn

@geindex read_file() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser read_file}@anchor{915}
@deffn {Μέθοδος} 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{'<???>'}.


Added in version 3.2: Replaces @code{readfp()}.

@end deffn

@geindex read_string() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser read_string}@anchor{31a1}
@deffn {Μέθοδος} 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.


Added in version 3.2.

@end deffn

@geindex read_dict() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser read_dict}@anchor{31a0}
@deffn {Μέθοδος} 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.


Added in version 3.2.

@end deffn

@geindex get() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser get}@anchor{1610}
@deffn {Μέθοδος} 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.


Άλλαξε στην έκδοση 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() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser getint}@anchor{3199}
@deffn {Μέθοδος} getint (section, option, *, raw=False, vars=None[, fallback])

A convenience method which coerces the `option' in the specified `section'
to an integer.  See @ref{1610,,get()} for explanation of `raw', `vars' and
`fallback'.
@end deffn

@geindex getfloat() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser getfloat}@anchor{319a}
@deffn {Μέθοδος} 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{1610,,get()} for explanation of `raw',
`vars' and `fallback'.
@end deffn

@geindex getboolean() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser getboolean}@anchor{3198}
@deffn {Μέθοδος} 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{277,,ValueError}.  See @ref{1610,,get()} for explanation of `raw', `vars' and
`fallback'.
@end deffn

@geindex items() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser items}@anchor{31ad}
@deffn {Μέθοδος} items (raw=False, vars=None)

@deffnx {Μέθοδος} 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{1610,,get()} method.


Άλλαξε στην έκδοση 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() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser set}@anchor{1611}
@deffn {Μέθοδος} set (section, option, value)

If the given section exists, set the given option to the specified value;
otherwise raise @ref{31ae,,NoSectionError}.  `option' and `value' must be
strings; if not, @ref{291,,TypeError} is raised.
@end deffn

@geindex write() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser write}@anchor{475}
@deffn {Μέθοδος} write (fileobject, space_around_delimiters=True)

Write a representation of the configuration to the specified @ref{156c,,file object}, which must be opened in text mode (accepting strings).  This
representation can be parsed by a future @ref{180a,,read()} call.  If
`space_around_delimiters' is true, delimiters between
keys and values are surrounded by spaces.


Άλλαξε στην έκδοση 3.14: Raises InvalidWriteError if this would write a representation which cannot
be accurately parsed by a future @ref{180a,,read()} call from this parser.

@end deffn

@cartouche
@quotation Σημείωση 
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() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser remove_option}@anchor{31af}
@deffn {Μέθοδος} remove_option (section, option)

Remove the specified `option' from the specified `section'.  If the
section does not exist, raise @ref{31ae,,NoSectionError}.  If the option
existed to be removed, return @ref{fcc,,True}; otherwise return
@ref{ef5,,False}.
@end deffn

@geindex remove_section() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser remove_section}@anchor{31b0}
@deffn {Μέθοδος} 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() (μέθοδος της configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser optionxform}@anchor{31a6}
@deffn {Μέθοδος} 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 @code{optionxform()} is called.
@end deffn
@end deffn

@geindex UNNAMED_SECTION (στη μονάδα configparser)
@anchor{library/configparser configparser UNNAMED_SECTION}@anchor{199c}
@deffn {Δεδομένα} configparser.UNNAMED_SECTION

A special object representing a section name used to reference the unnamed section (see @ref{319e,,Unnamed Sections}).
@end deffn

@geindex MAX_INTERPOLATION_DEPTH (στη μονάδα configparser)
@anchor{library/configparser configparser MAX_INTERPOLATION_DEPTH}@anchor{31b1}
@deffn {Δεδομένα} configparser.MAX_INTERPOLATION_DEPTH

The maximum depth for recursive interpolation for @ref{1610,,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{31b2}@anchor{library/configparser rawconfigparser-objects}@anchor{31b3}
@subsubsection RawConfigParser Objects


@geindex RawConfigParser (κλάση σε configparser)
@anchor{library/configparser configparser RawConfigParser}@anchor{130e}
@deffn {Κλάση} 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{6e4,,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.


Άλλαξε στην έκδοση 3.2: `allow_no_value', `delimiters', `comment_prefixes', `strict',
`empty_lines_in_values', `default_section' and `interpolation' were
added.



Άλλαξε στην έκδοση 3.5: The `converters' argument was added.



Άλλαξε στην έκδοση 3.8: The default `dict_type' is @ref{188,,dict}, since it now preserves
insertion order.



Άλλαξε στην έκδοση 3.13: The `allow_unnamed_section' argument was added.


@cartouche
@quotation Σημείωση 
Consider using @ref{6e4,,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() (μέθοδος της configparser.RawConfigParser)
@anchor{library/configparser configparser RawConfigParser add_section}@anchor{31b4}
@deffn {Μέθοδος} add_section (section)

Add a section named `section' or @ref{199c,,UNNAMED_SECTION} to the instance.

If the given section already exists, @ref{1613,,DuplicateSectionError} is
raised. If the `default section' name is passed, @ref{277,,ValueError} is
raised. If @ref{199c,,UNNAMED_SECTION} is passed and support is disabled,
@ref{31b5,,UnnamedSectionDisabledError} 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


Άλλαξε στην έκδοση 3.14: Added support for @ref{199c,,UNNAMED_SECTION}.


@geindex set() (μέθοδος της configparser.RawConfigParser)
@anchor{library/configparser configparser RawConfigParser set}@anchor{31b6}
@deffn {Μέθοδος} set (section, option, value)

If the given section exists, set the given option to the specified value;
otherwise raise @ref{31ae,,NoSectionError}.  While it is possible to use
@code{RawConfigParser} (or @ref{6e4,,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{31b7}
@subsubsection Exceptions


@geindex Error
@anchor{library/configparser configparser Error}@anchor{31b8}
@deffn {Εξαίρεση} configparser.Error

Base class for all other @code{configparser} exceptions.
@end deffn

@geindex NoSectionError
@anchor{library/configparser configparser NoSectionError}@anchor{31ae}
@deffn {Εξαίρεση} configparser.NoSectionError

Exception raised when a specified section is not found.
@end deffn

@geindex DuplicateSectionError
@anchor{library/configparser configparser DuplicateSectionError}@anchor{1613}
@deffn {Εξαίρεση} configparser.DuplicateSectionError

Exception raised if @ref{1612,,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.


Άλλαξε στην έκδοση 3.2: Added the optional `source' and `lineno' attributes and parameters to
@code{__init__()}.

@end deffn

@geindex DuplicateOptionError
@anchor{library/configparser configparser DuplicateOptionError}@anchor{1614}
@deffn {Εξαίρεση} 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{31b9}
@deffn {Εξαίρεση} 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{31ba}
@deffn {Εξαίρεση} configparser.InterpolationError

Base class for exceptions raised when problems occur performing string
interpolation.
@end deffn

@geindex InterpolationDepthError
@anchor{library/configparser configparser InterpolationDepthError}@anchor{31bb}
@deffn {Εξαίρεση} configparser.InterpolationDepthError

Exception raised when string interpolation cannot be completed because the
number of iterations exceeds @ref{31b1,,MAX_INTERPOLATION_DEPTH}.  Subclass of
@ref{31ba,,InterpolationError}.
@end deffn

@geindex InterpolationMissingOptionError
@anchor{library/configparser configparser InterpolationMissingOptionError}@anchor{31bc}
@deffn {Εξαίρεση} configparser.InterpolationMissingOptionError

Exception raised when an option referenced from a value does not exist.
Subclass of @ref{31ba,,InterpolationError}.
@end deffn

@geindex InterpolationSyntaxError
@anchor{library/configparser configparser InterpolationSyntaxError}@anchor{31bd}
@deffn {Εξαίρεση} configparser.InterpolationSyntaxError

Exception raised when the source text into which substitutions are made does
not conform to the required syntax.  Subclass of @ref{31ba,,InterpolationError}.
@end deffn

@geindex MissingSectionHeaderError
@anchor{library/configparser configparser MissingSectionHeaderError}@anchor{31be}
@deffn {Εξαίρεση} 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{914}
@deffn {Εξαίρεση} configparser.ParsingError

Exception raised when errors occur attempting to parse a file.


Άλλαξε στην έκδοση 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{31a7}
@deffn {Εξαίρεση} configparser.MultilineContinuationError

Exception raised when a key without a corresponding value is continued with
an indented line.


Added in version 3.13.

@end deffn

@geindex UnnamedSectionDisabledError
@anchor{library/configparser configparser UnnamedSectionDisabledError}@anchor{31b5}
@deffn {Εξαίρεση} configparser.UnnamedSectionDisabledError

Exception raised when attempting to use the
@ref{199c,,UNNAMED_SECTION} without enabling it.

@quotation


Added in version 3.14.

@end quotation
@end deffn

@geindex InvalidWriteError
@anchor{library/configparser configparser InvalidWriteError}@anchor{476}
@deffn {Εξαίρεση} configparser.InvalidWriteError

Exception raised when an attempted @ref{475,,ConfigParser.write()} would not be parsed
accurately with a future @ref{180a,,ConfigParser.read()} call.

Ex: Writing a key beginning with the @ref{319c,,ConfigParser.SECTCRE} pattern
would parse as a section header when read. Attempting to write this will raise
this exception.


Added in version 3.14.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tomllib — Parse TOML files,netrc — netrc file processing,configparser — Configuration file parser,File Formats
@anchor{library/tomllib doc}@anchor{31bf}@anchor{library/tomllib module-tomllib}@anchor{105}@anchor{library/tomllib tomllib-parse-toml-files}@anchor{31c0}@anchor{library/tomllib translation-repo}@anchor{31c1}
@subsection @code{tomllib} — Parse TOML files


@geindex module; tomllib

`Source code:' Lib/tomllib@footnote{https://github.com/python/cpython/tree/main/Lib/tomllib}


__________________________________________________________________


This module provides an interface for parsing TOML 1.1.0 (Tom’s Obvious Minimal
Language, https://toml.io@footnote{https://toml.io/en/}). This module does not
support writing TOML.


Added in version 3.11: The module was added with support for TOML 1.0.0.



Άλλαξε στην έκδοση 3.15: Added TOML 1.1.0 support.
See the @ref{288,,What’s New} for details.


@cartouche
@quotation Προειδοποίηση 
Be cautious when parsing data from untrusted sources.
A malicious TOML 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


@subsubheading Δείτε επίσης


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{90,,marshal} and @ref{ab,,pickle} modules.



@subsubheading Δείτε επίσης


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.


This module defines the following functions:

@geindex load() (στη μονάδα tomllib)
@anchor{library/tomllib tomllib load}@anchor{31c2}
@deffn {Συνάρτηση} tomllib.load (fp, /, *, parse_float=float)

Read a TOML file. The first argument should be a readable and binary file object.
Return a @ref{188,,dict}. Convert TOML types to Python using this
@ref{31c3,,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{1c2,,decimal.Decimal}). The callable must not return a
@ref{188,,dict} or a @ref{4d9,,list}, else a @ref{277,,ValueError} is raised.

A @ref{1b29,,TOMLDecodeError} will be raised on an invalid TOML document.
@end deffn

@geindex loads() (στη μονάδα tomllib)
@anchor{library/tomllib tomllib loads}@anchor{1b47}
@deffn {Συνάρτηση} tomllib.loads (s, /, *, parse_float=float)

Load TOML from a @ref{1df,,str} object. Return a @ref{188,,dict}. Convert TOML
types to Python using this @ref{31c3,,conversion table}. The
`parse_float' argument has the same meaning as in @ref{31c2,,load()}.

A @ref{1b29,,TOMLDecodeError} will be raised on an invalid TOML document.
@end deffn

The following exceptions are available:

@geindex TOMLDecodeError
@anchor{library/tomllib tomllib TOMLDecodeError}@anchor{1b29}
@deffn {Εξαίρεση} tomllib.TOMLDecodeError (msg, doc, pos)

Subclass of @ref{277,,ValueError} with the following additional attributes:

@geindex msg (ιδιότητα της tomllib.TOMLDecodeError)
@anchor{library/tomllib tomllib TOMLDecodeError msg}@anchor{31c4}
@deffn {Ιδιότητα} msg

The unformatted error message.
@end deffn

@geindex doc (ιδιότητα της tomllib.TOMLDecodeError)
@anchor{library/tomllib tomllib TOMLDecodeError doc}@anchor{31c5}
@deffn {Ιδιότητα} doc

The TOML document being parsed.
@end deffn

@geindex pos (ιδιότητα της tomllib.TOMLDecodeError)
@anchor{library/tomllib tomllib TOMLDecodeError pos}@anchor{31c6}
@deffn {Ιδιότητα} pos

The index of `doc' where parsing failed.
@end deffn

@geindex lineno (ιδιότητα της tomllib.TOMLDecodeError)
@anchor{library/tomllib tomllib TOMLDecodeError lineno}@anchor{31c7}
@deffn {Ιδιότητα} lineno

The line corresponding to `pos'.
@end deffn

@geindex colno (ιδιότητα της tomllib.TOMLDecodeError)
@anchor{library/tomllib tomllib TOMLDecodeError colno}@anchor{31c8}
@deffn {Ιδιότητα} colno

The column corresponding to `pos'.
@end deffn


Άλλαξε στην έκδοση 3.14: Added the `msg', `doc' and `pos' parameters.
Added the @ref{31c4,,msg}, @ref{31c5,,doc}, @ref{31c6,,pos}, @ref{31c7,,lineno} and @ref{31c8,,colno} attributes.



Αποσύρθηκε στην έκδοση 3.14: Passing free-form positional arguments is deprecated.

@end deffn

@menu
* Examples: Examples<9>. 
* Conversion Table:: 

@end menu

@node Examples<9>,Conversion Table,,tomllib — Parse TOML files
@anchor{library/tomllib examples}@anchor{31c9}
@subsubsection Examples


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,,Examples<9>,tomllib — Parse TOML files
@anchor{library/tomllib conversion-table}@anchor{31ca}
@subsubsection Conversion Table

@anchor{library/tomllib toml-to-py-table}@anchor{31c3}

@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

TOML

@tab

Python

@item

TOML document

@tab

dict

@item

string

@tab

str

@item

integer

@tab

int

@item

float

@tab

float (configurable with `parse_float')

@item

boolean

@tab

bool

@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

list

@item

table

@tab

dict

@item

inline table

@tab

dict

@item

array of tables

@tab

list of dicts

@end multitable


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node netrc — netrc file processing,plistlib — Generate and parse Apple plist files,tomllib — Parse TOML files,File Formats
@anchor{library/netrc doc}@anchor{31cb}@anchor{library/netrc module-netrc}@anchor{9f}@anchor{library/netrc netrc-netrc-file-processing}@anchor{31cc}@anchor{library/netrc translation-repo}@anchor{31cd}
@subsection @code{netrc} — netrc file processing


@geindex module; netrc

`Source code:' Lib/netrc.py@footnote{https://github.com/python/cpython/tree/main/Lib/netrc.py}


__________________________________________________________________


The @ref{1e70,,netrc} class parses and encapsulates the netrc file format used by
the Unix @code{ftp} program and other FTP clients.

@geindex netrc (κλάση σε netrc)
@anchor{library/netrc netrc netrc}@anchor{1e70}
@deffn {Κλάση} netrc.netrc ([file])

A @ref{1e70,,netrc} instance or subclass instance encapsulates data from  a netrc
file.  The initialization argument, if present, specifies the file to parse.  If
no argument is given, the file @code{.netrc} in the user’s home directory –
as determined by @ref{dd8,,os.path.expanduser()} – will be read.  Otherwise,
a @ref{243,,FileNotFoundError} exception will be raised.
Parse errors will raise @ref{31ce,,NetrcParseError} with diagnostic
information including the file name, line number, and terminating token.

If no argument is specified on a POSIX system, the presence of passwords in
the @code{.netrc} file will raise a @ref{31ce,,NetrcParseError} if the file
ownership or permissions are insecure (owned by a user other than the user
running the process, or accessible for read or write by any other user).
This implements security behavior equivalent to that of ftp and other
programs that use @code{.netrc}. Such security checks are not available
on platforms that do not support @ref{1a11,,os.getuid()}.


Άλλαξε στην έκδοση 3.4: Added the POSIX permission check.



Άλλαξε στην έκδοση 3.7: @ref{dd8,,os.path.expanduser()} is used to find the location of the
@code{.netrc} file when `file' is not passed as argument.



Άλλαξε στην έκδοση 3.10: @code{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{31ce}
@deffn {Εξαίρεση} netrc.NetrcParseError

Exception raised by the @ref{1e70,,netrc} class when syntactical errors are
encountered in source text.  Instances of this exception provide three
interesting attributes:

@geindex msg (ιδιότητα της netrc.NetrcParseError)
@anchor{library/netrc netrc NetrcParseError msg}@anchor{31cf}
@deffn {Ιδιότητα} msg

Textual explanation of the error.
@end deffn

@geindex filename (ιδιότητα της netrc.NetrcParseError)
@anchor{library/netrc netrc NetrcParseError filename}@anchor{31d0}
@deffn {Ιδιότητα} filename

The name of the source file.
@end deffn

@geindex lineno (ιδιότητα της netrc.NetrcParseError)
@anchor{library/netrc netrc NetrcParseError lineno}@anchor{31d1}
@deffn {Ιδιότητα} lineno

The line number on which the error was found.
@end deffn
@end deffn

@menu
* netrc Objects:: 

@end menu

@node netrc Objects,,,netrc — netrc file processing
@anchor{library/netrc id1}@anchor{31d2}@anchor{library/netrc netrc-objects}@anchor{31d3}
@subsubsection netrc Objects


A @ref{1e70,,netrc} instance has the following methods:

@geindex authenticators() (μέθοδος της netrc.netrc)
@anchor{library/netrc netrc netrc authenticators}@anchor{31d4}
@deffn {Μέθοδος} netrc.authenticators (host)

Return a 3-tuple @code{(login, account, password)} of authenticators for `host'.
If the netrc file did not contain an entry for the given host, return the tuple
associated with the “default” entry.  If neither matching host nor default entry
is available, return @code{None}.
@end deffn

@geindex __repr__() (μέθοδος της netrc.netrc)
@anchor{library/netrc netrc netrc __repr__}@anchor{31d5}
@deffn {Μέθοδος} netrc.__repr__ ()

Dump the class data as a string in the format of a netrc file. (This discards
comments and may reorder the entries.)
@end deffn

Instances of @ref{1e70,,netrc} have public instance variables:

@geindex hosts (ιδιότητα της netrc.netrc)
@anchor{library/netrc netrc netrc hosts}@anchor{31d6}
@deffn {Ιδιότητα} netrc.hosts

Dictionary mapping host names to @code{(login, account, password)} tuples.  The
“default” entry, if any, is represented as a pseudo-host by that name.
@end deffn

@geindex macros (ιδιότητα της netrc.netrc)
@anchor{library/netrc netrc netrc macros}@anchor{31d7}
@deffn {Ιδιότητα} netrc.macros

Dictionary mapping macro names to string lists.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node plistlib — Generate and parse Apple plist files,,netrc — netrc file processing,File Formats
@anchor{library/plistlib doc}@anchor{31d8}@anchor{library/plistlib module-plistlib}@anchor{b0}@anchor{library/plistlib plistlib-generate-and-parse-apple-plist-files}@anchor{31d9}@anchor{library/plistlib translation-repo}@anchor{31da}
@subsection @code{plistlib} — Generate and parse Apple @code{.plist} files


@geindex module; plistlib

`Source code:' Lib/plistlib.py@footnote{https://github.com/python/cpython/tree/main/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 or a frozen dictionary.

To write out and to parse a plist file, use the @ref{d1c,,dump()} and
@ref{d1a,,load()} functions.

To work with plist data in bytes or string objects, use @ref{d1d,,dumps()}
and @ref{d1b,,loads()}.

Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
(but only with string keys), @ref{1c7,,bytes}, @ref{1c6,,bytearray}
or @ref{6e7,,datetime.datetime} objects.


Άλλαξε στην έκδοση 3.4: New API, old API deprecated.  Support for binary format plists added.



Άλλαξε στην έκδοση 3.8: Support added for reading and writing @ref{de5,,UID} tokens in binary plists as used
by NSKeyedArchiver and NSKeyedUnarchiver.



Άλλαξε στην έκδοση 3.9: Old API removed.



@subsubheading Δείτε επίσης



@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


This module defines the following functions:

@geindex load() (στη μονάδα plistlib)
@anchor{library/plistlib plistlib load}@anchor{d1a}
@deffn {Συνάρτηση} 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{a65,,None}: Autodetect the file format

@item 
@ref{1323,,FMT_XML}: XML file format

@item 
@ref{1324,,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{2aac,,aware object}, with
@code{tzinfo} as @ref{8fc,,datetime.UTC}.

XML data for the @ref{1323,,FMT_XML} format is parsed using the Expat parser
from @ref{12f,,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 raises @ref{1eef,,InvalidFileException} when the file cannot be parsed.


Added in version 3.4.



Άλλαξε στην έκδοση 3.13: The keyword-only parameter `aware_datetime' has been added.

@end deffn

@geindex loads() (στη μονάδα plistlib)
@anchor{library/plistlib plistlib loads}@anchor{d1b}
@deffn {Συνάρτηση} plistlib.loads (data, *, fmt=None, dict_type=dict, aware_datetime=False)

Load a plist from a bytes or string object. See @ref{d1a,,load()} for an
explanation of the keyword arguments.


Added in version 3.4.



Άλλαξε στην έκδοση 3.13: `data' can be a string when `fmt' equals @ref{1323,,FMT_XML}.

@end deffn

@geindex dump() (στη μονάδα plistlib)
@anchor{library/plistlib plistlib dump}@anchor{d1c}
@deffn {Συνάρτηση} 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{1323,,FMT_XML}: XML formatted plist file

@item 
@ref{1324,,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{291,,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{2aac,,aware object}, it will convert to
UTC timezone before writing it.

A @ref{291,,TypeError} will be raised if the object is of an unsupported type or
a container that contains objects of unsupported types.

An @ref{c57,,OverflowError} will be raised for integer values that cannot
be represented in (binary) plist files.


Added in version 3.4.



Άλλαξε στην έκδοση 3.13: The keyword-only parameter `aware_datetime' has been added.

@end deffn

@geindex dumps() (στη μονάδα plistlib)
@anchor{library/plistlib plistlib dumps}@anchor{d1d}
@deffn {Συνάρτηση} 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{d1c,,dump()} for an explanation of the keyword
arguments of this function.


Added in version 3.4.

@end deffn

The following classes are available:

@geindex UID (κλάση σε plistlib)
@anchor{library/plistlib plistlib UID}@anchor{de5}
@deffn {Κλάση} plistlib.UID (data)

Wraps an @ref{326,,int}.  This is used when reading or writing NSKeyedArchiver
encoded data, which contains UID (see PList manual).

@geindex data (ιδιότητα της plistlib.UID)
@anchor{library/plistlib plistlib UID data}@anchor{31db}
@deffn {Ιδιότητα} data

Int value of the UID.  It must be in the range @code{0 <= data < 2**64}.
@end deffn


Added in version 3.8.

@end deffn

The following constants are available:

@geindex FMT_XML (στη μονάδα plistlib)
@anchor{library/plistlib plistlib FMT_XML}@anchor{1323}
@deffn {Δεδομένα} plistlib.FMT_XML

The XML format for plist files.


Added in version 3.4.

@end deffn

@geindex FMT_BINARY (στη μονάδα plistlib)
@anchor{library/plistlib plistlib FMT_BINARY}@anchor{1324}
@deffn {Δεδομένα} plistlib.FMT_BINARY

The binary format for plist files


Added in version 3.4.

@end deffn

The module defines the following exceptions:

@geindex InvalidFileException
@anchor{library/plistlib plistlib InvalidFileException}@anchor{1eef}
@deffn {Εξαίρεση} plistlib.InvalidFileException

Raised when a file cannot be parsed.


Added in version 3.4.

@end deffn

@menu
* Examples: Examples<10>. 

@end menu

@node Examples<10>,,,plistlib — Generate and parse Apple plist files
@anchor{library/plistlib examples}@anchor{31dc}
@subsubsection Examples


Generating a plist:

@example
import datetime as dt
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 = dt.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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Cryptographic Services,Generic Operating System Services,File Formats,The Python Standard Library
@anchor{library/crypto doc}@anchor{31dd}@anchor{library/crypto crypto}@anchor{31de}@anchor{library/crypto cryptographic-services}@anchor{31df}@anchor{library/crypto translation-repo}@anchor{31e0}
@section Cryptographic Services


@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 — Secure hashes and message digests:: 
* hmac — Keyed-Hashing for Message Authentication:: 
* secrets — Generate secure random numbers for managing secrets:: 

@end menu

@node hashlib — Secure hashes and message digests,hmac — Keyed-Hashing for Message Authentication,,Cryptographic Services
@anchor{library/hashlib doc}@anchor{31e1}@anchor{library/hashlib hashlib-secure-hashes-and-message-digests}@anchor{31e2}@anchor{library/hashlib module-hashlib}@anchor{6b}
@subsection @code{hashlib} — Secure hashes and message digests


@geindex module; hashlib

`Source code:' Lib/hashlib.py@footnote{https://github.com/python/cpython/tree/main/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


__________________________________________________________________


This module implements a common interface to many different hash algorithms.
Included are the FIPS secure hash algorithms SHA224, SHA256, SHA384, SHA512,
(defined in the FIPS 180-4 standard@footnote{https://csrc.nist.gov/pubs/fips/180-4/upd1/final}), the SHA-3 series (defined in the FIPS 202 standard@footnote{https://csrc.nist.gov/pubs/fips/202/final}) as well as the legacy algorithms SHA1 (formerly part of FIPS@footnote{https://csrc.nist.gov/news/2023/decision-to-revise-fips-180-4})
and the MD5 algorithm (defined in internet 
@geindex RFC; RFC 1321
RFC 1321@footnote{https://datatracker.ietf.org/doc/html/rfc1321.html}).

@cartouche
@quotation Σημείωση 
If you want the adler32 or crc32 hash functions, they are available in
the @ref{13c,,zlib} module.
@end quotation
@end cartouche

@menu
* Hash algorithms:: 
* Usage:: 
* Constructors:: 
* Attributes:: 
* Hash Objects:: 
* SHAKE variable length digests:: 
* File hashing:: 
* Key derivation:: 
* BLAKE2:: 

@end menu

@node Hash algorithms,Usage,,hashlib — Secure hashes and message digests
@anchor{library/hashlib hash-algorithms}@anchor{31e3}@anchor{library/hashlib id1}@anchor{31e4}
@subsubsection Hash algorithms


There is one constructor method named for each type of `hash'.  All return
a hash object with the same simple interface. For example: use @ref{2f3,,sha256()}
to create a SHA-256 hash object. You can now feed this object with
@ref{436,,bytes-like objects} (normally @ref{1c7,,bytes}) using
the @ref{31e5,,update} method.  At any point you can ask it for the
`digest' of the concatenation of the data fed to it so far using the
@ref{31e6,,digest()} or @ref{31e7,,hexdigest()} methods.

To allow multithreading, the Python @ref{411,,GIL} is released while computing a
hash supplied more than 2047 bytes of data at once in its constructor or
@ref{31e5,,.update} method.

@geindex OpenSSL;(use in module hashlib)

Constructors for hash algorithms that are always present in this module are
@ref{31e8,,sha1()}, @ref{31e9,,sha224()}, @ref{2f3,,sha256()}, @ref{31ea,,sha384()}, @ref{31eb,,sha512()},
@ref{1063,,sha3_224()}, @ref{1064,,sha3_256()}, @ref{1065,,sha3_384()}, @ref{1066,,sha3_512()},
@ref{1067,,shake_128()}, @ref{1068,,shake_256()}, @ref{a31,,blake2b()}, and @ref{a32,,blake2s()}.
@ref{2f2,,md5()} is normally available as well, though it may be missing or blocked
if you are using a rare «FIPS compliant» build of Python.
These correspond to @ref{1718,,algorithms_guaranteed}.

Additional algorithms may also be available if your Python distribution’s
@code{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{2f1,,new()}.  See @ref{1719,,algorithms_available}.

@cartouche
@quotation Προειδοποίηση 
Some algorithms have known hash collision weaknesses (including MD5 and
SHA1). Refer to Attacks on cryptographic hash algorithms@footnote{https://en.wikipedia.org/wiki/Cryptographic_hash_function#Attacks_on_cryptographic_hash_algorithms} and the
@ref{31ec,,hashlib-seealso} section at the end of this document.
@end quotation
@end cartouche


Added in version 3.6: SHA3 (Keccak) and SHAKE constructors @ref{1063,,sha3_224()}, @ref{1064,,sha3_256()},
@ref{1065,,sha3_384()}, @ref{1066,,sha3_512()}, @ref{1067,,shake_128()}, @ref{1068,,shake_256()}
were added.
@ref{a31,,blake2b()} and @ref{a32,,blake2s()} were added.

@anchor{library/hashlib hashlib-usedforsecurity}@anchor{31ed}

Άλλαξε στην έκδοση 3.9: All hashlib constructors take a keyword-only argument `usedforsecurity'
with default value @code{True}. A false value allows the use of insecure and
blocked hashing algorithms in restricted environments. @code{False} indicates
that the hashing algorithm is not used in a security context, e.g. as a
non-cryptographic one-way compression function.



Άλλαξε στην έκδοση 3.9: Hashlib now uses SHA3 and SHAKE from OpenSSL if it provides it.



Άλλαξε στην έκδοση 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}.



Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.19: The undocumented @code{string} keyword parameter in @code{_hashlib.new()}
and hash-named constructors such as @code{_md5.md5()} is deprecated.
Prefer passing the initial data as a positional argument for maximum
backwards compatibility.


@node Usage,Constructors,Hash algorithms,hashlib — Secure hashes and message digests
@anchor{library/hashlib usage}@anchor{31ee}
@subsubsection Usage


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

More condensed:

@example
>>> hashlib.sha256(b"Nobody inspects the spammish repetition").hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'
@end example

@node Constructors,Attributes,Usage,hashlib — Secure hashes and message digests
@anchor{library/hashlib constructors}@anchor{31ef}
@subsubsection Constructors


@geindex new() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib new}@anchor{2f1}
@deffn {Συνάρτηση} 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{2f1,,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() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib md5}@anchor{2f2}
@deffn {Συνάρτηση} hashlib.md5 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha1() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib sha1}@anchor{31e8}
@deffn {Συνάρτηση} hashlib.sha1 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha224() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib sha224}@anchor{31e9}
@deffn {Συνάρτηση} hashlib.sha224 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha256() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib sha256}@anchor{2f3}
@deffn {Συνάρτηση} hashlib.sha256 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha384() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib sha384}@anchor{31ea}
@deffn {Συνάρτηση} hashlib.sha384 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha512() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib sha512}@anchor{31eb}
@deffn {Συνάρτηση} hashlib.sha512 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha3_224() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib sha3_224}@anchor{1063}
@deffn {Συνάρτηση} hashlib.sha3_224 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha3_256() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib sha3_256}@anchor{1064}
@deffn {Συνάρτηση} hashlib.sha3_256 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha3_384() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib sha3_384}@anchor{1065}
@deffn {Συνάρτηση} hashlib.sha3_384 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha3_512() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib sha3_512}@anchor{1066}
@deffn {Συνάρτηση} hashlib.sha3_512 ([data], *, usedforsecurity=True)
@end deffn

Named constructors such as these are faster than passing an algorithm name to
@ref{2f1,,new()}.

@node Attributes,Hash Objects,Constructors,hashlib — Secure hashes and message digests
@anchor{library/hashlib attributes}@anchor{31f0}
@subsubsection Attributes


Hashlib provides the following constant module attributes:

@geindex algorithms_guaranteed (στη μονάδα hashlib)
@anchor{library/hashlib hashlib algorithms_guaranteed}@anchor{1718}
@deffn {Δεδομένα} hashlib.algorithms_guaranteed

A set containing the names of the hash algorithms guaranteed to be supported
by this module on all platforms.  Note that “md5” is in this list despite
some upstream vendors offering an odd «FIPS compliant» Python build that
excludes it.


Added in version 3.2.

@end deffn

@geindex algorithms_available (στη μονάδα hashlib)
@anchor{library/hashlib hashlib algorithms_available}@anchor{1719}
@deffn {Δεδομένα} hashlib.algorithms_available

A set containing the names of the hash algorithms that are available in the
running Python interpreter.  These names will be recognized when passed to
@ref{2f1,,new()}.  @ref{1718,,algorithms_guaranteed} will always be a subset.  The
same algorithm may appear multiple times in this set under different names
(thanks to OpenSSL).


Added in version 3.2.

@end deffn

@node Hash Objects,SHAKE variable length digests,Attributes,hashlib — Secure hashes and message digests
@anchor{library/hashlib hash-objects}@anchor{31f1}
@subsubsection Hash Objects


The following values are provided as constant attributes of the hash objects
returned by the constructors:

@geindex hash.digest_size (στη μονάδα hashlib)
@anchor{library/hashlib hashlib hash digest_size}@anchor{31f2}
@deffn {Δεδομένα} hash.digest_size

The size of the resulting hash in bytes.
@end deffn

@geindex hash.block_size (στη μονάδα hashlib)
@anchor{library/hashlib hashlib hash block_size}@anchor{31f3}
@deffn {Δεδομένα} hash.block_size

The internal block size of the hash algorithm in bytes.
@end deffn

A hash object has the following attributes:

@geindex name (ιδιότητα της hashlib.hash)
@anchor{library/hashlib hashlib hash name}@anchor{12f2}
@deffn {Ιδιότητα} hash.name

The canonical name of this hash, always lowercase and always suitable as a
parameter to @ref{2f1,,new()} to create another hash of this type.


Άλλαξε στην έκδοση 3.4: The name attribute has been present in CPython since its inception, but
until Python 3.4 was not formally specified, so may not exist on some
platforms.

@end deffn

A hash object has the following methods:

@geindex update() (μέθοδος της hashlib.hash)
@anchor{library/hashlib hashlib hash update}@anchor{31e5}
@deffn {Μέθοδος} hash.update (data)

Update the hash object with the @ref{436,,bytes-like object}.
Repeated calls are equivalent to a single call with the
concatenation of all the arguments: @code{m.update(a); m.update(b)} is
equivalent to @code{m.update(a+b)}.
@end deffn

@geindex digest() (μέθοδος της hashlib.hash)
@anchor{library/hashlib hashlib hash digest}@anchor{31e6}
@deffn {Μέθοδος} hash.digest ()

Return the digest of the data passed to the @ref{31e5,,update()} method so far.
This is a bytes object of size @ref{31f2,,digest_size} which may contain bytes in
the whole range from 0 to 255.
@end deffn

@geindex hexdigest() (μέθοδος της hashlib.hash)
@anchor{library/hashlib hashlib hash hexdigest}@anchor{31e7}
@deffn {Μέθοδος} hash.hexdigest ()

Like @ref{31e6,,digest()} except the digest is returned as a string object of
double length, containing only hexadecimal digits.  This may be used to
exchange the value safely in email or other non-binary environments.
@end deffn

@geindex copy() (μέθοδος της hashlib.hash)
@anchor{library/hashlib hashlib hash copy}@anchor{31f4}
@deffn {Μέθοδος} hash.copy ()

Return a copy («clone») of the hash object.  This can be used to efficiently
compute the digests of data sharing a common initial substring.
@end deffn

@node SHAKE variable length digests,File hashing,Hash Objects,hashlib — Secure hashes and message digests
@anchor{library/hashlib shake-variable-length-digests}@anchor{31f5}
@subsubsection SHAKE variable length digests


@geindex shake_128() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib shake_128}@anchor{1067}
@deffn {Συνάρτηση} hashlib.shake_128 ([data], *, usedforsecurity=True)
@end deffn

@geindex shake_256() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib shake_256}@anchor{1068}
@deffn {Συνάρτηση} hashlib.shake_256 ([data], *, usedforsecurity=True)
@end deffn

The @ref{1067,,shake_128()} and @ref{1068,,shake_256()} algorithms provide variable
length digests with length_in_bits//2 up to 128 or 256 bits of security.
As such, their digest methods require a length. Maximum length is not limited
by the SHAKE algorithm.

@geindex digest() (μέθοδος της hashlib.shake)
@anchor{library/hashlib hashlib shake digest}@anchor{2008}
@deffn {Μέθοδος} shake.digest (length)

Return the digest of the data passed to the @ref{31e5,,update()} method so far.
This is a bytes object of size `length' which may contain bytes in
the whole range from 0 to 255.
@end deffn

@geindex hexdigest() (μέθοδος της hashlib.shake)
@anchor{library/hashlib hashlib shake hexdigest}@anchor{2009}
@deffn {Μέθοδος} shake.hexdigest (length)

Like @ref{2008,,digest()} except the digest is returned as a string object of
double length, containing only hexadecimal digits.  This may be used to
exchange the value in email or other non-binary environments.
@end deffn

Example use:

@example
>>> h = hashlib.shake_256(b'Nobody inspects the spammish repetition')
>>> h.hexdigest(20)
'44709d6fcb83d92a76dcb0b668c98e1b1d3dafe7'
@end example

@node File hashing,Key derivation,SHAKE variable length digests,hashlib — Secure hashes and message digests
@anchor{library/hashlib file-hashing}@anchor{31f6}
@subsubsection File hashing


The hashlib module provides a helper function for efficient hashing of
a file or file-like object.

@geindex file_digest() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib file_digest}@anchor{a33}
@deffn {Συνάρτηση} hashlib.file_digest (fileobj, digest, /)

Return a digest object that has been updated with contents of file object.

`fileobj' must be a file-like object opened for reading in binary mode.
It accepts file objects from  builtin @ref{32b,,open()}, @ref{1255,,BytesIO}
instances, SocketIO objects from @ref{1548,,socket.socket.makefile()}, and
similar. `fileobj' must be opened in blocking mode, otherwise a
@ref{4c3,,BlockingIOError} may be raised.

The function may bypass Python’s I/O and use the file descriptor
from @ref{19b2,,fileno()} directly. `fileobj' must be assumed to be
in an unknown state after this function returns or raises. It is up to
the caller to close `fileobj'.

`digest' must either be a hash algorithm name as a `str', a hash
constructor, or a callable that returns a hash object.

Example:

@example
>>> import io, hashlib, hmac
>>> with open("library/hashlib.rst", "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


Added in version 3.11.



Άλλαξε στην έκδοση 3.14: Now raises a @ref{4c3,,BlockingIOError} if the file is opened in non-blocking
mode. Previously, spurious null bytes were added to the digest.

@end deffn

@node Key derivation,BLAKE2,File hashing,hashlib — Secure hashes and message digests
@anchor{library/hashlib key-derivation}@anchor{31f7}
@subsubsection Key derivation


Key derivation and key stretching algorithms are designed for secure password
hashing. Naive algorithms such as @code{sha1(password)} are not resistant against
brute-force attacks. A good password hashing function must be tunable, slow, and
include a salt@footnote{https://en.wikipedia.org/wiki/Salt_%28cryptography%29}.

@geindex pbkdf2_hmac() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib pbkdf2_hmac}@anchor{91e}
@deffn {Συνάρτηση} hashlib.pbkdf2_hmac (hash_name, password, salt, iterations, dklen=None)

The function provides PKCS#5 password-based key derivation function 2. It
uses HMAC as pseudorandom function.

The string `hash_name' is the desired name of the hash digest algorithm for
HMAC, e.g. “sha1” or “sha256”. `password' and `salt' are interpreted as
buffers of bytes. Applications and libraries should limit `password' to
a sensible length (e.g. 1024). `salt' should be about 16 or more bytes from
a proper source, e.g. @ref{931,,os.urandom()}.

The number of `iterations' should be chosen based on the hash algorithm and
computing power. As of 2022, hundreds of thousands of iterations of SHA-256
are suggested. For rationale as to why and how to choose what is best for
your application, read `Appendix A.2.2' of NIST-SP-800-132@footnote{https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf}. The answers
on the stackexchange pbkdf2 iterations question@footnote{https://security.stackexchange.com/questions/3959/recommended-of-iterations-when-using-pbkdf2-sha256/} explain in detail.

`dklen' is the length of the derived key in bytes. If `dklen' is @code{None} then the
digest size of the hash algorithm `hash_name' is used, e.g. 64 for 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.


Added in version 3.4.



Άλλαξε στην έκδοση 3.12: Function now only available when Python is built with OpenSSL. The slow
pure Python implementation has been removed.

@end deffn

@geindex scrypt() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib scrypt}@anchor{ffc}
@deffn {Συνάρτηση} hashlib.scrypt (password, *, salt, n, r, p, maxmem=0, dklen=64)

The function provides scrypt password-based key derivation function as
defined in 
@geindex RFC; RFC 7914
RFC 7914@footnote{https://datatracker.ietf.org/doc/html/rfc7914.html}.

`password' and `salt' must be @ref{436,,bytes-like objects}.  Applications and libraries should limit `password'
to a sensible length (e.g. 1024).  `salt' should be about 16 or more
bytes from a proper source, e.g. @ref{931,,os.urandom()}.

`n' is the CPU/Memory cost factor, `r' the block size, `p' parallelization
factor and `maxmem' limits memory (OpenSSL 1.1.0 defaults to 32 MiB).
`dklen' is the length of the derived key in bytes.


Added in version 3.6.

@end deffn

@node BLAKE2,,Key derivation,hashlib — Secure hashes and message digests
@anchor{library/hashlib blake2}@anchor{31f8}@anchor{library/hashlib hashlib-blake2}@anchor{31f9}
@subsubsection BLAKE2


@geindex blake2b@comma{} blake2s

BLAKE2@footnote{https://www.blake2.net} is a cryptographic hash function defined in 
@geindex RFC; RFC 7693
RFC 7693@footnote{https://datatracker.ietf.org/doc/html/rfc7693.html} that comes in two
flavors:


@itemize *

@item 
`BLAKE2b', optimized for 64-bit platforms and produces digests of any size
between 1 and 64 bytes,

@item 
`BLAKE2s', optimized for 8- to 32-bit platforms and produces digests of any
size between 1 and 32 bytes.
@end itemize

BLAKE2 supports `keyed mode' (a faster and simpler replacement for HMAC@footnote{https://en.wikipedia.org/wiki/Hash-based_message_authentication_code}),
`salted hashing', `personalization', and `tree hashing'.

Hash objects from this module follow the API of standard library’s
@code{hashlib} objects.

@menu
* Creating hash objects:: 
* Constants: Constants<5>. 
* Examples: Examples<11>. 
* Credits:: 

@end menu

@node Creating hash objects,Constants<5>,,BLAKE2
@anchor{library/hashlib creating-hash-objects}@anchor{31fa}
@subsubsection Creating hash objects


New hash objects are created by calling constructor functions:

@geindex blake2b() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib blake2b}@anchor{a31}
@deffn {Συνάρτηση} 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() (στη μονάδα hashlib)
@anchor{library/hashlib hashlib blake2s}@anchor{a32}
@deffn {Συνάρτηση} 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

These functions return the corresponding hash objects for calculating
BLAKE2b or BLAKE2s. They optionally take these general parameters:


@itemize *

@item 
`data': initial chunk of data to hash, which must be
@ref{436,,bytes-like object}.  It can be passed only as positional argument.

@item 
`digest_size': size of output digest in bytes.

@item 
`key': key for keyed hashing (up to 64 bytes for BLAKE2b, up to 32 bytes for
BLAKE2s).

@item 
`salt': salt for randomized hashing (up to 16 bytes for BLAKE2b, up to 8
bytes for BLAKE2s).

@item 
`person': personalization string (up to 16 bytes for BLAKE2b, up to 8 bytes
for BLAKE2s).
@end itemize

The following table shows limits for general parameters (in bytes):


@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 Σημείωση 
BLAKE2 specification defines constant lengths for salt and personalization
parameters, however, for convenience, this implementation accepts byte
strings of any size up to the specified length. If the length of the
parameter is less than specified, it is padded with zeros, thus, for
example, @code{b'salt'} and @code{b'salt\x00'} is the same value. (This is not
the case for `key'.)
@end quotation
@end cartouche

These sizes are available as module @ref{31fb,,constants} described below.

Constructor functions also accept the following tree hashing parameters:


@itemize *

@item 
`fanout': fanout (0 to 255, 0 if unlimited, 1 in sequential mode).

@item 
`depth': maximal depth of tree (1 to 255, 255 if unlimited, 1 in
sequential mode).

@item 
`leaf_size': maximal byte length of leaf (0 to @code{2**32-1}, 0 if unlimited or in
sequential mode).

@item 
`node_offset': node offset (0 to @code{2**64-1} for BLAKE2b, 0 to @code{2**48-1} for
BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode).

@item 
`node_depth': node depth (0 to 255, 0 for leaves, or in sequential mode).

@item 
`inner_size': inner digest size (0 to 64 for BLAKE2b, 0 to 32 for
BLAKE2s, 0 in sequential mode).

@item 
`last_node': boolean indicating whether the processed node is the last
one (@code{False} for sequential mode).
@end itemize


@float Figure

@image{python-figures/hashlib-blake2-tree,,,Explanation of tree mode parameters.,png}

@end float


See section 2.10 in BLAKE2 specification@footnote{https://www.blake2.net/blake2_20130129.pdf} for comprehensive review of tree
hashing.

@node Constants<5>,Examples<11>,Creating hash objects,BLAKE2
@anchor{library/hashlib constants}@anchor{31fb}
@subsubsection Constants


@geindex blake2b.SALT_SIZE (στη μονάδα hashlib)
@anchor{library/hashlib hashlib blake2b SALT_SIZE}@anchor{31fc}
@deffn {Δεδομένα} blake2b.SALT_SIZE
@end deffn

@geindex blake2s.SALT_SIZE (στη μονάδα hashlib)
@anchor{library/hashlib hashlib blake2s SALT_SIZE}@anchor{31fd}
@deffn {Δεδομένα} blake2s.SALT_SIZE
@end deffn

Salt length (maximum length accepted by constructors).

@geindex blake2b.PERSON_SIZE (στη μονάδα hashlib)
@anchor{library/hashlib hashlib blake2b PERSON_SIZE}@anchor{31fe}
@deffn {Δεδομένα} blake2b.PERSON_SIZE
@end deffn

@geindex blake2s.PERSON_SIZE (στη μονάδα hashlib)
@anchor{library/hashlib hashlib blake2s PERSON_SIZE}@anchor{31ff}
@deffn {Δεδομένα} blake2s.PERSON_SIZE
@end deffn

Personalization string length (maximum length accepted by constructors).

@geindex blake2b.MAX_KEY_SIZE (στη μονάδα hashlib)
@anchor{library/hashlib hashlib blake2b MAX_KEY_SIZE}@anchor{3200}
@deffn {Δεδομένα} blake2b.MAX_KEY_SIZE
@end deffn

@geindex blake2s.MAX_KEY_SIZE (στη μονάδα hashlib)
@anchor{library/hashlib hashlib blake2s MAX_KEY_SIZE}@anchor{3201}
@deffn {Δεδομένα} blake2s.MAX_KEY_SIZE
@end deffn

Maximum key size.

@geindex blake2b.MAX_DIGEST_SIZE (στη μονάδα hashlib)
@anchor{library/hashlib hashlib blake2b MAX_DIGEST_SIZE}@anchor{3202}
@deffn {Δεδομένα} blake2b.MAX_DIGEST_SIZE
@end deffn

@geindex blake2s.MAX_DIGEST_SIZE (στη μονάδα hashlib)
@anchor{library/hashlib hashlib blake2s MAX_DIGEST_SIZE}@anchor{3203}
@deffn {Δεδομένα} blake2s.MAX_DIGEST_SIZE
@end deffn

Maximum digest size that the hash function can output.

@node Examples<11>,Credits,Constants<5>,BLAKE2
@anchor{library/hashlib examples}@anchor{3204}
@subsubsection Examples


@menu
* Simple hashing:: 
* Using different digest sizes:: 
* Keyed hashing:: 
* Randomized hashing:: 
* Personalization:: 
* Tree mode:: 

@end menu

@node Simple hashing,Using different digest sizes,,Examples<11>
@anchor{library/hashlib simple-hashing}@anchor{3205}
@subsubsection Simple hashing


To calculate hash of some data, you should first construct a hash object by
calling the appropriate constructor function (@ref{a31,,blake2b()} or
@ref{a32,,blake2s()}), then update it with the data by calling @ref{31e5,,update()} on the
object, and, finally, get the digest out of the object by calling
@ref{31e6,,digest()} (or @ref{31e7,,hexdigest()} for hex-encoded string).

@example
>>> from hashlib import blake2b
>>> h = blake2b()
>>> h.update(b'Hello world')
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
@end example

As a shortcut, you can pass the first chunk of data to update directly to the
constructor as the positional argument:

@example
>>> from hashlib import blake2b
>>> blake2b(b'Hello world').hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
@end example

You can call @ref{31e5,,hash.update()} as many times as you need to iteratively
update the hash:

@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 Using different digest sizes,Keyed hashing,Simple hashing,Examples<11>
@anchor{library/hashlib using-different-digest-sizes}@anchor{3206}
@subsubsection Using different digest sizes


BLAKE2 has configurable size of digests up to 64 bytes for BLAKE2b and up to 32
bytes for BLAKE2s. For example, to replace SHA-1 with BLAKE2b without changing
the size of output, we can tell BLAKE2b to produce 20-byte digests:

@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

Hash objects with different digest sizes have completely different outputs
(shorter hashes are `not' prefixes of longer hashes); BLAKE2b and BLAKE2s
produce different outputs even if the output length is the same:

@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 Keyed hashing,Randomized hashing,Using different digest sizes,Examples<11>
@anchor{library/hashlib keyed-hashing}@anchor{3207}
@subsubsection Keyed hashing


Keyed hashing can be used for authentication as a faster and simpler
replacement for Hash-based message authentication code@footnote{https://en.wikipedia.org/wiki/HMAC} (HMAC).
BLAKE2 can be securely used in prefix-MAC mode thanks to the
indifferentiability property inherited from BLAKE.

This example shows how to get a (hex-encoded) 128-bit authentication code for
message @code{b'message data'} with key @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

As a practical example, a web application can symmetrically sign cookies sent
to users and later verify them to make sure they weren’t tampered with:

@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

Even though there’s a native keyed hashing mode, BLAKE2 can, of course, be used
in HMAC construction with @ref{6d,,hmac} module:

@example
>>> import hmac, hashlib
>>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)
>>> m.update(b'message')
>>> m.hexdigest()
'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'
@end example

@node Randomized hashing,Personalization,Keyed hashing,Examples<11>
@anchor{library/hashlib randomized-hashing}@anchor{3208}
@subsubsection Randomized hashing


By setting `salt' parameter users can introduce randomization to the hash
function. Randomized hashing is useful for protecting against collision attacks
on the hash function used in digital signatures.

@quotation

Randomized hashing is designed for situations where one party, the message
preparer, generates all or part of a message to be signed by a second
party, the message signer. If the message preparer is able to find
cryptographic hash function collisions (i.e., two messages producing the
same hash value), then they might prepare meaningful versions of the message
that would produce the same hash value and digital signature, but with
different results (e.g., transferring $1,000,000 to an account, rather than
$10). Cryptographic hash functions have been designed with collision
resistance as a major goal, but the current concentration on attacking
cryptographic hash functions may result in a given cryptographic hash
function providing less collision resistance than expected. Randomized
hashing offers the signer additional protection by reducing the likelihood
that a preparer can generate two or more messages that ultimately yield the
same hash value during the digital signature generation process — even if
it is practical to find collisions for the hash function. However, the use
of randomized hashing may reduce the amount of security provided by a
digital signature when all portions of the message are prepared
by the signer.

(NIST SP-800-106 "Randomized Hashing for Digital Signatures"@footnote{https://csrc.nist.gov/pubs/sp/800/106/final})
@end quotation

In BLAKE2 the salt is processed as a one-time input to the hash function during
initialization, rather than as an input to each compression function.

@cartouche
@quotation Προειδοποίηση 
`Salted hashing' (or just hashing) with BLAKE2 or any other general-purpose
cryptographic hash function, such as SHA-256, is not suitable for hashing
passwords.  See BLAKE2 FAQ@footnote{https://www.blake2.net/#qa} for more
information.
@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 Personalization,Tree mode,Randomized hashing,Examples<11>
@anchor{library/hashlib personalization}@anchor{3209}
@subsubsection Personalization


Sometimes it is useful to force hash function to produce different digests for
the same input for different purposes. Quoting the authors of the Skein hash
function:

@quotation

We recommend that all application designers seriously consider doing this;
we have seen many protocols where a hash that is computed in one part of
the protocol can be used in an entirely different part because two hash
computations were done on similar or related data, and the attacker can
force the application to make the hash inputs the same. Personalizing each
hash function used in the protocol summarily stops this type of attack.

(The Skein Hash Function Family@footnote{https://www.schneier.com/wp-content/uploads/2016/02/skein.pdf},
p. 21)
@end quotation

BLAKE2 can be personalized by passing bytes to the `person' argument:

@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

Personalization together with the keyed mode can also be used to derive different
keys from a single one.

@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 Tree mode,,Personalization,Examples<11>
@anchor{library/hashlib tree-mode}@anchor{320a}
@subsubsection Tree mode


Here’s an example of hashing a minimal tree with two leaf nodes:

@example
  10
 /  \
00  01
@end example

This example uses 64-byte internal digests, and returns the 32-byte final
digest:

@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 Credits,,Examples<11>,BLAKE2
@anchor{library/hashlib credits}@anchor{320b}
@subsubsection Credits


BLAKE2@footnote{https://www.blake2.net} was designed by `Jean-Philippe Aumasson', `Samuel Neves', `Zooko
Wilcox-O’Hearn', and `Christian Winnerlein' based on SHA-3@footnote{https://en.wikipedia.org/wiki/Secure_Hash_Algorithms} finalist BLAKE@footnote{https://web.archive.org/web/20200918190133/https://131002.net/blake/}
created by `Jean-Philippe Aumasson', `Luca Henzen', `Willi Meier', and
`Raphael C.-W. Phan'.

It uses core algorithm from ChaCha@footnote{https://cr.yp.to/chacha.html} cipher designed by `Daniel J.  Bernstein'.

The stdlib implementation is based on pyblake2@footnote{https://pythonhosted.org/pyblake2/} module. It was written by
`Dmitry Chestnykh' based on C implementation written by `Samuel Neves'. The
documentation was copied from pyblake2@footnote{https://pythonhosted.org/pyblake2/} and written by `Dmitry Chestnykh'.

The C code was partly rewritten for Python by `Christian Heimes'.

The following public domain dedication applies for both C hash function
implementation, extension code, and this documentation:

@quotation

To the extent possible under law, the author(s) have dedicated all copyright
and related and neighboring rights to this software to the public domain
worldwide. This software is distributed without any warranty.

You should have received a copy of the CC0 Public Domain Dedication along
with this software. If not, see
@indicateurl{https://creativecommons.org/publicdomain/zero/1.0/}.
@end quotation

The following people have helped with development or contributed their changes
to the project and the public domain according to the Creative Commons Public
Domain Dedication 1.0 Universal:


@itemize *

@item 
`Alexandr Sokolovskiy'
@end itemize
@anchor{library/hashlib hashlib-seealso}@anchor{31ec}

@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{6d,,hmac}

A module to generate message authentication codes using hashes.

@item Module @ref{f,,base64}

Another way to encode binary hashes for non-binary environments.

@item @indicateurl{https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf}

The FIPS 180-4 publication on Secure Hash Algorithms.

@item @indicateurl{https://csrc.nist.gov/pubs/fips/202/final}

The FIPS 202 publication on the SHA-3 Standard.

@item @indicateurl{https://www.blake2.net/}

Official BLAKE2 website.

@item @indicateurl{https://en.wikipedia.org/wiki/Cryptographic_hash_function}

Wikipedia article with information on which algorithms have known issues
and what that means regarding their use.

@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}

NIST Recommendation for Password-Based Key Derivation.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node hmac — Keyed-Hashing for Message Authentication,secrets — Generate secure random numbers for managing secrets,hashlib — Secure hashes and message digests,Cryptographic Services
@anchor{library/hmac doc}@anchor{320c}@anchor{library/hmac hmac-keyed-hashing-for-message-authentication}@anchor{320d}@anchor{library/hmac module-hmac}@anchor{6d}@anchor{library/hmac translation-repo}@anchor{320e}
@subsection @code{hmac} — Keyed-Hashing for Message Authentication


@geindex module; hmac

`Source code:' Lib/hmac.py@footnote{https://github.com/python/cpython/tree/main/Lib/hmac.py}


__________________________________________________________________


This module implements the HMAC algorithm as described by 
@geindex RFC; RFC 2104
RFC 2104@footnote{https://datatracker.ietf.org/doc/html/rfc2104.html}.
The interface allows to use any hash function with a `fixed' digest size.
In particular, extendable output functions such as SHAKE-128 or SHAKE-256
cannot be used with HMAC.

@geindex new() (στη μονάδα hmac)
@anchor{library/hmac hmac new}@anchor{e65}
@deffn {Συνάρτηση} hmac.new (key, msg=None, digestmod)

Return a new hmac object.  `key' is a bytes or bytearray object giving the
secret key.  If `msg' is present, the method call @code{update(msg)} is made.
`digestmod' is the digest name, digest constructor or module for the HMAC
object to use.  It may be any name suitable to @ref{2f1,,hashlib.new()}.
Despite its argument position, it is required.


Άλλαξε στην έκδοση 3.4: Parameter `key' can be a bytes or bytearray object.
Parameter `msg' can be of any type supported by @ref{6b,,hashlib}.
Parameter `digestmod' can be the name of a hash algorithm.



Άλλαξε στην έκδοση 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() (στη μονάδα hmac)
@anchor{library/hmac hmac digest}@anchor{efc}
@deffn {Συνάρτηση} hmac.digest (key, msg, digest)

Return digest of `msg' for given secret `key' and `digest'. The
function is equivalent to @code{HMAC(key, msg, digest).digest()}, but
uses an optimized C or inline implementation, which is faster for messages
that fit into memory. The parameters `key', `msg', and `digest' have
the same meaning as in @ref{e65,,new()}.

CPython implementation detail, the optimized C implementation is only used
when `digest' is a string and name of a digest algorithm, which is
supported by OpenSSL.


Added in version 3.7.

@end deffn

@geindex HMAC (κλάση σε hmac)
@anchor{library/hmac hmac HMAC}@anchor{efd}
@deffn {Κλάση} hmac.HMAC

An HMAC object has the following methods:
@end deffn

@geindex update() (μέθοδος της hmac.HMAC)
@anchor{library/hmac hmac HMAC update}@anchor{12f4}
@deffn {Μέθοδος} HMAC.update (msg)

Update the hmac object with `msg'.  Repeated calls are equivalent to a
single call with the concatenation of all the arguments:
@code{m.update(a); m.update(b)} is equivalent to @code{m.update(a + b)}.


Άλλαξε στην έκδοση 3.4: Parameter `msg' can be of any type supported by @ref{6b,,hashlib}.

@end deffn

@geindex digest() (μέθοδος της hmac.HMAC)
@anchor{library/hmac hmac HMAC digest}@anchor{320f}
@deffn {Μέθοδος} HMAC.digest ()

Return the digest of the bytes passed to the @ref{12f4,,update()} method so far.
This bytes object will be the same length as the `digest_size' of the digest
given to the constructor.  It may contain non-ASCII bytes, including NUL
bytes.

@cartouche
@quotation Προειδοποίηση 
When comparing the output of @code{digest()} to an externally supplied
digest during a verification routine, it is recommended to use the
@ref{1476,,compare_digest()} function instead of the @code{==} operator
to reduce the vulnerability to timing attacks.
@end quotation
@end cartouche
@end deffn

@geindex hexdigest() (μέθοδος της hmac.HMAC)
@anchor{library/hmac hmac HMAC hexdigest}@anchor{3210}
@deffn {Μέθοδος} HMAC.hexdigest ()

Like @ref{efc,,digest()} except the digest is returned as a string twice the
length containing only hexadecimal digits.  This may be used to exchange the
value safely in email or other non-binary environments.

@cartouche
@quotation Προειδοποίηση 
When comparing the output of @code{hexdigest()} to an externally supplied
digest during a verification routine, it is recommended to use the
@ref{1476,,compare_digest()} function instead of the @code{==} operator
to reduce the vulnerability to timing attacks.
@end quotation
@end cartouche
@end deffn

@geindex copy() (μέθοδος της hmac.HMAC)
@anchor{library/hmac hmac HMAC copy}@anchor{19a7}
@deffn {Μέθοδος} HMAC.copy ()

Return a copy («clone») of the hmac object.  This can be used to efficiently
compute the digests of strings that share a common initial substring.
@end deffn

A hash object has the following attributes:

@geindex digest_size (ιδιότητα της hmac.HMAC)
@anchor{library/hmac hmac HMAC digest_size}@anchor{12f7}
@deffn {Ιδιότητα} HMAC.digest_size

The size of the resulting HMAC digest in bytes.
@end deffn

@geindex block_size (ιδιότητα της hmac.HMAC)
@anchor{library/hmac hmac HMAC block_size}@anchor{12f5}
@deffn {Ιδιότητα} HMAC.block_size

The internal block size of the hash algorithm in bytes.


Added in version 3.4.

@end deffn

@geindex name (ιδιότητα της hmac.HMAC)
@anchor{library/hmac hmac HMAC name}@anchor{12f6}
@deffn {Ιδιότητα} HMAC.name

The canonical name of this HMAC, always lowercase, e.g. @code{hmac-md5}.


Added in version 3.4.

@end deffn


Άλλαξε στην έκδοση 3.10: Removed the undocumented attributes @code{HMAC.digest_cons}, @code{HMAC.inner},
and @code{HMAC.outer}.


This module also provides the following helper function:

@geindex compare_digest() (στη μονάδα hmac)
@anchor{library/hmac hmac compare_digest}@anchor{1476}
@deffn {Συνάρτηση} hmac.compare_digest (a, b)

Return @code{a == b}.  This function uses an approach designed to prevent
timing analysis by avoiding content-based short circuiting behaviour,
making it appropriate for cryptography.  `a' and `b' must both be of the
same type: either @ref{1df,,str} (ASCII only, as e.g. returned by
@ref{3210,,HMAC.hexdigest()}), or a @ref{436,,bytes-like object}.

@cartouche
@quotation Σημείωση 
If `a' and `b' are of different lengths, or if an error occurs,
a timing attack could theoretically reveal information about the
types and lengths of `a' and `b'—but not their values.
@end quotation
@end cartouche


Added in version 3.3.



Άλλαξε στην έκδοση 3.10: The function uses OpenSSL’s @code{CRYPTO_memcmp()} internally when
available.

@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{6b,,hashlib}

The Python module providing secure hash functions.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node secrets — Generate secure random numbers for managing secrets,,hmac — Keyed-Hashing for Message Authentication,Cryptographic Services
@anchor{library/secrets doc}@anchor{3211}@anchor{library/secrets module-secrets}@anchor{c8}@anchor{library/secrets secrets-generate-secure-random-numbers-for-managing-secrets}@anchor{3212}@anchor{library/secrets translation-repo}@anchor{3213}
@subsection @code{secrets} — Generate secure random numbers for managing secrets


@geindex module; secrets


Added in version 3.6.


@c from secrets import *
@c __name__ = '<doctest>'

`Source code:' Lib/secrets.py@footnote{https://github.com/python/cpython/tree/main/Lib/secrets.py}


__________________________________________________________________


The @code{secrets} module is used for generating cryptographically strong
random numbers suitable for managing data such as passwords, account
authentication, security tokens, and related secrets.

In particular, @code{secrets} should be used in preference to the
default pseudo-random number generator in the @ref{c0,,random} module, which
is designed for modelling and simulation, not security or cryptography.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 506
PEP 506@footnote{https://peps.python.org/pep-0506/}


@menu
* Random numbers:: 
* Generating tokens:: 
* Other functions:: 
* Recipes and best practices:: 

@end menu

@node Random numbers,Generating tokens,,secrets — Generate secure random numbers for managing secrets
@anchor{library/secrets random-numbers}@anchor{3214}
@subsubsection Random numbers


The @code{secrets} module provides access to the most secure source of
randomness that your operating system provides.

@geindex SystemRandom (κλάση σε secrets)
@anchor{library/secrets secrets SystemRandom}@anchor{3215}
@deffn {Κλάση} secrets.SystemRandom

A class for generating random numbers using the highest-quality
sources provided by the operating system.  See
@ref{2d75,,random.SystemRandom} for additional details.
@end deffn

@geindex choice() (στη μονάδα secrets)
@anchor{library/secrets secrets choice}@anchor{3216}
@deffn {Συνάρτηση} secrets.choice (seq)

Return a randomly chosen element from a non-empty sequence.
@end deffn

@geindex randbelow() (στη μονάδα secrets)
@anchor{library/secrets secrets randbelow}@anchor{3217}
@deffn {Συνάρτηση} secrets.randbelow (exclusive_upper_bound)

Return a random int in the range [0, `exclusive_upper_bound').
@end deffn

@geindex randbits() (στη μονάδα secrets)
@anchor{library/secrets secrets randbits}@anchor{3218}
@deffn {Συνάρτηση} secrets.randbits (k)

Return a non-negative int with `k' random bits.
@end deffn

@node Generating tokens,Other functions,Random numbers,secrets — Generate secure random numbers for managing secrets
@anchor{library/secrets generating-tokens}@anchor{3219}
@subsubsection Generating tokens


The @code{secrets} module provides functions for generating secure
tokens, suitable for applications such as password resets,
hard-to-guess URLs, and similar.

@geindex token_bytes() (στη μονάδα secrets)
@anchor{library/secrets secrets token_bytes}@anchor{2d7a}
@deffn {Συνάρτηση} secrets.token_bytes (nbytes=None)

Return a random byte string containing `nbytes' number of bytes.

If `nbytes' is not specified or @code{None}, @ref{321a,,DEFAULT_ENTROPY}
is used instead.

@example
>>> token_bytes(16)
b'\xebr\x17D*t\xae\xd4\xe3S\xb6\xe2\xebP1\x8b'
@end example
@end deffn

@geindex token_hex() (στη μονάδα secrets)
@anchor{library/secrets secrets token_hex}@anchor{1d24}
@deffn {Συνάρτηση} secrets.token_hex (nbytes=None)

Return a random text string, in hexadecimal.  The string has `nbytes'
random bytes, each byte converted to two hex digits.

If `nbytes' is not specified or @code{None}, @ref{321a,,DEFAULT_ENTROPY}
is used instead.

@example
>>> token_hex(16)
'f9bf78b9a18ce6d46a0cd2b0b86df9da'
@end example
@end deffn

@geindex token_urlsafe() (στη μονάδα secrets)
@anchor{library/secrets secrets token_urlsafe}@anchor{321b}
@deffn {Συνάρτηση} secrets.token_urlsafe (nbytes=None)

Return a random URL-safe text string, containing `nbytes' random
bytes.  The text is Base64 encoded, so on average each byte results
in approximately 1.3 characters.

If `nbytes' is not specified or @code{None}, @ref{321a,,DEFAULT_ENTROPY}
is used instead.

@example
>>> token_urlsafe(16)
'Drmhze6EPcv0fN_81Bj-nA'
@end example
@end deffn

@menu
* How many bytes should tokens use?:: 

@end menu

@node How many bytes should tokens use?,,,Generating tokens
@anchor{library/secrets how-many-bytes-should-tokens-use}@anchor{321c}
@subsubsection How many bytes should tokens use?


To be secure against
brute-force attacks@footnote{https://en.wikipedia.org/wiki/Brute-force_attack},
tokens need to have sufficient randomness.  Unfortunately, what is
considered sufficient will necessarily increase as computers get more
powerful and able to make more guesses in a shorter period.  As of 2015,
it is believed that 32 bytes (256 bits) of randomness is sufficient for
the typical use-case expected for the @code{secrets} module.

For those who want to manage their own token length, you can explicitly
specify how much randomness is used for tokens by giving an @ref{326,,int}
argument to the various @code{token_*} functions.  That argument is taken
as the number of bytes of randomness to use.

Otherwise, if no argument is provided, or if the argument is @code{None},
the @code{token_*} functions use @ref{321a,,DEFAULT_ENTROPY} instead.

@geindex DEFAULT_ENTROPY (στη μονάδα secrets)
@anchor{library/secrets secrets DEFAULT_ENTROPY}@anchor{321a}
@deffn {Δεδομένα} secrets.DEFAULT_ENTROPY

Default number of bytes of randomness used by the @code{token_*} functions.

The exact value is subject to change at any time, including during
maintenance releases.
@end deffn

@node Other functions,Recipes and best practices,Generating tokens,secrets — Generate secure random numbers for managing secrets
@anchor{library/secrets other-functions}@anchor{321d}
@subsubsection Other functions


@geindex compare_digest() (στη μονάδα secrets)
@anchor{library/secrets secrets compare_digest}@anchor{321e}
@deffn {Συνάρτηση} secrets.compare_digest (a, b)

Return @code{True} if strings or
@ref{436,,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{1476,,hmac.compare_digest()} for additional details.
@end deffn

@node Recipes and best practices,,Other functions,secrets — Generate secure random numbers for managing secrets
@anchor{library/secrets recipes-and-best-practices}@anchor{321f}
@subsubsection Recipes and best practices


This section shows recipes and best practices for using @code{secrets}
to manage a basic level of security.

Generate an eight-character alphanumeric password:

@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 Σημείωση 
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

Generate a ten-character alphanumeric password with at least one
lowercase character, at least one uppercase character, and at least
three digits:

@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

Generate an XKCD-style passphrase@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

Generate a hard-to-guess temporary URL containing a security token
suitable for password recovery applications:

@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;

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Generic Operating System Services,Command-line interface libraries,Cryptographic Services,The Python Standard Library
@anchor{library/allos doc}@anchor{3220}@anchor{library/allos allos}@anchor{3221}@anchor{library/allos generic-operating-system-services}@anchor{3222}@anchor{library/allos translation-repo}@anchor{3223}
@section Generic Operating System Services


The modules described in this chapter provide interfaces to operating system
features that are available on (almost) all operating systems, such as files and
a clock.  The interfaces are generally modeled after the Unix or C interfaces,
but they are available on most other systems as well.  Here’s an overview:

@menu
* os — Miscellaneous operating system interfaces:: 
* io — Core tools for working with streams:: 
* time — Πρόσβαση και μετατροπές χρόνου:: 
* logging — Logging facility for Python:: 
* logging.config — Logging configuration: logging config — Logging configuration. 
* logging.handlers — Logging handlers: logging handlers — Logging handlers. 
* platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας:: 
* errno — Standard errno system symbols:: 
* ctypes — A foreign function library for Python:: 

@end menu

@node os — Miscellaneous operating system interfaces,io — Core tools for working with streams,,Generic Operating System Services
@anchor{library/os doc}@anchor{3224}@anchor{library/os module-os}@anchor{a5}@anchor{library/os os-miscellaneous-operating-system-interfaces}@anchor{3225}
@subsection @code{os} — Miscellaneous operating system interfaces


@geindex module; os

`Source code:' Lib/os.py@footnote{https://github.com/python/cpython/tree/main/Lib/os.py}


__________________________________________________________________


This module provides a portable way of using operating system dependent
functionality.  If you just want to read or write a file see @ref{32b,,open()}, if
you want to manipulate paths, see the @ref{a6,,os.path} module, and if you want to
read all the lines in all the files on the command line see the @ref{5e,,fileinput}
module.  For creating temporary files and directories see the @ref{e9,,tempfile}
module, and for high-level file and directory handling see the @ref{cd,,shutil}
module.

Notes on the availability of these functions:


@itemize *

@item 
The design of all built-in operating system dependent modules of Python is
such that as long as the same functionality is available, it uses the same
interface; for example, the function @code{os.stat(path)} returns stat
information about `path' in the same format (which happens to have originated
with the POSIX interface).

@item 
Extensions peculiar to a particular operating system are also available
through the @code{os} module, but using them is of course a threat to
portability.

@item 
All functions accepting path or file names accept both bytes and string
objects, and result in an object of the same type, if a path or file name is
returned.

@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 @code{os} module are
not available or behave differently. APIs related to processes (e.g.
@ref{6bd,,fork()}, @ref{14a5,,execve()}) and resources (e.g. @ref{14ad,,nice()})
are not available. Others like @ref{1a11,,getuid()} and @ref{3226,,getpid()} are
emulated or stubs. WebAssembly platforms also lack support for signals (e.g.
@ref{170c,,kill()}, @ref{1151,,wait()}).
@end itemize

@cartouche
@quotation Σημείωση 
All functions in this module raise @ref{53c,,OSError} (or subclasses thereof) in
the case of invalid or inaccessible file names and paths, or other arguments
that have the correct type, but are not accepted by the operating system.
@end quotation
@end cartouche

@geindex error
@anchor{library/os os error}@anchor{3227}
@deffn {Εξαίρεση} os.error

An alias for the built-in @ref{53c,,OSError} exception.
@end deffn

@geindex name (στη μονάδα os)
@anchor{library/os os name}@anchor{3228}
@deffn {Δεδομένα} os.name

The name of the operating system dependent module imported.  The following
names have currently been registered: @code{'posix'}, @code{'nt'},
@code{'java'}.


@subsubheading Δείτε επίσης


@ref{518,,sys.platform} has a finer granularity.  @ref{14c2,,os.uname()} gives
system-dependent version information.

The @ref{af,,platform} module provides detailed checks for the
system’s identity.

@end deffn
@anchor{library/os os-filenames}@anchor{316a}
@menu
* File Names@comma{} Command Line Arguments@comma{} and Environment Variables: File Names Command Line Arguments and Environment Variables. 
* Python UTF-8 Mode:: 
* Process Parameters:: 
* File Object Creation:: 
* File Descriptor Operations:: 
* Files and Directories:: 
* Process Management:: 
* Interface to the scheduler:: 
* Miscellaneous System Information:: 
* Random numbers: Random numbers<2>. 

@end menu

@node File Names Command Line Arguments and Environment Variables,Python UTF-8 Mode,,os — Miscellaneous operating system interfaces
@anchor{library/os file-names-command-line-arguments-and-environment-variables}@anchor{3229}@anchor{library/os filesystem-encoding}@anchor{2e50}
@subsubsection File Names, Command Line Arguments, and Environment Variables


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{948,,filesystem encoding and error handler} to perform this
conversion (see @ref{1017,,sys.getfilesystemencoding()}).

The @ref{948,,filesystem encoding and error handler} are configured at Python
startup by the @ref{b6f,,PyConfig_Read()} function: see
@ref{62e,,filesystem_encoding} and
@ref{62f,,filesystem_errors} members of @ref{60b,,PyConfig}.


Άλλαξε στην έκδοση 3.1: On some systems, conversion using the file system encoding may fail. In this
case, Python uses the @ref{2a6a,,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{948,,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{675,,UnicodeError}.

See also the @ref{74d,,locale encoding}.

@node Python UTF-8 Mode,Process Parameters,File Names Command Line Arguments and Environment Variables,os — Miscellaneous operating system interfaces
@anchor{library/os python-utf-8-mode}@anchor{322a}@anchor{library/os utf8-mode}@anchor{a46}
@subsubsection Python UTF-8 Mode



Added in version 3.7: See 
@geindex Python Enhancement Proposals; PEP 540
PEP 540@footnote{https://peps.python.org/pep-0540/} for more details.



Άλλαξε στην έκδοση 3.15: Python UTF-8 mode is now enabled by default (
@geindex Python Enhancement Proposals; PEP 686
PEP 686@footnote{https://peps.python.org/pep-0686/}).
It may be disabled by setting 
@geindex PYTHONUTF8
@geindex μεταβλητή περιβάλλοντος; PYTHONUTF8
@ref{1ad,,PYTHONUTF8=0} as
an environment variable or by using the @ref{178,,-X utf8=0} command line option.


The Python UTF-8 Mode ignores the @ref{74d,,locale encoding} and forces the usage
of the UTF-8 encoding:


@itemize *

@item 
Use UTF-8 as the @ref{948,,filesystem encoding}.

@item 
@ref{1017,,sys.getfilesystemencoding()} returns @code{'utf-8'}.

@item 
@ref{947,,locale.getpreferredencoding()} returns @code{'utf-8'} (the `do_setlocale'
argument has no effect).

@item 
@ref{94a,,sys.stdin}, @ref{e9c,,sys.stdout}, and @ref{d05,,sys.stderr} all use
UTF-8 as their text encoding, with the @code{surrogateescape}
@ref{1d6c,,error handler} being enabled for @code{sys.stdin}
and @code{sys.stdout} (@code{sys.stderr} continues to use
@code{backslashreplace} as it does in the default locale-aware mode)

@item 
On Unix, @ref{1e2c,,os.device_encoding()} returns @code{'utf-8'} rather than the
device encoding.
@end itemize

Note that the standard stream settings in UTF-8 mode can be overridden by
@geindex PYTHONIOENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONIOENCODING
@ref{13b3,,PYTHONIOENCODING} (just as they can be in the default locale-aware
mode).

As a consequence of the changes in those lower level APIs, other higher
level APIs also exhibit different default behaviours:


@itemize *

@item 
Command line arguments, environment variables and filenames are decoded
to text using the UTF-8 encoding.

@item 
@ref{1012,,os.fsdecode()} and @ref{1013,,os.fsencode()} use the UTF-8 encoding.

@item 
@ref{32b,,open()}, @ref{92b,,io.open()}, and @ref{32c,,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{a46,,Python UTF-8 Mode} is enabled by default.
It can be disabled using the @ref{178,,-X utf8=0} command line
option or the 
@geindex PYTHONUTF8
@geindex μεταβλητή περιβάλλοντος; PYTHONUTF8
@ref{1ad,,PYTHONUTF8=0} environment variable.
The Python UTF-8 Mode can only be disabled at Python startup. Its value
can be read from @ref{a7c,,sys.flags.utf8_mode}.

If the UTF-8 mode is disabled, 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 μεταβλητή περιβάλλοντος; PYTHONCOERCECLOCALE
@ref{e9b,,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.

See also the @ref{240e,,UTF-8 mode on Windows}
and the @ref{948,,filesystem encoding and error handler}.

@node Process Parameters,File Object Creation,Python UTF-8 Mode,os — Miscellaneous operating system interfaces
@anchor{library/os os-procinfo}@anchor{322b}@anchor{library/os process-parameters}@anchor{322c}
@subsubsection Process Parameters


These functions and data items provide information and operate on the current
process and user.

@geindex ctermid() (στη μονάδα os)
@anchor{library/os os ctermid}@anchor{322d}
@deffn {Συνάρτηση} os.ctermid ()

Return the filename corresponding to the controlling terminal of the process.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex environ (στη μονάδα os)
@anchor{library/os os environ}@anchor{4e5}
@deffn {Δεδομένα} os.environ

A @ref{1564,,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 @code{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{4e5,,os.environ},
except for changes made by modifying @code{os.environ} directly.

This mapping may be used to modify the environment as well as query the
environment.  @ref{4e7,,putenv()} will be called automatically when the mapping
is modified.

On Unix, keys and values use @ref{1017,,sys.getfilesystemencoding()} and
@code{'surrogateescape'} error handler. Use @ref{4e6,,environb} if you would like
to use a different encoding.

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 Σημείωση 
Calling @ref{4e7,,putenv()} directly does not change @ref{4e5,,os.environ}, so it’s better
to modify @code{os.environ}.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
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{4e8,,unsetenv()} will be called automatically when an item is deleted from
@ref{4e5,,os.environ}, and when one of the @ref{7de,,pop()} or
@ref{1954,,clear()} methods is called.


@subsubheading Δείτε επίσης


The @ref{4e4,,os.reload_environ()} function.



Άλλαξε στην έκδοση 3.9: Updated to support 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}’s merge (@code{|}) and update (@code{|=}) operators.

@end deffn

@geindex environb (στη μονάδα os)
@anchor{library/os os environb}@anchor{4e6}
@deffn {Δεδομένα} os.environb

Bytes version of @ref{4e5,,environ}: a @ref{1564,,mapping} object where both keys
and values are @ref{1c7,,bytes} objects representing the process environment.
@code{environ} and @code{environb} are synchronized (modifying
@code{environb} updates @code{environ}, and vice versa).

@code{environb} is only available if @ref{15bc,,supports_bytes_environ} is
@code{True}.


Added in version 3.2.



Άλλαξε στην έκδοση 3.9: Updated to support 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}’s merge (@code{|}) and update (@code{|=}) operators.

@end deffn

@geindex reload_environ() (στη μονάδα os)
@anchor{library/os os reload_environ}@anchor{4e4}
@deffn {Συνάρτηση} os.reload_environ ()

The @ref{4e5,,os.environ} and @ref{4e6,,os.environb} mappings are a cache of
environment variables at the time that Python started.
As such, changes to the current process environment are not reflected
if made outside Python, or by @ref{4e7,,os.putenv()} or @ref{4e8,,os.unsetenv()}.
Use @code{os.reload_environ()} to update @code{os.environ} and @code{os.environb}
with any such changes to the current process environment.

@cartouche
@quotation Προειδοποίηση 
This function is not thread-safe. Calling it while the environment is
being modified in another thread is an undefined behavior. Reading from
@ref{4e5,,os.environ} or @ref{4e6,,os.environb}, or calling @ref{322e,,os.getenv()}
while reloading, may return an empty result.
@end quotation
@end cartouche


Added in version 3.14.

@end deffn


@deffn {Συνάρτηση} os.chdir (path)

@deffnx {Συνάρτηση} os.fchdir (fd)

@deffnx {Συνάρτηση} os.getcwd ()

These functions are described in @ref{322f,,Files and Directories}.
@end deffn

@geindex fsencode() (στη μονάδα os)
@anchor{library/os os fsencode}@anchor{1013}
@deffn {Συνάρτηση} os.fsencode (filename)

Encode @ref{79f,,path-like} `filename' to the
@ref{948,,filesystem encoding and error handler}; return @ref{1c7,,bytes}
unchanged.

@ref{1012,,fsdecode()} is the reverse function.


Added in version 3.2.



Άλλαξε στην έκδοση 3.6: Support added to accept objects implementing the @ref{100f,,os.PathLike}
interface.

@end deffn

@geindex fsdecode() (στη μονάδα os)
@anchor{library/os os fsdecode}@anchor{1012}
@deffn {Συνάρτηση} os.fsdecode (filename)

Decode the @ref{79f,,path-like} `filename' from the
@ref{948,,filesystem encoding and error handler}; return @ref{1df,,str}
unchanged.

@ref{1013,,fsencode()} is the reverse function.


Added in version 3.2.



Άλλαξε στην έκδοση 3.6: Support added to accept objects implementing the @ref{100f,,os.PathLike}
interface.

@end deffn

@geindex fspath() (στη μονάδα os)
@anchor{library/os os fspath}@anchor{1011}
@deffn {Συνάρτηση} os.fspath (path)

Return the file system representation of the path.

If @ref{1df,,str} or @ref{1c7,,bytes} is passed in, it is returned unchanged.
Otherwise @ref{1010,,__fspath__()} is called and its value is
returned as long as it is a @code{str} or @code{bytes} object.
In all other cases, @ref{291,,TypeError} is raised.


Added in version 3.6.

@end deffn

@geindex PathLike (κλάση σε os)
@anchor{library/os os PathLike}@anchor{100f}
@deffn {Κλάση} os.PathLike

An @ref{155f,,abstract base class} for objects representing a file system path,
e.g. @ref{8b6,,pathlib.PurePath}.


Added in version 3.6.


@geindex __fspath__() (μέθοδος της os.PathLike)
@anchor{library/os os PathLike __fspath__}@anchor{1010}
@deffn {Μέθοδος} abstractmethod __fspath__ ()

Return the file system path representation of the object.

The method should only return a @ref{1df,,str} or @ref{1c7,,bytes} object,
with the preference being for @code{str}.
@end deffn
@end deffn

@geindex getenv() (στη μονάδα os)
@anchor{library/os os getenv}@anchor{322e}
@deffn {Συνάρτηση} 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 @code{getenv()} uses @ref{4e5,,os.environ}, the mapping of @code{getenv()} is
similarly also captured on import, and the function may not reflect
future environment changes.

On Unix, keys and values are decoded with @ref{1017,,sys.getfilesystemencoding()}
and @code{'surrogateescape'} error handler. Use @ref{15bd,,os.getenvb()} if you
would like to use a different encoding.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.
@end deffn

@geindex getenvb() (στη μονάδα os)
@anchor{library/os os getenvb}@anchor{15bd}
@deffn {Συνάρτηση} 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 @code{getenvb()} uses @ref{4e6,,os.environb}, the mapping of @code{getenvb()} is
similarly also captured on import, and the function may not reflect
future environment changes.

@code{getenvb()} is only available if @ref{15bc,,supports_bytes_environ}
is @code{True}.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.2.

@end deffn

@geindex get_exec_path() (στη μονάδα os)
@anchor{library/os os get_exec_path}@anchor{3230}
@deffn {Συνάρτηση} os.get_exec_path (env=None)

Returns the list of directories that will be searched for a named
executable, similar to a shell, when launching a process.
`env', when specified, should be an environment variable dictionary
to lookup the PATH in.
By default, when `env' is @code{None}, @ref{4e5,,environ} is used.


Added in version 3.2.

@end deffn

@geindex getegid() (στη μονάδα os)
@anchor{library/os os getegid}@anchor{3231}
@deffn {Συνάρτηση} os.getegid ()

Return the effective group id of the current process.  This corresponds to the
«set id» bit on the file being executed in the current process.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex geteuid() (στη μονάδα os)
@anchor{library/os os geteuid}@anchor{1d6f}
@deffn {Συνάρτηση} os.geteuid ()

@geindex user;effective id

Return the current process’s effective user id.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex getgid() (στη μονάδα os)
@anchor{library/os os getgid}@anchor{3232}
@deffn {Συνάρτηση} os.getgid ()

@geindex process;group

Return the real group id of the current process.

@ref{232d,,Διαθεσιμότητα}: Unix.

The function is a stub on WASI, see @ref{1d67,,WebAssembly platforms} for more
information.
@end deffn

@geindex getgrouplist() (στη μονάδα os)
@anchor{library/os os getgrouplist}@anchor{14c0}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.3.

@end deffn

@geindex getgroups() (στη μονάδα os)
@anchor{library/os os getgroups}@anchor{3233}
@deffn {Συνάρτηση} os.getgroups ()

Return list of supplemental group ids associated with the current process.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.

@cartouche
@quotation Σημείωση 
On macOS, @code{getgroups()} behavior differs somewhat from
other Unix platforms. If the Python interpreter was built with a
deployment target of @code{10.5} or earlier, @code{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{3234,,setgroups()} if suitably privileged.
If built with a deployment target greater than @code{10.5},
@code{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 @code{setgroups()}, and its length is not limited to 16.  The
deployment target value can be obtained with
@ref{41e,,sysconfig.get_config_var('MACOSX_DEPLOYMENT_TARGET')}.
@end quotation
@end cartouche
@end deffn

@geindex getlogin() (στη μονάδα os)
@anchor{library/os os getlogin}@anchor{19f4}
@deffn {Συνάρτηση} os.getlogin ()

Return the name of the user logged in on the controlling terminal of the
process.  For most purposes, it is more useful to use
@ref{848,,getpass.getuser()} since the latter checks the environment variables
@geindex LOGNAME
@geindex μεταβλητή περιβάλλοντος; LOGNAME
@code{LOGNAME} or 
@geindex USERNAME
@geindex μεταβλητή περιβάλλοντος; USERNAME
@code{USERNAME} to find out who the user is, and
falls back to @code{pwd.getpwuid(os.getuid())[0]} to get the login name of the
current real user id.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows, not WASI.
@end deffn

@geindex getpgid() (στη μονάδα os)
@anchor{library/os os getpgid}@anchor{3235}
@deffn {Συνάρτηση} os.getpgid (pid)

Return the process group id of the process with process id `pid'. If `pid' is 0,
the process group id of the current process is returned.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex getpgrp() (στη μονάδα os)
@anchor{library/os os getpgrp}@anchor{3236}
@deffn {Συνάρτηση} os.getpgrp ()

@geindex process;group

Return the id of the current process group.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex getpid() (στη μονάδα os)
@anchor{library/os os getpid}@anchor{3226}
@deffn {Συνάρτηση} os.getpid ()

@geindex process;id

Return the current process id.

The function is a stub on WASI, see @ref{1d67,,WebAssembly platforms} for more
information.
@end deffn

@geindex getppid() (στη μονάδα os)
@anchor{library/os os getppid}@anchor{1bd6}
@deffn {Συνάρτηση} os.getppid ()

@geindex process;id of parent

Return the parent’s process id.  When the parent process has exited, on Unix
the id returned is the one of the init process (1), on Windows it is still
the same id, which may be already reused by another process.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows, not WASI.


Άλλαξε στην έκδοση 3.2: Added support for Windows.

@end deffn

@geindex getpriority() (στη μονάδα os)
@anchor{library/os os getpriority}@anchor{14ab}
@deffn {Συνάρτηση} os.getpriority (which, who)

@geindex process;scheduling priority

Get program scheduling priority.  The value `which' is one of
@ref{3237,,PRIO_PROCESS}, @ref{3238,,PRIO_PGRP}, or @ref{3239,,PRIO_USER}, and `who'
is interpreted relative to `which' (a process identifier for
@code{PRIO_PROCESS}, process group identifier for @code{PRIO_PGRP}, and a
user ID for @code{PRIO_USER}).  A zero value for `who' denotes
(respectively) the calling process, the process group of the calling process,
or the real user ID of the calling process.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.3.

@end deffn

@geindex PRIO_PROCESS (στη μονάδα os)
@geindex PRIO_PGRP (στη μονάδα os)
@geindex PRIO_USER (στη μονάδα os)
@anchor{library/os os PRIO_PROCESS}@anchor{3237}
@deffn {Δεδομένα} os.PRIO_PROCESS
@anchor{library/os os PRIO_PGRP}@anchor{3238}
@deffnx {Δεδομένα} os.PRIO_PGRP
@anchor{library/os os PRIO_USER}@anchor{3239}
@deffnx {Δεδομένα} os.PRIO_USER

Parameters for the @ref{14ab,,getpriority()} and @ref{14ac,,setpriority()} functions.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.3.

@end deffn

@geindex PRIO_DARWIN_THREAD (στη μονάδα os)
@geindex PRIO_DARWIN_PROCESS (στη μονάδα os)
@geindex PRIO_DARWIN_BG (στη μονάδα os)
@geindex PRIO_DARWIN_NONUI (στη μονάδα os)
@anchor{library/os os PRIO_DARWIN_THREAD}@anchor{323a}
@deffn {Δεδομένα} os.PRIO_DARWIN_THREAD
@anchor{library/os os PRIO_DARWIN_PROCESS}@anchor{323b}
@deffnx {Δεδομένα} os.PRIO_DARWIN_PROCESS
@anchor{library/os os PRIO_DARWIN_BG}@anchor{323c}
@deffnx {Δεδομένα} os.PRIO_DARWIN_BG
@anchor{library/os os PRIO_DARWIN_NONUI}@anchor{323d}
@deffnx {Δεδομένα} os.PRIO_DARWIN_NONUI

Parameters for the @ref{14ab,,getpriority()} and @ref{14ac,,setpriority()} functions.

@ref{232d,,Διαθεσιμότητα}: macOS


Added in version 3.12.

@end deffn

@geindex getresuid() (στη μονάδα os)
@anchor{library/os os getresuid}@anchor{16ba}
@deffn {Συνάρτηση} os.getresuid ()

Return a tuple (ruid, euid, suid) denoting the current process’s
real, effective, and saved user ids.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.2.

@end deffn

@geindex getresgid() (στη μονάδα os)
@anchor{library/os os getresgid}@anchor{16b9}
@deffn {Συνάρτηση} os.getresgid ()

Return a tuple (rgid, egid, sgid) denoting the current process’s
real, effective, and saved group ids.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.2.

@end deffn

@geindex getuid() (στη μονάδα os)
@anchor{library/os os getuid}@anchor{1a11}
@deffn {Συνάρτηση} os.getuid ()

@geindex user;id

Return the current process’s real user id.

@ref{232d,,Διαθεσιμότητα}: Unix.

The function is a stub on WASI, see @ref{1d67,,WebAssembly platforms} for more
information.
@end deffn

@geindex initgroups() (στη μονάδα os)
@anchor{library/os os initgroups}@anchor{16bd}
@deffn {Συνάρτηση} os.initgroups (username, gid, /)

Call the system @code{initgroups()} to initialize the group access list with all of
the groups of which the specified username is a member, plus the specified
group id.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android.


Added in version 3.2.

@end deffn

@geindex putenv() (στη μονάδα os)
@anchor{library/os os putenv}@anchor{4e7}
@deffn {Συνάρτηση} os.putenv (key, value, /)

@geindex environment variables;setting

Set the environment variable named `key' to the string `value'.  Such
changes to the environment affect subprocesses started with @ref{17ff,,os.system()},
@ref{585,,popen()} or @ref{6bd,,fork()} and @ref{323e,,execv()}.

Assignments to items in @ref{4e5,,os.environ} are automatically translated into
corresponding calls to @code{putenv()}; however, calls to @code{putenv()}
don’t update @code{os.environ}, so it is actually preferable to assign to items
of @code{os.environ}. This also applies to @ref{322e,,getenv()} and @ref{15bd,,getenvb()}, which
respectively use @code{os.environ} and @ref{4e6,,os.environb} in their implementations.

See also the @ref{4e4,,os.reload_environ()} function.

@cartouche
@quotation Σημείωση 
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

Raises an @ref{1e65,,auditing event} @code{os.putenv} with arguments @code{key}, @code{value}.


Άλλαξε στην έκδοση 3.9: The function is now always available.

@end deffn

@geindex setegid() (στη μονάδα os)
@anchor{library/os os setegid}@anchor{323f}
@deffn {Συνάρτηση} os.setegid (egid, /)

Set the current process’s effective group id.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android.
@end deffn

@geindex seteuid() (στη μονάδα os)
@anchor{library/os os seteuid}@anchor{3240}
@deffn {Συνάρτηση} os.seteuid (euid, /)

Set the current process’s effective user id.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android.
@end deffn

@geindex setgid() (στη μονάδα os)
@anchor{library/os os setgid}@anchor{3241}
@deffn {Συνάρτηση} os.setgid (gid, /)

Set the current process” group id.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android.
@end deffn

@geindex setgroups() (στη μονάδα os)
@anchor{library/os os setgroups}@anchor{3234}
@deffn {Συνάρτηση} os.setgroups (groups, /)

Set the list of supplemental group ids associated with the current process to
`groups'. `groups' must be a sequence, and each element must be an integer
identifying a group. This operation is typically available only to the superuser.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.

@cartouche
@quotation Σημείωση 
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{3233,,getgroups()} for cases where it may not
return the same group list set by calling setgroups().
@end quotation
@end cartouche
@end deffn

@geindex setns() (στη μονάδα os)
@anchor{library/os os setns}@anchor{1d3f}
@deffn {Συνάρτηση} 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{3242,,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{267,,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{3242,,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{19b2,,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{232d,,Διαθεσιμότητα}: Linux >= 3.0 with glibc >= 2.14.


Added in version 3.12.



@subsubheading Δείτε επίσης


The @ref{1d40,,unshare()} function.

@end deffn

@geindex setpgrp() (στη μονάδα os)
@anchor{library/os os setpgrp}@anchor{3243}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex setpgid() (στη μονάδα os)
@anchor{library/os os setpgid}@anchor{3244}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex setpriority() (στη μονάδα os)
@anchor{library/os os setpriority}@anchor{14ac}
@deffn {Συνάρτηση} os.setpriority (which, who, priority)

@geindex process;scheduling priority

Set program scheduling priority. The value `which' is one of
@ref{3237,,PRIO_PROCESS}, @ref{3238,,PRIO_PGRP}, or @ref{3239,,PRIO_USER}, and `who'
is interpreted relative to `which' (a process identifier for
@code{PRIO_PROCESS}, process group identifier for @code{PRIO_PGRP}, and a
user ID for @code{PRIO_USER}). A zero value for `who' denotes
(respectively) the calling process, the process group of the calling process,
or the real user ID of the calling process.
`priority' is a value in the range -20 to 19. The default priority is 0;
lower priorities cause more favorable scheduling.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.3.

@end deffn

@geindex setregid() (στη μονάδα os)
@anchor{library/os os setregid}@anchor{3245}
@deffn {Συνάρτηση} os.setregid (rgid, egid, /)

Set the current process’s real and effective group ids.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android.
@end deffn

@geindex setresgid() (στη μονάδα os)
@anchor{library/os os setresgid}@anchor{16bb}
@deffn {Συνάρτηση} os.setresgid (rgid, egid, sgid, /)

Set the current process’s real, effective, and saved group ids.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android.


Added in version 3.2.

@end deffn

@geindex setresuid() (στη μονάδα os)
@anchor{library/os os setresuid}@anchor{16bc}
@deffn {Συνάρτηση} os.setresuid (ruid, euid, suid, /)

Set the current process’s real, effective, and saved user ids.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android.


Added in version 3.2.

@end deffn

@geindex setreuid() (στη μονάδα os)
@anchor{library/os os setreuid}@anchor{3246}
@deffn {Συνάρτηση} os.setreuid (ruid, euid, /)

Set the current process’s real and effective user ids.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android.
@end deffn

@geindex getsid() (στη μονάδα os)
@anchor{library/os os getsid}@anchor{3247}
@deffn {Συνάρτηση} os.getsid (pid, /)

Call the system call @code{getsid()}.  See the Unix manual for the semantics.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex setsid() (στη μονάδα os)
@anchor{library/os os setsid}@anchor{1faa}
@deffn {Συνάρτηση} os.setsid ()

Call the system call @code{setsid()}.  See the Unix manual for the semantics.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex setuid() (στη μονάδα os)
@anchor{library/os os setuid}@anchor{3248}
@deffn {Συνάρτηση} os.setuid (uid, /)

@geindex user;id@comma{} setting

Set the current process’s user id.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android.
@end deffn

@c placed in this section since it relates to errno.... a little weak

@geindex strerror() (στη μονάδα os)
@anchor{library/os os strerror}@anchor{3249}
@deffn {Συνάρτηση} 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{277,,ValueError} is raised.
@end deffn

@geindex supports_bytes_environ (στη μονάδα os)
@anchor{library/os os supports_bytes_environ}@anchor{15bc}
@deffn {Δεδομένα} os.supports_bytes_environ

@code{True} if the native OS type of the environment is bytes (eg. @code{False} on
Windows).


Added in version 3.2.

@end deffn

@geindex umask() (στη μονάδα os)
@anchor{library/os os umask}@anchor{324a}
@deffn {Συνάρτηση} os.umask (mask, /)

Set the current numeric umask and return the previous umask.

The function is a stub on WASI, see @ref{1d67,,WebAssembly platforms} for more
information.
@end deffn

@geindex uname() (στη μονάδα os)
@anchor{library/os os uname}@anchor{14c2}
@deffn {Συνάρτηση} os.uname ()

@geindex gethostname() (in module socket)
@geindex gethostbyaddr() (in module socket)

Returns information identifying the current operating system.
The return value is an object with five attributes:


@itemize *

@item 
@code{sysname} - operating system name

@item 
@code{nodename} - name of machine on network (implementation-defined)

@item 
@code{release} - operating system release

@item 
@code{version} - operating system version

@item 
@code{machine} - hardware identifier
@end itemize

For backwards compatibility, this object is also iterable, behaving
like a five-tuple containing @code{sysname}, @code{nodename},
@code{release}, @code{version}, and @code{machine}
in that order.

Some systems truncate @code{nodename} to 8 characters or to the
leading component; a better way to get the hostname is
@ref{324b,,socket.gethostname()}  or even
@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{2001,,platform.uname()}
can be used to get the user-facing operating system name and version on iOS and
Android.

@ref{232d,,Διαθεσιμότητα}: Unix.


Άλλαξε στην έκδοση 3.3: Return type changed from a tuple to a tuple-like object
with named attributes.

@end deffn

@geindex unsetenv() (στη μονάδα os)
@anchor{library/os os unsetenv}@anchor{4e8}
@deffn {Συνάρτηση} os.unsetenv (key, /)

@geindex environment variables;deleting

Unset (delete) the environment variable named `key'. Such changes to the
environment affect subprocesses started with @ref{17ff,,os.system()}, @ref{585,,popen()} or
@ref{6bd,,fork()} and @ref{323e,,execv()}.

Deletion of items in @ref{4e5,,os.environ} is automatically translated into a
corresponding call to @code{unsetenv()}; however, calls to @code{unsetenv()}
don’t update @code{os.environ}, so it is actually preferable to delete items of
@code{os.environ}.

See also the @ref{4e4,,os.reload_environ()} function.

Raises an @ref{1e65,,auditing event} @code{os.unsetenv} with argument @code{key}.


Άλλαξε στην έκδοση 3.9: The function is now always available and is also available on Windows.

@end deffn

@geindex unshare() (στη μονάδα os)
@anchor{library/os os unshare}@anchor{1d40}
@deffn {Συνάρτηση} 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{3242,,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{232d,,Διαθεσιμότητα}: Linux >= 2.6.16.


Added in version 3.12.



@subsubheading Δείτε επίσης


The @ref{1d3f,,setns()} function.

@end deffn
@anchor{library/os os-unshare-clone-flags}@anchor{3242}
Flags to the @ref{1d40,,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 (στη μονάδα os)
@geindex CLONE_FS (στη μονάδα os)
@geindex CLONE_NEWCGROUP (στη μονάδα os)
@geindex CLONE_NEWIPC (στη μονάδα os)
@geindex CLONE_NEWNET (στη μονάδα os)
@geindex CLONE_NEWNS (στη μονάδα os)
@geindex CLONE_NEWPID (στη μονάδα os)
@geindex CLONE_NEWTIME (στη μονάδα os)
@geindex CLONE_NEWUSER (στη μονάδα os)
@geindex CLONE_NEWUTS (στη μονάδα os)
@geindex CLONE_SIGHAND (στη μονάδα os)
@geindex CLONE_SYSVSEM (στη μονάδα os)
@geindex CLONE_THREAD (στη μονάδα os)
@geindex CLONE_VM (στη μονάδα os)
@anchor{library/os os CLONE_FILES}@anchor{324c}
@deffn {Δεδομένα} os.CLONE_FILES
@anchor{library/os os CLONE_FS}@anchor{324d}
@deffnx {Δεδομένα} os.CLONE_FS
@anchor{library/os os CLONE_NEWCGROUP}@anchor{324e}
@deffnx {Δεδομένα} os.CLONE_NEWCGROUP
@anchor{library/os os CLONE_NEWIPC}@anchor{324f}
@deffnx {Δεδομένα} os.CLONE_NEWIPC
@anchor{library/os os CLONE_NEWNET}@anchor{3250}
@deffnx {Δεδομένα} os.CLONE_NEWNET
@anchor{library/os os CLONE_NEWNS}@anchor{3251}
@deffnx {Δεδομένα} os.CLONE_NEWNS
@anchor{library/os os CLONE_NEWPID}@anchor{3252}
@deffnx {Δεδομένα} os.CLONE_NEWPID
@anchor{library/os os CLONE_NEWTIME}@anchor{3253}
@deffnx {Δεδομένα} os.CLONE_NEWTIME
@anchor{library/os os CLONE_NEWUSER}@anchor{3254}
@deffnx {Δεδομένα} os.CLONE_NEWUSER
@anchor{library/os os CLONE_NEWUTS}@anchor{3255}
@deffnx {Δεδομένα} os.CLONE_NEWUTS
@anchor{library/os os CLONE_SIGHAND}@anchor{3256}
@deffnx {Δεδομένα} os.CLONE_SIGHAND
@anchor{library/os os CLONE_SYSVSEM}@anchor{3257}
@deffnx {Δεδομένα} os.CLONE_SYSVSEM
@anchor{library/os os CLONE_THREAD}@anchor{3258}
@deffnx {Δεδομένα} os.CLONE_THREAD
@anchor{library/os os CLONE_VM}@anchor{3259}
@deffnx {Δεδομένα} os.CLONE_VM
@end deffn

@node File Object Creation,File Descriptor Operations,Process Parameters,os — Miscellaneous operating system interfaces
@anchor{library/os file-object-creation}@anchor{325a}@anchor{library/os os-newstreams}@anchor{325b}
@subsubsection File Object Creation


These functions create new @ref{156c,,file objects}.  (See also
@ref{114b,,open()} for opening file descriptors.)

@geindex fdopen() (στη μονάδα os)
@anchor{library/os os fdopen}@anchor{2571}
@deffn {Συνάρτηση} os.fdopen (fd, *args, **kwargs)

Return an open file object connected to the file descriptor `fd'.  This is an
alias of the @ref{32b,,open()} built-in function and accepts the same arguments.
The only difference is that the first argument of @code{fdopen()} must always
be an integer.
@end deffn

@node File Descriptor Operations,Files and Directories,File Object Creation,os — Miscellaneous operating system interfaces
@anchor{library/os file-descriptor-operations}@anchor{325c}@anchor{library/os os-fd-ops}@anchor{325d}
@subsubsection File Descriptor Operations


These functions operate on I/O streams referenced using file descriptors.

File descriptors are small integers corresponding to a file that has been opened
by the current process.  For example, standard input is usually file descriptor
0, standard output is 1, and standard error is 2.  Further files opened by a
process will then be assigned 3, 4, 5, and so forth.  The name «file descriptor»
is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
by file descriptors.

The @ref{19b2,,fileno()} method can be used to obtain the file descriptor
associated with a @ref{156c,,file object} when required.  Note that using the file
descriptor directly will bypass the file object methods, ignoring aspects such
as internal buffering of data.

@geindex close() (στη μονάδα os)
@anchor{library/os os close}@anchor{f31}
@deffn {Συνάρτηση} os.close (fd)

Close file descriptor `fd'.

@cartouche
@quotation Σημείωση 
This function is intended for low-level I/O and must be applied to a file
descriptor as returned by @ref{114b,,os.open()} or @ref{1d62,,pipe()}.  To close a «file
object» returned by the built-in function @ref{32b,,open()} or by @ref{585,,popen()} or
@ref{2571,,fdopen()}, use its @ref{70b,,close()} method.
@end quotation
@end cartouche
@end deffn

@geindex closerange() (στη μονάδα os)
@anchor{library/os os closerange}@anchor{325e}
@deffn {Συνάρτηση} os.closerange (fd_low, fd_high, /)

Close all file descriptors from `fd_low' (inclusive) to `fd_high' (exclusive),
ignoring errors. Equivalent to (but much faster than):

@example
for fd in range(fd_low, fd_high):
    try:
        os.close(fd)
    except OSError:
        pass
@end example
@end deffn

@geindex copy_file_range() (στη μονάδα os)
@anchor{library/os os copy_file_range}@anchor{1ad5}
@deffn {Συνάρτηση} 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{53c,,OSError} is
raised with @ref{19ca,,errno} set to @ref{325f,,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.

The return value is the amount of bytes copied. This could be less than the
amount requested.

@cartouche
@quotation Σημείωση 
On Linux, @ref{1ad5,,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{232d,,Διαθεσιμότητα}: Linux >= 4.5 with glibc >= 2.27.


Added in version 3.8.

@end deffn

@geindex device_encoding() (στη μονάδα os)
@anchor{library/os os device_encoding}@anchor{1e2c}
@deffn {Συνάρτηση} os.device_encoding (fd)

Return a string describing the encoding of the device associated with `fd'
if it is connected to a terminal; else return @ref{a65,,None}.

On Unix, if the @ref{a46,,Python UTF-8 Mode} is enabled, return
@code{'UTF-8'} rather than the device encoding.


Άλλαξε στην έκδοση 3.10: On Unix, the function now implements the Python UTF-8 Mode.

@end deffn

@geindex dup() (στη μονάδα os)
@anchor{library/os os dup}@anchor{1fb2}
@deffn {Συνάρτηση} os.dup (fd, /)

Return a duplicate of file descriptor `fd'. The new file descriptor is
@ref{12aa,,non-inheritable}.

On Windows, when duplicating a standard stream (0: stdin, 1: stdout,
2: stderr), the new file descriptor is @ref{12aa,,inheritable}.

@ref{232d,,Διαθεσιμότητα}: not WASI.


Άλλαξε στην έκδοση 3.4: The new file descriptor is now non-inheritable.

@end deffn

@geindex dup2() (στη μονάδα os)
@anchor{library/os os dup2}@anchor{f20}
@deffn {Συνάρτηση} os.dup2 (fd, fd2, inheritable=True)

Duplicate file descriptor `fd' to `fd2', closing the latter first if
necessary. Return `fd2'. The new file descriptor is @ref{12aa,,inheritable} by default or non-inheritable if `inheritable'
is @code{False}.

@ref{232d,,Διαθεσιμότητα}: not WASI.


Άλλαξε στην έκδοση 3.4: Add the optional `inheritable' parameter.



Άλλαξε στην έκδοση 3.7: Return `fd2' on success. Previously, @code{None} was always returned.

@end deffn

@geindex fchmod() (στη μονάδα os)
@anchor{library/os os fchmod}@anchor{72d}
@deffn {Συνάρτηση} os.fchmod (fd, mode)

Change the mode of the file given by `fd' to the numeric `mode'.  See the
docs for @ref{72c,,chmod()} for possible values of `mode'.  As of Python 3.3, this
is equivalent to @code{os.chmod(fd, mode)}.

Raises an @ref{1e65,,auditing event} @code{os.chmod} with arguments @code{path}, @code{mode}, @code{dir_fd}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.

The function is limited on WASI, see @ref{1d67,,WebAssembly platforms} for more
information.


Άλλαξε στην έκδοση 3.13: Added support on Windows.

@end deffn

@geindex fchown() (στη μονάδα os)
@anchor{library/os os fchown}@anchor{1143}
@deffn {Συνάρτηση} os.fchown (fd, uid, gid)

Change the owner and group id of the file given by `fd' to the numeric `uid'
and `gid'.  To leave one of the ids unchanged, set it to -1.  See
@ref{149a,,chown()}.  As of Python 3.3, this is equivalent to @code{os.chown(fd, uid,
gid)}.

Raises an @ref{1e65,,auditing event} @code{os.chown} with arguments @code{path}, @code{uid}, @code{gid}, @code{dir_fd}.

@ref{232d,,Διαθεσιμότητα}: Unix.

The function is limited on WASI, see @ref{1d67,,WebAssembly platforms} for more
information.
@end deffn

@geindex fdatasync() (στη μονάδα os)
@anchor{library/os os fdatasync}@anchor{1144}
@deffn {Συνάρτηση} os.fdatasync (fd)

Force write of file with filedescriptor `fd' to disk. Does not force update of
metadata.

@ref{232d,,Διαθεσιμότητα}: Unix.

@cartouche
@quotation Σημείωση 
This function is not available on MacOS.
@end quotation
@end cartouche
@end deffn

@geindex fpathconf() (στη μονάδα os)
@anchor{library/os os fpathconf}@anchor{3260}
@deffn {Συνάρτηση} os.fpathconf (fd, name, /)

Return system configuration information relevant to an open file. `name'
specifies the configuration value to retrieve; it may be a string which is the
name of a defined system value; these names are specified in a number of
standards (POSIX.1, Unix 95, Unix 98, and others).  Some platforms define
additional names as well.  The names known to the host operating system are
given in the @code{pathconf_names} dictionary.  For configuration variables not
included in that mapping, passing an integer for `name' is also accepted.

If `name' is a string and is not known, @ref{277,,ValueError} is raised.  If a
specific value for `name' is not supported by the host system, even if it is
included in @code{pathconf_names}, an @ref{53c,,OSError} is raised with
@ref{1fc1,,errno.EINVAL} for the error number.

As of Python 3.3, this is equivalent to @code{os.pathconf(fd, name)}.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex fstat() (στη μονάδα os)
@anchor{library/os os fstat}@anchor{1145}
@deffn {Συνάρτηση} os.fstat (fd)

Get the status of the file descriptor `fd'. Return a @ref{1863,,stat_result}
object.

As of Python 3.3, this is equivalent to @code{os.stat(fd)}.


@subsubheading Δείτε επίσης


The @ref{4f5,,stat()} function.

@end deffn

@geindex fstatvfs() (στη μονάδα os)
@anchor{library/os os fstatvfs}@anchor{1146}
@deffn {Συνάρτηση} os.fstatvfs (fd, /)

Return information about the filesystem containing the file associated with
file descriptor `fd', like @ref{14a8,,statvfs()}.  As of Python 3.3, this is
equivalent to @code{os.statvfs(fd)}.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex fsync() (στη μονάδα os)
@anchor{library/os os fsync}@anchor{1147}
@deffn {Συνάρτηση} 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.

If you’re starting with a buffered Python @ref{156c,,file object} `f', first do
@code{f.flush()}, and then do @code{os.fsync(f.fileno())}, to ensure that all internal
buffers associated with `f' are written to disk.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.
@end deffn

@geindex ftruncate() (στη μονάδα os)
@anchor{library/os os ftruncate}@anchor{1148}
@deffn {Συνάρτηση} os.ftruncate (fd, length, /)

Truncate the file corresponding to file descriptor `fd', so that it is at
most `length' bytes in size.  As of Python 3.3, this is equivalent to
@code{os.truncate(fd, length)}.

Raises an @ref{1e65,,auditing event} @code{os.truncate} with arguments @code{fd}, @code{length}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.


Άλλαξε στην έκδοση 3.5: Added support for Windows

@end deffn

@geindex get_blocking() (στη μονάδα os)
@anchor{library/os os get_blocking}@anchor{11ec}
@deffn {Συνάρτηση} os.get_blocking (fd, /)

Get the blocking mode of the file descriptor: @code{False} if the
@ref{11ee,,O_NONBLOCK} flag is set, @code{True} if the flag is cleared.

See also @ref{11ed,,set_blocking()} and @ref{3261,,socket.socket.setblocking()}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.

The function is limited on WASI, see @ref{1d67,,WebAssembly platforms} for more
information.

On Windows, this function is limited to pipes.


Added in version 3.5.



Άλλαξε στην έκδοση 3.12: Added support for pipes on Windows.

@end deffn

@geindex grantpt() (στη μονάδα os)
@anchor{library/os os grantpt}@anchor{1c06}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.13.

@end deffn

@geindex isatty() (στη μονάδα os)
@anchor{library/os os isatty}@anchor{1e2b}
@deffn {Συνάρτηση} os.isatty (fd, /)

Return @code{True} if the file descriptor `fd' is open and connected to a
tty(-like) device, else @code{False}.
@end deffn

@geindex lockf() (στη μονάδα os)
@anchor{library/os os lockf}@anchor{14bf}
@deffn {Συνάρτηση} os.lockf (fd, cmd, len, /)

Apply, test or remove a POSIX lock on an open file descriptor.
`fd' is an open file descriptor.
`cmd' specifies the command to use - one of @ref{3262,,F_LOCK}, @ref{3263,,F_TLOCK},
@ref{3264,,F_ULOCK} or @ref{3265,,F_TEST}.
`len' specifies the section of the file to lock.

Raises an @ref{1e65,,auditing event} @code{os.lockf} with arguments @code{fd}, @code{cmd}, @code{len}.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex F_LOCK (στη μονάδα os)
@geindex F_TLOCK (στη μονάδα os)
@geindex F_ULOCK (στη μονάδα os)
@geindex F_TEST (στη μονάδα os)
@anchor{library/os os F_LOCK}@anchor{3262}
@deffn {Δεδομένα} os.F_LOCK
@anchor{library/os os F_TLOCK}@anchor{3263}
@deffnx {Δεδομένα} os.F_TLOCK
@anchor{library/os os F_ULOCK}@anchor{3264}
@deffnx {Δεδομένα} os.F_ULOCK
@anchor{library/os os F_TEST}@anchor{3265}
@deffnx {Δεδομένα} os.F_TEST

Flags that specify what action @ref{14bf,,lockf()} will take.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex login_tty() (στη μονάδα os)
@anchor{library/os os login_tty}@anchor{1ccb}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.11.

@end deffn

@geindex lseek() (στη μονάδα os)
@anchor{library/os os lseek}@anchor{14c3}
@deffn {Συνάρτηση} 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{1632,,SEEK_SET} or @code{0} – set `pos' relative to the beginning of the file

@item 
@ref{1633,,SEEK_CUR} or @code{1} – set `pos' relative to the current file position

@item 
@ref{1634,,SEEK_END} or @code{2} – set `pos' relative to the end of the file

@item 
@ref{3266,,SEEK_HOLE} – set `pos' to the next data location, relative to `pos'

@item 
@ref{3267,,SEEK_DATA} – set `pos' to the next data hole, relative to `pos'
@end itemize


Άλλαξε στην έκδοση 3.3: Add support for @code{SEEK_HOLE} and @code{SEEK_DATA}.

@end deffn

@geindex SEEK_SET (στη μονάδα os)
@geindex SEEK_CUR (στη μονάδα os)
@geindex SEEK_END (στη μονάδα os)
@anchor{library/os os SEEK_SET}@anchor{1632}
@deffn {Δεδομένα} os.SEEK_SET
@anchor{library/os os SEEK_CUR}@anchor{1633}
@deffnx {Δεδομένα} os.SEEK_CUR
@anchor{library/os os SEEK_END}@anchor{1634}
@deffnx {Δεδομένα} os.SEEK_END

Parameters to the @ref{14c3,,lseek()} function and the @ref{1631,,seek()}
method on @ref{156c,,file-like objects},
for whence to adjust the file position indicator.


@table @asis

@item @ref{1632,,SEEK_SET}

Adjust the file position relative to the beginning of the file.

@item @ref{1633,,SEEK_CUR}

Adjust the file position relative to the current file position.

@item @ref{1634,,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 (στη μονάδα os)
@geindex SEEK_DATA (στη μονάδα os)
@anchor{library/os os SEEK_HOLE}@anchor{3266}
@deffn {Δεδομένα} os.SEEK_HOLE
@anchor{library/os os SEEK_DATA}@anchor{3267}
@deffnx {Δεδομένα} os.SEEK_DATA

Parameters to the @ref{14c3,,lseek()} function and the @ref{1631,,seek()}
method on @ref{156c,,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 Σημείωση 
These operations only make sense for filesystems that support them.
@end quotation
@end cartouche

@ref{232d,,Διαθεσιμότητα}: Linux >= 3.1, macOS, Unix


Added in version 3.3.

@end deffn

@geindex open() (στη μονάδα os)
@anchor{library/os os open}@anchor{114b}
@deffn {Συνάρτηση} os.open (path, flags, mode=0o777, *, dir_fd=None)

Open the file `path' and set various flags according to `flags' and possibly
its mode according to `mode'.  When computing `mode', the current umask value
is first masked out.  Return the file descriptor for the newly opened file.
The new file descriptor is @ref{12aa,,non-inheritable}.

For a description of the flag and mode values, see the C run-time documentation;
flag constants (like @ref{3268,,O_RDONLY} and @ref{3269,,O_WRONLY}) are defined in
the @code{os} module.  In particular, on Windows adding
@ref{326a,,O_BINARY} is needed to open files in binary mode.

This function can support @ref{1496,,paths relative to directory descriptors} with the `dir_fd' parameter.

Raises an @ref{1e65,,auditing event} @code{open} with arguments @code{path}, @code{mode}, @code{flags}.


Άλλαξε στην έκδοση 3.4: The new file descriptor is now non-inheritable.


@cartouche
@quotation Σημείωση 
This function is intended for low-level I/O.  For normal usage, use the
built-in function @code{open()}, which returns a @ref{156c,,file object} with
@ref{16cd,,read()} and @ref{1099,,write()} methods.
To wrap a file descriptor in a file object, use @ref{2571,,fdopen()}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: Added the `dir_fd' parameter.



Άλλαξε στην έκδοση 3.5: If the system call is interrupted and the signal handler does not raise an
exception, the function now retries the system call instead of raising an
@ref{1141,,InterruptedError} exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

The following constants are options for the `flags' parameter to the
@ref{114b,,open()} function.  They can be combined using the bitwise OR operator
@code{|}.  Some of them are not available on all platforms.  For descriptions of
their availability and use, consult the @code{open(2)@footnote{https://manpages.debian.org/open(2)}} manual page on Unix
or the MSDN@footnote{https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx} on Windows.

@geindex O_RDONLY (στη μονάδα os)
@geindex O_WRONLY (στη μονάδα os)
@geindex O_RDWR (στη μονάδα os)
@geindex O_APPEND (στη μονάδα os)
@geindex O_CREAT (στη μονάδα os)
@geindex O_EXCL (στη μονάδα os)
@geindex O_TRUNC (στη μονάδα os)
@anchor{library/os os O_RDONLY}@anchor{3268}
@deffn {Δεδομένα} os.O_RDONLY
@anchor{library/os os O_WRONLY}@anchor{3269}
@deffnx {Δεδομένα} os.O_WRONLY
@anchor{library/os os O_RDWR}@anchor{326b}
@deffnx {Δεδομένα} os.O_RDWR
@anchor{library/os os O_APPEND}@anchor{326c}
@deffnx {Δεδομένα} os.O_APPEND
@anchor{library/os os O_CREAT}@anchor{326d}
@deffnx {Δεδομένα} os.O_CREAT
@anchor{library/os os O_EXCL}@anchor{1a0e}
@deffnx {Δεδομένα} os.O_EXCL
@anchor{library/os os O_TRUNC}@anchor{326e}
@deffnx {Δεδομένα} os.O_TRUNC

The above constants are available on Unix and Windows.
@end deffn

@geindex O_DSYNC (στη μονάδα os)
@geindex O_RSYNC (στη μονάδα os)
@geindex O_SYNC (στη μονάδα os)
@geindex O_NDELAY (στη μονάδα os)
@geindex O_NONBLOCK (στη μονάδα os)
@geindex O_NOCTTY (στη μονάδα os)
@geindex O_CLOEXEC (στη μονάδα os)
@anchor{library/os os O_DSYNC}@anchor{326f}
@deffn {Δεδομένα} os.O_DSYNC
@anchor{library/os os O_RSYNC}@anchor{3270}
@deffnx {Δεδομένα} os.O_RSYNC
@anchor{library/os os O_SYNC}@anchor{3271}
@deffnx {Δεδομένα} os.O_SYNC
@anchor{library/os os O_NDELAY}@anchor{3272}
@deffnx {Δεδομένα} os.O_NDELAY
@anchor{library/os os O_NONBLOCK}@anchor{11ee}
@deffnx {Δεδομένα} os.O_NONBLOCK
@anchor{library/os os O_NOCTTY}@anchor{3273}
@deffnx {Δεδομένα} os.O_NOCTTY
@anchor{library/os os O_CLOEXEC}@anchor{1424}
@deffnx {Δεδομένα} os.O_CLOEXEC

The above constants are only available on Unix.


Άλλαξε στην έκδοση 3.3: Add @code{O_CLOEXEC} constant.

@end deffn

@geindex O_BINARY (στη μονάδα os)
@geindex O_NOINHERIT (στη μονάδα os)
@geindex O_SHORT_LIVED (στη μονάδα os)
@geindex O_TEMPORARY (στη μονάδα os)
@geindex O_RANDOM (στη μονάδα os)
@geindex O_SEQUENTIAL (στη μονάδα os)
@geindex O_TEXT (στη μονάδα os)
@anchor{library/os os O_BINARY}@anchor{326a}
@deffn {Δεδομένα} os.O_BINARY
@anchor{library/os os O_NOINHERIT}@anchor{3274}
@deffnx {Δεδομένα} os.O_NOINHERIT
@anchor{library/os os O_SHORT_LIVED}@anchor{3275}
@deffnx {Δεδομένα} os.O_SHORT_LIVED
@anchor{library/os os O_TEMPORARY}@anchor{3276}
@deffnx {Δεδομένα} os.O_TEMPORARY
@anchor{library/os os O_RANDOM}@anchor{3277}
@deffnx {Δεδομένα} os.O_RANDOM
@anchor{library/os os O_SEQUENTIAL}@anchor{3278}
@deffnx {Δεδομένα} os.O_SEQUENTIAL
@anchor{library/os os O_TEXT}@anchor{3279}
@deffnx {Δεδομένα} os.O_TEXT

The above constants are only available on Windows.
@end deffn

@geindex O_EVTONLY (στη μονάδα os)
@geindex O_FSYNC (στη μονάδα os)
@geindex O_SYMLINK (στη μονάδα os)
@geindex O_NOFOLLOW_ANY (στη μονάδα os)
@anchor{library/os os O_EVTONLY}@anchor{bf3}
@deffn {Δεδομένα} os.O_EVTONLY
@anchor{library/os os O_FSYNC}@anchor{bf4}
@deffnx {Δεδομένα} os.O_FSYNC
@anchor{library/os os O_SYMLINK}@anchor{bf5}
@deffnx {Δεδομένα} os.O_SYMLINK
@anchor{library/os os O_NOFOLLOW_ANY}@anchor{bf6}
@deffnx {Δεδομένα} os.O_NOFOLLOW_ANY

The above constants are only available on macOS.


Άλλαξε στην έκδοση 3.10: Add @code{O_EVTONLY}, @code{O_FSYNC}, @code{O_SYMLINK}
and @code{O_NOFOLLOW_ANY} constants.

@end deffn

@geindex O_ASYNC (στη μονάδα os)
@geindex O_DIRECT (στη μονάδα os)
@geindex O_DIRECTORY (στη μονάδα os)
@geindex O_NOFOLLOW (στη μονάδα os)
@geindex O_NOATIME (στη μονάδα os)
@geindex O_PATH (στη μονάδα os)
@geindex O_TMPFILE (στη μονάδα os)
@geindex O_SHLOCK (στη μονάδα os)
@geindex O_EXLOCK (στη μονάδα os)
@anchor{library/os os O_ASYNC}@anchor{327a}
@deffn {Δεδομένα} os.O_ASYNC
@anchor{library/os os O_DIRECT}@anchor{327b}
@deffnx {Δεδομένα} os.O_DIRECT
@anchor{library/os os O_DIRECTORY}@anchor{327c}
@deffnx {Δεδομένα} os.O_DIRECTORY
@anchor{library/os os O_NOFOLLOW}@anchor{327d}
@deffnx {Δεδομένα} os.O_NOFOLLOW
@anchor{library/os os O_NOATIME}@anchor{327e}
@deffnx {Δεδομένα} os.O_NOATIME
@anchor{library/os os O_PATH}@anchor{131c}
@deffnx {Δεδομένα} os.O_PATH
@anchor{library/os os O_TMPFILE}@anchor{131d}
@deffnx {Δεδομένα} os.O_TMPFILE
@anchor{library/os os O_SHLOCK}@anchor{17d1}
@deffnx {Δεδομένα} os.O_SHLOCK
@anchor{library/os os O_EXLOCK}@anchor{17d2}
@deffnx {Δεδομένα} os.O_EXLOCK

The above constants are extensions and not present if they are not defined by
the C library.


Άλλαξε στην έκδοση 3.4: Add @code{O_PATH} on systems that support it.
Add @code{O_TMPFILE}, only available on Linux Kernel 3.11
  or newer.

@end deffn

@geindex openpty() (στη μονάδα os)
@anchor{library/os os openpty}@anchor{327f}
@deffn {Συνάρτηση} os.openpty ()

@geindex module;pty

Open a new pseudo-terminal pair. Return a pair of file descriptors
@code{(master, slave)} for the pty and the tty, respectively. The new file
descriptors are @ref{12aa,,non-inheritable}. For a (slightly) more
portable approach, use the @ref{b9,,pty} module.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Άλλαξε στην έκδοση 3.4: The new file descriptors are now non-inheritable.

@end deffn

@geindex pipe() (στη μονάδα os)
@anchor{library/os os pipe}@anchor{1d62}
@deffn {Συνάρτηση} os.pipe ()

Create a pipe.  Return a pair of file descriptors @code{(r, w)} usable for
reading and writing, respectively. The new file descriptor is
@ref{12aa,,non-inheritable}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.


Άλλαξε στην έκδοση 3.4: The new file descriptors are now non-inheritable.

@end deffn

@geindex pipe2() (στη μονάδα os)
@anchor{library/os os pipe2}@anchor{1495}
@deffn {Συνάρτηση} os.pipe2 (flags, /)

Create a pipe with `flags' set atomically.
`flags' can be constructed by ORing together one or more of these values:
@ref{11ee,,O_NONBLOCK}, @ref{1424,,O_CLOEXEC}.
Return a pair of file descriptors @code{(r, w)} usable for reading and writing,
respectively.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.3.

@end deffn

@geindex posix_fallocate() (στη μονάδα os)
@anchor{library/os os posix_fallocate}@anchor{114d}
@deffn {Συνάρτηση} os.posix_fallocate (fd, offset, len, /)

Ensures that enough disk space is allocated for the file specified by `fd'
starting from `offset' and continuing for `len' bytes.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex posix_fadvise() (στη μονάδα os)
@anchor{library/os os posix_fadvise}@anchor{114c}
@deffn {Συνάρτηση} os.posix_fadvise (fd, offset, len, advice, /)

Announces an intention to access data in a specific pattern thus allowing
the kernel to make optimizations.
The advice applies to the region of the file specified by `fd' starting at
`offset' and continuing for `len' bytes.
`advice' is one of @ref{3280,,POSIX_FADV_NORMAL}, @ref{3281,,POSIX_FADV_SEQUENTIAL},
@ref{3282,,POSIX_FADV_RANDOM}, @ref{3283,,POSIX_FADV_NOREUSE},
@ref{3284,,POSIX_FADV_WILLNEED} or @ref{3285,,POSIX_FADV_DONTNEED}.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex POSIX_FADV_NORMAL (στη μονάδα os)
@geindex POSIX_FADV_SEQUENTIAL (στη μονάδα os)
@geindex POSIX_FADV_RANDOM (στη μονάδα os)
@geindex POSIX_FADV_NOREUSE (στη μονάδα os)
@geindex POSIX_FADV_WILLNEED (στη μονάδα os)
@geindex POSIX_FADV_DONTNEED (στη μονάδα os)
@anchor{library/os os POSIX_FADV_NORMAL}@anchor{3280}
@deffn {Δεδομένα} os.POSIX_FADV_NORMAL
@anchor{library/os os POSIX_FADV_SEQUENTIAL}@anchor{3281}
@deffnx {Δεδομένα} os.POSIX_FADV_SEQUENTIAL
@anchor{library/os os POSIX_FADV_RANDOM}@anchor{3282}
@deffnx {Δεδομένα} os.POSIX_FADV_RANDOM
@anchor{library/os os POSIX_FADV_NOREUSE}@anchor{3283}
@deffnx {Δεδομένα} os.POSIX_FADV_NOREUSE
@anchor{library/os os POSIX_FADV_WILLNEED}@anchor{3284}
@deffnx {Δεδομένα} os.POSIX_FADV_WILLNEED
@anchor{library/os os POSIX_FADV_DONTNEED}@anchor{3285}
@deffnx {Δεδομένα} os.POSIX_FADV_DONTNEED

Flags that can be used in `advice' in @ref{114c,,posix_fadvise()} that specify
the access pattern that is likely to be used.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex pread() (στη μονάδα os)
@anchor{library/os os pread}@anchor{f1c}
@deffn {Συνάρτηση} os.pread (fd, n, offset, /)

Read at most `n' bytes from file descriptor `fd' at a position of `offset',
leaving the file offset unchanged.

Return a bytestring containing the bytes read. If the end of the file
referred to by `fd' has been reached, an empty bytes object is returned.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex posix_openpt() (στη μονάδα os)
@anchor{library/os os posix_openpt}@anchor{1c05}
@deffn {Συνάρτηση} 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{12aa,,non-inheritable}.
If the value @ref{1424,,O_CLOEXEC} is available on the system, it is added to
`oflag'.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.13.

@end deffn

@geindex preadv() (στη μονάδα os)
@anchor{library/os os preadv}@anchor{f1a}
@deffn {Συνάρτηση} os.preadv (fd, buffers, offset, flags=0, /)

Read from a file descriptor `fd' at a position of `offset' into mutable
@ref{436,,bytes-like objects} `buffers', leaving the file
offset unchanged.  Transfer data into each buffer until it is full and then
move on to the next buffer in the sequence to hold the rest of the data.

The flags argument contains a bitwise OR of zero or more of the following
flags:


@itemize -

@item 
@ref{3286,,RWF_HIPRI}

@item 
@ref{3287,,RWF_NOWAIT}

@item 
@ref{19f6,,RWF_DONTCACHE}
@end itemize

Return the total number of bytes actually read which can be less than the
total capacity of all the objects.

The operating system may set a limit (@ref{1b0d,,sysconf()} value
@code{'SC_IOV_MAX'}) on the number of buffers that can be used.

Combine the functionality of @ref{f1b,,os.readv()} and @ref{f1c,,os.pread()}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Using flags requires Linux >= 4.6.


Added in version 3.7.

@end deffn

@geindex RWF_NOWAIT (στη μονάδα os)
@anchor{library/os os RWF_NOWAIT}@anchor{3287}
@deffn {Δεδομένα} os.RWF_NOWAIT

Do not wait for data which is not immediately available. If this flag is
specified, the system call will return instantly if it would have to read
data from the backing storage or wait for a lock.

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{28f9,,errno.EAGAIN}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.14.


Added in version 3.7.

@end deffn

@geindex RWF_HIPRI (στη μονάδα os)
@anchor{library/os os RWF_HIPRI}@anchor{3286}
@deffn {Δεδομένα} os.RWF_HIPRI

High priority read/write. Allows block-based filesystems to use polling
of the device, which provides lower latency, but may use additional
resources.

Currently, on Linux, this feature is usable only on a file descriptor opened
using the @ref{327b,,O_DIRECT} flag.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.6.


Added in version 3.7.

@end deffn

@geindex RWF_DONTCACHE (στη μονάδα os)
@anchor{library/os os RWF_DONTCACHE}@anchor{19f6}
@deffn {Δεδομένα} os.RWF_DONTCACHE

Use uncached buffered IO.

@ref{232d,,Διαθεσιμότητα}: Linux >= 6.14


Added in version 3.15.

@end deffn

@geindex RWF_ATOMIC (στη μονάδα os)
@anchor{library/os os RWF_ATOMIC}@anchor{197b}
@deffn {Δεδομένα} os.RWF_ATOMIC

Write data atomically. Requires alignment to the device’s atomic write unit.

@ref{232d,,Διαθεσιμότητα}: Linux >= 6.11


Added in version 3.15.

@end deffn

@geindex ptsname() (στη μονάδα os)
@anchor{library/os os ptsname}@anchor{1c08}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.13.

@end deffn

@geindex pwrite() (στη μονάδα os)
@anchor{library/os os pwrite}@anchor{f1f}
@deffn {Συνάρτηση} os.pwrite (fd, str, offset, /)

Write the bytestring in `str' to file descriptor `fd' at position of
`offset', leaving the file offset unchanged.

Return the number of bytes actually written.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex pwritev() (στη μονάδα os)
@anchor{library/os os pwritev}@anchor{f1d}
@deffn {Συνάρτηση} 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{436,,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.

The flags argument contains a bitwise OR of zero or more of the following
flags:


@itemize -

@item 
@ref{3288,,RWF_DSYNC}

@item 
@ref{3289,,RWF_SYNC}

@item 
@ref{1f22,,RWF_APPEND}

@item 
@ref{19f6,,RWF_DONTCACHE}

@item 
@ref{197b,,RWF_ATOMIC}
@end itemize

Return the total number of bytes actually written.

The operating system may set a limit (@ref{1b0d,,sysconf()} value
@code{'SC_IOV_MAX'}) on the number of buffers that can be used.

Combine the functionality of @ref{f1e,,os.writev()} and @ref{f1f,,os.pwrite()}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Using flags requires Linux >= 4.6.


Added in version 3.7.

@end deffn

@geindex RWF_DSYNC (στη μονάδα os)
@anchor{library/os os RWF_DSYNC}@anchor{3288}
@deffn {Δεδομένα} os.RWF_DSYNC

Provide a per-write equivalent of the @ref{326f,,O_DSYNC} @ref{114b,,os.open()} flag.
This flag effect applies only to the data range written by the system call.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.7.


Added in version 3.7.

@end deffn

@geindex RWF_SYNC (στη μονάδα os)
@anchor{library/os os RWF_SYNC}@anchor{3289}
@deffn {Δεδομένα} os.RWF_SYNC

Provide a per-write equivalent of the @ref{3271,,O_SYNC} @ref{114b,,os.open()} flag.
This flag effect applies only to the data range written by the system call.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.7.


Added in version 3.7.

@end deffn

@geindex RWF_APPEND (στη μονάδα os)
@anchor{library/os os RWF_APPEND}@anchor{1f22}
@deffn {Δεδομένα} os.RWF_APPEND

Provide a per-write equivalent of the @ref{326c,,O_APPEND} @ref{114b,,os.open()}
flag. This flag is meaningful only for @ref{f1d,,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{232d,,Διαθεσιμότητα}: Linux >= 4.16.


Added in version 3.10.

@end deffn

@geindex read() (στη μονάδα os)
@anchor{library/os os read}@anchor{114e}
@deffn {Συνάρτηση} os.read (fd, n, /)

Read at most `n' bytes from file descriptor `fd'.

Return a bytestring containing the bytes read. If the end of the file
referred to by `fd' has been reached, an empty bytes object is returned.

@cartouche
@quotation Σημείωση 
This function is intended for low-level I/O and must be applied to a file
descriptor as returned by @ref{114b,,os.open()} or @ref{1d62,,pipe()}.  To read a
«file object» returned by the built-in function @ref{32b,,open()} or by
@ref{585,,popen()} or @ref{2571,,fdopen()}, or @ref{94a,,sys.stdin}, use its
@ref{225b,,read()} or @ref{16ce,,readline()} methods.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.5: If the system call is interrupted and the signal handler does not raise an
exception, the function now retries the system call instead of raising an
@ref{1141,,InterruptedError} exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).

@end deffn

@geindex readinto() (στη μονάδα os)
@anchor{library/os os readinto}@anchor{4eb}
@deffn {Συνάρτηση} os.readinto (fd, buffer, /)

Read from a file descriptor `fd' into a mutable
@ref{311,,buffer object} `buffer'.

The `buffer' should be mutable and @ref{436,,bytes-like}. On
success, returns the number of bytes read. Less bytes may be read than the
size of the buffer. The underlying system call will be retried when
interrupted by a signal, unless the signal handler raises an exception.
Other errors will not be retried and an error will be raised.

Returns 0 if `fd' is at end of file or if the provided `buffer' has
length 0 (which can be used to check for errors without reading data).
Never returns negative.

@cartouche
@quotation Σημείωση 
This function is intended for low-level I/O and must be applied to a file
descriptor as returned by @ref{114b,,os.open()} or @ref{1d62,,os.pipe()}.  To read a
«file object» returned by the built-in function @ref{32b,,open()}, or
@ref{94a,,sys.stdin}, use its member functions, for example
@ref{1ab9,,io.BufferedIOBase.readinto()}, @ref{16cd,,io.BufferedIOBase.read()}, or
@ref{225b,,io.TextIOBase.read()}
@end quotation
@end cartouche


Added in version 3.14.

@end deffn

@geindex sendfile() (στη μονάδα os)
@anchor{library/os os sendfile}@anchor{ed3}
@deffn {Συνάρτηση} os.sendfile (out_fd, in_fd, offset, count)

@deffnx {Συνάρτηση} 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}.

The first function notation is supported by all platforms that define
@code{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.

Cross-platform applications should not use `headers', `trailers' and `flags'
arguments.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.

@cartouche
@quotation Σημείωση 
For a higher-level wrapper of @code{sendfile()}, see
@ref{120e,,socket.socket.sendfile()}.
@end quotation
@end cartouche


Added in version 3.3.



Άλλαξε στην έκδοση 3.9: Parameters `out' and `in' was renamed to `out_fd' and `in_fd'.

@end deffn

@geindex SF_NODISKIO (στη μονάδα os)
@geindex SF_MNOWAIT (στη μονάδα os)
@geindex SF_SYNC (στη μονάδα os)
@anchor{library/os os SF_NODISKIO}@anchor{328a}
@deffn {Δεδομένα} os.SF_NODISKIO
@anchor{library/os os SF_MNOWAIT}@anchor{328b}
@deffnx {Δεδομένα} os.SF_MNOWAIT
@anchor{library/os os SF_SYNC}@anchor{328c}
@deffnx {Δεδομένα} os.SF_SYNC

Parameters to the @ref{ed3,,sendfile()} function, if the implementation supports
them.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.3.

@end deffn

@geindex SF_NOCACHE (στη μονάδα os)
@anchor{library/os os SF_NOCACHE}@anchor{328d}
@deffn {Δεδομένα} os.SF_NOCACHE

Parameter to the @ref{ed3,,sendfile()} function, if the implementation supports
it. The data won’t be cached in the virtual memory and will be freed afterwards.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.11.

@end deffn

@geindex set_blocking() (στη μονάδα os)
@anchor{library/os os set_blocking}@anchor{11ed}
@deffn {Συνάρτηση} os.set_blocking (fd, blocking, /)

Set the blocking mode of the specified file descriptor. Set the
@ref{11ee,,O_NONBLOCK} flag if blocking is @code{False}, clear the flag otherwise.

See also @ref{11ec,,get_blocking()} and @ref{3261,,socket.socket.setblocking()}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.

The function is limited on WASI, see @ref{1d67,,WebAssembly platforms} for more
information.

On Windows, this function is limited to pipes.


Added in version 3.5.



Άλλαξε στην έκδοση 3.12: Added support for pipes on Windows.

@end deffn

@geindex splice() (στη μονάδα os)
@anchor{library/os os splice}@anchor{bf2}
@deffn {Συνάρτηση} os.splice (src, dst, count, offset_src=None, offset_dst=None, flags=0)

Transfer `count' bytes from file descriptor `src', starting from offset
`offset_src', to file descriptor `dst', starting from offset `offset_dst'.

The splicing 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 
If @ref{328e,,SPLICE_F_MOVE} is specified,
the kernel is asked to move pages instead of copying,
but pages may still be copied if the kernel cannot move the pages from the pipe.

@item 
If @ref{328f,,SPLICE_F_NONBLOCK} is specified,
the kernel is asked to not block on I/O.
This makes the splice pipe operations nonblocking,
but splice may nevertheless block because the spliced file descriptors may block.

@item 
If @ref{3290,,SPLICE_F_MORE} is specified,
it hints to the kernel that more data will be coming in a subsequent splice.
@end itemize

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{53c,,OSError} is raised with
@ref{19ca,,errno} set to @ref{325f,,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. The copy is done as if
both files are opened as binary.

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.


@subsubheading Δείτε επίσης


The @code{splice(2)@footnote{https://manpages.debian.org/splice(2)}} man page.


@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.17 with glibc >= 2.5


Added in version 3.10.

@end deffn

@geindex SPLICE_F_MOVE (στη μονάδα os)
@geindex SPLICE_F_NONBLOCK (στη μονάδα os)
@geindex SPLICE_F_MORE (στη μονάδα os)
@anchor{library/os os SPLICE_F_MOVE}@anchor{328e}
@deffn {Δεδομένα} os.SPLICE_F_MOVE
@anchor{library/os os SPLICE_F_NONBLOCK}@anchor{328f}
@deffnx {Δεδομένα} os.SPLICE_F_NONBLOCK
@anchor{library/os os SPLICE_F_MORE}@anchor{3290}
@deffnx {Δεδομένα} os.SPLICE_F_MORE


Added in version 3.10.

@end deffn

@geindex readv() (στη μονάδα os)
@anchor{library/os os readv}@anchor{f1b}
@deffn {Συνάρτηση} os.readv (fd, buffers, /)

Read from a file descriptor `fd' into a number of mutable @ref{436,,bytes-like objects} `buffers'. Transfer data into each buffer until
it is full and then move on to the next buffer in the sequence to hold the
rest of the data.

Return the total number of bytes actually read which can be less than the
total capacity of all the objects.

The operating system may set a limit (@ref{1b0d,,sysconf()} value
@code{'SC_IOV_MAX'}) on the number of buffers that can be used.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex tcgetpgrp() (στη μονάδα os)
@anchor{library/os os tcgetpgrp}@anchor{3291}
@deffn {Συνάρτηση} os.tcgetpgrp (fd, /)

Return the process group associated with the terminal given by `fd' (an open
file descriptor as returned by @ref{114b,,os.open()}).

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex tcsetpgrp() (στη μονάδα os)
@anchor{library/os os tcsetpgrp}@anchor{3292}
@deffn {Συνάρτηση} os.tcsetpgrp (fd, pg, /)

Set the process group associated with the terminal given by `fd' (an open file
descriptor as returned by @ref{114b,,os.open()}) to `pg'.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex ttyname() (στη μονάδα os)
@anchor{library/os os ttyname}@anchor{3293}
@deffn {Συνάρτηση} os.ttyname (fd, /)

Return a string which specifies the terminal device associated with
file descriptor `fd'.  If `fd' is not associated with a terminal device, an
exception is raised.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex unlockpt() (στη μονάδα os)
@anchor{library/os os unlockpt}@anchor{1c07}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Unix, not WASI.


Added in version 3.13.

@end deffn

@geindex write() (στη μονάδα os)
@anchor{library/os os write}@anchor{1154}
@deffn {Συνάρτηση} os.write (fd, str, /)

Write the bytestring in `str' to file descriptor `fd'.

Return the number of bytes actually written.

@cartouche
@quotation Σημείωση 
This function is intended for low-level I/O and must be applied to a file
descriptor as returned by @ref{114b,,os.open()} or @ref{1d62,,pipe()}.  To write a «file
object» returned by the built-in function @ref{32b,,open()} or by @ref{585,,popen()} or
@ref{2571,,fdopen()}, or @ref{e9c,,sys.stdout} or @ref{d05,,sys.stderr}, use its
@ref{224a,,write()} method.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.5: If the system call is interrupted and the signal handler does not raise an
exception, the function now retries the system call instead of raising an
@ref{1141,,InterruptedError} exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).

@end deffn

@geindex writev() (στη μονάδα os)
@anchor{library/os os writev}@anchor{f1e}
@deffn {Συνάρτηση} os.writev (fd, buffers, /)

Write the contents of `buffers' to file descriptor `fd'. `buffers' must be
a sequence of @ref{436,,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.

Returns the total number of bytes actually written.

The operating system may set a limit (@ref{1b0d,,sysconf()} value
@code{'SC_IOV_MAX'}) on the number of buffers that can be used.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@menu
* Querying the size of a terminal:: 
* Inheritance of File Descriptors:: 

@end menu

@node Querying the size of a terminal,Inheritance of File Descriptors,,File Descriptor Operations
@anchor{library/os querying-the-size-of-a-terminal}@anchor{3294}@anchor{library/os terminal-size}@anchor{3295}
@subsubsection Querying the size of a terminal



Added in version 3.3.


@geindex get_terminal_size() (στη μονάδα os)
@anchor{library/os os get_terminal_size}@anchor{14ae}
@deffn {Συνάρτηση} os.get_terminal_size (fd=STDOUT_FILENO, /)

Return the size of the terminal window as @code{(columns, lines)},
tuple of type @ref{2f21,,terminal_size}.

The optional argument @code{fd} (default @code{STDOUT_FILENO}, or standard
output) specifies which file descriptor should be queried.

If the file descriptor is not connected to a terminal, an @ref{53c,,OSError}
is raised.

@ref{14af,,shutil.get_terminal_size()} is the high-level function which
should normally be used, @code{os.get_terminal_size} is the low-level
implementation.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.
@end deffn

@geindex terminal_size (κλάση σε os)
@anchor{library/os os terminal_size}@anchor{2f21}
@deffn {Κλάση} os.terminal_size

A subclass of tuple, holding @code{(columns, lines)} of the terminal window size.

@geindex columns (ιδιότητα της os.terminal_size)
@anchor{library/os os terminal_size columns}@anchor{3296}
@deffn {Ιδιότητα} columns

Width of the terminal window in characters.
@end deffn

@geindex lines (ιδιότητα της os.terminal_size)
@anchor{library/os os terminal_size lines}@anchor{3297}
@deffn {Ιδιότητα} lines

Height of the terminal window in characters.
@end deffn
@end deffn

@node Inheritance of File Descriptors,,Querying the size of a terminal,File Descriptor Operations
@anchor{library/os fd-inheritance}@anchor{12aa}@anchor{library/os inheritance-of-file-descriptors}@anchor{3298}
@subsubsection Inheritance of File Descriptors



Added in version 3.4.


A file descriptor has an «inheritable» flag which indicates if the file descriptor
can be inherited by child processes.  Since Python 3.4, file descriptors
created by Python are non-inheritable by default.

On UNIX, non-inheritable file descriptors are closed in child processes at the
execution of a new program, other file descriptors are inherited. Note that
non-inheritable file descriptors are still `inherited' by child processes on @ref{6bd,,os.fork()}.

On Windows, non-inheritable handles and file descriptors are closed in child
processes, except for standard streams (file descriptors 0, 1 and 2: stdin, stdout
and stderr), which are always inherited.  Using @ref{586,,spawn*} functions,
all inheritable handles and all inheritable file descriptors are inherited.
Using the @ref{df,,subprocess} module, all file descriptors except standard
streams are closed, and inheritable handles are only inherited if the
`close_fds' parameter is @code{False}.

On WebAssembly platforms, the file descriptor cannot be modified.

@geindex get_inheritable() (στη μονάδα os)
@anchor{library/os os get_inheritable}@anchor{12ab}
@deffn {Συνάρτηση} os.get_inheritable (fd, /)

Get the «inheritable» flag of the specified file descriptor (a boolean).
@end deffn

@geindex set_inheritable() (στη μονάδα os)
@anchor{library/os os set_inheritable}@anchor{12ac}
@deffn {Συνάρτηση} os.set_inheritable (fd, inheritable, /)

Set the «inheritable» flag of the specified file descriptor.
@end deffn

@geindex get_handle_inheritable() (στη μονάδα os)
@anchor{library/os os get_handle_inheritable}@anchor{12ad}
@deffn {Συνάρτηση} os.get_handle_inheritable (handle, /)

Get the «inheritable» flag of the specified handle (a boolean).

@ref{232d,,Διαθεσιμότητα}: Windows.
@end deffn

@geindex set_handle_inheritable() (στη μονάδα os)
@anchor{library/os os set_handle_inheritable}@anchor{12ae}
@deffn {Συνάρτηση} os.set_handle_inheritable (handle, inheritable, /)

Set the «inheritable» flag of the specified handle.

@ref{232d,,Διαθεσιμότητα}: Windows.
@end deffn

@node Files and Directories,Process Management,File Descriptor Operations,os — Miscellaneous operating system interfaces
@anchor{library/os files-and-directories}@anchor{3299}@anchor{library/os os-file-dir}@anchor{322f}
@subsubsection Files and Directories


On some Unix platforms, many of these functions support one or more of these
features:
@anchor{library/os path-fd}@anchor{f19}

@itemize *

@item 
`specifying a file descriptor:'
Normally the `path' argument provided to functions in the @code{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{14a9,,os.supports_fd}.
If this functionality is unavailable, using it will raise a
@ref{59a,,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{1496}

@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{14a3,,os.supports_dir_fd}.  If it’s unavailable,
using it will raise a @ref{59a,,NotImplementedError}.
@end itemize
@anchor{library/os follow-symlinks}@anchor{1497}

@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{14a4,,os.supports_follow_symlinks}.
If it’s unavailable, using it will raise a @ref{59a,,NotImplementedError}.
@end itemize

@geindex access() (στη μονάδα os)
@anchor{library/os os access}@anchor{1498}
@deffn {Συνάρτηση} os.access (path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)

Use the real uid/gid to test for access to `path'.  Note that most operations
will use the effective uid/gid, therefore this routine can be used in a
suid/sgid environment to test if the invoking user has the specified access to
`path'.  `mode' should be @ref{329a,,F_OK} to test the existence of `path', or it
can be the inclusive OR of one or more of @ref{329b,,R_OK}, @ref{329c,,W_OK}, and
@ref{329d,,X_OK} to test permissions.  Return @ref{fcc,,True} if access is allowed,
@ref{ef5,,False} if not. See the Unix man page @code{access(2)@footnote{https://manpages.debian.org/access(2)}} for more
information.

This function can support specifying @ref{1496,,paths relative to directory descriptors} and @ref{1497,,not following symlinks}.

If `effective_ids' is @code{True}, @code{access()} will perform its access
checks using the effective uid/gid instead of the real uid/gid.
`effective_ids' may not be supported on your platform; you can check whether
or not it is available using @ref{14aa,,os.supports_effective_ids}.  If it is
unavailable, using it will raise a @ref{59a,,NotImplementedError}.

@cartouche
@quotation Σημείωση 
Using @code{access()} to check if a user is authorized to e.g. open a file
before actually doing so using @ref{32b,,open()} creates a security hole,
because the user might exploit the short time interval between checking
and opening the file to manipulate it. It’s preferable to use @ref{329e,,EAFP}
techniques. For example:

@example
if os.access("myfile", os.R_OK):
    with open("myfile") as fp:
        return fp.read()
return "some default data"
@end example

is better written as:

@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 Σημείωση 
I/O operations may fail even when @code{access()} indicates that they would
succeed, particularly for operations on network filesystems which may have
permissions semantics beyond the usual POSIX permission-bit model.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: Added the `dir_fd', `effective_ids', and `follow_symlinks' parameters.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex F_OK (στη μονάδα os)
@geindex R_OK (στη μονάδα os)
@geindex W_OK (στη μονάδα os)
@geindex X_OK (στη μονάδα os)
@anchor{library/os os F_OK}@anchor{329a}
@deffn {Δεδομένα} os.F_OK
@anchor{library/os os R_OK}@anchor{329b}
@deffnx {Δεδομένα} os.R_OK
@anchor{library/os os W_OK}@anchor{329c}
@deffnx {Δεδομένα} os.W_OK
@anchor{library/os os X_OK}@anchor{329d}
@deffnx {Δεδομένα} os.X_OK

Values to pass as the `mode' parameter of @ref{1498,,access()} to test the
existence, readability, writability and executability of `path',
respectively.
@end deffn

@geindex chdir() (στη μονάδα os)
@anchor{library/os os chdir}@anchor{a02}
@deffn {Συνάρτηση} os.chdir (path)

@geindex directory;changing

Change the current working directory to `path'.

This function can support @ref{f19,,specifying a file descriptor}.  The
descriptor must refer to an opened directory, not an open file.

This function can raise @ref{53c,,OSError} and subclasses such as
@ref{243,,FileNotFoundError}, @ref{10f9,,PermissionError}, and @ref{1402,,NotADirectoryError}.

Raises an @ref{1e65,,auditing event} @code{os.chdir} with argument @code{path}.


Άλλαξε στην έκδοση 3.3: Added support for specifying `path' as a file descriptor
on some platforms.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex chflags() (στη μονάδα os)
@anchor{library/os os chflags}@anchor{1499}
@deffn {Συνάρτηση} os.chflags (path, flags, *, follow_symlinks=True)

Set the flags of `path' to the numeric `flags'. `flags' may take a combination
(bitwise OR) of the following values (as defined in the @ref{d9,,stat} module):


@itemize *

@item 
@ref{2ea5,,stat.UF_NODUMP}

@item 
@ref{2ea6,,stat.UF_IMMUTABLE}

@item 
@ref{2ea7,,stat.UF_APPEND}

@item 
@ref{2ea8,,stat.UF_OPAQUE}

@item 
@ref{2ea9,,stat.UF_NOUNLINK}

@item 
@ref{2eaa,,stat.UF_COMPRESSED}

@item 
@ref{2ead,,stat.UF_HIDDEN}

@item 
@ref{2eb1,,stat.SF_ARCHIVED}

@item 
@ref{2eb2,,stat.SF_IMMUTABLE}

@item 
@ref{2eb3,,stat.SF_APPEND}

@item 
@ref{2eb5,,stat.SF_NOUNLINK}

@item 
@ref{2eb6,,stat.SF_SNAPSHOT}
@end itemize

This function can support @ref{1497,,not following symlinks}.

Raises an @ref{1e65,,auditing event} @code{os.chflags} with arguments @code{path}, @code{flags}.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Άλλαξε στην έκδοση 3.3: Added the `follow_symlinks' parameter.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex chmod() (στη μονάδα os)
@anchor{library/os os chmod}@anchor{72c}
@deffn {Συνάρτηση} os.chmod (path, mode, *, dir_fd=None, follow_symlinks=True)

Change the mode of `path' to the numeric `mode'. `mode' may take one of the
following values (as defined in the @ref{d9,,stat} module) or bitwise ORed
combinations of them:


@itemize *

@item 
@ref{2e91,,stat.S_ISUID}

@item 
@ref{2e92,,stat.S_ISGID}

@item 
@ref{2e94,,stat.S_ENFMT}

@item 
@ref{2e95,,stat.S_ISVTX}

@item 
@ref{2ea1,,stat.S_IREAD}

@item 
@ref{2ea2,,stat.S_IWRITE}

@item 
@ref{2ea3,,stat.S_IEXEC}

@item 
@ref{2e96,,stat.S_IRWXU}

@item 
@ref{2e97,,stat.S_IRUSR}

@item 
@ref{2e98,,stat.S_IWUSR}

@item 
@ref{2e99,,stat.S_IXUSR}

@item 
@ref{2e9a,,stat.S_IRWXG}

@item 
@ref{2e9b,,stat.S_IRGRP}

@item 
@ref{2e9c,,stat.S_IWGRP}

@item 
@ref{2e93,,stat.S_IXGRP}

@item 
@ref{2e9d,,stat.S_IRWXO}

@item 
@ref{2e9e,,stat.S_IROTH}

@item 
@ref{2e9f,,stat.S_IWOTH}

@item 
@ref{2ea0,,stat.S_IXOTH}
@end itemize

This function can support @ref{f19,,specifying a file descriptor},
@ref{1496,,paths relative to directory descriptors} and @ref{1497,,not following symlinks}.

@cartouche
@quotation Σημείωση 
Although Windows supports @code{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{1d67,,WebAssembly platforms} for more
information.
@end quotation
@end cartouche

Raises an @ref{1e65,,auditing event} @code{os.chmod} with arguments @code{path}, @code{mode}, @code{dir_fd}.


Άλλαξε στην έκδοση 3.3: Added support for specifying `path' as an open file descriptor,
and the `dir_fd' and `follow_symlinks' arguments.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.13: Added support for a file descriptor and the `follow_symlinks' argument
on Windows.

@end deffn

@geindex chown() (στη μονάδα os)
@anchor{library/os os chown}@anchor{149a}
@deffn {Συνάρτηση} os.chown (path, uid, gid, *, dir_fd=None, follow_symlinks=True)

Change the owner and group id of `path' to the numeric `uid' and `gid'.  To
leave one of the ids unchanged, set it to -1.

This function can support @ref{f19,,specifying a file descriptor},
@ref{1496,,paths relative to directory descriptors} and @ref{1497,,not following symlinks}.

See @ref{74b,,shutil.chown()} for a higher-level function that accepts names in
addition to numeric ids.

Raises an @ref{1e65,,auditing event} @code{os.chown} with arguments @code{path}, @code{uid}, @code{gid}, @code{dir_fd}.

@ref{232d,,Διαθεσιμότητα}: Unix.

The function is limited on WASI, see @ref{1d67,,WebAssembly platforms} for more
information.


Άλλαξε στην έκδοση 3.3: Added support for specifying `path' as an open file descriptor,
and the `dir_fd' and `follow_symlinks' arguments.



Άλλαξε στην έκδοση 3.6: Supports a @ref{79f,,path-like object}.

@end deffn

@geindex chroot() (στη μονάδα os)
@anchor{library/os os chroot}@anchor{1f70}
@deffn {Συνάρτηση} os.chroot (path)

Change the root directory of the current process to `path'.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex fchdir() (στη μονάδα os)
@anchor{library/os os fchdir}@anchor{1142}
@deffn {Συνάρτηση} os.fchdir (fd)

Change the current working directory to the directory represented by the file
descriptor `fd'.  The descriptor must refer to an opened directory, not an
open file.  As of Python 3.3, this is equivalent to @code{os.chdir(fd)}.

Raises an @ref{1e65,,auditing event} @code{os.chdir} with argument @code{path}.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex getcwd() (στη μονάδα os)
@anchor{library/os os getcwd}@anchor{1b26}
@deffn {Συνάρτηση} os.getcwd ()

Return a string representing the current working directory.
@end deffn

@geindex getcwdb() (στη μονάδα os)
@anchor{library/os os getcwdb}@anchor{e51}
@deffn {Συνάρτηση} os.getcwdb ()

Return a bytestring representing the current working directory.


Άλλαξε στην έκδοση 3.8: The 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.

@end deffn

@geindex lchflags() (στη μονάδα os)
@anchor{library/os os lchflags}@anchor{329f}
@deffn {Συνάρτηση} os.lchflags (path, flags)

Set the flags of `path' to the numeric `flags', like @ref{1499,,chflags()}, but do
not follow symbolic links.  As of Python 3.3, this is equivalent to
@code{os.chflags(path, flags, follow_symlinks=False)}.

Raises an @ref{1e65,,auditing event} @code{os.chflags} with arguments @code{path}, @code{flags}.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex lchmod() (στη μονάδα os)
@anchor{library/os os lchmod}@anchor{72b}
@deffn {Συνάρτηση} os.lchmod (path, mode)

Change the mode of `path' to the numeric `mode'. If path is a symlink, this
affects the symlink rather than the target.  See the docs for @ref{72c,,chmod()}
for possible values of `mode'.  As of Python 3.3, this is equivalent to
@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.

Raises an @ref{1e65,,auditing event} @code{os.chmod} with arguments @code{path}, @code{mode}, @code{dir_fd}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows, not Linux, FreeBSD >= 1.3, NetBSD >= 1.3, not OpenBSD


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.13: Added support on Windows.

@end deffn

@geindex lchown() (στη μονάδα os)
@anchor{library/os os lchown}@anchor{32a0}
@deffn {Συνάρτηση} os.lchown (path, uid, gid)

Change the owner and group id of `path' to the numeric `uid' and `gid'.  This
function will not follow symbolic links.  As of Python 3.3, this is equivalent
to @code{os.chown(path, uid, gid, follow_symlinks=False)}.

Raises an @ref{1e65,,auditing event} @code{os.chown} with arguments @code{path}, @code{uid}, @code{gid}, @code{dir_fd}.

@ref{232d,,Διαθεσιμότητα}: Unix.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex link() (στη μονάδα os)
@anchor{library/os os link}@anchor{149b}
@deffn {Συνάρτηση} os.link (src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True)

Create a hard link pointing to `src' named `dst'.

This function can support specifying `src_dir_fd' and/or `dst_dir_fd' to
supply @ref{1496,,paths relative to directory descriptors}, and @ref{1497,,not following symlinks}.
The default value of `follow_symlinks' is @code{False} on Windows.

Raises an @ref{1e65,,auditing event} @code{os.link} with arguments @code{src}, @code{dst}, @code{src_dir_fd}, @code{dst_dir_fd}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.


Άλλαξε στην έκδοση 3.2: Added Windows support.



Άλλαξε στην έκδοση 3.3: Added the `src_dir_fd', `dst_dir_fd', and `follow_symlinks' parameters.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object} for `src' and `dst'.

@end deffn

@geindex listdir() (στη μονάδα os)
@anchor{library/os os listdir}@anchor{14a6}
@deffn {Συνάρτηση} 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' may be a @ref{79f,,path-like object}.  If `path' is of type @code{bytes}
(directly or indirectly through the @ref{100f,,PathLike} interface),
the filenames returned will also be of type @code{bytes};
in all other circumstances, they will be of type @code{str}.

This function can also support @ref{f19,,specifying a file descriptor}; the file descriptor must refer to a directory.

Raises an @ref{1e65,,auditing event} @code{os.listdir} with argument @code{path}.

@cartouche
@quotation Σημείωση 
To encode @code{str} filenames to @code{bytes}, use @ref{1013,,fsencode()}.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης


The @ref{e23,,scandir()} function returns directory entries along with
file attribute information, giving better performance for many
common use cases.



Άλλαξε στην έκδοση 3.2: The `path' parameter became optional.



Άλλαξε στην έκδοση 3.3: Added support for specifying `path' as an open file descriptor.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.15: @code{os.listdir(-1)} now fails with @code{OSError(errno.EBADF)} rather than
listing the current directory.

@end deffn

@geindex listdrives() (στη μονάδα os)
@anchor{library/os os listdrives}@anchor{8ae}
@deffn {Συνάρτηση} 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{53c,,OSError} if an error occurs collecting the drive
names.

Raises an @ref{1e65,,auditing event} @code{os.listdrives} with no arguments.

@ref{232d,,Διαθεσιμότητα}: Windows


Added in version 3.12.

@end deffn

@geindex listmounts() (στη μονάδα os)
@anchor{library/os os listmounts}@anchor{8b0}
@deffn {Συνάρτηση} 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{8af,,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{53c,,OSError} if the volume is not recognized or if an error
occurs collecting the paths.

Raises an @ref{1e65,,auditing event} @code{os.listmounts} with argument @code{volume}.

@ref{232d,,Διαθεσιμότητα}: Windows


Added in version 3.12.

@end deffn

@geindex listvolumes() (στη μονάδα os)
@anchor{library/os os listvolumes}@anchor{8af}
@deffn {Συνάρτηση} 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{8b0,,os.listmounts()}.

May raise @ref{53c,,OSError} if an error occurs collecting the volumes.

Raises an @ref{1e65,,auditing event} @code{os.listvolumes} with no arguments.

@ref{232d,,Διαθεσιμότητα}: Windows


Added in version 3.12.

@end deffn

@geindex lstat() (στη μονάδα os)
@anchor{library/os os lstat}@anchor{8b1}
@deffn {Συνάρτηση} os.lstat (path, *, dir_fd=None)

Perform the equivalent of an @code{lstat()} system call on the given path.
Similar to @ref{4f5,,stat()}, but does not follow symbolic links. Return a
@ref{1863,,stat_result} object.

On platforms that do not support symbolic links, this is an alias for
@ref{4f5,,stat()}.

As of Python 3.3, this is equivalent to @code{os.stat(path, dir_fd=dir_fd,
follow_symlinks=False)}.

This function can also support @ref{1496,,paths relative to directory descriptors}.


@subsubheading Δείτε επίσης


The @ref{4f5,,stat()} function.



Άλλαξε στην έκδοση 3.2: Added support for Windows 6.0 (Vista) symbolic links.



Άλλαξε στην έκδοση 3.3: Added the `dir_fd' parameter.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 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{4f5,,stat()}.

@end deffn

@geindex mkdir() (στη μονάδα os)
@anchor{library/os os mkdir}@anchor{72e}
@deffn {Συνάρτηση} os.mkdir (path, mode=0o777, *, dir_fd=None)

Create a directory named `path' with numeric mode `mode'.

If the directory already exists, @ref{13c9,,FileExistsError} is raised. If a parent
directory in the path does not exist, @ref{243,,FileNotFoundError} is raised.
@anchor{library/os mkdir-modebits}@anchor{32a1}
On some systems, `mode' is ignored.  Where it is used, the current umask
value is first masked out.  If bits other than the last 9 (i.e. the last 3
digits of the octal representation of the `mode') are set, their meaning is
platform-dependent.  On some platforms, they are ignored and you should call
@ref{72c,,chmod()} explicitly to set them.

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.

This function can also support @ref{1496,,paths relative to directory descriptors}.

It is also possible to create temporary directories; see the
@ref{e9,,tempfile} module’s @ref{730,,tempfile.mkdtemp()} function.

Raises an @ref{1e65,,auditing event} @code{os.mkdir} with arguments @code{path}, @code{mode}, @code{dir_fd}.


Άλλαξε στην έκδοση 3.3: Added the `dir_fd' parameter.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.13: Windows now handles a `mode' of @code{0o700}.

@end deffn

@geindex makedirs() (στη μονάδα os)
@anchor{library/os os makedirs}@anchor{72f}
@deffn {Συνάρτηση} os.makedirs (name, mode=0o777, exist_ok=False)

@geindex directory;creating
@geindex UNC paths;and os.makedirs()

Recursive directory creation function.  Like @ref{72e,,mkdir()}, but makes all
intermediate-level directories needed to contain the leaf directory.

The `mode' parameter is passed to @ref{72e,,mkdir()} for creating the leaf
directory; see @ref{32a1,,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 @code{makedirs()}.  The
file permission bits of existing parent directories are not changed.

If `exist_ok' is @code{False} (the default), a @ref{13c9,,FileExistsError} is
raised if the target directory already exists.

@cartouche
@quotation Σημείωση 
@code{makedirs()} will become confused if the path elements to create
include @ref{32a2,,pardir} (eg. «..» on UNIX systems).
@end quotation
@end cartouche

This function handles UNC paths correctly.

Raises an @ref{1e65,,auditing event} @code{os.mkdir} with arguments @code{path}, @code{mode}, @code{dir_fd}.


Άλλαξε στην έκδοση 3.2: Added the `exist_ok' parameter.



Άλλαξε στην έκδοση 3.4.1: Before Python 3.4.1, if `exist_ok' was @code{True} and the directory existed,
@code{makedirs()} would still raise an error if `mode' did not match the
mode of the existing directory. Since this behavior was impossible to
implement safely, it was removed in Python 3.4.1. See bpo-21082@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21082}.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.7: The `mode' argument no longer affects the file permission bits of
newly created intermediate-level directories.

@end deffn

@geindex mkfifo() (στη μονάδα os)
@anchor{library/os os mkfifo}@anchor{1149}
@deffn {Συνάρτηση} os.mkfifo (path, mode=0o666, *, dir_fd=None)

Create a FIFO (a named pipe) named `path' with numeric mode `mode'.
The current umask value is first masked out from the mode.

This function can also support @ref{1496,,paths relative to directory descriptors}.

FIFOs are pipes that can be accessed like regular files.  FIFOs exist until they
are deleted (for example with @ref{14a1,,os.unlink()}). Generally, FIFOs are used as
rendezvous between «client» and «server» type processes: the server opens the
FIFO for reading, and the client opens it for writing.  Note that @code{mkfifo()}
doesn’t open the FIFO — it just creates the rendezvous point.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Άλλαξε στην έκδοση 3.3: Added the `dir_fd' parameter.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex mknod() (στη μονάδα os)
@anchor{library/os os mknod}@anchor{114a}
@deffn {Συνάρτηση} os.mknod (path, mode=0o600, device=0, *, dir_fd=None)

Create a filesystem node (file, device special file or named pipe) named
`path'. `mode' specifies both the permissions to use and the type of node
to be created, being combined (bitwise OR) with one of @ref{2e8c,,stat.S_IFREG},
@ref{2e8f,,stat.S_IFCHR}, @ref{2e8d,,stat.S_IFBLK}, and @ref{2e90,,stat.S_IFIFO}.
For @code{stat.S_IFCHR} and @code{stat.S_IFBLK}, `device' defines the
newly created device special file (probably using
@ref{1b73,,os.makedev()}), otherwise it is ignored.

This function can also support @ref{1496,,paths relative to directory descriptors}.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.


Άλλαξε στην έκδοση 3.3: Added the `dir_fd' parameter.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex major() (στη μονάδα os)
@anchor{library/os os major}@anchor{1b71}
@deffn {Συνάρτηση} os.major (device, /)

Extract the device major number from a raw device number (usually the
@ref{32a3,,st_dev} or @ref{19f8,,st_rdev} field from @code{stat}).
@end deffn

@geindex minor() (στη μονάδα os)
@anchor{library/os os minor}@anchor{1b72}
@deffn {Συνάρτηση} os.minor (device, /)

Extract the device minor number from a raw device number (usually the
@ref{32a3,,st_dev} or @ref{19f8,,st_rdev} field from @code{stat}).
@end deffn

@geindex makedev() (στη μονάδα os)
@anchor{library/os os makedev}@anchor{1b73}
@deffn {Συνάρτηση} os.makedev (major, minor, /)

Compose a raw device number from the major and minor device numbers.
@end deffn

@geindex NODEV (στη μονάδα os)
@anchor{library/os os NODEV}@anchor{19f9}
@deffn {Δεδομένα} os.NODEV

Non-existent device.


Added in version 3.15.

@end deffn

@geindex pathconf() (στη μονάδα os)
@anchor{library/os os pathconf}@anchor{14a7}
@deffn {Συνάρτηση} os.pathconf (path, name)

Return system configuration information relevant to a named file. `name'
specifies the configuration value to retrieve; it may be a string which is the
name of a defined system value; these names are specified in a number of
standards (POSIX.1, Unix 95, Unix 98, and others).  Some platforms define
additional names as well.  The names known to the host operating system are
given in the @code{pathconf_names} dictionary.  For configuration variables not
included in that mapping, passing an integer for `name' is also accepted.

If `name' is a string and is not known, @ref{277,,ValueError} is raised.  If a
specific value for `name' is not supported by the host system, even if it is
included in @code{pathconf_names}, an @ref{53c,,OSError} is raised with
@ref{1fc1,,errno.EINVAL} for the error number.

This function can support @ref{f19,,specifying a file descriptor}.

@ref{232d,,Διαθεσιμότητα}: Unix.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex pathconf_names (στη μονάδα os)
@anchor{library/os os pathconf_names}@anchor{32a4}
@deffn {Δεδομένα} os.pathconf_names

Dictionary mapping names accepted by @ref{14a7,,pathconf()} and @ref{3260,,fpathconf()} to
the integer values defined for those names by the host operating system.  This
can be used to determine the set of names known to the system.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex readlink() (στη μονάδα os)
@anchor{library/os os readlink}@anchor{ced}
@deffn {Συνάρτηση} os.readlink (path, *, dir_fd=None)

Return a string representing the path to which the symbolic link points.  The
result may be either an absolute or relative pathname; if it is relative, it
may be converted to an absolute pathname using
@code{os.path.join(os.path.dirname(path), result)}.

If the `path' is a string object (directly or indirectly through a
@ref{100f,,PathLike} interface), the result will also be a string object,
and the call may raise a UnicodeDecodeError. If the `path' is a bytes
object (direct or indirectly), the result will be a bytes object.

This function can also support @ref{1496,,paths relative to directory descriptors}.

When trying to resolve a path that may contain links, use
@ref{241,,realpath()} to properly handle recursion and platform
differences.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.


Άλλαξε στην έκδοση 3.2: Added support for Windows 6.0 (Vista) symbolic links.



Άλλαξε στην έκδοση 3.3: Added the `dir_fd' parameter.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object} on Unix.



Άλλαξε στην έκδοση 3.8: Accepts a @ref{79f,,path-like object} and a bytes object on 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() (στη μονάδα os)
@anchor{library/os os remove}@anchor{149c}
@deffn {Συνάρτηση} os.remove (path, *, dir_fd=None)

Remove (delete) the file `path'.  If `path' is a directory, an
@ref{53c,,OSError} is raised.  Use @ref{149f,,rmdir()} to remove directories.
If the file does not exist, a @ref{243,,FileNotFoundError} is raised.

This function can support @ref{1496,,paths relative to directory descriptors}.

On Windows, attempting to remove a file that is in use causes an exception to
be raised; on Unix, the directory entry is removed but the storage allocated
to the file is not made available until the original file is no longer in use.

This function is semantically identical to @ref{14a1,,unlink()}.

Raises an @ref{1e65,,auditing event} @code{os.remove} with arguments @code{path}, @code{dir_fd}.


Άλλαξε στην έκδοση 3.3: Added the `dir_fd' parameter.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex removedirs() (στη μονάδα os)
@anchor{library/os os removedirs}@anchor{32a5}
@deffn {Συνάρτηση} os.removedirs (name)

@geindex directory;deleting

Remove directories recursively.  Works like @ref{149f,,rmdir()} except that, if the
leaf directory is successfully removed, @code{removedirs()}  tries to
successively remove every parent directory mentioned in  `path' until an error
is raised (which is ignored, because it generally means that a parent directory
is not empty). For example, @code{os.removedirs('foo/bar/baz')} will first remove
the directory @code{'foo/bar/baz'}, and then remove @code{'foo/bar'} and @code{'foo'} if
they are empty. Raises @ref{53c,,OSError} if the leaf directory could not be
successfully removed.

Raises an @ref{1e65,,auditing event} @code{os.remove} with arguments @code{path}, @code{dir_fd}.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex rename() (στη μονάδα os)
@anchor{library/os os rename}@anchor{149d}
@deffn {Συνάρτηση} os.rename (src, dst, *, src_dir_fd=None, dst_dir_fd=None)

Rename the file or directory `src' to `dst'. If `dst' exists, the operation
will fail with an @ref{53c,,OSError} subclass in a number of cases:

On Windows, if `dst' exists a @ref{13c9,,FileExistsError} is always raised.
The operation may fail if `src' and `dst' are on different filesystems. Use
@ref{e20,,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{1401,,IsADirectoryError} or a @ref{1402,,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{53c,,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).

This function can support specifying `src_dir_fd' and/or `dst_dir_fd' to
supply @ref{1496,,paths relative to directory descriptors}.

If you want cross-platform overwriting of the destination, use @ref{149e,,replace()}.

Raises an @ref{1e65,,auditing event} @code{os.rename} with arguments @code{src}, @code{dst}, @code{src_dir_fd}, @code{dst_dir_fd}.


Άλλαξε στην έκδοση 3.3: Added the `src_dir_fd' and `dst_dir_fd' parameters.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object} for `src' and `dst'.

@end deffn

@geindex renames() (στη μονάδα os)
@anchor{library/os os renames}@anchor{32a6}
@deffn {Συνάρτηση} os.renames (old, new)

Recursive directory or file renaming function. Works like @ref{149d,,rename()}, except
creation of any intermediate directories needed to make the new pathname good is
attempted first. After the rename, directories corresponding to rightmost path
segments of the old name will be pruned away using @ref{32a5,,removedirs()}.

@cartouche
@quotation Σημείωση 
This function can fail with the new directory structure made if you lack
permissions needed to remove the leaf directory or file.
@end quotation
@end cartouche

Raises an @ref{1e65,,auditing event} @code{os.rename} with arguments @code{src}, @code{dst}, @code{src_dir_fd}, @code{dst_dir_fd}.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object} for `old' and `new'.

@end deffn

@geindex replace() (στη μονάδα os)
@anchor{library/os os replace}@anchor{149e}
@deffn {Συνάρτηση} 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{53c,,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).

This function can support specifying `src_dir_fd' and/or `dst_dir_fd' to
supply @ref{1496,,paths relative to directory descriptors}.

Raises an @ref{1e65,,auditing event} @code{os.rename} with arguments @code{src}, @code{dst}, @code{src_dir_fd}, @code{dst_dir_fd}.


Added in version 3.3.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object} for `src' and `dst'.

@end deffn

@geindex rmdir() (στη μονάδα os)
@anchor{library/os os rmdir}@anchor{149f}
@deffn {Συνάρτηση} os.rmdir (path, *, dir_fd=None)

Remove (delete) the directory `path'.  If the directory does not exist or is
not empty, a @ref{243,,FileNotFoundError} or an @ref{53c,,OSError} is raised
respectively.  In order to remove whole directory trees,
@ref{335,,shutil.rmtree()} can be used.

This function can support @ref{1496,,paths relative to directory descriptors}.

Raises an @ref{1e65,,auditing event} @code{os.rmdir} with arguments @code{path}, @code{dir_fd}.


Άλλαξε στην έκδοση 3.3: Added the `dir_fd' parameter.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex scandir() (στη μονάδα os)
@anchor{library/os os scandir}@anchor{e23}
@deffn {Συνάρτηση} os.scandir (path='.')

Return an iterator of @ref{8ac,,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.

Using @code{scandir()} instead of @ref{14a6,,listdir()} can significantly
increase the performance of code that also needs file type or file
attribute information, because @ref{8ac,,os.DirEntry} objects expose this
information if the operating system provides it when scanning a directory.
All @code{os.DirEntry} methods may perform a system call, but
@ref{32a7,,is_dir()} and @ref{113d,,is_file()} usually only
require a system call for symbolic links; @ref{1c71,,os.DirEntry.stat()}
always requires a system call on Unix but only requires one for
symbolic links on Windows.

`path' may be a @ref{79f,,path-like object}.  If `path' is of type @code{bytes}
(directly or indirectly through the @ref{100f,,PathLike} interface),
the type of the @ref{32a8,,name} and @ref{1c00,,path}
attributes of each @ref{8ac,,os.DirEntry} will be @code{bytes}; in all other
circumstances, they will be of type @code{str}.

This function can also support @ref{f19,,specifying a file descriptor}; the file descriptor must refer to a directory.

Raises an @ref{1e65,,auditing event} @code{os.scandir} with argument @code{path}.

The @code{scandir()} iterator supports the @ref{478,,context manager} protocol
and has the following method:

@geindex close() (μέθοδος της os.scandir)
@anchor{library/os os scandir close}@anchor{107a}
@deffn {Μέθοδος} scandir.close ()

Close the iterator and free acquired resources.

This is called automatically when the iterator is exhausted or garbage
collected, or when an error happens during iterating.  However it
is advisable to call it explicitly or use the @ref{20a,,with}
statement.


Added in version 3.6.

@end deffn

The following example shows a simple use of @code{scandir()} to display all
the files (excluding directories) in the given `path' that don’t start with
@code{'.'}. The @code{entry.is_file()} call will generally not make an additional
system call:

@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 Σημείωση 
On Unix-based systems, @code{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


Added in version 3.5.



Άλλαξε στην έκδοση 3.6: Added support for the @ref{478,,context manager} protocol and the
@ref{107a,,close()} method.  If a @code{scandir()} iterator is neither
exhausted nor explicitly closed a @ref{74f,,ResourceWarning} will be emitted
in its destructor.

The function accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.7: Added support for @ref{f19,,file descriptors} on Unix.



Άλλαξε στην έκδοση 3.15: @code{os.scandir(-1)} now fails with @code{OSError(errno.EBADF)} rather than
listing the current directory.

@end deffn

@geindex DirEntry (κλάση σε os)
@anchor{library/os os DirEntry}@anchor{8ac}
@deffn {Κλάση} os.DirEntry

Object yielded by @ref{e23,,scandir()} to expose the file path and other file
attributes of a directory entry.

@ref{e23,,scandir()} will provide as much of this information as possible without
making additional system calls. When a @code{stat()} or @code{lstat()} system call
is made, the @code{os.DirEntry} object will cache the result.

@code{os.DirEntry} instances are not intended to be stored in long-lived data
structures; if you know the file metadata has changed or if a long time has
elapsed since calling @ref{e23,,scandir()}, call @code{os.stat(entry.path)} to fetch
up-to-date information.

Because the @code{os.DirEntry} methods can make operating system calls, they may
also raise @ref{53c,,OSError}. If you need very fine-grained
control over errors, you can catch @code{OSError} when calling one of the
@code{os.DirEntry} methods and handle as appropriate.

To be directly usable as a @ref{79f,,path-like object}, @code{os.DirEntry}
implements the @ref{100f,,PathLike} interface.

Attributes and methods on a @code{os.DirEntry} instance are as follows:

@geindex name (ιδιότητα της os.DirEntry)
@anchor{library/os os DirEntry name}@anchor{32a8}
@deffn {Ιδιότητα} name

The entry’s base filename, relative to the @ref{e23,,scandir()} `path'
argument.

The @ref{3228,,name} attribute will be @code{bytes} if the @ref{e23,,scandir()}
`path' argument is of type @code{bytes} and @code{str} otherwise.  Use
@ref{1012,,fsdecode()} to decode byte filenames.
@end deffn

@geindex path (ιδιότητα της os.DirEntry)
@anchor{library/os os DirEntry path}@anchor{1c00}
@deffn {Ιδιότητα} path

The entry’s full path name: equivalent to @code{os.path.join(scandir_path,
entry.name)} where `scandir_path' is the @ref{e23,,scandir()} `path'
argument.  The path is only absolute if the @code{scandir()} `path'
argument was absolute.  If the @code{scandir()} `path'
argument was a @ref{f19,,file descriptor}, the @ref{a6,,path}
attribute is the same as the @ref{3228,,name} attribute.

The @ref{a6,,path} attribute will be @code{bytes} if the @ref{e23,,scandir()}
`path' argument is of type @code{bytes} and @code{str} otherwise.  Use
@ref{1012,,fsdecode()} to decode byte filenames.
@end deffn

@geindex inode() (μέθοδος της os.DirEntry)
@anchor{library/os os DirEntry inode}@anchor{1c53}
@deffn {Μέθοδος} inode ()

Return the inode number of the entry.

The result is cached on the @code{os.DirEntry} object. Use
@code{os.stat(entry.path, follow_symlinks=False).st_ino} to fetch up-to-date
information.

On the first, uncached call, a system call is required on Windows but
not on Unix.
@end deffn

@geindex is_dir() (μέθοδος της os.DirEntry)
@anchor{library/os os DirEntry is_dir}@anchor{32a7}
@deffn {Μέθοδος} is_dir (*, follow_symlinks=True)

Return @code{True} if this entry is a directory or a symbolic link pointing
to a directory; return @code{False} if the entry is or points to any other
kind of file, or if it doesn’t exist anymore.

If `follow_symlinks' is @code{False}, return @code{True} only if this entry
is a directory (without following symlinks); return @code{False} if the
entry is any other kind of file or if it doesn’t exist anymore.

The result is cached on the @code{os.DirEntry} object, with a separate cache
for `follow_symlinks' @code{True} and @code{False}. Call @ref{4f5,,os.stat()} along
with @ref{2e78,,stat.S_ISDIR()} to fetch up-to-date information.

On the first, uncached call, no system call is required in most cases.
Specifically, for non-symlinks, neither Windows or Unix require a system
call, except on certain Unix file systems, such as network file systems,
that return @code{dirent.d_type == DT_UNKNOWN}. If the entry is a symlink,
a system call will be required to follow the symlink unless
`follow_symlinks' is @code{False}.

This method can raise @ref{53c,,OSError}, such as @ref{10f9,,PermissionError},
but @ref{243,,FileNotFoundError} is caught and not raised.
@end deffn

@geindex is_file() (μέθοδος της os.DirEntry)
@anchor{library/os os DirEntry is_file}@anchor{113d}
@deffn {Μέθοδος} is_file (*, follow_symlinks=True)

Return @code{True} if this entry is a file or a symbolic link pointing to a
file; return @code{False} if the entry is or points to a directory or other
non-file entry, or if it doesn’t exist anymore.

If `follow_symlinks' is @code{False}, return @code{True} only if this entry
is a file (without following symlinks); return @code{False} if the entry is
a directory or other non-file entry, or if it doesn’t exist anymore.

The result is cached on the @code{os.DirEntry} object. Caching, system calls
made, and exceptions raised are as per @ref{32a7,,is_dir()}.
@end deffn

@geindex is_symlink() (μέθοδος της os.DirEntry)
@anchor{library/os os DirEntry is_symlink}@anchor{32a9}
@deffn {Μέθοδος} is_symlink ()

Return @code{True} if this entry is a symbolic link (even if broken);
return @code{False} if the entry points to a directory or any kind of file,
or if it doesn’t exist anymore.

The result is cached on the @code{os.DirEntry} object. Call
@ref{dd0,,os.path.islink()} to fetch up-to-date information.

On the first, uncached call, no system call is required in most cases.
Specifically, neither Windows or Unix require a system call, except on
certain Unix file systems, such as network file systems, that return
@code{dirent.d_type == DT_UNKNOWN}.

This method can raise @ref{53c,,OSError}, such as @ref{10f9,,PermissionError},
but @ref{243,,FileNotFoundError} is caught and not raised.
@end deffn

@geindex is_junction() (μέθοδος της os.DirEntry)
@anchor{library/os os DirEntry is_junction}@anchor{8ad}
@deffn {Μέθοδος} 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{8b3,,os.path.isjunction()} to fetch up-to-date information.


Added in version 3.12.

@end deffn

@geindex stat() (μέθοδος της os.DirEntry)
@anchor{library/os os DirEntry stat}@anchor{1c71}
@deffn {Μέθοδος} stat (*, follow_symlinks=True)

Return a @ref{1863,,stat_result} object for this entry. This method
follows symbolic links by default; to stat a symbolic link add the
@code{follow_symlinks=False} argument.

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).

On Windows, the @code{st_ino}, @code{st_dev} and @code{st_nlink} attributes of the
@ref{1863,,stat_result} are always set to zero. Call @ref{4f5,,os.stat()} to
get these attributes.

The result is cached on the @code{os.DirEntry} object, with a separate cache
for `follow_symlinks' @code{True} and @code{False}. Call @ref{4f5,,os.stat()} to
fetch up-to-date information.
@end deffn

Note that there is a nice correspondence between several attributes
and methods of @code{os.DirEntry} and of @ref{4ee,,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.


Added in version 3.5.



Άλλαξε στην έκδοση 3.6: Added support for the @ref{100f,,PathLike} interface.  Added support
for @ref{1c7,,bytes} paths on Windows.



Άλλαξε στην έκδοση 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() (στη μονάδα os)
@anchor{library/os os stat}@anchor{4f5}
@deffn {Συνάρτηση} os.stat (path, *, dir_fd=None, follow_symlinks=True)

Get the status of a file or a file descriptor. Perform the equivalent of a
@code{stat()} system call on the given path. `path' may be specified as
either a string or bytes – directly or indirectly through the @ref{100f,,PathLike}
interface – or as an open file descriptor. Return a @ref{1863,,stat_result}
object.

This function normally follows symlinks; to stat a symlink add the argument
@code{follow_symlinks=False}, or use @ref{8b1,,lstat()}.

This function can support @ref{f19,,specifying a file descriptor} and
@ref{1497,,not following symlinks}.

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{241,,os.path.realpath()} function to resolve the path name as far as
possible and call @ref{8b1,,lstat()} on the result. This does not apply to
dangling symlinks or junction points, which will raise the usual exceptions.

@geindex module;stat

Example:

@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 Δείτε επίσης


@ref{1145,,fstat()} and @ref{8b1,,lstat()} functions.



Άλλαξε στην έκδοση 3.3: Added the `dir_fd' and `follow_symlinks' parameters,
specifying a file descriptor instead of a path.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 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 (κλάση σε os)
@anchor{library/os os stat_result}@anchor{1863}
@deffn {Κλάση} os.stat_result

Object whose attributes correspond roughly to the members of the
@code{stat} structure. It is used for the result of @ref{4f5,,os.stat()},
@ref{1145,,os.fstat()} and @ref{8b1,,os.lstat()}.

Attributes:

@geindex st_mode (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_mode}@anchor{dce}
@deffn {Ιδιότητα} st_mode

File mode: file type and file mode bits (permissions).
@end deffn

@geindex st_ino (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_ino}@anchor{32aa}
@deffn {Ιδιότητα} st_ino

Platform dependent, but if non-zero, uniquely identifies the
file for a given value of @code{st_dev}. Typically:


@itemize *

@item 
the inode number on Unix,

@item 
the file index@footnote{https://msdn.microsoft.com/en-us/library/aa363788} on
Windows
@end itemize
@end deffn

@geindex st_dev (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_dev}@anchor{32a3}
@deffn {Ιδιότητα} st_dev

Identifier of the device on which this file resides.
@end deffn

@geindex st_nlink (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_nlink}@anchor{32ab}
@deffn {Ιδιότητα} st_nlink

Number of hard links.
@end deffn

@geindex st_uid (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_uid}@anchor{32ac}
@deffn {Ιδιότητα} st_uid

User identifier of the file owner.
@end deffn

@geindex st_gid (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_gid}@anchor{32ad}
@deffn {Ιδιότητα} st_gid

Group identifier of the file owner.
@end deffn

@geindex st_size (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_size}@anchor{32ae}
@deffn {Ιδιότητα} st_size

Size of the file in bytes, if it is a regular file or a symbolic link.
The size of a symbolic link is the length of the pathname it contains,
without a terminating null byte.
@end deffn

Timestamps:

@geindex st_atime (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_atime}@anchor{32af}
@deffn {Ιδιότητα} st_atime

Time of most recent access expressed in seconds.
@end deffn

@geindex st_mtime (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_mtime}@anchor{313a}
@deffn {Ιδιότητα} st_mtime

Time of most recent content modification expressed in seconds.
@end deffn

@geindex st_ctime (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_ctime}@anchor{32b0}
@deffn {Ιδιότητα} st_ctime

Time of most recent metadata change expressed in seconds.


Άλλαξε στην έκδοση 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 (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_atime_ns}@anchor{32b1}
@deffn {Ιδιότητα} st_atime_ns

Time of most recent access expressed in nanoseconds as an integer.


Added in version 3.3.

@end deffn

@geindex st_mtime_ns (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_mtime_ns}@anchor{32b2}
@deffn {Ιδιότητα} st_mtime_ns

Time of most recent content modification expressed in nanoseconds as an
integer.


Added in version 3.3.

@end deffn

@geindex st_ctime_ns (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_ctime_ns}@anchor{32b3}
@deffn {Ιδιότητα} st_ctime_ns

Time of most recent metadata change expressed in nanoseconds as an
integer.


Added in version 3.3.



Άλλαξε στην έκδοση 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 (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_birthtime}@anchor{32b4}
@deffn {Ιδιότητα} st_birthtime

Time of file creation expressed in seconds. This attribute is not
always available, and may raise @ref{1a9,,AttributeError}.


Άλλαξε στην έκδοση 3.12: @code{st_birthtime} is now available on Windows.

@end deffn

@geindex st_birthtime_ns (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_birthtime_ns}@anchor{32b5}
@deffn {Ιδιότητα} st_birthtime_ns

Time of file creation expressed in nanoseconds as an integer.
This attribute is not always available, and may raise
@ref{1a9,,AttributeError}.


Added in version 3.12.

@end deffn

@cartouche
@quotation Σημείωση 
The exact meaning and resolution of the @ref{32af,,st_atime},
@ref{313a,,st_mtime}, @ref{32b0,,st_ctime} and @ref{32b4,,st_birthtime} attributes
depend on the operating system and the file system. For example, on
Windows systems using the FAT32 file systems, @code{st_mtime} has
2-second resolution, and @code{st_atime} has only 1-day resolution.
See your operating system documentation for details.

Similarly, although @ref{32b1,,st_atime_ns}, @ref{32b2,,st_mtime_ns},
@ref{32b3,,st_ctime_ns} and @ref{32b5,,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{32af,,st_atime}, @ref{313a,,st_mtime}, @ref{32b0,,st_ctime} and
@ref{32b4,,st_birthtime} cannot preserve all of it, and as such will be
slightly inexact. If you need the exact timestamps you should always use
@code{st_atime_ns}, @code{st_mtime_ns}, @code{st_ctime_ns} and
@code{st_birthtime_ns}.
@end quotation
@end cartouche

On some Unix systems (such as Linux), the following attributes may also be
available:

@geindex st_blocks (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_blocks}@anchor{32b6}
@deffn {Ιδιότητα} st_blocks

Number of 512-byte blocks allocated for file.
This may be smaller than @ref{32ae,,st_size}/512 when the file has holes.
@end deffn

@geindex st_blksize (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_blksize}@anchor{32b7}
@deffn {Ιδιότητα} st_blksize

«Preferred» blocksize for efficient file system I/O. Writing to a file in
smaller chunks may cause an inefficient read-modify-rewrite.
@end deffn

@geindex st_rdev (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_rdev}@anchor{19f8}
@deffn {Ιδιότητα} st_rdev

Type of device if an inode device.
@end deffn

@geindex st_flags (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_flags}@anchor{32b8}
@deffn {Ιδιότητα} st_flags

User defined flags for file.
@end deffn

On other Unix systems (such as FreeBSD), the following attributes may be
available (but may be only filled out if root tries to use them):

@geindex st_gen (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_gen}@anchor{32b9}
@deffn {Ιδιότητα} st_gen

File generation number.
@end deffn

On Solaris and derivatives, the following attributes may also be
available:

@geindex st_fstype (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_fstype}@anchor{f21}
@deffn {Ιδιότητα} st_fstype

String that uniquely identifies the type of the filesystem that
contains the file.
@end deffn

On macOS systems, the following attributes may also be available:

@geindex st_rsize (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_rsize}@anchor{32ba}
@deffn {Ιδιότητα} st_rsize

Real size of the file.
@end deffn

@geindex st_creator (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_creator}@anchor{32bb}
@deffn {Ιδιότητα} st_creator

Creator of the file.
@end deffn

@geindex st_type (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_type}@anchor{32bc}
@deffn {Ιδιότητα} st_type

File type.
@end deffn

On Windows systems, the following attributes are also available:

@geindex st_file_attributes (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_file_attributes}@anchor{11eb}
@deffn {Ιδιότητα} 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{d9,,stat} module.


Added in version 3.5.

@end deffn

@geindex st_reparse_tag (ιδιότητα της os.stat_result)
@anchor{library/os os stat_result st_reparse_tag}@anchor{dcf}
@deffn {Ιδιότητα} st_reparse_tag

When @ref{11eb,,st_file_attributes} has the @ref{2ec5,,FILE_ATTRIBUTE_REPARSE_POINT}
set, this field contains the tag identifying the type of reparse point.
See the @ref{2eca,,IO_REPARSE_TAG_*}
constants in the @ref{d9,,stat} module.
@end deffn

The standard module @ref{d9,,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 @code{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{dce,,st_mode}, @ref{32aa,,st_ino}, @ref{32a3,,st_dev}, @ref{32ab,,st_nlink},
@ref{32ac,,st_uid}, @ref{32ad,,st_gid}, @ref{32ae,,st_size}, @ref{32af,,st_atime},
@ref{313a,,st_mtime}, @ref{32b0,,st_ctime}. More items may be added at the end by
some implementations. For compatibility with older Python versions,
accessing @code{stat_result} as a tuple always returns integers.


Άλλαξε στην έκδοση 3.5: Windows now returns the file index as @ref{32aa,,st_ino} when
available.



Άλλαξε στην έκδοση 3.7: Added the @ref{f21,,st_fstype} member to Solaris/derivatives.



Άλλαξε στην έκδοση 3.8: Added the @ref{dcf,,st_reparse_tag} member on Windows.



Άλλαξε στην έκδοση 3.8: On Windows, the @ref{dce,,st_mode} member now identifies special
files as @ref{2e8f,,S_IFCHR}, @ref{2e90,,S_IFIFO} or
@ref{2e8d,,S_IFBLK} as appropriate.



Άλλαξε στην έκδοση 3.12: On Windows, @ref{32b0,,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{32b4,,st_birthtime} for the creation time.

On Windows, @ref{32aa,,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{19f8,,st_rdev} no longer returns a value. Previously
it would contain the same as @ref{32a3,,st_dev}, which was incorrect.

Added the @ref{32b4,,st_birthtime} member on Windows.

@end deffn

@geindex statx() (στη μονάδα os)
@anchor{library/os os statx}@anchor{23f}
@deffn {Συνάρτηση} os.statx (path, mask, *, flags=0, dir_fd=None, follow_symlinks=True)

Get the status of a file or file descriptor by performing a @code{statx()}
system call on the given path.

`path' is a @ref{79f,,path-like object} or an open file descriptor. `mask' is a
combination of the module-level @ref{32bd,,STATX_*} constants
specifying the information to retrieve. `flags' is a combination of the
module-level @ref{32be,,AT_STATX_*} constants and/or
@ref{32bf,,AT_NO_AUTOMOUNT}. Returns a @ref{32c0,,statx_result} object whose
@ref{32c1,,stx_mask} attribute specifies the information
actually retrieved (which may differ from `mask').

This function supports @ref{f19,,specifying a file descriptor},
@ref{1496,,paths relative to directory descriptors}, and
@ref{1497,,not following symlinks}.


@subsubheading Δείτε επίσης


The @code{statx(2)@footnote{https://manpages.debian.org/statx(2)}} man page.


@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28.


Added in version 3.15.

@end deffn

@geindex statx_result (κλάση σε os)
@anchor{library/os os statx_result}@anchor{32c0}
@deffn {Κλάση} os.statx_result

Information about a file returned by @ref{23f,,os.statx()}.

@code{statx_result} has the following attributes:

@geindex stx_atime (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_atime}@anchor{32c2}
@deffn {Ιδιότητα} stx_atime

Time of most recent access expressed in seconds.

Equal to @code{None} if @ref{32c3,,STATX_ATIME} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_atime_ns (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_atime_ns}@anchor{32c4}
@deffn {Ιδιότητα} stx_atime_ns

Time of most recent access expressed in nanoseconds as an integer.

Equal to @code{None} if @ref{32c3,,STATX_ATIME} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_atomic_write_segments_max (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_atomic_write_segments_max}@anchor{32c5}
@deffn {Ιδιότητα} stx_atomic_write_segments_max

Maximum iovecs for direct I/O with torn-write protection.

Equal to @code{None} if @ref{32c6,,STATX_WRITE_ATOMIC} is missing from
@ref{32c1,,stx_mask}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
userspace API headers >= 6.11.
@end deffn

@geindex stx_atomic_write_unit_max (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_atomic_write_unit_max}@anchor{32c7}
@deffn {Ιδιότητα} stx_atomic_write_unit_max

Maximum size for direct I/O with torn-write protection.

Equal to @code{None} if @ref{32c6,,STATX_WRITE_ATOMIC} is missing from
@ref{32c1,,stx_mask}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
userspace API headers >= 6.11.
@end deffn

@geindex stx_atomic_write_unit_max_opt (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_atomic_write_unit_max_opt}@anchor{32c8}
@deffn {Ιδιότητα} stx_atomic_write_unit_max_opt

Maximum optimized size for direct I/O with torn-write protection.

Equal to @code{None} if @ref{32c6,,STATX_WRITE_ATOMIC} is missing from
@ref{32c1,,stx_mask}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
userspace API headers >= 6.16.
@end deffn

@geindex stx_atomic_write_unit_min (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_atomic_write_unit_min}@anchor{32c9}
@deffn {Ιδιότητα} stx_atomic_write_unit_min

Minimum size for direct I/O with torn-write protection.

Equal to @code{None} if @ref{32c6,,STATX_WRITE_ATOMIC} is missing from
@ref{32c1,,stx_mask}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
userspace API headers >= 6.11.
@end deffn

@geindex stx_attributes (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_attributes}@anchor{2ecd}
@deffn {Ιδιότητα} stx_attributes

Bitmask of @ref{2ecf,,STATX_ATTR_*} constants
specifying the attributes of this file.
@end deffn

@geindex stx_attributes_mask (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_attributes_mask}@anchor{2ece}
@deffn {Ιδιότητα} stx_attributes_mask

A mask indicating which bits in @ref{2ecd,,stx_attributes} are supported by
the VFS and the filesystem.
@end deffn

@geindex stx_blksize (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_blksize}@anchor{32ca}
@deffn {Ιδιότητα} stx_blksize

«Preferred» blocksize for efficient file system I/O. Writing to a file in
smaller chunks may cause an inefficient read-modify-rewrite.
@end deffn

@geindex stx_blocks (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_blocks}@anchor{32cb}
@deffn {Ιδιότητα} stx_blocks

Number of 512-byte blocks allocated for file.
This may be smaller than @ref{32cc,,stx_size}/512 when the file has holes.

Equal to @code{None} if @ref{32cd,,STATX_BLOCKS} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_btime (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_btime}@anchor{32ce}
@deffn {Ιδιότητα} stx_btime

Time of file creation expressed in seconds.

Equal to @code{None} if @ref{32cf,,STATX_BTIME} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_btime_ns (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_btime_ns}@anchor{32d0}
@deffn {Ιδιότητα} stx_btime_ns

Time of file creation expressed in nanoseconds as an integer.

Equal to @code{None} if @ref{32cf,,STATX_BTIME} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_ctime (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_ctime}@anchor{32d1}
@deffn {Ιδιότητα} stx_ctime

Time of most recent metadata change expressed in seconds.

Equal to @code{None} if @ref{32d2,,STATX_CTIME} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_ctime_ns (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_ctime_ns}@anchor{32d3}
@deffn {Ιδιότητα} stx_ctime_ns

Time of most recent metadata change expressed in nanoseconds as an
integer.

Equal to @code{None} if @ref{32d2,,STATX_CTIME} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_dev (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_dev}@anchor{32d4}
@deffn {Ιδιότητα} stx_dev

Identifier of the device on which this file resides.
@end deffn

@geindex stx_dev_major (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_dev_major}@anchor{32d5}
@deffn {Ιδιότητα} stx_dev_major

Major number of the device on which this file resides.
@end deffn

@geindex stx_dev_minor (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_dev_minor}@anchor{32d6}
@deffn {Ιδιότητα} stx_dev_minor

Minor number of the device on which this file resides.
@end deffn

@geindex stx_dio_mem_align (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_dio_mem_align}@anchor{32d7}
@deffn {Ιδιότητα} stx_dio_mem_align

Direct I/O memory buffer alignment requirement.

Equal to @code{None} if @ref{32d8,,STATX_DIOALIGN} is missing from
@ref{32c1,,stx_mask}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
userspace API headers >= 6.1.
@end deffn

@geindex stx_dio_offset_align (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_dio_offset_align}@anchor{32d9}
@deffn {Ιδιότητα} stx_dio_offset_align

Direct I/O file offset alignment requirement.

Equal to @code{None} if @ref{32d8,,STATX_DIOALIGN} is missing from
@ref{32c1,,stx_mask}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
userspace API headers >= 6.1.
@end deffn

@geindex stx_dio_read_offset_align (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_dio_read_offset_align}@anchor{32da}
@deffn {Ιδιότητα} stx_dio_read_offset_align

Direct I/O file offset alignment requirement for reads.

Equal to @code{None} if @ref{32db,,STATX_DIO_READ_ALIGN} is missing from
@ref{32c1,,stx_mask}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
userspace API headers >= 6.14.
@end deffn

@geindex stx_gid (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_gid}@anchor{32dc}
@deffn {Ιδιότητα} stx_gid

Group identifier of the file owner.

Equal to @code{None} if @ref{32dd,,STATX_GID} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_ino (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_ino}@anchor{32de}
@deffn {Ιδιότητα} stx_ino

Inode number.

Equal to @code{None} if @ref{32df,,STATX_INO} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_mask (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_mask}@anchor{32c1}
@deffn {Ιδιότητα} stx_mask

Bitmask of @ref{32bd,,STATX_*} constants specifying the
information retrieved, which may differ from what was requested.
@end deffn

@geindex stx_mnt_id (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_mnt_id}@anchor{32e0}
@deffn {Ιδιότητα} stx_mnt_id

Mount identifier.

Equal to @code{None} if @ref{32e1,,STATX_MNT_ID} is missing from
@ref{32c1,,stx_mask}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
userspace API headers >= 5.8.
@end deffn

@geindex stx_mode (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_mode}@anchor{32e2}
@deffn {Ιδιότητα} stx_mode

File mode: file type and file mode bits (permissions).

Equal to @code{None} if @ref{32bd,,STATX_TYPE | STATX_MODE}
is missing from @ref{32c1,,stx_mask}.
@end deffn

@geindex stx_mtime (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_mtime}@anchor{32e3}
@deffn {Ιδιότητα} stx_mtime

Time of most recent content modification expressed in seconds.

Equal to @code{None} if @ref{32e4,,STATX_MTIME} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_mtime_ns (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_mtime_ns}@anchor{32e5}
@deffn {Ιδιότητα} stx_mtime_ns

Time of most recent content modification expressed in nanoseconds as an
integer.

Equal to @code{None} if @ref{32e4,,STATX_MTIME} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_nlink (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_nlink}@anchor{32e6}
@deffn {Ιδιότητα} stx_nlink

Number of hard links.

Equal to @code{None} if @ref{32e7,,STATX_NLINK} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_rdev (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_rdev}@anchor{32e8}
@deffn {Ιδιότητα} stx_rdev

Type of device if an inode device.
@end deffn

@geindex stx_rdev_major (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_rdev_major}@anchor{32e9}
@deffn {Ιδιότητα} stx_rdev_major

Major number of the device this file represents.
@end deffn

@geindex stx_rdev_minor (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_rdev_minor}@anchor{32ea}
@deffn {Ιδιότητα} stx_rdev_minor

Minor number of the device this file represents.
@end deffn

@geindex stx_size (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_size}@anchor{32cc}
@deffn {Ιδιότητα} stx_size

Size of the file in bytes, if it is a regular file or a symbolic link.
The size of a symbolic link is the length of the pathname it contains,
without a terminating null byte.

Equal to @code{None} if @ref{32eb,,STATX_SIZE} is missing from
@ref{32c1,,stx_mask}.
@end deffn

@geindex stx_subvol (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_subvol}@anchor{32ec}
@deffn {Ιδιότητα} stx_subvol

Subvolume identifier.

Equal to @code{None} if @ref{32ed,,STATX_SUBVOL} is missing from
@ref{32c1,,stx_mask}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
userspace API headers >= 6.10.
@end deffn

@geindex stx_uid (ιδιότητα της os.statx_result)
@anchor{library/os os statx_result stx_uid}@anchor{32ee}
@deffn {Ιδιότητα} stx_uid

User identifier of the file owner.

Equal to @code{None} if @ref{32ef,,STATX_UID} is missing from
@ref{32c1,,stx_mask}.
@end deffn


@subsubheading Δείτε επίσης


The @code{statx(2)@footnote{https://manpages.debian.org/statx(2)}} man page.


@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28.


Added in version 3.15.

@end deffn

@geindex STATX_TYPE (στη μονάδα os)
@geindex STATX_MODE (στη μονάδα os)
@geindex STATX_NLINK (στη μονάδα os)
@geindex STATX_UID (στη μονάδα os)
@geindex STATX_GID (στη μονάδα os)
@geindex STATX_ATIME (στη μονάδα os)
@geindex STATX_MTIME (στη μονάδα os)
@geindex STATX_CTIME (στη μονάδα os)
@geindex STATX_INO (στη μονάδα os)
@geindex STATX_SIZE (στη μονάδα os)
@geindex STATX_BLOCKS (στη μονάδα os)
@geindex STATX_BASIC_STATS (στη μονάδα os)
@geindex STATX_BTIME (στη μονάδα os)
@geindex STATX_MNT_ID (στη μονάδα os)
@geindex STATX_DIOALIGN (στη μονάδα os)
@geindex STATX_MNT_ID_UNIQUE (στη μονάδα os)
@geindex STATX_SUBVOL (στη μονάδα os)
@geindex STATX_WRITE_ATOMIC (στη μονάδα os)
@geindex STATX_DIO_READ_ALIGN (στη μονάδα os)
@anchor{library/os os STATX_TYPE}@anchor{32bd}
@deffn {Δεδομένα} os.STATX_TYPE
@anchor{library/os os STATX_MODE}@anchor{32f0}
@deffnx {Δεδομένα} os.STATX_MODE
@anchor{library/os os STATX_NLINK}@anchor{32e7}
@deffnx {Δεδομένα} os.STATX_NLINK
@anchor{library/os os STATX_UID}@anchor{32ef}
@deffnx {Δεδομένα} os.STATX_UID
@anchor{library/os os STATX_GID}@anchor{32dd}
@deffnx {Δεδομένα} os.STATX_GID
@anchor{library/os os STATX_ATIME}@anchor{32c3}
@deffnx {Δεδομένα} os.STATX_ATIME
@anchor{library/os os STATX_MTIME}@anchor{32e4}
@deffnx {Δεδομένα} os.STATX_MTIME
@anchor{library/os os STATX_CTIME}@anchor{32d2}
@deffnx {Δεδομένα} os.STATX_CTIME
@anchor{library/os os STATX_INO}@anchor{32df}
@deffnx {Δεδομένα} os.STATX_INO
@anchor{library/os os STATX_SIZE}@anchor{32eb}
@deffnx {Δεδομένα} os.STATX_SIZE
@anchor{library/os os STATX_BLOCKS}@anchor{32cd}
@deffnx {Δεδομένα} os.STATX_BLOCKS
@anchor{library/os os STATX_BASIC_STATS}@anchor{32f1}
@deffnx {Δεδομένα} os.STATX_BASIC_STATS
@anchor{library/os os STATX_BTIME}@anchor{32cf}
@deffnx {Δεδομένα} os.STATX_BTIME
@anchor{library/os os STATX_MNT_ID}@anchor{32e1}
@deffnx {Δεδομένα} os.STATX_MNT_ID
@anchor{library/os os STATX_DIOALIGN}@anchor{32d8}
@deffnx {Δεδομένα} os.STATX_DIOALIGN
@anchor{library/os os STATX_MNT_ID_UNIQUE}@anchor{32f2}
@deffnx {Δεδομένα} os.STATX_MNT_ID_UNIQUE
@anchor{library/os os STATX_SUBVOL}@anchor{32ed}
@deffnx {Δεδομένα} os.STATX_SUBVOL
@anchor{library/os os STATX_WRITE_ATOMIC}@anchor{32c6}
@deffnx {Δεδομένα} os.STATX_WRITE_ATOMIC
@anchor{library/os os STATX_DIO_READ_ALIGN}@anchor{32db}
@deffnx {Δεδομένα} os.STATX_DIO_READ_ALIGN

Bitflags for use in the `mask' parameter to @ref{23f,,os.statx()}.  Some of these
flags may be available even when their corresponding members in
@ref{32c0,,statx_result} are not available.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28.


Added in version 3.15.

@end deffn

@geindex AT_STATX_FORCE_SYNC (στη μονάδα os)
@anchor{library/os os AT_STATX_FORCE_SYNC}@anchor{32be}
@deffn {Δεδομένα} os.AT_STATX_FORCE_SYNC

A flag for the @ref{23f,,os.statx()} function.  Requests that the kernel return
up-to-date information even when doing so is expensive (for example,
requiring a round trip to the server for a file on a network filesystem).

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28.


Added in version 3.15.

@end deffn

@geindex AT_STATX_DONT_SYNC (στη μονάδα os)
@anchor{library/os os AT_STATX_DONT_SYNC}@anchor{32f3}
@deffn {Δεδομένα} os.AT_STATX_DONT_SYNC

A flag for the @ref{23f,,os.statx()} function.  Requests that the kernel return
cached information if possible.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28.


Added in version 3.15.

@end deffn

@geindex AT_STATX_SYNC_AS_STAT (στη μονάδα os)
@anchor{library/os os AT_STATX_SYNC_AS_STAT}@anchor{32f4}
@deffn {Δεδομένα} os.AT_STATX_SYNC_AS_STAT

A flag for the @ref{23f,,os.statx()} function.  This flag is defined as @code{0}, so
it has no effect, but it can be used to explicitly indicate neither
@ref{32be,,AT_STATX_FORCE_SYNC} nor @ref{32f3,,AT_STATX_DONT_SYNC} is being passed.
In the absence of the other two flags, the kernel will generally return
information as fresh as @ref{4f5,,os.stat()} would return.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.11 with glibc >= 2.28.


Added in version 3.15.

@end deffn

@geindex AT_NO_AUTOMOUNT (στη μονάδα os)
@anchor{library/os os AT_NO_AUTOMOUNT}@anchor{32bf}
@deffn {Δεδομένα} os.AT_NO_AUTOMOUNT

If the final component of a path is an automount point, operate on the
automount point instead of performing the automount.  On Linux,
@ref{4f5,,os.stat()}, @ref{1145,,os.fstat()} and @ref{8b1,,os.lstat()} always behave this
way.

@ref{232d,,Διαθεσιμότητα}: Linux.


Added in version 3.15.

@end deffn

@geindex statvfs() (στη μονάδα os)
@anchor{library/os os statvfs}@anchor{14a8}
@deffn {Συνάρτηση} 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}.

Two module-level constants are defined for the @code{f_flag} attribute’s
bit-flags: if @code{ST_RDONLY} is set, the filesystem is mounted
read-only, and if @code{ST_NOSUID} is set, the semantics of
setuid/setgid bits are disabled or not supported.

Additional module-level constants are defined for GNU/glibc based systems.
These are @code{ST_NODEV} (disallow access to device special files),
@code{ST_NOEXEC} (disallow program execution), @code{ST_SYNCHRONOUS}
(writes are synced at once), @code{ST_MANDLOCK} (allow mandatory locks on an FS),
@code{ST_WRITE} (write on file/directory/symlink), @code{ST_APPEND}
(append-only file), @code{ST_IMMUTABLE} (immutable file), @code{ST_NOATIME}
(do not update access times), @code{ST_NODIRATIME} (do not update directory access
times), @code{ST_RELATIME} (update atime relative to mtime/ctime).

This function can support @ref{f19,,specifying a file descriptor}.

@ref{232d,,Διαθεσιμότητα}: Unix.


Άλλαξε στην έκδοση 3.2: The @code{ST_RDONLY} and @code{ST_NOSUID} constants were added.



Άλλαξε στην έκδοση 3.3: Added support for specifying `path' as an open file descriptor.



Άλλαξε στην έκδοση 3.4: The @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},
and @code{ST_RELATIME} constants were added.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.7: Added the @code{f_fsid} attribute.

@end deffn

@geindex supports_dir_fd (στη μονάδα os)
@anchor{library/os os supports_dir_fd}@anchor{14a3}
@deffn {Δεδομένα} os.supports_dir_fd

A @ref{42b,,set} object indicating which functions in the @code{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{4f5,,os.stat()}
accepts open file descriptors for `dir_fd' on the local platform:

@example
os.stat in os.supports_dir_fd
@end example

Currently `dir_fd' parameters only work on Unix platforms;
none of them work on Windows.


Added in version 3.3.

@end deffn

@geindex supports_effective_ids (στη μονάδα os)
@anchor{library/os os supports_effective_ids}@anchor{14aa}
@deffn {Δεδομένα} os.supports_effective_ids

A @ref{42b,,set} object indicating whether @ref{1498,,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
@code{os.access()}; otherwise it will be empty.

This expression evaluates to @code{True} if @ref{1498,,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.


Added in version 3.3.

@end deffn

@geindex supports_fd (στη μονάδα os)
@anchor{library/os os supports_fd}@anchor{14a9}
@deffn {Δεδομένα} os.supports_fd

A @ref{42b,,set} object indicating which functions in the
@code{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{a02,,os.chdir()} accepts open file descriptors for `path' on your local
platform:

@example
os.chdir in os.supports_fd
@end example


Added in version 3.3.

@end deffn

@geindex supports_follow_symlinks (στη μονάδα os)
@anchor{library/os os supports_follow_symlinks}@anchor{14a4}
@deffn {Δεδομένα} os.supports_follow_symlinks

A @ref{42b,,set} object indicating which functions in the @code{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{4f5,,os.stat()} on the local platform:

@example
os.stat in os.supports_follow_symlinks
@end example


Added in version 3.3.

@end deffn

@geindex symlink() (στη μονάδα os)
@anchor{library/os os symlink}@anchor{14a0}
@deffn {Συνάρτηση} os.symlink (src, dst, target_is_directory=False, *, dir_fd=None)

Create a symbolic link pointing to `src' named `dst'.

The `src' parameter refers to the target of the link (the file or directory being linked to),
and `dst' is the name of the link being created.

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 @code{True} or a file symlink (the
default) otherwise.  On non-Windows platforms, `target_is_directory' is ignored.

This function can support @ref{1496,,paths relative to directory descriptors}.

@cartouche
@quotation Σημείωση 
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{53c,,OSError} is raised when the function is called by an unprivileged
user.
@end quotation
@end cartouche

Raises an @ref{1e65,,auditing event} @code{os.symlink} with arguments @code{src}, @code{dst}, @code{dir_fd}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.

The function is limited on WASI, see @ref{1d67,,WebAssembly platforms} for more
information.


Άλλαξε στην έκδοση 3.2: Added support for Windows 6.0 (Vista) symbolic links.



Άλλαξε στην έκδοση 3.3: Added the `dir_fd' parameter, and now allow `target_is_directory'
on non-Windows platforms.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object} for `src' and `dst'.



Άλλαξε στην έκδοση 3.8: Added support for unelevated symlinks on Windows with Developer Mode.

@end deffn

@geindex sync() (στη μονάδα os)
@anchor{library/os os sync}@anchor{14be}
@deffn {Συνάρτηση} os.sync ()

Force write of everything to disk.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex truncate() (στη μονάδα os)
@anchor{library/os os truncate}@anchor{11ef}
@deffn {Συνάρτηση} os.truncate (path, length)

Truncate the file corresponding to `path', so that it is at most
`length' bytes in size.

This function can support @ref{f19,,specifying a file descriptor}.

Raises an @ref{1e65,,auditing event} @code{os.truncate} with arguments @code{path}, @code{length}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.


Added in version 3.3.



Άλλαξε στην έκδοση 3.5: Added support for Windows



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex unlink() (στη μονάδα os)
@anchor{library/os os unlink}@anchor{14a1}
@deffn {Συνάρτηση} os.unlink (path, *, dir_fd=None)

Remove (delete) the file `path'.  This function is semantically
identical to @ref{149c,,remove()}; the @code{unlink} name is its
traditional Unix name.  Please see the documentation for
@code{remove()} for further information.

Raises an @ref{1e65,,auditing event} @code{os.remove} with arguments @code{path}, @code{dir_fd}.


Άλλαξε στην έκδοση 3.3: Added the `dir_fd' parameter.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex utime() (στη μονάδα os)
@anchor{library/os os utime}@anchor{14a2}
@deffn {Συνάρτηση} os.utime (path, times=None, *[, ns], dir_fd=None, follow_symlinks=True)

Set the access and modified times of the file specified by `path'.

@code{utime()} takes two optional parameters, `times' and `ns'.
These specify the times set on `path' and are used as follows:


@itemize -

@item 
If `ns' is specified,
it must be a 2-tuple of the form @code{(atime_ns, mtime_ns)}
where each member is an int expressing nanoseconds.

@item 
If `times' is not @code{None},
it must be a 2-tuple of the form @code{(atime, mtime)}
where each member is a real number expressing seconds,
rounded down to nanoseconds.

@item 
If `times' is @code{None} and `ns' is unspecified,
this is equivalent to specifying @code{ns=(atime_ns, mtime_ns)}
where both times are the current time.
@end itemize

It is an error to specify tuples for both `times' and `ns'.

Note that the exact times you set here may not be returned by a subsequent
@ref{4f5,,stat()} call, depending on the resolution with which your operating
system records access and modification times; see @code{stat()}. The best
way to preserve exact times is to use the `st_atime_ns' and `st_mtime_ns'
fields from the @code{os.stat()} result object with the `ns' parameter to
@code{utime()}.

This function can support @ref{f19,,specifying a file descriptor},
@ref{1496,,paths relative to directory descriptors} and @ref{1497,,not following symlinks}.

Raises an @ref{1e65,,auditing event} @code{os.utime} with arguments @code{path}, @code{times}, @code{ns}, @code{dir_fd}.


Άλλαξε στην έκδοση 3.3: Added support for specifying `path' as an open file descriptor,
and the `dir_fd', `follow_symlinks', and `ns' parameters.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.15: Accepts any real numbers as `times', not only integers or floats.

@end deffn

@geindex walk() (στη μονάδα os)
@anchor{library/os os walk}@anchor{8b9}
@deffn {Συνάρτηση} os.walk (top, topdown=True, onerror=None, followlinks=False)

@geindex directory;walking
@geindex directory;traversal

Generate the file names in a directory tree by walking the tree
either top-down or bottom-up. For each directory in the tree rooted at directory
`top' (including `top' itself), it yields a 3-tuple @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.

If optional argument `topdown' is @code{True} or not specified, the triple for a
directory is generated before the triples for any of its subdirectories
(directories are generated top-down).  If `topdown' is @code{False}, the triple
for a directory is generated after the triples for all of its subdirectories
(directories are generated bottom-up). No matter the value of `topdown', the
list of subdirectories is retrieved before the tuples for the directory and
its subdirectories are generated.

When `topdown' is @code{True}, the caller can modify the `dirnames' list in-place
(perhaps using @ref{1d1d,,del} or slice assignment), and @code{walk()} will only
recurse into the subdirectories whose names remain in `dirnames'; this can be
used to prune the search, impose a specific order of visiting, or even to inform
@code{walk()} about directories the caller creates or renames before it resumes
@code{walk()} again.  Modifying `dirnames' when `topdown' is @code{False} has
no effect on the behavior of the walk, because in bottom-up mode the directories
in `dirnames' are generated before `dirpath' itself is generated.

By default, errors from the @ref{e23,,scandir()} call are ignored.  If optional
argument `onerror' is specified, it should be a function; it will be called with
one argument, an @ref{53c,,OSError} instance.  It can report the error to continue
with the walk, or raise the exception to abort the walk.  Note that the filename
is available as the @code{filename} attribute of the exception object.

By default, @code{walk()} will not walk down into symbolic links that resolve to
directories. Set `followlinks' to @code{True} to visit directories pointed to by
symlinks, on systems that support them.

@cartouche
@quotation Σημείωση 
Be aware that setting `followlinks' to @code{True} can lead to infinite
recursion if a link points to a parent directory of itself. @code{walk()}
does not keep track of the directories it visited already.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
If you pass a relative pathname, don’t change the current working directory
between resumptions of @code{walk()}.  @code{walk()} never changes the current
directory, and assumes that its caller doesn’t either.
@end quotation
@end cartouche

This example displays the number of bytes taken by non-directory files in each
directory under the starting directory, except that it doesn’t look under any
@code{__pycache__} subdirectory:

@example
import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/xml'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if '__pycache__' in dirs:
        dirs.remove('__pycache__')  # don't visit __pycache__ directories
@end example

In the next example (simple implementation of @ref{335,,shutil.rmtree()}),
walking the tree bottom-up is essential, @ref{149f,,rmdir()} doesn’t allow
deleting a directory before the directory is empty:

@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

Raises an @ref{1e65,,auditing event} @code{os.walk} with arguments @code{top}, @code{topdown}, @code{onerror}, @code{followlinks}.


Άλλαξε στην έκδοση 3.5: This function now calls @ref{e23,,os.scandir()} instead of @ref{14a6,,os.listdir()},
making it faster by reducing the number of calls to @ref{4f5,,os.stat()}.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex fwalk() (στη μονάδα os)
@anchor{library/os os fwalk}@anchor{f18}
@deffn {Συνάρτηση} os.fwalk (top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)

@geindex directory;walking
@geindex directory;traversal

This behaves exactly like @ref{8b9,,walk()}, except that it yields a 4-tuple
@code{(dirpath, dirnames, filenames, dirfd)}, and it supports @code{dir_fd}.

`dirpath', `dirnames' and `filenames' are identical to @ref{8b9,,walk()} output,
and `dirfd' is a file descriptor referring to the directory `dirpath'.

This function always supports @ref{1496,,paths relative to directory descriptors} and @ref{1497,,not following symlinks}.  Note however
that, unlike other functions, the @code{fwalk()} default value for
`follow_symlinks' is @code{False}.

@cartouche
@quotation Σημείωση 
Since @code{fwalk()} yields file descriptors, those are only valid until
the next iteration step, so you should duplicate them (e.g. with
@ref{1fb2,,dup()}) if you want to keep them longer.
@end quotation
@end cartouche

This example displays the number of bytes taken by non-directory files in each
directory under the starting directory, except that it doesn’t look under any
@code{__pycache__} subdirectory:

@example
import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/xml'):
    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 '__pycache__' in dirs:
        dirs.remove('__pycache__')  # don't visit __pycache__ directories
@end example

In the next example, walking the tree bottom-up is essential:
@ref{149f,,rmdir()} doesn’t allow deleting a directory before the directory is
empty:

@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

Raises an @ref{1e65,,auditing event} @code{os.fwalk} with arguments @code{top}, @code{topdown}, @code{onerror}, @code{follow_symlinks}, @code{dir_fd}.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.7: Added support for @ref{1c7,,bytes} paths.

@end deffn

@geindex memfd_create() (στη μονάδα os)
@anchor{library/os os memfd_create}@anchor{dcd}
@deffn {Συνάρτηση} 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{12aa,,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{232d,,Διαθεσιμότητα}: Linux >= 3.17 with glibc >= 2.27.


Added in version 3.8.

@end deffn

@geindex MFD_CLOEXEC (στη μονάδα os)
@geindex MFD_ALLOW_SEALING (στη μονάδα os)
@geindex MFD_HUGETLB (στη μονάδα os)
@geindex MFD_HUGE_SHIFT (στη μονάδα os)
@geindex MFD_HUGE_MASK (στη μονάδα os)
@geindex MFD_HUGE_64KB (στη μονάδα os)
@geindex MFD_HUGE_512KB (στη μονάδα os)
@geindex MFD_HUGE_1MB (στη μονάδα os)
@geindex MFD_HUGE_2MB (στη μονάδα os)
@geindex MFD_HUGE_8MB (στη μονάδα os)
@geindex MFD_HUGE_16MB (στη μονάδα os)
@geindex MFD_HUGE_32MB (στη μονάδα os)
@geindex MFD_HUGE_256MB (στη μονάδα os)
@geindex MFD_HUGE_512MB (στη μονάδα os)
@geindex MFD_HUGE_1GB (στη μονάδα os)
@geindex MFD_HUGE_2GB (στη μονάδα os)
@geindex MFD_HUGE_16GB (στη μονάδα os)
@anchor{library/os os MFD_CLOEXEC}@anchor{32f5}
@deffn {Δεδομένα} os.MFD_CLOEXEC
@anchor{library/os os MFD_ALLOW_SEALING}@anchor{32f6}
@deffnx {Δεδομένα} os.MFD_ALLOW_SEALING
@anchor{library/os os MFD_HUGETLB}@anchor{32f7}
@deffnx {Δεδομένα} os.MFD_HUGETLB
@anchor{library/os os MFD_HUGE_SHIFT}@anchor{32f8}
@deffnx {Δεδομένα} os.MFD_HUGE_SHIFT
@anchor{library/os os MFD_HUGE_MASK}@anchor{32f9}
@deffnx {Δεδομένα} os.MFD_HUGE_MASK
@anchor{library/os os MFD_HUGE_64KB}@anchor{32fa}
@deffnx {Δεδομένα} os.MFD_HUGE_64KB
@anchor{library/os os MFD_HUGE_512KB}@anchor{32fb}
@deffnx {Δεδομένα} os.MFD_HUGE_512KB
@anchor{library/os os MFD_HUGE_1MB}@anchor{32fc}
@deffnx {Δεδομένα} os.MFD_HUGE_1MB
@anchor{library/os os MFD_HUGE_2MB}@anchor{32fd}
@deffnx {Δεδομένα} os.MFD_HUGE_2MB
@anchor{library/os os MFD_HUGE_8MB}@anchor{32fe}
@deffnx {Δεδομένα} os.MFD_HUGE_8MB
@anchor{library/os os MFD_HUGE_16MB}@anchor{32ff}
@deffnx {Δεδομένα} os.MFD_HUGE_16MB
@anchor{library/os os MFD_HUGE_32MB}@anchor{3300}
@deffnx {Δεδομένα} os.MFD_HUGE_32MB
@anchor{library/os os MFD_HUGE_256MB}@anchor{3301}
@deffnx {Δεδομένα} os.MFD_HUGE_256MB
@anchor{library/os os MFD_HUGE_512MB}@anchor{3302}
@deffnx {Δεδομένα} os.MFD_HUGE_512MB
@anchor{library/os os MFD_HUGE_1GB}@anchor{3303}
@deffnx {Δεδομένα} os.MFD_HUGE_1GB
@anchor{library/os os MFD_HUGE_2GB}@anchor{3304}
@deffnx {Δεδομένα} os.MFD_HUGE_2GB
@anchor{library/os os MFD_HUGE_16GB}@anchor{3305}
@deffnx {Δεδομένα} os.MFD_HUGE_16GB

These flags can be passed to @ref{dcd,,memfd_create()}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 3.17 with glibc >= 2.27

The @code{MFD_HUGE*} flags are only available since Linux 4.14.


Added in version 3.8.

@end deffn

@geindex eventfd() (στη μονάδα os)
@anchor{library/os os eventfd}@anchor{bf1}
@deffn {Συνάρτηση} os.eventfd (initval[, flags=os.EFD_CLOEXEC])

Create and return an event file descriptor. The file descriptors supports
raw @ref{114e,,read()} and @ref{1154,,write()} with a buffer size of 8,
@ref{1159,,select()}, @ref{268,,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{12aa,,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{1d56,,EFD_CLOEXEC},
@ref{1d57,,EFD_NONBLOCK}, and @ref{1d58,,EFD_SEMAPHORE}.

If @ref{1d58,,EFD_SEMAPHORE} is specified and the event counter is non-zero,
@ref{3306,,eventfd_read()} returns 1 and decrements the counter by one.

If @ref{1d58,,EFD_SEMAPHORE} is not specified and the event counter is
non-zero, @ref{3306,,eventfd_read()} returns the current event counter value and
resets the counter to zero.

If the event counter is zero and @ref{1d57,,EFD_NONBLOCK} is not
specified, @ref{3306,,eventfd_read()} blocks.

@ref{3307,,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.

Example:

@example
import os

# semaphore with start value '1'
fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFD_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{232d,,Διαθεσιμότητα}: Linux >= 2.6.27 with glibc >= 2.8


Added in version 3.10.

@end deffn

@geindex eventfd_read() (στη μονάδα os)
@anchor{library/os os eventfd_read}@anchor{3306}
@deffn {Συνάρτηση} os.eventfd_read (fd)

Read value from an @ref{bf1,,eventfd()} file descriptor and return a 64 bit
unsigned int. The function does not verify that `fd' is an @code{eventfd()}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.27


Added in version 3.10.

@end deffn

@geindex eventfd_write() (στη μονάδα os)
@anchor{library/os os eventfd_write}@anchor{3307}
@deffn {Συνάρτηση} os.eventfd_write (fd, value)

Add value to an @ref{bf1,,eventfd()} file descriptor. `value' must be a 64 bit
unsigned int. The function does not verify that `fd' is an @code{eventfd()}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.27


Added in version 3.10.

@end deffn

@geindex EFD_CLOEXEC (στη μονάδα os)
@anchor{library/os os EFD_CLOEXEC}@anchor{1d56}
@deffn {Δεδομένα} os.EFD_CLOEXEC

Set close-on-exec flag for new @ref{bf1,,eventfd()} file descriptor.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.27


Added in version 3.10.

@end deffn

@geindex EFD_NONBLOCK (στη μονάδα os)
@anchor{library/os os EFD_NONBLOCK}@anchor{1d57}
@deffn {Δεδομένα} os.EFD_NONBLOCK

Set @ref{11ee,,O_NONBLOCK} status flag for new @ref{bf1,,eventfd()} file
descriptor.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.27


Added in version 3.10.

@end deffn

@geindex EFD_SEMAPHORE (στη μονάδα os)
@anchor{library/os os EFD_SEMAPHORE}@anchor{1d58}
@deffn {Δεδομένα} os.EFD_SEMAPHORE

Provide semaphore-like semantics for reads from an @ref{bf1,,eventfd()} file
descriptor. On read the internal counter is decremented by one.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.30


Added in version 3.10.

@end deffn

@menu
* Timer File Descriptors:: 
* Linux extended attributes:: 

@end menu

@node Timer File Descriptors,Linux extended attributes,,Files and Directories
@anchor{library/os os-timerfd}@anchor{68c}@anchor{library/os timer-file-descriptors}@anchor{3308}
@subsubsection Timer File Descriptors



Added in 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() (στη μονάδα os)
@anchor{library/os os timerfd_create}@anchor{722}
@deffn {Συνάρτηση} os.timerfd_create (clockid, /, *, flags=0)

Create and return a timer file descriptor (`timerfd').

The file descriptor returned by @code{timerfd_create()} supports:


@itemize -

@item 
@ref{114e,,read()}

@item 
@ref{1159,,select()}

@item 
@ref{268,,poll()}
@end itemize

The file descriptor’s @ref{114e,,read()} method can be called with a buffer size
of 8. If the timer has already expired one or more times, @code{read()}
returns the number of expirations with the host’s endianness, which may be
converted to an @ref{326,,int} by @code{int.from_bytes(x, byteorder=sys.byteorder)}.

@ref{1159,,select()} and @ref{268,,poll()} can be used to wait until
timer expires and the file descriptor is readable.

`clockid' must be a valid @ref{3309,,clock ID},
as defined in the @ref{f7,,time} module:


@itemize -

@item 
@ref{a89,,time.CLOCK_REALTIME}

@item 
@ref{a88,,time.CLOCK_MONOTONIC}

@item 
@ref{f4d,,time.CLOCK_BOOTTIME} (Since Linux 3.15 for timerfd_create)
@end itemize

If `clockid' is @ref{a89,,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{72a,,TFD_TIMER_CANCEL_ON_SET}.

If `clockid' is @ref{a88,,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{f4d,,time.CLOCK_BOOTTIME}, same as @ref{a88,,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 be used, combined using bitwise OR
(the @code{|} operator):


@itemize -

@item 
@ref{727,,TFD_NONBLOCK}

@item 
@ref{728,,TFD_CLOEXEC}
@end itemize

If @ref{727,,TFD_NONBLOCK} is not set as a flag, @ref{114e,,read()} blocks until
the timer expires. If it is set as a flag, @code{read()} doesn’t block, but
If there hasn’t been an expiration since the last call to read,
@code{read()} raises @ref{53c,,OSError} with @code{errno} is set to
@ref{28f9,,errno.EAGAIN}.

@ref{728,,TFD_CLOEXEC} is always set by Python automatically.

The file descriptor must be closed with @ref{f31,,os.close()} when it is no
longer needed, or else the file descriptor will be leaked.


@subsubheading Δείτε επίσης


The @code{timerfd_create(2)@footnote{https://manpages.debian.org/timerfd_create(2)}} man page.


@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.27 with glibc >= 2.8


Added in version 3.13.

@end deffn

@geindex timerfd_settime() (στη μονάδα os)
@anchor{library/os os timerfd_settime}@anchor{723}
@deffn {Συνάρτηση} 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{724,,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 be used, combined using bitwise OR
(the @code{|} operator):


@itemize -

@item 
@ref{729,,TFD_TIMER_ABSTIME}

@item 
@ref{72a,,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{53c,,OSError} exception
with @code{errno} set to @ref{1fc1,,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{729,,TFD_TIMER_ABSTIME} flag is set,
the timer will fire when the timer’s clock
(set by `clockid' in @ref{722,,timerfd_create()}) reaches `initial' seconds.

The timer’s interval is set by the `interval' real number.
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{53c,,OSError} with @code{errno}
set to @ref{1fc1,,errno.EINVAL}

If the @ref{72a,,TFD_TIMER_CANCEL_ON_SET} flag is set along with
@ref{729,,TFD_TIMER_ABSTIME} and the clock for this timer is
@ref{a89,,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 Δείτε επίσης


@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{232d,,Διαθεσιμότητα}: Linux >= 2.6.27 with glibc >= 2.8


Added in version 3.13.

@end deffn

@geindex timerfd_settime_ns() (στη μονάδα os)
@anchor{library/os os timerfd_settime_ns}@anchor{724}
@deffn {Συνάρτηση} os.timerfd_settime_ns (fd, /, *, flags=0, initial=0, interval=0)

Similar to @ref{723,,timerfd_settime()}, but use time as nanoseconds.
This function operates the same interval timer as @code{timerfd_settime()}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.27 with glibc >= 2.8


Added in version 3.13.

@end deffn

@geindex timerfd_gettime() (στη μονάδα os)
@anchor{library/os os timerfd_gettime}@anchor{725}
@deffn {Συνάρτηση} os.timerfd_gettime (fd, /)

Return a two-item tuple of floats (@code{next_expiration}, @code{interval}).

@code{next_expiration} denotes the relative time until the timer next fires,
regardless of if the @ref{729,,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 Δείτε επίσης


@code{timerfd_gettime(2)@footnote{https://manpages.debian.org/timerfd_gettime(2)}}


@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.27 with glibc >= 2.8


Added in version 3.13.

@end deffn

@geindex timerfd_gettime_ns() (στη μονάδα os)
@anchor{library/os os timerfd_gettime_ns}@anchor{726}
@deffn {Συνάρτηση} os.timerfd_gettime_ns (fd, /)

Similar to @ref{725,,timerfd_gettime()}, but return time as nanoseconds.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.27 with glibc >= 2.8


Added in version 3.13.

@end deffn

@geindex TFD_NONBLOCK (στη μονάδα os)
@anchor{library/os os TFD_NONBLOCK}@anchor{727}
@deffn {Δεδομένα} os.TFD_NONBLOCK

A flag for the @ref{722,,timerfd_create()} function,
which sets the @ref{11ee,,O_NONBLOCK} status flag for the new timer file
descriptor. If @ref{727,,TFD_NONBLOCK} is not set as a flag, @ref{114e,,read()} blocks.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.27 with glibc >= 2.8


Added in version 3.13.

@end deffn

@geindex TFD_CLOEXEC (στη μονάδα os)
@anchor{library/os os TFD_CLOEXEC}@anchor{728}
@deffn {Δεδομένα} os.TFD_CLOEXEC

A flag for the @ref{722,,timerfd_create()} function,
If @ref{728,,TFD_CLOEXEC} is set as a flag, set close-on-exec flag for new file
descriptor.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.27 with glibc >= 2.8


Added in version 3.13.

@end deffn

@geindex TFD_TIMER_ABSTIME (στη μονάδα os)
@anchor{library/os os TFD_TIMER_ABSTIME}@anchor{729}
@deffn {Δεδομένα} os.TFD_TIMER_ABSTIME

A flag for the @ref{723,,timerfd_settime()} and @ref{724,,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{232d,,Διαθεσιμότητα}: Linux >= 2.6.27 with glibc >= 2.8


Added in version 3.13.

@end deffn

@geindex TFD_TIMER_CANCEL_ON_SET (στη μονάδα os)
@anchor{library/os os TFD_TIMER_CANCEL_ON_SET}@anchor{72a}
@deffn {Δεδομένα} os.TFD_TIMER_CANCEL_ON_SET

A flag for the @ref{723,,timerfd_settime()} and @ref{724,,timerfd_settime_ns()}
functions along with @ref{729,,TFD_TIMER_ABSTIME}.
The timer is cancelled when the time of the underlying clock changes
discontinuously.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.27 with glibc >= 2.8


Added in version 3.13.

@end deffn

@node Linux extended attributes,,Timer File Descriptors,Files and Directories
@anchor{library/os linux-extended-attributes}@anchor{330a}
@subsubsection Linux extended attributes



Added in version 3.3.


These functions are all available on Linux only.

@geindex getxattr() (στη μονάδα os)
@anchor{library/os os getxattr}@anchor{14b0}
@deffn {Συνάρτηση} os.getxattr (path, attribute, *, follow_symlinks=True)

Return the value of the extended filesystem attribute `attribute' for
`path'. `attribute' can be bytes or str (directly or indirectly through the
@ref{100f,,PathLike} interface). If it is str, it is encoded with the filesystem
encoding.

This function can support @ref{f19,,specifying a file descriptor} and
@ref{1497,,not following symlinks}.

Raises an @ref{1e65,,auditing event} @code{os.getxattr} with arguments @code{path}, @code{attribute}.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object} for `path' and `attribute'.

@end deffn

@geindex listxattr() (στη μονάδα os)
@anchor{library/os os listxattr}@anchor{14b1}
@deffn {Συνάρτηση} os.listxattr (path=None, *, follow_symlinks=True)

Return a list of the extended filesystem attributes on `path'.  The
attributes in the list are represented as strings decoded with the filesystem
encoding.  If `path' is @code{None}, @code{listxattr()} will examine the current
directory.

This function can support @ref{f19,,specifying a file descriptor} and
@ref{1497,,not following symlinks}.

Raises an @ref{1e65,,auditing event} @code{os.listxattr} with argument @code{path}.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.15: @code{os.listxattr(-1)} now fails with @code{OSError(errno.EBADF)} rather than
listing extended attributes of the current directory.

@end deffn

@geindex removexattr() (στη μονάδα os)
@anchor{library/os os removexattr}@anchor{14b2}
@deffn {Συνάρτηση} 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{100f,,PathLike} interface). If it is a string, it is encoded
with the @ref{948,,filesystem encoding and error handler}.

This function can support @ref{f19,,specifying a file descriptor} and
@ref{1497,,not following symlinks}.

Raises an @ref{1e65,,auditing event} @code{os.removexattr} with arguments @code{path}, @code{attribute}.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object} for `path' and `attribute'.

@end deffn

@geindex setxattr() (στη μονάδα os)
@anchor{library/os os setxattr}@anchor{14b3}
@deffn {Συνάρτηση} 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{100f,,PathLike} interface). If it is a str,
it is encoded with the @ref{948,,filesystem encoding and error handler}.  `flags' may be
@ref{330b,,XATTR_REPLACE} or @ref{330c,,XATTR_CREATE}. If @code{XATTR_REPLACE} is
given and the attribute does not exist, @code{ENODATA} will be raised.
If @code{XATTR_CREATE} is given and the attribute already exists, the
attribute will not be created and @code{EEXISTS} will be raised.

This function can support @ref{f19,,specifying a file descriptor} and
@ref{1497,,not following symlinks}.

@cartouche
@quotation Σημείωση 
A bug in Linux kernel versions less than 2.6.39 caused the flags argument
to be ignored on some filesystems.
@end quotation
@end cartouche

Raises an @ref{1e65,,auditing event} @code{os.setxattr} with arguments @code{path}, @code{attribute}, @code{value}, @code{flags}.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object} for `path' and `attribute'.

@end deffn

@geindex XATTR_SIZE_MAX (στη μονάδα os)
@anchor{library/os os XATTR_SIZE_MAX}@anchor{330d}
@deffn {Δεδομένα} os.XATTR_SIZE_MAX

The maximum size the value of an extended attribute can be. Currently, this
is 64 KiB on Linux.
@end deffn

@geindex XATTR_CREATE (στη μονάδα os)
@anchor{library/os os XATTR_CREATE}@anchor{330c}
@deffn {Δεδομένα} os.XATTR_CREATE

This is a possible value for the flags argument in @ref{14b3,,setxattr()}. It
indicates the operation must create an attribute.
@end deffn

@geindex XATTR_REPLACE (στη μονάδα os)
@anchor{library/os os XATTR_REPLACE}@anchor{330b}
@deffn {Δεδομένα} os.XATTR_REPLACE

This is a possible value for the flags argument in @ref{14b3,,setxattr()}. It
indicates the operation must replace an existing attribute.
@end deffn

@node Process Management,Interface to the scheduler,Files and Directories,os — Miscellaneous operating system interfaces
@anchor{library/os os-process}@anchor{330e}@anchor{library/os process-management}@anchor{330f}
@subsubsection Process Management


These functions may be used to create and manage processes.

The various @ref{3310,,exec*} functions take a list of arguments for the new
program loaded into the process.  In each case, the first of these arguments is
passed to the new program as its own name rather than as an argument a user may
have typed on a command line.  For the C programmer, this is the @code{argv[0]}
passed to a program’s @code{main()}.  For example, @code{os.execv('/bin/echo',
['foo', 'bar'])} will only print @code{bar} on standard output; @code{foo} will seem
to be ignored.

@geindex abort() (στη μονάδα os)
@anchor{library/os os abort}@anchor{3311}
@deffn {Συνάρτηση} os.abort ()

Generate a @ref{142a,,SIGABRT} signal to the current process.  On Unix, the default
behavior is to produce a core dump; on Windows, the process immediately returns
an exit code of @code{3}.  Be aware that calling this function will not call the
Python signal handler registered for @code{SIGABRT} with
@ref{14e0,,signal.signal()}.
@end deffn

@geindex add_dll_directory() (στη μονάδα os)
@anchor{library/os os add_dll_directory}@anchor{dae}
@deffn {Συνάρτηση} os.add_dll_directory (path)

Add a path to the DLL search path.

This search path is used when resolving dependencies for imported
extension modules (the module itself is resolved through
@ref{194,,sys.path}), and also by @ref{2d,,ctypes}.

Remove the directory by calling `close()' on the returned object
or using it in a @ref{20a,,with} statement.

See the Microsoft documentation@footnote{https://msdn.microsoft.com/44228cf2-6306-466c-8f16-f513cd3ba8b5}
for more information about how DLLs are loaded.

Raises an @ref{1e65,,auditing event} @code{os.add_dll_directory} with argument @code{path}.

@ref{232d,,Διαθεσιμότητα}: Windows.


Added in 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 μεταβλητή περιβάλλοντος; 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{e64,,porting notes} for information on
updating libraries.

@end deffn

@geindex execl() (στη μονάδα os)
@geindex execle() (στη μονάδα os)
@geindex execlp() (στη μονάδα os)
@geindex execlpe() (στη μονάδα os)
@geindex execv() (στη μονάδα os)
@geindex execve() (στη μονάδα os)
@geindex execvp() (στη μονάδα os)
@geindex execvpe() (στη μονάδα os)
@anchor{library/os os execl}@anchor{3310}
@deffn {Συνάρτηση} os.execl (path, arg0, arg1, ...)
@anchor{library/os os execle}@anchor{3312}
@deffnx {Συνάρτηση} os.execle (path, arg0, arg1, ..., env)
@anchor{library/os os execlp}@anchor{3313}
@deffnx {Συνάρτηση} os.execlp (file, arg0, arg1, ...)
@anchor{library/os os execlpe}@anchor{3314}
@deffnx {Συνάρτηση} os.execlpe (file, arg0, arg1, ..., env)
@anchor{library/os os execv}@anchor{323e}
@deffnx {Συνάρτηση} os.execv (path, args)
@anchor{library/os os execve}@anchor{14a5}
@deffnx {Συνάρτηση} os.execve (path, args, env)
@anchor{library/os os execvp}@anchor{3315}
@deffnx {Συνάρτηση} os.execvp (file, args)
@anchor{library/os os execvpe}@anchor{3316}
@deffnx {Συνάρτηση} os.execvpe (file, args, env)

These functions all execute a new program, replacing the current process; they
do not return.  On Unix, the new executable is loaded into the current process,
and will have the same process id as the caller.  Errors will be reported as
@ref{53c,,OSError} exceptions.

The current process is replaced immediately. Open file objects and
descriptors are not flushed, so if there may be data buffered
on these open files, you should flush them using
@ref{19fa,,flush()} or @ref{1147,,os.fsync()} before calling an
@code{exec*} function.

The «l» and «v» variants of the @code{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 (@code{execlp()},
@code{execlpe()}, @code{execvp()}, and @code{execvpe()}) will use the
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} environment variable to locate the program `file'.  When the
environment is being replaced (using one of the @code{exec*e} variants,
discussed in the next paragraph), the new environment is used as the source of
the 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} variable. The other variants, @code{execl()}, @code{execle()},
@code{execv()}, and @code{execve()}, will not use the 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; 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.

For @code{execle()}, @code{execlpe()}, @code{execve()}, and @code{execvpe()} (note
that these all end in «e»), the `env' parameter must be a mapping which is
used to define the environment variables for the new process (these are used
instead of the current process” environment); the functions @code{execl()},
@code{execlp()}, @code{execv()}, and @code{execvp()} all cause the new process to
inherit the environment of the current process.

For @code{execve()} on some platforms, `path' may also be specified as an open
file descriptor.  This functionality may not be supported on your platform;
you can check whether or not it is available using @ref{14a9,,os.supports_fd}.
If it is unavailable, using it will raise a @ref{59a,,NotImplementedError}.

Raises an @ref{1e65,,auditing event} @code{os.exec} with arguments @code{path}, @code{args}, @code{env}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows, not WASI, not Android, not iOS.


Άλλαξε στην έκδοση 3.3: Added support for specifying `path' as an open file descriptor
for @code{execve()}.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex _exit() (στη μονάδα os)
@anchor{library/os os _exit}@anchor{28f5}
@deffn {Συνάρτηση} os._exit (n)

Exit the process with status `n', without calling cleanup handlers, flushing
stdio buffers, etc.

@cartouche
@quotation Σημείωση 
The standard way to exit is @ref{4ff,,sys.exit(n)}.  @code{_exit()} should
normally only be used in the child process after a @ref{6bd,,fork()}.
@end quotation
@end cartouche
@end deffn

The following exit codes are defined and can be used with @ref{28f5,,_exit()},
although they are not required.  These are typically used for system programs
written in Python, such as a mail server’s external command delivery program.

@cartouche
@quotation Σημείωση 
Some of these may not be available on all Unix platforms, since there is some
variation.  These constants are defined where they are defined by the underlying
platform.
@end quotation
@end cartouche

@geindex EX_OK (στη μονάδα os)
@anchor{library/os os EX_OK}@anchor{3317}
@deffn {Δεδομένα} 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{232d,,Διαθεσιμότητα}: Unix, Windows.
@end deffn

@geindex EX_USAGE (στη μονάδα os)
@anchor{library/os os EX_USAGE}@anchor{3318}
@deffn {Δεδομένα} os.EX_USAGE

Exit code that means the command was used incorrectly, such as when the wrong
number of arguments are given.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_DATAERR (στη μονάδα os)
@anchor{library/os os EX_DATAERR}@anchor{3319}
@deffn {Δεδομένα} os.EX_DATAERR

Exit code that means the input data was incorrect.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_NOINPUT (στη μονάδα os)
@anchor{library/os os EX_NOINPUT}@anchor{331a}
@deffn {Δεδομένα} os.EX_NOINPUT

Exit code that means an input file did not exist or was not readable.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_NOUSER (στη μονάδα os)
@anchor{library/os os EX_NOUSER}@anchor{331b}
@deffn {Δεδομένα} os.EX_NOUSER

Exit code that means a specified user did not exist.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_NOHOST (στη μονάδα os)
@anchor{library/os os EX_NOHOST}@anchor{331c}
@deffn {Δεδομένα} os.EX_NOHOST

Exit code that means a specified host did not exist.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_UNAVAILABLE (στη μονάδα os)
@anchor{library/os os EX_UNAVAILABLE}@anchor{331d}
@deffn {Δεδομένα} os.EX_UNAVAILABLE

Exit code that means that a required service is unavailable.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_SOFTWARE (στη μονάδα os)
@anchor{library/os os EX_SOFTWARE}@anchor{331e}
@deffn {Δεδομένα} os.EX_SOFTWARE

Exit code that means an internal software error was detected.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_OSERR (στη μονάδα os)
@anchor{library/os os EX_OSERR}@anchor{331f}
@deffn {Δεδομένα} os.EX_OSERR

Exit code that means an operating system error was detected, such as the
inability to fork or create a pipe.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_OSFILE (στη μονάδα os)
@anchor{library/os os EX_OSFILE}@anchor{3320}
@deffn {Δεδομένα} os.EX_OSFILE

Exit code that means some system file did not exist, could not be opened, or had
some other kind of error.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_CANTCREAT (στη μονάδα os)
@anchor{library/os os EX_CANTCREAT}@anchor{3321}
@deffn {Δεδομένα} os.EX_CANTCREAT

Exit code that means a user specified output file could not be created.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_IOERR (στη μονάδα os)
@anchor{library/os os EX_IOERR}@anchor{3322}
@deffn {Δεδομένα} os.EX_IOERR

Exit code that means that an error occurred while doing I/O on some file.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_TEMPFAIL (στη μονάδα os)
@anchor{library/os os EX_TEMPFAIL}@anchor{3323}
@deffn {Δεδομένα} os.EX_TEMPFAIL

Exit code that means a temporary failure occurred.  This indicates something
that may not really be an error, such as a network connection that couldn’t be
made during a retryable operation.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_PROTOCOL (στη μονάδα os)
@anchor{library/os os EX_PROTOCOL}@anchor{3324}
@deffn {Δεδομένα} os.EX_PROTOCOL

Exit code that means that a protocol exchange was illegal, invalid, or not
understood.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_NOPERM (στη μονάδα os)
@anchor{library/os os EX_NOPERM}@anchor{3325}
@deffn {Δεδομένα} os.EX_NOPERM

Exit code that means that there were insufficient permissions to perform the
operation (but not intended for file system problems).

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_CONFIG (στη μονάδα os)
@anchor{library/os os EX_CONFIG}@anchor{3326}
@deffn {Δεδομένα} os.EX_CONFIG

Exit code that means that some kind of configuration error occurred.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex EX_NOTFOUND (στη μονάδα os)
@anchor{library/os os EX_NOTFOUND}@anchor{3327}
@deffn {Δεδομένα} os.EX_NOTFOUND

Exit code that means something like «an entry was not found».

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex fork() (στη μονάδα os)
@anchor{library/os os fork}@anchor{6bd}
@deffn {Συνάρτηση} os.fork ()

Fork a child process.  Return @code{0} in the child and the child’s process id in the
parent.  If an error occurs @ref{53c,,OSError} is raised.

Note that some platforms including FreeBSD <= 6.3 and Cygwin have
known issues when using @code{fork()} from a thread.

Raises an @ref{1e65,,auditing event} @code{os.fork} with no arguments.

@cartouche
@quotation Προειδοποίηση 
If you use TLS sockets in an application calling @code{fork()}, see
the warning in the @ref{d8,,ssl} documentation.
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
On macOS the use of this function is unsafe when mixed with using
higher-level system APIs, and that includes using @ref{114,,urllib.request}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.8: Calling @code{fork()} in a subinterpreter is no longer supported
(@ref{30d,,RuntimeError} is raised).



Άλλαξε στην έκδοση 3.12: If Python is able to detect that your process has multiple
threads, @ref{6bd,,os.fork()} now raises a @ref{2c9,,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{6bd,,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{232d,,Διαθεσιμότητα}: POSIX, not WASI, not Android, not iOS.
@end deffn

@geindex forkpty() (στη μονάδα os)
@anchor{library/os os forkpty}@anchor{6be}
@deffn {Συνάρτηση} os.forkpty ()

Fork a child process, using a new pseudo-terminal as the child’s controlling
terminal. Return a pair of @code{(pid, fd)}, where `pid' is @code{0} in the child, the
new child’s process id in the parent, and `fd' is the file descriptor of the
master end of the pseudo-terminal.  For a more portable approach, use the
@ref{b9,,pty} module.  If an error occurs @ref{53c,,OSError} is raised.

The returned file descriptor `fd' is @ref{12aa,,non-inheritable}.

Raises an @ref{1e65,,auditing event} @code{os.forkpty} with no arguments.

@cartouche
@quotation Προειδοποίηση 
On macOS the use of this function is unsafe when mixed with using
higher-level system APIs, and that includes using @ref{114,,urllib.request}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.8: Calling @code{forkpty()} in a subinterpreter is no longer supported
(@ref{30d,,RuntimeError} is raised).



Άλλαξε στην έκδοση 3.12: If Python is able to detect that your process has multiple
threads, this now raises a @ref{2c9,,DeprecationWarning}. See the
longer explanation on @ref{6bd,,os.fork()}.



Άλλαξε στην έκδοση 3.15: The returned file descriptor is now made non-inheritable.


@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex kill() (στη μονάδα os)
@anchor{library/os os kill}@anchor{170c}
@deffn {Συνάρτηση} os.kill (pid, sig, /)

@geindex process;killing
@geindex process;signalling

Send signal `sig' to the process `pid'.  Constants for the specific signals
available on the host platform are defined in the @ref{ce,,signal} module.

Windows: The @ref{170d,,signal.CTRL_C_EVENT} and
@ref{170e,,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'.

See also @ref{14dd,,signal.pthread_kill()}.

Raises an @ref{1e65,,auditing event} @code{os.kill} with arguments @code{pid}, @code{sig}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows, not WASI, not iOS.


Άλλαξε στην έκδοση 3.2: Added Windows support.

@end deffn

@geindex killpg() (στη μονάδα os)
@anchor{library/os os killpg}@anchor{1fab}
@deffn {Συνάρτηση} os.killpg (pgid, sig, /)

@geindex process;killing
@geindex process;signalling

Send the signal `sig' to the process group `pgid'.

Raises an @ref{1e65,,auditing event} @code{os.killpg} with arguments @code{pgid}, @code{sig}.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not iOS.
@end deffn

@geindex nice() (στη μονάδα os)
@anchor{library/os os nice}@anchor{14ad}
@deffn {Συνάρτηση} os.nice (increment, /)

Add `increment' to the process’s «niceness».  Return the new niceness.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.
@end deffn

@geindex pidfd_open() (στη μονάδα os)
@anchor{library/os os pidfd_open}@anchor{267}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Linux >= 5.3, Android >= @ref{f49,,build-time} API level 31


Added in version 3.9.


@geindex PIDFD_NONBLOCK (στη μονάδα os)
@anchor{library/os os PIDFD_NONBLOCK}@anchor{8ab}
@deffn {Δεδομένα} 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{28f9,,EAGAIN} rather than blocking.
@end deffn

@ref{232d,,Διαθεσιμότητα}: Linux >= 5.10


Added in version 3.12.

@end deffn

@geindex plock() (στη μονάδα os)
@anchor{library/os os plock}@anchor{3328}
@deffn {Συνάρτηση} os.plock (op, /)

Lock program segments into memory.  The value of `op' (defined in
@code{<sys/lock.h>}) determines which segments are locked.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not iOS.
@end deffn

@geindex popen() (στη μονάδα os)
@anchor{library/os os popen}@anchor{585}
@deffn {Συνάρτηση} 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{32b,,open()} function. The
returned file object reads or writes text strings rather than bytes.

The @code{close} method returns @ref{a65,,None} if the subprocess exited
successfully, or the subprocess’s return code if there was an
error. On POSIX systems, if the return code is positive it
represents the return value of the process left-shifted by one
byte.  If the return code is negative, the process was terminated
by the signal given by the negated value of the return code.  (For
example, the return value might be @code{- signal.SIGKILL} if the
subprocess was killed.)  On Windows systems, the return value
contains the signed integer return code from the child process.

On Unix, @ref{cea,,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}).

This is implemented using @ref{6bf,,subprocess.Popen}; see that class’s
documentation for more powerful ways to manage and communicate with
subprocesses.

@ref{232d,,Διαθεσιμότητα}: not WASI, not Android, not iOS.

@cartouche
@quotation Σημείωση 
The @ref{a46,,Python UTF-8 Mode} affects encodings used
for `cmd' and pipe contents.

@code{popen()} is a simple wrapper around @ref{6bf,,subprocess.Popen}.
Use @code{subprocess.Popen} or @ref{f45,,subprocess.run()} to
control options like encodings.
@end quotation
@end cartouche


@ref{1a7,,Soft deprecated} since version 3.14: The @ref{df,,subprocess} module is recommended instead.

@end deffn

@geindex posix_spawn() (στη μονάδα os)
@anchor{library/os os posix_spawn}@anchor{731}
@deffn {Συνάρτηση} 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{f45,,subprocess.run()} instead of @code{posix_spawn()}.

The positional-only arguments `path', `args', and `env' are similar to
@ref{14a5,,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{1949,,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 (στη μονάδα os)
@anchor{library/os os POSIX_SPAWN_OPEN}@anchor{3329}
@deffn {Δεδομένα} 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 (στη μονάδα os)
@anchor{library/os os POSIX_SPAWN_CLOSE}@anchor{332a}
@deffn {Δεδομένα} os.POSIX_SPAWN_CLOSE

(@code{os.POSIX_SPAWN_CLOSE}, `fd')

Performs @code{os.close(fd)}.
@end deffn

@geindex POSIX_SPAWN_DUP2 (στη μονάδα os)
@anchor{library/os os POSIX_SPAWN_DUP2}@anchor{332b}
@deffn {Δεδομένα} 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 (στη μονάδα os)
@anchor{library/os os POSIX_SPAWN_CLOSEFROM}@anchor{732}
@deffn {Δεδομένα} 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{59a,,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{1b2b,,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.

Raises an @ref{1e65,,auditing event} @code{os.posix_spawn} with arguments @code{path}, @code{argv}, @code{env}.


Added in version 3.8.



Άλλαξε στην έκδοση 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{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex posix_spawnp() (στη μονάδα os)
@anchor{library/os os posix_spawnp}@anchor{1949}
@deffn {Συνάρτηση} 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{731,,posix_spawn()} except that the system searches
for the `executable' file in the list of directories specified by the
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} environment variable (in the same way as for @code{execvp(3)}).

Raises an @ref{1e65,,auditing event} @code{os.posix_spawn} with arguments @code{path}, @code{argv}, @code{env}.


Added in version 3.8.


@ref{232d,,Διαθεσιμότητα}: POSIX, not WASI, not Android, not iOS.

See @ref{731,,posix_spawn()} documentation.
@end deffn

@geindex register_at_fork() (στη μονάδα os)
@anchor{library/os os register_at_fork}@anchor{332}
@deffn {Συνάρτηση} os.register_at_fork (*, before=None, after_in_parent=None, after_in_child=None)

Register callables to be executed when a new child process is forked
using @ref{6bd,,os.fork()} or similar process cloning APIs.
The parameters are optional and keyword-only.
Each specifies a different call point.


@itemize *

@item 
`before' is a function called before forking a child process.

@item 
`after_in_parent' is a function called from the parent process
after forking a child process.

@item 
`after_in_child' is a function called from the child process.
@end itemize

These calls are only made if control is expected to return to the
Python interpreter.  A typical @ref{df,,subprocess} launch will not
trigger them as the child is not going to re-enter the interpreter.

Functions registered for execution before forking are called in
reverse registration order.  Functions registered for execution
after forking (either in the parent or in the child) are called
in registration order.

Note that @code{fork()} calls made by third-party C code may not
call those functions, unless it explicitly calls @ref{f7d,,PyOS_BeforeFork()},
@ref{f7e,,PyOS_AfterFork_Parent()} and @ref{643,,PyOS_AfterFork_Child()}.

There is no way to unregister a function.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.


Added in version 3.7.

@end deffn

@geindex spawnl() (στη μονάδα os)
@geindex spawnle() (στη μονάδα os)
@geindex spawnlp() (στη μονάδα os)
@geindex spawnlpe() (στη μονάδα os)
@geindex spawnv() (στη μονάδα os)
@geindex spawnve() (στη μονάδα os)
@geindex spawnvp() (στη μονάδα os)
@geindex spawnvpe() (στη μονάδα os)
@anchor{library/os os spawnl}@anchor{586}
@deffn {Συνάρτηση} os.spawnl (mode, path, ...)
@anchor{library/os os spawnle}@anchor{332c}
@deffnx {Συνάρτηση} os.spawnle (mode, path, ..., env)
@anchor{library/os os spawnlp}@anchor{332d}
@deffnx {Συνάρτηση} os.spawnlp (mode, file, ...)
@anchor{library/os os spawnlpe}@anchor{332e}
@deffnx {Συνάρτηση} os.spawnlpe (mode, file, ..., env)
@anchor{library/os os spawnv}@anchor{332f}
@deffnx {Συνάρτηση} os.spawnv (mode, path, args)
@anchor{library/os os spawnve}@anchor{3330}
@deffnx {Συνάρτηση} os.spawnve (mode, path, args, env)
@anchor{library/os os spawnvp}@anchor{3331}
@deffnx {Συνάρτηση} os.spawnvp (mode, file, args)
@anchor{library/os os spawnvpe}@anchor{3332}
@deffnx {Συνάρτηση} os.spawnvpe (mode, file, args, env)

Execute the program `path' in a new process.

(Note that the @ref{df,,subprocess} module provides more powerful facilities for
spawning new processes and retrieving their results; using that module is
preferable to using these functions.  Check especially the
@ref{1531,,Replacing Older Functions with the subprocess Module} section.)

If `mode' is @ref{3333,,P_NOWAIT}, this function returns the process id of the new
process; if `mode' is @ref{3334,,P_WAIT}, returns the process’s exit code if it
exits normally, or @code{-signal}, where `signal' is the signal that killed the
process.  On Windows, the process id will actually be the process handle, so can
be used with the @ref{1153,,waitpid()} function.

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 @code{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.

The variants which include a second «p» near the end (@code{spawnlp()},
@code{spawnlpe()}, @code{spawnvp()}, and @code{spawnvpe()}) will use the
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} environment variable to locate the program `file'.  When the
environment is being replaced (using one of the @code{spawn*e} variants,
discussed in the next paragraph), the new environment is used as the source of
the 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} variable.  The other variants, @code{spawnl()},
@code{spawnle()}, @code{spawnv()}, and @code{spawnve()}, will not use the
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} variable to locate the executable; `path' must contain an
appropriate absolute or relative path.

For @code{spawnle()}, @code{spawnlpe()}, @code{spawnve()}, and @code{spawnvpe()}
(note that these all end in «e»), the `env' parameter must be a mapping
which is used to define the environment variables for the new process (they are
used instead of the current process” environment); the functions
@code{spawnl()}, @code{spawnlp()}, @code{spawnv()}, and @code{spawnvp()} all cause
the new process to inherit the environment of the current process.  Note that
keys and values in the `env' dictionary must be strings; invalid keys or
values will cause the function to fail, with a return value of @code{127}.

As an example, the following calls to @code{spawnlp()} and @code{spawnvpe()} are
equivalent:

@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

Raises an @ref{1e65,,auditing event} @code{os.spawn} with arguments @code{mode}, @code{path}, @code{args}, @code{env}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows, not WASI, not Android, not iOS.

@code{spawnlp()}, @code{spawnlpe()}, @code{spawnvp()}
and @code{spawnvpe()} are not available on Windows.  @code{spawnle()} and
@code{spawnve()} are not thread-safe on Windows; we advise you to use the
@ref{df,,subprocess} module instead.


Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



@ref{1a7,,Soft deprecated} since version 3.14: The @ref{df,,subprocess} module is recommended instead.

@end deffn

@geindex P_NOWAIT (στη μονάδα os)
@geindex P_NOWAITO (στη μονάδα os)
@anchor{library/os os P_NOWAIT}@anchor{3333}
@deffn {Δεδομένα} os.P_NOWAIT
@anchor{library/os os P_NOWAITO}@anchor{3335}
@deffnx {Δεδομένα} os.P_NOWAITO

Possible values for the `mode' parameter to the @ref{586,,spawn*} family of
functions.  If either of these values is given, the @code{spawn*} functions
will return as soon as the new process has been created, with the process id as
the return value.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.
@end deffn

@geindex P_WAIT (στη μονάδα os)
@anchor{library/os os P_WAIT}@anchor{3334}
@deffn {Δεδομένα} os.P_WAIT

Possible value for the `mode' parameter to the @ref{586,,spawn*} family of
functions.  If this is given as `mode', the @code{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{232d,,Διαθεσιμότητα}: Unix, Windows.
@end deffn

@geindex P_DETACH (στη μονάδα os)
@geindex P_OVERLAY (στη μονάδα os)
@anchor{library/os os P_DETACH}@anchor{3336}
@deffn {Δεδομένα} os.P_DETACH
@anchor{library/os os P_OVERLAY}@anchor{3337}
@deffnx {Δεδομένα} os.P_OVERLAY

Possible values for the `mode' parameter to the @ref{586,,spawn*} family of
functions.  These are less portable than those listed above. @ref{3336,,P_DETACH}
is similar to @ref{3333,,P_NOWAIT}, but the new process is detached from the
console of the calling process. If @ref{3337,,P_OVERLAY} is used, the current
process will be replaced; the @code{spawn*} function will not return.

@ref{232d,,Διαθεσιμότητα}: Windows.
@end deffn

@geindex startfile() (στη μονάδα os)
@anchor{library/os os startfile}@anchor{1e79}
@deffn {Συνάρτηση} os.startfile (path[, operation][, arguments][, cwd][, show_cmd])

Start a file with its associated application.

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.

@code{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{a8,,pathlib} or the
@ref{16be,,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{59a,,NotImplementedError} will be raised.

Raises an @ref{1e65,,auditing event} @code{os.startfile} with arguments @code{path}, @code{operation}.

Raises an @ref{1e65,,auditing event} @code{os.startfile/2} with arguments @code{path}, @code{operation}, @code{arguments}, @code{cwd}, @code{show_cmd}.

@ref{232d,,Διαθεσιμότητα}: Windows.


Άλλαξε στην έκδοση 3.10: Added the `arguments', `cwd' and `show_cmd' arguments, and the
@code{os.startfile/2} audit event.

@end deffn

@geindex system() (στη μονάδα os)
@anchor{library/os os system}@anchor{17ff}
@deffn {Συνάρτηση} 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{94a,,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{1151,,wait()}.

On Windows, the return value is that returned by the system shell after
running `command'.  The shell is given by the Windows environment variable
@geindex COMSPEC
@geindex μεταβλητή περιβάλλοντος; COMSPEC
@code{COMSPEC}: it is usually @code{cmd.exe}, which returns the exit
status of the command run; on systems using a non-native shell, consult your
shell documentation.

The @ref{df,,subprocess} module provides more powerful facilities for spawning
new processes and retrieving their results; using that module is recommended
to using this function.  See the @ref{1531,,Replacing Older Functions with the subprocess Module} section in
the @code{subprocess} documentation for some helpful recipes.

On Unix, @ref{cea,,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.

Raises an @ref{1e65,,auditing event} @code{os.system} with argument @code{command}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows, not WASI, not Android, not iOS.
@end deffn

@geindex times() (στη μονάδα os)
@anchor{library/os os times}@anchor{14c1}
@deffn {Συνάρτηση} os.times ()

Returns the current global process times.
The return value is an object with five attributes:


@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{232d,,Διαθεσιμότητα}: Unix, Windows.


Άλλαξε στην έκδοση 3.3: Return type changed from a tuple to a tuple-like object
with named attributes.

@end deffn

@geindex wait() (στη μονάδα os)
@anchor{library/os os wait}@anchor{1151}
@deffn {Συνάρτηση} os.wait ()

Wait for completion of a child process, and return a tuple containing its pid
and exit status indication: a 16-bit number, whose low byte is the signal number
that killed the process, and whose high byte is the exit status (if the signal
number is zero); the high bit of the low byte is set if a core file was
produced.

If there are no children that could be waited for, @ref{1400,,ChildProcessError}
is raised.

@ref{cea,,waitstatus_to_exitcode()} can be used to convert the exit status into an
exit code.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.


@subsubheading Δείτε επίσης


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{1153,,waitpid()} is the only one also available on Windows.

@end deffn

@geindex waitid() (στη μονάδα os)
@anchor{library/os os waitid}@anchor{1152}
@deffn {Συνάρτηση} os.waitid (idtype, id, options, /)

Wait for the completion of a child process.

`idtype' can be @ref{3338,,P_PID}, @ref{3339,,P_PGID}, @ref{333a,,P_ALL}, or (on Linux) @ref{ce9,,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{333b,,WEXITED},
@ref{333c,,WSTOPPED} or @ref{333d,,WCONTINUED} is required;
@ref{333e,,WNOHANG} and @ref{333f,,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{3340,,SIGCHLD})

@item 
@code{si_status} (the exit status or signal number, depending on @code{si_code})

@item 
@code{si_code} (see @ref{3341,,CLD_EXITED} for possible values)
@end itemize

If @ref{333e,,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{1400,,ChildProcessError} is raised.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.


Added in version 3.3.



Άλλαξε στην έκδοση 3.13: This function is now available on macOS as well.

@end deffn

@geindex waitpid() (στη μονάδα os)
@anchor{library/os os waitpid}@anchor{1153}
@deffn {Συνάρτηση} os.waitpid (pid, options, /)

The details of this function differ on Unix and Windows.

On Unix: Wait for completion of a child process given by process id `pid', and
return a tuple containing its process id and exit status indication (encoded as
for @ref{1151,,wait()}).  The semantics of the call are affected by the value of the
integer `options', which should be @code{0} for normal operation.

If `pid' is greater than @code{0}, @code{waitpid()} requests status information for
that specific process.  If `pid' is @code{0}, the request is for the status of any
child in the process group of the current process.  If `pid' is @code{-1}, the
request pertains to any child of the current process.  If `pid' is less than
@code{-1}, status is requested for any process in the process group @code{-pid} (the
absolute value of `pid').

`options' is an OR combination of flags.  If it contains @ref{333e,,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{1400,,ChildProcessError} is raised.  Other options that can be used are
@ref{3342,,WUNTRACED} and @ref{333d,,WCONTINUED}.

On Windows: Wait for completion of a process given by process handle `pid', and
return a tuple containing `pid', and its exit status shifted left by 8 bits
(shifting makes cross-platform use of the function easier). A `pid' less than or
equal to @code{0} has no special meaning on Windows, and raises an exception. The
value of integer `options' has no effect. `pid' can refer to any process whose
id is known, not necessarily a child process. The @ref{586,,spawn*}
functions called with @ref{3333,,P_NOWAIT} return suitable process handles.

@ref{cea,,waitstatus_to_exitcode()} can be used to convert the exit status into an
exit code.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows, not WASI, not Android, not iOS.


Άλλαξε στην έκδοση 3.5: If the system call is interrupted and the signal handler does not raise an
exception, the function now retries the system call instead of raising an
@ref{1141,,InterruptedError} exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).

@end deffn

@geindex wait3() (στη μονάδα os)
@anchor{library/os os wait3}@anchor{114f}
@deffn {Συνάρτηση} os.wait3 (options)

Similar to @ref{1153,,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{17d3,,resource.getrusage()} for details on resource usage information.  The
`options' argument is the same as that provided to @code{waitpid()} and
@ref{1150,,wait4()}.

@ref{cea,,waitstatus_to_exitcode()} can be used to convert the exit status into an
exitcode.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex wait4() (στη μονάδα os)
@anchor{library/os os wait4}@anchor{1150}
@deffn {Συνάρτηση} os.wait4 (pid, options)

Similar to @ref{1153,,waitpid()}, except a 3-element tuple, containing the child’s
process id, exit status indication, and resource usage information is
returned.  Refer to @ref{17d3,,resource.getrusage()} for details on resource usage
information.  The arguments to @code{wait4()} are the same as those provided
to @code{waitpid()}.

@ref{cea,,waitstatus_to_exitcode()} can be used to convert the exit status into an
exitcode.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex P_PID (στη μονάδα os)
@geindex P_PGID (στη μονάδα os)
@geindex P_ALL (στη μονάδα os)
@geindex P_PIDFD (στη μονάδα os)
@anchor{library/os os P_PID}@anchor{3338}
@deffn {Δεδομένα} os.P_PID
@anchor{library/os os P_PGID}@anchor{3339}
@deffnx {Δεδομένα} os.P_PGID
@anchor{library/os os P_ALL}@anchor{333a}
@deffnx {Δεδομένα} os.P_ALL
@anchor{library/os os P_PIDFD}@anchor{ce9}
@deffnx {Δεδομένα} os.P_PIDFD

These are the possible values for `idtype' in @ref{1152,,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{267,,pidfd_open()}).
@end itemize

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.

@cartouche
@quotation Σημείωση 
@code{P_PIDFD} is only available on Linux >= 5.4.
@end quotation
@end cartouche


Added in version 3.3.



Added in version 3.9: The @code{P_PIDFD} constant.

@end deffn

@geindex WCONTINUED (στη μονάδα os)
@anchor{library/os os WCONTINUED}@anchor{333d}
@deffn {Δεδομένα} os.WCONTINUED

This `options' flag for @ref{1153,,waitpid()}, @ref{114f,,wait3()}, @ref{1150,,wait4()}, and
@ref{1152,,waitid()} causes child processes to be reported if they have been
continued from a job control stop since they were last reported.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WEXITED (στη μονάδα os)
@anchor{library/os os WEXITED}@anchor{333b}
@deffn {Δεδομένα} os.WEXITED

This `options' flag for @ref{1152,,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{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.


Added in version 3.3.

@end deffn

@geindex WSTOPPED (στη μονάδα os)
@anchor{library/os os WSTOPPED}@anchor{333c}
@deffn {Δεδομένα} os.WSTOPPED

This `options' flag for @ref{1152,,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{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.


Added in version 3.3.

@end deffn

@geindex WUNTRACED (στη μονάδα os)
@anchor{library/os os WUNTRACED}@anchor{3342}
@deffn {Δεδομένα} os.WUNTRACED

This `options' flag for @ref{1153,,waitpid()}, @ref{114f,,wait3()}, and @ref{1150,,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{1152,,waitid()}.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WNOHANG (στη μονάδα os)
@anchor{library/os os WNOHANG}@anchor{333e}
@deffn {Δεδομένα} os.WNOHANG

This `options' flag causes @ref{1153,,waitpid()}, @ref{114f,,wait3()}, @ref{1150,,wait4()}, and
@ref{1152,,waitid()} to return right away if no child process status is available
immediately.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WNOWAIT (στη μονάδα os)
@anchor{library/os os WNOWAIT}@anchor{333f}
@deffn {Δεδομένα} os.WNOWAIT

This `options' flag causes @ref{1152,,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{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex CLD_EXITED (στη μονάδα os)
@geindex CLD_KILLED (στη μονάδα os)
@geindex CLD_DUMPED (στη μονάδα os)
@geindex CLD_TRAPPED (στη μονάδα os)
@geindex CLD_STOPPED (στη μονάδα os)
@geindex CLD_CONTINUED (στη μονάδα os)
@anchor{library/os os CLD_EXITED}@anchor{3341}
@deffn {Δεδομένα} os.CLD_EXITED
@anchor{library/os os CLD_KILLED}@anchor{ce7}
@deffnx {Δεδομένα} os.CLD_KILLED
@anchor{library/os os CLD_DUMPED}@anchor{3343}
@deffnx {Δεδομένα} os.CLD_DUMPED
@anchor{library/os os CLD_TRAPPED}@anchor{3344}
@deffnx {Δεδομένα} os.CLD_TRAPPED
@anchor{library/os os CLD_STOPPED}@anchor{ce8}
@deffnx {Δεδομένα} os.CLD_STOPPED
@anchor{library/os os CLD_CONTINUED}@anchor{3345}
@deffnx {Δεδομένα} os.CLD_CONTINUED

These are the possible values for @code{si_code} in the result returned by
@ref{1152,,waitid()}.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.


Added in version 3.3.



Άλλαξε στην έκδοση 3.9: Added @code{CLD_KILLED} and @code{CLD_STOPPED} values.

@end deffn

@geindex waitstatus_to_exitcode() (στη μονάδα os)
@anchor{library/os os waitstatus_to_exitcode}@anchor{cea}
@deffn {Συνάρτηση} 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{277,,ValueError}.
@end itemize

On Windows, return `status' shifted right by 8 bits.

On Unix, if the process is being traced or if @ref{1153,,waitpid()} was called
with @ref{3342,,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 Δείτε επίσης


@ref{3346,,WIFEXITED()}, @ref{3347,,WEXITSTATUS()}, @ref{3348,,WIFSIGNALED()},
@ref{3349,,WTERMSIG()}, @ref{334a,,WIFSTOPPED()}, @ref{334b,,WSTOPSIG()} functions.


@ref{232d,,Διαθεσιμότητα}: Unix, Windows, not WASI, not Android, not iOS.


Added in version 3.9.

@end deffn

The following functions take a process status code as returned by
@ref{17ff,,system()}, @ref{1151,,wait()}, or @ref{1153,,waitpid()} as a parameter.  They may be
used to determine the disposition of a process.

@geindex WCOREDUMP() (στη μονάδα os)
@anchor{library/os os WCOREDUMP}@anchor{334c}
@deffn {Συνάρτηση} os.WCOREDUMP (status, /)

Return @code{True} if a core dump was generated for the process, otherwise
return @code{False}.

This function should be employed only if @ref{3348,,WIFSIGNALED()} is true.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WIFCONTINUED() (στη μονάδα os)
@anchor{library/os os WIFCONTINUED}@anchor{334d}
@deffn {Συνάρτηση} os.WIFCONTINUED (status)

Return @code{True} if a stopped child has been resumed by delivery of
@ref{334e,,SIGCONT} (if the process has been continued from a job
control stop), otherwise return @code{False}.

See @ref{333d,,WCONTINUED} option.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WIFSTOPPED() (στη μονάδα os)
@anchor{library/os os WIFSTOPPED}@anchor{334a}
@deffn {Συνάρτηση} os.WIFSTOPPED (status)

Return @code{True} if the process was stopped by delivery of a signal,
otherwise return @code{False}.

@code{WIFSTOPPED()} only returns @code{True} if the @ref{1153,,waitpid()} call was
done using @ref{3342,,WUNTRACED} option or when the process is being traced (see
@code{ptrace(2)@footnote{https://manpages.debian.org/ptrace(2)}}).

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WIFSIGNALED() (στη μονάδα os)
@anchor{library/os os WIFSIGNALED}@anchor{3348}
@deffn {Συνάρτηση} os.WIFSIGNALED (status)

Return @code{True} if the process was terminated by a signal, otherwise return
@code{False}.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WIFEXITED() (στη μονάδα os)
@anchor{library/os os WIFEXITED}@anchor{3346}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WEXITSTATUS() (στη μονάδα os)
@anchor{library/os os WEXITSTATUS}@anchor{3347}
@deffn {Συνάρτηση} os.WEXITSTATUS (status)

Return the process exit status.

This function should be employed only if @ref{3346,,WIFEXITED()} is true.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WSTOPSIG() (στη μονάδα os)
@anchor{library/os os WSTOPSIG}@anchor{334b}
@deffn {Συνάρτηση} os.WSTOPSIG (status)

Return the signal which caused the process to stop.

This function should be employed only if @ref{334a,,WIFSTOPPED()} is true.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WTERMSIG() (στη μονάδα os)
@anchor{library/os os WTERMSIG}@anchor{3349}
@deffn {Συνάρτηση} os.WTERMSIG (status)

Return the number of the signal that caused the process to terminate.

This function should be employed only if @ref{3348,,WIFSIGNALED()} is true.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not Android, not iOS.
@end deffn

@node Interface to the scheduler,Miscellaneous System Information,Process Management,os — Miscellaneous operating system interfaces
@anchor{library/os interface-to-the-scheduler}@anchor{334f}
@subsubsection Interface to the scheduler


These functions control how a process is allocated CPU time by the operating
system. They are only available on some Unix platforms. For more detailed
information, consult your Unix manpages.


Added in version 3.3.


The following scheduling policies are exposed if they are supported by the
operating system.

@geindex SCHED_OTHER (στη μονάδα os)
@anchor{library/os os-scheduling-policy}@anchor{3350}@anchor{library/os os SCHED_OTHER}@anchor{3351}
@deffn {Δεδομένα} os.SCHED_OTHER

The default scheduling policy.
@end deffn

@geindex SCHED_BATCH (στη μονάδα os)
@anchor{library/os os SCHED_BATCH}@anchor{3352}
@deffn {Δεδομένα} os.SCHED_BATCH

Scheduling policy for CPU-intensive processes that tries to preserve
interactivity on the rest of the computer.
@end deffn

@geindex SCHED_DEADLINE (στη μονάδα os)
@anchor{library/os os SCHED_DEADLINE}@anchor{4e9}
@deffn {Δεδομένα} os.SCHED_DEADLINE

Scheduling policy for tasks with deadline constraints.


Added in version 3.14.

@end deffn

@geindex SCHED_IDLE (στη μονάδα os)
@anchor{library/os os SCHED_IDLE}@anchor{3353}
@deffn {Δεδομένα} os.SCHED_IDLE

Scheduling policy for extremely low priority background tasks.
@end deffn

@geindex SCHED_NORMAL (στη μονάδα os)
@anchor{library/os os SCHED_NORMAL}@anchor{4ea}
@deffn {Δεδομένα} os.SCHED_NORMAL

Alias for @ref{3351,,SCHED_OTHER}.


Added in version 3.14.

@end deffn

@geindex SCHED_SPORADIC (στη μονάδα os)
@anchor{library/os os SCHED_SPORADIC}@anchor{3354}
@deffn {Δεδομένα} os.SCHED_SPORADIC

Scheduling policy for sporadic server programs.
@end deffn

@geindex SCHED_FIFO (στη μονάδα os)
@anchor{library/os os SCHED_FIFO}@anchor{3355}
@deffn {Δεδομένα} os.SCHED_FIFO

A First In First Out scheduling policy.
@end deffn

@geindex SCHED_RR (στη μονάδα os)
@anchor{library/os os SCHED_RR}@anchor{3356}
@deffn {Δεδομένα} os.SCHED_RR

A round-robin scheduling policy.
@end deffn

@geindex SCHED_RESET_ON_FORK (στη μονάδα os)
@anchor{library/os os SCHED_RESET_ON_FORK}@anchor{3357}
@deffn {Δεδομένα} os.SCHED_RESET_ON_FORK

This flag can be OR’ed with any other scheduling policy. When a process with
this flag set forks, its child’s scheduling policy and priority are reset to
the default.
@end deffn

@geindex sched_param (κλάση σε os)
@anchor{library/os os sched_param}@anchor{1b2b}
@deffn {Κλάση} os.sched_param (sched_priority)

This class represents tunable scheduling parameters used in
@ref{14bb,,sched_setparam()}, @ref{14bc,,sched_setscheduler()}, and
@ref{14b7,,sched_getparam()}. It is immutable.

At the moment, there is only one possible parameter:

@geindex sched_priority (ιδιότητα της os.sched_param)
@anchor{library/os os sched_param sched_priority}@anchor{3358}
@deffn {Ιδιότητα} sched_priority

The scheduling priority for a scheduling policy.
@end deffn
@end deffn

@geindex sched_get_priority_min() (στη μονάδα os)
@anchor{library/os os sched_get_priority_min}@anchor{14b5}
@deffn {Συνάρτηση} os.sched_get_priority_min (policy)

Get the minimum priority value for `policy'. `policy' is one of the
scheduling policy constants above.
@end deffn

@geindex sched_get_priority_max() (στη μονάδα os)
@anchor{library/os os sched_get_priority_max}@anchor{14b4}
@deffn {Συνάρτηση} os.sched_get_priority_max (policy)

Get the maximum priority value for `policy'. `policy' is one of the
scheduling policy constants above.
@end deffn

@geindex sched_setscheduler() (στη μονάδα os)
@anchor{library/os os sched_setscheduler}@anchor{14bc}
@deffn {Συνάρτηση} os.sched_setscheduler (pid, policy, param, /)

Set the scheduling policy for the process with PID `pid'. A `pid' of 0 means
the calling process. `policy' is one of the scheduling policy constants
above. `param' is a @ref{1b2b,,sched_param} instance.
@end deffn

@geindex sched_getscheduler() (στη μονάδα os)
@anchor{library/os os sched_getscheduler}@anchor{14b8}
@deffn {Συνάρτηση} os.sched_getscheduler (pid, /)

Return the scheduling policy for the process with PID `pid'. A `pid' of 0
means the calling process. The result is one of the scheduling policy
constants above.
@end deffn

@geindex sched_setparam() (στη μονάδα os)
@anchor{library/os os sched_setparam}@anchor{14bb}
@deffn {Συνάρτηση} 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{1b2b,,sched_param} instance.
@end deffn

@geindex sched_getparam() (στη μονάδα os)
@anchor{library/os os sched_getparam}@anchor{14b7}
@deffn {Συνάρτηση} os.sched_getparam (pid, /)

Return the scheduling parameters as a @ref{1b2b,,sched_param} instance for the
process with PID `pid'. A `pid' of 0 means the calling process.
@end deffn

@geindex sched_rr_get_interval() (στη μονάδα os)
@anchor{library/os os sched_rr_get_interval}@anchor{14b9}
@deffn {Συνάρτηση} os.sched_rr_get_interval (pid, /)

Return the round-robin quantum in seconds for the process with PID `pid'. A
`pid' of 0 means the calling process.
@end deffn

@geindex sched_yield() (στη μονάδα os)
@anchor{library/os os sched_yield}@anchor{14bd}
@deffn {Συνάρτηση} os.sched_yield ()

Voluntarily relinquish the CPU. See @code{sched_yield(2)@footnote{https://manpages.debian.org/sched_yield(2)}} for details.
@end deffn

@geindex sched_setaffinity() (στη μονάδα os)
@anchor{library/os os sched_setaffinity}@anchor{14ba}
@deffn {Συνάρτηση} os.sched_setaffinity (pid, mask, /)

Restrict the process with PID `pid' (or the current process if zero) to a
set of CPUs.  `mask' is an iterable of integers representing the set of
CPUs to which the process should be restricted.
@end deffn

@geindex sched_getaffinity() (στη μονάδα os)
@anchor{library/os os sched_getaffinity}@anchor{14b6}
@deffn {Συνάρτηση} 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{6e0,,process_cpu_count()} function.
@end deffn

@node Miscellaneous System Information,Random numbers<2>,Interface to the scheduler,os — Miscellaneous operating system interfaces
@anchor{library/os miscellaneous-system-information}@anchor{3359}@anchor{library/os os-path}@anchor{335a}
@subsubsection Miscellaneous System Information


@geindex confstr() (στη μονάδα os)
@anchor{library/os os confstr}@anchor{1b0c}
@deffn {Συνάρτηση} os.confstr (name, /)

Return string-valued system configuration values. `name' specifies the
configuration value to retrieve; it may be a string which is the name of a
defined system value; these names are specified in a number of standards (POSIX,
Unix 95, Unix 98, and others).  Some platforms define additional names as well.
The names known to the host operating system are given as the keys of the
@code{confstr_names} dictionary.  For configuration variables not included in that
mapping, passing an integer for `name' is also accepted.

If the configuration value specified by `name' isn’t defined, @code{None} is
returned.

If `name' is a string and is not known, @ref{277,,ValueError} is raised.  If a
specific value for `name' is not supported by the host system, even if it is
included in @code{confstr_names}, an @ref{53c,,OSError} is raised with
@ref{1fc1,,errno.EINVAL} for the error number.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex confstr_names (στη μονάδα os)
@anchor{library/os os confstr_names}@anchor{335b}
@deffn {Δεδομένα} os.confstr_names

Dictionary mapping names accepted by @ref{1b0c,,confstr()} to the integer values
defined for those names by the host operating system. This can be used to
determine the set of names known to the system.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex cpu_count() (στη μονάδα os)
@anchor{library/os os cpu_count}@anchor{6e1}
@deffn {Συνάρτηση} os.cpu_count ()

Return the number of logical CPUs in the `system'. Returns @code{None} if
undetermined.

The @ref{6e0,,process_cpu_count()} function can be used to get the number of
logical CPUs usable by the calling thread of the `current process'.


Added in version 3.4.



Άλλαξε στην έκδοση 3.13: If @ref{178,,-X cpu_count} is given or 
@geindex PYTHON_CPU_COUNT
@geindex μεταβλητή περιβάλλοντος; PYTHON_CPU_COUNT
@ref{721,,PYTHON_CPU_COUNT} is set,
@code{cpu_count()} returns the override value `n'.

@end deffn

@geindex getloadavg() (στη μονάδα os)
@anchor{library/os os getloadavg}@anchor{1b40}
@deffn {Συνάρτηση} os.getloadavg ()

Return the number of processes in the system run queue averaged over the last
1, 5, and 15 minutes or raises @ref{53c,,OSError} if the load average was
unobtainable.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex process_cpu_count() (στη μονάδα os)
@anchor{library/os os process_cpu_count}@anchor{6e0}
@deffn {Συνάρτηση} 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{6e1,,cpu_count()} depending on the CPU affinity.

The @ref{6e1,,cpu_count()} function can be used to get the number of logical CPUs
in the `system'.

If @ref{178,,-X cpu_count} is given or 
@geindex PYTHON_CPU_COUNT
@geindex μεταβλητή περιβάλλοντος; PYTHON_CPU_COUNT
@ref{721,,PYTHON_CPU_COUNT} is set,
@code{process_cpu_count()} returns the override value `n'.

See also the @ref{14b6,,sched_getaffinity()} function.


Added in version 3.13.

@end deffn

@geindex sysconf() (στη μονάδα os)
@anchor{library/os os sysconf}@anchor{1b0d}
@deffn {Συνάρτηση} os.sysconf (name, /)

Return integer-valued system configuration values. If the configuration value
specified by `name' isn’t defined, @code{-1} is returned.  The comments regarding
the `name' parameter for @ref{1b0c,,confstr()} apply here as well; the dictionary that
provides information on the known names is given by @code{sysconf_names}.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex sysconf_names (στη μονάδα os)
@anchor{library/os os sysconf_names}@anchor{335c}
@deffn {Δεδομένα} os.sysconf_names

Dictionary mapping names accepted by @ref{1b0d,,sysconf()} to the integer values
defined for those names by the host operating system. This can be used to
determine the set of names known to the system.

@ref{232d,,Διαθεσιμότητα}: Unix.


Άλλαξε στην έκδοση 3.11: Add @code{'SC_MINSIGSTKSZ'} name.

@end deffn

The following data values are used to support path manipulation operations.  These
are defined for all platforms.

Higher-level operations on pathnames are defined in the @ref{a6,,os.path} module.

@geindex . (dot);in pathnames

@geindex curdir (στη μονάδα os)
@anchor{library/os os curdir}@anchor{2e73}
@deffn {Δεδομένα} os.curdir

The constant string used by the operating system to refer to the current
directory. This is @code{'.'} for Windows and POSIX. Also available via
@ref{a6,,os.path}.
@end deffn

@geindex ..;in pathnames

@geindex pardir (στη μονάδα os)
@anchor{library/os os pardir}@anchor{32a2}
@deffn {Δεδομένα} os.pardir

The constant string used by the operating system to refer to the parent
directory. This is @code{'..'} for Windows and POSIX. Also available via
@ref{a6,,os.path}.
@end deffn

@geindex / (slash);in pathnames

@geindex \ (backslash);in pathnames (Windows)

@geindex sep (στη μονάδα os)
@anchor{library/os os sep}@anchor{a5a}
@deffn {Δεδομένα} os.sep

The character used by the operating system to separate pathname components.
This is @code{'/'} for POSIX and @code{'\\'} for Windows.  Note that knowing this
is not sufficient to be able to parse or concatenate pathnames — use
@ref{2e6c,,os.path.split()} and @ref{1a42,,os.path.join()} — but it is occasionally
useful. Also available via @ref{a6,,os.path}.
@end deffn

@geindex / (slash);in pathnames

@geindex altsep (στη μονάδα os)
@anchor{library/os os altsep}@anchor{a5b}
@deffn {Δεδομένα} os.altsep

An alternative character used by the operating system to separate pathname
components, or @code{None} if only one separator character exists.  This is set to
@code{'/'} on Windows systems where @code{sep} is a backslash. Also available via
@ref{a6,,os.path}.
@end deffn

@geindex . (dot);in pathnames

@geindex extsep (στη μονάδα os)
@anchor{library/os os extsep}@anchor{335d}
@deffn {Δεδομένα} os.extsep

The character which separates the base filename from the extension; for example,
the @code{'.'} in @code{os.py}. Also available via @ref{a6,,os.path}.
@end deffn

@geindex ; (colon);path separator (POSIX)
@geindex ; (semicolon)

@geindex pathsep (στη μονάδα os)
@anchor{library/os os pathsep}@anchor{2322}
@deffn {Δεδομένα} os.pathsep

The character conventionally used by the operating system to separate search
path components (as in 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}), such as @code{':'} for POSIX or @code{';'} for
Windows. Also available via @ref{a6,,os.path}.
@end deffn

@geindex defpath (στη μονάδα os)
@anchor{library/os os defpath}@anchor{1fd3}
@deffn {Δεδομένα} os.defpath

The default search path used by @ref{3310,,exec*p*} and
@ref{586,,spawn*p*} if the environment doesn’t have a @code{'PATH'}
key. Also available via @ref{a6,,os.path}.
@end deffn

@geindex linesep (στη μονάδα os)
@anchor{library/os os linesep}@anchor{27d5}
@deffn {Δεδομένα} os.linesep

The string used to separate (or, rather, terminate) lines on the current
platform.  This may be a single character, such as @code{'\n'} for POSIX, or
multiple characters, for example, @code{'\r\n'} for Windows. Do not use
`os.linesep' as a line terminator when writing files opened in text mode (the
default); use a single @code{'\n'} instead, on all platforms.
@end deffn

@geindex devnull (στη μονάδα os)
@anchor{library/os os devnull}@anchor{2002}
@deffn {Δεδομένα} os.devnull

The file path of the null device. For example: @code{'/dev/null'} for
POSIX, @code{'nul'} for Windows.  Also available via @ref{a6,,os.path}.
@end deffn

@geindex RTLD_LAZY (στη μονάδα os)
@geindex RTLD_NOW (στη μονάδα os)
@geindex RTLD_GLOBAL (στη μονάδα os)
@geindex RTLD_LOCAL (στη μονάδα os)
@geindex RTLD_NODELETE (στη μονάδα os)
@geindex RTLD_NOLOAD (στη μονάδα os)
@geindex RTLD_DEEPBIND (στη μονάδα os)
@anchor{library/os os RTLD_LAZY}@anchor{14c4}
@deffn {Δεδομένα} os.RTLD_LAZY
@anchor{library/os os RTLD_NOW}@anchor{14c5}
@deffnx {Δεδομένα} os.RTLD_NOW
@anchor{library/os os RTLD_GLOBAL}@anchor{14c6}
@deffnx {Δεδομένα} os.RTLD_GLOBAL
@anchor{library/os os RTLD_LOCAL}@anchor{14c7}
@deffnx {Δεδομένα} os.RTLD_LOCAL
@anchor{library/os os RTLD_NODELETE}@anchor{14c8}
@deffnx {Δεδομένα} os.RTLD_NODELETE
@anchor{library/os os RTLD_NOLOAD}@anchor{14c9}
@deffnx {Δεδομένα} os.RTLD_NOLOAD
@anchor{library/os os RTLD_DEEPBIND}@anchor{14ca}
@deffnx {Δεδομένα} os.RTLD_DEEPBIND

Flags for use with the @ref{14cb,,setdlopenflags()} and
@ref{18b0,,getdlopenflags()} functions.  See the Unix manual page
@code{dlopen(3)@footnote{https://manpages.debian.org/dlopen(3)}} for what the different flags mean.


Added in version 3.3.

@end deffn

@node Random numbers<2>,,Miscellaneous System Information,os — Miscellaneous operating system interfaces
@anchor{library/os random-numbers}@anchor{335e}
@subsubsection Random numbers


@geindex getrandom() (στη μονάδα os)
@anchor{library/os os getrandom}@anchor{107b}
@deffn {Συνάρτηση} os.getrandom (size, flags=0)

Get up to `size' random bytes. The function can return less bytes than
requested.

These bytes can be used to seed user-space random number generators or for
cryptographic purposes.

@code{getrandom()} relies on entropy gathered from device drivers and other
sources of environmental noise. Unnecessarily reading large quantities of
data will have a negative impact on  other users  of the @code{/dev/random} and
@code{/dev/urandom} devices.

The flags argument is a bit mask that can contain zero or more of the
following values ORed together: @ref{335f,,os.GRND_RANDOM} and
@ref{3360,,GRND_NONBLOCK}.

See also the Linux getrandom() manual page@footnote{https://man7.org/linux/man-pages/man2/getrandom.2.html}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 3.17.


Added in version 3.6.

@end deffn

@geindex urandom() (στη μονάδα os)
@anchor{library/os os urandom}@anchor{931}
@deffn {Συνάρτηση} os.urandom (size, /)

Return a bytestring of `size' random bytes suitable for cryptographic use.

This function returns random bytes from an OS-specific randomness source.  The
returned data should be unpredictable enough for cryptographic applications,
though its exact quality depends on the OS implementation.

On Linux, if the @code{getrandom()} syscall is available, it is used in
blocking mode: block until the system urandom entropy pool is initialized
(128 bits of entropy are collected by the kernel). See the 
@geindex Python Enhancement Proposals; PEP 524
PEP 524@footnote{https://peps.python.org/pep-0524/} for
the rationale. On Linux, the @ref{107b,,getrandom()} function can be used to get
random bytes in non-blocking mode (using the @ref{3360,,GRND_NONBLOCK} flag) or
to poll until the system urandom entropy pool is initialized.

On a Unix-like system, random bytes are read from the @code{/dev/urandom}
device. If the @code{/dev/urandom} device is not available or not readable, the
@ref{59a,,NotImplementedError} exception is raised.

On Windows, it will use @code{BCryptGenRandom()}.


@subsubheading Δείτε επίσης


The @ref{c8,,secrets} module provides higher level functions. For an
easy-to-use interface to the random number generator provided by your
platform, please see @ref{2d75,,random.SystemRandom}.



Άλλαξε στην έκδοση 3.5: On Linux 3.17 and newer, the @code{getrandom()} syscall is now used
when available.  On OpenBSD 5.6 and newer, the C @code{getentropy()}
function is now used. These functions avoid the usage of an internal file
descriptor.



Άλλαξε στην έκδοση 3.5.2: On Linux, if the @code{getrandom()} syscall blocks (the urandom entropy pool
is not initialized yet), fall back on reading @code{/dev/urandom}.



Άλλαξε στην έκδοση 3.6: On Linux, @code{getrandom()} is now used in blocking mode to increase the
security.



Άλλαξε στην έκδοση 3.11: On Windows, @code{BCryptGenRandom()} is used instead of @code{CryptGenRandom()}
which is deprecated.

@end deffn

@geindex GRND_NONBLOCK (στη μονάδα os)
@anchor{library/os os GRND_NONBLOCK}@anchor{3360}
@deffn {Δεδομένα} os.GRND_NONBLOCK

By  default, when reading from @code{/dev/random}, @ref{107b,,getrandom()} blocks if
no random bytes are available, and when reading from @code{/dev/urandom}, it blocks
if the entropy pool has not yet been initialized.

If the @code{GRND_NONBLOCK} flag is set, then @ref{107b,,getrandom()} does not
block in these cases, but instead immediately raises @ref{4c3,,BlockingIOError}.


Added in version 3.6.

@end deffn

@geindex GRND_RANDOM (στη μονάδα os)
@anchor{library/os os GRND_RANDOM}@anchor{335f}
@deffn {Δεδομένα} os.GRND_RANDOM

If  this  bit  is  set,  then  random bytes are drawn from the
@code{/dev/random} pool instead of the @code{/dev/urandom} pool.


Added in version 3.6.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node io — Core tools for working with streams,time — Πρόσβαση και μετατροπές χρόνου,os — Miscellaneous operating system interfaces,Generic Operating System Services
@anchor{library/io doc}@anchor{3361}@anchor{library/io io-core-tools-for-working-with-streams}@anchor{3362}@anchor{library/io module-io}@anchor{82}@anchor{library/io translation-repo}@anchor{3363}
@subsection @code{io} — Core tools for working with streams


@geindex module; io

`Source code:' Lib/io.py@footnote{https://github.com/python/cpython/tree/main/Lib/io.py}


__________________________________________________________________


@menu
* Overview: Overview<2>. 
* Text Encoding:: 
* High-level Module Interface:: 
* Class hierarchy:: 
* Static Typing:: 
* Performance: Performance<3>. 

@end menu

@node Overview<2>,Text Encoding,,io — Core tools for working with streams
@anchor{library/io io-overview}@anchor{27d3}@anchor{library/io overview}@anchor{3364}
@subsubsection Overview


@geindex file object;io module

The @code{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{156c,,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{1df,,str} object to the @code{write()} method of a binary stream
will raise a @ref{291,,TypeError}.  So will giving a @ref{1c7,,bytes} object to the
@code{write()} method of a text stream.


Άλλαξε στην έκδοση 3.3: Operations that used to raise @ref{13fb,,IOError} now raise @ref{53c,,OSError}, since
@code{IOError} is now an alias of @code{OSError}.


@menu
* Text I/O:: 
* Binary I/O:: 
* Raw I/O:: 

@end menu

@node Text I/O,Binary I/O,,Overview<2>
@anchor{library/io text-i-o}@anchor{3365}
@subsubsection Text I/O


Text I/O expects and produces @ref{1df,,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{32b,,open()}, optionally
specifying an encoding:

@example
f = open("myfile.txt", "r", encoding="utf-8")
@end example

In-memory text streams are also available as @ref{12d4,,StringIO} objects:

@example
f = io.StringIO("some initial text data")
@end example

@cartouche
@quotation Σημείωση 
When working with a non-blocking stream, be aware that read operations on text I/O objects
might raise a @ref{4c3,,BlockingIOError} if the stream cannot perform the operation
immediately.
@end quotation
@end cartouche

The text stream API is described in detail in the documentation of
@ref{a84,,TextIOBase}.

@node Binary I/O,Raw I/O,Text I/O,Overview<2>
@anchor{library/io binary-i-o}@anchor{3366}
@subsubsection Binary I/O


Binary I/O (also called `buffered I/O') expects
@ref{436,,bytes-like objects} and produces @ref{1c7,,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{32b,,open()} with @code{'b'} in
the mode string:

@example
f = open("myfile.jpg", "rb")
@end example

In-memory binary streams are also available as @ref{1255,,BytesIO} objects:

@example
f = io.BytesIO(b"some initial binary data: \x00\x01")
@end example

The binary stream API is described in detail in the docs of
@ref{a83,,BufferedIOBase}.

Other library modules may provide additional ways to create text or binary
streams.  See @ref{1548,,socket.socket.makefile()} for example.

@node Raw I/O,,Binary I/O,Overview<2>
@anchor{library/io raw-i-o}@anchor{3367}
@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{147c,,RawIOBase}.

@node Text Encoding,High-level Module Interface,Overview<2>,io — Core tools for working with streams
@anchor{library/io io-text-encoding}@anchor{b9e}@anchor{library/io text-encoding}@anchor{3368}
@subsubsection Text Encoding


The default encoding of @ref{b9c,,TextIOWrapper} and @ref{32b,,open()} is
locale-specific (@ref{a45,,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 Δείτε επίσης



@table @asis

@item @ref{a46,,Python UTF-8 Mode}

Python UTF-8 Mode can be used to change the default encoding to
UTF-8 from locale-specific encoding.

@geindex Python Enhancement Proposals; PEP 686

@item PEP 686@footnote{https://peps.python.org/pep-0686/}

Python 3.15 will make @ref{a46,,Python UTF-8 Mode} default.
@end table


@menu
* Opt-in EncodingWarning:: 

@end menu

@node Opt-in EncodingWarning,,,Text Encoding
@anchor{library/io io-encoding-warning}@anchor{1ac}@anchor{library/io opt-in-encodingwarning}@anchor{3369}
@subsubsection Opt-in EncodingWarning



Added in 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{178,,-X warn_default_encoding} command line option or set the
@geindex PYTHONWARNDEFAULTENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNDEFAULTENCODING
@ref{b9d,,PYTHONWARNDEFAULTENCODING} environment variable, which will
emit an @ref{231d,,EncodingWarning} when the default encoding is used.

If you are providing an API that uses @ref{32b,,open()} or
@ref{b9c,,TextIOWrapper} and passes @code{encoding=None} as a parameter, you
can use @ref{1c44,,text_encoding()} so that callers of the API will emit an
@ref{231d,,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 High-level Module Interface,Class hierarchy,Text Encoding,io — Core tools for working with streams
@anchor{library/io high-level-module-interface}@anchor{336a}
@subsubsection High-level Module Interface


@geindex DEFAULT_BUFFER_SIZE (στη μονάδα io)
@anchor{library/io io DEFAULT_BUFFER_SIZE}@anchor{1c45}
@deffn {Δεδομένα} io.DEFAULT_BUFFER_SIZE

An int containing the default buffer size used by the module’s buffered I/O
classes.  @ref{32b,,open()} uses the file’s blksize (as obtained by
@ref{4f5,,os.stat()}) if possible.
@end deffn

@geindex open() (στη μονάδα io)
@anchor{library/io io open}@anchor{92b}
@deffn {Συνάρτηση} io.open (file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

This is an alias for the builtin @code{open()} function.


This function raises an @ref{1e65,,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() (στη μονάδα io)
@anchor{library/io io open_code}@anchor{1943}
@deffn {Συνάρτηση} 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{1df,,str} and an absolute path.

The behavior of this function may be overridden by an earlier call to the
@ref{1c9e,,PyFile_SetOpenCodeHook()}. However, assuming that `path' is a
@ref{1df,,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.


Added in version 3.8.

@end deffn

@geindex text_encoding() (στη μονάδα io)
@anchor{library/io io text_encoding}@anchor{1c44}
@deffn {Συνάρτηση} io.text_encoding (encoding, stacklevel=2, /)

This is a helper function for callables that use @ref{32b,,open()} or
@ref{b9c,,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{a46,,UTF-8 Mode}.

This function emits an @ref{231d,,EncodingWarning} if
@ref{a7c,,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{231d,,EncodingWarning} is emitted for the caller of
@code{read_text()}.

See @ref{b9e,,Text Encoding} for more information.


Added in version 3.10.



Άλλαξε στην έκδοση 3.11: @code{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{336b}
@deffn {Εξαίρεση} io.BlockingIOError

This is a compatibility alias for the builtin @code{BlockingIOError}
exception.
@end deffn

@geindex UnsupportedOperation
@anchor{library/io io UnsupportedOperation}@anchor{19c9}
@deffn {Εξαίρεση} io.UnsupportedOperation

An exception inheriting @ref{53c,,OSError} and @ref{277,,ValueError} that is raised
when an unsupported operation is called on a stream.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item @ref{e2,,sys}

contains the standard IO streams: @ref{94a,,sys.stdin}, @ref{e9c,,sys.stdout},
and @ref{d05,,sys.stderr}.
@end table


@node Class hierarchy,Static Typing,High-level Module Interface,io — Core tools for working with streams
@anchor{library/io class-hierarchy}@anchor{336c}
@subsubsection Class hierarchy


The implementation of I/O streams is organized as a hierarchy of classes.  First
@ref{155f,,abstract base classes} (ABCs), which are used to
specify the various categories of streams, then concrete classes providing the
standard stream implementations.

@cartouche
@quotation Σημείωση 
The abstract base classes also provide default implementations of some
methods in order to help implementation of concrete stream classes.  For
example, @ref{a83,,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{70a,,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{19c9,,UnsupportedOperation} if they do not support a given operation.

The @ref{147c,,RawIOBase} ABC extends @ref{70a,,IOBase}.  It deals with the reading
and writing of bytes to a stream.  @ref{16b4,,FileIO} subclasses @code{RawIOBase}
to provide an interface to files in the machine’s file system.

The @ref{a83,,BufferedIOBase} ABC extends @ref{70a,,IOBase}.  It deals with
buffering on a raw binary stream (@ref{147c,,RawIOBase}).  Its subclasses,
@ref{1754,,BufferedWriter}, @ref{15b5,,BufferedReader}, and @ref{1756,,BufferedRWPair}
buffer raw binary streams that are writable, readable, and both readable and writable,
respectively. @ref{1755,,BufferedRandom} provides a buffered interface to seekable streams.
Another @code{BufferedIOBase} subclass, @ref{1255,,BytesIO}, is a stream of
in-memory bytes.

The @ref{a84,,TextIOBase} ABC extends @ref{70a,,IOBase}.  It deals with
streams whose bytes represent text, and handles encoding and decoding to and
from strings.  @ref{b9c,,TextIOWrapper}, which extends @code{TextIOBase}, is a buffered text
interface to a buffered raw stream (@ref{a83,,BufferedIOBase}).  Finally,
@ref{12d4,,StringIO} is an in-memory stream for text.

Argument names are not part of the specification, and only the arguments of
@ref{32b,,open()} are intended to be used as keyword arguments.

The following table summarizes the ABCs provided by the @code{io} module:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ABC

@tab

Inherits

@tab

Stub Methods

@tab

Mixin Methods and Properties

@item

@ref{70a,,IOBase}

@tab

@tab

@code{fileno}, @code{seek},
and @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{147c,,RawIOBase}

@tab

@ref{70a,,IOBase}

@tab

@code{readinto} and
@code{write}

@tab

Inherited @ref{70a,,IOBase} methods, @code{read},
and @code{readall}

@item

@ref{a83,,BufferedIOBase}

@tab

@ref{70a,,IOBase}

@tab

@code{detach}, @code{read},
@code{read1}, and @code{write}

@tab

Inherited @ref{70a,,IOBase} methods, @code{readinto},
and @code{readinto1}

@item

@ref{a84,,TextIOBase}

@tab

@ref{70a,,IOBase}

@tab

@code{detach}, @code{read},
@code{readline}, and
@code{write}

@tab

Inherited @ref{70a,,IOBase} methods, @code{encoding},
@code{errors}, and @code{newlines}

@end multitable


@menu
* I/O Base Classes:: 
* Raw File I/O:: 
* Buffered Streams:: 
* Text I/O: Text I/O<2>. 

@end menu

@node I/O Base Classes,Raw File I/O,,Class hierarchy
@anchor{library/io i-o-base-classes}@anchor{336d}
@subsubsection I/O Base Classes


@geindex IOBase (κλάση σε io)
@anchor{library/io io IOBase}@anchor{70a}
@deffn {Κλάση} 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 @code{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{277,,ValueError} (or @ref{19c9,,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{1c7,,bytes}.  Other @ref{436,,bytes-like objects} are
accepted as method arguments too.  Text I/O classes work with @ref{1df,,str} data.

Note that calling any method (even inquiries) on a closed stream is
undefined.  Implementations may raise @ref{277,,ValueError} in this case.

@code{IOBase} (and its subclasses) supports the iterator protocol, meaning
that an @code{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{16ce,,readline()} below.

@code{IOBase} is also a context manager and therefore supports the
@ref{20a,,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

@code{IOBase} provides these data attributes and methods:

@geindex close() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase close}@anchor{70b}
@deffn {Μέθοδος} 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{277,,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 (ιδιότητα της io.IOBase)
@anchor{library/io io IOBase closed}@anchor{1ffd}
@deffn {Ιδιότητα} closed

@code{True} if the stream is closed.
@end deffn

@geindex fileno() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase fileno}@anchor{19b2}
@deffn {Μέθοδος} fileno ()

Return the underlying file descriptor (an integer) of the stream if it
exists.  An @ref{53c,,OSError} is raised if the IO object does not use a file
descriptor.
@end deffn

@geindex flush() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase flush}@anchor{19fa}
@deffn {Μέθοδος} flush ()

Flush the write buffers of the stream if applicable.  This does nothing
for read-only and non-blocking streams.
@end deffn

@geindex isatty() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase isatty}@anchor{2258}
@deffn {Μέθοδος} isatty ()

Return @code{True} if the stream is interactive (i.e., connected to
a terminal/tty device).
@end deffn

@geindex readable() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase readable}@anchor{1750}
@deffn {Μέθοδος} readable ()

Return @code{True} if the stream can be read from.
If @code{False}, @code{read()} will raise @ref{53c,,OSError}.
@end deffn

@geindex readline() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase readline}@anchor{16ce}
@deffn {Μέθοδος} 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{32b,,open()} can be used to select the line
terminator(s) recognized.
@end deffn

@geindex readlines() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase readlines}@anchor{29bb}
@deffn {Μέθοδος} 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() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase seek}@anchor{1631}
@deffn {Μέθοδος} 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{1632,,os.SEEK_SET} or @code{0} – start of the stream (the default);
`offset' should be zero or positive

@item 
@ref{1633,,os.SEEK_CUR} or @code{1} – current stream position;
`offset' may be negative

@item 
@ref{1634,,os.SEEK_END} or @code{2} – end of the stream;
`offset' is usually negative
@end itemize


Added in version 3.1: The @code{SEEK_*} constants.



Added in version 3.3: Some operating systems could support additional values, like
@ref{3266,,os.SEEK_HOLE} or @ref{3267,,os.SEEK_DATA}. The valid values
for a file could depend on it being open in text or binary mode.

@end deffn

@geindex seekable() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase seekable}@anchor{1752}
@deffn {Μέθοδος} seekable ()

Return @code{True} if the stream supports random access.  If @code{False},
@ref{1631,,seek()}, @ref{174f,,tell()} and @ref{16b5,,truncate()} will raise @ref{53c,,OSError}.
@end deffn

@geindex tell() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase tell}@anchor{174f}
@deffn {Μέθοδος} tell ()

Return the current stream position.
@end deffn

@geindex truncate() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase truncate}@anchor{16b5}
@deffn {Μέθοδος} 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.


Άλλαξε στην έκδοση 3.5: Windows will now zero-fill files when extending.

@end deffn

@geindex writable() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase writable}@anchor{1751}
@deffn {Μέθοδος} writable ()

Return @code{True} if the stream supports writing.  If @code{False},
@code{write()} and @ref{16b5,,truncate()} will raise @ref{53c,,OSError}.
@end deffn

@geindex writelines() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase writelines}@anchor{197c}
@deffn {Μέθοδος} 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__() (μέθοδος της io.IOBase)
@anchor{library/io io IOBase __del__}@anchor{336e}
@deffn {Μέθοδος} __del__ ()

Prepare for object destruction. @code{IOBase} provides a default
implementation of this method that calls the instance’s
@ref{70b,,close()} method.
@end deffn
@end deffn

@geindex RawIOBase (κλάση σε io)
@anchor{library/io io RawIOBase}@anchor{147c}
@deffn {Κλάση} io.RawIOBase

Base class for raw binary streams.  It inherits from @ref{70a,,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).

@code{RawIOBase} provides these methods in addition to those from
@ref{70a,,IOBase}:

@geindex read() (μέθοδος της io.RawIOBase)
@anchor{library/io io RawIOBase read}@anchor{11d0}
@deffn {Μέθοδος} 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{19c8,,readall()} and
@ref{11d1,,readinto()}.
@end deffn

@geindex readall() (μέθοδος της io.RawIOBase)
@anchor{library/io io RawIOBase readall}@anchor{19c8}
@deffn {Μέθοδος} readall ()

Read and return all the bytes from the stream until EOF, using multiple
calls to the stream if necessary.
@end deffn

@geindex readinto() (μέθοδος της io.RawIOBase)
@anchor{library/io io RawIOBase readinto}@anchor{11d1}
@deffn {Μέθοδος} readinto (b, /)

Read bytes into a pre-allocated, writable
@ref{436,,bytes-like object} `b', and return the
number of bytes read.  For example, `b' might be a @ref{1c6,,bytearray}.
If the object is in non-blocking mode and no bytes
are available, @code{None} is returned.
@end deffn

@geindex write() (μέθοδος της io.RawIOBase)
@anchor{library/io io RawIOBase write}@anchor{174e}
@deffn {Μέθοδος} write (b, /)

Write the given @ref{436,,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 (κλάση σε io)
@anchor{library/io io BufferedIOBase}@anchor{a83}
@deffn {Κλάση} io.BufferedIOBase

Base class for binary streams that support some kind of buffering.
It inherits from @ref{70a,,IOBase}.

The main difference with @ref{147c,,RawIOBase} is that methods @ref{16cd,,read()},
@ref{1ab9,,readinto()} and @ref{1099,,write()} will try (respectively) to read
as much input as requested or to emit all provided data.

In addition, if the underlying raw stream is in non-blocking mode, when the
system returns would block @ref{1099,,write()} will raise @ref{4c3,,BlockingIOError}
with @ref{28fd,,BlockingIOError.characters_written} and @ref{16cd,,read()} will return
data read so far or @code{None} if no data is available.

Besides, the @ref{16cd,,read()} method does not have a default
implementation that defers to @ref{1ab9,,readinto()}.

A typical @code{BufferedIOBase} implementation should not inherit from a
@ref{147c,,RawIOBase} implementation, but wrap one, like
@ref{1754,,BufferedWriter} and @ref{15b5,,BufferedReader} do.

@code{BufferedIOBase} provides or overrides these data attributes and
methods in addition to those from @ref{70a,,IOBase}:

@geindex raw (ιδιότητα της io.BufferedIOBase)
@anchor{library/io io BufferedIOBase raw}@anchor{1753}
@deffn {Ιδιότητα} raw

The underlying raw stream (a @ref{147c,,RawIOBase} instance) that
@code{BufferedIOBase} deals with.  This is not part of the
@code{BufferedIOBase} API and may not exist on some implementations.
@end deffn

@geindex detach() (μέθοδος της io.BufferedIOBase)
@anchor{library/io io BufferedIOBase detach}@anchor{3013}
@deffn {Μέθοδος} detach ()

Separate the underlying raw stream from the buffer and return it.

After the raw stream has been detached, the buffer is in an unusable
state.

Some buffers, like @ref{1255,,BytesIO}, do not have the concept of a single
raw stream to return from this method.  They raise
@ref{19c9,,UnsupportedOperation}.


Added in version 3.1.

@end deffn

@geindex read() (μέθοδος της io.BufferedIOBase)
@anchor{library/io io BufferedIOBase read}@anchor{16cd}
@deffn {Μέθοδος} read (size=-1, /)

Read and return up to `size' bytes. If the argument is omitted, @code{None},
or negative read as much as possible.

Fewer bytes may be returned than requested. An empty @ref{1c7,,bytes} object
is returned if the stream is already at EOF. More than one read may be
made and calls may be retried if specific errors are encountered, see
@ref{114e,,os.read()} and 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for more details. Less than size bytes
being returned does not imply that EOF is imminent.

When reading as much as possible the default implementation will use
@code{raw.readall} if available (which should implement
@ref{19c8,,RawIOBase.readall()}), otherwise will read in a loop until read
returns @code{None}, an empty @ref{1c7,,bytes}, or a non-retryable error. For
most streams this is to EOF, but for non-blocking streams more data may
become available.

@cartouche
@quotation Σημείωση 
When the underlying raw stream is non-blocking, implementations may
either raise @ref{4c3,,BlockingIOError} or return @code{None} if no data is
available. @code{io} implementations return @code{None}.
@end quotation
@end cartouche
@end deffn

@geindex read1() (μέθοδος της io.BufferedIOBase)
@anchor{library/io io BufferedIOBase read1}@anchor{307c}
@deffn {Μέθοδος} read1 (size=-1, /)

Read and return up to `size' bytes, calling @ref{11d1,,readinto()}
which may retry if @ref{1140,,EINTR} is encountered per
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/}. If `size' is @code{-1} or not provided, the implementation will
choose an arbitrary value for `size'.

@cartouche
@quotation Σημείωση 
When the underlying raw stream is non-blocking, implementations may
either raise @ref{4c3,,BlockingIOError} or return @code{None} if no data is
available. @code{io} implementations return @code{None}.
@end quotation
@end cartouche
@end deffn

@geindex readinto() (μέθοδος της io.BufferedIOBase)
@anchor{library/io io BufferedIOBase readinto}@anchor{1ab9}
@deffn {Μέθοδος} readinto (b, /)

Read bytes into a pre-allocated, writable
@ref{436,,bytes-like object} `b' and return the number of bytes read.
For example, `b' might be a @ref{1c6,,bytearray}.

Like @ref{16cd,,read()}, multiple reads may be issued to the underlying raw
stream, unless the latter is interactive.

A @ref{4c3,,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() (μέθοδος της io.BufferedIOBase)
@anchor{library/io io BufferedIOBase readinto1}@anchor{11cf}
@deffn {Μέθοδος} readinto1 (b, /)

Read bytes into a pre-allocated, writable
@ref{436,,bytes-like object} `b', using at most one call to
the underlying raw stream’s @ref{11d0,,read()} (or
@ref{11d1,,readinto()}) method. Return the number of bytes read.

A @ref{4c3,,BlockingIOError} is raised if the underlying raw stream is in non
blocking-mode, and has no data available at the moment.


Added in version 3.5.

@end deffn

@geindex write() (μέθοδος της io.BufferedIOBase)
@anchor{library/io io BufferedIOBase write}@anchor{1099}
@deffn {Μέθοδος} write (b, /)

Write the given @ref{436,,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{53c,,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{4c3,,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{336f}
@subsubsection Raw File I/O


@geindex FileIO (κλάση σε io)
@anchor{library/io io FileIO}@anchor{16b4}
@deffn {Κλάση} 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{147c,,RawIOBase}.

The `name' can be one of two things:


@itemize *

@item 
a character string or @ref{1c7,,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 @code{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{13c9,,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{11d0,,read()} (when called with a positive argument),
@ref{11d1,,readinto()} and @ref{174e,,write()} methods on this
class will only make one system call.

A custom opener can be used by passing a callable as `opener'. The underlying
file descriptor for the file object is then obtained by calling `opener' with
(`name', `flags'). `opener' must return an open file descriptor (passing
@ref{114b,,os.open} as `opener' results in functionality similar to passing
@code{None}).

The newly created file is @ref{12aa,,non-inheritable}.

See the @ref{32b,,open()} built-in function for examples on using the `opener'
parameter.


Άλλαξε στην έκδοση 3.3: The `opener' parameter was added.
The @code{'x'} mode was added.



Άλλαξε στην έκδοση 3.4: The file is now non-inheritable.


@code{FileIO} provides these data attributes in addition to those from
@ref{147c,,RawIOBase} and @ref{70a,,IOBase}:

@geindex mode (ιδιότητα της io.FileIO)
@anchor{library/io io FileIO mode}@anchor{19d0}
@deffn {Ιδιότητα} mode

The mode as given in the constructor.
@end deffn

@geindex name (ιδιότητα της io.FileIO)
@anchor{library/io io FileIO name}@anchor{3017}
@deffn {Ιδιότητα} name

The file name.  This is the file descriptor of the file when no name is
given in the constructor.
@end deffn
@end deffn

@node Buffered Streams,Text I/O<2>,Raw File I/O,Class hierarchy
@anchor{library/io buffered-streams}@anchor{3370}
@subsubsection Buffered Streams


Buffered I/O streams provide a higher-level interface to an I/O device
than raw I/O does.

@geindex BytesIO (κλάση σε io)
@anchor{library/io io BytesIO}@anchor{1255}
@deffn {Κλάση} io.BytesIO (initial_bytes=b'@w{'})

A binary stream using an in-memory bytes buffer.  It inherits from
@ref{a83,,BufferedIOBase}.  The buffer is discarded when the
@ref{70b,,close()} method is called.

The optional argument `initial_bytes' is a @ref{436,,bytes-like object} that
contains initial data.

Methods may be used from multiple threads without external locking in
@ref{198,,free-threaded builds}.

@code{BytesIO} provides or overrides these methods in addition to those
from @ref{a83,,BufferedIOBase} and @ref{70a,,IOBase}:

@geindex getbuffer() (μέθοδος της io.BytesIO)
@anchor{library/io io BytesIO getbuffer}@anchor{159a}
@deffn {Μέθοδος} 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 Σημείωση 
As long as the view exists, the @code{BytesIO} object cannot be
resized or closed.
@end quotation
@end cartouche


Added in version 3.2.

@end deffn

@geindex getvalue() (μέθοδος της io.BytesIO)
@anchor{library/io io BytesIO getvalue}@anchor{307a}
@deffn {Μέθοδος} getvalue ()

Return @ref{1c7,,bytes} containing the entire contents of the buffer.
@end deffn

@geindex read1() (μέθοδος της io.BytesIO)
@anchor{library/io io BytesIO read1}@anchor{3371}
@deffn {Μέθοδος} read1 (size=-1, /)

In @code{BytesIO}, this is the same as @ref{16cd,,read()}.


Άλλαξε στην έκδοση 3.7: The `size' argument is now optional.

@end deffn

@geindex readinto1() (μέθοδος της io.BytesIO)
@anchor{library/io io BytesIO readinto1}@anchor{3372}
@deffn {Μέθοδος} readinto1 (b, /)

In @code{BytesIO}, this is the same as @ref{1ab9,,readinto()}.


Added in version 3.5.

@end deffn
@end deffn

@geindex BufferedReader (κλάση σε io)
@anchor{library/io io BufferedReader}@anchor{15b5}
@deffn {Κλάση} io.BufferedReader (raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a readable, non
seekable @ref{147c,,RawIOBase} raw binary stream.  It inherits from
@ref{a83,,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 @code{BufferedReader} for the given readable
`raw' stream and `buffer_size'.  If `buffer_size' is omitted,
@ref{1c45,,DEFAULT_BUFFER_SIZE} is used.

@code{BufferedReader} provides or overrides these methods in addition to
those from @ref{a83,,BufferedIOBase} and @ref{70a,,IOBase}:

@geindex peek() (μέθοδος της io.BufferedReader)
@anchor{library/io io BufferedReader peek}@anchor{3373}
@deffn {Μέθοδος} peek (size=0, /)

Return bytes from the stream without advancing the position. The number of
bytes returned may be less or more than requested. If the underlying raw
stream is non-blocking and the operation would block, returns empty bytes.
@end deffn

@geindex read() (μέθοδος της io.BufferedReader)
@anchor{library/io io BufferedReader read}@anchor{3374}
@deffn {Μέθοδος} read (size=-1, /)

In @code{BufferedReader} this is the same as @ref{16cd,,io.BufferedIOBase.read()}
@end deffn

@geindex read1() (μέθοδος της io.BufferedReader)
@anchor{library/io io BufferedReader read1}@anchor{1968}
@deffn {Μέθοδος} read1 (size=-1, /)

In @code{BufferedReader} this is the same as @ref{307c,,io.BufferedIOBase.read1()}


Άλλαξε στην έκδοση 3.7: The `size' argument is now optional.

@end deffn
@end deffn

@geindex BufferedWriter (κλάση σε io)
@anchor{library/io io BufferedWriter}@anchor{1754}
@deffn {Κλάση} io.BufferedWriter (raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a writeable, non
seekable @ref{147c,,RawIOBase} raw binary stream.  It inherits from
@ref{a83,,BufferedIOBase}.

When writing to this object, data is normally placed into an internal
buffer.  The buffer will be written out to the underlying @ref{147c,,RawIOBase}
object under various conditions, including:


@itemize *

@item 
when the buffer gets too small for all pending data;

@item 
when @ref{3375,,flush()} is called;

@item 
when a @ref{1631,,seek()} is requested (for @ref{1755,,BufferedRandom} objects);

@item 
when the @code{BufferedWriter} object is closed or destroyed.
@end itemize

The constructor creates a @code{BufferedWriter} for the given writeable
`raw' stream.  If the `buffer_size' is not given, it defaults to
@ref{1c45,,DEFAULT_BUFFER_SIZE}.

@code{BufferedWriter} provides or overrides these methods in addition to
those from @ref{a83,,BufferedIOBase} and @ref{70a,,IOBase}:

@geindex flush() (μέθοδος της io.BufferedWriter)
@anchor{library/io io BufferedWriter flush}@anchor{3375}
@deffn {Μέθοδος} flush ()

Force bytes held in the buffer into the raw stream.  A
@ref{4c3,,BlockingIOError} should be raised if the raw stream blocks.
@end deffn

@geindex write() (μέθοδος της io.BufferedWriter)
@anchor{library/io io BufferedWriter write}@anchor{3376}
@deffn {Μέθοδος} write (b, /)

Write the @ref{436,,bytes-like object}, `b', and return the
number of bytes written.  When in non-blocking mode, a
@ref{4c3,,BlockingIOError} with @ref{28fd,,BlockingIOError.characters_written} set
is raised if the buffer needs to be written out but the raw stream blocks.
@end deffn
@end deffn

@geindex BufferedRandom (κλάση σε io)
@anchor{library/io io BufferedRandom}@anchor{1755}
@deffn {Κλάση} io.BufferedRandom (raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a seekable
@ref{147c,,RawIOBase} raw binary stream.  It inherits from @ref{15b5,,BufferedReader}
and @ref{1754,,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{1c45,,DEFAULT_BUFFER_SIZE}.

@code{BufferedRandom} is capable of anything @ref{15b5,,BufferedReader} or
@ref{1754,,BufferedWriter} can do.  In addition, @ref{1631,,seek()} and
@ref{174f,,tell()} are guaranteed to be implemented.
@end deffn

@geindex BufferedRWPair (κλάση σε io)
@anchor{library/io io BufferedRWPair}@anchor{1756}
@deffn {Κλάση} io.BufferedRWPair (reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)

A buffered binary stream providing higher-level access to two non seekable
@ref{147c,,RawIOBase} raw binary streams—one readable, the other writeable.
It inherits from @ref{a83,,BufferedIOBase}.

`reader' and `writer' are @ref{147c,,RawIOBase} objects that are readable and
writeable respectively.  If the `buffer_size' is omitted it defaults to
@ref{1c45,,DEFAULT_BUFFER_SIZE}.

@code{BufferedRWPair} implements all of @ref{a83,,BufferedIOBase}'s methods
except for @ref{3013,,detach()}, which raises
@ref{19c9,,UnsupportedOperation}.

@cartouche
@quotation Προειδοποίηση 
@code{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{1755,,BufferedRandom} instead.
@end quotation
@end cartouche
@end deffn

@node Text I/O<2>,,Buffered Streams,Class hierarchy
@anchor{library/io id1}@anchor{3377}
@subsubsection Text I/O


@geindex TextIOBase (κλάση σε io)
@anchor{library/io io TextIOBase}@anchor{a84}
@deffn {Κλάση} io.TextIOBase

Base class for text streams.  This class provides a character and line based
interface to stream I/O.  It inherits from @ref{70a,,IOBase}.

@code{TextIOBase} provides or overrides these data attributes and
methods in addition to those from @ref{70a,,IOBase}:

@geindex encoding (ιδιότητα της io.TextIOBase)
@anchor{library/io io TextIOBase encoding}@anchor{3378}
@deffn {Ιδιότητα} 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 (ιδιότητα της io.TextIOBase)
@anchor{library/io io TextIOBase errors}@anchor{16b3}
@deffn {Ιδιότητα} errors

The error setting of the decoder or encoder.
@end deffn

@geindex newlines (ιδιότητα της io.TextIOBase)
@anchor{library/io io TextIOBase newlines}@anchor{3379}
@deffn {Ιδιότητα} 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 (ιδιότητα της io.TextIOBase)
@anchor{library/io io TextIOBase buffer}@anchor{1648}
@deffn {Ιδιότητα} buffer

The underlying binary buffer (a @ref{a83,,BufferedIOBase}
or @ref{147c,,RawIOBase} instance) that @code{TextIOBase} deals with.
This is not part of the @code{TextIOBase} API and may not exist
in some implementations.
@end deffn

@geindex detach() (μέθοδος της io.TextIOBase)
@anchor{library/io io TextIOBase detach}@anchor{19a5}
@deffn {Μέθοδος} detach ()

Separate the underlying binary buffer from the @code{TextIOBase} and
return it.

After the underlying buffer has been detached, the @code{TextIOBase} is
in an unusable state.

Some @code{TextIOBase} implementations, like @ref{12d4,,StringIO}, may not
have the concept of an underlying buffer and calling this method will
raise @ref{19c9,,UnsupportedOperation}.


Added in version 3.1.

@end deffn

@geindex read() (μέθοδος της io.TextIOBase)
@anchor{library/io io TextIOBase read}@anchor{225b}
@deffn {Μέθοδος} read (size=-1, /)

Read and return at most `size' characters from the stream as a single
@ref{1df,,str}.  If `size' is negative or @code{None}, reads until EOF.
@end deffn

@geindex readline() (μέθοδος της io.TextIOBase)
@anchor{library/io io TextIOBase readline}@anchor{2296}
@deffn {Μέθοδος} readline (size=-1, /)

Read until newline or EOF and return a single @ref{1df,,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() (μέθοδος της io.TextIOBase)
@anchor{library/io io TextIOBase seek}@anchor{337a}
@deffn {Μέθοδος} 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{337b,,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.


Added in version 3.1: The @code{SEEK_*} constants.

@end deffn

@geindex tell() (μέθοδος της io.TextIOBase)
@anchor{library/io io TextIOBase tell}@anchor{337b}
@deffn {Μέθοδος} 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() (μέθοδος της io.TextIOBase)
@anchor{library/io io TextIOBase write}@anchor{224a}
@deffn {Μέθοδος} write (s, /)

Write the string `s' to the stream and return the number of characters
written.
@end deffn
@end deffn

@geindex TextIOWrapper (κλάση σε io)
@anchor{library/io io TextIOWrapper}@anchor{b9c}
@deffn {Κλάση} 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{a83,,BufferedIOBase} buffered binary stream.  It inherits from
@ref{a84,,TextIOBase}.

`encoding' gives the name of the encoding that the stream will be decoded or
encoded with.  In @ref{a46,,UTF-8 Mode}, this defaults to UTF-8.
Otherwise, it defaults to @ref{a45,,locale.getencoding()}.
@code{encoding="locale"} can be used to specify the current locale’s encoding
explicitly. See @ref{b9e,,Text Encoding} 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{277,,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{183d,,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{10f1,,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 
When writing output to the stream, if `newline' is @code{None}, any @code{'\n'}
characters written are translated to the system default line separator,
@ref{27d5,,os.linesep}.  If `newline' is @code{'@w{'}} or @code{'\n'}, no translation
takes place.  If `newline' is any of the other legal values, any @code{'\n'}
characters written are translated to the given string.
@end itemize

If `line_buffering' is @code{True}, @ref{19fa,,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{1099,,write()} are guaranteed
not to be buffered: any data written on the @code{TextIOWrapper}
object is immediately handled to its underlying binary `buffer'.


Άλλαξε στην έκδοση 3.3: The `write_through' argument has been added.



Άλλαξε στην έκδοση 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{231,,locale.setlocale()}, use the current locale
encoding instead of the user preferred encoding.



Άλλαξε στην έκδοση 3.10: The `encoding' argument now supports the @code{"locale"} dummy encoding name.


@cartouche
@quotation Σημείωση 
When the underlying raw stream is non-blocking, a @ref{4c3,,BlockingIOError}
may be raised if a read operation cannot be completed immediately.
@end quotation
@end cartouche

@code{TextIOWrapper} provides these data attributes and methods in
addition to those from @ref{a84,,TextIOBase} and @ref{70a,,IOBase}:

@geindex line_buffering (ιδιότητα της io.TextIOWrapper)
@anchor{library/io io TextIOWrapper line_buffering}@anchor{337c}
@deffn {Ιδιότητα} line_buffering

Whether line buffering is enabled.
@end deffn

@geindex write_through (ιδιότητα της io.TextIOWrapper)
@anchor{library/io io TextIOWrapper write_through}@anchor{337d}
@deffn {Ιδιότητα} write_through

Whether writes are passed immediately to the underlying binary
buffer.


Added in version 3.7.

@end deffn

@geindex reconfigure() (μέθοδος της io.TextIOWrapper)
@anchor{library/io io TextIOWrapper reconfigure}@anchor{f06}
@deffn {Μέθοδος} 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.

It is not possible to change the encoding or newline if some data
has already been read from the stream. On the other hand, changing
encoding after write is possible.

This method does an implicit stream flush before setting the
new parameters.


Added in version 3.7.



Άλλαξε στην έκδοση 3.11: The method supports @code{encoding="locale"} option.

@end deffn

@geindex seek() (μέθοδος της io.TextIOWrapper)
@anchor{library/io io TextIOWrapper seek}@anchor{337e}
@deffn {Μέθοδος} seek (cookie, whence=os.SEEK_SET, /)

Set the stream position.
Return the new stream position as an @ref{326,,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{19c7,,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 Δείτε επίσης


@ref{1632,,os.SEEK_SET}, @ref{1633,,os.SEEK_CUR}, and @ref{1634,,os.SEEK_END}.

@end deffn

@geindex tell() (μέθοδος της io.TextIOWrapper)
@anchor{library/io io TextIOWrapper tell}@anchor{19c7}
@deffn {Μέθοδος} tell ()

Return the stream position as an opaque number.
The return value of @code{tell()} can be given as input to @ref{337e,,seek()},
to restore a previous stream position.
@end deffn
@end deffn

@geindex StringIO (κλάση σε io)
@anchor{library/io io StringIO}@anchor{12d4}
@deffn {Κλάση} io.StringIO (initial_value='@w{'}, newline='\n')

A text stream using an in-memory text buffer.  It inherits from
@ref{a84,,TextIOBase}.

The text buffer is discarded when the @ref{70b,,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{224a,,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{b9c,,TextIOWrapper},
except that when writing output to the stream, if `newline' is @code{None},
newlines are written as @code{\n} on all platforms.

@code{StringIO} provides this method in addition to those from
@ref{a84,,TextIOBase} and @ref{70a,,IOBase}:

@geindex getvalue() (μέθοδος της io.StringIO)
@anchor{library/io io StringIO getvalue}@anchor{337f}
@deffn {Μέθοδος} getvalue ()

Return a @ref{1df,,str} containing the entire contents of the buffer.
Newlines are decoded as if by @ref{225b,,read()}, although
the stream position is not changed.
@end deffn

Example usage:

@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 (κλάση σε io)
@anchor{library/io io IncrementalNewlineDecoder}@anchor{1947}
@deffn {Κλάση} io.IncrementalNewlineDecoder

A helper codec that decodes newlines for @ref{10f1,,universal newlines} mode.
It inherits from @ref{2a4e,,codecs.IncrementalDecoder}.
@end deffn

@node Static Typing,Performance<3>,Class hierarchy,io — Core tools for working with streams
@anchor{library/io static-typing}@anchor{3380}
@subsubsection Static Typing


The following protocols can be used for annotating function and method
arguments for simple stream reading or writing operations. They are decorated
with @ref{861,,@@typing.runtime_checkable}.

@geindex Reader (κλάση σε io)
@anchor{library/io io Reader}@anchor{4c4}
@deffn {Κλάση} io.Reader [T]

Generic protocol for reading from a file or other input stream. @code{T} will
usually be @ref{1df,,str} or @ref{1c7,,bytes}, but can be any type that is
read from the stream.


Added in version 3.14.


@geindex read() (μέθοδος της io.Reader)
@anchor{library/io io Reader read}@anchor{3381}
@deffn {Μέθοδος} read ()

@deffnx {Μέθοδος} read (size, /)

Read data from the input stream and return it. If `size' is
specified, it should be an integer, and at most `size' items
(bytes/characters) will be read.
@end deffn

For example:

@example
def read_it(reader: Reader[str]):
    data = reader.read(11)
    assert isinstance(data, str)
@end example
@end deffn

@geindex Writer (κλάση σε io)
@anchor{library/io io Writer}@anchor{4c5}
@deffn {Κλάση} io.Writer [T]

Generic protocol for writing to a file or other output stream. @code{T} will
usually be @ref{1df,,str} or @ref{1c7,,bytes}, but can be any type that can be
written to the stream.


Added in version 3.14.


@geindex write() (μέθοδος της io.Writer)
@anchor{library/io io Writer write}@anchor{3382}
@deffn {Μέθοδος} write (data, /)

Write `data' to the output stream and return the number of items
(bytes/characters) written.
@end deffn

For example:

@example
def write_binary(writer: Writer[bytes]):
    writer.write(b"Hello world!\n")
@end example
@end deffn

See @ref{3383,,ABCs and Protocols for working with I/O} for other I/O related protocols and classes that can be
used for static type checking.

@node Performance<3>,,Static Typing,io — Core tools for working with streams
@anchor{library/io performance}@anchor{3384}
@subsubsection Performance


This section discusses the performance of the provided concrete I/O
implementations.

@menu
* Binary I/O: Binary I/O<2>. 
* Text I/O: Text I/O<3>. 
* Multi-threading: Multi-threading<3>. 
* Reentrancy:: 

@end menu

@node Binary I/O<2>,Text I/O<3>,,Performance<3>
@anchor{library/io id2}@anchor{3385}
@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 Text I/O<3>,Multi-threading<3>,Binary I/O<2>,Performance<3>
@anchor{library/io id3}@anchor{3386}
@subsubsection Text I/O


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{337b,,tell()} and @ref{337a,,seek()} are both quite slow
due to the reconstruction algorithm used.

@ref{12d4,,StringIO}, however, is a native in-memory unicode container and will
exhibit similar speed to @ref{1255,,BytesIO}.

@node Multi-threading<3>,Reentrancy,Text I/O<3>,Performance<3>
@anchor{library/io multi-threading}@anchor{3387}
@subsubsection Multi-threading


@ref{16b4,,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{15b5,,BufferedReader},
@ref{1754,,BufferedWriter}, @ref{1755,,BufferedRandom} and @ref{1756,,BufferedRWPair})
protect their internal structures using a lock; it is therefore safe to call
them from multiple threads at once.

@ref{b9c,,TextIOWrapper} objects are not thread-safe.

@node Reentrancy,,Multi-threading<3>,Performance<3>
@anchor{library/io reentrancy}@anchor{3388}
@subsubsection Reentrancy


Binary buffered objects (instances of @ref{15b5,,BufferedReader},
@ref{1754,,BufferedWriter}, @ref{1755,,BufferedRandom} and @ref{1756,,BufferedRWPair})
are not reentrant.  While reentrant calls will not happen in normal situations,
they can arise from doing I/O in a @ref{ce,,signal} handler.  If a thread tries to
re-enter a buffered object which it is already accessing, a @ref{30d,,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{32b,,open()} function
will wrap a buffered object inside a @ref{b9c,,TextIOWrapper}.  This includes
standard streams and therefore affects the built-in @ref{131f,,print()} function as
well.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node time — Πρόσβαση και μετατροπές χρόνου,logging — Logging facility for Python,io — Core tools for working with streams,Generic Operating System Services
@anchor{library/time doc}@anchor{3389}@anchor{library/time module-time}@anchor{f7}@anchor{library/time time-time-access-and-conversions}@anchor{338a}@anchor{library/time translation-repo}@anchor{338b}
@subsection @code{time} — Πρόσβαση και μετατροπές χρόνου


@geindex module; time


__________________________________________________________________


Αυτό το module παρέχει διάφορες συναρτήσεις σχετικές με τον χρόνο. Για σχετική λειτουργικότητα, δείτε επίσης τα modules @ref{33,,datetime} και @ref{15,,calendar}.

Αν και αυτό το module είναι πάντα διαθέσιμο, δεν είναι όλες οι συναρτήσεις διαθέσιμες σε όλες τις πλατφόρμες. Οι περισσότερες από τις συναρτήσεις που ορίζονται σε αυτό το module καλούν συναρτήσεις της πλατφόρμας C με το ίδιο όνομα. Μπορεί μερικές φορές να είναι χρήσιμο να συμβουλευτείτε την τεκμηρίωση της πλατφόρμας, επειδή η σημασιολογία αυτών των συναρτήσεων διαφέρει μεταξύ των πλατφορμών.

Απαιτείται μια εξήγηση ορισμένης ορολογίας και συμβάσεων.

@geindex epoch
@anchor{library/time epoch}@anchor{3139}

@itemize *

@item 
Το `epoch' είναι το σημείο όπου ξεκινά ο χρόνος, η τιμή που επιστρέφει το @code{time.gmtime(0)}. Είναι η 1η Ιανουαρίου 1970, 00:00:00 (UTC) σε όλες τις πλατφόρμες.
@end itemize

@geindex δευτερόλεπτα από το epoch


@itemize *

@item 
Ο όρος `seconds since the epoch' αναφέρεται στον συνολικό αριθμό των δευτερολέπτων που έχουν παρέλθει από το epoch, συνήθως εξαιρώντας τα leap seconds@footnote{https://en.wikipedia.org/wiki/Leap_second}. Τα δίσεκτα δευτερόλεπτα (leap seconds) εξαιρούνται από αυτό το σύνολο σε όλες τις πλατφόρμες που συμμορφώνονται με το POSIX.
@end itemize

@geindex Έτος 2038


@itemize *

@item 
Οι συναρτήσεις σε αυτό το module μπορεί να μην χειρίζονται ημερομηνίες και ώρες πριν από το @ref{3139,,epoch} ή πολύ μακριά στο μέλλον. Το σημείο κοπής στο μέλλον καθορίζεται από τη βιβλιοθήκη C· για συστήματα 32-bit, είναι τυπικά το 2038.
@end itemize

@geindex Έτη με 2 ψηφία


@itemize *

@item 
Η συνάρτηση @ref{17cf,,strptime()} μπορεί να αναλύσει 2-ψήφια έτη όταν δοθεί κωδικός μορφής @code{%y}. Όταν αναλύονται 2-ψήφια έτη, μετατρέπονται σύμφωνα με τα πρότυπα POSIX και ISO C: οι τιμές 69–99 αντιστοιχίζονται σε 1969–1999, και οι τιμές 0–68 αντιστοιχίζονται σε2000–2068.
@end itemize

@geindex UTC
@geindex Συντονισμένη Παγκόσμια Ώρα
@geindex Μεσημβρινή Ώρα Γκρίνουιτς


@itemize *

@item 
Το UTC είναι το Coordinated Universal Time@footnote{https://en.wikipedia.org/wiki/Coordinated_Universal_Time} και έχει αντικαταστήσει το Greenwich Mean Time@footnote{https://en.wikipedia.org/wiki/Greenwich_Mean_Time} ή GMT ως τη βάση της διεθνούς τήρησης χρόνου. Το ακρωνύμιο UTC δεν είναι λάθος αλλά συμμορφώνεται με ένα προηγούμενο, ουδέτερο ως προς τη γλώσσα, σχήμα ονομασίας για πρότυπα χρόνου όπως τα UT0, UT1, και UT2.
@end itemize

@geindex Θερινή Ώρα


@itemize *

@item 
Το DST είναι το Daylight Saving Time, μια προσαρμογή της ζώνης ώρας κατά (συνήθως) μία ώρα κατά τη διάρκεια μέρους του έτους. Οι κανόνες DST είναι μαγικοί (καθορίζονται από τοπικό νόμο) και μπορεί να αλλάζουν από έτος σε έτος. Η βιβλιοθήκη C έχει έναν πίνακα που περιέχει τους τοπικούς κανόνες (συχνά διαβάζεται από ένα σύστημα αρχείων για ευελιξία) και είναι η μόνη πηγή Αληθινής Σοφίας σε αυτό το θέμα.

@item 
Η ακρίβεια των διαφόρων συναρτήσεων πραγματικού χρόνου μπορεί να είναι λιγότερη από αυτή που υποδηλώνεται από τις μονάδες στις οποίες εκφράζεται η τιμή ή το όρισμά τους. Π.χ. στα περισσότερα συστήματα Unix, το ρολόι «χτυπάει» μόνο 50 ή 100 φορές το δευτερόλεπτο.

@item 
Από την άλλη πλευρά, η ακρίβεια της @ref{75e,,time()} και της @ref{a8c,,sleep()} είναι πιο καλή από τις αντίστοιχες Unix: οι χρόνοι εκφράζονται ως αριθμοί κινητής υποδιαστολής, η @code{time()} επιστρέφει τον πιο ακριβή διαθέσιμο χρόνο (χρησιμοποιώντας το Unix @code{gettimeofday()} όπου είναι διαθέσιμο), και @code{sleep()} θα δεχτεί έναν χρόνο με μη μηδενικό κλάσμα (το Unix :c:@code{select()} χρησιμοποιείται για αυτόν τον λόγο, όπου είναι διαθέσιμο).

@item 
Η τιμή χρόνου όπως επιστρέφεται από τις @ref{1569,,gmtime()}, @ref{189b,,localtime()}, και @ref{17cf,,strptime()}, και γίνεται αποδεκτή από τις @ref{1590,,asctime()}, @ref{1591,,mktime()} και @ref{1592,,strftime()}, είναι μια ακολουθία από 9 ακέραιους. Οι τιμές επιστροφής των @code{gmtime()}, @code{localtime()}, και @code{strptime()} προσφέρουν επίσης ονόματα χαρακτηριστικών για μεμονωμένα πεδία.

Δείτε την @ref{10a7,,struct_time} για μια περιγραφή αυτών των αντικειμένων.


Άλλαξε στην έκδοση 3.3: Ο τύπος @ref{10a7,,struct_time} επεκτάθηκε για να παρέχει τα @ref{338c,,tm_gmtoff} και @ref{338d,,tm_zone} χαρακτηριστικά όταν η πλατφόρμα υποστηρίζει τα αντίστοιχα μέλη @code{struct tm}.



Άλλαξε στην έκδοση 3.6: Τα @ref{10a7,,struct_time} χαρακτηριστικά @ref{338c,,tm_gmtoff} και @ref{338d,,tm_zone} είναι τώρα διαθέσιμα σε όλες τις πλατφόρμες.


@item 
Χρησιμοποιήστε τις ακόλουθες συναρτήσεις για να μετατρέψετε μεταξύ αναπαραστάσεων χρόνου:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Από

@tab

Προς

@tab

Χρήση

@item

δευτερόλεπτα από το epoch

@tab

@ref{10a7,,struct_time} σε UTC

@tab

@ref{1569,,gmtime()}

@item

δευτερόλεπτα από το epoch

@tab

@ref{10a7,,struct_time} σε τοπική ώρα

@tab

@ref{189b,,localtime()}

@item

@ref{10a7,,struct_time} σε UTC

@tab

δευτερόλεπτα από το epoch

@tab

@ref{2b5b,,calendar.timegm()}

@item

@ref{10a7,,struct_time} σε τοπική ώρα

@tab

δευτερόλεπτα από το epoch

@tab

@ref{1591,,mktime()}

@end multitable

@end itemize

@menu
* Συναρτήσεις: Συναρτήσεις<2>. 
* Σταθερές αναγνωριστικού ρολογιού:: 
* Σταθερές ζώνης ώρας:: 

@end menu

@node Συναρτήσεις<2>,Σταθερές αναγνωριστικού ρολογιού,,time — Πρόσβαση και μετατροπές χρόνου
@anchor{library/time functions}@anchor{338e}@anchor{library/time time-functions}@anchor{338f}
@subsubsection Συναρτήσεις


@geindex asctime() (στη μονάδα time)
@anchor{library/time time asctime}@anchor{1590}
@deffn {Συνάρτηση} time.asctime ([t])

Μετατρέπει μια πλειάδα ή @ref{10a7,,struct_time} που αναπαριστά έναν χρόνο όπως επιστρέφεται από τις @ref{1569,,gmtime()} ή @ref{189b,,localtime()} σε μια συμβολοσειρά της ακόλουθης μορφής: @code{'Sun Jun 20 23:21:05 1993'}. Το πεδίο της ημέρας είναι δύο χαρακτήρων και γεμίζεται με κενό αν η ημέρα είναι μονοψήφια, π.χ.: @code{'Wed Jun  9 04:26:40 1993'}.

Αν το `t' δεν παρέχεται, χρησιμοποιείται ο τρέχων χρόνος όπως επιστρέφεται από την @ref{189b,,localtime()}. Οι πληροφορίες τοπικής ρύθμισης δεν χρησιμοποιούνται από την @ref{1590,,asctime()}.

@cartouche
@quotation Σημείωση 
Σε αντίθεση με τη συνάρτηση C με το ίδιο όνομα, η @ref{1590,,asctime()} δεν προσθέτει μια νέα γραμμή στο τέλος.
@end quotation
@end cartouche
@end deffn

@geindex pthread_getcpuclockid() (στη μονάδα time)
@anchor{library/time time pthread_getcpuclockid}@anchor{f51}
@deffn {Συνάρτηση} time.pthread_getcpuclockid (thread_id)

Επιστρέφει το `clk_id' του ρολογιού χρόνου CPU που είναι συγκεκριμένο για το νήμα, για το καθορισμένο  `thread_id'.

Χρησιμοποιήστε το @ref{1505,,threading.get_ident()} ή το @ref{3390,,ident} χαρακτηριστικό των αντικειμένων @ref{420,,threading.Thread} για να λάβετε μια κατάλληλη τιμή για το `thread_id'.

@cartouche
@quotation Προειδοποίηση 
Η μετάδοση ενός μη έγκυρου ή ληγμένου `thread_id' μπορεί να έχει ως αποτέλεσμα μη ορισμένη συμπεριφορά, όπως σφάλμα τμηματοποίησης.
@end quotation
@end cartouche

@ref{232d,,Διαθεσιμότητα}: Unix

Δείτε τη σελίδα του εγχειριδίου για το @code{pthread_getcpuclockid(3)@footnote{https://manpages.debian.org/pthread_getcpuclockid(3)}} για περαιτέρω πληροφορίες.


Added in version 3.7.

@end deffn

@geindex clock_getres() (στη μονάδα time)
@anchor{library/time time clock_getres}@anchor{1508}
@deffn {Συνάρτηση} time.clock_getres (clk_id)

Επιστρέφει την ανάλυση (ακρίβεια) του συγκεκριμένου ρολογιού `clk_id'. Ανατρέξτε στο @ref{3309,,Σταθερές αναγνωριστικού ρολογιού} για μια λίστα αποδεκτών τιμών για `clk_id'.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex clock_gettime() (στη μονάδα time)
@anchor{library/time time clock_gettime}@anchor{1509}
@deffn {Συνάρτηση} time.clock_gettime (clk_id) -> float

Επιστρέφει τον χρόνο του συγκεκριμένου ρολογιού `clk_id'. Ανατρέξτε στο @ref{3309,,Σταθερές αναγνωριστικού ρολογιού} για μια λίστα αποδεκτών τιμών για `clk_id'.

Χρησιμοποιήστε την @ref{ea9,,clock_gettime_ns()} για να αποφύγετε την απώλεια ακρίβειας που προκαλείται από τον τύπο @ref{327,,float}.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex clock_gettime_ns() (στη μονάδα time)
@anchor{library/time time clock_gettime_ns}@anchor{ea9}
@deffn {Συνάρτηση} time.clock_gettime_ns (clk_id) -> int

Παρόμοιο με την @ref{1509,,clock_gettime()} αλλά επιστρέφει τον χρόνο σε νανοδευτερόλεπτα.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.7.

@end deffn

@geindex clock_settime() (στη μονάδα time)
@anchor{library/time time clock_settime}@anchor{150a}
@deffn {Συνάρτηση} time.clock_settime (clk_id, time)

Ορίζει τον χρόνο του συγκεκριμένου ρολογιού `clk_id'. Επί του παρόντος, το @ref{a89,,CLOCK_REALTIME} είναι η μόνη αποδεκτή τιμή για το `clk_id'.

Χρησιμοποιήστε την @ref{eaa,,clock_settime_ns()} για να αποφύγετε την απώλεια ακρίβειας που προκαλείται από τον τύπο @ref{327,,float}.

@ref{232d,,Διαθεσιμότητα}: Unix, not Android, not iOS.


Added in version 3.3.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `time', not only integer or float.

@end deffn

@geindex clock_settime_ns() (στη μονάδα time)
@anchor{library/time time clock_settime_ns}@anchor{eaa}
@deffn {Συνάρτηση} time.clock_settime_ns (clk_id, time: int)

Παρόμοιο με την @ref{150a,,clock_settime()} αλλά ορίζει τον χρόνο με νανοδευτερόλεπτα.

@ref{232d,,Διαθεσιμότητα}: Unix, not Android, not iOS.


Added in version 3.7.

@end deffn

@geindex ctime() (στη μονάδα time)
@anchor{library/time time ctime}@anchor{2ad8}
@deffn {Συνάρτηση} time.ctime ([secs])

Μετατρέπει έναν χρόνο εκφρασμένο σε δευτερόλεπτα από το @ref{3139,,epoch} σε μια συμβολοσειρά της μορφής: @code{'Sun Jun 20 23:21:05 1993'} που αναπαριστά την τοπική ώρα. Το πεδίο της ημέρας είναι δύο χαρακτήρων και γεμίζεται με κενό αν η ημέρα είναι μονοψήφια, π.χ.: @code{'Wed Jun  9 04:26:40 1993'}.

Αν το `secs' δεν παρέχεται ή είναι @ref{a65,,None}, χρησιμοποιείται ο τρέχων χρόνος όπως επιστρέφεται από την @ref{75e,,time()}. Το @code{ctime(secs)} είναι ισοδύναμο με το @code{asctime(localtime(secs))}. Οι πληροφορίες τοπικής ρύθμισης δεν χρησιμοποιούνται από την @ref{2ad8,,ctime()}.


Άλλαξε στην έκδοση 3.15: Accepts any real number, not only integer or float.

@end deffn

@geindex get_clock_info() (στη μονάδα time)
@anchor{library/time time get_clock_info}@anchor{1507}
@deffn {Συνάρτηση} time.get_clock_info (name)

Λάβετε πληροφορίες για το συγκεκριμένο ρολόι ως αντικείμενο χώρου ονομάτων. Τα υποστηριζόμενα ονόματα ρολογιών και οι αντίστοιχες συναρτήσεις για την ανάγνωση της τιμής τους είναι:


@itemize *

@item 
@code{'monotonic'}: @ref{75d,,time.monotonic()}

@item 
@code{'perf_counter'}: @ref{e49,,time.perf_counter()}

@item 
@code{'process_time'}: @ref{e4a,,time.process_time()}

@item 
@code{'thread_time'}: @ref{d03,,time.thread_time()}

@item 
@code{'time'}: @ref{75e,,time.time()}
@end itemize

Το αποτέλεσμα έχει τα ακόλουθα χαρακτηριστικά:


@itemize -

@item 
`adjustable': @code{True} αν το ρολόι μπορεί να ρυθμιστεί να πηδήξει μπροστά ή πίσω στον χρόνο, διαφορετικά @code{False}. Δεν αναφέρεται σε σταδιακές NTP ρυθμίσεις ρυθμού.

@item 
`implementation': Το όνομα της υποκείμενης συνάρτησης C που χρησιμοποιείται για να λάβει την τιμή του ρολογιού. Ανατρέξτε στο @ref{3309,,Σταθερές αναγνωριστικού ρολογιού} για πιθανές τιμές.

@item 
`monotonic': @code{True} αν το ρολόι δεν μπορεί να πάει πίσω, διαφορετικά @code{False}

@item 
`resolution': Η ανάλυση του ρολογιού σε δευτερόλεπτα (@ref{327,,float})
@end itemize


Added in version 3.3.

@end deffn

@geindex gmtime() (στη μονάδα time)
@anchor{library/time time gmtime}@anchor{1569}
@deffn {Συνάρτηση} time.gmtime ([secs])

Μετατρέπει έναν χρόνο εκφρασμένο σε δευτερόλεπτα από το @ref{3139,,epoch} σε μια @ref{10a7,,struct_time} σε UTC στην οποία η σημαία dst είναι πάντα μηδέν. Αν το `secs' δεν παρέχεται ή είναι @ref{a65,,None}, χρησιμοποιείται ο τρέχων χρόνος όπως επιστρέφεται από την @ref{75e,,time()}. Τα κλάσματα του δευτερολέπτου αγνοούνται. Δείτε παραπάνω για μια περιγραφή του αντικειμένου @code{struct_time}. Δείτε την @ref{2b5b,,calendar.timegm()} για την αντίστροφη αυτής της συνάρτησης.


Άλλαξε στην έκδοση 3.15: Accepts any real number, not only integer or float.

@end deffn

@geindex localtime() (στη μονάδα time)
@anchor{library/time time localtime}@anchor{189b}
@deffn {Συνάρτηση} time.localtime ([secs])

Όπως η @ref{1569,,gmtime()} αλλά μετατρέπει σε τοπική ώρα. Αν το `secs' δεν παρέχεται ή είναι @ref{a65,,None}, χρησιμοποιείται ο τρέχων χρόνος όπως επιστρέφεται από την @ref{75e,,time()}. Η σημαία dst ορίζεται σε @code{1} όταν το DST ισχύει για τον δεδομένο χρόνο.

@ref{189b,,localtime()} μπορεί να κάνει raise @ref{c57,,OverflowError}, αν η χρονική σφραγίδα είναι εκτός του εύρους τιμών που υποστηρίζονται από τις πλατφόρμες C @code{localtime()} ή @code{gmtime()} συναρτήσεις, και @ref{53c,,OSError} σε @code{localtime()} ή @code{gmtime()} αποτυχία. Είναι κοινό αυτό να περιορίζεται σε έτη μεταξύ 1970 και 2038.


Άλλαξε στην έκδοση 3.15: Accepts any real number, not only integer or float.

@end deffn

@geindex mktime() (στη μονάδα time)
@anchor{library/time time mktime}@anchor{1591}
@deffn {Συνάρτηση} time.mktime (t)

Αυτή είναι η αντίστροφη συνάρτηση της @ref{189b,,localtime()}. Το όρισμά της είναι η @ref{10a7,,struct_time} ή πλήρης 9-πλειάδα (καθώς η σημαία dst είναι απαραίτητη· χρησιμοποιήστε @code{-1} ως σημαία dst αν είναι άγνωστη) που εκφράζει τον χρόνο σε `τοπική' ώρα, όχι σε UTC. Επιστρέφει έναν αριθμό κινητής υποδιαστολής, για συμβατότητα με την @ref{75e,,time()}. Αν η τιμή εισόδου δεν μπορεί να αναπαρασταθεί ως έγκυρος χρόνος, είτε @ref{c57,,OverflowError} είτε @ref{277,,ValueError} θα γίνει raise (που εξαρτάται από το αν η μη έγκυρη τιμή πιαστεί από την Python ή τις υποκείμενες C βιβλιοθήκες). Η πιο πρώιμη ημερομηνία για την οποία μπορεί να δημιουργήσει έναν χρόνο εξαρτάται από την πλατφόρμα.
@end deffn

@geindex monotonic() (στη μονάδα time)
@anchor{library/time time monotonic}@anchor{75d}
@deffn {Συνάρτηση} time.monotonic () -> float

Επιστρέφει την τιμή (σε κλασματικά δευτερόλεπτα) ενός μονότονου ρολογιού, δηλαδή ενός ρολογιού που δεν μπορεί να πάει πίσω. Το ρολόι δεν επηρεάζεται από ενημερώσεις του συστήματος ρολογιού. Το σημείο αναφοράς της επιστρεφόμενης τιμής είναι απροσδιόριστο, έτσι ώστε μόνο η διαφορά μεταξύ των αποτελεσμάτων δύο κλήσεων να είναι έγκυρη.

Ρολόι:


@itemize *

@item 
Στα Windows, καλέστε τα @code{QueryPerformanceCounter()} και @code{QueryPerformanceFrequency()}.

@item 
Στο macOS, καλέστε τα @code{mach_absolute_time()} και @code{mach_timebase_info()}.

@item 
Στο HP-UX, καλέστε το @code{gethrtime()}.

@item 
Καλέστε το @code{clock_gettime(CLOCK_HIGHRES)} αν είναι διαθέσιμο.

@item 
Αλλιώς, καλέστε το @code{clock_gettime(CLOCK_MONOTONIC)}.
@end itemize

Χρησιμοποιήστε την @ref{eab,,monotonic_ns()} για να αποφύγετε την απώλεια ακρίβειας που προκαλείται από τον τύπο @ref{327,,float}.


Added in version 3.3.



Άλλαξε στην έκδοση 3.5: Η συνάρτηση είναι τώρα πάντα διαθέσιμη και το ρολόι είναι τώρα ίδιο για όλες τις διαδικασίες.



Άλλαξε στην έκδοση 3.10: Στο macOS, το ρολόι είναι τώρα ίδιο για όλες τις διαδικασίες.

@end deffn

@geindex monotonic_ns() (στη μονάδα time)
@anchor{library/time time monotonic_ns}@anchor{eab}
@deffn {Συνάρτηση} time.monotonic_ns () -> int

Παρόμοιο με την @ref{75d,,monotonic()}, αλλά επιστρέφει τον χρόνο σε νανοδευτερόλεπτα.


Added in version 3.7.

@end deffn

@geindex perf_counter() (στη μονάδα time)
@anchor{library/time time perf_counter}@anchor{e49}
@deffn {Συνάρτηση} time.perf_counter () -> float

@geindex μετρήσεις απόδοσης

Επιστρέφει την τιμή (σε κλασματικά δευτερόλεπτα) ενός μετρητή απόδοσης, δηλαδή ενός ρολογιού με την υψηλότερη διαθέσιμη ανάλυση για τη μέτρηση μιας σύντομης διάρκειας. Περιλαμβάνει τον χρόνο που πέρασε κατά τη διάρκεια του ύπνου. Το ρολόι είναι το ίδιο για όλες τις διαδικασίες. Το σημείο αναφοράς της επιστρεφόμενης τιμής είναι απροσδιόριστο, έτσι ώστε μόνο η διαφορά μεταξύ των αποτελεσμάτων δύο κλήσεων να είναι έγκυρη.

Στο CPython, χρησιμοποιεί το ίδιο ρολόι με την @ref{75d,,time.monotonic()} και είναι ένα μονότονο ρολόι, δηλαδή ένα ρολόι που δεν μπορεί να πάει πίσω.

Χρησιμοποιήστε την @ref{eac,,perf_counter_ns()} για να αποφύγετε την απώλεια ακρίβειας που προκαλείται από τον τύπο @ref{327,,float}.


Added in version 3.3.



Άλλαξε στην έκδοση 3.10: Στα Windows, το ρολόι είναι τώρα ίδιο για όλες τις διαδικασίες.



Άλλαξε στην έκδοση 3.13: Χρησιμοποιεί το ίδιο ρολόι με την @ref{75d,,time.monotonic()}.

@end deffn

@geindex perf_counter_ns() (στη μονάδα time)
@anchor{library/time time perf_counter_ns}@anchor{eac}
@deffn {Συνάρτηση} time.perf_counter_ns () -> int

Παρόμοιο με την @ref{e49,,perf_counter()}, αλλά επιστρέφει τον χρόνο σε νανοδευτερόλεπτα.


Added in version 3.7.

@end deffn

@geindex process_time() (στη μονάδα time)
@anchor{library/time time process_time}@anchor{e4a}
@deffn {Συνάρτηση} time.process_time () -> float

@geindex χρόνος CPU
@geindex χρόνος επεξεργαστή
@geindex μετρήσεις απόδοσης

Επιστρέφει την τιμή (σε κλασματικά δευτερόλεπτα) του αθροίσματος του συστήματος και του χρήστη CPU χρόνου της τρέχουσας διαδικασίας. Δεν περιλαμβάνει τον χρόνο που πέρασε κατά τη διάρκεια του ύπνου. Είναι σε επίπεδο διαδικασίας από τον ορισμό. Το σημείο αναφοράς της επιστρεφόμενης τιμής είναι απροσδιόριστο, έτσι ώστε μόνο η διαφορά μεταξύ των αποτελεσμάτων δύο κλήσεων να είναι έγκυρη.

Χρησιμοποιήστε την @ref{ead,,process_time_ns()} για να αποφύγετε την απώλεια ακρίβειας που προκαλείται από τον τύπο @ref{327,,float}.


Added in version 3.3.

@end deffn

@geindex process_time_ns() (στη μονάδα time)
@anchor{library/time time process_time_ns}@anchor{ead}
@deffn {Συνάρτηση} time.process_time_ns () -> int

Παρόμοιο με την @ref{e4a,,process_time()} αλλά επιστρέφει τον χρόνο σε νανοδευτερόλεπτα.


Added in version 3.7.

@end deffn

@geindex sleep() (στη μονάδα time)
@anchor{library/time time sleep}@anchor{a8c}
@deffn {Συνάρτηση} time.sleep (secs)

Suspend execution of the calling thread for the given number of seconds.
The argument may be a non-integer to indicate a more precise sleep time.

Αν ο ύπνος διακοπεί από ένα σήμα και δεν γίνει raise καμία εξαίρεση από τον χειριστή σήματος, ο ύπνος επανεκκινείται με έναν επανυπολογισμένο χρόνο λήξης.

Ο χρόνος αναστολής μπορεί να είναι μεγαλύτερος από τον ζητούμενο κατά αυθαίρετο ποσό, λόγω του προγραμματισμού άλλων δραστηριοτήτων στο σύστημα.

@subsubheading Υλοποίηση Windows


Στα Windows, αν το `secs' είναι μηδέν, το νήμα παραχωρεί το υπόλοιπο του χρόνου του σε οποιοδήποτε άλλο νήμα είναι έτοιμο να εκτελεστεί. Αν δεν υπάρχουν άλλα νήματα έτοιμα να εκτελεστούν, η συνάρτηση επιστρέφει αμέσως και το νήμα συνεχίζει την εκτέλεση. Στα Windows 10 και νεότερα, η υλοποίηση χρησιμοποιεί έναν χρονιστή υψηλής ακρίβειας@footnote{https://learn.microsoft.com/windows/win32/api/synchapi/nf-synchapi-createwaitabletimerexw} που παρέχει ανάλυση των 100 νανοδευτερολέπτων. Αν το `secs' είναι μηδέν, χρησιμοποιείται το @code{Sleep(0)}.

@subsubheading Υλοποίηση Unix



@itemize *

@item 
Χρησιμοποιήστε το @code{clock_nanosleep()} αν είναι διαθέσιμο (ανάλυση: 1 nanosecond).

@item 
Ή χρησιμοποιήστε το @code{nanosleep()} αν είναι διαθέσιμο (ανάλυση: 1 nanosecond);

@item 
Ή χρησιμοποιήστε το @code{select()} (ανάλυση: 1 microsecond).
@end itemize

@cartouche
@quotation Σημείωση 
Για να μιμηθείτε μια «no-op», χρησιμοποιήστε το @ref{427,,pass} αντί για @code{time.sleep(0)}.

Για να παραχωρήσετε εκούσια την CPU, καθορίστε μια πολιτική @ref{3350,,scheduling policy} σε πραγματικό χρόνο και χρησιμοποιήστε την @ref{14bd,,os.sched_yield()} αντί.
@end quotation
@end cartouche

Κάνει raise ένα @ref{1e65,,auditing event} @code{time.sleep} με όρισμα @code{secs}.


Άλλαξε στην έκδοση 3.5: Η συνάρτηση τώρα κοιμάται τουλάχιστον `secs' ακόμα και αν ο ύπνος διακοπεί από ένα σήμα, εκτός αν ο χειριστής σήματος κάνει raise μια εξαίρεση (δείτε το 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} για την αιτιολόγηση).



Άλλαξε στην έκδοση 3.11: Στο Unix, οι συναρτήσεις @code{clock_nanosleep()} και @code{nanosleep()} τώρα χρησιμοποιούνται αν είναι διαθέσιμες. Στα Windows, τώρα χρησιμοποιείται ένας χρονιστής που μπορεί να αναμένει.



Άλλαξε στην έκδοση 3.13: Κάνει raise ένα auditing event.



Άλλαξε στην έκδοση 3.15: Accepts any real number, not only integer or float.

@end deffn

@geindex % (ποσοστό);μορφή ημερομηνίας και ώρας

@geindex strftime() (στη μονάδα time)
@anchor{library/time time strftime}@anchor{1592}
@deffn {Συνάρτηση} time.strftime (format[, t])

Μετατρέπει μια πλειάδα ή @ref{10a7,,struct_time} που αναπαριστά έναν χρόνο όπως επιστρέφεται από την @ref{1569,,gmtime()} ή @ref{189b,,localtime()} σε μια συμβολοσειρά όπως καθορίζεται από το όρισμα `format'. Αν το `t' δεν παρέχεται, χρησιμοποιείται ο τρέχων χρόνος όπως επιστρέφεται από την @code{localtime()}. Το `format' πρέπει να είναι μια συμβολοσειρά. Η @ref{277,,ValueError} γίνεται raise αν οποιοδήποτε πεδίο στο `t' είναι εκτός του επιτρεπτού εύρους.

0 είναι ένα νόμιμο όρισμα για οποιαδήποτε θέση στην πλειάδα χρόνου· αν είναι κανονικά παράνομο, η τιμή αναγκάζεται σε μια σωστή.

Οι ακόλουθες οδηγίες μπορούν να ενσωματωθούν στη συμβολοσειρά `format'. Εμφανίζονται χωρίς την προαιρετική προδιαγραφή πλάτους πεδίου και ακρίβειας, και αντικαθίστανται από τους υποδεικνυόμενους χαρακτήρες στο αποτέλεσμα της @ref{1592,,strftime()}:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Οδηγία

@tab

Σημασία

@tab

Σημειώσεις

@item

@code{%a}

@tab

Τοπικό συντομογραφημένο όνομα ημέρας της εβδομάδας.

@tab

@item

@code{%A}

@tab

Τοπικό πλήρες όνομα ημέρας της εβδομάδας.

@tab

@item

@code{%b}

@tab

Τοπικό συντομογραφημένο όνομα μήνα.

@tab

@item

@code{%B}

@tab

Τοπικό πλήρες όνομα μήνα.

@tab

@item

@code{%c}

@tab

Τοπική κατάλληλη αναπαράσταση ημερομηνίας και ώρας.

@tab

@item

@code{%d}

@tab

Ημέρα του μήνα ως δεκαδικός αριθμός [01,31].

@tab

@item

@code{%f}

@tab


@table @asis

@item Μικροδευτερόλεπτα ως δεκαδικός αριθμός

[000000,999999].
@end table

@tab

(1)

@item

@code{%H}

@tab

Ώρα (ρολόι 24 ωρών) ως δεκαδικός αριθμός [00,23].

@tab

@item

@code{%I}

@tab

Ώρα (ρολόι 12 ωρών) ως δεκαδικός αριθμός [01,12].

@tab

@item

@code{%j}

@tab

Ημέρα του έτους ως δεκαδικός αριθμός [001,366].

@tab

@item

@code{%m}

@tab

Μήνας ως δεκαδικός αριθμός [01,12].

@tab

@item

@code{%M}

@tab

Λεπτό ως δεκαδικός αριθμός [00,59].

@tab

@item

@code{%p}

@tab

Τοπικό ισοδύναμο είτε του AM είτε του PM.

@tab

(2)

@item

@code{%S}

@tab

Δευτερόλεπτο ως δεκαδικός αριθμός [00,61].

@tab

(3)

@item

@code{%U}

@tab

Αριθμός εβδομάδας του έτους (η Κυριακή ως πρώτη ημέρα της εβδομάδας) ως δεκαδικός αριθμός [00,53]. Όλες οι ημέρες σε ένα νέο έτος που προηγούνται της πρώτης Κυριακής θεωρούνται ότι είναι στην εβδομάδα 0.

@tab

(4)

@item

@code{%u}

@tab

Ημέρα της εβδομάδας (η Δευτέρα είναι 1· η Κυριακή είναι 7) ως δεκαδικός αριθμός [1, 7].

@tab

@item

@code{%w}

@tab

Ημέρα της εβδομάδας ως δεκαδικός αριθμός [0(Κυριακή),6].

@tab

@item

@code{%W}

@tab

Αριθμός εβδομάδας του έτους (η Δευτέρα ως πρώτη ημέρα της εβδομάδας) ως δεκαδικός αριθμός [00,53]. Όλες οι ημέρες σε ένα νέο έτος που προηγούνται της πρώτης Δευτέρας θεωρούνται ότι είναι στην εβδομάδα 0.

@tab

(4)

@item

@code{%x}

@tab

Τοπική κατάλληλη αναπαράσταση ημερομηνίας.

@tab

@item

@code{%X}

@tab

Τοπική κατάλληλη αναπαράσταση ώρας.

@tab

@item

@code{%y}

@tab

Έτος χωρίς αιώνα ως δεκαδικός αριθμός [00,99].

@tab

@item

@code{%Y}

@tab

Έτος με αιώνα ως δεκαδικός αριθμός.

@tab

@item

@code{%z}

@tab

Μετατόπιση ζώνης ώρας που υποδεικνύει μια θετική ή αρνητική χρονική διαφορά από το UTC/GMT της μορφής +HHMM ή -HHMM, όπου το H αντιπροσωπεύει δεκαδικά ψηφία ώρας και το M αντιπροσωπεύει δεκαδικά ψηφία λεπτών [-23:59, +23:59]. @footnote{
Η χρήση του @code{%Z} είναι πλέον αποσυρμένη, αλλά η διαφυγή @code{%z} που επεκτείνεται σε την προτιμώμενη μετατόπιση ώρας/λεπτού δεν υποστηρίζεται από όλες τις βιβλιοθήκες ANSI C. Επίσης, μια αυστηρή ανάγνωση του αρχικού προτύπου 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} του 1982 απαιτεί ένα διψήφιο έτος (@code{%y} αντί για @code{%Y}), αλλά η πρακτική μετακινήθηκε σε έτη με 4 ψηφία πολύ πριν από το έτος 2000. Μετά από αυτό, το 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} έγινε παρωχημένο και το έτος με 4 ψηφία έχει προταθεί πρώτα από το 
@geindex RFC; RFC 1123
@uref{https://datatracker.ietf.org/doc/html/rfc1123.html,RFC 1123} και στη συνέχεια επιβλήθηκε από το 
@geindex RFC; RFC 2822
@uref{https://datatracker.ietf.org/doc/html/rfc2822.html,RFC 2822}, με το 
@geindex RFC; RFC 5322
@uref{https://datatracker.ietf.org/doc/html/rfc5322.html,RFC 5322} να συνεχίζει αυτή την απαίτηση.
}

@tab

@item

@code{%Z}

@tab

Όνομα ζώνης ώρας (κανένας χαρακτήρας αν δεν υπάρχει ζώνη ώρας).  Απαρχαιωμένο. @footnote{
Η χρήση του @code{%Z} είναι πλέον αποσυρμένη, αλλά η διαφυγή @code{%z} που επεκτείνεται σε την προτιμώμενη μετατόπιση ώρας/λεπτού δεν υποστηρίζεται από όλες τις βιβλιοθήκες ANSI C. Επίσης, μια αυστηρή ανάγνωση του αρχικού προτύπου 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} του 1982 απαιτεί ένα διψήφιο έτος (@code{%y} αντί για @code{%Y}), αλλά η πρακτική μετακινήθηκε σε έτη με 4 ψηφία πολύ πριν από το έτος 2000. Μετά από αυτό, το 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} έγινε παρωχημένο και το έτος με 4 ψηφία έχει προταθεί πρώτα από το 
@geindex RFC; RFC 1123
@uref{https://datatracker.ietf.org/doc/html/rfc1123.html,RFC 1123} και στη συνέχεια επιβλήθηκε από το 
@geindex RFC; RFC 2822
@uref{https://datatracker.ietf.org/doc/html/rfc2822.html,RFC 2822}, με το 
@geindex RFC; RFC 5322
@uref{https://datatracker.ietf.org/doc/html/rfc5322.html,RFC 5322} να συνεχίζει αυτή την απαίτηση.
}

@tab

@item

@code{%G}

@tab

ISO 8601 έτος (παρόμοιο με το @code{%Y} αλλά ακολουθεί τους κανόνες για το ISO 8601 ημερολογιακό έτος). Το έτος ξεκινά με την εβδομάδα που περιέχει την πρώτη Πέμπτη του ημερολογιακού έτους.

@tab

@item

@code{%V}

@tab

ISO 8601 αριθμός εβδομάδας (ως δεκαδικός αριθμός [01,53]). Η πρώτη εβδομάδα του έτους είναι αυτή που περιέχει την πρώτη Πέμπτη του έτους. Οι εβδομάδες ξεκινούν τη Δευτέρα.

@tab

@item

@code{%%}

@tab

Ένας κυριολεκτικός χαρακτήρας @code{'%'}.

@tab

@end multitable


Σημειώσεις:


@enumerate 

@item 
Η οδηγία μορφοποίησης @code{%f} εφαρμόζεται μόνο στην @ref{17cf,,strptime()}, όχι στην @ref{1592,,strftime()}. Ωστόσο, δείτε επίσης την @ref{2d2,,datetime.datetime.strptime()} και την @ref{1051,,datetime.datetime.strftime()} όπου η οδηγία μορφοποίησης @code{%f} @ref{2aaa,,εφαρμόζεται στα μικροδευτερόλεπτα}.

@item 
Όταν χρησιμοποιείται με τη συνάρτηση @ref{17cf,,strptime()}, η οδηγία @code{%p} επηρεάζει μόνο το πεδίο ώρας εξόδου αν η οδηγία @code{%I} χρησιμοποιείται για την ανάλυση της ώρας.
@end enumerate
@anchor{library/time leap-second}@anchor{3391}

@enumerate 3

@item 
Το εύρος είναι πραγματικά από @code{0} έως @code{61}· η τιμή @code{60} είναι έγκυρη σε χρονικές σφραγίδες που αναπαριστούν leap seconds@footnote{https://en.wikipedia.org/wiki/Leap_second} και η τιμή @code{61} υποστηρίζεται για ιστορικούς λόγους.

@item 
Όταν χρησιμοποιείται με τη συνάρτηση @ref{17cf,,strptime()}, τα @code{%U} και @code{%W} χρησιμοποιούνται μόνο σε υπολογισμούς όταν η ημέρα της εβδομάδας και το έτος καθορίζονται.
@end enumerate

Εδώ είναι ένα παράδειγμα, μια μορφή για ημερομηνίες συμβατή με αυτή που καθορίζεται στο 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} πρότυπο ηλεκτρονικού ταχυδρομείου Internet. @footnote{
Η χρήση του @code{%Z} είναι πλέον αποσυρμένη, αλλά η διαφυγή @code{%z} που επεκτείνεται σε την προτιμώμενη μετατόπιση ώρας/λεπτού δεν υποστηρίζεται από όλες τις βιβλιοθήκες ANSI C. Επίσης, μια αυστηρή ανάγνωση του αρχικού προτύπου 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} του 1982 απαιτεί ένα διψήφιο έτος (@code{%y} αντί για @code{%Y}), αλλά η πρακτική μετακινήθηκε σε έτη με 4 ψηφία πολύ πριν από το έτος 2000. Μετά από αυτό, το 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} έγινε παρωχημένο και το έτος με 4 ψηφία έχει προταθεί πρώτα από το 
@geindex RFC; RFC 1123
@uref{https://datatracker.ietf.org/doc/html/rfc1123.html,RFC 1123} και στη συνέχεια επιβλήθηκε από το 
@geindex RFC; RFC 2822
@uref{https://datatracker.ietf.org/doc/html/rfc2822.html,RFC 2822}, με το 
@geindex RFC; RFC 5322
@uref{https://datatracker.ietf.org/doc/html/rfc5322.html,RFC 5322} να συνεχίζει αυτή την απαίτηση.
}

@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

Πρόσθετες οδηγίες μπορεί να υποστηρίζονται σε ορισμένες πλατφόρμες, αλλά μόνο αυτές που αναφέρονται εδώ έχουν μια σημασία που τυποποιείται από την ANSI C. Για να δείτε το πλήρες σύνολο κωδικών μορφοποίησης που υποστηρίζονται στην πλατφόρμα σας, συμβουλευτείτε την τεκμηρίωση @code{strftime(3)@footnote{https://manpages.debian.org/strftime(3)}}.

Σε ορισμένες πλατφόρμες, μια προαιρετική προδιαγραφή πλάτους πεδίου και ακρίβειας μπορεί να ακολουθεί αμέσως το αρχικό @code{'%} μιας οδηγίας με την εξής σειρά· αυτό επίσης δεν είναι φορητό. Το πλάτος πεδίου είναι κανονικά 2 εκτός από το @code{%j} όπου είναι 3.
@end deffn

@geindex % (ποσοστό);μορφή ημερομηνίας και ώρας

@geindex strptime() (στη μονάδα time)
@anchor{library/time time strptime}@anchor{17cf}
@deffn {Συνάρτηση} time.strptime (string[, format])

Ανάλυση μιας συμβολοσειράς που αναπαριστά έναν χρόνο σύμφωνα με μια μορφή. Η επιστρεφόμενη τιμή είναι μια @ref{10a7,,struct_time} όπως επιστρέφεται από την @ref{1569,,gmtime()} ή την @ref{189b,,localtime()}.

Η παράμετρος `format' χρησιμοποιεί τις ίδιες οδηγίες με αυτές που χρησιμοποιούνται από την @ref{1592,,strftime()}; προεπιλέγεται σε @code{"%a %b %d %H:%M:%S %Y"} που ταιριάζει με τη μορφοποίηση που επιστρέφεται από την @ref{2ad8,,ctime()}. Αν το `string' δεν μπορεί να αναλυθεί σύμφωνα με το `format', ή αν έχει πλεονάζοντα δεδομένα μετά την ανάλυση, γίνεται raise η @ref{277,,ValueError}. Οι προεπιλεγμένες τιμές που χρησιμοποιούνται για να συμπληρώσουν τυχόν ελλείποντα δεδομένα όταν δεν μπορούν να εξαχθούν πιο ακριβείς τιμές είναι @code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)}. Τόσο το `string' όσο και το `format' πρέπει να είναι συμβολοσειρές.

Για παράδειγμα:

@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

Η υποστήριξη για την οδηγία @code{%Z} βασίζεται στις τιμές που περιέχονται στο @code{tzname} και στο αν το @code{daylight} είναι αληθές. Εξαιτίας αυτού, είναι ειδική για την πλατφόρμα εκτός από την αναγνώριση των UTC και GMT που είναι πάντα γνωστά (και θεωρούνται ότι δεν είναι ζώνες ώρας θερινής ώρας).

Μόνο οι οδηγίες που καθορίζονται στην τεκμηρίωση υποστηρίζονται. Επειδή η @code{strftime()} υλοποιείται ανά πλατφόρμα, μπορεί μερικές φορές να προσφέρει περισσότερες οδηγίες από αυτές που αναφέρονται. Αλλά η @code{strptime()} είναι ανεξάρτητη από οποιαδήποτε πλατφόρμα και ως εκ τούτου δεν υποστηρίζει απαραίτητα όλες τις διαθέσιμες οδηγίες που δεν τεκμηριώνονται ως υποστηριζόμενες.
@end deffn

@geindex struct_time (κλάση σε time)
@anchor{library/time time struct_time}@anchor{10a7}
@deffn {Κλάση} time.struct_time

Ο τύπος της ακολουθίας τιμών χρόνου που επιστρέφεται από την @ref{1569,,gmtime()}, @ref{189b,,localtime()}, και @ref{17cf,,strptime()}. Είναι ένα αντικείμενο με μια @ref{a3d,,named tuple} διεπαφή: οι τιμές μπορούν να προσπελαστεί με δείκτη και με όνομα χαρακτηριστικού. Παρουσιάζονται οι ακόλουθες τιμές:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

Δείκτης

@tab

Χαρακτηριστικό

@tab

Τιμές

@item

0

@tab

@geindex tm_year (ιδιότητα της time.struct_time)
@anchor{library/time time struct_time tm_year}@anchor{189a}
@deffn {Ιδιότητα} tm_year
@end deffn

@tab

(για παράδειγμα, 1993)

@item

1

@tab

@geindex tm_mon (ιδιότητα της time.struct_time)
@anchor{library/time time struct_time tm_mon}@anchor{3392}
@deffn {Ιδιότητα} tm_mon
@end deffn

@tab

εύρος [1, 12]

@item

2

@tab

@geindex tm_mday (ιδιότητα της time.struct_time)
@anchor{library/time time struct_time tm_mday}@anchor{3393}
@deffn {Ιδιότητα} tm_mday
@end deffn

@tab

εύρος [1, 31]

@item

3

@tab

@geindex tm_hour (ιδιότητα της time.struct_time)
@anchor{library/time time struct_time tm_hour}@anchor{3394}
@deffn {Ιδιότητα} tm_hour
@end deffn

@tab

εύρος [0, 23]

@item

4

@tab

@geindex tm_min (ιδιότητα της time.struct_time)
@anchor{library/time time struct_time tm_min}@anchor{3395}
@deffn {Ιδιότητα} tm_min
@end deffn

@tab

εύρος [0, 59]

@item

5

@tab

@geindex tm_sec (ιδιότητα της time.struct_time)
@anchor{library/time time struct_time tm_sec}@anchor{3396}
@deffn {Ιδιότητα} tm_sec
@end deffn

@tab

range [0, 61]; see @ref{3391,,Note (2)} in @ref{1592,,strftime()}

@item

6

@tab

@geindex tm_wday (ιδιότητα της time.struct_time)
@anchor{library/time time struct_time tm_wday}@anchor{3397}
@deffn {Ιδιότητα} tm_wday
@end deffn

@tab

εύρος [0, 6]; η Δευτέρα είναι 0

@item

7

@tab

@geindex tm_yday (ιδιότητα της time.struct_time)
@anchor{library/time time struct_time tm_yday}@anchor{3398}
@deffn {Ιδιότητα} tm_yday
@end deffn

@tab

εύρος [1, 366]

@item

8

@tab

@geindex tm_isdst (ιδιότητα της time.struct_time)
@anchor{library/time time struct_time tm_isdst}@anchor{2ae9}
@deffn {Ιδιότητα} tm_isdst
@end deffn

@tab

0, 1 ή -1; δείτε παρακάτω

@item

N/A

@tab

@geindex tm_zone (ιδιότητα της time.struct_time)
@anchor{library/time time struct_time tm_zone}@anchor{338d}
@deffn {Ιδιότητα} tm_zone
@end deffn

@tab

συντομογραφία ονόματος ζώνης ώρας

@item

N/A

@tab

@geindex tm_gmtoff (ιδιότητα της time.struct_time)
@anchor{library/time time struct_time tm_gmtoff}@anchor{338c}
@deffn {Ιδιότητα} tm_gmtoff
@end deffn

@tab

μετατόπιση ανατολικά του UTC σε δευτερόλεπτα

@end multitable


Σημειώστε ότι σε αντίθεση με τη δομή C, η τιμή του μήνα είναι σε εύρος [1, 12], όχι [0, 11].

Σε κλήσεις στην @ref{1591,,mktime()}, το @ref{2ae9,,tm_isdst} μπορεί να οριστεί σε 1 όταν ισχύει η θερινή ώρα, και σε 0 όταν δεν ισχύει. Μια τιμή -1 υποδεικνύει ότι αυτό δεν είναι γνωστό, και συνήθως θα έχει ως αποτέλεσμα τη συμπλήρωση της σωστής κατάστασης.

Όταν μια πλειάδα με λανθασμένο μήκος περνά σε μια συνάρτηση που αναμένει μια @ref{10a7,,struct_time}, ή έχει στοιχεία λάθος τύπου, γίνεται raise μια @ref{291,,TypeError}.
@end deffn

@geindex time() (στη μονάδα time)
@anchor{library/time time time}@anchor{75e}
@deffn {Συνάρτηση} time.time () -> float

Επιστρέφει τον χρόνο σε δευτερόλεπτα από την @ref{3139,,epoch} ως αριθμό κινητής υποδιαστολής. Η διαχείριση των leap seconds@footnote{https://en.wikipedia.org/wiki/Leap_second} εξαρτάται από την πλατφόρμα. Στα Windows και στα περισσότερα συστήματα Unix, τα leap seconds δεν υπολογίζονται στον χρόνο σε δευτερόλεπτα από την @ref{3139,,epoch}. Αυτό αναφέρεται συνήθως ως Unix time@footnote{https://en.wikipedia.org/wiki/Unix_time}.

Σημειώστε ότι παρόλο που ο χρόνος επιστρέφεται πάντα ως αριθμός κινητής υποδιαστολής, όχι όλα τα συστήματα παρέχουν χρόνο με καλύτερη ακρίβεια από 1 δευτερόλεπτο. Ενώ αυτή η συνάρτηση κανονικά επιστρέφει μη φθίνουσες τιμές, μπορεί να επιστρέψει μια χαμηλότερη τιμή από μια προηγούμενη κλήση αν το ρολόι του συστήματος έχει οριστεί πίσω μεταξύ των δύο κλήσεων.

Ο αριθμός που επιστρέφεται από την @ref{75e,,time()} μπορεί να μετατραπεί σε μια πιο συνηθισμένη μορφή χρόνου (δηλαδή έτος, μήνας, ημέρα, ώρα, κ.λπ…) σε UTC περνώντας τον στην @ref{1569,,gmtime()} συνάρτηση ή σε τοπική ώρα περνώντας τον στην @ref{189b,,localtime()} συνάρτηση. Σε και τις δύο περιπτώσεις επιστρέφεται ένα αντικείμενο @ref{10a7,,struct_time}, από το οποίο τα στοιχεία της ημερολογιακής ημερομηνίας μπορούν να προσπελαστούν ως χαρακτηριστικά.

Ρολόι:


@itemize *

@item 
Στα Windows, καλέστε την @code{GetSystemTimePreciseAsFileTime()}.

@item 
Καλέστε την @code{clock_gettime(CLOCK_REALTIME)} αν είναι διαθέσιμη.

@item 
Διαφορετικά, καλέστε την @code{gettimeofday()}.
@end itemize

Χρησιμοποιήστε την @ref{eae,,time_ns()} για να αποφύγετε την απώλεια ακρίβειας που προκαλείται από τον τύπο @ref{327,,float}.
@end deffn


Άλλαξε στην έκδοση 3.13: Στα Windows, καλέστε την @code{GetSystemTimePreciseAsFileTime()} αντί για την @code{GetSystemTimeAsFileTime()}.


@geindex time_ns() (στη μονάδα time)
@anchor{library/time time time_ns}@anchor{eae}
@deffn {Συνάρτηση} time.time_ns () -> int

Παρόμοιο με την @ref{75e,,time()} αλλά επιστρέφει τον χρόνο ως ακέραιο αριθμό νανοδευτερολέπτων από την @ref{3139,,epoch}.


Added in version 3.7.

@end deffn

@geindex thread_time() (στη μονάδα time)
@anchor{library/time time thread_time}@anchor{d03}
@deffn {Συνάρτηση} time.thread_time () -> float

@geindex χρόνος CPU
@geindex χρόνος επεξεργαστή
@geindex μετρήσεις απόδοσης

Επιστρέφει την τιμή (σε κλάσματα δευτερολέπτου) του αθροίσματος του συστήματος και του χρόνου CPU χρήστη του τρέχοντος νήματος. Δεν περιλαμβάνει τον χρόνο που πέρασε κατά τη διάρκεια ύπνου. Είναι ειδικό για το νήμα από τον ορισμό του. Το σημείο αναφοράς της επιστρεφόμενης τιμής είναι απροσδιόριστο, έτσι ώστε μόνο η διαφορά μεταξύ των αποτελεσμάτων δύο κλήσεων στο ίδιο νήμα να είναι έγκυρη.

Χρησιμοποιήστε την @ref{f50,,thread_time_ns()} για να αποφύγετε την απώλεια ακρίβειας που προκαλείται από τον τύπο @ref{327,,float}.

@ref{232d,,Διαθεσιμότητα}: Linux, Unix, Windows.

Συστήματα Unix που υποστηρίζουν το @code{CLOCK_THREAD_CPUTIME_ID}.


Added in version 3.7.

@end deffn

@geindex thread_time_ns() (στη μονάδα time)
@anchor{library/time time thread_time_ns}@anchor{f50}
@deffn {Συνάρτηση} time.thread_time_ns () -> int

Παρόμοιο με την @ref{d03,,thread_time()} αλλά επιστρέφει τον χρόνο ως νανοδευτερόλεπτα.


Added in version 3.7.

@end deffn

@geindex tzset() (στη μονάδα time)
@anchor{library/time time tzset}@anchor{3399}
@deffn {Συνάρτηση} time.tzset ()

Επαναφέρει τους κανόνες μετατροπής χρόνου που χρησιμοποιούνται από τις βιβλιοθήκες ρουτίνες. Η μεταβλητή περιβάλλοντος 
@geindex TZ
@geindex μεταβλητή περιβάλλοντος; TZ
@code{TZ} καθορίζει πώς γίνεται αυτό. Θα ορίσει επίσης τις μεταβλητές @code{tzname} (από τη μεταβλητή περιβάλλοντος 
@geindex TZ
@geindex μεταβλητή περιβάλλοντος; TZ
@code{TZ}), @code{timezone} (μη DST δευτερόλεπτα Δύση του UTC), @code{altzone} (DST δευτερόλεπτα δυτικά του UTC) και @code{daylight} (σε 0 αν αυτή η ζώνη ώρας δεν έχει κανόνες θερινής ώρας, ή σε μη μηδενικό αν υπάρχει μια ώρα, παρελθούσα, παρούσα ή μελλοντική όταν ισχύει η θερινή ώρα).

@ref{232d,,Διαθεσιμότητα}: Unix.

@cartouche
@quotation Σημείωση 
Αν και σε πολλές περιπτώσεις, η αλλαγή της μεταβλητής περιβάλλοντος 
@geindex TZ
@geindex μεταβλητή περιβάλλοντος; TZ
@code{TZ} μπορεί να επηρεάσει την έξοδο συναρτήσεων όπως η @ref{189b,,localtime()} χωρίς να καλέσει την @ref{3399,,tzset()}, αυτή η συμπεριφορά δεν πρέπει να βασίζεται.

Η μεταβλητή περιβάλλοντος 
@geindex TZ
@geindex μεταβλητή περιβάλλοντος; TZ
@code{TZ} δεν πρέπει να περιέχει κενά.
@end quotation
@end cartouche

Η τυπική μορφή της μεταβλητής περιβάλλοντος 
@geindex TZ
@geindex μεταβλητή περιβάλλοντος; TZ
@code{TZ} είναι (προστέθηκε κενό για σαφήνεια):

@example
std offset [dst [offset [,start[/time], end[/time]]]]
@end example

Όπου τα συστατικά είναι:


@table @asis

@item @code{std} και @code{dst}

Τρεις ή περισσότερες αλφαριθμητικές που δίνουν τις συντομογραφίες ζώνης ώρας. Αυτές θα προωθηθούν στο time.tzname

@item @code{offset}

Η μετατόπιση έχει τη μορφή: @code{± hh[:mm[:ss]]}. Αυτό υποδεικνύει την τιμή που προστίθεται στην τοπική ώρα για να φτάσει στο UTC. Εάν προηγείται από “-”, η ζώνη ώρας είναι ανατολικά του Πρώτου Μεσημβρινού· διαφορετικά, είναι δυτικά. Αν δεν ακολουθεί μετατόπιση μετά το dst, η θερινή ώρα θεωρείται ότι είναι μία ώρα μπροστά από την κανονική ώρα.

@item @code{start[/time], end[/time]}

Υποδεικνύει πότε να αλλάξει σε και από το DST. Η μορφή των ημερομηνιών έναρξης και λήξης είναι μία από τις ακόλουθες:


@table @asis

@item @code{J@var{n}}

Η Ιουλιανή ημέρα `n' (1 <= `n' <= 365). Οι δίσεκτες ημέρες δεν μετριούνται, οπότε σε όλα τα έτη η 28η Φεβρουαρίου είναι η ημέρα 59 και η 1η Μαρτίου είναι η ημέρα 60.

@item @code{@var{n}}

Η Ιουλιανή ημέρα με βάση το μηδέν (0 <= `n' <= 365). Οι δίσεκτες ημέρες μετριούνται, και είναι δυνατόν να αναφερθεί η 29η Φεβρουαρίου.

@item @code{M@var{m}.@var{n}.@var{d}}

Η `d'’η ημέρα (0 <= `d' <= 6) της εβδομάδας `n' του μήνα `m' του έτους (1 <= `n' <= 5, 1 <= `m' <= 12, όπου η εβδομάδα 5 σημαίνει «η τελευταία `d' ημέρα στο μήνα `m'» που μπορεί να συμβεί είτε στην τέταρτη είτε στην πέμπτη εβδομάδα). Η εβδομάδα 1 είναι η πρώτη εβδομάδα στην οποία συμβαίνει η `d'’η ημέρα. Η ημέρα μηδέν είναι η Κυριακή.
@end table

Το @code{time} έχει την ίδια μορφή με την @code{offset} εκτός από το ότι δεν επιτρέπεται προθετικός χαρακτήρας (“-” ή “+”). Η προεπιλογή, αν δεν δοθεί χρόνος, είναι 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

Σε πολλά συστήματα Unix (συμπεριλαμβανομένων των *BSD, Linux, Solaris, και Darwin), είναι πιο βολικό να χρησιμοποιήσετε τη βάση δεδομένων zoneinfo (@code{tzfile(5)@footnote{https://manpages.debian.org/tzfile(5)}}) του συστήματος για να καθορίσετε τους κανόνες ζώνης ώρας. Για να το κάνετε αυτό, ορίστε τη μεταβλητή περιβάλλοντος 
@geindex TZ
@geindex μεταβλητή περιβάλλοντος; TZ
@code{TZ} στη διαδρομή του απαιτούμενου αρχείου δεδομένων ζώνης ώρας, σε σχέση με τη ρίζα της βάσης δεδομένων ζώνης ώρας “zoneinfo” του συστήματος, που συνήθως βρίσκεται στο @code{/usr/share/zoneinfo}. Για παράδειγμα, @code{'US/Eastern'}, @code{'Australia/Melbourne'}, @code{'Egypt'} ή @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 Σταθερές αναγνωριστικού ρολογιού,Σταθερές ζώνης ώρας,Συναρτήσεις<2>,time — Πρόσβαση και μετατροπές χρόνου
@anchor{library/time clock-id-constants}@anchor{339a}@anchor{library/time time-clock-id-constants}@anchor{3309}
@subsubsection Σταθερές αναγνωριστικού ρολογιού


Αυτές οι σταθερές χρησιμοποιούνται ως παράμετροι για την @ref{1508,,clock_getres()} και την @ref{1509,,clock_gettime()}.

@geindex CLOCK_BOOTTIME (στη μονάδα time)
@anchor{library/time time CLOCK_BOOTTIME}@anchor{f4d}
@deffn {Δεδομένα} time.CLOCK_BOOTTIME

Ταυτόσημο με το @ref{a88,,CLOCK_MONOTONIC}, εκτός από το ότι περιλαμβάνει επίσης οποιονδήποτε χρόνο που το σύστημα είναι σε αναστολή.

Αυτό επιτρέπει στις εφαρμογές να λαμβάνουν ένα ρολόι μονότονο με επίγνωση αναστολής χωρίς να χρειάζεται να αντιμετωπίσουν τις επιπλοκές του @ref{a89,,CLOCK_REALTIME}, το οποίο μπορεί να έχει ασυνέχειες εάν ο χρόνος αλλάξει χρησιμοποιώντας την @code{settimeofday()} ή παρόμοια.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.39.


Added in version 3.7.

@end deffn

@geindex CLOCK_HIGHRES (στη μονάδα time)
@anchor{library/time time CLOCK_HIGHRES}@anchor{339b}
@deffn {Δεδομένα} time.CLOCK_HIGHRES

Το λειτουργικό σύστημα Solaris διαθέτει ένα χρονόμετρο @code{CLOCK_HIGHRES} που προσπαθεί να χρησιμοποιήσει μια βέλτιστη πηγή υλικού και μπορεί να δώσει σχεδόν ανάλυση νανοδευτερολέπτων. Το @code{CLOCK_HIGHRES} είναι το μη ρυθμιζόμενο, ρολόι υψηλής ανάλυσης.

@ref{232d,,Διαθεσιμότητα}: Solaris.


Added in version 3.3.

@end deffn

@geindex CLOCK_MONOTONIC (στη μονάδα time)
@anchor{library/time time CLOCK_MONOTONIC}@anchor{a88}
@deffn {Δεδομένα} time.CLOCK_MONOTONIC

Ρολόι που δεν μπορεί να ρυθμιστεί και αντιπροσωπεύει τον μονότονο χρόνο από ένα απροσδιόριστο σημείο εκκίνησης.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex CLOCK_MONOTONIC_RAW (στη μονάδα time)
@anchor{library/time time CLOCK_MONOTONIC_RAW}@anchor{339c}
@deffn {Δεδομένα} time.CLOCK_MONOTONIC_RAW

Παρόμοιο με το @ref{a88,,CLOCK_MONOTONIC}, αλλά παρέχει πρόσβαση σε έναν ακατέργαστο χρόνο βασισμένο σε υλικό που δεν υπόκειται σε ρυθμίσεις NTP.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.28, macOS >= 10.12.


Added in version 3.3.

@end deffn

@geindex CLOCK_MONOTONIC_RAW_APPROX (στη μονάδα time)
@anchor{library/time time CLOCK_MONOTONIC_RAW_APPROX}@anchor{339d}
@deffn {Δεδομένα} time.CLOCK_MONOTONIC_RAW_APPROX

Παρόμοιο με το @ref{339c,,CLOCK_MONOTONIC_RAW}, αλλά διαβάζει μια τιμή που έχει αποθηκευτεί στην κρυφή μνήμη από το σύστημα κατά την αλλαγή πλαισίου και επομένως έχει λιγότερη ακρίβεια.

@ref{232d,,Διαθεσιμότητα}: macOS >= 10.12.


Added in version 3.13.

@end deffn

@geindex CLOCK_PROCESS_CPUTIME_ID (στη μονάδα time)
@anchor{library/time time CLOCK_PROCESS_CPUTIME_ID}@anchor{339e}
@deffn {Δεδομένα} time.CLOCK_PROCESS_CPUTIME_ID

Υψηλής ανάλυσης χρονομετρητής ανά διεργασία από την CPU.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex CLOCK_PROF (στη μονάδα time)
@anchor{library/time time CLOCK_PROF}@anchor{f4e}
@deffn {Δεδομένα} time.CLOCK_PROF

Υψηλής ανάλυσης χρονομετρητής ανά διεργασία από την CPU.

@ref{232d,,Διαθεσιμότητα}: FreeBSD, NetBSD >= 7, OpenBSD.


Added in version 3.7.

@end deffn

@geindex CLOCK_TAI (στη μονάδα time)
@anchor{library/time time CLOCK_TAI}@anchor{1f4b}
@deffn {Δεδομένα} time.CLOCK_TAI

International Atomic Time@footnote{https://www.nist.gov/pml/time-and-frequency-division/how-utcnist-related-coordinated-universal-time-utc-international}

Το σύστημα πρέπει να έχει έναν τρέχοντα πίνακα leap second για να δώσει τη σωστή απάντηση. Το λογισμικό PTP ή NTP μπορεί να διατηρήσει έναν πίνακα leap second.

@ref{232d,,Διαθεσιμότητα}: Linux.


Added in version 3.9.

@end deffn

@geindex CLOCK_THREAD_CPUTIME_ID (στη μονάδα time)
@anchor{library/time time CLOCK_THREAD_CPUTIME_ID}@anchor{339f}
@deffn {Δεδομένα} time.CLOCK_THREAD_CPUTIME_ID

Ρολόι χρόνου CPU ειδικό για νήμα.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@geindex CLOCK_UPTIME (στη μονάδα time)
@anchor{library/time time CLOCK_UPTIME}@anchor{f4f}
@deffn {Δεδομένα} time.CLOCK_UPTIME

Χρόνος της απόλυτης τιμής του οποίου είναι ο χρόνος που το σύστημα λειτουργεί και δεν έχει ανασταλεί, παρέχοντας ακριβή μέτρηση χρόνου λειτουργίας, τόσο απόλυτη όσο και διαστήματος.

@ref{232d,,Διαθεσιμότητα}: FreeBSD, OpenBSD >= 5.5.


Added in version 3.7.

@end deffn

@geindex CLOCK_UPTIME_RAW (στη μονάδα time)
@anchor{library/time time CLOCK_UPTIME_RAW}@anchor{e06}
@deffn {Δεδομένα} time.CLOCK_UPTIME_RAW

Ρολόι που αυξάνεται μονότονα, παρακολουθώντας τον χρόνο από ένα αυθαίρετο σημείο, ανεπηρέαστο από ρυθμίσεις συχνότητας ή χρόνου και δεν αυξάνεται ενώ το σύστημα είναι σε κατάσταση ύπνου.

@ref{232d,,Διαθεσιμότητα}: macOS >= 10.12.


Added in version 3.8.

@end deffn

@geindex CLOCK_UPTIME_RAW_APPROX (στη μονάδα time)
@anchor{library/time time CLOCK_UPTIME_RAW_APPROX}@anchor{33a0}
@deffn {Δεδομένα} time.CLOCK_UPTIME_RAW_APPROX

Όπως το @ref{e06,,CLOCK_UPTIME_RAW}, αλλά η τιμή αποθηκεύεται στην κρυφή μνήμη από το σύστημα κατά τις αλλαγές πλαισίου και επομένως έχει λιγότερη ακρίβεια.

@ref{232d,,Διαθεσιμότητα}: macOS >= 10.12.


Added in version 3.13.

@end deffn

The following constant is the only parameter that can be sent to
@ref{150a,,clock_settime()}.

@geindex CLOCK_REALTIME (στη μονάδα time)
@anchor{library/time time CLOCK_REALTIME}@anchor{a89}
@deffn {Δεδομένα} time.CLOCK_REALTIME

Ρολόι πραγματικού χρόνου. Η ρύθμιση αυτού του ρολογιού απαιτεί κατάλληλα προνόμια. Το ρολόι είναι το ίδιο για όλες τις διεργασίες.

@ref{232d,,Διαθεσιμότητα}: Unix.


Added in version 3.3.

@end deffn

@node Σταθερές ζώνης ώρας,,Σταθερές αναγνωριστικού ρολογιού,time — Πρόσβαση και μετατροπές χρόνου
@anchor{library/time time-timezone-constants}@anchor{33a1}@anchor{library/time timezone-constants}@anchor{33a2}
@subsubsection Σταθερές ζώνης ώρας


@geindex altzone (στη μονάδα time)
@anchor{library/time time altzone}@anchor{33a3}
@deffn {Δεδομένα} time.altzone

Η μετατόπιση της τοπικής ζώνης ώρας DST, σε δευτερόλεπτα δυτικά του UTC, αν είναι ορισμένη. Αυτό είναι αρνητικό αν η τοπική ζώνη ώρας DST είναι ανατολικά του UTC (όπως στη Δυτική Ευρώπη, συμπεριλαμβανομένου του Ηνωμένου Βασιλείου). Χρησιμοποιήστε αυτό μόνο αν το @code{daylight} είναι μη μηδενικό. Δείτε την σημείωση παρακάτω.
@end deffn

@geindex daylight (στη μονάδα time)
@anchor{library/time time daylight}@anchor{33a4}
@deffn {Δεδομένα} time.daylight

Μη μηδενικό αν οριστεί μια ζώνη ώρας DST. Δείτε την σημείωση παρακάτω.
@end deffn

@geindex timezone (στη μονάδα time)
@anchor{library/time time timezone}@anchor{33a5}
@deffn {Δεδομένα} time.timezone

Η μετατόπιση της τοπικής (μη DST) ζώνης ώρας, σε δευτερόλεπτα δυτικά του UTC (αρνητικό στο μεγαλύτερο μέρος της Δυτικής Ευρώπης, θετικό στις ΗΠΑ, μηδέν στο Ηνωμένο Βασίλειο). Δείτε την σημείωση παρακάτω.
@end deffn

@geindex tzname (στη μονάδα time)
@anchor{library/time time tzname}@anchor{33a6}
@deffn {Δεδομένα} time.tzname

Μια πλειάδα από δύο συμβολοσειρές: η πρώτη είναι το όνομα της τοπικής μη DST ζώνης ώρας, η δεύτερη είναι το όνομα της τοπικής ζώνης ώρας DST. Αν δεν οριστεί ζώνη ώρας DST, η δεύτερη συμβολοσειρά δεν πρέπει να χρησιμοποιηθεί. Δείτε την σημείωση παρακάτω.
@end deffn

@cartouche
@quotation Σημείωση 
Για τις παραπάνω σταθερές ζώνες ώρας (@ref{33a3,,altzone}, @ref{33a4,,daylight}, @ref{33a5,,timezone}, και @ref{33a6,,tzname}), η τιμή καθορίζεται από τους κανόνες ζώνης ώρας που ισχύουν κατά το χρόνο φόρτωσης της μονάδας ή την τελευταία φορά που καλείται η @ref{3399,,tzset()} και μπορεί να είναι λανθασμένη για χρόνους στο παρελθόν. Συνιστάται να χρησιμοποιείτε τα @ref{338c,,tm_gmtoff} και @ref{338d,,tm_zone} αποτελέσματα από την @ref{189b,,localtime()} για να λάβετε πληροφορίες ζώνης ώρας.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{33,,datetime}

Πιο αντικειμενοστραφής διεπαφή για ημερομηνίες και ώρες.

@item Module @ref{89,,locale}

Υπηρεσίες διεθνοποίησης. Η ρύθμιση τοπικής ρυθμίσεως επηρεάζει την ερμηνεία πολλών προδιαγραφών μορφοποίησης στην @ref{1592,,strftime()} και την @ref{17cf,,strptime()}.

@item Module @ref{15,,calendar}

Γενικές συναρτήσεις σχετικές με το ημερολόγιο. Η @ref{2b5b,,timegm()} είναι η αντίστροφη της @ref{1569,,gmtime()} από αυτή τη μονάδα.
@end table


@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node logging — Logging facility for Python,logging config — Logging configuration,time — Πρόσβαση και μετατροπές χρόνου,Generic Operating System Services
@anchor{library/logging doc}@anchor{33a7}@anchor{library/logging logging-logging-facility-for-python}@anchor{33a8}@anchor{library/logging module-logging}@anchor{8a}@anchor{library/logging translation-repo}@anchor{33a9}
@subsection @code{logging} — Logging facility for Python


@geindex module; logging

`Source code:' Lib/logging/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/logging/__init__.py}

@geindex Errors;logging

@subsubheading Important



This page contains the API reference information. For tutorial
information and discussion of more advanced topics, see


@itemize *

@item 
@ref{159e,,Basic Tutorial}

@item 
@ref{159f,,Advanced Tutorial}

@item 
@ref{15a0,,Logging Cookbook}
@end itemize


__________________________________________________________________


This module defines functions and classes which implement a flexible event
logging system for applications and libraries.

The key benefit of having the logging API provided by a standard library module
is that all Python modules can participate in logging, so your application log
can include your own messages integrated with messages from third-party
modules.

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

If you run `myapp.py', you should see this in `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{dc2,,basicConfig()} provides a quick way to configure
the root logger that handles many use cases.

The module provides a lot of functionality and flexibility.  If you are
unfamiliar with logging, the best way to get to grips with it is to view the
tutorials (`see the links above and on the right').

The basic classes defined by the module, together with their attributes and
methods, are listed in the sections below.


@itemize *

@item 
Loggers expose the interface that application code directly uses.

@item 
Handlers send the log records (created by loggers) to the appropriate
destination.

@item 
Filters provide a finer grained facility for determining which log records
to output.

@item 
Formatters specify the layout of log records in the final output.
@end itemize

@menu
* Logger Objects:: 
* Logging Levels:: 
* Handler Objects:: 
* Formatter Objects:: 
* Filter Objects:: 
* LogRecord Objects:: 
* LogRecord attributes:: 
* LoggerAdapter Objects:: 
* Thread Safety:: 
* Module-Level Functions:: 
* Module-Level Attributes:: 
* Integration with the warnings module:: 

@end menu

@node Logger Objects,Logging Levels,,logging — Logging facility for Python
@anchor{library/logging logger}@anchor{33aa}@anchor{library/logging logger-objects}@anchor{33ab}
@subsubsection Logger Objects


Loggers have the following attributes and methods.  Note that Loggers should
`NEVER' be instantiated directly, but always through the module-level function
@code{logging.getLogger(name)}.  Multiple calls to @ref{d2a,,getLogger()} with the same
name will always return a reference to the same Logger object.

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 (κλάση σε logging)
@anchor{library/logging logging Logger}@anchor{f0c}
@deffn {Κλάση} logging.Logger

@geindex name (ιδιότητα της logging.Logger)
@anchor{library/logging logging Logger name}@anchor{33ac}
@deffn {Ιδιότητα} name

This is the logger’s name, and is the value that was passed to @ref{d2a,,getLogger()}
to obtain the logger.

@cartouche
@quotation Σημείωση 
This attribute should be treated as read-only.
@end quotation
@end cartouche
@end deffn

@geindex level (ιδιότητα της logging.Logger)
@anchor{library/logging logging Logger level}@anchor{33ad}
@deffn {Ιδιότητα} level

The threshold of this logger, as set by the @ref{1835,,setLevel()} method.

@cartouche
@quotation Σημείωση 
Do not set this attribute directly - always use @ref{1835,,setLevel()},
which has checks for the level passed to it.
@end quotation
@end cartouche
@end deffn

@geindex parent (ιδιότητα της logging.Logger)
@anchor{library/logging logging Logger parent}@anchor{33ae}
@deffn {Ιδιότητα} 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 Σημείωση 
This value should be treated as read-only.
@end quotation
@end cartouche
@end deffn

@geindex propagate (ιδιότητα της logging.Logger)
@anchor{library/logging logging Logger propagate}@anchor{1837}
@deffn {Ιδιότητα} propagate

If this attribute evaluates to true, events logged to this logger will be
passed to the handlers of higher level (ancestor) loggers, in addition to
any handlers attached to this logger. Messages are passed directly to the
ancestor loggers” handlers - neither the level nor filters of the ancestor
loggers in question are considered.

If this evaluates to false, logging messages are not passed to the handlers
of ancestor loggers.

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.

The constructor sets this attribute to @code{True}.

@cartouche
@quotation Σημείωση 
If you attach a handler to a logger `and' one or more of its
ancestors, it may emit the same record multiple times. In general, you
should not need to attach a handler to more than one logger - if you just
attach it to the appropriate logger which is highest in the logger
hierarchy, then it will see all events logged by all descendant loggers,
provided that their propagate setting is left set to @code{True}. A common
scenario is to attach handlers only to the root logger, and to let
propagation take care of the rest.
@end quotation
@end cartouche
@end deffn

@geindex handlers (ιδιότητα της logging.Logger)
@anchor{library/logging logging Logger handlers}@anchor{33af}
@deffn {Ιδιότητα} handlers

The list of handlers directly attached to this logger instance.

@cartouche
@quotation Σημείωση 
This attribute should be treated as read-only; it is normally changed via
the @ref{33b0,,addHandler()} and @ref{33b1,,removeHandler()} methods, which use locks to ensure
thread-safe operation.
@end quotation
@end cartouche
@end deffn

@geindex disabled (ιδιότητα της logging.Logger)
@anchor{library/logging logging Logger disabled}@anchor{33b2}
@deffn {Ιδιότητα} 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 Σημείωση 
This attribute should be treated as read-only.
@end quotation
@end cartouche
@end deffn

@geindex setLevel() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger setLevel}@anchor{1835}
@deffn {Μέθοδος} setLevel (level)

Sets the threshold for this logger to `level'. Logging messages which are less
severe than `level' will be ignored; logging messages which have severity `level'
or higher will be emitted by whichever handler or handlers service this logger,
unless a handler’s level has been set to a higher severity level than `level'.

When a logger is created, the level is set to @ref{33b3,,NOTSET} (which causes
all messages to be processed when the logger is the root logger, or delegation
to the parent when the logger is a non-root logger). Note that the root logger
is created with level @ref{22cf,,WARNING}.

The term “delegation to the parent” means that if a logger has a level of
NOTSET, its chain of ancestor loggers is traversed until either an ancestor with
a level other than NOTSET is found, or the root is reached.

If an ancestor is found with a level other than NOTSET, then that ancestor’s
level is treated as the effective level of the logger where the ancestor search
began, and is used to determine how a logging event is handled.

If the root is reached, and it has a level of NOTSET, then all messages will be
processed. Otherwise, the root’s level will be used as the effective level.

See @ref{a4a,,Logging Levels} for a list of levels.


Άλλαξε στην έκδοση 3.2: The `level' parameter now accepts a string representation of the
level such as “INFO” as an alternative to the integer constants
such as @ref{22ce,,INFO}. Note, however, that levels are internally stored
as integers, and methods such as e.g. @ref{33b4,,getEffectiveLevel()} and
@ref{169b,,isEnabledFor()} will return/expect to be passed integers.

@end deffn

@geindex isEnabledFor() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger isEnabledFor}@anchor{169b}
@deffn {Μέθοδος} isEnabledFor (level)

Indicates if a message of severity `level' would be processed by this logger.
This method checks first the module-level level set by
@code{logging.disable(level)} and then the logger’s effective level as determined
by @ref{33b4,,getEffectiveLevel()}.
@end deffn

@geindex getEffectiveLevel() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger getEffectiveLevel}@anchor{33b4}
@deffn {Μέθοδος} getEffectiveLevel ()

Indicates the effective level for this logger. If a value other than
@ref{33b3,,NOTSET} has been set using @ref{1835,,setLevel()}, it is returned. Otherwise,
the hierarchy is traversed towards the root until a value other than
@code{NOTSET} is found, and that value is returned. The value returned is
an integer, typically one of @ref{22cd,,logging.DEBUG}, @ref{22ce,,logging.INFO}
etc.
@end deffn

@geindex getChild() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger getChild}@anchor{1699}
@deffn {Μέθοδος} getChild (suffix)

Returns a logger which is a descendant to this logger, as determined by the suffix.
Thus, @code{logging.getLogger('abc').getChild('def.ghi')} would return the same
logger as would be returned by @code{logging.getLogger('abc.def.ghi')}. This is a
convenience method, useful when the parent logger is named using e.g. @code{__name__}
rather than a literal string.


Added in version 3.2.

@end deffn

@geindex getChildren() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger getChildren}@anchor{1d50}
@deffn {Μέθοδος} 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}.


Added in version 3.12.

@end deffn

@geindex debug() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger debug}@anchor{11de}
@deffn {Μέθοδος} debug (msg, *args, **kwargs)

Logs a message with level @ref{22cd,,DEBUG} on this logger. The `msg' is the
message format string, and the `args' are the arguments which are merged into
`msg' using the string formatting operator. (Note that this means that you can
use keywords in the format string, together with a single dictionary argument.)
No % formatting operation is performed on `msg' when no `args' are supplied.

There are four keyword arguments in `kwargs' which are inspected:
`exc_info', `stack_info', `stacklevel' and `extra'.

If `exc_info' does not evaluate as false, it causes exception information to be
added to the logging message. If an exception tuple (in the format returned by
@ref{a7a,,sys.exc_info()}) or an exception instance is provided, it is used;
otherwise, @code{sys.exc_info()} is called to get the exception information.

The second optional keyword argument is `stack_info', which defaults to
@code{False}. If true, stack information is added to the logging
message, including the actual logging call. Note that this is not the same
stack information as that displayed through specifying `exc_info': The
former is stack frames from the bottom of the stack up to the logging call
in the current thread, whereas the latter is information about stack frames
which have been unwound, following an exception, while searching for
exception handlers.

You can specify `stack_info' independently of `exc_info', e.g. to just show
how you got to a certain point in your code, even when no exceptions were
raised. The stack frames are printed following a header line which says:

@example
Stack (most recent call last):
@end example

This mimics the @code{Traceback (most recent call last):} which is used when
displaying exception frames.

The third optional keyword argument is `stacklevel', which defaults to @code{1}.
If greater than 1, the corresponding number of stack frames are skipped
when computing the line number and function name set in the @ref{138f,,LogRecord}
created for the logging event. This can be used in logging helpers so that
the function name, filename and line number recorded are not the information
for the helper function/method, but rather its caller. The name of this
parameter mirrors the equivalent one in the @ref{11b,,warnings} module.

The fourth keyword argument is `extra' which can be used to pass a
dictionary which is used to populate the @ref{1bf,,__dict__} of the
@ref{138f,,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

would print something like

@example
2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset
@end example

The keys in the dictionary passed in `extra' should not clash with the keys used
by the logging system. (See the section on @ref{33b5,,LogRecord attributes} for more
information on which keys are used by the logging system.)

If you choose to use these attributes in logged messages, you need to exercise
some care. In the above example, for instance, the @ref{1839,,Formatter} has been
set up with a format string which expects “clientip” and “user” in the attribute
dictionary of the @ref{138f,,LogRecord}. If these are missing, the message will
not be logged because a string formatting exception will occur. So in this case,
you always need to pass the `extra' dictionary with these keys.

While this might be annoying, this feature is intended for use in specialized
circumstances, such as multi-threaded servers where the same code executes in
many contexts, and interesting conditions which arise are dependent on this
context (such as remote client IP address and authenticated user name, in the
above example). In such circumstances, it is likely that specialized
@ref{1839,,Formatter}s would be used with particular @ref{1838,,Handler}s.

If no handler is attached to this logger (or any of its ancestors,
taking into account the relevant @ref{1837,,Logger.propagate} attributes),
the message will be sent to the handler set on @ref{15a3,,lastResort}.


Άλλαξε στην έκδοση 3.2: The `stack_info' parameter was added.



Άλλαξε στην έκδοση 3.5: The `exc_info' parameter can now accept exception instances.



Άλλαξε στην έκδοση 3.8: The `stacklevel' parameter was added.

@end deffn

@geindex info() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger info}@anchor{33b6}
@deffn {Μέθοδος} info (msg, *args, **kwargs)

Logs a message with level @ref{22ce,,INFO} on this logger. The arguments are
interpreted as for @ref{33b7,,debug()}.
@end deffn

@geindex warning() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger warning}@anchor{1c7a}
@deffn {Μέθοδος} warning (msg, *args, **kwargs)

Logs a message with level @ref{22cf,,WARNING} on this logger. The arguments are
interpreted as for @ref{33b7,,debug()}.

@cartouche
@quotation Σημείωση 
There is an obsolete method @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() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger error}@anchor{33b8}
@deffn {Μέθοδος} error (msg, *args, **kwargs)

Logs a message with level @ref{22d0,,ERROR} on this logger. The arguments are
interpreted as for @ref{33b7,,debug()}.
@end deffn

@geindex critical() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger critical}@anchor{11dd}
@deffn {Μέθοδος} critical (msg, *args, **kwargs)

Logs a message with level @ref{22d1,,CRITICAL} on this logger. The arguments are
interpreted as for @ref{33b7,,debug()}.
@end deffn

@geindex log() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger log}@anchor{11db}
@deffn {Μέθοδος} log (level, msg, *args, **kwargs)

Logs a message with integer level `level' on this logger. The other arguments are
interpreted as for @ref{33b7,,debug()}.
@end deffn

@geindex exception() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger exception}@anchor{11dc}
@deffn {Μέθοδος} exception (msg, *args, **kwargs)

Logs a message with level @ref{22d0,,ERROR} on this logger. The arguments are
interpreted as for @ref{33b7,,debug()}. Exception info is added to the logging
message. This method should only be called from an exception handler.
@end deffn

@geindex addFilter() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger addFilter}@anchor{33b9}
@deffn {Μέθοδος} addFilter (filter)

Adds the specified filter `filter' to this logger.
@end deffn

@geindex removeFilter() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger removeFilter}@anchor{33ba}
@deffn {Μέθοδος} removeFilter (filter)

Removes the specified filter `filter' from this logger.
@end deffn

@geindex filter() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger filter}@anchor{33bb}
@deffn {Μέθοδος} filter (record)

Apply this logger’s filters to the record and return @code{True} if the
record is to be processed. The filters are consulted in turn, until one of
them returns a false value. If none of them return a false value, the record
will be processed (passed to handlers). If one returns a false value, no
further processing of the record occurs.
@end deffn

@geindex addHandler() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger addHandler}@anchor{33b0}
@deffn {Μέθοδος} addHandler (hdlr)

Adds the specified handler `hdlr' to this logger.
@end deffn

@geindex removeHandler() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger removeHandler}@anchor{33b1}
@deffn {Μέθοδος} removeHandler (hdlr)

Removes the specified handler `hdlr' from this logger.
@end deffn

@geindex findCaller() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger findCaller}@anchor{33bc}
@deffn {Μέθοδος} findCaller (stack_info=False, stacklevel=1)

Finds the caller’s source filename and line number. Returns the filename, line
number, function name and stack information as a 4-element tuple. The stack
information is returned as @code{None} unless `stack_info' is @code{True}.

The `stacklevel' parameter is passed from code calling the @ref{33b7,,debug()}
and other APIs. If greater than 1, the excess is used to skip stack frames
before determining the values to be returned. This will generally be useful
when calling logging APIs from helper/wrapper code, so that the information
in the event log refers not to the helper/wrapper code, but to the code that
calls it.
@end deffn

@geindex handle() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger handle}@anchor{33bd}
@deffn {Μέθοδος} handle (record)

Handles a record by passing it to all handlers associated with this logger and
its ancestors (until a false value of `propagate' is found). This method is used
for unpickled records received from a socket, as well as those created locally.
Logger-level filtering is applied using @ref{33bb,,filter()}.
@end deffn

@geindex makeRecord() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger makeRecord}@anchor{33be}
@deffn {Μέθοδος} makeRecord (name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

This is a factory method which can be overridden in subclasses to create
specialized @ref{138f,,LogRecord} instances.
@end deffn

@geindex hasHandlers() (μέθοδος της logging.Logger)
@anchor{library/logging logging Logger hasHandlers}@anchor{33bf}
@deffn {Μέθοδος} hasHandlers ()

Checks to see if this logger has any handlers configured. This is done by
looking for handlers in this logger and its parents in the logger hierarchy.
Returns @code{True} if a handler was found, else @code{False}. The method stops searching
up the hierarchy whenever a logger with the “propagate” attribute set to
false is found - that will be the last logger which is checked for the
existence of handlers.


Added in version 3.2.

@end deffn


Άλλαξε στην έκδοση 3.7: Loggers can now be pickled and unpickled.

@end deffn

@node Logging Levels,Handler Objects,Logger Objects,logging — Logging facility for Python
@anchor{library/logging levels}@anchor{a4a}@anchor{library/logging logging-levels}@anchor{33c0}
@subsubsection Logging Levels


The numeric values of logging levels are given in the following table. These are
primarily of interest if you want to define your own levels, and need them to
have specific values relative to the predefined levels. If you define a level
with the same numeric value, it overwrites the predefined value; the predefined
name is lost.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Level

@tab

Numeric value

@tab

What it means / When to use it

@item

@geindex NOTSET (στη μονάδα logging)
@anchor{library/logging logging NOTSET}@anchor{33b3}
@deffn {Δεδομένα} 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 (στη μονάδα logging)
@anchor{library/logging logging DEBUG}@anchor{22cd}
@deffn {Δεδομένα} logging.DEBUG
@end deffn

@tab

10

@tab

Detailed information, typically only
of interest to a developer trying to
diagnose a problem.

@item

@geindex INFO (στη μονάδα logging)
@anchor{library/logging logging INFO}@anchor{22ce}
@deffn {Δεδομένα} logging.INFO
@end deffn

@tab

20

@tab

Confirmation that things are working
as expected.

@item

@geindex WARNING (στη μονάδα logging)
@anchor{library/logging logging WARNING}@anchor{22cf}
@deffn {Δεδομένα} 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 (στη μονάδα logging)
@anchor{library/logging logging ERROR}@anchor{22d0}
@deffn {Δεδομένα} logging.ERROR
@end deffn

@tab

40

@tab

Due to a more serious problem, the
software has not been able to
perform some function.

@item

@geindex CRITICAL (στη μονάδα logging)
@anchor{library/logging logging CRITICAL}@anchor{22d1}
@deffn {Δεδομένα} logging.CRITICAL
@end deffn

@tab

50

@tab

A serious error, indicating that the
program itself may be unable to
continue running.

@end multitable


@node Handler Objects,Formatter Objects,Logging Levels,logging — Logging facility for Python
@anchor{library/logging handler}@anchor{33c1}@anchor{library/logging handler-objects}@anchor{33c2}
@subsubsection Handler Objects


Handlers have the following attributes and methods. Note that @ref{1838,,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{33c3,,Handler.__init__()}.

@geindex Handler (κλάση σε logging)
@anchor{library/logging logging Handler}@anchor{1838}
@deffn {Κλάση} logging.Handler

@geindex __init__() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler __init__}@anchor{33c3}
@deffn {Μέθοδος} __init__ (level=NOTSET)

Initializes the @code{Handler} instance by setting its level, setting the list
of filters to the empty list and creating a lock (using @ref{33c4,,createLock()}) for
serializing access to an I/O mechanism.
@end deffn

@geindex createLock() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler createLock}@anchor{33c4}
@deffn {Μέθοδος} createLock ()

Initializes a thread lock which can be used to serialize access to underlying
I/O functionality which may not be threadsafe.
@end deffn

@geindex acquire() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler acquire}@anchor{33c5}
@deffn {Μέθοδος} acquire ()

Acquires the thread lock created with @ref{33c4,,createLock()}.
@end deffn

@geindex release() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler release}@anchor{33c6}
@deffn {Μέθοδος} release ()

Releases the thread lock acquired with @ref{33c5,,acquire()}.
@end deffn

@geindex setLevel() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler setLevel}@anchor{33c7}
@deffn {Μέθοδος} setLevel (level)

Sets the threshold for this handler to `level'. Logging messages which are
less severe than `level' will be ignored. When a handler is created, the
level is set to @ref{33b3,,NOTSET} (which causes all messages to be
processed).

See @ref{a4a,,Logging Levels} for a list of levels.


Άλλαξε στην έκδοση 3.2: The `level' parameter now accepts a string representation of the
level such as “INFO” as an alternative to the integer constants
such as @ref{22ce,,INFO}.

@end deffn

@geindex setFormatter() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler setFormatter}@anchor{33c8}
@deffn {Μέθοδος} setFormatter (fmt)

Sets the formatter for this handler to `fmt'.
The `fmt' argument must be a @ref{1839,,Formatter} instance or @code{None}.
@end deffn

@geindex addFilter() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler addFilter}@anchor{33c9}
@deffn {Μέθοδος} addFilter (filter)

Adds the specified filter `filter' to this handler.
@end deffn

@geindex removeFilter() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler removeFilter}@anchor{33ca}
@deffn {Μέθοδος} removeFilter (filter)

Removes the specified filter `filter' from this handler.
@end deffn

@geindex filter() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler filter}@anchor{33cb}
@deffn {Μέθοδος} filter (record)

Apply this handler’s filters to the record and return @code{True} if the
record is to be processed. The filters are consulted in turn, until one of
them returns a false value. If none of them return a false value, the record
will be emitted. If one returns a false value, the handler will not emit the
record.
@end deffn

@geindex flush() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler flush}@anchor{33cc}
@deffn {Μέθοδος} flush ()

Ensure all logging output has been flushed. This version does nothing and is
intended to be implemented by subclasses.
@end deffn

@geindex close() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler close}@anchor{33cd}
@deffn {Μέθοδος} close ()

Tidy up any resources used by the handler. This version does no output
but removes the handler from an internal map of handlers, which is used
for handler lookup by name.

Subclasses should ensure that this gets called from overridden @code{close()}
methods.
@end deffn

@geindex handle() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler handle}@anchor{33ce}
@deffn {Μέθοδος} handle (record)

Conditionally emits the specified logging record, depending on filters which may
have been added to the handler. Wraps the actual emission of the record with
acquisition/release of the I/O thread lock.
@end deffn

@geindex handleError() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler handleError}@anchor{33cf}
@deffn {Μέθοδος} handleError (record)

This method should be called from handlers when an exception is encountered
during an @ref{33d0,,emit()} call. If the module-level attribute
@ref{15a2,,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 @code{raiseExceptions} is @code{True}, as that is
more useful during development).
@end deffn

@geindex format() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler format}@anchor{33d1}
@deffn {Μέθοδος} format (record)

Do formatting for a record - if a formatter is set, use it. Otherwise, use the
default formatter for the module.
@end deffn

@geindex emit() (μέθοδος της logging.Handler)
@anchor{library/logging logging Handler emit}@anchor{33d0}
@deffn {Μέθοδος} emit (record)

Do whatever it takes to actually log the specified logging record. This version
is intended to be implemented by subclasses and so raises a
@ref{59a,,NotImplementedError}.

@cartouche
@quotation Προειδοποίηση 
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

For a list of handlers included as standard, see @ref{8c,,logging.handlers}.

@node Formatter Objects,Filter Objects,Handler Objects,logging — Logging facility for Python
@anchor{library/logging formatter-objects}@anchor{33d2}@anchor{library/logging id1}@anchor{33d3}
@subsubsection Formatter Objects


@geindex Formatter (κλάση σε logging)
@anchor{library/logging logging Formatter}@anchor{1839}
@deffn {Κλάση} logging.Formatter (fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Responsible for converting a @ref{138f,,LogRecord} to an output string
to be interpreted by a human or external system.

@*Παράμετροι: 

@itemize *

@item 
@code{fmt} (@ref{1df,,str}) – A format string in the given `style' for
the logged output as a whole.
The possible mapping keys are drawn from the @ref{138f,,LogRecord} object’s
@ref{33b5,,LogRecord attributes}.
If not specified, @code{'%(message)s'} is used,
which is just the logged message.

@item 
@code{datefmt} (@ref{1df,,str}) – A format string for the date/time portion of the logged output.
If not specified, the default described in @ref{33d4,,formatTime()} is used.

@item 
@code{style} (@ref{1df,,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{ab9,,printf-style String Formatting} (@code{%}), @ref{a12,,str.format()} (@code{@{})
or @ref{a77,,string.Template} (@code{$}). This only applies to
`fmt' (e.g. @code{'%(message)s'} versus @code{'@{message@}'}),
not to the actual log messages passed to the logging methods.
However, there are @ref{33d5,,other ways}
to use @code{@{}- and @code{$}-formatting for log messages.

@item 
@code{validate} (@ref{5ef,,bool}) – If @code{True} (the default), incorrect or mismatched
`fmt' and `style' will raise a @ref{277,,ValueError}; for example,
@code{logging.Formatter('%(asctime)s - %(message)s', style='@{')}.

@item 
@code{defaults} (@ref{188,,dict}@code{[}@ref{1df,,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



Άλλαξε στην έκδοση 3.2: Added the `style' parameter.



Άλλαξε στην έκδοση 3.8: Added the `validate' parameter.



Άλλαξε στην έκδοση 3.10: Added the `defaults' parameter.


@geindex format() (μέθοδος της logging.Formatter)
@anchor{library/logging logging Formatter format}@anchor{33d6}
@deffn {Μέθοδος} 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{33d4,,formatTime()} is called
to format the event time. If there is exception information, it is
formatted using @ref{33d7,,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 @code{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{33d8,,formatStack()} to transform it if necessary.
@end deffn

@geindex formatTime() (μέθοδος της logging.Formatter)
@anchor{library/logging logging Formatter formatTime}@anchor{33d4}
@deffn {Μέθοδος} formatTime (record, datefmt=None)

This method should be called from @ref{439,,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{1592,,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
@code{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{189b,,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 @code{time.localtime()} or
@ref{1569,,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.


Άλλαξε στην έκδοση 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).



Άλλαξε στην έκδοση 3.9: The @code{default_msec_format} can be @code{None}.

@end deffn

@geindex formatException() (μέθοδος της logging.Formatter)
@anchor{library/logging logging Formatter formatException}@anchor{33d7}
@deffn {Μέθοδος} formatException (exc_info)

Formats the specified exception information (a standard exception tuple as
returned by @ref{a7a,,sys.exc_info()}) as a string. This default implementation
just uses @ref{c27,,traceback.print_exception()}. The resulting string is
returned.
@end deffn

@geindex formatStack() (μέθοδος της logging.Formatter)
@anchor{library/logging logging Formatter formatStack}@anchor{33d8}
@deffn {Μέθοδος} formatStack (stack_info)

Formats the specified stack information (a string as returned by
@ref{1237,,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 (κλάση σε logging)
@anchor{library/logging logging BufferingFormatter}@anchor{33d9}
@deffn {Κλάση} 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{1839,,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() (μέθοδος της logging.BufferingFormatter)
@anchor{library/logging logging BufferingFormatter formatHeader}@anchor{33da}
@deffn {Μέθοδος} 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() (μέθοδος της logging.BufferingFormatter)
@anchor{library/logging logging BufferingFormatter formatFooter}@anchor{33db}
@deffn {Μέθοδος} 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() (μέθοδος της logging.BufferingFormatter)
@anchor{library/logging logging BufferingFormatter format}@anchor{33dc}
@deffn {Μέθοδος} 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 Filter Objects,LogRecord Objects,Formatter Objects,logging — Logging facility for Python
@anchor{library/logging filter}@anchor{33dd}@anchor{library/logging filter-objects}@anchor{33de}
@subsubsection Filter Objects


@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 (κλάση σε logging)
@anchor{library/logging logging Filter}@anchor{15a4}
@deffn {Κλάση} logging.Filter (name='@w{'})

Returns an instance of the @code{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() (μέθοδος της logging.Filter)
@anchor{library/logging logging Filter filter}@anchor{33df}
@deffn {Μέθοδος} 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{33b7,,debug()}, @ref{33e0,,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.


Άλλαξε στην έκδοση 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{33df,,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
@code{filter()}.



Άλλαξε στην έκδοση 3.12: You can now return a @ref{138f,,LogRecord} instance from filters to replace
the log record rather than modifying it in place. This allows filters attached to
a @ref{1838,,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{138f,,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{33e1,,Using Filters to impart contextual information}).

@node LogRecord Objects,LogRecord attributes,Filter Objects,logging — Logging facility for Python
@anchor{library/logging log-record}@anchor{33e2}@anchor{library/logging logrecord-objects}@anchor{33e3}
@subsubsection LogRecord Objects


@ref{138f,,LogRecord} instances are created automatically by the @ref{f0c,,Logger}
every time something is logged, and can be created manually via
@ref{33e4,,makeLogRecord()} (for example, from a pickled event received over the
wire).

@geindex LogRecord (κλάση σε logging)
@anchor{library/logging logging LogRecord}@anchor{138f}
@deffn {Κλάση} 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.

@*Παράμετροι: 

@itemize *

@item 
@code{name} (@ref{1df,,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{326,,int}) – The @ref{a4a,,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{1df,,str}) – The full string path of the source file
where the logging call was made.

@item 
@code{lineno} (@ref{326,,int}) – The line number in the source file
where the logging call was made.

@item 
@code{msg} (@ref{a9a,,Any}) – The event description message,
which can be a %-format string with placeholders for variable data,
or an arbitrary object (see @ref{33e5,,Using arbitrary objects as messages}).

@item 
@code{args} (@ref{1ce,,tuple}@code{ | }@ref{188,,dict}@code{[}@ref{1df,,str}@code{, }@ref{a9a,,Any}@code{]}) – Variable data to merge into the `msg' argument
to obtain the event description.

@item 
@code{exc_info} (@ref{1ce,,tuple}@code{[}@ref{186,,type}@code{[}@ref{9b9,,BaseException}@code{]}@code{, }@code{BaseException}@code{, }@ref{eb8,,types.TracebackType}@code{] }@code{| }@code{None}) – An exception tuple with the current exception information,
as returned by @ref{a7a,,sys.exc_info()},
or @code{None} if no exception information is available.

@item 
@code{func} (@ref{1df,,str}@code{ | }@code{None}) – The name of the function or method
from which the logging call was invoked.

@item 
@code{sinfo} (@ref{1df,,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() (μέθοδος της logging.LogRecord)
@anchor{library/logging logging LogRecord getMessage}@anchor{33e6}
@deffn {Μέθοδος} getMessage ()

Returns the message for this @code{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{1df,,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


Άλλαξε στην έκδοση 3.2: The creation of a @code{LogRecord} has been made more configurable by
providing a factory which is used to create the record. The factory can be
set using @ref{33e7,,getLogRecordFactory()} and @ref{33e8,,setLogRecordFactory()}
(see this for the factory’s signature).


This functionality can be used to inject your own values into a
@code{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,LogRecord Objects,logging — Logging facility for Python
@anchor{library/logging id2}@anchor{33e9}@anchor{library/logging logrecord-attributes}@anchor{33b5}
@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{a12,,str.format()}), you can use
@code{@{attrname@}} as the placeholder in the format string. If you are using
$-formatting (@ref{a77,,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{a12,,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{138f,,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{138f,,LogRecord} was created
(as returned by @ref{eae,,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

exc_text

@tab

You shouldn’t need to
format this yourself.

@tab

Exception information formatted as a string.
This is set when @ref{33d6,,Formatter.format()} is
invoked, or @code{None} if no exception has
occurred.

@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{22cd,,DEBUG}, @ref{22ce,,INFO},
@ref{22cf,,WARNING}, @ref{22d0,,ERROR},
@ref{22d1,,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{33d6,,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{138f,,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{33e5,,Using arbitrary objects as messages}).

@item

name

@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{460,,asyncio.Task} name (if available).

@end multitable



Άλλαξε στην έκδοση 3.1: `processName' was added.



Άλλαξε στην έκδοση 3.12: `taskName' was added.


@node LoggerAdapter Objects,Thread Safety,LogRecord attributes,logging — Logging facility for Python
@anchor{library/logging logger-adapter}@anchor{33ea}@anchor{library/logging loggeradapter-objects}@anchor{33eb}
@subsubsection LoggerAdapter Objects


@ref{169a,,LoggerAdapter} instances are used to conveniently pass contextual
information into logging calls. For a usage example, see the section on
@ref{33ec,,adding contextual information to your logging output}.

@geindex LoggerAdapter (κλάση σε logging)
@anchor{library/logging logging LoggerAdapter}@anchor{169a}
@deffn {Κλάση} logging.LoggerAdapter (logger, extra=None, merge_extra=False)

Returns an instance of @code{LoggerAdapter} initialized with an
underlying @ref{f0c,,Logger} instance, an optional dict-like object (`extra'),
and an optional boolean (`merge_extra') indicating whether or not
the `extra' argument of individual log calls should be merged with
the @code{LoggerAdapter} extra.
The default behavior is to ignore the `extra' argument of individual log
calls and only use the one of the @code{LoggerAdapter} instance

@geindex process() (μέθοδος της logging.LoggerAdapter)
@anchor{library/logging logging LoggerAdapter process}@anchor{33ed}
@deffn {Μέθοδος} 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 (ιδιότητα της logging.LoggerAdapter)
@anchor{library/logging logging LoggerAdapter manager}@anchor{33ee}
@deffn {Ιδιότητα} manager

Delegates to the underlying @code{manager} on `logger'.
@end deffn

@geindex _log (ιδιότητα της logging.LoggerAdapter)
@anchor{library/logging logging LoggerAdapter _log}@anchor{33ef}
@deffn {Ιδιότητα} _log

Delegates to the underlying @code{_log()} method on `logger'.
@end deffn

In addition to the above, @code{LoggerAdapter} supports the following
methods of @ref{f0c,,Logger}: @ref{11de,,debug()}, @ref{33b6,,info()},
@ref{1c7a,,warning()}, @ref{33b8,,error()}, @ref{11dc,,exception()},
@ref{11dd,,critical()}, @ref{11db,,log()}, @ref{169b,,isEnabledFor()},
@ref{33b4,,getEffectiveLevel()}, @ref{1835,,setLevel()} and
@ref{33bf,,hasHandlers()}. These methods have the same signatures as their
counterparts in @code{Logger}, so you can use the two types of instances
interchangeably.


Άλλαξε στην έκδοση 3.2: The @ref{169b,,isEnabledFor()}, @ref{33b4,,getEffectiveLevel()},
@ref{1835,,setLevel()} and @ref{33bf,,hasHandlers()} methods were added
to @code{LoggerAdapter}.  These methods delegate to the underlying logger.



Άλλαξε στην έκδοση 3.6: Attribute @code{manager} and method @code{_log()} were added, which
delegate to the underlying logger and allow adapters to be nested.



Άλλαξε στην έκδοση 3.10: The `extra' argument is now optional.



Άλλαξε στην έκδοση 3.13: The `merge_extra' parameter was added.

@end deffn

@node Thread Safety,Module-Level Functions,LoggerAdapter Objects,logging — Logging facility for Python
@anchor{library/logging thread-safety}@anchor{33f0}
@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 through 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{ce,,signal}
module, you may not be able to use logging from within such handlers. This is
because lock implementations in the @ref{f6,,threading} module are not always
re-entrant, and so cannot be invoked from such signal handlers.

@node Module-Level Functions,Module-Level Attributes,Thread Safety,logging — Logging facility for Python
@anchor{library/logging module-level-functions}@anchor{33f1}
@subsubsection Module-Level Functions


In addition to the classes described above, there are a number of module-level
functions.

@geindex getLogger() (στη μονάδα logging)
@anchor{library/logging logging getLogger}@anchor{d2a}
@deffn {Συνάρτηση} 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{33aa,,Logger Objects}.

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() (στη μονάδα logging)
@anchor{library/logging logging getLoggerClass}@anchor{33f2}
@deffn {Συνάρτηση} logging.getLoggerClass ()

Return either the standard @ref{f0c,,Logger} class, or the last class passed to
@ref{33f3,,setLoggerClass()}. This function may be called from within a new class
definition, to ensure that installing a customized @code{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() (στη μονάδα logging)
@anchor{library/logging logging getLogRecordFactory}@anchor{33e7}
@deffn {Συνάρτηση} logging.getLogRecordFactory ()

Return a callable which is used to create a @ref{138f,,LogRecord}.


Added in version 3.2: This function has been provided, along with @ref{33e8,,setLogRecordFactory()},
to allow developers more control over how the @ref{138f,,LogRecord}
representing a logging event is constructed.


See @ref{33e8,,setLogRecordFactory()} for more information about the how the
factory is called.
@end deffn

@geindex debug() (στη μονάδα logging)
@anchor{library/logging logging debug}@anchor{33b7}
@deffn {Συνάρτηση} logging.debug (msg, *args, **kwargs)

This is a convenience function that calls @ref{11de,,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{dc2,,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{11de,,Logger.debug()} (or other level-specific methods) on it, as
described at the beginning of this documentation.
@end deffn

@geindex info() (στη μονάδα logging)
@anchor{library/logging logging info}@anchor{33e0}
@deffn {Συνάρτηση} logging.info (msg, *args, **kwargs)

Logs a message with level @ref{22ce,,INFO} on the root logger. The arguments and behavior
are otherwise the same as for @ref{33b7,,debug()}.
@end deffn

@geindex warning() (στη μονάδα logging)
@anchor{library/logging logging warning}@anchor{331}
@deffn {Συνάρτηση} logging.warning (msg, *args, **kwargs)

Logs a message with level @ref{22cf,,WARNING} on the root logger. The arguments and behavior
are otherwise the same as for @ref{33b7,,debug()}.

@cartouche
@quotation Σημείωση 
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() (στη μονάδα logging)
@anchor{library/logging logging error}@anchor{33f4}
@deffn {Συνάρτηση} logging.error (msg, *args, **kwargs)

Logs a message with level @ref{22d0,,ERROR} on the root logger. The arguments and behavior
are otherwise the same as for @ref{33b7,,debug()}.
@end deffn

@geindex critical() (στη μονάδα logging)
@anchor{library/logging logging critical}@anchor{33f5}
@deffn {Συνάρτηση} logging.critical (msg, *args, **kwargs)

Logs a message with level @ref{22d1,,CRITICAL} on the root logger. The arguments and behavior
are otherwise the same as for @ref{33b7,,debug()}.
@end deffn

@geindex exception() (στη μονάδα logging)
@anchor{library/logging logging exception}@anchor{1836}
@deffn {Συνάρτηση} logging.exception (msg, *args, **kwargs)

Logs a message with level @ref{22d0,,ERROR} on the root logger. The arguments and behavior
are otherwise the same as for @ref{33b7,,debug()}. Exception info is added to the logging
message. This function should only be called from an exception handler.
@end deffn

@geindex log() (στη μονάδα logging)
@anchor{library/logging logging log}@anchor{33f6}
@deffn {Συνάρτηση} 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{33b7,,debug()}.
@end deffn

@geindex disable() (στη μονάδα logging)
@anchor{library/logging logging disable}@anchor{33f7}
@deffn {Συνάρτηση} 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.


Άλλαξε στην έκδοση 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() (στη μονάδα logging)
@anchor{library/logging logging addLevelName}@anchor{33f8}
@deffn {Συνάρτηση} 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{1839,,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 Σημείωση 
If you are thinking of defining your own levels, please see the
section on @ref{33f9,,Custom Levels}.
@end quotation
@end cartouche
@end deffn

@geindex getLevelNamesMapping() (στη μονάδα logging)
@anchor{library/logging logging getLevelNamesMapping}@anchor{a49}
@deffn {Συνάρτηση} logging.getLevelNamesMapping ()

Returns a mapping from level names to their corresponding logging levels. For example, the
string «CRITICAL» maps to @ref{22d1,,CRITICAL}. The returned mapping is copied from an internal
mapping on each call to this function.


Added in version 3.11.

@end deffn

@geindex getLevelName() (στη μονάδα logging)
@anchor{library/logging logging getLevelName}@anchor{33fa}
@deffn {Συνάρτηση} logging.getLevelName (level)

Returns the textual or numeric representation of logging level `level'.

If `level' is one of the predefined levels @ref{22d1,,CRITICAL}, @ref{22d0,,ERROR},
@ref{22cf,,WARNING}, @ref{22ce,,INFO} or @ref{22cd,,DEBUG} then you get the
corresponding string. If you have associated levels with names using
@ref{33f8,,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 Σημείωση 
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{33b5,,LogRecord attributes}), and
vice versa.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 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 in order to retain backward compatibility.

@end deffn

@geindex getHandlerByName() (στη μονάδα logging)
@anchor{library/logging logging getHandlerByName}@anchor{1d60}
@deffn {Συνάρτηση} logging.getHandlerByName (name)

Returns a handler with the specified `name', or @code{None} if there is no handler
with that name.


Added in version 3.12.

@end deffn

@geindex getHandlerNames() (στη μονάδα logging)
@anchor{library/logging logging getHandlerNames}@anchor{1c74}
@deffn {Συνάρτηση} logging.getHandlerNames ()

Returns an immutable set of all known handler names.


Added in version 3.12.

@end deffn

@geindex makeLogRecord() (στη μονάδα logging)
@anchor{library/logging logging makeLogRecord}@anchor{33e4}
@deffn {Συνάρτηση} logging.makeLogRecord (attrdict)

Creates and returns a new @ref{138f,,LogRecord} instance whose attributes are
defined by `attrdict'. This function is useful for taking a pickled
@code{LogRecord} attribute dictionary, sent over a socket, and reconstituting
it as a @code{LogRecord} instance at the receiving end.
@end deffn

@geindex basicConfig() (στη μονάδα logging)
@anchor{library/logging logging basicConfig}@anchor{dc2}
@deffn {Συνάρτηση} logging.basicConfig (**kwargs)

Does basic configuration for the logging system by either creating a
@ref{15a1,,StreamHandler} with a default @ref{1839,,Formatter}
or using the  given `formatter' instance, and adding it to the
root logger. The functions @ref{33b7,,debug()}, @ref{33e0,,info()}, @ref{331,,warning()},
@ref{33f4,,error()} and @ref{33f5,,critical()} will call @code{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 Σημείωση 
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{1e4a,,FileHandler} be
created, using the specified filename,
rather than a @ref{15a1,,StreamHandler}.

@item

`filemode'

@tab

If `filename' is specified, open the file
in this @ref{27d2,,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{1592,,time.strftime()}.

@item

`style'

@tab

If `format' is specified, use this style
for the format string. One of @code{'%'},
@code{'@{'} or @code{'$'} for @ref{ab9,,printf-style},
@ref{a12,,str.format()} or
@ref{a77,,string.Template} respectively.
Defaults to @code{'%'}.

@item

`level'

@tab

Set the root logger level to the specified
@ref{a4a,,level}.

@item

`stream'

@tab

Use the specified stream to initialize the
@ref{15a1,,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{1e4a,,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{1e4a,,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{32b,,open()},
which means that it will be treated the
same as passing “errors”.

@item

`formatter'

@tab

If specified, set this formatter instance
(see @ref{33d2,,Formatter Objects})
for all involved handlers.
If not specified, the default is to create
and use an instance of
@ref{1839,,logging.Formatter} based on
arguments `format', `datefmt' and `style'.
When `formatter' is specified together with
any of the three arguments `format',
`datefmt' and `style', a @code{ValueError} is
raised to signal that these arguments would
lose meaning otherwise.

@end multitable



Άλλαξε στην έκδοση 3.2: The `style' argument was added.



Άλλαξε στην έκδοση 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').



Άλλαξε στην έκδοση 3.8: The `force' argument was added.



Άλλαξε στην έκδοση 3.9: The `encoding' and `errors' arguments were added.



Άλλαξε στην έκδοση 3.15: The `formatter' argument was added.

@end deffn

@geindex shutdown() (στη μονάδα logging)
@anchor{library/logging logging shutdown}@anchor{33fb}
@deffn {Συνάρτηση} 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{d,,atexit}), so normally there’s no need to do that
manually.
@end deffn

@geindex setLoggerClass() (στη μονάδα logging)
@anchor{library/logging logging setLoggerClass}@anchor{33f3}
@deffn {Συνάρτηση} 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{d2a,,logging.getLogger()} API to get your loggers.
@end deffn

@geindex setLogRecordFactory() (στη μονάδα logging)
@anchor{library/logging logging setLogRecordFactory}@anchor{33e8}
@deffn {Συνάρτηση} logging.setLogRecordFactory (factory)

Set a callable which is used to create a @ref{138f,,LogRecord}.

@*Παράμετροι: 
@code{factory} – The factory callable to be used to instantiate a log record.



Added in version 3.2: This function has been provided, along with @ref{33e7,,getLogRecordFactory()}, to
allow developers more control over how the @ref{138f,,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

@*name: 
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{1237,,traceback.print_stack()}, showing the call hierarchy.


@*kwargs: 
Additional keyword arguments.

@end quotation
@end deffn

@node Module-Level Attributes,Integration with the warnings module,Module-Level Functions,logging — Logging facility for Python
@anchor{library/logging module-level-attributes}@anchor{33fc}
@subsubsection Module-Level Attributes


@geindex lastResort (στη μονάδα logging)
@anchor{library/logging logging lastResort}@anchor{15a3}
@deffn {Δεδομένα} logging.lastResort

A «handler of last resort» is available through this attribute. This
is a @ref{15a1,,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}.


Added in version 3.2.

@end deffn

@geindex raiseExceptions (στη μονάδα logging)
@anchor{library/logging logging raiseExceptions}@anchor{15a2}
@deffn {Δεδομένα} logging.raiseExceptions

Used to see if exceptions during handling should be propagated.

Default: @code{True}.

If @code{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{33fd}
@subsubsection Integration with the warnings module


The @ref{33fe,,captureWarnings()} function can be used to integrate @code{logging}
with the @ref{11b,,warnings} module.

@geindex captureWarnings() (στη μονάδα logging)
@anchor{library/logging logging captureWarnings}@anchor{33fe}
@deffn {Συνάρτηση} 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{11b,,warnings} module will
be redirected to the logging system. Specifically, a warning will be
formatted using @ref{1fe7,,warnings.formatwarning()} and the resulting string
logged to a logger named @code{'py.warnings'} with a severity of @ref{22cf,,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 Δείτε επίσης



@table @asis

@item Module @ref{8b,,logging.config}

Configuration API for the logging module.

@item Module @ref{8c,,logging.handlers}

Useful handlers included with the logging module.

@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 @code{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 @code{logging} package in the standard
library.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node logging config — Logging configuration,logging handlers — Logging handlers,logging — Logging facility for Python,Generic Operating System Services
@anchor{library/logging config doc}@anchor{33ff}@anchor{library/logging config logging-config-logging-configuration}@anchor{3400}@anchor{library/logging config module-logging config}@anchor{8b}@anchor{library/logging config translation-repo}@anchor{3401}
@subsection @code{logging.config} — Logging configuration


@geindex module; logging.config

`Source code:' Lib/logging/config.py@footnote{https://github.com/python/cpython/tree/main/Lib/logging/config.py}

@subsubheading Important



This page contains only reference information. For tutorials,
please see


@itemize *

@item 
@ref{159e,,Basic Tutorial}

@item 
@ref{159f,,Advanced Tutorial}

@item 
@ref{15a0,,Logging Cookbook}
@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{3402}@anchor{library/logging config logging-config-api}@anchor{1696}
@subsubsection Configuration functions


The following functions configure the logging module. They are located in the
@code{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{8a,,logging} itself) and defining handlers which are declared either in
@code{logging} or @ref{8c,,logging.handlers}.

@geindex dictConfig() (στη μονάδα logging.config)
@anchor{library/logging config logging config dictConfig}@anchor{1559}
@deffn {Συνάρτηση} logging.config.dictConfig (config)

Takes the logging configuration from a dictionary.  The contents of
this dictionary are described in @ref{3403,,Configuration dictionary schema}
below.

If an error is encountered during configuration, this function will
raise a @ref{277,,ValueError}, @ref{291,,TypeError}, @ref{1a9,,AttributeError}
or @ref{1bd,,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 @code{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.

@code{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 @code{dictConfig()} could be called exactly as
in the default, uncustomized state.


Added in version 3.2.

@end deffn

@geindex fileConfig() (στη μονάδα logging.config)
@anchor{library/logging config logging config fileConfig}@anchor{f0e}
@deffn {Συνάρτηση} logging.config.fileConfig (fname, defaults=None, disable_existing_loggers=True, encoding=None)

Reads the logging configuration from a @ref{26,,configparser}-format file. The
format of the file should be as described in
@ref{3404,,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{243,,FileNotFoundError} if the file
doesn’t exist and @ref{30d,,RuntimeError} if the file is invalid or
empty.

@*Παράμετροι: 

@itemize *

@item 
@code{fname} – A filename, or a file-like object, or an instance derived
from @ref{130e,,RawConfigParser}. If a
@code{RawConfigParser}-derived instance is passed, it is used as
is. Otherwise, a @ref{6e4,,ConfigParser} is
instantiated, and the configuration read by it from the
object passed in @code{fname}. If that has a @ref{c2,,readline()}
method, it is assumed to be a file-like object and read using
@ref{915,,read_file()}; otherwise,
it is assumed to be a filename and passed to
@ref{180a,,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



Άλλαξε στην έκδοση 3.4: An instance of a subclass of @ref{130e,,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


Άλλαξε στην έκδοση 3.10: Added the `encoding' parameter.



Άλλαξε στην έκδοση 3.12: An exception will be thrown if the provided file
doesn’t exist or is invalid or empty.


@end deffn

@geindex listen() (στη μονάδα logging.config)
@anchor{library/logging config logging config listen}@anchor{130f}
@deffn {Συνάρτηση} 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{1559,,dictConfig()} or
@ref{f0e,,fileConfig()}. Returns a @ref{420,,Thread} instance on which
you can call @ref{422,,start()} to start the server, and which
you can @ref{158d,,join()} when appropriate. To stop the server,
call @ref{3405,,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{3406}
@cartouche
@quotation Σημείωση 
Because portions of the configuration are passed through
@ref{184,,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
@code{listen()}. Specifically, if the process calling @code{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
@code{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 @code{listen()} to prevent unrecognised
configurations from being applied.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.4: The @code{verify} argument was added.


@cartouche
@quotation Σημείωση 
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{1559,,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() (στη μονάδα logging.config)
@anchor{library/logging config logging config stopListening}@anchor{3405}
@deffn {Συνάρτηση} logging.config.stopListening ()

Stops the listening server which was created with a call to @ref{130f,,listen()}.
This is typically called before calling @code{join()} on the return value from
@code{listen()}.
@end deffn

@node Security considerations,Configuration dictionary schema,Configuration functions,logging config — Logging configuration
@anchor{library/logging config security-considerations}@anchor{3407}
@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{3408,,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{3409}@anchor{library/logging config logging-config-dictschema}@anchor{3403}
@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{8a,,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{340a,,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{340b}
@subsubsection Dictionary Schema Details


The dictionary passed to @ref{1559,,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{3408,,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{340c}

@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{1839,,Formatter} instance.

The configuring dict is searched for the following optional keys
which correspond to the arguments passed to create a
@ref{1839,,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{1839,,Formatter}, thus this key is
most useful for instantiating a customised subclass of
@code{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{3408,,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{15a4,,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.


Άλλαξε στην έκδοση 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{15a1,,logging.StreamHandler}, using @code{sys.stdout} as the underlying
stream.  The handler with id @code{file} is instantiated as a
@ref{1b59,,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.


Άλλαξε στην έκδοση 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{f0e,,fileConfig()} API.

If the specified value is @code{True}, the configuration is processed
as described in the section on @ref{340d,,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{f0e,,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{340e}@anchor{library/logging config logging-config-dict-incremental}@anchor{340d}
@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{340a}@anchor{library/logging config object-connections}@anchor{340f}
@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{3408}@anchor{library/logging config user-defined-objects}@anchor{3410}
@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{1839,,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 @code{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

and:

@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{1839,,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 Προειδοποίηση 
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.


Άλλαξε στην έκδοση 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
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 Προειδοποίηση 
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{3411}@anchor{library/logging config handler-configuration-order}@anchor{3412}
@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{3413}@anchor{library/logging config logging-config-dict-externalobj}@anchor{3414}
@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{3415}@anchor{library/logging config logging-config-dict-internalobj}@anchor{3416}
@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{8a,,logging} module.  For
example, consider @ref{3417,,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{3418}@anchor{library/logging config logging-import-resolution}@anchor{3419}
@subsubsection Import resolution and custom importers


Import resolution, by default, uses the builtin @ref{ca6,,__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{666,,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{666,,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{1b5e}@anchor{library/logging config configuring-queuehandler-and-queuelistener}@anchor{341a}
@subsubsection Configuring QueueHandler and QueueListener


If you want to configure a @ref{1d5f,,QueueHandler}, noting that this
is normally used in conjunction with a @ref{4cf,,QueueListener}, you
can configure both together. After the configuration, the @code{QueueListener} instance
will be available as the @ref{341b,,listener} attribute of
the created handler, and that in turn will be available to you using
@ref{1d60,,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{341c,,Queue.put_nowait}
and @ref{341d,,Queue.get} public API. For instance, this may be
an actual instance of @ref{1738,,queue.Queue} or a subclass thereof, or a proxy
obtained by @ref{341e,,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{1738,,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{3408,,User-defined objects}. The result of this construction should be a
@ref{1738,,queue.Queue} instance.
@end itemize

If the  @code{queue} key is absent, a standard unbounded @ref{1738,,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{4cf,,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{3408,,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{4cf,,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{1d5f,,QueueHandler} and
@ref{4cf,,QueueListener}.


Added in version 3.12.


@node Configuration file format,,Configuration dictionary schema,logging config — Logging configuration
@anchor{library/logging config configuration-file-format}@anchor{341f}@anchor{library/logging config logging-config-fileformat}@anchor{3404}
@subsubsection Configuration file format


The configuration file format understood by @ref{f0e,,fileConfig()} is based on
@ref{26,,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 Σημείωση 
The @ref{f0e,,fileConfig()} API is older than the @ref{1559,,dictConfig()} API and does
not provide functionality to cover certain aspects of logging. For example,
you cannot configure @ref{15a4,,Filter} objects, which provide for
filtering of messages beyond simple integer levels, using @code{fileConfig()}.
If you need to have instances of @code{Filter} in your logging
configuration, you will need to use @code{dictConfig()}. Note that future
enhancements to configuration functionality will be added to
@code{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{27c6,,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{184,,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{27c6,,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{27c6,,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{340c,,formatters section}.

The @code{defaults} entry, when @ref{27c6,,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 Σημείωση 
Due to the use of @ref{184,,eval()} as described above, there are
potential security risks which result from using the @ref{130f,,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
@code{listen()} documentation for more information.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{8a,,logging}

API reference for the logging module.

@item Module @ref{8c,,logging.handlers}

Useful handlers included with the logging module.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node logging handlers — Logging handlers,platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας,logging config — Logging configuration,Generic Operating System Services
@anchor{library/logging handlers doc}@anchor{3420}@anchor{library/logging handlers logging-handlers-logging-handlers}@anchor{3421}@anchor{library/logging handlers module-logging handlers}@anchor{8c}@anchor{library/logging handlers translation-repo}@anchor{3422}
@subsection @code{logging.handlers} — Logging handlers


@geindex module; logging.handlers

`Source code:' Lib/logging/handlers.py@footnote{https://github.com/python/cpython/tree/main/Lib/logging/handlers.py}

@subsubheading Important



This page contains only reference information. For tutorials,
please see


@itemize *

@item 
@ref{159e,,Basic Tutorial}

@item 
@ref{159f,,Advanced Tutorial}

@item 
@ref{15a0,,Logging Cookbook}
@end itemize


__________________________________________________________________


The following useful handlers are provided in the package. Note that three of
the handlers (@ref{15a1,,StreamHandler}, @ref{1e4a,,FileHandler} and
@ref{1629,,NullHandler}) are actually defined in the @ref{8a,,logging} module itself,
but have been documented here along with the other handlers.

@menu
* StreamHandler:: 
* FileHandler:: 
* NullHandler:: 
* WatchedFileHandler:: 
* BaseRotatingHandler:: 
* RotatingFileHandler:: 
* TimedRotatingFileHandler:: 
* SocketHandler:: 
* DatagramHandler:: 
* SysLogHandler:: 
* NTEventLogHandler:: 
* SMTPHandler:: 
* MemoryHandler:: 
* HTTPHandler:: 
* QueueHandler:: 
* QueueListener:: 

@end menu

@node StreamHandler,FileHandler,,logging handlers — Logging handlers
@anchor{library/logging handlers stream-handler}@anchor{3423}@anchor{library/logging handlers streamhandler}@anchor{3424}
@subsubsection StreamHandler


The @ref{15a1,,StreamHandler} class, located in the core @ref{8a,,logging} package,
sends logging output to streams such as `sys.stdout', `sys.stderr' or any
file-like object (or, more precisely, any object which supports @code{write()}
and @code{flush()} methods).

@geindex StreamHandler (κλάση σε logging)
@anchor{library/logging handlers logging StreamHandler}@anchor{15a1}
@deffn {Κλάση} logging.StreamHandler (stream=None)

Returns a new instance of the @code{StreamHandler} class. If `stream' is
specified, the instance will use it for logging output; otherwise, `sys.stderr'
will be used.

@geindex emit() (μέθοδος της logging.StreamHandler)
@anchor{library/logging handlers logging StreamHandler emit}@anchor{3425}
@deffn {Μέθοδος} emit (record)

If a formatter is specified, it is used to format the record. The record
is then written to the stream followed by @ref{3426,,terminator}. If exception information
is present, it is formatted using @ref{c27,,traceback.print_exception()} and
appended to the stream.
@end deffn

@geindex flush() (μέθοδος της logging.StreamHandler)
@anchor{library/logging handlers logging StreamHandler flush}@anchor{3427}
@deffn {Μέθοδος} flush ()

Flushes the stream by calling its @code{flush()} method. Note that the
@code{close()} method is inherited from @ref{1838,,Handler} and so
does no output, so an explicit @code{flush()} call may be needed at times.
@end deffn

@geindex setStream() (μέθοδος της logging.StreamHandler)
@anchor{library/logging handlers logging StreamHandler setStream}@anchor{f0d}
@deffn {Μέθοδος} setStream (stream)

Sets the instance’s stream to the specified value, if it is different.
The old stream is flushed before the new stream is set.

@*Παράμετροι: 
@code{stream} – The stream that the handler should use.


@*Επιστρέφει: 
the old stream, if the stream was changed, or @code{None} if it wasn’t.



Added in version 3.7.

@end deffn

@geindex terminator (ιδιότητα της logging.StreamHandler)
@anchor{library/logging handlers logging StreamHandler terminator}@anchor{3426}
@deffn {Ιδιότητα} terminator

String used as the terminator when writing a formatted record to a stream.
Default value is @code{'\n'}.

If you don’t want a newline termination, you can set the handler instance’s
@code{terminator} attribute to the empty string.

In earlier versions, the terminator was hardcoded as @code{'\n'}.


Added in version 3.2.

@end deffn
@end deffn

@node FileHandler,NullHandler,StreamHandler,logging handlers — Logging handlers
@anchor{library/logging handlers file-handler}@anchor{3428}@anchor{library/logging handlers filehandler}@anchor{3429}
@subsubsection FileHandler


The @ref{1e4a,,FileHandler} class, located in the core @ref{8a,,logging} package,
sends logging output to a disk file.  It inherits the output functionality from
@ref{15a1,,StreamHandler}.

@geindex FileHandler (κλάση σε logging)
@anchor{library/logging handlers logging FileHandler}@anchor{1e4a}
@deffn {Κλάση} logging.FileHandler (filename, mode='a', encoding=None, delay=False, errors=None)

Returns a new instance of the @code{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{342a,,emit()}. By default, the file grows indefinitely. If
`errors' is specified, it’s used to determine how encoding errors are handled.


Άλλαξε στην έκδοση 3.6: As well as string values, @ref{4ee,,Path} objects are also accepted
for the `filename' argument.



Άλλαξε στην έκδοση 3.9: The `errors' parameter was added.


@geindex close() (μέθοδος της logging.FileHandler)
@anchor{library/logging handlers logging FileHandler close}@anchor{342b}
@deffn {Μέθοδος} close ()

Closes the file.
@end deffn

@geindex emit() (μέθοδος της logging.FileHandler)
@anchor{library/logging handlers logging FileHandler emit}@anchor{342a}
@deffn {Μέθοδος} emit (record)

Outputs the record to the file.

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 NullHandler,WatchedFileHandler,FileHandler,logging handlers — Logging handlers
@anchor{library/logging handlers null-handler}@anchor{342c}@anchor{library/logging handlers nullhandler}@anchor{342d}
@subsubsection NullHandler



Added in version 3.1.


The @ref{1629,,NullHandler} class, located in the core @ref{8a,,logging} package,
does not do any formatting or output. It is essentially a “no-op” handler
for use by library developers.

@geindex NullHandler (κλάση σε logging)
@anchor{library/logging handlers logging NullHandler}@anchor{1629}
@deffn {Κλάση} logging.NullHandler

Returns a new instance of the @code{NullHandler} class.

@geindex emit() (μέθοδος της logging.NullHandler)
@anchor{library/logging handlers logging NullHandler emit}@anchor{342e}
@deffn {Μέθοδος} emit (record)

This method does nothing.
@end deffn

@geindex handle() (μέθοδος της logging.NullHandler)
@anchor{library/logging handlers logging NullHandler handle}@anchor{342f}
@deffn {Μέθοδος} handle (record)

This method does nothing.
@end deffn

@geindex createLock() (μέθοδος της logging.NullHandler)
@anchor{library/logging handlers logging NullHandler createLock}@anchor{3430}
@deffn {Μέθοδος} createLock ()

This method returns @code{None} for the lock, since there is no
underlying I/O to which access needs to be serialized.
@end deffn
@end deffn

See @ref{3431,,Configuring Logging for a Library} for more information on how to use
@ref{1629,,NullHandler}.

@node WatchedFileHandler,BaseRotatingHandler,NullHandler,logging handlers — Logging handlers
@anchor{library/logging handlers watched-file-handler}@anchor{3432}@anchor{library/logging handlers watchedfilehandler}@anchor{3433}
@subsubsection WatchedFileHandler


The @ref{3434,,WatchedFileHandler} class, located in the @code{logging.handlers}
module, is a @code{FileHandler} which watches the file it is logging to. If
the file changes, it is closed and reopened using the file name.

A file change can happen because of usage of programs such as `newsyslog' and
`logrotate' which perform log file rotation. This handler, intended for use
under Unix/Linux, watches the file to see if it has changed since the last emit.
(A file is deemed to have changed if its device or inode have changed.) If the
file has changed, the old file stream is closed, and the file opened to get a
new stream.

This handler is not appropriate for use under Windows, because under Windows
open log files cannot be moved or renamed - logging opens the files with
exclusive locks - and so there is no need for such a handler. Furthermore,
`ST_INO' is not supported under Windows; @ref{4f5,,stat()} always returns zero
for this value.

@geindex WatchedFileHandler (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers WatchedFileHandler}@anchor{3434}
@deffn {Κλάση} logging.handlers.WatchedFileHandler (filename, mode='a', encoding=None, delay=False, errors=None)

Returns a new instance of the @code{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{3435,,emit()}.  By default, the file grows indefinitely. If
`errors' is provided, it determines how encoding errors are handled.


Άλλαξε στην έκδοση 3.6: As well as string values, @ref{4ee,,Path} objects are also accepted
for the `filename' argument.



Άλλαξε στην έκδοση 3.9: The `errors' parameter was added.


@geindex reopenIfNeeded() (μέθοδος της logging.handlers.WatchedFileHandler)
@anchor{library/logging handlers logging handlers WatchedFileHandler reopenIfNeeded}@anchor{1076}
@deffn {Μέθοδος} reopenIfNeeded ()

Checks to see if the file has changed.  If it has, the existing stream is
flushed and closed and the file opened again, typically as a precursor to
outputting the record to the file.


Added in version 3.6.

@end deffn

@geindex emit() (μέθοδος της logging.handlers.WatchedFileHandler)
@anchor{library/logging handlers logging handlers WatchedFileHandler emit}@anchor{3435}
@deffn {Μέθοδος} emit (record)

Outputs the record to the file, but first calls @ref{1076,,reopenIfNeeded()} to
reopen the file if it has changed.
@end deffn
@end deffn

@node BaseRotatingHandler,RotatingFileHandler,WatchedFileHandler,logging handlers — Logging handlers
@anchor{library/logging handlers base-rotating-handler}@anchor{3436}@anchor{library/logging handlers baserotatinghandler}@anchor{3437}
@subsubsection BaseRotatingHandler


The @ref{3438,,BaseRotatingHandler} class, located in the @code{logging.handlers}
module, is the base class for the rotating file handlers,
@ref{1b59,,RotatingFileHandler} and @ref{130b,,TimedRotatingFileHandler}. You should
not need to instantiate this class, but it has attributes and methods you may
need to override.

@geindex BaseRotatingHandler (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers BaseRotatingHandler}@anchor{3438}
@deffn {Κλάση} logging.handlers.BaseRotatingHandler (filename, mode, encoding=None, delay=False, errors=None)

The parameters are as for @code{FileHandler}. The attributes are:

@geindex namer (ιδιότητα της logging.handlers.BaseRotatingHandler)
@anchor{library/logging handlers logging handlers BaseRotatingHandler namer}@anchor{3439}
@deffn {Ιδιότητα} namer

If this attribute is set to a callable, the @ref{343a,,rotation_filename()}
method delegates to this callable. The parameters passed to the callable
are those passed to @code{rotation_filename()}.

@cartouche
@quotation Σημείωση 
The namer function is called quite a few times during rollover,
so it should be as simple and as fast as possible. It should also
return the same output every time for a given input, otherwise the
rollover behaviour may not work as expected.

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{1b59,,RotatingFileHandler} expects to have a set of log files
whose names contain successive integers, so that rotation works as expected,
and @ref{130b,,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 @code{TimedRotatingFileHandler} which
overrides the @ref{343b,,getFilesToDelete()} method to
fit in with the custom naming scheme.)
@end quotation
@end cartouche


Added in version 3.3.

@end deffn

@geindex rotator (ιδιότητα της logging.handlers.BaseRotatingHandler)
@anchor{library/logging handlers logging handlers BaseRotatingHandler rotator}@anchor{343c}
@deffn {Ιδιότητα} rotator

If this attribute is set to a callable, the @ref{343d,,rotate()} method
delegates to this callable.  The parameters passed to the callable are
those passed to @code{rotate()}.


Added in version 3.3.

@end deffn

@geindex rotation_filename() (μέθοδος της logging.handlers.BaseRotatingHandler)
@anchor{library/logging handlers logging handlers BaseRotatingHandler rotation_filename}@anchor{343a}
@deffn {Μέθοδος} rotation_filename (default_name)

Modify the filename of a log file when rotating.

This is provided so that a custom filename can be provided.

The default implementation calls the “namer” attribute of the handler,
if it’s callable, passing the default name to it. If the attribute isn’t
callable (the default is @code{None}), the name is returned unchanged.

@*Παράμετροι: 
@code{default_name} – The default name for the log file.



Added in version 3.3.

@end deffn

@geindex rotate() (μέθοδος της logging.handlers.BaseRotatingHandler)
@anchor{library/logging handlers logging handlers BaseRotatingHandler rotate}@anchor{343d}
@deffn {Μέθοδος} rotate (source, dest)

When rotating, rotate the current log.

The default implementation calls the “rotator” attribute of the handler,
if it’s callable, passing the source and dest arguments to it. If the
attribute isn’t callable (the default is @code{None}), the source is simply
renamed to the destination.

@*Παράμετροι: 

@itemize *

@item 
@code{source} – The source filename. This is normally the base
filename, e.g. “test.log”.

@item 
@code{dest} – The destination filename. This is normally
what the source is rotated to, e.g. “test.log.1”.
@end itemize



Added in version 3.3.

@end deffn
@end deffn

The reason the attributes exist is to save you having to subclass - you can use
the same callables for instances of @ref{1b59,,RotatingFileHandler} and
@ref{130b,,TimedRotatingFileHandler}. If either the namer or rotator callable
raises an exception, this will be handled in the same way as any other
exception during an @code{emit()} call, i.e. via the @code{handleError()} method
of the handler.

If you need to make more significant changes to rotation processing, you can
override the methods.

For an example, see @ref{343e,,Using a rotator and namer to customize log rotation processing}.

@node RotatingFileHandler,TimedRotatingFileHandler,BaseRotatingHandler,logging handlers — Logging handlers
@anchor{library/logging handlers rotating-file-handler}@anchor{343f}@anchor{library/logging handlers rotatingfilehandler}@anchor{3440}
@subsubsection RotatingFileHandler


The @ref{1b59,,RotatingFileHandler} class, located in the @code{logging.handlers}
module, supports rotation of disk log files.

@geindex RotatingFileHandler (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers RotatingFileHandler}@anchor{1b59}
@deffn {Κλάση} logging.handlers.RotatingFileHandler (filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)

Returns a new instance of the @code{RotatingFileHandler} 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{3441,,emit()}.  By default, the file grows indefinitely. If
`errors' is provided, it determines how encoding errors are handled.

You can use the `maxBytes' and `backupCount' values to allow the file to
`rollover' at a predetermined size. When the size is about to be exceeded,
the file is closed and a new file is silently opened for output. Rollover occurs
whenever the current log file is nearly `maxBytes' in length; but if either of
`maxBytes' or `backupCount' is zero, rollover never occurs, so you generally want
to set `backupCount' to at least 1, and have a non-zero `maxBytes'.
When `backupCount' is non-zero, the system will save old log files by appending
the extensions “.1”, “.2” etc., to the filename. For example, with a `backupCount'
of 5 and a base file name of @code{app.log}, you would get @code{app.log},
@code{app.log.1}, @code{app.log.2}, up to @code{app.log.5}. The file being
written to is always @code{app.log}.  When this file is filled, it is closed
and renamed to @code{app.log.1}, and if files @code{app.log.1},
@code{app.log.2}, etc. exist, then they are renamed to @code{app.log.2},
@code{app.log.3} etc. respectively.


Άλλαξε στην έκδοση 3.6: As well as string values, @ref{4ee,,Path} objects are also accepted
for the `filename' argument.



Άλλαξε στην έκδοση 3.9: The `errors' parameter was added.


@geindex doRollover() (μέθοδος της logging.handlers.RotatingFileHandler)
@anchor{library/logging handlers logging handlers RotatingFileHandler doRollover}@anchor{3442}
@deffn {Μέθοδος} doRollover ()

Does a rollover, as described above.
@end deffn

@geindex emit() (μέθοδος της logging.handlers.RotatingFileHandler)
@anchor{library/logging handlers logging handlers RotatingFileHandler emit}@anchor{3441}
@deffn {Μέθοδος} emit (record)

Outputs the record to the file, catering for rollover as described
previously.
@end deffn

@geindex shouldRollover() (μέθοδος της logging.handlers.RotatingFileHandler)
@anchor{library/logging handlers logging handlers RotatingFileHandler shouldRollover}@anchor{3443}
@deffn {Μέθοδος} shouldRollover (record)

See if the supplied record would cause the file to exceed the configured size limit.
@end deffn
@end deffn

@node TimedRotatingFileHandler,SocketHandler,RotatingFileHandler,logging handlers — Logging handlers
@anchor{library/logging handlers timed-rotating-file-handler}@anchor{3444}@anchor{library/logging handlers timedrotatingfilehandler}@anchor{3445}
@subsubsection TimedRotatingFileHandler


The @ref{130b,,TimedRotatingFileHandler} class, located in the
@code{logging.handlers} module, supports rotation of disk log files at certain
timed intervals.

@geindex TimedRotatingFileHandler (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers TimedRotatingFileHandler}@anchor{130b}
@deffn {Κλάση} logging.handlers.TimedRotatingFileHandler (filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)

Returns a new instance of the @code{TimedRotatingFileHandler} class. The
specified file is opened and used as the stream for logging. On rotating it also
sets the filename suffix. Rotating happens based on the product of `when' and
`interval'.

You can use the `when' to specify the type of `interval'. The list of possible
values is below.  Note that they are not case sensitive.


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Value

@tab

Type of interval

@tab

If/how `atTime' is used

@item

@code{'S'}

@tab

Seconds

@tab

Ignored

@item

@code{'M'}

@tab

Minutes

@tab

Ignored

@item

@code{'H'}

@tab

Hours

@tab

Ignored

@item

@code{'D'}

@tab

Days

@tab

Ignored

@item

@code{'W0'-'W6'}

@tab

Weekday (0=Monday)

@tab

Used to compute initial
rollover time

@item

@code{'midnight'}

@tab

Roll over at midnight, if
`atTime' not specified,
else at time `atTime'

@tab

Used to compute initial
rollover time

@end multitable


When using weekday-based rotation, specify “W0” for Monday, “W1” for
Tuesday, and so on up to “W6” for Sunday. In this case, the value passed for
`interval' isn’t used.

The system will save old log files by appending extensions to the filename.
The extensions are date-and-time based, using the strftime format
@code{%Y-%m-%d_%H-%M-%S} or a leading portion thereof, depending on the
rollover interval.

When computing the next rollover time for the first time (when the handler
is created), the last modification time of an existing log file, or else
the current time, is used to compute when the next rotation will occur.

If the `utc' argument is true, times in UTC will be used; otherwise
local time is used.

If `backupCount' is nonzero, at most `backupCount' files
will be kept, and if more would be created when rollover occurs, the oldest
one is deleted. The deletion logic uses the interval to determine which
files to delete, so changing the interval may leave old files lying around.

If `delay' is true, then file opening is deferred until the first call to
@ref{3446,,emit()}.

If `atTime' is not @code{None}, it must be a @code{datetime.time} instance which
specifies the time of day when rollover occurs, for the cases where rollover
is set to happen «at midnight» or «on a particular weekday». Note that in
these cases, the `atTime' value is effectively used to compute the `initial'
rollover, and subsequent rollovers would be calculated via the normal
interval calculation.

If `errors' is specified, it’s used to determine how encoding errors are
handled.

@cartouche
@quotation Σημείωση 
Calculation of the initial rollover time is done when the handler
is initialised. Calculation of subsequent rollover times is done only
when rollover occurs, and rollover occurs only when emitting output. If
this is not kept in mind, it might lead to some confusion. For example,
if an interval of «every minute» is set, that does not mean you will
always see log files with times (in the filename) separated by a minute;
if, during application execution, logging output is generated more
frequently than once a minute, `then' you can expect to see log files
with times separated by a minute. If, on the other hand, logging messages
are only output once every five minutes (say), then there will be gaps in
the file times corresponding to the minutes where no output (and hence no
rollover) occurred.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.4: `atTime' parameter was added.



Άλλαξε στην έκδοση 3.6: As well as string values, @ref{4ee,,Path} objects are also accepted
for the `filename' argument.



Άλλαξε στην έκδοση 3.9: The `errors' parameter was added.


@geindex doRollover() (μέθοδος της logging.handlers.TimedRotatingFileHandler)
@anchor{library/logging handlers logging handlers TimedRotatingFileHandler doRollover}@anchor{3447}
@deffn {Μέθοδος} doRollover ()

Does a rollover, as described above.
@end deffn

@geindex emit() (μέθοδος της logging.handlers.TimedRotatingFileHandler)
@anchor{library/logging handlers logging handlers TimedRotatingFileHandler emit}@anchor{3446}
@deffn {Μέθοδος} emit (record)

Outputs the record to the file, catering for rollover as described above.
@end deffn

@geindex getFilesToDelete() (μέθοδος της logging.handlers.TimedRotatingFileHandler)
@anchor{library/logging handlers logging handlers TimedRotatingFileHandler getFilesToDelete}@anchor{343b}
@deffn {Μέθοδος} 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

@geindex shouldRollover() (μέθοδος της logging.handlers.TimedRotatingFileHandler)
@anchor{library/logging handlers logging handlers TimedRotatingFileHandler shouldRollover}@anchor{3448}
@deffn {Μέθοδος} shouldRollover (record)

See if enough time has passed for a rollover to occur and if it has, compute
the next rollover time.
@end deffn
@end deffn

@node SocketHandler,DatagramHandler,TimedRotatingFileHandler,logging handlers — Logging handlers
@anchor{library/logging handlers socket-handler}@anchor{3449}@anchor{library/logging handlers sockethandler}@anchor{344a}
@subsubsection SocketHandler


The @ref{130c,,SocketHandler} class, located in the @code{logging.handlers} module,
sends logging output to a network socket. The base class uses a TCP socket.

@geindex SocketHandler (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers SocketHandler}@anchor{130c}
@deffn {Κλάση} logging.handlers.SocketHandler (host, port)

Returns a new instance of the @code{SocketHandler} class intended to
communicate with a remote machine whose address is given by `host' and `port'.


Άλλαξε στην έκδοση 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() (μέθοδος της logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler close}@anchor{344b}
@deffn {Μέθοδος} close ()

Closes the socket.
@end deffn

@geindex emit() (μέθοδος της logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler emit}@anchor{344c}
@deffn {Μέθοδος} 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{138f,,LogRecord}, use the @ref{33e4,,makeLogRecord()}
function.
@end deffn

@geindex handleError() (μέθοδος της logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler handleError}@anchor{344d}
@deffn {Μέθοδος} handleError ()

Handles an error which has occurred during @ref{344c,,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() (μέθοδος της logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler makeSocket}@anchor{344e}
@deffn {Μέθοδος} 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{1698,,socket.SOCK_STREAM}).
@end deffn

@geindex makePickle() (μέθοδος της logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler makePickle}@anchor{344f}
@deffn {Μέθοδος} 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() (μέθοδος της logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler send}@anchor{3450}
@deffn {Μέθοδος} 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{344f,,makePickle()}.

This function allows for partial sends, which can happen when the network
is busy.
@end deffn

@geindex createSocket() (μέθοδος της logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler createSocket}@anchor{a4d}
@deffn {Μέθοδος} 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,SocketHandler,logging handlers — Logging handlers
@anchor{library/logging handlers datagram-handler}@anchor{3451}@anchor{library/logging handlers datagramhandler}@anchor{3452}
@subsubsection DatagramHandler


The @ref{130d,,DatagramHandler} class, located in the @code{logging.handlers}
module, inherits from @ref{130c,,SocketHandler} to support sending logging messages
over UDP sockets.

@geindex DatagramHandler (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers DatagramHandler}@anchor{130d}
@deffn {Κλάση} logging.handlers.DatagramHandler (host, port)

Returns a new instance of the @code{DatagramHandler} class intended to
communicate with a remote machine whose address is given by `host' and `port'.

@cartouche
@quotation Σημείωση 
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


Άλλαξε στην έκδοση 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() (μέθοδος της logging.handlers.DatagramHandler)
@anchor{library/logging handlers logging handlers DatagramHandler emit}@anchor{3453}
@deffn {Μέθοδος} 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{138f,,LogRecord}, use the @ref{33e4,,makeLogRecord()}
function.
@end deffn

@geindex makeSocket() (μέθοδος της logging.handlers.DatagramHandler)
@anchor{library/logging handlers logging handlers DatagramHandler makeSocket}@anchor{3454}
@deffn {Μέθοδος} makeSocket ()

The factory method of @ref{130c,,SocketHandler} is here overridden to create
a UDP socket (@ref{1697,,socket.SOCK_DGRAM}).
@end deffn

@geindex send() (μέθοδος της logging.handlers.DatagramHandler)
@anchor{library/logging handlers logging handlers DatagramHandler send}@anchor{3455}
@deffn {Μέθοδος} 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{344f,,SocketHandler.makePickle()}.
@end deffn
@end deffn

@node SysLogHandler,NTEventLogHandler,DatagramHandler,logging handlers — Logging handlers
@anchor{library/logging handlers syslog-handler}@anchor{3456}@anchor{library/logging handlers sysloghandler}@anchor{3457}
@subsubsection SysLogHandler


The @ref{a4c,,SysLogHandler} class, located in the @code{logging.handlers} module,
supports sending logging messages to a remote or local Unix syslog.

@geindex SysLogHandler (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers SysLogHandler}@anchor{a4c}
@deffn {Κλάση} logging.handlers.SysLogHandler (address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM, timeout=None)

Returns a new instance of the @code{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{1697,,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{1698,,socket.SOCK_STREAM}.
If `timeout' is specified, it sets a timeout (in seconds) for the socket operations.
This can help prevent the program from hanging indefinitely if the syslog server is
unreachable. By default, `timeout' is @code{None}, meaning no timeout is applied.

Note that if your server is not listening on UDP port 514,
@code{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 Σημείωση 
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 @code{SysLogHandler} to work on this system.

See gh-91070@footnote{https://github.com/python/cpython/issues/91070} for more information.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.2: `socktype' was added.



Άλλαξε στην έκδοση 3.14: `timeout' was added.


@geindex close() (μέθοδος της logging.handlers.SysLogHandler)
@anchor{library/logging handlers logging handlers SysLogHandler close}@anchor{3458}
@deffn {Μέθοδος} close ()

Closes the socket to the remote host.
@end deffn

@geindex createSocket() (μέθοδος της logging.handlers.SysLogHandler)
@anchor{library/logging handlers logging handlers SysLogHandler createSocket}@anchor{a4b}
@deffn {Μέθοδος} 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.


Added in version 3.11.

@end deffn

@geindex emit() (μέθοδος της logging.handlers.SysLogHandler)
@anchor{library/logging handlers logging handlers SysLogHandler emit}@anchor{3459}
@deffn {Μέθοδος} 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.


Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 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() (μέθοδος της logging.handlers.SysLogHandler)
@anchor{library/logging handlers logging handlers SysLogHandler encodePriority}@anchor{345a}
@deffn {Μέθοδος} 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 @code{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} or @code{critical}

@tab

LOG_CRIT

@item

@code{debug}

@tab

LOG_DEBUG

@item

@code{emerg} or @code{panic}

@tab

LOG_EMERG

@item

@code{err} or @code{error}

@tab

LOG_ERR

@item

@code{info}

@tab

LOG_INFO

@item

@code{notice}

@tab

LOG_NOTICE

@item

@code{warn} or @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() (μέθοδος της logging.handlers.SysLogHandler)
@anchor{library/logging handlers logging handlers SysLogHandler mapPriority}@anchor{345b}
@deffn {Μέθοδος} 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{345c}@anchor{library/logging handlers nteventloghandler}@anchor{345d}
@subsubsection NTEventLogHandler


The @ref{1985,,NTEventLogHandler} class, located in the @code{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 (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers NTEventLogHandler}@anchor{1985}
@deffn {Κλάση} logging.handlers.NTEventLogHandler (appname, dllname=None, logtype='Application')

Returns a new instance of the @code{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() (μέθοδος της logging.handlers.NTEventLogHandler)
@anchor{library/logging handlers logging handlers NTEventLogHandler close}@anchor{345e}
@deffn {Μέθοδος} 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() (μέθοδος της logging.handlers.NTEventLogHandler)
@anchor{library/logging handlers logging handlers NTEventLogHandler emit}@anchor{345f}
@deffn {Μέθοδος} 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() (μέθοδος της logging.handlers.NTEventLogHandler)
@anchor{library/logging handlers logging handlers NTEventLogHandler getEventCategory}@anchor{3460}
@deffn {Μέθοδος} 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() (μέθοδος της logging.handlers.NTEventLogHandler)
@anchor{library/logging handlers logging handlers NTEventLogHandler getEventType}@anchor{3461}
@deffn {Μέθοδος} 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() (μέθοδος της logging.handlers.NTEventLogHandler)
@anchor{library/logging handlers logging handlers NTEventLogHandler getMessageID}@anchor{3462}
@deffn {Μέθοδος} 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{3463}@anchor{library/logging handlers smtphandler}@anchor{3464}
@subsubsection SMTPHandler


The @ref{1ad3,,SMTPHandler} class, located in the @code{logging.handlers} module,
supports sending logging messages to an email address via SMTP.

@geindex SMTPHandler (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers SMTPHandler}@anchor{1ad3}
@deffn {Κλάση} logging.handlers.SMTPHandler (mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

Returns a new instance of the @code{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{14e4,,smtplib.SMTP.starttls()} method.)

A timeout can be specified for communication with the SMTP server using the
`timeout' argument.


Άλλαξε στην έκδοση 3.3: Added the `timeout' parameter.


@geindex emit() (μέθοδος της logging.handlers.SMTPHandler)
@anchor{library/logging handlers logging handlers SMTPHandler emit}@anchor{3465}
@deffn {Μέθοδος} emit (record)

Formats the record and sends it to the specified addressees.
@end deffn

@geindex getSubject() (μέθοδος της logging.handlers.SMTPHandler)
@anchor{library/logging handlers logging handlers SMTPHandler getSubject}@anchor{3466}
@deffn {Μέθοδος} 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{3467}@anchor{library/logging handlers memoryhandler}@anchor{3468}
@subsubsection MemoryHandler


The @ref{3417,,MemoryHandler} class, located in the @code{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{3417,,MemoryHandler} is a subclass of the more general
@ref{3469,,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 (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers BufferingHandler}@anchor{3469}
@deffn {Κλάση} 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() (μέθοδος της logging.handlers.BufferingHandler)
@anchor{library/logging handlers logging handlers BufferingHandler emit}@anchor{346a}
@deffn {Μέθοδος} emit (record)

Append the record to the buffer. If @ref{346b,,shouldFlush()} returns true,
call @ref{346c,,flush()} to process the buffer.
@end deffn

@geindex flush() (μέθοδος της logging.handlers.BufferingHandler)
@anchor{library/logging handlers logging handlers BufferingHandler flush}@anchor{346c}
@deffn {Μέθοδος} flush ()

For a @code{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() (μέθοδος της logging.handlers.BufferingHandler)
@anchor{library/logging handlers logging handlers BufferingHandler shouldFlush}@anchor{346b}
@deffn {Μέθοδος} 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 (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers MemoryHandler}@anchor{3417}
@deffn {Κλάση} logging.handlers.MemoryHandler (capacity, flushLevel=ERROR, target=None, flushOnClose=True)

Returns a new instance of the @code{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{346d,,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.


Άλλαξε στην έκδοση 3.6: The `flushOnClose' parameter was added.


@geindex close() (μέθοδος της logging.handlers.MemoryHandler)
@anchor{library/logging handlers logging handlers MemoryHandler close}@anchor{346e}
@deffn {Μέθοδος} close ()

Calls @ref{346f,,flush()}, sets the target to @code{None} and clears the
buffer.
@end deffn

@geindex flush() (μέθοδος της logging.handlers.MemoryHandler)
@anchor{library/logging handlers logging handlers MemoryHandler flush}@anchor{346f}
@deffn {Μέθοδος} flush ()

For a @code{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() (μέθοδος της logging.handlers.MemoryHandler)
@anchor{library/logging handlers logging handlers MemoryHandler setTarget}@anchor{346d}
@deffn {Μέθοδος} setTarget (target)

Sets the target handler for this handler.
@end deffn

@geindex shouldFlush() (μέθοδος της logging.handlers.MemoryHandler)
@anchor{library/logging handlers logging handlers MemoryHandler shouldFlush}@anchor{3470}
@deffn {Μέθοδος} 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{3471}@anchor{library/logging handlers httphandler}@anchor{3472}
@subsubsection HTTPHandler


The @ref{11df,,HTTPHandler} class, located in the @code{logging.handlers} module,
supports sending logging messages to a web server, using either @code{GET} or
@code{POST} semantics.

@geindex HTTPHandler (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers HTTPHandler}@anchor{11df}
@deffn {Κλάση} logging.handlers.HTTPHandler (host, url, method='GET', secure=False, credentials=None, context=None)

Returns a new instance of the @code{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{336,,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.


Άλλαξε στην έκδοση 3.5: The `context' parameter was added.


@geindex mapLogRecord() (μέθοδος της logging.handlers.HTTPHandler)
@anchor{library/logging handlers logging handlers HTTPHandler mapLogRecord}@anchor{3473}
@deffn {Μέθοδος} 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{138f,,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() (μέθοδος της logging.handlers.HTTPHandler)
@anchor{library/logging handlers logging handlers HTTPHandler emit}@anchor{3474}
@deffn {Μέθοδος} emit (record)

Sends the record to the web server as a URL-encoded dictionary. The
@ref{3473,,mapLogRecord()} method is used to convert the record to the
dictionary to be sent.
@end deffn

@cartouche
@quotation Σημείωση 
Since preparing a record for sending it to a web server is not
the same as a generic formatting operation, using
@ref{33c8,,setFormatter()} to specify a
@ref{1839,,Formatter} for a @code{HTTPHandler} has no effect.
Instead of calling @ref{33d1,,format()}, this handler calls
@ref{3473,,mapLogRecord()} and then @ref{1246,,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{3475}@anchor{library/logging handlers queuehandler}@anchor{3476}
@subsubsection QueueHandler



Added in version 3.2.


The @ref{1d5f,,QueueHandler} class, located in the @code{logging.handlers} module,
supports sending logging messages to a queue, such as those implemented in the
@ref{be,,queue} or @ref{98,,multiprocessing} modules.

Along with the @ref{4cf,,QueueListener} class, @ref{1d5f,,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{1ad3,,SMTPHandler}) are done on a separate thread.

@geindex QueueHandler (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers QueueHandler}@anchor{1d5f}
@deffn {Κλάση} logging.handlers.QueueHandler (queue)

Returns a new instance of the @code{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{3477,,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{f27,,SimpleQueue} instances for `queue'.

@cartouche
@quotation Σημείωση 
If you are using @ref{98,,multiprocessing}, you should avoid using
@ref{f27,,SimpleQueue} and instead use @ref{1d85,,multiprocessing.Queue}.
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
The @ref{98,,multiprocessing} module uses an internal logger created and
accessed via @ref{3478,,get_logger()}.
@ref{1d85,,multiprocessing.Queue} will log @code{DEBUG} level messages upon
items being queued. If those log messages are processed by a
@code{QueueHandler} using the same @code{multiprocessing.Queue} instance,
it will cause a deadlock or infinite recursion.
@end quotation
@end cartouche

@geindex emit() (μέθοδος της logging.handlers.QueueHandler)
@anchor{library/logging handlers logging handlers QueueHandler emit}@anchor{3479}
@deffn {Μέθοδος} emit (record)

Enqueues the result of preparing the LogRecord. Should an exception
occur (e.g. because a bounded queue has filled up), the
@ref{33cf,,handleError()} method is called to handle the
error. This can result in the record silently being dropped (if
@ref{15a2,,logging.raiseExceptions} is @code{False}) or a message printed to
@code{sys.stderr} (if @code{logging.raiseExceptions} is @code{True}).
@end deffn

@geindex prepare() (μέθοδος της logging.handlers.QueueHandler)
@anchor{library/logging handlers logging handlers QueueHandler prepare}@anchor{347a}
@deffn {Μέθοδος} 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{439,,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 Σημείωση 
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{4cf,,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() (μέθοδος της logging.handlers.QueueHandler)
@anchor{library/logging handlers logging handlers QueueHandler enqueue}@anchor{3477}
@deffn {Μέθοδος} 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 (ιδιότητα της logging.handlers.QueueHandler)
@anchor{library/logging handlers logging handlers QueueHandler listener}@anchor{341b}
@deffn {Ιδιότητα} listener

When created via configuration using @ref{1559,,dictConfig()}, this
attribute will contain a @ref{4cf,,QueueListener} instance for use with this
handler. Otherwise, it will be @code{None}.


Added in version 3.12.

@end deffn
@end deffn

@node QueueListener,,QueueHandler,logging handlers — Logging handlers
@anchor{library/logging handlers queue-listener}@anchor{347b}@anchor{library/logging handlers queuelistener}@anchor{347c}
@subsubsection QueueListener



Added in version 3.2.


The @ref{4cf,,QueueListener} class, located in the @code{logging.handlers}
module, supports receiving logging messages from a queue, such as those
implemented in the @ref{be,,queue} or @ref{98,,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
@code{QueueListener} is not itself a handler, it is documented here
because it works hand-in-hand with @ref{1d5f,,QueueHandler}.

Along with the @ref{1d5f,,QueueHandler} class, @ref{4cf,,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{1ad3,,SMTPHandler}) are done on a separate thread.

@geindex QueueListener (κλάση σε logging.handlers)
@anchor{library/logging handlers logging handlers QueueListener}@anchor{4cf}
@deffn {Κλάση} logging.handlers.QueueListener (queue, *handlers, respect_handler_level=False)

Returns a new instance of the @code{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{347d,,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{f27,,SimpleQueue} instances for `queue'.

@cartouche
@quotation Σημείωση 
If you are using @ref{98,,multiprocessing}, you should avoid using
@ref{f27,,SimpleQueue} and instead use @ref{1d85,,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.


Άλλαξε στην έκδοση 3.5: The @code{respect_handler_level} argument was added.



Άλλαξε στην έκδοση 3.14: @code{QueueListener} can now be used as a context manager via
@ref{20a,,with}. When entering the context, the listener is started. When
exiting the context, the listener is stopped.
@ref{28a4,,__enter__()} returns the
@code{QueueListener} object.


@geindex dequeue() (μέθοδος της logging.handlers.QueueListener)
@anchor{library/logging handlers logging handlers QueueListener dequeue}@anchor{347d}
@deffn {Μέθοδος} 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() (μέθοδος της logging.handlers.QueueListener)
@anchor{library/logging handlers logging handlers QueueListener prepare}@anchor{347e}
@deffn {Μέθοδος} 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() (μέθοδος της logging.handlers.QueueListener)
@anchor{library/logging handlers logging handlers QueueListener handle}@anchor{347f}
@deffn {Μέθοδος} 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{347e,,prepare()}.
@end deffn

@geindex start() (μέθοδος της logging.handlers.QueueListener)
@anchor{library/logging handlers logging handlers QueueListener start}@anchor{4d0}
@deffn {Μέθοδος} start ()

Starts the listener.

This starts up a background thread to monitor the queue for
LogRecords to process.


Άλλαξε στην έκδοση 3.14: Raises @ref{30d,,RuntimeError} if called and the listener is already
running.

@end deffn

@geindex stop() (μέθοδος της logging.handlers.QueueListener)
@anchor{library/logging handlers logging handlers QueueListener stop}@anchor{3480}
@deffn {Μέθοδος} 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() (μέθοδος της logging.handlers.QueueListener)
@anchor{library/logging handlers logging handlers QueueListener enqueue_sentinel}@anchor{3481}
@deffn {Μέθοδος} 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.


Added in version 3.3.

@end deffn
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{8a,,logging}

API reference for the logging module.

@item Module @ref{8b,,logging.config}

Configuration API for the logging module.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας,errno — Standard errno system symbols,logging handlers — Logging handlers,Generic Operating System Services
@anchor{library/platform doc}@anchor{3482}@anchor{library/platform module-platform}@anchor{af}@anchor{library/platform platform-access-to-underlying-platform-s-identifying-data}@anchor{3483}@anchor{library/platform translation-repo}@anchor{3484}
@subsection @code{platform} — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας


@geindex module; platform

`Πηγαίος κώδικας:' Lib/platform.py@footnote{https://github.com/python/cpython/tree/main/Lib/platform.py}


__________________________________________________________________


@cartouche
@quotation Σημείωση 
Συγκεκριμένες πλατφόρμες καταγεγραμμένες αλφαβητικά, με το Linux να περιλαμβάνεται στην ενότητα Unix.
@end quotation
@end cartouche

@menu
* Cross Platform:: 
* Πλατφόρμα Windows:: 
* Πλατφόρμα macOS:: 
* Πλατφόρμα iOS:: 
* Πλατφόρμες Unix:: 
* Πλατφόρμες Linux:: 
* Πλατφόρμα Android:: 
* Χρήση από γραμμή εντολών:: 

@end menu

@node Cross Platform,Πλατφόρμα Windows,,platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας
@anchor{library/platform cross-platform}@anchor{3485}
@subsubsection Cross Platform


@geindex architecture() (στη μονάδα platform)
@anchor{library/platform platform architecture}@anchor{1c0e}
@deffn {Συνάρτηση} platform.architecture (executable=sys.executable, bits='@w{'}, linkage='@w{'})

Υποβάλλει ερώτημα στο δεδομένο εκτελέσιμο αρχείο (προεπιλογή είναι το εκτελέσιμο του δυαδικού διερμηνέα Python) για διάφορες πληροφορίες αρχιτεκτονικής.

Επιστρέφει μια πλειάδα @code{(bits, linkage)} που περιέχει πληροφορίες για την αρχιτεκτονική των bit και την μορφή σύνδεσης που χρησιμοποιείται για το εκτελέσιμο αρχείο. Και οι δύο τιμές επιστρέφονται ως συμβολοσειρές.

Οι τιμές που δεν μπορούν να προσδιοριστούν επιστρέφονται όπως δίνονται από τις προκαθορισμένες παραμέτρους. Αν η τιμή του bits δοθεί ως @code{'@w{'}}, τότε χρησιμοποιείται το @code{sizeof(pointer)} (ή το @code{sizeof(long)} στην έκδοση Python < 1.5.2) ως δείκτης για το υποστηριζόμενο μέγεθος δεικτών.

Η συνάρτηση βασίζεται στην εντολή του συστήματος @code{file} για την εκτέλεση της πραγματικής εργασίας. Αυτή είναι διαθέσιμη στα περισσότερα αν όχι σε όλα τα συστήματα Unix και σε ορισμένα μη-Unix συστήματα, και μόνο αν το εκτελέσιμο δείχνει στον διερμηνέα της Python. Χρησιμοποιούνται εύλογες προεπιλεγμένες τιμές όταν οι παραπάνω προϋποθέσεις δεν πληρούνται.

@cartouche
@quotation Σημείωση 
Στο macOS (και ίσως και σε άλλες πλατφόρμες), τα εκτελέσιμα αρχεία μπορεί να είναι καθολικά αρχεία που περιέχουν μέσα πολλαπλές αρχιτεκτονικές.

Για να προσδιορίσετε αν ο τρέχων διερμηνέας είναι 64-bit, είναι πιο αξιόπιστο να ελέγξετε το χαρακτηριστικό @ref{156e,,sys.maxsize}:

@example
is_64bits = sys.maxsize > 2**32
@end example
@end quotation
@end cartouche
@end deffn

@geindex machine() (στη μονάδα platform)
@anchor{library/platform platform machine}@anchor{3486}
@deffn {Συνάρτηση} platform.machine ()

Επιστρέφει τον τύπο του μηχανήματος, π.χ. @code{'AMD64'}. Επιστρέφει μια κενή συμβολοσειρά αν η τιμή δεν μπορεί να προσδιοριστεί.

Η έξοδος εξαρτάται από την πλατφόρμα και μπορεί να διαφέρει ως προς τα κεφαλαία/πεζά και τις συμβάσεις ονοματοδοσίας.
@end deffn

@geindex node() (στη μονάδα platform)
@anchor{library/platform platform node}@anchor{3487}
@deffn {Συνάρτηση} platform.node ()

Επιστρέφει το όνομα δικτύου του υπολογιστή (ενδέχεται να μην είναι πλήρως καθορισμένο!). Επιστρέφει μια κενή συμβολοσειρά, αν η τιμή δεν μπορεί να προσδιοριστεί.
@end deffn

@geindex platform() (στη μονάδα platform)
@anchor{library/platform platform platform}@anchor{1cc7}
@deffn {Συνάρτηση} platform.platform (aliased=False, terse=False)

Επιστρέφει μια συμβολοσειρά που προσδιορίζει την υποκείμενη πλατφόρμα με όσο το δυνατόν περισσότερες χρήσιμες πληροφορίες.

Η έξοδος προορίζεται να είναι `φιλική - ευανάγνωστη από τον άνθρωπο' και όχι αναγνώσιμη από μηχανή. Μπορεί να φαίνεται διαφορετική σε διαφορετικές πλατφόρμες και αυτό είναι σκόπιμο.

Αν το `aliased' είναι αληθές, η συνάρτηση θα χρησιμοποιήσει ψευδώνυμα για διάφορες πλατφόρμες που αναφέρουν ονόματα συστημάτων διαφορετικά από τα κοινά τους ονόματα, για παράδειγμα το SunOS θα αναφέρεται ως Solaris. Η συνάρτηση @ref{3488,,system_alias()} χρησιμοποιείται για την υλοποίηση αυτού.

Αν το `terse' οριστεί σε αληθές, η συνάρτηση επιστρέφει μόνο τις απολύτως απαραίτητες πληροφορίες για την αναγνώριση της πλατφόρμας.


Άλλαξε στην έκδοση 3.8: Στο macOS, η συνάρτηση χρησιμοποιεί τώρα την @ref{2003,,mac_ver()}, αν αυτή επιστρέψει μη κενή συμβολοσειρά έκδοσης, για να λάβει την έκδοση του macOS αντί για την έκδοση Darwin.

@end deffn

@geindex processor() (στη μονάδα platform)
@anchor{library/platform platform processor}@anchor{3489}
@deffn {Συνάρτηση} platform.processor ()

Επιστρέφει το (πραγματικό) όνομα του επεξεργαστή, π.χ. @code{'amdk6'}.

Επιστρέφεται μια κενή συμβολοσειρά εάν η τιμή δεν μπορεί να προσδιοριστεί. Σημειώστε ότι πολλές πλατφόρμες δεν παρέχουν αυτή την πληροφορία ή απλώς επιστρέφουν την ίδια τιμή με αυτή της @ref{3486,,machine()}. Το NetBSD το κάνει αυτό.
@end deffn

@geindex python_build() (στη μονάδα platform)
@anchor{library/platform platform python_build}@anchor{348a}
@deffn {Συνάρτηση} platform.python_build ()

Επιστρέφει μια πλειάδα @code{(buildno, builddate)} που δηλώνει τον αριθμό κατασκευής και την ημερομηνία κατασκευής της Python ως συμβολοσειρές.
@end deffn

@geindex python_compiler() (στη μονάδα platform)
@anchor{library/platform platform python_compiler}@anchor{348b}
@deffn {Συνάρτηση} platform.python_compiler ()

Επιστρέφει μια συμβολοσειρά που προσδιορίζει τον μεταγλωττιστή που χρησιμοποιήθηκε για την μεταγλώττιση της Python.
@end deffn

@geindex python_branch() (στη μονάδα platform)
@anchor{library/platform platform python_branch}@anchor{348c}
@deffn {Συνάρτηση} platform.python_branch ()

Επιστρέφει μια συμβολοσειρά που προσδιορίζει το branch του συστήματος ελέγχου εκδόσεων (SCM) της υλοποίησης της Python.
@end deffn

@geindex python_implementation() (στη μονάδα platform)
@anchor{library/platform platform python_implementation}@anchor{348d}
@deffn {Συνάρτηση} platform.python_implementation ()

Επιστρέφει μια συμβολοσειρά που προσδιορίζει την υλοποίηση της Python. Πιθανές τιμές είναι: “CPython”, “IronPython”, “Jython”, “PyPy”.
@end deffn

@geindex python_revision() (στη μονάδα platform)
@anchor{library/platform platform python_revision}@anchor{348e}
@deffn {Συνάρτηση} platform.python_revision ()

Επιστρέφει μια συμβολοσειρά που προσδιορίζει την αναθεώρηση SCM της υλοποίησης της Python.
@end deffn

@geindex python_version() (στη μονάδα platform)
@anchor{library/platform platform python_version}@anchor{348f}
@deffn {Συνάρτηση} platform.python_version ()

Επιστρέφει την έκδοση της Python ως συμβολοσειρά @code{'major.minor.patchlevel'}.

Σημειώστε ότι σε αντίθεση με το @code{sys.version} της Python, η επιστρεφόμενη τιμή θα περιλαμβάνει πάντα το επίπεδο διόρθωσης (το οποίο προεπιλεγμένα είναι 0).
@end deffn

@geindex python_version_tuple() (στη μονάδα platform)
@anchor{library/platform platform python_version_tuple}@anchor{3490}
@deffn {Συνάρτηση} platform.python_version_tuple ()

Επιστρέφει την έκδοση της Python ως πλειάδα @code{(major, minor, patchlevel)} από συμβολοσειρές.

Σημειώστε ότι, σε αντίθεση με την @code{sys.version} της Python, η επιστρεφόμενη τιμή θα περιλαμβάνει πάντα το επίπεδο ενημέρωσης (με προεπιλογή το @code{'0'}).
@end deffn

@geindex release() (στη μονάδα platform)
@anchor{library/platform platform release}@anchor{3491}
@deffn {Συνάρτηση} platform.release ()

Επιστρέφει την έκδοση του συστήματος, π.χ. @code{'2.2.0'} ή @code{'NT'}. Επιστρέφεται μια κενή συμβολοσειρά αν η τιμή δεν μπορεί να καθοριστεί.
@end deffn

@geindex system() (στη μονάδα platform)
@anchor{library/platform platform system}@anchor{2458}
@deffn {Συνάρτηση} platform.system ()

Επιστρέφει το όνομα του συστήματος/λειτουργικού, όπως @code{'Linux'}, @code{'Darwin'}, @code{'Java'}, @code{'Windows'}. Επιστρέφεται μια κενή συμβολοσειρά αν η τιμή δεν μπορεί να καθοριστεί.

Στο iOS και το Android, αυτό επιστρέφει το όνομα του λειτουργικό συστήματος που βλέπει ο χρήστης δηλαδή, @code{'iOS}, @code{'iPadOS'} ή @code{'Android'}). Για να λάβετε το όνομα του πυρήνα (@code{'Darwin'} ή @code{'Linux'}), χρησιμοποιήστε τη @ref{14c2,,os.uname()}.
@end deffn

@geindex system_alias() (στη μονάδα platform)
@anchor{library/platform platform system_alias}@anchor{3488}
@deffn {Συνάρτηση} platform.system_alias (system, release, version)

Επιστρέφει μια πλειάδα @code{(system, release, version)} με ονόματα εμπορικής χρήσης που χρησιμοποιούνται για ορισμένα συστήματα. Επίσης, αναδιατάσσει ορισμένες πληροφορίες σε περιπτώσεις που διαφορετικά θα προκαλούσαν σύγχυση.
@end deffn

@geindex version() (στη μονάδα platform)
@anchor{library/platform platform version}@anchor{3492}
@deffn {Συνάρτηση} platform.version ()

Επιστρέφει την έκδοση κυκλοφορίας του συστήματος, π.χ. @code{'#3 on degas'}. Επιστρέφεται μια κενή συμβολοσειρά εάν η τιμή δεν μπορεί να προσδιοριστεί.

Στο iOS και το Android, αυτή είναι η έκδοση του λειτουργικό συστήματος που βλέπει ο χρήστης. Για να λάβετε την έκδοση του πυρήνα Darwin ή Linux, χρησιμοποιήστε τη @ref{14c2,,os.uname()}.
@end deffn

@geindex uname() (στη μονάδα platform)
@anchor{library/platform platform uname}@anchor{2001}
@deffn {Συνάρτηση} platform.uname ()

Αρκετά φορητή διεπαφή uname. Επιστρέφει ένα @ref{1cf,,namedtuple()} που περιέχει έξι ιδιότητες: @ref{2458,,system}, @ref{3487,,node}, @ref{3491,,release}, @ref{3492,,version}, @ref{3486,,machine} και @ref{3489,,processor}.

Το @ref{3489,,processor} επιλύεται αργά, κατόπιν αιτήματος.

Σημείωση: τα ονόματα των πρώτων δύο ιδιοτήτων διαφέρουν από αυτά που παρουσιάζονται από την συνάρτηση @ref{14c2,,os.uname()}, όπου ονομάζονται @code{sysname} και @code{nodename}.

Οι τιμές που δεν μπορούν να προσδιοριστούν ορίζονται σε @code{'@w{'}}.


Άλλαξε στην έκδοση 3.3: Το αποτέλεσμα άλλαξε από μια πλειάδα σε @ref{1cf,,namedtuple()}.



Άλλαξε στην έκδοση 3.9: Το @ref{3489,,processor} αναλύεται καθυστερημένα αντί άμεσα.

@end deffn

@geindex invalidate_caches() (στη μονάδα platform)
@anchor{library/platform platform invalidate_caches}@anchor{505}
@deffn {Συνάρτηση} platform.invalidate_caches ()

Καθαρίστε την εσωτερική μνήμη από πληροφορίες όπως τη @ref{2001,,uname()}. Αυτό είναι συνήθως χρήσιμο όταν η @ref{3487,,node()} της πλατφόρμας αλλάζει από μια εξωτερική διεργασία και κάποιος πρέπει να ανακτήσει την ενημερωμένη τιμή.


Added in version 3.14.

@end deffn

@node Πλατφόρμα Windows,Πλατφόρμα macOS,Cross Platform,platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας
@anchor{library/platform windows-platform}@anchor{3493}
@subsubsection Πλατφόρμα Windows


@geindex win32_ver() (στη μονάδα platform)
@anchor{library/platform platform win32_ver}@anchor{1f3e}
@deffn {Συνάρτηση} platform.win32_ver (release='@w{'}, version='@w{'}, csd='@w{'}, ptype='@w{'})

Λαμβάνει επιπλέον πληροφορίες έκδοσης από το Μητρώο των Windows και επιστρέφει μια πλειάδα @code{(release, version, csd, ptype)} που αναφέρεται στην έκδοση του λειτουργικού συστήματος, τον αριθμό έκδοσης, το επίπεδο CSD (service pack) και τον τύπο λειτουργικού συστήματος (πολυεπεξεργαστικό/μονοεπεξεργαστικό). Τιμές που δεν μπορούν να προσδιοριστούν ορίζονται στα προεπιλεγμένα που δίνονται ως παράμετροι (όλα προεπιλέγονται σε κενές συμβολοσειρές).

Ως υπόδειξη: το `ptype' είναι @code{'Uniprocessor Free'} σε μηχανές NT με έναν επεξεργαστή και @code{'Multiprocessor Free'} σε μηχανές με πολλαπλούς επεξεργαστές. Ο όρος `“Free”' αναφέρεται σε έκδοση του λειτουργικού συστήματος χωρίς κώδικα αποσφαλμάτωσης. Θα μπορούσε επίσης να αναφέρει `“Checked”' που σημαίνει ότι η έκδοση του λειτουργικού συστήματος χρησιμοποιεί κώδικα αποσφαλμάτωσης, δηλαδή κώδικα που ελέγχει ορίσματα, εύρη κ.λπ.
@end deffn

@geindex win32_edition() (στη μονάδα platform)
@anchor{library/platform platform win32_edition}@anchor{3494}
@deffn {Συνάρτηση} platform.win32_edition ()

Επιστρέφει μια συμβολοσειρά που αναπαριστά την τρέχουσα έκδοση των Windows ή @code{None} αν δεν μπορεί να καθοριστεί η τιμή. Πιθανές τιμές περιλαμβάνουν, αλλά δεν περιορίζονται σε @code{'Enterprise'}, @code{'IoTUAP'}, @code{'ServerStandard'} και @code{'nanoserver'}.


Added in version 3.8.

@end deffn

@geindex win32_is_iot() (στη μονάδα platform)
@anchor{library/platform platform win32_is_iot}@anchor{3495}
@deffn {Συνάρτηση} platform.win32_is_iot ()

Επιστρέφει @code{True} αν η έκδοση των Windows που επιστρέφεται από την @ref{3494,,win32_edition()} αναγνωρίζεται ως έκδοση IoT.


Added in version 3.8.

@end deffn

@node Πλατφόρμα macOS,Πλατφόρμα iOS,Πλατφόρμα Windows,platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας
@anchor{library/platform macos-platform}@anchor{3496}
@subsubsection Πλατφόρμα macOS


@geindex mac_ver() (στη μονάδα platform)
@anchor{library/platform platform mac_ver}@anchor{2003}
@deffn {Συνάρτηση} platform.mac_ver (release='@w{'}, versioninfo=('@w{'}, '@w{'}, '@w{'}), machine='@w{'})

Λαμβάνει πληροφορίες έκδοσης macOS και τις επιστρέφει ως πλειάδα @code{(release, versioninfo, machine)} όπου το `versioninfo' είναι μια πλειάδα @code{(version, dev_stage, non_release_version)}.

Οι τιμές που δεν μπορούν να προσδιοριστούν ορίζονται ως @code{'@w{'}}. Όλα τα στοιχεία της πλειάδας είναι συμβολοσειρές.
@end deffn

@node Πλατφόρμα iOS,Πλατφόρμες Unix,Πλατφόρμα macOS,platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας
@anchor{library/platform ios-platform}@anchor{3497}
@subsubsection Πλατφόρμα iOS


@geindex ios_ver() (στη μονάδα platform)
@anchor{library/platform platform ios_ver}@anchor{2457}
@deffn {Συνάρτηση} platform.ios_ver (system='@w{'}, release='@w{'}, model='@w{'}, is_simulator=False)

Λάβετε πληροφορίες για την έκδοση του iOS και επιστρέψτε τις ως μια @ref{1cf,,namedtuple()} με τα εξής χαρακτηριστικά:


@itemize *

@item 
@code{system} είναι το όνομα του λειτουργικού συστήματος; είτε @code{'iOS'} ή @code{'iPadOS'}.

@item 
@code{release} είναι ο αριθμός έκδοσης iOS ως μια συμβολοσειρά (π.χ., @code{'17.2'}).

@item 
Το @code{model} είναι ο αναγνωριστικό αριθμός μοντέλου της συσκευής. Αυτό θα είναι μια συμβολοσειρά όπως @code{'iPhone13,2'} για μια φυσική συσκευή, ή @code{'iPhone'} για έναν εξομοιωτή.

@item 
Το @code{is_simulator} είναι μια δυαδική τιμή που περιγράφει αν η εφαρμογή εκτελείται σε εξομοιωτή ή σε φυσική συσκευή.
@end itemize

Οι καταχωρήσεις που δεν μπορούν να προσδιοριστούν ορίζονται στις προεπιλεγμένες τιμές που δίνονται ως παράμετροι.
@end deffn

@node Πλατφόρμες Unix,Πλατφόρμες Linux,Πλατφόρμα iOS,platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας
@anchor{library/platform unix-platforms}@anchor{3498}
@subsubsection Πλατφόρμες Unix


@geindex libc_ver() (στη μονάδα platform)
@anchor{library/platform platform libc_ver}@anchor{1a01}
@deffn {Συνάρτηση} platform.libc_ver (executable=sys.executable, lib='@w{'}, version='@w{'}, chunksize=16384)

Προσπαθεί να προσδιορίσει την έκδοση της libc με την οποία είναι συνδεδεμένο το εκτελέσιμο αρχείο (προεπιλογή είναι ο διερμηνέας της Python). Επιστρέφει μια πλειάδα συμβολοσειρών @code{(lib, version)}, η οποία ορίζεται στις δοθείσες παραμέτρους σε περίπτωση αποτυχίας της αναζήτησης.

Σημειώστε ότι αυτή η συνάρτηση έχει λεπτομερή γνώση του τρόπου με τον οποίο οι διάφορες εκδόσεις της libc προσθέτουν σύμβολα στο εκτελέσιμο και πιθανώς μπορεί να χρησιμοποιηθεί μόνο για εκτελέσιμα που έχουν μεταγλωττιστεί με το @code{gcc}.

Το αρχείο διαβάζεται και σαρώνονται τμήματά του μεγέθους `chunksize' bytes.
@end deffn

@node Πλατφόρμες Linux,Πλατφόρμα Android,Πλατφόρμες Unix,platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας
@anchor{library/platform linux-platforms}@anchor{3499}
@subsubsection Πλατφόρμες Linux


@geindex freedesktop_os_release() (στη μονάδα platform)
@anchor{library/platform platform freedesktop_os_release}@anchor{bff}
@deffn {Συνάρτηση} platform.freedesktop_os_release ()

Λαμβάνει την ταυτότητα του λειτουργικού συστήματος από το αρχείο @code{os-release} και την επιστρέφει ως λεξικό. Το αρχείο @code{os-release} είναι ένα πρότυπο του freedesktop.org@footnote{https://www.freedesktop.org/software/systemd/man/os-release.html} και είναι διαθέσιμο στις περισσότερες διανομές Linux. Μια αξιοσημείωτη εξαίρεση είναι το Android και οι διανομές που βασίζονται σε Android.

Κάνει raise εξαίρεση @ref{53c,,OSError} ή την υποκλάση όταν δεν είναι δυνατή η ανάγνωση ούτε του @code{/etc/os-release} ούτε του @code{/usr/lib/os-release}.

Σε περίπτωση επιτυχίας, η συνάρτηση επιστρέφει ένα λεξικό όπου τα κλειδιά και οι τιμές είναι συμβολοσειρές. Οι τιμές έχουν τους ειδικούς χαρακτήρες του, όπως @code{"} και @code{$}, χωρίς εισαγωγικά. Τα πεδία @code{NAME}, @code{ID} και @code{PRETTY_NAME} ορίζονται πάντα σύμφωνα με το πρότυπο. Όλα τα άλλα πεδία είναι προαιρετικά. Οι προμηθευτές μπορεί να περιλαμβάνουν πρόσθετα πεδία.

Σημειώστε ότι πεδία όπως τα @code{NAME}, @code{VERSION} και @code{VARIANT} είναι συμβολοσειρές κατάλληλες για παρουσίαση στους χρήστες. Τα προγράμματα θα πρέπει να χρησιμοποιούν πεδία όπως τα @code{ID}, @code{ID_LIKE}, @code{VERSION_ID} ή @code{VARIANT_ID} για την αναγνώριση διανομών Linux.

Παράδειγμα:

@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


Added in version 3.10.

@end deffn

@node Πλατφόρμα Android,Χρήση από γραμμή εντολών,Πλατφόρμες Linux,platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας
@anchor{library/platform android-platform}@anchor{349a}
@subsubsection Πλατφόρμα Android


@geindex android_ver() (στη μονάδα platform)
@anchor{library/platform platform android_ver}@anchor{1bd0}
@deffn {Συνάρτηση} platform.android_ver (release='@w{'}, api_level=0, manufacturer='@w{'}, model='@w{'}, device='@w{'}, is_emulator=False)

Λάβετε πληροφορίες για τη συσκευή Android. Επιστρέφει μια @ref{1cf,,namedtuple()} με τα εξής χαρακτηριστικά. Οι τιμές που δεν μπορούν να προσδιοριστούν ορίζονται στις προεπιλεγμένες τιμές που δίνονται ως παράμετροι.


@itemize *

@item 
@code{release} - Η έκδοση του Android, ως συμβολοσειρά (π.χ. @code{"14"}).

@item 
@code{api_level} - Το επίπεδο API της εκτελούμενης συσκευής, ως ακέραιος αριθμός (π.χ. @code{34} για Android 14). Για να λάβετε το επίπεδο API με το οποίο έχει κατασκευαστεί η Python, δείτε τη @ref{f49,,sys.getandroidapilevel()}.

@item 
@code{manufacturer} - Το όνομα του κατασκευαστή@footnote{https://developer.android.com/reference/android/os/Build#MANUFACTURER}.

@item 
@code{model} - Το όνομα του μοντέλου@footnote{https://developer.android.com/reference/android/os/Build#MODEL} – συνήθως το εμπορικό όνομα ή ο αριθμός μοντέλου.

@item 
@code{device} - Το όνομα της συσκευής@footnote{https://developer.android.com/reference/android/os/Build#DEVICE} – συνήθως ο αριθμός μοντέλου ή ένα κωδικό όνομα.

@item 
@code{is_emulator} - @code{True} αν η συσκευή είναι εξομοιωτής; @code{False} αν είναι φυσική συσκευή.
@end itemize

Η Google διατηρεί μια λίστα με γνωστά ονόματα μοντέλων συσκευών@footnote{https://storage.googleapis.com/play_public/supported_devices.html}.


Added in version 3.13.

@end deffn

@node Χρήση από γραμμή εντολών,,Πλατφόρμα Android,platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας
@anchor{library/platform command-line-usage}@anchor{349b}@anchor{library/platform platform-cli}@anchor{349c}
@subsubsection Χρήση από γραμμή εντολών


@code{platform} can also be invoked directly using the @ref{4ca,,-m}
switch of the interpreter:

@example
python -m platform [--terse] [--nonaliased] [@{nonaliased,terse@} ...]
@end example

Οι εξής επιλογές γίνονται αποδεκτές:

@geindex platform command line option; --terse
@anchor{library/platform cmdoption-platform-terse}@anchor{349d}
@deffn {Option} @w{-}@w{-}terse

Εκτυπώνει συνοπτικές πληροφορίες για την πλατφόρμα. Αυτό είναι ισοδύναμο με την κλήση @ref{1cc7,,platform.platform()} με το όρισμα `terse' ορισμένο σε @code{True}.
@end deffn

@geindex platform command line option; --nonaliased
@anchor{library/platform cmdoption-platform-nonaliased}@anchor{349e}
@deffn {Option} @w{-}@w{-}nonaliased

Εκτυπώνει πληροφορίες για την πλατφόρμα χωρίς την αντικατάσταση του ονόματος του συστήματος/ λειτουργικού. Αυτό είναι ισοδύναμο με την κλήση της @ref{1cc7,,platform.platform()} με το όρισμα `aliased' ορισμένο σε @code{True}.
@end deffn

Μπορείτε επίσης να περάσετε ένα ή περισσότερα ορίσματα θέσης (@code{terse}, @code{nonaliased}) για να ελέγξετε ρητά τη μορφή της εξόδου. Αυτά συμπεριφέρονται όπως οι αντίστοιχες επιλογές τους.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node errno — Standard errno system symbols,ctypes — A foreign function library for Python,platform — Πρόσβαση στα αναγνωριστικά δεδομένα της υποκείμενης πλατφόρμας,Generic Operating System Services
@anchor{library/errno doc}@anchor{349f}@anchor{library/errno errno-standard-errno-system-symbols}@anchor{34a0}@anchor{library/errno module-errno}@anchor{5a}@anchor{library/errno translation-repo}@anchor{34a1}
@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 (στη μονάδα errno)
@anchor{library/errno errno errorcode}@anchor{34a2}
@deffn {Δεδομένα} errno.errorcode

Dictionary providing a mapping from the errno value to the string name in the
underlying system.  For instance, @code{errno.errorcode[errno.EPERM]} maps to
@code{'EPERM'}.
@end deffn

To translate a numeric error code to an error message, use @ref{3249,,os.strerror()}.

Of the following list, symbols that are not used on the current platform are not
defined by the module.  The specific list of defined symbols is available as
@code{errno.errorcode.keys()}.  Symbols available can include:

@geindex EPERM (στη μονάδα errno)
@anchor{library/errno errno EPERM}@anchor{1d54}
@deffn {Δεδομένα} errno.EPERM

Operation not permitted. This error is mapped to the exception
@ref{10f9,,PermissionError}.
@end deffn

@geindex ENOENT (στη μονάδα errno)
@anchor{library/errno errno ENOENT}@anchor{2905}
@deffn {Δεδομένα} errno.ENOENT

No such file or directory. This error is mapped to the exception
@ref{243,,FileNotFoundError}.
@end deffn

@geindex ESRCH (στη μονάδα errno)
@anchor{library/errno errno ESRCH}@anchor{2909}
@deffn {Δεδομένα} errno.ESRCH

No such process. This error is mapped to the exception
@ref{1403,,ProcessLookupError}.
@end deffn

@geindex EINTR (στη μονάδα errno)
@anchor{library/errno errno EINTR}@anchor{1140}
@deffn {Δεδομένα} errno.EINTR

Interrupted system call. This error is mapped to the exception
@ref{1141,,InterruptedError}.
@end deffn

@geindex EIO (στη μονάδα errno)
@anchor{library/errno errno EIO}@anchor{34a3}
@deffn {Δεδομένα} errno.EIO

I/O error
@end deffn

@geindex ENXIO (στη μονάδα errno)
@anchor{library/errno errno ENXIO}@anchor{34a4}
@deffn {Δεδομένα} errno.ENXIO

No such device or address
@end deffn

@geindex E2BIG (στη μονάδα errno)
@anchor{library/errno errno E2BIG}@anchor{34a5}
@deffn {Δεδομένα} errno.E2BIG

Arg list too long
@end deffn

@geindex ENOEXEC (στη μονάδα errno)
@anchor{library/errno errno ENOEXEC}@anchor{34a6}
@deffn {Δεδομένα} errno.ENOEXEC

Exec format error
@end deffn

@geindex EBADF (στη μονάδα errno)
@anchor{library/errno errno EBADF}@anchor{d25}
@deffn {Δεδομένα} errno.EBADF

Bad file number
@end deffn

@geindex ECHILD (στη μονάδα errno)
@anchor{library/errno errno ECHILD}@anchor{28fe}
@deffn {Δεδομένα} errno.ECHILD

No child processes. This error is mapped to the exception
@ref{1400,,ChildProcessError}.
@end deffn

@geindex EAGAIN (στη μονάδα errno)
@anchor{library/errno errno EAGAIN}@anchor{28f9}
@deffn {Δεδομένα} errno.EAGAIN

Try again. This error is mapped to the exception @ref{4c3,,BlockingIOError}.
@end deffn

@geindex ENOMEM (στη μονάδα errno)
@anchor{library/errno errno ENOMEM}@anchor{34a7}
@deffn {Δεδομένα} errno.ENOMEM

Out of memory
@end deffn

@geindex EACCES (στη μονάδα errno)
@anchor{library/errno errno EACCES}@anchor{2908}
@deffn {Δεδομένα} errno.EACCES

Permission denied.  This error is mapped to the exception
@ref{10f9,,PermissionError}.
@end deffn

@geindex EFAULT (στη μονάδα errno)
@anchor{library/errno errno EFAULT}@anchor{34a8}
@deffn {Δεδομένα} errno.EFAULT

Bad address
@end deffn

@geindex ENOTBLK (στη μονάδα errno)
@anchor{library/errno errno ENOTBLK}@anchor{34a9}
@deffn {Δεδομένα} errno.ENOTBLK

Block device required
@end deffn

@geindex EBUSY (στη μονάδα errno)
@anchor{library/errno errno EBUSY}@anchor{34aa}
@deffn {Δεδομένα} errno.EBUSY

Device or resource busy
@end deffn

@geindex EEXIST (στη μονάδα errno)
@anchor{library/errno errno EEXIST}@anchor{2904}
@deffn {Δεδομένα} errno.EEXIST

File exists. This error is mapped to the exception
@ref{13c9,,FileExistsError}.
@end deffn

@geindex EXDEV (στη μονάδα errno)
@anchor{library/errno errno EXDEV}@anchor{325f}
@deffn {Δεδομένα} errno.EXDEV

Cross-device link
@end deffn

@geindex ENODEV (στη μονάδα errno)
@anchor{library/errno errno ENODEV}@anchor{34ab}
@deffn {Δεδομένα} errno.ENODEV

No such device
@end deffn

@geindex ENOTDIR (στη μονάδα errno)
@anchor{library/errno errno ENOTDIR}@anchor{2907}
@deffn {Δεδομένα} errno.ENOTDIR

Not a directory. This error is mapped to the exception
@ref{1402,,NotADirectoryError}.
@end deffn

@geindex EISDIR (στη μονάδα errno)
@anchor{library/errno errno EISDIR}@anchor{2906}
@deffn {Δεδομένα} errno.EISDIR

Is a directory. This error is mapped to the exception
@ref{1401,,IsADirectoryError}.
@end deffn

@geindex EINVAL (στη μονάδα errno)
@anchor{library/errno errno EINVAL}@anchor{1fc1}
@deffn {Δεδομένα} errno.EINVAL

Invalid argument
@end deffn

@geindex ENFILE (στη μονάδα errno)
@anchor{library/errno errno ENFILE}@anchor{34ac}
@deffn {Δεδομένα} errno.ENFILE

File table overflow
@end deffn

@geindex EMFILE (στη μονάδα errno)
@anchor{library/errno errno EMFILE}@anchor{34ad}
@deffn {Δεδομένα} errno.EMFILE

Too many open files
@end deffn

@geindex ENOTTY (στη μονάδα errno)
@anchor{library/errno errno ENOTTY}@anchor{34ae}
@deffn {Δεδομένα} errno.ENOTTY

Not a typewriter
@end deffn

@geindex ETXTBSY (στη μονάδα errno)
@anchor{library/errno errno ETXTBSY}@anchor{34af}
@deffn {Δεδομένα} errno.ETXTBSY

Text file busy
@end deffn

@geindex EFBIG (στη μονάδα errno)
@anchor{library/errno errno EFBIG}@anchor{34b0}
@deffn {Δεδομένα} errno.EFBIG

File too large
@end deffn

@geindex ENOSPC (στη μονάδα errno)
@anchor{library/errno errno ENOSPC}@anchor{34b1}
@deffn {Δεδομένα} errno.ENOSPC

No space left on device
@end deffn

@geindex ESPIPE (στη μονάδα errno)
@anchor{library/errno errno ESPIPE}@anchor{34b2}
@deffn {Δεδομένα} errno.ESPIPE

Illegal seek
@end deffn

@geindex EROFS (στη μονάδα errno)
@anchor{library/errno errno EROFS}@anchor{34b3}
@deffn {Δεδομένα} errno.EROFS

Read-only file system
@end deffn

@geindex EMLINK (στη μονάδα errno)
@anchor{library/errno errno EMLINK}@anchor{34b4}
@deffn {Δεδομένα} errno.EMLINK

Too many links
@end deffn

@geindex EPIPE (στη μονάδα errno)
@anchor{library/errno errno EPIPE}@anchor{28ff}
@deffn {Δεδομένα} errno.EPIPE

Broken pipe. This error is mapped to the exception
@ref{1404,,BrokenPipeError}.
@end deffn

@geindex EDOM (στη μονάδα errno)
@anchor{library/errno errno EDOM}@anchor{34b5}
@deffn {Δεδομένα} errno.EDOM

Math argument out of domain of func
@end deffn

@geindex ERANGE (στη μονάδα errno)
@anchor{library/errno errno ERANGE}@anchor{34b6}
@deffn {Δεδομένα} errno.ERANGE

Math result not representable
@end deffn

@geindex EDEADLK (στη μονάδα errno)
@anchor{library/errno errno EDEADLK}@anchor{34b7}
@deffn {Δεδομένα} errno.EDEADLK

Resource deadlock would occur
@end deffn

@geindex ENAMETOOLONG (στη μονάδα errno)
@anchor{library/errno errno ENAMETOOLONG}@anchor{34b8}
@deffn {Δεδομένα} errno.ENAMETOOLONG

File name too long
@end deffn

@geindex ENOLCK (στη μονάδα errno)
@anchor{library/errno errno ENOLCK}@anchor{34b9}
@deffn {Δεδομένα} errno.ENOLCK

No record locks available
@end deffn

@geindex ENOSYS (στη μονάδα errno)
@anchor{library/errno errno ENOSYS}@anchor{1d55}
@deffn {Δεδομένα} errno.ENOSYS

Function not implemented
@end deffn

@geindex ENOTEMPTY (στη μονάδα errno)
@anchor{library/errno errno ENOTEMPTY}@anchor{34ba}
@deffn {Δεδομένα} errno.ENOTEMPTY

Directory not empty
@end deffn

@geindex ELOOP (στη μονάδα errno)
@anchor{library/errno errno ELOOP}@anchor{34bb}
@deffn {Δεδομένα} errno.ELOOP

Too many symbolic links encountered
@end deffn

@geindex EWOULDBLOCK (στη μονάδα errno)
@anchor{library/errno errno EWOULDBLOCK}@anchor{28fb}
@deffn {Δεδομένα} errno.EWOULDBLOCK

Operation would block. This error is mapped to the exception
@ref{4c3,,BlockingIOError}.
@end deffn

@geindex ENOMSG (στη μονάδα errno)
@anchor{library/errno errno ENOMSG}@anchor{34bc}
@deffn {Δεδομένα} errno.ENOMSG

No message of desired type
@end deffn

@geindex EIDRM (στη μονάδα errno)
@anchor{library/errno errno EIDRM}@anchor{34bd}
@deffn {Δεδομένα} errno.EIDRM

Identifier removed
@end deffn

@geindex ECHRNG (στη μονάδα errno)
@anchor{library/errno errno ECHRNG}@anchor{34be}
@deffn {Δεδομένα} errno.ECHRNG

Channel number out of range
@end deffn

@geindex EL2NSYNC (στη μονάδα errno)
@anchor{library/errno errno EL2NSYNC}@anchor{34bf}
@deffn {Δεδομένα} errno.EL2NSYNC

Level 2 not synchronized
@end deffn

@geindex EL3HLT (στη μονάδα errno)
@anchor{library/errno errno EL3HLT}@anchor{34c0}
@deffn {Δεδομένα} errno.EL3HLT

Level 3 halted
@end deffn

@geindex EL3RST (στη μονάδα errno)
@anchor{library/errno errno EL3RST}@anchor{34c1}
@deffn {Δεδομένα} errno.EL3RST

Level 3 reset
@end deffn

@geindex ELNRNG (στη μονάδα errno)
@anchor{library/errno errno ELNRNG}@anchor{34c2}
@deffn {Δεδομένα} errno.ELNRNG

Link number out of range
@end deffn

@geindex EUNATCH (στη μονάδα errno)
@anchor{library/errno errno EUNATCH}@anchor{34c3}
@deffn {Δεδομένα} errno.EUNATCH

Protocol driver not attached
@end deffn

@geindex ENOCSI (στη μονάδα errno)
@anchor{library/errno errno ENOCSI}@anchor{34c4}
@deffn {Δεδομένα} errno.ENOCSI

No CSI structure available
@end deffn

@geindex EL2HLT (στη μονάδα errno)
@anchor{library/errno errno EL2HLT}@anchor{34c5}
@deffn {Δεδομένα} errno.EL2HLT

Level 2 halted
@end deffn

@geindex EBADE (στη μονάδα errno)
@anchor{library/errno errno EBADE}@anchor{34c6}
@deffn {Δεδομένα} errno.EBADE

Invalid exchange
@end deffn

@geindex EBADR (στη μονάδα errno)
@anchor{library/errno errno EBADR}@anchor{34c7}
@deffn {Δεδομένα} errno.EBADR

Invalid request descriptor
@end deffn

@geindex EXFULL (στη μονάδα errno)
@anchor{library/errno errno EXFULL}@anchor{34c8}
@deffn {Δεδομένα} errno.EXFULL

Exchange full
@end deffn

@geindex ENOANO (στη μονάδα errno)
@anchor{library/errno errno ENOANO}@anchor{34c9}
@deffn {Δεδομένα} errno.ENOANO

No anode
@end deffn

@geindex EBADRQC (στη μονάδα errno)
@anchor{library/errno errno EBADRQC}@anchor{34ca}
@deffn {Δεδομένα} errno.EBADRQC

Invalid request code
@end deffn

@geindex EBADSLT (στη μονάδα errno)
@anchor{library/errno errno EBADSLT}@anchor{34cb}
@deffn {Δεδομένα} errno.EBADSLT

Invalid slot
@end deffn

@geindex EDEADLOCK (στη μονάδα errno)
@anchor{library/errno errno EDEADLOCK}@anchor{34cc}
@deffn {Δεδομένα} errno.EDEADLOCK

File locking deadlock error
@end deffn

@geindex EBFONT (στη μονάδα errno)
@anchor{library/errno errno EBFONT}@anchor{34cd}
@deffn {Δεδομένα} errno.EBFONT

Bad font file format
@end deffn

@geindex ENOSTR (στη μονάδα errno)
@anchor{library/errno errno ENOSTR}@anchor{34ce}
@deffn {Δεδομένα} errno.ENOSTR

Device not a stream
@end deffn

@geindex ENODATA (στη μονάδα errno)
@anchor{library/errno errno ENODATA}@anchor{34cf}
@deffn {Δεδομένα} errno.ENODATA

No data available
@end deffn

@geindex ETIME (στη μονάδα errno)
@anchor{library/errno errno ETIME}@anchor{34d0}
@deffn {Δεδομένα} errno.ETIME

Timer expired
@end deffn

@geindex ENOSR (στη μονάδα errno)
@anchor{library/errno errno ENOSR}@anchor{34d1}
@deffn {Δεδομένα} errno.ENOSR

Out of streams resources
@end deffn

@geindex ENONET (στη μονάδα errno)
@anchor{library/errno errno ENONET}@anchor{34d2}
@deffn {Δεδομένα} errno.ENONET

Machine is not on the network
@end deffn

@geindex ENOPKG (στη μονάδα errno)
@anchor{library/errno errno ENOPKG}@anchor{34d3}
@deffn {Δεδομένα} errno.ENOPKG

Package not installed
@end deffn

@geindex EREMOTE (στη μονάδα errno)
@anchor{library/errno errno EREMOTE}@anchor{34d4}
@deffn {Δεδομένα} errno.EREMOTE

Object is remote
@end deffn

@geindex ENOLINK (στη μονάδα errno)
@anchor{library/errno errno ENOLINK}@anchor{34d5}
@deffn {Δεδομένα} errno.ENOLINK

Link has been severed
@end deffn

@geindex EADV (στη μονάδα errno)
@anchor{library/errno errno EADV}@anchor{34d6}
@deffn {Δεδομένα} errno.EADV

Advertise error
@end deffn

@geindex ESRMNT (στη μονάδα errno)
@anchor{library/errno errno ESRMNT}@anchor{34d7}
@deffn {Δεδομένα} errno.ESRMNT

Srmount error
@end deffn

@geindex ECOMM (στη μονάδα errno)
@anchor{library/errno errno ECOMM}@anchor{34d8}
@deffn {Δεδομένα} errno.ECOMM

Communication error on send
@end deffn

@geindex EPROTO (στη μονάδα errno)
@anchor{library/errno errno EPROTO}@anchor{34d9}
@deffn {Δεδομένα} errno.EPROTO

Protocol error
@end deffn

@geindex EMULTIHOP (στη μονάδα errno)
@anchor{library/errno errno EMULTIHOP}@anchor{34da}
@deffn {Δεδομένα} errno.EMULTIHOP

Multihop attempted
@end deffn

@geindex EDOTDOT (στη μονάδα errno)
@anchor{library/errno errno EDOTDOT}@anchor{34db}
@deffn {Δεδομένα} errno.EDOTDOT

RFS specific error
@end deffn

@geindex EBADMSG (στη μονάδα errno)
@anchor{library/errno errno EBADMSG}@anchor{34dc}
@deffn {Δεδομένα} errno.EBADMSG

Not a data message
@end deffn

@geindex EOVERFLOW (στη μονάδα errno)
@anchor{library/errno errno EOVERFLOW}@anchor{34dd}
@deffn {Δεδομένα} errno.EOVERFLOW

Value too large for defined data type
@end deffn

@geindex ENOTUNIQ (στη μονάδα errno)
@anchor{library/errno errno ENOTUNIQ}@anchor{34de}
@deffn {Δεδομένα} errno.ENOTUNIQ

Name not unique on network
@end deffn

@geindex EBADFD (στη μονάδα errno)
@anchor{library/errno errno EBADFD}@anchor{34df}
@deffn {Δεδομένα} errno.EBADFD

File descriptor in bad state
@end deffn

@geindex EREMCHG (στη μονάδα errno)
@anchor{library/errno errno EREMCHG}@anchor{34e0}
@deffn {Δεδομένα} errno.EREMCHG

Remote address changed
@end deffn

@geindex ELIBACC (στη μονάδα errno)
@anchor{library/errno errno ELIBACC}@anchor{34e1}
@deffn {Δεδομένα} errno.ELIBACC

Can not access a needed shared library
@end deffn

@geindex ELIBBAD (στη μονάδα errno)
@anchor{library/errno errno ELIBBAD}@anchor{34e2}
@deffn {Δεδομένα} errno.ELIBBAD

Accessing a corrupted shared library
@end deffn

@geindex ELIBSCN (στη μονάδα errno)
@anchor{library/errno errno ELIBSCN}@anchor{34e3}
@deffn {Δεδομένα} errno.ELIBSCN

.lib section in a.out corrupted
@end deffn

@geindex ELIBMAX (στη μονάδα errno)
@anchor{library/errno errno ELIBMAX}@anchor{34e4}
@deffn {Δεδομένα} errno.ELIBMAX

Attempting to link in too many shared libraries
@end deffn

@geindex ELIBEXEC (στη μονάδα errno)
@anchor{library/errno errno ELIBEXEC}@anchor{34e5}
@deffn {Δεδομένα} errno.ELIBEXEC

Cannot exec a shared library directly
@end deffn

@geindex EILSEQ (στη μονάδα errno)
@anchor{library/errno errno EILSEQ}@anchor{34e6}
@deffn {Δεδομένα} errno.EILSEQ

Illegal byte sequence
@end deffn

@geindex ERESTART (στη μονάδα errno)
@anchor{library/errno errno ERESTART}@anchor{34e7}
@deffn {Δεδομένα} errno.ERESTART

Interrupted system call should be restarted
@end deffn

@geindex ESTRPIPE (στη μονάδα errno)
@anchor{library/errno errno ESTRPIPE}@anchor{34e8}
@deffn {Δεδομένα} errno.ESTRPIPE

Streams pipe error
@end deffn

@geindex EUSERS (στη μονάδα errno)
@anchor{library/errno errno EUSERS}@anchor{34e9}
@deffn {Δεδομένα} errno.EUSERS

Too many users
@end deffn

@geindex ENOTSOCK (στη μονάδα errno)
@anchor{library/errno errno ENOTSOCK}@anchor{34ea}
@deffn {Δεδομένα} errno.ENOTSOCK

Socket operation on non-socket
@end deffn

@geindex EDESTADDRREQ (στη μονάδα errno)
@anchor{library/errno errno EDESTADDRREQ}@anchor{34eb}
@deffn {Δεδομένα} errno.EDESTADDRREQ

Destination address required
@end deffn

@geindex EMSGSIZE (στη μονάδα errno)
@anchor{library/errno errno EMSGSIZE}@anchor{34ec}
@deffn {Δεδομένα} errno.EMSGSIZE

Message too long
@end deffn

@geindex EPROTOTYPE (στη μονάδα errno)
@anchor{library/errno errno EPROTOTYPE}@anchor{34ed}
@deffn {Δεδομένα} errno.EPROTOTYPE

Protocol wrong type for socket
@end deffn

@geindex ENOPROTOOPT (στη μονάδα errno)
@anchor{library/errno errno ENOPROTOOPT}@anchor{34ee}
@deffn {Δεδομένα} errno.ENOPROTOOPT

Protocol not available
@end deffn

@geindex EPROTONOSUPPORT (στη μονάδα errno)
@anchor{library/errno errno EPROTONOSUPPORT}@anchor{34ef}
@deffn {Δεδομένα} errno.EPROTONOSUPPORT

Protocol not supported
@end deffn

@geindex ESOCKTNOSUPPORT (στη μονάδα errno)
@anchor{library/errno errno ESOCKTNOSUPPORT}@anchor{34f0}
@deffn {Δεδομένα} errno.ESOCKTNOSUPPORT

Socket type not supported
@end deffn

@geindex EOPNOTSUPP (στη μονάδα errno)
@anchor{library/errno errno EOPNOTSUPP}@anchor{34f1}
@deffn {Δεδομένα} errno.EOPNOTSUPP

Operation not supported on transport endpoint
@end deffn

@geindex ENOTSUP (στη μονάδα errno)
@anchor{library/errno errno ENOTSUP}@anchor{34f2}
@deffn {Δεδομένα} errno.ENOTSUP

Operation not supported


Added in version 3.2.

@end deffn

@geindex EPFNOSUPPORT (στη μονάδα errno)
@anchor{library/errno errno EPFNOSUPPORT}@anchor{34f3}
@deffn {Δεδομένα} errno.EPFNOSUPPORT

Protocol family not supported
@end deffn

@geindex EAFNOSUPPORT (στη μονάδα errno)
@anchor{library/errno errno EAFNOSUPPORT}@anchor{34f4}
@deffn {Δεδομένα} errno.EAFNOSUPPORT

Address family not supported by protocol
@end deffn

@geindex EADDRINUSE (στη μονάδα errno)
@anchor{library/errno errno EADDRINUSE}@anchor{34f5}
@deffn {Δεδομένα} errno.EADDRINUSE

Address already in use
@end deffn

@geindex EADDRNOTAVAIL (στη μονάδα errno)
@anchor{library/errno errno EADDRNOTAVAIL}@anchor{34f6}
@deffn {Δεδομένα} errno.EADDRNOTAVAIL

Cannot assign requested address
@end deffn

@geindex ENETDOWN (στη μονάδα errno)
@anchor{library/errno errno ENETDOWN}@anchor{34f7}
@deffn {Δεδομένα} errno.ENETDOWN

Network is down
@end deffn

@geindex ENETUNREACH (στη μονάδα errno)
@anchor{library/errno errno ENETUNREACH}@anchor{1fd8}
@deffn {Δεδομένα} errno.ENETUNREACH

Network is unreachable
@end deffn

@geindex ENETRESET (στη μονάδα errno)
@anchor{library/errno errno ENETRESET}@anchor{34f8}
@deffn {Δεδομένα} errno.ENETRESET

Network dropped connection because of reset
@end deffn

@geindex ECONNABORTED (στη μονάδα errno)
@anchor{library/errno errno ECONNABORTED}@anchor{2901}
@deffn {Δεδομένα} errno.ECONNABORTED

Software caused connection abort. This error is mapped to the
exception @ref{1405,,ConnectionAbortedError}.
@end deffn

@geindex ECONNRESET (στη μονάδα errno)
@anchor{library/errno errno ECONNRESET}@anchor{2903}
@deffn {Δεδομένα} errno.ECONNRESET

Connection reset by peer. This error is mapped to the exception
@ref{1407,,ConnectionResetError}.
@end deffn

@geindex ENOBUFS (στη μονάδα errno)
@anchor{library/errno errno ENOBUFS}@anchor{1d6e}
@deffn {Δεδομένα} errno.ENOBUFS

No buffer space available
@end deffn

@geindex EISCONN (στη μονάδα errno)
@anchor{library/errno errno EISCONN}@anchor{34f9}
@deffn {Δεδομένα} errno.EISCONN

Transport endpoint is already connected
@end deffn

@geindex ENOTCONN (στη μονάδα errno)
@anchor{library/errno errno ENOTCONN}@anchor{34fa}
@deffn {Δεδομένα} errno.ENOTCONN

Transport endpoint is not connected
@end deffn

@geindex ESHUTDOWN (στη μονάδα errno)
@anchor{library/errno errno ESHUTDOWN}@anchor{2900}
@deffn {Δεδομένα} errno.ESHUTDOWN

Cannot send after transport endpoint shutdown. This error is mapped
to the exception @ref{1404,,BrokenPipeError}.
@end deffn

@geindex ETOOMANYREFS (στη μονάδα errno)
@anchor{library/errno errno ETOOMANYREFS}@anchor{34fb}
@deffn {Δεδομένα} errno.ETOOMANYREFS

Too many references: cannot splice
@end deffn

@geindex ETIMEDOUT (στη μονάδα errno)
@anchor{library/errno errno ETIMEDOUT}@anchor{290a}
@deffn {Δεδομένα} errno.ETIMEDOUT

Connection timed out. This error is mapped to the exception
@ref{c0e,,TimeoutError}.
@end deffn

@geindex ECONNREFUSED (στη μονάδα errno)
@anchor{library/errno errno ECONNREFUSED}@anchor{2902}
@deffn {Δεδομένα} errno.ECONNREFUSED

Connection refused. This error is mapped to the exception
@ref{1406,,ConnectionRefusedError}.
@end deffn

@geindex EHOSTDOWN (στη μονάδα errno)
@anchor{library/errno errno EHOSTDOWN}@anchor{34fc}
@deffn {Δεδομένα} errno.EHOSTDOWN

Host is down
@end deffn

@geindex EHOSTUNREACH (στη μονάδα errno)
@anchor{library/errno errno EHOSTUNREACH}@anchor{34fd}
@deffn {Δεδομένα} errno.EHOSTUNREACH

No route to host
@end deffn

@geindex EHWPOISON (στη μονάδα errno)
@anchor{library/errno errno EHWPOISON}@anchor{49c}
@deffn {Δεδομένα} errno.EHWPOISON

Memory page has hardware error.


Added in version 3.14.

@end deffn

@geindex EALREADY (στη μονάδα errno)
@anchor{library/errno errno EALREADY}@anchor{28fa}
@deffn {Δεδομένα} errno.EALREADY

Operation already in progress. This error is mapped to the
exception @ref{4c3,,BlockingIOError}.
@end deffn

@geindex EINPROGRESS (στη μονάδα errno)
@anchor{library/errno errno EINPROGRESS}@anchor{28fc}
@deffn {Δεδομένα} errno.EINPROGRESS

Operation now in progress. This error is mapped to the exception
@ref{4c3,,BlockingIOError}.
@end deffn

@geindex ESTALE (στη μονάδα errno)
@anchor{library/errno errno ESTALE}@anchor{34fe}
@deffn {Δεδομένα} errno.ESTALE

Stale NFS file handle
@end deffn

@geindex EUCLEAN (στη μονάδα errno)
@anchor{library/errno errno EUCLEAN}@anchor{34ff}
@deffn {Δεδομένα} errno.EUCLEAN

Structure needs cleaning
@end deffn

@geindex ENOTNAM (στη μονάδα errno)
@anchor{library/errno errno ENOTNAM}@anchor{3500}
@deffn {Δεδομένα} errno.ENOTNAM

Not a XENIX named type file
@end deffn

@geindex ENAVAIL (στη μονάδα errno)
@anchor{library/errno errno ENAVAIL}@anchor{3501}
@deffn {Δεδομένα} errno.ENAVAIL

No XENIX semaphores available
@end deffn

@geindex EISNAM (στη μονάδα errno)
@anchor{library/errno errno EISNAM}@anchor{3502}
@deffn {Δεδομένα} errno.EISNAM

Is a named type file
@end deffn

@geindex EREMOTEIO (στη μονάδα errno)
@anchor{library/errno errno EREMOTEIO}@anchor{3503}
@deffn {Δεδομένα} errno.EREMOTEIO

Remote I/O error
@end deffn

@geindex EDQUOT (στη μονάδα errno)
@anchor{library/errno errno EDQUOT}@anchor{3504}
@deffn {Δεδομένα} errno.EDQUOT

Quota exceeded
@end deffn

@geindex EQFULL (στη μονάδα errno)
@anchor{library/errno errno EQFULL}@anchor{3505}
@deffn {Δεδομένα} errno.EQFULL

Interface output queue is full


Added in version 3.11.

@end deffn

@geindex ENOMEDIUM (στη μονάδα errno)
@anchor{library/errno errno ENOMEDIUM}@anchor{3506}
@deffn {Δεδομένα} errno.ENOMEDIUM

No medium found
@end deffn

@geindex EMEDIUMTYPE (στη μονάδα errno)
@anchor{library/errno errno EMEDIUMTYPE}@anchor{3507}
@deffn {Δεδομένα} errno.EMEDIUMTYPE

Wrong medium type
@end deffn

@geindex ENOKEY (στη μονάδα errno)
@anchor{library/errno errno ENOKEY}@anchor{3508}
@deffn {Δεδομένα} errno.ENOKEY

Required key not available
@end deffn

@geindex EKEYEXPIRED (στη μονάδα errno)
@anchor{library/errno errno EKEYEXPIRED}@anchor{3509}
@deffn {Δεδομένα} errno.EKEYEXPIRED

Key has expired
@end deffn

@geindex EKEYREVOKED (στη μονάδα errno)
@anchor{library/errno errno EKEYREVOKED}@anchor{350a}
@deffn {Δεδομένα} errno.EKEYREVOKED

Key has been revoked
@end deffn

@geindex EKEYREJECTED (στη μονάδα errno)
@anchor{library/errno errno EKEYREJECTED}@anchor{350b}
@deffn {Δεδομένα} errno.EKEYREJECTED

Key was rejected by service
@end deffn

@geindex ERFKILL (στη μονάδα errno)
@anchor{library/errno errno ERFKILL}@anchor{350c}
@deffn {Δεδομένα} errno.ERFKILL

Operation not possible due to RF-kill
@end deffn

@geindex ELOCKUNMAPPED (στη μονάδα errno)
@anchor{library/errno errno ELOCKUNMAPPED}@anchor{350d}
@deffn {Δεδομένα} errno.ELOCKUNMAPPED

Locked lock was unmapped
@end deffn

@geindex ENOTACTIVE (στη μονάδα errno)
@anchor{library/errno errno ENOTACTIVE}@anchor{350e}
@deffn {Δεδομένα} errno.ENOTACTIVE

Facility is not active
@end deffn

@geindex EAUTH (στη μονάδα errno)
@anchor{library/errno errno EAUTH}@anchor{350f}
@deffn {Δεδομένα} errno.EAUTH

Authentication error


Added in version 3.2.

@end deffn

@geindex EBADARCH (στη μονάδα errno)
@anchor{library/errno errno EBADARCH}@anchor{3510}
@deffn {Δεδομένα} errno.EBADARCH

Bad CPU type in executable


Added in version 3.2.

@end deffn

@geindex EBADEXEC (στη μονάδα errno)
@anchor{library/errno errno EBADEXEC}@anchor{3511}
@deffn {Δεδομένα} errno.EBADEXEC

Bad executable (or shared library)


Added in version 3.2.

@end deffn

@geindex EBADMACHO (στη μονάδα errno)
@anchor{library/errno errno EBADMACHO}@anchor{3512}
@deffn {Δεδομένα} errno.EBADMACHO

Malformed Mach-o file


Added in version 3.2.

@end deffn

@geindex EDEVERR (στη μονάδα errno)
@anchor{library/errno errno EDEVERR}@anchor{3513}
@deffn {Δεδομένα} errno.EDEVERR

Device error


Added in version 3.2.

@end deffn

@geindex EFTYPE (στη μονάδα errno)
@anchor{library/errno errno EFTYPE}@anchor{3514}
@deffn {Δεδομένα} errno.EFTYPE

Inappropriate file type or format


Added in version 3.2.

@end deffn

@geindex ENEEDAUTH (στη μονάδα errno)
@anchor{library/errno errno ENEEDAUTH}@anchor{3515}
@deffn {Δεδομένα} errno.ENEEDAUTH

Need authenticator


Added in version 3.2.

@end deffn

@geindex ENOATTR (στη μονάδα errno)
@anchor{library/errno errno ENOATTR}@anchor{3516}
@deffn {Δεδομένα} errno.ENOATTR

Attribute not found


Added in version 3.2.

@end deffn

@geindex ENOPOLICY (στη μονάδα errno)
@anchor{library/errno errno ENOPOLICY}@anchor{3517}
@deffn {Δεδομένα} errno.ENOPOLICY

Policy not found


Added in version 3.2.

@end deffn

@geindex EPROCLIM (στη μονάδα errno)
@anchor{library/errno errno EPROCLIM}@anchor{3518}
@deffn {Δεδομένα} errno.EPROCLIM

Too many processes


Added in version 3.2.

@end deffn

@geindex EPROCUNAVAIL (στη μονάδα errno)
@anchor{library/errno errno EPROCUNAVAIL}@anchor{3519}
@deffn {Δεδομένα} errno.EPROCUNAVAIL

Bad procedure for program


Added in version 3.2.

@end deffn

@geindex EPROGMISMATCH (στη μονάδα errno)
@anchor{library/errno errno EPROGMISMATCH}@anchor{351a}
@deffn {Δεδομένα} errno.EPROGMISMATCH

Program version wrong


Added in version 3.2.

@end deffn

@geindex EPROGUNAVAIL (στη μονάδα errno)
@anchor{library/errno errno EPROGUNAVAIL}@anchor{351b}
@deffn {Δεδομένα} errno.EPROGUNAVAIL

RPC prog. not avail


Added in version 3.2.

@end deffn

@geindex EPWROFF (στη μονάδα errno)
@anchor{library/errno errno EPWROFF}@anchor{351c}
@deffn {Δεδομένα} errno.EPWROFF

Device power is off


Added in version 3.2.

@end deffn

@geindex EBADRPC (στη μονάδα errno)
@anchor{library/errno errno EBADRPC}@anchor{351d}
@deffn {Δεδομένα} errno.EBADRPC

RPC struct is bad


Added in version 3.2.

@end deffn

@geindex ERPCMISMATCH (στη μονάδα errno)
@anchor{library/errno errno ERPCMISMATCH}@anchor{351e}
@deffn {Δεδομένα} errno.ERPCMISMATCH

RPC version wrong


Added in version 3.2.

@end deffn

@geindex ESHLIBVERS (στη μονάδα errno)
@anchor{library/errno errno ESHLIBVERS}@anchor{351f}
@deffn {Δεδομένα} errno.ESHLIBVERS

Shared library version mismatch


Added in version 3.2.

@end deffn

@geindex ENOTCAPABLE (στη μονάδα errno)
@anchor{library/errno errno ENOTCAPABLE}@anchor{1d3d}
@deffn {Δεδομένα} errno.ENOTCAPABLE

Capabilities insufficient. This error is mapped to the exception
@ref{10f9,,PermissionError}.

@ref{232d,,Διαθεσιμότητα}: WASI, FreeBSD


Added in version 3.11.1.

@end deffn

@geindex ECANCELED (στη μονάδα errno)
@anchor{library/errno errno ECANCELED}@anchor{1a02}
@deffn {Δεδομένα} errno.ECANCELED

Operation canceled


Added in version 3.2.

@end deffn

@geindex EOWNERDEAD (στη μονάδα errno)
@anchor{library/errno errno EOWNERDEAD}@anchor{3520}
@deffn {Δεδομένα} errno.EOWNERDEAD

Owner died


Added in version 3.2.

@end deffn

@geindex ENOTRECOVERABLE (στη μονάδα errno)
@anchor{library/errno errno ENOTRECOVERABLE}@anchor{3521}
@deffn {Δεδομένα} errno.ENOTRECOVERABLE

State not recoverable


Added in version 3.2.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node ctypes — A foreign function library for Python,,errno — Standard errno system symbols,Generic Operating System Services
@anchor{library/ctypes doc}@anchor{3522}@anchor{library/ctypes ctypes-a-foreign-function-library-for-python}@anchor{3523}@anchor{library/ctypes module-ctypes}@anchor{2d}@anchor{library/ctypes translation-repo}@anchor{3524}
@subsection @code{ctypes} — A foreign function library for Python


@geindex module; ctypes

`Source code:' Lib/ctypes@footnote{https://github.com/python/cpython/tree/main/Lib/ctypes}


__________________________________________________________________


@code{ctypes} is a foreign function library for Python.  It provides C compatible
data types, and allows calling functions in DLLs or shared libraries.  It can be
used to wrap these libraries in pure Python.

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile

@menu
* ctypes tutorial:: 
* ctypes reference:: 

@end menu

@node ctypes tutorial,ctypes reference,,ctypes — A foreign function library for Python
@anchor{library/ctypes ctypes-ctypes-tutorial}@anchor{3525}@anchor{library/ctypes ctypes-tutorial}@anchor{3526}
@subsubsection ctypes tutorial


Note: Some code samples reference the ctypes @ref{3527,,c_int} type.  On platforms
where @code{sizeof(long) == sizeof(int)} it is an alias to @ref{3528,,c_long}.
So, you should not be confused if @code{c_long} is printed if you would expect
@code{c_int} — they are actually the same type.

@menu
* Loading dynamic link libraries:: 
* Accessing functions from loaded dlls:: 
* Calling functions:: 
* Fundamental data types:: 
* Calling functions@comma{} continued: Calling functions continued. 
* Calling variadic functions:: 
* Calling functions with your own custom data types:: 
* Specifying the required argument types (function prototypes): Specifying the required argument types function prototypes. 
* Return types:: 
* Passing pointers (or; passing parameters by reference): Passing pointers or passing parameters by reference. 
* Structures and unions:: 
* Structure/union layout@comma{} alignment and byte order: Structure/union layout alignment and byte order. 
* Bit fields in structures and unions:: 
* Arrays:: 
* Pointers:: 
* Thread safety without the GIL:: 
* Type conversions:: 
* Incomplete Types:: 
* Callback functions:: 
* Accessing values exported from dlls:: 
* Surprises:: 
* Variable-sized data types:: 

@end menu

@node Loading dynamic link libraries,Accessing functions from loaded dlls,,ctypes tutorial
@anchor{library/ctypes ctypes-loading-dynamic-link-libraries}@anchor{3529}@anchor{library/ctypes loading-dynamic-link-libraries}@anchor{352a}
@subsubsection Loading dynamic link libraries


@code{ctypes} exports the @ref{352b,,cdll}, and on Windows
@ref{352c,,windll} and @ref{352d,,oledll}
objects, for loading dynamic link libraries.

You load libraries by accessing them as attributes of these objects.
@code{cdll} loads libraries which export functions using the
standard @code{cdecl} calling convention, while @code{windll}
libraries call functions using the @code{stdcall}
calling convention.
@ref{352d,,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{53c,,OSError} exception when the
function call fails.


Άλλαξε στην έκδοση 3.3: Windows errors used to raise @ref{13fd,,WindowsError}, which is now an alias
of @ref{53c,,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 appends the usual @code{.dll} file suffix automatically.

@cartouche
@quotation Σημείωση 
Accessing the standard C library through @code{cdll.msvcrt} will use an
outdated version of the library that may be incompatible with the one
being used by Python. Where possible, use native Python functionality,
or else import and use the @code{msvcrt} module.
@end quotation
@end cartouche

Other systems require the filename `including' the extension to
load a library, so attribute access can not be used to load libraries. Either the
@ref{352e,,LoadLibrary()} method of the dll loaders should be used,
or you should load the library by creating an instance of @ref{dad,,CDLL}
by calling the constructor.

For example, on Linux:

@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

On macOS:

@example
>>> cdll.LoadLibrary("libc.dylib")
<CDLL 'libc.dylib', handle ... at ...>
>>> libc = CDLL("libc.dylib")
>>> libc
<CDLL 'libc.dylib', handle ... at ...>
@end example

@node Accessing functions from loaded dlls,Calling functions,Loading dynamic link libraries,ctypes tutorial
@anchor{library/ctypes accessing-functions-from-loaded-dlls}@anchor{352f}@anchor{library/ctypes ctypes-accessing-functions-from-loaded-dlls}@anchor{3530}
@subsubsection Accessing functions from loaded dlls


Functions are accessed as attributes of dll objects:

@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' does not try to select one of them by magic, you must access the
version you need by specifying @code{GetModuleHandleA} or @code{GetModuleHandleW}
explicitly, and then call it with bytes or string objects respectively.

Sometimes, dlls export functions with names which aren’t valid Python
identifiers, like @code{"??2@@YAPAXI@@Z"}. In this case you have to use
@ref{f8f,,getattr()} to retrieve the function:

@example
>>> getattr(cdll.msvcrt, "??2@@YAPAXI@@Z")
<_FuncPtr object at 0x...>
>>>
@end example

On Windows, some dlls export functions not by name but by ordinal. These
functions can be accessed by indexing the dll object with the ordinal number:

@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 Calling functions,Fundamental data types,Accessing functions from loaded dlls,ctypes tutorial
@anchor{library/ctypes calling-functions}@anchor{3531}@anchor{library/ctypes ctypes-calling-functions}@anchor{3532}
@subsubsection Calling functions


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

@ref{277,,ValueError} is raised when you call an @code{stdcall} function with the
@code{cdecl} calling convention, or 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

To find out the correct calling convention you have to look into the C header
file or the documentation for the function you want to call.

On Windows, @code{ctypes} uses win32 structured exception handling to prevent
crashes from general protection faults when functions are called with invalid
argument values:

@example
>>> windll.kernel32.GetModuleHandleA(32)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
OSError: exception: access violation reading 0x00000020
>>>
@end example

There are, however, enough ways to crash Python with @code{ctypes}, so you
should be careful anyway.  The @ref{5b,,faulthandler} module can be helpful in
debugging crashes (e.g. from segmentation faults produced by erroneous C library
calls).

@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.

Before we move on calling functions with other parameter types, we have to learn
more about @code{ctypes} data types.

@node Fundamental data types,Calling functions continued,Calling functions,ctypes tutorial
@anchor{library/ctypes ctypes-fundamental-data-types}@anchor{2a32}@anchor{library/ctypes fundamental-data-types}@anchor{3533}
@subsubsection Fundamental data types


@code{ctypes} defines a number of primitive C compatible data types:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ctypes type

@tab

C type

@tab

Python type

@tab

@ref{2cd,,_type_}

@item

@ref{3534,,c_bool}

@tab

_Bool

@tab

@ref{5ef,,bool}

@tab

@code{'?'}

@item

@ref{3535,,c_char}

@tab

char

@tab

1-character @ref{1c7,,bytes}

@tab

@code{'c'}

@item

@ref{3536,,c_wchar}

@tab

@code{wchar_t}

@tab

1-character @ref{1df,,str}

@tab

@code{'u'}

@item

@ref{1cdf,,c_byte}

@tab

char

@tab

@ref{326,,int}

@tab

@code{'b'}

@item

@ref{1ce0,,c_ubyte}

@tab

unsigned char

@tab

@ref{326,,int}

@tab

@code{'B'}

@item

@ref{3537,,c_short}

@tab

short

@tab

@ref{326,,int}

@tab

@code{'h'}

@item

@ref{3538,,c_ushort}

@tab

unsigned short

@tab

@ref{326,,int}

@tab

@code{'H'}

@item

@ref{3527,,c_int}

@tab

int

@tab

@ref{326,,int}

@tab

@code{'i'} *

@item

@ref{3539,,c_int8}

@tab

@code{int8_t}

@tab

@ref{326,,int}

@tab

*

@item

@ref{353a,,c_int16}

@tab

@code{int16_t}

@tab

@ref{326,,int}

@tab

*

@item

@ref{353b,,c_int32}

@tab

@code{int32_t}

@tab

@ref{326,,int}

@tab

*

@item

@ref{353c,,c_int64}

@tab

@code{int64_t}

@tab

@ref{326,,int}

@tab

*

@item

@ref{353d,,c_uint}

@tab

unsigned int

@tab

@ref{326,,int}

@tab

@code{'I'} *

@item

@ref{353e,,c_uint8}

@tab

@code{uint8_t}

@tab

@ref{326,,int}

@tab

*

@item

@ref{353f,,c_uint16}

@tab

@code{uint16_t}

@tab

@ref{326,,int}

@tab

*

@item

@ref{3540,,c_uint32}

@tab

@code{uint32_t}

@tab

@ref{326,,int}

@tab

*

@item

@ref{3541,,c_uint64}

@tab

@code{uint64_t}

@tab

@ref{326,,int}

@tab

*

@item

@ref{3528,,c_long}

@tab

long

@tab

@ref{326,,int}

@tab

@code{'l'}

@item

@ref{3542,,c_ulong}

@tab

unsigned long

@tab

@ref{326,,int}

@tab

@code{'L'}

@item

@ref{3543,,c_longlong}

@tab

long long

@tab

@ref{326,,int}

@tab

@code{'q'} *

@item

@ref{3544,,c_ulonglong}

@tab

unsigned long long

@tab

@ref{326,,int}

@tab

@code{'Q'} *

@item

@ref{3545,,c_size_t}

@tab

@code{size_t}

@tab

@ref{326,,int}

@tab

*

@item

@ref{15e2,,c_ssize_t}

@tab

@ref{e24,,Py_ssize_t}

@tab

@ref{326,,int}

@tab

*

@item

@ref{1d61,,c_time_t}

@tab

@code{time_t}

@tab

@ref{326,,int}

@tab

*

@item

@ref{3546,,c_float}

@tab

float

@tab

@ref{327,,float}

@tab

@code{'f'}

@item

@ref{1eae,,c_double}

@tab

double

@tab

@ref{327,,float}

@tab

@code{'d'}

@item

@ref{1eaf,,c_longdouble}

@tab

long double

@tab

@ref{327,,float}

@tab

@code{'g'} *

@item

@ref{1c5d,,c_char_p}

@tab

char* (NUL terminated)

@tab

@ref{1c7,,bytes} or @code{None}

@tab

@code{'z'}

@item

@ref{1c5e,,c_wchar_p}

@tab

wchar_t* (NUL terminated)

@tab

@ref{1df,,str} or @code{None}

@tab

@code{'Z'}

@item

@ref{1c5f,,c_void_p}

@tab

void*

@tab

@ref{326,,int} or @code{None}

@tab

@code{'P'}

@item

@ref{486,,py_object}

@tab

@ref{19b,,PyObject}*

@tab

@ref{e4d,,object}

@tab

@code{'O'}

@item

@ref{3547,,VARIANT_BOOL}

@tab

short int

@tab

@ref{5ef,,bool}

@tab

@code{'v'}

@end multitable


Additionally, if IEC 60559 compatible complex arithmetic (Annex G) is supported
in both C and @code{libffi}, the following complex types are available:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ctypes type

@tab

C type

@tab

Python type

@tab

@ref{2cd,,_type_}

@item

@ref{2ce,,c_float_complex}

@tab

float complex

@tab

@ref{328,,complex}

@tab

@code{'Zf'}

@item

@ref{2cf,,c_double_complex}

@tab

double complex

@tab

@ref{328,,complex}

@tab

@code{'Zd'}

@item

@ref{2d0,,c_longdouble_complex}

@tab

long double complex

@tab

@ref{328,,complex}

@tab

@code{'Zg'}

@end multitable



Άλλαξε στην έκδοση 3.15: The @ref{2cd,,_type_} types @code{F}, @code{D} and @code{G} have been
replaced with @code{Zf}, @code{Zd} and @code{Zg}.


All these types can be created by calling them with an optional initializer of
the correct type and value:

@example
>>> c_int()
c_long(0)
>>> c_wchar_p("Hello, World")
c_wchar_p(140018365411392)
>>> c_ushort(-3)
c_ushort(65533)
>>>
@end example

The constructors for numeric types will convert input using
@ref{167a,,__bool__()},
@ref{43d,,__index__()} (for @code{int}),
@ref{d92,,__float__()} or @ref{9de,,__complex__()}.
This means @ref{3534,,c_bool} accepts any object with a truth value:

@example
>>> empty_list = []
>>> c_bool(empty_list)
c_bool(False)
@end example

Since these types are mutable, their value can also be changed afterwards:

@example
>>> i = c_int(42)
>>> print(i)
c_long(42)
>>> print(i.value)
42
>>> i.value = -99
>>> print(i.value)
-99
>>>
@end example

Assigning a new value to instances of the pointer types @ref{1c5d,,c_char_p},
@ref{1c5e,,c_wchar_p}, and @ref{1c5f,,c_void_p} changes the `memory location' they
point to, `not the contents' of the memory block (of course not, because Python
string objects are immutable):

@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

You should be careful, however, not to pass them to functions expecting pointers
to mutable memory. If you need mutable memory blocks, ctypes has a
@ref{3548,,create_string_buffer()} function which creates these in various ways.  The
current memory block contents can be accessed (or changed) with the @code{raw}
property; if you want to access it as NUL terminated string, use the @code{value}
property:

@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{3548,,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{1fa4,,create_unicode_buffer()} function.

@node Calling functions continued,Calling variadic functions,Fundamental data types,ctypes tutorial
@anchor{library/ctypes calling-functions-continued}@anchor{3549}@anchor{library/ctypes ctypes-calling-functions-continued}@anchor{354a}
@subsubsection Calling functions, continued


Note that printf prints to the real standard output channel, `not' to
@ref{e9c,,sys.stdout}, so these examples will only work at the console prompt, not
from within `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

As has been mentioned before, all Python types except integers, strings, and
bytes objects have to be wrapped in their corresponding @code{ctypes} type, so
that they can be converted to the required C data type:

@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,Calling functions with your own custom data types,Calling functions continued,ctypes tutorial
@anchor{library/ctypes calling-variadic-functions}@anchor{354b}@anchor{library/ctypes ctypes-calling-variadic-functions}@anchor{354c}
@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{1a00,,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{1a00,,argtypes} for all variadic functions.

@node Calling functions with your own custom data types,Specifying the required argument types function prototypes,Calling variadic functions,ctypes tutorial
@anchor{library/ctypes calling-functions-with-your-own-custom-data-types}@anchor{354d}@anchor{library/ctypes ctypes-calling-functions-with-own-custom-data-types}@anchor{354e}
@subsubsection Calling functions with your own custom data types


You can also customize @code{ctypes} argument conversion to allow instances of
your own classes be used as function arguments. @code{ctypes} looks for an
@code{_as_parameter_} attribute and uses this as the function argument. The
attribute must be an integer, string, bytes, a @code{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{6bb,,property} which makes the
attribute available on request.

@node Specifying the required argument types function prototypes,Return types,Calling functions with your own custom data types,ctypes tutorial
@anchor{library/ctypes ctypes-specifying-required-argument-types}@anchor{354f}@anchor{library/ctypes specifying-the-required-argument-types-function-prototypes}@anchor{3550}
@subsubsection Specifying the required argument types (function prototypes)


It is possible to specify the required argument types of functions exported from
DLLs by setting the @ref{1a00,,argtypes} attribute.

@ref{1a00,,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

Specifying a format protects against incompatible argument types (just as a
prototype for a C function), and tries to convert the arguments to valid types:

@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{3551,,from_param()} class method for them to be able to use them
in the @ref{1a00,,argtypes} sequence. The @code{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 @code{ctypes} instance, or an object with an
@code{_as_parameter_} attribute.

@node Return types,Passing pointers or passing parameters by reference,Specifying the required argument types function prototypes,ctypes tutorial
@anchor{library/ctypes ctypes-return-types}@anchor{3552}@anchor{library/ctypes return-types}@anchor{3553}
@subsubsection Return types


@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{3554,,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{1a00,,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{252c,,ord("x")} calls above, you can set the
@ref{1a00,,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{3554,,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} is a function which will call Windows @code{FormatMessage()} api to
get the string representation of an error code, and `returns' an exception.
@code{WinError} takes an optional error code parameter, if no one is used, it calls
@ref{1963,,GetLastError()} to retrieve it.

Please note that a much more powerful error checking mechanism is available
through the @ref{3555,,errcheck} attribute;
see the reference manual for details.

@node Passing pointers or passing parameters by reference,Structures and unions,Return types,ctypes tutorial
@anchor{library/ctypes ctypes-passing-pointers}@anchor{3556}@anchor{library/ctypes passing-pointers-or-passing-parameters-by-reference}@anchor{3557}
@subsubsection Passing pointers (or: passing parameters by reference)


Sometimes a C api function expects a `pointer' to a data type as parameter,
probably to write into the corresponding location, or if the data is too large
to be passed by value. This is also known as `passing parameters by reference'.

@code{ctypes} exports the @ref{3558,,byref()} function which is used to pass parameters
by reference.  The same effect can be achieved with the @ref{1c5c,,pointer()} function,
although @code{pointer()} does a lot more work since it constructs a real pointer
object, so it is faster to use @code{byref()} if you don’t need the pointer
object in Python itself:

@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 and unions,Structure/union layout alignment and byte order,Passing pointers or passing parameters by reference,ctypes tutorial
@anchor{library/ctypes ctypes-structures-unions}@anchor{3559}@anchor{library/ctypes structures-and-unions}@anchor{355a}
@subsubsection Structures and unions


Structures and unions must derive from the @ref{47c,,Structure} and @ref{47d,,Union}
base classes which are defined in the @code{ctypes} module. Each subclass must
define a @ref{1b50,,_fields_} attribute.  @code{_fields_} must be a list of
`2-tuples', containing a `field name' and a `field type'.

The field type must be a @code{ctypes} type like @ref{3527,,c_int}, or any other
derived @code{ctypes} type: structure, union, array, pointer.

Here is a simple example of a POINT structure, which contains two integers named
`x' and `y', and also shows how to initialize a structure in the constructor:

@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

You can, however, build much more complicated structures.  A structure can
itself contain other structures by using a structure as a field type.

Here is a RECT structure which contains two POINTs named `upperleft' and
`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

Nested structures can also be initialized in the constructor in several ways:

@example
>>> r = RECT(POINT(1, 2), POINT(3, 4))
>>> r = RECT((1, 2), (3, 4))
@end example

Field @ref{21f,,descriptor}s can be retrieved from the `class', they are useful
for debugging because they can provide useful information.
See @ref{47e,,CField}:

@example
>>> POINT.x
<ctypes.CField 'x' type=c_int, ofs=0, size=4>
>>> POINT.y
<ctypes.CField 'y' type=c_int, ofs=4, size=4>
>>>
@end example
@anchor{library/ctypes ctypes-structureunion-alignment-byte-order}@anchor{355b}
@cartouche
@quotation Προειδοποίηση 
@code{ctypes} does not support passing unions or structures with bit-fields
to functions by value.  While this may work on 32-bit x86, it’s not
guaranteed by the library to work in the general case.  Unions and
structures with bit-fields should always be passed to functions by pointer.
@end quotation
@end cartouche

@node Structure/union layout alignment and byte order,Bit fields in structures and unions,Structures and unions,ctypes tutorial
@anchor{library/ctypes structure-union-layout-alignment-and-byte-order}@anchor{355c}
@subsubsection Structure/union layout, alignment and byte order


By default, Structure and Union fields are laid out in the same way the C
compiler does it.  It is possible to override this behavior entirely by specifying a
@ref{319,,_layout_} class attribute in the subclass definition; see
the attribute documentation for details.

It is possible to specify the maximum alignment for the fields and/or for the
structure itself by setting the class attributes @ref{318,,_pack_}
and/or @ref{6ed,,_align_}, respectively.
See the attribute documentation for details.

@code{ctypes} uses the native byte order for Structures and Unions.  To build
structures with non-native byte order, you can use one of the
@ref{355d,,BigEndianStructure}, @ref{355e,,LittleEndianStructure},
@ref{1db1,,BigEndianUnion}, and @ref{1db2,,LittleEndianUnion} base classes.  These
classes cannot contain pointer fields.

@node Bit fields in structures and unions,Arrays,Structure/union layout alignment and byte order,ctypes tutorial
@anchor{library/ctypes bit-fields-in-structures-and-unions}@anchor{355f}@anchor{library/ctypes ctypes-bit-fields-in-structures-unions}@anchor{47b}
@subsubsection Bit fields in structures and 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{1b50,,_fields_} tuples:

@example
>>> class Int(Structure):
...     _fields_ = [("first_16", c_int, 16),
...                 ("second_16", c_int, 16)]
...
>>> print(Int.first_16)
<ctypes.CField 'first_16' type=c_int, ofs=0, bit_size=16, bit_offset=0>
>>> print(Int.second_16)
<ctypes.CField 'second_16' type=c_int, ofs=0, bit_size=16, bit_offset=16>
@end example

It is important to note that bit field allocation and layout in memory are not
defined as a C standard; their implementation is compiler-specific.
By default, Python will attempt to match the behavior of a «native» compiler
for the current platform.
See the @ref{319,,_layout_} attribute for details on the default
behavior and how to change it.

@node Arrays,Pointers,Bit fields in structures and unions,ctypes tutorial
@anchor{library/ctypes arrays}@anchor{3560}@anchor{library/ctypes ctypes-arrays}@anchor{3561}
@subsubsection Arrays


Arrays are sequences, containing a fixed number of instances of the same type.

The recommended way to create array types is by multiplying a data type with a
positive integer:

@example
TenPointsArrayType = POINT * 10
@end example

Here is an example of a somewhat artificial data type, a structure containing 4
POINTs among other stuff:

@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

Instances are created in the usual way, by calling the class:

@example
arr = TenPointsArrayType()
for pt in arr:
    print(pt.x, pt.y)
@end example

The above code print a series of @code{0 0} lines, because the array contents is
initialized to zeros.

Initializers of the correct type can also be specified:

@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 Pointers,Thread safety without the GIL,Arrays,ctypes tutorial
@anchor{library/ctypes ctypes-pointers}@anchor{3562}@anchor{library/ctypes pointers}@anchor{3563}
@subsubsection Pointers


Pointer instances are created by calling the @ref{1c5c,,pointer()} function on a
@code{ctypes} type:

@example
>>> from ctypes import *
>>> i = c_int(42)
>>> pi = pointer(i)
>>>
@end example

Pointer instances have a @ref{3564,,contents} attribute which
returns the object to which the pointer points, the @code{i} object above:

@example
>>> pi.contents
c_long(42)
>>>
@end example

Note that @code{ctypes} does not have OOR (original object return), it constructs a
new, equivalent object each time you retrieve an attribute:

@example
>>> pi.contents is i
False
>>> pi.contents is pi.contents
False
>>>
@end example

Assigning another @ref{3527,,c_int} instance to the pointer’s contents attribute
would cause the pointer to point to the memory location where this is stored:

@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.

Pointer instances can also be indexed with integers:

@example
>>> pi[0]
99
>>>
@end example

Assigning to an integer index changes the pointed to value:

@example
>>> print(i)
c_long(99)
>>> pi[0] = 22
>>> print(i)
c_long(22)
>>>
@end example

It is also possible to use indexes different from 0, but you must know what
you’re doing, just as in C: You can access or change arbitrary memory locations.
Generally you only use this feature if you receive a pointer from a C function,
and you `know' that the pointer actually points to an array instead of a single
item.

Behind the scenes, the @ref{1c5c,,pointer()} function does more than simply create
pointer instances, it has to create pointer `types' first. This is done with the
@ref{484,,POINTER()} function, which accepts any @code{ctypes} type, and returns a
new 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

Calling the pointer type without an argument creates a @code{NULL} pointer.
@code{NULL} pointers have a @code{False} boolean value:

@example
>>> null_ptr = POINTER(c_int)()
>>> print(bool(null_ptr))
False
>>>
@end example

@code{ctypes} checks for @code{NULL} when dereferencing pointers (but dereferencing
invalid non-@code{NULL} pointers would crash 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 Thread safety without the GIL,Type conversions,Pointers,ctypes tutorial
@anchor{library/ctypes ctypes-thread-safety}@anchor{3565}@anchor{library/ctypes thread-safety-without-the-gil}@anchor{3566}
@subsubsection Thread safety without the GIL


From Python 3.13 onward, the @ref{411,,GIL} can be disabled on the @ref{198,,free-threaded build}.
In ctypes, reads and writes to a single object concurrently is safe, but not across multiple objects:

@quotation

@example
>>> number = c_int(42)
>>> pointer_a = pointer(number)
>>> pointer_b = pointer(number)
@end example
@end quotation

In the above, it’s only safe for one object to read and write to the address at once if the GIL is disabled.
So, @code{pointer_a} can be shared and written to across multiple threads, but only if @code{pointer_b}
is not also attempting to do the same. If this is an issue, consider using a @ref{1a10,,threading.Lock}
to synchronize access to memory:

@quotation

@example
>>> import threading
>>> lock = threading.Lock()
>>> # Thread 1
>>> with lock:
...    pointer_a.contents = 24
>>> # Thread 2
>>> with lock:
...    pointer_b.contents = 42
@end example
@end quotation

@node Type conversions,Incomplete Types,Thread safety without the GIL,ctypes tutorial
@anchor{library/ctypes ctypes-type-conversions}@anchor{3567}@anchor{library/ctypes type-conversions}@anchor{3568}
@subsubsection Type conversions


Usually, ctypes does strict type checking.  This means, if you have
@code{POINTER(c_int)} in the @ref{1a00,,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{1a00,,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{3558,,byref()} conversion in this case automatically.

To set a POINTER type field to @code{NULL}, you can assign @code{None}:

@example
>>> bar.values = None
>>>
@end example

@c XXX list other conversions...

Sometimes you have instances of incompatible types.  In C, you can cast one type
into another type.  @code{ctypes} provides a @ref{3569,,cast()} function which can be
used in the same way.  The @code{Bar} structure defined above accepts
@code{POINTER(c_int)} pointers or @ref{3527,,c_int} arrays for its @code{values} field,
but not instances of other 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

For these cases, the @ref{3569,,cast()} function is handy.

The @ref{3569,,cast()} function can be used to cast a ctypes instance into a pointer
to a different ctypes data type.  @code{cast()} takes two parameters, a ctypes
object that is or can be converted to a pointer of some kind, and a ctypes
pointer type.  It returns an instance of the second argument, which references
the same memory block as the first argument:

@example
>>> a = (c_byte * 4)()
>>> cast(a, POINTER(c_int))
<ctypes.LP_c_long object at ...>
>>>
@end example

So, @ref{3569,,cast()} can be used to assign to the @code{values} field of @code{Bar} the
structure:

@example
>>> bar = Bar()
>>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
>>> print(bar.values[0])
0
>>>
@end example

@node Incomplete Types,Callback functions,Type conversions,ctypes tutorial
@anchor{library/ctypes ctypes-incomplete-types}@anchor{584}@anchor{library/ctypes incomplete-types}@anchor{356a}
@subsubsection Incomplete Types


`Incomplete Types' are structures, unions or arrays whose members are not yet
specified. In C, they are specified by forward declarations, which are defined
later:

@example
struct cell; /* forward declaration */

struct cell @{
    char *name;
    struct cell *next;
@};
@end example

The straightforward translation into ctypes code would be this, but it does not
work:

@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 @code{ctypes}, we can define the @code{cell} class and set the
@ref{1b50,,_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

Let’s try it. We create two instances of @code{cell}, and let them point to each
other, and finally follow the pointer chain a few times:

@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 Callback functions,Accessing values exported from dlls,Incomplete Types,ctypes tutorial
@anchor{library/ctypes callback-functions}@anchor{356b}@anchor{library/ctypes ctypes-callback-functions}@anchor{356c}
@subsubsection Callback functions


@code{ctypes} allows creating C callable function pointers from Python callables.
These are sometimes called `callback functions'.

First, you must create a class for the callback function. The class knows the
calling convention, the return type, and the number and types of arguments this
function will receive.

The @ref{356d,,CFUNCTYPE()} factory function creates types for callback functions
using the @code{cdecl} calling convention. On Windows, the @ref{356e,,WINFUNCTYPE()}
factory function creates types for callback functions using the @code{stdcall}
calling convention.

Both of these factory functions are called with the result type as first
argument, and the callback functions expected argument types as the remaining
arguments.

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.

So our callback function receives pointers to integers, and must return an
integer. First we create the @code{type} for the callback function:

@example
>>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
>>>
@end example

To get started, here is a simple callback that shows the values it gets
passed:

@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

The result:

@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

Now we can actually compare the two items and return a useful result:

@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

As we can easily check, our array is sorted now:

@example
>>> for i in ia: print(i, end=" ")
...
1 5 7 33 99
>>>
@end example

The function factories can be used as decorator factories, so we may as well
write:

@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 Σημείωση 
Make sure you keep references to @ref{356d,,CFUNCTYPE()} objects as long as they
are used from C code. @code{ctypes} doesn’t, and if you don’t, they may be
garbage collected, crashing your program when a callback is made.

Also, note that if the callback function is called in a thread created
outside of Python’s control (e.g. by the foreign code that calls the
callback), ctypes creates a new dummy Python thread on every invocation. This
behavior is correct for most purposes, but it means that values stored with
@ref{1a87,,threading.local} will `not' survive across different callbacks, even when
those calls are made from the same C thread.
@end quotation
@end cartouche

@node Accessing values exported from dlls,Surprises,Callback functions,ctypes tutorial
@anchor{library/ctypes accessing-values-exported-from-dlls}@anchor{356f}@anchor{library/ctypes ctypes-accessing-values-exported-from-dlls}@anchor{3570}
@subsubsection Accessing values exported from dlls


Some shared libraries not only export functions, they also export variables. An
example in the Python library itself is the @ref{5ae,,Py_Version}, Python
runtime version number encoded in a single constant integer.

@code{ctypes} can access values like this with the @ref{3571,,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

An extended example which also demonstrates the use of pointers accesses the
@ref{3572,,PyImport_FrozenModules} pointer exported by Python.

Quoting the docs for that value:

@quotation

This pointer is initialized to point to an array of @ref{b57,,_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

So manipulating this pointer could even prove useful. To restrict the example
size, we show only how this table can be read with @code{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{b57,,_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

Since @code{table} is a @code{pointer} to the array of @code{struct_frozen} records, we
can iterate over it, but we just have to make sure that our loop terminates,
because pointers have no size. Sooner or later it would probably crash with an
access violation or whatever, so it’s better to break out of the loop when we
hit the @code{NULL} entry:

@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

The fact that standard Python has a frozen module and a frozen package
(indicated by the negative @code{size} member) is not well known, it is only used
for testing. Try it out with @code{import __hello__} for example.

@node Surprises,Variable-sized data types,Accessing values exported from dlls,ctypes tutorial
@anchor{library/ctypes ctypes-surprises}@anchor{3573}@anchor{library/ctypes surprises}@anchor{3574}
@subsubsection Surprises


There are some edges in @code{ctypes} where you might expect something other
than what actually happens.

Consider the following example:

@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

Hm. We certainly expected the last statement to print @code{3 4 1 2}. What
happened? Here are the steps of the @code{rc.a, rc.b = rc.b, rc.a} line above:

@example
>>> temp0, temp1 = rc.b, rc.a
>>> rc.a = temp0
>>> rc.b = temp1
>>>
@end example

Note that @code{temp0} and @code{temp1} are objects still using the internal buffer of
the @code{rc} object above. So executing @code{rc.a = temp0} copies the buffer
contents of @code{temp0} into @code{rc} “s buffer.  This, in turn, changes the
contents of @code{temp1}. So, the last assignment @code{rc.b = temp1}, doesn’t have
the expected effect.

Keep in mind that retrieving sub-objects from Structure, Unions, and Arrays
doesn’t `copy' the sub-object, instead it retrieves a wrapper object accessing
the root-object’s underlying buffer.

Another example that may behave differently from what one would expect is this:

@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 Σημείωση 
Objects instantiated from @ref{1c5d,,c_char_p} can only have their value set to bytes
or integers.
@end quotation
@end cartouche

Why is it printing @code{False}?  ctypes instances are objects containing a memory
block plus some @ref{21f,,descriptor}s accessing the contents of the memory.
Storing a Python object in the memory block does not store the object itself,
instead the @code{contents} of the object is stored.  Accessing the contents again
constructs a new Python object each time!

@node Variable-sized data types,,Surprises,ctypes tutorial
@anchor{library/ctypes ctypes-variable-sized-data-types}@anchor{3575}@anchor{library/ctypes variable-sized-data-types}@anchor{3576}
@subsubsection Variable-sized data types


@code{ctypes} provides some support for variable-sized arrays and structures.

The @ref{3577,,resize()} function can be used to resize the memory buffer of an
existing ctypes object.  The function takes the object as first argument, and
the requested size in bytes as the second argument.  The memory block cannot be
made smaller than the natural memory block specified by the objects type, a
@ref{277,,ValueError} is raised if this is tried:

@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

This is nice and fine, but how would one access the additional elements
contained in this array?  Since the type still only knows about 4 elements, we
get errors accessing other elements:

@example
>>> short_array[:]
[0, 0, 0, 0]
>>> short_array[7]
Traceback (most recent call last):
    ...
IndexError: invalid index
>>>
@end example

Another way to use variable-sized data types with @code{ctypes} is to use the
dynamic nature of Python, and (re-)define the data type after the required size
is already known, on a case by case basis.

@node ctypes reference,,ctypes tutorial,ctypes — A foreign function library for Python
@anchor{library/ctypes ctypes-ctypes-reference}@anchor{3578}@anchor{library/ctypes ctypes-reference}@anchor{3579}
@subsubsection ctypes reference


@menu
* Loading shared libraries:: 
* Finding shared libraries:: 
* Listing loaded shared libraries:: 
* Foreign functions:: 
* Function prototypes:: 
* Utility functions:: 
* Data types: Data types<2>. 
* Fundamental data types: Fundamental data types<2>. 
* Structured data types:: 
* Arrays and pointers:: 
* Exceptions: Exceptions<9>. 

@end menu

@node Loading shared libraries,Finding shared libraries,,ctypes reference
@anchor{library/ctypes ctypes-loading-shared-libraries}@anchor{357a}@anchor{library/ctypes loading-shared-libraries}@anchor{357b}
@subsubsection Loading shared libraries


There are several ways to load shared libraries into the Python process.  One
way is to instantiate @ref{dad,,CDLL} or one of its subclasses:

@geindex CDLL (κλάση σε ctypes)
@anchor{library/ctypes ctypes CDLL}@anchor{dad}
@deffn {Κλάση} ctypes.CDLL (name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

Represents a loaded shared library.

Functions in this library use the standard C calling convention, and are
assumed to return int.
The Python @ref{685,,global interpreter lock} is released before calling any
function exported by these libraries, and reacquired afterwards.
For different function behavior, use a subclass: @ref{1ce1,,OleDLL},
@ref{1ce2,,WinDLL}, or @ref{1ce3,,PyDLL}.

If you have an existing @ref{357c,,handle} to an already
loaded shared library, it can be passed as the `handle' argument to wrap
the opened library in a new @code{CDLL} object.
In this case, `name' is only used to set the @ref{357d,,_name}
attribute, but it may be adjusted and/or validated.

If `handle' is @code{None}, the underlying platform’s @code{dlopen(3)@footnote{https://manpages.debian.org/dlopen(3)}} or
LoadLibraryExW@footnote{https://learn.microsoft.com/en-us/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw} function is used to load the library into
the process, and to get a handle to it.

`name' is the pathname of the shared library to open.
If `name' does not contain a path separator, the library is found
in a platform-specific way.

On Windows, the @code{.DLL} suffix may be missing. (For details, see
LoadLibraryExW@footnote{https://learn.microsoft.com/en-us/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw} documentation.)
Other platform-specific prefixes and suffixes (for example, @code{lib},
@code{.so}, @code{.dylib}, or version numbers) must be present in `name';
they are not added automatically.
See @ref{357e,,Finding shared libraries} for more information.

On non-Windows systems, `name' can  be @code{None}. In this case,
@code{dlopen()} is called with @code{NULL}, which opens the main program
as a «library».
(Some systems do the same is `name' is empty; @code{None}/@code{NULL} is more
portable.)

@cartouche
@quotation CPython implementation detail 
Since CPython is linked to @code{libc}, a @code{None} `name' is often used
to access the C standard library:

@example
>>> printf = ctypes.CDLL(None).printf
>>> printf.argtypes = [ctypes.c_char_p]
>>> printf(b"hello\n")
hello
6
@end example

To access the Python C API, prefer @ref{357f,,ctypes.pythonapi} which
works across platforms.
@end quotation
@end cartouche

The `mode' parameter can be used to specify how the library is loaded.  For
details, consult the @code{dlopen(3)@footnote{https://manpages.debian.org/dlopen(3)}} manpage.  On Windows, `mode' is
ignored.  On posix systems, RTLD_NOW is always added, and is not
configurable.

The `use_errno' parameter, when set to true, enables a ctypes mechanism that
allows accessing the system @ref{5a,,errno} error number in a safe way.
@code{ctypes} maintains a thread-local copy of the system’s @code{errno}
variable; if you call foreign functions created with @code{use_errno=True} then the
@code{errno} value before the function call is swapped with the ctypes private
copy, the same happens immediately after the function call.

The function @ref{3580,,ctypes.get_errno()} returns the value of the ctypes private
copy, and the function @ref{3581,,ctypes.set_errno()} changes the ctypes private copy
to a new value and returns the former value.

The `use_last_error' parameter, when set to true, enables the same mechanism for
the Windows error code which is managed by the @ref{1963,,GetLastError()} and
@code{SetLastError()} Windows API functions; @ref{3582,,ctypes.get_last_error()} and
@ref{3583,,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
LoadLibraryExW@footnote{https://learn.microsoft.com/en-us/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw} 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.

On Windows creating a @code{CDLL} instance may fail even if the DLL name
exists. When a dependent DLL of the loaded DLL is not found, a
@ref{53c,,OSError} error is raised with the message `«[WinError 126] The
specified module could not be found».' This error message does not contain
the name of the missing DLL because the Windows API does not return this
information making this error hard to diagnose. To resolve this error and
determine which DLL is not found, you need to find the list of dependent
DLLs and determine which one is not found using Windows debugging and
tracing tools.


@subsubheading Δείτε επίσης


Microsoft DUMPBIN tool@footnote{https://learn.microsoft.com/en-us/cpp/build/reference/dumpbin-reference?view=msvc-170}
– A tool to find DLL dependents.



Άλλαξε στην έκδοση 3.8: Added `winmode' parameter.



Άλλαξε στην έκδοση 3.12: The `name' parameter can now be a @ref{79f,,path-like object}.


Instances of this class have no public methods.  Functions exported by the
shared library can be accessed as attributes or by index.  Please note that
accessing the function through an attribute caches the result and therefore
accessing it repeatedly returns the same object each time.  On the other hand,
accessing it through an index returns a new object each time:

@example
>>> from ctypes import CDLL
>>> libc = CDLL("libc.so.6")  # On Linux
>>> libc.time == libc.time
True
>>> libc['time'] == libc['time']
False
@end example

The following public attributes are available. Their name starts with an
underscore to not clash with exported function names:

@geindex _handle (ιδιότητα της ctypes.CDLL)
@anchor{library/ctypes ctypes CDLL _handle}@anchor{357c}
@deffn {Ιδιότητα} _handle

The system handle used to access the library.
@end deffn

@geindex _name (ιδιότητα της ctypes.CDLL)
@anchor{library/ctypes ctypes CDLL _name}@anchor{357d}
@deffn {Ιδιότητα} _name

The name of the library passed in the constructor.
@end deffn
@end deffn

@geindex OleDLL (κλάση σε ctypes)
@anchor{library/ctypes ctypes OleDLL}@anchor{1ce1}
@deffn {Κλάση} ctypes.OleDLL

See @ref{dad,,CDLL}, the superclass, for common information.

Functions in this library use the @code{stdcall} calling convention, and are
assumed to return the windows specific @ref{3584,,HRESULT} code.  @code{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{53c,,OSError} is automatically raised.

@ref{232d,,Διαθεσιμότητα}: Windows


Άλλαξε στην έκδοση 3.3: @ref{13fd,,WindowsError} used to be raised,
which is now an alias of @ref{53c,,OSError}.

@end deffn

@geindex WinDLL (κλάση σε ctypes)
@anchor{library/ctypes ctypes WinDLL}@anchor{1ce2}
@deffn {Κλάση} ctypes.WinDLL

See @ref{dad,,CDLL}, the superclass, for common information.

Functions in these libraries use the @code{stdcall} calling convention, and are
assumed to return int by default.

@ref{232d,,Διαθεσιμότητα}: Windows
@end deffn

@geindex PyDLL (κλάση σε ctypes)
@anchor{library/ctypes ctypes PyDLL}@anchor{1ce3}
@deffn {Κλάση} ctypes.PyDLL

See @ref{dad,,CDLL}, the superclass, for common information.

When functions in this library are called, the
Python GIL is `not' released during the function call, and after the function
execution the Python error flag is checked. If the error flag is set, a Python
exception is raised.

Thus, this is only useful to call Python C API functions directly.
@end deffn

@geindex RTLD_GLOBAL (στη μονάδα ctypes)
@anchor{library/ctypes ctypes RTLD_GLOBAL}@anchor{3585}
@deffn {Δεδομένα} ctypes.RTLD_GLOBAL

Flag to use as `mode' parameter.  On platforms where this flag is not available,
it is defined as the integer zero.
@end deffn

@geindex RTLD_LOCAL (στη μονάδα ctypes)
@anchor{library/ctypes ctypes RTLD_LOCAL}@anchor{3586}
@deffn {Δεδομένα} ctypes.RTLD_LOCAL

Flag to use as `mode' parameter.  On platforms where this is not available, it
is the same as `RTLD_GLOBAL'.
@end deffn

@geindex DEFAULT_MODE (στη μονάδα ctypes)
@anchor{library/ctypes ctypes DEFAULT_MODE}@anchor{3587}
@deffn {Δεδομένα} ctypes.DEFAULT_MODE

The default mode which is used to load shared libraries.  On OSX 10.3, this is
`RTLD_GLOBAL', otherwise it is the same as `RTLD_LOCAL'.
@end deffn

Shared libraries can also be loaded by using one of the prefabricated objects,
which are instances of the @ref{3588,,LibraryLoader} class, either by calling the
@ref{352e,,LoadLibrary()} method, or by retrieving the library as
attribute of the loader instance.

@geindex LibraryLoader (κλάση σε ctypes)
@anchor{library/ctypes ctypes LibraryLoader}@anchor{3588}
@deffn {Κλάση} ctypes.LibraryLoader (dlltype)

Class which loads shared libraries.  `dlltype' should be one of the
@ref{dad,,CDLL}, @ref{1ce3,,PyDLL}, @ref{1ce2,,WinDLL}, or @ref{1ce1,,OleDLL} types.

@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() (μέθοδος της ctypes.LibraryLoader)
@anchor{library/ctypes ctypes LibraryLoader LoadLibrary}@anchor{352e}
@deffn {Μέθοδος} LoadLibrary (name)

Load a shared library into the process and return it.  This method always
returns a new instance of the library.
@end deffn
@end deffn

These prefabricated library loaders are available:

@quotation

@geindex cdll (στη μονάδα ctypes)
@anchor{library/ctypes ctypes cdll}@anchor{352b}
@deffn {Δεδομένα} ctypes.cdll

Creates @ref{dad,,CDLL} instances.
@end deffn

@geindex windll (στη μονάδα ctypes)
@anchor{library/ctypes ctypes windll}@anchor{352c}
@deffn {Δεδομένα} ctypes.windll

Creates @ref{1ce2,,WinDLL} instances.

@ref{232d,,Διαθεσιμότητα}: Windows
@end deffn

@geindex oledll (στη μονάδα ctypes)
@anchor{library/ctypes ctypes oledll}@anchor{352d}
@deffn {Δεδομένα} ctypes.oledll

Creates @ref{1ce1,,OleDLL} instances.

@ref{232d,,Διαθεσιμότητα}: Windows
@end deffn

@geindex pydll (στη μονάδα ctypes)
@anchor{library/ctypes ctypes pydll}@anchor{3589}
@deffn {Δεδομένα} ctypes.pydll

Creates @ref{1ce3,,PyDLL} instances.
@end deffn

@geindex pythonapi (στη μονάδα ctypes)
@anchor{library/ctypes ctypes pythonapi}@anchor{357f}
@deffn {Δεδομένα} ctypes.pythonapi

An instance of @ref{1ce3,,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
@end quotation


Loading a library through any of these objects raises an
@ref{1e65,,auditing event} @code{ctypes.dlopen} with string argument
@code{name}, the name used to load the library.



Accessing a function on a loaded library raises an auditing event
@code{ctypes.dlsym} with arguments @code{library} (the library object) and @code{name}
(the symbol’s name as a string or integer).



In cases when only the library handle is available rather than the object,
accessing a function raises an auditing event @code{ctypes.dlsym/handle} with
arguments @code{handle} (the raw library handle) and @code{name}.


@node Finding shared libraries,Listing loaded shared libraries,Loading shared libraries,ctypes reference
@anchor{library/ctypes ctypes-finding-shared-libraries}@anchor{357e}@anchor{library/ctypes finding-shared-libraries}@anchor{358a}
@subsubsection Finding shared libraries


When programming in a compiled language, shared libraries are accessed when
compiling/linking a program, and when the program is run.
The programmer specifies a short name; the C compiler, linker, and
runtime dynamic library loader then interact in system-specific ways to find
the filename of the library to load.

While the mapping from short names to filenames is not consistently exposed
by platforms, the @code{ctypes.util} module provides a function,
@code{find_library()}, that attempts to match it.
However, as backwards compatibility concerns make it difficult to adjust
its behavior for new platforms and configurations, the function
is @ref{1a7,,soft deprecated}.

If wrapping a shared library with @code{ctypes}, consider determining the
shared library name at development time, and hardcoding it into the wrapper
module instead of using @code{find_library()} to locate the library
at runtime.
Also consider adding a configuration option or environment variable to let
users select a library to use, and then perhaps use @code{find_library()}
as a default or fallback.

@geindex find_library() (στη μονάδα ctypes.util)
@anchor{library/ctypes ctypes util find_library}@anchor{10fe}
@deffn {Συνάρτηση} ctypes.util.find_library (name)

Try to find a library and return a pathname.

`name' is the «short» 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}.)
The result is in a format suitable for passing to @ref{dad,,CDLL}.

If no library can be found, return @code{None}.

The exact functionality is system dependent, and is `not guaranteed'
to match the behavior of the compiler, linker, and loader used for
(or by) Python.
It is recommended to only use this function as a default or fallback,


@ref{1a7,,Soft deprecated} since version 3.15: This function is kept for use in cases where it works, but not expected to
be updated for additional platforms and configurations.

@end deffn

On Linux, @code{find_library()} tries to run external
programs (@code{/sbin/ldconfig}, @code{gcc}, @code{objdump} and @code{ld}) to find the
library file.
If the output of these programs does not correspond to the dynamic
linker used by Python, the result of this function may be misleading.


Άλλαξε στην έκδοση 3.6: On Linux, the value of the environment variable @code{LD_LIBRARY_PATH} is used
when searching for libraries, if a library cannot be found by any other means.


Here are some examples:

@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, @code{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, @code{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}.

@geindex find_msvcrt() (στη μονάδα ctypes.util)
@anchor{library/ctypes ctypes util find_msvcrt}@anchor{358b}
@deffn {Συνάρτηση} 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.
Notably, this will happen for recent versions of the VC runtime library,
which are not directly loadable.

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{232d,,Διαθεσιμότητα}: Windows
@end deffn

@node Listing loaded shared libraries,Foreign functions,Finding shared libraries,ctypes reference
@anchor{library/ctypes ctypes-listing-loaded-shared-libraries}@anchor{358c}@anchor{library/ctypes listing-loaded-shared-libraries}@anchor{358d}
@subsubsection Listing loaded shared libraries


When writing code that relies on code loaded from shared libraries, it can be
useful to know which shared libraries have already been loaded into the current
process.

The @code{ctypes.util} module provides the @ref{483,,dllist()} function,
which calls the different APIs provided by the various platforms to help determine
which shared libraries have already been loaded into the current process.

The exact output of this function will be system dependent. On most platforms,
the first entry of this list represents the current process itself, which may
be an empty string.
For example, on glibc-based Linux, the return may look like:

@example
>>> from ctypes.util import dllist
>>> dllist()
['@w{'}, 'linux-vdso.so.1', '/lib/x86_64-linux-gnu/libm.so.6', '/lib/x86_64-linux-gnu/libc.so.6', ... ]
@end example

@node Foreign functions,Function prototypes,Listing loaded shared libraries,ctypes reference
@anchor{library/ctypes ctypes-foreign-functions}@anchor{358e}@anchor{library/ctypes foreign-functions}@anchor{358f}
@subsubsection Foreign functions


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{1af3,,_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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes _CFuncPtr}@anchor{1af3}
@deffn {Κλάση} ctypes._CFuncPtr

Base class for C callable foreign functions.

Instances of foreign functions are also C compatible data types; they
represent C function pointers.

This behavior can be customized by assigning to special attributes of the
foreign function object.

@geindex restype (ιδιότητα της ctypes._CFuncPtr)
@anchor{library/ctypes ctypes _CFuncPtr restype}@anchor{3554}
@deffn {Ιδιότητα} 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{3555,,errcheck} attribute.
@end deffn

@geindex argtypes (ιδιότητα της ctypes._CFuncPtr)
@anchor{library/ctypes ctypes _CFuncPtr argtypes}@anchor{1a00}
@deffn {Ιδιότητα} argtypes

Assign a tuple of ctypes types to specify the argument types that the
function accepts.  Functions using the @code{stdcall} calling convention can
only be called with the same number of arguments as the length of this
tuple; functions using the C calling convention accept additional,
unspecified arguments as well.

When a foreign function is called, each actual argument is passed to the
@ref{3551,,from_param()} class method of the items in the @ref{1a00,,argtypes}
tuple, this method allows adapting the actual argument to an object that
the foreign function accepts.  For example, a @ref{1c5d,,c_char_p} item in
the @code{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{3551,,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 (ιδιότητα της ctypes._CFuncPtr)
@anchor{library/ctypes ctypes _CFuncPtr errcheck}@anchor{3555}
@deffn {Ιδιότητα} errcheck

Assign a Python function or another callable to this attribute. The
callable will be called with three or more arguments:


@deffn {Συνάρτηση} callable (result, func, arguments)

`result' is what the foreign function returns, as specified by the
@code{restype} attribute.

`func' is the foreign function object itself, this allows reusing the
same callable object to check or post process the results of several
functions.

`arguments' is a tuple containing the parameters originally passed to
the function call, this allows specializing the behavior on the
arguments used.
@end deffn

The object that this function returns will be returned from the
foreign function call, but it can also check the result value
and raise an exception if the foreign function call failed.
@end deffn
@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.



Some ways to invoke foreign function calls as well as some of the
functions in this module may raise an auditing event
@code{ctypes.call_function} with arguments @code{function pointer} and @code{arguments}.


@node Function prototypes,Utility functions,Foreign functions,ctypes reference
@anchor{library/ctypes ctypes-function-prototypes}@anchor{3590}@anchor{library/ctypes function-prototypes}@anchor{3591}
@subsubsection Function prototypes


Foreign functions can also be created by instantiating function prototypes.
Function prototypes are similar to function prototypes in C; they describe a
function (return type, argument types, calling convention) without defining an
implementation.  The factory functions must be called with the desired result
type and the argument types of the function, and can be used as decorator
factories, and as such, be applied to functions through the @code{@@wrapper} syntax.
See @ref{356c,,Callback functions} for examples.

@geindex CFUNCTYPE() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes CFUNCTYPE}@anchor{356d}
@deffn {Συνάρτηση} ctypes.CFUNCTYPE (restype, *argtypes, use_errno=False, use_last_error=False)

The returned function prototype creates functions that use the standard C
calling convention.  The function will release the GIL during the call.  If
`use_errno' is set to true, the ctypes private copy of the system
@ref{5a,,errno} variable is exchanged with the real @code{errno} value before
and after the call; `use_last_error' does the same for the Windows error
code.
@end deffn

@geindex WINFUNCTYPE() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes WINFUNCTYPE}@anchor{356e}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Windows
@end deffn

@geindex PYFUNCTYPE() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes PYFUNCTYPE}@anchor{3592}
@deffn {Συνάρτηση} ctypes.PYFUNCTYPE (restype, *argtypes)

The returned function prototype creates functions that use the Python calling
convention.  The function will `not' release the GIL during the call.
@end deffn

Function prototypes created by these factory functions can be instantiated in
different ways, depending on the type and number of the parameters in the call:


@deffn {Συνάρτηση} prototype (address)

Returns a foreign function at the specified address which must be an integer.
@end deffn


@deffn {Συνάρτηση} prototype (callable)

Create a C callable function (a callback function) from a Python `callable'.
@end deffn


@deffn {Συνάρτηση} prototype (func_spec[, paramflags])

Returns a foreign function exported by a shared library. `func_spec' must
be a 2-tuple @code{(name_or_ordinal, library)}. The first item is the name of
the exported function as string, or the ordinal of the exported function
as small integer.  The second item is the shared library instance.
@end deffn


@deffn {Συνάρτηση} prototype (vtbl_index, name[, paramflags[, iid]])

Returns a foreign function that will call a COM method. `vtbl_index' is
the index into the virtual function table, a small non-negative
integer. `name' is name of the COM method. `iid' is an optional pointer to
the interface identifier which is used in extended error reporting.

If `iid' is not specified, an @ref{53c,,OSError} is raised if the COM method
call fails. If `iid' is specified, a @ref{47f,,COMError} is raised
instead.

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.

@ref{232d,,Διαθεσιμότητα}: Windows
@end deffn

The optional `paramflags' parameter creates foreign function wrappers with much
more functionality than the features described above.

`paramflags' must be a tuple of the same length as @ref{1a00,,argtypes}.

Each item in this tuple contains further information about a parameter, it must
be a tuple containing one, two, or three items.

The first item is an integer containing a combination of direction
flags for the parameter:

@quotation


@table @asis

@item 1

Specifies an input parameter to the function.

@item 2

Output parameter.  The foreign function fills in a value.

@item 4

Input parameter which defaults to the integer zero.
@end table
@end quotation

The optional second item is the parameter name as string.  If this is specified,
the foreign function can be called with named parameters.

The optional third item is the default value for this parameter.

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

Here is the wrapping with @code{ctypes}:

@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

The @code{MessageBox} foreign function can now be called in these ways:

@example
>>> MessageBox()
>>> MessageBox(text="Spam, spam, spam")
>>> MessageBox(flags=2, text="foo bar")
@end example

A second example demonstrates output parameters.  The win32 @code{GetWindowRect}
function retrieves the dimensions of a specified window by copying them into
@code{RECT} structure that the caller has to supply.  Here is the C declaration:

@example
WINUSERAPI BOOL WINAPI
GetWindowRect(
     HWND hWnd,
     LPRECT lpRect);
@end example

Here is the wrapping with @code{ctypes}:

@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

Functions with output parameters will automatically return the output parameter
value if there is a single one, or a tuple containing the output parameter
values when there are more than one, so the GetWindowRect function now returns a
RECT instance, when called.

Output parameters can be combined with the @ref{3555,,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{3555,,errcheck} function returns the argument tuple it receives
unchanged, @code{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 Utility functions,Data types<2>,Function prototypes,ctypes reference
@anchor{library/ctypes ctypes-utility-functions}@anchor{3593}@anchor{library/ctypes utility-functions}@anchor{3594}
@subsubsection Utility functions


@geindex addressof() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes addressof}@anchor{3595}
@deffn {Συνάρτηση} ctypes.addressof (obj)

Returns the address of the memory buffer as integer.  `obj' must be an
instance of a ctypes type.

Raises an @ref{1e65,,auditing event} @code{ctypes.addressof} with argument @code{obj}.
@end deffn

@geindex alignment() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes alignment}@anchor{3596}
@deffn {Συνάρτηση} 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() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes byref}@anchor{3558}
@deffn {Συνάρτηση} 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 CopyComPointer() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes CopyComPointer}@anchor{480}
@deffn {Συνάρτηση} ctypes.CopyComPointer (src, dst)

Copies a COM pointer from `src' to `dst' and returns the Windows specific
@code{HRESULT} value.

If `src' is not @code{NULL}, its @code{AddRef} method is called, incrementing the
reference count.

In contrast, the reference count of `dst' will not be decremented before
assigning the new value. Unless `dst' is @code{NULL}, the caller is responsible
for decrementing the reference count by calling its @code{Release} method when
necessary.

@ref{232d,,Διαθεσιμότητα}: Windows


Added in version 3.14.

@end deffn

@geindex cast() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes cast}@anchor{3569}
@deffn {Συνάρτηση} 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() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes create_string_buffer}@anchor{3548}
@deffn {Συνάρτηση} ctypes.create_string_buffer (init, size=None)

@deffnx {Συνάρτηση} ctypes.create_string_buffer (size)

This function creates a mutable character buffer. The returned object is a
ctypes array of @ref{3535,,c_char}.

If `size' is given (and not @code{None}), it must be an @ref{326,,int}.
It specifies the size of the returned array.

If the `init' argument is given, it must be @ref{1c7,,bytes}. It is used
to initialize the array items. Bytes not initialized this way are
set to zero (NUL).

If `size' is not given (or if it is @code{None}), the buffer is made one element
larger than `init', effectively adding a NUL terminator.

If both arguments are given, `size' must not be less than @code{len(init)}.

@cartouche
@quotation Προειδοποίηση 
If `size' is equal to @code{len(init)}, a NUL terminator is
not added. Do not treat such a buffer as a C string.
@end quotation
@end cartouche

For example:

@example
>>> bytes(create_string_buffer(2))
b'\x00\x00'
>>> bytes(create_string_buffer(b'ab'))
b'ab\x00'
>>> bytes(create_string_buffer(b'ab', 2))
b'ab'
>>> bytes(create_string_buffer(b'ab', 4))
b'ab\x00\x00'
>>> bytes(create_string_buffer(b'abcdef', 2))
Traceback (most recent call last):
   ...
ValueError: byte string too long
@end example

Raises an @ref{1e65,,auditing event} @code{ctypes.create_string_buffer} with arguments @code{init}, @code{size}.
@end deffn

@geindex create_unicode_buffer() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes create_unicode_buffer}@anchor{1fa4}
@deffn {Συνάρτηση} ctypes.create_unicode_buffer (init, size=None)

@deffnx {Συνάρτηση} ctypes.create_unicode_buffer (size)

This function creates a mutable unicode character buffer. The returned object is
a ctypes array of @ref{3536,,c_wchar}.

The function takes the same arguments as @ref{3548,,create_string_buffer()} except
`init' must be a string and `size' counts @ref{3536,,c_wchar}.

Raises an @ref{1e65,,auditing event} @code{ctypes.create_unicode_buffer} with arguments @code{init}, @code{size}.
@end deffn

@geindex DllCanUnloadNow() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes DllCanUnloadNow}@anchor{3597}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Windows
@end deffn

@geindex DllGetClassObject() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes DllGetClassObject}@anchor{3598}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Windows
@end deffn

@geindex dllist() (στη μονάδα ctypes.util)
@anchor{library/ctypes ctypes util dllist}@anchor{483}
@deffn {Συνάρτηση} ctypes.util.dllist ()

Try to provide a list of paths of the shared libraries loaded into the current
process.  These paths are not normalized or processed in any way.  The function
can raise @ref{53c,,OSError} if the underlying platform APIs fail.
The exact functionality is system dependent.

On most platforms, the first element of the list represents the current
executable file. It may be an empty string.

@ref{232d,,Διαθεσιμότητα}: Windows, macOS, iOS, glibc, BSD libc, musl


Added in version 3.14.

@end deffn

@geindex FormatError() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes FormatError}@anchor{3599}
@deffn {Συνάρτηση} 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
@ref{1963,,GetLastError()}.

@ref{232d,,Διαθεσιμότητα}: Windows
@end deffn

@geindex GetLastError() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes GetLastError}@anchor{1963}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Windows
@end deffn

@geindex get_errno() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes get_errno}@anchor{3580}
@deffn {Συνάρτηση} ctypes.get_errno ()

Returns the current value of the ctypes-private copy of the system
@ref{5a,,errno} variable in the calling thread.

Raises an @ref{1e65,,auditing event} @code{ctypes.get_errno} with no arguments.
@end deffn

@geindex get_last_error() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes get_last_error}@anchor{3582}
@deffn {Συνάρτηση} ctypes.get_last_error ()

Returns the current value of the ctypes-private copy of the system
@code{LastError} variable in the calling thread.

@ref{232d,,Διαθεσιμότητα}: Windows

Raises an @ref{1e65,,auditing event} @code{ctypes.get_last_error} with no arguments.
@end deffn

@geindex memmove() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes memmove}@anchor{359a}
@deffn {Συνάρτηση} 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() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes memset}@anchor{359b}
@deffn {Συνάρτηση} 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() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes POINTER}@anchor{484}
@deffn {Συνάρτηση} ctypes.POINTER (type, /)

Create or return a ctypes pointer type. Pointer types are cached and
reused internally, so calling this function repeatedly is cheap.
`type' must be a ctypes type.

`Λεπτομέρεια υλοποίησης CPython:' The resulting pointer type is cached in the @code{__pointer_type__}
attribute of `type'.
It is possible to set this attribute before the first call to
@code{POINTER} in order to set a custom pointer type.
However, doing this is discouraged: manually creating a suitable
pointer type is difficult without relying on implementation
details that may change in future Python versions.
@end deffn

@geindex pointer() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes pointer}@anchor{1c5c}
@deffn {Συνάρτηση} 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() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes resize}@anchor{3577}
@deffn {Συνάρτηση} 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() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes set_errno}@anchor{3581}
@deffn {Συνάρτηση} ctypes.set_errno (value)

Set the current value of the ctypes-private copy of the system @ref{5a,,errno}
variable in the calling thread to `value' and return the previous value.

Raises an @ref{1e65,,auditing event} @code{ctypes.set_errno} with argument @code{errno}.
@end deffn

@geindex set_last_error() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes set_last_error}@anchor{3583}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Windows

Raises an @ref{1e65,,auditing event} @code{ctypes.set_last_error} with argument @code{error}.
@end deffn

@geindex sizeof() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes sizeof}@anchor{359c}
@deffn {Συνάρτηση} 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() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes string_at}@anchor{482}
@deffn {Συνάρτηση} 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{1e65,,auditing event} @code{ctypes.string_at} with arguments @code{ptr}, @code{size}.
@end deffn

@geindex WinError() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes WinError}@anchor{359d}
@deffn {Συνάρτηση} ctypes.WinError (code=None, descr=None)

Creates an instance of @ref{53c,,OSError}.  If `code' is not specified,
@ref{1963,,GetLastError()} is called to determine the error code. If `descr' is not
specified, @ref{3599,,FormatError()} is called to get a textual description of the
error.

@ref{232d,,Διαθεσιμότητα}: Windows


Άλλαξε στην έκδοση 3.3: An instance of @ref{13fd,,WindowsError} used to be created, which is now an
alias of @ref{53c,,OSError}.

@end deffn

@geindex wstring_at() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes wstring_at}@anchor{359e}
@deffn {Συνάρτηση} 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{1e65,,auditing event} @code{ctypes.wstring_at} with arguments @code{ptr}, @code{size}.
@end deffn

@geindex memoryview_at() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes memoryview_at}@anchor{481}
@deffn {Συνάρτηση} ctypes.memoryview_at (ptr, size, readonly=False)

Return a @ref{1d2,,memoryview} object of length `size' that references memory
starting at `void *ptr'.

If `readonly' is true, the returned @code{memoryview} object can
not be used to modify the underlying memory.
(Changes made by other means will still be reflected in the returned
object.)

This function is similar to @ref{482,,string_at()} with the key
difference of not making a copy of the specified memory.
It is a semantically equivalent (but more efficient) alternative to
@code{memoryview((c_byte * size).from_address(ptr))}.
(While @ref{359f,,from_address()} only takes integers, `ptr' can also
be given as a @ref{484,,ctypes.POINTER} or a @ref{3558,,byref()} object.)

Raises an @ref{1e65,,auditing event} @code{ctypes.memoryview_at} with arguments @code{address}, @code{size}, @code{readonly}.


Added in version 3.14.

@end deffn

@node Data types<2>,Fundamental data types<2>,Utility functions,ctypes reference
@anchor{library/ctypes ctypes-data-types}@anchor{35a0}@anchor{library/ctypes data-types}@anchor{35a1}
@subsubsection Data types


@geindex _CData (κλάση σε ctypes)
@anchor{library/ctypes ctypes _CData}@anchor{35a2}
@deffn {Κλάση} 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{3595,,addressof()} helper function. Another instance variable is exposed as
@ref{35a3,,_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{25c5,,metaclass}):

@geindex from_buffer() (μέθοδος της ctypes._CData)
@anchor{library/ctypes ctypes _CData from_buffer}@anchor{35a4}
@deffn {Μέθοδος} 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{277,,ValueError} is raised.

Raises an @ref{1e65,,auditing event} @code{ctypes.cdata/buffer} with arguments @code{pointer}, @code{size}, @code{offset}.
@end deffn

@geindex from_buffer_copy() (μέθοδος της ctypes._CData)
@anchor{library/ctypes ctypes _CData from_buffer_copy}@anchor{35a5}
@deffn {Μέθοδος} 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{277,,ValueError} is
raised.

Raises an @ref{1e65,,auditing event} @code{ctypes.cdata/buffer} with arguments @code{pointer}, @code{size}, @code{offset}.
@end deffn

@geindex from_address() (μέθοδος της ctypes._CData)
@anchor{library/ctypes ctypes _CData from_address}@anchor{359f}
@deffn {Μέθοδος} 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{1e65,,auditing event} @code{ctypes.cdata} with argument
@code{address}.

@end deffn

@geindex from_param() (μέθοδος της ctypes._CData)
@anchor{library/ctypes ctypes _CData from_param}@anchor{3551}
@deffn {Μέθοδος} 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{1a00,,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() (μέθοδος της ctypes._CData)
@anchor{library/ctypes ctypes _CData in_dll}@anchor{3571}
@deffn {Μέθοδος} 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 class variables of ctypes data types:

@geindex __pointer_type__ (ιδιότητα της ctypes._CData)
@anchor{library/ctypes ctypes _CData __pointer_type__}@anchor{485}
@deffn {Ιδιότητα} __pointer_type__

The pointer type that was created by calling
@ref{484,,POINTER()} for corresponding ctypes data type. If a pointer type
was not yet created, the attribute is missing.


Added in version 3.14.

@end deffn

Common instance variables of ctypes data types:

@geindex _b_base_ (ιδιότητα της ctypes._CData)
@anchor{library/ctypes ctypes _CData _b_base_}@anchor{35a6}
@deffn {Ιδιότητα} _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{35a6,,_b_base_} read-only member is the root ctypes object that owns the
memory block.
@end deffn

@geindex _b_needsfree_ (ιδιότητα της ctypes._CData)
@anchor{library/ctypes ctypes _CData _b_needsfree_}@anchor{35a7}
@deffn {Ιδιότητα} _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 (ιδιότητα της ctypes._CData)
@anchor{library/ctypes ctypes _CData _objects}@anchor{35a3}
@deffn {Ιδιότητα} _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 Fundamental data types<2>,Structured data types,Data types<2>,ctypes reference
@anchor{library/ctypes ctypes-fundamental-data-types-2}@anchor{35a8}@anchor{library/ctypes id1}@anchor{35a9}
@subsubsection Fundamental data types


@geindex _SimpleCData (κλάση σε ctypes)
@anchor{library/ctypes ctypes _SimpleCData}@anchor{35aa}
@deffn {Κλάση} 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.  @code{_SimpleCData} is a subclass of
@ref{35a2,,_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 (ιδιότητα της ctypes._SimpleCData)
@anchor{library/ctypes ctypes _SimpleCData value}@anchor{35ab}
@deffn {Ιδιότητα} 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.  @code{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

Each subclass has a class attribute:

@geindex _type_ (ιδιότητα της ctypes._SimpleCData)
@anchor{library/ctypes ctypes _SimpleCData _type_}@anchor{2cd}
@deffn {Ιδιότητα} _type_

Class attribute that contains an internal type code, as a
single-character string.
See @ref{2a32,,Fundamental data types} for a summary.

Types marked * in the summary may be (or always are) aliases of a
different @code{_SimpleCData} subclass, and will not necessarily
use the listed type code.
For example, if the platform’s long, long long
and time_t C types are the same, then @ref{3528,,c_long},
@ref{3543,,c_longlong} and @ref{1d61,,c_time_t} all refer to a single class,
@code{c_long}, whose @ref{2cd,,_type_} code is @code{'l'}.
The @code{'L'} code will be unused.


@subsubheading Δείτε επίσης


The @ref{8,,array} and @ref{2a2e,,struct} modules,
as well as third-party modules like numpy@footnote{https://numpy.org/doc/stable/reference/arrays.interface.html#object.__array_interface__},
use similar – but slightly different – type codes.

@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{3554,,restype} of @ref{1c5d,,c_char_p}, you will always receive a Python bytes
object, `not' a @code{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{1c5f,,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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_byte}@anchor{1cdf}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_char}@anchor{3535}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_char_p}@anchor{1c5d}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_double}@anchor{1eae}
@deffn {Κλάση} ctypes.c_double

Represents the C double datatype.  The constructor accepts an
optional float initializer.
@end deffn

@geindex c_longdouble (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_longdouble}@anchor{1eaf}
@deffn {Κλάση} 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{1eae,,c_double}.
@end deffn

@geindex c_float (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_float}@anchor{3546}
@deffn {Κλάση} ctypes.c_float

Represents the C float datatype.  The constructor accepts an
optional float initializer.
@end deffn

@geindex c_double_complex (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_double_complex}@anchor{2cf}
@deffn {Κλάση} ctypes.c_double_complex

Represents the C double complex datatype, if available.  The
constructor accepts an optional @ref{328,,complex} initializer.


Added in version 3.14.

@end deffn

@geindex c_float_complex (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_float_complex}@anchor{2ce}
@deffn {Κλάση} ctypes.c_float_complex

Represents the C float complex datatype, if available.  The
constructor accepts an optional @ref{328,,complex} initializer.


Added in version 3.14.

@end deffn

@geindex c_longdouble_complex (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_longdouble_complex}@anchor{2d0}
@deffn {Κλάση} ctypes.c_longdouble_complex

Represents the C long double complex datatype, if available.  The
constructor accepts an optional @ref{328,,complex} initializer.


Added in version 3.14.

@end deffn

@geindex c_int (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_int}@anchor{3527}
@deffn {Κλάση} 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{3528,,c_long}.
@end deffn

@geindex c_int8 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_int8}@anchor{3539}
@deffn {Κλάση} ctypes.c_int8

Represents the C 8-bit signed int datatype.  It is an alias for
@ref{1cdf,,c_byte}.
@end deffn

@geindex c_int16 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_int16}@anchor{353a}
@deffn {Κλάση} ctypes.c_int16

Represents the C 16-bit signed int datatype.  Usually an alias for
@ref{3537,,c_short}.
@end deffn

@geindex c_int32 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_int32}@anchor{353b}
@deffn {Κλάση} ctypes.c_int32

Represents the C 32-bit signed int datatype.  Usually an alias for
@ref{3527,,c_int}.
@end deffn

@geindex c_int64 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_int64}@anchor{353c}
@deffn {Κλάση} ctypes.c_int64

Represents the C 64-bit signed int datatype.  Usually an alias for
@ref{3543,,c_longlong}.
@end deffn

@geindex c_long (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_long}@anchor{3528}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_longlong}@anchor{3543}
@deffn {Κλάση} ctypes.c_longlong

Represents the C signed long long datatype.  The constructor accepts
an optional integer initializer; no overflow checking is done.
On platforms where @code{sizeof(long long) == sizeof(long)} it is an alias
to @ref{3528,,c_long}.
@end deffn

@geindex c_short (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_short}@anchor{3537}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_size_t}@anchor{3545}
@deffn {Κλάση} ctypes.c_size_t

Represents the C @code{size_t} datatype.
Usually an alias for another unsigned integer type.
@end deffn

@geindex c_ssize_t (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_ssize_t}@anchor{15e2}
@deffn {Κλάση} ctypes.c_ssize_t

Represents the @ref{e24,,Py_ssize_t} datatype.
This is a signed version of @code{size_t};
that is, the POSIX @code{ssize_t} type.
Usually an alias for another integer type.


Added in version 3.2.

@end deffn

@geindex c_time_t (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_time_t}@anchor{1d61}
@deffn {Κλάση} ctypes.c_time_t

Represents the C @code{time_t} datatype.
Usually an alias for another integer type.


Added in version 3.12.

@end deffn

@geindex c_ubyte (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_ubyte}@anchor{1ce0}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_uint}@anchor{353d}
@deffn {Κλάση} 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{3542,,c_ulong}.
@end deffn

@geindex c_uint8 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_uint8}@anchor{353e}
@deffn {Κλάση} ctypes.c_uint8

Represents the C 8-bit unsigned int datatype.  It is an alias for
@ref{1ce0,,c_ubyte}.
@end deffn

@geindex c_uint16 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_uint16}@anchor{353f}
@deffn {Κλάση} ctypes.c_uint16

Represents the C 16-bit unsigned int datatype.  Usually an alias for
@ref{3538,,c_ushort}.
@end deffn

@geindex c_uint32 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_uint32}@anchor{3540}
@deffn {Κλάση} ctypes.c_uint32

Represents the C 32-bit unsigned int datatype.  Usually an alias for
@ref{353d,,c_uint}.
@end deffn

@geindex c_uint64 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_uint64}@anchor{3541}
@deffn {Κλάση} ctypes.c_uint64

Represents the C 64-bit unsigned int datatype.  Usually an alias for
@ref{3544,,c_ulonglong}.
@end deffn

@geindex c_ulong (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_ulong}@anchor{3542}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_ulonglong}@anchor{3544}
@deffn {Κλάση} ctypes.c_ulonglong

Represents the C unsigned long long datatype.  The constructor
accepts an optional integer initializer; no overflow checking is done.
On platforms where @code{sizeof(long long) == sizeof(long)} it is an alias
to @ref{3528,,c_long}.
@end deffn

@geindex c_ushort (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_ushort}@anchor{3538}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_void_p}@anchor{1c5f}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_wchar}@anchor{3536}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_wchar_p}@anchor{1c5e}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes c_bool}@anchor{3534}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes HRESULT}@anchor{3584}
@deffn {Κλάση} ctypes.HRESULT

Represents a @code{HRESULT} value, which contains success or
error information for a function or method call.

@ref{232d,,Διαθεσιμότητα}: Windows
@end deffn

@geindex py_object (κλάση σε ctypes)
@anchor{library/ctypes ctypes py_object}@anchor{486}
@deffn {Κλάση} ctypes.py_object

Represents the C @ref{19b,,PyObject}* datatype.  Calling this without an
argument creates a @code{NULL} PyObject* pointer.


Άλλαξε στην έκδοση 3.14: @code{py_object} is now a @ref{1d1,,generic type}.

@end deffn
@anchor{library/ctypes ctypes-wintypes}@anchor{3547}
The @code{ctypes.wintypes} module provides quite some other Windows specific
data types, for example @code{HWND}, @code{WPARAM},
@code{VARIANT_BOOL} or @code{DWORD}.
Some useful structures like @code{MSG} or @code{RECT} are also defined.

@node Structured data types,Arrays and pointers,Fundamental data types<2>,ctypes reference
@anchor{library/ctypes ctypes-structured-data-types}@anchor{35ac}@anchor{library/ctypes structured-data-types}@anchor{35ad}
@subsubsection Structured data types


@geindex Union (κλάση σε ctypes)
@anchor{library/ctypes ctypes Union}@anchor{47d}
@deffn {Κλάση} ctypes.Union (*args, **kw)

Abstract base class for unions in native byte order.

Unions share common attributes and behavior with structures;
see @ref{47c,,Structure} documentation for details.
@end deffn

@geindex BigEndianUnion (κλάση σε ctypes)
@anchor{library/ctypes ctypes BigEndianUnion}@anchor{1db1}
@deffn {Κλάση} ctypes.BigEndianUnion (*args, **kw)

Abstract base class for unions in `big endian' byte order.


Added in version 3.11.

@end deffn

@geindex LittleEndianUnion (κλάση σε ctypes)
@anchor{library/ctypes ctypes LittleEndianUnion}@anchor{1db2}
@deffn {Κλάση} ctypes.LittleEndianUnion (*args, **kw)

Abstract base class for unions in `little endian' byte order.


Added in version 3.11.

@end deffn

@geindex BigEndianStructure (κλάση σε ctypes)
@anchor{library/ctypes ctypes BigEndianStructure}@anchor{355d}
@deffn {Κλάση} ctypes.BigEndianStructure (*args, **kw)

Abstract base class for structures in `big endian' byte order.
@end deffn

@geindex LittleEndianStructure (κλάση σε ctypes)
@anchor{library/ctypes ctypes LittleEndianStructure}@anchor{355e}
@deffn {Κλάση} 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 (κλάση σε ctypes)
@anchor{library/ctypes ctypes Structure}@anchor{47c}
@deffn {Κλάση} 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{1b50,,_fields_} class variable. @code{ctypes} will
create @ref{21f,,descriptor}s which allow reading and writing the fields by direct
attribute accesses.  These are the

@geindex _fields_ (ιδιότητα της ctypes.Structure)
@anchor{library/ctypes ctypes Structure _fields_}@anchor{1b50}
@deffn {Ιδιότητα} _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{3527,,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{1b50,,_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 @code{_fields_} class variable can only be set once.
Later assignments will raise an @ref{1a9,,AttributeError}.

Additionally, the @code{_fields_} class variable must be defined before
the structure or union type is first used: an instance or subclass is
created, @ref{359c,,sizeof()} is called on it, and so on.
Later assignments to @code{_fields_} will raise an @ref{1a9,,AttributeError}.
If @code{_fields_} has not been set before such use,
the structure or union will have no own fields, as if @code{_fields_}
was empty.

Sub-subclasses of structure types inherit the fields of the base class
plus the @ref{1b50,,_fields_} defined in the sub-subclass, if any.
@end deffn

@geindex _pack_ (ιδιότητα της ctypes.Structure)
@anchor{library/ctypes ctypes Structure _pack_}@anchor{318}
@deffn {Ιδιότητα} _pack_

An optional small integer that allows overriding the alignment of
structure fields in the instance.

This is only implemented for the MSVC-compatible memory layout
(see @ref{319,,_layout_}).

Setting @code{_pack_} to 0 is the same as not setting it at all.
Otherwise, the value must be a positive power of two.
The effect is equivalent to @code{#pragma pack(N)} in C, except
@code{ctypes} may allow larger `n' than what the compiler accepts.

@code{_pack_} must already be defined
when @ref{1b50,,_fields_} is assigned, otherwise it will have no effect.


Καταργήθηκε από την έκδοση 3.14, θα αφαιρεθεί στην έκδοση 3.19: For historical reasons, if @code{_pack_} is non-zero,
the MSVC-compatible layout will be used by default.
On non-Windows platforms, this default is deprecated and is slated to
become an error in Python 3.19.
If it is intended, set @ref{319,,_layout_} to @code{'ms'}
explicitly.

@end deffn

@geindex _align_ (ιδιότητα της ctypes.Structure)
@anchor{library/ctypes ctypes Structure _align_}@anchor{6ed}
@deffn {Ιδιότητα} _align_

An optional small integer that allows increasing the alignment of
the structure when being packed or unpacked to/from memory.

The value must not be negative.
The effect is equivalent to @code{__attribute__((aligned(N)))} on GCC
or @code{#pragma align(N)} on MSVC, except @code{ctypes} may allow
values that the compiler would reject.

@code{_align_} can only `increase' a structure’s alignment
requirements. Setting it to 0 or 1 has no effect.

Using values that are not powers of two is discouraged and may lead to
surprising behavior.

@code{_align_} must already be defined
when @ref{1b50,,_fields_} is assigned, otherwise it will have no effect.


Added in version 3.13.

@end deffn

@geindex _layout_ (ιδιότητα της ctypes.Structure)
@anchor{library/ctypes ctypes Structure _layout_}@anchor{319}
@deffn {Ιδιότητα} _layout_

An optional string naming the struct/union layout. It can currently
be set to:


@itemize -

@item 
@code{"ms"}: the layout used by the Microsoft compiler (MSVC).
On GCC and Clang, this layout can be selected with
@code{__attribute__((ms_struct))}.

@item 
@code{"gcc-sysv"}: the layout used by GCC with the System V or “SysV-like”
data model, as used on Linux and macOS.
With this layout, @ref{318,,_pack_} must be unset or zero.
@end itemize

If not set explicitly, @code{ctypes} will use a default that
matches the platform conventions. This default may change in future
Python releases (for example, when a new platform gains official support,
or when a difference between similar platforms is found).
Currently the default will be:


@itemize -

@item 
On Windows: @code{"ms"}

@item 
When @ref{318,,_pack_} is specified: @code{"ms"}.
(This is deprecated; see @code{_pack_} documentation.)

@item 
Otherwise: @code{"gcc-sysv"}
@end itemize

@code{_layout_} must already be defined when
@ref{1b50,,_fields_} is assigned, otherwise it will have no effect.


Added in version 3.14.

@end deffn

@geindex _anonymous_ (ιδιότητα της ctypes.Structure)
@anchor{library/ctypes ctypes Structure _anonymous_}@anchor{35ae}
@deffn {Ιδιότητα} _anonymous_

An optional sequence that lists the names of unnamed (anonymous) fields.
@ref{35ae,,_anonymous_} must be already defined when @ref{1b50,,_fields_} is
assigned, otherwise it will have no effect.

The fields listed in this variable must be structure or union type fields.
@code{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{1b50,,_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{1b50,,_fields_}.  Keyword arguments in the
constructor are interpreted as attribute assignments, so they will initialize
@code{_fields_} with the same name, or create new attributes for names not
present in @code{_fields_}.
@end deffn

@geindex CField (κλάση σε ctypes)
@anchor{library/ctypes ctypes CField}@anchor{47e}
@deffn {Κλάση} ctypes.CField (*args, **kw)

Descriptor for fields of a @ref{47c,,Structure} and @ref{47d,,Union}.
For example:

@example
>>> class Color(Structure):
...     _fields_ = (
...         ('red', c_uint8),
...         ('green', c_uint8),
...         ('blue', c_uint8),
...         ('intense', c_bool, 1),
...         ('blinking', c_bool, 1),
...    )
...
>>> Color.red
<ctypes.CField 'red' type=c_ubyte, ofs=0, size=1>
>>> Color.green.type
<class 'ctypes.c_ubyte'>
>>> Color.blue.byte_offset
2
>>> Color.intense
<ctypes.CField 'intense' type=c_bool, ofs=3, bit_size=1, bit_offset=0>
>>> Color.blinking.bit_offset
1
@end example

All attributes are read-only.

@code{CField} objects are created via @ref{1b50,,_fields_};
do not instantiate the class directly.


Added in version 3.14: Previously, descriptors only had @code{offset} and @code{size} attributes
and a readable string representation; the @code{CField} class was not
available directly.


@geindex name (ιδιότητα της ctypes.CField)
@anchor{library/ctypes ctypes CField name}@anchor{35af}
@deffn {Ιδιότητα} name

Name of the field, as a string.
@end deffn

@geindex type (ιδιότητα της ctypes.CField)
@anchor{library/ctypes ctypes CField type}@anchor{35b0}
@deffn {Ιδιότητα} type

Type of the field, as a @ref{35a0,,ctypes class}.
@end deffn

@geindex offset (ιδιότητα της ctypes.CField)
@geindex byte_offset (ιδιότητα της ctypes.CField)
@anchor{library/ctypes ctypes CField offset}@anchor{35b1}
@deffn {Ιδιότητα} offset
@anchor{library/ctypes ctypes CField byte_offset}@anchor{35b2}
@deffnx {Ιδιότητα} byte_offset

Offset of the field, in bytes.

For bitfields, this is the offset of the underlying byte-aligned
`storage unit'; see @ref{35b3,,bit_offset}.
@end deffn

@geindex byte_size (ιδιότητα της ctypes.CField)
@anchor{library/ctypes ctypes CField byte_size}@anchor{35b4}
@deffn {Ιδιότητα} byte_size

Size of the field, in bytes.

For bitfields, this is the size of the underlying `storage unit'.
Typically, it has the same size as the bitfield’s type.
@end deffn

@geindex size (ιδιότητα της ctypes.CField)
@anchor{library/ctypes ctypes CField size}@anchor{35b5}
@deffn {Ιδιότητα} size

For non-bitfields, equivalent to @ref{35b4,,byte_size}.

For bitfields, this contains a backwards-compatible bit-packed
value that combines @ref{35b6,,bit_size} and
@ref{35b3,,bit_offset}.
Prefer using the explicit attributes instead.
@end deffn

@geindex is_bitfield (ιδιότητα της ctypes.CField)
@anchor{library/ctypes ctypes CField is_bitfield}@anchor{35b7}
@deffn {Ιδιότητα} is_bitfield

True if this is a bitfield.
@end deffn

@geindex bit_offset (ιδιότητα της ctypes.CField)
@geindex bit_size (ιδιότητα της ctypes.CField)
@anchor{library/ctypes ctypes CField bit_offset}@anchor{35b3}
@deffn {Ιδιότητα} bit_offset
@anchor{library/ctypes ctypes CField bit_size}@anchor{35b6}
@deffnx {Ιδιότητα} bit_size

The location of a bitfield within its `storage unit', that is, within
@ref{35b4,,byte_size} bytes of memory starting at
@ref{35b2,,byte_offset}.

To get the field’s value, read the storage unit as an integer,
@ref{26c0,,shift left} by @code{bit_offset} and
take the @code{bit_size} least significant bits.

For non-bitfields, @code{bit_offset} is zero
and @code{bit_size} is equal to @code{byte_size * 8}.
@end deffn

@geindex is_anonymous (ιδιότητα της ctypes.CField)
@anchor{library/ctypes ctypes CField is_anonymous}@anchor{35b8}
@deffn {Ιδιότητα} is_anonymous

True if this field is anonymous, that is, it contains nested sub-fields
that should be merged into a containing structure or union.
@end deffn
@end deffn

@node Arrays and pointers,Exceptions<9>,Structured data types,ctypes reference
@anchor{library/ctypes arrays-and-pointers}@anchor{35b9}@anchor{library/ctypes ctypes-arrays-pointers}@anchor{35ba}
@subsubsection Arrays and pointers


@geindex Array (κλάση σε ctypes)
@anchor{library/ctypes ctypes Array}@anchor{1ffb}
@deffn {Κλάση} ctypes.Array (*args)

Abstract base class for arrays.

The recommended way to create concrete array types is by multiplying any
@code{ctypes} data type with a non-negative integer.  Alternatively, you can subclass
this type and define @ref{35bb,,_length_} and @ref{35bc,,_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 @code{Array}.

@geindex _length_ (ιδιότητα της ctypes.Array)
@anchor{library/ctypes ctypes Array _length_}@anchor{35bb}
@deffn {Ιδιότητα} _length_

A positive integer specifying the number of elements in the array.
Out-of-range subscripts result in an @ref{18d7,,IndexError}. Will be
returned by @ref{a1f,,len()}.
@end deffn

@geindex _type_ (ιδιότητα της ctypes.Array)
@anchor{library/ctypes ctypes Array _type_}@anchor{35bc}
@deffn {Ιδιότητα} _type_

Specifies the type of each element in the array.
@end deffn

Array subclass constructors accept positional arguments, used to
initialize the elements in order.
@end deffn

@geindex ARRAY() (στη μονάδα ctypes)
@anchor{library/ctypes ctypes ARRAY}@anchor{79d}
@deffn {Συνάρτηση} ctypes.ARRAY (type, length)

Create an array.
Equivalent to @code{type * length}, where `type' is a
@code{ctypes} data type and `length' an integer.


@ref{1a7,,Soft deprecated} since version 3.14: In favor of multiplication.

@end deffn

@geindex _Pointer (κλάση σε ctypes)
@anchor{library/ctypes ctypes _Pointer}@anchor{35bd}
@deffn {Κλάση} ctypes._Pointer

Private, abstract base class for pointers.

Concrete pointer types are created by calling @ref{484,,POINTER()} with the
type that will be pointed to; this is done automatically by
@ref{1c5c,,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{a1f,,len()} will raise @ref{291,,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_ (ιδιότητα της ctypes._Pointer)
@anchor{library/ctypes ctypes _Pointer _type_}@anchor{1a7a}
@deffn {Ιδιότητα} _type_

Specifies the type pointed to.
@end deffn

@geindex contents (ιδιότητα της ctypes._Pointer)
@anchor{library/ctypes ctypes _Pointer contents}@anchor{3564}
@deffn {Ιδιότητα} 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 Exceptions<9>,,Arrays and pointers,ctypes reference
@anchor{library/ctypes ctypes-exceptions}@anchor{35be}@anchor{library/ctypes exceptions}@anchor{35bf}
@subsubsection Exceptions


@geindex ArgumentError
@anchor{library/ctypes ctypes ArgumentError}@anchor{35c0}
@deffn {Εξαίρεση} ctypes.ArgumentError

This exception is raised when a foreign function call cannot convert one of the
passed arguments.
@end deffn

@geindex COMError
@anchor{library/ctypes ctypes COMError}@anchor{47f}
@deffn {Εξαίρεση} ctypes.COMError (hresult, text, details)

This exception is raised when a COM method call failed.

@geindex hresult (ιδιότητα της ctypes.COMError)
@anchor{library/ctypes ctypes COMError hresult}@anchor{35c1}
@deffn {Ιδιότητα} hresult

The integer value representing the error code.
@end deffn

@geindex text (ιδιότητα της ctypes.COMError)
@anchor{library/ctypes ctypes COMError text}@anchor{35c2}
@deffn {Ιδιότητα} text

The error message.
@end deffn

@geindex details (ιδιότητα της ctypes.COMError)
@anchor{library/ctypes ctypes COMError details}@anchor{35c3}
@deffn {Ιδιότητα} details

The 5-tuple @code{(descr, source, helpfile, helpcontext, progid)}.

`descr' is the textual description.  `source' is the language-dependent
@code{ProgID} for the class or application that raised the error.  `helpfile'
is the path of the help file.  `helpcontext' is the help context
identifier.  `progid' is the @code{ProgID} of the interface that defined the
error.
@end deffn

@ref{232d,,Διαθεσιμότητα}: Windows


Added in version 3.14.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Command-line interface libraries,Concurrent Execution,Generic Operating System Services,The Python Standard Library
@anchor{library/cmdlinelibs doc}@anchor{35c4}@anchor{library/cmdlinelibs cmdlinelibs}@anchor{35c5}@anchor{library/cmdlinelibs command-line-interface-libraries}@anchor{35c6}@anchor{library/cmdlinelibs translation-repo}@anchor{35c7}
@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 — Parser for command-line options@comma{} arguments and subcommands: argparse — Parser for command-line options arguments and subcommands. 
* optparse — Parser for command line options:: 
* getpass — Portable password input:: 
* fileinput — Iterate over lines from multiple input streams:: 
* curses — Terminal handling for character-cell displays:: 
* curses.textpad — Text input widget for curses programs: curses textpad — Text input widget for curses programs. 
* curses.ascii — Utilities for ASCII characters: curses ascii — Utilities for ASCII characters. 
* curses.panel — A panel stack extension for curses: curses panel — A panel stack extension for curses. 
* cmd — Support for line-oriented command interpreters:: 

@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{35c8}@anchor{library/argparse argparse-parser-for-command-line-options-arguments-and-subcommands}@anchor{35c9}@anchor{library/argparse module-argparse}@anchor{7}
@subsection @code{argparse} — Parser for command-line options, arguments and subcommands


@geindex module; argparse


Added in version 3.2.


`Source code:' Lib/argparse.py@footnote{https://github.com/python/cpython/tree/main/Lib/argparse.py}

@cartouche
@quotation Σημείωση 
While @code{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{35ca,,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 Tutorial



This page contains the API reference information. For a more gentle
introduction to Python command-line parsing, have a look at the
@ref{35cb,,argparse tutorial}.

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{1609,,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{1dc,,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

The @ref{3ed,,ArgumentParser.add_argument()} method attaches individual argument
specifications to the parser.  It supports positional arguments, options that
accept values, and on/off flags:

@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

The @ref{35cc,,ArgumentParser.parse_args()} method runs the parser and places
the extracted data in a @ref{35cd,,argparse.Namespace} object:

@example
args = parser.parse_args()
print(args.filename, args.count, args.verbose)
@end example

@cartouche
@quotation Σημείωση 
If you’re looking for a guide about how to upgrade @ref{a4,,optparse} code
to @code{argparse}, see @ref{1557,,Upgrading Optparse Code}.
@end quotation
@end cartouche

@menu
* ArgumentParser objects:: 
* The add_argument() method: The add_argument method. 
* The parse_args() method: The parse_args method. 
* Other utilities:: 
* Exceptions: Exceptions<10>. 

@end menu

@node ArgumentParser objects,The add_argument method,,argparse — Parser for command-line options arguments and subcommands
@anchor{library/argparse argumentparser-objects}@anchor{35ce}
@subsubsection ArgumentParser objects


@geindex ArgumentParser (κλάση σε argparse)
@anchor{library/argparse argparse ArgumentParser}@anchor{1dc}
@deffn {Κλάση} 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, *, suggest_on_error=True, color=True)

Create a new @code{ArgumentParser} object. All parameters should be passed
as keyword arguments. Each parameter has its own more detailed description
below, but in short they are:


@itemize *

@item 
@ref{457,,prog} - The name of the program (default: generated from the @code{__main__}
module attributes and @code{sys.argv[0]})

@item 
@ref{35cf,,usage} - The string describing the program usage (default: generated from
arguments added to parser)

@item 
@ref{35d0,,description} - Text to display before the argument help
(by default, no text)

@item 
@ref{35d1,,epilog} - Text to display after the argument help (by default, no text)

@item 
@ref{35d2,,parents} - A list of @code{ArgumentParser} objects whose arguments should
also be included

@item 
@ref{35d3,,formatter_class} - A class for customizing the help output

@item 
@ref{35d4,,prefix_chars} - The set of characters that prefix optional arguments
(default: “-“)

@item 
@ref{35d5,,fromfile_prefix_chars} - The set of characters that prefix files from
which additional arguments should be read (default: @code{None})

@item 
@ref{35d6,,argument_default} - The global default value for arguments
(default: @code{None})

@item 
@ref{35d7,,conflict_handler} - The strategy for resolving conflicting optionals
(usually unnecessary)

@item 
@ref{35d8,,add_help} - Add a @code{-h/--help} option to the parser (default: @code{True})

@item 
@ref{1178,,allow_abbrev} - Allows long options to be abbreviated if the
abbreviation is unambiguous (default: @code{True})

@item 
@ref{35d9,,exit_on_error} - Determines whether or not @code{ArgumentParser} exits with
error info when an error occurs. (default: @code{True})

@item 
@ref{35da,,suggest_on_error} - Enables suggestions for mistyped argument choices
and subparser names (default: @code{True})

@item 
@ref{35db,,color} - Allow color output (default: @code{True})
@end itemize


Άλλαξε στην έκδοση 3.5: `allow_abbrev' parameter was added.



Άλλαξε στην έκδοση 3.8: In previous versions, `allow_abbrev' also disabled grouping of short
flags such as @code{-vv} to mean @code{-v -v}.



Άλλαξε στην έκδοση 3.9: `exit_on_error' parameter was added.



Άλλαξε στην έκδοση 3.14: `suggest_on_error' and `color' parameters were added.



Άλλαξε στην έκδοση 3.15: `suggest_on_error' default changed to @code{True}.

@end deffn

The following sections describe how each of these are used.

@menu
* prog:: 
* usage:: 
* description:: 
* epilog:: 
* parents:: 
* formatter_class:: 
* prefix_chars:: 
* fromfile_prefix_chars:: 
* argument_default:: 
* allow_abbrev:: 
* conflict_handler:: 
* add_help:: 
* exit_on_error:: 
* suggest_on_error:: 
* color:: 

@end menu

@node prog,usage,,ArgumentParser objects
@anchor{library/argparse id1}@anchor{35dc}@anchor{library/argparse prog}@anchor{457}
@subsubsection prog


By default, @ref{1dc,,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{2e63,,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{4ca,,-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{1dc,,ArgumentParser}:

@example
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]

options:
 -h, --help  show this help message and exit
@end example

Note that the program name, whether determined from @code{sys.argv[0]},
from the @code{__main__} module attributes or from the
@code{prog=} argument, is available to help messages using the @code{%(prog)s} format
specifier.

@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


Άλλαξε στην έκδοση 3.14: The default @code{prog} value now reflects how @code{__main__} was actually executed,
rather than always being @code{os.path.basename(sys.argv[0])}.


@node usage,description,prog,ArgumentParser objects
@anchor{library/argparse usage}@anchor{35cf}
@subsubsection usage


By default, @ref{1dc,,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

The @code{%(prog)s} format specifier is available to fill in the program name in
your usage messages.

When a custom usage message is specified for the main parser, you may also want to
consider passing  the @code{prog} argument to @ref{fd6,,add_subparsers()}
or the @code{prog} and the @code{usage} arguments to
@ref{35dd,,add_parser()}, to ensure consistent command prefixes and
usage information across subparsers.

@node description,epilog,usage,ArgumentParser objects
@anchor{library/argparse description}@anchor{35d0}@anchor{library/argparse id2}@anchor{35de}
@subsubsection description


Most calls to the @ref{1dc,,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.

By default, the description will be line-wrapped so that it fits within the
given space.  To change this behavior, see the @ref{35d3,,formatter_class} argument.

@node epilog,parents,description,ArgumentParser objects
@anchor{library/argparse epilog}@anchor{35d1}
@subsubsection epilog


Some programs like to display additional description of the program after the
description of the arguments.  Such text can be specified using the @code{epilog=}
argument to @ref{1dc,,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

As with the @ref{35d0,,description} argument, the @code{epilog=} text is by default
line-wrapped, but this behavior can be adjusted with the @ref{35d3,,formatter_class}
argument to @ref{1dc,,ArgumentParser}.

@node parents,formatter_class,epilog,ArgumentParser objects
@anchor{library/argparse parents}@anchor{35d2}
@subsubsection parents


Sometimes, several parsers share a common set of arguments. Rather than
repeating the definitions of these arguments, a single parser with all the
shared arguments and passed to @code{parents=} argument to @ref{1dc,,ArgumentParser}
can be used.  The @code{parents=} argument takes a list of @code{ArgumentParser}
objects, collects all the positional and optional actions from them, and adds
these actions to the @code{ArgumentParser} object being constructed:

@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

Note that most parent parsers will specify @code{add_help=False}.  Otherwise, the
@ref{1dc,,ArgumentParser} will see two @code{-h/--help} options (one in the parent
and one in the child) and raise an error.

@cartouche
@quotation Σημείωση 
You must fully initialize the parsers before passing them via @code{parents=}.
If you change the parent parsers after the child parser, those changes will
not be reflected in the child.
@end quotation
@end cartouche

@node formatter_class,prefix_chars,parents,ArgumentParser objects
@anchor{library/argparse formatter-class}@anchor{35d3}@anchor{library/argparse id3}@anchor{35df}
@subsubsection formatter_class


@ref{1dc,,ArgumentParser} objects allow the help formatting to be customized by
specifying an alternate formatting class.  Currently, there are four such
classes:

@geindex RawDescriptionHelpFormatter (κλάση σε argparse)
@geindex RawTextHelpFormatter (κλάση σε argparse)
@geindex ArgumentDefaultsHelpFormatter (κλάση σε argparse)
@geindex MetavarTypeHelpFormatter (κλάση σε argparse)
@anchor{library/argparse argparse RawDescriptionHelpFormatter}@anchor{35e0}
@deffn {Κλάση} argparse.RawDescriptionHelpFormatter
@anchor{library/argparse argparse RawTextHelpFormatter}@anchor{35e1}
@deffnx {Κλάση} argparse.RawTextHelpFormatter
@anchor{library/argparse argparse ArgumentDefaultsHelpFormatter}@anchor{1e47}
@deffnx {Κλάση} argparse.ArgumentDefaultsHelpFormatter
@anchor{library/argparse argparse MetavarTypeHelpFormatter}@anchor{35e2}
@deffnx {Κλάση} argparse.MetavarTypeHelpFormatter
@end deffn

@ref{35e0,,RawDescriptionHelpFormatter} and @ref{35e1,,RawTextHelpFormatter} give
more control over how textual descriptions are displayed.
By default, @ref{1dc,,ArgumentParser} objects line-wrap the @ref{35d0,,description} and
@ref{35d1,,epilog} texts in command-line help messages:

@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

Passing @ref{35e0,,RawDescriptionHelpFormatter} as @code{formatter_class=}
indicates that @ref{35d0,,description} and @ref{35d1,,epilog} are already correctly formatted and
should not be line-wrapped:

@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{35e1,,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{1e47,,ArgumentDefaultsHelpFormatter} automatically adds information about
default values to each of the argument help messages:

@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{35e2,,MetavarTypeHelpFormatter} uses the name of the @ref{35e3,,type} argument for each
argument as the display name for its values (rather than using the @ref{35e4,,dest}
as the regular formatter does):

@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 prefix_chars,fromfile_prefix_chars,formatter_class,ArgumentParser objects
@anchor{library/argparse prefix-chars}@anchor{35d4}
@subsubsection 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{1dc,,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

The @code{prefix_chars=} argument defaults to @code{'-'}. Supplying a set of
characters that does not include @code{-} will cause @code{-f/--foo} options to be
disallowed.

@node fromfile_prefix_chars,argument_default,prefix_chars,ArgumentParser objects
@anchor{library/argparse fromfile-prefix-chars}@anchor{35d5}
@subsubsection fromfile_prefix_chars


Sometimes, when dealing with a particularly long argument list, it
may make sense to keep the list of arguments in a file rather than typing it out
at the command line.  If the @code{fromfile_prefix_chars=} argument is given to the
@ref{1dc,,ArgumentParser} constructor, then arguments that start with any of the
specified characters will be treated as files, and will be replaced by the
arguments they contain.  For example:

@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

Arguments read from a file must be one per line by default (but see also
@ref{35e5,,convert_arg_line_to_args()}) and are treated as if they
were in the same place as the original file referencing argument on the command
line.  So in the example above, the expression @code{['-f', 'foo', '@@args.txt']}
is considered equivalent to the expression @code{['-f', 'foo', '-f', 'bar']}.

@cartouche
@quotation Σημείωση 
Empty lines are treated as empty strings (@code{'@w{'}}), which are allowed as values but
not as arguments. Empty lines that are read as arguments will result in an
«unrecognized arguments» error.
@end quotation
@end cartouche

@ref{1dc,,ArgumentParser} uses @ref{948,,filesystem encoding and error handler}
to read the file containing arguments.

The @code{fromfile_prefix_chars=} argument defaults to @code{None}, meaning that
arguments will never be treated as file references.


Άλλαξε στην έκδοση 3.12: @ref{1dc,,ArgumentParser} changed encoding and errors to read arguments files
from default (e.g. @ref{947,,locale.getpreferredencoding(False)}
and @code{"strict"}) to the @ref{948,,filesystem encoding and error handler}.
Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows.


@node argument_default,allow_abbrev,fromfile_prefix_chars,ArgumentParser objects
@anchor{library/argparse argument-default}@anchor{35d6}
@subsubsection argument_default


Generally, argument defaults are specified either by passing a default to
@ref{3ed,,add_argument()} or by calling the
@ref{35e6,,set_defaults()} methods with a specific set of name-value
pairs.  Sometimes however, it may be useful to specify a single parser-wide
default for arguments.  This can be accomplished by passing the
@code{argument_default=} keyword argument to @ref{1dc,,ArgumentParser}.  For example,
to globally suppress attribute creation on @ref{35cc,,parse_args()}
calls, we supply @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 allow_abbrev,conflict_handler,argument_default,ArgumentParser objects
@anchor{library/argparse allow-abbrev}@anchor{1178}@anchor{library/argparse id4}@anchor{35e7}
@subsubsection allow_abbrev


Normally, when you pass an argument list to the
@ref{35cc,,parse_args()} method of an @ref{1dc,,ArgumentParser},
it @ref{1177,,recognizes abbreviations} of long options.

This feature can be disabled by setting @code{allow_abbrev} to @code{False}:

@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


Added in version 3.5.


@node conflict_handler,add_help,allow_abbrev,ArgumentParser objects
@anchor{library/argparse conflict-handler}@anchor{35d7}
@subsubsection conflict_handler


@ref{1dc,,ArgumentParser} objects do not allow two actions with the same option
string.  By default, @code{ArgumentParser} objects raise an exception if an
attempt is made to create an argument with an option string that is already in
use:

@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

Sometimes (e.g. when using @ref{35d2,,parents}) it may be useful to simply override any
older arguments with the same option string.  To get this behavior, the value
@code{'resolve'} can be supplied to the @code{conflict_handler=} argument of
@ref{1dc,,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

Note that @ref{1dc,,ArgumentParser} objects only remove an action if all of its
option strings are overridden.  So, in the example above, the old @code{-f/--foo}
action is retained as the @code{-f} action, because only the @code{--foo} option
string was overridden.

@node add_help,exit_on_error,conflict_handler,ArgumentParser objects
@anchor{library/argparse add-help}@anchor{35d8}
@subsubsection add_help


By default, @ref{1dc,,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.

Occasionally, it may be useful to disable the addition of this help option.
This can be achieved by passing @code{False} as the @code{add_help=} argument to
@ref{1dc,,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

The help option is typically @code{-h/--help}. The exception to this is
if the @code{prefix_chars=} is specified and does not include @code{-}, in
which case @code{-h} and @code{--help} are not valid options.  In
this case, the first character in @code{prefix_chars} is used to prefix
the help options:

@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 exit_on_error,suggest_on_error,add_help,ArgumentParser objects
@anchor{library/argparse exit-on-error}@anchor{35d9}
@subsubsection exit_on_error


Normally, when you pass an invalid argument list to the @ref{35cc,,parse_args()}
method of an @ref{1dc,,ArgumentParser}, it will print a `message' to @ref{d05,,sys.stderr} and exit with a status
code of 2.

If the user would like to catch errors manually, the feature can be enabled by setting
@code{exit_on_error} to @code{False}:

@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


Added in version 3.9.


@node suggest_on_error,color,exit_on_error,ArgumentParser objects
@anchor{library/argparse suggest-on-error}@anchor{35da}
@subsubsection suggest_on_error


By default, when a user passes an invalid argument choice or subparser name,
@ref{1dc,,ArgumentParser} will exit with error info and provide suggestions for
mistyped arguments. The error message will list the permissible argument
choices (if specified) or subparser names, along with a «maybe you meant»
suggestion if a close match is found. Note that this only applies for arguments
when the choices specified are strings:

@example
>>> parser = argparse.ArgumentParser(suggest_on_error=True)
>>> parser.add_argument('--action', choices=['debug', 'dryrun'])
>>> parser.parse_args(['--action', 'debugg'])
usage: tester.py [-h] [--action @{debug,dryrun@}]
tester.py: error: argument --action: invalid choice: 'debugg', maybe you meant 'debug'? (choose from debug, dryrun)
@end example

You can disable suggestions by setting @code{suggest_on_error} to @code{False}.


Added in version 3.14.



Άλλαξε στην έκδοση 3.15: Changed default value of @code{suggest_on_error} from @code{False} to @code{True}.


@node color,,suggest_on_error,ArgumentParser objects
@anchor{library/argparse color}@anchor{35db}
@subsubsection color


By default, the help message is printed in color using ANSI escape sequences@footnote{https://en.wikipedia.org/wiki/ANSI_escape_code}.
If you want plain text help messages, you can disable this @ref{1af,,in your local environment}, or in the argument parser itself
by setting @code{color} to @code{False}:

@example
>>> parser = argparse.ArgumentParser(description='Process some integers.',
...                                  color=False)
>>> parser.add_argument('--action', choices=['sum', 'max'])
>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
...                     help='an integer for the accumulator')
>>> parser.parse_args(['--help'])
@end example

Note that when @code{color=True}, colored output depends on both environment
variables and terminal capabilities.  However, if @code{color=False}, colored
output is always disabled, even if environment variables like @code{FORCE_COLOR}
are set.


Added in version 3.14.


To highlight inline code in your description, epilog, or argument @code{help}
text, you can use single or double backticks:

@example
>>> parser = argparse.ArgumentParser(
...     formatter_class=argparse.RawDescriptionHelpFormatter,
...     description='Run `@w{`}python -m myapp`@w{`} to start.',
...     epilog='@w{'}'Examples:
...   `python -m myapp --verbose`
...   `@w{`}python -m myapp --config settings.json`@w{`}
... '@w{'}')
>>> parser.add_argument('--foo', help='set the `foo` value')
@end example

When colors are enabled, the text inside backticks will be displayed in a
distinct color to help examples stand out. When colors are disabled, backticks
are preserved as-is, which is readable in plain text.


Added in version 3.15.


@node The add_argument method,The parse_args method,ArgumentParser objects,argparse — Parser for command-line options arguments and subcommands
@anchor{library/argparse the-add-argument-method}@anchor{35e8}
@subsubsection The add_argument() method


@geindex add_argument() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser add_argument}@anchor{3ed}
@deffn {Μέθοδος} ArgumentParser.add_argument (name or flags..., *[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest][, deprecated])

Define how a single command-line argument should be parsed.  Each parameter
has its own more detailed description below, but in short they are:


@itemize *

@item 
@ref{35e9,,name or flags} - Either a name or a list of option strings, e.g. @code{'foo'}
or @code{'-f', '--foo'}.

@item 
@ref{1b46,,action} - The basic type of action to be taken when this argument is
encountered at the command line.

@item 
@ref{1936,,nargs} - The number of command-line arguments that should be consumed.

@item 
@ref{1b4d,,const} - A constant value required by some @ref{1b46,,action} and @ref{1936,,nargs} selections.

@item 
@ref{1b4c,,default} - The value produced if the argument is absent from the
command line and if it is absent from the namespace object.

@item 
@ref{35e3,,type} - The type to which the command-line argument should be converted.

@item 
@ref{1b48,,choices} - A sequence of the allowable values for the argument.

@item 
@ref{35ea,,required} - Whether or not the command-line option may be omitted
(optionals only).

@item 
@ref{35eb,,help} - A brief description of what the argument does.

@item 
@ref{35ec,,metavar} - A name for the argument in usage messages.

@item 
@ref{35e4,,dest} - The name of the attribute to be added to the object returned by
@ref{35cc,,parse_args()}.

@item 
@ref{35ed,,deprecated} - Whether or not use of the argument is deprecated.
@end itemize

The method returns an @ref{1d88,,Action} object representing the argument.
@end deffn

The following sections describe how each of these are used.

@menu
* name or flags:: 
* action:: 
* nargs:: 
* const:: 
* default:: 
* type:: 
* choices:: 
* required:: 
* help:: 
* metavar:: 
* dest:: 
* deprecated:: 
* Action classes:: 

@end menu

@node name or flags,action,,The add_argument method
@anchor{library/argparse id5}@anchor{35ee}@anchor{library/argparse name-or-flags}@anchor{35e9}
@subsubsection name or flags


The @ref{3ed,,add_argument()} method must know whether an optional
argument, like @code{-f} or @code{--foo}, or a positional argument, like a list of
filenames, is expected.  The first arguments passed to
@code{add_argument()} must therefore be either a series of
flags, or a simple argument name.

For example, an optional argument could be created like:

@example
>>> parser.add_argument('-f', '--foo')
@end example

while a positional argument could be created like:

@example
>>> parser.add_argument('bar')
@end example

When @ref{35cc,,parse_args()} is called, optional arguments will be
identified by the @code{-} prefix, and the remaining arguments will be assumed to
be positional:

@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

By default, @code{argparse} automatically handles the internal naming and
display names of arguments, simplifying the process without requiring
additional configuration.
As such, you do not need to specify the @ref{35e4,,dest} and @ref{35ec,,metavar} parameters.
For optional arguments, the @ref{35e4,,dest} parameter defaults to the argument name, with
underscores @code{_} replacing hyphens @code{-}. The @ref{35ec,,metavar} parameter defaults to
the upper-cased name. For example:

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo-bar')
>>> parser.parse_args(['--foo-bar', 'FOO-BAR'])
Namespace(foo_bar='FOO-BAR')
>>> parser.print_help()
usage:  [-h] [--foo-bar FOO-BAR]

optional arguments:
 -h, --help  show this help message and exit
 --foo-bar FOO-BAR
@end example

@node action,nargs,name or flags,The add_argument method
@anchor{library/argparse action}@anchor{1b46}@anchor{library/argparse id6}@anchor{35ef}
@subsubsection action


@ref{1dc,,ArgumentParser} objects associate command-line arguments with actions.  These
actions can do just about anything with the command-line arguments associated with
them, though most actions simply add an attribute to the object returned by
@ref{35cc,,parse_args()}.  The @code{action} keyword argument specifies
how the command-line arguments should be handled. The supplied actions are:


@itemize *

@item 
@code{'store'} - This just stores the argument’s value.  This is the default
action.

@item 
@code{'store_const'} - This stores the value specified by the @ref{1b4d,,const} keyword
argument; note that the @ref{1b4d,,const} keyword argument defaults to @code{None}.  The
@code{'store_const'} action is most commonly used with optional arguments that
specify some sort of flag.  For example:

@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'} that respectively store the values @code{True} and @code{False}
with default values of @code{False} and
@code{True}:

@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'} - This appends each argument value to a list.
It is useful for allowing an option to be specified multiple times.
If the default value is a non-empty list, the parsed value will start
with the default list’s elements and any values from the command line
will be appended after those default values. Example usage:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append', default=['0'])
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['0', '1', '2'])
@end example

@item 
@code{'append_const'} - This appends the value specified by
the @ref{1b4d,,const} keyword argument to a list; note that the @ref{1b4d,,const} keyword
argument defaults to @code{None}. The @code{'append_const'} action is typically
useful when multiple arguments need to store constants to the same list. For
example:

@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 appends each item from a multi-value
argument to a list.
The @code{'extend'} action is typically used with the @ref{1936,,nargs} keyword argument
value @code{'+'} or @code{'*'}.
Note that when @ref{1936,,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


Added in version 3.8.


@item 
@code{'count'} - This counts the number of times an argument occurs. For
example, this is useful for increasing verbosity levels:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count', default=0)
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)
@end example

Note, the `default' will be @code{None} unless explicitly set to `0'.

@item 
@code{'help'} - This prints a complete help message for all the options in the
current parser and then exits. By default a help action is automatically
added to the parser. See @ref{1dc,,ArgumentParser} for details of how the
output is created.

@item 
@code{'version'} - This expects a @code{version=} keyword argument in the
@ref{3ed,,add_argument()} call, and prints version information
and exits when invoked:

@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

You may also specify an arbitrary action by passing an @ref{1d88,,Action} subclass
(e.g. @ref{1db,,BooleanOptionalAction}) or other object that implements the same
interface. Only actions that consume command-line arguments (e.g. @code{'store'},
@code{'append'}, @code{'extend'}, or custom actions with non-zero @code{nargs}) can be used
with positional arguments.

The recommended way to create a custom action is to extend @ref{1d88,,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{35f0,,register()} method and reference them by their registered name.

An example of a custom action:

@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

For more details, see @ref{1d88,,Action}.

@node nargs,const,action,The add_argument method
@anchor{library/argparse id7}@anchor{35f1}@anchor{library/argparse nargs}@anchor{1936}
@subsubsection nargs


@ref{1dc,,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{35f2,,Specifying ambiguous arguments}. The supported values are:


@itemize *

@item 
@code{N} (an integer).  @code{N} arguments from the command line will be gathered
together into a list.  For example:

@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

Note that @code{nargs=1} produces a list of one item.  This is different from
the default, in which the item is produced by itself.
@end itemize

@geindex ? (question mark);in argparse module


@itemize *

@item 
@code{'?'}. One argument will be consumed from the command line if possible, and
produced as a single item.  If no command-line argument is present, the value from
@ref{1b4c,,default} will be produced.  Note that for optional arguments, there is an
additional case - the option string is present but not followed by a
command-line argument.  In this case the value from @ref{1b4d,,const} will be produced.  Some
examples to illustrate this:

@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

One of the more common uses of @code{nargs='?'} is to allow optional input and
output files:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', nargs='?')
>>> parser.add_argument('outfile', nargs='?')
>>> parser.parse_args(['input.txt', 'output.txt'])
Namespace(infile='input.txt', outfile='output.txt')
>>> parser.parse_args(['input.txt'])
Namespace(infile='input.txt', outfile=None)
>>> parser.parse_args([])
Namespace(infile=None, outfile=None)
@end example
@end itemize

@geindex * (asterisk);in argparse module


@itemize *

@item 
@code{'*'}.  All command-line arguments present are gathered into a list.  Note that
it generally doesn’t make much sense to have more than one positional argument
with @code{nargs='*'}, but multiple optional arguments with @code{nargs='*'} is
possible.  For example:

@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{'+'}. Just like @code{'*'}, all command-line arguments present are gathered into a
list.  Additionally, an error message will be generated if there wasn’t at
least one command-line argument present.  For example:

@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{1b46,,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 const,default,nargs,The add_argument method
@anchor{library/argparse const}@anchor{1b4d}@anchor{library/argparse id8}@anchor{35f3}
@subsubsection const


The @code{const} argument of @ref{3ed,,add_argument()} is used to hold
constant values that are not read from the command line but are required for
the various @ref{1dc,,ArgumentParser} actions.  The two most common uses of it are:


@itemize *

@item 
When @ref{3ed,,add_argument()} is called with
@code{action='store_const'} or @code{action='append_const'}.  These actions add the
@code{const} value to one of the attributes of the object returned by
@ref{35cc,,parse_args()}. See the @ref{1b46,,action} description for examples.
If @code{const} is not provided to @code{add_argument()}, it will
receive a default value of @code{None}.

@item 
When @ref{3ed,,add_argument()} is called with option strings
(like @code{-f} or @code{--foo}) and @code{nargs='?'}.  This creates an optional
argument that can be followed by zero or one command-line arguments.
When parsing the command line, if the option string is encountered with no
command-line argument following it, the value from @code{const} will be used.
See the @ref{1936,,nargs} description for examples.
@end itemize


Άλλαξε στην έκδοση 3.11: @code{const=None} by default, including when @code{action='append_const'} or
@code{action='store_const'}.


@node default,type,const,The add_argument method
@anchor{library/argparse default}@anchor{1b4c}@anchor{library/argparse id9}@anchor{35f4}
@subsubsection default


All optional arguments and some positional arguments may be omitted at the
command line.  The @code{default} keyword argument of
@ref{3ed,,add_argument()}, whose value defaults to @code{None},
specifies what value should be used if the command-line argument is not present.
For optional arguments, the @code{default} value is used when the option string
was not present at the command line:

@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

If the @code{default} value is a string, the parser parses the value as if it
were a command-line argument.  In particular, the parser applies any @ref{35e3,,type}
conversion argument, if provided, before setting the attribute on the
@ref{35cd,,Namespace} return value.  Otherwise, the parser uses the value as is:

@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

For positional arguments with @ref{1936,,nargs} equal to @code{?} or @code{*}, the @code{default} value
is used when no command-line argument was present:

@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{35ea,,required} arguments, the @code{default} value is ignored. For example, this
applies to positional arguments with @ref{1936,,nargs} values other than @code{?} or @code{*},
or optional arguments marked as @code{required=True}.

Providing @code{default=argparse.SUPPRESS} causes no attribute to be added if the
command-line argument was not present:

@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 type,choices,default,The add_argument method
@anchor{library/argparse argparse-type}@anchor{35f5}@anchor{library/argparse type}@anchor{35e3}
@subsubsection type


By default, the parser reads command-line arguments in as simple
strings. However, quite often the command-line string should instead be
interpreted as another type, such as a @ref{327,,float} or @ref{326,,int}.  The
@code{type} keyword for @ref{3ed,,add_argument()} allows any
necessary type-checking and type conversions to be performed.

If the @ref{35e3,,type} keyword is used with the @ref{1b4c,,default} keyword, the type converter
is only applied if the default is a string.

The argument to @code{type} can be a callable that accepts a single string or
the name of a registered type (see @ref{35f0,,register()})
If the function raises @ref{35f6,,ArgumentTypeError}, @ref{291,,TypeError}, or
@ref{277,,ValueError}, the exception is caught and a nicely formatted error
message is displayed. Other exception types are not handled.

Common built-in types and functions can be used as type converters:

@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('datapath', type=pathlib.Path)
@end example

User defined functions can be used as well:

@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

The @ref{5ef,,bool()} function is not recommended as a type converter.  All it does
is convert empty strings to @code{False} and non-empty strings to @code{True}.
This is usually not what is desired:

@example
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('--verbose', type=bool)
>>> parser.parse_args(['--verbose', 'False'])
Namespace(verbose=True)
@end example

See @ref{1db,,BooleanOptionalAction} or @code{action='store_true'} for common
alternatives.

In general, the @code{type} keyword is a convenience that should only be used for
simple conversions that can only raise one of the three supported exceptions.
Anything with more interesting error-handling or resource management should be
done downstream after the arguments are parsed.

For example, JSON or YAML conversions have complex error cases that require
better reporting than can be given by the @code{type} keyword.  A
@ref{11d5,,JSONDecodeError} would not be well formatted and a
@ref{243,,FileNotFoundError} exception would not be handled at all.

Even @ref{31e,,FileType} has its limitations for use with the @code{type}
keyword.  If one argument uses @code{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{20a,,with}-statement to manage the
files.

For type checkers that simply check against a fixed set of values, consider
using the @ref{1b48,,choices} keyword instead.

@node choices,required,type,The add_argument method
@anchor{library/argparse choices}@anchor{1b48}@anchor{library/argparse id10}@anchor{35f7}
@subsubsection choices


Some command-line arguments should be selected from a restricted set of values.
These can be handled by passing a sequence object as the `choices' keyword
argument to @ref{3ed,,add_argument()}.  When the command line is
parsed, argument values will be checked, and an error message will be displayed
if the argument was not one of the acceptable values:

@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

Any sequence can be passed as the `choices' value, so @ref{4d9,,list} objects,
@ref{1ce,,tuple} objects, and custom sequences are all supported.

Use of @ref{a21,,enum.Enum} is not recommended because it is difficult to
control its appearance in usage, help, and error messages.

Note that `choices' are checked after any @ref{35e3,,type}
conversions have been performed, so objects in `choices'
should match the @ref{35e3,,type} specified. This can make `choices'
appear unfamiliar in usage, help, or error messages.

To keep `choices' user-friendly, consider a custom type wrapper that
converts and formats values, or omit @ref{35e3,,type} and handle conversion in
your application code.

Formatted choices override the default `metavar' which is normally derived
from `dest'.  This is usually what you want because the user never sees the
`dest' parameter.  If this display isn’t desirable (perhaps because there are
many choices), just specify an explicit @ref{35ec,,metavar}.

@node required,help,choices,The add_argument method
@anchor{library/argparse id11}@anchor{35f8}@anchor{library/argparse required}@anchor{35ea}
@subsubsection 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{3ed,,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

As the example shows, if an option is marked as @code{required},
@ref{35cc,,parse_args()} will report an error if that option is not
present at the command line.

@cartouche
@quotation Σημείωση 
Required options are generally considered bad form because users expect
`options' to be `optional', and thus they should be avoided when possible.
@end quotation
@end cartouche

@node help,metavar,required,The add_argument method
@anchor{library/argparse help}@anchor{35eb}@anchor{library/argparse id12}@anchor{35f9}
@subsubsection 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.

The @code{help} strings can include various format specifiers to avoid repetition
of things like the program name or the argument @ref{1b4c,,default}.  The available
specifiers include the program name, @code{%(prog)s} and most keyword arguments to
@ref{3ed,,add_argument()}, e.g. @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

As the help string supports %-formatting, if you want a literal @code{%} to appear
in the help string, you must escape it as @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 metavar,dest,help,The add_argument method
@anchor{library/argparse id13}@anchor{35fa}@anchor{library/argparse metavar}@anchor{35ec}
@subsubsection metavar


When @ref{1dc,,ArgumentParser} generates help messages, it needs some way to refer
to each expected argument.  By default, @code{ArgumentParser} objects use the @ref{35e4,,dest}
value as the «name» of each object.  By default, for positional argument
actions, the @ref{35e4,,dest} value is used directly, and for optional argument actions,
the @ref{35e4,,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

An alternative name can be specified with @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

Note that @code{metavar} only changes the `displayed' name - the name of the
attribute on the @ref{35cc,,parse_args()} object is still determined
by the @ref{35e4,,dest} value.

Different values of @code{nargs} may cause the metavar to be used multiple times.
Providing a tuple to @code{metavar} specifies a different display for each of the
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 dest,deprecated,metavar,The add_argument method
@anchor{library/argparse dest}@anchor{35e4}@anchor{library/argparse id14}@anchor{35fb}
@subsubsection dest


Most @ref{1dc,,ArgumentParser} actions add some value as an attribute of the
object returned by @ref{35cc,,parse_args()}.  The name of this
attribute is determined by the @code{dest} keyword argument of
@ref{3ed,,add_argument()}.  For positional argument actions,
@code{dest} is normally supplied as the first argument to
@code{add_argument()}:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')
@end example

For optional argument actions, the value of @code{dest} is normally inferred from
the option strings.  @ref{1dc,,ArgumentParser} generates the value of @code{dest} by
taking the first double-dash long option string and stripping away the initial
@code{-} characters.
If no double-dash long option strings were supplied, @code{dest} will be derived
from the first single-dash long option string by stripping the initial @code{-}
character.
If no long option strings were supplied, @code{dest} will be derived from
the first short option string by stripping the initial @code{-} character.  Any
internal @code{-} characters will be converted to @code{_} characters to make sure
the string is a valid attribute name.  The examples below illustrate this
behavior:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
>>> parser.add_argument('-q', '-quz')
>>> parser.add_argument('-x', '-y')
>>> parser.parse_args('-f 1 -q 2 -x 3'.split())
Namespace(foo_bar='1', quz='2', x='3')
>>> parser.parse_args('--foo 1 -quz 2 -y 3'.split())
Namespace(foo_bar='1', quz='2', x='2')
@end example

@code{dest} allows a custom attribute name to be provided:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')
@end example


Άλλαξε στην έκδοση 3.15: Single-dash long option now takes precedence over short options.


@node deprecated,Action classes,dest,The add_argument method
@anchor{library/argparse deprecated}@anchor{35ed}@anchor{library/argparse id15}@anchor{35fc}
@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{3ed,,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{d05,,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


Added in version 3.13.


@node Action classes,,deprecated,The add_argument method
@anchor{library/argparse action-classes}@anchor{35fd}
@subsubsection Action classes


@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{3ed,,add_argument()}.

@geindex Action (κλάση σε argparse)
@anchor{library/argparse argparse Action}@anchor{1d88}
@deffn {Κλάση} 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{1dc,,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{3ed,,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__() (μέθοδος της argparse.Action)
@anchor{library/argparse argparse Action __call__}@anchor{35fe}
@deffn {Μέθοδος} __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{1dc,,ArgumentParser} object which contains this action.

@item 
`namespace' - The @ref{35cd,,Namespace} object that will be returned by
@ref{35cc,,parse_args()}.  Most actions add an attribute to this
object using @ref{27b7,,setattr()}.

@item 
`values' - The associated command-line arguments, with any type conversions
applied.  Type conversions are specified with the @ref{35e3,,type} keyword argument to
@ref{3ed,,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() (μέθοδος της argparse.Action)
@anchor{library/argparse argparse Action format_usage}@anchor{35ff}
@deffn {Μέθοδος} 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

@geindex BooleanOptionalAction (κλάση σε argparse)
@anchor{library/argparse argparse BooleanOptionalAction}@anchor{1db}
@deffn {Κλάση} argparse.BooleanOptionalAction

A subclass of @ref{1d88,,Action} for handling boolean flags with positive
and negative options. Adding a single argument such as @code{--foo} automatically
creates both @code{--foo} and @code{--no-foo} options, storing @code{True} and @code{False}
respectively:

@example
>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)
@end example

Single-dash long options are also supported.
For example, negative option @code{-nofoo} is automatically added for
positive option @code{-foo}.
But no additional options are added for short options such as @code{-f}.


Added in version 3.9.



Άλλαξε στην έκδοση 3.15: Added support for single-dash options.

Added support for alternate @ref{35d4,,prefix_chars}.

@end deffn

@node The parse_args method,Other utilities,The add_argument method,argparse — Parser for command-line options arguments and subcommands
@anchor{library/argparse the-parse-args-method}@anchor{3600}
@subsubsection The parse_args() method


@geindex parse_args() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser parse_args}@anchor{35cc}
@deffn {Μέθοδος} ArgumentParser.parse_args (args=None, namespace=None)

Convert argument strings to objects and assign them as attributes of the
namespace.  Return the populated namespace.

Previous calls to @ref{3ed,,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{3601,,args} - List of strings to parse.  The default is taken from
@ref{1609,,sys.argv}.

@item 
@ref{3602,,namespace} - An object to take the attributes.  The default is a new empty
@ref{35cd,,Namespace} object.
@end itemize
@end deffn

@menu
* Option value syntax:: 
* Invalid arguments:: 
* Arguments containing -:: 
* Argument abbreviations (prefix matching): Argument abbreviations prefix matching. 
* Beyond sys.argv: Beyond sys argv. 
* The Namespace object:: 

@end menu

@node Option value syntax,Invalid arguments,,The parse_args method
@anchor{library/argparse option-value-syntax}@anchor{3603}
@subsubsection Option value syntax


The @ref{35cc,,parse_args()} method supports several ways of
specifying the value of an option (if it takes one).  In the simplest case, the
option and its value are passed as two separate arguments:

@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

For long options (options with names longer than a single character), the option
and value can also be passed as a single command-line argument, using @code{=} to
separate them:

@example
>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)
@end example

For short options (options only one character long), the option and its value
can be concatenated:

@example
>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')
@end example

Several short options can be joined together, using only a single @code{-} prefix,
as long as only the last option (or none of them) requires a value:

@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 Invalid arguments,Arguments containing -,Option value syntax,The parse_args method
@anchor{library/argparse invalid-arguments}@anchor{3604}
@subsubsection Invalid arguments


While parsing the command line, @ref{35cc,,parse_args()} checks for a
variety of errors, including ambiguous options, invalid types, invalid options,
wrong number of positional arguments, etc.  When it encounters such an error,
it exits and prints the error along with a usage message:

@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 containing -,Argument abbreviations prefix matching,Invalid arguments,The parse_args method
@anchor{library/argparse arguments-containing}@anchor{3605}
@subsubsection Arguments containing @code{-}


The @ref{35cc,,parse_args()} method attempts to give errors whenever
the user has clearly made a mistake, but some situations are inherently
ambiguous.  For example, the command-line argument @code{-1} could either be an
attempt to specify an option or an attempt to provide a positional argument.
The @code{parse_args()} method is cautious here: positional
arguments may only begin with @code{-} if they look like negative numbers and
there are no options in the parser that look like negative numbers:

@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

If you have positional arguments that must begin with @code{-} and don’t look
like negative numbers, you can insert the pseudo-argument @code{'--'} which tells
@ref{35cc,,parse_args()} that everything after that is a positional
argument:

@example
>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)
@end example

See also @ref{35f2,,the argparse howto on ambiguous arguments}
for more details.

@node Argument abbreviations prefix matching,Beyond sys argv,Arguments containing -,The parse_args method
@anchor{library/argparse argument-abbreviations-prefix-matching}@anchor{3606}@anchor{library/argparse prefix-matching}@anchor{1177}
@subsubsection Argument abbreviations (prefix matching)


The @ref{35cc,,parse_args()} method @ref{1178,,by default}
allows long options to be abbreviated to a prefix, if the abbreviation is
unambiguous (the prefix matches a unique 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

An error is produced for arguments that could produce more than one options.
This feature can be disabled by setting @ref{1178,,allow_abbrev} to @code{False}.

@node Beyond sys argv,The Namespace object,Argument abbreviations prefix matching,The parse_args method
@anchor{library/argparse args}@anchor{3601}@anchor{library/argparse beyond-sys-argv}@anchor{3607}
@subsubsection Beyond @code{sys.argv}


Sometimes it may be useful to have an @ref{1dc,,ArgumentParser} parse arguments other than those
of @ref{1609,,sys.argv}.  This can be accomplished by passing a list of strings to
@ref{35cc,,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 The Namespace object,,Beyond sys argv,The parse_args method
@anchor{library/argparse namespace}@anchor{3602}@anchor{library/argparse the-namespace-object}@anchor{3608}
@subsubsection The Namespace object


@geindex Namespace (κλάση σε argparse)
@anchor{library/argparse argparse Namespace}@anchor{35cd}
@deffn {Κλάση} argparse.Namespace

Simple class used by default by @ref{35cc,,parse_args()} to create
an object holding attributes and return it.

This class is deliberately simple, just an @ref{e4d,,object} subclass with a
readable string representation. If you prefer to have dict-like view of the
attributes, you can use the standard Python idiom, @ref{2011,,vars()}:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
@{'foo': 'BAR'@}
@end example

It may also be useful to have an @ref{1dc,,ArgumentParser} assign attributes to an
already existing object, rather than a new @code{Namespace} object.  This can
be achieved by specifying the @code{namespace=} keyword argument:

@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 Other utilities,Exceptions<10>,The parse_args method,argparse — Parser for command-line options arguments and subcommands
@anchor{library/argparse other-utilities}@anchor{3609}
@subsubsection Other utilities


@menu
* Subcommands:: 
* FileType objects:: 
* Argument groups:: 
* Mutual exclusion:: 
* Parser defaults:: 
* Printing help:: 
* Partial parsing:: 
* Customizing file parsing:: 
* Exiting methods:: 
* Intermixed parsing:: 
* Registering custom types or actions:: 

@end menu

@node Subcommands,FileType objects,,Other utilities
@anchor{library/argparse subcommands}@anchor{360a}
@subsubsection Subcommands


@geindex add_subparsers() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser add_subparsers}@anchor{fd6}
@deffn {Μέθοδος} 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{1dc,,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, @ref{35dd,,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 of parameters:


@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 subcommand 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{1dc,,ArgumentParser})

@item 
@ref{1b46,,action} - the basic type of action to be taken when this argument is
encountered at the command line

@item 
@ref{35e4,,dest} - name of the attribute under which subcommand name will be
stored; by default @code{None} and no value is stored

@item 
@ref{35ea,,required} - Whether or not a subcommand must be provided, by default
@code{False} (added in 3.7)

@item 
@ref{35eb,,help} - help for sub-parser group in help output, by default @code{None}

@item 
@ref{35ec,,metavar} - string presenting available subcommands in help; by default it
is @code{None} and presents subcommands in form @{cmd1, cmd2, ..@}
@end itemize

Some example usage:

@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

Note that the object returned by @ref{35cc,,parse_args()} will only contain
attributes for the main parser and the subparser that was selected by the
command line (and not any other subparsers).  So in the example above, when
the @code{a} command is specified, only the @code{foo} and @code{bar} attributes are
present, and when the @code{b} command is specified, only the @code{foo} and
@code{baz} attributes are present.

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 @ref{35dd,,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

The @code{add_subparsers()} method also supports @code{title} and @code{description}
keyword arguments.  When either is present, the subparser’s commands will
appear in their own group in the help output.  For example:

@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

One particularly effective way of handling subcommands is to combine the use
of the @code{add_subparsers()} method with calls to @ref{35e6,,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

This way, you can let @ref{35cc,,parse_args()} do the job of calling the
appropriate function after argument parsing is complete.  Associating
functions with actions like this is typically the easiest way to handle the
different actions for each of your subparsers.  However, if it is necessary
to check the name of the subparser that was invoked, the @code{dest} keyword
argument to the @code{add_subparsers()} call will work:

@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


Άλλαξε στην έκδοση 3.7: New `required' keyword-only parameter.



Άλλαξε στην έκδοση 3.14: Subparser’s `prog' is no longer affected by a custom usage message in
the main parser.

@end deffn

@geindex add_parser() (μέθοδος της argparse._SubParsersAction)
@anchor{library/argparse argparse _SubParsersAction add_parser}@anchor{35dd}
@deffn {Μέθοδος} _SubParsersAction.add_parser (name, *, help=None, aliases=None, deprecated=False, **kwargs)

Create and return a new @ref{1dc,,ArgumentParser} object for the
subcommand `name'.

The `name' argument is the name of the sub-command.

The `help' argument provides a short description for this sub-command.

The `aliases' argument allows providing alternative names for this
sub-command. For example:

@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

The `deprecated' argument, if @code{True}, marks the sub-command as
deprecated and will issue a warning when used. For example:

@example
>>> parser = argparse.ArgumentParser(prog='chicken.py')
>>> subparsers = parser.add_subparsers()
>>> fly = subparsers.add_parser('fly', deprecated=True)
>>> args = parser.parse_args(['fly'])
chicken.py: warning: command 'fly' is deprecated
Namespace()
@end example

All other keyword arguments are passed directly to the
@code{ArgumentParser} constructor.


Added in version 3.13: Added the `deprecated' parameter.

@end deffn

@node FileType objects,Argument groups,Subcommands,Other utilities
@anchor{library/argparse filetype-objects}@anchor{360b}
@subsubsection FileType objects


@geindex FileType (κλάση σε argparse)
@anchor{library/argparse argparse FileType}@anchor{31e}
@deffn {Κλάση} argparse.FileType (mode='r', bufsize=-1, encoding=None, errors=None)

The @code{FileType} factory creates objects that can be passed to the type
argument of @ref{3ed,,ArgumentParser.add_argument()}.  Arguments that have
@code{FileType} objects as their type will open command-line arguments as
files with the requested modes, buffer sizes, encodings and error handling
(see the @ref{32b,,open()} function for more details):

@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

FileType objects understand the pseudo-argument @code{'-'} and automatically
convert this into @ref{94a,,sys.stdin} for readable @code{FileType} objects and
@ref{e9c,,sys.stdout} for writable @code{FileType} objects:

@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

@cartouche
@quotation Σημείωση 
If one argument uses `FileType' and then a subsequent argument fails,
an error is reported but the file is not automatically closed.
This can also clobber the output files.
In this case, it would be better to wait until after the parser has
run and then use the @ref{20a,,with}-statement to manage the files.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.4: Added the `encoding' and `errors' parameters.



Αποσύρθηκε στην έκδοση 3.14.

@end deffn

@node Argument groups,Mutual exclusion,FileType objects,Other utilities
@anchor{library/argparse argument-groups}@anchor{360c}
@subsubsection Argument groups


@geindex add_argument_group() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser add_argument_group}@anchor{31d}
@deffn {Μέθοδος} ArgumentParser.add_argument_group (title=None, description=None, *[, argument_default][, conflict_handler])

By default, @ref{1dc,,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 @code{add_argument_group()} method returns an argument group object which
has an @ref{3ed,,add_argument()} method just like a regular
@ref{1dc,,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{35d6,,argument_default} and @ref{35d7,,conflict_handler}
allow for finer-grained control of the behavior of the argument group. These
parameters have the same meaning as in the @ref{1dc,,ArgumentParser} constructor,
but apply specifically to the argument group rather than the entire parser.

Note that any arguments not in your user-defined groups will end up back
in the usual «positional arguments» and «optional arguments» sections.

Within each argument group, arguments are displayed in help output in the
order in which they are added.


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.14: Calling @code{add_argument_group()} on an argument group now raises an
exception. This nesting was never supported, often failed to work
correctly, and was unintentionally exposed through inheritance.



Αποσύρθηκε στην έκδοση 3.14: Passing @ref{35d4,,prefix_chars} to @code{add_argument_group()}
is now deprecated.

@end deffn

@node Mutual exclusion,Parser defaults,Argument groups,Other utilities
@anchor{library/argparse mutual-exclusion}@anchor{360d}
@subsubsection Mutual exclusion


@geindex add_mutually_exclusive_group() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser add_mutually_exclusive_group}@anchor{567}
@deffn {Μέθοδος} 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

The @code{add_mutually_exclusive_group()} method also accepts a `required'
argument, to indicate that at least one of the mutually exclusive arguments
is required:

@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{31d,,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


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.14: Calling @ref{31d,,add_argument_group()} or @code{add_mutually_exclusive_group()}
on a mutually exclusive group now raises an exception. This nesting was
never supported, often failed to work correctly, and was unintentionally
exposed through inheritance.

@end deffn

@node Parser defaults,Printing help,Mutual exclusion,Other utilities
@anchor{library/argparse parser-defaults}@anchor{360e}
@subsubsection Parser defaults


@geindex set_defaults() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser set_defaults}@anchor{35e6}
@deffn {Μέθοδος} ArgumentParser.set_defaults (**kwargs)

Most of the time, the attributes of the object returned by @ref{35cc,,parse_args()}
will be fully determined by inspecting the command-line arguments and the argument
actions.  @code{set_defaults()} allows some additional
attributes that are determined without any inspection of the command line to
be added:

@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

Note that defaults can be set at both the parser level using @code{set_defaults()}
and at the argument level using @ref{3ed,,add_argument()}. If both are called for the
same argument, the last default set for an argument is used:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar')
>>> parser.set_defaults(foo='spam')
>>> parser.parse_args([])
Namespace(foo='spam')
@end example

Parser-level defaults can be particularly useful when working with multiple
parsers.  See the @ref{fd6,,add_subparsers()} method for an
example of this type.
@end deffn

@geindex get_default() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser get_default}@anchor{360f}
@deffn {Μέθοδος} ArgumentParser.get_default (dest)

Get the default value for a namespace attribute, as set by either
@ref{3ed,,add_argument()} or by
@ref{35e6,,set_defaults()}:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'
@end example
@end deffn

@node Printing help,Partial parsing,Parser defaults,Other utilities
@anchor{library/argparse printing-help}@anchor{3610}
@subsubsection Printing help


In most typical applications, @ref{35cc,,parse_args()} will take
care of formatting and printing any usage or error messages.  However, several
formatting methods are available:

@geindex print_usage() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser print_usage}@anchor{3611}
@deffn {Μέθοδος} ArgumentParser.print_usage (file=None)

Print a brief description of how the @ref{1dc,,ArgumentParser} should be
invoked on the command line.  If `file' is @code{None}, @ref{e9c,,sys.stdout} is
assumed.
@end deffn

@geindex print_help() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser print_help}@anchor{3612}
@deffn {Μέθοδος} ArgumentParser.print_help (file=None)

Print a help message, including the program usage and information about the
arguments registered with the @ref{1dc,,ArgumentParser}.  If `file' is
@code{None}, @ref{e9c,,sys.stdout} is assumed.
@end deffn

There are also variants of these methods that simply return a string instead of
printing it:

@geindex format_usage() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser format_usage}@anchor{1fa0}
@deffn {Μέθοδος} ArgumentParser.format_usage ()

Return a string containing a brief description of how the
@ref{1dc,,ArgumentParser} should be invoked on the command line.
@end deffn

@geindex format_help() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser format_help}@anchor{3613}
@deffn {Μέθοδος} ArgumentParser.format_help ()

Return a string containing a help message, including the program usage and
information about the arguments registered with the @ref{1dc,,ArgumentParser}.
@end deffn

@node Partial parsing,Customizing file parsing,Printing help,Other utilities
@anchor{library/argparse partial-parsing}@anchor{3614}
@subsubsection Partial parsing


@geindex parse_known_args() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser parse_known_args}@anchor{3615}
@deffn {Μέθοδος} ArgumentParser.parse_known_args (args=None, namespace=None)

Sometimes a script only needs to handle a specific set of command-line
arguments, leaving any unrecognized arguments for another script or program.
In these cases, the @code{parse_known_args()} method can be
useful.

This method works similarly to @ref{35cc,,parse_args()}, but it does
not raise an error for extra, unrecognized arguments. Instead, it parses the
known arguments and returns a two item tuple that contains the populated
namespace and the list of any unrecognized arguments.

@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 Προειδοποίηση 
@ref{1177,,Prefix matching} rules apply to
@ref{3615,,parse_known_args()}. The parser may consume an option even if it’s just
a prefix of one of its known options, instead of leaving it in the remaining
arguments list.
@end quotation
@end cartouche

@node Customizing file parsing,Exiting methods,Partial parsing,Other utilities
@anchor{library/argparse customizing-file-parsing}@anchor{3616}
@subsubsection Customizing file parsing


@geindex convert_arg_line_to_args() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser convert_arg_line_to_args}@anchor{35e5}
@deffn {Μέθοδος} ArgumentParser.convert_arg_line_to_args (arg_line)

Arguments that are read from a file (see the `fromfile_prefix_chars'
keyword argument to the @ref{1dc,,ArgumentParser} constructor) are read one
argument per line. @code{convert_arg_line_to_args()} can be overridden for
fancier reading.

This method takes a single argument `arg_line' which is a string read from
the argument file.  It returns a list of arguments parsed from this string.
The method is called once per line read from the argument file, in order.

A useful override of this method is one that treats each space-separated word
as an argument.  The following example demonstrates how to do this:

@example
class MyArgumentParser(argparse.ArgumentParser):
    def convert_arg_line_to_args(self, arg_line):
        return arg_line.split()
@end example
@end deffn

@node Exiting methods,Intermixed parsing,Customizing file parsing,Other utilities
@anchor{library/argparse exiting-methods}@anchor{3617}
@subsubsection Exiting methods


@geindex exit() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser exit}@anchor{3618}
@deffn {Μέθοδος} 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{d05,,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() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser error}@anchor{3619}
@deffn {Μέθοδος} ArgumentParser.error (message)

This method prints a usage message, including the `message', to
@ref{d05,,sys.stderr} and terminates the program with a status code of 2.
@end deffn

@node Intermixed parsing,Registering custom types or actions,Exiting methods,Other utilities
@anchor{library/argparse intermixed-parsing}@anchor{361a}
@subsubsection Intermixed parsing


@geindex parse_intermixed_args() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser parse_intermixed_args}@anchor{ec5}
@deffn {Μέθοδος} ArgumentParser.parse_intermixed_args (args=None, namespace=None)
@end deffn

@geindex parse_known_intermixed_args() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser parse_known_intermixed_args}@anchor{361b}
@deffn {Μέθοδος} ArgumentParser.parse_known_intermixed_args (args=None, namespace=None)

A number of Unix commands allow the user to intermix optional arguments with
positional arguments.  The @ref{ec5,,parse_intermixed_args()}
and @code{parse_known_intermixed_args()} methods
support this parsing style.

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.

The following example shows the difference between
@ref{3615,,parse_known_args()} and
@ref{ec5,,parse_intermixed_args()}: the former returns @code{['2',
'3']} as unparsed arguments, while the latter collects all the positionals
into @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

@code{parse_known_intermixed_args()} returns a two item tuple
containing the populated namespace and the list of remaining argument strings.
@ref{ec5,,parse_intermixed_args()} raises an error if there are any
remaining unparsed argument strings.


Added in version 3.7.

@end deffn

@node Registering custom types or actions,,Intermixed parsing,Other utilities
@anchor{library/argparse registering-custom-types-or-actions}@anchor{361c}
@subsubsection Registering custom types or actions


@geindex register() (μέθοδος της argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser register}@anchor{35f0}
@deffn {Μέθοδος} 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<10>,,Other utilities,argparse — Parser for command-line options arguments and subcommands
@anchor{library/argparse exceptions}@anchor{361d}
@subsubsection Exceptions


@geindex ArgumentError
@anchor{library/argparse argparse ArgumentError}@anchor{361e}
@deffn {Εξαίρεση} 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{35f6}
@deffn {Εξαίρεση} argparse.ArgumentTypeError

Raised when something goes wrong converting a command line string to a type.
@end deffn

@subsubheading Guides and Tutorials


@menu
* Argparse Tutorial:: 
* Migrating optparse code to argparse:: 

@end menu

@node Argparse Tutorial,Migrating optparse code to argparse,,Exceptions<10>
@anchor{howto/argparse doc}@anchor{361f}@anchor{howto/argparse argparse-tutorial}@anchor{35cb}@anchor{howto/argparse id1}@anchor{3620}
@subsubsection Argparse Tutorial


@*author: 
Tshepang Mbambo


This tutorial is intended to be a gentle introduction to @ref{7,,argparse}, the
recommended command-line parsing module in the Python standard library.

@cartouche
@quotation Σημείωση 
The standard library includes two other libraries directly related
to command-line parameter processing: the lower level @ref{a4,,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{64,,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:: 
* The basics:: 
* Introducing Positional arguments:: 
* Introducing Optional arguments:: 
* Combining Positional and Optional arguments:: 
* Getting a little more advanced:: 
* How to translate the argparse output:: 
* Custom type converters:: 
* Conclusion:: 

@end menu

@node Concepts,The basics,,Argparse Tutorial
@anchor{howto/argparse concepts}@anchor{3621}
@subsubsection Concepts


Let’s show the sort of functionality that we are going to explore in this
introductory tutorial by making use of the @code{ls} command:

@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

A few concepts we can learn from the four commands:


@itemize *

@item 
The @code{ls} command is useful when run without any options at all. It defaults
to displaying the contents of the current directory.

@item 
If we want beyond what it provides by default, we tell it a bit more. In
this case, we want it to display a different directory, @code{pypy}.
What we did is specify what is known as a positional argument. It’s named so
because the program should know what to do with the value, solely based on
where it appears on the command line. This concept is more relevant
to a command like @code{cp}, whose most basic usage is @code{cp SRC DEST}.
The first position is `what you want copied,' and the second
position is `where you want it copied to'.

@item 
Now, say we want to change behaviour of the program. In our example,
we display more info for each file instead of just showing the file names.
The @code{-l} in that case is known as an optional argument.

@item 
That’s a snippet of the help text. It’s very useful in that you can
come across a program you have never used before, and can figure out
how it works simply by reading its help text.
@end itemize

@node The basics,Introducing Positional arguments,Concepts,Argparse Tutorial
@anchor{howto/argparse the-basics}@anchor{3622}
@subsubsection The basics


Let us start with a very simple example which does (almost) nothing:

@example
import argparse
parser = argparse.ArgumentParser()
parser.parse_args()
@end example

Following is a result of running the 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

Here is what is happening:


@itemize *

@item 
Running the script without any options results in nothing displayed to
stdout. Not so useful.

@item 
The second one starts to display the usefulness of the @ref{7,,argparse}
module. We have done almost nothing, but already we get a nice help message.

@item 
The @code{--help} option, which can also be shortened to @code{-h}, is the only
option we get for free (i.e. no need to specify it). Specifying anything
else results in an error. But even then, we do get a useful usage message,
also for free.
@end itemize

@node Introducing Positional arguments,Introducing Optional arguments,The basics,Argparse Tutorial
@anchor{howto/argparse introducing-positional-arguments}@anchor{3623}
@subsubsection Introducing Positional arguments


An example:

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo")
args = parser.parse_args()
print(args.echo)
@end example

And running the 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

Here is what’s happening:


@itemize *

@item 
We’ve added the @ref{3ed,,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 
Calling our program now requires us to specify an option.

@item 
The @ref{35cc,,parse_args()} method actually returns some data from the
options specified, in this case, @code{echo}.

@item 
The variable is some form of “magic” that @ref{7,,argparse} performs for free
(i.e. no need to specify which variable that value is stored in).
You will also notice that its name matches the string argument given
to the method, @code{echo}.
@end itemize

Note however that, although the help display looks nice and all, it currently
is not as helpful as it can be. For example we see that we got @code{echo} as a
positional argument, but we don’t know what it does, other than by guessing or
by reading the source code. So, let’s make it a bit more useful:

@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

And we get:

@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

Now, how about doing something even more useful:

@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

Following is a result of running the 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

That didn’t go so well. That’s because @ref{7,,argparse} treats the options we
give it as strings, unless we tell it otherwise. So, let’s tell
@code{argparse} to treat that input as an integer:

@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

Following is a result of running the 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

That went well. The program now even helpfully quits on bad illegal input
before proceeding.

@node Introducing Optional arguments,Combining Positional and Optional arguments,Introducing Positional arguments,Argparse Tutorial
@anchor{howto/argparse introducing-optional-arguments}@anchor{3624}
@subsubsection Introducing Optional arguments


So far we have been playing with positional arguments. Let us
have a look on how to add optional ones:

@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

And the output:

@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

Here is what is happening:


@itemize *

@item 
The program is written so as to display something when @code{--verbosity} is
specified and display nothing when not.

@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{322,,if} statement.

@item 
The help message is a bit different.

@item 
When using the @code{--verbosity} option, one must also specify some value,
any value.
@end itemize

The above example accepts arbitrary integer values for @code{--verbosity}, but for
our simple program, only two values are actually useful, @code{True} or @code{False}.
Let’s modify the code accordingly:

@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

And the output:

@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

Here is what is happening:


@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 
It complains when you specify a value, in true spirit of what flags
actually are.

@item 
Notice the different help text.
@end itemize

@menu
* Short options:: 

@end menu

@node Short options,,,Introducing Optional arguments
@anchor{howto/argparse short-options}@anchor{3625}
@subsubsection Short options


If you are familiar with command line usage,
you will notice that I haven’t yet touched on the topic of short
versions of the options. It’s quite 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

And here goes:

@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

Note that the new ability is also reflected in the help text.

@node Combining Positional and Optional arguments,Getting a little more advanced,Introducing Optional arguments,Argparse Tutorial
@anchor{howto/argparse combining-positional-and-optional-arguments}@anchor{3626}
@subsubsection Combining Positional and Optional arguments


Our program keeps growing in complexity:

@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

And now the output:

@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 
We’ve brought back a positional argument, hence the complaint.

@item 
Note that the order does not matter.
@end itemize

How about we give this program of ours back the ability to have
multiple verbosity values, and actually get to use them:

@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

And the output:

@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

These all look good except the last one, which exposes a bug in our program.
Let’s fix it by restricting the values the @code{--verbosity} option can accept:

@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

And the output:

@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

Note that the change also reflects both in the error message as well as the
help string.

Now, let’s use a different approach of playing with verbosity, which is pretty
common. It also matches the way the CPython executable handles its own
verbosity argument (check the output of @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

We have introduced another action, «count»,
to count the number of occurrences of specific options.

@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 
Yes, it’s now more of a flag (similar to @code{action="store_true"}) in the
previous version of our script. That should explain the complaint.

@item 
It also behaves similar to «store_true» action.

@item 
Now here’s a demonstration of what the «count» action gives. You’ve probably
seen this sort of usage before.

@item 
And if you don’t specify the @code{-v} flag, that flag is considered to have
@code{None} value.

@item 
As should be expected, specifying the long form of the flag, we should get
the same output.

@item 
Sadly, our help output isn’t very informative on the new ability our script
has acquired, but that can always be fixed by improving the documentation for
our script (e.g. via the @code{help} keyword argument).

@item 
That last output exposes a bug in our program.
@end itemize

Let’s fix:

@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

And this is what it gives:

@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 
First output went well, and fixes the bug we had before.
That is, we want any value >= 2 to be as verbose as possible.

@item 
Third output not so good.
@end itemize

Let’s fix that bug:

@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

We’ve just introduced yet another keyword, @code{default}.
We’ve set it to @code{0} in order to make it comparable to the other int values.
Remember that by default,
if an optional argument isn’t specified,
it gets the @code{None} value, and that cannot be compared to an int value
(hence the @ref{291,,TypeError} exception).

And:

@example
$ python prog.py 4
16
@end example

You can go quite far just with what we’ve learned so far,
and we have only scratched the surface.
The @ref{7,,argparse} module is very powerful,
and we’ll explore a bit more of it before we end this tutorial.

@node Getting a little more advanced,How to translate the argparse output,Combining Positional and Optional arguments,Argparse Tutorial
@anchor{howto/argparse getting-a-little-more-advanced}@anchor{3627}
@subsubsection Getting a little more advanced


What if we wanted to expand our tiny program to perform other powers,
not just squares:

@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

Output:

@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

Notice that so far we’ve been using verbosity level to `change' the text
that gets displayed. The following example instead uses verbosity level
to display `more' text instead:

@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

Output:

@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:: 
* Conflicting options:: 

@end menu

@node Specifying ambiguous arguments,Conflicting options,,Getting a little more advanced
@anchor{howto/argparse id2}@anchor{3628}@anchor{howto/argparse specifying-ambiguous-arguments}@anchor{35f2}
@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{35cc,,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 Conflicting options,,Specifying ambiguous arguments,Getting a little more advanced
@anchor{howto/argparse conflicting-options}@anchor{3629}
@subsubsection Conflicting options


So far, we have been working with two methods of an
@ref{1dc,,argparse.ArgumentParser} instance. Let’s introduce a third one,
@ref{567,,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

Our program is now simpler, and we’ve lost some functionality for the sake of
demonstration. Anyways, here’s the output:

@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

That should be easy to follow. I’ve added that last output so you can see the
sort of flexibility you get, i.e. mixing long form options with short form
ones.

Before we conclude, you probably want to tell your users the main purpose of
your program, just in case they don’t know:

@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

Note that slight difference in the usage text. Note the @code{[-v | -q]},
which tells us that we can either use @code{-v} or @code{-q},
but not both at the same time:

@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,Getting a little more advanced,Argparse Tutorial
@anchor{howto/argparse how-to-translate-the-argparse-output}@anchor{362a}
@subsubsection How to translate the argparse output


The output of the @ref{7,,argparse} module such as its help text and error
messages are all made translatable using the @ref{66,,gettext} module. This
allows applications to easily localize messages produced by
@code{argparse}. See also @ref{362b,,Internationalizing your programs and modules}.

For instance, in this @ref{7,,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{7,,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{7,,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{66,,gettext}, @ref{7,,argparse} will be able to display the
translated messages.

To translate your own strings in the @ref{7,,argparse} output, use @ref{66,,gettext}.

@node Custom type converters,Conclusion,How to translate the argparse output,Argparse Tutorial
@anchor{howto/argparse custom-type-converters}@anchor{362c}
@subsubsection Custom type converters


The @ref{7,,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{35cd,,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

Output:

@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,Argparse Tutorial
@anchor{howto/argparse conclusion}@anchor{362d}
@subsubsection Conclusion


The @ref{7,,argparse} module offers a lot more than shown here.
Its docs are quite detailed and thorough, and full of examples.
Having gone through this tutorial, you should easily digest them
without feeling overwhelmed.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)
@anchor{howto/argparse-optparse upgrading-optparse-code}@anchor{1557}
@node Migrating optparse code to argparse,,Argparse Tutorial,Exceptions<10>
@anchor{howto/argparse-optparse doc}@anchor{362e}@anchor{howto/argparse-optparse migrating-optparse-code}@anchor{362f}@anchor{howto/argparse-optparse migrating-optparse-code-to-argparse}@anchor{3630}@anchor{howto/argparse-optparse translation-repo}@anchor{3631}
@subsubsection Migrating @code{optparse} code to @code{argparse}


The @ref{7,,argparse} module offers several higher level features not natively
provided by the @ref{a4,,optparse} module, including:


@itemize *

@item 
Handling positional arguments.

@item 
Supporting subcommands.

@item 
Allowing alternative option prefixes like @code{+} and @code{/}.

@item 
Handling zero-or-more and one-or-more style arguments.

@item 
Producing more informative usage messages.

@item 
Providing a much simpler interface for custom @code{type} and @code{action}.
@end itemize

Originally, the @ref{7,,argparse} module attempted to maintain compatibility
with @ref{a4,,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{35ca,,Choosing an argument parsing library}, applications that are
currently using @ref{a4,,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{a4,,optparse} to @ref{7,,argparse},
the following suggestions should be helpful:


@itemize *

@item 
Replace all @ref{3632,,optparse.OptionParser.add_option()} calls with
@ref{3ed,,ArgumentParser.add_argument()} calls.

@item 
Replace @code{(options, args) = parser.parse_args()} with @code{args =
parser.parse_args()} and add additional @ref{3ed,,ArgumentParser.add_argument()}
calls for the positional arguments. Keep in mind that what was previously
called @code{options}, now in the @ref{7,,argparse} context is called @code{args}.

@item 
Replace @ref{3633,,optparse.OptionParser.disable_interspersed_args()}
by using @ref{ec5,,parse_intermixed_args()} instead of
@ref{35cc,,parse_args()}.

@item 
Replace callback actions and the @code{callback_*} keyword arguments with
@code{type} or @code{action} arguments.

@item 
Replace string names for @code{type} keyword arguments with the corresponding
type objects (e.g. int, float, complex, etc).

@item 
Replace @ref{3634,,optparse.Values} with @ref{35cd,,Namespace} and
@ref{3635,,optparse.OptionError} and @ref{3636,,optparse.OptionValueError} with
@ref{361e,,ArgumentError}.

@item 
Replace strings with implicit arguments such as @code{%default} or @code{%prog} with
the standard Python syntax to use dictionaries to format strings, that is,
@code{%(default)s} and @code{%(prog)s}.

@item 
Replace the OptionParser constructor @code{version} argument with a call to
@code{parser.add_argument('--version', action='version', version='<the version>')}.
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{3637}@anchor{library/optparse module-optparse}@anchor{a4}@anchor{library/optparse optparse-parser-for-command-line-options}@anchor{3638}@anchor{library/optparse translation-repo}@anchor{3639}
@subsection @code{optparse} — Parser for command line options


@geindex module; optparse

`Source code:' Lib/optparse.py@footnote{https://github.com/python/cpython/tree/main/Lib/optparse.py}


__________________________________________________________________


@menu
* Choosing an argument parsing library:: 
* Introduction: Introduction<5>. 
* Background:: 
* Tutorial: Tutorial<2>. 
* Reference Guide:: 
* Option Callbacks:: 
* Extending optparse:: 
* Exceptions: Exceptions<11>. 

@end menu

@node Choosing an argument parsing library,Introduction<5>,,optparse — Parser for command line options
@anchor{library/optparse choosing-an-argument-parser}@anchor{35ca}@anchor{library/optparse choosing-an-argument-parsing-library}@anchor{363a}
@subsubsection Choosing an argument parsing library


The standard library includes three argument parsing libraries:


@itemize *

@item 
@ref{64,,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 
@code{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{7,,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{7,,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{64,,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.

@code{optparse} should be considered as an alternative to @ref{7,,argparse} in the
following cases:


@itemize *

@item 
an application is already using @code{optparse} and doesn’t want to risk the
subtle behavioural changes that may arise when migrating to @ref{7,,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 @code{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 Δείτε επίσης


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<5>,Background,Choosing an argument parsing library,optparse — Parser for command line options
@anchor{library/optparse introduction}@anchor{363b}
@subsubsection Introduction


@code{optparse} is a more convenient, flexible, and powerful library for parsing
command-line options than the minimalist @ref{64,,getopt} module.
@code{optparse} uses a more declarative style of command-line parsing:
you create an instance of @ref{186f,,OptionParser},
populate it with options, and parse the command line.
@code{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 @code{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, @code{optparse} sets attributes of the
@code{options} object returned by @ref{1870,,parse_args()} based on user-supplied
command-line values.  When @code{parse_args()} returns from parsing this command
line, @code{options.filename} will be @code{"outfile"} and @code{options.verbose} will be
@code{False}.  @code{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 @code{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,Tutorial<2>,Introduction<5>,optparse — Parser for command line options
@anchor{library/optparse background}@anchor{363c}@anchor{library/optparse optparse-background}@anchor{363d}
@subsubsection Background


@code{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{363e}@anchor{library/optparse terminology}@anchor{363f}
@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 @code{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 @code{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
@code{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, @code{optparse} does not
support this feature.

@item positional argument

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.  @code{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{3640}@anchor{library/optparse what-are-options-for}@anchor{3641}
@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{3642}@anchor{library/optparse what-are-positional-arguments-for}@anchor{3643}
@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 Tutorial<2>,Reference Guide,Background,optparse — Parser for command line options
@anchor{library/optparse optparse-tutorial}@anchor{3644}@anchor{library/optparse tutorial}@anchor{3645}
@subsubsection Tutorial


While @code{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 @code{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 @code{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{3632,,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, @code{optparse}
encounters `option strings' and looks up options from them.

Once all of your options are defined, instruct @code{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{1870,,parse_args()}, but
that’s rarely necessary: by default it uses @code{sys.argv[1:]}.)

@ref{1870,,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{3646,,action}, @ref{3647,,type}, @ref{3648,,dest}
(destination), and @ref{3649,,help}. Of these, @code{action} is the
most fundamental.

@menu
* Understanding option actions:: 
* The store action:: 
* Handling boolean (flag) options: Handling boolean flag options. 
* Other actions:: 
* Default values:: 
* Generating help:: 
* Printing a version string:: 
* How optparse handles errors:: 
* Putting it all together:: 

@end menu

@node Understanding option actions,The store action,,Tutorial<2>
@anchor{library/optparse optparse-understanding-option-actions}@anchor{364a}@anchor{library/optparse understanding-option-actions}@anchor{364b}
@subsubsection Understanding option actions


Actions tell @code{optparse} what to do when it encounters an option on the
command line.  There is a fixed set of actions hard-coded into @code{optparse};
adding new actions is an advanced topic covered in section
@ref{364c,,Extending optparse}.  Most actions tell @code{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, @code{optparse} defaults to @code{store}.

@node The store action,Handling boolean flag options,Understanding option actions,Tutorial<2>
@anchor{library/optparse optparse-store-action}@anchor{364d}@anchor{library/optparse the-store-action}@anchor{364e}
@subsubsection The store action


The most common option action is @code{store}, which tells @code{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.

For example:

@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 @code{optparse} to parse it:

@example
args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)
@end example

When @code{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{1870,,parse_args()}, @code{options.filename} is @code{"foo.txt"}.

Some other option types supported by @code{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

will print @code{42}.

If you don’t specify a type, @code{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, @code{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, @code{optparse} looks at the first short option string: the
default destination for @code{-f} is @code{f}.

@code{optparse} also includes the built-in @code{complex} type.  Adding
types is covered in section @ref{364c,,Extending optparse}.

@node Handling boolean flag options,Other actions,The store action,Tutorial<2>
@anchor{library/optparse handling-boolean-flag-options}@anchor{364f}@anchor{library/optparse optparse-handling-boolean-options}@anchor{3650}
@subsubsection Handling boolean (flag) options


Flag options—set a variable to true or false when a particular option is
seen—are quite common.  @code{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 @code{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,Default values,Handling boolean flag options,Tutorial<2>
@anchor{library/optparse optparse-other-actions}@anchor{3651}@anchor{library/optparse other-actions}@anchor{3652}
@subsubsection Other actions


Some other actions supported by @code{optparse} are:


@table @asis

@item @code{"store_const"}

store a constant value, pre-set via @ref{3653,,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{3654,,Reference Guide},
and section @ref{3655,,Option Callbacks}.

@node Default values,Generating help,Other actions,Tutorial<2>
@anchor{library/optparse default-values}@anchor{3656}@anchor{library/optparse optparse-default-values}@anchor{3657}
@subsubsection Default values


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.  @code{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 @code{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{1870,,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,Default values,Tutorial<2>
@anchor{library/optparse generating-help}@anchor{3658}@anchor{library/optparse optparse-generating-help}@anchor{3659}
@subsubsection Generating help


@code{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{3649,,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 @code{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, @code{optparse} exits after
printing the help text.)

There’s a lot going on here to help @code{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

@code{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, @code{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—@code{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,
@code{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—@code{optparse} will replace it with @ref{1df,,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{365a}
@subsubsection Grouping Options


When dealing with many options, it is convenient to group these options for
better help output.  An @ref{186f,,OptionParser} can contain several option groups,
each of which can contain several options.

An option group is obtained using the class @ref{365b,,OptionGroup}:

@geindex OptionGroup (κλάση σε optparse)
@anchor{library/optparse optparse OptionGroup}@anchor{365b}
@deffn {Κλάση} optparse.OptionGroup (parser, title, description=None)

where


@itemize *

@item 
parser is the @ref{186f,,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{365b,,OptionGroup} inherits from @code{OptionContainer} (like
@ref{186f,,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{186f,,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{365b,,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() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser get_option_group}@anchor{365c}
@deffn {Μέθοδος} OptionParser.get_option_group (opt_str)

Return the @ref{365b,,OptionGroup} to which the short or long option
string `opt_str' (e.g. @code{'-o'} or @code{'--option'}) belongs. If
there’s no such @code{OptionGroup}, return @code{None}.
@end deffn

@node Printing a version string,How optparse handles errors,Generating help,Tutorial<2>
@anchor{library/optparse optparse-printing-version-string}@anchor{365d}@anchor{library/optparse printing-a-version-string}@anchor{365e}
@subsubsection Printing a version string


Similar to the brief usage string, @code{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, @code{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() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser print_version}@anchor{365f}
@deffn {Μέθοδος} OptionParser.print_version (file=None)

Print the version message for the current program (@code{self.version}) to
`file' (default stdout).  As with @ref{3660,,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() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser get_version}@anchor{3661}
@deffn {Μέθοδος} OptionParser.get_version ()

Same as @ref{365f,,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,Tutorial<2>
@anchor{library/optparse how-optparse-handles-errors}@anchor{3662}@anchor{library/optparse optparse-how-optparse-handles-errors}@anchor{3663}
@subsubsection How @code{optparse} handles errors


There are two broad classes of errors that @code{optparse} has to worry about:
programmer errors and user errors.  Programmer errors are usually erroneous
calls to @ref{3632,,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{3635,,optparse.OptionError} or
@ref{291,,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.  @code{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, @code{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

@code{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 @code{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,Tutorial<2>
@anchor{library/optparse optparse-putting-it-all-together}@anchor{3664}@anchor{library/optparse putting-it-all-together}@anchor{3665}
@subsubsection Putting it all together


Here’s what @code{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,Tutorial<2>,optparse — Parser for command line options
@anchor{library/optparse optparse-reference-guide}@anchor{3654}@anchor{library/optparse reference-guide}@anchor{3666}
@subsubsection Reference Guide


@menu
* Creating the parser:: 
* Populating the parser:: 
* Defining options:: 
* Option attributes:: 
* Standard option actions:: 
* Standard option types:: 
* Parsing arguments:: 
* Querying and manipulating your option parser:: 
* Conflicts between options:: 
* Cleanup:: 
* Other methods:: 

@end menu

@node Creating the parser,Populating the parser,,Reference Guide
@anchor{library/optparse creating-the-parser}@anchor{3667}@anchor{library/optparse optparse-creating-parser}@anchor{3668}
@subsubsection Creating the parser


The first step in using @code{optparse} is to create an OptionParser instance.

@geindex OptionParser (κλάση σε optparse)
@anchor{library/optparse optparse OptionParser}@anchor{186f}
@deffn {Κλάση} 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 @code{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{3632,,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{3632,,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}, @code{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{3669,,Conflicts between options}.

@item @code{description} (default: @code{None})

A paragraph of text giving a brief overview of your program.
@code{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.  @code{optparse} provides two concrete classes for this purpose:
IndentedHelpFormatter and TitledHelpFormatter.

@item @code{add_help_option} (default: @code{True})

If true, @code{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{366a}@anchor{library/optparse populating-the-parser}@anchor{366b}
@subsubsection Populating the parser


There are several ways to populate the parser with options.  The preferred way
is by using @ref{3632,,OptionParser.add_option()}, as shown in section
@ref{3644,,Tutorial}.  @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
@code{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{366c}@anchor{library/optparse optparse-defining-options}@anchor{366d}
@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{366e,,Option} instance is with the
@code{add_option()} method of @ref{186f,,OptionParser}.

@geindex add_option() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser add_option}@anchor{3632}
@deffn {Μέθοδος} OptionParser.add_option (option)

@deffnx {Μέθοδος} 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{3646,,action}, and it largely
determines which other attributes are relevant or required.  If you pass
irrelevant option attributes, or fail to pass required ones, @code{optparse}
raises an @ref{3635,,OptionError} exception explaining your mistake.

An option’s `action' determines what @code{optparse} does when it encounters
this option on the command-line.  The standard option actions hard-coded into
@code{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{3653,,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{3653,,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{3647,,type} and @ref{3648,,dest} option
attributes; see @ref{366f,,Standard option actions}.)
@end deffn

As you can see, most actions involve storing or updating a value somewhere.
@code{optparse} always creates a special object for this, conventionally called
@code{options}, which is an instance of @ref{3634,,optparse.Values}.

@geindex Values (κλάση σε optparse)
@anchor{library/optparse optparse Values}@anchor{3634}
@deffn {Κλάση} optparse.Values

An object holding parsed argument names and values as attributes.
Normally created by calling when calling @ref{1870,,OptionParser.parse_args()},
and can be overridden by a custom subclass passed to the `values' argument of
@code{OptionParser.parse_args()} (as described in @ref{3670,,Parsing arguments}).
@end deffn

Option
arguments (and various other values) are stored as attributes of this object,
according to the @ref{3648,,dest} (destination) option attribute.

For example, when you call

@example
parser.parse_args()
@end example

one of the first things @code{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 @code{optparse}, on seeing this option, will do the equivalent of

@example
options.filename = "foo"
@end example

The @ref{3647,,type} and @ref{3648,,dest} option attributes are almost
as important as @ref{3646,,action}, but @code{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{3671}@anchor{library/optparse optparse-option-attributes}@anchor{3672}
@subsubsection Option attributes


@geindex Option (κλάση σε optparse)
@anchor{library/optparse optparse Option}@anchor{366e}
@deffn {Κλάση} optparse.Option

A single command line argument,
with various attributes passed by keyword to the constructor.
Normally created with @ref{3632,,OptionParser.add_option()} rather than directly,
and can be overridden by a custom class via the `option_class' argument
to @ref{186f,,OptionParser}.
@end deffn

The following option attributes may be passed as keyword arguments to
@ref{3632,,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,
@code{optparse} raises @ref{3635,,OptionError}.

@geindex action (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option action}@anchor{3646}
@deffn {Ιδιότητα} Option.action

(default: @code{"store"})

Determines @code{optparse}’s behaviour when this option is seen on the
command line; the available options are documented @ref{366f,,here}.
@end deffn

@geindex type (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option type}@anchor{3647}
@deffn {Ιδιότητα} 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{3673,,here}.
@end deffn

@geindex dest (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option dest}@anchor{3648}
@deffn {Ιδιότητα} Option.dest

(default: derived from option strings)

If the option’s action implies writing or modifying a value somewhere, this
tells @code{optparse} where to write it: @code{dest} names an
attribute of the @code{options} object that @code{optparse} builds as it parses
the command line.
@end deffn

@geindex default (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option default}@anchor{3674}
@deffn {Ιδιότητα} Option.default

The value to use for this option’s destination if the option is not seen on
the command line.  See also @ref{3675,,OptionParser.set_defaults()}.
@end deffn

@geindex nargs (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option nargs}@anchor{3676}
@deffn {Ιδιότητα} Option.nargs

(default: 1)

How many arguments of type @ref{3647,,type} should be consumed when this
option is seen.  If > 1, @code{optparse} will store a tuple of values to
@ref{3648,,dest}.
@end deffn

@geindex const (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option const}@anchor{3653}
@deffn {Ιδιότητα} Option.const

For actions that store a constant value, the constant value to store.
@end deffn

@geindex choices (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option choices}@anchor{3677}
@deffn {Ιδιότητα} Option.choices

For options of type @code{"choice"}, the list of strings the user may choose
from.
@end deffn

@geindex callback (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option callback}@anchor{3678}
@deffn {Ιδιότητα} Option.callback

For options with action @code{"callback"}, the callable to call when this option
is seen.  See section @ref{3655,,Option Callbacks} for detail on the
arguments passed to the callable.
@end deffn

@geindex callback_args (ιδιότητα της optparse.Option)
@geindex callback_kwargs (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option callback_args}@anchor{3679}
@deffn {Ιδιότητα} Option.callback_args
@anchor{library/optparse optparse Option callback_kwargs}@anchor{367a}
@deffnx {Ιδιότητα} Option.callback_kwargs

Additional positional and keyword arguments to pass to @code{callback} after the
four standard callback arguments.
@end deffn

@geindex help (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option help}@anchor{3649}
@deffn {Ιδιότητα} Option.help

Help text to print for this option when listing all available options after
the user supplies a @code{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 (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option metavar}@anchor{367b}
@deffn {Ιδιότητα} Option.metavar

(default: derived from option strings)

Stand-in for the option argument(s) to use when printing help text.  See
section @ref{3644,,Tutorial} for an example.
@end deffn

@node Standard option actions,Standard option types,Option attributes,Reference Guide
@anchor{library/optparse optparse-standard-option-actions}@anchor{366f}@anchor{library/optparse standard-option-actions}@anchor{367c}
@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 @code{optparse}’s behaviour; a few have required attributes, which you
must specify for any option using that action.


@itemize *

@item 
@code{"store"} [relevant: @ref{3647,,type}, @ref{3648,,dest},
@ref{3676,,nargs}, @ref{3677,,choices}]

The option must be followed by an argument, which is converted to a value
according to @ref{3647,,type} and stored in @ref{3648,,dest}.  If
@ref{3676,,nargs} > 1, multiple arguments will be consumed from the
command line; all will be converted according to @code{type} and
stored to @code{dest} as a tuple.  See the
@ref{3673,,Standard option types} section.

If @ref{3677,,choices} is supplied (a list or tuple of strings), the type
defaults to @code{"choice"}.

If @ref{3647,,type} is not supplied, it defaults to @code{"string"}.

If @ref{3648,,dest} is not supplied, @code{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, @code{optparse} derives a
destination from the first short option string (e.g., @code{-f} implies @code{f}).

Example:

@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

@code{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{3653,,const}; relevant:
@ref{3648,,dest}]

The value @ref{3653,,const} is stored in @ref{3648,,dest}.

Example:

@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, @code{optparse} will set

@example
options.verbose = 2
@end example

@item 
@code{"store_true"} [relevant: @ref{3648,,dest}]

A special case of @code{"store_const"} that stores @code{True} to
@ref{3648,,dest}.

@item 
@code{"store_false"} [relevant: @ref{3648,,dest}]

Like @code{"store_true"}, but stores @code{False}.

Example:

@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{3647,,type}, @ref{3648,,dest},
@ref{3676,,nargs}, @ref{3677,,choices}]

The option must be followed by an argument, which is appended to the list in
@ref{3648,,dest}.  If no default value for @code{dest} is
supplied, an empty list is automatically created when @code{optparse} first
encounters this option on the command-line.  If @ref{3676,,nargs} > 1,
multiple arguments are consumed, and a tuple of length @code{nargs}
is appended to @code{dest}.

The defaults for @ref{3647,,type} and @ref{3648,,dest} are the same as
for the @code{"store"} action.

Example:

@example
parser.add_option("-t", "--tracks", action="append", type="int")
@end example

If @code{-t3} is seen on the command-line, @code{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{3653,,const}; relevant:
@ref{3648,,dest}]

Like @code{"store_const"}, but the value @ref{3653,,const} is appended to
@ref{3648,,dest}; as with @code{"append"}, @code{dest} defaults to
@code{None}, and an empty list is automatically created the first time the option
is encountered.

@item 
@code{"count"} [relevant: @ref{3648,,dest}]

Increment the integer stored at @ref{3648,,dest}.  If no default value is
supplied, @code{dest} is set to zero before being incremented the
first time.

Example:

@example
parser.add_option("-v", action="count", dest="verbosity")
@end example

The first time @code{-v} is seen on the command line, @code{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{3678,,callback}; relevant:
@ref{3647,,type}, @ref{3676,,nargs}, @ref{3679,,callback_args},
@ref{367a,,callback_kwargs}]

Call the function specified by @ref{3678,,callback}, which is called as

@example
func(option, opt_str, value, parser, *args, **kwargs)
@end example

See section @ref{3655,,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{3649,,help} string passed to every
option.

If no @ref{3649,,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}.

@code{optparse} automatically adds a @ref{3649,,help} option to all
OptionParsers, so you do not normally need to create one.

Example:

@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 @code{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, @code{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{3649,,help} options, you will rarely create @code{version} options,
since @code{optparse} automatically adds them when needed.
@end itemize

@node Standard option types,Parsing arguments,Standard option actions,Reference Guide
@anchor{library/optparse optparse-standard-option-types}@anchor{3673}@anchor{library/optparse standard-option-types}@anchor{367d}
@subsubsection Standard option types


@code{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{364c,,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{326,,int()} with the appropriate base (2, 8,
10, or 16).  If this fails, so will @code{optparse}, although with a more useful
error message.

@code{"float"} and @code{"complex"} option arguments are converted directly with
@ref{327,,float()} and @ref{328,,complex()}, with similar error-handling.

@code{"choice"} options are a subtype of @code{"string"} options.  The
@ref{3677,,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{3636,,OptionValueError} if an invalid string is given.

@node Parsing arguments,Querying and manipulating your option parser,Standard option types,Reference Guide
@anchor{library/optparse optparse-parsing-arguments}@anchor{3670}@anchor{library/optparse parsing-arguments}@anchor{367e}
@subsubsection Parsing arguments


The whole point of creating and populating an OptionParser is to call its
@ref{1870,,parse_args()} method.

@geindex parse_args() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser parse_args}@anchor{1870}
@deffn {Μέθοδος} 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{3634,,Values} object to store option arguments in (default: a
new instance of @code{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 @code{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{27b7,,setattr()} calls (roughly one
for every option argument stored to an option destination) and returned by
@ref{1870,,parse_args()}.

If @ref{1870,,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,Parsing arguments,Reference Guide
@anchor{library/optparse optparse-querying-manipulating-option-parser}@anchor{367f}@anchor{library/optparse querying-and-manipulating-your-option-parser}@anchor{3680}
@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() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser disable_interspersed_args}@anchor{3633}
@deffn {Μέθοδος} 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, @code{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 @code{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() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser enable_interspersed_args}@anchor{3681}
@deffn {Μέθοδος} 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() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser get_option}@anchor{3682}
@deffn {Μέθοδος} 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() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser has_option}@anchor{3683}
@deffn {Μέθοδος} 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() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser remove_option}@anchor{3684}
@deffn {Μέθοδος} OptionParser.remove_option (opt_str)

If the @ref{186f,,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 @code{OptionParser}, raises @ref{277,,ValueError}.
@end deffn

@node Conflicts between options,Cleanup,Querying and manipulating your option parser,Reference Guide
@anchor{library/optparse conflicts-between-options}@anchor{3685}@anchor{library/optparse optparse-conflicts-between-options}@anchor{3669}
@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, @code{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{3686,,OptionConflictError}

@item @code{"resolve"}

resolve option conflicts intelligently (see below)
@end table
@end quotation

As an example, let’s define an @ref{186f,,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, @code{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, @code{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 @code{optparse} removes it, leaving this help text:

@example
Options:
  ...
  -n, --noisy   be noisy
  --dry-run     new dry-run option
@end example

@node Cleanup,Other methods,Conflicts between options,Reference Guide
@anchor{library/optparse cleanup}@anchor{3687}@anchor{library/optparse optparse-cleanup}@anchor{3688}
@subsubsection Cleanup


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,,Cleanup,Reference Guide
@anchor{library/optparse optparse-other-methods}@anchor{3689}@anchor{library/optparse other-methods}@anchor{368a}
@subsubsection Other methods


OptionParser supports several other public methods:

@geindex set_usage() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser set_usage}@anchor{368b}
@deffn {Μέθοδος} 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() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser print_usage}@anchor{3660}
@deffn {Μέθοδος} 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() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser get_usage}@anchor{368c}
@deffn {Μέθοδος} OptionParser.get_usage ()

Same as @ref{3660,,print_usage()} but returns the usage string instead of
printing it.
@end deffn

@geindex set_defaults() (μέθοδος της optparse.OptionParser)
@anchor{library/optparse optparse OptionParser set_defaults}@anchor{3675}
@deffn {Μέθοδος} OptionParser.set_defaults (dest=value, ...)

Set default values for several option destinations at once.  Using
@code{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 @code{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{368d}@anchor{library/optparse optparse-option-callbacks}@anchor{3655}
@subsubsection Option Callbacks


When @code{optparse}’s built-in actions and types aren’t quite enough for your
needs, you have two choices: extend @code{optparse} or define a callback option.
Extending @code{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{368e}@anchor{library/optparse optparse-defining-callback-option}@anchor{368f}
@subsubsection Defining a callback option


As always, the easiest way to define a callback option is by using the
@ref{3632,,OptionParser.add_option()} method.  Apart from @ref{3646,,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, @code{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.

@code{optparse} always passes four particular arguments to your callback, and it
will only pass additional arguments if you specify them via
@ref{3679,,callback_args} and @ref{367a,,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{3647,,type}

has its usual meaning: as with the @code{"store"} or @code{"append"} actions, it
instructs @code{optparse} to consume one argument and convert it to
@ref{3647,,type}.  Rather than storing the converted value(s) anywhere,
though, @code{optparse} passes it to your callback function.

@item @ref{3676,,nargs}

also has its usual meaning: if it is supplied and > 1, @code{optparse} will
consume @ref{3676,,nargs} arguments, each of which must be convertible to
@ref{3647,,type}.  It then passes a tuple of converted values to your
callback.

@item @ref{3679,,callback_args}

a tuple of extra positional arguments to pass to the callback

@item @ref{367a,,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{3690}@anchor{library/optparse optparse-how-callbacks-called}@anchor{3691}
@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.  @code{optparse} will
only expect an argument if @ref{3647,,type} is set; the type of @code{value} will be
the type implied by the option’s type.  If @code{type} for this option is
@code{None} (no argument expected), then @code{value} will be @code{None}.  If @ref{3676,,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{1870,,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 @code{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{3679,,callback_args} option attribute.

@item @code{kwargs}

is a dictionary of arbitrary keyword arguments supplied via
@ref{367a,,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{3692}@anchor{library/optparse raising-errors-in-a-callback}@anchor{3693}
@subsubsection Raising errors in a callback


The callback function should raise @ref{3636,,OptionValueError} if there are any
problems with the option or its argument(s).  @code{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{3694}@anchor{library/optparse optparse-callback-example-1}@anchor{3695}
@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{3696}@anchor{library/optparse optparse-callback-example-2}@anchor{3697}
@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{3698}@anchor{library/optparse optparse-callback-example-3}@anchor{3699}
@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{369a}@anchor{library/optparse optparse-callback-example-4}@anchor{369b}
@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{369c}@anchor{library/optparse optparse-callback-example-5}@anchor{369d}
@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{3647,,type}, then the option takes one argument that must be
convertible to that type; if you further define @ref{3676,,nargs}, then the
option takes @code{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 @code{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{369e}@anchor{library/optparse optparse-callback-example-6}@anchor{369f}
@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 @code{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 @code{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 @code{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<11>,Option Callbacks,optparse — Parser for command line options
@anchor{library/optparse extending-optparse}@anchor{36a0}@anchor{library/optparse optparse-extending-optparse}@anchor{364c}
@subsubsection Extending @code{optparse}


Since the two major controlling factors in how @code{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{36a1}@anchor{library/optparse optparse-adding-new-types}@anchor{36a2}
@subsubsection Adding new types


To add new types, you need to define your own subclass of @code{optparse}’s
@ref{366e,,Option} class.  This class has a couple of attributes that define
@code{optparse}’s types: @ref{36a3,,TYPES} and @ref{36a4,,TYPE_CHECKER}.

@geindex TYPES (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option TYPES}@anchor{36a3}
@deffn {Ιδιότητα} Option.TYPES

A tuple of type names; in your subclass, simply define a new tuple
@ref{36a3,,TYPES} that builds on the standard one.
@end deffn

@geindex TYPE_CHECKER (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option TYPE_CHECKER}@anchor{36a4}
@deffn {Ιδιότητα} 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{366e,,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{1870,,OptionParser.parse_args()}, or be passed to a callback as the
@code{value} parameter.

Your type-checking function should raise @ref{3636,,OptionValueError} if it
encounters any problems.  @code{OptionValueError} takes a single string
argument, which is passed as-is to @ref{186f,,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 @code{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{36a4,,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{29,,copy()} of @ref{36a4,,Option.TYPE_CHECKER}, we would end
up modifying the @code{TYPE_CHECKER} attribute of @code{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 @code{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{36a5}@anchor{library/optparse optparse-adding-new-actions}@anchor{36a6}
@subsubsection Adding new actions


Adding new actions is a bit trickier, because you have to understand that
@code{optparse} has a couple of classifications for actions:


@table @asis

@item «store» actions

actions that result in @code{optparse} storing a value to an attribute of the
current OptionValues instance; these options require a @ref{3648,,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{3647,,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 (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option ACTIONS}@anchor{36a7}
@deffn {Ιδιότητα} Option.ACTIONS

All actions must be listed in ACTIONS.
@end deffn

@geindex STORE_ACTIONS (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option STORE_ACTIONS}@anchor{36a8}
@deffn {Ιδιότητα} Option.STORE_ACTIONS

«store» actions are additionally listed here.
@end deffn

@geindex TYPED_ACTIONS (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option TYPED_ACTIONS}@anchor{36a9}
@deffn {Ιδιότητα} Option.TYPED_ACTIONS

«typed» actions are additionally listed here.
@end deffn

@geindex ALWAYS_TYPED_ACTIONS (ιδιότητα της optparse.Option)
@anchor{library/optparse optparse Option ALWAYS_TYPED_ACTIONS}@anchor{36aa}
@deffn {Ιδιότητα} 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 @code{optparse}
assigns the default type, @code{"string"}, to options with no explicit type
whose action is listed in @ref{36aa,,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{36a8,,STORE_ACTIONS} and
@ref{36a9,,TYPED_ACTIONS}.

@item 
to ensure that @code{optparse} assigns the default type of @code{"string"} to
@code{"extend"} actions, we put the @code{"extend"} action in
@ref{36aa,,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 @code{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{f8f,,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<11>,,Extending optparse,optparse — Parser for command line options
@anchor{library/optparse exceptions}@anchor{36ab}
@subsubsection Exceptions


@geindex OptionError
@anchor{library/optparse optparse OptionError}@anchor{3635}
@deffn {Εξαίρεση} optparse.OptionError

Raised if an @ref{366e,,Option} instance is created with invalid or
inconsistent arguments.
@end deffn

@geindex OptionConflictError
@anchor{library/optparse optparse OptionConflictError}@anchor{3686}
@deffn {Εξαίρεση} optparse.OptionConflictError

Raised if conflicting options are added to an @ref{186f,,OptionParser}.
@end deffn

@geindex OptionValueError
@anchor{library/optparse optparse OptionValueError}@anchor{3636}
@deffn {Εξαίρεση} optparse.OptionValueError

Raised if an invalid option value is encountered on the command line.
@end deffn

@geindex BadOptionError
@anchor{library/optparse optparse BadOptionError}@anchor{36ac}
@deffn {Εξαίρεση} optparse.BadOptionError

Raised if an invalid option is passed on the command line.
@end deffn

@geindex AmbiguousOptionError
@anchor{library/optparse optparse AmbiguousOptionError}@anchor{36ad}
@deffn {Εξαίρεση} optparse.AmbiguousOptionError

Raised if an ambiguous option is passed on the command line.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{36ae}@anchor{library/getpass getpass-portable-password-input}@anchor{36af}@anchor{library/getpass module-getpass}@anchor{65}@anchor{library/getpass translation-repo}@anchor{36b0}
@subsection @code{getpass} — Portable password input


@geindex module; getpass

`Source code:' Lib/getpass.py@footnote{https://github.com/python/cpython/tree/main/Lib/getpass.py}


__________________________________________________________________


@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

The @code{getpass} module provides two functions:

@geindex getpass() (στη μονάδα getpass)
@anchor{library/getpass getpass getpass}@anchor{4ab}
@deffn {Συνάρτηση} getpass.getpass (prompt='Password: ', stream=None, *, echo_char=None)

Prompt the user for a password without echoing.  The user is prompted using
the string `prompt', which defaults to @code{'Password: '}.  On Unix, the
prompt is written to the file-like object `stream' using the replace error
handler if needed.  `stream' defaults to the controlling terminal
(@code{/dev/tty}) or if that is unavailable to @code{sys.stderr} (this
argument is ignored on Windows).

The `echo_char' argument controls how user input is displayed while typing.
If `echo_char' is @code{None} (default), input remains hidden. Otherwise,
`echo_char' must be a single printable ASCII character and each
typed character is replaced by it. For example, @code{echo_char='*'} will
display asterisks instead of the actual input.

If echo free input is unavailable getpass() falls back to printing
a warning message to `stream' and reading from @code{sys.stdin} and
issuing a @ref{36b1,,GetPassWarning}.

@cartouche
@quotation Σημείωση 
If you call getpass from within IDLE, the input may be done in the
terminal you launched IDLE from rather than the idle window itself.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
On Unix systems, when `echo_char' is set, the terminal will be
configured to operate in
@code{noncanonical mode@footnote{https://manpages.debian.org/termios(3)#Canonical_and_noncanonical_mode}}.
Common terminal control characters are supported:


@itemize *

@item 
@code{Ctrl}+@code{A} - Move cursor to beginning of line

@item 
@code{Ctrl}+@code{E} - Move cursor to end of line

@item 
@code{Ctrl}+@code{K} - Kill (delete) from cursor to end of line

@item 
@code{Ctrl}+@code{U} - Kill (delete) entire line

@item 
@code{Ctrl}+@code{W} - Erase previous word

@item 
@code{Ctrl}+@code{V} - Insert next character literally (quote)

@item 
@code{Backspace}/@code{DEL} - Delete character before cursor
@end itemize

These shortcuts work by reading the terminal’s configured control
character mappings from termios settings.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.14: Added the `echo_char' parameter for keyboard feedback.



Άλλαξε στην έκδοση 3.15: When using non-empty `echo_char' on Unix, keyboard shortcuts (including
cursor movement and line editing) are now properly handled using the
terminal’s control character configuration.

@end deffn

@geindex GetPassWarning
@anchor{library/getpass getpass GetPassWarning}@anchor{36b1}
@deffn {Εξαίρεση} getpass.GetPassWarning

A @ref{290f,,UserWarning} subclass issued when password input may be echoed.
@end deffn

@geindex getuser() (στη μονάδα getpass)
@anchor{library/getpass getpass getuser}@anchor{848}
@deffn {Συνάρτηση} getpass.getuser ()

Return the «login name» of the user.

This function checks the environment variables 
@geindex LOGNAME
@geindex μεταβλητή περιβάλλοντος; LOGNAME
@code{LOGNAME},
@geindex USER
@geindex μεταβλητή περιβάλλοντος; USER
@code{USER}, @code{LNAME} and 
@geindex USERNAME
@geindex μεταβλητή περιβάλλοντος; 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{ba,,pwd} module, otherwise, an @ref{53c,,OSError}
is raised.

In general, this function should be preferred over @ref{19f4,,os.getlogin()}.


Άλλαξε στην έκδοση 3.13: Previously, various exceptions beyond just @ref{53c,,OSError} were raised.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{36b2}@anchor{library/fileinput fileinput-iterate-over-lines-from-multiple-input-streams}@anchor{36b3}@anchor{library/fileinput module-fileinput}@anchor{5e}@anchor{library/fileinput translation-repo}@anchor{36b4}
@subsection @code{fileinput} — Iterate over lines from multiple input streams


@geindex module; fileinput

`Source code:' Lib/fileinput.py@footnote{https://github.com/python/cpython/tree/main/Lib/fileinput.py}


__________________________________________________________________


This module implements a helper class and functions to quickly write a
loop over standard input or a list of files. If you just want to read or
write one file see @ref{32b,,open()}.

The typical use is:

@example
import fileinput
for line in fileinput.input(encoding="utf-8"):
    process(line)
@end example

This iterates over the lines of all files listed in @code{sys.argv[1:]}, defaulting
to @code{sys.stdin} if the list is empty.  If a filename is @code{'-'}, it is also
replaced by @code{sys.stdin} and the optional arguments `mode' and `openhook'
are ignored.  To specify an alternative list of filenames, pass it as the
first argument to @ref{bd9,,input()}.  A single file name is also allowed.

All files are opened in text mode by default, but you can override this by
specifying the `mode' parameter in the call to @ref{bd9,,input()} or
@ref{b1e,,FileInput}.  If an I/O error occurs during opening or reading a file,
@ref{53c,,OSError} is raised.


Άλλαξε στην έκδοση 3.3: @ref{13fb,,IOError} used to be raised; it is now an alias of @ref{53c,,OSError}.


If @code{sys.stdin} is used more than once, the second and further use will return
no lines, except perhaps for interactive use, or if it has been explicitly reset
(e.g. using @code{sys.stdin.seek(0)}).

Empty files are opened and immediately closed; the only time their presence in
the list of filenames is noticeable at all is when the last file opened is
empty.

Lines are returned with any newlines intact, which means that the last line in
a file may not have one.

You can control how files are opened by providing an opening hook via the
`openhook' parameter to @ref{bd9,,fileinput.input()} or @ref{b1e,,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{bda,,hook_compressed()} to support compressed files.

The following function is the primary interface of this module:

@geindex input() (στη μονάδα fileinput)
@anchor{library/fileinput fileinput input}@anchor{bd9}
@deffn {Συνάρτηση} fileinput.input (files=None, inplace=False, backup='@w{'}, *, mode='r', openhook=None, encoding=None, errors=None)

Create an instance of the @ref{b1e,,FileInput} class.  The instance will be used
as global state for the functions of this module, and is also returned to use
during iteration.  The parameters to this function will be passed along to the
constructor of the @code{FileInput} class.

The @ref{b1e,,FileInput} instance can be used as a context manager in the
@ref{20a,,with} statement.  In this example, `input' is closed after the
@code{with} statement is exited, even if an exception occurs:

@example
with fileinput.input(files=('spam.txt', 'eggs.txt'), encoding="utf-8") as f:
    for line in f:
        process(line)
@end example


Άλλαξε στην έκδοση 3.2: Can be used as a context manager.



Άλλαξε στην έκδοση 3.8: The keyword parameters `mode' and `openhook' are now keyword-only.



Άλλαξε στην έκδοση 3.10: The keyword-only parameter `encoding' and `errors' are added.

@end deffn

The following functions use the global state created by @ref{bd9,,fileinput.input()};
if there is no active state, @ref{30d,,RuntimeError} is raised.

@geindex filename() (στη μονάδα fileinput)
@anchor{library/fileinput fileinput filename}@anchor{36b5}
@deffn {Συνάρτηση} fileinput.filename ()

Return the name of the file currently being read.  Before the first line has
been read, returns @code{None}.
@end deffn

@geindex fileno() (στη μονάδα fileinput)
@anchor{library/fileinput fileinput fileno}@anchor{17d0}
@deffn {Συνάρτηση} fileinput.fileno ()

Return the integer «file descriptor» for the current file. When no file is
opened (before the first line and between files), returns @code{-1}.
@end deffn

@geindex lineno() (στη μονάδα fileinput)
@anchor{library/fileinput fileinput lineno}@anchor{36b6}
@deffn {Συνάρτηση} fileinput.lineno ()

Return the cumulative line number of the line that has just been read.  Before
the first line has been read, returns @code{0}.  After the last line of the last
file has been read, returns the line number of that line.
@end deffn

@geindex filelineno() (στη μονάδα fileinput)
@anchor{library/fileinput fileinput filelineno}@anchor{36b7}
@deffn {Συνάρτηση} fileinput.filelineno ()

Return the line number in the current file.  Before the first line has been
read, returns @code{0}.  After the last line of the last file has been read,
returns the line number of that line within the file.
@end deffn

@geindex isfirstline() (στη μονάδα fileinput)
@anchor{library/fileinput fileinput isfirstline}@anchor{36b8}
@deffn {Συνάρτηση} fileinput.isfirstline ()

Return @code{True} if the line just read is the first line of its file, otherwise
return @code{False}.
@end deffn

@geindex isstdin() (στη μονάδα fileinput)
@anchor{library/fileinput fileinput isstdin}@anchor{36b9}
@deffn {Συνάρτηση} fileinput.isstdin ()

Return @code{True} if the last line was read from @code{sys.stdin}, otherwise return
@code{False}.
@end deffn

@geindex nextfile() (στη μονάδα fileinput)
@anchor{library/fileinput fileinput nextfile}@anchor{36ba}
@deffn {Συνάρτηση} fileinput.nextfile ()

Close the current file so that the next iteration will read the first line from
the next file (if any); lines not read from the file will not count towards the
cumulative line count.  The filename is not changed until after the first line
of the next file has been read.  Before the first line has been read, this
function has no effect; it cannot be used to skip the first file.  After the
last line of the last file has been read, this function has no effect.
@end deffn

@geindex close() (στη μονάδα fileinput)
@anchor{library/fileinput fileinput close}@anchor{36bb}
@deffn {Συνάρτηση} fileinput.close ()

Close the sequence.
@end deffn

The class which implements the sequence behavior provided by the module is
available for subclassing as well:

@geindex FileInput (κλάση σε fileinput)
@anchor{library/fileinput fileinput FileInput}@anchor{b1e}
@deffn {Κλάση} fileinput.FileInput (files=None, inplace=False, backup='@w{'}, *, mode='r', openhook=None, encoding=None, errors=None)

Class @code{FileInput} is the implementation; its methods @ref{36b5,,filename()},
@ref{17d0,,fileno()}, @ref{36b6,,lineno()}, @ref{36b7,,filelineno()}, @ref{36b8,,isfirstline()},
@ref{36b9,,isstdin()}, @ref{36ba,,nextfile()} and @ref{36bb,,close()} correspond to the
functions of the same name in the module. In addition it is @ref{15ce,,iterable}
and has a @ref{2296,,readline()} method which returns the next
input line. The sequence must be accessed in strictly sequential order;
random access and @code{readline()} cannot be mixed.

With `mode' you can specify which file mode will be passed to @ref{32b,,open()}. It
must be one of @code{'r'} and @code{'rb'}.

The `openhook', when given, must be a function that takes two arguments,
`filename' and `mode', and returns an accordingly opened file-like object. You
cannot use `inplace' and `openhook' together.

You can specify `encoding' and `errors' that is passed to @ref{32b,,open()} or `openhook'.

A @code{FileInput} instance can be used as a context manager in the
@ref{20a,,with} statement.  In this example, `input' is closed after the
@code{with} statement is exited, even if an exception occurs:

@example
with FileInput(files=('spam.txt', 'eggs.txt')) as input:
    process(input)
@end example


Άλλαξε στην έκδοση 3.2: Can be used as a context manager.



Άλλαξε στην έκδοση 3.8: The keyword parameter `mode' and `openhook' are now keyword-only.



Άλλαξε στην έκδοση 3.10: The keyword-only parameter `encoding' and `errors' are added.



Άλλαξε στην έκδοση 3.11: The @code{'rU'} and @code{'U'} modes and the @code{__getitem__()} method have
been removed.

@end deffn

`Optional in-place filtering:' if the keyword argument @code{inplace=True} is
passed to @ref{bd9,,fileinput.input()} or to the @ref{b1e,,FileInput} constructor, the
file is moved to a backup file and standard output is directed to the input file
(if a file of the same name as the backup file already exists, it will be
replaced silently).  This makes it possible to write a filter that rewrites its
input file in place.  If the `backup' parameter is given (typically as
@code{backup='.<some extension>'}), it specifies the extension for the backup file,
and the backup file remains around; by default, the extension is @code{'.bak'} and
it is deleted when the output file is closed.  In-place filtering is disabled
when standard input is read.

The two following opening hooks are provided by this module:

@geindex hook_compressed() (στη μονάδα fileinput)
@anchor{library/fileinput fileinput hook_compressed}@anchor{bda}
@deffn {Συνάρτηση} fileinput.hook_compressed (filename, mode, *, encoding=None, errors=None)

Transparently opens files compressed with gzip and bzip2 (recognized by the
extensions @code{'.gz'} and @code{'.bz2'}) using the @ref{6a,,gzip} and @ref{14,,bz2}
modules.  If the filename extension is not @code{'.gz'} or @code{'.bz2'}, the file is
opened normally (ie, using @ref{32b,,open()} without any decompression).

The `encoding' and `errors' values are passed to @ref{b9c,,io.TextIOWrapper}
for compressed files and open for normal files.

Usage example:  @code{fi = fileinput.FileInput(openhook=fileinput.hook_compressed, encoding="utf-8")}


Άλλαξε στην έκδοση 3.10: The keyword-only parameter `encoding' and `errors' are added.

@end deffn

@geindex hook_encoded() (στη μονάδα fileinput)
@anchor{library/fileinput fileinput hook_encoded}@anchor{1061}
@deffn {Συνάρτηση} fileinput.hook_encoded (encoding, errors=None)

Returns a hook which opens each file with @ref{32b,,open()}, using the given
`encoding' and `errors' to read the file.

Usage example: @code{fi =
fileinput.FileInput(openhook=fileinput.hook_encoded("utf-8",
"surrogateescape"))}


Άλλαξε στην έκδοση 3.6: Added the optional `errors' parameter.



Αποσύρθηκε στην έκδοση 3.10: This function is deprecated since @ref{bd9,,fileinput.input()} and @ref{b1e,,FileInput}
now have `encoding' and `errors' parameters.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{36bc}@anchor{library/curses curses-terminal-handling-for-character-cell-displays}@anchor{36bd}@anchor{library/curses module-curses}@anchor{2e}@anchor{library/curses translation-repo}@anchor{36be}
@subsection @code{curses} — Terminal handling for character-cell displays


@geindex module; curses

`Source code:' Lib/curses@footnote{https://github.com/python/cpython/tree/main/Lib/curses}


__________________________________________________________________


The @code{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{232d,,Διαθεσιμότητα}: not Android, not iOS, not WASI.

This module is not supported on @ref{244d,,mobile platforms}
or @ref{1d67,,WebAssembly platforms}.

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile

@ref{232d,,Διαθεσιμότητα}: Unix.

@cartouche
@quotation Σημείωση 
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 Δείτε επίσης



@table @asis

@item Module @ref{2f,,curses.ascii}

Utilities for working with ASCII characters, regardless of your locale settings.

@item Module @ref{30,,curses.panel}

A panel stack extension that adds depth to  curses windows.

@item Module @ref{31,,curses.textpad}

Editable text widget for curses supporting  @code{Emacs}-like bindings.

@item @ref{36bf,,Curses Programming with Python}

Tutorial material on using curses with Python, by Andrew Kuchling and Eric
Raymond.
@end table


@menu
* Functions: Functions<4>. 
* Window Objects:: 
* Constants: Constants<6>. 

@end menu

@node Functions<4>,Window Objects,,curses — Terminal handling for character-cell displays
@anchor{library/curses curses-functions}@anchor{36c0}@anchor{library/curses functions}@anchor{36c1}
@subsubsection Functions


The module @code{curses} defines the following exception:

@geindex error
@anchor{library/curses curses error}@anchor{1a16}
@deffn {Εξαίρεση} curses.error

Exception raised when a curses library function returns an error.
@end deffn

@cartouche
@quotation Σημείωση 
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{36c2,,A_NORMAL}.
@end quotation
@end cartouche

The module @code{curses} defines the following functions:

@geindex assume_default_colors() (στη μονάδα curses)
@anchor{library/curses curses assume_default_colors}@anchor{489}
@deffn {Συνάρτηση} curses.assume_default_colors (fg, bg, /)

Allow use of default values for colors on terminals supporting this feature.
Use this to support transparency in your application.


@itemize *

@item 
Assign terminal default foreground/background colors to color number @code{-1}.
So @code{init_pair(x, COLOR_RED, -1)} will initialize pair `x' as red
on default background and @code{init_pair(x, -1, COLOR_BLUE)} will
initialize pair `x' as default foreground on blue.

@item 
Change the definition of the color-pair @code{0} to @code{(fg, bg)}.
@end itemize


Added in version 3.14.

@end deffn

@geindex baudrate() (στη μονάδα curses)
@anchor{library/curses curses baudrate}@anchor{1a17}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses beep}@anchor{36c3}
@deffn {Συνάρτηση} curses.beep ()

Emit a short attention sound.
@end deffn

@geindex can_change_color() (στη μονάδα curses)
@anchor{library/curses curses can_change_color}@anchor{36c4}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses cbreak}@anchor{1a18}
@deffn {Συνάρτηση} 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{1a1d,,raw()} then @code{cbreak()} leaves the terminal in cbreak mode.
@end deffn

@geindex color_content() (στη μονάδα curses)
@anchor{library/curses curses color_content}@anchor{bcc}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses color_pair}@anchor{36c5}
@deffn {Συνάρτηση} 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{36c6,,A_STANDOUT}, @ref{36c7,,A_REVERSE},
and the other @code{A_*} attributes.  @ref{36c8,,pair_number()} is the counterpart
to this function.
@end deffn

@geindex curs_set() (στη μονάδα curses)
@anchor{library/curses curses curs_set}@anchor{36c9}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses def_prog_mode}@anchor{36ca}
@deffn {Συνάρτηση} 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{36cb,,reset_prog_mode()} will
restore this mode.
@end deffn

@geindex def_shell_mode() (στη μονάδα curses)
@anchor{library/curses curses def_shell_mode}@anchor{36cc}
@deffn {Συνάρτηση} 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{36cd,,reset_shell_mode()} will restore this mode.
@end deffn

@geindex delay_output() (στη μονάδα curses)
@anchor{library/curses curses delay_output}@anchor{36ce}
@deffn {Συνάρτηση} curses.delay_output (ms)

Insert an `ms' millisecond pause in output.
@end deffn

@geindex doupdate() (στη μονάδα curses)
@anchor{library/curses curses doupdate}@anchor{36cf}
@deffn {Συνάρτηση} 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 @code{doupdate()} ground updates the
physical screen to match the virtual screen.

The virtual screen may be updated by a @ref{1a22,,noutrefresh()} call after write
operations such as @ref{1a27,,addstr()} have been performed on a window.  The normal
@ref{1a21,,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() (στη μονάδα curses)
@anchor{library/curses curses echo}@anchor{1a19}
@deffn {Συνάρτηση} curses.echo ()

Enter echo mode.  In echo mode, each character input is echoed to the screen as
it is entered.
@end deffn

@geindex endwin() (στη μονάδα curses)
@anchor{library/curses curses endwin}@anchor{36d0}
@deffn {Συνάρτηση} curses.endwin ()

De-initialize the library, and return terminal to normal status.
@end deffn

@geindex erasechar() (στη μονάδα curses)
@anchor{library/curses curses erasechar}@anchor{36d1}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses filter}@anchor{36d2}
@deffn {Συνάρτηση} curses.filter ()

The @code{filter()} routine, if used, must be called before @ref{1a1b,,initscr()} is
called.  The effect is that, during those calls, 
@geindex LINES
@geindex μεταβλητή περιβάλλοντος; 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() (στη μονάδα curses)
@anchor{library/curses curses flash}@anchor{36d3}
@deffn {Συνάρτηση} 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{36c3,,beep()}.
@end deffn

@geindex flushinp() (στη μονάδα curses)
@anchor{library/curses curses flushinp}@anchor{36d4}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses getmouse}@anchor{36d5}
@deffn {Συνάρτηση} curses.getmouse ()

After @ref{1a30,,getch()} returns @ref{36d6,,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{36d7,,BUTTONn_PRESSED}, @ref{36d8,,BUTTONn_RELEASED}, @ref{36d9,,BUTTONn_CLICKED},
@ref{36da,,BUTTONn_DOUBLE_CLICKED}, @ref{36db,,BUTTONn_TRIPLE_CLICKED},
@ref{36dc,,BUTTON_SHIFT}, @ref{36dd,,BUTTON_CTRL}, @ref{36de,,BUTTON_ALT}.


Άλλαξε στην έκδοση 3.10: The @code{BUTTON5_*} constants are now exposed if they are provided by the
underlying curses library.

@end deffn

@geindex getsyx() (στη μονάδα curses)
@anchor{library/curses curses getsyx}@anchor{36df}
@deffn {Συνάρτηση} curses.getsyx ()

Return the current coordinates of the virtual screen cursor as a tuple
@code{(y, x)}.  If @ref{36e0,,leaveok} is currently @code{True}, then return @code{(-1, -1)}.
@end deffn

@geindex getwin() (στη μονάδα curses)
@anchor{library/curses curses getwin}@anchor{36e1}
@deffn {Συνάρτηση} curses.getwin (file)

Read window related data stored in the file by an earlier @ref{36e2,,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() (στη μονάδα curses)
@anchor{library/curses curses has_colors}@anchor{36e3}
@deffn {Συνάρτηση} curses.has_colors ()

Return @code{True} if the terminal can display colors; otherwise, return @code{False}.
@end deffn

@geindex has_extended_color_support() (στη μονάδα curses)
@anchor{library/curses curses has_extended_color_support}@anchor{bd0}
@deffn {Συνάρτηση} 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.


Added in version 3.10.

@end deffn

@geindex has_ic() (στη μονάδα curses)
@anchor{library/curses curses has_ic}@anchor{36e4}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses has_il}@anchor{36e5}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses has_key}@anchor{36e6}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses halfdelay}@anchor{36e7}
@deffn {Συνάρτηση} 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{36e8,,nocbreak()} to leave half-delay mode.
@end deffn

@geindex init_color() (στη μονάδα curses)
@anchor{library/curses curses init_color}@anchor{bcd}
@deffn {Συνάρτηση} 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 @code{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{36c4,,can_change_color()} returns @code{True}.
@end deffn

@geindex init_pair() (στη μονάδα curses)
@anchor{library/curses curses init_pair}@anchor{bce}
@deffn {Συνάρτηση} 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 can only be changed by
@ref{48a,,use_default_colors()} and @ref{489,,assume_default_colors()}).
The value of `fg' and `bg' arguments must be between @code{0} and
@code{COLORS - 1}, or, after calling @code{use_default_colors()} or
@code{assume_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() (στη μονάδα curses)
@anchor{library/curses curses initscr}@anchor{1a1b}
@deffn {Συνάρτηση} curses.initscr ()

Initialize the library. Return a @ref{1a24,,window} object
which represents the whole screen.

@cartouche
@quotation Σημείωση 
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() (στη μονάδα curses)
@anchor{library/curses curses is_term_resized}@anchor{36e9}
@deffn {Συνάρτηση} curses.is_term_resized (nlines, ncols)

Return @code{True} if @ref{1b4b,,resize_term()} would modify the window structure,
@code{False} otherwise.
@end deffn

@geindex isendwin() (στη μονάδα curses)
@anchor{library/curses curses isendwin}@anchor{36ea}
@deffn {Συνάρτηση} curses.isendwin ()

Return @code{True} if @ref{36d0,,endwin()} has been called (that is, the  curses library has
been deinitialized).
@end deffn

@geindex keyname() (στη μονάδα curses)
@anchor{library/curses curses keyname}@anchor{36eb}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses killchar}@anchor{36ec}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses longname}@anchor{1a1a}
@deffn {Συνάρτηση} 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{1a1b,,initscr()}.
@end deffn

@geindex meta() (στη μονάδα curses)
@anchor{library/curses curses meta}@anchor{36ed}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses mouseinterval}@anchor{36ee}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses mousemask}@anchor{36ef}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses napms}@anchor{1b2a}
@deffn {Συνάρτηση} curses.napms (ms)

Sleep for `ms' milliseconds.
@end deffn

@geindex newpad() (στη μονάδα curses)
@anchor{library/curses curses newpad}@anchor{36f0}
@deffn {Συνάρτηση} 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{1a21,,refresh()} and @ref{1a22,,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() (στη μονάδα curses)
@anchor{library/curses curses newwin}@anchor{36f1}
@deffn {Συνάρτηση} curses.newwin (nlines, ncols)

@deffnx {Συνάρτηση} curses.newwin (nlines, ncols, begin_y, begin_x)

Return a new @ref{1a24,,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() (στη μονάδα curses)
@anchor{library/curses curses nl}@anchor{1a1c}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses nocbreak}@anchor{36e8}
@deffn {Συνάρτηση} curses.nocbreak ()

Leave cbreak mode.  Return to normal «cooked» mode with line buffering.
@end deffn

@geindex noecho() (στη μονάδα curses)
@anchor{library/curses curses noecho}@anchor{36f2}
@deffn {Συνάρτηση} curses.noecho ()

Leave echo mode.  Echoing of input characters is turned off.
@end deffn

@geindex nonl() (στη μονάδα curses)
@anchor{library/curses curses nonl}@anchor{36f3}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses noqiflush}@anchor{36f4}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses noraw}@anchor{36f5}
@deffn {Συνάρτηση} curses.noraw ()

Leave raw mode. Return to normal «cooked» mode with line buffering.
@end deffn

@geindex pair_content() (στη μονάδα curses)
@anchor{library/curses curses pair_content}@anchor{bcf}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses pair_number}@anchor{36c8}
@deffn {Συνάρτηση} curses.pair_number (attr)

Return the number of the color-pair set by the attribute value `attr'.
@ref{36c5,,color_pair()} is the counterpart to this function.
@end deffn

@geindex putp() (στη μονάδα curses)
@anchor{library/curses curses putp}@anchor{36f6}
@deffn {Συνάρτηση} 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 @code{putp()}
always goes to standard output.
@end deffn

@geindex qiflush() (στη μονάδα curses)
@anchor{library/curses curses qiflush}@anchor{36f7}
@deffn {Συνάρτηση} curses.qiflush ([flag])

If `flag' is @code{False}, the effect is the same as calling @ref{36f4,,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() (στη μονάδα curses)
@anchor{library/curses curses raw}@anchor{1a1d}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses reset_prog_mode}@anchor{36cb}
@deffn {Συνάρτηση} curses.reset_prog_mode ()

Restore the  terminal  to «program» mode, as previously saved  by
@ref{36ca,,def_prog_mode()}.
@end deffn

@geindex reset_shell_mode() (στη μονάδα curses)
@anchor{library/curses curses reset_shell_mode}@anchor{36cd}
@deffn {Συνάρτηση} curses.reset_shell_mode ()

Restore the  terminal  to «shell» mode, as previously saved  by
@ref{36cc,,def_shell_mode()}.
@end deffn

@geindex resetty() (στη μονάδα curses)
@anchor{library/curses curses resetty}@anchor{36f8}
@deffn {Συνάρτηση} curses.resetty ()

Restore the state of the terminal modes to what it was at the last call to
@ref{36f9,,savetty()}.
@end deffn

@geindex resize_term() (στη μονάδα curses)
@anchor{library/curses curses resize_term}@anchor{1b4b}
@deffn {Συνάρτηση} curses.resize_term (nlines, ncols)

Backend function used by @ref{1b4a,,resizeterm()}, performing most of the work;
when resizing the windows, @code{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() (στη μονάδα curses)
@anchor{library/curses curses resizeterm}@anchor{1b4a}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses savetty}@anchor{36f9}
@deffn {Συνάρτηση} curses.savetty ()

Save the current state of the terminal modes in a buffer, usable by
@ref{36f8,,resetty()}.
@end deffn

@geindex get_escdelay() (στη μονάδα curses)
@anchor{library/curses curses get_escdelay}@anchor{cc0}
@deffn {Συνάρτηση} curses.get_escdelay ()

Retrieves the value set by @ref{cc1,,set_escdelay()}.


Added in version 3.9.

@end deffn

@geindex set_escdelay() (στη μονάδα curses)
@anchor{library/curses curses set_escdelay}@anchor{cc1}
@deffn {Συνάρτηση} 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.


Added in version 3.9.

@end deffn

@geindex get_tabsize() (στη μονάδα curses)
@anchor{library/curses curses get_tabsize}@anchor{cc2}
@deffn {Συνάρτηση} curses.get_tabsize ()

Retrieves the value set by @ref{cc3,,set_tabsize()}.


Added in version 3.9.

@end deffn

@geindex set_tabsize() (στη μονάδα curses)
@anchor{library/curses curses set_tabsize}@anchor{cc3}
@deffn {Συνάρτηση} 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.


Added in version 3.9.

@end deffn

@geindex setsyx() (στη μονάδα curses)
@anchor{library/curses curses setsyx}@anchor{36fa}
@deffn {Συνάρτηση} curses.setsyx (y, x)

Set the virtual screen cursor to `y', `x'. If `y' and `x' are both @code{-1}, then
@ref{36e0,,leaveok} is set @code{True}.
@end deffn

@geindex setupterm() (στη μονάδα curses)
@anchor{library/curses curses setupterm}@anchor{36fb}
@deffn {Συνάρτηση} 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 μεταβλητή περιβάλλοντος; 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() (στη μονάδα curses)
@anchor{library/curses curses start_color}@anchor{36fc}
@deffn {Συνάρτηση} 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{1a1b,,initscr()}.

@code{start_color()} initializes eight basic colors (black, red,  green, yellow,
blue, magenta, cyan, and white), and two global variables in the @code{curses}
module, @ref{36fd,,COLORS} and @ref{36fe,,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() (στη μονάδα curses)
@anchor{library/curses curses termattrs}@anchor{1a1e}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses termname}@anchor{1a1f}
@deffn {Συνάρτηση} curses.termname ()

Return the value of the environment variable 
@geindex TERM
@geindex μεταβλητή περιβάλλοντος; TERM
@code{TERM}, as a bytes object,
truncated to 14 characters.
@end deffn

@geindex tigetflag() (στη μονάδα curses)
@anchor{library/curses curses tigetflag}@anchor{36ff}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses tigetnum}@anchor{3700}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses tigetstr}@anchor{3701}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses tparm}@anchor{3702}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses typeahead}@anchor{3703}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses unctrl}@anchor{1a20}
@deffn {Συνάρτηση} 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() (στη μονάδα curses)
@anchor{library/curses curses ungetch}@anchor{3704}
@deffn {Συνάρτηση} curses.ungetch (ch)

Push `ch' so the next @ref{1a30,,getch()} will return it.

@cartouche
@quotation Σημείωση 
Only one `ch' can be pushed before @code{getch()} is called.
@end quotation
@end cartouche
@end deffn

@geindex update_lines_cols() (στη μονάδα curses)
@anchor{library/curses curses update_lines_cols}@anchor{11a3}
@deffn {Συνάρτηση} curses.update_lines_cols ()

Update the @ref{11a4,,LINES} and @ref{11a5,,COLS} module variables.
Useful for detecting manual screen resize.


Added in version 3.5.

@end deffn

@geindex unget_wch() (στη μονάδα curses)
@anchor{library/curses curses unget_wch}@anchor{1445}
@deffn {Συνάρτηση} curses.unget_wch (ch)

Push `ch' so the next @ref{1444,,get_wch()} will return it.

@cartouche
@quotation Σημείωση 
Only one `ch' can be pushed before @code{get_wch()} is called.
@end quotation
@end cartouche


Added in version 3.3.

@end deffn

@geindex ungetmouse() (στη μονάδα curses)
@anchor{library/curses curses ungetmouse}@anchor{3705}
@deffn {Συνάρτηση} curses.ungetmouse (id, x, y, z, bstate)

Push a @ref{36d6,,KEY_MOUSE} event onto the input queue, associating the given
state data with it.
@end deffn

@geindex use_env() (στη μονάδα curses)
@anchor{library/curses curses use_env}@anchor{3706}
@deffn {Συνάρτηση} curses.use_env (flag)

If used, this function should be called before @ref{1a1b,,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 μεταβλητή περιβάλλοντος; LINES
@code{LINES}
and 
@geindex COLUMNS
@geindex μεταβλητή περιβάλλοντος; 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 μεταβλητή περιβάλλοντος; LINES
@code{LINES} and 
@geindex COLUMNS
@geindex μεταβλητή περιβάλλοντος; COLUMNS
@code{COLUMNS} are not set).
@end deffn

@geindex use_default_colors() (στη μονάδα curses)
@anchor{library/curses curses use_default_colors}@anchor{48a}
@deffn {Συνάρτηση} curses.use_default_colors ()

Equivalent to @code{assume_default_colors(-1, -1)}.
@end deffn

@geindex wrapper() (στη μονάδα curses)
@anchor{library/curses curses wrapper}@anchor{e42}
@deffn {Συνάρτηση} 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,Constants<6>,Functions<4>,curses — Terminal handling for character-cell displays
@anchor{library/curses curses-window-objects}@anchor{1a24}@anchor{library/curses window-objects}@anchor{3707}
@subsubsection Window Objects


@geindex window (κλάση σε curses)
@anchor{library/curses curses window}@anchor{1442}
@deffn {Κλάση} curses.window

Window objects, as returned by @ref{1a1b,,initscr()} and @ref{36f1,,newwin()} above, have
the following methods and attributes:
@end deffn

@geindex addch() (μέθοδος της curses.window)
@anchor{library/curses curses window addch}@anchor{1a25}
@deffn {Μέθοδος} window.addch (ch[, attr])

@deffnx {Μέθοδος} 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 Σημείωση 
Writing outside the window, subwindow, or pad raises a @ref{1a16,,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() (μέθοδος της curses.window)
@anchor{library/curses curses window addnstr}@anchor{1a26}
@deffn {Μέθοδος} window.addnstr (str, n[, attr])

@deffnx {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window addstr}@anchor{1a27}
@deffn {Μέθοδος} window.addstr (str[, attr])

@deffnx {Μέθοδος} 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 Σημείωση 

@itemize *

@item 
Writing outside the window, subwindow, or pad raises @ref{1a16,,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{1a27,,addstr()}
with a `str' that has embedded newlines.  Instead, call @code{addstr()}
separately for each line.
@end itemize
@end quotation
@end cartouche
@end deffn

@geindex attroff() (μέθοδος της curses.window)
@anchor{library/curses curses window attroff}@anchor{3708}
@deffn {Μέθοδος} window.attroff (attr)

Remove attribute `attr' from the «background» set applied to all writes to the
current window.
@end deffn

@geindex attron() (μέθοδος της curses.window)
@anchor{library/curses curses window attron}@anchor{3709}
@deffn {Μέθοδος} window.attron (attr)

Add attribute `attr' to the «background» set applied to all writes to the
current window.
@end deffn

@geindex attrset() (μέθοδος της curses.window)
@anchor{library/curses curses window attrset}@anchor{370a}
@deffn {Μέθοδος} window.attrset (attr)

Set the «background» set of attributes to `attr'.  This set is initially
@code{0} (no attributes).
@end deffn

@geindex bkgd() (μέθοδος της curses.window)
@anchor{library/curses curses window bkgd}@anchor{370b}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window bkgdset}@anchor{370c}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window border}@anchor{1a28}
@deffn {Μέθοδος} 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 Σημείωση 
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

Parameter

@tab

Description

@tab

Default value

@item

`ls'

@tab

Left side

@tab

@ref{370d,,ACS_VLINE}

@item

`rs'

@tab

Right side

@tab

@ref{370d,,ACS_VLINE}

@item

`ts'

@tab

Top

@tab

@ref{370e,,ACS_HLINE}

@item

`bs'

@tab

Bottom

@tab

@ref{370e,,ACS_HLINE}

@item

`tl'

@tab

Upper-left corner

@tab

@ref{370f,,ACS_ULCORNER}

@item

`tr'

@tab

Upper-right corner

@tab

@ref{3710,,ACS_URCORNER}

@item

`bl'

@tab

Bottom-left corner

@tab

@ref{3711,,ACS_LLCORNER}

@item

`br'

@tab

Bottom-right corner

@tab

@ref{3712,,ACS_LRCORNER}

@end multitable

@end deffn

@geindex box() (μέθοδος της curses.window)
@anchor{library/curses curses window box}@anchor{1a29}
@deffn {Μέθοδος} window.box ([vertch, horch])

Similar to @ref{1a28,,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() (μέθοδος της curses.window)
@anchor{library/curses curses window chgat}@anchor{1a2a}
@deffn {Μέθοδος} window.chgat (attr)

@deffnx {Μέθοδος} window.chgat (num, attr)

@deffnx {Μέθοδος} window.chgat (y, x, attr)

@deffnx {Μέθοδος} 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{3713,,touchline()} method so that the contents will
be redisplayed by the next window refresh.
@end deffn

@geindex clear() (μέθοδος της curses.window)
@anchor{library/curses curses window clear}@anchor{3714}
@deffn {Μέθοδος} window.clear ()

Like @ref{3715,,erase()}, but also cause the whole window to be repainted upon next
call to @ref{1a21,,refresh()}.
@end deffn

@geindex clearok() (μέθοδος της curses.window)
@anchor{library/curses curses window clearok}@anchor{3716}
@deffn {Μέθοδος} window.clearok (flag)

If `flag' is @code{True}, the next call to @ref{1a21,,refresh()} will clear the window
completely.
@end deffn

@geindex clrtobot() (μέθοδος της curses.window)
@anchor{library/curses curses window clrtobot}@anchor{3717}
@deffn {Μέθοδος} window.clrtobot ()

Erase from cursor to the end of the window: all lines below the cursor are
deleted, and then the equivalent of @ref{3718,,clrtoeol()} is performed.
@end deffn

@geindex clrtoeol() (μέθοδος της curses.window)
@anchor{library/curses curses window clrtoeol}@anchor{3718}
@deffn {Μέθοδος} window.clrtoeol ()

Erase from cursor to the end of the line.
@end deffn

@geindex cursyncup() (μέθοδος της curses.window)
@anchor{library/curses curses window cursyncup}@anchor{3719}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window delch}@anchor{371a}
@deffn {Μέθοδος} window.delch ([y, x])

Delete any character at @code{(y, x)}.
@end deffn

@geindex deleteln() (μέθοδος της curses.window)
@anchor{library/curses curses window deleteln}@anchor{371b}
@deffn {Μέθοδος} window.deleteln ()

Delete the line under the cursor. All following lines are moved up by one line.
@end deffn

@geindex derwin() (μέθοδος της curses.window)
@anchor{library/curses curses window derwin}@anchor{371c}
@deffn {Μέθοδος} window.derwin (begin_y, begin_x)

@deffnx {Μέθοδος} window.derwin (nlines, ncols, begin_y, begin_x)

An abbreviation for «derive window», @code{derwin()} is the same as calling
@ref{371d,,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() (μέθοδος της curses.window)
@anchor{library/curses curses window echochar}@anchor{371e}
@deffn {Μέθοδος} window.echochar (ch[, attr])

Add character `ch' with attribute `attr', and immediately  call @ref{1a21,,refresh()}
on the window.
@end deffn

@geindex enclose() (μέθοδος της curses.window)
@anchor{library/curses curses window enclose}@anchor{1e87}
@deffn {Μέθοδος} 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.


Άλλαξε στην έκδοση 3.10: Previously it returned @code{1} or @code{0} instead of @code{True} or @code{False}.

@end deffn

@geindex encoding (ιδιότητα της curses.window)
@anchor{library/curses curses window encoding}@anchor{1443}
@deffn {Ιδιότητα} 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{371d,,window.subwin()}.
By default, current locale encoding is used (see @ref{a45,,locale.getencoding()}).


Added in version 3.3.

@end deffn

@geindex erase() (μέθοδος της curses.window)
@anchor{library/curses curses window erase}@anchor{3715}
@deffn {Μέθοδος} window.erase ()

Clear the window.
@end deffn

@geindex getbegyx() (μέθοδος της curses.window)
@anchor{library/curses curses window getbegyx}@anchor{371f}
@deffn {Μέθοδος} window.getbegyx ()

Return a tuple @code{(y, x)} of coordinates of upper-left corner.
@end deffn

@geindex getbkgd() (μέθοδος της curses.window)
@anchor{library/curses curses window getbkgd}@anchor{1a2b}
@deffn {Μέθοδος} window.getbkgd ()

Return the given window’s current background character/attribute pair.
@end deffn

@geindex getch() (μέθοδος της curses.window)
@anchor{library/curses curses window getch}@anchor{1a30}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window get_wch}@anchor{1444}
@deffn {Μέθοδος} 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.


Added in version 3.3.

@end deffn

@geindex getkey() (μέθοδος της curses.window)
@anchor{library/curses curses window getkey}@anchor{3720}
@deffn {Μέθοδος} window.getkey ([y, x])

Get a character, returning a string instead of an integer, as @ref{1a30,,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() (μέθοδος της curses.window)
@anchor{library/curses curses window getmaxyx}@anchor{3721}
@deffn {Μέθοδος} window.getmaxyx ()

Return a tuple @code{(y, x)} of the height and width of the window.
@end deffn

@geindex getparyx() (μέθοδος της curses.window)
@anchor{library/curses curses window getparyx}@anchor{3722}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window getstr}@anchor{1a34}
@deffn {Μέθοδος} window.getstr ()

@deffnx {Μέθοδος} window.getstr (n)

@deffnx {Μέθοδος} window.getstr (y, x)

@deffnx {Μέθοδος} window.getstr (y, x, n)

Read a bytes object from the user, with primitive line editing capacity.
The maximum value for `n' is 2047.


Άλλαξε στην έκδοση 3.14: The maximum value for `n' was increased from 1023 to 2047.

@end deffn

@geindex getyx() (μέθοδος της curses.window)
@anchor{library/curses curses window getyx}@anchor{3723}
@deffn {Μέθοδος} window.getyx ()

Return a tuple @code{(y, x)} of current cursor position  relative to the window’s
upper-left corner.
@end deffn

@geindex hline() (μέθοδος της curses.window)
@anchor{library/curses curses window hline}@anchor{3724}
@deffn {Μέθοδος} window.hline (ch, n)

@deffnx {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window idcok}@anchor{3725}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window idlok}@anchor{3726}
@deffn {Μέθοδος} window.idlok (flag)

If `flag' is @code{True}, @code{curses} will try and use hardware line
editing facilities. Otherwise, line insertion/deletion are disabled.
@end deffn

@geindex immedok() (μέθοδος της curses.window)
@anchor{library/curses curses window immedok}@anchor{3727}
@deffn {Μέθοδος} 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{1a21,,refresh()} yourself.
However, it may degrade performance considerably, due to repeated calls to
wrefresh.  This option is disabled by default.
@end deffn

@geindex inch() (μέθοδος της curses.window)
@anchor{library/curses curses window inch}@anchor{1a2c}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window insch}@anchor{3728}
@deffn {Μέθοδος} window.insch (ch[, attr])

@deffnx {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window insdelln}@anchor{3729}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window insertln}@anchor{372a}
@deffn {Μέθοδος} window.insertln ()

Insert a blank line under the cursor. All following lines are moved down by one
line.
@end deffn

@geindex insnstr() (μέθοδος της curses.window)
@anchor{library/curses curses window insnstr}@anchor{1a2e}
@deffn {Μέθοδος} window.insnstr (str, n[, attr])

@deffnx {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window insstr}@anchor{1a2d}
@deffn {Μέθοδος} window.insstr (str[, attr])

@deffnx {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window instr}@anchor{1a33}
@deffn {Μέθοδος} window.instr ([n])

@deffnx {Μέθοδος} 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, @code{instr()} returns a string
at most `n' characters long (exclusive of the trailing NUL).
The maximum value for `n' is 2047.


Άλλαξε στην έκδοση 3.14: The maximum value for `n' was increased from 1023 to 2047.

@end deffn

@geindex is_linetouched() (μέθοδος της curses.window)
@anchor{library/curses curses window is_linetouched}@anchor{372b}
@deffn {Μέθοδος} window.is_linetouched (line)

Return @code{True} if the specified line was modified since the last call to
@ref{1a21,,refresh()}; otherwise return @code{False}.  Raise a @ref{1a16,,curses.error}
exception if `line' is not valid for the given window.
@end deffn

@geindex is_wintouched() (μέθοδος της curses.window)
@anchor{library/curses curses window is_wintouched}@anchor{372c}
@deffn {Μέθοδος} window.is_wintouched ()

Return @code{True} if the specified window was modified since the last call to
@ref{1a21,,refresh()}; otherwise return @code{False}.
@end deffn

@geindex keypad() (μέθοδος της curses.window)
@anchor{library/curses curses window keypad}@anchor{372d}
@deffn {Μέθοδος} window.keypad (flag)

If `flag' is @code{True}, escape sequences generated by some keys (keypad,  function keys)
will be interpreted by @code{curses}. If `flag' is @code{False}, escape sequences will be
left as is in the input stream.
@end deffn

@geindex leaveok() (μέθοδος της curses.window)
@anchor{library/curses curses window leaveok}@anchor{36e0}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window move}@anchor{372e}
@deffn {Μέθοδος} window.move (new_y, new_x)

Move cursor to @code{(new_y, new_x)}.
@end deffn

@geindex mvderwin() (μέθοδος της curses.window)
@anchor{library/curses curses window mvderwin}@anchor{372f}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window mvwin}@anchor{3730}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window nodelay}@anchor{3731}
@deffn {Μέθοδος} window.nodelay (flag)

If `flag' is @code{True}, @ref{1a30,,getch()} will be non-blocking.
@end deffn

@geindex notimeout() (μέθοδος της curses.window)
@anchor{library/curses curses window notimeout}@anchor{3732}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window noutrefresh}@anchor{1a22}
@deffn {Μέθοδος} 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{36cf,,doupdate()}.
@end deffn

@geindex overlay() (μέθοδος της curses.window)
@anchor{library/curses curses window overlay}@anchor{3733}
@deffn {Μέθοδος} 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
@code{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() (μέθοδος της curses.window)
@anchor{library/curses curses window overwrite}@anchor{3734}
@deffn {Μέθοδος} 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
@code{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() (μέθοδος της curses.window)
@anchor{library/curses curses window putwin}@anchor{36e2}
@deffn {Μέθοδος} window.putwin (file)

Write all data associated with the window into the provided file object.  This
information can be later retrieved using the @ref{36e1,,getwin()} function.
@end deffn

@geindex redrawln() (μέθοδος της curses.window)
@anchor{library/curses curses window redrawln}@anchor{3735}
@deffn {Μέθοδος} 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{1a21,,refresh()} call.
@end deffn

@geindex redrawwin() (μέθοδος της curses.window)
@anchor{library/curses curses window redrawwin}@anchor{3736}
@deffn {Μέθοδος} window.redrawwin ()

Touch the entire window, causing it to be completely redrawn on the next
@ref{1a21,,refresh()} call.
@end deffn

@geindex refresh() (μέθοδος της curses.window)
@anchor{library/curses curses window refresh}@anchor{1a21}
@deffn {Μέθοδος} 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{36f0,,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() (μέθοδος της curses.window)
@anchor{library/curses curses window resize}@anchor{3737}
@deffn {Μέθοδος} 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{370c,,bkgdset()}) merged into them.
@end deffn

@geindex scroll() (μέθοδος της curses.window)
@anchor{library/curses curses window scroll}@anchor{3738}
@deffn {Μέθοδος} window.scroll ([lines=1])

Scroll the screen or scrolling region upward by `lines' lines.
@end deffn

@geindex scrollok() (μέθοδος της curses.window)
@anchor{library/curses curses window scrollok}@anchor{3739}
@deffn {Μέθοδος} 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{3726,,idlok()}.
@end deffn

@geindex setscrreg() (μέθοδος της curses.window)
@anchor{library/curses curses window setscrreg}@anchor{373a}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window standend}@anchor{373b}
@deffn {Μέθοδος} window.standend ()

Turn off the standout attribute.  On some terminals this has the side effect of
turning off all attributes.
@end deffn

@geindex standout() (μέθοδος της curses.window)
@anchor{library/curses curses window standout}@anchor{373c}
@deffn {Μέθοδος} window.standout ()

Turn on attribute `A_STANDOUT'.
@end deffn

@geindex subpad() (μέθοδος της curses.window)
@anchor{library/curses curses window subpad}@anchor{373d}
@deffn {Μέθοδος} window.subpad (begin_y, begin_x)

@deffnx {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window subwin}@anchor{371d}
@deffn {Μέθοδος} window.subwin (begin_y, begin_x)

@deffnx {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window syncdown}@anchor{373e}
@deffn {Μέθοδος} window.syncdown ()

Touch each location in the window that has been touched in any of its ancestor
windows.  This routine is called by @ref{1a21,,refresh()}, so it should almost never
be necessary to call it manually.
@end deffn

@geindex syncok() (μέθοδος της curses.window)
@anchor{library/curses curses window syncok}@anchor{373f}
@deffn {Μέθοδος} window.syncok (flag)

If `flag' is @code{True}, then @ref{3740,,syncup()} is called automatically
whenever there is a change in the window.
@end deffn

@geindex syncup() (μέθοδος της curses.window)
@anchor{library/curses curses window syncup}@anchor{3740}
@deffn {Μέθοδος} window.syncup ()

Touch all locations in ancestors of the window that have been changed in  the
window.
@end deffn

@geindex timeout() (μέθοδος της curses.window)
@anchor{library/curses curses window timeout}@anchor{3741}
@deffn {Μέθοδος} 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{1a30,,getch()} will
return @code{-1} if no input is waiting.  If `delay' is positive, then
@code{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() (μέθοδος της curses.window)
@anchor{library/curses curses window touchline}@anchor{3713}
@deffn {Μέθοδος} 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() (μέθοδος της curses.window)
@anchor{library/curses curses window touchwin}@anchor{3742}
@deffn {Μέθοδος} window.touchwin ()

Pretend the whole window has been changed, for purposes of drawing
optimizations.
@end deffn

@geindex untouchwin() (μέθοδος της curses.window)
@anchor{library/curses curses window untouchwin}@anchor{3743}
@deffn {Μέθοδος} window.untouchwin ()

Mark all lines in  the  window  as unchanged since the last call to
@ref{1a21,,refresh()}.
@end deffn

@geindex vline() (μέθοδος της curses.window)
@anchor{library/curses curses window vline}@anchor{1cfd}
@deffn {Μέθοδος} window.vline (ch, n[, attr])

@deffnx {Μέθοδος} 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 Constants<6>,,Window Objects,curses — Terminal handling for character-cell displays
@anchor{library/curses constants}@anchor{3744}
@subsubsection Constants


The @code{curses} module defines the following data members:

@geindex ERR (στη μονάδα curses)
@anchor{library/curses curses ERR}@anchor{3745}
@deffn {Δεδομένα} curses.ERR

Some curses routines  that  return  an integer, such as @ref{1a30,,getch()}, return
@ref{3745,,ERR} upon failure.
@end deffn

@geindex OK (στη μονάδα curses)
@anchor{library/curses curses OK}@anchor{3746}
@deffn {Δεδομένα} curses.OK

Some curses routines  that  return  an integer, such as  @ref{1b2a,,napms()}, return
@ref{3746,,OK} upon success.
@end deffn

@geindex version (στη μονάδα curses)
@anchor{library/curses curses version}@anchor{3747}
@deffn {Δεδομένα} curses.version

A bytes object representing the current version of the module.
@end deffn

@geindex ncurses_version (στη μονάδα curses)
@anchor{library/curses curses ncurses_version}@anchor{dab}
@deffn {Δεδομένα} 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.


Added in version 3.8.

@end deffn

@geindex COLORS (στη μονάδα curses)
@anchor{library/curses curses COLORS}@anchor{36fd}
@deffn {Δεδομένα} curses.COLORS

The maximum number of colors the terminal can support.
It is defined only after the call to @ref{36fc,,start_color()}.
@end deffn

@geindex COLOR_PAIRS (στη μονάδα curses)
@anchor{library/curses curses COLOR_PAIRS}@anchor{36fe}
@deffn {Δεδομένα} curses.COLOR_PAIRS

The maximum number of color pairs the terminal can support.
It is defined only after the call to @ref{36fc,,start_color()}.
@end deffn

@geindex COLS (στη μονάδα curses)
@anchor{library/curses curses COLS}@anchor{11a5}
@deffn {Δεδομένα} curses.COLS

The width of the screen, i.e., the number of columns.
It is defined only after the call to @ref{1a1b,,initscr()}.
Updated by @ref{11a3,,update_lines_cols()}, @ref{1b4a,,resizeterm()} and
@ref{1b4b,,resize_term()}.
@end deffn

@geindex LINES (στη μονάδα curses)
@anchor{library/curses curses LINES}@anchor{11a4}
@deffn {Δεδομένα} curses.LINES

The height of the screen, i.e., the number of lines.
It is defined only after the call to @ref{1a1b,,initscr()}.
Updated by @ref{11a3,,update_lines_cols()}, @ref{1b4a,,resizeterm()} and
@ref{1b4b,,resize_term()}.
@end deffn

Some constants are available to specify character cell attributes.
The exact constants available are system dependent.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribute

@tab

Meaning

@item

@geindex A_ALTCHARSET (στη μονάδα curses)
@anchor{library/curses curses A_ALTCHARSET}@anchor{3748}
@deffn {Δεδομένα} curses.A_ALTCHARSET
@end deffn

@tab

Alternate character set mode

@item

@geindex A_BLINK (στη μονάδα curses)
@anchor{library/curses curses A_BLINK}@anchor{3749}
@deffn {Δεδομένα} curses.A_BLINK
@end deffn

@tab

Blink mode

@item

@geindex A_BOLD (στη μονάδα curses)
@anchor{library/curses curses A_BOLD}@anchor{374a}
@deffn {Δεδομένα} curses.A_BOLD
@end deffn

@tab

Bold mode

@item

@geindex A_DIM (στη μονάδα curses)
@anchor{library/curses curses A_DIM}@anchor{374b}
@deffn {Δεδομένα} curses.A_DIM
@end deffn

@tab

Dim mode

@item

@geindex A_INVIS (στη μονάδα curses)
@anchor{library/curses curses A_INVIS}@anchor{374c}
@deffn {Δεδομένα} curses.A_INVIS
@end deffn

@tab

Invisible or blank mode

@item

@geindex A_ITALIC (στη μονάδα curses)
@anchor{library/curses curses A_ITALIC}@anchor{374d}
@deffn {Δεδομένα} curses.A_ITALIC
@end deffn

@tab

Italic mode

@item

@geindex A_NORMAL (στη μονάδα curses)
@anchor{library/curses curses A_NORMAL}@anchor{36c2}
@deffn {Δεδομένα} curses.A_NORMAL
@end deffn

@tab

Normal attribute

@item

@geindex A_PROTECT (στη μονάδα curses)
@anchor{library/curses curses A_PROTECT}@anchor{374e}
@deffn {Δεδομένα} curses.A_PROTECT
@end deffn

@tab

Protected mode

@item

@geindex A_REVERSE (στη μονάδα curses)
@anchor{library/curses curses A_REVERSE}@anchor{36c7}
@deffn {Δεδομένα} curses.A_REVERSE
@end deffn

@tab

Reverse background and
foreground colors

@item

@geindex A_STANDOUT (στη μονάδα curses)
@anchor{library/curses curses A_STANDOUT}@anchor{36c6}
@deffn {Δεδομένα} curses.A_STANDOUT
@end deffn

@tab

Standout mode

@item

@geindex A_UNDERLINE (στη μονάδα curses)
@anchor{library/curses curses A_UNDERLINE}@anchor{374f}
@deffn {Δεδομένα} curses.A_UNDERLINE
@end deffn

@tab

Underline mode

@item

@geindex A_HORIZONTAL (στη μονάδα curses)
@anchor{library/curses curses A_HORIZONTAL}@anchor{3750}
@deffn {Δεδομένα} curses.A_HORIZONTAL
@end deffn

@tab

Horizontal highlight

@item

@geindex A_LEFT (στη μονάδα curses)
@anchor{library/curses curses A_LEFT}@anchor{3751}
@deffn {Δεδομένα} curses.A_LEFT
@end deffn

@tab

Left highlight

@item

@geindex A_LOW (στη μονάδα curses)
@anchor{library/curses curses A_LOW}@anchor{3752}
@deffn {Δεδομένα} curses.A_LOW
@end deffn

@tab

Low highlight

@item

@geindex A_RIGHT (στη μονάδα curses)
@anchor{library/curses curses A_RIGHT}@anchor{3753}
@deffn {Δεδομένα} curses.A_RIGHT
@end deffn

@tab

Right highlight

@item

@geindex A_TOP (στη μονάδα curses)
@anchor{library/curses curses A_TOP}@anchor{3754}
@deffn {Δεδομένα} curses.A_TOP
@end deffn

@tab

Top highlight

@item

@geindex A_VERTICAL (στη μονάδα curses)
@anchor{library/curses curses A_VERTICAL}@anchor{3755}
@deffn {Δεδομένα} curses.A_VERTICAL
@end deffn

@tab

Vertical highlight

@end multitable



Added in 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

Meaning

@item

@geindex A_ATTRIBUTES (στη μονάδα curses)
@anchor{library/curses curses A_ATTRIBUTES}@anchor{3756}
@deffn {Δεδομένα} curses.A_ATTRIBUTES
@end deffn

@tab

Bit-mask to extract
attributes

@item

@geindex A_CHARTEXT (στη μονάδα curses)
@anchor{library/curses curses A_CHARTEXT}@anchor{3757}
@deffn {Δεδομένα} curses.A_CHARTEXT
@end deffn

@tab

Bit-mask to extract a
character

@item

@geindex A_COLOR (στη μονάδα curses)
@anchor{library/curses curses A_COLOR}@anchor{3758}
@deffn {Δεδομένα} 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

Key

@item

@geindex KEY_MIN (στη μονάδα curses)
@anchor{library/curses curses KEY_MIN}@anchor{3759}
@deffn {Δεδομένα} curses.KEY_MIN
@end deffn

@tab

Minimum key value

@item

@geindex KEY_BREAK (στη μονάδα curses)
@anchor{library/curses curses KEY_BREAK}@anchor{375a}
@deffn {Δεδομένα} curses.KEY_BREAK
@end deffn

@tab

Break key (unreliable)

@item

@geindex KEY_DOWN (στη μονάδα curses)
@anchor{library/curses curses KEY_DOWN}@anchor{375b}
@deffn {Δεδομένα} curses.KEY_DOWN
@end deffn

@tab

Down-arrow

@item

@geindex KEY_UP (στη μονάδα curses)
@anchor{library/curses curses KEY_UP}@anchor{375c}
@deffn {Δεδομένα} curses.KEY_UP
@end deffn

@tab

Up-arrow

@item

@geindex KEY_LEFT (στη μονάδα curses)
@anchor{library/curses curses KEY_LEFT}@anchor{375d}
@deffn {Δεδομένα} curses.KEY_LEFT
@end deffn

@tab

Left-arrow

@item

@geindex KEY_RIGHT (στη μονάδα curses)
@anchor{library/curses curses KEY_RIGHT}@anchor{375e}
@deffn {Δεδομένα} curses.KEY_RIGHT
@end deffn

@tab

Right-arrow

@item

@geindex KEY_HOME (στη μονάδα curses)
@anchor{library/curses curses KEY_HOME}@anchor{375f}
@deffn {Δεδομένα} curses.KEY_HOME
@end deffn

@tab

Home key (upward+left arrow)

@item

@geindex KEY_BACKSPACE (στη μονάδα curses)
@anchor{library/curses curses KEY_BACKSPACE}@anchor{3760}
@deffn {Δεδομένα} curses.KEY_BACKSPACE
@end deffn

@tab

Backspace (unreliable)

@item

@geindex KEY_F0 (στη μονάδα curses)
@anchor{library/curses curses KEY_F0}@anchor{3761}
@deffn {Δεδομένα} curses.KEY_F0
@end deffn

@tab

Function keys.  Up to 64 function keys are
supported.

@item

@geindex KEY_Fn (στη μονάδα curses)
@anchor{library/curses curses KEY_Fn}@anchor{3762}
@deffn {Δεδομένα} curses.KEY_Fn
@end deffn

@tab

Value of function key `n'

@item

@geindex KEY_DL (στη μονάδα curses)
@anchor{library/curses curses KEY_DL}@anchor{3763}
@deffn {Δεδομένα} curses.KEY_DL
@end deffn

@tab

Delete line

@item

@geindex KEY_IL (στη μονάδα curses)
@anchor{library/curses curses KEY_IL}@anchor{3764}
@deffn {Δεδομένα} curses.KEY_IL
@end deffn

@tab

Insert line

@item

@geindex KEY_DC (στη μονάδα curses)
@anchor{library/curses curses KEY_DC}@anchor{3765}
@deffn {Δεδομένα} curses.KEY_DC
@end deffn

@tab

Delete character

@item

@geindex KEY_IC (στη μονάδα curses)
@anchor{library/curses curses KEY_IC}@anchor{3766}
@deffn {Δεδομένα} curses.KEY_IC
@end deffn

@tab

Insert char or enter insert mode

@item

@geindex KEY_EIC (στη μονάδα curses)
@anchor{library/curses curses KEY_EIC}@anchor{3767}
@deffn {Δεδομένα} curses.KEY_EIC
@end deffn

@tab

Exit insert char mode

@item

@geindex KEY_CLEAR (στη μονάδα curses)
@anchor{library/curses curses KEY_CLEAR}@anchor{3768}
@deffn {Δεδομένα} curses.KEY_CLEAR
@end deffn

@tab

Clear screen

@item

@geindex KEY_EOS (στη μονάδα curses)
@anchor{library/curses curses KEY_EOS}@anchor{3769}
@deffn {Δεδομένα} curses.KEY_EOS
@end deffn

@tab

Clear to end of screen

@item

@geindex KEY_EOL (στη μονάδα curses)
@anchor{library/curses curses KEY_EOL}@anchor{376a}
@deffn {Δεδομένα} curses.KEY_EOL
@end deffn

@tab

Clear to end of line

@item

@geindex KEY_SF (στη μονάδα curses)
@anchor{library/curses curses KEY_SF}@anchor{376b}
@deffn {Δεδομένα} curses.KEY_SF
@end deffn

@tab

Scroll 1 line forward

@item

@geindex KEY_SR (στη μονάδα curses)
@anchor{library/curses curses KEY_SR}@anchor{376c}
@deffn {Δεδομένα} curses.KEY_SR
@end deffn

@tab

Scroll 1 line backward (reverse)

@item

@geindex KEY_NPAGE (στη μονάδα curses)
@anchor{library/curses curses KEY_NPAGE}@anchor{376d}
@deffn {Δεδομένα} curses.KEY_NPAGE
@end deffn

@tab

Next page

@item

@geindex KEY_PPAGE (στη μονάδα curses)
@anchor{library/curses curses KEY_PPAGE}@anchor{376e}
@deffn {Δεδομένα} curses.KEY_PPAGE
@end deffn

@tab

Previous page

@item

@geindex KEY_STAB (στη μονάδα curses)
@anchor{library/curses curses KEY_STAB}@anchor{376f}
@deffn {Δεδομένα} curses.KEY_STAB
@end deffn

@tab

Set tab

@item

@geindex KEY_CTAB (στη μονάδα curses)
@anchor{library/curses curses KEY_CTAB}@anchor{3770}
@deffn {Δεδομένα} curses.KEY_CTAB
@end deffn

@tab

Clear tab

@item

@geindex KEY_CATAB (στη μονάδα curses)
@anchor{library/curses curses KEY_CATAB}@anchor{3771}
@deffn {Δεδομένα} curses.KEY_CATAB
@end deffn

@tab

Clear all tabs

@item

@geindex KEY_ENTER (στη μονάδα curses)
@anchor{library/curses curses KEY_ENTER}@anchor{3772}
@deffn {Δεδομένα} curses.KEY_ENTER
@end deffn

@tab

Enter or send (unreliable)

@item

@geindex KEY_SRESET (στη μονάδα curses)
@anchor{library/curses curses KEY_SRESET}@anchor{3773}
@deffn {Δεδομένα} curses.KEY_SRESET
@end deffn

@tab

Soft (partial) reset (unreliable)

@item

@geindex KEY_RESET (στη μονάδα curses)
@anchor{library/curses curses KEY_RESET}@anchor{3774}
@deffn {Δεδομένα} curses.KEY_RESET
@end deffn

@tab

Reset or hard reset (unreliable)

@item

@geindex KEY_PRINT (στη μονάδα curses)
@anchor{library/curses curses KEY_PRINT}@anchor{3775}
@deffn {Δεδομένα} curses.KEY_PRINT
@end deffn

@tab

Print

@item

@geindex KEY_LL (στη μονάδα curses)
@anchor{library/curses curses KEY_LL}@anchor{3776}
@deffn {Δεδομένα} curses.KEY_LL
@end deffn

@tab

Home down or bottom (lower left)

@item

@geindex KEY_A1 (στη μονάδα curses)
@anchor{library/curses curses KEY_A1}@anchor{3777}
@deffn {Δεδομένα} curses.KEY_A1
@end deffn

@tab

Upper left of keypad

@item

@geindex KEY_A3 (στη μονάδα curses)
@anchor{library/curses curses KEY_A3}@anchor{3778}
@deffn {Δεδομένα} curses.KEY_A3
@end deffn

@tab

Upper right of keypad

@item

@geindex KEY_B2 (στη μονάδα curses)
@anchor{library/curses curses KEY_B2}@anchor{3779}
@deffn {Δεδομένα} curses.KEY_B2
@end deffn

@tab

Center of keypad

@item

@geindex KEY_C1 (στη μονάδα curses)
@anchor{library/curses curses KEY_C1}@anchor{377a}
@deffn {Δεδομένα} curses.KEY_C1
@end deffn

@tab

Lower left of keypad

@item

@geindex KEY_C3 (στη μονάδα curses)
@anchor{library/curses curses KEY_C3}@anchor{377b}
@deffn {Δεδομένα} curses.KEY_C3
@end deffn

@tab

Lower right of keypad

@item

@geindex KEY_BTAB (στη μονάδα curses)
@anchor{library/curses curses KEY_BTAB}@anchor{377c}
@deffn {Δεδομένα} curses.KEY_BTAB
@end deffn

@tab

Back tab

@item

@geindex KEY_BEG (στη μονάδα curses)
@anchor{library/curses curses KEY_BEG}@anchor{377d}
@deffn {Δεδομένα} curses.KEY_BEG
@end deffn

@tab

Beg (beginning)

@item

@geindex KEY_CANCEL (στη μονάδα curses)
@anchor{library/curses curses KEY_CANCEL}@anchor{377e}
@deffn {Δεδομένα} curses.KEY_CANCEL
@end deffn

@tab

Cancel

@item

@geindex KEY_CLOSE (στη μονάδα curses)
@anchor{library/curses curses KEY_CLOSE}@anchor{377f}
@deffn {Δεδομένα} curses.KEY_CLOSE
@end deffn

@tab

Close

@item

@geindex KEY_COMMAND (στη μονάδα curses)
@anchor{library/curses curses KEY_COMMAND}@anchor{3780}
@deffn {Δεδομένα} curses.KEY_COMMAND
@end deffn

@tab

Cmd (command)

@item

@geindex KEY_COPY (στη μονάδα curses)
@anchor{library/curses curses KEY_COPY}@anchor{3781}
@deffn {Δεδομένα} curses.KEY_COPY
@end deffn

@tab

Copy

@item

@geindex KEY_CREATE (στη μονάδα curses)
@anchor{library/curses curses KEY_CREATE}@anchor{3782}
@deffn {Δεδομένα} curses.KEY_CREATE
@end deffn

@tab

Create

@item

@geindex KEY_END (στη μονάδα curses)
@anchor{library/curses curses KEY_END}@anchor{3783}
@deffn {Δεδομένα} curses.KEY_END
@end deffn

@tab

End

@item

@geindex KEY_EXIT (στη μονάδα curses)
@anchor{library/curses curses KEY_EXIT}@anchor{3784}
@deffn {Δεδομένα} curses.KEY_EXIT
@end deffn

@tab

Exit

@item

@geindex KEY_FIND (στη μονάδα curses)
@anchor{library/curses curses KEY_FIND}@anchor{3785}
@deffn {Δεδομένα} curses.KEY_FIND
@end deffn

@tab

Find

@item

@geindex KEY_HELP (στη μονάδα curses)
@anchor{library/curses curses KEY_HELP}@anchor{3786}
@deffn {Δεδομένα} curses.KEY_HELP
@end deffn

@tab

Help

@item

@geindex KEY_MARK (στη μονάδα curses)
@anchor{library/curses curses KEY_MARK}@anchor{3787}
@deffn {Δεδομένα} curses.KEY_MARK
@end deffn

@tab

Mark

@item

@geindex KEY_MESSAGE (στη μονάδα curses)
@anchor{library/curses curses KEY_MESSAGE}@anchor{3788}
@deffn {Δεδομένα} curses.KEY_MESSAGE
@end deffn

@tab

Message

@item

@geindex KEY_MOVE (στη μονάδα curses)
@anchor{library/curses curses KEY_MOVE}@anchor{3789}
@deffn {Δεδομένα} curses.KEY_MOVE
@end deffn

@tab

Move

@item

@geindex KEY_NEXT (στη μονάδα curses)
@anchor{library/curses curses KEY_NEXT}@anchor{378a}
@deffn {Δεδομένα} curses.KEY_NEXT
@end deffn

@tab

Next

@item

@geindex KEY_OPEN (στη μονάδα curses)
@anchor{library/curses curses KEY_OPEN}@anchor{378b}
@deffn {Δεδομένα} curses.KEY_OPEN
@end deffn

@tab

Open

@item

@geindex KEY_OPTIONS (στη μονάδα curses)
@anchor{library/curses curses KEY_OPTIONS}@anchor{378c}
@deffn {Δεδομένα} curses.KEY_OPTIONS
@end deffn

@tab

Options

@item

@geindex KEY_PREVIOUS (στη μονάδα curses)
@anchor{library/curses curses KEY_PREVIOUS}@anchor{378d}
@deffn {Δεδομένα} curses.KEY_PREVIOUS
@end deffn

@tab

Prev (previous)

@item

@geindex KEY_REDO (στη μονάδα curses)
@anchor{library/curses curses KEY_REDO}@anchor{378e}
@deffn {Δεδομένα} curses.KEY_REDO
@end deffn

@tab

Redo

@item

@geindex KEY_REFERENCE (στη μονάδα curses)
@anchor{library/curses curses KEY_REFERENCE}@anchor{378f}
@deffn {Δεδομένα} curses.KEY_REFERENCE
@end deffn

@tab

Ref (reference)

@item

@geindex KEY_REFRESH (στη μονάδα curses)
@anchor{library/curses curses KEY_REFRESH}@anchor{3790}
@deffn {Δεδομένα} curses.KEY_REFRESH
@end deffn

@tab

Refresh

@item

@geindex KEY_REPLACE (στη μονάδα curses)
@anchor{library/curses curses KEY_REPLACE}@anchor{3791}
@deffn {Δεδομένα} curses.KEY_REPLACE
@end deffn

@tab

Replace

@item

@geindex KEY_RESTART (στη μονάδα curses)
@anchor{library/curses curses KEY_RESTART}@anchor{3792}
@deffn {Δεδομένα} curses.KEY_RESTART
@end deffn

@tab

Restart

@item

@geindex KEY_RESUME (στη μονάδα curses)
@anchor{library/curses curses KEY_RESUME}@anchor{3793}
@deffn {Δεδομένα} curses.KEY_RESUME
@end deffn

@tab

Resume

@item

@geindex KEY_SAVE (στη μονάδα curses)
@anchor{library/curses curses KEY_SAVE}@anchor{3794}
@deffn {Δεδομένα} curses.KEY_SAVE
@end deffn

@tab

Save

@item

@geindex KEY_SBEG (στη μονάδα curses)
@anchor{library/curses curses KEY_SBEG}@anchor{3795}
@deffn {Δεδομένα} curses.KEY_SBEG
@end deffn

@tab

Shifted Beg (beginning)

@item

@geindex KEY_SCANCEL (στη μονάδα curses)
@anchor{library/curses curses KEY_SCANCEL}@anchor{3796}
@deffn {Δεδομένα} curses.KEY_SCANCEL
@end deffn

@tab

Shifted Cancel

@item

@geindex KEY_SCOMMAND (στη μονάδα curses)
@anchor{library/curses curses KEY_SCOMMAND}@anchor{3797}
@deffn {Δεδομένα} curses.KEY_SCOMMAND
@end deffn

@tab

Shifted Command

@item

@geindex KEY_SCOPY (στη μονάδα curses)
@anchor{library/curses curses KEY_SCOPY}@anchor{3798}
@deffn {Δεδομένα} curses.KEY_SCOPY
@end deffn

@tab

Shifted Copy

@item

@geindex KEY_SCREATE (στη μονάδα curses)
@anchor{library/curses curses KEY_SCREATE}@anchor{3799}
@deffn {Δεδομένα} curses.KEY_SCREATE
@end deffn

@tab

Shifted Create

@item

@geindex KEY_SDC (στη μονάδα curses)
@anchor{library/curses curses KEY_SDC}@anchor{379a}
@deffn {Δεδομένα} curses.KEY_SDC
@end deffn

@tab

Shifted Delete char

@item

@geindex KEY_SDL (στη μονάδα curses)
@anchor{library/curses curses KEY_SDL}@anchor{379b}
@deffn {Δεδομένα} curses.KEY_SDL
@end deffn

@tab

Shifted Delete line

@item

@geindex KEY_SELECT (στη μονάδα curses)
@anchor{library/curses curses KEY_SELECT}@anchor{379c}
@deffn {Δεδομένα} curses.KEY_SELECT
@end deffn

@tab

Select

@item

@geindex KEY_SEND (στη μονάδα curses)
@anchor{library/curses curses KEY_SEND}@anchor{379d}
@deffn {Δεδομένα} curses.KEY_SEND
@end deffn

@tab

Shifted End

@item

@geindex KEY_SEOL (στη μονάδα curses)
@anchor{library/curses curses KEY_SEOL}@anchor{379e}
@deffn {Δεδομένα} curses.KEY_SEOL
@end deffn

@tab

Shifted Clear line

@item

@geindex KEY_SEXIT (στη μονάδα curses)
@anchor{library/curses curses KEY_SEXIT}@anchor{379f}
@deffn {Δεδομένα} curses.KEY_SEXIT
@end deffn

@tab

Shifted Exit

@item

@geindex KEY_SFIND (στη μονάδα curses)
@anchor{library/curses curses KEY_SFIND}@anchor{37a0}
@deffn {Δεδομένα} curses.KEY_SFIND
@end deffn

@tab

Shifted Find

@item

@geindex KEY_SHELP (στη μονάδα curses)
@anchor{library/curses curses KEY_SHELP}@anchor{37a1}
@deffn {Δεδομένα} curses.KEY_SHELP
@end deffn

@tab

Shifted Help

@item

@geindex KEY_SHOME (στη μονάδα curses)
@anchor{library/curses curses KEY_SHOME}@anchor{37a2}
@deffn {Δεδομένα} curses.KEY_SHOME
@end deffn

@tab

Shifted Home

@item

@geindex KEY_SIC (στη μονάδα curses)
@anchor{library/curses curses KEY_SIC}@anchor{37a3}
@deffn {Δεδομένα} curses.KEY_SIC
@end deffn

@tab

Shifted Input

@item

@geindex KEY_SLEFT (στη μονάδα curses)
@anchor{library/curses curses KEY_SLEFT}@anchor{37a4}
@deffn {Δεδομένα} curses.KEY_SLEFT
@end deffn

@tab

Shifted Left arrow

@item

@geindex KEY_SMESSAGE (στη μονάδα curses)
@anchor{library/curses curses KEY_SMESSAGE}@anchor{37a5}
@deffn {Δεδομένα} curses.KEY_SMESSAGE
@end deffn

@tab

Shifted Message

@item

@geindex KEY_SMOVE (στη μονάδα curses)
@anchor{library/curses curses KEY_SMOVE}@anchor{37a6}
@deffn {Δεδομένα} curses.KEY_SMOVE
@end deffn

@tab

Shifted Move

@item

@geindex KEY_SNEXT (στη μονάδα curses)
@anchor{library/curses curses KEY_SNEXT}@anchor{37a7}
@deffn {Δεδομένα} curses.KEY_SNEXT
@end deffn

@tab

Shifted Next

@item

@geindex KEY_SOPTIONS (στη μονάδα curses)
@anchor{library/curses curses KEY_SOPTIONS}@anchor{37a8}
@deffn {Δεδομένα} curses.KEY_SOPTIONS
@end deffn

@tab

Shifted Options

@item

@geindex KEY_SPREVIOUS (στη μονάδα curses)
@anchor{library/curses curses KEY_SPREVIOUS}@anchor{37a9}
@deffn {Δεδομένα} curses.KEY_SPREVIOUS
@end deffn

@tab

Shifted Prev

@item

@geindex KEY_SPRINT (στη μονάδα curses)
@anchor{library/curses curses KEY_SPRINT}@anchor{37aa}
@deffn {Δεδομένα} curses.KEY_SPRINT
@end deffn

@tab

Shifted Print

@item

@geindex KEY_SREDO (στη μονάδα curses)
@anchor{library/curses curses KEY_SREDO}@anchor{37ab}
@deffn {Δεδομένα} curses.KEY_SREDO
@end deffn

@tab

Shifted Redo

@item

@geindex KEY_SREPLACE (στη μονάδα curses)
@anchor{library/curses curses KEY_SREPLACE}@anchor{37ac}
@deffn {Δεδομένα} curses.KEY_SREPLACE
@end deffn

@tab

Shifted Replace

@item

@geindex KEY_SRIGHT (στη μονάδα curses)
@anchor{library/curses curses KEY_SRIGHT}@anchor{37ad}
@deffn {Δεδομένα} curses.KEY_SRIGHT
@end deffn

@tab

Shifted Right arrow

@item

@geindex KEY_SRSUME (στη μονάδα curses)
@anchor{library/curses curses KEY_SRSUME}@anchor{37ae}
@deffn {Δεδομένα} curses.KEY_SRSUME
@end deffn

@tab

Shifted Resume

@item

@geindex KEY_SSAVE (στη μονάδα curses)
@anchor{library/curses curses KEY_SSAVE}@anchor{37af}
@deffn {Δεδομένα} curses.KEY_SSAVE
@end deffn

@tab

Shifted Save

@item

@geindex KEY_SSUSPEND (στη μονάδα curses)
@anchor{library/curses curses KEY_SSUSPEND}@anchor{37b0}
@deffn {Δεδομένα} curses.KEY_SSUSPEND
@end deffn

@tab

Shifted Suspend

@item

@geindex KEY_SUNDO (στη μονάδα curses)
@anchor{library/curses curses KEY_SUNDO}@anchor{37b1}
@deffn {Δεδομένα} curses.KEY_SUNDO
@end deffn

@tab

Shifted Undo

@item

@geindex KEY_SUSPEND (στη μονάδα curses)
@anchor{library/curses curses KEY_SUSPEND}@anchor{37b2}
@deffn {Δεδομένα} curses.KEY_SUSPEND
@end deffn

@tab

Suspend

@item

@geindex KEY_UNDO (στη μονάδα curses)
@anchor{library/curses curses KEY_UNDO}@anchor{37b3}
@deffn {Δεδομένα} curses.KEY_UNDO
@end deffn

@tab

Undo

@item

@geindex KEY_MOUSE (στη μονάδα curses)
@anchor{library/curses curses KEY_MOUSE}@anchor{36d6}
@deffn {Δεδομένα} curses.KEY_MOUSE
@end deffn

@tab

Mouse event has occurred

@item

@geindex KEY_RESIZE (στη μονάδα curses)
@anchor{library/curses curses KEY_RESIZE}@anchor{37b4}
@deffn {Δεδομένα} curses.KEY_RESIZE
@end deffn

@tab

Terminal resize event

@item

@geindex KEY_MAX (στη μονάδα curses)
@anchor{library/curses curses KEY_MAX}@anchor{37b5}
@deffn {Δεδομένα} 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{3762,,KEY_F1}, @code{KEY_F2},
@code{KEY_F3}, @code{KEY_F4}) available, and the arrow keys mapped to
@ref{375c,,KEY_UP}, @ref{375b,,KEY_DOWN}, @ref{375d,,KEY_LEFT} and @ref{375e,,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

Constant

@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{37b6}
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 Σημείωση 
These are available only after @ref{1a1b,,initscr()} has  been called.
@end quotation
@end cartouche


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ACS code

@tab

Meaning

@item

@geindex ACS_BBSS (στη μονάδα curses)
@anchor{library/curses curses ACS_BBSS}@anchor{37b7}
@deffn {Δεδομένα} curses.ACS_BBSS
@end deffn

@tab

alternate name for upper right corner

@item

@geindex ACS_BLOCK (στη μονάδα curses)
@anchor{library/curses curses ACS_BLOCK}@anchor{37b8}
@deffn {Δεδομένα} curses.ACS_BLOCK
@end deffn

@tab

solid square block

@item

@geindex ACS_BOARD (στη μονάδα curses)
@anchor{library/curses curses ACS_BOARD}@anchor{37b9}
@deffn {Δεδομένα} curses.ACS_BOARD
@end deffn

@tab

board of squares

@item

@geindex ACS_BSBS (στη μονάδα curses)
@anchor{library/curses curses ACS_BSBS}@anchor{37ba}
@deffn {Δεδομένα} curses.ACS_BSBS
@end deffn

@tab

alternate name for horizontal line

@item

@geindex ACS_BSSB (στη μονάδα curses)
@anchor{library/curses curses ACS_BSSB}@anchor{37bb}
@deffn {Δεδομένα} curses.ACS_BSSB
@end deffn

@tab

alternate name for upper left corner

@item

@geindex ACS_BSSS (στη μονάδα curses)
@anchor{library/curses curses ACS_BSSS}@anchor{37bc}
@deffn {Δεδομένα} curses.ACS_BSSS
@end deffn

@tab

alternate name for top tee

@item

@geindex ACS_BTEE (στη μονάδα curses)
@anchor{library/curses curses ACS_BTEE}@anchor{37bd}
@deffn {Δεδομένα} curses.ACS_BTEE
@end deffn

@tab

bottom tee

@item

@geindex ACS_BULLET (στη μονάδα curses)
@anchor{library/curses curses ACS_BULLET}@anchor{37be}
@deffn {Δεδομένα} curses.ACS_BULLET
@end deffn

@tab

bullet

@item

@geindex ACS_CKBOARD (στη μονάδα curses)
@anchor{library/curses curses ACS_CKBOARD}@anchor{37bf}
@deffn {Δεδομένα} curses.ACS_CKBOARD
@end deffn

@tab

checker board (stipple)

@item

@geindex ACS_DARROW (στη μονάδα curses)
@anchor{library/curses curses ACS_DARROW}@anchor{37c0}
@deffn {Δεδομένα} curses.ACS_DARROW
@end deffn

@tab

arrow pointing down

@item

@geindex ACS_DEGREE (στη μονάδα curses)
@anchor{library/curses curses ACS_DEGREE}@anchor{37c1}
@deffn {Δεδομένα} curses.ACS_DEGREE
@end deffn

@tab

degree symbol

@item

@geindex ACS_DIAMOND (στη μονάδα curses)
@anchor{library/curses curses ACS_DIAMOND}@anchor{37c2}
@deffn {Δεδομένα} curses.ACS_DIAMOND
@end deffn

@tab

diamond

@item

@geindex ACS_GEQUAL (στη μονάδα curses)
@anchor{library/curses curses ACS_GEQUAL}@anchor{37c3}
@deffn {Δεδομένα} curses.ACS_GEQUAL
@end deffn

@tab

greater-than-or-equal-to

@item

@geindex ACS_HLINE (στη μονάδα curses)
@anchor{library/curses curses ACS_HLINE}@anchor{370e}
@deffn {Δεδομένα} curses.ACS_HLINE
@end deffn

@tab

horizontal line

@item

@geindex ACS_LANTERN (στη μονάδα curses)
@anchor{library/curses curses ACS_LANTERN}@anchor{37c4}
@deffn {Δεδομένα} curses.ACS_LANTERN
@end deffn

@tab

lantern symbol

@item

@geindex ACS_LARROW (στη μονάδα curses)
@anchor{library/curses curses ACS_LARROW}@anchor{37c5}
@deffn {Δεδομένα} curses.ACS_LARROW
@end deffn

@tab

left arrow

@item

@geindex ACS_LEQUAL (στη μονάδα curses)
@anchor{library/curses curses ACS_LEQUAL}@anchor{37c6}
@deffn {Δεδομένα} curses.ACS_LEQUAL
@end deffn

@tab

less-than-or-equal-to

@item

@geindex ACS_LLCORNER (στη μονάδα curses)
@anchor{library/curses curses ACS_LLCORNER}@anchor{3711}
@deffn {Δεδομένα} curses.ACS_LLCORNER
@end deffn

@tab

lower left-hand corner

@item

@geindex ACS_LRCORNER (στη μονάδα curses)
@anchor{library/curses curses ACS_LRCORNER}@anchor{3712}
@deffn {Δεδομένα} curses.ACS_LRCORNER
@end deffn

@tab

lower right-hand corner

@item

@geindex ACS_LTEE (στη μονάδα curses)
@anchor{library/curses curses ACS_LTEE}@anchor{37c7}
@deffn {Δεδομένα} curses.ACS_LTEE
@end deffn

@tab

left tee

@item

@geindex ACS_NEQUAL (στη μονάδα curses)
@anchor{library/curses curses ACS_NEQUAL}@anchor{37c8}
@deffn {Δεδομένα} curses.ACS_NEQUAL
@end deffn

@tab

not-equal sign

@item

@geindex ACS_PI (στη μονάδα curses)
@anchor{library/curses curses ACS_PI}@anchor{37c9}
@deffn {Δεδομένα} curses.ACS_PI
@end deffn

@tab

letter pi

@item

@geindex ACS_PLMINUS (στη μονάδα curses)
@anchor{library/curses curses ACS_PLMINUS}@anchor{37ca}
@deffn {Δεδομένα} curses.ACS_PLMINUS
@end deffn

@tab

plus-or-minus sign

@item

@geindex ACS_PLUS (στη μονάδα curses)
@anchor{library/curses curses ACS_PLUS}@anchor{37cb}
@deffn {Δεδομένα} curses.ACS_PLUS
@end deffn

@tab

big plus sign

@item

@geindex ACS_RARROW (στη μονάδα curses)
@anchor{library/curses curses ACS_RARROW}@anchor{37cc}
@deffn {Δεδομένα} curses.ACS_RARROW
@end deffn

@tab

right arrow

@item

@geindex ACS_RTEE (στη μονάδα curses)
@anchor{library/curses curses ACS_RTEE}@anchor{37cd}
@deffn {Δεδομένα} curses.ACS_RTEE
@end deffn

@tab

right tee

@item

@geindex ACS_S1 (στη μονάδα curses)
@anchor{library/curses curses ACS_S1}@anchor{37ce}
@deffn {Δεδομένα} curses.ACS_S1
@end deffn

@tab

scan line 1

@item

@geindex ACS_S3 (στη μονάδα curses)
@anchor{library/curses curses ACS_S3}@anchor{37cf}
@deffn {Δεδομένα} curses.ACS_S3
@end deffn

@tab

scan line 3

@item

@geindex ACS_S7 (στη μονάδα curses)
@anchor{library/curses curses ACS_S7}@anchor{37d0}
@deffn {Δεδομένα} curses.ACS_S7
@end deffn

@tab

scan line 7

@item

@geindex ACS_S9 (στη μονάδα curses)
@anchor{library/curses curses ACS_S9}@anchor{37d1}
@deffn {Δεδομένα} curses.ACS_S9
@end deffn

@tab

scan line 9

@item

@geindex ACS_SBBS (στη μονάδα curses)
@anchor{library/curses curses ACS_SBBS}@anchor{37d2}
@deffn {Δεδομένα} curses.ACS_SBBS
@end deffn

@tab

alternate name for lower right corner

@item

@geindex ACS_SBSB (στη μονάδα curses)
@anchor{library/curses curses ACS_SBSB}@anchor{37d3}
@deffn {Δεδομένα} curses.ACS_SBSB
@end deffn

@tab

alternate name for vertical line

@item

@geindex ACS_SBSS (στη μονάδα curses)
@anchor{library/curses curses ACS_SBSS}@anchor{37d4}
@deffn {Δεδομένα} curses.ACS_SBSS
@end deffn

@tab

alternate name for right tee

@item

@geindex ACS_SSBB (στη μονάδα curses)
@anchor{library/curses curses ACS_SSBB}@anchor{37d5}
@deffn {Δεδομένα} curses.ACS_SSBB
@end deffn

@tab

alternate name for lower left corner

@item

@geindex ACS_SSBS (στη μονάδα curses)
@anchor{library/curses curses ACS_SSBS}@anchor{37d6}
@deffn {Δεδομένα} curses.ACS_SSBS
@end deffn

@tab

alternate name for bottom tee

@item

@geindex ACS_SSSB (στη μονάδα curses)
@anchor{library/curses curses ACS_SSSB}@anchor{37d7}
@deffn {Δεδομένα} curses.ACS_SSSB
@end deffn

@tab

alternate name for left tee

@item

@geindex ACS_SSSS (στη μονάδα curses)
@anchor{library/curses curses ACS_SSSS}@anchor{37d8}
@deffn {Δεδομένα} curses.ACS_SSSS
@end deffn

@tab

alternate name for crossover or big plus

@item

@geindex ACS_STERLING (στη μονάδα curses)
@anchor{library/curses curses ACS_STERLING}@anchor{37d9}
@deffn {Δεδομένα} curses.ACS_STERLING
@end deffn

@tab

pound sterling

@item

@geindex ACS_TTEE (στη μονάδα curses)
@anchor{library/curses curses ACS_TTEE}@anchor{37da}
@deffn {Δεδομένα} curses.ACS_TTEE
@end deffn

@tab

top tee

@item

@geindex ACS_UARROW (στη μονάδα curses)
@anchor{library/curses curses ACS_UARROW}@anchor{37db}
@deffn {Δεδομένα} curses.ACS_UARROW
@end deffn

@tab

up arrow

@item

@geindex ACS_ULCORNER (στη μονάδα curses)
@anchor{library/curses curses ACS_ULCORNER}@anchor{370f}
@deffn {Δεδομένα} curses.ACS_ULCORNER
@end deffn

@tab

upper left corner

@item

@geindex ACS_URCORNER (στη μονάδα curses)
@anchor{library/curses curses ACS_URCORNER}@anchor{3710}
@deffn {Δεδομένα} curses.ACS_URCORNER
@end deffn

@tab

upper right corner

@item

@geindex ACS_VLINE (στη μονάδα curses)
@anchor{library/curses curses ACS_VLINE}@anchor{370d}
@deffn {Δεδομένα} curses.ACS_VLINE
@end deffn

@tab

vertical line

@end multitable


The following table lists mouse button constants used by @ref{36d5,,getmouse()}:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Mouse button constant

@tab

Meaning

@item

@geindex BUTTONn_PRESSED (στη μονάδα curses)
@anchor{library/curses curses BUTTONn_PRESSED}@anchor{36d7}
@deffn {Δεδομένα} curses.BUTTONn_PRESSED
@end deffn

@tab

Mouse button `n' pressed

@item

@geindex BUTTONn_RELEASED (στη μονάδα curses)
@anchor{library/curses curses BUTTONn_RELEASED}@anchor{36d8}
@deffn {Δεδομένα} curses.BUTTONn_RELEASED
@end deffn

@tab

Mouse button `n' released

@item

@geindex BUTTONn_CLICKED (στη μονάδα curses)
@anchor{library/curses curses BUTTONn_CLICKED}@anchor{36d9}
@deffn {Δεδομένα} curses.BUTTONn_CLICKED
@end deffn

@tab

Mouse button `n' clicked

@item

@geindex BUTTONn_DOUBLE_CLICKED (στη μονάδα curses)
@anchor{library/curses curses BUTTONn_DOUBLE_CLICKED}@anchor{36da}
@deffn {Δεδομένα} curses.BUTTONn_DOUBLE_CLICKED
@end deffn

@tab

Mouse button `n' double clicked

@item

@geindex BUTTONn_TRIPLE_CLICKED (στη μονάδα curses)
@anchor{library/curses curses BUTTONn_TRIPLE_CLICKED}@anchor{36db}
@deffn {Δεδομένα} curses.BUTTONn_TRIPLE_CLICKED
@end deffn

@tab

Mouse button `n' triple clicked

@item

@geindex BUTTON_SHIFT (στη μονάδα curses)
@anchor{library/curses curses BUTTON_SHIFT}@anchor{36dc}
@deffn {Δεδομένα} curses.BUTTON_SHIFT
@end deffn

@tab

Shift was down during button state change

@item

@geindex BUTTON_CTRL (στη μονάδα curses)
@anchor{library/curses curses BUTTON_CTRL}@anchor{36dd}
@deffn {Δεδομένα} curses.BUTTON_CTRL
@end deffn

@tab

Control was down during button state change

@item

@geindex BUTTON_ALT (στη μονάδα curses)
@anchor{library/curses curses BUTTON_ALT}@anchor{36de}
@deffn {Δεδομένα} curses.BUTTON_ALT
@end deffn

@tab

Control was down during button state change

@end multitable



Άλλαξε στην έκδοση 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

Constant

@tab

Color

@item

@geindex COLOR_BLACK (στη μονάδα curses)
@anchor{library/curses curses COLOR_BLACK}@anchor{37dc}
@deffn {Δεδομένα} curses.COLOR_BLACK
@end deffn

@tab

Black

@item

@geindex COLOR_BLUE (στη μονάδα curses)
@anchor{library/curses curses COLOR_BLUE}@anchor{37dd}
@deffn {Δεδομένα} curses.COLOR_BLUE
@end deffn

@tab

Blue

@item

@geindex COLOR_CYAN (στη μονάδα curses)
@anchor{library/curses curses COLOR_CYAN}@anchor{37de}
@deffn {Δεδομένα} curses.COLOR_CYAN
@end deffn

@tab

Cyan (light greenish blue)

@item

@geindex COLOR_GREEN (στη μονάδα curses)
@anchor{library/curses curses COLOR_GREEN}@anchor{37df}
@deffn {Δεδομένα} curses.COLOR_GREEN
@end deffn

@tab

Green

@item

@geindex COLOR_MAGENTA (στη μονάδα curses)
@anchor{library/curses curses COLOR_MAGENTA}@anchor{37e0}
@deffn {Δεδομένα} curses.COLOR_MAGENTA
@end deffn

@tab

Magenta (purplish red)

@item

@geindex COLOR_RED (στη μονάδα curses)
@anchor{library/curses curses COLOR_RED}@anchor{37e1}
@deffn {Δεδομένα} curses.COLOR_RED
@end deffn

@tab

Red

@item

@geindex COLOR_WHITE (στη μονάδα curses)
@anchor{library/curses curses COLOR_WHITE}@anchor{37e2}
@deffn {Δεδομένα} curses.COLOR_WHITE
@end deffn

@tab

White

@item

@geindex COLOR_YELLOW (στη μονάδα curses)
@anchor{library/curses curses COLOR_YELLOW}@anchor{37e3}
@deffn {Δεδομένα} 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{37e4}@anchor{library/curses module-curses textpad}@anchor{31}
@subsection @code{curses.textpad} — Text input widget for curses programs


@geindex module; curses.textpad

The @code{curses.textpad} module provides a @ref{37e5,,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 @code{curses.textpad} defines the following function:

@geindex rectangle() (στη μονάδα curses.textpad)
@anchor{library/curses curses textpad rectangle}@anchor{37e6}
@deffn {Συνάρτηση} 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{37e7}@anchor{library/curses textbox-objects}@anchor{37e8}
@subsubsection Textbox objects


You can instantiate a @ref{37e5,,Textbox} object as follows:

@geindex Textbox (κλάση σε curses.textpad)
@anchor{library/curses curses textpad Textbox}@anchor{37e5}
@deffn {Κλάση} curses.textpad.Textbox (win)

Return a textbox widget object.  The `win' argument should be a curses
@ref{1a24,,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{37e9,,stripspaces} flag is initially on.

@code{Textbox} objects have the following methods:

@geindex edit() (μέθοδος της curses.textpad.Textbox)
@anchor{library/curses curses textpad Textbox edit}@anchor{37ea}
@deffn {Μέθοδος} 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{37e9,,stripspaces} attribute.
@end deffn

@geindex do_command() (μέθοδος της curses.textpad.Textbox)
@anchor{library/curses curses textpad Textbox do_command}@anchor{37eb}
@deffn {Μέθοδος} do_command (ch)

Process a single command keystroke.  Here are the supported special
keystrokes:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Keystroke

@tab

Action

@item

@code{Control}-@code{A}

@tab

Go to left edge of window.

@item

@code{Control}-@code{B}

@tab

Cursor left, wrapping to previous line if
appropriate.

@item

@code{Control}-@code{D}

@tab

Delete character under cursor.

@item

@code{Control}-@code{E}

@tab

Go to right edge (stripspaces off) or end
of line (stripspaces on).

@item

@code{Control}-@code{F}

@tab

Cursor right, wrapping to next line when
appropriate.

@item

@code{Control}-@code{G}

@tab

Terminate, returning the window contents.

@item

@code{Control}-@code{H}

@tab

Delete character backward.

@item

@code{Control}-@code{J}

@tab

Terminate if the window is 1 line,
otherwise insert newline.

@item

@code{Control}-@code{K}

@tab

If line is blank, delete it, otherwise
clear to end of line.

@item

@code{Control}-@code{L}

@tab

Refresh screen.

@item

@code{Control}-@code{N}

@tab

Cursor down; move down one line.

@item

@code{Control}-@code{O}

@tab

Insert a blank line at cursor location.

@item

@code{Control}-@code{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

Constant

@tab

Keystroke

@item

@ref{375d,,KEY_LEFT}

@tab

@code{Control}-@code{B}

@item

@ref{375e,,KEY_RIGHT}

@tab

@code{Control}-@code{F}

@item

@ref{375c,,KEY_UP}

@tab

@code{Control}-@code{P}

@item

@ref{375b,,KEY_DOWN}

@tab

@code{Control}-@code{N}

@item

@ref{3760,,KEY_BACKSPACE}

@tab

@code{Control}-@code{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() (μέθοδος της curses.textpad.Textbox)
@anchor{library/curses curses textpad Textbox gather}@anchor{37ec}
@deffn {Μέθοδος} gather ()

Return the window contents as a string; whether blanks in the
window are included is affected by the @ref{37e9,,stripspaces} member.
@end deffn

@geindex stripspaces (ιδιότητα της curses.textpad.Textbox)
@anchor{library/curses curses textpad Textbox stripspaces}@anchor{37e9}
@deffn {Ιδιότητα} 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{37ed}@anchor{library/curses ascii curses-ascii-utilities-for-ascii-characters}@anchor{37ee}@anchor{library/curses ascii module-curses ascii}@anchor{2f}@anchor{library/curses ascii translation-repo}@anchor{37ef}
@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/main/Lib/curses/ascii.py}


__________________________________________________________________


The @code{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

Name

@tab

Meaning

@item

@geindex NUL (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii NUL}@anchor{37f0}
@deffn {Δεδομένα} curses.ascii.NUL
@end deffn

@tab

@item

@geindex SOH (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii SOH}@anchor{37f1}
@deffn {Δεδομένα} curses.ascii.SOH
@end deffn

@tab

Start of heading, console interrupt

@item

@geindex STX (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii STX}@anchor{37f2}
@deffn {Δεδομένα} curses.ascii.STX
@end deffn

@tab

Start of text

@item

@geindex ETX (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii ETX}@anchor{37f3}
@deffn {Δεδομένα} curses.ascii.ETX
@end deffn

@tab

End of text

@item

@geindex EOT (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii EOT}@anchor{37f4}
@deffn {Δεδομένα} curses.ascii.EOT
@end deffn

@tab

End of transmission

@item

@geindex ENQ (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii ENQ}@anchor{37f5}
@deffn {Δεδομένα} curses.ascii.ENQ
@end deffn

@tab

Enquiry, goes with @ref{37f6,,ACK} flow control

@item

@geindex ACK (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii ACK}@anchor{37f6}
@deffn {Δεδομένα} curses.ascii.ACK
@end deffn

@tab

Acknowledgement

@item

@geindex BEL (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii BEL}@anchor{37f7}
@deffn {Δεδομένα} curses.ascii.BEL
@end deffn

@tab

Bell

@item

@geindex BS (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii BS}@anchor{37f8}
@deffn {Δεδομένα} curses.ascii.BS
@end deffn

@tab

Backspace

@item

@geindex TAB (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii TAB}@anchor{37f9}
@deffn {Δεδομένα} curses.ascii.TAB
@end deffn

@tab

Tab

@item

@geindex HT (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii HT}@anchor{37fa}
@deffn {Δεδομένα} curses.ascii.HT
@end deffn

@tab

Alias for @ref{37f9,,TAB}: «Horizontal tab»

@item

@geindex LF (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii LF}@anchor{37fb}
@deffn {Δεδομένα} curses.ascii.LF
@end deffn

@tab

Line feed

@item

@geindex NL (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii NL}@anchor{37fc}
@deffn {Δεδομένα} curses.ascii.NL
@end deffn

@tab

Alias for @ref{37fb,,LF}: «New line»

@item

@geindex VT (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii VT}@anchor{37fd}
@deffn {Δεδομένα} curses.ascii.VT
@end deffn

@tab

Vertical tab

@item

@geindex FF (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii FF}@anchor{37fe}
@deffn {Δεδομένα} curses.ascii.FF
@end deffn

@tab

Form feed

@item

@geindex CR (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii CR}@anchor{37ff}
@deffn {Δεδομένα} curses.ascii.CR
@end deffn

@tab

Carriage return

@item

@geindex SO (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii SO}@anchor{3800}
@deffn {Δεδομένα} curses.ascii.SO
@end deffn

@tab

Shift-out, begin alternate character set

@item

@geindex SI (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii SI}@anchor{3801}
@deffn {Δεδομένα} curses.ascii.SI
@end deffn

@tab

Shift-in, resume default character set

@item

@geindex DLE (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii DLE}@anchor{3802}
@deffn {Δεδομένα} curses.ascii.DLE
@end deffn

@tab

Data-link escape

@item

@geindex DC1 (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii DC1}@anchor{3803}
@deffn {Δεδομένα} curses.ascii.DC1
@end deffn

@tab

XON, for flow control

@item

@geindex DC2 (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii DC2}@anchor{3804}
@deffn {Δεδομένα} curses.ascii.DC2
@end deffn

@tab

Device control 2, block-mode flow control

@item

@geindex DC3 (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii DC3}@anchor{3805}
@deffn {Δεδομένα} curses.ascii.DC3
@end deffn

@tab

XOFF, for flow control

@item

@geindex DC4 (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii DC4}@anchor{3806}
@deffn {Δεδομένα} curses.ascii.DC4
@end deffn

@tab

Device control 4

@item

@geindex NAK (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii NAK}@anchor{3807}
@deffn {Δεδομένα} curses.ascii.NAK
@end deffn

@tab

Negative acknowledgement

@item

@geindex SYN (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii SYN}@anchor{3808}
@deffn {Δεδομένα} curses.ascii.SYN
@end deffn

@tab

Synchronous idle

@item

@geindex ETB (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii ETB}@anchor{3809}
@deffn {Δεδομένα} curses.ascii.ETB
@end deffn

@tab

End transmission block

@item

@geindex CAN (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii CAN}@anchor{380a}
@deffn {Δεδομένα} curses.ascii.CAN
@end deffn

@tab

Cancel

@item

@geindex EM (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii EM}@anchor{380b}
@deffn {Δεδομένα} curses.ascii.EM
@end deffn

@tab

End of medium

@item

@geindex SUB (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii SUB}@anchor{380c}
@deffn {Δεδομένα} curses.ascii.SUB
@end deffn

@tab

Substitute

@item

@geindex ESC (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii ESC}@anchor{380d}
@deffn {Δεδομένα} curses.ascii.ESC
@end deffn

@tab

Escape

@item

@geindex FS (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii FS}@anchor{380e}
@deffn {Δεδομένα} curses.ascii.FS
@end deffn

@tab

File separator

@item

@geindex GS (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii GS}@anchor{380f}
@deffn {Δεδομένα} curses.ascii.GS
@end deffn

@tab

Group separator

@item

@geindex RS (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii RS}@anchor{3810}
@deffn {Δεδομένα} curses.ascii.RS
@end deffn

@tab

Record separator, block-mode terminator

@item

@geindex US (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii US}@anchor{3811}
@deffn {Δεδομένα} curses.ascii.US
@end deffn

@tab

Unit separator

@item

@geindex SP (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii SP}@anchor{3812}
@deffn {Δεδομένα} curses.ascii.SP
@end deffn

@tab

Space

@item

@geindex DEL (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii DEL}@anchor{3813}
@deffn {Δεδομένα} 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() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii isalnum}@anchor{3814}
@deffn {Συνάρτηση} curses.ascii.isalnum (c)

Checks for an ASCII alphanumeric character; it is equivalent to @code{isalpha(c) or
isdigit(c)}.
@end deffn

@geindex isalpha() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii isalpha}@anchor{3815}
@deffn {Συνάρτηση} curses.ascii.isalpha (c)

Checks for an ASCII alphabetic character; it is equivalent to @code{isupper(c) or
islower(c)}.
@end deffn

@geindex isascii() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii isascii}@anchor{3816}
@deffn {Συνάρτηση} curses.ascii.isascii (c)

Checks for a character value that fits in the 7-bit ASCII set.
@end deffn

@geindex isblank() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii isblank}@anchor{3817}
@deffn {Συνάρτηση} curses.ascii.isblank (c)

Checks for an ASCII whitespace character; space or horizontal tab.
@end deffn

@geindex iscntrl() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii iscntrl}@anchor{3818}
@deffn {Συνάρτηση} curses.ascii.iscntrl (c)

Checks for an ASCII control character (in the range 0x00 to 0x1f or 0x7f).
@end deffn

@geindex isdigit() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii isdigit}@anchor{3819}
@deffn {Συνάρτηση} 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() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii isgraph}@anchor{381a}
@deffn {Συνάρτηση} curses.ascii.isgraph (c)

Checks for ASCII any printable character except space.
@end deffn

@geindex islower() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii islower}@anchor{381b}
@deffn {Συνάρτηση} curses.ascii.islower (c)

Checks for an ASCII lower-case character.
@end deffn

@geindex isprint() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii isprint}@anchor{381c}
@deffn {Συνάρτηση} curses.ascii.isprint (c)

Checks for any ASCII printable character including space.
@end deffn

@geindex ispunct() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii ispunct}@anchor{381d}
@deffn {Συνάρτηση} curses.ascii.ispunct (c)

Checks for any printable ASCII character which is not a space or an alphanumeric
character.
@end deffn

@geindex isspace() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii isspace}@anchor{381e}
@deffn {Συνάρτηση} 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() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii isupper}@anchor{381f}
@deffn {Συνάρτηση} curses.ascii.isupper (c)

Checks for an ASCII uppercase letter.
@end deffn

@geindex isxdigit() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii isxdigit}@anchor{3820}
@deffn {Συνάρτηση} curses.ascii.isxdigit (c)

Checks for an ASCII hexadecimal digit.  This is equivalent to @code{c in
string.hexdigits}.
@end deffn

@geindex isctrl() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii isctrl}@anchor{3821}
@deffn {Συνάρτηση} curses.ascii.isctrl (c)

Checks for an ASCII control character (ordinal values 0 to 31).
@end deffn

@geindex ismeta() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii ismeta}@anchor{3822}
@deffn {Συνάρτηση} 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{252c,,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() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii ascii}@anchor{3823}
@deffn {Συνάρτηση} curses.ascii.ascii (c)

Return the ASCII value corresponding to the low 7 bits of `c'.
@end deffn

@geindex ctrl() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii ctrl}@anchor{3824}
@deffn {Συνάρτηση} 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() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii alt}@anchor{3825}
@deffn {Συνάρτηση} 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() (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii unctrl}@anchor{3826}
@deffn {Συνάρτηση} 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 (στη μονάδα curses.ascii)
@anchor{library/curses ascii curses ascii controlnames}@anchor{3827}
@deffn {Δεδομένα} 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node curses panel — A panel stack extension for curses,cmd — Support for line-oriented command interpreters,curses ascii — Utilities for ASCII characters,Command-line interface libraries
@anchor{library/curses panel doc}@anchor{3828}@anchor{library/curses panel curses-panel-a-panel-stack-extension-for-curses}@anchor{3829}@anchor{library/curses panel module-curses panel}@anchor{30}@anchor{library/curses panel translation-repo}@anchor{382a}
@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
* Functions: Functions<5>. 
* Panel Objects:: 

@end menu

@node Functions<5>,Panel Objects,,curses panel — A panel stack extension for curses
@anchor{library/curses panel cursespanel-functions}@anchor{382b}@anchor{library/curses panel functions}@anchor{382c}
@subsubsection Functions


The module @code{curses.panel} defines the following functions:

@geindex bottom_panel() (στη μονάδα curses.panel)
@anchor{library/curses panel curses panel bottom_panel}@anchor{382d}
@deffn {Συνάρτηση} curses.panel.bottom_panel ()

Returns the bottom panel in the panel stack.
@end deffn

@geindex new_panel() (στη μονάδα curses.panel)
@anchor{library/curses panel curses panel new_panel}@anchor{19fb}
@deffn {Συνάρτηση} 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() (στη μονάδα curses.panel)
@anchor{library/curses panel curses panel top_panel}@anchor{382e}
@deffn {Συνάρτηση} curses.panel.top_panel ()

Returns the top panel in the panel stack.
@end deffn

@geindex update_panels() (στη μονάδα curses.panel)
@anchor{library/curses panel curses panel update_panels}@anchor{382f}
@deffn {Συνάρτηση} curses.panel.update_panels ()

Updates the virtual screen after changes in the panel stack. This does not call
@ref{36cf,,curses.doupdate()}, so you’ll have to do this yourself.
@end deffn

@node Panel Objects,,Functions<5>,curses panel — A panel stack extension for curses
@anchor{library/curses panel curses-panel-objects}@anchor{3830}@anchor{library/curses panel panel-objects}@anchor{3831}
@subsubsection Panel Objects


Panel objects, as returned by @ref{19fb,,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() (μέθοδος της curses.panel.Panel)
@anchor{library/curses panel curses panel Panel above}@anchor{3832}
@deffn {Μέθοδος} Panel.above ()

Returns the panel above the current panel.
@end deffn

@geindex below() (μέθοδος της curses.panel.Panel)
@anchor{library/curses panel curses panel Panel below}@anchor{3833}
@deffn {Μέθοδος} Panel.below ()

Returns the panel below the current panel.
@end deffn

@geindex bottom() (μέθοδος της curses.panel.Panel)
@anchor{library/curses panel curses panel Panel bottom}@anchor{3834}
@deffn {Μέθοδος} Panel.bottom ()

Push the panel to the bottom of the stack.
@end deffn

@geindex hidden() (μέθοδος της curses.panel.Panel)
@anchor{library/curses panel curses panel Panel hidden}@anchor{3835}
@deffn {Μέθοδος} Panel.hidden ()

Returns @code{True} if the panel is hidden (not visible), @code{False} otherwise.
@end deffn

@geindex hide() (μέθοδος της curses.panel.Panel)
@anchor{library/curses panel curses panel Panel hide}@anchor{3836}
@deffn {Μέθοδος} Panel.hide ()

Hide the panel. This does not delete the object, it just makes the window on
screen invisible.
@end deffn

@geindex move() (μέθοδος της curses.panel.Panel)
@anchor{library/curses panel curses panel Panel move}@anchor{3837}
@deffn {Μέθοδος} Panel.move (y, x)

Move the panel to the screen coordinates @code{(y, x)}.
@end deffn

@geindex replace() (μέθοδος της curses.panel.Panel)
@anchor{library/curses panel curses panel Panel replace}@anchor{3838}
@deffn {Μέθοδος} Panel.replace (win)

Change the window associated with the panel to the window `win'.
@end deffn

@geindex set_userptr() (μέθοδος της curses.panel.Panel)
@anchor{library/curses panel curses panel Panel set_userptr}@anchor{3839}
@deffn {Μέθοδος} 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() (μέθοδος της curses.panel.Panel)
@anchor{library/curses panel curses panel Panel show}@anchor{383a}
@deffn {Μέθοδος} Panel.show ()

Display the panel (which might have been hidden).
@end deffn

@geindex top() (μέθοδος της curses.panel.Panel)
@anchor{library/curses panel curses panel Panel top}@anchor{383b}
@deffn {Μέθοδος} Panel.top ()

Push panel to the top of the stack.
@end deffn

@geindex userptr() (μέθοδος της curses.panel.Panel)
@anchor{library/curses panel curses panel Panel userptr}@anchor{383c}
@deffn {Μέθοδος} Panel.userptr ()

Returns the user pointer for the panel.  This might be any Python object.
@end deffn

@geindex window() (μέθοδος της curses.panel.Panel)
@anchor{library/curses panel curses panel Panel window}@anchor{383d}
@deffn {Μέθοδος} Panel.window ()

Returns the window object associated with the panel.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node cmd — Support for line-oriented command interpreters,,curses panel — A panel stack extension for curses,Command-line interface libraries
@anchor{library/cmd doc}@anchor{383e}@anchor{library/cmd cmd-support-for-line-oriented-command-interpreters}@anchor{383f}@anchor{library/cmd module-cmd}@anchor{1a}@anchor{library/cmd translation-repo}@anchor{3840}
@subsection @code{cmd} — Support for line-oriented command interpreters


@geindex module; cmd

`Source code:' Lib/cmd.py@footnote{https://github.com/python/cpython/tree/main/Lib/cmd.py}


__________________________________________________________________


The @ref{1a78,,Cmd} class provides a simple framework for writing line-oriented
command interpreters.  These are often useful for test harnesses, administrative
tools, and prototypes that will later be wrapped in a more sophisticated
interface.

@geindex Cmd (κλάση σε cmd)
@anchor{library/cmd cmd Cmd}@anchor{1a78}
@deffn {Κλάση} cmd.Cmd (completekey='tab', stdin=None, stdout=None)

A @code{Cmd} instance or subclass instance is a line-oriented interpreter
framework.  There is no good reason to instantiate @code{Cmd} itself; rather,
it’s useful as a superclass of an interpreter class you define yourself in order
to inherit @code{Cmd}’s methods and encapsulate action methods.

The optional argument `completekey' is the @ref{c2,,readline} name of a completion
key; it defaults to @code{Tab}. If `completekey' is not @ref{a65,,None} and
@code{readline} is available, command completion is done automatically.

The default, @code{'tab'}, is treated specially, so that it refers to the
@code{Tab} key on every @ref{1c2f,,readline.backend}.
Specifically, if @code{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.

The optional arguments `stdin' and `stdout' specify the  input and output file
objects that the Cmd instance or subclass  instance will use for input and
output. If not specified, they will default to @ref{94a,,sys.stdin} and
@ref{e9c,,sys.stdout}.

If you want a given `stdin' to be used, make sure to set the instance’s
@ref{3841,,use_rawinput} attribute to @code{False}, otherwise `stdin' will be
ignored.


Άλλαξε στην έκδοση 3.13: @code{completekey='tab'} is replaced by @code{'^I'} for @code{editline}.

@end deffn

@menu
* Cmd Objects:: 
* Cmd Example:: 

@end menu

@node Cmd Objects,Cmd Example,,cmd — Support for line-oriented command interpreters
@anchor{library/cmd cmd-objects}@anchor{3842}@anchor{library/cmd id1}@anchor{3843}
@subsubsection Cmd Objects


A @ref{1a78,,Cmd} instance has the following methods:

@geindex cmdloop() (μέθοδος της cmd.Cmd)
@anchor{library/cmd cmd Cmd cmdloop}@anchor{3844}
@deffn {Μέθοδος} Cmd.cmdloop (intro=None)

Repeatedly issue a prompt, accept input, parse an initial prefix off the
received input, and dispatch to action methods, passing them the remainder of
the line as argument.

The optional argument is a banner or intro string to be issued before the first
prompt (this overrides the @ref{3845,,intro} class attribute).

If the @ref{c2,,readline} module is loaded, input will automatically inherit
@code{bash}-like history-list editing (e.g. @code{Control}-@code{P} scrolls back
to the last command, @code{Control}-@code{N} forward to the next one, @code{Control}-@code{F}
moves the cursor to the right non-destructively, @code{Control}-@code{B} moves the
cursor to the left non-destructively, etc.).

An end-of-file on input is passed back as the string @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{1c33,,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{3846,,postcmd()} method returns a true value.
The `stop' argument to @code{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() (μέθοδος της cmd.Cmd)
@anchor{library/cmd cmd Cmd do_help}@anchor{1c33}
@deffn {Μέθοδος} Cmd.do_help (arg)

All subclasses of @ref{1a78,,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() (μέθοδος της cmd.Cmd)
@anchor{library/cmd cmd Cmd onecmd}@anchor{3847}
@deffn {Μέθοδος} 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{3848,,precmd()} and @ref{3846,,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{3849,,default()} method is returned.
@end deffn

@geindex emptyline() (μέθοδος της cmd.Cmd)
@anchor{library/cmd cmd Cmd emptyline}@anchor{384a}
@deffn {Μέθοδος} Cmd.emptyline ()

Method called when an empty line is entered in response to the prompt. If this
method is not overridden, it repeats the last nonempty command entered.
@end deffn

@geindex default() (μέθοδος της cmd.Cmd)
@anchor{library/cmd cmd Cmd default}@anchor{3849}
@deffn {Μέθοδος} Cmd.default (line)

Method called on an input line when the command prefix is not recognized. If
this method is not overridden, it prints an error message and returns.
@end deffn

@geindex completedefault() (μέθοδος της cmd.Cmd)
@anchor{library/cmd cmd Cmd completedefault}@anchor{384b}
@deffn {Μέθοδος} 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() (μέθοδος της cmd.Cmd)
@anchor{library/cmd cmd Cmd columnize}@anchor{1e00}
@deffn {Μέθοδος} Cmd.columnize (list, displaywidth=80)

Method called to display a list of strings as a compact set of columns.
Each column is only as wide as necessary.
Columns are separated by two spaces for readability.
@end deffn

@geindex precmd() (μέθοδος της cmd.Cmd)
@anchor{library/cmd cmd Cmd precmd}@anchor{3848}
@deffn {Μέθοδος} Cmd.precmd (line)

Hook method executed just before the command line `line' is interpreted, but
after the input prompt is generated and issued.  This method is a stub in
@ref{1a78,,Cmd}; it exists to be overridden by subclasses.  The return value is
used as the command which will be executed by the @ref{3847,,onecmd()} method; the
@code{precmd()} implementation may re-write the command or simply return `line'
unchanged.
@end deffn

@geindex postcmd() (μέθοδος της cmd.Cmd)
@anchor{library/cmd cmd Cmd postcmd}@anchor{3846}
@deffn {Μέθοδος} Cmd.postcmd (stop, line)

Hook method executed just after a command dispatch is finished.  This method is
a stub in @ref{1a78,,Cmd}; it exists to be overridden by subclasses.  `line' is the
command line which was executed, and `stop' is a flag which indicates whether
execution will be terminated after the call to @code{postcmd()}; this will be the
return value of the @ref{3847,,onecmd()} method.  The return value of this method will
be used as the new value for the internal flag which corresponds to `stop';
returning false will cause interpretation to continue.
@end deffn

@geindex preloop() (μέθοδος της cmd.Cmd)
@anchor{library/cmd cmd Cmd preloop}@anchor{384c}
@deffn {Μέθοδος} Cmd.preloop ()

Hook method executed once when @ref{3844,,cmdloop()} is called.  This method is a stub
in @ref{1a78,,Cmd}; it exists to be overridden by subclasses.
@end deffn

@geindex postloop() (μέθοδος της cmd.Cmd)
@anchor{library/cmd cmd Cmd postloop}@anchor{384d}
@deffn {Μέθοδος} Cmd.postloop ()

Hook method executed once when @ref{3844,,cmdloop()} is about to return. This method
is a stub in @ref{1a78,,Cmd}; it exists to be overridden by subclasses.
@end deffn

Instances of @ref{1a78,,Cmd} subclasses have some public instance variables:

@geindex prompt (ιδιότητα της cmd.Cmd)
@anchor{library/cmd cmd Cmd prompt}@anchor{384e}
@deffn {Ιδιότητα} Cmd.prompt

The prompt issued to solicit input.
@end deffn

@geindex identchars (ιδιότητα της cmd.Cmd)
@anchor{library/cmd cmd Cmd identchars}@anchor{384f}
@deffn {Ιδιότητα} Cmd.identchars

The string of characters accepted for the command prefix.
@end deffn

@geindex lastcmd (ιδιότητα της cmd.Cmd)
@anchor{library/cmd cmd Cmd lastcmd}@anchor{3850}
@deffn {Ιδιότητα} Cmd.lastcmd

The last nonempty command prefix seen.
@end deffn

@geindex cmdqueue (ιδιότητα της cmd.Cmd)
@anchor{library/cmd cmd Cmd cmdqueue}@anchor{3851}
@deffn {Ιδιότητα} Cmd.cmdqueue

A list of queued input lines.  The cmdqueue list is checked in
@ref{3844,,cmdloop()} when new input is needed; if it is nonempty, its elements
will be processed in order, as if entered at the prompt.
@end deffn

@geindex intro (ιδιότητα της cmd.Cmd)
@anchor{library/cmd cmd Cmd intro}@anchor{3845}
@deffn {Ιδιότητα} Cmd.intro

A string to issue as an intro or banner.  May be overridden by giving the
@ref{3844,,cmdloop()} method an argument.
@end deffn

@geindex doc_header (ιδιότητα της cmd.Cmd)
@anchor{library/cmd cmd Cmd doc_header}@anchor{3852}
@deffn {Ιδιότητα} Cmd.doc_header

The header to issue if the help output has a section for documented commands.
@end deffn

@geindex misc_header (ιδιότητα της cmd.Cmd)
@anchor{library/cmd cmd Cmd misc_header}@anchor{3853}
@deffn {Ιδιότητα} 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 (ιδιότητα της cmd.Cmd)
@anchor{library/cmd cmd Cmd undoc_header}@anchor{3854}
@deffn {Ιδιότητα} 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 (ιδιότητα της cmd.Cmd)
@anchor{library/cmd cmd Cmd ruler}@anchor{3855}
@deffn {Ιδιότητα} Cmd.ruler

The character used to draw separator lines under the help-message headers.  If
empty, no ruler line is drawn.  It defaults to @code{'='}.
@end deffn

@geindex use_rawinput (ιδιότητα της cmd.Cmd)
@anchor{library/cmd cmd Cmd use_rawinput}@anchor{3841}
@deffn {Ιδιότητα} Cmd.use_rawinput

A flag, defaulting to true.  If true, @ref{3844,,cmdloop()} uses @ref{167d,,input()} to
display a prompt and read the next command; if false, @ref{e9c,,sys.stdout.write()}
and @ref{94a,,sys.stdin.readline()} are used. (This means that by importing
@ref{c2,,readline}, on systems that support it, the interpreter will automatically
support @code{Emacs}-like line editing  and command-history keystrokes.)
@end deffn

@node Cmd Example,,Cmd Objects,cmd — Support for line-oriented command interpreters
@anchor{library/cmd cmd-example}@anchor{3856}@anchor{library/cmd id2}@anchor{3857}
@subsubsection Cmd Example


The @code{cmd} module is mainly useful for building custom shells that let a
user work with a program interactively.

This section presents a simple example of how to build a shell around a few of
the commands in the @ref{10a,,turtle} module.

Basic turtle commands such as @ref{3858,,forward()} are added to a
@ref{1a78,,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{3848,,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{3851,,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

Here is a sample session with the turtle shell showing the help functions, using
blank lines to repeat commands, and the simple record and playback facility:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Concurrent Execution,Networking and Interprocess Communication,Command-line interface libraries,The Python Standard Library
@anchor{library/concurrency doc}@anchor{3859}@anchor{library/concurrency concurrency}@anchor{385a}@anchor{library/concurrency concurrent-execution}@anchor{385b}@anchor{library/concurrency translation-repo}@anchor{385c}
@section Concurrent Execution


The modules described in this chapter provide support for concurrent
execution of code. The appropriate choice of tool will depend on the
task to be executed (CPU bound vs IO bound) and preferred style of
development (event driven cooperative multitasking vs preemptive
multitasking). Here’s an overview:

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

@end menu

@node threading — Thread-based parallelism,multiprocessing — Process-based parallelism,,Concurrent Execution
@anchor{library/threading doc}@anchor{385d}@anchor{library/threading module-threading}@anchor{f6}@anchor{library/threading threading-thread-based-parallelism}@anchor{385e}
@subsection @code{threading} — Thread-based parallelism


@geindex module; threading

`Source code:' Lib/threading.py@footnote{https://github.com/python/cpython/tree/main/Lib/threading.py}


__________________________________________________________________


This module constructs higher-level threading interfaces on top of the lower
level @ref{2,,_thread} module.

@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

@menu
* Introduction: Introduction<6>. 
* GIL and performance considerations:: 
* Reference: Reference<2>. 
* Using locks@comma{} conditions@comma{} and semaphores in the with statement: Using locks conditions and semaphores in the with statement. 
* Iterator synchronization:: 

@end menu

@node Introduction<6>,GIL and performance considerations,,threading — Thread-based parallelism
@anchor{library/threading introduction}@anchor{385f}
@subsubsection Introduction


The @code{threading} module provides a way to run multiple threads@footnote{https://en.wikipedia.org/wiki/Thread_(computing)} (smaller
units of a process) concurrently within a single process. It allows for the
creation and management of threads, making it possible to execute tasks in
parallel, sharing memory space. Threads are particularly useful when tasks are
I/O bound, such as file operations or making network requests,
where much of the time is spent waiting for external resources.

A typical use case for @code{threading} includes managing a pool of worker
threads that can process multiple tasks concurrently.  Here’s a basic example of
creating and starting threads using @ref{420,,Thread}:

@example
import threading
import time

def crawl(link, delay=3):
    print(f"crawl started for @{link@}")
    time.sleep(delay)  # Blocking I/O (simulating a network request)
    print(f"crawl ended for @{link@}")

links = [
    "https://python.org",
    "https://docs.python.org",
    "https://peps.python.org",
]

# Start threads for each link
threads = []
for link in links:
    # Using `args` to pass positional arguments and `kwargs` for keyword arguments
    t = threading.Thread(target=crawl, args=(link,), kwargs=@{"delay": 2@})
    threads.append(t)

# Start each thread
for t in threads:
    t.start()

# Wait for all threads to finish
for t in threads:
    t.join()
@end example


Άλλαξε στην έκδοση 3.7: This module used to be optional, it is now always available.



@subsubheading Δείτε επίσης


@ref{b27,,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{be,,queue} provides a thread-safe interface for exchanging data between
running threads.

@ref{b,,asyncio} offers an alternative approach to achieving task level
concurrency without requiring the use of multiple operating system threads.


@cartouche
@quotation Σημείωση 
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

`Λεπτομέρεια υλοποίησης CPython:' In CPython, due to the @ref{685,,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{98,,multiprocessing} or @ref{206,,concurrent.futures.ProcessPoolExecutor}.
However, threading is still an appropriate model if you want to run
multiple I/O-bound tasks simultaneously.

@node GIL and performance considerations,Reference<2>,Introduction<6>,threading — Thread-based parallelism
@anchor{library/threading gil-and-performance-considerations}@anchor{3860}
@subsubsection GIL and performance considerations


Unlike the @ref{98,,multiprocessing} module, which uses separate processes to
bypass the @ref{685,,global interpreter lock} (GIL), the threading module operates
within a single process, meaning that all threads share the same memory space.
However, the GIL limits the performance gains of threading when it comes to
CPU-bound tasks, as only one thread can execute Python bytecode at a time.
Despite this, threads remain a useful tool for achieving concurrency in many
scenarios.

As of Python 3.13, @ref{487,,free-threaded} builds
can disable the GIL, enabling true parallel execution of threads, but this
feature is not available by default (see 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}).

@c TODO: At some point this feature will become available by default.

@node Reference<2>,Using locks conditions and semaphores in the with statement,GIL and performance considerations,threading — Thread-based parallelism
@anchor{library/threading reference}@anchor{3861}
@subsubsection Reference


This module defines the following functions:

@geindex active_count() (στη μονάδα threading)
@anchor{library/threading threading active_count}@anchor{33f}
@deffn {Συνάρτηση} threading.active_count ()

Return the number of @ref{420,,Thread} objects currently alive.  The returned
count is equal to the length of the list returned by @ref{1e51,,enumerate()}.

The function @code{activeCount} is a deprecated alias for this function.
@end deffn

@geindex current_thread() (στη μονάδα threading)
@anchor{library/threading threading current_thread}@anchor{33e}
@deffn {Συνάρτηση} threading.current_thread ()

Return the current @ref{420,,Thread} object, corresponding to the caller’s thread
of control.  If the caller’s thread of control was not created through the
@code{threading} module, a dummy thread object with limited functionality is
returned.

The function @code{currentThread} is a deprecated alias for this function.
@end deffn

@geindex excepthook() (στη μονάδα threading)
@anchor{library/threading threading excepthook}@anchor{c23}
@deffn {Συνάρτηση} threading.excepthook (args, /)

Handle uncaught exception raised by @ref{e00,,Thread.run()}.

The `args' argument has the following attributes:


@itemize *

@item 
`exc_type': Exception type.

@item 
`exc_value': Exception value, can be @code{None}.

@item 
`exc_traceback': Exception traceback, can be @code{None}.

@item 
`thread': Thread which raised the exception, can be @code{None}.
@end itemize

If `exc_type' is @ref{10f7,,SystemExit}, the exception is silently ignored.
Otherwise, the exception is printed out on @ref{d05,,sys.stderr}.

If  this function raises an exception, @ref{be5,,sys.excepthook()} is called to
handle it.

@ref{c23,,threading.excepthook()} can be overridden to control how uncaught
exceptions raised by @ref{e00,,Thread.run()} are handled.

Storing `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 `thread' using a custom hook can resurrect it if it is set to an
object which is being finalized. Avoid storing `thread' after the custom
hook completes to avoid resurrecting objects.


@subsubheading Δείτε επίσης


@ref{be5,,sys.excepthook()} handles uncaught exceptions.



Added in version 3.8.

@end deffn

@geindex __excepthook__ (στη μονάδα threading)
@anchor{library/threading threading __excepthook__}@anchor{c22}
@deffn {Δεδομένα} threading.__excepthook__

Holds the original value of @ref{c23,,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.


Added in version 3.10.

@end deffn

@geindex get_ident() (στη μονάδα threading)
@anchor{library/threading threading get_ident}@anchor{1505}
@deffn {Συνάρτηση} threading.get_ident ()

Return the “thread identifier” of the current thread.  This is a nonzero
integer.  Its value has no direct meaning; it is intended as a magic cookie
to be used e.g. to index a dictionary of thread-specific data.  Thread
identifiers may be recycled when a thread exits and another thread is
created.


Added in version 3.3.

@end deffn

@geindex get_native_id() (στη μονάδα threading)
@anchor{library/threading threading get_native_id}@anchor{e01}
@deffn {Συνάρτηση} threading.get_native_id ()

Return the native integral Thread ID of the current thread assigned by the kernel.
This is a non-negative integer.
Its 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).

@ref{232d,,Διαθεσιμότητα}: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD, Solaris.


Added in version 3.8.



Άλλαξε στην έκδοση 3.13: Added support for GNU/kFreeBSD.



Άλλαξε στην έκδοση 3.15: Added support for Solaris.

@end deffn

@geindex enumerate() (στη μονάδα threading)
@anchor{library/threading threading enumerate}@anchor{1e51}
@deffn {Συνάρτηση} threading.enumerate ()

Return a list of all @ref{420,,Thread} objects currently active.  The list
includes daemonic threads and dummy thread objects created by
@ref{33e,,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() (στη μονάδα threading)
@anchor{library/threading threading main_thread}@anchor{137b}
@deffn {Συνάρτηση} threading.main_thread ()

Return the main @ref{420,,Thread} object.  In normal conditions, the
main thread is the thread from which the Python interpreter was
started.


Added in version 3.4.

@end deffn

@geindex settrace() (στη μονάδα threading)
@anchor{library/threading threading settrace}@anchor{c20}
@deffn {Συνάρτηση} threading.settrace (func)

@geindex trace function

Set a trace function for all threads started from the @code{threading} module.
The `func' will be passed to  @ref{55c,,sys.settrace()} for each thread, before its
@ref{e00,,run()} method is called.
@end deffn

@geindex settrace_all_threads() (στη μονάδα threading)
@anchor{library/threading threading settrace_all_threads}@anchor{8d8}
@deffn {Συνάρτηση} threading.settrace_all_threads (func)

Set a trace function for all threads started from the @code{threading} module
and all Python threads that are currently executing.

The `func' will be passed to  @ref{55c,,sys.settrace()} for each thread, before its
@ref{e00,,run()} method is called.


Added in version 3.12.

@end deffn

@geindex gettrace() (στη μονάδα threading)
@anchor{library/threading threading gettrace}@anchor{c1e}
@deffn {Συνάρτηση} threading.gettrace ()

@geindex trace function
@geindex debugger

Get the trace function as set by @ref{c20,,settrace()}.


Added in version 3.10.

@end deffn

@geindex setprofile() (στη μονάδα threading)
@anchor{library/threading threading setprofile}@anchor{c21}
@deffn {Συνάρτηση} threading.setprofile (func)

@geindex profile function

Set a profile function for all threads started from the @code{threading} module.
The `func' will be passed to  @ref{18a0,,sys.setprofile()} for each thread, before its
@ref{e00,,run()} method is called.
@end deffn

@geindex setprofile_all_threads() (στη μονάδα threading)
@anchor{library/threading threading setprofile_all_threads}@anchor{8d9}
@deffn {Συνάρτηση} threading.setprofile_all_threads (func)

Set a profile function for all threads started from the @code{threading} module
and all Python threads that are currently executing.

The `func' will be passed to  @ref{18a0,,sys.setprofile()} for each thread, before its
@ref{e00,,run()} method is called.


Added in version 3.12.

@end deffn

@geindex getprofile() (στη μονάδα threading)
@anchor{library/threading threading getprofile}@anchor{c1f}
@deffn {Συνάρτηση} threading.getprofile ()

@geindex profile function

Get the profiler function as set by @ref{c21,,setprofile()}.


Added in version 3.10.

@end deffn

@geindex stack_size() (στη μονάδα threading)
@anchor{library/threading threading stack_size}@anchor{3862}
@deffn {Συνάρτηση} threading.stack_size ([size])

Return the thread stack size used when creating new threads.  The optional
`size' argument specifies the stack size to be used for subsequently created
threads, and must be 0 (use platform or configured default) or a positive
integer value of at least 32,768 (32 KiB). If `size' is not specified,
0 is used.  If changing the thread stack size is
unsupported, a @ref{30d,,RuntimeError} is raised.  If the specified stack size is
invalid, a @ref{277,,ValueError} is raised and the stack size is unmodified.  32 KiB
is currently the minimum supported stack size value to guarantee sufficient
stack space for the interpreter itself.  Note that some platforms may have
particular restrictions on values for the stack size, such as requiring a
minimum stack size > 32 KiB or requiring allocation in multiples of the system
memory page size - platform documentation should be referred to for more
information (4 KiB pages are common; using multiples of 4096 for the stack size is
the suggested approach in the absence of more specific information).

@ref{232d,,Διαθεσιμότητα}: Windows, pthreads.

Unix platforms with POSIX threads support.
@end deffn

This module also defines the following constant:

@geindex TIMEOUT_MAX (στη μονάδα threading)
@anchor{library/threading threading TIMEOUT_MAX}@anchor{3863}
@deffn {Δεδομένα} threading.TIMEOUT_MAX

The maximum value allowed for the `timeout' parameter of blocking functions
(@ref{a87,,Lock.acquire()}, @ref{122c,,RLock.acquire()}, @ref{1e5d,,Condition.wait()}, etc.).
Specifying a timeout greater than this value will raise an
@ref{c57,,OverflowError}.


Added in version 3.2.

@end deffn

This module defines a number of classes, which are detailed in the sections
below.

The design of this module is loosely based on Java’s threading model. However,
where Java makes locks and condition variables basic behavior of every object,
they are separate objects in Python.  Python’s @ref{420,,Thread} class supports a
subset of the behavior of Java’s Thread class; currently, there are no
priorities, no thread groups, and threads cannot be destroyed, stopped,
suspended, resumed, or interrupted.  The static methods of Java’s Thread class,
when implemented, are mapped to module-level functions.

All of the methods described below are executed atomically.

@menu
* Thread-local data:: 
* Thread objects:: 
* Lock objects:: 
* RLock objects:: 
* Condition objects:: 
* Semaphore objects:: 
* Semaphore example:: 
* Event objects:: 
* Timer objects:: 
* Barrier objects:: 

@end menu

@node Thread-local data,Thread objects,,Reference<2>
@anchor{library/threading thread-local-data}@anchor{3864}
@subsubsection Thread-local data


Thread-local data is data whose values are thread specific. If you
have data that you want to be local to a thread, create a
@ref{1a87,,local} object and use its attributes:

@example
>>> mydata = local()
>>> mydata.number = 42
>>> mydata.number
42
@end example

You can also access the @ref{1a87,,local}-object’s dictionary:

@example
>>> mydata.__dict__
@{'number': 42@}
>>> mydata.__dict__.setdefault('widgets', [])
[]
>>> mydata.widgets
[]
@end example

If we access the data in a different thread:

@example
>>> log = []
>>> def f():
...     items = sorted(mydata.__dict__.items())
...     log.append(items)
...     mydata.number = 11
...     log.append(mydata.number)

>>> import threading
>>> thread = threading.Thread(target=f)
>>> thread.start()
>>> thread.join()
>>> log
[[], 11]
@end example

we get different data.  Furthermore, changes made in the other thread
don’t affect data seen in this thread:

@example
>>> mydata.number
42
@end example

Of course, values you get from a @ref{1a87,,local} object, including their
@ref{1bf,,__dict__} attribute, are for whatever thread was current
at the time the attribute was read.  For that reason, you generally
don’t want to save these values across threads, as they apply only to
the thread they came from.

You can create custom @ref{1a87,,local} objects by subclassing the
@code{local} class:

@example
>>> class MyLocal(local):
...     number = 2
...     def __init__(self, /, **kw):
...         self.__dict__.update(kw)
...     def squared(self):
...         return self.number ** 2
@end example

This can be useful to support default values, methods and
initialization.  Note that if you define an @ref{2fa,,__init__()}
method, it will be called each time the @ref{1a87,,local} object is used
in a separate thread.  This is necessary to initialize each thread’s
dictionary.

Now if we create a @ref{1a87,,local} object:

@example
>>> mydata = MyLocal(color='red')
@end example

we have a default number:

@example
>>> mydata.number
2
@end example

an initial color:

@example
>>> mydata.color
'red'
>>> del mydata.color
@end example

And a method that operates on the data:

@example
>>> mydata.squared()
4
@end example

As before, we can access the data in a separate thread:

@example
>>> log = []
>>> thread = threading.Thread(target=f)
>>> thread.start()
>>> thread.join()
>>> log
[[('color', 'red')], 11]
@end example

without affecting this thread’s data:

@example
>>> mydata.number
2
>>> mydata.color
Traceback (most recent call last):
...
AttributeError: 'MyLocal' object has no attribute 'color'
@end example

Note that subclasses can define @ref{9d9,,__slots__}, but they are not
thread local. They are shared across threads:

@example
>>> class MyLocal(local):
...     __slots__ = 'number'

>>> mydata = MyLocal()
>>> mydata.number = 42
>>> mydata.color = 'red'
@end example

So, the separate thread:

@example
>>> thread = threading.Thread(target=f)
>>> thread.start()
>>> thread.join()
@end example

affects what we see:

@example
>>> mydata.number
11
@end example

@geindex local (κλάση σε threading)
@anchor{library/threading threading local}@anchor{1a87}
@deffn {Κλάση} threading.local

A class that represents thread-local data.
@end deffn

@node Thread objects,Lock objects,Thread-local data,Reference<2>
@anchor{library/threading id1}@anchor{3865}@anchor{library/threading thread-objects}@anchor{3866}
@subsubsection Thread objects


The @ref{420,,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{e00,,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 @code{run()} methods of this class.

Once a thread object is created, its activity must be started by calling the
thread’s @ref{422,,start()} method.  This invokes the @ref{e00,,run()}
method in a separate thread of control.

Once the thread’s activity is started, the thread is considered “alive”. It
stops being alive when its @ref{e00,,run()} method terminates – either
normally, or by raising an unhandled exception.  The @ref{d18,,is_alive()}
method tests whether the thread is alive.

Other threads can call a thread’s @ref{158d,,join()} method.  This blocks
the calling thread until the thread whose @code{join()} method is
called is terminated.

A thread has a name.  The name can be passed to the constructor, and read or
changed through the @ref{33d,,name} attribute.

If the @ref{e00,,run()} method raises an exception,
@ref{c23,,threading.excepthook()} is called to handle it. By default,
@code{threading.excepthook()} ignores silently @ref{10f7,,SystemExit}.

A thread can be flagged as a «daemon thread».  The significance of this flag is
that the entire Python program exits when only daemon threads are left.  The
initial value is inherited from the creating thread.  The flag can be set
through the @ref{33b,,daemon} property or the `daemon' constructor
argument.

@cartouche
@quotation Σημείωση 
Daemon threads are abruptly stopped at shutdown.  Their resources (such
as open files, database transactions, etc.) may not be released properly.
If you want your threads to stop gracefully, make them non-daemonic and
use a suitable signalling mechanism such as an @ref{1503,,Event}.
@end quotation
@end cartouche

There is a «main thread» object; this corresponds to the initial thread of
control in the Python program.  It is not a daemon thread.

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{3867,,joined}.  They are never deleted,
since it is impossible to detect the termination of alien threads.

@geindex Thread (κλάση σε threading)
@anchor{library/threading threading Thread}@anchor{420}
@deffn {Κλάση} threading.Thread (group=None, target=None, name=None, args=(), kwargs=@{@}, *, daemon=None, context=None)

This constructor should always be called with keyword arguments.  Arguments
are:

`group' should be @code{None}; reserved for future extension when a
@code{ThreadGroup} class is implemented.

`target' is the callable object to be invoked by the @ref{e00,,run()} method.
Defaults to @code{None}, meaning nothing is called.

`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' is a dictionary of keyword arguments for the target invocation.
Defaults to @code{@{@}}.

If not @code{None}, `daemon' explicitly sets whether the thread is daemonic.
If @code{None} (the default), the daemonic property is inherited from the
current thread.

`context' is the @ref{421,,Context} value to use when starting
the thread.  The default value is @code{None} which indicates that the
@ref{41f,,sys.flags.thread_inherit_context} flag controls the behaviour.  If
the flag is true, threads will start with a copy of the context of the
caller of @ref{422,,start()}.  If false, they will start with an empty
context.  To explicitly start with an empty context, pass a new instance of
@ref{421,,Context()}.  To explicitly start with a copy of the
current context, pass the value from @ref{3868,,copy_context()}. The
flag defaults true on free-threaded builds and false otherwise.

If the subclass overrides the constructor, it must make sure to invoke the
base class constructor (@code{Thread.__init__()}) before doing anything else to
the thread.


Άλλαξε στην έκδοση 3.3: Added the `daemon' parameter.



Άλλαξε στην έκδοση 3.10: Use the `target' name if `name' argument is omitted.



Άλλαξε στην έκδοση 3.14: Added the `context' parameter.


@geindex start() (μέθοδος της threading.Thread)
@anchor{library/threading threading Thread start}@anchor{422}
@deffn {Μέθοδος} start ()

Start the thread’s activity.

It must be called at most once per thread object.  It arranges for the
object’s @ref{e00,,run()} method to be invoked in a separate thread
of control.

This method will raise a @ref{30d,,RuntimeError} if called more than once
on the same thread object.

If supported, set the operating system thread name to
@ref{33d,,threading.Thread.name}. The name can be truncated depending on the
operating system thread name limits.


Άλλαξε στην έκδοση 3.14: Set the operating system thread name.

@end deffn

@geindex run() (μέθοδος της threading.Thread)
@anchor{library/threading threading Thread run}@anchor{e00}
@deffn {Μέθοδος} run ()

Method representing the thread’s activity.

You may override this method in a subclass.  The standard @code{run()}
method invokes the callable object passed to the object’s constructor as
the `target' argument, if any, with positional and keyword arguments taken
from the `args' and `kwargs' arguments, respectively.

Using list or tuple as the `args' argument which passed to the @code{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() (μέθοδος της threading.Thread)
@anchor{library/threading meth-thread-join}@anchor{3867}@anchor{library/threading threading Thread join}@anchor{158d}
@deffn {Μέθοδος} join (timeout=None)

Wait until the thread terminates. This blocks the calling thread until
the thread whose @code{join()} method is called terminates – either
normally or through an unhandled exception – or until the optional
timeout occurs.

When the `timeout' argument is present and not @code{None}, it should be a
real number specifying a timeout for the operation in seconds
(or fractions thereof). As @code{join()} always returns @code{None},
you must call @ref{d18,,is_alive()} after @code{join()} to
decide whether a timeout happened – if the thread is still alive, the
@code{join()} call timed out.

When the `timeout' argument is not present or @code{None}, the operation will
block until the thread terminates.

A thread can be joined many times.

@code{join()} raises a @ref{30d,,RuntimeError} if an attempt is made
to join the current thread as that would cause a deadlock. It is also
an error to @code{join()} a thread before it has been started
and attempts to do so raise the same exception.

If an attempt is made to join a running daemonic thread in late stages
of @ref{1a0,,Python finalization} @code{join()}
raises a @ref{68a,,PythonFinalizationError}.


Άλλαξε στην έκδοση 3.14: May raise @ref{68a,,PythonFinalizationError}.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timeout', not only integer or float.

@end deffn

@geindex name (ιδιότητα της threading.Thread)
@anchor{library/threading threading Thread name}@anchor{33d}
@deffn {Ιδιότητα} name

A string used for identification purposes only. It has no semantics.
Multiple threads may be given the same name.  The initial name is set by
the constructor.

On some platforms, the thread name is set at the operating system level
when the thread starts, so that it is visible in task managers.
This name may be truncated to fit in a system-specific limit (for example,
15 bytes on Linux or 63 bytes on macOS).

Changes to `name' are only reflected at the OS level when the currently
running thread is renamed. (Setting the `name' attribute of a
different thread only updates the Python Thread object.)
@end deffn

@geindex getName() (μέθοδος της threading.Thread)
@geindex setName() (μέθοδος της threading.Thread)
@anchor{library/threading threading Thread getName}@anchor{3869}
@deffn {Μέθοδος} getName ()
@anchor{library/threading threading Thread setName}@anchor{33c}
@deffnx {Μέθοδος} setName ()

Deprecated getter/setter API for @ref{33d,,name}; use it directly as a
property instead.


Αποσύρθηκε στην έκδοση 3.10.

@end deffn

@geindex ident (ιδιότητα της threading.Thread)
@anchor{library/threading threading Thread ident}@anchor{3390}
@deffn {Ιδιότητα} ident

The “thread identifier” of this thread or @code{None} if the thread has not
been started.  This is a nonzero integer.  See the @ref{1505,,get_ident()}
function.  Thread identifiers may be recycled when a thread exits and
another thread is created.  The identifier is available even after the
thread has exited.
@end deffn

@geindex native_id (ιδιότητα της threading.Thread)
@anchor{library/threading threading Thread native_id}@anchor{e02}
@deffn {Ιδιότητα} 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{e01,,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 Σημείωση 
Similar to Process IDs, Thread IDs are only valid (guaranteed unique
system-wide) from the time the thread is created until the thread
has been terminated.
@end quotation
@end cartouche

@ref{232d,,Διαθεσιμότητα}: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD.


Added in version 3.8.

@end deffn

@geindex is_alive() (μέθοδος της threading.Thread)
@anchor{library/threading threading Thread is_alive}@anchor{d18}
@deffn {Μέθοδος} is_alive ()

Return whether the thread is alive.

This method returns @code{True} just before the @ref{e00,,run()} method
starts until just after the @code{run()} method terminates.  The
module function @ref{1e51,,enumerate()} returns a list of all alive threads.
@end deffn

@geindex daemon (ιδιότητα της threading.Thread)
@anchor{library/threading threading Thread daemon}@anchor{33b}
@deffn {Ιδιότητα} daemon

A boolean value indicating whether this thread is a daemon thread (@code{True})
or not (@code{False}).  This must be set before @ref{422,,start()} is called,
otherwise @ref{30d,,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
@code{daemon} = @code{False}.

The entire Python program exits when no alive non-daemon threads are left.
@end deffn

@geindex isDaemon() (μέθοδος της threading.Thread)
@geindex setDaemon() (μέθοδος της threading.Thread)
@anchor{library/threading threading Thread isDaemon}@anchor{386a}
@deffn {Μέθοδος} isDaemon ()
@anchor{library/threading threading Thread setDaemon}@anchor{33a}
@deffnx {Μέθοδος} setDaemon ()

Deprecated getter/setter API for @ref{33b,,daemon}; use it directly as a
property instead.


Αποσύρθηκε στην έκδοση 3.10.

@end deffn
@end deffn

@node Lock objects,RLock objects,Thread objects,Reference<2>
@anchor{library/threading id2}@anchor{386b}@anchor{library/threading lock-objects}@anchor{386c}
@subsubsection Lock objects


A primitive lock is a synchronization primitive that is not owned by a
particular thread when locked.  In Python, it is currently the lowest level
synchronization primitive available, implemented directly by the @ref{2,,_thread}
extension module.

A primitive lock is in one of two states, «locked» or «unlocked». It is created
in the unlocked state.  It has two basic methods, @ref{a87,,acquire()} and
@ref{1667,,release()}.  When the state is unlocked, @code{acquire()}
changes the state to locked and returns immediately.  When the state is locked,
@code{acquire()} blocks until a call to @code{release()} in another
thread changes it to unlocked, then the @code{acquire()} call resets it
to locked and returns.  The @code{release()} method should only be
called in the locked state; it changes the state to unlocked and returns
immediately. If an attempt is made to release an unlocked lock, a
@ref{30d,,RuntimeError} will be raised.

Locks also support the @ref{386d,,context management protocol}.

When more than one thread is blocked in @ref{a87,,acquire()} waiting for the
state to turn to unlocked, only one thread proceeds when a @ref{1667,,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 (κλάση σε threading)
@anchor{library/threading threading Lock}@anchor{1a10}
@deffn {Κλάση} 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.


Άλλαξε στην έκδοση 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() (μέθοδος της threading.Lock)
@anchor{library/threading threading Lock acquire}@anchor{a87}
@deffn {Μέθοδος} acquire (blocking=True, timeout=-1)

Acquire a lock, blocking or non-blocking.

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 `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).


Άλλαξε στην έκδοση 3.2: The `timeout' parameter is new.



Άλλαξε στην έκδοση 3.2: Lock acquisition can now be interrupted by signals on POSIX if the
underlying threading implementation supports it.



Άλλαξε στην έκδοση 3.14: Lock acquisition can now be interrupted by signals on Windows.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timeout', not only integer or float.

@end deffn

@geindex release() (μέθοδος της threading.Lock)
@anchor{library/threading threading Lock release}@anchor{1667}
@deffn {Μέθοδος} 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.

When invoked on an unlocked lock, a @ref{30d,,RuntimeError} is raised.

There is no return value.
@end deffn

@geindex locked() (μέθοδος της threading.Lock)
@anchor{library/threading threading Lock locked}@anchor{386e}
@deffn {Μέθοδος} locked ()

Return @code{True} if the lock is acquired.
@end deffn
@end deffn

@node RLock objects,Condition objects,Lock objects,Reference<2>
@anchor{library/threading id3}@anchor{386f}@anchor{library/threading rlock-objects}@anchor{3870}
@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{122c,,acquire()} method to lock it,
and its @ref{1667,,release()} method to unlock it.

@cartouche
@quotation Σημείωση 
Reentrant locks support the @ref{386d,,context management protocol},
so it is recommended to use @ref{20a,,with} instead of manually calling
@ref{122c,,acquire()} and @ref{3871,,release()}
to handle acquiring and releasing the lock for a block of code.
@end quotation
@end cartouche

RLock’s @ref{122c,,acquire()}/@ref{3871,,release()} call pairs may be nested,
unlike Lock’s @ref{a87,,acquire()}/@ref{1667,,release()}. Only the final
@code{release()} (the @code{release()} of the outermost pair) resets
the lock to an unlocked state and allows another thread blocked in
@code{acquire()} to proceed.

@ref{122c,,acquire()}/@ref{3871,,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 (κλάση σε threading)
@anchor{library/threading threading RLock}@anchor{2df}
@deffn {Κλάση} 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() (μέθοδος της threading.RLock)
@anchor{library/threading threading RLock acquire}@anchor{122c}
@deffn {Μέθοδος} acquire (blocking=True, timeout=-1)

Acquire a lock, blocking or non-blocking.


@subsubheading Δείτε επίσης



@table @asis

@item @ref{386d,,Using RLock as a context manager}

Recommended over manual @code{acquire()} and @ref{3871,,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 value.

@item 
If the same thread owns the lock, acquire the lock again, and
return immediately. This is the difference between @ref{1a10,,Lock} and
@code{RLock}; @code{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{3871,,release()} as many times
may lead to deadlock. Consider using @code{RLock} as a context manager rather than
calling acquire/release directly.


Άλλαξε στην έκδοση 3.2: The `timeout' parameter is new.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timeout', not only integer or float.

@end deffn

@geindex release() (μέθοδος της threading.RLock)
@anchor{library/threading threading RLock release}@anchor{3871}
@deffn {Μέθοδος} 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{30d,,RuntimeError} is raised if this method is called when the lock is
not acquired.

There is no return value.
@end deffn

@geindex locked() (μέθοδος της threading.RLock)
@anchor{library/threading threading RLock locked}@anchor{1a32}
@deffn {Μέθοδος} locked ()

Return a boolean indicating whether this object is locked right now.


Added in version 3.14.

@end deffn
@end deffn

@node Condition objects,Semaphore objects,RLock objects,Reference<2>
@anchor{library/threading condition-objects}@anchor{3872}@anchor{library/threading id4}@anchor{3873}
@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{386d,,context management protocol}:
using the @code{with} statement acquires the associated lock for the duration of
the enclosed block.  The @ref{3874,,acquire()} and
@ref{3875,,release()} methods also call the corresponding methods of
the associated lock.

Other methods must be called with the associated lock held.  The
@ref{1e5d,,wait()} method releases the lock, and then blocks until
another thread awakens it by calling @ref{1d64,,notify()} or
@ref{338,,notify_all()}.  Once awakened, @code{wait()}
re-acquires the lock and returns.  It is also possible to specify a timeout.

The @ref{1d64,,notify()} method wakes up one of the threads waiting for
the condition variable, if any are waiting.  The @ref{338,,notify_all()}
method wakes up all threads waiting for the condition variable.

Note: the @ref{1d64,,notify()} and @ref{338,,notify_all()} methods
don’t release the lock; this means that the thread or threads awakened will
not return from their @ref{1e5d,,wait()} call immediately, but only when
the thread that called @code{notify()} or @code{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{1e5d,,wait()} repeatedly until they
see the desired state, while threads that modify the state call
@ref{1d64,,notify()} or @ref{338,,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{1e5d,,wait()} can return after an arbitrary long time,
and the condition which prompted the @ref{1d64,,notify()} call may
no longer hold true.  This is inherent to multi-threaded programming.  The
@ref{3876,,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{1d64,,notify()} and @ref{338,,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 (κλάση σε threading)
@anchor{library/threading threading Condition}@anchor{1500}
@deffn {Κλάση} 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{1a10,,Lock}
or @ref{2df,,RLock} object, and it is used as the underlying lock.  Otherwise,
a new @code{RLock} object is created and used as the underlying lock.


Άλλαξε στην έκδοση 3.3: changed from a factory function to a class.


@geindex acquire() (μέθοδος της threading.Condition)
@anchor{library/threading threading Condition acquire}@anchor{3874}
@deffn {Μέθοδος} 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() (μέθοδος της threading.Condition)
@anchor{library/threading threading Condition release}@anchor{3875}
@deffn {Μέθοδος} release ()

Release the underlying lock. This method calls the corresponding method on
the underlying lock; there is no return value.
@end deffn

@geindex locked() (μέθοδος της threading.Condition)
@anchor{library/threading threading Condition locked}@anchor{3877}
@deffn {Μέθοδος} locked ()

Return a boolean indicating whether this object is locked right now.


Added in version 3.14.

@end deffn

@geindex wait() (μέθοδος της threading.Condition)
@anchor{library/threading threading Condition wait}@anchor{1e5d}
@deffn {Μέθοδος} 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{30d,,RuntimeError} is
raised.

This method releases the underlying lock, and then blocks until it is
awakened by a @ref{1d64,,notify()} or @ref{338,,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
real number specifying a timeout for the operation in seconds
(or fractions thereof).

When the underlying lock is an @ref{2df,,RLock}, it is not released using
its @ref{3875,,release()} method, since this may not actually unlock the lock
when it was acquired multiple times recursively.  Instead, an internal
interface of the @code{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}.


Άλλαξε στην έκδοση 3.2: Previously, the method always returned @code{None}.

@end deffn

@geindex wait_for() (μέθοδος της threading.Condition)
@anchor{library/threading threading Condition wait_for}@anchor{3876}
@deffn {Μέθοδος} 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{1e5d,,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{1e5d,,wait()}: The lock must be
held when called and is re-acquired on return.  The predicate is evaluated
with the lock held.


Added in version 3.2.

@end deffn

@geindex notify() (μέθοδος της threading.Condition)
@anchor{library/threading threading Condition notify}@anchor{1d64}
@deffn {Μέθοδος} 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{30d,,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{1e5d,,wait()}
call until it can reacquire the lock.  Since @code{notify()} does not
release the lock, its caller should.
@end deffn

@geindex notify_all() (μέθοδος της threading.Condition)
@anchor{library/threading threading Condition notify_all}@anchor{338}
@deffn {Μέθοδος} notify_all ()

Wake up all threads waiting on this condition.  This method acts like
@ref{1d64,,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{30d,,RuntimeError} is raised.

The method @code{notifyAll} is a deprecated alias for this method.
@end deffn
@end deffn

@node Semaphore objects,Semaphore example,Condition objects,Reference<2>
@anchor{library/threading id5}@anchor{3878}@anchor{library/threading semaphore-objects}@anchor{3879}
@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{15f8,,acquire()} and
@ref{387a,,release()}).

A semaphore manages an internal counter which is decremented by each
@ref{15f8,,acquire()} call and incremented by each @ref{387a,,release()}
call.  The counter can never go below zero; when @code{acquire()}
finds that it is zero, it blocks, waiting until some other thread calls
@code{release()}.

Semaphores also support the @ref{386d,,context management protocol}.

@geindex Semaphore (κλάση σε threading)
@anchor{library/threading threading Semaphore}@anchor{1501}
@deffn {Κλάση} threading.Semaphore (value=1)

This class implements semaphore objects.  A semaphore manages an atomic
counter representing the number of @ref{387a,,release()} calls minus the number of
@ref{15f8,,acquire()} calls, plus an initial value.  The @code{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{277,,ValueError} is
raised.


Άλλαξε στην έκδοση 3.3: changed from a factory function to a class.


@geindex acquire() (μέθοδος της threading.Semaphore)
@anchor{library/threading threading Semaphore acquire}@anchor{15f8}
@deffn {Μέθοδος} acquire (blocking=True, timeout=None)

Acquire a semaphore.

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{387a,,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 @code{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.


Άλλαξε στην έκδοση 3.2: The `timeout' parameter is new.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timeout', not only integer or float.

@end deffn

@geindex release() (μέθοδος της threading.Semaphore)
@anchor{library/threading threading Semaphore release}@anchor{387a}
@deffn {Μέθοδος} 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.


Άλλαξε στην έκδοση 3.9: Added the `n' parameter to release multiple waiting threads at once.

@end deffn
@end deffn

@geindex BoundedSemaphore (κλάση σε threading)
@anchor{library/threading threading BoundedSemaphore}@anchor{1502}
@deffn {Κλάση} 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{277,,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.


Άλλαξε στην έκδοση 3.3: changed from a factory function to a class.

@end deffn

@node Semaphore example,Event objects,Semaphore objects,Reference<2>
@anchor{library/threading semaphore-example}@anchor{387b}@anchor{library/threading semaphore-examples}@anchor{387c}
@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 example,Reference<2>
@anchor{library/threading event-objects}@anchor{387d}@anchor{library/threading id6}@anchor{387e}
@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{387f,,set()} method and reset to false with the @ref{3880,,clear()}
method.  The @ref{16cb,,wait()} method blocks until the flag is true.

@geindex Event (κλάση σε threading)
@anchor{library/threading threading Event}@anchor{1503}
@deffn {Κλάση} threading.Event

Class implementing event objects.  An event manages a flag that can be set to
true with the @ref{387f,,set()} method and reset to false with the
@ref{3880,,clear()} method.  The @ref{16cb,,wait()} method blocks until the flag is true.
The flag is initially false.


Άλλαξε στην έκδοση 3.3: changed from a factory function to a class.


@geindex is_set() (μέθοδος της threading.Event)
@anchor{library/threading threading Event is_set}@anchor{339}
@deffn {Μέθοδος} 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() (μέθοδος της threading.Event)
@anchor{library/threading threading Event set}@anchor{387f}
@deffn {Μέθοδος} set ()

Set the internal flag to true. All threads waiting for it to become true
are awakened. Threads that call @ref{16cb,,wait()} once the flag is true will
not block at all.
@end deffn

@geindex clear() (μέθοδος της threading.Event)
@anchor{library/threading threading Event clear}@anchor{3880}
@deffn {Μέθοδος} clear ()

Reset the internal flag to false. Subsequently, threads calling
@ref{16cb,,wait()} will block until @ref{387f,,set()} is called to set the internal
flag to true again.
@end deffn

@geindex wait() (μέθοδος της threading.Event)
@anchor{library/threading threading Event wait}@anchor{16cb}
@deffn {Μέθοδος} 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
real number specifying a timeout for the operation in seconds,
or fractions thereof.


Άλλαξε στην έκδοση 3.1: Previously, the method always returned @code{None}.

@end deffn
@end deffn

@node Timer objects,Barrier objects,Event objects,Reference<2>
@anchor{library/threading id7}@anchor{3881}@anchor{library/threading timer-objects}@anchor{3882}
@subsubsection Timer objects


This class represents an action that should be run only after a certain amount
of time has passed — a timer.  @ref{1504,,Timer} is a subclass of @ref{420,,Thread}
and as such also functions as an example of creating custom threads.

Timers are started, as with threads, by calling their @ref{422,,Timer.start}
method.  The timer can be stopped (before its action has begun) by calling the
@ref{3883,,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.

For example:

@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 (κλάση σε threading)
@anchor{library/threading threading Timer}@anchor{1504}
@deffn {Κλάση} 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.


Άλλαξε στην έκδοση 3.3: changed from a factory function to a class.


@geindex cancel() (μέθοδος της threading.Timer)
@anchor{library/threading threading Timer cancel}@anchor{3883}
@deffn {Μέθοδος} 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,,Timer objects,Reference<2>
@anchor{library/threading barrier-objects}@anchor{3884}
@subsubsection Barrier objects



Added in 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{3885,,wait()} method and will block until
all of the threads have made their @code{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 (κλάση σε threading)
@anchor{library/threading threading Barrier}@anchor{158c}
@deffn {Κλάση} 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{3885,,wait()} method.

@geindex wait() (μέθοδος της threading.Barrier)
@anchor{library/threading threading Barrier wait}@anchor{3885}
@deffn {Μέθοδος} 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{158e,,BrokenBarrierError} exception if the
barrier is broken or reset while a thread is waiting.
@end deffn

@geindex reset() (μέθοδος της threading.Barrier)
@anchor{library/threading threading Barrier reset}@anchor{3886}
@deffn {Μέθοδος} reset ()

Return the barrier to the default, empty state.  Any threads waiting on it
will receive the @ref{158e,,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() (μέθοδος της threading.Barrier)
@anchor{library/threading threading Barrier abort}@anchor{3887}
@deffn {Μέθοδος} abort ()

Put the barrier into a broken state.  This causes any active or future
calls to @ref{3885,,wait()} to fail with the @ref{158e,,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 (ιδιότητα της threading.Barrier)
@anchor{library/threading threading Barrier parties}@anchor{3888}
@deffn {Ιδιότητα} parties

The number of threads required to pass the barrier.
@end deffn

@geindex n_waiting (ιδιότητα της threading.Barrier)
@anchor{library/threading threading Barrier n_waiting}@anchor{3889}
@deffn {Ιδιότητα} n_waiting

The number of threads currently waiting in the barrier.
@end deffn

@geindex broken (ιδιότητα της threading.Barrier)
@anchor{library/threading threading Barrier broken}@anchor{388a}
@deffn {Ιδιότητα} broken

A boolean that is @code{True} if the barrier is in the broken state.
@end deffn
@end deffn

@geindex BrokenBarrierError
@anchor{library/threading threading BrokenBarrierError}@anchor{158e}
@deffn {Εξαίρεση} threading.BrokenBarrierError

This exception, a subclass of @ref{30d,,RuntimeError}, is raised when the
@ref{158c,,Barrier} object is reset or broken.
@end deffn

@node Using locks conditions and semaphores in the with statement,Iterator synchronization,Reference<2>,threading — Thread-based parallelism
@anchor{library/threading using-locks-conditions-and-semaphores-in-the-with-statement}@anchor{388b}@anchor{library/threading with-locks}@anchor{386d}
@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{20a,,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

is equivalent to:

@example
some_lock.acquire()
try:
    # do something...
finally:
    some_lock.release()
@end example

Currently, @ref{1a10,,Lock}, @ref{2df,,RLock}, @ref{1500,,Condition},
@ref{1501,,Semaphore}, and @ref{1502,,BoundedSemaphore} objects may be used as
@ref{20a,,with} statement context managers.

@node Iterator synchronization,,Using locks conditions and semaphores in the with statement,threading — Thread-based parallelism
@anchor{library/threading iterator-synchronization}@anchor{388c}
@subsubsection Iterator synchronization


By default, Python iterators do not support concurrent access. Most iterators make
no guarantees when accessed simultaneously from multiple threads. Generator
iterators, for example, raise @ref{277,,ValueError} if one of their iterator methods
is called while the generator is already executing. The tools in this section
allow reliable concurrency support to be added to ordinary iterators and
iterator-producing callables.

The @ref{27f,,serialize_iterator} wrapper lets multiple threads share a single iterator and
take turns consuming from it. While one thread is running @code{__next__()}, the
others block until the iterator becomes available. Each value produced by the
underlying iterator is delivered to exactly one caller.

The @ref{281,,concurrent_tee()} function lets multiple threads each receive the full
stream of values from one underlying iterator. It creates independent iterators
that all draw from the same source. Values are buffered until consumed by all
of the derived iterators.

@geindex serialize_iterator (κλάση σε threading)
@anchor{library/threading threading serialize_iterator}@anchor{27f}
@deffn {Κλάση} threading.serialize_iterator (iterable)

Return an iterator wrapper that serializes concurrent calls to
@ref{1672,,__next__()} using a lock.

If the wrapped iterator also defines @ref{260f,,send()},
@ref{905,,throw()}, or @ref{199e,,close()}, those calls
are serialized as well.

This makes it possible to share a single iterator, including a generator
iterator, between multiple threads. A lock ensures that calls are handled
one at a time. No values are duplicated or skipped by the wrapper itself.
Each item from the underlying iterator is given to exactly one caller.

This wrapper does not copy or buffer values. Threads that call
@ref{bb5,,next()} while another thread is already advancing the iterator will
block until the active call completes.

Example:

@example
import threading

def squares(n):
    for x in range(n):
        yield x * x

def consume(name, iterable):
    for item in iterable:
        print(name, item)

source = threading.serialize_iterator(squares(5))

t1 = threading.Thread(target=consume, args=("left", source))
t2 = threading.Thread(target=consume, args=("right", source))
t1.start()
t2.start()
t1.join()
t2.join()
@end example

In this example, each number is printed exactly once, but the work is shared
between the two threads.


Added in version 3.15.

@end deffn

@geindex synchronized_iterator() (στη μονάδα threading)
@anchor{library/threading threading synchronized_iterator}@anchor{280}
@deffn {Συνάρτηση} threading.synchronized_iterator (func)

Wrap an iterator-producing callable so that each iterator it returns is
automatically passed through @ref{27f,,serialize_iterator}.

This is especially useful as a @ref{b18,,decorator} for generator functions,
allowing their generator-iterators to be consumed from multiple threads.

Example:

@example
import threading

@@threading.synchronized_iterator
def squares(n):
    for x in range(n):
        yield x * x

def consume(name, iterable):
    for item in iterable:
        print(name, item)

source = squares(5)

t1 = threading.Thread(target=consume, args=("left", source))
t2 = threading.Thread(target=consume, args=("right", source))
t1.start()
t2.start()
t1.join()
t2.join()
@end example

The returned wrapper preserves the metadata of `func', such as its name and
wrapped function reference.


Added in version 3.15.

@end deffn

@geindex concurrent_tee() (στη μονάδα threading)
@anchor{library/threading threading concurrent_tee}@anchor{281}
@deffn {Συνάρτηση} threading.concurrent_tee (iterable, n=2)

Return `n' independent iterators from a single input `iterable', with
guaranteed behavior when the derived iterators are consumed concurrently.

This function is similar to @ref{2dc2,,itertools.tee()}, but is intended for cases
where the source iterator may feed consumers running in different threads.
Each returned iterator yields every value from the underlying iterable, in
the same order.

Internally, values are buffered until every derived iterator has consumed
them.

The returned iterators share the same underlying synchronization lock. Each
individual derived iterator is intended to be consumed by one thread at a
time. If a single derived iterator must itself be shared by multiple
threads, wrap it with @ref{27f,,serialize_iterator}.

If `n' is @code{0}, return an empty tuple. If `n' is negative, raise
@ref{277,,ValueError}.

Example:

@example
import threading

def squares(n):
    for x in range(n):
        yield x * x

def consume(name, iterable):
    for item in iterable:
        print(name, item)

source = squares(5)
left, right = threading.concurrent_tee(source)

t1 = threading.Thread(target=consume, args=("left", left))
t2 = threading.Thread(target=consume, args=("right", right))
t1.start()
t2.start()
t1.join()
t2.join()
@end example

In this example, both consumer threads see the full sequence of squares
from a single generator expression.


Added in version 3.15.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node multiprocessing — Process-based parallelism,multiprocessing shared_memory — Shared memory for direct access across processes,threading — Thread-based parallelism,Concurrent Execution
@anchor{library/multiprocessing doc}@anchor{388d}@anchor{library/multiprocessing module-multiprocessing}@anchor{98}@anchor{library/multiprocessing multiprocessing-process-based-parallelism}@anchor{388e}@anchor{library/multiprocessing translation-repo}@anchor{388f}
@subsection @code{multiprocessing} — Process-based parallelism


@geindex module; multiprocessing

`Source code:' Lib/multiprocessing/@footnote{https://github.com/python/cpython/tree/main/Lib/multiprocessing/}


__________________________________________________________________


@c include for modules that don't work on WASM or mobile platforms

@ref{232d,,Διαθεσιμότητα}: not Android, not iOS, not WASI.

This module is not supported on @ref{244d,,mobile platforms}
or @ref{1d67,,WebAssembly platforms}.

@menu
* Introduction: Introduction<7>. 
* Reference: Reference<3>. 
* Programming guidelines:: 
* Examples: Examples<12>. 

@end menu

@node Introduction<7>,Reference<3>,,multiprocessing — Process-based parallelism
@anchor{library/multiprocessing introduction}@anchor{3890}
@subsubsection Introduction


@code{multiprocessing} is a package that supports spawning processes using an
API similar to the @ref{f6,,threading} module.  The @code{multiprocessing} package
offers both local and remote concurrency, effectively side-stepping the
@ref{685,,Global Interpreter Lock} by using
subprocesses instead of threads.  Due
to this, the @code{multiprocessing} module allows the programmer to fully
leverage multiple processors on a given machine.  It runs on both POSIX and
Windows.

The @code{multiprocessing} module also introduces the
@ref{1315,,Pool} object which offers a convenient means of
parallelizing the execution of a function across multiple input values,
distributing the input data across processes (data parallelism).  The following
example demonstrates the common practice of defining such functions in a module
so that child processes can successfully import that module.  This basic example
of data parallelism using @code{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

will print to standard output

@example
[1, 4, 9]
@end example

The @code{multiprocessing} module also introduces APIs which do not have
analogs in the @ref{f6,,threading} module, like the ability to @ref{1a7f,,terminate}, @ref{4dd,,interrupt} or @ref{f15,,kill} a running process.


@subsubheading Δείτε επίσης


@ref{206,,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{1315,,Pool}
interface directly, the @ref{24,,concurrent.futures} API more readily allows
the submission of work to the underlying process pool to be separated from
waiting for the results.


@menu
* The Process class:: 
* Contexts and start methods:: 
* Exchanging objects between processes:: 
* Synchronization between processes:: 
* Sharing state between processes:: 
* Using a pool of workers:: 

@end menu

@node The Process class,Contexts and start methods,,Introduction<7>
@anchor{library/multiprocessing the-process-class}@anchor{3891}
@subsubsection The @code{Process} class


In @code{multiprocessing}, processes are spawned by creating a @ref{4de,,Process}
object and then calling its @ref{1735,,start()} method.  @code{Process}
follows the API of @ref{420,,threading.Thread}.  A trivial example of a
multiprocess program is

@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

To show the individual process IDs involved, here is an expanded example:

@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

For an explanation of why the @code{if __name__ == '__main__'} part is
necessary, see @ref{3892,,Programming guidelines}.

The arguments to @ref{4de,,Process} usually need to be unpickleable from within
the child process. If you tried typing the above example directly into a REPL it
could lead to an @ref{1a9,,AttributeError} in the child process trying to locate the
`f' function in the @code{__main__} module.

@node Contexts and start methods,Exchanging objects between processes,The Process class,Introduction<7>
@anchor{library/multiprocessing contexts-and-start-methods}@anchor{3893}@anchor{library/multiprocessing multiprocessing-start-methods}@anchor{46d}
@subsubsection Contexts and start methods


Depending on the platform, @code{multiprocessing} supports three ways
to start a process.  These `start methods' are

@quotation
@anchor{library/multiprocessing multiprocessing-start-method-spawn}@anchor{46f}

@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{3894,,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.
@end table
@anchor{library/multiprocessing multiprocessing-start-method-fork}@anchor{46e}

@table @asis

@item `fork'

The parent process uses @ref{6bd,,os.fork()} to fork the Python
interpreter.  The child process, when it begins, is effectively
identical to the parent process.  All resources of the parent are
inherited by the child process.  Note that safely forking a
multithreaded process is problematic.

Available on POSIX systems.


Άλλαξε στην έκδοση 3.14: This is no longer the default start method on any platform.
Code that requires `fork' must explicitly specify that via
@ref{4d6,,get_context()} or @ref{4d7,,set_start_method()}.



Άλλαξε στην έκδοση 3.12: If Python is able to detect that your process has multiple threads, the
@ref{6bd,,os.fork()} function that this start method calls internally will
raise a @ref{2c9,,DeprecationWarning}. Use a different start method.
See the @code{os.fork()} documentation for further explanation.

@end table
@anchor{library/multiprocessing multiprocessing-start-method-forkserver}@anchor{46c}

@table @asis

@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{6bd,,os.fork()}.
No unnecessary resources are inherited.

Available on POSIX platforms which support passing file descriptors over
Unix pipes such as Linux.  The default on those.


Άλλαξε στην έκδοση 3.14: This became the default start method on POSIX platforms.

@end table
@end quotation


Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 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}.



Άλλαξε στην έκδοση 3.14: On POSIX platforms the default start method was changed from `fork' to
`forkserver' to retain the performance but avoid common multithreaded
process incompatibilities. See gh-84559@footnote{https://github.com/python/cpython/issues/84559}.


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{1be1,,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.)

To select a start method you use the @ref{4d7,,set_start_method()} in
the @code{if __name__ == '__main__'} clause of the main module.  For
example:

@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{4d7,,set_start_method()} should not be used more than once in the
program.

Alternatively, you can use @ref{4d6,,get_context()} to obtain a context
object.  Context objects have the same API as the multiprocessing
module, and allow one to use multiple start methods in the same
program.

@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

Note that objects related to one context may not be compatible with
processes for a different context.  In particular, locks created using
the `fork' context cannot be passed to processes started using the
`spawn' or `forkserver' start methods.

Libraries using @code{multiprocessing} or
@ref{206,,ProcessPoolExecutor} should be designed to allow
their users to provide their own multiprocessing context.  Using a specific
context of your own within a library can lead to incompatibilities with the
rest of the library user’s application.  Always document if your library
requires a specific start method.

@cartouche
@quotation Προειδοποίηση 
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 Exchanging objects between processes,Synchronization between processes,Contexts and start methods,Introduction<7>
@anchor{library/multiprocessing exchanging-objects-between-processes}@anchor{3895}
@subsubsection Exchanging objects between processes


@code{multiprocessing} supports two types of communication channel between
processes:

`Queues'

@quotation

The @ref{1d85,,Queue} class is a near clone of @ref{1738,,queue.Queue}.  For
example:

@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 @code{multiprocessing} queue will be serialized.
@end quotation

`Pipes'

@quotation

The @ref{3896,,Pipe()} function returns a pair of connection objects connected by a
pipe which by default is duplex (two-way).  For example:

@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

The two connection objects returned by @ref{3896,,Pipe()} represent the two ends of
the pipe.  Each connection object has @code{send()} and
@code{recv()} methods (among others).  Note that data in a pipe
may become corrupted if two processes (or threads) try to read from or write
to the `same' end of the pipe at the same time.  Of course there is no risk
of corruption from processes using different ends of the pipe at the same
time.

The @code{send()} method serializes the object and
@code{recv()} re-creates the object.
@end quotation

@node Synchronization between processes,Sharing state between processes,Exchanging objects between processes,Introduction<7>
@anchor{library/multiprocessing synchronization-between-processes}@anchor{3897}
@subsubsection Synchronization between processes


@code{multiprocessing} contains equivalents of all the synchronization
primitives from @ref{f6,,threading}.  For instance one can use a lock to ensure
that only one process prints to standard output at a time:

@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

Without using the lock output from the different processes is liable to get all
mixed up.

@node Sharing state between processes,Using a pool of workers,Synchronization between processes,Introduction<7>
@anchor{library/multiprocessing sharing-state-between-processes}@anchor{3898}
@subsubsection Sharing state between processes


As mentioned above, when doing concurrent programming it is usually best to
avoid using shared state as far as possible.  This is particularly true when
using multiple processes.

However, if you really do need to use some shared data then
@code{multiprocessing} provides a couple of ways of doing so.

`Shared memory'

@quotation

Data can be stored in a shared memory map using @ref{3899,,Value} or
@ref{389a,,Array}.  For example, the following code

@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

will print

@example
3.1415927
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
@end example

The @code{'d'} and @code{'i'} arguments used when creating @code{num} and @code{arr} are
typecodes of the kind used by the @ref{8,,array} module: @code{'d'} indicates a
double precision float and @code{'i'} indicates a signed integer.  These shared
objects will be process and thread-safe.

For more flexibility in using shared memory one can use the
@ref{9e,,multiprocessing.sharedctypes} module which supports the creation of
arbitrary ctypes objects allocated from shared memory.
@end quotation

`Server process'

@quotation

A manager object returned by @ref{4dc,,Manager()} controls a server process which
holds Python objects and allows other processes to manipulate them using
proxies.

A manager returned by @ref{4dc,,Manager()} will support types
@ref{4d9,,list}, @ref{188,,dict}, @ref{42b,,set}, @ref{389b,,Namespace}, @ref{1a7c,,Lock},
@ref{1a7d,,RLock}, @ref{389c,,Semaphore}, @ref{389d,,BoundedSemaphore},
@ref{389e,,Condition}, @ref{1dfd,,Event}, @ref{389f,,Barrier},
@ref{1d85,,Queue}, @ref{3899,,Value} and @ref{389a,,Array}.  For example,

@example
from multiprocessing import Process, Manager

def f(d, l, s):
    d[1] = '1'
    d['2'] = 2
    d[0.25] = None
    l.reverse()
    s.add('a')
    s.add('b')

if __name__ == '__main__':
    with Manager() as manager:
        d = manager.dict()
        l = manager.list(range(10))
        s = manager.set()

        p = Process(target=f, args=(d, l, s))
        p.start()
        p.join()

        print(d)
        print(l)
        print(s)
@end example

will print

@example
@{0.25: None, 1: '1', '2': 2@}
[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
@{'a', 'b'@}
@end example

Server process managers are more flexible than using shared memory objects
because they can be made to support arbitrary object types.  Also, a single
manager can be shared by processes on different computers over a network.
They are, however, slower than using shared memory.
@end quotation

@node Using a pool of workers,,Sharing state between processes,Introduction<7>
@anchor{library/multiprocessing using-a-pool-of-workers}@anchor{38a0}
@subsubsection Using a pool of workers


The @ref{1315,,Pool} class represents a pool of worker
processes.  It has methods which allows tasks to be offloaded to the worker
processes in a few different ways.

For example:

@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

Note that the methods of a pool should only ever be used by the
process which created it.

@cartouche
@quotation Σημείωση 
Functionality within this package requires that the @code{__main__} module be
importable by the children. This is covered in @ref{3892,,Programming guidelines}
however it is worth pointing out here. This means that some examples, such
as the @ref{1315,,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

(If you try this it will actually output three full tracebacks
interleaved in a semi-random fashion, and then you may have to
stop the parent process somehow.)
@end quotation
@end cartouche

@node Reference<3>,Programming guidelines,Introduction<7>,multiprocessing — Process-based parallelism
@anchor{library/multiprocessing reference}@anchor{38a1}
@subsubsection Reference


The @code{multiprocessing} package mostly replicates the API of the
@ref{f6,,threading} module.

@menu
* Global start method:: 
* Process and exceptions:: 
* Pipes and Queues:: 
* Miscellaneous: Miscellaneous<3>. 
* Connection Objects:: 
* Synchronization primitives:: 
* Shared ctypes Objects:: 
* Managers:: 
* Proxy Objects:: 
* Process Pools:: 
* Listeners and Clients:: 
* Authentication keys:: 
* Logging: Logging<2>. 
* The multiprocessing.dummy module: The multiprocessing dummy module. 

@end menu

@node Global start method,Process and exceptions,,Reference<3>
@anchor{library/multiprocessing global-start-method}@anchor{38a2}@anchor{library/multiprocessing id1}@anchor{38a3}
@subsubsection Global start method


Python supports several ways to create and initialize a process.
The global start method sets the default mechanism for creating a process.

Several multiprocessing functions and methods that may also instantiate
certain objects will implicitly set the global start method to the system’s default,
if it hasn’t been set already. The global start method can only be set once.
If you need to change the start method from the system default, you must
proactively set the global start method before calling functions or methods,
or creating these objects.

@node Process and exceptions,Pipes and Queues,Global start method,Reference<3>
@anchor{library/multiprocessing process-and-exceptions}@anchor{38a4}
@subsubsection @code{Process} and exceptions


@geindex Process (κλάση σε multiprocessing)
@anchor{library/multiprocessing multiprocessing Process}@anchor{4de}
@deffn {Κλάση} multiprocessing.Process (group=None, target=None, name=None, args=(), kwargs=@{@}, *, daemon=None)

Process objects represent activity that is run in a separate process. The
@code{Process} class has equivalents of all the methods of
@ref{420,,threading.Thread}.

The constructor should always be called with keyword arguments. `group'
should always be @code{None}; it exists solely for compatibility with
@ref{420,,threading.Thread}.  `target' is the callable object to be invoked by
the @ref{3894,,run()} method.  It defaults to @code{None}, meaning nothing is
called. `name' is the process name (see @ref{38a5,,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{38a6,,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'.

If a subclass overrides the constructor, it must make sure it invokes the
base class constructor (@code{super().__init__()}) before doing anything else
to the process.

@cartouche
@quotation Σημείωση 
In general, all arguments to @code{Process} must be picklable.  This is
frequently observed when trying to create a @code{Process} or use a
@ref{206,,concurrent.futures.ProcessPoolExecutor} from a REPL with a
locally defined `target' function.

Passing a callable object defined in the current REPL session causes the
child process to die via an uncaught @ref{1a9,,AttributeError} exception when
starting as `target' must have been defined within an importable module
in order to be loaded during unpickling.

Example of this uncatchable error from the child:

@example
>>> import multiprocessing as mp
>>> def knigit():
...     print("Ni!")
...
>>> process = mp.Process(target=knigit)
>>> process.start()
>>> Traceback (most recent call last):
  File ".../multiprocessing/spawn.py", line ..., in spawn_main
  File ".../multiprocessing/spawn.py", line ..., in _main
AttributeError: module '__main__' has no attribute 'knigit'
>>> process
<SpawnProcess name='SpawnProcess-1' pid=379473 parent=378707 stopped exitcode=1>
@end example

See @ref{38a7,,The spawn and forkserver start methods}.  While this restriction is
not true if using the @code{"fork"} start method, as of Python @code{3.14} that
is no longer the default on any platform.  See
@ref{46d,,Contexts and start methods}.
See also gh-132898@footnote{https://github.com/python/cpython/issues/132898}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: Added the `daemon' parameter.


@geindex run() (μέθοδος της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process run}@anchor{3894}
@deffn {Μέθοδος} run ()

Method representing the process’s activity.

You may override this method in a subclass.  The standard @code{run()}
method invokes the callable object passed to the object’s constructor as
the target argument, if any, with sequential and keyword arguments taken
from the `args' and `kwargs' arguments, respectively.

Using a list or tuple as the `args' argument passed to @code{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() (μέθοδος της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process start}@anchor{1735}
@deffn {Μέθοδος} start ()

Start the process’s activity.

This must be called at most once per process object.  It arranges for the
object’s @ref{3894,,run()} method to be invoked in a separate process.
@end deffn

@geindex join() (μέθοδος της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process join}@anchor{1737}
@deffn {Μέθοδος} join ([timeout])

If the optional argument `timeout' is @code{None} (the default), the method
blocks until the process whose @code{join()} method is called terminates.
If `timeout' is a positive number, it blocks at most `timeout' seconds.
Note that the method returns @code{None} if its process terminates or if the
method times out.  Check the process’s @ref{38a8,,exitcode} to determine if
it terminated.

A process can be joined many times.

A process cannot join itself because this would cause a deadlock.  It is
an error to attempt to join a process before it has been started.
@end deffn

@geindex name (ιδιότητα της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process name}@anchor{38a5}
@deffn {Ιδιότητα} name

The process’s name.  The name is a string used for identification purposes
only.  It has no semantics.  Multiple processes may be given the same
name.

The initial name is set by the constructor.  If no explicit name is
provided to the constructor, a name of the form
“Process-N@w{[1]}:N@w{[2]}:…:N@w{[k]}” is constructed, where
each N@w{[k]} is the N-th child of its parent.
@end deffn

@geindex is_alive() (μέθοδος της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process is_alive}@anchor{1736}
@deffn {Μέθοδος} is_alive ()

Return whether the process is alive.

Roughly, a process object is alive from the moment the @ref{1735,,start()}
method returns until the child process terminates.
@end deffn

@geindex daemon (ιδιότητα της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process daemon}@anchor{38a6}
@deffn {Ιδιότητα} daemon

The process’s daemon flag, a Boolean value.  This must be set before
@ref{1735,,start()} is called.

The initial value is inherited from the creating process.

When a process exits, it attempts to terminate all of its daemonic child
processes.

Note that a daemonic process is not allowed to create child processes.
Otherwise a daemonic process would leave its children orphaned if it gets
terminated when its parent process exits. Additionally, these are `not'
Unix daemons or services, they are normal processes that will be
terminated (and not joined) if non-daemonic processes have exited.
@end deffn

In addition to the  @ref{420,,threading.Thread} API, @code{Process} objects
also support the following attributes and methods:

@geindex pid (ιδιότητα της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process pid}@anchor{38a9}
@deffn {Ιδιότητα} pid

Return the process ID.  Before the process is spawned, this will be
@code{None}.
@end deffn

@geindex exitcode (ιδιότητα της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process exitcode}@anchor{38a8}
@deffn {Ιδιότητα} exitcode

The child’s exit code.  This will be @code{None} if the process has not yet
terminated.

If the child’s @ref{3894,,run()} method returned normally, the exit code
will be 0.  If it terminated via @ref{4ff,,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{3894,,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 (ιδιότητα της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process authkey}@anchor{38aa}
@deffn {Ιδιότητα} authkey

The process’s authentication key (a byte string).

When @code{multiprocessing} is initialized the main process is assigned a
random string using @ref{931,,os.urandom()}.

When a @code{Process} object is created, it will inherit the
authentication key of its parent process, although this may be changed by
setting @ref{38aa,,authkey} to another byte string.

See @ref{38ab,,Authentication keys}.
@end deffn

@geindex sentinel (ιδιότητα της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process sentinel}@anchor{148d}
@deffn {Ιδιότητα} sentinel

A numeric handle of a system object which will become «ready» when
the process ends.

You can use this value if you want to wait on several events at
once using @ref{148b,,multiprocessing.connection.wait()}.  Otherwise
calling @ref{1737,,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{c9,,select} module.


Added in version 3.3.

@end deffn

@geindex interrupt() (μέθοδος της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process interrupt}@anchor{4dd}
@deffn {Μέθοδος} interrupt ()

Terminate the process. Works on POSIX using the @ref{4df,,SIGINT} signal.
Behavior on Windows is undefined.

By default, this terminates the child process by raising @ref{d96,,KeyboardInterrupt}.
This behavior can be altered by setting the respective signal handler in the child
process @ref{14e0,,signal.signal()} for @ref{4df,,SIGINT}.

Note: if the child process catches and discards @ref{d96,,KeyboardInterrupt}, the
process will not be terminated.

Note: the default behavior will also set @ref{38a8,,exitcode} to @code{1} as if an
uncaught exception was raised in the child process. To have a different
@code{exitcode} you may simply catch @ref{d96,,KeyboardInterrupt} and call
@code{exit(your_code)}.


Added in version 3.14.

@end deffn

@geindex terminate() (μέθοδος της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process terminate}@anchor{1a7f}
@deffn {Μέθοδος} terminate ()

Terminate the process.  On POSIX this is done using the @ref{1782,,SIGTERM} signal;
on Windows @code{TerminateProcess()} is used.  Note that exit handlers and
finally clauses, etc., will not be executed.

Note that descendant processes of the process will `not' be terminated –
they will simply become orphaned.

@cartouche
@quotation Προειδοποίηση 
If this method is used when the associated process is using a pipe or
queue then the pipe or queue is liable to become corrupted and may
become unusable by other process.  Similarly, if the process has
acquired a lock or semaphore etc. then terminating it is liable to
cause other processes to deadlock.
@end quotation
@end cartouche
@end deffn

@geindex kill() (μέθοδος της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process kill}@anchor{f15}
@deffn {Μέθοδος} kill ()

Same as @ref{1a7f,,terminate()} but using the @code{SIGKILL} signal on POSIX.


Added in version 3.7.

@end deffn

@geindex close() (μέθοδος της multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process close}@anchor{f14}
@deffn {Μέθοδος} close ()

Close the @code{Process} object, releasing all resources associated
with it.  @ref{277,,ValueError} is raised if the underlying process
is still running.  Once @code{close()} returns successfully, most
other methods and attributes of the @code{Process} object will
raise @code{ValueError}.


Added in version 3.7.

@end deffn

Note that the @ref{1735,,start()}, @ref{1737,,join()}, @ref{1736,,is_alive()},
@ref{1a7f,,terminate()} and @ref{38a8,,exitcode} methods should only be called by
the process that created the process object.

Example usage of some of the methods of @code{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{38ac}
@deffn {Εξαίρεση} multiprocessing.ProcessError

The base class of all @code{multiprocessing} exceptions.
@end deffn

@geindex BufferTooShort
@anchor{library/multiprocessing multiprocessing BufferTooShort}@anchor{38ad}
@deffn {Εξαίρεση} multiprocessing.BufferTooShort

Exception raised by @code{Connection.recv_bytes_into()} when the supplied
buffer object is too small for the message read.

If @code{e} is an instance of @code{BufferTooShort} then @code{e.args[0]} will give
the message as a byte string.
@end deffn

@geindex AuthenticationError
@anchor{library/multiprocessing multiprocessing AuthenticationError}@anchor{38ae}
@deffn {Εξαίρεση} multiprocessing.AuthenticationError

Raised when there is an authentication error.
@end deffn

@geindex TimeoutError
@anchor{library/multiprocessing multiprocessing TimeoutError}@anchor{38af}
@deffn {Εξαίρεση} multiprocessing.TimeoutError

Raised by methods with a timeout when the timeout expires.
@end deffn

@node Pipes and Queues,Miscellaneous<3>,Process and exceptions,Reference<3>
@anchor{library/multiprocessing pipes-and-queues}@anchor{38b0}
@subsubsection Pipes and Queues


When using multiple processes, one generally uses message passing for
communication between processes and avoids having to use any synchronization
primitives like locks.

For passing messages one can use @ref{3896,,Pipe()} (for a connection between two
processes) or a queue (which allows multiple producers and consumers).

The @ref{1d85,,Queue}, @ref{ce3,,SimpleQueue} and @ref{38b1,,JoinableQueue} types
are multi-producer, multi-consumer @abbr{FIFO}
queues modelled on the @ref{1738,,queue.Queue} class in the
standard library.  They differ in that @code{Queue} lacks the
@ref{38b2,,task_done()} and @ref{38b3,,join()} methods introduced
into Python 2.5’s @code{queue.Queue} class.

If you use @ref{38b1,,JoinableQueue} then you `must' call
@ref{38b4,,JoinableQueue.task_done()} for each task removed from the queue or else the
semaphore used to count the number of unfinished tasks may eventually overflow,
raising an exception.

One difference from other Python queue implementations, is that @code{multiprocessing}
queues serializes all objects that are put into them using @ref{ab,,pickle}.
The object returned by the get method is a re-created object that does not share
memory with the original object.

Note that one can also create a shared queue by using a manager object – see
@ref{38b5,,Managers}.

@cartouche
@quotation Σημείωση 
@code{multiprocessing} uses the usual @ref{38b6,,queue.Empty} and
@ref{38b7,,queue.Full} exceptions to signal a timeout.  They are not available in
the @code{multiprocessing} namespace so you need to import them from
@ref{be,,queue}.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
When an object is put on a queue, the object is pickled and a
background thread later flushes the pickled data to an underlying
pipe.  This has some consequences which are a little surprising,
but should not cause any practical difficulties – if they really
bother you then you can instead use a queue created with a
@ref{38b5,,manager}.


@enumerate 

@item 
After putting an object on an empty queue there may be an
infinitesimal delay before the queue’s @ref{1b7b,,empty()}
method returns @ref{ef5,,False} and @ref{38b8,,get_nowait()} can
return without raising @ref{38b6,,queue.Empty}.

@item 
If multiple processes are enqueuing objects, it is possible for
the objects to be received at the other end out-of-order.
However, objects enqueued by the same process will always be in
the expected order with respect to each other.
@end enumerate
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
If a process is killed using @ref{1a7f,,Process.terminate()} or @ref{170c,,os.kill()}
while it is trying to use a @ref{1d85,,Queue}, then the data in the queue is
likely to become corrupted.  This may cause any other process to get an
exception when it tries to use the queue later on.
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
As mentioned above, if a child process has put items on a queue (and it has
not used @ref{38b9,,JoinableQueue.cancel_join_thread}), then that process will
not terminate until all buffered items have been flushed to the pipe.

This means that if you try joining that process you may get a deadlock unless
you are sure that all items which have been put on the queue have been
consumed.  Similarly, if the child process is non-daemonic then the parent
process may hang on exit when it tries to join all its non-daemonic children.

Note that a queue created using a manager does not have this issue.  See
@ref{3892,,Programming guidelines}.
@end quotation
@end cartouche

For an example of the usage of queues for interprocess communication see
@ref{38ba,,Examples}.

@geindex Pipe() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing Pipe}@anchor{3896}
@deffn {Συνάρτηση} multiprocessing.Pipe (duplex=True)

Returns a pair @code{(conn1, conn2)} of
@ref{148c,,Connection} objects representing the
ends of a pipe.

If `duplex' is @code{True} (the default) then the pipe is bidirectional.  If
`duplex' is @code{False} then the pipe is unidirectional: @code{conn1} can only be
used for receiving messages and @code{conn2} can only be used for sending
messages.

The @code{send()} method serializes the object using
@ref{ab,,pickle} and the @code{recv()} re-creates the object.
@end deffn

@geindex Queue (κλάση σε multiprocessing)
@anchor{library/multiprocessing multiprocessing Queue}@anchor{1d85}
@deffn {Κλάση} multiprocessing.Queue ([maxsize])

Returns a process shared queue implemented using a pipe and a few
locks/semaphores.  When a process first puts an item on the queue a feeder
thread is started which transfers objects from a buffer into the pipe.

Instantiating this class may set the global start method. See
@ref{38a2,,Global start method} for more details.

The usual @ref{38b6,,queue.Empty} and @ref{38b7,,queue.Full} exceptions from the
standard library’s @ref{be,,queue} module are raised to signal timeouts.

@code{Queue} implements all the methods of @ref{1738,,queue.Queue} except for
@ref{38b2,,task_done()}, @ref{38b3,,join()}, and
@ref{745,,shutdown()}.

@geindex qsize() (μέθοδος της multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue qsize}@anchor{38bb}
@deffn {Μέθοδος} qsize ()

Return the approximate size of the queue.  Because of
multithreading/multiprocessing semantics, this number is not reliable.

Note that this may raise @ref{59a,,NotImplementedError} on platforms like
macOS where @code{sem_getvalue()} is not implemented.
@end deffn

@geindex empty() (μέθοδος της multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue empty}@anchor{1b7b}
@deffn {Μέθοδος} empty ()

Return @code{True} if the queue is empty, @code{False} otherwise.  Because of
multithreading/multiprocessing semantics, this is not reliable.

May raise an @ref{53c,,OSError} on closed queues. (not guaranteed)
@end deffn

@geindex full() (μέθοδος της multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue full}@anchor{38bc}
@deffn {Μέθοδος} full ()

Return @code{True} if the queue is full, @code{False} otherwise.  Because of
multithreading/multiprocessing semantics, this is not reliable.
@end deffn

@geindex put() (μέθοδος της multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue put}@anchor{200b}
@deffn {Μέθοδος} put (obj[, block[, timeout]])

Put obj into the queue.  If the optional argument `block' is @code{True}
(the default) 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{38b7,,queue.Full} exception if no
free slot was available within that time.  Otherwise (`block' is
@code{False}), put an item on the queue if a free slot is immediately
available, else raise the @code{queue.Full} exception (`timeout' is
ignored in that case).


Άλλαξε στην έκδοση 3.8: If the queue is closed, @ref{277,,ValueError} is raised instead of
@ref{a97,,AssertionError}.

@end deffn

@geindex put_nowait() (μέθοδος της multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue put_nowait}@anchor{38bd}
@deffn {Μέθοδος} put_nowait (obj)

Equivalent to @code{put(obj, False)}.
@end deffn

@geindex get() (μέθοδος της multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue get}@anchor{200c}
@deffn {Μέθοδος} get ([block[, timeout]])

Remove and return an item from the queue.  If optional args `block' is
@code{True} (the default) and `timeout' is @code{None} (the default), block if
necessary until an item is available.  If `timeout' is a positive number,
it blocks at most `timeout' seconds and raises the @ref{38b6,,queue.Empty}
exception if no item was available within that time.  Otherwise (block is
@code{False}), return an item if one is immediately available, else raise the
@code{queue.Empty} exception (`timeout' is ignored in that case).


Άλλαξε στην έκδοση 3.8: If the queue is closed, @ref{277,,ValueError} is raised instead of
@ref{53c,,OSError}.

@end deffn

@geindex get_nowait() (μέθοδος της multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue get_nowait}@anchor{38b8}
@deffn {Μέθοδος} get_nowait ()

Equivalent to @code{get(False)}.
@end deffn

@ref{1d85,,multiprocessing.Queue} has a few additional methods not found in
@ref{1738,,queue.Queue}.  These methods are usually unnecessary for most
code:

@geindex close() (μέθοδος της multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue close}@anchor{1d86}
@deffn {Μέθοδος} close ()

Close the queue: release internal resources.

A queue must not be used anymore after it is closed. For example,
@ref{200c,,get()}, @ref{200b,,put()} and @ref{1b7b,,empty()}
methods must no longer be called.

The background thread will quit once it has flushed all buffered
data to the pipe.  This is called automatically when the queue is garbage
collected.
@end deffn

@geindex join_thread() (μέθοδος της multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue join_thread}@anchor{38be}
@deffn {Μέθοδος} join_thread ()

Join the background thread.  This can only be used after @ref{1d86,,close()} has
been called.  It blocks until the background thread exits, ensuring that
all data in the buffer has been flushed to the pipe.

By default if a process is not the creator of the queue then on exit it
will attempt to join the queue’s background thread.  The process can call
@ref{38b9,,cancel_join_thread()} to make @code{join_thread()} do nothing.
@end deffn

@geindex cancel_join_thread() (μέθοδος της multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue cancel_join_thread}@anchor{38b9}
@deffn {Μέθοδος} cancel_join_thread ()

Prevent @ref{38be,,join_thread()} from blocking.  In particular, this prevents
the background thread from being joined automatically when the process
exits – see @code{join_thread()}.

A better name for this method might be
@code{allow_exit_without_flush()}.  It is likely to cause enqueued
data to be lost, and you almost certainly will not need to use it.
It is really only there if you need the current process to exit
immediately without waiting to flush enqueued data to the
underlying pipe, and you don’t care about lost data.
@end deffn

@cartouche
@quotation Σημείωση 
This class’s functionality requires a functioning shared semaphore
implementation on the host operating system. Without one, the
functionality in this class will be disabled, and attempts to
instantiate a @code{Queue} will result in an @ref{1bd,,ImportError}. See
bpo-3770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3770} for additional information.  The same holds true for any
of the specialized queue types listed below.
@end quotation
@end cartouche
@end deffn

@geindex SimpleQueue (κλάση σε multiprocessing)
@anchor{library/multiprocessing multiprocessing SimpleQueue}@anchor{ce3}
@deffn {Κλάση} multiprocessing.SimpleQueue

It is a simplified @ref{1d85,,Queue} type, very close to a locked @ref{3896,,Pipe}.

Instantiating this class may set the global start method. See
@ref{38a2,,Global start method} for more details.

@geindex close() (μέθοδος της multiprocessing.SimpleQueue)
@anchor{library/multiprocessing multiprocessing SimpleQueue close}@anchor{ce4}
@deffn {Μέθοδος} close ()

Close the queue: release internal resources.

A queue must not be used anymore after it is closed. For example,
@ref{38bf,,get()}, @ref{38c0,,put()} and @ref{1b7c,,empty()} methods must no longer be
called.


Added in version 3.9.

@end deffn

@geindex empty() (μέθοδος της multiprocessing.SimpleQueue)
@anchor{library/multiprocessing multiprocessing SimpleQueue empty}@anchor{1b7c}
@deffn {Μέθοδος} empty ()

Return @code{True} if the queue is empty, @code{False} otherwise.

Always raises an @ref{53c,,OSError} if the SimpleQueue is closed.
@end deffn

@geindex get() (μέθοδος της multiprocessing.SimpleQueue)
@anchor{library/multiprocessing multiprocessing SimpleQueue get}@anchor{38bf}
@deffn {Μέθοδος} get ()

Remove and return an item from the queue.
@end deffn

@geindex put() (μέθοδος της multiprocessing.SimpleQueue)
@anchor{library/multiprocessing multiprocessing SimpleQueue put}@anchor{38c0}
@deffn {Μέθοδος} put (item)

Put `item' into the queue.
@end deffn
@end deffn

@geindex JoinableQueue (κλάση σε multiprocessing)
@anchor{library/multiprocessing multiprocessing JoinableQueue}@anchor{38b1}
@deffn {Κλάση} multiprocessing.JoinableQueue ([maxsize])

@code{JoinableQueue}, a @ref{1d85,,Queue} subclass, is a queue which
additionally has @ref{38b4,,task_done()} and @ref{38c1,,join()} methods.

Instantiating this class may set the global start method. See
@ref{38a2,,Global start method} for more details.

@geindex task_done() (μέθοδος της multiprocessing.JoinableQueue)
@anchor{library/multiprocessing multiprocessing JoinableQueue task_done}@anchor{38b4}
@deffn {Μέθοδος} task_done ()

Indicate that a formerly enqueued task is complete. Used by queue
consumers.  For each @ref{200c,,get()} used to fetch a task, a subsequent
call to @code{task_done()} tells the queue that the processing on the task
is complete.

If a @ref{38b3,,join()} is currently blocking, it will resume when all
items have been processed (meaning that a @code{task_done()} call was
received for every item that had been @ref{200b,,put()} into the queue).

Raises a @ref{277,,ValueError} if called more times than there were items
placed in the queue.
@end deffn

@geindex join() (μέθοδος της multiprocessing.JoinableQueue)
@anchor{library/multiprocessing multiprocessing JoinableQueue join}@anchor{38c1}
@deffn {Μέθοδος} join ()

Block until all items in the queue have been gotten and processed.

The count of unfinished tasks goes up whenever an item is added to the
queue.  The count goes down whenever a consumer calls
@ref{38b4,,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{38b3,,join()} unblocks.
@end deffn
@end deffn

@node Miscellaneous<3>,Connection Objects,Pipes and Queues,Reference<3>
@anchor{library/multiprocessing miscellaneous}@anchor{38c2}
@subsubsection Miscellaneous


@geindex active_children() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing active_children}@anchor{38c3}
@deffn {Συνάρτηση} multiprocessing.active_children ()

Return list of all live children of the current process.

Calling this has the side effect of «joining» any processes which have
already finished.
@end deffn

@geindex cpu_count() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing cpu_count}@anchor{1319}
@deffn {Συνάρτηση} multiprocessing.cpu_count ()

Return the number of CPUs in the system.

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{6e0,,os.process_cpu_count()} (or @code{len(os.sched_getaffinity(0))}).

When the number of CPUs cannot be determined a @ref{59a,,NotImplementedError}
is raised.


@subsubheading Δείτε επίσης


@ref{6e1,,os.cpu_count()}
@ref{6e0,,os.process_cpu_count()}



Άλλαξε στην έκδοση 3.13: The return value can also be overridden using the
@ref{178,,-X cpu_count} flag or 
@geindex PYTHON_CPU_COUNT
@geindex μεταβλητή περιβάλλοντος; PYTHON_CPU_COUNT
@ref{721,,PYTHON_CPU_COUNT} as this is
merely a wrapper around the @ref{a5,,os} cpu count APIs.

@end deffn

@geindex current_process() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing current_process}@anchor{38c4}
@deffn {Συνάρτηση} multiprocessing.current_process ()

Return the @ref{4de,,Process} object corresponding to the current process.

An analogue of @ref{33e,,threading.current_thread()}.
@end deffn

@geindex parent_process() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing parent_process}@anchor{38c5}
@deffn {Συνάρτηση} multiprocessing.parent_process ()

Return the @ref{4de,,Process} object corresponding to the parent process of
the @ref{38c4,,current_process()}. For the main process, @code{parent_process} will
be @code{None}.


Added in version 3.8.

@end deffn

@geindex freeze_support() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing freeze_support}@anchor{1933}
@deffn {Συνάρτηση} multiprocessing.freeze_support ()

Add support for when a program which uses @code{multiprocessing} has been
frozen to produce an executable.  (Has been tested with `py2exe',
`PyInstaller' and `cx_Freeze'.)

One needs to call this function straight after the @code{if __name__ ==
'__main__'} line of the main module.  For example:

@example
from multiprocessing import Process, freeze_support

def f():
    print('hello world!')

if __name__ == '__main__':
    freeze_support()
    Process(target=f).start()
@end example

If the @code{freeze_support()} line is omitted then trying to run the frozen
executable will raise @ref{30d,,RuntimeError}.

Calling @code{freeze_support()} has no effect when the start method is not
`spawn'. In addition, if the module is being run normally by the Python
interpreter (the program has not been frozen), then @code{freeze_support()}
has no effect.
@end deffn

@geindex get_all_start_methods() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing get_all_start_methods}@anchor{1313}
@deffn {Συνάρτηση} 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{46d,,Contexts and start methods}.


Added in version 3.4.

@end deffn

@geindex get_context() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing get_context}@anchor{4d6}
@deffn {Συνάρτηση} multiprocessing.get_context (method=None)

Return a context object which has the same attributes as the
@code{multiprocessing} module.

If `method' is @code{None} then the default context is returned. Note that if
the global start method has not been set, this will set it to the system default
See @ref{38a2,,Global start method} for more details.
Otherwise `method' should be @code{'fork'}, @code{'spawn'},
@code{'forkserver'}.  @ref{277,,ValueError} is raised if the specified
start method is not available.  See @ref{46d,,Contexts and start methods}.


Added in version 3.4.

@end deffn

@geindex get_start_method() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing get_start_method}@anchor{1314}
@deffn {Συνάρτηση} multiprocessing.get_start_method (allow_none=False)

Return the name of start method used for starting processes.

If the global start method is not set and `allow_none' is @code{False}, the global start
method is set to the default, and its name is returned. See
@ref{38a2,,Global start method} for more details.

The return value can be @code{'fork'}, @code{'spawn'}, @code{'forkserver'}
or @code{None}.  See @ref{46d,,Contexts and start methods}.


Added in version 3.4.



Άλλαξε στην έκδοση 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. See bpo-33725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33725}.

@end deffn

@geindex set_executable() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing set_executable}@anchor{1d8c}
@deffn {Συνάρτηση} multiprocessing.set_executable (executable)

Set the path of the Python interpreter to use when starting a child process.
(By default @ref{3ac,,sys.executable} is used).  Embedders will probably need to
do something like

@example
set_executable(os.path.join(sys.exec_prefix, 'pythonw.exe'))
@end example

before they can create child processes.


Άλλαξε στην έκδοση 3.4: Now supported on POSIX when the @code{'spawn'} start method is used.



Άλλαξε στην έκδοση 3.11: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex set_forkserver_preload() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing set_forkserver_preload}@anchor{1969}
@deffn {Συνάρτηση} multiprocessing.set_forkserver_preload (module_names, *, on_error='ignore')

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. 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{4de,,Process}).

The `on_error' parameter controls how @ref{1bd,,ImportError} exceptions during
module preloading are handled: @code{"ignore"} (default) silently ignores
failures, @code{"warn"} causes the forkserver subprocess to emit an
@ref{907,,ImportWarning} to stderr, and @code{"fail"} causes the forkserver
subprocess to exit with the exception traceback on stderr, making
subsequent process creation fail with @ref{167e,,EOFError} or
@ref{11bf,,ConnectionError}.

Only meaningful when using the @code{'forkserver'} start method.
See @ref{46d,,Contexts and start methods}.


Added in version 3.4.



Άλλαξε στην έκδοση 3.15: Added the `on_error' parameter.

@end deffn

@geindex set_start_method() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing set_start_method}@anchor{4d7}
@deffn {Συνάρτηση} 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{30d,,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.

Note that this should be called at most once, and it should be
protected inside the @code{if __name__ == '__main__'} clause of the
main module.

See @ref{46d,,Contexts and start methods}.


Added in version 3.4.

@end deffn

@cartouche
@quotation Σημείωση 
@code{multiprocessing} contains no analogues of
@ref{33f,,threading.active_count()}, @ref{1e51,,threading.enumerate()},
@ref{c20,,threading.settrace()}, @ref{c21,,threading.setprofile()},
@ref{1504,,threading.Timer}, or @ref{1a87,,threading.local}.
@end quotation
@end cartouche

@node Connection Objects,Synchronization primitives,Miscellaneous<3>,Reference<3>
@anchor{library/multiprocessing connection-objects}@anchor{38c6}
@subsubsection Connection Objects


Connection objects allow the sending and receiving of picklable objects or
strings.  They can be thought of as message oriented connected sockets.

Connection objects are usually created using
@ref{3896,,Pipe} – see also
@ref{38c7,,Listeners and Clients}.

@geindex Connection (κλάση σε multiprocessing.connection)
@anchor{library/multiprocessing multiprocessing connection Connection}@anchor{148c}
@deffn {Κλάση} multiprocessing.connection.Connection

@geindex send() (μέθοδος της multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection send}@anchor{38c8}
@deffn {Μέθοδος} send (obj)

Send an object to the other end of the connection which should be read
using @ref{38c9,,recv()}.

The object must be picklable.  Very large pickles (approximately 32 MiB+,
though it depends on the OS) may raise a @ref{277,,ValueError} exception.
@end deffn

@geindex recv() (μέθοδος της multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection recv}@anchor{38c9}
@deffn {Μέθοδος} recv ()

Return an object sent from the other end of the connection using
@ref{38c8,,send()}.  Blocks until there is something to receive.  Raises
@ref{167e,,EOFError} if there is nothing left to receive
and the other end was closed.
@end deffn

@geindex fileno() (μέθοδος της multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection fileno}@anchor{38ca}
@deffn {Μέθοδος} fileno ()

Return the file descriptor or handle used by the connection.
@end deffn

@geindex close() (μέθοδος της multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection close}@anchor{38cb}
@deffn {Μέθοδος} close ()

Close the connection.

This is called automatically when the connection is garbage collected.
@end deffn

@geindex poll() (μέθοδος της multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection poll}@anchor{38cc}
@deffn {Μέθοδος} poll ([timeout])

Return whether there is any data available to be read.

If `timeout' is not specified then it will return immediately.  If
`timeout' is a number then this specifies the maximum time in seconds to
block.  If `timeout' is @code{None} then an infinite timeout is used.

Note that multiple connection objects may be polled at once by
using @ref{148b,,multiprocessing.connection.wait()}.
@end deffn

@geindex send_bytes() (μέθοδος της multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection send_bytes}@anchor{38cd}
@deffn {Μέθοδος} send_bytes (buf[, offset[, size]])

Send byte data from a @ref{436,,bytes-like object} as a complete message.

If `offset' is given then data is read from that position in `buf'.  If
`size' is given then that many bytes will be read from `buf'.  Very large
buffers (approximately 32 MiB+, though it depends on the OS) may raise a
@ref{277,,ValueError} exception
@end deffn

@geindex recv_bytes() (μέθοδος της multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection recv_bytes}@anchor{38ce}
@deffn {Μέθοδος} recv_bytes ([maxlength])

Return a complete message of byte data sent from the other end of the
connection as a string.  Blocks until there is something to receive.
Raises @ref{167e,,EOFError} if there is nothing left
to receive and the other end has closed.

If `maxlength' is specified and the message is longer than `maxlength'
then @ref{53c,,OSError} is raised and the connection will no longer be
readable.


Άλλαξε στην έκδοση 3.3: This function used to raise @ref{13fb,,IOError}, which is now an
alias of @ref{53c,,OSError}.

@end deffn

@geindex recv_bytes_into() (μέθοδος της multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection recv_bytes_into}@anchor{38cf}
@deffn {Μέθοδος} recv_bytes_into (buf[, offset])

Read into `buf' a complete message of byte data sent from the other end
of the connection and return the number of bytes in the message.  Blocks
until there is something to receive.  Raises
@ref{167e,,EOFError} if there is nothing left to receive and the other end was
closed.

`buf' must be a writable @ref{436,,bytes-like object}.  If
`offset' is given then the message will be written into the buffer from
that position.  Offset must be a non-negative integer less than the
length of `buf' (in bytes).

If the buffer is too short then a @code{BufferTooShort} exception is
raised and the complete message is available as @code{e.args[0]} where @code{e}
is the exception instance.
@end deffn


Άλλαξε στην έκδοση 3.3: Connection objects themselves can now be transferred between processes
using @ref{38c8,,Connection.send()} and @ref{38c9,,Connection.recv()}.

Connection objects also now support the context management protocol – see
@ref{2601,,Τύποι Διαχείρισης Περιεχομένου}.  @ref{28a4,,__enter__()} returns the
connection object, and @ref{28a5,,__exit__()} calls @ref{38cb,,close()}.

@end deffn

For example:

@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{38d0}
@cartouche
@quotation Προειδοποίηση 
The @ref{38c9,,Connection.recv()} method automatically unpickles the data it
receives, which can be a security risk unless you can trust the process
which sent the message.

Therefore, unless the connection object was produced using @code{Pipe()} you
should only use the @ref{38c9,,recv()} and @ref{38c8,,send()}
methods after performing some sort of authentication.  See
@ref{38ab,,Authentication keys}.
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
If a process is killed while it is trying to read or write to a pipe then
the data in the pipe is likely to become corrupted, because it may become
impossible to be sure where the message boundaries lie.
@end quotation
@end cartouche

@node Synchronization primitives,Shared ctypes Objects,Connection Objects,Reference<3>
@anchor{library/multiprocessing synchronization-primitives}@anchor{38d1}
@subsubsection Synchronization primitives


Generally synchronization primitives are not as necessary in a multiprocess
program as they are in a multithreaded program.  See the documentation for
@ref{f6,,threading} module.

Note that one can also create synchronization primitives by using a manager
object – see @ref{38b5,,Managers}.

@geindex Barrier (κλάση σε multiprocessing)
@anchor{library/multiprocessing multiprocessing Barrier}@anchor{389f}
@deffn {Κλάση} multiprocessing.Barrier (parties[, action[, timeout]])

A barrier object: a clone of @ref{158c,,threading.Barrier}.

Instantiating this class may set the global start method. See
@ref{38a2,,Global start method} for more details.


Added in version 3.3.

@end deffn

@geindex BoundedSemaphore (κλάση σε multiprocessing)
@anchor{library/multiprocessing multiprocessing BoundedSemaphore}@anchor{389d}
@deffn {Κλάση} multiprocessing.BoundedSemaphore ([value])

A bounded semaphore object: a close analog of
@ref{1502,,threading.BoundedSemaphore}.

Instantiating this class may set the global start method. See
@ref{38a2,,Global start method} for more details.

A solitary difference from its close analog exists: its @code{acquire} method’s
first argument is named `block', as is consistent with @ref{38d2,,Lock.acquire()}.

@geindex locked() (μέθοδος της multiprocessing.BoundedSemaphore)
@anchor{library/multiprocessing multiprocessing BoundedSemaphore locked}@anchor{38d3}
@deffn {Μέθοδος} locked ()

Return a boolean indicating whether this object is locked right now.


Added in version 3.14.

@end deffn

@cartouche
@quotation Σημείωση 
On macOS, this is indistinguishable from @ref{389c,,Semaphore} because
@code{sem_getvalue()} is not implemented on that platform.
@end quotation
@end cartouche
@end deffn

@geindex Condition (κλάση σε multiprocessing)
@anchor{library/multiprocessing multiprocessing Condition}@anchor{389e}
@deffn {Κλάση} multiprocessing.Condition ([lock])

A condition variable: an alias for @ref{1500,,threading.Condition}.

If `lock' is specified then it should be a @ref{1a7c,,Lock} or @ref{1a7d,,RLock}
object from @code{multiprocessing}.

Instantiating this class may set the global start method. See
@ref{38a2,,Global start method} for more details.


Άλλαξε στην έκδοση 3.3: The @ref{3876,,wait_for()} method was added.

@end deffn

@geindex Event (κλάση σε multiprocessing)
@anchor{library/multiprocessing multiprocessing Event}@anchor{1dfd}
@deffn {Κλάση} multiprocessing.Event

A clone of @ref{1503,,threading.Event}.

Instantiating this class may set the global start method. See
@ref{38a2,,Global start method} for more details.
@end deffn

@geindex Lock (κλάση σε multiprocessing)
@anchor{library/multiprocessing multiprocessing Lock}@anchor{1a7c}
@deffn {Κλάση} multiprocessing.Lock

A non-recursive lock object: a close analog of @ref{1a10,,threading.Lock}.
Once a process or thread has acquired a lock, subsequent attempts to
acquire it from any process or thread will block until it is released;
any process or thread may release it.  The concepts and behaviors of
@code{threading.Lock} as it applies to threads are replicated here in
@ref{1a7c,,multiprocessing.Lock} as it applies to either processes or threads,
except as noted.

Note that @code{Lock} is actually a factory function which returns an
instance of @code{multiprocessing.synchronize.Lock} initialized with a
default context.

Instantiating this class may set the global start method. See
@ref{38a2,,Global start method} for more details.

@code{Lock} supports the @ref{478,,context manager} protocol and thus may be
used in @ref{20a,,with} statements.

@geindex acquire() (μέθοδος της multiprocessing.Lock)
@anchor{library/multiprocessing multiprocessing Lock acquire}@anchor{38d2}
@deffn {Μέθοδος} acquire (block=True, timeout=None)

Acquire a lock, blocking or non-blocking.

With the `block' argument set to @code{True} (the default), the method call
will block until the lock is in an unlocked state, then set it to locked
and return @code{True}.  Note that the name of this first argument differs
from that in @ref{a87,,threading.Lock.acquire()}.

With the `block' argument set to @code{False}, the method call does not
block.  If the lock is currently in a locked state, return @code{False};
otherwise set the lock to a locked state and return @code{True}.

When invoked with a positive, floating-point value for `timeout', block
for at most the number of seconds specified by `timeout' as long as
the lock can not be acquired.  Invocations with a negative value for
`timeout' are equivalent to a `timeout' of zero.  Invocations with a
`timeout' value of @code{None} (the default) set the timeout period to
infinite.  Note that the treatment of negative or @code{None} values for
`timeout' differs from the implemented behavior in
@ref{a87,,threading.Lock.acquire()}.  The `timeout' argument has no practical
implications if the `block' argument is set to @code{False} and is thus
ignored.  Returns @code{True} if the lock has been acquired or @code{False} if
the timeout period has elapsed.
@end deffn

@geindex release() (μέθοδος της multiprocessing.Lock)
@anchor{library/multiprocessing multiprocessing Lock release}@anchor{38d4}
@deffn {Μέθοδος} release ()

Release a lock.  This can be called from any process or thread, not only
the process or thread which originally acquired the lock.

Behavior is the same as in @ref{1667,,threading.Lock.release()} except that
when invoked on an unlocked lock, a @ref{277,,ValueError} is raised.
@end deffn

@geindex locked() (μέθοδος της multiprocessing.Lock)
@anchor{library/multiprocessing multiprocessing Lock locked}@anchor{1a9e}
@deffn {Μέθοδος} locked ()

Return a boolean indicating whether this object is locked right now.


Added in version 3.14.

@end deffn
@end deffn

@geindex RLock (κλάση σε multiprocessing)
@anchor{library/multiprocessing multiprocessing RLock}@anchor{1a7d}
@deffn {Κλάση} multiprocessing.RLock

A recursive lock object: a close analog of @ref{2df,,threading.RLock}.  A
recursive lock must be released by the process or thread that acquired it.
Once a process or thread has acquired a recursive lock, the same process
or thread may acquire it again without blocking; that process or thread
must release it once for each time it has been acquired.

Note that @code{RLock} is actually a factory function which returns an
instance of @code{multiprocessing.synchronize.RLock} initialized with a
default context.

Instantiating this class may set the global start method. See
@ref{38a2,,Global start method} for more details.

@code{RLock} supports the @ref{478,,context manager} protocol and thus may be
used in @ref{20a,,with} statements.

@geindex acquire() (μέθοδος της multiprocessing.RLock)
@anchor{library/multiprocessing multiprocessing RLock acquire}@anchor{38d5}
@deffn {Μέθοδος} acquire (block=True, timeout=None)

Acquire a lock, blocking or non-blocking.

When invoked with the `block' argument set to @code{True}, block until the
lock is in an unlocked state (not owned by any process or thread) unless
the lock is already owned by the current process or thread.  The current
process or thread then takes ownership of the lock (if it does not
already have ownership) and the recursion level inside the lock increments
by one, resulting in a return value of @code{True}.  Note that there are
several differences in this first argument’s behavior compared to the
implementation of @ref{122c,,threading.RLock.acquire()}, starting with the name
of the argument itself.

When invoked with the `block' argument set to @code{False}, do not block.
If the lock has already been acquired (and thus is owned) by another
process or thread, the current process or thread does not take ownership
and the recursion level within the lock is not changed, resulting in
a return value of @code{False}.  If the lock is in an unlocked state, the
current process or thread takes ownership and the recursion level is
incremented, resulting in a return value of @code{True}.

Use and behaviors of the `timeout' argument are the same as in
@ref{38d2,,Lock.acquire()}.  Note that some of these behaviors of `timeout'
differ from the implemented behaviors in @ref{122c,,threading.RLock.acquire()}.
@end deffn

@geindex release() (μέθοδος της multiprocessing.RLock)
@anchor{library/multiprocessing multiprocessing RLock release}@anchor{38d6}
@deffn {Μέθοδος} release ()

Release a lock, decrementing the recursion level.  If after the
decrement the recursion level is zero, reset the lock to unlocked (not
owned by any process or thread) and if any other processes or 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 process or
thread.

Only call this method when the calling process or thread owns the lock.
An @ref{a97,,AssertionError} is raised if this method is called by a process
or thread other than the owner or if the lock is in an unlocked (unowned)
state.  Note that the type of exception raised in this situation
differs from the implemented behavior in @ref{3871,,threading.RLock.release()}.
@end deffn

@geindex locked() (μέθοδος της multiprocessing.RLock)
@anchor{library/multiprocessing multiprocessing RLock locked}@anchor{1a9f}
@deffn {Μέθοδος} locked ()

Return a boolean indicating whether this object is locked right now.


Added in version 3.14.

@end deffn
@end deffn

@geindex Semaphore (κλάση σε multiprocessing)
@anchor{library/multiprocessing multiprocessing Semaphore}@anchor{389c}
@deffn {Κλάση} multiprocessing.Semaphore ([value])

A semaphore object: a close analog of @ref{1501,,threading.Semaphore}.

Instantiating this class may set the global start method. See
@ref{38a2,,Global start method} for more details.

A solitary difference from its close analog exists: its @code{acquire} method’s
first argument is named `block', as is consistent with @ref{38d2,,Lock.acquire()}.

@geindex get_value() (μέθοδος της multiprocessing.Semaphore)
@anchor{library/multiprocessing multiprocessing Semaphore get_value}@anchor{38d7}
@deffn {Μέθοδος} get_value ()

Return the current value of semaphore.

Note that this may raise @ref{59a,,NotImplementedError} on platforms like
macOS where @code{sem_getvalue()} is not implemented.
@end deffn

@geindex locked() (μέθοδος της multiprocessing.Semaphore)
@anchor{library/multiprocessing multiprocessing Semaphore locked}@anchor{38d8}
@deffn {Μέθοδος} locked ()

Return a boolean indicating whether this object is locked right now.


Added in version 3.14.

@end deffn
@end deffn

@cartouche
@quotation Σημείωση 
On macOS, @code{sem_timedwait} is unsupported, so calling @code{acquire()} with
a timeout will emulate that function’s behavior using a sleeping loop.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Some of this package’s functionality requires a functioning shared semaphore
implementation on the host operating system. Without one, the
@code{multiprocessing.synchronize} module will be disabled, and attempts to
import it will result in an @ref{1bd,,ImportError}. See
bpo-3770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3770} for additional information.
@end quotation
@end cartouche

@node Shared ctypes Objects,Managers,Synchronization primitives,Reference<3>
@anchor{library/multiprocessing shared-ctypes-objects}@anchor{38d9}
@subsubsection Shared @code{ctypes} Objects


It is possible to create shared objects using shared memory which can be
inherited by child processes.

@geindex Value() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing Value}@anchor{3899}
@deffn {Συνάρτηση} multiprocessing.Value (typecode_or_type, *args, lock=True)

Return a @ref{2d,,ctypes} object allocated from shared memory.  By default the
return value is actually a synchronized wrapper for the object.  The object
itself can be accessed via the `value' attribute of a @ref{3899,,Value}.

`typecode_or_type' determines the type of the returned object: it is either a
ctypes type or a one character typecode of the kind used by the @ref{8,,array}
module.  `*args' is passed on to the constructor for the type.

If `lock' is @code{True} (the default) then a new recursive lock
object is created to synchronize access to the value.  If `lock' is
a @ref{1a7c,,Lock} or @ref{1a7d,,RLock} object then that will be used to
synchronize access to the value.  If `lock' is @code{False} then
access to the returned object will not be automatically protected
by a lock, so it will not necessarily be «process-safe».

Operations like @code{+=} which involve a read and write are not
atomic.  So if, for instance, you want to atomically increment a
shared value it is insufficient to just do

@example
counter.value += 1
@end example

Assuming the associated lock is recursive (which it is by default)
you can instead do

@example
with counter.get_lock():
    counter.value += 1
@end example

Note that `lock' is a keyword-only argument.
@end deffn

@geindex Array() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing Array}@anchor{389a}
@deffn {Συνάρτηση} multiprocessing.Array (typecode_or_type, size_or_initializer, *, lock=True)

Return a ctypes array allocated from shared memory.  By default the return
value is actually a synchronized wrapper for the array.

`typecode_or_type' determines the type of the elements of the returned array:
it is either a @ref{2a32,,ctypes type} or a one
character typecode of the kind used by the @ref{8,,array} module with the
exception of @code{'w'}, which is not supported.  In addition, the @code{'c'}
typecode is an alias for @ref{3535,,ctypes.c_char}.  If `size_or_initializer'
is an integer, then it determines the length of the array, and the array
will be initially zeroed. Otherwise, `size_or_initializer' is a sequence
which is used to initialize the array and whose length determines the length
of the array.

If `lock' is @code{True} (the default) then a new lock object is created to
synchronize access to the value.  If `lock' is a @ref{1a7c,,Lock} or
@ref{1a7d,,RLock} object then that will be used to synchronize access to the
value.  If `lock' is @code{False} then access to the returned object will not be
automatically protected by a lock, so it will not necessarily be
«process-safe».

Note that `lock' is a keyword only argument.

Note that an array of @ref{3535,,ctypes.c_char} has `value' and `raw'
attributes which allow one to use it to store and retrieve strings.
@end deffn

@menu
* The multiprocessing.sharedctypes module: The multiprocessing sharedctypes module. 

@end menu

@node The multiprocessing sharedctypes module,,,Shared ctypes Objects
@anchor{library/multiprocessing module-multiprocessing sharedctypes}@anchor{9e}@anchor{library/multiprocessing the-multiprocessing-sharedctypes-module}@anchor{38da}
@subsubsection The @code{multiprocessing.sharedctypes} module


@geindex module; multiprocessing.sharedctypes

The @code{multiprocessing.sharedctypes} module provides functions for allocating
@ref{2d,,ctypes} objects from shared memory which can be inherited by child
processes.

@cartouche
@quotation Σημείωση 
Although it is possible to store a pointer in shared memory remember that
this will refer to a location in the address space of a specific process.
However, the pointer is quite likely to be invalid in the context of a second
process and trying to dereference the pointer from the second process may
cause a crash.
@end quotation
@end cartouche

@geindex RawArray() (στη μονάδα multiprocessing.sharedctypes)
@anchor{library/multiprocessing multiprocessing sharedctypes RawArray}@anchor{1a39}
@deffn {Συνάρτηση} multiprocessing.sharedctypes.RawArray (typecode_or_type, size_or_initializer)

Return a ctypes array allocated from shared memory.

`typecode_or_type' determines the type of the elements of the returned array:
it is either a ctypes type or a one character typecode of the kind used by
the @ref{8,,array} module.  If `size_or_initializer' is an integer then it
determines the length of the array, and the array will be initially zeroed.
Otherwise `size_or_initializer' is a sequence which is used to initialize the
array and whose length determines the length of the array.

Note that setting and getting an element is potentially non-atomic – use
@ref{1a38,,Array()} instead to make sure that access is automatically synchronized
using a lock.
@end deffn

@geindex RawValue() (στη μονάδα multiprocessing.sharedctypes)
@anchor{library/multiprocessing multiprocessing sharedctypes RawValue}@anchor{1a3b}
@deffn {Συνάρτηση} multiprocessing.sharedctypes.RawValue (typecode_or_type, *args)

Return a ctypes object allocated from shared memory.

`typecode_or_type' determines the type of the returned object: it is either a
ctypes type or a one character typecode of the kind used by the @ref{8,,array}
module.  `*args' is passed on to the constructor for the type.

Note that setting and getting the value is potentially non-atomic – use
@ref{1a3a,,Value()} instead to make sure that access is automatically synchronized
using a lock.

Note that an array of @ref{3535,,ctypes.c_char} has @code{value} and @code{raw}
attributes which allow one to use it to store and retrieve strings – see
documentation for @ref{2d,,ctypes}.
@end deffn

@geindex Array() (στη μονάδα multiprocessing.sharedctypes)
@anchor{library/multiprocessing multiprocessing sharedctypes Array}@anchor{1a38}
@deffn {Συνάρτηση} multiprocessing.sharedctypes.Array (typecode_or_type, size_or_initializer, *, lock=True, ctx=None)

The same as @ref{1a39,,RawArray()} except that depending on the value of `lock' a
process-safe synchronization wrapper may be returned instead of a raw ctypes
array.

If `lock' is @code{True} (the default) then a new lock object is created to
synchronize access to the value.  If `lock' is a
@ref{1a7c,,Lock} or @ref{1a7d,,RLock} object
then that will be used to synchronize access to the
value.  If `lock' is @code{False} then access to the returned object will not be
automatically protected by a lock, so it will not necessarily be
«process-safe».

`ctx' is a context object, or @code{None} (use the current context). If @code{None},
calling this may set the global start method. See
@ref{38a2,,Global start method} for more details.

Note that `lock' and `ctx' are keyword-only parameters.
@end deffn

@geindex Value() (στη μονάδα multiprocessing.sharedctypes)
@anchor{library/multiprocessing multiprocessing sharedctypes Value}@anchor{1a3a}
@deffn {Συνάρτηση} multiprocessing.sharedctypes.Value (typecode_or_type, *args, lock=True, ctx=None)

The same as @ref{1a3b,,RawValue()} except that depending on the value of `lock' a
process-safe synchronization wrapper may be returned instead of a raw ctypes
object.

If `lock' is @code{True} (the default) then a new lock object is created to
synchronize access to the value.  If `lock' is a @ref{1a7c,,Lock} or
@ref{1a7d,,RLock} object then that will be used to synchronize access to the
value.  If `lock' is @code{False} then access to the returned object will not be
automatically protected by a lock, so it will not necessarily be
«process-safe».

`ctx' is a context object, or @code{None} (use the current context). If @code{None},
calling this may set the global start method. See
@ref{38a2,,Global start method} for more details.

Note that `lock' and `ctx' are keyword-only parameters.
@end deffn

@geindex copy() (στη μονάδα multiprocessing.sharedctypes)
@anchor{library/multiprocessing multiprocessing sharedctypes copy}@anchor{38db}
@deffn {Συνάρτηση} multiprocessing.sharedctypes.copy (obj)

Return a ctypes object allocated from shared memory which is a copy of the
ctypes object `obj'.
@end deffn

@geindex synchronized() (στη μονάδα multiprocessing.sharedctypes)
@anchor{library/multiprocessing multiprocessing sharedctypes synchronized}@anchor{11e4}
@deffn {Συνάρτηση} multiprocessing.sharedctypes.synchronized (obj, lock=None, ctx=None)

Return a process-safe wrapper object for a ctypes object which uses `lock' to
synchronize access.  If `lock' is @code{None} (the default) then a
@ref{1a7d,,multiprocessing.RLock} object is created automatically.

`ctx' is a context object, or @code{None} (use the current context). If @code{None},
calling this may set the global start method. See
@ref{38a2,,Global start method} for more details.

A synchronized wrapper will have two methods in addition to those of the
object it wraps: @code{get_obj()} returns the wrapped object and
@code{get_lock()} returns the lock object used for synchronization.

Note that accessing the ctypes object through the wrapper can be a lot slower
than accessing the raw ctypes object.


Άλλαξε στην έκδοση 3.5: Synchronized objects support the @ref{478,,context manager} protocol.

@end deffn

The table below compares the syntax for creating shared ctypes objects from
shared memory with the normal ctypes syntax.  (In the table @code{MyStruct} is some
subclass of @ref{47c,,ctypes.Structure}.)


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ctypes

@tab

sharedctypes using type

@tab

sharedctypes using 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


Below is an example where a number of ctypes objects are modified by a child
process:

@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

The results printed are

@example
49
0.1111111111111111
HELLO WORLD
[(3.515625, 39.0625), (33.0625, 4.0), (5.640625, 90.25)]
@end example

@node Managers,Proxy Objects,Shared ctypes Objects,Reference<3>
@anchor{library/multiprocessing managers}@anchor{38dc}@anchor{library/multiprocessing multiprocessing-managers}@anchor{38b5}
@subsubsection Managers


Managers provide a way to create data which can be shared between different
processes, including sharing over a network between processes running on
different machines. A manager object controls a server process which manages
`shared objects'.  Other processes can access the shared objects by using
proxies.

@geindex built-in function; multiprocessing.Manager()
@anchor{library/multiprocessing multiprocessing Manager}@anchor{4dc}
@deffn {Συνάρτηση} multiprocessing.Manager ()

Returns a started @ref{1ab8,,SyncManager} object which
can be used for sharing objects between processes.  The returned manager
object corresponds to a spawned child process and has methods which will
create shared objects and return corresponding proxies.
@end deffn

@geindex module; multiprocessing.managers
@anchor{library/multiprocessing module-multiprocessing managers}@anchor{9b}
Manager processes will be shutdown as soon as they are garbage collected or
their parent process exits.  The manager classes are defined in the
@ref{9b,,multiprocessing.managers} module:

@geindex BaseManager (κλάση σε multiprocessing.managers)
@anchor{library/multiprocessing multiprocessing managers BaseManager}@anchor{38dd}
@deffn {Κλάση} multiprocessing.managers.BaseManager (address=None, authkey=None, serializer='pickle', ctx=None, *, shutdown_timeout=1.0)

Create a BaseManager object.

Once created one should call @ref{38de,,start()} or @code{get_server().serve_forever()} to ensure
that the manager object refers to a started manager process.

`address' is the address on which the manager process listens for new
connections.  If `address' is @code{None} then an arbitrary one is chosen.

`authkey' is the authentication key which will be used to check the
validity of incoming connections to the server process.  If
`authkey' is @code{None} then @code{current_process().authkey} is used.
Otherwise `authkey' is used and it must be a byte string.

`serializer' must be @code{'pickle'} (use @ref{ab,,pickle} serialization) or
@code{'xmlrpclib'} (use @ref{137,,xmlrpc.client} serialization).

`ctx' is a context object, or @code{None} (use the current context). If @code{None},
calling this may set the global start method. See
@ref{38a2,,Global start method} for more details.

`shutdown_timeout' is a timeout in seconds used to wait until the process
used by the manager completes in the @ref{38df,,shutdown()} method. If the
shutdown times out, the process is terminated. If terminating the process
also times out, the process is killed.


Άλλαξε στην έκδοση 3.11: Added the `shutdown_timeout' parameter.


@geindex start() (μέθοδος της multiprocessing.managers.BaseManager)
@anchor{library/multiprocessing multiprocessing managers BaseManager start}@anchor{38de}
@deffn {Μέθοδος} start ([initializer[, initargs]])

Start a subprocess to start the manager.  If `initializer' is not @code{None}
then the subprocess will call @code{initializer(*initargs)} when it starts.
@end deffn

@geindex get_server() (μέθοδος της multiprocessing.managers.BaseManager)
@anchor{library/multiprocessing multiprocessing managers BaseManager get_server}@anchor{38e0}
@deffn {Μέθοδος} get_server ()

Returns a @code{Server} object which represents the actual server under
the control of the Manager. The @code{Server} object supports the
@code{serve_forever()} method:

@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} additionally has an @ref{38e1,,address} attribute.
@end deffn

@geindex connect() (μέθοδος της multiprocessing.managers.BaseManager)
@anchor{library/multiprocessing multiprocessing managers BaseManager connect}@anchor{38e2}
@deffn {Μέθοδος} connect ()

Connect a local manager object to a remote manager process:

@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() (μέθοδος της multiprocessing.managers.BaseManager)
@anchor{library/multiprocessing multiprocessing managers BaseManager shutdown}@anchor{38df}
@deffn {Μέθοδος} shutdown ()

Stop the process used by the manager.  This is only available if
@ref{38de,,start()} has been used to start the server process.

This can be called multiple times.
@end deffn

@geindex register() (μέθοδος της multiprocessing.managers.BaseManager)
@anchor{library/multiprocessing multiprocessing managers BaseManager register}@anchor{38e3}
@deffn {Μέθοδος} register (typeid[, callable[, proxytype[, exposed[, method_to_typeid[, create_method]]]]])

A classmethod which can be used for registering a type or callable with
the manager class.

`typeid' is a «type identifier» which is used to identify a particular
type of shared object.  This must be a string.

`callable' is a callable used for creating objects for this type
identifier.  If a manager instance will be connected to the
server using the @ref{38e2,,connect()} method, or if the
`create_method' argument is @code{False} then this can be left as
@code{None}.

`proxytype' is a subclass of @ref{38e4,,BaseProxy} which is used to create
proxies for shared objects with this `typeid'.  If @code{None} then a proxy
class is created automatically.

`exposed' is used to specify a sequence of method names which proxies for
this typeid should be allowed to access using
@ref{38e5,,BaseProxy._callmethod()}.  (If `exposed' is @code{None} then
@code{proxytype._exposed_} is used instead if it exists.)  In the case
where no exposed list is specified, all «public methods» of the shared
object will be accessible.  (Here a «public method» means any attribute
which has a @ref{961,,__call__()} method and whose name does not begin
with @code{'_'}.)

`method_to_typeid' is a mapping used to specify the return type of those
exposed methods which should return a proxy.  It maps method names to
typeid strings.  (If `method_to_typeid' is @code{None} then
@code{proxytype._method_to_typeid_} is used instead if it exists.)  If a
method’s name is not a key of this mapping or if the mapping is @code{None}
then the object returned by the method will be copied by value.

`create_method' determines whether a method should be created with name
`typeid' which can be used to tell the server process to create a new
shared object and return a proxy for it.  By default it is @code{True}.
@end deffn

@code{BaseManager} instances also have one read-only property:

@geindex address (ιδιότητα της multiprocessing.managers.BaseManager)
@anchor{library/multiprocessing multiprocessing managers BaseManager address}@anchor{38e1}
@deffn {Ιδιότητα} address

The address used by the manager.
@end deffn


Άλλαξε στην έκδοση 3.3: Manager objects support the context management protocol – see
@ref{2601,,Τύποι Διαχείρισης Περιεχομένου}.  @ref{28a4,,__enter__()} starts the
server process (if it has not already started) and then returns the
manager object.  @ref{28a5,,__exit__()} calls @ref{38df,,shutdown()}.

In previous versions @ref{28a4,,__enter__()} did not start the
manager’s server process if it was not already started.

@end deffn

@geindex SyncManager (κλάση σε multiprocessing.managers)
@anchor{library/multiprocessing multiprocessing managers SyncManager}@anchor{1ab8}
@deffn {Κλάση} multiprocessing.managers.SyncManager

A subclass of @ref{38dd,,BaseManager} which can be used for the synchronization
of processes.  Objects of this type are returned by
@ref{4dc,,multiprocessing.Manager()}.

Its methods create and return @ref{4d8,,Proxy Objects} for a
number of commonly used data types to be synchronized across processes.
This notably includes shared lists and dictionaries.

@geindex Barrier() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Barrier}@anchor{38e6}
@deffn {Μέθοδος} Barrier (parties[, action[, timeout]])

Create a shared @ref{158c,,threading.Barrier} object and return a
proxy for it.


Added in version 3.3.

@end deffn

@geindex BoundedSemaphore() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager BoundedSemaphore}@anchor{38e7}
@deffn {Μέθοδος} BoundedSemaphore ([value])

Create a shared @ref{1502,,threading.BoundedSemaphore} object and return a
proxy for it.
@end deffn

@geindex Condition() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Condition}@anchor{38e8}
@deffn {Μέθοδος} Condition ([lock])

Create a shared @ref{1500,,threading.Condition} object and return a proxy for
it.

If `lock' is supplied then it should be a proxy for a
@ref{1a10,,threading.Lock} or @ref{2df,,threading.RLock} object.


Άλλαξε στην έκδοση 3.3: The @ref{3876,,wait_for()} method was added.

@end deffn

@geindex Event() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Event}@anchor{38e9}
@deffn {Μέθοδος} Event ()

Create a shared @ref{1503,,threading.Event} object and return a proxy for it.
@end deffn

@geindex Lock() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Lock}@anchor{173b}
@deffn {Μέθοδος} Lock ()

Create a shared @ref{1a10,,threading.Lock} object and return a proxy for it.
@end deffn

@geindex Namespace() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Namespace}@anchor{38ea}
@deffn {Μέθοδος} Namespace ()

Create a shared @ref{389b,,Namespace} object and return a proxy for it.
@end deffn

@geindex Queue() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Queue}@anchor{341e}
@deffn {Μέθοδος} Queue ([maxsize])

Create a shared @ref{1738,,queue.Queue} object and return a proxy for it.
@end deffn

@geindex RLock() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager RLock}@anchor{173c}
@deffn {Μέθοδος} RLock ()

Create a shared @ref{2df,,threading.RLock} object and return a proxy for it.
@end deffn

@geindex Semaphore() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Semaphore}@anchor{173d}
@deffn {Μέθοδος} Semaphore ([value])

Create a shared @ref{1501,,threading.Semaphore} object and return a proxy for
it.
@end deffn

@geindex Array() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Array}@anchor{38eb}
@deffn {Μέθοδος} Array (typecode, sequence)

Create an array and return a proxy for it.
@end deffn

@geindex Value() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Value}@anchor{38ec}
@deffn {Μέθοδος} Value (typecode, value)

Create an object with a writable @code{value} attribute and return a proxy
for it.
@end deffn

@geindex dict() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager dict}@anchor{38ed}
@deffn {Μέθοδος} dict ()

@deffnx {Μέθοδος} dict (mapping)

@deffnx {Μέθοδος} dict (sequence)

Create a shared @ref{188,,dict} object and return a proxy for it.
@end deffn

@geindex list() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager list}@anchor{38ee}
@deffn {Μέθοδος} list ()

@deffnx {Μέθοδος} list (sequence)

Create a shared @ref{4d9,,list} object and return a proxy for it.
@end deffn

@geindex set() (μέθοδος της multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager set}@anchor{4db}
@deffn {Μέθοδος} set ()

@deffnx {Μέθοδος} set (sequence)

@deffnx {Μέθοδος} set (mapping)

Create a shared @ref{42b,,set} object and return a proxy for it.


Added in version 3.14: @ref{42b,,set} support was added.

@end deffn


Άλλαξε στην έκδοση 3.6: Shared objects are capable of being nested.  For example, a shared
container object such as a shared list can contain other shared objects
which will all be managed and synchronized by the @code{SyncManager}.

@end deffn

@geindex Namespace (κλάση σε multiprocessing.managers)
@anchor{library/multiprocessing multiprocessing managers Namespace}@anchor{389b}
@deffn {Κλάση} multiprocessing.managers.Namespace

A type that can register with @ref{1ab8,,SyncManager}.

A namespace object has no public methods, but does have writable attributes.
Its representation shows the values of its attributes.

However, when using a proxy for a namespace object, an attribute beginning
with @code{'_'} will be an attribute of the proxy and not an attribute of the
referent:

@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
* Customized managers:: 
* Using a remote manager:: 

@end menu

@node Customized managers,Using a remote manager,,Managers
@anchor{library/multiprocessing customized-managers}@anchor{38ef}
@subsubsection Customized managers


To create one’s own manager, one creates a subclass of @ref{38dd,,BaseManager} and
uses the @ref{38e3,,register()} classmethod to register new types or
callables with the manager class.  For example:

@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 Using a remote manager,,Customized managers,Managers
@anchor{library/multiprocessing using-a-remote-manager}@anchor{38f0}
@subsubsection Using a remote manager


It is possible to run a manager server on one machine and have clients use it
from other machines (assuming that the firewalls involved allow it).

Running the following commands creates a server for a single shared queue which
remote clients can access:

@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

One client can access the server as follows:

@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

Another client can also use it:

@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

Local processes can also access that queue, using the code from above on the
client to access it remotely:

@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 Proxy Objects,Process Pools,Managers,Reference<3>
@anchor{library/multiprocessing multiprocessing-proxy-objects}@anchor{4d8}@anchor{library/multiprocessing proxy-objects}@anchor{38f1}
@subsubsection Proxy Objects


A proxy is an object which `refers' to a shared object which lives (presumably)
in a different process.  The shared object is said to be the `referent' of the
proxy.  Multiple proxy objects may have the same referent.

A proxy object has methods which invoke corresponding methods of its referent
(although not every method of the referent will necessarily be available through
the proxy).  In this way, a proxy can be used just like its referent can:

@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

Notice that applying @ref{1df,,str()} to a proxy will return the representation of
the referent, whereas applying @ref{45b,,repr()} will return the representation of
the proxy.

An important feature of proxy objects is that they are picklable so they can be
passed between processes.  As such, a referent can contain
@ref{4d8,,Proxy Objects}.  This permits nesting of these managed
lists, dicts, and other @ref{4d8,,Proxy Objects}:

@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

Similarly, dict and list proxies may be nested inside one another:

@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

If standard (non-proxy) @ref{4d9,,list} or @ref{188,,dict} objects are contained
in a referent, modifications to those mutable values will not be propagated
through the manager because the proxy has no way of knowing when the values
contained within are modified.  However, storing a value in a container proxy
(which triggers a @code{__setitem__} on the proxy object) does propagate through
the manager and so to effectively modify such an item, one could re-assign the
modified value to the container proxy:

@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

This approach is perhaps less convenient than employing nested
@ref{4d8,,Proxy Objects} for most use cases but also
demonstrates a level of control over the synchronization.

@cartouche
@quotation Σημείωση 
The proxy types in @code{multiprocessing} do nothing to support comparisons
by value.  So, for instance, we have:

@example
>>> manager.list([1,2,3]) == [1,2,3]
False
@end example

One should just use a copy of the referent instead when making comparisons.
@end quotation
@end cartouche

@geindex BaseProxy (κλάση σε multiprocessing.managers)
@anchor{library/multiprocessing multiprocessing managers BaseProxy}@anchor{38e4}
@deffn {Κλάση} multiprocessing.managers.BaseProxy

Proxy objects are instances of subclasses of @code{BaseProxy}.

@geindex _callmethod() (μέθοδος της multiprocessing.managers.BaseProxy)
@anchor{library/multiprocessing multiprocessing managers BaseProxy _callmethod}@anchor{38e5}
@deffn {Μέθοδος} _callmethod (methodname[, args[, kwds]])

Call and return the result of a method of the proxy’s referent.

If @code{proxy} is a proxy whose referent is @code{obj} then the expression

@example
proxy._callmethod(methodname, args, kwds)
@end example

will evaluate the expression

@example
getattr(obj, methodname)(*args, **kwds)
@end example

in the manager’s process.

The returned value will be a copy of the result of the call or a proxy to
a new shared object – see documentation for the `method_to_typeid'
argument of @ref{38e3,,BaseManager.register()}.

If an exception is raised by the call, then is re-raised by
@code{_callmethod()}.  If some other exception is raised in the manager’s
process then this is converted into a @code{RemoteError} exception and is
raised by @code{_callmethod()}.

Note in particular that an exception will be raised if `methodname' has
not been `exposed'.

An example of the usage of @code{_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() (μέθοδος της multiprocessing.managers.BaseProxy)
@anchor{library/multiprocessing multiprocessing managers BaseProxy _getvalue}@anchor{38f2}
@deffn {Μέθοδος} _getvalue ()

Return a copy of the referent.

If the referent is unpicklable then this will raise an exception.
@end deffn

@geindex __repr__() (μέθοδος της multiprocessing.managers.BaseProxy)
@anchor{library/multiprocessing multiprocessing managers BaseProxy __repr__}@anchor{38f3}
@deffn {Μέθοδος} __repr__ ()

Return a representation of the proxy object.
@end deffn

@geindex __str__() (μέθοδος της multiprocessing.managers.BaseProxy)
@anchor{library/multiprocessing multiprocessing managers BaseProxy __str__}@anchor{38f4}
@deffn {Μέθοδος} __str__ ()

Return the representation of the referent.
@end deffn
@end deffn

@menu
* Cleanup: Cleanup<2>. 

@end menu

@node Cleanup<2>,,,Proxy Objects
@anchor{library/multiprocessing cleanup}@anchor{38f5}
@subsubsection Cleanup


A proxy object uses a weakref callback so that when it gets garbage collected it
deregisters itself from the manager which owns its referent.

A shared object gets deleted from the manager process when there are no longer
any proxies referring to it.

@node Process Pools,Listeners and Clients,Proxy Objects,Reference<3>
@anchor{library/multiprocessing module-multiprocessing pool}@anchor{9c}@anchor{library/multiprocessing process-pools}@anchor{38f6}
@subsubsection Process Pools


@geindex module; multiprocessing.pool

One can create a pool of processes which will carry out tasks submitted to it
with the @ref{1315,,Pool} class.

@geindex Pool (κλάση σε multiprocessing.pool)
@anchor{library/multiprocessing multiprocessing pool Pool}@anchor{1315}
@deffn {Κλάση} multiprocessing.pool.Pool ([processes[, initializer[, initargs[, maxtasksperchild[, context]]]]])

A process pool object which controls a pool of worker processes to which jobs
can be submitted.  It supports asynchronous results with timeouts and
callbacks and has a parallel map implementation.

`processes' is the number of worker processes to use.  If `processes' is
@code{None} then the number returned by @ref{6e0,,os.process_cpu_count()} is used.

If `initializer' is not @code{None} then each worker process will call
@code{initializer(*initargs)} when it starts.

`maxtasksperchild' is the number of tasks a worker process can complete
before it will exit and be replaced with a fresh worker process, to enable
unused resources to be freed. The default `maxtasksperchild' is @code{None}, which
means worker processes will live as long as the pool.

`context' can be used to specify the context used for starting
the worker processes.  Usually a pool is created using the
function @code{multiprocessing.Pool()} or the @ref{1315,,Pool()} method
of a context object.  In both cases `context' is set
appropriately. If @code{None}, calling this function will have the side effect
of setting the current global start method if it has not been set already.
See the @code{get_context()} function.

Note that the methods of the pool object should only be called by
the process which created the pool.

@cartouche
@quotation Προειδοποίηση 
@ref{9c,,multiprocessing.pool} objects have internal resources that need to be
properly managed (like any other resource) by using the pool as a context manager
or by calling @ref{38f7,,close()} and @ref{38f8,,terminate()} manually. Failure to do this
can lead to the process hanging on finalization.

Note that it is `not correct' to rely on the garbage collector to destroy the pool
as CPython does not assure that the finalizer of the pool will be called
(see @ref{13a6,,object.__del__()} for more information).
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.2: Added the `maxtasksperchild' parameter.



Άλλαξε στην έκδοση 3.4: Added the `context' parameter.



Άλλαξε στην έκδοση 3.13: `processes' uses @ref{6e0,,os.process_cpu_count()} by default, instead of
@ref{6e1,,os.cpu_count()}.


@cartouche
@quotation Σημείωση 
Worker processes within a @code{Pool} typically live for the complete
duration of the Pool’s work queue. A frequent pattern found in other
systems (such as Apache, mod_wsgi, etc) to free resources held by
workers is to allow a worker within a pool to complete only a set
amount of work before exiting, being cleaned up and a new
process spawned to replace the old one. The `maxtasksperchild'
argument to the @code{Pool} exposes this ability to the end user.
@end quotation
@end cartouche

@geindex apply() (μέθοδος της multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool apply}@anchor{1739}
@deffn {Μέθοδος} apply (func[, args[, kwds]])

Call `func' with arguments `args' and keyword arguments `kwds'.  It blocks
until the result is ready. Given this blocks, @ref{173a,,apply_async()} is
better suited for performing work in parallel. Additionally, `func'
is only executed in one of the workers of the pool.
@end deffn

@geindex apply_async() (μέθοδος της multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool apply_async}@anchor{173a}
@deffn {Μέθοδος} apply_async (func[, args[, kwds[, callback[, error_callback]]]])

A variant of the @ref{1739,,apply()} method which returns a
@ref{38f9,,AsyncResult} object.

If `callback' is specified then it should be a callable which accepts a
single argument.  When the result becomes ready `callback' is applied to
it, that is unless the call failed, in which case the `error_callback'
is applied instead.

If `error_callback' is specified then it should be a callable which
accepts a single argument.  If the target function fails, then
the `error_callback' is called with the exception instance.

Callbacks should complete immediately since otherwise the thread which
handles the results will get blocked.
@end deffn

@geindex map() (μέθοδος της multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool map}@anchor{1491}
@deffn {Μέθοδος} map (func, iterable[, chunksize])

A parallel equivalent of the @ref{43e,,map()} built-in function (it supports only
one `iterable' argument though, for multiple iterables see @ref{148e,,starmap()}).
It blocks until the result is ready.

This method chops the iterable into a number of chunks which it submits to
the process pool as separate tasks.  The (approximate) size of these
chunks can be specified by setting `chunksize' to a positive integer.

Note that it may cause high memory usage for very long iterables. Consider
using @ref{38fa,,imap()} or @ref{38fb,,imap_unordered()} with explicit `chunksize'
option for better efficiency.
@end deffn

@geindex map_async() (μέθοδος της multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool map_async}@anchor{1492}
@deffn {Μέθοδος} map_async (func, iterable[, chunksize[, callback[, error_callback]]])

A variant of the @ref{1491,,map()} method which returns a
@ref{38f9,,AsyncResult} object.

If `callback' is specified then it should be a callable which accepts a
single argument.  When the result becomes ready `callback' is applied to
it, that is unless the call failed, in which case the `error_callback'
is applied instead.

If `error_callback' is specified then it should be a callable which
accepts a single argument.  If the target function fails, then
the `error_callback' is called with the exception instance.

Callbacks should complete immediately since otherwise the thread which
handles the results will get blocked.
@end deffn

@geindex imap() (μέθοδος της multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool imap}@anchor{38fa}
@deffn {Μέθοδος} imap (func, iterable[, chunksize])

A lazier version of @ref{1491,,map()}.

The `chunksize' argument is the same as the one used by the @ref{1491,,map()}
method.  For very long iterables using a large value for `chunksize' can
make the job complete `much' faster than using the default value of
@code{1}.

Also if `chunksize' is @code{1} then the @code{next()} method of the iterator
returned by the @code{imap()} method has an optional `timeout' parameter:
@code{next(timeout)} will raise @ref{38af,,multiprocessing.TimeoutError} if the
result cannot be returned within `timeout' seconds.
@end deffn

@geindex imap_unordered() (μέθοδος της multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool imap_unordered}@anchor{38fb}
@deffn {Μέθοδος} imap_unordered (func, iterable[, chunksize])

The same as @ref{38fa,,imap()} except that the ordering of the results from the
returned iterator should be considered arbitrary.  (Only when there is
only one worker process is the order guaranteed to be «correct».)
@end deffn

@geindex starmap() (μέθοδος της multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool starmap}@anchor{148e}
@deffn {Μέθοδος} starmap (func, iterable[, chunksize])

Like @ref{1491,,map()} except that the
elements of the `iterable' are expected to be iterables that are
unpacked as arguments.

Hence an `iterable' of @code{[(1,2), (3, 4)]} results in @code{[func(1,2),
func(3,4)]}.


Added in version 3.3.

@end deffn

@geindex starmap_async() (μέθοδος της multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool starmap_async}@anchor{148f}
@deffn {Μέθοδος} starmap_async (func, iterable[, chunksize[, callback[, error_callback]]])

A combination of @ref{148e,,starmap()} and @ref{1492,,map_async()} that iterates over
`iterable' of iterables and calls `func' with the iterables unpacked.
Returns a result object.


Added in version 3.3.

@end deffn

@geindex close() (μέθοδος της multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool close}@anchor{38f7}
@deffn {Μέθοδος} close ()

Prevents any more tasks from being submitted to the pool.  Once all the
tasks have been completed the worker processes will exit.
@end deffn

@geindex terminate() (μέθοδος της multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool terminate}@anchor{38f8}
@deffn {Μέθοδος} terminate ()

Stops the worker processes immediately without completing outstanding
work.  When the pool object is garbage collected @code{terminate()} will be
called immediately.
@end deffn

@geindex join() (μέθοδος της multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool join}@anchor{38fc}
@deffn {Μέθοδος} join ()

Wait for the worker processes to exit.  One must call @ref{38f7,,close()} or
@ref{38f8,,terminate()} before using @code{join()}.
@end deffn


Άλλαξε στην έκδοση 3.3: Pool objects now support the context management protocol – see
@ref{2601,,Τύποι Διαχείρισης Περιεχομένου}.  @ref{28a4,,__enter__()} returns the
pool object, and @ref{28a5,,__exit__()} calls @ref{38f8,,terminate()}.

@end deffn

@geindex AsyncResult (κλάση σε multiprocessing.pool)
@anchor{library/multiprocessing multiprocessing pool AsyncResult}@anchor{38f9}
@deffn {Κλάση} multiprocessing.pool.AsyncResult

The class of the result returned by @ref{173a,,Pool.apply_async()} and
@ref{1492,,Pool.map_async()}.

@geindex get() (μέθοδος της multiprocessing.pool.AsyncResult)
@anchor{library/multiprocessing multiprocessing pool AsyncResult get}@anchor{38fd}
@deffn {Μέθοδος} get ([timeout])

Return the result when it arrives.  If `timeout' is not @code{None} and the
result does not arrive within `timeout' seconds then
@ref{38af,,multiprocessing.TimeoutError} is raised.  If the remote call raised
an exception then that exception will be reraised by @code{get()}.
@end deffn

@geindex wait() (μέθοδος της multiprocessing.pool.AsyncResult)
@anchor{library/multiprocessing multiprocessing pool AsyncResult wait}@anchor{38fe}
@deffn {Μέθοδος} wait ([timeout])

Wait until the result is available or until `timeout' seconds pass.
@end deffn

@geindex ready() (μέθοδος της multiprocessing.pool.AsyncResult)
@anchor{library/multiprocessing multiprocessing pool AsyncResult ready}@anchor{38ff}
@deffn {Μέθοδος} ready ()

Return whether the call has completed.
@end deffn

@geindex successful() (μέθοδος της multiprocessing.pool.AsyncResult)
@anchor{library/multiprocessing multiprocessing pool AsyncResult successful}@anchor{3900}
@deffn {Μέθοδος} successful ()

Return whether the call completed without raising an exception.  Will
raise @ref{277,,ValueError} if the result is not ready.


Άλλαξε στην έκδοση 3.7: If the result is not ready, @ref{277,,ValueError} is raised instead of
@ref{a97,,AssertionError}.

@end deffn
@end deffn

The following example demonstrates the use of a pool:

@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 Listeners and Clients,Authentication keys,Process Pools,Reference<3>
@anchor{library/multiprocessing listeners-and-clients}@anchor{3901}@anchor{library/multiprocessing module-multiprocessing connection}@anchor{99}@anchor{library/multiprocessing multiprocessing-listeners-clients}@anchor{38c7}
@subsubsection Listeners and Clients


@geindex module; multiprocessing.connection

Usually message passing between processes is done using queues or by using
@ref{148c,,Connection} objects returned by
@ref{3896,,Pipe()}.

However, the @code{multiprocessing.connection} module allows some extra
flexibility.  It basically gives a high level message oriented API for dealing
with sockets or Windows named pipes.  It also has support for `digest
authentication' using the @ref{6d,,hmac} module, and for polling
multiple connections at the same time.

@geindex deliver_challenge() (στη μονάδα multiprocessing.connection)
@anchor{library/multiprocessing multiprocessing connection deliver_challenge}@anchor{3902}
@deffn {Συνάρτηση} multiprocessing.connection.deliver_challenge (connection, authkey)

Send a randomly generated message to the other end of the connection and wait
for a reply.

If the reply matches the digest of the message using `authkey' as the key
then a welcome message is sent to the other end of the connection.  Otherwise
@ref{38ae,,AuthenticationError} is raised.
@end deffn

@geindex answer_challenge() (στη μονάδα multiprocessing.connection)
@anchor{library/multiprocessing multiprocessing connection answer_challenge}@anchor{3903}
@deffn {Συνάρτηση} multiprocessing.connection.answer_challenge (connection, authkey)

Receive a message, calculate the digest of the message using `authkey' as the
key, and then send the digest back.

If a welcome message is not received, then
@ref{38ae,,AuthenticationError} is raised.
@end deffn

@geindex Client() (στη μονάδα multiprocessing.connection)
@anchor{library/multiprocessing multiprocessing connection Client}@anchor{3904}
@deffn {Συνάρτηση} multiprocessing.connection.Client (address[, family[, authkey]])

Attempt to set up a connection to the listener which is using address
`address', returning a @ref{148c,,Connection}.

The type of the connection is determined by `family' argument, but this can
generally be omitted since it can usually be inferred from the format of
`address'. (See @ref{3905,,Address Formats})

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{38ae,,AuthenticationError} is raised if authentication fails.
See @ref{38ab,,Authentication keys}.
@end deffn

@geindex Listener (κλάση σε multiprocessing.connection)
@anchor{library/multiprocessing multiprocessing connection Listener}@anchor{1c2b}
@deffn {Κλάση} multiprocessing.connection.Listener ([address[, family[, backlog[, authkey]]]])

A wrapper for a bound socket or Windows named pipe which is “listening” for
connections.

`address' is the address to be used by the bound socket or named pipe of the
listener object.

@cartouche
@quotation Σημείωση 
If an address of “0.0.0.0” is used, the address will not be a connectable
end point on Windows. If you require a connectable end-point,
you should use “127.0.0.1”.
@end quotation
@end cartouche

`family' is the type of socket (or named pipe) to use.  This can be one of
the strings @code{'AF_INET'} (for a TCP socket), @code{'AF_UNIX'} (for a Unix
domain socket) or @code{'AF_PIPE'} (for a Windows named pipe).  Of these only
the first is guaranteed to be available.  If `family' is @code{None} then the
family is inferred from the format of `address'.  If `address' is also
@code{None} then a default is chosen.  This default is the family which is
assumed to be the fastest available.  See
@ref{3905,,Address Formats}.  Note that if `family' is
@code{'AF_UNIX'} and address is @code{None} then the socket will be created in a
private temporary directory created using @ref{2ef1,,tempfile.mkstemp()}.

If the listener object uses a socket then `backlog' (1 by default) is passed
to the @ref{120f,,listen()} method of the socket once it has been
bound.

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{38ae,,AuthenticationError} is raised if authentication fails.
See @ref{38ab,,Authentication keys}.

@geindex accept() (μέθοδος της multiprocessing.connection.Listener)
@anchor{library/multiprocessing multiprocessing connection Listener accept}@anchor{1be8}
@deffn {Μέθοδος} accept ()

Accept a connection on the bound socket or named pipe of the listener
object and return a @ref{148c,,Connection} object.
If authentication is attempted and fails, then
@ref{38ae,,AuthenticationError} is raised.
@end deffn

@geindex close() (μέθοδος της multiprocessing.connection.Listener)
@anchor{library/multiprocessing multiprocessing connection Listener close}@anchor{3906}
@deffn {Μέθοδος} close ()

Close the bound socket or named pipe of the listener object.  This is
called automatically when the listener is garbage collected.  However it
is advisable to call it explicitly.
@end deffn

Listener objects have the following read-only properties:

@geindex address (ιδιότητα της multiprocessing.connection.Listener)
@anchor{library/multiprocessing multiprocessing connection Listener address}@anchor{3907}
@deffn {Ιδιότητα} address

The address which is being used by the Listener object.
@end deffn

@geindex last_accepted (ιδιότητα της multiprocessing.connection.Listener)
@anchor{library/multiprocessing multiprocessing connection Listener last_accepted}@anchor{3908}
@deffn {Ιδιότητα} last_accepted

The address from which the last accepted connection came.  If this is
unavailable then it is @code{None}.
@end deffn


Άλλαξε στην έκδοση 3.3: Listener objects now support the context management protocol – see
@ref{2601,,Τύποι Διαχείρισης Περιεχομένου}.  @ref{28a4,,__enter__()} returns the
listener object, and @ref{28a5,,__exit__()} calls @ref{3906,,close()}.

@end deffn

@geindex wait() (στη μονάδα multiprocessing.connection)
@anchor{library/multiprocessing multiprocessing connection wait}@anchor{148b}
@deffn {Συνάρτηση} multiprocessing.connection.wait (object_list, timeout=None)

Wait till an object in `object_list' is ready.  Returns the list of
those objects in `object_list' which are ready.  If `timeout' is a
float then the call blocks for at most that many seconds.  If
`timeout' is @code{None} then it will block for an unlimited period.
A negative timeout is equivalent to a zero timeout.

For both POSIX and Windows, an object can appear in `object_list' if
it is


@itemize *

@item 
a readable @ref{148c,,Connection} object;

@item 
a connected and readable @ref{115a,,socket.socket} object; or

@item 
the @ref{148d,,sentinel} attribute of a
@ref{4de,,Process} object.
@end itemize

A connection or socket object is ready when there is data available
to be read from it, or the other end has been closed.

`POSIX': @code{wait(object_list, timeout)} almost equivalent
@code{select.select(object_list, [], [], timeout)}.  The difference is
that, if @ref{1159,,select.select()} is interrupted by a signal, it can
raise @ref{53c,,OSError} with an error number of @code{EINTR}, whereas
@code{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{19b2,,fileno()} method which returns a
socket handle or pipe handle.  (Note that pipe handles and socket
handles are `not' waitable handles.)


Added in version 3.3.

@end deffn

`Examples'

The following server code creates a listener which uses @code{'secret password'} as
an authentication key.  It then waits for a connection and sends some data to
the 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

The following code connects to the server and receives some data from the
server:

@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

The following code uses @ref{148b,,wait()} to
wait for messages from multiple processes at once:

@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
* Address Formats:: 

@end menu

@node Address Formats,,,Listeners and Clients
@anchor{library/multiprocessing address-formats}@anchor{3909}@anchor{library/multiprocessing multiprocessing-address-formats}@anchor{3905}
@subsubsection Address Formats



@itemize *

@item 
An @code{'AF_INET'} address is a tuple of the form @code{(hostname, port)} where
`hostname' is a string and `port' is an integer.

@item 
An @code{'AF_UNIX'} address is a string representing a filename on the
filesystem.

@item 
An @code{'AF_PIPE'} address is a string of the form
@code{r'\\.\pipe\@var{PipeName}'}.  To use @ref{3904,,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

Note that any string beginning with two backslashes is assumed by default to be
an @code{'AF_PIPE'} address rather than an @code{'AF_UNIX'} address.

@node Authentication keys,Logging<2>,Listeners and Clients,Reference<3>
@anchor{library/multiprocessing authentication-keys}@anchor{390a}@anchor{library/multiprocessing multiprocessing-auth-keys}@anchor{38ab}
@subsubsection Authentication keys


When one uses @ref{38c9,,Connection.recv}, the
data received is automatically
unpickled. Unfortunately unpickling data from an untrusted source is a security
risk. Therefore @ref{1c2b,,Listener} and @ref{3904,,Client()} use the @ref{6d,,hmac} module
to provide digest authentication.

An authentication key is a byte string which can be thought of as a
password: once a connection is established both ends will demand proof
that the other knows the authentication key.  (Demonstrating that both
ends are using the same key does `not' involve sending the key over
the connection.)

If authentication is requested but no authentication key is specified then the
return value of @code{current_process().authkey} is used (see
@ref{4de,,Process}).  This value will be automatically inherited by
any @code{Process} object that the current process creates.
This means that (by default) all processes of a multi-process program will share
a single authentication key which can be used when setting up connections
between themselves.

Suitable authentication keys can also be generated by using @ref{931,,os.urandom()}.

This authentication protects @ref{1c2b,,Listener} and @ref{3904,,Client()} connections,
which are reachable by address.  It is not applied to the anonymous pipes
created by @ref{3896,,Pipe()} or used internally by
@ref{1d85,,Queue}.
@code{multiprocessing} treats all local processes running as the same user as
trusted; on most operating systems such processes can access each other’s pipe
file descriptors regardless.  Applications that require isolation between
processes of the same user must arrange it at the operating-system level –
for example, by running workers under a different user account or in a sandbox.

@node Logging<2>,The multiprocessing dummy module,Authentication keys,Reference<3>
@anchor{library/multiprocessing logging}@anchor{390b}
@subsubsection Logging


Some support for logging is available.  Note, however, that the @ref{8a,,logging}
package does not use process shared locks so it is possible (depending on the
handler type) for messages from different processes to get mixed up.

@geindex get_logger() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing get_logger}@anchor{3478}
@deffn {Συνάρτηση} multiprocessing.get_logger ()

Returns the logger used by @code{multiprocessing}.  If necessary, a new one
will be created.

When first created the logger has level @ref{33b3,,logging.NOTSET} and no
default handler. Messages sent to this logger will not by default propagate
to the root logger.

Note that on Windows child processes will only inherit the level of the
parent process’s logger – any other customization of the logger will not be
inherited.
@end deffn

@geindex log_to_stderr() (στη μονάδα multiprocessing)
@anchor{library/multiprocessing multiprocessing log_to_stderr}@anchor{390c}
@deffn {Συνάρτηση} multiprocessing.log_to_stderr (level=None)

This function performs a call to @ref{3478,,get_logger()} but in addition to
returning the logger created by get_logger, it adds a handler which sends
output to @ref{d05,,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

Below is an example session with logging turned on:

@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

For a full table of logging levels, see the @ref{8a,,logging} module.

@node The multiprocessing dummy module,,Logging<2>,Reference<3>
@anchor{library/multiprocessing module-multiprocessing dummy}@anchor{9a}@anchor{library/multiprocessing the-multiprocessing-dummy-module}@anchor{390d}
@subsubsection The @code{multiprocessing.dummy} module


@geindex module; multiprocessing.dummy

@code{multiprocessing.dummy} replicates the API of @code{multiprocessing} but is
no more than a wrapper around the @ref{f6,,threading} module.

In particular, the @code{Pool} function provided by @code{multiprocessing.dummy}
returns an instance of @ref{1eca,,ThreadPool}, which is a subclass of
@ref{1315,,Pool} that supports all the same method calls but uses a pool of
worker threads rather than worker processes.

@geindex ThreadPool (κλάση σε multiprocessing.pool)
@anchor{library/multiprocessing multiprocessing pool ThreadPool}@anchor{1eca}
@deffn {Κλάση} multiprocessing.pool.ThreadPool ([processes[, initializer[, initargs]]])

A thread pool object which controls a pool of worker threads to which jobs
can be submitted.  @code{ThreadPool} instances are fully interface
compatible with @ref{1315,,Pool} instances, and their resources must also be
properly managed, either by using the pool as a context manager or by
calling @ref{38f7,,close()} and
@ref{38f8,,terminate()} manually.

`processes' is the number of worker threads to use.  If `processes' is
@code{None} then the number returned by @ref{6e0,,os.process_cpu_count()} is used.

If `initializer' is not @code{None} then each worker process will call
@code{initializer(*initargs)} when it starts.

Unlike @ref{1315,,Pool}, `maxtasksperchild' and `context' cannot be provided.

@cartouche
@quotation Σημείωση 
A @code{ThreadPool} shares the same interface as @ref{1315,,Pool}, which
is designed around a pool of processes and predates the introduction of
the @ref{24,,concurrent.futures} module.  As such, it inherits some
operations that don’t make sense for a pool backed by threads, and it
has its own type for representing the status of asynchronous jobs,
@ref{38f9,,AsyncResult}, that is not understood by any other libraries.

Users should generally prefer to use
@ref{b27,,concurrent.futures.ThreadPoolExecutor}, which has a simpler
interface that was designed around threads from the start, and which
returns @ref{155b,,concurrent.futures.Future} instances that are
compatible with many other libraries, including @ref{b,,asyncio}.
@end quotation
@end cartouche
@end deffn

@node Programming guidelines,Examples<12>,Reference<3>,multiprocessing — Process-based parallelism
@anchor{library/multiprocessing multiprocessing-programming}@anchor{3892}@anchor{library/multiprocessing programming-guidelines}@anchor{390e}
@subsubsection Programming guidelines


There are certain guidelines and idioms which should be adhered to when using
@code{multiprocessing}.

@menu
* All start methods:: 
* The spawn and forkserver start methods:: 

@end menu

@node All start methods,The spawn and forkserver start methods,,Programming guidelines
@anchor{library/multiprocessing all-start-methods}@anchor{390f}
@subsubsection All start methods


The following applies to all start methods.

Avoid shared state

@quotation

As far as possible one should try to avoid shifting large amounts of data
between processes.

It is probably best to stick to using queues or pipes for communication
between processes rather than using the lower level synchronization
primitives.
@end quotation

Picklability

@quotation

Ensure that the arguments to the methods of proxies are picklable.
@end quotation

Thread safety of proxies

@quotation

Do not use a proxy object from more than one thread unless you protect it
with a lock.

(There is never a problem with different processes using the `same' proxy.)
@end quotation

Joining zombie processes

@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{38c3,,active_children()} is called) all completed processes
which have not yet been joined will be joined.  Also calling a finished
process’s @ref{1736,,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

Better to inherit than pickle/unpickle

@quotation

When using the `spawn' or `forkserver' start methods many types
from @code{multiprocessing} need to be picklable so that child
processes can use them.  However, one should generally avoid
sending shared objects to other processes using pipes or queues.
Instead you should arrange the program so that a process which
needs access to a shared resource created elsewhere can inherit it
from an ancestor process.
@end quotation

Avoid terminating processes

@quotation

Using the @ref{1a7f,,Process.terminate}
method to stop a process is liable to
cause any shared resources (such as locks, semaphores, pipes and queues)
currently being used by the process to become broken or unavailable to other
processes.

Therefore it is probably best to only consider using
@ref{1a7f,,Process.terminate} on processes
which never use any shared resources.
@end quotation

Joining processes that use queues

@quotation

Bear in mind that a process that has put items in a queue will wait before
terminating until all the buffered items are fed by the «feeder» thread to
the underlying pipe.  (The child process can call the
@ref{38b9,,Queue.cancel_join_thread}
method of the queue to avoid this behaviour.)

This means that whenever you use a queue you need to make sure that all
items which have been put on the queue will eventually be removed before the
process is joined.  Otherwise you cannot be sure that processes which have
put items on the queue will terminate.  Remember also that non-daemonic
processes will be joined automatically.

An example which will deadlock is the following:

@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

A fix here would be to swap the last two lines (or simply remove the
@code{p.join()} line).
@end quotation

Explicitly pass resources to child processes

@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.

Apart from making the code (potentially) compatible with Windows
and the other start methods this also ensures that as long as the
child process is still alive the object will not be garbage
collected in the parent process.  This might be important if some
resource is freed when the object is garbage collected in the
parent process.

So for instance

@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

should be rewritten as

@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

Beware of replacing @ref{94a,,sys.stdin} with a «file like object»

@quotation

@code{multiprocessing} originally unconditionally called:

@example
os.close(sys.stdin.fileno())
@end example

in the @code{multiprocessing.Process._bootstrap()} method — this resulted
in issues with processes-in-processes. This has been changed to:

@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{94a,,sys.stdin()} with a «file-like object»
with output buffering.  This danger is that if multiple processes call
@ref{70b,,close()} on this file-like object, it could result in the same
data being flushed to the object multiple times, resulting in corruption.

If you write a file-like object and implement your own caching, you can
make it fork-safe by storing the pid whenever you append to the cache,
and discarding the cache when the pid changes. For example:

@example
@@property
def cache(self):
    pid = os.getpid()
    if pid != self._pid:
        self._pid = pid
        self._cache = []
    return self._cache
@end example

For more information, see bpo-5155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5155}, bpo-5313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5313} and bpo-5331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5331}
@end quotation
@anchor{library/multiprocessing multiprocessing-programming-spawn}@anchor{38a7}
@node The spawn and forkserver start methods,,All start methods,Programming guidelines
@anchor{library/multiprocessing multiprocessing-programming-forkserver}@anchor{470}@anchor{library/multiprocessing the-spawn-and-forkserver-start-methods}@anchor{3910}
@subsubsection The `spawn' and `forkserver' start methods


There are a few extra restrictions which don’t apply to the `fork'
start method.

More picklability

@quotation

Ensure that all arguments to @ref{4de,,Process} are
picklable.  Also, if you subclass @code{Process.__init__}, you must make sure
that instances will be picklable when the
@ref{1735,,Process.start} method is called.
@end quotation

Global variables

@quotation

Bear in mind that if code run in a child process tries to access a global
variable, then the value it sees (if any) may not be the same as the value
in the parent process at the time that @ref{1735,,Process.start} was called.

However, global variables which are just module level constants cause no
problems.
@end quotation
@anchor{library/multiprocessing multiprocessing-safe-main-import}@anchor{3911}
Safe importing of main module

@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).

For example, using the `spawn' or `forkserver' start method
running the following module would fail with a
@ref{30d,,RuntimeError}:

@example
from multiprocessing import Process

def foo():
    print('hello')

p = Process(target=foo)
p.start()
@end example

Instead one should protect the «entry point» of the program by using @code{if
__name__ == '__main__':} as follows:

@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

(The @code{freeze_support()} line can be omitted if the program will be run
normally instead of frozen.)

This allows the newly spawned Python interpreter to safely import the module
and then run the module’s @code{foo()} function.

Similar restrictions apply if a pool or manager is created in the main
module.
@end quotation

@node Examples<12>,,Programming guidelines,multiprocessing — Process-based parallelism
@anchor{library/multiprocessing examples}@anchor{3912}@anchor{library/multiprocessing multiprocessing-examples}@anchor{38ba}
@subsubsection Examples


Demonstration of how to create and use customized managers and proxies:

@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

Using @ref{1315,,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

An example showing how to use queues to feed tasks to a collection of worker
processes and collect the results:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node multiprocessing shared_memory — Shared memory for direct access across processes,The concurrent package,multiprocessing — Process-based parallelism,Concurrent Execution
@anchor{library/multiprocessing shared_memory doc}@anchor{3913}@anchor{library/multiprocessing shared_memory module-multiprocessing shared_memory}@anchor{9d}@anchor{library/multiprocessing shared_memory multiprocessing-shared-memory-shared-memory-for-direct-access-across-processes}@anchor{3914}@anchor{library/multiprocessing shared_memory translation-repo}@anchor{3915}
@subsection @code{multiprocessing.shared_memory} — Shared memory for direct access across processes


@geindex module; multiprocessing.shared_memory

`Source code:' Lib/multiprocessing/shared_memory.py@footnote{https://github.com/python/cpython/tree/main/Lib/multiprocessing/shared_memory.py}


Added in version 3.8.


@geindex Shared Memory
@geindex POSIX Shared Memory
@geindex Named Shared Memory


__________________________________________________________________


This module provides a class, @ref{1be1,,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{38dd,,BaseManager} subclass,
@ref{3916,,SharedMemoryManager}, is also provided in the
@ref{9b,,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 (κλάση σε multiprocessing.shared_memory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory}@anchor{1be1}
@deffn {Κλάση} 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{3917,,close()} method should be called.
When a shared memory block is no longer needed by any process, the
@ref{3918,,unlink()} method should be called to ensure proper cleanup.

@*Παράμετροι: 

@itemize *

@item 
@code{name} (@ref{1df,,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{5ef,,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{326,,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{5ef,,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{98,,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{df,,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



Άλλαξε στην έκδοση 3.13: Added the `track' parameter.


@geindex close() (μέθοδος της multiprocessing.shared_memory.SharedMemory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory close}@anchor{3917}
@deffn {Μέθοδος} close ()

Close the file descriptor/handle to the shared memory from this
instance.  @code{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{3918,,unlink()} method.
@end deffn

@geindex unlink() (μέθοδος της multiprocessing.shared_memory.SharedMemory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory unlink}@anchor{3918}
@deffn {Μέθοδος} 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.
@code{unlink()} and @ref{3917,,close()} can be called in any order, but
trying to access data inside a shared memory block after @code{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 (ιδιότητα της multiprocessing.shared_memory.SharedMemory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory buf}@anchor{3919}
@deffn {Ιδιότητα} buf

A memoryview of contents of the shared memory block.
@end deffn

@geindex name (ιδιότητα της multiprocessing.shared_memory.SharedMemory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory name}@anchor{391a}
@deffn {Ιδιότητα} name

Read-only access to the unique name of the shared memory block.
@end deffn

@geindex size (ιδιότητα της multiprocessing.shared_memory.SharedMemory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory size}@anchor{391b}
@deffn {Ιδιότητα} size

Read-only access to size in bytes of the shared memory block.
@end deffn
@end deffn

The following example demonstrates low-level use of @ref{1be1,,SharedMemory}
instances:

@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{1be1,,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 (κλάση σε multiprocessing.managers)
@anchor{library/multiprocessing shared_memory multiprocessing managers SharedMemoryManager}@anchor{3916}
@deffn {Κλάση} multiprocessing.managers.SharedMemoryManager ([address[, authkey]])

A subclass of @ref{38dd,,multiprocessing.managers.BaseManager} which can be
used for the management of shared memory blocks across processes.

A call to @ref{38de,,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{38df,,shutdown()} on the instance.
This triggers a @ref{3918,,unlink()} call
on all of the @ref{391c,,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.

This class provides methods for creating and returning @ref{391c,,SharedMemory}
instances and for creating a list-like object (@ref{391d,,ShareableList})
backed by shared memory.

Refer to @ref{38dd,,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() (μέθοδος της multiprocessing.managers.SharedMemoryManager)
@anchor{library/multiprocessing shared_memory multiprocessing managers SharedMemoryManager SharedMemory}@anchor{391c}
@deffn {Μέθοδος} SharedMemory (size)

Create and return a new @ref{391c,,SharedMemory} object with the
specified `size' in bytes.
@end deffn

@geindex ShareableList() (μέθοδος της multiprocessing.managers.SharedMemoryManager)
@anchor{library/multiprocessing shared_memory multiprocessing managers SharedMemoryManager ShareableList}@anchor{391d}
@deffn {Μέθοδος} ShareableList (sequence)

Create and return a new @ref{391d,,ShareableList} object, initialized
by the values from the input `sequence'.
@end deffn
@end deffn

The following example demonstrates the basic mechanisms of a
@ref{3916,,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{3916,,SharedMemoryManager} objects via the
@ref{20a,,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{3916,,SharedMemoryManager}
in a @ref{20a,,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 (κλάση σε multiprocessing.shared_memory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList}@anchor{1f4c}
@deffn {Κλάση} 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{326,,int} (signed 64-bit)

@item 
@ref{327,,float}

@item 
@ref{5ef,,bool}

@item 
@ref{1df,,str} (less than 10M bytes each when encoded as UTF-8)

@item 
@ref{1c7,,bytes} (less than 10M bytes each)

@item 
@code{None}
@end itemize

It also notably differs from the built-in @ref{4d9,,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{1be1,,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 Σημείωση 
A known issue exists for @ref{1c7,,bytes} and @ref{1df,,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() (μέθοδος της multiprocessing.shared_memory.ShareableList)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList count}@anchor{391e}
@deffn {Μέθοδος} count (value)

Return the number of occurrences of `value'.
@end deffn

@geindex index() (μέθοδος της multiprocessing.shared_memory.ShareableList)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList index}@anchor{391f}
@deffn {Μέθοδος} index (value)

Return first index position of `value'.
Raise @ref{277,,ValueError} if `value' is not present.
@end deffn

@geindex format (ιδιότητα της multiprocessing.shared_memory.ShareableList)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList format}@anchor{3920}
@deffn {Ιδιότητα} format

Read-only attribute containing the @ref{de,,struct} packing format used by
all currently stored values.
@end deffn

@geindex shm (ιδιότητα της multiprocessing.shared_memory.ShareableList)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList shm}@anchor{3921}
@deffn {Ιδιότητα} shm

The @ref{1be1,,SharedMemory} instance where the values are stored.
@end deffn
@end deffn

The following example demonstrates basic use of a @ref{1f4c,,ShareableList}
instance:

@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

The following example depicts how one, two, or many processes may access the
same @ref{1f4c,,ShareableList} by supplying the name of the shared memory block
behind it:

@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{1f4c,,ShareableList}
(and underlying @ref{1be1,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node The concurrent package,concurrent futures — Launching parallel tasks,multiprocessing shared_memory — Shared memory for direct access across processes,Concurrent Execution
@anchor{library/concurrent doc}@anchor{3922}@anchor{library/concurrent the-concurrent-package}@anchor{3923}@anchor{library/concurrent translation-repo}@anchor{3924}
@subsection The @code{concurrent} package


This package contains the following modules:


@itemize *

@item 
@ref{24,,concurrent.futures} – Launching parallel tasks

@item 
@ref{25,,concurrent.interpreters} – Multiple interpreters in the same process
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node concurrent futures — Launching parallel tasks,concurrent interpreters — Multiple interpreters in the same process,The concurrent package,Concurrent Execution
@anchor{library/concurrent futures doc}@anchor{3925}@anchor{library/concurrent futures concurrent-futures-launching-parallel-tasks}@anchor{3926}@anchor{library/concurrent futures module-concurrent futures}@anchor{24}@anchor{library/concurrent futures translation-repo}@anchor{3927}
@subsection @code{concurrent.futures} — Launching parallel tasks


@geindex module; concurrent.futures


Added in version 3.2.


`Source code:' Lib/concurrent/futures/thread.py@footnote{https://github.com/python/cpython/tree/main/Lib/concurrent/futures/thread.py},
Lib/concurrent/futures/process.py@footnote{https://github.com/python/cpython/tree/main/Lib/concurrent/futures/process.py},
and Lib/concurrent/futures/interpreter.py@footnote{https://github.com/python/cpython/tree/main/Lib/concurrent/futures/interpreter.py}


__________________________________________________________________


The @code{concurrent.futures} module provides a high-level interface for
asynchronously executing callables.

The asynchronous execution can be performed with threads, using
@ref{b27,,ThreadPoolExecutor} or @ref{46a,,InterpreterPoolExecutor},
or separate processes, using @ref{206,,ProcessPoolExecutor}.
Each implements the same interface, which is defined
by the abstract @ref{3928,,Executor} class.

@ref{155b,,concurrent.futures.Future} must not be confused with
@ref{f8b,,asyncio.Future}, which is designed for use with @ref{b,,asyncio}
tasks and coroutines. See the @ref{3929,,asyncio’s Future}
documentation for a detailed comparison of the two.

@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

@menu
* Executor Objects:: 
* ThreadPoolExecutor:: 
* InterpreterPoolExecutor:: 
* 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{392a}
@subsubsection Executor Objects


@geindex Executor (κλάση σε concurrent.futures)
@anchor{library/concurrent futures concurrent futures Executor}@anchor{3928}
@deffn {Κλάση} 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() (μέθοδος της concurrent.futures.Executor)
@anchor{library/concurrent futures concurrent futures Executor submit}@anchor{e44}
@deffn {Μέθοδος} submit (fn, /, *args, **kwargs)

Schedules the callable, `fn', to be executed as @code{fn(*args, **kwargs)}
and returns a @ref{155b,,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() (μέθοδος της concurrent.futures.Executor)
@anchor{library/concurrent futures concurrent futures Executor map}@anchor{473}
@deffn {Μέθοδος} map (fn, *iterables, timeout=None, chunksize=1, buffersize=None)

Similar to @ref{43e,,map(fn@comma{} *iterables)} except:


@itemize *

@item 
The `iterables' are collected immediately rather than lazily, unless a
`buffersize' is specified to limit the number of submitted tasks whose
results have not yet been yielded. If the buffer is full, iteration over
the `iterables' pauses until a result is yielded from the buffer.

@item 
`fn' is executed asynchronously and several calls to
`fn' may be made concurrently.
@end itemize

The returned iterator raises a @ref{c0e,,TimeoutError}
if @ref{1672,,__next__()} is called and the result isn’t available
after `timeout' seconds from the original call to @code{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{206,,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{b27,,ThreadPoolExecutor} and @ref{46a,,InterpreterPoolExecutor},
`chunksize' has no effect.


Άλλαξε στην έκδοση 3.5: Added the `chunksize' parameter.



Άλλαξε στην έκδοση 3.14: Added the `buffersize' parameter.

@end deffn

@geindex shutdown() (μέθοδος της concurrent.futures.Executor)
@anchor{library/concurrent futures concurrent futures Executor shutdown}@anchor{cbe}
@deffn {Μέθοδος} 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{e44,,Executor.submit()} and @ref{473,,Executor.map()} made after shutdown will
raise @ref{30d,,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 executor
as a @ref{478,,context manager} via the  @ref{20a,,with} statement, which
will shutdown the @code{Executor} (waiting as if @code{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


Άλλαξε στην έκδοση 3.9: Added `cancel_futures'.

@end deffn
@end deffn

@node ThreadPoolExecutor,InterpreterPoolExecutor,Executor Objects,concurrent futures — Launching parallel tasks
@anchor{library/concurrent futures threadpoolexecutor}@anchor{392b}
@subsubsection ThreadPoolExecutor


@ref{b27,,ThreadPoolExecutor} is an @ref{3928,,Executor} subclass that uses a pool of
threads to execute calls asynchronously.

Deadlocks can occur when the callable associated with a @ref{155b,,Future} waits on
the results of another @code{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

And:

@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)
future = executor.submit(wait_on_future)
# Note: calling future.result() would also cause a deadlock because
# the single worker thread is already waiting for wait_on_future().
@end example

@geindex ThreadPoolExecutor (κλάση σε concurrent.futures)
@anchor{library/concurrent futures concurrent futures ThreadPoolExecutor}@anchor{b27}
@deffn {Κλάση} concurrent.futures.ThreadPoolExecutor (max_workers=None, thread_name_prefix='@w{'}, initializer=None, initargs=())

An @ref{3928,,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{392c,,BrokenThreadPool},
as well as any attempt to submit more jobs to the pool.


Άλλαξε στην έκδοση 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 @code{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{206,,ProcessPoolExecutor}.



Άλλαξε στην έκδοση 3.6: Added the `thread_name_prefix' parameter to allow users to
control the @ref{420,,threading.Thread} names for worker threads created by
the pool for easier debugging.



Άλλαξε στην έκδοση 3.7: Added the `initializer' and `initargs' arguments.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 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{392d}@anchor{library/concurrent futures threadpoolexecutor-example}@anchor{155c}
@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 InterpreterPoolExecutor,ProcessPoolExecutor,ThreadPoolExecutor,concurrent futures — Launching parallel tasks
@anchor{library/concurrent futures interpreterpoolexecutor}@anchor{392e}
@subsubsection InterpreterPoolExecutor



Added in version 3.14.


The @ref{46a,,InterpreterPoolExecutor} class uses a pool of interpreters
to execute calls asynchronously.  It is a @ref{b27,,ThreadPoolExecutor}
subclass, which means each worker is running in its own thread.
The difference here is that each worker has its own interpreter,
and runs each task using that interpreter.

The biggest benefit to using interpreters instead of only threads
is true multi-core parallelism.  Each interpreter has its own
@ref{685,,Global Interpreter Lock}, so code
running in one interpreter can run on one CPU core, while code in
another interpreter runs unblocked on a different core.

The tradeoff is that writing concurrent code for use with multiple
interpreters can take extra effort.  However, this is because it
forces you to be deliberate about how and when interpreters interact,
and to be explicit about what data is shared between interpreters.
This results in several benefits that help balance the extra effort,
including true multi-core parallelism,  For example, code written
this way can make it easier to reason about concurrency.  Another
major benefit is that you don’t have to deal with several of the
big pain points of using threads, like race conditions.

Each worker’s interpreter is isolated from all the other interpreters.
«Isolated» means each interpreter has its own runtime state and
operates completely independently.  For example, if you redirect
@ref{e9c,,sys.stdout} in one interpreter, it will not be automatically
redirected to any other interpreter.  If you import a module in one
interpreter, it is not automatically imported in any other.  You
would need to import the module separately in interpreter where
you need it.  In fact, each module imported in an interpreter is
a completely separate object from the same module in a different
interpreter, including @ref{e2,,sys}, @ref{13,,builtins},
and even @code{__main__}.

Isolation means a mutable object, or other data, cannot be used
by more than one interpreter at the same time.  That effectively means
interpreters cannot actually share such objects or data.  Instead,
each interpreter must have its own copy, and you will have to
synchronize any changes between the copies manually.  Immutable
objects and data, like the builtin singletons, strings, and tuples
of immutable objects, don’t have these limitations.

Communicating and synchronizing between interpreters is most effectively
done using dedicated tools, like those proposed in 
@geindex Python Enhancement Proposals; PEP 734
PEP 734@footnote{https://peps.python.org/pep-0734/}.  One less
efficient alternative is to serialize with @ref{ab,,pickle} and then send
the bytes over a shared @ref{d4,,socket} or
@ref{1d62,,pipe}.

@geindex InterpreterPoolExecutor (κλάση σε concurrent.futures)
@anchor{library/concurrent futures concurrent futures InterpreterPoolExecutor}@anchor{46a}
@deffn {Κλάση} concurrent.futures.InterpreterPoolExecutor (max_workers=None, thread_name_prefix='@w{'}, initializer=None, initargs=())

A @ref{b27,,ThreadPoolExecutor} subclass that executes calls asynchronously
using a pool of at most `max_workers' threads.  Each thread runs
tasks in its own interpreter.  The worker interpreters are isolated
from each other, which means each has its own runtime state and that
they can’t share any mutable objects or other data.  Each interpreter
has its own @ref{685,,Global Interpreter Lock},
which means code run with this executor has true multi-core parallelism.

The optional `initializer' and `initargs' arguments have the same
meaning as for @code{ThreadPoolExecutor}: the initializer is run
when each worker is created, though in this case it is run in
the worker’s interpreter.  The executor serializes the `initializer'
and `initargs' using @ref{ab,,pickle} when sending them to the worker’s
interpreter.

@cartouche
@quotation Σημείωση 
The executor may replace uncaught exceptions from `initializer'
with @ref{392f,,ExecutionFailed}.
@end quotation
@end cartouche

Other caveats from parent @ref{b27,,ThreadPoolExecutor} apply here.
@end deffn

@ref{e44,,submit()} and @ref{473,,map()} work like normal,
except the worker serializes the callable and arguments using
@ref{ab,,pickle} when sending them to its interpreter.  The worker
likewise serializes the return value when sending it back.

When a worker’s current task raises an uncaught exception, the worker
always tries to preserve the exception as-is.  If that is successful
then it also sets the @code{__cause__} to a corresponding
@ref{392f,,ExecutionFailed}
instance, which contains a summary of the original exception.
In the uncommon case that the worker is not able to preserve the
original as-is then it directly preserves the corresponding
@code{ExecutionFailed}
instance instead.

@node ProcessPoolExecutor,Future Objects,InterpreterPoolExecutor,concurrent futures — Launching parallel tasks
@anchor{library/concurrent futures processpoolexecutor}@anchor{3930}
@subsubsection ProcessPoolExecutor


The @ref{206,,ProcessPoolExecutor} class is an @ref{3928,,Executor} subclass that
uses a pool of processes to execute calls asynchronously.
@code{ProcessPoolExecutor} uses the @ref{98,,multiprocessing} module, which
allows it to side-step the @ref{685,,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{206,,ProcessPoolExecutor} will not work in the interactive interpreter.

Calling @ref{3928,,Executor} or @ref{155b,,Future} methods from a callable submitted
to a @ref{206,,ProcessPoolExecutor} will result in deadlock.

Note that the restrictions on functions and arguments needing to picklable as
per @ref{4de,,multiprocessing.Process} apply when using @ref{e44,,submit()}
and @ref{473,,map()} on a @ref{206,,ProcessPoolExecutor}. A function defined
in a REPL or a lambda should not be expected to work.

@geindex ProcessPoolExecutor (κλάση σε concurrent.futures)
@anchor{library/concurrent futures concurrent futures ProcessPoolExecutor}@anchor{206}
@deffn {Κλάση} concurrent.futures.ProcessPoolExecutor (max_workers=None, mp_context=None, initializer=None, initargs=(), max_tasks_per_child=None)

An @ref{3928,,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{6e0,,os.process_cpu_count()}.
If `max_workers' is less than or equal to @code{0}, then a @ref{277,,ValueError}
will be raised.
On Windows, `max_workers' must be less than or equal to @code{61}. If it is not
then @code{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{98,,multiprocessing} context or @code{None}. It will be
used to launch the workers. If `mp_context' is @code{None} or not given, the
default @code{multiprocessing} context is used.
See @ref{46d,,Contexts and start methods}.

`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{3931,,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.

@cartouche
@quotation Σημείωση 
Bugs have been reported when using the `max_tasks_per_child' feature that
can result in the @code{ProcessPoolExecutor} hanging in some
circumstances. Follow its eventual resolution in gh-115634@footnote{https://github.com/python/cpython/issues/115634}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: When one of the worker processes terminates abruptly, a
@ref{3931,,BrokenProcessPool} error is now raised.
Previously, behaviour
was undefined but operations on the executor or its futures would often
freeze or deadlock.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.11: The `max_tasks_per_child' argument was added to allow users to
control the lifetime of workers in the pool.



Άλλαξε στην έκδοση 3.12: On POSIX systems, if your application has multiple threads and the
@ref{98,,multiprocessing} context uses the @code{"fork"} start method:
The @ref{6bd,,os.fork()} function called internally to spawn workers may raise a
@ref{2c9,,DeprecationWarning}. Pass a `mp_context' configured to use a
different start method. See the @code{os.fork()} documentation for
further explanation.



Άλλαξε στην έκδοση 3.13: `max_workers' uses @ref{6e0,,os.process_cpu_count()} by default, instead of
@ref{6e1,,os.cpu_count()}.



Άλλαξε στην έκδοση 3.14: The default process start method (see
@ref{46d,,Contexts and start methods}) changed away from `fork'. If you
require the `fork' start method for @code{ProcessPoolExecutor} you must
explicitly pass @code{mp_context=multiprocessing.get_context("fork")}.


@geindex terminate_workers() (μέθοδος της concurrent.futures.ProcessPoolExecutor)
@anchor{library/concurrent futures concurrent futures ProcessPoolExecutor terminate_workers}@anchor{471}
@deffn {Μέθοδος} terminate_workers ()

Attempt to terminate all living worker processes immediately by calling
@ref{1a7f,,Process.terminate} on each of them.
Internally, it will also call @ref{cbe,,Executor.shutdown()} to ensure that all
other resources associated with the executor are freed.

After calling this method the caller should no longer submit tasks to the
executor.


Added in version 3.14.

@end deffn

@geindex kill_workers() (μέθοδος της concurrent.futures.ProcessPoolExecutor)
@anchor{library/concurrent futures concurrent futures ProcessPoolExecutor kill_workers}@anchor{472}
@deffn {Μέθοδος} kill_workers ()

Attempt to kill all living worker processes immediately by calling
@ref{f15,,Process.kill} on each of them.
Internally, it will also call @ref{cbe,,Executor.shutdown()} to ensure that all
other resources associated with the executor are freed.

After calling this method the caller should no longer submit tasks to the
executor.


Added in version 3.14.

@end deffn
@end deffn

@menu
* ProcessPoolExecutor Example:: 

@end menu

@node ProcessPoolExecutor Example,,,ProcessPoolExecutor
@anchor{library/concurrent futures id2}@anchor{3932}@anchor{library/concurrent futures processpoolexecutor-example}@anchor{155d}
@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{3933}
@subsubsection Future Objects


The @ref{155b,,Future} class encapsulates the asynchronous execution of a callable.
@code{Future} instances are created by @ref{e44,,Executor.submit()}.

@geindex Future (κλάση σε concurrent.futures)
@anchor{library/concurrent futures concurrent futures Future}@anchor{155b}
@deffn {Κλάση} concurrent.futures.Future

Encapsulates the asynchronous execution of a callable.  @code{Future}
instances are created by @ref{e44,,Executor.submit()} and should not be created
directly except for testing.

@geindex cancel() (μέθοδος της concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future cancel}@anchor{3934}
@deffn {Μέθοδος} 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() (μέθοδος της concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future cancelled}@anchor{3935}
@deffn {Μέθοδος} cancelled ()

Return @code{True} if the call was successfully cancelled.
@end deffn

@geindex running() (μέθοδος της concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future running}@anchor{3936}
@deffn {Μέθοδος} running ()

Return @code{True} if the call is currently being executed and cannot be
cancelled.
@end deffn

@geindex done() (μέθοδος της concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future done}@anchor{3937}
@deffn {Μέθοδος} done ()

Return @code{True} if the call was successfully cancelled or finished
running.
@end deffn

@geindex result() (μέθοδος της concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future result}@anchor{3938}
@deffn {Μέθοδος} 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{c0e,,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{d9f,,CancelledError}
will be raised.

If the call raised an exception, this method will raise the same exception.
@end deffn

@geindex exception() (μέθοδος της concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future exception}@anchor{3939}
@deffn {Μέθοδος} 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{c0e,,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{d9f,,CancelledError}
will be raised.

If the call completed without raising, @code{None} is returned.
@end deffn

@geindex add_done_callback() (μέθοδος της concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future add_done_callback}@anchor{393a}
@deffn {Μέθοδος} 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{d9e,,Exception} subclass, it will be logged and
ignored.  If the callable raises a @ref{9b9,,BaseException} subclass, the
behavior is undefined.

If the future has already completed or been cancelled, `fn' will be
called immediately.
@end deffn

The following @code{Future} methods are meant for use in unit tests and
@ref{3928,,Executor} implementations.

@geindex set_running_or_notify_cancel() (μέθοδος της concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future set_running_or_notify_cancel}@anchor{393b}
@deffn {Μέθοδος} set_running_or_notify_cancel ()

This method should only be called by @ref{3928,,Executor} implementations
before executing the work associated with the @code{Future} and by unit
tests.

If the method returns @code{False} then the @code{Future} was cancelled,
i.e. @ref{3934,,Future.cancel()} was called and returned @code{True}.  Any threads
waiting on the @code{Future} completing (i.e. through
@ref{1bd1,,as_completed()} or @ref{1dfc,,wait()}) will be woken up.

If the method returns @code{True} then the @code{Future} was not cancelled
and has been put in the running state, i.e. calls to
@ref{3936,,Future.running()} will return @code{True}.

This method can only be called once and cannot be called after
@ref{393c,,Future.set_result()} or @ref{393d,,Future.set_exception()} have been
called.
@end deffn

@geindex set_result() (μέθοδος της concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future set_result}@anchor{393c}
@deffn {Μέθοδος} set_result (result)

Sets the result of the work associated with the @code{Future} to
`result'.

This method should only be used by @ref{3928,,Executor} implementations and
unit tests.


Άλλαξε στην έκδοση 3.8: This method raises
@ref{1b65,,concurrent.futures.InvalidStateError} if the @code{Future} is
already done.

@end deffn

@geindex set_exception() (μέθοδος της concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future set_exception}@anchor{393d}
@deffn {Μέθοδος} set_exception (exception)

Sets the result of the work associated with the @code{Future} to the
@ref{d9e,,Exception} `exception'.

This method should only be used by @ref{3928,,Executor} implementations and
unit tests.


Άλλαξε στην έκδοση 3.8: This method raises
@ref{1b65,,concurrent.futures.InvalidStateError} if the @code{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{393e}
@subsubsection Module Functions


@geindex wait() (στη μονάδα concurrent.futures)
@anchor{library/concurrent futures concurrent futures wait}@anchor{1dfc}
@deffn {Συνάρτηση} concurrent.futures.wait (fs, timeout=None, return_when=ALL_COMPLETED)

Wait for the @ref{155b,,Future} instances (possibly created by different
@ref{3928,,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' indicates when this function should return.  It must be one of
the following constants:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constant

@tab

Description

@item

@geindex FIRST_COMPLETED (στη μονάδα concurrent.futures)
@anchor{library/concurrent futures concurrent futures FIRST_COMPLETED}@anchor{393f}
@deffn {Δεδομένα} concurrent.futures.FIRST_COMPLETED
@end deffn

@tab

The function will return when any future finishes or is cancelled.

@item

@geindex FIRST_EXCEPTION (στη μονάδα concurrent.futures)
@anchor{library/concurrent futures concurrent futures FIRST_EXCEPTION}@anchor{3940}
@deffn {Δεδομένα} 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{3941,,ALL_COMPLETED}.

@item

@geindex ALL_COMPLETED (στη μονάδα concurrent.futures)
@anchor{library/concurrent futures concurrent futures ALL_COMPLETED}@anchor{3941}
@deffn {Δεδομένα} concurrent.futures.ALL_COMPLETED
@end deffn

@tab

The function will return when all futures finish or are cancelled.

@end multitable

@end deffn

@geindex as_completed() (στη μονάδα concurrent.futures)
@anchor{library/concurrent futures concurrent futures as_completed}@anchor{1bd1}
@deffn {Συνάρτηση} concurrent.futures.as_completed (fs, timeout=None)

Returns an iterator over the @ref{155b,,Future} instances (possibly created by
different @ref{3928,,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
@code{as_completed()} is called will be yielded first.  The returned iterator
raises a @ref{c0e,,TimeoutError} if @ref{1672,,__next__()}
is called and the result isn’t available after `timeout' seconds from the
original call to @code{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 Δείτε επίσης



@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{3942}
@subsubsection Exception classes


@geindex CancelledError
@anchor{library/concurrent futures concurrent futures CancelledError}@anchor{d9f}
@deffn {Εξαίρεση} concurrent.futures.CancelledError

Raised when a future is cancelled.
@end deffn

@geindex TimeoutError
@anchor{library/concurrent futures concurrent futures TimeoutError}@anchor{3943}
@deffn {Εξαίρεση} concurrent.futures.TimeoutError

A deprecated alias of @code{TimeoutError},
raised when a future operation exceeds the given timeout.


Άλλαξε στην έκδοση 3.11: This class was made an alias of @code{TimeoutError}.

@end deffn

@geindex BrokenExecutor
@anchor{library/concurrent futures concurrent futures BrokenExecutor}@anchor{3944}
@deffn {Εξαίρεση} concurrent.futures.BrokenExecutor

Derived from @ref{30d,,RuntimeError}, this exception class is raised
when an executor is broken for some reason, and cannot be used
to submit or execute new tasks.


Added in version 3.7.

@end deffn

@geindex InvalidStateError
@anchor{library/concurrent futures concurrent futures InvalidStateError}@anchor{1b65}
@deffn {Εξαίρεση} concurrent.futures.InvalidStateError

Raised when an operation is performed on a future that is not allowed
in the current state.


Added in version 3.8.

@end deffn

@geindex BrokenThreadPool
@anchor{library/concurrent futures concurrent futures thread BrokenThreadPool}@anchor{392c}
@deffn {Εξαίρεση} concurrent.futures.thread.BrokenThreadPool

Derived from @ref{3944,,BrokenExecutor}, this exception
class is raised when one of the workers
of a @ref{b27,,ThreadPoolExecutor}
has failed initializing.


Added in version 3.7.

@end deffn

@geindex BrokenInterpreterPool
@anchor{library/concurrent futures concurrent futures interpreter BrokenInterpreterPool}@anchor{3945}
@deffn {Εξαίρεση} concurrent.futures.interpreter.BrokenInterpreterPool

Derived from @ref{392c,,BrokenThreadPool},
this exception class is raised when one of the workers
of a @ref{46a,,InterpreterPoolExecutor}
has failed initializing.


Added in version 3.14.

@end deffn

@geindex BrokenProcessPool
@anchor{library/concurrent futures concurrent futures process BrokenProcessPool}@anchor{3931}
@deffn {Εξαίρεση} concurrent.futures.process.BrokenProcessPool

Derived from @ref{3944,,BrokenExecutor} (formerly
@ref{30d,,RuntimeError}), this exception class is raised when one of the
workers of a @ref{206,,ProcessPoolExecutor}
has terminated in a non-clean
fashion (for example, if it was killed from the outside).


Added in version 3.3.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node concurrent interpreters — Multiple interpreters in the same process,subprocess — Subprocess management,concurrent futures — Launching parallel tasks,Concurrent Execution
@anchor{library/concurrent interpreters doc}@anchor{3946}@anchor{library/concurrent interpreters concurrent-interpreters-multiple-interpreters-in-the-same-process}@anchor{3947}@anchor{library/concurrent interpreters module-concurrent interpreters}@anchor{25}@anchor{library/concurrent interpreters translation-repo}@anchor{3948}
@subsection @code{concurrent.interpreters} — Multiple interpreters in the same process


@geindex module; concurrent.interpreters


Added in version 3.14.


`Source code:' Lib/concurrent/interpreters@footnote{https://github.com/python/cpython/tree/main/Lib/concurrent/interpreters}


__________________________________________________________________


The @code{concurrent.interpreters} module constructs higher-level
interfaces on top of the lower level @code{_interpreters} module.

The module is primarily meant to provide a basic API for managing
interpreters (AKA «subinterpreters») and running things in them.
Running mostly involves switching to an interpreter (in the current
thread) and calling a function in that execution context.

For concurrency, interpreters themselves (and this module) don’t
provide much more than isolation, which on its own isn’t useful.
Actual concurrency is available separately through
@ref{f6,,threads}  See @ref{3949,,below}@anchor{library/concurrent interpreters interp-concurrency}@anchor{3949}


@subsubheading Δείτε επίσης



@table @asis

@item @ref{46a,,InterpreterPoolExecutor}

Combines threads with interpreters in a familiar interface.
@end table

@c XXX Add references to the upcoming HOWTO docs in the seealso block.


@table @asis

@item @ref{412,,Isolating Extension Modules}

How to update an extension module to support multiple interpreters.
@end table

@geindex Python Enhancement Proposals; PEP 554
PEP 554@footnote{https://peps.python.org/pep-0554/}

@geindex Python Enhancement Proposals; PEP 734
PEP 734@footnote{https://peps.python.org/pep-0734/}

@geindex Python Enhancement Proposals; PEP 684
PEP 684@footnote{https://peps.python.org/pep-0684/}


@c XXX Why do we disallow multiple interpreters on WASM?

@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

@menu
* Key details:: 
* Introduction: Introduction<8>. 
* Reference: Reference<4>. 
* Basic usage:: 

@end menu

@node Key details,Introduction<8>,,concurrent interpreters — Multiple interpreters in the same process
@anchor{library/concurrent interpreters key-details}@anchor{394a}
@subsubsection Key details


Before we dive in further, there are a small number of details
to keep in mind about using multiple interpreters:


@itemize *

@item 
@ref{394b,,isolated}@anchor{library/concurrent interpreters interp-isolation}@anchor{394b}, by default

@item 
no implicit threads

@item 
not all PyPI packages support use in multiple interpreters yet
@end itemize

@c XXX Are there other relevant details to list?

@node Introduction<8>,Reference<4>,Key details,concurrent interpreters — Multiple interpreters in the same process
@anchor{library/concurrent interpreters interpreters-intro}@anchor{394c}@anchor{library/concurrent interpreters introduction}@anchor{394d}
@subsubsection Introduction


An «interpreter» is effectively the execution context of the Python
runtime.  It contains all of the state the runtime needs to execute
a program.  This includes things like the import state and builtins.
(Each thread, even if there’s only the main thread, has some extra
runtime state, in addition to the current interpreter, related to
the current exception and the bytecode eval loop.)

The concept and functionality of the interpreter have been a part of
Python since version 2.2, but the feature was only available through
the C-API and not well known, and the @ref{394b,,isolation}
was relatively incomplete until version 3.12.

@menu
* Multiple Interpreters and Isolation:: 
* Running in an Interpreter:: 
* Concurrency and Parallelism:: 
* Communication Between Interpreters:: 
* «Sharing» Objects:: 

@end menu

@node Multiple Interpreters and Isolation,Running in an Interpreter,,Introduction<8>
@anchor{library/concurrent interpreters multiple-interpreters-and-isolation}@anchor{394e}
@subsubsection Multiple Interpreters and Isolation


A Python implementation may support using multiple interpreters in the
same process.  CPython has this support.  Each interpreter is
effectively isolated from the others (with a limited number of
carefully managed process-global exceptions to the rule).

That isolation is primarily useful as a strong separation between
distinct logical components of a program, where you want to have
careful control of how those components interact.

@cartouche
@quotation Σημείωση 
Interpreters in the same process can technically never be strictly
isolated from one another since there are few restrictions on memory
access within the same process.  The Python runtime makes a best
effort at isolation but extension modules may easily violate that.
Therefore, do not use multiple interpreters in security-sensitive
situations, where they shouldn’t have access to each other’s data.
@end quotation
@end cartouche

@node Running in an Interpreter,Concurrency and Parallelism,Multiple Interpreters and Isolation,Introduction<8>
@anchor{library/concurrent interpreters running-in-an-interpreter}@anchor{394f}
@subsubsection Running in an Interpreter


Running in a different interpreter involves switching to it in the
current thread and then calling some function.  The runtime will
execute the function using the current interpreter’s state.  The
@code{concurrent.interpreters} module provides a basic API for
creating and managing interpreters, as well as the switch-and-call
operation.

No other threads are automatically started for the operation.
There is @ref{3950,,a helper}@anchor{library/concurrent interpreters interp-call-in-thread}@anchor{3950} for that though.
There is another dedicated helper for calling the builtin
@ref{185,,exec()} in an interpreter.

When @ref{185,,exec()} (or @ref{184,,eval()}) are called in an interpreter,
they run using the interpreter’s @code{__main__} module as the
«globals» namespace.  The same is true for functions that aren’t
associated with any module.  This is the same as how scripts invoked
from the command-line run in the @code{__main__} module.

@node Concurrency and Parallelism,Communication Between Interpreters,Running in an Interpreter,Introduction<8>
@anchor{library/concurrent interpreters concurrency-and-parallelism}@anchor{3951}
@subsubsection Concurrency and Parallelism


As noted earlier, interpreters do not provide any concurrency
on their own.  They strictly represent the isolated execution
context the runtime will use `in the current thread'.  That isolation
makes them similar to processes, but they still enjoy in-process
efficiency, like threads.

All that said, interpreters do naturally support certain flavors of
concurrency.
There’s a powerful side effect of that isolation.  It enables a
different approach to concurrency than you can take with async or
threads.  It’s a similar concurrency model to CSP or the actor model,
a model which is relatively easy to reason about.

You can take advantage of that concurrency model in a single thread,
switching back and forth between interpreters, Stackless-style.
However, this model is more useful when you combine interpreters
with multiple threads.  This mostly involves starting a new thread,
where you switch to another interpreter and run what you want there.

Each actual thread in Python, even if you’re only running in the main
thread, has its own `current' execution context.  Multiple threads can
use the same interpreter or different ones.

At a high level, you can think of the combination of threads and
interpreters as threads with opt-in sharing.

As a significant bonus, interpreters are sufficiently isolated that
they do not share the @ref{411,,GIL}, which means combining threads with
multiple interpreters enables full multi-core parallelism.
(This has been the case since Python 3.12.)

@node Communication Between Interpreters,«Sharing» Objects,Concurrency and Parallelism,Introduction<8>
@anchor{library/concurrent interpreters communication-between-interpreters}@anchor{3952}
@subsubsection Communication Between Interpreters


In practice, multiple interpreters are useful only if we have a way
to communicate between them.  This usually involves some form of
message passing, but can even mean sharing data in some carefully
managed way.

With this in mind, the @code{concurrent.interpreters} module provides
a @ref{1738,,queue.Queue} implementation, available through
@ref{3953,,create_queue()}.

@node «Sharing» Objects,,Communication Between Interpreters,Introduction<8>
@anchor{library/concurrent interpreters interp-object-sharing}@anchor{3954}@anchor{library/concurrent interpreters sharing-objects}@anchor{3955}
@subsubsection «Sharing» Objects


Any data actually shared between interpreters loses the thread-safety
provided by the @ref{411,,GIL}.  There are various options for dealing with
this in extension modules.  However, from Python code the lack of
thread-safety means objects can’t actually be shared, with a few
exceptions.  Instead, a copy must be created, which means mutable
objects won’t stay in sync.

By default, most objects are copied with @ref{ab,,pickle} when they are
passed to another interpreter.  Nearly all of the immutable builtin
objects are either directly shared or copied efficiently.  For example:


@itemize *

@item 
@ref{a65,,None}

@item 
@ref{5ef,,bool} (@ref{fcc,,True} and @ref{ef5,,False})

@item 
@ref{1c7,,bytes}

@item 
@ref{1df,,str}

@item 
@ref{326,,int}

@item 
@ref{327,,float}

@item 
@ref{1ce,,tuple} (of similarly supported objects)
@end itemize

There is a small number of Python types that actually share mutable
data between interpreters:


@itemize *

@item 
@ref{1d2,,memoryview}

@item 
@ref{3956,,Queue}
@end itemize

@node Reference<4>,Basic usage,Introduction<8>,concurrent interpreters — Multiple interpreters in the same process
@anchor{library/concurrent interpreters reference}@anchor{3957}
@subsubsection Reference


This module defines the following functions:

@geindex list_all() (στη μονάδα concurrent.interpreters)
@anchor{library/concurrent interpreters concurrent interpreters list_all}@anchor{3958}
@deffn {Συνάρτηση} concurrent.interpreters.list_all ()

Return a @ref{4d9,,list} of @ref{3959,,Interpreter} objects,
one for each existing interpreter.
@end deffn

@geindex get_current() (στη μονάδα concurrent.interpreters)
@anchor{library/concurrent interpreters concurrent interpreters get_current}@anchor{395a}
@deffn {Συνάρτηση} concurrent.interpreters.get_current ()

Return an @ref{3959,,Interpreter} object for the currently running
interpreter.
@end deffn

@geindex get_main() (στη μονάδα concurrent.interpreters)
@anchor{library/concurrent interpreters concurrent interpreters get_main}@anchor{395b}
@deffn {Συνάρτηση} concurrent.interpreters.get_main ()

Return an @ref{3959,,Interpreter} object for the main interpreter.
This is the interpreter the runtime created to run the @ref{69d,,REPL}
or the script given at the command-line.  It is usually the only one.
@end deffn

@geindex create() (στη μονάδα concurrent.interpreters)
@anchor{library/concurrent interpreters concurrent interpreters create}@anchor{19f5}
@deffn {Συνάρτηση} concurrent.interpreters.create ()

Initialize a new (idle) Python interpreter
and return a @ref{3959,,Interpreter} object for it.
@end deffn

@geindex create_queue() (στη μονάδα concurrent.interpreters)
@anchor{library/concurrent interpreters concurrent interpreters create_queue}@anchor{3953}
@deffn {Συνάρτηση} concurrent.interpreters.create_queue ()

Initialize a new cross-interpreter queue and return a @ref{3956,,Queue}
object for it.
@end deffn

@menu
* Interpreter objects:: 
* Exceptions: Exceptions<12>. 
* Communicating Between Interpreters:: 

@end menu

@node Interpreter objects,Exceptions<12>,,Reference<4>
@anchor{library/concurrent interpreters interpreter-objects}@anchor{395c}
@subsubsection Interpreter objects


@geindex Interpreter (κλάση σε concurrent.interpreters)
@anchor{library/concurrent interpreters concurrent interpreters Interpreter}@anchor{3959}
@deffn {Κλάση} concurrent.interpreters.Interpreter (id)

A single interpreter in the current process.

Generally, @code{Interpreter} shouldn’t be called directly.
Instead, use @ref{19f5,,create()} or one of the other module functions.

@geindex id (ιδιότητα της concurrent.interpreters.Interpreter)
@anchor{library/concurrent interpreters concurrent interpreters Interpreter id}@anchor{395d}
@deffn {Ιδιότητα} id

(read-only)

The underlying interpreter’s ID.
@end deffn

@geindex whence (ιδιότητα της concurrent.interpreters.Interpreter)
@anchor{library/concurrent interpreters concurrent interpreters Interpreter whence}@anchor{395e}
@deffn {Ιδιότητα} whence

(read-only)

A string describing where the interpreter came from.
@end deffn

@geindex is_running() (μέθοδος της concurrent.interpreters.Interpreter)
@anchor{library/concurrent interpreters concurrent interpreters Interpreter is_running}@anchor{395f}
@deffn {Μέθοδος} is_running ()

Return @code{True} if the interpreter is currently executing code
in its @code{__main__} module and @code{False} otherwise.
@end deffn

@geindex close() (μέθοδος της concurrent.interpreters.Interpreter)
@anchor{library/concurrent interpreters concurrent interpreters Interpreter close}@anchor{19d3}
@deffn {Μέθοδος} close ()

Finalize and destroy the interpreter.
@end deffn

@geindex prepare_main() (μέθοδος της concurrent.interpreters.Interpreter)
@anchor{library/concurrent interpreters concurrent interpreters Interpreter prepare_main}@anchor{3960}
@deffn {Μέθοδος} prepare_main (ns=None, **kwargs)

Bind objects in the interpreter’s @code{__main__} module.

Some objects are actually shared and some are copied efficiently,
but most are copied via @ref{ab,,pickle}.  See @ref{3954,,«Sharing» Objects}.
@end deffn

@geindex exec() (μέθοδος της concurrent.interpreters.Interpreter)
@anchor{library/concurrent interpreters concurrent interpreters Interpreter exec}@anchor{3961}
@deffn {Μέθοδος} exec (code, /, dedent=True)

Run the given source code in the interpreter (in the current thread).
@end deffn

@geindex call() (μέθοδος της concurrent.interpreters.Interpreter)
@anchor{library/concurrent interpreters concurrent interpreters Interpreter call}@anchor{3962}
@deffn {Μέθοδος} call (callable, /, *args, **kwargs)

Return the result of calling running the given function in the
interpreter (in the current thread).
@end deffn

@geindex call_in_thread() (μέθοδος της concurrent.interpreters.Interpreter)
@anchor{library/concurrent interpreters concurrent interpreters Interpreter call_in_thread}@anchor{3963}
@deffn {Μέθοδος} call_in_thread (callable, /, *args, **kwargs)

Run the given function in the interpreter (in a new thread).
@end deffn
@end deffn

@node Exceptions<12>,Communicating Between Interpreters,Interpreter objects,Reference<4>
@anchor{library/concurrent interpreters exceptions}@anchor{3964}
@subsubsection Exceptions


@geindex InterpreterError
@anchor{library/concurrent interpreters concurrent interpreters InterpreterError}@anchor{3965}
@deffn {Εξαίρεση} concurrent.interpreters.InterpreterError

This exception, a subclass of @ref{d9e,,Exception}, is raised when
an interpreter-related error happens.
@end deffn

@geindex InterpreterNotFoundError
@anchor{library/concurrent interpreters concurrent interpreters InterpreterNotFoundError}@anchor{3966}
@deffn {Εξαίρεση} concurrent.interpreters.InterpreterNotFoundError

This exception, a subclass of @ref{3965,,InterpreterError}, is raised when
the targeted interpreter no longer exists.
@end deffn

@geindex ExecutionFailed
@anchor{library/concurrent interpreters concurrent interpreters ExecutionFailed}@anchor{392f}
@deffn {Εξαίρεση} concurrent.interpreters.ExecutionFailed

This exception, a subclass of @ref{3965,,InterpreterError}, is raised when
the running code raised an uncaught exception.

@geindex excinfo (ιδιότητα της concurrent.interpreters.ExecutionFailed)
@anchor{library/concurrent interpreters concurrent interpreters ExecutionFailed excinfo}@anchor{3967}
@deffn {Ιδιότητα} excinfo

A basic snapshot of the exception raised in the other interpreter.
@end deffn
@end deffn

@c XXX Document the excinfoattrs?

@geindex NotShareableError
@anchor{library/concurrent interpreters concurrent interpreters NotShareableError}@anchor{3968}
@deffn {Εξαίρεση} concurrent.interpreters.NotShareableError

This exception, a subclass of @ref{291,,TypeError}, is raised when
an object cannot be sent to another interpreter.
@end deffn

@node Communicating Between Interpreters,,Exceptions<12>,Reference<4>
@anchor{library/concurrent interpreters communicating-between-interpreters}@anchor{3969}
@subsubsection Communicating Between Interpreters


@geindex Queue (κλάση σε concurrent.interpreters)
@anchor{library/concurrent interpreters concurrent interpreters Queue}@anchor{3956}
@deffn {Κλάση} concurrent.interpreters.Queue (id)

A wrapper around a low-level, cross-interpreter queue, which
implements the @ref{1738,,queue.Queue} interface.  The underlying queue
can only be created through @ref{3953,,create_queue()}.

Some objects are actually shared and some are copied efficiently,
but most are copied via @ref{ab,,pickle}.  See @ref{3954,,«Sharing» Objects}.

@geindex id (ιδιότητα της concurrent.interpreters.Queue)
@anchor{library/concurrent interpreters concurrent interpreters Queue id}@anchor{396a}
@deffn {Ιδιότητα} id

(read-only)

The queue’s ID.
@end deffn
@end deffn

@geindex QueueEmptyError
@anchor{library/concurrent interpreters concurrent interpreters QueueEmptyError}@anchor{396b}
@deffn {Εξαίρεση} concurrent.interpreters.QueueEmptyError

This exception, a subclass of @ref{38b6,,queue.Empty}, is raised from
@code{Queue.get()} and @code{Queue.get_nowait()} when the queue
is empty.
@end deffn

@geindex QueueFullError
@anchor{library/concurrent interpreters concurrent interpreters QueueFullError}@anchor{396c}
@deffn {Εξαίρεση} concurrent.interpreters.QueueFullError

This exception, a subclass of @ref{38b7,,queue.Full}, is raised from
@code{Queue.put()} and @code{Queue.put_nowait()} when the queue
is full.
@end deffn

@node Basic usage,,Reference<4>,concurrent interpreters — Multiple interpreters in the same process
@anchor{library/concurrent interpreters basic-usage}@anchor{396d}
@subsubsection Basic usage


Creating an interpreter and running code in it:

@example
from concurrent import interpreters

interp = interpreters.create()

# Run in the current OS thread.

interp.exec('print("spam!")')

interp.exec("""if True:
    print('spam!')
    """)

from textwrap import dedent
interp.exec(dedent("""
    print('spam!')
    """))

def run(arg):
    return arg

res = interp.call(run, 'spam!')
print(res)

def run():
    print('spam!')

interp.call(run)

# Run in new OS thread.

t = interp.call_in_thread(run)
t.join()
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node subprocess — Subprocess management,sched — Event scheduler,concurrent interpreters — Multiple interpreters in the same process,Concurrent Execution
@anchor{library/subprocess doc}@anchor{396e}@anchor{library/subprocess module-subprocess}@anchor{df}@anchor{library/subprocess subprocess-subprocess-management}@anchor{396f}@anchor{library/subprocess translation-repo}@anchor{3970}
@subsection @code{subprocess} — Subprocess management


@geindex module; subprocess

`Source code:' Lib/subprocess.py@footnote{https://github.com/python/cpython/tree/main/Lib/subprocess.py}


__________________________________________________________________


The @code{subprocess} module allows you to spawn new processes, connect to their
input/output/error pipes, and obtain their return codes.  This module intends to
replace several older modules and functions:

@example
os.system
os.spawn*
@end example

Information about how the @code{subprocess} module can be used to replace these
modules and functions can be found in the following sections.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 324
PEP 324@footnote{https://peps.python.org/pep-0324/} – PEP proposing the subprocess module


@c include for modules that don't work on WASM or mobile platforms

@ref{232d,,Διαθεσιμότητα}: not Android, not iOS, not WASI.

This module is not supported on @ref{244d,,mobile platforms}
or @ref{1d67,,WebAssembly platforms}.

@menu
* Using the subprocess Module:: 
* Security Considerations:: 
* Popen Objects:: 
* Windows Popen Helpers:: 
* Older high-level API:: 
* Replacing Older Functions with the subprocess Module:: 
* Legacy Shell Invocation Functions:: 
* Notes: Notes<2>. 

@end menu

@node Using the subprocess Module,Security Considerations,,subprocess — Subprocess management
@anchor{library/subprocess using-the-subprocess-module}@anchor{3971}
@subsubsection Using the @code{subprocess} Module


The recommended approach to invoking subprocesses is to use the @ref{f45,,run()}
function for all use cases it can handle. For more advanced use cases, the
underlying @ref{6bf,,Popen} interface can be used directly.

@geindex run() (στη μονάδα subprocess)
@anchor{library/subprocess subprocess run}@anchor{f45}
@deffn {Συνάρτηση} 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)

Run the command described by `args'.  Wait for command to complete, then
return a @ref{1224,,CompletedProcess} instance.

The arguments shown above are merely the most common ones, described below
in @ref{3972,,Frequently Used Arguments} (hence the use of keyword-only notation
in the abbreviated signature). The full function signature is largely the
same as that of the @ref{6bf,,Popen} constructor - most of the arguments to
this function are passed through to that interface. (`timeout',  `input',
`check', and `capture_output' are not.)

If `capture_output' is true, stdout and stderr will be captured.
When used, the internal @ref{6bf,,Popen} object is automatically created with
`stdout' and `stderr' both set to @ref{f46,,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 @code{PIPE}
and `stderr' to @ref{3973,,STDOUT},
instead of using `capture_output'.

A `timeout' may be specified in seconds, it is internally passed on to
@ref{19aa,,Popen.communicate()}. If the timeout expires, the child process will be
killed and waited for. The @ref{19ab,,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{19aa,,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{6bf,,Popen} object is automatically created with
`stdin' set to @ref{f46,,PIPE},
and the `stdin' argument may not be used as well.

If `check' is true, and the process exits with a non-zero exit code, a
@ref{16c9,,CalledProcessError} exception will be raised. Attributes of that
exception hold the arguments, the exit code, and stdout and stderr if they
were captured.

If `encoding' or `errors' are specified, or `text' is true,
file objects for stdin, stdout and stderr are opened in text mode using the
specified `encoding' and `errors' or the @ref{b9c,,io.TextIOWrapper} default.
The `universal_newlines' argument is equivalent  to `text' and is provided
for backwards compatibility. By default, file objects are opened in binary mode.

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{6bf,,Popen}. This mapping can be str to str on any platform
or bytes to bytes on POSIX platforms much like @ref{4e5,,os.environ} or
@ref{4e6,,os.environb}.

Examples:

@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


Added in version 3.5.



Άλλαξε στην έκδοση 3.6: Added `encoding' and `errors' parameters



Άλλαξε στην έκδοση 3.7: Added the `text' parameter, as a more understandable alias of `universal_newlines'.
Added the `capture_output' parameter.



Άλλαξε στην έκδοση 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 (κλάση σε subprocess)
@anchor{library/subprocess subprocess CompletedProcess}@anchor{1224}
@deffn {Κλάση} subprocess.CompletedProcess

The return value from @ref{f45,,run()}, representing a process that has finished.

@geindex args (ιδιότητα της subprocess.CompletedProcess)
@anchor{library/subprocess subprocess CompletedProcess args}@anchor{3974}
@deffn {Ιδιότητα} args

The arguments used to launch the process. This may be a list or a string.
@end deffn

@geindex returncode (ιδιότητα της subprocess.CompletedProcess)
@anchor{library/subprocess subprocess CompletedProcess returncode}@anchor{3975}
@deffn {Ιδιότητα} returncode

Exit status of the child process. Typically, an exit status of 0 indicates
that it ran successfully.

A negative value @code{-N} indicates that the child was terminated by signal
@code{N} (POSIX only).
@end deffn

@geindex stdout (ιδιότητα της subprocess.CompletedProcess)
@anchor{library/subprocess subprocess CompletedProcess stdout}@anchor{3976}
@deffn {Ιδιότητα} stdout

Captured stdout from the child process. A bytes sequence, or a string if
@ref{f45,,run()} was called with an encoding, errors, or text=True.
@code{None} if stdout was not captured.

If you ran the process with @code{stderr=subprocess.STDOUT}, stdout and
stderr will be combined in this attribute, and @ref{3977,,stderr} will be
@code{None}.
@end deffn

@geindex stderr (ιδιότητα της subprocess.CompletedProcess)
@anchor{library/subprocess subprocess CompletedProcess stderr}@anchor{3977}
@deffn {Ιδιότητα} stderr

Captured stderr from the child process. A bytes sequence, or a string if
@ref{f45,,run()} was called with an encoding, errors, or text=True.
@code{None} if stderr was not captured.
@end deffn

@geindex check_returncode() (μέθοδος της subprocess.CompletedProcess)
@anchor{library/subprocess subprocess CompletedProcess check_returncode}@anchor{3978}
@deffn {Μέθοδος} check_returncode ()

If @ref{3975,,returncode} is non-zero, raise a @ref{16c9,,CalledProcessError}.
@end deffn


Added in version 3.5.

@end deffn

@geindex DEVNULL (στη μονάδα subprocess)
@anchor{library/subprocess subprocess DEVNULL}@anchor{14f9}
@deffn {Δεδομένα} subprocess.DEVNULL

Special value that can be used as the `stdin', `stdout' or `stderr' argument
to @ref{6bf,,Popen} and indicates that the special file @ref{2002,,os.devnull}
will be used.


Added in version 3.3.

@end deffn

@geindex PIPE (στη μονάδα subprocess)
@anchor{library/subprocess subprocess PIPE}@anchor{f46}
@deffn {Δεδομένα} subprocess.PIPE

Special value that can be used as the `stdin', `stdout' or `stderr' argument
to @ref{6bf,,Popen} and indicates that a pipe to the standard stream should be
opened.  Most useful with @ref{19aa,,Popen.communicate()}.
@end deffn

@geindex STDOUT (στη μονάδα subprocess)
@anchor{library/subprocess subprocess STDOUT}@anchor{3973}
@deffn {Δεδομένα} subprocess.STDOUT

Special value that can be used as the `stderr' argument to @ref{6bf,,Popen} and
indicates that standard error should go into the same handle as standard
output.
@end deffn

@geindex SubprocessError
@anchor{library/subprocess subprocess SubprocessError}@anchor{3979}
@deffn {Εξαίρεση} subprocess.SubprocessError

Base class for all other exceptions from this module.


Added in version 3.3.

@end deffn

@geindex TimeoutExpired
@anchor{library/subprocess subprocess TimeoutExpired}@anchor{19ab}
@deffn {Εξαίρεση} subprocess.TimeoutExpired

Subclass of @ref{3979,,SubprocessError}, raised when a timeout expires
while waiting for a child process.

@geindex cmd (ιδιότητα της subprocess.TimeoutExpired)
@anchor{library/subprocess subprocess TimeoutExpired cmd}@anchor{397a}
@deffn {Ιδιότητα} cmd

Command that was used to spawn the child process.
@end deffn

@geindex timeout (ιδιότητα της subprocess.TimeoutExpired)
@anchor{library/subprocess subprocess TimeoutExpired timeout}@anchor{397b}
@deffn {Ιδιότητα} timeout

Timeout in seconds.
@end deffn

@geindex output (ιδιότητα της subprocess.TimeoutExpired)
@anchor{library/subprocess subprocess TimeoutExpired output}@anchor{397c}
@deffn {Ιδιότητα} output

Output of the child process if it was captured by @ref{f45,,run()} or
@ref{136b,,check_output()}.  Otherwise, @code{None}.  This is always
@ref{1c7,,bytes} when any output was captured regardless of the
@code{text=True} setting.  It may remain @code{None} instead of @code{b'@w{'}}
when no output was observed.
@end deffn

@geindex stdout (ιδιότητα της subprocess.TimeoutExpired)
@anchor{library/subprocess subprocess TimeoutExpired stdout}@anchor{397d}
@deffn {Ιδιότητα} stdout

Alias for output, for symmetry with @ref{397e,,stderr}.
@end deffn

@geindex stderr (ιδιότητα της subprocess.TimeoutExpired)
@anchor{library/subprocess subprocess TimeoutExpired stderr}@anchor{397e}
@deffn {Ιδιότητα} stderr

Stderr output of the child process if it was captured by @ref{f45,,run()}.
Otherwise, @code{None}.  This is always @ref{1c7,,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


Added in version 3.3.



Άλλαξε στην έκδοση 3.5: `stdout' and `stderr' attributes added

@end deffn

@geindex CalledProcessError
@anchor{library/subprocess subprocess CalledProcessError}@anchor{16c9}
@deffn {Εξαίρεση} subprocess.CalledProcessError

Subclass of @ref{3979,,SubprocessError}, raised when a process run by
@ref{397f,,check_call()}, @ref{136b,,check_output()}, or @ref{f45,,run()} (with @code{check=True})
returns a non-zero exit status.

@geindex returncode (ιδιότητα της subprocess.CalledProcessError)
@anchor{library/subprocess subprocess CalledProcessError returncode}@anchor{3980}
@deffn {Ιδιότητα} returncode

Exit status of the child process.  If the process exited due to a
signal, this will be the negative signal number.
@end deffn

@geindex cmd (ιδιότητα της subprocess.CalledProcessError)
@anchor{library/subprocess subprocess CalledProcessError cmd}@anchor{3981}
@deffn {Ιδιότητα} cmd

Command that was used to spawn the child process.
@end deffn

@geindex output (ιδιότητα της subprocess.CalledProcessError)
@anchor{library/subprocess subprocess CalledProcessError output}@anchor{3982}
@deffn {Ιδιότητα} output

Output of the child process if it was captured by @ref{f45,,run()} or
@ref{136b,,check_output()}.  Otherwise, @code{None}.
@end deffn

@geindex stdout (ιδιότητα της subprocess.CalledProcessError)
@anchor{library/subprocess subprocess CalledProcessError stdout}@anchor{3983}
@deffn {Ιδιότητα} stdout

Alias for output, for symmetry with @ref{3984,,stderr}.
@end deffn

@geindex stderr (ιδιότητα της subprocess.CalledProcessError)
@anchor{library/subprocess subprocess CalledProcessError stderr}@anchor{3984}
@deffn {Ιδιότητα} stderr

Stderr output of the child process if it was captured by @ref{f45,,run()}.
Otherwise, @code{None}.
@end deffn


Άλλαξε στην έκδοση 3.5: `stdout' and `stderr' attributes added

@end deffn

@menu
* Frequently Used Arguments:: 
* Popen Constructor:: 
* Exceptions: Exceptions<13>. 

@end menu

@node Frequently Used Arguments,Popen Constructor,,Using the subprocess Module
@anchor{library/subprocess frequently-used-arguments}@anchor{3972}@anchor{library/subprocess id1}@anchor{3985}
@subsubsection Frequently Used Arguments


To support a wide variety of use cases, the @ref{6bf,,Popen} constructor (and
the convenience functions) accept a large number of optional arguments. For
most typical use cases, many of these arguments can be safely left at their
default values. The arguments that are most commonly needed are:

@quotation

`args' is required for all calls and should be a string, or a sequence of
program arguments. Providing a sequence of arguments is generally
preferred, as it allows the module to take care of any required escaping
and quoting of arguments (e.g. to permit spaces in file names). If passing
a single string, either `shell' must be @ref{fcc,,True} (see below) or else
the string must simply name the program to be executed without specifying
any arguments.

`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{f46,,PIPE}, @ref{14f9,,DEVNULL}, an existing file descriptor (a
positive integer), and an existing @ref{156c,,file object} with a valid file
descriptor.  With the default settings of @code{None}, no redirection will
occur.  @code{PIPE} indicates that a new pipe to the child should be
created.  @code{DEVNULL} indicates that the special file @ref{2002,,os.devnull}
will be used.  Additionally, `stderr' can be @ref{3973,,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

If `encoding' or `errors' are specified, or `text' (also known as
`universal_newlines') is true,
the file objects `stdin', `stdout' and `stderr' will be opened in text
mode using the `encoding' and `errors' specified in the call or the
defaults for @ref{b9c,,io.TextIOWrapper}.

For `stdin', line ending characters @code{'\n'} in the input will be converted
to the default line separator @ref{27d5,,os.linesep}. For `stdout' and `stderr',
all line endings in the output will be converted to @code{'\n'}.  For more
information see the documentation of the @ref{b9c,,io.TextIOWrapper} class
when the `newline' argument to its constructor is @code{None}.

If text mode is not used, `stdin', `stdout' and `stderr' will be opened as
binary streams. No encoding or line ending conversion is performed.


Άλλαξε στην έκδοση 3.6: Added the `encoding' and `errors' parameters.



Άλλαξε στην έκδοση 3.7: Added the `text' parameter as an alias for `universal_newlines'.


@cartouche
@quotation Σημείωση 
The newlines attribute of the file objects @ref{3986,,Popen.stdin},
@ref{3987,,Popen.stdout} and @ref{3988,,Popen.stderr} are not updated by
the @ref{19aa,,Popen.communicate()} method.
@end quotation
@end cartouche

If `shell' is @code{True}, the specified command will be executed through
the shell.  This can be useful if you are using Python primarily for the
enhanced control flow it offers over most system shells and still want
convenient access to other shell features such as shell pipes, filename
wildcards, environment variable expansion, and expansion of @code{~} to a
user’s home directory.  However, note that Python itself offers
implementations of many shell-like features (in particular, @ref{67,,glob},
@ref{5f,,fnmatch}, @ref{8b9,,os.walk()}, @ref{177c,,os.path.expandvars()},
@ref{dd8,,os.path.expanduser()}, and @ref{cd,,shutil}).


Άλλαξε στην έκδοση 3.3: When `universal_newlines' is @code{True}, the class uses the encoding
@ref{947,,locale.getpreferredencoding(False)}
instead of @code{locale.getpreferredencoding()}.  See the
@ref{b9c,,io.TextIOWrapper} class for more information on this change.


@cartouche
@quotation Σημείωση 
Read the @ref{3989,,Security Considerations} section before using @code{shell=True}.
@end quotation
@end cartouche
@end quotation

These options, along with all of the other options, are described in more
detail in the @ref{6bf,,Popen} constructor documentation.

@node Popen Constructor,Exceptions<13>,Frequently Used Arguments,Using the subprocess Module
@anchor{library/subprocess popen-constructor}@anchor{398a}
@subsubsection Popen Constructor


The underlying process creation and management in this module is handled by
the @ref{6bf,,Popen} class. It offers a lot of flexibility so that developers
are able to handle the less common cases not covered by the convenience
functions.

@geindex Popen (κλάση σε subprocess)
@anchor{library/subprocess subprocess Popen}@anchor{6bf}
@deffn {Κλάση} 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{3316,,os.execvpe()}-like behavior to execute the child program.  On Windows,
the class uses the Windows @code{CreateProcess()} function.  The arguments to
@code{Popen} are as follows.

`args' should be a sequence of program arguments or else a single string
or @ref{79f,,path-like object}.
By default, the program to execute is the first item in `args' if `args' is
a sequence.  If `args' is a string, the interpretation is
platform-dependent and described below.  See the `shell' and `executable'
arguments for additional differences from the default behavior.  Unless
otherwise stated, it is recommended to pass `args' as a sequence.

@cartouche
@quotation Προειδοποίηση 
For maximum reliability, use a fully qualified path for the executable.
To search for an unqualified name on 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}, use
@ref{8c4,,shutil.which()}. On all platforms, passing @ref{3ac,,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{3316,,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

An example of passing some arguments to an external program
as a sequence is:

@example
Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])
@end example

On POSIX, if `args' is a string, the string is interpreted as the name or
path of the program to execute.  However, this can only be done if not
passing arguments to the program.

@cartouche
@quotation Σημείωση 
It may not be obvious how to break a shell command into a sequence of arguments,
especially in complex cases. @ref{949,,shlex.split()} can illustrate how to
determine the correct tokenization for `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

Note in particular that options (such as `-input') and arguments (such
as `eggs.txt') that are separated by whitespace in the shell go in separate
list elements, while arguments that need quoting or backslash escaping when
used in the shell (such as filenames containing spaces or the `echo' command
shown above) are single list elements.
@end quotation
@end cartouche

On Windows, if `args' is a sequence, it will be converted to a string in a
manner described in @ref{398b,,Converting an argument sequence to a string on Windows}.  This is because
the underlying @code{CreateProcess()} operates on strings.


Άλλαξε στην έκδοση 3.6: `args' parameter accepts a @ref{79f,,path-like object} if `shell' is
@code{False} and a sequence containing path-like objects on POSIX.



Άλλαξε στην έκδοση 3.8: `args' parameter accepts a @ref{79f,,path-like object} if `shell' is
@code{False} and a sequence containing bytes and path-like objects
on Windows.


The `shell' argument (which defaults to @code{False}) specifies whether to use
the shell as the program to execute.  If `shell' is @code{True}, it is
recommended to pass `args' as a string rather than as a sequence.

On POSIX with @code{shell=True}, the shell defaults to @code{/bin/sh}.  If
`args' is a string, the string specifies the command
to execute through the shell.  This means that the string must be
formatted exactly as it would be when typed at the shell prompt.  This
includes, for example, quoting or backslash escaping filenames with spaces in
them.  If `args' is a sequence, the first item specifies the command string, and
any additional items will be treated as additional arguments to the shell
itself.  That is to say, @code{Popen} does the equivalent of:

@example
Popen(['/bin/sh', '-c', args[0], args[1], ...])
@end example

On Windows with @code{shell=True}, the 
@geindex COMSPEC
@geindex μεταβλητή περιβάλλοντος; COMSPEC
@code{COMSPEC} environment variable
specifies the default shell.  The only time you need to specify
@code{shell=True} on Windows is when the command you wish to execute is built
into the shell (e.g. @code{dir} or @code{copy}).  You do not need
@code{shell=True} to run a batch file or console-based executable.

@cartouche
@quotation Σημείωση 
Read the @ref{3989,,Security Considerations} section before using @code{shell=True}.
@end quotation
@end cartouche

`bufsize' will be supplied as the corresponding argument to the
@ref{32b,,open()} function when creating the stdin/stdout/stderr pipe
file objects:


@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 
any other positive value means use a buffer of approximately that
size

@item 
negative bufsize (the default) means the system default of
io.DEFAULT_BUFFER_SIZE will be used.
@end itemize


Άλλαξε στην έκδοση 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.


The `executable' argument specifies a replacement program to execute.   It
is very seldom needed.  When @code{shell=False}, `executable' replaces the
program to execute specified by `args'.  However, the original `args' is
still passed to the program.  Most programs treat the program specified
by `args' as the command name, which can then be different from the program
actually executed.  On POSIX, the `args' name
becomes the display name for the executable in utilities such as
@code{ps}.  If @code{shell=True}, on POSIX the `executable' argument
specifies a replacement shell for the default @code{/bin/sh}.


Άλλαξε στην έκδοση 3.6: `executable' parameter accepts a @ref{79f,,path-like object} on POSIX.



Άλλαξε στην έκδοση 3.8: `executable' parameter accepts a bytes and @ref{79f,,path-like object}
on Windows.



Άλλαξε στην έκδοση 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{f46,,PIPE}, @ref{14f9,,DEVNULL}, an existing file descriptor (a
positive integer), and an existing @ref{156c,,file object} with a valid file
descriptor.  With the default settings of @code{None}, no redirection will
occur.  @code{PIPE} indicates that a new pipe to the child should be
created.  @code{DEVNULL} indicates that the special file @ref{2002,,os.devnull}
will be used.  Additionally, `stderr' can be @ref{3973,,STDOUT}, which indicates
that the stderr data from the applications should be captured into the same
file handle as for `stdout'.

If `preexec_fn' is set to a callable object, this object will be called in the
child process just before the child is executed.
(POSIX only)

@cartouche
@quotation Προειδοποίηση 
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 Σημείωση 
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{1faa,,os.setsid()} or @ref{3244,,os.setpgid()} in the child.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.8: The `preexec_fn' parameter is no longer supported in subinterpreters.
The use of the parameter in a subinterpreter raises
@ref{30d,,RuntimeError}. The new restriction may affect applications that
are deployed in mod_wsgi, uWSGI, and other embedded environments.


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{12aa,,Inheritance of File Descriptors}.

On Windows, if `close_fds' is true then no handles will be inherited by the
child process unless explicitly passed in the @code{handle_list} element of
@ref{fcd,,STARTUPINFO.lpAttributeList}, or by standard handle redirection.


Άλλαξε στην έκδοση 3.2: The default for `close_fds' was changed from @ref{ef5,,False} to
what is described above.



Άλλαξε στην έκδοση 3.7: On Windows the default for `close_fds' was changed from @ref{ef5,,False} to
@ref{fcc,,True} when redirecting the standard handles. It’s now possible to
set `close_fds' to @code{True} when redirecting the standard handles.


`pass_fds' is an optional sequence of file descriptors to keep open
between the parent and child.  Providing any `pass_fds' forces
`close_fds' to be @ref{fcc,,True}.  (POSIX only)


Άλλαξε στην έκδοση 3.2: The `pass_fds' parameter was added.


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{79f,,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.


Άλλαξε στην έκδοση 3.6: `cwd' parameter accepts a @ref{79f,,path-like object} on POSIX.



Άλλαξε στην έκδοση 3.7: `cwd' parameter accepts a @ref{79f,,path-like object} on Windows.



Άλλαξε στην έκδοση 3.8: `cwd' parameter accepts a bytes object on Windows.


If `restore_signals' is true (the default) all signals that Python has set to
SIG_IGN are restored to SIG_DFL in the child process before the exec.
Currently this includes the SIGPIPE, SIGXFZ and SIGXFSZ signals.
(POSIX only)


Άλλαξε στην έκδοση 3.2: `restore_signals' was added.


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{232d,,Διαθεσιμότητα}: POSIX


Άλλαξε στην έκδοση 3.2: `start_new_session' was added.


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{232d,,Διαθεσιμότητα}: POSIX


Άλλαξε στην έκδοση 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{398c,,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{232d,,Διαθεσιμότητα}: POSIX


Added in 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{398c,,grp.getgrnam()} and the values in @code{gr_gid} will be used.
Integer values will be passed verbatim. (POSIX only)

@ref{232d,,Διαθεσιμότητα}: POSIX


Added in 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{398d,,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)

@cartouche
@quotation Σημείωση 
Specifying `user' will not drop existing supplementary group memberships!
The caller must also pass @code{extra_groups=()} to reduce the group membership
of the child process for security purposes.
@end quotation
@end cartouche

@ref{232d,,Διαθεσιμότητα}: POSIX


Added in 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{232d,,Διαθεσιμότητα}: POSIX


Added in 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{4e5,,os.environ} or @ref{4e6,,os.environb}.

@cartouche
@quotation Σημείωση 
If specified, `env' must provide any variables required for the program to
execute.  On Windows, in order to run a side-by-side assembly@footnote{https://en.wikipedia.org/wiki/Side-by-Side_Assembly} the
specified `env' `must' include a valid @code{%SystemRoot%}.
@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{3972,,Frequently Used Arguments}.
The `universal_newlines' argument is equivalent  to `text' and is provided
for backwards compatibility. By default, file objects are opened in binary mode.


Added in version 3.6: `encoding' and `errors' were added.



Added in version 3.7: `text' was added as a more readable alias for `universal_newlines'.


If given, `startupinfo' will be a @ref{398e,,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{398f,,CREATE_NEW_CONSOLE}

@item 
@ref{3990,,CREATE_NEW_PROCESS_GROUP}

@item 
@ref{3991,,ABOVE_NORMAL_PRIORITY_CLASS}

@item 
@ref{3992,,BELOW_NORMAL_PRIORITY_CLASS}

@item 
@ref{3993,,HIGH_PRIORITY_CLASS}

@item 
@ref{3994,,IDLE_PRIORITY_CLASS}

@item 
@ref{3995,,NORMAL_PRIORITY_CLASS}

@item 
@ref{3996,,REALTIME_PRIORITY_CLASS}

@item 
@ref{3997,,CREATE_NO_WINDOW}

@item 
@ref{3998,,DETACHED_PROCESS}

@item 
@ref{3999,,CREATE_DEFAULT_ERROR_MODE}

@item 
@ref{399a,,CREATE_BREAKAWAY_FROM_JOB}
@end itemize

`pipesize' can be used to change the size of the pipe when
@ref{f46,,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.


Άλλαξε στην έκδοση 3.10: Added the `pipesize' parameter.


Popen objects are supported as context managers via the @ref{20a,,with} statement:
on exit, standard file descriptors are closed, and the process is waited for.

@example
with Popen(["ifconfig"], stdout=PIPE) as proc:
    log.write(proc.stdout.read())
@end example


Popen and the other functions in this module that use it raise an
@ref{1e65,,auditing event} @code{subprocess.Popen} with arguments
@code{executable}, @code{args}, @code{cwd}, and @code{env}. The value for @code{args}
may be a single string or a list of strings, depending on platform.



Άλλαξε στην έκδοση 3.2: Added context manager support.



Άλλαξε στην έκδοση 3.6: Popen destructor now emits a @ref{74f,,ResourceWarning} warning if the child
process is still running.



Άλλαξε στην έκδοση 3.8: Popen can use @ref{731,,os.posix_spawn()} in some cases for better
performance. On Windows Subsystem for Linux and QEMU User Emulation,
Popen constructor using @code{os.posix_spawn()} no longer raise an
exception on errors like missing program, but the child process fails
with a non-zero @ref{e52,,returncode}.

@end deffn

@node Exceptions<13>,,Popen Constructor,Using the subprocess Module
@anchor{library/subprocess exceptions}@anchor{399b}
@subsubsection Exceptions


Exceptions raised in the child process, before the new program has started to
execute, will be re-raised in the parent.

The most common exception raised is @ref{53c,,OSError}.  This occurs, for example,
when trying to execute a non-existent file.  Applications should prepare for
@code{OSError} exceptions. Note that, when @code{shell=True}, @code{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.

A @ref{277,,ValueError} will be raised if @ref{6bf,,Popen} is called with invalid
arguments.

@ref{397f,,check_call()} and @ref{136b,,check_output()} will raise
@ref{16c9,,CalledProcessError} if the called process returns a non-zero return
code.

All of the functions and methods that accept a `timeout' parameter, such as
@ref{f45,,run()} and @ref{19aa,,Popen.communicate()} will raise @ref{19ab,,TimeoutExpired} if
the timeout expires before the process exits.

Exceptions defined in this module all inherit from @ref{3979,,SubprocessError}.


Added in version 3.3: The @ref{3979,,SubprocessError} base class was added.


@node Security Considerations,Popen Objects,Using the subprocess Module,subprocess — Subprocess management
@anchor{library/subprocess security-considerations}@anchor{3989}@anchor{library/subprocess subprocess-security}@anchor{399c}
@subsubsection Security Considerations


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{399d,,some platforms}, it is possible
to use @ref{781,,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 Popen Objects,Windows Popen Helpers,Security Considerations,subprocess — Subprocess management
@anchor{library/subprocess popen-objects}@anchor{399e}
@subsubsection Popen Objects


Instances of the @ref{6bf,,Popen} class have the following methods:

@geindex poll() (μέθοδος της subprocess.Popen)
@anchor{library/subprocess subprocess Popen poll}@anchor{399f}
@deffn {Μέθοδος} Popen.poll ()

Check if child process has terminated.  Set and return
@ref{e52,,returncode} attribute. Otherwise, returns @code{None}.
@end deffn

@geindex wait() (μέθοδος της subprocess.Popen)
@anchor{library/subprocess subprocess Popen wait}@anchor{266}
@deffn {Μέθοδος} Popen.wait (timeout=None)

Wait for child process to terminate.  Set and return
@ref{e52,,returncode} attribute.

If the process does not terminate after `timeout' seconds, raise a
@ref{19ab,,TimeoutExpired} exception.  It is safe to catch this exception and
retry the wait.

@cartouche
@quotation Σημείωση 
This will deadlock when using @code{stdout=PIPE} or @code{stderr=PIPE}
and the child process generates enough output to a pipe such that
it blocks waiting for the OS pipe buffer to accept more data.
Use @ref{19aa,,Popen.communicate()} when using pipes to avoid that.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
When @code{timeout} is not @code{None} and the platform supports it, an
efficient event-driven mechanism is used to wait for process termination:


@itemize -

@item 
Linux >= 5.3 uses @ref{267,,os.pidfd_open()} + @ref{268,,select.poll()}

@item 
macOS and other BSD variants use @ref{269,,select.kqueue()} +
@code{KQ_FILTER_PROC} + @code{KQ_NOTE_EXIT}

@item 
Windows uses @code{WaitForSingleObject}
@end itemize

If none of these mechanisms are available, the function falls back to a
busy loop (non-blocking call and short sleeps).
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Use the @ref{b,,asyncio} module for an asynchronous wait: see
@ref{e3a,,asyncio.create_subprocess_exec}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: `timeout' was added.



Άλλαξε στην έκδοση 3.15: if `timeout' is not @code{None}, use efficient event-driven implementation
on Linux >= 5.3 and macOS / BSD.

@end deffn

@geindex communicate() (μέθοδος της subprocess.Popen)
@anchor{library/subprocess subprocess Popen communicate}@anchor{19aa}
@deffn {Μέθοδος} 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{e52,,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.

@code{communicate()} returns a tuple @code{(stdout_data, stderr_data)}.
The data will be strings if streams were opened in text mode; otherwise,
bytes.

Note that if you want to send data to the process’s stdin, you need to create
the Popen object with @code{stdin=PIPE}.  Similarly, to get anything other than
@code{None} in the result tuple, you need to give @code{stdout=PIPE} and/or
@code{stderr=PIPE} too.

If the process does not terminate after `timeout' seconds, a
@ref{19ab,,TimeoutExpired} exception will be raised.  Catching this exception and
retrying communication will not lose any output.  Supplying `input' to a
subsequent post-timeout @code{communicate()} call is in undefined behavior
and may become an error in the future.

The child process is not killed if the timeout expires, so in order to
cleanup properly a well-behaved application should kill the child process and
finish communication:

@example
proc = subprocess.Popen(...)
try:
    outs, errs = proc.communicate(timeout=15)
except TimeoutExpired:
    proc.kill()
    outs, errs = proc.communicate()
@end example

After a call to @code{communicate()} raises @ref{19ab,,TimeoutExpired}, do
not call @ref{266,,wait()}. Use an additional @code{communicate()}
call to finish handling pipes and populate the @ref{e52,,returncode}
attribute.

@cartouche
@quotation Σημείωση 
The data read is buffered in memory, so do not use this method if the data
size is large or unlimited.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: `timeout' was added.

@end deffn

@geindex send_signal() (μέθοδος της subprocess.Popen)
@anchor{library/subprocess subprocess Popen send_signal}@anchor{1781}
@deffn {Μέθοδος} Popen.send_signal (signal)

Sends the signal `signal' to the child.

Do nothing if the process completed.

@cartouche
@quotation Σημείωση 
On Windows, SIGTERM is an alias for @ref{177f,,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() (μέθοδος της subprocess.Popen)
@anchor{library/subprocess subprocess Popen terminate}@anchor{177f}
@deffn {Μέθοδος} Popen.terminate ()

Stop the child. On POSIX OSs the method sends @ref{1782,,SIGTERM} to the
child. On Windows the Win32 API function @code{TerminateProcess()} is called
to stop the child.
@end deffn

@geindex kill() (μέθοδος της subprocess.Popen)
@anchor{library/subprocess subprocess Popen kill}@anchor{1780}
@deffn {Μέθοδος} Popen.kill ()

Kills the child. On POSIX OSs the function sends SIGKILL to the child.
On Windows @code{kill()} is an alias for @ref{177f,,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 (ιδιότητα της subprocess.Popen)
@anchor{library/subprocess subprocess Popen args}@anchor{39a0}
@deffn {Ιδιότητα} Popen.args

The `args' argument as it was passed to @ref{6bf,,Popen} – a
sequence of program arguments or else a single string.


Added in version 3.3.

@end deffn

@geindex stdin (ιδιότητα της subprocess.Popen)
@anchor{library/subprocess subprocess Popen stdin}@anchor{3986}
@deffn {Ιδιότητα} Popen.stdin

If the `stdin' argument was @ref{f46,,PIPE}, this attribute is a writeable
stream object as returned by @ref{32b,,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 @code{PIPE}, this attribute is @code{None}.
@end deffn

@geindex stdout (ιδιότητα της subprocess.Popen)
@anchor{library/subprocess subprocess Popen stdout}@anchor{3987}
@deffn {Ιδιότητα} Popen.stdout

If the `stdout' argument was @ref{f46,,PIPE}, this attribute is a readable
stream object as returned by @ref{32b,,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 @code{PIPE}, this attribute is @code{None}.
@end deffn

@geindex stderr (ιδιότητα της subprocess.Popen)
@anchor{library/subprocess subprocess Popen stderr}@anchor{3988}
@deffn {Ιδιότητα} Popen.stderr

If the `stderr' argument was @ref{f46,,PIPE}, this attribute is a readable
stream object as returned by @ref{32b,,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 @code{PIPE}, this attribute is @code{None}.
@end deffn

@cartouche
@quotation Προειδοποίηση 
Use @ref{19aa,,communicate()} rather than @ref{3986,,.stdin.write},
@ref{3987,,.stdout.read} or @ref{3988,,.stderr.read} to avoid
deadlocks due to any of the other OS pipe buffers filling up and blocking the
child process.
@end quotation
@end cartouche

@geindex pid (ιδιότητα της subprocess.Popen)
@anchor{library/subprocess subprocess Popen pid}@anchor{39a1}
@deffn {Ιδιότητα} Popen.pid

The process ID of the child process.

Note that if you set the `shell' argument to @code{True}, this is the process ID
of the spawned shell.
@end deffn

@geindex returncode (ιδιότητα της subprocess.Popen)
@anchor{library/subprocess subprocess Popen returncode}@anchor{e52}
@deffn {Ιδιότητα} Popen.returncode

The child return code. Initially @code{None}, @ref{e52,,returncode} is set by
a call to the @ref{399f,,poll()}, @ref{266,,wait()}, or @ref{19aa,,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.

A negative value @code{-N} indicates that the child was terminated by signal
@code{N} (POSIX only).

When @code{shell=True}, the return code reflects the exit status of the shell
itself (e.g. @code{/bin/sh}), which may map signals to codes such as
@code{128+N}. See the documentation of the shell (for example, the Bash
manual’s Exit Status) for details.
@end deffn

@node Windows Popen Helpers,Older high-level API,Popen Objects,subprocess — Subprocess management
@anchor{library/subprocess windows-popen-helpers}@anchor{39a2}
@subsubsection Windows Popen Helpers


The @ref{398e,,STARTUPINFO} class and following constants are only available
on Windows.

@geindex STARTUPINFO (κλάση σε subprocess)
@anchor{library/subprocess subprocess STARTUPINFO}@anchor{398e}
@deffn {Κλάση} subprocess.STARTUPINFO (*, dwFlags=0, hStdInput=None, hStdOutput=None, hStdError=None, wShowWindow=0, lpAttributeList=None)

Partial support of the Windows
STARTUPINFO@footnote{https://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx}
structure is used for @ref{6bf,,Popen} creation.  The following attributes can
be set by passing them as keyword-only arguments.


Άλλαξε στην έκδοση 3.7: Keyword-only argument support was added.


@geindex dwFlags (ιδιότητα της subprocess.STARTUPINFO)
@anchor{library/subprocess subprocess STARTUPINFO dwFlags}@anchor{39a3}
@deffn {Ιδιότητα} dwFlags

A bit field that determines whether certain @code{STARTUPINFO}
attributes are used when the process creates a window.

@example
si = subprocess.STARTUPINFO()
si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW
@end example
@end deffn

@geindex hStdInput (ιδιότητα της subprocess.STARTUPINFO)
@anchor{library/subprocess subprocess STARTUPINFO hStdInput}@anchor{39a4}
@deffn {Ιδιότητα} hStdInput

If @ref{39a3,,dwFlags} specifies @ref{39a5,,STARTF_USESTDHANDLES}, this attribute
is the standard input handle for the process. If
@code{STARTF_USESTDHANDLES} is not specified, the default for standard
input is the keyboard buffer.
@end deffn

@geindex hStdOutput (ιδιότητα της subprocess.STARTUPINFO)
@anchor{library/subprocess subprocess STARTUPINFO hStdOutput}@anchor{39a6}
@deffn {Ιδιότητα} hStdOutput

If @ref{39a3,,dwFlags} specifies @ref{39a5,,STARTF_USESTDHANDLES}, this attribute
is the standard output handle for the process. Otherwise, this attribute
is ignored and the default for standard output is the console window’s
buffer.
@end deffn

@geindex hStdError (ιδιότητα της subprocess.STARTUPINFO)
@anchor{library/subprocess subprocess STARTUPINFO hStdError}@anchor{39a7}
@deffn {Ιδιότητα} hStdError

If @ref{39a3,,dwFlags} specifies @ref{39a5,,STARTF_USESTDHANDLES}, this attribute
is the standard error handle for the process. Otherwise, this attribute is
ignored and the default for standard error is the console window’s buffer.
@end deffn

@geindex wShowWindow (ιδιότητα της subprocess.STARTUPINFO)
@anchor{library/subprocess subprocess STARTUPINFO wShowWindow}@anchor{39a8}
@deffn {Ιδιότητα} wShowWindow

If @ref{39a3,,dwFlags} specifies @ref{39a9,,STARTF_USESHOWWINDOW}, this attribute
can be any of the values that can be specified in the @code{nCmdShow}
parameter for the
ShowWindow@footnote{https://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx}
function, except for @code{SW_SHOWDEFAULT}. Otherwise, this attribute is
ignored.

@ref{39aa,,SW_HIDE} is provided for this attribute. It is used when
@ref{6bf,,Popen} is called with @code{shell=True}.
@end deffn

@geindex lpAttributeList (ιδιότητα της subprocess.STARTUPINFO)
@anchor{library/subprocess subprocess STARTUPINFO lpAttributeList}@anchor{fcd}
@deffn {Ιδιότητα} lpAttributeList

A dictionary of additional attributes for process creation as given in
@code{STARTUPINFOEX}, see
UpdateProcThreadAttribute@footnote{https://msdn.microsoft.com/en-us/library/windows/desktop/ms686880(v=vs.85).aspx}.

Supported attributes:


@table @asis

@item `handle_list'

Sequence of handles that will be inherited. `close_fds' must be true if
non-empty.

The handles must be temporarily made inheritable by
@ref{12ae,,os.set_handle_inheritable()} when passed to the @ref{6bf,,Popen}
constructor, else @ref{53c,,OSError} will be raised with Windows error
@code{ERROR_INVALID_PARAMETER} (87).

@cartouche
@quotation Προειδοποίηση 
In a multithreaded process, use caution to avoid leaking handles
that are marked inheritable when combining this feature with
concurrent calls to other process creation functions that inherit
all handles such as @ref{17ff,,os.system()}.  This also applies to
standard handle redirection, which temporarily creates inheritable
handles.
@end quotation
@end cartouche
@end table


Added in version 3.7.

@end deffn
@end deffn

@menu
* Windows Constants:: 

@end menu

@node Windows Constants,,,Windows Popen Helpers
@anchor{library/subprocess windows-constants}@anchor{39ab}
@subsubsection Windows Constants


The @code{subprocess} module exposes the following constants.

@geindex STD_INPUT_HANDLE (στη μονάδα subprocess)
@anchor{library/subprocess subprocess STD_INPUT_HANDLE}@anchor{39ac}
@deffn {Δεδομένα} subprocess.STD_INPUT_HANDLE

The standard input device. Initially, this is the console input buffer,
@code{CONIN$}.
@end deffn

@geindex STD_OUTPUT_HANDLE (στη μονάδα subprocess)
@anchor{library/subprocess subprocess STD_OUTPUT_HANDLE}@anchor{39ad}
@deffn {Δεδομένα} subprocess.STD_OUTPUT_HANDLE

The standard output device. Initially, this is the active console screen
buffer, @code{CONOUT$}.
@end deffn

@geindex STD_ERROR_HANDLE (στη μονάδα subprocess)
@anchor{library/subprocess subprocess STD_ERROR_HANDLE}@anchor{39ae}
@deffn {Δεδομένα} subprocess.STD_ERROR_HANDLE

The standard error device. Initially, this is the active console screen
buffer, @code{CONOUT$}.
@end deffn

@geindex SW_HIDE (στη μονάδα subprocess)
@anchor{library/subprocess subprocess SW_HIDE}@anchor{39aa}
@deffn {Δεδομένα} subprocess.SW_HIDE

Hides the window. Another window will be activated.
@end deffn

@geindex STARTF_USESTDHANDLES (στη μονάδα subprocess)
@anchor{library/subprocess subprocess STARTF_USESTDHANDLES}@anchor{39a5}
@deffn {Δεδομένα} subprocess.STARTF_USESTDHANDLES

Specifies that the @ref{39a4,,STARTUPINFO.hStdInput},
@ref{39a6,,STARTUPINFO.hStdOutput}, and @ref{39a7,,STARTUPINFO.hStdError} attributes
contain additional information.
@end deffn

@geindex STARTF_USESHOWWINDOW (στη μονάδα subprocess)
@anchor{library/subprocess subprocess STARTF_USESHOWWINDOW}@anchor{39a9}
@deffn {Δεδομένα} subprocess.STARTF_USESHOWWINDOW

Specifies that the @ref{39a8,,STARTUPINFO.wShowWindow} attribute contains
additional information.
@end deffn

@geindex STARTF_FORCEONFEEDBACK (στη μονάδα subprocess)
@anchor{library/subprocess subprocess STARTF_FORCEONFEEDBACK}@anchor{39af}
@deffn {Δεδομένα} subprocess.STARTF_FORCEONFEEDBACK

A @ref{39a3,,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.


Added in version 3.13.

@end deffn

@geindex STARTF_FORCEOFFFEEDBACK (στη μονάδα subprocess)
@anchor{library/subprocess subprocess STARTF_FORCEOFFFEEDBACK}@anchor{39b0}
@deffn {Δεδομένα} subprocess.STARTF_FORCEOFFFEEDBACK

A @ref{39a3,,STARTUPINFO.dwFlags} parameter to specify that the mouse
cursor will not be changed when launching a process.


Added in version 3.13.

@end deffn

@geindex CREATE_NEW_CONSOLE (στη μονάδα subprocess)
@anchor{library/subprocess subprocess CREATE_NEW_CONSOLE}@anchor{398f}
@deffn {Δεδομένα} subprocess.CREATE_NEW_CONSOLE

The new process has a new console, instead of inheriting its parent’s
console (the default).
@end deffn

@geindex CREATE_NEW_PROCESS_GROUP (στη μονάδα subprocess)
@anchor{library/subprocess subprocess CREATE_NEW_PROCESS_GROUP}@anchor{3990}
@deffn {Δεδομένα} subprocess.CREATE_NEW_PROCESS_GROUP

A @ref{6bf,,Popen} @code{creationflags} parameter to specify that a new process
group will be created. This flag is necessary for using @ref{170c,,os.kill()}
on the subprocess.

This flag is ignored if @ref{398f,,CREATE_NEW_CONSOLE} is specified.
@end deffn

@geindex ABOVE_NORMAL_PRIORITY_CLASS (στη μονάδα subprocess)
@anchor{library/subprocess subprocess ABOVE_NORMAL_PRIORITY_CLASS}@anchor{3991}
@deffn {Δεδομένα} subprocess.ABOVE_NORMAL_PRIORITY_CLASS

A @ref{6bf,,Popen} @code{creationflags} parameter to specify that a new process
will have an above average priority.


Added in version 3.7.

@end deffn

@geindex BELOW_NORMAL_PRIORITY_CLASS (στη μονάδα subprocess)
@anchor{library/subprocess subprocess BELOW_NORMAL_PRIORITY_CLASS}@anchor{3992}
@deffn {Δεδομένα} subprocess.BELOW_NORMAL_PRIORITY_CLASS

A @ref{6bf,,Popen} @code{creationflags} parameter to specify that a new process
will have a below average priority.


Added in version 3.7.

@end deffn

@geindex HIGH_PRIORITY_CLASS (στη μονάδα subprocess)
@anchor{library/subprocess subprocess HIGH_PRIORITY_CLASS}@anchor{3993}
@deffn {Δεδομένα} subprocess.HIGH_PRIORITY_CLASS

A @ref{6bf,,Popen} @code{creationflags} parameter to specify that a new process
will have a high priority.


Added in version 3.7.

@end deffn

@geindex IDLE_PRIORITY_CLASS (στη μονάδα subprocess)
@anchor{library/subprocess subprocess IDLE_PRIORITY_CLASS}@anchor{3994}
@deffn {Δεδομένα} subprocess.IDLE_PRIORITY_CLASS

A @ref{6bf,,Popen} @code{creationflags} parameter to specify that a new process
will have an idle (lowest) priority.


Added in version 3.7.

@end deffn

@geindex NORMAL_PRIORITY_CLASS (στη μονάδα subprocess)
@anchor{library/subprocess subprocess NORMAL_PRIORITY_CLASS}@anchor{3995}
@deffn {Δεδομένα} subprocess.NORMAL_PRIORITY_CLASS

A @ref{6bf,,Popen} @code{creationflags} parameter to specify that a new process
will have a normal priority. (default)


Added in version 3.7.

@end deffn

@geindex REALTIME_PRIORITY_CLASS (στη μονάδα subprocess)
@anchor{library/subprocess subprocess REALTIME_PRIORITY_CLASS}@anchor{3996}
@deffn {Δεδομένα} subprocess.REALTIME_PRIORITY_CLASS

A @ref{6bf,,Popen} @code{creationflags} parameter to specify that a new process
will have realtime priority.
You should almost never use REALTIME_PRIORITY_CLASS, because this interrupts
system threads that manage mouse input, keyboard input, and background disk
flushing. This class can be appropriate for applications that «talk» directly
to hardware or that perform brief tasks that should have limited interruptions.


Added in version 3.7.

@end deffn

@geindex CREATE_NO_WINDOW (στη μονάδα subprocess)
@anchor{library/subprocess subprocess CREATE_NO_WINDOW}@anchor{3997}
@deffn {Δεδομένα} subprocess.CREATE_NO_WINDOW

A @ref{6bf,,Popen} @code{creationflags} parameter to specify that a new process
will not create a window.


Added in version 3.7.

@end deffn

@geindex DETACHED_PROCESS (στη μονάδα subprocess)
@anchor{library/subprocess subprocess DETACHED_PROCESS}@anchor{3998}
@deffn {Δεδομένα} subprocess.DETACHED_PROCESS

A @ref{6bf,,Popen} @code{creationflags} parameter to specify that a new process
will not inherit its parent’s console.
This value cannot be used with CREATE_NEW_CONSOLE.


Added in version 3.7.

@end deffn

@geindex CREATE_DEFAULT_ERROR_MODE (στη μονάδα subprocess)
@anchor{library/subprocess subprocess CREATE_DEFAULT_ERROR_MODE}@anchor{3999}
@deffn {Δεδομένα} subprocess.CREATE_DEFAULT_ERROR_MODE

A @ref{6bf,,Popen} @code{creationflags} parameter to specify that a new process
does not inherit the error mode of the calling process. Instead, the new
process gets the default error mode.
This feature is particularly useful for multithreaded shell applications
that run with hard errors disabled.


Added in version 3.7.

@end deffn

@geindex CREATE_BREAKAWAY_FROM_JOB (στη μονάδα subprocess)
@anchor{library/subprocess subprocess CREATE_BREAKAWAY_FROM_JOB}@anchor{399a}
@deffn {Δεδομένα} subprocess.CREATE_BREAKAWAY_FROM_JOB

A @ref{6bf,,Popen} @code{creationflags} parameter to specify that a new process
is not associated with the job.


Added in version 3.7.

@end deffn

@node Older high-level API,Replacing Older Functions with the subprocess Module,Windows Popen Helpers,subprocess — Subprocess management
@anchor{library/subprocess call-function-trio}@anchor{39b1}@anchor{library/subprocess older-high-level-api}@anchor{39b2}
@subsubsection Older high-level API


Prior to Python 3.5, these three functions comprised the high level API to
subprocess. You can now use @ref{f45,,run()} in many cases, but lots of existing code
calls these functions.

@geindex call() (στη μονάδα subprocess)
@anchor{library/subprocess subprocess call}@anchor{f47}
@deffn {Συνάρτηση} subprocess.call (args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)

Run the command described by `args'.  Wait for command to complete, then
return the @ref{e52,,returncode} attribute.

Code needing to capture stdout or stderr should use @ref{f45,,run()} instead:

@example
run(...).returncode
@end example

To suppress stdout or stderr, supply a value of @ref{14f9,,DEVNULL}.

The arguments shown above are merely some common ones.
The full function signature is the
same as that of the @ref{6bf,,Popen} constructor - this function passes all
supplied arguments other than `timeout' directly through to that interface.

@cartouche
@quotation Σημείωση 
Do not use @code{stdout=PIPE} or @code{stderr=PIPE} with this
function.  The child process will block if it generates enough
output to a pipe to fill up the OS pipe buffer as the pipes are
not being read from.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: `timeout' was added.



Άλλαξε στην έκδοση 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() (στη μονάδα subprocess)
@anchor{library/subprocess subprocess check_call}@anchor{397f}
@deffn {Συνάρτηση} 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{16c9,,CalledProcessError}. The
@code{CalledProcessError} object will have the return code in the
@ref{3980,,returncode} attribute.
If @code{check_call()} was unable to start the process it will propagate the exception
that was raised.

Code needing to capture stdout or stderr should use @ref{f45,,run()} instead:

@example
run(..., check=True)
@end example

To suppress stdout or stderr, supply a value of @ref{14f9,,DEVNULL}.

The arguments shown above are merely some common ones.
The full function signature is the
same as that of the @ref{6bf,,Popen} constructor - this function passes all
supplied arguments other than `timeout' directly through to that interface.

@cartouche
@quotation Σημείωση 
Do not use @code{stdout=PIPE} or @code{stderr=PIPE} with this
function.  The child process will block if it generates enough
output to a pipe to fill up the OS pipe buffer as the pipes are
not being read from.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: `timeout' was added.



Άλλαξε στην έκδοση 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() (στη μονάδα subprocess)
@anchor{library/subprocess subprocess check_output}@anchor{136b}
@deffn {Συνάρτηση} 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)

Run command with arguments and return its output.

If the return code was non-zero it raises a @ref{16c9,,CalledProcessError}. The
@code{CalledProcessError} object will have the return code in the
@ref{3980,,returncode} attribute and any output in the
@ref{3982,,output} attribute.

This is equivalent to:

@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{f45,,run()} -
most arguments are passed directly through to that interface.
One API deviation from @code{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.

By default, this function will return the data as encoded bytes. The actual
encoding of the output data may depend on the command being invoked, so the
decoding to text will often need to be handled at the application level.

This behaviour may be overridden by setting `text', `encoding', `errors',
or `universal_newlines' to @code{True} as described in
@ref{3972,,Frequently Used Arguments} and @ref{f45,,run()}.

To also capture standard error in the result, use
@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


Added in version 3.1.



Άλλαξε στην έκδοση 3.3: `timeout' was added.



Άλλαξε στην έκδοση 3.4: Support for the `input' keyword argument was added.



Άλλαξε στην έκδοση 3.6: `encoding' and `errors' were added.  See @ref{f45,,run()} for details.



Added in version 3.7: `text' was added as a more readable alias for `universal_newlines'.



Άλλαξε στην έκδοση 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 Replacing Older Functions with the subprocess Module,Legacy Shell Invocation Functions,Older high-level API,subprocess — Subprocess management
@anchor{library/subprocess replacing-older-functions-with-the-subprocess-module}@anchor{39b3}@anchor{library/subprocess subprocess-replacements}@anchor{1531}
@subsubsection Replacing Older Functions with the @code{subprocess} Module


In this section, «a becomes b» means that b can be used as a replacement for a.

@cartouche
@quotation Σημείωση 
All «a» functions in this section fail (more or less) silently if the
executed program cannot be found; the «b» replacements raise @ref{53c,,OSError}
instead.

In addition, the replacements using @ref{136b,,check_output()} will fail with a
@ref{16c9,,CalledProcessError} if the requested operation produces a non-zero
return code. The output is still available as the
@ref{3982,,output} attribute of the raised exception.
@end quotation
@end cartouche

In the following examples, we assume that the relevant functions have already
been imported from the @code{subprocess} module.

@menu
* Replacing /bin/sh shell command substitution:: 
* Replacing shell pipeline:: 
* Replacing os.system(): Replacing os system. 
* Replacing the os.spawn family: Replacing the os spawn family. 
* Replacing os.popen(): Replacing os popen. 

@end menu

@node Replacing /bin/sh shell command substitution,Replacing shell pipeline,,Replacing Older Functions with the subprocess Module
@anchor{library/subprocess replacing-bin-sh-shell-command-substitution}@anchor{39b4}
@subsubsection Replacing @code{/bin/sh} shell command substitution


@example
output=$(mycmd myarg)
@end example

becomes:

@example
output = check_output(["mycmd", "myarg"])
@end example

@node Replacing shell pipeline,Replacing os system,Replacing /bin/sh shell command substitution,Replacing Older Functions with the subprocess Module
@anchor{library/subprocess replacing-shell-pipeline}@anchor{39b5}
@subsubsection Replacing shell pipeline


@example
output=$(dmesg | grep hda)
@end example

becomes:

@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

The @code{p1.stdout.close()} call after starting the p2 is important in order for
p1 to receive a SIGPIPE if p2 exits before p1.

Alternatively, for trusted input, the shell’s own pipeline support may still
be used directly:

@example
output=$(dmesg | grep hda)
@end example

becomes:

@example
output = check_output("dmesg | grep hda", shell=True)
@end example

@node Replacing os system,Replacing the os spawn family,Replacing shell pipeline,Replacing Older Functions with the subprocess Module
@anchor{library/subprocess replacing-os-system}@anchor{39b6}
@subsubsection Replacing @code{os.system()}


@example
sts = os.system("mycmd" + " myarg")
# becomes
retcode = call("mycmd" + " myarg", shell=True)
@end example

Notes:


@itemize *

@item 
Calling the program through the shell is usually not required.

@item 
The @ref{f47,,call()} return value is encoded differently to that of
@ref{17ff,,os.system()}.

@item 
The @ref{17ff,,os.system()} function ignores SIGINT and SIGQUIT signals while
the command is running, but the caller must do this separately when
using the @code{subprocess} module.
@end itemize

A more realistic example would look like this:

@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 Replacing the os spawn family,Replacing os popen,Replacing os system,Replacing Older Functions with the subprocess Module
@anchor{library/subprocess replacing-the-os-spawn-family}@anchor{39b7}
@subsubsection Replacing the @code{os.spawn} family


P_NOWAIT example:

@example
pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid
@end example

P_WAIT example:

@example
retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])
@end example

Vector example:

@example
os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])
@end example

Environment example:

@example
os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
==>
Popen(["/bin/mycmd", "myarg"], env=@{"PATH": "/usr/bin"@})
@end example

@node Replacing os popen,,Replacing the os spawn family,Replacing Older Functions with the subprocess Module
@anchor{library/subprocess replacing-os-popen}@anchor{39b8}
@subsubsection Replacing @code{os.popen()}


Return code handling translates as follows:

@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 Legacy Shell Invocation Functions,Notes<2>,Replacing Older Functions with the subprocess Module,subprocess — Subprocess management
@anchor{library/subprocess legacy-shell-invocation-functions}@anchor{39b9}
@subsubsection Legacy Shell Invocation Functions


This module also provides the following legacy functions from the 2.x
@code{commands} module. These operations implicitly invoke the system shell and
none of the guarantees described above regarding security and exception
handling consistency are valid for these functions.

@geindex getstatusoutput() (στη μονάδα subprocess)
@anchor{library/subprocess subprocess getstatusoutput}@anchor{136d}
@deffn {Συνάρτηση} subprocess.getstatusoutput (cmd, *, encoding=None, errors=None)

Return @code{(exitcode, output)} of executing `cmd' in a shell.

Execute the string `cmd' in a shell with @ref{136b,,check_output()} and
return a 2-tuple @code{(exitcode, output)}.
`encoding' and `errors' are used to decode output;
see the notes on @ref{3972,,Frequently Used Arguments} for more details.

A trailing newline is stripped from the output.
The exit code for the command can be interpreted as the return code
of subprocess.  Example:

@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{232d,,Διαθεσιμότητα}: Unix, Windows.


Άλλαξε στην έκδοση 3.3.4: Windows support was added.

The function now returns (exitcode, output) instead of (status, output)
as it did in Python 3.3.3 and earlier.  exitcode has the same value as
@ref{e52,,returncode}.



Άλλαξε στην έκδοση 3.11: Added the `encoding' and `errors' parameters.

@end deffn

@geindex getoutput() (στη μονάδα subprocess)
@anchor{library/subprocess subprocess getoutput}@anchor{136c}
@deffn {Συνάρτηση} subprocess.getoutput (cmd, *, encoding=None, errors=None)

Return output (stdout and stderr) of executing `cmd' in a shell.

Like @ref{136d,,getstatusoutput()}, except the exit code is ignored and the return
value is a string containing the command’s output.  Example:

@example
>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'
@end example

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.


Άλλαξε στην έκδοση 3.3.4: Windows support added



Άλλαξε στην έκδοση 3.11: Added the `encoding' and `errors' parameters.

@end deffn

@node Notes<2>,,Legacy Shell Invocation Functions,subprocess — Subprocess management
@anchor{library/subprocess notes}@anchor{39ba}
@subsubsection Notes


@menu
* Timeout Behavior:: 
* Converting an argument sequence to a string on Windows:: 
* Disable use of posix_spawn(): Disable use of posix_spawn. 

@end menu

@node Timeout Behavior,Converting an argument sequence to a string on Windows,,Notes<2>
@anchor{library/subprocess subprocess-timeout-behavior}@anchor{39bb}@anchor{library/subprocess timeout-behavior}@anchor{39bc}
@subsubsection Timeout Behavior


When using the @code{timeout} parameter in functions like @ref{f45,,run()},
@ref{266,,Popen.wait()}, or @ref{19aa,,Popen.communicate()},
users should be aware of the following behaviors:


@enumerate 

@item 
`Process Creation Delay': The initial process creation itself cannot be interrupted
on many platform APIs. This means that even when specifying a timeout, you are not
guaranteed to see a timeout exception until at least after however long process
creation takes.

@item 
`Extremely Small Timeout Values': Setting very small timeout values (such as a few
milliseconds) may result in almost immediate @ref{19ab,,TimeoutExpired} exceptions because
process creation and system scheduling inherently require time.
@end enumerate

@node Converting an argument sequence to a string on Windows,Disable use of posix_spawn,Timeout Behavior,Notes<2>
@anchor{library/subprocess converting-an-argument-sequence-to-a-string-on-windows}@anchor{39bd}@anchor{library/subprocess converting-argument-sequence}@anchor{398b}
@subsubsection Converting an argument sequence to a string on Windows


On Windows, an `args' sequence is converted to a string that can be parsed
using the following rules (which correspond to the rules used by the MS C
runtime):


@enumerate 

@item 
Arguments are delimited by white space, which is either a
space or a tab.

@item 
A string surrounded by double quotation marks is
interpreted as a single argument, regardless of white space
contained within.  A quoted string can be embedded in an
argument.

@item 
A double quotation mark preceded by a backslash is
interpreted as a literal double quotation mark.

@item 
Backslashes are interpreted literally, unless they
immediately precede a double quotation mark.

@item 
If backslashes immediately precede a double quotation mark,
every pair of backslashes is interpreted as a literal
backslash.  If the number of backslashes is odd, the last
backslash escapes the next double quotation mark as
described in rule 3.
@end enumerate


@subsubheading Δείτε επίσης



@table @asis

@item @ref{cc,,shlex}

Module which provides function to parse and escape command lines.
@end table


@node Disable use of posix_spawn,,Converting an argument sequence to a string on Windows,Notes<2>
@anchor{library/subprocess disable-posix-spawn}@anchor{39be}@anchor{library/subprocess disable-use-of-posix-spawn}@anchor{39bf}
@subsubsection Disable use of @code{posix_spawn()}


On Linux, @code{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.

@example
subprocess._USE_POSIX_SPAWN = False  # See CPython issue gh-NNNNNN.
@end example

It is safe to set this to false on any Python version. It will have no
effect on older or newer versions where unsupported. Do not assume the attribute
is available to read. Despite the name, a true value does not indicate 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.


Added in version 3.8: @code{_USE_POSIX_SPAWN}


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node sched — Event scheduler,queue — A synchronized queue class,subprocess — Subprocess management,Concurrent Execution
@anchor{library/sched doc}@anchor{39c0}@anchor{library/sched module-sched}@anchor{c7}@anchor{library/sched sched-event-scheduler}@anchor{39c1}@anchor{library/sched translation-repo}@anchor{39c2}
@subsection @code{sched} — Event scheduler


@geindex module; sched

`Source code:' Lib/sched.py@footnote{https://github.com/python/cpython/tree/main/Lib/sched.py}

@geindex event scheduling


__________________________________________________________________


The @code{sched} module defines a class which implements a general purpose event
scheduler:

@geindex scheduler (κλάση σε sched)
@anchor{library/sched sched scheduler}@anchor{14d3}
@deffn {Κλάση} sched.scheduler (timefunc=time.monotonic, delayfunc=time.sleep)

The @code{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.


Άλλαξε στην έκδοση 3.3: `timefunc' and `delayfunc' parameters are optional.



Άλλαξε στην έκδοση 3.3: @code{scheduler} class can be safely used in multi-threaded
environments.

@end deffn

Example:

@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{39c3}@anchor{library/sched scheduler-objects}@anchor{39c4}
@subsubsection Scheduler Objects


@ref{14d3,,scheduler} instances have the following methods and attributes:

@geindex enterabs() (μέθοδος της sched.scheduler)
@anchor{library/sched sched scheduler enterabs}@anchor{14d5}
@deffn {Μέθοδος} 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{1ef0,,cancel()}).


Άλλαξε στην έκδοση 3.3: `argument' parameter is optional.



Άλλαξε στην έκδοση 3.3: `kwargs' parameter was added.

@end deffn

@geindex enter() (μέθοδος της sched.scheduler)
@anchor{library/sched sched scheduler enter}@anchor{14d4}
@deffn {Μέθοδος} 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{14d5,,enterabs()}.


Άλλαξε στην έκδοση 3.3: `argument' parameter is optional.



Άλλαξε στην έκδοση 3.3: `kwargs' parameter was added.

@end deffn

@geindex cancel() (μέθοδος της sched.scheduler)
@anchor{library/sched sched scheduler cancel}@anchor{1ef0}
@deffn {Μέθοδος} 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{277,,ValueError}.
@end deffn

@geindex empty() (μέθοδος της sched.scheduler)
@anchor{library/sched sched scheduler empty}@anchor{39c5}
@deffn {Μέθοδος} scheduler.empty ()

Return @code{True} if the event queue is empty.
@end deffn

@geindex run() (μέθοδος της sched.scheduler)
@anchor{library/sched sched scheduler run}@anchor{14d2}
@deffn {Μέθοδος} 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 @code{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.


Άλλαξε στην έκδοση 3.3: `blocking' parameter was added.

@end deffn

@geindex queue (ιδιότητα της sched.scheduler)
@anchor{library/sched sched scheduler queue}@anchor{39c6}
@deffn {Ιδιότητα} 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{a3d,,named tuple} with the
following fields:  time, priority, action, argument, kwargs.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node queue — A synchronized queue class,contextvars — Context Variables,sched — Event scheduler,Concurrent Execution
@anchor{library/queue doc}@anchor{39c7}@anchor{library/queue module-queue}@anchor{be}@anchor{library/queue queue-a-synchronized-queue-class}@anchor{39c8}@anchor{library/queue translation-repo}@anchor{39c9}
@subsection @code{queue} — A synchronized queue class


@geindex module; queue

`Source code:' Lib/queue.py@footnote{https://github.com/python/cpython/tree/main/Lib/queue.py}


__________________________________________________________________


The @code{queue} module implements multi-producer, multi-consumer queues.
It is especially useful in threaded programming when information must be
exchanged safely between multiple threads.  The @ref{1738,,Queue} class in this
module implements all the required locking semantics.

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{6c,,heapq} module) and the
lowest valued entry is retrieved first.

Internally, those three types of queues use locks to temporarily block
competing threads; however, they are not designed to handle reentrancy
within a thread.

In addition, the module implements a «simple»
@abbr{FIFO} queue type, @ref{f27,,SimpleQueue}, whose
specific implementation provides additional guarantees
in exchange for the smaller functionality.

The @code{queue} module defines the following classes and exceptions:

@geindex Queue (κλάση σε queue)
@anchor{library/queue queue Queue}@anchor{1738}
@deffn {Κλάση} queue.Queue (maxsize=0)

Constructor for a @abbr{FIFO} queue.  `maxsize' is
an integer that sets the upperbound
limit on the number of items that can be placed in the queue.  Insertion will
block once this size has been reached, until queue items are consumed.  If
`maxsize' is less than or equal to zero, the queue size is infinite.
@end deffn

@geindex LifoQueue (κλάση σε queue)
@anchor{library/queue queue LifoQueue}@anchor{28b2}
@deffn {Κλάση} queue.LifoQueue (maxsize=0)

Constructor for a @abbr{LIFO} queue.  `maxsize' is
an integer that sets the upperbound
limit on the number of items that can be placed in the queue.  Insertion will
block once this size has been reached, until queue items are consumed.  If
`maxsize' is less than or equal to zero, the queue size is infinite.
@end deffn

@geindex PriorityQueue (κλάση σε queue)
@anchor{library/queue queue PriorityQueue}@anchor{28b3}
@deffn {Κλάση} queue.PriorityQueue (maxsize=0)

Constructor for a priority queue.  `maxsize' is an integer that sets the upperbound
limit on the number of items that can be placed in the queue.  Insertion will
block once this size has been reached, until queue items are consumed.  If
`maxsize' is less than or equal to zero, the queue size is infinite.

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)}.

If the `data' elements are not comparable, the data can be wrapped in a class
that ignores the data item and only compares the priority number:

@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 (κλάση σε queue)
@anchor{library/queue queue SimpleQueue}@anchor{f27}
@deffn {Κλάση} queue.SimpleQueue

Constructor for an unbounded @abbr{FIFO} queue.
Simple queues lack advanced functionality such as task tracking.


Added in version 3.7.

@end deffn

@geindex Empty
@anchor{library/queue queue Empty}@anchor{38b6}
@deffn {Εξαίρεση} queue.Empty

Exception raised when non-blocking @ref{341d,,get()} (or
@ref{39ca,,get_nowait()}) is called
on a @ref{1738,,Queue} object which is empty.
@end deffn

@geindex Full
@anchor{library/queue queue Full}@anchor{38b7}
@deffn {Εξαίρεση} queue.Full

Exception raised when non-blocking @ref{39cb,,put()} (or
@ref{341c,,put_nowait()}) is called
on a @ref{1738,,Queue} object which is full.
@end deffn

@geindex ShutDown
@anchor{library/queue queue ShutDown}@anchor{746}
@deffn {Εξαίρεση} queue.ShutDown

Exception raised when @ref{39cb,,put()} or @ref{341d,,get()} is called on
a @ref{1738,,Queue} object which has been shut down.


Added in version 3.13.

@end deffn

@menu
* Queue Objects:: 
* SimpleQueue Objects:: 

@end menu

@node Queue Objects,SimpleQueue Objects,,queue — A synchronized queue class
@anchor{library/queue queue-objects}@anchor{39cc}@anchor{library/queue queueobjects}@anchor{39cd}
@subsubsection Queue Objects


Queue objects (@ref{1738,,Queue}, @ref{28b2,,LifoQueue}, or @ref{28b3,,PriorityQueue})
provide the public methods described below.

@geindex qsize() (μέθοδος της queue.Queue)
@anchor{library/queue queue Queue qsize}@anchor{39ce}
@deffn {Μέθοδος} Queue.qsize ()

Return the approximate size of the queue.  Note, qsize() > 0 doesn’t
guarantee that a subsequent get() will not block, nor will qsize() < maxsize
guarantee that put() will not block.
@end deffn

@geindex empty() (μέθοδος της queue.Queue)
@anchor{library/queue queue Queue empty}@anchor{39cf}
@deffn {Μέθοδος} Queue.empty ()

Return @code{True} if the queue is empty, @code{False} otherwise.  If empty()
returns @code{True} it doesn’t guarantee that a subsequent call to put()
will not block.  Similarly, if empty() returns @code{False} it doesn’t
guarantee that a subsequent call to get() will not block.
@end deffn

@geindex full() (μέθοδος της queue.Queue)
@anchor{library/queue queue Queue full}@anchor{39d0}
@deffn {Μέθοδος} Queue.full ()

Return @code{True} if the queue is full, @code{False} otherwise.  If full()
returns @code{True} it doesn’t guarantee that a subsequent call to get()
will not block.  Similarly, if full() returns @code{False} it doesn’t
guarantee that a subsequent call to put() will not block.
@end deffn

@geindex put() (μέθοδος της queue.Queue)
@anchor{library/queue queue Queue put}@anchor{39cb}
@deffn {Μέθοδος} 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{38b7,,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 @code{Full} exception (`timeout' is
ignored in that case).

Raises @ref{746,,ShutDown} if the queue has been shut down.
@end deffn

@geindex put_nowait() (μέθοδος της queue.Queue)
@anchor{library/queue queue Queue put_nowait}@anchor{341c}
@deffn {Μέθοδος} Queue.put_nowait (item)

Equivalent to @code{put(item, block=False)}.
@end deffn

@geindex get() (μέθοδος της queue.Queue)
@anchor{library/queue queue Queue get}@anchor{341d}
@deffn {Μέθοδος} Queue.get (block=True, timeout=None)

Remove and return an item from the queue.  If optional args `block' is true and
`timeout' is @code{None} (the default), block if necessary until an item is available.
If `timeout' is a positive number, it blocks at most `timeout' seconds and
raises the @ref{38b6,,Empty} exception if no item was available within that time.
Otherwise (`block' is false), return an item if one is immediately available,
else raise the @code{Empty} exception (`timeout' is ignored in that case).

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{d96,,KeyboardInterrupt}.

Raises @ref{746,,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() (μέθοδος της queue.Queue)
@anchor{library/queue queue Queue get_nowait}@anchor{39ca}
@deffn {Μέθοδος} Queue.get_nowait ()

Equivalent to @code{get(False)}.
@end deffn

Two methods are offered to support tracking whether enqueued tasks have been
fully processed by daemon consumer threads.

@geindex task_done() (μέθοδος της queue.Queue)
@anchor{library/queue queue Queue task_done}@anchor{38b2}
@deffn {Μέθοδος} Queue.task_done ()

Indicate that a formerly enqueued task is complete.  Used by queue consumer
threads.  For each @ref{341d,,get()} used to fetch a task, a subsequent call to
@code{task_done()} tells the queue that the processing on the task is complete.

If a @ref{38b3,,join()} is currently blocking, it will resume when all items have been
processed (meaning that a @code{task_done()} call was received for every item
that had been @ref{39cb,,put()} into the queue).

Raises a @ref{277,,ValueError} if called more times than there were items placed in
the queue.
@end deffn

@geindex join() (μέθοδος της queue.Queue)
@anchor{library/queue queue Queue join}@anchor{38b3}
@deffn {Μέθοδος} Queue.join ()

Blocks until all items in the queue have been gotten and processed.

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{38b2,,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, @code{join()} unblocks.
@end deffn

@menu
* Waiting for task completion:: 
* Terminating queues:: 

@end menu

@node Waiting for task completion,Terminating queues,,Queue Objects
@anchor{library/queue waiting-for-task-completion}@anchor{39d1}
@subsubsection Waiting for task completion


Example of how to wait for enqueued tasks to be completed:

@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

@node Terminating queues,,Waiting for task completion,Queue Objects
@anchor{library/queue terminating-queues}@anchor{39d2}
@subsubsection Terminating queues


When no longer needed, @ref{1738,,Queue} objects can be wound down
until empty or terminated immediately with a hard shutdown.

@geindex shutdown() (μέθοδος της queue.Queue)
@anchor{library/queue queue Queue shutdown}@anchor{745}
@deffn {Μέθοδος} Queue.shutdown (immediate=False)

Put a @ref{1738,,Queue} instance into a shutdown mode.

The queue can no longer grow.
Future calls to @ref{39cb,,put()} raise @ref{746,,ShutDown}.
Currently blocked callers of @code{put()} will be unblocked
and will raise @code{ShutDown} in the formerly blocked thread.

If `immediate' is false (the default), the queue can be wound
down normally with @ref{341d,,get()} calls to extract tasks
that have already been loaded.

And if @ref{38b2,,task_done()} is called for each remaining task, a
pending @ref{38b3,,join()} will be unblocked normally.

Once the queue is empty, future calls to @ref{341d,,get()} will
raise @ref{746,,ShutDown}.

If `immediate' is true, the queue is terminated immediately.
The queue is drained to be completely empty and the count
of unfinished tasks is reduced by the number of tasks drained.
If unfinished tasks is zero, callers of @ref{38b3,,join()}
are unblocked.  Also, blocked callers of @ref{341d,,get()}
are unblocked and will raise @ref{746,,ShutDown} because the
queue is empty.

Use caution when using @ref{38b3,,join()} with `immediate' set
to true. This unblocks the join even when no work has been done
on the tasks, violating the usual invariant for joining a queue.


Added in version 3.13.

@end deffn

@node SimpleQueue Objects,,Queue Objects,queue — A synchronized queue class
@anchor{library/queue simplequeue-objects}@anchor{39d3}
@subsubsection SimpleQueue Objects


@ref{f27,,SimpleQueue} objects provide the public methods described below.

@geindex qsize() (μέθοδος της queue.SimpleQueue)
@anchor{library/queue queue SimpleQueue qsize}@anchor{39d4}
@deffn {Μέθοδος} SimpleQueue.qsize ()

Return the approximate size of the queue.  Note, qsize() > 0 doesn’t
guarantee that a subsequent get() will not block.
@end deffn

@geindex empty() (μέθοδος της queue.SimpleQueue)
@anchor{library/queue queue SimpleQueue empty}@anchor{39d5}
@deffn {Μέθοδος} 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() (μέθοδος της queue.SimpleQueue)
@anchor{library/queue queue SimpleQueue put}@anchor{39d6}
@deffn {Μέθοδος} SimpleQueue.put (item, block=True, timeout=None)

Put `item' into the queue.  The method never blocks and always succeeds
(except for potential low-level errors such as failure to allocate memory).
The optional args `block' and `timeout' are ignored and only provided
for compatibility with @ref{39cb,,Queue.put()}.

`Λεπτομέρεια υλοποίησης 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{11d,,weakref} callbacks.
@end deffn

@geindex put_nowait() (μέθοδος της queue.SimpleQueue)
@anchor{library/queue queue SimpleQueue put_nowait}@anchor{39d7}
@deffn {Μέθοδος} SimpleQueue.put_nowait (item)

Equivalent to @code{put(item, block=False)}, provided for compatibility with
@ref{341c,,Queue.put_nowait()}.
@end deffn

@geindex get() (μέθοδος της queue.SimpleQueue)
@anchor{library/queue queue SimpleQueue get}@anchor{39d8}
@deffn {Μέθοδος} SimpleQueue.get (block=True, timeout=None)

Remove and return an item from the queue.  If optional args `block' is true and
`timeout' is @code{None} (the default), block if necessary until an item is available.
If `timeout' is a positive number, it blocks at most `timeout' seconds and
raises the @ref{38b6,,Empty} exception if no item was available within that time.
Otherwise (`block' is false), return an item if one is immediately available,
else raise the @code{Empty} exception (`timeout' is ignored in that case).
@end deffn

@geindex get_nowait() (μέθοδος της queue.SimpleQueue)
@anchor{library/queue queue SimpleQueue get_nowait}@anchor{39d9}
@deffn {Μέθοδος} SimpleQueue.get_nowait ()

Equivalent to @code{get(False)}.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Class @ref{1d85,,multiprocessing.Queue}

A queue class for use in a multi-processing (rather than multi-threading)
context.
@end table

@ref{9d6,,collections.deque} is an alternative implementation of unbounded
queues with fast atomic @ref{2b8f,,append()} and
@ref{2b95,,popleft()} operations that do not require locking
and also support indexing.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node contextvars — Context Variables,_thread — Low-level threading API,queue — A synchronized queue class,Concurrent Execution
@anchor{library/contextvars doc}@anchor{39da}@anchor{library/contextvars contextvars-context-variables}@anchor{39db}@anchor{library/contextvars module-contextvars}@anchor{28}@anchor{library/contextvars translation-repo}@anchor{39dc}
@subsection @code{contextvars} — Context Variables


@geindex module; contextvars


__________________________________________________________________


This module provides APIs to manage, store, and access context-local
state.  The @ref{1a9d,,ContextVar} class is used to declare
and work with `Context Variables'.  The @ref{3868,,copy_context()}
function and the @ref{421,,Context} class should be used to
manage the current context in asynchronous frameworks.

Context managers that have state should use Context Variables
instead of @ref{1a87,,threading.local()} to prevent their state from
bleeding to other code unexpectedly, when used in concurrent code.

See also 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/} for additional details.


Added in version 3.7.


@menu
* Context Variables:: 
* Manual Context Management:: 
* asyncio support:: 

@end menu

@node Context Variables,Manual Context Management,,contextvars — Context Variables
@anchor{library/contextvars context-variables}@anchor{39dd}
@subsubsection Context Variables


@geindex ContextVar (κλάση σε contextvars)
@anchor{library/contextvars contextvars ContextVar}@anchor{1a9d}
@deffn {Κλάση} contextvars.ContextVar (name[, *, default])

This class is used to declare a new Context Variable, e.g.:

@example
var: ContextVar[int] = ContextVar('var', default=42)
@end example

The required `name' parameter is used for introspection and debug
purposes.

The optional keyword-only `default' parameter is returned by
@ref{39de,,ContextVar.get()} when no value for the variable is found
in the current context.

`Important:' Context Variables should be created at the top module
level and never in closures.  @ref{421,,Context} objects hold strong
references to context variables which prevents context variables
from being properly garbage collected.

@geindex name (ιδιότητα της contextvars.ContextVar)
@anchor{library/contextvars contextvars ContextVar name}@anchor{39df}
@deffn {Ιδιότητα} name

The name of the variable.  This is a read-only property.


Added in version 3.7.1.

@end deffn

@geindex get() (μέθοδος της contextvars.ContextVar)
@anchor{library/contextvars contextvars ContextVar get}@anchor{39de}
@deffn {Μέθοδος} get ([default])

Return a value for the context variable for the current context.

If there is no value for the variable in the current context,
the method will:


@itemize *

@item 
return the value of the `default' argument of the method,
if provided; or

@item 
return the default value for the context variable,
if it was created with one; or

@item 
raise a @ref{25da,,LookupError}.
@end itemize
@end deffn

@geindex set() (μέθοδος της contextvars.ContextVar)
@anchor{library/contextvars contextvars ContextVar set}@anchor{198d}
@deffn {Μέθοδος} set (value)

Call to set a new value for the context variable in the current
context.

The required `value' argument is the new value for the context
variable.

Returns a @ref{479,,Token} object that can be used
to restore the variable to its previous value via the
@ref{39e0,,ContextVar.reset()} method.

For convenience, the token object can be used as a context manager
to avoid calling @ref{39e0,,ContextVar.reset()} manually:

@example
var = ContextVar('var', default='default value')

with var.set('new value'):
    assert var.get() == 'new value'

assert var.get() == 'default value'
@end example

It is a shorthand for:

@example
var = ContextVar('var', default='default value')

token = var.set('new value')
try:
    assert var.get() == 'new value'
finally:
    var.reset(token)

assert var.get() == 'default value'
@end example


Added in version 3.14: Added support for using tokens as context managers.

@end deffn

@geindex reset() (μέθοδος της contextvars.ContextVar)
@anchor{library/contextvars contextvars ContextVar reset}@anchor{39e0}
@deffn {Μέθοδος} reset (token)

Reset the context variable to the value it had before the
@ref{198d,,ContextVar.set()} that created the `token' was used.

For example:

@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

The same `token' cannot be used twice.
@end deffn
@end deffn

@geindex Token (κλάση σε contextvars)
@anchor{library/contextvars contextvars Token}@anchor{479}
@deffn {Κλάση} contextvars.Token

`Token' objects are returned by the @ref{198d,,ContextVar.set()} method.
They can be passed to the @ref{39e0,,ContextVar.reset()} method to revert
the value of the variable to what it was before the corresponding
`set'. A single token cannot reset a context variable more than once.

Tokens support the @ref{2572,,context manager protocol}
to automatically reset context variables. See @ref{198d,,ContextVar.set()}.


Added in version 3.14: Added support for usage as a context manager.


@geindex var (ιδιότητα της contextvars.Token)
@anchor{library/contextvars contextvars Token var}@anchor{39e1}
@deffn {Ιδιότητα} var

A read-only property.  Points to the @ref{1a9d,,ContextVar} object
that created the token.
@end deffn

@geindex old_value (ιδιότητα της contextvars.Token)
@anchor{library/contextvars contextvars Token old_value}@anchor{39e2}
@deffn {Ιδιότητα} old_value

A read-only property.  Set to the value the variable had before
the @ref{198d,,ContextVar.set()} method call that created the token.
It points to @ref{1a4d,,Token.MISSING} if the variable was not set
before the call.
@end deffn

@geindex MISSING (ιδιότητα της contextvars.Token)
@anchor{library/contextvars contextvars Token MISSING}@anchor{1a4d}
@deffn {Ιδιότητα} MISSING

A marker object used by @ref{39e2,,Token.old_value}.
@end deffn
@end deffn

@node Manual Context Management,asyncio support,Context Variables,contextvars — Context Variables
@anchor{library/contextvars manual-context-management}@anchor{39e3}
@subsubsection Manual Context Management


@geindex copy_context() (στη μονάδα contextvars)
@anchor{library/contextvars contextvars copy_context}@anchor{3868}
@deffn {Συνάρτηση} contextvars.copy_context ()

Returns a copy of the current @ref{421,,Context} object.

The following snippet gets a copy of the current context and prints
all variables and their values that are set in it:

@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 (κλάση σε contextvars)
@anchor{library/contextvars contextvars Context}@anchor{421}
@deffn {Κλάση} contextvars.Context

A mapping of @ref{1a9d,,ContextVars} to their values.

@code{Context()} creates an empty context with no values in it.
To get a copy of the current context use the
@ref{3868,,copy_context()} function.

Each thread has its own effective stack of @code{Context} objects.  The
@ref{1b77,,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{198c,,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{198c,,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{1a9d,,ContextVar} objects
behave in a similar fashion to @ref{1a87,,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{30d,,RuntimeError}.

After exiting a context, it can later be re-entered (from any thread).

Any changes to @ref{1a9d,,ContextVar} values via the @ref{198d,,ContextVar.set()}
method are recorded in the current context.  The @ref{39de,,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 implements the @ref{c9c,,collections.abc.Mapping} interface.

@geindex run() (μέθοδος της contextvars.Context)
@anchor{library/contextvars contextvars Context run}@anchor{198c}
@deffn {Μέθοδος} 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() (μέθοδος της contextvars.Context)
@anchor{library/contextvars contextvars Context copy}@anchor{39e4}
@deffn {Μέθοδος} copy ()

Return a shallow copy of the context object.
@end deffn


@deffn {Describe} var in context

Return @code{True} if the `context' has a value for `var' set;
return @code{False} otherwise.
@end deffn


@deffn {Describe} context[var]

Return the value of the `var' @ref{1a9d,,ContextVar} variable.
If the variable is not set in the context object, a
@ref{7df,,KeyError} is raised.
@end deffn

@geindex get() (μέθοδος της contextvars.Context)
@anchor{library/contextvars contextvars Context get}@anchor{39e5}
@deffn {Μέθοδος} get (var[, default])

Return the value for `var' if `var' has the value in the context
object.  Return `default' otherwise.  If `default' is not given,
return @code{None}.
@end deffn


@deffn {Describe} iter(context)

Return an iterator over the variables stored in the context
object.
@end deffn


@deffn {Describe} len(proxy)

Return the number of variables set in the context object.
@end deffn

@geindex keys() (μέθοδος της contextvars.Context)
@anchor{library/contextvars contextvars Context keys}@anchor{39e6}
@deffn {Μέθοδος} keys ()

Return a list of all variables in the context object.
@end deffn

@geindex values() (μέθοδος της contextvars.Context)
@anchor{library/contextvars contextvars Context values}@anchor{39e7}
@deffn {Μέθοδος} values ()

Return a list of all variables” values in the context object.
@end deffn

@geindex items() (μέθοδος της contextvars.Context)
@anchor{library/contextvars contextvars Context items}@anchor{39e8}
@deffn {Μέθοδος} items ()

Return a list of 2-tuples containing all variables and their
values in the context object.
@end deffn
@end deffn

@node asyncio support,,Manual Context Management,contextvars — Context Variables
@anchor{library/contextvars asyncio-support}@anchor{39e9}
@subsubsection asyncio support


Context variables are natively supported in @ref{b,,asyncio} and are
ready to be used without any extra configuration.  For example, here
is a simple echo server, that uses a context variable to make the
address of a remote client available in the Task that handles that
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, it is now possible to get the
    # 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

The following are support modules for some of the above services:

@node _thread — Low-level threading API,,contextvars — Context Variables,Concurrent Execution
@anchor{library/_thread doc}@anchor{39ea}@anchor{library/_thread module-_thread}@anchor{2}@anchor{library/_thread thread-low-level-threading-api}@anchor{39eb}@anchor{library/_thread translation-repo}@anchor{39ec}
@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


__________________________________________________________________


This module provides low-level primitives for working with multiple threads
(also called `light-weight processes' or `tasks') — multiple threads of
control sharing their global data space.  For synchronization, simple locks
(also called `mutexes' or `binary semaphores') are provided.
The @ref{f6,,threading} module provides an easier to use and higher-level
threading API built on top of this module.

@geindex pthreads
@geindex threads;POSIX


Άλλαξε στην έκδοση 3.7: This module used to be optional, it is now always available.


This module defines the following constants and functions:

@geindex error
@anchor{library/_thread thread error}@anchor{39ed}
@deffn {Εξαίρεση} _thread.error

Raised on thread-specific errors.


Άλλαξε στην έκδοση 3.3: This is now a synonym of the built-in @ref{30d,,RuntimeError}.

@end deffn

@geindex LockType (στη μονάδα _thread)
@anchor{library/_thread thread LockType}@anchor{39ee}
@deffn {Δεδομένα} _thread.LockType

This is the type of lock objects.
@end deffn

@geindex start_new_thread() (στη μονάδα _thread)
@anchor{library/_thread thread start_new_thread}@anchor{6bc}
@deffn {Συνάρτηση} _thread.start_new_thread (function, args[, kwargs])

Start a new thread and return its identifier.  The thread executes the
function `function' with the argument list `args' (which must be a tuple).
The optional `kwargs' argument specifies a dictionary of keyword arguments.

When the function returns, the thread silently exits.

When the function terminates with an unhandled exception,
@ref{70c,,sys.unraisablehook()} is called to handle the exception. The `object'
attribute of the hook argument is `function'. By default, a stack trace is
printed and then the thread exits (but other threads continue to run).

When the function raises a @ref{10f7,,SystemExit} exception, it is silently
ignored.

Raises an @ref{1e65,,auditing event} @code{_thread.start_new_thread} with arguments @code{function}, @code{args}, @code{kwargs}.


Άλλαξε στην έκδοση 3.8: @ref{70c,,sys.unraisablehook()} is now used to handle unhandled exceptions.

@end deffn

@geindex interrupt_main() (στη μονάδα _thread)
@anchor{library/_thread thread interrupt_main}@anchor{c1c}
@deffn {Συνάρτηση} _thread.interrupt_main (signum=signal.SIGINT, /)

Simulate the effect of a signal arriving in the main thread.
A thread can use this function to interrupt the main thread, though
there is no guarantee that the interruption will happen immediately.

If given, `signum' is the number of the signal to simulate.
If `signum' is not given, @ref{4df,,signal.SIGINT} is simulated.

If the given signal isn’t handled by Python (it was set to
@ref{1dac,,signal.SIG_DFL} or @ref{1dab,,signal.SIG_IGN}), this function does
nothing.


Άλλαξε στην έκδοση 3.10: The `signum' argument is added to customize the signal number.


@cartouche
@quotation Σημείωση 
This does not emit the corresponding signal but schedules a call to
the associated handler (if it exists).
If you want to truly emit the signal, use @ref{1d8b,,signal.raise_signal()}.
@end quotation
@end cartouche
@end deffn

@geindex exit() (στη μονάδα _thread)
@anchor{library/_thread thread exit}@anchor{39ef}
@deffn {Συνάρτηση} _thread.exit ()

Raise the @ref{10f7,,SystemExit} exception.  When not caught, this will cause the
thread to exit silently.
@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() (στη μονάδα _thread)
@anchor{library/_thread thread allocate_lock}@anchor{39f0}
@deffn {Συνάρτηση} _thread.allocate_lock ()

Return a new lock object.  Methods of locks are described below.  The lock is
initially unlocked.
@end deffn

@geindex get_ident() (στη μονάδα _thread)
@anchor{library/_thread thread get_ident}@anchor{39f1}
@deffn {Συνάρτηση} _thread.get_ident ()

Return the “thread identifier” of the current thread.  This is a nonzero
integer.  Its value has no direct meaning; it is intended as a magic cookie to
be used e.g. to index a dictionary of thread-specific data.  Thread identifiers
may be recycled when a thread exits and another thread is created.
@end deffn

@geindex get_native_id() (στη μονάδα _thread)
@anchor{library/_thread thread get_native_id}@anchor{39f2}
@deffn {Συνάρτηση} _thread.get_native_id ()

Return the native integral Thread ID of the current thread assigned by the kernel.
This is a non-negative integer.
Its 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).

@ref{232d,,Διαθεσιμότητα}: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD, Solaris.


Added in version 3.8.



Άλλαξε στην έκδοση 3.13: Added support for GNU/kFreeBSD.



Άλλαξε στην έκδοση 3.15: Added support for Solaris.

@end deffn

@geindex stack_size() (στη μονάδα _thread)
@anchor{library/_thread thread stack_size}@anchor{197a}
@deffn {Συνάρτηση} _thread.stack_size ([size])

Return the thread stack size used when creating new threads.  The optional
`size' argument specifies the stack size to be used for subsequently created
threads, and must be 0 (use platform or configured default) or a positive
integer value of at least 32,768 (32 KiB). If `size' is not specified,
0 is used.  If changing the thread stack size is
unsupported, a @ref{30d,,RuntimeError} is raised.  If the specified stack size is
invalid, a @ref{277,,ValueError} is raised and the stack size is unmodified.  32 KiB
is currently the minimum supported stack size value to guarantee sufficient
stack space for the interpreter itself.  Note that some platforms may have
particular restrictions on values for the stack size, such as requiring a
minimum stack size > 32 KiB or requiring allocation in multiples of the system
memory page size - platform documentation should be referred to for more
information (4 KiB pages are common; using multiples of 4096 for the stack size is
the suggested approach in the absence of more specific information).

@ref{232d,,Διαθεσιμότητα}: Windows, pthreads.

Unix platforms with POSIX threads support.
@end deffn

@geindex TIMEOUT_MAX (στη μονάδα _thread)
@anchor{library/_thread thread TIMEOUT_MAX}@anchor{39f3}
@deffn {Δεδομένα} _thread.TIMEOUT_MAX

The maximum value allowed for the `timeout' parameter of
@ref{a87,,Lock.acquire}. Specifying a timeout greater
than this value will raise an @ref{c57,,OverflowError}.


Added in version 3.2.

@end deffn

Lock objects have the following methods:

@geindex acquire() (μέθοδος της _thread.lock)
@anchor{library/_thread thread lock acquire}@anchor{39f4}
@deffn {Μέθοδος} lock.acquire (blocking=True, timeout=-1)

Without any optional argument, this method acquires the lock unconditionally, if
necessary waiting until it is released by another thread (only one thread at a
time can acquire a lock — that’s their reason for existence).

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.

The return value is @code{True} if the lock is acquired successfully,
@code{False} if not.


Άλλαξε στην έκδοση 3.2: The `timeout' parameter is new.



Άλλαξε στην έκδοση 3.2: Lock acquires can now be interrupted by signals on POSIX.



Άλλαξε στην έκδοση 3.14: Lock acquires can now be interrupted by signals on Windows.

@end deffn

@geindex release() (μέθοδος της _thread.lock)
@anchor{library/_thread thread lock release}@anchor{39f5}
@deffn {Μέθοδος} lock.release ()

Releases the lock.  The lock must have been acquired earlier, but not
necessarily by the same thread.
@end deffn

@geindex locked() (μέθοδος της _thread.lock)
@anchor{library/_thread thread lock locked}@anchor{39f6}
@deffn {Μέθοδος} lock.locked ()

Return the status of the lock: @code{True} if it has been acquired by some thread,
@code{False} if not.
@end deffn

In addition to these methods, lock objects can also be used via the
@ref{20a,,with} statement, e.g.:

@example
import _thread

a_lock = _thread.allocate_lock()

with a_lock:
    print("a_lock is locked while this executes")
@end example

`Caveats:'

@geindex module;signal


@itemize *

@item 
Interrupts always go to the main thread (the @ref{d96,,KeyboardInterrupt}
exception will be received by that thread.)

@item 
Calling @ref{4ff,,sys.exit()} or raising the @ref{10f7,,SystemExit} exception is
equivalent to calling @ref{39ef,,_thread.exit()}.

@item 
When the main thread exits, it is system defined whether the other threads
survive.  On most systems, they are killed without executing
@ref{ad6,,try} … @ref{44c,,finally} clauses or executing object
destructors.
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Networking and Interprocess Communication,Internet Data Handling,Concurrent Execution,The Python Standard Library
@anchor{library/ipc doc}@anchor{39f7}@anchor{library/ipc ipc}@anchor{39f8}@anchor{library/ipc networking-and-interprocess-communication}@anchor{39f9}@anchor{library/ipc translation-repo}@anchor{39fa}
@section Networking and Interprocess Communication


The modules described in this chapter provide mechanisms for
networking and inter-processes communication.

Some modules only work for two processes that are on the same machine, e.g.
@ref{ce,,signal} and @ref{94,,mmap}.  Other modules support networking protocols
that two or more processes can use to communicate across machines.

The list of modules described in this chapter is:

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

@end menu

@node asyncio — Asynchronous I/O,socket — Low-level networking interface,,Networking and Interprocess Communication
@anchor{library/asyncio doc}@anchor{39fb}@anchor{library/asyncio asyncio-asynchronous-i-o}@anchor{39fc}@anchor{library/asyncio module-asyncio}@anchor{b}
@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

asyncio is a library to write `concurrent' code using
the `async/await' syntax.

asyncio is used as a foundation for multiple Python asynchronous
frameworks that provide high-performance network and web-servers,
database connection libraries, distributed task queues, etc.

asyncio is often a perfect fit for IO-bound and high-level
`structured' network code.


@subsubheading Δείτε επίσης



@table @asis

@item @ref{39fd,,A conceptual overview of asyncio}

Explanation of the fundamentals of asyncio.
@end table


asyncio provides a set of `high-level' APIs to:


@itemize *

@item 
@ref{39fe,,run Python coroutines} concurrently and
have full control over their execution;

@item 
perform @ref{19b0,,network IO and IPC};

@item 
control @ref{39ff,,subprocesses};

@item 
distribute tasks via @ref{3a00,,queues};

@item 
@ref{3a01,,synchronize} concurrent code;
@end itemize

Additionally, there are `low-level' APIs for
`library and framework developers' to:


@itemize *

@item 
create and manage @ref{112f,,event loops}, which
provide asynchronous APIs for @ref{3a02,,networking},
running @ref{3a03,,subprocesses},
handling @ref{3a04,,OS signals}, etc;

@item 
implement efficient protocols using
@ref{3a05,,transports};

@item 
@ref{3a06,,bridge} callback-based libraries and code
with async/await syntax.
@end itemize

@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.
@anchor{library/asyncio asyncio-cli}@anchor{3a07}
@subsubheading asyncio REPL


You can experiment with an @code{asyncio} concurrent context in the @ref{69d,,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

This REPL provides limited compatibility with 
@geindex PYTHON_BASIC_REPL
@geindex μεταβλητή περιβάλλοντος; PYTHON_BASIC_REPL
@ref{452,,PYTHON_BASIC_REPL}.
It is recommended that the default REPL is used
for full functionality and the latest features.

Raises an @ref{1e65,,auditing event} @code{cpython.run_stdin} with no arguments.


Άλλαξε στην έκδοση 3.12.5: (also 3.11.10, 3.10.15, 3.9.20, and 3.8.20)
Emits audit events.



Άλλαξε στην έκδοση 3.13: Uses PyREPL if possible, in which case 
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,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 Reference


@menu
* Runners:: 
* Coroutines and tasks:: 
* Streams:: 
* Synchronization Primitives:: 
* Subprocesses:: 
* Ουρές:: 
* Exceptions: Exceptions<14>. 
* Call Graph Introspection:: 
* Event loop:: 
* Futures:: 
* Transports and Protocols:: 
* Policies:: 
* Platform Support:: 
* Extending:: 
* High-level API Index:: 
* Low-level API Index:: 
* Developing with asyncio:: 

@end menu

@node Runners,Coroutines and tasks,,asyncio — Asynchronous I/O
@anchor{library/asyncio-runner doc}@anchor{3a08}@anchor{library/asyncio-runner runners}@anchor{3a09}
@subsubsection Runners


`Source code:' Lib/asyncio/runners.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/runners.py}

This section outlines high-level asyncio primitives to run asyncio code.

They are built on top of an @ref{112f,,event loop} with the aim
to simplify async code usage for common wide-spread scenarios.

@menu
* Running an asyncio Program:: 
* Runner context manager:: 
* Handling Keyboard Interruption:: 

@end menu

@node Running an asyncio Program,Runner context manager,,Runners
@anchor{library/asyncio-runner running-an-asyncio-program}@anchor{3a0a}
@subsubsection Running an asyncio Program


@geindex run() (στη μονάδα asyncio)
@anchor{library/asyncio-runner asyncio run}@anchor{309}
@deffn {Συνάρτηση} asyncio.run (coro, *, debug=None, loop_factory=None)

Execute `coro' in an asyncio event loop and return the result.

The argument can be any awaitable object.

This function runs the awaitable, taking care of managing the
asyncio event loop, `finalizing asynchronous generators', and
closing the executor.

This function cannot be called when another asyncio event loop is
running in the same thread.

If `debug' is @code{True}, the event loop will be run in debug mode. @code{False} disables
debug mode explicitly. @code{None} is used to respect the global
@ref{2328,,Debug Mode} settings.

If `loop_factory' is not @code{None}, it is used to create a new event loop;
otherwise @ref{3a0b,,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{1c6d,,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.

Example:

@example
async def main():
    await asyncio.sleep(1)
    print('hello')

asyncio.run(main())
@end example


Added in version 3.7.



Άλλαξε στην έκδοση 3.9: Updated to use @ref{cb8,,loop.shutdown_default_executor()}.



Άλλαξε στην έκδοση 3.10: `debug' is @code{None} by default to respect the global debug mode settings.



Άλλαξε στην έκδοση 3.12: Added `loop_factory' parameter.



Άλλαξε στην έκδοση 3.14: `coro' can be any awaitable object.


@cartouche
@quotation Σημείωση 
The @code{asyncio} policy system is deprecated and will be removed
in Python 3.16; from there on, an explicit `loop_factory' is needed
to configure the event loop.
@end quotation
@end cartouche
@end deffn

@node Runner context manager,Handling Keyboard Interruption,Running an asyncio Program,Runners
@anchor{library/asyncio-runner runner-context-manager}@anchor{3a0c}
@subsubsection Runner context manager


@geindex Runner (κλάση σε asyncio)
@anchor{library/asyncio-runner asyncio Runner}@anchor{30a}
@deffn {Κλάση} asyncio.Runner (*, debug=None, loop_factory=None)

A context manager that simplifies `multiple' async function calls in the same
context.

Sometimes several top-level async functions should be called in the same @ref{112f,,event loop} and @ref{421,,contextvars.Context}.

If `debug' is @code{True}, the event loop will be run in debug mode. @code{False} disables
debug mode explicitly. @code{None} is used to respect the global
@ref{2328,,Debug Mode} settings.

`loop_factory' could be used for overriding the loop creation.
It is the responsibility of the `loop_factory' to set the created loop as the
current one. By default @ref{3a0b,,asyncio.new_event_loop()} is used and set as
current event loop with @ref{1d53,,asyncio.set_event_loop()} if `loop_factory' is @code{None}.

Basically, @ref{309,,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


Added in version 3.11.


@geindex run() (μέθοδος της asyncio.Runner)
@anchor{library/asyncio-runner asyncio Runner run}@anchor{1b62}
@deffn {Μέθοδος} run (coro, *, context=None)

Execute `coro' in the embedded event loop.

The argument can be any awaitable object.

If the argument is a coroutine, it is wrapped in a Task.

An optional keyword-only `context' argument allows specifying a
custom @ref{421,,contextvars.Context} for the code to run in.
The runner’s default context is used if context is @code{None}.

Returns the awaitable’s result or raises an exception.

This function cannot be called when another asyncio event loop is
running in the same thread.


Άλλαξε στην έκδοση 3.14: `coro' can be any awaitable object.

@end deffn

@geindex close() (μέθοδος της asyncio.Runner)
@anchor{library/asyncio-runner asyncio Runner close}@anchor{3a0d}
@deffn {Μέθοδος} close ()

Close the runner.

Finalize asynchronous generators, shutdown default executor, close the event loop
and release embedded @ref{421,,contextvars.Context}.
@end deffn

@geindex get_loop() (μέθοδος της asyncio.Runner)
@anchor{library/asyncio-runner asyncio Runner get_loop}@anchor{3a0e}
@deffn {Μέθοδος} get_loop ()

Return the event loop associated with the runner instance.
@end deffn

@cartouche
@quotation Σημείωση 
@code{Runner} uses the lazy initialization strategy, its constructor doesn’t
initialize underlying low-level structures.

Embedded `loop' and `context' are created at the @ref{20a,,with} body entering
or the first call of @ref{309,,run()} or @ref{3a0e,,get_loop()}.
@end quotation
@end cartouche
@end deffn

@node Handling Keyboard Interruption,,Runner context manager,Runners
@anchor{library/asyncio-runner handling-keyboard-interruption}@anchor{3a0f}
@subsubsection Handling Keyboard Interruption



Added in version 3.11.


When @ref{4df,,signal.SIGINT} is raised by @code{Ctrl}-@code{C}, @ref{d96,,KeyboardInterrupt}
exception is raised in the main thread by default. However this doesn’t work with
@ref{b,,asyncio} because it can interrupt asyncio internals and can hang the program from
exiting.

To mitigate this issue, @ref{b,,asyncio} handles @ref{4df,,signal.SIGINT} as follows:


@enumerate 

@item 
@ref{1b62,,asyncio.Runner.run()} installs a custom @ref{4df,,signal.SIGINT} handler before
any user code is executed and removes it when exiting from the function.

@item 
The @ref{30a,,Runner} creates the main task for the passed coroutine for its
execution.

@item 
When @ref{4df,,signal.SIGINT} is raised by @code{Ctrl}-@code{C}, the custom signal handler
cancels the main task by calling @ref{6d9,,asyncio.Task.cancel()} which raises
@ref{6da,,asyncio.CancelledError} inside the main task.  This causes the Python stack
to unwind, @code{try/except} and @code{try/finally} blocks can be used for resource
cleanup.  After the main task is cancelled, @ref{1b62,,asyncio.Runner.run()} raises
@ref{d96,,KeyboardInterrupt}.

@item 
A user could write a tight loop which cannot be interrupted by
@ref{6d9,,asyncio.Task.cancel()}, in which case the second following @code{Ctrl}-@code{C}
immediately raises the @ref{d96,,KeyboardInterrupt} without cancelling the main task.
@end enumerate

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Coroutines and tasks,Streams,Runners,asyncio — Asynchronous I/O
@anchor{library/asyncio-task doc}@anchor{3a10}@anchor{library/asyncio-task coroutines-and-tasks}@anchor{3a11}@anchor{library/asyncio-task translation-repo}@anchor{3a12}
@subsubsection Coroutines and tasks


This section outlines high-level asyncio APIs to work with coroutines
and Tasks.

@menu
* Coroutines: Coroutines<3>. 
* Awaitables:: 
* Creating tasks:: 
* Task cancellation:: 
* Task groups:: 
* Sleeping:: 
* Running tasks concurrently:: 
* Eager task factory:: 
* Shielding from cancellation:: 
* Timeouts:: 
* Waiting primitives:: 
* Running in threads:: 
* Scheduling from other threads:: 
* Introspection:: 
* Task object:: 

@end menu

@node Coroutines<3>,Awaitables,,Coroutines and tasks
@anchor{library/asyncio-task coroutine}@anchor{39fe}@anchor{library/asyncio-task coroutines}@anchor{3a13}
@subsubsection Coroutines


`Source code:' Lib/asyncio/coroutines.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/coroutines.py}


__________________________________________________________________


@ref{8a2,,Coroutines} declared with the async/await syntax is the
preferred way of writing asyncio applications.  For example, the following
snippet of code prints «hello», waits 1 second,
and then prints «world»:

@example
>>> import asyncio

>>> async def main():
...     print('hello')
...     await asyncio.sleep(1)
...     print('world')

>>> asyncio.run(main())
hello
world
@end example

Note that simply calling a coroutine will not schedule it to
be executed:

@example
>>> main()
<coroutine object main at 0x1053bb7c8>
@end example

To actually run a coroutine, asyncio provides the following mechanisms:


@itemize *

@item 
The @ref{309,,asyncio.run()} function to run the top-level
entry point «main()» function (see the above example.)

@item 
Awaiting on a coroutine.  The following snippet of code will
print «hello» after waiting for 1 second, and then print «world»
after waiting for `another' 2 seconds:

@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

Expected output:

@example
started at 17:13:52
hello
world
finished at 17:13:55
@end example

@item 
The @ref{462,,asyncio.create_task()} function to run coroutines
concurrently as asyncio @ref{460,,Tasks}.

Let’s modify the above example and run two @code{say_after} coroutines
`concurrently':

@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

Note that expected output now shows that the snippet runs
1 second faster than before:

@example
started at 17:14:32
hello
world
finished at 17:14:34
@end example

@item 
The @ref{6d7,,asyncio.TaskGroup} class provides a more modern
alternative to @ref{462,,create_task()}.
Using this API, the last example becomes:

@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

The timing and output should be the same as for the previous version.


Added in version 3.11: @ref{6d7,,asyncio.TaskGroup}.

@end itemize

@node Awaitables,Creating tasks,Coroutines<3>,Coroutines and tasks
@anchor{library/asyncio-task asyncio-awaitables}@anchor{3a14}@anchor{library/asyncio-task awaitables}@anchor{3a15}
@subsubsection Awaitables


We say that an object is an `awaitable' object if it can be used
in an @ref{432,,await} expression.  Many asyncio APIs are designed to
accept awaitables.

There are three main types of `awaitable' objects:
`coroutines', `Tasks', and `Futures'.

@subsubheading Coroutines


Python coroutines are `awaitables' and therefore can be awaited from
other 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 Σημαντικό 
In this documentation the term «coroutine» can be used for
two closely related concepts:


@itemize *

@item 
a `coroutine function': an @ref{9cf,,async def} function;

@item 
a `coroutine object': an object returned by calling a
`coroutine function'.
@end itemize
@end quotation
@end cartouche

@subsubheading Tasks


`Tasks' are used to schedule coroutines `concurrently'.

When a coroutine is wrapped into a `Task' with functions like
@ref{462,,asyncio.create_task()} the coroutine is automatically
scheduled to run soon:

@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 Futures


A @ref{f8b,,Future} is a special `low-level' awaitable object that
represents an `eventual result' of an asynchronous operation.

When a Future object is `awaited' it means that the coroutine will
wait until the Future is resolved in some other place.

Future objects in asyncio are needed to allow callback-based code
to be used with async/await.

Normally `there is no need' to create Future objects at the
application level code.

Future objects, sometimes exposed by libraries and some asyncio
APIs, can be awaited:

@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

A good example of a low-level function that returns a Future object
is @ref{cba,,loop.run_in_executor()}.

@node Creating tasks,Task cancellation,Awaitables,Coroutines and tasks
@anchor{library/asyncio-task creating-tasks}@anchor{3a16}
@subsubsection Creating tasks


`Source code:' Lib/asyncio/tasks.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/tasks.py}


__________________________________________________________________


@geindex create_task() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio create_task}@anchor{462}
@deffn {Συνάρτηση} asyncio.create_task (coro, *, name=None, context=None, eager_start=None, **kwargs)

Wrap the `coro' @ref{39fe,,coroutine} into a @ref{460,,Task}
and schedule its execution.  Return the Task object.

The full function signature is largely the same as that of the
@ref{460,,Task} constructor (or factory) - all of the keyword arguments to
this function are passed through to that interface.

An optional keyword-only `context' argument allows specifying a
custom @ref{421,,contextvars.Context} for the `coro' to run in.
The current context copy is created when no `context' is provided.

An optional keyword-only `eager_start' argument allows specifying
if the task should execute eagerly during the call to create_task,
or be scheduled later. If `eager_start' is not passed the mode set
by @ref{461,,loop.set_task_factory()} will be used.

The task is executed in the loop returned by @ref{ecf,,get_running_loop()},
@ref{30d,,RuntimeError} is raised if there is no running loop in
current thread.

@cartouche
@quotation Σημείωση 
@ref{464,,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 Σημαντικό 
Save a reference to the result of this function, to avoid
a task disappearing mid-execution. The event loop only keeps
weak references to tasks. A task that isn’t referenced elsewhere
may get garbage collected at any time, even before it’s done.
For reliable «fire-and-forget» background tasks, gather them in
a 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


Added in version 3.7.



Άλλαξε στην έκδοση 3.8: Added the `name' parameter.



Άλλαξε στην έκδοση 3.11: Added the `context' parameter.



Άλλαξε στην έκδοση 3.14: Added the `eager_start' parameter by passing on all `kwargs'.

@end deffn

@node Task cancellation,Task groups,Creating tasks,Coroutines and tasks
@anchor{library/asyncio-task task-cancellation}@anchor{3a17}
@subsubsection Task cancellation


Tasks can easily and safely be cancelled.
When a task is cancelled, @ref{6da,,asyncio.CancelledError} will be raised
in the task at the next opportunity.

It is recommended that coroutines use @code{try/finally} blocks to robustly
perform clean-up logic. In case @ref{6da,,asyncio.CancelledError}
is explicitly caught, it should generally be propagated when
clean-up is complete. @code{asyncio.CancelledError} directly subclasses
@ref{9b9,,BaseException} so most code will not need to be aware of it.

The asyncio components that enable structured concurrency, like
@ref{6d7,,asyncio.TaskGroup} and @ref{9f5,,asyncio.timeout()},
are implemented using cancellation internally and might misbehave if
a coroutine swallows @ref{6da,,asyncio.CancelledError}. Similarly, user code
should not generally call @ref{6dc,,uncancel}.
However, in cases when suppressing @code{asyncio.CancelledError} is
truly desired, it is necessary to also call @code{uncancel()} to completely
remove the cancellation state.

@node Task groups,Sleeping,Task cancellation,Coroutines and tasks
@anchor{library/asyncio-task task-groups}@anchor{3a18}@anchor{library/asyncio-task taskgroups}@anchor{3a19}
@subsubsection Task groups


Task groups combine a task creation API with a convenient
and reliable way to wait for all tasks in the group to finish.

@geindex TaskGroup (κλάση σε asyncio)
@anchor{library/asyncio-task asyncio TaskGroup}@anchor{6d7}
@deffn {Κλάση} asyncio.TaskGroup

An @ref{9f3,,asynchronous context manager}
holding a group of tasks.
Tasks can be added to the group using @ref{462,,create_task()}.
All tasks are awaited when the context manager exits.


Added in version 3.11.


@geindex create_task() (μέθοδος της asyncio.TaskGroup)
@anchor{library/asyncio-task asyncio TaskGroup create_task}@anchor{464}
@deffn {Μέθοδος} create_task (coro, *, name=None, context=None, eager_start=None, **kwargs)

Create a task in this task group.
The signature matches that of @ref{462,,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}.


Άλλαξε στην έκδοση 3.13: Close the given coroutine if the task group is not active.



Άλλαξε στην έκδοση 3.14: Passes on all `kwargs' to @ref{463,,loop.create_task()}

@end deffn

@geindex cancel() (μέθοδος της asyncio.TaskGroup)
@anchor{library/asyncio-task asyncio TaskGroup cancel}@anchor{1e4}
@deffn {Μέθοδος} cancel ()

Cancel the task group.  This is a non-exceptional, early exit of the
task group’s lifetime – useful once the group’s goal has been met or
its services no longer needed.

@ref{6d9,,cancel()} will be called on any tasks in the group that
aren’t yet done, as well as the parent (body) of the group.  The task group
context manager will exit `without' @ref{6da,,asyncio.CancelledError} being raised.

If @code{cancel()} is called before entering the task group, the group will be
cancelled upon entry.  This is useful for patterns where one piece of
code passes an unused @ref{6d7,,asyncio.TaskGroup} instance to another in order to have
the ability to cancel anything run within the group.

@code{cancel()} is idempotent and may be called after the task group has
already exited.

Some ways to use @code{cancel()}:


@itemize *

@item 
call it from the task group body based on some condition or event

@item 
pass the task group instance to child tasks via @ref{462,,create_task()}, allowing a child
task to conditionally cancel the entire entire group

@item 
pass the task group instance or bound @code{cancel()} method to some other task `before'
opening the task group, allowing remote cancellation
@end itemize


Added in version 3.15.

@end deffn
@end deffn

Example:

@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

The @code{async with} statement will wait for all tasks in the group to finish.
While waiting, new tasks may still be added to the group
(for example, by passing @code{tg} into one of the coroutines
and calling @code{tg.create_task()} in that coroutine).  There is also opportunity to
request termination of the entire task group with @code{tg.cancel()}, based on some condition.
Once the last task has finished and the @code{async with} block is exited,
no new tasks may be added to the group.

The first time any of the tasks belonging to the group fails
with an exception other than @ref{6da,,asyncio.CancelledError},
the remaining tasks in the group are cancelled.
No further tasks can then be added to the group.
At this point, if the body of the @code{async with} statement is still active
(i.e., @ref{1bad,,__aexit__()} hasn’t been called yet),
the task directly containing the @code{async with} statement is also cancelled.
The resulting @code{asyncio.CancelledError} will interrupt an @code{await},
but it will not bubble out of the containing @code{async with} statement.

Once all tasks have finished, if any tasks have failed
with an exception other than @ref{6da,,asyncio.CancelledError},
those exceptions are combined in an
@ref{6d8,,ExceptionGroup} or @ref{767,,BaseExceptionGroup}
(as appropriate; see their documentation)
which is then raised.

Two base exceptions are treated specially:
If any task fails with @ref{d96,,KeyboardInterrupt} or @ref{10f7,,SystemExit},
the task group still cancels the remaining tasks and waits for them,
but then the initial @code{KeyboardInterrupt} or @code{SystemExit}
is re-raised instead of @ref{6d8,,ExceptionGroup} or @ref{767,,BaseExceptionGroup}.

If the body of the @code{async with} statement exits with an exception
(so @ref{1bad,,__aexit__()} is called with an exception set),
this is treated the same as if one of the tasks failed:
the remaining tasks are cancelled and then waited for,
and non-cancellation exceptions are grouped into an
exception group and raised.
The exception passed into @code{__aexit__()},
unless it is @ref{6da,,asyncio.CancelledError},
is also included in the exception group.
The same special case is made for
@ref{d96,,KeyboardInterrupt} and @ref{10f7,,SystemExit} as in the previous paragraph.

Task groups are careful not to mix up the internal cancellation used to
«wake up» their @ref{1bad,,__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{6d8,,ExceptionGroup}, it will call the parent task’s
@ref{6d9,,cancel()} method. This ensures that a
@ref{6da,,asyncio.CancelledError} will be raised at the next
@ref{432,,await}, so the cancellation is not lost.

Task groups preserve the cancellation count
reported by @ref{6db,,asyncio.Task.cancelling()}.


Άλλαξε στην έκδοση 3.13: Improved handling of simultaneous internal and external cancellations
and correct preservation of cancellation counts.


@node Sleeping,Running tasks concurrently,Task groups,Coroutines and tasks
@anchor{library/asyncio-task sleeping}@anchor{3a1a}
@subsubsection Sleeping


@geindex sleep() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio sleep}@anchor{e33}
@deffn {Συνάρτηση} async asyncio.sleep (delay, result=None)

Block for `delay' seconds.

If `result' is provided, it is returned to the caller
when the coroutine completes.

@code{sleep()} always suspends the current task, allowing other tasks
to run.

Setting the delay to 0 provides an optimized path to allow other
tasks to run. This can be used by long-running functions to avoid
blocking the event loop for the full duration of the function call.
@anchor{library/asyncio-task asyncio-example-sleep}@anchor{3a1b}
Example of coroutine displaying the current date every second
for 5 seconds:

@example
import asyncio
import datetime as dt

async def display_date():
    loop = asyncio.get_running_loop()
    end_time = loop.time() + 5.0
    while True:
        print(dt.datetime.now())
        if (loop.time() + 1.0) >= end_time:
            break
        await asyncio.sleep(1)

asyncio.run(display_date())
@end example


Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.



Άλλαξε στην έκδοση 3.13: Raises @ref{277,,ValueError} if `delay' is @ref{a53,,nan}.

@end deffn

@node Running tasks concurrently,Eager task factory,Sleeping,Coroutines and tasks
@anchor{library/asyncio-task running-tasks-concurrently}@anchor{3a1c}
@subsubsection Running tasks concurrently


@geindex gather() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio gather}@anchor{9f4}
@deffn {Συνάρτηση} awaitable asyncio.gather (*aws, return_exceptions=False)

Run @ref{3a14,,awaitable objects} in the `aws'
sequence `concurrently'.

If any awaitable in `aws' is a coroutine, it is automatically
scheduled as a Task.

If all awaitables are completed successfully, the result is an
aggregate list of returned values.  The order of result values
corresponds to the order of awaitables in `aws'.

If `return_exceptions' is @code{False} (default), the first
raised exception is immediately propagated to the task that
awaits on @code{gather()}.  Other awaitables in the `aws' sequence
`won’t be cancelled' and will continue to run.

If `return_exceptions' is @code{True}, exceptions are treated the
same as successful results, and aggregated in the result list.

If @code{gather()} is `cancelled', all submitted awaitables
(that have not completed yet) are also `cancelled'.

If any Task or Future from the `aws' sequence is `cancelled', it is
treated as if it raised @ref{6da,,CancelledError} – the @code{gather()}
call is `not' cancelled in this case.  This is to prevent the
cancellation of one submitted Task/Future to cause other
Tasks/Futures to be cancelled.

@cartouche
@quotation Σημείωση 
A new alternative to create and run tasks concurrently and
wait for their completion is @ref{6d7,,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{3a1d}
Example:

@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 Σημείωση 
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


Άλλαξε στην έκδοση 3.7: If the `gather' itself is cancelled, the cancellation is
propagated regardless of `return_exceptions'.



Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.



Αποσύρθηκε στην έκδοση 3.10: Deprecation warning is emitted if no positional arguments are provided
or not all positional arguments are Future-like objects
and there is no running event loop.

@end deffn

@node Eager task factory,Shielding from cancellation,Running tasks concurrently,Coroutines and tasks
@anchor{library/asyncio-task eager-task-factory}@anchor{3a1e}@anchor{library/asyncio-task id1}@anchor{3a1f}
@subsubsection Eager task factory


@geindex eager_task_factory() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio eager_task_factory}@anchor{88d}
@deffn {Συνάρτηση} asyncio.eager_task_factory (loop, coro, *, name=None, context=None)

A task factory for eager task execution.

When using this factory (via @ref{461,,loop.set_task_factory(asyncio.eager_task_factory)}),
coroutines begin execution synchronously during @ref{460,,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 Σημείωση 
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


Added in version 3.12.

@end deffn

@geindex create_eager_task_factory() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio create_eager_task_factory}@anchor{88e}
@deffn {Συνάρτηση} asyncio.create_eager_task_factory (custom_task_constructor)

Create an eager task factory, similar to @ref{88d,,eager_task_factory()},
using the provided `custom_task_constructor' when creating a new task instead
of the default @ref{460,,Task}.

`custom_task_constructor' must be a `callable' with the signature matching
the signature of @ref{460,,Task.__init__}.
The callable must return a @ref{460,,asyncio.Task}-compatible object.

This function returns a `callable' intended to be used as a task factory of an
event loop via @ref{461,,loop.set_task_factory(factory)}).


Added in version 3.12.

@end deffn

@node Shielding from cancellation,Timeouts,Eager task factory,Coroutines and tasks
@anchor{library/asyncio-task shielding-from-cancellation}@anchor{3a20}
@subsubsection Shielding from cancellation


@geindex shield() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio shield}@anchor{e34}
@deffn {Συνάρτηση} awaitable asyncio.shield (aw)

Protect an @ref{3a14,,awaitable object}
from being @ref{6d9,,cancelled}.

If `aw' is a coroutine it is automatically scheduled as a Task.

The statement:

@example
task = asyncio.create_task(something())
res = await shield(task)
@end example

is equivalent to:

@example
res = await something()
@end example

`except' that if the coroutine containing it is cancelled, the
Task running in @code{something()} is not cancelled.  From the point
of view of @code{something()}, the cancellation did not happen.
Although its caller is still cancelled, so the «await» expression
still raises a @ref{6da,,CancelledError}.

If @code{something()} is cancelled by other means (i.e. from within
itself) that would also cancel @code{shield()}.

If it is desired to completely ignore cancellation (not recommended)
the @code{shield()} function should be combined with a try/except
clause, as follows:

@example
task = asyncio.create_task(something())
try:
    res = await shield(task)
except CancelledError:
    res = None
@end example

@cartouche
@quotation Σημαντικό 
Save a reference to tasks passed to this function, to avoid
a task disappearing mid-execution. The event loop only keeps
weak references to tasks. A task that isn’t referenced elsewhere
may get garbage collected at any time, even before it’s done.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.



Αποσύρθηκε στην έκδοση 3.10: Deprecation warning is emitted if `aw' is not Future-like object
and there is no running event loop.

@end deffn

@node Timeouts,Waiting primitives,Shielding from cancellation,Coroutines and tasks
@anchor{library/asyncio-task timeouts}@anchor{3a21}
@subsubsection Timeouts


@geindex timeout() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio timeout}@anchor{9f5}
@deffn {Συνάρτηση} asyncio.timeout (delay)

Return an @ref{9f3,,asynchronous context manager}
that can be used to limit the amount of time spent waiting on
something.

`delay' can either be @code{None}, or a float/int number of
seconds to wait. If `delay' is @code{None}, no time limit will
be applied; this can be useful if the delay is unknown when
the context manager is created.

In either case, the context manager can be rescheduled after
creation using @ref{3a22,,Timeout.reschedule()}.

Example:

@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{6da,,asyncio.CancelledError} internally, transforming it
into a @ref{c0e,,TimeoutError} which can be caught and handled.

@cartouche
@quotation Σημείωση 
The @ref{9f5,,asyncio.timeout()} context manager is what transforms
the @ref{6da,,asyncio.CancelledError} into a @ref{c0e,,TimeoutError},
which means the @code{TimeoutError} can only be caught
`outside' of the context manager.
@end quotation
@end cartouche

Example of catching @ref{c0e,,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

The context manager produced by @ref{9f5,,asyncio.timeout()} can be
rescheduled to a different deadline and inspected.

@geindex Timeout (κλάση σε asyncio)
@anchor{library/asyncio-task asyncio Timeout}@anchor{1c47}
@deffn {Κλάση} asyncio.Timeout (when)

An @ref{9f3,,asynchronous context manager}
for cancelling overdue coroutines.

Prefer using @ref{9f5,,asyncio.timeout()} or @ref{1dad,,asyncio.timeout_at()}
rather than instantiating @code{Timeout} directly.

@code{when} should be an absolute time at which the context should time out,
as measured by the event loop’s clock:


@itemize -

@item 
If @code{when} is @code{None}, the timeout will never trigger.

@item 
If @code{when < loop.time()}, the timeout will trigger on the next
iteration of the event loop.
@end itemize

@quotation

@geindex when() (μέθοδος της asyncio.Timeout)
@anchor{library/asyncio-task asyncio Timeout when}@anchor{3a23}
@deffn {Μέθοδος} when () -> float | None

Return the current deadline, or @code{None} if the current
deadline is not set.
@end deffn

@geindex reschedule() (μέθοδος της asyncio.Timeout)
@anchor{library/asyncio-task asyncio Timeout reschedule}@anchor{3a22}
@deffn {Μέθοδος} reschedule (when: float | None)

Reschedule the timeout.
@end deffn

@geindex expired() (μέθοδος της asyncio.Timeout)
@anchor{library/asyncio-task asyncio Timeout expired}@anchor{3a24}
@deffn {Μέθοδος} expired () -> bool

Return whether the context manager has exceeded its deadline
(expired).
@end deffn
@end quotation
@end deffn

Example:

@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

Timeout context managers can be safely nested.


Added in version 3.11.

@end deffn

@geindex timeout_at() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio timeout_at}@anchor{1dad}
@deffn {Συνάρτηση} asyncio.timeout_at (when)

Similar to @ref{9f5,,asyncio.timeout()}, except `when' is the absolute time
to stop waiting, or @code{None}.

Example:

@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


Added in version 3.11.

@end deffn

@geindex wait_for() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio wait_for}@anchor{9f6}
@deffn {Συνάρτηση} async asyncio.wait_for (aw, timeout)

Wait for the `aw' @ref{3a14,,awaitable}
to complete with a timeout.

If `aw' is a coroutine it is automatically scheduled as a Task.

`timeout' can either be @code{None} or a float or int number of seconds
to wait for.  If `timeout' is @code{None}, block until the future
completes.

If a timeout occurs, it cancels the task and raises
@ref{c0e,,TimeoutError}.

To avoid the task @ref{6d9,,cancellation},
wrap it in @ref{e34,,shield()}.

The function will wait until the future is actually cancelled,
so the total wait time may exceed the `timeout'. If an exception
happens during cancellation, it is propagated.

If the wait is cancelled, the future `aw' is also cancelled.
@anchor{library/asyncio-task asyncio-example-waitfor}@anchor{3a25}
Example:

@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


Άλλαξε στην έκδοση 3.7: When `aw' is cancelled due to a timeout, @code{wait_for} waits
for `aw' to be cancelled.  Previously, it raised
@ref{c0e,,TimeoutError} immediately.



Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.



Άλλαξε στην έκδοση 3.11: Raises @ref{c0e,,TimeoutError} instead of @ref{1cb8,,asyncio.TimeoutError}.

@end deffn

@node Waiting primitives,Running in threads,Timeouts,Coroutines and tasks
@anchor{library/asyncio-task waiting-primitives}@anchor{3a26}
@subsubsection Waiting primitives


@geindex wait() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio wait}@anchor{891}
@deffn {Συνάρτηση} async asyncio.wait (aws, *, timeout=None, return_when=ALL_COMPLETED)

Run @ref{f8b,,Future} and @ref{460,,Task} instances in the `aws'
iterable concurrently and block until the condition specified
by `return_when'.

The `aws' iterable must not be empty.

Returns two sets of Tasks/Futures: @code{(done, pending)}.

Usage:

@example
done, pending = await asyncio.wait(aws)
@end example

`timeout' (a float or int), if specified, can be used to control
the maximum number of seconds to wait before returning.

Note that this function does not raise @ref{c0e,,TimeoutError}.
Futures or Tasks that aren’t done when the timeout occurs are simply
returned in the second set.

`return_when' indicates when this function should return.  It must
be one of the following constants:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constant

@tab

Description

@item

@geindex FIRST_COMPLETED (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio FIRST_COMPLETED}@anchor{3a27}
@deffn {Δεδομένα} asyncio.FIRST_COMPLETED
@end deffn

@tab

The function will return when any future finishes or is cancelled.

@item

@geindex FIRST_EXCEPTION (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio FIRST_EXCEPTION}@anchor{3a28}
@deffn {Δεδομένα} 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{3a29,,ALL_COMPLETED}.

@item

@geindex ALL_COMPLETED (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio ALL_COMPLETED}@anchor{3a29}
@deffn {Δεδομένα} asyncio.ALL_COMPLETED
@end deffn

@tab

The function will return when all futures finish or are cancelled.

@end multitable


Unlike @ref{9f6,,wait_for()}, @code{wait()} does not cancel the
futures when a timeout occurs.


Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.



Άλλαξε στην έκδοση 3.11: Passing coroutine objects to @code{wait()} directly is forbidden.



Άλλαξε στην έκδοση 3.12: Added support for generators yielding tasks.

@end deffn

@geindex as_completed() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio as_completed}@anchor{6cc}
@deffn {Συνάρτηση} asyncio.as_completed (aws, *, timeout=None)

Run @ref{3a14,,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{6cd,,asynchronous iterator} or a plain @ref{6ce,,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{c0e,,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.


Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.



Αποσύρθηκε στην έκδοση 3.10: Deprecation warning is emitted if not all awaitable objects in the `aws'
iterable are Future-like objects and there is no running event loop.



Άλλαξε στην έκδοση 3.12: Added support for generators yielding tasks.



Άλλαξε στην έκδοση 3.13: The result can now be used as either an @ref{6cd,,asynchronous iterator}
or as a plain @ref{6ce,,iterator} (previously it was only a plain iterator).

@end deffn

@node Running in threads,Scheduling from other threads,Waiting primitives,Coroutines and tasks
@anchor{library/asyncio-task running-in-threads}@anchor{3a2a}
@subsubsection Running in threads


@geindex to_thread() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio to_thread}@anchor{cb9}
@deffn {Συνάρτηση} async asyncio.to_thread (func, /, *args, **kwargs)

Asynchronously run function `func' in a separate thread.

Any *args and **kwargs supplied for this function are directly passed
to `func'. Also, the current @ref{421,,contextvars.Context} is propagated,
allowing context variables from the event loop thread to be accessed in the
separate thread.

Return a coroutine that can be awaited to get the eventual result of `func'.

This coroutine function is primarily intended to be used for executing
IO-bound functions/methods that would otherwise block the event loop if
they were run in the main thread. For example:

@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

Directly calling @code{blocking_io()} in any coroutine would block the event loop
for its duration, resulting in an additional 1 second of run time. Instead,
by using @code{asyncio.to_thread()}, we can run it in a separate thread without
blocking the event loop.

@cartouche
@quotation Σημείωση 
Due to the @ref{411,,GIL}, @code{asyncio.to_thread()} can typically only be used
to make IO-bound functions non-blocking. However, for extension modules
that release the GIL or alternative Python implementations that don’t
have one, @code{asyncio.to_thread()} can also be used for CPU-bound functions.
@end quotation
@end cartouche


Added in version 3.9.

@end deffn

@node Scheduling from other threads,Introspection,Running in threads,Coroutines and tasks
@anchor{library/asyncio-task scheduling-from-other-threads}@anchor{3a2b}
@subsubsection Scheduling from other threads


@geindex run_coroutine_threadsafe() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio run_coroutine_threadsafe}@anchor{c58}
@deffn {Συνάρτηση} asyncio.run_coroutine_threadsafe (coro, loop)

Submit a coroutine to the given event loop.  Thread-safe.

Return a @ref{155b,,concurrent.futures.Future} to wait for the result
from another OS thread.

This function is meant to be called from a different OS thread
than the one where the event loop is running.  Example:

@example
def in_thread(loop: asyncio.AbstractEventLoop) -> None:
    # Run some blocking IO
    pathlib.Path("example.txt").write_text("hello world", encoding="utf8")

    # 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=2) == 3

async def amain() -> None:
    # Get the running loop
    loop = asyncio.get_running_loop()

    # Run something in a thread
    await asyncio.to_thread(in_thread, loop)
@end example

It’s also possible to run the other way around.  Example:

@example
@@contextlib.contextmanager
def loop_in_thread() -> Generator[asyncio.AbstractEventLoop]:
    loop_fut = concurrent.futures.Future[asyncio.AbstractEventLoop]()
    stop_event = asyncio.Event()

    async def main() -> None:
        loop_fut.set_result(asyncio.get_running_loop())
        await stop_event.wait()

    with concurrent.futures.ThreadPoolExecutor(1) as tpe:
        complete_fut = tpe.submit(asyncio.run, main())
        for fut in concurrent.futures.as_completed((loop_fut, complete_fut)):
            if fut is loop_fut:
                loop = loop_fut.result()
                try:
                    yield loop
                finally:
                    loop.call_soon_threadsafe(stop_event.set)
            else:
                fut.result()

# Create a loop in another thread
with loop_in_thread() as loop:
    # 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=2) == 3
@end example

If an exception is raised in the coroutine, the returned Future
will be notified.  It can also be used to cancel the task in
the event loop:

@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

See the @ref{3a2c,,concurrency and multithreading}
section of the documentation.

Unlike other asyncio functions this function requires the `loop'
argument to be passed explicitly.


Added in version 3.5.1.

@end deffn

@node Introspection,Task object,Scheduling from other threads,Coroutines and tasks
@anchor{library/asyncio-task introspection}@anchor{3a2d}
@subsubsection Introspection


@geindex current_task() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio current_task}@anchor{88f}
@deffn {Συνάρτηση} asyncio.current_task (loop=None)

Return the currently running @ref{460,,Task} instance, or @code{None} if
no task is running.

If `loop' is @code{None} @ref{ecf,,get_running_loop()} is used to get
the current loop.


Added in version 3.7.

@end deffn

@geindex all_tasks() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio all_tasks}@anchor{d20}
@deffn {Συνάρτηση} asyncio.all_tasks (loop=None)

Return a set of not yet finished @ref{460,,Task} objects run by
the loop.

If `loop' is @code{None}, @ref{ecf,,get_running_loop()} is used for getting
current loop.


Added in version 3.7.

@end deffn

@geindex iscoroutine() (στη μονάδα asyncio)
@anchor{library/asyncio-task asyncio iscoroutine}@anchor{890}
@deffn {Συνάρτηση} asyncio.iscoroutine (obj)

Return @code{True} if `obj' is a coroutine object.


Added in version 3.4.

@end deffn

@node Task object,,Introspection,Coroutines and tasks
@anchor{library/asyncio-task asyncio-task-obj}@anchor{3a2e}@anchor{library/asyncio-task task-object}@anchor{3a2f}
@subsubsection Task object


@geindex Task (κλάση σε asyncio)
@anchor{library/asyncio-task asyncio Task}@anchor{460}
@deffn {Κλάση} asyncio.Task (coro, *, loop=None, name=None, context=None, eager_start=False)

A @ref{f8b,,Future-like} object that runs a Python
@ref{39fe,,coroutine}.  Not thread-safe.

Tasks are used to run coroutines in event loops.
If a coroutine awaits on a Future, the Task suspends
the execution of the coroutine and waits for the completion
of the Future.  When the Future is `done', the execution of
the wrapped coroutine resumes.

Event loops use cooperative scheduling: an event loop runs
one Task at a time.  While a Task awaits for the completion of a
Future, the event loop runs other Tasks, callbacks, or performs
IO operations.

Use the high-level @ref{462,,asyncio.create_task()} function to create
Tasks, or the low-level @ref{463,,loop.create_task()} or
@ref{1035,,ensure_future()} functions.  Manual instantiation of Tasks
is discouraged.

To cancel a running Task use the @ref{6d9,,cancel()} method.  Calling it
will cause the Task to throw a @ref{6da,,CancelledError} exception into
the wrapped coroutine.  If a coroutine is awaiting on a future-like
object during cancellation, the awaited object will be cancelled.

@ref{3a30,,cancelled()} can be used to check if the Task was cancelled.
The method returns @code{True} if the wrapped coroutine did not
suppress the @ref{6da,,CancelledError} exception and was actually
cancelled.

@ref{460,,asyncio.Task} inherits from @ref{f8b,,Future} all of its
APIs except @ref{3a31,,Future.set_result()} and
@ref{103c,,Future.set_exception()}.

An optional keyword-only `context' argument allows specifying a
custom @ref{421,,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{460,,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.


Άλλαξε στην έκδοση 3.7: Added support for the @ref{28,,contextvars} module.



Άλλαξε στην έκδοση 3.8: Added the `name' parameter.



Αποσύρθηκε στην έκδοση 3.10: Deprecation warning is emitted if `loop' is not specified
and there is no running event loop.



Άλλαξε στην έκδοση 3.11: Added the `context' parameter.



Άλλαξε στην έκδοση 3.12: Added the `eager_start' parameter.


@geindex done() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task done}@anchor{3a32}
@deffn {Μέθοδος} done ()

Return @code{True} if the Task is `done'.

A Task is `done' when the wrapped coroutine either returned
a value, raised an exception, or the Task was cancelled.
@end deffn

@geindex result() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task result}@anchor{3a33}
@deffn {Μέθοδος} result ()

Return the result of the Task.

If the Task is `done', the result of the wrapped coroutine
is returned (or if the coroutine raised an exception, that
exception is re-raised.)

If the Task has been `cancelled', this method raises
a @ref{6da,,CancelledError} exception.

If the Task’s result isn’t yet available, this method raises
an @ref{3a34,,InvalidStateError} exception.
@end deffn

@geindex exception() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task exception}@anchor{3a35}
@deffn {Μέθοδος} exception ()

Return the exception of the Task.

If the wrapped coroutine raised an exception that exception
is returned.  If the wrapped coroutine returned normally
this method returns @code{None}.

If the Task has been `cancelled', this method raises a
@ref{6da,,CancelledError} exception.

If the Task isn’t `done' yet, this method raises an
@ref{3a34,,InvalidStateError} exception.
@end deffn

@geindex add_done_callback() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task add_done_callback}@anchor{3a36}
@deffn {Μέθοδος} add_done_callback (callback, *, context=None)

Add a callback to be run when the Task is `done'.

This method should only be used in low-level callback-based code.

See the documentation of @ref{ecc,,Future.add_done_callback()}
for more details.
@end deffn

@geindex remove_done_callback() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task remove_done_callback}@anchor{3a37}
@deffn {Μέθοδος} remove_done_callback (callback)

Remove `callback' from the callbacks list.

This method should only be used in low-level callback-based code.

See the documentation of @ref{1b2c,,Future.remove_done_callback()}
for more details.
@end deffn

@geindex get_stack() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task get_stack}@anchor{3a38}
@deffn {Μέθοδος} get_stack (*, limit=None)

Return the list of stack frames for this Task.

If the wrapped coroutine is not done, this returns the stack
where it is suspended.  If the coroutine has completed
successfully or was cancelled, this returns an empty list.
If the coroutine was terminated by an exception, this returns
the list of traceback frames.

The frames are always ordered from oldest to newest.

Only one stack frame is returned for a suspended coroutine.

The optional `limit' argument sets the maximum number of frames
to return; by default all available frames are returned.
The ordering of the returned list differs depending on whether
a stack or a traceback is returned: the newest frames of a
stack are returned, but the oldest frames of a traceback are
returned.  (This matches the behavior of the traceback module.)
@end deffn

@geindex print_stack() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task print_stack}@anchor{1ccf}
@deffn {Μέθοδος} print_stack (*, limit=None, file=None)

Print the stack or traceback for this Task.

This produces output similar to that of the traceback module
for the frames retrieved by @ref{3a38,,get_stack()}.

The `limit' argument is passed to @ref{3a38,,get_stack()} directly.

The `file' argument is an I/O stream to which the output
is written; by default output is written to @ref{e9c,,sys.stdout}.
@end deffn

@geindex get_coro() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task get_coro}@anchor{da0}
@deffn {Μέθοδος} get_coro ()

Return the coroutine object wrapped by the @code{Task}.

@cartouche
@quotation Σημείωση 
This will return @code{None} for Tasks which have already
completed eagerly. See the @ref{3a1e,,Eager Task Factory}.
@end quotation
@end cartouche


Added in version 3.8.



Άλλαξε στην έκδοση 3.12: Newly added eager task execution means result may be @code{None}.

@end deffn

@geindex get_context() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task get_context}@anchor{3a39}
@deffn {Μέθοδος} get_context ()

Return the @ref{421,,contextvars.Context} object
associated with the task.


Added in version 3.12.

@end deffn

@geindex get_name() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task get_name}@anchor{da2}
@deffn {Μέθοδος} get_name ()

Return the name of the Task.

If no name has been explicitly assigned to the Task, the default
asyncio Task implementation generates a default name during
instantiation.


Added in version 3.8.

@end deffn

@geindex set_name() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task set_name}@anchor{da1}
@deffn {Μέθοδος} set_name (value)

Set the name of the Task.

The `value' argument can be any object, which is then
converted to a string.

In the default Task implementation, the name will be visible
in the @ref{45b,,repr()} output of a task object.


Added in version 3.8.

@end deffn

@geindex cancel() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task cancel}@anchor{6d9}
@deffn {Μέθοδος} cancel (msg=None)

Request the Task to be cancelled.

If the Task is already `done' or `cancelled', return @code{False},
otherwise, return @code{True}.

The method arranges for a @ref{6da,,CancelledError} exception to be thrown
into the wrapped coroutine on the next cycle of the event loop.

The coroutine then has a chance to clean up or even deny the
request by suppressing the exception with a @ref{ad6,,try} …
… @code{except CancelledError} … @ref{44c,,finally} block.
Therefore, unlike @ref{1da3,,Future.cancel()}, @code{Task.cancel()} does
not guarantee that the Task will be cancelled, although
suppressing cancellation completely is not common and is actively
discouraged.  Should the coroutine nevertheless decide to suppress
the cancellation, it needs to call @ref{6dc,,Task.uncancel()} in addition
to catching the exception.

If the Task being cancelled is currently awaiting on a future-like
object, that awaited object will also be cancelled. This cancellation
propagates down the entire chain of awaited objects.


Άλλαξε στην έκδοση 3.9: Added the `msg' parameter.



Άλλαξε στην έκδοση 3.11: The @code{msg} parameter is propagated from cancelled task to its awaiter.

@anchor{library/asyncio-task asyncio-example-task-cancel}@anchor{3a3a}
The following example illustrates how coroutines can intercept
the cancellation request:

@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() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task cancelled}@anchor{3a30}
@deffn {Μέθοδος} cancelled ()

Return @code{True} if the Task is `cancelled'.

The Task is `cancelled' when the cancellation was requested with
@ref{6d9,,cancel()} and the wrapped coroutine propagated the
@ref{6da,,CancelledError} exception thrown into it.
@end deffn

@geindex uncancel() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task uncancel}@anchor{6dc}
@deffn {Μέθοδος} uncancel ()

Decrement the count of cancellation requests to this Task.

Returns the remaining number of cancellation requests.

Note that once execution of a cancelled task completed, further
calls to @code{uncancel()} are ineffective.


Added in version 3.11.


This method is used by asyncio’s internals and isn’t expected to be
used by end-user code.  In particular, if a Task gets successfully
uncancelled, this allows for elements of structured concurrency like
@ref{3a19,,Task groups} and @ref{9f5,,asyncio.timeout()} to continue running,
isolating cancellation to the respective structured block.
For example:

@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

While the block with @code{make_request()} and @code{make_another_request()}
might get cancelled due to the timeout, @code{unrelated_code()} should
continue running even in case of the timeout.  This is implemented
with @code{uncancel()}.  @ref{6d7,,TaskGroup} context managers use
@ref{6dc,,uncancel()} in a similar fashion.

If end-user code is, for some reason, suppressing cancellation by
catching @ref{6da,,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{6d9,,cancel()} call had arranged
for @ref{6da,,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


Άλλαξε στην έκδοση 3.13: Changed to rescind pending cancellation requests upon reaching zero.


@geindex cancelling() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-task asyncio Task cancelling}@anchor{6db}
@deffn {Μέθοδος} cancelling ()

Return the number of pending cancellation requests to this Task, i.e.,
the number of calls to @ref{6d9,,cancel()} less the number of
@ref{6dc,,uncancel()} calls.

Note that if this number is greater than zero but the Task is
still executing, @ref{3a30,,cancelled()} will still return @code{False}.
This is because this number can be lowered by calling @ref{6dc,,uncancel()},
which can lead to the task not being cancelled after all if the
cancellation requests go down to zero.

This method is used by asyncio’s internals and isn’t expected to be
used by end-user code.  See @ref{6dc,,uncancel()} for more details.


Added in version 3.11.

@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Streams,Synchronization Primitives,Coroutines and tasks,asyncio — Asynchronous I/O
@anchor{library/asyncio-stream doc}@anchor{3a3b}@anchor{library/asyncio-stream asyncio-streams}@anchor{19b0}@anchor{library/asyncio-stream streams}@anchor{3a3c}@anchor{library/asyncio-stream translation-repo}@anchor{3a3d}
@subsubsection Streams


`Source code:' Lib/asyncio/streams.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/streams.py}


__________________________________________________________________


Streams are high-level async/await-ready primitives to work with
network connections.  Streams allow sending and receiving data without
using callbacks or low-level protocols and transports.
@anchor{library/asyncio-stream asyncio-example-stream}@anchor{3a3e}
Here is an example of a TCP echo client written using asyncio
streams:

@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

See also the @ref{3a3f,,Examples} section below.

@subsubheading Stream Functions


The following top-level asyncio functions can be used to create
and work with streams:

@geindex open_connection() (στη μονάδα asyncio)
@anchor{library/asyncio-stream asyncio open_connection}@anchor{edc}
@deffn {Συνάρτηση} async 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)

Establish a network connection and return a pair of
@code{(reader, writer)} objects.

The returned `reader' and `writer' objects are instances of
@ref{194a,,StreamReader} and @ref{1c76,,StreamWriter} classes.

`limit' determines the buffer size limit used by the
returned @ref{194a,,StreamReader} instance.  By default the `limit'
is set to 64 KiB.

The rest of the arguments are passed directly to
@ref{9f9,,loop.create_connection()}.

@cartouche
@quotation Σημείωση 
The `sock' argument transfers ownership of the socket to the
@ref{1c76,,StreamWriter} created. To close the socket, call its
@ref{3a40,,close()} method.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.7: Added the `ssl_handshake_timeout' parameter.



Άλλαξε στην έκδοση 3.8: Added the `happy_eyeballs_delay' and `interleave' parameters.



Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.



Άλλαξε στην έκδοση 3.11: Added the `ssl_shutdown_timeout' parameter.

@end deffn

@geindex start_server() (στη μονάδα asyncio)
@anchor{library/asyncio-stream asyncio start_server}@anchor{edd}
@deffn {Συνάρτηση} async 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)

Start a socket server.

The `client_connected_cb' callback is called whenever a new client
connection is established.  It receives a @code{(reader, writer)} pair
as two arguments, instances of the @ref{194a,,StreamReader} and
@ref{1c76,,StreamWriter} classes.

`client_connected_cb' can be a plain callable or a
@ref{39fe,,coroutine function}; if it is a coroutine function,
it will be automatically scheduled as a @ref{460,,Task}.

`limit' determines the buffer size limit used by the
returned @ref{194a,,StreamReader} instance.  By default the `limit'
is set to 64 KiB.

The rest of the arguments are passed directly to
@ref{ed7,,loop.create_server()}.

@cartouche
@quotation Σημείωση 
The `sock' argument transfers ownership of the socket to the
server created. To close the socket, call the server’s
@ref{3a41,,close()} method.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.7: Added the `ssl_handshake_timeout' and `start_serving' parameters.



Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.



Άλλαξε στην έκδοση 3.11: Added the `ssl_shutdown_timeout' parameter.



Άλλαξε στην έκδοση 3.13: Added the `keep_alive' parameter.

@end deffn

@subsubheading Unix Sockets


@geindex open_unix_connection() (στη μονάδα asyncio)
@anchor{library/asyncio-stream asyncio open_unix_connection}@anchor{3a42}
@deffn {Συνάρτηση} async asyncio.open_unix_connection (path=None, *, limit=None, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Establish a Unix socket connection and return a pair of
@code{(reader, writer)}.

Similar to @ref{edc,,open_connection()} but operates on Unix sockets.

See also the documentation of @ref{3a43,,loop.create_unix_connection()}.

@cartouche
@quotation Σημείωση 
The `sock' argument transfers ownership of the socket to the
@ref{1c76,,StreamWriter} created. To close the socket, call its
@ref{3a40,,close()} method.
@end quotation
@end cartouche

@ref{232d,,Διαθεσιμότητα}: Unix.


Άλλαξε στην έκδοση 3.7: Added the `ssl_handshake_timeout' parameter.
The `path' parameter can now be a @ref{79f,,path-like object}



Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.



Άλλαξε στην έκδοση 3.11: Added the `ssl_shutdown_timeout' parameter.

@end deffn

@geindex start_unix_server() (στη μονάδα asyncio)
@anchor{library/asyncio-stream asyncio start_unix_server}@anchor{3a44}
@deffn {Συνάρτηση} async 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, cleanup_socket=True)

Start a Unix socket server.

Similar to @ref{edd,,start_server()} but works with Unix sockets.

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.

See also the documentation of @ref{6d0,,loop.create_unix_server()}.

@cartouche
@quotation Σημείωση 
The `sock' argument transfers ownership of the socket to the
server created. To close the socket, call the server’s
@ref{3a41,,close()} method.
@end quotation
@end cartouche

@ref{232d,,Διαθεσιμότητα}: Unix.


Άλλαξε στην έκδοση 3.7: Added the `ssl_handshake_timeout' and `start_serving' parameters.
The `path' parameter can now be a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.



Άλλαξε στην έκδοση 3.11: Added the `ssl_shutdown_timeout' parameter.



Άλλαξε στην έκδοση 3.13: Added the `cleanup_socket' parameter.

@end deffn

@menu
* StreamReader:: 
* StreamWriter:: 
* Examples: Examples<13>. 

@end menu

@node StreamReader,StreamWriter,,Streams
@anchor{library/asyncio-stream streamreader}@anchor{3a45}
@subsubsection StreamReader


@geindex StreamReader (κλάση σε asyncio)
@anchor{library/asyncio-stream asyncio StreamReader}@anchor{194a}
@deffn {Κλάση} asyncio.StreamReader

Represents a reader object that provides APIs to read data
from the IO stream. As an @ref{112d,,asynchronous iterable}, the
object supports the @ref{e70,,async for} statement.

It is not recommended to instantiate `StreamReader' objects
directly; use @ref{edc,,open_connection()} and @ref{edd,,start_server()}
instead.

@geindex feed_eof() (μέθοδος της asyncio.StreamReader)
@anchor{library/asyncio-stream asyncio StreamReader feed_eof}@anchor{3a46}
@deffn {Μέθοδος} feed_eof ()

Acknowledge the EOF.
@end deffn

@geindex read() (μέθοδος της asyncio.StreamReader)
@anchor{library/asyncio-stream asyncio StreamReader read}@anchor{3a47}
@deffn {Μέθοδος} async read (n=-1)

Read up to `n' bytes from the stream.

If `n' is not provided or set to @code{-1},
read until EOF, then return all read @ref{1c7,,bytes}.
If EOF was received and the internal buffer is empty,
return an empty @code{bytes} object.

If `n' is @code{0}, return an empty @code{bytes} object immediately.

If `n' is positive, return at most `n' available @code{bytes}
as soon as at least 1 byte is available in the internal buffer.
If EOF is received before any byte is read, return an empty
@code{bytes} object.
@end deffn

@geindex readline() (μέθοδος της asyncio.StreamReader)
@anchor{library/asyncio-stream asyncio StreamReader readline}@anchor{3a48}
@deffn {Μέθοδος} async readline ()

Read one line, where «line» is a sequence of bytes
ending with @code{\n}.

If EOF is received and @code{\n} was not found, the method
returns partially read data.

If EOF is received and the internal buffer is empty,
return an empty @code{bytes} object.
@end deffn

@geindex readexactly() (μέθοδος της asyncio.StreamReader)
@anchor{library/asyncio-stream asyncio StreamReader readexactly}@anchor{103a}
@deffn {Μέθοδος} async readexactly (n)

Read exactly `n' bytes.

Raise an @ref{1edd,,IncompleteReadError} if EOF is reached before `n'
can be read.  Use the @ref{3a49,,IncompleteReadError.partial}
attribute to get the partially read data.
@end deffn

@geindex readuntil() (μέθοδος της asyncio.StreamReader)
@anchor{library/asyncio-stream asyncio StreamReader readuntil}@anchor{6d6}
@deffn {Μέθοδος} async readuntil (separator=b'\n')

Read data from the stream until `separator' is found.

On success, the data and separator will be removed from the
internal buffer (consumed). Returned data will include the
separator at the end.

If the amount of data read exceeds the configured stream limit, a
@ref{3a4a,,LimitOverrunError} exception is raised, and the data
is left in the internal buffer and can be read again.

If EOF is reached before the complete separator is found,
an @ref{1edd,,IncompleteReadError} exception is raised, and the internal
buffer is reset.  The @ref{3a49,,IncompleteReadError.partial} attribute
may contain a portion of the separator.

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{3a4a,,LimitOverrunError},
the shortest possible separator is considered to be the one that
matched.


Added in version 3.5.2.



Άλλαξε στην έκδοση 3.13: The `separator' parameter may now be a @ref{1ce,,tuple} of
separators.

@end deffn

@geindex at_eof() (μέθοδος της asyncio.StreamReader)
@anchor{library/asyncio-stream asyncio StreamReader at_eof}@anchor{3a4b}
@deffn {Μέθοδος} at_eof ()

Return @code{True} if the buffer is empty and @ref{3a46,,feed_eof()}
was called.
@end deffn
@end deffn

@node StreamWriter,Examples<13>,StreamReader,Streams
@anchor{library/asyncio-stream streamwriter}@anchor{3a4c}
@subsubsection StreamWriter


@geindex StreamWriter (κλάση σε asyncio)
@anchor{library/asyncio-stream asyncio StreamWriter}@anchor{1c76}
@deffn {Κλάση} asyncio.StreamWriter

Represents a writer object that provides APIs to write data
to the IO stream.

It is not recommended to instantiate `StreamWriter' objects
directly; use @ref{edc,,open_connection()} and @ref{edd,,start_server()}
instead.

@geindex write() (μέθοδος της asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter write}@anchor{3a4d}
@deffn {Μέθοδος} write (data)

The method attempts to write the `data' to the underlying socket immediately.
If that fails, the data is queued in an internal write buffer until it can be
sent.

The `data' buffer should be a bytes, bytearray, or C-contiguous one-dimensional
memoryview object.

The method should be used along with the @code{drain()} method:

@example
stream.write(data)
await stream.drain()
@end example
@end deffn

@geindex writelines() (μέθοδος της asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter writelines}@anchor{3a4e}
@deffn {Μέθοδος} writelines (data)

The method writes a list (or any iterable) of bytes to the underlying socket
immediately.
If that fails, the data is queued in an internal write buffer until it can be
sent.

The method should be used along with the @code{drain()} method:

@example
stream.writelines(lines)
await stream.drain()
@end example
@end deffn

@geindex close() (μέθοδος της asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter close}@anchor{3a40}
@deffn {Μέθοδος} close ()

The method closes the stream and the underlying socket.

The method should be used, though not mandatory,
along with the @code{wait_closed()} method:

@example
stream.close()
await stream.wait_closed()
@end example
@end deffn

@geindex can_write_eof() (μέθοδος της asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter can_write_eof}@anchor{3a4f}
@deffn {Μέθοδος} can_write_eof ()

Return @code{True} if the underlying transport supports
the @ref{3a50,,write_eof()} method, @code{False} otherwise.
@end deffn

@geindex write_eof() (μέθοδος της asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter write_eof}@anchor{3a50}
@deffn {Μέθοδος} write_eof ()

Close the write end of the stream after the buffered write
data is flushed.
@end deffn

@geindex transport (ιδιότητα της asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter transport}@anchor{3a51}
@deffn {Ιδιότητα} transport

Return the underlying asyncio transport.
@end deffn

@geindex get_extra_info() (μέθοδος της asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter get_extra_info}@anchor{3a52}
@deffn {Μέθοδος} get_extra_info (name, default=None)

Access optional transport information; see
@ref{e62,,BaseTransport.get_extra_info()} for details.
@end deffn

@geindex drain() (μέθοδος της asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter drain}@anchor{1d27}
@deffn {Μέθοδος} async drain ()

Wait until it is appropriate to resume writing to the stream.
Example:

@example
writer.write(data)
await writer.drain()
@end example

This is a flow control method that interacts with the underlying
IO write buffer.  When the size of the buffer reaches
the high watermark, `drain()' blocks until the size of the
buffer is drained down to the low watermark and writing can
be resumed.  When there is nothing to wait for, the @code{drain()}
returns immediately.
@end deffn

@geindex start_tls() (μέθοδος της asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter start_tls}@anchor{9fa}
@deffn {Μέθοδος} async start_tls (sslcontext, *, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Upgrade an existing stream-based connection to TLS.

Parameters:


@itemize *

@item 
`sslcontext': a configured instance of @ref{336,,SSLContext}.

@item 
`server_hostname': sets or overrides the host name that the target
server’s certificate will be matched against.

@item 
`ssl_handshake_timeout' is the time in seconds to wait for the TLS
handshake to complete before aborting the connection.  @code{60.0} seconds
if @code{None} (default).

@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


Added in version 3.11.



Άλλαξε στην έκδοση 3.12: Added the `ssl_shutdown_timeout' parameter.

@end deffn

@geindex is_closing() (μέθοδος της asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter is_closing}@anchor{ed1}
@deffn {Μέθοδος} is_closing ()

Return @code{True} if the stream is closed or in the process of
being closed.


Added in version 3.7.

@end deffn

@geindex wait_closed() (μέθοδος της asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter wait_closed}@anchor{ed0}
@deffn {Μέθοδος} async wait_closed ()

Wait until the stream is closed.

Should be called after @ref{3a40,,close()} to wait until the underlying
connection is closed, ensuring that all data has been flushed
before e.g. exiting the program.


Added in version 3.7.

@end deffn
@end deffn

@node Examples<13>,,StreamWriter,Streams
@anchor{library/asyncio-stream examples}@anchor{3a3f}
@subsubsection Examples


@menu
* TCP echo client using streams:: 
* TCP echo server using streams:: 
* Get HTTP headers:: 
* Register an open socket to wait for data using streams:: 

@end menu

@node TCP echo client using streams,TCP echo server using streams,,Examples<13>
@anchor{library/asyncio-stream asyncio-tcp-echo-client-streams}@anchor{3a53}@anchor{library/asyncio-stream tcp-echo-client-using-streams}@anchor{3a54}
@subsubsection TCP echo client using streams


TCP echo client using the @ref{edc,,asyncio.open_connection()} function:

@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 Δείτε επίσης


The @ref{3a55,,TCP echo client protocol}
example uses the low-level @ref{9f9,,loop.create_connection()} method.


@node TCP echo server using streams,Get HTTP headers,TCP echo client using streams,Examples<13>
@anchor{library/asyncio-stream asyncio-tcp-echo-server-streams}@anchor{3a56}@anchor{library/asyncio-stream tcp-echo-server-using-streams}@anchor{3a57}
@subsubsection TCP echo server using streams


TCP echo server using the @ref{edd,,asyncio.start_server()} function:

@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 Δείτε επίσης


The @ref{3a58,,TCP echo server protocol}
example uses the @ref{ed7,,loop.create_server()} method.


@node Get HTTP headers,Register an open socket to wait for data using streams,TCP echo server using streams,Examples<13>
@anchor{library/asyncio-stream get-http-headers}@anchor{3a59}
@subsubsection Get HTTP headers


Simple example querying HTTP headers of the URL passed on the command line:

@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

Usage:

@example
python example.py http://example.com/path/page.html
@end example

or with HTTPS:

@example
python example.py https://example.com/path/page.html
@end example

@node Register an open socket to wait for data using streams,,Get HTTP headers,Examples<13>
@anchor{library/asyncio-stream asyncio-example-create-connection-streams}@anchor{3a5a}@anchor{library/asyncio-stream register-an-open-socket-to-wait-for-data-using-streams}@anchor{3a5b}
@subsubsection Register an open socket to wait for data using streams


Coroutine waiting until a socket receives data using the
@ref{edc,,open_connection()} function:

@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 Δείτε επίσης


The @ref{3a5c,,register an open socket to wait for data using a protocol} example uses a low-level protocol and
the @ref{9f9,,loop.create_connection()} method.

The @ref{3a5d,,watch a file descriptor for read events} example uses the low-level
@ref{3a5e,,loop.add_reader()} method to watch a file descriptor.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Synchronization Primitives,Subprocesses,Streams,asyncio — Asynchronous I/O
@anchor{library/asyncio-sync doc}@anchor{3a5f}@anchor{library/asyncio-sync asyncio-sync}@anchor{3a01}@anchor{library/asyncio-sync synchronization-primitives}@anchor{3a60}@anchor{library/asyncio-sync translation-repo}@anchor{3a61}
@subsubsection Synchronization Primitives


`Source code:' Lib/asyncio/locks.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/locks.py}


__________________________________________________________________


asyncio synchronization primitives are designed to be similar to
those of the @ref{f6,,threading} module with two important caveats:


@itemize *

@item 
asyncio primitives are not thread-safe, therefore they should not
be used for OS thread synchronization (use @ref{f6,,threading} for
that);

@item 
methods of these synchronization primitives do not accept the `timeout'
argument; use the @ref{9f6,,asyncio.wait_for()} function to perform
operations with timeouts.
@end itemize

asyncio has the following basic synchronization primitives:


@itemize *

@item 
@ref{e35,,Lock}

@item 
@ref{56d,,Event}

@item 
@ref{e36,,Condition}

@item 
@ref{e37,,Semaphore}

@item 
@ref{e38,,BoundedSemaphore}

@item 
@ref{9f7,,Barrier}
@end itemize


__________________________________________________________________


@menu
* Lock:: 
* Event:: 
* Condition:: 
* Semaphore:: 
* BoundedSemaphore:: 
* Barrier:: 

@end menu

@node Lock,Event,,Synchronization Primitives
@anchor{library/asyncio-sync lock}@anchor{3a62}
@subsubsection Lock


@geindex Lock (κλάση σε asyncio)
@anchor{library/asyncio-sync asyncio Lock}@anchor{e35}
@deffn {Κλάση} asyncio.Lock

Implements a mutex lock for asyncio tasks.  Not thread-safe.

An asyncio lock can be used to guarantee exclusive access to a
shared resource.

The preferred way to use a Lock is an @ref{20b,,async with}
statement:

@example
lock = asyncio.Lock()

# ... later
async with lock:
    # access shared state
@end example

which is equivalent to:

@example
lock = asyncio.Lock()

# ... later
await lock.acquire()
try:
    # access shared state
finally:
    lock.release()
@end example


Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.


@geindex acquire() (μέθοδος της asyncio.Lock)
@anchor{library/asyncio-sync asyncio Lock acquire}@anchor{3a63}
@deffn {Μέθοδος} async acquire ()

Acquire the lock.

This method waits until the lock is `unlocked', sets it to
`locked' and returns @code{True}.

When more than one coroutine is blocked in @code{acquire()}
waiting for the lock to be unlocked, only one coroutine
eventually proceeds.

Acquiring a lock is `fair': the coroutine that proceeds will be
the first coroutine that started waiting on the lock.
@end deffn

@geindex release() (μέθοδος της asyncio.Lock)
@anchor{library/asyncio-sync asyncio Lock release}@anchor{3a64}
@deffn {Μέθοδος} release ()

Release the lock.

When the lock is `locked', reset it to `unlocked' and return.

If the lock is `unlocked', a @ref{30d,,RuntimeError} is raised.
@end deffn

@geindex locked() (μέθοδος της asyncio.Lock)
@anchor{library/asyncio-sync asyncio Lock locked}@anchor{3a65}
@deffn {Μέθοδος} locked ()

Return @code{True} if the lock is `locked'.
@end deffn
@end deffn

@node Event,Condition,Lock,Synchronization Primitives
@anchor{library/asyncio-sync event}@anchor{3a66}
@subsubsection Event


@geindex Event (κλάση σε asyncio)
@anchor{library/asyncio-sync asyncio Event}@anchor{56d}
@deffn {Κλάση} asyncio.Event

An event object.  Not thread-safe.

An asyncio event can be used to notify multiple asyncio tasks
that some event has happened.

An Event object manages an internal flag that can be set to `true'
with the @ref{3a67,,set()} method and reset to `false' with the
@ref{3a68,,clear()} method.  The @ref{3a69,,wait()} method blocks until the
flag is set to `true'.  The flag is set to `false' initially.


Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.

@anchor{library/asyncio-sync asyncio-example-sync-event}@anchor{3a6a}
Example:

@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() (μέθοδος της asyncio.Event)
@anchor{library/asyncio-sync asyncio Event wait}@anchor{3a69}
@deffn {Μέθοδος} async wait ()

Wait until the event is set.

If the event is set, return @code{True} immediately.
Otherwise block until another task calls @ref{3a67,,set()}.
@end deffn

@geindex set() (μέθοδος της asyncio.Event)
@anchor{library/asyncio-sync asyncio Event set}@anchor{3a67}
@deffn {Μέθοδος} set ()

Set the event.

All tasks waiting for event to be set will be immediately
awakened.
@end deffn

@geindex clear() (μέθοδος της asyncio.Event)
@anchor{library/asyncio-sync asyncio Event clear}@anchor{3a68}
@deffn {Μέθοδος} clear ()

Clear (unset) the event.

Subsequent tasks awaiting on @ref{3a69,,wait()} will now block until the
@ref{3a67,,set()} method is called again.
@end deffn

@geindex is_set() (μέθοδος της asyncio.Event)
@anchor{library/asyncio-sync asyncio Event is_set}@anchor{3a6b}
@deffn {Μέθοδος} is_set ()

Return @code{True} if the event is set.
@end deffn
@end deffn

@node Condition,Semaphore,Event,Synchronization Primitives
@anchor{library/asyncio-sync condition}@anchor{3a6c}
@subsubsection Condition


@geindex Condition (κλάση σε asyncio)
@anchor{library/asyncio-sync asyncio Condition}@anchor{e36}
@deffn {Κλάση} asyncio.Condition (lock=None)

A Condition object.  Not thread-safe.

An asyncio condition primitive can be used by a task to wait for
some event to happen and then get exclusive access to a shared
resource.

In essence, a Condition object combines the functionality
of an @ref{56d,,Event} and a @ref{e35,,Lock}.  It is possible to have
multiple Condition objects share one Lock, which allows coordinating
exclusive access to a shared resource between different tasks
interested in particular states of that shared resource.

The optional `lock' argument must be a @ref{e35,,Lock} object or
@code{None}.  In the latter case a new Lock object is created
automatically.


Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.


The preferred way to use a Condition is an @ref{20b,,async with}
statement:

@example
cond = asyncio.Condition()

# ... later
async with cond:
    await cond.wait()
@end example

which is equivalent to:

@example
cond = asyncio.Condition()

# ... later
await cond.acquire()
try:
    await cond.wait()
finally:
    cond.release()
@end example

@geindex acquire() (μέθοδος της asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition acquire}@anchor{3a6d}
@deffn {Μέθοδος} async acquire ()

Acquire the underlying lock.

This method waits until the underlying lock is `unlocked',
sets it to `locked' and returns @code{True}.
@end deffn

@geindex notify() (μέθοδος της asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition notify}@anchor{1bff}
@deffn {Μέθοδος} 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.

The lock must be acquired before this method is called and
released shortly after.  If called with an `unlocked' lock
a @ref{30d,,RuntimeError} error is raised.
@end deffn

@geindex locked() (μέθοδος της asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition locked}@anchor{3a6e}
@deffn {Μέθοδος} locked ()

Return @code{True} if the underlying lock is acquired.
@end deffn

@geindex notify_all() (μέθοδος της asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition notify_all}@anchor{3a6f}
@deffn {Μέθοδος} notify_all ()

Wake up all tasks waiting on this condition.

This method acts like @ref{1bff,,notify()}, but wakes up all waiting
tasks.

The lock must be acquired before this method is called and
released shortly after.  If called with an `unlocked' lock
a @ref{30d,,RuntimeError} error is raised.
@end deffn

@geindex release() (μέθοδος της asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition release}@anchor{3a70}
@deffn {Μέθοδος} release ()

Release the underlying lock.

When invoked on an unlocked lock, a @ref{30d,,RuntimeError} is
raised.
@end deffn

@geindex wait() (μέθοδος της asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition wait}@anchor{1c28}
@deffn {Μέθοδος} async wait ()

Wait until notified.

If the calling task has not acquired the lock when this method is
called, a @ref{30d,,RuntimeError} is raised.

This method releases the underlying lock, and then blocks until
it is awakened by a @ref{1bff,,notify()} or @ref{3a6f,,notify_all()} call.
Once awakened, the Condition re-acquires its lock and this method
returns @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 @code{wait()} again. For this reason, you may
prefer to use @ref{3a71,,wait_for()} instead.
@end deffn

@geindex wait_for() (μέθοδος της asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition wait_for}@anchor{3a71}
@deffn {Μέθοδος} async wait_for (predicate)

Wait until a predicate becomes `true'.

The predicate must be a callable which result will be
interpreted as a boolean value.  The method will repeatedly
@ref{1c28,,wait()} until the predicate evaluates to `true'. The final value is the
return value.
@end deffn
@end deffn

@node Semaphore,BoundedSemaphore,Condition,Synchronization Primitives
@anchor{library/asyncio-sync semaphore}@anchor{3a72}
@subsubsection Semaphore


@geindex Semaphore (κλάση σε asyncio)
@anchor{library/asyncio-sync asyncio Semaphore}@anchor{e37}
@deffn {Κλάση} asyncio.Semaphore (value=1)

A Semaphore object.  Not thread-safe.

A semaphore manages an internal counter which is decremented by each
@ref{1c29,,acquire()} call and incremented by each @ref{3a73,,release()} call.
The counter can never go below zero; when @code{acquire()} finds
that it is zero, it blocks, waiting until some task calls
@code{release()}.

The optional `value' argument gives the initial value for the
internal counter (@code{1} by default). If the given value is
less than @code{0} a @ref{277,,ValueError} is raised.


Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.


The preferred way to use a Semaphore is an @ref{20b,,async with}
statement:

@example
sem = asyncio.Semaphore(10)

# ... later
async with sem:
    # work with shared resource
@end example

which is equivalent to:

@example
sem = asyncio.Semaphore(10)

# ... later
await sem.acquire()
try:
    # work with shared resource
finally:
    sem.release()
@end example

@geindex acquire() (μέθοδος της asyncio.Semaphore)
@anchor{library/asyncio-sync asyncio Semaphore acquire}@anchor{1c29}
@deffn {Μέθοδος} async acquire ()

Acquire a semaphore.

If the internal counter is greater than zero, decrement
it by one and return @code{True} immediately.  If it is zero, wait
until a @ref{3a73,,release()} is called and return @code{True}.
@end deffn

@geindex locked() (μέθοδος της asyncio.Semaphore)
@anchor{library/asyncio-sync asyncio Semaphore locked}@anchor{3a74}
@deffn {Μέθοδος} locked ()

Returns @code{True} if semaphore can not be acquired immediately.
@end deffn

@geindex release() (μέθοδος της asyncio.Semaphore)
@anchor{library/asyncio-sync asyncio Semaphore release}@anchor{3a73}
@deffn {Μέθοδος} release ()

Release a semaphore, incrementing the internal counter by one.
Can wake up a task waiting to acquire the semaphore.

Unlike @ref{e38,,BoundedSemaphore}, @code{Semaphore} allows
making more @code{release()} calls than @code{acquire()} calls.
@end deffn
@end deffn

@node BoundedSemaphore,Barrier,Semaphore,Synchronization Primitives
@anchor{library/asyncio-sync boundedsemaphore}@anchor{3a75}
@subsubsection BoundedSemaphore


@geindex BoundedSemaphore (κλάση σε asyncio)
@anchor{library/asyncio-sync asyncio BoundedSemaphore}@anchor{e38}
@deffn {Κλάση} asyncio.BoundedSemaphore (value=1)

A bounded semaphore object.  Not thread-safe.

Bounded Semaphore is a version of @ref{e37,,Semaphore} that raises
a @ref{277,,ValueError} in @ref{3a73,,release()} if it
increases the internal counter above the initial `value'.


Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.

@end deffn

@node Barrier,,BoundedSemaphore,Synchronization Primitives
@anchor{library/asyncio-sync barrier}@anchor{3a76}
@subsubsection Barrier


@geindex Barrier (κλάση σε asyncio)
@anchor{library/asyncio-sync asyncio Barrier}@anchor{9f7}
@deffn {Κλάση} asyncio.Barrier (parties)

A barrier object.  Not thread-safe.

A barrier is a simple synchronization primitive that allows to block until
`parties' number of tasks are waiting on it.
Tasks can wait on the @ref{3a77,,wait()} method and would be blocked until
the specified number of tasks end up waiting on @code{wait()}.
At that point all of the waiting tasks would unblock simultaneously.

@ref{20b,,async with} can be used as an alternative to awaiting on
@ref{3a77,,wait()}.

The barrier can be reused any number of times.
@anchor{library/asyncio-sync asyncio-example-barrier}@anchor{3a78}
Example:

@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

Result of this example is:

@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


Added in version 3.11.


@geindex wait() (μέθοδος της asyncio.Barrier)
@anchor{library/asyncio-sync asyncio Barrier wait}@anchor{3a77}
@deffn {Μέθοδος} async wait ()

Pass the barrier. When all the tasks party to the barrier have called
this function, they are all unblocked simultaneously.

When a waiting or blocked task in the barrier is cancelled,
this task exits the barrier which stays in the same state.
If the state of the barrier is «filling», the number of waiting task
decreases by 1.

The return value is an integer in the range of 0 to @code{parties-1}, different
for each task. This can be used to select a task to do some special
housekeeping, e.g.:

@example
...
async with barrier as position:
   if position == 0:
      # Only one task prints this
      print('End of *draining phase*')
@end example

This method may raise a @ref{9f8,,BrokenBarrierError} exception if the
barrier is broken or reset while a task is waiting.
It could raise a @ref{6da,,CancelledError} if a task is cancelled.
@end deffn

@geindex reset() (μέθοδος της asyncio.Barrier)
@anchor{library/asyncio-sync asyncio Barrier reset}@anchor{3a79}
@deffn {Μέθοδος} async reset ()

Return the barrier to the default, empty state.  Any tasks waiting on it
will receive the @ref{9f8,,BrokenBarrierError} exception.

If a barrier is broken it may be better to just leave it and create a new one.
@end deffn

@geindex abort() (μέθοδος της asyncio.Barrier)
@anchor{library/asyncio-sync asyncio Barrier abort}@anchor{3a7a}
@deffn {Μέθοδος} async abort ()

Put the barrier into a broken state.  This causes any active or future
calls to @ref{3a77,,wait()} to fail with the @ref{9f8,,BrokenBarrierError}.
Use this for example if one of the tasks needs to abort, to avoid infinite
waiting tasks.
@end deffn

@geindex parties (ιδιότητα της asyncio.Barrier)
@anchor{library/asyncio-sync asyncio Barrier parties}@anchor{3a7b}
@deffn {Ιδιότητα} parties

The number of tasks required to pass the barrier.
@end deffn

@geindex n_waiting (ιδιότητα της asyncio.Barrier)
@anchor{library/asyncio-sync asyncio Barrier n_waiting}@anchor{3a7c}
@deffn {Ιδιότητα} n_waiting

The number of tasks currently waiting in the barrier while filling.
@end deffn

@geindex broken (ιδιότητα της asyncio.Barrier)
@anchor{library/asyncio-sync asyncio Barrier broken}@anchor{3a7d}
@deffn {Ιδιότητα} broken

A boolean that is @code{True} if the barrier is in the broken state.
@end deffn
@end deffn

@geindex BrokenBarrierError
@anchor{library/asyncio-sync asyncio BrokenBarrierError}@anchor{9f8}
@deffn {Εξαίρεση} asyncio.BrokenBarrierError

This exception, a subclass of @ref{30d,,RuntimeError}, is raised when the
@ref{9f7,,Barrier} object is reset or broken.
@end deffn


__________________________________________________________________



Άλλαξε στην έκδοση 3.9: Acquiring a lock using @code{await lock} or @code{yield from lock} and/or
@ref{20a,,with} statement (@code{with await lock}, @code{with (yield from
lock)}) was removed.  Use @code{async with lock} instead.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Subprocesses,Ουρές,Synchronization Primitives,asyncio — Asynchronous I/O
@anchor{library/asyncio-subprocess doc}@anchor{3a7e}@anchor{library/asyncio-subprocess asyncio-subprocess}@anchor{39ff}@anchor{library/asyncio-subprocess subprocesses}@anchor{3a7f}@anchor{library/asyncio-subprocess translation-repo}@anchor{3a80}
@subsubsection Subprocesses


`Source code:' Lib/asyncio/subprocess.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/subprocess.py},
Lib/asyncio/base_subprocess.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/base_subprocess.py}


__________________________________________________________________


This section describes high-level async/await asyncio APIs to
create and manage subprocesses.
@anchor{library/asyncio-subprocess asyncio-example-subprocess-shell}@anchor{3a81}
Here’s an example of how asyncio can run a shell command and
obtain its result:

@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

will print:

@example
['ls /zzz' exited with 1]
[stderr]
ls: /zzz: No such file or directory
@end example

Because all asyncio subprocess functions are asynchronous and asyncio
provides many tools to work with such functions, it is easy to execute
and monitor multiple subprocesses in parallel.  It is indeed trivial
to modify the above example to run several commands simultaneously:

@example
async def main():
    await asyncio.gather(
        run('ls /zzz'),
        run('sleep 1; echo "hello"'))

asyncio.run(main())
@end example

See also the @ref{3a82,,Examples} subsection.

@menu
* Creating Subprocesses:: 
* Constants: Constants<7>. 
* Interacting with Subprocesses:: 

@end menu

@node Creating Subprocesses,Constants<7>,,Subprocesses
@anchor{library/asyncio-subprocess creating-subprocesses}@anchor{3a83}
@subsubsection Creating Subprocesses


@geindex create_subprocess_exec() (στη μονάδα asyncio)
@anchor{library/asyncio-subprocess asyncio create_subprocess_exec}@anchor{e3a}
@deffn {Συνάρτηση} async asyncio.create_subprocess_exec (program, *args, stdin=None, stdout=None, stderr=None, limit=None, **kwds)

Create a subprocess.

The `limit' argument sets the buffer limit for @ref{194a,,StreamReader}
wrappers for @ref{3a84,,stdout} and @ref{3a85,,stderr}
(if @ref{f46,,subprocess.PIPE} is passed to `stdout' and `stderr' arguments).

Return a @ref{3a86,,Process} instance.

See the documentation of @ref{3a87,,loop.subprocess_exec()} for other
parameters.

If the process object is garbage collected while the process is still
running, the child process will be killed.


Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.

@end deffn

@geindex create_subprocess_shell() (στη μονάδα asyncio)
@anchor{library/asyncio-subprocess asyncio create_subprocess_shell}@anchor{e3b}
@deffn {Συνάρτηση} async asyncio.create_subprocess_shell (cmd, stdin=None, stdout=None, stderr=None, limit=None, **kwds)

Run the `cmd' shell command.

The `limit' argument sets the buffer limit for @ref{194a,,StreamReader}
wrappers for @ref{3a84,,stdout} and @ref{3a85,,stderr}
(if @ref{f46,,subprocess.PIPE} is passed to `stdout' and `stderr' arguments).

Return a @ref{3a86,,Process} instance.

See the documentation of @ref{3a88,,loop.subprocess_shell()} for other
parameters.

If the process object is garbage collected while the process is still
running, the child process will be killed.

@cartouche
@quotation Σημαντικό 
It is the application’s responsibility to ensure that all whitespace and
special characters are quoted appropriately to avoid shell injection@footnote{https://en.wikipedia.org/wiki/Shell_injection#Shell_injection}
vulnerabilities. The @ref{781,,shlex.quote()} function can be used to properly
escape whitespace and special shell characters in strings that are going
to be used to construct shell commands.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.10: Removed the `loop' parameter.

@end deffn

@cartouche
@quotation Σημείωση 
Subprocesses are available for Windows if a @ref{9fe,,ProactorEventLoop} is
used. See @ref{3a89,,Subprocess Support on Windows}
for details.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης


asyncio also has the following `low-level' APIs to work with subprocesses:
@ref{3a87,,loop.subprocess_exec()}, @ref{3a88,,loop.subprocess_shell()},
@ref{3a8a,,loop.connect_read_pipe()}, @ref{3a8b,,loop.connect_write_pipe()},
as well as the @ref{3a8c,,Subprocess Transports}
and @ref{3a8d,,Subprocess Protocols}.


@node Constants<7>,Interacting with Subprocesses,Creating Subprocesses,Subprocesses
@anchor{library/asyncio-subprocess constants}@anchor{3a8e}
@subsubsection Constants


@geindex asyncio.subprocess.PIPE (ενσωματωμένη μεταβλητή)
@anchor{library/asyncio-subprocess asyncio subprocess PIPE}@anchor{3a8f}
@deffn {Δεδομένα} asyncio.subprocess.PIPE

Can be passed to the `stdin', `stdout' or `stderr' parameters.

If `PIPE' is passed to `stdin' argument, the
@ref{3a90,,Process.stdin} attribute
will point to a @ref{1c76,,StreamWriter} instance.

If `PIPE' is passed to `stdout' or `stderr' arguments, the
@ref{3a84,,Process.stdout} and
@ref{3a85,,Process.stderr}
attributes will point to @ref{194a,,StreamReader} instances.
@end deffn

@geindex asyncio.subprocess.STDOUT (ενσωματωμένη μεταβλητή)
@anchor{library/asyncio-subprocess asyncio subprocess STDOUT}@anchor{3a91}
@deffn {Δεδομένα} asyncio.subprocess.STDOUT

Special value that can be used as the `stderr' argument and indicates
that standard error should be redirected into standard output.
@end deffn

@geindex asyncio.subprocess.DEVNULL (ενσωματωμένη μεταβλητή)
@anchor{library/asyncio-subprocess asyncio subprocess DEVNULL}@anchor{3a92}
@deffn {Δεδομένα} asyncio.subprocess.DEVNULL

Special value that can be used as the `stdin', `stdout' or `stderr' argument
to process creation functions.  It indicates that the special file
@ref{2002,,os.devnull} will be used for the corresponding subprocess stream.
@end deffn

@node Interacting with Subprocesses,,Constants<7>,Subprocesses
@anchor{library/asyncio-subprocess interacting-with-subprocesses}@anchor{3a93}
@subsubsection Interacting with Subprocesses


Both @ref{e3a,,create_subprocess_exec()} and @ref{e3b,,create_subprocess_shell()}
functions return instances of the `Process' class.  `Process' is a high-level
wrapper that allows communicating with subprocesses and watching for
their completion.

@geindex asyncio.subprocess.Process (ενσωματωμένη κλάση)
@anchor{library/asyncio-subprocess asyncio subprocess Process}@anchor{3a86}
@deffn {Κλάση} asyncio.subprocess.Process

An object that wraps OS processes created by the
@ref{e3a,,create_subprocess_exec()} and @ref{e3b,,create_subprocess_shell()}
functions.

This class is designed to have a similar API to the
@ref{6bf,,subprocess.Popen} class, but there are some
notable differences:


@itemize *

@item 
unlike Popen, Process instances do not have an equivalent to
the @ref{399f,,poll()} method;

@item 
the @ref{1ca2,,communicate()} and
@ref{3a94,,wait()} methods don’t have a
`timeout' parameter: use the @ref{9f6,,wait_for()} function;

@item 
the @ref{3a94,,Process.wait()} method
is asynchronous, whereas @ref{266,,subprocess.Popen.wait()} method
is implemented as a blocking busy loop;

@item 
the `universal_newlines' parameter is not supported.
@end itemize

This class is @ref{3a2c,,not thread safe}.

See also the @ref{3a95,,Subprocess and Threads}
section.

@geindex wait() (μέθοδος της asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process wait}@anchor{3a94}
@deffn {Μέθοδος} async wait ()

Wait for the child process to terminate.

Set and return the @ref{3a96,,returncode} attribute.

@cartouche
@quotation Σημείωση 
This method can deadlock when using @code{stdout=PIPE} or
@code{stderr=PIPE} and the child process generates so much output
that it blocks waiting for the OS pipe buffer to accept
more data. Use the @ref{1ca2,,communicate()} method when using pipes
to avoid this condition.
@end quotation
@end cartouche
@end deffn

@geindex communicate() (μέθοδος της asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process communicate}@anchor{1ca2}
@deffn {Μέθοδος} async communicate (input=None)

Interact with process:


@enumerate 

@item 
send data to `stdin' (if `input' is not @code{None});

@item 
closes `stdin';

@item 
read data from `stdout' and `stderr', until EOF is reached;

@item 
wait for process to terminate.
@end enumerate

The optional `input' argument is the data (@ref{1c7,,bytes} object)
that will be sent to the child process.

Return a tuple @code{(stdout_data, stderr_data)}.

If either @ref{1404,,BrokenPipeError} or @ref{1407,,ConnectionResetError}
exception is raised when writing `input' into `stdin', the
exception is ignored.  This condition occurs when the process
exits before all data are written into `stdin'.

If it is desired to send data to the process” `stdin',
the process needs to be created with @code{stdin=PIPE}.  Similarly,
to get anything other than @code{None} in the result tuple, the
process has to be created with @code{stdout=PIPE} and/or
@code{stderr=PIPE} arguments.

Note, that the data read is buffered in memory, so do not use
this method if the data size is large or unlimited.


Άλλαξε στην έκδοση 3.12: `stdin' gets closed when @code{input=None} too.

@end deffn

@geindex send_signal() (μέθοδος της asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process send_signal}@anchor{1b61}
@deffn {Μέθοδος} send_signal (signal)

Sends the signal `signal' to the child process.

@cartouche
@quotation Σημείωση 
On Windows, @ref{1782,,SIGTERM} is an alias for @ref{3a97,,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() (μέθοδος της asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process terminate}@anchor{3a97}
@deffn {Μέθοδος} terminate ()

Stop the child process.

On POSIX systems this method sends @ref{1782,,SIGTERM} to the
child process.

On Windows the Win32 API function @code{TerminateProcess()} is
called to stop the child process.
@end deffn

@geindex kill() (μέθοδος της asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process kill}@anchor{3a98}
@deffn {Μέθοδος} kill ()

Kill the child process.

On POSIX systems this method sends @ref{f16,,SIGKILL} to the child
process.

On Windows this method is an alias for @ref{3a97,,terminate()}.
@end deffn

@geindex stdin (ιδιότητα της asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process stdin}@anchor{3a90}
@deffn {Ιδιότητα} stdin

Standard input stream (@ref{1c76,,StreamWriter}) or @code{None}
if the process was created with @code{stdin=None}.
@end deffn

@geindex stdout (ιδιότητα της asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process stdout}@anchor{3a84}
@deffn {Ιδιότητα} stdout

Standard output stream (@ref{194a,,StreamReader}) or @code{None}
if the process was created with @code{stdout=None}.
@end deffn

@geindex stderr (ιδιότητα της asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process stderr}@anchor{3a85}
@deffn {Ιδιότητα} stderr

Standard error stream (@ref{194a,,StreamReader}) or @code{None}
if the process was created with @code{stderr=None}.
@end deffn

@cartouche
@quotation Προειδοποίηση 
Use the @ref{1ca2,,communicate()} method rather than
@ref{3a90,,process.stdin.write()},
@ref{3a84,,await process.stdout.read()} or
@ref{3a85,,await process.stderr.read()}.
This avoids deadlocks due to streams pausing reading or writing
and blocking the child process.
@end quotation
@end cartouche

@geindex pid (ιδιότητα της asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process pid}@anchor{3a99}
@deffn {Ιδιότητα} pid

Process identification number (PID).

Note that for processes created by the @ref{e3b,,create_subprocess_shell()}
function, this attribute is the PID of the spawned shell.
@end deffn

@geindex returncode (ιδιότητα της asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process returncode}@anchor{3a96}
@deffn {Ιδιότητα} returncode

Return code of the process when it exits.

A @code{None} value indicates that the process has not terminated yet.

For processes created with @ref{e3a,,create_subprocess_exec()}, a negative
value @code{-N} indicates that the child was terminated by signal @code{N}
(POSIX only).

For processes created with @ref{e3b,,create_subprocess_shell()}, the
return code reflects the exit status of the shell itself (e.g. @code{/bin/sh}),
which may map signals to codes such as @code{128+N}. See the
documentation of the shell (for example, the Bash manual’s Exit Status)
for details.
@end deffn
@end deffn

@menu
* Subprocess and Threads:: 
* Examples: Examples<14>. 

@end menu

@node Subprocess and Threads,Examples<14>,,Interacting with Subprocesses
@anchor{library/asyncio-subprocess asyncio-subprocess-threads}@anchor{3a95}@anchor{library/asyncio-subprocess subprocess-and-threads}@anchor{3a9a}
@subsubsection Subprocess and Threads


Standard asyncio event loop supports running subprocesses from different threads by
default.

On Windows subprocesses are provided by @ref{9fe,,ProactorEventLoop} only (default),
@ref{30b,,SelectorEventLoop} has no subprocess support.

Note that alternative event loop implementations might have own limitations;
please refer to their documentation.


@subsubheading Δείτε επίσης


The @ref{3a2c,,Concurrency and multithreading in asyncio} section.


@node Examples<14>,,Subprocess and Threads,Interacting with Subprocesses
@anchor{library/asyncio-subprocess examples}@anchor{3a82}
@subsubsection Examples


An example using the @ref{3a86,,Process} class to
control a subprocess and the @ref{194a,,StreamReader} class to read from
its standard output.
@anchor{library/asyncio-subprocess asyncio-example-create-subprocess-exec}@anchor{3a9b}
The subprocess is created by the @ref{e3a,,create_subprocess_exec()}
function:

@example
import asyncio
import sys

async def get_date():
    code = 'import datetime as dt; print(dt.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

See also the @ref{3a9c,,same example}
written using low-level APIs.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Ουρές,Exceptions<14>,Subprocesses,asyncio — Asynchronous I/O
@anchor{library/asyncio-queue doc}@anchor{3a9d}@anchor{library/asyncio-queue asyncio-queues}@anchor{3a00}@anchor{library/asyncio-queue queues}@anchor{3a9e}@anchor{library/asyncio-queue translation-repo}@anchor{3a9f}
@subsubsection Ουρές


`Πηγαίος κώδικας:' Lib/asyncio/queues.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/queues.py}


__________________________________________________________________


Οι ουρές asyncio έχουν σχεδιαστεί ώστε να μοιάζουν με τις κλάσεις του module @ref{be,,queue}.  Αν και οι ουρές asyncio δεν είναι ασφαλείς για χρήση με νήματα (thread-safe), έχουν σχεδιαστεί για να χρησιμοποιούνται συγκεκριμένα σε κώδικα async/await.

Σημειώστε ότι οι μέθοδοι των ουρών asyncio δεν διαθέτουν παράμετρο `timeout'. Χρησιμοποιήστε την συνάρτηση @ref{9f6,,asyncio.wait_for()} για να εκτελέσετε λειτουργίες ουράς με χρονικό όριο.

Δείτε επίσης την ενότητα @ref{3aa0,,Examples} παρακάτω.

@menu
* Ουρά:: 
* Σειρά Προτεραιότητας:: 
* Ουρά LIFO:: 
* Εξαιρέσεις: Εξαιρέσεις<2>. 
* Παραδείγματα: Παραδείγματα<4>. 

@end menu

@node Ουρά,Σειρά Προτεραιότητας,,Ουρές
@anchor{library/asyncio-queue queue}@anchor{3aa1}
@subsubsection Ουρά


@geindex Queue (κλάση σε asyncio)
@anchor{library/asyncio-queue asyncio Queue}@anchor{e39}
@deffn {Κλάση} asyncio.Queue (maxsize=0)

Μια ουρά τύπου πρώτος που εισέρχεται, πρώτος που εξέρχεται (FIFO).

Αν η τιμή του `maxsize' είναι λιγότερη ή ίση με το μηδέν, το μέγεθος της ουράς είναι άπειρο.  Αν είναι ένας ακέραιος μεγαλύτερος από το @code{0}, τότε η εντολή @code{await put()} μπλοκάρει, όταν η ουρά φτάσει το `maxsize' μέχρι να αφαιρεθεί ένα στοιχείο μέσω της μεθόδου @ref{3aa2,,get()}.

Σε αντίθεση με την ουρά του @ref{be,,queue} στην βιβλιοθήκη threading, το μέγεθος της ουράς είναι πάντα γνωστό και μπορεί να επιστραφεί καλώντας τη μέθοδο @ref{3aa3,,qsize()}.


Άλλαξε στην έκδοση 3.10: Αφαιρέθηκε η παράμετρος `loop'.


Αυτή η κλάση είναι @ref{3a2c,,not thread safe}.

@geindex maxsize (ιδιότητα της asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue maxsize}@anchor{3aa4}
@deffn {Ιδιότητα} maxsize

Αριθμός στοιχείων που επιτρέπονται στην ουρά.
@end deffn

@geindex empty() (μέθοδος της asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue empty}@anchor{3aa5}
@deffn {Μέθοδος} empty ()

Επιστρέφει @code{True} αν η ουρά είναι άδεια, διαφορετικά @code{False}.
@end deffn

@geindex full() (μέθοδος της asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue full}@anchor{3aa6}
@deffn {Μέθοδος} full ()

Επιστρέφει @code{True} αν υπάρχουν @ref{3aa4,,maxsize} αντικείμενα στην ουρά.

Αν η ουρά αρχικοποιήθηκε με @code{maxsize=0} (προεπιλογή), τότε η @ref{3aa6,,full()} δεν επιστρέφει ποτέ @code{True}.
@end deffn

@geindex get() (μέθοδος της asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue get}@anchor{3aa2}
@deffn {Μέθοδος} async get ()

Αφαίρεση και επιστροφή ενός αντικειμένου από την ουρά. Αν η ουρά είναι κενή, περιμένετε μέχρι να είναι διαθέσιμο ένα αντικείμενο.

Κάνει raise μια @ref{6d3,,QueueShutDown} αν η ουρά έχει τερματιστεί και είναι κενή, ή αν η ουρά έχει τερματιστεί άμεσα.
@end deffn

@geindex get_nowait() (μέθοδος της asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue get_nowait}@anchor{3aa7}
@deffn {Μέθοδος} get_nowait ()

Επιστρέφει ένα αντικείμενο, αν είναι άμεσα διαθέσιμο, αλλιώς κάνε raise την @ref{3aa8,,QueueEmpty}.
@end deffn

@geindex join() (μέθοδος της asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue join}@anchor{117f}
@deffn {Μέθοδος} async join ()

Αποκλείει μέχρι να ληφθούν και να υποβληθούν σε επεξεργασία όλα τα στοιχεία στην ουρά.

Ο αριθμός των ημιτελών εργασιών αυξάνεται κάθε φορά που προστίθεται ένα αντικείμενο στην ουρά. Ο αριθμός μειώνεται όταν μια καταναλωτική coroutine καλεί τη μέθοδο @ref{1180,,task_done()} για να υποδείξει ότι το αντικείμενο λήφθηκε και η εργασία πάνω του έχει ολοκληρωθεί.  Όταν ο αριθμός των ατελείωτων εργασιών μειωθεί στο μηδέν, η μέθοδος @ref{117f,,join()} αποδεσμεύεται.
@end deffn

@geindex put() (μέθοδος της asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue put}@anchor{3aa9}
@deffn {Μέθοδος} async put (item)

Τοποθετεί ένα αντικείμενο στην ουρά. Αν η ουρά είναι γεμάτη, περιμένετε μέχρι να είναι διαθέσιμη μια ελεύθερη θέση, πριν προσθέσετε το αντικείμενο.

Κάνει raise μια @ref{6d3,,QueueShutDown} αν η ουρά έχει τερματιστεί.
@end deffn

@geindex put_nowait() (μέθοδος της asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue put_nowait}@anchor{3aaa}
@deffn {Μέθοδος} put_nowait (item)

Τοποθετεί ένα αντικείμενο στην ουρά χωρίς να μπλοκάρει.

Αν δεν είναι διαθέσιμη μια ελεύθερη θέση αμέσως, γίνεται raise η @ref{3aab,,QueueFull}.
@end deffn

@geindex qsize() (μέθοδος της asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue qsize}@anchor{3aa3}
@deffn {Μέθοδος} qsize ()

Επιστρέφει τον αριθμό των αντικειμένων στην ουρά.
@end deffn

@geindex shutdown() (μέθοδος της asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue shutdown}@anchor{6d2}
@deffn {Μέθοδος} shutdown (immediate=False)

Βάζει ένα στιγμιότυπο της @ref{e39,,Queue} σε λειτουργία τερματισμού.

The queue can no longer grow.
Future calls to @ref{3aa9,,put()} raise @ref{6d3,,QueueShutDown}.
Currently blocked callers of @code{put()} will be unblocked
and will raise @code{QueueShutDown} in the formerly awaiting task.

Αν το `immediate' είναι false (η προεπιλογή), η ουρά μπορεί να τερματιστεί κανονικά με κλήσεις της @ref{3aa2,,get()} για να εξαχθούν εργασίες που έχουν ήδη φορτωθεί.

Και αν η @ref{1180,,task_done()} κληθεί για κάθε υπόλοιπη εργασία, μια εκκρεμής @ref{117f,,join()} θα αποδεσμευτεί κανονικά.

Μόλις η ουρά είναι κενή, μελλοντικές κλήσεις της @ref{3aa2,,get()} θα κάνουν raise την @ref{6d3,,QueueShutDown}.

Αν το `immediate' είναι true, η ουρά τερματίζεται αμέσως. Η ουρά αδειάζει για να είναι εντελώς κενή και ο αριθμός των ημιτελών εργασιών μειώνεται κατά τον αριθμό των εργασιών που αδειάστηκαν. Αν οι ημιτελείς εργασίες είναι μηδέν, οι καλούντες της @ref{117f,,join()} αποδεσμεύονται. Επίσης, οι αποκλεισμένοι καλούντες της @ref{3aa2,,get()} αποδεσμεύονται και θα κάνουν raise την @ref{6d3,,QueueShutDown} επειδή η ουρά είναι κενή.

Χρησιμοποιήστε προσοχή όταν χρησιμοποιείτε την @ref{117f,,join()} με το `immediate' ορισμένο σε αληθές. Αυτό αποδεσμεύει την ένωση ακόμη και όταν δεν έχει γίνει καμία εργασία στις εργασίες, παραβιάζοντας το συνηθισμένο αμετάβλητο για την ένωση μιας ουράς.


Added in version 3.13.

@end deffn

@geindex task_done() (μέθοδος της asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue task_done}@anchor{1180}
@deffn {Μέθοδος} task_done ()

Υποδεικνύει ότι μια εργασία που είχε προστεθεί στην ουρά έχει ολοκληρωθεί.

Χρησιμοποιείται από τους καταναλωτές της ουράς. Για κάθε κλήση της @ref{3aa2,,get()} για να ανακτηθεί μια εργασία, μια επακόλουθη κλήση της @ref{1180,,task_done()} ενημερώνει την ουρά ότι η επεξεργασία της εργασίας έχει ολοκληρωθεί.

Εάν μια κλήση της @ref{117f,,join()} μπλοκάρει αυτή την στιγμή, θα συνεχιστεί όταν όλα τα αντικείμενα έχουν επεξεργαστεί (σημαίνει ότι λήφθηκε μια κλήση της @ref{1180,,task_done()} για κάθε αντικείμενο που είχε προστεθεί με @ref{3aa9,,put()} στην ουρά).

Κάνει raise την @ref{277,,ValueError} εάν κληθεί περισσότερες φορές από όσες τα αντικείμενα που είχαν τοποθετηθεί στην ουρά.
@end deffn
@end deffn

@node Σειρά Προτεραιότητας,Ουρά LIFO,Ουρά,Ουρές
@anchor{library/asyncio-queue priority-queue}@anchor{3aac}
@subsubsection Σειρά Προτεραιότητας


@geindex PriorityQueue (κλάση σε asyncio)
@anchor{library/asyncio-queue asyncio PriorityQueue}@anchor{3aad}
@deffn {Κλάση} asyncio.PriorityQueue

Μια παραλλαγή της @ref{e39,,Queue}; η οποία ανακτά τις καταχωρήσεις με σειρά προτεραιότητας (οι χαμηλότερες πρώτες).

Οι καταχωρήσεις είναι συνήθως της μορφής @code{(priority_number, data)}.
@end deffn

@node Ουρά LIFO,Εξαιρέσεις<2>,Σειρά Προτεραιότητας,Ουρές
@anchor{library/asyncio-queue lifo-queue}@anchor{3aae}
@subsubsection Ουρά LIFO


@geindex LifoQueue (κλάση σε asyncio)
@anchor{library/asyncio-queue asyncio LifoQueue}@anchor{3aaf}
@deffn {Κλάση} asyncio.LifoQueue

Μια παραλλαγή της κλάσης @ref{e39,,Queue} που ανακτά τις πιο πρόσφατα προστιθέμενες καταχωρίσεις πρώτες (με τη λογική τελευταίος μέσα, πρώτος έξω).
@end deffn

@node Εξαιρέσεις<2>,Παραδείγματα<4>,Ουρά LIFO,Ουρές
@anchor{library/asyncio-queue exceptions}@anchor{3ab0}
@subsubsection Εξαιρέσεις


@geindex QueueEmpty
@anchor{library/asyncio-queue asyncio QueueEmpty}@anchor{3aa8}
@deffn {Εξαίρεση} asyncio.QueueEmpty

Αυτή η εξαίρεση γίνεται raise όταν η μέθοδος @ref{3aa7,,get_nowait()} καλείται σε μια άδεια ουρά.
@end deffn

@geindex QueueFull
@anchor{library/asyncio-queue asyncio QueueFull}@anchor{3aab}
@deffn {Εξαίρεση} asyncio.QueueFull

Εξαίρεση που γίνεται raise όταν η μέθοδος @ref{3aaa,,put_nowait()} καλείται σε μια ουρά που έχει φτάσει στο `maxsize' της.
@end deffn

@geindex QueueShutDown
@anchor{library/asyncio-queue asyncio QueueShutDown}@anchor{6d3}
@deffn {Εξαίρεση} asyncio.QueueShutDown

Εξαίρεση που γίνεται raise όταν η μέθοδος @ref{3aa9,,put()} ή @ref{3aa2,,get()} καλείται σε μια ουρά που έχει τερματιστεί.


Added in version 3.13.

@end deffn

@node Παραδείγματα<4>,,Εξαιρέσεις<2>,Ουρές
@anchor{library/asyncio-queue examples}@anchor{3aa0}
@subsubsection Παραδείγματα

@anchor{library/asyncio-queue asyncio-example-queue-dist}@anchor{3ab1}
Οι ουρές μπορούν να χρησιμοποιηθούν για τη διανομή εργασίας μεταξύ αρκετών παράλληλων εργασιών:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Exceptions<14>,Call Graph Introspection,Ουρές,asyncio — Asynchronous I/O
@anchor{library/asyncio-exceptions doc}@anchor{3ab2}@anchor{library/asyncio-exceptions asyncio-exceptions}@anchor{3ab3}@anchor{library/asyncio-exceptions exceptions}@anchor{3ab4}@anchor{library/asyncio-exceptions translation-repo}@anchor{3ab5}
@subsubsection Exceptions


`Source code:' Lib/asyncio/exceptions.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/exceptions.py}


__________________________________________________________________


@geindex TimeoutError
@anchor{library/asyncio-exceptions asyncio TimeoutError}@anchor{1cb8}
@deffn {Εξαίρεση} asyncio.TimeoutError

A deprecated alias of @code{TimeoutError},
raised when the operation has exceeded the given deadline.


Άλλαξε στην έκδοση 3.11: This class was made an alias of @code{TimeoutError}.

@end deffn

@geindex CancelledError
@anchor{library/asyncio-exceptions asyncio CancelledError}@anchor{6da}
@deffn {Εξαίρεση} asyncio.CancelledError

The operation has been cancelled.

This exception can be caught to perform custom operations
when asyncio Tasks are cancelled.  In almost all situations the
exception must be re-raised.


Άλλαξε στην έκδοση 3.8: @code{CancelledError} is now a subclass of @ref{9b9,,BaseException} rather than @ref{d9e,,Exception}.

@end deffn

@geindex InvalidStateError
@anchor{library/asyncio-exceptions asyncio InvalidStateError}@anchor{3a34}
@deffn {Εξαίρεση} asyncio.InvalidStateError

Invalid internal state of @ref{460,,Task} or @ref{f8b,,Future}.

Can be raised in situations like setting a result value for a
`Future' object that already has a result value set.
@end deffn

@geindex SendfileNotAvailableError
@anchor{library/asyncio-exceptions asyncio SendfileNotAvailableError}@anchor{3ab6}
@deffn {Εξαίρεση} asyncio.SendfileNotAvailableError

The «sendfile» syscall is not available for the given
socket or file type.

A subclass of @ref{30d,,RuntimeError}.
@end deffn

@geindex IncompleteReadError
@anchor{library/asyncio-exceptions asyncio IncompleteReadError}@anchor{1edd}
@deffn {Εξαίρεση} asyncio.IncompleteReadError

The requested read operation did not complete fully.

Raised by the @ref{19b0,,asyncio stream APIs}.

This exception is a subclass of @ref{167e,,EOFError}.

@geindex expected (ιδιότητα της asyncio.IncompleteReadError)
@anchor{library/asyncio-exceptions asyncio IncompleteReadError expected}@anchor{3ab7}
@deffn {Ιδιότητα} expected

The total number (@ref{326,,int}) of expected bytes.
@end deffn

@geindex partial (ιδιότητα της asyncio.IncompleteReadError)
@anchor{library/asyncio-exceptions asyncio IncompleteReadError partial}@anchor{3a49}
@deffn {Ιδιότητα} partial

A string of @ref{1c7,,bytes} read before the end of stream was reached.
@end deffn
@end deffn

@geindex LimitOverrunError
@anchor{library/asyncio-exceptions asyncio LimitOverrunError}@anchor{3a4a}
@deffn {Εξαίρεση} asyncio.LimitOverrunError

Reached the buffer size limit while looking for a separator.

Raised by the @ref{19b0,,asyncio stream APIs}.

@geindex consumed (ιδιότητα της asyncio.LimitOverrunError)
@anchor{library/asyncio-exceptions asyncio LimitOverrunError consumed}@anchor{3ab8}
@deffn {Ιδιότητα} consumed

The total number of to be consumed bytes.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Call Graph Introspection,Event loop,Exceptions<14>,asyncio — Asynchronous I/O
@anchor{library/asyncio-graph doc}@anchor{3ab9}@anchor{library/asyncio-graph asyncio-graph}@anchor{3aba}@anchor{library/asyncio-graph call-graph-introspection}@anchor{3abb}@anchor{library/asyncio-graph translation-repo}@anchor{3abc}
@subsubsection Call Graph Introspection


`Source code:' Lib/asyncio/graph.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/graph.py}


__________________________________________________________________


asyncio has powerful runtime call graph introspection utilities
to trace the entire call graph of a running `coroutine' or `task', or
a suspended `future'.  These utilities and the underlying machinery
can be used from within a Python program or by external profilers
and debuggers.


Added in version 3.14.


@geindex print_call_graph() (στη μονάδα asyncio)
@anchor{library/asyncio-graph asyncio print_call_graph}@anchor{466}
@deffn {Συνάρτηση} asyncio.print_call_graph (future=None, /, *, file=None, depth=1, limit=None)

Print the async call graph for the current task or the provided
@ref{460,,Task} or @ref{f8b,,Future}.

This function prints entries starting from the top frame and going
down towards the invocation point.

The function receives an optional `future' argument.
If not passed, the current running task will be used.

If the function is called on `the current task', the optional
keyword-only `depth' argument can be used to skip the specified
number of frames from top of the stack.

If the optional keyword-only `limit' argument is provided, each call stack
in the resulting graph is truncated to include at most @code{abs(limit)}
entries. If `limit' is positive, the entries left are the closest to
the invocation point. If `limit' is negative, the topmost entries are
left. If `limit' is omitted or @code{None}, all entries are present.
If `limit' is @code{0}, the call stack is not printed at all, only
«awaited by» information is printed.

If `file' is omitted or @code{None}, the function will print
to @ref{e9c,,sys.stdout}.

`Example:'

The following Python code:

@example
import asyncio

async def test():
    asyncio.print_call_graph()

async def main():
    async with asyncio.TaskGroup() as g:
        g.create_task(test(), name='test')

asyncio.run(main())
@end example

will print:

@example
* Task(name='test', id=0x1039f0fe0)
+ Call stack:
|   File 't2.py', line 4, in async test()
+ Awaited by:
   * Task(name='Task-1', id=0x103a5e060)
      + Call stack:
      |   File 'taskgroups.py', line 107, in async TaskGroup.__aexit__()
      |   File 't2.py', line 7, in async main()
@end example
@end deffn

@geindex format_call_graph() (στη μονάδα asyncio)
@anchor{library/asyncio-graph asyncio format_call_graph}@anchor{3abd}
@deffn {Συνάρτηση} asyncio.format_call_graph (future=None, /, *, depth=1, limit=None)

Like @ref{466,,print_call_graph()}, but returns a string.
If `future' is @code{None} and there’s no current task,
the function returns an empty string.
@end deffn

@geindex capture_call_graph() (στη μονάδα asyncio)
@anchor{library/asyncio-graph asyncio capture_call_graph}@anchor{465}
@deffn {Συνάρτηση} asyncio.capture_call_graph (future=None, /, *, depth=1, limit=None)

Capture the async call graph for the current task or the provided
@ref{460,,Task} or @ref{f8b,,Future}.

The function receives an optional `future' argument.
If not passed, the current running task will be used. If there’s no
current task, the function returns @code{None}.

If the function is called on `the current task', the optional
keyword-only `depth' argument can be used to skip the specified
number of frames from top of the stack.

Returns a @code{FutureCallGraph} data class object:


@itemize *

@item 
@code{FutureCallGraph(future, call_stack, awaited_by)}

@quotation

Where `future' is a reference to a @ref{f8b,,Future} or
a @ref{460,,Task} (or their subclasses.)

@code{call_stack} is a tuple of @code{FrameCallGraphEntry} objects.

@code{awaited_by} is a tuple of @code{FutureCallGraph} objects.
@end quotation

@item 
@code{FrameCallGraphEntry(frame)}

@quotation

Where `frame' is a frame object of a regular Python function
in the call stack.
@end quotation
@end itemize
@end deffn

@menu
* Low level utility functions:: 

@end menu

@node Low level utility functions,,,Call Graph Introspection
@anchor{library/asyncio-graph low-level-utility-functions}@anchor{3abe}
@subsubsection Low level utility functions


To introspect an async call graph asyncio requires cooperation from
control flow structures, such as @ref{e34,,shield()} or @ref{6d7,,TaskGroup}.
Any time an intermediate @ref{f8b,,Future} object with low-level APIs like
@ref{ecc,,Future.add_done_callback()} is
involved, the following two functions should be used to inform asyncio
about how exactly such intermediate future objects are connected with
the tasks they wrap or control.

@geindex future_add_to_awaited_by() (στη μονάδα asyncio)
@anchor{library/asyncio-graph asyncio future_add_to_awaited_by}@anchor{3abf}
@deffn {Συνάρτηση} asyncio.future_add_to_awaited_by (future, waiter, /)

Record that `future' is awaited on by `waiter'.

Both `future' and `waiter' must be instances of
@ref{f8b,,Future} or @ref{460,,Task} or their subclasses,
otherwise the call would have no effect.

A call to @code{future_add_to_awaited_by()} must be followed by an
eventual call to the @ref{3ac0,,future_discard_from_awaited_by()} function
with the same arguments.
@end deffn

@geindex future_discard_from_awaited_by() (στη μονάδα asyncio)
@anchor{library/asyncio-graph asyncio future_discard_from_awaited_by}@anchor{3ac0}
@deffn {Συνάρτηση} asyncio.future_discard_from_awaited_by (future, waiter, /)

Record that `future' is no longer awaited on by `waiter'.

Both `future' and `waiter' must be instances of
@ref{f8b,,Future} or @ref{460,,Task} or their subclasses, otherwise
the call would have no effect.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Event loop,Futures,Call Graph Introspection,asyncio — Asynchronous I/O
@anchor{library/asyncio-eventloop doc}@anchor{3ac1}@anchor{library/asyncio-eventloop asyncio-event-loop}@anchor{112f}@anchor{library/asyncio-eventloop event-loop}@anchor{3ac2}@anchor{library/asyncio-eventloop translation-repo}@anchor{3ac3}
@subsubsection Event loop


`Source code:' Lib/asyncio/events.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/events.py},
Lib/asyncio/base_events.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/base_events.py}


__________________________________________________________________


@subsubheading Preface


The event loop is the core of every asyncio application.
Event loops run asynchronous tasks and callbacks, perform network
IO operations, and run subprocesses.

Application developers should typically use the high-level asyncio functions,
such as @ref{309,,asyncio.run()}, and should rarely need to reference the loop
object or call its methods.  This section is intended mostly for authors
of lower-level code, libraries, and frameworks, who need finer control over
the event loop behavior.

@subsubheading Obtaining the Event Loop


The following low-level functions can be used to get, set, or create
an event loop:

@geindex get_running_loop() (στη μονάδα asyncio)
@anchor{library/asyncio-eventloop asyncio get_running_loop}@anchor{ecf}
@deffn {Συνάρτηση} asyncio.get_running_loop ()

Return the running event loop in the current OS thread.

Raise a @ref{30d,,RuntimeError} if there is no running event loop.

This function can only be called from a coroutine or a callback.


Added in version 3.7.

@end deffn

@geindex get_event_loop() (στη μονάδα asyncio)
@anchor{library/asyncio-eventloop asyncio get_event_loop}@anchor{56c}
@deffn {Συνάρτηση} asyncio.get_event_loop ()

Get the current event loop.

When called from a coroutine or a callback (e.g. scheduled with
call_soon or similar API), this function will always return the
running event loop.

If there is no running event loop set, the function will return
the result of the @code{get_event_loop_policy().get_event_loop()} call.

Because this function has rather complex behavior (especially
when custom event loop policies are in use), using the
@ref{ecf,,get_running_loop()} function is preferred to @code{get_event_loop()}
in coroutines and callbacks.

As noted above, consider using the higher-level @ref{309,,asyncio.run()} function,
instead of using these lower level functions to manually create and close an
event loop.


Άλλαξε στην έκδοση 3.14: Raises a @ref{30d,,RuntimeError} if there is no current event loop.


@cartouche
@quotation Σημείωση 
The @code{asyncio} policy system is deprecated and will be removed
in Python 3.16; from there on, this function will return the current
running event loop if present else it will return the
loop set by @ref{1d53,,set_event_loop()}.
@end quotation
@end cartouche
@end deffn

@geindex set_event_loop() (στη μονάδα asyncio)
@anchor{library/asyncio-eventloop asyncio set_event_loop}@anchor{1d53}
@deffn {Συνάρτηση} asyncio.set_event_loop (loop)

Set `loop' as the current event loop for the current OS thread.
@end deffn

@geindex new_event_loop() (στη μονάδα asyncio)
@anchor{library/asyncio-eventloop asyncio new_event_loop}@anchor{3a0b}
@deffn {Συνάρτηση} asyncio.new_event_loop ()

Create and return a new event loop object.
@end deffn

Note that the behaviour of @ref{56c,,get_event_loop()}, @ref{1d53,,set_event_loop()},
and @ref{3a0b,,new_event_loop()} functions can be altered by
@ref{3ac4,,setting a custom event loop policy}.

@subsubheading Contents


This documentation page contains the following sections:


@itemize *

@item 
The @ref{3ac5,,Event Loop Methods} section is the reference documentation of
the event loop APIs;

@item 
The @ref{3ac6,,Callback Handles} section documents the @ref{2071,,Handle} and
@ref{1cdc,,TimerHandle} instances which are returned from scheduling
methods such as @ref{ec8,,loop.call_soon()} and @ref{eca,,loop.call_later()};

@item 
The @ref{3ac7,,Server Objects} section documents types returned from
event loop methods like @ref{ed7,,loop.create_server()};

@item 
The @ref{3ac8,,Event Loop Implementations} section documents the
@ref{30b,,SelectorEventLoop} and @ref{9fe,,ProactorEventLoop} classes;

@item 
The @ref{3ac9,,Examples} section showcases how to work with some event
loop APIs.
@end itemize

@menu
* Event loop methods:: 
* Callback handles:: 
* Server objects:: 
* Event loop implementations:: 
* Examples: Examples<15>. 

@end menu

@node Event loop methods,Callback handles,,Event loop
@anchor{library/asyncio-eventloop asyncio-event-loop-methods}@anchor{3aca}@anchor{library/asyncio-eventloop event-loop-methods}@anchor{3ac5}
@subsubsection Event loop methods


Event loops have `low-level' APIs for the following:

@menu
* Running and stopping the loop:: 
* Scheduling callbacks:: 
* Scheduling delayed callbacks:: 
* Creating futures and tasks:: 
* Opening network connections:: 
* Creating network servers:: 
* Transferring files:: 
* TLS upgrade:: 
* Watching file descriptors:: 
* Working with socket objects directly:: 
* DNS:: 
* Working with pipes:: 
* Unix signals:: 
* Executing code in thread or process pools:: 
* Error handling API:: 
* Enabling debug mode:: 
* Running subprocesses:: 

@end menu

@node Running and stopping the loop,Scheduling callbacks,,Event loop methods
@anchor{library/asyncio-eventloop running-and-stopping-the-loop}@anchor{3acb}
@subsubsection Running and stopping the loop


@geindex run_until_complete() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop run_until_complete}@anchor{1036}
@deffn {Μέθοδος} loop.run_until_complete (future)

Run until the `future' (an instance of @ref{f8b,,Future}) has
completed.

If the argument is a @ref{39fe,,coroutine object} it
is implicitly scheduled to run as a @ref{460,,asyncio.Task}.

Return the Future’s result or raise its exception.
@end deffn

@geindex run_forever() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop run_forever}@anchor{3acc}
@deffn {Μέθοδος} loop.run_forever ()

Run the event loop until @ref{103b,,stop()} is called.

If @ref{103b,,stop()} is called before @code{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.

If @ref{103b,,stop()} is called while @code{run_forever()} is running,
the loop will run the current batch of callbacks and then exit.
Note that new callbacks scheduled by callbacks will not run in this
case; instead, they will run the next time @code{run_forever()} or
@ref{1036,,run_until_complete()} is called.
@end deffn

@geindex stop() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop stop}@anchor{103b}
@deffn {Μέθοδος} loop.stop ()

Stop the event loop.
@end deffn

@geindex is_running() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop is_running}@anchor{3acd}
@deffn {Μέθοδος} loop.is_running ()

Return @code{True} if the event loop is currently running.
@end deffn

@geindex is_closed() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop is_closed}@anchor{117c}
@deffn {Μέθοδος} loop.is_closed ()

Return @code{True} if the event loop was closed.
@end deffn

@geindex close() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop close}@anchor{3ace}
@deffn {Μέθοδος} loop.close ()

Close the event loop.

The loop must not be running when this function is called.
Any pending callbacks will be discarded.

This method clears all queues and shuts down the executor, but does
not wait for the executor to finish.

This method is idempotent and irreversible.  No other methods
should be called after the event loop is closed.
@end deffn

@geindex shutdown_asyncgens() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop shutdown_asyncgens}@anchor{103d}
@deffn {Μέθοδος} async loop.shutdown_asyncgens ()

Schedule all currently open @ref{2692,,asynchronous generator} objects to
close with an @ref{caa,,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.

Note that there is no need to call this function when
@ref{309,,asyncio.run()} is used.

Example:

@example
try:
    loop.run_forever()
finally:
    loop.run_until_complete(loop.shutdown_asyncgens())
    loop.close()
@end example


Added in version 3.6.

@end deffn

@geindex shutdown_default_executor() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop shutdown_default_executor}@anchor{cb8}
@deffn {Μέθοδος} async loop.shutdown_default_executor (timeout=None)

Schedule the closure of the default executor and wait for it to join all of
the threads in the @ref{b27,,ThreadPoolExecutor}.
Once this method has been called,
using the default executor with @ref{cba,,loop.run_in_executor()}
will raise a @ref{30d,,RuntimeError}.

The `timeout' parameter specifies the amount of time
(in @ref{327,,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{6dd,,RuntimeWarning} is emitted
and the default executor is terminated
without waiting for its threads to finish joining.

@cartouche
@quotation Σημείωση 
Do not call this method when using @ref{309,,asyncio.run()},
as the latter handles default executor shutdown automatically.
@end quotation
@end cartouche


Added in version 3.9.



Άλλαξε στην έκδοση 3.12: Added the `timeout' parameter.

@end deffn

@node Scheduling callbacks,Scheduling delayed callbacks,Running and stopping the loop,Event loop methods
@anchor{library/asyncio-eventloop scheduling-callbacks}@anchor{3acf}
@subsubsection Scheduling callbacks


@geindex call_soon() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop call_soon}@anchor{ec8}
@deffn {Μέθοδος} loop.call_soon (callback, *args, context=None)

Schedule the `callback' @ref{2fc5,,callback} to be called with
`args' arguments at the next iteration of the event loop.

Return an instance of @ref{2071,,asyncio.Handle},
which can be used later to cancel the callback.

Callbacks are called in the order in which they are registered.
Each callback will be called exactly once.

The optional keyword-only `context' argument specifies a
custom @ref{421,,contextvars.Context} for the `callback' to run in.
Callbacks use the current context when no `context' is provided.

Unlike @ref{ec9,,call_soon_threadsafe()}, this method is not thread-safe.
@end deffn

@geindex call_soon_threadsafe() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop call_soon_threadsafe}@anchor{ec9}
@deffn {Μέθοδος} loop.call_soon_threadsafe (callback, *args, context=None)

A thread-safe variant of @ref{ec8,,call_soon()}. When scheduling callbacks from
another thread, this function `must' be used, since @code{call_soon()} is not
thread-safe.

This function is safe to be called from a reentrant context or signal handler,
however, it is not safe or fruitful to use the returned handle in such contexts.

Raises @ref{30d,,RuntimeError} if called on a loop that’s been closed.
This can happen on a secondary thread when the main application is
shutting down.

See the @ref{3a2c,,concurrency and multithreading}
section of the documentation.


Άλλαξε στην έκδοση 3.7: The `context' keyword-only parameter was added. See 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/}
for more details.

@end deffn
@anchor{library/asyncio-eventloop asyncio-pass-keywords}@anchor{3ad0}
@cartouche
@quotation Σημείωση 
Most @ref{b,,asyncio} scheduling functions don’t allow passing
keyword arguments.  To do that, use @ref{4a6,,functools.partial()}:

@example
# will schedule "print("Hello", flush=True)"
loop.call_soon(
    functools.partial(print, "Hello", flush=True))
@end example

Using partial objects is usually more convenient than using lambdas,
as asyncio can render partial objects better in debug and error
messages.
@end quotation
@end cartouche

@node Scheduling delayed callbacks,Creating futures and tasks,Scheduling callbacks,Event loop methods
@anchor{library/asyncio-eventloop asyncio-delayed-calls}@anchor{3ad1}@anchor{library/asyncio-eventloop scheduling-delayed-callbacks}@anchor{3ad2}
@subsubsection Scheduling delayed callbacks


Event loop provides mechanisms to schedule callback functions
to be called at some point in the future.  Event loop uses monotonic
clocks to track time.

@geindex call_later() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop call_later}@anchor{eca}
@deffn {Μέθοδος} loop.call_later (delay, callback, *args, context=None)

Schedule `callback' to be called after the given `delay'
number of seconds (can be either an int or a float).

An instance of @ref{1cdc,,asyncio.TimerHandle} is returned which can
be used to cancel the callback.

`callback' will be called exactly once.  If two callbacks are
scheduled for exactly the same time, the order in which they
are called is undefined.

The optional positional `args' will be passed to the callback when
it is called. Use @ref{4a6,,functools.partial()}
@ref{3ad0,,to pass keyword arguments} to
`callback'.

An optional keyword-only `context' argument allows specifying a
custom @ref{421,,contextvars.Context} for the `callback' to run in.
The current context is used when no `context' is provided.

@cartouche
@quotation Σημείωση 
For performance, callbacks scheduled with @code{loop.call_later()}
may run up to one clock-resolution early (see
@code{time.get_clock_info('monotonic').resolution}).
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.7: The `context' keyword-only parameter was added. See 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/}
for more details.



Άλλαξε στην έκδοση 3.8: In Python 3.7 and earlier with the default event loop implementation,
the `delay' could not exceed one day.
This has been fixed in Python 3.8.

@end deffn

@geindex call_at() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop call_at}@anchor{ecb}
@deffn {Μέθοδος} loop.call_at (when, callback, *args, context=None)

Schedule `callback' to be called at the given absolute timestamp
`when' (an int or a float), using the same time reference as
@ref{3ad3,,loop.time()}.

This method’s behavior is the same as @ref{eca,,call_later()}.

An instance of @ref{1cdc,,asyncio.TimerHandle} is returned which can
be used to cancel the callback.

@cartouche
@quotation Σημείωση 
For performance, callbacks scheduled with @code{loop.call_at()}
may run up to one clock-resolution early (see
@code{time.get_clock_info('monotonic').resolution}).
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.7: The `context' keyword-only parameter was added. See 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/}
for more details.



Άλλαξε στην έκδοση 3.8: In Python 3.7 and earlier with the default event loop implementation,
the difference between `when' and the current time could not exceed
one day.  This has been fixed in Python 3.8.

@end deffn

@geindex time() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop time}@anchor{3ad3}
@deffn {Μέθοδος} loop.time ()

Return the current time, as a @ref{327,,float} value, according to
the event loop’s internal monotonic clock.
@end deffn

@cartouche
@quotation Σημείωση 

Άλλαξε στην έκδοση 3.8: In Python 3.7 and earlier timeouts (relative `delay' or absolute `when')
should not exceed one day.  This has been fixed in Python 3.8.

@end quotation
@end cartouche


@subsubheading Δείτε επίσης


The @ref{e33,,asyncio.sleep()} function.


@node Creating futures and tasks,Opening network connections,Scheduling delayed callbacks,Event loop methods
@anchor{library/asyncio-eventloop creating-futures-and-tasks}@anchor{3ad4}
@subsubsection Creating futures and tasks


@geindex create_future() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop create_future}@anchor{1038}
@deffn {Μέθοδος} loop.create_future ()

Create an @ref{f8b,,asyncio.Future} object attached to the event loop.

This is the preferred way to create Futures in asyncio. This lets
third-party event loops provide alternative implementations of
the Future object (with better performance or instrumentation).


Added in version 3.5.2.

@end deffn

@geindex create_task() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop create_task}@anchor{463}
@deffn {Μέθοδος} loop.create_task (coro, *, name=None, context=None, eager_start=None, **kwargs)

Schedule the execution of @ref{39fe,,coroutine} `coro'.
Return a @ref{460,,Task} object.

Third-party event loops can use their own subclass of @ref{460,,Task}
for interoperability. In this case, the result type is a subclass
of @code{Task}.

The full function signature is largely the same as that of the
@ref{460,,Task} constructor (or factory) - all of the keyword arguments to
this function are passed through to that interface.

If the `name' argument is provided and not @code{None}, it is set as
the name of the task using @ref{da1,,Task.set_name()}.

An optional keyword-only `context' argument allows specifying a
custom @ref{421,,contextvars.Context} for the `coro' to run in.
The current context copy is created when no `context' is provided.

An optional keyword-only `eager_start' argument allows specifying
if the task should execute eagerly during the call to create_task,
or be scheduled later. If `eager_start' is not passed the mode set
by @ref{461,,loop.set_task_factory()} will be used.


Άλλαξε στην έκδοση 3.8: Added the `name' parameter.



Άλλαξε στην έκδοση 3.11: Added the `context' parameter.



Άλλαξε στην έκδοση 3.13.3: Added @code{kwargs} which passes on arbitrary extra parameters, including  @code{name} and @code{context}.



Άλλαξε στην έκδοση 3.13.4: Rolled back the change that passes on `name' and `context' (if it is None),
while still passing on other arbitrary keyword arguments (to avoid breaking backwards compatibility with 3.13.3).



Άλλαξε στην έκδοση 3.14: All `kwargs' are now passed on. The `eager_start' parameter works with eager task factories.

@end deffn

@geindex set_task_factory() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop set_task_factory}@anchor{461}
@deffn {Μέθοδος} loop.set_task_factory (factory)

Set a task factory that will be used by
@ref{463,,loop.create_task()}.

If `factory' is @code{None} the default task factory will be set.
Otherwise, `factory' must be a `callable' with the signature matching
@code{(loop, coro, **kwargs)}, where `loop' is a reference to the active
event loop, and `coro' is a coroutine object.  The callable
must pass on all `kwargs', and return a @ref{460,,asyncio.Task}-compatible object.


Άλλαξε στην έκδοση 3.13.3: Required that all `kwargs' are passed on to @ref{460,,asyncio.Task}.



Άλλαξε στην έκδοση 3.13.4: `name' is no longer passed to task factories. `context' is no longer passed
to task factories if it is @code{None}.


Άλλαξε στην έκδοση 3.14: `name' and `context' are now unconditionally passed on to task factories again.


@end deffn

@geindex get_task_factory() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop get_task_factory}@anchor{117e}
@deffn {Μέθοδος} loop.get_task_factory ()

Return a task factory or @code{None} if the default one is in use.
@end deffn

@node Opening network connections,Creating network servers,Creating futures and tasks,Event loop methods
@anchor{library/asyncio-eventloop opening-network-connections}@anchor{3ad5}
@subsubsection Opening network connections


@geindex create_connection() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop create_connection}@anchor{9f9}
@deffn {Μέθοδος} async 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)

Open a streaming transport connection to a given
address specified by `host' and `port'.

The socket family can be either @ref{1da7,,AF_INET} or
@ref{1da8,,AF_INET6} depending on `host' (or the `family'
argument, if provided).

The socket type will be @ref{1698,,SOCK_STREAM}.

`protocol_factory' must be a callable returning an
@ref{3ad6,,asyncio protocol} implementation.

This method will try to establish the connection in the background.
When successful, it returns a @code{(transport, protocol)} pair.

The chronological synopsis of the underlying operation is as follows:


@enumerate 

@item 
The connection is established and a @ref{3ad7,,transport}
is created for it.

@item 
`protocol_factory' is called without arguments and is expected to
return a @ref{3ad6,,protocol} instance.

@item 
The protocol instance is coupled with the transport by calling its
@ref{3ad8,,connection_made()} method.

@item 
A @code{(transport, protocol)} tuple is returned on success.
@end enumerate

The created transport is an implementation-dependent bidirectional
stream.

Other arguments:


@itemize *

@item 
`ssl': if given and not false, a SSL/TLS transport is created
(by default a plain TCP transport is created).  If `ssl' is
a @ref{336,,ssl.SSLContext} object, this context is used to create
the transport; if `ssl' is @ref{fcc,,True}, a default context returned
from @ref{68e,,ssl.create_default_context()} is used.


@subsubheading Δείτε επίσης


@ref{3ad9,,SSL/TLS security considerations}


@item 
`server_hostname' sets or overrides the hostname that the target
server’s certificate will be matched against.  Should only be passed
if `ssl' is not @code{None}.  By default the value of the `host' argument
is used.  If `host' is empty, there is no default and you must pass a
value for `server_hostname'.  If `server_hostname' is an empty
string, hostname matching is disabled (which is a serious security
risk, allowing for potential man-in-the-middle attacks).

@item 
`family', `proto', `flags' are the optional address family, protocol
and flags to be passed through to getaddrinfo() for `host' resolution.
If given, these should all be integers from the corresponding
@ref{d4,,socket} module constants.

@item 
`happy_eyeballs_delay', if given, enables Happy Eyeballs for this
connection. It should
be a floating-point number representing the amount of time in seconds
to wait for a connection attempt to complete, before starting the next
attempt in parallel. This is the «Connection Attempt Delay» as defined
in 
@geindex RFC; RFC 8305
RFC 8305@footnote{https://datatracker.ietf.org/doc/html/rfc8305.html}. A sensible default value recommended by the RFC is @code{0.25}
(250 milliseconds).

@item 
`interleave' controls address reordering when a host name resolves to
multiple IP addresses.
If @code{0} or unspecified, no reordering is done, and addresses are
tried in the order returned by @ref{fd3,,getaddrinfo()}. If a positive integer
is specified, the addresses are interleaved by address family, and the
given integer is interpreted as «First Address Family Count» as defined
in 
@geindex RFC; RFC 8305
RFC 8305@footnote{https://datatracker.ietf.org/doc/html/rfc8305.html}. The default is @code{0} if `happy_eyeballs_delay' is not
specified, and @code{1} if it is.

@item 
`sock', if given, should be an existing, already connected
@ref{115a,,socket.socket} object to be used by the transport.
If `sock' is given, none of `host', `port', `family', `proto', `flags',
`happy_eyeballs_delay', `interleave'
and `local_addr' should be specified.

@cartouche
@quotation Σημείωση 
The `sock' argument transfers ownership of the socket to the
transport created. To close the socket, call the transport’s
@ref{3ada,,close()} method.
@end quotation
@end cartouche

@item 
`local_addr', if given, is a @code{(local_host, local_port)} tuple used
to bind the socket locally.  The `local_host' and `local_port'
are looked up using @code{getaddrinfo()}, similarly to `host' and `port'.

@item 
`ssl_handshake_timeout' is (for a TLS connection) the time in seconds
to wait for the TLS handshake to complete before aborting the connection.
@code{60.0} seconds if @code{None} (default).

@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).

@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


Άλλαξε στην έκδοση 3.5: Added support for SSL/TLS in @ref{9fe,,ProactorEventLoop}.



Άλλαξε στην έκδοση 3.6: The socket option @ref{f32,,socket.TCP_NODELAY} is set by default
for all TCP connections.



Άλλαξε στην έκδοση 3.7: Added the `ssl_handshake_timeout' parameter.



Άλλαξε στην έκδοση 3.8: Added the `happy_eyeballs_delay' and `interleave' parameters.

Happy Eyeballs Algorithm: Success with Dual-Stack Hosts.
When a server’s IPv4 path and protocol are working, but the server’s
IPv6 path and protocol are not working, a dual-stack client
application experiences significant connection delay compared to an
IPv4-only client.  This is undesirable because it causes the
dual-stack client to have a worse user experience.  This document
specifies requirements for algorithms that reduce this user-visible
delay and provides an algorithm.

For more information: @indicateurl{https://datatracker.ietf.org/doc/html/rfc6555}



Άλλαξε στην έκδοση 3.11: Added the `ssl_shutdown_timeout' parameter.



Άλλαξε στην έκδοση 3.12: `all_errors' was added.



@subsubheading Δείτε επίσης


The @ref{edc,,open_connection()} function is a high-level alternative
API.  It returns a pair of (@ref{194a,,StreamReader}, @ref{1c76,,StreamWriter})
that can be used directly in async/await code.

@end deffn

@geindex create_datagram_endpoint() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop create_datagram_endpoint}@anchor{b1a}
@deffn {Μέθοδος} async 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)

Create a datagram connection.

The socket family can be either @ref{1da7,,AF_INET},
@ref{1da8,,AF_INET6}, or @ref{1daa,,AF_UNIX},
depending on `host' (or the `family' argument, if provided).

The socket type will be @ref{1697,,SOCK_DGRAM}.

`protocol_factory' must be a callable returning a
@ref{3ad6,,protocol} implementation.

A tuple of @code{(transport, protocol)} is returned on success.

Other arguments:


@itemize *

@item 
`local_addr', if given, is a @code{(local_host, local_port)} tuple used
to bind the socket locally.  The `local_host' and `local_port'
are looked up using @ref{fd3,,getaddrinfo()}.

@cartouche
@quotation Σημείωση 
On Windows, when using the proactor event loop with @code{local_addr=None},
an @ref{53c,,OSError} with @code{errno.WSAEINVAL} will be raised
when running it.
@end quotation
@end cartouche

@item 
`remote_addr', if given, is a @code{(remote_host, remote_port)} tuple used
to connect the socket to a remote address.  The `remote_host' and
`remote_port' are looked up using @ref{fd3,,getaddrinfo()}.

@item 
`family', `proto', `flags' are the optional address family, protocol
and flags to be passed through to @ref{fd3,,getaddrinfo()} for `host'
resolution. If given, these should all be integers from the
corresponding @ref{d4,,socket} module constants.

@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{f32,,socket.SO_REUSEPORT} constant is not
defined then this capability is unsupported.

@item 
`allow_broadcast' tells the kernel to allow this endpoint to send
messages to the broadcast address.

@item 
`sock' can optionally be specified in order to use a preexisting,
already connected, @ref{115a,,socket.socket} object to be used by the
transport. If specified, `local_addr' and `remote_addr' should be omitted
(must be @ref{a65,,None}).

@cartouche
@quotation Σημείωση 
The `sock' argument transfers ownership of the socket to the
transport created. To close the socket, call the transport’s
@ref{3ada,,close()} method.
@end quotation
@end cartouche
@end itemize

See @ref{3adb,,UDP echo client protocol} and
@ref{3adc,,UDP echo server protocol} examples.


Άλλαξε στην έκδοση 3.4.4: The `family', `proto', `flags', `reuse_address', `reuse_port',
`allow_broadcast', and `sock' parameters were added.



Άλλαξε στην έκδοση 3.8: Added support for Windows.



Άλλαξε στην έκδοση 3.8.1: The `reuse_address' parameter is no longer supported, as using
@ref{f32,,socket.SO_REUSEADDR}
poses a significant security concern for
UDP. Explicitly passing @code{reuse_address=True} will raise an exception.

When multiple processes with differing UIDs assign sockets to an
identical UDP socket address with @code{SO_REUSEADDR}, incoming packets can
become randomly distributed among the sockets.

For supported platforms, `reuse_port' can be used as a replacement for
similar functionality. With `reuse_port',
@ref{f32,,socket.SO_REUSEPORT}
is used instead, which specifically
prevents processes with differing UIDs from assigning sockets to the same
socket address.



Άλλαξε στην έκδοση 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() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop create_unix_connection}@anchor{3a43}
@deffn {Μέθοδος} async loop.create_unix_connection (protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Create a Unix connection.

The socket family will be @ref{1daa,,AF_UNIX}; socket
type will be @ref{1698,,SOCK_STREAM}.

A tuple of @code{(transport, protocol)} is returned on success.

`path' is the name of a Unix domain socket and is required,
unless a `sock' parameter is specified.  Abstract Unix sockets,
@ref{1df,,str}, @ref{1c7,,bytes}, and @ref{4ee,,Path} paths are
supported.

See the documentation of the @ref{9f9,,loop.create_connection()} method
for information about arguments to this method.

@ref{232d,,Διαθεσιμότητα}: Unix.


Άλλαξε στην έκδοση 3.7: Added the `ssl_handshake_timeout' parameter.
The `path' parameter can now be a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.11: Added the `ssl_shutdown_timeout' parameter.

@end deffn

@node Creating network servers,Transferring files,Opening network connections,Event loop methods
@anchor{library/asyncio-eventloop creating-network-servers}@anchor{3add}
@subsubsection Creating network servers


@geindex create_server() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop loop-create-server}@anchor{3a02}@anchor{library/asyncio-eventloop asyncio loop create_server}@anchor{ed7}
@deffn {Μέθοδος} async 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{1698,,SOCK_STREAM}) listening
on `port' of the `host' address.

Returns a @ref{ed6,,Server} object.

Arguments:


@itemize *

@item 
`protocol_factory' must be a callable returning a
@ref{3ad6,,protocol} implementation.

@item 
The `host' parameter can be set to several types which determine where
the server would be listening:


@itemize -

@item 
If `host' is a string, the TCP server is bound to a single network
interface specified by `host'.

@item 
If `host' is a sequence of strings, the TCP server is bound to all
network interfaces specified by the sequence.

@item 
If `host' is an empty string or @code{None}, all interfaces are
assumed and a list of multiple sockets will be returned (most likely
one for IPv4 and another one for IPv6).
@end itemize

@item 
The `port' parameter can be set to specify which port the server should
listen on. If @code{0} or @code{None} (the default), a random unused port will
be selected (note that if `host' resolves to multiple network interfaces,
a different random port will be selected for each interface).

@item 
`family' can be set to either @ref{1da7,,socket.AF_INET} or
@ref{1da8,,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{3ade,,AF_UNSPEC}).

@item 
`flags' is a bitmask for @ref{fd3,,getaddrinfo()}.

@item 
`sock' can optionally be specified in order to use a preexisting
socket object. If specified, `host' and `port' must not be specified.

@cartouche
@quotation Σημείωση 
The `sock' argument transfers ownership of the socket to the
server created. To close the socket, call the server’s
@ref{3a41,,close()} method.
@end quotation
@end cartouche

@item 
`backlog' is the maximum number of queued connections passed to
@ref{120f,,listen()} (defaults to 100).

@item 
`ssl' can be set to an @ref{336,,SSLContext} instance to enable
TLS over the accepted connections.

@item 
`reuse_address' tells the kernel to reuse a local socket in
@code{TIME_WAIT} state, without waiting for its natural timeout to
expire. If not specified will automatically be set to @code{True} on
Unix.

@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.

@item 
`keep_alive' set to @code{True} keeps connections active by enabling the
periodic transmission of messages.
@end itemize


Άλλαξε στην έκδοση 3.13: Added the `keep_alive' parameter.



@itemize *

@item 
`ssl_handshake_timeout' is (for a TLS server) the time in seconds to wait
for the TLS handshake to complete before aborting the connection.
@code{60.0} seconds if @code{None} (default).

@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).

@item 
`start_serving' set to @code{True} (the default) causes the created server
to start accepting connections immediately.  When set to @code{False},
the user should await on @ref{ed8,,Server.start_serving()} or
@ref{ed9,,Server.serve_forever()} to make the server to start accepting
connections.
@end itemize


Άλλαξε στην έκδοση 3.5: Added support for SSL/TLS in @ref{9fe,,ProactorEventLoop}.



Άλλαξε στην έκδοση 3.5.1: The `host' parameter can be a sequence of strings.



Άλλαξε στην έκδοση 3.6: Added `ssl_handshake_timeout' and `start_serving' parameters.
The socket option @ref{f32,,socket.TCP_NODELAY} is set by default
for all TCP connections.



Άλλαξε στην έκδοση 3.11: Added the `ssl_shutdown_timeout' parameter.



@subsubheading Δείτε επίσης


The @ref{edd,,start_server()} function is a higher-level alternative API
that returns a pair of @ref{194a,,StreamReader} and @ref{1c76,,StreamWriter}
that can be used in an async/await code.

@end deffn

@geindex create_unix_server() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop create_unix_server}@anchor{6d0}
@deffn {Μέθοδος} async 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{ed7,,loop.create_server()} but works with the
@ref{1daa,,AF_UNIX} socket family.

`path' is the name of a Unix domain socket, and is required,
unless a `sock' argument is provided.  Abstract Unix sockets,
@ref{1df,,str}, @ref{1c7,,bytes}, and @ref{4ee,,Path} paths
are supported.

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.

See the documentation of the @ref{ed7,,loop.create_server()} method
for information about arguments to this method.

@ref{232d,,Διαθεσιμότητα}: Unix.


Άλλαξε στην έκδοση 3.7: Added the `ssl_handshake_timeout' and `start_serving' parameters.
The `path' parameter can now be a @ref{4ee,,Path} object.



Άλλαξε στην έκδοση 3.11: Added the `ssl_shutdown_timeout' parameter.



Άλλαξε στην έκδοση 3.13: Added the `cleanup_socket' parameter.

@end deffn

@geindex connect_accepted_socket() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop connect_accepted_socket}@anchor{bbb}
@deffn {Μέθοδος} async loop.connect_accepted_socket (protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Wrap an already accepted connection into a transport/protocol pair.

This method can be used by servers that accept connections outside
of asyncio but that use asyncio to handle them.

Parameters:


@itemize *

@item 
`protocol_factory' must be a callable returning a
@ref{3ad6,,protocol} implementation.

@item 
`sock' is a preexisting socket object returned from
@ref{115b,,socket.accept}.

@cartouche
@quotation Σημείωση 
The `sock' argument transfers ownership of the socket to the
transport created. To close the socket, call the transport’s
@ref{3ada,,close()} method.
@end quotation
@end cartouche

@item 
`ssl' can be set to an @ref{336,,SSLContext} to enable SSL over
the accepted connections.

@item 
`ssl_handshake_timeout' is (for an SSL connection) the time in seconds to
wait for the SSL handshake to complete before aborting the connection.
@code{60.0} seconds if @code{None} (default).

@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

Returns a @code{(transport, protocol)} pair.


Added in version 3.5.3.



Άλλαξε στην έκδοση 3.7: Added the `ssl_handshake_timeout' parameter.



Άλλαξε στην έκδοση 3.11: Added the `ssl_shutdown_timeout' parameter.

@end deffn

@node Transferring files,TLS upgrade,Creating network servers,Event loop methods
@anchor{library/asyncio-eventloop transferring-files}@anchor{3adf}
@subsubsection Transferring files


@geindex sendfile() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sendfile}@anchor{3ae0}
@deffn {Μέθοδος} async loop.sendfile (transport, file, offset=0, count=None, *, fallback=True)

Send a `file' over a `transport'.  Return the total number of bytes
sent.

The method uses high-performance @ref{ed3,,os.sendfile()} if available.

`file' must be a regular file object opened in binary mode.

`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 always updated,
even when this method raises an error, and
@ref{174f,,file.tell()} can be used to obtain the actual
number of bytes sent.

`fallback' set to @code{True} makes asyncio to manually read and send
the file when the platform does not support the sendfile system call
(e.g. Windows or SSL socket on Unix).

Raise @ref{3ab6,,SendfileNotAvailableError} if the system does not support
the `sendfile' syscall and `fallback' is @code{False}.


Added in version 3.7.

@end deffn

@node TLS upgrade,Watching file descriptors,Transferring files,Event loop methods
@anchor{library/asyncio-eventloop tls-upgrade}@anchor{3ae1}
@subsubsection TLS upgrade


@geindex start_tls() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop start_tls}@anchor{ecd}
@deffn {Μέθοδος} async loop.start_tls (transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Upgrade an existing transport-based connection to TLS.

Create a TLS coder/decoder instance and insert it between the `transport'
and the `protocol'. The coder/decoder implements both `transport'-facing
protocol and `protocol'-facing transport.

Return the created two-interface instance. After `await', the `protocol'
must stop using the original `transport' and communicate with the returned
object only because the coder caches `protocol'-side data and sporadically
exchanges extra TLS session packets with `transport'.

In some situations (e.g. when the passed transport is already closing) this
may return @code{None}.

Parameters:


@itemize *

@item 
`transport' and `protocol' instances that methods like
@ref{ed7,,create_server()} and
@ref{9f9,,create_connection()} return.

@item 
`sslcontext': a configured instance of @ref{336,,SSLContext}.

@item 
`server_side' pass @code{True} when a server-side connection is being
upgraded (like the one created by @ref{ed7,,create_server()}).

@item 
`server_hostname': sets or overrides the host name that the target
server’s certificate will be matched against.

@item 
`ssl_handshake_timeout' is (for a TLS connection) the time in seconds to
wait for the TLS handshake to complete before aborting the connection.
@code{60.0} seconds if @code{None} (default).

@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


Added in version 3.7.



Άλλαξε στην έκδοση 3.11: Added the `ssl_shutdown_timeout' parameter.

@end deffn

@node Watching file descriptors,Working with socket objects directly,TLS upgrade,Event loop methods
@anchor{library/asyncio-eventloop watching-file-descriptors}@anchor{3ae2}
@subsubsection Watching file descriptors


@geindex add_reader() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop add_reader}@anchor{3a5e}
@deffn {Μέθοδος} loop.add_reader (fd, callback, *args)

Start monitoring the `fd' file descriptor for read availability and
invoke `callback' with the specified arguments once `fd' is available for
reading.

Any preexisting callback registered for `fd' is cancelled and replaced by
`callback'.
@end deffn

@geindex remove_reader() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop remove_reader}@anchor{3ae3}
@deffn {Μέθοδος} loop.remove_reader (fd)

Stop monitoring the `fd' file descriptor for read availability. Returns
@code{True} if `fd' was previously being monitored for reads.
@end deffn

@geindex add_writer() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop add_writer}@anchor{3ae4}
@deffn {Μέθοδος} loop.add_writer (fd, callback, *args)

Start monitoring the `fd' file descriptor for write availability and
invoke `callback' with the specified arguments `args' once `fd' is
available for writing.

Any preexisting callback registered for `fd' is cancelled and replaced by
`callback'.

Use @ref{4a6,,functools.partial()} @ref{3ad0,,to pass keyword arguments} to `callback'.
@end deffn

@geindex remove_writer() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop remove_writer}@anchor{3ae5}
@deffn {Μέθοδος} loop.remove_writer (fd)

Stop monitoring the `fd' file descriptor for write availability. Returns
@code{True} if `fd' was previously being monitored for writes.
@end deffn

See also @ref{3ae6,,Platform Support} section
for some limitations of these methods.

@node Working with socket objects directly,DNS,Watching file descriptors,Event loop methods
@anchor{library/asyncio-eventloop working-with-socket-objects-directly}@anchor{3ae7}
@subsubsection Working with socket objects directly


In general, protocol implementations that use transport-based APIs
such as @ref{9f9,,loop.create_connection()} and @ref{ed7,,loop.create_server()}
are faster than implementations that work with sockets directly.
However, there are some use cases when performance is not critical, and
working with @ref{115a,,socket} objects directly is more
convenient.

@geindex sock_recv() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_recv}@anchor{fd0}
@deffn {Μέθοδος} async loop.sock_recv (sock, nbytes)

Receive up to `nbytes' from `sock'.  Asynchronous version of
@ref{115d,,socket.recv()}.

Return the received data as a bytes object.

`sock' must be a non-blocking socket.


Άλλαξε στην έκδοση 3.7: Even though this method was always documented as a coroutine
method, releases before Python 3.7 returned a @ref{f8b,,Future}.
Since Python 3.7 this is an @code{async def} method.

@end deffn

@geindex sock_recv_into() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_recv_into}@anchor{ece}
@deffn {Μέθοδος} async loop.sock_recv_into (sock, buf)

Receive data from `sock' into the `buf' buffer.  Modeled after the blocking
@ref{16c2,,socket.recv_into()} method.

Return the number of bytes written to the buffer.

`sock' must be a non-blocking socket.


Added in version 3.7.

@end deffn

@geindex sock_recvfrom() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_recvfrom}@anchor{9fc}
@deffn {Μέθοδος} async loop.sock_recvfrom (sock, bufsize)

Receive a datagram of up to `bufsize' from `sock'.  Asynchronous version of
@ref{115e,,socket.recvfrom()}.

Return a tuple of (received data, remote address).

`sock' must be a non-blocking socket.


Added in version 3.11.

@end deffn

@geindex sock_recvfrom_into() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_recvfrom_into}@anchor{9fd}
@deffn {Μέθοδος} async loop.sock_recvfrom_into (sock, buf, nbytes=0)

Receive a datagram of up to `nbytes' from `sock' into `buf'.
Asynchronous version of
@ref{16c3,,socket.recvfrom_into()}.

Return a tuple of (number of bytes received, remote address).

`sock' must be a non-blocking socket.


Added in version 3.11.

@end deffn

@geindex sock_sendall() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_sendall}@anchor{fd1}
@deffn {Μέθοδος} async loop.sock_sendall (sock, data)

Send `data' to the `sock' socket. Asynchronous version of
@ref{1161,,socket.sendall()}.

This method continues to send to the socket until either all data
in `data' has been sent or an error occurs.  @code{None} is returned
on success.  On error, an exception is raised. Additionally, there is no way
to determine how much data, if any, was successfully processed by the
receiving end of the connection.

`sock' must be a non-blocking socket.


Άλλαξε στην έκδοση 3.7: Even though the method was always documented as a coroutine
method, before Python 3.7 it returned a @ref{f8b,,Future}.
Since Python 3.7, this is an @code{async def} method.

@end deffn

@geindex sock_sendto() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_sendto}@anchor{9fb}
@deffn {Μέθοδος} async loop.sock_sendto (sock, data, address)

Send a datagram from `sock' to `address'.
Asynchronous version of
@ref{1162,,socket.sendto()}.

Return the number of bytes sent.

`sock' must be a non-blocking socket.


Added in version 3.11.

@end deffn

@geindex sock_connect() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_connect}@anchor{1181}
@deffn {Μέθοδος} async loop.sock_connect (sock, address)

Connect `sock' to a remote socket at `address'.

Asynchronous version of @ref{115c,,socket.connect()}.

`sock' must be a non-blocking socket.


Άλλαξε στην έκδοση 3.5.2: @code{address} no longer needs to be resolved.  @code{sock_connect}
will try to check if the `address' is already resolved by calling
@ref{d2c,,socket.inet_pton()}.  If not,
@ref{fd3,,loop.getaddrinfo()} will be used to resolve the
`address'.



@subsubheading Δείτε επίσης


@ref{9f9,,loop.create_connection()}
and  @ref{edc,,asyncio.open_connection()}.

@end deffn

@geindex sock_accept() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_accept}@anchor{fd2}
@deffn {Μέθοδος} async loop.sock_accept (sock)

Accept a connection.  Modeled after the blocking
@ref{115b,,socket.accept()} method.

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.

`sock' must be a non-blocking socket.


Άλλαξε στην έκδοση 3.7: Even though the method was always documented as a coroutine
method, before Python 3.7 it returned a @ref{f8b,,Future}.
Since Python 3.7, this is an @code{async def} method.



@subsubheading Δείτε επίσης


@ref{ed7,,loop.create_server()} and @ref{edd,,start_server()}.

@end deffn

@geindex sock_sendfile() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_sendfile}@anchor{ed2}
@deffn {Μέθοδος} async loop.sock_sendfile (sock, file, offset=0, count=None, *, fallback=True)

Send a file using high-performance @ref{ed3,,os.sendfile} if possible.
Return the total number of bytes sent.

Asynchronous version of @ref{120e,,socket.sendfile()}.

`sock' must be a non-blocking @ref{1698,,socket.SOCK_STREAM}
@ref{115a,,socket}.

`file' must be a regular file object open in binary mode.

`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 always updated,
even when this method raises an error, and
@ref{174f,,file.tell()} can be used to obtain the actual
number of bytes sent.

`fallback', when set to @code{True}, makes asyncio manually read and send
the file when the platform does not support the sendfile syscall
(e.g. Windows or SSL socket on Unix).

Raise @ref{3ab6,,SendfileNotAvailableError} if the system does not support
`sendfile' syscall and `fallback' is @code{False}.

`sock' must be a non-blocking socket.


Added in version 3.7.

@end deffn

@node DNS,Working with pipes,Working with socket objects directly,Event loop methods
@anchor{library/asyncio-eventloop dns}@anchor{3ae8}
@subsubsection DNS


@geindex getaddrinfo() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop getaddrinfo}@anchor{fd3}
@deffn {Μέθοδος} async loop.getaddrinfo (host, port, *, family=0, type=0, proto=0, flags=0)

Asynchronous version of @ref{1925,,socket.getaddrinfo()}.
@end deffn

@geindex getnameinfo() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop getnameinfo}@anchor{fd4}
@deffn {Μέθοδος} async loop.getnameinfo (sockaddr, flags=0)

Asynchronous version of @ref{1c42,,socket.getnameinfo()}.
@end deffn

@cartouche
@quotation Σημείωση 
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


Άλλαξε στην έκδοση 3.7: Both `getaddrinfo' and `getnameinfo' methods were always documented
to return a coroutine, but prior to Python 3.7 they were, in fact,
returning @ref{f8b,,asyncio.Future} objects.  Starting with Python 3.7
both methods are coroutines.


@node Working with pipes,Unix signals,DNS,Event loop methods
@anchor{library/asyncio-eventloop working-with-pipes}@anchor{3ae9}
@subsubsection Working with pipes


@geindex connect_read_pipe() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop connect_read_pipe}@anchor{3a8a}
@deffn {Μέθοδος} async loop.connect_read_pipe (protocol_factory, pipe)

Register the read end of `pipe' in the event loop.

`protocol_factory' must be a callable returning an
@ref{3ad6,,asyncio protocol} implementation.

`pipe' is a @ref{156c,,file-like object}.

Return pair @code{(transport, protocol)}, where `transport' supports
the @ref{3aea,,ReadTransport} interface and `protocol' is an object
instantiated by the `protocol_factory'.

With @ref{30b,,SelectorEventLoop} event loop, the `pipe' is set to
non-blocking mode.
@end deffn

@geindex connect_write_pipe() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop connect_write_pipe}@anchor{3a8b}
@deffn {Μέθοδος} async loop.connect_write_pipe (protocol_factory, pipe)

Register the write end of `pipe' in the event loop.

`protocol_factory' must be a callable returning an
@ref{3ad6,,asyncio protocol} implementation.

`pipe' is @ref{156c,,file-like object}.

Return pair @code{(transport, protocol)}, where `transport' supports
@ref{3aeb,,WriteTransport} interface and `protocol' is an object
instantiated by the `protocol_factory'.

With @ref{30b,,SelectorEventLoop} event loop, the `pipe' is set to
non-blocking mode.
@end deffn

@cartouche
@quotation Σημείωση 
@ref{30b,,SelectorEventLoop} does not support the above methods on
Windows.  Use @ref{9fe,,ProactorEventLoop} instead for Windows.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης


The @ref{3a87,,loop.subprocess_exec()} and
@ref{3a88,,loop.subprocess_shell()} methods.


@node Unix signals,Executing code in thread or process pools,Working with pipes,Event loop methods
@anchor{library/asyncio-eventloop unix-signals}@anchor{3aec}
@subsubsection Unix signals


@geindex add_signal_handler() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop loop-add-signal-handler}@anchor{3a04}@anchor{library/asyncio-eventloop asyncio loop add_signal_handler}@anchor{3aed}
@deffn {Μέθοδος} loop.add_signal_handler (signum, callback, *args)

Set `callback' as the handler for the `signum' signal,
passing `args' as positional arguments.

The callback will be invoked by `loop', along with other queued callbacks
and runnable coroutines of that event loop. Unlike signal handlers
registered using @ref{14e0,,signal.signal()}, a callback registered with this
function is allowed to interact with the event loop.

Raise @ref{277,,ValueError} if the signal number is invalid or uncatchable.
Raise @ref{30d,,RuntimeError} if there is a problem setting up the handler.

Use @ref{4a6,,functools.partial()} @ref{3ad0,,to pass keyword arguments} to `callback'.

Like @ref{14e0,,signal.signal()}, this function must be invoked in the main
thread.
@end deffn

@geindex remove_signal_handler() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop remove_signal_handler}@anchor{3aee}
@deffn {Μέθοδος} loop.remove_signal_handler (sig)

Remove the handler for the `sig' signal.

Return @code{True} if the signal handler was removed, or @code{False} if
no handler was set for the given signal.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn


@subsubheading Δείτε επίσης


The @ref{ce,,signal} module.


@node Executing code in thread or process pools,Error handling API,Unix signals,Event loop methods
@anchor{library/asyncio-eventloop executing-code-in-thread-or-process-pools}@anchor{3aef}
@subsubsection Executing code in thread or process pools


@geindex run_in_executor() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop run_in_executor}@anchor{cba}
@deffn {Μέθοδος} awaitable loop.run_in_executor (executor, func, *args)

Arrange for `func' to be called in the specified executor
passing `args' as positional arguments.

The `executor' argument should be an @ref{3928,,concurrent.futures.Executor}
instance. The default executor is used if `executor' is @code{None}.
The default executor can be set by @ref{b28,,loop.set_default_executor()},
otherwise, a @ref{b27,,concurrent.futures.ThreadPoolExecutor} will be
lazy-initialized and used by @ref{cba,,run_in_executor()} if needed.

Example:

@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)

    # 4. Run in a custom interpreter pool:
    with concurrent.futures.InterpreterPoolExecutor() as pool:
        result = await loop.run_in_executor(
            pool, cpu_bound)
        print('custom interpreter pool', result)

if __name__ == '__main__':
    asyncio.run(main())
@end example

Note that the entry point guard (@code{if __name__ == '__main__'})
is required for option 3 due to the peculiarities of @ref{98,,multiprocessing},
which is used by @ref{206,,ProcessPoolExecutor}.
See @ref{3911,,Safe importing of main module}.

This method returns a @ref{f8b,,asyncio.Future} object.

Use @ref{4a6,,functools.partial()} @ref{3ad0,,to pass keyword arguments} to `func'.


Άλλαξε στην έκδοση 3.5.3: @code{loop.run_in_executor()} no longer configures the
@code{max_workers} of the thread pool executor it creates, instead
leaving it up to the thread pool executor
(@ref{b27,,ThreadPoolExecutor}) to set the
default.

@end deffn

@geindex set_default_executor() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop set_default_executor}@anchor{b28}
@deffn {Μέθοδος} loop.set_default_executor (executor)

Set `executor' as the default executor used by @ref{cba,,run_in_executor()}.
`executor' must be an instance of
@ref{b27,,ThreadPoolExecutor}, which includes
@ref{46a,,InterpreterPoolExecutor}.


Άλλαξε στην έκδοση 3.11: `executor' must be an instance of
@ref{b27,,ThreadPoolExecutor}.

@end deffn

@node Error handling API,Enabling debug mode,Executing code in thread or process pools,Event loop methods
@anchor{library/asyncio-eventloop error-handling-api}@anchor{3af0}
@subsubsection Error handling API


Allows customizing how exceptions are handled in the event loop.

@geindex set_exception_handler() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop set_exception_handler}@anchor{3af1}
@deffn {Μέθοδος} loop.set_exception_handler (handler)

Set `handler' as the new event loop exception handler.

If `handler' is @code{None}, the default exception handler will
be set.  Otherwise, `handler' must be a callable with the signature
matching @code{(loop, context)}, where @code{loop}
is a reference to the active event loop, and @code{context}
is a @code{dict} object containing the details of the exception
(see @ref{3af2,,call_exception_handler()} documentation for details
about context).

If the handler is called on behalf of a @ref{460,,Task} or
@ref{2071,,Handle}, it is run in the
@ref{421,,contextvars.Context} of that task or callback handle.


Άλλαξε στην έκδοση 3.12: The handler may be called in the @ref{421,,Context}
of the task or handle where the exception originated.

@end deffn

@geindex get_exception_handler() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop get_exception_handler}@anchor{1039}
@deffn {Μέθοδος} loop.get_exception_handler ()

Return the current exception handler, or @code{None} if no custom
exception handler was set.


Added in version 3.5.2.

@end deffn

@geindex default_exception_handler() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop default_exception_handler}@anchor{3af3}
@deffn {Μέθοδος} loop.default_exception_handler (context)

Default exception handler.

This is called when an exception occurs and no exception
handler is set. This can be called by a custom exception
handler that wants to defer to the default handler behavior.

`context' parameter has the same meaning as in
@ref{3af2,,call_exception_handler()}.
@end deffn

@geindex call_exception_handler() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop call_exception_handler}@anchor{3af2}
@deffn {Μέθοδος} loop.call_exception_handler (context)

Call the current event loop exception handler.

`context' is a @code{dict} object containing the following keys
(new keys may be introduced in future Python versions):


@itemize *

@item 
“message”: Error message;

@item 
“exception” (optional): Exception object;

@item 
“future” (optional): @ref{f8b,,asyncio.Future} instance;

@item 
“task” (optional): @ref{460,,asyncio.Task} instance;

@item 
“handle” (optional): @ref{2071,,asyncio.Handle} instance;

@item 
“protocol” (optional): @ref{3ad6,,Protocol} instance;

@item 
“transport” (optional): @ref{3ad7,,Transport} instance;

@item 
“socket” (optional): @ref{115a,,socket.socket} instance;

@item 
“source_traceback” (optional): Traceback of the source;

@item 
“handle_traceback” (optional): Traceback of the handle;

@item 

@table @asis

@item “asyncgen” (optional): Asynchronous generator that caused

the exception.
@end table
@end itemize

@cartouche
@quotation Σημείωση 
This method should not be overloaded in subclassed
event loops.  For custom exception handling, use
the @ref{3af1,,set_exception_handler()} method.
@end quotation
@end cartouche
@end deffn

@node Enabling debug mode,Running subprocesses,Error handling API,Event loop methods
@anchor{library/asyncio-eventloop enabling-debug-mode}@anchor{3af4}
@subsubsection Enabling debug mode


@geindex get_debug() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop get_debug}@anchor{117b}
@deffn {Μέθοδος} loop.get_debug ()

Get the debug mode (@ref{5ef,,bool}) of the event loop.

The default value is @code{True} if the environment variable
@geindex PYTHONASYNCIODEBUG
@geindex μεταβλητή περιβάλλοντος; PYTHONASYNCIODEBUG
@ref{2327,,PYTHONASYNCIODEBUG} is set to a non-empty string, @code{False}
otherwise.
@end deffn

@geindex set_debug() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop set_debug}@anchor{117a}
@deffn {Μέθοδος} loop.set_debug (enabled: bool)

Set the debug mode of the event loop.


Άλλαξε στην έκδοση 3.7: The new @ref{70d,,Python Development Mode} can now also be used
to enable the debug mode.

@end deffn

@geindex slow_callback_duration (ιδιότητα της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop slow_callback_duration}@anchor{3af5}
@deffn {Ιδιότητα} 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 Δείτε επίσης


The @ref{2328,,debug mode of asyncio}.


@node Running subprocesses,,Enabling debug mode,Event loop methods
@anchor{library/asyncio-eventloop running-subprocesses}@anchor{3af6}
@subsubsection Running subprocesses


Methods described in this subsections are low-level.  In regular
async/await code consider using the high-level
@ref{e3b,,asyncio.create_subprocess_shell()} and
@ref{e3a,,asyncio.create_subprocess_exec()} convenience functions instead.

@cartouche
@quotation Σημείωση 
On Windows, the default event loop @ref{9fe,,ProactorEventLoop} supports
subprocesses, whereas @ref{30b,,SelectorEventLoop} does not. See
@ref{3a89,,Subprocess Support on Windows} for
details.
@end quotation
@end cartouche

@geindex subprocess_exec() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop loop-subprocess-exec}@anchor{3a03}@anchor{library/asyncio-eventloop asyncio loop subprocess_exec}@anchor{3a87}
@deffn {Μέθοδος} async loop.subprocess_exec (protocol_factory, *args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

Create a subprocess from one or more string arguments specified by
`args'.

`args' must be a list of strings represented by:


@itemize *

@item 
@ref{1df,,str};

@item 
or @ref{1c7,,bytes}, encoded to the
@ref{2e50,,filesystem encoding}.
@end itemize

The first string specifies the program executable,
and the remaining strings specify the arguments.  Together, string
arguments form the @code{argv} of the program.

This is similar to the standard library @ref{6bf,,subprocess.Popen}
class called with @code{shell=False} and the list of strings passed as
the first argument; however, where @code{Popen} takes
a single argument which is list of strings, `subprocess_exec'
takes multiple string arguments.

The `protocol_factory' must be a callable returning a subclass of the
@ref{3af7,,asyncio.SubprocessProtocol} class.

Other parameters:


@itemize *

@item 
`stdin' can be any of these:


@itemize *

@item 
a file-like object

@item 
an existing file descriptor (a positive integer), for example those created with @ref{1d62,,os.pipe()}

@item 
the @ref{f46,,subprocess.PIPE} constant (default) which will create a new
pipe and connect it,

@item 
the value @code{None} which will make the subprocess inherit the file
descriptor from this process

@item 
the @ref{14f9,,subprocess.DEVNULL} constant which indicates that the
special @ref{2002,,os.devnull} file will be used
@end itemize

@item 
`stdout' can be any of these:


@itemize *

@item 
a file-like object

@item 
the @ref{f46,,subprocess.PIPE} constant (default) which will create a new
pipe and connect it,

@item 
the value @code{None} which will make the subprocess inherit the file
descriptor from this process

@item 
the @ref{14f9,,subprocess.DEVNULL} constant which indicates that the
special @ref{2002,,os.devnull} file will be used
@end itemize

@item 
`stderr' can be any of these:


@itemize *

@item 
a file-like object

@item 
the @ref{f46,,subprocess.PIPE} constant (default) which will create a new
pipe and connect it,

@item 
the value @code{None} which will make the subprocess inherit the file
descriptor from this process

@item 
the @ref{14f9,,subprocess.DEVNULL} constant which indicates that the
special @ref{2002,,os.devnull} file will be used

@item 
the @ref{3973,,subprocess.STDOUT} constant which will connect the standard
error stream to the process” standard output stream
@end itemize

@item 
All other keyword arguments are passed to @ref{6bf,,subprocess.Popen}
without interpretation, except for `bufsize', `universal_newlines',
`shell', `text', `encoding' and `errors', which should not be specified
at all.

The @code{asyncio} subprocess API does not support decoding the streams
as text. @ref{ca8,,bytes.decode()} can be used to convert the bytes returned
from the stream to text.
@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{3a8b,,connect_write_pipe()} or @ref{3a8a,,connect_read_pipe()} for use
with the event loop.

See the constructor of the @ref{6bf,,subprocess.Popen} class
for documentation on other arguments.

Returns a pair of @code{(transport, protocol)}, where `transport'
conforms to the @ref{3af8,,asyncio.SubprocessTransport} base class and
`protocol' is an object instantiated by the `protocol_factory'.

If the transport is closed or is garbage collected, the child process
is killed if it is still running.
@end deffn

@geindex subprocess_shell() (μέθοδος της asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop subprocess_shell}@anchor{3a88}
@deffn {Μέθοδος} async loop.subprocess_shell (protocol_factory, cmd, *, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

Create a subprocess from `cmd', which can be a @ref{1df,,str} or a
@ref{1c7,,bytes} string encoded to the
@ref{2e50,,filesystem encoding},
using the platform’s «shell» syntax.

This is similar to the standard library @ref{6bf,,subprocess.Popen}
class called with @code{shell=True}.

The `protocol_factory' must be a callable returning a subclass of the
@ref{3af7,,SubprocessProtocol} class.

See @ref{3a87,,subprocess_exec()} for more details about
the remaining arguments.

Returns a pair of @code{(transport, protocol)}, where `transport'
conforms to the @ref{3af8,,SubprocessTransport} base class and
`protocol' is an object instantiated by the `protocol_factory'.

If the transport is closed or is garbage collected, the child process
is killed if it is still running.
@end deffn

@cartouche
@quotation Σημείωση 
It is the application’s responsibility to ensure that all whitespace
and special characters are quoted appropriately to avoid shell injection@footnote{https://en.wikipedia.org/wiki/Shell_injection#Shell_injection}
vulnerabilities. The @ref{781,,shlex.quote()} function can be used to
properly escape whitespace and special characters in strings that
are going to be used to construct shell commands.
@end quotation
@end cartouche

@node Callback handles,Server objects,Event loop methods,Event loop
@anchor{library/asyncio-eventloop callback-handles}@anchor{3ac6}
@subsubsection Callback handles


@geindex Handle (κλάση σε asyncio)
@anchor{library/asyncio-eventloop asyncio Handle}@anchor{2071}
@deffn {Κλάση} asyncio.Handle

A callback wrapper object returned by @ref{ec8,,loop.call_soon()},
@ref{ec9,,loop.call_soon_threadsafe()}.

@geindex get_context() (μέθοδος της asyncio.Handle)
@anchor{library/asyncio-eventloop asyncio Handle get_context}@anchor{3af9}
@deffn {Μέθοδος} get_context ()

Return the @ref{421,,contextvars.Context} object
associated with the handle.


Added in version 3.12.

@end deffn

@geindex cancel() (μέθοδος της asyncio.Handle)
@anchor{library/asyncio-eventloop asyncio Handle cancel}@anchor{3afa}
@deffn {Μέθοδος} cancel ()

Cancel the callback.  If the callback has already been canceled
or executed, this method has no effect.
@end deffn

@geindex cancelled() (μέθοδος της asyncio.Handle)
@anchor{library/asyncio-eventloop asyncio Handle cancelled}@anchor{ede}
@deffn {Μέθοδος} cancelled ()

Return @code{True} if the callback was cancelled.


Added in version 3.7.

@end deffn
@end deffn

@geindex TimerHandle (κλάση σε asyncio)
@anchor{library/asyncio-eventloop asyncio TimerHandle}@anchor{1cdc}
@deffn {Κλάση} asyncio.TimerHandle

A callback wrapper object returned by @ref{eca,,loop.call_later()},
and @ref{ecb,,loop.call_at()}.

This class is a subclass of @ref{2071,,Handle}.

@geindex when() (μέθοδος της asyncio.TimerHandle)
@anchor{library/asyncio-eventloop asyncio TimerHandle when}@anchor{edb}
@deffn {Μέθοδος} when ()

Return a scheduled callback time as @ref{327,,float} seconds.

The time is an absolute timestamp, using the same time
reference as @ref{3ad3,,loop.time()}.


Added in version 3.7.

@end deffn
@end deffn

@node Server objects,Event loop implementations,Callback handles,Event loop
@anchor{library/asyncio-eventloop server-objects}@anchor{3ac7}
@subsubsection Server objects


Server objects are created by @ref{ed7,,loop.create_server()},
@ref{6d0,,loop.create_unix_server()}, @ref{edd,,start_server()},
and @ref{3a44,,start_unix_server()} functions.

Do not instantiate the @ref{ed6,,Server} class directly.

@geindex Server (κλάση σε asyncio)
@anchor{library/asyncio-eventloop asyncio Server}@anchor{ed6}
@deffn {Κλάση} asyncio.Server

`Server' objects are asynchronous context managers.  When used in an
@code{async with} statement, it’s guaranteed that the Server object is
closed and not accepting new connections when the @code{async with}
statement is completed:

@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


Άλλαξε στην έκδοση 3.7: Server object is an asynchronous context manager since Python 3.7.



Άλλαξε στην έκδοση 3.11: This class was exposed publicly as @code{asyncio.Server} in Python 3.9.11, 3.10.3 and 3.11.


@geindex close() (μέθοδος της asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server close}@anchor{3a41}
@deffn {Μέθοδος} close ()

Stop serving: close listening sockets and set the @ref{fd5,,sockets}
attribute to @code{None}.

The sockets that represent existing incoming client connections
are left open.

The server is closed asynchronously; use the @ref{1c46,,wait_closed()}
coroutine to wait until the server is closed (and no more
connections are active).
@end deffn

@geindex close_clients() (μέθοδος της asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server close_clients}@anchor{6d4}
@deffn {Μέθοδος} close_clients ()

Close all existing incoming client connections.

Calls @ref{3ada,,close()} on all associated
transports.

@ref{3a41,,close()} should be called before @code{close_clients()} when
closing the server to avoid races with new clients connecting.


Added in version 3.13.

@end deffn

@geindex abort_clients() (μέθοδος της asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server abort_clients}@anchor{6d5}
@deffn {Μέθοδος} abort_clients ()

Close all existing incoming client connections immediately,
without waiting for pending operations to complete.

Calls @ref{3afb,,abort()} on all associated
transports.

@ref{3a41,,close()} should be called before @code{abort_clients()} when
closing the server to avoid races with new clients connecting.


Added in version 3.13.

@end deffn

@geindex get_loop() (μέθοδος της asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server get_loop}@anchor{ed5}
@deffn {Μέθοδος} get_loop ()

Return the event loop associated with the server object.


Added in version 3.7.

@end deffn

@geindex start_serving() (μέθοδος της asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server start_serving}@anchor{ed8}
@deffn {Μέθοδος} async start_serving ()

Start accepting connections.

This method is idempotent, so it can be called when
the server is already serving.

The `start_serving' keyword-only parameter to
@ref{ed7,,loop.create_server()} and
@ref{edd,,asyncio.start_server()} allows creating a Server object
that is not accepting connections initially.  In this case
@code{Server.start_serving()}, or @ref{ed9,,Server.serve_forever()} can be used
to make the Server start accepting connections.


Added in version 3.7.

@end deffn

@geindex serve_forever() (μέθοδος της asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server serve_forever}@anchor{ed9}
@deffn {Μέθοδος} async serve_forever ()

Start accepting connections until the coroutine is cancelled.
Cancellation of @code{serve_forever} task causes the server
to be closed.

This method can be called if the server is already accepting
connections.  Only one @code{serve_forever} task can exist per
one `Server' object.

Example:

@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


Added in version 3.7.

@end deffn

@geindex is_serving() (μέθοδος της asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server is_serving}@anchor{eda}
@deffn {Μέθοδος} is_serving ()

Return @code{True} if the server is accepting new connections.


Added in version 3.7.

@end deffn

@geindex wait_closed() (μέθοδος της asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server wait_closed}@anchor{1c46}
@deffn {Μέθοδος} async wait_closed ()

Wait until the @ref{3a41,,close()} method completes and all active
connections have finished.
@end deffn

@geindex sockets (ιδιότητα της asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server sockets}@anchor{fd5}
@deffn {Ιδιότητα} sockets

List of socket-like objects, @code{asyncio.trsock.TransportSocket}, which
the server is listening on.


Άλλαξε στην έκδοση 3.7: Prior to Python 3.7 @code{Server.sockets} used to return an
internal list of server sockets directly.  In 3.7 a copy
of that list is returned.

@end deffn
@end deffn
@anchor{library/asyncio-eventloop asyncio-event-loops}@anchor{3afc}
@node Event loop implementations,Examples<15>,Server objects,Event loop
@anchor{library/asyncio-eventloop asyncio-event-loop-implementations}@anchor{3afd}@anchor{library/asyncio-eventloop event-loop-implementations}@anchor{3ac8}
@subsubsection Event loop implementations


asyncio ships with two different event loop implementations:
@ref{30b,,SelectorEventLoop} and @ref{9fe,,ProactorEventLoop}.

By default asyncio is configured to use @ref{1c6d,,EventLoop}.

@geindex SelectorEventLoop (κλάση σε asyncio)
@anchor{library/asyncio-eventloop asyncio SelectorEventLoop}@anchor{30b}
@deffn {Κλάση} asyncio.SelectorEventLoop

A subclass of @ref{d29,,AbstractEventLoop} based on the
@ref{ca,,selectors} module.

Uses the most efficient `selector' available for the given
platform.  It is also possible to manually configure the
exact selector implementation to be used:

@example
import asyncio
import selectors

async def main():
   ...

loop_factory = lambda: asyncio.SelectorEventLoop(selectors.SelectSelector())
asyncio.run(main(), loop_factory=loop_factory)
@end example

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.
@end deffn

@geindex ProactorEventLoop (κλάση σε asyncio)
@anchor{library/asyncio-eventloop asyncio ProactorEventLoop}@anchor{9fe}
@deffn {Κλάση} asyncio.ProactorEventLoop

A subclass of @ref{d29,,AbstractEventLoop} for Windows that uses «I/O Completion Ports» (IOCP).

@ref{232d,,Διαθεσιμότητα}: Windows.


@subsubheading Δείτε επίσης


MSDN documentation on I/O Completion Ports@footnote{https://learn.microsoft.com/windows/win32/fileio/i-o-completion-ports}.

@end deffn

@geindex EventLoop (κλάση σε asyncio)
@anchor{library/asyncio-eventloop asyncio EventLoop}@anchor{1c6d}
@deffn {Κλάση} asyncio.EventLoop

@quotation

An alias to the most efficient available subclass of @ref{d29,,AbstractEventLoop} for the given
platform.

It is an alias to @ref{30b,,SelectorEventLoop} on Unix and @ref{9fe,,ProactorEventLoop} on Windows.
@end quotation


Added in version 3.13.

@end deffn

@geindex AbstractEventLoop (κλάση σε asyncio)
@anchor{library/asyncio-eventloop asyncio AbstractEventLoop}@anchor{d29}
@deffn {Κλάση} asyncio.AbstractEventLoop

Abstract base class for asyncio-compliant event loops.

The @ref{3aca,,Event loop methods} section lists all
methods that an alternative implementation of @code{AbstractEventLoop}
should have defined.
@end deffn

@node Examples<15>,,Event loop implementations,Event loop
@anchor{library/asyncio-eventloop examples}@anchor{3ac9}
@subsubsection Examples


Note that all examples in this section `purposefully' show how
to use the low-level event loop APIs, such as @ref{3acc,,loop.run_forever()}
and @ref{ec8,,loop.call_soon()}.  Modern asyncio applications rarely
need to be written this way; consider using the high-level functions
like @ref{309,,asyncio.run()}.

@menu
* Hello World with call_soon(): Hello World with call_soon. 
* Display the current date with call_later(): Display the current date with call_later. 
* Watch a file descriptor for read events:: 
* Set signal handlers for SIGINT and SIGTERM:: 

@end menu

@node Hello World with call_soon,Display the current date with call_later,,Examples<15>
@anchor{library/asyncio-eventloop asyncio-example-lowlevel-helloworld}@anchor{3afe}@anchor{library/asyncio-eventloop hello-world-with-call-soon}@anchor{3aff}
@subsubsection Hello World with call_soon()


An example using the @ref{ec8,,loop.call_soon()} method to schedule a
callback. The callback displays @code{"Hello World"} and then stops the
event loop:

@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 Δείτε επίσης


A similar @ref{39fe,,Hello World}
example created with a coroutine and the @ref{309,,run()} function.


@node Display the current date with call_later,Watch a file descriptor for read events,Hello World with call_soon,Examples<15>
@anchor{library/asyncio-eventloop asyncio-example-call-later}@anchor{3b00}@anchor{library/asyncio-eventloop display-the-current-date-with-call-later}@anchor{3b01}
@subsubsection Display the current date with call_later()


An example of a callback displaying the current date every second. The
callback uses the @ref{eca,,loop.call_later()} method to reschedule itself
after 5 seconds, and then stops the event loop:

@example
import asyncio
import datetime as dt

def display_date(end_time, loop):
    print(dt.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 Δείτε επίσης


A similar @ref{3a1b,,current date} example
created with a coroutine and the @ref{309,,run()} function.


@node Watch a file descriptor for read events,Set signal handlers for SIGINT and SIGTERM,Display the current date with call_later,Examples<15>
@anchor{library/asyncio-eventloop asyncio-example-watch-fd}@anchor{3a5d}@anchor{library/asyncio-eventloop watch-a-file-descriptor-for-read-events}@anchor{3b02}
@subsubsection Watch a file descriptor for read events


Wait until a file descriptor received some data using the
@ref{3a5e,,loop.add_reader()} method and then close the event loop:

@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 Δείτε επίσης



@itemize *

@item 
A similar @ref{3a5c,,example}
using transports, protocols, and the
@ref{9f9,,loop.create_connection()} method.

@item 
Another similar @ref{3a5a,,example}
using the high-level @ref{edc,,asyncio.open_connection()} function
and streams.
@end itemize


@node Set signal handlers for SIGINT and SIGTERM,,Watch a file descriptor for read events,Examples<15>
@anchor{library/asyncio-eventloop asyncio-example-unix-signals}@anchor{3b03}@anchor{library/asyncio-eventloop set-signal-handlers-for-sigint-and-sigterm}@anchor{3b04}
@subsubsection Set signal handlers for SIGINT and SIGTERM


(This @code{signal} example only works on Unix.)

Register handlers for signals @ref{4df,,SIGINT} and @ref{1782,,SIGTERM}
using the @ref{3aed,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Futures,Transports and Protocols,Event loop,asyncio — Asynchronous I/O
@anchor{library/asyncio-future doc}@anchor{3929}@anchor{library/asyncio-future asyncio-futures}@anchor{3a06}@anchor{library/asyncio-future futures}@anchor{3b05}@anchor{library/asyncio-future translation-repo}@anchor{3b06}
@subsubsection Futures


`Source code:' Lib/asyncio/futures.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/futures.py},
Lib/asyncio/base_futures.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/base_futures.py}


__________________________________________________________________


`Future' objects are used to bridge `low-level callback-based code'
with high-level async/await code.

@menu
* Future Functions:: 
* Future Object:: 

@end menu

@node Future Functions,Future Object,,Futures
@anchor{library/asyncio-future future-functions}@anchor{3b07}
@subsubsection Future Functions


@geindex isfuture() (στη μονάδα asyncio)
@anchor{library/asyncio-future asyncio isfuture}@anchor{3b08}
@deffn {Συνάρτηση} asyncio.isfuture (obj)

Return @code{True} if `obj' is either of:


@itemize *

@item 
an instance of @ref{f8b,,asyncio.Future},

@item 
an instance of @ref{460,,asyncio.Task},

@item 
a Future-like object with a @code{_asyncio_future_blocking}
attribute.
@end itemize


Added in version 3.5.

@end deffn

@geindex ensure_future() (στη μονάδα asyncio)
@anchor{library/asyncio-future asyncio ensure_future}@anchor{1035}
@deffn {Συνάρτηση} asyncio.ensure_future (obj, *, loop=None)

Return:


@itemize *

@item 
`obj' argument as is, if `obj' is a @ref{f8b,,Future},
a @ref{460,,Task}, or a Future-like object (@ref{3b08,,isfuture()}
is used for the test.)

@item 
a @ref{460,,Task} object wrapping `obj', if `obj' is a
coroutine (@ref{890,,iscoroutine()} is used for the test);
in this case the coroutine will be scheduled by
@code{ensure_future()}.

@item 
a @ref{460,,Task} object that would await on `obj', if `obj' is an
awaitable (@ref{11cb,,inspect.isawaitable()} is used for the test.)
@end itemize

If `obj' is neither of the above a @ref{291,,TypeError} is raised.

@cartouche
@quotation Σημαντικό 
Save a reference to the result of this function, to avoid
a task disappearing mid-execution.

See also the @ref{462,,create_task()} function which is the
preferred way for creating new tasks or use @ref{6d7,,asyncio.TaskGroup}
which keeps reference to the task internally.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.5.1: The function accepts any @ref{6cf,,awaitable} object.



Αποσύρθηκε στην έκδοση 3.10: Deprecation warning is emitted if `obj' is not a Future-like object
and `loop' is not specified and there is no running event loop.

@end deffn

@geindex wrap_future() (στη μονάδα asyncio)
@anchor{library/asyncio-future asyncio wrap_future}@anchor{1e73}
@deffn {Συνάρτηση} asyncio.wrap_future (future, *, loop=None)

Wrap a @ref{155b,,concurrent.futures.Future} object in a
@ref{f8b,,asyncio.Future} object.


Αποσύρθηκε στην έκδοση 3.10: Deprecation warning is emitted if `future' is not a Future-like object
and `loop' is not specified and there is no running event loop.

@end deffn

@node Future Object,,Future Functions,Futures
@anchor{library/asyncio-future asyncio-future-obj}@anchor{3b09}@anchor{library/asyncio-future future-object}@anchor{3b0a}
@subsubsection Future Object


@geindex Future (κλάση σε asyncio)
@anchor{library/asyncio-future asyncio Future}@anchor{f8b}
@deffn {Κλάση} asyncio.Future (*, loop=None)

A Future represents an eventual result of an asynchronous
operation.  Not thread-safe.

Future is an @ref{6cf,,awaitable} object.  Coroutines can await on
Future objects until they either have a result or an exception
set, or until they are cancelled. A Future can be awaited multiple
times and the result is same.

Typically Futures are used to enable low-level
callback-based code (e.g. in protocols implemented using asyncio
@ref{3a05,,transports})
to interoperate with high-level async/await code.

The rule of thumb is to never expose Future objects in user-facing
APIs, and the recommended way to create a Future object is to call
@ref{1038,,loop.create_future()}.  This way alternative event loop
implementations can inject their own optimized implementations
of a Future object.


Άλλαξε στην έκδοση 3.7: Added support for the @ref{28,,contextvars} module.



Αποσύρθηκε στην έκδοση 3.10: Deprecation warning is emitted if `loop' is not specified
and there is no running event loop.


@geindex result() (μέθοδος της asyncio.Future)
@anchor{library/asyncio-future asyncio Future result}@anchor{3b0b}
@deffn {Μέθοδος} result ()

Return the result of the Future.

If the Future is `done' and has a result set by the
@ref{3a31,,set_result()} method, the result value is returned.

If the Future is `done' and has an exception set by the
@ref{103c,,set_exception()} method, this method raises the exception.

If the Future has been `cancelled', this method raises
a @ref{6da,,CancelledError} exception.

If the Future’s result isn’t yet available, this method raises
an @ref{3a34,,InvalidStateError} exception.
@end deffn

@geindex set_result() (μέθοδος της asyncio.Future)
@anchor{library/asyncio-future asyncio Future set_result}@anchor{3a31}
@deffn {Μέθοδος} set_result (result)

Mark the Future as `done' and set its result.

Raises an @ref{3a34,,InvalidStateError} error if the Future is
already `done'.
@end deffn

@geindex set_exception() (μέθοδος της asyncio.Future)
@anchor{library/asyncio-future asyncio Future set_exception}@anchor{103c}
@deffn {Μέθοδος} set_exception (exception)

Mark the Future as `done' and set an exception.

Raises an @ref{3a34,,InvalidStateError} error if the Future is
already `done'.
@end deffn

@geindex done() (μέθοδος της asyncio.Future)
@anchor{library/asyncio-future asyncio Future done}@anchor{3b0c}
@deffn {Μέθοδος} done ()

Return @code{True} if the Future is `done'.

A Future is `done' if it was `cancelled' or if it has a result
or an exception set with @ref{3a31,,set_result()} or
@ref{103c,,set_exception()} calls.
@end deffn

@geindex cancelled() (μέθοδος της asyncio.Future)
@anchor{library/asyncio-future asyncio Future cancelled}@anchor{3b0d}
@deffn {Μέθοδος} cancelled ()

Return @code{True} if the Future was `cancelled'.

The method is usually used to check if a Future is not
`cancelled' before setting a result or an exception for it:

@example
if not fut.cancelled():
    fut.set_result(42)
@end example
@end deffn

@geindex add_done_callback() (μέθοδος της asyncio.Future)
@anchor{library/asyncio-future asyncio Future add_done_callback}@anchor{ecc}
@deffn {Μέθοδος} add_done_callback (callback, *, context=None)

Add a callback to be run when the Future is `done'.

The `callback' is called with the Future object as its only
argument.

If the Future is already `done' when this method is called,
the callback is scheduled with @ref{ec8,,loop.call_soon()}.

An optional keyword-only `context' argument allows specifying a
custom @ref{421,,contextvars.Context} for the `callback' to run in.
The current context is used when no `context' is provided.

@ref{4a6,,functools.partial()} can be used to pass parameters
to the callback, e.g.:

@example
# Call 'print("Future:", fut)' when "fut" is done.
fut.add_done_callback(
    functools.partial(print, "Future:"))
@end example


Άλλαξε στην έκδοση 3.7: The `context' keyword-only parameter was added.
See 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/} for more details.

@end deffn

@geindex remove_done_callback() (μέθοδος της asyncio.Future)
@anchor{library/asyncio-future asyncio Future remove_done_callback}@anchor{1b2c}
@deffn {Μέθοδος} remove_done_callback (callback)

Remove `callback' from the callbacks list.

Returns the number of callbacks removed, which is typically 1,
unless a callback was added more than once.
@end deffn

@geindex cancel() (μέθοδος της asyncio.Future)
@anchor{library/asyncio-future asyncio Future cancel}@anchor{1da3}
@deffn {Μέθοδος} cancel (msg=None)

Cancel the Future and schedule callbacks.

If the Future is already `done' or `cancelled', return @code{False}.
Otherwise, change the Future’s state to `cancelled',
schedule the callbacks, and return @code{True}.

The optional string argument `msg' is passed as the argument to the
@ref{6da,,CancelledError} exception raised when a cancelled Future
is awaited.


Άλλαξε στην έκδοση 3.9: Added the `msg' parameter.

@end deffn

@geindex exception() (μέθοδος της asyncio.Future)
@anchor{library/asyncio-future asyncio Future exception}@anchor{3b0e}
@deffn {Μέθοδος} exception ()

Return the exception that was set on this Future.

The exception (or @code{None} if no exception was set) is
returned only if the Future is `done'.

If the Future has been `cancelled', this method raises a
@ref{6da,,CancelledError} exception.

If the Future isn’t `done' yet, this method raises an
@ref{3a34,,InvalidStateError} exception.
@end deffn

@geindex get_loop() (μέθοδος της asyncio.Future)
@anchor{library/asyncio-future asyncio Future get_loop}@anchor{ed4}
@deffn {Μέθοδος} get_loop ()

Return the event loop the Future object is bound to.


Added in version 3.7.

@end deffn
@end deffn
@anchor{library/asyncio-future asyncio-example-future}@anchor{3b0f}
This example creates a Future object, creates and schedules an
asynchronous Task to set result for the Future, and waits until
the Future has a result:

@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 Σημαντικό 
The Future object was designed to mimic
@ref{155b,,concurrent.futures.Future}.  Key differences include:


@itemize -

@item 
unlike asyncio Futures, @ref{155b,,concurrent.futures.Future}
instances cannot be awaited.

@item 
@ref{3b0b,,asyncio.Future.result()} and @ref{3b0e,,asyncio.Future.exception()}
do not accept the `timeout' argument.

@item 
@ref{3b0b,,asyncio.Future.result()} and @ref{3b0e,,asyncio.Future.exception()}
raise an @ref{3a34,,InvalidStateError} exception when the Future is not
`done'.

@item 
Callbacks registered with @ref{ecc,,asyncio.Future.add_done_callback()}
are not called immediately.  They are scheduled with
@ref{ec8,,loop.call_soon()} instead.

@item 
asyncio Future is not compatible with the
@ref{1dfc,,concurrent.futures.wait()} and
@ref{1bd1,,concurrent.futures.as_completed()} functions.

@item 
@ref{1da3,,asyncio.Future.cancel()} accepts an optional @code{msg} argument,
but @ref{3934,,concurrent.futures.Future.cancel()} does not.
@end itemize
@end quotation
@end cartouche

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Transports and Protocols,Policies,Futures,asyncio — Asynchronous I/O
@anchor{library/asyncio-protocol doc}@anchor{3b10}@anchor{library/asyncio-protocol asyncio-transports-protocols}@anchor{3a05}@anchor{library/asyncio-protocol translation-repo}@anchor{3b11}@anchor{library/asyncio-protocol transports-and-protocols}@anchor{3b12}
@subsubsection Transports and Protocols


@subsubheading Preface


Transports and Protocols are used by the `low-level' event loop
APIs such as @ref{9f9,,loop.create_connection()}.  They use
callback-based programming style and enable high-performance
implementations of network or IPC protocols (e.g. HTTP).

Essentially, transports and protocols should only be used in
libraries and frameworks and never in high-level asyncio
applications.

This documentation page covers both @ref{3b13,,Transports} and @ref{3b14,,Protocols}.

@subsubheading Introduction


At the highest level, the transport is concerned with `how' bytes
are transmitted, while the protocol determines `which' bytes to
transmit (and to some extent when).

A different way of saying the same thing: a transport is an
abstraction for a socket (or similar I/O endpoint) while a protocol
is an abstraction for an application, from the transport’s point
of view.

Yet another view is the transport and protocol interfaces
together define an abstract interface for using network I/O and
interprocess I/O.

There is always a 1:1 relationship between transport and protocol
objects: the protocol calls transport methods to send data,
while the transport calls protocol methods to pass it data that
has been received.

Most of connection oriented event loop methods
(such as @ref{9f9,,loop.create_connection()}) usually accept a
`protocol_factory' argument used to create a `Protocol' object
for an accepted connection, represented by a `Transport' object.
Such methods usually return a tuple of @code{(transport, protocol)}.

@subsubheading Contents


This documentation page contains the following sections:


@itemize *

@item 
The @ref{3b13,,Transports} section documents asyncio @ref{3b15,,BaseTransport},
@ref{3aea,,ReadTransport}, @ref{3aeb,,WriteTransport}, @ref{3b16,,Transport},
@ref{1d25,,DatagramTransport}, and @ref{3af8,,SubprocessTransport}
classes.

@item 
The @ref{3b14,,Protocols} section documents asyncio @ref{3b17,,BaseProtocol},
@ref{3b18,,Protocol}, @ref{e63,,BufferedProtocol},
@ref{abc,,DatagramProtocol}, and @ref{3af7,,SubprocessProtocol} classes.

@item 
The @ref{3b19,,Examples} section showcases how to work with transports,
protocols, and low-level event loop APIs.
@end itemize

@menu
* Transports:: 
* Protocols: Protocols<2>. 
* Examples: Examples<16>. 

@end menu

@node Transports,Protocols<2>,,Transports and Protocols
@anchor{library/asyncio-protocol asyncio-transport}@anchor{3ad7}@anchor{library/asyncio-protocol transports}@anchor{3b13}
@subsubsection Transports


`Source code:' Lib/asyncio/transports.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/transports.py}


__________________________________________________________________


Transports are classes provided by @ref{b,,asyncio} in order to abstract
various kinds of communication channels.

Transport objects are always instantiated by an
@ref{112f,,asyncio event loop}.

asyncio implements transports for TCP, UDP, SSL, and subprocess pipes.
The methods available on a transport depend on the transport’s kind.

The transport classes are @ref{3a2c,,not thread safe}.

@menu
* Transports Hierarchy:: 
* Base Transport:: 
* Read-only Transports:: 
* Write-only Transports:: 
* Datagram Transports:: 
* Subprocess Transports:: 

@end menu

@node Transports Hierarchy,Base Transport,,Transports
@anchor{library/asyncio-protocol transports-hierarchy}@anchor{3b1a}
@subsubsection Transports Hierarchy


@geindex BaseTransport (κλάση σε asyncio)
@anchor{library/asyncio-protocol asyncio BaseTransport}@anchor{3b15}
@deffn {Κλάση} asyncio.BaseTransport

Base class for all transports.  Contains methods that all
asyncio transports share.
@end deffn

@geindex WriteTransport (κλάση σε asyncio)
@anchor{library/asyncio-protocol asyncio WriteTransport}@anchor{3aeb}
@deffn {Κλάση} asyncio.WriteTransport (BaseTransport)

A base transport for write-only connections.

Instances of the `WriteTransport' class are returned from
the @ref{3a8b,,loop.connect_write_pipe()} event loop method and
are also used by subprocess-related methods like
@ref{3a87,,loop.subprocess_exec()}.
@end deffn

@geindex ReadTransport (κλάση σε asyncio)
@anchor{library/asyncio-protocol asyncio ReadTransport}@anchor{3aea}
@deffn {Κλάση} asyncio.ReadTransport (BaseTransport)

A base transport for read-only connections.

Instances of the `ReadTransport' class are returned from
the @ref{3a8a,,loop.connect_read_pipe()} event loop method and
are also used by subprocess-related methods like
@ref{3a87,,loop.subprocess_exec()}.
@end deffn

@geindex Transport (κλάση σε asyncio)
@anchor{library/asyncio-protocol asyncio Transport}@anchor{3b16}
@deffn {Κλάση} asyncio.Transport (WriteTransport, ReadTransport)

Interface representing a bidirectional transport, such as a
TCP connection.

The user does not instantiate a transport directly; they call a
utility function, passing it a protocol factory and other
information necessary to create the transport and protocol.

Instances of the `Transport' class are returned from or used by
event loop methods like @ref{9f9,,loop.create_connection()},
@ref{3a43,,loop.create_unix_connection()},
@ref{ed7,,loop.create_server()}, @ref{3ae0,,loop.sendfile()}, etc.
@end deffn

@geindex DatagramTransport (κλάση σε asyncio)
@anchor{library/asyncio-protocol asyncio DatagramTransport}@anchor{1d25}
@deffn {Κλάση} asyncio.DatagramTransport (BaseTransport)

A transport for datagram (UDP) connections.

Instances of the `DatagramTransport' class are returned from
the @ref{b1a,,loop.create_datagram_endpoint()} event loop method.
@end deffn

@geindex SubprocessTransport (κλάση σε asyncio)
@anchor{library/asyncio-protocol asyncio SubprocessTransport}@anchor{3af8}
@deffn {Κλάση} asyncio.SubprocessTransport (BaseTransport)

An abstraction to represent a connection between a parent and its
child OS process.

Instances of the `SubprocessTransport' class are returned from
event loop methods @ref{3a88,,loop.subprocess_shell()} and
@ref{3a87,,loop.subprocess_exec()}.
@end deffn

@node Base Transport,Read-only Transports,Transports Hierarchy,Transports
@anchor{library/asyncio-protocol base-transport}@anchor{3b1b}
@subsubsection Base Transport


@geindex close() (μέθοδος της asyncio.BaseTransport)
@anchor{library/asyncio-protocol asyncio BaseTransport close}@anchor{3ada}
@deffn {Μέθοδος} BaseTransport.close ()

Close the transport.

If the transport has a buffer for outgoing
data, buffered data will be flushed asynchronously.  No more data
will be received.  After all buffered data is flushed, the
protocol’s @ref{3b1c,,protocol.connection_lost()} method will be called with
@ref{a65,,None} as its argument. The transport should not be
used once it is closed.
@end deffn

@geindex is_closing() (μέθοδος της asyncio.BaseTransport)
@anchor{library/asyncio-protocol asyncio BaseTransport is_closing}@anchor{1037}
@deffn {Μέθοδος} BaseTransport.is_closing ()

Return @code{True} if the transport is closing or is closed.
@end deffn

@geindex get_extra_info() (μέθοδος της asyncio.BaseTransport)
@anchor{library/asyncio-protocol asyncio BaseTransport get_extra_info}@anchor{e62}
@deffn {Μέθοδος} BaseTransport.get_extra_info (name, default=None)

Return information about the transport or underlying resources
it uses.

`name' is a string representing the piece of transport-specific
information to get.

`default' is the value to return if the information is not
available, or if the transport does not support querying it
with the given third-party event loop implementation or on the
current platform.

For example, the following code attempts to get the underlying
socket object of the transport:

@example
sock = transport.get_extra_info('socket')
if sock is not None:
    print(sock.getsockopt(...))
@end example

Categories of information that can be queried on some transports:


@itemize *

@item 
socket:


@itemize -

@item 
@code{'peername'}: the remote address to which the socket is
connected, result of @ref{3b1d,,socket.socket.getpeername()}
(@code{None} on error)

@item 
@code{'socket'}: @ref{115a,,socket.socket} instance

@item 
@code{'sockname'}: the socket’s own address,
result of @ref{50c,,socket.socket.getsockname()}
@end itemize

@item 
SSL socket:


@itemize -

@item 
@code{'compression'}: the compression algorithm being used as a
string, or @code{None} if the connection isn’t compressed; result
of @ref{14f0,,ssl.SSLSocket.compression()}

@item 
@code{'cipher'}: 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; result of
@ref{3b1e,,ssl.SSLSocket.cipher()}

@item 
@code{'peercert'}: peer certificate; result of
@ref{1361,,ssl.SSLSocket.getpeercert()}

@item 
@code{'sslcontext'}: @ref{336,,ssl.SSLContext} instance

@item 
@code{'ssl_object'}: @ref{f40,,ssl.SSLObject} or
@ref{cbb,,ssl.SSLSocket} instance
@end itemize

@item 
pipe:


@itemize -

@item 
@code{'pipe'}: pipe object
@end itemize

@item 
subprocess:


@itemize -

@item 
@code{'subprocess'}: @ref{6bf,,subprocess.Popen} instance
@end itemize
@end itemize
@end deffn

@geindex set_protocol() (μέθοδος της asyncio.BaseTransport)
@anchor{library/asyncio-protocol asyncio BaseTransport set_protocol}@anchor{3b1f}
@deffn {Μέθοδος} BaseTransport.set_protocol (protocol)

Set a new protocol.

Switching protocol should only be done when both
protocols are documented to support the switch.
@end deffn

@geindex get_protocol() (μέθοδος της asyncio.BaseTransport)
@anchor{library/asyncio-protocol asyncio BaseTransport get_protocol}@anchor{3b20}
@deffn {Μέθοδος} BaseTransport.get_protocol ()

Return the current protocol.
@end deffn

@node Read-only Transports,Write-only Transports,Base Transport,Transports
@anchor{library/asyncio-protocol read-only-transports}@anchor{3b21}
@subsubsection Read-only Transports


@geindex is_reading() (μέθοδος της asyncio.ReadTransport)
@anchor{library/asyncio-protocol asyncio ReadTransport is_reading}@anchor{edf}
@deffn {Μέθοδος} ReadTransport.is_reading ()

Return @code{True} if the transport is receiving new data.


Added in version 3.7.

@end deffn

@geindex pause_reading() (μέθοδος της asyncio.ReadTransport)
@anchor{library/asyncio-protocol asyncio ReadTransport pause_reading}@anchor{ee1}
@deffn {Μέθοδος} ReadTransport.pause_reading ()

Pause the receiving end of the transport.  No data will be passed to
the protocol’s @ref{1d01,,protocol.data_received()}
method until @ref{ee0,,resume_reading()} is called.


Άλλαξε στην έκδοση 3.7: The method is idempotent, i.e. it can be called when the
transport is already paused or closed.

@end deffn

@geindex resume_reading() (μέθοδος της asyncio.ReadTransport)
@anchor{library/asyncio-protocol asyncio ReadTransport resume_reading}@anchor{ee0}
@deffn {Μέθοδος} ReadTransport.resume_reading ()

Resume the receiving end.  The protocol’s
@ref{1d01,,protocol.data_received()} method
will be called once again if some data is available for reading.


Άλλαξε στην έκδοση 3.7: The method is idempotent, i.e. it can be called when the
transport is already reading.

@end deffn

@node Write-only Transports,Datagram Transports,Read-only Transports,Transports
@anchor{library/asyncio-protocol write-only-transports}@anchor{3b22}
@subsubsection Write-only Transports


@geindex abort() (μέθοδος της asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport abort}@anchor{3afb}
@deffn {Μέθοδος} WriteTransport.abort ()

Close the transport immediately, without waiting for pending operations
to complete.  Buffered data will be lost.  No more data will be received.
The protocol’s @ref{3b1c,,protocol.connection_lost()} method will eventually be
called with @ref{a65,,None} as its argument.
@end deffn

@geindex can_write_eof() (μέθοδος της asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport can_write_eof}@anchor{3b23}
@deffn {Μέθοδος} WriteTransport.can_write_eof ()

Return @ref{fcc,,True} if the transport supports
@ref{3b24,,write_eof()}, @ref{ef5,,False} if not.
@end deffn

@geindex get_write_buffer_size() (μέθοδος της asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport get_write_buffer_size}@anchor{192c}
@deffn {Μέθοδος} WriteTransport.get_write_buffer_size ()

Return the current size of the output buffer used by the transport.
@end deffn

@geindex get_write_buffer_limits() (μέθοδος της asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport get_write_buffer_limits}@anchor{117d}
@deffn {Μέθοδος} WriteTransport.get_write_buffer_limits ()

Get the `high' and `low' watermarks for write flow control. Return a
tuple @code{(low, high)} where `low' and `high' are positive number of
bytes.

Use @ref{3b25,,set_write_buffer_limits()} to set the limits.


Added in version 3.4.2.

@end deffn

@geindex set_write_buffer_limits() (μέθοδος της asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport set_write_buffer_limits}@anchor{3b25}
@deffn {Μέθοδος} WriteTransport.set_write_buffer_limits (high=None, low=None)

Set the `high' and `low' watermarks for write flow control.

These two values (measured in number of
bytes) control when the protocol’s
@ref{3b26,,protocol.pause_writing()}
and @ref{3b27,,protocol.resume_writing()}
methods are called. If specified, the low watermark must be less
than or equal to the high watermark.  Neither `high' nor `low'
can be negative.

@ref{3b26,,pause_writing()} is called when the buffer size
becomes greater than or equal to the `high' value. If writing has
been paused, @ref{3b27,,resume_writing()} is called when
the buffer size becomes less than or equal to the `low' value.

The defaults are implementation-specific.  If only the
high watermark is given, the low watermark defaults to an
implementation-specific value less than or equal to the
high watermark.  Setting `high' to zero forces `low' to zero as
well, and causes @ref{3b26,,pause_writing()} to be called
whenever the buffer becomes non-empty.  Setting `low' to zero causes
@ref{3b27,,resume_writing()} to be called only once the
buffer is empty. Use of zero for either limit is generally
sub-optimal as it reduces opportunities for doing I/O and
computation concurrently.

Use @ref{117d,,get_write_buffer_limits()}
to get the limits.
@end deffn

@geindex write() (μέθοδος της asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport write}@anchor{1a0a}
@deffn {Μέθοδος} WriteTransport.write (data)

Write some `data' bytes to the transport.

This method does not block; it buffers the data and arranges for it
to be sent out asynchronously.
@end deffn

@geindex writelines() (μέθοδος της asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport writelines}@anchor{1a09}
@deffn {Μέθοδος} WriteTransport.writelines (list_of_data)

Write a list (or any iterable) of data bytes to the transport.
This is functionally equivalent to calling @ref{1a0a,,write()} on each
element yielded by the iterable, but may be implemented more
efficiently.
@end deffn

@geindex write_eof() (μέθοδος της asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport write_eof}@anchor{3b24}
@deffn {Μέθοδος} WriteTransport.write_eof ()

Close the write end of the transport after flushing all buffered data.
Data may still be received.

This method can raise @ref{59a,,NotImplementedError} if the transport
(e.g. SSL) doesn’t support half-closed connections.
@end deffn

@node Datagram Transports,Subprocess Transports,Write-only Transports,Transports
@anchor{library/asyncio-protocol datagram-transports}@anchor{3b28}
@subsubsection Datagram Transports


@geindex sendto() (μέθοδος της asyncio.DatagramTransport)
@anchor{library/asyncio-protocol asyncio DatagramTransport sendto}@anchor{6d1}
@deffn {Μέθοδος} DatagramTransport.sendto (data, addr=None)

Send the `data' bytes to the remote peer given by `addr' (a
transport-dependent target address).  If `addr' is @ref{a65,,None},
the data is sent to the target address given on transport
creation.

This method does not block; it buffers the data and arranges
for it to be sent out asynchronously.


Άλλαξε στην έκδοση 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() (μέθοδος της asyncio.DatagramTransport)
@anchor{library/asyncio-protocol asyncio DatagramTransport abort}@anchor{3b29}
@deffn {Μέθοδος} DatagramTransport.abort ()

Close the transport immediately, without waiting for pending
operations to complete.  Buffered data will be lost.
No more data will be received.  The protocol’s
@ref{3b1c,,protocol.connection_lost()}
method will eventually be called with @ref{a65,,None} as its argument.
@end deffn

@node Subprocess Transports,,Datagram Transports,Transports
@anchor{library/asyncio-protocol asyncio-subprocess-transports}@anchor{3a8c}@anchor{library/asyncio-protocol subprocess-transports}@anchor{3b2a}
@subsubsection Subprocess Transports


@geindex get_pid() (μέθοδος της asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport get_pid}@anchor{3b2b}
@deffn {Μέθοδος} SubprocessTransport.get_pid ()

Return the subprocess process id as an integer.
@end deffn

@geindex get_pipe_transport() (μέθοδος της asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport get_pipe_transport}@anchor{3b2c}
@deffn {Μέθοδος} SubprocessTransport.get_pipe_transport (fd)

Return the transport for the communication pipe corresponding to the
integer file descriptor `fd':


@itemize *

@item 
@code{0}: writable streaming transport of the standard input (`stdin'),
or @ref{a65,,None} if the subprocess was not created with @code{stdin=PIPE}

@item 
@code{1}: readable streaming transport of the standard output (`stdout'),
or @ref{a65,,None} if the subprocess was not created with @code{stdout=PIPE}

@item 
@code{2}: readable streaming transport of the standard error (`stderr'),
or @ref{a65,,None} if the subprocess was not created with @code{stderr=PIPE}

@item 
other `fd': @ref{a65,,None}
@end itemize
@end deffn

@geindex get_returncode() (μέθοδος της asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport get_returncode}@anchor{3b2d}
@deffn {Μέθοδος} SubprocessTransport.get_returncode ()

Return the subprocess return code as an integer or @ref{a65,,None}
if it hasn’t returned, which is similar to the
@ref{e52,,subprocess.Popen.returncode} attribute.
@end deffn

@geindex kill() (μέθοδος της asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport kill}@anchor{3b2e}
@deffn {Μέθοδος} SubprocessTransport.kill ()

Kill the subprocess.

On POSIX systems, the function sends SIGKILL to the subprocess.
On Windows, this method is an alias for @ref{3b2f,,terminate()}.

See also @ref{1780,,subprocess.Popen.kill()}.
@end deffn

@geindex send_signal() (μέθοδος της asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport send_signal}@anchor{3b30}
@deffn {Μέθοδος} SubprocessTransport.send_signal (signal)

Send the `signal' number to the subprocess, as in
@ref{1781,,subprocess.Popen.send_signal()}.
@end deffn

@geindex terminate() (μέθοδος της asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport terminate}@anchor{3b2f}
@deffn {Μέθοδος} SubprocessTransport.terminate ()

Stop the subprocess.

On POSIX systems, this method sends @ref{1782,,SIGTERM} to the subprocess.
On Windows, the Windows API function @code{TerminateProcess()} is called to
stop the subprocess.

See also @ref{177f,,subprocess.Popen.terminate()}.
@end deffn

@geindex close() (μέθοδος της asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport close}@anchor{3b31}
@deffn {Μέθοδος} SubprocessTransport.close ()

Kill the subprocess by calling the @ref{3b2e,,kill()} method.

If the subprocess hasn’t returned yet, and close transports of
`stdin', `stdout', and `stderr' pipes.
@end deffn

@node Protocols<2>,Examples<16>,Transports,Transports and Protocols
@anchor{library/asyncio-protocol asyncio-protocol}@anchor{3ad6}@anchor{library/asyncio-protocol protocols}@anchor{3b14}
@subsubsection Protocols


`Source code:' Lib/asyncio/protocols.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/protocols.py}


__________________________________________________________________


asyncio provides a set of abstract base classes that should be used
to implement network protocols.  Those classes are meant to be used
together with @ref{3ad7,,transports}.

Subclasses of abstract base protocol classes may implement some or
all methods.  All these methods are callbacks: they are called by
transports on certain events, for example when some data is received.
A base protocol method should be called by the corresponding transport.

@menu
* Base Protocols:: 
* Base Protocol:: 
* Streaming Protocols:: 
* Buffered Streaming Protocols:: 
* Datagram Protocols:: 
* Subprocess Protocols:: 

@end menu

@node Base Protocols,Base Protocol,,Protocols<2>
@anchor{library/asyncio-protocol base-protocols}@anchor{3b32}
@subsubsection Base Protocols


@geindex BaseProtocol (κλάση σε asyncio)
@anchor{library/asyncio-protocol asyncio BaseProtocol}@anchor{3b17}
@deffn {Κλάση} asyncio.BaseProtocol

Base protocol with methods that all protocols share.
@end deffn

@geindex Protocol (κλάση σε asyncio)
@anchor{library/asyncio-protocol asyncio Protocol}@anchor{3b18}
@deffn {Κλάση} asyncio.Protocol (BaseProtocol)

The base class for implementing streaming protocols
(TCP, Unix sockets, etc).
@end deffn

@geindex BufferedProtocol (κλάση σε asyncio)
@anchor{library/asyncio-protocol asyncio BufferedProtocol}@anchor{e63}
@deffn {Κλάση} asyncio.BufferedProtocol (BaseProtocol)

A base class for implementing streaming protocols with manual
control of the receive buffer.
@end deffn

@geindex DatagramProtocol (κλάση σε asyncio)
@anchor{library/asyncio-protocol asyncio DatagramProtocol}
@deffn {Κλάση} asyncio.DatagramProtocol (BaseProtocol)

The base class for implementing datagram (UDP) protocols.
@end deffn

@geindex SubprocessProtocol (κλάση σε asyncio)
@anchor{library/asyncio-protocol asyncio SubprocessProtocol}@anchor{3af7}
@deffn {Κλάση} asyncio.SubprocessProtocol (BaseProtocol)

The base class for implementing protocols communicating with child
processes (unidirectional pipes).
@end deffn

@node Base Protocol,Streaming Protocols,Base Protocols,Protocols<2>
@anchor{library/asyncio-protocol base-protocol}@anchor{3b33}
@subsubsection Base Protocol


All asyncio protocols can implement Base Protocol callbacks.

@subsubheading Connection Callbacks


Connection callbacks are called on all protocols, exactly once per
a successful connection.  All other protocol callbacks can only be
called between those two methods.

@geindex connection_made() (μέθοδος της asyncio.BaseProtocol)
@anchor{library/asyncio-protocol asyncio BaseProtocol connection_made}@anchor{3ad8}
@deffn {Μέθοδος} BaseProtocol.connection_made (transport)

Called when a connection is made.

The `transport' argument is the transport representing the
connection.  The protocol is responsible for storing the reference
to its transport.
@end deffn

@geindex connection_lost() (μέθοδος της asyncio.BaseProtocol)
@anchor{library/asyncio-protocol asyncio BaseProtocol connection_lost}@anchor{3b1c}
@deffn {Μέθοδος} BaseProtocol.connection_lost (exc)

Called when the connection is lost or closed.

The argument is either an exception object or @ref{a65,,None}.
The latter means a regular EOF is received, or the connection was
aborted or closed by this side of the connection.
@end deffn

@subsubheading Flow Control Callbacks


Flow control callbacks can be called by transports to pause or
resume writing performed by the protocol.

See the documentation of the @ref{3b25,,set_write_buffer_limits()}
method for more details.

@geindex pause_writing() (μέθοδος της asyncio.BaseProtocol)
@anchor{library/asyncio-protocol asyncio BaseProtocol pause_writing}@anchor{3b26}
@deffn {Μέθοδος} BaseProtocol.pause_writing ()

Called when the transport’s buffer goes over the high watermark.
@end deffn

@geindex resume_writing() (μέθοδος της asyncio.BaseProtocol)
@anchor{library/asyncio-protocol asyncio BaseProtocol resume_writing}@anchor{3b27}
@deffn {Μέθοδος} BaseProtocol.resume_writing ()

Called when the transport’s buffer drains below the low watermark.
@end deffn

If the buffer size equals the high watermark,
@ref{3b26,,pause_writing()} is not called: the buffer size must
go strictly over.

Conversely, @ref{3b27,,resume_writing()} is called when the
buffer size is equal or lower than the low watermark.  These end
conditions are important to ensure that things go as expected when
either mark is zero.

@node Streaming Protocols,Buffered Streaming Protocols,Base Protocol,Protocols<2>
@anchor{library/asyncio-protocol streaming-protocols}@anchor{3b34}
@subsubsection Streaming Protocols


Event methods, such as @ref{ed7,,loop.create_server()},
@ref{6d0,,loop.create_unix_server()}, @ref{9f9,,loop.create_connection()},
@ref{3a43,,loop.create_unix_connection()}, @ref{bbb,,loop.connect_accepted_socket()},
@ref{3a8a,,loop.connect_read_pipe()}, and @ref{3a8b,,loop.connect_write_pipe()}
accept factories that return streaming protocols.

@geindex data_received() (μέθοδος της asyncio.Protocol)
@anchor{library/asyncio-protocol asyncio Protocol data_received}@anchor{1d01}
@deffn {Μέθοδος} Protocol.data_received (data)

Called when some data is received.  `data' is a non-empty bytes
object containing the incoming data.

Whether the data is buffered, chunked or reassembled depends on
the transport.  In general, you shouldn’t rely on specific semantics
and instead make your parsing generic and flexible. However,
data is always received in the correct order.

The method can be called an arbitrary number of times while
a connection is open.

However, @ref{3b35,,protocol.eof_received()}
is called at most once.  Once @code{eof_received()} is called,
@code{data_received()} is not called anymore.
@end deffn

@geindex eof_received() (μέθοδος της asyncio.Protocol)
@anchor{library/asyncio-protocol asyncio Protocol eof_received}@anchor{3b35}
@deffn {Μέθοδος} Protocol.eof_received ()

Called when the other end signals it won’t send any more data
(for example by calling @ref{3b24,,transport.write_eof()}, if the other end also uses
asyncio).

This method may return a false value (including @code{None}), in which case
the transport will close itself.  Conversely, if this method returns a
true value, the protocol used determines whether to close the transport.
Since the default implementation returns @code{None}, it implicitly closes the
connection.

Some transports, including SSL, don’t support half-closed connections,
in which case returning true from this method will result in the connection
being closed.
@end deffn

State machine:

@example
start -> connection_made
    [-> data_received]*
    [-> eof_received]?
-> connection_lost -> end
@end example

@node Buffered Streaming Protocols,Datagram Protocols,Streaming Protocols,Protocols<2>
@anchor{library/asyncio-protocol buffered-streaming-protocols}@anchor{3b36}
@subsubsection Buffered Streaming Protocols



Added in version 3.7.


Buffered Protocols can be used with any event loop method
that supports @ref{3b34,,Streaming Protocols}.

@code{BufferedProtocol} implementations allow explicit manual allocation
and control of the receive buffer.  Event loops can then use the buffer
provided by the protocol to avoid unnecessary data copies.  This
can result in noticeable performance improvement for protocols that
receive big amounts of data.  Sophisticated protocol implementations
can significantly reduce the number of buffer allocations.

The following callbacks are called on @ref{e63,,BufferedProtocol}
instances:

@geindex get_buffer() (μέθοδος της asyncio.BufferedProtocol)
@anchor{library/asyncio-protocol asyncio BufferedProtocol get_buffer}@anchor{3b37}
@deffn {Μέθοδος} BufferedProtocol.get_buffer (sizehint)

Called to allocate a new receive buffer.

`sizehint' is the recommended minimum size for the returned
buffer.  It is acceptable to return smaller or larger buffers
than what `sizehint' suggests.  When set to -1, the buffer size
can be arbitrary. It is an error to return a buffer with a zero size.

@code{get_buffer()} must return an object implementing the
@ref{311,,buffer protocol}.
@end deffn

@geindex buffer_updated() (μέθοδος της asyncio.BufferedProtocol)
@anchor{library/asyncio-protocol asyncio BufferedProtocol buffer_updated}@anchor{3b38}
@deffn {Μέθοδος} BufferedProtocol.buffer_updated (nbytes)

Called when the buffer was updated with the received data.

`nbytes' is the total number of bytes that were written to the buffer.
@end deffn

@geindex eof_received() (μέθοδος της asyncio.BufferedProtocol)
@anchor{library/asyncio-protocol asyncio BufferedProtocol eof_received}@anchor{3b39}
@deffn {Μέθοδος} BufferedProtocol.eof_received ()

See the documentation of the @ref{3b35,,protocol.eof_received()} method.
@end deffn

@ref{3b37,,get_buffer()} can be called an arbitrary number
of times during a connection.  However, @ref{3b35,,protocol.eof_received()} is called at most once
and, if called, @code{get_buffer()} and
@ref{3b38,,buffer_updated()} won’t be called after it.

State machine:

@example
start -> connection_made
    [-> get_buffer
        [-> buffer_updated]?
    ]*
    [-> eof_received]?
-> connection_lost -> end
@end example

@node Datagram Protocols,Subprocess Protocols,Buffered Streaming Protocols,Protocols<2>
@anchor{library/asyncio-protocol datagram-protocols}@anchor{3b3a}
@subsubsection Datagram Protocols


Datagram Protocol instances should be constructed by protocol
factories passed to the @ref{b1a,,loop.create_datagram_endpoint()} method.

@geindex datagram_received() (μέθοδος της asyncio.DatagramProtocol)
@anchor{library/asyncio-protocol asyncio DatagramProtocol datagram_received}@anchor{3b3b}
@deffn {Μέθοδος} DatagramProtocol.datagram_received (data, addr)

Called when a datagram is received.  `data' is a bytes object containing
the incoming data.  `addr' is the address of the peer sending the data;
the exact format depends on the transport.
@end deffn

@geindex error_received() (μέθοδος της asyncio.DatagramProtocol)
@anchor{library/asyncio-protocol asyncio DatagramProtocol error_received}@anchor{3b3c}
@deffn {Μέθοδος} DatagramProtocol.error_received (exc)

Called when a previous send or receive operation raises an
@ref{53c,,OSError}.  `exc' is the @code{OSError} instance.

This method is called in rare conditions, when the transport (e.g. UDP)
detects that a datagram could not be delivered to its recipient.
In many conditions though, undeliverable datagrams will be silently
dropped.
@end deffn

@cartouche
@quotation Σημείωση 
On BSD systems (macOS, FreeBSD, etc.) flow control is not supported
for datagram protocols, because there is no reliable way to detect send
failures caused by writing too many packets.

The socket always appears “ready” and excess packets are dropped. An
@ref{53c,,OSError} with @code{errno} set to @ref{1d6e,,errno.ENOBUFS} may
or may not be raised; if it is raised, it will be reported to
@ref{3b3c,,DatagramProtocol.error_received()} but otherwise ignored.
@end quotation
@end cartouche

@node Subprocess Protocols,,Datagram Protocols,Protocols<2>
@anchor{library/asyncio-protocol asyncio-subprocess-protocols}@anchor{3a8d}@anchor{library/asyncio-protocol subprocess-protocols}@anchor{3b3d}
@subsubsection Subprocess Protocols


Subprocess Protocol instances should be constructed by protocol
factories passed to the @ref{3a87,,loop.subprocess_exec()} and
@ref{3a88,,loop.subprocess_shell()} methods.

@geindex pipe_data_received() (μέθοδος της asyncio.SubprocessProtocol)
@anchor{library/asyncio-protocol asyncio SubprocessProtocol pipe_data_received}@anchor{1d4e}
@deffn {Μέθοδος} SubprocessProtocol.pipe_data_received (fd, data)

Called when the child process writes data into its stdout or stderr
pipe.

`fd' is the integer file descriptor of the pipe.

`data' is a non-empty bytes object containing the received data.
@end deffn

@geindex pipe_connection_lost() (μέθοδος της asyncio.SubprocessProtocol)
@anchor{library/asyncio-protocol asyncio SubprocessProtocol pipe_connection_lost}@anchor{3b3e}
@deffn {Μέθοδος} SubprocessProtocol.pipe_connection_lost (fd, exc)

Called when one of the pipes communicating with the child process
is closed.

`fd' is the integer file descriptor that was closed.
@end deffn

@geindex process_exited() (μέθοδος της asyncio.SubprocessProtocol)
@anchor{library/asyncio-protocol asyncio SubprocessProtocol process_exited}@anchor{1d4d}
@deffn {Μέθοδος} SubprocessProtocol.process_exited ()

Called when the child process has exited.

It can be called before @ref{1d4e,,pipe_data_received()} and
@ref{3b3e,,pipe_connection_lost()} methods.
@end deffn

@node Examples<16>,,Protocols<2>,Transports and Protocols
@anchor{library/asyncio-protocol examples}@anchor{3b19}
@subsubsection Examples


@menu
* TCP Echo Server:: 
* TCP Echo Client:: 
* UDP Echo Server:: 
* UDP Echo Client:: 
* Connecting Existing Sockets:: 
* loop.subprocess_exec() and SubprocessProtocol: loop subprocess_exec and SubprocessProtocol. 

@end menu

@node TCP Echo Server,TCP Echo Client,,Examples<16>
@anchor{library/asyncio-protocol asyncio-example-tcp-echo-server-protocol}@anchor{3a58}@anchor{library/asyncio-protocol tcp-echo-server}@anchor{3b3f}
@subsubsection TCP Echo Server


Create a TCP echo server using the @ref{ed7,,loop.create_server()} method, send back
received data, and close the connection:

@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 Δείτε επίσης


The @ref{3a56,,TCP echo server using streams}
example uses the high-level @ref{edd,,asyncio.start_server()} function.


@node TCP Echo Client,UDP Echo Server,TCP Echo Server,Examples<16>
@anchor{library/asyncio-protocol asyncio-example-tcp-echo-client-protocol}@anchor{3a55}@anchor{library/asyncio-protocol tcp-echo-client}@anchor{3b40}
@subsubsection TCP Echo Client


A TCP echo client using the @ref{9f9,,loop.create_connection()} method, sends
data, and waits until the connection is closed:

@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 Δείτε επίσης


The @ref{3a53,,TCP echo client using streams}
example uses the high-level @ref{edc,,asyncio.open_connection()} function.


@node UDP Echo Server,UDP Echo Client,TCP Echo Client,Examples<16>
@anchor{library/asyncio-protocol asyncio-udp-echo-server-protocol}@anchor{3adc}@anchor{library/asyncio-protocol udp-echo-server}@anchor{3b41}
@subsubsection UDP Echo Server


A UDP echo server, using the @ref{b1a,,loop.create_datagram_endpoint()}
method, sends back received data:

@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 UDP Echo Client,Connecting Existing Sockets,UDP Echo Server,Examples<16>
@anchor{library/asyncio-protocol asyncio-udp-echo-client-protocol}@anchor{3adb}@anchor{library/asyncio-protocol udp-echo-client}@anchor{3b42}
@subsubsection UDP Echo Client


A UDP echo client, using the @ref{b1a,,loop.create_datagram_endpoint()}
method, sends data and closes the transport when it receives the answer:

@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 Connecting Existing Sockets,loop subprocess_exec and SubprocessProtocol,UDP Echo Client,Examples<16>
@anchor{library/asyncio-protocol asyncio-example-create-connection}@anchor{3a5c}@anchor{library/asyncio-protocol connecting-existing-sockets}@anchor{3b43}
@subsubsection Connecting Existing Sockets


Wait until a socket receives data using the
@ref{9f9,,loop.create_connection()} method with a protocol:

@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 Δείτε επίσης


The @ref{3a5d,,watch a file descriptor for read events} example uses the low-level
@ref{3a5e,,loop.add_reader()} method to register an FD.

The @ref{3a5a,,register an open socket to wait for data using streams} example uses high-level streams
created by the @ref{edc,,open_connection()} function in a coroutine.


@node loop subprocess_exec and SubprocessProtocol,,Connecting Existing Sockets,Examples<16>
@anchor{library/asyncio-protocol asyncio-example-subprocess-proto}@anchor{3a9c}@anchor{library/asyncio-protocol loop-subprocess-exec-and-subprocessprotocol}@anchor{3b44}
@subsubsection loop.subprocess_exec() and SubprocessProtocol


An example of a subprocess protocol used to get the output of a
subprocess and to wait for the subprocess exit.

The subprocess is created by the @ref{3a87,,loop.subprocess_exec()} method:

@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 as dt; print(dt.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

See also the @ref{3a9b,,same example}
written using high-level APIs.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Policies,Platform Support,Transports and Protocols,asyncio — Asynchronous I/O
@anchor{library/asyncio-policy doc}@anchor{3b45}@anchor{library/asyncio-policy asyncio-policies}@anchor{3ac4}@anchor{library/asyncio-policy policies}@anchor{3b46}@anchor{library/asyncio-policy translation-repo}@anchor{3b47}
@subsubsection Policies


@cartouche
@quotation Προειδοποίηση 
Policies are deprecated and will be removed in Python 3.16.
Users are encouraged to use the @ref{309,,asyncio.run()} function
or the @ref{30a,,asyncio.Runner} with `loop_factory' to use
the desired loop implementation.
@end quotation
@end cartouche

An event loop policy is a global object
used to get and set the current @ref{112f,,event loop},
as well as create new event loops.
The default policy can be @ref{3b48,,replaced} with
@ref{3b49,,built-in alternatives}
to use different event loop implementations,
or substituted by a @ref{3b4a,,custom policy}
that can override these behaviors.

The @ref{3b4b,,policy object}
gets and sets a separate event loop per `context'.
This is per-thread by default,
though custom policies could define `context' differently.

Custom event loop policies can control the behavior of
@ref{56c,,get_event_loop()}, @ref{1d53,,set_event_loop()}, and @ref{3a0b,,new_event_loop()}.

Policy objects should implement the APIs defined
in the @ref{303,,AbstractEventLoopPolicy} abstract base class.

@menu
* Getting and Setting the Policy:: 
* Policy Objects:: 
* Custom Policies:: 

@end menu

@node Getting and Setting the Policy,Policy Objects,,Policies
@anchor{library/asyncio-policy asyncio-policy-get-set}@anchor{3b48}@anchor{library/asyncio-policy getting-and-setting-the-policy}@anchor{3b4c}
@subsubsection Getting and Setting the Policy


The following functions can be used to get and set the policy
for the current process:

@geindex get_event_loop_policy() (στη μονάδα asyncio)
@anchor{library/asyncio-policy asyncio get_event_loop_policy}@anchor{307}
@deffn {Συνάρτηση} asyncio.get_event_loop_policy ()

Return the current process-wide policy.


Αποσύρθηκε στην έκδοση 3.14: The @code{get_event_loop_policy()} function is deprecated and
will be removed in Python 3.16.

@end deffn

@geindex set_event_loop_policy() (στη μονάδα asyncio)
@anchor{library/asyncio-policy asyncio set_event_loop_policy}@anchor{308}
@deffn {Συνάρτηση} asyncio.set_event_loop_policy (policy)

Set the current process-wide policy to `policy'.

If `policy' is set to @code{None}, the default policy is restored.


Αποσύρθηκε στην έκδοση 3.14: The @code{set_event_loop_policy()} function is deprecated and
will be removed in Python 3.16.

@end deffn

@node Policy Objects,Custom Policies,Getting and Setting the Policy,Policies
@anchor{library/asyncio-policy asyncio-policy-objects}@anchor{3b4b}@anchor{library/asyncio-policy policy-objects}@anchor{3b4d}
@subsubsection Policy Objects


The abstract event loop policy base class is defined as follows:

@geindex AbstractEventLoopPolicy (κλάση σε asyncio)
@anchor{library/asyncio-policy asyncio AbstractEventLoopPolicy}@anchor{303}
@deffn {Κλάση} asyncio.AbstractEventLoopPolicy

An abstract base class for asyncio policies.

@geindex get_event_loop() (μέθοδος της asyncio.AbstractEventLoopPolicy)
@anchor{library/asyncio-policy asyncio AbstractEventLoopPolicy get_event_loop}@anchor{3b4e}
@deffn {Μέθοδος} get_event_loop ()

Get the event loop for the current context.

Return an event loop object implementing the
@ref{d29,,AbstractEventLoop} interface.

This method should never return @code{None}.


Άλλαξε στην έκδοση 3.6.

@end deffn

@geindex set_event_loop() (μέθοδος της asyncio.AbstractEventLoopPolicy)
@anchor{library/asyncio-policy asyncio AbstractEventLoopPolicy set_event_loop}@anchor{3b4f}
@deffn {Μέθοδος} set_event_loop (loop)

Set the event loop for the current context to `loop'.
@end deffn

@geindex new_event_loop() (μέθοδος της asyncio.AbstractEventLoopPolicy)
@anchor{library/asyncio-policy asyncio AbstractEventLoopPolicy new_event_loop}@anchor{3b50}
@deffn {Μέθοδος} new_event_loop ()

Create and return a new event loop object.

This method should never return @code{None}.
@end deffn


Αποσύρθηκε στην έκδοση 3.14: The @code{AbstractEventLoopPolicy} class is deprecated and
will be removed in Python 3.16.

@end deffn
@anchor{library/asyncio-policy asyncio-policy-builtin}@anchor{3b49}
asyncio ships with the following built-in policies:

@geindex DefaultEventLoopPolicy (κλάση σε asyncio)
@anchor{library/asyncio-policy asyncio DefaultEventLoopPolicy}@anchor{304}
@deffn {Κλάση} asyncio.DefaultEventLoopPolicy

The default asyncio policy.  Uses @ref{30b,,SelectorEventLoop}
on Unix and @ref{9fe,,ProactorEventLoop} on Windows.

There is no need to install the default policy manually. asyncio
is configured to use the default policy automatically.


Άλλαξε στην έκδοση 3.8: On Windows, @ref{9fe,,ProactorEventLoop} is now used by default.



Άλλαξε στην έκδοση 3.14: The @ref{56c,,get_event_loop()} method of the default asyncio policy now
raises a @ref{30d,,RuntimeError} if there is no set event loop.



Αποσύρθηκε στην έκδοση 3.14: The @code{DefaultEventLoopPolicy} class is deprecated and
will be removed in Python 3.16.

@end deffn

@geindex WindowsSelectorEventLoopPolicy (κλάση σε asyncio)
@anchor{library/asyncio-policy asyncio WindowsSelectorEventLoopPolicy}@anchor{305}
@deffn {Κλάση} asyncio.WindowsSelectorEventLoopPolicy

An alternative event loop policy that uses the
@ref{30b,,SelectorEventLoop} event loop implementation.

@ref{232d,,Διαθεσιμότητα}: Windows.


Αποσύρθηκε στην έκδοση 3.14: The @code{WindowsSelectorEventLoopPolicy} class is deprecated and
will be removed in Python 3.16.

@end deffn

@geindex WindowsProactorEventLoopPolicy (κλάση σε asyncio)
@anchor{library/asyncio-policy asyncio WindowsProactorEventLoopPolicy}@anchor{306}
@deffn {Κλάση} asyncio.WindowsProactorEventLoopPolicy

An alternative event loop policy that uses the
@ref{9fe,,ProactorEventLoop} event loop implementation.

@ref{232d,,Διαθεσιμότητα}: Windows.


Αποσύρθηκε στην έκδοση 3.14: The @code{WindowsProactorEventLoopPolicy} class is deprecated and
will be removed in Python 3.16.

@end deffn

@node Custom Policies,,Policy Objects,Policies
@anchor{library/asyncio-policy asyncio-custom-policies}@anchor{3b4a}@anchor{library/asyncio-policy custom-policies}@anchor{3b51}
@subsubsection Custom Policies


To implement a new event loop policy, it is recommended to subclass
@ref{304,,DefaultEventLoopPolicy} and override the methods for which
custom behavior is wanted, e.g.:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Platform Support,Extending,Policies,asyncio — Asynchronous I/O
@anchor{library/asyncio-platforms doc}@anchor{3b52}@anchor{library/asyncio-platforms asyncio-platform-support}@anchor{3ae6}@anchor{library/asyncio-platforms platform-support}@anchor{3b53}@anchor{library/asyncio-platforms translation-repo}@anchor{3b54}
@subsubsection Platform Support


The @ref{b,,asyncio} module is designed to be portable,
but some platforms have subtle differences and limitations
due to the platforms” underlying architecture and capabilities.

@menu
* All Platforms:: 
* Windows: Windows<83>. 
* macOS: macOS<53>. 

@end menu

@node All Platforms,Windows<83>,,Platform Support
@anchor{library/asyncio-platforms all-platforms}@anchor{3b55}
@subsubsection All Platforms



@itemize *

@item 
@ref{3a5e,,loop.add_reader()} and @ref{3ae4,,loop.add_writer()}
cannot be used to monitor file I/O.
@end itemize

@node Windows<83>,macOS<53>,All Platforms,Platform Support
@anchor{library/asyncio-platforms windows}@anchor{3b56}
@subsubsection Windows


`Source code:' Lib/asyncio/proactor_events.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/proactor_events.py},
Lib/asyncio/windows_events.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/windows_events.py},
Lib/asyncio/windows_utils.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/windows_utils.py}


__________________________________________________________________



Άλλαξε στην έκδοση 3.8: On Windows, @ref{9fe,,ProactorEventLoop} is now the default event loop.


All event loops on Windows do not support the following methods:


@itemize *

@item 
@ref{3a43,,loop.create_unix_connection()} and
@ref{6d0,,loop.create_unix_server()} are not supported.
The @ref{1daa,,socket.AF_UNIX} socket family is specific to Unix.

@item 
@ref{3aed,,loop.add_signal_handler()} and
@ref{3aee,,loop.remove_signal_handler()} are not supported.
@end itemize

@ref{30b,,SelectorEventLoop} has the following limitations:


@itemize *

@item 
@ref{3b57,,SelectSelector} is used to wait on socket events:
it supports sockets and is limited to 512 sockets.

@item 
@ref{3a5e,,loop.add_reader()} and @ref{3ae4,,loop.add_writer()} only accept
socket handles (e.g. pipe file descriptors are not supported).

@item 
Pipes are not supported, so the @ref{3a8a,,loop.connect_read_pipe()}
and @ref{3a8b,,loop.connect_write_pipe()} methods are not implemented.

@item 
@ref{39ff,,Subprocesses} are not supported, i.e.
@ref{3a87,,loop.subprocess_exec()} and @ref{3a88,,loop.subprocess_shell()}
methods are not implemented.
@end itemize

@ref{9fe,,ProactorEventLoop} has the following limitations:


@itemize *

@item 
The @ref{3a5e,,loop.add_reader()} and @ref{3ae4,,loop.add_writer()}
methods are not supported.
@end itemize

The resolution of the monotonic clock on Windows is usually around 15.6
milliseconds.  The best resolution is 0.5 milliseconds. The resolution depends on the
hardware (availability of HPET@footnote{https://en.wikipedia.org/wiki/High_Precision_Event_Timer}) and on the
Windows configuration.

@menu
* Subprocess Support on Windows:: 

@end menu

@node Subprocess Support on Windows,,,Windows<83>
@anchor{library/asyncio-platforms asyncio-windows-subprocess}@anchor{3a89}@anchor{library/asyncio-platforms subprocess-support-on-windows}@anchor{3b58}
@subsubsection Subprocess Support on Windows


On Windows, the default event loop @ref{9fe,,ProactorEventLoop} supports
subprocesses, whereas @ref{30b,,SelectorEventLoop} does not.

@node macOS<53>,,Windows<83>,Platform Support
@anchor{library/asyncio-platforms macos}@anchor{3b59}
@subsubsection macOS


Modern macOS versions are fully supported.

@subsubheading macOS <= 10.8


On macOS 10.6, 10.7 and 10.8, the default event loop
uses @ref{3b5a,,selectors.KqueueSelector}, which does not support
character devices on these versions.  The @ref{30b,,SelectorEventLoop}
can be manually configured to use @ref{3b57,,SelectSelector}
or @ref{f96,,PollSelector} to support character devices on
these older versions of macOS.  Example:

@example
import asyncio
import selectors

selector = selectors.SelectSelector()
loop = asyncio.SelectorEventLoop(selector)
asyncio.set_event_loop(loop)
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Extending,High-level API Index,Platform Support,asyncio — Asynchronous I/O
@anchor{library/asyncio-extending doc}@anchor{3b5b}@anchor{library/asyncio-extending extending}@anchor{3b5c}@anchor{library/asyncio-extending translation-repo}@anchor{3b5d}
@subsubsection Extending


The main direction for @ref{b,,asyncio} extending is writing custom `event loop'
classes. Asyncio has helpers that could be used to simplify this task.

@cartouche
@quotation Σημείωση 
Third-parties should reuse existing asyncio code with caution,
a new Python version is free to break backward compatibility
in `internal' part of API.
@end quotation
@end cartouche

@menu
* Writing a Custom Event Loop:: 
* Future and Task private constructors:: 
* Task lifetime support:: 

@end menu

@node Writing a Custom Event Loop,Future and Task private constructors,,Extending
@anchor{library/asyncio-extending writing-a-custom-event-loop}@anchor{3b5e}
@subsubsection Writing a Custom Event Loop


@ref{d29,,asyncio.AbstractEventLoop} declares very many methods.  Implementing all them
from scratch is a tedious job.

A loop can get many common methods implementation for free by inheriting from
@code{asyncio.BaseEventLoop}.

In turn, the successor should implement a bunch of `private' methods declared but not
implemented in @code{asyncio.BaseEventLoop}.

For example, @code{loop.create_connection()} checks arguments, resolves DNS addresses, and
calls @code{loop._make_socket_transport()} that should be implemented by inherited class.
The @code{_make_socket_transport()} method is not documented and is considered as an
`internal' API.

@node Future and Task private constructors,Task lifetime support,Writing a Custom Event Loop,Extending
@anchor{library/asyncio-extending future-and-task-private-constructors}@anchor{3b5f}
@subsubsection Future and Task private constructors


@ref{f8b,,asyncio.Future} and @ref{460,,asyncio.Task} should be never created directly,
please use corresponding @ref{1038,,loop.create_future()} and @ref{463,,loop.create_task()},
or @ref{462,,asyncio.create_task()} factories instead.

However, third-party `event loops' may `reuse' built-in future and task implementations
for the sake of getting a complex and highly optimized code for free.

For this purpose the following, `private' constructors are listed:

@geindex __init__() (μέθοδος της asyncio.Future)
@anchor{library/asyncio-extending asyncio Future __init__}@anchor{3b60}
@deffn {Μέθοδος} Future.__init__ (*, loop=None)

Create a built-in future instance.

`loop' is an optional event loop instance.
@end deffn

@geindex __init__() (μέθοδος της asyncio.Task)
@anchor{library/asyncio-extending asyncio Task __init__}@anchor{3b61}
@deffn {Μέθοδος} Task.__init__ (coro, *, loop=None, name=None, context=None)

Create a built-in task instance.

`loop' is an optional event loop instance. The rest of arguments are described in
@ref{463,,loop.create_task()} description.


Άλλαξε στην έκδοση 3.11: `context' argument is added.

@end deffn

@node Task lifetime support,,Future and Task private constructors,Extending
@anchor{library/asyncio-extending task-lifetime-support}@anchor{3b62}
@subsubsection Task lifetime support


A third party task implementation should call the following functions to keep a task
visible by @ref{d20,,asyncio.all_tasks()} and @ref{88f,,asyncio.current_task()}:

@geindex _register_task() (στη μονάδα asyncio)
@anchor{library/asyncio-extending asyncio _register_task}@anchor{3b63}
@deffn {Συνάρτηση} asyncio._register_task (task)

Register a new `task' as managed by `asyncio'.

Call the function from a task constructor.
@end deffn

@geindex _unregister_task() (στη μονάδα asyncio)
@anchor{library/asyncio-extending asyncio _unregister_task}@anchor{3b64}
@deffn {Συνάρτηση} asyncio._unregister_task (task)

Unregister a `task' from `asyncio' internal structures.

The function should be called when a task is about to finish.
@end deffn

@geindex _enter_task() (στη μονάδα asyncio)
@anchor{library/asyncio-extending asyncio _enter_task}@anchor{3b65}
@deffn {Συνάρτηση} asyncio._enter_task (loop, task)

Switch the current task to the `task' argument.

Call the function just before executing a portion of embedded `coroutine'
(@ref{260e,,coroutine.send()} or @ref{904,,coroutine.throw()}).
@end deffn

@geindex _leave_task() (στη μονάδα asyncio)
@anchor{library/asyncio-extending asyncio _leave_task}@anchor{3b66}
@deffn {Συνάρτηση} asyncio._leave_task (loop, task)

Switch the current task back from `task' to @code{None}.

Call the function just after @ref{260e,,coroutine.send()} or @ref{904,,coroutine.throw()}
execution.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node High-level API Index,Low-level API Index,Extending,asyncio — Asynchronous I/O
@anchor{library/asyncio-api-index doc}@anchor{c4f}@anchor{library/asyncio-api-index high-level-api-index}@anchor{3b67}@anchor{library/asyncio-api-index translation-repo}@anchor{3b68}
@subsubsection High-level API Index


This page lists all high-level async/await enabled asyncio APIs.

@menu
* Tasks:: 
* Queues:: 
* Subprocesses: Subprocesses<2>. 
* Streams: Streams<2>. 
* Synchronization:: 
* Exceptions: Exceptions<15>. 

@end menu

@node Tasks,Queues,,High-level API Index
@anchor{library/asyncio-api-index tasks}@anchor{3b69}
@subsubsection Tasks


Utilities to run asyncio programs, create Tasks, and
await on multiple things with timeouts.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{309,,run()}

@tab

Create event loop, run a coroutine, close the loop.

@item

@ref{30a,,Runner}

@tab

A context manager that simplifies multiple async function calls.

@item

@ref{460,,Task}

@tab

Task object.

@item

@ref{6d7,,TaskGroup}

@tab

A context manager that holds a group of tasks. Provides
a convenient and reliable way to wait for all tasks in the group to
finish.

@item

@ref{462,,create_task()}

@tab

Start an asyncio Task, then returns it.

@item

@ref{88f,,current_task()}

@tab

Return the current Task.

@item

@ref{d20,,all_tasks()}

@tab

Return all tasks that are not yet finished for an event loop.

@item

@code{await} @ref{e33,,sleep()}

@tab

Sleep for a number of seconds.

@item

@code{await} @ref{9f4,,gather()}

@tab

Schedule and wait for things concurrently.

@item

@code{await} @ref{9f6,,wait_for()}

@tab

Run with a timeout.

@item

@code{await} @ref{e34,,shield()}

@tab

Shield from cancellation.

@item

@code{await} @ref{891,,wait()}

@tab

Monitor for completion.

@item

@ref{9f5,,timeout()}

@tab

Run with a timeout. Useful in cases when @code{wait_for} is not suitable.

@item

@ref{cb9,,to_thread()}

@tab

Asynchronously run a function in a separate OS thread.

@item

@ref{c58,,run_coroutine_threadsafe()}

@tab

Schedule a coroutine from another OS thread.

@item

@code{for in} @ref{6cc,,as_completed()}

@tab

Monitor for completion with a @code{for} loop.

@end multitable


@subsubheading Examples



@itemize *

@item 
@ref{3a1d,,Using asyncio.gather() to run things in parallel}.

@item 
@ref{3a25,,Using asyncio.wait_for() to enforce a timeout}.

@item 
@ref{3a3a,,Cancellation}.

@item 
@ref{3a1b,,Using asyncio.sleep()}.

@item 
See also the main @ref{39fe,,Tasks documentation page}.
@end itemize

@node Queues,Subprocesses<2>,Tasks,High-level API Index
@anchor{library/asyncio-api-index queues}@anchor{3b6a}
@subsubsection Queues


Queues should be used to distribute work amongst multiple asyncio Tasks,
implement connection pools, and pub/sub patterns.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{e39,,Queue}

@tab

A FIFO queue.

@item

@ref{3aad,,PriorityQueue}

@tab

A priority queue.

@item

@ref{3aaf,,LifoQueue}

@tab

A LIFO queue.

@end multitable


@subsubheading Examples



@itemize *

@item 
@ref{3ab1,,Using asyncio.Queue to distribute workload between several Tasks}.

@item 
See also the @ref{3a00,,Queues documentation page}.
@end itemize

@node Subprocesses<2>,Streams<2>,Queues,High-level API Index
@anchor{library/asyncio-api-index subprocesses}@anchor{3b6b}
@subsubsection Subprocesses


Utilities to spawn subprocesses and run shell commands.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{e3a,,create_subprocess_exec()}

@tab

Create a subprocess.

@item

@code{await} @ref{e3b,,create_subprocess_shell()}

@tab

Run a shell command.

@end multitable


@subsubheading Examples



@itemize *

@item 
@ref{3a81,,Executing a shell command}.

@item 
See also the @ref{39ff,,subprocess APIs}
documentation.
@end itemize

@node Streams<2>,Synchronization,Subprocesses<2>,High-level API Index
@anchor{library/asyncio-api-index streams}@anchor{3b6c}
@subsubsection Streams


High-level APIs to work with network IO.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{edc,,open_connection()}

@tab

Establish a TCP connection.

@item

@code{await} @ref{3a42,,open_unix_connection()}

@tab

Establish a Unix socket connection.

@item

@code{await} @ref{edd,,start_server()}

@tab

Start a TCP server.

@item

@code{await} @ref{3a44,,start_unix_server()}

@tab

Start a Unix socket server.

@item

@ref{194a,,StreamReader}

@tab

High-level async/await object to receive network data.

@item

@ref{1c76,,StreamWriter}

@tab

High-level async/await object to send network data.

@end multitable


@subsubheading Examples



@itemize *

@item 
@ref{3a3e,,Example TCP client}.

@item 
See also the @ref{19b0,,streams APIs}
documentation.
@end itemize

@node Synchronization,Exceptions<15>,Streams<2>,High-level API Index
@anchor{library/asyncio-api-index synchronization}@anchor{3b6d}
@subsubsection Synchronization


Threading-like synchronization primitives that can be used in Tasks.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{e35,,Lock}

@tab

A mutex lock.

@item

@ref{56d,,Event}

@tab

An event object.

@item

@ref{e36,,Condition}

@tab

A condition object.

@item

@ref{e37,,Semaphore}

@tab

A semaphore.

@item

@ref{e38,,BoundedSemaphore}

@tab

A bounded semaphore.

@item

@ref{9f7,,Barrier}

@tab

A barrier object.

@end multitable


@subsubheading Examples



@itemize *

@item 
@ref{3a6a,,Using asyncio.Event}.

@item 
@ref{3a78,,Using asyncio.Barrier}.

@item 
See also the documentation of asyncio
@ref{3a01,,synchronization primitives}.
@end itemize

@node Exceptions<15>,,Synchronization,High-level API Index
@anchor{library/asyncio-api-index exceptions}@anchor{3b6e}
@subsubsection Exceptions



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{6da,,asyncio.CancelledError}

@tab

Raised when a Task is cancelled. See also @ref{6d9,,Task.cancel()}.

@item

@ref{9f8,,asyncio.BrokenBarrierError}

@tab

Raised when a Barrier is broken. See also @ref{3a77,,Barrier.wait()}.

@end multitable


@subsubheading Examples



@itemize *

@item 
@ref{3a3a,,Handling CancelledError to run code on cancellation request}.

@item 
See also the full list of
@ref{3ab3,,asyncio-specific exceptions}.
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Low-level API Index,Developing with asyncio,High-level API Index,asyncio — Asynchronous I/O
@anchor{library/asyncio-llapi-index doc}@anchor{3b6f}@anchor{library/asyncio-llapi-index low-level-api-index}@anchor{3b70}@anchor{library/asyncio-llapi-index translation-repo}@anchor{3b71}
@subsubsection Low-level API Index


This page lists all low-level asyncio APIs.

@menu
* Obtaining the Event Loop:: 
* Event Loop Methods:: 
* Transports: Transports<2>. 
* Protocols: Protocols<3>. 
* Event Loop Policies:: 

@end menu

@node Obtaining the Event Loop,Event Loop Methods,,Low-level API Index
@anchor{library/asyncio-llapi-index obtaining-the-event-loop}@anchor{3b72}
@subsubsection Obtaining the Event Loop



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{ecf,,asyncio.get_running_loop()}

@tab

The `preferred' function to get the running event loop.

@item

@ref{56c,,asyncio.get_event_loop()}

@tab

Get an event loop instance (running or current via the current policy).

@item

@ref{1d53,,asyncio.set_event_loop()}

@tab

Set the event loop as current via the current policy.

@item

@ref{3a0b,,asyncio.new_event_loop()}

@tab

Create a new event loop.

@end multitable


@subsubheading Examples



@itemize *

@item 
@ref{3b0f,,Using asyncio.get_running_loop()}.
@end itemize

@node Event Loop Methods,Transports<2>,Obtaining the Event Loop,Low-level API Index
@anchor{library/asyncio-llapi-index event-loop-methods}@anchor{3b73}
@subsubsection Event Loop Methods


See also the main documentation section about the
@ref{3aca,,Event loop methods}.

@subsubheading Lifecycle



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{1036,,loop.run_until_complete()}

@tab

Run a Future/Task/awaitable until complete.

@item

@ref{3acc,,loop.run_forever()}

@tab

Run the event loop forever.

@item

@ref{103b,,loop.stop()}

@tab

Stop the event loop.

@item

@ref{3ace,,loop.close()}

@tab

Close the event loop.

@item

@ref{3acd,,loop.is_running()}

@tab

Return @code{True} if the event loop is running.

@item

@ref{117c,,loop.is_closed()}

@tab

Return @code{True} if the event loop is closed.

@item

@code{await} @ref{103d,,loop.shutdown_asyncgens()}

@tab

Close asynchronous generators.

@end multitable


@subsubheading Debugging



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{117a,,loop.set_debug()}

@tab

Enable or disable the debug mode.

@item

@ref{117b,,loop.get_debug()}

@tab

Get the current debug mode.

@end multitable


@subsubheading Scheduling Callbacks



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{ec8,,loop.call_soon()}

@tab

Invoke a callback soon.

@item

@ref{ec9,,loop.call_soon_threadsafe()}

@tab

A thread-safe variant of @ref{ec8,,loop.call_soon()}.

@item

@ref{eca,,loop.call_later()}

@tab

Invoke a callback `after' the given time.

@item

@ref{ecb,,loop.call_at()}

@tab

Invoke a callback `at' the given time.

@end multitable


@subsubheading Thread/Interpreter/Process Pool



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{cba,,loop.run_in_executor()}

@tab

Run a CPU-bound or other blocking function in
a @ref{24,,concurrent.futures} executor.

@item

@ref{b28,,loop.set_default_executor()}

@tab

Set the default executor for @ref{cba,,loop.run_in_executor()}.

@end multitable


@subsubheading Tasks and Futures



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{1038,,loop.create_future()}

@tab

Create a @ref{f8b,,Future} object.

@item

@ref{463,,loop.create_task()}

@tab

Schedule coroutine as a @ref{460,,Task}.

@item

@ref{461,,loop.set_task_factory()}

@tab

Set a factory used by @ref{463,,loop.create_task()} to
create @ref{460,,Tasks}.

@item

@ref{117e,,loop.get_task_factory()}

@tab

Get the factory @ref{463,,loop.create_task()} uses
to create @ref{460,,Tasks}.

@end multitable


@subsubheading DNS



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{fd3,,loop.getaddrinfo()}

@tab

Asynchronous version of @ref{1925,,socket.getaddrinfo()}.

@item

@code{await} @ref{fd4,,loop.getnameinfo()}

@tab

Asynchronous version of @ref{1c42,,socket.getnameinfo()}.

@end multitable


@subsubheading Networking and IPC



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{9f9,,loop.create_connection()}

@tab

Open a TCP connection.

@item

@code{await} @ref{ed7,,loop.create_server()}

@tab

Create a TCP server.

@item

@code{await} @ref{3a43,,loop.create_unix_connection()}

@tab

Open a Unix socket connection.

@item

@code{await} @ref{6d0,,loop.create_unix_server()}

@tab

Create a Unix socket server.

@item

@code{await} @ref{bbb,,loop.connect_accepted_socket()}

@tab

Wrap a @ref{115a,,socket} into a @code{(transport, protocol)}
pair.

@item

@code{await} @ref{b1a,,loop.create_datagram_endpoint()}

@tab

Open a datagram (UDP) connection.

@item

@code{await} @ref{3ae0,,loop.sendfile()}

@tab

Send a file over a transport.

@item

@code{await} @ref{ecd,,loop.start_tls()}

@tab

Upgrade an existing connection to TLS.

@item

@code{await} @ref{3a8a,,loop.connect_read_pipe()}

@tab

Wrap a read end of a pipe into a @code{(transport, protocol)} pair.

@item

@code{await} @ref{3a8b,,loop.connect_write_pipe()}

@tab

Wrap a write end of a pipe into a @code{(transport, protocol)} pair.

@end multitable


@subsubheading Sockets



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{fd0,,loop.sock_recv()}

@tab

Receive data from the @ref{115a,,socket}.

@item

@code{await} @ref{ece,,loop.sock_recv_into()}

@tab

Receive data from the @ref{115a,,socket} into a buffer.

@item

@code{await} @ref{9fc,,loop.sock_recvfrom()}

@tab

Receive a datagram from the @ref{115a,,socket}.

@item

@code{await} @ref{9fd,,loop.sock_recvfrom_into()}

@tab

Receive a datagram from the @ref{115a,,socket} into a buffer.

@item

@code{await} @ref{fd1,,loop.sock_sendall()}

@tab

Send data to the @ref{115a,,socket}.

@item

@code{await} @ref{9fb,,loop.sock_sendto()}

@tab

Send a datagram via the @ref{115a,,socket} to the given address.

@item

@code{await} @ref{1181,,loop.sock_connect()}

@tab

Connect the @ref{115a,,socket}.

@item

@code{await} @ref{fd2,,loop.sock_accept()}

@tab

Accept a @ref{115a,,socket} connection.

@item

@code{await} @ref{ed2,,loop.sock_sendfile()}

@tab

Send a file over the @ref{115a,,socket}.

@item

@ref{3a5e,,loop.add_reader()}

@tab

Start watching a file descriptor for read availability.

@item

@ref{3ae3,,loop.remove_reader()}

@tab

Stop watching a file descriptor for read availability.

@item

@ref{3ae4,,loop.add_writer()}

@tab

Start watching a file descriptor for write availability.

@item

@ref{3ae5,,loop.remove_writer()}

@tab

Stop watching a file descriptor for write availability.

@end multitable


@subsubheading Unix Signals



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{3aed,,loop.add_signal_handler()}

@tab

Add a handler for a @ref{ce,,signal}.

@item

@ref{3aee,,loop.remove_signal_handler()}

@tab

Remove a handler for a @ref{ce,,signal}.

@end multitable


@subsubheading Subprocesses



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{3a87,,loop.subprocess_exec()}

@tab

Spawn a subprocess.

@item

@ref{3a88,,loop.subprocess_shell()}

@tab

Spawn a subprocess from a shell command.

@end multitable


@subsubheading Error Handling



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{3af2,,loop.call_exception_handler()}

@tab

Call the exception handler.

@item

@ref{3af1,,loop.set_exception_handler()}

@tab

Set a new exception handler.

@item

@ref{1039,,loop.get_exception_handler()}

@tab

Get the current exception handler.

@item

@ref{3af3,,loop.default_exception_handler()}

@tab

The default exception handler implementation.

@end multitable


@subsubheading Examples



@itemize *

@item 
@ref{3afe,,Using asyncio.new_event_loop() and loop.run_forever()}.

@item 
@ref{3b00,,Using loop.call_later()}.

@item 
Using @code{loop.create_connection()} to implement
@ref{3a55,,an echo-client}.

@item 
Using @code{loop.create_connection()} to
@ref{3a5c,,connect a socket}.

@item 
@ref{3a5d,,Using add_reader() to watch an FD for read events}.

@item 
@ref{3b03,,Using loop.add_signal_handler()}.

@item 
@ref{3a9c,,Using loop.subprocess_exec()}.
@end itemize

@node Transports<2>,Protocols<3>,Event Loop Methods,Low-level API Index
@anchor{library/asyncio-llapi-index transports}@anchor{3b74}
@subsubsection Transports


All transports implement the following methods:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{3ada,,transport.close()}

@tab

Close the transport.

@item

@ref{1037,,transport.is_closing()}

@tab

Return @code{True} if the transport is closing or is closed.

@item

@ref{e62,,transport.get_extra_info()}

@tab

Request for information about the transport.

@item

@ref{3b1f,,transport.set_protocol()}

@tab

Set a new protocol.

@item

@ref{3b20,,transport.get_protocol()}

@tab

Return the current protocol.

@end multitable


Transports that can receive data (TCP and Unix connections,
pipes, etc).  Returned from methods like
@ref{9f9,,loop.create_connection()}, @ref{3a43,,loop.create_unix_connection()},
@ref{3a8a,,loop.connect_read_pipe()}, etc:

@subsubheading Read Transports



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{edf,,transport.is_reading()}

@tab

Return @code{True} if the transport is receiving.

@item

@ref{ee1,,transport.pause_reading()}

@tab

Pause receiving.

@item

@ref{ee0,,transport.resume_reading()}

@tab

Resume receiving.

@end multitable


Transports that can Send data (TCP and Unix connections,
pipes, etc).  Returned from methods like
@ref{9f9,,loop.create_connection()}, @ref{3a43,,loop.create_unix_connection()},
@ref{3a8b,,loop.connect_write_pipe()}, etc:

@subsubheading Write Transports



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{1a0a,,transport.write()}

@tab

Write data to the transport.

@item

@ref{1a09,,transport.writelines()}

@tab

Write buffers to the transport.

@item

@ref{3b23,,transport.can_write_eof()}

@tab

Return @ref{fcc,,True} if the transport supports sending EOF.

@item

@ref{3b24,,transport.write_eof()}

@tab

Close and send EOF after flushing buffered data.

@item

@ref{3afb,,transport.abort()}

@tab

Close the transport immediately.

@item

@ref{192c,,transport.get_write_buffer_size()}

@tab

Return the current size of the output buffer.

@item

@ref{117d,,transport.get_write_buffer_limits()}

@tab

Return high and low water marks for write flow control.

@item

@ref{3b25,,transport.set_write_buffer_limits()}

@tab

Set new high and low water marks for write flow control.

@end multitable


Transports returned by @ref{b1a,,loop.create_datagram_endpoint()}:

@subsubheading Datagram Transports



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{6d1,,transport.sendto()}

@tab

Send data to the remote peer.

@item

@ref{3b29,,transport.abort()}

@tab

Close the transport immediately.

@end multitable


Low-level transport abstraction over subprocesses.
Returned by @ref{3a87,,loop.subprocess_exec()} and
@ref{3a88,,loop.subprocess_shell()}:

@subsubheading Subprocess Transports



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{3b2b,,transport.get_pid()}

@tab

Return the subprocess process id.

@item

@ref{3b2c,,transport.get_pipe_transport()}

@tab

Return the transport for the requested communication pipe
(`stdin', `stdout', or `stderr').

@item

@ref{3b2d,,transport.get_returncode()}

@tab

Return the subprocess return code.

@item

@ref{3b2e,,transport.kill()}

@tab

Kill the subprocess.

@item

@ref{3b30,,transport.send_signal()}

@tab

Send a signal to the subprocess.

@item

@ref{3b2f,,transport.terminate()}

@tab

Stop the subprocess.

@item

@ref{3b31,,transport.close()}

@tab

Kill the subprocess and close all pipes.

@end multitable


@node Protocols<3>,Event Loop Policies,Transports<2>,Low-level API Index
@anchor{library/asyncio-llapi-index protocols}@anchor{3b75}
@subsubsection Protocols


Protocol classes can implement the following `callback methods':


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{3ad8,,connection_made()}

@tab

Called when a connection is made.

@item

@code{callback} @ref{3b1c,,connection_lost()}

@tab

Called when the connection is lost or closed.

@item

@code{callback} @ref{3b26,,pause_writing()}

@tab

Called when the transport’s buffer goes over the high water mark.

@item

@code{callback} @ref{3b27,,resume_writing()}

@tab

Called when the transport’s buffer drains below the low water mark.

@end multitable


@subsubheading Streaming Protocols (TCP, Unix Sockets, Pipes)



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{1d01,,data_received()}

@tab

Called when some data is received.

@item

@code{callback} @ref{3b35,,eof_received()}

@tab

Called when an EOF is received.

@end multitable


@subsubheading Buffered Streaming Protocols



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{3b37,,get_buffer()}

@tab

Called to allocate a new receive buffer.

@item

@code{callback} @ref{3b38,,buffer_updated()}

@tab

Called when the buffer was updated with the received data.

@item

@code{callback} @ref{3b39,,eof_received()}

@tab

Called when an EOF is received.

@end multitable


@subsubheading Datagram Protocols



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{3b3b,,datagram_received()}

@tab

Called when a datagram is received.

@item

@code{callback} @ref{3b3c,,error_received()}

@tab

Called when a previous send or receive operation raises an
@ref{53c,,OSError}.

@end multitable


@subsubheading Subprocess Protocols



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{1d4e,,pipe_data_received()}

@tab

Called when the child process writes data into its
`stdout' or `stderr' pipe.

@item

@code{callback} @ref{3b3e,,pipe_connection_lost()}

@tab

Called when one of the pipes communicating with
the child process is closed.

@item

@code{callback} @ref{1d4d,,process_exited()}

@tab

Called when the child process has exited. It can be called before
@ref{1d4e,,pipe_data_received()} and
@ref{3b3e,,pipe_connection_lost()} methods.

@end multitable


@node Event Loop Policies,,Protocols<3>,Low-level API Index
@anchor{library/asyncio-llapi-index event-loop-policies}@anchor{3b76}
@subsubsection Event Loop Policies


Policies is a low-level mechanism to alter the behavior of
functions like @ref{56c,,asyncio.get_event_loop()}.  See also
the main @ref{3ac4,,policies section} for more
details.

@subsubheading Accessing Policies



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{307,,asyncio.get_event_loop_policy()}

@tab

Return the current process-wide policy.

@item

@ref{308,,asyncio.set_event_loop_policy()}

@tab

Set a new process-wide policy.

@item

@ref{303,,AbstractEventLoopPolicy}

@tab

Base class for policy objects.

@end multitable


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Developing with asyncio,,Low-level API Index,asyncio — Asynchronous I/O
@anchor{library/asyncio-dev doc}@anchor{3b77}@anchor{library/asyncio-dev asyncio-dev}@anchor{3b78}@anchor{library/asyncio-dev developing-with-asyncio}@anchor{3b79}@anchor{library/asyncio-dev translation-repo}@anchor{3b7a}
@subsubsection Developing with asyncio


Asynchronous programming is different from classic «sequential»
programming.

This page lists common mistakes and traps and explains how
to avoid them.

@menu
* Debug Mode:: 
* Concurrency and Multithreading:: 
* Running Blocking Code:: 
* Logging: Logging<3>. 
* Detect never-awaited coroutines:: 
* Detect never-retrieved exceptions:: 
* Asynchronous generators best practices:: 

@end menu

@node Debug Mode,Concurrency and Multithreading,,Developing with asyncio
@anchor{library/asyncio-dev asyncio-debug-mode}@anchor{2328}@anchor{library/asyncio-dev debug-mode}@anchor{3b7b}
@subsubsection Debug Mode


By default asyncio runs in production mode.  In order to ease
the development asyncio has a `debug mode'.

There are several ways to enable asyncio debug mode:


@itemize *

@item 
Setting the 
@geindex PYTHONASYNCIODEBUG
@geindex μεταβλητή περιβάλλοντος; PYTHONASYNCIODEBUG
@ref{2327,,PYTHONASYNCIODEBUG} environment variable to @code{1}.

@item 
Using the @ref{70d,,Python Development Mode}.

@item 
Passing @code{debug=True} to @ref{309,,asyncio.run()}.

@item 
Calling @ref{117a,,loop.set_debug()}.
@end itemize

In addition to enabling the debug mode, consider also:


@itemize *

@item 
setting the log level of the @ref{3b7c,,asyncio logger} to
@ref{22cd,,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 
configuring the @ref{11b,,warnings} module to display
@ref{74f,,ResourceWarning} warnings.  One way of doing that is by
using the @ref{1c0,,-W} @code{default} command line option.
@end itemize

When the debug mode is enabled:


@itemize *

@item 
Many non-threadsafe asyncio APIs (such as @ref{ec8,,loop.call_soon()} and
@ref{ecb,,loop.call_at()} methods) raise an exception if they are called
from a wrong thread.

@item 
The execution time of the I/O selector is logged if it takes too long to
perform an I/O operation.

@item 
Callbacks taking longer than 100 milliseconds are logged.  The
@ref{3af5,,loop.slow_callback_duration} attribute can be used to set the
minimum execution duration in seconds that is considered «slow».
@end itemize

@node Concurrency and Multithreading,Running Blocking Code,Debug Mode,Developing with asyncio
@anchor{library/asyncio-dev asyncio-multithreading}@anchor{3a2c}@anchor{library/asyncio-dev concurrency-and-multithreading}@anchor{3b7d}
@subsubsection Concurrency and Multithreading


An event loop runs in a thread (typically the main thread) and executes
all callbacks and Tasks in its thread.  While a Task is running in the
event loop, no other Tasks can run in the same thread.  When a Task
executes an @code{await} expression, the running Task gets suspended, and
the event loop executes the next Task.

To schedule a @ref{2fc5,,callback} from another OS thread, the
@ref{ec9,,loop.call_soon_threadsafe()} method should be used. Example:

@example
loop.call_soon_threadsafe(callback, *args)
@end example

Almost all asyncio objects are not thread safe, which is typically
not a problem unless there is code that works with them from outside
of a Task or a callback.  If there’s a need for such code to call a
low-level asyncio API, the @ref{ec9,,loop.call_soon_threadsafe()} method
should be used, e.g.:

@example
loop.call_soon_threadsafe(fut.cancel)
@end example

To schedule a coroutine object from a different OS thread, the
@ref{c58,,run_coroutine_threadsafe()} function should be used. It returns a
@ref{155b,,concurrent.futures.Future} to access the result:

@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.

The @ref{cba,,loop.run_in_executor()} method can be used with a
@ref{b27,,concurrent.futures.ThreadPoolExecutor} or
@ref{46a,,InterpreterPoolExecutor} to execute
blocking code in a different OS thread without blocking the OS thread
that the event loop runs in.

There is currently no way to schedule coroutines or callbacks directly
from a different process (such as one started with
@ref{98,,multiprocessing}). The @ref{3aca,,Event loop methods}
section lists APIs that can read from pipes and watch file descriptors
without blocking the event loop. In addition, asyncio’s
@ref{39ff,,Subprocess} APIs provide a way to start a
process and communicate with it from the event loop. Lastly, the
aforementioned @ref{cba,,loop.run_in_executor()} method can also be used
with a @ref{206,,concurrent.futures.ProcessPoolExecutor} to execute
code in a different process.

@node Running Blocking Code,Logging<3>,Concurrency and Multithreading,Developing with asyncio
@anchor{library/asyncio-dev asyncio-handle-blocking}@anchor{3b7e}@anchor{library/asyncio-dev running-blocking-code}@anchor{3b7f}
@subsubsection Running Blocking Code


Blocking (CPU-bound) code should not be called directly.  For example,
if a function performs a CPU-intensive calculation for 1 second,
all concurrent asyncio Tasks and IO operations would be delayed
by 1 second.

An executor can be used to run a task in a different thread,
including in a different interpreter, or even in
a different process to avoid blocking the OS thread with the
event loop.  See the @ref{cba,,loop.run_in_executor()} method for more
details.

@node Logging<3>,Detect never-awaited coroutines,Running Blocking Code,Developing with asyncio
@anchor{library/asyncio-dev asyncio-logger}@anchor{3b7c}@anchor{library/asyncio-dev logging}@anchor{3b80}
@subsubsection Logging


asyncio uses the @ref{8a,,logging} module and all logging is performed
via the @code{"asyncio"} logger.

The default log level is @ref{22ce,,logging.INFO}, which can be easily
adjusted:

@example
logging.getLogger("asyncio").setLevel(logging.WARNING)
@end example

Network logging can block the event loop. It is recommended to use
a separate thread for handling logs or use non-blocking IO. For example,
see @ref{3b81,,Dealing with handlers that block}.

@node Detect never-awaited coroutines,Detect never-retrieved exceptions,Logging<3>,Developing with asyncio
@anchor{library/asyncio-dev asyncio-coroutine-not-scheduled}@anchor{3b82}@anchor{library/asyncio-dev detect-never-awaited-coroutines}@anchor{3b83}
@subsubsection Detect never-awaited coroutines


When a coroutine function is called, but not awaited
(e.g. @code{coro()} instead of @code{await coro()})
or the coroutine is not scheduled with @ref{462,,asyncio.create_task()}, asyncio
will emit a @ref{6dd,,RuntimeWarning}:

@example
import asyncio

async def test():
    print("never scheduled")

async def main():
    test()

asyncio.run(main())
@end example

Output:

@example
test.py:7: RuntimeWarning: coroutine 'test' was never awaited
  test()
@end example

Output in debug mode:

@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

The usual fix is to either await the coroutine or call the
@ref{462,,asyncio.create_task()} function:

@example
async def main():
    await test()
@end example

@node Detect never-retrieved exceptions,Asynchronous generators best practices,Detect never-awaited coroutines,Developing with asyncio
@anchor{library/asyncio-dev detect-never-retrieved-exceptions}@anchor{3b84}
@subsubsection Detect never-retrieved exceptions


If a @ref{103c,,Future.set_exception()} is called but the Future object is
never awaited on, the exception would never be propagated to the
user code.  In this case, asyncio would emit a log message when the
Future object is garbage collected.

Example of an unhandled exception:

@example
import asyncio

async def bug():
    raise Exception("not consumed")

async def main():
    asyncio.create_task(bug())

asyncio.run(main())
@end example

Output:

@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{2328,,Enable the debug mode} to get the
traceback where the task was created:

@example
asyncio.run(main(), debug=True)
@end example

Output in debug mode:

@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

@node Asynchronous generators best practices,,Detect never-retrieved exceptions,Developing with asyncio
@anchor{library/asyncio-dev asynchronous-generators-best-practices}@anchor{3b85}
@subsubsection Asynchronous generators best practices


Writing correct and efficient asyncio code requires awareness of certain pitfalls.
This section outlines essential best practices that can save you hours of debugging.

@menu
* Close asynchronous generators explicitly:: 
* Create asynchronous generators only when the event loop is running:: 
* Avoid concurrent iteration and closure of the same generator:: 

@end menu

@node Close asynchronous generators explicitly,Create asynchronous generators only when the event loop is running,,Asynchronous generators best practices
@anchor{library/asyncio-dev close-asynchronous-generators-explicitly}@anchor{3b86}
@subsubsection Close asynchronous generators explicitly


It is recommended to manually close the
@ref{3b87,,asynchronous generator}. If a generator
exits early - for example, due to an exception raised in the body of
an @code{async for} loop - its asynchronous cleanup code may run in an
unexpected context. This can occur after the tasks it depends on have completed,
or during the event loop shutdown when the async-generator’s garbage collection
hook is called.

To avoid this, explicitly close the generator by calling its
@ref{caa,,aclose()} method, or use the @ref{bc9,,contextlib.aclosing()}
context manager:

@example
import asyncio
import contextlib

async def gen():
  yield 1
  yield 2

async def func():
  async with contextlib.aclosing(gen()) as g:
    async for x in g:
      break  # Don't iterate until the end

asyncio.run(func())
@end example

As noted above, the cleanup code for these asynchronous generators is deferred.
The following example demonstrates that the finalization of an asynchronous
generator can occur in an unexpected order:

@example
import asyncio
work_done = False

async def cursor():
    try:
        yield 1
    finally:
        assert work_done

async def rows():
    global work_done
    try:
        yield 2
    finally:
        await asyncio.sleep(0.1) # imitate some async work
        work_done = True


async def main():
    async for c in cursor():
        async for r in rows():
            break
        break

asyncio.run(main())
@end example

For this example, we get the following output:

@example
unhandled exception during asyncio.run() shutdown
task: <Task finished name='Task-3' coro=<<async_generator_athrow without __name__>()> exception=AssertionError()>
Traceback (most recent call last):
  File "example.py", line 6, in cursor
    yield 1
asyncio.exceptions.CancelledError

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "example.py", line 8, in cursor
    assert work_done
           ^^^^^^^^^
AssertionError
@end example

The @code{cursor()} asynchronous generator was finalized before the @code{rows}
generator - an unexpected behavior.

The example can be fixed by explicitly closing the
@code{cursor} and @code{rows} async-generators:

@example
async def main():
    async with contextlib.aclosing(cursor()) as cursor_gen:
        async for c in cursor_gen:
            async with contextlib.aclosing(rows()) as rows_gen:
                async for r in rows_gen:
                    break
            break
@end example

@node Create asynchronous generators only when the event loop is running,Avoid concurrent iteration and closure of the same generator,Close asynchronous generators explicitly,Asynchronous generators best practices
@anchor{library/asyncio-dev create-asynchronous-generators-only-when-the-event-loop-is-running}@anchor{3b88}
@subsubsection Create asynchronous generators only when the event loop is running


It is recommended to create
@ref{3b87,,asynchronous generators} only after
the event loop has been created.

To ensure that asynchronous generators close reliably, the event loop uses the
@ref{1baa,,sys.set_asyncgen_hooks()} function to register callback functions. These
callbacks update the list of running asynchronous generators to keep it in a
consistent state.

When the @ref{103d,,loop.shutdown_asyncgens()}
function is called, the running generators are stopped gracefully and the
list is cleared.

The asynchronous generator invokes the corresponding system hook during its
first iteration. At the same time, the generator records that the hook has
been called and does not call it again.

Therefore, if iteration begins before the event loop is created,
the event loop will not be able to add the generator to its list of active
generators because the hooks are set after the generator attempts to call them.
Consequently, the event loop will not be able to terminate the generator
if necessary.

Consider the following example:

@example
import asyncio

async def agenfn():
    try:
        yield 10
    finally:
        await asyncio.sleep(0)


with asyncio.Runner() as runner:
    agen = agenfn()
    print(runner.run(anext(agen)))
    del agen
@end example

Output:

@example
10
Exception ignored while closing generator <async_generator object agenfn at 0x000002F71CD10D70>:
Traceback (most recent call last):
  File "example.py", line 13, in <module>
    del agen
        ^^^^
RuntimeError: async generator ignored GeneratorExit
@end example

This example can be fixed as follows:

@example
import asyncio

async def agenfn():
    try:
        yield 10
    finally:
        await asyncio.sleep(0)

async def main():
    agen = agenfn()
    print(await anext(agen))
    del agen

asyncio.run(main())
@end example

@node Avoid concurrent iteration and closure of the same generator,,Create asynchronous generators only when the event loop is running,Asynchronous generators best practices
@anchor{library/asyncio-dev avoid-concurrent-iteration-and-closure-of-the-same-generator}@anchor{3b89}
@subsubsection Avoid concurrent iteration and closure of the same generator


Async generators may be reentered while another
@ref{2697,,__anext__()} / @ref{906,,athrow()} / @ref{caa,,aclose()} call is in
progress. This may lead to an inconsistent state of the async generator and can
cause errors.

Let’s consider the following example:

@example
import asyncio

async def consumer():
    for idx in range(100):
        await asyncio.sleep(0)
        message = yield idx
        print('received', message)

async def amain():
    agenerator = consumer()
    await agenerator.asend(None)

    fa = asyncio.create_task(agenerator.asend('A'))
    fb = asyncio.create_task(agenerator.asend('B'))
    await fa
    await fb

asyncio.run(amain())
@end example

Output:

@example
received A
Traceback (most recent call last):
  File "test.py", line 38, in <module>
    asyncio.run(amain())
    ~~~~~~~~~~~^^^^^^^^^
  File "Lib/asyncio/runners.py", line 204, in run
    return runner.run(main)
           ~~~~~~~~~~^^^^^^
  File "Lib/asyncio/runners.py", line 127, in run
    return self._loop.run_until_complete(task)
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^
  File "Lib/asyncio/base_events.py", line 719, in run_until_complete
    return future.result()
           ~~~~~~~~~~~~~^^
  File "test.py", line 36, in amain
    await fb
RuntimeError: anext(): asynchronous generator is already running
@end example

Therefore, it is recommended to avoid using asynchronous generators in parallel
tasks or across multiple event loops.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@cartouche
@quotation Σημείωση 
The source code for asyncio can be found in Lib/asyncio/@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/}.
@end quotation
@end cartouche

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node socket — Low-level networking interface,ssl — TLS/SSL wrapper for socket objects,asyncio — Asynchronous I/O,Networking and Interprocess Communication
@anchor{library/socket doc}@anchor{3b8a}@anchor{library/socket module-socket}@anchor{d4}@anchor{library/socket socket-low-level-networking-interface}@anchor{3b8b}@anchor{library/socket translation-repo}@anchor{3b8c}
@subsection @code{socket} — Low-level networking interface


@geindex module; socket

`Source code:' Lib/socket.py@footnote{https://github.com/python/cpython/tree/main/Lib/socket.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 Σημείωση 
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{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} 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{115a,,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 Δείτε επίσης



@table @asis

@item Module @ref{d5,,socketserver}

Classes that simplify writing network servers.

@item Module @ref{d8,,ssl}

A TLS/SSL wrapper for socket objects.
@end table


@menu
* Socket families:: 
* Module contents: Module contents<3>. 
* Socket Objects:: 
* Notes on socket timeouts:: 
* Example: Example<7>. 

@end menu

@node Socket families,Module contents<3>,,socket — Low-level networking interface
@anchor{library/socket socket-addresses}@anchor{3b8d}@anchor{library/socket socket-families}@anchor{3b8e}
@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{1daa,,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{436,,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.


Άλλαξε στην έκδοση 3.3: Previously, @ref{1daa,,AF_UNIX} socket paths were assumed to use UTF-8
encoding.



Άλλαξε στην έκδοση 3.5: Writable @ref{436,,bytes-like object} is now accepted.

@end itemize
@anchor{library/socket host-port}@anchor{3b8f}

@itemize -

@item 
A pair @code{(host, port)} is used for the @ref{1da7,,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{1da8,,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
@code{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.


Άλλαξε στην έκδοση 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{3b90,,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{3b91,,CAN_ISOTP} protocol requires 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{cff,,CAN_J1939} protocol requires 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.


Added in version 3.3.


@item 
@ref{1da9,,AF_BLUETOOTH} supports the following protocols and address
formats:


@itemize -

@item 
@ref{50b,,BTPROTO_L2CAP} accepts a tuple
@code{(bdaddr, psm[, cid[, bdaddr_type]])} where:


@itemize -

@item 
@code{bdaddr} is a string specifying the Bluetooth address.

@item 
@code{psm} is an integer specifying the Protocol/Service Multiplexer.

@item 
@code{cid} is an optional integer specifying the Channel Identifier.
If not given, defaults to zero.

@item 
@code{bdaddr_type} is an optional integer specifying the address type;
one of @ref{3b92,,BDADDR_BREDR} (default), @ref{3b93,,BDADDR_LE_PUBLIC},
@ref{3b94,,BDADDR_LE_RANDOM}.
@end itemize


Άλλαξε στην έκδοση 3.14: Added @code{cid} and @code{bdaddr_type} fields.


@item 
@ref{3b95,,BTPROTO_RFCOMM} accepts @code{(bdaddr, channel)} where @code{bdaddr}
is the Bluetooth address as a string and @code{channel} is an integer.

@item 
@ref{509,,BTPROTO_HCI} accepts a format that depends on your OS.


@itemize -

@item 
On Linux it accepts an integer @code{device_id} or a tuple
@code{(device_id, [channel])} where @code{device_id}
specifies the number of the Bluetooth device,
and @code{channel} is an optional integer specifying the HCI channel
(@ref{3b96,,HCI_CHANNEL_RAW} by default).

@item 
On FreeBSD, NetBSD and DragonFly BSD it accepts @code{bdaddr}
where @code{bdaddr} is the Bluetooth address as a string.
@end itemize


Άλλαξε στην έκδοση 3.2: NetBSD and DragonFlyBSD support added.



Άλλαξε στην έκδοση 3.13.3: FreeBSD support added.



Άλλαξε στην έκδοση 3.14: Added @code{channel} field.
@code{device_id} not packed in a tuple is now accepted.


@item 
@ref{50a,,BTPROTO_SCO} accepts @code{bdaddr} where @code{bdaddr} is
the Bluetooth address as a string or a @ref{1c7,,bytes} object.
(ex. @code{'12:23:34:45:56:67'} or @code{b'12:23:34:45:56:67'})


Άλλαξε στην έκδοση 3.14: FreeBSD support added.

@end itemize

@item 
@ref{1094,,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{232d,,Διαθεσιμότητα}: Linux >= 2.6.38.

Some algorithm types require more recent Kernels.


Added in version 3.6.


@item 
@ref{f33,,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{232d,,Διαθεσιμότητα}: Linux >= 3.9

See @code{vsock(7)@footnote{https://manpages.debian.org/vsock(7)}}


Added in version 3.7.


@item 
@ref{3b97,,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{1d21,,ETH_P_ALL} to capture all protocols,
one of the @ref{1d22,,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{232d,,Διαθεσιμότητα}: Linux >= 2.2.

@item 
@ref{3b98,,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{232d,,Διαθεσιμότητα}: Linux >= 4.7.


Added in 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{232d,,Διαθεσιμότητα}: Linux >= 2.6.20, FreeBSD >= 10.1


Added in version 3.9.


@item 
@ref{3b99,,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.


Added in 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{53c,,OSError} or one of its
subclasses.

Non-blocking mode is supported through @ref{3261,,setblocking()}.  A
generalization of this based on timeouts is supported through
@ref{3b9a,,settimeout()}.

@node Module contents<3>,Socket Objects,Socket families,socket — Low-level networking interface
@anchor{library/socket module-contents}@anchor{3b9b}
@subsubsection Module contents


The module @code{socket} exports the following elements.

@menu
* Exceptions: Exceptions<16>. 
* Constants: Constants<8>. 
* Functions: Functions<6>. 

@end menu

@node Exceptions<16>,Constants<8>,,Module contents<3>
@anchor{library/socket exceptions}@anchor{3b9c}
@subsubsection Exceptions


@geindex error
@anchor{library/socket socket error}@anchor{13fe}
@deffn {Εξαίρεση} socket.error

A deprecated alias of @ref{53c,,OSError}.


Άλλαξε στην έκδοση 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{53c,,OSError}.

@end deffn

@geindex herror
@anchor{library/socket socket herror}@anchor{3b9d}
@deffn {Εξαίρεση} socket.herror

A subclass of @ref{53c,,OSError}, this exception is raised for
address-related errors, i.e. for functions that use `h_errno' in the POSIX
C API, including @ref{1e7b,,gethostbyname_ex()} and @ref{1e7a,,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.


Άλλαξε στην έκδοση 3.3: This class was made a subclass of @ref{53c,,OSError}.

@end deffn

@geindex gaierror
@anchor{library/socket socket gaierror}@anchor{1cc5}
@deffn {Εξαίρεση} socket.gaierror

A subclass of @ref{53c,,OSError}, this exception is raised for
address-related errors by @ref{1925,,getaddrinfo()} and @ref{1c42,,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.


Άλλαξε στην έκδοση 3.3: This class was made a subclass of @ref{53c,,OSError}.

@end deffn

@geindex timeout
@anchor{library/socket socket timeout}@anchor{c0d}
@deffn {Εξαίρεση} socket.timeout

A deprecated alias of @ref{c0e,,TimeoutError}.

A subclass of @ref{53c,,OSError}, this exception is raised when a timeout
occurs on a socket which has had timeouts enabled via a prior call to
@ref{3b9a,,settimeout()} (or implicitly through
@ref{3b9e,,setdefaulttimeout()}).  The accompanying value is a string
whose value is currently always «timed out».


Άλλαξε στην έκδοση 3.3: This class was made a subclass of @ref{53c,,OSError}.



Άλλαξε στην έκδοση 3.10: This class was made an alias of @ref{c0e,,TimeoutError}.

@end deffn

@node Constants<8>,Functions<6>,Exceptions<16>,Module contents<3>
@anchor{library/socket constants}@anchor{3b9f}
@subsubsection Constants


The AF_* and SOCK_* constants are now @code{AddressFamily} and
@code{SocketKind} @ref{109d,,IntEnum} collections.


Added in version 3.4.


@geindex AF_UNIX (στη μονάδα socket)
@geindex AF_INET (στη μονάδα socket)
@geindex AF_INET6 (στη μονάδα socket)
@anchor{library/socket socket AF_UNIX}@anchor{1daa}
@deffn {Δεδομένα} socket.AF_UNIX
@anchor{library/socket socket AF_INET}@anchor{1da7}
@deffnx {Δεδομένα} socket.AF_INET
@anchor{library/socket socket AF_INET6}@anchor{1da8}
@deffnx {Δεδομένα} socket.AF_INET6

These constants represent the address (and protocol) families, used for the
first argument to @ref{115a,,socket()}.  If the @ref{1daa,,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 (στη μονάδα socket)
@anchor{library/socket socket AF_UNSPEC}@anchor{3ade}
@deffn {Δεδομένα} socket.AF_UNSPEC

@ref{3ade,,AF_UNSPEC} means that
@ref{1925,,getaddrinfo()} should return socket addresses for any
address family (either IPv4, IPv6, or any other) that can be used.
@end deffn

@geindex SOCK_STREAM (στη μονάδα socket)
@geindex SOCK_DGRAM (στη μονάδα socket)
@geindex SOCK_RAW (στη μονάδα socket)
@geindex SOCK_RDM (στη μονάδα socket)
@geindex SOCK_SEQPACKET (στη μονάδα socket)
@anchor{library/socket socket SOCK_STREAM}@anchor{1698}
@deffn {Δεδομένα} socket.SOCK_STREAM
@anchor{library/socket socket SOCK_DGRAM}@anchor{1697}
@deffnx {Δεδομένα} socket.SOCK_DGRAM
@anchor{library/socket socket SOCK_RAW}@anchor{3ba0}
@deffnx {Δεδομένα} socket.SOCK_RAW
@anchor{library/socket socket SOCK_RDM}@anchor{3ba1}
@deffnx {Δεδομένα} socket.SOCK_RDM
@anchor{library/socket socket SOCK_SEQPACKET}@anchor{3ba2}
@deffnx {Δεδομένα} socket.SOCK_SEQPACKET

These constants represent the socket types, used for the second argument to
@ref{115a,,socket()}.  More constants may be available depending on the system.
(Only @ref{1698,,SOCK_STREAM} and @ref{1697,,SOCK_DGRAM} appear to be generally
useful.)
@end deffn

@geindex SOCK_CLOEXEC (στη μονάδα socket)
@geindex SOCK_NONBLOCK (στη μονάδα socket)
@anchor{library/socket socket SOCK_CLOEXEC}@anchor{fca}
@deffn {Δεδομένα} socket.SOCK_CLOEXEC
@anchor{library/socket socket SOCK_NONBLOCK}@anchor{fc9}
@deffnx {Δεδομένα} 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 Δείτε επίσης


Secure File Descriptor Handling@footnote{https://udrepper.livejournal.com/20407.html}
for a more thorough explanation.


@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.27.


Added in version 3.2.

@end deffn

@geindex SOMAXCONN (στη μονάδα socket)
@anchor{library/socket socket-unix-constants}@anchor{f32}
@deffn {Δεδομένα} SO_*
@anchor{library/socket socket SOMAXCONN}@anchor{1210}
@deffnx {Δεδομένα} socket.SOMAXCONN

@deffnx {Δεδομένα} MSG_*

@deffnx {Δεδομένα} SOL_*

@deffnx {Δεδομένα} SCM_*

@deffnx {Δεδομένα} IPPROTO_*

@deffnx {Δεδομένα} IPPORT_*

@deffnx {Δεδομένα} INADDR_*

@deffnx {Δεδομένα} IP_*

@deffnx {Δεδομένα} IPV6_*

@deffnx {Δεδομένα} EAI_*

@deffnx {Δεδομένα} AI_*

@deffnx {Δεδομένα} NI_*

@deffnx {Δεδομένα} 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{1093,,setsockopt()} and @ref{1092,,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.


Άλλαξε στην έκδοση 3.6: @code{SO_DOMAIN}, @code{SO_PROTOCOL}, @code{SO_PEERSEC}, @code{SO_PASSSEC},
@code{TCP_USER_TIMEOUT}, @code{TCP_CONGESTION} were added.



Άλλαξε στην έκδοση 3.6.5: Added support for @code{TCP_FASTOPEN}, @code{TCP_KEEPCNT} on Windows platforms
when available.



Άλλαξε στην έκδοση 3.7: @code{TCP_NOTSENT_LOWAT} was added.

Added support for @code{TCP_KEEPIDLE}, @code{TCP_KEEPINTVL} on Windows platforms
when available.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 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}.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.14: Added missing @code{IP_FREEBIND}, @code{IP_RECVERR}, @code{IPV6_RECVERR},
@code{IP_RECVTTL}, and @code{IP_RECVORIGDSTADDR} on Linux.



Άλλαξε στην έκδοση 3.14: Added support for @code{TCP_QUICKACK} on Windows platforms when available.



Άλλαξε στην έκδοση 3.15: @code{IPV6_HDRINCL} was added.
Added support for @code{SO_PASSRIGHTS} on Linux platforms when available.

@end deffn

@geindex AF_CAN (στη μονάδα socket)
@geindex PF_CAN (στη μονάδα socket)
@anchor{library/socket socket AF_CAN}@anchor{3b90}
@deffn {Δεδομένα} socket.AF_CAN
@anchor{library/socket socket PF_CAN}@anchor{3ba3}
@deffnx {Δεδομένα} socket.PF_CAN

@deffnx {Δεδομένα} SOL_CAN_*

@deffnx {Δεδομένα} CAN_*

Many constants of these forms, documented in the Linux documentation, are
also defined in the socket module.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.25, NetBSD >= 8.


Added in version 3.3.



Άλλαξε στην έκδοση 3.11: NetBSD support was added.



Άλλαξε στην έκδοση 3.14: Restored missing @code{CAN_RAW_ERR_FILTER} on Linux.

@end deffn

@geindex CAN_BCM (στη μονάδα socket)
@anchor{library/socket socket CAN_BCM}@anchor{134c}
@deffn {Δεδομένα} socket.CAN_BCM

@deffnx {Δεδομένα} 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{232d,,Διαθεσιμότητα}: Linux >= 2.6.25.

@cartouche
@quotation Σημείωση 
The @code{CAN_BCM_CAN_FD_FRAME} flag is only available on Linux >= 4.8.
@end quotation
@end cartouche


Added in version 3.4.

@end deffn

@geindex CAN_RAW_FD_FRAMES (στη μονάδα socket)
@anchor{library/socket socket CAN_RAW_FD_FRAMES}@anchor{1278}
@deffn {Δεδομένα} 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{232d,,Διαθεσιμότητα}: Linux >= 3.6.


Added in version 3.5.

@end deffn

@geindex CAN_RAW_JOIN_FILTERS (στη μονάδα socket)
@anchor{library/socket socket CAN_RAW_JOIN_FILTERS}@anchor{cfe}
@deffn {Δεδομένα} 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{232d,,Διαθεσιμότητα}: Linux >= 4.1.


Added in version 3.9.

@end deffn

@geindex CAN_ISOTP (στη μονάδα socket)
@anchor{library/socket socket CAN_ISOTP}@anchor{3b91}
@deffn {Δεδομένα} 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{232d,,Διαθεσιμότητα}: Linux >= 2.6.25.


Added in version 3.7.

@end deffn

@geindex CAN_J1939 (στη μονάδα socket)
@anchor{library/socket socket CAN_J1939}@anchor{cff}
@deffn {Δεδομένα} socket.CAN_J1939

CAN_J1939, in the CAN protocol family, is the SAE J1939 protocol.
J1939 constants, documented in the Linux documentation.

@ref{232d,,Διαθεσιμότητα}: Linux >= 5.4.


Added in version 3.9.

@end deffn

@geindex AF_DIVERT (στη μονάδα socket)
@geindex PF_DIVERT (στη μονάδα socket)
@anchor{library/socket socket AF_DIVERT}@anchor{3ba4}
@deffn {Δεδομένα} socket.AF_DIVERT
@anchor{library/socket socket PF_DIVERT}@anchor{3ba5}
@deffnx {Δεδομένα} socket.PF_DIVERT

These two constants, documented in the FreeBSD divert(4) manual page, are
also defined in the socket module.

@ref{232d,,Διαθεσιμότητα}: FreeBSD >= 14.0.


Added in version 3.12.

@end deffn

@geindex AF_PACKET (στη μονάδα socket)
@geindex PF_PACKET (στη μονάδα socket)
@anchor{library/socket socket AF_PACKET}@anchor{3b97}
@deffn {Δεδομένα} socket.AF_PACKET
@anchor{library/socket socket PF_PACKET}@anchor{3ba6}
@deffnx {Δεδομένα} socket.PF_PACKET

@deffnx {Δεδομένα} PACKET_*

Many constants of these forms, documented in the Linux documentation, are
also defined in the socket module.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.2.
@end deffn

@geindex ETH_P_ALL (στη μονάδα socket)
@anchor{library/socket socket ETH_P_ALL}@anchor{1d21}
@deffn {Δεδομένα} socket.ETH_P_ALL

@code{ETH_P_ALL} can be used in the @ref{115a,,socket}
constructor as `proto' for the @ref{3b97,,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{232d,,Διαθεσιμότητα}: Linux.


Added in version 3.12.

@end deffn

@geindex AF_RDS (στη μονάδα socket)
@geindex PF_RDS (στη μονάδα socket)
@geindex SOL_RDS (στη μονάδα socket)
@anchor{library/socket socket AF_RDS}@anchor{3ba7}
@deffn {Δεδομένα} socket.AF_RDS
@anchor{library/socket socket PF_RDS}@anchor{3ba8}
@deffnx {Δεδομένα} socket.PF_RDS
@anchor{library/socket socket SOL_RDS}@anchor{3ba9}
@deffnx {Δεδομένα} socket.SOL_RDS

@deffnx {Δεδομένα} RDS_*

Many constants of these forms, documented in the Linux documentation, are
also defined in the socket module.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.30.


Added in version 3.3.

@end deffn

@geindex SIO_RCVALL (στη μονάδα socket)
@geindex SIO_KEEPALIVE_VALS (στη μονάδα socket)
@geindex SIO_LOOPBACK_FAST_PATH (στη μονάδα socket)
@anchor{library/socket socket SIO_RCVALL}@anchor{3baa}
@deffn {Δεδομένα} socket.SIO_RCVALL
@anchor{library/socket socket SIO_KEEPALIVE_VALS}@anchor{3bab}
@deffnx {Δεδομένα} socket.SIO_KEEPALIVE_VALS
@anchor{library/socket socket SIO_LOOPBACK_FAST_PATH}@anchor{1091}
@deffnx {Δεδομένα} socket.SIO_LOOPBACK_FAST_PATH

@deffnx {Δεδομένα} RCVALL_*

Constants for Windows” WSAIoctl(). The constants are used as arguments to the
@ref{1090,,ioctl()} method of socket objects.


Άλλαξε στην έκδοση 3.6: @code{SIO_LOOPBACK_FAST_PATH} was added.

@end deffn


@deffn {Δεδομένα} 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 (στη μονάδα socket)
@geindex SOL_ALG (στη μονάδα socket)
@anchor{library/socket socket AF_ALG}@anchor{1094}
@deffn {Δεδομένα} socket.AF_ALG
@anchor{library/socket socket SOL_ALG}@anchor{3bac}
@deffnx {Δεδομένα} socket.SOL_ALG

@deffnx {Δεδομένα} ALG_*

Constants for Linux Kernel cryptography.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.38.


Added in version 3.6.

@end deffn

@geindex AF_VSOCK (στη μονάδα socket)
@geindex IOCTL_VM_SOCKETS_GET_LOCAL_CID (στη μονάδα socket)
@anchor{library/socket socket AF_VSOCK}@anchor{f33}
@deffn {Δεδομένα} socket.AF_VSOCK
@anchor{library/socket socket IOCTL_VM_SOCKETS_GET_LOCAL_CID}@anchor{3bad}
@deffnx {Δεδομένα} socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID

@deffnx {Δεδομένα} VMADDR*

@deffnx {Δεδομένα} SO_VM*

Constants for Linux host/guest communication.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.8.


Added in version 3.7.

@end deffn

@geindex AF_LINK (στη μονάδα socket)
@anchor{library/socket socket AF_LINK}@anchor{134d}
@deffn {Δεδομένα} socket.AF_LINK

@ref{232d,,Διαθεσιμότητα}: BSD, macOS.


Added in version 3.4.

@end deffn

@geindex has_ipv6 (στη μονάδα socket)
@anchor{library/socket socket has_ipv6}@anchor{3bae}
@deffn {Δεδομένα} socket.has_ipv6

This constant contains a boolean value which indicates if IPv6 is supported on
this platform.
@end deffn

@geindex AF_BLUETOOTH (στη μονάδα socket)
@geindex BTPROTO_L2CAP (στη μονάδα socket)
@geindex BTPROTO_RFCOMM (στη μονάδα socket)
@geindex BTPROTO_HCI (στη μονάδα socket)
@geindex BTPROTO_SCO (στη μονάδα socket)
@anchor{library/socket socket AF_BLUETOOTH}@anchor{1da9}
@deffn {Δεδομένα} socket.AF_BLUETOOTH
@anchor{library/socket socket BTPROTO_L2CAP}@anchor{50b}
@deffnx {Δεδομένα} socket.BTPROTO_L2CAP
@anchor{library/socket socket BTPROTO_RFCOMM}@anchor{3b95}
@deffnx {Δεδομένα} socket.BTPROTO_RFCOMM
@anchor{library/socket socket BTPROTO_HCI}@anchor{509}
@deffnx {Δεδομένα} socket.BTPROTO_HCI
@anchor{library/socket socket BTPROTO_SCO}@anchor{50a}
@deffnx {Δεδομένα} socket.BTPROTO_SCO

Integer constants for use with Bluetooth addresses.
@end deffn

@geindex BDADDR_ANY (στη μονάδα socket)
@geindex BDADDR_LOCAL (στη μονάδα socket)
@anchor{library/socket socket BDADDR_ANY}@anchor{3baf}
@deffn {Δεδομένα} socket.BDADDR_ANY
@anchor{library/socket socket BDADDR_LOCAL}@anchor{3bb0}
@deffnx {Δεδομένα} socket.BDADDR_LOCAL

These are string constants containing Bluetooth addresses with special
meanings. For example, @ref{3baf,,BDADDR_ANY} can be used to indicate
any address when specifying the binding socket with
@ref{3b95,,BTPROTO_RFCOMM}.
@end deffn

@geindex BDADDR_BREDR (στη μονάδα socket)
@geindex BDADDR_LE_PUBLIC (στη μονάδα socket)
@geindex BDADDR_LE_RANDOM (στη μονάδα socket)
@anchor{library/socket socket BDADDR_BREDR}@anchor{3b92}
@deffn {Δεδομένα} socket.BDADDR_BREDR
@anchor{library/socket socket BDADDR_LE_PUBLIC}@anchor{3b93}
@deffnx {Δεδομένα} socket.BDADDR_LE_PUBLIC
@anchor{library/socket socket BDADDR_LE_RANDOM}@anchor{3b94}
@deffnx {Δεδομένα} socket.BDADDR_LE_RANDOM

These constants describe the Bluetooth address type when binding or
connecting a @ref{50b,,BTPROTO_L2CAP} socket.

@ref{232d,,Διαθεσιμότητα}: Linux, FreeBSD


Added in version 3.14.

@end deffn

@geindex SOL_RFCOMM (στη μονάδα socket)
@geindex SOL_L2CAP (στη μονάδα socket)
@geindex SOL_HCI (στη μονάδα socket)
@geindex SOL_SCO (στη μονάδα socket)
@geindex SOL_BLUETOOTH (στη μονάδα socket)
@anchor{library/socket socket SOL_RFCOMM}@anchor{3bb1}
@deffn {Δεδομένα} socket.SOL_RFCOMM
@anchor{library/socket socket SOL_L2CAP}@anchor{3bb2}
@deffnx {Δεδομένα} socket.SOL_L2CAP
@anchor{library/socket socket SOL_HCI}@anchor{3bb3}
@deffnx {Δεδομένα} socket.SOL_HCI
@anchor{library/socket socket SOL_SCO}@anchor{3bb4}
@deffnx {Δεδομένα} socket.SOL_SCO
@anchor{library/socket socket SOL_BLUETOOTH}@anchor{3bb5}
@deffnx {Δεδομένα} socket.SOL_BLUETOOTH

Used in the level argument to the @ref{1093,,setsockopt()} and
@ref{1092,,getsockopt()} methods of Bluetooth socket objects.

@ref{3bb5,,SOL_BLUETOOTH} is only available on Linux. Other constants
are available if the corresponding protocol is supported.
@end deffn

@geindex L2CAP_LM (στη μονάδα socket)

@deffn {Δεδομένα} SO_L2CAP_*
@anchor{library/socket socket L2CAP_LM}@anchor{3bb6}
@deffnx {Δεδομένα} socket.L2CAP_LM

@deffnx {Δεδομένα} L2CAP_LM_*

@deffnx {Δεδομένα} SO_RFCOMM_*

@deffnx {Δεδομένα} RFCOMM_LM_*

@deffnx {Δεδομένα} SO_SCO_*

@deffnx {Δεδομένα} SO_BTH_*

@deffnx {Δεδομένα} BT_*

Used in the option name and value argument to the @ref{1093,,setsockopt()}
and @ref{1092,,getsockopt()} methods of Bluetooth socket objects.

@code{BT_*} and @ref{3bb6,,L2CAP_LM} are only available on Linux.
@code{SO_BTH_*} are only available on Windows.
Other constants may be available on Linux and various BSD platforms.


Added in version 3.14.

@end deffn

@geindex HCI_FILTER (στη μονάδα socket)
@geindex HCI_TIME_STAMP (στη μονάδα socket)
@geindex HCI_DATA_DIR (στη μονάδα socket)
@geindex SO_HCI_EVT_FILTER (στη μονάδα socket)
@geindex SO_HCI_PKT_FILTER (στη μονάδα socket)
@anchor{library/socket socket HCI_FILTER}@anchor{3bb7}
@deffn {Δεδομένα} socket.HCI_FILTER
@anchor{library/socket socket HCI_TIME_STAMP}@anchor{3bb8}
@deffnx {Δεδομένα} socket.HCI_TIME_STAMP
@anchor{library/socket socket HCI_DATA_DIR}@anchor{3bb9}
@deffnx {Δεδομένα} socket.HCI_DATA_DIR
@anchor{library/socket socket SO_HCI_EVT_FILTER}@anchor{3bba}
@deffnx {Δεδομένα} socket.SO_HCI_EVT_FILTER
@anchor{library/socket socket SO_HCI_PKT_FILTER}@anchor{3bbb}
@deffnx {Δεδομένα} socket.SO_HCI_PKT_FILTER

Option names for use with @ref{509,,BTPROTO_HCI}.
Availability and format of the option values depend on platform.


Άλλαξε στην έκδοση 3.14: Added @code{SO_HCI_EVT_FILTER} and @code{SO_HCI_PKT_FILTER}
on NetBSD and DragonFly BSD.
Added @code{HCI_DATA_DIR} on FreeBSD, NetBSD and DragonFly BSD.

@end deffn

@geindex HCI_DEV_NONE (στη μονάδα socket)
@anchor{library/socket socket HCI_DEV_NONE}@anchor{3bbc}
@deffn {Δεδομένα} socket.HCI_DEV_NONE

The @code{device_id} value used to create an HCI socket that isn’t specific
to a single Bluetooth adapter.

@ref{232d,,Διαθεσιμότητα}: Linux


Added in version 3.14.

@end deffn

@geindex HCI_CHANNEL_RAW (στη μονάδα socket)
@geindex HCI_CHANNEL_USER (στη μονάδα socket)
@geindex HCI_CHANNEL_MONITOR (στη μονάδα socket)
@geindex HCI_CHANNEL_CONTROL (στη μονάδα socket)
@geindex HCI_CHANNEL_LOGGING (στη μονάδα socket)
@anchor{library/socket socket HCI_CHANNEL_RAW}@anchor{3b96}
@deffn {Δεδομένα} socket.HCI_CHANNEL_RAW
@anchor{library/socket socket HCI_CHANNEL_USER}@anchor{3bbd}
@deffnx {Δεδομένα} socket.HCI_CHANNEL_USER
@anchor{library/socket socket HCI_CHANNEL_MONITOR}@anchor{3bbe}
@deffnx {Δεδομένα} socket.HCI_CHANNEL_MONITOR
@anchor{library/socket socket HCI_CHANNEL_CONTROL}@anchor{3bbf}
@deffnx {Δεδομένα} socket.HCI_CHANNEL_CONTROL
@anchor{library/socket socket HCI_CHANNEL_LOGGING}@anchor{3bc0}
@deffnx {Δεδομένα} socket.HCI_CHANNEL_LOGGING

Possible values for @code{channel} field in the @ref{509,,BTPROTO_HCI} address.

@ref{232d,,Διαθεσιμότητα}: Linux


Added in version 3.14.

@end deffn

@geindex AF_QIPCRTR (στη μονάδα socket)
@anchor{library/socket socket AF_QIPCRTR}@anchor{3b98}
@deffn {Δεδομένα} socket.AF_QIPCRTR

Constant for Qualcomm’s IPC router protocol, used to communicate with
service providing remote processors.

@ref{232d,,Διαθεσιμότητα}: Linux >= 4.7.
@end deffn

@geindex SCM_CREDS2 (στη μονάδα socket)
@geindex LOCAL_CREDS (στη μονάδα socket)
@geindex LOCAL_CREDS_PERSISTENT (στη μονάδα socket)
@anchor{library/socket socket SCM_CREDS2}@anchor{3bc1}
@deffn {Δεδομένα} socket.SCM_CREDS2
@anchor{library/socket socket LOCAL_CREDS}@anchor{3bc2}
@deffnx {Δεδομένα} socket.LOCAL_CREDS
@anchor{library/socket socket LOCAL_CREDS_PERSISTENT}@anchor{3bc3}
@deffnx {Δεδομένα} 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.


Added in version 3.11.


@ref{232d,,Διαθεσιμότητα}: FreeBSD.
@end deffn

@geindex SO_INCOMING_CPU (στη μονάδα socket)
@anchor{library/socket socket SO_INCOMING_CPU}@anchor{3bc4}
@deffn {Δεδομένα} socket.SO_INCOMING_CPU

Constant to optimize CPU locality, to be used in conjunction with
@code{SO_REUSEPORT}.


Added in version 3.11.


@ref{232d,,Διαθεσιμότητα}: Linux >= 3.9
@end deffn

@geindex SO_REUSEPORT_LB (στη μονάδα socket)
@anchor{library/socket socket SO_REUSEPORT_LB}@anchor{1af5}
@deffn {Δεδομένα} socket.SO_REUSEPORT_LB

@quotation

Constant to enable duplicate address and port bindings with load balancing.
@end quotation


Added in version 3.14.


@ref{232d,,Διαθεσιμότητα}: FreeBSD >= 12.0
@end deffn

@geindex AF_HYPERV (στη μονάδα socket)
@geindex HV_PROTOCOL_RAW (στη μονάδα socket)
@geindex HVSOCKET_CONNECT_TIMEOUT (στη μονάδα socket)
@geindex HVSOCKET_CONNECT_TIMEOUT_MAX (στη μονάδα socket)
@geindex HVSOCKET_CONNECTED_SUSPEND (στη μονάδα socket)
@geindex HVSOCKET_ADDRESS_FLAG_PASSTHRU (στη μονάδα socket)
@geindex HV_GUID_ZERO (στη μονάδα socket)
@geindex HV_GUID_WILDCARD (στη μονάδα socket)
@geindex HV_GUID_BROADCAST (στη μονάδα socket)
@geindex HV_GUID_CHILDREN (στη μονάδα socket)
@geindex HV_GUID_LOOPBACK (στη μονάδα socket)
@geindex HV_GUID_PARENT (στη μονάδα socket)
@anchor{library/socket socket AF_HYPERV}@anchor{3b99}
@deffn {Δεδομένα} socket.AF_HYPERV
@anchor{library/socket socket HV_PROTOCOL_RAW}@anchor{3bc5}
@deffnx {Δεδομένα} socket.HV_PROTOCOL_RAW
@anchor{library/socket socket HVSOCKET_CONNECT_TIMEOUT}@anchor{3bc6}
@deffnx {Δεδομένα} socket.HVSOCKET_CONNECT_TIMEOUT
@anchor{library/socket socket HVSOCKET_CONNECT_TIMEOUT_MAX}@anchor{3bc7}
@deffnx {Δεδομένα} socket.HVSOCKET_CONNECT_TIMEOUT_MAX
@anchor{library/socket socket HVSOCKET_CONNECTED_SUSPEND}@anchor{3bc8}
@deffnx {Δεδομένα} socket.HVSOCKET_CONNECTED_SUSPEND
@anchor{library/socket socket HVSOCKET_ADDRESS_FLAG_PASSTHRU}@anchor{3bc9}
@deffnx {Δεδομένα} socket.HVSOCKET_ADDRESS_FLAG_PASSTHRU
@anchor{library/socket socket HV_GUID_ZERO}@anchor{3bca}
@deffnx {Δεδομένα} socket.HV_GUID_ZERO
@anchor{library/socket socket HV_GUID_WILDCARD}@anchor{3bcb}
@deffnx {Δεδομένα} socket.HV_GUID_WILDCARD
@anchor{library/socket socket HV_GUID_BROADCAST}@anchor{3bcc}
@deffnx {Δεδομένα} socket.HV_GUID_BROADCAST
@anchor{library/socket socket HV_GUID_CHILDREN}@anchor{3bcd}
@deffnx {Δεδομένα} socket.HV_GUID_CHILDREN
@anchor{library/socket socket HV_GUID_LOOPBACK}@anchor{3bce}
@deffnx {Δεδομένα} socket.HV_GUID_LOOPBACK
@anchor{library/socket socket HV_GUID_PARENT}@anchor{3bcf}
@deffnx {Δεδομένα} socket.HV_GUID_PARENT

Constants for Windows Hyper-V sockets for host/guest communications.

@ref{232d,,Διαθεσιμότητα}: Windows.


Added in version 3.12.

@end deffn

@geindex ETHERTYPE_ARP (στη μονάδα socket)
@geindex ETHERTYPE_IP (στη μονάδα socket)
@geindex ETHERTYPE_IPV6 (στη μονάδα socket)
@geindex ETHERTYPE_VLAN (στη μονάδα socket)
@anchor{library/socket socket-ethernet-types}@anchor{1d22}@anchor{library/socket socket ETHERTYPE_ARP}@anchor{3bd0}
@deffn {Δεδομένα} socket.ETHERTYPE_ARP
@anchor{library/socket socket ETHERTYPE_IP}@anchor{3bd1}
@deffnx {Δεδομένα} socket.ETHERTYPE_IP
@anchor{library/socket socket ETHERTYPE_IPV6}@anchor{3bd2}
@deffnx {Δεδομένα} socket.ETHERTYPE_IPV6
@anchor{library/socket socket ETHERTYPE_VLAN}@anchor{3bd3}
@deffnx {Δεδομένα} socket.ETHERTYPE_VLAN

IEEE 802.3 protocol number@footnote{https://www.iana.org/assignments/ieee-802-numbers/ieee-802-numbers.txt}.
constants.

@ref{232d,,Διαθεσιμότητα}: Linux, FreeBSD, macOS.


Added in version 3.12.

@end deffn

@geindex SHUT_RD (στη μονάδα socket)
@geindex SHUT_WR (στη μονάδα socket)
@geindex SHUT_RDWR (στη μονάδα socket)
@anchor{library/socket socket SHUT_RD}@anchor{3bd4}
@deffn {Δεδομένα} socket.SHUT_RD
@anchor{library/socket socket SHUT_WR}@anchor{3bd5}
@deffnx {Δεδομένα} socket.SHUT_WR
@anchor{library/socket socket SHUT_RDWR}@anchor{3bd6}
@deffnx {Δεδομένα} socket.SHUT_RDWR

These constants are used by the @ref{3bd7,,shutdown()} method of socket objects.

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@node Functions<6>,,Constants<8>,Module contents<3>
@anchor{library/socket functions}@anchor{3bd8}
@subsubsection Functions


@menu
* Creating sockets:: 
* Other functions: Other functions<2>. 

@end menu

@node Creating sockets,Other functions<2>,,Functions<6>
@anchor{library/socket creating-sockets}@anchor{3bd9}
@subsubsection Creating sockets


The following functions all create @ref{3bda,,socket objects}.

@geindex socket (κλάση σε socket)
@anchor{library/socket socket socket}@anchor{115a}
@deffn {Κλάση} 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{1da7,,AF_INET} (the default),
@ref{1da8,,AF_INET6}, @ref{1daa,,AF_UNIX}, @ref{3b90,,AF_CAN}, @ref{3b97,,AF_PACKET},
or @ref{3ba7,,AF_RDS}. The socket type should be @ref{1698,,SOCK_STREAM} (the
default), @ref{1697,,SOCK_DGRAM}, @ref{3ba0,,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 @code{AF_CAN} the protocol
should be one of @code{CAN_RAW}, @ref{134c,,CAN_BCM}, @ref{3b91,,CAN_ISOTP} or
@ref{cff,,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{3b1d,,socket.getpeername()} but not the actual OS resource.  Unlike
@ref{3bdb,,socket.fromfd()}, `fileno' will return the same socket and not a
duplicate. This may help close a detached socket using
@ref{f30,,socket.close()}.

The newly created socket is @ref{12aa,,non-inheritable}.

Raises an @ref{1e65,,auditing event} @code{socket.__new__} with arguments @code{self}, @code{family}, @code{type}, @code{protocol}.


Άλλαξε στην έκδοση 3.3: The AF_CAN family was added.
The AF_RDS family was added.



Άλλαξε στην έκδοση 3.4: The CAN_BCM protocol was added.



Άλλαξε στην έκδοση 3.4: The returned socket is now non-inheritable.



Άλλαξε στην έκδοση 3.7: The CAN_ISOTP protocol was added.



Άλλαξε στην έκδοση 3.7: When @ref{fc9,,SOCK_NONBLOCK} or @ref{fca,,SOCK_CLOEXEC}
bit flags are applied to `type' they are cleared, and
@ref{fcb,,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}.



Άλλαξε στην έκδοση 3.9: The CAN_J1939 protocol was added.



Άλλαξε στην έκδοση 3.10: The IPPROTO_MPTCP protocol was added.

@end deffn

@geindex socketpair() (στη μονάδα socket)
@anchor{library/socket socket socketpair}@anchor{fb5}
@deffn {Συνάρτηση} 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{115a,,socket()} function. The default family is @ref{1daa,,AF_UNIX}
if defined on the platform; otherwise, the default is @ref{1da7,,AF_INET}.

The newly created sockets are @ref{12aa,,non-inheritable}.


Άλλαξε στην έκδοση 3.2: The returned socket objects now support the whole socket API, rather
than a subset.



Άλλαξε στην έκδοση 3.4: The returned sockets are now non-inheritable.



Άλλαξε στην έκδοση 3.5: Windows support added.

@end deffn

@geindex create_connection() (στη μονάδα socket)
@anchor{library/socket socket create_connection}@anchor{a62}
@deffn {Συνάρτηση} 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{115c,,socket.connect()}: if `host' is a non-numeric hostname,
it will try to resolve it for both @ref{1da7,,AF_INET} and @ref{1da8,,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{3bdc,,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 “” 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{6d8,,ExceptionGroup} containing the errors of all
attempts.


Άλλαξε στην έκδοση 3.2: `source_address' was added.



Άλλαξε στην έκδοση 3.11: `all_errors' was added.

@end deffn

@geindex create_server() (στη μονάδα socket)
@anchor{library/socket socket create_server}@anchor{def}
@deffn {Συνάρτηση} 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{1da7,,AF_INET} or @ref{1da8,,AF_INET6}.
`backlog' is the queue size passed to @ref{120f,,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, `family' is @ref{1da8,,AF_INET6} and the platform
supports it the socket will be able to accept both IPv4 and IPv6 connections,
else it will raise @ref{277,,ValueError}. Most POSIX platforms and Windows are
supposed to support this functionality.
When this functionality is enabled the address returned by
@ref{3b1d,,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{df0,,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 Σημείωση 
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


Added in version 3.8.

@end deffn

@geindex has_dualstack_ipv6() (στη μονάδα socket)
@anchor{library/socket socket has_dualstack_ipv6}@anchor{df0}
@deffn {Συνάρτηση} socket.has_dualstack_ipv6 ()

Return @code{True} if the platform supports creating a TCP socket which can
handle both IPv4 and IPv6 connections.


Added in version 3.8.

@end deffn

@geindex fromfd() (στη μονάδα socket)
@anchor{library/socket socket fromfd}@anchor{3bdb}
@deffn {Συνάρτηση} socket.fromfd (fd, family, type, proto=0)

Duplicate the file descriptor `fd' (an integer as returned by a file object’s
@ref{19b2,,fileno()} method) and build a socket object from the result.  Address
family, socket type and protocol number are as for the @ref{115a,,socket()} function.
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.

The newly created socket is @ref{12aa,,non-inheritable}.


Άλλαξε στην έκδοση 3.4: The returned socket is now non-inheritable.

@end deffn

@geindex fromshare() (στη μονάδα socket)
@anchor{library/socket socket fromshare}@anchor{fc6}
@deffn {Συνάρτηση} socket.fromshare (data)

Instantiate a socket from data obtained from the @ref{fc7,,socket.share()}
method.  The socket is assumed to be in blocking mode.

@ref{232d,,Διαθεσιμότητα}: Windows.


Added in version 3.3.

@end deffn

@geindex SocketType (στη μονάδα socket)
@anchor{library/socket socket SocketType}@anchor{3bdd}
@deffn {Δεδομένα} 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 Other functions<2>,,Creating sockets,Functions<6>
@anchor{library/socket other-functions}@anchor{3bde}
@subsubsection Other functions


The @code{socket} module also offers various network-related services:

@geindex close() (στη μονάδα socket)
@anchor{library/socket socket close}@anchor{f30}
@deffn {Συνάρτηση} socket.close (fd)

Close a socket file descriptor. This is like @ref{f31,,os.close()}, but for
sockets. On some platforms (most notably Windows) @code{os.close()}
does not work for socket file descriptors.


Added in version 3.7.

@end deffn

@geindex getaddrinfo() (στη μονάδα socket)
@anchor{library/socket socket getaddrinfo}@anchor{1925}
@deffn {Συνάρτηση} 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{3ade,,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{115a,,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' and flags Python was compiled with,
and is meant to be passed to the @ref{115c,,socket.connect()} method.

`sockaddr' can be one of the following:


@itemize *

@item 
a @code{(address, port)} 2-tuple for @ref{1da7,,AF_INET}

@item 
a @code{(address, port, flowinfo, scope_id)} 4-tuple for @ref{1da8,,AF_INET6} if
Python was compiled with @code{--enable-ipv6} (the default)

@item 
a 2-tuple containing raw data for @ref{1da8,,AF_INET6} if Python was
compiled with @code{--disable-ipv6}
@end itemize

@cartouche
@quotation Σημείωση 
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{1698,,SOCK_STREAM} or
@ref{1697,,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{1e65,,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


Άλλαξε στην έκδοση 3.2: parameters can now be passed using keyword arguments.



Άλλαξε στην έκδοση 3.7: for IPv6 multicast addresses, string representing an address will not
contain @code{%scope_id} part.

@end deffn

@geindex getfqdn() (στη μονάδα socket)
@anchor{library/socket socket getfqdn}@anchor{1cec}
@deffn {Συνάρτηση} 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{1e7a,,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{324b,,gethostname()} is returned.
@end deffn

@geindex gethostbyname() (στη μονάδα socket)
@anchor{library/socket socket gethostbyname}@anchor{3bdf}
@deffn {Συνάρτηση} 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{1e7b,,gethostbyname_ex()} for a more complete
interface. @code{gethostbyname()} does not support IPv6 name resolution, and
@ref{1925,,getaddrinfo()} should be used instead for IPv4/v6 dual stack support.

Raises an @ref{1e65,,auditing event} @code{socket.gethostbyname} with argument @code{hostname}.

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex gethostbyname_ex() (στη μονάδα socket)
@anchor{library/socket socket gethostbyname_ex}@anchor{1e7b}
@deffn {Συνάρτηση} 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). @code{gethostbyname_ex()} does not support IPv6 name
resolution, and @ref{1925,,getaddrinfo()} should be used instead for IPv4/v6 dual
stack support.

Raises an @ref{1e65,,auditing event} @code{socket.gethostbyname} with argument @code{hostname}.

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex gethostname() (στη μονάδα socket)
@anchor{library/socket socket gethostname}@anchor{324b}
@deffn {Συνάρτηση} socket.gethostname ()

Return a string containing the hostname of the machine where  the Python
interpreter is currently executing.

Raises an @ref{1e65,,auditing event} @code{socket.gethostname} with no arguments.

Note: @code{gethostname()} doesn’t always return the fully qualified domain
name; use @ref{1cec,,getfqdn()} for that.

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex gethostbyaddr() (στη μονάδα socket)
@anchor{library/socket socket gethostbyaddr}@anchor{1e7a}
@deffn {Συνάρτηση} 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{1cec,,getfqdn()}. @code{gethostbyaddr()} supports
both IPv4 and IPv6.

Raises an @ref{1e65,,auditing event} @code{socket.gethostbyaddr} with argument @code{ip_address}.

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex getnameinfo() (στη μονάδα socket)
@anchor{library/socket socket getnameinfo}@anchor{1c42}
@deffn {Συνάρτηση} 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{1e65,,auditing event} @code{socket.getnameinfo} with argument @code{sockaddr}.

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex getprotobyname() (στη μονάδα socket)
@anchor{library/socket socket getprotobyname}@anchor{3be0}
@deffn {Συνάρτηση} 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{115a,,socket()}
function.  This is usually only needed for sockets opened in «raw» mode
(@ref{3ba0,,SOCK_RAW}); for the normal socket modes, the correct protocol is chosen
automatically if the protocol is omitted or zero.

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex getservbyname() (στη μονάδα socket)
@anchor{library/socket socket getservbyname}@anchor{3be1}
@deffn {Συνάρτηση} 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{1e65,,auditing event} @code{socket.getservbyname} with arguments @code{servicename}, @code{protocolname}.

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex getservbyport() (στη μονάδα socket)
@anchor{library/socket socket getservbyport}@anchor{3be2}
@deffn {Συνάρτηση} 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{1e65,,auditing event} @code{socket.getservbyport} with arguments @code{port}, @code{protocolname}.

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex ntohl() (στη μονάδα socket)
@anchor{library/socket socket ntohl}@anchor{3be3}
@deffn {Συνάρτηση} 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() (στη μονάδα socket)
@anchor{library/socket socket ntohs}@anchor{c56}
@deffn {Συνάρτηση} 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.


Άλλαξε στην έκδοση 3.10: Raises @ref{c57,,OverflowError} if `x' does not fit in a 16-bit unsigned
integer.

@end deffn

@geindex htonl() (στη μονάδα socket)
@anchor{library/socket socket htonl}@anchor{3be4}
@deffn {Συνάρτηση} 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() (στη μονάδα socket)
@anchor{library/socket socket htons}@anchor{c55}
@deffn {Συνάρτηση} 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.


Άλλαξε στην έκδοση 3.10: Raises @ref{c57,,OverflowError} if `x' does not fit in a 16-bit unsigned
integer.

@end deffn

@geindex inet_aton() (στη μονάδα socket)
@anchor{library/socket socket inet_aton}@anchor{d2b}
@deffn {Συνάρτηση} 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.

@code{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{53c,,OSError} will be raised. Note that exactly what is valid depends on
the underlying C implementation of @code{inet_aton()}.

@code{inet_aton()} does not support IPv6, and @ref{d2c,,inet_pton()} should be used
instead for IPv4/v6 dual stack support.
@end deffn

@geindex inet_ntoa() (στη μονάδα socket)
@anchor{library/socket socket inet_ntoa}@anchor{3be5}
@deffn {Συνάρτηση} socket.inet_ntoa (packed_ip)

Convert a 32-bit packed IPv4 address (a @ref{436,,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{53c,,OSError} will be raised. @code{inet_ntoa()} does not
support IPv6, and @ref{134e,,inet_ntop()} should be used instead for IPv4/v6 dual
stack support.


Άλλαξε στην έκδοση 3.5: Writable @ref{436,,bytes-like object} is now accepted.

@end deffn

@geindex inet_pton() (στη μονάδα socket)
@anchor{library/socket socket inet_pton}@anchor{d2c}
@deffn {Συνάρτηση} socket.inet_pton (address_family, ip_string)

Convert an IP address from its family-specific string format to a packed,
binary format. @code{inet_pton()} is useful when a library or network protocol
calls for an object of type @code{in_addr} (similar to
@ref{d2b,,inet_aton()}) or @code{in6_addr}.

Supported values for `address_family' are currently @ref{1da7,,AF_INET} and
@ref{1da8,,AF_INET6}. If the IP address string `ip_string' is invalid,
@ref{53c,,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{232d,,Διαθεσιμότητα}: Unix, Windows.


Άλλαξε στην έκδοση 3.4: Windows support added

@end deffn

@geindex inet_ntop() (στη μονάδα socket)
@anchor{library/socket socket inet_ntop}@anchor{134e}
@deffn {Συνάρτηση} socket.inet_ntop (address_family, packed_ip)

Convert a packed IP address (a @ref{436,,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'}).
@code{inet_ntop()} is useful when a library or network protocol returns an
object of type @code{in_addr} (similar to @ref{3be5,,inet_ntoa()}) or
@code{in6_addr}.

Supported values for `address_family' are currently @ref{1da7,,AF_INET} and
@ref{1da8,,AF_INET6}. If the bytes object `packed_ip' is not the correct
length for the specified address family, @ref{277,,ValueError} will be raised.
@ref{53c,,OSError} is raised for errors from the call to @code{inet_ntop()}.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows.


Άλλαξε στην έκδοση 3.4: Windows support added



Άλλαξε στην έκδοση 3.5: Writable @ref{436,,bytes-like object} is now accepted.

@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() (στη μονάδα socket)
@anchor{library/socket socket CMSG_LEN}@anchor{2006}
@deffn {Συνάρτηση} 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{115f,,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{2005,,CMSG_SPACE()} and thus include
space for padding, even when the item will be the last in the
buffer.  Raises @ref{c57,,OverflowError} if `length' is outside the
permissible range of values.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.

Most Unix platforms.


Added in version 3.3.

@end deffn

@geindex CMSG_SPACE() (στη μονάδα socket)
@anchor{library/socket socket CMSG_SPACE}@anchor{2005}
@deffn {Συνάρτηση} socket.CMSG_SPACE (length)

Return the buffer size needed for @ref{115f,,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 @code{CMSG_SPACE()}
values for their associated data lengths.  Raises
@ref{c57,,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{232d,,Διαθεσιμότητα}: Unix, not WASI.

most Unix platforms.


Added in version 3.3.

@end deffn

@geindex getdefaulttimeout() (στη μονάδα socket)
@anchor{library/socket socket getdefaulttimeout}@anchor{3bdc}
@deffn {Συνάρτηση} 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() (στη μονάδα socket)
@anchor{library/socket socket setdefaulttimeout}@anchor{3b9e}
@deffn {Συνάρτηση} socket.setdefaulttimeout (timeout)

Set the default timeout in seconds (real number) for new socket objects.  When
the socket module is first imported, the default is @code{None}.  See
@ref{3b9a,,settimeout()} for possible values and their respective
meanings.


Άλλαξε στην έκδοση 3.15: Accepts any real number, not only integer or float.

@end deffn

@geindex sethostname() (στη μονάδα socket)
@anchor{library/socket socket sethostname}@anchor{14e7}
@deffn {Συνάρτηση} socket.sethostname (name)

Set the machine’s hostname to `name'.  This will raise an
@ref{53c,,OSError} if you don’t have enough rights.

Raises an @ref{1e65,,auditing event} @code{socket.sethostname} with argument @code{name}.

@ref{232d,,Διαθεσιμότητα}: Unix, not Android.


Added in version 3.3.

@end deffn

@geindex if_nameindex() (στη μονάδα socket)
@anchor{library/socket socket if_nameindex}@anchor{df1}
@deffn {Συνάρτηση} socket.if_nameindex ()

Return a list of network interface information
(index int, name string) tuples.
@ref{53c,,OSError} if the system call fails.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows, not WASI.


Added in version 3.3.



Άλλαξε στην έκδοση 3.8: Windows support was added.


@cartouche
@quotation Σημείωση 
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() (στη μονάδα socket)
@anchor{library/socket socket if_nametoindex}@anchor{df2}
@deffn {Συνάρτηση} socket.if_nametoindex (if_name)

Return a network interface index number corresponding to an
interface name.
@ref{53c,,OSError} if no interface with the given name exists.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows, not WASI.


Added in version 3.3.



Άλλαξε στην έκδοση 3.8: Windows support was added.



@subsubheading Δείτε επίσης


«Interface name» is a name as documented in @ref{df1,,if_nameindex()}.

@end deffn

@geindex if_indextoname() (στη μονάδα socket)
@anchor{library/socket socket if_indextoname}@anchor{df3}
@deffn {Συνάρτηση} socket.if_indextoname (if_index)

Return a network interface name corresponding to an
interface index number.
@ref{53c,,OSError} if no interface with the given index exists.

@ref{232d,,Διαθεσιμότητα}: Unix, Windows, not WASI.


Added in version 3.3.



Άλλαξε στην έκδοση 3.8: Windows support was added.



@subsubheading Δείτε επίσης


«Interface name» is a name as documented in @ref{df1,,if_nameindex()}.

@end deffn

@geindex send_fds() (στη μονάδα socket)
@anchor{library/socket socket send_fds}@anchor{d00}
@deffn {Συνάρτηση} socket.send_fds (sock, buffers, fds[, flags[, address]])

Send the list of file descriptors `fds' over an @ref{1daa,,AF_UNIX} socket `sock'.
The `fds' parameter is a sequence of file descriptors.
Consult @ref{88c,,sendmsg()} for the documentation of these parameters.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.

Unix platforms supporting @ref{88c,,sendmsg()}
and @code{SCM_RIGHTS} mechanism.


Added in version 3.9.

@end deffn

@geindex recv_fds() (στη μονάδα socket)
@anchor{library/socket socket recv_fds}@anchor{d01}
@deffn {Συνάρτηση} socket.recv_fds (sock, bufsize, maxfds[, flags])

Receive up to `maxfds' file descriptors from an @ref{1daa,,AF_UNIX} socket `sock'.
Return @code{(msg, list(fds), flags, addr)}.
Consult @ref{115f,,recvmsg()} for the documentation of these parameters.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI.

Unix platforms supporting @ref{115f,,recvmsg()}
and @code{SCM_RIGHTS} mechanism.


Added in version 3.9.


@cartouche
@quotation Σημείωση 
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<3>,socket — Low-level networking interface
@anchor{library/socket id1}@anchor{3be6}@anchor{library/socket socket-objects}@anchor{3bda}
@subsubsection Socket Objects


Socket objects have the following methods.  Except for
@ref{1548,,makefile()}, these correspond to Unix system calls applicable
to sockets.


Άλλαξε στην έκδοση 3.2: Support for the @ref{478,,context manager} protocol was added.  Exiting the
context manager is equivalent to calling @ref{f30,,close()}.


@geindex accept() (μέθοδος της socket.socket)
@anchor{library/socket socket socket accept}@anchor{115b}
@deffn {Μέθοδος} 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.

The newly created socket is @ref{12aa,,non-inheritable}.


Άλλαξε στην έκδοση 3.4: The socket is now non-inheritable.



Άλλαξε στην έκδοση 3.5: If the system call is interrupted and the signal handler does not raise
an exception, the method now retries the system call instead of raising
an @ref{1141,,InterruptedError} exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).

@end deffn

@geindex bind() (μέθοδος της socket.socket)
@anchor{library/socket socket socket bind}@anchor{18dc}
@deffn {Μέθοδος} 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 @ref{3b8d,,Socket families}.

Raises an @ref{1e65,,auditing event} @code{socket.bind} with arguments @code{self}, @code{address}.

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex close() (μέθοδος της socket.socket)
@anchor{library/socket socket socket close}@anchor{10fa}
@deffn {Μέθοδος} socket.close ()

Mark the socket closed.  The underlying system resource (e.g. a file
descriptor) is also closed when all file objects from @ref{1548,,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 @code{close()} them explicitly, or to use a
@ref{20a,,with} statement around them.


Άλλαξε στην έκδοση 3.6: @ref{53c,,OSError} is now raised if an error occurs when the underlying
@code{close()} call is made.


@cartouche
@quotation Σημείωση 
@code{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{3bd7,,shutdown()}
before @code{close()}.
@end quotation
@end cartouche
@end deffn

@geindex connect() (μέθοδος της socket.socket)
@anchor{library/socket socket socket connect}@anchor{115c}
@deffn {Μέθοδος} socket.connect (address)

Connect to a remote socket at `address'. The format of `address' depends on the
address family — see @ref{3b8d,,Socket families}.

If the connection is interrupted by a signal, the method waits until the
connection completes, or raises a @ref{c0e,,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{1141,,InterruptedError} exception if the connection is interrupted by a
signal (or the exception raised by the signal handler).

Raises an @ref{1e65,,auditing event} @code{socket.connect} with arguments @code{self}, @code{address}.


Άλλαξε στην έκδοση 3.5: The method now waits until the connection completes instead of raising an
@ref{1141,,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{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex connect_ex() (μέθοδος της socket.socket)
@anchor{library/socket socket socket connect_ex}@anchor{18db}
@deffn {Μέθοδος} 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{1e65,,auditing event} @code{socket.connect} with arguments @code{self}, @code{address}.

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex detach() (μέθοδος της socket.socket)
@anchor{library/socket socket socket detach}@anchor{15c3}
@deffn {Μέθοδος} 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.


Added in version 3.2.

@end deffn

@geindex dup() (μέθοδος της socket.socket)
@anchor{library/socket socket socket dup}@anchor{3be7}
@deffn {Μέθοδος} socket.dup ()

Duplicate the socket.

The newly created socket is @ref{12aa,,non-inheritable}.


Άλλαξε στην έκδοση 3.4: The socket is now non-inheritable.


@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex fileno() (μέθοδος της socket.socket)
@anchor{library/socket socket socket fileno}@anchor{3be8}
@deffn {Μέθοδος} socket.fileno ()

Return the socket’s file descriptor (a small integer), or -1 on failure. This
is useful with @ref{1159,,select.select()}.

Under Windows the small integer returned by this method cannot be used where a
file descriptor can be used (such as @ref{2571,,os.fdopen()}).  Unix does not have
this limitation.
@end deffn

@geindex get_inheritable() (μέθοδος της socket.socket)
@anchor{library/socket socket socket get_inheritable}@anchor{12af}
@deffn {Μέθοδος} socket.get_inheritable ()

Get the @ref{12aa,,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.


Added in version 3.4.

@end deffn

@geindex getpeername() (μέθοδος της socket.socket)
@anchor{library/socket socket socket getpeername}@anchor{3b1d}
@deffn {Μέθοδος} 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 @ref{3b8d,,Socket families}.
On some systems this function is not supported.
@end deffn

@geindex getsockname() (μέθοδος της socket.socket)
@anchor{library/socket socket socket getsockname}@anchor{50c}
@deffn {Μέθοδος} 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 @ref{3b8d,,Socket families}.
@end deffn

@geindex getsockopt() (μέθοδος της socket.socket)
@anchor{library/socket socket socket getsockopt}@anchor{1092}
@deffn {Μέθοδος} 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{f32,,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{de,,struct} for a way
to decode C structures encoded as byte strings).

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex getblocking() (μέθοδος της socket.socket)
@anchor{library/socket socket socket getblocking}@anchor{f2f}
@deffn {Μέθοδος} 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}.


Added in version 3.7.

@end deffn

@geindex gettimeout() (μέθοδος της socket.socket)
@anchor{library/socket socket socket gettimeout}@anchor{3be9}
@deffn {Μέθοδος} 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{3261,,setblocking()} or @ref{3b9a,,settimeout()}.
@end deffn

@geindex ioctl() (μέθοδος της socket.socket)
@anchor{library/socket socket socket ioctl}@anchor{1090}
@deffn {Μέθοδος} socket.ioctl (control, option)

The @code{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{1962,,fcntl.fcntl()} and @ref{181d,,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}.

@ref{232d,,Διαθεσιμότητα}: Windows


Άλλαξε στην έκδοση 3.6: @code{SIO_LOOPBACK_FAST_PATH} was added.

@end deffn

@geindex listen() (μέθοδος της socket.socket)
@anchor{library/socket socket socket listen}@anchor{120f}
@deffn {Μέθοδος} 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{232d,,Διαθεσιμότητα}: not WASI.


Άλλαξε στην έκδοση 3.5: The `backlog' parameter is now optional.

@end deffn

@geindex makefile() (μέθοδος της socket.socket)
@anchor{library/socket socket socket makefile}@anchor{1548}
@deffn {Μέθοδος} socket.makefile (mode='r', buffering=None, *, encoding=None, errors=None, newline=None)

@geindex I/O control;buffering

Return a @ref{156c,,file object} associated with the socket.  The exact returned
type depends on the arguments given to @code{makefile()}.  These arguments are
interpreted the same way as by the built-in @ref{32b,,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 @code{makefile()} won’t close the
original socket unless all other file objects have been closed and
@ref{f30,,socket.close()} has been called on the socket object.

@cartouche
@quotation Σημείωση 
On Windows, the file-like object created by @code{makefile()} cannot be
used where a file object with a file descriptor is expected, such as the
stream arguments of @ref{6bf,,subprocess.Popen()}.
@end quotation
@end cartouche
@end deffn

@geindex recv() (μέθοδος της socket.socket)
@anchor{library/socket socket socket recv}@anchor{115d}
@deffn {Μέθοδος} 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.


Άλλαξε στην έκδοση 3.5: If the system call is interrupted and the signal handler does not raise
an exception, the method now retries the system call instead of raising
an @ref{1141,,InterruptedError} exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).

@end deffn

@geindex recvfrom() (μέθοδος της socket.socket)
@anchor{library/socket socket socket recvfrom}@anchor{115e}
@deffn {Μέθοδος} 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
@ref{3b8d,,Socket families}.


Άλλαξε στην έκδοση 3.5: If the system call is interrupted and the signal handler does not raise
an exception, the method now retries the system call instead of raising
an @ref{1141,,InterruptedError} exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).



Άλλαξε στην έκδοση 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{1c42,,getnameinfo()}.

@end deffn

@geindex recvmsg() (μέθοδος της socket.socket)
@anchor{library/socket socket socket recvmsg}@anchor{115f}
@deffn {Μέθοδος} 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{2005,,CMSG_SPACE()} or @ref{2006,,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{115d,,recv()}.

The return value is a 4-tuple: @code{(data, ancdata, msg_flags,
address)}.  The `data' item is a @ref{1c7,,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
@code{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{88c,,sendmsg()} and @code{recvmsg()} can be used to
pass file descriptors between processes over an @ref{1daa,,AF_UNIX}
socket.  When this facility is used (it is often restricted to
@ref{1698,,SOCK_STREAM} sockets), @code{recvmsg()} will return, in its
ancillary data, items of the form @code{(socket.SOL_SOCKET,
socket.SCM_RIGHTS, fds)}, where `fds' is a @ref{1c7,,bytes} object
representing the new file descriptors as a binary array of the
native C int type.  If @code{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, @code{recvmsg()} will issue
a @ref{6dd,,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{88c,,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{232d,,Διαθεσιμότητα}: Unix.

Most Unix platforms.


Added in version 3.3.



Άλλαξε στην έκδοση 3.5: If the system call is interrupted and the signal handler does not raise
an exception, the method now retries the system call instead of raising
an @ref{1141,,InterruptedError} exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).

@end deffn

@geindex recvmsg_into() (μέθοδος της socket.socket)
@anchor{library/socket socket socket recvmsg_into}@anchor{14e6}
@deffn {Μέθοδος} socket.recvmsg_into (buffers[, ancbufsize[, flags]])

Receive normal data and ancillary data from the socket, behaving as
@ref{115f,,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{1c6,,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{1b0d,,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 @code{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{115f,,recvmsg()}.

Example:

@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{232d,,Διαθεσιμότητα}: Unix.

Most Unix platforms.


Added in version 3.3.

@end deffn

@geindex recvfrom_into() (μέθοδος της socket.socket)
@anchor{library/socket socket socket recvfrom_into}@anchor{16c3}
@deffn {Μέθοδος} 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 @ref{3b8d,,Socket families}.
@end deffn

@geindex recv_into() (μέθοδος της socket.socket)
@anchor{library/socket socket socket recv_into}@anchor{16c2}
@deffn {Μέθοδος} 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() (μέθοδος της socket.socket)
@anchor{library/socket socket socket send}@anchor{1160}
@deffn {Μέθοδος} 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{115d,,recv()}.
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{3bea,,Socket Programming HOWTO}.


Άλλαξε στην έκδοση 3.5: If the system call is interrupted and the signal handler does not raise
an exception, the method now retries the system call instead of raising
an @ref{1141,,InterruptedError} exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).

@end deffn

@geindex sendall() (μέθοδος της socket.socket)
@anchor{library/socket socket socket sendall}@anchor{1161}
@deffn {Μέθοδος} 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{115d,,recv()}.
Unlike @ref{1160,,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.


Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.5: If the system call is interrupted and the signal handler does not raise
an exception, the method now retries the system call instead of raising
an @ref{1141,,InterruptedError} exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).

@end deffn

@geindex sendto() (μέθοδος της socket.socket)
@anchor{library/socket socket socket sendto}@anchor{1162}
@deffn {Μέθοδος} socket.sendto (bytes, address)

@deffnx {Μέθοδος} 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{115d,,recv()}.  Return the number of
bytes sent. The format of `address' depends on the address family — see
@ref{3b8d,,Socket families}.

Raises an @ref{1e65,,auditing event} @code{socket.sendto} with arguments @code{self}, @code{address}.


Άλλαξε στην έκδοση 3.5: If the system call is interrupted and the signal handler does not raise
an exception, the method now retries the system call instead of raising
an @ref{1141,,InterruptedError} exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).

@end deffn

@geindex sendmsg() (μέθοδος της socket.socket)
@anchor{library/socket socket socket sendmsg}@anchor{88c}
@deffn {Μέθοδος} 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{436,,bytes-like objects}
(e.g. @ref{1c7,,bytes} objects); the operating system may set a limit
(@ref{1b0d,,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{2005,,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{1160,,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{1daa,,AF_UNIX} socket, on systems which support the
@code{SCM_RIGHTS} mechanism.  See also @ref{115f,,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{232d,,Διαθεσιμότητα}: Unix, not WASI.

Most Unix platforms.

Raises an @ref{1e65,,auditing event} @code{socket.sendmsg} with arguments @code{self}, @code{address}.


Added in version 3.3.



Άλλαξε στην έκδοση 3.5: If the system call is interrupted and the signal handler does not raise
an exception, the method now retries the system call instead of raising
an @ref{1141,,InterruptedError} exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).

@end deffn

@geindex sendmsg_afalg() (μέθοδος της socket.socket)
@anchor{library/socket socket socket sendmsg_afalg}@anchor{1095}
@deffn {Μέθοδος} socket.sendmsg_afalg ([msg], *, op[, iv[, assoclen[, flags]]])

Specialized version of @ref{88c,,sendmsg()} for @ref{1094,,AF_ALG} socket.
Set mode, IV, AEAD associated data length and flags for @code{AF_ALG} socket.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.38.


Added in version 3.6.

@end deffn

@geindex sendfile() (μέθοδος της socket.socket)
@anchor{library/socket socket socket sendfile}@anchor{120e}
@deffn {Μέθοδος} socket.sendfile (file, offset=0, count=None)

Send a file until EOF is reached by using high-performance
@ref{ed3,,os.sendfile} and return the total number of bytes which were sent.
`file' must be a regular file object opened in binary mode. If
@code{os.sendfile} is not available (e.g. Windows) or `file' is not a
regular file @ref{1160,,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{174f,,file.tell()} can be used to figure out the number of
bytes which were sent. The socket must be of @ref{1698,,SOCK_STREAM} type.
Non-blocking sockets are not supported.


Added in version 3.5.

@end deffn

@geindex set_inheritable() (μέθοδος της socket.socket)
@anchor{library/socket socket socket set_inheritable}@anchor{12b0}
@deffn {Μέθοδος} socket.set_inheritable (inheritable)

Set the @ref{12aa,,inheritable flag} of the socket’s file
descriptor or socket’s handle.


Added in version 3.4.

@end deffn

@geindex setblocking() (μέθοδος της socket.socket)
@anchor{library/socket socket socket setblocking}@anchor{3261}
@deffn {Μέθοδος} 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{3b9a,,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


Άλλαξε στην έκδοση 3.7: The method no longer applies @ref{fc9,,SOCK_NONBLOCK} flag on
@ref{fcb,,socket.type}.

@end deffn

@geindex settimeout() (μέθοδος της socket.socket)
@anchor{library/socket socket socket settimeout}@anchor{3b9a}
@deffn {Μέθοδος} socket.settimeout (value)

Set a timeout on blocking socket operations.  The `value' argument can be a
nonnegative real number expressing seconds, or @code{None}.
If a non-zero value is given, subsequent socket operations will raise a
@ref{c0d,,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{3beb,,notes on socket timeouts}.


Άλλαξε στην έκδοση 3.7: The method no longer toggles @ref{fc9,,SOCK_NONBLOCK} flag on
@ref{fcb,,socket.type}.



Άλλαξε στην έκδοση 3.15: Accepts any real number, not only integer or float.

@end deffn

@geindex setsockopt() (μέθοδος της socket.socket)
@anchor{library/socket socket socket setsockopt}@anchor{1093}
@deffn {Μέθοδος} socket.setsockopt (level, optname, value: int | Buffer)

@deffnx {Μέθοδος} 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{436,,bytes-like object} representing a buffer. In the latter
case it is up to the caller to ensure that the bytestring contains the
proper bits (see the optional built-in module @ref{de,,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 calling @code{setsockopt()} C
function with @code{optval=NULL} and @code{optlen=optlen}.


Άλλαξε στην έκδοση 3.5: Writable @ref{436,,bytes-like object} is now accepted.



Άλλαξε στην έκδοση 3.6: setsockopt(level, optname, None, optlen: int) form added.


@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex shutdown() (μέθοδος της socket.socket)
@anchor{library/socket socket socket shutdown}@anchor{3bd7}
@deffn {Μέθοδος} socket.shutdown (how)

Shut down one or both halves of the connection.  If `how' is @ref{3bd4,,SHUT_RD},
further receives are disallowed.  If `how' is @ref{3bd5,,SHUT_WR}, further sends
are disallowed.  If `how' is @ref{3bd6,,SHUT_RDWR}, further sends and receives are
disallowed.

@ref{232d,,Διαθεσιμότητα}: not WASI.
@end deffn

@geindex share() (μέθοδος της socket.socket)
@anchor{library/socket socket socket share}@anchor{fc7}
@deffn {Μέθοδος} 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{fc6,,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{232d,,Διαθεσιμότητα}: Windows.


Added in version 3.3.

@end deffn

Note that there are no methods @code{read()} or @code{write()}; use
@ref{115d,,recv()} and @ref{1160,,send()} without `flags' argument instead.

Socket objects also have these (read-only) attributes that correspond to the
values given to the @ref{115a,,socket} constructor.

@geindex family (ιδιότητα της socket.socket)
@anchor{library/socket socket socket family}@anchor{3bec}
@deffn {Ιδιότητα} socket.family

The socket family.
@end deffn

@geindex type (ιδιότητα της socket.socket)
@anchor{library/socket socket socket type}@anchor{fcb}
@deffn {Ιδιότητα} socket.type

The socket type.
@end deffn

@geindex proto (ιδιότητα της socket.socket)
@anchor{library/socket socket socket proto}@anchor{3bed}
@deffn {Ιδιότητα} socket.proto

The socket protocol.
@end deffn

@node Notes on socket timeouts,Example<7>,Socket Objects,socket — Low-level networking interface
@anchor{library/socket notes-on-socket-timeouts}@anchor{3bee}@anchor{library/socket socket-timeouts}@anchor{3beb}
@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{3b9e,,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{c9,,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{c0d,,timeout} exception)
or if the system returns an error.
@end itemize

@cartouche
@quotation Σημείωση 
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{3be8,,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{3bef}
@subsubsection Timeouts and the @code{connect} method


The @ref{115c,,connect()} operation is also subject to the timeout
setting, and in general it is recommended to call @ref{3b9a,,settimeout()}
before calling @code{connect()} or pass a timeout parameter to
@ref{a62,,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{3bf0}
@subsubsection Timeouts and the @code{accept} method


If @ref{3bdc,,getdefaulttimeout()} is not @ref{a65,,None}, sockets returned by
the @ref{115b,,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{115b,,accept()} is in `blocking mode';

@item 
if the listening socket is in `non-blocking mode', whether the socket
returned by @ref{115b,,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 Example<7>,,Notes on socket timeouts,socket — Low-level networking interface
@anchor{library/socket example}@anchor{3bf1}@anchor{library/socket socket-example}@anchor{3bf2}
@subsubsection Example


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{115a,,socket()},
@ref{18dc,,bind()}, @ref{120f,,listen()}, @ref{115b,,accept()} (possibly
repeating the @code{accept()} to service more than one client), while a
client only needs the sequence @code{socket()}, @ref{115c,,connect()}.  Also
note that the server does not @ref{1161,,sendall()}/@ref{115d,,recv()} on
the socket it is listening on but on the new socket returned by
@code{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{134c,,CAN_BCM}) the socket, you
can use the @ref{1160,,socket.send()} and @ref{115d,,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 @code{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 Δείτε επίσης


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.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node ssl — TLS/SSL wrapper for socket objects,select — Waiting for I/O completion,socket — Low-level networking interface,Networking and Interprocess Communication
@anchor{library/ssl doc}@anchor{3bf3}@anchor{library/ssl module-ssl}@anchor{d8}@anchor{library/ssl ssl-tls-ssl-wrapper-for-socket-objects}@anchor{3bf4}@anchor{library/ssl translation-repo}@anchor{3bf5}
@subsection @code{ssl} — TLS/SSL wrapper for socket objects


@geindex module; ssl

`Source code:' Lib/ssl.py@footnote{https://github.com/python/cpython/tree/main/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.

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile

@cartouche
@quotation Σημείωση 
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 Προειδοποίηση 
Don’t use this module without reading the @ref{3ad9,,Security considerations}.  Doing so
may lead to a false sense of security, as the default settings of the
ssl module are not necessarily appropriate for your application.
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

This section documents the objects and functions in the @code{ssl} module; for more
general information about TLS, SSL, and certificates, the reader is referred to
the documents in the «See Also» section at the bottom.

This module provides a class, @ref{cbb,,ssl.SSLSocket}, which is derived from the
@ref{115a,,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.

For more sophisticated applications, the @ref{336,,ssl.SSLContext} class
helps manage settings and certificates, which can then be inherited
by SSL sockets created through the @ref{933,,SSLContext.wrap_socket()} method.


Άλλαξε στην έκδοση 3.5.3: Updated to support linking with OpenSSL 1.1.0



Άλλαξε στην έκδοση 3.6: OpenSSL 0.9.8, 1.0.0 and 1.0.1 are deprecated and no longer supported.
In the future the ssl module will require at least OpenSSL 1.0.2 or
1.1.0.



Άλλαξε στην έκδοση 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
* Functions@comma{} constants@comma{} and exceptions: Functions constants and exceptions. 
* SSL sockets:: 
* SSL contexts:: 
* Certificates:: 
* Examples: Examples<17>. 
* Notes on non-blocking sockets:: 
* Memory BIO support:: 
* SSL session:: 
* Security considerations: Security considerations<2>. 
* TLS 1.3: TLS 1 3. 

@end menu

@node Functions constants and exceptions,SSL sockets,,ssl — TLS/SSL wrapper for socket objects
@anchor{library/ssl functions-constants-and-exceptions}@anchor{3bf6}
@subsubsection Functions, constants, and exceptions


@menu
* Socket creation:: 
* Context creation:: 
* Signature algorithms:: 
* Exceptions: Exceptions<17>. 
* Random generation:: 
* Certificate handling:: 
* Constants: Constants<9>. 

@end menu

@node Socket creation,Context creation,,Functions constants and exceptions
@anchor{library/ssl socket-creation}@anchor{3bf7}
@subsubsection Socket creation


Instances of @ref{cbb,,SSLSocket} must be created using the
@ref{933,,SSLContext.wrap_socket()} method. The helper function
@ref{68e,,create_default_context()} returns a new context with secure default
settings.

Client socket example with default context and IPv4/IPv6 dual stack:

@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

Client socket example with custom context and 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

Server socket example listening on localhost IPv4:

@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 Context creation,Signature algorithms,Socket creation,Functions constants and exceptions
@anchor{library/ssl context-creation}@anchor{3bf8}
@subsubsection Context creation


A convenience function helps create @ref{336,,SSLContext} objects for common
purposes.

@geindex create_default_context() (στη μονάδα ssl)
@anchor{library/ssl ssl create_default_context}@anchor{68e}
@deffn {Συνάρτηση} ssl.create_default_context (purpose=Purpose.SERVER_AUTH, *, cafile=None, capath=None, cadata=None)

Return a new @ref{336,,SSLContext} object with default settings for
the given `purpose'.  The settings are chosen by the @code{ssl} module,
and usually represent a higher security level than when calling the
@code{SSLContext} constructor directly.

`cafile', `capath', `cadata' represent optional CA certificates to
trust for certificate verification, as in
@ref{129c,,SSLContext.load_verify_locations()}.  If all three are
@ref{a65,,None}, this function can choose to trust the system’s default
CA certificates instead.

The settings are: @ref{c48,,PROTOCOL_TLS_CLIENT} or
@ref{c49,,PROTOCOL_TLS_SERVER}, @ref{c12,,OP_NO_SSLv2}, and @ref{c13,,OP_NO_SSLv3}
with high encryption cipher suites without RC4 and
without unauthenticated cipher suites. Passing @ref{135c,,SERVER_AUTH}
as `purpose' sets @ref{3bf9,,verify_mode} to @ref{3bfa,,CERT_REQUIRED}
and either loads CA certificates (when at least one of `cafile', `capath' or
`cadata' is given) or uses @ref{135b,,SSLContext.load_default_certs()} to load
default CA certificates.

When @ref{3bfb,,keylog_filename} is supported and the environment
variable 
@geindex SSLKEYLOGFILE
@geindex μεταβλητή περιβάλλοντος; SSLKEYLOGFILE
@code{SSLKEYLOGFILE} is set, @code{create_default_context()}
enables key logging.

The default settings for this context include
@ref{68f,,VERIFY_X509_PARTIAL_CHAIN} and @ref{690,,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 Σημείωση 
The protocol, options, cipher and other settings may change to more
restrictive values anytime without prior deprecation.  The values
represent a fair balance between compatibility and security.

If your application needs specific settings, you should create a
@ref{336,,SSLContext} and apply the settings yourself.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
If you find that when certain older clients or servers attempt to connect
with a @ref{336,,SSLContext} created by this function that they get an error
stating «Protocol or cipher suite mismatch», it may be that they only
support SSL3.0 which this function excludes using the
@ref{c13,,OP_NO_SSLv3}. SSL3.0 is widely considered to be completely broken@footnote{https://en.wikipedia.org/wiki/POODLE}. If you still wish to continue to
use this function but still allow SSL 3.0 connections you can re-enable
them using:

@example
ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
ctx.options &= ~ssl.OP_NO_SSLv3
@end example
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
This context enables @ref{690,,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


Added in version 3.4.



Άλλαξε στην έκδοση 3.4.4: RC4 was dropped from the default cipher string.



Άλλαξε στην έκδοση 3.6: ChaCha20/Poly1305 was added to the default cipher string.

3DES was dropped from the default cipher string.



Άλλαξε στην έκδοση 3.8: Support for key logging to 
@geindex SSLKEYLOGFILE
@geindex μεταβλητή περιβάλλοντος; SSLKEYLOGFILE
@code{SSLKEYLOGFILE} was added.



Άλλαξε στην έκδοση 3.10: The context now uses @ref{c48,,PROTOCOL_TLS_CLIENT} or
@ref{c49,,PROTOCOL_TLS_SERVER} protocol instead of generic
@ref{3bfc,,PROTOCOL_TLS}.



Άλλαξε στην έκδοση 3.13: The context now uses @ref{68f,,VERIFY_X509_PARTIAL_CHAIN} and
@ref{690,,VERIFY_X509_STRICT} in its default verify flags.

@end deffn

@node Signature algorithms,Exceptions<17>,Context creation,Functions constants and exceptions
@anchor{library/ssl signature-algorithms}@anchor{3bfd}
@subsubsection Signature algorithms


@geindex get_sigalgs() (στη μονάδα ssl)
@anchor{library/ssl ssl get_sigalgs}@anchor{260}
@deffn {Συνάρτηση} ssl.get_sigalgs ()

Return a list of available TLS signature algorithm names used
by servers to complete the TLS handshake or clients requesting
certificate-based authentication. For example:

@example
>>> ssl.get_sigalgs()
['ecdsa_secp256r1_sha256', 'ecdsa_secp384r1_sha384', ...]
@end example

These names can be used when building string values to pass to the
@ref{261,,SSLContext.set_client_sigalgs()} and
@ref{262,,SSLContext.set_server_sigalgs()} methods.


Added in version 3.15.

@end deffn

@node Exceptions<17>,Random generation,Signature algorithms,Functions constants and exceptions
@anchor{library/ssl exceptions}@anchor{3bfe}
@subsubsection Exceptions


@geindex SSLError
@anchor{library/ssl ssl SSLError}@anchor{161e}
@deffn {Εξαίρεση} ssl.SSLError

Raised to signal an error from the underlying SSL implementation
(currently provided by the OpenSSL library).  This signifies some
problem in the higher-level encryption and authentication layer that’s
superimposed on the underlying network connection.  This error
is a subtype of @ref{53c,,OSError}.  The error code and message of
@code{SSLError} instances are provided by the OpenSSL library.


Άλλαξε στην έκδοση 3.3: @code{SSLError} used to be a subtype of @ref{13fe,,socket.error}.


@geindex library (ιδιότητα της ssl.SSLError)
@anchor{library/ssl ssl SSLError library}@anchor{14f2}
@deffn {Ιδιότητα} library

A string mnemonic designating the OpenSSL submodule in which the error
occurred, such as @code{SSL}, @code{PEM} or @code{X509}.  The range of possible
values depends on the OpenSSL version.


Added in version 3.3.

@end deffn

@geindex reason (ιδιότητα της ssl.SSLError)
@anchor{library/ssl ssl SSLError reason}@anchor{14f3}
@deffn {Ιδιότητα} 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.


Added in version 3.3.

@end deffn
@end deffn

@geindex SSLZeroReturnError
@anchor{library/ssl ssl SSLZeroReturnError}@anchor{3bff}
@deffn {Εξαίρεση} ssl.SSLZeroReturnError

A subclass of @ref{161e,,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.


Added in version 3.3.

@end deffn

@geindex SSLWantReadError
@anchor{library/ssl ssl SSLWantReadError}@anchor{121a}
@deffn {Εξαίρεση} ssl.SSLWantReadError

A subclass of @ref{161e,,SSLError} raised by a @ref{3c00,,non-blocking SSL socket} when trying to read or write data, but more data needs
to be received on the underlying TCP transport before the request can be
fulfilled.


Added in version 3.3.

@end deffn

@geindex SSLWantWriteError
@anchor{library/ssl ssl SSLWantWriteError}@anchor{121b}
@deffn {Εξαίρεση} ssl.SSLWantWriteError

A subclass of @ref{161e,,SSLError} raised by a @ref{3c00,,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.


Added in version 3.3.

@end deffn

@geindex SSLSyscallError
@anchor{library/ssl ssl SSLSyscallError}@anchor{3c01}
@deffn {Εξαίρεση} ssl.SSLSyscallError

A subclass of @ref{161e,,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.


Added in version 3.3.

@end deffn

@geindex SSLEOFError
@anchor{library/ssl ssl SSLEOFError}@anchor{1903}
@deffn {Εξαίρεση} ssl.SSLEOFError

A subclass of @ref{161e,,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.


Added in version 3.3.

@end deffn

@geindex SSLCertVerificationError
@anchor{library/ssl ssl SSLCertVerificationError}@anchor{f3b}
@deffn {Εξαίρεση} ssl.SSLCertVerificationError

A subclass of @ref{161e,,SSLError} raised when certificate validation has
failed.


Added in version 3.7.


@geindex verify_code (ιδιότητα της ssl.SSLCertVerificationError)
@anchor{library/ssl ssl SSLCertVerificationError verify_code}@anchor{3c02}
@deffn {Ιδιότητα} verify_code

A numeric error number that denotes the verification error.
@end deffn

@geindex verify_message (ιδιότητα της ssl.SSLCertVerificationError)
@anchor{library/ssl ssl SSLCertVerificationError verify_message}@anchor{3c03}
@deffn {Ιδιότητα} verify_message

A human readable string of the verification error.
@end deffn
@end deffn

@geindex CertificateError
@anchor{library/ssl ssl CertificateError}@anchor{3c04}
@deffn {Εξαίρεση} ssl.CertificateError

An alias for @ref{f3b,,SSLCertVerificationError}.


Άλλαξε στην έκδοση 3.7: The exception is now an alias for @ref{f3b,,SSLCertVerificationError}.

@end deffn

@node Random generation,Certificate handling,Exceptions<17>,Functions constants and exceptions
@anchor{library/ssl random-generation}@anchor{3c05}
@subsubsection Random generation


@geindex RAND_bytes() (στη μονάδα ssl)
@anchor{library/ssl ssl RAND_bytes}@anchor{932}
@deffn {Συνάρτηση} ssl.RAND_bytes (num, /)

Return `num' cryptographically strong pseudo-random bytes. Raises an
@ref{161e,,SSLError} if the PRNG has not been seeded with enough data or if the
operation is not supported by the current RAND method. @ref{1e74,,RAND_status()}
can be used to check the status of the PRNG and @ref{3c06,,RAND_add()} can be used
to seed the PRNG.

For almost all applications @ref{931,,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.


Added in version 3.3.

@end deffn

@geindex RAND_status() (στη μονάδα ssl)
@anchor{library/ssl ssl RAND_status}@anchor{1e74}
@deffn {Συνάρτηση} ssl.RAND_status ()

Return @code{True} if the SSL pseudo-random number generator has been seeded
with “enough” randomness, and @code{False} otherwise.  Use @ref{3c06,,ssl.RAND_add()}
to increase the randomness of the pseudo-random number generator.
@end deffn

@geindex RAND_add() (στη μονάδα ssl)
@anchor{library/ssl ssl RAND_add}@anchor{3c06}
@deffn {Συνάρτηση} 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.


Άλλαξε στην έκδοση 3.5: Writable @ref{436,,bytes-like object} is now accepted.

@end deffn

@node Certificate handling,Constants<9>,Random generation,Functions constants and exceptions
@anchor{library/ssl certificate-handling}@anchor{3c07}
@subsubsection Certificate handling


@c import ssl

@geindex cert_time_to_seconds() (στη μονάδα ssl)
@anchor{library/ssl ssl cert_time_to_seconds}@anchor{121c}
@deffn {Συνάρτηση} 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
>>> import datetime as dt
>>> timestamp = ssl.cert_time_to_seconds("Jan  5 09:34:43 2018 GMT")
>>> timestamp
1515144883
>>> print(dt.datetime.fromtimestamp(timestamp, dt.UTC))
2018-01-05 09:34:43+00:00
@end example

«notBefore» or «notAfter» dates must use GMT (
@geindex RFC; RFC 5280
RFC 5280@footnote{https://datatracker.ietf.org/doc/html/rfc5280.html}).


Άλλαξε στην έκδοση 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() (στη μονάδα ssl)
@anchor{library/ssl ssl get_server_certificate}@anchor{c15}
@deffn {Συνάρτηση} 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{129c,,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.


Άλλαξε στην έκδοση 3.3: This function is now IPv6-compatible.



Άλλαξε στην έκδοση 3.5: The default `ssl_version' is changed from @ref{3c08,,PROTOCOL_SSLv3} to
@ref{3bfc,,PROTOCOL_TLS} for maximum compatibility with modern servers.



Άλλαξε στην έκδοση 3.10: The `timeout' parameter was added.

@end deffn

@geindex DER_cert_to_PEM_cert() (στη μονάδα ssl)
@anchor{library/ssl ssl DER_cert_to_PEM_cert}@anchor{3c09}
@deffn {Συνάρτηση} 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() (στη μονάδα ssl)
@anchor{library/ssl ssl PEM_cert_to_DER_cert}@anchor{3c0a}
@deffn {Συνάρτηση} 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() (στη μονάδα ssl)
@anchor{library/ssl ssl get_default_verify_paths}@anchor{1353}
@deffn {Συνάρτηση} 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{1354,,SSLContext.set_default_verify_paths()}. The return value is a
@ref{a3d,,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


Added in version 3.4.

@end deffn

@geindex enum_certificates() (στη μονάδα ssl)
@anchor{library/ssl ssl enum_certificates}@anchor{135e}
@deffn {Συνάρτηση} 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.

Example:

@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{232d,,Διαθεσιμότητα}: Windows.


Added in version 3.4.

@end deffn

@geindex enum_crls() (στη μονάδα ssl)
@anchor{library/ssl ssl enum_crls}@anchor{135f}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Windows.


Added in version 3.4.

@end deffn

@node Constants<9>,,Certificate handling,Functions constants and exceptions
@anchor{library/ssl constants}@anchor{3c0b}
@subsubsection Constants


@quotation

All constants are now @ref{109d,,enum.IntEnum} or @ref{105d,,enum.IntFlag} collections.


Added in version 3.6.

@end quotation

@geindex CERT_NONE (στη μονάδα ssl)
@anchor{library/ssl ssl CERT_NONE}@anchor{3c0c}
@deffn {Δεδομένα} ssl.CERT_NONE

Possible value for @ref{3bf9,,SSLContext.verify_mode}.
Except for @ref{c48,,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{3ad9,,Security considerations} below.
@end deffn

@geindex CERT_OPTIONAL (στη μονάδα ssl)
@anchor{library/ssl ssl CERT_OPTIONAL}@anchor{3c0d}
@deffn {Δεδομένα} ssl.CERT_OPTIONAL

Possible value for @ref{3bf9,,SSLContext.verify_mode}.
In client mode, @ref{3c0d,,CERT_OPTIONAL}
has the same meaning as @ref{3bfa,,CERT_REQUIRED}. It is recommended to
use @code{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{129c,,SSLContext.load_verify_locations()}.
@end deffn

@geindex CERT_REQUIRED (στη μονάδα ssl)
@anchor{library/ssl ssl CERT_REQUIRED}@anchor{3bfa}
@deffn {Δεδομένα} ssl.CERT_REQUIRED

Possible value for @ref{3bf9,,SSLContext.verify_mode}.
In this mode, certificates are
required from the other side of the socket connection; an @ref{161e,,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{3c0e,,check_hostname} must be
enabled as well to verify the authenticity of a cert.
@ref{c48,,PROTOCOL_TLS_CLIENT} uses @ref{3bfa,,CERT_REQUIRED} and
enables @code{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{129c,,SSLContext.load_verify_locations()}.
@end deffn

@geindex VerifyMode (κλάση σε ssl)
@anchor{library/ssl ssl VerifyMode}@anchor{3c0f}
@deffn {Κλάση} ssl.VerifyMode

@ref{109d,,enum.IntEnum} collection of CERT_* constants.


Added in version 3.6.

@end deffn

@geindex VERIFY_DEFAULT (στη μονάδα ssl)
@anchor{library/ssl ssl VERIFY_DEFAULT}@anchor{1358}
@deffn {Δεδομένα} ssl.VERIFY_DEFAULT

Possible value for @ref{1357,,SSLContext.verify_flags}. In this mode, certificate
revocation lists (CRLs) are not checked. By default OpenSSL does neither
require nor verify CRLs.


Added in version 3.4.

@end deffn

@geindex VERIFY_CRL_CHECK_LEAF (στη μονάδα ssl)
@anchor{library/ssl ssl VERIFY_CRL_CHECK_LEAF}@anchor{1359}
@deffn {Δεδομένα} ssl.VERIFY_CRL_CHECK_LEAF

Possible value for @ref{1357,,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{129c,,SSLContext.load_verify_locations}, validation will fail.


Added in version 3.4.

@end deffn

@geindex VERIFY_CRL_CHECK_CHAIN (στη μονάδα ssl)
@anchor{library/ssl ssl VERIFY_CRL_CHECK_CHAIN}@anchor{135a}
@deffn {Δεδομένα} ssl.VERIFY_CRL_CHECK_CHAIN

Possible value for @ref{1357,,SSLContext.verify_flags}. In this mode, CRLs of
all certificates in the peer cert chain are checked.


Added in version 3.4.

@end deffn

@geindex VERIFY_X509_STRICT (στη μονάδα ssl)
@anchor{library/ssl ssl VERIFY_X509_STRICT}@anchor{690}
@deffn {Δεδομένα} ssl.VERIFY_X509_STRICT

Possible value for @ref{1357,,SSLContext.verify_flags} to disable workarounds
for broken X.509 certificates.


Added in version 3.4.

@end deffn

@geindex VERIFY_ALLOW_PROXY_CERTS (στη μονάδα ssl)
@anchor{library/ssl ssl VERIFY_ALLOW_PROXY_CERTS}@anchor{1e8b}
@deffn {Δεδομένα} ssl.VERIFY_ALLOW_PROXY_CERTS

Possible value for @ref{1357,,SSLContext.verify_flags} to enables proxy
certificate verification.


Added in version 3.10.

@end deffn

@geindex VERIFY_X509_TRUSTED_FIRST (στη μονάδα ssl)
@anchor{library/ssl ssl VERIFY_X509_TRUSTED_FIRST}@anchor{3c10}
@deffn {Δεδομένα} ssl.VERIFY_X509_TRUSTED_FIRST

Possible value for @ref{1357,,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.


Added in version 3.4.4.

@end deffn

@geindex VERIFY_X509_PARTIAL_CHAIN (στη μονάδα ssl)
@anchor{library/ssl ssl VERIFY_X509_PARTIAL_CHAIN}@anchor{68f}
@deffn {Δεδομένα} ssl.VERIFY_X509_PARTIAL_CHAIN

Possible value for @ref{1357,,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.


Added in version 3.10.

@end deffn

@geindex VerifyFlags (κλάση σε ssl)
@anchor{library/ssl ssl VerifyFlags}@anchor{3c11}
@deffn {Κλάση} ssl.VerifyFlags

@ref{105d,,enum.IntFlag} collection of VERIFY_* constants.


Added in version 3.6.

@end deffn

@geindex PROTOCOL_TLS (στη μονάδα ssl)
@anchor{library/ssl ssl PROTOCOL_TLS}@anchor{3bfc}
@deffn {Δεδομένα} 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.


Added in version 3.6.



Αποσύρθηκε στην έκδοση 3.10: TLS clients and servers require different default settings for secure
communication. The generic TLS protocol constant is deprecated in
favor of @ref{c48,,PROTOCOL_TLS_CLIENT} and @ref{c49,,PROTOCOL_TLS_SERVER}.

@end deffn

@geindex PROTOCOL_TLS_CLIENT (στη μονάδα ssl)
@anchor{library/ssl ssl PROTOCOL_TLS_CLIENT}@anchor{c48}
@deffn {Δεδομένα} 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{3bfa,,CERT_REQUIRED} and
@ref{3c0e,,check_hostname} by default.


Added in version 3.6.

@end deffn

@geindex PROTOCOL_TLS_SERVER (στη μονάδα ssl)
@anchor{library/ssl ssl PROTOCOL_TLS_SERVER}@anchor{c49}
@deffn {Δεδομένα} ssl.PROTOCOL_TLS_SERVER

Auto-negotiate the highest protocol version that both the client and
server support, and configure the context server-side connections.


Added in version 3.6.

@end deffn

@geindex PROTOCOL_SSLv23 (στη μονάδα ssl)
@anchor{library/ssl ssl PROTOCOL_SSLv23}@anchor{3c12}
@deffn {Δεδομένα} ssl.PROTOCOL_SSLv23

Alias for @ref{3bfc,,PROTOCOL_TLS}.


Αποσύρθηκε στην έκδοση 3.6: Use @ref{3bfc,,PROTOCOL_TLS} instead.

@end deffn

@geindex PROTOCOL_SSLv3 (στη μονάδα ssl)
@anchor{library/ssl ssl PROTOCOL_SSLv3}@anchor{3c08}
@deffn {Δεδομένα} 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 Προειδοποίηση 
SSL version 3 is insecure.  Its use is highly discouraged.
@end quotation
@end cartouche


Αποσύρθηκε στην έκδοση 3.6: OpenSSL has deprecated all version specific protocols. Use the default
protocol @ref{c49,,PROTOCOL_TLS_SERVER} or @ref{c48,,PROTOCOL_TLS_CLIENT}
with @ref{c46,,SSLContext.minimum_version} and
@ref{c47,,SSLContext.maximum_version} instead.

@end deffn

@geindex PROTOCOL_TLSv1 (στη μονάδα ssl)
@anchor{library/ssl ssl PROTOCOL_TLSv1}@anchor{3c13}
@deffn {Δεδομένα} ssl.PROTOCOL_TLSv1

Selects TLS version 1.0 as the channel encryption protocol.


Αποσύρθηκε στην έκδοση 3.6: OpenSSL has deprecated all version specific protocols.

@end deffn

@geindex PROTOCOL_TLSv1_1 (στη μονάδα ssl)
@anchor{library/ssl ssl PROTOCOL_TLSv1_1}@anchor{1351}
@deffn {Δεδομένα} ssl.PROTOCOL_TLSv1_1

Selects TLS version 1.1 as the channel encryption protocol.
Available only with openssl version 1.0.1+.


Added in version 3.4.



Αποσύρθηκε στην έκδοση 3.6: OpenSSL has deprecated all version specific protocols.

@end deffn

@geindex PROTOCOL_TLSv1_2 (στη μονάδα ssl)
@anchor{library/ssl ssl PROTOCOL_TLSv1_2}@anchor{1352}
@deffn {Δεδομένα} ssl.PROTOCOL_TLSv1_2

Selects TLS version 1.2 as the channel encryption protocol.
Available only with openssl version 1.0.1+.


Added in version 3.4.



Αποσύρθηκε στην έκδοση 3.6: OpenSSL has deprecated all version specific protocols.

@end deffn

@geindex OP_ALL (στη μονάδα ssl)
@anchor{library/ssl ssl OP_ALL}@anchor{3c14}
@deffn {Δεδομένα} 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.


Added in version 3.2.

@end deffn

@geindex OP_NO_SSLv2 (στη μονάδα ssl)
@anchor{library/ssl ssl OP_NO_SSLv2}@anchor{c12}
@deffn {Δεδομένα} ssl.OP_NO_SSLv2

Prevents an SSLv2 connection.  This option is only applicable in
conjunction with @ref{3bfc,,PROTOCOL_TLS}.  It prevents the peers from
choosing SSLv2 as the protocol version.


Added in version 3.2.



Αποσύρθηκε στην έκδοση 3.6: SSLv2 is deprecated

@end deffn

@geindex OP_NO_SSLv3 (στη μονάδα ssl)
@anchor{library/ssl ssl OP_NO_SSLv3}@anchor{c13}
@deffn {Δεδομένα} ssl.OP_NO_SSLv3

Prevents an SSLv3 connection.  This option is only applicable in
conjunction with @ref{3bfc,,PROTOCOL_TLS}.  It prevents the peers from
choosing SSLv3 as the protocol version.


Added in version 3.2.



Αποσύρθηκε στην έκδοση 3.6: SSLv3 is deprecated

@end deffn

@geindex OP_NO_TLSv1 (στη μονάδα ssl)
@anchor{library/ssl ssl OP_NO_TLSv1}@anchor{3c15}
@deffn {Δεδομένα} ssl.OP_NO_TLSv1

Prevents a TLSv1 connection.  This option is only applicable in
conjunction with @ref{3bfc,,PROTOCOL_TLS}.  It prevents the peers from
choosing TLSv1 as the protocol version.


Added in version 3.2.



Αποσύρθηκε στην έκδοση 3.7: The option is deprecated since OpenSSL 1.1.0, use the new
@ref{c46,,SSLContext.minimum_version} and
@ref{c47,,SSLContext.maximum_version} instead.

@end deffn

@geindex OP_NO_TLSv1_1 (στη μονάδα ssl)
@anchor{library/ssl ssl OP_NO_TLSv1_1}@anchor{3c16}
@deffn {Δεδομένα} ssl.OP_NO_TLSv1_1

Prevents a TLSv1.1 connection. This option is only applicable in conjunction
with @ref{3bfc,,PROTOCOL_TLS}. It prevents the peers from choosing TLSv1.1 as
the protocol version. Available only with openssl version 1.0.1+.


Added in version 3.4.



Αποσύρθηκε στην έκδοση 3.7: The option is deprecated since OpenSSL 1.1.0.

@end deffn

@geindex OP_NO_TLSv1_2 (στη μονάδα ssl)
@anchor{library/ssl ssl OP_NO_TLSv1_2}@anchor{3c17}
@deffn {Δεδομένα} ssl.OP_NO_TLSv1_2

Prevents a TLSv1.2 connection. This option is only applicable in conjunction
with @ref{3bfc,,PROTOCOL_TLS}. It prevents the peers from choosing TLSv1.2 as
the protocol version. Available only with openssl version 1.0.1+.


Added in version 3.4.



Αποσύρθηκε στην έκδοση 3.7: The option is deprecated since OpenSSL 1.1.0.

@end deffn

@geindex OP_NO_TLSv1_3 (στη μονάδα ssl)
@anchor{library/ssl ssl OP_NO_TLSv1_3}@anchor{1e52}
@deffn {Δεδομένα} ssl.OP_NO_TLSv1_3

Prevents a TLSv1.3 connection. This option is only applicable in conjunction
with @ref{3bfc,,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'.


Added in version 3.6.3.



Αποσύρθηκε στην έκδοση 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 (στη μονάδα ssl)
@anchor{library/ssl ssl OP_NO_RENEGOTIATION}@anchor{3c18}
@deffn {Δεδομένα} 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.


Added in version 3.7.

@end deffn

@geindex OP_CIPHER_SERVER_PREFERENCE (στη μονάδα ssl)
@anchor{library/ssl ssl OP_CIPHER_SERVER_PREFERENCE}@anchor{14f4}
@deffn {Δεδομένα} 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.


Added in version 3.3.

@end deffn

@geindex OP_SINGLE_DH_USE (στη μονάδα ssl)
@anchor{library/ssl ssl OP_SINGLE_DH_USE}@anchor{3c19}
@deffn {Δεδομένα} 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.


Added in version 3.3.

@end deffn

@geindex OP_SINGLE_ECDH_USE (στη μονάδα ssl)
@anchor{library/ssl ssl OP_SINGLE_ECDH_USE}@anchor{3c1a}
@deffn {Δεδομένα} 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.


Added in version 3.3.

@end deffn

@geindex OP_ENABLE_MIDDLEBOX_COMPAT (στη μονάδα ssl)
@anchor{library/ssl ssl OP_ENABLE_MIDDLEBOX_COMPAT}@anchor{3c1b}
@deffn {Δεδομένα} 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.


Added in version 3.8.

@end deffn

@geindex OP_NO_COMPRESSION (στη μονάδα ssl)
@anchor{library/ssl ssl OP_NO_COMPRESSION}@anchor{14f1}
@deffn {Δεδομένα} ssl.OP_NO_COMPRESSION

Disable compression on the SSL channel.  This is useful if the application
protocol supports its own compression scheme.


Added in version 3.3.

@end deffn

@geindex Options (κλάση σε ssl)
@anchor{library/ssl ssl Options}@anchor{3c1c}
@deffn {Κλάση} ssl.Options

@ref{105d,,enum.IntFlag} collection of OP_* constants.
@end deffn

@geindex OP_NO_TICKET (στη μονάδα ssl)
@anchor{library/ssl ssl OP_NO_TICKET}@anchor{3c1d}
@deffn {Δεδομένα} ssl.OP_NO_TICKET

Prevent client side from requesting a session ticket.


Added in version 3.6.

@end deffn

@geindex OP_IGNORE_UNEXPECTED_EOF (στη μονάδα ssl)
@anchor{library/ssl ssl OP_IGNORE_UNEXPECTED_EOF}@anchor{c10}
@deffn {Δεδομένα} ssl.OP_IGNORE_UNEXPECTED_EOF

Ignore unexpected shutdown of TLS connections.

This option is only available with OpenSSL 3.0.0 and later.


Added in version 3.10.

@end deffn

@geindex OP_ENABLE_KTLS (στη μονάδα ssl)
@anchor{library/ssl ssl OP_ENABLE_KTLS}@anchor{1a43}
@deffn {Δεδομένα} 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.


Added in version 3.12.

@end deffn

@geindex OP_LEGACY_SERVER_CONNECT (στη μονάδα ssl)
@anchor{library/ssl ssl OP_LEGACY_SERVER_CONNECT}@anchor{1cf0}
@deffn {Δεδομένα} ssl.OP_LEGACY_SERVER_CONNECT

Allow legacy insecure renegotiation between OpenSSL and unpatched servers
only.


Added in version 3.12.

@end deffn

@geindex HAS_ALPN (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_ALPN}@anchor{1217}
@deffn {Δεδομένα} 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}.


Added in version 3.5.

@end deffn

@geindex HAS_NEVER_CHECK_COMMON_NAME (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_NEVER_CHECK_COMMON_NAME}@anchor{3c1e}
@deffn {Δεδομένα} ssl.HAS_NEVER_CHECK_COMMON_NAME

Whether the OpenSSL library has built-in support not checking subject
common name and @ref{f3c,,SSLContext.hostname_checks_common_name} is
writeable.


Added in version 3.7.

@end deffn

@geindex HAS_ECDH (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_ECDH}@anchor{3c1f}
@deffn {Δεδομένα} 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.


Added in version 3.3.

@end deffn

@geindex HAS_SNI (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_SNI}@anchor{3c20}
@deffn {Δεδομένα} 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}).


Added in version 3.2.

@end deffn

@geindex HAS_NPN (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_NPN}@anchor{3c21}
@deffn {Δεδομένα} 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{337,,SSLContext.set_npn_protocols()} method to advertise
which protocols you want to support.


Added in version 3.3.

@end deffn

@geindex HAS_SSLv2 (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_SSLv2}@anchor{3c22}
@deffn {Δεδομένα} ssl.HAS_SSLv2

Whether the OpenSSL library has built-in support for the SSL 2.0 protocol.


Added in version 3.7.

@end deffn

@geindex HAS_SSLv3 (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_SSLv3}@anchor{3c23}
@deffn {Δεδομένα} ssl.HAS_SSLv3

Whether the OpenSSL library has built-in support for the SSL 3.0 protocol.


Added in version 3.7.

@end deffn

@geindex HAS_TLSv1 (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_TLSv1}@anchor{3c24}
@deffn {Δεδομένα} ssl.HAS_TLSv1

Whether the OpenSSL library has built-in support for the TLS 1.0 protocol.


Added in version 3.7.

@end deffn

@geindex HAS_TLSv1_1 (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_TLSv1_1}@anchor{f42}
@deffn {Δεδομένα} ssl.HAS_TLSv1_1

Whether the OpenSSL library has built-in support for the TLS 1.1 protocol.


Added in version 3.7.

@end deffn

@geindex HAS_TLSv1_2 (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_TLSv1_2}@anchor{3c25}
@deffn {Δεδομένα} ssl.HAS_TLSv1_2

Whether the OpenSSL library has built-in support for the TLS 1.2 protocol.


Added in version 3.7.

@end deffn

@geindex HAS_TLSv1_3 (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_TLSv1_3}@anchor{3c26}
@deffn {Δεδομένα} ssl.HAS_TLSv1_3

Whether the OpenSSL library has built-in support for the TLS 1.3 protocol.


Added in version 3.7.

@end deffn

@geindex HAS_PSK (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_PSK}@anchor{3c27}
@deffn {Δεδομένα} ssl.HAS_PSK

Whether the OpenSSL library has built-in support for TLS-PSK.


Added in version 3.13.

@end deffn

@geindex HAS_PSK_TLS13 (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_PSK_TLS13}@anchor{259}
@deffn {Δεδομένα} ssl.HAS_PSK_TLS13

Whether the OpenSSL library has built-in support for External PSKs in TLS
1.3 as described in 
@geindex RFC; RFC 9258
RFC 9258@footnote{https://datatracker.ietf.org/doc/html/rfc9258.html}.


Added in version 3.15.

@end deffn

@geindex HAS_PHA (στη μονάδα ssl)
@anchor{library/ssl ssl HAS_PHA}@anchor{50e}
@deffn {Δεδομένα} ssl.HAS_PHA

Whether the OpenSSL library has built-in support for TLS-PHA.


Added in version 3.14.

@end deffn

@geindex CHANNEL_BINDING_TYPES (στη μονάδα ssl)
@anchor{library/ssl ssl CHANNEL_BINDING_TYPES}@anchor{3c28}
@deffn {Δεδομένα} ssl.CHANNEL_BINDING_TYPES

List of supported TLS channel binding types.  Strings in this list
can be used as arguments to @ref{14ef,,SSLSocket.get_channel_binding()}.


Added in version 3.3.

@end deffn

@geindex OPENSSL_VERSION (στη μονάδα ssl)
@anchor{library/ssl ssl OPENSSL_VERSION}@anchor{15c5}
@deffn {Δεδομένα} 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


Added in version 3.2.

@end deffn

@geindex OPENSSL_VERSION_INFO (στη μονάδα ssl)
@anchor{library/ssl ssl OPENSSL_VERSION_INFO}@anchor{15c6}
@deffn {Δεδομένα} 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


Added in version 3.2.

@end deffn

@geindex OPENSSL_VERSION_NUMBER (στη μονάδα ssl)
@anchor{library/ssl ssl OPENSSL_VERSION_NUMBER}@anchor{15c7}
@deffn {Δεδομένα} 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


Added in version 3.2.

@end deffn

@geindex ALERT_DESCRIPTION_HANDSHAKE_FAILURE (στη μονάδα ssl)
@geindex ALERT_DESCRIPTION_INTERNAL_ERROR (στη μονάδα ssl)
@anchor{library/ssl ssl ALERT_DESCRIPTION_HANDSHAKE_FAILURE}@anchor{3c29}
@deffn {Δεδομένα} ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE
@anchor{library/ssl ssl ALERT_DESCRIPTION_INTERNAL_ERROR}@anchor{3c2a}
@deffnx {Δεδομένα} ssl.ALERT_DESCRIPTION_INTERNAL_ERROR

@deffnx {Δεδομένα} 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{1360,,SSLContext.set_servername_callback()}.


Added in version 3.4.

@end deffn

@geindex AlertDescription (κλάση σε ssl)
@anchor{library/ssl ssl AlertDescription}@anchor{3c2b}
@deffn {Κλάση} ssl.AlertDescription

@ref{109d,,enum.IntEnum} collection of ALERT_DESCRIPTION_* constants.


Added in version 3.6.

@end deffn

@geindex Purpose.SERVER_AUTH (στη μονάδα ssl)
@anchor{library/ssl ssl Purpose SERVER_AUTH}@anchor{135c}
@deffn {Δεδομένα} Purpose.SERVER_AUTH

Option for @ref{68e,,create_default_context()} and
@ref{135b,,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).


Added in version 3.4.

@end deffn

@geindex Purpose.CLIENT_AUTH (στη μονάδα ssl)
@anchor{library/ssl ssl Purpose CLIENT_AUTH}@anchor{135d}
@deffn {Δεδομένα} Purpose.CLIENT_AUTH

Option for @ref{68e,,create_default_context()} and
@ref{135b,,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).


Added in version 3.4.

@end deffn

@geindex SSLErrorNumber (κλάση σε ssl)
@anchor{library/ssl ssl SSLErrorNumber}@anchor{3c2c}
@deffn {Κλάση} ssl.SSLErrorNumber

@ref{109d,,enum.IntEnum} collection of SSL_ERROR_* constants.


Added in version 3.6.

@end deffn

@geindex TLSVersion (κλάση σε ssl)
@anchor{library/ssl ssl TLSVersion}@anchor{3c2d}
@deffn {Κλάση} ssl.TLSVersion

@ref{109d,,enum.IntEnum} collection of SSL and TLS versions for
@ref{c47,,SSLContext.maximum_version} and @ref{c46,,SSLContext.minimum_version}.


Added in version 3.7.

@end deffn

@geindex MINIMUM_SUPPORTED (ιδιότητα της ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion MINIMUM_SUPPORTED}@anchor{3c2e}
@deffn {Ιδιότητα} TLSVersion.MINIMUM_SUPPORTED
@end deffn

@geindex MAXIMUM_SUPPORTED (ιδιότητα της ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion MAXIMUM_SUPPORTED}@anchor{3c2f}
@deffn {Ιδιότητα} 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 (ιδιότητα της ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion SSLv3}@anchor{3c30}
@deffn {Ιδιότητα} TLSVersion.SSLv3
@end deffn

@geindex TLSv1 (ιδιότητα της ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion TLSv1}@anchor{3c31}
@deffn {Ιδιότητα} TLSVersion.TLSv1
@end deffn

@geindex TLSv1_1 (ιδιότητα της ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion TLSv1_1}@anchor{3c32}
@deffn {Ιδιότητα} TLSVersion.TLSv1_1
@end deffn

@geindex TLSv1_2 (ιδιότητα της ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion TLSv1_2}@anchor{3c33}
@deffn {Ιδιότητα} TLSVersion.TLSv1_2
@end deffn

@geindex TLSv1_3 (ιδιότητα της ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion TLSv1_3}@anchor{3c34}
@deffn {Ιδιότητα} TLSVersion.TLSv1_3

SSL 3.0 to TLS 1.3.


Αποσύρθηκε στην έκδοση 3.10: All @ref{3c2d,,TLSVersion} members except @ref{3c33,,TLSVersion.TLSv1_2} and
@code{TLSVersion.TLSv1_3} are deprecated.

@end deffn

@node SSL sockets,SSL contexts,Functions constants and exceptions,ssl — TLS/SSL wrapper for socket objects
@anchor{library/ssl ssl-sockets}@anchor{3c35}
@subsubsection SSL sockets


@geindex SSLSocket (κλάση σε ssl)
@anchor{library/ssl ssl SSLSocket}@anchor{cbb}
@deffn {Κλάση} ssl.SSLSocket (socket.socket)

SSL sockets provide the following methods of @ref{3bda,,Socket Objects}:


@itemize -

@item 
@ref{115b,,accept()}

@item 
@ref{18dc,,bind()}

@item 
@ref{10fa,,close()}

@item 
@ref{115c,,connect()}

@item 
@ref{15c3,,detach()}

@item 
@ref{3be8,,fileno()}

@item 
@ref{3b1d,,getpeername()}, @ref{50c,,getsockname()}

@item 
@ref{1092,,getsockopt()}, @ref{1093,,setsockopt()}

@item 
@ref{3be9,,gettimeout()}, @ref{3b9a,,settimeout()},
@ref{3261,,setblocking()}

@item 
@ref{120f,,listen()}

@item 
@ref{1548,,makefile()}

@item 
@ref{115d,,recv()}, @ref{16c2,,recv_into()}
(but passing a non-zero @code{flags} argument is not allowed)

@item 
@ref{1160,,send()}, @ref{1161,,sendall()} (with
the same limitation)

@item 
@ref{120e,,sendfile()} (it may be high-performant only when
the kernel TLS is enabled by setting @ref{1a43,,OP_ENABLE_KTLS} or when a
socket is plain-text, else @ref{1160,,send()} will be used)

@item 
@ref{3bd7,,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{3c00,,notes on non-blocking sockets}.

Instances of @code{SSLSocket} must be created using the
@ref{933,,SSLContext.wrap_socket()} method.


Άλλαξε στην έκδοση 3.5: The @code{sendfile()} method was added.



Άλλαξε στην έκδοση 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.



Αποσύρθηκε στην έκδοση 3.6: It is deprecated to create a @code{SSLSocket} instance directly, use
@ref{933,,SSLContext.wrap_socket()} to wrap a socket.



Άλλαξε στην έκδοση 3.7: @code{SSLSocket} instances must to created with
@ref{933,,wrap_socket()}. In earlier versions, it was possible
to create instances directly. This was never documented or officially
supported.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.15: Python now uses @code{SSL_sendfile} internally when possible. The
function sends a file more efficiently because it performs TLS encryption
in the kernel to avoid additional context switches.

@end deffn

SSL sockets also have the following additional methods and attributes:

@geindex read() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket read}@anchor{121f}
@deffn {Μέθοδος} 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{121a,,SSLWantReadError} or @ref{121b,,SSLWantWriteError} if the socket is
@ref{3c00,,non-blocking} and the read would block.

As at any time a re-negotiation is possible, a call to @code{read()} can also
cause write operations.


Άλλαξε στην έκδοση 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.



Αποσύρθηκε στην έκδοση 3.6: Use @code{recv()} instead of @code{read()}.

@end deffn

@geindex write() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket write}@anchor{1220}
@deffn {Μέθοδος} SSLSocket.write (data)

Write `data' to the SSL socket and return the number of bytes written. The
`data' argument must be an object supporting the buffer interface.

Raise @ref{121a,,SSLWantReadError} or @ref{121b,,SSLWantWriteError} if the socket is
@ref{3c00,,non-blocking} and the write would block.

As at any time a re-negotiation is possible, a call to @code{write()} can
also cause read operations.


Άλλαξε στην έκδοση 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 `data'.



Αποσύρθηκε στην έκδοση 3.6: Use @code{send()} instead of @code{write()}.

@end deffn

@cartouche
@quotation Σημείωση 
The @ref{121f,,read()} and @ref{1220,,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{3c36,,SSLSocket.unwrap()} was not called.

Normally you should use the socket API methods like
@ref{115d,,recv()} and @ref{1160,,send()} instead of these
methods.
@end quotation
@end cartouche

@geindex do_handshake() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket do_handshake}@anchor{121e}
@deffn {Μέθοδος} SSLSocket.do_handshake (block=False)

Perform the SSL setup handshake.

If `block' is true and the timeout obtained by @ref{3be9,,gettimeout()}
is zero, the socket is set in blocking mode until the handshake is performed.


Άλλαξε στην έκδοση 3.4: The handshake method also performs @code{match_hostname()} when the
@ref{3c0e,,check_hostname} attribute of the socket’s
@ref{3c37,,context} is true.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 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() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket getpeercert}@anchor{1361}
@deffn {Μέθοδος} 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{277,,ValueError}.

If the @code{binary_form} parameter is @ref{ef5,,False}, and a certificate was
received from the peer, this method returns a @ref{188,,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{fcc,,True}, and a certificate was
provided, this method returns the DER-encoded form of the entire certificate
as a sequence of bytes, or @ref{a65,,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 @code{getpeercert()} will return
@ref{a65,,None} if you used @ref{3c0c,,CERT_NONE} (rather than
@ref{3c0d,,CERT_OPTIONAL} or @ref{3bfa,,CERT_REQUIRED}).
@end itemize

See also @ref{3c0e,,SSLContext.check_hostname}.


Άλλαξε στην έκδοση 3.2: The returned dictionary includes additional items such as @code{issuer}
and @code{notBefore}.



Άλλαξε στην έκδοση 3.4: @ref{277,,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.



Άλλαξε στην έκδοση 3.9: IPv6 address strings no longer have a trailing new line.

@end deffn

@geindex get_verified_chain() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket get_verified_chain}@anchor{1b6f}
@deffn {Μέθοδος} 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{1b70,,get_unverified_chain()}.


Added in version 3.13.

@end deffn

@geindex get_unverified_chain() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket get_unverified_chain}@anchor{1b70}
@deffn {Μέθοδος} SSLSocket.get_unverified_chain ()

Returns raw certificate chain provided by the other
end of the SSL channel as a list of DER-encoded bytes.


Added in version 3.13.

@end deffn

@geindex cipher() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket cipher}@anchor{3b1e}
@deffn {Μέθοδος} 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() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket shared_ciphers}@anchor{121d}
@deffn {Μέθοδος} 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.  @code{shared_ciphers()} returns
@code{None} if no connection has been established or the socket is a client
socket.


Added in version 3.5.

@end deffn

@geindex group() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket group}@anchor{25c}
@deffn {Μέθοδος} SSLSocket.group ()

Return the group used for doing key agreement on this connection. If no
connection has been established, returns @code{None}.


Added in version 3.15.

@end deffn

@geindex client_sigalg() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket client_sigalg}@anchor{263}
@deffn {Μέθοδος} SSLSocket.client_sigalg ()

Return the signature algorithm used for performing certificate-based client
authentication on this connection, or @code{None} if no connection has been
established or client authentication didn’t occur.


Added in version 3.15.

@end deffn

@geindex server_sigalg() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket server_sigalg}@anchor{264}
@deffn {Μέθοδος} SSLSocket.server_sigalg ()

Return the signature algorithm used by the server to complete the TLS
handshake on this connection, or @code{None} if no connection has been
established or the cipher suite has no signature.


Added in version 3.15.

@end deffn

@geindex compression() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket compression}@anchor{14f0}
@deffn {Μέθοδος} 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{14f1,,OP_NO_COMPRESSION} to disable SSL-level compression.


Added in version 3.3.

@end deffn

@geindex get_channel_binding() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket get_channel_binding}@anchor{14ef}
@deffn {Μέθοδος} 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{3c28,,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{277,,ValueError} will be
raised if an unsupported channel binding type is requested.


Added in version 3.3.

@end deffn

@geindex selected_alpn_protocol() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket selected_alpn_protocol}@anchor{1216}
@deffn {Μέθοδος} SSLSocket.selected_alpn_protocol ()

Return the protocol that was selected during the TLS handshake.  If
@ref{1215,,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.


Added in version 3.5.

@end deffn

@geindex selected_npn_protocol() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket selected_npn_protocol}@anchor{c4a}
@deffn {Μέθοδος} SSLSocket.selected_npn_protocol ()

Return the higher-level protocol that was selected during the TLS/SSL
handshake. If @ref{337,,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}.


Added in version 3.3.



Αποσύρθηκε στην έκδοση 3.10: NPN has been superseded by ALPN

@end deffn

@geindex unwrap() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket unwrap}@anchor{3c36}
@deffn {Μέθοδος} 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() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket verify_client_post_handshake}@anchor{df6}
@deffn {Μέθοδος} 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{df5,,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{161e,,SSLError} is raised.

@cartouche
@quotation Σημείωση 
Only available with OpenSSL 1.1.1 and TLS 1.3 enabled. Without TLS 1.3
support, the method raises @ref{59a,,NotImplementedError}.
@end quotation
@end cartouche


Added in version 3.8.

@end deffn

@geindex version() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket version}@anchor{1219}
@deffn {Μέθοδος} 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.


Added in version 3.5.

@end deffn

@geindex pending() (μέθοδος της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket pending}@anchor{3c38}
@deffn {Μέθοδος} SSLSocket.pending ()

Returns the number of already decrypted bytes available for read, pending on
the connection.
@end deffn

@geindex context (ιδιότητα της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket context}@anchor{3c37}
@deffn {Ιδιότητα} SSLSocket.context

The @ref{336,,SSLContext} object this SSL socket is tied to.


Added in version 3.2.

@end deffn

@geindex server_side (ιδιότητα της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket server_side}@anchor{3c39}
@deffn {Ιδιότητα} SSLSocket.server_side

A boolean which is @code{True} for server-side sockets and @code{False} for
client-side sockets.


Added in version 3.2.

@end deffn

@geindex server_hostname (ιδιότητα της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket server_hostname}@anchor{f3e}
@deffn {Ιδιότητα} SSLSocket.server_hostname

Hostname of the server: @ref{1df,,str} type, or @code{None} for server-side
socket or if the hostname was not specified in the constructor.


Added in version 3.2.



Άλλαξε στην έκδοση 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 (ιδιότητα της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket session}@anchor{1b57}
@deffn {Ιδιότητα} SSLSocket.session

The @ref{109b,,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{121e,,do_handshake()} has been called to reuse a session.


Added in version 3.6.

@end deffn

@geindex session_reused (ιδιότητα της ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket session_reused}@anchor{3c3a}
@deffn {Ιδιότητα} SSLSocket.session_reused


Added in version 3.6.

@end deffn

@node SSL contexts,Certificates,SSL sockets,ssl — TLS/SSL wrapper for socket objects
@anchor{library/ssl ssl-contexts}@anchor{3c3b}
@subsubsection SSL contexts



Added in 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 (κλάση σε ssl)
@anchor{library/ssl ssl SSLContext}@anchor{336}
@deffn {Κλάση} 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{3bfc,,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{3bfc,,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

yes

@tab

no

@tab

no @footnote{
@code{SSLContext} disables SSLv2 with @ref{c12,,OP_NO_SSLv2} by default.
}

@tab

no

@tab

no

@tab

no

@item

`SSLv3'

@tab

no

@tab

yes

@tab

no @footnote{
@code{SSLContext} disables SSLv3 with @ref{c13,,OP_NO_SSLv3} by default.
}

@tab

no

@tab

no

@tab

no

@item

`TLS' (`SSLv23') @footnote{
TLS 1.3 protocol will be available with @ref{3bfc,,PROTOCOL_TLS} in
OpenSSL >= 1.1.1. There is no dedicated PROTOCOL constant for just
TLS 1.3.
}

@tab

no @footnote{
@code{SSLContext} disables SSLv2 with @ref{c12,,OP_NO_SSLv2} by default.
}

@tab

no @footnote{
@code{SSLContext} disables SSLv3 with @ref{c13,,OP_NO_SSLv3} by default.
}

@tab

yes

@tab

yes

@tab

yes

@tab

yes

@item

`TLSv1'

@tab

no

@tab

no

@tab

yes

@tab

yes

@tab

no

@tab

no

@item

`TLSv1.1'

@tab

no

@tab

no

@tab

yes

@tab

no

@tab

yes

@tab

no

@item

`TLSv1.2'

@tab

no

@tab

no

@tab

yes

@tab

no

@tab

no

@tab

yes

@end multitable



@subsubheading Δείτε επίσης


@ref{68e,,create_default_context()} lets the @code{ssl} module choose
security settings for a given purpose.



Άλλαξε στην έκδοση 3.6: The context is created with secure default values. The options
@ref{14f1,,OP_NO_COMPRESSION}, @ref{14f4,,OP_CIPHER_SERVER_PREFERENCE},
@ref{3c19,,OP_SINGLE_DH_USE}, @ref{3c1a,,OP_SINGLE_ECDH_USE},
@ref{c12,,OP_NO_SSLv2},
and @ref{c13,,OP_NO_SSLv3} (except for @ref{3c08,,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.



Αποσύρθηκε στην έκδοση 3.10: @code{SSLContext} without protocol argument is deprecated. The
context class will either require @ref{c48,,PROTOCOL_TLS_CLIENT} or
@ref{c49,,PROTOCOL_TLS_SERVER} protocol in the future.



Άλλαξε στην έκδοση 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{3bfc,,PROTOCOL_TLS}, @ref{c48,,PROTOCOL_TLS_CLIENT}, and
@ref{c49,,PROTOCOL_TLS_SERVER} use TLS 1.2 as minimum TLS version.


@cartouche
@quotation Σημείωση 
@code{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 Σημείωση 
@code{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{336,,SSLContext} objects have the following methods and attributes:

@geindex cert_store_stats() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext cert_store_stats}@anchor{1355}
@deffn {Μέθοδος} 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


Added in version 3.4.

@end deffn

@geindex load_cert_chain() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext load_cert_chain}@anchor{797}
@deffn {Μέθοδος} 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{3c3c,,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{161e,,SSLError} is raised if the private key doesn’t
match with the certificate.


Άλλαξε στην έκδοση 3.3: New optional argument `password'.

@end deffn

@geindex load_default_certs() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext load_default_certs}@anchor{135b}
@deffn {Μέθοδος} 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{1354,,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{135c,,Purpose.SERVER_AUTH} loads certificates, that are
flagged and trusted for TLS web server authentication (client side
sockets). @ref{135d,,Purpose.CLIENT_AUTH} loads CA certificates for client
certificate verification on the server side.


Added in version 3.4.

@end deffn

@geindex load_verify_locations() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext load_verify_locations}@anchor{129c}
@deffn {Μέθοδος} 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{3bf9,,verify_mode} is other than
@ref{3c0c,,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{1357,,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{3c3c,,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{436,,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.


Άλλαξε στην έκδοση 3.4: New optional argument `cadata'

@end deffn

@geindex get_ca_certs() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext get_ca_certs}@anchor{1356}
@deffn {Μέθοδος} SSLContext.get_ca_certs (binary_form=False)

Get a list of loaded «certification authority» (CA) certificates. If the
@code{binary_form} parameter is @ref{ef5,,False} each list
entry is a dict like the output of @ref{1361,,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 Σημείωση 
Certificates in a capath directory aren’t loaded unless they have
been used at least once.
@end quotation
@end cartouche


Added in version 3.4.

@end deffn

@geindex get_ciphers() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext get_ciphers}@anchor{109c}
@deffn {Μέθοδος} SSLContext.get_ciphers ()

Get a list of enabled ciphers. The list is in order of cipher priority.
See @ref{25f,,SSLContext.set_ciphers()}.

Example:

@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


Added in version 3.6.

@end deffn

@geindex get_groups() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext get_groups}@anchor{25d}
@deffn {Μέθοδος} SSLContext.get_groups (*, include_aliases=False)

Get a list of groups implemented for key agreement, taking into
account the current TLS @ref{c46,,minimum_version} and
@ref{c47,,maximum_version} values.  For example:

@example
>>> ctx = ssl.create_default_context()
>>> ctx.minimum_version = ssl.TLSVersion.TLSv1_3
>>> ctx.maximum_version = ssl.TLSVersion.TLSv1_3
>>> ctx.get_groups()
['secp256r1', 'secp384r1', 'secp521r1', 'x25519', 'x448', ...]
@end example

By default, this method returns only the preferred IANA names for the
available groups. However, if the @code{include_aliases} parameter is set to
@ref{fcc,,True} this method will also return any associated aliases such as
the ECDH curve names supported in older versions of OpenSSL.


Added in version 3.15.

@end deffn

@geindex set_default_verify_paths() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_default_verify_paths}@anchor{1354}
@deffn {Μέθοδος} 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() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_ciphers}@anchor{25f}
@deffn {Μέθοδος} SSLContext.set_ciphers (ciphers, /)

Set the allowed ciphers for sockets created with this context when
connecting using TLS 1.2 and earlier.  The `ciphers' argument should
be a string in the OpenSSL cipher list format@footnote{https://docs.openssl.org/master/man1/ciphers/}.
To set allowed TLS 1.3 ciphers, use @ref{25e,,SSLContext.set_ciphersuites()}.

If no cipher can be selected (because compile-time options or other
configuration forbids use of all the specified ciphers), an
@ref{161e,,SSLError} will be raised.

@cartouche
@quotation Σημείωση 
When connected, the @ref{3b1e,,SSLSocket.cipher()} method of SSL sockets will
return details about the negotiated cipher.
@end quotation
@end cartouche
@end deffn

@geindex set_ciphersuites() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_ciphersuites}@anchor{25e}
@deffn {Μέθοδος} SSLContext.set_ciphersuites (ciphersuites, /)

Set the allowed ciphers for sockets created with this context when
connecting using TLS 1.3.  The `ciphersuites' argument should be a
colon-separate string of TLS 1.3 cipher names.  If no cipher can be
selected (because compile-time options or other configuration forbids
use of all the specified ciphers), an @ref{161e,,SSLError} will be raised.

@cartouche
@quotation Σημείωση 
When connected, the @ref{3b1e,,SSLSocket.cipher()} method of SSL sockets will
return details about the negotiated cipher.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn

@geindex set_groups() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_groups}@anchor{25a}
@deffn {Μέθοδος} SSLContext.set_groups (groups, /)

Set the groups allowed for key agreement for sockets created with this
context.  It should be a string in the OpenSSL group list format@footnote{https://docs.openssl.org/master/man3/SSL_CTX_set1_groups_list/}.

@cartouche
@quotation Σημείωση 
When connected, the @ref{25c,,SSLSocket.group()} method of SSL sockets will
return the group used for key agreement on that connection.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn

@geindex set_client_sigalgs() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_client_sigalgs}@anchor{261}
@deffn {Μέθοδος} SSLContext.set_client_sigalgs (sigalgs, /)

Set the signature algorithms allowed for certificate-based client
authentication. It should be a string in the OpenSSL client sigalgs list format@footnote{https://docs.openssl.org/master/man3/SSL_CTX_set1_client_sigalgs_list/}.

@cartouche
@quotation Σημείωση 
When connected, the @ref{263,,SSLSocket.client_sigalg()} method of SSL
sockets will return the signature algorithm used for performing
certificate-based client authentication on that connection.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn

@geindex set_server_sigalgs() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_server_sigalgs}@anchor{262}
@deffn {Μέθοδος} SSLContext.set_server_sigalgs (sigalgs, /)

Set the signature algorithms allowed for the server to complete the TLS
handshake. It should be a string in the OpenSSL sigalgs list format@footnote{https://docs.openssl.org/master/man3/SSL_CTX_set1_sigalgs_list/}.

@cartouche
@quotation Σημείωση 
When connected, the @ref{264,,SSLSocket.server_sigalg()} method of SSL
sockets will return the signature algorithm used by the server to
complete the TLS handshake on that connection.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn

@geindex set_alpn_protocols() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_alpn_protocols}@anchor{1215}
@deffn {Μέθοδος} SSLContext.set_alpn_protocols (alpn_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{1216,,SSLSocket.selected_alpn_protocol()} method will
return the agreed-upon protocol.

This method will raise @ref{59a,,NotImplementedError} if @ref{1217,,HAS_ALPN} is
@code{False}.


Added in version 3.5.

@end deffn

@geindex set_npn_protocols() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_npn_protocols}@anchor{337}
@deffn {Μέθοδος} SSLContext.set_npn_protocols (npn_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{c4a,,SSLSocket.selected_npn_protocol()} method will
return the agreed-upon protocol.

This method will raise @ref{59a,,NotImplementedError} if @ref{3c21,,HAS_NPN} is
@code{False}.


Added in version 3.3.



Αποσύρθηκε στην έκδοση 3.10: NPN has been superseded by ALPN

@end deffn

@geindex sni_callback (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext sni_callback}@anchor{1e85}
@deffn {Ιδιότητα} 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{cbb,,ssl.SSLSocket}, the second is a string
that represents the server name that the client is intending to communicate
(or @ref{a65,,None} if the TLS Client Hello does not contain a server name)
and the third argument is the original @ref{336,,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{cbb,,ssl.SSLSocket}’s
@ref{3c37,,SSLSocket.context} attribute to a new object of type
@ref{336,,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{1216,,SSLSocket.selected_alpn_protocol()} and @ref{3c37,,SSLSocket.context}.
The @ref{1361,,SSLSocket.getpeercert()}, @ref{1b6f,,SSLSocket.get_verified_chain()},
@ref{1b70,,SSLSocket.get_unverified_chain()} @ref{3b1e,,SSLSocket.cipher()}
and @ref{14f0,,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{3c2a,,ALERT_DESCRIPTION_*} can be
returned.  Other return values will result in a TLS fatal error with
@code{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{3c29,,ALERT_DESCRIPTION_HANDSHAKE_FAILURE}.

This method will raise @ref{59a,,NotImplementedError} if the OpenSSL library
had OPENSSL_NO_TLSEXT defined when it was built.


Added in version 3.7.

@end deffn

@geindex set_servername_callback() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_servername_callback}@anchor{1360}
@deffn {Μέθοδος} SSLContext.set_servername_callback (server_name_callback)

This is a legacy API retained for backwards compatibility. When possible,
you should use @ref{1e85,,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{3c2a,,ALERT_DESCRIPTION_INTERNAL_ERROR} fatal TLS
alert message to the client.


Added in version 3.4.

@end deffn

@geindex load_dh_params() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext load_dh_params}@anchor{14ee}
@deffn {Μέθοδος} 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{3c19,,OP_SINGLE_DH_USE} option to further improve security.


Added in version 3.3.

@end deffn

@geindex set_ecdh_curve() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_ecdh_curve}@anchor{25b}
@deffn {Μέθοδος} 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{3c1a,,OP_SINGLE_ECDH_USE} option to further improve security.

This method is not available if @ref{3c1f,,HAS_ECDH} is @code{False}.


Added in version 3.3.



@subsubheading Δείτε επίσης



@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() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext wrap_socket}@anchor{933}
@deffn {Μέθοδος} 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{3c3d,,SSLContext.sslsocket_class} (default @ref{cbb,,SSLSocket}). The
returned SSL socket is tied to the context, its settings and certificates.
`sock' must be a @ref{1698,,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{161e,,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{277,,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{121e,,SSLSocket.do_handshake()} method.  Calling
@code{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{fcc,,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{ef5,,False}, it will raise the
exceptions back to the caller.

`session', see @ref{1b57,,session}.

To wrap an @ref{cbb,,SSLSocket} in another @code{SSLSocket}, use
@ref{f41,,SSLContext.wrap_bio()}.


Άλλαξε στην έκδοση 3.5: Always allow a server_hostname to be passed, even if OpenSSL does not
have SNI.



Άλλαξε στην έκδοση 3.6: `session' argument was added.



Άλλαξε στην έκδοση 3.7: The method returns an instance of @ref{3c3d,,SSLContext.sslsocket_class}
instead of hard-coded @ref{cbb,,SSLSocket}.

@end deffn

@geindex sslsocket_class (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext sslsocket_class}@anchor{3c3d}
@deffn {Ιδιότητα} SSLContext.sslsocket_class

The return type of @ref{933,,SSLContext.wrap_socket()}, defaults to
@ref{cbb,,SSLSocket}. The attribute can be assigned to on instances of
@ref{336,,SSLContext} in order to return a custom subclass of
@code{SSLSocket}.


Added in version 3.7.

@end deffn

@geindex wrap_bio() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext wrap_bio}@anchor{f41}
@deffn {Μέθοδος} 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{3c3e,,SSLContext.sslobject_class} (default @ref{f40,,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{933,,SSLContext.wrap_socket()}.


Άλλαξε στην έκδοση 3.6: `session' argument was added.



Άλλαξε στην έκδοση 3.7: The method returns an instance of @ref{3c3e,,SSLContext.sslobject_class}
instead of hard-coded @ref{f40,,SSLObject}.

@end deffn

@geindex sslobject_class (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext sslobject_class}@anchor{3c3e}
@deffn {Ιδιότητα} SSLContext.sslobject_class

The return type of @ref{f41,,SSLContext.wrap_bio()}, defaults to
@ref{f40,,SSLObject}. The attribute can be overridden on instance of class
in order to return a custom subclass of @code{SSLObject}.


Added in version 3.7.

@end deffn

@geindex session_stats() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext session_stats}@anchor{3c3f}
@deffn {Μέθοδος} 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 (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext check_hostname}@anchor{3c0e}
@deffn {Ιδιότητα} SSLContext.check_hostname

Whether to match the peer cert’s hostname in
@ref{121e,,SSLSocket.do_handshake()}. The context’s
@ref{3bf9,,verify_mode} must be set to @ref{3c0d,,CERT_OPTIONAL} or
@ref{3bfa,,CERT_REQUIRED}, and you must pass `server_hostname' to
@ref{933,,wrap_socket()} in order to match the hostname.  Enabling
hostname checking automatically sets @code{verify_mode} from
@ref{3c0c,,CERT_NONE} to @code{CERT_REQUIRED}.  It cannot be set back to
@code{CERT_NONE} as long as hostname checking is enabled. The
@ref{c48,,PROTOCOL_TLS_CLIENT} protocol enables hostname checking by default.
With other protocols, hostname checking must be enabled explicitly.

Example:

@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


Added in version 3.4.



Άλλαξε στην έκδοση 3.7: @ref{3bf9,,verify_mode} is now automatically changed
to @ref{3bfa,,CERT_REQUIRED}  when hostname checking is enabled and
@code{verify_mode} is @ref{3c0c,,CERT_NONE}. Previously
the same operation would have failed with a @ref{277,,ValueError}.

@end deffn

@geindex keylog_filename (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext keylog_filename}@anchor{3bfb}
@deffn {Ιδιότητα} 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.


Added in version 3.8.

@end deffn

@geindex maximum_version (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext maximum_version}@anchor{c47}
@deffn {Ιδιότητα} SSLContext.maximum_version

A @ref{3c2d,,TLSVersion} enum member representing the highest supported
TLS version. The value defaults to @ref{3c2f,,TLSVersion.MAXIMUM_SUPPORTED}.
The attribute is read-only for protocols other than @ref{3bfc,,PROTOCOL_TLS},
@ref{c48,,PROTOCOL_TLS_CLIENT}, and @ref{c49,,PROTOCOL_TLS_SERVER}.

The attributes @code{maximum_version},
@ref{c46,,minimum_version} and
@ref{c11,,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{3c17,,OP_NO_TLSv1_2} in @code{options} and
@code{maximum_version} set to @ref{3c33,,TLSVersion.TLSv1_2}
will not be able to establish a TLS 1.2 connection.


Added in version 3.7.

@end deffn

@geindex minimum_version (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext minimum_version}@anchor{c46}
@deffn {Ιδιότητα} SSLContext.minimum_version

Like @ref{c47,,SSLContext.maximum_version} except it is the lowest
supported version or @ref{3c2e,,TLSVersion.MINIMUM_SUPPORTED}.


Added in version 3.7.

@end deffn

@geindex num_tickets (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext num_tickets}@anchor{3c40}
@deffn {Ιδιότητα} SSLContext.num_tickets

Control the number of TLS 1.3 session tickets of a
@ref{c49,,PROTOCOL_TLS_SERVER} context. The setting has no impact on TLS
1.0 to 1.2 connections.


Added in version 3.8.

@end deffn

@geindex options (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext options}@anchor{c11}
@deffn {Ιδιότητα} SSLContext.options

An integer representing the set of SSL options enabled on this context.
The default value is @ref{3c14,,OP_ALL}, but you can specify other options
such as @ref{c12,,OP_NO_SSLv2} by ORing them together.


Άλλαξε στην έκδοση 3.6: @code{SSLContext.options} returns @ref{3c1c,,Options} flags:

@example
>>> ssl.create_default_context().options
<Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>
@end example



Αποσύρθηκε στην έκδοση 3.7: All @code{OP_NO_SSL*} and @code{OP_NO_TLS*} options have been deprecated since
Python 3.7. Use @ref{c46,,SSLContext.minimum_version} and
@ref{c47,,SSLContext.maximum_version} instead.

@end deffn

@geindex post_handshake_auth (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext post_handshake_auth}@anchor{df5}
@deffn {Ιδιότητα} 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{3bf9,,SSLContext.verify_mode} must
be set to @ref{3c0d,,CERT_OPTIONAL} or @ref{3bfa,,CERT_REQUIRED}, too. The
actual client cert exchange is delayed until
@ref{df6,,SSLSocket.verify_client_post_handshake()} is called and some I/O is
performed.


Added in version 3.8.

@end deffn

@geindex protocol (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext protocol}@anchor{3c41}
@deffn {Ιδιότητα} SSLContext.protocol

The protocol version chosen when constructing the context.  This attribute
is read-only.
@end deffn

@geindex hostname_checks_common_name (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext hostname_checks_common_name}@anchor{f3c}
@deffn {Ιδιότητα} SSLContext.hostname_checks_common_name

Whether @ref{3c0e,,check_hostname} falls back to verify the cert’s
subject common name in the absence of a subject alternative name
extension (default: true).


Added in version 3.7.



Άλλαξε στην έκδοση 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 (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext security_level}@anchor{3c42}
@deffn {Ιδιότητα} 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.


Added in version 3.10.

@end deffn

@geindex verify_flags (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext verify_flags}@anchor{1357}
@deffn {Ιδιότητα} SSLContext.verify_flags

The flags for certificate verification operations. You can set flags like
@ref{1359,,VERIFY_CRL_CHECK_LEAF} by ORing them together. By default OpenSSL
does neither require nor verify certificate revocation lists (CRLs).


Added in version 3.4.



Άλλαξε στην έκδοση 3.6: @code{SSLContext.verify_flags} returns @ref{3c11,,VerifyFlags} flags:

@example
>>> ssl.create_default_context().verify_flags
<VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>
@end example

@end deffn

@geindex verify_mode (ιδιότητα της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext verify_mode}@anchor{3bf9}
@deffn {Ιδιότητα} 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{3c0c,,CERT_NONE}, @ref{3c0d,,CERT_OPTIONAL} or @ref{3bfa,,CERT_REQUIRED}.


Άλλαξε στην έκδοση 3.6: @code{SSLContext.verify_mode} returns @ref{3c0f,,VerifyMode} enum:

@example
>>> ssl.create_default_context().verify_mode
<VerifyMode.CERT_REQUIRED: 2>
@end example

@end deffn

@geindex set_psk_client_callback() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_psk_client_callback}@anchor{3c43}
@deffn {Μέθοδος} 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{436,,bytes-like object} representing the pre-shared key. Return a zero
length PSK to reject the connection.

Setting @code{callback} to @ref{a65,,None} removes any existing callback.

@cartouche
@quotation Σημείωση 
When using TLS 1.3:


@itemize -

@item 
the @code{hint} parameter is always @ref{a65,,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{59a,,NotImplementedError} if @ref{3c27,,HAS_PSK} is
@code{False}.


Added in version 3.13.

@end deffn

@geindex set_psk_server_callback() (μέθοδος της ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_psk_server_callback}@anchor{3c44}
@deffn {Μέθοδος} 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{436,,bytes-like object} representing the pre-shared key.
Return a zero length PSK to reject the connection.

Setting @code{callback} to @ref{a65,,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 Σημείωση 
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{59a,,NotImplementedError} if @ref{3c27,,HAS_PSK} is
@code{False}.


Added in version 3.13.

@end deffn

@geindex certificates

@geindex X509 certificate

@node Certificates,Examples<17>,SSL contexts,ssl — TLS/SSL wrapper for socket objects
@anchor{library/ssl certificates}@anchor{3c45}@anchor{library/ssl ssl-certificates}@anchor{3c3c}
@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{3c46}
@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{3c47}
@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{135b,,SSLContext.load_default_certs()}, this is done
automatically with @ref{68e,,create_default_context()}.

@node Combined key and certificate,Self-signed certificates,CA certificates,Certificates
@anchor{library/ssl combined-key-and-certificate}@anchor{3c48}
@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{797,,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{3c49}
@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 Examples<17>,Notes on non-blocking sockets,Certificates,ssl — TLS/SSL wrapper for socket objects
@anchor{library/ssl examples}@anchor{3c4a}
@subsubsection Examples


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

@end menu

@node Testing for SSL support,Client-side operation,,Examples<17>
@anchor{library/ssl testing-for-ssl-support}@anchor{3c4b}
@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,Examples<17>
@anchor{library/ssl client-side-operation}@anchor{3c4c}
@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{c48,,PROTOCOL_TLS_CLIENT} protocol configures the context for cert
validation and hostname verification. @ref{3bf9,,verify_mode} is
set to @ref{3bfa,,CERT_REQUIRED} and @ref{3c0e,,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{3bfa,,CERT_REQUIRED}
and @ref{3c0e,,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{3ad9,,Security considerations} below.

@node Server-side operation,,Client-side operation,Examples<17>
@anchor{library/ssl server-side-operation}@anchor{3c4d}
@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{933,,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{3c00,,non-blocking mode} and use an event loop).

@node Notes on non-blocking sockets,Memory BIO support,Examples<17>,ssl — TLS/SSL wrapper for socket objects
@anchor{library/ssl notes-on-non-blocking-sockets}@anchor{3c4e}@anchor{library/ssl ssl-nonblocking}@anchor{3c00}
@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{cbb,,SSLSocket} methods will raise either
@ref{121b,,SSLWantWriteError} or @ref{121a,,SSLWantReadError} instead of
@ref{4c3,,BlockingIOError} if an I/O operation would
block. @code{SSLWantReadError} will be raised if a read operation on
the underlying socket is necessary, and @code{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.


Άλλαξε στην έκδοση 3.5: In earlier Python versions, the @code{SSLSocket.send()} method
returned zero instead of raising @ref{121b,,SSLWantWriteError} or
@ref{121a,,SSLWantReadError}.


@item 
Calling @ref{1159,,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
@code{select()}.

@item 
Conversely, since the SSL layer has its own framing, a SSL socket may
still have data available for reading without @ref{1159,,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 @code{select()} call if still necessary.

(of course, similar provisions apply when using other primitives such as
@ref{268,,poll()}, or those in the @ref{ca,,selectors} module)

@item 
The SSL handshake itself will be non-blocking: the
@ref{121e,,SSLSocket.do_handshake()} method has to be retried until it returns
successfully.  Here is a synopsis using @ref{1159,,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 Δείτε επίσης


The @ref{b,,asyncio} module supports @ref{3c00,,non-blocking SSL sockets} and provides a higher level @ref{19b0,,Streams API}.
It polls for events using the @ref{ca,,selectors} module and
handles @ref{121b,,SSLWantWriteError}, @ref{121a,,SSLWantReadError} and
@ref{4c3,,BlockingIOError} exceptions. It runs the SSL handshake asynchronously
as well.


@node Memory BIO support,SSL session,Notes on non-blocking sockets,ssl — TLS/SSL wrapper for socket objects
@anchor{library/ssl memory-bio-support}@anchor{3c4f}
@subsubsection Memory BIO support



Added in version 3.5.


Ever since the SSL module was introduced in Python 2.6, the @ref{cbb,,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{115a,,socket.socket},
from which @ref{cbb,,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{115a,,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{cbb,,SSLSocket} called @ref{f40,,SSLObject} is
provided.

@geindex SSLObject (κλάση σε ssl)
@anchor{library/ssl ssl SSLObject}@anchor{f40}
@deffn {Κλάση} ssl.SSLObject

A reduced-scope variant of @ref{cbb,,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 @code{SSLObject} instance
must be created using the @ref{f41,,wrap_bio()} method. This
method will create the @code{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{3c37,,context}

@item 
@ref{3c39,,server_side}

@item 
@ref{f3e,,server_hostname}

@item 
@ref{1b57,,session}

@item 
@ref{3c3a,,session_reused}

@item 
@ref{121f,,read()}

@item 
@ref{1220,,write()}

@item 
@ref{1361,,getpeercert()}

@item 
@ref{1b6f,,get_verified_chain()}

@item 
@ref{1b70,,get_unverified_chain()}

@item 
@ref{1216,,selected_alpn_protocol()}

@item 
@ref{c4a,,selected_npn_protocol()}

@item 
@ref{3b1e,,cipher()}

@item 
@ref{121d,,shared_ciphers()}

@item 
@ref{14f0,,compression()}

@item 
@ref{3c38,,pending()}

@item 
@ref{121e,,do_handshake()}

@item 
@ref{df6,,verify_client_post_handshake()}

@item 
@ref{3c36,,unwrap()}

@item 
@ref{14ef,,get_channel_binding()}

@item 
@ref{1219,,version()}
@end itemize

When compared to @ref{cbb,,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{1213,,MemoryBIO} buffers.

@item 
There is no `do_handshake_on_connect' machinery. You must always manually
call @ref{121e,,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{1903,,SSLEOFError} exception.

@item 
The method @ref{3c36,,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{1360,,SSLContext.set_servername_callback()} will get an @code{SSLObject}
instance instead of a @ref{cbb,,SSLSocket} instance as its first parameter.
@end itemize

Some notes related to the use of @code{SSLObject}:


@itemize -

@item 
All IO on an @code{SSLObject} is @ref{3c00,,non-blocking}.
This means that for example @ref{121f,,read()} will raise an
@ref{121a,,SSLWantReadError} if it needs more data than the incoming BIO has
available.
@end itemize


Άλλαξε στην έκδοση 3.7: @code{SSLObject} instances must be created with
@ref{f41,,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{1213,,MemoryBIO} provides a memory buffer that can be used for this
purpose.  It wraps an OpenSSL memory BIO (Basic IO) object:

@geindex MemoryBIO (κλάση σε ssl)
@anchor{library/ssl ssl MemoryBIO}@anchor{1213}
@deffn {Κλάση} ssl.MemoryBIO

A memory buffer that can be used to pass data between Python and an SSL
protocol instance.

@geindex pending (ιδιότητα της ssl.MemoryBIO)
@anchor{library/ssl ssl MemoryBIO pending}@anchor{3c50}
@deffn {Ιδιότητα} pending

Return the number of bytes currently in the memory buffer.
@end deffn

@geindex eof (ιδιότητα της ssl.MemoryBIO)
@anchor{library/ssl ssl MemoryBIO eof}@anchor{3c51}
@deffn {Ιδιότητα} eof

A boolean indicating whether the memory BIO is current at the end-of-file
position.
@end deffn

@geindex read() (μέθοδος της ssl.MemoryBIO)
@anchor{library/ssl ssl MemoryBIO read}@anchor{3c52}
@deffn {Μέθοδος} 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() (μέθοδος της ssl.MemoryBIO)
@anchor{library/ssl ssl MemoryBIO write}@anchor{3c53}
@deffn {Μέθοδος} 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() (μέθοδος της ssl.MemoryBIO)
@anchor{library/ssl ssl MemoryBIO write_eof}@anchor{3c54}
@deffn {Μέθοδος} write_eof ()

Write an EOF marker to the memory BIO. After this method has been called, it
is illegal to call @ref{3c53,,write()}. The attribute @ref{3c51,,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,ssl — TLS/SSL wrapper for socket objects
@anchor{library/ssl ssl-session}@anchor{3c55}
@subsubsection SSL session



Added in version 3.6.


@geindex SSLSession (κλάση σε ssl)
@anchor{library/ssl ssl SSLSession}@anchor{109b}
@deffn {Κλάση} ssl.SSLSession

Session object used by @ref{1b57,,session}.

@geindex id (ιδιότητα της ssl.SSLSession)
@anchor{library/ssl ssl SSLSession id}@anchor{3c56}
@deffn {Ιδιότητα} id
@end deffn

@geindex time (ιδιότητα της ssl.SSLSession)
@anchor{library/ssl ssl SSLSession time}@anchor{3c57}
@deffn {Ιδιότητα} time
@end deffn

@geindex timeout (ιδιότητα της ssl.SSLSession)
@anchor{library/ssl ssl SSLSession timeout}@anchor{3c58}
@deffn {Ιδιότητα} timeout
@end deffn

@geindex ticket_lifetime_hint (ιδιότητα της ssl.SSLSession)
@anchor{library/ssl ssl SSLSession ticket_lifetime_hint}@anchor{3c59}
@deffn {Ιδιότητα} ticket_lifetime_hint
@end deffn

@geindex has_ticket (ιδιότητα της ssl.SSLSession)
@anchor{library/ssl ssl SSLSession has_ticket}@anchor{3c5a}
@deffn {Ιδιότητα} 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{3c5b}@anchor{library/ssl ssl-security}@anchor{3ad9}
@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{3c5c}
@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{68e,,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{cfa,,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{797,,SSLContext.load_cert_chain()}.

By contrast, if you create the SSL context by calling the @ref{336,,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{3c5d}
@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{3c5e}
@subsubsection Verifying certificates


When calling the @ref{336,,SSLContext} constructor directly,
@ref{3c0c,,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{3bfa,,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{1361,,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{3c0e,,SSLContext.check_hostname} is enabled.


Άλλαξε στην έκδοση 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{3bfa,,CERT_REQUIRED} and similarly check the client certificate.

@node Protocol versions,Cipher selection,Verifying certificates,Manual settings
@anchor{library/ssl protocol-versions}@anchor{3c5f}
@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{c48,,PROTOCOL_TLS_CLIENT} or
@ref{c49,,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{c48,,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{3c60}
@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{25f,,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{109c,,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{3c61}
@subsubsection Multi-processing


If using this module as part of a multi-processed application (using,
for example the @ref{98,,multiprocessing} or @ref{24,,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{6bd,,os.fork()}.  Any
successful call of @ref{3c06,,RAND_add()} or @ref{932,,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{f3f}@anchor{library/ssl tls-1-3}@anchor{3c62}
@subsubsection TLS 1.3



Added in 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.  To restrict which TLS 1.3 ciphers
are allowed, the @ref{25e,,SSLContext.set_ciphersuites()} method should be
called instead of @ref{25f,,SSLContext.set_ciphers()}, which only affects
ciphers in older TLS versions.  The @ref{109c,,SSLContext.get_ciphers()} method
returns information about ciphers for both TLS 1.3 and earlier versions
and the method @ref{3b1e,,SSLSocket.cipher()} returns information about the
negotiated cipher for both TLS 1.3 and earlier versions once a connection
is established.

@item 
Session tickets are no longer sent as part of the initial handshake and
are handled differently.  @ref{1b57,,SSLSocket.session} and @ref{109b,,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,
and rekeying are not supported yet.
@end itemize


@subsubheading Δείτε επίσης



@table @asis

@item Class @ref{115a,,socket.socket}

Documentation of underlying @ref{d4,,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. Eastlake, Jeffrey I. Schiller, Steve Crocker

@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}

David Cooper et al.

@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}

Tim Dierks and Eric Rescorla.

@geindex RFC; RFC 6066

@item RFC 6066: Transport Layer Security (TLS) Extensions@footnote{https://datatracker.ietf.org/doc/html/rfc6066.html}

Donald E. 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


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node select — Waiting for I/O completion,selectors — High-level I/O multiplexing,ssl — TLS/SSL wrapper for socket objects,Networking and Interprocess Communication
@anchor{library/select doc}@anchor{3c63}@anchor{library/select module-select}@anchor{c9}@anchor{library/select select-waiting-for-i-o-completion}@anchor{3c64}@anchor{library/select translation-repo}@anchor{3c65}
@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 Σημείωση 
The @ref{ca,,selectors} module allows high-level and efficient I/O
multiplexing, built upon the @code{select} module primitives. Users are
encouraged to use the @code{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{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

The module defines the following:

@geindex error
@anchor{library/select select error}@anchor{13ff}
@deffn {Εξαίρεση} select.error

A deprecated alias of @ref{53c,,OSError}.


Άλλαξε στην έκδοση 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{53c,,OSError}.

@end deffn

@geindex devpoll() (στη μονάδα select)
@anchor{library/select select devpoll}@anchor{133f}
@deffn {Συνάρτηση} select.devpoll ()

(Only supported on Solaris and derivatives.)  Returns a @code{/dev/poll}
polling object; see section @ref{3c66,,/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{12aa,,non-inheritable}.


Added in version 3.3.



Άλλαξε στην έκδοση 3.4: The new file descriptor is now non-inheritable.

@end deffn

@geindex epoll() (στη μονάδα select)
@anchor{library/select select epoll}@anchor{133d}
@deffn {Συνάρτηση} 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(2)@footnote{https://manpages.debian.org/epoll_create1(2)}} 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{3c67,,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{20a,,with} statement, the new file descriptor is automatically closed
at the end of the block.

The new file descriptor is @ref{12aa,,non-inheritable}.


Άλλαξε στην έκδοση 3.3: Added the `flags' parameter.



Άλλαξε στην έκδοση 3.4: Support for the @ref{20a,,with} statement was added.
The new file descriptor is now non-inheritable.



Αποσύρθηκε στην έκδοση 3.4: The `flags' parameter.  @code{select.EPOLL_CLOEXEC} is used by default now.
Use @ref{12ac,,os.set_inheritable()} to make the file descriptor inheritable.



Άλλαξε στην έκδοση 3.15: When CPython is built, this function may be disabled using
@ref{193a,,--disable-epoll}.

@end deffn

@geindex poll() (στη μονάδα select)
@anchor{library/select select poll}@anchor{268}
@deffn {Συνάρτηση} 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{3c68,,Polling Objects} below for the methods supported
by polling objects.
@end deffn

@geindex kqueue() (στη μονάδα select)
@anchor{library/select select kqueue}@anchor{269}
@deffn {Συνάρτηση} select.kqueue ()

(Only supported on BSD.)  Returns a kernel queue object; see section
@ref{3c69,,Kqueue Objects} below for the methods supported by kqueue objects.

The new file descriptor is @ref{12aa,,non-inheritable}.


Άλλαξε στην έκδοση 3.4: The new file descriptor is now non-inheritable.

@end deffn

@geindex kevent() (στη μονάδα select)
@anchor{library/select select kevent}@anchor{3c6a}
@deffn {Συνάρτηση} 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{3c6b,,Kevent Objects} below for the methods supported by kevent objects.
@end deffn

@geindex select() (στη μονάδα select)
@anchor{library/select select select}@anchor{1159}
@deffn {Συνάρτηση} select.select (rlist, wlist, xlist, timeout=None)

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{19b2,,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 in seconds; it may be
a non-integer to specify fractions of seconds.
When the `timeout' argument is omitted or @code{None}, 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{156c,,file objects} (e.g. @code{sys.stdin}, or objects returned by
@ref{32b,,open()} or @ref{585,,os.popen()}), socket objects returned by
@ref{115a,,socket.socket()}.  You may also define a `wrapper' class yourself,
as long as it has an appropriate @ref{19b2,,fileno()} method (that
really returns a file descriptor, not just a random integer).

@cartouche
@quotation Σημείωση 
@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


Άλλαξε στην έκδοση 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{1141,,InterruptedError}.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timeout', not only integer or float.

@end deffn

@geindex PIPE_BUF (στη μονάδα select)
@anchor{library/select select PIPE_BUF}@anchor{15b1}
@deffn {Δεδομένα} 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{1159,,select()},
@code{poll()} or another interface in this module.  This doesn’t apply
to other kinds of file-like objects such as sockets.

This value is guaranteed by POSIX to be at least 512.

@ref{232d,,Διαθεσιμότητα}: Unix


Added in 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{3c6c}@anchor{library/select devpoll-objects}@anchor{3c66}
@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() (μέθοδος της select.devpoll)
@anchor{library/select select devpoll close}@anchor{1341}
@deffn {Μέθοδος} devpoll.close ()

Close the file descriptor of the polling object.


Added in version 3.4.

@end deffn

@geindex closed (ιδιότητα της select.devpoll)
@anchor{library/select select devpoll closed}@anchor{1342}
@deffn {Ιδιότητα} devpoll.closed

@code{True} if the polling object is closed.


Added in version 3.4.

@end deffn

@geindex fileno() (μέθοδος της select.devpoll)
@anchor{library/select select devpoll fileno}@anchor{1340}
@deffn {Μέθοδος} devpoll.fileno ()

Return the file descriptor number of the polling object.


Added in version 3.4.

@end deffn

@geindex register() (μέθοδος της select.devpoll)
@anchor{library/select select devpoll register}@anchor{3c6d}
@deffn {Μέθοδος} devpoll.register (fd[, eventmask])

Register a file descriptor with the polling object.  Future calls to the
@ref{268,,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{19b2,,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 as with @code{poll()}
object. The default value is a combination of the constants @code{POLLIN},
@code{POLLPRI}, and @code{POLLOUT}.

@cartouche
@quotation Προειδοποίηση 
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() (μέθοδος της select.devpoll)
@anchor{library/select select devpoll modify}@anchor{3c6e}
@deffn {Μέθοδος} devpoll.modify (fd[, eventmask])

This method does an @ref{3c6f,,unregister()} followed by a
@ref{3c6d,,register()}. It is (a bit) more efficient than doing the same
explicitly.
@end deffn

@geindex unregister() (μέθοδος της select.devpoll)
@anchor{library/select select devpoll unregister}@anchor{3c6f}
@deffn {Μέθοδος} devpoll.unregister (fd)

Remove a file descriptor being tracked by a polling object.  Just like the
@ref{3c6d,,register()} method, `fd' can be an integer or an object with a
@ref{19b2,,fileno()} method that returns an integer.

Attempting to remove a file descriptor that was never registered is
safely ignored.
@end deffn

@geindex poll() (μέθοδος της select.devpoll)
@anchor{library/select select devpoll poll}@anchor{1155}
@deffn {Μέθοδος} 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{a65,,None}, the call will
block until there is an event for this poll object.


Άλλαξε στην έκδοση 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{1141,,InterruptedError}.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timeout', not only integer or float.

@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{3c70}@anchor{library/select epoll-objects}@anchor{3c67}
@subsubsection Edge and Level Trigger Polling (epoll) Objects


@quotation

@indicateurl{https://linux.die.net/man/4/epoll}

`eventmask'


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constant

@tab

Meaning

@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.

@item

@code{EPOLLWAKEUP}

@tab

Prevents sleep during event waiting.

@end multitable



Added in version 3.6: @code{EPOLLEXCLUSIVE} was added.  It’s only supported by Linux Kernel 4.5
or later.



Added in version 3.14: @code{EPOLLWAKEUP} was added. It’s only supported by Linux Kernel 3.5
or later.

@end quotation

@geindex close() (μέθοδος της select.epoll)
@anchor{library/select select epoll close}@anchor{133e}
@deffn {Μέθοδος} epoll.close ()

Close the control file descriptor of the epoll object.
@end deffn

@geindex closed (ιδιότητα της select.epoll)
@anchor{library/select select epoll closed}@anchor{3c71}
@deffn {Ιδιότητα} epoll.closed

@code{True} if the epoll object is closed.
@end deffn

@geindex fileno() (μέθοδος της select.epoll)
@anchor{library/select select epoll fileno}@anchor{3c72}
@deffn {Μέθοδος} epoll.fileno ()

Return the file descriptor number of the control fd.
@end deffn

@geindex fromfd() (μέθοδος της select.epoll)
@anchor{library/select select epoll fromfd}@anchor{3c73}
@deffn {Μέθοδος} epoll.fromfd (fd)

Create an epoll object from a given file descriptor.
@end deffn

@geindex register() (μέθοδος της select.epoll)
@anchor{library/select select epoll register}@anchor{3c74}
@deffn {Μέθοδος} epoll.register (fd[, eventmask])

Register a fd descriptor with the epoll object.
@end deffn

@geindex modify() (μέθοδος της select.epoll)
@anchor{library/select select epoll modify}@anchor{3c75}
@deffn {Μέθοδος} epoll.modify (fd, eventmask)

Modify a registered file descriptor.
@end deffn

@geindex unregister() (μέθοδος της select.epoll)
@anchor{library/select select epoll unregister}@anchor{d24}
@deffn {Μέθοδος} epoll.unregister (fd)

Remove a registered file descriptor from the epoll object.


Άλλαξε στην έκδοση 3.9: The method no longer ignores the @ref{d25,,EBADF} error.

@end deffn

@geindex poll() (μέθοδος της select.epoll)
@anchor{library/select select epoll poll}@anchor{1156}
@deffn {Μέθοδος} epoll.poll (timeout=None, maxevents=-1)

Wait for events.
If `timeout' is given, it specifies the length of time in seconds
(may be non-integer) which the system will wait for events before returning.


Άλλαξε στην έκδοση 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{1141,,InterruptedError}.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timeout', not only integer or float.

@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{3c68}@anchor{library/select polling-objects}@anchor{3c76}
@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() (μέθοδος της select.poll)
@anchor{library/select select poll register}@anchor{3c77}
@deffn {Μέθοδος} poll.register (fd[, eventmask])

Register a file descriptor with the polling object.  Future calls to the
@ref{268,,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{19b2,,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

Constant

@tab

Meaning

@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() (μέθοδος της select.poll)
@anchor{library/select select poll modify}@anchor{3c78}
@deffn {Μέθοδος} 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{53c,,OSError} exception with errno
@code{ENOENT} to be raised.
@end deffn

@geindex unregister() (μέθοδος της select.poll)
@anchor{library/select select poll unregister}@anchor{3c79}
@deffn {Μέθοδος} poll.unregister (fd)

Remove a file descriptor being tracked by a polling object.  Just like the
@ref{3c77,,register()} method, `fd' can be an integer or an object with a
@ref{19b2,,fileno()} method that returns an integer.

Attempting to remove a file descriptor that was never registered causes a
@ref{7df,,KeyError} exception to be raised.
@end deffn

@geindex poll() (μέθοδος της select.poll)
@anchor{library/select select poll poll}@anchor{1158}
@deffn {Μέθοδος} 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{a65,,None}, the call will
block until there is an event for this poll object.


Άλλαξε στην έκδοση 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{1141,,InterruptedError}.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timeout', not only integer or float.
If @code{ppoll()} function is available, `timeout' has a resolution
of @code{1} ns (@code{1e-6} ms) instead of @code{1} ms.

@end deffn

@node Kqueue Objects,Kevent Objects,Polling Objects,select — Waiting for I/O completion
@anchor{library/select id1}@anchor{3c7a}@anchor{library/select kqueue-objects}@anchor{3c69}
@subsubsection Kqueue Objects


@geindex close() (μέθοδος της select.kqueue)
@anchor{library/select select kqueue close}@anchor{1926}
@deffn {Μέθοδος} kqueue.close ()

Close the control file descriptor of the kqueue object.
@end deffn

@geindex closed (ιδιότητα της select.kqueue)
@anchor{library/select select kqueue closed}@anchor{3c7b}
@deffn {Ιδιότητα} kqueue.closed

@code{True} if the kqueue object is closed.
@end deffn

@geindex fileno() (μέθοδος της select.kqueue)
@anchor{library/select select kqueue fileno}@anchor{3c7c}
@deffn {Μέθοδος} kqueue.fileno ()

Return the file descriptor number of the control fd.
@end deffn

@geindex fromfd() (μέθοδος της select.kqueue)
@anchor{library/select select kqueue fromfd}@anchor{3c7d}
@deffn {Μέθοδος} kqueue.fromfd (fd)

Create a kqueue object from a given file descriptor.
@end deffn

@geindex control() (μέθοδος της select.kqueue)
@anchor{library/select select kqueue control}@anchor{1157}
@deffn {Μέθοδος} 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 (non-integers are possible); the default is @code{None},
to wait forever
@end itemize


Άλλαξε στην έκδοση 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{1141,,InterruptedError}.



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timeout', not only integer or float.

@end deffn

@node Kevent Objects,,Kqueue Objects,select — Waiting for I/O completion
@anchor{library/select id2}@anchor{3c7e}@anchor{library/select kevent-objects}@anchor{3c6b}
@subsubsection Kevent Objects


@indicateurl{https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2}

@geindex ident (ιδιότητα της select.kevent)
@anchor{library/select select kevent ident}@anchor{3c7f}
@deffn {Ιδιότητα} 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{19b2,,fileno()} method. kevent
stores the integer internally.
@end deffn

@geindex filter (ιδιότητα της select.kevent)
@anchor{library/select select kevent filter}@anchor{3c80}
@deffn {Ιδιότητα} kevent.filter

Name of the kernel filter.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constant

@tab

Meaning

@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 (ιδιότητα της select.kevent)
@anchor{library/select select kevent flags}@anchor{3c81}
@deffn {Ιδιότητα} kevent.flags

Filter action.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constant

@tab

Meaning

@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

Permits control() to return the event

@item

@code{KQ_EV_DISABLE}

@tab

Disables event

@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 (ιδιότητα της select.kevent)
@anchor{library/select select kevent fflags}@anchor{3c82}
@deffn {Ιδιότητα} kevent.fflags

Filter specific flags.

@code{KQ_FILTER_READ} and  @code{KQ_FILTER_WRITE} filter flags:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constant

@tab

Meaning

@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

Constant

@tab

Meaning

@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

Constant

@tab

Meaning

@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

Constant

@tab

Meaning

@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 (ιδιότητα της select.kevent)
@anchor{library/select select kevent data}@anchor{3c83}
@deffn {Ιδιότητα} kevent.data

Filter specific data.
@end deffn

@geindex udata (ιδιότητα της select.kevent)
@anchor{library/select select kevent udata}@anchor{3c84}
@deffn {Ιδιότητα} kevent.udata

User defined value.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node selectors — High-level I/O multiplexing,signal — Set handlers for asynchronous events,select — Waiting for I/O completion,Networking and Interprocess Communication
@anchor{library/selectors doc}@anchor{3c85}@anchor{library/selectors module-selectors}@anchor{ca}@anchor{library/selectors selectors-high-level-i-o-multiplexing}@anchor{3c86}@anchor{library/selectors translation-repo}@anchor{3c87}
@subsection @code{selectors} — High-level I/O multiplexing


@geindex module; selectors


Added in version 3.4.


`Source code:' Lib/selectors.py@footnote{https://github.com/python/cpython/tree/main/Lib/selectors.py}


__________________________________________________________________


@menu
* Introduction: Introduction<9>. 
* Classes:: 
* Examples: Examples<18>. 

@end menu

@node Introduction<9>,Classes,,selectors — High-level I/O multiplexing
@anchor{library/selectors introduction}@anchor{3c88}
@subsubsection Introduction


This module allows high-level and efficient I/O multiplexing, built upon the
@ref{c9,,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{3c89,,BaseSelector} abstract base class, along with several
concrete implementations (@ref{3b5a,,KqueueSelector}, @ref{f95,,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{19b2,,fileno()} method, or a raw file descriptor. See @ref{156c,,file object}.

@ref{3c8a,,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 Σημείωση 
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 Δείτε επίσης



@table @asis

@item @ref{c9,,select}

Low-level I/O multiplexing module.
@end table


@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

@node Classes,Examples<18>,Introduction<9>,selectors — High-level I/O multiplexing
@anchor{library/selectors classes}@anchor{3c8b}
@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 module’s
constants below:

@quotation


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constant

@tab

Meaning

@item

@geindex EVENT_READ (στη μονάδα selectors)
@anchor{library/selectors selectors EVENT_READ}@anchor{3c8c}
@deffn {Δεδομένα} selectors.EVENT_READ
@end deffn

@tab

Available for read

@item

@geindex EVENT_WRITE (στη μονάδα selectors)
@anchor{library/selectors selectors EVENT_WRITE}@anchor{3c8d}
@deffn {Δεδομένα} selectors.EVENT_WRITE
@end deffn

@tab

Available for write

@end multitable

@end quotation

@geindex SelectorKey (κλάση σε selectors)
@anchor{library/selectors selectors SelectorKey}@anchor{3c8e}
@deffn {Κλάση} selectors.SelectorKey

A @code{SelectorKey} is a @ref{1cf,,namedtuple} used to
associate a file object to its underlying file descriptor, selected event
mask and attached data. It is returned by several @ref{3c89,,BaseSelector}
methods.

@geindex fileobj (ιδιότητα της selectors.SelectorKey)
@anchor{library/selectors selectors SelectorKey fileobj}@anchor{3c8f}
@deffn {Ιδιότητα} fileobj

File object registered.
@end deffn

@geindex fd (ιδιότητα της selectors.SelectorKey)
@anchor{library/selectors selectors SelectorKey fd}@anchor{3c90}
@deffn {Ιδιότητα} fd

Underlying file descriptor.
@end deffn

@geindex events (ιδιότητα της selectors.SelectorKey)
@anchor{library/selectors selectors SelectorKey events}@anchor{3c91}
@deffn {Ιδιότητα} events

Events that must be waited for on this file object.
@end deffn

@geindex data (ιδιότητα της selectors.SelectorKey)
@anchor{library/selectors selectors SelectorKey data}@anchor{3c92}
@deffn {Ιδιότητα} 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 (κλάση σε selectors)
@anchor{library/selectors selectors BaseSelector}@anchor{3c89}
@deffn {Κλάση} selectors.BaseSelector

A @code{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{3c8a,,DefaultSelector} instead, or one of @ref{3b57,,SelectSelector},
@ref{3b5a,,KqueueSelector} etc. if you want to specifically use an
implementation, and your platform supports it.
@code{BaseSelector} and its concrete implementations support the
@ref{478,,context manager} protocol.

@geindex register() (μέθοδος της selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector register}@anchor{3c93}
@deffn {Μέθοδος} 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{3c8e,,SelectorKey} instance, or raises a
@ref{277,,ValueError} in case of invalid event mask or file descriptor, or
@ref{7df,,KeyError} if the file object is already registered.
@end deffn

@geindex unregister() (μέθοδος της selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector unregister}@anchor{3c94}
@deffn {Μέθοδος} 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{3c8e,,SelectorKey} instance, or raises a
@ref{7df,,KeyError} if `fileobj' is not registered.  It will raise
@ref{277,,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() (μέθοδος της selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector modify}@anchor{f94}
@deffn {Μέθοδος} 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{3c8e,,SelectorKey} instance, or raises a
@ref{277,,ValueError} in case of invalid event mask or file descriptor, or
@ref{7df,,KeyError} if the file object is not registered.
@end deffn

@geindex select() (μέθοδος της selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector select}@anchor{3c95}
@deffn {Μέθοδος} 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{3c8e,,SelectorKey} instance corresponding to a ready file
object.
`events' is a bitmask of events ready on this file object.

@cartouche
@quotation Σημείωση 
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


Άλλαξε στην έκδοση 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() (μέθοδος της selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector close}@anchor{3c96}
@deffn {Μέθοδος} 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() (μέθοδος της selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector get_key}@anchor{3c97}
@deffn {Μέθοδος} get_key (fileobj)

Return the key associated with a registered file object.

This returns the @ref{3c8e,,SelectorKey} instance associated to this file
object, or raises @ref{7df,,KeyError} if the file object is not registered.
@end deffn

@geindex get_map() (μέθοδος της selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector get_map}@anchor{3c98}
@deffn {Μέθοδος} abstractmethod get_map ()

Return a mapping of file objects to selector keys.

This returns a @ref{c9c,,Mapping} instance mapping
registered file objects to their associated @ref{3c8e,,SelectorKey}
instance.
@end deffn
@end deffn

@geindex DefaultSelector (κλάση σε selectors)
@anchor{library/selectors selectors DefaultSelector}@anchor{3c8a}
@deffn {Κλάση} 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 (κλάση σε selectors)
@anchor{library/selectors selectors SelectSelector}@anchor{3b57}
@deffn {Κλάση} selectors.SelectSelector

@ref{1159,,select.select()}-based selector.
@end deffn

@geindex PollSelector (κλάση σε selectors)
@anchor{library/selectors selectors PollSelector}@anchor{f96}
@deffn {Κλάση} selectors.PollSelector

@ref{268,,select.poll()}-based selector.
@end deffn

@geindex EpollSelector (κλάση σε selectors)
@anchor{library/selectors selectors EpollSelector}@anchor{f95}
@deffn {Κλάση} selectors.EpollSelector

@ref{133d,,select.epoll()}-based selector.

@geindex fileno() (μέθοδος της selectors.EpollSelector)
@anchor{library/selectors selectors EpollSelector fileno}@anchor{3c99}
@deffn {Μέθοδος} fileno ()

This returns the file descriptor used by the underlying
@ref{133d,,select.epoll()} object.
@end deffn
@end deffn

@geindex DevpollSelector (κλάση σε selectors)
@anchor{library/selectors selectors DevpollSelector}@anchor{f97}
@deffn {Κλάση} selectors.DevpollSelector

@ref{133f,,select.devpoll()}-based selector.

@geindex fileno() (μέθοδος της selectors.DevpollSelector)
@anchor{library/selectors selectors DevpollSelector fileno}@anchor{3c9a}
@deffn {Μέθοδος} fileno ()

This returns the file descriptor used by the underlying
@ref{133f,,select.devpoll()} object.
@end deffn


Added in version 3.5.

@end deffn

@geindex KqueueSelector (κλάση σε selectors)
@anchor{library/selectors selectors KqueueSelector}@anchor{3b5a}
@deffn {Κλάση} selectors.KqueueSelector

@ref{269,,select.kqueue()}-based selector.

@geindex fileno() (μέθοδος της selectors.KqueueSelector)
@anchor{library/selectors selectors KqueueSelector fileno}@anchor{3c9b}
@deffn {Μέθοδος} fileno ()

This returns the file descriptor used by the underlying
@ref{269,,select.kqueue()} object.
@end deffn
@end deffn

@node Examples<18>,,Classes,selectors — High-level I/O multiplexing
@anchor{library/selectors examples}@anchor{3c9c}
@subsubsection Examples


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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node signal — Set handlers for asynchronous events,mmap — Memory-mapped file support,selectors — High-level I/O multiplexing,Networking and Interprocess Communication
@anchor{library/signal doc}@anchor{3c9d}@anchor{library/signal module-signal}@anchor{ce}@anchor{library/signal signal-set-handlers-for-asynchronous-events}@anchor{3c9e}@anchor{library/signal translation-repo}@anchor{3c9f}
@subsection @code{signal} — Set handlers for asynchronous events


@geindex module; signal

`Source code:' Lib/signal.py@footnote{https://github.com/python/cpython/tree/main/Lib/signal.py}


__________________________________________________________________


This module provides mechanisms to use signal handlers in Python.

@menu
* General rules:: 
* Module contents: Module contents<4>. 
* Examples: Examples<19>. 
* Note on SIGPIPE:: 
* Note on Signal Handlers and Exceptions:: 

@end menu

@node General rules,Module contents<4>,,signal — Set handlers for asynchronous events
@anchor{library/signal general-rules}@anchor{3ca0}
@subsubsection General rules


The @ref{14e0,,signal.signal()} function allows defining custom handlers to be
executed when a signal is received.  A small number of default handlers are
installed: @ref{3ca1,,SIGPIPE} is ignored (so write errors on pipes and sockets
can be reported as ordinary Python exceptions) and @ref{4df,,SIGINT} is
translated into a @ref{d96,,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{3340,,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{3ca2}
@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{3ca3,,virtual machine} to execute the corresponding Python signal handler
at a later point (for example, at the next @ref{6b3,,bytecode} instruction).
This has consequences:


@itemize *

@item 
It makes little sense to catch synchronous errors like @ref{1429,,SIGFPE} or
@ref{1428,,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{5b,,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{28e8,,note below} for a
discussion.
@end itemize

@node Signals and threads,,Execution of Python signal handlers,General rules
@anchor{library/signal id1}@anchor{3ca4}@anchor{library/signal signals-and-threads}@anchor{3ca5}
@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{f6,,threading} module instead.

Besides, only the main thread of the main interpreter is allowed to set a new signal handler.

@cartouche
@quotation Προειδοποίηση 
Synchronization primitives such as @ref{1a10,,threading.Lock} should not be used
within signal handlers.  Doing so can lead to unexpected deadlocks.
@end quotation
@end cartouche

@node Module contents<4>,Examples<19>,General rules,signal — Set handlers for asynchronous events
@anchor{library/signal module-contents}@anchor{3ca6}
@subsubsection Module contents



Άλλαξε στην έκδοση 3.5: signal (SIG*), handler (@ref{1dac,,SIG_DFL}, @ref{1dab,,SIG_IGN}) and sigmask
(@ref{3ca7,,SIG_BLOCK}, @ref{3ca8,,SIG_UNBLOCK}, @ref{3ca9,,SIG_SETMASK})
related constants listed below were turned into
@ref{109d,,enums} (@ref{3caa,,Signals}, @ref{3cab,,Handlers} and @ref{3cac,,Sigmasks} respectively).
@ref{1c2d,,getsignal()}, @ref{14dc,,pthread_sigmask()}, @ref{14de,,sigpending()} and
@ref{14df,,sigwait()} functions return human-readable
@code{enums} as @code{Signals} objects.


The signal module defines three enums:

@geindex Signals (κλάση σε signal)
@anchor{library/signal signal Signals}@anchor{3caa}
@deffn {Κλάση} signal.Signals

@ref{109d,,enum.IntEnum} collection of SIG* constants and the CTRL_* constants.


Added in version 3.5.

@end deffn

@geindex Handlers (κλάση σε signal)
@anchor{library/signal signal Handlers}@anchor{3cab}
@deffn {Κλάση} signal.Handlers

@ref{109d,,enum.IntEnum} collection of the constants @ref{1dac,,SIG_DFL} and @ref{1dab,,SIG_IGN}.


Added in version 3.5.

@end deffn

@geindex Sigmasks (κλάση σε signal)
@anchor{library/signal signal Sigmasks}@anchor{3cac}
@deffn {Κλάση} signal.Sigmasks

@ref{109d,,enum.IntEnum} collection of the constants @ref{3ca7,,SIG_BLOCK}, @ref{3ca8,,SIG_UNBLOCK} and @ref{3ca9,,SIG_SETMASK}.

@ref{232d,,Διαθεσιμότητα}: 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.


Added in version 3.5.

@end deffn

The variables defined in the @code{signal} module are:

@geindex SIG_DFL (στη μονάδα signal)
@anchor{library/signal signal SIG_DFL}@anchor{1dac}
@deffn {Δεδομένα} 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 @ref{3cad,,SIGQUIT} is to dump core and exit, while the
default action for @ref{3340,,SIGCHLD} is to simply ignore it.
@end deffn

@geindex SIG_IGN (στη μονάδα signal)
@anchor{library/signal signal SIG_IGN}@anchor{1dab}
@deffn {Δεδομένα} signal.SIG_IGN

This is another standard signal handler, which will simply ignore the given
signal.
@end deffn

@geindex SIGABRT (στη μονάδα signal)
@anchor{library/signal signal SIGABRT}@anchor{142a}
@deffn {Δεδομένα} signal.SIGABRT

Abort signal from @code{abort(3)@footnote{https://manpages.debian.org/abort(3)}}.
@end deffn

@geindex SIGALRM (στη μονάδα signal)
@anchor{library/signal signal SIGALRM}@anchor{3cae}
@deffn {Δεδομένα} signal.SIGALRM

Timer signal from @code{alarm(2)@footnote{https://manpages.debian.org/alarm(2)}}.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGBREAK (στη μονάδα signal)
@anchor{library/signal signal SIGBREAK}@anchor{3caf}
@deffn {Δεδομένα} signal.SIGBREAK

Interrupt from keyboard (CTRL + BREAK).

@ref{232d,,Διαθεσιμότητα}: Windows.
@end deffn

@geindex SIGBUS (στη μονάδα signal)
@anchor{library/signal signal SIGBUS}@anchor{142b}
@deffn {Δεδομένα} signal.SIGBUS

Bus error (bad memory access).

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGCHLD (στη μονάδα signal)
@anchor{library/signal signal SIGCHLD}@anchor{3340}
@deffn {Δεδομένα} signal.SIGCHLD

Child process stopped or terminated.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGCLD (στη μονάδα signal)
@anchor{library/signal signal SIGCLD}@anchor{3cb0}
@deffn {Δεδομένα} signal.SIGCLD

Alias to @ref{3340,,SIGCHLD}.

@ref{232d,,Διαθεσιμότητα}: not macOS.
@end deffn

@geindex SIGCONT (στη μονάδα signal)
@anchor{library/signal signal SIGCONT}@anchor{334e}
@deffn {Δεδομένα} signal.SIGCONT

Continue the process if it is currently stopped

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGFPE (στη μονάδα signal)
@anchor{library/signal signal SIGFPE}@anchor{1429}
@deffn {Δεδομένα} signal.SIGFPE

Floating-point exception. For example, division by zero.


@subsubheading Δείτε επίσης


@ref{d11,,ZeroDivisionError} is raised when the second argument of a division
or modulo operation is zero.

@end deffn

@geindex SIGHUP (στη μονάδα signal)
@anchor{library/signal signal SIGHUP}@anchor{3cb1}
@deffn {Δεδομένα} signal.SIGHUP

Hangup detected on controlling terminal or death of controlling process.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGILL (στη μονάδα signal)
@anchor{library/signal signal SIGILL}@anchor{142c}
@deffn {Δεδομένα} signal.SIGILL

Illegal instruction.
@end deffn

@geindex SIGINT (στη μονάδα signal)
@anchor{library/signal signal SIGINT}@anchor{4df}
@deffn {Δεδομένα} signal.SIGINT

Interrupt from keyboard (CTRL + C).

Default action is to raise @ref{d96,,KeyboardInterrupt}.
@end deffn

@geindex SIGKILL (στη μονάδα signal)
@anchor{library/signal signal SIGKILL}@anchor{f16}
@deffn {Δεδομένα} signal.SIGKILL

Kill signal.

It cannot be caught, blocked, or ignored.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGPIPE (στη μονάδα signal)
@anchor{library/signal signal SIGPIPE}@anchor{3ca1}
@deffn {Δεδομένα} signal.SIGPIPE

Broken pipe: write to pipe with no readers.

Default action is to ignore the signal.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGPROF (στη μονάδα signal)
@anchor{library/signal signal SIGPROF}@anchor{3cb2}
@deffn {Δεδομένα} signal.SIGPROF

Profiling timer expired.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGQUIT (στη μονάδα signal)
@anchor{library/signal signal SIGQUIT}@anchor{3cad}
@deffn {Δεδομένα} signal.SIGQUIT

Terminal quit signal.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGSEGV (στη μονάδα signal)
@anchor{library/signal signal SIGSEGV}@anchor{1428}
@deffn {Δεδομένα} signal.SIGSEGV

Segmentation fault: invalid memory reference.
@end deffn

@geindex SIGSTOP (στη μονάδα signal)
@anchor{library/signal signal SIGSTOP}@anchor{3cb3}
@deffn {Δεδομένα} signal.SIGSTOP

Stop executing (cannot be caught or ignored).

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGSTKFLT (στη μονάδα signal)
@anchor{library/signal signal SIGSTKFLT}@anchor{1dfe}
@deffn {Δεδομένα} signal.SIGSTKFLT

Stack fault on coprocessor. The Linux kernel does not raise this signal: it
can only be raised in user space.

@ref{232d,,Διαθεσιμότητα}: 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.


Added in version 3.11.

@end deffn

@geindex SIGTERM (στη μονάδα signal)
@anchor{library/signal signal SIGTERM}@anchor{1782}
@deffn {Δεδομένα} signal.SIGTERM

Termination signal.
@end deffn

@geindex SIGUSR1 (στη μονάδα signal)
@anchor{library/signal signal SIGUSR1}@anchor{3cb4}
@deffn {Δεδομένα} signal.SIGUSR1

User-defined signal 1.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGUSR2 (στη μονάδα signal)
@anchor{library/signal signal SIGUSR2}@anchor{3cb5}
@deffn {Δεδομένα} signal.SIGUSR2

User-defined signal 2.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGVTALRM (στη μονάδα signal)
@anchor{library/signal signal SIGVTALRM}@anchor{3cb6}
@deffn {Δεδομένα} signal.SIGVTALRM

Virtual timer expired.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGWINCH (στη μονάδα signal)
@anchor{library/signal signal SIGWINCH}@anchor{3cb7}
@deffn {Δεδομένα} signal.SIGWINCH

Window resize signal.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex SIGXCPU (στη μονάδα signal)
@anchor{library/signal signal SIGXCPU}@anchor{3cb8}
@deffn {Δεδομένα} signal.SIGXCPU

CPU time limit exceeded.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn


@deffn {Δεδομένα} SIG*

All the signal numbers are defined symbolically.  For example, the hangup signal
is defined as @ref{3cb1,,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 (στη μονάδα signal)
@anchor{library/signal signal CTRL_C_EVENT}@anchor{170d}
@deffn {Δεδομένα} signal.CTRL_C_EVENT

The signal corresponding to the @code{Ctrl}+@code{C} keystroke event. This signal can
only be used with @ref{170c,,os.kill()}.

@ref{232d,,Διαθεσιμότητα}: Windows.


Added in version 3.2.

@end deffn

@geindex CTRL_BREAK_EVENT (στη μονάδα signal)
@anchor{library/signal signal CTRL_BREAK_EVENT}@anchor{170e}
@deffn {Δεδομένα} signal.CTRL_BREAK_EVENT

The signal corresponding to the @code{Ctrl}+@code{Break} keystroke event. This signal can
only be used with @ref{170c,,os.kill()}.

@ref{232d,,Διαθεσιμότητα}: Windows.


Added in version 3.2.

@end deffn

@geindex NSIG (στη μονάδα signal)
@anchor{library/signal signal NSIG}@anchor{1d87}
@deffn {Δεδομένα} signal.NSIG

One more than the number of the highest signal number.
Use @ref{3cb9,,valid_signals()} to get valid signal numbers.
@end deffn

@geindex ITIMER_REAL (στη μονάδα signal)
@anchor{library/signal signal ITIMER_REAL}@anchor{3cba}
@deffn {Δεδομένα} signal.ITIMER_REAL

Decrements interval timer in real time, and delivers @ref{3cae,,SIGALRM} upon
expiration.
@end deffn

@geindex ITIMER_VIRTUAL (στη μονάδα signal)
@anchor{library/signal signal ITIMER_VIRTUAL}@anchor{3cbb}
@deffn {Δεδομένα} signal.ITIMER_VIRTUAL

Decrements interval timer only when the process is executing, and delivers
SIGVTALRM upon expiration.
@end deffn

@geindex ITIMER_PROF (στη μονάδα signal)
@anchor{library/signal signal ITIMER_PROF}@anchor{3cbc}
@deffn {Δεδομένα} 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 (στη μονάδα signal)
@anchor{library/signal signal SIG_BLOCK}@anchor{3ca7}
@deffn {Δεδομένα} signal.SIG_BLOCK

A possible value for the `how' parameter to @ref{14dc,,pthread_sigmask()}
indicating that signals are to be blocked.


Added in version 3.3.

@end deffn

@geindex SIG_UNBLOCK (στη μονάδα signal)
@anchor{library/signal signal SIG_UNBLOCK}@anchor{3ca8}
@deffn {Δεδομένα} signal.SIG_UNBLOCK

A possible value for the `how' parameter to @ref{14dc,,pthread_sigmask()}
indicating that signals are to be unblocked.


Added in version 3.3.

@end deffn

@geindex SIG_SETMASK (στη μονάδα signal)
@anchor{library/signal signal SIG_SETMASK}@anchor{3ca9}
@deffn {Δεδομένα} signal.SIG_SETMASK

A possible value for the `how' parameter to @ref{14dc,,pthread_sigmask()}
indicating that the signal mask is to be replaced.


Added in version 3.3.

@end deffn

The @code{signal} module defines one exception:

@geindex ItimerError
@anchor{library/signal signal ItimerError}@anchor{3cbd}
@deffn {Εξαίρεση} signal.ItimerError

Raised to signal an error from the underlying @ref{3cbe,,setitimer()} or
@ref{3cbf,,getitimer()} implementation. Expect this error if an invalid
interval timer or a negative time is passed to @code{setitimer()}.
This error is a subtype of @ref{53c,,OSError}.


Added in version 3.3: This error used to be a subtype of @ref{13fb,,IOError}, which is now an
alias of @ref{53c,,OSError}.

@end deffn

The @code{signal} module defines the following functions:

@geindex alarm() (στη μονάδα signal)
@anchor{library/signal signal alarm}@anchor{3cc0}
@deffn {Συνάρτηση} signal.alarm (time)

If `time' is non-zero, this function requests that a @ref{3cae,,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{232d,,Διαθεσιμότητα}: Unix.

See the man page @code{alarm(2)@footnote{https://manpages.debian.org/alarm(2)}} for further information.
@end deffn

@geindex getsignal() (στη μονάδα signal)
@anchor{library/signal signal getsignal}@anchor{1c2d}
@deffn {Συνάρτηση} 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{1dab,,signal.SIG_IGN}, @ref{1dac,,signal.SIG_DFL} or @ref{a65,,None}.  Here,
@code{signal.SIG_IGN} means that the signal was previously ignored,
@code{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() (στη μονάδα signal)
@anchor{library/signal signal strsignal}@anchor{200d}
@deffn {Συνάρτηση} signal.strsignal (signalnum)

Returns the description of signal `signalnum', such as «Interrupt»
for @ref{4df,,SIGINT}. Returns @ref{a65,,None} if `signalnum' has no
description. Raises @ref{277,,ValueError} if `signalnum' is invalid.


Added in version 3.8.

@end deffn

@geindex valid_signals() (στη μονάδα signal)
@anchor{library/signal signal valid_signals}@anchor{3cb9}
@deffn {Συνάρτηση} 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.


Added in version 3.8.

@end deffn

@geindex pause() (στη μονάδα signal)
@anchor{library/signal signal pause}@anchor{3cc1}
@deffn {Συνάρτηση} signal.pause ()

Cause the process to sleep until a signal is received; the appropriate handler
will then be called.  Returns nothing.

@ref{232d,,Διαθεσιμότητα}: Unix.

See the man page @code{signal(2)@footnote{https://manpages.debian.org/signal(2)}} for further information.

See also @ref{14df,,sigwait()}, @ref{1164,,sigwaitinfo()}, @ref{1163,,sigtimedwait()} and
@ref{14de,,sigpending()}.
@end deffn

@geindex raise_signal() (στη μονάδα signal)
@anchor{library/signal signal raise_signal}@anchor{1d8b}
@deffn {Συνάρτηση} signal.raise_signal (signum)

Sends a signal to the calling process. Returns nothing.


Added in version 3.8.

@end deffn

@geindex pidfd_send_signal() (στη μονάδα signal)
@anchor{library/signal signal pidfd_send_signal}@anchor{cf8}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Linux >= 5.1, Android >= @ref{f49,,build-time} API level 31


Added in version 3.9.

@end deffn

@geindex pthread_kill() (στη μονάδα signal)
@anchor{library/signal signal pthread_kill}@anchor{14dd}
@deffn {Συνάρτηση} 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{3ca5,,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{1141,,InterruptedError}.

Use @ref{1505,,threading.get_ident()} or the @ref{3390,,ident}
attribute of @ref{420,,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{1e65,,auditing event} @code{signal.pthread_kill} with arguments @code{thread_id}, @code{signalnum}.

@ref{232d,,Διαθεσιμότητα}: Unix.

See the man page @code{pthread_kill(3)@footnote{https://manpages.debian.org/pthread_kill(3)}} for further  information.

See also @ref{170c,,os.kill()}.


Added in version 3.3.

@end deffn

@geindex pthread_sigmask() (στη μονάδα signal)
@anchor{library/signal signal pthread_sigmask}@anchor{14dc}
@deffn {Συνάρτηση} 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{3ca7,,SIG_BLOCK}: The set of blocked signals is the union of the current
set and the `mask' argument.

@item 
@ref{3ca8,,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{3ca9,,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{4df,,signal.SIGINT},
@ref{1782,,signal.SIGTERM}@}). Use @ref{3cb9,,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{f16,,SIGKILL} and @ref{3cb3,,SIGSTOP} cannot be blocked.

@ref{232d,,Διαθεσιμότητα}: 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{3cc1,,pause()}, @ref{14de,,sigpending()} and @ref{14df,,sigwait()}.


Added in version 3.3.

@end deffn

@geindex setitimer() (στη μονάδα signal)
@anchor{library/signal signal setitimer}@anchor{3cbe}
@deffn {Συνάρτηση} signal.setitimer (which, seconds, interval=0)

Sets given interval timer (one of @ref{3cba,,signal.ITIMER_REAL},
@ref{3cbb,,signal.ITIMER_VIRTUAL} or @ref{3cbc,,signal.ITIMER_PROF}) specified
by `which' to fire after `seconds' (rounded up to microseconds, different from
@ref{3cc0,,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{3cba,,signal.ITIMER_REAL} will deliver @ref{3cae,,SIGALRM},
@ref{3cbb,,signal.ITIMER_VIRTUAL} sends @ref{3cb6,,SIGVTALRM},
and @ref{3cbc,,signal.ITIMER_PROF} will deliver @ref{3cb2,,SIGPROF}.

The old values are returned as a two-tuple of floats:
(@code{delay}, @code{interval}).

Attempting to pass an invalid interval timer will cause an
@ref{3cbd,,ItimerError}.

@ref{232d,,Διαθεσιμότητα}: Unix.


Άλλαξε στην έκδοση 3.15: Accepts any real numbers as `seconds' and `interval', not only integers
or floats.

@end deffn

@geindex getitimer() (στη μονάδα signal)
@anchor{library/signal signal getitimer}@anchor{3cbf}
@deffn {Συνάρτηση} signal.getitimer (which)

Returns current value of a given interval timer specified by `which'.

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex set_wakeup_fd() (στη μονάδα signal)
@anchor{library/signal signal set_wakeup_fd}@anchor{f2d}
@deffn {Συνάρτηση} signal.set_wakeup_fd (fd, *, warn_on_full_buffer=True)

Set the wakeup file descriptor to `fd'.  When a signal your program has
registered a signal handler for is received, the signal number is written as
a single byte into the fd.  If you haven’t registered a signal handler for
the signals you care about, then nothing will be written to the wakeup 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{3ca5,,the main thread of the main interpreter};
attempting to call it from other threads will cause a @ref{277,,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.


Άλλαξε στην έκδοση 3.5: On Windows, the function now also supports socket handles.



Άλλαξε στην έκδοση 3.7: Added @code{warn_on_full_buffer} parameter.

@end deffn

@geindex siginterrupt() (στη μονάδα signal)
@anchor{library/signal signal siginterrupt}@anchor{14e1}
@deffn {Συνάρτηση} signal.siginterrupt (signalnum, flag)

Change system call restart behaviour: if `flag' is @ref{ef5,,False}, system
calls will be restarted when interrupted by signal `signalnum', otherwise
system calls will be interrupted.  Returns nothing.

@ref{232d,,Διαθεσιμότητα}: 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{ce,,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() (στη μονάδα signal)
@anchor{library/signal signal signal}@anchor{14e0}
@deffn {Συνάρτηση} 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{1dab,,signal.SIG_IGN} or @ref{1dac,,signal.SIG_DFL}.  The previous
signal handler will be returned (see the description of @ref{1c2d,,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{3ca5,,the main thread of the main interpreter};
attempting to call it from other threads will cause a @ref{277,,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{acd,,description in the type hierarchy} or see the
attribute descriptions in the @ref{81,,inspect} module).

On Windows, @code{signal()} can only be called with @ref{142a,,SIGABRT},
@ref{1429,,SIGFPE}, @ref{142c,,SIGILL}, @ref{4df,,SIGINT}, @ref{1428,,SIGSEGV},
@ref{1782,,SIGTERM}, or @ref{3caf,,SIGBREAK}.
A @ref{277,,ValueError} will be raised in any other case.
Note that not all systems define the same set of signal names; an
@ref{1a9,,AttributeError} will be raised if a signal name is not defined as
@code{SIG*} module level constant.
@end deffn

@geindex sigpending() (στη μονάδα signal)
@anchor{library/signal signal sigpending}@anchor{14de}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Unix.

See the man page @code{sigpending(2)@footnote{https://manpages.debian.org/sigpending(2)}} for further information.

See also @ref{3cc1,,pause()}, @ref{14dc,,pthread_sigmask()} and @ref{14df,,sigwait()}.


Added in version 3.3.

@end deffn

@geindex sigwait() (στη μονάδα signal)
@anchor{library/signal signal sigwait}@anchor{14df}
@deffn {Συνάρτηση} 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{232d,,Διαθεσιμότητα}: Unix.

See the man page @code{sigwait(3)@footnote{https://manpages.debian.org/sigwait(3)}} for further information.

See also @ref{3cc1,,pause()}, @ref{14dc,,pthread_sigmask()}, @ref{14de,,sigpending()},
@ref{1164,,sigwaitinfo()} and @ref{1163,,sigtimedwait()}.


Added in version 3.3.

@end deffn

@geindex sigwaitinfo() (στη μονάδα signal)
@anchor{library/signal signal sigwaitinfo}@anchor{1164}
@deffn {Συνάρτηση} 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{1141,,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{232d,,Διαθεσιμότητα}: Unix.

See the man page @code{sigwaitinfo(2)@footnote{https://manpages.debian.org/sigwaitinfo(2)}} for further information.

See also @ref{3cc1,,pause()}, @ref{14df,,sigwait()} and @ref{1163,,sigtimedwait()}.


Added in version 3.3.



Άλλαξε στην έκδοση 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() (στη μονάδα signal)
@anchor{library/signal signal sigtimedwait}@anchor{1163}
@deffn {Συνάρτηση} signal.sigtimedwait (sigset, timeout)

Like @ref{1164,,sigwaitinfo()}, but takes an additional `timeout' argument
specifying a timeout. If `timeout' is specified as @code{0}, a poll is
performed. Returns @ref{a65,,None} if a timeout occurs.

@ref{232d,,Διαθεσιμότητα}: Unix.

See the man page @code{sigtimedwait(2)@footnote{https://manpages.debian.org/sigtimedwait(2)}} for further information.

See also @ref{3cc1,,pause()}, @ref{14df,,sigwait()} and @ref{1164,,sigwaitinfo()}.


Added in version 3.3.



Άλλαξε στην έκδοση 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).



Άλλαξε στην έκδοση 3.15: Accepts any real number as `timeout', not only integer or float.

@end deffn

@node Examples<19>,Note on SIGPIPE,Module contents<4>,signal — Set handlers for asynchronous events
@anchor{library/signal examples}@anchor{3cc2}@anchor{library/signal signal-example}@anchor{3cc3}
@subsubsection Examples


Here is a minimal example program. It uses the @ref{3cc0,,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{114b,,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<19>,signal — Set handlers for asynchronous events
@anchor{library/signal note-on-sigpipe}@anchor{3cc4}
@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{3ca1,,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{3ca1,,SIGPIPE}’s disposition to @ref{1dac,,SIG_DFL} in
order to avoid @ref{1404,,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{28e8}@anchor{library/signal note-on-signal-handlers-and-exceptions}@anchor{3cc5}
@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{6b3,,bytecode} instruction. Most
notably, a @ref{d96,,KeyboardInterrupt} may appear at any point during execution.
Most Python code, including the standard library, cannot be made robust against
this, and so a @code{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{d96,,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 @code{KeyboardInterrupt} as a means
of gracefully shutting down.  Instead, they should install their own
@ref{4df,,SIGINT} handler. Below is an example of an HTTP server that avoids
@code{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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node mmap — Memory-mapped file support,,signal — Set handlers for asynchronous events,Networking and Interprocess Communication
@anchor{library/mmap doc}@anchor{3cc6}@anchor{library/mmap mmap-memory-mapped-file-support}@anchor{3cc7}@anchor{library/mmap module-mmap}@anchor{94}@anchor{library/mmap translation-repo}@anchor{3cc8}
@subsection @code{mmap} — Memory-mapped file support


@geindex module; mmap


__________________________________________________________________


@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

Memory-mapped file objects behave like both @ref{1c6,,bytearray} and like
@ref{156c,,file objects}.  You can use mmap objects in most places
where @code{bytearray} are expected; for example, you can use the @ref{c1,,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{23c,,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{19b2,,fileno()} method to obtain the correct value for the
`fileno' parameter.  Otherwise, you can open the file using the
@ref{114b,,os.open()} function, which returns a file descriptor directly (the file
still needs to be closed when done).

@cartouche
@quotation Σημείωση 
If you want to create a memory-mapping for a writable, buffered file, you
should @ref{19fa,,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{291,,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.


Άλλαξε στην έκδοση 3.7: Added @code{ACCESS_DEFAULT} constant.


To map anonymous memory, -1 should be passed as the fileno along with the length.

@geindex mmap (κλάση σε mmap)
@anchor{library/mmap mmap mmap}@anchor{23c}
@deffn {Κλάση} mmap.mmap (fileno, length, tagname=None, access=ACCESS_DEFAULT, offset=0, *, trackfd=True)

`(Windows version)' Maps `length' bytes from the file specified by the
file descriptor `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}.

If `trackfd' is @code{False}, the file handle corresponding to `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{1a45,,size()} and @ref{3e9,,resize()}
methods will fail.
This mode is useful to limit the number of open file handles.
The original file can be renamed (but not deleted) after closing `fileno'.


Άλλαξε στην έκδοση 3.15: The `trackfd' parameter was added.


Raises an @ref{1e65,,auditing event} @code{mmap.__new__} with arguments @code{fileno}, @code{length}, @code{access}, @code{offset}.
@end deffn


@deffn {Κλάση} 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{23c,,mmap} is called.

`flags' specifies the nature of the mapping. @ref{3cc9,,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{3cca,,MAP_SHARED} creates a
mapping that’s shared with all other processes mapping the same areas of
the file.  The default value is @code{MAP_SHARED}. Some systems have
additional possible flags with the full list specified in
@ref{3ccb,,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{1a45,,size()} and @ref{3e9,,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.


Άλλαξε στην έκδοση 3.13: The `trackfd' parameter was added.


This example shows a simple way of using @ref{23c,,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{23c,,mmap} can also be used as a context manager in a @ref{20a,,with}
statement:

@example
import mmap

with mmap.mmap(-1, 13) as mm:
    mm.write(b"Hello world!")
@end example


Added in 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{1e65,,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() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap close}@anchor{3ccc}
@deffn {Μέθοδος} 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 (ιδιότητα της mmap.mmap)
@anchor{library/mmap mmap mmap closed}@anchor{3ccd}
@deffn {Ιδιότητα} closed

@code{True} if the file is closed.


Added in version 3.2.

@end deffn

@geindex find() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap find}@anchor{3cce}
@deffn {Μέθοδος} 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.


Άλλαξε στην έκδοση 3.5: Writable @ref{436,,bytes-like object} is now accepted.

@end deffn

@geindex flush() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap flush}@anchor{e5e}
@deffn {Μέθοδος} flush ([offset[, size]], *, flags=MS_SYNC)

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}.

The `flags' parameter specifies the synchronization behavior.
`flags' must be one of the @ref{3ccf,,MS_* constants} available
on the system.

On Windows, the `flags' parameter is ignored.

@code{None} is returned to indicate success.  An exception is raised when the
call failed.


Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.15: Allow specifying `offset' without `size'. Previously, both `offset'
and `size' parameters were required together. Now `offset' can be
specified alone, and the flush operation will extend from `offset'
to the end of the mmap.



Άλλαξε στην έκδοση 3.15: Added `flags' parameter to control synchronization behavior.

@end deffn

@geindex madvise() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap madvise}@anchor{dca}
@deffn {Μέθοδος} 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{3cd0,,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.


Added in version 3.8.

@end deffn

@geindex move() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap move}@anchor{3cd1}
@deffn {Μέθοδος} 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{291,,TypeError} exception.
@end deffn

@geindex read() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap read}@anchor{1489}
@deffn {Μέθοδος} read ([n])

Return a @ref{1c7,,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.


Άλλαξε στην έκδοση 3.3: Argument can be omitted or @code{None}.

@end deffn

@geindex read_byte() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap read_byte}@anchor{3cd2}
@deffn {Μέθοδος} read_byte ()

Returns a byte at the current file position as an integer, and advances
the file position by 1.
@end deffn

@geindex readline() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap readline}@anchor{3cd3}
@deffn {Μέθοδος} 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() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap resize}@anchor{3e9}
@deffn {Μέθοδος} 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{291,,TypeError} exception.
Resizing a map created with `trackfd' set to @code{False},
will raise a @ref{277,,ValueError} exception.

`On Windows': Resizing the map will raise an @ref{53c,,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.

Availability: Windows and systems with the @code{mremap()} system call.


Άλλαξε στην έκδοση 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() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap rfind}@anchor{3cd4}
@deffn {Μέθοδος} 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.


Άλλαξε στην έκδοση 3.5: Writable @ref{436,,bytes-like object} is now accepted.

@end deffn

@geindex seek() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap seek}@anchor{71e}
@deffn {Μέθοδος} 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).


Άλλαξε στην έκδοση 3.13: Return the new absolute position instead of @code{None}.

@end deffn

@geindex seekable() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap seekable}@anchor{71d}
@deffn {Μέθοδος} seekable ()

Return whether the file supports seeking, and the return value is always @code{True}.


Added in version 3.13.

@end deffn

@geindex set_name() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap set_name}@anchor{23d}
@deffn {Μέθοδος} set_name (name, /)

Annotate the memory mapping with the given `name' for easier identification
in @code{/proc/<pid>/maps} if the kernel supports the feature and @ref{178,,-X dev} is passed
to Python or if Python is built in @ref{3dc,,debug mode}.
The length of `name' must not exceed 67 bytes including the @code{'\0'} terminator.

@ref{232d,,Διαθεσιμότητα}: Linux >= 5.17 (kernel built with @code{CONFIG_ANON_VMA_NAME} option)


Added in version 3.15.

@end deffn

@geindex size() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap size}@anchor{1a45}
@deffn {Μέθοδος} size ()

Return the length of the file, which can be larger than the size of the
memory-mapped area.
For an anonymous mapping, return its size.


Άλλαξε στην έκδοση 3.15: Anonymous mappings are now supported on Unix.

@end deffn

@geindex tell() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap tell}@anchor{3cd5}
@deffn {Μέθοδος} tell ()

Returns the current position of the file pointer.
@end deffn

@geindex write() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap write}@anchor{10ff}
@deffn {Μέθοδος} 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{277,,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{291,,TypeError} exception.


Άλλαξε στην έκδοση 3.5: Writable @ref{436,,bytes-like object} is now accepted.



Άλλαξε στην έκδοση 3.6: The number of bytes written is now returned.

@end deffn

@geindex write_byte() (μέθοδος της mmap.mmap)
@anchor{library/mmap mmap mmap write_byte}@anchor{3cd6}
@deffn {Μέθοδος} 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{291,,TypeError} exception.
@end deffn
@end deffn

@menu
* MADV_* Constants:: 
* MAP_* Constants:: 
* MS_* Constants:: 

@end menu

@node MADV_* Constants,MAP_* Constants,,mmap — Memory-mapped file support
@anchor{library/mmap madv-constants}@anchor{3cd7}@anchor{library/mmap madvise-constants}@anchor{3cd0}
@subsubsection MADV_* Constants


@geindex MADV_NORMAL (στη μονάδα mmap)
@geindex MADV_RANDOM (στη μονάδα mmap)
@geindex MADV_SEQUENTIAL (στη μονάδα mmap)
@geindex MADV_WILLNEED (στη μονάδα mmap)
@geindex MADV_DONTNEED (στη μονάδα mmap)
@geindex MADV_REMOVE (στη μονάδα mmap)
@geindex MADV_DONTFORK (στη μονάδα mmap)
@geindex MADV_DOFORK (στη μονάδα mmap)
@geindex MADV_HWPOISON (στη μονάδα mmap)
@geindex MADV_MERGEABLE (στη μονάδα mmap)
@geindex MADV_UNMERGEABLE (στη μονάδα mmap)
@geindex MADV_SOFT_OFFLINE (στη μονάδα mmap)
@geindex MADV_HUGEPAGE (στη μονάδα mmap)
@geindex MADV_NOHUGEPAGE (στη μονάδα mmap)
@geindex MADV_DONTDUMP (στη μονάδα mmap)
@geindex MADV_DODUMP (στη μονάδα mmap)
@geindex MADV_FREE (στη μονάδα mmap)
@geindex MADV_NOSYNC (στη μονάδα mmap)
@geindex MADV_AUTOSYNC (στη μονάδα mmap)
@geindex MADV_NOCORE (στη μονάδα mmap)
@geindex MADV_CORE (στη μονάδα mmap)
@geindex MADV_PROTECT (στη μονάδα mmap)
@geindex MADV_FREE_REUSABLE (στη μονάδα mmap)
@geindex MADV_FREE_REUSE (στη μονάδα mmap)
@anchor{library/mmap mmap MADV_NORMAL}@anchor{3cd8}
@deffn {Δεδομένα} mmap.MADV_NORMAL
@anchor{library/mmap mmap MADV_RANDOM}@anchor{3cd9}
@deffnx {Δεδομένα} mmap.MADV_RANDOM
@anchor{library/mmap mmap MADV_SEQUENTIAL}@anchor{3cda}
@deffnx {Δεδομένα} mmap.MADV_SEQUENTIAL
@anchor{library/mmap mmap MADV_WILLNEED}@anchor{3cdb}
@deffnx {Δεδομένα} mmap.MADV_WILLNEED
@anchor{library/mmap mmap MADV_DONTNEED}@anchor{3cdc}
@deffnx {Δεδομένα} mmap.MADV_DONTNEED
@anchor{library/mmap mmap MADV_REMOVE}@anchor{3cdd}
@deffnx {Δεδομένα} mmap.MADV_REMOVE
@anchor{library/mmap mmap MADV_DONTFORK}@anchor{3cde}
@deffnx {Δεδομένα} mmap.MADV_DONTFORK
@anchor{library/mmap mmap MADV_DOFORK}@anchor{3cdf}
@deffnx {Δεδομένα} mmap.MADV_DOFORK
@anchor{library/mmap mmap MADV_HWPOISON}@anchor{3ce0}
@deffnx {Δεδομένα} mmap.MADV_HWPOISON
@anchor{library/mmap mmap MADV_MERGEABLE}@anchor{3ce1}
@deffnx {Δεδομένα} mmap.MADV_MERGEABLE
@anchor{library/mmap mmap MADV_UNMERGEABLE}@anchor{3ce2}
@deffnx {Δεδομένα} mmap.MADV_UNMERGEABLE
@anchor{library/mmap mmap MADV_SOFT_OFFLINE}@anchor{3ce3}
@deffnx {Δεδομένα} mmap.MADV_SOFT_OFFLINE
@anchor{library/mmap mmap MADV_HUGEPAGE}@anchor{3ce4}
@deffnx {Δεδομένα} mmap.MADV_HUGEPAGE
@anchor{library/mmap mmap MADV_NOHUGEPAGE}@anchor{3ce5}
@deffnx {Δεδομένα} mmap.MADV_NOHUGEPAGE
@anchor{library/mmap mmap MADV_DONTDUMP}@anchor{3ce6}
@deffnx {Δεδομένα} mmap.MADV_DONTDUMP
@anchor{library/mmap mmap MADV_DODUMP}@anchor{3ce7}
@deffnx {Δεδομένα} mmap.MADV_DODUMP
@anchor{library/mmap mmap MADV_FREE}@anchor{3ce8}
@deffnx {Δεδομένα} mmap.MADV_FREE
@anchor{library/mmap mmap MADV_NOSYNC}@anchor{3ce9}
@deffnx {Δεδομένα} mmap.MADV_NOSYNC
@anchor{library/mmap mmap MADV_AUTOSYNC}@anchor{3cea}
@deffnx {Δεδομένα} mmap.MADV_AUTOSYNC
@anchor{library/mmap mmap MADV_NOCORE}@anchor{3ceb}
@deffnx {Δεδομένα} mmap.MADV_NOCORE
@anchor{library/mmap mmap MADV_CORE}@anchor{3cec}
@deffnx {Δεδομένα} mmap.MADV_CORE
@anchor{library/mmap mmap MADV_PROTECT}@anchor{3ced}
@deffnx {Δεδομένα} mmap.MADV_PROTECT
@anchor{library/mmap mmap MADV_FREE_REUSABLE}@anchor{3cee}
@deffnx {Δεδομένα} mmap.MADV_FREE_REUSABLE
@anchor{library/mmap mmap MADV_FREE_REUSE}@anchor{3cef}
@deffnx {Δεδομένα} mmap.MADV_FREE_REUSE

These options can be passed to @ref{dca,,mmap.madvise()}.  Not every option will
be present on every system.

Availability: Systems with the madvise() system call.


Added in version 3.8.

@end deffn

@node MAP_* Constants,MS_* Constants,MADV_* Constants,mmap — Memory-mapped file support
@anchor{library/mmap id1}@anchor{3cf0}@anchor{library/mmap map-constants}@anchor{3ccb}
@subsubsection MAP_* Constants


@geindex MAP_SHARED (στη μονάδα mmap)
@geindex MAP_PRIVATE (στη μονάδα mmap)
@geindex MAP_32BIT (στη μονάδα mmap)
@geindex MAP_ALIGNED_SUPER (στη μονάδα mmap)
@geindex MAP_ANON (στη μονάδα mmap)
@geindex MAP_ANONYMOUS (στη μονάδα mmap)
@geindex MAP_CONCEAL (στη μονάδα mmap)
@geindex MAP_DENYWRITE (στη μονάδα mmap)
@geindex MAP_EXECUTABLE (στη μονάδα mmap)
@geindex MAP_HASSEMAPHORE (στη μονάδα mmap)
@geindex MAP_JIT (στη μονάδα mmap)
@geindex MAP_NOCACHE (στη μονάδα mmap)
@geindex MAP_NOEXTEND (στη μονάδα mmap)
@geindex MAP_NORESERVE (στη μονάδα mmap)
@geindex MAP_POPULATE (στη μονάδα mmap)
@geindex MAP_RESILIENT_CODESIGN (στη μονάδα mmap)
@geindex MAP_RESILIENT_MEDIA (στη μονάδα mmap)
@geindex MAP_STACK (στη μονάδα mmap)
@geindex MAP_TPRO (στη μονάδα mmap)
@geindex MAP_TRANSLATED_ALLOW_EXECUTE (στη μονάδα mmap)
@geindex MAP_UNIX03 (στη μονάδα mmap)
@anchor{library/mmap mmap MAP_SHARED}@anchor{3cca}
@deffn {Δεδομένα} mmap.MAP_SHARED
@anchor{library/mmap mmap MAP_PRIVATE}@anchor{3cc9}
@deffnx {Δεδομένα} mmap.MAP_PRIVATE
@anchor{library/mmap mmap MAP_32BIT}@anchor{1c24}
@deffnx {Δεδομένα} mmap.MAP_32BIT
@anchor{library/mmap mmap MAP_ALIGNED_SUPER}@anchor{1cc8}
@deffnx {Δεδομένα} mmap.MAP_ALIGNED_SUPER
@anchor{library/mmap mmap MAP_ANON}@anchor{3cf1}
@deffnx {Δεδομένα} mmap.MAP_ANON
@anchor{library/mmap mmap MAP_ANONYMOUS}@anchor{3cf2}
@deffnx {Δεδομένα} mmap.MAP_ANONYMOUS
@anchor{library/mmap mmap MAP_CONCEAL}@anchor{1cc9}
@deffnx {Δεδομένα} mmap.MAP_CONCEAL
@anchor{library/mmap mmap MAP_DENYWRITE}@anchor{3cf3}
@deffnx {Δεδομένα} mmap.MAP_DENYWRITE
@anchor{library/mmap mmap MAP_EXECUTABLE}@anchor{3cf4}
@deffnx {Δεδομένα} mmap.MAP_EXECUTABLE
@anchor{library/mmap mmap MAP_HASSEMAPHORE}@anchor{1c1f}
@deffnx {Δεδομένα} mmap.MAP_HASSEMAPHORE
@anchor{library/mmap mmap MAP_JIT}@anchor{1c21}
@deffnx {Δεδομένα} mmap.MAP_JIT
@anchor{library/mmap mmap MAP_NOCACHE}@anchor{1c20}
@deffnx {Δεδομένα} mmap.MAP_NOCACHE
@anchor{library/mmap mmap MAP_NOEXTEND}@anchor{1c1e}
@deffnx {Δεδομένα} mmap.MAP_NOEXTEND
@anchor{library/mmap mmap MAP_NORESERVE}@anchor{1c1d}
@deffnx {Δεδομένα} mmap.MAP_NORESERVE
@anchor{library/mmap mmap MAP_POPULATE}@anchor{1f23}
@deffnx {Δεδομένα} mmap.MAP_POPULATE
@anchor{library/mmap mmap MAP_RESILIENT_CODESIGN}@anchor{1c22}
@deffnx {Δεδομένα} mmap.MAP_RESILIENT_CODESIGN
@anchor{library/mmap mmap MAP_RESILIENT_MEDIA}@anchor{1c23}
@deffnx {Δεδομένα} mmap.MAP_RESILIENT_MEDIA
@anchor{library/mmap mmap MAP_STACK}@anchor{3cf5}
@deffnx {Δεδομένα} mmap.MAP_STACK
@anchor{library/mmap mmap MAP_TPRO}@anchor{1c27}
@deffnx {Δεδομένα} mmap.MAP_TPRO
@anchor{library/mmap mmap MAP_TRANSLATED_ALLOW_EXECUTE}@anchor{1c25}
@deffnx {Δεδομένα} mmap.MAP_TRANSLATED_ALLOW_EXECUTE
@anchor{library/mmap mmap MAP_UNIX03}@anchor{1c26}
@deffnx {Δεδομένα} mmap.MAP_UNIX03

These are the various flags that can be passed to @ref{23c,,mmap.mmap()}.  @code{MAP_ALIGNED_SUPER}
is only available at FreeBSD and @code{MAP_CONCEAL} is only available at OpenBSD.  Note
that some options might not be present on some systems.


Άλλαξε στην έκδοση 3.10: Added @code{MAP_POPULATE} constant.



Added in version 3.11: Added @code{MAP_STACK} constant.



Added in version 3.12: Added @code{MAP_ALIGNED_SUPER} and @code{MAP_CONCEAL} constants.



Added in version 3.13: Added @code{MAP_32BIT}, @code{MAP_HASSEMAPHORE}, @code{MAP_JIT},
@code{MAP_NOCACHE}, @code{MAP_NOEXTEND}, @code{MAP_NORESERVE},
@code{MAP_RESILIENT_CODESIGN}, @code{MAP_RESILIENT_MEDIA},
@code{MAP_TPRO}, @code{MAP_TRANSLATED_ALLOW_EXECUTE}, and
@code{MAP_UNIX03} constants.

@end deffn

@node MS_* Constants,,MAP_* Constants,mmap — Memory-mapped file support
@anchor{library/mmap id2}@anchor{3cf6}@anchor{library/mmap ms-constants}@anchor{3ccf}
@subsubsection MS_* Constants


@geindex MS_SYNC (στη μονάδα mmap)
@geindex MS_ASYNC (στη μονάδα mmap)
@geindex MS_INVALIDATE (στη μονάδα mmap)
@anchor{library/mmap mmap MS_SYNC}@anchor{3cf7}
@deffn {Δεδομένα} mmap.MS_SYNC
@anchor{library/mmap mmap MS_ASYNC}@anchor{3cf8}
@deffnx {Δεδομένα} mmap.MS_ASYNC
@anchor{library/mmap mmap MS_INVALIDATE}@anchor{3cf9}
@deffnx {Δεδομένα} mmap.MS_INVALIDATE

These flags control the synchronization behavior for @ref{e5e,,mmap.flush()}:


@itemize *

@item 
@code{MS_SYNC} - Synchronous flush: writes are scheduled and the call
blocks until they are physically written to storage.

@item 
@code{MS_ASYNC} - Asynchronous flush: writes are scheduled but the call
returns immediately without waiting for completion.

@item 
@code{MS_INVALIDATE} - Invalidate cached data: invalidates other mappings
of the same file so they can see the changes.
@end itemize


Added in version 3.15.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Internet Data Handling,Structured Markup Processing Tools,Networking and Interprocess Communication,The Python Standard Library
@anchor{library/netdata doc}@anchor{3cfa}@anchor{library/netdata internet-data-handling}@anchor{3cfb}@anchor{library/netdata netdata}@anchor{3cfc}@anchor{library/netdata translation-repo}@anchor{3cfd}
@section Internet Data Handling


This chapter describes modules which support handling data formats commonly used
on the internet.

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

@end menu

@node email — An email and MIME handling package,json — JSON encoder and decoder,,Internet Data Handling
@anchor{library/email doc}@anchor{3cfe}@anchor{library/email email-an-email-and-mime-handling-package}@anchor{3cff}@anchor{library/email module-email}@anchor{3e}
@subsection @code{email} — An email and MIME handling package


@geindex module; email

`Source code:' Lib/email/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/email/__init__.py}


__________________________________________________________________


The @code{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{d2,,smtplib}.  The @code{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}.

The overall structure of the email package can be divided into three major
components, plus a fourth component that controls the behavior of the other
components.

The central component of the package is an «object model» that represents email
messages.  An application interacts with the package primarily through the
object model interface defined in the @ref{47,,message} sub-module.  The
application can use this API to ask questions about an existing email, to
construct a new email, or to add or remove email subcomponents that themselves
use the same object model interface.  That is, following the nature of email
messages and their MIME subcomponents, the email object model is a tree
structure of objects that all provide the @ref{216,,EmailMessage}
API.

The other two major components of the package are the @ref{51,,parser} and
the @ref{43,,generator}.  The parser takes the serialized version of an
email message (a stream of bytes) and converts it into a tree of
@ref{216,,EmailMessage} objects.  The generator takes an
@code{EmailMessage} and turns it back into a serialized byte
stream.  (The parser and generator also handle streams of text characters, but
this usage is discouraged as it is too easy to end up with messages that are
not valid in one way or another.)

The control component is the @ref{52,,policy} module.  Every
@ref{216,,EmailMessage}, every @ref{43,,generator}, and every
@ref{51,,parser} has an associated @code{policy} object that
controls its behavior.  Usually an application only needs to specify the policy
when an @code{EmailMessage} is created, either by directly
instantiating an @code{EmailMessage}  to create a new email,
or by parsing an input stream using a @code{parser}.  But the policy can
be changed when the message is serialized using a @code{generator}.
This allows, for example, a generic email message to be parsed from disk, but
to serialize it using standard SMTP settings when sending it to an email
server.

The email package does its best to hide the details of the various governing
RFCs from the application.  Conceptually the application should be able to
treat the email message as a structured tree of unicode text and binary
attachments, without having to worry about how these are represented when
serialized.  In practice, however, it is often necessary to be aware of at
least some of the rules governing MIME messages and their structure,
specifically the names and nature of the MIME «content types» and how they
identify multipart documents.  For the most part this knowledge should only be
required for more complex applications, and even then it should only be the
high level structure in question, and not the details of how those structures
are represented.  Since MIME content types are used widely in modern internet
software (not just email), this will be a familiar concept to many programmers.

The following sections describe the functionality of the @code{email} package.
We start with the @ref{47,,message} object model, which is the primary
interface an application will use, and follow that with the
@ref{51,,parser} and @ref{43,,generator} components.  Then we cover the
@ref{52,,policy} controls, which completes the treatment of the main
components of the library.

The next three sections cover the exceptions the package may raise and the
defects (non-compliance with the RFCs) that the @ref{51,,parser} may
detect.  Then we cover the @ref{45,,headerregistry} and the
@ref{40,,contentmanager} sub-components, which provide tools for doing more
detailed manipulation of headers and payloads, respectively.  Both of these
components contain features relevant to consuming and producing non-trivial
messages, but also document their extensibility APIs, which will be of interest
to advanced applications.

Following those is a set of examples of using the fundamental parts of the APIs
covered in the preceding sections.

The foregoing represent the modern (unicode friendly) API of the email package.
The remaining sections, starting with the @ref{780,,Message}
class, cover the legacy @ref{105a,,compat32} API that deals much more
directly with the details of how email messages are represented.  The
@code{compat32} API does `not' hide the details of the RFCs from
the application, but for applications that need to operate at that level, they
can be useful tools.  This documentation is also relevant for applications that
are still using the @ref{105a,,compat32} API for backward
compatibility reasons.


Άλλαξε στην έκδοση 3.6: Docs reorganized and rewritten to promote the new
@ref{216,,EmailMessage}/@ref{1464,,EmailPolicy}
API.


Contents of the @code{email} package documentation:

@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; Κλάσεις Εξαιρέσεων και Ελαττωμάτων: email errors Κλάσεις Εξαιρέσεων και Ελαττωμάτων. 
* email.headerregistry; Custom Header Objects: email headerregistry Custom Header Objects. 
* email.contentmanager; Managing MIME Content: email contentmanager Managing MIME Content. 
* email; Examples: email Examples. 
* email.message.Message; Representing an email message using the compat32 API: email message Message Representing an email message using the compat32 API. 
* 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; Αναπαράσταση συνόλων χαρακτήρων: email charset Αναπαράσταση συνόλων χαρακτήρων. 
* 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{3d00}@anchor{library/email message email-message-representing-an-email-message}@anchor{3d01}@anchor{library/email message module-email message}@anchor{47}
@subsubsection @code{email.message}: Representing an email message


@geindex module; email.message

`Source code:' Lib/email/message.py@footnote{https://github.com/python/cpython/tree/main/Lib/email/message.py}


__________________________________________________________________



Added in version 3.6: @footnote{
Originally added in 3.4 as a @ref{13ea,,provisional module}.  Docs for legacy message class moved to
@ref{3d02,,email.message.Message; Representing an email message using the compat32 API}.
}


The central class in the @ref{3e,,email} package is the @ref{216,,EmailMessage}
class, imported from the @code{email.message} module.  It is the base class for
the @code{email} object model.  @code{EmailMessage} provides the core
functionality for setting and querying header fields, for accessing message
bodies, and for creating or modifying structured messages.

An email message consists of `headers' and a `payload' (which is also referred
to as the `content').  Headers are 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} or 
@geindex RFC; RFC 6532
RFC 6532@footnote{https://datatracker.ietf.org/doc/html/rfc6532.html} style field names
and values, where the field name and value are separated by a colon.  The colon
is not part of either the field name or the field value.  The payload may be a
simple text message, or a binary object, or a structured sequence of
sub-messages each with their own set of headers and their own payload.  The
latter type of payload is indicated by the message having a MIME type such as
@code{multipart/*} or @code{message/rfc822}.

The conceptual model provided by an @ref{216,,EmailMessage} object is that of an
ordered dictionary of headers coupled with a `payload' that represents the
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} body of the message, which might be a list of sub-@code{EmailMessage}
objects.  In addition to the normal dictionary methods for accessing the header
names and values, there are methods for accessing specialized information from
the headers (for example the MIME content type), for operating on the payload,
for generating a serialized version of the message, and for recursively walking
over the object tree.

The @ref{216,,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.

The `payload' is either a string or bytes object, in the case of simple message
objects, or a list of @ref{216,,EmailMessage} objects, for MIME container
documents such as @code{multipart/*} and @code{message/rfc822}
message objects.

@geindex EmailMessage (κλάση σε email.message)
@anchor{library/email message email message EmailMessage}@anchor{216}
@deffn {Κλάση} email.message.EmailMessage (policy=default)

If `policy' is specified use the rules it specifies to update and serialize
the representation of the message.  If `policy' is not set, use the
@ref{19ac,,default} policy, which follows the rules of the email
RFCs except for line endings (instead of the RFC mandated @code{\r\n}, it uses
the Python standard @code{\n} line endings).  For more information see the
@ref{52,,policy} documentation. @footnote{
The @ref{216,,EmailMessage} class requires a policy that provides a
@code{content_manager} attribute for content management methods like
@code{set_content()} and @code{get_content()} to work. The legacy
@ref{105a,,compat32} policy does not support these methods
and should not be used with @code{EmailMessage}.
}

@geindex as_string() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage as_string}@anchor{3d03}
@deffn {Μέθοδος} 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{780,,Message} class `maxheaderlen' is
accepted, but defaults to @code{None}, which means that by default the line
length is controlled by the
@ref{3d04,,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{1577,,Generator}.

Flattening the message may trigger changes to the @code{EmailMessage}
if defaults need to be filled in to complete the transformation to a
string (for example, MIME boundaries may be generated or modified).

Note that this method is provided as a convenience and may not be the
most useful way to serialize messages in your application, especially if
you are dealing with multiple messages.  See
@ref{1577,,email.generator.Generator} for a more flexible API for
serializing messages.  Note also that this method is restricted to
producing messages serialized as «7 bit clean» when
@ref{217,,utf8} is @code{False}, which is the default.


Άλλαξε στην έκδοση 3.6: the default behavior when `maxheaderlen'
is not specified was changed from defaulting to 0 to defaulting
to the value of `max_line_length' from the policy.

@end deffn

@geindex __str__() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __str__}@anchor{3d05}
@deffn {Μέθοδος} __str__ ()

Equivalent to @code{as_string(policy=self.policy.clone(utf8=True))}.  Allows
@code{str(msg)} to produce a string containing the serialized message in a
readable format.


Άλλαξε στην έκδοση 3.4: the method was changed to use @code{utf8=True},
thus producing an 
@geindex RFC; RFC 6531
RFC 6531@footnote{https://datatracker.ietf.org/doc/html/rfc6531.html}-like message representation, instead of
being a direct alias for @ref{3d03,,as_string()}.

@end deffn

@geindex as_bytes() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage as_bytes}@anchor{3d06}
@deffn {Μέθοδος} as_bytes (unixfrom=False, policy=None)

Return the entire message flattened as a bytes object.  When optional
`unixfrom' is true, the envelope header is included in the returned
string.  `unixfrom' defaults to @code{False}.  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{1578,,BytesGenerator}.

Flattening the message may trigger changes to the @code{EmailMessage}
if defaults need to be filled in to complete the transformation to a
string (for example, MIME boundaries may be generated or modified).

Note that this method is provided as a convenience and may not be the
most useful way to serialize messages in your application, especially if
you are dealing with multiple messages.  See
@ref{1578,,email.generator.BytesGenerator} for a more flexible API for
serializing messages.
@end deffn

@geindex __bytes__() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __bytes__}@anchor{3d07}
@deffn {Μέθοδος} __bytes__ ()

Equivalent to @ref{3d06,,as_bytes()}.  Allows @code{bytes(msg)} to produce a
bytes object containing the serialized message.
@end deffn

@geindex is_multipart() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage is_multipart}@anchor{3d08}
@deffn {Μέθοδος} is_multipart ()

Return @code{True} if the message’s payload is a list of
sub-@code{EmailMessage} objects, otherwise return @code{False}.  When
@code{is_multipart()} returns @code{False}, the payload should be a string
object (which might be a CTE encoded binary payload).  Note that
@code{is_multipart()} returning @code{True} does not necessarily mean that
«msg.get_content_maintype() == “multipart”» will return the @code{True}.
For example, @code{is_multipart} will return @code{True} when the
@code{EmailMessage} is of type @code{message/rfc822}.
@end deffn

@geindex set_unixfrom() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage set_unixfrom}@anchor{3d09}
@deffn {Μέθοδος} set_unixfrom (unixfrom)

Set the message’s envelope header to `unixfrom', which should be a
string.  (See @ref{3d0a,,mboxMessage} for a brief description of
this header.)
@end deffn

@geindex get_unixfrom() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_unixfrom}@anchor{3d0b}
@deffn {Μέθοδος} get_unixfrom ()

Return the message’s envelope header.  Defaults to @code{None} if the
envelope header was never set.
@end deffn

The following methods implement the mapping-like interface for accessing the
message’s headers.  Note that there are some semantic differences
between these methods and a normal mapping (i.e. dictionary) interface.  For
example, in a dictionary there are no duplicate keys, but here there may be
duplicate message headers.  Also, in dictionaries there is no guaranteed
order to the keys returned by @ref{3d0c,,keys()}, but in an @code{EmailMessage}
object, headers are always returned in the order they appeared in the
original message, or in which they were added to the message later.  Any
header deleted and then re-added is always appended to the end of the
header list.

These semantic differences are intentional and are biased toward
convenience in the most common use cases.

Note that in all cases, any envelope header present in the message is not
included in the mapping interface.

@geindex __len__() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __len__}@anchor{3d0d}
@deffn {Μέθοδος} __len__ ()

Return the total number of headers, including duplicates.
@end deffn

@geindex __contains__() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __contains__}@anchor{3d0e}
@deffn {Μέθοδος} __contains__ (name)

Return @code{True} if the message object has a field named `name'. Matching is
done without regard to case and `name' does not include the trailing
colon.  Used for the @code{in} operator.  For example:

@example
if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])
@end example
@end deffn

@geindex __getitem__() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __getitem__}@anchor{3d0f}
@deffn {Μέθοδος} __getitem__ (name)

Return the value of the named header field.  `name' does not include the
colon field separator.  If the header is missing, @code{None} is returned; a
@ref{7df,,KeyError} is never raised.

Note that if the named field appears more than once in the message’s
headers, exactly which of those field values will be returned is
undefined.  Use the @ref{3d10,,get_all()} method to get the values of all the
extant headers named `name'.

Using the standard (non-@code{compat32}) policies, the returned value is an
instance of a subclass of @ref{3d11,,email.headerregistry.BaseHeader}.
@end deffn

@geindex __setitem__() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __setitem__}@anchor{3d12}
@deffn {Μέθοδος} __setitem__ (name, val)

Add a header to the message with field name `name' and value `val'.  The
field is appended to the end of the message’s existing headers.

Note that this does `not' overwrite or delete any existing header with the same
name.  If you want to ensure that the new header is the only one present in the
message with field name `name', delete the field first, e.g.:

@example
del msg['subject']
msg['subject'] = 'Python roolz!'
@end example

If the @ref{52,,policy} defines certain headers to be unique (as the standard
policies do), this method may raise a @ref{277,,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__() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __delitem__}@anchor{3d13}
@deffn {Μέθοδος} __delitem__ (name)

Delete all occurrences of the field with name `name' from the message’s
headers.  No exception is raised if the named field isn’t present in the
headers.
@end deffn

@geindex keys() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage keys}@anchor{3d0c}
@deffn {Μέθοδος} keys ()

Return a list of all the message’s header field names.
@end deffn

@geindex values() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage values}@anchor{3d14}
@deffn {Μέθοδος} values ()

Return a list of all the message’s field values.
@end deffn

@geindex items() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage items}@anchor{3d15}
@deffn {Μέθοδος} items ()

Return a list of 2-tuples containing all the message’s field headers and
values.
@end deffn

@geindex get() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get}@anchor{3d16}
@deffn {Μέθοδος} get (name, failobj=None)

Return the value of the named header field.  This is identical to
@ref{787,,__getitem__()} except that optional `failobj' is returned if the
named header is missing (`failobj' defaults to @code{None}).
@end deffn

Here are some additional useful header related methods:

@geindex get_all() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_all}@anchor{3d10}
@deffn {Μέθοδος} get_all (name, failobj=None)

Return a list of all the values for the field named `name'. If there are
no such named headers in the message, `failobj' is returned (defaults to
@code{None}).
@end deffn

@geindex add_header() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage add_header}@anchor{3d17}
@deffn {Μέθοδος} add_header (_name, _value, **_params)

Extended header setting.  This method is similar to @ref{3d12,,__setitem__()}
except that additional header parameters can be provided as keyword
arguments.  `_name' is the header field to add and `_value' is the
`primary' value for the header.

For each item in the keyword argument dictionary `_params', the key is
taken as the parameter name, with underscores converted to dashes (since
dashes are illegal in Python identifiers).  Normally, the parameter will
be added as @code{key="value"} unless the value is @code{None}, in which case
only the key will be added.

If the value contains non-ASCII characters, the charset and language may
be explicitly controlled by specifying the value as a three tuple in the
format @code{(CHARSET, LANGUAGE, VALUE)}, where @code{CHARSET} is a string
naming the charset to be used to encode the value, @code{LANGUAGE} can
usually be set to @code{None} or the empty string (see 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} for other
possibilities), and @code{VALUE} is the string value containing non-ASCII
code points.  If a three tuple is not passed and the value contains
non-ASCII characters, it is automatically encoded in 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} format
using a @code{CHARSET} of @code{utf-8} and a @code{LANGUAGE} of @code{None}.

Here is an example:

@example
msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
@end example

This will add a header that looks like

@example
Content-Disposition: attachment; filename="bud.gif"
@end example

An example of the extended interface with non-ASCII characters:

@example
msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '@w{'}, 'Fußballer.ppt'))
@end example
@end deffn

@geindex replace_header() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage replace_header}@anchor{3d18}
@deffn {Μέθοδος} replace_header (_name, _value)

Replace a header.  Replace the first header found in the message that
matches `_name', retaining header order and field name case of the
original header.  If no matching header is found, raise a
@ref{7df,,KeyError}.
@end deffn

@geindex get_content_type() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_content_type}@anchor{3d19}
@deffn {Μέθοδος} get_content_type ()

Return the message’s content type, coerced to lower case of the form
@code{maintype/subtype}.  If there is no @code{Content-Type}
header in the message return the value returned by
@ref{3d1a,,get_default_type()}.  If the @code{Content-Type} header is
invalid, return @code{text/plain}.

(According to 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}, messages always have a default type,
@code{get_content_type()} will always return a value.  
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} defines
a message’s default type to be @code{text/plain} unless it appears
inside a @code{multipart/digest} container, in which case it would
be @code{message/rfc822}.  If the @code{Content-Type} header
has an invalid type specification, 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} mandates that the default
type be @code{text/plain}.)
@end deffn

@geindex get_content_maintype() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_content_maintype}@anchor{3d1b}
@deffn {Μέθοδος} get_content_maintype ()

Return the message’s main content type.  This is the @code{maintype}
part of the string returned by @ref{3d19,,get_content_type()}.
@end deffn

@geindex get_content_subtype() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_content_subtype}@anchor{3d1c}
@deffn {Μέθοδος} get_content_subtype ()

Return the message’s sub-content type.  This is the @code{subtype}
part of the string returned by @ref{3d19,,get_content_type()}.
@end deffn

@geindex get_default_type() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_default_type}@anchor{3d1a}
@deffn {Μέθοδος} get_default_type ()

Return the default content type.  Most messages have a default content
type of @code{text/plain}, except for messages that are subparts of
@code{multipart/digest} containers.  Such subparts have a default
content type of @code{message/rfc822}.
@end deffn

@geindex set_default_type() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage set_default_type}@anchor{3d1d}
@deffn {Μέθοδος} set_default_type (ctype)

Set the default content type.  `ctype' should either be
@code{text/plain} or @code{message/rfc822}, although this is
not enforced.  The default content type is not stored in the
@code{Content-Type} header, so it only affects the return value of
the @code{get_content_type} methods when no @code{Content-Type}
header is present in the message.
@end deffn

@geindex set_param() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage set_param}@anchor{3d1e}
@deffn {Μέθοδος} set_param (param, value, header='Content-Type', requote=True, charset=None, language='@w{'}, replace=False)

Set a parameter in the @code{Content-Type} header.  If the
parameter already exists in the header, replace its value with `value'.
When `header' is @code{Content-Type} (the default) and the header does not
yet exist in the message, add it, set its value to
@code{text/plain}, and append the new parameter value.  Optional
`header' specifies an alternative header to @code{Content-Type}.

If the value contains non-ASCII characters, the charset and language may
be explicitly specified using the optional `charset' and `language'
parameters.  Optional `language' specifies the 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} language,
defaulting to the empty string.  Both `charset' and `language' should be
strings.  The default is to use the @code{utf8} `charset' and @code{None} for
the `language'.

If `replace' is @code{False} (the default) the header is moved to the
end of the list of headers.  If `replace' is @code{True}, the header
will be updated in place.

Use of the `requote' parameter with @code{EmailMessage} objects is
deprecated.

Note that existing parameter values of headers may be accessed through
the @ref{3d1f,,params} attribute of the
header value (for example, @code{msg['Content-Type'].params['charset']}).


Άλλαξε στην έκδοση 3.4: @code{replace} keyword was added.

@end deffn

@geindex del_param() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage del_param}@anchor{3d20}
@deffn {Μέθοδος} del_param (param, header='content-type', requote=True)

Remove the given parameter completely from the @code{Content-Type}
header.  The header will be re-written in place without the parameter or
its value.  Optional `header' specifies an alternative to
@code{Content-Type}.

Use of the `requote' parameter with @code{EmailMessage} objects is
deprecated.
@end deffn

@geindex get_filename() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_filename}@anchor{3d21}
@deffn {Μέθοδος} get_filename (failobj=None)

Return the value of the @code{filename} parameter of the
@code{Content-Disposition} header of the message.  If the header
does not have a @code{filename} parameter, this method falls back to looking
for the @code{name} parameter on the @code{Content-Type} header.  If
neither is found, or the header is missing, then `failobj' is returned.
The returned string will always be unquoted as per
@ref{3d22,,email.utils.unquote()}.
@end deffn

@geindex get_boundary() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_boundary}@anchor{3d23}
@deffn {Μέθοδος} get_boundary (failobj=None)

Return the value of the @code{boundary} parameter of the
@code{Content-Type} header of the message, or `failobj' if either
the header is missing, or has no @code{boundary} parameter.  The returned
string will always be unquoted as per @ref{3d22,,email.utils.unquote()}.
@end deffn

@geindex set_boundary() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage set_boundary}@anchor{3d24}
@deffn {Μέθοδος} set_boundary (boundary)

Set the @code{boundary} parameter of the @code{Content-Type} header to
`boundary'.  @code{set_boundary()} will always quote `boundary' if
necessary.  A @ref{3d25,,HeaderParseError} is raised if the
message object has no @code{Content-Type} header.

Note that using this method is subtly different from deleting the old
@code{Content-Type} header and adding a new one with the new
boundary via @ref{3d17,,add_header()}, because @code{set_boundary()} preserves
the order of the @code{Content-Type} header in the list of
headers.
@end deffn

@geindex get_content_charset() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_content_charset}@anchor{3d26}
@deffn {Μέθοδος} get_content_charset (failobj=None)

Return the @code{charset} parameter of the @code{Content-Type} header,
coerced to lower case.  If there is no @code{Content-Type} header, or if
that header has no @code{charset} parameter, `failobj' is returned.
@end deffn

@geindex get_charsets() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_charsets}@anchor{3d27}
@deffn {Μέθοδος} get_charsets (failobj=None)

Return a list containing the character set names in the message.  If the
message is a @code{multipart}, then the list will contain one element
for each subpart in the payload, otherwise, it will be a list of length 1.

Each item in the list will be a string which is the value of the
@code{charset} parameter in the @code{Content-Type} header for the
represented subpart.  If the subpart has no @code{Content-Type}
header, no @code{charset} parameter, or is not of the @code{text} main
MIME type, then that item in the returned list will be `failobj'.
@end deffn

@geindex is_attachment() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage is_attachment}@anchor{3d28}
@deffn {Μέθοδος} is_attachment ()

Return @code{True} if there is a @code{Content-Disposition} header
and its (case insensitive) value is @code{attachment}, @code{False} otherwise.


Άλλαξε στην έκδοση 3.4.2: is_attachment is now a method instead of a property, for consistency
with @ref{3d29,,is_multipart()}.

@end deffn

@geindex get_content_disposition() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_content_disposition}@anchor{3d2a}
@deffn {Μέθοδος} get_content_disposition ()

Return the lowercased value (without parameters) of the message’s
@code{Content-Disposition} header if it has one, or @code{None}.  The
possible values for this method are `inline', `attachment' or @code{None}
if the message follows 
@geindex RFC; RFC 2183
RFC 2183@footnote{https://datatracker.ietf.org/doc/html/rfc2183.html}.


Added in version 3.5.

@end deffn

The following methods relate to interrogating and manipulating the content
(payload) of the message.

@geindex walk() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage walk}@anchor{3d2b}
@deffn {Μέθοδος} walk ()

The @code{walk()} method is an all-purpose generator which can be used to
iterate over all the parts and subparts of a message object tree, in
depth-first traversal order.  You will typically use @code{walk()} as the
iterator in a @code{for} loop; each iteration returns the next subpart.

Here’s an example that prints the MIME type of every part of a multipart
message structure:

@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} iterates over the subparts of any part where
@ref{3d08,,is_multipart()} returns @code{True}, even though
@code{msg.get_content_maintype() == 'multipart'} may return @code{False}.  We
can see this in our example by making use of the @code{_structure} debug
helper function:

@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

Here the @code{message} parts are not @code{multiparts}, but they do contain
subparts. @code{is_multipart()} returns @code{True} and @code{walk} descends
into the subparts.
@end deffn

@geindex get_body() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_body}@anchor{3d2c}
@deffn {Μέθοδος} get_body (preferencelist=('related', 'html', 'plain'))

Return the MIME part that is the best candidate to be the «body» of the
message.

`preferencelist' must be a sequence of strings from the set @code{related},
@code{html}, and @code{plain}, and indicates the order of preference for the
content type of the part returned.

Start looking for candidate matches with the object on which the
@code{get_body} method is called.

If @code{related} is not included in `preferencelist', consider the root
part (or subpart of the root part) of any related encountered as a
candidate if the (sub-)part matches a preference.

When encountering a @code{multipart/related}, check the @code{start} parameter
and if a part with a matching @code{Content-ID} is found, consider
only it when looking for candidate matches.  Otherwise consider only the
first (default root) part of the @code{multipart/related}.

If a part has a @code{Content-Disposition} header, only consider
the part a candidate match if the value of the header is @code{inline}.

If none of the candidates matches any of the preferences in
`preferencelist', return @code{None}.

Notes: (1) For most applications the only `preferencelist' combinations
that really make sense are @code{('plain',)}, @code{('html', 'plain')}, and the
default @code{('related', 'html', 'plain')}.  (2) Because matching starts
with the object on which @code{get_body} is called, calling @code{get_body} on
a @code{multipart/related} will return the object itself unless
`preferencelist' has a non-default value. (3) Messages (or message parts)
that do not specify a @code{Content-Type} or whose
@code{Content-Type} header is invalid will be treated as if they
are of type @code{text/plain}, which may occasionally cause @code{get_body} to
return unexpected results.
@end deffn

@geindex iter_attachments() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage iter_attachments}@anchor{3d2d}
@deffn {Μέθοδος} iter_attachments ()

Return an iterator over all of the immediate sub-parts of the message
that are not candidate «body» parts.  That is, skip the first occurrence
of each of @code{text/plain}, @code{text/html}, @code{multipart/related}, or
@code{multipart/alternative} (unless they are explicitly marked as
attachments via @code{Content-Disposition: attachment}), and
return all remaining parts.  When applied directly to a
@code{multipart/related}, return an iterator over the all the related parts
except the root part (ie: the part pointed to by the @code{start} parameter,
or the first part if there is no @code{start} parameter or the @code{start}
parameter doesn’t match the @code{Content-ID} of any of the
parts).  When applied directly to a @code{multipart/alternative} or a
non-@code{multipart}, return an empty iterator.
@end deffn

@geindex iter_parts() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage iter_parts}@anchor{3d2e}
@deffn {Μέθοδος} iter_parts ()

Return an iterator over all of the immediate sub-parts of the message,
which will be empty for a non-@code{multipart}.  (See also
@ref{3d2b,,walk()}.)
@end deffn

@geindex get_content() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_content}@anchor{3d2f}
@deffn {Μέθοδος} get_content (*args, content_manager=None, **kw)

Call the @ref{3d30,,get_content()} method
of the `content_manager', passing self as the message object, and passing
along any other arguments or keywords as additional arguments.  If
`content_manager' is not specified, use the @code{content_manager} specified
by the current @ref{52,,policy}.
@end deffn

@geindex set_content() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage set_content}@anchor{1e54}
@deffn {Μέθοδος} set_content (*args, content_manager=None, **kw)

Call the @ref{3d31,,set_content()} method
of the `content_manager', passing self as the message object, and passing
along any other arguments or keywords as additional arguments.  If
`content_manager' is not specified, use the @code{content_manager} specified
by the current @ref{52,,policy}.
@end deffn

@geindex make_related() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage make_related}@anchor{3d32}
@deffn {Μέθοδος} make_related (boundary=None)

Convert a non-@code{multipart} message into a @code{multipart/related} message,
moving any existing @code{Content-} headers and payload into a
(new) first part of the @code{multipart}.  If `boundary' is specified, use
it as the boundary string in the multipart, otherwise leave the boundary
to be automatically created when it is needed (for example, when the
message is serialized).
@end deffn

@geindex make_alternative() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage make_alternative}@anchor{3d33}
@deffn {Μέθοδος} make_alternative (boundary=None)

Convert a non-@code{multipart} or a @code{multipart/related} into a
@code{multipart/alternative}, moving any existing @code{Content-}
headers and payload into a (new) first part of the @code{multipart}.  If
`boundary' is specified, use it as the boundary string in the multipart,
otherwise leave the boundary to be automatically created when it is
needed (for example, when the message is serialized).
@end deffn

@geindex make_mixed() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage make_mixed}@anchor{3d34}
@deffn {Μέθοδος} make_mixed (boundary=None)

Convert a non-@code{multipart}, a @code{multipart/related}, or a
@code{multipart-alternative} into a @code{multipart/mixed}, moving any existing
@code{Content-} headers and payload into a (new) first part of the
@code{multipart}.  If `boundary' is specified, use it as the boundary string
in the multipart, otherwise leave the boundary to be automatically
created when it is needed (for example, when the message is serialized).
@end deffn

@geindex add_related() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage add_related}@anchor{3d35}
@deffn {Μέθοδος} add_related (*args, content_manager=None, **kw)

If the message is a @code{multipart/related}, create a new message
object, pass all of the arguments to its @ref{1e54,,set_content()} method,
and @ref{3d36,,attach()} it to the @code{multipart}.  If
the message is a non-@code{multipart}, call @ref{3d32,,make_related()} and then
proceed as above.  If the message is any other type of @code{multipart},
raise a @ref{291,,TypeError}. If `content_manager' is not specified, use
the @code{content_manager} specified by the current @ref{52,,policy}.
If the added part has no @code{Content-Disposition} header,
add one with the value @code{inline}.
@end deffn

@geindex add_alternative() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage add_alternative}@anchor{3d37}
@deffn {Μέθοδος} add_alternative (*args, content_manager=None, **kw)

If the message is a @code{multipart/alternative}, create a new message
object, pass all of the arguments to its @ref{1e54,,set_content()} method, and
@ref{3d36,,attach()} it to the @code{multipart}.  If the
message is a non-@code{multipart} or @code{multipart/related}, call
@ref{3d33,,make_alternative()} and then proceed as above.  If the message is
any other type of @code{multipart}, raise a @ref{291,,TypeError}. If
`content_manager' is not specified, use the @code{content_manager} specified
by the current @ref{52,,policy}.
@end deffn

@geindex add_attachment() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage add_attachment}@anchor{3d38}
@deffn {Μέθοδος} add_attachment (*args, content_manager=None, **kw)

If the message is a @code{multipart/mixed}, create a new message object,
pass all of the arguments to its @ref{1e54,,set_content()} method, and
@ref{3d36,,attach()} it to the @code{multipart}.  If the
message is a non-@code{multipart}, @code{multipart/related}, or
@code{multipart/alternative}, call @ref{3d34,,make_mixed()} and then proceed as
above. If `content_manager' is not specified, use the @code{content_manager}
specified by the current @ref{52,,policy}.  If the added part
has no @code{Content-Disposition} header, add one with the value
@code{attachment}.  This method can be used both for explicit attachments
(@code{Content-Disposition: attachment}) and @code{inline} attachments
(@code{Content-Disposition: inline}), by passing appropriate
options to the @code{content_manager}.
@end deffn

@geindex clear() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage clear}@anchor{3d39}
@deffn {Μέθοδος} clear ()

Remove the payload and all of the headers.
@end deffn

@geindex clear_content() (μέθοδος της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage clear_content}@anchor{3d3a}
@deffn {Μέθοδος} clear_content ()

Remove the payload and all of the @code{!Content-} headers, leaving
all other headers intact and in their original order.
@end deffn

@code{EmailMessage} objects have the following instance attributes:

@geindex preamble (ιδιότητα της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage preamble}@anchor{3d3b}
@deffn {Ιδιότητα} preamble

The format of a MIME document allows for some text between the blank line
following the headers, and the first multipart boundary string. Normally,
this text is never visible in a MIME-aware mail reader because it falls
outside the standard MIME armor.  However, when viewing the raw text of
the message, or when viewing the message in a non-MIME aware reader, this
text can become visible.

The `preamble' attribute contains this leading extra-armor text for MIME
documents.  When the @ref{1546,,Parser} discovers some text
after the headers but before the first boundary string, it assigns this
text to the message’s `preamble' attribute.  When the
@ref{1577,,Generator} is writing out the plain text
representation of a MIME message, and it finds the
message has a `preamble' attribute, it will write this text in the area
between the headers and the first boundary.  See @ref{51,,email.parser} and
@ref{43,,email.generator} for details.

Note that if the message object has no preamble, the `preamble' attribute
will be @code{None}.
@end deffn

@geindex epilogue (ιδιότητα της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage epilogue}@anchor{3d3c}
@deffn {Ιδιότητα} epilogue

The `epilogue' attribute acts the same way as the `preamble' attribute,
except that it contains text that appears between the last boundary and
the end of the message.  As with the @ref{3d3b,,preamble},
if there is no epilog text this attribute will be @code{None}.
@end deffn

@geindex defects (ιδιότητα της email.message.EmailMessage)
@anchor{library/email message email message EmailMessage defects}@anchor{3d3d}
@deffn {Ιδιότητα} defects

The `defects' attribute contains a list of all the problems found when
parsing this message.  See @ref{42,,email.errors} for a detailed description
of the possible parsing defects.
@end deffn
@end deffn

@geindex MIMEPart (κλάση σε email.message)
@anchor{library/email message email message MIMEPart}@anchor{12e5}
@deffn {Κλάση} email.message.MIMEPart (policy=default)

This class represents a subpart of a MIME message.  It is identical to
@ref{216,,EmailMessage}, except that no @code{MIME-Version} headers are
added when @ref{1e54,,set_content()} is called, since sub-parts do
not need their own @code{MIME-Version} headers.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{3d3e}@anchor{library/email parser email-parser-parsing-email-messages}@anchor{3d3f}@anchor{library/email parser module-email parser}@anchor{51}@anchor{library/email parser translation-repo}@anchor{3d40}
@subsubsection @code{email.parser}: Parsing email messages


@geindex module; email.parser

`Source code:' Lib/email/parser.py@footnote{https://github.com/python/cpython/tree/main/Lib/email/parser.py}


__________________________________________________________________


Message object structures can be created in one of two ways: they can be
created from whole cloth by creating an @ref{216,,EmailMessage}
object, adding headers using the dictionary interface, and adding payload(s)
using @ref{1e54,,set_content()} and related methods, or
they can be created by parsing a serialized representation of the email
message.

The @ref{3e,,email} package provides a standard parser that understands most email
document structures, including MIME documents.  You can pass the parser a
bytes, string or file object, and the parser will return to you the root
@ref{216,,EmailMessage} instance of the object structure.  For
simple, non-MIME messages the payload of this root object will likely be a
string containing the text of the message.  For MIME messages, the root object
will return @code{True} from its @ref{3d08,,is_multipart()}
method, and the subparts can be accessed via the payload manipulation methods,
such as @ref{3d2c,,get_body()},
@ref{3d2e,,iter_parts()}, and
@ref{3d2b,,walk()}.

There are actually two parser interfaces available for use, the @ref{1546,,Parser}
API and the incremental @ref{19a9,,FeedParser} API.  The @code{Parser} API is
most useful if you have the entire text of the message in memory, or if the
entire message lives in a file on the file system.  @code{FeedParser} is more
appropriate when you are reading the message from a stream which might block
waiting for more input (such as reading an email message from a socket).  The
@code{FeedParser} can consume and parse the message incrementally, and only
returns the root object when you close the parser.

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{3e,,email} package’s bundled parser and the
@ref{216,,EmailMessage} class is embodied in the @ref{1460,,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
* FeedParser API:: 
* Parser API:: 
* Additional notes:: 

@end menu

@node FeedParser API,Parser API,,email parser Parsing email messages
@anchor{library/email parser feedparser-api}@anchor{3d41}
@subsubsection FeedParser API


The @ref{1574,,BytesFeedParser}, imported from the @code{email.feedparser} module,
provides an API that is conducive to incremental parsing of email messages,
such as would be necessary when reading the text of an email message from a
source that can block (such as a socket).  The @code{BytesFeedParser} can of
course be used to parse an email message fully contained in a @ref{436,,bytes-like object}, string, or file, but the @ref{1575,,BytesParser} API may be more
convenient for such use cases.  The semantics and results of the two parser
APIs are identical.

The @ref{1574,,BytesFeedParser}’s API is simple; you create an instance, feed it a
bunch of bytes until there’s no more to feed it, then close the parser to
retrieve the root message object.  The @code{BytesFeedParser} is extremely
accurate when parsing standards-compliant messages, and it does a very good job
of parsing non-compliant messages, providing information about how a message
was deemed broken.  It will populate a message object’s
@ref{3d3d,,defects} attribute with a list of any
problems it found in a message.  See the @ref{42,,email.errors} module for the
list of defects that it can find.

Here is the API for the @ref{1574,,BytesFeedParser}:

@geindex BytesFeedParser (κλάση σε email.parser)
@anchor{library/email parser email parser BytesFeedParser}@anchor{1574}
@deffn {Κλάση} email.parser.BytesFeedParser (_factory=None, *, policy=policy.compat32)

Create a @code{BytesFeedParser} instance.  Optional `_factory' is a
no-argument callable; if not specified use the
@ref{1059,,message_factory} from the `policy'.  Call
`_factory' whenever a new message object is needed.

If `policy' is specified use the rules it specifies to update the
representation of the message.  If `policy' is not set, use the
@ref{1461,,compat32} policy, which maintains backward
compatibility with the Python 3.2 version of the email package and provides
@ref{780,,Message} as the default factory.  All other policies
provide @ref{216,,EmailMessage} as the default `_factory'. For
more information on what else `policy' controls, see the
@ref{52,,policy} documentation.

Note: `The policy keyword should always be specified'; The default will
change to @ref{19ac,,email.policy.default} in a future version of Python.


Added in version 3.2.



Άλλαξε στην έκδοση 3.3: Added the `policy' keyword.



Άλλαξε στην έκδοση 3.6: `_factory' defaults to the policy @code{message_factory}.


@geindex feed() (μέθοδος της email.parser.BytesFeedParser)
@anchor{library/email parser email parser BytesFeedParser feed}@anchor{3d42}
@deffn {Μέθοδος} feed (data)

Feed the parser some more data.  `data' should be a @ref{436,,bytes-like object} containing one or more lines.  The lines can be partial and the
parser will stitch such partial lines together properly.  The lines can
have any of the three common line endings: carriage return, newline, or
carriage return and newline (they can even be mixed).
@end deffn

@geindex close() (μέθοδος της email.parser.BytesFeedParser)
@anchor{library/email parser email parser BytesFeedParser close}@anchor{3d43}
@deffn {Μέθοδος} close ()

Complete the parsing of all previously fed data and return the root
message object.  It is undefined what happens if @ref{3d42,,feed()} is called
after this method has been called.
@end deffn
@end deffn

@geindex FeedParser (κλάση σε email.parser)
@anchor{library/email parser email parser FeedParser}@anchor{19a9}
@deffn {Κλάση} email.parser.FeedParser (_factory=None, *, policy=policy.compat32)

Works like @ref{1574,,BytesFeedParser} except that the input to the
@ref{3d42,,feed()} method must be a string.  This is of limited
utility, since the only way for such a message to be valid is for it to
contain only ASCII text or, if @ref{217,,utf8} is
@code{True}, no binary attachments.


Άλλαξε στην έκδοση 3.3: Added the `policy' keyword.

@end deffn

@node Parser API,Additional notes,FeedParser API,email parser Parsing email messages
@anchor{library/email parser parser-api}@anchor{3d44}
@subsubsection Parser API


The @ref{1575,,BytesParser} class, imported from the @code{email.parser} module,
provides an API that can be used to parse a message when the complete contents
of the message are available in a @ref{436,,bytes-like object} or file.  The
@code{email.parser} module also provides @ref{1546,,Parser} for parsing strings,
and header-only parsers, @ref{1468,,BytesHeaderParser} and
@ref{1469,,HeaderParser}, which can be used if you’re only interested in the
headers of the message.  @code{BytesHeaderParser} and @code{HeaderParser}
can be much faster in these situations, since they do not attempt to parse the
message body, instead setting the payload to the raw body.

@geindex BytesParser (κλάση σε email.parser)
@anchor{library/email parser email parser BytesParser}@anchor{1575}
@deffn {Κλάση} email.parser.BytesParser (_class=None, *, policy=policy.compat32)

Create a @code{BytesParser} instance.  The `_class' and `policy'
arguments have the same meaning and semantics as the `_factory'
and `policy' arguments of @ref{1574,,BytesFeedParser}.

Note: `The policy keyword should always be specified'; The default will
change to @ref{19ac,,email.policy.default} in a future version of Python.


Άλλαξε στην έκδοση 3.3: Removed the `strict' argument that was deprecated in 2.4.  Added the
`policy' keyword.



Άλλαξε στην έκδοση 3.6: `_class' defaults to the policy @code{message_factory}.


@geindex parse() (μέθοδος της email.parser.BytesParser)
@anchor{library/email parser email parser BytesParser parse}@anchor{3d45}
@deffn {Μέθοδος} parse (fp, headersonly=False)

Read all the data from the binary file-like object `fp', parse the
resulting bytes, and return the message object.  `fp' must support
both the @ref{16ce,,readline()} and the @ref{16cd,,read()}
methods.

The bytes contained in `fp' must be formatted as a block of 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}
(or, if @ref{217,,utf8} is @code{True}, 
@geindex RFC; RFC 6532
RFC 6532@footnote{https://datatracker.ietf.org/doc/html/rfc6532.html})
style headers and header continuation lines, optionally preceded by an
envelope header.  The header block is terminated either by the end of the
data or by a blank line.  Following the header block is the body of the
message (which may contain MIME-encoded subparts, including subparts
with a @code{Content-Transfer-Encoding} of @code{8bit}).

Optional `headersonly' is a flag specifying whether to stop parsing after
reading the headers or not.  The default is @code{False}, meaning it parses
the entire contents of the file.
@end deffn

@geindex parsebytes() (μέθοδος της email.parser.BytesParser)
@anchor{library/email parser email parser BytesParser parsebytes}@anchor{3d46}
@deffn {Μέθοδος} parsebytes (bytes, headersonly=False)

Similar to the @ref{3d45,,parse()} method, except it takes a @ref{436,,bytes-like object} instead of a file-like object.  Calling this method on a
bytes-like object is equivalent to wrapping `bytes' in a
@ref{1255,,BytesIO} instance first and calling @code{parse()}.

Optional `headersonly' is as with the @ref{3d45,,parse()} method.
@end deffn


Added in version 3.2.

@end deffn

@geindex BytesHeaderParser (κλάση σε email.parser)
@anchor{library/email parser email parser BytesHeaderParser}@anchor{1468}
@deffn {Κλάση} email.parser.BytesHeaderParser (_class=None, *, policy=policy.compat32)

Exactly like @ref{1575,,BytesParser}, except that `headersonly'
defaults to @code{True}.


Added in version 3.3.

@end deffn

@geindex Parser (κλάση σε email.parser)
@anchor{library/email parser email parser Parser}@anchor{1546}
@deffn {Κλάση} email.parser.Parser (_class=None, *, policy=policy.compat32)

This class is parallel to @ref{1575,,BytesParser}, but handles string input.


Άλλαξε στην έκδοση 3.3: Removed the `strict' argument.  Added the `policy' keyword.



Άλλαξε στην έκδοση 3.6: `_class' defaults to the policy @code{message_factory}.


@geindex parse() (μέθοδος της email.parser.Parser)
@anchor{library/email parser email parser Parser parse}@anchor{3d47}
@deffn {Μέθοδος} parse (fp, headersonly=False)

Read all the data from the text-mode file-like object `fp', parse the
resulting text, and return the root message object.  `fp' must support
both the @ref{2296,,readline()} and the
@ref{225b,,read()} methods on file-like objects.

Other than the text mode requirement, this method operates like
@ref{3d45,,BytesParser.parse()}.
@end deffn

@geindex parsestr() (μέθοδος της email.parser.Parser)
@anchor{library/email parser email parser Parser parsestr}@anchor{3d48}
@deffn {Μέθοδος} parsestr (text, headersonly=False)

Similar to the @ref{3d47,,parse()} method, except it takes a string object
instead of a file-like object.  Calling this method on a string is
equivalent to wrapping `text' in a @ref{12d4,,StringIO} instance first
and calling @code{parse()}.

Optional `headersonly' is as with the @ref{3d47,,parse()} method.
@end deffn
@end deffn

@geindex HeaderParser (κλάση σε email.parser)
@anchor{library/email parser email parser HeaderParser}@anchor{1469}
@deffn {Κλάση} email.parser.HeaderParser (_class=None, *, policy=policy.compat32)

Exactly like @ref{1546,,Parser}, except that `headersonly'
defaults to @code{True}.
@end deffn

Since creating a message object structure from a string or a file object is such
a common task, four functions are provided as a convenience.  They are available
in the top-level @ref{3e,,email} package namespace.

@geindex message_from_bytes() (στη μονάδα email)
@anchor{library/email parser email message_from_bytes}@anchor{1572}
@deffn {Συνάρτηση} email.message_from_bytes (s, _class=None, *, policy=policy.compat32)

Return a message object structure from a @ref{436,,bytes-like object}.  This is
equivalent to @code{BytesParser().parsebytes(s)}.  Optional `_class' and
`policy' are interpreted as with the @ref{1575,,BytesParser} class
constructor.


Added in version 3.2.



Άλλαξε στην έκδοση 3.3: Removed the `strict' argument.  Added the `policy' keyword.

@end deffn

@geindex message_from_binary_file() (στη μονάδα email)
@anchor{library/email parser email message_from_binary_file}@anchor{1573}
@deffn {Συνάρτηση} email.message_from_binary_file (fp, _class=None, *, policy=policy.compat32)

Return a message object structure tree from an open binary @ref{156c,,file object}.  This is equivalent to @code{BytesParser().parse(fp)}.  `_class' and
`policy' are interpreted as with the @ref{1575,,BytesParser} class
constructor.


Added in version 3.2.



Άλλαξε στην έκδοση 3.3: Removed the `strict' argument.  Added the `policy' keyword.

@end deffn

@geindex message_from_string() (στη μονάδα email)
@anchor{library/email parser email message_from_string}@anchor{3d49}
@deffn {Συνάρτηση} email.message_from_string (s, _class=None, *, policy=policy.compat32)

Return a message object structure from a string.  This is equivalent to
@code{Parser().parsestr(s)}.  `_class' and `policy' are interpreted as
with the @ref{1546,,Parser} class constructor.


Άλλαξε στην έκδοση 3.3: Removed the `strict' argument.  Added the `policy' keyword.

@end deffn

@geindex message_from_file() (στη μονάδα email)
@anchor{library/email parser email message_from_file}@anchor{3d4a}
@deffn {Συνάρτηση} email.message_from_file (fp, _class=None, *, policy=policy.compat32)

Return a message object structure tree from an open @ref{156c,,file object}.
This is equivalent to @code{Parser().parse(fp)}.  `_class' and `policy' are
interpreted as with the @ref{1546,,Parser} class constructor.


Άλλαξε στην έκδοση 3.3: Removed the `strict' argument.  Added the `policy' keyword.



Άλλαξε στην έκδοση 3.6: `_class' defaults to the policy @code{message_factory}.

@end deffn

Here’s an example of how you might use @ref{1572,,message_from_bytes()} at an
interactive Python prompt:

@example
>>> import email
>>> msg = email.message_from_bytes(myBytes)
@end example

@node Additional notes,,Parser API,email parser Parsing email messages
@anchor{library/email parser additional-notes}@anchor{3d4b}
@subsubsection Additional notes


Here are some notes on the parsing semantics:


@itemize *

@item 
Most non-@code{multipart} type messages are parsed as a single message
object with a string payload.  These objects will return @code{False} for
@ref{3d08,,is_multipart()}, and
@ref{3d2e,,iter_parts()} will yield an empty list.

@item 
All @code{multipart} type messages will be parsed as a container message
object with a list of sub-message objects for their payload.  The outer
container message will return @code{True} for
@ref{3d08,,is_multipart()}, and
@ref{3d2e,,iter_parts()} will yield a list of subparts.

@item 
Most messages with a content type of @code{message/*} (such as
@code{message/delivery-status} and @code{message/rfc822}) will also
be parsed as container object containing a list payload of length 1.  Their
@ref{3d08,,is_multipart()} method will return @code{True}.
The single element yielded by @ref{3d2e,,iter_parts()}
will be a sub-message object.

@item 
Some non-standards-compliant messages may not be internally consistent about
their @code{multipart}-edness.  Such messages may have a
@code{Content-Type} header of type @code{multipart}, but their
@ref{3d08,,is_multipart()} method may return @code{False}.
If such messages were parsed with the @ref{19a9,,FeedParser},
they will have an instance of the
@ref{3d4c,,MultipartInvariantViolationDefect} class in their
`defects' attribute list.  See @ref{42,,email.errors} for details.
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{3d4d}@anchor{library/email generator email-generator-generating-mime-documents}@anchor{3d4e}@anchor{library/email generator module-email generator}@anchor{43}@anchor{library/email generator translation-repo}@anchor{3d4f}
@subsubsection @code{email.generator}: Generating MIME documents


@geindex module; email.generator

`Source code:' Lib/email/generator.py@footnote{https://github.com/python/cpython/tree/main/Lib/email/generator.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{120a,,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.

As with the @ref{51,,email.parser} module, you aren’t limited to the functionality
of the bundled generator; you could write one from scratch yourself.  However
the bundled generator knows how to generate most email in a standards-compliant
way, should handle MIME and non-MIME email messages just fine, and is designed
so that the bytes-oriented parsing and generation operations are inverses,
assuming the same non-transforming @ref{52,,policy} is used for both.  That
is, parsing the serialized byte stream via the
@ref{1575,,BytesParser} class and then regenerating the serialized
byte stream using @ref{1578,,BytesGenerator} should produce output identical to
the input @footnote{
This statement assumes that you use the appropriate setting for
@code{unixfrom}, and that there are no @ref{52,,email.policy} settings calling for
automatic adjustments (for example,
@ref{3d50,,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.
}.  (On the other hand, using the generator on an
@ref{216,,EmailMessage} constructed by program may result in
changes to the @code{EmailMessage} object as defaults are
filled in.)

The @ref{1577,,Generator} class can be used to flatten a message into a text (as
opposed to binary) serialized representation, but since Unicode cannot
represent binary data directly, the message is of necessity transformed into
something that contains only ASCII characters, using the standard email RFC
Content Transfer Encoding techniques for encoding email messages for transport
over channels that are not «8 bit clean».

To accommodate reproducible processing of SMIME-signed messages
@ref{1577,,Generator} disables header folding for message parts of type
@code{multipart/signed} and all subparts.

@geindex BytesGenerator (κλάση σε email.generator)
@anchor{library/email generator email generator BytesGenerator}@anchor{1578}
@deffn {Κλάση} email.generator.BytesGenerator (outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Return a @code{BytesGenerator} object that will write any message provided
to the @ref{3d51,,flatten()} method, or any surrogateescape encoded text provided
to the @ref{3d52,,write()} method, to the @ref{19b1,,file-like object} `outfp'.
`outfp' must support a @code{write} method that accepts binary data.

If optional `mangle_from_' is @code{True}, put a @code{>} character in front of
any line in the body that starts with the exact string @code{"From "}, that is
@code{From} followed by a space at the beginning of a line.  `mangle_from_'
defaults to the value of the @ref{11af,,mangle_from_}
setting of the `policy' (which is @code{True} for the
@ref{105a,,compat32} policy and @code{False} for all others).
`mangle_from_' is intended for use when messages are stored in Unix mbox
format (see @ref{8e,,mailbox} and WHY THE CONTENT-LENGTH FORMAT IS BAD@footnote{https://www.jwz.org/doc/content-length.html}).

If `maxheaderlen' is not @code{None}, refold any header lines that are longer
than `maxheaderlen', or if @code{0}, do not rewrap any headers.  If
`manheaderlen' is @code{None} (the default), wrap headers and other message
lines according to the `policy' settings.

If `policy' is specified, use that policy to control message generation.  If
`policy' is @code{None} (the default), use the policy associated with the
@ref{780,,Message} or @ref{216,,EmailMessage}
object passed to @code{flatten} to control the message generation.  See
@ref{52,,email.policy} for details on what `policy' controls.


Added in version 3.2.



Άλλαξε στην έκδοση 3.3: Added the `policy' keyword.



Άλλαξε στην έκδοση 3.6: The default behavior of the `mangle_from_'
and `maxheaderlen' parameters is to follow the policy.


@geindex flatten() (μέθοδος της email.generator.BytesGenerator)
@anchor{library/email generator email generator BytesGenerator flatten}@anchor{3d51}
@deffn {Μέθοδος} flatten (msg, unixfrom=False, linesep=None)

Print the textual representation of the message object structure rooted
at `msg' to the output file specified when the @code{BytesGenerator}
instance was created.

If the @ref{52,,policy} option @ref{3d53,,cte_type}
is @code{8bit} (the default), copy any headers in the original parsed
message that have not been modified to the output with any bytes with the
high bit set reproduced as in the original, and preserve the non-ASCII
@code{Content-Transfer-Encoding} of any body parts that have them.
If @code{cte_type} is @code{7bit}, convert the bytes with the high bit set as
needed using an ASCII-compatible @code{Content-Transfer-Encoding}.
That is, transform parts with non-ASCII
@code{Content-Transfer-Encoding}
(@code{Content-Transfer-Encoding: 8bit}) to an ASCII compatible
@code{Content-Transfer-Encoding}, and encode RFC-invalid non-ASCII
bytes in headers using the MIME @code{unknown-8bit} character set, thus
rendering them RFC-compliant.

@c XXX: There should be an option that just does the RFC
@c compliance transformation on headers but leaves CTE 8bit parts alone.

If `unixfrom' is @code{True}, print the envelope header delimiter used by
the Unix mailbox format (see @ref{8e,,mailbox}) before the first of the
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} headers of the root message object.  If the root object has
no envelope header, craft a standard one.  The default is @code{False}.
Note that for subparts, no envelope header is ever printed.

If `linesep' is not @code{None}, use it as the separator character between
all the lines of the flattened message.  If `linesep' is @code{None} (the
default), use the value specified in the `policy'.

@c XXX: flatten should take a *policy* keyword.
@end deffn

@geindex clone() (μέθοδος της email.generator.BytesGenerator)
@anchor{library/email generator email generator BytesGenerator clone}@anchor{3d54}
@deffn {Μέθοδος} clone (fp)

Return an independent clone of this @code{BytesGenerator} instance with
the exact same option settings, and `fp' as the new `outfp'.
@end deffn

@geindex write() (μέθοδος της email.generator.BytesGenerator)
@anchor{library/email generator email generator BytesGenerator write}@anchor{3d52}
@deffn {Μέθοδος} write (s)

Encode `s' using the @code{ASCII} codec and the @code{surrogateescape} error
handler, and pass it to the `write' method of the `outfp' passed to the
@code{BytesGenerator}’s constructor.
@end deffn
@end deffn

As a convenience, @ref{216,,EmailMessage} provides the methods
@ref{3d06,,as_bytes()} and @code{bytes(aMessage)} (a.k.a.
@ref{3d07,,__bytes__()}), which simplify the generation of
a serialized binary representation of a message object.  For more detail, see
@ref{47,,email.message}.

Because strings cannot represent binary data, the @ref{1577,,Generator} class must
convert any binary data in any message it flattens to an ASCII compatible
format, by converting them to an ASCII compatible
@code{Content-Transfer_Encoding}.  Using the terminology of the email
RFCs, you can think of this as @code{Generator} serializing to an I/O stream
that is not «8 bit clean».  In other words, most applications will want
to be using @ref{1578,,BytesGenerator}, and not @code{Generator}.

@geindex Generator (κλάση σε email.generator)
@anchor{library/email generator email generator Generator}@anchor{1577}
@deffn {Κλάση} email.generator.Generator (outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Return a @code{Generator} object that will write any message provided
to the @ref{3d55,,flatten()} method, or any text provided to the @ref{3d56,,write()}
method, to the @ref{19b1,,file-like object} `outfp'.  `outfp' must support a
@code{write} method that accepts string data.

If optional `mangle_from_' is @code{True}, put a @code{>} character in front of
any line in the body that starts with the exact string @code{"From "}, that is
@code{From} followed by a space at the beginning of a line.  `mangle_from_'
defaults to the value of the @ref{11af,,mangle_from_}
setting of the `policy' (which is @code{True} for the
@ref{105a,,compat32} policy and @code{False} for all others).
`mangle_from_' is intended for use when messages are stored in Unix mbox
format (see @ref{8e,,mailbox} and WHY THE CONTENT-LENGTH FORMAT IS BAD@footnote{https://www.jwz.org/doc/content-length.html}).

If `maxheaderlen' is not @code{None}, refold any header lines that are longer
than `maxheaderlen', or if @code{0}, do not rewrap any headers.  If
`manheaderlen' is @code{None} (the default), wrap headers and other message
lines according to the `policy' settings.

If `policy' is specified, use that policy to control message generation.  If
`policy' is @code{None} (the default), use the policy associated with the
@ref{780,,Message} or @ref{216,,EmailMessage}
object passed to @code{flatten} to control the message generation.  See
@ref{52,,email.policy} for details on what `policy' controls.


Άλλαξε στην έκδοση 3.3: Added the `policy' keyword.



Άλλαξε στην έκδοση 3.6: The default behavior of the `mangle_from_'
and `maxheaderlen' parameters is to follow the policy.


@geindex flatten() (μέθοδος της email.generator.Generator)
@anchor{library/email generator email generator Generator flatten}@anchor{3d55}
@deffn {Μέθοδος} flatten (msg, unixfrom=False, linesep=None)

Print the textual representation of the message object structure rooted
at `msg' to the output file specified when the @code{Generator}
instance was created.

If the @ref{52,,policy} option @ref{3d53,,cte_type}
is @code{8bit}, generate the message as if the option were set to @code{7bit}.
(This is required because strings cannot represent non-ASCII bytes.)
Convert any bytes with the high bit set as needed using an
ASCII-compatible @code{Content-Transfer-Encoding}.  That is,
transform parts with non-ASCII @code{Content-Transfer-Encoding}
(@code{Content-Transfer-Encoding: 8bit}) to an ASCII compatible
@code{Content-Transfer-Encoding}, and encode RFC-invalid non-ASCII
bytes in headers using the MIME @code{unknown-8bit} character set, thus
rendering them RFC-compliant.

If `unixfrom' is @code{True}, print the envelope header delimiter used by
the Unix mailbox format (see @ref{8e,,mailbox}) before the first of the
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} headers of the root message object.  If the root object has
no envelope header, craft a standard one.  The default is @code{False}.
Note that for subparts, no envelope header is ever printed.

If `linesep' is not @code{None}, use it as the separator character between
all the lines of the flattened message.  If `linesep' is @code{None} (the
default), use the value specified in the `policy'.

@c XXX: flatten should take a *policy* keyword.


Άλλαξε στην έκδοση 3.2: Added support for re-encoding @code{8bit} message bodies, and the
`linesep' argument.

@end deffn

@geindex clone() (μέθοδος της email.generator.Generator)
@anchor{library/email generator email generator Generator clone}@anchor{3d57}
@deffn {Μέθοδος} clone (fp)

Return an independent clone of this @code{Generator} instance with the
exact same options, and `fp' as the new `outfp'.
@end deffn

@geindex write() (μέθοδος της email.generator.Generator)
@anchor{library/email generator email generator Generator write}@anchor{3d56}
@deffn {Μέθοδος} write (s)

Write `s' to the `write' method of the `outfp' passed to the
@code{Generator}’s constructor.  This provides just enough file-like
API for @code{Generator} instances to be used in the @ref{131f,,print()}
function.
@end deffn
@end deffn

As a convenience, @ref{216,,EmailMessage} provides the methods
@ref{3d03,,as_string()} and @code{str(aMessage)} (a.k.a.
@ref{3d05,,__str__()}), which simplify the generation of
a formatted string representation of a message object.  For more detail, see
@ref{47,,email.message}.

The @code{email.generator} module also provides a derived class,
@ref{1058,,DecodedGenerator}, which is like the @ref{1577,,Generator} base class,
except that non-@code{text} parts are not serialized, but are instead
represented in the output stream by a string derived from a template filled
in with information about the part.

@geindex DecodedGenerator (κλάση σε email.generator)
@anchor{library/email generator email generator DecodedGenerator}@anchor{1058}
@deffn {Κλάση} email.generator.DecodedGenerator (outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

Act like @ref{1577,,Generator}, except that for any subpart of the message
passed to @ref{3d55,,Generator.flatten()}, if the subpart is of main type
@code{text}, print the decoded payload of the subpart, and if the main
type is not @code{text}, instead of printing it fill in the string
`fmt' using information from the part and print the resulting
filled-in string.

To fill in `fmt', execute @code{fmt % part_info}, where @code{part_info}
is a dictionary composed of the following keys and values:


@itemize *

@item 
@code{type} – Full MIME type of the non-@code{text} part

@item 
@code{maintype} – Main MIME type of the non-@code{text} part

@item 
@code{subtype} – Sub-MIME type of the non-@code{text} part

@item 
@code{filename} – Filename of the non-@code{text} part

@item 
@code{description} – Description associated with the non-@code{text} part

@item 
@code{encoding} – Content transfer encoding of the non-@code{text} part
@end itemize

If `fmt' is @code{None}, use the following default `fmt':

@quotation

«[Non-text (%(type)s) part of message omitted, filename %(filename)s]»
@end quotation

Optional `_mangle_from_' and `maxheaderlen' are as with the
@ref{1577,,Generator} base class.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node email policy Policy Objects,email errors Κλάσεις Εξαιρέσεων και Ελαττωμάτων,email generator Generating MIME documents,email — An email and MIME handling package
@anchor{library/email policy doc}@anchor{3d58}@anchor{library/email policy email-policy-policy-objects}@anchor{3d59}@anchor{library/email policy module-email policy}@anchor{52}@anchor{library/email policy translation-repo}@anchor{3d5a}
@subsubsection @code{email.policy}: Policy Objects


@geindex module; email.policy


Added in version 3.3.


`Source code:' Lib/email/policy.py@footnote{https://github.com/python/cpython/tree/main/Lib/email/policy.py}


__________________________________________________________________


The @ref{3e,,email} package’s prime focus is the handling of email messages as
described by the various email and MIME RFCs.  However, the general format of
email messages (a block of header fields each consisting of a name followed by
a colon followed by a value, the whole block followed by a blank line and an
arbitrary “body”), is a format that has found utility outside of the realm of
email.  Some of these uses conform fairly closely to the main email RFCs, some
do not.  Even when working with email, there are times when it is desirable to
break strict compliance with the RFCs, such as generating emails that
interoperate with email servers that do not themselves follow the standards, or
that implement extensions you want to use in ways that violate the
standards.

Policy objects give the email package the flexibility to handle all these
disparate use cases.

A @ref{1460,,Policy} object encapsulates a set of attributes and methods that
control the behavior of various components of the email package during use.
@code{Policy} instances can be passed to various classes and methods in the
email package to alter the default behavior.  The settable values and their
defaults are described below.

There is a default policy used by all classes in the email package.  For all of
the @ref{51,,parser} classes and the related convenience functions, and for
the @ref{780,,Message} class, this is the @ref{1461,,Compat32}
policy, via its corresponding pre-defined instance @ref{105a,,compat32}.  This
policy provides for complete backward compatibility (in some cases, including
bug compatibility) with the pre-Python3.3 version of the email package.

This default value for the `policy' keyword to
@ref{216,,EmailMessage} is the @ref{1464,,EmailPolicy} policy, via
its pre-defined instance @ref{19ac,,default}.

When a @ref{780,,Message} or @ref{216,,EmailMessage}
object is created, it acquires a policy.  If the message is created by a
@ref{51,,parser}, a policy passed to the parser will be the policy used by
the message it creates.  If the message is created by the program, then the
policy can be specified when it is created.  When a message is passed to a
@ref{43,,generator}, the generator uses the policy from the message by
default, but you can also pass a specific policy to the generator that will
override the one stored on the message object.

The default value for the `policy' keyword for the @ref{51,,email.parser} classes
and the parser convenience functions `will be changing' in a future version of
Python.  Therefore you should `always specify explicitly which policy you want
to use' when calling any of the classes and functions described in the
@code{parser} module.

The first part of this documentation covers the features of @ref{1460,,Policy}, an
@ref{155f,,abstract base class} that defines the features that are common to all
policy objects, including @ref{105a,,compat32}.  This includes certain hook
methods that are called internally by the email package, which a custom policy
could override to obtain different behavior.  The second part describes the
concrete classes @ref{1464,,EmailPolicy} and @ref{1461,,Compat32}, which implement
the hooks that provide the standard behavior and the backward compatible
behavior and features, respectively.

@ref{1460,,Policy} instances are immutable, but they can be cloned, accepting the
same keyword arguments as the class constructor and returning a new
@code{Policy} instance that is a copy of the original but with the specified
attributes values changed.

As an example, the following code could be used to read an email message from a
file on disk and pass it to the system @code{sendmail} program on a Unix system:

@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')

Here we are telling @ref{1578,,BytesGenerator} to use the RFC
correct line separator characters when creating the binary string to feed into
@code{sendmail's} @code{stdin}, where the default policy would use @code{\n} line
separators.

Some email package methods accept a `policy' keyword argument, allowing the
policy to be overridden for that method.  For example, the following code uses
the @ref{12e2,,as_bytes()} method of the `msg' object from
the previous example and writes the message to a file using the native line
separators for the platform on which it is running:

@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

Policy objects can also be combined using the addition operator, producing a
policy object whose settings are a combination of the non-default values of the
summed objects:

@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

This operation is not commutative; that is, the order in which the objects are
added matters.  To illustrate:

@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 (κλάση σε email.policy)
@anchor{library/email policy email policy Policy}@anchor{1460}
@deffn {Κλάση} email.policy.Policy (**kw)

This is the @ref{155f,,abstract base class} for all policy classes.  It provides
default implementations for a couple of trivial methods, as well as the
implementation of the immutability property, the @ref{1462,,clone()} method, and
the constructor semantics.

The constructor of a policy class can be passed various keyword arguments.
The arguments that may be specified are any non-method properties on this
class, plus any additional non-method properties on the concrete class.  A
value specified in the constructor will override the default value for the
corresponding attribute.

This class defines the following properties, and thus values for the
following may be passed in the constructor of any policy class:

@geindex max_line_length (ιδιότητα της email.policy.Policy)
@anchor{library/email policy email policy Policy max_line_length}@anchor{3d04}
@deffn {Ιδιότητα} max_line_length

The maximum length of any line in the serialized output, not counting the
end of line character(s).  Default is 78, per 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}.  A value of
@code{0} or @ref{a65,,None} indicates that no line wrapping should be
done at all.
@end deffn

@geindex linesep (ιδιότητα της email.policy.Policy)
@anchor{library/email policy email policy Policy linesep}@anchor{3d5b}
@deffn {Ιδιότητα} linesep

The string to be used to terminate lines in serialized output.  The
default is @code{\n} because that’s the internal end-of-line discipline used
by Python, though @code{\r\n} is required by the RFCs.
@end deffn

@geindex cte_type (ιδιότητα της email.policy.Policy)
@anchor{library/email policy email policy Policy cte_type}@anchor{3d53}
@deffn {Ιδιότητα} cte_type

Controls the type of Content Transfer Encodings that may be or are
required to be used.  The possible values are:


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{7bit}

@tab

all data must be «7 bit clean» (ASCII-only).  This means that
where necessary data will be encoded using either
quoted-printable or base64 encoding.

@item

@code{8bit}

@tab

data is not constrained to be 7 bit clean.  Data in headers is
still required to be ASCII-only and so will be encoded (see
@ref{3d5c,,fold_binary()} and @ref{217,,utf8} below for
exceptions), but body parts may use the @code{8bit} CTE.

@end multitable


A @code{cte_type} value of @code{8bit} only works with @code{BytesGenerator}, not
@code{Generator}, because strings cannot contain binary data.  If a
@code{Generator} is operating under a policy that specifies
@code{cte_type=8bit}, it will act as if @code{cte_type} is @code{7bit}.
@end deffn

@geindex raise_on_defect (ιδιότητα της email.policy.Policy)
@anchor{library/email policy email policy Policy raise_on_defect}@anchor{3d5d}
@deffn {Ιδιότητα} raise_on_defect

If @ref{fcc,,True}, any defects encountered will be raised as errors.  If
@ref{ef5,,False} (the default), defects will be passed to the
@ref{3d5e,,register_defect()} method.
@end deffn

@geindex mangle_from_ (ιδιότητα της email.policy.Policy)
@anchor{library/email policy email policy Policy mangle_from_}@anchor{11af}
@deffn {Ιδιότητα} mangle_from_

If @ref{fcc,,True}, lines starting with `«From «' in the body are
escaped by putting a @code{>} in front of them. This parameter is used when
the message is being serialized by a generator.
Default: @ref{ef5,,False}.


Added in version 3.5.

@end deffn

@geindex message_factory (ιδιότητα της email.policy.Policy)
@anchor{library/email policy email policy Policy message_factory}@anchor{1059}
@deffn {Ιδιότητα} message_factory

A factory function for constructing a new empty message object.  Used
by the parser when building messages.  Defaults to @code{None}, in
which case @ref{780,,Message} is used.


Added in version 3.6.

@end deffn

@geindex verify_generated_headers (ιδιότητα της email.policy.Policy)
@anchor{library/email policy email policy Policy verify_generated_headers}@anchor{6f7}
@deffn {Ιδιότητα} verify_generated_headers

If @code{True} (the default), the generator will raise
@ref{1910,,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{1461,,Compat32} policy.
For backwards compatible, but unsafe, behavior, it must be set to
@code{False} explicitly.


Added in version 3.13.

@end deffn

The following @code{Policy} method is intended to be called by code using
the email library to create policy instances with custom settings:

@geindex clone() (μέθοδος της email.policy.Policy)
@anchor{library/email policy email policy Policy clone}@anchor{1462}
@deffn {Μέθοδος} clone (**kw)

Return a new @code{Policy} instance whose attributes have the same
values as the current instance, except where those attributes are
given new values by the keyword arguments.
@end deffn

The remaining @code{Policy} methods are called by the email package code,
and are not intended to be called by an application using the email package.
A custom policy must implement all of these methods.

@geindex handle_defect() (μέθοδος της email.policy.Policy)
@anchor{library/email policy email policy Policy handle_defect}@anchor{3d5f}
@deffn {Μέθοδος} handle_defect (obj, defect)

Handle a `defect' found on `obj'.  When the email package calls this
method, `defect' will always be a subclass of
@ref{3d60,,MessageDefect}.

The default implementation checks the @ref{3d5d,,raise_on_defect} flag.  If
it is @code{True}, `defect' is raised as an exception.  If it is @code{False}
(the default), `obj' and `defect' are passed to @ref{3d5e,,register_defect()}.
@end deffn

@geindex register_defect() (μέθοδος της email.policy.Policy)
@anchor{library/email policy email policy Policy register_defect}@anchor{3d5e}
@deffn {Μέθοδος} register_defect (obj, defect)

Register a `defect' on `obj'.  In the email package, `defect' will always
be a subclass of @ref{3d60,,MessageDefect}.

The default implementation calls the @code{append} method of the @code{defects}
attribute of `obj'.  When the email package calls @ref{3d5f,,handle_defect},
`obj' will normally have a @code{defects} attribute that has an @code{append}
method.  Custom object types used with the email package (for example,
custom @code{Message} objects) should also provide such an attribute,
otherwise defects in parsed messages will raise unexpected errors.
@end deffn

@geindex header_max_count() (μέθοδος της email.policy.Policy)
@anchor{library/email policy email policy Policy header_max_count}@anchor{3d61}
@deffn {Μέθοδος} header_max_count (name)

Return the maximum allowed number of headers named `name'.

Called when a header is added to an @ref{216,,EmailMessage}
or @ref{780,,Message} object.  If the returned value is not
@code{0} or @code{None}, and there are already a number of headers with the
name `name' greater than or equal to the value returned, a
@ref{277,,ValueError} is raised.

Because the default behavior of @code{Message.__setitem__} is to append the
value to the list of headers, it is easy to create duplicate headers
without realizing it.  This method allows certain headers to be limited
in the number of instances of that header that may be added to a
@code{Message} programmatically.  (The limit is not observed by the parser,
which will faithfully produce as many headers as exist in the message
being parsed.)

The default implementation returns @code{None} for all header names.
@end deffn

@geindex header_source_parse() (μέθοδος της email.policy.Policy)
@anchor{library/email policy email policy Policy header_source_parse}@anchor{3d62}
@deffn {Μέθοδος} header_source_parse (sourcelines)

The email package calls this method with a list of strings, each string
ending with the line separation characters found in the source being
parsed.  The first line includes the field header name and separator.
All whitespace in the source is preserved.  The method should return the
@code{(name, value)} tuple that is to be stored in the @code{Message} to
represent the parsed header.

If an implementation wishes to retain compatibility with the existing
email package policies, `name' should be the case preserved name (all
characters up to the “@code{:}” separator), while `value' should be the
unfolded value (all line separator characters removed, but whitespace
kept intact), stripped of leading whitespace.

`sourcelines' may contain surrogateescaped binary data.

There is no default implementation
@end deffn

@geindex header_store_parse() (μέθοδος της email.policy.Policy)
@anchor{library/email policy email policy Policy header_store_parse}@anchor{3d63}
@deffn {Μέθοδος} header_store_parse (name, value)

The email package calls this method with the name and value provided by
the application program when the application program is modifying a
@code{Message} programmatically (as opposed to a @code{Message} created by a
parser).  The method should return the @code{(name, value)} tuple that is to
be stored in the @code{Message} to represent the header.

If an implementation wishes to retain compatibility with the existing
email package policies, the `name' and `value' should be strings or
string subclasses that do not change the content of the passed in
arguments.

There is no default implementation
@end deffn

@geindex header_fetch_parse() (μέθοδος της email.policy.Policy)
@anchor{library/email policy email policy Policy header_fetch_parse}@anchor{3d64}
@deffn {Μέθοδος} header_fetch_parse (name, value)

The email package calls this method with the `name' and `value' currently
stored in the @code{Message} when that header is requested by the
application program, and whatever the method returns is what is passed
back to the application as the value of the header being retrieved.
Note that there may be more than one header with the same name stored in
the @code{Message}; the method is passed the specific name and value of the
header destined to be returned to the application.

`value' may contain surrogateescaped binary data.  There should be no
surrogateescaped binary data in the value returned by the method.

There is no default implementation
@end deffn

@geindex fold() (μέθοδος της email.policy.Policy)
@anchor{library/email policy email policy Policy fold}@anchor{3d65}
@deffn {Μέθοδος} fold (name, value)

The email package calls this method with the `name' and `value' currently
stored in the @code{Message} for a given header.  The method should return a
string that represents that header «folded» correctly (according to the
policy settings) by composing the `name' with the `value' and inserting
@ref{3d5b,,linesep} characters at the appropriate places.  See 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}
for a discussion of the rules for folding email headers.

`value' may contain surrogateescaped binary data.  There should be no
surrogateescaped binary data in the string returned by the method.
@end deffn

@geindex fold_binary() (μέθοδος της email.policy.Policy)
@anchor{library/email policy email policy Policy fold_binary}@anchor{3d5c}
@deffn {Μέθοδος} fold_binary (name, value)

The same as @ref{3d65,,fold()}, except that the returned value should be a
bytes object rather than a string.

`value' may contain surrogateescaped binary data.  These could be
converted back into binary data in the returned bytes object.
@end deffn
@end deffn

@geindex EmailPolicy (κλάση σε email.policy)
@anchor{library/email policy email policy EmailPolicy}@anchor{1464}
@deffn {Κλάση} email.policy.EmailPolicy (**kw)

This concrete @ref{1460,,Policy} provides behavior that is intended to be fully
compliant with the current email RFCs.  These include (but are not limited
to) 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}, 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html}, and the current MIME RFCs.

This policy adds new header parsing and folding algorithms.  Instead of
simple strings, headers are @code{str} subclasses with attributes that depend
on the type of the field.  The parsing and folding algorithm fully implement
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} and 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}.

The default value for the @ref{1059,,message_factory}
attribute is @ref{216,,EmailMessage}.

In addition to the settable attributes listed above that apply to all
policies, this policy adds the following additional attributes:


Added in version 3.6: @footnote{
Originally added in 3.3 as a @ref{13ea,,provisional feature}.
}


@geindex utf8 (ιδιότητα της email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy utf8}@anchor{217}
@deffn {Ιδιότητα} utf8

If @code{False}, follow 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}, supporting non-ASCII characters in
headers by encoding them as 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} «encoded words».  If @code{True},
follow 
@geindex RFC; RFC 6532
RFC 6532@footnote{https://datatracker.ietf.org/doc/html/rfc6532.html} and use @code{utf-8} encoding for headers.  Messages
formatted in this way may be passed to SMTP servers that support
the @code{SMTPUTF8} extension (
@geindex RFC; RFC 6531
RFC 6531@footnote{https://datatracker.ietf.org/doc/html/rfc6531.html}).

When @code{False}, the generator will raise
@ref{1910,,HeaderWriteError} if any header includes non-ASCII
characters in a context where 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} does not permit encoded words.
This particularly applies to mailboxes («addr-spec») with non-ASCII
characters, which can be created via
@ref{1912,,Address}. To use a mailbox with a non-ASCII
domain name with @code{utf8=False}, first encode the domain using the
third-party idna@footnote{https://pypi.org/project/idna/} or uts46@footnote{https://pypi.org/project/uts46/} module or with
@ref{55,,encodings.idna}. It is not possible to use a non-ASCII username
(«local-part») in a mailbox when @code{utf8=False}.


Άλλαξε στην έκδοση 3.15: Can trigger the raising of @ref{1910,,HeaderWriteError}.
(Earlier versions incorrectly applied 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} in certain contexts,
mostly notably in addr-specs.)

@end deffn

@geindex refold_source (ιδιότητα της email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy refold_source}@anchor{3d50}
@deffn {Ιδιότητα} refold_source

If the value for a header in the @code{Message} object originated from a
@ref{51,,parser} (as opposed to being set by a program), this
attribute indicates whether or not a generator should refold that value
when transforming the message back into serialized form.  The possible
values are:


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{none}

@tab

all source values use original folding

@item

@code{long}

@tab

source values that have any line that is longer than
@code{max_line_length} will be refolded

@item

@code{all}

@tab

all values are refolded.

@end multitable


The default is @code{long}.
@end deffn

@geindex header_factory (ιδιότητα της email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy header_factory}@anchor{3d66}
@deffn {Ιδιότητα} header_factory

A callable that takes two arguments, @code{name} and @code{value}, where
@code{name} is a header field name and @code{value} is an unfolded header field
value, and returns a string subclass that represents that header.  A
default @code{header_factory} (see @ref{45,,headerregistry}) is provided
that supports custom parsing for the various address and date 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}
header field types, and the major MIME header field stypes.  Support for
additional custom parsing will be added in the future.
@end deffn

@geindex content_manager (ιδιότητα της email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy content_manager}@anchor{12e6}
@deffn {Ιδιότητα} content_manager

An object with at least two methods: get_content and set_content.  When
the @ref{3d2f,,get_content()} or
@ref{1e54,,set_content()} method of an
@ref{216,,EmailMessage} object is called, it calls the
corresponding method of this object, passing it the message object as its
first argument, and any arguments or keywords that were passed to it as
additional arguments.  By default @code{content_manager} is set to
@ref{3d67,,raw_data_manager}.


Added in version 3.4.

@end deffn

The class provides the following concrete implementations of the abstract
methods of @ref{1460,,Policy}:

@geindex header_max_count() (μέθοδος της email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy header_max_count}@anchor{3d68}
@deffn {Μέθοδος} header_max_count (name)

Returns the value of the
@ref{3d69,,max_count} attribute of the
specialized class used to represent the header with the given name.
@end deffn

@geindex header_source_parse() (μέθοδος της email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy header_source_parse}@anchor{1b2d}
@deffn {Μέθοδος} header_source_parse (sourcelines)

The name is parsed as everything up to the “@code{:}” and returned
unmodified.  The value is determined by stripping leading whitespace off
the remainder of the first line, joining all subsequent lines together,
and stripping any trailing carriage return or linefeed characters.
@end deffn

@geindex header_store_parse() (μέθοδος της email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy header_store_parse}@anchor{3d6a}
@deffn {Μέθοδος} header_store_parse (name, value)

The name is returned unchanged.  If the input value has a @code{name}
attribute and it matches `name' ignoring case, the value is returned
unchanged.  Otherwise the `name' and `value' are passed to
@code{header_factory}, and the resulting header object is returned as
the value.  In this case a @code{ValueError} is raised if the input value
contains CR or LF characters.
@end deffn

@geindex header_fetch_parse() (μέθοδος της email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy header_fetch_parse}@anchor{3d6b}
@deffn {Μέθοδος} header_fetch_parse (name, value)

If the value has a @code{name} attribute, it is returned to unmodified.
Otherwise the `name', and the `value' with any CR or LF characters
removed, are passed to the @code{header_factory}, and the resulting
header object is returned.  Any surrogateescaped bytes get turned into
the unicode unknown-character glyph.
@end deffn

@geindex fold() (μέθοδος της email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy fold}@anchor{1bfb}
@deffn {Μέθοδος} fold (name, value)

Header folding is controlled by the @ref{3d50,,refold_source} policy setting.
A value is considered to be a “source value” if and only if it does not
have a @code{name} attribute (having a @code{name} attribute means it is a
header object of some sort).  If a source value needs to be refolded
according to the policy, it is converted into a header object by
passing the `name' and the `value' with any CR and LF characters removed
to the @code{header_factory}.  Folding of a header object is done by
calling its @code{fold} method with the current policy.

Source values are split into lines using @ref{15fb,,splitlines()}.  If
the value is not to be refolded, the lines are rejoined using the
@code{linesep} from the policy and returned.  The exception is lines
containing non-ascii binary data.  In that case the value is refolded
regardless of the @code{refold_source} setting, which causes the binary data
to be CTE encoded using the @code{unknown-8bit} charset.
@end deffn

@geindex fold_binary() (μέθοδος της email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy fold_binary}@anchor{3d6c}
@deffn {Μέθοδος} fold_binary (name, value)

The same as @ref{1bfb,,fold()} if @ref{3d53,,cte_type} is @code{7bit}, except
that the returned value is bytes.

If @ref{3d53,,cte_type} is @code{8bit}, non-ASCII binary data is
converted back
into bytes.  Headers with binary data are not refolded, regardless of the
@code{refold_header} setting, since there is no way to know whether the
binary data consists of single byte characters or multibyte characters.
@end deffn
@end deffn

The following instances of @ref{1464,,EmailPolicy} provide defaults suitable for
specific application domains.  Note that in the future the behavior of these
instances (in particular the @code{HTTP} instance) may be adjusted to conform even
more closely to the RFCs relevant to their domains.

@geindex default (στη μονάδα email.policy)
@anchor{library/email policy email policy default}@anchor{19ac}
@deffn {Δεδομένα} email.policy.default

An instance of @code{EmailPolicy} with all defaults unchanged.  This policy
uses the standard Python @code{\n} line endings rather than the RFC-correct
@code{\r\n}.
@end deffn

@geindex SMTP (στη μονάδα email.policy)
@anchor{library/email policy email policy SMTP}@anchor{3d6d}
@deffn {Δεδομένα} email.policy.SMTP

Suitable for serializing messages in conformance with the email RFCs.
Like @code{default}, but with @code{linesep} set to @code{\r\n}, which is RFC
compliant.
@end deffn

@geindex SMTPUTF8 (στη μονάδα email.policy)
@anchor{library/email policy email policy SMTPUTF8}@anchor{1911}
@deffn {Δεδομένα} email.policy.SMTPUTF8

The same as @code{SMTP} except that @ref{217,,utf8} is @code{True}.
Useful for serializing messages to a message store without using encoded
words in the headers.  Should only be used for SMTP transmission if the
sender or recipient addresses have non-ASCII characters (the
@ref{120b,,smtplib.SMTP.send_message()} method handles this automatically).
@end deffn

@geindex HTTP (στη μονάδα email.policy)
@anchor{library/email policy email policy HTTP}@anchor{3d6e}
@deffn {Δεδομένα} email.policy.HTTP

Suitable for serializing headers with for use in HTTP traffic.  Like
@code{SMTP} except that @code{max_line_length} is set to @code{None} (unlimited).
@end deffn

@geindex strict (στη μονάδα email.policy)
@anchor{library/email policy email policy strict}@anchor{3d6f}
@deffn {Δεδομένα} email.policy.strict

Convenience instance.  The same as @code{default} except that
@code{raise_on_defect} is set to @code{True}.  This allows any policy to be made
strict by writing:

@example
somepolicy + policy.strict
@end example
@end deffn

With all of these @ref{1464,,EmailPolicies}, the effective API of
the email package is changed from the Python 3.2 API in the following ways:


@itemize *

@item 
Setting a header on a @ref{780,,Message} results in that
header being parsed and a header object created.

@item 
Fetching a header value from a @ref{780,,Message} results
in that header being parsed and a header object created and
returned.

@item 
Any header object, or any header that is refolded due to the
policy settings, is folded using an algorithm that fully implements the
RFC folding algorithms, including knowing where encoded words are required
and allowed.
@end itemize

From the application view, this means that any header obtained through the
@ref{216,,EmailMessage} is a header object with extra
attributes, whose string value is the fully decoded unicode value of the
header.  Likewise, a header may be assigned a new value, or a new header
created, using a unicode string, and the policy will take care of converting
the unicode string into the correct RFC encoded form.

The header objects and their attributes are described in
@ref{45,,headerregistry}.

@geindex Compat32 (κλάση σε email.policy)
@anchor{library/email policy email policy Compat32}@anchor{1461}
@deffn {Κλάση} email.policy.Compat32 (**kw)

This concrete @ref{1460,,Policy} is the backward compatibility policy.  It
replicates the behavior of the email package in Python 3.2.  The
@code{policy} module also defines an instance of this class,
@ref{105a,,compat32}, that is used as the default policy.  Thus the default
behavior of the email package is to maintain compatibility with Python 3.2.

The following attributes have values that are different from the
@ref{1460,,Policy} default:

@geindex mangle_from_ (ιδιότητα της email.policy.Compat32)
@anchor{library/email policy email policy Compat32 mangle_from_}@anchor{3d70}
@deffn {Ιδιότητα} mangle_from_

The default is @code{True}.
@end deffn

The class provides the following concrete implementations of the
abstract methods of @ref{1460,,Policy}:

@geindex header_source_parse() (μέθοδος της email.policy.Compat32)
@anchor{library/email policy email policy Compat32 header_source_parse}@anchor{1b2e}
@deffn {Μέθοδος} header_source_parse (sourcelines)

The name is parsed as everything up to the “@code{:}” and returned
unmodified.  The value is determined by stripping leading whitespace off
the remainder of the first line, joining all subsequent lines together,
and stripping any trailing carriage return or linefeed characters.
@end deffn

@geindex header_store_parse() (μέθοδος της email.policy.Compat32)
@anchor{library/email policy email policy Compat32 header_store_parse}@anchor{3d71}
@deffn {Μέθοδος} header_store_parse (name, value)

The name and value are returned unmodified.
@end deffn

@geindex header_fetch_parse() (μέθοδος της email.policy.Compat32)
@anchor{library/email policy email policy Compat32 header_fetch_parse}@anchor{3d72}
@deffn {Μέθοδος} header_fetch_parse (name, value)

If the value contains binary data, it is converted into a
@ref{1e55,,Header} object using the @code{unknown-8bit} charset.
Otherwise it is returned unmodified.
@end deffn

@geindex fold() (μέθοδος της email.policy.Compat32)
@anchor{library/email policy email policy Compat32 fold}@anchor{3d73}
@deffn {Μέθοδος} fold (name, value)

Headers are folded using the @ref{1e55,,Header} folding
algorithm, which preserves existing line breaks in the value, and wraps
each resulting line to the @code{max_line_length}.  Non-ASCII binary data are
CTE encoded using the @code{unknown-8bit} charset.
@end deffn

@geindex fold_binary() (μέθοδος της email.policy.Compat32)
@anchor{library/email policy email policy Compat32 fold_binary}@anchor{3d74}
@deffn {Μέθοδος} fold_binary (name, value)

Headers are folded using the @ref{1e55,,Header} folding
algorithm, which preserves existing line breaks in the value, and wraps
each resulting line to the @code{max_line_length}.  If @code{cte_type} is
@code{7bit}, non-ascii binary data is CTE encoded using the @code{unknown-8bit}
charset.  Otherwise the original source header is used, with its existing
line breaks and any (RFC invalid) binary data it may contain.
@end deffn
@end deffn

@geindex compat32 (στη μονάδα email.policy)
@anchor{library/email policy email policy compat32}@anchor{105a}
@deffn {Δεδομένα} email.policy.compat32

An instance of @ref{1461,,Compat32}, providing  backward compatibility with the
behavior of the email package in Python 3.2.

@cartouche
@quotation Σημείωση 
The @ref{105a,,compat32} policy should not be used as a policy for
@ref{216,,EmailMessage} objects, and should only be used
to serialize messages that were created using the @code{compat32}
policy.
@end quotation
@end cartouche
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node email errors Κλάσεις Εξαιρέσεων και Ελαττωμάτων,email headerregistry Custom Header Objects,email policy Policy Objects,email — An email and MIME handling package
@anchor{library/email errors doc}@anchor{3d75}@anchor{library/email errors email-errors-exception-and-defect-classes}@anchor{3d76}@anchor{library/email errors module-email errors}@anchor{42}@anchor{library/email errors translation-repo}@anchor{3d77}
@subsubsection @code{email.errors}: Κλάσεις Εξαιρέσεων και Ελαττωμάτων


@geindex module; email.errors

`Πηγαίος κώδικας:' Lib/email/errors.py@footnote{https://github.com/python/cpython/tree/main/Lib/email/errors.py}


__________________________________________________________________


The following exception classes are defined in the @code{email.errors} module:

@geindex MessageError
@anchor{library/email errors email errors MessageError}@anchor{3d78}
@deffn {Εξαίρεση} email.errors.MessageError

Αυτή είναι η βασική κλάση για όλες τις εξαιρέσεις που μπορεί να κάνει raise το module @ref{3e,,email}. Παράγεται από την τυπική κλάση @ref{d9e,,Exception} και δεν ορίζει επιπλέον μεθόδους.
@end deffn

@geindex MessageParseError
@anchor{library/email errors email errors MessageParseError}@anchor{3d79}
@deffn {Εξαίρεση} email.errors.MessageParseError

Αυτή είναι η βασική κλάση για τις εξαιρέσεις που γίνονται raise από την κλάση @ref{1546,,Parser}. Κληρονομεί από την @ref{3d78,,MessageError}. Αυτή η κλάση χρησιμοποιείται επίσης εσωτερικά από τον αναλυτή που χρησιμοποιείται από το @ref{45,,headerregistry}.
@end deffn

@geindex HeaderParseError
@anchor{library/email errors email errors HeaderParseError}@anchor{3d25}
@deffn {Εξαίρεση} email.errors.HeaderParseError

Γίνεται raise κάτω από ορισμένες συνθήκες σφάλματος κατά την ανάλυση των κεφαλίδων 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} ενός μηνύματος, αυτή η κλάση προέρχεται από την @ref{3d79,,MessageParseError}. Η μέθοδος @ref{3d24,,set_boundary()} θα κάνει raise αυτό το σφάλμα αν ο τύπος περιεχομένου είναι άγνωστος όταν καλείται η μέθοδος. Η @ref{1e55,,Header} μπορεί να κάνει raise αυτό το σφάλμα για ορισμένα σφάλματα αποκωδικοποίησης base64, καθώς και όταν επιχειρείται η δημιουργία μιας κεφαλίδας που φαίνεται να περιέχει ενσωματωμένη κεφαλίδα (δηλαδή υπάρχει μια γραμμή συνέχειας που δεν έχει προηγούμενο κενό διάστημα και μοιάζει με κεφαλίδα).
@end deffn

@geindex BoundaryError
@anchor{library/email errors email errors BoundaryError}@anchor{3d7a}
@deffn {Εξαίρεση} email.errors.BoundaryError

Έχει καταργηθεί και δεν χρησιμοποιείται πλέον.
@end deffn

@geindex MultipartConversionError
@anchor{library/email errors email errors MultipartConversionError}@anchor{3d7b}
@deffn {Εξαίρεση} email.errors.MultipartConversionError

Γίνεται raise εάν η μέθοδος @ref{3d36,,attach()} καλείται σε ένα στιγμιότυπο μιας κλάσης που προέρχεται από τη @ref{3d7c,,MIMENonMultipart} (π.χ. @ref{3d7d,,MIMEImage}). Η @ref{3d7b,,MultipartConversionError} κληρονομεί ταυτόχρονα από την @ref{3d78,,MessageError} και την ενσωματωμένη @ref{291,,TypeError}.
@end deffn

@geindex HeaderWriteError
@anchor{library/email errors email errors HeaderWriteError}@anchor{1910}
@deffn {Εξαίρεση} email.errors.HeaderWriteError

Γίνεται raise όταν παρουσιάζεται σφάλμα όταν το @ref{43,,generator} εξάγει κεφαλίδες.
@end deffn

@geindex MessageDefect
@anchor{library/email errors email errors MessageDefect}@anchor{3d60}
@deffn {Εξαίρεση} email.errors.MessageDefect

Αυτή είναι η βασική κλάση για όλα τα ελαττώματα που εντοπίζονται κατά την ανάλυση μηνυμάτων email. Είναι παράγωγη της @ref{277,,ValueError}.
@end deffn

@geindex HeaderDefect
@anchor{library/email errors email errors HeaderDefect}@anchor{3d7e}
@deffn {Εξαίρεση} email.errors.HeaderDefect

Αυτή είναι η βασική κλάση για όλα τα ελαττώματα που εντοπίζονται κατά την ανάλυση των κεφαλίδων email. Είναι παράγωγο της @ref{3d60,,MessageDefect}.
@end deffn

Ακολουθεί η λίστα με τα ελαττώματα που μπορεί να εντοπίσει η @ref{19a9,,FeedParser} κατά την ανάλυση των μηνυμάτων. Σημειώστε ότι τα ελαττώματα προστίθενται στο μήνυμα όπου βρέθηκε το πρόβλημα, οπότε για παράδειγμα, εάν ένα μήνυμα που είναι ένθετο μέσα σε ένα @code{multipart/alternative} είχε μια παραμορφωμένη κεφαλίδα, αυτό το ένθετο αντικείμενο μηνύματος θα είχε ένα ελάττωμα, αλλά τα μηνύματα που το περιέχουν όχι.

Όλες οι κλάσεις ελαττωμάτων είναι υποκλάσεις της @ref{3d60,,email.errors.MessageDefect}.

@geindex NoBoundaryInMultipartDefect
@anchor{library/email errors email errors NoBoundaryInMultipartDefect}@anchor{3d7f}
@deffn {Εξαίρεση} email.errors.NoBoundaryInMultipartDefect

Ένα μήνυμα ισχυριζόταν ότι ήταν πολυμερές, αλλά δεν είχε παράμετρο @code{boundary}.
@end deffn

@geindex StartBoundaryNotFoundDefect
@anchor{library/email errors email errors StartBoundaryNotFoundDefect}@anchor{3d80}
@deffn {Εξαίρεση} email.errors.StartBoundaryNotFoundDefect

Το όριο εκκίνησης που αναφέρεται στην κεφαλίδα @code{Content-Type} δεν βρέθηκε ποτέ.
@end deffn

@geindex CloseBoundaryNotFoundDefect
@anchor{library/email errors email errors CloseBoundaryNotFoundDefect}@anchor{3d81}
@deffn {Εξαίρεση} email.errors.CloseBoundaryNotFoundDefect

Βρέθηκε ένα όριο εκκίνησης, αλλά δεν βρέθηκε ποτέ αντίστοιχο όριο κλεισίματος.


Added in version 3.3.

@end deffn

@geindex FirstHeaderLineIsContinuationDefect
@anchor{library/email errors email errors FirstHeaderLineIsContinuationDefect}@anchor{3d82}
@deffn {Εξαίρεση} email.errors.FirstHeaderLineIsContinuationDefect

Το μήνυμα είχε μια γραμμή συνέχισης ως την πρώτη γραμμή κεφαλίδας.
@end deffn

@geindex MisplacedEnvelopeHeaderDefect
@anchor{library/email errors email errors MisplacedEnvelopeHeaderDefect}@anchor{3d83}
@deffn {Εξαίρεση} email.errors.MisplacedEnvelopeHeaderDefect

Βρέθηκε μια κεφαλίδα «Unix From» στη μέση ενός μπλοκ κεφαλίδων.
@end deffn

@geindex MissingHeaderBodySeparatorDefect
@anchor{library/email errors email errors MissingHeaderBodySeparatorDefect}@anchor{3d84}
@deffn {Εξαίρεση} email.errors.MissingHeaderBodySeparatorDefect

Βρέθηκε μια γραμμή κατά την ανάλυση των κεφαλίδων που δεν είχε αρχικό κενό αλλά δεν περιείχε “:”. Η ανάλυση συνεχίζεται στην περίπτωση που η γραμμή αντιπροσωπεύει την πρώτη γραμμή του σώματος.


Added in version 3.3.

@end deffn

@geindex MalformedHeaderDefect
@anchor{library/email errors email errors MalformedHeaderDefect}@anchor{3d85}
@deffn {Εξαίρεση} email.errors.MalformedHeaderDefect

Βρέθηκε μια κεφαλίδα που της έλειπε μια άνω τελεία, ή ήταν αλλιώς παραμορφωμένη.


Αποσύρθηκε στην έκδοση 3.3: Αυτό το σφάλμα δεν έχει χρησιμοποιηθεί εδώ και πολλές εκδόσεις της Python.

@end deffn

@geindex MultipartInvariantViolationDefect
@anchor{library/email errors email errors MultipartInvariantViolationDefect}@anchor{3d4c}
@deffn {Εξαίρεση} email.errors.MultipartInvariantViolationDefect

Ένα μήνυμα δήλωσε ότι είναι @code{multipart}, αλλά δεν βρέθηκαν υπομέρη. Σημειώστε ότι όταν ένα μήνυμα έχει αυτό το σφάλμα, η μέθοδος του @ref{3d29,,is_multipart()} μπορεί να επιστρέψει @code{False} ακόμα κι αν ο τύπος περιεχομένου του δηλώνει ότι είναι @code{multipart}.
@end deffn

@geindex InvalidBase64PaddingDefect
@anchor{library/email errors email errors InvalidBase64PaddingDefect}@anchor{3d86}
@deffn {Εξαίρεση} email.errors.InvalidBase64PaddingDefect

Όταν αποκωδικοποιείται ένα μπλοκ από base64 κωδικοποιημένα bytes, η προσθήκη padding δεν ήταν σωστή. Προστίθεται αρκετό padding για να πραγματοποιηθεί η αποκωδικοποίηση, αλλά τα αποκωδικοποιημένα bytes που προκύπτουν μπορεί να είναι άκυρα.
@end deffn

@geindex InvalidBase64CharactersDefect
@anchor{library/email errors email errors InvalidBase64CharactersDefect}@anchor{3d87}
@deffn {Εξαίρεση} email.errors.InvalidBase64CharactersDefect

Όταν αποκωδικοποιείται ένα μπλοκ από base64 κωδικοποιημένα bytes, συναντήθηκαν χαρακτήρες εκτός του αλφαβήτου base64. Οι χαρακτήρες αγνοούνται, αλλά τα αποκωδικοποιημένα bytes που προκύπτουν μπορεί να είναι άκυρα.
@end deffn

@geindex InvalidBase64LengthDefect
@anchor{library/email errors email errors InvalidBase64LengthDefect}@anchor{3d88}
@deffn {Εξαίρεση} email.errors.InvalidBase64LengthDefect

Όταν αποκωδικοποιείται ένα μπλοκ από base64 κωδικοποιημένα bytes, ο αριθμός των χαρακτήρων base64 χωρίς συμπλήρωμα ήταν άκυρος (1 παραπάνω από ένα πολλαπλάσιο του 4). Το κωδικοποιημένο μπλοκ διατηρήθηκε ως έχει.
@end deffn

@geindex InvalidDateDefect
@anchor{library/email errors email errors InvalidDateDefect}@anchor{3d89}
@deffn {Εξαίρεση} email.errors.InvalidDateDefect

Όταν αποκωδικοποιείται ένα άκυρο ή μη αναγνώσιμο πεδίο ημερομηνίας. Η αρχική τιμή διατηρείται ως έχει.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node email headerregistry Custom Header Objects,email contentmanager Managing MIME Content,email errors Κλάσεις Εξαιρέσεων και Ελαττωμάτων,email — An email and MIME handling package
@anchor{library/email headerregistry doc}@anchor{3d8a}@anchor{library/email headerregistry email-headerregistry-custom-header-objects}@anchor{3d8b}@anchor{library/email headerregistry module-email headerregistry}@anchor{45}@anchor{library/email headerregistry translation-repo}@anchor{3d8c}
@subsubsection @code{email.headerregistry}: Custom Header Objects


@geindex module; email.headerregistry

`Source code:' Lib/email/headerregistry.py@footnote{https://github.com/python/cpython/tree/main/Lib/email/headerregistry.py}


__________________________________________________________________



Added in version 3.6: @footnote{
Originally added in 3.3 as a @ref{13ea,,provisional module}
}


Headers are represented by customized subclasses of @ref{1df,,str}.  The
particular class used to represent a given header is determined by the
@ref{3d66,,header_factory} of the @ref{52,,policy} in
effect when the headers are created.  This section documents the particular
@code{header_factory} implemented by the email package for handling 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}
compliant email messages, which not only provides customized header objects for
various header types, but also provides an extension mechanism for applications
to add their own custom header types.

When using any of the policy objects derived from
@ref{1464,,EmailPolicy}, all headers are produced by
@ref{3d8d,,HeaderRegistry} and have @ref{3d11,,BaseHeader} as their last base
class.  Each header class has an additional base class that is determined by
the type of the header.  For example, many headers have the class
@ref{3d8e,,UnstructuredHeader} as their other base class.  The specialized second
class for a header is determined by the name of the header, using a lookup
table stored in the @code{HeaderRegistry}.  All of this is managed
transparently for the typical application program, but interfaces are provided
for modifying the default behavior for use by more complex applications.

The sections below first document the header base classes and their attributes,
followed by the API for modifying the behavior of @ref{3d8d,,HeaderRegistry}, and
finally the support classes used to represent the data parsed from structured
headers.

@geindex BaseHeader (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry BaseHeader}@anchor{3d11}
@deffn {Κλάση} email.headerregistry.BaseHeader (name, value)

`name' and `value' are passed to @code{BaseHeader} from the
@ref{3d66,,header_factory} call.  The string value of
any header object is the `value' fully decoded to unicode.

This base class defines the following read-only properties:

@geindex name (ιδιότητα της email.headerregistry.BaseHeader)
@anchor{library/email headerregistry email headerregistry BaseHeader name}@anchor{3d8f}
@deffn {Ιδιότητα} name

The name of the header (the portion of the field before the “:”).  This
is exactly the value passed in the
@ref{3d66,,header_factory} call for `name'; that
is, case is preserved.
@end deffn

@geindex defects (ιδιότητα της email.headerregistry.BaseHeader)
@anchor{library/email headerregistry email headerregistry BaseHeader defects}@anchor{3d90}
@deffn {Ιδιότητα} defects

A tuple of @ref{3d7e,,HeaderDefect} instances reporting any
RFC compliance problems found during parsing.  The email package tries to
be complete about detecting compliance issues.  See the @ref{42,,errors}
module for a discussion of the types of defects that may be reported.
@end deffn

@geindex max_count (ιδιότητα της email.headerregistry.BaseHeader)
@anchor{library/email headerregistry email headerregistry BaseHeader max_count}@anchor{3d69}
@deffn {Ιδιότητα} max_count

The maximum number of headers of this type that can have the same
@code{name}.  A value of @code{None} means unlimited.  The @code{BaseHeader} value
for this attribute is @code{None}; it is expected that specialized header
classes will override this value as needed.
@end deffn

@code{BaseHeader} also provides the following method, which is called by the
email library code and should not in general be called by application
programs:

@geindex fold() (μέθοδος της email.headerregistry.BaseHeader)
@anchor{library/email headerregistry email headerregistry BaseHeader fold}@anchor{3d91}
@deffn {Μέθοδος} fold (*, policy)

Return a string containing @ref{3d5b,,linesep}
characters as required to correctly fold the header according to
`policy'.  A @ref{3d53,,cte_type} of @code{8bit} will be
treated as if it were @code{7bit}, since headers may not contain arbitrary
binary data.  If @ref{217,,utf8} is @code{False},
non-ASCII data will be 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} encoded.
@end deffn

@code{BaseHeader} by itself cannot be used to create a header object.  It
defines a protocol that each specialized header cooperates with in order to
produce the header object.  Specifically, @code{BaseHeader} requires that
the specialized class provide a @ref{69a,,classmethod()} named @code{parse}.  This
method is called as follows:

@example
parse(string, kwds)
@end example

@code{kwds} is a dictionary containing one pre-initialized key, @code{defects}.
@code{defects} is an empty list.  The parse method should append any detected
defects to this list.  On return, the @code{kwds} dictionary `must' contain
values for at least the keys @code{decoded} and @code{defects}.  @code{decoded}
should be the string value for the header (that is, the header value fully
decoded to unicode).  The parse method should assume that `string' may
contain content-transfer-encoded parts, but should correctly handle all valid
unicode characters as well so that it can parse un-encoded header values.

@code{BaseHeader}’s @code{__new__} then creates the header instance, and calls its
@code{init} method.  The specialized class only needs to provide an @code{init}
method if it wishes to set additional attributes beyond those provided by
@code{BaseHeader} itself.  Such an @code{init} method should look like this:

@example
def init(self, /, *args, **kw):
    self._myattr = kw.pop('myattr')
    super().init(*args, **kw)
@end example

That is, anything extra that the specialized class puts in to the @code{kwds}
dictionary should be removed and handled, and the remaining contents of
@code{kw} (and @code{args}) passed to the @code{BaseHeader} @code{init} method.
@end deffn

@geindex UnstructuredHeader (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry UnstructuredHeader}@anchor{3d8e}
@deffn {Κλάση} email.headerregistry.UnstructuredHeader

An «unstructured» header is the default type of header in 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}.
Any header that does not have a specified syntax is treated as
unstructured.  The classic example of an unstructured header is the
@code{Subject} header.

In 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}, an unstructured header is a run of arbitrary text in the
ASCII character set.  
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html}, however, has an 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} compatible
mechanism for encoding non-ASCII text as ASCII characters within a header
value.  When a `value' containing encoded words is passed to the
constructor, the @code{UnstructuredHeader} parser converts such encoded words
into unicode, following the 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} rules for unstructured text.  The
parser uses heuristics to attempt to decode certain non-compliant encoded
words.  Defects are registered in such cases, as well as defects for issues
such as invalid characters within the encoded words or the non-encoded text.

This header type provides no additional attributes.
@end deffn

@geindex DateHeader (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry DateHeader}@anchor{3d92}
@deffn {Κλάση} email.headerregistry.DateHeader

@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} specifies a very specific format for dates within email headers.
The @code{DateHeader} parser recognizes that date format, as well as
recognizing a number of variant forms that are sometimes found «in the
wild».

This header type provides the following additional attributes:

@geindex datetime (ιδιότητα της email.headerregistry.DateHeader)
@anchor{library/email headerregistry email headerregistry DateHeader datetime}@anchor{3d93}
@deffn {Ιδιότητα} datetime

If the header value can be recognized as a valid date of one form or
another, this attribute will contain a @ref{6e7,,datetime}
instance representing that date.  If the timezone of the input date is
specified as @code{-0000} (indicating it is in UTC but contains no
information about the source timezone), then @ref{3d93,,datetime} will be a
naive @code{datetime}.  If a specific timezone offset is
found (including @code{+0000}), then @code{datetime} will contain an aware
@code{datetime} that uses @ref{146c,,datetime.timezone} to record the timezone
offset.
@end deffn

The @code{decoded} value of the header is determined by formatting the
@code{datetime} according to the 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} rules; that is, it is set to:

@example
email.utils.format_datetime(self.datetime)
@end example

When creating a @code{DateHeader}, `value' may be
@ref{6e7,,datetime} instance.  This means, for example, that
the following code is valid and does what one would expect:

@example
msg['Date'] = datetime(2011, 7, 15, 21)
@end example

Because this is a naive @code{datetime} it will be interpreted as a UTC
timestamp, and the resulting value will have a timezone of @code{-0000}.  Much
more useful is to use the @ref{56f,,localtime()} function from the
@ref{53,,utils} module:

@example
msg['Date'] = utils.localtime()
@end example

This example sets the date header to the current time and date using
the current timezone offset.
@end deffn

@geindex AddressHeader (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry AddressHeader}@anchor{3d94}
@deffn {Κλάση} email.headerregistry.AddressHeader

Address headers are one of the most complex structured header types.
The @code{AddressHeader} class provides a generic interface to any address
header.

This header type provides the following additional attributes:

@geindex groups (ιδιότητα της email.headerregistry.AddressHeader)
@anchor{library/email headerregistry email headerregistry AddressHeader groups}@anchor{3d95}
@deffn {Ιδιότητα} groups

A tuple of @ref{3d96,,Group} objects encoding the
addresses and groups found in the header value.  Addresses that are
not part of a group are represented in this list as single-address
@code{Groups} whose @ref{3d97,,display_name} is @code{None}.
@end deffn

@geindex addresses (ιδιότητα της email.headerregistry.AddressHeader)
@anchor{library/email headerregistry email headerregistry AddressHeader addresses}@anchor{3d98}
@deffn {Ιδιότητα} addresses

A tuple of @ref{1912,,Address} objects encoding all
of the individual addresses from the header value.  If the header value
contains any groups, the individual addresses from the group are included
in the list at the point where the group occurs in the value (that is,
the list of addresses is «flattened» into a one dimensional list).
@end deffn

The @code{decoded} value of the header will have all encoded words decoded to
unicode.  @ref{55,,idna} encoded domain names are also decoded to
unicode.  The @code{decoded} value is set by @ref{2847,,joining} the
@ref{1df,,str} value of the elements of the @code{groups} attribute with @code{',
'}.

A list of @ref{1912,,Address} and @ref{3d96,,Group} objects in any combination
may be used to set the value of an address header.  @code{Group} objects whose
@code{display_name} is @code{None} will be interpreted as single addresses, which
allows an address list to be copied with groups intact by using the list
obtained from the @code{groups} attribute of the source header.
@end deffn

@geindex SingleAddressHeader (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry SingleAddressHeader}@anchor{3d99}
@deffn {Κλάση} email.headerregistry.SingleAddressHeader

A subclass of @ref{3d94,,AddressHeader} that adds one
additional attribute:

@geindex address (ιδιότητα της email.headerregistry.SingleAddressHeader)
@anchor{library/email headerregistry email headerregistry SingleAddressHeader address}@anchor{3d9a}
@deffn {Ιδιότητα} address

The single address encoded by the header value.  If the header value
actually contains more than one address (which would be a violation of
the RFC under the default @ref{52,,policy}), accessing this attribute
will result in a @ref{277,,ValueError}.
@end deffn
@end deffn

Many of the above classes also have a @code{Unique} variant (for example,
@code{UniqueUnstructuredHeader}).  The only difference is that in the @code{Unique}
variant, @ref{3d69,,max_count} is set to 1.

@geindex MIMEVersionHeader (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry MIMEVersionHeader}@anchor{3d9b}
@deffn {Κλάση} email.headerregistry.MIMEVersionHeader

There is really only one valid value for the @code{MIME-Version}
header, and that is @code{1.0}.  For future proofing, this header class
supports other valid version numbers.  If a version number has a valid value
per 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}, then the header object will have non-@code{None} values for
the following attributes:

@geindex version (ιδιότητα της email.headerregistry.MIMEVersionHeader)
@anchor{library/email headerregistry email headerregistry MIMEVersionHeader version}@anchor{3d9c}
@deffn {Ιδιότητα} version

The version number as a string, with any whitespace and/or comments
removed.
@end deffn

@geindex major (ιδιότητα της email.headerregistry.MIMEVersionHeader)
@anchor{library/email headerregistry email headerregistry MIMEVersionHeader major}@anchor{3d9d}
@deffn {Ιδιότητα} major

The major version number as an integer
@end deffn

@geindex minor (ιδιότητα της email.headerregistry.MIMEVersionHeader)
@anchor{library/email headerregistry email headerregistry MIMEVersionHeader minor}@anchor{3d9e}
@deffn {Ιδιότητα} minor

The minor version number as an integer
@end deffn
@end deffn

@geindex ParameterizedMIMEHeader (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry ParameterizedMIMEHeader}@anchor{3d9f}
@deffn {Κλάση} email.headerregistry.ParameterizedMIMEHeader

MIME headers all start with the prefix “Content-”.  Each specific header has
a certain value, described under the class for that header.  Some can
also take a list of supplemental parameters, which have a common format.
This class serves as a base for all the MIME headers that take parameters.

@geindex params (ιδιότητα της email.headerregistry.ParameterizedMIMEHeader)
@anchor{library/email headerregistry email headerregistry ParameterizedMIMEHeader params}@anchor{3d1f}
@deffn {Ιδιότητα} params

A dictionary mapping parameter names to parameter values.


Άλλαξε στην έκδοση 3.15: It is now a @ref{182,,frozendict} instead of a
@ref{189,,types.MappingProxyType}.

@end deffn
@end deffn

@geindex ContentTypeHeader (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry ContentTypeHeader}@anchor{3da0}
@deffn {Κλάση} email.headerregistry.ContentTypeHeader

A @ref{3d9f,,ParameterizedMIMEHeader} class that handles the
@code{Content-Type} header.

@geindex content_type (ιδιότητα της email.headerregistry.ContentTypeHeader)
@anchor{library/email headerregistry email headerregistry ContentTypeHeader content_type}@anchor{3da1}
@deffn {Ιδιότητα} content_type

The content type string, in the form @code{maintype/subtype}.
@end deffn

@geindex maintype (ιδιότητα της email.headerregistry.ContentTypeHeader)
@anchor{library/email headerregistry email headerregistry ContentTypeHeader maintype}@anchor{3da2}
@deffn {Ιδιότητα} maintype
@end deffn

@geindex subtype (ιδιότητα της email.headerregistry.ContentTypeHeader)
@anchor{library/email headerregistry email headerregistry ContentTypeHeader subtype}@anchor{3da3}
@deffn {Ιδιότητα} subtype
@end deffn
@end deffn

@geindex ContentDispositionHeader (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry ContentDispositionHeader}@anchor{3da4}
@deffn {Κλάση} email.headerregistry.ContentDispositionHeader

A @ref{3d9f,,ParameterizedMIMEHeader} class that handles the
@code{Content-Disposition} header.

@geindex content_disposition (ιδιότητα της email.headerregistry.ContentDispositionHeader)
@anchor{library/email headerregistry email headerregistry ContentDispositionHeader content_disposition}@anchor{3da5}
@deffn {Ιδιότητα} content_disposition

@code{inline} and @code{attachment} are the only valid values in common use.
@end deffn
@end deffn

@geindex ContentTransferEncodingHeader (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry ContentTransferEncodingHeader}@anchor{3da6}
@deffn {Κλάση} email.headerregistry.ContentTransferEncodingHeader

Handles the @code{Content-Transfer-Encoding} header.

@geindex cte (ιδιότητα της email.headerregistry.ContentTransferEncodingHeader)
@anchor{library/email headerregistry email headerregistry ContentTransferEncodingHeader cte}@anchor{3da7}
@deffn {Ιδιότητα} cte

Valid values are @code{7bit}, @code{8bit}, @code{base64}, and
@code{quoted-printable}.  See 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} for more information.
@end deffn
@end deffn

@geindex HeaderRegistry (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry HeaderRegistry}@anchor{3d8d}
@deffn {Κλάση} email.headerregistry.HeaderRegistry (base_class=BaseHeader, default_class=UnstructuredHeader, use_default_map=True)

This is the factory used by @ref{1464,,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{184e,,__bases__} list.

The default mappings are:

@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} has the following methods:

@geindex map_to_type() (μέθοδος της email.headerregistry.HeaderRegistry)
@anchor{library/email headerregistry email headerregistry HeaderRegistry map_to_type}@anchor{3da8}
@deffn {Μέθοδος} map_to_type (self, name, cls)

`name' is the name of the header to be mapped.  It will be converted to
lower case in the registry.  `cls' is the specialized class to be used,
along with `base_class', to create the class used to instantiate headers
that match `name'.
@end deffn

@geindex __getitem__() (μέθοδος της email.headerregistry.HeaderRegistry)
@anchor{library/email headerregistry email headerregistry HeaderRegistry __getitem__}@anchor{3da9}
@deffn {Μέθοδος} __getitem__ (name)

Construct and return a class to handle creating a `name' header.
@end deffn

@geindex __call__() (μέθοδος της email.headerregistry.HeaderRegistry)
@anchor{library/email headerregistry email headerregistry HeaderRegistry __call__}@anchor{3daa}
@deffn {Μέθοδος} __call__ (name, value)

Retrieves the specialized header associated with `name' from the
registry (using `default_class' if `name' does not appear in the
registry) and composes it with `base_class' to produce a class,
calls the constructed class’s constructor, passing it the same
argument list, and finally returns the class instance created thereby.
@end deffn
@end deffn

The following classes are the classes used to represent data parsed from
structured headers and can, in general, be used by an application program to
construct structured values to assign to specific headers.

@geindex Address (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry Address}@anchor{1912}
@deffn {Κλάση} email.headerregistry.Address (display_name='@w{'}, username='@w{'}, domain='@w{'}, addr_spec=None)

The class used to represent an email address.  The general form of an
address is:

@example
[display_name] <username@@domain>
@end example

or:

@example
username@@domain
@end example

where each part must conform to specific syntax rules spelled out in
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}.

As a convenience `addr_spec' can be specified instead of `username' and
`domain', in which case `username' and `domain' will be parsed from the
`addr_spec'.  An `addr_spec' must be a properly RFC quoted string; if it is
not @code{Address} will raise an error.  Unicode characters are allowed and
will be property encoded when serialized.  However, per the RFCs, unicode is
`not' allowed in the username portion of the address.

@geindex display_name (ιδιότητα της email.headerregistry.Address)
@anchor{library/email headerregistry email headerregistry Address display_name}@anchor{3dab}
@deffn {Ιδιότητα} display_name

The display name portion of the address, if any, with all quoting
removed.  If the address does not have a display name, this attribute
will be an empty string.
@end deffn

@geindex username (ιδιότητα της email.headerregistry.Address)
@anchor{library/email headerregistry email headerregistry Address username}@anchor{3dac}
@deffn {Ιδιότητα} username

The @code{username} portion of the address, with all quoting removed.
@end deffn

@geindex domain (ιδιότητα της email.headerregistry.Address)
@anchor{library/email headerregistry email headerregistry Address domain}@anchor{3dad}
@deffn {Ιδιότητα} domain

The @code{domain} portion of the address.
@end deffn

@geindex addr_spec (ιδιότητα της email.headerregistry.Address)
@anchor{library/email headerregistry email headerregistry Address addr_spec}@anchor{3dae}
@deffn {Ιδιότητα} addr_spec

The @code{username@@domain} portion of the address, correctly quoted
for use as a bare address (the second form shown above).  This
attribute is not mutable.
@end deffn

@geindex __str__() (μέθοδος της email.headerregistry.Address)
@anchor{library/email headerregistry email headerregistry Address __str__}@anchor{3daf}
@deffn {Μέθοδος} __str__ ()

The @code{str} value of the object is the address quoted according to
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} rules, but with no Content Transfer Encoding of any non-ASCII
characters.
@end deffn

To support SMTP (
@geindex RFC; RFC 5321
RFC 5321@footnote{https://datatracker.ietf.org/doc/html/rfc5321.html}), @code{Address} handles one special case: if
@code{username} and @code{domain} are both the empty string (or @code{None}), then
the string value of the @code{Address} is @code{<>}.
@end deffn

@geindex Group (κλάση σε email.headerregistry)
@anchor{library/email headerregistry email headerregistry Group}@anchor{3d96}
@deffn {Κλάση} email.headerregistry.Group (display_name=None, addresses=None)

The class used to represent an address group.  The general form of an
address group is:

@example
display_name: [address-list];
@end example

As a convenience for processing lists of addresses that consist of a mixture
of groups and single addresses, a @code{Group} may also be used to represent
single addresses that are not part of a group by setting `display_name' to
@code{None} and providing a list of the single address as `addresses'.

@geindex display_name (ιδιότητα της email.headerregistry.Group)
@anchor{library/email headerregistry email headerregistry Group display_name}@anchor{3d97}
@deffn {Ιδιότητα} display_name

The @code{display_name} of the group.  If it is @code{None} and there is
exactly one @code{Address} in @code{addresses}, then the @code{Group} represents a
single address that is not in a group.
@end deffn

@geindex addresses (ιδιότητα της email.headerregistry.Group)
@anchor{library/email headerregistry email headerregistry Group addresses}@anchor{3db0}
@deffn {Ιδιότητα} addresses

A possibly empty tuple of @ref{1912,,Address} objects representing the
addresses in the group.
@end deffn

@geindex __str__() (μέθοδος της email.headerregistry.Group)
@anchor{library/email headerregistry email headerregistry Group __str__}@anchor{3db1}
@deffn {Μέθοδος} __str__ ()

The @code{str} value of a @code{Group} is formatted according to 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html},
but with no Content Transfer Encoding of any non-ASCII characters.  If
@code{display_name} is none and there is a single @code{Address} in the
@code{addresses} list, the @code{str} value will be the same as the @code{str} of
that single @code{Address}.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node email contentmanager Managing MIME Content,email Examples,email headerregistry Custom Header Objects,email — An email and MIME handling package
@anchor{library/email contentmanager doc}@anchor{3db2}@anchor{library/email contentmanager email-contentmanager-managing-mime-content}@anchor{3db3}@anchor{library/email contentmanager module-email contentmanager}@anchor{40}@anchor{library/email contentmanager translation-repo}@anchor{3db4}
@subsubsection @code{email.contentmanager}: Managing MIME Content


@geindex module; email.contentmanager

`Source code:' Lib/email/contentmanager.py@footnote{https://github.com/python/cpython/tree/main/Lib/email/contentmanager.py}


__________________________________________________________________



Added in version 3.6: @footnote{
Originally added in 3.4 as a @ref{13ea,,provisional module}
}


@geindex ContentManager (κλάση σε email.contentmanager)
@anchor{library/email contentmanager email contentmanager ContentManager}@anchor{3db5}
@deffn {Κλάση} email.contentmanager.ContentManager

Base class for content managers.  Provides the standard registry mechanisms
to register converters between MIME content and other representations, as
well as the @code{get_content} and @code{set_content} dispatch methods.

@geindex get_content() (μέθοδος της email.contentmanager.ContentManager)
@anchor{library/email contentmanager email contentmanager ContentManager get_content}@anchor{3d30}
@deffn {Μέθοδος} get_content (msg, *args, **kw)

Look up a handler function based on the @code{mimetype} of `msg' (see next
paragraph), call it, passing through all arguments, and return the result
of the call.  The expectation is that the handler will extract the
payload from `msg' and return an object that encodes information about
the extracted data.

To find the handler, look for the following keys in the registry,
stopping with the first one found:


@itemize *

@item 
the string representing the full MIME type (@code{maintype/subtype})

@item 
the string representing the @code{maintype}

@item 
the empty string
@end itemize

If none of these keys produce a handler, raise a @ref{7df,,KeyError} for the
full MIME type.
@end deffn

@geindex set_content() (μέθοδος της email.contentmanager.ContentManager)
@anchor{library/email contentmanager email contentmanager ContentManager set_content}@anchor{3d31}
@deffn {Μέθοδος} set_content (msg, obj, *args, **kw)

If the @code{maintype} is @code{multipart}, raise a @ref{291,,TypeError}; otherwise
look up a handler function based on the type of `obj' (see next
paragraph), call @ref{3d3a,,clear_content()} on the
`msg', and call the handler function, passing through all arguments.  The
expectation is that the handler will transform and store `obj' into
`msg', possibly making other changes to `msg' as well, such as adding
various MIME headers to encode information needed to interpret the stored
data.

To find the handler, obtain the type of `obj' (@code{typ = type(obj)}), and
look for the following keys in the registry, stopping with the first one
found:


@itemize *

@item 
the type itself (@code{typ})

@item 
the type’s fully qualified name (@code{typ.__module__ + '.' +
typ.__qualname__}).

@item 
the type’s @ref{2565,,qualname} (@code{typ.__qualname__})

@item 
the type’s @ref{184d,,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{1afd,,MRO} (@ref{2569,,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{7df,,KeyError} for the fully
qualified name of the type.

Also add a @code{MIME-Version} header if one is not present (see
also @ref{12e5,,MIMEPart}).
@end deffn

@geindex add_get_handler() (μέθοδος της email.contentmanager.ContentManager)
@anchor{library/email contentmanager email contentmanager ContentManager add_get_handler}@anchor{3db6}
@deffn {Μέθοδος} add_get_handler (key, handler)

Record the function `handler' as the handler for `key'.  For the possible
values of `key', see @ref{3db7,,get_content()}.
@end deffn

@geindex add_set_handler() (μέθοδος της email.contentmanager.ContentManager)
@anchor{library/email contentmanager email contentmanager ContentManager add_set_handler}@anchor{3db8}
@deffn {Μέθοδος} add_set_handler (typekey, handler)

Record `handler' as the function to call when an object of a type
matching `typekey' is passed to @ref{3db9,,set_content()}.  For the possible
values of `typekey', see @code{set_content()}.
@end deffn
@end deffn

@menu
* Content Manager Instances:: 

@end menu

@node Content Manager Instances,,,email contentmanager Managing MIME Content
@anchor{library/email contentmanager content-manager-instances}@anchor{3dba}
@subsubsection Content Manager Instances


Currently the email package provides only one concrete content manager,
@ref{3d67,,raw_data_manager}, although more may be added in the future.
@code{raw_data_manager} is the
@ref{12e6,,content_manager} provided by
@ref{1464,,EmailPolicy} and its derivatives.

@geindex raw_data_manager (στη μονάδα email.contentmanager)
@anchor{library/email contentmanager email contentmanager raw_data_manager}@anchor{3d67}
@deffn {Δεδομένα} email.contentmanager.raw_data_manager

This content manager provides only a minimum interface beyond that provided
by @ref{780,,Message} itself:  it deals only with text, raw
byte strings, and @code{Message} objects.  Nevertheless, it
provides significant advantages compared to the base API: @code{get_content} on
a text part will return a unicode string without the application needing to
manually decode it, @code{set_content} provides a rich set of options for
controlling the headers added to a part and controlling the content transfer
encoding, and it enables the use of the various @code{add_} methods, thereby
simplifying the creation of multipart messages.

@geindex get_content() (στη μονάδα email.contentmanager)
@anchor{library/email contentmanager email contentmanager get_content}@anchor{3db7}
@deffn {Μέθοδος} email.contentmanager.get_content (msg, errors='replace')

Return the payload of the part as either a string (for @code{text} parts), an
@ref{216,,EmailMessage} object (for @code{message/rfc822}
parts), or a @code{bytes} object (for all other non-multipart types).  Raise
a @ref{7df,,KeyError} if called on a @code{multipart}.  If the part is a
@code{text} part and `errors' is specified, use it as the error handler when
decoding the payload to unicode.  The default error handler is
@code{replace}.
@end deffn

@geindex set_content() (στη μονάδα email.contentmanager)
@anchor{library/email contentmanager email contentmanager set_content}@anchor{3db9}
@deffn {Μέθοδος} email.contentmanager.set_content (msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

@deffnx {Μέθοδος} email.contentmanager.set_content (msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)

@deffnx {Μέθοδος} email.contentmanager.set_content (msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

Add headers and payload to `msg':

Add a @code{Content-Type} header with a @code{maintype/subtype}
value.


@itemize *

@item 
For @code{str}, set the MIME @code{maintype} to @code{text}, and set the
subtype to `subtype' if it is specified, or @code{plain} if it is not.

@item 
For @code{bytes}, use the specified `maintype' and `subtype', or
raise a @ref{291,,TypeError} if they are not specified.

@item 
For @ref{216,,EmailMessage} objects, set the maintype
to @code{message}, and set the subtype to `subtype' if it is
specified or @code{rfc822} if it is not.  If `subtype' is
@code{partial}, raise an error (@code{bytes} objects must be used to
construct @code{message/partial} parts).
@end itemize

If `charset' is provided (which is valid only for @code{str}), encode the
string to bytes using the specified character set.  The default is
@code{utf-8}.  If the specified `charset' is a known alias for a standard
MIME charset name, use the standard charset instead.

If `cte' is set, encode the payload using the specified content transfer
encoding, and set the @code{Content-Transfer-Encoding} header to
that value.  Possible values for `cte' are @code{quoted-printable},
@code{base64}, @code{7bit}, @code{8bit}, and @code{binary}.  If the input cannot be
encoded in the specified encoding (for example, specifying a `cte' of
@code{7bit} for an input that contains non-ASCII values), raise a
@ref{277,,ValueError}.


@itemize *

@item 
For @code{str} objects, if `cte' is not set use heuristics to
determine the most compact encoding.  Prior to encoding,
@ref{15fb,,str.splitlines()} is used to normalize all line boundaries,
ensuring that each line of the payload is terminated by the
current policy’s @ref{3d5b,,linesep} property
(even if the original string did not end with one).

@item 
For @code{bytes} objects, `cte' is taken to be base64 if not set,
and the aforementioned newline translation is not performed.

@item 
For @ref{216,,EmailMessage}, per 
@geindex RFC; RFC 2046
RFC 2046@footnote{https://datatracker.ietf.org/doc/html/rfc2046.html}, raise
an error if a `cte' of @code{quoted-printable} or @code{base64} is
requested for `subtype' @code{rfc822}, and for any `cte' other than
@code{7bit} for `subtype' @code{external-body}.  For
@code{message/rfc822}, use @code{8bit} if `cte' is not specified.  For
all other values of `subtype', use @code{7bit}.
@end itemize

@cartouche
@quotation Σημείωση 
A `cte' of @code{binary} does not actually work correctly yet.
The @code{EmailMessage} object as modified by @code{set_content} is
correct, but @ref{1578,,BytesGenerator} does not
serialize it correctly.
@end quotation
@end cartouche

If `disposition' is set, use it as the value of the
@code{Content-Disposition} header.  If not specified, and
`filename' is specified, add the header with the value @code{attachment}.
If `disposition' is not specified and `filename' is also not specified,
do not add the header.  The only valid values for `disposition' are
@code{attachment} and @code{inline}.

If `filename' is specified, use it as the value of the @code{filename}
parameter of the @code{Content-Disposition} header.

If `cid' is specified, add a @code{Content-ID} header with
`cid' as its value.

If `params' is specified, iterate its @code{items} method and use the
resulting @code{(key, value)} pairs to set additional parameters on the
@code{Content-Type} header.

If `headers' is specified and is a list of strings of the form
@code{headername: headervalue} or a list of @code{header} objects
(distinguished from strings by having a @code{name} attribute), add the
headers to `msg'.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node email Examples,email message Message Representing an email message using the compat32 API,email contentmanager Managing MIME Content,email — An email and MIME handling package
@anchor{library/email examples doc}@anchor{3dbb}@anchor{library/email examples email-examples}@anchor{12e7}@anchor{library/email examples id1}@anchor{3dbc}@anchor{library/email examples translation-repo}@anchor{3dbd}
@subsubsection @code{email}: Examples


Here are a few examples of how to use the @ref{3e,,email} package to read, write,
and send simple email messages, as well as more complex MIME messages.

First, let’s see how to create and send a simple text message (both the
text content and the addresses may contain unicode characters):

@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

Parsing 
@geindex RFC; RFC 822
RFC 822@footnote{https://datatracker.ietf.org/doc/html/rfc822.html} headers can easily be done by the using the classes
from the @ref{51,,parser} module:

@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

Here’s an example of how to send a MIME message containing a bunch of family
pictures that may be residing in a directory:

@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

Here’s an example of how to send the entire contents of a directory as an email
message: @footnote{
Thanks to Matthew Dixon Cowles for the original inspiration and examples.
}

@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

Here’s an example of how to unpack a MIME message like the one
above, into a directory of files:

@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

Here’s an example of how to create an HTML message with an alternative plain
text version.  To make things a bit more interesting, we include a related
image in the html part, and we save a copy of what we are going to send to
disk, as well as sending it.

@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

If we were sent the message from the last example, here is one way we could
process it:

@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

Up to the prompt, the output from the above is:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

Legacy API:

@node email message Message Representing an email message using the compat32 API,email mime Creating email and MIME objects from scratch,email Examples,email — An email and MIME handling package
@anchor{library/email compat32-message doc}@anchor{3dbe}@anchor{library/email compat32-message compat32-message}@anchor{3d02}@anchor{library/email compat32-message email-message-message-representing-an-email-message-using-the-compat32-api}@anchor{3dbf}@anchor{library/email compat32-message translation-repo}@anchor{3dc0}
@subsubsection @code{email.message.Message}: Representing an email message using the @code{compat32} API


The @ref{780,,Message} class is very similar to the
@ref{216,,EmailMessage} class, without the methods added by that
class, and with the default behavior of certain other methods being slightly
different.  We also document here some methods that, while supported by the
@code{EmailMessage} class, are not recommended unless you are
dealing with legacy code.

The philosophy and structure of the two classes is otherwise the same.

This document describes the behavior under the default (for @ref{780,,Message})
policy @ref{1461,,Compat32}.  If you are going to use another policy,
you should be using the @ref{216,,EmailMessage} class instead.

An email message consists of `headers' and a `payload'.  Headers must be
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} style names and values, where the field name and value are
separated by a colon.  The colon is not part of either the field name or the
field value.  The payload may be a simple text message, or a binary object, or
a structured sequence of sub-messages each with their own set of headers and
their own payload.  The latter type of payload is indicated by the message
having a MIME type such as @code{multipart/*} or
@code{message/rfc822}.

The conceptual model provided by a @ref{780,,Message} object is that of an
ordered dictionary of headers with additional methods for accessing both
specialized information from the headers, for accessing the payload, for
generating a serialized version of the message, and for recursively walking
over the object tree.  Note that duplicate headers are supported but special
methods must be used to access them.

The @ref{780,,Message} pseudo-dictionary is indexed by the header names, which
must be ASCII values.  The values of the dictionary are strings that are
supposed to contain only ASCII characters; there is some special handling for
non-ASCII input, but it doesn’t always produce the correct results.  Headers
are stored and returned in case-preserving form, but field names are matched
case-insensitively.  There may also be a single envelope header, also known as
the `Unix-From' header or the @code{From_} header.  The `payload' is either a
string or bytes, in the case of simple message objects, or a list of
@code{Message} objects, for MIME container documents (e.g.
@code{multipart/*} and @code{message/rfc822}).

Here are the methods of the @ref{780,,Message} class:

@geindex Message (κλάση σε email.message)
@anchor{library/email compat32-message email message Message}@anchor{780}
@deffn {Κλάση} email.message.Message (policy=compat32)

If `policy' is specified (it must be an instance of a @ref{52,,policy}
class) use the rules it specifies to update and serialize the representation
of the message.  If `policy' is not set, use the @ref{1461,,compat32} policy, which maintains backward compatibility with
the Python 3.2 version of the email package.  For more information see the
@code{policy} documentation.


Άλλαξε στην έκδοση 3.3: The `policy' keyword argument was added.


@geindex as_string() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message as_string}@anchor{12e1}
@deffn {Μέθοδος} as_string (unixfrom=False, maxheaderlen=0, 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 reasons,
`maxheaderlen' defaults to @code{0}, so if you want a different value you
must override it explicitly (the value specified for `max_line_length' in
the policy will be ignored by this method).  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 @code{Generator}.

Flattening the message may trigger changes to the @code{Message} if
defaults need to be filled in to complete the transformation to a string
(for example, MIME boundaries may be generated or modified).

Note that this method is provided as a convenience and may not always
format the message the way you want.  For example, by default it does
not do the mangling of lines that begin with @code{From} that is
required by the Unix mbox format.  For more flexibility, instantiate a
@ref{1577,,Generator} instance and use its
@ref{3d55,,flatten()} method directly.  For example:

@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

If the message object contains binary data that is not encoded according
to RFC standards, the non-compliant data will be replaced by unicode
«unknown character» code points.  (See also @ref{12e2,,as_bytes()} and
@ref{1578,,BytesGenerator}.)


Άλλαξε στην έκδοση 3.4: the `policy' keyword argument was added.

@end deffn

@geindex __str__() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message __str__}@anchor{3dc1}
@deffn {Μέθοδος} __str__ ()

Equivalent to @ref{12e1,,as_string()}.  Allows @code{str(msg)} to produce a
string containing the formatted message.
@end deffn

@geindex as_bytes() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message as_bytes}@anchor{12e2}
@deffn {Μέθοδος} as_bytes (unixfrom=False, policy=None)

Return the entire message flattened as a bytes object.  When optional
`unixfrom' is true, the envelope header is included in the returned
string.  `unixfrom' defaults to @code{False}.  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
@code{BytesGenerator}.

Flattening the message may trigger changes to the @code{Message} if
defaults need to be filled in to complete the transformation to a string
(for example, MIME boundaries may be generated or modified).

Note that this method is provided as a convenience and may not always
format the message the way you want.  For example, by default it does
not do the mangling of lines that begin with @code{From} that is
required by the Unix mbox format.  For more flexibility, instantiate a
@ref{1578,,BytesGenerator} instance and use its
@ref{3d51,,flatten()} method directly.
For example:

@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


Added in version 3.4.

@end deffn

@geindex __bytes__() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message __bytes__}@anchor{12e3}
@deffn {Μέθοδος} __bytes__ ()

Equivalent to @ref{12e2,,as_bytes()}.  Allows @code{bytes(msg)} to produce a
bytes object containing the formatted message.


Added in version 3.4.

@end deffn

@geindex is_multipart() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message is_multipart}@anchor{3d29}
@deffn {Μέθοδος} is_multipart ()

Return @code{True} if the message’s payload is a list of
sub-@code{Message} objects, otherwise return @code{False}.  When
@code{is_multipart()} returns @code{False}, the payload should be a string
object (which might be a CTE encoded binary payload).  (Note that
@code{is_multipart()} returning @code{True} does not necessarily mean that
«msg.get_content_maintype() == “multipart”» will return the @code{True}.
For example, @code{is_multipart} will return @code{True} when the
@code{Message} is of type @code{message/rfc822}.)
@end deffn

@geindex set_unixfrom() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message set_unixfrom}@anchor{3dc2}
@deffn {Μέθοδος} set_unixfrom (unixfrom)

Set the message’s envelope header to `unixfrom', which should be a string.
@end deffn

@geindex get_unixfrom() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_unixfrom}@anchor{3dc3}
@deffn {Μέθοδος} get_unixfrom ()

Return the message’s envelope header.  Defaults to @code{None} if the
envelope header was never set.
@end deffn

@geindex attach() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message attach}@anchor{3d36}
@deffn {Μέθοδος} attach (payload)

Add the given `payload' to the current payload, which must be @code{None} or
a list of @code{Message} objects before the call. After the call, the
payload will always be a list of @code{Message} objects.  If you want to
set the payload to a scalar object (e.g. a string), use
@ref{3dc4,,set_payload()} instead.

This is a legacy method.  On the
@ref{216,,EmailMessage} class its functionality is
replaced by @ref{1e54,,set_content()} and the
related @code{make} and @code{add} methods.
@end deffn

@geindex get_payload() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_payload}@anchor{1576}
@deffn {Μέθοδος} get_payload (i=None, decode=False)

Return the current payload, which will be a list of
@code{Message} objects when @ref{3d29,,is_multipart()} is @code{True}, or a
string when @code{is_multipart()} is @code{False}.  If the payload is a list
and you mutate the list object, you modify the message’s payload in place.

With optional argument `i', @code{get_payload()} will return the `i'-th
element of the payload, counting from zero, if @ref{3d29,,is_multipart()} is
@code{True}.  An @ref{18d7,,IndexError} will be raised if `i' is less than 0 or
greater than or equal to the number of items in the payload.  If the
payload is a string (i.e.  @code{is_multipart()} is @code{False}) and `i' is
given, a @ref{291,,TypeError} is raised.

Optional `decode' is a flag indicating whether the payload should be
decoded or not, according to the @code{Content-Transfer-Encoding}
header. When @code{True} and the message is not a multipart, the payload will
be decoded if this header’s value is @code{quoted-printable} or @code{base64}.
If some other encoding is used, or @code{Content-Transfer-Encoding}
header is missing, the payload is
returned as-is (undecoded).  In all cases the returned value is binary
data.  If the message is a multipart and the `decode' flag is @code{True},
then @code{None} is returned.  If the payload is base64 and it was not
perfectly formed (missing padding, characters outside the base64
alphabet), then an appropriate defect will be added to the message’s
defect property (@ref{3d86,,InvalidBase64PaddingDefect} or
@ref{3d87,,InvalidBase64CharactersDefect}, respectively).

When `decode' is @code{False} (the default) the body is returned as a string
without decoding the @code{Content-Transfer-Encoding}.  However,
for a @code{Content-Transfer-Encoding} of 8bit, an attempt is made
to decode the original bytes using the @code{charset} specified by the
@code{Content-Type} header, using the @code{replace} error handler.
If no @code{charset} is specified, or if the @code{charset} given is not
recognized by the email package, the body is decoded using the default
ASCII charset.

This is a legacy method.  On the
@ref{216,,EmailMessage} class its functionality is
replaced by @ref{3d2f,,get_content()} and
@ref{3d2e,,iter_parts()}.
@end deffn

@geindex set_payload() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message set_payload}@anchor{3dc4}
@deffn {Μέθοδος} set_payload (payload, charset=None)

Set the entire message object’s payload to `payload'.  It is the client’s
responsibility to ensure the payload invariants.  Optional `charset' sets
the message’s default character set; see @ref{3dc5,,set_charset()} for details.

This is a legacy method.  On the
@ref{216,,EmailMessage} class its functionality is
replaced by @ref{1e54,,set_content()}.
@end deffn

@geindex set_charset() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message set_charset}@anchor{3dc5}
@deffn {Μέθοδος} set_charset (charset)

Set the character set of the payload to `charset', which can either be a
@ref{11b2,,Charset} instance (see @ref{3f,,email.charset}), a
string naming a character set, or @code{None}.  If it is a string, it will
be converted to a @code{Charset} instance.  If `charset'
is @code{None}, the @code{charset} parameter will be removed from the
@code{Content-Type} header (the message will not be otherwise
modified).  Anything else will generate a @ref{291,,TypeError}.

If there is no existing @code{MIME-Version} header one will be
added.  If there is no existing @code{Content-Type} header, one
will be added with a value of @code{text/plain}.  Whether the
@code{Content-Type} header already exists or not, its @code{charset}
parameter will be set to `charset.output_charset'.   If
`charset.input_charset' and `charset.output_charset' differ, the payload
will be re-encoded to the `output_charset'.  If there is no existing
@code{Content-Transfer-Encoding} header, then the payload will be
transfer-encoded, if needed, using the specified
@ref{11b2,,Charset}, and a header with the appropriate value
will be added.  If a @code{Content-Transfer-Encoding} header
already exists, the payload is assumed to already be correctly encoded
using that @code{Content-Transfer-Encoding} and is not modified.

This is a legacy method.  On the
@ref{216,,EmailMessage} class its functionality is
replaced by the `charset' parameter of the
@ref{1e54,,email.message.EmailMessage.set_content()} method.
@end deffn

@geindex get_charset() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_charset}@anchor{3dc6}
@deffn {Μέθοδος} get_charset ()

Return the @ref{11b2,,Charset} instance associated with the
message’s payload.

This is a legacy method.  On the
@ref{216,,EmailMessage} class it always returns
@code{None}.
@end deffn

The following methods implement a mapping-like interface for accessing the
message’s 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} headers.  Note that there are some semantic differences
between these methods and a normal mapping (i.e. dictionary) interface.  For
example, in a dictionary there are no duplicate keys, but here there may be
duplicate message headers.  Also, in dictionaries there is no guaranteed
order to the keys returned by @ref{3dc7,,keys()}, but in a @code{Message} object,
headers are always returned in the order they appeared in the original
message, or were added to the message later.  Any header deleted and then
re-added are always appended to the end of the header list.

These semantic differences are intentional and are biased toward maximal
convenience.

Note that in all cases, any envelope header present in the message is not
included in the mapping interface.

In a model generated from bytes, any header values that (in contravention of
the RFCs) contain non-ASCII bytes will, when retrieved through this
interface, be represented as @ref{1e55,,Header} objects with
a charset of @code{unknown-8bit}.

@geindex __len__() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message __len__}@anchor{3dc8}
@deffn {Μέθοδος} __len__ ()

Return the total number of headers, including duplicates.
@end deffn

@geindex __contains__() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message __contains__}@anchor{1cf3}
@deffn {Μέθοδος} __contains__ (name)

Return @code{True} if the message object has a field named `name'. Matching is
done case-insensitively and `name' should not include the trailing colon.
Used for the @code{in} operator, e.g.:

@example
if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])
@end example
@end deffn

@geindex __getitem__() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message __getitem__}@anchor{3dc9}
@deffn {Μέθοδος} __getitem__ (name)

Return the value of the named header field.  `name' should not include the
colon field separator.  If the header is missing, @code{None} is returned; a
@ref{7df,,KeyError} is never raised.

Note that if the named field appears more than once in the message’s
headers, exactly which of those field values will be returned is
undefined.  Use the @ref{3dca,,get_all()} method to get the values of all the
extant named headers.
@end deffn

@geindex __setitem__() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message __setitem__}@anchor{1aa3}
@deffn {Μέθοδος} __setitem__ (name, val)

Add a header to the message with field name `name' and value `val'.  The
field is appended to the end of the message’s existing fields.

Note that this does `not' overwrite or delete any existing header with the same
name.  If you want to ensure that the new header is the only one present in the
message with field name `name', delete the field first, e.g.:

@example
del msg['subject']
msg['subject'] = 'Python roolz!'
@end example
@end deffn

@geindex __delitem__() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message __delitem__}@anchor{3dcb}
@deffn {Μέθοδος} __delitem__ (name)

Delete all occurrences of the field with name `name' from the message’s
headers.  No exception is raised if the named field isn’t present in the
headers.
@end deffn

@geindex keys() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message keys}@anchor{3dc7}
@deffn {Μέθοδος} keys ()

Return a list of all the message’s header field names.
@end deffn

@geindex values() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message values}@anchor{3dcc}
@deffn {Μέθοδος} values ()

Return a list of all the message’s field values.
@end deffn

@geindex items() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message items}@anchor{3dcd}
@deffn {Μέθοδος} items ()

Return a list of 2-tuples containing all the message’s field headers and
values.
@end deffn

@geindex get() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get}@anchor{3dce}
@deffn {Μέθοδος} get (name, failobj=None)

Return the value of the named header field.  This is identical to
@ref{787,,__getitem__()} except that optional `failobj' is returned if the
named header is missing (defaults to @code{None}).
@end deffn

Here are some additional useful methods:

@geindex get_all() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_all}@anchor{3dca}
@deffn {Μέθοδος} get_all (name, failobj=None)

Return a list of all the values for the field named `name'. If there are
no such named headers in the message, `failobj' is returned (defaults to
@code{None}).
@end deffn

@geindex add_header() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message add_header}@anchor{1aa4}
@deffn {Μέθοδος} add_header (_name, _value, **_params)

Extended header setting.  This method is similar to @ref{1aa3,,__setitem__()}
except that additional header parameters can be provided as keyword
arguments.  `_name' is the header field to add and `_value' is the
`primary' value for the header.

For each item in the keyword argument dictionary `_params', the key is
taken as the parameter name, with underscores converted to dashes (since
dashes are illegal in Python identifiers).  Normally, the parameter will
be added as @code{key="value"} unless the value is @code{None}, in which case
only the key will be added.  If the value contains non-ASCII characters,
it can be specified as a three tuple in the format
@code{(CHARSET, LANGUAGE, VALUE)}, where @code{CHARSET} is a string naming the
charset to be used to encode the value, @code{LANGUAGE} can usually be set
to @code{None} or the empty string (see 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} for other possibilities),
and @code{VALUE} is the string value containing non-ASCII code points.  If
a three tuple is not passed and the value contains non-ASCII characters,
it is automatically encoded in 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} format using a @code{CHARSET}
of @code{utf-8} and a @code{LANGUAGE} of @code{None}.

Here’s an example:

@example
msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
@end example

This will add a header that looks like

@example
Content-Disposition: attachment; filename="bud.gif"
@end example

An example with non-ASCII characters:

@example
msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '@w{'}, 'Fußballer.ppt'))
@end example

Which produces

@example
Content-Disposition: attachment; filename*="iso-8859-1'@w{'}Fu%DFballer.ppt"
@end example
@end deffn

@geindex replace_header() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message replace_header}@anchor{3dcf}
@deffn {Μέθοδος} replace_header (_name, _value)

Replace a header.  Replace the first header found in the message that
matches `_name', retaining header order and field name case.  If no
matching header was found, a @ref{7df,,KeyError} is raised.
@end deffn

@geindex get_content_type() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_content_type}@anchor{3dd0}
@deffn {Μέθοδος} get_content_type ()

Return the message’s content type.  The returned string is coerced to
lower case of the form @code{maintype/subtype}.  If there was no
@code{Content-Type} header in the message the default type as given
by @ref{3dd1,,get_default_type()} will be returned.  Since according to
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}, messages always have a default type, @code{get_content_type()}
will always return a value.

@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} defines a message’s default type to be @code{text/plain}
unless it appears inside a @code{multipart/digest} container, in
which case it would be @code{message/rfc822}.  If the
@code{Content-Type} header has an invalid type specification,
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} mandates that the default type be @code{text/plain}.
@end deffn

@geindex get_content_maintype() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_content_maintype}@anchor{3dd2}
@deffn {Μέθοδος} get_content_maintype ()

Return the message’s main content type.  This is the @code{maintype}
part of the string returned by @ref{3dd0,,get_content_type()}.
@end deffn

@geindex get_content_subtype() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_content_subtype}@anchor{3dd3}
@deffn {Μέθοδος} get_content_subtype ()

Return the message’s sub-content type.  This is the @code{subtype}
part of the string returned by @ref{3dd0,,get_content_type()}.
@end deffn

@geindex get_default_type() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_default_type}@anchor{3dd1}
@deffn {Μέθοδος} get_default_type ()

Return the default content type.  Most messages have a default content
type of @code{text/plain}, except for messages that are subparts of
@code{multipart/digest} containers.  Such subparts have a default
content type of @code{message/rfc822}.
@end deffn

@geindex set_default_type() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message set_default_type}@anchor{3dd4}
@deffn {Μέθοδος} set_default_type (ctype)

Set the default content type.  `ctype' should either be
@code{text/plain} or @code{message/rfc822}, although this is not
enforced.  The default content type is not stored in the
@code{Content-Type} header.
@end deffn

@geindex get_params() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_params}@anchor{3dd5}
@deffn {Μέθοδος} get_params (failobj=None, header='content-type', unquote=True)

Return the message’s @code{Content-Type} parameters, as a list.
The elements of the returned list are 2-tuples of key/value pairs, as
split on the @code{'='} sign.  The left hand side of the @code{'='} is the key,
while the right hand side is the value.  If there is no @code{'='} sign in
the parameter the value is the empty string, otherwise the value is as
described in @ref{3dd6,,get_param()} and is unquoted if optional `unquote' is
@code{True} (the default).

Optional `failobj' is the object to return if there is no
@code{Content-Type} header.  Optional `header' is the header to
search instead of @code{Content-Type}.

This is a legacy method.  On the
@ref{216,,EmailMessage} class its functionality is
replaced by the `params' property of the individual header objects
returned by the header access methods.
@end deffn

@geindex get_param() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_param}@anchor{3dd6}
@deffn {Μέθοδος} get_param (param, failobj=None, header='content-type', unquote=True)

Return the value of the @code{Content-Type} header’s parameter
`param' as a string.  If the message has no @code{Content-Type}
header or if there is no such parameter, then `failobj' is returned
(defaults to @code{None}).

Optional `header' if given, specifies the message header to use instead of
@code{Content-Type}.

Parameter keys are always compared case insensitively.  The return value
can either be a string, or a 3-tuple if the parameter was 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}
encoded.  When it’s a 3-tuple, the elements of the value are of the form
@code{(CHARSET, LANGUAGE, VALUE)}.  Note that both @code{CHARSET} and
@code{LANGUAGE} can be @code{None}, in which case you should consider @code{VALUE}
to be encoded in the @code{us-ascii} charset.  You can usually ignore
@code{LANGUAGE}.

If your application doesn’t care whether the parameter was encoded as in
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}, you can collapse the parameter value by calling
@ref{3dd7,,email.utils.collapse_rfc2231_value()}, passing in the return value
from @code{get_param()}.  This will return a suitably decoded Unicode
string when the value is a tuple, or the original string unquoted if it
isn’t.  For example:

@example
rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)
@end example

In any case, the parameter value (either the returned string, or the
@code{VALUE} item in the 3-tuple) is always unquoted, unless `unquote' is set
to @code{False}.

This is a legacy method.  On the
@ref{216,,EmailMessage} class its functionality is
replaced by the `params' property of the individual header objects
returned by the header access methods.
@end deffn

@geindex set_param() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message set_param}@anchor{12e4}
@deffn {Μέθοδος} set_param (param, value, header='Content-Type', requote=True, charset=None, language='@w{'}, replace=False)

Set a parameter in the @code{Content-Type} header.  If the
parameter already exists in the header, its value will be replaced with
`value'.  If the @code{Content-Type} header as not yet been defined
for this message, it will be set to @code{text/plain} and the new
parameter value will be appended as per 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}.

Optional `header' specifies an alternative header to
@code{Content-Type}, and all parameters will be quoted as necessary
unless optional `requote' is @code{False} (the default is @code{True}).

If optional `charset' is specified, the parameter will be encoded
according to 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}. Optional `language' specifies the RFC 2231
language, defaulting to the empty string.  Both `charset' and `language'
should be strings.

If `replace' is @code{False} (the default) the header is moved to the
end of the list of headers.  If `replace' is @code{True}, the header
will be updated in place.


Άλλαξε στην έκδοση 3.4: @code{replace} keyword was added.

@end deffn

@geindex del_param() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message del_param}@anchor{3dd8}
@deffn {Μέθοδος} del_param (param, header='content-type', requote=True)

Remove the given parameter completely from the @code{Content-Type}
header.  The header will be re-written in place without the parameter or
its value.  All values will be quoted as necessary unless `requote' is
@code{False} (the default is @code{True}).  Optional `header' specifies an
alternative to @code{Content-Type}.
@end deffn

@geindex set_type() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message set_type}@anchor{3dd9}
@deffn {Μέθοδος} set_type (type, header='Content-Type', requote=True)

Set the main type and subtype for the @code{Content-Type}
header. `type' must be a string in the form @code{maintype/subtype},
otherwise a @ref{277,,ValueError} is raised.

This method replaces the @code{Content-Type} header, keeping all
the parameters in place.  If `requote' is @code{False}, this leaves the
existing header’s quoting as is, otherwise the parameters will be quoted
(the default).

An alternative header can be specified in the `header' argument. When the
@code{Content-Type} header is set a @code{MIME-Version}
header is also added.

This is a legacy method.  On the
@ref{216,,EmailMessage} class its functionality is
replaced by the @code{make_} and @code{add_} methods.
@end deffn

@geindex get_filename() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_filename}@anchor{3dda}
@deffn {Μέθοδος} get_filename (failobj=None)

Return the value of the @code{filename} parameter of the
@code{Content-Disposition} header of the message.  If the header
does not have a @code{filename} parameter, this method falls back to looking
for the @code{name} parameter on the @code{Content-Type} header.  If
neither is found, or the header is missing, then `failobj' is returned.
The returned string will always be unquoted as per
@ref{3d22,,email.utils.unquote()}.
@end deffn

@geindex get_boundary() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_boundary}@anchor{3ddb}
@deffn {Μέθοδος} get_boundary (failobj=None)

Return the value of the @code{boundary} parameter of the
@code{Content-Type} header of the message, or `failobj' if either
the header is missing, or has no @code{boundary} parameter.  The returned
string will always be unquoted as per @ref{3d22,,email.utils.unquote()}.
@end deffn

@geindex set_boundary() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message set_boundary}@anchor{3ddc}
@deffn {Μέθοδος} set_boundary (boundary)

Set the @code{boundary} parameter of the @code{Content-Type} header to
`boundary'.  @code{set_boundary()} will always quote `boundary' if
necessary.  A @ref{3d25,,HeaderParseError} is raised if the
message object has no @code{Content-Type} header.

Note that using this method is subtly different than deleting the old
@code{Content-Type} header and adding a new one with the new
boundary via @ref{1aa4,,add_header()}, because @code{set_boundary()} preserves
the order of the @code{Content-Type} header in the list of
headers. However, it does `not' preserve any continuation lines which may
have been present in the original @code{Content-Type} header.
@end deffn

@geindex get_content_charset() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_content_charset}@anchor{3ddd}
@deffn {Μέθοδος} get_content_charset (failobj=None)

Return the @code{charset} parameter of the @code{Content-Type} header,
coerced to lower case.  If there is no @code{Content-Type} header, or if
that header has no @code{charset} parameter, `failobj' is returned.

Note that this method differs from @ref{3dc6,,get_charset()} which returns the
@ref{11b2,,Charset} instance for the default encoding of the message body.
@end deffn

@geindex get_charsets() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_charsets}@anchor{3dde}
@deffn {Μέθοδος} get_charsets (failobj=None)

Return a list containing the character set names in the message.  If the
message is a @code{multipart}, then the list will contain one element
for each subpart in the payload, otherwise, it will be a list of length 1.

Each item in the list will be a string which is the value of the
@code{charset} parameter in the @code{Content-Type} header for the
represented subpart.  However, if the subpart has no
@code{Content-Type} header, no @code{charset} parameter, or is not of
the @code{text} main MIME type, then that item in the returned list
will be `failobj'.
@end deffn

@geindex get_content_disposition() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message get_content_disposition}@anchor{11b0}
@deffn {Μέθοδος} get_content_disposition ()

Return the lowercased value (without parameters) of the message’s
@code{Content-Disposition} header if it has one, or @code{None}.  The
possible values for this method are `inline', `attachment' or @code{None}
if the message follows 
@geindex RFC; RFC 2183
RFC 2183@footnote{https://datatracker.ietf.org/doc/html/rfc2183.html}.


Added in version 3.5.

@end deffn

@geindex walk() (μέθοδος της email.message.Message)
@anchor{library/email compat32-message email message Message walk}@anchor{3ddf}
@deffn {Μέθοδος} walk ()

The @code{walk()} method is an all-purpose generator which can be used to
iterate over all the parts and subparts of a message object tree, in
depth-first traversal order.  You will typically use @code{walk()} as the
iterator in a @code{for} loop; each iteration returns the next subpart.

Here’s an example that prints the MIME type of every part of a multipart
message structure:

@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} iterates over the subparts of any part where
@ref{3d29,,is_multipart()} returns @code{True}, even though
@code{msg.get_content_maintype() == 'multipart'} may return @code{False}.  We
can see this in our example by making use of the @code{_structure} debug
helper function:

@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

Here the @code{message} parts are not @code{multiparts}, but they do contain
subparts. @code{is_multipart()} returns @code{True} and @code{walk} descends
into the subparts.
@end deffn

@code{Message} objects can also optionally contain two instance attributes,
which can be used when generating the plain text of a MIME message.

@geindex preamble (ιδιότητα της email.message.Message)
@anchor{library/email compat32-message email message Message preamble}@anchor{3de0}
@deffn {Ιδιότητα} preamble

The format of a MIME document allows for some text between the blank line
following the headers, and the first multipart boundary string. Normally,
this text is never visible in a MIME-aware mail reader because it falls
outside the standard MIME armor.  However, when viewing the raw text of
the message, or when viewing the message in a non-MIME aware reader, this
text can become visible.

The `preamble' attribute contains this leading extra-armor text for MIME
documents.  When the @ref{1546,,Parser} discovers some text
after the headers but before the first boundary string, it assigns this
text to the message’s `preamble' attribute.  When the
@ref{1577,,Generator} is writing out the plain text
representation of a MIME message, and it finds the
message has a `preamble' attribute, it will write this text in the area
between the headers and the first boundary.  See @ref{51,,email.parser} and
@ref{43,,email.generator} for details.

Note that if the message object has no preamble, the `preamble' attribute
will be @code{None}.
@end deffn

@geindex epilogue (ιδιότητα της email.message.Message)
@anchor{library/email compat32-message email message Message epilogue}@anchor{3de1}
@deffn {Ιδιότητα} epilogue

The `epilogue' attribute acts the same way as the `preamble' attribute,
except that it contains text that appears between the last boundary and
the end of the message.

You do not need to set the epilogue to the empty string in order for the
@ref{1577,,Generator} to print a newline at the end of the
file.
@end deffn

@geindex defects (ιδιότητα της email.message.Message)
@anchor{library/email compat32-message email message Message defects}@anchor{3de2}
@deffn {Ιδιότητα} defects

The `defects' attribute contains a list of all the problems found when
parsing this message.  See @ref{42,,email.errors} for a detailed description
of the possible parsing defects.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node email mime Creating email and MIME objects from scratch,email header Internationalized headers,email message Message Representing an email message using the compat32 API,email — An email and MIME handling package
@anchor{library/email mime doc}@anchor{3de3}@anchor{library/email mime email-mime-creating-email-and-mime-objects-from-scratch}@anchor{3de4}@anchor{library/email mime module-email mime}@anchor{48}@anchor{library/email mime translation-repo}@anchor{3de5}
@subsubsection @code{email.mime}: Creating email and MIME objects from scratch


@geindex module; email.mime

`Source code:' Lib/email/mime/@footnote{https://github.com/python/cpython/tree/main/Lib/email/mime/}


__________________________________________________________________


This module is part of the legacy (@code{Compat32}) email API.  Its functionality
is partially replaced by the @ref{40,,contentmanager} in the new API, but
in certain applications these classes may still be useful, even in non-legacy
code.

Ordinarily, you get a message object structure by passing a file or some text to
a parser, which parses the text and returns the root message object.  However
you can also build a complete message structure from scratch, or even individual
@ref{780,,Message} objects by hand.  In fact, you can also take an
existing structure and add new @code{Message} objects, move them
around, etc.  This makes a very convenient interface for slicing-and-dicing MIME
messages.

You can create a new object structure by creating @ref{780,,Message}
instances, adding attachments and all the appropriate headers manually.  For MIME
messages though, the @ref{3e,,email} package provides some convenient subclasses to
make things easier.

Here are the classes:

@geindex module; email.mime.base

@geindex MIMEBase (κλάση σε email.mime.base)
@anchor{library/email mime module-email mime base}@anchor{4b}@anchor{library/email mime email mime base MIMEBase}@anchor{3de6}
@deffn {Κλάση} email.mime.base.MIMEBase (_maintype, _subtype, *, policy=compat32, **_params)

Module: @ref{4b,,email.mime.base}

This is the base class for all the MIME-specific subclasses of
@ref{780,,Message}.  Ordinarily you won’t create instances
specifically of @code{MIMEBase}, although you could.  @code{MIMEBase}
is provided primarily as a convenient base class for more specific
MIME-aware subclasses.

`_maintype' is the @code{Content-Type} major type (e.g. @code{text}
or @code{image}), and `_subtype' is the @code{Content-Type} minor
type  (e.g. @code{plain} or @code{gif}).  `_params' is a parameter
key/value dictionary and is passed directly to @ref{1aa4,,Message.add_header}.

If `policy' is specified, (defaults to the
@ref{1461,,compat32} policy) it will be passed to
@ref{780,,Message}.

The @code{MIMEBase} class always adds a @code{Content-Type} header
(based on `_maintype', `_subtype', and `_params'), and a
@code{MIME-Version} header (always set to @code{1.0}).


Άλλαξε στην έκδοση 3.6: Added `policy' keyword-only parameter.

@end deffn

@geindex module; email.mime.nonmultipart

@geindex MIMENonMultipart (κλάση σε email.mime.nonmultipart)
@anchor{library/email mime module-email mime nonmultipart}@anchor{4f}@anchor{library/email mime email mime nonmultipart MIMENonMultipart}@anchor{3d7c}
@deffn {Κλάση} email.mime.nonmultipart.MIMENonMultipart

Module: @ref{4f,,email.mime.nonmultipart}

A subclass of @ref{3de6,,MIMEBase}, this is an intermediate base
class for MIME messages that are not @code{multipart}.  The primary
purpose of this class is to prevent the use of the
@ref{3d36,,attach()} method, which only makes sense for
@code{multipart} messages.  If @code{attach()}
is called, a @ref{3d7b,,MultipartConversionError} exception is raised.
@end deffn

@geindex module; email.mime.multipart

@geindex MIMEMultipart (κλάση σε email.mime.multipart)
@anchor{library/email mime module-email mime multipart}@anchor{4e}@anchor{library/email mime email mime multipart MIMEMultipart}@anchor{3de7}
@deffn {Κλάση} email.mime.multipart.MIMEMultipart (_subtype='mixed', boundary=None, _subparts=None, *, policy=compat32, **_params)

Module: @ref{4e,,email.mime.multipart}

A subclass of @ref{3de6,,MIMEBase}, this is an intermediate base
class for MIME messages that are @code{multipart}.  Optional `_subtype'
defaults to @code{mixed}, but can be used to specify the subtype of the
message.  A @code{Content-Type} header of @code{multipart/_subtype}
will be added to the message object.  A @code{MIME-Version} header will
also be added.

Optional `boundary' is the multipart boundary string.  When @code{None} (the
default), the boundary is calculated when needed (for example, when the
message is serialized).

`_subparts' is a sequence of initial subparts for the payload.  It must be
possible to convert this sequence to a list.  You can always attach new subparts
to the message by using the @ref{3d36,,Message.attach} method.

Optional `policy' argument defaults to @ref{1461,,compat32}.

Additional parameters for the @code{Content-Type} header are taken from
the keyword arguments, or passed into the `_params' argument, which is a keyword
dictionary.


Άλλαξε στην έκδοση 3.6: Added `policy' keyword-only parameter.

@end deffn

@geindex module; email.mime.application

@geindex MIMEApplication (κλάση σε email.mime.application)
@anchor{library/email mime module-email mime application}@anchor{49}@anchor{library/email mime email mime application MIMEApplication}@anchor{3de8}
@deffn {Κλάση} email.mime.application.MIMEApplication (_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Module: @ref{49,,email.mime.application}

A subclass of @ref{3d7c,,MIMENonMultipart}, the
@code{MIMEApplication} class is used to represent MIME message objects of
major type @code{application}.  `_data' contains the bytes for the raw
application data.  Optional `_subtype' specifies the MIME subtype and defaults
to @code{octet-stream}.

Optional `_encoder' is a callable (i.e. function) which will perform the actual
encoding of the data for transport.  This callable takes one argument, which is
the @code{MIMEApplication} instance. It should use
@ref{1576,,get_payload()} and
@ref{3dc4,,set_payload()} to change the payload to encoded
form.  It should also add
any @code{Content-Transfer-Encoding} or other headers to the message
object as necessary.  The default encoding is base64.  See the
@ref{41,,email.encoders} module for a list of the built-in encoders.

Optional `policy' argument defaults to @ref{1461,,compat32}.

`_params' are passed straight through to the base class constructor.


Άλλαξε στην έκδοση 3.6: Added `policy' keyword-only parameter.

@end deffn

@geindex module; email.mime.audio

@geindex MIMEAudio (κλάση σε email.mime.audio)
@anchor{library/email mime module-email mime audio}@anchor{4a}@anchor{library/email mime email mime audio MIMEAudio}@anchor{3de9}
@deffn {Κλάση} email.mime.audio.MIMEAudio (_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Module: @ref{4a,,email.mime.audio}

A subclass of @ref{3d7c,,MIMENonMultipart}, the
@code{MIMEAudio} class is used to create MIME message objects of major type
@code{audio}. `_audiodata' contains the bytes for the raw audio data.  If
this data can be decoded as au, wav, aiff, or aifc, then the
subtype will be automatically included in the @code{Content-Type} header.
Otherwise you can explicitly specify the audio subtype via the `_subtype'
argument.  If the minor type could not be guessed and `_subtype' was not given,
then @ref{291,,TypeError} is raised.

Optional `_encoder' is a callable (i.e. function) which will perform the actual
encoding of the audio data for transport.  This callable takes one argument,
which is the @code{MIMEAudio} instance. It should use
@ref{1576,,get_payload()} and
@ref{3dc4,,set_payload()} to change the payload to encoded
form.  It should also add
any @code{Content-Transfer-Encoding} or other headers to the message
object as necessary.  The default encoding is base64.  See the
@ref{41,,email.encoders} module for a list of the built-in encoders.

Optional `policy' argument defaults to @ref{1461,,compat32}.

`_params' are passed straight through to the base class constructor.


Άλλαξε στην έκδοση 3.6: Added `policy' keyword-only parameter.

@end deffn

@geindex module; email.mime.image

@geindex MIMEImage (κλάση σε email.mime.image)
@anchor{library/email mime module-email mime image}@anchor{4c}@anchor{library/email mime email mime image MIMEImage}@anchor{3d7d}
@deffn {Κλάση} email.mime.image.MIMEImage (_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Module: @ref{4c,,email.mime.image}

A subclass of @ref{3d7c,,MIMENonMultipart}, the
@code{MIMEImage} class is used to create MIME message objects of major type
@code{image}. `_imagedata' contains the bytes for the raw image data.  If
this data type can be detected (jpeg, png, gif, tiff, rgb, pbm, pgm, ppm,
rast, xbm, bmp, webp, and exr attempted), then the subtype will be
automatically included in the @code{Content-Type} header. Otherwise
you can explicitly specify the image subtype via the `_subtype' argument.
If the minor type could not be guessed and `_subtype' was not given, then
@ref{291,,TypeError} is raised.

Optional `_encoder' is a callable (i.e. function) which will perform the actual
encoding of the image data for transport.  This callable takes one argument,
which is the @code{MIMEImage} instance. It should use
@ref{1576,,get_payload()} and
@ref{3dc4,,set_payload()} to change the payload to encoded
form.  It should also add
any @code{Content-Transfer-Encoding} or other headers to the message
object as necessary.  The default encoding is base64.  See the
@ref{41,,email.encoders} module for a list of the built-in encoders.

Optional `policy' argument defaults to @ref{1461,,compat32}.

`_params' are passed straight through to the @ref{3de6,,MIMEBase}
constructor.


Άλλαξε στην έκδοση 3.6: Added `policy' keyword-only parameter.

@end deffn

@geindex module; email.mime.message

@geindex MIMEMessage (κλάση σε email.mime.message)
@anchor{library/email mime module-email mime message}@anchor{4d}@anchor{library/email mime email mime message MIMEMessage}@anchor{3dea}
@deffn {Κλάση} email.mime.message.MIMEMessage (_msg, _subtype='rfc822', *, policy=compat32)

Module: @ref{4d,,email.mime.message}

A subclass of @ref{3d7c,,MIMENonMultipart}, the
@code{MIMEMessage} class is used to create MIME objects of main type
@code{message}. `_msg' is used as the payload, and must be an instance
of class @ref{780,,Message} (or a subclass thereof), otherwise
a @ref{291,,TypeError} is raised.

Optional `_subtype' sets the subtype of the message; it defaults to
@code{rfc822}.

Optional `policy' argument defaults to @ref{1461,,compat32}.


Άλλαξε στην έκδοση 3.6: Added `policy' keyword-only parameter.

@end deffn

@geindex module; email.mime.text

@geindex MIMEText (κλάση σε email.mime.text)
@anchor{library/email mime module-email mime text}@anchor{50}@anchor{library/email mime email mime text MIMEText}@anchor{11b1}
@deffn {Κλάση} email.mime.text.MIMEText (_text, _subtype='plain', _charset=None, *, policy=compat32)

Module: @ref{50,,email.mime.text}

A subclass of @ref{3d7c,,MIMENonMultipart}, the
@code{MIMEText} class is used to create MIME objects of major type
@code{text}. `_text' is the string for the payload.  `_subtype' is the
minor type and defaults to @code{plain}.  `_charset' is the character
set of the text and is passed as an argument to the
@code{MIMENonMultipart} constructor; it defaults
to @code{us-ascii} if the string contains only @code{ascii} code points, and
@code{utf-8} otherwise.  The `_charset' parameter accepts either a string or a
@ref{11b2,,Charset} instance.

Unless the `_charset' argument is explicitly set to @code{None}, the
MIMEText object created will have both a @code{Content-Type} header
with a @code{charset} parameter, and a @code{Content-Transfer-Encoding}
header.  This means that a subsequent @code{set_payload} call will not result
in an encoded payload, even if a charset is passed in the @code{set_payload}
command.  You can «reset» this behavior by deleting the
@code{Content-Transfer-Encoding} header, after which a @code{set_payload} call
will automatically encode the new payload (and add a new
@code{Content-Transfer-Encoding} header).

Optional `policy' argument defaults to @ref{1461,,compat32}.


Άλλαξε στην έκδοση 3.5: `_charset' also accepts @ref{11b2,,Charset} instances.



Άλλαξε στην έκδοση 3.6: Added `policy' keyword-only parameter.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node email header Internationalized headers,email charset Αναπαράσταση συνόλων χαρακτήρων,email mime Creating email and MIME objects from scratch,email — An email and MIME handling package
@anchor{library/email header doc}@anchor{3deb}@anchor{library/email header email-header-internationalized-headers}@anchor{3dec}@anchor{library/email header module-email header}@anchor{44}@anchor{library/email header translation-repo}@anchor{3ded}
@subsubsection @code{email.header}: Internationalized headers


@geindex module; email.header

`Source code:' Lib/email/header.py@footnote{https://github.com/python/cpython/tree/main/Lib/email/header.py}


__________________________________________________________________


This module is part of the legacy (@code{Compat32}) email API.  In the current API
encoding and decoding of headers is handled transparently by the
dictionary-like API of the @ref{216,,EmailMessage} class.  In
addition to uses in legacy code, this module can be useful in applications that
need to completely control the character sets used when encoding headers.

The remaining text in this section is the original documentation of the module.

@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} is the base standard that describes the format of email messages.
It derives from the older 
@geindex RFC; RFC 822
RFC 822@footnote{https://datatracker.ietf.org/doc/html/rfc822.html} standard which came into widespread use at
a time when most email was composed of ASCII characters only.  
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} is a
specification written assuming email contains only 7-bit ASCII characters.

Of course, as email has been deployed worldwide, it has become
internationalized, such that language specific character sets can now be used in
email messages.  The base standard still requires email messages to be
transferred using only 7-bit ASCII characters, so a slew of RFCs have been
written describing how to encode email containing non-ASCII characters into
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}-compliant format. These RFCs include 
@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}, and 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}. The @ref{3e,,email} package supports these standards
in its @code{email.header} and @ref{3f,,email.charset} modules.

If you want to include non-ASCII characters in your email headers, say in the
@code{Subject} or @code{To} fields, you should use the
@ref{1e55,,Header} class and assign the field in the @ref{780,,Message}
object to an instance of @code{Header} instead of using a string for the header
value.  Import the @code{Header} class from the @code{email.header} module.
For example:

@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

Notice here how we wanted the @code{Subject} field to contain a non-ASCII
character?  We did this by creating a @ref{1e55,,Header} instance and passing in
the character set that the byte string was encoded in.  When the subsequent
@ref{780,,Message} instance was flattened, the @code{Subject}
field was properly 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} encoded.  MIME-aware mail readers would show this
header using the embedded ISO-8859-1 character.

Here is the @ref{1e55,,Header} class description:

@geindex Header (κλάση σε email.header)
@anchor{library/email header email header Header}@anchor{1e55}
@deffn {Κλάση} email.header.Header (s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')

Create a MIME-compliant header that can contain strings in different character
sets.

Optional `s' is the initial header value.  If @code{None} (the default), the
initial header value is not set.  You can later append to the header with
@ref{3dee,,append()} method calls.  `s' may be an instance of @ref{1c7,,bytes} or
@ref{1df,,str}, but see the @code{append()} documentation for semantics.

Optional `charset' serves two purposes: it has the same meaning as the `charset'
argument to the @ref{3dee,,append()} method.  It also sets the default character set
for all subsequent @code{append()} calls that omit the `charset' argument.  If
`charset' is not provided in the constructor (the default), the @code{us-ascii}
character set is used both as `s'’s initial charset and as the default for
subsequent @code{append()} calls.

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.

Optional `continuation_ws' must be 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}-compliant folding
whitespace, and is usually either a space or a hard tab character.  This
character will be prepended to continuation lines.  `continuation_ws'
defaults to a single space character.

Optional `errors' is passed straight through to the @ref{3dee,,append()} method.

@geindex append() (μέθοδος της email.header.Header)
@anchor{library/email header email header Header append}@anchor{3dee}
@deffn {Μέθοδος} append (s, charset=None, errors='strict')

Append the string `s' to the MIME header.

Optional `charset', if given, should be a @ref{11b2,,Charset}
instance (see @ref{3f,,email.charset}) or the name of a character set, which
will be converted to a @code{Charset} instance.  A value
of @code{None} (the default) means that the `charset' given in the constructor
is used.

`s' may be an instance of @ref{1c7,,bytes} or @ref{1df,,str}.  If it is an
instance of @code{bytes}, then `charset' is the encoding of that byte
string, and a @ref{675,,UnicodeError} will be raised if the string cannot be
decoded with that character set.

If `s' is an instance of @ref{1df,,str}, then `charset' is a hint specifying
the character set of the characters in the string.

In either case, when producing an 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}-compliant header using
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} rules, the string will be encoded using the output codec of
the charset.  If the string cannot be encoded using the output codec, a
UnicodeError will be raised.

Optional `errors' is passed as the errors argument to the decode call
if `s' is a byte string.
@end deffn

@geindex encode() (μέθοδος της email.header.Header)
@anchor{library/email header email header Header encode}@anchor{3def}
@deffn {Μέθοδος} encode (splitchars=';, \t', maxlinelen=None, linesep='\n')

Encode a message header into an RFC-compliant format, possibly wrapping
long lines and encapsulating non-ASCII parts in base64 or quoted-printable
encodings.

Optional `splitchars' is a string containing characters which should be
given extra weight by the splitting algorithm during normal header
wrapping.  This is in very rough support of 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}'s “higher level
syntactic breaks”:  split points preceded by a splitchar are preferred
during line splitting, with the characters preferred in the order in
which they appear in the string.  Space and tab may be included in the
string to indicate whether preference should be given to one over the
other as a split point when other split chars do not appear in the line
being split.  Splitchars does not affect 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} encoded lines.

`maxlinelen', if given, overrides the instance’s value for the maximum
line length.

`linesep' specifies the characters used to separate the lines of the
folded header.  It defaults to the most useful value for Python
application code (@code{\n}), but @code{\r\n} can be specified in order
to produce headers with RFC-compliant line separators.


Άλλαξε στην έκδοση 3.2: Added the `linesep' argument.

@end deffn

The @code{Header} class also provides a number of methods to support
standard operators and built-in functions.

@geindex __str__() (μέθοδος της email.header.Header)
@anchor{library/email header email header Header __str__}@anchor{3df0}
@deffn {Μέθοδος} __str__ ()

Returns an approximation of the @code{Header} as a string, using an
unlimited line length.  All pieces are converted to unicode using the
specified encoding and joined together appropriately.  Any pieces with a
charset of @code{'unknown-8bit'} are decoded as ASCII using the @code{'replace'}
error handler.


Άλλαξε στην έκδοση 3.2: Added handling for the @code{'unknown-8bit'} charset.

@end deffn

@geindex __eq__() (μέθοδος της email.header.Header)
@anchor{library/email header email header Header __eq__}@anchor{3df1}
@deffn {Μέθοδος} __eq__ (other)

This method allows you to compare two @code{Header} instances for
equality.
@end deffn

@geindex __ne__() (μέθοδος της email.header.Header)
@anchor{library/email header email header Header __ne__}@anchor{3df2}
@deffn {Μέθοδος} __ne__ (other)

This method allows you to compare two @code{Header} instances for
inequality.
@end deffn
@end deffn

The @code{email.header} module also provides the following convenient functions.

@geindex decode_header() (στη μονάδα email.header)
@anchor{library/email header email header decode_header}@anchor{1465}
@deffn {Συνάρτηση} email.header.decode_header (header)

Decode a message header value without converting the character set. The header
value is in `header'.

For historical reasons, this function may return either:


@enumerate 

@item 
A list of pairs containing each of the decoded parts of the header,
@code{(decoded_bytes, charset)}, where `decoded_bytes' is always an instance of
@ref{1c7,,bytes}, and `charset' is either:

@quotation


@itemize -

@item 
A lower case string containing the name of the character set specified.

@item 
@code{None} for non-encoded parts of the header.
@end itemize
@end quotation

@item 
A list of length 1 containing a pair @code{(string, None)}, where
`string' is always an instance of @ref{1df,,str}.
@end enumerate

An @ref{3d25,,email.errors.HeaderParseError} may be raised when certain decoding
errors occur (e.g. a base64 decoding exception).

Here are examples:

@example
>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[(b'p\xf6stal', 'iso-8859-1')]
>>> decode_header('unencoded_string')
[('unencoded_string', None)]
>>> decode_header('bar =?utf-8?B?ZsOzbw==?=')
[(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]
@end example

@cartouche
@quotation Σημείωση 
This function exists for backwards compatibility only. For
new code, we recommend using @ref{3d8d,,email.headerregistry.HeaderRegistry}.
@end quotation
@end cartouche
@end deffn

@geindex make_header() (στη μονάδα email.header)
@anchor{library/email header email header make_header}@anchor{1466}
@deffn {Συνάρτηση} email.header.make_header (decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')

Create a @ref{1e55,,Header} instance from a sequence of pairs as returned by
@ref{1465,,decode_header()}.

@ref{1465,,decode_header()} takes a header value string and returns a sequence of
pairs of the format @code{(decoded_string, charset)} where `charset' is the name of
the character set.

This function takes one of those sequence of pairs and returns a
@ref{1e55,,Header} instance.  Optional `maxlinelen', `header_name', and
`continuation_ws' are as in the @code{Header} constructor.

@cartouche
@quotation Σημείωση 
This function exists for backwards compatibility only, and is
not recommended for use in new code.
@end quotation
@end cartouche
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node email charset Αναπαράσταση συνόλων χαρακτήρων,email encoders Encoders,email header Internationalized headers,email — An email and MIME handling package
@anchor{library/email charset doc}@anchor{3df3}@anchor{library/email charset email-charset-representing-character-sets}@anchor{3df4}@anchor{library/email charset module-email charset}@anchor{3f}@anchor{library/email charset translation-repo}@anchor{3df5}
@subsubsection @code{email.charset}: Αναπαράσταση συνόλων χαρακτήρων


@geindex module; email.charset

`Πηγαίος κώδικας:' Lib/email.charset.py@footnote{https://github.com/python/cpython/tree/main/Lib/email.charset.py}


__________________________________________________________________


Αυτό το module αποτελεί μέρος του παλιού API (@code{Compat32}) του email.  Στο νέο API, χρησιμοποιείται μόνο ο πίνακας των ψευδωνύμων.

Το υπόλοιπο κείμενο σε αυτή την ενότητα είναι η αρχική τεκμηρίωση του module.

Αυτό το module παρέχει την κλάση @ref{11b2,,Charset} για την αναπαράσταση των συνόλων χαρακτήρων και των μετατροπών τους σε μηνύματα email, καθώς και ένα μητρώο συνόλων χαρακτήρων και διάφορες βοηθητικές μεθόδους για τη διαχείρισή του. Τα στιγμιότυπα της @code{Charset} χρησιμοποιούνται σε αρκετά άλλα modules εντός του πακέτου @ref{3e,,email}.

Import this class from the @code{email.charset} module.

@geindex Charset (κλάση σε email.charset)
@anchor{library/email charset email charset Charset}@anchor{11b2}
@deffn {Κλάση} email.charset.Charset (input_charset=DEFAULT_CHARSET)

Αντιστοίχιση συνόλων χαρακτήρων στις ιδιότητες τους στο email.

Αυτή η κλάση παρέχει πληροφορίες σχετικά με τις απαιτήσεις που επιβάλλονται σε ένα email για ένα συγκεκριμένο σύνολο χαρακτήρων. Παρέχει επίσης βοηθητικές ρουτίνες για την μετατροπή μεταξύ συνόλων χαρακτήρων, εφόσον είναι διαθέσιμα τα αντίστοιχα codecs. Δεδομένου ενός συνόλου χαρακτήρων, θα προσπαθήσει να παρέχει πληροφορίες σχετικά με τον τρόπο χρήσης του σε ένα email με τρόπο συμβατό με το RFC.

Ορισμένα σύνολα χαρακτήρων πρέπει να κωδικοποιούνται με quoted-printable ή base64 όταν χρησιμοποιούνται σε κεφαλίδες ή σώματα email. Ορισμένα σύνολα χαρακτήρων πρέπει να μετατραπούν πλήρως και δεν επιτρέπονται στα email.

Το προαιρετικό `input_charset' περιγράφεται παρακάτω· μετατρέπεται πάντα σε πεζά. Μετά την κανονικοποίηση ψευδωνύμων, χρησιμοποιείται επίσης ως αναζήτηση στο μητρώο των συνόλων χαρακτήρων για να προσδιορίσει την κωδικοποίηση κεφαλίδας, την κωδικοποίηση σώματος και τον κωδικοποιητή μετατροπής εξόδου που θα χρησιμοποιηθεί για το σύνολο χαρακτήρων. Για παράδειγμα, εάν το `input_charset' είναι @code{iso-8859-1}, τότε οι κεφαλίδες και τα σώματα θα κωδικοποιηθούν χρησιμοποιώντας quoted-printable και δεν απαιτείται codec μετατροπής εξόδου. Εάν το `input_charset' είναι @code{euc-jp}, τότε οι κεφαλίδες θα κωδικοποιηθούν με base64, τα σώματα δεν θα κωδικοποιηθούν, αλλά το κείμενο εξόδου θα μετατραπεί από το σύνολο χαρακτήρων @code{euc-jp} στο @code{iso-2022-jp}.

Στιγμιότυπα της κλάσης @ref{11b2,,Charset} έχουν τα ακόλουθα χαρακτηριστικά δεδομένων:

@geindex input_charset (ιδιότητα της email.charset.Charset)
@anchor{library/email charset email charset Charset input_charset}@anchor{3df6}
@deffn {Ιδιότητα} input_charset

Το αρχικό σύνολο χαρακτήρων καθορίζεται. Τα κοινά ψευδώνυμα μετατρέπονται στα `επίσημα' ονόματα τους για το email (π.χ. το @code{latin_1} μετατρέπεται σε @code{iso-8859-1}). Προεπιλογή είναι το 7-bit @code{us-ascii}.
@end deffn

@geindex header_encoding (ιδιότητα της email.charset.Charset)
@anchor{library/email charset email charset Charset header_encoding}@anchor{3df7}
@deffn {Ιδιότητα} header_encoding

Εάν το σύνολο χαρακτήρων πρέπει να κωδικοποιηθεί πριν χρησιμοποιηθεί σε κεφαλίδα email, αυτό το χαρακτηριστικό θα οριστεί σε @code{charset.QP} (για quoted-printable), @code{charset.BASE64} (για κωδικοποίηση base64), ή @code{charset.SHORTEST} για την πιο σύντομη κωδικοποίηση από QP ή BASE64. Διαφορετικά, θα είναι @code{None}.
@end deffn

@geindex body_encoding (ιδιότητα της email.charset.Charset)
@anchor{library/email charset email charset Charset body_encoding}@anchor{3df8}
@deffn {Ιδιότητα} body_encoding

Ίδιο με το `header_encoding', αλλά περιγράφει την κωδικοποίηση για το σώμα του μηνύματος email, το οποίο μπορεί να είναι διαφορετικό από την κωδικοποίηση της κεφαλίδας. Η τιμή @code{charset.SHORTEST} δεν επιτρέπεται για το `body_encoding'.
@end deffn

@geindex output_charset (ιδιότητα της email.charset.Charset)
@anchor{library/email charset email charset Charset output_charset}@anchor{3df9}
@deffn {Ιδιότητα} output_charset

Ορισμένα σύνολα χαρακτήρων πρέπει να μετατραπούν πριν χρησιμοποιηθούν σε κεφαλίδες ή σώματα email. Αν το `input_charset' είναι ένα από αυτά, αυτό το χαρακτηριστικό θα περιέχει το όνομα του συνόλου χαρακτήρων στο οποίο θα μετατραπεί η έξοδος. Αλλιώς, θα είναι @code{None}.
@end deffn

@geindex input_codec (ιδιότητα της email.charset.Charset)
@anchor{library/email charset email charset Charset input_codec}@anchor{3dfa}
@deffn {Ιδιότητα} input_codec

Το όνομα του Python codec που χρησιμοποιείται για την μετατροπή του `input_charset' σε Unicode. Αν δεν απαιτείται codec μετατροπής, αυτό το χαρακτηριστικό θα είναι @code{None}.
@end deffn

@geindex output_codec (ιδιότητα της email.charset.Charset)
@anchor{library/email charset email charset Charset output_codec}@anchor{3dfb}
@deffn {Ιδιότητα} output_codec

Το όνομα του Python codec που χρησιμοποιείται για την μετατροπή του Unicode στο `output_charset'. Αν δεν απαιτείται codec μετατροπής, αυτό το χαρακτηριστικό θα έχει την ίδια τιμή με το `input_codec'.
@end deffn

Στιγμιότυπα της κλάσης @ref{11b2,,Charset} διαθέτουν επίσης τις εξής μεθόδους:

@geindex get_body_encoding() (μέθοδος της email.charset.Charset)
@anchor{library/email charset email charset Charset get_body_encoding}@anchor{3dfc}
@deffn {Μέθοδος} get_body_encoding ()

Επιστρέφει τον κωδικοποιητή μεταφοράς περιεχομένου που χρησιμοποιείται για την κωδικοποίηση του σώματος.

Αυτή είναι είτε η συμβολοσειρά @code{quoted-printable} ή @code{base64}, ανάλογα με την κωδικοποίηση που χρησιμοποιείται, είτε είναι μια συνάρτηση, οπότε πρέπει να καλέσετε τη συνάρτηση με ένα μόνο όρισμα, το αντικείμενο Message που κωδικοποιείται. Η συνάρτηση θα πρέπει στη συνέχεια να ορίσει την κεφαλίδα @code{Content-Transfer-Encoding} η ίδια, σε ότι είναι κατάλληλο.

Επιστρέφει την συμβολοσειρά @code{quoted-printable} αν το `body_encoding' είναι @code{QP}, επιστρέφει την συμβολοσειρά @code{base64} αν το `body_encoding' είναι @code{BASE64}, και επιστρέφει την συμβολοσειρά @code{7bit} διαφορετικά.
@end deffn

@geindex get_output_charset() (μέθοδος της email.charset.Charset)
@anchor{library/email charset email charset Charset get_output_charset}@anchor{3dfd}
@deffn {Μέθοδος} get_output_charset ()

Επιστρέφει το σύνολο χαρακτήρων εξόδου.

Αυτό είναι το χαρακτηριστικό `output_charset' αν δεν είναι @code{None}, διαφορετικά είναι το `input_charset'.
@end deffn

@geindex header_encode() (μέθοδος της email.charset.Charset)
@anchor{library/email charset email charset Charset header_encode}@anchor{3dfe}
@deffn {Μέθοδος} header_encode (string)

Κωδικοποιεί την κεφαλίδα της συμβολοσειράς `string'.

Ο τύπος κωδικοποίησης (base64 ή quoted-printable) θα βασίζεται στο χαρακτηριστικό `header_encoding'.
@end deffn

@geindex header_encode_lines() (μέθοδος της email.charset.Charset)
@anchor{library/email charset email charset Charset header_encode_lines}@anchor{3dff}
@deffn {Μέθοδος} header_encode_lines (string, maxlengths)

Κωδικοποιεί την κεφαλίδα μιας συμβολοσειράς `string' μετατρέποντας το πρώτα σε bytes.

Αυτό είναι παρόμοιο με την μέθοδο @ref{3dfe,,header_encode()}, εκτός από το ότι το string τοποθετείται στις μέγιστες γραμμές μήκους που δίνονται από το όρισμα `maxlengths', το οποίο πρέπει να είναι ένας iterator: κάθε στοιχείο που επιστρέφεται από αυτόν τον iterator θα παρέχει το επόμενο μέγιστο μήκος γραμμής.
@end deffn

@geindex body_encode() (μέθοδος της email.charset.Charset)
@anchor{library/email charset email charset Charset body_encode}@anchor{3e00}
@deffn {Μέθοδος} body_encode (string)

Κωδικοποίηση σώματος της συμβολοσειράς `string'.

Ο τύπος κωδικοποίησης (base64 ή quoted-printable) θα βασίζεται στο χαρακτηριστικό `body_encoding'.
@end deffn

Η κλάση @ref{11b2,,Charset} παρέχει επίσης αρκετές μεθόδους για να υποστηρίξει τις τυπικές λειτουργίες και τις ενσωματωμένες συναρτήσεις.

@geindex __str__() (μέθοδος της email.charset.Charset)
@anchor{library/email charset email charset Charset __str__}@anchor{3e01}
@deffn {Μέθοδος} __str__ ()

Επιστρέφει το `input_charset' ως συμβολοσειρά που έχει μετατραπεί σε πεζά. Η μέθοδος @code{__repr__()} είναι ένα ψευδώνυμο για την μέθοδο @code{__str__()}.
@end deffn

@geindex __eq__() (μέθοδος της email.charset.Charset)
@anchor{library/email charset email charset Charset __eq__}@anchor{3e02}
@deffn {Μέθοδος} __eq__ (other)

Αυτή η μέθοδος σας επιτρέπει να συγκρίνετε δύο στιγμιότυπα της κλάσης @ref{11b2,,Charset} για ισότητα.
@end deffn

@geindex __ne__() (μέθοδος της email.charset.Charset)
@anchor{library/email charset email charset Charset __ne__}@anchor{3e03}
@deffn {Μέθοδος} __ne__ (other)

Αυτή η μέθοδος σας επιτρέπει να συγκρίνετε δύο στιγμιότυπα της κλάσης @ref{11b2,,Charset} για ανισότητα.
@end deffn
@end deffn

The @code{email.charset} module also provides the following functions for adding
new entries to the global character set, alias, and codec registries:

@geindex add_charset() (στη μονάδα email.charset)
@anchor{library/email charset email charset add_charset}@anchor{3e04}
@deffn {Συνάρτηση} email.charset.add_charset (charset, header_enc=None, body_enc=None, output_charset=None)

Προσθέστε ιδιότητες χαρακτήρων στο καθολικό μητρώο.

Το `charset' είναι το σύνολο χαρακτήρων εισόδου, και πρέπει να είναι το κανονικό όνομα ενός συνόλου χαρακτήρων.

Προαιρετικά το `header_enc' και `body_enc' είναι είτε @code{charset.QP} για κωδικοποίηση quoted-printable, @code{charset.BASE64} για κωδικοποίηση base64, @code{charset.SHORTEST} για την πιο σύντομη από τις κωδικοποιήσεις quoted-printable ή base64, ή @code{None} για καμία κωδικοποίηση. Το @code{SHORTEST} είναι έγκυρο μόνο για το `header_enc'. Η προεπιλογή είναι @code{None} για καμία κωδικοποίηση.

Προαιρετικό `output_charset' είναι το σύνολο χαρακτήρων στο οποίο θα πρέπει να βρίσκεται η έξοδος. Οι μετατροπές θα γίνονται από το εισερχόμενο σύνολο χαρακτήρων, σε Unicode, και στη συνέχεια στο σύνολο χαρακτήρων εξόδου όταν καλείται η μέθοδος @code{Charset.convert()}.  Η προεπιλογή είναι να εξάγεται το ίδιο σύνολο χαρακτήρων με το εισερχόμενο.

Τόσο το `input_charset' όσο και το `output_charset' πρέπει να έχουν καταχωρίσεις Unicode codec στη χαρτογράφηση χαρακτήρων προς codec του module· χρησιμοποιήστε την συνάρτηση @ref{3e05,,add_codec()} για να προσθέσετε codecs που το module δεν γνωρίζει. Δείτε την τεκμηρίωση του module @ref{1c,,codecs} για περισσότερες πληροφορίες.

Το καθολικό μητρώο συνόλων χαρακτήρων διατηρείται στο καθολικό dictionary του module @code{CHARSETS}.
@end deffn

@geindex add_alias() (στη μονάδα email.charset)
@anchor{library/email charset email charset add_alias}@anchor{3e06}
@deffn {Συνάρτηση} email.charset.add_alias (alias, canonical)

Προσθέστε ένα ψευδώνυμο συνόλου χαρακτήρων. Το `alias' είναι το όνομα του ψευδωνύμου, π.χ. @code{latin-1}. Το `canonical' είναι το κανονικό όνομα του συνόλου χαρακτήρων, π.χ. @code{iso-8859-1}.

Το παγκόσμιο μητρώο ψευδωνύμων συνόλων χαρακτήρων διατηρείται στο καθολικό λεξικό του module @code{ALIASES}.
@end deffn

@geindex add_codec() (στη μονάδα email.charset)
@anchor{library/email charset email charset add_codec}@anchor{3e05}
@deffn {Συνάρτηση} email.charset.add_codec (charset, codecname)

Προσθέστε έναν κωδικοποιητή που αντιστοιχεί χαρακτήρες από το δεδομένο σύνολο χαρακτήρων προς και από Unicode.

Το `charset' είναι το κανονικό όνομα ενός συνόλου χαρακτήρων. Το `codecname' είναι το όνομα ενός κωδικοποιητή Python, ως κατάλληλο για το δεύτερο όρισμα της μεθόδου @ref{ca7,,encode()} της κλάσης @ref{1df,,str}.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node email encoders Encoders,email utils Miscellaneous utilities,email charset Αναπαράσταση συνόλων χαρακτήρων,email — An email and MIME handling package
@anchor{library/email encoders doc}@anchor{3e07}@anchor{library/email encoders email-encoders-encoders}@anchor{3e08}@anchor{library/email encoders module-email encoders}@anchor{41}@anchor{library/email encoders translation-repo}@anchor{3e09}
@subsubsection @code{email.encoders}: Encoders


@geindex module; email.encoders

`Source code:' Lib/email/encoders.py@footnote{https://github.com/python/cpython/tree/main/Lib/email/encoders.py}


__________________________________________________________________


This module is part of the legacy (@code{Compat32}) email API.  In the
new API the functionality is provided by the `cte' parameter of
the @ref{1e54,,set_content()} method.

This module is deprecated in Python 3.  The functions provided here
should not be called explicitly since the @ref{11b1,,MIMEText}
class sets the content type and CTE header using the `_subtype' and `_charset'
values passed during the instantiation of that class.

The remaining text in this section is the original documentation of the module.

When creating @ref{780,,Message} objects from scratch, you often
need to encode the payloads for transport through compliant mail servers. This
is especially true for @code{image/*} and @code{text/*} type messages
containing binary data.

The @ref{3e,,email} package provides some convenient encoders in its
@code{encoders} module.  These encoders are actually used by the
@ref{3de9,,MIMEAudio} and @ref{3d7d,,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.

Note that these functions are not meaningful for a multipart message.  They
must be applied to individual subparts instead, and will raise a
@ref{291,,TypeError} if passed a message whose type is multipart.

Here are the encoding functions provided:

@geindex encode_quopri() (στη μονάδα email.encoders)
@anchor{library/email encoders email encoders encode_quopri}@anchor{3e0a}
@deffn {Συνάρτηση} email.encoders.encode_quopri (msg)

Encodes the payload into quoted-printable form and sets the
@code{Content-Transfer-Encoding} header to @code{quoted-printable} @footnote{
Note that encoding with @ref{3e0a,,encode_quopri()} also encodes all tabs and space
characters in the data.
}.
This is a good encoding to use when most of your payload is normal printable
data, but contains a few unprintable characters.
@end deffn

@geindex encode_base64() (στη μονάδα email.encoders)
@anchor{library/email encoders email encoders encode_base64}@anchor{3e0b}
@deffn {Συνάρτηση} email.encoders.encode_base64 (msg)

Encodes the payload into base64 form and sets the
@code{Content-Transfer-Encoding} header to @code{base64}.  This is a good
encoding to use when most of your payload is unprintable data since it is a more
compact form than quoted-printable.  The drawback of base64 encoding is that it
renders the text non-human readable.
@end deffn

@geindex encode_7or8bit() (στη μονάδα email.encoders)
@anchor{library/email encoders email encoders encode_7or8bit}@anchor{3e0c}
@deffn {Συνάρτηση} email.encoders.encode_7or8bit (msg)

This doesn’t actually modify the message’s payload, but it does set the
@code{Content-Transfer-Encoding} header to either @code{7bit} or @code{8bit} as
appropriate, based on the payload data.
@end deffn

@geindex encode_noop() (στη μονάδα email.encoders)
@anchor{library/email encoders email encoders encode_noop}@anchor{3e0d}
@deffn {Συνάρτηση} email.encoders.encode_noop (msg)

This does nothing; it doesn’t even set the
@code{Content-Transfer-Encoding} header.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node email utils Miscellaneous utilities,email iterators Iterators,email encoders Encoders,email — An email and MIME handling package
@anchor{library/email utils doc}@anchor{3e0e}@anchor{library/email utils email-utils-miscellaneous-utilities}@anchor{3e0f}@anchor{library/email utils module-email utils}@anchor{53}@anchor{library/email utils translation-repo}@anchor{3e10}
@subsubsection @code{email.utils}: Miscellaneous utilities


@geindex module; email.utils

`Source code:' Lib/email/utils.py@footnote{https://github.com/python/cpython/tree/main/Lib/email/utils.py}


__________________________________________________________________


There are a couple of useful utilities provided in the @code{email.utils}
module:

@geindex localtime() (στη μονάδα email.utils)
@anchor{library/email utils email utils localtime}@anchor{56f}
@deffn {Συνάρτηση} 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{6e7,,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.


Added in version 3.3.



Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.14: The `isdst' parameter.

@end deffn

@geindex make_msgid() (στη μονάδα email.utils)
@anchor{library/email utils email utils make_msgid}@anchor{3e11}
@deffn {Συνάρτηση} email.utils.make_msgid (idstring=None, domain=None)

Returns a string suitable for an 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}-compliant
@code{Message-ID} header.  Optional `idstring' if given, is a string
used to strengthen the uniqueness of the message id.  Optional `domain' if
given provides the portion of the msgid after the “@@”.  The default is the
local hostname.  It is not normally necessary to override this default, but
may be useful certain cases, such as a constructing distributed system that
uses a consistent domain name across multiple hosts.


Άλλαξε στην έκδοση 3.2: Added the `domain' keyword.

@end deffn

The remaining functions are part of the legacy (@code{Compat32}) email API.  There
is no need to directly use these with the new API, since the parsing and
formatting they provide is done automatically by the header parsing machinery
of the new API.

@geindex quote() (στη μονάδα email.utils)
@anchor{library/email utils email utils quote}@anchor{3e12}
@deffn {Συνάρτηση} email.utils.quote (str)

Return a new string with backslashes in `str' replaced by two backslashes, and
double quotes replaced by backslash-double quote.
@end deffn

@geindex unquote() (στη μονάδα email.utils)
@anchor{library/email utils email utils unquote}@anchor{3d22}
@deffn {Συνάρτηση} email.utils.unquote (str)

Return a new string which is an `unquoted' version of `str'. If `str' ends and
begins with double quotes, they are stripped off.  Likewise if `str' ends and
begins with angle brackets, they are stripped off.
@end deffn

@geindex parseaddr() (στη μονάδα email.utils)
@anchor{library/email utils email utils parseaddr}@anchor{6f9}
@deffn {Συνάρτηση} email.utils.parseaddr (address, *, strict=True)

Parse address – which should be the value of some address-containing field such
as @code{To} or @code{Cc} – into its constituent `realname' and
`email address' parts.  Returns a tuple of that information, unless the parse
fails, in which case a 2-tuple of @code{('@w{'}, '@w{'})} is returned.

If `strict' is true, use a strict parser which rejects malformed inputs.


Άλλαξε στην έκδοση 3.13: Add `strict' optional parameter and reject malformed inputs by default.

@end deffn

@geindex formataddr() (στη μονάδα email.utils)
@anchor{library/email utils email utils formataddr}@anchor{1543}
@deffn {Συνάρτηση} email.utils.formataddr (pair, charset='utf-8')

The inverse of @ref{6f9,,parseaddr()}, this takes a 2-tuple of the form @code{(realname,
email_address)} and returns the string value suitable for a @code{To} or
@code{Cc} header.  If the first element of `pair' is false, then the
second element is returned unmodified.

Optional `charset' is the character set that will be used in the 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html}
encoding of the @code{realname} if the @code{realname} contains non-ASCII
characters.  Can be an instance of @ref{1df,,str} or a
@ref{11b2,,Charset}.  Defaults to @code{utf-8}.


Άλλαξε στην έκδοση 3.3: Added the `charset' option.

@end deffn

@geindex getaddresses() (στη μονάδα email.utils)
@anchor{library/email utils email utils getaddresses}@anchor{6f8}
@deffn {Συνάρτηση} 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{3dca,,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


Άλλαξε στην έκδοση 3.13: Add `strict' optional parameter and reject malformed inputs by default.

@end deffn

@geindex parsedate() (στη μονάδα email.utils)
@anchor{library/email utils email utils parsedate}@anchor{3e13}
@deffn {Συνάρτηση} email.utils.parsedate (date)

Attempts to parse a date according to the rules in 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}. however, some
mailers don’t follow that format as specified, so @code{parsedate()} tries to
guess correctly in such cases.  `date' is a string containing an 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}
date, such as  @code{"Mon, 20 Nov 1995 19:12:08 -0500"}.  If it succeeds in parsing
the date, @code{parsedate()} returns a 9-tuple that can be passed directly to
@ref{1591,,time.mktime()}; otherwise @code{None} will be returned.  Note that indexes 6,
7, and 8 of the result tuple are not usable.
@end deffn

@geindex parsedate_tz() (στη μονάδα email.utils)
@anchor{library/email utils email utils parsedate_tz}@anchor{1e1a}
@deffn {Συνάρτηση} email.utils.parsedate_tz (date)

Performs the same function as @ref{3e13,,parsedate()}, but returns either @code{None} or
a 10-tuple; the first 9 elements make up a tuple that can be passed directly to
@ref{1591,,time.mktime()}, and the tenth is the offset of the date’s timezone from UTC
(which is the official term for Greenwich Mean Time) @footnote{
Note that the sign of the timezone offset is the opposite of the sign of the
@code{time.timezone} variable for the same timezone; the latter variable follows
the POSIX standard while this module follows 
@geindex RFC; RFC 2822
@uref{https://datatracker.ietf.org/doc/html/rfc2822.html,RFC 2822}.
}.  If the input string
has no timezone, the last element of the tuple returned is @code{0}, which represents
UTC. Note that indexes 6, 7, and 8 of the result tuple are not usable.
@end deffn

@geindex parsedate_to_datetime() (στη μονάδα email.utils)
@anchor{library/email utils email utils parsedate_to_datetime}@anchor{146b}
@deffn {Συνάρτηση} email.utils.parsedate_to_datetime (date)

The inverse of @ref{146a,,format_datetime()}.  Performs the same function as
@ref{3e13,,parsedate()}, but on success returns a @ref{6e7,,datetime};
otherwise @code{ValueError} is raised if `date' contains an invalid value such
as an hour greater than 23 or a timezone offset not between -24 and 24 hours.
If the input date has a timezone of @code{-0000}, the @code{datetime} will be a naive
@code{datetime}, and if the date is conforming to the RFCs it will represent a
time in UTC but with no indication of the actual source timezone of the
message the date comes from.  If the input date has any other valid timezone
offset, the @code{datetime} will be an aware @code{datetime} with the
corresponding a @ref{146c,,timezone} @ref{9d8,,tzinfo}.


Added in version 3.3.

@end deffn

@geindex mktime_tz() (στη μονάδα email.utils)
@anchor{library/email utils email utils mktime_tz}@anchor{3e14}
@deffn {Συνάρτηση} email.utils.mktime_tz (tuple)

Turn a 10-tuple as returned by @ref{1e1a,,parsedate_tz()} into a UTC
timestamp (seconds since the Epoch).  If the timezone item in the
tuple is @code{None}, assume local time.
@end deffn

@geindex formatdate() (στη μονάδα email.utils)
@anchor{library/email utils email utils formatdate}@anchor{180c}
@deffn {Συνάρτηση} email.utils.formatdate (timeval=None, localtime=False, usegmt=False)

Returns a date string as per 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}, e.g.:

@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{1569,,time.gmtime()} and @ref{189b,,time.localtime()}, otherwise the current time is
used.

Optional `localtime' is a flag that when @code{True}, interprets `timeval', and
returns a date relative to the local timezone instead of UTC, properly taking
daylight savings time into account. The default is @code{False} meaning UTC is
used.

Optional `usegmt' is a flag that when @code{True}, outputs a  date string with the
timezone as an ascii string @code{GMT}, rather than a numeric @code{-0000}. This is
needed for some protocols (such as HTTP). This only applies when `localtime' is
@code{False}.  The default is @code{False}.
@end deffn

@geindex format_datetime() (στη μονάδα email.utils)
@anchor{library/email utils email utils format_datetime}@anchor{146a}
@deffn {Συνάρτηση} email.utils.format_datetime (dt, usegmt=False)

Like @code{formatdate}, but the input is a @ref{33,,datetime} instance.  If it is
a naive datetime, it is assumed to be «UTC with no information about the
source timezone», and the conventional @code{-0000} is used for the timezone.
If it is an aware @code{datetime}, then the numeric timezone offset is used.
If it is an aware timezone with offset zero, then `usegmt' may be set to
@code{True}, in which case the string @code{GMT} is used instead of the numeric
timezone offset.  This provides a way to generate standards conformant HTTP
date headers.


Added in version 3.3.

@end deffn

@geindex decode_rfc2231() (στη μονάδα email.utils)
@anchor{library/email utils email utils decode_rfc2231}@anchor{3e15}
@deffn {Συνάρτηση} email.utils.decode_rfc2231 (s)

Decode the string `s' according to 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}.
@end deffn

@geindex encode_rfc2231() (στη μονάδα email.utils)
@anchor{library/email utils email utils encode_rfc2231}@anchor{3e16}
@deffn {Συνάρτηση} email.utils.encode_rfc2231 (s, charset=None, language=None)

Encode the string `s' according to 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}.  Optional `charset' and
`language', if given is the character set name and language name to use.  If
neither is given, `s' is returned as-is.  If `charset' is given but `language'
is not, the string is encoded using the empty string for `language'.
@end deffn

@geindex collapse_rfc2231_value() (στη μονάδα email.utils)
@anchor{library/email utils email utils collapse_rfc2231_value}@anchor{3dd7}
@deffn {Συνάρτηση} email.utils.collapse_rfc2231_value (value, errors='replace', fallback_charset='us-ascii')

When a header parameter is encoded in 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} format,
@ref{3dd6,,Message.get_param} may return a
3-tuple containing the character set,
language, and value.  @code{collapse_rfc2231_value()} turns this into a unicode
string.  Optional `errors' is passed to the `errors' argument of @ref{1df,,str}’s
@ref{ca7,,encode()} method; it defaults to @code{'replace'}.  Optional
`fallback_charset' specifies the character set to use if the one in the
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} header is not known by Python; it defaults to @code{'us-ascii'}.

For convenience, if the `value' passed to @code{collapse_rfc2231_value()} is not
a tuple, it should be a string and it is returned unquoted.
@end deffn

@geindex decode_params() (στη μονάδα email.utils)
@anchor{library/email utils email utils decode_params}@anchor{1a2f}
@deffn {Συνάρτηση} email.utils.decode_params (params)

Decode parameters list according to 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}.  `params' is a sequence of
2-tuples containing elements of the form @code{(content-type, string-value)}.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node email iterators Iterators,,email utils Miscellaneous utilities,email — An email and MIME handling package
@anchor{library/email iterators doc}@anchor{3e17}@anchor{library/email iterators email-iterators-iterators}@anchor{3e18}@anchor{library/email iterators module-email iterators}@anchor{46}@anchor{library/email iterators translation-repo}@anchor{3e19}
@subsubsection @code{email.iterators}: Iterators


@geindex module; email.iterators

`Source code:' Lib/email/iterators.py@footnote{https://github.com/python/cpython/tree/main/Lib/email/iterators.py}


__________________________________________________________________


Iterating over a message object tree is fairly easy with the
@ref{3ddf,,Message.walk} method.  The
@code{email.iterators} module provides some useful higher level iterations over
message object trees.

@geindex body_line_iterator() (στη μονάδα email.iterators)
@anchor{library/email iterators email iterators body_line_iterator}@anchor{3e1a}
@deffn {Συνάρτηση} email.iterators.body_line_iterator (msg, decode=False)

This iterates over all the payloads in all the subparts of `msg', returning the
string payloads line-by-line.  It skips over all the subpart headers, and it
skips over any subpart with a payload that isn’t a Python string.  This is
somewhat equivalent to reading the flat text representation of the message from
a file using @ref{2296,,readline()}, skipping over all the
intervening headers.

Optional `decode' is passed through to @ref{1576,,Message.get_payload}.
@end deffn

@geindex typed_subpart_iterator() (στη μονάδα email.iterators)
@anchor{library/email iterators email iterators typed_subpart_iterator}@anchor{3e1b}
@deffn {Συνάρτηση} email.iterators.typed_subpart_iterator (msg, maintype='text', subtype=None)

This iterates over all the subparts of `msg', returning only those subparts that
match the MIME type specified by `maintype' and `subtype'.

Note that `subtype' is optional; if omitted, then subpart MIME type matching is
done only with the main type.  `maintype' is optional too; it defaults to
@code{text}.

Thus, by default @code{typed_subpart_iterator()} returns each subpart that has a
MIME type of @code{text/*}.
@end deffn

The following function has been added as a useful debugging tool.  It should
`not' be considered part of the supported public interface for the package.

@geindex _structure() (στη μονάδα email.iterators)
@anchor{library/email iterators email iterators _structure}@anchor{3e1c}
@deffn {Συνάρτηση} email.iterators._structure (msg, fp=None, level=0, include_default=False)

Prints an indented representation of the content types of the message object
structure.  For example:

@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()

Optional `fp' is a file-like object to print the output to.  It must be
suitable for Python’s @ref{131f,,print()} function.  `level' is used internally.
`include_default', if true, prints the default type as well.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{d2,,smtplib}

SMTP (Simple Mail Transport Protocol) client

@item Module @ref{b1,,poplib}

POP (Post Office Protocol) client

@item Module @ref{77,,imaplib}

IMAP (Internet Message Access Protocol) client

@item Module @ref{8e,,mailbox}

Tools for creating, reading, and managing collections of messages on disk
using a variety standard formats.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node json — JSON encoder and decoder,mailbox — Manipulate mailboxes in various formats,email — An email and MIME handling package,Internet Data Handling
@anchor{library/json doc}@anchor{3e1d}@anchor{library/json json-json-encoder-and-decoder}@anchor{3e1e}@anchor{library/json module-json}@anchor{85}@anchor{library/json translation-repo}@anchor{3e1f}
@subsection @code{json} — JSON encoder and decoder


@geindex module; json

`Source code:' Lib/json/__init__.py@footnote{https://github.com/python/cpython/tree/main/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{
As noted in @uref{https://www.rfc-editor.org/errata_search.php?rfc=7159,the errata for RFC 7159},
JSON permits literal U+2028 (LINE SEPARATOR) and
U+2029 (PARAGRAPH SEPARATOR) characters in strings, whereas JavaScript
(as of ECMAScript Edition 5.1) does not.
} ).

@cartouche
@quotation Σημείωση 
The term «object» in the context of JSON processing in Python can be
ambiguous. All values in Python are objects. In JSON, an object refers to
any data wrapped in curly braces, similar to a Python dictionary.
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
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

This module exposes an API familiar to users of the standard library
@ref{90,,marshal} and @ref{ab,,pickle} modules.

Encoding basic Python object hierarchies:

@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

Compact encoding:

@example
>>> import json
>>> json.dumps([1, 2, 3, @{'4': 5, '6': 7@}], separators=(',', ':'))
'[1,2,3,@{"4":5,"6":7@}]'
@end example

Pretty printing:

@example
>>> import json
>>> print(json.dumps(@{'6': 7, '4': 5@}, sort_keys=True, indent=4))
@{
    "4": 5,
    "6": 7
@}
@end example

Customizing 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

Decoding 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

Customizing JSON object decoding:

@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

Extending @ref{10fc,,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

Using @code{json} from the shell to validate and pretty-print:

@example
$ echo '@{"json":"obj"@}' | python -m json
@{
    "json": "obj"
@}
$ echo '@{1.2:3.4@}' | python -m json
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
@end example

See @ref{4cb,,Command-line interface} for detailed documentation.

@cartouche
@quotation Σημείωση 
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 Σημείωση 
This module’s encoders and decoders preserve input and output order by
default.  Order is only lost if the underlying containers are unordered.
@end quotation
@end cartouche

@menu
* Basic Usage:: 
* Encoders and Decoders:: 
* Exceptions: Exceptions<18>. 
* Standard Compliance and Interoperability:: 
* Command-line interface: Command-line interface<4>. 

@end menu

@node Basic Usage,Encoders and Decoders,,json — JSON encoder and decoder
@anchor{library/json basic-usage}@anchor{3e20}
@subsubsection Basic Usage


@geindex dump() (στη μονάδα json)
@anchor{library/json json dump}@anchor{10fb}
@deffn {Συνάρτηση} 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{19b1,,file-like object}) using this @ref{3e21,,Python-to-JSON conversion table}.

@cartouche
@quotation Σημείωση 
Unlike @ref{ab,,pickle} and @ref{90,,marshal}, JSON is not a framed protocol,
so trying to serialize multiple objects with repeated calls to
@code{dump()} using the same `fp' will result in an invalid JSON file.
@end quotation
@end cartouche

@*Παράμετροι: 

@itemize *

@item 
@code{obj} (@ref{e4d,,object}) – The Python object to be serialized.

@item 
@code{fp} (@ref{19b1,,file-like object}) – The file-like object `obj' will be serialized to.
The @code{json} module always produces @ref{1df,,str} objects,
not @ref{1c7,,bytes} objects,
therefore @code{fp.write()} must support @code{str} input.

@item 
@code{skipkeys} (@ref{5ef,,bool}) – If @code{True}, keys that are not of a basic type
(@ref{1df,,str}, @ref{326,,int}, @ref{327,,float}, @code{bool}, @code{None})
will be skipped instead of raising a @ref{291,,TypeError}.
Default @code{False}.

@item 
@code{ensure_ascii} (@ref{5ef,,bool}) – If @code{True} (the default), the output is guaranteed to
have all incoming non-ASCII and non-printable characters escaped.
If @code{False}, all characters will be outputted as-is, except for
the characters that must be escaped: quotation mark, reverse solidus,
and the control characters U+0000 through U+001F.

@item 
@code{check_circular} (@ref{5ef,,bool}) – If @code{False}, the circular reference check for container types is skipped
and a circular reference will result in a @ref{1121,,RecursionError} (or worse).
Default @code{True}.

@item 
@code{allow_nan} (@ref{5ef,,bool}) – If @code{False}, serialization of out-of-range @ref{327,,float} values
(@code{nan}, @code{inf}, @code{-inf}) will result in a @ref{277,,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{10fc,,JSONEncoder} subclass) – If set, a custom JSON encoder with the
@ref{3e22,,default()} method overridden,
for serializing into custom datatypes.
If @code{None} (the default), @code{JSONEncoder} is used.

@item 
@code{indent} (@ref{326,,int}@code{ | }@ref{1df,,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{1ce,,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{2fa4,,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{291,,TypeError}.
If @code{None} (the default), @code{TypeError} is raised.

@item 
@code{sort_keys} (@ref{5ef,,bool}) – If @code{True}, dictionaries will be outputted sorted by key.
Default @code{False}.
@end itemize



Άλλαξε στην έκδοση 3.2: Allow strings for `indent' in addition to integers.



Άλλαξε στην έκδοση 3.4: Use @code{(',', ': ')} as default if `indent' is not @code{None}.



Άλλαξε στην έκδοση 3.6: All optional parameters are now @ref{7a3,,keyword-only}.

@end deffn

@geindex dumps() (στη μονάδα json)
@anchor{library/json json dumps}@anchor{248}
@deffn {Συνάρτηση} 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)

Serialize `obj' to a JSON formatted @ref{1df,,str} using this @ref{3e21,,conversion table}.  The arguments have the same meaning as in
@ref{10fb,,dump()}.

@cartouche
@quotation Σημείωση 
Keys in key/value pairs of JSON are always of the type @ref{1df,,str}. When
a dictionary is converted into JSON, all the keys of the dictionary are
coerced to strings. As a result of this, if a dictionary is converted
into JSON and then back into a dictionary, the dictionary may not equal
the original one. That is, @code{loads(dumps(x)) != x} if x has non-string
keys.
@end quotation
@end cartouche
@end deffn

@geindex load() (στη μονάδα json)
@anchor{library/json json load}@anchor{22e}
@deffn {Συνάρτηση} json.load (fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, array_hook=None, **kw)

Deserialize `fp' to a Python object
using the @ref{3e23,,JSON-to-Python conversion table}.

@*Παράμετροι: 

@itemize *

@item 
@code{fp} (@ref{19b1,,file-like object}) – A @code{.read()}-supporting @ref{225c,,text file} or @ref{225d,,binary file}
containing the JSON document to be deserialized.

@item 
@code{cls} (a @ref{10fd,,JSONDecoder} subclass) – If set, a custom JSON decoder.
Additional keyword arguments to @code{load()}
will be passed to the constructor of `cls'.
If @code{None} (the default), @code{JSONDecoder} is used.

@item 
@code{object_hook} (@ref{2fa4,,callable} | None) – If set, a function that is called with the result of
any JSON object literal decoded (a @ref{188,,dict}).
The return value of this function will be used
instead of the @code{dict}.
This feature can be used to implement custom decoders,
for example JSON-RPC@footnote{https://www.jsonrpc.org} class hinting.
Default @code{None}.

@item 
@code{object_pairs_hook} (@ref{2fa4,,callable} | None) – If set, a function that is called with the result of
any JSON object literal decoded with an ordered list of pairs.
The return value of this function will be used
instead of the @ref{188,,dict}.
This feature can be used to implement custom decoders.
If `object_hook' is also set, `object_pairs_hook' takes priority.
Default @code{None}.

@item 
@code{array_hook} (@ref{2fa4,,callable} | None) – If set, a function that is called with the result of
any JSON array literal decoded with as a Python list.
The return value of this function will be used
instead of the @ref{4d9,,list}.
This feature can be used to implement custom decoders.
Default @code{None}.

@item 
@code{parse_float} (@ref{2fa4,,callable} | None) – If set, a function that is called with
the string of every JSON float to be decoded.
If @code{None} (the default), it is equivalent to @code{float(num_str)}.
This can be used to parse JSON floats into custom datatypes,
for example @ref{1c2,,decimal.Decimal}.

@item 
@code{parse_int} (@ref{2fa4,,callable} | None) – If set, a function that is called with
the string of every JSON int to be decoded.
If @code{None} (the default), it is equivalent to @code{int(num_str)}.
This can be used to parse JSON integers into custom datatypes,
for example @ref{327,,float}.

@item 
@code{parse_constant} (@ref{2fa4,,callable} | None) – If set, a function that is called with one of the following strings:
@code{'-Infinity'}, @code{'Infinity'}, or @code{'NaN'}.
This can be used to raise an exception
if invalid JSON numbers are encountered.
Default @code{None}.
@end itemize


@*Προκαλεί: 

@itemize *

@item 
@ref{11d5,,JSONDecodeError} – When the data being deserialized is not a valid JSON document.

@item 
@ref{dd7,,UnicodeDecodeError} – When the data being deserialized does not contain
UTF-8, UTF-16 or UTF-32 encoded data.
@end itemize



Άλλαξε στην έκδοση 3.1: 


@itemize *

@item 
Added the optional `object_pairs_hook' parameter.

@item 
`parse_constant' doesn’t get called on “null”, “true”, “false” anymore.
@end itemize



Άλλαξε στην έκδοση 3.6: 


@itemize *

@item 
All optional parameters are now @ref{7a3,,keyword-only}.

@item 
`fp' can now be a @ref{225d,,binary file}.
The input encoding should be UTF-8, UTF-16 or UTF-32.
@end itemize



Άλλαξε στην έκδοση 3.11: The default `parse_int' of @ref{326,,int()} now limits the maximum length of
the integer string via the interpreter’s @ref{9ec,,integer string conversion length limitation} to help avoid denial
of service attacks.



Άλλαξε στην έκδοση 3.15: Added the optional `array_hook' parameter.

@end deffn

@geindex loads() (στη μονάδα json)
@anchor{library/json json loads}@anchor{22f}
@deffn {Συνάρτηση} json.loads (s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, array_hook=None, **kw)

Identical to @ref{22e,,load()}, but instead of a file-like object,
deserialize `s' (a @ref{1df,,str}, @ref{1c7,,bytes} or @ref{1c6,,bytearray}
instance containing a JSON document) to a Python object using this
@ref{3e23,,conversion table}.


Άλλαξε στην έκδοση 3.6: `s' can now be of type @ref{1c7,,bytes} or @ref{1c6,,bytearray}. The
input encoding should be UTF-8, UTF-16 or UTF-32.



Άλλαξε στην έκδοση 3.9: The keyword argument `encoding' has been removed.

@end deffn

@node Encoders and Decoders,Exceptions<18>,Basic Usage,json — JSON encoder and decoder
@anchor{library/json encoders-and-decoders}@anchor{3e24}
@subsubsection Encoders and Decoders


@geindex JSONDecoder (κλάση σε json)
@anchor{library/json json JSONDecoder}@anchor{10fd}
@deffn {Κλάση} json.JSONDecoder (*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None, array_hook=None)

Simple JSON decoder.

Performs the following translations in decoding by default:
@anchor{library/json json-to-py-table}@anchor{3e23}

@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 
@headitem

JSON

@tab

Python

@item

object

@tab

dict

@item

array

@tab

list

@item

string

@tab

str

@item

number (int)

@tab

int

@item

number (real)

@tab

float

@item

true

@tab

True

@item

false

@tab

False

@item

null

@tab

None

@end multitable


It also understands @code{NaN}, @code{Infinity}, and @code{-Infinity} as their
corresponding @code{float} values, which is outside the JSON spec.

`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{188,,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{188,,dict}.  This feature can be used to implement custom decoders.  If
`object_hook' is also defined, the `object_pairs_hook' takes priority.


Άλλαξε στην έκδοση 3.1: Added support for `object_pairs_hook'.


`array_hook' is an optional function that will be called with the
result of every JSON array decoded as a list. The return value of
`array_hook' will be used instead of the @ref{4d9,,list}. This feature can be
used to implement custom decoders.


Άλλαξε στην έκδοση 3.15: Added support for `array_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{1c2,,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{327,,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.

If `strict' is false (@code{True} is the default), then control characters
will be allowed inside strings.  Control characters in this context are
those with character codes in the 0–31 range, including @code{'\t'} (tab),
@code{'\n'}, @code{'\r'} and @code{'\0'}.

If the data being deserialized is not a valid JSON document, a
@ref{11d5,,JSONDecodeError} will be raised.


Άλλαξε στην έκδοση 3.6: All parameters are now @ref{7a3,,keyword-only}.


@geindex decode() (μέθοδος της json.JSONDecoder)
@anchor{library/json json JSONDecoder decode}@anchor{3e25}
@deffn {Μέθοδος} decode (s)

Return the Python representation of `s' (a @ref{1df,,str} instance
containing a JSON document).

@ref{11d5,,JSONDecodeError} will be raised if the given JSON document is not
valid.
@end deffn

@geindex raw_decode() (μέθοδος της json.JSONDecoder)
@anchor{library/json json JSONDecoder raw_decode}@anchor{3e26}
@deffn {Μέθοδος} raw_decode (s)

Decode a JSON document from `s' (a @ref{1df,,str} beginning with a
JSON document) and return a 2-tuple of the Python representation
and the index in `s' where the document ended.

This can be used to decode a JSON document from a string that may have
extraneous data at the end.
@end deffn
@end deffn

@geindex JSONEncoder (κλάση σε json)
@anchor{library/json json JSONEncoder}@anchor{10fc}
@deffn {Κλάση} json.JSONEncoder (*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Extensible JSON encoder for Python data structures.

Supports the following objects and types by default:
@anchor{library/json py-to-json-table}@anchor{3e21}

@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Python

@tab

JSON

@item

dict

@tab

object

@item

list, tuple

@tab

array

@item

str

@tab

string

@item

int, float, int- & float-derived Enums

@tab

number

@item

True

@tab

true

@item

False

@tab

false

@item

None

@tab

null

@end multitable



Άλλαξε στην έκδοση 3.4: Added support for int- and float-derived Enum classes.


To extend this to recognize other objects, subclass and implement a
@ref{3e22,,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{291,,TypeError}).

If `skipkeys' is false (the default), a @ref{291,,TypeError} will be raised when
trying to encode keys that are not @ref{1df,,str}, @ref{326,,int}, @ref{327,,float},
@ref{5ef,,bool} or @code{None}.  If `skipkeys' is true, such items are simply skipped.

If `ensure_ascii' is true (the default), the output is guaranteed to
have all incoming non-ASCII and non-printable characters escaped.
If `ensure_ascii' is false, all characters will be output as-is, except for
the characters that must be escaped: quotation mark, reverse solidus,
and the control characters U+0000 through U+001F.

If `check_circular' is true (the default), then lists, dicts, and custom
encoded objects will be checked for circular references during encoding to
prevent an infinite recursion (which would cause a @ref{1121,,RecursionError}).
Otherwise, no such check takes place.

If `allow_nan' is true (the default), then @code{NaN}, @code{Infinity}, and
@code{-Infinity} will be encoded as such.  This behavior is not JSON
specification compliant, but is consistent with most JavaScript based
encoders and decoders.  Otherwise, it will be a @ref{277,,ValueError} to encode
such floats.

If `sort_keys' is true (default: @code{False}), then the output of dictionaries
will be sorted by key; this is useful for regression tests to ensure that
JSON serializations can be compared on a day-to-day basis.

If `indent' is a non-negative integer or string, then JSON array elements and
object members will be pretty-printed with that indent level.  An indent level
of 0, negative, or @code{""} will only insert newlines.  @code{None} (the default)
selects the most compact representation. Using a positive integer indent
indents that many spaces per level.  If `indent' is a string (such as @code{"\t"}),
that string is used to indent each level.


Άλλαξε στην έκδοση 3.2: Allow strings for `indent' in addition to integers.


If specified, `separators' should be an @code{(item_separator, key_separator)}
tuple.  The default is @code{(', ', ': ')} if `indent' is @code{None} and
@code{(',', ': ')} otherwise.  To get the most compact JSON representation,
you should specify @code{(',', ':')} to eliminate whitespace.


Άλλαξε στην έκδοση 3.4: Use @code{(',', ': ')} as default if `indent' is not @code{None}.


If specified, `default' should be a function that gets called for objects that
can’t otherwise be serialized.  It should return a JSON encodable version of
the object or raise a @ref{291,,TypeError}.  If not specified, @code{TypeError}
is raised.


Άλλαξε στην έκδοση 3.6: All parameters are now @ref{7a3,,keyword-only}.


@geindex default() (μέθοδος της json.JSONEncoder)
@anchor{library/json json JSONEncoder default}@anchor{3e22}
@deffn {Μέθοδος} default (o)

Implement this method in a subclass such that it returns a serializable
object for `o', or calls the base implementation (to raise a
@ref{291,,TypeError}).

For example, to support arbitrary iterators, you could implement
@code{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() (μέθοδος της json.JSONEncoder)
@anchor{library/json json JSONEncoder encode}@anchor{3e27}
@deffn {Μέθοδος} encode (o)

Return a JSON string representation of a Python data structure, `o'.  For
example:

@example
>>> json.JSONEncoder().encode(@{"foo": ["bar", "baz"]@})
'@{"foo": ["bar", "baz"]@}'
@end example
@end deffn

@geindex iterencode() (μέθοδος της json.JSONEncoder)
@anchor{library/json json JSONEncoder iterencode}@anchor{19b3}
@deffn {Μέθοδος} iterencode (o)

Encode the given object, `o', and yield each string representation as
available.  For example:

@example
for chunk in json.JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)
@end example
@end deffn
@end deffn

@node Exceptions<18>,Standard Compliance and Interoperability,Encoders and Decoders,json — JSON encoder and decoder
@anchor{library/json exceptions}@anchor{3e28}
@subsubsection Exceptions


@geindex JSONDecodeError
@anchor{library/json json JSONDecodeError}@anchor{11d5}
@deffn {Εξαίρεση} json.JSONDecodeError (msg, doc, pos)

Subclass of @ref{277,,ValueError} with the following additional attributes:

@geindex msg (ιδιότητα της json.JSONDecodeError)
@anchor{library/json json JSONDecodeError msg}@anchor{3e29}
@deffn {Ιδιότητα} msg

The unformatted error message.
@end deffn

@geindex doc (ιδιότητα της json.JSONDecodeError)
@anchor{library/json json JSONDecodeError doc}@anchor{3e2a}
@deffn {Ιδιότητα} doc

The JSON document being parsed.
@end deffn

@geindex pos (ιδιότητα της json.JSONDecodeError)
@anchor{library/json json JSONDecodeError pos}@anchor{3e2b}
@deffn {Ιδιότητα} pos

The start index of `doc' where parsing failed.
@end deffn

@geindex lineno (ιδιότητα της json.JSONDecodeError)
@anchor{library/json json JSONDecodeError lineno}@anchor{3e2c}
@deffn {Ιδιότητα} lineno

The line corresponding to `pos'.
@end deffn

@geindex colno (ιδιότητα της json.JSONDecodeError)
@anchor{library/json json JSONDecodeError colno}@anchor{3e2d}
@deffn {Ιδιότητα} colno

The column corresponding to `pos'.
@end deffn


Added in version 3.5.

@end deffn

@node Standard Compliance and Interoperability,Command-line interface<4>,Exceptions<18>,json — JSON encoder and decoder
@anchor{library/json standard-compliance-and-interoperability}@anchor{3e2e}
@subsubsection Standard Compliance and Interoperability


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{10fc,,JSONEncoder} and @ref{10fd,,JSONDecoder} subclasses, and
parameters other than those explicitly mentioned, are not considered.

This module does not comply with the RFC in a strict fashion, implementing some
extensions that are valid JavaScript but not valid JSON.  In particular:


@itemize -

@item 
Infinite and NaN number values are accepted and output;

@item 
Repeated names within an object are accepted, and only the value of the last
name-value pair is used.
@end itemize

Since the RFC permits RFC-compliant parsers to accept input texts that are not
RFC-compliant, this module’s deserializer is technically RFC-compliant under
default settings.

@menu
* Character Encodings:: 
* Infinite and NaN Number Values:: 
* Repeated Names Within an Object:: 
* Top-level Non-Object@comma{} Non-Array Values: Top-level Non-Object Non-Array Values. 
* Implementation Limitations:: 

@end menu

@node Character Encodings,Infinite and NaN Number Values,,Standard Compliance and Interoperability
@anchor{library/json character-encodings}@anchor{3e2f}
@subsubsection Character Encodings


The RFC requires that JSON be represented using either UTF-8, UTF-16, or
UTF-32, with UTF-8 being the recommended default for maximum interoperability.

As permitted, though not required, by the RFC, this module’s serializer sets
`ensure_ascii=True' by default, thus escaping the output so that the resulting
strings only contain printable ASCII characters.

Other than the `ensure_ascii' parameter, this module is defined strictly in
terms of conversion between Python objects and
@ref{1df,,Unicode strings}, and thus does not otherwise directly address
the issue of character encodings.

The RFC prohibits adding a byte order mark (BOM) to the start of a JSON text,
and this module’s serializer does not add a BOM to its output.
The RFC permits, but does not require, JSON deserializers to ignore an initial
BOM in their input.  This module’s deserializer raises a @ref{277,,ValueError}
when an initial BOM is present.

The RFC does not explicitly forbid JSON strings which contain byte sequences
that don’t correspond to valid Unicode characters (e.g. unpaired UTF-16
surrogates), but it does note that they may cause interoperability problems.
By default, this module accepts and outputs (when present in the original
@ref{1df,,str}) code points for such sequences.

@node Infinite and NaN Number Values,Repeated Names Within an Object,Character Encodings,Standard Compliance and Interoperability
@anchor{library/json infinite-and-nan-number-values}@anchor{3e30}
@subsubsection Infinite and NaN Number Values


The RFC does not permit the representation of infinite or NaN number values.
Despite that, by default, this module accepts and outputs @code{Infinity},
@code{-Infinity}, and @code{NaN} as if they were valid JSON number literal values:

@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

In the serializer, the `allow_nan' parameter can be used to alter this
behavior.  In the deserializer, the `parse_constant' parameter can be used to
alter this behavior.

@node Repeated Names Within an Object,Top-level Non-Object Non-Array Values,Infinite and NaN Number Values,Standard Compliance and Interoperability
@anchor{library/json repeated-names-within-an-object}@anchor{3e31}
@subsubsection Repeated Names Within an Object


The RFC specifies that the names within a JSON object should be unique, but
does not mandate how repeated names in JSON objects should be handled.  By
default, this module does not raise an exception; instead, it ignores all but
the last name-value pair for a given name:

@example
>>> weird_json = '@{"x": 1, "x": 2, "x": 3@}'
>>> json.loads(weird_json)
@{'x': 3@}
@end example

The `object_pairs_hook' parameter can be used to alter this behavior.

@node Top-level Non-Object Non-Array Values,Implementation Limitations,Repeated Names Within an Object,Standard Compliance and Interoperability
@anchor{library/json top-level-non-object-non-array-values}@anchor{3e32}
@subsubsection Top-level Non-Object, Non-Array Values


The old version of JSON specified by the obsolete 
@geindex RFC; RFC 4627
RFC 4627@footnote{https://datatracker.ietf.org/doc/html/rfc4627.html} required that
the top-level value of a JSON text must be either a JSON object or array
(Python @ref{188,,dict} or @ref{4d9,,list}), and could not be a JSON null,
boolean, number, or string value.  
@geindex RFC; RFC 7159
RFC 7159@footnote{https://datatracker.ietf.org/doc/html/rfc7159.html} removed that restriction, and
this module does not and has never implemented that restriction in either its
serializer or its deserializer.

Regardless, for maximum interoperability, you may wish to voluntarily adhere
to the restriction yourself.

@node Implementation Limitations,,Top-level Non-Object Non-Array Values,Standard Compliance and Interoperability
@anchor{library/json implementation-limitations}@anchor{3e33}
@subsubsection Implementation Limitations


Some JSON deserializer implementations may set limits on:


@itemize *

@item 
the size of accepted JSON texts

@item 
the maximum level of nesting of JSON objects and arrays

@item 
the range and precision of JSON numbers

@item 
the content and maximum length of JSON strings
@end itemize

This module does not impose any such limits beyond those of the relevant
Python datatypes themselves or the Python interpreter itself.

When serializing to JSON, beware any such limitations in applications that may
consume your JSON.  In particular, it is common for JSON numbers to be
deserialized into IEEE 754 double precision numbers and thus subject to that
representation’s range and precision limitations.  This is especially relevant
when serializing Python @ref{326,,int} values of extremely large magnitude, or
when serializing instances of «exotic» numerical types such as
@ref{1c2,,decimal.Decimal}.

@node Command-line interface<4>,,Standard Compliance and Interoperability,json — JSON encoder and decoder
@anchor{library/json command-line-interface}@anchor{3e34}@anchor{library/json json-commandline}@anchor{4cb}@anchor{library/json module-json tool}@anchor{86}
@subsubsection Command-line interface


@geindex module; json.tool

`Source code:' Lib/json/tool.py@footnote{https://github.com/python/cpython/tree/main/Lib/json/tool.py}


__________________________________________________________________


The @code{json} module can be invoked as a script via @code{python -m json}
to validate and pretty-print JSON objects. The @code{json.tool} submodule
implements this interface.

If the optional @code{infile} and @code{outfile} arguments are not
specified, @ref{94a,,sys.stdin} and @ref{e9c,,sys.stdout} will be used respectively:

@example
$ echo '@{"json": "obj"@}' | python -m json
@{
    "json": "obj"
@}
$ echo '@{1.2:3.4@}' | python -m json
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
@end example


Άλλαξε στην έκδοση 3.5: The output is now in the same order as the input. Use the
@ref{3e35,,--sort-keys} option to sort the output of dictionaries
alphabetically by key.



Άλλαξε στην έκδοση 3.14: The @code{json} module may now be directly executed as
@code{python -m json}. For backwards compatibility, invoking
the CLI as @code{python -m json.tool} remains supported.


@menu
* Command-line options: Command-line options<3>. 

@end menu

@node Command-line options<3>,,,Command-line interface<4>
@anchor{library/json command-line-options}@anchor{3e36}
@subsubsection Command-line options


@geindex json command line option; infile
@anchor{library/json cmdoption-json-arg-infile}@anchor{3e37}
@deffn {Option} infile

The JSON file to be validated or pretty-printed:

@example
$ python -m json 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{94a,,sys.stdin}.
@end deffn

@geindex json command line option; outfile
@anchor{library/json cmdoption-json-arg-outfile}@anchor{3e38}
@deffn {Option} outfile

Write the output of the `infile' to the given `outfile'. Otherwise, write it
to @ref{e9c,,sys.stdout}.
@end deffn

@geindex json command line option; --sort-keys
@anchor{library/json cmdoption-json-sort-keys}@anchor{3e35}
@deffn {Option} @w{-}@w{-}sort@w{-}keys

Sort the output of dictionaries alphabetically by key.


Added in version 3.5.

@end deffn

@geindex json command line option; --no-ensure-ascii
@anchor{library/json cmdoption-json-no-ensure-ascii}@anchor{3e39}
@deffn {Option} @w{-}@w{-}no@w{-}ensure@w{-}ascii

Disable escaping of non-ascii characters, see @ref{248,,json.dumps()} for more information.


Added in version 3.9.

@end deffn

@geindex json command line option; --json-lines
@anchor{library/json cmdoption-json-json-lines}@anchor{3e3a}
@deffn {Option} @w{-}@w{-}json@w{-}lines

Parse every input line as separate JSON object.


Added in version 3.8.

@end deffn

@geindex json command line option; --indent
@geindex json command line option; --tab
@geindex json command line option; --no-indent
@geindex json command line option; --compact
@anchor{library/json cmdoption-json-indent}@anchor{3e3b}@anchor{library/json cmdoption-json-tab}@anchor{3e3c}@anchor{library/json cmdoption-json-no-indent}@anchor{3e3d}@anchor{library/json cmdoption-json-compact}@anchor{3e3e}
@deffn {Option} @w{-}@w{-}indent, @w{-}@w{-}tab, @w{-}@w{-}no@w{-}indent, @w{-}@w{-}compact

Mutually exclusive options for whitespace control.


Added in version 3.9.

@end deffn

@geindex json command line option; -h
@geindex json command line option; --help
@anchor{library/json cmdoption-json-h}@anchor{3e3f}@anchor{library/json cmdoption-json-help}@anchor{3e40}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Show the help message.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node mailbox — Manipulate mailboxes in various formats,mimetypes — Map filenames to MIME types,json — JSON encoder and decoder,Internet Data Handling
@anchor{library/mailbox doc}@anchor{3e41}@anchor{library/mailbox mailbox-manipulate-mailboxes-in-various-formats}@anchor{3e42}@anchor{library/mailbox module-mailbox}@anchor{8e}@anchor{library/mailbox translation-repo}@anchor{3e43}
@subsection @code{mailbox} — Manipulate mailboxes in various formats


@geindex module; mailbox

`Source code:' Lib/mailbox.py@footnote{https://github.com/python/cpython/tree/main/Lib/mailbox.py}


__________________________________________________________________


This module defines two classes, @ref{15f1,,Mailbox} and @ref{15f5,,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{47,,email.message} module’s
@ref{780,,Message} class with format-specific state and behavior.
Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{3e,,email}

Represent and manipulate messages.
@end table


@menu
* Mailbox objects:: 
* Message objects:: 
* Exceptions: Exceptions<19>. 
* Examples: Examples<20>. 

@end menu

@node Mailbox objects,Message objects,,mailbox — Manipulate mailboxes in various formats
@anchor{library/mailbox id1}@anchor{3e44}@anchor{library/mailbox mailbox-objects}@anchor{3e45}
@subsubsection @code{Mailbox} objects


@geindex Mailbox (κλάση σε mailbox)
@anchor{library/mailbox mailbox Mailbox}@anchor{15f1}
@deffn {Κλάση} mailbox.Mailbox

A mailbox, which may be inspected and modified.

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{15f0,,add()} and removed using a @code{del} statement or the set-like
methods @ref{3e46,,remove()} and @ref{3e47,,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{15f5,,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{6ce,,iterator} iterates over message
representations, not keys as the default @ref{188,,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{7df,,KeyError} exception if the corresponding message is subsequently
removed.

@cartouche
@quotation Προειδοποίηση 
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{84b,,Maildir}; try to avoid using single-file formats such as
@ref{1c03,,mbox} for
concurrent writing.  If you’re modifying a mailbox, you `must' lock it by
calling the @ref{3e48,,lock()} and @ref{3e49,,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

The @code{Mailbox} class supports the @ref{20a,,with} statement.  When used
as a context manager, @code{Mailbox} calls @ref{3e48,,lock()} when the context is entered,
returns the mailbox object as the context object, and at context end calls @ref{3e4a,,close()},
thereby releasing the lock.


Άλλαξε στην έκδοση 3.15: Support for the @ref{20a,,with} statement was added.


@code{Mailbox} instances have the following methods:

@geindex add() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox add}@anchor{15f0}
@deffn {Μέθοδος} add (message)

Add `message' to the mailbox and return the key that has been assigned to
it.

Parameter `message' may be a @ref{15f5,,Message} instance, an
@ref{780,,email.message.Message} instance, a string, a byte string, or a
file-like object (which should be open in binary mode). If `message' is
an instance of the
appropriate format-specific @code{Message} subclass (e.g., if it’s an
@ref{3d0a,,mboxMessage} instance and this is an @ref{1c03,,mbox} instance), its
format-specific information is used. Otherwise, reasonable defaults for
format-specific information are used.


Άλλαξε στην έκδοση 3.2: Support for binary input was added.

@end deffn

@geindex remove() (μέθοδος της mailbox.Mailbox)
@geindex __delitem__() (μέθοδος της mailbox.Mailbox)
@geindex discard() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox remove}@anchor{3e46}
@deffn {Μέθοδος} remove (key)
@anchor{library/mailbox mailbox Mailbox __delitem__}@anchor{3e4b}
@deffnx {Μέθοδος} __delitem__ (key)
@anchor{library/mailbox mailbox Mailbox discard}@anchor{3e47}
@deffnx {Μέθοδος} discard (key)

Delete the message corresponding to `key' from the mailbox.

If no such message exists, a @ref{7df,,KeyError} exception is raised if the
method was called as @code{remove()} or @code{__delitem__()} but no
exception is raised if the method was called as @code{discard()}. The
behavior of @code{discard()} may be preferred if the underlying mailbox
format supports concurrent modification by other processes.
@end deffn

@geindex __setitem__() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox __setitem__}@anchor{3e4c}
@deffn {Μέθοδος} __setitem__ (key, message)

Replace the message corresponding to `key' with `message'. Raise a
@ref{7df,,KeyError} exception if no message already corresponds to `key'.

As with @ref{15f0,,add()}, parameter `message' may be a @ref{15f5,,Message}
instance, an @ref{780,,email.message.Message} instance, a string, a byte
string, or a file-like object (which should be open in binary mode). If
`message' is an
instance of the appropriate format-specific @code{Message} subclass
(e.g., if it’s an @ref{3d0a,,mboxMessage} instance and this is an
@ref{1c03,,mbox} instance), its format-specific information is
used. Otherwise, the format-specific information of the message that
currently corresponds to `key' is left unchanged.
@end deffn

@geindex iterkeys() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox iterkeys}@anchor{3e4d}
@deffn {Μέθοδος} iterkeys ()

Return an @ref{6ce,,iterator} over all keys
@end deffn

@geindex keys() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox keys}@anchor{3e4e}
@deffn {Μέθοδος} keys ()

The same as @ref{3e4d,,iterkeys()}, except that a @ref{4d9,,list} is returned
rather than an @ref{6ce,,iterator}
@end deffn

@geindex itervalues() (μέθοδος της mailbox.Mailbox)
@geindex __iter__() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox itervalues}@anchor{3e4f}
@deffn {Μέθοδος} itervalues ()
@anchor{library/mailbox mailbox Mailbox __iter__}@anchor{3e50}
@deffnx {Μέθοδος} __iter__ ()

Return an @ref{6ce,,iterator} over representations of all messages.
The messages are represented
as instances of the appropriate format-specific @ref{15f5,,Message} subclass
unless a custom message factory was specified when the @code{Mailbox}
instance was initialized.

@cartouche
@quotation Σημείωση 
The behavior of @code{__iter__()} is unlike that of dictionaries, which
iterate over keys.
@end quotation
@end cartouche
@end deffn

@geindex values() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox values}@anchor{3e51}
@deffn {Μέθοδος} values ()

The same as @ref{3e4f,,itervalues()}, except that a @ref{4d9,,list} is returned
rather than an @ref{6ce,,iterator}
@end deffn

@geindex iteritems() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox iteritems}@anchor{3e52}
@deffn {Μέθοδος} iteritems ()

Return an @ref{6ce,,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{15f5,,Message} subclass unless a custom message factory was specified
when the @code{Mailbox} instance was initialized.
@end deffn

@geindex items() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox items}@anchor{3e53}
@deffn {Μέθοδος} items ()

The same as @ref{3e52,,iteritems()}, except that a @ref{4d9,,list} of pairs is
returned rather than an @ref{6ce,,iterator} of pairs.
@end deffn

@geindex get() (μέθοδος της mailbox.Mailbox)
@geindex __getitem__() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox get}@anchor{3e54}
@deffn {Μέθοδος} get (key, default=None)
@anchor{library/mailbox mailbox Mailbox __getitem__}@anchor{3e55}
@deffnx {Μέθοδος} __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
@code{get()} and a @ref{7df,,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{15f5,,Message} subclass unless a
custom message factory was specified when the @code{Mailbox} instance
was initialized.
@end deffn

@geindex get_message() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox get_message}@anchor{3e56}
@deffn {Μέθοδος} get_message (key)

Return a representation of the message corresponding to `key' as an
instance of the appropriate format-specific @ref{15f5,,Message} subclass, or
raise a @ref{7df,,KeyError} exception if no such message exists.
@end deffn

@geindex get_bytes() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox get_bytes}@anchor{15f3}
@deffn {Μέθοδος} get_bytes (key)

Return a byte representation of the message corresponding to `key', or
raise a @ref{7df,,KeyError} exception if no such message exists.


Added in version 3.2.

@end deffn

@geindex get_string() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox get_string}@anchor{15f4}
@deffn {Μέθοδος} get_string (key)

Return a string representation of the message corresponding to `key', or
raise a @ref{7df,,KeyError} exception if no such message exists.  The
message is processed through @ref{780,,email.message.Message} to
convert it to a 7bit clean representation.
@end deffn

@geindex get_file() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox get_file}@anchor{15f2}
@deffn {Μέθοδος} get_file (key)

Return a @ref{19b1,,file-like} representation of the
message corresponding to `key',
or raise a @ref{7df,,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.


Άλλαξε στην έκδοση 3.2: The file object really is a @ref{225d,,binary file}; previously it was
incorrectly returned in text mode.  Also, the @ref{19b1,,file-like object}
now supports the @ref{478,,context manager} protocol: you can use a
@ref{20a,,with} statement to automatically close it.


@cartouche
@quotation Σημείωση 
Unlike other representations of messages,
@ref{19b1,,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__() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox __contains__}@anchor{3e57}
@deffn {Μέθοδος} __contains__ (key)

Return @code{True} if `key' corresponds to a message, @code{False} otherwise.
@end deffn

@geindex __len__() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox __len__}@anchor{3e58}
@deffn {Μέθοδος} __len__ ()

Return a count of messages in the mailbox.
@end deffn

@geindex clear() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox clear}@anchor{3e59}
@deffn {Μέθοδος} clear ()

Delete all messages from the mailbox.
@end deffn

@geindex pop() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox pop}@anchor{3e5a}
@deffn {Μέθοδος} 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{15f5,,Message} subclass unless a custom message factory was specified
when the @code{Mailbox} instance was initialized.
@end deffn

@geindex popitem() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox popitem}@anchor{3e5b}
@deffn {Μέθοδος} 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{7df,,KeyError} exception. The
message is represented as an instance of the appropriate format-specific
@ref{15f5,,Message} subclass unless a custom message factory was specified
when the @code{Mailbox} instance was initialized.
@end deffn

@geindex update() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox update}@anchor{3e5c}
@deffn {Μέθοδος} 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{3e4c,,__setitem__()}. As with @code{__setitem__()},
each `key' must already correspond to a message in the mailbox or else a
@ref{7df,,KeyError} exception will be raised, so in general it is incorrect
for `arg' to be a @code{Mailbox} instance.

@cartouche
@quotation Σημείωση 
Unlike with dictionaries, keyword arguments are not supported.
@end quotation
@end cartouche
@end deffn

@geindex flush() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox flush}@anchor{1bcb}
@deffn {Μέθοδος} flush ()

Write any pending changes to the filesystem. For some @code{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() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox lock}@anchor{3e48}
@deffn {Μέθοδος} lock ()

Acquire an exclusive advisory lock on the mailbox so that other processes
know not to modify it. An @ref{3e5d,,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() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox unlock}@anchor{3e49}
@deffn {Μέθοδος} unlock ()

Release the lock on the mailbox, if any.
@end deffn

@geindex close() (μέθοδος της mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox close}@anchor{3e4a}
@deffn {Μέθοδος} 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{3e5e}@anchor{library/mailbox maildir-objects}@anchor{3e5f}
@subsubsection @code{Maildir} objects


@geindex Maildir (κλάση σε mailbox)
@anchor{library/mailbox mailbox Maildir}@anchor{84b}
@deffn {Κλάση} mailbox.Maildir (dirname, factory=None, create=True)

A subclass of @ref{15f1,,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{3e60,,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 (ιδιότητα της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir colon}@anchor{3e61}
@deffn {Ιδιότητα} 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


Άλλαξε στην έκδοση 3.13: @code{Maildir} now ignores files with a leading dot.


@code{Maildir} instances have all of the methods of @ref{15f1,,Mailbox} in
addition to the following:

@geindex list_folders() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir list_folders}@anchor{3e62}
@deffn {Μέθοδος} list_folders ()

Return a list of the names of all folders.
@end deffn

@geindex get_folder() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir get_folder}@anchor{3e63}
@deffn {Μέθοδος} get_folder (folder)

Return a @code{Maildir} instance representing the folder whose name is
`folder'. A @ref{3e64,,NoSuchMailboxError} exception is raised if the folder
does not exist.
@end deffn

@geindex add_folder() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir add_folder}@anchor{3e65}
@deffn {Μέθοδος} add_folder (folder)

Create a folder whose name is `folder' and return a @code{Maildir}
instance representing it.
@end deffn

@geindex remove_folder() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir remove_folder}@anchor{3e66}
@deffn {Μέθοδος} remove_folder (folder)

Delete the folder whose name is `folder'. If the folder contains any
messages, a @ref{3e67,,NotEmptyError} exception will be raised and the folder
will not be deleted.
@end deffn

@geindex clean() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir clean}@anchor{3e68}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir get_flags}@anchor{1c4c}
@deffn {Μέθοδος} 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{3e60,,MaildirMessage} object, use
its @ref{3e69,,get_flags()} method instead, because
changes made by the message’s @ref{3e6a,,set_flags()},
@ref{3e6b,,add_flag()} and @ref{3e6c,,remove_flag()}
methods are not reflected here until the mailbox’s
@ref{3e6d,,__setitem__()} method is called.


Added in version 3.13.

@end deffn

@geindex set_flags() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir set_flags}@anchor{1c4d}
@deffn {Μέθοδος} 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{3e60,,MaildirMessage} object, use
its @ref{3e6a,,set_flags()} method instead, because
changes made with this mailbox method will not be visible to the
message object’s method, @ref{3e69,,get_flags()}.


Added in version 3.13.

@end deffn

@geindex add_flag() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir add_flag}@anchor{1c4e}
@deffn {Μέθοδος} 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{3e6b,,add_flag()} method are similar to
those for @ref{1c4d,,set_flags()}; see the discussion there.


Added in version 3.13.

@end deffn

@geindex remove_flag() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir remove_flag}@anchor{1c4f}
@deffn {Μέθοδος} 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{3e6c,,remove_flag()} method are similar to
those for @ref{1c4d,,set_flags()}; see the discussion there.


Added in version 3.13.

@end deffn

@geindex get_info() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir get_info}@anchor{1c4a}
@deffn {Μέθοδος} 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{3e60,,MaildirMessage} object, use
its @ref{3e6e,,get_info()} method instead, because
changes made by the message’s @ref{3e6f,,set_info()} method
are not reflected here until the mailbox’s @ref{3e6d,,__setitem__()} method
is called.


Added in version 3.13.

@end deffn

@geindex set_info() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir set_info}@anchor{1c4b}
@deffn {Μέθοδος} 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{3e60,,MaildirMessage} object, use
its @ref{3e6f,,set_info()} method instead, because
changes made with this mailbox method will not be visible to the
message object’s method, @ref{3e6e,,get_info()}.


Added in version 3.13.

@end deffn

Some @ref{15f1,,Mailbox} methods implemented by @code{Maildir} deserve special
remarks:

@geindex add() (μέθοδος της mailbox.Maildir)
@geindex __setitem__() (μέθοδος της mailbox.Maildir)
@geindex update() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir add}@anchor{3e70}
@deffn {Μέθοδος} add (message)
@anchor{library/mailbox mailbox Maildir __setitem__}@anchor{3e6d}
@deffnx {Μέθοδος} __setitem__ (key, message)
@anchor{library/mailbox mailbox Maildir update}@anchor{3e71}
@deffnx {Μέθοδος} update (arg)

@cartouche
@quotation Προειδοποίηση 
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() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir flush}@anchor{3e72}
@deffn {Μέθοδος} flush ()

All changes to Maildir mailboxes are immediately applied, so this method
does nothing.
@end deffn

@geindex lock() (μέθοδος της mailbox.Maildir)
@geindex unlock() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir lock}@anchor{3e73}
@deffn {Μέθοδος} lock ()
@anchor{library/mailbox mailbox Maildir unlock}@anchor{3e74}
@deffnx {Μέθοδος} unlock ()

Maildir mailboxes do not support (or require) locking, so these methods do
nothing.
@end deffn

@geindex close() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir close}@anchor{3e75}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir get_file}@anchor{3e76}
@deffn {Μέθοδος} 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 Δείτε επίσης



@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{3e77}@anchor{library/mailbox mbox-objects}@anchor{3e78}
@subsubsection @code{mbox} objects


@geindex mbox (κλάση σε mailbox)
@anchor{library/mailbox mailbox mbox}@anchor{1c03}
@deffn {Κλάση} mailbox.mbox (path, factory=None, create=True)

A subclass of @ref{15f1,,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{3d0a,,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{15f1,,Mailbox} methods implemented by @code{mbox} deserve special
remarks:

@geindex get_bytes() (μέθοδος της mailbox.mbox)
@anchor{library/mailbox mailbox mbox get_bytes}@anchor{3e79}
@deffn {Μέθοδος} get_bytes (key, from_=False)

Note: This method has an extra parameter (`from_') compared with other classes.
The first line of an mbox file entry is the Unix «From « line.
If `from_' is False, the first line of the file is dropped.
@end deffn

@geindex get_file() (μέθοδος της mailbox.mbox)
@anchor{library/mailbox mailbox mbox get_file}@anchor{3e7a}
@deffn {Μέθοδος} get_file (key, from_=False)

Using the file after calling @ref{1bcb,,flush()} or
@ref{3e4a,,close()} on the @code{mbox} instance may yield
unpredictable results or raise an exception.

Note: This method has an extra parameter (`from_') compared with other classes.
The first line of an mbox file entry is the Unix «From « line.
If `from_' is False, the first line of the file is dropped.
@end deffn

@geindex get_string() (μέθοδος της mailbox.mbox)
@anchor{library/mailbox mailbox mbox get_string}@anchor{3e7b}
@deffn {Μέθοδος} get_string (key, from_=False)

Note: This method has an extra parameter (`from_') compared with other classes.
The first line of an mbox file entry is the Unix «From « line.
If `from_' is False, the first line of the file is dropped.
@end deffn

@geindex lock() (μέθοδος της mailbox.mbox)
@geindex unlock() (μέθοδος της mailbox.mbox)
@anchor{library/mailbox mailbox mbox lock}@anchor{3e7c}
@deffn {Μέθοδος} lock ()
@anchor{library/mailbox mailbox mbox unlock}@anchor{3e7d}
@deffnx {Μέθοδος} unlock ()

Three locking mechanisms are used—dot locking and, if available, the
@code{flock()} and @code{lockf()} system calls.
@end deffn
@end deffn


@subsubheading Δείτε επίσης



@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{3e7e}@anchor{library/mailbox mh-objects}@anchor{3e7f}
@subsubsection @code{MH} objects


@geindex MH (κλάση σε mailbox)
@anchor{library/mailbox mailbox MH}@anchor{1c35}
@deffn {Κλάση} mailbox.MH (path, factory=None, create=True)

A subclass of @ref{15f1,,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{3e80,,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{15f1,,Mailbox} in addition
to the following:


Άλλαξε στην έκδοση 3.13: Supported folders that don’t contain a @code{.mh_sequences} file.


@geindex list_folders() (μέθοδος της mailbox.MH)
@anchor{library/mailbox mailbox MH list_folders}@anchor{3e81}
@deffn {Μέθοδος} list_folders ()

Return a list of the names of all folders.
@end deffn

@geindex get_folder() (μέθοδος της mailbox.MH)
@anchor{library/mailbox mailbox MH get_folder}@anchor{3e82}
@deffn {Μέθοδος} get_folder (folder)

Return an @code{MH} instance representing the folder whose name is
`folder'. A @ref{3e64,,NoSuchMailboxError} exception is raised if the folder
does not exist.
@end deffn

@geindex add_folder() (μέθοδος της mailbox.MH)
@anchor{library/mailbox mailbox MH add_folder}@anchor{3e83}
@deffn {Μέθοδος} add_folder (folder)

Create a folder whose name is `folder' and return an @code{MH} instance
representing it.
@end deffn

@geindex remove_folder() (μέθοδος της mailbox.MH)
@anchor{library/mailbox mailbox MH remove_folder}@anchor{3e84}
@deffn {Μέθοδος} remove_folder (folder)

Delete the folder whose name is `folder'. If the folder contains any
messages, a @ref{3e67,,NotEmptyError} exception will be raised and the folder
will not be deleted.
@end deffn

@geindex get_sequences() (μέθοδος της mailbox.MH)
@anchor{library/mailbox mailbox MH get_sequences}@anchor{3e85}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.MH)
@anchor{library/mailbox mailbox MH set_sequences}@anchor{3e86}
@deffn {Μέθοδος} 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{3e85,,get_sequences()}.
@end deffn

@geindex pack() (μέθοδος της mailbox.MH)
@anchor{library/mailbox mailbox MH pack}@anchor{3e87}
@deffn {Μέθοδος} pack ()

Rename messages in the mailbox as necessary to eliminate gaps in
numbering.  Entries in the sequences list are updated correspondingly.

@cartouche
@quotation Σημείωση 
Already-issued keys are invalidated by this operation and should not be
subsequently used.
@end quotation
@end cartouche
@end deffn

Some @ref{15f1,,Mailbox} methods implemented by @code{MH} deserve special
remarks:

@geindex remove() (μέθοδος της mailbox.MH)
@geindex __delitem__() (μέθοδος της mailbox.MH)
@geindex discard() (μέθοδος της mailbox.MH)
@anchor{library/mailbox mailbox MH remove}@anchor{3e88}
@deffn {Μέθοδος} remove (key)
@anchor{library/mailbox mailbox MH __delitem__}@anchor{3e89}
@deffnx {Μέθοδος} __delitem__ (key)
@anchor{library/mailbox mailbox MH discard}@anchor{3e8a}
@deffnx {Μέθοδος} 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() (μέθοδος της mailbox.MH)
@geindex unlock() (μέθοδος της mailbox.MH)
@anchor{library/mailbox mailbox MH lock}@anchor{3e8b}
@deffn {Μέθοδος} lock ()
@anchor{library/mailbox mailbox MH unlock}@anchor{3e8c}
@deffnx {Μέθοδος} 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() (μέθοδος της mailbox.MH)
@anchor{library/mailbox mailbox MH get_file}@anchor{3e8d}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.MH)
@anchor{library/mailbox mailbox MH flush}@anchor{3e8e}
@deffn {Μέθοδος} flush ()

All changes to MH mailboxes are immediately applied, so this method does
nothing.
@end deffn

@geindex close() (μέθοδος της mailbox.MH)
@anchor{library/mailbox mailbox MH close}@anchor{3e8f}
@deffn {Μέθοδος} close ()

@code{MH} instances do not keep any open files, so this method is
equivalent to @ref{3e8c,,unlock()}.
@end deffn
@end deffn


@subsubheading Δείτε επίσης



@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{3e90}@anchor{library/mailbox mailbox-babyl}@anchor{3e91}
@subsubsection @code{Babyl} objects


@geindex Babyl (κλάση σε mailbox)
@anchor{library/mailbox mailbox Babyl}@anchor{3e92}
@deffn {Κλάση} mailbox.Babyl (path, factory=None, create=True)

A subclass of @ref{15f1,,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{3e93,,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{15f1,,Mailbox} in
addition to the following:

@geindex get_labels() (μέθοδος της mailbox.Babyl)
@anchor{library/mailbox mailbox Babyl get_labels}@anchor{3e94}
@deffn {Μέθοδος} get_labels ()

Return a list of the names of all user-defined labels used in the mailbox.

@cartouche
@quotation Σημείωση 
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{15f1,,Mailbox} methods implemented by @code{Babyl} deserve special
remarks:

@geindex get_file() (μέθοδος της mailbox.Babyl)
@anchor{library/mailbox mailbox Babyl get_file}@anchor{3e95}
@deffn {Μέθοδος} 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{1255,,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() (μέθοδος της mailbox.Babyl)
@geindex unlock() (μέθοδος της mailbox.Babyl)
@anchor{library/mailbox mailbox Babyl lock}@anchor{3e96}
@deffn {Μέθοδος} lock ()
@anchor{library/mailbox mailbox Babyl unlock}@anchor{3e97}
@deffnx {Μέθοδος} unlock ()

Three locking mechanisms are used—dot locking and, if available, the
@code{flock()} and @code{lockf()} system calls.
@end deffn
@end deffn


@subsubheading Δείτε επίσης



@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{3e98}@anchor{library/mailbox mmdf-objects}@anchor{3e99}
@subsubsection @code{MMDF} objects


@geindex MMDF (κλάση σε mailbox)
@anchor{library/mailbox mailbox MMDF}@anchor{1c04}
@deffn {Κλάση} mailbox.MMDF (path, factory=None, create=True)

A subclass of @ref{15f1,,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{3e9a,,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{15f1,,Mailbox} methods implemented by @code{MMDF} deserve special
remarks:

@geindex get_bytes() (μέθοδος της mailbox.MMDF)
@anchor{library/mailbox mailbox MMDF get_bytes}@anchor{3e9b}
@deffn {Μέθοδος} get_bytes (key, from_=False)

Note: This method has an extra parameter (`from_') compared with other classes.
The first line of an mbox file entry is the Unix «From « line.
If `from_' is False, the first line of the file is dropped.
@end deffn

@geindex get_file() (μέθοδος της mailbox.MMDF)
@anchor{library/mailbox mailbox MMDF get_file}@anchor{3e9c}
@deffn {Μέθοδος} get_file (key, from_=False)

Using the file after calling @ref{1bcb,,flush()} or
@ref{3e4a,,close()} on the @code{MMDF} instance may yield
unpredictable results or raise an exception.

Note: This method has an extra parameter (`from_') compared with other classes.
The first line of an mbox file entry is the Unix «From « line.
If `from_' is False, the first line of the file is dropped.
@end deffn

@geindex lock() (μέθοδος της mailbox.MMDF)
@geindex unlock() (μέθοδος της mailbox.MMDF)
@anchor{library/mailbox mailbox MMDF lock}@anchor{3e9d}
@deffn {Μέθοδος} lock ()
@anchor{library/mailbox mailbox MMDF unlock}@anchor{3e9e}
@deffnx {Μέθοδος} unlock ()

Three locking mechanisms are used—dot locking and, if available, the
@code{flock()} and @code{lockf()} system calls.
@end deffn
@end deffn


@subsubheading Δείτε επίσης



@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<19>,Mailbox objects,mailbox — Manipulate mailboxes in various formats
@anchor{library/mailbox mailbox-message-objects}@anchor{3e9f}@anchor{library/mailbox message-objects}@anchor{3ea0}
@subsubsection @code{Message} objects


@geindex Message (κλάση σε mailbox)
@anchor{library/mailbox mailbox Message}@anchor{15f5}
@deffn {Κλάση} mailbox.Message (message=None)

A subclass of the @ref{47,,email.message} module’s
@ref{780,,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{780,,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 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.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{15f1,,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{3ea1}@anchor{library/mailbox maildirmessage-objects}@anchor{3ea2}
@subsubsection @code{MaildirMessage} objects


@geindex MaildirMessage (κλάση σε mailbox)
@anchor{library/mailbox mailbox MaildirMessage}@anchor{3e60}
@deffn {Κλάση} mailbox.MaildirMessage (message=None)

A message with Maildir-specific behaviors. Parameter `message' has the same
meaning as with the @ref{15f5,,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

Flag

@tab

Meaning

@tab

Explanation

@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() (μέθοδος της mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage get_subdir}@anchor{3ea3}
@deffn {Μέθοδος} 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 Σημείωση 
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() (μέθοδος της mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage set_subdir}@anchor{3ea4}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage get_flags}@anchor{3e69}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage set_flags}@anchor{3e6a}
@deffn {Μέθοδος} set_flags (flags)

Set the flags specified by `flags' and unset all others.
@end deffn

@geindex add_flag() (μέθοδος της mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage add_flag}@anchor{3e6b}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage remove_flag}@anchor{3e6c}
@deffn {Μέθοδος} remove_flag (flag)

Unset the flag(s) 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.  If «info» contains experimental information rather than
flags, the current «info» is not modified.
@end deffn

@geindex get_date() (μέθοδος της mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage get_date}@anchor{3ea5}
@deffn {Μέθοδος} get_date ()

Return the delivery date of the message as a floating-point number
representing seconds since the epoch.
@end deffn

@geindex set_date() (μέθοδος της mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage set_date}@anchor{3ea6}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage get_info}@anchor{3e6e}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage set_info}@anchor{3e6f}
@deffn {Μέθοδος} 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{3d0a,,mboxMessage} or @ref{3e9a,,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{3d0a,,mboxMessage} or @ref{3e9a,,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{3e80,,MHMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e80,,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{3e93,,BabylMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e93,,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{3ea7}@anchor{library/mailbox mboxmessage-objects}@anchor{3ea8}
@subsubsection @code{mboxMessage} objects


@geindex mboxMessage (κλάση σε mailbox)
@anchor{library/mailbox mailbox mboxMessage}@anchor{3d0a}
@deffn {Κλάση} mailbox.mboxMessage (message=None)

A message with mbox-specific behaviors. Parameter `message' has the same meaning
as with the @ref{15f5,,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

Flag

@tab

Meaning

@tab

Explanation

@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() (μέθοδος της mailbox.mboxMessage)
@anchor{library/mailbox mailbox mboxMessage get_from}@anchor{3ea9}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.mboxMessage)
@anchor{library/mailbox mailbox mboxMessage set_from}@anchor{3eaa}
@deffn {Μέθοδος} 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{10a7,,time.struct_time} instance, a
tuple suitable for passing to @ref{1592,,time.strftime()}, or @code{True} (to use
@ref{1569,,time.gmtime()}).
@end deffn

@geindex get_flags() (μέθοδος της mailbox.mboxMessage)
@anchor{library/mailbox mailbox mboxMessage get_flags}@anchor{3eab}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.mboxMessage)
@anchor{library/mailbox mailbox mboxMessage set_flags}@anchor{3eac}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.mboxMessage)
@anchor{library/mailbox mailbox mboxMessage add_flag}@anchor{3ead}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.mboxMessage)
@anchor{library/mailbox mailbox mboxMessage remove_flag}@anchor{3eae}
@deffn {Μέθοδος} remove_flag (flag)

Unset the flag(s) 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.
@end deffn
@end deffn

When an @code{mboxMessage} instance is created based upon a
@ref{3e60,,MaildirMessage} instance, a «From « line is generated based upon the
@code{MaildirMessage} instance’s delivery date, and the following conversions
take place:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e60,,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{3e80,,MHMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e80,,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{3e93,,BabylMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e93,,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{3e9a,,MMDFMessage}
instance, the «From « line is copied and all flags directly correspond:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e9a,,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{3eaf}@anchor{library/mailbox mhmessage-objects}@anchor{3eb0}
@subsubsection @code{MHMessage} objects


@geindex MHMessage (κλάση σε mailbox)
@anchor{library/mailbox mailbox MHMessage}@anchor{3e80}
@deffn {Κλάση} mailbox.MHMessage (message=None)

A message with MH-specific behaviors. Parameter `message' has the same meaning
as with the @ref{15f5,,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

Sequence

@tab

Explanation

@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() (μέθοδος της mailbox.MHMessage)
@anchor{library/mailbox mailbox MHMessage get_sequences}@anchor{3eb1}
@deffn {Μέθοδος} get_sequences ()

Return a list of the names of sequences that include this message.
@end deffn

@geindex set_sequences() (μέθοδος της mailbox.MHMessage)
@anchor{library/mailbox mailbox MHMessage set_sequences}@anchor{3eb2}
@deffn {Μέθοδος} set_sequences (sequences)

Set the list of sequences that include this message.
@end deffn

@geindex add_sequence() (μέθοδος της mailbox.MHMessage)
@anchor{library/mailbox mailbox MHMessage add_sequence}@anchor{3eb3}
@deffn {Μέθοδος} add_sequence (sequence)

Add `sequence' to the list of sequences that include this message.
@end deffn

@geindex remove_sequence() (μέθοδος της mailbox.MHMessage)
@anchor{library/mailbox mailbox MHMessage remove_sequence}@anchor{3eb4}
@deffn {Μέθοδος} 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{3e60,,MaildirMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e60,,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{3d0a,,mboxMessage} or @ref{3e9a,,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{3d0a,,mboxMessage} or @ref{3e9a,,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{3e93,,BabylMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e93,,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{3eb5}@anchor{library/mailbox mailbox-babylmessage}@anchor{3eb6}
@subsubsection @code{BabylMessage} objects


@geindex BabylMessage (κλάση σε mailbox)
@anchor{library/mailbox mailbox BabylMessage}@anchor{3e93}
@deffn {Κλάση} mailbox.BabylMessage (message=None)

A message with Babyl-specific behaviors. Parameter `message' has the same
meaning as with the @ref{15f5,,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

Explanation

@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() (μέθοδος της mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage get_labels}@anchor{3eb7}
@deffn {Μέθοδος} get_labels ()

Return a list of labels on the message.
@end deffn

@geindex set_labels() (μέθοδος της mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage set_labels}@anchor{3eb8}
@deffn {Μέθοδος} set_labels (labels)

Set the list of labels on the message to `labels'.
@end deffn

@geindex add_label() (μέθοδος της mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage add_label}@anchor{3eb9}
@deffn {Μέθοδος} add_label (label)

Add `label' to the list of labels on the message.
@end deffn

@geindex remove_label() (μέθοδος της mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage remove_label}@anchor{3eba}
@deffn {Μέθοδος} remove_label (label)

Remove `label' from the list of labels on the message.
@end deffn

@geindex get_visible() (μέθοδος της mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage get_visible}@anchor{3ebb}
@deffn {Μέθοδος} get_visible ()

Return a @ref{15f5,,Message} instance whose headers are the message’s
visible headers and whose body is empty.
@end deffn

@geindex set_visible() (μέθοδος της mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage set_visible}@anchor{3ebc}
@deffn {Μέθοδος} set_visible (visible)

Set the message’s visible headers to be the same as the headers in
`message'.  Parameter `visible' should be a @ref{15f5,,Message} instance, an
@ref{780,,email.message.Message} instance, a string, or a file-like object
(which should be open in text mode).
@end deffn

@geindex update_visible() (μέθοδος της mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage update_visible}@anchor{3ebd}
@deffn {Μέθοδος} 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{3e60,,MaildirMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e60,,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{3d0a,,mboxMessage} or @ref{3e9a,,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{3d0a,,mboxMessage} or @ref{3e9a,,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{3e80,,MHMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e80,,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{3ebe}@anchor{library/mailbox mmdfmessage-objects}@anchor{3ebf}
@subsubsection @code{MMDFMessage} objects


@geindex MMDFMessage (κλάση σε mailbox)
@anchor{library/mailbox mailbox MMDFMessage}@anchor{3e9a}
@deffn {Κλάση} mailbox.MMDFMessage (message=None)

A message with MMDF-specific behaviors. Parameter `message' has the same meaning
as with the @ref{15f5,,Message} constructor.

As with message in an mbox mailbox, MMDF messages are stored with the
sender’s address and the delivery date in an initial line beginning with
«From «.  Likewise, flags that indicate the state of the message are
typically stored in @code{Status} and @code{X-Status} headers.

Conventional flags for MMDF messages are identical to those of mbox message
and are as follows:


@multitable {xxxxxxxx} {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Flag

@tab

Meaning

@tab

Explanation

@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{3d0a,,mboxMessage}:

@geindex get_from() (μέθοδος της mailbox.MMDFMessage)
@anchor{library/mailbox mailbox MMDFMessage get_from}@anchor{3ec0}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.MMDFMessage)
@anchor{library/mailbox mailbox MMDFMessage set_from}@anchor{3ec1}
@deffn {Μέθοδος} 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{10a7,,time.struct_time} instance, a
tuple suitable for passing to @ref{1592,,time.strftime()}, or @code{True} (to use
@ref{1569,,time.gmtime()}).
@end deffn

@geindex get_flags() (μέθοδος της mailbox.MMDFMessage)
@anchor{library/mailbox mailbox MMDFMessage get_flags}@anchor{3ec2}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.MMDFMessage)
@anchor{library/mailbox mailbox MMDFMessage set_flags}@anchor{3ec3}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.MMDFMessage)
@anchor{library/mailbox mailbox MMDFMessage add_flag}@anchor{3ec4}
@deffn {Μέθοδος} 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() (μέθοδος της mailbox.MMDFMessage)
@anchor{library/mailbox mailbox MMDFMessage remove_flag}@anchor{3ec5}
@deffn {Μέθοδος} remove_flag (flag)

Unset the flag(s) 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.
@end deffn
@end deffn

When an @code{MMDFMessage} instance is created based upon a
@ref{3e60,,MaildirMessage} instance, a «From « line is generated based upon the
@code{MaildirMessage} instance’s delivery date, and the following conversions
take place:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e60,,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{3e80,,MHMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e80,,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{3e93,,BabylMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3e93,,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{3d0a,,mboxMessage} instance, the «From « line is copied and all flags directly
correspond:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3d0a,,mboxMessage} 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 Exceptions<19>,Examples<20>,Message objects,mailbox — Manipulate mailboxes in various formats
@anchor{library/mailbox exceptions}@anchor{3ec6}
@subsubsection Exceptions


The following exception classes are defined in the @code{mailbox} module:

@geindex Error
@anchor{library/mailbox mailbox Error}@anchor{3ec7}
@deffn {Εξαίρεση} mailbox.Error

The base class for all other module-specific exceptions.
@end deffn

@geindex NoSuchMailboxError
@anchor{library/mailbox mailbox NoSuchMailboxError}@anchor{3e64}
@deffn {Εξαίρεση} mailbox.NoSuchMailboxError

Raised when a mailbox is expected but is not found, such as when instantiating a
@ref{15f1,,Mailbox} subclass with a path that does not exist (and with the `create'
parameter set to @code{False}), or when opening a folder that does not exist.
@end deffn

@geindex NotEmptyError
@anchor{library/mailbox mailbox NotEmptyError}@anchor{3e67}
@deffn {Εξαίρεση} mailbox.NotEmptyError

Raised when a mailbox is not empty but is expected to be, such as when deleting
a folder that contains messages.
@end deffn

@geindex ExternalClashError
@anchor{library/mailbox mailbox ExternalClashError}@anchor{3e5d}
@deffn {Εξαίρεση} 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, or when a uniquely generated file name
already exists.
@end deffn

@geindex FormatError
@anchor{library/mailbox mailbox FormatError}@anchor{3ec8}
@deffn {Εξαίρεση} mailbox.FormatError

Raised when the data in a file cannot be parsed, such as when an @ref{1c35,,MH}
instance attempts to read a corrupted @code{.mh_sequences} file.
@end deffn

@node Examples<20>,,Exceptions<19>,mailbox — Manipulate mailboxes in various formats
@anchor{library/mailbox examples}@anchor{3ec9}@anchor{library/mailbox mailbox-examples}@anchor{3eca}
@subsubsection Examples


A simple example of printing the subjects of all messages in a mailbox that seem
interesting:

@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

To copy all mail from a Babyl mailbox to an MH mailbox, converting all of the
format-specific information that can be converted:

@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

This example sorts mail from several mailing lists into different mailboxes,
being careful to avoid mail corruption due to concurrent modification by other
programs, mail loss due to interruption of the program, or premature termination
due to malformed messages in the mailbox:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node mimetypes — Map filenames to MIME types,base64 — Base16 Base32 Base64 Base85 Data Encodings,mailbox — Manipulate mailboxes in various formats,Internet Data Handling
@anchor{library/mimetypes doc}@anchor{3ecb}@anchor{library/mimetypes mimetypes-map-filenames-to-mime-types}@anchor{3ecc}@anchor{library/mimetypes module-mimetypes}@anchor{93}@anchor{library/mimetypes translation-repo}@anchor{3ecd}
@subsection @code{mimetypes} — Map filenames to MIME types


@geindex module; mimetypes

`Source code:' Lib/mimetypes.py@footnote{https://github.com/python/cpython/tree/main/Lib/mimetypes.py}

@geindex MIME;content type


__________________________________________________________________


The @code{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{3ece,,init()} if they rely on
the information @code{init()} sets up.

@geindex guess_type() (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes guess_type}@anchor{71b}
@deffn {Συνάρτηση} 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{79f,,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}.
However, the behavior of this module also depends on the underlying operating
system. Only file types recognized by the OS or explicitly registered with
Python’s internal database can be identified. 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.


Άλλαξε στην έκδοση 3.8: Added support for `url' being a @ref{79f,,path-like object}.



@ref{1a7,,Soft deprecated} since version 3.13: Passing a file path instead of URL.
Use @ref{71a,,guess_file_type()} for this.

@end deffn

@geindex guess_file_type() (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes guess_file_type}@anchor{71a}
@deffn {Συνάρτηση} 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{71b,,guess_type()} function, but accepts a path instead of URL.
Path can be a string, a bytes object or a @ref{79f,,path-like object}.


Added in version 3.13.

@end deffn

@geindex guess_all_extensions() (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes guess_all_extensions}@anchor{1e41}
@deffn {Συνάρτηση} 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{71b,,guess_type()} and @ref{71a,,guess_file_type()}.

The optional `strict' argument has the same meaning as with the @ref{71b,,guess_type()} function.
@end deffn

@geindex guess_extension() (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes guess_extension}@anchor{3ecf}
@deffn {Συνάρτηση} 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{71b,,guess_type()} and @ref{71a,,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{71b,,guess_type()} function.
@end deffn

Some additional functions and data items are available for controlling the
behavior of the module.

@geindex init() (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes init}@anchor{3ece}
@deffn {Συνάρτηση} 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{3ed0,,knownfiles}; on Windows, the
current registry settings are loaded.  Each file named in `files' or
@code{knownfiles} takes precedence over those named before it.  Calling
@code{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.


Άλλαξε στην έκδοση 3.2: Previously, Windows registry settings were ignored.

@end deffn

@geindex read_mime_types() (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes read_mime_types}@anchor{1f1f}
@deffn {Συνάρτηση} 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() (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes add_type}@anchor{3ed1}
@deffn {Συνάρτηση} 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 (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes inited}@anchor{3ed2}
@deffn {Δεδομένα} mimetypes.inited

Flag indicating whether or not the global data structures have been initialized.
This is set to @code{True} by @ref{3ece,,init()}.
@end deffn

@geindex knownfiles (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes knownfiles}@anchor{3ed0}
@deffn {Δεδομένα} 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 (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes suffix_map}@anchor{3ed3}
@deffn {Δεδομένα} 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 (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes encodings_map}@anchor{3ed4}
@deffn {Δεδομένα} mimetypes.encodings_map

Dictionary mapping filename extensions to encoding types.
@end deffn

@geindex types_map (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes types_map}@anchor{3ed5}
@deffn {Δεδομένα} mimetypes.types_map

Dictionary mapping filename extensions to MIME types.
@end deffn

@geindex common_types (στη μονάδα mimetypes)
@anchor{library/mimetypes mimetypes common_types}@anchor{3ed6}
@deffn {Δεδομένα} mimetypes.common_types

Dictionary mapping filename extensions to non-standard, but commonly found MIME
types.
@end deffn

An example usage of the 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:: 
* Command-line usage: Command-line usage<2>. 
* Command-line example:: 

@end menu

@node MimeTypes objects,Command-line usage<2>,,mimetypes — Map filenames to MIME types
@anchor{library/mimetypes id1}@anchor{3ed7}@anchor{library/mimetypes mimetypes-objects}@anchor{3ed8}
@subsubsection MimeTypes objects


The @ref{189d,,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
@code{mimetypes} module.

@geindex MimeTypes (κλάση σε mimetypes)
@anchor{library/mimetypes mimetypes MimeTypes}@anchor{189d}
@deffn {Κλάση} 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{3ed9,,read()} or
@ref{3eda,,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 (ιδιότητα της mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes suffix_map}@anchor{3edb}
@deffn {Ιδιότητα} 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{3ed3,,suffix_map} defined in the module.
@end deffn

@geindex encodings_map (ιδιότητα της mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes encodings_map}@anchor{3edc}
@deffn {Ιδιότητα} encodings_map

Dictionary mapping filename extensions to encoding types.  This is initially a
copy of the global @ref{3ed4,,encodings_map} defined in the module.
@end deffn

@geindex types_map (ιδιότητα της mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes types_map}@anchor{3edd}
@deffn {Ιδιότητα} 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{3ed6,,common_types} and
@ref{3ed5,,types_map}.
@end deffn

@geindex types_map_inv (ιδιότητα της mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes types_map_inv}@anchor{3ede}
@deffn {Ιδιότητα} 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{3ed6,,common_types} and @ref{3ed5,,types_map}.
@end deffn

@geindex guess_extension() (μέθοδος της mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes guess_extension}@anchor{3edf}
@deffn {Μέθοδος} guess_extension (type, strict=True)

Similar to the @ref{3ecf,,guess_extension()} function, using the tables stored as part
of the object.
@end deffn

@geindex guess_type() (μέθοδος της mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes guess_type}@anchor{2007}
@deffn {Μέθοδος} guess_type (url, strict=True)

Similar to the @ref{71b,,guess_type()} function, using the tables stored as part of
the object.
@end deffn

@geindex guess_file_type() (μέθοδος της mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes guess_file_type}@anchor{3ee0}
@deffn {Μέθοδος} guess_file_type (path, *, strict=True)

Similar to the @ref{71a,,guess_file_type()} function, using the tables stored
as part of the object.


Added in version 3.13.

@end deffn

@geindex guess_all_extensions() (μέθοδος της mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes guess_all_extensions}@anchor{3ee1}
@deffn {Μέθοδος} guess_all_extensions (type, strict=True)

Similar to the @ref{1e41,,guess_all_extensions()} function, using the tables stored
as part of the object.
@end deffn

@geindex read() (μέθοδος της mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes read}@anchor{3ed9}
@deffn {Μέθοδος} read (filename, strict=True)

Load MIME information from a file named `filename'.  This uses @ref{3eda,,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() (μέθοδος της mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes readfp}@anchor{3eda}
@deffn {Μέθοδος} 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() (μέθοδος της mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes read_windows_registry}@anchor{3ee2}
@deffn {Μέθοδος} read_windows_registry (strict=True)

Load MIME type information from the Windows registry.

@ref{232d,,Διαθεσιμότητα}: Windows.

If `strict' is @code{True}, information will be added to the list of standard
types, else to the list of non-standard types.


Added in version 3.2.

@end deffn

@geindex add_type() (μέθοδος της mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes add_type}@anchor{30c}
@deffn {Μέθοδος} add_type (type, ext, strict=True)

Add a mapping from the MIME type `type' to the extension `ext'.
Valid extensions start with a “.” or are empty. 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.


Καταργήθηκε από την έκδοση 3.14, αφαιρέθηκε στην έκδοση 3.16: Invalid, undotted extensions will raise a
@ref{277,,ValueError} in Python 3.16.

@end deffn
@end deffn

@node Command-line usage<2>,Command-line example,MimeTypes objects,mimetypes — Map filenames to MIME types
@anchor{library/mimetypes command-line-usage}@anchor{3ee3}@anchor{library/mimetypes mimetypes-cli}@anchor{4d3}
@subsubsection Command-line usage


The @code{mimetypes} module can be executed as a script from the command line.

@example
python -m mimetypes [-h] [-e] [-l] type [type ...]
@end example

The following options are accepted:

@geindex mimetypes command line option; -h
@geindex mimetypes command line option; --help
@anchor{library/mimetypes cmdoption-mimetypes-h}@anchor{3ee4}
@deffn {Επιλογή Προγράμματος} @w{-}h
@anchor{library/mimetypes cmdoption-mimetypes-help}@anchor{3ee5}
@deffnx {Επιλογή Προγράμματος} @w{-}@w{-}help

Show the help message and exit.
@end deffn

@geindex mimetypes command line option; -e
@geindex mimetypes command line option; --extension
@anchor{library/mimetypes cmdoption-mimetypes-e}@anchor{3ee6}
@deffn {Επιλογή Προγράμματος} @w{-}e
@anchor{library/mimetypes cmdoption-mimetypes-extension}@anchor{3ee7}
@deffnx {Επιλογή Προγράμματος} @w{-}@w{-}extension

Guess extension instead of type.
@end deffn

@geindex mimetypes command line option; -l
@geindex mimetypes command line option; --lenient
@anchor{library/mimetypes cmdoption-mimetypes-l}@anchor{3ee8}
@deffn {Επιλογή Προγράμματος} @w{-}l
@anchor{library/mimetypes cmdoption-mimetypes-lenient}@anchor{3ee9}
@deffnx {Επιλογή Προγράμματος} @w{-}@w{-}lenient

Additionally search for some common, but non-standard types.
@end deffn

By default the script converts MIME types to file extensions.
However, if @code{--extension} is specified,
it converts file extensions to MIME types.

For each @code{type} entry, the script writes a line into the standard output
stream. If an unknown type occurs, it writes an error message into the
standard error stream and exits with the return code @code{1}.

@c mimetypes-cli-example:

@node Command-line example,,Command-line usage<2>,mimetypes — Map filenames to MIME types
@anchor{library/mimetypes command-line-example}@anchor{3eea}
@subsubsection Command-line example


Here are some examples of typical usage of the @code{mimetypes} command-line
interface:

@example
$ # get a MIME type by a file name
$ python -m mimetypes filename.png
type: image/png encoding: None

$ # get a MIME type by a URL
$ python -m mimetypes https://example.com/filename.txt
type: text/plain encoding: None

$ # get a complex MIME type
$ python -m mimetypes filename.tar.gz
type: application/x-tar encoding: gzip

$ # get a MIME type for a rare file extension
$ python -m mimetypes filename.pict
error: unknown extension of filename.pict

$ # now look in the extended database built into Python
$ python -m mimetypes --lenient filename.pict
type: image/pict encoding: None

$ # get a file extension by a MIME type
$ python -m mimetypes --extension text/javascript
.js

$ # get a file extension by a rare MIME type
$ python -m mimetypes --extension text/xul
error: unknown type text/xul

$ # now look in the extended database again
$ python -m mimetypes --extension --lenient text/xul
.xul

$ # try to feed an unknown file extension
$ python -m mimetypes filename.sh filename.nc filename.xxx filename.txt
type: application/x-sh encoding: None
type: application/x-netcdf encoding: None
error: unknown extension of filename.xxx

$ # try to feed an unknown MIME type
$ python -m mimetypes --extension audio/aac audio/opus audio/future audio/x-wav
.aac
.opus
error: unknown type audio/future
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node base64 — Base16 Base32 Base64 Base85 Data Encodings,binascii — Convert between binary and ASCII,mimetypes — Map filenames to MIME types,Internet Data Handling
@anchor{library/base64 doc}@anchor{3eeb}@anchor{library/base64 base64-base16-base32-base64-base85-data-encodings}@anchor{3eec}@anchor{library/base64 module-base64}@anchor{f}@anchor{library/base64 translation-repo}@anchor{3eed}
@subsection @code{base64} — Base16, Base32, Base64, Base85 Data Encodings


@geindex module; base64

`Source code:' Lib/base64.py@footnote{https://github.com/python/cpython/tree/main/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.
This includes the @ref{3eee,,encodings specified in}
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} (Base64, Base32 and Base16)
and the non-standard @ref{3eef,,Base85 encodings}.

There are two interfaces provided by this module.  The modern interface
supports encoding @ref{436,,bytes-like objects} to ASCII
@ref{1c7,,bytes}, and decoding bytes-like objects or
strings containing ASCII to @code{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.

The @ref{3ef0,,legacy interface} does not support decoding from strings, but it does
provide functions for encoding and decoding to and from @ref{156c,,file objects}.  It only supports the Base64 standard alphabet, and it adds
newlines every 76 characters as per 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}.  Note that if you are looking
for 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} support you probably want to be looking at the @ref{3e,,email}
package instead.


Άλλαξε στην έκδοση 3.3: ASCII-only Unicode strings are now accepted by the decoding functions of
the modern interface.



Άλλαξε στην έκδοση 3.4: Any @ref{436,,bytes-like objects} are now accepted by all
encoding and decoding functions in this module.  Ascii85/Base85 support added.


@menu
* RFC 4648 Encodings:: 
* Base85 Encodings:: 
* Legacy Interface:: 
* Security Considerations: Security Considerations<2>. 

@end menu

@node RFC 4648 Encodings,Base85 Encodings,,base64 — Base16 Base32 Base64 Base85 Data Encodings
@anchor{library/base64 base64-rfc-4648}@anchor{3eee}@anchor{library/base64 rfc-4648-encodings}@anchor{3ef1}
@subsubsection RFC 4648 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.

@geindex b64encode() (στη μονάδα base64)
@anchor{library/base64 base64 b64encode}@anchor{1eb}
@deffn {Συνάρτηση} base64.b64encode (s, altchars=None, *, padded=True, wrapcol=0)

Encode the @ref{436,,bytes-like object} `s' using Base64 and return the encoded
@ref{1c7,,bytes}.

Optional `altchars' must be a @ref{436,,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.

If `padded' is true (default), pad the encoded data with the “=”
character to a size multiple of 4.
If `padded' is false, do not add the pad characters.

If `wrapcol' is non-zero, insert a newline (@code{b'\n'}) character
after at most every `wrapcol' characters.
If `wrapcol' is zero (default), do not insert any newlines.


Άλλαξε στην έκδοση 3.15: Added the `padded' and `wrapcol' parameters.

@end deffn

@geindex b64decode() (στη μονάδα base64)
@anchor{library/base64 base64 b64decode}@anchor{1ec}
@deffn {Συνάρτηση} base64.b64decode (s, altchars=None, validate=False, *, padded=True, canonical=False)

@deffnx {Συνάρτηση} base64.b64decode (s, altchars=None, validate=True, *, ignorechars, padded=True, canonical=False)

Decode the Base64 encoded @ref{436,,bytes-like object} or ASCII string
`s' and return the decoded @ref{1c7,,bytes}.

Optional `altchars' must be a @ref{436,,bytes-like object} or ASCII string
of length 2 which specifies the alternative alphabet used instead of the
@code{+} and @code{/} characters.

If `padded' is true, the last group of 4 base 64 alphabet characters must
be padded with the “=” character.
If `padded' is false, padding is neither required nor recognized:
the “=” character is not treated as padding but as a non-alphabet
character, which means it is silently discarded when `validate' is false,
or causes an @ref{13ce,,Error} when `validate' is true unless
b”=” is included in `ignorechars'.

A @ref{13ce,,binascii.Error} exception is raised
if `s' is incorrectly padded.

If `ignorechars' is specified, it should be a @ref{436,,bytes-like object}
containing characters to ignore from the input when `validate' is true.
If `ignorechars' contains the pad character @code{'='},  the pad characters
presented before the end of the encoded data and the excess pad characters
will be ignored.
The default value of `validate' is @code{True} if `ignorechars' is specified,
@code{False} otherwise.

If `validate' is false, characters that are neither
in the normal base-64 alphabet nor (if `ignorechars' is not specified)
the alternative alphabet are
discarded prior to the padding check, but the @code{+} and @code{/} characters
keep their meaning if they are not in `altchars' (they will be discarded
in future Python versions).

If `validate' is true, these non-alphabet characters in the input
result in a @ref{13ce,,binascii.Error}.

If `canonical' is true, non-zero padding bits are rejected.
See @ref{1fd,,binascii.a2b_base64()} for details.

For more information about the strict base64 check, see @ref{1fd,,binascii.a2b_base64()}


Άλλαξε στην έκδοση 3.15: Added the `canonical', `ignorechars', and `padded' parameters.



Αποσύρθηκε στην έκδοση 3.15: Accepting the @code{+} and @code{/} characters with an alternative alphabet
is now deprecated.

@end deffn

@geindex standard_b64encode() (στη μονάδα base64)
@anchor{library/base64 base64 standard_b64encode}@anchor{3ef2}
@deffn {Συνάρτηση} base64.standard_b64encode (s)

Encode @ref{436,,bytes-like object} `s' using the standard Base64 alphabet
and return the encoded @ref{1c7,,bytes}.
@end deffn

@geindex standard_b64decode() (στη μονάδα base64)
@anchor{library/base64 base64 standard_b64decode}@anchor{3ef3}
@deffn {Συνάρτηση} base64.standard_b64decode (s)

Decode @ref{436,,bytes-like object} or ASCII string `s' using the standard
Base64 alphabet and return the decoded @ref{1c7,,bytes}.
@end deffn

@geindex urlsafe_b64encode() (στη μονάδα base64)
@anchor{library/base64 base64 urlsafe_b64encode}@anchor{1ed}
@deffn {Συνάρτηση} base64.urlsafe_b64encode (s, *, padded=True)

Encode @ref{436,,bytes-like object} `s' using the
URL- and filesystem-safe alphabet, which
substitutes @code{-} instead of @code{+} and @code{_} instead of @code{/} in the
standard Base64 alphabet, and return the encoded @ref{1c7,,bytes}.  The result
can still contain @code{=} if `padded' is true (default).


Άλλαξε στην έκδοση 3.15: Added the `padded' parameter.

@end deffn

@geindex urlsafe_b64decode() (στη μονάδα base64)
@anchor{library/base64 base64 urlsafe_b64decode}@anchor{1ee}
@deffn {Συνάρτηση} base64.urlsafe_b64decode (s, *, padded=False)

Decode @ref{436,,bytes-like object} or ASCII string `s'
using the URL- and filesystem-safe
alphabet, which substitutes @code{-} instead of @code{+} and @code{_} instead of
@code{/} in the standard Base64 alphabet, and return the decoded
@ref{1c7,,bytes}.


Άλλαξε στην έκδοση 3.15: Added the `padded' parameter.
Padding of input is no longer required by default.



Αποσύρθηκε στην έκδοση 3.15: Accepting the @code{+} and @code{/} characters is now deprecated.

@end deffn

@geindex b32encode() (στη μονάδα base64)
@anchor{library/base64 base64 b32encode}@anchor{1e7}
@deffn {Συνάρτηση} base64.b32encode (s, *, padded=True, wrapcol=0)

Encode the @ref{436,,bytes-like object} `s' using Base32 and return the
encoded @ref{1c7,,bytes}.

If `padded' is true (default), pad the encoded data with the “=”
character to a size multiple of 8.
If `padded' is false, do not add the pad characters.

If `wrapcol' is non-zero, insert a newline (@code{b'\n'}) character
after at most every `wrapcol' characters.
If `wrapcol' is zero (default), do not add any newlines.


Άλλαξε στην έκδοση 3.15: Added the `padded' and `wrapcol' parameters.

@end deffn

@geindex b32decode() (στη μονάδα base64)
@anchor{library/base64 base64 b32decode}@anchor{1e8}
@deffn {Συνάρτηση} base64.b32decode (s, casefold=False, map01=None, *, padded=True, ignorechars=b'@w{'}, canonical=False)

Decode the Base32 encoded @ref{436,,bytes-like object} or ASCII string `s' and
return the decoded @ref{1c7,,bytes}.

Optional `casefold' is a flag specifying
whether a lowercase alphabet is acceptable as input.  For security purposes,
the default is @code{False}.

@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.

If `padded' is true, the last group of 8 base 32 alphabet characters must
be padded with the “=” character.
If `padded' is false, padding is neither required nor recognized:
the “=” character is not treated as padding but as a non-alphabet
character, which means it raises an @ref{13ce,,Error} unless
b”=” is included in `ignorechars'.

`ignorechars' should be a @ref{436,,bytes-like object} containing characters
to ignore from the input.

If `canonical' is true, non-zero padding bits are rejected.
See @ref{1f7,,binascii.a2b_base32()} for details.

A @ref{13ce,,binascii.Error} is raised if `s' is
incorrectly padded or if there are non-alphabet characters present in the
input.


Άλλαξε στην έκδοση 3.15: Added the `canonical', `ignorechars', and `padded' parameters.

@end deffn

@geindex b32hexencode() (στη μονάδα base64)
@anchor{library/base64 base64 b32hexencode}@anchor{1e9}
@deffn {Συνάρτηση} base64.b32hexencode (s, *, padded=True, wrapcol=0)

Similar to @ref{1e7,,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}.


Added in version 3.10.



Άλλαξε στην έκδοση 3.15: Added the `padded' and `wrapcol' parameters.

@end deffn

@geindex b32hexdecode() (στη μονάδα base64)
@anchor{library/base64 base64 b32hexdecode}@anchor{1ea}
@deffn {Συνάρτηση} base64.b32hexdecode (s, casefold=False, *, padded=True, ignorechars=b'@w{'}, canonical=False)

Similar to @ref{1e8,,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.


Added in version 3.10.



Άλλαξε στην έκδοση 3.15: Added the `canonical', `ignorechars', and `padded' parameters.

@end deffn

@geindex b16encode() (στη μονάδα base64)
@anchor{library/base64 base64 b16encode}@anchor{1ef}
@deffn {Συνάρτηση} base64.b16encode (s, *, wrapcol=0)

Encode the @ref{436,,bytes-like object} `s' using Base16 and return the
encoded @ref{1c7,,bytes}.

If `wrapcol' is non-zero, insert a newline (@code{b'\n'}) character
after at most every `wrapcol' characters.
If `wrapcol' is zero (default), do not add any newlines.


Άλλαξε στην έκδοση 3.15: Added the `wrapcol' parameter.

@end deffn

@geindex b16decode() (στη μονάδα base64)
@anchor{library/base64 base64 b16decode}@anchor{1f1}
@deffn {Συνάρτηση} base64.b16decode (s, casefold=False, *, ignorechars=b'@w{'})

Decode the Base16 encoded @ref{436,,bytes-like object} or ASCII string `s' and
return the decoded @ref{1c7,,bytes}.

Optional `casefold' is a flag specifying whether a
lowercase alphabet is acceptable as input.  For security purposes, the default
is @code{False}.

`ignorechars' should be a @ref{436,,bytes-like object} containing characters
to ignore from the input.

A @ref{13ce,,binascii.Error} is raised if `s' is
incorrectly padded or if there are non-alphabet characters present in the
input.


Άλλαξε στην έκδοση 3.15: Added the `ignorechars' parameter.

@end deffn

@node Base85 Encodings,Legacy Interface,RFC 4648 Encodings,base64 — Base16 Base32 Base64 Base85 Data Encodings
@anchor{library/base64 base64-base-85}@anchor{3eef}@anchor{library/base64 base85-encodings}@anchor{3ef4}
@subsubsection Base85 Encodings


Base85 encoding is not formally specified but rather a de facto standard,
thus different systems perform the encoding differently.

The @ref{12ce,,a85encode()} and @ref{1f0,,b85encode()} functions in this module are two implementations of
the de facto standard. You should call the function with the Base85
implementation used by the software you intend to work with.

The two functions present in this module differ in how they handle the following:


@itemize *

@item 
Whether to include enclosing @code{<~} and @code{~>} markers

@item 
Whether to include newline characters

@item 
The set of ASCII characters used for encoding

@item 
Handling of null bytes
@end itemize

Refer to the documentation of the individual functions for more information.

@geindex a85encode() (στη μονάδα base64)
@anchor{library/base64 base64 a85encode}@anchor{12ce}
@deffn {Συνάρτηση} base64.a85encode (b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

Encode the @ref{436,,bytes-like object} `b' using Ascii85 and return the
encoded @ref{1c7,,bytes}.

`foldspaces' is an optional flag that uses the special short sequence “y”
instead of 4 consecutive spaces (ASCII 0x20) as supported by “btoa”. This
feature is not supported by the «standard» Ascii85 encoding.

If `wrapcol' is non-zero, insert a newline (@code{b'\n'}) character
after at most every `wrapcol' characters.
If `wrapcol' is zero (default), do not insert any newlines.

If `pad' is true, the input is padded with @code{b'\0'} so its length is a
multiple of 4 bytes before encoding.
Note that the @code{btoa} implementation always pads.

`adobe' controls whether the encoded byte sequence is framed with @code{<~}
and @code{~>}, which is used by the Adobe implementation.


Added in version 3.4.

@end deffn

@geindex a85decode() (στη μονάδα base64)
@anchor{library/base64 base64 a85decode}@anchor{1f4}
@deffn {Συνάρτηση} base64.a85decode (b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\x0b', canonical=False)

Decode the Ascii85 encoded @ref{436,,bytes-like object} or ASCII string `b' and
return the decoded @ref{1c7,,bytes}.

`foldspaces' is a flag that specifies whether the “y” short sequence
should be accepted as shorthand for 4 consecutive spaces (ASCII 0x20).
This feature is not supported by the «standard» Ascii85 encoding.

`adobe' controls whether the input sequence is in Adobe Ascii85 format
(i.e. is framed with <~ and ~>).

`ignorechars' should be a @ref{436,,bytes-like object} containing characters
to ignore from the input.
This should only contain whitespace characters, and by
default contains all whitespace characters in ASCII.

If `canonical' is true, non-canonical encodings are rejected.
See @ref{1f9,,binascii.a2b_ascii85()} for details.


Added in version 3.4.



Άλλαξε στην έκδοση 3.15: Added the `canonical' parameter.
Single-character final groups are now always rejected as encoding
violations.

@end deffn

@geindex b85encode() (στη μονάδα base64)
@anchor{library/base64 base64 b85encode}@anchor{1f0}
@deffn {Συνάρτηση} base64.b85encode (b, pad=False, *, wrapcol=0)

Encode the @ref{436,,bytes-like object} `b' using base85 (as used in e.g.
git-style binary diffs) and return the encoded @ref{1c7,,bytes}.

If `pad' is true, the input is padded with @code{b'\0'} so its length is a
multiple of 4 bytes before encoding.

If `wrapcol' is non-zero, insert a newline (@code{b'\n'}) character
after at most every `wrapcol' characters.
If `wrapcol' is zero (default), do not add any newlines.


Added in version 3.4.



Άλλαξε στην έκδοση 3.15: Added the `wrapcol' parameter.

@end deffn

@geindex b85decode() (στη μονάδα base64)
@anchor{library/base64 base64 b85decode}@anchor{1f2}
@deffn {Συνάρτηση} base64.b85decode (b, *, ignorechars=b'@w{'}, canonical=False)

Decode the base85-encoded @ref{436,,bytes-like object} or ASCII string `b' and
return the decoded @ref{1c7,,bytes}.  Padding is implicitly removed, if
necessary.

`ignorechars' should be a @ref{436,,bytes-like object} containing characters
to ignore from the input.

If `canonical' is true, non-canonical encodings are rejected.
See @ref{1fb,,binascii.a2b_base85()} for details.


Added in version 3.4.



Άλλαξε στην έκδοση 3.15: Added the `canonical' and `ignorechars' parameters.
Single-character final groups are now always rejected as encoding
violations.

@end deffn

@geindex z85encode() (στη μονάδα base64)
@anchor{library/base64 base64 z85encode}@anchor{1e6}
@deffn {Συνάρτηση} base64.z85encode (s, pad=False, *, wrapcol=0)

Encode the @ref{436,,bytes-like object} `s' using Z85 (as used in ZeroMQ)
and return the encoded @ref{1c7,,bytes}.  See Z85 specification@footnote{https://rfc.zeromq.org/spec/32/} for more information.

If `pad' is true, the input is padded with @code{b'\0'} so its length is a
multiple of 4 bytes before encoding.

If `wrapcol' is non-zero, insert a newline (@code{b'\n'}) character
after at most every `wrapcol' characters.
If `wrapcol' is zero (default), do not add any newlines.


Added in version 3.13.



Άλλαξε στην έκδοση 3.15: The `pad' parameter was added.



Άλλαξε στην έκδοση 3.15: Added the `wrapcol' parameter.

@end deffn

@geindex z85decode() (στη μονάδα base64)
@anchor{library/base64 base64 z85decode}@anchor{1f3}
@deffn {Συνάρτηση} base64.z85decode (s, *, ignorechars=b'@w{'}, canonical=False)

Decode the Z85-encoded @ref{436,,bytes-like object} or ASCII string `s' and
return the decoded @ref{1c7,,bytes}.  See Z85 specification@footnote{https://rfc.zeromq.org/spec/32/} for more information.

`ignorechars' should be a @ref{436,,bytes-like object} containing characters
to ignore from the input.

If `canonical' is true, non-canonical encodings are rejected.
See @ref{1fb,,binascii.a2b_base85()} for details.


Added in version 3.13.



Άλλαξε στην έκδοση 3.15: Added the `canonical' and `ignorechars' parameters.
Single-character final groups are now always rejected as encoding
violations.

@end deffn

@node Legacy Interface,Security Considerations<2>,Base85 Encodings,base64 — Base16 Base32 Base64 Base85 Data Encodings
@anchor{library/base64 base64-legacy}@anchor{3ef0}@anchor{library/base64 legacy-interface}@anchor{3ef5}
@subsubsection Legacy Interface


@geindex decode() (στη μονάδα base64)
@anchor{library/base64 base64 decode}@anchor{3ef6}
@deffn {Συνάρτηση} base64.decode (input, output)

Decode the contents of the binary `input' file and write the resulting binary
data to the `output' file. `input' and `output' must be @ref{156c,,file objects}. `input' will be read until @code{input.readline()} returns an
empty bytes object.
@end deffn

@geindex decodebytes() (στη μονάδα base64)
@anchor{library/base64 base64 decodebytes}@anchor{d1f}
@deffn {Συνάρτηση} base64.decodebytes (s)

Decode the @ref{436,,bytes-like object} `s', which must contain one or more
lines of base64 encoded data, and return the decoded @ref{1c7,,bytes}.


Added in version 3.1.

@end deffn

@geindex encode() (στη μονάδα base64)
@anchor{library/base64 base64 encode}@anchor{3ef7}
@deffn {Συνάρτηση} base64.encode (input, output)

Encode the contents of the binary `input' file and write the resulting base64
encoded data to the `output' file. `input' and `output' must be @ref{156c,,file objects}. `input' will be read until @code{input.read()} returns
an empty bytes object. @code{encode()} inserts a newline character (@code{b'\n'})
after every 76 bytes of the output, as well as ensuring that the output
always ends with a newline, as per 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} (MIME).
@end deffn

@geindex encodebytes() (στη μονάδα base64)
@anchor{library/base64 base64 encodebytes}@anchor{d1e}
@deffn {Συνάρτηση} base64.encodebytes (s)

Encode the @ref{436,,bytes-like object} `s', which can contain arbitrary binary
data, and return @ref{1c7,,bytes} containing the base64-encoded data, with newlines
(@code{b'\n'}) inserted after every 76 bytes of output, and ensuring that
there is a trailing newline, as per 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} (MIME).


Added in version 3.1.

@end deffn

An example usage of the 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

@node Security Considerations<2>,,Legacy Interface,base64 — Base16 Base32 Base64 Base85 Data Encodings
@anchor{library/base64 base64-security}@anchor{3ef8}@anchor{library/base64 security-considerations}@anchor{3ef9}
@subsubsection Security Considerations


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 Δείτε επίσης



@table @asis

@item Module @ref{11,,binascii}

Support module containing ASCII-to-binary and binary-to-ASCII conversions.

@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

Section 5.2, «Base64 Content-Transfer-Encoding,» provides the definition of the
base64 encoding.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node binascii — Convert between binary and ASCII,quopri — Encode and decode MIME quoted-printable data,base64 — Base16 Base32 Base64 Base85 Data Encodings,Internet Data Handling
@anchor{library/binascii doc}@anchor{3efa}@anchor{library/binascii binascii-convert-between-binary-and-ascii}@anchor{3efb}@anchor{library/binascii module-binascii}@anchor{11}@anchor{library/binascii translation-repo}@anchor{3efc}
@subsection @code{binascii} — Convert between binary and ASCII


@geindex module; binascii

@geindex module;base64


__________________________________________________________________


The @code{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{f,,base64} instead. The @code{binascii} module contains
low-level functions written in C for greater speed that are used by the
higher-level modules.

@cartouche
@quotation Σημείωση 
@code{a2b_*} functions accept Unicode strings containing only ASCII characters.
Other functions only accept @ref{436,,bytes-like objects} (such as
@ref{1c7,,bytes}, @ref{1c6,,bytearray} and other objects that support the buffer
protocol).


Άλλαξε στην έκδοση 3.3: ASCII-only unicode strings are now accepted by the @code{a2b_*} functions.

@end quotation
@end cartouche

The @code{binascii} module defines the following functions:

@geindex a2b_uu() (στη μονάδα binascii)
@anchor{library/binascii binascii a2b_uu}@anchor{1905}
@deffn {Συνάρτηση} binascii.a2b_uu (string)

Convert a single line of uuencoded data back to binary and return the binary
data. Lines normally contain 45 (binary) bytes, except for the last line. Line
data may be followed by whitespace.
@end deffn

@geindex b2a_uu() (στη μονάδα binascii)
@anchor{library/binascii binascii b2a_uu}@anchor{ee4}
@deffn {Συνάρτηση} binascii.b2a_uu (data, *, backtick=False)

Convert binary data to a line of ASCII characters, the return value is the
converted line, including a newline char. The length of `data' should be at most
45. If `backtick' is true, zeros are represented by @code{'`'} instead of spaces.


Άλλαξε στην έκδοση 3.7: Added the `backtick' parameter.

@end deffn

@geindex a2b_base64() (στη μονάδα binascii)
@anchor{library/binascii binascii a2b_base64}@anchor{1fd}
@deffn {Συνάρτηση} binascii.a2b_base64 (string, /, *, padded=True, alphabet=BASE64_ALPHABET, strict_mode=False, canonical=False)

@deffnx {Συνάρτηση} binascii.a2b_base64 (string, /, *, ignorechars, padded=True, alphabet=BASE64_ALPHABET, strict_mode=True, canonical=False)

Convert a block of base64 data back to binary and return the binary data. More
than one line may be passed at a time.

Optional `alphabet' must be a @ref{1c7,,bytes} object of length 64 which
specifies an alternative alphabet.

If `padded' is true, the last group of 4 base 64 alphabet characters must
be padded with the “=” character.
If `padded' is false, padding is neither required nor recognized:
the “=” character is not treated as padding but as a non-alphabet
character, which means it is silently discarded when `strict_mode' is false,
or causes an @ref{13ce,,Error} when `strict_mode' is true unless
b”=” is included in `ignorechars'.

If `ignorechars' is specified, it should be a @ref{436,,bytes-like object}
containing characters to ignore from the input when `strict_mode' is true.
If `ignorechars' contains the pad character @code{'='},  the pad characters
presented before the end of the encoded data and the excess pad characters
will be ignored.
The default value of `strict_mode' is @code{True} if `ignorechars' is specified,
@code{False} otherwise.

If `strict_mode' is true, only valid base64 data will be converted. Invalid base64
data will raise @ref{13ce,,binascii.Error}.

Valid base64:


@itemize *

@item 
Conforms to 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.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

If `canonical' is true, non-zero padding bits in the last group are rejected
with @ref{13ce,,binascii.Error}, enforcing canonical encoding as defined in
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} section 3.5.  This check is independent of `strict_mode'.


Άλλαξε στην έκδοση 3.11: Added the `strict_mode' parameter.



Άλλαξε στην έκδοση 3.15: Added the `alphabet', `canonical', `ignorechars', and `padded' parameters.

@end deffn

@geindex b2a_base64() (στη μονάδα binascii)
@anchor{library/binascii binascii b2a_base64}@anchor{1fc}
@deffn {Συνάρτηση} binascii.b2a_base64 (data, *, padded=True, alphabet=BASE64_ALPHABET, wrapcol=0, newline=True)

Convert binary data to a line(s) of ASCII characters in base64 coding,
as specified in 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}.

If `padded' is true (default), pad the encoded data with the “=”
character to a size multiple of 4.
If `padded' is false, do not add the pad characters.

If `wrapcol' is non-zero, insert a newline (@code{b'\n'}) character
after at most every `wrapcol' characters.
If `wrapcol' is zero (default), do not insert any newlines.

If `newline' is true (default), a newline character will be added
at the end of the output.


Άλλαξε στην έκδοση 3.6: Added the `newline' parameter.



Άλλαξε στην έκδοση 3.15: Added the `alphabet', `padded' and `wrapcol' parameters.

@end deffn

@geindex a2b_ascii85() (στη μονάδα binascii)
@anchor{library/binascii binascii a2b_ascii85}@anchor{1f9}
@deffn {Συνάρτηση} binascii.a2b_ascii85 (string, /, *, foldspaces=False, adobe=False, ignorechars=b'@w{'}, canonical=False)

Convert Ascii85 data back to binary and return the binary data.

Valid Ascii85 data contains characters from the Ascii85 alphabet in groups
of five (except for the final group, which may have from two to five
characters). Each group encodes 32 bits of binary data in the range from
@code{0} to @code{2 ** 32 - 1}, inclusive. The special character @code{z} is
accepted as a short form of the group @code{!!!!!}, which encodes four
consecutive null bytes. A single-character final group is always rejected
as an encoding violation.

`foldspaces' is a flag that specifies whether the “y” short sequence
should be accepted as shorthand for 4 consecutive spaces (ASCII 0x20).
This feature is not supported by the «standard» Ascii85 encoding.

`adobe' controls whether the input sequence is in Adobe Ascii85 format
(i.e. is framed with <~ and ~>).

`ignorechars' should be a @ref{436,,bytes-like object} containing characters
to ignore from the input.
This should only contain whitespace characters.

If `canonical' is true, non-canonical encodings are rejected with
@ref{13ce,,binascii.Error}.  Here «canonical» means the encoding that
@ref{1f8,,b2a_ascii85()} would produce: the @code{z} abbreviation must be used
for all-zero groups (rather than @code{!!!!!}), and partial final groups
must use the same padding digits as the encoder.

Invalid Ascii85 data will raise @ref{13ce,,binascii.Error}.


Added in version 3.15.

@end deffn

@geindex b2a_ascii85() (στη μονάδα binascii)
@anchor{library/binascii binascii b2a_ascii85}@anchor{1f8}
@deffn {Συνάρτηση} binascii.b2a_ascii85 (data, /, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

Convert binary data to a formatted sequence of ASCII characters in Ascii85
coding. The return value is the converted data.

`foldspaces' is an optional flag that uses the special short sequence “y”
instead of 4 consecutive spaces (ASCII 0x20) as supported by “btoa”. This
feature is not supported by the «standard» Ascii85 encoding.

If `wrapcol' is non-zero, insert a newline (@code{b'\n'}) character
after at most every `wrapcol' characters.
If `wrapcol' is zero (default), do not insert any newlines.

If `pad' is true, the input is padded with @code{b'\0'} so its length is a
multiple of 4 bytes before encoding.
Note that the @code{btoa} implementation always pads.

`adobe' controls whether the encoded byte sequence is framed with @code{<~}
and @code{~>}, which is used by the Adobe implementation.


Added in version 3.15.

@end deffn

@geindex a2b_base85() (στη μονάδα binascii)
@anchor{library/binascii binascii a2b_base85}@anchor{1fb}
@deffn {Συνάρτηση} binascii.a2b_base85 (string, /, *, alphabet=BASE85_ALPHABET, ignorechars=b'@w{'}, canonical=False)

Convert Base85 data back to binary and return the binary data.
More than one line may be passed at a time.

Valid Base85 data contains characters from the Base85 alphabet in groups
of five (except for the final group, which may have from two to five
characters). Each group encodes 32 bits of binary data in the range from
@code{0} to @code{2 ** 32 - 1}, inclusive. A single-character final group is
always rejected as an encoding violation.

Optional `alphabet' must be a @ref{1c7,,bytes} object of length 85 which
specifies an alternative alphabet.

`ignorechars' should be a @ref{436,,bytes-like object} containing characters
to ignore from the input.

If `canonical' is true, non-canonical encodings are rejected with
@ref{13ce,,binascii.Error}.  Here «canonical» means the encoding that
@ref{1fa,,b2a_base85()} would produce: partial final groups must use the
same padding digits as the encoder.

Invalid Base85 data will raise @ref{13ce,,binascii.Error}.


Added in version 3.15.

@end deffn

@geindex b2a_base85() (στη μονάδα binascii)
@anchor{library/binascii binascii b2a_base85}@anchor{1fa}
@deffn {Συνάρτηση} binascii.b2a_base85 (data, /, *, alphabet=BASE85_ALPHABET, wrapcol=0, pad=False)

Convert binary data to a line of ASCII characters in Base85 coding.
The return value is the converted line.

Optional `alphabet' must be a @ref{436,,bytes-like object} of length 85 which
specifies an alternative alphabet.

If `wrapcol' is non-zero, insert a newline (@code{b'\n'}) character
after at most every `wrapcol' characters.
If `wrapcol' is zero (default), do not insert any newlines.

If `pad' is true, the input is padded with @code{b'\0'} so its length is a
multiple of 4 bytes before encoding.


Added in version 3.15.

@end deffn

@geindex a2b_base32() (στη μονάδα binascii)
@anchor{library/binascii binascii a2b_base32}@anchor{1f7}
@deffn {Συνάρτηση} binascii.a2b_base32 (string, /, *, padded=True, alphabet=BASE32_ALPHABET, ignorechars=b'@w{'}, canonical=False)

Convert base32 data back to binary and return the binary data.

Valid base32 data contains characters from the base32 alphabet specified
in 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} in groups of eight (if necessary, the final group is padded
to eight characters with @code{=}). Each group encodes 40 bits of binary data
in the range from @code{0} to @code{2 ** 40 - 1}, inclusive.

@cartouche
@quotation Σημείωση 
This function does not map lowercase characters (which are invalid in
standard base32) to their uppercase counterparts, nor does it
contextually map @code{0} to @code{O} and @code{1} to @code{I}/@code{L} as 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}
allows.
@end quotation
@end cartouche

Optional `alphabet' must be a @ref{1c7,,bytes} object of length 32 which
specifies an alternative alphabet.

If `padded' is true, the last group of 8 base 32 alphabet characters must
be padded with the “=” character.
If `padded' is false, the “=” character is treated as other non-alphabet
characters (depending on the value of `ignorechars').

`ignorechars' should be a @ref{436,,bytes-like object} containing characters
to ignore from the input.
If `ignorechars' contains the pad character @code{'='},  the pad characters
presented before the end of the encoded data and the excess pad characters
will be ignored.

If `canonical' is true, non-zero padding bits in the last group are rejected
with @ref{13ce,,binascii.Error}, enforcing canonical encoding as defined in
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} section 3.5.

Invalid base32 data will raise @ref{13ce,,binascii.Error}.


Added in version 3.15.

@end deffn

@geindex b2a_base32() (στη μονάδα binascii)
@anchor{library/binascii binascii b2a_base32}@anchor{1f6}
@deffn {Συνάρτηση} binascii.b2a_base32 (data, /, *, padded=True, alphabet=BASE32_ALPHABET, wrapcol=0)

Convert binary data to a line of ASCII characters in base32 coding,
as specified in 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}. The return value is the converted line.

Optional `alphabet' must be a @ref{436,,bytes-like object} of length 32 which
specifies an alternative alphabet.

If `padded' is true (default), pad the encoded data with the “=”
character to a size multiple of 8.
If `padded' is false, do not add the pad characters.

If `wrapcol' is non-zero, insert a newline (@code{b'\n'}) character
after at most every `wrapcol' characters.
If `wrapcol' is zero (default), do not insert any newlines.


Added in version 3.15.

@end deffn

@geindex a2b_qp() (στη μονάδα binascii)
@anchor{library/binascii binascii a2b_qp}@anchor{3efd}
@deffn {Συνάρτηση} binascii.a2b_qp (data, header=False)

Convert a block of quoted-printable data back to binary and return the binary
data. More than one line may be passed at a time. If the optional argument
`header' is present and true, underscores will be decoded as spaces.
@end deffn

@geindex b2a_qp() (στη μονάδα binascii)
@anchor{library/binascii binascii b2a_qp}@anchor{3efe}
@deffn {Συνάρτηση} binascii.b2a_qp (data, quotetabs=False, istext=True, header=False)

Convert binary data to a line(s) of ASCII characters in quoted-printable
encoding.  The return value is the converted line(s). If the optional argument
`quotetabs' is present and true, all tabs and spaces will be encoded.   If the
optional argument `istext' is present and true, newlines are not encoded but
trailing whitespace will be encoded. If the optional argument `header' is
present and true, spaces will be encoded as underscores per 
@geindex RFC; RFC 1522
RFC 1522@footnote{https://datatracker.ietf.org/doc/html/rfc1522.html}. If the
optional argument `header' is present and false, newline characters will be
encoded as well; otherwise linefeed conversion might corrupt the binary data
stream.
@end deffn

@geindex crc_hqx() (στη μονάδα binascii)
@anchor{library/binascii binascii crc_hqx}@anchor{b1b}
@deffn {Συνάρτηση} binascii.crc_hqx (data, value)

Compute a 16-bit CRC value of `data', starting with `value' as the
initial CRC, and return the result.  This uses the CRC-CCITT polynomial
`x'@w{^16} + `x'@w{^12} + `x'@w{^5} + 1, often represented as
0x1021.  This CRC is used in the binhex4 format.
@end deffn

@geindex crc32() (στη μονάδα binascii)
@anchor{library/binascii binascii crc32}@anchor{1c19}
@deffn {Συνάρτηση} 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


Άλλαξε στην έκδοση 3.0: The result is always unsigned.

@end deffn

@geindex b2a_hex() (στη μονάδα binascii)
@geindex hexlify() (στη μονάδα binascii)
@anchor{library/binascii binascii b2a_hex}@anchor{192b}
@deffn {Συνάρτηση} binascii.b2a_hex (data[, sep[, bytes_per_sep=1]])
@anchor{library/binascii binascii hexlify}@anchor{1955}
@deffnx {Συνάρτηση} binascii.hexlify (data[, sep[, bytes_per_sep=1]])

Return the hexadecimal representation of the binary `data'.  Every byte of
`data' is converted into the corresponding 2-digit hex representation.  The
returned bytes object is therefore twice as long as the length of `data'.

Similar functionality (but returning a text string) is also conveniently
accessible using the @ref{111e,,bytes.hex()} method.

If `sep' is specified, it must be a single character str or bytes object.
It will be inserted in the output after every `bytes_per_sep' input bytes.
Separator placement is counted from the right end of the output by default,
if you wish to count from the left, supply a negative `bytes_per_sep' value.

@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


Άλλαξε στην έκδοση 3.8: The `sep' and `bytes_per_sep' parameters were added.

@end deffn

@geindex a2b_hex() (στη μονάδα binascii)
@geindex unhexlify() (στη μονάδα binascii)
@anchor{library/binascii binascii a2b_hex}@anchor{1fe}
@deffn {Συνάρτηση} binascii.a2b_hex (hexstr, *, ignorechars=b'@w{'})
@anchor{library/binascii binascii unhexlify}@anchor{1ff}
@deffnx {Συνάρτηση} binascii.unhexlify (hexstr, *, ignorechars=b'@w{'})

Return the binary data represented by the hexadecimal string `hexstr'.  This
function is the inverse of @ref{192b,,b2a_hex()}. `hexstr' must contain an even number
of hexadecimal digits (which can be upper or lower case), otherwise an
@ref{13ce,,Error} exception is raised.

`ignorechars' should be a @ref{436,,bytes-like object} containing characters
to ignore from the input.

Similar functionality (accepting only text string arguments, but more
liberal towards whitespace) is also accessible using the
@ref{434,,bytes.fromhex()} class method.


Άλλαξε στην έκδοση 3.15: Added the `ignorechars' parameter.

@end deffn

@geindex Error
@anchor{library/binascii binascii Error}@anchor{13ce}
@deffn {Εξαίρεση} binascii.Error

Exception raised on errors. These are usually programming errors.
@end deffn

@geindex Incomplete
@anchor{library/binascii binascii Incomplete}@anchor{3eff}
@deffn {Εξαίρεση} binascii.Incomplete

Exception raised on incomplete data. These are usually not programming errors,
but may be handled by reading a little more data and trying again.
@end deffn

@geindex BASE64_ALPHABET (στη μονάδα binascii)
@anchor{library/binascii binascii BASE64_ALPHABET}@anchor{3f00}
@deffn {Δεδομένα} binascii.BASE64_ALPHABET

The Base 64 alphabet according to 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}.


Added in version 3.15.

@end deffn

@geindex URLSAFE_BASE64_ALPHABET (στη μονάδα binascii)
@anchor{library/binascii binascii URLSAFE_BASE64_ALPHABET}@anchor{3f01}
@deffn {Δεδομένα} binascii.URLSAFE_BASE64_ALPHABET

The «URL and filename safe» Base 64 alphabet according to 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}.


Added in version 3.15.

@end deffn

@geindex UU_ALPHABET (στη μονάδα binascii)
@anchor{library/binascii binascii UU_ALPHABET}@anchor{3f02}
@deffn {Δεδομένα} binascii.UU_ALPHABET

The uuencoding alphabet.


Added in version 3.15.

@end deffn

@geindex CRYPT_ALPHABET (στη μονάδα binascii)
@anchor{library/binascii binascii CRYPT_ALPHABET}@anchor{3f03}
@deffn {Δεδομένα} binascii.CRYPT_ALPHABET

The Base 64 alphabet used in the @code{crypt(3)@footnote{https://manpages.debian.org/crypt(3)}} routine and in the GEDCOM format.


Added in version 3.15.

@end deffn

@geindex BINHEX_ALPHABET (στη μονάδα binascii)
@anchor{library/binascii binascii BINHEX_ALPHABET}@anchor{3f04}
@deffn {Δεδομένα} binascii.BINHEX_ALPHABET

The Base 64 alphabet used in BinHex 4 (HQX) within the classic Mac OS.


Added in version 3.15.

@end deffn

@geindex BASE85_ALPHABET (στη μονάδα binascii)
@anchor{library/binascii binascii BASE85_ALPHABET}@anchor{3f05}
@deffn {Δεδομένα} binascii.BASE85_ALPHABET

The Base85 alphabet.


Added in version 3.15.

@end deffn

@geindex ASCII85_ALPHABET (στη μονάδα binascii)
@anchor{library/binascii binascii ASCII85_ALPHABET}@anchor{3f06}
@deffn {Δεδομένα} binascii.ASCII85_ALPHABET

The Ascii85 alphabet.


Added in version 3.15.

@end deffn

@geindex Z85_ALPHABET (στη μονάδα binascii)
@anchor{library/binascii binascii Z85_ALPHABET}@anchor{3f07}
@deffn {Δεδομένα} binascii.Z85_ALPHABET

The Z85@footnote{https://rfc.zeromq.org/spec/32/} alphabet.


Added in version 3.15.

@end deffn

@geindex BASE32_ALPHABET (στη μονάδα binascii)
@anchor{library/binascii binascii BASE32_ALPHABET}@anchor{3f08}
@deffn {Δεδομένα} binascii.BASE32_ALPHABET

The Base 32 alphabet according to 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}.


Added in version 3.15.

@end deffn

@geindex BASE32HEX_ALPHABET (στη μονάδα binascii)
@anchor{library/binascii binascii BASE32HEX_ALPHABET}@anchor{3f09}
@deffn {Δεδομένα} binascii.BASE32HEX_ALPHABET

The «Extended Hex» Base 32 alphabet according to 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}.
Data encoded with this alphabet maintains its sort order during bitwise
comparisons.


Added in version 3.15.

@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{f,,base64}

Support for RFC compliant base64-style encoding in base 16, 32, 64,
and 85.

@item Module @ref{bf,,quopri}

Support for quoted-printable encoding used in MIME email messages.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node quopri — Encode and decode MIME quoted-printable data,,binascii — Convert between binary and ASCII,Internet Data Handling
@anchor{library/quopri doc}@anchor{3f0a}@anchor{library/quopri module-quopri}@anchor{bf}@anchor{library/quopri quopri-encode-and-decode-mime-quoted-printable-data}@anchor{3f0b}@anchor{library/quopri translation-repo}@anchor{3f0c}
@subsection @code{quopri} — Encode and decode MIME quoted-printable data


@geindex module; quopri

`Source code:' Lib/quopri.py@footnote{https://github.com/python/cpython/tree/main/Lib/quopri.py}

@geindex quoted-printable;encoding
@geindex MIME;quoted-printable encoding


__________________________________________________________________


This module performs quoted-printable transport encoding and decoding, as
defined in 
@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».
The quoted-printable encoding is designed for data where there are relatively
few nonprintable characters; the base64 encoding scheme available via the
@ref{f,,base64} module is more compact if there are many such characters, as when
sending a graphics file.

@geindex decode() (στη μονάδα quopri)
@anchor{library/quopri quopri decode}@anchor{2a95}
@deffn {Συνάρτηση} quopri.decode (input, output, header=False)

Decode the contents of the `input' file and write the resulting decoded binary
data to the `output' file. `input' and `output' must be @ref{156c,,binary file objects}.  If the optional argument `header' is present and true, underscore
will be decoded as space. This is used to decode «Q»-encoded headers as
described in 
@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() (στη μονάδα quopri)
@anchor{library/quopri quopri encode}@anchor{2a94}
@deffn {Συνάρτηση} quopri.encode (input, output, quotetabs, header=False)

Encode the contents of the `input' file and write the resulting quoted-printable
data to the `output' file. `input' and `output' must be
@ref{156c,,binary file objects}. `quotetabs', a
non-optional flag which controls whether to encode embedded spaces
and tabs; when true it encodes such embedded whitespace, and when
false it leaves them unencoded.
Note that spaces and tabs appearing at the end of lines are always encoded,
as per 
@geindex RFC; RFC 1521
RFC 1521@footnote{https://datatracker.ietf.org/doc/html/rfc1521.html}.  `header' is a flag which controls if spaces are encoded
as underscores as per 
@geindex RFC; RFC 1522
RFC 1522@footnote{https://datatracker.ietf.org/doc/html/rfc1522.html}.
@end deffn

@geindex decodestring() (στη μονάδα quopri)
@anchor{library/quopri quopri decodestring}@anchor{3f0d}
@deffn {Συνάρτηση} quopri.decodestring (s, header=False)

Like @ref{2a95,,decode()}, except that it accepts a source @ref{1c7,,bytes} and
returns the corresponding decoded @code{bytes}.
@end deffn

@geindex encodestring() (στη μονάδα quopri)
@anchor{library/quopri quopri encodestring}@anchor{3f0e}
@deffn {Συνάρτηση} quopri.encodestring (s, quotetabs=False, header=False)

Like @ref{2a94,,encode()}, except that it accepts a source @ref{1c7,,bytes} and
returns the corresponding encoded @code{bytes}. By default, it sends a
@code{False} value to `quotetabs' parameter of the @code{encode()} function.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{f,,base64}

Encode and decode MIME base64 data
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Structured Markup Processing Tools,Πρωτόκολλα Internet και Υποστήριξη,Internet Data Handling,The Python Standard Library
@anchor{library/markup doc}@anchor{3f0f}@anchor{library/markup markup}@anchor{3f10}@anchor{library/markup structured-markup-processing-tools}@anchor{3f11}@anchor{library/markup translation-repo}@anchor{3f12}
@section Structured Markup Processing Tools


Python supports a variety of modules to work with various forms of structured
data markup.  This includes modules to work with the Standard Generalized Markup
Language (SGML) and the Hypertext Markup Language (HTML), and several interfaces
for working with the Extensible Markup Language (XML).

@menu
* html — HyperText Markup Language support:: 
* html.parser — Simple HTML and XHTML parser: html parser — Simple HTML and XHTML parser. 
* html.entities — Definitions of HTML general entities: html entities — Definitions of HTML general entities. 
* XML Processing Modules:: 
* xml.etree.ElementTree — The ElementTree XML API: xml etree ElementTree — The ElementTree XML API. 
* xml.dom — The Document Object Model API: xml dom — The Document Object Model API. 
* xml.dom.minidom — Minimal DOM implementation: xml dom minidom — Minimal DOM implementation. 
* xml.dom.pulldom — Support for building partial DOM trees: xml dom pulldom — Support for building partial DOM trees. 
* xml.sax — Support for SAX2 parsers: xml sax — Support for SAX2 parsers. 
* xml.sax.handler — Βασικές κλάσεις για χειριστές SAX: xml sax handler — Βασικές κλάσεις για χειριστές SAX. 
* xml.sax.saxutils — SAX Utilities: xml sax saxutils — SAX Utilities. 
* xml.sax.xmlreader — Interface for XML parsers: xml sax xmlreader — Interface for XML parsers. 
* xml.parsers.expat — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat: xml parsers expat — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat. 

@end menu

@node html — HyperText Markup Language support,html parser — Simple HTML and XHTML parser,,Structured Markup Processing Tools
@anchor{library/html doc}@anchor{3f13}@anchor{library/html html-hypertext-markup-language-support}@anchor{3f14}@anchor{library/html module-html}@anchor{6e}
@subsection @code{html} — HyperText Markup Language support


@geindex module; html

`Source code:' Lib/html/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/html/__init__.py}


__________________________________________________________________


This module defines utilities to manipulate HTML.

@geindex escape() (στη μονάδα html)
@anchor{library/html html escape}@anchor{13b7}
@deffn {Συνάρτηση} html.escape (s, quote=True)

Convert the characters @code{&}, @code{<} and @code{>} in string `s' to HTML-safe
sequences.  Use this if you need to display text that might contain such
characters in HTML.  If the optional flag `quote' is true (the default), the
characters (@code{"}) and (@code{'}) are also translated; this helps for inclusion
in an HTML attribute value delimited by quotes, as in @code{<a href="...">}.
If `quote' is set to false, the characters (@code{"}) and (@code{'}) are not
translated.


Added in version 3.2.

@end deffn

@geindex unescape() (στη μονάδα html)
@anchor{library/html html unescape}@anchor{d21}
@deffn {Συνάρτηση} html.unescape (s)

Convert all named and numeric character references (e.g. @code{&gt;},
@code{&#62;}, @code{&#x3e;}) in the string `s' to the corresponding Unicode
characters.  This function uses the rules defined by the HTML 5 standard
for both valid and invalid character references, and the @ref{147e,,list of HTML 5 named character references}.


Added in version 3.4.

@end deffn


__________________________________________________________________


Submodules in the @code{html} package are:


@itemize *

@item 
@ref{70,,html.parser} – HTML/XHTML parser with lenient parsing mode

@item 
@ref{6f,,html.entities} – HTML entity definitions
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node html parser — Simple HTML and XHTML parser,html entities — Definitions of HTML general entities,html — HyperText Markup Language support,Structured Markup Processing Tools
@anchor{library/html parser doc}@anchor{3f15}@anchor{library/html parser html-parser-simple-html-and-xhtml-parser}@anchor{3f16}@anchor{library/html parser module-html parser}@anchor{70}@anchor{library/html parser translation-repo}@anchor{3f17}
@subsection @code{html.parser} — Simple HTML and XHTML parser


@geindex module; html.parser

`Source code:' Lib/html/parser.py@footnote{https://github.com/python/cpython/tree/main/Lib/html/parser.py}

@geindex HTML
@geindex XHTML


__________________________________________________________________


This module defines a class @ref{c4d,,HTMLParser} which serves as the basis for
parsing text files formatted in HTML (HyperText Mark-up Language) and XHTML.

@geindex HTMLParser (κλάση σε html.parser)
@anchor{library/html parser html parser HTMLParser}@anchor{c4d}
@deffn {Κλάση} html.parser.HTMLParser (*, convert_charrefs=True, scripting=False)

Create a parser instance able to parse invalid markup.

If `convert_charrefs' is true (the default), all character
references (except the ones in elements like @code{script} and @code{style}) are
automatically converted to the corresponding Unicode characters.

If `scripting' is false (the default), the content of the @code{noscript}
element is parsed normally; if it’s true, it’s returned as is without
being parsed.

An @code{HTMLParser} instance is fed HTML data and calls handler methods
when start tags, end tags, text, comments, and other markup elements are
encountered.  The user should subclass @code{HTMLParser} and override its
methods to implement the desired behavior.

This parser does not check that end tags match start tags or call the end-tag
handler for elements which are closed implicitly by closing an outer element.


Άλλαξε στην έκδοση 3.4: `convert_charrefs' keyword argument added.



Άλλαξε στην έκδοση 3.5: The default value for argument `convert_charrefs' is now @code{True}.



Άλλαξε στην έκδοση 3.14.1: Added the `scripting' parameter.

@end deffn

@menu
* Example HTML Parser Application:: 
* HTMLParser Methods:: 
* Examples: Examples<21>. 

@end menu

@node Example HTML Parser Application,HTMLParser Methods,,html parser — Simple HTML and XHTML parser
@anchor{library/html parser example-html-parser-application}@anchor{3f18}
@subsubsection Example HTML Parser Application


As a basic example, below is a simple HTML parser that uses the
@ref{c4d,,HTMLParser} class to print out start tags, end tags, and data
as they are encountered:

@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

The output will then be:

@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 HTMLParser Methods,Examples<21>,Example HTML Parser Application,html parser — Simple HTML and XHTML parser
@anchor{library/html parser htmlparser-methods}@anchor{3f19}
@subsubsection @code{HTMLParser} Methods


@ref{c4d,,HTMLParser} instances have the following methods:

@geindex feed() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser feed}@anchor{3f1a}
@deffn {Μέθοδος} HTMLParser.feed (data)

Feed some text to the parser.  It is processed insofar as it consists of
complete elements; incomplete data is buffered until more data is fed or
@ref{1a44,,close()} is called.  `data' must be @ref{1df,,str}.
@end deffn

@geindex close() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser close}@anchor{1a44}
@deffn {Μέθοδος} HTMLParser.close ()

Force processing of all buffered data as if it were followed by an end-of-file
mark.  This method may be redefined by a derived class to define additional
processing at the end of the input, but the redefined version should always call
the @ref{c4d,,HTMLParser} base class method @code{close()}.
@end deffn

@geindex reset() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser reset}@anchor{3f1b}
@deffn {Μέθοδος} HTMLParser.reset ()

Reset the instance.  Loses all unprocessed data.  This is called implicitly at
instantiation time.
@end deffn

@geindex getpos() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser getpos}@anchor{3f1c}
@deffn {Μέθοδος} HTMLParser.getpos ()

Return current line number and offset.
@end deffn

@geindex get_starttag_text() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser get_starttag_text}@anchor{3f1d}
@deffn {Μέθοδος} 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

The following methods are called when data or markup elements are encountered
and they are meant to be overridden in a subclass.  The base class
implementations do nothing (except for @ref{3f1e,,handle_startendtag()}):

@geindex handle_starttag() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_starttag}@anchor{3f1f}
@deffn {Μέθοδος} HTMLParser.handle_starttag (tag, attrs)

This method is called to handle the start tag of an element (e.g. @code{<div id="main">}).

The `tag' argument is the name of the tag converted to lower case. The `attrs'
argument is a list of @code{(name, value)} pairs containing the attributes found
inside the tag’s @code{<>} brackets.  The `name' will be translated to lower case,
and quotes in the `value' have been removed, and character and entity references
have been replaced.  For empty attributes, `value' is @code{None}.

For instance, for the tag @code{<A HREF="https://www.cwi.nl/">}, this method
would be called as @code{handle_starttag('a', [('href', 'https://www.cwi.nl/')])}.

All entity references from @ref{6f,,html.entities} are replaced in the attribute
values.
@end deffn

@geindex handle_endtag() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_endtag}@anchor{3f20}
@deffn {Μέθοδος} HTMLParser.handle_endtag (tag)

This method is called to handle the end tag of an element (e.g. @code{</div>}).

The `tag' argument is the name of the tag converted to lower case.
@end deffn

@geindex handle_startendtag() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_startendtag}@anchor{3f1e}
@deffn {Μέθοδος} HTMLParser.handle_startendtag (tag, attrs)

Similar to @ref{3f1f,,handle_starttag()}, but called when the parser encounters an
XHTML-style empty tag (@code{<img ... />}).  This method may be overridden by
subclasses which require this particular lexical information; the default
implementation simply calls @code{handle_starttag()} and @ref{3f20,,handle_endtag()}.
@end deffn

@geindex handle_data() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_data}@anchor{3f21}
@deffn {Μέθοδος} HTMLParser.handle_data (data)

This method is called to process arbitrary data (e.g. text nodes and the
content of elements like @code{script} and @code{style}).
@end deffn

@geindex handle_entityref() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_entityref}@anchor{3f22}
@deffn {Μέθοδος} HTMLParser.handle_entityref (name)

This method is called to process a named character reference of the form
@code{&name;} (e.g. @code{&gt;}), where `name' is a general entity reference
(e.g. @code{'gt'}).
This method is only called if `convert_charrefs' is false.
@end deffn

@geindex handle_charref() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_charref}@anchor{3f23}
@deffn {Μέθοδος} 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 only called if `convert_charrefs' is false.
@end deffn

@geindex handle_comment() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_comment}@anchor{3f24}
@deffn {Μέθοδος} HTMLParser.handle_comment (data)

This method is called when a comment is encountered (e.g. @code{<!--comment-->}).

For example, the comment @code{<!-- comment -->} will cause this method to be
called with the argument @code{' comment '}.

The content of Internet Explorer conditional comments (condcoms) will also be
sent to this method, so, for @code{<!--[if IE 9]>IE9-specific content<![endif]-->},
this method will receive @code{'[if IE 9]>IE9-specific content<![endif]'}.
@end deffn

@geindex handle_decl() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_decl}@anchor{3f25}
@deffn {Μέθοδος} HTMLParser.handle_decl (decl)

This method is called to handle an HTML doctype declaration (e.g.
@code{<!DOCTYPE html>}).

The `decl' parameter will be the entire contents of the declaration inside
the @code{<!...>} markup (e.g. @code{'DOCTYPE html'}).
@end deffn

@geindex handle_pi() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_pi}@anchor{3f26}
@deffn {Μέθοδος} HTMLParser.handle_pi (data)

Method called when a processing instruction is encountered.  The `data'
parameter will contain the entire processing instruction. For example, for the
processing instruction @code{<?proc color='red'>}, this method would be called as
@code{handle_pi("proc color='red'")}.  It is intended to be overridden by a derived
class; the base class implementation does nothing.

@cartouche
@quotation Σημείωση 
The @ref{c4d,,HTMLParser} class uses the SGML syntactic rules for processing
instructions.  An XHTML processing instruction using the trailing @code{'?'} will
cause the @code{'?'} to be included in `data'.
@end quotation
@end cartouche
@end deffn

@geindex unknown_decl() (μέθοδος της html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser unknown_decl}@anchor{3f27}
@deffn {Μέθοδος} HTMLParser.unknown_decl (data)

This method is called when an unrecognized declaration is read by the parser.

The `data' parameter will be the entire contents of the declaration inside
the @code{<![...]>} markup.  It is sometimes useful to be overridden by a
derived class.  The base class implementation does nothing.
@end deffn

@node Examples<21>,,HTMLParser Methods,html parser — Simple HTML and XHTML parser
@anchor{library/html parser examples}@anchor{3f28}@anchor{library/html parser htmlparser-examples}@anchor{3f29}
@subsubsection Examples


The following class implements a parser that will be used to illustrate more
examples:

@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

Parsing a 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

Parsing an element with a few attributes and a title:

@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

The content of elements like @code{script} and @code{style} is returned as is,
without further parsing:

@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! &#9786;</strong>");</script>')
Start tag: script
     attr: ('type', 'text/javascript')
Data     : alert("<strong>hello! &#9786;</strong>");
End tag  : script
@end example

Attribute names are converted to lowercase, quotes from attribute values removed,
and @code{None} is returned as `value' for empty attributes (such as @code{checked}):

@example
>>> parser.feed("<input TYPE='checkbox' checked required='@w{'} disabled=disabled>")
Start tag: input
     attr: ('type', 'checkbox')
     attr: ('checked', None)
     attr: ('required', '@w{'})
     attr: ('disabled', 'disabled')
@end example

Parsing comments:

@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

Parsing named and numeric character references and converting them to the
correct char (note: these 3 references are all equivalent to @code{'>'}):

@example
>>> parser = MyHTMLParser()
>>> parser.feed('&gt;&#62;&#x3E;')
Data     : >>>

>>> parser = MyHTMLParser(convert_charrefs=False)
>>> parser.feed('&gt;&#62;&#x3E;')
Named ent: >
Num ent  : >
Num ent  : >
@end example

Feeding incomplete chunks to @ref{3f1a,,feed()} works, but
@ref{3f21,,handle_data()} might be called more than once
if `convert_charrefs' is false:

@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

Parsing invalid HTML (e.g. unquoted attributes) also works:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node html entities — Definitions of HTML general entities,XML Processing Modules,html parser — Simple HTML and XHTML parser,Structured Markup Processing Tools
@anchor{library/html entities doc}@anchor{3f2a}@anchor{library/html entities html-entities-definitions-of-html-general-entities}@anchor{3f2b}@anchor{library/html entities module-html entities}@anchor{6f}@anchor{library/html entities translation-repo}@anchor{3f2c}
@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/main/Lib/html/entities.py}


__________________________________________________________________


This module defines four dictionaries, @ref{147e,,html5},
@ref{3f2d,,name2codepoint}, @ref{3f2e,,codepoint2name}, and @ref{3f2f,,entitydefs}.

@geindex html5 (στη μονάδα html.entities)
@anchor{library/html entities html entities html5}@anchor{147e}
@deffn {Δεδομένα} html.entities.html5

A dictionary that maps HTML5 named character references @footnote{
See @indicateurl{https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references}
} to the
equivalent Unicode character(s), e.g. @code{html5['gt;'] == '>'}.
Note that the trailing semicolon is included in the name (e.g. @code{'gt;'}),
however some of the names are accepted by the standard even without the
semicolon: in this case the name is present with and without the @code{';'}.
See also @ref{d21,,html.unescape()}.


Added in version 3.3.

@end deffn

@geindex entitydefs (στη μονάδα html.entities)
@anchor{library/html entities html entities entitydefs}@anchor{3f2f}
@deffn {Δεδομένα} html.entities.entitydefs

A dictionary mapping XHTML 1.0 entity definitions to their replacement text in
ISO Latin-1.
@end deffn

@geindex name2codepoint (στη μονάδα html.entities)
@anchor{library/html entities html entities name2codepoint}@anchor{3f2d}
@deffn {Δεδομένα} html.entities.name2codepoint

A dictionary that maps HTML4 entity names to the Unicode code points.
@end deffn

@geindex codepoint2name (στη μονάδα html.entities)
@anchor{library/html entities html entities codepoint2name}@anchor{3f2e}
@deffn {Δεδομένα} html.entities.codepoint2name

A dictionary that maps Unicode code points to HTML4 entity names.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node XML Processing Modules,xml etree ElementTree — The ElementTree XML API,html entities — Definitions of HTML general entities,Structured Markup Processing Tools
@anchor{library/xml doc}@anchor{3f30}@anchor{library/xml module-xml}@anchor{129}@anchor{library/xml translation-repo}@anchor{3f31}@anchor{library/xml xml}@anchor{3f32}@anchor{library/xml xml-processing-modules}@anchor{3f33}
@subsection XML Processing Modules


@geindex module; xml

`Source code:' Lib/xml/@footnote{https://github.com/python/cpython/tree/main/Lib/xml/}


__________________________________________________________________


Python’s interfaces for processing XML are grouped in the @code{xml} package.

@cartouche
@quotation Σημείωση 
If you need to parse untrusted or unauthenticated data, see
@ref{3f34,,XML security}.
@end quotation
@end cartouche

It is important to note that modules in the @code{xml} package require that
there be at least one SAX-compliant XML parser available. The Expat parser is
included with Python, so the @ref{12f,,xml.parsers.expat} module will always be
available.

The documentation for the @ref{12a,,xml.dom} and @ref{132,,xml.sax} packages are the
definition of the Python bindings for the DOM and SAX interfaces.

The XML handling submodules are:


@itemize *

@item 
@ref{12e,,xml.etree.ElementTree}: the ElementTree API, a simple and lightweight
XML processor
@end itemize



@itemize *

@item 
@ref{12a,,xml.dom}: the DOM API definition

@item 
@ref{12b,,xml.dom.minidom}: a minimal DOM implementation

@item 
@ref{12c,,xml.dom.pulldom}: support for building partial DOM trees
@end itemize



@itemize *

@item 
@ref{132,,xml.sax}: SAX2 base classes and convenience functions

@item 
@ref{12f,,xml.parsers.expat}: the Expat parser binding
@end itemize

This module also defines utility functions.

@geindex is_valid_name() (στη μονάδα xml)
@anchor{library/xml xml is_valid_name}@anchor{2b3}
@deffn {Συνάρτηση} xml.is_valid_name (name)

Return @code{True} if the string is a valid element or attribute name,
@code{False} otherwise.

Almost all characters are permitted in names, except control characters and
those which either are or reasonably could be used as delimiters.
Characters like «:», «-», «.», «_», and «·» are permitted, but «<», «/»,
«!», «?», and «=» are forbidden.
The name cannot start with a digit or a character like «-», «.», and «·».


Added in version 3.15.

@end deffn

@geindex is_valid_text() (στη μονάδα xml)
@anchor{library/xml xml is_valid_text}@anchor{2b4}
@deffn {Συνάρτηση} xml.is_valid_text (data)

Return @code{True} if the string is a sequence of legal XML 1.0 characters,
@code{False} otherwise.

Almost all characters are permitted in XML 1.0 documents, except C0 control
characters (excluding TAB, CR and LF), surrogate characters and special
Unicode characters U+FFFE and U+FFFF.


Added in version 3.15.

@end deffn
@anchor{library/xml xml-security}@anchor{3f34}
@menu
* XML security:: 

@end menu

@node XML security,,,XML Processing Modules
@anchor{library/xml id1}@anchor{3f35}@anchor{library/xml xml-vulnerabilities}@anchor{3f36}
@subsubsection XML security


An attacker can abuse XML features to carry out denial of service attacks,
access local files, generate network connections to other machines, or
circumvent firewalls when attacker-controlled XML is being parsed,
in Python or elsewhere.

The built-in XML parsers of Python rely on the library libexpat@footnote{https://github.com/libexpat/libexpat}, commonly
called Expat, for parsing XML.

By default, Expat itself does not access local files or create network
connections.

Expat versions lower than 2.7.2 may be vulnerable to the «billion laughs»,
«quadratic blowup» and «large tokens» vulnerabilities, or to disproportional
use of dynamic memory.
Python bundles a copy of Expat, and whether Python uses the bundled or a
system-wide Expat, depends on how the Python interpreter
@ref{1d2b,,has been configured} in your environment.
Python may be vulnerable if it uses such older versions of Expat.
Check @code{pyexpat.EXPAT_VERSION}.

@ref{136,,xmlrpc} is `vulnerable' to the «decompression bomb» attack.


@table @asis

@item billion laughs / exponential entity expansion

The Billion Laughs@footnote{https://en.wikipedia.org/wiki/Billion_laughs} attack – also known as exponential entity expansion –
uses multiple levels of nested entities. Each entity refers to another entity
several times, and the final entity definition contains a small string.
The exponential expansion results in several gigabytes of text and
consumes lots of memory and CPU time.

@item quadratic blowup entity expansion

A quadratic blowup attack is similar to a Billion Laughs@footnote{https://en.wikipedia.org/wiki/Billion_laughs} attack; it abuses
entity expansion, too. Instead of nested entities it repeats one large entity
with a couple of thousand chars over and over again. The attack isn’t as
efficient as the exponential case but it avoids triggering parser countermeasures
that forbid deeply nested entities.

@item decompression bomb

Decompression bombs (aka ZIP bomb@footnote{https://en.wikipedia.org/wiki/Zip_bomb}) apply to all XML libraries
that can parse compressed XML streams such as gzipped HTTP streams or
LZMA-compressed
files. For an attacker it can reduce the amount of transmitted data by three
magnitudes or more.

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xml etree ElementTree — The ElementTree XML API,xml dom — The Document Object Model API,XML Processing Modules,Structured Markup Processing Tools
@anchor{library/xml etree elementtree doc}@anchor{3f37}@anchor{library/xml etree elementtree module-xml etree ElementTree}@anchor{12e}@anchor{library/xml etree elementtree translation-repo}@anchor{3f38}@anchor{library/xml etree elementtree xml-etree-elementtree-the-elementtree-xml-api}@anchor{3f39}
@subsection @code{xml.etree.ElementTree} — The ElementTree XML API


@geindex module; xml.etree.ElementTree

`Source code:' Lib/xml/etree/ElementTree.py@footnote{https://github.com/python/cpython/tree/main/Lib/xml/etree/ElementTree.py}


__________________________________________________________________


The @code{xml.etree.ElementTree} module implements a simple and efficient API
for parsing and creating XML data.


Άλλαξε στην έκδοση 3.3: This module will use a fast implementation whenever available.



Αποσύρθηκε στην έκδοση 3.3: The @code{xml.etree.cElementTree} module is deprecated.


@cartouche
@quotation Σημείωση 
If you need to parse untrusted or unauthenticated data, see
@ref{3f34,,XML security}.
@end quotation
@end cartouche

@menu
* Tutorial: Tutorial<3>. 
* XPath support:: 
* Reference: Reference<5>. 
* XInclude support:: 
* Reference: Reference<6>. 

@end menu

@node Tutorial<3>,XPath support,,xml etree ElementTree — The ElementTree XML API
@anchor{library/xml etree elementtree tutorial}@anchor{3f3a}
@subsubsection Tutorial


This is a short tutorial for using @code{xml.etree.ElementTree} (@code{ET} in
short).  The goal is to demonstrate some of the building blocks and basic
concepts of the module.

@menu
* XML tree and elements:: 
* Parsing XML:: 
* Pull API for non-blocking parsing:: 
* Finding interesting elements:: 
* Modifying an XML File:: 
* Building XML documents:: 
* Parsing XML with Namespaces:: 

@end menu

@node XML tree and elements,Parsing XML,,Tutorial<3>
@anchor{library/xml etree elementtree xml-tree-and-elements}@anchor{3f3b}
@subsubsection XML tree and elements


XML is an inherently hierarchical data format, and the most natural way to
represent it is with a tree.  @code{ET} has two classes for this purpose -
@ref{d19,,ElementTree} represents the whole XML document as a tree, and
@ref{343,,Element} represents a single node in this tree.  Interactions with
the whole document (reading and writing to/from files) are usually done
on the @code{ElementTree} level.  Interactions with a single XML element
and its sub-elements are done on the @code{Element} level.

@node Parsing XML,Pull API for non-blocking parsing,XML tree and elements,Tutorial<3>
@anchor{library/xml etree elementtree elementtree-parsing-xml}@anchor{3f3c}@anchor{library/xml etree elementtree parsing-xml}@anchor{3f3d}
@subsubsection Parsing 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

We can import this data by reading from a file:

@example
import xml.etree.ElementTree as ET
tree = ET.parse('country_data.xml')
root = tree.getroot()
@end example

Or directly from a string:

@example
root = ET.fromstring(country_data_as_string)
@end example

@ref{3f3e,,fromstring()} parses XML from a string directly into an @ref{343,,Element},
which is the root element of the parsed tree.  Other parsing functions may
create an @ref{d19,,ElementTree}.  Check the documentation to be sure.

As an @ref{343,,Element}, @code{root} has a tag and a dictionary of attributes:

@example
>>> root.tag
'data'
>>> root.attrib
@{@}
@end example

It also has children nodes over which we can iterate:

@example
>>> for child in root:
...     print(child.tag, child.attrib)
...
country @{'name': 'Liechtenstein'@}
country @{'name': 'Singapore'@}
country @{'name': 'Panama'@}
@end example

Children are nested, and we can access specific child nodes by index:

@example
>>> root[0][1].text
'2008'
@end example

@cartouche
@quotation Σημείωση 
Not all elements of the XML input will end up as elements of the
parsed tree. Currently, this module skips over any XML comments,
processing instructions, and document type declarations in the
input. Nevertheless, trees built using this module’s API rather
than parsing from XML text can have comments and processing
instructions in them; they will be included when generating XML
output. A document type declaration may be accessed by passing a
custom @ref{e19,,TreeBuilder} instance to the @ref{e18,,XMLParser}
constructor.
@end quotation
@end cartouche

@node Pull API for non-blocking parsing,Finding interesting elements,Parsing XML,Tutorial<3>
@anchor{library/xml etree elementtree elementtree-pull-parsing}@anchor{139d}@anchor{library/xml etree elementtree pull-api-for-non-blocking-parsing}@anchor{3f3f}
@subsubsection Pull API for non-blocking parsing


Most parsing functions provided by this module require the whole document
to be read at once before returning any result.  It is possible to use an
@ref{e18,,XMLParser} and feed data into it incrementally, but it is a push API that
calls methods on a callback target, which is too low-level and inconvenient for
most needs.  Sometimes what the user really wants is to be able to parse XML
incrementally, without blocking operations, while enjoying the convenience of
fully constructed @ref{343,,Element} objects.

The most powerful tool for doing this is @ref{139c,,XMLPullParser}.  It does not
require a blocking read to obtain the XML data, and is instead fed with data
incrementally with @ref{3f40,,XMLPullParser.feed()} calls.  To get the parsed XML
elements, call @ref{3f41,,XMLPullParser.read_events()}.  Here is an example:

@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

The obvious use case is applications that operate in a non-blocking fashion
where the XML data is being received from a socket or read incrementally from
some storage device.  In such cases, blocking reads are unacceptable.

Because it’s so flexible, @ref{139c,,XMLPullParser} can be inconvenient to use for
simpler use-cases.  If you don’t mind your application blocking on reading XML
data but would still like to have incremental parsing capabilities, take a look
at @ref{3eb,,iterparse()}.  It can be useful when you’re reading a large XML document
and don’t want to hold it wholly in memory.

Where `immediate' feedback through events is wanted, calling method
@ref{778,,XMLPullParser.flush()} can help reduce delay;
please make sure to study the related security notes.

@node Finding interesting elements,Modifying an XML File,Pull API for non-blocking parsing,Tutorial<3>
@anchor{library/xml etree elementtree finding-interesting-elements}@anchor{3f42}
@subsubsection Finding interesting elements


@ref{343,,Element} has some useful methods that help iterate recursively over all
the sub-tree below it (its children, their children, and so on).  For example,
@ref{16f3,,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{1aa2,,Element.findall()} finds only elements with a tag which are direct
children of the current element.  @ref{1aa1,,Element.find()} finds the `first' child
with a particular tag, and @ref{3f43,,Element.text} accesses the element’s text
content.  @ref{3f44,,Element.get()} accesses the element’s attributes:

@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

More sophisticated specification of which elements to look for is possible by
using @ref{f6b,,XPath}.

@node Modifying an XML File,Building XML documents,Finding interesting elements,Tutorial<3>
@anchor{library/xml etree elementtree modifying-an-xml-file}@anchor{3f45}
@subsubsection Modifying an XML File


@ref{d19,,ElementTree} provides a simple way to build XML documents and write them to files.
The @ref{e5b,,ElementTree.write()} method serves this purpose.

Once created, an @ref{343,,Element} object may be manipulated by directly changing
its fields (such as @ref{3f43,,Element.text}), adding and modifying attributes
(@ref{3f46,,Element.set()} method), as well as adding new children (for example
with @ref{3f47,,Element.append()}).

Let’s say we want to add one to each country’s rank, and add an @code{updated}
attribute to the rank element:

@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

Our XML now looks like this:

@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

We can remove elements using @ref{1981,,Element.remove()}.  Let’s say we want to
remove all countries with a rank higher than 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

Note that concurrent modification while iterating can lead to problems,
just like when iterating and modifying Python lists or dicts.
Therefore, the example first collects all matching elements with
@code{root.findall()}, and only then iterates over the list of matches.

Our XML now looks like this:

@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 Building XML documents,Parsing XML with Namespaces,Modifying an XML File,Tutorial<3>
@anchor{library/xml etree elementtree building-xml-documents}@anchor{3f48}
@subsubsection Building XML documents


The @ref{1930,,SubElement()} function also provides a convenient way to create new
sub-elements for a given element:

@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 Parsing XML with Namespaces,,Building XML documents,Tutorial<3>
@anchor{library/xml etree elementtree parsing-xml-with-namespaces}@anchor{3f49}
@subsubsection Parsing XML with Namespaces


If the XML input has namespaces@footnote{https://en.wikipedia.org/wiki/XML_namespace}, tags and attributes
with prefixes in the form @code{prefix:sometag} get expanded to
@code{@{uri@}sometag} where the `prefix' is replaced by the full `URI'.
Also, if there is a default namespace@footnote{https://www.w3.org/TR/xml-names/#defaulting},
that full URI gets prepended to all of the non-prefixed tags.

Here is an XML example that incorporates two namespaces, one with the
prefix «fictional» and the other serving as the default namespace:

@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

One way to search and explore this XML example is to manually add the
URI to every tag or attribute in the xpath of a
@ref{1aa1,,find()} or @ref{1aa2,,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

A better way to search the namespaced XML example is to create a
dictionary with your own prefixes and use those in the search functions:

@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

These two approaches both output:

@example
John Cleese
 |--> Lancelot
 |--> Archie Leach
Eric Idle
 |--> Sir Robin
 |--> Gunther
 |--> Commander Clement
@end example

@node XPath support,Reference<5>,Tutorial<3>,xml etree ElementTree — The ElementTree XML API
@anchor{library/xml etree elementtree elementtree-xpath}@anchor{f6b}@anchor{library/xml etree elementtree xpath-support}@anchor{3f4a}
@subsubsection XPath support


This module provides limited support for
XPath expressions@footnote{https://www.w3.org/TR/xpath} for locating elements in a
tree.  The goal is to support a small subset of the abbreviated syntax; a full
XPath engine is outside the scope of the module.

@menu
* Example: Example<8>. 
* Supported XPath syntax:: 

@end menu

@node Example<8>,Supported XPath syntax,,XPath support
@anchor{library/xml etree elementtree example}@anchor{3f4b}
@subsubsection Example


Here’s an example that demonstrates some of the XPath capabilities of the
module.  We’ll be using the @code{countrydata} XML document from the
@ref{3f3c,,Parsing XML} section:

@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

For XML with namespaces, use the usual qualified @code{@{namespace@}tag} notation:

@example
# All dublin-core "title" tags in the document
root.findall(".//@{http://purl.org/dc/elements/1.1/@}title")
@end example

@node Supported XPath syntax,,Example<8>,XPath support
@anchor{library/xml etree elementtree supported-xpath-syntax}@anchor{3f4c}
@subsubsection Supported XPath syntax



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Syntax

@tab

Meaning

@item

@code{tag}

@tab

Selects all child elements with the given tag.
For example, @code{spam} selects all child elements
named @code{spam}, and @code{spam/egg} selects all
grandchildren named @code{egg} in all children named
@code{spam}.  @code{@{namespace@}*} selects all tags in the
given namespace, @code{@{*@}spam} selects tags named
@code{spam} in any (or no) namespace, and @code{@{@}*}
only selects tags that are not in a namespace.


Άλλαξε στην έκδοση 3.8: Support for star-wildcards was added.


@item

@code{*}

@tab

Selects all child elements, including comments and
processing instructions.  For example, @code{*/egg}
selects all grandchildren named @code{egg}.

@item

@code{.}

@tab

Selects the current node.  This is mostly useful
at the beginning of the path, to indicate that it’s
a relative path.

@item

@code{//}

@tab

Selects all subelements, on all levels beneath the
current  element.  For example, @code{.//egg} selects
all @code{egg} elements in the entire tree.

@item

@code{..}

@tab

Selects the parent element.  Returns @code{None} if the
path attempts to reach the ancestors of the start
element (the element @code{find} was called on).

@item

@code{[@@attrib]}

@tab

Selects all elements that have the given attribute.

@item

@code{[@@attrib='value']}

@tab

Selects all elements for which the given attribute
has the given value.  The value cannot contain
quotes.

@item

@code{[@@attrib!='value']}

@tab

Selects all elements for which the given attribute
does not have the given value. The value cannot
contain quotes.


Added in version 3.10.


@item

@code{[tag]}

@tab

Selects all elements that have a child named
@code{tag}.  Only immediate children are supported.

@item

@code{[.='text']}

@tab

Selects all elements whose complete text content,
including descendants, equals the given @code{text}.


Added in version 3.7.


@item

@code{[.!='text']}

@tab

Selects all elements whose complete text content,
including descendants, does not equal the given
@code{text}.


Added in version 3.10.


@item

@code{[tag='text']}

@tab

Selects all elements that have a child named
@code{tag} whose complete text content, including
descendants, equals the given @code{text}.

@item

@code{[tag!='text']}

@tab

Selects all elements that have a child named
@code{tag} whose complete text content, including
descendants, does not equal the given @code{text}.


Added in version 3.10.


@item

@code{[position]}

@tab

Selects all elements that are located at the given
position.  The position can be either an integer
(1 is the first position), the expression @code{last()}
(for the last position), or a position relative to
the last position (e.g. @code{last()-1}).

@end multitable


Predicates (expressions within square brackets) must be preceded by a tag
name, an asterisk, or another predicate.  @code{position} predicates must be
preceded by a tag name.

@node Reference<5>,XInclude support,XPath support,xml etree ElementTree — The ElementTree XML API
@anchor{library/xml etree elementtree reference}@anchor{3f4d}
@subsubsection Reference


@menu
* Functions: Functions<7>. 

@end menu

@node Functions<7>,,,Reference<5>
@anchor{library/xml etree elementtree elementtree-functions}@anchor{3f4e}@anchor{library/xml etree elementtree functions}@anchor{3f4f}
@subsubsection Functions


@geindex canonicalize() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree canonicalize}@anchor{e17}
@deffn {Συνάρτηση} xml.etree.ElementTree.canonicalize (xml_data=None, *, out=None, from_file=None, **options)

C14N 2.0@footnote{https://www.w3.org/TR/xml-c14n2/} transformation function.

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.

This function takes an XML data string (`xml_data') or a file path or
file-like object (`from_file') as input, converts it to the canonical
form, and writes it out using the `out' file(-like) object, if provided,
or returns it as a text string if not.  The output file receives text,
not bytes.  It should therefore be opened in text mode with @code{utf-8}
encoding.

Typical uses:

@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

The configuration `options' are as follows:


@itemize -

@item 
`with_comments': set to true to include comments (default: false)

@item 

@table @asis

@item `strip_text': set to true to strip whitespace before and after text content

(default: false)
@end table

@item 

@table @asis

@item `rewrite_prefixes': set to true to replace namespace prefixes by «n@{number@}»

(default: false)
@end table

@item 

@table @asis

@item `qname_aware_tags': a set of qname aware tag names in which prefixes

should be replaced in text content (default: empty)
@end table

@item 

@table @asis

@item `qname_aware_attrs': a set of qname aware attribute names in which prefixes

should be replaced in text content (default: empty)
@end table

@item 
`exclude_attrs': a set of attribute names that should not be serialised

@item 
`exclude_tags': a set of tag names that should not be serialised
@end itemize

In the option list above, «a set» refers to any collection or iterable of
strings, no ordering is expected.


Added in version 3.8.

@end deffn

@geindex Comment() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree Comment}@anchor{3f50}
@deffn {Συνάρτηση} xml.etree.ElementTree.Comment (text=None)

Comment element factory.  This factory function creates a special element
that will be serialized as an XML comment by the standard serializer.  The
comment string can be either a bytestring or a Unicode string.  `text' is a
string containing the comment string.  Returns an element instance
representing a comment.

Note that @ref{e18,,XMLParser} skips over comments in the input
instead of creating comment objects for them. An @ref{d19,,ElementTree} will
only contain comment nodes if they have been inserted into to
the tree using one of the @ref{343,,Element} methods.
@end deffn

@geindex dump() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree dump}@anchor{3f51}
@deffn {Συνάρτηση} xml.etree.ElementTree.dump (elem)

Writes an element tree or element structure to sys.stdout.  This function
should be used for debugging only.

The exact output format is implementation dependent.  In this version, it’s
written as an ordinary XML file.

`elem' is an element tree or an individual element.


Άλλαξε στην έκδοση 3.8: The @code{dump()} function now preserves the attribute order specified
by the user.

@end deffn

@geindex fromstring() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree fromstring}@anchor{3f3e}
@deffn {Συνάρτηση} xml.etree.ElementTree.fromstring (text, parser=None)

Parses an XML section from a string constant.  Same as @ref{3f52,,XML()}.  `text'
is a string containing XML data.  `parser' is an optional parser instance.
If not given, the standard @ref{e18,,XMLParser} parser is used.
Returns an @ref{343,,Element} instance.
@end deffn

@geindex fromstringlist() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree fromstringlist}@anchor{157a}
@deffn {Συνάρτηση} xml.etree.ElementTree.fromstringlist (sequence, parser=None)

Parses an XML document from a sequence of string fragments.  `sequence' is a
list or other sequence containing XML data fragments.  `parser' is an
optional parser instance.  If not given, the standard @ref{e18,,XMLParser}
parser is used.  Returns an @ref{343,,Element} instance.


Added in version 3.2.

@end deffn

@geindex indent() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree indent}@anchor{3f53}
@deffn {Συνάρτηση} xml.etree.ElementTree.indent (tree, space='  ', level=0)

Appends whitespace to the subtree to indent the tree visually.
This can be used to generate pretty-printed XML output.
`tree' can be an Element or ElementTree.  `space' is the whitespace
string that will be inserted for each indentation level, two space
characters by default.  For indenting partial subtrees inside of an
already indented tree, pass the initial indentation level as `level'.


Added in version 3.9.

@end deffn

@geindex iselement() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree iselement}@anchor{3f54}
@deffn {Συνάρτηση} xml.etree.ElementTree.iselement (element)

Check if an object appears to be a valid element object.  `element' is an
element instance.  Return @code{True} if this is an element object.
@end deffn

@geindex iterparse() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree iterparse}@anchor{3eb}
@deffn {Συνάρτηση} 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{156c,,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{e18,,XMLParser} parser is used.  `parser' must be a subclass of
@code{XMLParser} and can only use the default @ref{e19,,TreeBuilder} as a
target. Returns an @ref{6ce,,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.

Note that while @code{iterparse()} builds the tree incrementally, it issues
blocking reads on `source' (or the file it names).  As such, it’s unsuitable
for applications where blocking reads can’t be made.  For fully non-blocking
parsing, see @ref{139c,,XMLPullParser}.

@cartouche
@quotation Σημείωση 
@code{iterparse()} only guarantees that it has seen the «>» character of a
starting tag when it emits a «start» event, so the attributes are defined,
but the contents of the text and tail attributes are undefined at that
point.  The same applies to the element children; they may or may not be
present.

If you need a fully populated element, look for «end» events instead.
@end quotation
@end cartouche


Αποσύρθηκε στην έκδοση 3.4: The `parser' argument.



Άλλαξε στην έκδοση 3.8: The @code{comment} and @code{pi} events were added.



Άλλαξε στην έκδοση 3.13: Added the @code{close()} method.



Άλλαξε στην έκδοση 3.15: A @ref{74f,,ResourceWarning} is now emitted if the iterator opened a file
and is not explicitly closed.

@end deffn

@geindex parse() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree parse}@anchor{3f55}
@deffn {Συνάρτηση} xml.etree.ElementTree.parse (source, parser=None)

Parses an XML section into an element tree.  `source' is a filename or file
object containing XML data.  `parser' is an optional parser instance.  If
not given, the standard @ref{e18,,XMLParser} parser is used.  Returns an
@ref{d19,,ElementTree} instance.
@end deffn

@geindex ProcessingInstruction() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ProcessingInstruction}@anchor{3f56}
@deffn {Συνάρτηση} xml.etree.ElementTree.ProcessingInstruction (target, text=None)

PI element factory.  This factory function creates a special element that
will be serialized as an XML processing instruction.  `target' is a string
containing the PI target.  `text' is a string containing the PI contents, if
given.  Returns an element instance, representing a processing instruction.

Note that @ref{e18,,XMLParser} skips over processing instructions
in the input instead of creating PI objects for them. An
@ref{d19,,ElementTree} will only contain processing instruction nodes if
they have been inserted into to the tree using one of the
@ref{343,,Element} methods.
@end deffn

@geindex register_namespace() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree register_namespace}@anchor{157b}
@deffn {Συνάρτηση} xml.etree.ElementTree.register_namespace (prefix, uri)

Registers a namespace prefix.  The registry is global, and any existing
mapping for either the given prefix or the namespace URI will be removed.
`prefix' is a namespace prefix.  `uri' is a namespace uri.  Tags and
attributes in this namespace will be serialized with the given prefix, if at
all possible.


Added in version 3.2.

@end deffn

@geindex SubElement() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree SubElement}@anchor{1930}
@deffn {Συνάρτηση} xml.etree.ElementTree.SubElement (parent, tag, /, attrib=@{@}, **extra)

Subelement factory.  This function creates an element instance, and appends
it to an existing element.

The element name, attribute names, and attribute values can be either
bytestrings or Unicode strings.  `parent' is the parent element.  `tag' is
the subelement name.  `attrib' is an optional dictionary, containing element
attributes.  `extra' contains additional attributes, given as keyword
arguments.  Returns an element instance.


Άλλαξε στην έκδοση 3.15: `attrib' can now be a @ref{182,,frozendict}.



Άλλαξε στην έκδοση 3.15: `parent' and `tag' are now positional-only parameters.

@end deffn

@geindex tostring() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree tostring}@anchor{139e}
@deffn {Συνάρτηση} xml.etree.ElementTree.tostring (element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)

Generates a string representation of an XML element, including all
subelements.  `element' is an @ref{343,,Element} instance.  `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
the output encoding (default is US-ASCII).  Use @code{encoding="unicode"} to
generate a Unicode string (otherwise, a bytestring is generated).  `method'
is either @code{"xml"}, @code{"html"} or @code{"text"} (default is @code{"xml"}).
`xml_declaration', `default_namespace' and `short_empty_elements' has the same
meaning as in @ref{e5b,,ElementTree.write()}. Returns an (optionally) encoded string
containing the XML data.


Άλλαξε στην έκδοση 3.4: Added the `short_empty_elements' parameter.



Άλλαξε στην έκδοση 3.8: Added the `xml_declaration' and `default_namespace' parameters.



Άλλαξε στην έκδοση 3.8: The @code{tostring()} function now preserves the attribute order
specified by the user.

@end deffn

@geindex tostringlist() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree tostringlist}@anchor{139f}
@deffn {Συνάρτηση} xml.etree.ElementTree.tostringlist (element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)

Generates a string representation of an XML element, including all
subelements.  `element' is an @ref{343,,Element} instance.  `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
the output encoding (default is US-ASCII).  Use @code{encoding="unicode"} to
generate a Unicode string (otherwise, a bytestring is generated).  `method'
is either @code{"xml"}, @code{"html"} or @code{"text"} (default is @code{"xml"}).
`xml_declaration', `default_namespace' and `short_empty_elements' has the same
meaning as in @ref{e5b,,ElementTree.write()}. Returns a list of (optionally) encoded
strings containing the XML data. It does not guarantee any specific sequence,
except that @code{b"".join(tostringlist(element)) == tostring(element)}.


Added in version 3.2.



Άλλαξε στην έκδοση 3.4: Added the `short_empty_elements' parameter.



Άλλαξε στην έκδοση 3.8: Added the `xml_declaration' and `default_namespace' parameters.



Άλλαξε στην έκδοση 3.8: The @code{tostringlist()} function now preserves the attribute order
specified by the user.

@end deffn

@geindex XML() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree XML}@anchor{3f52}
@deffn {Συνάρτηση} xml.etree.ElementTree.XML (text, parser=None)

Parses an XML section from a string constant.  This function can be used to
embed «XML literals» in Python code.  `text' is a string containing XML
data.  `parser' is an optional parser instance.  If not given, the standard
@ref{e18,,XMLParser} parser is used.  Returns an @ref{343,,Element} instance.
@end deffn

@geindex XMLID() (στη μονάδα xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree XMLID}@anchor{3f57}
@deffn {Συνάρτηση} xml.etree.ElementTree.XMLID (text, parser=None)

Parses an XML section from a string constant, and also returns a dictionary
which maps from element id:s to elements.  `text' is a string containing XML
data.  `parser' is an optional parser instance.  If not given, the standard
@ref{e18,,XMLParser} parser is used.  Returns a tuple containing an
@ref{343,,Element} instance and a dictionary.
@end deffn

@node XInclude support,Reference<6>,Reference<5>,xml etree ElementTree — The ElementTree XML API
@anchor{library/xml etree elementtree elementtree-xinclude}@anchor{3f58}@anchor{library/xml etree elementtree xinclude-support}@anchor{3f59}
@subsubsection XInclude support


This module provides limited support for
XInclude directives@footnote{https://www.w3.org/TR/xinclude/}, via the @ref{12d,,xml.etree.ElementInclude} helper module.  This module can be used to insert subtrees and text strings into element trees, based on information in the tree.

@menu
* Example: Example<9>. 

@end menu

@node Example<9>,,,XInclude support
@anchor{library/xml etree elementtree id3}@anchor{3f5a}
@subsubsection Example


Here’s an example that demonstrates use of the XInclude module. To include an XML document in the current document, use the @code{@{http://www.w3.org/2001/XInclude@}include} element and set the `parse' attribute to @code{"xml"}, and use the `href' attribute to specify the document to include.

@example
<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="source.xml" parse="xml" />
</document>
@end example

By default, the `href' attribute is treated as a file name. You can use custom loaders to override this behaviour. Also note that the standard helper does not support XPointer syntax.

To process this file, load it as usual, and pass the root element to the @code{xml.etree.ElementTree} module:

@example
from xml.etree import ElementTree, ElementInclude

tree = ElementTree.parse("document.xml")
root = tree.getroot()

ElementInclude.include(root)
@end example

The ElementInclude module replaces the @code{@{http://www.w3.org/2001/XInclude@}include} element with the root element from the `source.xml' document. The result might look something like this:

@example
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <para>This is a paragraph.</para>
</document>
@end example

If the `parse' attribute is omitted, it defaults to «xml». The href attribute is required.

To include a text document, use the @code{@{http://www.w3.org/2001/XInclude@}include} element, and set the `parse' attribute to «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

The result might look something like:

@example
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) 2003.
</document>
@end example

@node Reference<6>,,XInclude support,xml etree ElementTree — The ElementTree XML API
@anchor{library/xml etree elementtree id4}@anchor{3f5b}
@subsubsection Reference


@menu
* Functions: Functions<8>. 
* Element Objects:: 
* ElementTree Objects:: 
* QName Objects:: 
* TreeBuilder Objects:: 
* XMLParser Objects:: 
* XMLPullParser Objects:: 
* Exceptions: Exceptions<20>. 

@end menu

@node Functions<8>,Element Objects,,Reference<6>
@anchor{library/xml etree elementtree elementinclude-functions}@anchor{3f5c}@anchor{library/xml etree elementtree id5}@anchor{3f5d}
@subsubsection Functions


@geindex module; xml.etree.ElementInclude

@geindex default_loader() (στη μονάδα xml.etree.ElementInclude)
@anchor{library/xml etree elementtree module-xml etree ElementInclude}@anchor{12d}@anchor{library/xml etree elementtree xml etree ElementInclude default_loader}@anchor{3f5e}
@deffn {Συνάρτηση} 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{343,,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() (στη μονάδα xml.etree.ElementInclude)
@anchor{library/xml etree elementtree xml etree ElementInclude include}@anchor{3f5f}
@deffn {Συνάρτηση} 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{343,,Element} or an
@ref{d19,,ElementTree} instance to find such element.
`loader' is an optional resource loader.  If omitted, it defaults to @ref{3f5e,,default_loader()}.
If given, it should be a callable that implements the same interface as
@code{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.


Άλλαξε στην έκδοση 3.9: Added the `base_url' and `max_depth' parameters.

@end deffn

@node Element Objects,ElementTree Objects,Functions<8>,Reference<6>
@anchor{library/xml etree elementtree element-objects}@anchor{3f60}@anchor{library/xml etree elementtree elementtree-element-objects}@anchor{3f61}
@subsubsection Element Objects


@geindex Element (κλάση σε xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree Element}@anchor{343}
@deffn {Κλάση} xml.etree.ElementTree.Element (tag, /, attrib=@{@}, **extra)

Element class.  This class defines the Element interface, and provides a
reference implementation of this interface.

The element name, attribute names, and attribute values can be either
bytestrings or Unicode strings.  `tag' is the element name.  `attrib' is
an optional dictionary, containing element attributes.  `extra' contains
additional attributes, given as keyword arguments.


Άλλαξε στην έκδοση 3.15: `attrib' can now be a @ref{182,,frozendict}.



Άλλαξε στην έκδοση 3.15: `tag' is now a positional-only parameter.


@geindex tag (ιδιότητα της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element tag}@anchor{16f2}
@deffn {Ιδιότητα} tag

A string identifying what kind of data this element represents (the
element type, in other words).
@end deffn

@geindex text (ιδιότητα της xml.etree.ElementTree.Element)
@geindex tail (ιδιότητα της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element text}@anchor{3f43}
@deffn {Ιδιότητα} text
@anchor{library/xml etree elementtree xml etree ElementTree Element tail}@anchor{3f62}
@deffnx {Ιδιότητα} tail

These attributes can be used to hold additional data associated with
the element.  Their values are usually strings but may be any
application-specific object.  If the element is created from
an XML file, the `text' attribute holds either the text between
the element’s start tag and its first child or end tag, or @code{None}, and
the `tail' attribute holds either the text between the element’s
end tag and the next tag, or @code{None}.  For the XML data

@example
<a><b>1<c>2<d/>3</c></b>4</a>
@end example

the `a' element has @code{None} for both `text' and `tail' attributes,
the `b' element has `text' @code{"1"} and `tail' @code{"4"},
the `c' element has `text' @code{"2"} and `tail' @code{None},
and the `d' element has `text' @code{None} and `tail' @code{"3"}.

To collect the inner text of an element, see @ref{157e,,itertext()}, for
example @code{"".join(element.itertext())}.

Applications may store arbitrary objects in these attributes.
@end deffn

@geindex attrib (ιδιότητα της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element attrib}@anchor{3f63}
@deffn {Ιδιότητα} attrib

A dictionary containing the element’s attributes.  Note that while the
`attrib' value is always a real mutable Python dictionary, an ElementTree
implementation may choose to use another internal representation, and
create the dictionary only if someone asks for it.  To take advantage of
such implementations, use the dictionary methods below whenever possible.
@end deffn

The following dictionary-like methods work on the element attributes.

@geindex clear() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element clear}@anchor{3f64}
@deffn {Μέθοδος} clear ()

Resets an element.  This function removes all subelements, clears all
attributes, and sets the text and tail attributes to @code{None}.
@end deffn

@geindex get() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element get}@anchor{3f44}
@deffn {Μέθοδος} get (key, default=None)

Gets the element attribute named `key'.

Returns the attribute value, or `default' if the attribute was not found.
@end deffn

@geindex items() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element items}@anchor{3f65}
@deffn {Μέθοδος} items ()

Returns the element attributes as a sequence of (name, value) pairs.  The
attributes are returned in an arbitrary order.
@end deffn

@geindex keys() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element keys}@anchor{3f66}
@deffn {Μέθοδος} keys ()

Returns the elements attribute names as a list.  The names are returned
in an arbitrary order.
@end deffn

@geindex set() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element set}@anchor{3f46}
@deffn {Μέθοδος} set (key, value)

Set the attribute `key' on the element to `value'.
@end deffn

The following methods work on the element’s children (subelements).

@geindex append() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element append}@anchor{3f47}
@deffn {Μέθοδος} append (subelement)

Adds the element `subelement' to the end of this element’s internal list
of subelements.  Raises @ref{291,,TypeError} if `subelement' is not an
@code{Element}.
@end deffn

@geindex extend() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element extend}@anchor{157c}
@deffn {Μέθοδος} extend (subelements)

Appends `subelements' from an iterable of elements.
Raises @ref{291,,TypeError} if a subelement is not an @code{Element}.


Added in version 3.2.

@end deffn

@geindex find() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element find}@anchor{1aa1}
@deffn {Μέθοδος} find (match, namespaces=None)

Finds the first subelement matching `match'.  `match' may be a tag name
or a @ref{f6b,,path}.  Returns an element instance
or @code{None}.  `namespaces' is an optional mapping from namespace prefix
to full name.  Pass @code{'@w{'}} as prefix to move all unprefixed tag names
in the expression into the given namespace.
@end deffn

@geindex findall() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element findall}@anchor{1aa2}
@deffn {Μέθοδος} findall (match, namespaces=None)

Finds all matching subelements, by tag name or
@ref{f6b,,path}.  Returns a list containing all matching
elements in document order.  `namespaces' is an optional mapping from
namespace prefix to full name.  Pass @code{'@w{'}} as prefix to move all
unprefixed tag names in the expression into the given namespace.
@end deffn

@geindex findtext() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element findtext}@anchor{190a}
@deffn {Μέθοδος} findtext (match, default=None, namespaces=None)

Finds text for the first subelement matching `match'.  `match' may be
a tag name or a @ref{f6b,,path}.  Returns the text content
of the first matching element, or `default' if no element was found.
Note that if the matching element has no text content an empty string
is returned. `namespaces' is an optional mapping from namespace prefix
to full name.  Pass @code{'@w{'}} as prefix to move all unprefixed tag names
in the expression into the given namespace.
@end deffn

@geindex insert() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element insert}@anchor{3f67}
@deffn {Μέθοδος} insert (index, subelement)

Inserts `subelement' at the given position in this element.  Raises
@ref{291,,TypeError} if `subelement' is not an @code{Element}.
@end deffn

@geindex iter() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element iter}@anchor{16f3}
@deffn {Μέθοδος} iter (tag=None)

Creates a tree @ref{6ce,,iterator} with the current element as the root.
The iterator iterates over this element and all elements below it, in
document (depth first) order.  If `tag' is not @code{None} or @code{'*'}, only
elements whose tag equals `tag' are returned from the iterator.  If the
tree structure is modified during iteration, the result is undefined.


Added in version 3.2.

@end deffn

@geindex iterfind() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element iterfind}@anchor{157d}
@deffn {Μέθοδος} iterfind (match, namespaces=None)

Finds all matching subelements, by tag name or
@ref{f6b,,path}.  Returns an iterable yielding all
matching elements in document order. `namespaces' is an optional mapping
from namespace prefix to full name.


Added in version 3.2.

@end deffn

@geindex itertext() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element itertext}@anchor{157e}
@deffn {Μέθοδος} itertext ()

Creates a text iterator.  The iterator loops over this element and all
subelements, in document order, and returns all inner text.


Added in version 3.2.

@end deffn

@geindex makeelement() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element makeelement}@anchor{3f68}
@deffn {Μέθοδος} makeelement (tag, attrib)

Creates a new element object of the same type as this element.  Do not
call this method, use the @ref{1930,,SubElement()} factory function instead.
@end deffn

@geindex remove() (μέθοδος της xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element remove}@anchor{1981}
@deffn {Μέθοδος} remove (subelement)

Removes `subelement' from the element.  Unlike the find* methods this
method compares elements based on the instance identity, not on tag value
or contents.
@end deffn

@code{Element} objects also support the following sequence type methods
for working with subelements: @ref{1671,,__delitem__()},
@ref{787,,__getitem__()}, @ref{1670,,__setitem__()},
@ref{1989,,__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


Άλλαξε στην έκδοση 3.12: Testing the truth value of an Element emits @ref{2c9,,DeprecationWarning}.


Prior to Python 3.8, the serialisation order of the XML attributes of
elements was artificially made predictable by sorting the attributes by
their name. Based on the now guaranteed ordering of dicts, this arbitrary
reordering was removed in Python 3.8 to preserve the order in which
attributes were originally parsed or created by user code.

In general, user code should try not to depend on a specific ordering of
attributes, given that the XML Information Set@footnote{https://www.w3.org/TR/xml-infoset/} explicitly excludes the attribute
order from conveying information. Code should be prepared to deal with
any ordering on input. In cases where deterministic XML output is required,
e.g. for cryptographic signing or test data sets, canonical serialisation
is available with the @ref{e17,,canonicalize()} function.

In cases where canonical output is not applicable but a specific attribute
order is still desirable on output, code should aim for creating the
attributes directly in the desired order, to avoid perceptual mismatches
for readers of the code. In cases where this is difficult to achieve, a
recipe like the following can be applied prior to serialisation to enforce
an order independently from the Element creation:

@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 ElementTree Objects,QName Objects,Element Objects,Reference<6>
@anchor{library/xml etree elementtree elementtree-elementtree-objects}@anchor{3f69}@anchor{library/xml etree elementtree elementtree-objects}@anchor{3f6a}
@subsubsection ElementTree Objects


@geindex ElementTree (κλάση σε xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree}@anchor{d19}
@deffn {Κλάση} xml.etree.ElementTree.ElementTree (element=None, file=None)

ElementTree wrapper class.  This class represents an entire element
hierarchy, and adds some extra support for serialization to and from
standard XML.

`element' is the root element.  The tree is initialized with the contents
of the XML `file' if given.

@geindex _setroot() (μέθοδος της xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree _setroot}@anchor{3f6b}
@deffn {Μέθοδος} _setroot (element)

Replaces the root element for this tree.  This discards the current
contents of the tree, and replaces it with the given element.  Use with
care.  `element' is an element instance.
@end deffn

@geindex find() (μέθοδος της xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree find}@anchor{3f6c}
@deffn {Μέθοδος} find (match, namespaces=None)

Same as @ref{1aa1,,Element.find()}, starting at the root of the tree.
@end deffn

@geindex findall() (μέθοδος της xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree findall}@anchor{3f6d}
@deffn {Μέθοδος} findall (match, namespaces=None)

Same as @ref{1aa2,,Element.findall()}, starting at the root of the tree.
@end deffn

@geindex findtext() (μέθοδος της xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree findtext}@anchor{3f6e}
@deffn {Μέθοδος} findtext (match, default=None, namespaces=None)

Same as @ref{190a,,Element.findtext()}, starting at the root of the tree.
@end deffn

@geindex getroot() (μέθοδος της xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree getroot}@anchor{3f6f}
@deffn {Μέθοδος} getroot ()

Returns the root element for this tree.
@end deffn

@geindex iter() (μέθοδος της xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree iter}@anchor{3f70}
@deffn {Μέθοδος} iter (tag=None)

Creates and returns a tree iterator for the root element.  The iterator
loops over all elements in this tree, in section order.  `tag' is the tag
to look for (default is to return all elements).
@end deffn

@geindex iterfind() (μέθοδος της xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree iterfind}@anchor{3f71}
@deffn {Μέθοδος} iterfind (match, namespaces=None)

Same as @ref{157d,,Element.iterfind()}, starting at the root of the tree.


Added in version 3.2.

@end deffn

@geindex parse() (μέθοδος της xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree parse}@anchor{3f72}
@deffn {Μέθοδος} parse (source, parser=None)

Loads an external XML section into this element tree.  `source' is a file
name or @ref{156c,,file object}.  `parser' is an optional parser instance.
If not given, the standard @ref{e18,,XMLParser} parser is used.  Returns the
section root element.
@end deffn

@geindex write() (μέθοδος της xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree write}@anchor{e5b}
@deffn {Μέθοδος} write (file, encoding='us-ascii', xml_declaration=None, default_namespace=None, method='xml', *, short_empty_elements=True)

Writes the element tree to a file, as XML.  `file' is a file name, or a
@ref{156c,,file object} opened for writing.  `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 the output
encoding (default is US-ASCII).
`xml_declaration' controls if an XML declaration should be added to the
file.  Use @code{False} for never, @code{True} for always, @code{None}
for only if not US-ASCII or UTF-8 or Unicode (default is @code{None}).
`default_namespace' sets the default XML namespace (for «xmlns»).
`method' is either @code{"xml"}, @code{"html"} or @code{"text"} (default is
@code{"xml"}).
The keyword-only `short_empty_elements' parameter controls the formatting
of elements that contain no content.  If @code{True} (the default), they are
emitted as a single self-closed tag, otherwise they are emitted as a pair
of start/end tags.

The output is either a string (@ref{1df,,str}) or binary (@ref{1c7,,bytes}).
This is controlled by the `encoding' argument.  If `encoding' is
@code{"unicode"}, the output is a string; otherwise, it’s binary.  Note that
this may conflict with the type of `file' if it’s an open
@ref{156c,,file object}; make sure you do not try to write a string to a
binary stream and vice versa.


Άλλαξε στην έκδοση 3.4: Added the `short_empty_elements' parameter.



Άλλαξε στην έκδοση 3.8: The @code{write()} method now preserves the attribute order specified
by the user.

@end deffn
@end deffn

This is the XML file that is going to be manipulated:

@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

Example of changing the attribute «target» of every link in first paragraph:

@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 QName Objects,TreeBuilder Objects,ElementTree Objects,Reference<6>
@anchor{library/xml etree elementtree elementtree-qname-objects}@anchor{3f73}@anchor{library/xml etree elementtree qname-objects}@anchor{3f74}
@subsubsection QName Objects


@geindex QName (κλάση σε xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree QName}@anchor{3f75}
@deffn {Κλάση} xml.etree.ElementTree.QName (text_or_uri, tag=None)

QName wrapper.  This can be used to wrap a QName attribute value, in order
to get proper namespace handling on output.  `text_or_uri' is a string
containing the QName value, in the form @{uri@}local, or, if the tag argument
is given, the URI part of a QName.  If `tag' is given, the first argument is
interpreted as a URI, and this argument is interpreted as a local name.
@code{QName} instances are opaque.
@end deffn

@node TreeBuilder Objects,XMLParser Objects,QName Objects,Reference<6>
@anchor{library/xml etree elementtree elementtree-treebuilder-objects}@anchor{3f76}@anchor{library/xml etree elementtree treebuilder-objects}@anchor{3f77}
@subsubsection TreeBuilder Objects


@geindex TreeBuilder (κλάση σε xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder}@anchor{e19}
@deffn {Κλάση} xml.etree.ElementTree.TreeBuilder (element_factory=None, *, comment_factory=None, pi_factory=None, insert_comments=False, insert_pis=False)

Generic element structure builder.  This builder converts a sequence of
start, data, end, comment and pi method calls to a well-formed element
structure.  You can use this class to build an element structure using
a custom XML parser, or a parser for some other XML-like format.

`element_factory', when given, must be a callable accepting two positional
arguments: a tag and a dict of attributes.  It is expected to return a new
element instance.

The `comment_factory' and `pi_factory' functions, when given, should behave
like the @ref{3f50,,Comment()} and @ref{3f56,,ProcessingInstruction()} functions to
create comments and processing instructions.  When not given, the default
factories will be used.  When `insert_comments' and/or `insert_pis' is true,
comments/pis will be inserted into the tree if they appear within the root
element (but not outside of it).

@geindex close() (μέθοδος της xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder close}@anchor{3f78}
@deffn {Μέθοδος} close ()

Flushes the builder buffers, and returns the toplevel document
element.  Returns an @ref{343,,Element} instance.
@end deffn

@geindex data() (μέθοδος της xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder data}@anchor{3f79}
@deffn {Μέθοδος} data (data)

Adds text to the current element.  `data' is a string.  This should be
either a bytestring, or a Unicode string.
@end deffn

@geindex end() (μέθοδος της xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder end}@anchor{157f}
@deffn {Μέθοδος} end (tag)

Closes the current element.  `tag' is the element name.  Returns the
closed element.
@end deffn

@geindex start() (μέθοδος της xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder start}@anchor{1f60}
@deffn {Μέθοδος} start (tag, attrs)

Opens a new element.  `tag' is the element name.  `attrs' is a dictionary
containing element attributes.  Returns the opened element.
@end deffn

@geindex comment() (μέθοδος της xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder comment}@anchor{3f7a}
@deffn {Μέθοδος} comment (text)

Creates a comment with the given `text'.  If @code{insert_comments} is true,
this will also add it to the tree.


Added in version 3.8.

@end deffn

@geindex pi() (μέθοδος της xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder pi}@anchor{3f7b}
@deffn {Μέθοδος} 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.


Added in version 3.8.

@end deffn

In addition, a custom @code{TreeBuilder} object can provide the
following methods:

@geindex doctype() (μέθοδος της xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder doctype}@anchor{e5d}
@deffn {Μέθοδος} doctype (name, pubid, system)

Handles a doctype declaration.  `name' is the doctype name.  `pubid' is
the public identifier.  `system' is the system identifier.  This method
does not exist on the default @code{TreeBuilder} class.


Added in version 3.2.

@end deffn

@geindex start_ns() (μέθοδος της xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder start_ns}@anchor{3f7c}
@deffn {Μέθοδος} start_ns (prefix, uri)

Is called whenever the parser encounters a new namespace declaration,
before the @code{start()} callback for the opening element that defines it.
`prefix' is @code{'@w{'}} for the default namespace and the declared
namespace prefix name otherwise.  `uri' is the namespace URI.


Added in version 3.8.

@end deffn

@geindex end_ns() (μέθοδος της xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder end_ns}@anchor{3f7d}
@deffn {Μέθοδος} end_ns (prefix)

Is called after the @code{end()} callback of an element that declared
a namespace prefix mapping, with the name of the `prefix' that went
out of scope.


Added in version 3.8.

@end deffn
@end deffn

@geindex C14NWriterTarget (κλάση σε xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree C14NWriterTarget}@anchor{3f7e}
@deffn {Κλάση} 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)

A C14N 2.0@footnote{https://www.w3.org/TR/xml-c14n2/} writer.  Arguments are the
same as for the @ref{e17,,canonicalize()} function.  This class does not build a
tree but translates the callback events directly into a serialised form
using the `write' function.


Added in version 3.8.

@end deffn

@node XMLParser Objects,XMLPullParser Objects,TreeBuilder Objects,Reference<6>
@anchor{library/xml etree elementtree elementtree-xmlparser-objects}@anchor{3f7f}@anchor{library/xml etree elementtree xmlparser-objects}@anchor{3f80}
@subsubsection XMLParser Objects


@geindex XMLParser (κλάση σε xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree XMLParser}@anchor{e18}
@deffn {Κλάση} xml.etree.ElementTree.XMLParser (*, target=None, encoding=None)

This class is the low-level building block of the module.  It uses
@ref{12f,,xml.parsers.expat} for efficient, event-based parsing of XML.  It can
be fed XML data incrementally with the @ref{3f81,,feed()} method, and parsing
events are translated to a push API - by invoking callbacks on the `target'
object.  If `target' is omitted, the standard @ref{e19,,TreeBuilder} is used.
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, the value overrides the
encoding specified in the XML file.


Άλλαξε στην έκδοση 3.8: Parameters are now @ref{7a3,,keyword-only}.
The `html' argument is no longer supported.


@geindex close() (μέθοδος της xml.etree.ElementTree.XMLParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLParser close}@anchor{3f82}
@deffn {Μέθοδος} close ()

Finishes feeding data to the parser.  Returns the result of calling the
@code{close()} method of the `target' passed during construction; by default,
this is the toplevel document element.
@end deffn

@geindex feed() (μέθοδος της xml.etree.ElementTree.XMLParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLParser feed}@anchor{3f81}
@deffn {Μέθοδος} feed (data)

Feeds data to the parser.  `data' is encoded data.
@end deffn

@geindex flush() (μέθοδος της xml.etree.ElementTree.XMLParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLParser flush}@anchor{777}
@deffn {Μέθοδος} 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 @code{flush()} temporarily disables reparse deferral
with Expat (if currently enabled) and triggers a reparse.
Disabling reparse deferral has security consequences; please see
@ref{77a,,xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()} for details.

@code{flush()}
has been backported to some prior releases of CPython as a security fix.
Check for availability using @ref{8e2,,hasattr()} if used in code running
across a variety of Python versions.


Added in version 3.13.

@end deffn

@ref{3f81,,XMLParser.feed()} calls `target''s @code{start(tag, attrs_dict)} method
for each opening tag, its @code{end(tag)} method for each closing tag, and data
is processed by method @code{data(data)}.  For further supported callback
methods, see the @ref{e19,,TreeBuilder} class.  @ref{3f82,,XMLParser.close()} calls
`target''s method @code{close()}. @code{XMLParser} can be used not only for
building a tree structure. This is an example of counting the maximum depth
of an XML file:

@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 XMLPullParser Objects,Exceptions<20>,XMLParser Objects,Reference<6>
@anchor{library/xml etree elementtree elementtree-xmlpullparser-objects}@anchor{3f83}@anchor{library/xml etree elementtree xmlpullparser-objects}@anchor{3f84}
@subsubsection XMLPullParser Objects


@geindex XMLPullParser (κλάση σε xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser}@anchor{139c}
@deffn {Κλάση} xml.etree.ElementTree.XMLPullParser (events=None)

A pull parser suitable for non-blocking applications.  Its input-side API is
similar to that of @ref{e18,,XMLParser}, but instead of pushing calls to a
callback target, @code{XMLPullParser} collects an internal list of parsing
events and lets the user read from it. `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.

@geindex feed() (μέθοδος της xml.etree.ElementTree.XMLPullParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser feed}@anchor{3f40}
@deffn {Μέθοδος} feed (data)

Feed the given bytes data to the parser.
@end deffn

@geindex flush() (μέθοδος της xml.etree.ElementTree.XMLPullParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser flush}@anchor{778}
@deffn {Μέθοδος} 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 @code{flush()} temporarily disables reparse deferral
with Expat (if currently enabled) and triggers a reparse.
Disabling reparse deferral has security consequences; please see
@ref{77a,,xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()} for details.

@code{flush()}
has been backported to some prior releases of CPython as a security fix.
Check for availability using @ref{8e2,,hasattr()} if used in code running
across a variety of Python versions.


Added in version 3.13.

@end deffn

@geindex close() (μέθοδος της xml.etree.ElementTree.XMLPullParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser close}@anchor{3f85}
@deffn {Μέθοδος} close ()

Signal the parser that the data stream is terminated. Unlike
@ref{3f82,,XMLParser.close()}, this method always returns @ref{a65,,None}.
Any events not yet retrieved when the parser is closed can still be
read with @ref{3f41,,read_events()}.
@end deffn

@geindex read_events() (μέθοδος της xml.etree.ElementTree.XMLPullParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser read_events}@anchor{3f41}
@deffn {Μέθοδος} read_events ()

Return an iterator over the events which have been encountered in the
data fed to the
parser.  The iterator yields @code{(event, elem)} pairs, where `event' is a
string representing the type of event (e.g. @code{"end"}) and `elem' is the
encountered @ref{343,,Element} object, or other context value as follows.


@itemize *

@item 
@code{start}, @code{end}: the current Element.

@item 
@code{comment}, @code{pi}: the current comment / processing instruction

@item 
@code{start-ns}: a tuple @code{(prefix, uri)} naming the declared namespace
mapping.

@item 
@code{end-ns}: @ref{a65,,None} (this may change in a future version)
@end itemize

Events provided in a previous call to @code{read_events()} will not be
yielded again.  Events are consumed from the internal queue only when
they are retrieved from the iterator, so multiple readers iterating in
parallel over iterators obtained from @code{read_events()} will have
unpredictable results.
@end deffn

@cartouche
@quotation Σημείωση 
@code{XMLPullParser} only guarantees that it has seen the «>»
character of a starting tag when it emits a «start» event, so the
attributes are defined, but the contents of the text and tail attributes
are undefined at that point.  The same applies to the element children;
they may or may not be present.

If you need a fully populated element, look for «end» events instead.
@end quotation
@end cartouche


Added in version 3.4.



Άλλαξε στην έκδοση 3.8: The @code{comment} and @code{pi} events were added.

@end deffn

@node Exceptions<20>,,XMLPullParser Objects,Reference<6>
@anchor{library/xml etree elementtree exceptions}@anchor{3f86}
@subsubsection Exceptions


@geindex ParseError (κλάση σε xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ParseError}@anchor{161c}
@deffn {Κλάση} xml.etree.ElementTree.ParseError

XML parse error, raised by the various parsing methods in this module when
parsing fails.  The string representation of an instance of this exception
will contain a user-friendly error message.  In addition, it will have
the following attributes available:

@geindex code (ιδιότητα της xml.etree.ElementTree.ParseError)
@anchor{library/xml etree elementtree xml etree ElementTree ParseError code}@anchor{3f87}
@deffn {Ιδιότητα} code

A numeric error code from the expat parser. See the documentation of
@ref{12f,,xml.parsers.expat} for the list of error codes and their meanings.
@end deffn

@geindex position (ιδιότητα της xml.etree.ElementTree.ParseError)
@anchor{library/xml etree elementtree xml etree ElementTree ParseError position}@anchor{3f88}
@deffn {Ιδιότητα} position

A tuple of `line', `column' numbers, specifying where the error occurred.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xml dom — The Document Object Model API,xml dom minidom — Minimal DOM implementation,xml etree ElementTree — The ElementTree XML API,Structured Markup Processing Tools
@anchor{library/xml dom doc}@anchor{3f89}@anchor{library/xml dom module-xml dom}@anchor{12a}@anchor{library/xml dom translation-repo}@anchor{3f8a}@anchor{library/xml dom xml-dom-the-document-object-model-api}@anchor{3f8b}
@subsection @code{xml.dom} — The Document Object Model API


@geindex module; xml.dom

`Source code:' Lib/xml/dom/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/xml/dom/__init__.py}


__________________________________________________________________


The Document Object Model, or «DOM,» is a cross-language API from the World Wide
Web Consortium (W3C) for accessing and modifying XML documents.  A DOM
implementation presents an XML document as a tree structure, or allows client
code to build such a structure from scratch.  It then gives access to the
structure through a set of objects which provided well-known interfaces.

The DOM is extremely useful for random-access applications.  SAX only allows you
a view of one bit of the document at a time.  If you are looking at one SAX
element, you have no access to another.  If you are looking at a text node, you
have no access to a containing element. When you write a SAX application, you
need to keep track of your program’s position in the document somewhere in your
own code.  SAX does not do it for you.  Also, if you need to look ahead in the
XML document, you are just out of luck.

Some applications are simply impossible in an event driven model with no access
to a tree.  Of course you could build some sort of tree yourself in SAX events,
but the DOM allows you to avoid writing that code.  The DOM is a standard tree
representation for XML data.

The Document Object Model is being defined by the W3C in stages, or «levels» in
their terminology.  The Python mapping of the API is substantially based on the
DOM Level 2 recommendation.

@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

DOM applications typically start by parsing some XML into a DOM.  How this is
accomplished is not covered at all by DOM Level 1, and Level 2 provides only
limited improvements: There is a @code{DOMImplementation} object class which
provides access to @code{Document} creation methods, but no way to access an
XML reader/parser/Document builder in an implementation-independent way. There
is also no well-defined way to access these methods without an existing
@code{Document} object.  In Python, each DOM implementation will provide a
function @ref{3f8c,,getDOMImplementation()}. DOM Level 3 adds a Load/Store
specification, which defines an interface to the reader, but this is not yet
available in the Python standard library.

Once you have a DOM document object, you can access the parts of your XML
document through its properties and methods.  These properties are defined in
the DOM specification; this portion of the reference manual describes the
interpretation of the specification in Python.

The specification provided by the W3C defines the DOM API for Java, ECMAScript,
and OMG IDL.  The Python mapping defined here is based in large part on the IDL
version of the specification, but strict compliance is not required (though
implementations are free to support the strict mapping from IDL).  See section
@ref{3f8d,,Conformance} for a detailed discussion of mapping requirements.


@subsubheading Δείτε επίσης



@table @asis

@item Document Object Model (DOM) Level 2 Specification@footnote{https://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/}

The W3C recommendation upon which the Python DOM API is based.

@item Document Object Model (DOM) Level 1 Specification@footnote{https://www.w3.org/TR/REC-DOM-Level-1/}

The W3C recommendation for the DOM supported by @ref{12b,,xml.dom.minidom}.

@item Python Language Mapping Specification@footnote{https://www.omg.org/spec/PYTH/1.2/PDF}

This specifies the mapping from OMG IDL to Python.
@end table


@menu
* Module Contents:: 
* Objects in the DOM:: 
* Conformance:: 

@end menu

@node Module Contents,Objects in the DOM,,xml dom — The Document Object Model API
@anchor{library/xml dom module-contents}@anchor{3f8e}
@subsubsection Module Contents


The @code{xml.dom} contains the following functions:

@geindex registerDOMImplementation() (στη μονάδα xml.dom)
@anchor{library/xml dom xml dom registerDOMImplementation}@anchor{3f8f}
@deffn {Συνάρτηση} xml.dom.registerDOMImplementation (name, factory)

Register the `factory' function with the name `name'.  The factory function
should return an object which implements the @code{DOMImplementation}
interface.  The factory function can return the same object every time, or a new
one for each call, as appropriate for the specific implementation (e.g. if that
implementation supports some customization).
@end deffn

@geindex getDOMImplementation() (στη μονάδα xml.dom)
@anchor{library/xml dom xml dom getDOMImplementation}@anchor{3f8c}
@deffn {Συνάρτηση} xml.dom.getDOMImplementation (name=None, features=())

Return a suitable DOM implementation. The `name' is either well-known, the
module name of a DOM implementation, or @code{None}. If it is not @code{None}, imports
the corresponding module and returns a @code{DOMImplementation} object if the
import succeeds.  If no name is given, and if the environment variable
@geindex PYTHON_DOM
@geindex μεταβλητή περιβάλλοντος; PYTHON_DOM
@code{PYTHON_DOM} is set, this variable is used to find the implementation.

If name is not given, this examines the available implementations to find one
with the required feature set.  If no implementation can be found, raise an
@ref{1bd,,ImportError}.  The features list must be a sequence of @code{(feature,
version)} pairs which are passed to the @code{hasFeature()} method on available
@code{DOMImplementation} objects.
@end deffn

Some convenience constants are also provided:

@geindex EMPTY_NAMESPACE (στη μονάδα xml.dom)
@anchor{library/xml dom xml dom EMPTY_NAMESPACE}@anchor{3f90}
@deffn {Δεδομένα} xml.dom.EMPTY_NAMESPACE

The value used to indicate that no namespace is associated with a node in the
DOM.  This is typically found as the @code{namespaceURI} of a node, or used as
the `namespaceURI' parameter to a namespaces-specific method.
@end deffn

@geindex XML_NAMESPACE (στη μονάδα xml.dom)
@anchor{library/xml dom xml dom XML_NAMESPACE}@anchor{3f91}
@deffn {Δεδομένα} xml.dom.XML_NAMESPACE

The namespace URI associated with the reserved prefix @code{xml}, as defined by
Namespaces in XML@footnote{https://www.w3.org/TR/REC-xml-names/} (section 4).
@end deffn

@geindex XMLNS_NAMESPACE (στη μονάδα xml.dom)
@anchor{library/xml dom xml dom XMLNS_NAMESPACE}@anchor{3f92}
@deffn {Δεδομένα} xml.dom.XMLNS_NAMESPACE

The namespace URI for namespace declarations, as defined by 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 (στη μονάδα xml.dom)
@anchor{library/xml dom xml dom XHTML_NAMESPACE}@anchor{3f93}
@deffn {Δεδομένα} xml.dom.XHTML_NAMESPACE

The URI of the XHTML namespace as defined by XHTML 1.0: The Extensible HyperText Markup Language@footnote{https://www.w3.org/TR/xhtml1/} (section 3.1.1).
@end deffn

In addition, @code{xml.dom} contains a base @code{Node} class and the DOM
exception classes.  The @code{Node} class provided by this module does not
implement any of the methods or attributes defined by the DOM specification;
concrete DOM implementations must provide those.  The @code{Node} class
provided as part of this module does provide the constants used for the
@code{nodeType} attribute on concrete @code{Node} objects; they are located
within the class rather than at the module level to conform with the DOM
specifications.

@c Should the Node documentation go here?

@node Objects in the DOM,Conformance,Module Contents,xml dom — The Document Object Model API
@anchor{library/xml dom dom-objects}@anchor{3f94}@anchor{library/xml dom objects-in-the-dom}@anchor{3f95}
@subsubsection Objects in the DOM


The definitive documentation for the DOM is the DOM specification from the W3C.

Note that DOM attributes may also be manipulated as nodes instead of as simple
strings.  It is fairly rare that you must do this, however, so this usage is not
yet documented.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Interface

@tab

Section

@tab

Purpose

@item

@code{DOMImplementation}

@tab

@ref{3f96,,DOMImplementation Objects}

@tab

Interface to the underlying
implementation.

@item

@code{Node}

@tab

@ref{3f97,,Node Objects}

@tab

Base interface for most objects
in a document.

@item

@code{NodeList}

@tab

@ref{25a0,,NodeList Objects}

@tab

Interface for a sequence of
nodes.

@item

@code{DocumentType}

@tab

@ref{3f98,,DocumentType Objects}

@tab

Information about the
declarations needed to process
a document.

@item

@code{Document}

@tab

@ref{3f99,,Document Objects}

@tab

Object which represents an
entire document.

@item

@code{Element}

@tab

@ref{3f9a,,Element Objects}

@tab

Element nodes in the document
hierarchy.

@item

@code{Attr}

@tab

@ref{3f9b,,Attr Objects}

@tab

Attribute value nodes on
element nodes.

@item

@code{Comment}

@tab

@ref{3f9c,,Comment Objects}

@tab

Representation of comments in
the source document.

@item

@code{Text}

@tab

@ref{3f9d,,Text and CDATASection Objects}

@tab

Nodes containing textual
content from the document.

@item

@code{ProcessingInstruction}

@tab

@ref{3f9e,,ProcessingInstruction Objects}

@tab

Processing instruction
representation.

@end multitable


An additional section describes the exceptions defined for working with the DOM
in Python.

@menu
* DOMImplementation Objects:: 
* Node Objects:: 
* NodeList Objects:: 
* DocumentType Objects:: 
* Document Objects:: 
* Element Objects: Element Objects<2>. 
* Attr Objects:: 
* NamedNodeMap Objects:: 
* Comment Objects:: 
* Text and CDATASection Objects:: 
* ProcessingInstruction Objects:: 
* Exceptions: Exceptions<21>. 

@end menu

@node DOMImplementation Objects,Node Objects,,Objects in the DOM
@anchor{library/xml dom dom-implementation-objects}@anchor{3f96}@anchor{library/xml dom domimplementation-objects}@anchor{3f9f}
@subsubsection DOMImplementation Objects


The @code{DOMImplementation} interface provides a way for applications to
determine the availability of particular features in the DOM they are using.
DOM Level 2 added the ability to create new @code{Document} and
@code{DocumentType} objects using the @code{DOMImplementation} as well.

@geindex hasFeature() (μέθοδος της xml.dom.DOMImplementation)
@anchor{library/xml dom xml dom DOMImplementation hasFeature}@anchor{3fa0}
@deffn {Μέθοδος} DOMImplementation.hasFeature (feature, version)

Return @code{True} if the feature identified by the pair of strings `feature' and
`version' is implemented.
@end deffn

@geindex createDocument() (μέθοδος της xml.dom.DOMImplementation)
@anchor{library/xml dom xml dom DOMImplementation createDocument}@anchor{3fa1}
@deffn {Μέθοδος} DOMImplementation.createDocument (namespaceUri, qualifiedName, doctype)

Return a new @code{Document} object (the root of the DOM), with a child
@code{Element} object having the given `namespaceUri' and `qualifiedName'. The
`doctype' must be a @code{DocumentType} object created by
@ref{3fa2,,createDocumentType()}, or @code{None}. In the Python DOM API, the first two
arguments can also be @code{None} in order to indicate that no @code{Element}
child is to be created.
@end deffn

@geindex createDocumentType() (μέθοδος της xml.dom.DOMImplementation)
@anchor{library/xml dom xml dom DOMImplementation createDocumentType}@anchor{3fa2}
@deffn {Μέθοδος} DOMImplementation.createDocumentType (qualifiedName, publicId, systemId)

Return a new @code{DocumentType} object that encapsulates the given
`qualifiedName', `publicId', and `systemId' strings, representing the
information contained in an XML document type declaration.
@end deffn

@node Node Objects,NodeList Objects,DOMImplementation Objects,Objects in the DOM
@anchor{library/xml dom dom-node-objects}@anchor{3f97}@anchor{library/xml dom node-objects}@anchor{3fa3}
@subsubsection Node Objects


All of the components of an XML document are subclasses of @code{Node}.

@geindex nodeType (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node nodeType}@anchor{3fa4}
@deffn {Ιδιότητα} Node.nodeType

An integer representing the node type.  Symbolic constants for the types are on
the @code{Node} object: @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}.
This is a read-only attribute.
@end deffn

@geindex parentNode (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node parentNode}@anchor{3fa5}
@deffn {Ιδιότητα} Node.parentNode

The parent of the current node, or @code{None} for the document node. The value is
always a @code{Node} object or @code{None}.  For @code{Element} nodes, this
will be the parent element, except for the root element, in which case it will
be the @code{Document} object. For @code{Attr} nodes, this is always
@code{None}. This is a read-only attribute.
@end deffn

@geindex attributes (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node attributes}@anchor{3fa6}
@deffn {Ιδιότητα} Node.attributes

A @code{NamedNodeMap} of attribute objects.  Only elements have actual values
for this; others provide @code{None} for this attribute. This is a read-only
attribute.
@end deffn

@geindex previousSibling (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node previousSibling}@anchor{3fa7}
@deffn {Ιδιότητα} Node.previousSibling

The node that immediately precedes this one with the same parent.  For
instance the element with an end-tag that comes just before the `self'
element’s start-tag.  Of course, XML documents are made up of more than just
elements so the previous sibling could be text, a comment, or something else.
If this node is the first child of the parent, this attribute will be
@code{None}. This is a read-only attribute.
@end deffn

@geindex nextSibling (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node nextSibling}@anchor{3fa8}
@deffn {Ιδιότητα} Node.nextSibling

The node that immediately follows this one with the same parent.  See also
@ref{3fa7,,previousSibling}.  If this is the last child of the parent, this
attribute will be @code{None}. This is a read-only attribute.
@end deffn

@geindex childNodes (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node childNodes}@anchor{3fa9}
@deffn {Ιδιότητα} Node.childNodes

A list of nodes contained within this node. This is a read-only attribute.
@end deffn

@geindex firstChild (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node firstChild}@anchor{3faa}
@deffn {Ιδιότητα} Node.firstChild

The first child of the node, if there are any, or @code{None}. This is a read-only
attribute.
@end deffn

@geindex lastChild (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node lastChild}@anchor{3fab}
@deffn {Ιδιότητα} Node.lastChild

The last child of the node, if there are any, or @code{None}. This is a read-only
attribute.
@end deffn

@geindex localName (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node localName}@anchor{3fac}
@deffn {Ιδιότητα} Node.localName

The part of the @code{tagName} following the colon if there is one, else the
entire @code{tagName}.  The value is a string.
@end deffn

@geindex prefix (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node prefix}@anchor{3fad}
@deffn {Ιδιότητα} Node.prefix

The part of the @code{tagName} preceding the colon if there is one, else the
empty string.  The value is a string, or @code{None}.
@end deffn

@geindex namespaceURI (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node namespaceURI}@anchor{3fae}
@deffn {Ιδιότητα} Node.namespaceURI

The namespace associated with the element name.  This will be a string or
@code{None}.  This is a read-only attribute.
@end deffn

@geindex nodeName (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node nodeName}@anchor{3faf}
@deffn {Ιδιότητα} Node.nodeName

This has a different meaning for each node type; see the DOM specification for
details.  You can always get the information you would get here from another
property such as the @code{tagName} property for elements or the @code{name}
property for attributes. For all node types, the value of this attribute will be
either a string or @code{None}.  This is a read-only attribute.
@end deffn

@geindex nodeValue (ιδιότητα της xml.dom.Node)
@anchor{library/xml dom xml dom Node nodeValue}@anchor{3fb0}
@deffn {Ιδιότητα} Node.nodeValue

This has a different meaning for each node type; see the DOM specification for
details.  The situation is similar to that with @ref{3faf,,nodeName}.  The value is
a string or @code{None}.
@end deffn

@geindex hasAttributes() (μέθοδος της xml.dom.Node)
@anchor{library/xml dom xml dom Node hasAttributes}@anchor{3fb1}
@deffn {Μέθοδος} Node.hasAttributes ()

Return @code{True} if the node has any attributes.
@end deffn

@geindex hasChildNodes() (μέθοδος της xml.dom.Node)
@anchor{library/xml dom xml dom Node hasChildNodes}@anchor{3fb2}
@deffn {Μέθοδος} Node.hasChildNodes ()

Return @code{True} if the node has any child nodes.
@end deffn

@geindex isSameNode() (μέθοδος της xml.dom.Node)
@anchor{library/xml dom xml dom Node isSameNode}@anchor{3fb3}
@deffn {Μέθοδος} Node.isSameNode (other)

Return @code{True} if `other' refers to the same node as this node. This is especially
useful for DOM implementations which use any sort of proxy architecture (because
more than one object can refer to the same node).

@cartouche
@quotation Σημείωση 
This is based on a proposed DOM Level 3 API which is still in the «working
draft» stage, but this particular interface appears uncontroversial.  Changes
from the W3C will not necessarily affect this method in the Python DOM interface
(though any new W3C API for this would also be supported).
@end quotation
@end cartouche
@end deffn

@geindex appendChild() (μέθοδος της xml.dom.Node)
@anchor{library/xml dom xml dom Node appendChild}@anchor{3fb4}
@deffn {Μέθοδος} Node.appendChild (newChild)

Add a new child node to this node at the end of the list of
children, returning `newChild'. If the node was already in
the tree, it is removed first.
@end deffn

@geindex insertBefore() (μέθοδος της xml.dom.Node)
@anchor{library/xml dom xml dom Node insertBefore}@anchor{3fb5}
@deffn {Μέθοδος} Node.insertBefore (newChild, refChild)

Insert a new child node before an existing child.  It must be the case that
`refChild' is a child of this node; if not, @ref{277,,ValueError} is raised.
`newChild' is returned. If `refChild' is @code{None}, it inserts `newChild' at the
end of the children’s list.
@end deffn

@geindex removeChild() (μέθοδος της xml.dom.Node)
@anchor{library/xml dom xml dom Node removeChild}@anchor{3fb6}
@deffn {Μέθοδος} Node.removeChild (oldChild)

Remove a child node.  `oldChild' must be a child of this node; if not,
@ref{277,,ValueError} is raised.  `oldChild' is returned on success.  If `oldChild'
will not be used further, its @code{unlink()} method should be called.
@end deffn

@geindex replaceChild() (μέθοδος της xml.dom.Node)
@anchor{library/xml dom xml dom Node replaceChild}@anchor{3fb7}
@deffn {Μέθοδος} Node.replaceChild (newChild, oldChild)

Replace an existing node with a new node. It must be the case that  `oldChild'
is a child of this node; if not, @ref{277,,ValueError} is raised.
@end deffn

@geindex normalize() (μέθοδος της xml.dom.Node)
@anchor{library/xml dom xml dom Node normalize}@anchor{3fb8}
@deffn {Μέθοδος} Node.normalize ()

Join adjacent text nodes so that all stretches of text are stored as single
@code{Text} instances.  This simplifies processing text from a DOM tree for
many applications.
@end deffn

@geindex cloneNode() (μέθοδος της xml.dom.Node)
@anchor{library/xml dom xml dom Node cloneNode}@anchor{3fb9}
@deffn {Μέθοδος} Node.cloneNode (deep)

Clone this node.  Setting `deep' means to clone all child nodes as well.  This
returns the clone.
@end deffn

@node NodeList Objects,DocumentType Objects,Node Objects,Objects in the DOM
@anchor{library/xml dom dom-nodelist-objects}@anchor{25a0}@anchor{library/xml dom nodelist-objects}@anchor{3fba}
@subsubsection NodeList Objects


A @code{NodeList} represents a sequence of nodes.  These objects are used in
two ways in the DOM Core recommendation:  an @code{Element} object provides
one as its list of child nodes, and the @code{getElementsByTagName()} and
@code{getElementsByTagNameNS()} methods of @code{Node} return objects with this
interface to represent query results.

The DOM Level 2 recommendation defines one method and one attribute for these
objects:

@geindex item() (μέθοδος της xml.dom.NodeList)
@anchor{library/xml dom xml dom NodeList item}@anchor{3fbb}
@deffn {Μέθοδος} NodeList.item (i)

Return the `i'’th item from the sequence, if there is one, or @code{None}.  The
index `i' is not allowed to be less than zero or greater than or equal to the
length of the sequence.
@end deffn

@geindex length (ιδιότητα της xml.dom.NodeList)
@anchor{library/xml dom xml dom NodeList length}@anchor{3fbc}
@deffn {Ιδιότητα} NodeList.length

The number of nodes in the sequence.
@end deffn

In addition, the Python DOM interface requires that some additional support is
provided to allow @code{NodeList} objects to be used as Python sequences.  All
@code{NodeList} implementations must include support for
@ref{1989,,__len__()} and
@ref{787,,__getitem__()}; this allows iteration over the @code{NodeList} in
@ref{321,,for} statements and proper support for the @ref{a1f,,len()} built-in
function.

If a DOM implementation supports modification of the document, the
@code{NodeList} implementation must also support the
@ref{1670,,__setitem__()} and @ref{1671,,__delitem__()} methods.

@node DocumentType Objects,Document Objects,NodeList Objects,Objects in the DOM
@anchor{library/xml dom documenttype-objects}@anchor{3fbd}@anchor{library/xml dom dom-documenttype-objects}@anchor{3f98}
@subsubsection DocumentType Objects


Information about the notations and entities declared by a document (including
the external subset if the parser uses it and can provide the information) is
available from a @code{DocumentType} object.  The @code{DocumentType} for a
document is available from the @code{Document} object’s @code{doctype}
attribute; if there is no @code{DOCTYPE} declaration for the document, the
document’s @code{doctype} attribute will be set to @code{None} instead of an
instance of this interface.

@code{DocumentType} is a specialization of @code{Node}, and adds the
following attributes:

@geindex publicId (ιδιότητα της xml.dom.DocumentType)
@anchor{library/xml dom xml dom DocumentType publicId}@anchor{3fbe}
@deffn {Ιδιότητα} DocumentType.publicId

The public identifier for the external subset of the document type definition.
This will be a string or @code{None}.
@end deffn

@geindex systemId (ιδιότητα της xml.dom.DocumentType)
@anchor{library/xml dom xml dom DocumentType systemId}@anchor{3fbf}
@deffn {Ιδιότητα} DocumentType.systemId

The system identifier for the external subset of the document type definition.
This will be a URI as a string, or @code{None}.
@end deffn

@geindex internalSubset (ιδιότητα της xml.dom.DocumentType)
@anchor{library/xml dom xml dom DocumentType internalSubset}@anchor{3fc0}
@deffn {Ιδιότητα} DocumentType.internalSubset

A string giving the complete internal subset from the document. This does not
include the brackets which enclose the subset.  If the document has no internal
subset, this should be @code{None}.
@end deffn

@geindex name (ιδιότητα της xml.dom.DocumentType)
@anchor{library/xml dom xml dom DocumentType name}@anchor{3fc1}
@deffn {Ιδιότητα} DocumentType.name

The name of the root element as given in the @code{DOCTYPE} declaration, if
present.
@end deffn

@geindex entities (ιδιότητα της xml.dom.DocumentType)
@anchor{library/xml dom xml dom DocumentType entities}@anchor{3fc2}
@deffn {Ιδιότητα} DocumentType.entities

This is a @code{NamedNodeMap} giving the definitions of external entities.
For entity names defined more than once, only the first definition is provided
(others are ignored as required by the XML recommendation).  This may be
@code{None} if the information is not provided by the parser, or if no entities are
defined.
@end deffn

@geindex notations (ιδιότητα της xml.dom.DocumentType)
@anchor{library/xml dom xml dom DocumentType notations}@anchor{3fc3}
@deffn {Ιδιότητα} DocumentType.notations

This is a @code{NamedNodeMap} giving the definitions of notations. For
notation names defined more than once, only the first definition is provided
(others are ignored as required by the XML recommendation).  This may be
@code{None} if the information is not provided by the parser, or if no notations
are defined.
@end deffn

@node Document Objects,Element Objects<2>,DocumentType Objects,Objects in the DOM
@anchor{library/xml dom document-objects}@anchor{3fc4}@anchor{library/xml dom dom-document-objects}@anchor{3f99}
@subsubsection Document Objects


A @code{Document} represents an entire XML document, including its constituent
elements, attributes, processing instructions, comments etc.  Remember that it
inherits properties from @code{Node}.

@geindex documentElement (ιδιότητα της xml.dom.Document)
@anchor{library/xml dom xml dom Document documentElement}@anchor{19a4}
@deffn {Ιδιότητα} Document.documentElement

The one and only root element of the document.
@end deffn

@geindex createElement() (μέθοδος της xml.dom.Document)
@anchor{library/xml dom xml dom Document createElement}@anchor{3fc5}
@deffn {Μέθοδος} Document.createElement (tagName)

Create and return a new element node.  The element is not inserted into the
document when it is created.  You need to explicitly insert it with one of the
other methods such as @code{insertBefore()} or @code{appendChild()}.
@end deffn

@geindex createElementNS() (μέθοδος της xml.dom.Document)
@anchor{library/xml dom xml dom Document createElementNS}@anchor{3fc6}
@deffn {Μέθοδος} Document.createElementNS (namespaceURI, tagName)

Create and return a new element with a namespace.  The `tagName' may have a
prefix.  The element is not inserted into the document when it is created.  You
need to explicitly insert it with one of the other methods such as
@code{insertBefore()} or @code{appendChild()}.
@end deffn

@geindex createTextNode() (μέθοδος της xml.dom.Document)
@anchor{library/xml dom xml dom Document createTextNode}@anchor{3fc7}
@deffn {Μέθοδος} Document.createTextNode (data)

Create and return a text node containing the data passed as a parameter.  As
with the other creation methods, this one does not insert the node into the
tree.
@end deffn

@geindex createComment() (μέθοδος της xml.dom.Document)
@anchor{library/xml dom xml dom Document createComment}@anchor{3fc8}
@deffn {Μέθοδος} Document.createComment (data)

Create and return a comment node containing the data passed as a parameter.  As
with the other creation methods, this one does not insert the node into the
tree.
@end deffn

@geindex createProcessingInstruction() (μέθοδος της xml.dom.Document)
@anchor{library/xml dom xml dom Document createProcessingInstruction}@anchor{3fc9}
@deffn {Μέθοδος} Document.createProcessingInstruction (target, data)

Create and return a processing instruction node containing the `target' and
`data' passed as parameters.  As with the other creation methods, this one does
not insert the node into the tree.
@end deffn

@geindex createAttribute() (μέθοδος της xml.dom.Document)
@anchor{library/xml dom xml dom Document createAttribute}@anchor{3fca}
@deffn {Μέθοδος} Document.createAttribute (name)

Create and return an attribute node.  This method does not associate the
attribute node with any particular element.  You must use
@code{setAttributeNode()} on the appropriate @code{Element} object to use the
newly created attribute instance.
@end deffn

@geindex createAttributeNS() (μέθοδος της xml.dom.Document)
@anchor{library/xml dom xml dom Document createAttributeNS}@anchor{3fcb}
@deffn {Μέθοδος} Document.createAttributeNS (namespaceURI, qualifiedName)

Create and return an attribute node with a namespace.  The `tagName' may have a
prefix.  This method does not associate the attribute node with any particular
element.  You must use @code{setAttributeNode()} on the appropriate
@code{Element} object to use the newly created attribute instance.
@end deffn

@geindex getElementsByTagName() (μέθοδος της xml.dom.Document)
@anchor{library/xml dom xml dom Document getElementsByTagName}@anchor{3fcc}
@deffn {Μέθοδος} Document.getElementsByTagName (tagName)

Search for all descendants (direct children, children’s children, etc.) with a
particular element type name.
@end deffn

@geindex getElementsByTagNameNS() (μέθοδος της xml.dom.Document)
@anchor{library/xml dom xml dom Document getElementsByTagNameNS}@anchor{3fcd}
@deffn {Μέθοδος} Document.getElementsByTagNameNS (namespaceURI, localName)

Search for all descendants (direct children, children’s children, etc.) with a
particular namespace URI and localname.  The localname is the part of the
namespace after the prefix.
@end deffn

@node Element Objects<2>,Attr Objects,Document Objects,Objects in the DOM
@anchor{library/xml dom dom-element-objects}@anchor{3f9a}@anchor{library/xml dom element-objects}@anchor{3fce}
@subsubsection Element Objects


@code{Element} is a subclass of @code{Node}, so inherits all the attributes
of that class.

@geindex tagName (ιδιότητα της xml.dom.Element)
@anchor{library/xml dom xml dom Element tagName}@anchor{3fcf}
@deffn {Ιδιότητα} Element.tagName

The element type name.  In a namespace-using document it may have colons in it.
The value is a string.
@end deffn

@geindex getElementsByTagName() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element getElementsByTagName}@anchor{3fd0}
@deffn {Μέθοδος} Element.getElementsByTagName (tagName)

Same as equivalent method in the @code{Document} class.
@end deffn

@geindex getElementsByTagNameNS() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element getElementsByTagNameNS}@anchor{3fd1}
@deffn {Μέθοδος} Element.getElementsByTagNameNS (namespaceURI, localName)

Same as equivalent method in the @code{Document} class.
@end deffn

@geindex hasAttribute() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element hasAttribute}@anchor{3fd2}
@deffn {Μέθοδος} Element.hasAttribute (name)

Return @code{True} if the element has an attribute named by `name'.
@end deffn

@geindex hasAttributeNS() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element hasAttributeNS}@anchor{3fd3}
@deffn {Μέθοδος} Element.hasAttributeNS (namespaceURI, localName)

Return @code{True} if the element has an attribute named by `namespaceURI' and
`localName'.
@end deffn

@geindex getAttribute() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element getAttribute}@anchor{3fd4}
@deffn {Μέθοδος} Element.getAttribute (name)

Return the value of the attribute named by `name' as a string. If no such
attribute exists, an empty string is returned, as if the attribute had no value.
@end deffn

@geindex getAttributeNode() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element getAttributeNode}@anchor{3fd5}
@deffn {Μέθοδος} Element.getAttributeNode (attrname)

Return the @code{Attr} node for the attribute named by `attrname'.
@end deffn

@geindex getAttributeNS() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element getAttributeNS}@anchor{3fd6}
@deffn {Μέθοδος} Element.getAttributeNS (namespaceURI, localName)

Return the value of the attribute named by `namespaceURI' and `localName' as a
string. If no such attribute exists, an empty string is returned, as if the
attribute had no value.
@end deffn

@geindex getAttributeNodeNS() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element getAttributeNodeNS}@anchor{3fd7}
@deffn {Μέθοδος} Element.getAttributeNodeNS (namespaceURI, localName)

Return an attribute value as a node, given a `namespaceURI' and `localName'.
@end deffn

@geindex removeAttribute() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element removeAttribute}@anchor{3fd8}
@deffn {Μέθοδος} Element.removeAttribute (name)

Remove an attribute by name.  If there is no matching attribute, a
@ref{3fd9,,NotFoundErr} is raised.
@end deffn

@geindex removeAttributeNode() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element removeAttributeNode}@anchor{3fda}
@deffn {Μέθοδος} Element.removeAttributeNode (oldAttr)

Remove and return `oldAttr' from the attribute list, if present. If `oldAttr' is
not present, @ref{3fd9,,NotFoundErr} is raised.
@end deffn

@geindex removeAttributeNS() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element removeAttributeNS}@anchor{3fdb}
@deffn {Μέθοδος} Element.removeAttributeNS (namespaceURI, localName)

Remove an attribute by name.  Note that it uses a localName, not a qname.  No
exception is raised if there is no matching attribute.
@end deffn

@geindex setAttribute() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element setAttribute}@anchor{3fdc}
@deffn {Μέθοδος} Element.setAttribute (name, value)

Set an attribute value from a string.
@end deffn

@geindex setAttributeNode() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element setAttributeNode}@anchor{3fdd}
@deffn {Μέθοδος} Element.setAttributeNode (newAttr)

Add a new attribute node to the element, replacing an existing attribute if
necessary if the @code{name} attribute matches.  If a replacement occurs, the
old attribute node will be returned.  If `newAttr' is already in use,
@ref{3fde,,InuseAttributeErr} will be raised.
@end deffn

@geindex setAttributeNodeNS() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element setAttributeNodeNS}@anchor{3fdf}
@deffn {Μέθοδος} Element.setAttributeNodeNS (newAttr)

Add a new attribute node to the element, replacing an existing attribute if
necessary if the @code{namespaceURI} and @code{localName} attributes match.
If a replacement occurs, the old attribute node will be returned.  If `newAttr'
is already in use, @ref{3fde,,InuseAttributeErr} will be raised.
@end deffn

@geindex setAttributeNS() (μέθοδος της xml.dom.Element)
@anchor{library/xml dom xml dom Element setAttributeNS}@anchor{3fe0}
@deffn {Μέθοδος} Element.setAttributeNS (namespaceURI, qname, value)

Set an attribute value from a string, given a `namespaceURI' and a `qname'.
Note that a qname is the whole attribute name.  This is different than above.
@end deffn

@node Attr Objects,NamedNodeMap Objects,Element Objects<2>,Objects in the DOM
@anchor{library/xml dom attr-objects}@anchor{3fe1}@anchor{library/xml dom dom-attr-objects}@anchor{3f9b}
@subsubsection Attr Objects


@code{Attr} inherits from @code{Node}, so inherits all its attributes.

@geindex name (ιδιότητα της xml.dom.Attr)
@anchor{library/xml dom xml dom Attr name}@anchor{3fe2}
@deffn {Ιδιότητα} Attr.name

The attribute name.
In a namespace-using document it may include a colon.
@end deffn

@geindex localName (ιδιότητα της xml.dom.Attr)
@anchor{library/xml dom xml dom Attr localName}@anchor{3fe3}
@deffn {Ιδιότητα} Attr.localName

The part of the name following the colon if there is one, else the
entire name.
This is a read-only attribute.
@end deffn

@geindex prefix (ιδιότητα της xml.dom.Attr)
@anchor{library/xml dom xml dom Attr prefix}@anchor{3fe4}
@deffn {Ιδιότητα} Attr.prefix

The part of the name preceding the colon if there is one, else the
empty string.
@end deffn

@geindex value (ιδιότητα της xml.dom.Attr)
@anchor{library/xml dom xml dom Attr value}@anchor{3fe5}
@deffn {Ιδιότητα} Attr.value

The text value of the attribute.  This is a synonym for the
@code{nodeValue} attribute.
@end deffn

@node NamedNodeMap Objects,Comment Objects,Attr Objects,Objects in the DOM
@anchor{library/xml dom dom-attributelist-objects}@anchor{3fe6}@anchor{library/xml dom namednodemap-objects}@anchor{3fe7}
@subsubsection NamedNodeMap Objects


@code{NamedNodeMap} does `not' inherit from @code{Node}.

@geindex length (ιδιότητα της xml.dom.NamedNodeMap)
@anchor{library/xml dom xml dom NamedNodeMap length}@anchor{3fe8}
@deffn {Ιδιότητα} NamedNodeMap.length

The length of the attribute list.
@end deffn

@geindex item() (μέθοδος της xml.dom.NamedNodeMap)
@anchor{library/xml dom xml dom NamedNodeMap item}@anchor{3fe9}
@deffn {Μέθοδος} NamedNodeMap.item (index)

Return an attribute with a particular index.  The order you get the attributes
in is arbitrary but will be consistent for the life of a DOM.  Each item is an
attribute node.  Get its value with the @code{value} attribute.
@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 Comment Objects,Text and CDATASection Objects,NamedNodeMap Objects,Objects in the DOM
@anchor{library/xml dom comment-objects}@anchor{3fea}@anchor{library/xml dom dom-comment-objects}@anchor{3f9c}
@subsubsection Comment Objects


@code{Comment} represents a comment in the XML document.  It is a subclass of
@code{Node}, but cannot have child nodes.

@geindex data (ιδιότητα της xml.dom.Comment)
@anchor{library/xml dom xml dom Comment data}@anchor{3feb}
@deffn {Ιδιότητα} Comment.data

The content of the comment as a string.  The attribute contains all characters
between the leading @code{<!-}@code{-} and trailing @code{-}@code{->}, but does not
include them.
@end deffn

@node Text and CDATASection Objects,ProcessingInstruction Objects,Comment Objects,Objects in the DOM
@anchor{library/xml dom dom-text-objects}@anchor{3f9d}@anchor{library/xml dom text-and-cdatasection-objects}@anchor{3fec}
@subsubsection Text and CDATASection Objects


The @code{Text} interface represents text in the XML document.  If the parser
and DOM implementation support the DOM’s XML extension, portions of the text
enclosed in CDATA marked sections are stored in @code{CDATASection} objects.
These two interfaces are identical, but provide different values for the
@code{nodeType} attribute.

These interfaces extend the @code{Node} interface.  They cannot have child
nodes.

@geindex data (ιδιότητα της xml.dom.Text)
@anchor{library/xml dom xml dom Text data}@anchor{3fed}
@deffn {Ιδιότητα} Text.data

The content of the text node as a string.
@end deffn

@cartouche
@quotation Σημείωση 
The use of a @code{CDATASection} node does not indicate that the node
represents a complete CDATA marked section, only that the content of the node
was part of a CDATA section.  A single CDATA section may be represented by more
than one node in the document tree.  There is no way to determine whether two
adjacent @code{CDATASection} nodes represent different CDATA marked sections.
@end quotation
@end cartouche

@node ProcessingInstruction Objects,Exceptions<21>,Text and CDATASection Objects,Objects in the DOM
@anchor{library/xml dom dom-pi-objects}@anchor{3f9e}@anchor{library/xml dom processinginstruction-objects}@anchor{3fee}
@subsubsection ProcessingInstruction Objects


Represents a processing instruction in the XML document; this inherits from the
@code{Node} interface and cannot have child nodes.

@geindex target (ιδιότητα της xml.dom.ProcessingInstruction)
@anchor{library/xml dom xml dom ProcessingInstruction target}@anchor{3fef}
@deffn {Ιδιότητα} ProcessingInstruction.target

The content of the processing instruction up to the first whitespace character.
This is a read-only attribute.
@end deffn

@geindex data (ιδιότητα της xml.dom.ProcessingInstruction)
@anchor{library/xml dom xml dom ProcessingInstruction data}@anchor{3ff0}
@deffn {Ιδιότητα} ProcessingInstruction.data

The content of the processing instruction following the first whitespace
character.
@end deffn

@node Exceptions<21>,,ProcessingInstruction Objects,Objects in the DOM
@anchor{library/xml dom dom-exceptions}@anchor{3ff1}@anchor{library/xml dom exceptions}@anchor{3ff2}
@subsubsection Exceptions


The DOM Level 2 recommendation defines a single exception, @ref{3ff3,,DOMException},
and a number of constants that allow applications to determine what sort of
error occurred. @code{DOMException} instances carry a @ref{1b,,code} attribute
that provides the appropriate value for the specific exception.

The Python DOM interface provides the constants, but also expands the set of
exceptions so that a specific exception exists for each of the exception codes
defined by the DOM.  The implementations must raise the appropriate specific
exception, each of which carries the appropriate value for the @ref{1b,,code}
attribute.

@geindex DOMException
@anchor{library/xml dom xml dom DOMException}@anchor{3ff3}
@deffn {Εξαίρεση} xml.dom.DOMException

Base exception class used for all specific DOM exceptions.  This exception class
cannot be directly instantiated.
@end deffn

@geindex DomstringSizeErr
@anchor{library/xml dom xml dom DomstringSizeErr}@anchor{3ff4}
@deffn {Εξαίρεση} xml.dom.DomstringSizeErr

Raised when a specified range of text does not fit into a string. This is not
known to be used in the Python DOM implementations, but may be received from DOM
implementations not written in Python.
@end deffn

@geindex HierarchyRequestErr
@anchor{library/xml dom xml dom HierarchyRequestErr}@anchor{3ff5}
@deffn {Εξαίρεση} xml.dom.HierarchyRequestErr

Raised when an attempt is made to insert a node where the node type is not
allowed.
@end deffn

@geindex IndexSizeErr
@anchor{library/xml dom xml dom IndexSizeErr}@anchor{3ff6}
@deffn {Εξαίρεση} xml.dom.IndexSizeErr

Raised when an index or size parameter to a method is negative or exceeds the
allowed values.
@end deffn

@geindex InuseAttributeErr
@anchor{library/xml dom xml dom InuseAttributeErr}@anchor{3fde}
@deffn {Εξαίρεση} xml.dom.InuseAttributeErr

Raised when an attempt is made to insert an @code{Attr} node that is already
present elsewhere in the document.
@end deffn

@geindex InvalidAccessErr
@anchor{library/xml dom xml dom InvalidAccessErr}@anchor{3ff7}
@deffn {Εξαίρεση} xml.dom.InvalidAccessErr

Raised if a parameter or an operation is not supported on the underlying object.
@end deffn

@geindex InvalidCharacterErr
@anchor{library/xml dom xml dom InvalidCharacterErr}@anchor{3ff8}
@deffn {Εξαίρεση} xml.dom.InvalidCharacterErr

This exception is raised when a string parameter contains a character that is
not permitted in the context it’s being used in by the XML 1.0 recommendation.
For example, attempting to create an @code{Element} node with a space in the
element type name will cause this error to be raised.
@end deffn

@geindex InvalidModificationErr
@anchor{library/xml dom xml dom InvalidModificationErr}@anchor{3ff9}
@deffn {Εξαίρεση} xml.dom.InvalidModificationErr

Raised when an attempt is made to modify the type of a node.
@end deffn

@geindex InvalidStateErr
@anchor{library/xml dom xml dom InvalidStateErr}@anchor{3ffa}
@deffn {Εξαίρεση} xml.dom.InvalidStateErr

Raised when an attempt is made to use an object that is not defined or is no
longer usable.
@end deffn

@geindex NamespaceErr
@anchor{library/xml dom xml dom NamespaceErr}@anchor{3ffb}
@deffn {Εξαίρεση} xml.dom.NamespaceErr

If an attempt is made to change any object in a way that is not permitted with
regard to the Namespaces in XML@footnote{https://www.w3.org/TR/REC-xml-names/}
recommendation, this exception is raised.
@end deffn

@geindex NotFoundErr
@anchor{library/xml dom xml dom NotFoundErr}@anchor{3fd9}
@deffn {Εξαίρεση} xml.dom.NotFoundErr

Exception when a node does not exist in the referenced context.  For example,
@code{NamedNodeMap.removeNamedItem()} will raise this if the node passed in does
not exist in the map.
@end deffn

@geindex NotSupportedErr
@anchor{library/xml dom xml dom NotSupportedErr}@anchor{3ffc}
@deffn {Εξαίρεση} xml.dom.NotSupportedErr

Raised when the implementation does not support the requested type of object or
operation.
@end deffn

@geindex NoDataAllowedErr
@anchor{library/xml dom xml dom NoDataAllowedErr}@anchor{3ffd}
@deffn {Εξαίρεση} xml.dom.NoDataAllowedErr

This is raised if data is specified for a node which does not support data.

@c XXX  a better explanation is needed!
@end deffn

@geindex NoModificationAllowedErr
@anchor{library/xml dom xml dom NoModificationAllowedErr}@anchor{3ffe}
@deffn {Εξαίρεση} xml.dom.NoModificationAllowedErr

Raised on attempts to modify an object where modifications are not allowed (such
as for read-only nodes).
@end deffn

@geindex SyntaxErr
@anchor{library/xml dom xml dom SyntaxErr}@anchor{3fff}
@deffn {Εξαίρεση} xml.dom.SyntaxErr

Raised when an invalid or illegal string is specified.

@c XXX  how is this different from InvalidCharacterErr?
@end deffn

@geindex WrongDocumentErr
@anchor{library/xml dom xml dom WrongDocumentErr}@anchor{4000}
@deffn {Εξαίρεση} xml.dom.WrongDocumentErr

Raised when a node is inserted in a different document than it currently belongs
to, and the implementation does not support migrating the node from one document
to the other.
@end deffn

The exception codes defined in the DOM recommendation map to the exceptions
described above according to this table:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constant

@tab

Exception

@item

@code{DOMSTRING_SIZE_ERR}

@tab

@ref{3ff4,,DomstringSizeErr}

@item

@code{HIERARCHY_REQUEST_ERR}

@tab

@ref{3ff5,,HierarchyRequestErr}

@item

@code{INDEX_SIZE_ERR}

@tab

@ref{3ff6,,IndexSizeErr}

@item

@code{INUSE_ATTRIBUTE_ERR}

@tab

@ref{3fde,,InuseAttributeErr}

@item

@code{INVALID_ACCESS_ERR}

@tab

@ref{3ff7,,InvalidAccessErr}

@item

@code{INVALID_CHARACTER_ERR}

@tab

@ref{3ff8,,InvalidCharacterErr}

@item

@code{INVALID_MODIFICATION_ERR}

@tab

@ref{3ff9,,InvalidModificationErr}

@item

@code{INVALID_STATE_ERR}

@tab

@ref{3ffa,,InvalidStateErr}

@item

@code{NAMESPACE_ERR}

@tab

@ref{3ffb,,NamespaceErr}

@item

@code{NOT_FOUND_ERR}

@tab

@ref{3fd9,,NotFoundErr}

@item

@code{NOT_SUPPORTED_ERR}

@tab

@ref{3ffc,,NotSupportedErr}

@item

@code{NO_DATA_ALLOWED_ERR}

@tab

@ref{3ffd,,NoDataAllowedErr}

@item

@code{NO_MODIFICATION_ALLOWED_ERR}

@tab

@ref{3ffe,,NoModificationAllowedErr}

@item

@code{SYNTAX_ERR}

@tab

@ref{3fff,,SyntaxErr}

@item

@code{WRONG_DOCUMENT_ERR}

@tab

@ref{4000,,WrongDocumentErr}

@end multitable


@node Conformance,,Objects in the DOM,xml dom — The Document Object Model API
@anchor{library/xml dom conformance}@anchor{4001}@anchor{library/xml dom dom-conformance}@anchor{3f8d}
@subsubsection Conformance


This section describes the conformance requirements and relationships between
the Python DOM API, the W3C DOM recommendations, and the OMG IDL mapping for
Python.

@menu
* Type Mapping:: 
* Accessor Methods:: 

@end menu

@node Type Mapping,Accessor Methods,,Conformance
@anchor{library/xml dom dom-type-mapping}@anchor{4002}@anchor{library/xml dom type-mapping}@anchor{4003}
@subsubsection Type Mapping


The IDL types used in the DOM specification are mapped to Python types
according to the following table.


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

IDL Type

@tab

Python Type

@item

@code{boolean}

@tab

@code{bool} or @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 Accessor Methods,,Type Mapping,Conformance
@anchor{library/xml dom accessor-methods}@anchor{4004}@anchor{library/xml dom dom-accessor-methods}@anchor{4005}
@subsubsection Accessor Methods


The mapping from OMG IDL to Python defines accessor functions for IDL
@code{attribute} declarations in much the way the Java mapping does.
Mapping the IDL declarations

@example
readonly attribute string someValue;
         attribute string anotherValue;
@end example

yields three accessor functions:  a «get» method for @code{someValue}
(@code{_get_someValue()}), and «get» and «set» methods for @code{anotherValue}
(@code{_get_anotherValue()} and @code{_set_anotherValue()}).  The mapping, in
particular, does not require that the IDL attributes are accessible as normal
Python attributes:  @code{object.someValue} is `not' required to work, and may
raise an @ref{1a9,,AttributeError}.

The Python DOM API, however, `does' require that normal attribute access work.
This means that the typical surrogates generated by Python IDL compilers are not
likely to work, and wrapper objects may be needed on the client if the DOM
objects are accessed via CORBA. While this does require some additional
consideration for CORBA DOM clients, the implementers with experience using DOM
over CORBA from Python do not consider this a problem.  Attributes that are
declared @code{readonly} may not restrict write access in all DOM
implementations.

In the Python DOM API, accessor functions are not required.  If provided, they
should take the form defined by the Python IDL mapping, but these methods are
considered unnecessary since the attributes are accessible directly from Python.
«Set» accessors should never be provided for @code{readonly} attributes.

The IDL definitions do not fully embody the requirements of the W3C DOM API,
such as the notion of certain objects, such as the return value of
@code{getElementsByTagName()}, being «live».  The Python DOM API does not require
implementations to enforce such requirements.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xml dom minidom — Minimal DOM implementation,xml dom pulldom — Support for building partial DOM trees,xml dom — The Document Object Model API,Structured Markup Processing Tools
@anchor{library/xml dom minidom doc}@anchor{4006}@anchor{library/xml dom minidom module-xml dom minidom}@anchor{12b}@anchor{library/xml dom minidom translation-repo}@anchor{4007}@anchor{library/xml dom minidom xml-dom-minidom-minimal-dom-implementation}@anchor{4008}
@subsection @code{xml.dom.minidom} — Minimal DOM implementation


@geindex module; xml.dom.minidom

`Source code:' Lib/xml/dom/minidom.py@footnote{https://github.com/python/cpython/tree/main/Lib/xml/dom/minidom.py}


__________________________________________________________________


@code{xml.dom.minidom} is a minimal implementation of the Document Object
Model interface, with an API similar to that in other languages.  It is intended
to be simpler than the full DOM and also significantly smaller.  Users who are
not already proficient with the DOM should consider using the
@ref{12e,,xml.etree.ElementTree} module for their XML processing instead.

@cartouche
@quotation Σημείωση 
If you need to parse untrusted or unauthenticated data, see
@ref{3f34,,XML security}.
@end quotation
@end cartouche

DOM applications typically start by parsing some XML into a DOM.  With
@code{xml.dom.minidom}, this is done through the parse functions:

@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

The @ref{4009,,parse()} function can take either a filename or an open file object.

@geindex parse() (στη μονάδα xml.dom.minidom)
@anchor{library/xml dom minidom xml dom minidom parse}@anchor{4009}
@deffn {Συνάρτηση} xml.dom.minidom.parse (filename_or_file, parser=None, bufsize=None)

Return a @code{Document} from the given input. `filename_or_file' may be
either a file name, or a file-like object. `parser', if given, must be a SAX2
parser object. This function will change the document handler of the parser and
activate namespace support; other parser configuration (like setting an entity
resolver) must have been done in advance.
@end deffn

If you have XML in a string, you can use the @ref{400a,,parseString()} function
instead:

@geindex parseString() (στη μονάδα xml.dom.minidom)
@anchor{library/xml dom minidom xml dom minidom parseString}@anchor{400a}
@deffn {Συνάρτηση} xml.dom.minidom.parseString (string, parser=None)

Return a @code{Document} that represents the `string'. This method creates an
@ref{12d4,,io.StringIO} object for the string and passes that on to @ref{4009,,parse()}.
@end deffn

Both functions return a @code{Document} object representing the content of the
document.

What the @ref{4009,,parse()} and @ref{400a,,parseString()} functions do is connect an XML
parser with a «DOM builder» that can accept parse events from any SAX parser and
convert them into a DOM tree.  The names of the functions are perhaps misleading,
but are easy to grasp when learning the interfaces.  The parsing of the document
will be completed before these functions return; it’s simply that these
functions do not provide a parser implementation themselves.

You can also create a @code{Document} by calling a method on a «DOM
Implementation» object.  You can get this object either by calling the
@code{getDOMImplementation()} function in the @ref{12a,,xml.dom} package or the
@code{xml.dom.minidom} module.  Once you have a @code{Document}, you
can add child nodes to it to populate the 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

Once you have a DOM document object, you can access the parts of your XML
document through its properties and methods.  These properties are defined in
the DOM specification.  The main property of the document object is the
@code{documentElement} property.  It gives you the main element in the XML
document: the one that holds all others.  Here is an example program:

@example
dom3 = parseString("<myxml>Some data</myxml>")
assert dom3.documentElement.tagName == "myxml"
@end example

When you are finished with a DOM tree, you may optionally call the
@code{unlink()} method to encourage early cleanup of the now-unneeded
objects.  @code{unlink()} is an @code{xml.dom.minidom}-specific
extension to the DOM API that renders the node and its descendants
essentially useless.  Otherwise, Python’s garbage collector will
eventually take care of the objects in the tree.


@subsubheading Δείτε επίσης



@table @asis

@item Document Object Model (DOM) Level 1 Specification@footnote{https://www.w3.org/TR/REC-DOM-Level-1/}

The W3C recommendation for the DOM supported by @code{xml.dom.minidom}.
@end table


@menu
* DOM Objects:: 
* DOM Example:: 
* minidom and the DOM standard:: 

@end menu

@node DOM Objects,DOM Example,,xml dom minidom — Minimal DOM implementation
@anchor{library/xml dom minidom dom-objects}@anchor{400b}@anchor{library/xml dom minidom minidom-objects}@anchor{400c}
@subsubsection DOM Objects


The definition of the DOM API for Python is given as part of the @ref{12a,,xml.dom}
module documentation.  This section lists the differences between the API and
@code{xml.dom.minidom}.

@geindex unlink() (μέθοδος της xml.dom.minidom.Node)
@anchor{library/xml dom minidom xml dom minidom Node unlink}@anchor{400d}
@deffn {Μέθοδος} Node.unlink ()

Break internal references within the DOM so that it will be garbage collected on
versions of Python without cyclic GC.  Even when cyclic GC is available, using
this can make large amounts of memory available sooner, so calling this on DOM
objects as soon as they are no longer needed is good practice.  This only needs
to be called on the @code{Document} object, but may be called on child nodes
to discard children of that node.

You can avoid calling this method explicitly by using the @ref{20a,,with}
statement. The following code will automatically unlink `dom' when the
@code{with} block is exited:

@example
with xml.dom.minidom.parse(datasource) as dom:
    ... # Work with dom.
@end example
@end deffn

@geindex writexml() (μέθοδος της xml.dom.minidom.Node)
@anchor{library/xml dom minidom xml dom minidom Node writexml}@anchor{e58}
@deffn {Μέθοδος} Node.writexml (writer, indent='@w{'}, addindent='@w{'}, newl='@w{'}, encoding=None, standalone=None)

Write XML to the writer object.  The writer receives texts but not bytes as input,
it should have a @code{write()} method which matches that of the file object
interface.  The `indent' parameter is the indentation of the current node.
The `addindent' parameter is the incremental indentation to use for subnodes
of the current one.  The `newl' parameter specifies the string to use to
terminate newlines.

For the @code{Document} node, an additional keyword argument `encoding' can
be used to specify the encoding field of the XML header.

Similarly, explicitly stating the `standalone' argument causes the
standalone document declarations to be added to the prologue of the XML
document.
If the value is set to @code{True}, @code{standalone="yes"} is added,
otherwise it is set to @code{"no"}.
Not stating the argument will omit the declaration from the document.


Άλλαξε στην έκδοση 3.8: The @code{writexml()} method now preserves the attribute order specified
by the user.



Άλλαξε στην έκδοση 3.9: The `standalone' parameter was added.

@end deffn

@geindex toxml() (μέθοδος της xml.dom.minidom.Node)
@anchor{library/xml dom minidom xml dom minidom Node toxml}@anchor{e59}
@deffn {Μέθοδος} Node.toxml (encoding=None, standalone=None)

Return a string or byte string containing the XML represented by
the DOM node.

With an explicit `encoding' @footnote{
The encoding name included in the XML output should conform to
the appropriate standards. For example, «UTF-8» is valid, but
«UTF8» is not valid in an XML document’s declaration, even though
Python accepts it as an encoding name.
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}.
} argument, the result is a byte
string in the specified encoding.
With no `encoding' argument, the result is a Unicode string, and the
XML declaration in the resulting string does not specify an
encoding. Encoding this string in an encoding other than UTF-8 is
likely incorrect, since UTF-8 is the default encoding of XML.

The `standalone' argument behaves exactly as in @ref{e58,,writexml()}.


Άλλαξε στην έκδοση 3.8: The @code{toxml()} method now preserves the attribute order specified
by the user.



Άλλαξε στην έκδοση 3.9: The `standalone' parameter was added.

@end deffn

@geindex toprettyxml() (μέθοδος της xml.dom.minidom.Node)
@anchor{library/xml dom minidom xml dom minidom Node toprettyxml}@anchor{e5a}
@deffn {Μέθοδος} Node.toprettyxml (indent='\t', newl='\n', encoding=None, standalone=None)

Return a pretty-printed version of the document. `indent' specifies the
indentation string and defaults to a tabulator; `newl' specifies the string
emitted at the end of each line and defaults to @code{\n}.

The `encoding' argument behaves like the corresponding argument of
@ref{e59,,toxml()}.

The `standalone' argument behaves exactly as in @ref{e58,,writexml()}.


Άλλαξε στην έκδοση 3.8: The @code{toprettyxml()} method now preserves the attribute order specified
by the user.



Άλλαξε στην έκδοση 3.9: The `standalone' parameter was added.

@end deffn

@node DOM Example,minidom and the DOM standard,DOM Objects,xml dom minidom — Minimal DOM implementation
@anchor{library/xml dom minidom dom-example}@anchor{400e}@anchor{library/xml dom minidom id2}@anchor{400f}
@subsubsection DOM Example


This example program is a fairly realistic example of a simple program. In this
particular case, we do not take much advantage of the flexibility of the 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 and the DOM standard,,DOM Example,xml dom minidom — Minimal DOM implementation
@anchor{library/xml dom minidom minidom-and-dom}@anchor{4010}@anchor{library/xml dom minidom minidom-and-the-dom-standard}@anchor{4011}
@subsubsection minidom and the DOM standard


The @code{xml.dom.minidom} module is essentially a DOM 1.0-compatible DOM with
some DOM 2 features (primarily namespace features).

Usage of the DOM interface in Python is straight-forward.  The following mapping
rules apply:


@itemize *

@item 
Interfaces are accessed through instance objects. Applications should not
instantiate the classes themselves; they should use the creator functions
available on the @code{Document} object. Derived interfaces support all
operations (and attributes) from the base interfaces, plus any new operations.

@item 
Operations are used as methods. Since the DOM uses only @ref{323,,in}
parameters, the arguments are passed in normal order (from left to right).
There are no optional arguments. @code{void} operations return @code{None}.

@item 
IDL attributes map to instance attributes. For compatibility with the OMG IDL
language mapping for Python, an attribute @code{foo} can also be accessed through
accessor methods @code{_get_foo()} and @code{_set_foo()}.  @code{readonly}
attributes must not be changed; this is not enforced at runtime.

@item 
The types @code{short int}, @code{unsigned int}, @code{unsigned long long}, and
@code{boolean} all map to Python integer objects.

@item 
The type @code{DOMString} maps to Python strings. @code{xml.dom.minidom} supports
either bytes or strings, but will normally produce strings.
Values of type @code{DOMString} may also be @code{None} where allowed to have the IDL
@code{null} value by the DOM specification from the W3C.

@item 
@code{const} declarations map to variables in their respective scope (e.g.
@code{xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE}); they must not be changed.

@item 
@code{DOMException} is currently not supported in @code{xml.dom.minidom}.
Instead, @code{xml.dom.minidom} uses standard Python exceptions such as
@ref{291,,TypeError} and @ref{1a9,,AttributeError}.

@item 
@code{NodeList} objects are implemented using Python’s built-in list type.
These objects provide the interface defined in the DOM specification, but with
earlier versions of Python they do not support the official API.  They are,
however, much more «Pythonic» than the interface defined in the W3C
recommendations.
@end itemize

The following interfaces have no implementation in @code{xml.dom.minidom}:


@itemize *

@item 
@code{DOMTimeStamp}

@item 
@code{EntityReference}
@end itemize

Most of these reflect information in the XML document that is not of general
utility to most DOM users.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xml dom pulldom — Support for building partial DOM trees,xml sax — Support for SAX2 parsers,xml dom minidom — Minimal DOM implementation,Structured Markup Processing Tools
@anchor{library/xml dom pulldom doc}@anchor{4012}@anchor{library/xml dom pulldom module-xml dom pulldom}@anchor{12c}@anchor{library/xml dom pulldom translation-repo}@anchor{4013}@anchor{library/xml dom pulldom xml-dom-pulldom-support-for-building-partial-dom-trees}@anchor{4014}
@subsection @code{xml.dom.pulldom} — Support for building partial DOM trees


@geindex module; xml.dom.pulldom

`Source code:' Lib/xml/dom/pulldom.py@footnote{https://github.com/python/cpython/tree/main/Lib/xml/dom/pulldom.py}


__________________________________________________________________


The @code{xml.dom.pulldom} module provides a «pull parser» which can also be
asked to produce DOM-accessible fragments of the document where necessary. The
basic concept involves pulling «events» from a stream of incoming XML and
processing them. In contrast to SAX which also employs an event-driven
processing model together with callbacks, the user of a pull parser is
responsible for explicitly pulling events from the stream, looping over those
events until either processing is finished or an error condition occurs.

@cartouche
@quotation Σημείωση 
If you need to parse untrusted or unauthenticated data, see
@ref{3f34,,XML security}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.7.1: The SAX parser no longer processes general external entities by default to
increase security by default. To enable processing of external entities,
pass a custom parser instance in:

@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


Example:

@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} is a constant and can be one of:


@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} is an object of type @code{xml.dom.minidom.Document},
@code{xml.dom.minidom.Element} or @code{xml.dom.minidom.Text}.

Since the document is treated as a «flat» stream of events, the document «tree»
is implicitly traversed and the desired elements are found regardless of their
depth in the tree. In other words, one does not need to consider hierarchical
issues such as recursive searching of the document nodes, although if the
context of elements were important, one would either need to maintain some
context-related state (i.e. remembering where one is in the document at any
given point) or to make use of the @ref{4015,,DOMEventStream.expandNode()} method
and switch to DOM-related processing.

@geindex PullDOM (κλάση σε xml.dom.pulldom)
@anchor{library/xml dom pulldom xml dom pulldom PullDOM}@anchor{4016}
@deffn {Κλάση} xml.dom.pulldom.PullDOM (documentFactory=None)

Subclass of @ref{4017,,xml.sax.handler.ContentHandler}.
@end deffn

@geindex SAX2DOM (κλάση σε xml.dom.pulldom)
@anchor{library/xml dom pulldom xml dom pulldom SAX2DOM}@anchor{4018}
@deffn {Κλάση} xml.dom.pulldom.SAX2DOM (documentFactory=None)

Subclass of @ref{4017,,xml.sax.handler.ContentHandler}.
@end deffn

@geindex parse() (στη μονάδα xml.dom.pulldom)
@anchor{library/xml dom pulldom xml dom pulldom parse}@anchor{4019}
@deffn {Συνάρτηση} xml.dom.pulldom.parse (stream_or_string, parser=None, bufsize=None)

Return a @ref{b1c,,DOMEventStream} from the given input. `stream_or_string' may be
either a file name, or a file-like object. `parser', if given, must be an
@ref{401a,,XMLReader} object. This function will change the
document handler of the
parser and activate namespace support; other parser configuration (like
setting an entity resolver) must have been done in advance.
@end deffn

If you have XML in a string, you can use the @ref{401b,,parseString()} function instead:

@geindex parseString() (στη μονάδα xml.dom.pulldom)
@anchor{library/xml dom pulldom xml dom pulldom parseString}@anchor{401b}
@deffn {Συνάρτηση} xml.dom.pulldom.parseString (string, parser=None)

Return a @ref{b1c,,DOMEventStream} that represents the (Unicode) `string'.
@end deffn

@geindex default_bufsize (στη μονάδα xml.dom.pulldom)
@anchor{library/xml dom pulldom xml dom pulldom default_bufsize}@anchor{401c}
@deffn {Δεδομένα} xml.dom.pulldom.default_bufsize

Default value for the `bufsize' parameter to @ref{4019,,parse()}.

The value of this variable can be changed before calling @ref{4019,,parse()} and
the new value will take effect.
@end deffn

@menu
* DOMEventStream Objects:: 

@end menu

@node DOMEventStream Objects,,,xml dom pulldom — Support for building partial DOM trees
@anchor{library/xml dom pulldom domeventstream-objects}@anchor{401d}@anchor{library/xml dom pulldom id1}@anchor{401e}
@subsubsection DOMEventStream Objects


@geindex DOMEventStream (κλάση σε xml.dom.pulldom)
@anchor{library/xml dom pulldom xml dom pulldom DOMEventStream}@anchor{b1c}
@deffn {Κλάση} xml.dom.pulldom.DOMEventStream (stream, parser, bufsize)


Άλλαξε στην έκδοση 3.11: Support for @ref{787,,__getitem__()} method has been removed.


@geindex getEvent() (μέθοδος της xml.dom.pulldom.DOMEventStream)
@anchor{library/xml dom pulldom xml dom pulldom DOMEventStream getEvent}@anchor{401f}
@deffn {Μέθοδος} getEvent ()

Return a tuple containing `event' and the current `node' as
@code{xml.dom.minidom.Document} if event equals @code{START_DOCUMENT},
@code{xml.dom.minidom.Element} if event equals @code{START_ELEMENT} or
@code{END_ELEMENT} or @code{xml.dom.minidom.Text} if event equals
@code{CHARACTERS}.
The current node does not contain information about its children, unless
@ref{4015,,expandNode()} is called.
@end deffn

@geindex expandNode() (μέθοδος της xml.dom.pulldom.DOMEventStream)
@anchor{library/xml dom pulldom xml dom pulldom DOMEventStream expandNode}@anchor{4015}
@deffn {Μέθοδος} expandNode (node)

Expands all children of `node' into `node'. Example:

@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() (μέθοδος της xml.dom.pulldom.DOMEventStream)
@anchor{library/xml dom pulldom xml dom pulldom DOMEventStream reset}@anchor{4020}
@deffn {Μέθοδος} reset ()
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xml sax — Support for SAX2 parsers,xml sax handler — Βασικές κλάσεις για χειριστές SAX,xml dom pulldom — Support for building partial DOM trees,Structured Markup Processing Tools
@anchor{library/xml sax doc}@anchor{4021}@anchor{library/xml sax module-xml sax}@anchor{132}@anchor{library/xml sax translation-repo}@anchor{4022}@anchor{library/xml sax xml-sax-support-for-sax2-parsers}@anchor{4023}
@subsection @code{xml.sax} — Support for SAX2 parsers


@geindex module; xml.sax

`Source code:' Lib/xml/sax/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/xml/sax/__init__.py}


__________________________________________________________________


The @code{xml.sax} package provides a number of modules which implement the
Simple API for XML (SAX) interface for Python.  The package itself provides the
SAX exceptions and the convenience functions which will be most used by users of
the SAX API.

@cartouche
@quotation Σημείωση 
If you need to parse untrusted or unauthenticated data, see
@ref{3f34,,XML security}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.7.1: The SAX parser no longer processes general external entities by default
to increase security. Before, the parser created network connections
to fetch remote files or loaded local files from the file
system for DTD and entities. The feature can be enabled again with method
@ref{4024,,setFeature()} on the parser object
and argument @ref{19b7,,feature_external_ges}.


The convenience functions are:

@geindex make_parser() (στη μονάδα xml.sax)
@anchor{library/xml sax xml sax make_parser}@anchor{200a}
@deffn {Συνάρτηση} xml.sax.make_parser (parser_list=[])

Create and return a SAX @ref{401a,,XMLReader} object.  The
first parser found will
be used.  If `parser_list' is provided, it must be an iterable of strings which
name modules that have a function named @code{create_parser()}.  Modules listed
in `parser_list' will be used before modules in the default list of parsers.


Άλλαξε στην έκδοση 3.8: The `parser_list' argument can be any iterable, not just a list.

@end deffn

@geindex parse() (στη μονάδα xml.sax)
@anchor{library/xml sax xml sax parse}@anchor{1fd5}
@deffn {Συνάρτηση} xml.sax.parse (filename_or_stream, handler, error_handler=handler.ErrorHandler())

Create a SAX parser and use it to parse a document.  The document, passed in as
`filename_or_stream', can be a filename or a file object.  The `handler'
parameter needs to be a SAX @ref{4017,,ContentHandler} instance.  If
`error_handler' is given, it must be a SAX @ref{4025,,ErrorHandler}
instance; if
omitted,  @ref{4026,,SAXParseException} will be raised on all errors.  There is no
return value; all work must be done by the `handler' passed in.
@end deffn

@geindex parseString() (στη μονάδα xml.sax)
@anchor{library/xml sax xml sax parseString}@anchor{124d}
@deffn {Συνάρτηση} xml.sax.parseString (string, handler, error_handler=handler.ErrorHandler())

Similar to @ref{1fd5,,parse()}, but parses from a buffer `string' received as a
parameter.  `string' must be a @ref{1df,,str} instance or a
@ref{436,,bytes-like object}.


Άλλαξε στην έκδοση 3.5: Added support of @ref{1df,,str} instances.

@end deffn

A typical SAX application uses three kinds of objects: readers, handlers and
input sources.  «Reader» in this context is another term for parser, i.e. some
piece of code that reads the bytes or characters from the input source, and
produces a sequence of events. The events then get distributed to the handler
objects, i.e. the reader invokes a method on the handler.  A SAX application
must therefore obtain a reader object, create or open the input sources, create
the handlers, and connect these objects all together.  As the final step of
preparation, the reader is called to parse the input. During parsing, methods on
the handler objects are called based on structural and syntactic events from the
input data.

For these objects, only the interfaces are relevant; they are normally not
instantiated by the application itself.  Since Python does not have an explicit
notion of interface, they are formally introduced as classes, but applications
may use implementations which do not inherit from the provided classes.  The
@ref{124c,,InputSource}, @ref{4027,,Locator},
@code{Attributes}, @code{AttributesNS},
and @ref{401a,,XMLReader} interfaces are defined in the
module @ref{135,,xml.sax.xmlreader}.  The handler interfaces are defined in
@ref{133,,xml.sax.handler}.  For convenience,
@code{InputSource} (which is often
instantiated directly) and the handler classes are also available from
@code{xml.sax}.  These interfaces are described below.

In addition to these classes, @code{xml.sax} provides the following exception
classes.

@geindex SAXException
@anchor{library/xml sax xml sax SAXException}@anchor{4028}
@deffn {Εξαίρεση} xml.sax.SAXException (msg, exception=None)

Encapsulate an XML error or warning.  This class can contain basic error or
warning information from either the XML parser or the application: it can be
subclassed to provide additional functionality or to add localization.  Note
that although the handlers defined in the
@ref{4025,,ErrorHandler} interface
receive instances of this exception, it is not required to actually raise the
exception — it is also useful as a container for information.

When instantiated, `msg' should be a human-readable description of the error.
The optional `exception' parameter, if given, should be @code{None} or an exception
that was caught by the parsing code and is being passed along as information.

This is the base class for the other SAX exception classes.
@end deffn

@geindex SAXParseException
@anchor{library/xml sax xml sax SAXParseException}@anchor{4026}
@deffn {Εξαίρεση} xml.sax.SAXParseException (msg, exception, locator)

Subclass of @ref{4028,,SAXException} raised on parse errors. Instances of this
class are passed to the methods of the SAX
@ref{4025,,ErrorHandler} interface to provide information
about the parse error.  This class supports the SAX
@ref{4027,,Locator} interface as well as the
@ref{4028,,SAXException} interface.
@end deffn

@geindex SAXNotRecognizedException
@anchor{library/xml sax xml sax SAXNotRecognizedException}@anchor{4029}
@deffn {Εξαίρεση} xml.sax.SAXNotRecognizedException (msg, exception=None)

Subclass of @ref{4028,,SAXException} raised when a SAX
@ref{401a,,XMLReader} is
confronted with an unrecognized feature or property.  SAX applications and
extensions may use this class for similar purposes.
@end deffn

@geindex SAXNotSupportedException
@anchor{library/xml sax xml sax SAXNotSupportedException}@anchor{402a}
@deffn {Εξαίρεση} xml.sax.SAXNotSupportedException (msg, exception=None)

Subclass of @ref{4028,,SAXException} raised when a SAX
@ref{401a,,XMLReader} is asked to
enable a feature that is not supported, or to set a property to a value that the
implementation does not support.  SAX applications and extensions may use this
class for similar purposes.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item SAX: The Simple API for XML@footnote{http://www.saxproject.org/}

This site is the focal point for the definition of the SAX API.  It provides a
Java implementation and online documentation.  Links to implementations and
historical information are also available.

@item Module @ref{133,,xml.sax.handler}

Definitions of the interfaces for application-provided objects.

@item Module @ref{134,,xml.sax.saxutils}

Convenience functions for use in SAX applications.

@item Module @ref{135,,xml.sax.xmlreader}

Definitions of the interfaces for parser-provided objects.
@end table


@menu
* SAXException Objects:: 

@end menu

@node SAXException Objects,,,xml sax — Support for SAX2 parsers
@anchor{library/xml sax sax-exception-objects}@anchor{402b}@anchor{library/xml sax saxexception-objects}@anchor{402c}
@subsubsection SAXException Objects


The @ref{4028,,SAXException} exception class supports the following methods:

@geindex getMessage() (μέθοδος της xml.sax.SAXException)
@anchor{library/xml sax xml sax SAXException getMessage}@anchor{402d}
@deffn {Μέθοδος} SAXException.getMessage ()

Return a human-readable message describing the error condition.
@end deffn

@geindex getException() (μέθοδος της xml.sax.SAXException)
@anchor{library/xml sax xml sax SAXException getException}@anchor{402e}
@deffn {Μέθοδος} SAXException.getException ()

Return an encapsulated exception object, or @code{None}.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xml sax handler — Βασικές κλάσεις για χειριστές SAX,xml sax saxutils — SAX Utilities,xml sax — Support for SAX2 parsers,Structured Markup Processing Tools
@anchor{library/xml sax handler doc}@anchor{402f}@anchor{library/xml sax handler module-xml sax handler}@anchor{133}@anchor{library/xml sax handler translation-repo}@anchor{4030}@anchor{library/xml sax handler xml-sax-handler-base-classes-for-sax-handlers}@anchor{4031}
@subsection @code{xml.sax.handler} — Βασικές κλάσεις για χειριστές SAX


@geindex module; xml.sax.handler

`Πηγαίος κώδικας:' Lib/xml/sax/handler.py@footnote{https://github.com/python/cpython/tree/main/Lib/xml/sax/handler.py}


__________________________________________________________________


The SAX API defines five kinds of handlers: content handlers, DTD handlers,
error handlers, entity resolvers and lexical handlers. Applications normally
only need to implement those interfaces whose events they are interested in;
they can implement the interfaces in a single object or in multiple objects.
Handler implementations should inherit from the base classes provided in the
module @code{xml.sax.handler}, so that all methods get default implementations.

@geindex ContentHandler (κλάση σε xml.sax.handler)
@anchor{library/xml sax handler xml sax handler ContentHandler}@anchor{4017}
@deffn {Κλάση} xml.sax.handler.ContentHandler

Αυτή είναι η κύρια διεπαφή callback στο SAX και η πιο σημαντική για τις εφαρμογές. Η σειρά των γεγονότων σε αυτή τη διεπαφή αντικατοπτρίζει τη σειρά των πληροφοριών στο έγγραφο.
@end deffn

@geindex DTDHandler (κλάση σε xml.sax.handler)
@anchor{library/xml sax handler xml sax handler DTDHandler}@anchor{4032}
@deffn {Κλάση} xml.sax.handler.DTDHandler

Χειρισμός DTD γεγονότων.

Αυτή η διεπαφή καθορίζει μόνο τα γεγονότα DTD που απαιτούνται για βασική ανάλυση (μη αναλυμένες οντότητες και ιδιότητες).
@end deffn

@geindex EntityResolver (κλάση σε xml.sax.handler)
@anchor{library/xml sax handler xml sax handler EntityResolver}@anchor{4033}
@deffn {Κλάση} xml.sax.handler.EntityResolver

Βασική διεπαφή για την επίλυση οντοτήτων. Εάν δημιουργήσετε ένα αντικείμενο που υλοποιεί αυτή τη διεπαφή, τότε θα πρέπει να το καταχωρήσετε στον αναλυτή σας, o αναλυτής θα καλέσει τη μέθοδο στο αντικείμενό σας για να επιλύσει όλες τις εξωτερικές οντότητες.
@end deffn

@geindex ErrorHandler (κλάση σε xml.sax.handler)
@anchor{library/xml sax handler xml sax handler ErrorHandler}@anchor{4025}
@deffn {Κλάση} xml.sax.handler.ErrorHandler

Διεπαφή που χρησιμοποιείται από τον αναλυτή για να παρουσιάσει μηνύματα σφάλματος και προειδοποιήσεων στην εφαρμογή. Οι μέθοδοι αυτού του αντικειμένου ελέγχουν αν τα σφάλματα μετατρέπονται άμεσα σε εξαιρέσεις ή αντιμετωπίζονται με κάποιο άλλο τρόπο.
@end deffn

@geindex LexicalHandler (κλάση σε xml.sax.handler)
@anchor{library/xml sax handler xml sax handler LexicalHandler}@anchor{c33}
@deffn {Κλάση} xml.sax.handler.LexicalHandler

Διεπαφή που χρησιμοποιείται από τον αναλυτή για να παρουσιάσει γεγονότα χαμηλής συχνότητας που μπορεί να μην ενδιαφέρουν πολλές εφαρμογές.
@end deffn

In addition to these classes, @code{xml.sax.handler} provides symbolic constants
for the feature and property names.

@geindex feature_namespaces (στη μονάδα xml.sax.handler)
@anchor{library/xml sax handler xml sax handler feature_namespaces}@anchor{4034}
@deffn {Δεδομένα} xml.sax.handler.feature_namespaces


@display
value: @code{"http://xml.org/sax/features/namespaces"}@w{ }
true: Εκτέλεση επεξεργασίας ονομάτων χώρου.@w{ }
false: Προαιρετικά μη εκτέλεση επεξεργασίας ονομάτων χώρου (υπονοεί namespace-prefixes; προεπιλογή).@w{ }
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή@w{ }
@end display


@end deffn

@geindex feature_namespace_prefixes (στη μονάδα xml.sax.handler)
@anchor{library/xml sax handler xml sax handler feature_namespace_prefixes}@anchor{4035}
@deffn {Δεδομένα} xml.sax.handler.feature_namespace_prefixes


@display
value: @code{"http://xml.org/sax/features/namespace-prefixes"}@w{ }
true: Αναφορά των αρχικών ονομάτων με πρόθεμα και ιδιοτήτων που χρησιμοποιούνται για δηλώσεις ονομάτων χώρου.@w{ }
false: Μη αναφορά ιδιοτήτων που χρησιμοποιούνται για δηλώσεις ονομάτων χώρου, και προαιρετικά μη αναφορά αρχικών ονομάτων με πρόθεμα (προεπιλογή).@w{ }
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή@w{ }
@end display


@end deffn

@geindex feature_string_interning (στη μονάδα xml.sax.handler)
@anchor{library/xml sax handler xml sax handler feature_string_interning}@anchor{4036}
@deffn {Δεδομένα} xml.sax.handler.feature_string_interning


@display
value: @code{"http://xml.org/sax/features/string-interning"}@w{ }
true: Όλα τα ονόματα στοιχείων, πρόθεμα, ονόματα ιδιοτήτων, URIs ονομάτων χώρου και τοπικά ονόματα εσωτερικεύονται χρησιμοποιώντας την ενσωματωμένη συνάρτηση εσωτερικοποίησης (intern).@w{ }
false: Τα ονόματα δεν εσωτερικεύονται απαραίτητα, αν και μπορεί να είναι (προεπιλογή).@w{ }
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή@w{ }
@end display


@end deffn

@geindex feature_validation (στη μονάδα xml.sax.handler)
@anchor{library/xml sax handler xml sax handler feature_validation}@anchor{4037}
@deffn {Δεδομένα} xml.sax.handler.feature_validation


@display
value: @code{"http://xml.org/sax/features/validation"}@w{ }
true: Αναφορά όλων των σφαλμάτων επικύρωσης (υπονοεί external-general-entities και external-parameter-entities).@w{ }
false: Μη αναφορά σφαλμάτων επικύρωσης.@w{ }
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή@w{ }
@end display


@end deffn

@geindex feature_external_ges (στη μονάδα xml.sax.handler)
@anchor{library/xml sax handler xml sax handler feature_external_ges}@anchor{19b7}
@deffn {Δεδομένα} xml.sax.handler.feature_external_ges

@cartouche
@quotation Προειδοποίηση 
Η ενεργοποίηση ανοίγει μια ευπάθεια σε επιθέσεις εξωτερικών οντοτήτων@footnote{https://en.wikipedia.org/wiki/XML_external_entity_attack} εάν ο αναλυτής χρησιμοποιείται με περιεχόμενο XML που παρέχεται από τον χρήστη. Παρακαλώ σκεφτείτε το μοντέλο απειλών σας@footnote{https://en.wikipedia.org/wiki/Threat_model} πριν ενεργοποιήσετε αυτό το χαρακτηριστικό.
@end quotation
@end cartouche


@display
value: @code{"http://xml.org/sax/features/external-general-entities"}@w{ }
true: Συμπερίληψη όλων των εξωτερικών γενικών (κείμενο) οντοτήτων.@w{ }
false: Μη συμπερίληψη εξωτερικών γενικών οντοτήτων.@w{ }
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή@w{ }
@end display


@end deffn

@geindex feature_external_pes (στη μονάδα xml.sax.handler)
@anchor{library/xml sax handler xml sax handler feature_external_pes}@anchor{4038}
@deffn {Δεδομένα} xml.sax.handler.feature_external_pes


@display
value: @code{"http://xml.org/sax/features/external-parameter-entities"}@w{ }
true: Συμπερίληψη όλων των εξωτερικών παραμέτρων οντοτήτων, συμπεριλαμβανομένου του εξωτερικού υποσυνόλου DTD.@w{ }
false: Μη συμπερίληψη εξωτερικών παραμέτρων οντοτήτων, ακόμη και του εξωτερικού υποσυνόλου DTD.@w{ }
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή@w{ }
@end display


@end deffn

@geindex all_features (στη μονάδα xml.sax.handler)
@anchor{library/xml sax handler xml sax handler all_features}@anchor{4039}
@deffn {Δεδομένα} xml.sax.handler.all_features

Λίστα όλων των χαρακτηριστικών.
@end deffn

@geindex property_lexical_handler (στη μονάδα xml.sax.handler)
@anchor{library/xml sax handler xml sax handler property_lexical_handler}@anchor{403a}
@deffn {Δεδομένα} xml.sax.handler.property_lexical_handler


@display
value: @code{"http://xml.org/sax/properties/lexical-handler"}@w{ }
data type: xml.sax.handler.LexicalHandler (δεν υποστηρίζεται στην Python 2)@w{ }
description: Ένας προαιρετικός χειριστής επέκτασης για λεξικά συμβάντα όπως τα σχόλια.@w{ }
access: read/write@w{ }
@end display


@end deffn

@geindex property_declaration_handler (στη μονάδα xml.sax.handler)
@anchor{library/xml sax handler xml sax handler property_declaration_handler}@anchor{403b}
@deffn {Δεδομένα} xml.sax.handler.property_declaration_handler


@display
value: @code{"http://xml.org/sax/properties/declaration-handler"}@w{ }
data type: xml.sax.sax2lib.DeclHandler (δεν υποστηρίζεται στην Python 2)@w{ }
description: Ένας προαιρετικός χειριστής επέκτασης για γεγονότα που σχετίζονται με το DTD εκτός από τις δηλώσεις και τις μη αναλυμένες οντότητες.@w{ }
access: read/write@w{ }
@end display


@end deffn

@geindex property_dom_node (στη μονάδα xml.sax.handler)
@anchor{library/xml sax handler xml sax handler property_dom_node}@anchor{403c}
@deffn {Δεδομένα} xml.sax.handler.property_dom_node


@display
value: @code{"http://xml.org/sax/properties/dom-node"}@w{ }
data type: org.w3c.dom.Node (δεν υποστηρίζεται στην Python 2)@w{ }
description: Κατά την ανάλυση, ο τρέχων DOM κόμβος που επισκέπτεται εάν αυτός είναι ένας επαναληπτικός DOM κόμβος∙ όταν δεν αναλύεται, ο ριζικός DOM κόμβος για την επανάληψη.@w{ }
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή@w{ }
@end display


@end deffn

@geindex property_xml_string (στη μονάδα xml.sax.handler)
@anchor{library/xml sax handler xml sax handler property_xml_string}@anchor{403d}
@deffn {Δεδομένα} xml.sax.handler.property_xml_string


@display
value: @code{"http://xml.org/sax/properties/xml-string"}@w{ }
data type: Bytes@w{ }
description: Η κυριολεκτική συμβολοσειρά χαρακτήρων που ήταν η πηγή για το τρέχον γεγονός.@w{ }
access: μόνο για ανάγνωση@w{ }
@end display


@end deffn

@geindex all_properties (στη μονάδα xml.sax.handler)
@anchor{library/xml sax handler xml sax handler all_properties}@anchor{403e}
@deffn {Δεδομένα} xml.sax.handler.all_properties

Λίστα όλων των γνωστών ονομάτων ιδιοτήτων.
@end deffn

@menu
* ContentHandler Αντικείμενα:: 
* DTDHandler Αντικείμενα:: 
* EntityResolver Αντικείμενα:: 
* ErrorHandler Αντικείμενα:: 
* LexicalHandler Αντικείμενα:: 

@end menu

@node ContentHandler Αντικείμενα,DTDHandler Αντικείμενα,,xml sax handler — Βασικές κλάσεις για χειριστές SAX
@anchor{library/xml sax handler content-handler-objects}@anchor{403f}@anchor{library/xml sax handler contenthandler-objects}@anchor{4040}
@subsubsection ContentHandler Αντικείμενα


Οι χρήστες αναμένεται να δημιουργήσουν υποκλάση @ref{4017,,ContentHandler} για να υποστηρίξουν την εφαρμογή τους.  Οι ακόλουθες μέθοδοι καλούνται από τον αναλυτή στα κατάλληλα γεγονότα στο έγγραφο εισόδου:

@geindex setDocumentLocator() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler setDocumentLocator}@anchor{4041}
@deffn {Μέθοδος} ContentHandler.setDocumentLocator (locator)

Καλείται από τον αναλυτή για να δώσει στην εφαρμογή έναν εντοπιστή για τον εντοπισμό της προέλευσης των γεγονότων του εγγράφου.

Οι αναλυτές SAX ενθαρρύνονται έντονα (αν και δεν απαιτείται απολύτως) να παρέχουν έναν εντοπιστή: εάν το κάνουν, πρέπει να παρέχουν τον εντοπιστή στην εφαρμογή καλώντας αυτή τη μέθοδο πριν από την κλήση οποιωνδήποτε άλλων μεθόδων στη διεπαφή DocumentHandler.

Ο εντοπιστής επιτρέπει στην εφαρμογή να προσδιορίσει τη θέση τέλους οποιουδήποτε γεγονότος που σχετίζεται με το έγγραφο, ακόμη και αν ο αναλυτής δεν αναφέρει σφάλμα. Συνήθως, η εφαρμογή θα χρησιμοποιήσει αυτές τις πληροφορίες για την αναφορά των δικών της σφαλμάτων (όπως περιεχόμενο χαρακτήρων που δεν αντιστοιχεί στους επιχειρηματικούς κανόνες της εφαρμογής). Οι πληροφορίες που επιστρέφονται από τον εντοπιστή πιθανώς δεν είναι αρκετές για χρήση με μια μηχανή αναζήτησης.

Σημειώστε ότι ο εντοπιστής θα επιστρέψει σωστές πληροφορίες μόνο κατά την κλήση των γεγονότων σε αυτή τη διεπαφή. Η εφαρμογή δεν θα πρέπει να προσπαθήσει να τον χρησιμοποιήσει σε οποιαδήποτε άλλη στιγμή.
@end deffn

@geindex startDocument() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler startDocument}@anchor{4042}
@deffn {Μέθοδος} ContentHandler.startDocument ()

Λήψη ειδοποίησης για την αρχή ενός εγγράφου.

Ο αναλυτής SAX θα καλέσει αυτή τη μέθοδο μόνο μία φορά, πριν από οποιαδήποτε άλλη μέθοδο σε αυτή τη διεπαφή ή σε DTDHandler (εκτός από @ref{4041,,setDocumentLocator()}).
@end deffn

@geindex endDocument() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler endDocument}@anchor{4043}
@deffn {Μέθοδος} ContentHandler.endDocument ()

Λήψη ειδοποίησης για το τέλος ενός εγγράφου.

Ο αναλυτής SAX θα καλέσει αυτή τη μέθοδο μόνο μία φορά, και θα είναι η τελευταία μέθοδος που θα κληθεί κατά τη διάρκεια της ανάλυσης. Ο αναλυτής δεν θα καλέσει αυτή τη μέθοδο μέχρι να εγκαταλείψει την ανάλυση (εξαιτίας ενός μη ανακτήσιμου σφάλματος) ή να φτάσει στο τέλος της εισόδου.
@end deffn

@geindex startPrefixMapping() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler startPrefixMapping}@anchor{4044}
@deffn {Μέθοδος} ContentHandler.startPrefixMapping (prefix, uri)

Αρχή της έκτασης ενός προθέματος-URI χαρτογράφησης ονόματος χώρου.

Οι πληροφορίες από αυτό το γεγονός δεν είναι απαραίτητες για την κανονική επεξεργασία ονομάτων χώρου: ο αναγνώστης SAX XML θα αντικαταστήσει αυτόματα τα προθέματα για τα ονόματα στοιχείων και ιδιοτήτων όταν είναι ενεργοποιημένο το χαρακτηριστικό @code{feature_namespaces} (η προεπιλογή).

Υπάρχουν, ωστόσο, περιπτώσεις όπου οι εφαρμογές χρειάζεται να χρησιμοποιούν προθέματα σε δεδομένα χαρακτήρων ή σε τιμές ιδιοτήτων, όπου δεν μπορούν να επεκταθούν αυτόματα με ασφάλεια. Τα γεγονότα @ref{4044,,startPrefixMapping()} και @ref{4045,,endPrefixMapping()} παρέχουν στις εφαρμογές τις πληροφορίες για να επεκτείνουν τα προθέματα σε αυτά τα συμφραζόμενα, εάν είναι απαραίτητο.

@c XXX This is not really the default, is it? MvL

Σημειώστε ότι τα γεγονότα @ref{4044,,startPrefixMapping()} και @ref{4045,,endPrefixMapping()} δεν εγγυώνται ότι θα είναι σωστά εγκατεστημένα σε σχέση με το ένα το άλλο: όλα τα γεγονότα @code{startPrefixMapping()} θα συμβούν πριν από το αντίστοιχο @ref{18e5,,startElement()} γεγονός, και όλα τα γεγονότα @code{endPrefixMapping()} θα συμβούν μετά το αντίστοιχο @ref{18e6,,endElement()} γεγονός, αλλά η σειρά τους δεν είναι εγγυημένη.
@end deffn

@geindex endPrefixMapping() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler endPrefixMapping}@anchor{4045}
@deffn {Μέθοδος} ContentHandler.endPrefixMapping (prefix)

Τέλος της έκτασης μιας χαρτογράφησης προθέματος-URI.

Δείτε @ref{4044,,startPrefixMapping()} για λεπτομέρειες. Αυτό το γεγονός θα συμβεί πάντα μετά το αντίστοιχο γεγονός @ref{18e6,,endElement()}, αλλά η σειρά των γεγονότων @ref{4045,,endPrefixMapping()} δεν είναι εγγυημένη.
@end deffn

@geindex startElement() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler startElement}@anchor{18e5}
@deffn {Μέθοδος} ContentHandler.startElement (name, attrs)

Σηματοδοτεί την αρχή ενός στοιχείου σε λειτουργία χωρίς ονόματα χώρου.

Η παράμετρος `name' περιέχει το ακατέργαστο όνομα XML 1.0 του τύπου στοιχείου ως συμβολοσειρά και η παράμετρος `attrs' περιέχει ένα αντικείμενο της @ref{4046,,Attributes} διεπαφής που περιέχει τις ιδιότητες του στοιχείου. Το αντικείμενο που περιέχεται στην παράμετρο `attrs' μπορεί να χρησιμοποιηθεί ξανά από τον αναλυτή∙ η διατήρηση αναφοράς σε αυτό δεν είναι αξιόπιστος τρόπος για να διατηρήσετε αντίγραφο των ιδιοτήτων. Για να διατηρήσετε ένα αντίγραφο των ιδιοτήτων, χρησιμοποιήστε τη μέθοδο @ref{29,,copy()} του αντικειμένου `attrs'.
@end deffn

@geindex endElement() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler endElement}@anchor{18e6}
@deffn {Μέθοδος} ContentHandler.endElement (name)

Σηματοδοτεί το τέλος ενός στοιχείου σε λειτουργία χωρίς ονόματα χώρου.

Η παράμετρος `name' περιέχει το όνομα του τύπου στοιχείου, όπως και με το @ref{18e5,,startElement()} γεγονός.
@end deffn

@geindex startElementNS() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler startElementNS}@anchor{4047}
@deffn {Μέθοδος} ContentHandler.startElementNS (name, qname, attrs)

Σηματοδοτεί την αρχή ενός στοιχείου σε λειτουργία ονομάτων χώρου.

Η παράμετρος `name' περιέχει το όνομα του τύπου στοιχείου ως @code{(uri, localname)} πλειάδα, η παράμετρος `qname' περιέχει το ακατέργαστο όνομα XML 1.0 που χρησιμοποιείται στο έγγραφο προέλευσης, και η παράμετρος `attrs' περιέχει μια παρουσία της διεπαφής @ref{4048,,AttributesNS} που περιέχει τις ιδιότητες του στοιχείου. Εάν δεν συσχετίζεται κανένα όνομα χώρου με το στοιχείο, το `uri' συστατικό του `name' θα είναι @code{None}. Το αντικείμενο που περιέχεται στην παράμετρο `attrs' μπορεί να χρησιμοποιηθεί ξανά από τον αναλυτή. Η διατήρηση αναφοράς σε αυτό δεν είναι αξιόπιστος τρόπος για να διατηρήσετε αντίγραφο των ιδιοτήτων. Για να διατηρήσετε ένα αντίγραφο των ιδιοτήτων, χρησιμοποιήστε τη μέθοδο @ref{29,,copy()} του αντικειμένου `attrs'.

Οι αναλυτές μπορούν να ορίσουν την παράμετρο `qname' σε @code{None}, εκτός εάν είναι ενεργοποιημένο το χαρακτηριστικό @code{feature_namespace_prefixes}.
@end deffn

@geindex endElementNS() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler endElementNS}@anchor{4049}
@deffn {Μέθοδος} ContentHandler.endElementNS (name, qname)

Σηματοδοτεί το τέλος ενός στοιχείου σε λειτουργία ονομάτων χώρου.

Η παράμετρος `name' περιέχει το όνομα του τύπου στοιχείου, όπως και με τη @ref{4047,,startElementNS()} μέθοδο, όπως και η παράμετρος `qname'.
@end deffn

@geindex characters() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler characters}@anchor{18e7}
@deffn {Μέθοδος} ContentHandler.characters (content)

Λήψη ειδοποίησης για δεδομένα χαρακτήρων.

Ο Αναλυτής θα καλέσει αυτή τη μέθοδο για να αναφέρει κάθε κομμάτι δεδομένων χαρακτήρων. Οι αναλυτές SAX μπορεί να επιστρέψουν όλα τα συνεχόμενα δεδομένα χαρακτήρων σε ένα μοναδικό κομμάτι, ή μπορεί να τα χωρίσουν σε αρκετά κομμάτια. Ωστόσο, όλοι οι χαρακτήρες σε οποιοδήποτε μεμονωμένο γεγονός πρέπει να προέρχονται από την ίδια εξωτερική οντότητα, έτσι ώστε ο Εντοπιστής να παρέχει χρήσιμες πληροφορίες.

Το `content' μπορεί να είναι μια συμβολοσειρά ή ένα στιγμιότυπο bytes. Το αναγνωστικό @code{expat} παράγει πάντα συμβολοσειρές.

@cartouche
@quotation Σημείωση 
Η προηγούμενη διεπαφή SAX 1 που παρείχε η ομάδα ειδικού ενδιαφέροντος Python XML Group χρησιμοποιούσε μια διεπαφή που έμοιαζε περισσότερο με τη Java για αυτή τη μέθοδο.  Δεδομένου ότι οι περισσότεροι αναλυτές που χρησιμοποιούνται από την Python δεν εκμεταλλεύονταν την παλαιότερη διεπαφή, επιλέχθηκε η απλούστερη υπογραφή για να την αντικαταστήσει.  Για να μετατρέψετε τον παλιό κώδικα στη νέα διεπαφή, χρησιμοποιήστε `content' αντί να τεμαχίζετε το περιεχόμενο με τις παλιές παραμέτρους `offset' και `length'.
@end quotation
@end cartouche
@end deffn

@geindex ignorableWhitespace() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler ignorableWhitespace}@anchor{404a}
@deffn {Μέθοδος} ContentHandler.ignorableWhitespace (whitespace)

Λήψη ειδοποίησης για αγνοήσιμα κενά σε περιεχόμενο στοιχείου.

Οι Επικυρωτικοί Αναλυτές πρέπει να χρησιμοποιούν αυτή τη μέθοδο για να αναφέρουν κάθε κομμάτι αγνοήσιμου κενού (βλ. την W3C XML 1.0 σύσταση, τμήμα 2.10): οι μη επικυρωτικοί αναλυτές μπορούν επίσης να χρησιμοποιούν αυτή τη μέθοδο εάν είναι ικανοί να αναλύουν και να χρησιμοποιούν μοντέλα περιεχομένου.

Οι αναλυτές SAX μπορεί να επιστρέψουν όλα τα συνεχόμενα κενά σε ένα μοναδικό κομμάτι, ή μπορεί να τα χωρίσουν σε αρκετά κομμάτια. Ωστόσο, όλοι οι χαρακτήρες σε οποιοδήποτε μεμονωμένο γεγονός πρέπει να προέρχονται από την ίδια εξωτερική οντότητα, έτσι ώστε ο Εντοπιστής να παρέχει χρήσιμες πληροφορίες.
@end deffn

@geindex processingInstruction() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler processingInstruction}@anchor{404b}
@deffn {Μέθοδος} ContentHandler.processingInstruction (target, data)

Λήψη ειδοποίησης για μια οδηγία επεξεργασίας.

Ο Αναλυτής θα καλέσει αυτή τη μέθοδο μία φορά για κάθε οδηγία επεξεργασίας που βρέθηκε: σημειώστε ότι οι οδηγίες επεξεργασίας μπορεί να εμφανίζονται πριν ή μετά το κύριο στοιχείο του εγγράφου.

Ένας αναλυτής SAX δεν πρέπει ποτέ να αναφέρει μια δήλωση XML (XML 1.0, τμήμα 2.8) ή μια δήλωση κειμένου (XML  1.0, τμήμα 4.3.1) χρησιμοποιώντας αυτή τη μέθοδο.
@end deffn

@geindex skippedEntity() (μέθοδος της xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler skippedEntity}@anchor{404c}
@deffn {Μέθοδος} ContentHandler.skippedEntity (name)

Λήψη ειδοποίησης για μια παράλειψη οντότητας.

Ο Αναλυτής θα καλέσει αυτή τη μέθοδο μία φορά για κάθε παράλειψη οντότητας. Οι μη επικυρωτικοί επεξεργαστές μπορεί να παραλείψουν οντότητες εάν δεν έχουν δει τις δηλώσεις (για παράδειγμα, η οντότητα δηλώθηκε σε ένα εξωτερικό υποσύνολο DTD). Όλοι οι επεξεργαστές μπορεί να παραλείψουν εξωτερικές οντότητες, ανάλογα με τις τιμές των ιδιοτήτων @code{feature_external_ges} και @code{feature_external_pes}.
@end deffn

@node DTDHandler Αντικείμενα,EntityResolver Αντικείμενα,ContentHandler Αντικείμενα,xml sax handler — Βασικές κλάσεις για χειριστές SAX
@anchor{library/xml sax handler dtd-handler-objects}@anchor{404d}@anchor{library/xml sax handler dtdhandler-objects}@anchor{404e}
@subsubsection DTDHandler Αντικείμενα


Τα @ref{4032,,DTDHandler} αντικείμενα παρέχουν τις ακόλουθες μεθόδους:

@geindex notationDecl() (μέθοδος της xml.sax.handler.DTDHandler)
@anchor{library/xml sax handler xml sax handler DTDHandler notationDecl}@anchor{404f}
@deffn {Μέθοδος} DTDHandler.notationDecl (name, publicId, systemId)

Χειρισμός ενός γεγονότος δήλωσης σημείωσης.
@end deffn

@geindex unparsedEntityDecl() (μέθοδος της xml.sax.handler.DTDHandler)
@anchor{library/xml sax handler xml sax handler DTDHandler unparsedEntityDecl}@anchor{4050}
@deffn {Μέθοδος} DTDHandler.unparsedEntityDecl (name, publicId, systemId, ndata)

Χειρισμός ενός γεγονότος δήλωσης μη αναλυμένης οντότητας.
@end deffn

@node EntityResolver Αντικείμενα,ErrorHandler Αντικείμενα,DTDHandler Αντικείμενα,xml sax handler — Βασικές κλάσεις για χειριστές SAX
@anchor{library/xml sax handler entity-resolver-objects}@anchor{4051}@anchor{library/xml sax handler entityresolver-objects}@anchor{4052}
@subsubsection EntityResolver Αντικείμενα


@geindex resolveEntity() (μέθοδος της xml.sax.handler.EntityResolver)
@anchor{library/xml sax handler xml sax handler EntityResolver resolveEntity}@anchor{4053}
@deffn {Μέθοδος} EntityResolver.resolveEntity (publicId, systemId)

Επιλύστε τον αναγνωριστικό συστήματος μιας οντότητας και επιστρέψτε είτε τον αναγνωριστικό συστήματος για ανάγνωση ως συμβολοσειρά, είτε μια InputSource για ανάγνωση. Η προεπιλεγμένη υλοποίηση επιστρέφει το `systemId'.
@end deffn

@node ErrorHandler Αντικείμενα,LexicalHandler Αντικείμενα,EntityResolver Αντικείμενα,xml sax handler — Βασικές κλάσεις για χειριστές SAX
@anchor{library/xml sax handler errorhandler-objects}@anchor{4054}@anchor{library/xml sax handler sax-error-handler}@anchor{4055}
@subsubsection ErrorHandler Αντικείμενα


Τα αντικείμενα με αυτή τη διεπαφή χρησιμοποιούνται για να λαμβάνουν πληροφορίες σφάλματος και προειδοποίησης από το @ref{401a,,XMLReader}. Εάν δημιουργήσετε ένα αντικείμενο που υλοποιεί αυτή τη διεπαφή, τότε εγγράψτε το αντικείμενο με το σας @code{XMLReader}, ο αναλυτής θα καλέσει τις μεθόδους στο αντικείμενό σας για να αναφέρει όλες τις προειδοποιήσεις και τα σφάλματα. Υπάρχουν τρία επίπεδα σφαλμάτων διαθέσιμα: προειδοποιήσεις, (πιθανώς) ανακτήσιμα σφάλματα και μη ανακτήσιμα σφάλματα. Όλες οι μέθοδοι δέχονται ένα @ref{4026,,SAXParseException} ως τη μόνη παράμετρο. Τα σφάλματα και οι προειδοποιήσεις μπορούν να μετατραπούν σε εξαίρεση κάνοντας raise το αντικείμενο της εξαίρεσης που περιέχεται.

@geindex error() (μέθοδος της xml.sax.handler.ErrorHandler)
@anchor{library/xml sax handler xml sax handler ErrorHandler error}@anchor{4056}
@deffn {Μέθοδος} ErrorHandler.error (exception)

Καλείται όταν ο αναλυτής συναντήσει ένα ανακτήσιμο σφάλμα. Εάν αυτή η μέθοδος δεν κάνει raise μια εξαίρεση, η ανάλυση μπορεί να συνεχιστεί, αλλά δεν θα πρέπει να αναμένεται περαιτέρω πληροφορίες εγγράφου από την εφαρμογή. Η επιτρεπόμενη συνέχιση του αναλυτή μπορεί να επιτρέψει την ανακάλυψη πρόσθετων σφαλμάτων στο έγγραφο εισόδου.
@end deffn

@geindex fatalError() (μέθοδος της xml.sax.handler.ErrorHandler)
@anchor{library/xml sax handler xml sax handler ErrorHandler fatalError}@anchor{4057}
@deffn {Μέθοδος} ErrorHandler.fatalError (exception)

Καλείται όταν ο αναλυτής συναντήσει ένα σφάλμα από το οποίο δεν μπορεί να ανακάμψει. Η ανάλυση αναμένεται να τερματιστεί όταν αυτή η μέθοδος επιστρέψει.
@end deffn

@geindex warning() (μέθοδος της xml.sax.handler.ErrorHandler)
@anchor{library/xml sax handler xml sax handler ErrorHandler warning}@anchor{4058}
@deffn {Μέθοδος} ErrorHandler.warning (exception)

Καλείται όταν ο αναλυτής παρουσιάσει πληροφορίες προειδοποίησης στην εφαρμογή. Η ανάλυση αναμένεται να συνεχιστεί όταν αυτή η μέθοδος επιστρέψει, και οι πληροφορίες του εγγράφου θα συνεχίσουν να περνούν στην εφαρμογή. Κάνοντας raise μια εξαίρεση σε αυτή τη μέθοδο, θα οδηγήσει στον τερματισμό της ανάλυσης.
@end deffn

@node LexicalHandler Αντικείμενα,,ErrorHandler Αντικείμενα,xml sax handler — Βασικές κλάσεις για χειριστές SAX
@anchor{library/xml sax handler lexical-handler-objects}@anchor{4059}@anchor{library/xml sax handler lexicalhandler-objects}@anchor{405a}
@subsubsection LexicalHandler Αντικείμενα


Προαιρετικός χειριστής SAX2 για λεξικά γεγονότα.

Αυτός ο χειριστής χρησιμοποιείται για την απόκτηση λεξικών πληροφοριών σχετικά με ένα έγγραφο XML. Οι λεξικές πληροφορίες περιλαμβάνουν πληροφορίες που περιγράφουν την κωδικοποίηση του εγγράφου που χρησιμοποιείται και τα σχόλια XML που ενσωματώνονται στο έγγραφο, καθώς και τα όρια τμημάτων για το DTD και για τυχόν τμήματα CDATA. Οι λεξικοί χειριστές χρησιμοποιούνται με τον ίδιο τρόπο όπως οι χειριστές περιεχομένου.

Ορίστε τον LexicalHandler ενός XMLReader χρησιμοποιώντας τη μέθοδο setProperty με τον αναγνωριστικό ιδιότητας @code{'http://xml.org/sax/properties/lexical-handler'}.

@geindex comment() (μέθοδος της xml.sax.handler.LexicalHandler)
@anchor{library/xml sax handler xml sax handler LexicalHandler comment}@anchor{405b}
@deffn {Μέθοδος} LexicalHandler.comment (content)

Αναφέρει ένα σχόλιο οπουδήποτε στο έγγραφο (συμπεριλαμβανομένου του DTD και εκτός του στοιχείου εγγράφου).
@end deffn

@geindex startDTD() (μέθοδος της xml.sax.handler.LexicalHandler)
@anchor{library/xml sax handler xml sax handler LexicalHandler startDTD}@anchor{405c}
@deffn {Μέθοδος} LexicalHandler.startDTD (name, public_id, system_id)

Αναφέρει την αρχή των δηλώσεων DTD εάν το έγγραφο έχει συσχετισμένο DTD.
@end deffn

@geindex endDTD() (μέθοδος της xml.sax.handler.LexicalHandler)
@anchor{library/xml sax handler xml sax handler LexicalHandler endDTD}@anchor{405d}
@deffn {Μέθοδος} LexicalHandler.endDTD ()

Αναφέρει το τέλος της δήλωσης DTD.
@end deffn

@geindex startCDATA() (μέθοδος της xml.sax.handler.LexicalHandler)
@anchor{library/xml sax handler xml sax handler LexicalHandler startCDATA}@anchor{405e}
@deffn {Μέθοδος} LexicalHandler.startCDATA ()

Αναφέρει την αρχή ενός τμήματος σημειωμένου ως CDATA.

Τα περιεχόμενα του τμήματος σημειωμένου ως CDATA θα αναφερθούν μέσω του χειριστή χαρακτήρων.
@end deffn

@geindex endCDATA() (μέθοδος της xml.sax.handler.LexicalHandler)
@anchor{library/xml sax handler xml sax handler LexicalHandler endCDATA}@anchor{405f}
@deffn {Μέθοδος} LexicalHandler.endCDATA ()

Αναφέρει το τέλος ενός τμήματος σημειωμένου ως CDATA.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xml sax saxutils — SAX Utilities,xml sax xmlreader — Interface for XML parsers,xml sax handler — Βασικές κλάσεις για χειριστές SAX,Structured Markup Processing Tools
@anchor{library/xml sax utils doc}@anchor{4060}@anchor{library/xml sax utils module-xml sax saxutils}@anchor{134}@anchor{library/xml sax utils translation-repo}@anchor{4061}@anchor{library/xml sax utils xml-sax-saxutils-sax-utilities}@anchor{4062}
@subsection @code{xml.sax.saxutils} — SAX Utilities


@geindex module; xml.sax.saxutils

`Source code:' Lib/xml/sax/saxutils.py@footnote{https://github.com/python/cpython/tree/main/Lib/xml/sax/saxutils.py}


__________________________________________________________________


The module @code{xml.sax.saxutils} contains a number of classes and functions
that are commonly useful when creating SAX applications, either in direct use,
or as base classes.

@geindex escape() (στη μονάδα xml.sax.saxutils)
@anchor{library/xml sax utils xml sax saxutils escape}@anchor{4063}
@deffn {Συνάρτηση} xml.sax.saxutils.escape (data, entities=@{@})

Escape @code{'&'}, @code{'<'}, and @code{'>'} in a string of data.

You can escape other strings of data by passing a dictionary as the optional
`entities' parameter.  The keys and values must all be strings; each key will be
replaced with its corresponding value.  The characters @code{'&'}, @code{'<'} and
@code{'>'} are always escaped, even if `entities' is provided.

@cartouche
@quotation Σημείωση 
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() (στη μονάδα xml.sax.saxutils)
@anchor{library/xml sax utils xml sax saxutils unescape}@anchor{4064}
@deffn {Συνάρτηση} xml.sax.saxutils.unescape (data, entities=@{@})

Unescape @code{'&amp;'}, @code{'&lt;'}, and @code{'&gt;'} in a string of data.

You can unescape other strings of data by passing a dictionary as the optional
`entities' parameter.  The keys and values must all be strings; each key will be
replaced with its corresponding value.  @code{'&amp;'}, @code{'&lt;'}, and @code{'&gt;'}
are always unescaped, even if `entities' is provided.
@end deffn

@geindex quoteattr() (στη μονάδα xml.sax.saxutils)
@anchor{library/xml sax utils xml sax saxutils quoteattr}@anchor{4065}
@deffn {Συνάρτηση} xml.sax.saxutils.quoteattr (data, entities=@{@})

Similar to @ref{4063,,escape()}, but also prepares `data' to be used as an
attribute value.  The return value is a quoted version of `data' with any
additional required replacements. @code{quoteattr()} will select a quote
character based on the content of `data', attempting to avoid encoding any
quote characters in the string.  If both single- and double-quote characters
are already in `data', the double-quote characters will be encoded and `data'
will be wrapped in double-quotes.  The resulting string can be used directly
as an attribute value:

@example
>>> print("<element attr=%s>" % quoteattr("ab ' cd \" ef"))
<element attr="ab ' cd &quot; ef">
@end example

This function is useful when generating attribute values for HTML or any SGML
using the reference concrete syntax.
@end deffn

@geindex XMLGenerator (κλάση σε xml.sax.saxutils)
@anchor{library/xml sax utils xml sax saxutils XMLGenerator}@anchor{4066}
@deffn {Κλάση} xml.sax.saxutils.XMLGenerator (out=None, encoding='iso-8859-1', short_empty_elements=False)

This class implements the @ref{4017,,ContentHandler} interface
by writing SAX
events back into an XML document. In other words, using an @code{XMLGenerator}
as the content handler will reproduce the original document being parsed. `out'
should be a file-like object which will default to `sys.stdout'. `encoding' is
the encoding of the output stream which defaults to @code{'iso-8859-1'}.
`short_empty_elements' controls the formatting of elements that contain no
content:  if @code{False} (the default) they are emitted as a pair of start/end
tags, if set to @code{True} they are emitted as a single self-closed tag.


Άλλαξε στην έκδοση 3.2: Added the `short_empty_elements' parameter.

@end deffn

@geindex XMLFilterBase (κλάση σε xml.sax.saxutils)
@anchor{library/xml sax utils xml sax saxutils XMLFilterBase}@anchor{4067}
@deffn {Κλάση} xml.sax.saxutils.XMLFilterBase (base)

This class is designed to sit between an
@ref{401a,,XMLReader} and the client
application’s event handlers.  By default, it does nothing but pass requests up
to the reader and events on to the handlers unmodified, but subclasses can
override specific methods to modify the event stream or the configuration
requests as they pass through.
@end deffn

@geindex prepare_input_source() (στη μονάδα xml.sax.saxutils)
@anchor{library/xml sax utils xml sax saxutils prepare_input_source}@anchor{4068}
@deffn {Συνάρτηση} 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{124c,,InputSource} object ready for
reading.  The input source can be given as a string, a file-like object, or
an @code{InputSource} object; parsers will use this
function to implement the polymorphic `source' argument to their
@ref{4069,,parse()} method.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xml sax xmlreader — Interface for XML parsers,xml parsers expat — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat,xml sax saxutils — SAX Utilities,Structured Markup Processing Tools
@anchor{library/xml sax reader doc}@anchor{406a}@anchor{library/xml sax reader module-xml sax xmlreader}@anchor{135}@anchor{library/xml sax reader translation-repo}@anchor{406b}@anchor{library/xml sax reader xml-sax-xmlreader-interface-for-xml-parsers}@anchor{406c}
@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/main/Lib/xml/sax/xmlreader.py}


__________________________________________________________________


SAX parsers implement the @ref{401a,,XMLReader} interface. They are implemented in
a Python module, which must provide a function @code{create_parser()}. This
function is invoked by  @ref{200a,,xml.sax.make_parser()} with no arguments to create
a new  parser object.

@geindex XMLReader (κλάση σε xml.sax.xmlreader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader}@anchor{401a}
@deffn {Κλάση} xml.sax.xmlreader.XMLReader

Base class which can be inherited by SAX parsers.
@end deffn

@geindex IncrementalParser (κλάση σε xml.sax.xmlreader)
@anchor{library/xml sax reader xml sax xmlreader IncrementalParser}@anchor{406d}
@deffn {Κλάση} 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 (κλάση σε xml.sax.xmlreader)
@anchor{library/xml sax reader xml sax xmlreader Locator}@anchor{4027}
@deffn {Κλάση} 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 (κλάση σε xml.sax.xmlreader)
@anchor{library/xml sax reader xml sax xmlreader InputSource}@anchor{124c}
@deffn {Κλάση} xml.sax.xmlreader.InputSource (system_id=None)

Encapsulation of the information needed by the @ref{401a,,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{4069,,XMLReader.parse()} method and for returning from
EntityResolver.resolveEntity.

An @code{InputSource} belongs to the application, the @ref{401a,,XMLReader} is
not allowed to modify @code{InputSource} objects passed to it from the
application, although it may make copies and modify those.
@end deffn

@geindex AttributesImpl (κλάση σε xml.sax.xmlreader)
@anchor{library/xml sax reader xml sax xmlreader AttributesImpl}@anchor{406e}
@deffn {Κλάση} xml.sax.xmlreader.AttributesImpl (attrs)

This is an implementation of the @code{Attributes} interface (see section
@ref{4046,,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 (κλάση σε xml.sax.xmlreader)
@anchor{library/xml sax reader xml sax xmlreader AttributesNSImpl}@anchor{406f}
@deffn {Κλάση} xml.sax.xmlreader.AttributesNSImpl (attrs, qnames)

Namespace-aware variant of @ref{406e,,AttributesImpl}, which will be passed to
@code{startElementNS()}. It is derived from @code{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{4048,,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{4070}@anchor{library/xml sax reader xmlreader-objects}@anchor{4071}
@subsubsection XMLReader Objects


The @ref{401a,,XMLReader} interface supports the following methods:

@geindex parse() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader parse}@anchor{4069}
@deffn {Μέθοδος} 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{4ee,,pathlib.Path} or @ref{79f,,path-like}
object, or an @ref{124c,,InputSource} object. When
@code{parse()} returns, the input is completely processed, and the parser object
can be discarded or reset.


Άλλαξε στην έκδοση 3.5: Added support of character streams.



Άλλαξε στην έκδοση 3.8: Added support of path-like objects.

@end deffn

@geindex getContentHandler() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getContentHandler}@anchor{4072}
@deffn {Μέθοδος} XMLReader.getContentHandler ()

Return the current @ref{4017,,ContentHandler}.
@end deffn

@geindex setContentHandler() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setContentHandler}@anchor{4073}
@deffn {Μέθοδος} XMLReader.setContentHandler (handler)

Set the current @ref{4017,,ContentHandler}.  If no
@code{ContentHandler} is set, content events will be
discarded.
@end deffn

@geindex getDTDHandler() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getDTDHandler}@anchor{4074}
@deffn {Μέθοδος} XMLReader.getDTDHandler ()

Return the current @ref{4032,,DTDHandler}.
@end deffn

@geindex setDTDHandler() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setDTDHandler}@anchor{4075}
@deffn {Μέθοδος} XMLReader.setDTDHandler (handler)

Set the current @ref{4032,,DTDHandler}.  If no
@code{DTDHandler} is set, DTD
events will be discarded.
@end deffn

@geindex getEntityResolver() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getEntityResolver}@anchor{4076}
@deffn {Μέθοδος} XMLReader.getEntityResolver ()

Return the current @ref{4033,,EntityResolver}.
@end deffn

@geindex setEntityResolver() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setEntityResolver}@anchor{4077}
@deffn {Μέθοδος} XMLReader.setEntityResolver (handler)

Set the current @ref{4033,,EntityResolver}.  If no
@code{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() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getErrorHandler}@anchor{4078}
@deffn {Μέθοδος} XMLReader.getErrorHandler ()

Return the current @ref{4025,,ErrorHandler}.
@end deffn

@geindex setErrorHandler() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setErrorHandler}@anchor{4079}
@deffn {Μέθοδος} XMLReader.setErrorHandler (handler)

Set the current error handler.  If no @ref{4025,,ErrorHandler}
is set, errors will be raised as exceptions, and warnings will be printed.
@end deffn

@geindex setLocale() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setLocale}@anchor{407a}
@deffn {Μέθοδος} 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() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getFeature}@anchor{407b}
@deffn {Μέθοδος} 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{133,,xml.sax.handler}.
@end deffn

@geindex setFeature() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setFeature}@anchor{4024}
@deffn {Μέθοδος} 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() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getProperty}@anchor{407c}
@deffn {Μέθοδος} 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{133,,xml.sax.handler}.
@end deffn

@geindex setProperty() (μέθοδος της xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setProperty}@anchor{407d}
@deffn {Μέθοδος} 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{407e}@anchor{library/xml sax reader incrementalparser-objects}@anchor{407f}
@subsubsection IncrementalParser Objects


Instances of @ref{406d,,IncrementalParser} offer the following additional methods:

@geindex feed() (μέθοδος της xml.sax.xmlreader.IncrementalParser)
@anchor{library/xml sax reader xml sax xmlreader IncrementalParser feed}@anchor{4080}
@deffn {Μέθοδος} IncrementalParser.feed (data)

Process a chunk of `data'.
@end deffn

@geindex close() (μέθοδος της xml.sax.xmlreader.IncrementalParser)
@anchor{library/xml sax reader xml sax xmlreader IncrementalParser close}@anchor{4081}
@deffn {Μέθοδος} 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() (μέθοδος της xml.sax.xmlreader.IncrementalParser)
@anchor{library/xml sax reader xml sax xmlreader IncrementalParser reset}@anchor{4082}
@deffn {Μέθοδος} 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{4083}@anchor{library/xml sax reader locator-objects}@anchor{4084}
@subsubsection Locator Objects


Instances of @ref{4027,,Locator} provide these methods:

@geindex getColumnNumber() (μέθοδος της xml.sax.xmlreader.Locator)
@anchor{library/xml sax reader xml sax xmlreader Locator getColumnNumber}@anchor{4085}
@deffn {Μέθοδος} Locator.getColumnNumber ()

Return the column number where the current event begins.
@end deffn

@geindex getLineNumber() (μέθοδος της xml.sax.xmlreader.Locator)
@anchor{library/xml sax reader xml sax xmlreader Locator getLineNumber}@anchor{4086}
@deffn {Μέθοδος} Locator.getLineNumber ()

Return the line number where the current event begins.
@end deffn

@geindex getPublicId() (μέθοδος της xml.sax.xmlreader.Locator)
@anchor{library/xml sax reader xml sax xmlreader Locator getPublicId}@anchor{4087}
@deffn {Μέθοδος} Locator.getPublicId ()

Return the public identifier for the current event.
@end deffn

@geindex getSystemId() (μέθοδος της xml.sax.xmlreader.Locator)
@anchor{library/xml sax reader xml sax xmlreader Locator getSystemId}@anchor{4088}
@deffn {Μέθοδος} 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{4089}@anchor{library/xml sax reader inputsource-objects}@anchor{408a}
@subsubsection InputSource Objects


@geindex setPublicId() (μέθοδος της xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource setPublicId}@anchor{408b}
@deffn {Μέθοδος} InputSource.setPublicId (id)

Sets the public identifier of this @ref{124c,,InputSource}.
@end deffn

@geindex getPublicId() (μέθοδος της xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource getPublicId}@anchor{408c}
@deffn {Μέθοδος} InputSource.getPublicId ()

Returns the public identifier of this @ref{124c,,InputSource}.
@end deffn

@geindex setSystemId() (μέθοδος της xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource setSystemId}@anchor{408d}
@deffn {Μέθοδος} InputSource.setSystemId (id)

Sets the system identifier of this @ref{124c,,InputSource}.
@end deffn

@geindex getSystemId() (μέθοδος της xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource getSystemId}@anchor{408e}
@deffn {Μέθοδος} InputSource.getSystemId ()

Returns the system identifier of this @ref{124c,,InputSource}.
@end deffn

@geindex setEncoding() (μέθοδος της xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource setEncoding}@anchor{408f}
@deffn {Μέθοδος} InputSource.setEncoding (encoding)

Sets the character encoding of this @ref{124c,,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{124c,,InputSource} is ignored if the
@code{InputSource} also contains a character stream.
@end deffn

@geindex getEncoding() (μέθοδος της xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource getEncoding}@anchor{4090}
@deffn {Μέθοδος} InputSource.getEncoding ()

Get the character encoding of this InputSource.
@end deffn

@geindex setByteStream() (μέθοδος της xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource setByteStream}@anchor{4091}
@deffn {Μέθοδος} InputSource.setByteStream (bytefile)

Set the byte stream (a @ref{225d,,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() (μέθοδος της xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource getByteStream}@anchor{4092}
@deffn {Μέθοδος} 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() (μέθοδος της xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource setCharacterStream}@anchor{4093}
@deffn {Μέθοδος} InputSource.setCharacterStream (charfile)

Set the character stream (a @ref{225c,,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() (μέθοδος της xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource getCharacterStream}@anchor{4094}
@deffn {Μέθοδος} 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{4046}@anchor{library/xml sax reader the-attributes-interface}@anchor{4095}
@subsubsection The @code{Attributes} Interface


@code{Attributes} objects implement a portion of the @ref{1564,,mapping protocol}, including the methods @code{copy()},
@code{get()}, @ref{175c,,__contains__()},
@code{items()}, @code{keys()},
and @code{values()}.  The following methods
are also provided:

@geindex getLength() (μέθοδος της xml.sax.xmlreader.Attributes)
@anchor{library/xml sax reader xml sax xmlreader Attributes getLength}@anchor{4096}
@deffn {Μέθοδος} Attributes.getLength ()

Return the number of attributes.
@end deffn

@geindex getNames() (μέθοδος της xml.sax.xmlreader.Attributes)
@anchor{library/xml sax reader xml sax xmlreader Attributes getNames}@anchor{4097}
@deffn {Μέθοδος} Attributes.getNames ()

Return the names of the attributes.
@end deffn

@geindex getType() (μέθοδος της xml.sax.xmlreader.Attributes)
@anchor{library/xml sax reader xml sax xmlreader Attributes getType}@anchor{4098}
@deffn {Μέθοδος} Attributes.getType (name)

Returns the type of the attribute `name', which is normally @code{'CDATA'}.
@end deffn

@geindex getValue() (μέθοδος της xml.sax.xmlreader.Attributes)
@anchor{library/xml sax reader xml sax xmlreader Attributes getValue}@anchor{4099}
@deffn {Μέθοδος} 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{4048}@anchor{library/xml sax reader the-attributesns-interface}@anchor{409a}
@subsubsection The @code{AttributesNS} Interface


This interface is a subtype of the @code{Attributes} interface (see section
@ref{4046,,The Attributes Interface}).  All methods supported by that interface are also
available on @code{AttributesNS} objects.

The following methods are also available:

@geindex getValueByQName() (μέθοδος της xml.sax.xmlreader.AttributesNS)
@anchor{library/xml sax reader xml sax xmlreader AttributesNS getValueByQName}@anchor{409b}
@deffn {Μέθοδος} AttributesNS.getValueByQName (name)

Return the value for a qualified name.
@end deffn

@geindex getNameByQName() (μέθοδος της xml.sax.xmlreader.AttributesNS)
@anchor{library/xml sax reader xml sax xmlreader AttributesNS getNameByQName}@anchor{409c}
@deffn {Μέθοδος} AttributesNS.getNameByQName (name)

Return the @code{(namespace, localname)} pair for a qualified `name'.
@end deffn

@geindex getQNameByName() (μέθοδος της xml.sax.xmlreader.AttributesNS)
@anchor{library/xml sax reader xml sax xmlreader AttributesNS getQNameByName}@anchor{409d}
@deffn {Μέθοδος} AttributesNS.getQNameByName (name)

Return the qualified name for a @code{(namespace, localname)} pair.
@end deffn

@geindex getQNames() (μέθοδος της xml.sax.xmlreader.AttributesNS)
@anchor{library/xml sax reader xml sax xmlreader AttributesNS getQNames}@anchor{409e}
@deffn {Μέθοδος} AttributesNS.getQNames ()

Return the qualified names of all attributes.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xml parsers expat — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat,,xml sax xmlreader — Interface for XML parsers,Structured Markup Processing Tools
@anchor{library/pyexpat doc}@anchor{409f}@anchor{library/pyexpat module-xml parsers expat}@anchor{12f}@anchor{library/pyexpat translation-repo}@anchor{40a0}@anchor{library/pyexpat xml-parsers-expat-fast-xml-parsing-using-expat}@anchor{40a1}
@subsection @code{xml.parsers.expat} — Γρήγορη ανάλυση XML χρησιμοποιώντας το 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 Σημείωση 
Εάν χρειάζεται να αναλύσετε μη αξιόπιστα ή μη πιστοποιημένα δεδομένα, δείτε @ref{3f34,,XML security}.
@end quotation
@end cartouche

@geindex Expat

The @code{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

Αυτό το module χρησιμοποιεί το @code{pyexpat} module για να παρέχει πρόσβαση στον αναλυτή Expat. Η άμεση χρήση του @code{pyexpat} module δεν συνιστάται πλέον.

Αυτό το module παρέχει μια εξαίρεση και έναν τύπο αντικειμένου:

@geindex ExpatError
@anchor{library/pyexpat xml parsers expat ExpatError}@anchor{161d}
@deffn {Εξαίρεση} xml.parsers.expat.ExpatError

Η εξαίρεση γίνεται raise όταν το Expat αναφέρει ένα σφάλμα. Δείτε την ενότητα @ref{40a2,,Εξαιρέσεις ExpatError} για περισσότερες πληροφορίες σχετικά με την ερμηνεία σφαλμάτων Expat.
@end deffn

@geindex error
@anchor{library/pyexpat xml parsers expat error}@anchor{40a3}
@deffn {Εξαίρεση} xml.parsers.expat.error

Ψευδώνυμο για @ref{161d,,ExpatError}.
@end deffn

@geindex XMLParserType (στη μονάδα xml.parsers.expat)
@anchor{library/pyexpat xml parsers expat XMLParserType}@anchor{40a4}
@deffn {Δεδομένα} xml.parsers.expat.XMLParserType

Ο τύπος των τιμών επιστροφής από τη συνάρτηση @ref{40a5,,ParserCreate()}.
@end deffn

The @code{xml.parsers.expat} module contains two functions:

@geindex ErrorString() (στη μονάδα xml.parsers.expat)
@anchor{library/pyexpat xml parsers expat ErrorString}@anchor{40a6}
@deffn {Συνάρτηση} xml.parsers.expat.ErrorString (errno)

Επιστρέφει μια επεξηγηματική συμβολοσειρά για έναν δεδομένο αριθμό σφάλματος `errno'.
@end deffn

@geindex ParserCreate() (στη μονάδα xml.parsers.expat)
@anchor{library/pyexpat xml parsers expat ParserCreate}@anchor{40a5}
@deffn {Συνάρτηση} xml.parsers.expat.ParserCreate (encoding=None, namespace_separator=None)

Δημιουργεί και επιστρέφει ένα νέο αντικείμενο @code{xmlparser}. Το `encoding', εάν καθοριστεί, πρέπει να είναι μια συμβολοσειρά που ονομάζει την κωδικοποίηση που χρησιμοποιείται από τα δεδομένα XML. Το Expat δεν υποστηρίζει τόσες πολλές κωδικοποιήσεις όσες η Python, και το ρεπερτόριό του από κωδικοποιήσεις δεν μπορεί να επεκταθεί· υποστηρίζει UTF-8, UTF-16, ISO-8859-1 (Latin1) και ASCII. Εάν δοθεί το `encoding' @footnote{
Η συμβολοσειρά κωδικοποίησης που περιλαμβάνεται στην έξοδο XML θα πρέπει να συμμορφώνεται με τα κατάλληλα πρότυπα. Για παράδειγμα, το «UTF-8» είναι έγκυρο, αλλά το «UTF8» δεν είναι. Δείτε @indicateurl{https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl} και @indicateurl{https://www.iana.org/assignments/character-sets/character-sets.xhtml}.
}, θα αντικαταστήσει την έμμεση ή ρητή κωδικοποίηση του εγγράφου.
@anchor{library/pyexpat xmlparser-non-root}@anchor{40a7}
Οι αναλυτές που δημιουργούνται μέσω @code{ParserCreate()} ονομάζονται αναλυτές «ρίζας», με την έννοια ότι δεν έχουν συνδεδεμένο κανέναν γονικό αναλυτή. Οι μη ριζικοί αναλυτές δημιουργούνται από το @ref{1931,,parser.ExternalEntityParserCreate}.

Το Expat μπορεί προαιρετικά να κάνει επεξεργασία χώρων ονομάτων XML για εσάς, εφόσον ενεργοποιηθεί με την παροχή μιας τιμής στο `namespace_separator'. Η τιμή πρέπει να είναι μια συμβολοσειρά ενός χαρακτήρα· διαφορετικά θα γίνει raise μια @ref{277,,ValueError} εάν το μήκος της συμβολοσειράς είναι μη έγκυρο (το @code{None} θεωρείται το ίδιο με το να μην δοθεί καθόλου τιμή). Όταν είναι ενεργοποιημένη η επεξεργασία χώρων ονομάτων, τα ονόματα τύπων στοιχείων και τα ονόματα χαρακτηριστικών που ανήκουν σε έναν χώρο ονομάτων θα επεκταθούν. Το όνομα στοιχείου που περνάει στους χειριστές στοιχείων @code{StartElementHandler} και @code{EndElementHandler} θα είναι ο συνδυασμός του URI χώρου ονομάτων, του χαρακτήρα διαχωρισμού χώρου ονομάτων και του τοπικού μέρους του ονόματος. Εάν ο διαχωριστής χώρου ονομάτων είναι ένα μηδενικό byte (@code{chr(0)}) τότε το URI χώρου ονομάτων και το τοπικό μέρος θα συνδυαστούν χωρίς κανέναν διαχωριστή.

Για παράδειγμα, εάν το `namespace_separator' οριστεί σε χαρακτήρα κενό (@code{' '}) και αναλυθεί το ακόλουθο έγγραφο:

@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} θα λάβει τις ακόλουθες συμβολοσειρές για κάθε στοιχείο:

@example
http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2
@end example

Λόγω περιορισμών στη βιβλιοθήκη @code{Expat} που χρησιμοποιείται από το @code{pyexpat}, η αντικείμενη @code{xmlparser} που επιστρέφεται μπορεί να χρησιμοποιηθεί μόνο για την ανάλυση ενός μεμονωμένου εγγράφου XML. Καλέστε @code{ParserCreate} για κάθε έγγραφο για να παρέχετε μοναδικά στιγμιότυπα αναλυτών.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item The Expat XML Parser@footnote{http://www.libexpat.org/}

Αρχική σελίδα του έργου Expat.
@end table


@menu
* Αντικείμενα XMLParser:: 
* Εξαιρέσεις ExpatError:: 
* Παράδειγμα:: 
* Περιγραφές Μοντέλου Περιεχομένου:: 
* Σταθερές σφαλμάτων Expat:: 

@end menu

@node Αντικείμενα XMLParser,Εξαιρέσεις ExpatError,,xml parsers expat — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat
@anchor{library/pyexpat id2}@anchor{40a8}@anchor{library/pyexpat xmlparser-objects}@anchor{2b8}
@subsubsection Αντικείμενα XMLParser


Τα @code{xmlparser} αντικείμενα έχουν τις ακόλουθες μεθόδους:

@geindex Parse() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser Parse}@anchor{40a9}
@deffn {Μέθοδος} xmlparser.Parse (data[, isfinal])

Αναλύει τα περιεχόμενα της συμβολοσειράς `data', καλώντας τις κατάλληλες συναρτήσεις χειρισμού για την επεξεργασία των αναλυμένων δεδομένων. Το `isfinal' πρέπει να είναι true στην τελική κλήση αυτής της μεθόδου· επιτρέπει την ανάλυση ενός μεμονωμένου αρχείου σε θραύσματα, όχι την υποβολή πολλαπλών αρχείων. Το `data' μπορεί να είναι η κενή συμβολοσειρά οποιαδήποτε στιγμή.
@end deffn

@geindex ParseFile() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ParseFile}@anchor{40aa}
@deffn {Μέθοδος} xmlparser.ParseFile (file)

Αναλύει δεδομένα XML διαβάζοντας από το αντικείμενο `file'. Το `file' απαιτείται μόνο να παρέχει τη μέθοδο @code{read(nbytes)}, επιστρέφοντας την κενή συμβολοσειρά όταν δεν υπάρχουν άλλα δεδομένα.
@end deffn

@geindex SetBase() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser SetBase}@anchor{40ab}
@deffn {Μέθοδος} xmlparser.SetBase (base)

Ορίζει τη βάση που θα χρησιμοποιηθεί για την επίλυση σχετικών URI σε αναγνωριστικά συστήματος μέσα σε δηλώσεις. Η επίλυση σχετικών αναγνωριστικών αφήνεται στην εφαρμογή: αυτή η τιμή θα περαστεί ως όρισμα `base' στις συναρτήσεις @ref{40ac,,ExternalEntityRefHandler()}, @ref{40ad,,NotationDeclHandler()} και @ref{40ae,,UnparsedEntityDeclHandler()}.
@end deffn

@geindex GetBase() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser GetBase}@anchor{40af}
@deffn {Μέθοδος} xmlparser.GetBase ()

Επιστρέφει μια συμβολοσειρά που περιέχει τη βάση που ορίστηκε από μια προηγούμενη κλήση στο @ref{40ab,,SetBase()}, ή @code{None} εάν το @code{SetBase()} δεν έχει κληθεί.
@end deffn

@geindex GetInputContext() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser GetInputContext}@anchor{40b0}
@deffn {Μέθοδος} xmlparser.GetInputContext ()

Επιστρέφει τα δεδομένα εισόδου που δημιουργήθηκαν από το τρέχον γεγονός ως συμβολοσειρά. Τα δεδομένα είναι στην κωδικοποίηση της οντότητας που περιέχει το κείμενο. Όταν καλείται ενώ δεν είναι ενεργός κάποιος χειριστής γεγονότος, η τιμή επιστροφής είναι @code{None}.
@end deffn

@geindex ExternalEntityParserCreate() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ExternalEntityParserCreate}@anchor{1931}
@deffn {Μέθοδος} xmlparser.ExternalEntityParserCreate (context[, encoding])

Δημιουργεί έναν «θυγατρικό» αναλυτή που μπορεί να χρησιμοποιηθεί για την ανάλυση μιας εξωτερικής αναλυμένης οντότητας που αναφέρεται από το περιεχόμενο που αναλύεται από τον γονικό αναλυτή. Η παράμετρος `context' πρέπει να είναι η συμβολοσειρά που περνάει στη συνάρτηση χειρισμού @ref{40ac,,ExternalEntityRefHandler()}, που περιγράφεται παρακάτω. Ο παιδικός αναλυτής δημιουργείται με τα @ref{40b1,,ordered_attributes} και @ref{40b2,,specified_attributes} ορισμένα στις τιμές αυτού του αναλυτή.
@end deffn

@geindex SetParamEntityParsing() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser SetParamEntityParsing}@anchor{40b3}
@deffn {Μέθοδος} xmlparser.SetParamEntityParsing (flag)

Ελέγχει την ανάλυση των οντοτήτων παραμέτρων (συμπεριλαμβανομένου του εξωτερικού υποσυνόλου DTD). Οι πιθανές τιμές `flag' είναι @code{XML_PARAM_ENTITY_PARSING_NEVER}, @code{XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE} και @code{XML_PARAM_ENTITY_PARSING_ALWAYS}. Επιστρέφει true εάν ο ορισμός της σημαίας ήταν επιτυχής.
@end deffn

@geindex UseForeignDTD() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser UseForeignDTD}@anchor{40b4}
@deffn {Μέθοδος} xmlparser.UseForeignDTD ([flag])

Η κλήση αυτού με μια αληθή τιμή για το `flag' (η προεπιλογή) θα προκαλέσει το Expat να καλέσει το @ref{40ac,,ExternalEntityRefHandler} με @ref{a65,,None} για όλα τα ορίσματα για να επιτρέψει τη φόρτωση ενός εναλλακτικού DTD. Εάν το έγγραφο δεν περιέχει δήλωση τύπου εγγράφου, το @code{ExternalEntityRefHandler} θα κληθεί ακόμα, αλλά το @ref{40b5,,StartDoctypeDeclHandler} και @ref{40b6,,EndDoctypeDeclHandler} δεν θα κληθούν.

Η μετάδοση μιας ψευδούς τιμής για το `flag' θα ακυρώσει μια προηγούμενη κλήση που πέρασε μια αληθή τιμή, αλλά διαφορετικά δεν έχει καμία επίδραση.

Αυτή η μέθοδος μπορεί να κληθεί μόνο πριν κληθούν οι μέθοδοι @ref{40a9,,Parse()} ή @ref{40aa,,ParseFile()}; η κλήση της μετά από οποιαδήποτε από αυτές θα προκαλέσει @ref{161d,,ExpatError} να γίνει raise με το χαρακτηριστικό @ref{1b,,code} ορισμένο σε @code{errors.codes[errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING]}.
@end deffn

@geindex SetReparseDeferralEnabled() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser SetReparseDeferralEnabled}@anchor{77a}
@deffn {Μέθοδος} xmlparser.SetReparseDeferralEnabled (enabled)

@cartouche
@quotation Προειδοποίηση 
Η κλήση @code{SetReparseDeferralEnabled(False)} έχει επιπτώσεις στην ασφάλεια, όπως αναλυτικά παρακάτω· βεβαιωθείτε ότι κατανοείτε αυτές τις συνέπειες πριν από τη χρήση της μεθόδου @code{SetReparseDeferralEnabled}.
@end quotation
@end cartouche

Το Expat 2.6.0 εισήγαγε έναν μηχανισμό ασφάλειας που ονομάζεται «αναβολή επανεπεξεργασίας» όπου αντί να προκαλείται άρνηση υπηρεσίας μέσω τετραγωνικού χρόνου εκτέλεσης από την επανεπεξεργασία μεγάλων token, η επανεπεξεργασία μη ολοκληρωμένων token τώρα καθυστερείται από προεπιλογή μέχρι να φτάσει μια επαρκής ποσότητα εισόδου. Λόγω αυτής της καθυστέρησης, οι καταχωρημένοι χειριστές μπορεί — ανάλογα με το μέγεθος των τμημάτων εισόδου που ωθούνται στο Expat — να μην καλούνται αμέσως μετά την ώθηση νέας εισόδου στον αναλυτή. Όπου επιθυμείται άμεση ανατροφοδότηση και ανάληψη ευθύνης για την προστασία από την άρνηση υπηρεσίας από μεγάλα token, η κλήση @code{SetReparseDeferralEnabled(False)} απενεργοποιεί την αναβολή επανεπεξεργασίας για το τρέχον στιγμιότυπο αναλυτή Expat, προσωρινά ή συνολικά. Η κλήση @code{SetReparseDeferralEnabled(True)} επιτρέπει την επανενεργοποίηση της αναβολής επανεπεξεργασίας.

@code{SetReparseDeferralEnabled()}
has been backported to some prior releases of CPython as a security fix.
Check for availability using @ref{8e2,,hasattr()} if used in code running
across a variety of Python versions.


Added in version 3.13.

@end deffn

@geindex GetReparseDeferralEnabled() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser GetReparseDeferralEnabled}@anchor{779}
@deffn {Μέθοδος} xmlparser.GetReparseDeferralEnabled ()

Επιστρέφει εάν η αναβολή επανεπεξεργασίας είναι επί του παρόντος ενεργοποιημένη για το δεδομένο στιγμιότυπο αναλυτή Expat.


Added in version 3.13.

@end deffn

@code{xmlparser} objects have the following methods to tune protections
against some common XML vulnerabilities.

@geindex SetBillionLaughsAttackProtectionActivationThreshold() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser SetBillionLaughsAttackProtectionActivationThreshold}@anchor{2b9}
@deffn {Μέθοδος} xmlparser.SetBillionLaughsAttackProtectionActivationThreshold (threshold, /)

Sets the number of output bytes needed to activate protection against
billion laughs@footnote{https://en.wikipedia.org/wiki/Billion_laughs_attack} attacks.

The number of output bytes includes amplification from entity expansion
and reading DTD files.

Parser objects usually have a protection activation threshold of 8 MiB,
but the actual default value depends on the underlying Expat library.

Γίνεται raise @ref{161d,,ExpatError} εάν αυτή η μέθοδος κληθεί σε έναν @ref{40a7,,non-root} αναλυτή. Τα αντίστοιχα @ref{40b7,,lineno} και @ref{40b8,,offset} δεν πρέπει να χρησιμοποιούνται καθώς μπορεί να μην έχουν καμία ειδική σημασία.

@code{SetBillionLaughsAttackProtectionActivationThreshold()}
has been backported to some prior releases of CPython as a security fix.
Check for availability using @ref{8e2,,hasattr()} if used in code running
across a variety of Python versions.

@cartouche
@quotation Σημείωση 
Activation thresholds below 4 MiB are known to break support for DITA 1.3
payload and are hence not recommended.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn

@geindex SetBillionLaughsAttackProtectionMaximumAmplification() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser SetBillionLaughsAttackProtectionMaximumAmplification}@anchor{2ba}
@deffn {Μέθοδος} xmlparser.SetBillionLaughsAttackProtectionMaximumAmplification (max_factor, /)

Sets the maximum tolerated amplification factor for protection against
billion laughs@footnote{https://en.wikipedia.org/wiki/Billion_laughs_attack} attacks.

The amplification factor is calculated as @code{(direct + indirect) / direct}
while parsing, where @code{direct} is the number of bytes read from
the primary document in parsing and @code{indirect} is the number of
bytes added by expanding entities and reading of external DTD files.

The `max_factor' value must be a non-NaN @ref{327,,float} value greater than
or equal to 1.0. Peak amplifications of factor 15,000 for the entire payload
and of factor 30,000 in the middle of parsing have been observed with small
benign files in practice. In particular, the activation threshold should be
carefully chosen to avoid false positives.

Parser objects usually have a maximum amplification factor of 100,
but the actual default value depends on the underlying Expat library.

Γίνεται raise @ref{161d,,ExpatError} εάν αυτή η μέθοδος κληθεί σε έναν @ref{40a7,,non-root} αναλυτή ή εάν το `max_factor' είναι εκτός του έγκυρου εύρους. Τα αντίστοιχα @ref{40b7,,lineno} και @ref{40b8,,offset} δεν πρέπει να χρησιμοποιούνται καθώς μπορεί να μην έχουν καμία ειδική σημασία.

@code{SetBillionLaughsAttackProtectionMaximumAmplification()}
has been backported to some prior releases of CPython as a security fix.
Check for availability using @ref{8e2,,hasattr()} if used in code running
across a variety of Python versions.

@cartouche
@quotation Σημείωση 
The maximum amplification factor is only considered if the threshold
that can be adjusted by @ref{2b9,,SetBillionLaughsAttackProtectionActivationThreshold()}
is exceeded.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn

@geindex SetAllocTrackerActivationThreshold() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser SetAllocTrackerActivationThreshold}@anchor{2b6}
@deffn {Μέθοδος} xmlparser.SetAllocTrackerActivationThreshold (threshold, /)

Ορίζει τον αριθμό των δεσμευμένων byte δυναμικής μνήμης που απαιτούνται για την ενεργοποίηση της προστασίας κατά της δυσανάλογης χρήσης RAM.

Parser objects usually have an allocation activation threshold of 64 MiB,
but the actual default value depends on the underlying Expat library.

Γίνεται raise @ref{161d,,ExpatError} εάν αυτή η μέθοδος κληθεί σε έναν @ref{40a7,,non-root} αναλυτή. Τα αντίστοιχα @ref{40b7,,lineno} και @ref{40b8,,offset} δεν πρέπει να χρησιμοποιούνται καθώς μπορεί να μην έχουν καμία ειδική σημασία.

@code{SetAllocTrackerActivationThreshold()}
has been backported to some prior releases of CPython as a security fix.
Check for availability using @ref{8e2,,hasattr()} if used in code running
across a variety of Python versions.


Added in version 3.15.

@end deffn

@geindex SetAllocTrackerMaximumAmplification() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser SetAllocTrackerMaximumAmplification}@anchor{2b7}
@deffn {Μέθοδος} xmlparser.SetAllocTrackerMaximumAmplification (max_factor, /)

Ορίζει τον μέγιστο παράγοντα ενίσχυσης μεταξύ άμεσης εισόδου και byte δυναμικής μνήμης που έχουν δεσμευτεί.

Ο παράγοντας ενίσχυσης υπολογίζεται ως @code{allocated / direct} κατά την ανάλυση, όπου το @code{direct} είναι ο αριθμός των byte που διαβάστηκαν από το κύριο έγγραφο στην ανάλυση και το @code{allocated} είναι ο αριθμός των byte δυναμικής μνήμης που έχουν δεσμευτεί στην ιεραρχία αναλυτών.

Η τιμή `max_factor' πρέπει να είναι μια μη-NaN @ref{327,,float} τιμή μεγαλύτερη ή ίση του 1.0. Παράγοντες ενίσχυσης μεγαλύτεροι από 100.0 μπορούν να παρατηρηθούν κοντά στην αρχή της ανάλυσης ακόμη και με ακίνδυνα αρχεία στην πράξη. Ειδικότερα, το όριο ενεργοποίησης πρέπει να επιλεγεί προσεκτικά για να αποφευχθούν ψευδώς θετικά.

Parser objects usually have a maximum amplification factor of 100,
but the actual default value depends on the underlying Expat library.

Γίνεται raise @ref{161d,,ExpatError} εάν αυτή η μέθοδος κληθεί σε έναν @ref{40a7,,non-root} αναλυτή ή εάν το `max_factor' είναι εκτός του έγκυρου εύρους. Τα αντίστοιχα @ref{40b7,,lineno} και @ref{40b8,,offset} δεν πρέπει να χρησιμοποιούνται καθώς μπορεί να μην έχουν καμία ειδική σημασία.

@code{SetAllocTrackerMaximumAmplification()}
has been backported to some prior releases of CPython as a security fix.
Check for availability using @ref{8e2,,hasattr()} if used in code running
across a variety of Python versions.

@cartouche
@quotation Σημείωση 
Ο μέγιστος παράγοντας ενίσχυσης λαμβάνεται υπόψιν μόνο εάν ξεπεραστεί το όριο ενεργοποίησης που μπορεί να προσαρμοστεί από το @ref{2b6,,SetAllocTrackerActivationThreshold()}.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn

Τα @code{xmlparser} αντικείμενα έχουν τα ακόλουθα χαρακτηριστικά:

@geindex buffer_size (ιδιότητα της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser buffer_size}@anchor{40b9}
@deffn {Ιδιότητα} xmlparser.buffer_size

Το μέγεθος του buffer που χρησιμοποιείται όταν το @ref{1864,,buffer_text} είναι true. Ένα νέο μέγεθος buffer μπορεί να οριστεί εκχωρώντας μια νέα ακέραια τιμή σε αυτό το χαρακτηριστικό. Όταν αλλάζει το μέγεθος, το buffer θα εκκενωθεί.
@end deffn

@geindex buffer_text (ιδιότητα της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser buffer_text}@anchor{1864}
@deffn {Ιδιότητα} xmlparser.buffer_text

Ο ορισμός αυτού σε true προκαλεί το αντικείμενο @code{xmlparser} να αποθηκεύει σε buffer το κειμενικό περιεχόμενο που επιστρέφεται από το Expat για να αποφευχθούν πολλαπλές κλήσεις στην ανάκληση @ref{40ba,,CharacterDataHandler()} όποτε είναι δυνατόν. Αυτό μπορεί να βελτιώσει σημαντικά την απόδοση καθώς το Expat κανονικά διασπά τα δεδομένα χαρακτήρων σε θραύσματα σε κάθε αλλαγή γραμμής. Αυτό το χαρακτηριστικό είναι false από προεπιλογή, και μπορεί να αλλάξει οποιαδήποτε στιγμή. Σημειώστε ότι όταν είναι false, τα δεδομένα που δεν περιέχουν αλλαγές γραμμών μπορεί επίσης να διασπαστούν.
@end deffn

@geindex buffer_used (ιδιότητα της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser buffer_used}@anchor{40bb}
@deffn {Ιδιότητα} xmlparser.buffer_used

Εάν το @ref{1864,,buffer_text} είναι ενεργοποιημένο, ο αριθμός των byte που αποθηκεύονται στο buffer. Αυτά τα byte αντιπροσωπεύουν κείμενο κωδικοποιημένο σε UTF-8. Αυτό το χαρακτηριστικό δεν έχει καμία ουσιαστική ερμηνεία όταν το @code{buffer_text} είναι false.
@end deffn

@geindex ordered_attributes (ιδιότητα της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ordered_attributes}@anchor{40b1}
@deffn {Ιδιότητα} xmlparser.ordered_attributes

Ο ορισμός αυτού του χαρακτηριστικού σε έναν μη μηδενικό ακέραιο προκαλεί τα χαρακτηριστικά να αναφέρονται ως λίστα αντί για λεξικό. Τα χαρακτηριστικά παρουσιάζονται με τη σειρά που βρέθηκαν στο κείμενο του εγγράφου. Για κάθε χαρακτηριστικό, παρουσιάζονται δύο καταχωρήσεις λίστας: το όνομα του χαρακτηριστικού και η τιμή του χαρακτηριστικού. (Παλαιότερες εκδόσεις αυτού του module χρησιμοποιούσαν επίσης αυτή τη μορφή.) Από προεπιλογή, αυτό το χαρακτηριστικό είναι false· μπορεί να αλλάξει οποιαδήποτε στιγμή.
@end deffn

@geindex specified_attributes (ιδιότητα της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser specified_attributes}@anchor{40b2}
@deffn {Ιδιότητα} xmlparser.specified_attributes

Εάν οριστεί σε έναν μη μηδενικό ακέραιο, ο αναλυτής θα αναφέρει μόνο εκείνα τα χαρακτηριστικά που καθορίστηκαν στο παράδειγμα εγγράφου και όχι εκείνα που προέκυψαν από δηλώσεις χαρακτηριστικών. Οι εφαρμογές που το ορίζουν αυτό πρέπει να είναι ιδιαίτερα προσεκτικές στη χρήση των πρόσθετων πληροφοριών που είναι διαθέσιμες από τις δηλώσεις όπως απαιτείται για τη συμμόρφωση με τα πρότυπα για τη συμπεριφορά των επεξεργαστών XML. Από προεπιλογή, αυτό το χαρακτηριστικό είναι false· μπορεί να αλλάξει οποιαδήποτε στιγμή.
@end deffn

Τα ακόλουθα χαρακτηριστικά περιέχουν τιμές που σχετίζονται με το πιο πρόσφατο σφάλμα που αντιμετωπίστηκε από ένα αντικείμενο @code{xmlparser}, και θα έχουν σωστές τιμές μόνο όταν μια κλήση στο @code{Parse()} ή @code{ParseFile()} έχει προκαλέσει μια εξαίρεση @ref{161d,,xml.parsers.expat.ExpatError}.

@geindex ErrorByteIndex (ιδιότητα της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ErrorByteIndex}@anchor{40bc}
@deffn {Ιδιότητα} xmlparser.ErrorByteIndex

Δείκτης byte στον οποίο συνέβη ένα σφάλμα.
@end deffn

@geindex ErrorCode (ιδιότητα της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ErrorCode}@anchor{40bd}
@deffn {Ιδιότητα} xmlparser.ErrorCode

Αριθμητικός κωδικός που προσδιορίζει το πρόβλημα. Αυτή η τιμή μπορεί να περαστεί στη συνάρτηση @ref{40a6,,ErrorString()}, ή να συγκριθεί με μία από τις σταθερές που ορίζονται στο αντικείμενο @code{errors}.
@end deffn

@geindex ErrorColumnNumber (ιδιότητα της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ErrorColumnNumber}@anchor{40be}
@deffn {Ιδιότητα} xmlparser.ErrorColumnNumber

Αριθμός στήλης στον οποίο συνέβη ένα σφάλμα.
@end deffn

@geindex ErrorLineNumber (ιδιότητα της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ErrorLineNumber}@anchor{40bf}
@deffn {Ιδιότητα} xmlparser.ErrorLineNumber

Αριθμός γραμμής στον οποίο συνέβη ένα σφάλμα.
@end deffn

Τα ακόλουθα χαρακτηριστικά περιέχουν τιμές που σχετίζονται με την τρέχουσα θέση ανάλυσης σε ένα αντικείμενο @code{xmlparser}. Κατά τη διάρκεια μιας ανάκλησης που αναφέρει ένα γεγονός ανάλυσης, υποδεικνύουν τη θέση της πρώτης από τη σειρά χαρακτήρων που δημιούργησαν το γεγονός. Όταν καλείται εκτός μιας ανάκλησης, η υποδεικνυόμενη θέση θα είναι ακριβώς μετά το τελευταίο γεγονός ανάλυσης (ανεξάρτητα από το αν υπήρχε μια σχετική ανάκληση).

@geindex CurrentByteIndex (ιδιότητα της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser CurrentByteIndex}@anchor{40c0}
@deffn {Ιδιότητα} xmlparser.CurrentByteIndex

Τρέχων δείκτης byte στην είσοδο του αναλυτή.
@end deffn

@geindex CurrentColumnNumber (ιδιότητα της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser CurrentColumnNumber}@anchor{40c1}
@deffn {Ιδιότητα} xmlparser.CurrentColumnNumber

Τρέχων αριθμός στήλης στην είσοδο του αναλυτή.
@end deffn

@geindex CurrentLineNumber (ιδιότητα της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser CurrentLineNumber}@anchor{40c2}
@deffn {Ιδιότητα} xmlparser.CurrentLineNumber

Τρέχων αριθμός γραμμής στην είσοδο του αναλυτή.
@end deffn

Εδώ είναι η λίστα των χειριστών που μπορούν να οριστούν. Για να ορίσετε έναν χειριστή σε ένα αντικείμενο @code{xmlparser} `o', χρησιμοποιήστε @code{o.handlername = func}. Το `handlername' πρέπει να ληφθεί από την ακόλουθη λίστα, και το `func' πρέπει να είναι ένα αντικείμενο που μπορεί να κληθεί αποδεχόμενο τον σωστό αριθμό ορισμάτων. Τα ορίσματα είναι όλες συμβολοσειρές, εκτός εάν αναφέρεται διαφορετικά.

@geindex XmlDeclHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser XmlDeclHandler}@anchor{40c3}
@deffn {Μέθοδος} xmlparser.XmlDeclHandler (version, encoding, standalone)

Καλείται όταν αναλύεται η δήλωση XML. Η δήλωση XML είναι η (προαιρετική) δήλωση της εφαρμοστέας έκδοσης της σύστασης XML, της κωδικοποίησης του κειμένου του εγγράφου, και μια προαιρετική «αυτόνομη» δήλωση. Το `version' και το `encoding' θα είναι συμβολοσειρές, και το `standalone' θα είναι @code{1} εάν το έγγραφο δηλώνεται αυτόνομο, @code{0} εάν δηλώνεται ότι δεν είναι αυτόνομο, ή @code{-1} εάν η ρήτρα αυτόνομης παραλείφθηκε. Αυτό είναι διαθέσιμο μόνο με την έκδοση 1.95.0 ή νεότερη του Expat.
@end deffn

@geindex StartDoctypeDeclHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser StartDoctypeDeclHandler}@anchor{40b5}
@deffn {Μέθοδος} 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 an internal document declaration subset. This requires Expat version
1.2 or newer.
@end deffn

@geindex EndDoctypeDeclHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser EndDoctypeDeclHandler}@anchor{40b6}
@deffn {Μέθοδος} xmlparser.EndDoctypeDeclHandler ()

Καλείται όταν το Expat ολοκληρώνει την ανάλυση της δήλωσης τύπου εγγράφου. Αυτό απαιτεί Expat έκδοσης 1.2 ή νεότερης.
@end deffn

@geindex ElementDeclHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ElementDeclHandler}@anchor{1922}
@deffn {Μέθοδος} xmlparser.ElementDeclHandler (name, model)

Καλείται μία φορά για κάθε δήλωση τύπου στοιχείου. Το `name' είναι το όνομα του τύπου στοιχείου, και το `model' είναι μια αναπαράσταση του μοντέλου περιεχομένου.
@end deffn

@geindex AttlistDeclHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser AttlistDeclHandler}@anchor{40c4}
@deffn {Μέθοδος} xmlparser.AttlistDeclHandler (elname, attname, type, default, required)

Καλείται για κάθε δηλωμένο χαρακτηριστικό για έναν τύπο στοιχείου. Εάν μια δήλωση λίστας χαρακτηριστικών δηλώνει τρία χαρακτηριστικά, αυτός ο χειριστής καλείται τρεις φορές, μία για κάθε χαρακτηριστικό. Το `elname' είναι το όνομα του στοιχείου στο οποίο εφαρμόζεται η δήλωση και το `attname' είναι το όνομα του δηλωμένου χαρακτηριστικού. Ο τύπος χαρακτηριστικού είναι μια συμβολοσειρά που περνάει ως `type'· οι πιθανές τιμές είναι @code{'CDATA'}, @code{'ID'}, @code{'IDREF'}, … το `default' δίνει την προεπιλεγμένη τιμή για το χαρακτηριστικό που χρησιμοποιείται όταν το χαρακτηριστικό δεν καθορίζεται από το παράδειγμα εγγράφου, ή @code{None} εάν δεν υπάρχει προεπιλεγμένη τιμή (τιμές @code{#IMPLIED}). Εάν το χαρακτηριστικό απαιτείται να δοθεί στο παράδειγμα εγγράφου, το `required' θα είναι true. Αυτό απαιτεί Expat έκδοση 1.95.0 ή νεότερης.
@end deffn

@geindex StartElementHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser StartElementHandler}@anchor{40c5}
@deffn {Μέθοδος} xmlparser.StartElementHandler (name, attributes)

Καλείται για την έναρξη κάθε στοιχείου. Το `name' είναι μια συμβολοσειρά που περιέχει το όνομα του στοιχείου, και το `attributes' είναι τα χαρακτηριστικά του στοιχείου. Εάν το @ref{40b1,,ordered_attributes} είναι true, αυτό είναι μια λίστα (δείτε το @code{ordered_attributes} για μια πλήρη περιγραφή). Διαφορετικά είναι ένα λεξικό που αντιστοιχίζει ονόματα σε τιμές.
@end deffn

@geindex EndElementHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser EndElementHandler}@anchor{40c6}
@deffn {Μέθοδος} xmlparser.EndElementHandler (name)

Καλείται για το τέλος κάθε στοιχείου.
@end deffn

@geindex ProcessingInstructionHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ProcessingInstructionHandler}@anchor{40c7}
@deffn {Μέθοδος} xmlparser.ProcessingInstructionHandler (target, data)

Καλείται για κάθε οδηγία επεξεργασίας.
@end deffn

@geindex CharacterDataHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser CharacterDataHandler}@anchor{40ba}
@deffn {Μέθοδος} xmlparser.CharacterDataHandler (data)

Καλείται για δεδομένα χαρακτήρων. Αυτό θα κληθεί για κανονικά δεδομένα χαρακτήρων, περιεχόμενο επισημασμένο ως CDATA, και αγνοήσιμο κενό χώρο. Οι εφαρμογές που πρέπει να διακρίνουν αυτές τις περιπτώσεις μπορούν να χρησιμοποιήσουν τις ανακλήσεις @ref{40c8,,StartCdataSectionHandler}, @ref{40c9,,EndCdataSectionHandler}, και @ref{1922,,ElementDeclHandler} για να συλλέξουν τις απαιτούμενες πληροφορίες. Σημειώστε ότι τα δεδομένα χαρακτήρων μπορεί να διασπαστούν ακόμη και αν είναι μικρά και έτσι μπορεί να λάβετε περισσότερες από μία κλήσεις στο @ref{40ba,,CharacterDataHandler()}. Ορίστε το χαρακτηριστικό στιγμιότυπου @ref{1864,,buffer_text} σε @code{True} για να αποφύγετε αυτό.
@end deffn

@geindex UnparsedEntityDeclHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser UnparsedEntityDeclHandler}@anchor{40ae}
@deffn {Μέθοδος} xmlparser.UnparsedEntityDeclHandler (entityName, base, systemId, publicId, notationName)

Καλείται για δηλώσεις μη αναλυμένων (NDATA) οντοτήτων. Αυτό είναι παρόν μόνο για την έκδοση 1.2 της βιβλιοθήκης Expat· για πιο πρόσφατες εκδόσεις, χρησιμοποιήστε @ref{40ca,,EntityDeclHandler} αντ” αυτού. (Η υποκείμενη λειτουργία στη βιβλιοθήκη Expat έχει κηρυχθεί απαρχαιωμένη.)
@end deffn

@geindex EntityDeclHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser EntityDeclHandler}@anchor{40ca}
@deffn {Μέθοδος} xmlparser.EntityDeclHandler (entityName, is_parameter_entity, value, base, systemId, publicId, notationName)

Καλείται για όλες τις δηλώσεις οντοτήτων. Για παραμετρικές και εσωτερικές οντότητες, το `value' θα είναι μια συμβολοσειρά που δίνει τα δηλωμένα περιεχόμενα της οντότητας· αυτό θα είναι @code{None} για εξωτερικές οντότητες. Η παράμετρος `notationName' θα είναι @code{None} για αναλυμένες οντότητες, και το όνομα της σημειογραφίας για μη αναλυμένες οντότητες. Το `is_parameter_entity' θα είναι true εάν η οντότητα είναι μια παραμετρική οντότητα ή false για γενικές οντότητες (οι περισσότερες εφαρμογές χρειάζεται να ασχολούνται μόνο με γενικές οντότητες). Αυτό είναι διαθέσιμο μόνο ξεκινώντας από την έκδοση 1.95.0 της βιβλιοθήκης Expat.
@end deffn

@geindex NotationDeclHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser NotationDeclHandler}@anchor{40ad}
@deffn {Μέθοδος} xmlparser.NotationDeclHandler (notationName, base, systemId, publicId)

Καλείται για δηλώσεις σημειογραφίας. Το `notationName', `base', και `systemId', και `publicId' είναι συμβολοσειρές εάν δίνονται. Εάν το δημόσιο αναγνωριστικό παραλείπεται, το `publicId' θα είναι @code{None}.
@end deffn

@geindex StartNamespaceDeclHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser StartNamespaceDeclHandler}@anchor{40cb}
@deffn {Μέθοδος} xmlparser.StartNamespaceDeclHandler (prefix, uri)

Καλείται όταν ένα στοιχείο περιέχει μια δήλωση χώρου ονομάτων. Οι δηλώσεις χώρων ονομάτων επεξεργάζονται πριν κληθεί ο @ref{40c5,,StartElementHandler} για το στοιχείο στο οποίο τοποθετούνται οι δηλώσεις.
@end deffn

@geindex EndNamespaceDeclHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser EndNamespaceDeclHandler}@anchor{40cc}
@deffn {Μέθοδος} xmlparser.EndNamespaceDeclHandler (prefix)

Καλείται όταν επιτευχθεί η ετικέτα κλεισίματος για ένα στοιχείο που περιείχε μια δήλωση χώρου ονομάτων. Αυτό καλείται μία φορά για κάθε δήλωση χώρου ονομάτων στο στοιχείο με την αντίστροφη σειρά για την οποία κλήθηκε ο @ref{40cb,,StartNamespaceDeclHandler} για να υποδείξει την έναρξη της εμβέλειας κάθε δήλωσης χώρου ονομάτων. Οι κλήσεις σε αυτόν τον χειριστή γίνονται μετά τον αντίστοιχο @ref{40c6,,EndElementHandler} για το τέλος του στοιχείου.
@end deffn

@geindex CommentHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser CommentHandler}@anchor{40cd}
@deffn {Μέθοδος} xmlparser.CommentHandler (data)

Καλείται για σχόλια. Το `data' είναι το κείμενο του σχολίου, εξαιρώντας το προκαταρκτικό @code{'<!-}@code{-'} και το τελικό @code{'-}@code{->'}.
@end deffn

@geindex StartCdataSectionHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser StartCdataSectionHandler}@anchor{40c8}
@deffn {Μέθοδος} xmlparser.StartCdataSectionHandler ()

Καλείται στην αρχή μιας ενότητας CDATA. Αυτό και το @ref{40c9,,EndCdataSectionHandler} είναι απαραίτητα για να μπορέσουμε να αναγνωρίσουμε την συντακτική έναρξη και το τέλος για τις ενότητες CDATA.
@end deffn

@geindex EndCdataSectionHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser EndCdataSectionHandler}@anchor{40c9}
@deffn {Μέθοδος} xmlparser.EndCdataSectionHandler ()

Καλείται στο τέλος μιας ενότητας CDATA.
@end deffn

@geindex DefaultHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser DefaultHandler}@anchor{40ce}
@deffn {Μέθοδος} xmlparser.DefaultHandler (data)

Καλείται για οποιουσδήποτε χαρακτήρες στο έγγραφο XML για τους οποίους δεν έχει οριστεί κάποιος κατάλληλος χειριστής. Αυτό σημαίνει χαρακτήρες που είναι μέρος μιας κατασκευής που θα μπορούσε να αναφερθεί, αλλά για την οποία δεν έχει παρασχεθεί χειριστής.
@end deffn

@geindex DefaultHandlerExpand() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser DefaultHandlerExpand}@anchor{40cf}
@deffn {Μέθοδος} xmlparser.DefaultHandlerExpand (data)

Αυτό είναι το ίδιο με το @ref{40ce,,DefaultHandler()}, αλλά δεν εμποδίζει την επέκταση εσωτερικών οντοτήτων. Η αναφορά οντότητας δεν θα περαστεί στον προεπιλεγμένο χειριστή.
@end deffn

@geindex NotStandaloneHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser NotStandaloneHandler}@anchor{40d0}
@deffn {Μέθοδος} xmlparser.NotStandaloneHandler ()

Καλείται εάν το έγγραφο XML δεν έχει δηλωθεί ως αυτόνομο έγγραφο. Αυτό συμβαίνει όταν υπάρχει ένα εξωτερικό υποσύνολο ή μια αναφορά σε μια παραμετρική οντότητα, αλλά η δήλωση XML δεν ορίζει το standalone σε @code{yes} σε μια δήλωση XML. Εάν αυτός ο χειριστής επιστρέψει @code{0}, τότε ο αναλυτής θα προκαλέσει ένα σφάλμα @code{XML_ERROR_NOT_STANDALONE}. Εάν αυτός ο χειριστής δεν έχει οριστεί, δεν γίνεται raise καμία εξαίρεση από τον αναλυτή για αυτή την κατάσταση.
@end deffn

@geindex ExternalEntityRefHandler() (μέθοδος της xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ExternalEntityRefHandler}@anchor{40ac}
@deffn {Μέθοδος} xmlparser.ExternalEntityRefHandler (context, base, systemId, publicId)

@cartouche
@quotation Προειδοποίηση 
Η υλοποίηση ενός χειριστή που έχει πρόσβαση σε τοπικά αρχεία και/ή στο δίκτυο μπορεί να δημιουργήσει μια ευπάθεια σε @cite{external entity attacks <https://en.wikipedia.org/wiki/XML_external_entity_attack>} εάν το @code{xmlparser} χρησιμοποιείται με περιεχόμενο XML που παρέχεται από τον χρήστη. Σκεφτείτε το threat model@footnote{https://en.wikipedia.org/wiki/Threat_model} σας πριν υλοποιήσετε αυτόν τον χειριστή.
@end quotation
@end cartouche

Καλείται για αναφορές σε εξωτερικές οντότητες. Το `base' είναι η τρέχουσα βάση, όπως ορίζεται από μια προηγούμενη κλήση στο @ref{40ab,,SetBase()}. Τα δημόσια και συστημικά αναγνωριστικά, `systemId' και `publicId', είναι συμβολοσειρές εάν δίνονται· εάν το δημόσιο αναγνωριστικό δεν δίνεται, το `publicId' θα είναι @code{None}. Η τιμή `context' είναι αδιαφανής και πρέπει να χρησιμοποιείται μόνο όπως περιγράφεται παρακάτω.

Για να αναλυθούν εξωτερικές οντότητες, αυτός ο χειριστής πρέπει να υλοποιηθεί. Είναι υπεύθυνος για τη δημιουργία του υπο-αναλυτή χρησιμοποιώντας @code{ExternalEntityParserCreate(context)}, την αρχικοποίηση του με τις κατάλληλες ανακλήσεις, και την ανάλυση της οντότητας. Αυτός ο χειριστής πρέπει να επιστρέψει έναν ακέραιο· εάν επιστρέψει @code{0}, ο αναλυτής θα προκαλέσει ένα σφάλμα @code{XML_ERROR_EXTERNAL_ENTITY_HANDLING}, διαφορετικά η ανάλυση θα συνεχιστεί.

Εάν αυτός ο χειριστής δεν παρέχεται, οι εξωτερικές οντότητες αναφέρονται από την ανάκληση @ref{40ce,,DefaultHandler}, εάν παρέχεται.
@end deffn

@node Εξαιρέσεις ExpatError,Παράδειγμα,Αντικείμενα XMLParser,xml parsers expat — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat
@anchor{library/pyexpat expaterror-exceptions}@anchor{40d1}@anchor{library/pyexpat expaterror-objects}@anchor{40a2}
@subsubsection Εξαιρέσεις ExpatError


Οι εξαιρέσεις @ref{161d,,ExpatError} έχουν έναν αριθμό ενδιαφερόντων χαρακτηριστικών:

@geindex code (ιδιότητα της xml.parsers.expat.ExpatError)
@anchor{library/pyexpat xml parsers expat ExpatError code}@anchor{40d2}
@deffn {Ιδιότητα} ExpatError.code

Ο εσωτερικός αριθμός σφάλματος του Expat για το συγκεκριμένο σφάλμα. Το @ref{40d3,,errors.messages} λεξικό αντιστοιχεί αυτούς τους αριθμούς σφάλματος στα μηνύματα σφαλμάτων του Expat. Για παράδειγμα:

@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

Το module @ref{130,,errors} παρέχει επίσης σταθερές μηνυμάτων σφαλμάτων και ένα λεξικό @ref{40d4,,codes} που αντιστοιχίζει αυτά τα μηνύματα πίσω στους κωδικούς σφαλμάτων, δείτε παρακάτω.
@end deffn

@geindex lineno (ιδιότητα της xml.parsers.expat.ExpatError)
@anchor{library/pyexpat xml parsers expat ExpatError lineno}@anchor{40b7}
@deffn {Ιδιότητα} ExpatError.lineno

Αριθμός γραμμής στον οποίο ανιχνεύθηκε το σφάλμα. Η πρώτη γραμμή αριθμείται @code{1}.
@end deffn

@geindex offset (ιδιότητα της xml.parsers.expat.ExpatError)
@anchor{library/pyexpat xml parsers expat ExpatError offset}@anchor{40b8}
@deffn {Ιδιότητα} ExpatError.offset

Χαρακτήρας μετατόπισης στη γραμμή όπου συνέβη το σφάλμα. Η πρώτη στήλη αριθμείται @code{0}.
@end deffn

@node Παράδειγμα,Περιγραφές Μοντέλου Περιεχομένου,Εξαιρέσεις ExpatError,xml parsers expat — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat
@anchor{library/pyexpat example}@anchor{40d5}@anchor{library/pyexpat expat-example}@anchor{40d6}
@subsubsection Παράδειγμα


Το ακόλουθο πρόγραμμα ορίζει τρεις χειριστές που απλώς εκτυπώνουν τα ορίσματά τους.

@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

Η έξοδος από αυτό το πρόγραμμα είναι:

@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 Περιγραφές Μοντέλου Περιεχομένου,Σταθερές σφαλμάτων Expat,Παράδειγμα,xml parsers expat — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat
@anchor{library/pyexpat content-model-descriptions}@anchor{40d7}@anchor{library/pyexpat expat-content-models}@anchor{40d8}@anchor{library/pyexpat module-xml parsers expat model}@anchor{131}
@subsubsection Περιγραφές Μοντέλου Περιεχομένου


@geindex module; xml.parsers.expat.model

Τα μοντέλα περιεχομένου περιγράφονται χρησιμοποιώντας εμφωλευμένες πλειάδες. Κάθε πλειάδα περιέχει τέσσερις τιμές: ο τύπος, ο ποσοτικός δείκτης, το όνομα, και μια πλειάδα παιδιών. Τα παιδιά είναι απλώς επιπλέον περιγραφές μοντέλου περιεχομένου.

The values of the first two fields are constants defined in the
@code{xml.parsers.expat.model} module.  These constants can be collected in two
groups: the model type group and the quantifier group.

Οι σταθερές στην ομάδα τύπου μοντέλου είναι:


@deffn {Δεδομένα} xml.parsers.expat.model.XML_CTYPE_ANY

Το στοιχείο που ονομάζεται από το όνομα μοντέλου δηλώθηκε ότι έχει ένα μοντέλο περιεχομένου @code{ANY}.
@end deffn


@deffn {Δεδομένα} xml.parsers.expat.model.XML_CTYPE_CHOICE

Το ονομαζόμενο στοιχείο επιτρέπει μια επιλογή από έναν αριθμό επιλογών· αυτό χρησιμοποιείται για μοντέλα περιεχομένου όπως @code{(A | B | C)}.
@end deffn


@deffn {Δεδομένα} xml.parsers.expat.model.XML_CTYPE_EMPTY

Στοιχεία που δηλώνονται ως @code{EMPTY} έχουν αυτόν τον τύπο μοντέλου.
@end deffn


@deffn {Δεδομένα} xml.parsers.expat.model.XML_CTYPE_MIXED
@end deffn


@deffn {Δεδομένα} xml.parsers.expat.model.XML_CTYPE_NAME
@end deffn


@deffn {Δεδομένα} xml.parsers.expat.model.XML_CTYPE_SEQ

Τα μοντέλα που αντιπροσωπεύουν μια σειρά μοντέλων που ακολουθούν το ένα το άλλο υποδεικνύονται με αυτόν τον τύπο μοντέλου. Αυτό χρησιμοποιείται για μοντέλα όπως @code{(A, B, C)}.
@end deffn

Οι σταθερές στην ομάδα ποσοτικών δεικτών είναι:


@deffn {Δεδομένα} xml.parsers.expat.model.XML_CQUANT_NONE

Δεν δίνεται κανένας τροποποιητής, οπότε μπορεί να εμφανιστεί ακριβώς μία φορά, όπως για @code{A}.
@end deffn


@deffn {Δεδομένα} xml.parsers.expat.model.XML_CQUANT_OPT

Το μοντέλο είναι προαιρετικό: μπορεί να εμφανιστεί μία φορά ή καθόλου, όπως για @code{A?}.
@end deffn


@deffn {Δεδομένα} xml.parsers.expat.model.XML_CQUANT_PLUS

Το μοντέλο πρέπει να εμφανίζεται μία ή περισσότερες φορές (όπως @code{A+}).
@end deffn


@deffn {Δεδομένα} xml.parsers.expat.model.XML_CQUANT_REP

Το μοντέλο πρέπει να εμφανίζεται μηδέν ή περισσότερες φορές, όπως για @code{A*}.
@end deffn

@node Σταθερές σφαλμάτων Expat,,Περιγραφές Μοντέλου Περιεχομένου,xml parsers expat — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat
@anchor{library/pyexpat expat-error-constants}@anchor{40d9}@anchor{library/pyexpat expat-errors}@anchor{40da}@anchor{library/pyexpat module-xml parsers expat errors}@anchor{130}
@subsubsection Σταθερές σφαλμάτων Expat


@geindex module; xml.parsers.expat.errors

The following constants are provided in the @code{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{1b,,code} attribute with
@code{errors.codes[errors.XML_ERROR_@var{CONSTANT_NAME}]}.

Το module @code{errors} έχει τα ακόλουθα χαρακτηριστικά:

@geindex codes (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors codes}@anchor{40d4}
@deffn {Δεδομένα} xml.parsers.expat.errors.codes

Ένα λεξικό που αντιστοιχίζει περιγραφές συμβολοσειρών στους κωδικούς σφαλμάτων τους.


Added in version 3.2.

@end deffn

@geindex messages (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors messages}@anchor{40d3}
@deffn {Δεδομένα} xml.parsers.expat.errors.messages

Ένα λεξικό που αντιστοιχίζει αριθμητικούς κωδικούς σφαλμάτων στις περιγραφές συμβολοσειρών τους.


Added in version 3.2.

@end deffn

@geindex XML_ERROR_ASYNC_ENTITY (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_ASYNC_ENTITY}@anchor{40db}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_ASYNC_ENTITY
@end deffn

@geindex XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF}@anchor{40dc}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

Μια αναφορά οντότητας σε μια τιμή χαρακτηριστικού αναφέρθηκε σε μια εξωτερική οντότητα αντί για μια εσωτερική οντότητα.
@end deffn

@geindex XML_ERROR_BAD_CHAR_REF (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_BAD_CHAR_REF}@anchor{40dd}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_BAD_CHAR_REF

Μια αναφορά χαρακτήρα αναφέρθηκε σε έναν χαρακτήρα που είναι παράνομος στο XML (για παράδειγμα, ο χαρακτήρας @code{0}, ή “@code{&#0;}”).
@end deffn

@geindex XML_ERROR_BINARY_ENTITY_REF (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_BINARY_ENTITY_REF}@anchor{40de}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_BINARY_ENTITY_REF

Μια αναφορά οντότητας αναφέρθηκε σε μια οντότητα που δηλώθηκε με μια σημειογραφία, οπότε δεν μπορεί να αναλυθεί.
@end deffn

@geindex XML_ERROR_DUPLICATE_ATTRIBUTE (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_DUPLICATE_ATTRIBUTE}@anchor{40df}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_DUPLICATE_ATTRIBUTE

Ένα χαρακτηριστικό χρησιμοποιήθηκε περισσότερες από μία φορές σε μια ετικέτα έναρξης.
@end deffn

@geindex XML_ERROR_INCORRECT_ENCODING (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_INCORRECT_ENCODING}@anchor{40e0}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_INCORRECT_ENCODING
@end deffn

@geindex XML_ERROR_INVALID_TOKEN (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_INVALID_TOKEN}@anchor{40e1}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_INVALID_TOKEN

Προκαλείται όταν ένα εισερχόμενο byte δεν μπορούσε να ανατεθεί σωστά σε έναν χαρακτήρα· για παράδειγμα, ένα byte NUL (τιμή @code{0}) σε μια ροή εισόδου UTF-8.
@end deffn

@geindex XML_ERROR_JUNK_AFTER_DOC_ELEMENT (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_JUNK_AFTER_DOC_ELEMENT}@anchor{40e2}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_JUNK_AFTER_DOC_ELEMENT

Κάτι άλλο εκτός από κενό χώρο συνέβη μετά το στοιχείο εγγράφου.
@end deffn

@geindex XML_ERROR_MISPLACED_XML_PI (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_MISPLACED_XML_PI}@anchor{40e3}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_MISPLACED_XML_PI

Βρέθηκε μια δήλωση XML κάπου αλλού εκτός από την αρχή των δεδομένων εισόδου.
@end deffn

@geindex XML_ERROR_NO_ELEMENTS (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NO_ELEMENTS}@anchor{40e4}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_NO_ELEMENTS

Το έγγραφο δεν περιέχει στοιχεία (το XML απαιτεί όλα τα έγγραφα να περιέχουν ακριβώς ένα στοιχείο κορυφαίου επιπέδου)..
@end deffn

@geindex XML_ERROR_NO_MEMORY (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NO_MEMORY}@anchor{40e5}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_NO_MEMORY

Το Expat δεν ήταν σε θέση να δεσμεύσει μνήμη εσωτερικά.
@end deffn

@geindex XML_ERROR_PARAM_ENTITY_REF (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_PARAM_ENTITY_REF}@anchor{40e6}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_PARAM_ENTITY_REF

Βρέθηκε μια αναφορά παραμετρικής οντότητας όπου δεν επιτρέπεται.
@end deffn

@geindex XML_ERROR_PARTIAL_CHAR (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_PARTIAL_CHAR}@anchor{40e7}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_PARTIAL_CHAR

Βρέθηκε ένας ατελής χαρακτήρας στην είσοδο.
@end deffn

@geindex XML_ERROR_RECURSIVE_ENTITY_REF (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_RECURSIVE_ENTITY_REF}@anchor{40e8}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_RECURSIVE_ENTITY_REF

Μια αναφορά οντότητας περιείχε μια άλλη αναφορά στην ίδια οντότητα· πιθανώς μέσω ενός διαφορετικού ονόματος, και πιθανώς έμμεσα.
@end deffn

@geindex XML_ERROR_SYNTAX (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_SYNTAX}@anchor{40e9}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_SYNTAX

Συνέβη κάποιο μη καθορισμένο συντακτικό σφάλμα.
@end deffn

@geindex XML_ERROR_TAG_MISMATCH (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_TAG_MISMATCH}@anchor{40ea}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_TAG_MISMATCH

Μια ετικέτα λήξης δεν ταιριάζει με την πιο εσωτερική ανοιχτή ετικέτα έναρξης.
@end deffn

@geindex XML_ERROR_UNCLOSED_TOKEN (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNCLOSED_TOKEN}@anchor{40eb}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_UNCLOSED_TOKEN

Κάποιο token (όπως μια ετικέτα έναρξης) δεν έκλεισε πριν το τέλος της ροής ή συναντήθηκε το επόμενο διακριτικό.
@end deffn

@geindex XML_ERROR_UNDEFINED_ENTITY (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNDEFINED_ENTITY}@anchor{40ec}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_UNDEFINED_ENTITY

Έγινε αναφορά σε μια οντότητα που δεν ορίστηκε.
@end deffn

@geindex XML_ERROR_UNKNOWN_ENCODING (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNKNOWN_ENCODING}@anchor{40ed}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_UNKNOWN_ENCODING

Η κωδικοποίηση εγγράφου δεν υποστηρίζεται από το Expat.
@end deffn

@geindex XML_ERROR_UNCLOSED_CDATA_SECTION (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNCLOSED_CDATA_SECTION}@anchor{40ee}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_UNCLOSED_CDATA_SECTION

Μια ενότητα με σήμανση CDATA δεν έκλεισε.
@end deffn

@geindex XML_ERROR_EXTERNAL_ENTITY_HANDLING (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_EXTERNAL_ENTITY_HANDLING}@anchor{40ef}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_EXTERNAL_ENTITY_HANDLING
@end deffn

@geindex XML_ERROR_NOT_STANDALONE (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NOT_STANDALONE}@anchor{40f0}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_NOT_STANDALONE

Ο αναλυτής διαπίστωσε ότι το έγγραφο δεν ήταν «αυτόνομο» αν και το δήλωνε ότι ήταν στη δήλωση XML, και ο @code{NotStandaloneHandler} ορίστηκε και επέστρεψε @code{0}.
@end deffn

@geindex XML_ERROR_UNEXPECTED_STATE (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNEXPECTED_STATE}@anchor{40f1}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_UNEXPECTED_STATE
@end deffn

@geindex XML_ERROR_ENTITY_DECLARED_IN_PE (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_ENTITY_DECLARED_IN_PE}@anchor{40f2}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_ENTITY_DECLARED_IN_PE
@end deffn

@geindex XML_ERROR_FEATURE_REQUIRES_XML_DTD (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_FEATURE_REQUIRES_XML_DTD}@anchor{40f3}
@deffn {Δεδομένα} 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 @code{xml.parsers.expat} module.
@end deffn

@geindex XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING}@anchor{40f4}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

Ζητήθηκε μια αλλαγή συμπεριφοράς μετά την έναρξη της ανάλυσης που μπορεί να αλλάξει μόνο πριν ξεκινήσει η ανάλυση. Αυτό (προς το παρόν) προκαλείται μόνο από τη @code{UseForeignDTD()}.
@end deffn

@geindex XML_ERROR_UNBOUND_PREFIX (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNBOUND_PREFIX}@anchor{40f5}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_UNBOUND_PREFIX

Βρέθηκε ένα μη δηλωμένο πρόθεμα όταν η επεξεργασία χώρου ονομάτων ήταν ενεργοποιημένη.
@end deffn

@geindex XML_ERROR_UNDECLARING_PREFIX (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNDECLARING_PREFIX}@anchor{40f6}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_UNDECLARING_PREFIX

Το έγγραφο προσπάθησε να αφαιρέσει τη δήλωση χώρου ονομάτων που σχετίζεται με ένα πρόθεμα.
@end deffn

@geindex XML_ERROR_INCOMPLETE_PE (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_INCOMPLETE_PE}@anchor{40f7}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_INCOMPLETE_PE

Μια παραμετρική οντότητα περιείχε ατελή σήμανση.
@end deffn

@geindex XML_ERROR_XML_DECL (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_XML_DECL}@anchor{40f8}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_XML_DECL

Το έγγραφο δεν περιείχε καθόλου στοιχείο εγγράφου.
@end deffn

@geindex XML_ERROR_TEXT_DECL (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_TEXT_DECL}@anchor{40f9}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_TEXT_DECL

Υπήρξε σφάλμα κατά την ανάλυση μιας δήλωσης κειμένου σε μια εξωτερική οντότητα.
@end deffn

@geindex XML_ERROR_PUBLICID (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_PUBLICID}@anchor{40fa}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_PUBLICID

Βρέθηκαν χαρακτήρες στο δημόσιο αναγνωριστικό που δεν επιτρέπονται.
@end deffn

@geindex XML_ERROR_SUSPENDED (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_SUSPENDED}@anchor{40fb}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_SUSPENDED

Η ζητούμενη λειτουργία πραγματοποιήθηκε σε έναν αναλυτή που είχε ανασταλεί, αλλά δεν επιτρέπεται. Αυτό περιλαμβάνει προσπάθειες παροχής επιπλέον εισόδου ή διακοπής του αναλυτή.
@end deffn

@geindex XML_ERROR_NOT_SUSPENDED (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NOT_SUSPENDED}@anchor{40fc}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_NOT_SUSPENDED

Έγινε μια προσπάθεια να συνεχιστεί ο αναλυτής όταν ο αναλυτής δεν είχε ανασταλεί.
@end deffn

@geindex XML_ERROR_ABORTED (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_ABORTED}@anchor{40fd}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_ABORTED

Αυτό δεν θα πρέπει να αναφέρεται σε εφαρμογές Python.
@end deffn

@geindex XML_ERROR_FINISHED (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_FINISHED}@anchor{40fe}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_FINISHED

Η ζητούμενη λειτουργία πραγματοποιήθηκε σε έναν αναλυτή που ολοκλήρωσε την ανάλυση της εισόδου, αλλά δεν επιτρέπεται. Αυτό περιλαμβάνει προσπάθειες παροχής επιπλέον εισόδου ή διακοπής του αναλυτή.
@end deffn

@geindex XML_ERROR_SUSPEND_PE (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_SUSPEND_PE}@anchor{40ff}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_SUSPEND_PE
@end deffn

@geindex XML_ERROR_RESERVED_PREFIX_XML (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_RESERVED_PREFIX_XML}@anchor{4100}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XML

Έγινε μια προσπάθεια να ακυρωθεί η δήλωση του δεσμευμένου προθέματος χώρου ονομάτων @code{xml} ή να το συνδέσει με ένα άλλο URI χώρου ονομάτων.
@end deffn

@geindex XML_ERROR_RESERVED_PREFIX_XMLNS (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_RESERVED_PREFIX_XMLNS}@anchor{4101}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XMLNS

Έγινε μια προσπάθεια να δηλωθεί ή να ακυρωθεί η δήλωση του δεσμευμένου προθέματος χώρου ονομάτων @code{xmlns}.
@end deffn

@geindex XML_ERROR_RESERVED_NAMESPACE_URI (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_RESERVED_NAMESPACE_URI}@anchor{4102}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_RESERVED_NAMESPACE_URI

Έγινε μια προσπάθεια να δεσμευτεί το URI ενός από τα δεσμευμένα προθέματα χώρου ονομάτων @code{xml} και @code{xmlns} σε ένα άλλο πρόθεμα χώρου ονομάτων.
@end deffn

@geindex XML_ERROR_INVALID_ARGUMENT (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_INVALID_ARGUMENT}@anchor{4103}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_INVALID_ARGUMENT

Αυτό δεν θα πρέπει να αναφέρεται σε εφαρμογές Python.
@end deffn

@geindex XML_ERROR_NO_BUFFER (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NO_BUFFER}@anchor{4104}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_NO_BUFFER

Αυτό δεν θα πρέπει να αναφέρεται σε εφαρμογές Python.
@end deffn

@geindex XML_ERROR_AMPLIFICATION_LIMIT_BREACH (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_AMPLIFICATION_LIMIT_BREACH}@anchor{4105}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_AMPLIFICATION_LIMIT_BREACH

Το όριο στον παράγοντα ενίσχυσης εισόδου (από DTD και οντότητες) έχει παραβιαστεί.
@end deffn

@geindex XML_ERROR_NOT_STARTED (στη μονάδα xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NOT_STARTED}@anchor{1af4}
@deffn {Δεδομένα} xml.parsers.expat.errors.XML_ERROR_NOT_STARTED

Ο αναλυτής προσπάθησε να σταματήσει ή να ανασταλεί πριν ξεκινήσει.


Added in version 3.14.

@end deffn

@subsubheading Υποσημειώσεις


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Πρωτόκολλα Internet και Υποστήριξη,Multimedia Services,Structured Markup Processing Tools,The Python Standard Library
@anchor{library/internet doc}@anchor{4106}@anchor{library/internet internet}@anchor{4107}@anchor{library/internet internet-protocols-and-support}@anchor{4108}@anchor{library/internet translation-repo}@anchor{4109}
@section Πρωτόκολλα Internet και Υποστήριξη


@geindex WWW
@geindex Internet
@geindex Παγκόσμιος Ιστός

@geindex module;socket

Τα modules που περιγράφονται σε αυτό το κεφάλαιο υλοποιούν πρωτόκολλα internet και υποστήριξη για τις σχετικές τεχνολογίες. Όλα υλοποιούνται σε Python. Τα περισσότερα από αυτά τα modules απαιτούν την παρουσία του, εξαρτώμενου από το σύστημα, module @ref{d4,,socket}, το οποίο υποστηρίζεται επί του παρόντος στις περισσότερες δημοφιλείς πλατφόρμες. Εδώ είναι μια επισκόπηση:

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

@end menu

@node webbrowser — Convenient web-browser controller,wsgiref — WSGI Utilities and Reference Implementation,,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/webbrowser doc}@anchor{410a}@anchor{library/webbrowser module-webbrowser}@anchor{11e}@anchor{library/webbrowser webbrowser-convenient-web-browser-controller}@anchor{410b}
@subsection @code{webbrowser} — Convenient web-browser controller


@geindex module; webbrowser

`Source code:' Lib/webbrowser.py@footnote{https://github.com/python/cpython/tree/main/Lib/webbrowser.py}


__________________________________________________________________


The @code{webbrowser} module provides a high-level interface to allow displaying
web-based documents to users. Under most circumstances, simply calling the
@ref{1923,,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 μεταβλητή περιβάλλοντος; BROWSER
@code{BROWSER} exists, it is interpreted as the
@ref{2322,,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 value is a single word that refers to one of the
already registered browsers this browser is added to the front of the search list;
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 μεταβλητή περιβάλλοντος; PATH
@code{PATH} environment variable.
}


Άλλαξε στην έκδοση 3.14: The 
@geindex BROWSER
@geindex μεταβλητή περιβάλλοντος; BROWSER
@code{BROWSER} variable can now also be used to reorder the list of
platform defaults. This is particularly useful on macOS where the platform
defaults do not refer to command-line tools on 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH}.


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 μεταβλητή περιβάλλοντος; 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
@code{webbrowser} module on iOS requires the @ref{2d,,ctypes} module. If
@code{ctypes} isn’t available, calls to @ref{1923,,open()} will fail.

@menu
* Command-line interface: Command-line interface<5>. 
* Browser controller objects:: 

@end menu

@node Command-line interface<5>,Browser controller objects,,webbrowser — Convenient web-browser controller
@anchor{library/webbrowser command-line-interface}@anchor{410c}@anchor{library/webbrowser webbrowser-cli}@anchor{410d}
@subsubsection Command-line interface


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:

@geindex webbrowser command line option; -n
@geindex webbrowser command line option; --new-window
@anchor{library/webbrowser cmdoption-webbrowser-n}@anchor{410e}@anchor{library/webbrowser cmdoption-webbrowser-new-window}@anchor{410f}
@deffn {Option} @w{-}n, @w{-}@w{-}new@w{-}window

Opens the URL in a new browser window, if possible.
@end deffn

@geindex webbrowser command line option; -t
@geindex webbrowser command line option; --new-tab
@anchor{library/webbrowser cmdoption-webbrowser-t}@anchor{4110}@anchor{library/webbrowser cmdoption-webbrowser-new-tab}@anchor{4111}
@deffn {Option} @w{-}t, @w{-}@w{-}new@w{-}tab

Opens the URL in a new browser tab.
@end deffn

The options are, naturally, mutually exclusive.  Usage example:

@example
python -m webbrowser -t "https://www.python.org"
@end example

@ref{232d,,Διαθεσιμότητα}: not WASI, not Android.

The following exception is defined:

@geindex Error
@anchor{library/webbrowser webbrowser Error}@anchor{4112}
@deffn {Εξαίρεση} webbrowser.Error

Exception raised when a browser control error occurs.
@end deffn

The following functions are defined:

@geindex open() (στη μονάδα webbrowser)
@anchor{library/webbrowser webbrowser open}@anchor{1923}
@deffn {Συνάρτηση} 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{1e65,,auditing event} @code{webbrowser.open} with argument @code{url}.
@end deffn

@geindex open_new() (στη μονάδα webbrowser)
@anchor{library/webbrowser webbrowser open_new}@anchor{4113}
@deffn {Συνάρτηση} 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() (στη μονάδα webbrowser)
@anchor{library/webbrowser webbrowser open_new_tab}@anchor{4114}
@deffn {Συνάρτηση} webbrowser.open_new_tab (url)

Open `url' in a new page («tab») of the default browser, if possible, otherwise
equivalent to @ref{4113,,open_new()}.

Returns @code{True} if a browser was successfully launched, @code{False} otherwise.
@end deffn

@geindex get() (στη μονάδα webbrowser)
@anchor{library/webbrowser webbrowser get}@anchor{4115}
@deffn {Συνάρτηση} 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() (στη μονάδα webbrowser)
@anchor{library/webbrowser webbrowser register}@anchor{4116}
@deffn {Συνάρτηση} webbrowser.register (name, constructor, instance=None, *, preferred=False)

Register the browser type `name'.  Once a browser type is registered, the
@ref{4115,,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{4115,,get()} call with no argument.  Otherwise, this entry point is only
useful if you plan to either set the 
@geindex BROWSER
@geindex μεταβλητή περιβάλλοντος; BROWSER
@code{BROWSER} variable or call
@code{get()} with a nonempty argument matching the name of a handler you
declare.


Άλλαξε στην έκδοση 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{4115,,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{'macos'}

@tab

@code{MacOS('default')}

@tab

(3)

@item

@code{'safari'}

@tab

@code{MacOS('safari')}

@tab

(3)

@item

@code{'chrome'}

@tab

@code{MacOS('google chrome')}

@tab

(3)

@item

@code{'firefox'}

@tab

@code{MacOS('firefox')}

@tab

(3)

@item

@code{'google-chrome'}

@tab

@code{Chrome('google-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


Added in 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.



Added in version 3.3: Support for Chrome/Chromium has been added.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.13: Support for iOS has been added.



Added in version 3.15: @code{MacOS} has been added as a replacement for @code{MacOSXOSAScript},
opening browsers via @code{/usr/bin/open} instead of @code{osascript}.



Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.17: @code{MacOSXOSAScript} is deprecated in favour of @code{MacOS}.
Using @code{/usr/bin/open} instead of @code{osascript} is a
security and usability improvement: @code{osascript} may be blocked
on managed systems due to its abuse potential as a general-purpose
scripting interpreter.


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

@node Browser controller objects,,Command-line interface<5>,webbrowser — Convenient web-browser controller
@anchor{library/webbrowser browser-controller-objects}@anchor{4117}@anchor{library/webbrowser browser-controllers}@anchor{4118}
@subsubsection Browser controller objects


Browser controllers provide the @ref{799,,name} attribute,
and the following three methods which parallel module-level convenience functions:

@geindex name (ιδιότητα της webbrowser.controller)
@anchor{library/webbrowser webbrowser controller name}@anchor{799}
@deffn {Ιδιότητα} controller.name

System-dependent name for the browser.
@end deffn

@geindex open() (μέθοδος της webbrowser.controller)
@anchor{library/webbrowser webbrowser controller open}@anchor{4119}
@deffn {Μέθοδος} 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() (μέθοδος της webbrowser.controller)
@anchor{library/webbrowser webbrowser controller open_new}@anchor{411a}
@deffn {Μέθοδος} 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{4113,,open_new()}.
@end deffn

@geindex open_new_tab() (μέθοδος της webbrowser.controller)
@anchor{library/webbrowser webbrowser controller open_new_tab}@anchor{411b}
@deffn {Μέθοδος} 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{4113,,open_new()}.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node wsgiref — WSGI Utilities and Reference Implementation,urllib — URL handling modules,webbrowser — Convenient web-browser controller,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/wsgiref doc}@anchor{411c}@anchor{library/wsgiref module-wsgiref}@anchor{121}@anchor{library/wsgiref translation-repo}@anchor{411d}@anchor{library/wsgiref wsgiref-wsgi-utilities-and-reference-implementation}@anchor{411e}
@subsection @code{wsgiref} — WSGI Utilities and Reference Implementation


@geindex module; wsgiref

`Source code:' Lib/wsgiref@footnote{https://github.com/python/cpython/tree/main/Lib/wsgiref}


__________________________________________________________________


@cartouche
@quotation Προειδοποίηση 
@code{wsgiref} is a reference implementation and is not recommended for
production. The module only implements basic security checks.
@end quotation
@end cartouche

The Web Server Gateway Interface (WSGI) is a standard interface between web
server software and web applications written in Python. Having a standard
interface makes it easy to use an application that supports WSGI with a number
of different web servers.

Only authors of web servers and programming frameworks need to know every detail
and corner case of the WSGI design.  You don’t need to understand every detail
of WSGI just to install a WSGI application or to write a web application using
an existing framework.

@code{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/}).

See wsgi.readthedocs.io@footnote{https://wsgi.readthedocs.io/} for more information about WSGI, and links
to tutorials and other resources.

@c XXX If you're just trying to write a web application...

@menu
* wsgiref.util – WSGI environment utilities: wsgiref util – WSGI environment utilities. 
* wsgiref.headers – WSGI response header tools: wsgiref headers – WSGI response header tools. 
* wsgiref.simple_server – a simple WSGI HTTP server: wsgiref simple_server – a simple WSGI HTTP server. 
* wsgiref.validate — WSGI conformance checker: wsgiref validate — WSGI conformance checker. 
* wsgiref.handlers – server/gateway base classes: wsgiref handlers – server/gateway base classes. 
* wsgiref.types – WSGI types for static type checking: wsgiref types – WSGI types for static type checking. 
* Examples: Examples<22>. 

@end menu

@node wsgiref util – WSGI environment utilities,wsgiref headers – WSGI response header tools,,wsgiref — WSGI Utilities and Reference Implementation
@anchor{library/wsgiref module-wsgiref util}@anchor{126}@anchor{library/wsgiref wsgiref-util-wsgi-environment-utilities}@anchor{411f}
@subsubsection @code{wsgiref.util} – WSGI environment utilities


@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{4120,,WSGIEnvironment} for a type alias that can be used
in type annotations.

@geindex guess_scheme() (στη μονάδα wsgiref.util)
@anchor{library/wsgiref wsgiref util guess_scheme}@anchor{4121}
@deffn {Συνάρτηση} wsgiref.util.guess_scheme (environ)

Return a guess for whether @code{wsgi.url_scheme} should be «http» or «https», by
checking for a @code{HTTPS} environment variable in the `environ' dictionary.  The
return value is a string.

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() (στη μονάδα wsgiref.util)
@anchor{library/wsgiref wsgiref util request_uri}@anchor{4122}
@deffn {Συνάρτηση} 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() (στη μονάδα wsgiref.util)
@anchor{library/wsgiref wsgiref util application_uri}@anchor{4123}
@deffn {Συνάρτηση} wsgiref.util.application_uri (environ)

Similar to @ref{4122,,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() (στη μονάδα wsgiref.util)
@anchor{library/wsgiref wsgiref util shift_path_info}@anchor{4124}
@deffn {Συνάρτηση} 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 @code{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() (στη μονάδα wsgiref.util)
@anchor{library/wsgiref wsgiref util setup_testing_defaults}@anchor{4125}
@deffn {Συνάρτηση} wsgiref.util.setup_testing_defaults (environ)

Update `environ' with trivial defaults for testing purposes.

This routine adds various parameters required for WSGI, including @code{HTTP_HOST},
@code{SERVER_NAME}, @code{SERVER_PORT}, @code{REQUEST_METHOD}, @code{SCRIPT_NAME},
@code{PATH_INFO}, and all of the 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}-defined @code{wsgi.*} variables.  It
only supplies default values, and does not replace any existing settings for
these variables.

This routine is intended to make it easier for unit tests of WSGI servers and
applications to set up dummy environments.  It should NOT be used by actual WSGI
servers or applications, since the data is fake!

Example usage (see also @ref{4126,,demo_app()}
for another example):

@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 @code{wsgiref.util} module
also provides these miscellaneous utilities:

@geindex is_hop_by_hop() (στη μονάδα wsgiref.util)
@anchor{library/wsgiref wsgiref util is_hop_by_hop}@anchor{1c43}
@deffn {Συνάρτηση} 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 (κλάση σε wsgiref.util)
@anchor{library/wsgiref wsgiref util FileWrapper}@anchor{b1d}
@deffn {Κλάση} wsgiref.util.FileWrapper (filelike, blksize=8192)

A concrete implementation of the @ref{4127,,wsgiref.types.FileWrapper}
protocol used to convert a file-like object to an @ref{6ce,,iterator}.
The resulting objects
are @ref{15ce,,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.

Example usage:

@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


Άλλαξε στην έκδοση 3.11: Support for @ref{787,,__getitem__()} method has been removed.

@end deffn

@node wsgiref headers – WSGI response header tools,wsgiref simple_server – a simple WSGI HTTP server,wsgiref util – WSGI environment utilities,wsgiref — WSGI Utilities and Reference Implementation
@anchor{library/wsgiref module-wsgiref headers}@anchor{123}@anchor{library/wsgiref wsgiref-headers-wsgi-response-header-tools}@anchor{4128}
@subsubsection @code{wsgiref.headers} – WSGI response header tools


@geindex module; wsgiref.headers

This module provides a single class, @ref{1249,,Headers}, for convenient
manipulation of WSGI response headers using a mapping-like interface.

@geindex Headers (κλάση σε wsgiref.headers)
@anchor{library/wsgiref wsgiref headers Headers}@anchor{1249}
@deffn {Κλάση} 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.

@code{Headers} objects support typical mapping operations including
@ref{787,,__getitem__()}, @ref{2223,,get()}, @ref{1670,,__setitem__()},
@ref{1421,,setdefault()},
@ref{1671,,__delitem__()} and @ref{175c,,__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, @code{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.

@code{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 @code{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 @code{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, @code{Headers}
objects also have the following methods for querying and adding multi-valued
headers, and for adding headers with MIME parameters:

@geindex get_all() (μέθοδος της wsgiref.headers.Headers)
@anchor{library/wsgiref wsgiref headers Headers get_all}@anchor{4129}
@deffn {Μέθοδος} get_all (name)

Return a list of all the values for the named header.

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() (μέθοδος της wsgiref.headers.Headers)
@anchor{library/wsgiref wsgiref headers Headers add_header}@anchor{412a}
@deffn {Μέθοδος} 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

The above will add a header that looks like this:

@example
Content-Disposition: attachment; filename="bud.gif"
@end example
@end deffn


Άλλαξε στην έκδοση 3.5: `headers' parameter is optional.

@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{124}@anchor{library/wsgiref wsgiref-simple-server-a-simple-wsgi-http-server}@anchor{412b}
@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{75,,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{126,,wsgiref.util}.)

@geindex make_server() (στη μονάδα wsgiref.simple_server)
@anchor{library/wsgiref wsgiref simple_server make_server}@anchor{412c}
@deffn {Συνάρτηση} 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/}.

Example usage:

@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() (στη μονάδα wsgiref.simple_server)
@anchor{library/wsgiref wsgiref simple_server demo_app}@anchor{4126}
@deffn {Συνάρτηση} 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 @code{wsgiref.simple_server}) is able to run a simple WSGI application
correctly.

The `start_response' callable should follow the @ref{412d,,StartResponse} protocol.
@end deffn

@geindex WSGIServer (κλάση σε wsgiref.simple_server)
@anchor{library/wsgiref wsgiref simple_server WSGIServer}@anchor{412e}
@deffn {Κλάση} wsgiref.simple_server.WSGIServer (server_address, RequestHandlerClass)

Create a @code{WSGIServer} instance.  `server_address' should be a
@code{(host,port)} tuple, and `RequestHandlerClass' should be the subclass of
@ref{226,,http.server.BaseHTTPRequestHandler} that will be used to process
requests.

You do not normally need to call this constructor, as the @ref{412c,,make_server()}
function can handle all the details for you.

@code{WSGIServer} is a subclass of @ref{412f,,http.server.HTTPServer}, so all
of its methods (such as @code{serve_forever()} and @code{handle_request()}) are
available. @code{WSGIServer} also provides these WSGI-specific methods:

@geindex set_app() (μέθοδος της wsgiref.simple_server.WSGIServer)
@anchor{library/wsgiref wsgiref simple_server WSGIServer set_app}@anchor{4130}
@deffn {Μέθοδος} set_app (application)

Sets the callable `application' as the WSGI application that will receive
requests.
@end deffn

@geindex get_app() (μέθοδος της wsgiref.simple_server.WSGIServer)
@anchor{library/wsgiref wsgiref simple_server WSGIServer get_app}@anchor{4131}
@deffn {Μέθοδος} get_app ()

Returns the currently set application callable.
@end deffn

Normally, however, you do not need to use these additional methods, as
@ref{4130,,set_app()} is normally called by @ref{412c,,make_server()}, and the
@ref{4131,,get_app()} exists mainly for the benefit of request handler instances.
@end deffn

@geindex WSGIRequestHandler (κλάση σε wsgiref.simple_server)
@anchor{library/wsgiref wsgiref simple_server WSGIRequestHandler}@anchor{4132}
@deffn {Κλάση} 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{412e,,WSGIServer} instance).

You do not need to create instances of this class directly; they are
automatically created as needed by @ref{412e,,WSGIServer} objects.  You can,
however, subclass this class and supply it as a `handler_class' to the
@ref{412c,,make_server()} function.  Some possibly relevant methods for overriding in
subclasses:

@geindex get_environ() (μέθοδος της wsgiref.simple_server.WSGIRequestHandler)
@anchor{library/wsgiref wsgiref simple_server WSGIRequestHandler get_environ}@anchor{4133}
@deffn {Μέθοδος} get_environ ()

Return a @ref{4120,,WSGIEnvironment} dictionary for a
request.  The default
implementation copies the contents of the @ref{412e,,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() (μέθοδος της wsgiref.simple_server.WSGIRequestHandler)
@anchor{library/wsgiref wsgiref simple_server WSGIRequestHandler get_stderr}@anchor{4134}
@deffn {Μέθοδος} 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() (μέθοδος της wsgiref.simple_server.WSGIRequestHandler)
@anchor{library/wsgiref wsgiref simple_server WSGIRequestHandler handle}@anchor{4135}
@deffn {Μέθοδος} handle ()

Process the HTTP request.  The default implementation creates a handler instance
using a @ref{122,,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{127}@anchor{library/wsgiref wsgiref-validate-wsgi-conformance-checker}@anchor{4136}
@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
@code{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() (στη μονάδα wsgiref.validate)
@anchor{library/wsgiref wsgiref validate validator}@anchor{4137}
@deffn {Συνάρτηση} 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{a97,,AssertionError} being raised;
note, however, that how these errors are handled is server-dependent.  For
example, @ref{124,,wsgiref.simple_server} and other servers based on
@ref{122,,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{11b,,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 @code{warnings} API, any such warnings will be written to
@code{sys.stderr} (`not' @code{wsgi.errors}, unless they happen to be the same
object).

Example usage:

@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{122}@anchor{library/wsgiref wsgiref-handlers-server-gateway-base-classes}@anchor{4138}
@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 (κλάση σε wsgiref.handlers)
@anchor{library/wsgiref wsgiref handlers CGIHandler}@anchor{4139}
@deffn {Κλάση} 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{413a,,BaseCGIHandler} that sets @code{wsgi.run_once}
to true, @code{wsgi.multithread} to false, and @code{wsgi.multiprocess} to true, and
always uses @ref{e2,,sys} and @ref{a5,,os} to obtain the necessary CGI streams and
environment.
@end deffn

@geindex IISCGIHandler (κλάση σε wsgiref.handlers)
@anchor{library/wsgiref wsgiref handlers IISCGIHandler}@anchor{413b}
@deffn {Κλάση} wsgiref.handlers.IISCGIHandler

A specialized alternative to @ref{4139,,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{4139,,CGIHandler}, i.e., by calling @code{IISCGIHandler().run(app)}, where
@code{app} is the WSGI application object you wish to invoke.


Added in version 3.2.

@end deffn

@geindex BaseCGIHandler (κλάση σε wsgiref.handlers)
@anchor{library/wsgiref wsgiref handlers BaseCGIHandler}@anchor{413a}
@deffn {Κλάση} wsgiref.handlers.BaseCGIHandler (stdin, stdout, stderr, environ, multithread=True, multiprocess=False)

Similar to @ref{4139,,CGIHandler}, but instead of using the @ref{e2,,sys} and
@ref{a5,,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{413c,,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 @code{SimpleHandler}.
@end deffn

@geindex SimpleHandler (κλάση σε wsgiref.handlers)
@anchor{library/wsgiref wsgiref handlers SimpleHandler}@anchor{413c}
@deffn {Κλάση} wsgiref.handlers.SimpleHandler (stdin, stdout, stderr, environ, multithread=True, multiprocess=False)

Similar to @ref{413a,,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 @code{BaseCGIHandler}.

This class is a subclass of @ref{1fc2,,BaseHandler}.  It overrides the
@code{__init__()}, @ref{413d,,get_stdin()},
@ref{413e,,get_stderr()}, @ref{413f,,add_cgi_vars()},
@ref{4140,,_write()}, and @ref{4141,,_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{1099,,write()} method of `stdout' should write
each chunk in full, like @ref{a83,,io.BufferedIOBase}.
@end deffn

@geindex BaseHandler (κλάση σε wsgiref.handlers)
@anchor{library/wsgiref wsgiref handlers BaseHandler}@anchor{1fc2}
@deffn {Κλάση} 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.

@code{BaseHandler} instances have only one method intended for external use:

@geindex run() (μέθοδος της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler run}@anchor{4142}
@deffn {Μέθοδος} run (app)

Run the specified WSGI application, `app'.
@end deffn

All of the other @code{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() (μέθοδος της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler _write}@anchor{4140}
@deffn {Μέθοδος} _write (data)

Buffer the bytes `data' for transmission to the client.  It’s okay if this
method actually transmits the data; @code{BaseHandler} just separates write
and flush operations for greater efficiency when the underlying system actually
has such a distinction.
@end deffn

@geindex _flush() (μέθοδος της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler _flush}@anchor{4141}
@deffn {Μέθοδος} _flush ()

Force buffered data to be transmitted to the client.  It’s okay if this method
is a no-op (i.e., if @ref{4140,,_write()} actually sends the data).
@end deffn

@geindex get_stdin() (μέθοδος της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler get_stdin}@anchor{413d}
@deffn {Μέθοδος} get_stdin ()

Return an object compatible with @ref{4143,,InputStream}
suitable for use as the @code{wsgi.input} of the
request currently being processed.
@end deffn

@geindex get_stderr() (μέθοδος της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler get_stderr}@anchor{413e}
@deffn {Μέθοδος} get_stderr ()

Return an object compatible with @ref{4144,,ErrorStream}
suitable for use as the @code{wsgi.errors} of the
request currently being processed.
@end deffn

@geindex add_cgi_vars() (μέθοδος της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler add_cgi_vars}@anchor{413f}
@deffn {Μέθοδος} 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 @code{BaseHandler}
subclass.

Attributes and methods for customizing the WSGI environment:

@geindex wsgi_multithread (ιδιότητα της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler wsgi_multithread}@anchor{4145}
@deffn {Ιδιότητα} wsgi_multithread

The value to be used for the @code{wsgi.multithread} environment variable.  It
defaults to true in @code{BaseHandler}, but may have a different default (or
be set by the constructor) in the other subclasses.
@end deffn

@geindex wsgi_multiprocess (ιδιότητα της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler wsgi_multiprocess}@anchor{4146}
@deffn {Ιδιότητα} wsgi_multiprocess

The value to be used for the @code{wsgi.multiprocess} environment variable.  It
defaults to true in @code{BaseHandler}, but may have a different default (or
be set by the constructor) in the other subclasses.
@end deffn

@geindex wsgi_run_once (ιδιότητα της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler wsgi_run_once}@anchor{4147}
@deffn {Ιδιότητα} wsgi_run_once

The value to be used for the @code{wsgi.run_once} environment variable.  It
defaults to false in @code{BaseHandler}, but @ref{4139,,CGIHandler} sets it to
true by default.
@end deffn

@geindex os_environ (ιδιότητα της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler os_environ}@anchor{4148}
@deffn {Ιδιότητα} 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
@code{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 (ιδιότητα της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler server_software}@anchor{4149}
@deffn {Ιδιότητα} server_software

If the @ref{414a,,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{413a,,BaseCGIHandler} and @ref{4139,,CGIHandler}) that are not HTTP origin
servers.


Άλλαξε στην έκδοση 3.3: The term «Python» is replaced with implementation specific term like
«CPython», «Jython» etc.

@end deffn

@geindex get_scheme() (μέθοδος της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler get_scheme}@anchor{414b}
@deffn {Μέθοδος} get_scheme ()

Return the URL scheme being used for the current request.  The default
implementation uses the @code{guess_scheme()} function from @ref{126,,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() (μέθοδος της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler setup_environ}@anchor{414c}
@deffn {Μέθοδος} 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{413d,,get_stdin()}, @ref{413e,,get_stderr()}, and @ref{413f,,add_cgi_vars()} methods and the
@ref{414d,,wsgi_file_wrapper} attribute.  It also inserts a @code{SERVER_SOFTWARE} key
if not present, as long as the @ref{414a,,origin_server} attribute is a true value
and the @ref{4149,,server_software} attribute is set.
@end deffn

Methods and attributes for customizing exception handling:

@geindex log_exception() (μέθοδος της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler log_exception}@anchor{414e}
@deffn {Μέθοδος} 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 (ιδιότητα της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler traceback_limit}@anchor{414f}
@deffn {Ιδιότητα} traceback_limit

The maximum number of frames to include in tracebacks output by the default
@ref{414e,,log_exception()} method.  If @code{None}, all frames are included.
@end deffn

@geindex error_output() (μέθοδος της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler error_output}@anchor{4150}
@deffn {Μέθοδος} 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/}). In particular,
the `start_response' callable should follow the @ref{412d,,StartResponse}
protocol.

The default implementation just uses the @ref{4151,,error_status},
@ref{4152,,error_headers}, and @ref{4153,,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 (ιδιότητα της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler error_status}@anchor{4151}
@deffn {Ιδιότητα} 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 (ιδιότητα της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler error_headers}@anchor{4152}
@deffn {Ιδιότητα} 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 (ιδιότητα της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler error_body}@anchor{4153}
@deffn {Ιδιότητα} 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 (ιδιότητα της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler wsgi_file_wrapper}@anchor{414d}
@deffn {Ιδιότητα} wsgi_file_wrapper

A @code{wsgi.file_wrapper} factory, compatible with
@ref{4127,,wsgiref.types.FileWrapper}, or @code{None}.  The default value
of this attribute is the @ref{b1d,,wsgiref.util.FileWrapper} class.
@end deffn

@geindex sendfile() (μέθοδος της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler sendfile}@anchor{4154}
@deffn {Μέθοδος} 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{414d,,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 (ιδιότητα της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler origin_server}@anchor{414a}
@deffn {Ιδιότητα} origin_server

This attribute should be set to a true value if the handler’s @ref{4140,,_write()} and
@ref{4141,,_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 @code{BaseHandler}, but false in
@ref{413a,,BaseCGIHandler} and @ref{4139,,CGIHandler}.
@end deffn

@geindex http_version (ιδιότητα της wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler http_version}@anchor{4155}
@deffn {Ιδιότητα} http_version

If @ref{414a,,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() (στη μονάδα wsgiref.handlers)
@anchor{library/wsgiref wsgiref handlers read_environ}@anchor{1562}
@deffn {Συνάρτηση} 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{4139,,CGIHandler} and @ref{413b,,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.


Added in version 3.2.

@end deffn

@node wsgiref types – WSGI types for static type checking,Examples<22>,wsgiref handlers – server/gateway base classes,wsgiref — WSGI Utilities and Reference Implementation
@anchor{library/wsgiref module-wsgiref types}@anchor{125}@anchor{library/wsgiref wsgiref-types-wsgi-types-for-static-type-checking}@anchor{4156}
@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/}.


Added in version 3.11.


@geindex StartResponse (κλάση σε wsgiref.types)
@anchor{library/wsgiref wsgiref types StartResponse}@anchor{412d}
@deffn {Κλάση} wsgiref.types.StartResponse

A @ref{76c,,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 (στη μονάδα wsgiref.types)
@anchor{library/wsgiref wsgiref types WSGIEnvironment}@anchor{4120}
@deffn {Δεδομένα} wsgiref.types.WSGIEnvironment

A type alias describing a WSGI environment dictionary.
@end deffn

@geindex WSGIApplication (στη μονάδα wsgiref.types)
@anchor{library/wsgiref wsgiref types WSGIApplication}@anchor{4157}
@deffn {Δεδομένα} wsgiref.types.WSGIApplication

A type alias describing a WSGI application callable.
@end deffn

@geindex InputStream (κλάση σε wsgiref.types)
@anchor{library/wsgiref wsgiref types InputStream}@anchor{4143}
@deffn {Κλάση} wsgiref.types.InputStream

A @ref{76c,,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 (κλάση σε wsgiref.types)
@anchor{library/wsgiref wsgiref types ErrorStream}@anchor{4144}
@deffn {Κλάση} wsgiref.types.ErrorStream

A @ref{76c,,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 (κλάση σε wsgiref.types)
@anchor{library/wsgiref wsgiref types FileWrapper}@anchor{4127}
@deffn {Κλάση} wsgiref.types.FileWrapper

A @ref{76c,,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{b1d,,wsgiref.util.FileWrapper} for a concrete implementation of this
protocol.
@end deffn

@node Examples<22>,,wsgiref types – WSGI types for static type checking,wsgiref — WSGI Utilities and Reference Implementation
@anchor{library/wsgiref examples}@anchor{4158}
@subsubsection Examples


This is a working «Hello World» WSGI application, where the `start_response'
callable should follow the @ref{412d,,StartResponse} protocol:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node urllib — URL handling modules,urllib request — Extensible library for opening URLs,wsgiref — WSGI Utilities and Reference Implementation,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/urllib doc}@anchor{4159}@anchor{library/urllib module-urllib}@anchor{111}@anchor{library/urllib translation-repo}@anchor{415a}@anchor{library/urllib urllib-url-handling-modules}@anchor{415b}
@subsection @code{urllib} — URL handling modules


@geindex module; urllib

`Source code:' Lib/urllib/@footnote{https://github.com/python/cpython/tree/main/Lib/urllib/}


__________________________________________________________________


@code{urllib} is a package that collects several modules for working with URLs:


@itemize *

@item 
@ref{114,,urllib.request} for opening and reading URLs

@item 
@ref{112,,urllib.error} containing the exceptions raised by @ref{114,,urllib.request}

@item 
@ref{113,,urllib.parse} for parsing URLs

@item 
@ref{116,,urllib.robotparser} for parsing @code{robots.txt} files
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node urllib request — Extensible library for opening URLs,urllib response — Response classes used by urllib,urllib — URL handling modules,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/urllib request doc}@anchor{415c}@anchor{library/urllib request module-urllib request}@anchor{114}@anchor{library/urllib request translation-repo}@anchor{415d}@anchor{library/urllib request urllib-request-extensible-library-for-opening-urls}@anchor{415e}
@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/main/Lib/urllib/request.py}


__________________________________________________________________


The @code{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 Δείτε επίσης


The Requests package@footnote{https://requests.readthedocs.io/en/master/}
is recommended for a higher-level HTTP client interface.


@cartouche
@quotation Προειδοποίηση 
On macOS it is unsafe to use this module in programs using
@ref{6bd,,os.fork()} because the @ref{415f,,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{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

The @code{urllib.request} module defines the following functions:

@geindex urlopen() (στη μονάδα urllib.request)
@anchor{library/urllib request urllib request urlopen}@anchor{57f}
@deffn {Συνάρτηση} 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{1381,,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{1381,,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{336,,ssl.SSLContext} instance
describing the various SSL options. See @ref{224,,HTTPSConnection}
for more details.

This function always returns an object which can work as a
@ref{478,,context manager} and has the properties `url', `headers', and `status'.
See @ref{4160,,urllib.response.addinfourl} for more detail on these properties.

For HTTP and HTTPS URLs, this function returns a
@ref{147a,,http.client.HTTPResponse} object slightly modified. In addition
to the three new methods above, the msg attribute contains the
same information as the @ref{4161,,reason}
attribute — the reason phrase returned by server — instead of
the response headers as it is specified in the documentation for
@code{HTTPResponse}.

For FTP, file, and data URLs, this function
returns a @ref{4160,,urllib.response.addinfourl} object.

Raises @ref{53a,,URLError} on protocol errors.

Note that @code{None} may be returned if no handler handles the request (though
the default installed global @ref{199b,,OpenerDirector} uses
@ref{4162,,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{1fa5,,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{57f,,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{1fa5,,ProxyHandler} objects.


The default opener raises an @ref{1e65,,auditing event}
@code{urllib.Request} with arguments @code{fullurl}, @code{data}, @code{headers},
@code{method} taken from the request object.



Άλλαξε στην έκδοση 3.2: `cafile' and `capath' were added.

HTTPS virtual hosts are now supported if possible (that is, if
@ref{3c20,,ssl.HAS_SNI} is true).

`data' can be an iterable object.



Άλλαξε στην έκδοση 3.3: `cadefault' was added.



Άλλαξε στην έκδοση 3.4.3: `context' was added.



Άλλαξε στην έκδοση 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{1215,,set_alpn_protocols()}.



Άλλαξε στην έκδοση 3.13: Remove `cafile', `capath' and `cadefault' parameters: use the `context'
parameter instead.

@end deffn

@geindex install_opener() (στη μονάδα urllib.request)
@anchor{library/urllib request urllib request install_opener}@anchor{4163}
@deffn {Συνάρτηση} urllib.request.install_opener (opener)

Install an @ref{199b,,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{1385,,OpenerDirector.open()} instead of
@ref{57f,,urlopen()}.  The code does not check for a real
@code{OpenerDirector}, and any class with the appropriate interface will
work.
@end deffn

@geindex build_opener() (στη μονάδα urllib.request)
@anchor{library/urllib request urllib request build_opener}@anchor{581}
@deffn {Συνάρτηση} urllib.request.build_opener ([handler, ...])

Return an @ref{199b,,OpenerDirector} instance, which chains the handlers in the
order given. `handler's can be either instances of @ref{4164,,BaseHandler}, or
subclasses of @code{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{1fa5,,ProxyHandler} (if proxy
settings are detected), @ref{4162,,UnknownHandler}, @ref{10b8,,HTTPHandler},
@ref{4165,,HTTPDefaultErrorHandler}, @ref{4166,,HTTPRedirectHandler},
@ref{4167,,FTPHandler}, @ref{4168,,FileHandler}, @ref{4169,,HTTPErrorProcessor}.

If the Python installation has SSL support (i.e., if the @ref{d8,,ssl} module
can be imported), @ref{15ca,,HTTPSHandler} will also be added.

A @ref{4164,,BaseHandler} subclass may also change its @code{handler_order}
attribute to modify its position in the handlers list.
@end deffn

@geindex pathname2url() (στη μονάδα urllib.request)
@anchor{library/urllib request urllib request pathname2url}@anchor{53b}
@deffn {Συνάρτηση} urllib.request.pathname2url (path, *, add_scheme=False)

Convert the given local path to a @code{file:} URL. This function uses
@ref{f62,,quote()} function to encode the path.

If `add_scheme' is false (the default), the return value omits the
@code{file:} scheme prefix. Set `add_scheme' to true to return a complete URL.

This example shows the function being used on Windows:

@example
>>> from urllib.request import pathname2url
>>> path = 'C:\\Program Files'
>>> pathname2url(path, add_scheme=True)
'file:///C:/Program%20Files'
@end example


Άλλαξε στην έκδοση 3.14: Windows drive letters are no longer converted to uppercase, and @code{:}
characters not following a drive letter no longer cause an
@ref{53c,,OSError} exception to be raised on Windows.



Άλλαξε στην έκδοση 3.14: Paths beginning with a slash are converted to URLs with authority
sections. For example, the path @code{/etc/hosts} is converted to
the URL @code{///etc/hosts}.



Άλλαξε στην έκδοση 3.14: The `add_scheme' parameter was added.

@end deffn

@geindex url2pathname() (στη μονάδα urllib.request)
@anchor{library/urllib request urllib request url2pathname}@anchor{539}
@deffn {Συνάρτηση} urllib.request.url2pathname (url, *, require_scheme=False, resolve_host=False)

Convert the given @code{file:} URL to a local path. This function uses
@ref{1cfa,,unquote()} to decode the URL.

If `require_scheme' is false (the default), the given value should omit a
@code{file:} scheme prefix. If `require_scheme' is set to true, the given
value should include the prefix; a @ref{53a,,URLError} is raised
if it doesn’t.

The URL authority is discarded if it is empty, @code{localhost}, or the local
hostname. Otherwise, if `resolve_host' is set to true, the authority is
resolved using @ref{3bdf,,socket.gethostbyname()} and discarded if it matches a
local IP address (as per 
@geindex RFC; RFC 8089 Section 3
RFC 8089 §3@footnote{https://datatracker.ietf.org/doc/html/rfc8089.html#section-3}). If the
authority is still unhandled, then on Windows a UNC path is returned, and
on other platforms a @ref{53a,,URLError} is raised.

This example shows the function being used on Windows:

@example
>>> from urllib.request import url2pathname
>>> url = 'file:///C:/Program%20Files'
>>> url2pathname(url, require_scheme=True)
'C:\\Program Files'
@end example


Άλλαξε στην έκδοση 3.14: Windows drive letters are no longer converted to uppercase, and @code{:}
characters not following a drive letter no longer cause an
@ref{53c,,OSError} exception to be raised on Windows.



Άλλαξε στην έκδοση 3.14: The URL authority is discarded if it matches the local hostname.
Otherwise, if the authority isn’t empty or @code{localhost}, then on
Windows a UNC path is returned (as before), and on other platforms a
@ref{53a,,URLError} is raised.



Άλλαξε στην έκδοση 3.14: The URL query and fragment components are discarded if present.



Άλλαξε στην έκδοση 3.14: The `require_scheme' and `resolve_host' parameters were added.

@end deffn

@geindex getproxies() (στη μονάδα urllib.request)
@anchor{library/urllib request urllib request getproxies}@anchor{415f}
@deffn {Συνάρτηση} 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 Σημείωση 
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 (κλάση σε urllib.request)
@anchor{library/urllib request urllib request Request}@anchor{1381}
@deffn {Κλάση} 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{10b8,,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{1246,,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{416a,,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{111,,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{1382,,method} attribute and is used by @ref{1512,,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
@code{method} attribute in the class itself.

@cartouche
@quotation Σημείωση 
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


Άλλαξε στην έκδοση 3.3: @ref{1382,,Request.method} argument is added to the Request class.



Άλλαξε στην έκδοση 3.4: Default @ref{1382,,Request.method} may be indicated at the class level.



Άλλαξε στην έκδοση 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 (κλάση σε urllib.request)
@anchor{library/urllib request urllib request OpenerDirector}@anchor{199b}
@deffn {Κλάση} urllib.request.OpenerDirector

The @code{OpenerDirector} class opens URLs via @ref{4164,,BaseHandler}s chained
together. It manages the chaining of handlers, and recovery from errors.
@end deffn

@geindex BaseHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request BaseHandler}@anchor{4164}
@deffn {Κλάση} urllib.request.BaseHandler

This is the base class for all registered handlers — and handles only the
simple mechanics of registration.
@end deffn

@geindex HTTPDefaultErrorHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request HTTPDefaultErrorHandler}@anchor{4165}
@deffn {Κλάση} urllib.request.HTTPDefaultErrorHandler

A class which defines a default handler for HTTP error responses; all responses
are turned into @ref{1387,,HTTPError} exceptions.
@end deffn

@geindex HTTPRedirectHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request HTTPRedirectHandler}@anchor{4166}
@deffn {Κλάση} urllib.request.HTTPRedirectHandler

A class to handle redirections.
@end deffn

@geindex HTTPCookieProcessor (κλάση σε urllib.request)
@anchor{library/urllib request urllib request HTTPCookieProcessor}@anchor{416b}
@deffn {Κλάση} urllib.request.HTTPCookieProcessor (cookiejar=None)

A class to handle HTTP Cookies.
@end deffn

@geindex ProxyHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request ProxyHandler}@anchor{1fa5}
@deffn {Κλάση} 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 μεταβλητή περιβάλλοντος; 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 Σημείωση 
@code{HTTP_PROXY} will be ignored if a variable @code{REQUEST_METHOD} is set;
see the documentation on @ref{415f,,getproxies()}.
@end quotation
@end cartouche
@end deffn

@geindex HTTPPasswordMgr (κλάση σε urllib.request)
@anchor{library/urllib request urllib request HTTPPasswordMgr}@anchor{416c}
@deffn {Κλάση} urllib.request.HTTPPasswordMgr

Keep a database of  @code{(realm, uri) -> (user, password)} mappings.
@end deffn

@geindex HTTPPasswordMgrWithDefaultRealm (κλάση σε urllib.request)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithDefaultRealm}@anchor{416d}
@deffn {Κλάση} 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 (κλάση σε urllib.request)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithPriorAuth}@anchor{1245}
@deffn {Κλάση} urllib.request.HTTPPasswordMgrWithPriorAuth

A variant of @ref{416d,,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.


Added in version 3.5.

@end deffn

@geindex AbstractBasicAuthHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request AbstractBasicAuthHandler}@anchor{1e66}
@deffn {Κλάση} 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{416c,,HTTPPasswordMgr}; refer to section
@ref{416e,,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{416f,,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.


Added in version 3.5: Added @code{is_authenticated} support.

@end deffn

@geindex HTTPBasicAuthHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request HTTPBasicAuthHandler}@anchor{4170}
@deffn {Κλάση} urllib.request.HTTPBasicAuthHandler (password_mgr=None)

Handle authentication with the remote host. `password_mgr', if given, should
be something that is compatible with @ref{416c,,HTTPPasswordMgr}; refer to
section @ref{416e,,HTTPPasswordMgr Objects} for information on the interface that must
be supported. HTTPBasicAuthHandler will raise a @ref{277,,ValueError} when
presented with a wrong Authentication scheme.
@end deffn

@geindex ProxyBasicAuthHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request ProxyBasicAuthHandler}@anchor{4171}
@deffn {Κλάση} urllib.request.ProxyBasicAuthHandler (password_mgr=None)

Handle authentication with the proxy. `password_mgr', if given, should be
something that is compatible with @ref{416c,,HTTPPasswordMgr}; refer to section
@ref{416e,,HTTPPasswordMgr Objects} for information on the interface that must be
supported.
@end deffn

@geindex AbstractDigestAuthHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request AbstractDigestAuthHandler}@anchor{1f5f}
@deffn {Κλάση} 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{416c,,HTTPPasswordMgr}; refer to section
@ref{416e,,HTTPPasswordMgr Objects} for information on the interface that must be
supported.


Άλλαξε στην έκδοση 3.14: Added support for HTTP digest authentication algorithm @code{SHA-256}.

@end deffn

@geindex HTTPDigestAuthHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request HTTPDigestAuthHandler}@anchor{4172}
@deffn {Κλάση} urllib.request.HTTPDigestAuthHandler (password_mgr=None)

Handle authentication with the remote host. `password_mgr', if given, should
be something that is compatible with @ref{416c,,HTTPPasswordMgr}; refer to
section @ref{416e,,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{277,,ValueError} when presented with an authentication scheme other than
Digest or Basic.


Άλλαξε στην έκδοση 3.3: Raise @ref{277,,ValueError} on unsupported Authentication Scheme.

@end deffn

@geindex ProxyDigestAuthHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request ProxyDigestAuthHandler}@anchor{4173}
@deffn {Κλάση} urllib.request.ProxyDigestAuthHandler (password_mgr=None)

Handle authentication with the proxy. `password_mgr', if given, should be
something that is compatible with @ref{416c,,HTTPPasswordMgr}; refer to section
@ref{416e,,HTTPPasswordMgr Objects} for information on the interface that must be
supported.
@end deffn

@geindex HTTPHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request HTTPHandler}@anchor{10b8}
@deffn {Κλάση} urllib.request.HTTPHandler

A class to handle opening of HTTP URLs.
@end deffn

@geindex HTTPSHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request HTTPSHandler}@anchor{15ca}
@deffn {Κλάση} 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{224,,http.client.HTTPSConnection}.


Άλλαξε στην έκδοση 3.2: `context' and `check_hostname' were added.

@end deffn

@geindex FileHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request FileHandler}@anchor{4168}
@deffn {Κλάση} urllib.request.FileHandler

Open local files.
@end deffn

@geindex DataHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request DataHandler}@anchor{1380}
@deffn {Κλάση} urllib.request.DataHandler

Open data URLs.


Added in version 3.4.

@end deffn

@geindex FTPHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request FTPHandler}@anchor{4167}
@deffn {Κλάση} urllib.request.FTPHandler

Open FTP URLs.
@end deffn

@geindex CacheFTPHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request CacheFTPHandler}@anchor{1c9d}
@deffn {Κλάση} urllib.request.CacheFTPHandler

Open FTP URLs, keeping a cache of open FTP connections to minimize delays.
@end deffn

@geindex UnknownHandler (κλάση σε urllib.request)
@anchor{library/urllib request urllib request UnknownHandler}@anchor{4162}
@deffn {Κλάση} urllib.request.UnknownHandler

A catch-all class to handle unknown URLs.
@end deffn

@geindex HTTPErrorProcessor (κλάση σε urllib.request)
@anchor{library/urllib request urllib request HTTPErrorProcessor}@anchor{4169}
@deffn {Κλάση} 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:: 
* Examples: Examples<23>. 
* 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{4174}@anchor{library/urllib request request-objects}@anchor{4175}
@subsubsection Request Objects


The following methods describe @ref{1381,,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 (ιδιότητα της urllib.request.Request)
@anchor{library/urllib request urllib request Request full_url}@anchor{1383}
@deffn {Ιδιότητα} Request.full_url

The original URL passed to the constructor.


Άλλαξε στην έκδοση 3.4.


Request.full_url is a property with setter, getter and a deleter. Getting
@code{full_url} returns the original request URL with the
fragment, if it was present.
@end deffn

@geindex type (ιδιότητα της urllib.request.Request)
@anchor{library/urllib request urllib request Request type}@anchor{4176}
@deffn {Ιδιότητα} Request.type

The URI scheme.
@end deffn

@geindex host (ιδιότητα της urllib.request.Request)
@anchor{library/urllib request urllib request Request host}@anchor{4177}
@deffn {Ιδιότητα} Request.host

The URI authority, typically a host, but may also contain a port
separated by a colon.
@end deffn

@geindex origin_req_host (ιδιότητα της urllib.request.Request)
@anchor{library/urllib request urllib request Request origin_req_host}@anchor{4178}
@deffn {Ιδιότητα} Request.origin_req_host

The original host for the request, without port.
@end deffn

@geindex selector (ιδιότητα της urllib.request.Request)
@anchor{library/urllib request urllib request Request selector}@anchor{4179}
@deffn {Ιδιότητα} Request.selector

The URI path.  If the @ref{1381,,Request} uses a proxy, then selector
will be the full URL that is passed to the proxy.
@end deffn

@geindex data (ιδιότητα της urllib.request.Request)
@anchor{library/urllib request urllib request Request data}@anchor{1384}
@deffn {Ιδιότητα} Request.data

The entity body for the request, or @code{None} if not specified.


Άλλαξε στην έκδοση 3.4: Changing value of @code{Request.data} now deletes «Content-Length»
header if it was previously set or calculated.

@end deffn

@geindex unverifiable (ιδιότητα της urllib.request.Request)
@anchor{library/urllib request urllib request Request unverifiable}@anchor{417a}
@deffn {Ιδιότητα} 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 (ιδιότητα της urllib.request.Request)
@anchor{library/urllib request urllib request Request method}@anchor{1382}
@deffn {Ιδιότητα} Request.method

The HTTP request method to use.  By default its value is @ref{a65,,None},
which means that @ref{1512,,get_method()} will do its normal computation
of the method to be used.  Its value can be set (thus overriding the default
computation in @code{get_method()}) either by providing a default
value by setting it at the class level in a @ref{1381,,Request} subclass, or by
passing a value in to the @code{Request} constructor via the `method'
argument.


Added in version 3.3.



Άλλαξε στην έκδοση 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() (μέθοδος της urllib.request.Request)
@anchor{library/urllib request urllib request Request get_method}@anchor{1512}
@deffn {Μέθοδος} Request.get_method ()

Return a string indicating the HTTP request method.  If
@ref{1382,,Request.method} is not @code{None}, return its value, otherwise return
@code{'GET'} if @ref{1384,,Request.data} is @code{None}, or @code{'POST'} if it’s not.
This is only meaningful for HTTP requests.


Άλλαξε στην έκδοση 3.3: get_method now looks at the value of @ref{1382,,Request.method}.

@end deffn

@geindex add_header() (μέθοδος της urllib.request.Request)
@anchor{library/urllib request urllib request Request add_header}@anchor{416a}
@deffn {Μέθοδος} 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() (μέθοδος της urllib.request.Request)
@anchor{library/urllib request urllib request Request add_unredirected_header}@anchor{417b}
@deffn {Μέθοδος} Request.add_unredirected_header (key, header)

Add a header that will not be added to a redirected request.
@end deffn

@geindex has_header() (μέθοδος της urllib.request.Request)
@anchor{library/urllib request urllib request Request has_header}@anchor{417c}
@deffn {Μέθοδος} Request.has_header (header)

Return whether the instance has the named header (checks both regular and
unredirected).
@end deffn

@geindex remove_header() (μέθοδος της urllib.request.Request)
@anchor{library/urllib request urllib request Request remove_header}@anchor{1386}
@deffn {Μέθοδος} Request.remove_header (header)

Remove named header from the request instance (both from regular and
unredirected headers).


Added in version 3.4.

@end deffn

@geindex get_full_url() (μέθοδος της urllib.request.Request)
@anchor{library/urllib request urllib request Request get_full_url}@anchor{417d}
@deffn {Μέθοδος} Request.get_full_url ()

Return the URL given in the constructor.


Άλλαξε στην έκδοση 3.4.


Returns @ref{1383,,Request.full_url}
@end deffn

@geindex set_proxy() (μέθοδος της urllib.request.Request)
@anchor{library/urllib request urllib request Request set_proxy}@anchor{417e}
@deffn {Μέθοδος} 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() (μέθοδος της urllib.request.Request)
@anchor{library/urllib request urllib request Request get_header}@anchor{417f}
@deffn {Μέθοδος} 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() (μέθοδος της urllib.request.Request)
@anchor{library/urllib request urllib request Request header_items}@anchor{4180}
@deffn {Μέθοδος} Request.header_items ()

Return a list of tuples (header_name, header_value) of the Request headers.
@end deffn


Άλλαξε στην έκδοση 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{4181}@anchor{library/urllib request openerdirector-objects}@anchor{4182}
@subsubsection OpenerDirector Objects


@ref{199b,,OpenerDirector} instances have the following methods:

@geindex add_handler() (μέθοδος της urllib.request.OpenerDirector)
@anchor{library/urllib request urllib request OpenerDirector add_handler}@anchor{4183}
@deffn {Μέθοδος} OpenerDirector.add_handler (handler)

`handler' should be an instance of @ref{4164,,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{4184,,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{4185,,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{4186,,BaseHandler.<protocol>_request()} for more information.

@item 
@code{<protocol>_response()} — signal that the handler knows how to
post-process `protocol' responses.

See @ref{4187,,BaseHandler.<protocol>_response()} for more information.
@end itemize
@end deffn

@geindex open() (μέθοδος της urllib.request.OpenerDirector)
@anchor{library/urllib request urllib request OpenerDirector open}@anchor{1385}
@deffn {Μέθοδος} 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{57f,,urlopen()} (which simply calls the @code{open()}
method on the currently installed global @ref{199b,,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() (μέθοδος της urllib.request.OpenerDirector)
@anchor{library/urllib request urllib request OpenerDirector error}@anchor{4188}
@deffn {Μέθοδος} 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{57f,,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{a65,,None}
value (ie. a response), or raises an exception (usually
@ref{53a,,URLError}).  Exceptions are allowed to propagate.

In fact, the above algorithm is first tried for methods named
@ref{4189,,default_open()}.  If all such methods return @ref{a65,,None}, the algorithm
is repeated for methods named like @code{<protocol>_open()}.  If all such methods
return @code{None}, the algorithm is repeated for methods named
@ref{418a,,unknown_open()}.

Note that the implementation of these methods may involve calls of the parent
@ref{199b,,OpenerDirector} instance’s @ref{1385,,open()} and
@ref{4188,,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{418b}@anchor{library/urllib request basehandler-objects}@anchor{418c}
@subsubsection BaseHandler Objects


@ref{4164,,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() (μέθοδος της urllib.request.BaseHandler)
@anchor{library/urllib request urllib request BaseHandler add_parent}@anchor{418d}
@deffn {Μέθοδος} BaseHandler.add_parent (director)

Add a director as parent.
@end deffn

@geindex close() (μέθοδος της urllib.request.BaseHandler)
@anchor{library/urllib request urllib request BaseHandler close}@anchor{418e}
@deffn {Μέθοδος} BaseHandler.close ()

Remove any parents.
@end deffn

The following attribute and methods should only be used by classes derived from
@ref{4164,,BaseHandler}.

@cartouche
@quotation Σημείωση 
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 (ιδιότητα της urllib.request.BaseHandler)
@anchor{library/urllib request urllib request BaseHandler parent}@anchor{418f}
@deffn {Ιδιότητα} BaseHandler.parent

A valid @ref{199b,,OpenerDirector}, which can be used to open using a different
protocol, or handle errors.
@end deffn

@geindex default_open() (μέθοδος της urllib.request.BaseHandler)
@anchor{library/urllib request urllib request BaseHandler default_open}@anchor{4189}
@deffn {Μέθοδος} BaseHandler.default_open (req)

This method is `not' defined in @ref{4164,,BaseHandler}, but subclasses should
define it if they want to catch all URLs.

This method, if implemented, will be called by the parent
@ref{199b,,OpenerDirector}.  It should return a file-like object as described in
the return value of the @ref{1385,,open()} method of @code{OpenerDirector}, or @code{None}.
It should raise @ref{53a,,URLError}, unless a truly exceptional
thing happens (for example, @ref{18fa,,MemoryError} should not be mapped to
@code{URLError}).

This method will be called before any protocol-specific open method.
@end deffn

@anchor{library/urllib request protocol-open}@anchor{4184}
@deffn {Μέθοδος} BaseHandler.<protocol>_open(req)

This method is `not' defined in @ref{4164,,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{199b,,OpenerDirector}.
Return values should be the same as for  @ref{4189,,default_open()}.
@end deffn

@geindex unknown_open() (μέθοδος της urllib.request.BaseHandler)
@anchor{library/urllib request urllib request BaseHandler unknown_open}@anchor{418a}
@deffn {Μέθοδος} BaseHandler.unknown_open (req)

This method is `not' defined in @ref{4164,,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{418f,,parent}
@ref{199b,,OpenerDirector}.  Return values should be the same as for
@ref{4189,,default_open()}.
@end deffn

@geindex http_error_default() (μέθοδος της urllib.request.BaseHandler)
@anchor{library/urllib request urllib request BaseHandler http_error_default}@anchor{4190}
@deffn {Μέθοδος} BaseHandler.http_error_default (req, fp, code, msg, hdrs)

This method is `not' defined in @ref{4164,,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{199b,,OpenerDirector} getting
the error, and should not normally be called in other circumstances.

@ref{199b,,OpenerDirector} will call this method with five positional arguments:


@enumerate 

@item 
a @ref{1381,,Request} object,

@item 
a file-like object with the HTTP error body,

@item 
the three-digit code of the error, as a string,

@item 
the user-visible explanation of the code, as a string, and

@item 
the headers of the error, as a mapping object.
@end enumerate

Return values and exceptions raised should be the same as those of
@ref{57f,,urlopen()}.
@end deffn

@anchor{library/urllib request http-error-nnn}@anchor{4185}
@deffn {Μέθοδος} 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{4164,,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{4190,,http_error_default()}.
@end deffn

@anchor{library/urllib request protocol-request}@anchor{4186}
@deffn {Μέθοδος} BaseHandler.<protocol>_request(req)

This method is `not' defined in @ref{4164,,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{199b,,OpenerDirector}.
`req' will be a @ref{1381,,Request} object. The return value should be a
@code{Request} object.
@end deffn

@anchor{library/urllib request protocol-response}@anchor{4187}
@deffn {Μέθοδος} BaseHandler.<protocol>_response(req, response)

This method is `not' defined in @ref{4164,,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{199b,,OpenerDirector}.
`req' will be a @ref{1381,,Request} object. `response' will be an object
implementing the same interface as the return value of @ref{57f,,urlopen()}.  The
return value should implement the same interface as the return value of
@code{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{4191}@anchor{library/urllib request httpredirecthandler-objects}@anchor{4192}
@subsubsection HTTPRedirectHandler Objects


@cartouche
@quotation Σημείωση 
Some HTTP redirections require action from this module’s client code.  If this
is the case, @ref{1387,,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{1387,,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() (μέθοδος της urllib.request.HTTPRedirectHandler)
@anchor{library/urllib request urllib request HTTPRedirectHandler redirect_request}@anchor{4193}
@deffn {Μέθοδος} HTTPRedirectHandler.redirect_request (req, fp, code, msg, hdrs, newurl)

Return a @ref{1381,,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 @code{Request} to allow @code{http_error_30*()} to perform the
redirect to `newurl'.  Otherwise, raise @ref{1387,,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 Σημείωση 
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() (μέθοδος της urllib.request.HTTPRedirectHandler)
@anchor{library/urllib request urllib request HTTPRedirectHandler http_error_301}@anchor{4194}
@deffn {Μέθοδος} 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{199b,,OpenerDirector} when getting an HTTP “moved permanently” response.
@end deffn

@geindex http_error_302() (μέθοδος της urllib.request.HTTPRedirectHandler)
@anchor{library/urllib request urllib request HTTPRedirectHandler http_error_302}@anchor{4195}
@deffn {Μέθοδος} HTTPRedirectHandler.http_error_302 (req, fp, code, msg, hdrs)

The same as @ref{4194,,http_error_301()}, but called for the “found” response.
@end deffn

@geindex http_error_303() (μέθοδος της urllib.request.HTTPRedirectHandler)
@anchor{library/urllib request urllib request HTTPRedirectHandler http_error_303}@anchor{4196}
@deffn {Μέθοδος} HTTPRedirectHandler.http_error_303 (req, fp, code, msg, hdrs)

The same as @ref{4194,,http_error_301()}, but called for the “see other” response.
@end deffn

@geindex http_error_307() (μέθοδος της urllib.request.HTTPRedirectHandler)
@anchor{library/urllib request urllib request HTTPRedirectHandler http_error_307}@anchor{4197}
@deffn {Μέθοδος} HTTPRedirectHandler.http_error_307 (req, fp, code, msg, hdrs)

The same as @ref{4194,,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() (μέθοδος της urllib.request.HTTPRedirectHandler)
@anchor{library/urllib request urllib request HTTPRedirectHandler http_error_308}@anchor{4198}
@deffn {Μέθοδος} HTTPRedirectHandler.http_error_308 (req, fp, code, msg, hdrs)

The same as @ref{4194,,http_error_301()}, but called for the “permanent redirect”
response. It does not allow changing the request method from @code{POST}
to @code{GET}.


Added in 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{4199}@anchor{library/urllib request httpcookieprocessor-objects}@anchor{419a}
@subsubsection HTTPCookieProcessor Objects


@ref{416b,,HTTPCookieProcessor} instances have one attribute:

@geindex cookiejar (ιδιότητα της urllib.request.HTTPCookieProcessor)
@anchor{library/urllib request urllib request HTTPCookieProcessor cookiejar}@anchor{419b}
@deffn {Ιδιότητα} HTTPCookieProcessor.cookiejar

The @ref{419c,,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{419d}@anchor{library/urllib request proxyhandler-objects}@anchor{419e}
@subsubsection ProxyHandler Objects



@deffn {Μέθοδος} ProxyHandler.<protocol>_open(request)

The @ref{1fa5,,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{416e}@anchor{library/urllib request httppasswordmgr-objects}@anchor{419f}
@subsubsection HTTPPasswordMgr Objects


These methods are available on @ref{416c,,HTTPPasswordMgr} and
@ref{416d,,HTTPPasswordMgrWithDefaultRealm} objects.

@geindex add_password() (μέθοδος της urllib.request.HTTPPasswordMgr)
@anchor{library/urllib request urllib request HTTPPasswordMgr add_password}@anchor{41a0}
@deffn {Μέθοδος} 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() (μέθοδος της urllib.request.HTTPPasswordMgr)
@anchor{library/urllib request urllib request HTTPPasswordMgr find_user_password}@anchor{1dcf}
@deffn {Μέθοδος} 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{416d,,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{416f}@anchor{library/urllib request httppasswordmgrwithpriorauth-objects}@anchor{41a1}
@subsubsection HTTPPasswordMgrWithPriorAuth Objects


This password manager extends @ref{416d,,HTTPPasswordMgrWithDefaultRealm} to support
tracking URIs for which authentication credentials should always be sent.

@geindex add_password() (μέθοδος της urllib.request.HTTPPasswordMgrWithPriorAuth)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithPriorAuth add_password}@anchor{41a2}
@deffn {Μέθοδος} HTTPPasswordMgrWithPriorAuth.add_password (realm, uri, user, passwd, is_authenticated=False)

`realm', `uri', `user', `passwd' are as for
@ref{41a0,,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() (μέθοδος της urllib.request.HTTPPasswordMgrWithPriorAuth)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithPriorAuth find_user_password}@anchor{41a3}
@deffn {Μέθοδος} HTTPPasswordMgrWithPriorAuth.find_user_password (realm, authuri)

Same as for @ref{416d,,HTTPPasswordMgrWithDefaultRealm} objects
@end deffn

@geindex update_authenticated() (μέθοδος της urllib.request.HTTPPasswordMgrWithPriorAuth)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithPriorAuth update_authenticated}@anchor{41a4}
@deffn {Μέθοδος} 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() (μέθοδος της urllib.request.HTTPPasswordMgrWithPriorAuth)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithPriorAuth is_authenticated}@anchor{1dd0}
@deffn {Μέθοδος} 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{41a5}@anchor{library/urllib request abstractbasicauthhandler-objects}@anchor{41a6}
@subsubsection AbstractBasicAuthHandler Objects


@geindex http_error_auth_reqed() (μέθοδος της urllib.request.AbstractBasicAuthHandler)
@anchor{library/urllib request urllib request AbstractBasicAuthHandler http_error_auth_reqed}@anchor{41a7}
@deffn {Μέθοδος} 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{1381,,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{41a8}@anchor{library/urllib request httpbasicauthhandler-objects}@anchor{41a9}
@subsubsection HTTPBasicAuthHandler Objects


@geindex http_error_401() (μέθοδος της urllib.request.HTTPBasicAuthHandler)
@anchor{library/urllib request urllib request HTTPBasicAuthHandler http_error_401}@anchor{41aa}
@deffn {Μέθοδος} 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{41ab}@anchor{library/urllib request proxybasicauthhandler-objects}@anchor{41ac}
@subsubsection ProxyBasicAuthHandler Objects


@geindex http_error_407() (μέθοδος της urllib.request.ProxyBasicAuthHandler)
@anchor{library/urllib request urllib request ProxyBasicAuthHandler http_error_407}@anchor{41ad}
@deffn {Μέθοδος} 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{41ae}@anchor{library/urllib request abstractdigestauthhandler-objects}@anchor{41af}
@subsubsection AbstractDigestAuthHandler Objects


@geindex http_error_auth_reqed() (μέθοδος της urllib.request.AbstractDigestAuthHandler)
@anchor{library/urllib request urllib request AbstractDigestAuthHandler http_error_auth_reqed}@anchor{41b0}
@deffn {Μέθοδος} 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{1381,,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{41b1}@anchor{library/urllib request httpdigestauthhandler-objects}@anchor{41b2}
@subsubsection HTTPDigestAuthHandler Objects


@geindex http_error_401() (μέθοδος της urllib.request.HTTPDigestAuthHandler)
@anchor{library/urllib request urllib request HTTPDigestAuthHandler http_error_401}@anchor{41b3}
@deffn {Μέθοδος} 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{41b4}@anchor{library/urllib request proxydigestauthhandler-objects}@anchor{41b5}
@subsubsection ProxyDigestAuthHandler Objects


@geindex http_error_407() (μέθοδος της urllib.request.ProxyDigestAuthHandler)
@anchor{library/urllib request urllib request ProxyDigestAuthHandler http_error_407}@anchor{41b6}
@deffn {Μέθοδος} 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{41b7}@anchor{library/urllib request httphandler-objects}@anchor{41b8}
@subsubsection HTTPHandler Objects


@geindex http_open() (μέθοδος της urllib.request.HTTPHandler)
@anchor{library/urllib request urllib request HTTPHandler http_open}@anchor{41b9}
@deffn {Μέθοδος} HTTPHandler.http_open (req)

Send an HTTP request, which can be either GET or POST, depending on
@code{req.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{41ba}@anchor{library/urllib request httpshandler-objects}@anchor{41bb}
@subsubsection HTTPSHandler Objects


@geindex https_open() (μέθοδος της urllib.request.HTTPSHandler)
@anchor{library/urllib request urllib request HTTPSHandler https_open}@anchor{41bc}
@deffn {Μέθοδος} HTTPSHandler.https_open (req)

Send an HTTPS request, which can be either GET or POST, depending on
@code{req.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{41bd}@anchor{library/urllib request filehandler-objects}@anchor{41be}
@subsubsection FileHandler Objects


@geindex file_open() (μέθοδος της urllib.request.FileHandler)
@anchor{library/urllib request urllib request FileHandler file_open}@anchor{41bf}
@deffn {Μέθοδος} FileHandler.file_open (req)

Open the file locally, if there is no host name, or the host name is
@code{'localhost'}.


Άλλαξε στην έκδοση 3.2: This method is applicable only for local hostnames.  When a remote
hostname is given, a @ref{53a,,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{41c0}@anchor{library/urllib request datahandler-objects}@anchor{41c1}
@subsubsection DataHandler Objects


@geindex data_open() (μέθοδος της urllib.request.DataHandler)
@anchor{library/urllib request urllib request DataHandler data_open}@anchor{41c2}
@deffn {Μέθοδος} 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{277,,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{41c3}@anchor{library/urllib request ftphandler-objects}@anchor{41c4}
@subsubsection FTPHandler Objects


@geindex ftp_open() (μέθοδος της urllib.request.FTPHandler)
@anchor{library/urllib request urllib request FTPHandler ftp_open}@anchor{41c5}
@deffn {Μέθοδος} 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{41c6}@anchor{library/urllib request cacheftphandler-objects}@anchor{41c7}
@subsubsection CacheFTPHandler Objects


@ref{1c9d,,CacheFTPHandler} objects are @ref{4167,,FTPHandler} objects with the
following additional methods:

@geindex setTimeout() (μέθοδος της urllib.request.CacheFTPHandler)
@anchor{library/urllib request urllib request CacheFTPHandler setTimeout}@anchor{41c8}
@deffn {Μέθοδος} CacheFTPHandler.setTimeout (t)

Set timeout of connections to `t' seconds.
@end deffn

@geindex setMaxConns() (μέθοδος της urllib.request.CacheFTPHandler)
@anchor{library/urllib request urllib request CacheFTPHandler setMaxConns}@anchor{41c9}
@deffn {Μέθοδος} 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{41ca}@anchor{library/urllib request unknownhandler-objects}@anchor{41cb}
@subsubsection UnknownHandler Objects


@geindex unknown_open() (μέθοδος της urllib.request.UnknownHandler)
@anchor{library/urllib request urllib request UnknownHandler unknown_open}@anchor{41cc}
@deffn {Μέθοδος} UnknownHandler.unknown_open ()

Raise a @ref{53a,,URLError} exception.
@end deffn

@node HTTPErrorProcessor Objects,Examples<23>,UnknownHandler Objects,urllib request — Extensible library for opening URLs
@anchor{library/urllib request http-error-processor-objects}@anchor{41cd}@anchor{library/urllib request httperrorprocessor-objects}@anchor{41ce}
@subsubsection HTTPErrorProcessor Objects


@geindex http_response() (μέθοδος της urllib.request.HTTPErrorProcessor)
@anchor{library/urllib request urllib request HTTPErrorProcessor http_response}@anchor{41cf}
@deffn {Μέθοδος} 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{4188,,OpenerDirector.error()}.
Eventually, @ref{4165,,HTTPDefaultErrorHandler} will raise an
@ref{1387,,HTTPError} if no other handler handles the error.
@end deffn

@geindex https_response() (μέθοδος της urllib.request.HTTPErrorProcessor)
@anchor{library/urllib request urllib request HTTPErrorProcessor https_response}@anchor{41d0}
@deffn {Μέθοδος} HTTPErrorProcessor.https_response (request, response)

Process HTTPS error responses.

The behavior is same as @ref{41cf,,http_response()}.
@end deffn

@node Examples<23>,Legacy interface,HTTPErrorProcessor Objects,urllib request — Extensible library for opening URLs
@anchor{library/urllib request examples}@anchor{41d1}@anchor{library/urllib request urllib-request-examples}@anchor{41d2}
@subsubsection Examples


In addition to the examples below, more examples are given in
@ref{41d3,,HOWTO Fetch Internet Resources Using The urllib Package}.

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>\n<!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->\n<!--[if IE 7]>      <html class="no-js ie7 lt-ie8 lt-ie9">          <![endif]-->\n<!--[if IE 8]>      <html class="no-js ie8 lt-ie9">
@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 HTML spec document, @indicateurl{https://html.spec.whatwg.org/#charset}, lists
the various ways in which an HTML or an XML document could have specified its
encoding information.

For additional information, see the W3C document: @indicateurl{https://www.w3.org/International/questions/qa-html-encoding-declarations}.

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>
<!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->
<!-
@end example

It is also possible to achieve the same result without using the
@ref{478,,context manager} approach:

@example
>>> import urllib.request
>>> f = urllib.request.urlopen('http://www.python.org/')
>>> try:
...     print(f.read(100).decode('utf-8'))
... finally:
...     f.close()
...
<!doctype html>
<!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->
<!--
@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{1381,,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)
with urllib.request.urlopen('http://www.example.com/login.html') as f:
    print(f.read().decode('utf-8'))
@end example

@ref{581,,build_opener()} provides many handlers by default, including a
@ref{1fa5,,ProxyHandler}.  By default, @code{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{1fa5,,ProxyHandler} with one that uses
programmatically supplied proxy URLs, and adds proxy authorization support with
@ref{4171,,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:
with opener.open('http://www.example.com/login.html') as f:
   print(f.read().decode('utf-8'))
@end example

Adding HTTP headers:

Use the `headers' argument to the @ref{1381,,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: . . .)')
with urllib.request.urlopen(req) as f:
    print(f.read().decode('utf-8'))
@end example

@ref{199b,,OpenerDirector} automatically adds a @code{User-Agent} header to
every @ref{1381,,Request}.  To change this:

@example
import urllib.request
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
with opener.open('http://www.example.com/') as f:
   print(f.read().decode('utf-8'))
@end example

Also, remember that a few standard headers (@code{Content-Length},
@code{Content-Type} and @code{Host})
are added when the @ref{1381,,Request} is passed to @ref{57f,,urlopen()} (or
@ref{1385,,OpenerDirector.open()}).
@anchor{library/urllib request urllib-examples}@anchor{41d4}
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.build_opener(urllib.request.ProxyHandler(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.build_opener(urllib.request.ProxyHandler(@{@}@}))
>>> with opener.open("http://www.python.org/") as f:
...     f.read().decode('utf-8')
...
@end example

@node Legacy interface,urllib request Restrictions,Examples<23>,urllib request — Extensible library for opening URLs
@anchor{library/urllib request legacy-interface}@anchor{41d5}
@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() (στη μονάδα urllib.request)
@anchor{library/urllib request urllib request urlretrieve}@anchor{580}
@deffn {Συνάρτηση} 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{57f,,urlopen()} returned (for
a remote object). Exceptions are the same as for @code{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{1246,,urllib.parse.urlencode()} function.

@code{urlretrieve()} will raise @ref{41d6,,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() (στη μονάδα urllib.request)
@anchor{library/urllib request urllib request urlcleanup}@anchor{1fac}
@deffn {Συνάρτηση} urllib.request.urlcleanup ()

Cleans up temporary files that may have been left behind by previous
calls to @ref{580,,urlretrieve()}.
@end deffn

@node urllib request Restrictions,,Legacy interface,urllib request — Extensible library for opening URLs
@anchor{library/urllib request urllib-request-restrictions}@anchor{41d7}
@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.


Άλλαξε στην έκδοση 3.4: Added support for data URLs.


@item 
The caching feature of @ref{580,,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{57f,,urlopen()} and @ref{580,,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{57f,,urlopen()} or @ref{580,,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{70,,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{61,,ftplib} module.
@end itemize

@node urllib response — Response classes used by urllib,urllib parse — Parse URLs into components,urllib request — Extensible library for opening URLs,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/urllib request module-urllib response}@anchor{115}@anchor{library/urllib request urllib-response-response-classes-used-by-urllib}@anchor{41d8}
@subsection @code{urllib.response} — Response classes used by urllib


@geindex module; urllib.response

The @code{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 @code{urllib.request} module.
The typical response object is a @ref{4160,,urllib.response.addinfourl} instance:

@geindex addinfourl (κλάση σε urllib.response)
@anchor{library/urllib request urllib response addinfourl}@anchor{4160}
@deffn {Κλάση} urllib.response.addinfourl

@geindex url (ιδιότητα της urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl url}@anchor{1b08}
@deffn {Ιδιότητα} url

URL of the resource retrieved, commonly used to determine if a redirect was followed.
@end deffn

@geindex headers (ιδιότητα της urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl headers}@anchor{41d9}
@deffn {Ιδιότητα} headers

Returns the headers of the response in the form of an @ref{216,,EmailMessage} instance.
@end deffn

@geindex status (ιδιότητα της urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl status}@anchor{41da}
@deffn {Ιδιότητα} status


Added in version 3.9.


Status code returned by server.
@end deffn

@geindex geturl() (μέθοδος της urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl geturl}@anchor{41db}
@deffn {Μέθοδος} geturl ()


Αποσύρθηκε στην έκδοση 3.9: Deprecated in favor of @ref{1b08,,url}.

@end deffn

@geindex info() (μέθοδος της urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl info}@anchor{41dc}
@deffn {Μέθοδος} info ()


Αποσύρθηκε στην έκδοση 3.9: Deprecated in favor of @ref{41d9,,headers}.

@end deffn

@geindex code (ιδιότητα της urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl code}@anchor{41dd}
@deffn {Ιδιότητα} code


Αποσύρθηκε στην έκδοση 3.9: Deprecated in favor of @ref{41da,,status}.

@end deffn

@geindex getcode() (μέθοδος της urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl getcode}@anchor{41de}
@deffn {Μέθοδος} getcode ()


Αποσύρθηκε στην έκδοση 3.9: Deprecated in favor of @ref{41da,,status}.

@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node urllib parse — Parse URLs into components,urllib error — Exception classes raised by urllib request,urllib response — Response classes used by urllib,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/urllib parse doc}@anchor{41df}@anchor{library/urllib parse module-urllib parse}@anchor{113}@anchor{library/urllib parse translation-repo}@anchor{41e0}@anchor{library/urllib parse urllib-parse-parse-urls-into-components}@anchor{41e1}
@subsection @code{urllib.parse} — Parse URLs into components


@geindex module; urllib.parse

`Source code:' Lib/urllib/parse.py@footnote{https://github.com/python/cpython/tree/main/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}.

`Λεπτομέρεια υλοποίησης 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{1ba4,,--with-app-store-compliance} option.

The @code{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{41e2}
@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 urlsplit() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse urlsplit}@anchor{2a3}
@deffn {Συνάρτηση} urllib.parse.urlsplit (urlstring, scheme=None, allow_fragments=True, *, missing_as_none=False)

Parse a URL into five components, returning a 5-item @ref{a3d,,named tuple}
@ref{41e3,,SplitResult} or @ref{41e4,,SplitResultBytes}.
This corresponds to the general structure of a URL:
@code{scheme://netloc/path?query#fragment}.
Each tuple item is a string, possibly empty, or @code{None} if
`missing_as_none' is true.
Not defined component are represented an empty string (by default) or
@code{None} if `missing_as_none' is true.
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 urlsplit
>>> urlsplit("scheme://netloc/path?query#fragment")
SplitResult(scheme='scheme', netloc='netloc', path='/path',
            query='query', fragment='fragment')
>>> o = urlsplit("http://docs.python.org:80/3/library/urllib.parse.html?"
...              "highlight=params#url-parsing")
>>> o
SplitResult(scheme='http', netloc='docs.python.org:80',
            path='/3/library/urllib.parse.html',
            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'
>>> urlsplit("http://docs.python.org?")
SplitResult(scheme='http', netloc='docs.python.org', path='@w{'},
            query='@w{'}, fragment='@w{'})
>>> urlsplit("http://docs.python.org?", missing_as_none=True)
SplitResult(scheme='http', netloc='docs.python.org', path='@w{'},
            query='@w{'}, fragment=None)
@end example

Following the syntax specifications in 
@geindex RFC; RFC 1808
RFC 1808@footnote{https://datatracker.ietf.org/doc/html/rfc1808.html}, @code{urlsplit()} 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 urlsplit
>>> urlsplit('//www.cwi.nl:80/%7Eguido/Python.html')
SplitResult(scheme='@w{'}, netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            query='@w{'}, fragment='@w{'})
>>> urlsplit('www.cwi.nl/%7Eguido/Python.html')
SplitResult(scheme='@w{'}, netloc='@w{'}, path='www.cwi.nl/%7Eguido/Python.html',
            query='@w{'}, fragment='@w{'})
>>> urlsplit('help/Python.html')
SplitResult(scheme='@w{'}, netloc='@w{'}, path='help/Python.html',
            query='@w{'}, fragment='@w{'})
>>> urlsplit('help/Python.html', missing_as_none=True)
SplitResult(scheme=None, netloc=None, path='help/Python.html',
            query=None, fragment=None)
@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' or @code{None}, except that the @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
or query component, and @code{fragment} is set to @code{None} or the empty
string (depending on the value of `missing_as_none') in the return value.

The return value is a @ref{a3d,,named tuple}, which means that its items can
be accessed by index or as named attributes, which are:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribute

@tab

Index

@tab

Value

@tab

Value if not present

@item

@code{scheme}

@tab

0

@tab

URL scheme specifier

@tab

`scheme' parameter or
empty string @footnote{
Depending on the value of the `missing_as_none' argument.
}

@item

@code{netloc}

@tab

1

@tab

Network location part

@tab

@code{None} or empty string @footnote{
Depending on the value of the `missing_as_none' argument.
}

@item

@code{path}

@tab

2

@tab

Hierarchical path

@tab

empty string

@item

@code{query}

@tab

3

@tab

Query component

@tab

@code{None} or empty string @footnote{
Depending on the value of the `missing_as_none' argument.
}

@item

@code{fragment}

@tab

4

@tab

Fragment identifier

@tab

@code{None} or empty string @footnote{
Depending on the value of the `missing_as_none' argument.
}

@item

@code{username}

@tab

@tab

User name

@tab

@code{None}

@item

@code{password}

@tab

@tab

Password

@tab

@code{None}

@item

@code{hostname}

@tab

@tab

Host name (lower case)

@tab

@code{None}

@item

@code{port}

@tab

@tab

Port number as integer,
if present

@tab

@code{None}

@end multitable


Reading the @code{port} attribute will raise a @ref{277,,ValueError} if
an invalid port is specified in the URL.  See section
@ref{41e5,,Structured Parse Results} for more information on the result object.

Unmatched square brackets in the @code{netloc} attribute will raise a
@ref{277,,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{277,,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 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html}, 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.

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 @ref{41e3,,SplitResult} object
replacing specified fields with new values.

@example
>>> from urllib.parse import urlsplit
>>> u = urlsplit('//www.cwi.nl:80/%7Eguido/Python.html')
>>> u
SplitResult(scheme='@w{'}, netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            query='@w{'}, fragment='@w{'})
>>> u._replace(scheme='http')
SplitResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            query='@w{'}, fragment='@w{'})
@end example

@cartouche
@quotation Προειδοποίηση 
@code{urlsplit()} does not perform validation.  See @ref{41e6,,URL parsing security} for details.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.2: Added IPv6 URL parsing capabilities.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.6: Out-of-range port numbers now raise @ref{277,,ValueError}, instead of
returning @code{None}.



Άλλαξε στην έκδοση 3.8: Characters that affect netloc parsing under NFKC normalization will
now raise @ref{277,,ValueError}.



Άλλαξε στην έκδοση 3.10: ASCII newline and tab characters are stripped from the URL.



Άλλαξε στην έκδοση 3.12: Leading WHATWG C0 control and space characters are stripped from the URL.



Άλλαξε στην έκδοση 3.15: Added the `missing_as_none' parameter.

@end deffn

@geindex parse_qs() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse parse_qs}@anchor{589}
@deffn {Συνάρτηση} 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{277,,ValueError} exception.

The optional `encoding' and `errors' parameters specify how to decode
percent-encoded sequences into Unicode characters, as accepted by the
@ref{ca8,,bytes.decode()} method.

The optional argument `max_num_fields' is the maximum number of fields to
read. If set, then throws a @ref{277,,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{1246,,urllib.parse.urlencode()} function (with the @code{doseq}
parameter set to @code{True}) to convert such dictionaries into query
strings.


Άλλαξε στην έκδοση 3.2: Add `encoding' and `errors' parameters.



Άλλαξε στην έκδοση 3.8: Added `max_num_fields' parameter.



Άλλαξε στην έκδοση 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.



Αποσύρθηκε στην έκδοση 3.14: Accepting objects with false values (like @code{0} and @code{[]}) except empty
strings and byte-like objects and @code{None} is now deprecated.

@end deffn

@geindex parse_qsl() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse parse_qsl}@anchor{588}
@deffn {Συνάρτηση} 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{277,,ValueError} exception.

The optional `encoding' and `errors' parameters specify how to decode
percent-encoded sequences into Unicode characters, as accepted by the
@ref{ca8,,bytes.decode()} method.

The optional argument `max_num_fields' is the maximum number of fields to
read. If set, then throws a @ref{277,,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{1246,,urllib.parse.urlencode()} function to convert such lists of pairs into
query strings.


Άλλαξε στην έκδοση 3.2: Add `encoding' and `errors' parameters.



Άλλαξε στην έκδοση 3.8: Added `max_num_fields' parameter.



Άλλαξε στην έκδοση 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 urlunsplit() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse urlunsplit}@anchor{2a6}
@deffn {Συνάρτηση} urllib.parse.urlunsplit (parts)

@deffnx {Συνάρτηση} urllib.parse.urlunsplit (parts, *, keep_empty)

Construct a URL from a tuple as returned by @ref{2a3,,urlsplit()}. 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 @code{?} with an empty query; the RFC states that these are equivalent).

If `keep_empty' is true, empty strings are kept in the result (for example,
a @code{?} for an empty query), only @code{None} components are omitted.
This allows rebuilding a URL that was parsed with option
@code{missing_as_none=True}.
By default, `keep_empty' is true if `parts' is the result of the
@ref{2a3,,urlsplit()} call with @code{missing_as_none=True}.


Άλλαξε στην έκδοση 3.15: Added the `keep_empty' parameter.

@end deffn

@geindex urlparse() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse urlparse}@anchor{2a4}
@deffn {Συνάρτηση} urllib.parse.urlparse (urlstring, scheme=None, allow_fragments=True, *, missing_as_none=False)

This is similar to @ref{2a3,,urlsplit()}, but additionally splits the `path'
component on `path' and `params'.
This function returns a 6-item @ref{a3d,,named tuple} @ref{41e7,,ParseResult}
or @ref{41e8,,ParseResultBytes}.
Its items are the same as for the @code{urlsplit()} result, except that
`params' is inserted at index 3, between `path' and `query'.

This function is based on obsoleted 
@geindex RFC; RFC 1738
RFC 1738@footnote{https://datatracker.ietf.org/doc/html/rfc1738.html} and 
@geindex RFC; RFC 1808
RFC 1808@footnote{https://datatracker.ietf.org/doc/html/rfc1808.html}, which
listed `params' as the main URL component.
The more recent URL syntax allows parameters to be applied to each segment
of the `path' portion of the URL (see 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html}).
@ref{2a3,,urlsplit()} should generally be used instead of @code{urlparse()}.
A separate function is needed to separate the path segments and parameters.
@end deffn

@geindex urlunparse() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse urlunparse}@anchor{2a7}
@deffn {Συνάρτηση} urllib.parse.urlunparse (parts)

@deffnx {Συνάρτηση} urllib.parse.urlunparse (parts, *, keep_empty)

Combine the elements of a tuple as returned by @ref{2a4,,urlparse()} into a
complete URL as a string. 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).

If `keep_empty' is true, empty strings are kept in the result (for example,
a @code{?} for an empty query), only @code{None} components are omitted.
This allows rebuilding a URL that was parsed with option
@code{missing_as_none=True}.
By default, `keep_empty' is true if `parts' is the result of the
@ref{2a4,,urlparse()} call with @code{missing_as_none=True}.


Άλλαξε στην έκδοση 3.15: Added the `keep_empty' parameter.

@end deffn

@geindex urljoin() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse urljoin}@anchor{1247}
@deffn {Συνάρτηση} 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{2a3,,urlsplit()}.

@cartouche
@quotation Σημείωση 
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{2a3,,urlsplit()} and
@ref{2a6,,urlunsplit()}, removing possible `scheme' and `netloc' parts.
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
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


Άλλαξε στην έκδοση 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() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse urldefrag}@anchor{2a5}
@deffn {Συνάρτηση} urllib.parse.urldefrag (url, *, missing_as_none=False)

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 (by default) or @code{None} if `missing_as_none' is true.

The return value is a @ref{a3d,,named tuple}, its items can be accessed by index
or as named attributes:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribute

@tab

Index

@tab

Value

@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

@code{None} or empty string @footnote{
Depending on the value of the `missing_as_none' argument.
}

@end multitable


See section @ref{41e5,,Structured Parse Results} for more information on the result
object.


Άλλαξε στην έκδοση 3.2: Result is a structured object rather than a simple 2-tuple.



Άλλαξε στην έκδοση 3.15: Added the `missing_as_none' parameter.

@end deffn

@geindex unwrap() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse unwrap}@anchor{41e9}
@deffn {Συνάρτηση} 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 id8}@anchor{41ea}@anchor{library/urllib parse url-parsing-security}@anchor{41e6}
@subsubsection URL parsing security


The @ref{2a3,,urlsplit()} and @ref{2a4,,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 @code{None} (depending on the value of the
`missing_as_none' argument).
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 id9}@anchor{41eb}@anchor{library/urllib parse parsing-ascii-encoded-bytes}@anchor{15ee}
@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{1c7,,bytes} and
@ref{1c6,,bytearray} objects in addition to @ref{1df,,str} objects.

If @ref{1df,,str} data is passed in, the result will also contain only
@code{str} data. If @ref{1c7,,bytes} or @ref{1c6,,bytearray} data is
passed in, the result will contain only @code{bytes} data.

Attempting to mix @ref{1df,,str} data with @ref{1c7,,bytes} or
@ref{1c6,,bytearray} in a single function call will result in a
@ref{291,,TypeError} being raised, while attempting to pass in non-ASCII
byte values will trigger @ref{dd7,,UnicodeDecodeError}.

To support easier conversion of result objects between @ref{1df,,str} and
@ref{1c7,,bytes}, all return values from URL parsing functions provide
either an @code{encode()} method (when the result contains @code{str}
data) or a @code{decode()} method (when the result contains @code{bytes}
data). The signatures of these methods match those of the corresponding
@code{str} and @code{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 @code{bytes} data (for
@code{encode()} methods) or @code{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.


Άλλαξε στην έκδοση 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{41ec}@anchor{library/urllib parse urlparse-result-object}@anchor{41e5}
@subsubsection Structured Parse Results


The result objects from the @ref{2a3,,urlsplit()}, @ref{2a4,,urlparse()}  and
@ref{2a5,,urldefrag()} functions are subclasses of the @ref{1ce,,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() (μέθοδος της urllib.parse.urllib.parse.SplitResult)
@anchor{library/urllib parse urllib parse urllib parse SplitResult geturl}@anchor{41ed}
@deffn {Μέθοδος} 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 unless the URL was parsed
with @code{missing_as_none=True}.

For @ref{2a5,,urldefrag()} results, only empty fragment identifiers will be removed.
For @ref{2a3,,urlsplit()} and @ref{2a4,,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/'
>>> r3 = urlsplit(url, missing_as_none=True)
>>> r3.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{1df,,str} objects:

@geindex DefragResult (κλάση σε urllib.parse)
@anchor{library/urllib parse urllib parse DefragResult}@anchor{41ee}
@deffn {Κλάση} urllib.parse.DefragResult (url, fragment)

Concrete class for @ref{2a5,,urldefrag()} results containing @ref{1df,,str}
data. The @code{encode()} method returns a @ref{41ef,,DefragResultBytes}
instance.


Added in version 3.2.

@end deffn

@geindex ParseResult (κλάση σε urllib.parse)
@anchor{library/urllib parse urllib parse ParseResult}@anchor{41e7}
@deffn {Κλάση} urllib.parse.ParseResult (scheme, netloc, path, params, query, fragment)

Concrete class for @ref{2a4,,urlparse()} results containing @ref{1df,,str}
data. The @code{encode()} method returns a @ref{41e8,,ParseResultBytes}
instance.
@end deffn

@geindex SplitResult (κλάση σε urllib.parse)
@anchor{library/urllib parse urllib parse SplitResult}@anchor{41e3}
@deffn {Κλάση} urllib.parse.SplitResult (scheme, netloc, path, query, fragment)

Concrete class for @ref{2a3,,urlsplit()} results containing @ref{1df,,str}
data. The @code{encode()} method returns a @ref{41e4,,SplitResultBytes}
instance.
@end deffn

The following classes provide the implementations of the parse results when
operating on @ref{1c7,,bytes} or @ref{1c6,,bytearray} objects:

@geindex DefragResultBytes (κλάση σε urllib.parse)
@anchor{library/urllib parse urllib parse DefragResultBytes}@anchor{41ef}
@deffn {Κλάση} urllib.parse.DefragResultBytes (url, fragment)

Concrete class for @ref{2a5,,urldefrag()} results containing @ref{1c7,,bytes}
data. The @code{decode()} method returns a @ref{41ee,,DefragResult}
instance.


Added in version 3.2.

@end deffn

@geindex ParseResultBytes (κλάση σε urllib.parse)
@anchor{library/urllib parse urllib parse ParseResultBytes}@anchor{41e8}
@deffn {Κλάση} urllib.parse.ParseResultBytes (scheme, netloc, path, params, query, fragment)

Concrete class for @ref{2a4,,urlparse()} results containing @ref{1c7,,bytes}
data. The @code{decode()} method returns a @ref{41e7,,ParseResult}
instance.


Added in version 3.2.

@end deffn

@geindex SplitResultBytes (κλάση σε urllib.parse)
@anchor{library/urllib parse urllib parse SplitResultBytes}@anchor{41e4}
@deffn {Κλάση} urllib.parse.SplitResultBytes (scheme, netloc, path, query, fragment)

Concrete class for @ref{2a3,,urlsplit()} results containing @ref{1c7,,bytes}
data. The @code{decode()} method returns a @ref{41e3,,SplitResult}
instance.


Added in version 3.2.

@end deffn

@node URL Quoting,,Structured Parse Results,urllib parse — Parse URLs into components
@anchor{library/urllib parse url-quoting}@anchor{41f0}
@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() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse quote}@anchor{f62}
@deffn {Συνάρτηση} 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{1df,,str} or a @ref{1c7,,bytes} object.


Άλλαξε στην έκδοση 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{ca7,,str.encode()} method.
`encoding' defaults to @code{'utf-8'}.
`errors' defaults to @code{'strict'}, meaning unsupported characters raise a
@ref{a67,,UnicodeEncodeError}.
`encoding' and `errors' must not be supplied if `string' is a
@ref{1c7,,bytes}, or a @ref{291,,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() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse quote_plus}@anchor{15ed}
@deffn {Συνάρτηση} urllib.parse.quote_plus (string, safe='@w{'}, encoding=None, errors=None)

Like @ref{f62,,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() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse quote_from_bytes}@anchor{1d4f}
@deffn {Συνάρτηση} urllib.parse.quote_from_bytes (bytes, safe='/')

Like @ref{f62,,quote()}, but accepts a @ref{1c7,,bytes} object rather than a
@ref{1df,,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() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse unquote}@anchor{1cfa}
@deffn {Συνάρτηση} 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{ca8,,bytes.decode()} method.

`string' may be either a @ref{1df,,str} or a @ref{1c7,,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/'}.


Άλλαξε στην έκδοση 3.9: `string' parameter supports bytes and str objects (previously only str).

@end deffn

@geindex unquote_plus() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse unquote_plus}@anchor{41f1}
@deffn {Συνάρτηση} urllib.parse.unquote_plus (string, encoding='utf-8', errors='replace')

Like @ref{1cfa,,unquote()}, but also replace plus signs with spaces, as required
for unquoting HTML form values.

`string' must be a @ref{1df,,str}.

Example: @code{unquote_plus('/El+Ni%C3%B1o/')} yields @code{'/El Niño/'}.
@end deffn

@geindex unquote_to_bytes() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse unquote_to_bytes}@anchor{1cfb}
@deffn {Συνάρτηση} urllib.parse.unquote_to_bytes (string)

Replace @code{%@var{xx}} escapes with their single-octet equivalent, and return a
@ref{1c7,,bytes} object.

`string' may be either a @ref{1df,,str} or a @ref{1c7,,bytes} object.

If it is a @ref{1df,,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() (στη μονάδα urllib.parse)
@anchor{library/urllib parse urllib parse urlencode}@anchor{1246}
@deffn {Συνάρτηση} 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{1df,,str} or @ref{1c7,,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{57f,,urlopen()} function, then
it should be encoded to bytes, otherwise it would result in a
@ref{291,,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{15ed,,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{f62,,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{1df,,str}).

To reverse this encoding process, @ref{589,,parse_qs()} and @ref{588,,parse_qsl()} are
provided in this module to parse query strings into Python data structures.

Refer to @ref{41d4,,urllib examples} to find out how the
@ref{1246,,urllib.parse.urlencode()} method can be used for generating the query
string of a URL or data for a POST request.


Άλλαξε στην έκδοση 3.2: `query' supports bytes and string objects.



Άλλαξε στην έκδοση 3.5: Added the `quote_via' parameter.



Αποσύρθηκε στην έκδοση 3.14: Accepting objects with false values (like @code{0} and @code{[]}) except empty
strings and byte-like objects and @code{None} is now deprecated.

@end deffn


@subsubheading Δείτε επίσης



@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


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node urllib error — Exception classes raised by urllib request,urllib robotparser — Parser for robots txt,urllib parse — Parse URLs into components,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/urllib error doc}@anchor{41f2}@anchor{library/urllib error module-urllib error}@anchor{112}@anchor{library/urllib error translation-repo}@anchor{41f3}@anchor{library/urllib error urllib-error-exception-classes-raised-by-urllib-request}@anchor{41f4}
@subsection @code{urllib.error} — Exception classes raised by urllib.request


@geindex module; urllib.error

`Source code:' Lib/urllib/error.py@footnote{https://github.com/python/cpython/tree/main/Lib/urllib/error.py}


__________________________________________________________________


The @code{urllib.error} module defines the exception classes for exceptions
raised by @ref{114,,urllib.request}.  The base exception class is @ref{53a,,URLError}.

The following exceptions are raised by @code{urllib.error} as appropriate:

@geindex URLError
@anchor{library/urllib error urllib error URLError}@anchor{53a}
@deffn {Εξαίρεση} urllib.error.URLError

The handlers raise this exception (or derived exceptions) when they run into
a problem.  It is a subclass of @ref{53c,,OSError}.

@geindex reason (ιδιότητα της urllib.error.URLError)
@anchor{library/urllib error urllib error URLError reason}@anchor{41f5}
@deffn {Ιδιότητα} reason

The reason for this error.  It can be a message string or another
exception instance.
@end deffn


Άλλαξε στην έκδοση 3.3: @code{URLError} used to be a subtype of @ref{13fb,,IOError}, which is now an
alias of @ref{53c,,OSError}.

@end deffn

@geindex HTTPError
@anchor{library/urllib error urllib error HTTPError}@anchor{1387}
@deffn {Εξαίρεση} urllib.error.HTTPError (url, code, msg, hdrs, fp)

Though being an exception (a subclass of @ref{53a,,URLError}), an
@code{HTTPError} can also function as a non-exceptional file-like return
value (the same thing that @ref{57f,,urlopen()} returns).  This
is useful when handling exotic HTTP errors, such as requests for
authentication.

@geindex url (ιδιότητα της urllib.error.HTTPError)
@anchor{library/urllib error urllib error HTTPError url}@anchor{41f6}
@deffn {Ιδιότητα} url

Contains the request URL.
An alias for `filename' attribute.
@end deffn

@geindex code (ιδιότητα της urllib.error.HTTPError)
@anchor{library/urllib error urllib error HTTPError code}@anchor{41f7}
@deffn {Ιδιότητα} code

An HTTP status code as defined in 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html}.  This numeric value corresponds
to a value found in the dictionary of codes as found in
@ref{41f8,,http.server.BaseHTTPRequestHandler.responses}.
@end deffn

@geindex reason (ιδιότητα της urllib.error.HTTPError)
@anchor{library/urllib error urllib error HTTPError reason}@anchor{41f9}
@deffn {Ιδιότητα} reason

This is usually a string explaining the reason for this error.
An alias for `msg' attribute.
@end deffn

@geindex headers (ιδιότητα της urllib.error.HTTPError)
@anchor{library/urllib error urllib error HTTPError headers}@anchor{1388}
@deffn {Ιδιότητα} headers

The HTTP response headers for the HTTP request that caused the
@code{HTTPError}.
An alias for `hdrs' attribute.


Added in version 3.4.

@end deffn

@geindex fp (ιδιότητα της urllib.error.HTTPError)
@anchor{library/urllib error urllib error HTTPError fp}@anchor{41fa}
@deffn {Ιδιότητα} 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{41d6}
@deffn {Εξαίρεση} urllib.error.ContentTooShortError (msg, content)

This exception is raised when the @ref{580,,urlretrieve()}
function detects that
the amount of the downloaded data is less than the expected amount (given by
the `Content-Length' header).

@geindex content (ιδιότητα της urllib.error.ContentTooShortError)
@anchor{library/urllib error urllib error ContentTooShortError content}@anchor{41fb}
@deffn {Ιδιότητα} content

The downloaded (and supposedly truncated) data.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node urllib robotparser — Parser for robots txt,http — HTTP modules,urllib error — Exception classes raised by urllib request,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/urllib robotparser doc}@anchor{41fc}@anchor{library/urllib robotparser module-urllib robotparser}@anchor{116}@anchor{library/urllib robotparser translation-repo}@anchor{41fd}@anchor{library/urllib robotparser urllib-robotparser-parser-for-robots-txt}@anchor{41fe}
@subsection @code{urllib.robotparser} —  Parser for robots.txt


@geindex module; urllib.robotparser

`Source code:' Lib/urllib/robotparser.py@footnote{https://github.com/python/cpython/tree/main/Lib/urllib/robotparser.py}

@geindex WWW
@geindex World Wide Web
@geindex URL
@geindex robots.txt


__________________________________________________________________


This module provides a single class, @ref{10ba,,RobotFileParser}, which answers
questions about whether or not a particular user agent can fetch a URL on the
website that published the @code{robots.txt} file.  For more details on the
structure of @code{robots.txt} files, see 
@geindex RFC; RFC 9309
RFC 9309@footnote{https://datatracker.ietf.org/doc/html/rfc9309.html}.

@geindex RobotFileParser (κλάση σε urllib.robotparser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser}@anchor{10ba}
@deffn {Κλάση} urllib.robotparser.RobotFileParser (url='@w{'})

This class provides methods to read, parse and answer questions about the
@code{robots.txt} file at `url'.

@geindex set_url() (μέθοδος της urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser set_url}@anchor{41ff}
@deffn {Μέθοδος} set_url (url)

Sets the URL referring to a @code{robots.txt} file.
@end deffn

@geindex read() (μέθοδος της urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser read}@anchor{1af2}
@deffn {Μέθοδος} read ()

Reads the @code{robots.txt} URL and feeds it to the parser.
@end deffn

@geindex parse() (μέθοδος της urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser parse}@anchor{2070}
@deffn {Μέθοδος} parse (lines)

Parses the lines argument.
@end deffn

@geindex can_fetch() (μέθοδος της urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser can_fetch}@anchor{4200}
@deffn {Μέθοδος} can_fetch (useragent, url)

Returns @code{True} if the `useragent' is allowed to fetch the `url'
according to the rules contained in the parsed @code{robots.txt}
file.
@end deffn

@geindex mtime() (μέθοδος της urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser mtime}@anchor{4201}
@deffn {Μέθοδος} mtime ()

Returns the time the @code{robots.txt} file was last fetched.  This is
useful for long-running web spiders that need to check for new
@code{robots.txt} files periodically.
@end deffn

@geindex modified() (μέθοδος της urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser modified}@anchor{4202}
@deffn {Μέθοδος} modified ()

Sets the time the @code{robots.txt} file was last fetched to the current
time.
@end deffn

@geindex crawl_delay() (μέθοδος της urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser crawl_delay}@anchor{4203}
@deffn {Μέθοδος} crawl_delay (useragent)

Returns the value of the @code{Crawl-delay} parameter from @code{robots.txt}
for the `useragent' in question.  If there is no such parameter or it
doesn’t apply to the `useragent' specified or the @code{robots.txt} entry
for this parameter has invalid syntax, return @code{None}.


Added in version 3.6.

@end deffn

@geindex request_rate() (μέθοδος της urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser request_rate}@anchor{4204}
@deffn {Μέθοδος} request_rate (useragent)

Returns the contents of the @code{Request-rate} parameter from
@code{robots.txt} as a @ref{a3d,,named tuple} @code{RequestRate(requests, seconds)}.
If there is no such parameter or it doesn’t apply to the `useragent'
specified or the @code{robots.txt} entry for this parameter has invalid
syntax, return @code{None}.


Added in version 3.6.

@end deffn

@geindex site_maps() (μέθοδος της urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser site_maps}@anchor{2010}
@deffn {Μέθοδος} site_maps ()

Returns the contents of the @code{Sitemap} parameter from
@code{robots.txt} in the form of a @ref{4d9,,list()}. If there is no such
parameter or the @code{robots.txt} entry for this parameter has
invalid syntax, return @code{None}.


Added in version 3.8.

@end deffn
@end deffn

The following example demonstrates basic use of the @ref{10ba,,RobotFileParser}
class:

@example
>>> import urllib.robotparser
>>> rp = urllib.robotparser.RobotFileParser()
>>> rp.set_url("http://www.pythontest.net/robots.txt")
>>> rp.read()
>>> rrate = rp.request_rate("*")
>>> rrate.requests
1
>>> rrate.seconds
1
>>> rp.crawl_delay("*")
6
>>> rp.can_fetch("*", "http://www.pythontest.net/")
True
>>> rp.can_fetch("*", "http://www.pythontest.net/no-robots-here/")
False
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node http — HTTP modules,http client — HTTP protocol client,urllib robotparser — Parser for robots txt,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/http doc}@anchor{4205}@anchor{library/http http-http-modules}@anchor{4206}@anchor{library/http module-http}@anchor{71}@anchor{library/http translation-repo}@anchor{4207}
@subsection @code{http} — HTTP modules


@geindex module; http

`Source code:' Lib/http/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/http/__init__.py}

@geindex HTTP;protocol
@geindex HTTP;http (standard module)


__________________________________________________________________


@code{http} is a package that collects several modules for working with the
HyperText Transfer Protocol:


@itemize *

@item 
@ref{72,,http.client} is a low-level HTTP protocol client; for high-level URL
opening use @ref{114,,urllib.request}

@item 
@ref{75,,http.server} contains basic HTTP server classes based on @ref{d5,,socketserver}

@item 
@ref{74,,http.cookies} has utilities for implementing state management with cookies

@item 
@ref{73,,http.cookiejar} provides persistence of cookies
@end itemize

The @code{http} module also defines the following enums that help you work with http related code:

@geindex HTTPStatus (κλάση σε http)
@anchor{library/http http HTTPStatus}@anchor{cd0}
@deffn {Κλάση} http.HTTPStatus


Added in version 3.5.


A subclass of @ref{109d,,enum.IntEnum} that defines a set of HTTP status codes,
reason phrases and long descriptions written in English.

Usage:

@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
* HTTP status codes:: 
* HTTP status category:: 
* HTTP methods:: 

@end menu

@node HTTP status codes,HTTP status category,,http — HTTP modules
@anchor{library/http http-status-codes}@anchor{4208}@anchor{library/http id1}@anchor{4209}
@subsubsection HTTP status codes


Supported,
IANA-registered status codes@footnote{https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml}
available in @ref{cd0,,http.HTTPStatus} are:


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Code

@tab

Enum Name

@tab

Details

@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 (Experimental)

@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 (Experimental)

@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 (Experimental)

@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 (Experimental)

@item

@code{511}

@tab

@code{NETWORK_AUTHENTICATION_REQUIRED}

@tab

Additional HTTP Status Codes 
@geindex RFC; RFC 6585
RFC 6585@footnote{https://datatracker.ietf.org/doc/html/rfc6585.html}, Section 6

@end multitable


In order to preserve backwards compatibility, enum values are also present
in the @ref{72,,http.client} module in the form of constants. The enum name is
equal to the constant name (i.e. @code{http.HTTPStatus.OK} is also available as
@code{http.client.OK}).


Άλλαξε στην έκδοση 3.7: Added @code{421 MISDIRECTED_REQUEST} status code.



Added in version 3.8: Added @code{451 UNAVAILABLE_FOR_LEGAL_REASONS} status code.



Added in version 3.9: Added @code{103 EARLY_HINTS}, @code{418 IM_A_TEAPOT} and @code{425 TOO_EARLY} status codes.



Άλλαξε στην έκδοση 3.13: Implemented RFC9110 naming for status constants. Old constant names are preserved for
backwards compatibility: @code{413 REQUEST_ENTITY_TOO_LARGE}, @code{414 REQUEST_URI_TOO_LONG},
@code{416 REQUESTED_RANGE_NOT_SATISFIABLE} and @code{422 UNPROCESSABLE_ENTITY}.


@node HTTP status category,HTTP methods,HTTP status codes,http — HTTP modules
@anchor{library/http http-status-category}@anchor{420a}
@subsubsection HTTP status category



Added in 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

Details

@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

Usage:

@example
>>> from http import HTTPStatus
>>> HTTPStatus.OK.is_success
True
>>> HTTPStatus.OK.is_client_error
False
@end example
@end quotation

@geindex HTTPMethod (κλάση σε http)
@anchor{library/http http HTTPMethod}@anchor{420b}
@deffn {Κλάση} http.HTTPMethod


Added in version 3.11.


A subclass of @ref{a0d,,enum.StrEnum} that defines a set of HTTP methods and descriptions written in English.

Usage:

@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{420c}@anchor{library/http id2}@anchor{420d}
@subsubsection HTTP methods


Supported,
IANA-registered methods@footnote{https://www.iana.org/assignments/http-methods/http-methods.xhtml}
available in @ref{420b,,http.HTTPMethod} are:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Method

@tab

Enum Name

@tab

Details

@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


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node http client — HTTP protocol client,ftplib — FTP protocol client,http — HTTP modules,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/http client doc}@anchor{420e}@anchor{library/http client http-client-http-protocol-client}@anchor{420f}@anchor{library/http client module-http client}@anchor{72}@anchor{library/http client translation-repo}@anchor{4210}
@subsection @code{http.client} — HTTP protocol client


@geindex module; http.client

`Source code:' Lib/http/client.py@footnote{https://github.com/python/cpython/tree/main/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{114,,urllib.request} uses it to handle URLs that use HTTP and HTTPS.


@subsubheading Δείτε επίσης


The Requests package@footnote{https://requests.readthedocs.io/en/latest/}
is recommended for a higher-level HTTP client interface.


@cartouche
@quotation Σημείωση 
HTTPS support is only available if Python was compiled with SSL support
(through the @ref{d8,,ssl} module).
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

The module provides the following classes:

@geindex HTTPConnection (κλάση σε http.client)
@anchor{library/http client http client HTTPConnection}@anchor{223}
@deffn {Κλάση} http.client.HTTPConnection (host, port=None[, timeout], source_address=None, blocksize=8192, max_response_headers=None)

An @code{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. The optional `max_response_headers'
parameter sets the maximum number of allowed response headers to help
prevent denial-of-service attacks, otherwise the default value (100) is used.

For example, the following calls all create instances that connect to the server
at the same host and 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


Άλλαξε στην έκδοση 3.2: `source_address' was added.



Άλλαξε στην έκδοση 3.4: The  `strict' parameter was removed. HTTP 0.9-style «Simple Responses» are
no longer supported.



Άλλαξε στην έκδοση 3.7: `blocksize' parameter was added.



Άλλαξε στην έκδοση 3.15: `max_response_headers' parameter was added.

@end deffn

@geindex HTTPSConnection (κλάση σε http.client)
@anchor{library/http client http client HTTPSConnection}@anchor{224}
@deffn {Κλάση} http.client.HTTPSConnection (host, port=None, *[, timeout], source_address=None, context=None, blocksize=8192, max_response_headers=None)

A subclass of @ref{223,,HTTPConnection} that uses SSL for communication with
secure servers.  Default port is @code{443}.  If `context' is specified, it
must be a @ref{336,,ssl.SSLContext} instance describing the various SSL
options.

Please read @ref{3ad9,,Security considerations} for more information on best practices.


Άλλαξε στην έκδοση 3.2: `source_address', `context' and `check_hostname' were added.



Άλλαξε στην έκδοση 3.2: This class now supports HTTPS virtual hosts if possible (that is,
if @ref{3c20,,ssl.HAS_SNI} is true).



Άλλαξε στην έκδοση 3.4: The `strict' parameter was removed. HTTP 0.9-style «Simple Responses» are
no longer supported.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.8: This class now enables TLS 1.3
@ref{df5,,ssl.SSLContext.post_handshake_auth} for the default `context' or
when `cert_file' is passed with a custom `context'.



Άλλαξε στην έκδοση 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{1215,,set_alpn_protocols()}.



Άλλαξε στην έκδοση 3.12: The deprecated `key_file', `cert_file' and `check_hostname' parameters
have been removed.



Άλλαξε στην έκδοση 3.15: `max_response_headers' parameter was added.

@end deffn

@geindex HTTPResponse (κλάση σε http.client)
@anchor{library/http client http client HTTPResponse}@anchor{147a}
@deffn {Κλάση} http.client.HTTPResponse (sock, debuglevel=0, method=None, url=None)

Class whose instances are returned upon successful connection.  Not
instantiated directly by user.


Άλλαξε στην έκδοση 3.4: The `strict' parameter was removed. HTTP 0.9 style «Simple Responses» are
no longer supported.

@end deffn

This module provides the following function:

@geindex parse_headers() (στη μονάδα http.client)
@anchor{library/http client http client parse_headers}@anchor{2015}
@deffn {Συνάρτηση} 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{a83,,BufferedIOBase} reader
(i.e. not text) and must provide a valid 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} style header.

This function returns an instance of @ref{4211,,http.client.HTTPMessage}
that holds the header fields, but no payload
(the same as @ref{4212,,HTTPResponse.msg}
and @ref{4213,,http.server.BaseHTTPRequestHandler.headers}).
After returning, the file pointer `fp' is ready to read the HTTP body.

@cartouche
@quotation Σημείωση 
@ref{2015,,parse_headers()} does not parse the start-line of a HTTP message;
it only parses the @code{Name: value} lines. The file has to be ready to
read these field lines, so the first line should already be consumed
before calling the function.
@end quotation
@end cartouche
@end deffn

The following exceptions are raised as appropriate:

@geindex HTTPException
@anchor{library/http client http client HTTPException}@anchor{4214}
@deffn {Εξαίρεση} http.client.HTTPException

The base class of the other exceptions in this module.  It is a subclass of
@ref{d9e,,Exception}.
@end deffn

@geindex NotConnected
@anchor{library/http client http client NotConnected}@anchor{4215}
@deffn {Εξαίρεση} http.client.NotConnected

A subclass of @ref{4214,,HTTPException}.
@end deffn

@geindex InvalidURL
@anchor{library/http client http client InvalidURL}@anchor{4216}
@deffn {Εξαίρεση} http.client.InvalidURL

A subclass of @ref{4214,,HTTPException}, raised if a port is given and is either
non-numeric or empty.
@end deffn

@geindex UnknownProtocol
@anchor{library/http client http client UnknownProtocol}@anchor{4217}
@deffn {Εξαίρεση} http.client.UnknownProtocol

A subclass of @ref{4214,,HTTPException}.
@end deffn

@geindex UnknownTransferEncoding
@anchor{library/http client http client UnknownTransferEncoding}@anchor{4218}
@deffn {Εξαίρεση} http.client.UnknownTransferEncoding

A subclass of @ref{4214,,HTTPException}.
@end deffn

@geindex UnimplementedFileMode
@anchor{library/http client http client UnimplementedFileMode}@anchor{4219}
@deffn {Εξαίρεση} http.client.UnimplementedFileMode

A subclass of @ref{4214,,HTTPException}.
@end deffn

@geindex IncompleteRead
@anchor{library/http client http client IncompleteRead}@anchor{421a}
@deffn {Εξαίρεση} http.client.IncompleteRead

A subclass of @ref{4214,,HTTPException}.
@end deffn

@geindex ImproperConnectionState
@anchor{library/http client http client ImproperConnectionState}@anchor{421b}
@deffn {Εξαίρεση} http.client.ImproperConnectionState

A subclass of @ref{4214,,HTTPException}.
@end deffn

@geindex CannotSendRequest
@anchor{library/http client http client CannotSendRequest}@anchor{421c}
@deffn {Εξαίρεση} http.client.CannotSendRequest

A subclass of @ref{421b,,ImproperConnectionState}.
@end deffn

@geindex CannotSendHeader
@anchor{library/http client http client CannotSendHeader}@anchor{421d}
@deffn {Εξαίρεση} http.client.CannotSendHeader

A subclass of @ref{421b,,ImproperConnectionState}.
@end deffn

@geindex ResponseNotReady
@anchor{library/http client http client ResponseNotReady}@anchor{421e}
@deffn {Εξαίρεση} http.client.ResponseNotReady

A subclass of @ref{421b,,ImproperConnectionState}.
@end deffn

@geindex BadStatusLine
@anchor{library/http client http client BadStatusLine}@anchor{421f}
@deffn {Εξαίρεση} http.client.BadStatusLine

A subclass of @ref{4214,,HTTPException}.  Raised if a server responds with a HTTP
status code that we don’t understand.
@end deffn

@geindex LineTooLong
@anchor{library/http client http client LineTooLong}@anchor{4220}
@deffn {Εξαίρεση} http.client.LineTooLong

A subclass of @ref{4214,,HTTPException}.  Raised if an excessively long line
is received in the HTTP protocol from the server.
@end deffn

@geindex RemoteDisconnected
@anchor{library/http client http client RemoteDisconnected}@anchor{11be}
@deffn {Εξαίρεση} http.client.RemoteDisconnected

A subclass of @ref{1407,,ConnectionResetError} and @ref{421f,,BadStatusLine}.  Raised
by @ref{11bd,,HTTPConnection.getresponse()} when the attempt to read the response
results in no data read from the connection, indicating that the remote end
has closed the connection.


Added in version 3.5: Previously, @ref{421f,,BadStatusLine}@code{('@w{'})} was raised.

@end deffn

The constants defined in this module are:

@geindex HTTP_PORT (στη μονάδα http.client)
@anchor{library/http client http client HTTP_PORT}@anchor{4221}
@deffn {Δεδομένα} http.client.HTTP_PORT

The default port for the HTTP protocol (always @code{80}).
@end deffn

@geindex HTTPS_PORT (στη μονάδα http.client)
@anchor{library/http client http client HTTPS_PORT}@anchor{4222}
@deffn {Δεδομένα} http.client.HTTPS_PORT

The default port for the HTTPS protocol (always @code{443}).
@end deffn

@geindex responses (στη μονάδα http.client)
@anchor{library/http client http client responses}@anchor{4223}
@deffn {Δεδομένα} http.client.responses

This dictionary maps the HTTP 1.1 status codes to the W3C names.

Example: @code{http.client.responses[http.client.NOT_FOUND]} is @code{'Not Found'}.
@end deffn

See @ref{4208,,HTTP status codes} for a list of HTTP status codes that are
available in this module as constants.

@menu
* HTTPConnection Objects:: 
* HTTPResponse Objects:: 
* Examples: Examples<24>. 
* HTTPMessage Objects:: 

@end menu

@node HTTPConnection Objects,HTTPResponse Objects,,http client — HTTP protocol client
@anchor{library/http client httpconnection-objects}@anchor{4224}@anchor{library/http client id1}@anchor{4225}
@subsubsection HTTPConnection Objects


@ref{223,,HTTPConnection} instances have the following methods:

@geindex request() (μέθοδος της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection request}@anchor{106a}
@deffn {Μέθοδος} 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).

If `body' is specified, the specified data is sent after the headers are
finished.  It may be a @ref{1df,,str}, a @ref{436,,bytes-like object}, an
open @ref{156c,,file object}, or an iterable of @ref{1c7,,bytes}.  If `body'
is a string, it is encoded as ISO-8859-1, the default for HTTP.  If it
is a bytes-like object, the bytes are sent as is.  If it is a file
object, the contents of the file is sent; this file object should
support at least the @code{read()} method.  If the file object is an
instance of @ref{a84,,io.TextIOBase}, the data returned by the @code{read()}
method will be encoded as ISO-8859-1, otherwise the data returned by
@code{read()} is sent as is.  If `body' is an iterable, the elements of the
iterable are sent as is until the iterable is exhausted.

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).

If `headers' contains neither Content-Length nor Transfer-Encoding,
but there is a request body, one of those
header fields will be added automatically.  If
`body' is @code{None}, the Content-Length header is set to @code{0} for
methods that expect a body (@code{PUT}, @code{POST}, and @code{PATCH}).  If
`body' is a string or a bytes-like object that is not also a
@ref{156c,,file}, the Content-Length header is
set to its length.  Any other type of `body' (files
and iterables in general) will be chunk-encoded, and the
Transfer-Encoding header will automatically be set instead of
Content-Length.

The `encode_chunked' argument is only relevant if Transfer-Encoding is
specified in `headers'.  If `encode_chunked' is @code{False}, the
HTTPConnection object assumes that all encoding is handled by the
calling code.  If it is @code{True}, the body will be chunk-encoded.

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 Σημείωση 
Chunked transfer encoding has been added to the HTTP protocol
version 1.1.  Unless the HTTP server is known to handle HTTP 1.1,
the caller must either specify the Content-Length, or must pass a
@ref{1df,,str} or bytes-like object that is not also a file as the
body representation.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Note that you must have read the whole response or call @ref{4226,,close()}
if @ref{11bd,,getresponse()} raised an non-@ref{11bf,,ConnectionError} exception
before you can send a new request to the server.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.2: `body' can now be an iterable.



Άλλαξε στην έκδοση 3.6: If neither Content-Length nor Transfer-Encoding are set in
`headers', file and iterable `body' objects are now chunk-encoded.
The `encode_chunked' argument was added.
No attempt is made to determine the Content-Length for file
objects.

@end deffn

@geindex getresponse() (μέθοδος της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection getresponse}@anchor{11bd}
@deffn {Μέθοδος} HTTPConnection.getresponse ()

Should be called after a request is sent to get the response from the server.
Returns an @ref{147a,,HTTPResponse} instance.


Άλλαξε στην έκδοση 3.5: If a @ref{11bf,,ConnectionError} or subclass is raised, the
@ref{223,,HTTPConnection} object will be ready to reconnect when
a new request is sent.

Note that this does not apply to @ref{53c,,OSError}s raised by the underlying
socket. Instead the caller is responsible to call @ref{4226,,close()} on the
existing connection.

@end deffn

@geindex set_debuglevel() (μέθοδος της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection set_debuglevel}@anchor{4227}
@deffn {Μέθοδος} HTTPConnection.set_debuglevel (level)

Set the debugging level.  The default debug level is @code{0}, meaning no
debugging output is printed.  Any value greater than @code{0} will cause all
currently defined debug output to be printed to stdout.  The @code{debuglevel}
is passed to any new @ref{147a,,HTTPResponse} objects that are created.


Added in version 3.1.

@end deffn

@geindex set_tunnel() (μέθοδος της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection set_tunnel}@anchor{15cf}
@deffn {Μέθοδος} HTTPConnection.set_tunnel (host, port=None, headers=None)

Set the host and the port for HTTP Connect Tunnelling. This allows running
the connection through a proxy server.

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.

For example, to tunnel through a HTTPS proxy server running locally on port
8080, we would pass the address of the proxy to the @ref{224,,HTTPSConnection}
constructor, and the address of the host that we eventually want to reach to
the @code{set_tunnel()} method:

@example
>>> import http.client
>>> conn = http.client.HTTPSConnection("localhost", 8080)
>>> conn.set_tunnel("www.python.org")
>>> conn.request("HEAD","/index.html")
@end example


Added in version 3.2.



Άλλαξε στην έκδοση 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() (μέθοδος της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection get_proxy_response_headers}@anchor{1c79}
@deffn {Μέθοδος} 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}.


Added in version 3.12.

@end deffn

@geindex connect() (μέθοδος της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection connect}@anchor{4228}
@deffn {Μέθοδος} HTTPConnection.connect ()

Connect to the server specified when the object was created.  By default,
this is called automatically when making a request if the client does not
already have a connection.

Raises an @ref{1e65,,auditing event} @code{http.client.connect} with arguments @code{self}, @code{host}, @code{port}.
@end deffn

@geindex close() (μέθοδος της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection close}@anchor{4226}
@deffn {Μέθοδος} HTTPConnection.close ()

Close the connection to the server.
@end deffn

@geindex blocksize (ιδιότητα της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection blocksize}@anchor{4229}
@deffn {Ιδιότητα} HTTPConnection.blocksize

Buffer size in bytes for sending a file-like message body.


Added in version 3.7.

@end deffn

@geindex max_response_headers (ιδιότητα της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection max_response_headers}@anchor{422a}
@deffn {Ιδιότητα} HTTPConnection.max_response_headers

The maximum number of allowed response headers to help prevent denial-of-service
attacks. By default, the maximum number of allowed headers is set to 100.


Added in version 3.15.

@end deffn

As an alternative to using the @ref{106a,,request()} method described above, you can
also send your request step by step, by using the four functions below.

@geindex putrequest() (μέθοδος της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection putrequest}@anchor{422b}
@deffn {Μέθοδος} HTTPConnection.putrequest (method, url, skip_host=False, skip_accept_encoding=False)

This should be the first call after the connection to the server has been
made. It sends a line to the server consisting of the `method' string,
the `url' string, and the HTTP version (@code{HTTP/1.1}).  To disable automatic
sending of @code{Host:} or @code{Accept-Encoding:} headers (for example to accept
additional content encodings), specify `skip_host' or `skip_accept_encoding'
with non-False values.
@end deffn

@geindex putheader() (μέθοδος της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection putheader}@anchor{422c}
@deffn {Μέθοδος} HTTPConnection.putheader (header, argument[, ...])

Send an 
@geindex RFC; RFC 822
RFC 822@footnote{https://datatracker.ietf.org/doc/html/rfc822.html}-style header to the server.  It sends a line to the server
consisting of the header, a colon and a space, and the first argument.  If more
arguments are given, continuation lines are sent, each consisting of a tab and
an argument.
@end deffn

@geindex endheaders() (μέθοδος της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection endheaders}@anchor{106b}
@deffn {Μέθοδος} HTTPConnection.endheaders (message_body=None, *, encode_chunked=False)

Send a blank line to the server, signalling the end of the headers. The
optional `message_body' argument can be used to pass a message body
associated with the request.

If `encode_chunked' is @code{True}, the result of each iteration of
`message_body' will be chunk-encoded as specified in 
@geindex RFC; RFC 7230
RFC 7230@footnote{https://datatracker.ietf.org/doc/html/rfc7230.html},
Section 3.3.1.  How the data is encoded is dependent on the type of
`message_body'.  If `message_body' implements the @ref{311,,buffer interface} the encoding will result in a single chunk.
If `message_body' is a @ref{28aa,,collections.abc.Iterable}, each iteration
of `message_body' will result in a chunk.  If `message_body' is a
@ref{156c,,file object}, each call to @code{.read()} will result in a chunk.
The method automatically signals the end of the chunk-encoded data
immediately after `message_body'.

@cartouche
@quotation Σημείωση 
Due to the chunked encoding specification, empty chunks
yielded by an iterator body will be ignored by the chunk-encoder.
This is to avoid premature termination of the read of the request by
the target server due to malformed encoding.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.6: Added chunked encoding support and the `encode_chunked' parameter.

@end deffn

@geindex send() (μέθοδος της http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection send}@anchor{422d}
@deffn {Μέθοδος} HTTPConnection.send (data)

Send data to the server.  This should be used directly only after the
@ref{106b,,endheaders()} method has been called and before @ref{11bd,,getresponse()} is
called.

Raises an @ref{1e65,,auditing event} @code{http.client.send} with arguments @code{self}, @code{data}.
@end deffn

@node HTTPResponse Objects,Examples<24>,HTTPConnection Objects,http client — HTTP protocol client
@anchor{library/http client httpresponse-objects}@anchor{422e}@anchor{library/http client id2}@anchor{422f}
@subsubsection HTTPResponse Objects


An @ref{147a,,HTTPResponse} instance wraps the HTTP response from the
server.  It provides access to the request headers and the entity
body.  The response is an iterable object and can be used in a with
statement.


Άλλαξε στην έκδοση 3.5: The @ref{a83,,io.BufferedIOBase} interface is now implemented and
all of its reader operations are supported.


@geindex read() (μέθοδος της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse read}@anchor{1ad0}
@deffn {Μέθοδος} HTTPResponse.read ([amt])

Reads and returns the response body, or up to the next `amt' bytes.
@end deffn

@geindex readinto() (μέθοδος της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse readinto}@anchor{147b}
@deffn {Μέθοδος} HTTPResponse.readinto (b)

Reads up to the next len(b) bytes of the response body into the buffer `b'.
Returns the number of bytes read.


Added in version 3.3.

@end deffn

@geindex getheader() (μέθοδος της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse getheader}@anchor{4230}
@deffn {Μέθοδος} 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() (μέθοδος της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse getheaders}@anchor{4231}
@deffn {Μέθοδος} HTTPResponse.getheaders ()

Return a list of (header, value) tuples.
@end deffn

@geindex fileno() (μέθοδος της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse fileno}@anchor{4232}
@deffn {Μέθοδος} HTTPResponse.fileno ()

Return the @code{fileno} of the underlying socket.
@end deffn

@geindex msg (ιδιότητα της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse msg}@anchor{4212}
@deffn {Ιδιότητα} HTTPResponse.msg

A @ref{4211,,http.client.HTTPMessage} instance containing the response
headers.  @code{http.client.HTTPMessage} is a subclass of
@ref{780,,email.message.Message}.
@end deffn

@geindex version (ιδιότητα της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse version}@anchor{4233}
@deffn {Ιδιότητα} HTTPResponse.version

HTTP protocol version used by server.  10 for HTTP/1.0, 11 for HTTP/1.1.
@end deffn

@geindex url (ιδιότητα της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse url}@anchor{4234}
@deffn {Ιδιότητα} HTTPResponse.url

URL of the resource retrieved, commonly used to determine if a redirect was followed.
@end deffn

@geindex headers (ιδιότητα της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse headers}@anchor{4235}
@deffn {Ιδιότητα} HTTPResponse.headers

Headers of the response in the form of an @ref{216,,email.message.EmailMessage} instance.
@end deffn

@geindex status (ιδιότητα της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse status}@anchor{4236}
@deffn {Ιδιότητα} HTTPResponse.status

Status code returned by server.
@end deffn

@geindex reason (ιδιότητα της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse reason}@anchor{4161}
@deffn {Ιδιότητα} HTTPResponse.reason

Reason phrase returned by server.
@end deffn

@geindex debuglevel (ιδιότητα της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse debuglevel}@anchor{4237}
@deffn {Ιδιότητα} HTTPResponse.debuglevel

A debugging hook.  If @ref{4237,,debuglevel} is greater than zero, messages
will be printed to stdout as the response is read and parsed.
@end deffn

@geindex closed (ιδιότητα της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse closed}@anchor{4238}
@deffn {Ιδιότητα} HTTPResponse.closed

Is @code{True} if the stream is closed.
@end deffn

@geindex geturl() (μέθοδος της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse geturl}@anchor{4239}
@deffn {Μέθοδος} HTTPResponse.geturl ()


Αποσύρθηκε στην έκδοση 3.9: Deprecated in favor of @ref{4234,,url}.

@end deffn

@geindex info() (μέθοδος της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse info}@anchor{423a}
@deffn {Μέθοδος} HTTPResponse.info ()


Αποσύρθηκε στην έκδοση 3.9: Deprecated in favor of @ref{4235,,headers}.

@end deffn

@geindex getcode() (μέθοδος της http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse getcode}@anchor{423b}
@deffn {Μέθοδος} HTTPResponse.getcode ()


Αποσύρθηκε στην έκδοση 3.9: Deprecated in favor of @ref{4236,,status}.

@end deffn

@node Examples<24>,HTTPMessage Objects,HTTPResponse Objects,http client — HTTP protocol client
@anchor{library/http client examples}@anchor{423c}
@subsubsection Examples


Here is an example session that uses the @code{GET} method:

@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

Here is an example session that uses the @code{HEAD} method.  Note that the
@code{HEAD} method never returns any data.

@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{1381,,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 HTTPMessage Objects,,Examples<24>,http client — HTTP protocol client
@anchor{library/http client httpmessage-objects}@anchor{423d}@anchor{library/http client id3}@anchor{423e}
@subsubsection HTTPMessage Objects


@geindex HTTPMessage (κλάση σε http.client)
@anchor{library/http client http client HTTPMessage}@anchor{4211}
@deffn {Κλάση} http.client.HTTPMessage (email.message.Message)
@end deffn

An @ref{4211,,http.client.HTTPMessage} instance holds the headers from an HTTP
response.  It is implemented using the @ref{780,,email.message.Message} class.

@c XXX Define the methods that clients can depend upon between versions.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node ftplib — FTP protocol client,poplib — POP3 protocol client,http client — HTTP protocol client,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/ftplib doc}@anchor{423f}@anchor{library/ftplib ftplib-ftp-protocol-client}@anchor{4240}@anchor{library/ftplib module-ftplib}@anchor{61}@anchor{library/ftplib translation-repo}@anchor{4241}
@subsection @code{ftplib} — FTP protocol client


@geindex module; ftplib

`Source code:' Lib/ftplib.py@footnote{https://github.com/python/cpython/tree/main/Lib/ftplib.py}

@geindex FTP;protocol
@geindex FTP;ftplib (standard module)


__________________________________________________________________


This module defines the class @ref{cca,,FTP} and a few related items. The
@code{FTP} class implements the client side of the FTP protocol.  You can use
this to write Python programs that perform a variety of automated FTP jobs, such
as mirroring other FTP servers.  It is also used by the module
@ref{114,,urllib.request} to handle URLs that use FTP.  For more information on FTP
(File Transfer Protocol), see internet 
@geindex RFC; RFC 959
RFC 959@footnote{https://datatracker.ietf.org/doc/html/rfc959.html}.

The default encoding is UTF-8, following 
@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{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

Here’s a sample session using the @code{ftplib} module:

@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
* Reference: Reference<7>. 

@end menu

@node Reference<7>,,,ftplib — FTP protocol client
@anchor{library/ftplib ftplib-reference}@anchor{4242}@anchor{library/ftplib reference}@anchor{4243}
@subsubsection Reference


@menu
* FTP objects:: 
* FTP_TLS objects:: 
* Module variables:: 

@end menu

@node FTP objects,FTP_TLS objects,,Reference<7>
@anchor{library/ftplib ftp-objects}@anchor{4244}@anchor{library/ftplib id1}@anchor{4245}
@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 (κλάση σε ftplib)
@anchor{library/ftplib ftplib FTP}@anchor{cca}
@deffn {Κλάση} ftplib.FTP (host='@w{'}, user='@w{'}, passwd='@w{'}, acct='@w{'}, timeout=None, source_address=None, *, encoding='utf-8')

Return a new instance of the @code{FTP} class.

@*Παράμετροι: 

@itemize *

@item 
@code{host} (@ref{1df,,str}) – The hostname to connect to.
If given, @code{connect(host)} is implicitly called by the constructor.

@item 
@code{user} (@ref{1df,,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{1df,,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{1df,,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{327,,float}@code{ | }@code{None}) – A timeout in seconds for blocking operations like @ref{4246,,connect()}
(default: the global default timeout setting).

@item 
@code{source_address} (@ref{1ce,,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{1df,,str}) – The encoding for directories and filenames (default: @code{'utf-8'}).
@end itemize


The @code{FTP} class supports the @ref{20a,,with} statement, e.g.:

@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


Άλλαξε στην έκδοση 3.2: Support for the @ref{20a,,with} statement was added.



Άλλαξε στην έκδοση 3.3: `source_address' parameter was added.



Άλλαξε στην έκδοση 3.9: If the `timeout' parameter is set to be zero, it will raise a
@ref{277,,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.

@code{FTP} instances have the following methods:

@geindex set_debuglevel() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP set_debuglevel}@anchor{4247}
@deffn {Μέθοδος} set_debuglevel (level)

Set the instance’s debugging level as an @ref{326,,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() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP connect}@anchor{4246}
@deffn {Μέθοδος} 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 @code{FTP} instance was created.
All other @code{FTP} methods can only be called
after a connection has successfully been made.

@*Παράμετροι: 

@itemize *

@item 
@code{host} (@ref{1df,,str}) – The host to connect to.

@item 
@code{port} (@ref{326,,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{327,,float}@code{ | }@code{None}) – A timeout in seconds for the connection attempt
(default: the global default timeout setting).

@item 
@code{source_address} (@ref{1ce,,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{1e65,,auditing event} @code{ftplib.connect} with arguments @code{self}, @code{host}, @code{port}.


Άλλαξε στην έκδοση 3.3: `source_address' parameter was added.

@end deffn

@geindex getwelcome() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP getwelcome}@anchor{4248}
@deffn {Μέθοδος} 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() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP login}@anchor{4249}
@deffn {Μέθοδος} 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 @code{FTP} instance was created.
Most FTP commands are only allowed after the client has logged in.

@*Παράμετροι: 

@itemize *

@item 
@code{user} (@ref{1df,,str}) – The username to log in with (default: @code{'anonymous'}).

@item 
@code{passwd} (@ref{1df,,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{1df,,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() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP abort}@anchor{424a}
@deffn {Μέθοδος} 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() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP sendcmd}@anchor{424b}
@deffn {Μέθοδος} sendcmd (cmd)

Send a simple command string to the server and return the response string.

Raises an @ref{1e65,,auditing event} @code{ftplib.sendcmd} with arguments @code{self}, @code{cmd}.
@end deffn

@geindex voidcmd() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP voidcmd}@anchor{424c}
@deffn {Μέθοδος} 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{424d,,error_reply} otherwise.

Raises an @ref{1e65,,auditing event} @code{ftplib.sendcmd} with arguments @code{self}, @code{cmd}.
@end deffn

@geindex retrbinary() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP retrbinary}@anchor{424e}
@deffn {Μέθοδος} retrbinary (cmd, callback, blocksize=8192, rest=None)

Retrieve a file in binary transfer mode.

@*Παράμετροι: 

@itemize *

@item 
@code{cmd} (@ref{1df,,str}) – An appropriate @code{RETR} command: @code{"RETR @var{filename}"}.

@item 
@code{callback} (@ref{2fa4,,callable}) – A single parameter callable that is called
for each block of data received,
with its single argument being the data as @ref{1c7,,bytes}.

@item 
@code{blocksize} (@ref{326,,int}) – The maximum chunk size to read on the low-level
@ref{115a,,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{326,,int}) – A @code{REST} command to be sent to the server.
See the documentation for the `rest' parameter of the @ref{424f,,transfercmd()} method.
@end itemize

@end deffn

@geindex retrlines() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP retrlines}@anchor{4250}
@deffn {Μέθοδος} 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{424e,,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{e9c,,sys.stdout}.
@end deffn

@geindex set_pasv() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP set_pasv}@anchor{4251}
@deffn {Μέθοδος} set_pasv (val)

Enable «passive» mode if `val' is true, otherwise disable passive mode.
Passive mode is on by default.
@end deffn

@geindex storbinary() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP storbinary}@anchor{16ae}
@deffn {Μέθοδος} storbinary (cmd, fp, blocksize=8192, callback=None, rest=None)

Store a file in binary transfer mode.

@*Παράμετροι: 

@itemize *

@item 
@code{cmd} (@ref{1df,,str}) – An appropriate @code{STOR} command: @code{"STOR @var{filename}"}.

@item 
@code{fp} (@ref{156c,,file object}) – A file object (opened in binary mode) which is read until EOF,
using its @ref{11d0,,read()} method in blocks of size `blocksize'
to provide the data to be stored.

@item 
@code{blocksize} (@ref{326,,int}) – The read block size.
Defaults to @code{8192}.

@item 
@code{callback} (@ref{2fa4,,callable}) – A single parameter callable that is called
for each block of data sent,
with its single argument being the data as @ref{1c7,,bytes}.

@item 
@code{rest} (@ref{326,,int}) – A @code{REST} command to be sent to the server.
See the documentation for the `rest' parameter of the @ref{424f,,transfercmd()} method.
@end itemize



Άλλαξε στην έκδοση 3.2: The `rest' parameter was added.

@end deffn

@geindex storlines() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP storlines}@anchor{4252}
@deffn {Μέθοδος} storlines (cmd, fp, callback=None)

Store a file in line mode.  `cmd' should be an appropriate
@code{STOR} command (see @ref{16ae,,storbinary()}).  Lines are read until EOF from the
@ref{156c,,file object} `fp' (opened in binary mode) using its @ref{16ce,,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() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP transfercmd}@anchor{424f}
@deffn {Μέθοδος} 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 @code{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{424d,,error_reply} exception
will be raised.  If this happens, simply call @code{transfercmd()} without a
`rest' argument.
@end deffn

@geindex ntransfercmd() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP ntransfercmd}@anchor{4253}
@deffn {Μέθοδος} ntransfercmd (cmd, rest=None)

Like @ref{424f,,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 @code{transfercmd()}.
@end deffn

@geindex mlsd() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP mlsd}@anchor{146f}
@deffn {Μέθοδος} 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.


Added in version 3.3.

@end deffn

@geindex nlst() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP nlst}@anchor{1470}
@deffn {Μέθοδος} nlst (argument[, ...])

Return a list of file names as returned by the @code{NLST} command.  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{NLST} command.

@cartouche
@quotation Σημείωση 
If your server supports the command, @ref{146f,,mlsd()} offers a better API.
@end quotation
@end cartouche
@end deffn

@geindex dir() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP dir}@anchor{1471}
@deffn {Μέθοδος} 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{4250,,retrlines()}; the default prints to
@ref{e9c,,sys.stdout}.  This method returns @code{None}.

@cartouche
@quotation Σημείωση 
If your server supports the command, @ref{146f,,mlsd()} offers a better API.
@end quotation
@end cartouche
@end deffn

@geindex rename() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP rename}@anchor{4254}
@deffn {Μέθοδος} rename (fromname, toname)

Rename file `fromname' on the server to `toname'.
@end deffn

@geindex delete() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP delete}@anchor{4255}
@deffn {Μέθοδος} delete (filename)

Remove the file named `filename' from the server.  If successful, returns the
text of the response, otherwise raises @ref{4256,,error_perm} on permission errors or
@ref{424d,,error_reply} on other errors.
@end deffn

@geindex cwd() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP cwd}@anchor{4257}
@deffn {Μέθοδος} cwd (pathname)

Set the current directory on the server.
@end deffn

@geindex mkd() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP mkd}@anchor{4258}
@deffn {Μέθοδος} mkd (pathname)

Create a new directory on the server.
@end deffn

@geindex pwd() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP pwd}@anchor{4259}
@deffn {Μέθοδος} pwd ()

Return the pathname of the current directory on the server.
@end deffn

@geindex rmd() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP rmd}@anchor{425a}
@deffn {Μέθοδος} rmd (dirname)

Remove the directory named `dirname' on the server.
@end deffn

@geindex size() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP size}@anchor{425b}
@deffn {Μέθοδος} 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() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP quit}@anchor{425c}
@deffn {Μέθοδος} 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{425d,,close()} method which renders the @code{FTP} instance useless for
subsequent calls (see below).
@end deffn

@geindex close() (μέθοδος της ftplib.FTP)
@anchor{library/ftplib ftplib FTP close}@anchor{425d}
@deffn {Μέθοδος} close ()

Close the connection unilaterally.  This should not be applied to an already
closed connection such as after a successful call to @ref{425c,,quit()}.
After this call the @code{FTP} instance should not be used any more (after
a call to @code{close()} or @code{quit()} you cannot reopen the
connection by issuing another @ref{4249,,login()} method).
@end deffn
@end deffn

@node FTP_TLS objects,Module variables,FTP objects,Reference<7>
@anchor{library/ftplib ftp-tls-objects}@anchor{425e}
@subsubsection FTP_TLS objects


@geindex FTP_TLS (κλάση σε ftplib)
@anchor{library/ftplib ftplib FTP_TLS}@anchor{ccb}
@deffn {Κλάση} ftplib.FTP_TLS (host='@w{'}, user='@w{'}, passwd='@w{'}, acct='@w{'}, *, context=None, timeout=None, source_address=None, encoding='utf-8')

An @ref{cca,,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 Σημείωση 
The user must explicitly secure the data connection
by calling the @ref{425f,,prot_p()} method.
@end quotation
@end cartouche

@*Παράμετροι: 

@itemize *

@item 
@code{host} (@ref{1df,,str}) – The hostname to connect to.
If given, @code{connect(host)} is implicitly called by the constructor.

@item 
@code{user} (@ref{1df,,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{1df,,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{1df,,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{336,,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{3ad9,,Security considerations} for best practices.

@item 
@code{timeout} (@ref{327,,float}@code{ | }@code{None}) – A timeout in seconds for blocking operations like @ref{4246,,connect()}
(default: the global default timeout setting).

@item 
@code{source_address} (@ref{1ce,,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{1df,,str}) – The encoding for directories and filenames (default: @code{'utf-8'}).
@end itemize



Added in version 3.2.



Άλλαξε στην έκδοση 3.3: Added the `source_address' parameter.



Άλλαξε στην έκδοση 3.4: The class now supports hostname check with
@ref{3c0e,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{3c20,,ssl.HAS_SNI}).



Άλλαξε στην έκδοση 3.9: If the `timeout' parameter is set to be zero, it will raise a
@ref{277,,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}.



Άλλαξε στην έκδοση 3.12: The deprecated `keyfile' and `certfile' parameters have been removed.


Here’s a sample session using the @code{FTP_TLS} class:

@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{cca,,FTP},
defining these additional methods and attributes:

@geindex auth() (μέθοδος της ftplib.FTP_TLS)
@anchor{library/ftplib ftplib FTP_TLS auth}@anchor{4260}
@deffn {Μέθοδος} auth ()

Set up a secure control connection by using TLS.


Άλλαξε στην έκδοση 3.4: The method now supports hostname check with
@ref{3c0e,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{3c20,,ssl.HAS_SNI}).

@end deffn

@geindex ccc() (μέθοδος της ftplib.FTP_TLS)
@anchor{library/ftplib ftplib FTP_TLS ccc}@anchor{146e}
@deffn {Μέθοδος} 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.


Added in version 3.3.

@end deffn

@geindex prot_p() (μέθοδος της ftplib.FTP_TLS)
@anchor{library/ftplib ftplib FTP_TLS prot_p}@anchor{425f}
@deffn {Μέθοδος} prot_p ()

Set up secure data connection by using TLS.
@end deffn

@geindex prot_c() (μέθοδος της ftplib.FTP_TLS)
@anchor{library/ftplib ftplib FTP_TLS prot_c}@anchor{4261}
@deffn {Μέθοδος} prot_c ()

Set up clear text data connection.
@end deffn
@end deffn

@node Module variables,,FTP_TLS objects,Reference<7>
@anchor{library/ftplib module-variables}@anchor{4262}
@subsubsection Module variables


@geindex error_reply
@anchor{library/ftplib ftplib error_reply}@anchor{424d}
@deffn {Εξαίρεση} ftplib.error_reply

Exception raised when an unexpected reply is received from the server.
@end deffn

@geindex error_temp
@anchor{library/ftplib ftplib error_temp}@anchor{4263}
@deffn {Εξαίρεση} ftplib.error_temp

Exception raised when an error code signifying a temporary error (response
codes in the range 400–499) is received.
@end deffn

@geindex error_perm
@anchor{library/ftplib ftplib error_perm}@anchor{4256}
@deffn {Εξαίρεση} ftplib.error_perm

Exception raised when an error code signifying a permanent error (response
codes in the range 500–599) is received.
@end deffn

@geindex error_proto
@anchor{library/ftplib ftplib error_proto}@anchor{4264}
@deffn {Εξαίρεση} ftplib.error_proto

Exception raised when a reply is received from the server that does not fit
the response specifications of the File Transfer Protocol, i.e. begin with a
digit in the range 1–5.
@end deffn

@geindex all_errors (στη μονάδα ftplib)
@anchor{library/ftplib ftplib all_errors}@anchor{4265}
@deffn {Δεδομένα} ftplib.all_errors

The set of all exceptions (as a tuple) that methods of @ref{cca,,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{53c,,OSError} and @ref{167e,,EOFError}.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{9f,,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


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node poplib — POP3 protocol client,imaplib — IMAP4 protocol client,ftplib — FTP protocol client,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/poplib doc}@anchor{4266}@anchor{library/poplib module-poplib}@anchor{b1}@anchor{library/poplib poplib-pop3-protocol-client}@anchor{4267}@anchor{library/poplib translation-repo}@anchor{4268}
@subsection @code{poplib} — POP3 protocol client


@geindex module; poplib

`Source code:' Lib/poplib.py@footnote{https://github.com/python/cpython/tree/main/Lib/poplib.py}

@geindex POP3;protocol


__________________________________________________________________


This module defines a class, @ref{cf0,,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
@code{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 @code{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{cf1,,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{31a,,imaplib.IMAP4} class, as IMAP servers tend to be better implemented.

@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

The @code{poplib} module provides two classes:

@geindex POP3 (κλάση σε poplib)
@anchor{library/poplib poplib POP3}@anchor{cf0}
@deffn {Κλάση} 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{1e65,,auditing event} @code{poplib.connect} with arguments @code{self}, @code{host}, @code{port}.


All commands will raise an @ref{1e65,,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.



Άλλαξε στην έκδοση 3.9: If the `timeout' parameter is set to be zero, it will raise a
@ref{277,,ValueError} to prevent the creation of a non-blocking socket.

@end deffn

@geindex POP3_SSL (κλάση σε poplib)
@anchor{library/poplib poplib POP3_SSL}@anchor{cf1}
@deffn {Κλάση} poplib.POP3_SSL (host, port=POP3_SSL_PORT, *, timeout=None, context=None)

This is a subclass of @ref{cf0,,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 @code{POP3} constructor.
`context' is an optional @ref{336,,ssl.SSLContext} object which allows
bundling SSL configuration options, certificates and private keys into a
single (potentially long-lived) structure.  Please read @ref{3ad9,,Security considerations}
for best practices.

Raises an @ref{1e65,,auditing event} @code{poplib.connect} with arguments @code{self}, @code{host}, @code{port}.


All commands will raise an @ref{1e65,,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.



Άλλαξε στην έκδοση 3.2: `context' parameter added.



Άλλαξε στην έκδοση 3.4: The class now supports hostname check with
@ref{3c0e,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{3c20,,ssl.HAS_SNI}).



Άλλαξε στην έκδοση 3.9: If the `timeout' parameter is set to be zero, it will raise a
@ref{277,,ValueError} to prevent the creation of a non-blocking socket.



Άλλαξε στην έκδοση 3.12: The deprecated `keyfile' and `certfile' parameters have been removed.

@end deffn

One exception is defined as an attribute of the @code{poplib} module:

@geindex error_proto
@anchor{library/poplib poplib error_proto}@anchor{1545}
@deffn {Εξαίρεση} poplib.error_proto

Exception raised on any errors from this module (errors from @ref{d4,,socket}
module are not caught). The reason for the exception is passed to the
constructor as a string.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{77,,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{4269}@anchor{library/poplib pop3-objects}@anchor{426a}
@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{cf0,,POP3} instance has the following methods:

@geindex set_debuglevel() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 set_debuglevel}@anchor{426b}
@deffn {Μέθοδος} 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() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 getwelcome}@anchor{426c}
@deffn {Μέθοδος} POP3.getwelcome ()

Returns the greeting string sent by the POP3 server.
@end deffn

@geindex capa() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 capa}@anchor{1326}
@deffn {Μέθοδος} 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'...]@}}.


Added in version 3.4.

@end deffn

@geindex user() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 user}@anchor{426d}
@deffn {Μέθοδος} POP3.user (username)

Send user command, response should indicate that a password is required.
@end deffn

@geindex pass_() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 pass_}@anchor{426e}
@deffn {Μέθοδος} POP3.pass_ (password)

Send password, response includes message count and mailbox size. Note: the
mailbox on the server is locked until @ref{1544,,quit()} is called.
@end deffn

@geindex apop() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 apop}@anchor{426f}
@deffn {Μέθοδος} POP3.apop (user, secret)

Use the more secure APOP authentication to log into the POP3 server.
@end deffn

@geindex rpop() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 rpop}@anchor{4270}
@deffn {Μέθοδος} POP3.rpop (user)

Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.
@end deffn

@geindex stat() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 stat}@anchor{4271}
@deffn {Μέθοδος} POP3.stat ()

Get mailbox status.  The result is a tuple of 2 integers: @code{(message count,
mailbox size)}.
@end deffn

@geindex list() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 list}@anchor{4272}
@deffn {Μέθοδος} 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() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 retr}@anchor{4273}
@deffn {Μέθοδος} 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() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 dele}@anchor{4274}
@deffn {Μέθοδος} 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() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 rset}@anchor{4275}
@deffn {Μέθοδος} POP3.rset ()

Remove any deletion marks for the mailbox.
@end deffn

@geindex noop() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 noop}@anchor{4276}
@deffn {Μέθοδος} POP3.noop ()

Do nothing.  Might be used as a keep-alive.
@end deffn

@geindex quit() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 quit}@anchor{1544}
@deffn {Μέθοδος} POP3.quit ()

Signoff:  commit changes, unlock mailbox, drop connection.
@end deffn

@geindex top() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 top}@anchor{4277}
@deffn {Μέθοδος} 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() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 uidl}@anchor{4278}
@deffn {Μέθοδος} 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() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 utf8}@anchor{11fa}
@deffn {Μέθοδος} POP3.utf8 ()

Try to switch to UTF-8 mode. Returns the server response if successful,
raises @ref{1545,,error_proto} if not. Specified in 
@geindex RFC; RFC 6856
RFC 6856@footnote{https://datatracker.ietf.org/doc/html/rfc6856.html}.


Added in version 3.5.

@end deffn

@geindex stls() (μέθοδος της poplib.POP3)
@anchor{library/poplib poplib POP3 stls}@anchor{1327}
@deffn {Μέθοδος} 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{336,,ssl.SSLContext} object which allows
bundling SSL configuration options, certificates and private keys into
a single (potentially long-lived) structure.  Please read @ref{3ad9,,Security considerations}
for best practices.

This method supports hostname checking via
@ref{3c0e,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{3c20,,ssl.HAS_SNI}).


Added in version 3.4.

@end deffn

Instances of @ref{cf1,,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{4279}@anchor{library/poplib pop3-example}@anchor{427a}
@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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node imaplib — IMAP4 protocol client,smtplib — SMTP protocol client,poplib — POP3 protocol client,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/imaplib doc}@anchor{427b}@anchor{library/imaplib imaplib-imap4-protocol-client}@anchor{427c}@anchor{library/imaplib module-imaplib}@anchor{77}@anchor{library/imaplib translation-repo}@anchor{427d}
@subsection @code{imaplib} — IMAP4 protocol client


@geindex module; imaplib

`Source code:' Lib/imaplib.py@footnote{https://github.com/python/cpython/tree/main/Lib/imaplib.py}

@geindex IMAP4;protocol
@geindex IMAP4_SSL;protocol
@geindex IMAP4_stream;protocol


__________________________________________________________________


This module defines three classes, @ref{31a,,IMAP4}, @ref{cd3,,IMAP4_SSL} and
@ref{cd5,,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{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

Three classes are provided by the @code{imaplib} module, @ref{31a,,IMAP4} is the
base class:

@geindex IMAP4 (κλάση σε imaplib)
@anchor{library/imaplib imaplib IMAP4}@anchor{31a}
@deffn {Κλάση} 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 @code{IMAP4} class supports the @ref{20a,,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


Άλλαξε στην έκδοση 3.5: Support for the @ref{20a,,with} statement was added.



Άλλαξε στην έκδοση 3.9: The optional `timeout' parameter was added.

@end deffn

Three exceptions are defined as attributes of the @ref{31a,,IMAP4} class:

@geindex IMAP4.error
@anchor{library/imaplib imaplib IMAP4 error}@anchor{1a0c}
@deffn {Εξαίρεση} 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{427e}
@deffn {Εξαίρεση} IMAP4.abort

IMAP4 server errors cause this exception to be raised.  This is a sub-class of
@ref{1a0c,,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{427f}
@deffn {Εξαίρεση} IMAP4.readonly

This exception is raised when a writable mailbox has its status changed by the
server.  This is a sub-class of @ref{1a0c,,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 (κλάση σε imaplib)
@anchor{library/imaplib imaplib IMAP4_SSL}@anchor{cd3}
@deffn {Κλάση} imaplib.IMAP4_SSL (host='@w{'}, port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)

This is a subclass derived from @ref{31a,,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{336,,ssl.SSLContext} object which allows bundling
SSL configuration options, certificates and private keys into a single
(potentially long-lived) structure.  Please read @ref{3ad9,,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.


Άλλαξε στην έκδοση 3.3: `ssl_context' parameter was added.



Άλλαξε στην έκδοση 3.4: The class now supports hostname check with
@ref{3c0e,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{3c20,,ssl.HAS_SNI}).



Άλλαξε στην έκδοση 3.9: The optional `timeout' parameter was added.



Άλλαξε στην έκδοση 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 (κλάση σε imaplib)
@anchor{library/imaplib imaplib IMAP4_stream}@anchor{cd5}
@deffn {Κλάση} imaplib.IMAP4_stream (command)

This is a subclass derived from @ref{31a,,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() (στη μονάδα imaplib)
@anchor{library/imaplib imaplib Internaldate2tuple}@anchor{4280}
@deffn {Συνάρτηση} imaplib.Internaldate2tuple (datestr)

Parse an IMAP4 @code{INTERNALDATE} string and return corresponding local
time.  The return value is a @ref{10a7,,time.struct_time} tuple or
@code{None} if the string has wrong format.
@end deffn

@geindex Int2AP() (στη μονάδα imaplib)
@anchor{library/imaplib imaplib Int2AP}@anchor{4281}
@deffn {Συνάρτηση} imaplib.Int2AP (num)

Converts an integer into a bytes representation using characters from the set
[@code{A} .. @code{P}].
@end deffn

@geindex ParseFlags() (στη μονάδα imaplib)
@anchor{library/imaplib imaplib ParseFlags}@anchor{4282}
@deffn {Συνάρτηση} imaplib.ParseFlags (flagstr)

Converts an IMAP4 @code{FLAGS} response to a tuple of individual flags.
@end deffn

@geindex Time2Internaldate() (στη μονάδα imaplib)
@anchor{library/imaplib imaplib Time2Internaldate}@anchor{4283}
@deffn {Συνάρτηση} 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{75e,,time.time()}), a 9-tuple representing local time
an instance of @ref{10a7,,time.struct_time} (as returned by
@ref{189b,,time.localtime()}), an aware instance of
@ref{6e7,,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 Δείτε επίσης


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{4284}@anchor{library/imaplib imap4-objects}@anchor{4285}
@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)'}).

Most commands return 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{31a,,IMAP4} instance has the following methods:

@geindex append() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 append}@anchor{4286}
@deffn {Μέθοδος} IMAP4.append (mailbox, flags, date_time, message)

Append `message' to named mailbox.
@end deffn

@geindex authenticate() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 authenticate}@anchor{4287}
@deffn {Μέθοδος} 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.


Άλλαξε στην έκδοση 3.5: string usernames and passwords are now encoded to @code{utf-8} instead of
being limited to ASCII.

@end deffn

@geindex check() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 check}@anchor{4288}
@deffn {Μέθοδος} IMAP4.check ()

Checkpoint mailbox on server.
@end deffn

@geindex close() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 close}@anchor{cd7}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 copy}@anchor{4289}
@deffn {Μέθοδος} IMAP4.copy (message_set, new_mailbox)

Copy `message_set' messages onto end of `new_mailbox'.
@end deffn

@geindex create() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 create}@anchor{428a}
@deffn {Μέθοδος} IMAP4.create (mailbox)

Create new mailbox named `mailbox'.
@end deffn

@geindex delete() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 delete}@anchor{428b}
@deffn {Μέθοδος} IMAP4.delete (mailbox)

Delete old mailbox named `mailbox'.
@end deffn

@geindex deleteacl() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 deleteacl}@anchor{428c}
@deffn {Μέθοδος} IMAP4.deleteacl (mailbox, who)

Delete the ACLs (remove any rights) set for who on mailbox.
@end deffn

@geindex enable() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 enable}@anchor{11c2}
@deffn {Μέθοδος} 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}).


Added in version 3.5: The @code{enable()} method itself, and 
@geindex RFC; RFC 6855
RFC 6855@footnote{https://datatracker.ietf.org/doc/html/rfc6855.html} support.

@end deffn

@geindex expunge() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 expunge}@anchor{428d}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 fetch}@anchor{428e}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 getacl}@anchor{428f}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 getannotation}@anchor{4290}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 getquota}@anchor{4291}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 getquotaroot}@anchor{4292}
@deffn {Μέθοδος} 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 idle() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 idle}@anchor{4bb}
@deffn {Μέθοδος} IMAP4.idle (duration=None)

Return an @code{Idler}: an iterable context manager implementing the
IMAP4 @code{IDLE} command as defined in 
@geindex RFC; RFC 2177
RFC 2177@footnote{https://datatracker.ietf.org/doc/html/rfc2177.html}.

The returned object sends the @code{IDLE} command when activated by the
@ref{20a,,with} statement, produces IMAP untagged responses via the
@ref{6ce,,iterator} protocol, and sends @code{DONE} upon context exit.

All untagged responses that arrive after sending the @code{IDLE} command
(including any that arrive before the server acknowledges the command) will
be available via iteration. Any leftover responses (those not iterated in
the @ref{20a,,with} context) can be retrieved in the usual way after
@code{IDLE} ends, using @ref{4293,,IMAP4.response()}.

Responses are represented as @code{(type, [data, ...])} tuples, as described
in @ref{4285,,IMAP4 Objects}.

The `duration' argument sets a maximum duration (in seconds) to keep idling,
after which any ongoing iteration will stop. It can be an @ref{326,,int} or
@ref{327,,float}, or @code{None} for no time limit.
Callers wishing to avoid inactivity timeouts on servers that impose them
should keep this at most 29 minutes (1740 seconds).
Requires a socket connection; `duration' must be @code{None} on
@ref{cd5,,IMAP4_stream} connections.

@example
>>> with M.idle(duration=29 * 60) as idler:
...     for typ, data in idler:
...         print(typ, data)
...
EXISTS [b'1']
RECENT [b'1']
@end example

@geindex burst() (μέθοδος της imaplib.IMAP4.Idler)
@anchor{library/imaplib imaplib IMAP4 Idler burst}@anchor{4294}
@deffn {Μέθοδος} Idler.burst (interval=0.1)

Yield a burst of responses no more than `interval' seconds apart
(expressed as an @ref{326,,int} or @ref{327,,float}).

This @ref{1409,,generator} is an alternative to iterating one response at a
time, intended to aid in efficient batch processing. It retrieves the
next response along with any immediately available subsequent responses.
(For example, a rapid series of @code{EXPUNGE} responses after a bulk
delete.)

Requires a socket connection; does not work on @ref{cd5,,IMAP4_stream}
connections.

@example
>>> with M.idle() as idler:
...     # get a response and any others following by < 0.1 seconds
...     batch = list(idler.burst())
...     print(f'processing @{len(batch)@} responses...')
...     print(batch)
...
processing 3 responses...
[('EXPUNGE', [b'2']), ('EXPUNGE', [b'1']), ('RECENT', [b'0'])]
@end example

@cartouche
@quotation Πρακτική συμβουλή 
The @code{IDLE} context’s maximum duration, as passed to
@code{IMAP4.idle()}, is respected when waiting for the first response
in a burst. Therefore, an expired @code{Idler} will cause this
generator to return immediately without producing anything. Callers
should consider this if using it in a loop.
@end quotation
@end cartouche
@end deffn

@cartouche
@quotation Σημείωση 
The iterator returned by @code{IMAP4.idle()} is usable only within a
@ref{20a,,with} statement. Before or after that context, unsolicited
responses are collected internally whenever a command finishes, and can
be retrieved with @ref{4293,,IMAP4.response()}.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
The @code{Idler} class name and structure are internal interfaces,
subject to change. Calling code can rely on its context management,
iteration, and public method to remain stable, but should not subclass,
instantiate, compare, or otherwise directly reference the class.
@end quotation
@end cartouche


Added in version 3.14.

@end deffn

@geindex list() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 list}@anchor{4295}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 login}@anchor{4296}
@deffn {Μέθοδος} IMAP4.login (user, password)

Identify the client using a plaintext password. The `password' will be quoted.
@end deffn

@geindex login_cram_md5() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 login_cram_md5}@anchor{1a0b}
@deffn {Μέθοδος} 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}.


Άλλαξε στην έκδοση 3.15: An @ref{1a0c,,IMAP4.error} is raised if MD5 support is not available.

@end deffn

@geindex logout() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 logout}@anchor{e53}
@deffn {Μέθοδος} IMAP4.logout ()

Shutdown connection to server. Returns server @code{BYE} response.


Άλλαξε στην έκδοση 3.8: The method no longer ignores silently arbitrary exceptions.

@end deffn

@geindex lsub() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 lsub}@anchor{4297}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 myrights}@anchor{4298}
@deffn {Μέθοδος} IMAP4.myrights (mailbox)

Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
@end deffn

@geindex namespace() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 namespace}@anchor{4299}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 noop}@anchor{429a}
@deffn {Μέθοδος} IMAP4.noop ()

Send @code{NOOP} to server.
@end deffn

@geindex open() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 open}@anchor{cd4}
@deffn {Μέθοδος} 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{277,,ValueError} to reject creating a non-blocking socket.
This method is implicitly called by the @ref{31a,,IMAP4} constructor.
The connection objects established by this method will be used in
the @ref{429b,,IMAP4.read()}, @ref{429c,,IMAP4.readline()}, @ref{429d,,IMAP4.send()},
and @ref{429e,,IMAP4.shutdown()} methods. You may override this method.

Raises an @ref{1e65,,auditing event} @code{imaplib.open} with arguments @code{self}, @code{host}, @code{port}.


Άλλαξε στην έκδοση 3.9: The `timeout' parameter was added.

@end deffn

@geindex partial() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 partial}@anchor{429f}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 proxyauth}@anchor{42a0}
@deffn {Μέθοδος} IMAP4.proxyauth (user)

Assume authentication as `user'. Allows an authorised administrator to proxy
into any user’s mailbox.
@end deffn

@geindex read() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 read}@anchor{429b}
@deffn {Μέθοδος} IMAP4.read (size)

Reads `size' bytes from the remote server. You may override this method.
@end deffn

@geindex readline() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 readline}@anchor{429c}
@deffn {Μέθοδος} IMAP4.readline ()

Reads one line from the remote server. You may override this method.
@end deffn

@geindex recent() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 recent}@anchor{42a1}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 rename}@anchor{42a2}
@deffn {Μέθοδος} IMAP4.rename (oldmailbox, newmailbox)

Rename mailbox named `oldmailbox' to `newmailbox'.
@end deffn

@geindex response() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 response}@anchor{4293}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 search}@anchor{42a3}
@deffn {Μέθοδος} 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{11c2,,enable()}
command.

Example:

@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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 select}@anchor{42a4}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 send}@anchor{429d}
@deffn {Μέθοδος} IMAP4.send (data)

Sends @code{data} to the remote server. You may override this method.

Raises an @ref{1e65,,auditing event} @code{imaplib.send} with arguments @code{self}, @code{data}.
@end deffn

@geindex setacl() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 setacl}@anchor{42a5}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 setannotation}@anchor{42a6}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 setquota}@anchor{42a7}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 shutdown}@anchor{429e}
@deffn {Μέθοδος} IMAP4.shutdown ()

Close connection established in @code{open}.  This method is implicitly
called by @ref{e53,,IMAP4.logout()}.  You may override this method.
@end deffn

@geindex socket() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 socket}@anchor{42a8}
@deffn {Μέθοδος} IMAP4.socket ()

Returns socket instance used to connect to server.
@end deffn

@geindex sort() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 sort}@anchor{42a9}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 starttls}@anchor{15cc}
@deffn {Μέθοδος} IMAP4.starttls (ssl_context=None)

Send a @code{STARTTLS} command.  The `ssl_context' argument is optional
and should be a @ref{336,,ssl.SSLContext} object.  This will enable
encryption on the IMAP connection.  Please read @ref{3ad9,,Security considerations} for
best practices.


Added in version 3.2.



Άλλαξε στην έκδοση 3.4: The method now supports hostname check with
@ref{3c0e,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{3c20,,ssl.HAS_SNI}).

@end deffn

@geindex status() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 status}@anchor{42aa}
@deffn {Μέθοδος} IMAP4.status (mailbox, names)

Request named status conditions for `mailbox'.
@end deffn

@geindex store() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 store}@anchor{42ab}
@deffn {Μέθοδος} 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 Σημείωση 
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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 subscribe}@anchor{42ac}
@deffn {Μέθοδος} IMAP4.subscribe (mailbox)

Subscribe to new mailbox.
@end deffn

@geindex thread() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 thread}@anchor{42ad}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 uid}@anchor{42ae}
@deffn {Μέθοδος} 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() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 unsubscribe}@anchor{42af}
@deffn {Μέθοδος} IMAP4.unsubscribe (mailbox)

Unsubscribe from old mailbox.
@end deffn

@geindex unselect() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 unselect}@anchor{cd6}
@deffn {Μέθοδος} IMAP4.unselect ()

@ref{cd6,,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{cd7,,imaplib.IMAP4.close()}, except
that no messages are permanently removed from the currently
selected mailbox.


Added in version 3.9.

@end deffn

@geindex xatom() (μέθοδος της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 xatom}@anchor{42b0}
@deffn {Μέθοδος} 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{31a,,IMAP4}:

@geindex PROTOCOL_VERSION (ιδιότητα της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 PROTOCOL_VERSION}@anchor{42b1}
@deffn {Ιδιότητα} IMAP4.PROTOCOL_VERSION

The most recent supported protocol in the @code{CAPABILITY} response from the
server.
@end deffn

@geindex debug (ιδιότητα της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 debug}@anchor{42b2}
@deffn {Ιδιότητα} 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 (ιδιότητα της imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 utf8_enabled}@anchor{11c3}
@deffn {Ιδιότητα} IMAP4.utf8_enabled

Boolean value that is normally @code{False}, but is set to @code{True} if an
@ref{11c2,,enable()} command is successfully issued for the @code{UTF8=ACCEPT}
capability.


Added in version 3.5.

@end deffn

@geindex file (imaplib.IMAP4 property)
@anchor{library/imaplib imaplib IMAP4 file}@anchor{2f8}
@deffn {Property} IMAP4.file

Internal @ref{15b5,,BufferedReader} associated with the underlying socket.
This property is documented for legacy purposes but not part of the public
interface. The caller is responsible to ensure that the current file is
closed before changing it.


Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.19.

@end deffn

@node IMAP4 Example,,IMAP4 Objects,imaplib — IMAP4 protocol client
@anchor{library/imaplib id2}@anchor{42b3}@anchor{library/imaplib imap4-example}@anchor{42b4}
@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node smtplib — SMTP protocol client,uuid — UUID objects according to RFC 9562,imaplib — IMAP4 protocol client,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/smtplib doc}@anchor{42b5}@anchor{library/smtplib module-smtplib}@anchor{d2}@anchor{library/smtplib smtplib-smtp-protocol-client}@anchor{42b6}@anchor{library/smtplib translation-repo}@anchor{42b7}
@subsection @code{smtplib} — SMTP protocol client


@geindex module; smtplib

`Source code:' Lib/smtplib.py@footnote{https://github.com/python/cpython/tree/main/Lib/smtplib.py}

@geindex SMTP;protocol
@geindex Simple Mail Transfer Protocol


__________________________________________________________________


The @code{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{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

@geindex SMTP (κλάση σε smtplib)
@anchor{library/smtplib smtplib SMTP}@anchor{cfa}
@deffn {Κλάση} smtplib.SMTP (host='@w{'}, port=0, local_hostname=None[, timeout], source_address=None)

An @code{SMTP} instance encapsulates an SMTP connection.  It has methods
that support a full repertoire of SMTP and ESMTP operations.

If the host parameter is set to a truthy value, @ref{1913,,SMTP.connect()} is called with
host and port automatically when the object is created; otherwise, @code{connect()} must
be called manually.

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{1cec,,socket.getfqdn()}.  If the @ref{1913,,connect()} call returns anything other
than a success code, an @ref{42b8,,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{c0e,,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{120a,,sendmail()}, and @ref{42b9,,SMTP.quit()} methods.
An example is included below.

The @code{SMTP} class supports the @ref{20a,,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{1e65,,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.


@geindex default_port (ιδιότητα της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP default_port}@anchor{42ba}
@deffn {Ιδιότητα} default_port

The default port used for SMTP connections (25).
@end deffn


Άλλαξε στην έκδοση 3.3: Support for the @ref{20a,,with} statement was added.



Άλλαξε στην έκδοση 3.3: `source_address' argument was added.



Added in version 3.5: The SMTPUTF8 extension (
@geindex RFC; RFC 6531
RFC 6531@footnote{https://datatracker.ietf.org/doc/html/rfc6531.html}) is now supported.



Άλλαξε στην έκδοση 3.9: If the `timeout' parameter is set to be zero, it will raise a
@ref{277,,ValueError} to prevent the creation of a non-blocking socket.

@end deffn

@geindex SMTP_SSL (κλάση σε smtplib)
@anchor{library/smtplib smtplib SMTP_SSL}@anchor{cfb}
@deffn {Κλάση} smtplib.SMTP_SSL (host='@w{'}, port=0, local_hostname=None, *[, timeout], context=None, source_address=None)

An @code{SMTP_SSL} instance behaves exactly the same as instances of
@ref{cfa,,SMTP}. @code{SMTP_SSL} should be used for situations where SSL is
required from the beginning of the connection and using @ref{14e4,,SMTP.starttls()} is
not appropriate.

If the host parameter is set to a truthy value, @ref{1913,,SMTP.connect()} is called with host
and port automatically when the object is created; otherwise, @code{SMTP.connect()} must
be called manually.

The optional arguments `local_hostname', `timeout' and `source_address' have the same
meaning as they do in the @ref{cfa,,SMTP} class.  `context', also optional,
can contain a @ref{336,,SSLContext} and allows configuring various
aspects of the secure connection.  Please read @ref{3ad9,,Security considerations} for
best practices.

@geindex default_port (ιδιότητα της smtplib.SMTP_SSL)
@anchor{library/smtplib smtplib SMTP_SSL default_port}@anchor{42bb}
@deffn {Ιδιότητα} default_port

The default port used for SMTP-over-SSL connections (465).
@end deffn


Άλλαξε στην έκδοση 3.3: `context' was added.



Άλλαξε στην έκδοση 3.3: The `source_address' argument was added.



Άλλαξε στην έκδοση 3.4: The class now supports hostname check with
@ref{3c0e,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{3c20,,ssl.HAS_SNI}).



Άλλαξε στην έκδοση 3.9: If the `timeout' parameter is set to be zero, it will raise a
@ref{277,,ValueError} to prevent the creation of a non-blocking socket



Άλλαξε στην έκδοση 3.12: The deprecated `keyfile' and `certfile' parameters have been removed.

@end deffn

@geindex LMTP (κλάση σε smtplib)
@anchor{library/smtplib smtplib LMTP}@anchor{cfc}
@deffn {Κλάση} 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
@ref{1913,,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{cfa,,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.


Άλλαξε στην έκδοση 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{134a}
@deffn {Εξαίρεση} smtplib.SMTPException

Subclass of @ref{53c,,OSError} that is the base exception class for all
the other exceptions provided by this module.


Άλλαξε στην έκδοση 3.4: SMTPException became subclass of @ref{53c,,OSError}

@end deffn

@geindex SMTPServerDisconnected
@anchor{library/smtplib smtplib SMTPServerDisconnected}@anchor{42bc}
@deffn {Εξαίρεση} smtplib.SMTPServerDisconnected

This exception is raised when the server unexpectedly disconnects, or when an
attempt is made to use the @ref{cfa,,SMTP} instance before connecting it to a
server.
@end deffn

@geindex SMTPResponseException
@anchor{library/smtplib smtplib SMTPResponseException}@anchor{42bd}
@deffn {Εξαίρεση} 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.

@geindex smtp_code (ιδιότητα της smtplib.SMTPResponseException)
@anchor{library/smtplib smtplib SMTPResponseException smtp_code}@anchor{42be}
@deffn {Ιδιότητα} smtp_code

The error code.
@end deffn

@geindex smtp_error (ιδιότητα της smtplib.SMTPResponseException)
@anchor{library/smtplib smtplib SMTPResponseException smtp_error}@anchor{42bf}
@deffn {Ιδιότητα} smtp_error

The error message.
@end deffn
@end deffn

@geindex SMTPSenderRefused
@anchor{library/smtplib smtplib SMTPSenderRefused}@anchor{42c0}
@deffn {Εξαίρεση} smtplib.SMTPSenderRefused

Sender address refused.  In addition to the attributes set by on all
@ref{42bd,,SMTPResponseException} exceptions, this sets “sender” to the string that
the SMTP server refused.
@end deffn

@geindex SMTPRecipientsRefused
@anchor{library/smtplib smtplib SMTPRecipientsRefused}@anchor{42c1}
@deffn {Εξαίρεση} smtplib.SMTPRecipientsRefused

All recipient addresses refused.

@geindex recipients (ιδιότητα της smtplib.SMTPRecipientsRefused)
@anchor{library/smtplib smtplib SMTPRecipientsRefused recipients}@anchor{42c2}
@deffn {Ιδιότητα} recipients

A dictionary of exactly the same sort as returned
by @ref{120a,,SMTP.sendmail()} containing the errors for
each recipient.
@end deffn
@end deffn

@geindex SMTPDataError
@anchor{library/smtplib smtplib SMTPDataError}@anchor{42c3}
@deffn {Εξαίρεση} smtplib.SMTPDataError

The SMTP server refused to accept the message data.
@end deffn

@geindex SMTPConnectError
@anchor{library/smtplib smtplib SMTPConnectError}@anchor{42b8}
@deffn {Εξαίρεση} smtplib.SMTPConnectError

Error occurred during establishment of a connection  with the server.
@end deffn

@geindex SMTPHeloError
@anchor{library/smtplib smtplib SMTPHeloError}@anchor{42c4}
@deffn {Εξαίρεση} smtplib.SMTPHeloError

The server refused our @code{HELO} message.
@end deffn

@geindex SMTPNotSupportedError
@anchor{library/smtplib smtplib SMTPNotSupportedError}@anchor{1f9f}
@deffn {Εξαίρεση} smtplib.SMTPNotSupportedError

The command or option attempted is not supported by the server.


Added in version 3.5.

@end deffn

@geindex SMTPAuthenticationError
@anchor{library/smtplib smtplib SMTPAuthenticationError}@anchor{42c5}
@deffn {Εξαίρεση} smtplib.SMTPAuthenticationError

SMTP authentication went wrong.  Most probably the server didn’t accept the
username/password combination provided.
@end deffn


@subsubheading Δείτε επίσης



@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{42c6}@anchor{library/smtplib smtp-objects}@anchor{42c7}
@subsubsection SMTP Objects


An @ref{cfa,,SMTP} instance has the following methods:

@geindex set_debuglevel() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP set_debuglevel}@anchor{1209}
@deffn {Μέθοδος} 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.


Άλλαξε στην έκδοση 3.5: Added debuglevel 2.

@end deffn

@geindex docmd() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP docmd}@anchor{42c8}
@deffn {Μέθοδος} 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{42bc,,SMTPServerDisconnected} will be raised.
@end deffn

@geindex connect() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP connect}@anchor{1913}
@deffn {Μέθοδος} 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.

If port is not changed from its default value of 0, the value of the @ref{42ba,,default_port}
attribute is used.

Raises an @ref{1e65,,auditing event} @code{smtplib.connect} with arguments @code{self}, @code{host}, @code{port}.
@end deffn

@geindex helo() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP helo}@anchor{42c9}
@deffn {Μέθοδος} 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 @ref{42ca,,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{120a,,sendmail()} when necessary.
@end deffn

@geindex ehlo() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP ehlo}@anchor{42cb}
@deffn {Μέθοδος} 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{42cc,,has_extn()}.
Also sets several informational attributes: the message returned by
the server is stored as the @ref{42cd,,ehlo_resp} attribute, @ref{42ce,,does_esmtp}
is set to @code{True} or @code{False} depending on whether the server supports
ESMTP, and @ref{42cf,,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{42cc,,has_extn()} before sending mail, it should not be
necessary to call this method explicitly.  It will be implicitly called by
@ref{120a,,sendmail()} when necessary.
@end deffn

@geindex ehlo_or_helo_if_needed() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP ehlo_or_helo_if_needed}@anchor{42d0}
@deffn {Μέθοδος} SMTP.ehlo_or_helo_if_needed ()

This method calls @ref{42cb,,ehlo()} and/or @ref{42c9,,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{42c4,,SMTPHeloError}

The server didn’t reply properly to the @code{HELO} greeting.
@end table
@end deffn

@geindex has_extn() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP has_extn}@anchor{42cc}
@deffn {Μέθοδος} SMTP.has_extn (name)

Return @ref{fcc,,True} if `name' is in the set of SMTP service extensions returned
by the server, @ref{ef5,,False} otherwise. Case is ignored.
@end deffn

@geindex verify() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP verify}@anchor{42d1}
@deffn {Μέθοδος} 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 Σημείωση 
Many sites disable SMTP @code{VRFY} in order to foil spammers.
@end quotation
@end cartouche
@end deffn

@geindex login() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP login}@anchor{42d2}
@deffn {Μέθοδος} 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{42c4,,SMTPHeloError}

The server didn’t reply properly to the @code{HELO} greeting.

@item @ref{42c5,,SMTPAuthenticationError}

The server didn’t accept the username/password combination.

@item @ref{1f9f,,SMTPNotSupportedError}

The @code{AUTH} command is not supported by the server.

@item @ref{134a,,SMTPException}

No suitable authentication method was found.
@end table

Each of the authentication methods supported by @code{smtplib} are tried in
turn if they are advertised as supported by the server.  See @ref{1208,,auth()}
for a list of supported authentication methods.  `initial_response_ok' is
passed through to @code{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.


Άλλαξε στην έκδοση 3.5: @ref{1f9f,,SMTPNotSupportedError} may be raised, and the
`initial_response_ok' parameter was added.

@end deffn

@geindex auth() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP auth}@anchor{1208}
@deffn {Μέθοδος} 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 @ref{42cf,,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{42d2,,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 @code{smtplib}.


Added in version 3.5.

@end deffn

@geindex starttls() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP starttls}@anchor{14e4}
@deffn {Μέθοδος} 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{42cb,,ehlo()}
again.

If `keyfile' and `certfile' are provided, they are used to create an
@ref{336,,ssl.SSLContext}.

Optional `context' parameter is an @ref{336,,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.


Άλλαξε στην έκδοση 3.12: The deprecated `keyfile' and `certfile' parameters have been removed.



@table @asis

@item @ref{42c4,,SMTPHeloError}

The server didn’t reply properly to the @code{HELO} greeting.

@item @ref{1f9f,,SMTPNotSupportedError}

The server does not support the STARTTLS extension.

@item @ref{30d,,RuntimeError}

SSL/TLS support is not available to your Python interpreter.
@end table


Άλλαξε στην έκδοση 3.3: `context' was added.



Άλλαξε στην έκδοση 3.4: The method now supports hostname check with
@ref{3c0e,,ssl.SSLContext.check_hostname} and `Server Name Indicator' (see
@ref{3c20,,HAS_SNI}).



Άλλαξε στην έκδοση 3.5: The error raised for lack of STARTTLS support is now the
@ref{1f9f,,SMTPNotSupportedError} subclass instead of the base
@ref{134a,,SMTPException}.

@end deffn

@geindex sendmail() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP sendmail}@anchor{120a}
@deffn {Μέθοδος} 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'. Each option should be passed as a string
containing the full text of the option, including any potential key
(for instance, @code{"NOTIFY=SUCCESS,FAILURE"}). (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 Σημείωση 
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{42c1,,SMTPRecipientsRefused}

All recipients were refused.  Nobody got the mail.

@item @ref{42c4,,SMTPHeloError}

The server didn’t reply properly to the @code{HELO} greeting.

@item @ref{42c0,,SMTPSenderRefused}

The server didn’t accept the `from_addr'.

@item @ref{42c3,,SMTPDataError}

The server replied with an unexpected error code (other than a refusal of a
recipient).

@item @ref{1f9f,,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.


Άλλαξε στην έκδοση 3.2: `msg' may be a byte string.



Άλλαξε στην έκδοση 3.5: @code{SMTPUTF8} support added, and @ref{1f9f,,SMTPNotSupportedError} may be
raised if @code{SMTPUTF8} is specified but the server does not support it.

@end deffn

@geindex send_message() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP send_message}@anchor{120b}
@deffn {Μέθοδος} SMTP.send_message (msg, from_addr=None, to_addrs=None, mail_options=(), rcpt_options=())

This is a convenience method for calling @ref{120a,,sendmail()} with the message
represented by an @ref{780,,email.message.Message} object.  The arguments have
the same meaning as for @code{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{277,,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{1578,,BytesGenerator} with @code{\r\n} as the `linesep', and
calls @ref{120a,,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 @ref{1f9f,,SMTPNotSupportedError} is raised.  Otherwise the @code{Message} is
serialized with a clone of its @ref{52,,policy} with the
@ref{217,,utf8} attribute set to @code{True}, and
@code{SMTPUTF8} and @code{BODY=8BITMIME} are added to `mail_options'.


Added in version 3.2.



Added in version 3.5: Support for internationalized addresses (@code{SMTPUTF8}).

@end deffn

@geindex quit() (μέθοδος της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP quit}@anchor{42b9}
@deffn {Μέθοδος} 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.

Additionally, an SMTP instance has the following attributes:

@geindex helo_resp (ιδιότητα της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP helo_resp}@anchor{42ca}
@deffn {Ιδιότητα} SMTP.helo_resp

The response to the @code{HELO} command, see @ref{42c9,,helo()}.
@end deffn

@geindex ehlo_resp (ιδιότητα της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP ehlo_resp}@anchor{42cd}
@deffn {Ιδιότητα} SMTP.ehlo_resp

The response to the @code{EHLO} command, see @ref{42cb,,ehlo()}.
@end deffn

@geindex does_esmtp (ιδιότητα της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP does_esmtp}@anchor{42ce}
@deffn {Ιδιότητα} SMTP.does_esmtp

A boolean value indicating whether the server supports ESMTP, see
@ref{42cb,,ehlo()}.
@end deffn

@geindex esmtp_features (ιδιότητα της smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP esmtp_features}@anchor{42cf}
@deffn {Ιδιότητα} SMTP.esmtp_features

A dictionary of the names of SMTP service extensions supported by the server,
see @ref{42cb,,ehlo()}.
@end deffn

@node SMTP Example,,SMTP Objects,smtplib — SMTP protocol client
@anchor{library/smtplib id2}@anchor{42d3}@anchor{library/smtplib smtp-example}@anchor{42d4}
@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 Σημείωση 
In general, you will want to use the @ref{3e,,email} package’s features to
construct an email message, which you can then send
via @ref{120b,,send_message()}; see @ref{12e7,,email; Examples}.
@end quotation
@end cartouche

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node uuid — UUID objects according to RFC 9562,socketserver — A framework for network servers,smtplib — SMTP protocol client,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/uuid doc}@anchor{42d5}@anchor{library/uuid module-uuid}@anchor{119}@anchor{library/uuid translation-repo}@anchor{42d6}@anchor{library/uuid uuid-uuid-objects-according-to-rfc-9562}@anchor{42d7}
@subsection @code{uuid} — UUID objects according to 
@geindex RFC; RFC 9562
`RFC 9562'


@geindex module; uuid

`Source code:' Lib/uuid.py@footnote{https://github.com/python/cpython/tree/main/Lib/uuid.py}


__________________________________________________________________


This module provides immutable @ref{e25,,UUID} objects (the @code{UUID} class)
and @ref{42d8,,functions} for generating UUIDs corresponding
to a specific UUID version as specified in 
@geindex RFC; RFC 9562
RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html} (which supersedes 
@geindex RFC; RFC 4122
RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html}),
for example, @ref{f67,,uuid1()} for UUID version 1, @ref{561,,uuid3()} for UUID version 3, and so on.
Note that UUID version 2 is deliberately omitted as it is outside the scope of the RFC.

If all you want is a unique ID, you should probably call @ref{f67,,uuid1()} or
@ref{563,,uuid4()}.  Note that @code{uuid1()} may compromise privacy since it creates
a UUID containing the computer’s network address.  @code{uuid4()} creates a
random UUID.

Depending on support from the underlying platform, @ref{f67,,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{e25,,UUID} have an @ref{f65,,is_safe} attribute
which relays any information about the UUID’s safety, using this enumeration:

@geindex SafeUUID (κλάση σε uuid)
@anchor{library/uuid uuid SafeUUID}@anchor{42d9}
@deffn {Κλάση} uuid.SafeUUID


Added in version 3.7.


@geindex safe (ιδιότητα της uuid.SafeUUID)
@anchor{library/uuid uuid SafeUUID safe}@anchor{42da}
@deffn {Ιδιότητα} safe

The UUID was generated by the platform in a multiprocessing-safe way.
@end deffn

@geindex unsafe (ιδιότητα της uuid.SafeUUID)
@anchor{library/uuid uuid SafeUUID unsafe}@anchor{42db}
@deffn {Ιδιότητα} unsafe

The UUID was not generated in a multiprocessing-safe way.
@end deffn

@geindex unknown (ιδιότητα της uuid.SafeUUID)
@anchor{library/uuid uuid SafeUUID unknown}@anchor{42dc}
@deffn {Ιδιότητα} unknown

The platform does not provide information on whether the UUID was
generated safely or not.
@end deffn
@end deffn

@geindex UUID (κλάση σε uuid)
@anchor{library/uuid uuid UUID}@anchor{e25}
@deffn {Κλάση} uuid.UUID (hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)

Create a UUID from either a string of 32 hexadecimal digits, a string of 16
bytes in big-endian order as the `bytes' argument, a string of 16 bytes in
little-endian order as the `bytes_le' argument, a tuple of six integers
(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') as the
`fields' argument, or a single 128-bit integer as the `int' argument.
When a string of hex digits is given, curly braces, hyphens,
and a URN prefix are all optional.  For example, these
expressions all yield the same 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

Exactly one of `hex', `bytes', `bytes_le', `fields', or `int' must be given.
The `version' argument is optional; if given, the resulting UUID will have its
variant and version number set according to 
@geindex RFC; RFC 9562
RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html}, overriding bits in the
given `hex', `bytes', `bytes_le', `fields', or `int'.

Comparison of UUID objects are made by way of comparing their
@ref{42dd,,UUID.int} attributes.  Comparison with a non-UUID object
raises a @ref{291,,TypeError}.

@code{str(uuid)} returns a string in the form
@code{12345678-1234-5678-1234-567812345678} where the 32 hexadecimal digits
represent the UUID.
@end deffn

@ref{e25,,UUID} instances have these read-only attributes:

@geindex bytes (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID bytes}@anchor{42de}
@deffn {Ιδιότητα} UUID.bytes

The UUID as a 16-byte string (containing the six integer fields in big-endian
byte order).
@end deffn

@geindex bytes_le (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID bytes_le}@anchor{42df}
@deffn {Ιδιότητα} UUID.bytes_le

The UUID as a 16-byte string (with `time_low', `time_mid', and `time_hi_version'
in little-endian byte order).
@end deffn

@geindex fields (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID fields}@anchor{42e0}
@deffn {Ιδιότητα} UUID.fields

A tuple of the six integer fields of the UUID, which are also available as six
individual attributes and two derived attributes:
@end deffn


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

Field

@tab

Meaning

@item

@geindex time_low (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID time_low}@anchor{42e1}
@deffn {Ιδιότητα} UUID.time_low
@end deffn

@tab

The first 32 bits of the UUID. Only relevant to version 1.

@item

@geindex time_mid (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID time_mid}@anchor{42e2}
@deffn {Ιδιότητα} UUID.time_mid
@end deffn

@tab

The next 16 bits of the UUID. Only relevant to version 1.

@item

@geindex time_hi_version (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID time_hi_version}@anchor{42e3}
@deffn {Ιδιότητα} UUID.time_hi_version
@end deffn

@tab

The next 16 bits of the UUID. Only relevant to version 1.

@item

@geindex clock_seq_hi_variant (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID clock_seq_hi_variant}@anchor{42e4}
@deffn {Ιδιότητα} UUID.clock_seq_hi_variant
@end deffn

@tab

The next 8 bits of the UUID. Only relevant to versions 1 and 6.

@item

@geindex clock_seq_low (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID clock_seq_low}@anchor{42e5}
@deffn {Ιδιότητα} UUID.clock_seq_low
@end deffn

@tab

The next 8 bits of the UUID. Only relevant to versions 1 and 6.

@item

@geindex node (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID node}@anchor{42e6}
@deffn {Ιδιότητα} UUID.node
@end deffn

@tab

The last 48 bits of the UUID. Only relevant to version 1.

@item

@geindex time (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID time}@anchor{42e7}
@deffn {Ιδιότητα} UUID.time
@end deffn

@tab

The 60-bit timestamp as a count of 100-nanosecond intervals since
Gregorian epoch (1582-10-15 00:00:00) for versions 1 and 6, or the
48-bit timestamp in milliseconds since Unix epoch (1970-01-01 00:00:00)
for version 7.

@item

@geindex clock_seq (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID clock_seq}@anchor{42e8}
@deffn {Ιδιότητα} UUID.clock_seq
@end deffn

@tab

The 14-bit sequence number. Only relevant to versions 1 and 6.

@end multitable


@geindex hex (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID hex}@anchor{1ab3}
@deffn {Ιδιότητα} UUID.hex

The UUID as a 32-character lowercase hexadecimal string.
@end deffn

@geindex int (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID int}@anchor{42dd}
@deffn {Ιδιότητα} UUID.int

The UUID as a 128-bit integer.
@end deffn

@geindex urn (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID urn}@anchor{42e9}
@deffn {Ιδιότητα} UUID.urn

The UUID as a URN as specified in 
@geindex RFC; RFC 9562
RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html}.
@end deffn

@geindex variant (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID variant}@anchor{42ea}
@deffn {Ιδιότητα} UUID.variant

The UUID variant, which determines the internal layout of the UUID. This will be
one of the constants @ref{42eb,,RESERVED_NCS}, @ref{42ec,,RFC_4122},
@ref{42ed,,RESERVED_MICROSOFT}, or @ref{42ee,,RESERVED_FUTURE}.
@end deffn

@geindex version (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID version}@anchor{42ef}
@deffn {Ιδιότητα} UUID.version

The UUID version number (1 through 8, meaningful only when the variant is
@ref{42ec,,RFC_4122}).


Άλλαξε στην έκδοση 3.14: Added UUID versions 6, 7 and 8.

@end deffn

@geindex is_safe (ιδιότητα της uuid.UUID)
@anchor{library/uuid uuid UUID is_safe}@anchor{f65}
@deffn {Ιδιότητα} UUID.is_safe

An enumeration of @ref{42d9,,SafeUUID} which indicates whether the platform
generated the UUID in a multiprocessing-safe way.


Added in version 3.7.

@end deffn

The @code{uuid} module defines the following functions:

@geindex getnode() (στη μονάδα uuid)
@anchor{library/uuid uuid getnode}@anchor{f66}
@deffn {Συνάρτηση} uuid.getnode ()

Get the hardware address as a 48-bit positive integer.  The first time this
runs, it may launch a separate program, which could be quite slow.  If all
attempts to obtain the hardware address fail, we choose a random 48-bit
number with the multicast bit (least significant bit of the first octet)
set to 1 as recommended in 
@geindex RFC; RFC 4122
RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html}.  «Hardware address» means the MAC
address of a network interface.  On a machine with multiple network
interfaces, universally administered MAC addresses (i.e. where the second
least significant bit of the first octet is `unset') will be preferred over
locally administered MAC addresses, but with no other ordering guarantees.


Άλλαξε στην έκδοση 3.7: Universally administered MAC addresses are preferred over locally
administered MAC addresses, since the former are guaranteed to be
globally unique, while the latter are not.

@end deffn

@geindex uuid1() (στη μονάδα uuid)
@anchor{library/uuid uuid-factory-functions}@anchor{42d8}@anchor{library/uuid uuid uuid1}@anchor{f67}
@deffn {Συνάρτηση} uuid.uuid1 (node=None, clock_seq=None)

Generate a UUID from a host ID, sequence number, and the current time
according to 
@geindex RFC; RFC 9562 Section 5.1
RFC 9562@comma{} §5.1@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html#section-5.1}.

When `node' is not specified, @ref{f66,,getnode()} is used to obtain the hardware
address as a 48-bit positive integer. When a sequence number `clock_seq' is
not specified, a pseudo-random 14-bit positive integer is generated.

If `node' or `clock_seq' exceed their expected bit count,
only their least significant bits are kept.
@end deffn

@geindex uuid3() (στη μονάδα uuid)
@anchor{library/uuid uuid uuid3}@anchor{561}
@deffn {Συνάρτηση} 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{1c7,,bytes} object or a string
that will be encoded using UTF-8)
according to 
@geindex RFC; RFC 9562 Section 5.3
RFC 9562@comma{} §5.3@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html#section-5.3}.
@end deffn

@geindex uuid4() (στη μονάδα uuid)
@anchor{library/uuid uuid uuid4}@anchor{563}
@deffn {Συνάρτηση} uuid.uuid4 ()

Generate a random UUID in a cryptographically-secure method
according to 
@geindex RFC; RFC 9562 Section 5.4
RFC 9562@comma{} §5.4@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html#section-5.4}.
@end deffn

@geindex uuid5() (στη μονάδα uuid)
@anchor{library/uuid uuid uuid5}@anchor{562}
@deffn {Συνάρτηση} 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{1c7,,bytes} object or a string
that will be encoded using UTF-8)
according to 
@geindex RFC; RFC 9562 Section 5.5
RFC 9562@comma{} §5.5@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html#section-5.5}.
@end deffn

@geindex uuid6() (στη μονάδα uuid)
@anchor{library/uuid uuid uuid6}@anchor{53e}
@deffn {Συνάρτηση} uuid.uuid6 (node=None, clock_seq=None)

Generate a UUID from a sequence number and the current time according to
@geindex RFC; RFC 9562 Section 5.6
RFC 9562@comma{} §5.6@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html#section-5.6}.

This is an alternative to @ref{f67,,uuid1()} to improve database locality.

When `node' is not specified, @ref{f66,,getnode()} is used to obtain the hardware
address as a 48-bit positive integer. When a sequence number `clock_seq' is
not specified, a pseudo-random 14-bit positive integer is generated.

If `node' or `clock_seq' exceed their expected bit count,
only their least significant bits are kept.


Added in version 3.14.

@end deffn

@geindex uuid7() (στη μονάδα uuid)
@anchor{library/uuid uuid uuid7}@anchor{53f}
@deffn {Συνάρτηση} uuid.uuid7 ()

Generate a time-based UUID according to
@geindex RFC; RFC 9562 Section 5.7
RFC 9562@comma{} §5.7@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html#section-5.7}.

For portability across platforms lacking sub-millisecond precision, UUIDs
produced by this function embed a 48-bit timestamp and use a 42-bit counter
to guarantee monotonicity within a millisecond.


Added in version 3.14.

@end deffn

@geindex uuid8() (στη μονάδα uuid)
@anchor{library/uuid uuid uuid8}@anchor{540}
@deffn {Συνάρτηση} uuid.uuid8 (a=None, b=None, c=None)

Generate a pseudo-random UUID according to
@geindex RFC; RFC 9562 Section 5.8
RFC 9562@comma{} §5.8@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html#section-5.8}.

When specified, the parameters `a', `b' and `c' are expected to be
positive integers of 48, 12 and 62 bits respectively. If they exceed
their expected bit count, only their least significant bits are kept;
non-specified arguments are substituted for a pseudo-random integer of
appropriate size.

By default, `a', `b' and `c' are not generated by a cryptographically
secure pseudo-random number generator (CSPRNG). Use @ref{563,,uuid4()} when
a UUID needs to be used in a security-sensitive context.


Added in version 3.14.

@end deffn

The @code{uuid} module defines the following namespace identifiers for use with
@ref{561,,uuid3()} or @ref{562,,uuid5()}.

@geindex NAMESPACE_DNS (στη μονάδα uuid)
@anchor{library/uuid uuid NAMESPACE_DNS}@anchor{42f0}
@deffn {Δεδομένα} uuid.NAMESPACE_DNS

When this namespace is specified, the `name' string is a fully qualified domain
name.
@end deffn

@geindex NAMESPACE_URL (στη μονάδα uuid)
@anchor{library/uuid uuid NAMESPACE_URL}@anchor{42f1}
@deffn {Δεδομένα} uuid.NAMESPACE_URL

When this namespace is specified, the `name' string is a URL.
@end deffn

@geindex NAMESPACE_OID (στη μονάδα uuid)
@anchor{library/uuid uuid NAMESPACE_OID}@anchor{42f2}
@deffn {Δεδομένα} uuid.NAMESPACE_OID

When this namespace is specified, the `name' string is an ISO OID.
@end deffn

@geindex NAMESPACE_X500 (στη μονάδα uuid)
@anchor{library/uuid uuid NAMESPACE_X500}@anchor{42f3}
@deffn {Δεδομένα} uuid.NAMESPACE_X500

When this namespace is specified, the `name' string is an X.500 DN in DER or a
text output format.
@end deffn

The @code{uuid} module defines the following constants for the possible values
of the @ref{42ea,,variant} attribute:

@geindex RESERVED_NCS (στη μονάδα uuid)
@anchor{library/uuid uuid RESERVED_NCS}@anchor{42eb}
@deffn {Δεδομένα} uuid.RESERVED_NCS

Reserved for NCS compatibility.
@end deffn

@geindex RFC_4122 (στη μονάδα uuid)
@anchor{library/uuid uuid RFC_4122}@anchor{42ec}
@deffn {Δεδομένα} uuid.RFC_4122

Specifies the UUID layout given in 
@geindex RFC; RFC 4122
RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html}. This constant is kept
for backward compatibility even though 
@geindex RFC; RFC 4122
RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html} has been superseded
by 
@geindex RFC; RFC 9562
RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html}.
@end deffn

@geindex RESERVED_MICROSOFT (στη μονάδα uuid)
@anchor{library/uuid uuid RESERVED_MICROSOFT}@anchor{42ed}
@deffn {Δεδομένα} uuid.RESERVED_MICROSOFT

Reserved for Microsoft compatibility.
@end deffn

@geindex RESERVED_FUTURE (στη μονάδα uuid)
@anchor{library/uuid uuid RESERVED_FUTURE}@anchor{42ee}
@deffn {Δεδομένα} uuid.RESERVED_FUTURE

Reserved for future definition.
@end deffn

The @code{uuid} module defines the special Nil and Max UUID values:

@geindex NIL (στη μονάδα uuid)
@anchor{library/uuid uuid NIL}@anchor{541}
@deffn {Δεδομένα} uuid.NIL

A special form of UUID that is specified to have all 128 bits set to zero
according to 
@geindex RFC; RFC 9562 Section 5.9
RFC 9562@comma{} §5.9@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html#section-5.9}.


Added in version 3.14.

@end deffn

@geindex MAX (στη μονάδα uuid)
@anchor{library/uuid uuid MAX}@anchor{542}
@deffn {Δεδομένα} uuid.MAX

A special form of UUID that is specified to have all 128 bits set to one
according to 
@geindex RFC; RFC 9562 Section 5.10
RFC 9562@comma{} §5.10@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html#section-5.10}.


Added in version 3.14.

@end deffn


@subsubheading Δείτε επίσης



@table @asis

@geindex RFC; RFC 9562

@item RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html} - A Universally Unique IDentifier (UUID) URN Namespace

This specification defines a Uniform Resource Name namespace for UUIDs, the
internal format of UUIDs, and methods of generating UUIDs.
@end table


@menu
* Command-Line Usage:: 
* Example: Example<10>. 
* Command-Line Example:: 

@end menu

@node Command-Line Usage,Example<10>,,uuid — UUID objects according to RFC 9562
@anchor{library/uuid command-line-usage}@anchor{42f4}@anchor{library/uuid uuid-cli}@anchor{862}
@subsubsection Command-Line Usage



Added in version 3.12.


The @code{uuid} module can be executed as a script from the command line.

@example
python -m uuid [-h] [-u @{uuid1,uuid3,uuid4,uuid5,uuid6,uuid7,uuid8@}] [-n NAMESPACE] [-N NAME]
@end example

The following options are accepted:

@geindex uuid command line option; -h
@geindex uuid command line option; --help
@anchor{library/uuid cmdoption-uuid-h}@anchor{42f5}@anchor{library/uuid cmdoption-uuid-help}@anchor{42f6}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Show the help message and exit.
@end deffn

@geindex uuid command line option; -u
@geindex uuid command line option; --uuid
@anchor{library/uuid cmdoption-uuid-u}@anchor{42f7}
@deffn {Option} @w{-}u <uuid>
@anchor{library/uuid cmdoption-uuid-uuid}@anchor{42f8}
@deffnx {Option} @w{-}@w{-}uuid <uuid>

Specify the function name to use to generate the uuid. By default @ref{563,,uuid4()}
is used.


Άλλαξε στην έκδοση 3.14: Allow generating UUID versions 6, 7 and 8.

@end deffn

@geindex uuid command line option; -n
@geindex uuid command line option; --namespace
@anchor{library/uuid cmdoption-uuid-n}@anchor{42f9}
@deffn {Option} @w{-}n <namespace>
@anchor{library/uuid cmdoption-uuid-namespace}@anchor{42fa}
@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{561,,uuid3()} / @ref{562,,uuid5()} functions.
@end deffn

@geindex uuid command line option; -N
@geindex uuid command line option; --name
@anchor{library/uuid cmdoption-uuid-N}@anchor{42fb}
@deffn {Option} @w{-}N <name>
@anchor{library/uuid cmdoption-uuid-name}@anchor{42fc}
@deffnx {Option} @w{-}@w{-}name <name>

The name used as part of generating the uuid. Only required for
@ref{561,,uuid3()} / @ref{562,,uuid5()} functions.
@end deffn

@geindex uuid command line option; -C
@geindex uuid command line option; --count
@anchor{library/uuid cmdoption-uuid-C}@anchor{42fd}
@deffn {Option} @w{-}C <num>
@anchor{library/uuid cmdoption-uuid-count}@anchor{543}
@deffnx {Option} @w{-}@w{-}count <num>

Generate `num' fresh UUIDs.


Added in version 3.14.

@end deffn

@node Example<10>,Command-Line Example,Command-Line Usage,uuid — UUID objects according to RFC 9562
@anchor{library/uuid example}@anchor{42fe}@anchor{library/uuid uuid-example}@anchor{42ff}
@subsubsection Example


Here are some examples of typical usage of the @code{uuid} 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')

>>> # 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')

>>> # get the Nil UUID
>>> uuid.NIL
UUID('00000000-0000-0000-0000-000000000000')

>>> # get the Max UUID
>>> uuid.MAX
UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')

>>> # same as UUIDv1 but with fields reordered to improve DB locality
>>> uuid.uuid6()
UUID('1f0799c0-98b9-62db-92c6-a0d365b91053')

>>> # get UUIDv7 creation (local) time as a timestamp in milliseconds
>>> u = uuid.uuid7()
>>> u.time
1743936859822

>>> # get UUIDv7 creation (local) time as a datetime object
>>> import datetime as dt
>>> dt.datetime.fromtimestamp(u.time / 1000)
datetime.datetime(...)

>>> # make a UUID with custom blocks
>>> uuid.uuid8(0x12345678, 0x9abcdef0, 0x11223344)
UUID('00001234-5678-8ef0-8000-000011223344')
@end example

@node Command-Line Example,,Example<10>,uuid — UUID objects according to RFC 9562
@anchor{library/uuid command-line-example}@anchor{4300}@anchor{library/uuid uuid-cli-example}@anchor{4301}
@subsubsection Command-Line Example


Here are some examples of typical usage of the @code{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

# generate 42 random UUIDs
$ python -m uuid -C 42
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node socketserver — A framework for network servers,http server — HTTP servers,uuid — UUID objects according to RFC 9562,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/socketserver doc}@anchor{4302}@anchor{library/socketserver module-socketserver}@anchor{d5}@anchor{library/socketserver socketserver-a-framework-for-network-servers}@anchor{4303}@anchor{library/socketserver translation-repo}@anchor{4304}
@subsection @code{socketserver} — A framework for network servers


@geindex module; socketserver

`Source code:' Lib/socketserver.py@footnote{https://github.com/python/cpython/tree/main/Lib/socketserver.py}


__________________________________________________________________


The @code{socketserver} module simplifies the task of writing network servers.

@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

There are four basic concrete server classes:

@geindex TCPServer (κλάση σε socketserver)
@anchor{library/socketserver socketserver TCPServer}@anchor{16c4}
@deffn {Κλάση} socketserver.TCPServer (server_address, RequestHandlerClass, bind_and_activate=True)

This uses the internet TCP protocol, which provides for
continuous streams of data between the client and server.
If `bind_and_activate' is true, the constructor automatically attempts to
invoke @ref{4305,,server_bind()} and
@ref{4306,,server_activate()}.  The other parameters are passed to
the @ref{14e9,,BaseServer} base class.


Άλλαξε στην έκδοση 3.15: The default queue size is now @code{socket.SOMAXCONN} for @ref{16c4,,socketserver.TCPServer}.

@end deffn

@geindex UDPServer (κλάση σε socketserver)
@anchor{library/socketserver socketserver UDPServer}@anchor{4307}
@deffn {Κλάση} socketserver.UDPServer (server_address, RequestHandlerClass, bind_and_activate=True)

This uses datagrams, which are discrete packets of information that may
arrive out of order or be lost while in transit.  The parameters are
the same as for @ref{16c4,,TCPServer}.
@end deffn

@geindex UnixStreamServer (κλάση σε socketserver)
@geindex UnixDatagramServer (κλάση σε socketserver)
@anchor{library/socketserver socketserver UnixStreamServer}@anchor{4308}
@deffn {Κλάση} socketserver.UnixStreamServer (server_address, RequestHandlerClass, bind_and_activate=True)
@anchor{library/socketserver socketserver UnixDatagramServer}@anchor{4309}
@deffnx {Κλάση} socketserver.UnixDatagramServer (server_address, RequestHandlerClass, bind_and_activate=True)

These more infrequently used classes are similar to the TCP and
UDP classes, but use Unix domain sockets; they’re not available on
non-Unix platforms.  The parameters are the same as for
@ref{16c4,,TCPServer}.
@end deffn

These four classes process requests `synchronously'; each request must be
completed before the next request can be started.  This isn’t suitable if each
request takes a long time to complete, because it requires a lot of computation,
or because it returns a lot of data which the client is slow to process.  The
solution is to create a separate process or thread to handle each request; the
@ref{f37,,ForkingMixIn} and @ref{f01,,ThreadingMixIn} mix-in classes can be used to
support asynchronous behaviour.

Creating a server requires several steps.  First, you must create a request
handler class by subclassing the @ref{430a,,BaseRequestHandler} class and
overriding its @ref{430b,,handle()} method;
this method will process incoming
requests.  Second, you must instantiate one of the server classes, passing it
the server’s address and the request handler class. It is recommended to use
the server in a @ref{20a,,with} statement. Then call the
@ref{16c7,,handle_request()} or
@ref{14eb,,serve_forever()} method of the server object to
process one or many requests.  Finally, call @ref{f35,,server_close()}
to close the socket (unless you used a @code{with} statement).

When inheriting from @ref{f01,,ThreadingMixIn} for threaded connection behavior,
you should explicitly declare how you want your threads to behave on an abrupt
shutdown.  The @code{ThreadingMixIn} class defines an attribute
`daemon_threads', which indicates whether or not the server should wait for
thread termination.  You should set the flag explicitly if you would like
threads to behave autonomously; the default is @ref{ef5,,False}, meaning that
Python will not exit until all threads created by @code{ThreadingMixIn} have
exited.

Server classes have the same external methods and attributes, no matter what
network protocol they use.

@menu
* Server Creation Notes:: 
* Server Objects:: 
* Request Handler Objects:: 
* Examples: Examples<25>. 

@end menu

@node Server Creation Notes,Server Objects,,socketserver — A framework for network servers
@anchor{library/socketserver server-creation-notes}@anchor{430c}
@subsubsection Server Creation Notes


There are five classes in an inheritance diagram, four of which represent
synchronous servers of four types:

@example
+------------+
| BaseServer |
+------------+
      |
      v
+-----------+        +------------------+
| TCPServer |------->| UnixStreamServer |
+-----------+        +------------------+
      |
      v
+-----------+        +--------------------+
| UDPServer |------->| UnixDatagramServer |
+-----------+        +--------------------+
@end example

Note that @ref{4309,,UnixDatagramServer} derives from @ref{4307,,UDPServer}, not from
@ref{4308,,UnixStreamServer} — the only difference between an IP and a Unix
server is the address family.

@geindex ForkingMixIn (κλάση σε socketserver)
@geindex ThreadingMixIn (κλάση σε socketserver)
@anchor{library/socketserver socketserver ForkingMixIn}@anchor{f37}
@deffn {Κλάση} socketserver.ForkingMixIn
@anchor{library/socketserver socketserver ThreadingMixIn}@anchor{f01}
@deffnx {Κλάση} socketserver.ThreadingMixIn

Forking and threading versions of each type of server can be created
using these mix-in classes.  For instance, @ref{430d,,ThreadingUDPServer}
is created as follows:

@example
class ThreadingUDPServer(ThreadingMixIn, UDPServer):
    pass
@end example

The mix-in class comes first, since it overrides a method defined in
@ref{4307,,UDPServer}.  Setting the various attributes also changes the
behavior of the underlying server mechanism.

@code{ForkingMixIn} and the Forking classes mentioned below are
only available on POSIX platforms that support @ref{6bd,,fork()}.

@geindex block_on_close (ιδιότητα της socketserver.ThreadingMixIn)
@anchor{library/socketserver socketserver ThreadingMixIn block_on_close}@anchor{f36}
@deffn {Ιδιότητα} block_on_close

@ref{f35,,ForkingMixIn.server_close}
waits until all child processes complete, except if
@ref{f36,,block_on_close} attribute is @code{False}.

@ref{f35,,ThreadingMixIn.server_close}
waits until all non-daemon threads complete, except if
@ref{f36,,block_on_close} attribute is @code{False}.
@end deffn

@geindex max_children (ιδιότητα της socketserver.ThreadingMixIn)
@anchor{library/socketserver socketserver ThreadingMixIn max_children}@anchor{430e}
@deffn {Ιδιότητα} max_children

Specify how many child processes will exist to handle requests at a time
for @code{ForkingMixIn}.  If the limit is reached,
new requests will wait until one child process has finished.
@end deffn

@geindex daemon_threads (ιδιότητα της socketserver.ThreadingMixIn)
@anchor{library/socketserver socketserver ThreadingMixIn daemon_threads}@anchor{430f}
@deffn {Ιδιότητα} daemon_threads

For @code{ThreadingMixIn} use daemonic threads by setting
@ref{430f,,ThreadingMixIn.daemon_threads}
to @code{True} to not wait until threads complete.
@end deffn


Άλλαξε στην έκδοση 3.7: @ref{f35,,ForkingMixIn.server_close} and
@code{ThreadingMixIn.server_close} now waits until all
child processes and non-daemonic threads complete.
Add a new @ref{f36,,ForkingMixIn.block_on_close} class
attribute to opt-in for the pre-3.7 behaviour.

@end deffn

@geindex ForkingTCPServer (κλάση σε socketserver)
@geindex ForkingUDPServer (κλάση σε socketserver)
@geindex ThreadingTCPServer (κλάση σε socketserver)
@geindex ThreadingUDPServer (κλάση σε socketserver)
@geindex ForkingUnixStreamServer (κλάση σε socketserver)
@geindex ForkingUnixDatagramServer (κλάση σε socketserver)
@geindex ThreadingUnixStreamServer (κλάση σε socketserver)
@geindex ThreadingUnixDatagramServer (κλάση σε socketserver)
@anchor{library/socketserver socketserver ForkingTCPServer}@anchor{4310}
@deffn {Κλάση} socketserver.ForkingTCPServer
@anchor{library/socketserver socketserver ForkingUDPServer}@anchor{4311}
@deffnx {Κλάση} socketserver.ForkingUDPServer
@anchor{library/socketserver socketserver ThreadingTCPServer}@anchor{4312}
@deffnx {Κλάση} socketserver.ThreadingTCPServer
@anchor{library/socketserver socketserver ThreadingUDPServer}@anchor{430d}
@deffnx {Κλάση} socketserver.ThreadingUDPServer
@anchor{library/socketserver socketserver ForkingUnixStreamServer}@anchor{4313}
@deffnx {Κλάση} socketserver.ForkingUnixStreamServer
@anchor{library/socketserver socketserver ForkingUnixDatagramServer}@anchor{4314}
@deffnx {Κλάση} socketserver.ForkingUnixDatagramServer
@anchor{library/socketserver socketserver ThreadingUnixStreamServer}@anchor{4315}
@deffnx {Κλάση} socketserver.ThreadingUnixStreamServer
@anchor{library/socketserver socketserver ThreadingUnixDatagramServer}@anchor{4316}
@deffnx {Κλάση} socketserver.ThreadingUnixDatagramServer

These classes are pre-defined using the mix-in classes.
@end deffn


Added in version 3.12: The @code{ForkingUnixStreamServer} and @code{ForkingUnixDatagramServer} classes
were added.


To implement a service, you must derive a class from @ref{430a,,BaseRequestHandler}
and redefine its @ref{430b,,handle()} method.
You can then run various versions of
the service by combining one of the server classes with your request handler
class.  The request handler class must be different for datagram or stream
services.  This can be hidden by using the handler subclasses
@ref{1098,,StreamRequestHandler} or @ref{4317,,DatagramRequestHandler}.

Of course, you still have to use your head!  For instance, it makes no sense to
use a forking server if the service contains state in memory that can be
modified by different requests, since the modifications in the child process
would never reach the initial state kept in the parent process and passed to
each child.  In this case, you can use a threading server, but you will probably
have to use locks to protect the integrity of the shared data.

On the other hand, if you are building an HTTP server where all data is stored
externally (for instance, in the file system), a synchronous class will
essentially render the service «deaf» while one request is being handled –
which may be for a very long time if a client is slow to receive all the data it
has requested.  Here a threading or forking server is appropriate.

In some cases, it may be appropriate to process part of a request synchronously,
but to finish processing in a forked child depending on the request data.  This
can be implemented by using a synchronous server and doing an explicit fork in
the request handler class @ref{430b,,handle()} method.

Another approach to handling multiple simultaneous requests in an environment
that supports neither threads nor @ref{6bd,,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{ca,,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 Server Objects,Request Handler Objects,Server Creation Notes,socketserver — A framework for network servers
@anchor{library/socketserver server-objects}@anchor{4318}
@subsubsection Server Objects


@geindex BaseServer (κλάση σε socketserver)
@anchor{library/socketserver socketserver BaseServer}@anchor{14e9}
@deffn {Κλάση} socketserver.BaseServer (server_address, RequestHandlerClass)

This is the superclass of all Server objects in the module.  It defines the
interface, given below, but does not implement most of the methods, which is
done in subclasses.  The two parameters are stored in the respective
@ref{4319,,server_address} and @ref{431a,,RequestHandlerClass} attributes.

@geindex fileno() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer fileno}@anchor{431b}
@deffn {Μέθοδος} fileno ()

Return an integer file descriptor for the socket on which the server is
listening.  This function is most commonly passed to @ref{ca,,selectors}, to
allow monitoring multiple servers in the same process.
@end deffn

@geindex handle_request() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer handle_request}@anchor{16c7}
@deffn {Μέθοδος} handle_request ()

Process a single request.  This function calls the following methods in
order: @ref{431c,,get_request()}, @ref{431d,,verify_request()}, and
@ref{431e,,process_request()}.  If the user-provided
@ref{430b,,handle()} method of the
handler class raises an exception, the server’s @ref{10f8,,handle_error()} method
will be called.  If no request is received within @ref{16c5,,timeout}
seconds, @ref{16c6,,handle_timeout()} will be called and @code{handle_request()}
will return.
@end deffn

@geindex serve_forever() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer serve_forever}@anchor{14eb}
@deffn {Μέθοδος} serve_forever (poll_interval=0.5)

Handle requests until an explicit @ref{2004,,shutdown()} request.  Poll for
shutdown every `poll_interval' seconds.
Ignores the @ref{16c5,,timeout} attribute.  It
also calls @ref{14ea,,service_actions()}, which may be used by a subclass or mixin
to provide actions specific to a given service.  For example, the
@ref{f37,,ForkingMixIn} class uses @code{service_actions()} to clean up zombie
child processes.


Άλλαξε στην έκδοση 3.3: Added @code{service_actions} call to the @code{serve_forever} method.

@end deffn

@geindex service_actions() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer service_actions}@anchor{14ea}
@deffn {Μέθοδος} service_actions ()

This is called in the @ref{14eb,,serve_forever()} loop. This method can be
overridden by subclasses or mixin classes to perform actions specific to
a given service, such as cleanup actions.


Added in version 3.3.

@end deffn

@geindex shutdown() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer shutdown}@anchor{2004}
@deffn {Μέθοδος} shutdown ()

Tell the @ref{14eb,,serve_forever()} loop to stop and wait until it does.
@code{shutdown()} must be called while @code{serve_forever()} is running in a
different thread otherwise it will deadlock.
@end deffn

@geindex server_close() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer server_close}@anchor{f35}
@deffn {Μέθοδος} server_close ()

Clean up the server. May be overridden.
@end deffn

@geindex address_family (ιδιότητα της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer address_family}@anchor{431f}
@deffn {Ιδιότητα} address_family

The family of protocols to which the server’s socket belongs.  Common
examples are @ref{1da7,,socket.AF_INET}, @ref{1da8,,socket.AF_INET6}, and
@ref{1daa,,socket.AF_UNIX}.  Subclass the TCP or UDP server classes in this
module with class attribute @code{address_family = AF_INET6} set if you
want IPv6 server classes.
@end deffn

@geindex RequestHandlerClass (ιδιότητα της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer RequestHandlerClass}@anchor{431a}
@deffn {Ιδιότητα} RequestHandlerClass

The user-provided request handler class; an instance of this class is created
for each request.
@end deffn

@geindex server_address (ιδιότητα της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer server_address}@anchor{4319}
@deffn {Ιδιότητα} server_address

The address on which the server is listening.  The format of addresses varies
depending on the protocol family;
see the documentation for the @ref{d4,,socket} module
for details.  For internet protocols, this is a tuple containing a string giving
the address, and an integer port number: @code{('127.0.0.1', 80)}, for example.
@end deffn

@geindex socket (ιδιότητα της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer socket}@anchor{4320}
@deffn {Ιδιότητα} socket

The socket object on which the server will listen for incoming requests.
@end deffn

The server classes support the following class variables:

@c XXX should class variables be covered before instance variables, or vice versa?

@geindex allow_reuse_address (ιδιότητα της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer allow_reuse_address}@anchor{4321}
@deffn {Ιδιότητα} allow_reuse_address

Whether the server will allow the reuse of an address.  This defaults to
@ref{ef5,,False}, and can be set in subclasses to change the policy.
@end deffn

@geindex request_queue_size (ιδιότητα της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer request_queue_size}@anchor{4322}
@deffn {Ιδιότητα} request_queue_size

The size of the request queue.  If it takes a long time to process a single
request, any requests that arrive while the server is busy are placed into a
queue, up to @ref{4322,,request_queue_size} requests.  Once the queue is full,
further requests from clients will get a «Connection denied» error.  The default
value is usually 5, but this can be overridden by subclasses.
@end deffn

@geindex socket_type (ιδιότητα της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer socket_type}@anchor{4323}
@deffn {Ιδιότητα} socket_type

The type of socket used by the server; @ref{1698,,socket.SOCK_STREAM} and
@ref{1697,,socket.SOCK_DGRAM} are two common values.
@end deffn

@geindex timeout (ιδιότητα της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer timeout}@anchor{16c5}
@deffn {Ιδιότητα} timeout

Timeout duration, measured in seconds, or @ref{a65,,None} if no timeout is
desired.  If @ref{16c7,,handle_request()} receives no incoming requests within the
timeout period, the @ref{16c6,,handle_timeout()} method is called.
@end deffn

There are various server methods that can be overridden by subclasses of base
server classes like @ref{16c4,,TCPServer}; these methods aren’t useful to external
users of the server object.

@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() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer finish_request}@anchor{4324}
@deffn {Μέθοδος} finish_request (request, client_address)

Actually processes the request by instantiating @ref{431a,,RequestHandlerClass} and
calling its @ref{430b,,handle()} method.
@end deffn

@geindex get_request() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer get_request}@anchor{431c}
@deffn {Μέθοδος} get_request ()

Must accept a request from the socket, and return a 2-tuple containing the `new'
socket object to be used to communicate with the client, and the client’s
address.
@end deffn

@geindex handle_error() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer handle_error}@anchor{10f8}
@deffn {Μέθοδος} handle_error (request, client_address)

This function is called if the @ref{430b,,handle()}
method of a @ref{431a,,RequestHandlerClass} instance raises
an exception.  The default action is to print the traceback to
standard error and continue handling further requests.


Άλλαξε στην έκδοση 3.6: Now only called for exceptions derived from the @ref{d9e,,Exception}
class.

@end deffn

@geindex handle_timeout() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer handle_timeout}@anchor{16c6}
@deffn {Μέθοδος} handle_timeout ()

This function is called when the @ref{16c5,,timeout} attribute has been set to a
value other than @ref{a65,,None} and the timeout period has passed with no
requests being received.  The default action for forking servers is
to collect the status of any child processes that have exited, while
in threading servers this method does nothing.
@end deffn

@geindex process_request() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer process_request}@anchor{431e}
@deffn {Μέθοδος} process_request (request, client_address)

Calls @ref{4324,,finish_request()} to create an instance of the
@ref{431a,,RequestHandlerClass}.  If desired, this function can create a new process
or thread to handle the request; the @ref{f37,,ForkingMixIn} and
@ref{f01,,ThreadingMixIn} classes do this.
@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() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer server_activate}@anchor{4306}
@deffn {Μέθοδος} server_activate ()

Called by the server’s constructor to activate the server.  The default behavior
for a TCP server just invokes @ref{120f,,listen()}
on the server’s socket.  May be overridden.
@end deffn

@geindex server_bind() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer server_bind}@anchor{4305}
@deffn {Μέθοδος} server_bind ()

Called by the server’s constructor to bind the socket to the desired address.
May be overridden.
@end deffn

@geindex verify_request() (μέθοδος της socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer verify_request}@anchor{431d}
@deffn {Μέθοδος} verify_request (request, client_address)

Must return a Boolean value; if the value is @ref{fcc,,True}, the request will
be processed, and if it’s @ref{ef5,,False}, the request will be denied.  This
function can be overridden to implement access controls for a server. The
default implementation always returns @code{True}.
@end deffn


Άλλαξε στην έκδοση 3.6: Support for the @ref{478,,context manager} protocol was added.  Exiting the
context manager is equivalent to calling @ref{f35,,server_close()}.

@end deffn

@node Request Handler Objects,Examples<25>,Server Objects,socketserver — A framework for network servers
@anchor{library/socketserver request-handler-objects}@anchor{4325}
@subsubsection Request Handler Objects


@geindex BaseRequestHandler (κλάση σε socketserver)
@anchor{library/socketserver socketserver BaseRequestHandler}@anchor{430a}
@deffn {Κλάση} socketserver.BaseRequestHandler

This is the superclass of all request handler objects.  It defines
the interface, given below.  A concrete request handler subclass must
define a new @ref{430b,,handle()} method, and can override any of
the other methods.  A new instance of the subclass is created for each
request.

@geindex setup() (μέθοδος της socketserver.BaseRequestHandler)
@anchor{library/socketserver socketserver BaseRequestHandler setup}@anchor{4326}
@deffn {Μέθοδος} setup ()

Called before the @ref{430b,,handle()} method to perform any initialization actions
required.  The default implementation does nothing.
@end deffn

@geindex handle() (μέθοδος της socketserver.BaseRequestHandler)
@anchor{library/socketserver socketserver BaseRequestHandler handle}@anchor{430b}
@deffn {Μέθοδος} 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{4327,,request}; the client
address as @ref{4328,,client_address}; and the server instance as
@ref{4329,,server}, in case it needs access to per-server information.

The type of @ref{4327,,request} is different for datagram or stream
services.  For stream services, @code{request} is a socket object; for
datagram services, @code{request} is a pair of string and socket.
@end deffn

@geindex finish() (μέθοδος της socketserver.BaseRequestHandler)
@anchor{library/socketserver socketserver BaseRequestHandler finish}@anchor{432a}
@deffn {Μέθοδος} finish ()

Called after the @ref{430b,,handle()} method to perform any clean-up actions
required.  The default implementation does nothing.  If @ref{4326,,setup()}
raises an exception, this function will not be called.
@end deffn

@geindex request (ιδιότητα της socketserver.BaseRequestHandler)
@anchor{library/socketserver socketserver BaseRequestHandler request}@anchor{4327}
@deffn {Ιδιότητα} request

The `new' @ref{115a,,socket.socket} object
to be used to communicate with the client.
@end deffn

@geindex client_address (ιδιότητα της socketserver.BaseRequestHandler)
@anchor{library/socketserver socketserver BaseRequestHandler client_address}@anchor{4328}
@deffn {Ιδιότητα} client_address

Client address returned by @ref{431c,,BaseServer.get_request()}.
@end deffn

@geindex server (ιδιότητα της socketserver.BaseRequestHandler)
@anchor{library/socketserver socketserver BaseRequestHandler server}@anchor{4329}
@deffn {Ιδιότητα} server

@ref{14e9,,BaseServer} object used for handling the request.
@end deffn
@end deffn

@geindex StreamRequestHandler (κλάση σε socketserver)
@geindex DatagramRequestHandler (κλάση σε socketserver)
@anchor{library/socketserver socketserver StreamRequestHandler}@anchor{1098}
@deffn {Κλάση} socketserver.StreamRequestHandler
@anchor{library/socketserver socketserver DatagramRequestHandler}@anchor{4317}
@deffnx {Κλάση} socketserver.DatagramRequestHandler

These @ref{430a,,BaseRequestHandler} subclasses override the
@ref{4326,,setup()} and @ref{432a,,finish()}
methods, and provide @ref{432b,,rfile} and @ref{1097,,wfile} attributes.

@geindex rfile (ιδιότητα της socketserver.DatagramRequestHandler)
@anchor{library/socketserver socketserver DatagramRequestHandler rfile}@anchor{432b}
@deffn {Ιδιότητα} rfile

A file object from which receives the request is read.
Support the @ref{a83,,io.BufferedIOBase} readable interface.
@end deffn

@geindex wfile (ιδιότητα της socketserver.DatagramRequestHandler)
@anchor{library/socketserver socketserver DatagramRequestHandler wfile}@anchor{1097}
@deffn {Ιδιότητα} wfile

A file object to which the reply is written.
Support the @ref{a83,,io.BufferedIOBase} writable interface
@end deffn


Άλλαξε στην έκδοση 3.6: @ref{1097,,wfile} also supports the
@ref{a83,,io.BufferedIOBase} writable interface.

@end deffn

@node Examples<25>,,Request Handler Objects,socketserver — A framework for network servers
@anchor{library/socketserver examples}@anchor{432c}
@subsubsection Examples


@menu
* socketserver.TCPServer Example: socketserver TCPServer Example. 
* socketserver.UDPServer Example: socketserver UDPServer Example. 
* Asynchronous Mixins:: 

@end menu

@node socketserver TCPServer Example,socketserver UDPServer Example,,Examples<25>
@anchor{library/socketserver socketserver-tcpserver-example}@anchor{432d}
@subsubsection @code{socketserver.TCPServer} Example


This is the server side:

@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
        pieces = [b'@w{'}]
        total = 0
        while b'\n' not in pieces[-1] and total < 10_000:
            pieces.append(self.request.recv(2000))
            total += len(pieces[-1])
        self.data = b'@w{'}.join(pieces)
        print(f"Received from @{self.client_address[0]@}:")
        print(self.data.decode("utf-8"))
        # just send back the same data, but upper-cased
        self.request.sendall(self.data.upper())
        # after we return, the socket will be closed.

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

An alternative request handler class that makes use of streams (file-like
objects that simplify communication by providing the standard file interface):

@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.
        # We limit ourselves to 10000 bytes to avoid abuse by the sender.
        self.data = self.rfile.readline(10000).rstrip()
        print(f"@{self.client_address[0]@} wrote:")
        print(self.data.decode("utf-8"))
        # 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
first handler had to use a @code{recv()} loop to accumulate data until a
newline itself.  If it had just used a single @code{recv()} without the loop it
would just have returned what has been received so far from the client.
TCP is stream based: data arrives in the order it was sent, but there is no
correlation between client @code{send()} or @code{sendall()} calls and the number
of @code{recv()} calls on the server required to receive it.

This is the client side:

@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, "utf-8"))
    sock.sendall(b"\n")

    # Receive data from the server and shut down
    received = str(sock.recv(1024), "utf-8")

print("Sent:    ", data)
print("Received:", received)
@end example

The output of the example should look something like this:

Server:

@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 socketserver UDPServer Example,Asynchronous Mixins,socketserver TCPServer Example,Examples<25>
@anchor{library/socketserver socketserver-udpserver-example}@anchor{432e}
@subsubsection @code{socketserver.UDPServer} Example


This is the server side:

@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(f"@{self.client_address[0]@} wrote:")
        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

This is the client side:

@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:    ", data)
print("Received:", received)
@end example

The output of the example should look exactly like for the TCP server example.

@node Asynchronous Mixins,,socketserver UDPServer Example,Examples<25>
@anchor{library/socketserver asynchronous-mixins}@anchor{432f}
@subsubsection Asynchronous Mixins


To build asynchronous handlers, use the @ref{f01,,ThreadingMixIn} and
@ref{f37,,ForkingMixIn} classes.

An example for the @ref{f01,,ThreadingMixIn} class:

@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

The output of the example should look something like this:

@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

The @ref{f37,,ForkingMixIn} class is used in the same way, except that the server
will spawn a new process for each request.
Available only on POSIX platforms that support @ref{6bd,,fork()}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node http server — HTTP servers,http cookies — HTTP state management,socketserver — A framework for network servers,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/http server doc}@anchor{4330}@anchor{library/http server http-server-http-servers}@anchor{4331}@anchor{library/http server module-http server}@anchor{75}@anchor{library/http server translation-repo}@anchor{4332}
@subsection @code{http.server} — HTTP servers


@geindex module; http.server

`Source code:' Lib/http/server.py@footnote{https://github.com/python/cpython/tree/main/Lib/http/server.py}

@geindex WWW;server
@geindex HTTP;protocol
@geindex URL
@geindex httpd


__________________________________________________________________


This module defines classes for implementing HTTP servers.

@cartouche
@quotation Προειδοποίηση 
@code{http.server} is not recommended for production. It only implements
@ref{4333,,basic security checks}.
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

One class, @ref{412f,,HTTPServer}, is a @ref{16c4,,socketserver.TCPServer} subclass.
It creates and listens at the HTTP socket, dispatching the requests to a
handler.  Code to create and run the server looks like this:

@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 (κλάση σε http.server)
@anchor{library/http server http server HTTPServer}@anchor{412f}
@deffn {Κλάση} http.server.HTTPServer (server_address, RequestHandlerClass)

This class builds on the @ref{16c4,,TCPServer} class by storing
the server address as instance variables named @code{server_name} and
@code{server_port}. The server is accessible by the handler, typically
through the handler’s @code{server} instance variable.
@end deffn

@geindex ThreadingHTTPServer (κλάση σε http.server)
@anchor{library/http server http server ThreadingHTTPServer}@anchor{f00}
@deffn {Κλάση} http.server.ThreadingHTTPServer (server_address, RequestHandlerClass)

This class is identical to HTTPServer but uses threads to handle
requests by using the @ref{f01,,ThreadingMixIn}. This
is useful to handle web browsers pre-opening sockets, on which
@ref{412f,,HTTPServer} would wait indefinitely.


Added in version 3.7.

@end deffn

@geindex HTTPSServer (κλάση σε http.server)
@anchor{library/http server http server HTTPSServer}@anchor{4b6}
@deffn {Κλάση} http.server.HTTPSServer (server_address, RequestHandlerClass, bind_and_activate=True, *, certfile, keyfile=None, password=None, alpn_protocols=None)

Subclass of @ref{412f,,HTTPServer} with a wrapped socket using the @ref{d8,,ssl} module.
If the @code{ssl} module is not available, instantiating a @code{HTTPSServer}
object fails with a @ref{30d,,RuntimeError}.

The `certfile' argument is the path to the SSL certificate chain file,
and the `keyfile' is the path to file containing the private key.

A `password' can be specified for files protected and wrapped with PKCS#8,
but beware that this could possibly expose hardcoded passwords in clear.


@subsubheading Δείτε επίσης


See @ref{797,,ssl.SSLContext.load_cert_chain()} for additional
information on the accepted values for `certfile', `keyfile'
and `password'.


When specified, the `alpn_protocols' argument must be a sequence of strings
specifying the «Application-Layer Protocol Negotiation» (ALPN) protocols
supported by the server. ALPN allows the server and the client to negotiate
the application protocol during the TLS handshake.

By default, it is set to @code{["http/1.1"]}, meaning the server supports HTTP/1.1.


Added in version 3.14.

@end deffn

@geindex ThreadingHTTPSServer (κλάση σε http.server)
@anchor{library/http server http server ThreadingHTTPSServer}@anchor{4334}
@deffn {Κλάση} http.server.ThreadingHTTPSServer (server_address, RequestHandlerClass, bind_and_activate=True, *, certfile, keyfile=None, password=None, alpn_protocols=None)

This class is identical to @ref{4b6,,HTTPSServer} but uses threads to handle
requests by inheriting from @ref{f01,,ThreadingMixIn}. This is
analogous to @ref{f00,,ThreadingHTTPServer} only using @code{HTTPSServer}.


Added in version 3.14.

@end deffn

The @ref{412f,,HTTPServer}, @ref{f00,,ThreadingHTTPServer}, @ref{4b6,,HTTPSServer} and
@ref{4334,,ThreadingHTTPSServer} must be given a `RequestHandlerClass' on
instantiation, of which this module provides three different variants:

@geindex BaseHTTPRequestHandler (κλάση σε http.server)
@anchor{library/http server http server BaseHTTPRequestHandler}@anchor{226}
@deffn {Κλάση} http.server.BaseHTTPRequestHandler (request, client_address, server)

This class is used to handle the HTTP requests that arrive at the server.  By
itself, it cannot respond to any actual HTTP requests; it must be subclassed
to handle each request method (for example, @code{'GET'} or @code{'POST'}).
@code{BaseHTTPRequestHandler} provides a number of class and instance
variables, and methods for use by subclasses.

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.

@code{BaseHTTPRequestHandler} has the following instance variables:

@geindex client_address (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler client_address}@anchor{4335}
@deffn {Ιδιότητα} client_address

Contains a tuple of the form @code{(host, port)} referring to the client’s
address.
@end deffn

@geindex server (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler server}@anchor{4336}
@deffn {Ιδιότητα} server

Contains the server instance.
@end deffn

@geindex close_connection (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler close_connection}@anchor{4337}
@deffn {Ιδιότητα} close_connection

Boolean that should be set before @ref{4338,,handle_one_request()} returns,
indicating if another request may be expected, or if the connection should
be shut down.
@end deffn

@geindex requestline (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler requestline}@anchor{4339}
@deffn {Ιδιότητα} requestline

Contains the string representation of the HTTP request line. The
terminating CRLF is stripped. This attribute should be set by
@ref{4338,,handle_one_request()}. If no valid request line was processed, it
should be set to the empty string.
@end deffn

@geindex command (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler command}@anchor{433a}
@deffn {Ιδιότητα} command

Contains the command (request type). For example, @code{'GET'}.
@end deffn

@geindex path (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler path}@anchor{433b}
@deffn {Ιδιότητα} path

Contains the request path. If query component of the URL is present,
then @code{path} includes the query. Using the terminology of 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html},
@code{path} here includes @code{hier-part} and the @code{query}.
@end deffn

@geindex request_version (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler request_version}@anchor{433c}
@deffn {Ιδιότητα} request_version

Contains the version string from the request. For example, @code{'HTTP/1.0'}.
@end deffn

@geindex headers (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler headers}@anchor{4213}
@deffn {Ιδιότητα} headers

Holds an instance of the class specified by the @ref{433d,,MessageClass} class
variable. This instance parses and manages the headers in the HTTP
request. The @ref{2015,,parse_headers()} function from
@ref{72,,http.client} is used to parse the headers and it requires that the
HTTP request provide a valid 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} style header.
@end deffn

@geindex rfile (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler rfile}@anchor{433e}
@deffn {Ιδιότητα} rfile

An @ref{a83,,io.BufferedIOBase} input stream, ready to read from
the start of the optional input data.
@end deffn

@geindex wfile (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler wfile}@anchor{433f}
@deffn {Ιδιότητα} 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.


Άλλαξε στην έκδοση 3.6: This is an @ref{a83,,io.BufferedIOBase} stream.

@end deffn

@code{BaseHTTPRequestHandler} has the following attributes:

@geindex server_version (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler server_version}@anchor{4340}
@deffn {Ιδιότητα} server_version

Specifies the server software version.  You may want to override this. The
format is multiple whitespace-separated strings, where each string is of
the form name[/version]. For example, @code{'BaseHTTP/0.2'}.
@end deffn

@geindex sys_version (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler sys_version}@anchor{4341}
@deffn {Ιδιότητα} sys_version

Contains the Python system version, in a form usable by the
@ref{4342,,version_string} method and the @ref{4340,,server_version} class
variable. For example, @code{'Python/1.4'}.
@end deffn

@geindex error_message_format (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler error_message_format}@anchor{12fb}
@deffn {Ιδιότητα} error_message_format

Specifies a format string that should be used by @ref{12fa,,send_error()} method
for building an error response to the client. The string is filled by
default with variables from @ref{41f8,,responses} based on the status code
that passed to @code{send_error()}.
@end deffn

@geindex error_content_type (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler error_content_type}@anchor{4343}
@deffn {Ιδιότητα} error_content_type

Specifies the Content-Type HTTP header of error responses sent to the
client.  The default value is @code{'text/html'}.
@end deffn

@geindex protocol_version (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler protocol_version}@anchor{4344}
@deffn {Ιδιότητα} 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{4345,,send_header()}) in all of its responses to clients.
For backwards compatibility, the setting defaults to @code{'HTTP/1.0'}.
@end deffn

@geindex MessageClass (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler MessageClass}@anchor{433d}
@deffn {Ιδιότητα} MessageClass

Specifies an @ref{780,,email.message.Message}-like class to parse HTTP
headers.  Typically, this is not overridden, and it defaults to
@ref{4211,,http.client.HTTPMessage}.
@end deffn

@geindex responses (ιδιότητα της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler responses}@anchor{41f8}
@deffn {Ιδιότητα} responses

This attribute contains a mapping of error code integers to two-element tuples
containing a short and long message. For example, @code{@{code: (shortmessage,
longmessage)@}}. The `shortmessage' is usually used as the `message' key in an
error response, and `longmessage' as the `explain' key.  It is used by
@ref{4346,,send_response_only()} and @ref{12fa,,send_error()} methods.
@end deffn

A @code{BaseHTTPRequestHandler} instance has the following methods:

@geindex handle() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler handle}@anchor{4347}
@deffn {Μέθοδος} handle ()

Calls @ref{4338,,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() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler handle_one_request}@anchor{4338}
@deffn {Μέθοδος} 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() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler handle_expect_100}@anchor{4348}
@deffn {Μέθοδος} 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 example, the server can choose to send @code{417
Expectation Failed} as a response header and @code{return False}.


Added in version 3.2.

@end deffn

@geindex send_error() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler send_error}@anchor{12fa}
@deffn {Μέθοδος} 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{12fb,,error_message_format} attribute and emitted, after
a complete set of headers, as the response body.  The @ref{41f8,,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}.


Άλλαξε στην έκδοση 3.4: The error response includes a Content-Length header.
Added the `explain' argument.

@end deffn

@geindex send_response() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler send_response}@anchor{4349}
@deffn {Μέθοδος} 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{4342,,version_string()} and
@ref{434a,,date_time_string()} methods, respectively. If the server does not
intend to send any other headers using the @ref{4345,,send_header()} method,
then @code{send_response()} should be followed by an @ref{1478,,end_headers()}
call.


Άλλαξε στην έκδοση 3.3: Headers are stored to an internal buffer and @ref{1478,,end_headers()}
needs to be called explicitly.

@end deffn

@geindex send_header() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler send_header}@anchor{4345}
@deffn {Μέθοδος} send_header (keyword, value)

Adds the HTTP header to an internal buffer which will be written to the
output stream when either @ref{1478,,end_headers()} or @ref{1479,,flush_headers()} is
invoked. `keyword' should specify the header keyword, with `value'
specifying its value. Note that, after the send_header calls are done,
@code{end_headers()} MUST BE called in order to complete the operation.

This method does not reject input containing CRLF sequences.


Άλλαξε στην έκδοση 3.2: Headers are stored in an internal buffer.

@end deffn

@geindex send_response_only() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler send_response_only}@anchor{4346}
@deffn {Μέθοδος} 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.

This method does not reject `message' containing CRLF sequences.


Added in version 3.2.

@end deffn

@geindex end_headers() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler end_headers}@anchor{1478}
@deffn {Μέθοδος} end_headers ()

Adds a blank line
(indicating the end of the HTTP headers in the response)
to the headers buffer and calls @ref{1479,,flush_headers()}.


Άλλαξε στην έκδοση 3.2: The buffered headers are written to the output stream.

@end deffn

@geindex flush_headers() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler flush_headers}@anchor{1479}
@deffn {Μέθοδος} flush_headers ()

Finally send the headers to the output stream and flush the internal
headers buffer.


Added in version 3.3.

@end deffn

@geindex log_request() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler log_request}@anchor{434b}
@deffn {Μέθοδος} 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() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler log_error}@anchor{434c}
@deffn {Μέθοδος} log_error (...)

Logs an error when a request cannot be fulfilled. By default, it passes
the message to @ref{434d,,log_message()}, so it takes the same arguments
(`format' and additional values).
@end deffn

@geindex log_message() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler log_message}@anchor{434d}
@deffn {Μέθοδος} 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
@code{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() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler version_string}@anchor{4342}
@deffn {Μέθοδος} version_string ()

Returns the server software’s version string. This is a combination of the
@ref{4340,,server_version} and @ref{4341,,sys_version} attributes.
@end deffn

@geindex date_time_string() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler date_time_string}@anchor{434a}
@deffn {Μέθοδος} 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{75e,,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() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler log_date_time_string}@anchor{434e}
@deffn {Μέθοδος} log_date_time_string ()

Returns the current date and time, formatted for logging.
@end deffn

@geindex address_string() (μέθοδος της http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler address_string}@anchor{434f}
@deffn {Μέθοδος} address_string ()

Returns the client address.


Άλλαξε στην έκδοση 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 (κλάση σε http.server)
@anchor{library/http server http server SimpleHTTPRequestHandler}@anchor{22a}
@deffn {Κλάση} http.server.SimpleHTTPRequestHandler (request, client_address, server, *, directory=None, extra_response_headers=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.


Άλλαξε στην έκδοση 3.7: Added the `directory' parameter.



Άλλαξε στην έκδοση 3.9: The `directory' parameter accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.15: Added `extra_response_headers' parameter.


A lot of the work, such as parsing the request, is done by the base class
@ref{226,,BaseHTTPRequestHandler}.  This class implements the @ref{4350,,do_GET()}
and @ref{4351,,do_HEAD()} functions.

The following are defined as class-level attributes of
@code{SimpleHTTPRequestHandler}:

@geindex server_version (ιδιότητα της http.server.SimpleHTTPRequestHandler)
@anchor{library/http server http server SimpleHTTPRequestHandler server_version}@anchor{4352}
@deffn {Ιδιότητα} server_version

This will be @code{"SimpleHTTP/" + __version__}, where @code{__version__} is
defined at the module level.
@end deffn

@geindex default_content_type (ιδιότητα της http.server.SimpleHTTPRequestHandler)
@anchor{library/http server http server SimpleHTTPRequestHandler default_content_type}@anchor{228}
@deffn {Ιδιότητα} default_content_type

Specifies the Content-Type header value sent when the MIME type
cannot be guessed from the file extension of the requested URL.
By default, it is set to @code{'application/octet-stream'}.


Added in version 3.15.

@end deffn

@geindex extensions_map (ιδιότητα της http.server.SimpleHTTPRequestHandler)
@anchor{library/http server http server SimpleHTTPRequestHandler extensions_map}@anchor{4353}
@deffn {Ιδιότητα} 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.


Άλλαξε στην έκδοση 3.9: This dictionary is no longer filled with the default system mappings,
but only contains overrides.

@end deffn

@geindex extra_response_headers (ιδιότητα της http.server.SimpleHTTPRequestHandler)
@anchor{library/http server http server SimpleHTTPRequestHandler extra_response_headers}@anchor{4354}
@deffn {Ιδιότητα} extra_response_headers

A sequence of @code{(name, value)} pairs containing user-defined extra HTTP
response headers to add to each successful HTTP status 200 response. These
headers are not included in other status code responses.

Headers that the server sends automatically such as @code{Content-Type}
will not be overwritten by @code{extra_response_headers}.
@end deffn

The @code{SimpleHTTPRequestHandler} class defines the following methods:

@geindex do_HEAD() (μέθοδος της http.server.SimpleHTTPRequestHandler)
@anchor{library/http server http server SimpleHTTPRequestHandler do_HEAD}@anchor{4351}
@deffn {Μέθοδος} 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{4350,,do_GET()}
method for a more complete explanation of the possible headers.
@end deffn

@geindex do_GET() (μέθοδος της http.server.SimpleHTTPRequestHandler)
@anchor{library/http server http server SimpleHTTPRequestHandler do_GET}@anchor{4350}
@deffn {Μέθοδος} 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{14a6,,os.listdir()} to scan the directory, and returns a @code{404} error
response if the @code{listdir()} fails.

If the request was mapped to a file, it is opened. Any @ref{53c,,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.

The instance attribute @ref{4354,,extra_response_headers} is a sequence of
@code{(name, value)} pairs containing user-defined extra response headers.

Then follows a blank line signifying the end of the headers, and then the
contents of the file are output.

For example usage, see the implementation of the @code{test} function
in Lib/http/server.py@footnote{https://github.com/python/cpython/tree/main/Lib/http/server.py}.


Άλλαξε στην έκδοση 3.7: Support of the @code{'If-Modified-Since'} header.

@end deffn
@end deffn

The @ref{22a,,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{22a,,SimpleHTTPRequestHandler} can also be subclassed to enhance behavior,
such as using different index file names by overriding the class attribute
@code{index_pages}.

@menu
* Command-line interface: Command-line interface<6>. 
* Security considerations: Security considerations<3>. 

@end menu

@node Command-line interface<6>,Security considerations<3>,,http server — HTTP servers
@anchor{library/http server command-line-interface}@anchor{4355}@anchor{library/http server http-server-cli}@anchor{227}
@subsubsection Command-line interface


@code{http.server} can also be invoked directly using the @ref{4ca,,-m}
switch of the interpreter.  The following example illustrates how to serve
files relative to the current directory:

@example
python -m http.server [OPTIONS] [port]
@end example

The following options are accepted:

@geindex http.server command line option; port
@anchor{library/http server cmdoption-http server-arg-port}@anchor{4356}
@deffn {Option} port

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
@end deffn

@geindex http.server command line option; -b
@geindex http.server command line option; --bind
@anchor{library/http server cmdoption-http server-b}@anchor{4357}@anchor{library/http server cmdoption-http server-bind}@anchor{4358}
@deffn {Option} @w{-}b, @w{-}@w{-}bind <address>

Specifies a specific address to which it should bind. Both IPv4 and IPv6
addresses are supported. By default, the server binds itself to all
interfaces. 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


Added in version 3.4.



Άλλαξε στην έκδοση 3.8: Support IPv6 in the @code{--bind} option.

@end deffn

@geindex http.server command line option; -d
@geindex http.server command line option; --directory
@anchor{library/http server cmdoption-http server-d}@anchor{1a35}@anchor{library/http server cmdoption-http server-directory}@anchor{4359}
@deffn {Option} @w{-}d, @w{-}@w{-}directory <dir>

Specifies a directory to which it should serve the files. By default,
the server uses the current directory. For example, the following command
uses a specific directory:

@example
python -m http.server --directory /tmp/
@end example


Added in version 3.7.

@end deffn

@geindex http.server command line option; -p
@geindex http.server command line option; --protocol
@anchor{library/http server cmdoption-http server-p}@anchor{435a}@anchor{library/http server cmdoption-http server-protocol}@anchor{435b}
@deffn {Option} @w{-}p, @w{-}@w{-}protocol <version>

Specifies the HTTP version to which the server is conformant. By default,
the server is conformant to HTTP/1.0. For example, the following command
runs an HTTP/1.1 conformant server:

@example
python -m http.server --protocol HTTP/1.1
@end example


Added in version 3.11.

@end deffn

@geindex http.server command line option; --content-type
@anchor{library/http server cmdoption-http server-content-type}@anchor{229}
@deffn {Option} @w{-}@w{-}content@w{-}type <content_type>

Specifies the default Content-Type HTTP header used when the MIME type
cannot be guessed from the URL’s file extension. By default, the server
uses @code{'application/octet-stream'}:

@example
python -m http.server --content-type text/html
@end example


Added in version 3.15.

@end deffn

@geindex http.server command line option; --tls-cert
@anchor{library/http server cmdoption-http server-tls-cert}@anchor{4b7}
@deffn {Option} @w{-}@w{-}tls@w{-}cert

Specifies a TLS certificate chain for HTTPS connections:

@example
python -m http.server --tls-cert fullchain.pem
@end example


Added in version 3.14.

@end deffn

@geindex http.server command line option; --tls-key
@anchor{library/http server cmdoption-http server-tls-key}@anchor{4b8}
@deffn {Option} @w{-}@w{-}tls@w{-}key

Specifies a private key file for HTTPS connections.

This option requires @code{--tls-cert} to be specified.


Added in version 3.14.

@end deffn

@geindex http.server command line option; --tls-password-file
@anchor{library/http server cmdoption-http server-tls-password-file}@anchor{4b9}
@deffn {Option} @w{-}@w{-}tls@w{-}password@w{-}file

Specifies the password file for password-protected private keys:

@example
python -m http.server \
       --tls-cert cert.pem \
       --tls-key key.pem \
       --tls-password-file password.txt
@end example

This option requires @code{--tls-cert} to be specified.


Added in version 3.14.

@end deffn

@geindex http.server command line option; -H
@geindex http.server command line option; --header
@anchor{library/http server cmdoption-http server-H}@anchor{435c}@anchor{library/http server cmdoption-http server-header}@anchor{435d}
@deffn {Option} @w{-}H, @w{-}@w{-}header <header> <value>

Specify an additional extra HTTP Response Header to send on successful HTTP
200 responses. Can be used multiple times to send additional custom response
headers. Headers that are sent automatically by the server (for instance
Content-Type) will not be overwritten by the server.


Added in version 3.15.

@end deffn

@node Security considerations<3>,,Command-line interface<6>,http server — HTTP servers
@anchor{library/http server http-server-security}@anchor{4333}@anchor{library/http server security-considerations}@anchor{435e}
@subsubsection Security considerations


@geindex http.server;security

@ref{22a,,SimpleHTTPRequestHandler} will follow symbolic links when handling
requests, this makes it possible for files outside of the specified directory
to be served.

Methods @ref{4345,,BaseHTTPRequestHandler.send_header()} and
@ref{4346,,BaseHTTPRequestHandler.send_response_only()} assume sanitized input
and do not perform input validation such as checking for the presence of CRLF
sequences. Untrusted input may result in HTTP Header injection attacks.

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{226,,BaseHTTPRequestHandler} @code{.log_message}
implementation. This could allow remote clients connecting to your
server to send nefarious control codes to your terminal.


Άλλαξε στην έκδοση 3.12: Control characters are scrubbed in stderr logs.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node http cookies — HTTP state management,http cookiejar — Cookie handling for HTTP clients,http server — HTTP servers,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/http cookies doc}@anchor{435f}@anchor{library/http cookies http-cookies-http-state-management}@anchor{4360}@anchor{library/http cookies module-http cookies}@anchor{74}@anchor{library/http cookies translation-repo}@anchor{4361}
@subsection @code{http.cookies} — HTTP state management


@geindex module; http.cookies

`Source code:' Lib/http/cookies.py@footnote{https://github.com/python/cpython/tree/main/Lib/http/cookies.py}


__________________________________________________________________


The @code{http.cookies} module defines classes for abstracting the concept of
cookies, an HTTP state management mechanism. It supports both simple string-only
cookies, and provides an abstraction for having any serializable data-type as
cookie value.

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{1668,,string.ascii_letters}, @ref{293c,,string.digits} and
@code{!#$%&'*+-.^_`|~:} denote the set of valid characters allowed by this module
in a cookie name (as @ref{fc0,,key}).


Άλλαξε στην έκδοση 3.3: Allowed “:” as a valid cookie name character.


@cartouche
@quotation Σημείωση 
On encountering an invalid cookie, @ref{4362,,CookieError} is raised, so if your
cookie data comes from a browser you should always prepare for invalid data
and catch @code{CookieError} on parsing.
@end quotation
@end cartouche

@geindex CookieError
@anchor{library/http cookies http cookies CookieError}@anchor{4362}
@deffn {Εξαίρεση} http.cookies.CookieError

Exception failing because of 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} invalidity: incorrect attributes,
incorrect @code{Set-Cookie} header, etc.
@end deffn

@geindex BaseCookie (κλάση σε http.cookies)
@anchor{library/http cookies http cookies BaseCookie}@anchor{4363}
@deffn {Κλάση} http.cookies.BaseCookie ([input])

This class is a dictionary-like object whose keys are strings and whose values
are @ref{fc3,,Morsel} instances. Note that upon setting a key to a value, the
value is first converted to a @code{Morsel} containing the key and the value.

If `input' is given, it is passed to the @ref{4364,,load()} method.
@end deffn

@geindex SimpleCookie (κλάση σε http.cookies)
@anchor{library/http cookies http cookies SimpleCookie}@anchor{2012}
@deffn {Κλάση} http.cookies.SimpleCookie ([input])

This class derives from @ref{4363,,BaseCookie} and overrides @ref{4365,,value_decode()}
and @ref{4366,,value_encode()}. @code{SimpleCookie} supports
strings as cookie values. When setting the value, @code{SimpleCookie}
calls the builtin @ref{1df,,str()} to convert
the value to a string. Values received from HTTP are kept as strings.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{73,,http.cookiejar}

HTTP cookie handling for web `clients'.  The @ref{73,,http.cookiejar} and
@code{http.cookies} modules do not depend on each other.

@geindex RFC; RFC 2109

@item RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} - HTTP State Management Mechanism

This is the state management specification implemented by this module.
@end table


@menu
* Cookie Objects:: 
* Morsel Objects:: 
* Example: Example<11>. 

@end menu

@node Cookie Objects,Morsel Objects,,http cookies — HTTP state management
@anchor{library/http cookies cookie-objects}@anchor{4367}@anchor{library/http cookies id1}@anchor{4368}
@subsubsection Cookie Objects


@geindex value_decode() (μέθοδος της http.cookies.BaseCookie)
@anchor{library/http cookies http cookies BaseCookie value_decode}@anchor{4365}
@deffn {Μέθοδος} BaseCookie.value_decode (val)

Return a tuple @code{(real_value, coded_value)} from a string representation.
@code{real_value} can be any type. This method does no decoding in
@ref{4363,,BaseCookie} — it exists so it can be overridden.
@end deffn

@geindex value_encode() (μέθοδος της http.cookies.BaseCookie)
@anchor{library/http cookies http cookies BaseCookie value_encode}@anchor{4366}
@deffn {Μέθοδος} BaseCookie.value_encode (val)

Return a tuple @code{(real_value, coded_value)}. `val' can be any type, but
@code{coded_value} will always be converted to a string.
This method does no encoding in @ref{4363,,BaseCookie} — it exists so it can
be overridden.

In general, it should be the case that @code{value_encode()} and
@ref{4365,,value_decode()} are inverses on the range of `value_decode'.
@end deffn

@geindex output() (μέθοδος της http.cookies.BaseCookie)
@anchor{library/http cookies http cookies BaseCookie output}@anchor{2f7}
@deffn {Μέθοδος} 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{fc3,,Morsel}’s @ref{2f6,,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() (μέθοδος της http.cookies.BaseCookie)
@anchor{library/http cookies http cookies BaseCookie js_output}@anchor{2f5}
@deffn {Μέθοδος} BaseCookie.js_output (attrs=None)

Return an embeddable JavaScript snippet, which, if run on a browser which
supports JavaScript, will act the same as if the HTTP headers was sent.

The meaning for `attrs' is the same as in @ref{2f7,,output()}.


Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.19: This method generates a JavaScript snippet to set cookies in the browser,
which is no longer considered a standard or recommended approach.
Use @ref{2f7,,output()} instead to generate HTTP
headers.

@end deffn

@geindex load() (μέθοδος της http.cookies.BaseCookie)
@anchor{library/http cookies http cookies BaseCookie load}@anchor{4364}
@deffn {Μέθοδος} BaseCookie.load (rawdata)

If `rawdata' is a string, parse it as an @code{HTTP_COOKIE} and add the values
found there as @ref{fc3,,Morsel}s. If it is a dictionary, it is equivalent to:

@example
for k, v in rawdata.items():
    cookie[k] = v
@end example
@end deffn

@node Morsel Objects,Example<11>,Cookie Objects,http cookies — HTTP state management
@anchor{library/http cookies id2}@anchor{4369}@anchor{library/http cookies morsel-objects}@anchor{436a}
@subsubsection Morsel Objects


@geindex Morsel (κλάση σε http.cookies)
@anchor{library/http cookies http cookies Morsel}@anchor{fc3}
@deffn {Κλάση} http.cookies.Morsel

Abstract a key/value pair, which has some 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} attributes.

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 (ιδιότητα της http.cookies.Morsel)
@geindex path (ιδιότητα της http.cookies.Morsel)
@geindex comment (ιδιότητα της http.cookies.Morsel)
@geindex domain (ιδιότητα της http.cookies.Morsel)
@geindex secure (ιδιότητα της http.cookies.Morsel)
@geindex version (ιδιότητα της http.cookies.Morsel)
@geindex httponly (ιδιότητα της http.cookies.Morsel)
@geindex samesite (ιδιότητα της http.cookies.Morsel)
@geindex partitioned (ιδιότητα της http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel expires}@anchor{436b}
@deffn {Ιδιότητα} expires
@anchor{library/http cookies http cookies Morsel path}@anchor{436c}
@deffnx {Ιδιότητα} path
@anchor{library/http cookies http cookies Morsel comment}@anchor{436d}
@deffnx {Ιδιότητα} comment
@anchor{library/http cookies http cookies Morsel domain}@anchor{436e}
@deffnx {Ιδιότητα} domain

@deffnx {Ιδιότητα} max@w{-}age
@anchor{library/http cookies http cookies Morsel secure}@anchor{436f}
@deffnx {Ιδιότητα} secure
@anchor{library/http cookies http cookies Morsel version}@anchor{4370}
@deffnx {Ιδιότητα} version
@anchor{library/http cookies http cookies Morsel httponly}@anchor{1773}
@deffnx {Ιδιότητα} httponly
@anchor{library/http cookies http cookies Morsel samesite}@anchor{4371}
@deffnx {Ιδιότητα} samesite
@anchor{library/http cookies http cookies Morsel partitioned}@anchor{4372}
@deffnx {Ιδιότητα} partitioned
@end deffn
@end quotation

The attribute @ref{1773,,httponly} specifies that the cookie is only transferred
in HTTP requests, and is not accessible through JavaScript. This is intended
to mitigate some forms of cross-site scripting.

The attribute @ref{4371,,samesite} controls when the browser sends the cookie with
cross-site requests. This helps to mitigate CSRF attacks. Valid values are
«Strict» (only sent with same-site requests), «Lax» (sent with same-site
requests and top-level navigations), and «None» (sent with same-site and
cross-site requests). When using «None», the «secure» attribute must also
be set, as required by modern browsers.

The attribute @ref{4372,,partitioned} indicates to user agents that these
cross-site cookies `should' only be available in the same top-level context
that the cookie was first set in. For this to be accepted by the user agent,
you `must' also set @code{Secure}.

In addition, it is recommended to use the @code{__Host} prefix when setting
partitioned cookies to make them bound to the hostname and not the
registrable domain. Read
CHIPS (Cookies Having Independent Partitioned State)@footnote{https://github.com/privacycg/CHIPS/blob/main/README.md}
for full details and examples.

The keys are case-insensitive and their default value is @code{'@w{'}}.


Άλλαξε στην έκδοση 3.5: @code{__eq__()} now takes @ref{fc0,,key} and @ref{fc1,,value}
into account.



Άλλαξε στην έκδοση 3.7: Attributes @ref{fc0,,key}, @ref{fc1,,value} and
@ref{fc2,,coded_value} are read-only.  Use @ref{fc4,,set()} for
setting them.



Άλλαξε στην έκδοση 3.8: Added support for the @ref{4371,,samesite} attribute.



Άλλαξε στην έκδοση 3.14: Added support for the @ref{4372,,partitioned} attribute.

@end deffn

@geindex value (ιδιότητα της http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel value}@anchor{fc1}
@deffn {Ιδιότητα} Morsel.value

The value of the cookie.
@end deffn

@geindex coded_value (ιδιότητα της http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel coded_value}@anchor{fc2}
@deffn {Ιδιότητα} Morsel.coded_value

The encoded value of the cookie — this is what should be sent.
@end deffn

@geindex key (ιδιότητα της http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel key}@anchor{fc0}
@deffn {Ιδιότητα} Morsel.key

The name of the cookie.
@end deffn

@geindex set() (μέθοδος της http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel set}@anchor{fc4}
@deffn {Μέθοδος} Morsel.set (key, value, coded_value)

Set the `key', `value' and `coded_value' attributes.
@end deffn

@geindex isReservedKey() (μέθοδος της http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel isReservedKey}@anchor{4373}
@deffn {Μέθοδος} Morsel.isReservedKey (K)

Whether `K' is a member of the set of keys of a @ref{fc3,,Morsel}.
@end deffn

@geindex output() (μέθοδος της http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel output}@anchor{2f6}
@deffn {Μέθοδος} Morsel.output (attrs=None, header='Set-Cookie:')

Return a string representation of the Morsel, suitable to be sent as an HTTP
header. By default, all the attributes are included, unless `attrs' is given, in
which case it should be a list of attributes to use. `header' is by default
@code{"Set-Cookie:"}.
@end deffn

@geindex js_output() (μέθοδος της http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel js_output}@anchor{2f4}
@deffn {Μέθοδος} Morsel.js_output (attrs=None)

Return an embeddable JavaScript snippet, which, if run on a browser which
supports JavaScript, will act the same as if the HTTP header was sent.

The meaning for `attrs' is the same as in @ref{2f6,,output()}.


Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.19: This method generates a JavaScript snippet to set cookies in the browser,
which is no longer considered a standard or recommended approach.
Use @ref{2f6,,output()} instead to generate HTTP
headers.

@end deffn

@geindex OutputString() (μέθοδος της http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel OutputString}@anchor{4374}
@deffn {Μέθοδος} Morsel.OutputString (attrs=None)

Return a string representing the Morsel, without any surrounding HTTP or
JavaScript.

The meaning for `attrs' is the same as in @ref{2f6,,output()}.
@end deffn

@geindex update() (μέθοδος της http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel update}@anchor{1277}
@deffn {Μέθοδος} Morsel.update (values)

Update the values in the Morsel dictionary with the values in the dictionary
`values'.  Raise an error if any of the keys in the `values' dict is not a
valid 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} attribute.


Άλλαξε στην έκδοση 3.5: an error is raised for invalid keys.

@end deffn

@geindex copy() (μέθοδος της http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel copy}@anchor{1276}
@deffn {Μέθοδος} Morsel.copy (value)

Return a shallow copy of the Morsel object.


Άλλαξε στην έκδοση 3.5: return a Morsel object instead of a dict.

@end deffn

@geindex setdefault() (μέθοδος της http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel setdefault}@anchor{4375}
@deffn {Μέθοδος} Morsel.setdefault (key, value=None)

Raise an error if key is not a valid 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} attribute, otherwise
behave the same as @ref{1421,,dict.setdefault()}.
@end deffn

@node Example<11>,,Morsel Objects,http cookies — HTTP state management
@anchor{library/http cookies cookie-example}@anchor{4376}@anchor{library/http cookies example}@anchor{4377}
@subsubsection Example


The following example demonstrates how to use the @code{http.cookies} module.

@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=;";')
>>> print(C)
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=;"
>>> 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node http cookiejar — Cookie handling for HTTP clients,xmlrpc — XMLRPC server and client modules,http cookies — HTTP state management,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/http cookiejar doc}@anchor{4378}@anchor{library/http cookiejar http-cookiejar-cookie-handling-for-http-clients}@anchor{4379}@anchor{library/http cookiejar module-http cookiejar}@anchor{73}@anchor{library/http cookiejar translation-repo}@anchor{437a}
@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/main/Lib/http/cookiejar.py}


__________________________________________________________________


The @code{http.cookiejar} module defines classes for automatic handling of HTTP
cookies.  It is useful for accessing websites 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.
@code{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 Σημείωση 
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{437b}
@deffn {Εξαίρεση} http.cookiejar.LoadError

Instances of @ref{437c,,FileCookieJar} raise this exception on failure to load
cookies from a file.  @code{LoadError} is a subclass of @ref{53c,,OSError}.


Άλλαξε στην έκδοση 3.3: @code{LoadError} used to be a subtype of @ref{13fb,,IOError}, which is now an
alias of @ref{53c,,OSError}.

@end deffn

The following classes are provided:

@geindex CookieJar (κλάση σε http.cookiejar)
@anchor{library/http cookiejar http cookiejar CookieJar}@anchor{419c}
@deffn {Κλάση} http.cookiejar.CookieJar (policy=None)

`policy' is an object implementing the @ref{437d,,CookiePolicy} interface.

The @code{CookieJar} class stores HTTP cookies.  It extracts cookies from HTTP
requests, and returns them in HTTP responses. @code{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 (κλάση σε http.cookiejar)
@anchor{library/http cookiejar http cookiejar FileCookieJar}@anchor{437c}
@deffn {Κλάση} http.cookiejar.FileCookieJar (filename=None, delayload=None, policy=None)

`policy' is an object implementing the @ref{437d,,CookiePolicy} interface.  For the
other arguments, see the documentation for the corresponding attributes.

A @ref{419c,,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{437e,,load()} or @ref{437f,,revert()} method is called.  Subclasses of this class are
documented in section @ref{4380,,FileCookieJar subclasses and co-operation with web browsers}.

This should not be initialized directly – use its subclasses below instead.


Άλλαξε στην έκδοση 3.8: The filename parameter supports a @ref{79f,,path-like object}.

@end deffn

@geindex CookiePolicy (κλάση σε http.cookiejar)
@anchor{library/http cookiejar http cookiejar CookiePolicy}@anchor{437d}
@deffn {Κλάση} http.cookiejar.CookiePolicy

This class is responsible for deciding whether each cookie should be accepted
from / returned to the server.
@end deffn

@geindex DefaultCookiePolicy (κλάση σε http.cookiejar)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy}@anchor{1fe3}
@deffn {Κλάση} 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{a65,,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{437d,,CookiePolicy} and @code{DefaultCookiePolicy} objects.

@code{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{4381,,rfc2109_as_netscape} is @code{True}, RFC 2109 cookies are
“downgraded” by the @ref{419c,,CookieJar} instance to Netscape cookies, by
setting the @code{version} attribute of the @ref{4382,,Cookie} instance to 0.
@code{DefaultCookiePolicy} also provides some parameters to allow some
fine-tuning of policy.
@end deffn

@geindex Cookie (κλάση σε http.cookiejar)
@anchor{library/http cookiejar http cookiejar Cookie}@anchor{4382}
@deffn {Κλάση} 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 @code{http.cookiejar} construct their own @code{Cookie}
instances.  Instead, if necessary, call @code{make_cookies()} on a
@ref{419c,,CookieJar} instance.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{114,,urllib.request}

URL opening with automatic cookie handling.

@item Module @ref{74,,http.cookies}

HTTP cookie classes, principally useful for server-side code.  The
@code{http.cookiejar} and @ref{74,,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 @code{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:: 
* Cookie Objects: Cookie Objects<2>. 
* Examples: Examples<26>. 

@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{4383}@anchor{library/http cookiejar cookiejar-and-filecookiejar-objects}@anchor{4384}
@subsubsection CookieJar and FileCookieJar Objects


@ref{419c,,CookieJar} objects support the @ref{6ce,,iterator} protocol for iterating over
contained @ref{4382,,Cookie} objects.

@ref{419c,,CookieJar} has the following methods:

@geindex add_cookie_header() (μέθοδος της http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar add_cookie_header}@anchor{4385}
@deffn {Μέθοδος} 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{419c,,CookieJar}’s @ref{437d,,CookiePolicy} instance are true and false
respectively), the @code{Cookie2} header is also added when appropriate.

The `request' object (usually a @ref{1381,,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{114,,urllib.request}.


Άλλαξε στην έκδοση 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() (μέθοδος της http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar extract_cookies}@anchor{4386}
@deffn {Μέθοδος} CookieJar.extract_cookies (response, request)

Extract cookies from HTTP `response' and store them in the @ref{419c,,CookieJar},
where allowed by policy.

The @ref{419c,,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{4387,,CookiePolicy.set_ok()} method’s approval).

The `response' object (usually the result of a call to
@ref{57f,,urllib.request.urlopen()}, or similar) should support an @code{info()}
method, which returns an @ref{780,,email.message.Message} instance.

The `request' object (usually a @ref{1381,,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{114,,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.


Άλλαξε στην έκδοση 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() (μέθοδος της http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar set_policy}@anchor{4388}
@deffn {Μέθοδος} CookieJar.set_policy (policy)

Set the @ref{437d,,CookiePolicy} instance to be used.
@end deffn

@geindex make_cookies() (μέθοδος της http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar make_cookies}@anchor{4389}
@deffn {Μέθοδος} CookieJar.make_cookies (response, request)

Return sequence of @ref{4382,,Cookie} objects extracted from `response' object.

See the documentation for @ref{4386,,extract_cookies()} for the interfaces required of
the `response' and `request' arguments.
@end deffn

@geindex set_cookie_if_ok() (μέθοδος της http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar set_cookie_if_ok}@anchor{438a}
@deffn {Μέθοδος} CookieJar.set_cookie_if_ok (cookie, request)

Set a @ref{4382,,Cookie} if policy says it’s OK to do so.
@end deffn

@geindex set_cookie() (μέθοδος της http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar set_cookie}@anchor{438b}
@deffn {Μέθοδος} CookieJar.set_cookie (cookie)

Set a @ref{4382,,Cookie}, without checking with policy to see whether or not it
should be set.
@end deffn

@geindex clear() (μέθοδος της http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar clear}@anchor{438c}
@deffn {Μέθοδος} 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{7df,,KeyError} if no matching cookie exists.
@end deffn

@geindex clear_session_cookies() (μέθοδος της http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar clear_session_cookies}@anchor{438d}
@deffn {Μέθοδος} 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{437c,,FileCookieJar} implements the following additional methods:

@geindex save() (μέθοδος της http.cookiejar.FileCookieJar)
@anchor{library/http cookiejar http cookiejar FileCookieJar save}@anchor{438e}
@deffn {Μέθοδος} FileCookieJar.save (filename=None, ignore_discard=False, ignore_expires=False)

Save cookies to a file.

This base class raises @ref{59a,,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{a65,,None},
@ref{277,,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{437e,,load()} or
@ref{437f,,revert()} methods.
@end deffn

@geindex load() (μέθοδος της http.cookiejar.FileCookieJar)
@anchor{library/http cookiejar http cookiejar FileCookieJar load}@anchor{437e}
@deffn {Μέθοδος} 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{438e,,save()}.

The named file must be in the format understood by the class, or
@ref{437b,,LoadError} will be raised.  Also, @ref{53c,,OSError} may be raised, for
example if the file does not exist.


Άλλαξε στην έκδοση 3.3: @ref{13fb,,IOError} used to be raised, it is now an alias of @ref{53c,,OSError}.

@end deffn

@geindex revert() (μέθοδος της http.cookiejar.FileCookieJar)
@anchor{library/http cookiejar http cookiejar FileCookieJar revert}@anchor{437f}
@deffn {Μέθοδος} FileCookieJar.revert (filename=None, ignore_discard=False, ignore_expires=False)

Clear all cookies and reload cookies from a saved file.

@code{revert()} can raise the same exceptions as @ref{437e,,load()}. If there is a
failure, the object’s state will not be altered.
@end deffn

@ref{437c,,FileCookieJar} instances have the following public attributes:

@geindex filename (ιδιότητα της http.cookiejar.FileCookieJar)
@anchor{library/http cookiejar http cookiejar FileCookieJar filename}@anchor{438f}
@deffn {Ιδιότητα} FileCookieJar.filename

Filename of default file in which to keep cookies.  This attribute may be
assigned to.
@end deffn

@geindex delayload (ιδιότητα της http.cookiejar.FileCookieJar)
@anchor{library/http cookiejar http cookiejar FileCookieJar delayload}@anchor{4390}
@deffn {Ιδιότητα} 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{419c,,CookieJar} object may
ignore it.  None of the @ref{437c,,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{4380}@anchor{library/http cookiejar filecookiejar-subclasses-and-co-operation-with-web-browsers}@anchor{4391}
@subsubsection FileCookieJar subclasses and co-operation with web browsers


The following @ref{419c,,CookieJar} subclasses are provided for reading and
writing.

@geindex MozillaCookieJar (κλάση σε http.cookiejar)
@anchor{library/http cookiejar http cookiejar MozillaCookieJar}@anchor{4392}
@deffn {Κλάση} http.cookiejar.MozillaCookieJar (filename=None, delayload=None, policy=None)

A @ref{437c,,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 Σημείωση 
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 Προειδοποίηση 
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 (κλάση σε http.cookiejar)
@anchor{library/http cookiejar http cookiejar LWPCookieJar}@anchor{4393}
@deffn {Κλάση} http.cookiejar.LWPCookieJar (filename=None, delayload=None, policy=None)

A @ref{437c,,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.


Άλλαξε στην έκδοση 3.8: The filename parameter supports a @ref{79f,,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{4394}@anchor{library/http cookiejar cookiepolicy-objects}@anchor{4395}
@subsubsection CookiePolicy Objects


Objects implementing the @ref{437d,,CookiePolicy} interface have the following
methods:

@geindex set_ok() (μέθοδος της http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy set_ok}@anchor{4387}
@deffn {Μέθοδος} CookiePolicy.set_ok (cookie, request)

Return boolean value indicating whether cookie should be accepted from server.

`cookie' is a @ref{4382,,Cookie} instance.  `request' is an object
implementing the interface defined by the documentation for
@ref{4386,,CookieJar.extract_cookies()}.
@end deffn

@geindex return_ok() (μέθοδος της http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy return_ok}@anchor{4396}
@deffn {Μέθοδος} CookiePolicy.return_ok (cookie, request)

Return boolean value indicating whether cookie should be returned to server.

`cookie' is a @ref{4382,,Cookie} instance.  `request' is an object
implementing the interface defined by the documentation for
@ref{4385,,CookieJar.add_cookie_header()}.
@end deffn

@geindex domain_return_ok() (μέθοδος της http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy domain_return_ok}@anchor{4397}
@deffn {Μέθοδος} 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 @code{domain_return_ok()} and @ref{4398,,path_return_ok()} leaves all the
work to @ref{4396,,return_ok()}.

If @code{domain_return_ok()} returns true for the cookie domain,
@ref{4398,,path_return_ok()} is called for the cookie path.  Otherwise,
@code{path_return_ok()} and @ref{4396,,return_ok()} are never called for that cookie
domain.  If @code{path_return_ok()} returns true, @code{return_ok()} is called
with the @ref{4382,,Cookie} object itself for a full check.  Otherwise,
@code{return_ok()} is never called for that cookie path.

Note that @code{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{4398,,path_return_ok()}.

The `request' argument is as documented for @ref{4396,,return_ok()}.
@end deffn

@geindex path_return_ok() (μέθοδος της http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy path_return_ok}@anchor{4398}
@deffn {Μέθοδος} CookiePolicy.path_return_ok (path, request)

Return @code{False} if cookies should not be returned, given cookie path.

See the documentation for @ref{4397,,domain_return_ok()}.
@end deffn

In addition to implementing the methods above, implementations of the
@ref{437d,,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 (ιδιότητα της http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy netscape}@anchor{4399}
@deffn {Ιδιότητα} CookiePolicy.netscape

Implement Netscape protocol.
@end deffn

@geindex rfc2965 (ιδιότητα της http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy rfc2965}@anchor{439a}
@deffn {Ιδιότητα} CookiePolicy.rfc2965

Implement 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} protocol.
@end deffn

@geindex hide_cookie2 (ιδιότητα της http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy hide_cookie2}@anchor{439b}
@deffn {Ιδιότητα} 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{437d,,CookiePolicy} class is by subclassing
from @ref{1fe3,,DefaultCookiePolicy} and overriding some or all of the methods
above.  @code{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,Cookie Objects<2>,CookiePolicy Objects,http cookiejar — Cookie handling for HTTP clients
@anchor{library/http cookiejar default-cookie-policy-objects}@anchor{439c}@anchor{library/http cookiejar defaultcookiepolicy-objects}@anchor{439d}
@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{437d,,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{a65,,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{1fe3,,DefaultCookiePolicy} implements the following additional methods:

@geindex blocked_domains() (μέθοδος της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy blocked_domains}@anchor{439e}
@deffn {Μέθοδος} DefaultCookiePolicy.blocked_domains ()

Return the sequence of blocked domains (as a tuple).
@end deffn

@geindex set_blocked_domains() (μέθοδος της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy set_blocked_domains}@anchor{439f}
@deffn {Μέθοδος} DefaultCookiePolicy.set_blocked_domains (blocked_domains)

Set the sequence of blocked domains.
@end deffn

@geindex is_blocked() (μέθοδος της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy is_blocked}@anchor{43a0}
@deffn {Μέθοδος} DefaultCookiePolicy.is_blocked (domain)

Return @code{True} if `domain' is on the blocklist for setting or receiving
cookies.
@end deffn

@geindex allowed_domains() (μέθοδος της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy allowed_domains}@anchor{43a1}
@deffn {Μέθοδος} DefaultCookiePolicy.allowed_domains ()

Return @ref{a65,,None}, or the sequence of allowed domains (as a tuple).
@end deffn

@geindex set_allowed_domains() (μέθοδος της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy set_allowed_domains}@anchor{43a2}
@deffn {Μέθοδος} DefaultCookiePolicy.set_allowed_domains (allowed_domains)

Set the sequence of allowed domains, or @ref{a65,,None}.
@end deffn

@geindex is_not_allowed() (μέθοδος της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy is_not_allowed}@anchor{43a3}
@deffn {Μέθοδος} DefaultCookiePolicy.is_not_allowed (domain)

Return @code{True} if `domain' is not on the allowlist for setting or receiving
cookies.
@end deffn

@ref{1fe3,,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 (ιδιότητα της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy rfc2109_as_netscape}@anchor{4381}
@deffn {Ιδιότητα} DefaultCookiePolicy.rfc2109_as_netscape

If true, request that the @ref{419c,,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{4382,,Cookie} instance to 0.  The default value is @ref{a65,,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 (ιδιότητα της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_domain}@anchor{43a4}
@deffn {Ιδιότητα} 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 (ιδιότητα της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_rfc2965_unverifiable}@anchor{43a5}
@deffn {Ιδιότητα} 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 (ιδιότητα της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_ns_unverifiable}@anchor{43a6}
@deffn {Ιδιότητα} 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 (ιδιότητα της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_ns_domain}@anchor{43a7}
@deffn {Ιδιότητα} 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 (ιδιότητα της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_ns_set_initial_dollar}@anchor{43a8}
@deffn {Ιδιότητα} 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 (ιδιότητα της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_ns_set_path}@anchor{43a9}
@deffn {Ιδιότητα} DefaultCookiePolicy.strict_ns_set_path

Don’t allow setting cookies whose path doesn’t path-match request URI.
@end deffn

@ref{43a7,,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 (ιδιότητα της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainStrictNoDots}@anchor{43aa}
@deffn {Ιδιότητα} 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 (ιδιότητα της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainStrictNonDomain}@anchor{43ab}
@deffn {Ιδιότητα} 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 (ιδιότητα της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainRFC2965Match}@anchor{43ac}
@deffn {Ιδιότητα} 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 (ιδιότητα της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainLiberal}@anchor{43ad}
@deffn {Ιδιότητα} DefaultCookiePolicy.DomainLiberal

Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched
off).
@end deffn

@geindex DomainStrict (ιδιότητα της http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainStrict}@anchor{43ae}
@deffn {Ιδιότητα} DefaultCookiePolicy.DomainStrict

Equivalent to @code{DomainStrictNoDots|DomainStrictNonDomain}.
@end deffn

@node Cookie Objects<2>,Examples<26>,DefaultCookiePolicy Objects,http cookiejar — Cookie handling for HTTP clients
@anchor{library/http cookiejar cookie-objects}@anchor{43af}
@subsubsection Cookie Objects


@ref{4382,,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 @code{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{437d,,CookiePolicy} method.  The class does not enforce
internal consistency, so you should know what you’re doing if you do that.

@geindex version (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie version}@anchor{43b0}
@deffn {Ιδιότητα} Cookie.version

Integer or @ref{a65,,None}.  Netscape cookies have @ref{43b0,,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
@code{http.cookiejar} may “downgrade” RFC 2109 cookies to Netscape cookies, in which
case @code{version} is 0.
@end deffn

@geindex name (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie name}@anchor{43b1}
@deffn {Ιδιότητα} Cookie.name

Cookie name (a string).
@end deffn

@geindex value (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie value}@anchor{43b2}
@deffn {Ιδιότητα} Cookie.value

Cookie value (a string), or @ref{a65,,None}.
@end deffn

@geindex port (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie port}@anchor{43b3}
@deffn {Ιδιότητα} Cookie.port

String representing a port or a set of ports (eg. “80”, or “80,8080”), or
@ref{a65,,None}.
@end deffn

@geindex domain (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie domain}@anchor{43b4}
@deffn {Ιδιότητα} Cookie.domain

Cookie domain (a string).
@end deffn

@geindex path (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie path}@anchor{43b5}
@deffn {Ιδιότητα} Cookie.path

Cookie path (a string, eg. @code{'/acme/rocket_launchers'}).
@end deffn

@geindex secure (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie secure}@anchor{43b6}
@deffn {Ιδιότητα} Cookie.secure

@code{True} if cookie should only be returned over a secure connection.
@end deffn

@geindex expires (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie expires}@anchor{43b7}
@deffn {Ιδιότητα} Cookie.expires

Integer expiry date in seconds since epoch, or @ref{a65,,None}.  See also the
@ref{43b8,,is_expired()} method.
@end deffn

@geindex discard (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie discard}@anchor{43b9}
@deffn {Ιδιότητα} Cookie.discard

@code{True} if this is a session cookie.
@end deffn

@geindex comment (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie comment}@anchor{43ba}
@deffn {Ιδιότητα} Cookie.comment

String comment from the server explaining the function of this cookie, or
@ref{a65,,None}.
@end deffn

@geindex comment_url (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie comment_url}@anchor{43bb}
@deffn {Ιδιότητα} Cookie.comment_url

URL linking to a comment from the server explaining the function of this cookie,
or @ref{a65,,None}.
@end deffn

@geindex rfc2109 (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie rfc2109}@anchor{43bc}
@deffn {Ιδιότητα} 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
@code{http.cookiejar} may “downgrade” RFC 2109 cookies to Netscape cookies, in
which case @ref{43b0,,version} is 0.
@end deffn

@geindex port_specified (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie port_specified}@anchor{43bd}
@deffn {Ιδιότητα} 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 (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie domain_specified}@anchor{43be}
@deffn {Ιδιότητα} Cookie.domain_specified

@code{True} if a domain was explicitly specified by the server.
@end deffn

@geindex domain_initial_dot (ιδιότητα της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie domain_initial_dot}@anchor{43bf}
@deffn {Ιδιότητα} 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() (μέθοδος της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie has_nonstandard_attr}@anchor{43c0}
@deffn {Μέθοδος} Cookie.has_nonstandard_attr (name)

Return @code{True} if cookie has the named cookie-attribute.
@end deffn

@geindex get_nonstandard_attr() (μέθοδος της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie get_nonstandard_attr}@anchor{43c1}
@deffn {Μέθοδος} 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() (μέθοδος της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie set_nonstandard_attr}@anchor{43c2}
@deffn {Μέθοδος} Cookie.set_nonstandard_attr (name, value)

Set the value of the named cookie-attribute.
@end deffn

The @ref{4382,,Cookie} class also defines the following method:

@geindex is_expired() (μέθοδος της http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie is_expired}@anchor{43b8}
@deffn {Μέθοδος} 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 Examples<26>,,Cookie Objects<2>,http cookiejar — Cookie handling for HTTP clients
@anchor{library/http cookiejar examples}@anchor{43c3}
@subsubsection Examples


The first example shows the most common usage of @code{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{1fe3,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xmlrpc — XMLRPC server and client modules,xmlrpc client — XML-RPC client access,http cookiejar — Cookie handling for HTTP clients,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/xmlrpc doc}@anchor{43c4}@anchor{library/xmlrpc module-xmlrpc}@anchor{136}@anchor{library/xmlrpc translation-repo}@anchor{43c5}@anchor{library/xmlrpc xmlrpc-xmlrpc-server-and-client-modules}@anchor{43c6}
@subsection @code{xmlrpc} — XMLRPC server and client modules


@geindex module; xmlrpc

XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP 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.

@code{xmlrpc} is a package that collects server and client modules implementing
XML-RPC.  The modules are:


@itemize *

@item 
@ref{137,,xmlrpc.client}

@item 
@ref{138,,xmlrpc.server}
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xmlrpc client — XML-RPC client access,xmlrpc server — Basic XML-RPC servers,xmlrpc — XMLRPC server and client modules,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/xmlrpc client doc}@anchor{43c7}@anchor{library/xmlrpc client module-xmlrpc client}@anchor{137}@anchor{library/xmlrpc client translation-repo}@anchor{43c8}@anchor{library/xmlrpc client xmlrpc-client-xml-rpc-client-access}@anchor{43c9}
@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/main/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 Προειδοποίηση 
The @code{xmlrpc.client} module is not secure against maliciously
constructed data.  If you need to parse untrusted or unauthenticated data,
see @ref{3f34,,XML security}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.5: For HTTPS URIs, @code{xmlrpc.client} now performs all the necessary
certificate and hostname checks by default.


@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

@geindex ServerProxy (κλάση σε xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client ServerProxy}@anchor{e1b}
@deffn {Κλάση} xmlrpc.client.ServerProxy (uri, transport=None, encoding=None, verbose=False, allow_none=False, use_datetime=False, use_builtin_types=False, *, headers=(), context=None)

A @code{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{291,,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{6e7,,datetime.datetime} objects and binary data to be
presented as @ref{1c7,,bytes} objects; this flag is false by default.
@code{datetime.datetime}, @code{bytes} and @ref{1c6,,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')]}).
If an HTTPS URL is provided, `context' may be @ref{336,,ssl.SSLContext}
and configures the SSL settings of the underlying HTTPS connection.
The obsolete `use_datetime' flag is similar to `use_builtin_types' but it
applies only to date/time values.


Άλλαξε στην έκδοση 3.3: The `use_builtin_types' flag was added.



Άλλαξε στην έκδοση 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.

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

Python type

@item

@code{boolean}

@tab

@ref{5ef,,bool}

@item

@code{int}, @code{i1},
@code{i2},  @code{i4},
@code{i8} or
@code{biginteger}

@tab

@ref{326,,int} in range from -2147483648 to 2147483647.
Values get the @code{<int>} tag.

@item

@code{double} or
@code{float}

@tab

@ref{327,,float}.  Values get the @code{<double>} tag.

@item

@code{string}

@tab

@ref{1df,,str}

@item

@code{array}

@tab

@ref{4d9,,list} or @ref{1ce,,tuple} containing
conformable elements.  Arrays are returned as
@code{lists}.

@item

@code{struct}

@tab

@ref{188,,dict}.  Keys must be strings, values may be
any conformable type.  Objects of user-defined
classes can be passed in; only their
@ref{1bf,,__dict__} attribute is transmitted.

@item

@code{dateTime.iso8601}

@tab

@ref{1786,,DateTime} or @ref{6e7,,datetime.datetime}.
Returned type depends on values of
`use_builtin_types' and `use_datetime' flags.

@item

@code{base64}

@tab

@ref{43ca,,Binary}, @ref{1c7,,bytes} or
@ref{1c6,,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{1c2,,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{43cb,,Fault} instance, used to signal XML-RPC server errors, or
@ref{43cc,,ProtocolError} used to signal an error in the HTTP/HTTPS transport layer.
Both @code{Fault} and @code{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{1c7,,bytes} or @ref{1c6,,bytearray} classes or the
@ref{43ca,,Binary} wrapper class described below.

@code{Server} is retained as an alias for @code{ServerProxy} for backwards
compatibility.  New code should use @code{ServerProxy}.


Άλλαξε στην έκδοση 3.5: Added the `context' argument.



Άλλαξε στην έκδοση 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 Δείτε επίσης



@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:: 
* DateTime Objects:: 
* 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,DateTime Objects,,xmlrpc client — XML-RPC client access
@anchor{library/xmlrpc client id1}@anchor{43cd}@anchor{library/xmlrpc client serverproxy-objects}@anchor{43ce}
@subsubsection ServerProxy Objects


A @ref{e1b,,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 either
by returning data in a conformant type or by raising a @ref{43cb,,Fault} or
@ref{43cc,,ProtocolError} exception indicating an error.

Servers that support the XML introspection API support some common methods
grouped under the reserved @code{system} attribute:

@geindex listMethods() (μέθοδος της xmlrpc.client.ServerProxy.system)
@anchor{library/xmlrpc client xmlrpc client ServerProxy system listMethods}@anchor{43cf}
@deffn {Μέθοδος} 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() (μέθοδος της xmlrpc.client.ServerProxy.system)
@anchor{library/xmlrpc client xmlrpc client ServerProxy system methodSignature}@anchor{43d0}
@deffn {Μέθοδος} 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() (μέθοδος της xmlrpc.client.ServerProxy.system)
@anchor{library/xmlrpc client xmlrpc client ServerProxy system methodHelp}@anchor{43d1}
@deffn {Μέθοδος} 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


Άλλαξε στην έκδοση 3.5: Instances of @ref{e1b,,ServerProxy} support the @ref{478,,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 DateTime Objects,Binary Objects,ServerProxy Objects,xmlrpc client — XML-RPC client access
@anchor{library/xmlrpc client datetime-objects}@anchor{43d2}@anchor{library/xmlrpc client id2}@anchor{43d3}
@subsubsection DateTime Objects


@geindex DateTime (κλάση σε xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client DateTime}@anchor{1786}
@deffn {Κλάση} 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{6e7,,datetime.datetime}
instance.  It has the following methods, supported mainly for internal
use by the marshalling/unmarshalling code:

@geindex decode() (μέθοδος της xmlrpc.client.DateTime)
@anchor{library/xmlrpc client xmlrpc client DateTime decode}@anchor{43d4}
@deffn {Μέθοδος} decode (string)

Accept a string as the instance’s new time value.
@end deffn

@geindex encode() (μέθοδος της xmlrpc.client.DateTime)
@anchor{library/xmlrpc client xmlrpc client DateTime encode}@anchor{43d5}
@deffn {Μέθοδος} encode (out)

Write the XML-RPC encoding of this @code{DateTime} item to the `out' stream
object.
@end deffn

It also supports certain of Python’s built-in operators through
@ref{1645,,rich comparison} and @ref{1bc,,__repr__()}
methods.
@end deffn

A working example follows. The server code:

@example
import datetime as dt
from xmlrpc.server import SimpleXMLRPCServer
import xmlrpc.client

def today():
    today = dt.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 as dt

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")

today = proxy.today()
# convert the ISO 8601 string to a datetime object
converted = dt.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")
print(f"Today: @{converted.strftime('%d.%m.%Y, %H:%M')@}")
@end example

@node Binary Objects,Fault Objects,DateTime Objects,xmlrpc client — XML-RPC client access
@anchor{library/xmlrpc client binary-objects}@anchor{43d6}@anchor{library/xmlrpc client id3}@anchor{43d7}
@subsubsection Binary Objects


@geindex Binary (κλάση σε xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client Binary}@anchor{43ca}
@deffn {Κλάση} xmlrpc.client.Binary

This class may be initialized from bytes data (which may include NULs). The
primary access to the content of a @code{Binary} object is provided by an
attribute:

@geindex data (ιδιότητα της xmlrpc.client.Binary)
@anchor{library/xmlrpc client xmlrpc client Binary data}@anchor{43d8}
@deffn {Ιδιότητα} data

The binary data encapsulated by the @code{Binary} instance.  The data is
provided as a @ref{1c7,,bytes} object.
@end deffn

@code{Binary} objects have the following methods, supported mainly for
internal use by the marshalling/unmarshalling code:

@geindex decode() (μέθοδος της xmlrpc.client.Binary)
@anchor{library/xmlrpc client xmlrpc client Binary decode}@anchor{43d9}
@deffn {Μέθοδος} decode (bytes)

Accept a base64 @ref{1c7,,bytes} object and decode it as the instance’s new data.
@end deffn

@geindex encode() (μέθοδος της xmlrpc.client.Binary)
@anchor{library/xmlrpc client xmlrpc client Binary encode}@anchor{43da}
@deffn {Μέθοδος} 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{ec0,,__eq__()} and @ref{18b9,,__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{43db}@anchor{library/xmlrpc client id4}@anchor{43dc}
@subsubsection Fault Objects


@geindex Fault (κλάση σε xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client Fault}@anchor{43cb}
@deffn {Κλάση} xmlrpc.client.Fault

A @code{Fault} object encapsulates the content of an XML-RPC fault tag. Fault
objects have the following attributes:

@geindex faultCode (ιδιότητα της xmlrpc.client.Fault)
@anchor{library/xmlrpc client xmlrpc client Fault faultCode}@anchor{43dd}
@deffn {Ιδιότητα} faultCode

An int indicating the fault type.
@end deffn

@geindex faultString (ιδιότητα της xmlrpc.client.Fault)
@anchor{library/xmlrpc client xmlrpc client Fault faultString}@anchor{43de}
@deffn {Ιδιότητα} 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{43cb,,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{43df}@anchor{library/xmlrpc client protocolerror-objects}@anchor{43e0}
@subsubsection ProtocolError Objects


@geindex ProtocolError (κλάση σε xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client ProtocolError}@anchor{43cc}
@deffn {Κλάση} xmlrpc.client.ProtocolError

A @code{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 (ιδιότητα της xmlrpc.client.ProtocolError)
@anchor{library/xmlrpc client xmlrpc client ProtocolError url}@anchor{43e1}
@deffn {Ιδιότητα} url

The URI or URL that triggered the error.
@end deffn

@geindex errcode (ιδιότητα της xmlrpc.client.ProtocolError)
@anchor{library/xmlrpc client xmlrpc client ProtocolError errcode}@anchor{43e2}
@deffn {Ιδιότητα} errcode

The error code.
@end deffn

@geindex errmsg (ιδιότητα της xmlrpc.client.ProtocolError)
@anchor{library/xmlrpc client xmlrpc client ProtocolError errmsg}@anchor{43e3}
@deffn {Ιδιότητα} errmsg

The error message or diagnostic string.
@end deffn

@geindex headers (ιδιότητα της xmlrpc.client.ProtocolError)
@anchor{library/xmlrpc client xmlrpc client ProtocolError headers}@anchor{43e4}
@deffn {Ιδιότητα} 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{43cc,,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{43e5}
@subsubsection MultiCall Objects


The @ref{43e6,,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 (κλάση σε xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client MultiCall}@anchor{43e6}
@deffn {Κλάση} 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 arguments in the
@code{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{1409,,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{43e7}
@subsubsection Convenience Functions


@geindex dumps() (στη μονάδα xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client dumps}@anchor{43e8}
@deffn {Συνάρτηση} 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{43cb,,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{a65,,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() (στη μονάδα xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client loads}@anchor{17d7}
@deffn {Συνάρτηση} 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{43cb,,Fault} exception.
The `use_builtin_types' flag can be used to cause date/time values to be
presented as @ref{6e7,,datetime.datetime} objects and binary data to be
presented as @ref{1c7,,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.


Άλλαξε στην έκδοση 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{43e9}@anchor{library/xmlrpc client xmlrpc-client-example}@anchor{43ea}
@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{43eb}
@subsubsection Example of Client and Server Usage


See @ref{43ec,,SimpleXMLRPCServer example}.

@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)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xmlrpc server — Basic XML-RPC servers,ipaddress — IPv4/IPv6 manipulation library,xmlrpc client — XML-RPC client access,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/xmlrpc server doc}@anchor{43ed}@anchor{library/xmlrpc server module-xmlrpc server}@anchor{138}@anchor{library/xmlrpc server translation-repo}@anchor{43ee}@anchor{library/xmlrpc server xmlrpc-server-basic-xml-rpc-servers}@anchor{43ef}
@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/main/Lib/xmlrpc/server.py}


__________________________________________________________________


The @code{xmlrpc.server} module provides a basic server framework for XML-RPC
servers written in Python.  Servers can either be free standing, using
@ref{43f0,,SimpleXMLRPCServer}, or embedded in a CGI environment, using
@ref{43f1,,CGIXMLRPCRequestHandler}.

@cartouche
@quotation Προειδοποίηση 
The @code{xmlrpc.server} module is not secure against maliciously
constructed data.  If you need to parse untrusted or unauthenticated data,
see @ref{3f34,,XML security}.
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

@geindex SimpleXMLRPCServer (κλάση σε xmlrpc.server)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCServer}@anchor{43f0}
@deffn {Κλάση} 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{16cc,,SimpleXMLRPCRequestHandler}.  The `addr' and `requestHandler' parameters
are passed to the @ref{16c4,,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{137,,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{17d7,,loads()} function and controls which types are processed
when date/times values or binary data are received; it defaults to false.


Άλλαξε στην έκδοση 3.3: The `use_builtin_types' flag was added.

@end deffn

@geindex CGIXMLRPCRequestHandler (κλάση σε xmlrpc.server)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler}@anchor{43f1}
@deffn {Κλάση} 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{137,,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{17d7,,loads()} function and controls which types are processed
when date/times values or binary data are received; it defaults to false.


Άλλαξε στην έκδοση 3.3: The `use_builtin_types' flag was added.

@end deffn

@geindex SimpleXMLRPCRequestHandler (κλάση σε xmlrpc.server)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCRequestHandler}@anchor{16cc}
@deffn {Κλάση} 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{43f0,,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{43f2}@anchor{library/xmlrpc server simplexmlrpcserver-objects}@anchor{43f3}
@subsubsection SimpleXMLRPCServer objects


The @ref{43f0,,SimpleXMLRPCServer} class is based on
@ref{16c4,,socketserver.TCPServer} and provides a means of creating simple, stand
alone XML-RPC servers.

@geindex register_function() (μέθοδος της xmlrpc.server.SimpleXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCServer register_function}@anchor{43f4}
@deffn {Μέθοδος} 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{1679,,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{1679,,function.__name__} will be used.


Άλλαξε στην έκδοση 3.7: @code{register_function()} can be used as a decorator.

@end deffn

@geindex register_instance() (μέθοδος της xmlrpc.server.SimpleXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCServer register_instance}@anchor{43f5}
@deffn {Μέθοδος} 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{43f4,,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 Προειδοποίηση 
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() (μέθοδος της xmlrpc.server.SimpleXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCServer register_introspection_functions}@anchor{43f6}
@deffn {Μέθοδος} 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() (μέθοδος της xmlrpc.server.SimpleXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCServer register_multicall_functions}@anchor{43f7}
@deffn {Μέθοδος} SimpleXMLRPCServer.register_multicall_functions ()

Registers the XML-RPC multicall function system.multicall.
@end deffn

@geindex rpc_paths (ιδιότητα της xmlrpc.server.SimpleXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCRequestHandler rpc_paths}@anchor{43f8}
@deffn {Ιδιότητα} 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{43f9}@anchor{library/xmlrpc server simplexmlrpcserver-example}@anchor{43ec}
@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 Προειδοποίηση 
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 within a secure, closed network.
@end quotation
@end cartouche

@example
import datetime as dt

class ExampleService:
    def getData(self):
        return '42'

    class currentTime:
        @@staticmethod
        def getCurrentTime():
            return dt.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{43fa}
@subsubsection CGIXMLRPCRequestHandler


The @ref{43f1,,CGIXMLRPCRequestHandler} class can be used to handle XML-RPC
requests sent to Python CGI scripts.

@geindex register_function() (μέθοδος της xmlrpc.server.CGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler register_function}@anchor{43fb}
@deffn {Μέθοδος} 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{1679,,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{1679,,function.__name__} will be used.


Άλλαξε στην έκδοση 3.7: @code{register_function()} can be used as a decorator.

@end deffn

@geindex register_instance() (μέθοδος της xmlrpc.server.CGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler register_instance}@anchor{43fc}
@deffn {Μέθοδος} CGIXMLRPCRequestHandler.register_instance (instance)

Register an object which is used to expose method names  which have not been
registered using @ref{43fb,,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() (μέθοδος της xmlrpc.server.CGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler register_introspection_functions}@anchor{43fd}
@deffn {Μέθοδος} 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() (μέθοδος της xmlrpc.server.CGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler register_multicall_functions}@anchor{43fe}
@deffn {Μέθοδος} CGIXMLRPCRequestHandler.register_multicall_functions ()

Register the XML-RPC multicall function @code{system.multicall}.
@end deffn

@geindex handle_request() (μέθοδος της xmlrpc.server.CGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler handle_request}@anchor{43ff}
@deffn {Μέθοδος} 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

Example:

@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{4400}
@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{1f97,,DocXMLRPCServer}, or embedded in a CGI environment, using
@ref{4401,,DocCGIXMLRPCRequestHandler}.

@geindex DocXMLRPCServer (κλάση σε xmlrpc.server)
@anchor{library/xmlrpc server xmlrpc server DocXMLRPCServer}@anchor{1f97}
@deffn {Κλάση} 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{43f0,,SimpleXMLRPCServer}; `requestHandler' defaults to
@ref{4402,,DocXMLRPCRequestHandler}.


Άλλαξε στην έκδοση 3.3: The `use_builtin_types' flag was added.

@end deffn

@geindex DocCGIXMLRPCRequestHandler (κλάση σε xmlrpc.server)
@anchor{library/xmlrpc server xmlrpc server DocCGIXMLRPCRequestHandler}@anchor{4401}
@deffn {Κλάση} xmlrpc.server.DocCGIXMLRPCRequestHandler

Create a new instance to handle XML-RPC requests in a CGI environment.
@end deffn

@geindex DocXMLRPCRequestHandler (κλάση σε xmlrpc.server)
@anchor{library/xmlrpc server xmlrpc server DocXMLRPCRequestHandler}@anchor{4402}
@deffn {Κλάση} 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{1f97,,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{4403}@anchor{library/xmlrpc server docxmlrpcserver-objects}@anchor{4404}
@subsubsection DocXMLRPCServer objects


The @ref{1f97,,DocXMLRPCServer} class is derived from @ref{43f0,,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() (μέθοδος της xmlrpc.server.DocXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server DocXMLRPCServer set_server_title}@anchor{4405}
@deffn {Μέθοδος} 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() (μέθοδος της xmlrpc.server.DocXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server DocXMLRPCServer set_server_name}@anchor{4406}
@deffn {Μέθοδος} 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() (μέθοδος της xmlrpc.server.DocXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server DocXMLRPCServer set_server_documentation}@anchor{4407}
@deffn {Μέθοδος} 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{4408}
@subsubsection DocCGIXMLRPCRequestHandler


The @ref{4401,,DocCGIXMLRPCRequestHandler} class is derived from
@ref{43f1,,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() (μέθοδος της xmlrpc.server.DocCGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server DocCGIXMLRPCRequestHandler set_server_title}@anchor{4409}
@deffn {Μέθοδος} 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() (μέθοδος της xmlrpc.server.DocCGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server DocCGIXMLRPCRequestHandler set_server_name}@anchor{440a}
@deffn {Μέθοδος} 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() (μέθοδος της xmlrpc.server.DocCGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server DocCGIXMLRPCRequestHandler set_server_documentation}@anchor{440b}
@deffn {Μέθοδος} 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node ipaddress — IPv4/IPv6 manipulation library,,xmlrpc server — Basic XML-RPC servers,Πρωτόκολλα Internet και Υποστήριξη
@anchor{library/ipaddress doc}@anchor{440c}@anchor{library/ipaddress ipaddress-ipv4-ipv6-manipulation-library}@anchor{440d}@anchor{library/ipaddress module-ipaddress}@anchor{83}@anchor{library/ipaddress translation-repo}@anchor{440e}
@subsection @code{ipaddress} — IPv4/IPv6 manipulation library


@geindex module; ipaddress

`Source code:' Lib/ipaddress.py@footnote{https://github.com/python/cpython/tree/main/Lib/ipaddress.py}


__________________________________________________________________


@code{ipaddress} provides the capabilities to create, manipulate and
operate on IPv4 and IPv6 addresses and networks.

The functions and classes in this module make it straightforward to handle
various tasks related to IP addresses, including checking whether or not two
hosts are on the same subnet, iterating over all hosts in a particular
subnet, checking whether or not a string represents a valid IP address or
network definition, and so on.

This is the full module API reference—for an overview and introduction, see
@ref{440f,,An introduction to the ipaddress module}.


Added in version 3.3.


@c import ipaddress
@c from ipaddress import (
@c     ip_network, IPv4Address, IPv4Interface, IPv4Network,
@c )

@menu
* Convenience factory functions:: 
* IP Addresses:: 
* IP Network definitions:: 
* Interface objects:: 
* Other Module Level Functions:: 
* Custom Exceptions:: 

@end menu

@node Convenience factory functions,IP Addresses,,ipaddress — IPv4/IPv6 manipulation library
@anchor{library/ipaddress convenience-factory-functions}@anchor{4410}
@subsubsection Convenience factory functions


The @code{ipaddress} module provides factory functions to conveniently create
IP addresses, networks and interfaces:

@geindex ip_address() (στη μονάδα ipaddress)
@anchor{library/ipaddress ipaddress ip_address}@anchor{4411}
@deffn {Συνάρτηση} ipaddress.ip_address (address)

Return an @ref{710,,IPv4Address} or @ref{711,,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{277,,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() (στη μονάδα ipaddress)
@anchor{library/ipaddress ipaddress ip_network}@anchor{4412}
@deffn {Συνάρτηση} ipaddress.ip_network (address, strict=True)

Return an @ref{712,,IPv4Network} or @ref{713,,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 @code{IPv4Network} or @code{IPv6Network} constructor.  A
@ref{277,,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() (στη μονάδα ipaddress)
@anchor{library/ipaddress ipaddress ip_interface}@anchor{4413}
@deffn {Συνάρτηση} ipaddress.ip_interface (address)

Return an @ref{1d94,,IPv4Interface} or @ref{1d95,,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{277,,ValueError} is raised if `address' does not represent a valid IPv4 or
IPv6 address.
@end deffn

One downside of these convenience functions is that the need to handle both
IPv4 and IPv6 formats means that error messages provide minimal
information on the precise error, as the functions don’t know whether the
IPv4 or IPv6 format was intended. More detailed error reporting can be
obtained by calling the appropriate version specific class constructors
directly.

@node IP Addresses,IP Network definitions,Convenience factory functions,ipaddress — IPv4/IPv6 manipulation library
@anchor{library/ipaddress ip-addresses}@anchor{4414}
@subsubsection IP Addresses


@menu
* Address objects:: 
* Conversion to Strings and Integers:: 
* Operators: Operators<2>. 

@end menu

@node Address objects,Conversion to Strings and Integers,,IP Addresses
@anchor{library/ipaddress address-objects}@anchor{4415}
@subsubsection Address objects


The @ref{710,,IPv4Address} and @ref{711,,IPv6Address} objects share a lot of common
attributes.  Some attributes that are only meaningful for IPv6 addresses are
also implemented by @code{IPv4Address} objects, in order to make it easier to
write code that handles both IP versions correctly.  Address objects are
@ref{183,,hashable}, so they can be used as keys in dictionaries.

@geindex IPv4Address (κλάση σε ipaddress)
@anchor{library/ipaddress ipaddress IPv4Address}@anchor{710}
@deffn {Κλάση} ipaddress.IPv4Address (address)

Construct an IPv4 address.  An @ref{4416,,AddressValueError} is raised if
`address' is not a valid IPv4 address.

The following constitutes a valid IPv4 address:


@enumerate 

@item 
A string in decimal-dot notation, consisting of four decimal integers in
the inclusive range 0–255, separated by dots (e.g. @code{192.168.0.1}). Each
integer represents an octet (byte) in the address. Leading zeroes are
not tolerated to prevent confusion with octal notation.

@item 
An integer that fits into 32 bits.

@item 
An integer packed into a @ref{1c7,,bytes} object of length 4 (most
significant octet first).
@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


Άλλαξε στην έκδοση 3.8: Leading zeros are tolerated, even in ambiguous cases that look like
octal notation.



Άλλαξε στην έκδοση 3.9.5: Leading zeros are no longer tolerated and are treated as an error.
IPv4 address strings are now parsed as strict as glibc
@ref{d2c,,inet_pton()}.


@geindex version (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address version}@anchor{4417}
@deffn {Ιδιότητα} version

The appropriate version number: @code{4} for IPv4, @code{6} for IPv6.


Άλλαξε στην έκδοση 3.14: Made available on the class.

@end deffn

@geindex max_prefixlen (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address max_prefixlen}@anchor{4418}
@deffn {Ιδιότητα} max_prefixlen

The total number of bits in the address representation for this
version: @code{32} for IPv4, @code{128} for IPv6.

The prefix defines the number of leading bits in an  address that
are compared to determine whether or not an address is part of a
network.


Άλλαξε στην έκδοση 3.14: Made available on the class.

@end deffn

@geindex compressed (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address compressed}@anchor{4419}
@deffn {Ιδιότητα} compressed
@end deffn

@geindex exploded (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address exploded}@anchor{441a}
@deffn {Ιδιότητα} exploded

The string representation in dotted decimal notation. Leading zeroes
are never included in the representation.

As IPv4 does not define a shorthand notation for addresses with octets
set to zero, these two attributes are always the same as @code{str(addr)}
for IPv4 addresses. Exposing these attributes makes it easier to
write display code that can handle both IPv4 and IPv6 addresses.
@end deffn

@geindex packed (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address packed}@anchor{441b}
@deffn {Ιδιότητα} packed

The binary representation of this address - a @ref{1c7,,bytes} object of
the appropriate length (most significant octet first). This is 4 bytes
for IPv4 and 16 bytes for IPv6.
@end deffn

@geindex reverse_pointer (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address reverse_pointer}@anchor{11d3}
@deffn {Ιδιότητα} reverse_pointer

The name of the reverse DNS PTR record for the IP address, e.g.:

@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

This is the name that could be used for performing a PTR lookup, not the
resolved hostname itself.


Added in version 3.5.

@end deffn

@geindex is_multicast (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_multicast}@anchor{441c}
@deffn {Ιδιότητα} is_multicast

@code{True} if the address is reserved for multicast use.  See
@geindex RFC; RFC 3171
RFC 3171@footnote{https://datatracker.ietf.org/doc/html/rfc3171.html} (for IPv4) or 
@geindex RFC; RFC 2373
RFC 2373@footnote{https://datatracker.ietf.org/doc/html/rfc2373.html} (for IPv6).
@end deffn

@geindex is_private (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_private}@anchor{1bcd}
@deffn {Ιδιότητα} 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{441d,,IPv6Address.ipv4_mapped}):

@example
address.is_private == address.ipv4_mapped.is_private
@end example
@end itemize

@code{is_private} has value opposite to @ref{1309,,is_global}, except for the shared address space
(@code{100.64.0.0/10} range) where they are both @code{False}.


Άλλαξε στην έκδοση 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 (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_global}@anchor{1309}
@deffn {Ιδιότητα} 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{441d,,IPv6Address.ipv4_mapped}):

@example
address.is_global == address.ipv4_mapped.is_global
@end example

@code{is_global} has value opposite to @ref{1bcd,,is_private}, except for the shared address space
(@code{100.64.0.0/10} range) where they are both @code{False}.


Added in version 3.4.



Άλλαξε στην έκδοση 3.13: Fixed some false positives and false negatives, see @ref{1bcd,,is_private} for details.

@end deffn

@geindex is_unspecified (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_unspecified}@anchor{441e}
@deffn {Ιδιότητα} is_unspecified

@code{True} if the address is unspecified.  See 
@geindex RFC; RFC 5735
RFC 5735@footnote{https://datatracker.ietf.org/doc/html/rfc5735.html} (for IPv4)
or 
@geindex RFC; RFC 2373
RFC 2373@footnote{https://datatracker.ietf.org/doc/html/rfc2373.html} (for IPv6).
@end deffn

@geindex is_reserved (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_reserved}@anchor{441f}
@deffn {Ιδιότητα} is_reserved

@code{True} if the address is noted as reserved by the IETF.
For IPv4, this is only @code{240.0.0.0/4}, the @code{Reserved} address block.
For IPv6, this is all addresses allocated@footnote{https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.xhtml} as
@code{Reserved by IETF} for future use.

@cartouche
@quotation Σημείωση 
For IPv4, @code{is_reserved} is not related to the address block value of the
@code{Reserved-by-Protocol} column in iana-ipv4-special-registry@footnote{https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml}.
@end quotation
@end cartouche

@cartouche
@quotation Προσοχή 
For IPv6, @code{fec0::/10} a former Site-Local scoped address prefix is
currently excluded from that list (see @ref{4420,,is_site_local} & 
@geindex RFC; RFC 3879
RFC 3879@footnote{https://datatracker.ietf.org/doc/html/rfc3879.html}).
@end quotation
@end cartouche
@end deffn

@geindex is_loopback (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_loopback}@anchor{4421}
@deffn {Ιδιότητα} is_loopback

@code{True} if this is a loopback address.  See 
@geindex RFC; RFC 3330
RFC 3330@footnote{https://datatracker.ietf.org/doc/html/rfc3330.html} (for IPv4)
or 
@geindex RFC; RFC 2373
RFC 2373@footnote{https://datatracker.ietf.org/doc/html/rfc2373.html} (for IPv6).
@end deffn

@geindex is_link_local (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_link_local}@anchor{4422}
@deffn {Ιδιότητα} is_link_local

@code{True} if the address is reserved for link-local usage.  See
@geindex RFC; RFC 3927
RFC 3927@footnote{https://datatracker.ietf.org/doc/html/rfc3927.html}.
@end deffn

@geindex ipv6_mapped (ιδιότητα της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address ipv6_mapped}@anchor{70f}
@deffn {Ιδιότητα} ipv6_mapped

@code{IPv4Address} object representing the IPv4-mapped IPv6 address. See 
@geindex RFC; RFC 4291
RFC 4291@footnote{https://datatracker.ietf.org/doc/html/rfc4291.html}.


Added in version 3.13.

@end deffn
@end deffn

@geindex __format__() (μέθοδος της ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address __format__}@anchor{4423}
@deffn {Μέθοδος} IPv4Address.__format__ (fmt)

Returns a string representation of the IP address, controlled by
an explicit format string.
`fmt' can be one of the following: @code{'s'}, the default option,
equivalent to @ref{1df,,str()}, @code{'b'} for a zero-padded binary string,
@code{'X'} or @code{'x'} for an uppercase or lowercase hexadecimal
representation, or @code{'n'}, which is equivalent to @code{'b'} for IPv4
addresses and @code{'x'} for IPv6. For binary and hexadecimal
representations, the form specifier @code{'#'} and the grouping option
@code{'_'} are available. @code{__format__} is used by @code{format}, @code{str.format}
and 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


Added in version 3.9.

@end deffn

@geindex IPv6Address (κλάση σε ipaddress)
@anchor{library/ipaddress ipaddress IPv6Address}@anchor{711}
@deffn {Κλάση} ipaddress.IPv6Address (address)

Construct an IPv6 address.  An @ref{4416,,AddressValueError} is raised if
`address' is not a valid IPv6 address.

The following constitutes a valid IPv6 address:


@enumerate 

@item 
A string consisting of eight groups of four hexadecimal digits, each
group representing 16 bits.  The groups are separated by colons.
This describes an `exploded' (longhand) notation.  The string can
also be `compressed' (shorthand notation) by various means.  See
@geindex RFC; RFC 4291
RFC 4291@footnote{https://datatracker.ietf.org/doc/html/rfc4291.html} for details.  For example,
@code{"0000:0000:0000:0000:0000:0abc:0007:0def"} can be compressed to
@code{"::abc:7:def"}.

Optionally, the string may also have a scope zone ID, expressed
with a suffix @code{%scope_id}. If present, the scope ID must be non-empty,
and may not contain @code{%}.
See 
@geindex RFC; RFC 4007
RFC 4007@footnote{https://datatracker.ietf.org/doc/html/rfc4007.html} for details.
For example, @code{fe80::1234%1} might identify address @code{fe80::1234} on the first link of the node.

@item 
An integer that fits into 128 bits.

@item 
An integer packed into a @ref{1c7,,bytes} object of length 16, big-endian.
@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 (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address compressed}@anchor{4424}
@deffn {Ιδιότητα} compressed
@end deffn

The short form of the address representation, with leading zeroes in
groups omitted and the longest sequence of groups consisting entirely of
zeroes collapsed to a single empty group.

This is also the value returned by @code{str(addr)} for IPv6 addresses.

@geindex exploded (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address exploded}@anchor{4425}
@deffn {Ιδιότητα} exploded
@end deffn

The long form of the address representation, with all leading zeroes and
groups consisting entirely of zeroes included.

For the following attributes and methods, see the corresponding
documentation of the @ref{710,,IPv4Address} class:

@geindex packed (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address packed}@anchor{4426}
@deffn {Ιδιότητα} packed
@end deffn

@geindex reverse_pointer (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address reverse_pointer}@anchor{1b54}
@deffn {Ιδιότητα} reverse_pointer
@end deffn

@geindex version (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address version}@anchor{4427}
@deffn {Ιδιότητα} version
@end deffn

@geindex max_prefixlen (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address max_prefixlen}@anchor{4428}
@deffn {Ιδιότητα} max_prefixlen
@end deffn

@geindex is_multicast (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_multicast}@anchor{4429}
@deffn {Ιδιότητα} is_multicast
@end deffn

@geindex is_private (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_private}@anchor{1bce}
@deffn {Ιδιότητα} is_private
@end deffn

@geindex is_global (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_global}@anchor{1bcf}
@deffn {Ιδιότητα} is_global


Added in version 3.4.

@end deffn

@geindex is_unspecified (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_unspecified}@anchor{442a}
@deffn {Ιδιότητα} is_unspecified
@end deffn

@geindex is_reserved (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_reserved}@anchor{442b}
@deffn {Ιδιότητα} is_reserved
@end deffn

@geindex is_loopback (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_loopback}@anchor{1bb4}
@deffn {Ιδιότητα} is_loopback
@end deffn

@geindex is_link_local (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_link_local}@anchor{442c}
@deffn {Ιδιότητα} is_link_local
@end deffn

@geindex is_site_local (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_site_local}@anchor{4420}
@deffn {Ιδιότητα} is_site_local

@code{True} if the address is reserved for site-local usage.  Note that
the site-local address space has been deprecated by 
@geindex RFC; RFC 3879
RFC 3879@footnote{https://datatracker.ietf.org/doc/html/rfc3879.html}. Use
@ref{1bcd,,is_private} to test if this address is in the
space of unique local addresses as defined by 
@geindex RFC; RFC 4193
RFC 4193@footnote{https://datatracker.ietf.org/doc/html/rfc4193.html}.
@end deffn

@geindex ipv4_mapped (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address ipv4_mapped}@anchor{441d}
@deffn {Ιδιότητα} ipv4_mapped

For addresses that appear to be IPv4 mapped addresses in the range
@code{::FFFF:0:0/96} as defined by 
@geindex RFC; RFC 4291
RFC 4291@footnote{https://datatracker.ietf.org/doc/html/rfc4291.html}, this property reports the
embedded IPv4 address. For any other address, this property will be @code{None}.
@end deffn

@geindex scope_id (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address scope_id}@anchor{cdd}
@deffn {Ιδιότητα} scope_id

For scoped addresses as defined by 
@geindex RFC; RFC 4007
RFC 4007@footnote{https://datatracker.ietf.org/doc/html/rfc4007.html}, this property identifies
the particular zone of the address’s scope that the address belongs to,
as a string. When no scope zone is specified, this property will be @code{None}.
@end deffn

@geindex sixtofour (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address sixtofour}@anchor{442d}
@deffn {Ιδιότητα} sixtofour

For addresses that appear to be 6to4 addresses  (starting with
@code{2002::/16}) as defined by 
@geindex RFC; RFC 3056
RFC 3056@footnote{https://datatracker.ietf.org/doc/html/rfc3056.html}, this property will report
the embedded IPv4 address.  For any other address, this property will
be @code{None}.
@end deffn

@geindex teredo (ιδιότητα της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address teredo}@anchor{442e}
@deffn {Ιδιότητα} teredo

For addresses that appear to be Teredo addresses (starting with
@code{2001::/32}) as defined by 
@geindex RFC; RFC 4380
RFC 4380@footnote{https://datatracker.ietf.org/doc/html/rfc4380.html}, this property will report
the embedded @code{(server, client)} IP address pair.  For any other
address, this property will be @code{None}.
@end deffn
@end deffn

@geindex __format__() (μέθοδος της ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address __format__}@anchor{442f}
@deffn {Μέθοδος} IPv6Address.__format__ (fmt)

Refer to the corresponding method documentation in
@ref{710,,IPv4Address}.


Added in version 3.9.

@end deffn

@node Conversion to Strings and Integers,Operators<2>,Address objects,IP Addresses
@anchor{library/ipaddress conversion-to-strings-and-integers}@anchor{4430}
@subsubsection Conversion to Strings and Integers


To interoperate with networking interfaces such as the socket module,
addresses must be converted to strings or integers. This is handled using
the @ref{1df,,str()} and @ref{326,,int()} builtin functions:

@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 Operators<2>,,Conversion to Strings and Integers,IP Addresses
@anchor{library/ipaddress operators}@anchor{4431}
@subsubsection Operators


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
* Comparison operators:: 
* Arithmetic operators:: 

@end menu

@node Comparison operators,Arithmetic operators,,Operators<2>
@anchor{library/ipaddress comparison-operators}@anchor{4432}
@subsubsection Comparison operators


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 Arithmetic operators,,Comparison operators,Operators<2>
@anchor{library/ipaddress arithmetic-operators}@anchor{4433}
@subsubsection Arithmetic operators


Integers can be added to or subtracted from address objects.  Some examples:

@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 IP Network definitions,Interface objects,IP Addresses,ipaddress — IPv4/IPv6 manipulation library
@anchor{library/ipaddress ip-network-definitions}@anchor{4434}
@subsubsection IP Network definitions


The @ref{712,,IPv4Network} and @ref{713,,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
* Prefix@comma{} net mask and host mask: Prefix net mask and host mask. 
* Network objects:: 
* Operators: Operators<3>. 

@end menu

@node Prefix net mask and host mask,Network objects,,IP Network definitions
@anchor{library/ipaddress prefix-net-mask-and-host-mask}@anchor{4435}
@subsubsection Prefix, net mask and host mask


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 Network objects,Operators<3>,Prefix net mask and host mask,IP Network definitions
@anchor{library/ipaddress network-objects}@anchor{4436}
@subsubsection Network objects


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{712,,IPv4Network} and @ref{713,,IPv6Network},
so to avoid duplication they are only documented for @code{IPv4Network}.
Network objects are @ref{183,,hashable}, so they can be used as keys in
dictionaries.

@geindex IPv4Network (κλάση σε ipaddress)
@anchor{library/ipaddress ipaddress IPv4Network}@anchor{712}
@deffn {Κλάση} ipaddress.IPv4Network (address, strict=True)

Construct an IPv4 network definition.  `address' can be one of the following:


@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{1c7,,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 @ref{710,,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{4416,,AddressValueError} is raised if `address' is not a valid IPv4
address.  A @ref{4437,,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{277,,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{291,,TypeError} if the argument’s IP version is
incompatible to @code{self}.


Άλλαξε στην έκδοση 3.5: Added the two-tuple form for the `address' constructor parameter.


@geindex version (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network version}@anchor{4438}
@deffn {Ιδιότητα} version
@end deffn

@geindex max_prefixlen (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network max_prefixlen}@anchor{4439}
@deffn {Ιδιότητα} max_prefixlen

Refer to the corresponding attribute documentation in
@ref{710,,IPv4Address}.
@end deffn

@geindex is_multicast (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network is_multicast}@anchor{443a}
@deffn {Ιδιότητα} is_multicast
@end deffn

@geindex is_private (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network is_private}@anchor{443b}
@deffn {Ιδιότητα} is_private
@end deffn

@geindex is_unspecified (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network is_unspecified}@anchor{443c}
@deffn {Ιδιότητα} is_unspecified
@end deffn

@geindex is_reserved (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network is_reserved}@anchor{443d}
@deffn {Ιδιότητα} is_reserved
@end deffn

@geindex is_loopback (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network is_loopback}@anchor{443e}
@deffn {Ιδιότητα} is_loopback
@end deffn

@geindex is_link_local (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network is_link_local}@anchor{443f}
@deffn {Ιδιότητα} 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 (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network network_address}@anchor{4440}
@deffn {Ιδιότητα} 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 (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network broadcast_address}@anchor{4441}
@deffn {Ιδιότητα} 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 (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network hostmask}@anchor{4442}
@deffn {Ιδιότητα} hostmask

The host mask, as an @ref{710,,IPv4Address} object.
@end deffn

@geindex netmask (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network netmask}@anchor{4443}
@deffn {Ιδιότητα} netmask

The net mask, as an @ref{710,,IPv4Address} object.
@end deffn

@geindex with_prefixlen (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network with_prefixlen}@anchor{4444}
@deffn {Ιδιότητα} with_prefixlen
@end deffn

@geindex compressed (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network compressed}@anchor{4445}
@deffn {Ιδιότητα} compressed
@end deffn

@geindex exploded (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network exploded}@anchor{4446}
@deffn {Ιδιότητα} exploded

A string representation of the network, with the mask in prefix
notation.

@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 (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network with_netmask}@anchor{4447}
@deffn {Ιδιότητα} with_netmask

A string representation of the network, with the mask in net mask
notation.
@end deffn

@geindex with_hostmask (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network with_hostmask}@anchor{4448}
@deffn {Ιδιότητα} with_hostmask

A string representation of the network, with the mask in host mask
notation.
@end deffn

@geindex num_addresses (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network num_addresses}@anchor{4449}
@deffn {Ιδιότητα} num_addresses

The total number of addresses in the network.
@end deffn

@geindex prefixlen (ιδιότητα της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network prefixlen}@anchor{444a}
@deffn {Ιδιότητα} prefixlen

Length of the network prefix, in bits.
@end deffn

@geindex hosts() (μέθοδος της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network hosts}@anchor{19c4}
@deffn {Μέθοδος} 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() (μέθοδος της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network overlaps}@anchor{444b}
@deffn {Μέθοδος} overlaps (other)

@code{True} if this network is partly or wholly contained in `other' or
`other' is wholly contained in this network.
@end deffn

@geindex address_exclude() (μέθοδος της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network address_exclude}@anchor{444c}
@deffn {Μέθοδος} address_exclude (network)

Computes the network definitions resulting from removing the given
`network' from this one.  Returns an iterator of network objects.
Raises @ref{277,,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() (μέθοδος της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network subnets}@anchor{1251}
@deffn {Μέθοδος} 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() (μέθοδος της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network supernet}@anchor{1252}
@deffn {Μέθοδος} 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() (μέθοδος της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network subnet_of}@anchor{444d}
@deffn {Μέθοδος} subnet_of (other)

Return @code{True} if this network is a subnet of `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


Added in version 3.7.

@end deffn

@geindex supernet_of() (μέθοδος της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network supernet_of}@anchor{444e}
@deffn {Μέθοδος} supernet_of (other)

Return @code{True} if this network is a supernet of `other'.

@example
>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> a.supernet_of(b)
True
@end example


Added in version 3.7.

@end deffn

@geindex compare_networks() (μέθοδος της ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network compare_networks}@anchor{444f}
@deffn {Μέθοδος} 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


Αποσύρθηκε στην έκδοση 3.7: It uses the same ordering and comparison algorithm as «<», «==», and «>»

@end deffn
@end deffn

@geindex IPv6Network (κλάση σε ipaddress)
@anchor{library/ipaddress ipaddress IPv6Network}@anchor{713}
@deffn {Κλάση} ipaddress.IPv6Network (address, strict=True)

Construct an IPv6 network definition.  `address' can be one of the following:


@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{1c7,,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 @ref{711,,IPv6Address} object; and the netmask is an
integer representing the prefix length.
@end enumerate

An @ref{4416,,AddressValueError} is raised if `address' is not a valid IPv6
address.  A @ref{4437,,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{277,,ValueError} is raised.  Otherwise, the host bits are masked out
to determine the appropriate network address.


Άλλαξε στην έκδοση 3.5: Added the two-tuple form for the `address' constructor parameter.


@geindex version (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network version}@anchor{4450}
@deffn {Ιδιότητα} version
@end deffn

@geindex max_prefixlen (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network max_prefixlen}@anchor{4451}
@deffn {Ιδιότητα} max_prefixlen
@end deffn

@geindex is_multicast (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_multicast}@anchor{4452}
@deffn {Ιδιότητα} is_multicast
@end deffn

@geindex is_private (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_private}@anchor{4453}
@deffn {Ιδιότητα} is_private
@end deffn

@geindex is_unspecified (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_unspecified}@anchor{4454}
@deffn {Ιδιότητα} is_unspecified
@end deffn

@geindex is_reserved (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_reserved}@anchor{4455}
@deffn {Ιδιότητα} is_reserved
@end deffn

@geindex is_loopback (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_loopback}@anchor{4456}
@deffn {Ιδιότητα} is_loopback
@end deffn

@geindex is_link_local (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_link_local}@anchor{4457}
@deffn {Ιδιότητα} is_link_local
@end deffn

@geindex network_address (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network network_address}@anchor{4458}
@deffn {Ιδιότητα} network_address
@end deffn

@geindex broadcast_address (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network broadcast_address}@anchor{4459}
@deffn {Ιδιότητα} broadcast_address
@end deffn

@geindex hostmask (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network hostmask}@anchor{445a}
@deffn {Ιδιότητα} hostmask
@end deffn

@geindex netmask (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network netmask}@anchor{445b}
@deffn {Ιδιότητα} netmask
@end deffn

@geindex with_prefixlen (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network with_prefixlen}@anchor{445c}
@deffn {Ιδιότητα} with_prefixlen
@end deffn

@geindex compressed (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network compressed}@anchor{445d}
@deffn {Ιδιότητα} compressed
@end deffn

@geindex exploded (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network exploded}@anchor{445e}
@deffn {Ιδιότητα} exploded
@end deffn

@geindex with_netmask (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network with_netmask}@anchor{445f}
@deffn {Ιδιότητα} with_netmask
@end deffn

@geindex with_hostmask (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network with_hostmask}@anchor{4460}
@deffn {Ιδιότητα} with_hostmask
@end deffn

@geindex num_addresses (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network num_addresses}@anchor{4461}
@deffn {Ιδιότητα} num_addresses
@end deffn

@geindex prefixlen (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network prefixlen}@anchor{4462}
@deffn {Ιδιότητα} prefixlen
@end deffn

@geindex hosts() (μέθοδος της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network hosts}@anchor{19c5}
@deffn {Μέθοδος} 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() (μέθοδος της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network overlaps}@anchor{4463}
@deffn {Μέθοδος} overlaps (other)
@end deffn

@geindex address_exclude() (μέθοδος της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network address_exclude}@anchor{4464}
@deffn {Μέθοδος} address_exclude (network)
@end deffn

@geindex subnets() (μέθοδος της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network subnets}@anchor{4465}
@deffn {Μέθοδος} subnets (prefixlen_diff=1, new_prefix=None)
@end deffn

@geindex supernet() (μέθοδος της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network supernet}@anchor{4466}
@deffn {Μέθοδος} supernet (prefixlen_diff=1, new_prefix=None)
@end deffn

@geindex subnet_of() (μέθοδος της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network subnet_of}@anchor{4467}
@deffn {Μέθοδος} subnet_of (other)
@end deffn

@geindex supernet_of() (μέθοδος της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network supernet_of}@anchor{4468}
@deffn {Μέθοδος} supernet_of (other)
@end deffn

@geindex compare_networks() (μέθοδος της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network compare_networks}@anchor{4469}
@deffn {Μέθοδος} compare_networks (other)

Refer to the corresponding attribute documentation in
@ref{712,,IPv4Network}.
@end deffn

@geindex is_site_local (ιδιότητα της ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_site_local}@anchor{446a}
@deffn {Ιδιότητα} is_site_local

This 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 Operators<3>,,Network objects,IP Network definitions
@anchor{library/ipaddress id1}@anchor{446b}
@subsubsection Operators


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
* Logical operators:: 
* Iteration:: 
* Networks as containers of addresses:: 

@end menu

@node Logical operators,Iteration,,Operators<3>
@anchor{library/ipaddress logical-operators}@anchor{446c}
@subsubsection Logical operators


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 Iteration,Networks as containers of addresses,Logical operators,Operators<3>
@anchor{library/ipaddress iteration}@anchor{446d}
@subsubsection Iteration


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{19c4,,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 Networks as containers of addresses,,Iteration,Operators<3>
@anchor{library/ipaddress networks-as-containers-of-addresses}@anchor{446e}
@subsubsection Networks as containers of addresses


Network objects can act as containers of addresses.  Some examples:

@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 Interface objects,Other Module Level Functions,IP Network definitions,ipaddress — IPv4/IPv6 manipulation library
@anchor{library/ipaddress interface-objects}@anchor{446f}
@subsubsection Interface objects


Interface objects are @ref{183,,hashable}, so they can be used as keys in
dictionaries.

@geindex IPv4Interface (κλάση σε ipaddress)
@anchor{library/ipaddress ipaddress IPv4Interface}@anchor{1d94}
@deffn {Κλάση} ipaddress.IPv4Interface (address)

Construct an IPv4 interface.  The meaning of `address' is as in the
constructor of @ref{712,,IPv4Network}, except that arbitrary host addresses
are always accepted.

@code{IPv4Interface} is a subclass of @ref{710,,IPv4Address}, so it inherits
all the attributes from that class.  In addition, the following attributes
are available:

@geindex ip (ιδιότητα της ipaddress.IPv4Interface)
@anchor{library/ipaddress ipaddress IPv4Interface ip}@anchor{4470}
@deffn {Ιδιότητα} ip

The address (@ref{710,,IPv4Address}) without network information.

@example
>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.ip
IPv4Address('192.0.2.5')
@end example
@end deffn

@geindex network (ιδιότητα της ipaddress.IPv4Interface)
@anchor{library/ipaddress ipaddress IPv4Interface network}@anchor{4471}
@deffn {Ιδιότητα} network

The network (@ref{712,,IPv4Network}) this interface belongs to.

@example
>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.network
IPv4Network('192.0.2.0/24')
@end example
@end deffn

@geindex with_prefixlen (ιδιότητα της ipaddress.IPv4Interface)
@anchor{library/ipaddress ipaddress IPv4Interface with_prefixlen}@anchor{4472}
@deffn {Ιδιότητα} 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 (ιδιότητα της ipaddress.IPv4Interface)
@anchor{library/ipaddress ipaddress IPv4Interface with_netmask}@anchor{4473}
@deffn {Ιδιότητα} 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 (ιδιότητα της ipaddress.IPv4Interface)
@anchor{library/ipaddress ipaddress IPv4Interface with_hostmask}@anchor{4474}
@deffn {Ιδιότητα} 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 (κλάση σε ipaddress)
@anchor{library/ipaddress ipaddress IPv6Interface}@anchor{1d95}
@deffn {Κλάση} ipaddress.IPv6Interface (address)

Construct an IPv6 interface.  The meaning of `address' is as in the
constructor of @ref{713,,IPv6Network}, except that arbitrary host addresses
are always accepted.

@code{IPv6Interface} is a subclass of @ref{711,,IPv6Address}, so it inherits
all the attributes from that class.  In addition, the following attributes
are available:

@geindex ip (ιδιότητα της ipaddress.IPv6Interface)
@anchor{library/ipaddress ipaddress IPv6Interface ip}@anchor{4475}
@deffn {Ιδιότητα} ip
@end deffn

@geindex network (ιδιότητα της ipaddress.IPv6Interface)
@anchor{library/ipaddress ipaddress IPv6Interface network}@anchor{4476}
@deffn {Ιδιότητα} network
@end deffn

@geindex with_prefixlen (ιδιότητα της ipaddress.IPv6Interface)
@anchor{library/ipaddress ipaddress IPv6Interface with_prefixlen}@anchor{4477}
@deffn {Ιδιότητα} with_prefixlen
@end deffn

@geindex with_netmask (ιδιότητα της ipaddress.IPv6Interface)
@anchor{library/ipaddress ipaddress IPv6Interface with_netmask}@anchor{4478}
@deffn {Ιδιότητα} with_netmask
@end deffn

@geindex with_hostmask (ιδιότητα της ipaddress.IPv6Interface)
@anchor{library/ipaddress ipaddress IPv6Interface with_hostmask}@anchor{4479}
@deffn {Ιδιότητα} with_hostmask

Refer to the corresponding attribute documentation in
@ref{1d94,,IPv4Interface}.
@end deffn
@end deffn

@menu
* Operators: Operators<4>. 

@end menu

@node Operators<4>,,,Interface objects
@anchor{library/ipaddress id2}@anchor{447a}
@subsubsection Operators


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
* Logical operators: Logical operators<2>. 

@end menu

@node Logical operators<2>,,,Operators<4>
@anchor{library/ipaddress id3}@anchor{447b}
@subsubsection Logical operators


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 Other Module Level Functions,Custom Exceptions,Interface objects,ipaddress — IPv4/IPv6 manipulation library
@anchor{library/ipaddress other-module-level-functions}@anchor{447c}
@subsubsection Other Module Level Functions


The module also provides the following module level functions:

@geindex v4_int_to_packed() (στη μονάδα ipaddress)
@anchor{library/ipaddress ipaddress v4_int_to_packed}@anchor{447d}
@deffn {Συνάρτηση} 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{277,,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() (στη μονάδα ipaddress)
@anchor{library/ipaddress ipaddress v6_int_to_packed}@anchor{447e}
@deffn {Συνάρτηση} 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{277,,ValueError} is raised if the integer is negative or too large to be an
IPv6 IP address.
@end deffn

@geindex summarize_address_range() (στη μονάδα ipaddress)
@anchor{library/ipaddress ipaddress summarize_address_range}@anchor{1253}
@deffn {Συνάρτηση} 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{710,,IPv4Address} or
@ref{711,,IPv6Address} in the range and `last' is the last @code{IPv4Address}
or @code{IPv6Address} in the range.  A @ref{291,,TypeError} is raised if
`first' or `last' are not IP addresses or are not of the same version.  A
@ref{277,,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() (στη μονάδα ipaddress)
@anchor{library/ipaddress ipaddress collapse_addresses}@anchor{1254}
@deffn {Συνάρτηση} ipaddress.collapse_addresses (addresses)

Return an iterator of the collapsed @ref{712,,IPv4Network} or
@ref{713,,IPv6Network} objects.  `addresses' is an @ref{15ce,,iterable} of
@code{IPv4Network} or @code{IPv6Network} objects.  A @ref{291,,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() (στη μονάδα ipaddress)
@anchor{library/ipaddress ipaddress get_mixed_type_key}@anchor{447f}
@deffn {Συνάρτηση} 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 @code{ipaddress} sort these anyway.  If you need to do this, you can use
this function as the `key' argument to @ref{f8c,,sorted()}.

`obj' is either a network or address object.
@end deffn

@node Custom Exceptions,,Other Module Level Functions,ipaddress — IPv4/IPv6 manipulation library
@anchor{library/ipaddress custom-exceptions}@anchor{4480}
@subsubsection Custom Exceptions


To support more specific error reporting from class constructors, the
module defines the following exceptions:

@geindex AddressValueError
@anchor{library/ipaddress ipaddress AddressValueError}@anchor{4416}
@deffn {Εξαίρεση} ipaddress.AddressValueError (ValueError)

Any value error related to the address.
@end deffn

@geindex NetmaskValueError
@anchor{library/ipaddress ipaddress NetmaskValueError}@anchor{4437}
@deffn {Εξαίρεση} ipaddress.NetmaskValueError (ValueError)

Any value error related to the net mask.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Multimedia Services,Internationalization,Πρωτόκολλα Internet και Υποστήριξη,The Python Standard Library
@anchor{library/mm doc}@anchor{4481}@anchor{library/mm mmedia}@anchor{4482}@anchor{library/mm multimedia-services}@anchor{4483}@anchor{library/mm translation-repo}@anchor{4484}
@section Multimedia Services


The modules described in this chapter implement various algorithms or interfaces
that are mainly useful for multimedia applications.  They are available at the
discretion of the installation.  Here’s an overview:

@menu
* wave — Read and write WAV files:: 
* colorsys — Μετατροπές μεταξύ συστημάτων χρωμάτων:: 

@end menu

@node wave — Read and write WAV files,colorsys — Μετατροπές μεταξύ συστημάτων χρωμάτων,,Multimedia Services
@anchor{library/wave doc}@anchor{4485}@anchor{library/wave module-wave}@anchor{11c}@anchor{library/wave wave-read-and-write-wav-files}@anchor{4486}
@subsection @code{wave} — Read and write WAV files


@geindex module; wave

`Source code:' Lib/wave.py@footnote{https://github.com/python/cpython/tree/main/Lib/wave.py}


__________________________________________________________________


The @code{wave} module provides a convenient interface to the Waveform Audio
«WAVE» (or «WAV») file format.

The module supports uncompressed PCM and IEEE floating-point WAV formats.


Άλλαξε στην έκδοση 3.12: Support for @code{WAVE_FORMAT_EXTENSIBLE} headers was added, provided that the
extended format is @code{KSDATAFORMAT_SUBTYPE_PCM}.



Άλλαξε στην έκδοση 3.15: Support for reading and writing @code{WAVE_FORMAT_IEEE_FLOAT} files was added.


The @code{wave} module defines the following function and exception:

@geindex open() (στη μονάδα wave)
@anchor{library/wave wave open}@anchor{d17}
@deffn {Συνάρτηση} wave.open (file, mode=None)

If `file' is a string, a @ref{79f,,path-like object} or a
@ref{436,,bytes-like object} open the file by that name, otherwise treat it as
a file-like object.  `mode' can be:


@table @asis

@item @code{'rb'}

Read only mode.

@item @code{'wb'}

Write only mode.
@end table

Note that it does not allow read/write WAV files.

A `mode' of @code{'rb'} returns a @ref{2e6,,Wave_read} object, while a `mode' of
@code{'wb'} returns a @ref{2e7,,Wave_write} object.  If `mode' is omitted and a
file-like object is passed as `file', @code{file.mode} is used as the default
value for `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 @code{open()} function may be used in a @ref{20a,,with} statement.  When
the @code{with} block completes, the @ref{4487,,Wave_read.close()} or
@ref{4488,,Wave_write.close()} method is called.


Άλλαξε στην έκδοση 3.4: Added support for unseekable files.



Άλλαξε στην έκδοση 3.15: Added support for @ref{79f,,path-like objects}
and @ref{436,,bytes-like objects}.

@end deffn

@geindex Error
@anchor{library/wave wave Error}@anchor{4489}
@deffn {Εξαίρεση} wave.Error

An error raised when something is impossible because it violates the WAV
specification or hits an implementation deficiency.
@end deffn

@geindex WAVE_FORMAT_PCM (στη μονάδα wave)
@anchor{library/wave wave WAVE_FORMAT_PCM}@anchor{448a}
@deffn {Δεδομένα} wave.WAVE_FORMAT_PCM

Format code for uncompressed PCM audio.
@end deffn

@geindex WAVE_FORMAT_IEEE_FLOAT (στη μονάδα wave)
@anchor{library/wave wave WAVE_FORMAT_IEEE_FLOAT}@anchor{448b}
@deffn {Δεδομένα} wave.WAVE_FORMAT_IEEE_FLOAT

Format code for IEEE floating-point audio.
@end deffn

@geindex WAVE_FORMAT_EXTENSIBLE (στη μονάδα wave)
@anchor{library/wave wave WAVE_FORMAT_EXTENSIBLE}@anchor{448c}
@deffn {Δεδομένα} wave.WAVE_FORMAT_EXTENSIBLE

Format code for WAVE extensible headers.
@end deffn

@menu
* Wave_read Objects:: 
* Wave_write Objects:: 

@end menu

@node Wave_read Objects,Wave_write Objects,,wave — Read and write WAV files
@anchor{library/wave id1}@anchor{448d}@anchor{library/wave wave-read-objects}@anchor{448e}
@subsubsection Wave_read Objects


@geindex Wave_read (κλάση σε wave)
@anchor{library/wave wave Wave_read}@anchor{2e6}
@deffn {Κλάση} wave.Wave_read

Read a WAV file.

Wave_read objects, as returned by @ref{d17,,open()}, have the following methods:

@geindex close() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read close}@anchor{4487}
@deffn {Μέθοδος} close ()

Close the stream if it was opened by @code{wave}, and make the instance
unusable.  This is called automatically on object collection.
@end deffn

@geindex getnchannels() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read getnchannels}@anchor{448f}
@deffn {Μέθοδος} getnchannels ()

Returns number of audio channels (@code{1} for mono, @code{2} for stereo).
@end deffn

@geindex getsampwidth() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read getsampwidth}@anchor{4490}
@deffn {Μέθοδος} getsampwidth ()

Returns sample width in bytes.
@end deffn

@geindex getframerate() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read getframerate}@anchor{4491}
@deffn {Μέθοδος} getframerate ()

Returns sampling frequency.
@end deffn

@geindex getnframes() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read getnframes}@anchor{4492}
@deffn {Μέθοδος} getnframes ()

Returns number of audio frames.
@end deffn

@geindex getformat() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read getformat}@anchor{2ad}
@deffn {Μέθοδος} getformat ()

Returns the frame format code.

This is one of @ref{448a,,WAVE_FORMAT_PCM},
@ref{448b,,WAVE_FORMAT_IEEE_FLOAT}, or @ref{448c,,WAVE_FORMAT_EXTENSIBLE}.
@end deffn

@geindex getcomptype() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read getcomptype}@anchor{4493}
@deffn {Μέθοδος} getcomptype ()

Returns compression type (@code{'NONE'} is the only supported type).
@end deffn

@geindex getcompname() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read getcompname}@anchor{4494}
@deffn {Μέθοδος} getcompname ()

Human-readable version of @ref{4493,,getcomptype()}. Usually @code{'not compressed'}
parallels @code{'NONE'}.
@end deffn

@geindex getparams() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read getparams}@anchor{1393}
@deffn {Μέθοδος} getparams ()

Returns a @ref{1cf,,namedtuple()} @code{(nchannels, sampwidth,
framerate, nframes, comptype, compname)}, equivalent to output
of the @code{get*()} methods.
@end deffn

@geindex readframes() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read readframes}@anchor{19af}
@deffn {Μέθοδος} readframes (n)

Reads and returns at most `n' frames of audio, as a @ref{1c7,,bytes} object.
@end deffn

@geindex rewind() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read rewind}@anchor{4495}
@deffn {Μέθοδος} rewind ()

Rewind the file pointer to the beginning of the audio stream.
@end deffn

The following two methods define a term «position» which is compatible between
them, and is otherwise implementation dependent.

@geindex setpos() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read setpos}@anchor{4496}
@deffn {Μέθοδος} setpos (pos)

Set the file pointer to the specified position.
@end deffn

@geindex tell() (μέθοδος της wave.Wave_read)
@anchor{library/wave wave Wave_read tell}@anchor{4497}
@deffn {Μέθοδος} tell ()

Return current file pointer position.
@end deffn
@end deffn

@node Wave_write Objects,,Wave_read Objects,wave — Read and write WAV files
@anchor{library/wave id2}@anchor{4498}@anchor{library/wave wave-write-objects}@anchor{1394}
@subsubsection Wave_write Objects


@geindex Wave_write (κλάση σε wave)
@anchor{library/wave wave Wave_write}@anchor{2e7}
@deffn {Κλάση} wave.Wave_write

Write a WAV file.

Wave_write objects, as returned by @ref{d17,,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{4499,,setnframes()} or @ref{2b0,,setparams()} with the number
of frames that will be written before @ref{4488,,close()} is called and
then using @ref{1395,,writeframesraw()} to write the frame data, or by
calling @ref{1396,,writeframes()} with all of the frame data to be
written.  In the latter case @code{writeframes()} will calculate
the number of frames in the data and set `nframes' accordingly before writing
the frame data.


Άλλαξε στην έκδοση 3.4: Added support for unseekable files.


Wave_write objects have the following methods:

@geindex close() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write close}@anchor{4488}
@deffn {Μέθοδος} close ()

Make sure `nframes' is correct, and close the file if it was opened by
@code{wave}.  This method is called upon object collection.  It will raise
an exception if the output stream is not seekable and `nframes' does not
match the number of frames actually written.
@end deffn

@geindex setnchannels() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write setnchannels}@anchor{449a}
@deffn {Μέθοδος} setnchannels (n)

Set the number of channels.
@end deffn

@geindex getnchannels() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write getnchannels}@anchor{449b}
@deffn {Μέθοδος} getnchannels ()

Return the number of channels.
@end deffn

@geindex setsampwidth() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write setsampwidth}@anchor{449c}
@deffn {Μέθοδος} setsampwidth (n)

Set the sample width to `n' bytes.

For @ref{448b,,WAVE_FORMAT_IEEE_FLOAT}, only 4-byte (32-bit) and
8-byte (64-bit) sample widths are supported.
@end deffn

@geindex getsampwidth() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write getsampwidth}@anchor{449d}
@deffn {Μέθοδος} getsampwidth ()

Return the sample width in bytes.
@end deffn

@geindex setframerate() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write setframerate}@anchor{1932}
@deffn {Μέθοδος} setframerate (n)

Set the frame rate to `n'.


Άλλαξε στην έκδοση 3.2: A non-integral input to this method is rounded to the nearest
integer.

@end deffn

@geindex getframerate() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write getframerate}@anchor{449e}
@deffn {Μέθοδος} getframerate ()

Return the frame rate.
@end deffn

@geindex setnframes() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write setnframes}@anchor{4499}
@deffn {Μέθοδος} setnframes (n)

Set the number of frames to `n'.  This will be changed later if the number
of frames actually written is different (this update attempt will
raise an error if the output stream is not seekable).
@end deffn

@geindex getnframes() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write getnframes}@anchor{449f}
@deffn {Μέθοδος} getnframes ()

Return the number of audio frames written so far.
@end deffn

@geindex setcomptype() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write setcomptype}@anchor{44a0}
@deffn {Μέθοδος} setcomptype (type, name)

Set the compression type and description. At the moment, only compression type
@code{NONE} is supported, meaning no compression.
@end deffn

@geindex getcomptype() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write getcomptype}@anchor{44a1}
@deffn {Μέθοδος} getcomptype ()

Return the compression type (@code{'NONE'}).
@end deffn

@geindex getcompname() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write getcompname}@anchor{44a2}
@deffn {Μέθοδος} getcompname ()

Return the human-readable compression type name.
@end deffn

@geindex setformat() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write setformat}@anchor{2af}
@deffn {Μέθοδος} setformat (format)

Set the frame format code.

Supported values are @ref{448a,,WAVE_FORMAT_PCM} and
@ref{448b,,WAVE_FORMAT_IEEE_FLOAT}.

When setting @ref{448b,,WAVE_FORMAT_IEEE_FLOAT}, the sample width must be
4 or 8 bytes.
@end deffn

@geindex getformat() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write getformat}@anchor{2ae}
@deffn {Μέθοδος} getformat ()

Return the current frame format code.
@end deffn

@geindex setparams() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write setparams}@anchor{2b0}
@deffn {Μέθοδος} setparams (tuple)

The `tuple' should be
@code{(nchannels, sampwidth, framerate, nframes, comptype, compname, format)},
with values valid for the @code{set*()} methods. Sets all parameters.

For backwards compatibility, a 6-item tuple without `format' is also
accepted and defaults to @ref{448a,,WAVE_FORMAT_PCM}.

For @code{format=WAVE_FORMAT_IEEE_FLOAT}, `sampwidth' must be 4 or 8.
@end deffn

@geindex getparams() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write getparams}@anchor{44a3}
@deffn {Μέθοδος} getparams ()

Return a @ref{1cf,,namedtuple()}
@code{(nchannels, sampwidth, framerate, nframes, comptype, compname)}
containing the current output parameters.
@end deffn

@geindex tell() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write tell}@anchor{44a4}
@deffn {Μέθοδος} tell ()

Return current position in the file, with the same disclaimer for the
@ref{4497,,Wave_read.tell()} and @ref{4496,,Wave_read.setpos()} methods.
@end deffn

@geindex writeframesraw() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write writeframesraw}@anchor{1395}
@deffn {Μέθοδος} writeframesraw (data)

Write audio frames, without correcting `nframes'.


Άλλαξε στην έκδοση 3.4: Any @ref{436,,bytes-like object} is now accepted.

@end deffn

@geindex writeframes() (μέθοδος της wave.Wave_write)
@anchor{library/wave wave Wave_write writeframes}@anchor{1396}
@deffn {Μέθοδος} writeframes (data)

Write audio frames and make sure `nframes' is correct.  It will raise an
error if the output stream is not seekable and the total number of frames
that have been written after `data' has been written does not match the
previously set value for `nframes'.


Άλλαξε στην έκδοση 3.4: Any @ref{436,,bytes-like object} is now accepted.


Note that it is invalid to set any parameters after calling @code{writeframes()}
or @ref{1395,,writeframesraw()}, and any attempt to do so will raise
@ref{4489,,wave.Error}.

For @ref{448b,,WAVE_FORMAT_IEEE_FLOAT} output, a @code{fact} chunk is written as
required by the WAVE specification for non-PCM formats.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node colorsys — Μετατροπές μεταξύ συστημάτων χρωμάτων,,wave — Read and write WAV files,Multimedia Services
@anchor{library/colorsys doc}@anchor{44a5}@anchor{library/colorsys colorsys-conversions-between-color-systems}@anchor{44a6}@anchor{library/colorsys module-colorsys}@anchor{20}@anchor{library/colorsys translation-repo}@anchor{44a7}
@subsection @code{colorsys} — Μετατροπές μεταξύ συστημάτων χρωμάτων


@geindex module; colorsys

`Πηγαίος κώδικας' Lib/colorsys.py@footnote{https://github.com/python/cpython/tree/main/Lib/colorsys.py}


__________________________________________________________________


The @code{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 Δείτε επίσης


Περισσότερες πληροφορίες σχετικά με τους χρωματικούς χώρους μπορούν να βρεθούν στις διευθύνσεις @indicateurl{https://poynton.ca/ColorFAQ.html} και @indicateurl{https://www.cambridgeincolour.com/tutorials/color-spaces.htm}.


The @code{colorsys} module defines the following functions:

@geindex rgb_to_yiq() (στη μονάδα colorsys)
@anchor{library/colorsys colorsys rgb_to_yiq}@anchor{44a8}
@deffn {Συνάρτηση} colorsys.rgb_to_yiq (r, g, b)

Μετατρέπει το χρώμα από συντεταγμένες RGB σε συντεταγμένες YIQ.
@end deffn

@geindex yiq_to_rgb() (στη μονάδα colorsys)
@anchor{library/colorsys colorsys yiq_to_rgb}@anchor{44a9}
@deffn {Συνάρτηση} colorsys.yiq_to_rgb (y, i, q)

Μετατρέπει το χρώμα από συντεταγμένες YIQ σε συντεταγμένες RGB.
@end deffn

@geindex rgb_to_hls() (στη μονάδα colorsys)
@anchor{library/colorsys colorsys rgb_to_hls}@anchor{1c78}
@deffn {Συνάρτηση} colorsys.rgb_to_hls (r, g, b)

Μετατρέπει το χρώμα από συντεταγμένες RGB σε συντεταγμένες HLS.
@end deffn

@geindex hls_to_rgb() (στη μονάδα colorsys)
@anchor{library/colorsys colorsys hls_to_rgb}@anchor{44aa}
@deffn {Συνάρτηση} colorsys.hls_to_rgb (h, l, s)

Μετατρέπει το χρώμα από συντεταγμένες HLS σε συντεταγμένες RGB.
@end deffn

@geindex rgb_to_hsv() (στη μονάδα colorsys)
@anchor{library/colorsys colorsys rgb_to_hsv}@anchor{44ab}
@deffn {Συνάρτηση} colorsys.rgb_to_hsv (r, g, b)

Μετατρέπει το χρώμα από συντεταγμένες RGB σε συντεταγμένες HSV.
@end deffn

@geindex hsv_to_rgb() (στη μονάδα colorsys)
@anchor{library/colorsys colorsys hsv_to_rgb}@anchor{44ac}
@deffn {Συνάρτηση} colorsys.hsv_to_rgb (h, s, v)

Μετατρέπει το χρώμα από συντεταγμένες HSV σε συντεταγμένες RGB.
@end deffn

Παράδειγμα:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Internationalization,Γραφικές επαφές χρηστών με το Tk,Multimedia Services,The Python Standard Library
@anchor{library/i18n doc}@anchor{44ad}@anchor{library/i18n i18n}@anchor{44ae}@anchor{library/i18n internationalization}@anchor{44af}@anchor{library/i18n translation-repo}@anchor{44b0}
@section Internationalization


The modules described in this chapter help you write software that is
independent of language and locale by providing mechanisms for selecting a
language to be used in  program messages or by tailoring output to match local
conventions.

The list of modules described in this chapter is:

@menu
* gettext — Multilingual internationalization services:: 
* locale — Internationalization services:: 

@end menu

@node gettext — Multilingual internationalization services,locale — Internationalization services,,Internationalization
@anchor{library/gettext doc}@anchor{44b1}@anchor{library/gettext gettext-multilingual-internationalization-services}@anchor{44b2}@anchor{library/gettext module-gettext}@anchor{66}
@subsection @code{gettext} — Multilingual internationalization services


@geindex module; gettext

`Source code:' Lib/gettext.py@footnote{https://github.com/python/cpython/tree/main/Lib/gettext.py}


__________________________________________________________________


The @code{gettext} module provides internationalization (I18N) and localization
(L10N) services for your Python modules and applications. It supports both the
GNU @code{gettext} message catalog API and a higher level, class-based API that may
be more appropriate for Python files.  The interface described below allows you
to write your module and application messages in one natural language, and
provide a catalog of translated messages for running under different natural
languages.

Some hints on localizing your Python modules and applications are also given.

@menu
* GNU gettext API:: 
* Class-based API:: 
* Internationalizing your programs and modules:: 
* Acknowledgements: Acknowledgements<9>. 

@end menu

@node GNU gettext API,Class-based API,,gettext — Multilingual internationalization services
@anchor{library/gettext gnu-gettext-api}@anchor{44b3}
@subsubsection GNU @code{gettext} API


The @code{gettext} module defines the following API, which is very similar to
the GNU @code{gettext} API.  If you use this API you will affect the
translation of your entire application globally.  Often this is what you want if
your application is monolingual, with the choice of language dependent on the
locale of your user.  If you are localizing a Python module, or if your
application needs to switch languages on the fly, you probably want to use the
class-based API instead.

@geindex bindtextdomain() (στη μονάδα gettext)
@anchor{library/gettext gettext bindtextdomain}@anchor{44b4}
@deffn {Συνάρτηση} gettext.bindtextdomain (domain, localedir=None)

Bind the `domain' to the locale directory `localedir'.  More concretely,
@code{gettext} will look for binary @code{.mo} files for the given domain using
the path (on Unix): @code{`localedir'/`language'/LC_MESSAGES/`domain'.mo}, where
`language' is searched for in the environment variables 
@geindex LANGUAGE
@geindex μεταβλητή περιβάλλοντος; LANGUAGE
@code{LANGUAGE},
@geindex LC_ALL
@geindex μεταβλητή περιβάλλοντος; LC_ALL
@code{LC_ALL}, 
@geindex LC_MESSAGES
@geindex μεταβλητή περιβάλλοντος; LC_MESSAGES
@code{LC_MESSAGES}, and 
@geindex LANG
@geindex μεταβλητή περιβάλλοντος; LANG
@code{LANG} respectively.

If `localedir' is omitted or @code{None}, then the current binding for `domain' is
returned. @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{3aa,,sys.base_prefix}). For this reason, it is always best to call
@ref{44b4,,bindtextdomain()} with an explicit absolute path at the start of your
application.
}
@end deffn

@geindex textdomain() (στη μονάδα gettext)
@anchor{library/gettext gettext textdomain}@anchor{44b5}
@deffn {Συνάρτηση} gettext.textdomain (domain=None)

Change or query the current global domain.  If `domain' is @code{None}, then the
current global domain is returned, otherwise the global domain is set to
`domain', which is returned.
@end deffn

@geindex _ (underscore);gettext

@geindex gettext() (στη μονάδα gettext)
@anchor{library/gettext gettext gettext}@anchor{180b}
@deffn {Συνάρτηση} 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() (στη μονάδα gettext)
@anchor{library/gettext gettext dgettext}@anchor{44b6}
@deffn {Συνάρτηση} gettext.dgettext (domain, message)

Like @ref{180b,,gettext()}, but look the message up in the specified `domain'.
@end deffn

@geindex ngettext() (στη μονάδα gettext)
@anchor{library/gettext gettext ngettext}@anchor{44b7}
@deffn {Συνάρτηση} gettext.ngettext (singular, plural, n)

Like @ref{180b,,gettext()}, but consider plural forms. If a translation is found,
apply the plural formula to `n', and return the resulting message (some
languages have more than two plural forms). If no translation is found, return
`singular' if `n' is 1; return `plural' otherwise.

The Plural formula is taken from the catalog header. It is a C or Python
expression that has a free variable `n'; the expression evaluates to the index
of the plural in the catalog. See
the GNU gettext documentation@footnote{https://www.gnu.org/software/gettext/manual/gettext.html}
for the precise syntax to be used in @code{.po} files and the
formulas for a variety of languages.
@end deffn

@geindex dngettext() (στη μονάδα gettext)
@anchor{library/gettext gettext dngettext}@anchor{44b8}
@deffn {Συνάρτηση} gettext.dngettext (domain, singular, plural, n)

Like @ref{44b7,,ngettext()}, but look the message up in the specified `domain'.
@end deffn

@geindex pgettext() (στη μονάδα gettext)
@anchor{library/gettext gettext pgettext}@anchor{db8}
@deffn {Συνάρτηση} gettext.pgettext (context, message)
@end deffn

@geindex dpgettext() (στη μονάδα gettext)
@anchor{library/gettext gettext dpgettext}@anchor{44b9}
@deffn {Συνάρτηση} gettext.dpgettext (domain, context, message)
@end deffn

@geindex npgettext() (στη μονάδα gettext)
@anchor{library/gettext gettext npgettext}@anchor{44ba}
@deffn {Συνάρτηση} gettext.npgettext (context, singular, plural, n)
@end deffn

@geindex dnpgettext() (στη μονάδα gettext)
@anchor{library/gettext gettext dnpgettext}@anchor{44bb}
@deffn {Συνάρτηση} gettext.dnpgettext (domain, context, singular, plural, n)

Similar to the corresponding functions without the @code{p} in the prefix (that
is, @ref{66,,gettext()}, @ref{44b6,,dgettext()}, @ref{44b7,,ngettext()}, @ref{44b8,,dngettext()}),
but the translation is restricted to the given message `context'.


Added in 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.

Here’s an example of typical usage for this 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 Class-based API,Internationalizing your programs and modules,GNU gettext API,gettext — Multilingual internationalization services
@anchor{library/gettext class-based-api}@anchor{44bc}
@subsubsection Class-based API


The class-based API of the @code{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{44bd,,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() (στη μονάδα gettext)
@anchor{library/gettext gettext find}@anchor{44be}
@deffn {Συνάρτηση} gettext.find (domain, localedir=None, languages=None, all=False)

This function implements the standard @code{.mo} file search algorithm.  It
takes a `domain', identical to what @ref{44b5,,textdomain()} takes.  Optional
`localedir' is as in @ref{44b4,,bindtextdomain()}. Optional `languages' is a list of
strings, where each string is a language code.

If `localedir' is not given, then the default system locale directory is used.
@footnote{
See the footnote for @ref{44b4,,bindtextdomain()} above.
}  If `languages' is not given, then the following environment variables are
searched: 
@geindex LANGUAGE
@geindex μεταβλητή περιβάλλοντος; LANGUAGE
@code{LANGUAGE}, 
@geindex LC_ALL
@geindex μεταβλητή περιβάλλοντος; LC_ALL
@code{LC_ALL}, 
@geindex LC_MESSAGES
@geindex μεταβλητή περιβάλλοντος; LC_MESSAGES
@code{LC_MESSAGES}, and
@geindex LANG
@geindex μεταβλητή περιβάλλοντος; LANG
@code{LANG}.  The first one returning a non-empty value is used for the
`languages' variable. The environment variables should contain a colon separated
list of languages, which will be split on the colon to produce the expected list
of language code strings.

@code{find()} then expands and normalizes the languages, and then iterates
through them, searching for an existing file built of these components:

@code{`localedir'/`language'/LC_MESSAGES/`domain'.mo}

The first such file name that exists is returned by @code{find()}. If no such
file is found, then @code{None} is returned. If `all' is given, it returns a list
of all file names, in the order in which they appear in the languages list or
the environment variables.
@end deffn

@geindex translation() (στη μονάδα gettext)
@anchor{library/gettext gettext translation}@anchor{e3c}
@deffn {Συνάρτηση} 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{44be,,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{44bd,,GNUTranslations}.  The class’s constructor must
take a single @ref{156c,,file object} argument.

If multiple files are found, later files are used as fallbacks for earlier ones.
To allow setting the fallback, @ref{942,,copy.copy()} is used to clone each
translation object from the cache; the actual instance data is still shared with
the cache.

If no @code{.mo} file is found, this function raises @ref{53c,,OSError} if
`fallback' is false (which is the default), and returns a
@ref{44bf,,NullTranslations} instance if `fallback' is true.


Άλλαξε στην έκδοση 3.3: @ref{13fb,,IOError} used to be raised, it is now an alias of @ref{53c,,OSError}.



Άλλαξε στην έκδοση 3.11: `codeset' parameter is removed.

@end deffn

@geindex install() (στη μονάδα gettext)
@anchor{library/gettext gettext install}@anchor{e3d}
@deffn {Συνάρτηση} 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{e3c,,translation()}.

For the `names' parameter, please see the description of the translation
object’s @ref{44c0,,install()} method.

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.


Άλλαξε στην έκδοση 3.11: `names' is now a keyword-only parameter.

@end deffn

@menu
* The NullTranslations class:: 
* The GNUTranslations class:: 
* Solaris message catalog support:: 
* The Catalog constructor:: 

@end menu

@node The NullTranslations class,The GNUTranslations class,,Class-based API
@anchor{library/gettext the-nulltranslations-class}@anchor{44c1}
@subsubsection The @code{NullTranslations} class


Translation classes are what actually implement the translation of original
source file message strings to translated message strings. The base class used
by all translation classes is @ref{44bf,,NullTranslations}; this provides the basic
interface you can use to write your own specialized translation classes.  Here
are the methods of @code{NullTranslations}:

@geindex NullTranslations (κλάση σε gettext)
@anchor{library/gettext gettext NullTranslations}@anchor{44bf}
@deffn {Κλάση} gettext.NullTranslations (fp=None)

Takes an optional @ref{156c,,file object} `fp', which is ignored by the base class.
Initializes «protected» instance variables `_info' and `_charset' which are set
by derived classes, as well as `_fallback', which is set through
@ref{44c2,,add_fallback()}.  It then calls @code{self._parse(fp)} if `fp' is not
@code{None}.

@geindex _parse() (μέθοδος της gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations _parse}@anchor{44c3}
@deffn {Μέθοδος} _parse (fp)

No-op in the base class, this method takes file object `fp', and reads
the data from the file, initializing its message catalog.  If you have an
unsupported message catalog file format, you should override this method
to parse your format.
@end deffn

@geindex add_fallback() (μέθοδος της gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations add_fallback}@anchor{44c2}
@deffn {Μέθοδος} add_fallback (fallback)

Add `fallback' as the fallback object for the current translation object.
A translation object should consult the fallback if it cannot provide a
translation for a given message.
@end deffn

@geindex gettext() (μέθοδος της gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations gettext}@anchor{44c4}
@deffn {Μέθοδος} gettext (message)

If a fallback has been set, forward @code{gettext()} to the fallback.
Otherwise, return `message'.  Overridden in derived classes.
@end deffn

@geindex ngettext() (μέθοδος της gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations ngettext}@anchor{44c5}
@deffn {Μέθοδος} ngettext (singular, plural, n)

If a fallback has been set, forward @code{ngettext()} to the fallback.
Otherwise, return `singular' if `n' is 1; return `plural' otherwise.
Overridden in derived classes.
@end deffn

@geindex pgettext() (μέθοδος της gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations pgettext}@anchor{44c6}
@deffn {Μέθοδος} pgettext (context, message)

If a fallback has been set, forward @code{pgettext()} to the fallback.
Otherwise, return the translated message.  Overridden in derived classes.


Added in version 3.8.

@end deffn

@geindex npgettext() (μέθοδος της gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations npgettext}@anchor{44c7}
@deffn {Μέθοδος} npgettext (context, singular, plural, n)

If a fallback has been set, forward @code{npgettext()} to the fallback.
Otherwise, return the translated message.  Overridden in derived classes.


Added in version 3.8.

@end deffn

@geindex info() (μέθοδος της gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations info}@anchor{44c8}
@deffn {Μέθοδος} info ()

Return a dictionary containing
the metadata found in the message catalog file.
@end deffn

@geindex charset() (μέθοδος της gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations charset}@anchor{44c9}
@deffn {Μέθοδος} charset ()

Return the encoding of the message catalog file.
@end deffn

@geindex install() (μέθοδος της gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations install}@anchor{44c0}
@deffn {Μέθοδος} install (names=None)

This method installs @ref{44c4,,gettext()} into the built-in namespace,
binding it to @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.


Άλλαξε στην έκδοση 3.8: Added @code{'pgettext'} and @code{'npgettext'}.

@end deffn
@end deffn

@node The GNUTranslations class,Solaris message catalog support,The NullTranslations class,Class-based API
@anchor{library/gettext the-gnutranslations-class}@anchor{44ca}
@subsubsection The @code{GNUTranslations} class


The @code{gettext} module provides one additional class derived from
@ref{44bf,,NullTranslations}: @ref{44bd,,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{44bd,,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.

If the @code{.mo} file’s magic number is invalid, the major version number is
unexpected, or if other problems occur while reading the file, instantiating a
@ref{44bd,,GNUTranslations} class can raise @ref{53c,,OSError}.

@geindex GNUTranslations (κλάση σε gettext)
@anchor{library/gettext gettext GNUTranslations}@anchor{44bd}
@deffn {Κλάση} gettext.GNUTranslations

The following methods are overridden from the base class implementation:

@geindex gettext() (μέθοδος της gettext.GNUTranslations)
@anchor{library/gettext gettext GNUTranslations gettext}@anchor{44cb}
@deffn {Μέθοδος} gettext (message)

Look up the `message' id in the catalog and return the corresponding message
string, as a Unicode string.  If there is no entry in the catalog for the
`message' id, and a fallback has been set, the look up is forwarded to the
fallback’s @ref{44c4,,gettext()} method.  Otherwise, the
`message' id is returned.
@end deffn

@geindex ngettext() (μέθοδος της gettext.GNUTranslations)
@anchor{library/gettext gettext GNUTranslations ngettext}@anchor{44cc}
@deffn {Μέθοδος} ngettext (singular, plural, n)

Do a plural-forms lookup of a message id.  `singular' is used as the message id
for purposes of lookup in the catalog, while `n' is used to determine which
plural form to use.  The returned message string is a Unicode string.

If the message id is not found in the catalog, and a fallback is specified,
the request is forwarded to the fallback’s @ref{44c5,,ngettext()}
method.  Otherwise, when `n' is 1 `singular' is returned, and `plural' is
returned in all other cases.

Here is an example:

@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() (μέθοδος της gettext.GNUTranslations)
@anchor{library/gettext gettext GNUTranslations pgettext}@anchor{44cd}
@deffn {Μέθοδος} pgettext (context, message)

Look up the `context' and `message' id in the catalog and return the
corresponding message string, as a Unicode string.  If there is no
entry in the catalog for the `message' id and `context', and a fallback
has been set, the look up is forwarded to the fallback’s
@code{pgettext()} method.  Otherwise, the `message' id is returned.


Added in version 3.8.

@end deffn

@geindex npgettext() (μέθοδος της gettext.GNUTranslations)
@anchor{library/gettext gettext GNUTranslations npgettext}@anchor{44ce}
@deffn {Μέθοδος} npgettext (context, singular, plural, n)

Do a plural-forms lookup of a message id.  `singular' is used as the
message id for purposes of lookup in the catalog, while `n' is used to
determine which plural form to use.

If the message id for `context' is not found in the catalog, and a
fallback is specified, the request is forwarded to the fallback’s
@code{npgettext()} method.  Otherwise, when `n' is 1 `singular' is
returned, and `plural' is returned in all other cases.


Added in version 3.8.

@end deffn
@end deffn

@node Solaris message catalog support,The Catalog constructor,The GNUTranslations class,Class-based API
@anchor{library/gettext solaris-message-catalog-support}@anchor{44cf}
@subsubsection Solaris message catalog support


The Solaris operating system defines its own binary @code{.mo} file format, but
since no documentation can be found on this format, it is not supported at this
time.

@node The Catalog constructor,,Solaris message catalog support,Class-based API
@anchor{library/gettext the-catalog-constructor}@anchor{44d0}
@subsubsection The Catalog constructor


@geindex GNOME

GNOME uses a version of the @code{gettext} module by James Henstridge, but this
version has a slightly different API.  Its documented usage was:

@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{e3c,,translation()} function described above.

One difference between this module and Henstridge’s: his catalog objects
supported access through a mapping API, but this appears to be unused and so is
not currently supported.

@node Internationalizing your programs and modules,Acknowledgements<9>,Class-based API,gettext — Multilingual internationalization services
@anchor{library/gettext i18n-howto}@anchor{362b}@anchor{library/gettext internationalizing-your-programs-and-modules}@anchor{44d1}
@subsubsection Internationalizing your programs and modules


Internationalization (I18N) refers to the operation by which a program is made
aware of multiple languages.  Localization (L10N) refers to the adaptation of
your program, once internationalized, to the local language and cultural habits.
In order to provide multilingual messages for your Python programs, you need to
take the following steps:


@enumerate 

@item 
prepare your program or module by specially marking translatable strings

@item 
run a suite of tools over your marked files to generate raw messages catalogs

@item 
create language-specific translations of the message catalogs

@item 
use the @code{gettext} module so that message strings are properly translated
@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{66,,_}.  For example:

@example
filename = 'mylog.txt'
message = _('writing a log message')
with open(filename, 'w') as fp:
    fp.write(message)
@end example

In this example, the string @code{'writing a log message'} is marked as a candidate
for translation, while the strings @code{'mylog.txt'} and @code{'w'} are not.

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 also includes pure-Python versions of these programs, called
@code{pygettext.py} and @code{msgfmt.py}; some Python distributions
will install them for you.  @code{pygettext.py} is similar to
@code{xgettext}, but only understands Python source code and
cannot handle other programming languages such as C or C++.
@code{pygettext.py} supports a command-line interface similar to
@code{xgettext}; for details on its use, run @code{pygettext.py
--help}.  @code{msgfmt.py} is binary compatible with GNU
@code{msgfmt}.  With these two programs, you may not need the GNU
@code{gettext} package to internationalize your Python
applications.)

@code{xgettext}, @code{pygettext}, and similar tools generate
@code{.po} files that are message catalogs.  They are structured
human-readable files that contain every marked string in the source
code, along with a placeholder for the translated versions of these
strings.

Copies of these @code{.po} files are then handed over to the
individual human translators who write translations for every
supported natural language.  They send back the completed
language-specific versions as a @code{<language-name>.po} file that’s
compiled into a machine-readable @code{.mo} binary catalog file using
the @code{msgfmt} program.  The @code{.mo} files are used by the
@code{gettext} module for the actual translation processing at
run-time.

How you use the @code{gettext} module in your code depends on whether you are
internationalizing a single module or your entire application. The next two
sections will discuss each case.

@menu
* Localizing your module:: 
* Localizing your application:: 
* Changing languages on the fly:: 
* Deferred translations:: 

@end menu

@node Localizing your module,Localizing your application,,Internationalizing your programs and modules
@anchor{library/gettext localizing-your-module}@anchor{44d2}
@subsubsection Localizing your module


If you are localizing your module, you must take care not to make global
changes, e.g. to the built-in namespace. You should not use the GNU @code{gettext}
API but instead the class-based API.

Let’s say your module is called «spam» and the module’s various natural language
translation @code{.mo} files reside in @code{/usr/share/locale} in GNU
@code{gettext} format.  Here’s what you would put at the top of your
module:

@example
import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.gettext
@end example

@node Localizing your application,Changing languages on the fly,Localizing your module,Internationalizing your programs and modules
@anchor{library/gettext localizing-your-application}@anchor{44d3}
@subsubsection Localizing your 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.

In the simple case then, you need only add the following bit of code to the main
driver file of your application:

@example
import gettext
gettext.install('myapplication')
@end example

If you need to set the locale directory, you can pass it into the
@ref{e3d,,install()} function:

@example
import gettext
gettext.install('myapplication', '/usr/share/locale')
@end example

@node Changing languages on the fly,Deferred translations,Localizing your application,Internationalizing your programs and modules
@anchor{library/gettext changing-languages-on-the-fly}@anchor{44d4}
@subsubsection Changing languages on the fly


If your program needs to support many languages at the same time, you may want
to create multiple translation instances and then switch between them
explicitly, like so:

@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 Deferred translations,,Changing languages on the fly,Internationalizing your programs and modules
@anchor{library/gettext deferred-translations}@anchor{44d5}
@subsubsection Deferred translations


In most coding situations, strings are translated where they are coded.
Occasionally however, you need to mark strings for translation, but defer actual
translation until later.  A classic example is:

@example
animals = ['mollusk',
           'albatross',
           'rat',
           'penguin',
           'python', ]
# ...
for a in animals:
    print(a)
@end example

Here, you want to mark the strings in the @code{animals} list as being
translatable, but you don’t actually want to translate them until they are
printed.

Here is one way you can handle this situation:

@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{1d1d,,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.

Another way to handle this is with the following example:

@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 Acknowledgements<9>,,Internationalizing your programs and modules,gettext — Multilingual internationalization services
@anchor{library/gettext acknowledgements}@anchor{44d6}
@subsubsection Acknowledgements


The following people contributed code, feedback, design suggestions, previous
implementations, and valuable experience to the creation of this 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node locale — Internationalization services,,gettext — Multilingual internationalization services,Internationalization
@anchor{library/locale doc}@anchor{44d7}@anchor{library/locale locale-internationalization-services}@anchor{44d8}@anchor{library/locale module-locale}@anchor{89}@anchor{library/locale translation-repo}@anchor{44d9}
@subsection @code{locale} — Internationalization services


@geindex module; locale

`Source code:' Lib/locale.py@footnote{https://github.com/python/cpython/tree/main/Lib/locale.py}


__________________________________________________________________


The @code{locale} module opens access to the POSIX locale database and
functionality. The POSIX locale mechanism allows programmers to deal with
certain cultural issues in an application, without requiring the programmer to
know all the specifics of each country where the software is executed.

@geindex module;_locale

The @code{locale} module is implemented on top of the @code{_locale} module,
which in turn uses an ANSI C locale implementation if available.

The @code{locale} module defines the following exception and functions:

@geindex Error
@anchor{library/locale locale Error}@anchor{44da}
@deffn {Εξαίρεση} locale.Error

Exception raised when the locale passed to @ref{231,,setlocale()} is not
recognized.
@end deffn

@geindex setlocale() (στη μονάδα locale)
@anchor{library/locale locale setlocale}@anchor{231}
@deffn {Συνάρτηση} locale.setlocale (category, locale=None)

If `locale' is given and not @code{None}, @code{setlocale()} modifies the locale
setting for the `category'. The available categories are listed in the data
description below. `locale' may be a @ref{44db,,string}, or a pair,
language code and encoding. An empty string specifies the user’s
default settings. If the modification of the locale fails, the exception
@ref{44da,,Error} is raised. If successful, the new locale setting is returned.

If `locale' is a pair, it is converted to a locale name using
the locale aliasing engine.
The language code has the same format as a @ref{44db,,locale name},
but without encoding.
The language code and encoding can be @code{None}.

If `locale' is omitted or @code{None}, the current setting for `category' is
returned.

Example:

@example
>>> import locale
>>> loc = locale.setlocale(locale.LC_ALL)  # get current locale
# use German locale; name and availability varies with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8')
>>> 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

@code{setlocale()} is not thread-safe on most systems. Applications typically
start with a call of:

@example
import locale
locale.setlocale(locale.LC_ALL, '@w{'})
@end example

This sets the locale for all categories to the user’s default setting (typically
specified in the 
@geindex LANG
@geindex μεταβλητή περιβάλλοντος; LANG
@code{LANG} environment variable).  If the locale is not
changed thereafter, using multithreading should not cause problems.


Άλλαξε στην έκδοση 3.15: Support language codes with @code{@@}-modifiers.

@end deffn

@geindex localeconv() (στη μονάδα locale)
@anchor{library/locale locale localeconv}@anchor{fbd}
@deffn {Συνάρτηση} locale.localeconv ()

Returns the database of the local conventions as a dictionary. This dictionary
has the following strings as keys:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Category

@tab

Key

@tab

Meaning

@item

@ref{44dc,,LC_NUMERIC}

@tab

@code{'decimal_point'}

@tab

Decimal point character.

@item

@tab

@code{'grouping'}

@tab

Sequence of numbers specifying
which relative positions the
@code{'thousands_sep'} is
expected.  If the sequence is
terminated with
@ref{44dd,,CHAR_MAX}, no further
grouping is performed. If the
sequence terminates with a
@code{0},  the last group size is
repeatedly used.

@item

@tab

@code{'thousands_sep'}

@tab

Character used between groups.

@item

@ref{44de,,LC_MONETARY}

@tab

@code{'int_curr_symbol'}

@tab

International currency symbol.

@item

@tab

@code{'currency_symbol'}

@tab

Local currency symbol.

@item

@tab

@code{'p_cs_precedes/n_cs_precedes'}

@tab

Whether the currency symbol
precedes the value (for
positive resp. negative
values).

@item

@tab

@code{'p_sep_by_space/n_sep_by_space'}

@tab

Whether the currency symbol is
separated from the value  by a
space (for positive resp.
negative values).

@item

@tab

@code{'mon_decimal_point'}

@tab

Decimal point used for
monetary values.

@item

@tab

@code{'frac_digits'}

@tab

Number of fractional digits
used in local formatting of
monetary values.

@item

@tab

@code{'int_frac_digits'}

@tab

Number of fractional digits
used in international
formatting of monetary values.

@item

@tab

@code{'mon_thousands_sep'}

@tab

Group separator used for
monetary values.

@item

@tab

@code{'mon_grouping'}

@tab

Equivalent to @code{'grouping'},
used for monetary values.

@item

@tab

@code{'positive_sign'}

@tab

Symbol used to annotate a
positive monetary value.

@item

@tab

@code{'negative_sign'}

@tab

Symbol used to annotate a
negative monetary value.

@item

@tab

@code{'p_sign_posn/n_sign_posn'}

@tab

The position of the sign (for
positive resp. negative
values), see below.

@end multitable


All numeric values can be set to @ref{44dd,,CHAR_MAX} to indicate that there is no
value specified in this locale.

The possible values for @code{'p_sign_posn'} and @code{'n_sign_posn'} are given below.


@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Value

@tab

Explanation

@item

@code{0}

@tab

Currency and value are surrounded by
parentheses.

@item

@code{1}

@tab

The sign should precede the value and
currency symbol.

@item

@code{2}

@tab

The sign should follow the value and
currency symbol.

@item

@code{3}

@tab

The sign should immediately precede the
value.

@item

@code{4}

@tab

The sign should immediately follow the
value.

@item

@code{CHAR_MAX}

@tab

Nothing is specified in this locale.

@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.


Άλλαξε στην έκδοση 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() (στη μονάδα locale)
@anchor{library/locale locale nl_langinfo}@anchor{667}
@deffn {Συνάρτηση} locale.nl_langinfo (option)

Return some locale-specific information as a string.  This function is not
available on all systems, and the set of possible options might also vary
across platforms.  The possible argument values are numbers, for which
symbolic constants are available in the locale module.

The @code{nl_langinfo()} function accepts one of the following keys.  Most
descriptions are taken from the corresponding description in the GNU C
library.

@geindex CODESET (στη μονάδα locale)
@anchor{library/locale locale CODESET}@anchor{44df}
@deffn {Δεδομένα} locale.CODESET

Get a string with the name of the character encoding used in the
selected locale.
@end deffn

@geindex D_T_FMT (στη μονάδα locale)
@anchor{library/locale locale D_T_FMT}@anchor{44e0}
@deffn {Δεδομένα} locale.D_T_FMT

Get a string that can be used as a format string for @ref{1592,,time.strftime()} to
represent date and time in a locale-specific way.
@end deffn

@geindex D_FMT (στη μονάδα locale)
@anchor{library/locale locale D_FMT}@anchor{44e1}
@deffn {Δεδομένα} locale.D_FMT

Get a string that can be used as a format string for @ref{1592,,time.strftime()} to
represent a date in a locale-specific way.
@end deffn

@geindex T_FMT (στη μονάδα locale)
@anchor{library/locale locale T_FMT}@anchor{44e2}
@deffn {Δεδομένα} locale.T_FMT

Get a string that can be used as a format string for @ref{1592,,time.strftime()} to
represent a time in a locale-specific way.
@end deffn

@geindex T_FMT_AMPM (στη μονάδα locale)
@anchor{library/locale locale T_FMT_AMPM}@anchor{44e3}
@deffn {Δεδομένα} locale.T_FMT_AMPM

Get a format string for @ref{1592,,time.strftime()} to represent time in the am/pm
format.
@end deffn

@geindex DAY_1 (στη μονάδα locale)
@geindex DAY_2 (στη μονάδα locale)
@geindex DAY_3 (στη μονάδα locale)
@geindex DAY_4 (στη μονάδα locale)
@geindex DAY_5 (στη μονάδα locale)
@geindex DAY_6 (στη μονάδα locale)
@geindex DAY_7 (στη μονάδα locale)
@anchor{library/locale locale DAY_1}@anchor{44e4}
@deffn {Δεδομένα} locale.DAY_1
@anchor{library/locale locale DAY_2}@anchor{44e5}
@deffnx {Δεδομένα} locale.DAY_2
@anchor{library/locale locale DAY_3}@anchor{44e6}
@deffnx {Δεδομένα} locale.DAY_3
@anchor{library/locale locale DAY_4}@anchor{44e7}
@deffnx {Δεδομένα} locale.DAY_4
@anchor{library/locale locale DAY_5}@anchor{44e8}
@deffnx {Δεδομένα} locale.DAY_5
@anchor{library/locale locale DAY_6}@anchor{44e9}
@deffnx {Δεδομένα} locale.DAY_6
@anchor{library/locale locale DAY_7}@anchor{44ea}
@deffnx {Δεδομένα} locale.DAY_7

Get the name of the n-th day of the week.

@cartouche
@quotation Σημείωση 
This follows the US convention of @ref{44e4,,DAY_1} being Sunday, not the
international convention (ISO 8601) that Monday is the first day of the
week.
@end quotation
@end cartouche
@end deffn

@geindex ABDAY_1 (στη μονάδα locale)
@geindex ABDAY_2 (στη μονάδα locale)
@geindex ABDAY_3 (στη μονάδα locale)
@geindex ABDAY_4 (στη μονάδα locale)
@geindex ABDAY_5 (στη μονάδα locale)
@geindex ABDAY_6 (στη μονάδα locale)
@geindex ABDAY_7 (στη μονάδα locale)
@anchor{library/locale locale ABDAY_1}@anchor{44eb}
@deffn {Δεδομένα} locale.ABDAY_1
@anchor{library/locale locale ABDAY_2}@anchor{44ec}
@deffnx {Δεδομένα} locale.ABDAY_2
@anchor{library/locale locale ABDAY_3}@anchor{44ed}
@deffnx {Δεδομένα} locale.ABDAY_3
@anchor{library/locale locale ABDAY_4}@anchor{44ee}
@deffnx {Δεδομένα} locale.ABDAY_4
@anchor{library/locale locale ABDAY_5}@anchor{44ef}
@deffnx {Δεδομένα} locale.ABDAY_5
@anchor{library/locale locale ABDAY_6}@anchor{44f0}
@deffnx {Δεδομένα} locale.ABDAY_6
@anchor{library/locale locale ABDAY_7}@anchor{44f1}
@deffnx {Δεδομένα} locale.ABDAY_7

Get the abbreviated name of the n-th day of the week.
@end deffn

@geindex MON_1 (στη μονάδα locale)
@geindex MON_2 (στη μονάδα locale)
@geindex MON_3 (στη μονάδα locale)
@geindex MON_4 (στη μονάδα locale)
@geindex MON_5 (στη μονάδα locale)
@geindex MON_6 (στη μονάδα locale)
@geindex MON_7 (στη μονάδα locale)
@geindex MON_8 (στη μονάδα locale)
@geindex MON_9 (στη μονάδα locale)
@geindex MON_10 (στη μονάδα locale)
@geindex MON_11 (στη μονάδα locale)
@geindex MON_12 (στη μονάδα locale)
@anchor{library/locale locale MON_1}@anchor{44f2}
@deffn {Δεδομένα} locale.MON_1
@anchor{library/locale locale MON_2}@anchor{44f3}
@deffnx {Δεδομένα} locale.MON_2
@anchor{library/locale locale MON_3}@anchor{44f4}
@deffnx {Δεδομένα} locale.MON_3
@anchor{library/locale locale MON_4}@anchor{44f5}
@deffnx {Δεδομένα} locale.MON_4
@anchor{library/locale locale MON_5}@anchor{44f6}
@deffnx {Δεδομένα} locale.MON_5
@anchor{library/locale locale MON_6}@anchor{44f7}
@deffnx {Δεδομένα} locale.MON_6
@anchor{library/locale locale MON_7}@anchor{44f8}
@deffnx {Δεδομένα} locale.MON_7
@anchor{library/locale locale MON_8}@anchor{44f9}
@deffnx {Δεδομένα} locale.MON_8
@anchor{library/locale locale MON_9}@anchor{44fa}
@deffnx {Δεδομένα} locale.MON_9
@anchor{library/locale locale MON_10}@anchor{44fb}
@deffnx {Δεδομένα} locale.MON_10
@anchor{library/locale locale MON_11}@anchor{44fc}
@deffnx {Δεδομένα} locale.MON_11
@anchor{library/locale locale MON_12}@anchor{44fd}
@deffnx {Δεδομένα} locale.MON_12

Get the name of the n-th month.
@end deffn

@geindex ABMON_1 (στη μονάδα locale)
@geindex ABMON_2 (στη μονάδα locale)
@geindex ABMON_3 (στη μονάδα locale)
@geindex ABMON_4 (στη μονάδα locale)
@geindex ABMON_5 (στη μονάδα locale)
@geindex ABMON_6 (στη μονάδα locale)
@geindex ABMON_7 (στη μονάδα locale)
@geindex ABMON_8 (στη μονάδα locale)
@geindex ABMON_9 (στη μονάδα locale)
@geindex ABMON_10 (στη μονάδα locale)
@geindex ABMON_11 (στη μονάδα locale)
@geindex ABMON_12 (στη μονάδα locale)
@anchor{library/locale locale ABMON_1}@anchor{44fe}
@deffn {Δεδομένα} locale.ABMON_1
@anchor{library/locale locale ABMON_2}@anchor{44ff}
@deffnx {Δεδομένα} locale.ABMON_2
@anchor{library/locale locale ABMON_3}@anchor{4500}
@deffnx {Δεδομένα} locale.ABMON_3
@anchor{library/locale locale ABMON_4}@anchor{4501}
@deffnx {Δεδομένα} locale.ABMON_4
@anchor{library/locale locale ABMON_5}@anchor{4502}
@deffnx {Δεδομένα} locale.ABMON_5
@anchor{library/locale locale ABMON_6}@anchor{4503}
@deffnx {Δεδομένα} locale.ABMON_6
@anchor{library/locale locale ABMON_7}@anchor{4504}
@deffnx {Δεδομένα} locale.ABMON_7
@anchor{library/locale locale ABMON_8}@anchor{4505}
@deffnx {Δεδομένα} locale.ABMON_8
@anchor{library/locale locale ABMON_9}@anchor{4506}
@deffnx {Δεδομένα} locale.ABMON_9
@anchor{library/locale locale ABMON_10}@anchor{4507}
@deffnx {Δεδομένα} locale.ABMON_10
@anchor{library/locale locale ABMON_11}@anchor{4508}
@deffnx {Δεδομένα} locale.ABMON_11
@anchor{library/locale locale ABMON_12}@anchor{4509}
@deffnx {Δεδομένα} locale.ABMON_12

Get the abbreviated name of the n-th month.
@end deffn

@geindex RADIXCHAR (στη μονάδα locale)
@anchor{library/locale locale RADIXCHAR}@anchor{450a}
@deffn {Δεδομένα} locale.RADIXCHAR

Get the radix character (decimal dot, decimal comma, etc.).
@end deffn

@geindex THOUSEP (στη μονάδα locale)
@anchor{library/locale locale THOUSEP}@anchor{450b}
@deffn {Δεδομένα} locale.THOUSEP

Get the separator character for thousands (groups of three digits).
@end deffn

@geindex YESEXPR (στη μονάδα locale)
@anchor{library/locale locale YESEXPR}@anchor{450c}
@deffn {Δεδομένα} locale.YESEXPR

Get a regular expression that can be used with the regex function to
recognize a positive response to a yes/no question.
@end deffn

@geindex NOEXPR (στη μονάδα locale)
@anchor{library/locale locale NOEXPR}@anchor{450d}
@deffn {Δεδομένα} 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 Σημείωση 
The regular expressions for @ref{450c,,YESEXPR} and
@ref{450d,,NOEXPR} use syntax suitable for the
@code{regex} function from the C library, which might
differ from the syntax used in @ref{c1,,re}.
@end quotation
@end cartouche
@end deffn

@geindex CRNCYSTR (στη μονάδα locale)
@anchor{library/locale locale CRNCYSTR}@anchor{450e}
@deffn {Δεδομένα} locale.CRNCYSTR

Get the currency symbol, preceded by «-» if the symbol should appear before
the value, «+» if the symbol should appear after the value, or «.» if the
symbol should replace the radix character.
@end deffn

@geindex ERA (στη μονάδα locale)
@anchor{library/locale locale ERA}@anchor{450f}
@deffn {Δεδομένα} locale.ERA

Get a string which describes how years are counted and displayed for
each era in a locale.

Most locales do not define this value.  An example of a locale which does
define this value is the Japanese one.  In Japan, the traditional
representation of dates includes the name of the era corresponding to the
then-emperor’s reign.

Normally it should not be necessary to use this value directly. Specifying
the @code{E} modifier in their format strings causes the @ref{1592,,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 (στη μονάδα locale)
@anchor{library/locale locale ERA_D_T_FMT}@anchor{4510}
@deffn {Δεδομένα} locale.ERA_D_T_FMT

Get a format string for @ref{1592,,time.strftime()} to represent date and time in a
locale-specific era-based way.
@end deffn

@geindex ERA_D_FMT (στη μονάδα locale)
@anchor{library/locale locale ERA_D_FMT}@anchor{4511}
@deffn {Δεδομένα} locale.ERA_D_FMT

Get a format string for @ref{1592,,time.strftime()} to represent a date in a
locale-specific era-based way.
@end deffn

@geindex ERA_T_FMT (στη μονάδα locale)
@anchor{library/locale locale ERA_T_FMT}@anchor{4512}
@deffn {Δεδομένα} locale.ERA_T_FMT

Get a format string for @ref{1592,,time.strftime()} to represent a time in a
locale-specific era-based way.
@end deffn

@geindex ALT_DIGITS (στη μονάδα locale)
@anchor{library/locale locale ALT_DIGITS}@anchor{4513}
@deffn {Δεδομένα} 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

The function temporarily sets the @code{LC_CTYPE} locale to the locale
of the category that determines the requested value (@code{LC_TIME},
@code{LC_NUMERIC}, @code{LC_MONETARY} or @code{LC_MESSAGES}) if locales are
different and the resulting string is non-ASCII.
This temporary change affects other threads.


Άλλαξε στην έκδοση 3.14: The function now temporarily sets the @code{LC_CTYPE} locale in some cases.

@end deffn

@geindex getdefaultlocale() (στη μονάδα locale)
@anchor{library/locale locale getdefaultlocale}@anchor{233}
@deffn {Συνάρτηση} locale.getdefaultlocale ([envvars])

Tries to determine the default locale settings and returns them as a tuple of
the form @code{(language code, encoding)}.

According to POSIX, a program which has not called @code{setlocale(LC_ALL, '@w{'})}
runs using the portable @code{'C'} locale.  Calling @code{setlocale(LC_ALL, '@w{'})} lets
it use the default locale as defined by the 
@geindex LANG
@geindex μεταβλητή περιβάλλοντος; LANG
@code{LANG} variable.  Since we
do not want to interfere with the current locale setting we thus emulate the
behavior in the way described above.

To maintain compatibility with other platforms, not only the 
@geindex LANG
@geindex μεταβλητή περιβάλλοντος; LANG
@code{LANG}
variable is tested, but a list of variables given as envvars parameter.  The
first found to be defined will be used.  `envvars' defaults to the search
path used in GNU gettext; it must always contain the variable name
@code{'LANG'}.  The GNU gettext search path contains @code{'LC_ALL'},
@code{'LC_CTYPE'}, @code{'LANG'} and @code{'LANGUAGE'}, in that order.

The language code has the same format as a @ref{44db,,locale name},
but without encoding and @code{@@}-modifier.
The language code and encoding may be @code{None} if their values cannot be
determined.
The «C» locale is represented as @code{(None, None)}.
@end deffn

@geindex getlocale() (στη μονάδα locale)
@anchor{library/locale locale getlocale}@anchor{232}
@deffn {Συνάρτηση} locale.getlocale (category=LC_CTYPE)

Returns the current setting for the given locale category as a tuple containing
the language code and encoding. `category' may be one of the @code{LC_*}
values except @ref{4514,,LC_ALL}.  It defaults to @ref{4515,,LC_CTYPE}.

The language code has the same format as a @ref{44db,,locale name},
but without encoding.
The language code and encoding may be @code{None} if their values cannot be
determined.
The «C» locale is represented as @code{(None, None)}.


Άλλαξε στην έκδοση 3.15: @code{@@}-modifier are no longer silently removed, but included in
the language code.

@end deffn

@geindex getpreferredencoding() (στη μονάδα locale)
@anchor{library/locale locale getpreferredencoding}@anchor{947}
@deffn {Συνάρτηση} locale.getpreferredencoding (do_setlocale=True)

Return the @ref{74d,,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.

On some systems, it is necessary to invoke @ref{231,,setlocale()} to obtain the
user preferences, so this function is not thread-safe. If invoking setlocale
is not necessary or desired, `do_setlocale' should be set to @code{False}.

On Android or if the @ref{a46,,Python UTF-8 Mode} is enabled, always
return @code{'utf-8'}, the @ref{74d,,locale encoding} and the `do_setlocale'
argument are ignored.

The @ref{4516,,Python preinitialization} configures the LC_CTYPE
locale. See also the @ref{948,,filesystem encoding and error handler}.


Άλλαξε στην έκδοση 3.7: The function now always returns @code{"utf-8"} on Android or if the
@ref{a46,,Python UTF-8 Mode} is enabled.

@end deffn

@geindex getencoding() (στη μονάδα locale)
@anchor{library/locale locale getencoding}@anchor{a45}
@deffn {Συνάρτηση} locale.getencoding ()

Get the current @ref{74d,,locale encoding}:


@itemize *

@item 
On Android and VxWorks, return @code{"utf-8"}.

@item 
On Unix, return the encoding of the current @ref{4515,,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{4516,,Python preinitialization} configures the LC_CTYPE
locale. See also the @ref{948,,filesystem encoding and error handler}.

This function is similar to
@ref{947,,getpreferredencoding(False)} except this
function ignores the @ref{a46,,Python UTF-8 Mode}.


Added in version 3.11.

@end deffn

@geindex normalize() (στη μονάδα locale)
@anchor{library/locale locale normalize}@anchor{4517}
@deffn {Συνάρτηση} locale.normalize (localename)

Returns a normalized locale code for the given locale name.  The returned locale
code is formatted for use with @ref{231,,setlocale()}.  If normalization fails, the
original name is returned unchanged.

If the given encoding is not known, the function defaults to the default
encoding for the locale code just like @ref{231,,setlocale()}.
@end deffn

@geindex strcoll() (στη μονάδα locale)
@anchor{library/locale locale strcoll}@anchor{4518}
@deffn {Συνάρτηση} locale.strcoll (string1, string2)

Compares two strings according to the current @ref{4519,,LC_COLLATE} setting. As
any other compare function, returns a negative, or a positive value, or @code{0},
depending on whether `string1' collates before or after `string2' or is equal to
it.
@end deffn

@geindex strxfrm() (στη μονάδα locale)
@anchor{library/locale locale strxfrm}@anchor{19f7}
@deffn {Συνάρτηση} locale.strxfrm (string)

Transforms a string to one that can be used in locale-aware
comparisons.  For example, @code{strxfrm(s1) < strxfrm(s2)} is
equivalent to @code{strcoll(s1, s2) < 0}.  This function can be used
when the same string is compared repeatedly, e.g. when collating a
sequence of strings.
@end deffn

@geindex format_string() (στη μονάδα locale)
@anchor{library/locale locale format_string}@anchor{92d}
@deffn {Συνάρτηση} locale.format_string (format, val, grouping=False, monetary=False)

Formats a number `val' according to the current @ref{44dc,,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.

If `monetary' is true, the conversion uses monetary thousands separator and
grouping strings.

Processes formatting specifiers as in @code{format % val}, but takes the current
locale settings into account.


Άλλαξε στην έκδοση 3.7: The `monetary' keyword parameter was added.

@end deffn

@geindex currency() (στη μονάδα locale)
@anchor{library/locale locale currency}@anchor{451a}
@deffn {Συνάρτηση} locale.currency (val, symbol=True, grouping=False, international=False)

Formats a number `val' according to the current @ref{44de,,LC_MONETARY} settings.

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 Σημείωση 
This function will not work with the “C” locale, so you have to set a
locale via @ref{231,,setlocale()} first.
@end quotation
@end cartouche
@end deffn

@geindex str() (στη μονάδα locale)
@anchor{library/locale locale str}@anchor{451b}
@deffn {Συνάρτηση} 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() (στη μονάδα locale)
@anchor{library/locale locale delocalize}@anchor{11d9}
@deffn {Συνάρτηση} locale.delocalize (string)

Converts a string into a normalized number string, following the
@ref{44dc,,LC_NUMERIC} settings.


Added in version 3.5.

@end deffn

@geindex localize() (στη μονάδα locale)
@anchor{library/locale locale localize}@anchor{451c}
@deffn {Συνάρτηση} locale.localize (string, grouping=False, monetary=False)

Converts a normalized number string into a formatted string following the
@ref{44dc,,LC_NUMERIC} settings.


Added in version 3.10.

@end deffn

@geindex atof() (στη μονάδα locale)
@anchor{library/locale locale atof}@anchor{451d}
@deffn {Συνάρτηση} locale.atof (string, func=float)

Converts a string to a number, following the @ref{44dc,,LC_NUMERIC} settings,
by calling `func' on the result of calling @ref{11d9,,delocalize()} on `string'.
@end deffn

@geindex atoi() (στη μονάδα locale)
@anchor{library/locale locale atoi}@anchor{451e}
@deffn {Συνάρτηση} locale.atoi (string)

Converts a string to an integer, following the @ref{44dc,,LC_NUMERIC} conventions.
@end deffn

@geindex LC_CTYPE (στη μονάδα locale)
@anchor{library/locale locale LC_CTYPE}@anchor{4515}
@deffn {Δεδομένα} 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, @code{pyctype.h} provides locale-independent
equivalents like @ref{16fd,,Py_TOLOWER}.
@end deffn

@geindex LC_COLLATE (στη μονάδα locale)
@anchor{library/locale locale LC_COLLATE}@anchor{4519}
@deffn {Δεδομένα} locale.LC_COLLATE

Locale category for sorting strings.  The functions @ref{4518,,strcoll()} and
@ref{19f7,,strxfrm()} of the @code{locale} module are affected.
@end deffn

@geindex LC_TIME (στη μονάδα locale)
@anchor{library/locale locale LC_TIME}@anchor{451f}
@deffn {Δεδομένα} locale.LC_TIME

Locale category for the formatting of time.  The function @ref{1592,,time.strftime()}
follows these conventions.
@end deffn

@geindex LC_MONETARY (στη μονάδα locale)
@anchor{library/locale locale LC_MONETARY}@anchor{44de}
@deffn {Δεδομένα} locale.LC_MONETARY

Locale category for formatting of monetary values.  The available options are
available from the @ref{fbd,,localeconv()} function.
@end deffn

@geindex LC_MESSAGES (στη μονάδα locale)
@anchor{library/locale locale LC_MESSAGES}@anchor{4520}
@deffn {Δεδομένα} locale.LC_MESSAGES

Locale category for message display. Python currently does not support
application specific locale-aware messages.  Messages displayed by the operating
system, like those returned by @ref{3249,,os.strerror()} might be affected by this
category.

This value may not be available on operating systems not conforming to the
POSIX standard, most notably Windows.
@end deffn

@geindex LC_NUMERIC (στη μονάδα locale)
@anchor{library/locale locale LC_NUMERIC}@anchor{44dc}
@deffn {Δεδομένα} locale.LC_NUMERIC

Locale category for formatting numbers.  The functions @ref{92d,,format_string()},
@ref{451e,,atoi()}, @ref{451d,,atof()} and @ref{451b,,str()} of the @code{locale} module are
affected by that category.  All other numeric formatting operations are not
affected.
@end deffn

@geindex LC_ALL (στη μονάδα locale)
@anchor{library/locale locale LC_ALL}@anchor{4514}
@deffn {Δεδομένα} locale.LC_ALL

Combination of all locale settings.  If this flag is used when the locale is
changed, setting the locale for all categories is attempted. If that fails for
any category, no category is changed at all.  When the locale is retrieved using
this flag, a string indicating the setting for all categories is returned. This
string can be later used to restore the settings.
@end deffn

@geindex CHAR_MAX (στη μονάδα locale)
@anchor{library/locale locale CHAR_MAX}@anchor{44dd}
@deffn {Δεδομένα} locale.CHAR_MAX

This is a symbolic constant used for different values returned by
@ref{fbd,,localeconv()}.
@end deffn

@menu
* Background@comma{} details@comma{} hints@comma{} tips and caveats: Background details hints tips and caveats. 
* Locale names:: 
* For extension writers and programs that embed Python:: 
* Access to message catalogs:: 

@end menu

@node Background details hints tips and caveats,Locale names,,locale — Internationalization services
@anchor{library/locale background-details-hints-tips-and-caveats}@anchor{4521}
@subsubsection Background, details, hints, tips and caveats


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.

Initially, when a program is started, the locale is the @code{C} locale, no matter
what the user’s preferred locale is.  There is one exception: the
@ref{4515,,LC_CTYPE} category is changed at startup to set the current locale
encoding to the user’s preferred locale encoding. The program must explicitly
say that it wants the user’s preferred locale settings for other categories by
calling @code{setlocale(LC_ALL, '@w{'})}.

It is generally a bad idea to call @ref{231,,setlocale()} in some library routine,
since as a side effect it affects the entire program.  Saving and restoring it
is almost as bad: it is expensive and affects other threads that happen to run
before the settings have been restored.

If, when coding a module for general use, you need a locale independent version
of an operation that is affected by the locale (such as
certain formats used with @ref{1592,,time.strftime()}), you will have to find a way to
do it without using the standard library routine.  Even better is convincing
yourself that using locale settings is okay.  Only as a last resort should you
document that your module is not compatible with non-@code{C} locale settings.

The only way to perform numeric operations according to the locale is to use the
special functions defined by this module: @ref{451d,,atof()}, @ref{451e,,atoi()},
@ref{92d,,format_string()}, @ref{451b,,str()}.

There is no way to perform case conversions and character classifications
according to the locale.  For (Unicode) text strings these are done according
to the character value only, while for byte strings, the conversions and
classifications are done according to the ASCII value of the byte, and bytes
whose high bit is set (i.e., non-ASCII bytes) are never converted or considered
part of a character class such as letter or whitespace.

@node Locale names,For extension writers and programs that embed Python,Background details hints tips and caveats,locale — Internationalization services
@anchor{library/locale locale-name}@anchor{44db}@anchor{library/locale locale-names}@anchor{4522}
@subsubsection Locale names


The format of the locale name is platform dependent, and the set of supported
locales can depend on the system configuration.

On Posix platforms, it usually has the format @footnote{
@uref{https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html#tag_08_02,IEEE Std 1003.1-2024; 8.2 Internationalization Variables}
}:

@example
  language ["_" territory] ["." charset] ["@@" modifier]
@end example

where `language' is a two- or three-letter language code from ISO 639@footnote{https://www.iso.org/iso-639-language-code},
`territory' is a two-letter country or region code from ISO 3166@footnote{https://www.iso.org/iso-3166-country-codes.html},
`charset' is a locale encoding, and `modifier' is a script name,
a language subtag, a sort order identifier, or other locale modifier
(for example, «latin», «valencia», «stroke» and «euro»).

On Windows, several formats are supported. @footnote{
@uref{https://learn.microsoft.com/en-us/cpp/c-runtime-library/locale-names-languages-and-country-region-strings,UCRT Locale names@comma{} Languages@comma{} and Country/Region strings}
} @footnote{
@uref{https://learn.microsoft.com/en-us/windows/win32/intl/locale-names,Locale Names}
}
A subset of IETF BCP 47@footnote{https://www.rfc-editor.org/info/bcp47} tags:

@example
  language ["-" script] ["-" territory] ["." charset]
  language ["-" script] "-" territory "-" modifier
@end example

where `language' and `territory' have the same meaning as in Posix,
`script' is a four-letter script code from ISO 15924@footnote{https://www.unicode.org/iso15924/},
and `modifier' is a language subtag, a sort order identifier
or custom modifier (for example, «valencia», «stroke» or «x-python»).
Both hyphen (@code{'-'}) and underscore (@code{'_'}) separators are supported.
Only UTF-8 encoding is allowed for BCP 47 tags.

Windows also supports locale names in the format:

@example
  language ["_" territory] ["." charset]
@end example

where `language' and `territory' are full names, such as «English» and
«United States», and `charset' is either a code page number (for example, «1252»)
or UTF-8.
Only the underscore separator is supported in this format.

The «C» locale is supported on all platforms.

@node For extension writers and programs that embed Python,Access to message catalogs,Locale names,locale — Internationalization services
@anchor{library/locale embedding-locale}@anchor{4523}@anchor{library/locale for-extension-writers-and-programs-that-embed-python}@anchor{4524}
@subsubsection For extension writers and programs that embed Python


Extension modules should never call @ref{231,,setlocale()}, except to find out what
the current locale is.  But since the return value can only be used portably to
restore it, that is not very useful (except perhaps to find out whether or not
the locale is @code{C}).

When Python code uses the @code{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 Access to message catalogs,,For extension writers and programs that embed Python,locale — Internationalization services
@anchor{library/locale access-to-message-catalogs}@anchor{4525}@anchor{library/locale locale-gettext}@anchor{4526}
@subsubsection Access to message catalogs


@geindex gettext() (στη μονάδα locale)
@anchor{library/locale locale gettext}@anchor{4527}
@deffn {Συνάρτηση} locale.gettext (msg)
@end deffn

@geindex dgettext() (στη μονάδα locale)
@anchor{library/locale locale dgettext}@anchor{4528}
@deffn {Συνάρτηση} locale.dgettext (domain, msg)
@end deffn

@geindex dcgettext() (στη μονάδα locale)
@anchor{library/locale locale dcgettext}@anchor{4529}
@deffn {Συνάρτηση} locale.dcgettext (domain, msg, category)
@end deffn

@geindex textdomain() (στη μονάδα locale)
@anchor{library/locale locale textdomain}@anchor{452a}
@deffn {Συνάρτηση} locale.textdomain (domain)
@end deffn

@geindex bindtextdomain() (στη μονάδα locale)
@anchor{library/locale locale bindtextdomain}@anchor{452b}
@deffn {Συνάρτηση} locale.bindtextdomain (domain, dir)
@end deffn

@geindex bind_textdomain_codeset() (στη μονάδα locale)
@anchor{library/locale locale bind_textdomain_codeset}@anchor{452c}
@deffn {Συνάρτηση} 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{66,,gettext()},
@ref{4528,,dgettext()}, @ref{4529,,dcgettext()}, @ref{452a,,textdomain()}, @ref{452b,,bindtextdomain()},
and @ref{452c,,bind_textdomain_codeset()}.  These are similar to the same functions in
the @ref{66,,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{66,,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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Γραφικές επαφές χρηστών με το Tk,Εργαλεία Ανάπτυξης,Internationalization,The Python Standard Library
@anchor{library/tk doc}@anchor{452d}@anchor{library/tk graphical-user-interfaces-with-tk}@anchor{452e}@anchor{library/tk tkinter}@anchor{452f}@anchor{library/tk translation-repo}@anchor{4530}
@section Γραφικές επαφές χρηστών με το Tk


@geindex GUI
@geindex Γραφική Διεπαφή Χρήστη
@geindex Tkinter
@geindex Tk

Το Tk/Tcl αποτελεί από καιρό αναπόσπαστο μέρος της Python. Παρέχει ένα ισχυρό και ανεξάρτητο πλατφόρμας εργαλείο παραθύρων, το οποίο είναι διαθέσιμο στους προγραμματιστές της Python που χρησιμοποιούν το πακέτο @ref{f9,,tkinter} και την επέκτασή του, το @ref{102,,tkinter.ttk} module.

Το πακέτο @ref{f9,,tkinter} είναι ένα λεπτό αντικειμενοστραφές στρώμα πάνω από το Tcl/Tk.Για να χρησιμοποιήσετε το @code{tkinter}, δεν χρειάζεται να γράψετε κώδικα Tcl, αλλά θα χρειαστεί να συμβουλευτείτε την τεκμηρίωση του Tcl. Το @code{tkinter} είναι ένα σύνολο περιβλημάτων που υλοποιούν τα widget του Tk ως κλάσεις Python.

Το @ref{f9,,tkinter} έχει ως κύρια πλεονεκτήματα το γεγονός ότι είναι γρήγορο και ότι συνήθως συνοδεύει την Python. Αν και η τυπική τεκμηρίωσή του είναι ανεπαρκής, υπάρχει καλό υλικό διαθέσιμο, το οποίο περιλαμβάνει: αναφορές, σεμινάρια, ένα βιβλίο και άλλα. Το @code{tkinter} είναι επίσης γνωστό για την ξεπερασμένη του εμφάνιση και αίσθηση, η οποία έχει βελτιωθεί σημαντικά στο Tk 8.5. Παρ” όλα αυτά, υπάρχουν πολλές άλλες βιβλιοθήκες GUI που μπορεί να σας ενδιαφέρουν. Το Python wiki παραθέτει διάφορα εναλλακτικά GUI frameworks and tools@footnote{https://wiki.python.org/moin/GuiProgramming}.

@menu
* tkinter — Python interface to Tcl/Tk:: 
* tkinter.colorchooser — Color choosing dialog: tkinter colorchooser — Color choosing dialog. 
* tkinter.font — Tkinter font wrapper: tkinter font — Tkinter font wrapper. 
* Tkinter Dialogs:: 
* tkinter.messagebox — Tkinter message prompts: tkinter messagebox — Tkinter message prompts. 
* tkinter.scrolledtext — Scrolled Text Widget: tkinter scrolledtext — Scrolled Text Widget. 
* tkinter.dnd — Drag and drop support: tkinter dnd — Drag and drop support. 
* tkinter.ttk — Tk themed widgets: tkinter ttk — Tk themed widgets. 
* IDLE — Python editor and shell:: 
* turtle — Turtle graphics:: 

@end menu

@node tkinter — Python interface to Tcl/Tk,tkinter colorchooser — Color choosing dialog,,Γραφικές επαφές χρηστών με το Tk
@anchor{library/tkinter doc}@anchor{4531}@anchor{library/tkinter module-tkinter}@anchor{f9}@anchor{library/tkinter tkinter-python-interface-to-tcl-tk}@anchor{4532}
@subsection @code{tkinter} — Python interface to Tcl/Tk


@geindex module; tkinter

`Source code:' Lib/tkinter/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/tkinter/__init__.py}


__________________________________________________________________


The @code{tkinter} package («Tk interface») is the standard Python interface to
the Tcl/Tk GUI toolkit.  Both Tk and @code{tkinter} are available on most Unix
platforms, including macOS, as well as on Windows systems.

Running @code{python -m tkinter} from the command line should open a window
demonstrating a simple Tk interface, letting you know that @code{tkinter} is
properly installed on your system, and also showing what version of Tcl/Tk is
installed, so you can read the Tcl/Tk documentation specific to that version.

Tkinter supports a range of Tcl/Tk versions, built either with or
without thread support. The official Python binary release bundles Tcl/Tk 8.6
threaded. See the source code for the @ref{3,,_tkinter} module
for more information about supported versions.

Tkinter is not a thin wrapper, but adds a fair amount of its own logic to
make the experience more pythonic. This documentation will concentrate on these
additions and changes, and refer to the official Tcl/Tk documentation for
details that are unchanged.

@cartouche
@quotation Σημείωση 
Tcl/Tk 8.5 (2007) introduced a modern set of themed user interface components
along with a new API to use them. Both old and new APIs are still available.
Most documentation you will find online still uses the old API and
can be woefully outdated.
@end quotation
@end cartouche

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile


@subsubheading Δείτε επίσης



@itemize *

@item 

@table @asis

@item TkDocs@footnote{https://tkdocs.com/}

Extensive tutorial on creating user interfaces with Tkinter.  Explains key concepts,
and illustrates recommended approaches using the modern API.
@end table

@item 

@table @asis

@item Tkinter 8.5 reference: a GUI for Python@footnote{https://www.tkdocs.com/shipman/}

Reference documentation for Tkinter 8.5 detailing available classes, methods, and options.
@end table
@end itemize

Tcl/Tk Resources:


@itemize *

@item 

@table @asis

@item Tk commands@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm}

Comprehensive reference to each of the underlying Tcl/Tk commands used by Tkinter.
@end table

@item 

@table @asis

@item Tcl/Tk Home Page@footnote{https://www.tcl.tk}

Additional documentation, and links to Tcl/Tk core development.
@end table
@end itemize

Books:


@itemize *

@item 

@table @asis

@item Modern Tkinter for Busy Python Developers@footnote{https://tkdocs.com/book.html}

By 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}

By Mark Lutz; has excellent coverage of 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}

By John Ousterhout, inventor of Tcl/Tk, and Ken Jones; does not cover Tkinter. (ISBN 978-0321336330)
@end table
@end itemize


@menu
* Architecture:: 
* Tkinter Modules:: 
* Tkinter Life Preserver:: 
* Threading model:: 
* Handy Reference:: 
* File Handlers:: 

@end menu

@node Architecture,Tkinter Modules,,tkinter — Python interface to Tcl/Tk
@anchor{library/tkinter architecture}@anchor{4533}
@subsubsection Architecture


Tcl/Tk is not a single library but rather consists of a few distinct
modules, each with separate functionality and its own official
documentation. Python’s binary releases also ship an add-on module
together with it.


@table @asis

@item Tcl

Tcl is a dynamic interpreted programming language, just like Python. Though
it can be used on its own as a general-purpose programming language, it is
most commonly embedded into C applications as a scripting engine or an
interface to the Tk toolkit. The Tcl library has a C interface to
create and manage one or more instances of a Tcl interpreter, run Tcl
commands and scripts in those instances, and add custom commands
implemented in either Tcl or C. Each interpreter has an event queue,
and there are facilities to send events to it and process them.
Unlike Python, Tcl’s execution model is designed around cooperative
multitasking, and Tkinter bridges this difference
(see @ref{4534,,Threading model} for details).

@item Tk

Tk is a Tcl package@footnote{https://wiki.tcl-lang.org/37432} implemented in C
that adds custom commands to create and manipulate GUI widgets. Each
@ref{1bb6,,Tk} object embeds its own Tcl interpreter instance with Tk loaded into
it. Tk’s widgets are very customizable, though at the cost of a dated appearance.
Tk uses Tcl’s event queue to generate and process GUI events.

@item Ttk

Themed Tk (Ttk) is a newer family of Tk widgets that provide a much better
appearance on different platforms than many of the classic Tk widgets.
Ttk is distributed as part of Tk, starting with Tk version 8.5. Python
bindings are provided in a separate module, @ref{102,,tkinter.ttk}.
@end table

Internally, Tk and Ttk use facilities of the underlying operating system,
i.e., Xlib on Unix/X11, Cocoa on macOS, GDI on Windows.

When your Python application uses a class in Tkinter, e.g., to create a widget,
the @code{tkinter} module first assembles a Tcl/Tk command string. It passes that
Tcl command string to an internal @ref{3,,_tkinter} binary module, which then
calls the Tcl interpreter to evaluate it. The Tcl interpreter will then call into the
Tk and/or Ttk packages, which will in turn make calls to Xlib, Cocoa, or GDI.

@node Tkinter Modules,Tkinter Life Preserver,Architecture,tkinter — Python interface to Tcl/Tk
@anchor{library/tkinter tkinter-modules}@anchor{4535}
@subsubsection Tkinter Modules


Support for Tkinter is spread across several modules. Most applications will need the
main @code{tkinter} module, as well as the @ref{102,,tkinter.ttk} module, which provides
the modern themed widget set and API:

@example
from tkinter import *
from tkinter import ttk
@end example

@geindex Tk (κλάση σε tkinter)
@anchor{library/tkinter tkinter Tk}@anchor{1bb6}
@deffn {Κλάση} tkinter.Tk (screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None)

Construct a toplevel Tk widget, which is usually the main window of an
application, and initialize a Tcl interpreter for this widget.  Each
instance has its own associated Tcl interpreter.

The @code{Tk} class is typically instantiated using all default values.
However, the following keyword arguments are currently recognized:


@table @asis

@item `screenName'

When given (as a string), sets the 
@geindex DISPLAY
@geindex μεταβλητή περιβάλλοντος; DISPLAY
@code{DISPLAY} environment
variable. (X11 only)

@item `baseName'

Name of the profile file.  By default, `baseName' is derived from the
program name (@code{sys.argv[0]}).

@item `className'

Name of the widget class.  Used as a profile file and also as the name
with which Tcl is invoked (`argv0' in `interp').

@item `useTk'

If @code{True}, initialize the Tk subsystem.  The @ref{4536,,tkinter.Tcl()}
function sets this to @code{False}.

@item `sync'

If @code{True}, execute all X server commands synchronously, so that errors
are reported immediately.  Can be used for debugging. (X11 only)

@item `use'

Specifies the `id' of the window in which to embed the application,
instead of it being created as an independent toplevel window. `id' must
be specified in the same way as the value for the -use option for
toplevel widgets (that is, it has a form like that returned by
@code{winfo_id()}).

Note that on some platforms this will only work correctly if `id' refers
to a Tk frame or toplevel that has its -container option enabled.
@end table

@code{Tk} reads and interprets profile files, named
@code{.`className'.tcl} and @code{.`baseName'.tcl}, into the Tcl
interpreter and calls @ref{185,,exec()} on the contents of
@code{.`className'.py} and @code{.`baseName'.py}.  The path for the
profile files is the 
@geindex HOME
@geindex μεταβλητή περιβάλλοντος; HOME
@code{HOME} environment variable or, if that
isn’t defined, then @ref{2e73,,os.curdir}.

@geindex tk (ιδιότητα της tkinter.Tk)
@anchor{library/tkinter tkinter Tk tk}@anchor{19fe}
@deffn {Ιδιότητα} tk

The Tk application object created by instantiating @code{Tk}.  This
provides access to the Tcl interpreter.  Each widget that is attached
the same instance of @code{Tk} has the same value for its @ref{19fe,,tk}
attribute.
@end deffn

@geindex master (ιδιότητα της tkinter.Tk)
@anchor{library/tkinter tkinter Tk master}@anchor{4537}
@deffn {Ιδιότητα} master

The widget object that contains this widget.  For @code{Tk}, the
@code{master} is @ref{a65,,None} because it is the main window.  The terms
`master' and `parent' are similar and sometimes used interchangeably
as argument names; however, calling @code{winfo_parent()} returns a
string of the widget name whereas @code{master} returns the object.
`parent'/`child' reflects the tree-like relationship while
`master' (or `container')/`content' reflects the container structure.
@end deffn

@geindex children (ιδιότητα της tkinter.Tk)
@anchor{library/tkinter tkinter Tk children}@anchor{4538}
@deffn {Ιδιότητα} children

The immediate descendants of this widget as a @ref{188,,dict} with the
child widget names as the keys and the child instance objects as the
values.
@end deffn
@end deffn

@geindex Tcl() (στη μονάδα tkinter)
@anchor{library/tkinter tkinter Tcl}@anchor{4536}
@deffn {Συνάρτηση} tkinter.Tcl (screenName=None, baseName=None, className='Tk', useTk=False)

The @code{Tcl()} function is a factory function which creates an object much like
that created by the @ref{1bb6,,Tk} class, except that it does not initialize the Tk
subsystem.  This is most often useful when driving the Tcl interpreter in an
environment where one doesn’t want to create extraneous toplevel windows, or
where one cannot (such as Unix/Linux systems without an X server).  An object
created by the @code{Tcl()} object can have a Toplevel window created (and the Tk
subsystem initialized) by calling its @code{loadtk()} method.
@end deffn

The modules that provide Tk support include:


@table @asis

@item @code{tkinter}

Main Tkinter module.

@item @ref{fa,,tkinter.colorchooser}

Dialog to let the user choose a color.

@item @ref{fb,,tkinter.commondialog}

Base class for the dialogs defined in the other modules listed here.

@item @ref{fd,,tkinter.filedialog}

Common dialogs to allow the user to specify a file to open or save.

@item @ref{fe,,tkinter.font}

Utilities to help work with fonts.

@item @ref{ff,,tkinter.messagebox}

Access to standard Tk dialog boxes.

@item @ref{100,,tkinter.scrolledtext}

Text widget with a vertical scroll bar built in.

@item @ref{101,,tkinter.simpledialog}

Basic dialogs and convenience functions.

@item @ref{102,,tkinter.ttk}

Themed widget set introduced in Tk 8.5, providing modern alternatives
for many of the classic widgets in the main @code{tkinter} module.
@end table

Additional modules:

@geindex module; _tkinter
@anchor{library/tkinter module-_tkinter}@anchor{3}

@table @asis

@item @ref{3,,_tkinter}

A binary module that contains the low-level interface to Tcl/Tk.
It is automatically imported by the main @code{tkinter} module,
and should never be used directly by application programmers.
It is usually a shared library (or DLL), but might in some cases be
statically linked with the Python interpreter.

@item @ref{76,,idlelib}

Python’s Integrated Development and Learning Environment (IDLE). Based
on @code{tkinter}.

@item @code{tkinter.constants}

Symbolic constants that can be used in place of strings when passing
various parameters to Tkinter calls. Automatically imported by the
main @code{tkinter} module.

@item @ref{fc,,tkinter.dnd}

(experimental) Drag-and-drop support for @code{tkinter}. This will
become deprecated when it is replaced with the Tk DND.

@item @ref{10a,,turtle}

Turtle graphics in a Tk window.
@end table

@node Tkinter Life Preserver,Threading model,Tkinter Modules,tkinter — Python interface to Tcl/Tk
@anchor{library/tkinter tkinter-life-preserver}@anchor{4539}
@subsubsection Tkinter Life Preserver


This section is not designed to be an exhaustive tutorial on either Tk or
Tkinter.  For that, refer to one of the external resources noted earlier.
Instead, this section provides a very quick orientation to what a Tkinter
application looks like, identifies foundational Tk concepts, and
explains how the Tkinter wrapper is structured.

The remainder of this section will help you to identify the classes,
methods, and options you’ll need in your Tkinter application, and where to
find more detailed documentation on them, including in the official Tcl/Tk
reference manual.

@menu
* A Hello World Program:: 
* Important Tk Concepts:: 
* Understanding How Tkinter Wraps Tcl/Tk:: 
* How do I…? What option does…?:: 
* Navigating the Tcl/Tk Reference Manual:: 

@end menu

@node A Hello World Program,Important Tk Concepts,,Tkinter Life Preserver
@anchor{library/tkinter a-hello-world-program}@anchor{453a}
@subsubsection A Hello World Program


We’ll start by walking through a «Hello World» application in Tkinter. This
isn’t the smallest one we could write, but has enough to illustrate some
key concepts you’ll need to know.

@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

After the imports, the next line creates an instance of the @code{Tk} class,
which initializes Tk and creates its associated Tcl interpreter. It also
creates a toplevel window, known as the root window, which serves as the main
window of the application.

The following line creates a frame widget, which in this case will contain
a label and a button we’ll create next. The frame is fit inside the root
window.

The next line creates a label widget holding a static text string. The
@code{grid()} method is used to specify the relative layout (position) of the
label within its containing frame widget, similar to how tables in HTML work.

A button widget is then created, and placed to the right of the label. When
pressed, it will call the @code{destroy()} method of the root window.

Finally, the @code{mainloop()} method puts everything on the display, and
responds to user input until the program terminates.

@node Important Tk Concepts,Understanding How Tkinter Wraps Tcl/Tk,A Hello World Program,Tkinter Life Preserver
@anchor{library/tkinter important-tk-concepts}@anchor{453b}
@subsubsection Important Tk Concepts


Even this simple program illustrates the following key Tk concepts:


@table @asis

@item widgets

A Tkinter user interface is made up of individual `widgets'. Each widget is
represented as a Python object, instantiated from classes like
@code{ttk.Frame}, @code{ttk.Label}, and @code{ttk.Button}.

@item widget hierarchy

Widgets are arranged in a `hierarchy'. The label and button were contained
within a frame, which in turn was contained within the root window. When
creating each `child' widget, its `parent' widget is passed as the first
argument to the widget constructor.

@item configuration options

Widgets have `configuration options', which modify their appearance and
behavior, such as the text to display in a label or button. Different
classes of widgets will have different sets of options.

@item geometry management

Widgets aren’t automatically added to the user interface when they are
created. A `geometry manager' like @code{grid} controls where in the
user interface they are placed.

@item event loop

Tkinter reacts to user input, changes from your program, and even refreshes
the display only when actively running an `event loop'. If your program
isn’t running the event loop, your user interface won’t update.
@end table

@node Understanding How Tkinter Wraps Tcl/Tk,How do I…? What option does…?,Important Tk Concepts,Tkinter Life Preserver
@anchor{library/tkinter understanding-how-tkinter-wraps-tcl-tk}@anchor{453c}
@subsubsection Understanding How Tkinter Wraps 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.

Whether it’s trying to navigate reference documentation, trying to find
the right method or option, adapting some existing code, or debugging your
Tkinter application, there are times that it will be useful to understand
what those underlying Tcl/Tk commands look like.

To illustrate, here is the Tcl/Tk equivalent of the main part of the Tkinter
script above.

@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

Tcl’s syntax is similar to many shell languages, where the first word is the
command to be executed, with arguments to that command following it, separated
by spaces. Without getting into too many details, notice the following:


@itemize *

@item 
The commands used to create widgets (like @code{ttk::frame}) correspond to
widget classes in Tkinter.

@item 
Tcl widget options (like @code{-text}) correspond to keyword arguments in
Tkinter.

@item 
Widgets are referred to by a `pathname' in Tcl (like @code{.frm.btn}),
whereas Tkinter doesn’t use names but object references.

@item 
A widget’s place in the widget hierarchy is encoded in its (hierarchical)
pathname, which uses a @code{.} (dot) as a path separator. The pathname for
the root window is just @code{.} (dot). In Tkinter, the hierarchy is defined
not by pathname but by specifying the parent widget when creating each
child widget.

@item 
Operations which are implemented as separate `commands' in Tcl (like
@code{grid} or @code{destroy}) are represented as `methods' on Tkinter widget
objects. As you’ll see shortly, at other times Tcl uses what appear to be
method calls on widget objects, which more closely mirror what is
used in Tkinter.
@end itemize

@node How do I…? What option does…?,Navigating the Tcl/Tk Reference Manual,Understanding How Tkinter Wraps Tcl/Tk,Tkinter Life Preserver
@anchor{library/tkinter how-do-i-what-option-does}@anchor{453d}
@subsubsection How do I…? What option does…?


If you’re not sure how to do something in Tkinter, and you can’t immediately
find it in the tutorial or reference documentation you’re using, there are a
few strategies that can be helpful.

First, remember that the details of how individual widgets work may vary
across different versions of both Tkinter and Tcl/Tk. If you’re searching
documentation, make sure it corresponds to the Python and Tcl/Tk versions
installed on your system.

When searching for how to use an API, it helps to know the exact name of the
class, option, or method that you’re using. Introspection, either in an
interactive Python shell or with @ref{131f,,print()}, can help you identify what
you need.

To find out what configuration options are available on any widget, call its
@code{configure()} method, which returns a dictionary containing a variety of
information about each object, including its default and current values. Use
@code{keys()} to get just the names of each option.

@example
btn = ttk.Button(frm, ...)
print(btn.configure().keys())
@end example

As most widgets have many configuration options in common, it can be useful
to find out which are specific to a particular widget class. Comparing the
list of options to that of a simpler widget, like a frame, is one way to
do that.

@example
print(set(btn.configure().keys()) - set(frm.configure().keys()))
@end example

Similarly, you can find the available methods for a widget object using the
standard @ref{a23,,dir()} function. If you try it, you’ll see there are over 200
common widget methods, so again identifying those specific to a widget class
is helpful.

@example
print(dir(btn))
print(set(dir(btn)) - set(dir(frm)))
@end example

@node Navigating the Tcl/Tk Reference Manual,,How do I…? What option does…?,Tkinter Life Preserver
@anchor{library/tkinter navigating-the-tcl-tk-reference-manual}@anchor{453e}
@subsubsection Navigating the Tcl/Tk Reference Manual


As noted, the official Tk commands@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm}
reference manual (man pages) is often the most accurate description of what
specific operations on widgets do. Even when you know the name of the option
or method that you need, you may still have a few places to look.

While all operations in Tkinter are implemented as method calls on widget
objects, you’ve seen that many Tcl/Tk operations appear as commands that
take a widget pathname as its first parameter, followed by optional
parameters, e.g.

@example
destroy .
grid .frm.btn -column 0 -row 0
@end example

Others, however, look more like methods called on a widget object (in fact,
when you create a widget in Tcl/Tk, it creates a Tcl command with the name
of the widget pathname, with the first parameter to that command being the
name of a method to call).

@example
.frm.btn invoke
.frm.lbl configure -text "Goodbye"
@end example

In the official Tcl/Tk reference documentation, you’ll find most operations
that look like method calls on the man page for a specific widget (e.g.,
you’ll find the @code{invoke()} method on the
ttk::button@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/ttk_button.htm}
man page), while functions that take a widget as a parameter often have
their own man page (e.g.,
grid@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/grid.htm}).

You’ll find many common options and methods in the
options@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/options.htm} or
ttk::widget@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/ttk_widget.htm} man
pages, while others are found in the man page for a specific widget class.

You’ll also find that many Tkinter methods have compound names, e.g.,
@code{winfo_x()}, @code{winfo_height()}, @code{winfo_viewable()}. You’d find
documentation for all of these in the
winfo@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/winfo.htm} man page.

@cartouche
@quotation Σημείωση 
Somewhat confusingly, there are also methods on all Tkinter widgets
that don’t actually operate on the widget, but operate at a global
scope, independent of any widget. Examples are methods for accessing
the clipboard or the system bell. (They happen to be implemented as
methods in the base @code{Widget} class that all Tkinter widgets
inherit from).
@end quotation
@end cartouche

@node Threading model,Handy Reference,Tkinter Life Preserver,tkinter — Python interface to Tcl/Tk
@anchor{library/tkinter threading-model}@anchor{4534}
@subsubsection Threading model


Python and Tcl/Tk have very different threading models, which @code{tkinter}
tries to bridge. If you use threads, you may need to be aware of this.

A Python interpreter may have many threads associated with it. In Tcl, multiple
threads can be created, but each thread has a separate Tcl interpreter instance
associated with it. Threads can also create more than one interpreter instance,
though each interpreter instance can be used only by the one thread that created it.

Each @code{Tk} object created by @code{tkinter} contains a Tcl interpreter.
It also keeps track of which thread created that interpreter. Calls to
@code{tkinter} can be made from any Python thread. Internally, if a call comes
from a thread other than the one that created the @code{Tk} object, an event
is posted to the interpreter’s event queue, and when executed, the result is
returned to the calling Python thread.

Tcl/Tk applications are normally event-driven, meaning that after initialization,
the interpreter runs an event loop (i.e. @code{Tk.mainloop()}) and responds to events.
Because it is single-threaded, event handlers must respond quickly, otherwise they
will block other events from being processed. To avoid this, any long-running
computations should not run in an event handler, but are either broken into smaller
pieces using timers, or run in another thread. This is different from many GUI
toolkits where the GUI runs in a completely separate thread from all application
code including event handlers.

If the Tcl interpreter is not running the event loop and processing events, any
@code{tkinter} calls made from threads other than the one running the Tcl
interpreter will fail.

A number of special cases exist:


@itemize *

@item 
Tcl/Tk libraries can be built so they are not thread-aware. In this case,
@code{tkinter} calls the library from the originating Python thread, even
if this is different than the thread that created the Tcl interpreter. A global
lock ensures only one call occurs at a time.

@item 
While @code{tkinter} allows you to create more than one instance of a @code{Tk}
object (with its own interpreter), all interpreters that are part of the same
thread share a common event queue, which gets ugly fast. In practice, don’t create
more than one instance of @code{Tk} at a time. Otherwise, it’s best to create
them in separate threads and ensure you’re running a thread-aware Tcl/Tk build.

@item 
Blocking event handlers are not the only way to prevent the Tcl interpreter from
reentering the event loop. It is even possible to run multiple nested event loops
or abandon the event loop entirely. If you’re doing anything tricky when it comes
to events or threads, be aware of these possibilities.

@item 
There are a few select @code{tkinter} functions that presently work only when
called from the thread that created the Tcl interpreter.
@end itemize

@node Handy Reference,File Handlers,Threading model,tkinter — Python interface to Tcl/Tk
@anchor{library/tkinter handy-reference}@anchor{453f}
@subsubsection Handy Reference


@menu
* Setting Options:: 
* The Packer:: 
* Packer Options:: 
* Coupling Widget Variables:: 
* The Window Manager:: 
* Tk Option Data Types:: 
* Bindings and Events:: 
* The index Parameter:: 
* Images:: 

@end menu

@node Setting Options,The Packer,,Handy Reference
@anchor{library/tkinter setting-options}@anchor{4540}@anchor{library/tkinter tkinter-setting-options}@anchor{4541}
@subsubsection Setting Options


Options control things like the color and border width of a widget. Options can
be set in three ways:


@table @asis

@item At object creation time, using keyword arguments

@example
fred = Button(self, fg="red", bg="blue")
@end example

@item After object creation, treating the option name like a dictionary index

@example
fred["fg"] = "red"
fred["bg"] = "blue"
@end example

@item Use the config() method to update multiple attrs subsequent to object creation

@example
fred.config(fg="red", bg="blue")
@end example
@end table

For a complete explanation of a given option and its behavior, see the Tk man
pages for the widget in question.

Note that the man pages list «STANDARD OPTIONS» and «WIDGET SPECIFIC OPTIONS»
for each widget.  The former is a list of options that are common to many
widgets, the latter are the options that are idiosyncratic to that particular
widget.  The Standard Options are documented on the @code{options(3)@footnote{https://manpages.debian.org/options(3)}} man
page.

No distinction between standard and widget-specific options is made in this
document.  Some options don’t apply to some kinds of widgets. Whether a given
widget responds to a particular option depends on the class of the widget;
buttons have a @code{command} option, labels do not.

The options supported by a given widget are listed in that widget’s man page, or
can be queried at runtime by calling the @code{config()} method without
arguments, or by calling the @code{keys()} method on that widget.  The return
value of these calls is a dictionary whose key is the name of the option as a
string (for example, @code{'relief'}) and whose values are 5-tuples.

Some options, like @code{bg} are synonyms for common options with long names
(@code{bg} is shorthand for «background»). Passing the @code{config()} method the name
of a shorthand option will return a 2-tuple, not 5-tuple. The 2-tuple passed
back will contain the name of the synonym and the «real» option (such as
@code{('bg', 'background')}).


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Meaning

@tab

Example

@item

0

@tab

option name

@tab

@code{'relief'}

@item

1

@tab

option name for database lookup

@tab

@code{'relief'}

@item

2

@tab

option class for database
lookup

@tab

@code{'Relief'}

@item

3

@tab

default value

@tab

@code{'raised'}

@item

4

@tab

current value

@tab

@code{'groove'}

@end multitable


Example:

@example
>>> print(fred.config())
@{'relief': ('relief', 'relief', 'Relief', 'raised', 'groove')@}
@end example

Of course, the dictionary printed will include all the options available and
their values.  This is meant only as an example.

@node The Packer,Packer Options,Setting Options,Handy Reference
@anchor{library/tkinter the-packer}@anchor{4542}
@subsubsection The Packer


@geindex packing (widgets)

The packer is one of Tk’s geometry-management mechanisms.    Geometry managers
are used to specify the relative positioning of widgets within their container.
In contrast to the more cumbersome `placer' (which is
used less commonly, and we do not cover here), the packer takes qualitative
relationship specification - `above', `to the left of', `filling', etc - and
works everything out to determine the exact placement coordinates for you.

The size of any container widget is determined by the size of the «content widgets»
inside.  The packer is used to control where content widgets appear inside the
container into which they are packed.  You can pack widgets into frames, and frames
into other frames, in order to achieve the kind of layout you desire.
Additionally, the arrangement is dynamically adjusted to accommodate incremental
changes to the configuration, once it is packed.

Note that widgets do not appear until they have had their geometry specified
with a geometry manager.  It’s a common early mistake to leave out the geometry
specification, and then be surprised when the widget is created but nothing
appears.  A widget will appear only after it has had, for example, the packer’s
@code{pack()} method applied to it.

The pack() method can be called with keyword-option/value pairs that control
where the widget is to appear within its container, and how it is to behave when
the main application window is resized.  Here are some examples:

@example
fred.pack()                     # defaults to side = "top"
fred.pack(side="left")
fred.pack(expand=1)
@end example

@node Packer Options,Coupling Widget Variables,The Packer,Handy Reference
@anchor{library/tkinter packer-options}@anchor{4543}
@subsubsection Packer Options


For more extensive information on the packer and the options that it can take,
see the man pages and page 183 of John Ousterhout’s book.


@table @asis

@item anchor

Anchor type.  Denotes where the packer is to place each content in its parcel.

@item expand

Boolean, @code{0} or @code{1}.

@item fill

Legal values: @code{'x'}, @code{'y'}, @code{'both'}, @code{'none'}.

@item ipadx and ipady

A distance - designating internal padding on each side of the content.

@item padx and pady

A distance - designating external padding on each side of the content.

@item side

Legal values are: @code{'left'}, @code{'right'}, @code{'top'}, @code{'bottom'}.
@end table

@node Coupling Widget Variables,The Window Manager,Packer Options,Handy Reference
@anchor{library/tkinter coupling-widget-variables}@anchor{4544}
@subsubsection Coupling Widget Variables


The current-value setting of some widgets (like text entry widgets) can be
connected directly to application variables by using special options.  These
options are @code{variable}, @code{textvariable}, @code{onvalue}, @code{offvalue}, and
@code{value}.  This connection works both ways: if the variable changes for any
reason, the widget it’s connected to will be updated to reflect the new value.

Unfortunately, in the current implementation of @code{tkinter} it is not
possible to hand over an arbitrary Python variable to a widget through a
@code{variable} or @code{textvariable} option.  The only kinds of variables for which
this works are variables that are subclassed from a class called Variable,
defined in @code{tkinter}.

There are many useful subclasses of Variable already defined:
@code{StringVar}, @code{IntVar}, @code{DoubleVar}, and
@code{BooleanVar}.  To read the current value of such a variable, call the
@code{get()} method on it, and to change its value you call the @code{set()}
method.  If you follow this protocol, the widget will always track the value of
the variable, with no further intervention on your part.

For example:

@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 The Window Manager,Tk Option Data Types,Coupling Widget Variables,Handy Reference
@anchor{library/tkinter the-window-manager}@anchor{4545}
@subsubsection The Window Manager


@geindex window manager (widgets)

In Tk, there is a utility command, @code{wm}, for interacting with the window
manager.  Options to the @code{wm} command allow you to control things like titles,
placement, icon bitmaps, and the like.  In @code{tkinter}, these commands have
been implemented as methods on the @code{Wm} class.  Toplevel widgets are
subclassed from the @code{Wm} class, and so can call the @code{Wm} methods
directly.

To get at the toplevel window that contains a given widget, you can often just
refer to the widget’s @code{master}.  Of course if the widget has been packed inside of
a frame, the @code{master} won’t represent a toplevel window.  To get at the toplevel
window that contains an arbitrary widget, you can call the @code{_root()} method.
This method begins with an underscore to denote the fact that this function is
part of the implementation, and not an interface to Tk functionality.

Here are some examples of typical usage:

@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 Tk Option Data Types,Bindings and Events,The Window Manager,Handy Reference
@anchor{library/tkinter tk-option-data-types}@anchor{4546}
@subsubsection Tk Option Data Types


@geindex Tk Option Data Types


@table @asis

@item anchor

Legal values are points of the compass: @code{"n"}, @code{"ne"}, @code{"e"}, @code{"se"},
@code{"s"}, @code{"sw"}, @code{"w"}, @code{"nw"}, and also @code{"center"}.

@item bitmap

There are eight built-in, named bitmaps: @code{'error'}, @code{'gray25'},
@code{'gray50'}, @code{'hourglass'}, @code{'info'}, @code{'questhead'}, @code{'question'},
@code{'warning'}.  To specify an X bitmap filename, give the full path to the file,
preceded with an @code{@@}, as in @code{"@@/usr/contrib/bitmap/gumby.bit"}.

@item boolean

You can pass integers 0 or 1 or the strings @code{"yes"} or @code{"no"}.

@item callback

This is any Python function that takes no arguments.  For example:

@example
def print_it():
    print("hi there")
fred["command"] = print_it
@end example

@item color

Colors can be given as the names of X colors in the rgb.txt file, or as strings
representing RGB values in 4 bit: @code{"#RGB"}, 8 bit: @code{"#RRGGBB"}, 12 bit:
@code{"#RRRGGGBBB"}, or 16 bit: @code{"#RRRRGGGGBBBB"} ranges, where R,G,B here
represent any legal hex digit.  See page 160 of Ousterhout’s book for details.

@item cursor

The standard X cursor names from @code{cursorfont.h} can be used, without the
@code{XC_} prefix.  For example to get a hand cursor (@code{XC_hand2}), use the
string @code{"hand2"}.  You can also specify a bitmap and mask file of your own.
See page 179 of Ousterhout’s book.

@item distance

Screen distances can be specified in either pixels or absolute distances.
Pixels are given as numbers and absolute distances as strings, with the trailing
character denoting units: @code{c} for centimetres, @code{i} for inches, @code{m} for
millimetres, @code{p} for printer’s points.  For example, 3.5 inches is expressed
as @code{"3.5i"}.

@item font

Tk uses a list font name format, such as @code{@{courier 10 bold@}}. Font sizes with
positive numbers are measured in points; sizes with negative numbers are
measured in pixels.

@item geometry

This is a string of the form @code{widthxheight}, where width and height are
measured in pixels for most widgets (in characters for widgets displaying text).
For example: @code{fred["geometry"] = "200x100"}.

@item justify

Legal values are the strings: @code{"left"}, @code{"center"}, and @code{"right"}.

@item region

This is a string with four space-delimited elements, each of which is a legal
distance (see above).  For example: @code{"2 3 4 5"} and @code{"3i 2i 4.5i 2i"} and
@code{"3c 2c 4c 10.43c"}  are all legal regions.

@item relief

Determines what the border style of a widget will be.  Legal values are:
@code{"raised"}, @code{"sunken"}, @code{"flat"}, @code{"groove"}, and @code{"ridge"}.

@item scrollcommand

This is almost always the @code{set()} method of some scrollbar widget, but can
be any widget method that takes a single argument.

@item wrap

Must be one of: @code{"none"}, @code{"char"}, or @code{"word"}.
@end table

@node Bindings and Events,The index Parameter,Tk Option Data Types,Handy Reference
@anchor{library/tkinter bindings-and-events}@anchor{4547}@anchor{library/tkinter id2}@anchor{4548}
@subsubsection Bindings and Events


@geindex bind (widgets)
@geindex events (widgets)

The bind method from the widget command allows you to watch for certain events
and to have a callback function trigger when that event type occurs.  The form
of the bind method is:

@example
def bind(self, sequence, func, add='@w{'}):
@end example

where:


@table @asis

@item sequence

is a string that denotes the target kind of event.  (See the
@code{bind(3tk)@footnote{https://manpages.debian.org/bind(3tk)}} man page, and page 201 of John Ousterhout’s book,
@cite{Tcl and the Tk Toolkit (2nd edition)}, for details).

@item func

is a Python function, taking one argument, to be invoked when the event occurs.
An Event instance will be passed as the argument. (Functions deployed this way
are commonly known as `callbacks'.)

@item add

is optional, either @code{'@w{'}} or @code{'+'}.  Passing an empty string denotes that
this binding is to replace any other bindings that this event is associated
with.  Passing a @code{'+'} means that this function is to be added to the list
of functions bound to this event type.
@end table

For example:

@example
def turn_red(self, event):
    event.widget["activeforeground"] = "red"

self.button.bind("<Enter>", self.turn_red)
@end example

Notice how the widget field of the event is being accessed in the
@code{turn_red()} callback.  This field contains the widget that caught the X
event.  The following table lists the other event fields you can access, and how
they are denoted in Tk, which can be useful when referring to the Tk man pages.


@multitable {xxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Tk

@tab

Tkinter Event Field

@tab

Tk

@tab

Tkinter Event Field

@item

%f

@tab

focus

@tab

%A

@tab

char

@item

%h

@tab

height

@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 The index Parameter,Images,Bindings and Events,Handy Reference
@anchor{library/tkinter the-index-parameter}@anchor{4549}
@subsubsection The index Parameter


A number of widgets require «index» parameters to be passed.  These are used to
point at a specific place in a Text widget, or to particular characters in an
Entry widget, or to particular menu items in a Menu widget.


@table @asis

@item Entry widget indexes (index, view index, etc.)

Entry widgets have options that refer to character positions in the text being
displayed.  You can use these @code{tkinter} functions to access these special
points in text widgets:

@item Text widget indexes

The index notation for Text widgets is very rich and is best described in the Tk
man pages.

@item Menu indexes (menu.invoke(), menu.entryconfig(), etc.)

Some options and methods for menus manipulate specific menu entries. Anytime a
menu index is needed for an option or a parameter, you may pass in:


@itemize *

@item 
an integer which refers to the numeric position of the entry in the widget,
counted from the top, starting with 0;

@item 
the string @code{"active"}, which refers to the menu position that is currently
under the cursor;

@item 
the string @code{"last"} which refers to the last menu item;

@item 
An integer preceded by @code{@@}, as in @code{@@6}, where the integer is interpreted
as a y pixel coordinate in the menu’s coordinate system;

@item 
the string @code{"none"}, which indicates no menu entry at all, most often used
with menu.activate() to deactivate all entries, and finally,

@item 
a text string that is pattern matched against the label of the menu entry, as
scanned from the top of the menu to the bottom.  Note that this index type is
considered after all the others, which means that matches for menu items
labelled @code{last}, @code{active}, or @code{none} may be interpreted as the above
literals, instead.
@end itemize
@end table

@node Images,,The index Parameter,Handy Reference
@anchor{library/tkinter images}@anchor{454a}
@subsubsection Images


Images of different formats can be created through the corresponding subclass
of @code{tkinter.Image}:


@itemize *

@item 
@code{BitmapImage} for images in XBM format.

@item 
@code{PhotoImage} for images in PGM, PPM, GIF and PNG formats. The latter
is supported starting with Tk 8.6.
@end itemize

Either type of image is created through either the @code{file} or the @code{data}
option (other options are available as well).


Άλλαξε στην έκδοση 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()}.


The image object can then be used wherever an @code{image} option is supported by
some widget (e.g. labels, buttons, menus). In these cases, Tk will not keep a
reference to the image. When the last Python reference to the image object is
deleted, the image data is deleted as well, and Tk will display an empty box
wherever the image was used.


@subsubheading Δείτε επίσης


The Pillow@footnote{https://python-pillow.org/} package adds support for
formats such as BMP, JPEG, TIFF, and WebP, among others.


@node File Handlers,,Handy Reference,tkinter — Python interface to Tcl/Tk
@anchor{library/tkinter file-handlers}@anchor{454b}@anchor{library/tkinter tkinter-file-handlers}@anchor{454c}
@subsubsection File Handlers


Tk allows you to register and unregister a callback function which will be
called from the Tk mainloop when I/O is possible on a file descriptor.
Only one handler may be registered per file descriptor. Example code:

@example
import tkinter
widget = tkinter.Tk()
mask = tkinter.READABLE | tkinter.WRITABLE
widget.tk.createfilehandler(file, mask, callback)
...
widget.tk.deletefilehandler(file)
@end example

This feature is not available on Windows.

Since you don’t know how many bytes are available for reading, you may not
want to use the @ref{a83,,BufferedIOBase} or @ref{a84,,TextIOBase}
@ref{16cd,,read()} or @ref{16ce,,readline()} methods,
since these will insist on reading a predefined number of bytes.
For sockets, the @ref{115d,,recv()} or
@ref{115e,,recvfrom()} methods will work fine; for other files,
use raw reads or @code{os.read(file.fileno(), maxbytecount)}.

@geindex createfilehandler() (μέθοδος της _tkinter.Widget.tk)
@anchor{library/tkinter tkinter Widget tk createfilehandler}@anchor{454d}
@deffn {Μέθοδος} Widget.tk.createfilehandler (file, mask, func)

Registers the file handler callback function `func'. The `file' argument
may either be an object with a @ref{19b2,,fileno()} method (such as
a file or socket object), or an integer file descriptor. The `mask'
argument is an ORed combination of any of the three constants below.
The callback is called as follows:

@example
callback(file, mask)
@end example
@end deffn

@geindex deletefilehandler() (μέθοδος της _tkinter.Widget.tk)
@anchor{library/tkinter tkinter Widget tk deletefilehandler}@anchor{454e}
@deffn {Μέθοδος} Widget.tk.deletefilehandler (file)

Unregisters a file handler.
@end deffn

@geindex READABLE (στη μονάδα _tkinter)
@geindex WRITABLE (στη μονάδα _tkinter)
@geindex EXCEPTION (στη μονάδα _tkinter)
@anchor{library/tkinter tkinter READABLE}@anchor{454f}
@deffn {Δεδομένα} _tkinter.READABLE
@anchor{library/tkinter tkinter WRITABLE}@anchor{4550}
@deffnx {Δεδομένα} _tkinter.WRITABLE
@anchor{library/tkinter tkinter EXCEPTION}@anchor{4551}
@deffnx {Δεδομένα} _tkinter.EXCEPTION

Constants used in the `mask' arguments.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tkinter colorchooser — Color choosing dialog,tkinter font — Tkinter font wrapper,tkinter — Python interface to Tcl/Tk,Γραφικές επαφές χρηστών με το Tk
@anchor{library/tkinter colorchooser doc}@anchor{4552}@anchor{library/tkinter colorchooser module-tkinter colorchooser}@anchor{fa}@anchor{library/tkinter colorchooser tkinter-colorchooser-color-choosing-dialog}@anchor{4553}@anchor{library/tkinter colorchooser translation-repo}@anchor{4554}
@subsection @code{tkinter.colorchooser} — Color choosing dialog


@geindex module; tkinter.colorchooser

`Source code:' Lib/tkinter/colorchooser.py@footnote{https://github.com/python/cpython/tree/main/Lib/tkinter/colorchooser.py}


__________________________________________________________________


The @code{tkinter.colorchooser} module provides the @ref{4555,,Chooser} class
as an interface to the native color picker dialog. @code{Chooser} implements
a modal color choosing dialog window. The @code{Chooser} class inherits from
the @ref{4556,,Dialog} class.

@geindex Chooser (κλάση σε tkinter.colorchooser)
@anchor{library/tkinter colorchooser tkinter colorchooser Chooser}@anchor{4555}
@deffn {Κλάση} tkinter.colorchooser.Chooser (master=None, **options)
@end deffn

@geindex askcolor() (στη μονάδα tkinter.colorchooser)
@anchor{library/tkinter colorchooser tkinter colorchooser askcolor}@anchor{4557}
@deffn {Συνάρτηση} tkinter.colorchooser.askcolor (color=None, **options)

Create a color choosing dialog. A call to this method will show the window,
wait for the user to make a selection, and return the selected color (or
@code{None}) to the caller.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{fb,,tkinter.commondialog}

Tkinter standard dialog module
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tkinter font — Tkinter font wrapper,Tkinter Dialogs,tkinter colorchooser — Color choosing dialog,Γραφικές επαφές χρηστών με το Tk
@anchor{library/tkinter font doc}@anchor{4558}@anchor{library/tkinter font module-tkinter font}@anchor{fe}@anchor{library/tkinter font tkinter-font-tkinter-font-wrapper}@anchor{4559}@anchor{library/tkinter font translation-repo}@anchor{455a}
@subsection @code{tkinter.font} — Tkinter font wrapper


@geindex module; tkinter.font

`Source code:' Lib/tkinter/font.py@footnote{https://github.com/python/cpython/tree/main/Lib/tkinter/font.py}


__________________________________________________________________


The @code{tkinter.font} module provides the @ref{1ec4,,Font} class for creating
and using named fonts.

The different font weights and slants are:

@geindex NORMAL (στη μονάδα tkinter.font)
@geindex BOLD (στη μονάδα tkinter.font)
@geindex ITALIC (στη μονάδα tkinter.font)
@geindex ROMAN (στη μονάδα tkinter.font)
@anchor{library/tkinter font tkinter font NORMAL}@anchor{455b}
@deffn {Δεδομένα} tkinter.font.NORMAL
@anchor{library/tkinter font tkinter font BOLD}@anchor{455c}
@deffnx {Δεδομένα} tkinter.font.BOLD
@anchor{library/tkinter font tkinter font ITALIC}@anchor{455d}
@deffnx {Δεδομένα} tkinter.font.ITALIC
@anchor{library/tkinter font tkinter font ROMAN}@anchor{455e}
@deffnx {Δεδομένα} tkinter.font.ROMAN
@end deffn

@geindex Font (κλάση σε tkinter.font)
@anchor{library/tkinter font tkinter font Font}@anchor{1ec4}
@deffn {Κλάση} tkinter.font.Font (root=None, font=None, name=None, exists=False, **options)

The @code{Font} class represents a named font. `Font' instances are given
unique names and can be specified by their family, size, and style
configuration. Named fonts are Tk’s method of creating and identifying
fonts as a single object, rather than specifying a font by its attributes
with each occurrence.

@quotation

arguments:

@quotation


@display
`font' - font specifier tuple (family, size, options)@w{ }
`name' - unique font name@w{ }
`exists' - self points to existing named font if true@w{ }
@end display


@end quotation

additional keyword options (ignored if `font' is specified):

@quotation


@display
`family' - font family i.e. Courier, Times@w{ }
`size' - font size@w{ }
@display
If `size' is positive it is interpreted as size in points.@w{ }
If `size' is a negative number its absolute value is treated@w{ }
as size in pixels.@w{ }
@end display
`weight' - font emphasis (NORMAL, BOLD)@w{ }
`slant' - ROMAN, ITALIC@w{ }
`underline' - font underlining (0 - none, 1 - underline)@w{ }
`overstrike' - font strikeout (0 - none, 1 - strikeout)@w{ }
@end display


@end quotation
@end quotation

@geindex actual() (μέθοδος της tkinter.font.Font)
@anchor{library/tkinter font tkinter font Font actual}@anchor{455f}
@deffn {Μέθοδος} actual (option=None, displayof=None)

Return the attributes of the font.
@end deffn

@geindex cget() (μέθοδος της tkinter.font.Font)
@anchor{library/tkinter font tkinter font Font cget}@anchor{4560}
@deffn {Μέθοδος} cget (option)

Retrieve an attribute of the font.
@end deffn

@geindex config() (μέθοδος της tkinter.font.Font)
@anchor{library/tkinter font tkinter font Font config}@anchor{4561}
@deffn {Μέθοδος} config (**options)

Modify attributes of the font.
@end deffn

@geindex copy() (μέθοδος της tkinter.font.Font)
@anchor{library/tkinter font tkinter font Font copy}@anchor{4562}
@deffn {Μέθοδος} copy ()

Return new instance of the current font.
@end deffn

@geindex measure() (μέθοδος της tkinter.font.Font)
@anchor{library/tkinter font tkinter font Font measure}@anchor{4563}
@deffn {Μέθοδος} measure (text, displayof=None)

Return amount of space the text would occupy on the specified display
when formatted in the current font. If no display is specified then the
main application window is assumed.
@end deffn

@geindex metrics() (μέθοδος της tkinter.font.Font)
@anchor{library/tkinter font tkinter font Font metrics}@anchor{4564}
@deffn {Μέθοδος} metrics (*options, **kw)

Return font-specific data.
Options include:


@table @asis

@item `ascent' - distance between baseline and highest point that a

character of the font can occupy

@item `descent' - distance between baseline and lowest point that a

character of the font can occupy

@item `linespace' - minimum vertical separation necessary between any two

characters of the font that ensures no vertical overlap between lines.
@end table

`fixed' - 1 if font is fixed-width else 0
@end deffn
@end deffn

@geindex families() (στη μονάδα tkinter.font)
@anchor{library/tkinter font tkinter font families}@anchor{4565}
@deffn {Συνάρτηση} tkinter.font.families (root=None, displayof=None)

Return the different font families.
@end deffn

@geindex names() (στη μονάδα tkinter.font)
@anchor{library/tkinter font tkinter font names}@anchor{4566}
@deffn {Συνάρτηση} tkinter.font.names (root=None)

Return the names of defined fonts.
@end deffn

@geindex nametofont() (στη μονάδα tkinter.font)
@anchor{library/tkinter font tkinter font nametofont}@anchor{1ec6}
@deffn {Συνάρτηση} tkinter.font.nametofont (name, root=None)

Return a @ref{1ec4,,Font} representation of a tk named font.


Άλλαξε στην έκδοση 3.10: The `root' parameter was added.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Tkinter Dialogs,tkinter messagebox — Tkinter message prompts,tkinter font — Tkinter font wrapper,Γραφικές επαφές χρηστών με το Tk
@anchor{library/dialog doc}@anchor{4567}@anchor{library/dialog tkinter-dialogs}@anchor{4568}@anchor{library/dialog translation-repo}@anchor{4569}
@subsection Tkinter Dialogs


@menu
* tkinter.simpledialog — Standard Tkinter input dialogs: tkinter simpledialog — Standard Tkinter input dialogs. 
* tkinter.filedialog — File selection dialogs: tkinter filedialog — File selection dialogs. 
* tkinter.commondialog — Dialog window templates: tkinter commondialog — Dialog window templates. 

@end menu

@node tkinter simpledialog — Standard Tkinter input dialogs,tkinter filedialog — File selection dialogs,,Tkinter Dialogs
@anchor{library/dialog module-tkinter simpledialog}@anchor{101}@anchor{library/dialog tkinter-simpledialog-standard-tkinter-input-dialogs}@anchor{456a}
@subsubsection @code{tkinter.simpledialog} — Standard Tkinter input dialogs


@geindex module; tkinter.simpledialog

`Source code:' Lib/tkinter/simpledialog.py@footnote{https://github.com/python/cpython/tree/main/Lib/tkinter/simpledialog.py}


__________________________________________________________________


The @code{tkinter.simpledialog} module contains convenience classes and
functions for creating simple modal dialogs to get a value from the user.

@geindex askfloat() (στη μονάδα tkinter.simpledialog)
@geindex askinteger() (στη μονάδα tkinter.simpledialog)
@geindex askstring() (στη μονάδα tkinter.simpledialog)
@anchor{library/dialog tkinter simpledialog askfloat}@anchor{456b}
@deffn {Συνάρτηση} tkinter.simpledialog.askfloat (title, prompt, **kw)
@anchor{library/dialog tkinter simpledialog askinteger}@anchor{1ec7}
@deffnx {Συνάρτηση} tkinter.simpledialog.askinteger (title, prompt, **kw)
@anchor{library/dialog tkinter simpledialog askstring}@anchor{456c}
@deffnx {Συνάρτηση} tkinter.simpledialog.askstring (title, prompt, **kw)

The above three functions provide dialogs that prompt the user to enter a value
of the desired type.
@end deffn

@geindex Dialog (κλάση σε tkinter.simpledialog)
@anchor{library/dialog tkinter simpledialog Dialog}@anchor{456d}
@deffn {Κλάση} tkinter.simpledialog.Dialog (parent, title=None)

The base class for custom dialogs.

@geindex body() (μέθοδος της tkinter.simpledialog.Dialog)
@anchor{library/dialog tkinter simpledialog Dialog body}@anchor{456e}
@deffn {Μέθοδος} body (master)

Override to construct the dialog’s interface and return the widget that
should have initial focus.
@end deffn

@geindex buttonbox() (μέθοδος της tkinter.simpledialog.Dialog)
@anchor{library/dialog tkinter simpledialog Dialog buttonbox}@anchor{456f}
@deffn {Μέθοδος} buttonbox ()

Default behaviour adds OK and Cancel buttons. Override for custom button
layouts.
@end deffn
@end deffn

@node tkinter filedialog — File selection dialogs,tkinter commondialog — Dialog window templates,tkinter simpledialog — Standard Tkinter input dialogs,Tkinter Dialogs
@anchor{library/dialog module-tkinter filedialog}@anchor{fd}@anchor{library/dialog tkinter-filedialog-file-selection-dialogs}@anchor{4570}
@subsubsection @code{tkinter.filedialog} — File selection dialogs


@geindex module; tkinter.filedialog

`Source code:' Lib/tkinter/filedialog.py@footnote{https://github.com/python/cpython/tree/main/Lib/tkinter/filedialog.py}


__________________________________________________________________


The @code{tkinter.filedialog} module provides classes and factory functions for
creating file/directory selection windows.

@menu
* Native Load/Save Dialogs:: 

@end menu

@node Native Load/Save Dialogs,,,tkinter filedialog — File selection dialogs
@anchor{library/dialog native-load-save-dialogs}@anchor{4571}
@subsubsection Native Load/Save Dialogs


The following classes and functions provide file dialog windows that combine a
native look-and-feel with configuration options to customize behaviour.
The following keyword arguments are applicable to the classes and functions
listed below:

@quotation


@display
`parent' - the window to place the dialog on top of@w{ }
@end display




@display
`title' - the title of the window@w{ }
@end display




@display
`initialdir' - the directory that the dialog starts in@w{ }
@end display




@display
`initialfile' - the file selected upon opening of the dialog@w{ }
@end display




@display
`filetypes' - a sequence of (label, pattern) tuples, “*” wildcard is allowed@w{ }
@end display




@display
`defaultextension' - default extension to append to file (save dialogs)@w{ }
@end display




@display
`multiple' - when true, selection of multiple items is allowed@w{ }
@end display


@end quotation

`Static factory functions'

The below functions when called create a modal, native look-and-feel dialog,
wait for the user’s selection, then return the selected value(s) or @code{None} to the
caller.

@geindex askopenfile() (στη μονάδα tkinter.filedialog)
@geindex askopenfiles() (στη μονάδα tkinter.filedialog)
@anchor{library/dialog tkinter filedialog askopenfile}@anchor{4572}
@deffn {Συνάρτηση} tkinter.filedialog.askopenfile (mode='r', **options)
@anchor{library/dialog tkinter filedialog askopenfiles}@anchor{4573}
@deffnx {Συνάρτηση} tkinter.filedialog.askopenfiles (mode='r', **options)

The above two functions create an @ref{4574,,Open} dialog and return the opened
file object(s) in read-only mode.
@end deffn

@geindex asksaveasfile() (στη μονάδα tkinter.filedialog)
@anchor{library/dialog tkinter filedialog asksaveasfile}@anchor{4575}
@deffn {Συνάρτηση} tkinter.filedialog.asksaveasfile (mode='w', **options)

Create a @ref{4576,,SaveAs} dialog and return a file object opened in write-only mode.
@end deffn

@geindex askopenfilename() (στη μονάδα tkinter.filedialog)
@geindex askopenfilenames() (στη μονάδα tkinter.filedialog)
@anchor{library/dialog tkinter filedialog askopenfilename}@anchor{4577}
@deffn {Συνάρτηση} tkinter.filedialog.askopenfilename (**options)
@anchor{library/dialog tkinter filedialog askopenfilenames}@anchor{4578}
@deffnx {Συνάρτηση} tkinter.filedialog.askopenfilenames (**options)

The above two functions create an @ref{4574,,Open} dialog and return the
selected filename(s) that correspond to existing file(s).
@end deffn

@geindex asksaveasfilename() (στη μονάδα tkinter.filedialog)
@anchor{library/dialog tkinter filedialog asksaveasfilename}@anchor{4579}
@deffn {Συνάρτηση} tkinter.filedialog.asksaveasfilename (**options)

Create a @ref{4576,,SaveAs} dialog and return the selected filename.
@end deffn

@geindex askdirectory() (στη μονάδα tkinter.filedialog)
@anchor{library/dialog tkinter filedialog askdirectory}@anchor{457a}
@deffn {Συνάρτηση} tkinter.filedialog.askdirectory (**options)


@display
Prompt user to select a directory.@w{ }
Additional keyword option:@w{ }
@display
`mustexist' - determines if selection must be an existing directory.@w{ }
@end display
@end display


@end deffn

@geindex Open (κλάση σε tkinter.filedialog)
@geindex SaveAs (κλάση σε tkinter.filedialog)
@anchor{library/dialog tkinter filedialog Open}@anchor{4574}
@deffn {Κλάση} tkinter.filedialog.Open (master=None, **options)
@anchor{library/dialog tkinter filedialog SaveAs}@anchor{4576}
@deffnx {Κλάση} tkinter.filedialog.SaveAs (master=None, **options)

The above two classes provide native dialog windows for saving and loading
files.
@end deffn

`Convenience classes'

The below classes are used for creating file/directory windows from scratch.
These do not emulate the native look-and-feel of the platform.

@geindex Directory (κλάση σε tkinter.filedialog)
@anchor{library/dialog tkinter filedialog Directory}@anchor{457b}
@deffn {Κλάση} tkinter.filedialog.Directory (master=None, **options)

Create a dialog prompting the user to select a directory.
@end deffn

@cartouche
@quotation Σημείωση 
The `FileDialog' class should be subclassed for custom event
handling and behaviour.
@end quotation
@end cartouche

@geindex FileDialog (κλάση σε tkinter.filedialog)
@anchor{library/dialog tkinter filedialog FileDialog}@anchor{457c}
@deffn {Κλάση} tkinter.filedialog.FileDialog (master, title=None)

Create a basic file selection dialog.

@geindex cancel_command() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog cancel_command}@anchor{457d}
@deffn {Μέθοδος} cancel_command (event=None)

Trigger the termination of the dialog window.
@end deffn

@geindex dirs_double_event() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog dirs_double_event}@anchor{457e}
@deffn {Μέθοδος} dirs_double_event (event)

Event handler for double-click event on directory.
@end deffn

@geindex dirs_select_event() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog dirs_select_event}@anchor{457f}
@deffn {Μέθοδος} dirs_select_event (event)

Event handler for click event on directory.
@end deffn

@geindex files_double_event() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog files_double_event}@anchor{4580}
@deffn {Μέθοδος} files_double_event (event)

Event handler for double-click event on file.
@end deffn

@geindex files_select_event() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog files_select_event}@anchor{4581}
@deffn {Μέθοδος} files_select_event (event)

Event handler for single-click event on file.
@end deffn

@geindex filter_command() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog filter_command}@anchor{4582}
@deffn {Μέθοδος} filter_command (event=None)

Filter the files by directory.
@end deffn

@geindex get_filter() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog get_filter}@anchor{4583}
@deffn {Μέθοδος} get_filter ()

Retrieve the file filter currently in use.
@end deffn

@geindex get_selection() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog get_selection}@anchor{4584}
@deffn {Μέθοδος} get_selection ()

Retrieve the currently selected item.
@end deffn

@geindex go() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog go}@anchor{4585}
@deffn {Μέθοδος} go (dir_or_file=os.curdir, pattern='*', default='@w{'}, key=None)

Render dialog and start event loop.
@end deffn

@geindex ok_event() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog ok_event}@anchor{4586}
@deffn {Μέθοδος} ok_event (event)

Exit dialog returning current selection.
@end deffn

@geindex quit() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog quit}@anchor{4587}
@deffn {Μέθοδος} quit (how=None)

Exit dialog returning filename, if any.
@end deffn

@geindex set_filter() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog set_filter}@anchor{4588}
@deffn {Μέθοδος} set_filter (dir, pat)

Set the file filter.
@end deffn

@geindex set_selection() (μέθοδος της tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog set_selection}@anchor{4589}
@deffn {Μέθοδος} set_selection (file)

Update the current file selection to `file'.
@end deffn
@end deffn

@geindex LoadFileDialog (κλάση σε tkinter.filedialog)
@anchor{library/dialog tkinter filedialog LoadFileDialog}@anchor{458a}
@deffn {Κλάση} tkinter.filedialog.LoadFileDialog (master, title=None)

A subclass of FileDialog that creates a dialog window for selecting an
existing file.

@geindex ok_command() (μέθοδος της tkinter.filedialog.LoadFileDialog)
@anchor{library/dialog tkinter filedialog LoadFileDialog ok_command}@anchor{458b}
@deffn {Μέθοδος} ok_command ()

Test that a file is provided and that the selection indicates an
already existing file.
@end deffn
@end deffn

@geindex SaveFileDialog (κλάση σε tkinter.filedialog)
@anchor{library/dialog tkinter filedialog SaveFileDialog}@anchor{458c}
@deffn {Κλάση} tkinter.filedialog.SaveFileDialog (master, title=None)

A subclass of FileDialog that creates a dialog window for selecting a
destination file.

@geindex ok_command() (μέθοδος της tkinter.filedialog.SaveFileDialog)
@anchor{library/dialog tkinter filedialog SaveFileDialog ok_command}@anchor{458d}
@deffn {Μέθοδος} ok_command ()

Test whether or not the selection points to a valid file that is not a
directory. Confirmation is required if an already existing file is
selected.
@end deffn
@end deffn

@node tkinter commondialog — Dialog window templates,,tkinter filedialog — File selection dialogs,Tkinter Dialogs
@anchor{library/dialog module-tkinter commondialog}@anchor{fb}@anchor{library/dialog tkinter-commondialog-dialog-window-templates}@anchor{458e}
@subsubsection @code{tkinter.commondialog} — Dialog window templates


@geindex module; tkinter.commondialog

`Source code:' Lib/tkinter/commondialog.py@footnote{https://github.com/python/cpython/tree/main/Lib/tkinter/commondialog.py}


__________________________________________________________________


The @code{tkinter.commondialog} module provides the @ref{4556,,Dialog} class that
is the base class for dialogs defined in other supporting modules.

@geindex Dialog (κλάση σε tkinter.commondialog)
@anchor{library/dialog tkinter commondialog Dialog}@anchor{4556}
@deffn {Κλάση} tkinter.commondialog.Dialog (master=None, **options)

@geindex show() (μέθοδος της tkinter.commondialog.Dialog)
@anchor{library/dialog tkinter commondialog Dialog show}@anchor{458f}
@deffn {Μέθοδος} show (**options)

Render the Dialog window.
@end deffn
@end deffn


@subsubheading Δείτε επίσης


Modules @ref{ff,,tkinter.messagebox}, @ref{2255,,Ανάγνωση και Εγγραφή Αρχείων}


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tkinter messagebox — Tkinter message prompts,tkinter scrolledtext — Scrolled Text Widget,Tkinter Dialogs,Γραφικές επαφές χρηστών με το Tk
@anchor{library/tkinter messagebox doc}@anchor{4590}@anchor{library/tkinter messagebox module-tkinter messagebox}@anchor{ff}@anchor{library/tkinter messagebox tkinter-messagebox-tkinter-message-prompts}@anchor{4591}@anchor{library/tkinter messagebox translation-repo}@anchor{4592}
@subsection @code{tkinter.messagebox} — Tkinter message prompts


@geindex module; tkinter.messagebox

`Source code:' Lib/tkinter/messagebox.py@footnote{https://github.com/python/cpython/tree/main/Lib/tkinter/messagebox.py}


__________________________________________________________________


The @code{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{4593,,OK}, @ref{4594,,CANCEL}, @ref{4595,,YES}, @ref{4596,,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 (κλάση σε tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox Message}@anchor{4597}
@deffn {Κλάση} 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{4598,,symbolic name} of the default button
for this message window (@ref{4593,,OK}, @ref{4594,,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{4599,,icon} to display.
If this option is not specified, then the @ref{459a,,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{459b,,predefined set of buttons}
to be displayed.
@end table
@end quotation

@geindex show() (μέθοδος της tkinter.messagebox.Message)
@anchor{library/tkinter messagebox tkinter messagebox Message show}@anchor{459c}
@deffn {Μέθοδος} 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

`Information message box'

@geindex showinfo() (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox showinfo}@anchor{459d}
@deffn {Συνάρτηση} tkinter.messagebox.showinfo (title=None, message=None, **options)

Creates and displays an information message box with the specified title
and message.
@end deffn

`Warning message boxes'

@geindex showwarning() (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox showwarning}@anchor{459e}
@deffn {Συνάρτηση} 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() (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox showerror}@anchor{459f}
@deffn {Συνάρτηση} tkinter.messagebox.showerror (title=None, message=None, **options)

Creates and displays an error message box with the specified title
and message.
@end deffn

`Question message boxes'

@geindex askquestion() (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox askquestion}@anchor{45a0}
@deffn {Συνάρτηση} tkinter.messagebox.askquestion (title=None, message=None, *, type=YESNO, **options)

Ask a question. By default shows buttons @ref{4595,,YES} and @ref{4596,,NO}.
Returns the symbolic name of the selected button.
@end deffn

@geindex askokcancel() (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox askokcancel}@anchor{45a1}
@deffn {Συνάρτηση} tkinter.messagebox.askokcancel (title=None, message=None, **options)

Ask if operation should proceed. Shows buttons @ref{4593,,OK} and @ref{4594,,CANCEL}.
Returns @code{True} if the answer is ok and @code{False} otherwise.
@end deffn

@geindex askretrycancel() (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox askretrycancel}@anchor{45a2}
@deffn {Συνάρτηση} tkinter.messagebox.askretrycancel (title=None, message=None, **options)

Ask if operation should be retried. Shows buttons @ref{45a3,,RETRY} and @ref{4594,,CANCEL}.
Return @code{True} if the answer is yes and @code{False} otherwise.
@end deffn

@geindex askyesno() (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox askyesno}@anchor{45a4}
@deffn {Συνάρτηση} tkinter.messagebox.askyesno (title=None, message=None, **options)

Ask a question. Shows buttons @ref{4595,,YES} and @ref{4596,,NO}.
Returns @code{True} if the answer is yes and @code{False} otherwise.
@end deffn

@geindex askyesnocancel() (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox askyesnocancel}@anchor{45a5}
@deffn {Συνάρτηση} tkinter.messagebox.askyesnocancel (title=None, message=None, **options)

Ask a question. Shows buttons @ref{4595,,YES}, @ref{4596,,NO} and @ref{4594,,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{4598}
Symbolic names of buttons:

@geindex ABORT (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox ABORT}@anchor{45a6}
@deffn {Δεδομένα} tkinter.messagebox.ABORT = 'abort'
@end deffn

@geindex RETRY (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox RETRY}@anchor{45a3}
@deffn {Δεδομένα} tkinter.messagebox.RETRY = 'retry'
@end deffn

@geindex IGNORE (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox IGNORE}@anchor{45a7}
@deffn {Δεδομένα} tkinter.messagebox.IGNORE = 'ignore'
@end deffn

@geindex OK (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox OK}@anchor{4593}
@deffn {Δεδομένα} tkinter.messagebox.OK = 'ok'
@end deffn

@geindex CANCEL (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox CANCEL}@anchor{4594}
@deffn {Δεδομένα} tkinter.messagebox.CANCEL = 'cancel'
@end deffn

@geindex YES (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox YES}@anchor{4595}
@deffn {Δεδομένα} tkinter.messagebox.YES = 'yes'
@end deffn

@geindex NO (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox NO}@anchor{4596}
@deffn {Δεδομένα} tkinter.messagebox.NO = 'no'
@end deffn
@anchor{library/tkinter messagebox messagebox-types}@anchor{459b}
Predefined sets of buttons:

@geindex ABORTRETRYIGNORE (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox ABORTRETRYIGNORE}@anchor{45a8}
@deffn {Δεδομένα} tkinter.messagebox.ABORTRETRYIGNORE = 'abortretryignore'

Displays three buttons whose symbolic names are @ref{45a6,,ABORT},
@ref{45a3,,RETRY} and @ref{45a7,,IGNORE}.
@end deffn


@deffn {Δεδομένα} tkinter.messagebox.OK = 'ok'

Displays one button whose symbolic name is @ref{4593,,OK}.
@end deffn

@geindex OKCANCEL (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox OKCANCEL}@anchor{45a9}
@deffn {Δεδομένα} tkinter.messagebox.OKCANCEL = 'okcancel'

Displays two buttons whose symbolic names are @ref{4593,,OK} and
@ref{4594,,CANCEL}.
@end deffn

@geindex RETRYCANCEL (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox RETRYCANCEL}@anchor{45aa}
@deffn {Δεδομένα} tkinter.messagebox.RETRYCANCEL = 'retrycancel'

Displays two buttons whose symbolic names are @ref{45a3,,RETRY} and
@ref{4594,,CANCEL}.
@end deffn

@geindex YESNO (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox YESNO}@anchor{45ab}
@deffn {Δεδομένα} tkinter.messagebox.YESNO = 'yesno'

Displays two buttons whose symbolic names are @ref{4595,,YES} and
@ref{4596,,NO}.
@end deffn

@geindex YESNOCANCEL (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox YESNOCANCEL}@anchor{45ac}
@deffn {Δεδομένα} tkinter.messagebox.YESNOCANCEL = 'yesnocancel'

Displays three buttons whose symbolic names are @ref{4595,,YES},
@ref{4596,,NO} and @ref{4594,,CANCEL}.
@end deffn
@anchor{library/tkinter messagebox messagebox-icons}@anchor{4599}
Icon images:

@geindex ERROR (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox ERROR}@anchor{45ad}
@deffn {Δεδομένα} tkinter.messagebox.ERROR = 'error'
@end deffn

@geindex INFO (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox INFO}@anchor{459a}
@deffn {Δεδομένα} tkinter.messagebox.INFO = 'info'
@end deffn

@geindex QUESTION (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox QUESTION}@anchor{45ae}
@deffn {Δεδομένα} tkinter.messagebox.QUESTION = 'question'
@end deffn

@geindex WARNING (στη μονάδα tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox WARNING}@anchor{45af}
@deffn {Δεδομένα} tkinter.messagebox.WARNING = 'warning'
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tkinter scrolledtext — Scrolled Text Widget,tkinter dnd — Drag and drop support,tkinter messagebox — Tkinter message prompts,Γραφικές επαφές χρηστών με το Tk
@anchor{library/tkinter scrolledtext doc}@anchor{45b0}@anchor{library/tkinter scrolledtext module-tkinter scrolledtext}@anchor{100}@anchor{library/tkinter scrolledtext tkinter-scrolledtext-scrolled-text-widget}@anchor{45b1}@anchor{library/tkinter scrolledtext translation-repo}@anchor{45b2}
@subsection @code{tkinter.scrolledtext} — Scrolled Text Widget


@geindex module; tkinter.scrolledtext

`Source code:' Lib/tkinter/scrolledtext.py@footnote{https://github.com/python/cpython/tree/main/Lib/tkinter/scrolledtext.py}


__________________________________________________________________


The @code{tkinter.scrolledtext} module provides a class of the same name which
implements a basic text widget which has a vertical scroll bar configured to do
the «right thing.»  Using the @ref{45b3,,ScrolledText} class is a lot easier than
setting up a text widget and scroll bar directly.

The text widget and scrollbar are packed together in a @code{Frame}, and the
methods of the @code{Grid} and @code{Pack} geometry managers are acquired
from the @code{Frame} object.  This allows the @ref{45b3,,ScrolledText} widget to
be used directly to achieve most normal geometry management behavior.

Should more specific control be necessary, the following attributes are
available:

@geindex ScrolledText (κλάση σε tkinter.scrolledtext)
@anchor{library/tkinter scrolledtext tkinter scrolledtext ScrolledText}@anchor{45b3}
@deffn {Κλάση} tkinter.scrolledtext.ScrolledText (master=None, **kw)

@geindex frame (ιδιότητα της tkinter.scrolledtext.ScrolledText)
@anchor{library/tkinter scrolledtext tkinter scrolledtext ScrolledText frame}@anchor{45b4}
@deffn {Ιδιότητα} frame

The frame which surrounds the text and scroll bar widgets.
@end deffn

@geindex vbar (ιδιότητα της tkinter.scrolledtext.ScrolledText)
@anchor{library/tkinter scrolledtext tkinter scrolledtext ScrolledText vbar}@anchor{45b5}
@deffn {Ιδιότητα} vbar

The scroll bar widget.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tkinter dnd — Drag and drop support,tkinter ttk — Tk themed widgets,tkinter scrolledtext — Scrolled Text Widget,Γραφικές επαφές χρηστών με το Tk
@anchor{library/tkinter dnd doc}@anchor{45b6}@anchor{library/tkinter dnd module-tkinter dnd}@anchor{fc}@anchor{library/tkinter dnd tkinter-dnd-drag-and-drop-support}@anchor{45b7}@anchor{library/tkinter dnd translation-repo}@anchor{45b8}
@subsection @code{tkinter.dnd} — Drag and drop support


@geindex module; tkinter.dnd

`Source code:' Lib/tkinter/dnd.py@footnote{https://github.com/python/cpython/tree/main/Lib/tkinter/dnd.py}


__________________________________________________________________


@cartouche
@quotation Σημείωση 
This is experimental and due to be deprecated when it is replaced
with the Tk DND.
@end quotation
@end cartouche

The @code{tkinter.dnd} module provides drag-and-drop support for objects within
a single application, within the same window or between windows. To enable an
object to be dragged, you must create an event binding for it that starts the
drag-and-drop process. Typically, you bind a ButtonPress event to a callback
function that you write (see @ref{4547,,Bindings and Events}). The function should
call @ref{45b9,,dnd_start()}, where “source” is the object to be dragged, and “event”
is the event that invoked the call (the argument to your callback function).

Selection of a target object occurs as follows:


@enumerate 

@item 
Top-down search of area under mouse for target widget
@end enumerate

@quotation


@itemize *

@item 
Target widget should have a callable `dnd_accept' attribute

@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 
Call to `<old_target>.dnd_leave(source, event)'

@item 
Call to `<new_target>.dnd_enter(source, event)'

@item 
Call to `<target>.dnd_commit(source, event)' to notify of drop

@item 
Call to `<source>.dnd_end(target, event)' to signal end of drag-and-drop
@end enumerate

@geindex DndHandler (κλάση σε tkinter.dnd)
@anchor{library/tkinter dnd tkinter dnd DndHandler}@anchor{45ba}
@deffn {Κλάση} tkinter.dnd.DndHandler (source, event)

The `DndHandler' class handles drag-and-drop events tracking Motion and
ButtonRelease events on the root of the event widget.

@geindex cancel() (μέθοδος της tkinter.dnd.DndHandler)
@anchor{library/tkinter dnd tkinter dnd DndHandler cancel}@anchor{45bb}
@deffn {Μέθοδος} cancel (event=None)

Cancel the drag-and-drop process.
@end deffn

@geindex finish() (μέθοδος της tkinter.dnd.DndHandler)
@anchor{library/tkinter dnd tkinter dnd DndHandler finish}@anchor{45bc}
@deffn {Μέθοδος} finish (event, commit=0)

Execute end of drag-and-drop functions.
@end deffn

@geindex on_motion() (μέθοδος της tkinter.dnd.DndHandler)
@anchor{library/tkinter dnd tkinter dnd DndHandler on_motion}@anchor{45bd}
@deffn {Μέθοδος} on_motion (event)

Inspect area below mouse for target objects while drag is performed.
@end deffn

@geindex on_release() (μέθοδος της tkinter.dnd.DndHandler)
@anchor{library/tkinter dnd tkinter dnd DndHandler on_release}@anchor{45be}
@deffn {Μέθοδος} on_release (event)

Signal end of drag when the release pattern is triggered.
@end deffn
@end deffn

@geindex dnd_start() (στη μονάδα tkinter.dnd)
@anchor{library/tkinter dnd tkinter dnd dnd_start}@anchor{45b9}
@deffn {Συνάρτηση} tkinter.dnd.dnd_start (source, event)

Factory function for drag-and-drop process.
@end deffn


@subsubheading Δείτε επίσης


@ref{4547,,Bindings and Events}


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tkinter ttk — Tk themed widgets,IDLE — Python editor and shell,tkinter dnd — Drag and drop support,Γραφικές επαφές χρηστών με το Tk
@anchor{library/tkinter ttk doc}@anchor{45bf}@anchor{library/tkinter ttk module-tkinter ttk}@anchor{102}@anchor{library/tkinter ttk tkinter-ttk-tk-themed-widgets}@anchor{45c0}@anchor{library/tkinter ttk translation-repo}@anchor{45c1}
@subsection @code{tkinter.ttk} — Tk themed widgets


@geindex module; tkinter.ttk

`Source code:' Lib/tkinter/ttk.py@footnote{https://github.com/python/cpython/tree/main/Lib/tkinter/ttk.py}

@geindex ttk


__________________________________________________________________


The @code{tkinter.ttk} module provides access to the Tk themed widget set,
introduced in Tk 8.5. It provides additional benefits including anti-aliased font
rendering under X11 and window transparency (requiring a composition
window manager on X11).

The basic idea for @code{tkinter.ttk} is to separate, to the extent possible,
the code implementing a widget’s behavior from the code implementing its
appearance.


@subsubheading Δείτε επίσης



@table @asis

@item Tk Widget Styling Support@footnote{https://core.tcl.tk/tips/doc/trunk/tip/48.md}

A document introducing theming support for Tk
@end table


@menu
* Using Ttk:: 
* Ttk Widgets:: 
* Widget:: 
* Combobox:: 
* Spinbox:: 
* Notebook:: 
* Progressbar:: 
* Separator:: 
* Sizegrip:: 
* Treeview:: 
* Ttk Styling:: 

@end menu

@node Using Ttk,Ttk Widgets,,tkinter ttk — Tk themed widgets
@anchor{library/tkinter ttk using-ttk}@anchor{45c2}
@subsubsection Using Ttk


To start using Ttk, import its module:

@example
from tkinter import ttk
@end example

To override the basic Tk widgets, the import should follow the Tk import:

@example
from tkinter import *
from tkinter.ttk import *
@end example

That code causes several @code{tkinter.ttk} widgets (@code{Button},
@code{Checkbutton}, @code{Entry}, @code{Frame}, @code{Label},
@code{LabelFrame}, @code{Menubutton}, @code{PanedWindow},
@code{Radiobutton}, @code{Scale} and @code{Scrollbar}) to
automatically replace the Tk widgets.

This has the direct benefit of using the new widgets which gives a better
look and feel across platforms; however, the replacement widgets are not
completely compatible. The main difference is that widget options such as
«fg», «bg» and others related to widget styling are no
longer present in Ttk widgets.  Instead, use  the @code{ttk.Style} class
for improved styling effects.


@subsubheading Δείτε επίσης



@table @asis

@item Converting existing applications to use Tile widgets@footnote{https://tktable.sourceforge.net/tile/doc/converting.txt}

A monograph (using Tcl terminology) about differences typically
encountered when moving applications to use the new widgets.
@end table


@node Ttk Widgets,Widget,Using Ttk,tkinter ttk — Tk themed widgets
@anchor{library/tkinter ttk ttk-widgets}@anchor{45c3}
@subsubsection Ttk Widgets


Ttk comes with 18 widgets, twelve of which already existed in tkinter:
@code{Button}, @code{Checkbutton}, @code{Entry}, @code{Frame},
@code{Label}, @code{LabelFrame}, @code{Menubutton}, @code{PanedWindow},
@code{Radiobutton}, @code{Scale}, @code{Scrollbar}, and @ref{f53,,Spinbox}.
The other six are new: @ref{45c4,,Combobox}, @ref{45c5,,Notebook},
@ref{45c6,,Progressbar}, @code{Separator}, @code{Sizegrip} and
@ref{e56,,Treeview}. And all them are subclasses of @ref{45c7,,Widget}.

Using the Ttk widgets gives the application an improved look and feel.
As discussed above, there are differences in how the styling is coded.

Tk code:

@example
l1 = tkinter.Label(text="Test", fg="black", bg="white")
l2 = tkinter.Label(text="Test", fg="black", bg="white")
@end example

Ttk code:

@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

For more information about @ref{45c8,,TtkStyling}, see the @ref{761,,Style} class
documentation.

@node Widget,Combobox,Ttk Widgets,tkinter ttk — Tk themed widgets
@anchor{library/tkinter ttk widget}@anchor{45c9}
@subsubsection Widget


@code{ttk.Widget} defines standard options and methods supported by Tk
themed widgets and is not supposed to be directly instantiated.

@menu
* Standard Options:: 
* Scrollable Widget Options:: 
* Label Options:: 
* Compatibility Options:: 
* Widget States:: 
* ttk.Widget: ttk Widget. 

@end menu

@node Standard Options,Scrollable Widget Options,,Widget
@anchor{library/tkinter ttk standard-options}@anchor{45ca}
@subsubsection Standard Options


All the @code{ttk} Widgets accept the following options:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

class

@tab

Specifies the window class. The class is used when querying
the option database for the window’s other options, to
determine the default bindtags for the window, and to select
the widget’s default layout and style. This option is
read-only, and may only be specified when the window is
created.

@item

cursor

@tab

Specifies the mouse cursor to be used for the widget. If set
to the empty string (the default), the cursor is inherited
for the parent widget.

@item

takefocus

@tab

Determines whether the window accepts the focus during
keyboard traversal. 0, 1 or an empty string is returned.
If 0 is returned, it means that the window should be skipped
entirely during keyboard traversal. If 1, it means that the
window should receive the input focus as long as it is
viewable. And an empty string means that the traversal
scripts make the decision about whether or not to focus
on the window.

@item

style

@tab

May be used to specify a custom widget style.

@end multitable


@node Scrollable Widget Options,Label Options,Standard Options,Widget
@anchor{library/tkinter ttk scrollable-widget-options}@anchor{45cb}
@subsubsection Scrollable Widget Options


The following options are supported by widgets that are controlled by a
scrollbar.


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

xscrollcommand

@tab

Used to communicate with horizontal scrollbars.

When the view in the widget’s window change, the widget
will generate a Tcl command based on the scrollcommand.

Usually this option consists of the method
@code{Scrollbar.set()} of some scrollbar. This will cause
the scrollbar to be updated whenever the view in the
window changes.

@item

yscrollcommand

@tab

Used to communicate with vertical scrollbars.
For some more information, see above.

@end multitable


@node Label Options,Compatibility Options,Scrollable Widget Options,Widget
@anchor{library/tkinter ttk label-options}@anchor{45cc}
@subsubsection Label Options


The following options are supported by labels, buttons and other button-like
widgets.


@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

text

@tab

Specifies a text string to be displayed inside the widget.

@item

textvariable

@tab

Specifies a name whose value will be used in place of the
text option resource.

@item

underline

@tab

If set, specifies the index (0-based) of a character to
underline in the text string. The underline character is
used for mnemonic activation.

@item

image

@tab

Specifies an image to display. This is a list of 1 or more
elements. The first element is the default image name. The
rest of the list if a sequence of statespec/value pairs as
defined by @ref{1edb,,Style.map()}, specifying different images
to use when the widget is in a particular state or a
combination of states. All images in the list should have
the same size.

@item

compound

@tab

Specifies how to display the image relative to the text,
in the case both text and images options are present.
Valid values are:


@itemize *

@item 
text: display text only

@item 
image: display image only

@item 
top, bottom, left, right: display image above, below,
left of, or right of the text, respectively.

@item 
none: the default. display the image if present,
otherwise the text.
@end itemize

@item

width

@tab

If greater than zero, specifies how much space, in
character widths, to allocate for the text label, if less
than zero, specifies a minimum width. If zero or
unspecified, the natural width of the text label is used.

@end multitable


@node Compatibility Options,Widget States,Label Options,Widget
@anchor{library/tkinter ttk compatibility-options}@anchor{45cd}
@subsubsection Compatibility Options



@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

state

@tab

May be set to «normal» or «disabled» to control the «disabled»
state bit. This is a write-only option: setting it changes the
widget state, but the @ref{45ce,,Widget.state()} method does not
affect this option.

@end multitable


@node Widget States,ttk Widget,Compatibility Options,Widget
@anchor{library/tkinter ttk widget-states}@anchor{45cf}
@subsubsection Widget States


The widget state is a bitmap of independent state flags.


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Flag

@tab

Description

@item

active

@tab

The mouse cursor is over the widget and pressing a mouse
button will cause some action to occur

@item

disabled

@tab

Widget is disabled under program control

@item

focus

@tab

Widget has keyboard focus

@item

pressed

@tab

Widget is being pressed

@item

selected

@tab

«On», «true», or «current» for things like Checkbuttons and
radiobuttons

@item

background

@tab

Windows and Mac have a notion of an «active» or foreground
window. The `background' state is set for widgets in a
background window, and cleared for those in the foreground
window

@item

readonly

@tab

Widget should not allow user modification

@item

alternate

@tab

A widget-specific alternate display format

@item

invalid

@tab

The widget’s value is invalid

@end multitable


A state specification is a sequence of state names, optionally prefixed with
an exclamation point indicating that the bit is off.

@node ttk Widget,,Widget States,Widget
@anchor{library/tkinter ttk ttk-widget}@anchor{45d0}
@subsubsection ttk.Widget


Besides the methods described below, the @code{ttk.Widget} supports the
methods @code{tkinter.Widget.cget()} and @code{tkinter.Widget.configure()}.

@geindex Widget (κλάση σε tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Widget}@anchor{45c7}
@deffn {Κλάση} tkinter.ttk.Widget

@geindex identify() (μέθοδος της tkinter.ttk.Widget)
@anchor{library/tkinter ttk tkinter ttk Widget identify}@anchor{45d1}
@deffn {Μέθοδος} identify (x, y)

Returns the name of the element at position `x' `y', or the empty string
if the point does not lie within any element.

`x' and `y' are pixel coordinates relative to the widget.
@end deffn

@geindex instate() (μέθοδος της tkinter.ttk.Widget)
@anchor{library/tkinter ttk tkinter ttk Widget instate}@anchor{45d2}
@deffn {Μέθοδος} instate (statespec, callback=None, *args, **kw)

Test the widget’s state. If a callback is not specified, returns @code{True}
if the widget state matches `statespec' and @code{False} otherwise. If callback
is specified then it is called with args if widget state matches
`statespec'.
@end deffn

@geindex state() (μέθοδος της tkinter.ttk.Widget)
@anchor{library/tkinter ttk tkinter ttk Widget state}@anchor{45ce}
@deffn {Μέθοδος} state (statespec=None)

Modify or inquire widget state. If `statespec' is specified, sets the
widget state according to it and return a new `statespec' indicating
which flags were changed. If `statespec' is not specified, returns
the currently enabled state flags.
@end deffn

`statespec' will usually be a list or a tuple.
@end deffn

@node Combobox,Spinbox,Widget,tkinter ttk — Tk themed widgets
@anchor{library/tkinter ttk combobox}@anchor{45d3}
@subsubsection Combobox


The @code{ttk.Combobox} widget combines a text field with a pop-down list of
values. This widget is a subclass of @code{Entry}.

Besides the methods inherited from @ref{45c7,,Widget}: @code{Widget.cget()},
@code{Widget.configure()}, @ref{45d1,,Widget.identify()}, @ref{45d2,,Widget.instate()}
and @ref{45ce,,Widget.state()}, and the following inherited from @code{Entry}:
@code{Entry.bbox()}, @code{Entry.delete()}, @code{Entry.icursor()},
@code{Entry.index()}, @code{Entry.insert()}, @code{Entry.selection()},
@code{Entry.xview()}, it has some other methods, described at
@code{ttk.Combobox}.

@menu
* Options:: 
* Virtual events:: 
* ttk.Combobox: ttk Combobox. 

@end menu

@node Options,Virtual events,,Combobox
@anchor{library/tkinter ttk options}@anchor{45d4}
@subsubsection Options


This widget accepts the following specific options:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

exportselection

@tab

Boolean value. If set, the widget selection is linked
to the Window Manager selection (which can be returned
by invoking Misc.selection_get, for example).

@item

justify

@tab

Specifies how the text is aligned within the widget.
One of «left», «center», or «right».

@item

height

@tab

Specifies the height of the pop-down listbox, in rows.

@item

postcommand

@tab

A script (possibly registered with Misc.register) that
is called immediately before displaying the values. It
may specify which values to display.

@item

state

@tab

One of «normal», «readonly», or «disabled». In the
«readonly» state, the value may not be edited directly,
and the user can only selection of the values from the
dropdown list. In the «normal» state, the text field is
directly editable. In the «disabled» state, no
interaction is possible.

@item

textvariable

@tab

Specifies a name whose value is linked to the widget
value. Whenever the value associated with that name
changes, the widget value is updated, and vice versa.
See @code{tkinter.StringVar}.

@item

values

@tab

Specifies the list of values to display in the
drop-down listbox.

@item

width

@tab

Specifies an integer value indicating the desired width
of the entry window, in average-size characters of the
widget’s font.

@end multitable


@node Virtual events,ttk Combobox,Options,Combobox
@anchor{library/tkinter ttk virtual-events}@anchor{45d5}
@subsubsection Virtual events


The combobox widgets generates a `<<ComboboxSelected>>' virtual event
when the user selects an element from the list of values.

@node ttk Combobox,,Virtual events,Combobox
@anchor{library/tkinter ttk ttk-combobox}@anchor{45d6}
@subsubsection ttk.Combobox


@geindex Combobox (κλάση σε tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Combobox}@anchor{45c4}
@deffn {Κλάση} tkinter.ttk.Combobox

@geindex current() (μέθοδος της tkinter.ttk.Combobox)
@anchor{library/tkinter ttk tkinter ttk Combobox current}@anchor{45d7}
@deffn {Μέθοδος} current (newindex=None)

If `newindex' is specified, sets the combobox value to the element
position `newindex'. Otherwise, returns the index of the current value or
-1 if the current value is not in the values list.
@end deffn

@geindex get() (μέθοδος της tkinter.ttk.Combobox)
@anchor{library/tkinter ttk tkinter ttk Combobox get}@anchor{45d8}
@deffn {Μέθοδος} get ()

Returns the current value of the combobox.
@end deffn

@geindex set() (μέθοδος της tkinter.ttk.Combobox)
@anchor{library/tkinter ttk tkinter ttk Combobox set}@anchor{45d9}
@deffn {Μέθοδος} set (value)

Sets the value of the combobox to `value'.
@end deffn
@end deffn

@node Spinbox,Notebook,Combobox,tkinter ttk — Tk themed widgets
@anchor{library/tkinter ttk spinbox}@anchor{45da}
@subsubsection Spinbox


The @code{ttk.Spinbox} widget is a @code{ttk.Entry} enhanced with increment
and decrement arrows.  It can be used for numbers or lists of string values.
This widget is a subclass of @code{Entry}.

Besides the methods inherited from @ref{45c7,,Widget}: @code{Widget.cget()},
@code{Widget.configure()}, @ref{45d1,,Widget.identify()}, @ref{45d2,,Widget.instate()}
and @ref{45ce,,Widget.state()}, and the following inherited from @code{Entry}:
@code{Entry.bbox()}, @code{Entry.delete()}, @code{Entry.icursor()},
@code{Entry.index()}, @code{Entry.insert()}, @code{Entry.xview()},
it has some other methods, described at @code{ttk.Spinbox}.

@menu
* Options: Options<2>. 
* Virtual events: Virtual events<2>. 
* ttk.Spinbox: ttk Spinbox. 

@end menu

@node Options<2>,Virtual events<2>,,Spinbox
@anchor{library/tkinter ttk id1}@anchor{45db}
@subsubsection Options


This widget accepts the following specific options:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

from

@tab

Float value.  If set, this is the minimum value to
which the decrement button will decrement.  Must be
spelled as @code{from_} when used as an argument, since
@code{from} is a Python keyword.

@item

to

@tab

Float value.  If set, this is the maximum value to
which the increment button will increment.

@item

increment

@tab

Float value.  Specifies the amount which the
increment/decrement buttons change the
value. Defaults to 1.0.

@item

values

@tab

Sequence of string or float values.  If specified,
the increment/decrement buttons will cycle through
the items in this sequence rather than incrementing
or decrementing numbers.

@item

wrap

@tab

Boolean value.  If @code{True}, increment and decrement
buttons will cycle from the @code{to} value to the
@code{from} value or the @code{from} value to the @code{to}
value, respectively.

@item

format

@tab

String value.  This specifies the format of numbers
set by the increment/decrement buttons.  It must be
in the form «%W.Pf», where W is the padded width of
the value, P is the precision, and “%” and “f” are
literal.

@item

command

@tab

Python callable.  Will be called with no arguments
whenever either of the increment or decrement buttons
are pressed.

@end multitable


@node Virtual events<2>,ttk Spinbox,Options<2>,Spinbox
@anchor{library/tkinter ttk id2}@anchor{45dc}
@subsubsection Virtual events


The spinbox widget generates an `<<Increment>>' virtual event when the
user presses <Up>, and a `<<Decrement>>' virtual event when the user
presses <Down>.

@node ttk Spinbox,,Virtual events<2>,Spinbox
@anchor{library/tkinter ttk ttk-spinbox}@anchor{45dd}
@subsubsection ttk.Spinbox


@geindex Spinbox (κλάση σε tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Spinbox}@anchor{f53}
@deffn {Κλάση} tkinter.ttk.Spinbox

@geindex get() (μέθοδος της tkinter.ttk.Spinbox)
@anchor{library/tkinter ttk tkinter ttk Spinbox get}@anchor{45de}
@deffn {Μέθοδος} get ()

Returns the current value of the spinbox.
@end deffn

@geindex set() (μέθοδος της tkinter.ttk.Spinbox)
@anchor{library/tkinter ttk tkinter ttk Spinbox set}@anchor{45df}
@deffn {Μέθοδος} set (value)

Sets the value of the spinbox to `value'.
@end deffn
@end deffn

@node Notebook,Progressbar,Spinbox,tkinter ttk — Tk themed widgets
@anchor{library/tkinter ttk notebook}@anchor{45e0}
@subsubsection Notebook


Ttk Notebook widget manages a collection of windows and displays a single
one at a time. Each child window is associated with a tab, which the user
may select to change the currently displayed window.

@menu
* Options: Options<3>. 
* Tab Options:: 
* Tab Identifiers:: 
* Virtual Events:: 
* ttk.Notebook: ttk Notebook. 

@end menu

@node Options<3>,Tab Options,,Notebook
@anchor{library/tkinter ttk id3}@anchor{45e1}
@subsubsection Options


This widget accepts the following specific options:


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

height

@tab

If present and greater than zero, specifies the desired height
of the pane area (not including internal padding or tabs).
Otherwise, the maximum height of all panes is used.

@item

padding

@tab

Specifies the amount of extra space to add around the outside
of the notebook. The padding is a list up to four length
specifications left top right bottom. If fewer than four
elements are specified, bottom defaults to top, right defaults
to left, and top defaults to left.

@item

width

@tab

If present and greater than zero, specified the desired width
of the pane area (not including internal padding). Otherwise,
the maximum width of all panes is used.

@end multitable


@node Tab Options,Tab Identifiers,Options<3>,Notebook
@anchor{library/tkinter ttk tab-options}@anchor{45e2}
@subsubsection Tab Options


There are also specific options for tabs:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

state

@tab

Either «normal», «disabled» or «hidden». If «disabled», then
the tab is not selectable. If «hidden», then the tab is not
shown.

@item

sticky

@tab

Specifies how the child window is positioned within the pane
area. Value is a string containing zero or more of the
characters «n», «s», «e» or «w». Each letter refers to a
side (north, south, east or west) that the child window will
stick to, as per the @code{grid()} geometry manager.

@item

padding

@tab

Specifies the amount of extra space to add between the
notebook and this pane. Syntax is the same as for the option
padding used by this widget.

@item

text

@tab

Specifies a text to be displayed in the tab.

@item

image

@tab

Specifies an image to display in the tab. See the option
image described in @ref{45c7,,Widget}.

@item

compound

@tab

Specifies how to display the image relative to the text, in
the case both options text and image are present. See
@ref{45cc,,Label Options} for legal values.

@item

underline

@tab

Specifies the index (0-based) of a character to underline in
the text string. The underlined character is used for
mnemonic activation if @ref{45e3,,Notebook.enable_traversal()} is
called.

@end multitable


@node Tab Identifiers,Virtual Events,Tab Options,Notebook
@anchor{library/tkinter ttk tab-identifiers}@anchor{45e4}
@subsubsection Tab Identifiers


The tab_id present in several methods of @code{ttk.Notebook} may take any
of the following forms:


@itemize *

@item 
An integer between zero and the number of tabs

@item 
The name of a child window

@item 
A positional specification of the form «@@x,y», which identifies the tab

@item 
The literal string «current», which identifies the currently selected tab

@item 
The literal string «end», which returns the number of tabs (only valid for
@ref{45e5,,Notebook.index()})
@end itemize

@node Virtual Events,ttk Notebook,Tab Identifiers,Notebook
@anchor{library/tkinter ttk id4}@anchor{45e6}
@subsubsection Virtual Events


This widget generates a `<<NotebookTabChanged>>' virtual event after a new
tab is selected.

@node ttk Notebook,,Virtual Events,Notebook
@anchor{library/tkinter ttk ttk-notebook}@anchor{45e7}
@subsubsection ttk.Notebook


@geindex Notebook (κλάση σε tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Notebook}@anchor{45c5}
@deffn {Κλάση} tkinter.ttk.Notebook

@geindex add() (μέθοδος της tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook add}@anchor{45e8}
@deffn {Μέθοδος} add (child, **kw)

Adds a new tab to the notebook.

If window is currently managed by the notebook but hidden, it is
restored to its previous position.

See @ref{45e2,,Tab Options} for the list of available options.
@end deffn

@geindex forget() (μέθοδος της tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook forget}@anchor{45e9}
@deffn {Μέθοδος} forget (tab_id)

Removes the tab specified by `tab_id', unmaps and unmanages the
associated window.
@end deffn

@geindex hide() (μέθοδος της tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook hide}@anchor{45ea}
@deffn {Μέθοδος} hide (tab_id)

Hides the tab specified by `tab_id'.

The tab will not be displayed, but the associated window remains
managed by the notebook and its configuration remembered. Hidden tabs
may be restored with the @ref{45e8,,add()} command.
@end deffn

@geindex identify() (μέθοδος της tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook identify}@anchor{45eb}
@deffn {Μέθοδος} identify (x, y)

Returns the name of the tab element at position `x', `y', or the empty
string if none.
@end deffn

@geindex index() (μέθοδος της tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook index}@anchor{45e5}
@deffn {Μέθοδος} index (tab_id)

Returns the numeric index of the tab specified by `tab_id', or the total
number of tabs if `tab_id' is the string «end».
@end deffn

@geindex insert() (μέθοδος της tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook insert}@anchor{45ec}
@deffn {Μέθοδος} insert (pos, child, **kw)

Inserts a pane at the specified position.

`pos' is either the string «end», an integer index, or the name of a
managed child. If `child' is already managed by the notebook, moves it to
the specified position.

See @ref{45e2,,Tab Options} for the list of available options.
@end deffn

@geindex select() (μέθοδος της tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook select}@anchor{45ed}
@deffn {Μέθοδος} select (tab_id=None)

Selects the specified `tab_id'.

The associated child window will be displayed, and the
previously selected window (if different) is unmapped. If `tab_id' is
omitted, returns the widget name of the currently selected pane.
@end deffn

@geindex tab() (μέθοδος της tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook tab}@anchor{45ee}
@deffn {Μέθοδος} tab (tab_id, option=None, **kw)

Query or modify the options of the specific `tab_id'.

If `kw' is not given, returns a dictionary of the tab option values. If
`option' is specified, returns the value of that `option'. Otherwise,
sets the options to the corresponding values.
@end deffn

@geindex tabs() (μέθοδος της tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook tabs}@anchor{45ef}
@deffn {Μέθοδος} tabs ()

Returns a list of windows managed by the notebook.
@end deffn

@geindex enable_traversal() (μέθοδος της tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook enable_traversal}@anchor{45e3}
@deffn {Μέθοδος} enable_traversal ()

Enable keyboard traversal for a toplevel window containing this notebook.

This will extend the bindings for the toplevel window containing the
notebook as follows:


@itemize *

@item 
@code{Control}-@code{Tab}: selects the tab following the currently selected one.

@item 
@code{Shift}-@code{Control}-@code{Tab}: selects the tab preceding the currently selected one.

@item 
@code{Alt}-@code{K}: where `K' is the mnemonic (underlined) character of any tab, will
select that tab.
@end itemize

Multiple notebooks in a single toplevel may be enabled for traversal,
including nested notebooks. However, notebook traversal only works
properly if all panes have the notebook they are in as master.
@end deffn
@end deffn

@node Progressbar,Separator,Notebook,tkinter ttk — Tk themed widgets
@anchor{library/tkinter ttk progressbar}@anchor{45f0}
@subsubsection Progressbar


The @code{ttk.Progressbar} widget shows the status of a long-running
operation. It can operate in two modes:  1) the determinate mode which shows the
amount completed relative to the total amount of work to be done and 2) the
indeterminate mode which provides an animated display to let the user know that
work is progressing.

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

@end menu

@node Options<4>,ttk Progressbar,,Progressbar
@anchor{library/tkinter ttk id5}@anchor{45f1}
@subsubsection Options


This widget accepts the following specific options:


@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

orient

@tab

One of «horizontal» or «vertical». Specifies the orientation
of the progress bar.

@item

length

@tab

Specifies the length of the long axis of the progress bar
(width if horizontal, height if vertical).

@item

mode

@tab

One of «determinate» or «indeterminate».

@item

maximum

@tab

A number specifying the maximum value. Defaults to 100.

@item

value

@tab

The current value of the progress bar. In «determinate» mode,
this represents the amount of work completed. In
«indeterminate» mode, it is interpreted as modulo `maximum';
that is, the progress bar completes one «cycle» when its value
increases by `maximum'.

@item

variable

@tab

A name which is linked to the option value. If specified, the
value of the progress bar is automatically set to the value of
this name whenever the latter is modified.

@item

phase

@tab

Read-only option. The widget periodically increments the value
of this option whenever its value is greater than 0 and, in
determinate mode, less than maximum. This option may be used
by the current theme to provide additional animation effects.

@end multitable


@node ttk Progressbar,,Options<4>,Progressbar
@anchor{library/tkinter ttk ttk-progressbar}@anchor{45f2}
@subsubsection ttk.Progressbar


@geindex Progressbar (κλάση σε tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Progressbar}@anchor{45c6}
@deffn {Κλάση} tkinter.ttk.Progressbar

@geindex start() (μέθοδος της tkinter.ttk.Progressbar)
@anchor{library/tkinter ttk tkinter ttk Progressbar start}@anchor{45f3}
@deffn {Μέθοδος} start (interval=None)

Begin autoincrement mode: schedules a recurring timer event that calls
@ref{45f4,,Progressbar.step()} every `interval' milliseconds. If omitted,
`interval' defaults to 50 milliseconds.
@end deffn

@geindex step() (μέθοδος της tkinter.ttk.Progressbar)
@anchor{library/tkinter ttk tkinter ttk Progressbar step}@anchor{45f4}
@deffn {Μέθοδος} step (amount=None)

Increments the progress bar’s value by `amount'.

`amount' defaults to 1.0 if omitted.
@end deffn

@geindex stop() (μέθοδος της tkinter.ttk.Progressbar)
@anchor{library/tkinter ttk tkinter ttk Progressbar stop}@anchor{45f5}
@deffn {Μέθοδος} stop ()

Stop autoincrement mode: cancels any recurring timer event initiated by
@ref{45f3,,Progressbar.start()} for this progress bar.
@end deffn
@end deffn

@node Separator,Sizegrip,Progressbar,tkinter ttk — Tk themed widgets
@anchor{library/tkinter ttk separator}@anchor{45f6}
@subsubsection Separator


The @code{ttk.Separator} widget displays a horizontal or vertical separator
bar.

It has no other methods besides the ones inherited from @code{ttk.Widget}.

@menu
* Options: Options<5>. 

@end menu

@node Options<5>,,,Separator
@anchor{library/tkinter ttk id6}@anchor{45f7}
@subsubsection Options


This widget accepts the following specific option:


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

orient

@tab

One of «horizontal» or «vertical». Specifies the orientation of
the separator.

@end multitable


@node Sizegrip,Treeview,Separator,tkinter ttk — Tk themed widgets
@anchor{library/tkinter ttk sizegrip}@anchor{45f8}
@subsubsection Sizegrip


The @code{ttk.Sizegrip} widget (also known as a grow box) allows the user to
resize the containing toplevel window by pressing and dragging the grip.

This widget has neither specific options nor specific methods, besides the
ones inherited from @code{ttk.Widget}.

@menu
* Platform-specific notes:: 
* Bugs:: 

@end menu

@node Platform-specific notes,Bugs,,Sizegrip
@anchor{library/tkinter ttk platform-specific-notes}@anchor{45f9}
@subsubsection Platform-specific notes



@itemize *

@item 
On macOS, toplevel windows automatically include a built-in size grip
by default. Adding a @code{Sizegrip} is harmless, since the built-in
grip will just mask the widget.
@end itemize

@node Bugs,,Platform-specific notes,Sizegrip
@anchor{library/tkinter ttk bugs}@anchor{45fa}
@subsubsection Bugs



@itemize *

@item 
If the containing toplevel’s position was specified relative to the right
or bottom of the screen (e.g. ….), the @code{Sizegrip} widget will
not resize the window.

@item 
This widget supports only «southeast» resizing.
@end itemize

@node Treeview,Ttk Styling,Sizegrip,tkinter ttk — Tk themed widgets
@anchor{library/tkinter ttk treeview}@anchor{45fb}
@subsubsection Treeview


The @code{ttk.Treeview} widget displays a hierarchical collection of items.
Each item has a textual label, an optional image, and an optional list of data
values. The data values are displayed in successive columns after the tree
label.

The order in which data values are displayed may be controlled by setting
the widget option @code{displaycolumns}. The tree widget can also display column
headings. Columns may be accessed by number or symbolic names listed in the
widget option columns. See @ref{45fc,,Column Identifiers}.

Each item is identified by a unique name. The widget will generate item IDs
if they are not supplied by the caller. There is a distinguished root item,
named @code{@{@}}. The root item itself is not displayed; its children appear at the
top level of the hierarchy.

Each item also has a list of tags, which can be used to associate event bindings
with individual items and control the appearance of the item.

The Treeview widget supports horizontal and vertical scrolling, according to
the options described in @ref{45cb,,Scrollable Widget Options} and the methods
@ref{45fd,,Treeview.xview()} and @ref{45fe,,Treeview.yview()}.

@menu
* Options: Options<6>. 
* Item Options:: 
* Tag Options:: 
* Column Identifiers:: 
* Virtual Events: Virtual Events<2>. 
* ttk.Treeview: ttk Treeview. 

@end menu

@node Options<6>,Item Options,,Treeview
@anchor{library/tkinter ttk id7}@anchor{45ff}
@subsubsection Options


This widget accepts the following specific options:


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

columns

@tab

A list of column identifiers, specifying the number of
columns and their names.

@item

displaycolumns

@tab

A list of column identifiers (either symbolic or
integer indices) specifying which data columns are
displayed and the order in which they appear, or the
string «#all».

@item

height

@tab

Specifies the number of rows which should be visible.
Note: the requested width is determined from the sum
of the column widths.

@item

padding

@tab

Specifies the internal padding for the widget. The
padding is a list of up to four length specifications.

@item

selectmode

@tab

Controls how the built-in class bindings manage the
selection. One of «extended», «browse» or «none».
If set to «extended» (the default), multiple items may
be selected. If «browse», only a single item will be
selected at a time. If «none», the selection will not
be changed.

Note that the application code and tag bindings can set
the selection however they wish, regardless of the
value  of this option.

@item

show

@tab

A list containing zero or more of the following values,
specifying which elements of the tree to display.


@itemize *

@item 
tree: display tree labels in column #0.

@item 
headings: display the heading row.
@end itemize

The default is «tree headings», i.e., show all
elements.

`Note': Column #0 always refers to the tree column,
even if show=»tree» is not specified.

@end multitable


@node Item Options,Tag Options,Options<6>,Treeview
@anchor{library/tkinter ttk item-options}@anchor{4600}
@subsubsection Item Options


The following item options may be specified for items in the insert and item
widget commands.


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

text

@tab

The textual label to display for the item.

@item

image

@tab

A Tk Image, displayed to the left of the label.

@item

values

@tab

The list of values associated with the item.

Each item should have the same number of values as the widget
option columns. If there are fewer values than columns, the
remaining values are assumed empty. If there are more values
than columns, the extra values are ignored.

@item

open

@tab

@code{True}/@code{False} value indicating whether the item’s
children should be displayed or hidden.

@item

tags

@tab

A list of tags associated with this item.

@end multitable


@node Tag Options,Column Identifiers,Item Options,Treeview
@anchor{library/tkinter ttk tag-options}@anchor{4601}
@subsubsection Tag Options


The following options may be specified on tags:


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

foreground

@tab

Specifies the text foreground color.

@item

background

@tab

Specifies the cell or item background color.

@item

font

@tab

Specifies the font to use when drawing text.

@item

image

@tab

Specifies the item image, in case the item’s image option
is empty.

@end multitable


@node Column Identifiers,Virtual Events<2>,Tag Options,Treeview
@anchor{library/tkinter ttk column-identifiers}@anchor{45fc}
@subsubsection Column Identifiers


Column identifiers take any of the following forms:


@itemize *

@item 
A symbolic name from the list of columns option.

@item 
An integer n, specifying the nth data column.

@item 
A string of the form #n, where n is an integer, specifying the nth display
column.
@end itemize

Notes:


@itemize *

@item 
Item’s option values may be displayed in a different order than the order
in which they are stored.

@item 
Column #0 always refers to the tree column, even if show=»tree» is not
specified.
@end itemize

A data column number is an index into an item’s option values list; a display
column number is the column number in the tree where the values are displayed.
Tree labels are displayed in column #0. If option displaycolumns is not set,
then data column n is displayed in column #n+1. Again, `column #0 always
refers to the tree column'.

@node Virtual Events<2>,ttk Treeview,Column Identifiers,Treeview
@anchor{library/tkinter ttk id8}@anchor{4602}
@subsubsection Virtual Events


The Treeview widget generates the following virtual events.


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Event

@tab

Description

@item

<<TreeviewSelect>>

@tab

Generated whenever the selection changes.

@item

<<TreeviewOpen>>

@tab

Generated just before settings the focus item to
open=True.

@item

<<TreeviewClose>>

@tab

Generated just after setting the focus item to
open=False.

@end multitable


The @ref{4603,,Treeview.focus()} and @ref{e55,,Treeview.selection()} methods can be used
to determine the affected item or items.

@node ttk Treeview,,Virtual Events<2>,Treeview
@anchor{library/tkinter ttk ttk-treeview}@anchor{4604}
@subsubsection ttk.Treeview


@geindex Treeview (κλάση σε tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Treeview}@anchor{e56}
@deffn {Κλάση} tkinter.ttk.Treeview

@geindex bbox() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview bbox}@anchor{4605}
@deffn {Μέθοδος} bbox (item, column=None)

Returns the bounding box (relative to the treeview widget’s window) of
the specified `item' in the form (x, y, width, height).

If `column' is specified, returns the bounding box of that cell. If the
`item' is not visible (i.e., if it is a descendant of a closed item or is
scrolled offscreen), returns an empty string.
@end deffn

@geindex get_children() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview get_children}@anchor{4606}
@deffn {Μέθοδος} get_children (item=None)

Returns the list of children belonging to `item'.

If `item' is not specified, returns root children.
@end deffn

@geindex set_children() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview set_children}@anchor{4607}
@deffn {Μέθοδος} set_children (item, *newchildren)

Replaces `item'’s child with `newchildren'.

Children present in `item' that are not present in `newchildren' are
detached from the tree. No items in `newchildren' may be an ancestor of
`item'. Note that not specifying `newchildren' results in detaching
`item'’s children.
@end deffn

@geindex column() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview column}@anchor{4608}
@deffn {Μέθοδος} column (column, option=None, **kw)

Query or modify the options for the specified `column'.

If `kw' is not given, returns a dict of the column option values. If
`option' is specified then the value for that `option' is returned.
Otherwise, sets the options to the corresponding values.

The valid options/values are:


@table @asis

@item `id'

Returns the column name. This is a read-only option.

@item `anchor': One of the standard Tk anchor values.

Specifies how the text in this column should be aligned with respect
to the cell.

@item `minwidth': width

The minimum width of the column in pixels. The treeview widget will
not make the column any smaller than specified by this option when
the widget is resized or the user drags a column.

@item `stretch': @code{True}/@code{False}

Specifies whether the column’s width should be adjusted when
the widget is resized.

@item `width': width

The width of the column in pixels.
@end table

To configure the tree column, call this with column = «#0»
@end deffn

@geindex delete() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview delete}@anchor{4609}
@deffn {Μέθοδος} delete (*items)

Delete all specified `items' and all their descendants.

The root item may not be deleted.
@end deffn

@geindex detach() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview detach}@anchor{460a}
@deffn {Μέθοδος} detach (*items)

Unlinks all of the specified `items' from the tree.

The items and all of their descendants are still present, and may be
reinserted at another point in the tree, but will not be displayed.

The root item may not be detached.
@end deffn

@geindex exists() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview exists}@anchor{460b}
@deffn {Μέθοδος} exists (item)

Returns @code{True} if the specified `item' is present in the tree.
@end deffn

@geindex focus() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview focus}@anchor{4603}
@deffn {Μέθοδος} focus (item=None)

If `item' is specified, sets the focus item to `item'. Otherwise, returns
the current focus item, or “” if there is none.
@end deffn

@geindex heading() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview heading}@anchor{460c}
@deffn {Μέθοδος} heading (column, option=None, **kw)

Query or modify the heading options for the specified `column'.

If `kw' is not given, returns a dict of the heading option values. If
`option' is specified then the value for that `option' is returned.
Otherwise, sets the options to the corresponding values.

The valid options/values are:


@table @asis

@item `text': text

The text to display in the column heading.

@item `image': imageName

Specifies an image to display to the right of the column heading.

@item `anchor': anchor

Specifies how the heading text should be aligned. One of the standard
Tk anchor values.

@item `command': callback

A callback to be invoked when the heading label is pressed.
@end table

To configure the tree column heading, call this with column = «#0».
@end deffn

@geindex identify() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview identify}@anchor{460d}
@deffn {Μέθοδος} identify (component, x, y)

Returns a description of the specified `component' under the point given
by `x' and `y', or the empty string if no such `component' is present at
that position.
@end deffn

@geindex identify_row() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview identify_row}@anchor{460e}
@deffn {Μέθοδος} identify_row (y)

Returns the item ID of the item at position `y'.
@end deffn

@geindex identify_column() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview identify_column}@anchor{460f}
@deffn {Μέθοδος} identify_column (x)

Returns the data column identifier of the cell at position `x'.

The tree column has ID #0.
@end deffn

@geindex identify_region() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview identify_region}@anchor{4610}
@deffn {Μέθοδος} identify_region (x, y)

Returns one of:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

region

@tab

meaning

@item

heading

@tab

Tree heading area.

@item

separator

@tab

Space between two columns headings.

@item

tree

@tab

The tree area.

@item

cell

@tab

A data cell.

@end multitable


Availability: Tk 8.6.
@end deffn

@geindex identify_element() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview identify_element}@anchor{4611}
@deffn {Μέθοδος} identify_element (x, y)

Returns the element at position `x', `y'.

Availability: Tk 8.6.
@end deffn

@geindex index() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview index}@anchor{4612}
@deffn {Μέθοδος} index (item)

Returns the integer index of `item' within its parent’s list of children.
@end deffn

@geindex insert() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview insert}@anchor{4613}
@deffn {Μέθοδος} insert (parent, index, iid=None, **kw)

Creates a new item and returns the item identifier of the newly created
item.

`parent' is the item ID of the parent item, or the empty string to create
a new top-level item. `index' is an integer, or the value «end»,
specifying where in the list of parent’s children to insert the new item.
If `index' is less than or equal to zero, the new node is inserted at
the beginning; if `index' is greater than or equal to the current number
of children, it is inserted at the end. If `iid' is specified, it is used
as the item identifier; `iid' must not already exist in the tree.
Otherwise, a new unique identifier is generated.

See @ref{4600,,Item Options} for the list of available options.
@end deffn

@geindex item() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview item}@anchor{4614}
@deffn {Μέθοδος} item (item, option=None, **kw)

Query or modify the options for the specified `item'.

If no options are given, a dict with options/values for the item is
returned.
If `option' is specified then the value for that option is returned.
Otherwise, sets the options to the corresponding values as given by `kw'.
@end deffn

@geindex move() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview move}@anchor{4615}
@deffn {Μέθοδος} move (item, parent, index)

Moves `item' to position `index' in `parent'’s list of children.

It is illegal to move an item under one of its descendants. If `index' is
less than or equal to zero, `item' is moved to the beginning; if greater
than or equal to the number of children, it is moved to the end. If `item'
was detached it is reattached.
@end deffn

@geindex next() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview next}@anchor{4616}
@deffn {Μέθοδος} next (item)

Returns the identifier of `item'’s next sibling, or “” if `item' is the
last child of its parent.
@end deffn

@geindex parent() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview parent}@anchor{4617}
@deffn {Μέθοδος} parent (item)

Returns the ID of the parent of `item', or “” if `item' is at the top
level of the hierarchy.
@end deffn

@geindex prev() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview prev}@anchor{4618}
@deffn {Μέθοδος} prev (item)

Returns the identifier of `item'’s previous sibling, or “” if `item' is
the first child of its parent.
@end deffn

@geindex reattach() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview reattach}@anchor{4619}
@deffn {Μέθοδος} reattach (item, parent, index)

An alias for @ref{4615,,Treeview.move()}.
@end deffn

@geindex see() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview see}@anchor{461a}
@deffn {Μέθοδος} see (item)

Ensure that `item' is visible.

Sets all of `item'’s ancestors open option to @code{True}, and scrolls the
widget if necessary so that `item' is within the visible portion of
the tree.
@end deffn

@geindex selection() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview selection}@anchor{e55}
@deffn {Μέθοδος} selection ()

Returns a tuple of selected items.


Άλλαξε στην έκδοση 3.8: @code{selection()} no longer takes arguments.  For changing the selection
state use the following selection methods.

@end deffn

@geindex selection_set() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview selection_set}@anchor{e57}
@deffn {Μέθοδος} selection_set (*items)

`items' becomes the new selection.


Άλλαξε στην έκδοση 3.6: `items' can be passed as separate arguments, not just as a single tuple.

@end deffn

@geindex selection_add() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview selection_add}@anchor{461b}
@deffn {Μέθοδος} selection_add (*items)

Add `items' to the selection.


Άλλαξε στην έκδοση 3.6: `items' can be passed as separate arguments, not just as a single tuple.

@end deffn

@geindex selection_remove() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview selection_remove}@anchor{461c}
@deffn {Μέθοδος} selection_remove (*items)

Remove `items' from the selection.


Άλλαξε στην έκδοση 3.6: `items' can be passed as separate arguments, not just as a single tuple.

@end deffn

@geindex selection_toggle() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview selection_toggle}@anchor{461d}
@deffn {Μέθοδος} selection_toggle (*items)

Toggle the selection state of each item in `items'.


Άλλαξε στην έκδοση 3.6: `items' can be passed as separate arguments, not just as a single tuple.

@end deffn

@geindex set() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview set}@anchor{461e}
@deffn {Μέθοδος} set (item, column=None, value=None)

With one argument, returns a dictionary of column/value pairs for the
specified `item'. With two arguments, returns the current value of the
specified `column'. With three arguments, sets the value of given
`column' in given `item' to the specified `value'.
@end deffn

@geindex tag_bind() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview tag_bind}@anchor{461f}
@deffn {Μέθοδος} tag_bind (tagname, sequence=None, callback=None)

Bind a callback for the given event `sequence' to the tag `tagname'.
When an event is delivered to an item, the callbacks for each of the
item’s tags option are called.
@end deffn

@geindex tag_configure() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview tag_configure}@anchor{4620}
@deffn {Μέθοδος} tag_configure (tagname, option=None, **kw)

Query or modify the options for the specified `tagname'.

If `kw' is not given, returns a dict of the option settings for
`tagname'. If `option' is specified, returns the value for that `option'
for the specified `tagname'. Otherwise, sets the options to the
corresponding values for the given `tagname'.
@end deffn

@geindex tag_has() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview tag_has}@anchor{4621}
@deffn {Μέθοδος} tag_has (tagname, item=None)

If `item' is specified, returns 1 or 0 depending on whether the specified
`item' has the given `tagname'. Otherwise, returns a list of all items
that have the specified tag.

Availability: Tk 8.6
@end deffn

@geindex xview() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview xview}@anchor{45fd}
@deffn {Μέθοδος} xview (*args)

Query or modify horizontal position of the treeview.
@end deffn

@geindex yview() (μέθοδος της tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview yview}@anchor{45fe}
@deffn {Μέθοδος} yview (*args)

Query or modify vertical position of the treeview.
@end deffn
@end deffn

@node Ttk Styling,,Treeview,tkinter ttk — Tk themed widgets
@anchor{library/tkinter ttk ttk-styling}@anchor{4622}@anchor{library/tkinter ttk ttkstyling}@anchor{45c8}
@subsubsection Ttk Styling


Each widget in @code{ttk} is assigned a style, which specifies the set of
elements making up the widget and how they are arranged, along with dynamic
and default settings for element options. By default the style name is the
same as the widget’s class name, but it may be overridden by the widget’s style
option. If you don’t know the class name of a widget, use the method
@code{Misc.winfo_class()} (somewidget.winfo_class()).


@subsubheading Δείτε επίσης



@table @asis

@item Tcl'2004 conference presentation@footnote{https://tktable.sourceforge.net/tile/tile-tcl2004.pdf}

This document explains how the theme engine works
@end table


@geindex Style (κλάση σε tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Style}@anchor{761}
@deffn {Κλάση} tkinter.ttk.Style

This class is used to manipulate the style database.

@geindex configure() (μέθοδος της tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style configure}@anchor{4623}
@deffn {Μέθοδος} configure (style, query_opt=None, **kw)

Query or set the default value of the specified option(s) in `style'.

Each key in `kw' is an option and each value is a string identifying
the value for that option.

For example, to change every default button to be a flat button with
some padding and a different background color:

@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() (μέθοδος της tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style map}@anchor{1edb}
@deffn {Μέθοδος} map (style, query_opt=None, **kw)

Query or sets dynamic values of the specified option(s) in `style'.

Each key in `kw' is an option and each value should be a list or a
tuple (usually) containing statespecs grouped in tuples, lists, or
some other preference. A statespec is a compound of one
or more states and then a value.

An example may make it more understandable:

@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

Note that the order of the (states, value) sequences for an option does
matter, if the order is changed to @code{[('active', 'blue'), ('pressed',
'red')]} in the foreground option, for example, the result would be a
blue foreground when the widget were in active or pressed states.
@end deffn

@geindex lookup() (μέθοδος της tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style lookup}@anchor{4624}
@deffn {Μέθοδος} lookup (style, option, state=None, default=None)

Returns the value specified for `option' in `style'.

If `state' is specified, it is expected to be a sequence of one or more
states. If the `default' argument is set, it is used as a fallback value
in case no specification for option is found.

To check what font a Button uses by default:

@example
from tkinter import ttk

print(ttk.Style().lookup("TButton", "font"))
@end example
@end deffn

@geindex layout() (μέθοδος της tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style layout}@anchor{4625}
@deffn {Μέθοδος} layout (style, layoutspec=None)

Define the widget layout for given `style'. If `layoutspec' is omitted,
return the layout specification for given style.

`layoutspec', if specified, is expected to be a list or some other
sequence type (excluding strings), where each item should be a tuple and
the first item is the layout name and the second item should have the
format described in @ref{4626,,Layouts}.

To understand the format, see the following example (it is not
intended to do anything useful):

@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() (μέθοδος της tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style element_create}@anchor{760}
@deffn {Μέθοδος} 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.

If «image» is used, `args' should contain the default image name followed
by statespec/value pairs (this is the imagespec), and `kw' may have the
following options:


@table @asis

@item border=padding

padding is a list of up to four integers, specifying the left, top,
right, and bottom borders, respectively.

@item height=height

Specifies a minimum height for the element. If less than zero, the
base image’s height is used as a default.

@item padding=padding

Specifies the element’s interior padding. Defaults to border’s value
if not specified.

@item sticky=spec

Specifies how the image is placed within the final parcel. spec
contains zero or more characters «n», «s», «w», or «e».

@item width=width

Specifies a minimum width for the element. If less than zero, the
base image’s width is used as a default.
@end table

Example:

@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

If «from» is used as the value of `etype',
@code{element_create()} will clone an existing
element. `args' is expected to contain a themename, from which
the element will be cloned, and optionally an element to clone from.
If this element to clone from is not specified, an empty element will
be used. `kw' is discarded.

Example:

@example
style = ttk.Style(root)
style.element_create('plain.background', 'from', 'default')
@end example

If «vsapi» is used as the value of `etype', @code{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=padding

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=width

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=height

Specifies the height of the element.
See the comments for `width'.
@end table

Example:

@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


Άλλαξε στην έκδοση 3.13: Added support of the «vsapi» element factory.

@end deffn

@geindex element_names() (μέθοδος της tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style element_names}@anchor{4627}
@deffn {Μέθοδος} element_names ()

Returns the list of elements defined in the current theme.
@end deffn

@geindex element_options() (μέθοδος της tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style element_options}@anchor{4628}
@deffn {Μέθοδος} element_options (elementname)

Returns the list of `elementname'’s options.
@end deffn

@geindex theme_create() (μέθοδος της tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style theme_create}@anchor{4629}
@deffn {Μέθοδος} theme_create (themename, parent=None, settings=None)

Create a new theme.

It is an error if `themename' already exists. If `parent' is specified,
the new theme will inherit styles, elements and layouts from the parent
theme. If `settings' are present they are expected to have the same
syntax used for @ref{462a,,theme_settings()}.
@end deffn

@geindex theme_settings() (μέθοδος της tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style theme_settings}@anchor{462a}
@deffn {Μέθοδος} theme_settings (themename, settings)

Temporarily sets the current theme to `themename', apply specified
`settings' and then restore the previous theme.

Each key in `settings' is a style and each value may contain the keys
“configure”, “map”, “layout” and “element create” and they are expected
to have the same format as specified by the methods
@ref{4623,,Style.configure()}, @ref{1edb,,Style.map()}, @ref{4625,,Style.layout()} and
@ref{760,,Style.element_create()} respectively.

As an example, let’s change the Combobox for the default theme a bit:

@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() (μέθοδος της tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style theme_names}@anchor{462b}
@deffn {Μέθοδος} theme_names ()

Returns a list of all known themes.
@end deffn

@geindex theme_use() (μέθοδος της tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style theme_use}@anchor{462c}
@deffn {Μέθοδος} theme_use (themename=None)

If `themename' is not given, returns the theme in use.  Otherwise, sets
the current theme to `themename', refreshes all widgets and emits a
<<ThemeChanged>> event.
@end deffn
@end deffn

@menu
* Layouts:: 

@end menu

@node Layouts,,,Ttk Styling
@anchor{library/tkinter ttk layouts}@anchor{4626}
@subsubsection Layouts


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.

The valid options/values are:


@table @asis

@item `side': whichside

Specifies which side of the cavity to place the element; one of
top, right, bottom or left. If omitted, the element occupies the
entire cavity.

@item `sticky': nswe

Specifies where the element is placed inside its allocated parcel.

@item `unit': 0 or 1

If set to 1, causes the element and all of its descendants to be treated as
a single element for the purposes of @ref{45d1,,Widget.identify()} et al. It’s
used for things like scrollbar thumbs with grips.

@item `children': [sublayout… ]

Specifies a list of elements to place inside the element. Each
element is a tuple (or other sequence type) where the first item is
the layout name, and the other is a @ref{4626,,Layout}.
@end table
@anchor{library/tkinter ttk layout}@anchor{462d}
@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node IDLE — Python editor and shell,turtle — Turtle graphics,tkinter ttk — Tk themed widgets,Γραφικές επαφές χρηστών με το Tk
@anchor{library/idle doc}@anchor{462e}@anchor{library/idle idle}@anchor{13be}@anchor{library/idle idle-python-editor-and-shell}@anchor{462f}@anchor{library/idle translation-repo}@anchor{4630}
@subsection IDLE — Python editor and shell


`Source code:' Lib/idlelib/@footnote{https://github.com/python/cpython/tree/main/Lib/idlelib/}

@geindex IDLE
@geindex Python Editor
@geindex Integrated Development Environment

@c Remember to update Lib/idlelib/help.html with idlelib.help.copy_strip() when modifying this file.


__________________________________________________________________


IDLE is Python’s Integrated Development and Learning Environment.

IDLE has the following features:


@itemize *

@item 
cross-platform: works mostly the same on Windows, Unix, and macOS

@item 
Python shell window (interactive interpreter) with colorizing
of code input, output, and error messages

@item 
multi-window text editor with multiple undo, Python colorizing,
smart indent, call tips, auto completion, and other features

@item 
search within any window, replace within editor windows, and search
through multiple files (grep)

@item 
debugger with persistent breakpoints, stepping, and viewing
of global and local namespaces

@item 
configuration, browsers, and other dialogs
@end itemize

The IDLE application is implemented in the @ref{76,,idlelib} package.

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile

@menu
* Menus:: 
* Editing and Navigation:: 
* Startup and Code Execution:: 
* Help and Preferences:: 
* idlelib — implementation of IDLE application:: 

@end menu

@node Menus,Editing and Navigation,,IDLE — Python editor and shell
@anchor{library/idle menus}@anchor{4631}
@subsubsection Menus


IDLE has two main window types, the Shell window and the Editor window.  It is
possible to have multiple editor windows simultaneously.  On Windows and
Linux, each has its own top menu.  Each menu documented below indicates
which window type it is associated with.

Output windows, such as used for Edit => Find in Files, are a subtype of editor
window.  They currently have the same top menu but a different
default title and context menu.

On macOS, there is one application menu.  It dynamically changes according
to the window currently selected.  It has an IDLE menu, and some entries
described below are moved around to conform to Apple guidelines.

@menu
* File menu (Shell and Editor): File menu Shell and Editor. 
* Edit menu (Shell and Editor): Edit menu Shell and Editor. 
* Format menu (Editor window only): Format menu Editor window only. 
* Run menu (Editor window only): Run menu Editor window only. 
* Shell menu (Shell window only): Shell menu Shell window only. 
* Debug menu (Shell window only): Debug menu Shell window only. 
* Options menu (Shell and Editor): Options menu Shell and Editor. 
* Window menu (Shell and Editor): Window menu Shell and Editor. 
* Help menu (Shell and Editor): Help menu Shell and Editor. 
* Context menus:: 

@end menu

@node File menu Shell and Editor,Edit menu Shell and Editor,,Menus
@anchor{library/idle file-menu-shell-and-editor}@anchor{4632}
@subsubsection File menu (Shell and Editor)



@table @asis

@item New File

Create a new file editing window.

@item Open…

Open an existing file with an Open dialog.

@item Open Module…

Open an existing module (searches sys.path).

@item Recent Files

Open a list of recent files.  Click one to open it.
@end table

@geindex Module browser
@geindex Path browser


@table @asis

@item Module Browser

Show functions, classes, and methods in the current Editor file in a
tree structure.  In the shell, open a module first.

@item Path Browser

Show sys.path directories, modules, functions, classes and methods in a
tree structure.

@item Save

Save the current window to the associated file, if there is one.  Windows
that have been changed since being opened or last saved have a * before
and after the window title.  If there is no associated file,
do Save As instead.

@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 manager 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

Print the current window to the default printer.

@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 Edit menu Shell and Editor,Format menu Editor window only,File menu Shell and Editor,Menus
@anchor{library/idle edit-menu-shell-and-editor}@anchor{4633}
@subsubsection Edit menu (Shell and Editor)



@table @asis

@item Undo

Undo the last change to the current window.  A maximum of 1000 changes may
be undone.

@item Redo

Redo the last undone change to the current window.

@item Select All

Select the entire contents of the current window.

@item Cut

Copy selection into the system-wide clipboard; then delete the selection.

@item Copy

Copy selection into the system-wide clipboard.

@item Paste

Insert contents of the system-wide clipboard into the current window.
@end table

The clipboard functions are also available in context menus.


@table @asis

@item Find…

Open a search dialog with many options

@item Find Again

Repeat the last search, if there is one.

@item Find Selection

Search for the currently selected string, if there is one.

@item Find in Files…

Open a file search dialog.  Put results in a new output window.

@item Replace…

Open a search-and-replace dialog.

@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{4634,,Completions} in the Editing and Navigation section below.

@item Expand Word

Expand a prefix you have typed to match a full word in the same window;
repeat to get a different expansion.

@item Show Call Tip

After an unclosed parenthesis for a function, open a small window with
function parameter hints.  See @ref{4635,,Calltips} in the
Editing and Navigation section below.

@item Show Surrounding Parens

Highlight the surrounding parenthesis.
@end table

@node Format menu Editor window only,Run menu Editor window only,Edit menu Shell and Editor,Menus
@anchor{library/idle format-menu}@anchor{4636}@anchor{library/idle format-menu-editor-window-only}@anchor{4637}
@subsubsection Format menu (Editor window only)



@table @asis

@item Format Paragraph

Rewrap the text block containing the text insert cursor.
Avoid code lines.  See @ref{4638,,Format block} in the
Editing and Navigation section below.

@item Indent Region

Shift selected lines right by the indent width (default 4 spaces).

@item Dedent Region

Shift selected lines left by the indent width (default 4 spaces).

@item Comment Out Region

Insert ## in front of selected lines.

@item Uncomment Region

Remove leading # or ## from selected lines.

@item Tabify Region

Turn `leading' stretches of spaces into tabs. (Note: We recommend using
4 space blocks to indent Python code.)

@item Untabify Region

Turn `all' tabs into the correct number of spaces.

@item Toggle Tabs

Open a dialog to switch between indenting with spaces and tabs.

@item New Indent Width

Open a dialog to change indent width. The accepted default by the Python
community is 4 spaces.

@item Strip Trailing Whitespace

Remove trailing space and other whitespace characters after the last
non-whitespace character of a line by applying @ref{1853,,str.rstrip()} to each line,
including lines within multiline strings.  Except for Shell windows,
remove extra newlines at the end of the file.
@end table

@geindex Run script

@node Run menu Editor window only,Shell menu Shell window only,Format menu Editor window only,Menus
@anchor{library/idle run-menu-editor-window-only}@anchor{4639}
@subsubsection Run menu (Editor window only)

@anchor{library/idle run-module}@anchor{463a}

@table @asis

@item Run Module

Do @ref{463b,,Check Module}.  If no error, restart the shell to clean the
environment, then execute the module.  Output is displayed in the Shell
window.  Note that output requires use of @code{print} or @code{write}.
When execution is complete, the Shell retains focus and displays a prompt.
At this point, one may interactively explore the result of execution.
This is similar to executing a file with @code{python -i file} at a command
line.
@end table
@anchor{library/idle run-custom}@anchor{463c}

@table @asis

@item Run… Customized

Same as @ref{463a,,Run Module}, but run the module with customized
settings.  `Command Line Arguments' extend @ref{1609,,sys.argv} as if passed
on a command line. The module can be run in the Shell without restarting.
@end table
@anchor{library/idle check-module}@anchor{463b}

@table @asis

@item Check Module

Check the syntax of the module currently open in the Editor window. If the
module has not been saved IDLE will either prompt the user to save or
autosave, as selected in the General tab of the Idle Settings dialog.  If
there is a syntax error, the approximate location is indicated in the
Editor window.
@end table
@anchor{library/idle python-shell}@anchor{463d}

@table @asis

@item Python Shell

Open or wake up the Python Shell window.
@end table

@node Shell menu Shell window only,Debug menu Shell window only,Run menu Editor window only,Menus
@anchor{library/idle shell-menu-shell-window-only}@anchor{463e}
@subsubsection Shell menu (Shell window only)



@table @asis

@item View Last Restart

Scroll the shell window to the last Shell restart.

@item Restart Shell

Restart the shell to clean the environment and reset display and exception handling.

@item Previous History

Cycle through earlier commands in history which match the current entry.

@item Next History

Cycle through later commands in history which match the current entry.

@item Interrupt Execution

Stop a running program.
@end table

@node Debug menu Shell window only,Options menu Shell and Editor,Shell menu Shell window only,Menus
@anchor{library/idle debug-menu-shell-window-only}@anchor{463f}
@subsubsection Debug menu (Shell window only)



@table @asis

@item Go to File/Line

Look on the current line. with the cursor, and the line above for a filename
and line number.  If found, open the file if not already open, and show the
line.  Use this to view source lines referenced in an exception traceback
and lines found by Find in Files. Also available in the context menu of
the Shell window and Output windows.
@end table

@geindex debugger
@geindex stack viewer


@table @asis

@item Debugger (toggle)

When activated, code entered in the Shell or run from an Editor will run
under the debugger.  In the Editor, breakpoints can be set with the context
menu.  This feature is still incomplete and somewhat experimental.

@item Stack Viewer

Show the stack traceback of the last exception in a tree widget, with
access to locals and globals.

@item Auto-open Stack Viewer

Toggle automatically opening the stack viewer on an unhandled exception.
@end table

@node Options menu Shell and Editor,Window menu Shell and Editor,Debug menu Shell window only,Menus
@anchor{library/idle options-menu-shell-and-editor}@anchor{4640}
@subsubsection Options menu (Shell and Editor)



@table @asis

@item Configure IDLE

Open a configuration dialog and change preferences for the following:
fonts, indentation, keybindings, text color themes, startup windows and
size, additional help sources, and extensions.  On macOS, open the
configuration dialog by selecting Preferences in the application
menu. For more details, see
@ref{4641,,Setting preferences} under Help and preferences.
@end table

Most configuration options apply to all windows or all future windows.
The option items below only apply to the active window.


@table @asis

@item Show/Hide Code Context (Editor Window only)

Open a pane at the top of the edit window which shows the block context
of the code which has scrolled above the top of the window.  See
@ref{4642,,Code Context} in the Editing and Navigation section
below.

@item Show/Hide Line Numbers (Editor Window only)

Open a column to the left of the edit window which shows the number
of each line of text.  The default is off, which may be changed in the
preferences (see @ref{4641,,Setting preferences}).

@item Zoom/Restore Height

Toggles the window between normal size and maximum height. The initial size
defaults to 40 lines by 80 chars unless changed on the General tab of the
Configure IDLE dialog.  The maximum height for a screen is determined by
momentarily maximizing a window the first time one is zoomed on the screen.
Changing screen settings may invalidate the saved height.  This toggle has
no effect when a window is maximized.
@end table

@node Window menu Shell and Editor,Help menu Shell and Editor,Options menu Shell and Editor,Menus
@anchor{library/idle window-menu-shell-and-editor}@anchor{4643}
@subsubsection Window menu (Shell and Editor)


Lists the names of all open windows; select one to bring it to the foreground
(deiconifying it if necessary).

@node Help menu Shell and Editor,Context menus,Window menu Shell and Editor,Menus
@anchor{library/idle help-menu-shell-and-editor}@anchor{4644}
@subsubsection Help menu (Shell and Editor)



@table @asis

@item About IDLE

Display version, copyright, license, credits, and more.

@item IDLE Help

Display this IDLE document, detailing the menu options, basic editing and
navigation, and other tips.

@item Python Docs

Access local Python documentation, if installed, or start a web browser
and open docs.python.org showing the latest Python documentation.

@item Turtle Demo

Run the turtledemo module with example Python code and turtle drawings.
@end table

Additional help sources may be added here with the Configure IDLE dialog under
the General tab. See the @ref{4645,,Help sources} subsection below
for more on Help menu choices.

@geindex Cut
@geindex Copy
@geindex Paste
@geindex Set Breakpoint
@geindex Clear Breakpoint
@geindex breakpoints

@node Context menus,,Help menu Shell and Editor,Menus
@anchor{library/idle context-menus}@anchor{4646}
@subsubsection Context menus


Open a context menu by right-clicking in a window (Control-click on macOS).
Context menus have the standard clipboard functions also on the Edit menu.


@table @asis

@item Cut

Copy selection into the system-wide clipboard; then delete the selection.

@item Copy

Copy selection into the system-wide clipboard.

@item Paste

Insert contents of the system-wide clipboard into the current window.
@end table

Editor windows also have breakpoint functions.  Lines with a breakpoint set are
specially marked.  Breakpoints only have an effect when running under the
debugger.  Breakpoints for a file are saved in the user’s @code{.idlerc}
directory.


@table @asis

@item Set Breakpoint

Set a breakpoint on the current line.

@item Clear Breakpoint

Clear the breakpoint on that line.
@end table

Shell and Output windows also have the following.


@table @asis

@item Go to file/line

Same as in Debug menu.
@end table

The Shell window also has an output squeezing facility explained in the `Python
Shell window' subsection below.


@table @asis

@item Squeeze

If the cursor is over an output line, squeeze all the output between
the code above and the prompt below down to a “Squeezed text” label.
@end table

@node Editing and Navigation,Startup and Code Execution,Menus,IDLE — Python editor and shell
@anchor{library/idle editing-and-navigation}@anchor{4647}@anchor{library/idle id1}@anchor{4648}
@subsubsection Editing and Navigation


@menu
* Editor windows:: 
* Key bindings:: 
* Automatic indentation:: 
* Search and Replace:: 
* Completions:: 
* Calltips:: 
* Format block:: 
* Code Context:: 
* Shell window:: 
* Text colors:: 

@end menu

@node Editor windows,Key bindings,,Editing and Navigation
@anchor{library/idle editor-windows}@anchor{4649}
@subsubsection Editor windows


IDLE may open editor windows when it starts, depending on settings
and how you start IDLE.  Thereafter, use the File menu.  There can be only
one open editor window for a given file.

The title bar contains the name of the file, the full path, and the version
of Python and IDLE running the window.  The status bar contains the line
number (“Ln”) and column number (“Col”).  Line numbers start with 1;
column numbers with 0.

IDLE assumes that files with a known .py* extension contain Python code
and that other files do not.  Run Python code with the Run menu.

@node Key bindings,Automatic indentation,Editor windows,Editing and Navigation
@anchor{library/idle key-bindings}@anchor{464a}
@subsubsection Key bindings


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}-@code{LeftArrow} and @code{C}-@code{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}-@code{Home} and @code{C}-@code{End} go to beginning or end of the file.

@item 
@code{Backspace} and @code{Del} (or @code{C}-@code{d}) delete the previous
or next character.

@item 
@code{C}-@code{Backspace} and @code{C}-@code{Del} delete one word left or right.

@item 
@code{C}-@code{k} deletes (“kills”) everything to the right.
@end itemize

Standard keybindings (like @code{C}-@code{c} to copy and @code{C}-@code{v} to paste)
may work.  Keybindings are selected in the Configure IDLE dialog.

@node Automatic indentation,Search and Replace,Key bindings,Editing and Navigation
@anchor{library/idle automatic-indentation}@anchor{464b}
@subsubsection Automatic indentation


After a block-opening statement, the next line is indented by 4 spaces (in the
Python Shell window by one tab).  After certain keywords (break, return etc.)
the next line is dedented.  In leading indentation, @code{Backspace} deletes up
to 4 spaces if they are there. @code{Tab} inserts spaces (in the Python
Shell window one tab), number depends on Indent width. Currently, tabs
are restricted to four spaces due to Tcl/Tk limitations.

See also the indent/dedent region commands on the
@ref{4636,,Format menu}.

@node Search and Replace,Completions,Automatic indentation,Editing and Navigation
@anchor{library/idle search-and-replace}@anchor{464c}
@subsubsection Search and Replace


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 Completions,Calltips,Search and Replace,Editing and Navigation
@anchor{library/idle completions}@anchor{4634}@anchor{library/idle id2}@anchor{464d}
@subsubsection Completions


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{a5a,,os.sep} or
@ref{a5b,,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}-@code{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 Calltips,Format block,Completions,Editing and Navigation
@anchor{library/idle calltips}@anchor{4635}@anchor{library/idle id3}@anchor{464e}
@subsubsection Calltips


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 Format block,Code Context,Calltips,Editing and Navigation
@anchor{library/idle format-block}@anchor{4638}@anchor{library/idle id4}@anchor{464f}
@subsubsection Format block


Reformat Paragraph rewraps a block (“paragraph”) of contiguous equally
indented non-blank comments, a similar block of text within a multiline
string, or a selected subset of either.
If needed, add a blank line to separate string from code.
Partial lines in a selection expand to complete lines.
The resulting lines have the same indent as before
but have maximum total length of N columns (characters).
Change the default N of 72 on the Window tab of IDLE Settings.

@node Code Context,Shell window,Format block,Editing and Navigation
@anchor{library/idle code-context}@anchor{4642}@anchor{library/idle id5}@anchor{4650}
@subsubsection Code Context


Within an editor window containing Python code, code context can be toggled
in order to show or hide a pane at the top of the window.  When shown, this
pane freezes the opening lines for block code, such as those beginning with
@code{class}, @code{def}, or @code{if} keywords, that would have otherwise scrolled
out of view.  The size of the pane will be expanded and contracted as needed
to show the all current levels of context, up to the maximum number of
lines defined in the Configure IDLE dialog (which defaults to 15).  If there
are no current context lines and the feature is toggled on, a single blank
line will display.  Clicking on a line in the context pane will move that
line to the top of the editor.

The text and background colors for the context pane can be configured under
the Highlights tab in the Configure IDLE dialog.

@node Shell window,Text colors,Code Context,Editing and Navigation
@anchor{library/idle shell-window}@anchor{4651}
@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{17e,,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}-@code{c} attempts to interrupt statement execution (but may fail).

@item 
@code{C}-@code{d} closes Shell if typed at a @code{>>>} prompt.

@item 
@code{Alt}-@code{p} and @code{Alt}-@code{n} (@code{C}-@code{p} and @code{C}-@code{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 Text colors,,Shell window,Editing and Navigation
@anchor{library/idle text-colors}@anchor{4652}
@subsubsection Text colors


Idle defaults to black on white text, but colors text with special meanings.
For the shell, these are shell output, shell error, user output, and
user error.  For Python code, at the shell prompt or in an editor, these are
keywords, builtin class and function names, names following @code{class} and
@code{def}, strings, and comments. For any text window, these are the cursor (when
present), found text (when possible), and selected text.

IDLE also highlights the @ref{be6,,soft keywords} @ref{1d4,,match},
@code{case}, and @ref{be7,,_} 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.

Text coloring is done in the background, so uncolorized text is occasionally
visible.  To change the color scheme, use the Configure IDLE dialog
Highlighting tab.  The marking of debugger breakpoint lines in the editor and
text in popups and dialogs is not user-configurable.

@node Startup and Code Execution,Help and Preferences,Editing and Navigation,IDLE — Python editor and shell
@anchor{library/idle startup-and-code-execution}@anchor{4653}
@subsubsection Startup and Code Execution


Upon startup with the @code{-s} option, IDLE will execute the file referenced by
the environment variables 
@geindex IDLESTARTUP
@geindex μεταβλητή περιβάλλοντος; IDLESTARTUP
@code{IDLESTARTUP} or 
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP}.
IDLE first checks for @code{IDLESTARTUP}; if @code{IDLESTARTUP} is present the file
referenced is run.  If @code{IDLESTARTUP} is not present, IDLE checks for
@code{PYTHONSTARTUP}.  Files referenced by these environment variables are
convenient places to store functions that are used frequently from the IDLE
shell, or for executing import statements to import common modules.

In addition, @code{Tk} also loads a startup file if it is present.  Note that the
Tk file is loaded unconditionally.  This additional file is @code{.Idle.py} and is
looked for in the user’s home directory.  Statements in this file will be
executed in the Tk namespace, so this file is not useful for importing
functions to be used from IDLE’s Python shell.

@menu
* Command-line usage: Command-line usage<3>. 
* Startup failure:: 
* Running user code:: 
* User output in Shell:: 
* Developing tkinter applications:: 
* Running without a subprocess:: 

@end menu

@node Command-line usage<3>,Startup failure,,Startup and Code Execution
@anchor{library/idle command-line-usage}@anchor{4654}@anchor{library/idle idlelib-cli}@anchor{4655}
@subsubsection Command-line usage


IDLE can be invoked from the command line with various options. The general syntax is:

@example
python -m idlelib [options] [file ...]
@end example

The following options are available:

@geindex idle command line option; -c
@anchor{library/idle cmdoption-idle-c}@anchor{4656}
@deffn {Option} @w{-}c <command>

Run the specified Python command in the shell window.
For example, pass @code{-c "print('Hello, World!')"}.
On Windows, the outer quotes must be double quotes as shown.
@end deffn

@geindex idle command line option; -d
@anchor{library/idle cmdoption-idle-d}@anchor{4657}
@deffn {Option} @w{-}d

Enable the debugger and open the shell window.
@end deffn

@geindex idle command line option; -e
@anchor{library/idle cmdoption-idle-e}@anchor{4658}
@deffn {Option} @w{-}e

Open an editor window.
@end deffn

@geindex idle command line option; -h
@anchor{library/idle cmdoption-idle-h}@anchor{4659}
@deffn {Option} @w{-}h

Print a help message with legal combinations of options and exit.
@end deffn

@geindex idle command line option; -i
@anchor{library/idle cmdoption-idle-i}@anchor{465a}
@deffn {Option} @w{-}i

Open a shell window.
@end deffn

@geindex idle command line option; -r
@anchor{library/idle cmdoption-idle-r}@anchor{465b}
@deffn {Option} @w{-}r <file>

Run the specified file in the shell window.
@end deffn

@geindex idle command line option; -s
@anchor{library/idle cmdoption-idle-s}@anchor{465c}
@deffn {Option} @w{-}s

Run the startup file (as defined by the environment variables 
@geindex IDLESTARTUP
@geindex μεταβλητή περιβάλλοντος; IDLESTARTUP
@code{IDLESTARTUP} or 
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP}) before opening the shell window.
@end deffn

@geindex idle command line option; -t
@anchor{library/idle cmdoption-idle-t}@anchor{465d}
@deffn {Option} @w{-}t <title>

Set the title of the shell window.
@end deffn

@geindex idle command line option; -
@anchor{library/idle cmdoption-idle-0}@anchor{465e}
@deffn {Option} @w{-}

Read and execute standard input in the shell window. This option must be the last one before any arguments.
@end deffn

If arguments are provided:


@itemize -

@item 
If @code{-}, @code{-c}, or @code{-r} is used, all arguments are placed in @code{sys.argv[1:]},
and @code{sys.argv[0]} is set to @code{'@w{'}}, @code{'-c'}, or @code{'-r'} respectively.
No editor window is opened, even if that is the default set in the `Options' dialog.

@item 
Otherwise, arguments are treated as files to be opened for editing, and @code{sys.argv} reflects the arguments passed to IDLE itself.
@end itemize

@node Startup failure,Running user code,Command-line usage<3>,Startup and Code Execution
@anchor{library/idle startup-failure}@anchor{465f}
@subsubsection Startup failure


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.

A common cause of failure is a user-written file with the same name as a
standard library module, such as `random.py' and `tkinter.py'. When such a
file is located in the same directory as a file that is about to be run,
IDLE cannot import the stdlib file.  The current fix is to rename the
user file.

Though less common than in the past, an antivirus or firewall program may
stop the connection.  If the program cannot be taught to allow the
connection, then it must be turned off for IDLE to work.  It is safe to
allow this internal connection because no data is visible on external
ports.  A similar problem is a network mis-configuration that blocks
connections.

Python installation issues occasionally stop IDLE: multiple versions can
clash, or a single installation might need admin access.  If one undo the
clash, or cannot or does not want to run as admin, it might be easiest to
completely remove Python and start over.

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 Running user code,User output in Shell,Startup failure,Startup and Code Execution
@anchor{library/idle running-user-code}@anchor{4660}
@subsubsection Running user code


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.

By default, IDLE runs user code in a separate OS process rather than in
the user interface process that runs the shell and editor.  In the execution
process, it replaces @code{sys.stdin}, @code{sys.stdout}, and @code{sys.stderr}
with objects that get input from and send output to the Shell window.
The original values stored in @code{sys.__stdin__}, @code{sys.__stdout__}, and
@code{sys.__stderr__} are not touched, but may be @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{2803,,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.

If @code{sys} is reset by user code, such as with @code{importlib.reload(sys)},
IDLE’s changes are lost and input from the keyboard and output to the screen
will not work correctly.

When Shell has the focus, it controls the keyboard and screen.  This is
normally transparent, but functions that directly access the keyboard
and screen will not work.  These include system-specific functions that
determine whether a key has been pressed and if so, which.

The IDLE code running in the execution process adds frames to the call stack
that would not be there otherwise.  IDLE wraps @code{sys.getrecursionlimit} and
@code{sys.setrecursionlimit} to reduce the effect of the additional stack
frames.

When user code raises SystemExit either directly or by calling sys.exit,
IDLE returns to a Shell prompt instead of exiting.

@node User output in Shell,Developing tkinter applications,Running user code,Startup and Code Execution
@anchor{library/idle user-output-in-shell}@anchor{4661}
@subsubsection User output in Shell


When a program outputs text, the result is determined by the
corresponding output device.  When IDLE executes user code, @code{sys.stdout}
and @code{sys.stderr} are connected to the display area of IDLE’s Shell.  Some of
its features are inherited from the underlying Tk Text widget.  Others
are programmed additions.  Where it matters, Shell is designed for development
rather than production runs.

For instance, Shell never throws away output.  A program that sends unlimited
output to Shell will eventually fill memory, resulting in a memory error.
In contrast, some system text windows only keep the last n lines of output.
A Windows console, for instance, keeps a user-settable 1 to 9999 lines,
with 300 the default.

A Tk Text widget, and hence IDLE’s Shell, displays characters (codepoints) in
the BMP (Basic Multilingual Plane) subset of Unicode.  Which characters are
displayed with a proper glyph and which with a replacement box depends on the
operating system and installed fonts.  Tab characters cause the following text
to begin after the next tab stop. (They occur every 8 “characters”).  Newline
characters cause following text to appear on a new line.  Other control
characters are ignored or displayed as a space, box, or something else,
depending on the operating system and font.  (Moving the text cursor through
such output with arrow keys may exhibit some surprising spacing behavior.)

@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

The @code{repr} function is used for interactive echo of expression
values.  It returns an altered version of the input string in which
control codes, some BMP codepoints, and all non-BMP codepoints are
replaced with escape codes. As demonstrated above, it allows one to
identify the characters in a string, regardless of how they are displayed.

Normal and error output are generally kept separate (on separate lines)
from code input and each other.  They each get different highlight colors.

For SyntaxError tracebacks, the normal “^” marking where the error was
detected is replaced by coloring the text with an error highlight.
When code run from a file causes other exceptions, one may right click
on a traceback line to jump to the corresponding line in an IDLE editor.
The file will be opened if necessary.

Shell has a special facility for squeezing output lines down to a
“Squeezed text” label.  This is done automatically
for output over N lines (N = 50 by default).
N can be changed in the PyShell section of the General
page of the Settings dialog.  Output with fewer lines can be squeezed by
right clicking on the output.  This can be useful lines long enough to slow
down scrolling.

Squeezed output is expanded in place by double-clicking the label.
It can also be sent to the clipboard or a separate view window by
right-clicking the label.

@node Developing tkinter applications,Running without a subprocess,User output in Shell,Startup and Code Execution
@anchor{library/idle developing-tkinter-applications}@anchor{4662}
@subsubsection Developing tkinter applications


IDLE is intentionally different from standard Python in order to
facilitate development of tkinter programs.  Enter @code{import tkinter as tk;
root = tk.Tk()} in standard Python and nothing appears.  Enter the same
in IDLE and a tk window appears.  In standard Python, one must also enter
@code{root.update()} to see the window.  IDLE does the equivalent in the
background, about 20 times a second, which is about every 50 milliseconds.
Next enter @code{b = tk.Button(root, text='button'); b.pack()}.  Again,
nothing visibly changes in standard Python until one enters @code{root.update()}.

Most tkinter programs run @code{root.mainloop()}, which usually does not
return until the tk app is destroyed.  If the program is run with
@code{python -i} or from an IDLE editor, a @code{>>>} shell prompt does not
appear until @code{mainloop()} returns, at which time there is nothing left
to interact with.

When running a tkinter program from an IDLE editor, one can comment out
the mainloop call.  One then gets a shell prompt immediately and can
interact with the live application.  One just has to remember to
re-enable the mainloop call when running in standard Python.

@node Running without a subprocess,,Developing tkinter applications,Startup and Code Execution
@anchor{library/idle running-without-a-subprocess}@anchor{4663}
@subsubsection Running without a subprocess


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.

If the attempt to make the socket connection fails, Idle will notify you.
Such failures are sometimes transient, but if persistent, the problem
may be either a firewall blocking the connection or misconfiguration of
a particular system.  Until the problem is fixed, one can run Idle with
the -n command line switch.

If IDLE is started with the -n command line switch it will run in a
single process and will not create the subprocess which runs the RPC
Python execution server.  This can be useful if Python cannot create
the subprocess or the RPC socket interface on your platform.  However,
in this mode user code is not isolated from IDLE itself.  Also, the
environment is not restarted when Run/Run Module (F5) is selected.  If
your code has been modified, you must reload() the affected modules and
re-import any specific items (e.g. from foo import baz) if the changes
are to take effect.  For these reasons, it is preferable to run IDLE
with the default subprocess if at all possible.


Αποσύρθηκε στην έκδοση 3.4.


@node Help and Preferences,idlelib — implementation of IDLE application,Startup and Code Execution,IDLE — Python editor and shell
@anchor{library/idle help-and-preferences}@anchor{4664}
@subsubsection Help and Preferences


@menu
* Help sources:: 
* Setting preferences:: 
* IDLE on macOS:: 
* Extensions:: 

@end menu

@node Help sources,Setting preferences,,Help and Preferences
@anchor{library/idle help-sources}@anchor{4645}@anchor{library/idle id6}@anchor{4665}
@subsubsection Help sources


Help menu entry «IDLE Help» displays a formatted html version of the
IDLE chapter of the Library Reference.  The result, in a read-only
tkinter text window, is close to what one sees in a web browser.
Navigate through the text with a mousewheel,
the scrollbar, or up and down arrow keys held down.
Or click the TOC (Table of Contents) button and select a section
header in the opened box.

Help menu entry «Python Docs» opens the extensive sources of help,
including tutorials, available at @code{docs.python.org/x.y}, where “x.y”
is the currently running Python version.  If your system
has an off-line copy of the docs (this may be an installation option),
that will be opened instead.

Selected URLs can be added or removed from the help menu at any time using the
General tab of the Configure IDLE dialog.

@node Setting preferences,IDLE on macOS,Help sources,Help and Preferences
@anchor{library/idle preferences}@anchor{4641}@anchor{library/idle setting-preferences}@anchor{4666}
@subsubsection Setting preferences


The font preferences, highlighting, keys, and general preferences can be
changed via Configure IDLE on the Option menu.
Non-default user settings are saved in a @code{.idlerc} directory in the user’s
home directory.  Problems caused by bad user configuration files are solved
by editing or deleting one or more of the files in @code{.idlerc}.

On the Font tab, see the text sample for the effect of font face and size
on multiple characters in multiple languages.  Edit the sample to add
other characters of personal interest.  Use the sample to select
monospaced fonts.  If particular characters have problems in Shell or an
editor, add them to the top of the sample and try changing first size
and then font.

On the Highlights and Keys tab, select a built-in or custom color theme
and key set.  To use a newer built-in color theme or key set with older
IDLEs, save it as a new custom theme or key set and it well be accessible
to older IDLEs.

@node IDLE on macOS,Extensions,Setting preferences,Help and Preferences
@anchor{library/idle idle-on-macos}@anchor{4667}
@subsubsection IDLE on macOS


Under System Preferences: Dock, one can set «Prefer tabs when opening
documents» to «Always».  This setting is not compatible with the tk/tkinter
GUI framework used by IDLE, and it breaks a few IDLE features.

@node Extensions,,IDLE on macOS,Help and Preferences
@anchor{library/idle extensions}@anchor{4668}
@subsubsection Extensions


IDLE contains an extension facility.  Preferences for extensions can be
changed with the Extensions tab of the preferences dialog. See the
beginning of config-extensions.def in the idlelib directory for further
information.  The only current default extension is zzdummy, an example
also used for testing.

@node idlelib — implementation of IDLE application,,Help and Preferences,IDLE — Python editor and shell
@anchor{library/idle idlelib-implementation-of-idle-application}@anchor{4669}@anchor{library/idle module-idlelib}@anchor{76}
@subsubsection idlelib — implementation of IDLE application


@geindex module; idlelib

`Source code:' Lib/idlelib@footnote{https://github.com/python/cpython/tree/main/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 Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node turtle — Turtle graphics,,IDLE — Python editor and shell,Γραφικές επαφές χρηστών με το Tk
@anchor{library/turtle doc}@anchor{466a}@anchor{library/turtle module-turtle}@anchor{10a}@anchor{library/turtle translation-repo}@anchor{466b}@anchor{library/turtle turtle-turtle-graphics}@anchor{466c}
@subsection @code{turtle} — Turtle graphics


@geindex module; turtle

`Source code:' Lib/turtle.py@footnote{https://github.com/python/cpython/tree/main/Lib/turtle.py}

@c from turtle import *
@c turtle = Turtle()

@c import os
@c os.remove("my_drawing.ps")
@c # Destroy the turtle window after tests are complete
@c # Imported via star import in testsetup
@c bye()


__________________________________________________________________


@menu
* Introduction: Introduction<10>. 
* Get started:: 
* Tutorial: Tutorial<4>. 
* How to…:: 
* Turtle graphics reference:: 
* Methods of RawTurtle/Turtle and corresponding functions:: 
* Methods of TurtleScreen/Screen and corresponding functions:: 
* Public classes:: 
* Explanation: Explanation<2>. 
* Help and configuration:: 
* turtledemo — Demo scripts:: 
* Changes since Python 2.6: Changes since Python 2 6. 
* Changes since Python 3.0: Changes since Python 3 0. 

@end menu

@node Introduction<10>,Get started,,turtle — Turtle graphics
@anchor{library/turtle introduction}@anchor{466d}
@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.

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile

@node Get started,Tutorial<4>,Introduction<10>,turtle — Turtle graphics
@anchor{library/turtle get-started}@anchor{466e}
@subsubsection Get started


Imagine a robotic turtle starting at (0, 0) in the x-y plane.  After an @code{import turtle}, give it the
command @code{turtle.forward(15)}, and it moves (on-screen!) 15 pixels in the
direction it is facing, drawing a line as it moves.  Give it the command
@code{turtle.right(25)}, and it rotates in-place 25 degrees clockwise.

@subsubheading Turtle star



Turtle can draw intricate shapes using programs that repeat simple
moves.

@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 Tutorial<4>,How to…,Get started,turtle — Turtle graphics
@anchor{library/turtle turtle-tutorial}@anchor{466f}@anchor{library/turtle tutorial}@anchor{4670}
@subsubsection Tutorial


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,,Tutorial<4>
@anchor{library/turtle starting-a-turtle-environment}@anchor{4671}
@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{f9,,Tk interface package} on your system.

@node Basic drawing,Making algorithmic patterns,Starting a turtle environment,Tutorial<4>
@anchor{library/turtle basic-drawing}@anchor{4672}
@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
* Pen control:: 
* The turtle’s position:: 

@end menu

@node Pen control,The turtle’s position,,Basic drawing
@anchor{library/turtle pen-control}@anchor{4673}
@subsubsection Pen control


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,,Pen control,Basic drawing
@anchor{library/turtle the-turtle-s-position}@anchor{4674}
@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,Tutorial<4>
@anchor{library/turtle making-algorithmic-patterns}@anchor{4675}
@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,Tutorial<4>,turtle — Turtle graphics
@anchor{library/turtle how-to}@anchor{4676}@anchor{library/turtle turtle-how-to}@anchor{4677}
@subsubsection How to…


This section covers some typical turtle use-cases and approaches.

@menu
* Get started as quickly as possible:: 
* Automatically begin and end filling:: 
* 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,Automatically begin and end filling,,How to…
@anchor{library/turtle get-started-as-quickly-as-possible}@anchor{4678}
@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{466f,,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{3858,,forward()}. These are especially
useful when working with learners for whom typing is not a skill.
@anchor{library/turtle note}@anchor{4679}
@quotation

You’ll need to have the @ref{f9,,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 Automatically begin and end filling,Use the turtle module namespace,Get started as quickly as possible,How to…
@anchor{library/turtle automatically-begin-and-end-filling}@anchor{467a}
@subsubsection Automatically begin and end filling


Starting with Python 3.14, you can use the @ref{523,,fill()} @ref{478,,context manager}
instead of @ref{467b,,begin_fill()} and @ref{467c,,end_fill()} to automatically begin and
end fill. Here is an example:

@example
with fill():
    for i in range(4):
        forward(100)
        right(90)

forward(200)
@end example

The code above is equivalent to:

@example
begin_fill()
for i in range(4):
    forward(100)
    right(90)
end_fill()

forward(200)
@end example

@node Use the turtle module namespace,Use turtle graphics in a script,Automatically begin and end filling,How to…
@anchor{library/turtle use-the-turtle-module-namespace}@anchor{467d}
@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{467e}
@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{467f}
@subsubsection Use object-oriented turtle graphics



@subsubheading Δείτε επίσης


@ref{4680,,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{4681,,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,Methods of RawTurtle/Turtle and corresponding functions,How to…,turtle — Turtle graphics
@anchor{library/turtle turtle-graphics-reference}@anchor{4682}
@subsubsection Turtle graphics reference


@cartouche
@quotation Σημείωση 
In the following documentation the argument list for functions is given.
Methods, of course, have the additional first argument `self' which is
omitted here.
@end quotation
@end cartouche

@menu
* Turtle methods:: 
* Methods of TurtleScreen/Screen:: 

@end menu

@node Turtle methods,Methods of TurtleScreen/Screen,,Turtle graphics reference
@anchor{library/turtle turtle-methods}@anchor{4683}
@subsubsection Turtle methods



@table @asis

@item Turtle motion


@table @asis

@item Move and draw


@display
@ref{3858,,forward()} | @ref{4684,,fd()}@w{ }
@ref{4685,,backward()} | @ref{4686,,bk()} | @ref{4687,,back()}@w{ }
@ref{4688,,right()} | @ref{4689,,rt()}@w{ }
@ref{468a,,left()} | @ref{468b,,lt()}@w{ }
@ref{468c,,goto()} | @ref{468d,,setpos()} | @ref{468e,,setposition()}@w{ }
@ref{1c9c,,teleport()}@w{ }
@ref{468f,,setx()}@w{ }
@ref{4690,,sety()}@w{ }
@ref{4691,,setheading()} | @ref{4692,,seth()}@w{ }
@ref{4693,,home()}@w{ }
@ref{4694,,circle()}@w{ }
@ref{4695,,dot()}@w{ }
@ref{4696,,stamp()}@w{ }
@ref{4697,,clearstamp()}@w{ }
@ref{4698,,clearstamps()}@w{ }
@ref{4699,,undo()}@w{ }
@ref{469a,,speed()}@w{ }
@end display



@item Tell Turtle’s state


@display
@ref{469b,,position()} | @ref{469c,,pos()}@w{ }
@ref{469d,,towards()}@w{ }
@ref{469e,,xcor()}@w{ }
@ref{469f,,ycor()}@w{ }
@ref{46a0,,heading()}@w{ }
@ref{46a1,,distance()}@w{ }
@end display



@item Setting and measurement


@display
@ref{46a2,,degrees()}@w{ }
@ref{46a3,,radians()}@w{ }
@end display


@end table

@item Pen control


@table @asis

@item Drawing state


@display
@ref{46a4,,pendown()} | @ref{46a5,,pd()} | @ref{46a6,,down()}@w{ }
@ref{46a7,,penup()} | @ref{46a8,,pu()} | @ref{46a9,,up()}@w{ }
@ref{46aa,,pensize()} | @ref{46ab,,width()}@w{ }
@ref{46ac,,pen()}@w{ }
@ref{46ad,,isdown()}@w{ }
@end display



@item Color control


@display
@ref{46ae,,color()}@w{ }
@ref{46af,,pencolor()}@w{ }
@ref{46b0,,fillcolor()}@w{ }
@end display



@item Filling


@display
@ref{46b1,,filling()}@w{ }
@ref{523,,fill()}@w{ }
@ref{467b,,begin_fill()}@w{ }
@ref{467c,,end_fill()}@w{ }
@end display



@item More drawing control


@display
@ref{46b2,,reset()}@w{ }
@ref{46b3,,clear()}@w{ }
@ref{46b4,,write()}@w{ }
@end display


@end table

@item Turtle state


@table @asis

@item Visibility


@display
@ref{46b5,,showturtle()} | @ref{46b6,,st()}@w{ }
@ref{46b7,,hideturtle()} | @ref{46b8,,ht()}@w{ }
@ref{46b9,,isvisible()}@w{ }
@end display



@item Appearance


@display
@ref{46ba,,shape()}@w{ }
@ref{46bb,,resizemode()}@w{ }
@ref{46bc,,shapesize()} | @ref{46bd,,turtlesize()}@w{ }
@ref{46be,,shearfactor()}@w{ }
@ref{b0d,,tiltangle()}@w{ }
@ref{46bf,,tilt()}@w{ }
@ref{46c0,,shapetransform()}@w{ }
@ref{46c1,,get_shapepoly()}@w{ }
@end display


@end table

@item Using events


@display
@ref{46c2,,onclick()}@w{ }
@ref{46c3,,onrelease()}@w{ }
@ref{46c4,,ondrag()}@w{ }
@end display



@item Special Turtle methods


@display
@ref{524,,poly()}@w{ }
@ref{46c5,,begin_poly()}@w{ }
@ref{46c6,,end_poly()}@w{ }
@ref{46c7,,get_poly()}@w{ }
@ref{46c8,,clone()}@w{ }
@ref{46c9,,getturtle()} | @ref{46ca,,getpen()}@w{ }
@ref{46cb,,getscreen()}@w{ }
@ref{46cc,,setundobuffer()}@w{ }
@ref{46cd,,undobufferentries()}@w{ }
@end display


@end table

@node Methods of TurtleScreen/Screen,,Turtle methods,Turtle graphics reference
@anchor{library/turtle methods-of-turtlescreen-screen}@anchor{46ce}
@subsubsection Methods of TurtleScreen/Screen



@table @asis

@item Window control


@display
@ref{46cf,,bgcolor()}@w{ }
@ref{46d0,,bgpic()}@w{ }
@ref{46d1,,clearscreen()}@w{ }
@ref{46d2,,resetscreen()}@w{ }
@ref{46d3,,screensize()}@w{ }
@ref{46d4,,setworldcoordinates()}@w{ }
@end display



@item Animation control


@display
@ref{525,,no_animation()}@w{ }
@ref{46d5,,delay()}@w{ }
@ref{46d6,,tracer()}@w{ }
@ref{46d7,,update()}@w{ }
@end display



@item Using screen events


@display
@ref{46d8,,listen()}@w{ }
@ref{46d9,,onkey()} | @ref{46da,,onkeyrelease()}@w{ }
@ref{46db,,onkeypress()}@w{ }
@ref{46c2,,onclick()} | @ref{46dc,,onscreenclick()}@w{ }
@ref{46dd,,ontimer()}@w{ }
@ref{46de,,mainloop()} | @ref{46df,,done()}@w{ }
@end display



@item Settings and special methods


@display
@ref{46e0,,mode()}@w{ }
@ref{46e1,,colormode()}@w{ }
@ref{46e2,,getcanvas()}@w{ }
@ref{46e3,,getshapes()}@w{ }
@ref{46e4,,register_shape()} | @ref{46e5,,addshape()}@w{ }
@ref{46e6,,turtles()}@w{ }
@ref{46e7,,window_height()}@w{ }
@ref{46e8,,window_width()}@w{ }
@end display



@item Input methods


@display
@ref{1e71,,textinput()}@w{ }
@ref{1e72,,numinput()}@w{ }
@end display



@item Methods specific to Screen


@display
@ref{46e9,,bye()}@w{ }
@ref{46ea,,exitonclick()}@w{ }
@ref{1b83,,save()}@w{ }
@ref{46eb,,setup()}@w{ }
@ref{46ec,,title()}@w{ }
@end display


@end table

@node Methods of RawTurtle/Turtle and corresponding functions,Methods of TurtleScreen/Screen and corresponding functions,Turtle graphics reference,turtle — Turtle graphics
@anchor{library/turtle methods-of-rawturtle-turtle-and-corresponding-functions}@anchor{46ed}
@subsubsection Methods of RawTurtle/Turtle and corresponding functions


Most of the examples in this section refer to a Turtle instance called
@code{turtle}.

@menu
* Turtle motion:: 
* Tell Turtle’s state:: 
* Settings for measurement:: 
* Pen control: Pen control<2>. 
* Turtle state:: 
* Using events:: 
* Special Turtle methods:: 
* Compound shapes:: 

@end menu

@node Turtle motion,Tell Turtle’s state,,Methods of RawTurtle/Turtle and corresponding functions
@anchor{library/turtle turtle-motion}@anchor{46ee}
@subsubsection Turtle motion


@geindex forward() (στη μονάδα turtle)
@geindex fd() (στη μονάδα turtle)
@anchor{library/turtle turtle forward}@anchor{3858}
@deffn {Συνάρτηση} turtle.forward (distance)
@anchor{library/turtle turtle fd}@anchor{4684}
@deffnx {Συνάρτηση} turtle.fd (distance)

@*Παράμετροι: 
@code{distance} – a number (integer or float)


Move the turtle forward by the specified `distance', in the direction the
turtle is headed.

@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() (στη μονάδα turtle)
@geindex bk() (στη μονάδα turtle)
@geindex backward() (στη μονάδα turtle)
@anchor{library/turtle turtle back}@anchor{4687}
@deffn {Συνάρτηση} turtle.back (distance)
@anchor{library/turtle turtle bk}@anchor{4686}
@deffnx {Συνάρτηση} turtle.bk (distance)
@anchor{library/turtle turtle backward}@anchor{4685}
@deffnx {Συνάρτηση} turtle.backward (distance)

@*Παράμετροι: 
@code{distance} – a number


Move the turtle backward by `distance', opposite to the direction the
turtle is headed.  Do not change the turtle’s heading.

@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() (στη μονάδα turtle)
@geindex rt() (στη μονάδα turtle)
@anchor{library/turtle turtle right}@anchor{4688}
@deffn {Συνάρτηση} turtle.right (angle)
@anchor{library/turtle turtle rt}@anchor{4689}
@deffnx {Συνάρτηση} turtle.rt (angle)

@*Παράμετροι: 
@code{angle} – a number (integer or float)


Turn turtle right by `angle' units.  (Units are by default degrees, but
can be set via the @ref{46a2,,degrees()} and @ref{46a3,,radians()} functions.)  Angle
orientation depends on the turtle mode, see @ref{46e0,,mode()}.

@c >>> turtle.setheading(22)

@example
>>> turtle.heading()
22.0
>>> turtle.right(45)
>>> turtle.heading()
337.0
@end example
@end deffn

@geindex left() (στη μονάδα turtle)
@geindex lt() (στη μονάδα turtle)
@anchor{library/turtle turtle left}@anchor{468a}
@deffn {Συνάρτηση} turtle.left (angle)
@anchor{library/turtle turtle lt}@anchor{468b}
@deffnx {Συνάρτηση} turtle.lt (angle)

@*Παράμετροι: 
@code{angle} – a number (integer or float)


Turn turtle left by `angle' units.  (Units are by default degrees, but
can be set via the @ref{46a2,,degrees()} and @ref{46a3,,radians()} functions.)  Angle
orientation depends on the turtle mode, see @ref{46e0,,mode()}.

@c >>> turtle.setheading(22)

@example
>>> turtle.heading()
22.0
>>> turtle.left(45)
>>> turtle.heading()
67.0
@end example
@end deffn

@geindex goto() (στη μονάδα turtle)
@geindex setpos() (στη μονάδα turtle)
@geindex setposition() (στη μονάδα turtle)
@anchor{library/turtle turtle goto}@anchor{468c}
@deffn {Συνάρτηση} turtle.goto (x, y=None)
@anchor{library/turtle turtle setpos}@anchor{468d}
@deffnx {Συνάρτηση} turtle.setpos (x, y=None)
@anchor{library/turtle turtle setposition}@anchor{468e}
@deffnx {Συνάρτηση} turtle.setposition (x, y=None)

@*Παράμετροι: 

@itemize *

@item 
@code{x} – a number or a pair/vector of numbers

@item 
@code{y} – a number or @code{None}
@end itemize


If `y' is @code{None}, `x' must be a pair of coordinates or a @ref{46ef,,Vec2D}
(e.g. as returned by @ref{469c,,pos()}).

Move turtle to an absolute position.  If the pen is down, draw line.  Do
not change the turtle’s orientation.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle teleport}@anchor{1c9c}
@deffn {Συνάρτηση} turtle.teleport (x, y=None, *, fill_gap=False)

@*Παράμετροι: 

@itemize *

@item 
@code{x} – a number or @code{None}

@item 
@code{y} – a number or @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


Added in version 3.12.

@end deffn

@geindex setx() (στη μονάδα turtle)
@anchor{library/turtle turtle setx}@anchor{468f}
@deffn {Συνάρτηση} turtle.setx (x)

@*Παράμετροι: 
@code{x} – a number (integer or float)


Set the turtle’s first coordinate to `x', leave second coordinate
unchanged.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle sety}@anchor{4690}
@deffn {Συνάρτηση} turtle.sety (y)

@*Παράμετροι: 
@code{y} – a number (integer or float)


Set the turtle’s second coordinate to `y', leave first coordinate unchanged.

@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() (στη μονάδα turtle)
@geindex seth() (στη μονάδα turtle)
@anchor{library/turtle turtle setheading}@anchor{4691}
@deffn {Συνάρτηση} turtle.setheading (to_angle)
@anchor{library/turtle turtle seth}@anchor{4692}
@deffnx {Συνάρτηση} turtle.seth (to_angle)

@*Παράμετροι: 
@code{to_angle} – a number (integer or float)


Set the orientation of the turtle to `to_angle'.  Here are some common
directions in degrees:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 
@headitem

standard mode

@tab

logo mode

@item

0 - east

@tab

0 - north

@item

90 - north

@tab

90 - east

@item

180 - west

@tab

180 - south

@item

270 - south

@tab

270 - west

@end multitable


@example
>>> turtle.setheading(90)
>>> turtle.heading()
90.0
@end example
@end deffn

@geindex home() (στη μονάδα turtle)
@anchor{library/turtle turtle home}@anchor{4693}
@deffn {Συνάρτηση} turtle.home ()

Move turtle to the origin – coordinates (0,0) – and set its heading to
its start-orientation (which depends on the mode, see @ref{46e0,,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() (στη μονάδα turtle)
@anchor{library/turtle turtle circle}@anchor{4694}
@deffn {Συνάρτηση} turtle.circle (radius, extent=None, steps=None)

@*Παράμετροι: 

@itemize *

@item 
@code{radius} – a number

@item 
@code{extent} – a number (or @code{None})

@item 
@code{steps} – an integer (or @code{None})
@end itemize


Draw a circle with given `radius'.  The center is `radius' units left of
the turtle; `extent' – an angle – determines which part of the circle
is drawn.  If `extent' is not given, draw the entire circle.  If `extent'
is not a full circle, one endpoint of the arc is the current pen
position.  Draw the arc in counterclockwise direction if `radius' is
positive, otherwise in clockwise direction.  Finally the direction of the
turtle is changed by the amount of `extent'.

As the circle is approximated by an inscribed regular polygon, `steps'
determines the number of steps to use.  If not given, it will be
calculated automatically.  May be used to draw regular polygons.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle dot}@anchor{4695}
@deffn {Συνάρτηση} turtle.dot ()

@deffnx {Συνάρτηση} turtle.dot (size)

@deffnx {Συνάρτηση} turtle.dot (color, /)

@deffnx {Συνάρτηση} turtle.dot (size, color, /)

@deffnx {Συνάρτηση} turtle.dot (size, r, g, b, /)

@*Παράμετροι: 

@itemize *

@item 
@code{size} – an integer >= 1 (if given)

@item 
@code{color} – a colorstring or a numeric color tuple
@end itemize


Draw a circular dot with diameter `size', using `color'.  If `size' is
not given, the maximum of @code{pensize+4} and @code{2*pensize} is used.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle stamp}@anchor{4696}
@deffn {Συνάρτηση} turtle.stamp ()

Stamp a copy of the turtle shape onto the canvas at the current turtle
position.  Return a stamp_id for that stamp, which can be used to delete
it by calling @code{clearstamp(stamp_id)}.

@example
>>> turtle.color("blue")
>>> stamp_id = turtle.stamp()
>>> turtle.fd(50)
@end example
@end deffn

@geindex clearstamp() (στη μονάδα turtle)
@anchor{library/turtle turtle clearstamp}@anchor{4697}
@deffn {Συνάρτηση} turtle.clearstamp (stampid)

@*Παράμετροι: 
@code{stampid} – an integer, must be return value of previous
@ref{4696,,stamp()} call


Delete stamp with given `stampid'.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle clearstamps}@anchor{4698}
@deffn {Συνάρτηση} turtle.clearstamps (n=None)

@*Παράμετροι: 
@code{n} – an integer (or @code{None})


Delete all or first/last `n' of turtle’s stamps.  If `n' is @code{None}, delete
all stamps, if `n' > 0 delete first `n' stamps, else if `n' < 0 delete
last `n' stamps.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle undo}@anchor{4699}
@deffn {Συνάρτηση} turtle.undo ()

Undo (repeatedly) the last turtle action(s).  Number of available
undo actions is determined by the size of the undobuffer.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle speed}@anchor{469a}
@deffn {Συνάρτηση} turtle.speed (speed=None)

@*Παράμετροι: 
@code{speed} – an integer in the range 0..10 or a speedstring (see below)


Set the turtle’s speed to an integer value in the range 0..10.  If no
argument is given, return current speed.

If input is a number greater than 10 or smaller than 0.5, speed is set
to 0.  Speedstrings are mapped to speedvalues as follows:


@itemize *

@item 
«fastest»:  0

@item 
«fast»:  10

@item 
«normal»:  6

@item 
«slow»:  3

@item 
«slowest»:  1
@end itemize

Speeds from 1 to 10 enforce increasingly faster animation of line drawing
and turtle turning.

Attention: `speed' = 0 means that `no' animation takes
place. forward/back makes turtle jump and likewise left/right make the
turtle turn instantly.

@example
>>> turtle.speed()
3
>>> turtle.speed('normal')
>>> turtle.speed()
6
>>> turtle.speed(9)
>>> turtle.speed()
9
@end example
@end deffn

@node Tell Turtle’s state,Settings for measurement,Turtle motion,Methods of RawTurtle/Turtle and corresponding functions
@anchor{library/turtle tell-turtle-s-state}@anchor{46f0}
@subsubsection Tell Turtle’s state


@geindex position() (στη μονάδα turtle)
@geindex pos() (στη μονάδα turtle)
@anchor{library/turtle turtle position}@anchor{469b}
@deffn {Συνάρτηση} turtle.position ()
@anchor{library/turtle turtle pos}@anchor{469c}
@deffnx {Συνάρτηση} turtle.pos ()

Return the turtle’s current location (x,y) (as a @ref{46ef,,Vec2D} vector).

@example
>>> turtle.pos()
(440.00,-0.00)
@end example
@end deffn

@geindex towards() (στη μονάδα turtle)
@anchor{library/turtle turtle towards}@anchor{469d}
@deffn {Συνάρτηση} turtle.towards (x, y=None)

@*Παράμετροι: 

@itemize *

@item 
@code{x} – a number or a pair/vector of numbers or a turtle instance

@item 
@code{y} – a number if `x' is a number, else @code{None}
@end itemize


Return the angle between the line from turtle position to position specified
by (x,y), the vector or the other turtle.  This depends on the turtle’s start
orientation which depends on the mode - «standard»/»world» or «logo».

@example
>>> turtle.goto(10, 10)
>>> turtle.towards(0,0)
225.0
@end example
@end deffn

@geindex xcor() (στη μονάδα turtle)
@anchor{library/turtle turtle xcor}@anchor{469e}
@deffn {Συνάρτηση} turtle.xcor ()

Return the turtle’s x coordinate.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle ycor}@anchor{469f}
@deffn {Συνάρτηση} turtle.ycor ()

Return the turtle’s y coordinate.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle heading}@anchor{46a0}
@deffn {Συνάρτηση} turtle.heading ()

Return the turtle’s current heading (value depends on the turtle mode, see
@ref{46e0,,mode()}).

@example
>>> turtle.home()
>>> turtle.left(67)
>>> turtle.heading()
67.0
@end example
@end deffn

@geindex distance() (στη μονάδα turtle)
@anchor{library/turtle turtle distance}@anchor{46a1}
@deffn {Συνάρτηση} turtle.distance (x, y=None)

@*Παράμετροι: 

@itemize *

@item 
@code{x} – a number or a pair/vector of numbers or a turtle instance

@item 
@code{y} – a number if `x' is a number, else @code{None}
@end itemize


Return the distance from the turtle to (x,y), the given vector, or the given
other turtle, in turtle step units.

@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 Settings for measurement,Pen control<2>,Tell Turtle’s state,Methods of RawTurtle/Turtle and corresponding functions
@anchor{library/turtle settings-for-measurement}@anchor{46f1}
@subsubsection Settings for measurement


@geindex degrees() (στη μονάδα turtle)
@anchor{library/turtle turtle degrees}@anchor{46a2}
@deffn {Συνάρτηση} turtle.degrees (fullcircle=360.0)

@*Παράμετροι: 
@code{fullcircle} – a number


Set angle measurement units, i.e. set number of «degrees» for a full circle.
Default value is 360 degrees.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle radians}@anchor{46a3}
@deffn {Συνάρτηση} turtle.radians ()

Set the angle measurement units to radians.  Equivalent to
@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 Pen control<2>,Turtle state,Settings for measurement,Methods of RawTurtle/Turtle and corresponding functions
@anchor{library/turtle id1}@anchor{46f2}
@subsubsection Pen control


@menu
* Drawing state:: 
* Color control:: 
* Filling:: 
* More drawing control:: 

@end menu

@node Drawing state,Color control,,Pen control<2>
@anchor{library/turtle drawing-state}@anchor{46f3}
@subsubsection Drawing state


@geindex pendown() (στη μονάδα turtle)
@geindex pd() (στη μονάδα turtle)
@geindex down() (στη μονάδα turtle)
@anchor{library/turtle turtle pendown}@anchor{46a4}
@deffn {Συνάρτηση} turtle.pendown ()
@anchor{library/turtle turtle pd}@anchor{46a5}
@deffnx {Συνάρτηση} turtle.pd ()
@anchor{library/turtle turtle down}@anchor{46a6}
@deffnx {Συνάρτηση} turtle.down ()

Pull the pen down – drawing when moving.
@end deffn

@geindex penup() (στη μονάδα turtle)
@geindex pu() (στη μονάδα turtle)
@geindex up() (στη μονάδα turtle)
@anchor{library/turtle turtle penup}@anchor{46a7}
@deffn {Συνάρτηση} turtle.penup ()
@anchor{library/turtle turtle pu}@anchor{46a8}
@deffnx {Συνάρτηση} turtle.pu ()
@anchor{library/turtle turtle up}@anchor{46a9}
@deffnx {Συνάρτηση} turtle.up ()

Pull the pen up – no drawing when moving.
@end deffn

@geindex pensize() (στη μονάδα turtle)
@geindex width() (στη μονάδα turtle)
@anchor{library/turtle turtle pensize}@anchor{46aa}
@deffn {Συνάρτηση} turtle.pensize (width=None)
@anchor{library/turtle turtle width}@anchor{46ab}
@deffnx {Συνάρτηση} turtle.width (width=None)

@*Παράμετροι: 
@code{width} – a positive number


Set the line thickness to `width' or return it.  If resizemode is set to
«auto» and turtleshape is a polygon, that polygon is drawn with the same line
thickness.  If no argument is given, the current pensize is returned.

@example
>>> turtle.pensize()
1
>>> turtle.pensize(10)   # from here on lines of width 10 are drawn
@end example
@end deffn

@geindex pen() (στη μονάδα turtle)
@anchor{library/turtle turtle pen}@anchor{46ac}
@deffn {Συνάρτηση} turtle.pen (pen=None, **pendict)

@*Παράμετροι: 

@itemize *

@item 
@code{pen} – a dictionary with some or all of the below listed keys

@item 
@code{pendict} – one or more keyword-arguments with the below listed keys as keywords
@end itemize


Return or set the pen’s attributes in a «pen-dictionary» with the following
key/value pairs:


@itemize *

@item 
«shown»: True/False

@item 
«pendown»: True/False

@item 
«pencolor»: color-string or color-tuple

@item 
«fillcolor»: color-string or color-tuple

@item 
«pensize»: positive number

@item 
«speed»: number in range 0..10

@item 
«resizemode»: «auto» or «user» or «noresize»

@item 
«stretchfactor»: (positive number, positive number)

@item 
«outline»: positive number

@item 
«tilt»: number
@end itemize

This dictionary can be used as argument for a subsequent call to @code{pen()}
to restore the former pen-state.  Moreover one or more of these attributes
can be provided as keyword-arguments.  This can be used to set several pen
attributes in one statement.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle isdown}@anchor{46ad}
@deffn {Συνάρτηση} turtle.isdown ()

Return @code{True} if pen is down, @code{False} if it’s up.

@example
>>> turtle.penup()
>>> turtle.isdown()
False
>>> turtle.pendown()
>>> turtle.isdown()
True
@end example
@end deffn

@node Color control,Filling,Drawing state,Pen control<2>
@anchor{library/turtle color-control}@anchor{46f4}
@subsubsection Color control


@geindex pencolor() (στη μονάδα turtle)
@anchor{library/turtle turtle pencolor}@anchor{46af}
@deffn {Συνάρτηση} turtle.pencolor ()

@deffnx {Συνάρτηση} turtle.pencolor (color, /)

@deffnx {Συνάρτηση} turtle.pencolor (r, g, b, /)

Return or set the pencolor.

Four input formats are allowed:


@table @asis

@item @code{pencolor()}

Return the current pencolor as color specification string or
as a tuple (see example).  May be used as input to another
color/pencolor/fillcolor/bgcolor call.

@item @code{pencolor(colorstring)}

Set pencolor to `colorstring', which is a Tk color specification string,
such as @code{"red"}, @code{"yellow"}, or @code{"#33cc8c"}.

@item @code{pencolor((r, g, b))}

Set pencolor to the RGB color represented by the tuple of `r', `g', and
`b'.  Each of `r', `g', and `b' must be in the range 0..colormode, where
colormode is either 1.0 or 255 (see @ref{46e1,,colormode()}).

@item @code{pencolor(r, g, b)}

Set pencolor to the RGB color represented by `r', `g', and `b'.  Each of
`r', `g', and `b' must be in the range 0..colormode.
@end table

If turtleshape is a polygon, the outline of that polygon is drawn with the
newly set pencolor.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle fillcolor}@anchor{46b0}
@deffn {Συνάρτηση} turtle.fillcolor ()

@deffnx {Συνάρτηση} turtle.fillcolor (color, /)

@deffnx {Συνάρτηση} turtle.fillcolor (r, g, b, /)

Return or set the fillcolor.

Four input formats are allowed:


@table @asis

@item @code{fillcolor()}

Return the current fillcolor as color specification string, possibly
in tuple format (see example).  May be used as input to another
color/pencolor/fillcolor/bgcolor call.

@item @code{fillcolor(colorstring)}

Set fillcolor to `colorstring', which is a Tk color specification string,
such as @code{"red"}, @code{"yellow"}, or @code{"#33cc8c"}.

@item @code{fillcolor((r, g, b))}

Set fillcolor to the RGB color represented by the tuple of `r', `g', and
`b'.  Each of `r', `g', and `b' must be in the range 0..colormode, where
colormode is either 1.0 or 255 (see @ref{46e1,,colormode()}).

@item @code{fillcolor(r, g, b)}

Set fillcolor to the RGB color represented by `r', `g', and `b'.  Each of
`r', `g', and `b' must be in the range 0..colormode.
@end table

If turtleshape is a polygon, the interior of that polygon is drawn
with the newly set fillcolor.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle color}@anchor{46ae}
@deffn {Συνάρτηση} turtle.color ()

@deffnx {Συνάρτηση} turtle.color (color, /)

@deffnx {Συνάρτηση} turtle.color (r, g, b, /)

@deffnx {Συνάρτηση} turtle.color (pencolor, fillcolor, /)

Return or set pencolor and fillcolor.

Several input formats are allowed.  They use 0 to 3 arguments as
follows:


@table @asis

@item @code{color()}

Return the current pencolor and the current fillcolor as a pair of color
specification strings or tuples as returned by @ref{46af,,pencolor()} and
@ref{46b0,,fillcolor()}.

@item @code{color(colorstring)}, @code{color((r,g,b))}, @code{color(r,g,b)}

Inputs as in @ref{46af,,pencolor()}, set both, fillcolor and pencolor, to the
given value.

@item @code{color(colorstring1, colorstring2)}, @code{color((r1,g1,b1), (r2,g2,b2))}

Equivalent to @code{pencolor(colorstring1)} and @code{fillcolor(colorstring2)}
and analogously if the other input format is used.
@end table

If turtleshape is a polygon, outline and interior of that polygon is drawn
with the newly set colors.

@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

See also: Screen method @ref{46e1,,colormode()}.

@node Filling,More drawing control,Color control,Pen control<2>
@anchor{library/turtle filling}@anchor{46f5}
@subsubsection Filling


@c >>> turtle.home()

@geindex filling() (στη μονάδα turtle)
@anchor{library/turtle turtle filling}@anchor{46b1}
@deffn {Συνάρτηση} turtle.filling ()

Return fillstate (@code{True} if filling, @code{False} else).

@example
>>> turtle.begin_fill()
>>> if turtle.filling():
...    turtle.pensize(5)
... else:
...    turtle.pensize(3)
@end example
@end deffn

@geindex fill() (στη μονάδα turtle)
@anchor{library/turtle turtle fill}@anchor{523}
@deffn {Συνάρτηση} turtle.fill ()

Fill the shape drawn in the @code{with turtle.fill():} block.

@example
>>> turtle.color("black", "red")
>>> with turtle.fill():
...     turtle.circle(80)
@end example

Using @code{fill()} is equivalent to adding the @ref{467b,,begin_fill()} before the
fill-block and @ref{467c,,end_fill()} after the fill-block:

@example
>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()
@end example


Added in version 3.14.

@end deffn

@geindex begin_fill() (στη μονάδα turtle)
@anchor{library/turtle turtle begin_fill}@anchor{467b}
@deffn {Συνάρτηση} turtle.begin_fill ()

To be called just before drawing a shape to be filled.
@end deffn

@geindex end_fill() (στη μονάδα turtle)
@anchor{library/turtle turtle end_fill}@anchor{467c}
@deffn {Συνάρτηση} turtle.end_fill ()

Fill the shape drawn after the last call to @ref{467b,,begin_fill()}.

Whether or not overlap regions for self-intersecting polygons
or multiple shapes are filled depends on the operating system graphics,
type of overlap, and number of overlaps.  For example, the Turtle star
above may be either all yellow or have some white regions.

@example
>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()
@end example
@end deffn

@node More drawing control,,Filling,Pen control<2>
@anchor{library/turtle more-drawing-control}@anchor{46f6}
@subsubsection More drawing control


@geindex reset() (στη μονάδα turtle)
@anchor{library/turtle turtle reset}@anchor{46b2}
@deffn {Συνάρτηση} turtle.reset ()

Delete the turtle’s drawings from the screen, re-center the turtle and set
variables to the default values.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle clear}@anchor{46b3}
@deffn {Συνάρτηση} turtle.clear ()

Delete the turtle’s drawings from the screen.  Do not move turtle.  State and
position of the turtle as well as drawings of other turtles are not affected.
@end deffn

@geindex write() (στη μονάδα turtle)
@anchor{library/turtle turtle write}@anchor{46b4}
@deffn {Συνάρτηση} turtle.write (arg, move=False, align='left', font=('Arial', 8, 'normal'))

@*Παράμετροι: 

@itemize *

@item 
@code{arg} – object to be written to the TurtleScreen

@item 
@code{move} – True/False

@item 
@code{align} – one of the strings «left», «center» or right»

@item 
@code{font} – a triple (fontname, fontsize, fonttype)
@end itemize


Write text - the string representation of `arg' - at the current turtle
position according to `align' («left», «center» or «right») and with the given
font.  If `move' is true, the pen is moved to the bottom-right corner of the
text.  By default, `move' is @code{False}.

@example
>>> turtle.write("Home = ", True, align="center")
>>> turtle.write((0,0), True)
@end example
@end deffn

@node Turtle state,Using events,Pen control<2>,Methods of RawTurtle/Turtle and corresponding functions
@anchor{library/turtle turtle-state}@anchor{46f7}
@subsubsection Turtle state


@menu
* Visibility:: 
* Appearance:: 

@end menu

@node Visibility,Appearance,,Turtle state
@anchor{library/turtle visibility}@anchor{46f8}
@subsubsection Visibility


@geindex hideturtle() (στη μονάδα turtle)
@geindex ht() (στη μονάδα turtle)
@anchor{library/turtle turtle hideturtle}@anchor{46b7}
@deffn {Συνάρτηση} turtle.hideturtle ()
@anchor{library/turtle turtle ht}@anchor{46b8}
@deffnx {Συνάρτηση} turtle.ht ()

Make the turtle invisible.  It’s a good idea to do this while you’re in the
middle of doing some complex drawing, because hiding the turtle speeds up the
drawing observably.

@example
>>> turtle.hideturtle()
@end example
@end deffn

@geindex showturtle() (στη μονάδα turtle)
@geindex st() (στη μονάδα turtle)
@anchor{library/turtle turtle showturtle}@anchor{46b5}
@deffn {Συνάρτηση} turtle.showturtle ()
@anchor{library/turtle turtle st}@anchor{46b6}
@deffnx {Συνάρτηση} turtle.st ()

Make the turtle visible.

@example
>>> turtle.showturtle()
@end example
@end deffn

@geindex isvisible() (στη μονάδα turtle)
@anchor{library/turtle turtle isvisible}@anchor{46b9}
@deffn {Συνάρτηση} turtle.isvisible ()

Return @code{True} if the Turtle is shown, @code{False} if it’s hidden.

@example
>>> turtle.hideturtle()
>>> turtle.isvisible()
False
>>> turtle.showturtle()
>>> turtle.isvisible()
True
@end example
@end deffn

@node Appearance,,Visibility,Turtle state
@anchor{library/turtle appearance}@anchor{46f9}
@subsubsection Appearance


@geindex shape() (στη μονάδα turtle)
@anchor{library/turtle turtle shape}@anchor{46ba}
@deffn {Συνάρτηση} turtle.shape (name=None)

@*Παράμετροι: 
@code{name} – a string which is a valid shapename


Set turtle shape to shape with given `name' or, if name is not given, return
name of current shape.  Shape with `name' must exist in the TurtleScreen’s
shape dictionary.  Initially there are the following polygon shapes: «arrow»,
«turtle», «circle», «square», «triangle», «classic».  To learn about how to
deal with shapes see Screen method @ref{46e4,,register_shape()}.

@example
>>> turtle.shape()
'classic'
>>> turtle.shape("turtle")
>>> turtle.shape()
'turtle'
@end example
@end deffn

@geindex resizemode() (στη μονάδα turtle)
@anchor{library/turtle turtle resizemode}@anchor{46bb}
@deffn {Συνάρτηση} turtle.resizemode (rmode=None)

@*Παράμετροι: 
@code{rmode} – one of the strings «auto», «user», «noresize»


Set resizemode to one of the values: «auto», «user», «noresize».  If `rmode'
is not given, return current resizemode.  Different resizemodes have the
following effects:


@itemize -

@item 
«auto»: adapts the appearance of the turtle corresponding to the value of pensize.

@item 
«user»: adapts the appearance of the turtle according to the values of
stretchfactor and outlinewidth (outline), which are set by
@ref{46bc,,shapesize()}.

@item 
«noresize»: no adaption of the turtle’s appearance takes place.
@end itemize

@code{resizemode("user")} is called by @ref{46bc,,shapesize()} when used with arguments.

@example
>>> turtle.resizemode()
'noresize'
>>> turtle.resizemode("auto")
>>> turtle.resizemode()
'auto'
@end example
@end deffn

@geindex shapesize() (στη μονάδα turtle)
@geindex turtlesize() (στη μονάδα turtle)
@anchor{library/turtle turtle shapesize}@anchor{46bc}
@deffn {Συνάρτηση} turtle.shapesize (stretch_wid=None, stretch_len=None, outline=None)
@anchor{library/turtle turtle turtlesize}@anchor{46bd}
@deffnx {Συνάρτηση} turtle.turtlesize (stretch_wid=None, stretch_len=None, outline=None)

@*Παράμετροι: 

@itemize *

@item 
@code{stretch_wid} – positive number

@item 
@code{stretch_len} – positive number

@item 
@code{outline} – positive number
@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() (στη μονάδα turtle)
@anchor{library/turtle turtle shearfactor}@anchor{46be}
@deffn {Συνάρτηση} turtle.shearfactor (shear=None)

@*Παράμετροι: 
@code{shear} – number (optional)


Set or return the current shearfactor. Shear the turtleshape according to
the given shearfactor shear, which is the tangent of the shear angle.
Do `not' change the turtle’s heading (direction of movement).
If shear is not given: return the current shearfactor, i. e. the
tangent of the shear angle, by which lines parallel to the
heading of the turtle are sheared.

@example
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.shearfactor(0.5)
>>> turtle.shearfactor()
0.5
@end example
@end deffn

@geindex tilt() (στη μονάδα turtle)
@anchor{library/turtle turtle tilt}@anchor{46bf}
@deffn {Συνάρτηση} turtle.tilt (angle)

@*Παράμετροι: 
@code{angle} – a number


Rotate the turtleshape by `angle' from its current tilt-angle, but do `not'
change the turtle’s heading (direction of movement).

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle tiltangle}@anchor{b0d}
@deffn {Συνάρτηση} turtle.tiltangle (angle=None)

@*Παράμετροι: 
@code{angle} – a number (optional)


Set or return the current tilt-angle. If angle is given, rotate the
turtleshape to point in the direction specified by angle,
regardless of its current tilt-angle. Do `not' change the turtle’s
heading (direction of movement).
If angle is not given: return the current tilt-angle, i. e. the angle
between the orientation of the turtleshape and the heading of the
turtle (its direction of movement).

@example
>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(45)
>>> turtle.tiltangle()
45.0
@end example
@end deffn

@geindex shapetransform() (στη μονάδα turtle)
@anchor{library/turtle turtle shapetransform}@anchor{46c0}
@deffn {Συνάρτηση} turtle.shapetransform (t11=None, t12=None, t21=None, t22=None)

@*Παράμετροι: 

@itemize *

@item 
@code{t11} – a number (optional)

@item 
@code{t12} – a number (optional)

@item 
@code{t21} – a number (optional)

@item 
@code{t12} – a number (optional)
@end itemize


Set or return the current transformation matrix of the turtle shape.

If none of the matrix elements are given, return the transformation
matrix as a tuple of 4 elements.
Otherwise set the given elements and transform the turtleshape
according to the matrix consisting of first row t11, t12 and
second row t21, t22. The determinant t11 * t22 - t12 * t21 must not be
zero, otherwise an error is raised.
Modify stretchfactor, shearfactor and tiltangle according to the
given matrix.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle get_shapepoly}@anchor{46c1}
@deffn {Συνάρτηση} turtle.get_shapepoly ()

Return the current shape polygon as tuple of coordinate pairs. This
can be used to define a new shape or components of a compound shape.

@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 Using events,Special Turtle methods,Turtle state,Methods of RawTurtle/Turtle and corresponding functions
@anchor{library/turtle using-events}@anchor{46fa}
@subsubsection Using events



@deffn {Συνάρτηση} turtle.onclick (fun, btn=1, add=None)

@*Παράμετροι: 

@itemize *

@item 
@code{fun} – a function with two arguments which will be called with the
coordinates of the clicked point on the canvas

@item 
@code{btn} – number of the mouse-button, defaults to 1 (left mouse button)

@item 
@code{add} – @code{True} or @code{False} – if @code{True}, a new binding will be
added, otherwise it will replace a former binding
@end itemize


Bind `fun' to mouse-click events on this turtle.  If `fun' is @code{None},
existing bindings are removed.  Example for the anonymous turtle, i.e. the
procedural way:

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle onrelease}@anchor{46c3}
@deffn {Συνάρτηση} turtle.onrelease (fun, btn=1, add=None)

@*Παράμετροι: 

@itemize *

@item 
@code{fun} – a function with two arguments which will be called with the
coordinates of the clicked point on the canvas

@item 
@code{btn} – number of the mouse-button, defaults to 1 (left mouse button)

@item 
@code{add} – @code{True} or @code{False} – if @code{True}, a new binding will be
added, otherwise it will replace a former binding
@end itemize


Bind `fun' to mouse-button-release events on this turtle.  If `fun' is
@code{None}, existing bindings are removed.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle ondrag}@anchor{46c4}
@deffn {Συνάρτηση} turtle.ondrag (fun, btn=1, add=None)

@*Παράμετροι: 

@itemize *

@item 
@code{fun} – a function with two arguments which will be called with the
coordinates of the clicked point on the canvas

@item 
@code{btn} – number of the mouse-button, defaults to 1 (left mouse button)

@item 
@code{add} – @code{True} or @code{False} – if @code{True}, a new binding will be
added, otherwise it will replace a former binding
@end itemize


Bind `fun' to mouse-move events on this turtle.  If `fun' is @code{None},
existing bindings are removed.

Remark: Every sequence of mouse-move-events on a turtle is preceded by a
mouse-click event on that turtle.

@example
>>> turtle.ondrag(turtle.goto)
@end example

Subsequently, clicking and dragging the Turtle will move it across
the screen thereby producing handdrawings (if pen is down).
@end deffn

@node Special Turtle methods,Compound shapes,Using events,Methods of RawTurtle/Turtle and corresponding functions
@anchor{library/turtle special-turtle-methods}@anchor{46fb}
@subsubsection Special Turtle methods


@geindex poly() (στη μονάδα turtle)
@anchor{library/turtle turtle poly}@anchor{524}
@deffn {Συνάρτηση} turtle.poly ()

Record the vertices of a polygon drawn in the @code{with turtle.poly():} block.
The first and last vertices will be connected.

@example
>>> with turtle.poly():
...     turtle.forward(100)
...     turtle.right(60)
...     turtle.forward(100)
@end example


Added in version 3.14.

@end deffn

@geindex begin_poly() (στη μονάδα turtle)
@anchor{library/turtle turtle begin_poly}@anchor{46c5}
@deffn {Συνάρτηση} turtle.begin_poly ()

Start recording the vertices of a polygon.  Current turtle position is first
vertex of polygon.
@end deffn

@geindex end_poly() (στη μονάδα turtle)
@anchor{library/turtle turtle end_poly}@anchor{46c6}
@deffn {Συνάρτηση} turtle.end_poly ()

Stop recording the vertices of a polygon.  Current turtle position is last
vertex of polygon.  This will be connected with the first vertex.
@end deffn

@geindex get_poly() (στη μονάδα turtle)
@anchor{library/turtle turtle get_poly}@anchor{46c7}
@deffn {Συνάρτηση} turtle.get_poly ()

Return the last recorded polygon.

@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() (στη μονάδα turtle)
@anchor{library/turtle turtle clone}@anchor{46c8}
@deffn {Συνάρτηση} turtle.clone ()

Create and return a clone of the turtle with same position, heading and
turtle properties.

@example
>>> mick = Turtle()
>>> joe = mick.clone()
@end example
@end deffn

@geindex getturtle() (στη μονάδα turtle)
@geindex getpen() (στη μονάδα turtle)
@anchor{library/turtle turtle getturtle}@anchor{46c9}
@deffn {Συνάρτηση} turtle.getturtle ()
@anchor{library/turtle turtle getpen}@anchor{46ca}
@deffnx {Συνάρτηση} turtle.getpen ()

Return the Turtle object itself.  Only reasonable use: as a function to
return the «anonymous turtle»:

@example
>>> pet = getturtle()
>>> pet.fd(50)
>>> pet
<turtle.Turtle object at 0x...>
@end example
@end deffn

@geindex getscreen() (στη μονάδα turtle)
@anchor{library/turtle turtle getscreen}@anchor{46cb}
@deffn {Συνάρτηση} turtle.getscreen ()

Return the @ref{46fc,,TurtleScreen} object the turtle is drawing on.
TurtleScreen methods can then be called for that object.

@example
>>> ts = turtle.getscreen()
>>> ts
<turtle._Screen object at 0x...>
>>> ts.bgcolor("pink")
@end example
@end deffn

@geindex setundobuffer() (στη μονάδα turtle)
@anchor{library/turtle turtle setundobuffer}@anchor{46cc}
@deffn {Συνάρτηση} turtle.setundobuffer (size)

@*Παράμετροι: 
@code{size} – an integer or @code{None}


Set or disable undobuffer.  If `size' is an integer, an empty undobuffer of
given size is installed.  `size' gives the maximum number of turtle actions
that can be undone by the @ref{4699,,undo()} method/function.  If `size' is
@code{None}, the undobuffer is disabled.

@example
>>> turtle.setundobuffer(42)
@end example
@end deffn

@geindex undobufferentries() (στη μονάδα turtle)
@anchor{library/turtle turtle undobufferentries}@anchor{46cd}
@deffn {Συνάρτηση} turtle.undobufferentries ()

Return number of entries in the undobuffer.

@example
>>> while undobufferentries():
...     undo()
@end example
@end deffn

@node Compound shapes,,Special Turtle methods,Methods of RawTurtle/Turtle and corresponding functions
@anchor{library/turtle compound-shapes}@anchor{46fd}@anchor{library/turtle compoundshapes}@anchor{46fe}
@subsubsection Compound shapes


To use compound turtle shapes, which consist of several polygons of different
color, you must use the helper class @ref{46ff,,Shape} explicitly as described
below:


@enumerate 

@item 
Create an empty Shape object of type «compound».

@item 
Add as many components to this object as desired, using the
@ref{4700,,addcomponent()} method.

For example:

@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 
Now add the Shape to the Screen’s shapelist and use it:

@example
>>> register_shape("myshape", s)
>>> shape("myshape")
@end example
@end enumerate

@cartouche
@quotation Σημείωση 
The @ref{46ff,,Shape} class is used internally by the @ref{46e4,,register_shape()}
method in different ways.  The application programmer has to deal with the
Shape class `only' when using compound shapes like shown above!
@end quotation
@end cartouche

@node Methods of TurtleScreen/Screen and corresponding functions,Public classes,Methods of RawTurtle/Turtle and corresponding functions,turtle — Turtle graphics
@anchor{library/turtle methods-of-turtlescreen-screen-and-corresponding-functions}@anchor{4701}
@subsubsection Methods of TurtleScreen/Screen and corresponding functions


Most of the examples in this section refer to a TurtleScreen instance called
@code{screen}.

@c >>> screen = Screen()

@menu
* Window control:: 
* Animation control:: 
* Using screen events:: 
* Input methods:: 
* Settings and special methods:: 
* Methods specific to Screen@comma{} not inherited from TurtleScreen: Methods specific to Screen not inherited from TurtleScreen. 

@end menu

@node Window control,Animation control,,Methods of TurtleScreen/Screen and corresponding functions
@anchor{library/turtle window-control}@anchor{4702}
@subsubsection Window control


@geindex bgcolor() (στη μονάδα turtle)
@anchor{library/turtle turtle bgcolor}@anchor{46cf}
@deffn {Συνάρτηση} turtle.bgcolor ()

@deffnx {Συνάρτηση} turtle.bgcolor (color, /)

@deffnx {Συνάρτηση} turtle.bgcolor (r, g, b, /)

Return or set the background color of the TurtleScreen.

Four input formats are allowed:


@table @asis

@item @code{bgcolor()}

Return the current background color as color specification string or
as a tuple (see example).  May be used as input to another
color/pencolor/fillcolor/bgcolor call.

@item @code{bgcolor(colorstring)}

Set the background color to `colorstring', which is a Tk color
specification string, such as @code{"red"}, @code{"yellow"}, or @code{"#33cc8c"}.

@item @code{bgcolor((r, g, b))}

Set the background color to the RGB color represented by the tuple of
`r', `g', and `b'.
Each of `r', `g', and `b' must be in the range 0..colormode, where
colormode is either 1.0 or 255 (see @ref{46e1,,colormode()}).

@item @code{bgcolor(r, g, b)}

Set the background color to the RGB color represented by `r', `g', and `b'.  Each of
`r', `g', and `b' must be in the range 0..colormode.
@end table

@example
>>> screen.bgcolor("orange")
>>> screen.bgcolor()
'orange'
>>> screen.bgcolor("#800080")
>>> screen.bgcolor()
(128.0, 0.0, 128.0)
@end example
@end deffn

@geindex bgpic() (στη μονάδα turtle)
@anchor{library/turtle turtle bgpic}@anchor{46d0}
@deffn {Συνάρτηση} turtle.bgpic (picname=None)

@*Παράμετροι: 
@code{picname} – a string, name of an image file (PNG, GIF, PGM, and PPM)
or @code{"nopic"}, or @code{None}


Set background image or return name of current backgroundimage.  If `picname'
is a filename, set the corresponding image as background.  If `picname' is
@code{"nopic"}, delete background image, if present.  If `picname' is @code{None},
return the filename of the current backgroundimage.

@example
>>> screen.bgpic()
'nopic'
>>> screen.bgpic("landscape.gif")
>>> screen.bgpic()
"landscape.gif"
@end example
@end deffn


@deffn {Συνάρτηση} turtle.clear ()

@cartouche
@quotation Σημείωση 
This TurtleScreen method is available as a global function only under the
name @code{clearscreen}.  The global function @code{clear} is a different one
derived from the Turtle method @code{clear}.
@end quotation
@end cartouche
@end deffn

@geindex clearscreen() (στη μονάδα turtle)
@anchor{library/turtle turtle clearscreen}@anchor{46d1}
@deffn {Συνάρτηση} turtle.clearscreen ()

Delete all drawings and all turtles from the TurtleScreen.  Reset the now
empty TurtleScreen to its initial state: white background, no background
image, no event bindings and tracing on.
@end deffn


@deffn {Συνάρτηση} turtle.reset ()

@cartouche
@quotation Σημείωση 
This TurtleScreen method is available as a global function only under the
name @code{resetscreen}.  The global function @code{reset} is another one
derived from the Turtle method @code{reset}.
@end quotation
@end cartouche
@end deffn

@geindex resetscreen() (στη μονάδα turtle)
@anchor{library/turtle turtle resetscreen}@anchor{46d2}
@deffn {Συνάρτηση} turtle.resetscreen ()

Reset all Turtles on the Screen to their initial state.
@end deffn

@geindex screensize() (στη μονάδα turtle)
@anchor{library/turtle turtle screensize}@anchor{46d3}
@deffn {Συνάρτηση} turtle.screensize (canvwidth=None, canvheight=None, bg=None)

@*Παράμετροι: 

@itemize *

@item 
@code{canvwidth} – positive integer, new width of canvas in pixels

@item 
@code{canvheight} – positive integer, new height of canvas in pixels

@item 
@code{bg} – colorstring or color-tuple, new background color
@end itemize


If no arguments are given, return current (canvaswidth, canvasheight).  Else
resize the canvas the turtles are drawing on.  Do not alter the drawing
window.  To observe hidden parts of the canvas, use the scrollbars. With this
method, one can make visible those parts of a drawing which were outside the
canvas before.

@example
>>> screen.screensize()
(400, 300)
>>> screen.screensize(2000,1500)
>>> screen.screensize()
(2000, 1500)
@end example

e.g. to search for an erroneously escaped turtle ;-)
@end deffn

@geindex setworldcoordinates() (στη μονάδα turtle)
@anchor{library/turtle turtle setworldcoordinates}@anchor{46d4}
@deffn {Συνάρτηση} turtle.setworldcoordinates (llx, lly, urx, ury)

@*Παράμετροι: 

@itemize *

@item 
@code{llx} – a number, x-coordinate of lower left corner of canvas

@item 
@code{lly} – a number, y-coordinate of lower left corner of canvas

@item 
@code{urx} – a number, x-coordinate of upper right corner of canvas

@item 
@code{ury} – a number, y-coordinate of upper right corner of canvas
@end itemize


Set up user-defined coordinate system and switch to mode «world» if
necessary.  This performs a @code{screen.reset()}.  If mode «world» is already
active, all drawings are redrawn according to the new coordinates.

`ATTENTION': in user-defined coordinate systems angles may appear
distorted.

@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 Animation control,Using screen events,Window control,Methods of TurtleScreen/Screen and corresponding functions
@anchor{library/turtle animation-control}@anchor{4703}
@subsubsection Animation control


@geindex no_animation() (στη μονάδα turtle)
@anchor{library/turtle turtle no_animation}@anchor{525}
@deffn {Συνάρτηση} turtle.no_animation ()

Temporarily disable turtle animation. The code written inside the
@code{no_animation} block will not be animated;
once the code block is exited, the drawing will appear.

@example
>>> with screen.no_animation():
...     for dist in range(2, 400, 2):
...         fd(dist)
...         rt(90)
@end example


Added in version 3.14.

@end deffn

@geindex delay() (στη μονάδα turtle)
@anchor{library/turtle turtle delay}@anchor{46d5}
@deffn {Συνάρτηση} turtle.delay (delay=None)

@*Παράμετροι: 
@code{delay} – positive integer


Set or return the drawing `delay' in milliseconds.  (This is approximately
the time interval between two consecutive canvas updates.)  The longer the
drawing delay, the slower the animation.

Optional argument:

@example
>>> screen.delay()
10
>>> screen.delay(5)
>>> screen.delay()
5
@end example
@end deffn

@geindex tracer() (στη μονάδα turtle)
@anchor{library/turtle turtle tracer}@anchor{46d6}
@deffn {Συνάρτηση} turtle.tracer (n=None, delay=None)

@*Παράμετροι: 

@itemize *

@item 
@code{n} – nonnegative integer

@item 
@code{delay} – nonnegative integer
@end itemize


Turn turtle animation on/off and set delay for update drawings.  If
`n' is given, only each n-th regular screen update is really
performed.  (Can be used to accelerate the drawing of complex
graphics.)  When called without arguments, returns the currently
stored value of n. Second argument sets delay value (see
@ref{46d5,,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() (στη μονάδα turtle)
@anchor{library/turtle turtle update}@anchor{46d7}
@deffn {Συνάρτηση} turtle.update ()

Perform a TurtleScreen update. To be used when tracer is turned off.
@end deffn

See also the RawTurtle/Turtle method @ref{469a,,speed()}.

@node Using screen events,Input methods,Animation control,Methods of TurtleScreen/Screen and corresponding functions
@anchor{library/turtle using-screen-events}@anchor{4704}
@subsubsection Using screen events


@geindex listen() (στη μονάδα turtle)
@anchor{library/turtle turtle listen}@anchor{46d8}
@deffn {Συνάρτηση} turtle.listen (xdummy=None, ydummy=None)

Set focus on TurtleScreen (in order to collect key-events).  Dummy arguments
are provided in order to be able to pass @code{listen()} to the onclick method.
@end deffn

@geindex onkey() (στη μονάδα turtle)
@geindex onkeyrelease() (στη μονάδα turtle)
@anchor{library/turtle turtle onkey}@anchor{46d9}
@deffn {Συνάρτηση} turtle.onkey (fun, key)
@anchor{library/turtle turtle onkeyrelease}@anchor{46da}
@deffnx {Συνάρτηση} turtle.onkeyrelease (fun, key)

@*Παράμετροι: 

@itemize *

@item 
@code{fun} – a function with no arguments or @code{None}

@item 
@code{key} – a string: key (e.g. «a») or key-symbol (e.g. «space»)
@end itemize


Bind `fun' to key-release event of key.  If `fun' is @code{None}, event bindings
are removed. Remark: in order to be able to register key-events, TurtleScreen
must have the focus. (See method @ref{46d8,,listen()}.)

@example
>>> def f():
...     fd(50)
...     lt(60)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()
@end example
@end deffn

@geindex onkeypress() (στη μονάδα turtle)
@anchor{library/turtle turtle onkeypress}@anchor{46db}
@deffn {Συνάρτηση} turtle.onkeypress (fun, key=None)

@*Παράμετροι: 

@itemize *

@item 
@code{fun} – a function with no arguments or @code{None}

@item 
@code{key} – a string: key (e.g. «a») or key-symbol (e.g. «space»)
@end itemize


Bind `fun' to key-press event of key if key is given,
or to any key-press-event if no key is given.
Remark: in order to be able to register key-events, TurtleScreen
must have focus. (See method @ref{46d8,,listen()}.)

@example
>>> def f():
...     fd(50)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()
@end example
@end deffn

@geindex onclick() (στη μονάδα turtle)
@geindex onscreenclick() (στη μονάδα turtle)
@anchor{library/turtle turtle onclick}@anchor{46c2}
@deffn {Συνάρτηση} turtle.onclick (fun, btn=1, add=None)
@anchor{library/turtle turtle onscreenclick}@anchor{46dc}
@deffnx {Συνάρτηση} turtle.onscreenclick (fun, btn=1, add=None)

@*Παράμετροι: 

@itemize *

@item 
@code{fun} – a function with two arguments which will be called with the
coordinates of the clicked point on the canvas

@item 
@code{btn} – number of the mouse-button, defaults to 1 (left mouse button)

@item 
@code{add} – @code{True} or @code{False} – if @code{True}, a new binding will be
added, otherwise it will replace a former binding
@end itemize


Bind `fun' to mouse-click events on this screen.  If `fun' is @code{None},
existing bindings are removed.

Example for a TurtleScreen instance named @code{screen} and a Turtle instance
named @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 Σημείωση 
This TurtleScreen method is available as a global function only under the
name @code{onscreenclick}.  The global function @code{onclick} is another one
derived from the Turtle method @code{onclick}.
@end quotation
@end cartouche
@end deffn

@geindex ontimer() (στη μονάδα turtle)
@anchor{library/turtle turtle ontimer}@anchor{46dd}
@deffn {Συνάρτηση} turtle.ontimer (fun, t=0)

@*Παράμετροι: 

@itemize *

@item 
@code{fun} – a function with no arguments

@item 
@code{t} – a number >= 0
@end itemize


Install a timer that calls `fun' after `t' milliseconds.

@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() (στη μονάδα turtle)
@geindex done() (στη μονάδα turtle)
@anchor{library/turtle turtle mainloop}@anchor{46de}
@deffn {Συνάρτηση} turtle.mainloop ()
@anchor{library/turtle turtle done}@anchor{46df}
@deffnx {Συνάρτηση} turtle.done ()

Starts event loop - calling Tkinter’s mainloop function.
Must be the last statement in a turtle graphics program.
Must `not' be used if a script is run from within IDLE in -n mode
(No subprocess) - for interactive use of turtle graphics.

@example
>>> screen.mainloop()
@end example
@end deffn

@node Input methods,Settings and special methods,Using screen events,Methods of TurtleScreen/Screen and corresponding functions
@anchor{library/turtle input-methods}@anchor{4705}
@subsubsection Input methods


@geindex textinput() (στη μονάδα turtle)
@anchor{library/turtle turtle textinput}@anchor{1e71}
@deffn {Συνάρτηση} turtle.textinput (title, prompt)

@*Παράμετροι: 

@itemize *

@item 
@code{title} – string

@item 
@code{prompt} – string
@end itemize


Pop up a dialog window for input of a string. Parameter title is
the title of the dialog window, prompt is a text mostly describing
what information to input.
Return the string input. If the dialog is canceled, return @code{None}.

@example
>>> screen.textinput("NIM", "Name of first player:")
@end example
@end deffn

@geindex numinput() (στη μονάδα turtle)
@anchor{library/turtle turtle numinput}@anchor{1e72}
@deffn {Συνάρτηση} turtle.numinput (title, prompt, default=None, minval=None, maxval=None)

@*Παράμετροι: 

@itemize *

@item 
@code{title} – string

@item 
@code{prompt} – string

@item 
@code{default} – number (optional)

@item 
@code{minval} – number (optional)

@item 
@code{maxval} – number (optional)
@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 Settings and special methods,Methods specific to Screen not inherited from TurtleScreen,Input methods,Methods of TurtleScreen/Screen and corresponding functions
@anchor{library/turtle settings-and-special-methods}@anchor{4706}
@subsubsection Settings and special methods


@geindex mode() (στη μονάδα turtle)
@anchor{library/turtle turtle mode}@anchor{46e0}
@deffn {Συνάρτηση} turtle.mode (mode=None)

@*Παράμετροι: 
@code{mode} – one of the strings «standard», «logo» or «world»


Set turtle mode («standard», «logo» or «world») and perform reset.  If mode
is not given, current mode is returned.

Mode «standard» is compatible with old @code{turtle}.  Mode «logo» is
compatible with most Logo turtle graphics.  Mode «world» uses user-defined
«world coordinates». `Attention': in this mode angles appear distorted if
@code{x/y} unit-ratio doesn’t equal 1.


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 
@headitem

Mode

@tab

Initial turtle heading

@tab

positive angles

@item

«standard»

@tab

to the right (east)

@tab

counterclockwise

@item

«logo»

@tab

upward    (north)

@tab

clockwise

@end multitable


@example
>>> mode("logo")   # resets turtle heading to north
>>> mode()
'logo'
@end example
@end deffn

@geindex colormode() (στη μονάδα turtle)
@anchor{library/turtle turtle colormode}@anchor{46e1}
@deffn {Συνάρτηση} turtle.colormode (cmode=None)

@*Παράμετροι: 
@code{cmode} – one of the values 1.0 or 255


Return the colormode or set it to 1.0 or 255.  Subsequently `r', `g', `b'
values of color triples have to be in the range 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() (στη μονάδα turtle)
@anchor{library/turtle turtle getcanvas}@anchor{46e2}
@deffn {Συνάρτηση} turtle.getcanvas ()

Return the Canvas of this TurtleScreen.  Useful for insiders who know what to
do with a Tkinter Canvas.

@example
>>> cv = screen.getcanvas()
>>> cv
<turtle.ScrolledCanvas object ...>
@end example
@end deffn

@geindex getshapes() (στη μονάδα turtle)
@anchor{library/turtle turtle getshapes}@anchor{46e3}
@deffn {Συνάρτηση} turtle.getshapes ()

Return a list of names of all currently available turtle shapes.

@example
>>> screen.getshapes()
['arrow', 'blank', 'circle', ..., 'turtle']
@end example
@end deffn

@geindex register_shape() (στη μονάδα turtle)
@geindex addshape() (στη μονάδα turtle)
@anchor{library/turtle turtle register_shape}@anchor{46e4}
@deffn {Συνάρτηση} turtle.register_shape (name, shape=None)
@anchor{library/turtle turtle addshape}@anchor{46e5}
@deffnx {Συνάρτηση} turtle.addshape (name, shape=None)

There are four different ways to call this function:


@enumerate 

@item 
`name' is the name of an image file (PNG, GIF, PGM, and PPM) and `shape' is @code{None}: Install the
corresponding image shape.

@example
>>> screen.register_shape("turtle.gif")
@end example

@cartouche
@quotation Σημείωση 
Image shapes `do not' rotate when turning the turtle, so they do not
display the heading of the turtle!
@end quotation
@end cartouche

@item 
`name' is an arbitrary string and `shape' is the name of an image file (PNG, GIF, PGM, and PPM): Install the
corresponding image shape.

@example
>>> screen.register_shape("turtle", "turtle.gif")
@end example

@cartouche
@quotation Σημείωση 
Image shapes `do not' rotate when turning the turtle, so they do not
display the heading of the turtle!
@end quotation
@end cartouche

@item 
`name' is an arbitrary string and `shape' is a tuple of pairs of
coordinates: Install the corresponding polygon shape.

@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{46ff,,Shape}
object: Install the corresponding compound shape.
@end enumerate

Add a turtle shape to TurtleScreen’s shapelist.  Only thusly registered
shapes can be used by issuing the command @code{shape(shapename)}.


Άλλαξε στην έκδοση 3.14: Added support for PNG, PGM, and PPM image formats.
Both a shape name and an image file name can be specified.

@end deffn

@geindex turtles() (στη μονάδα turtle)
@anchor{library/turtle turtle turtles}@anchor{46e6}
@deffn {Συνάρτηση} turtle.turtles ()

Return the list of turtles on the screen.

@example
>>> for turtle in screen.turtles():
...     turtle.color("red")
@end example
@end deffn

@geindex window_height() (στη μονάδα turtle)
@anchor{library/turtle turtle window_height}@anchor{46e7}
@deffn {Συνάρτηση} turtle.window_height ()

Return the height of the turtle window.

@example
>>> screen.window_height()
480
@end example
@end deffn

@geindex window_width() (στη μονάδα turtle)
@anchor{library/turtle turtle window_width}@anchor{46e8}
@deffn {Συνάρτηση} turtle.window_width ()

Return the width of the turtle window.

@example
>>> screen.window_width()
640
@end example
@end deffn

@node Methods specific to Screen not inherited from TurtleScreen,,Settings and special methods,Methods of TurtleScreen/Screen and corresponding functions
@anchor{library/turtle methods-specific-to-screen-not-inherited-from-turtlescreen}@anchor{4707}@anchor{library/turtle screenspecific}@anchor{4708}
@subsubsection Methods specific to Screen, not inherited from TurtleScreen


@geindex bye() (στη μονάδα turtle)
@anchor{library/turtle turtle bye}@anchor{46e9}
@deffn {Συνάρτηση} turtle.bye ()

Shut the turtlegraphics window.
@end deffn

@geindex exitonclick() (στη μονάδα turtle)
@anchor{library/turtle turtle exitonclick}@anchor{46ea}
@deffn {Συνάρτηση} turtle.exitonclick ()

Bind @code{bye()} method to mouse clicks on the Screen.

If the value «using_IDLE» in the configuration dictionary is @code{False}
(default value), also enter mainloop.  Remark: If IDLE with the @code{-n} switch
(no subprocess) is used, this value should be set to @code{True} in
@code{turtle.cfg}.  In this case IDLE’s own mainloop is active also for the
client script.
@end deffn

@geindex save() (στη μονάδα turtle)
@anchor{library/turtle turtle save}@anchor{1b83}
@deffn {Συνάρτηση} turtle.save (filename, overwrite=False)

Save the current turtle drawing (and turtles) as a PostScript file.

@*Παράμετροι: 

@itemize *

@item 
@code{filename} – the path of the saved PostScript file

@item 
@code{overwrite} – if @code{False} and there already exists a file with the given
filename, then the function will raise a
@code{FileExistsError}. If it is @code{True}, the file will be
overwritten.
@end itemize


@example
>>> screen.save("my_drawing.ps")
>>> screen.save("my_drawing.ps", overwrite=True)
@end example


Added in version 3.14.

@end deffn

@geindex setup() (στη μονάδα turtle)
@anchor{library/turtle turtle setup}@anchor{46eb}
@deffn {Συνάρτηση} turtle.setup (width=_CFG['width'], height=_CFG['height'], startx=_CFG['leftright'], starty=_CFG['topbottom'])

Set the size and position of the main window.  Default values of arguments
are stored in the configuration dictionary and can be changed via a
@code{turtle.cfg} file.

@*Παράμετροι: 

@itemize *

@item 
@code{width} – if an integer, a size in pixels, if a float, a fraction of the
screen; default is 50% of screen

@item 
@code{height} – if an integer, the height in pixels, if a float, a fraction of
the screen; default is 75% of screen

@item 
@code{startx} – if positive, starting position in pixels from the left
edge of the screen, if negative from the right edge, if @code{None},
center window horizontally

@item 
@code{starty} – if positive, starting position in pixels from the top
edge of the screen, if negative from the bottom edge, if @code{None},
center window vertically
@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() (στη μονάδα turtle)
@anchor{library/turtle turtle title}@anchor{46ec}
@deffn {Συνάρτηση} turtle.title (titlestring)

@*Παράμετροι: 
@code{titlestring} – a string that is shown in the titlebar of the turtle
graphics window


Set title of turtle window to `titlestring'.

@example
>>> screen.title("Welcome to the turtle zoo!")
@end example
@end deffn

@node Public classes,Explanation<2>,Methods of TurtleScreen/Screen and corresponding functions,turtle — Turtle graphics
@anchor{library/turtle public-classes}@anchor{4709}
@subsubsection Public classes


@geindex RawTurtle (κλάση σε turtle)
@geindex RawPen (κλάση σε turtle)
@anchor{library/turtle turtle RawTurtle}@anchor{470a}
@deffn {Κλάση} turtle.RawTurtle (canvas)
@anchor{library/turtle turtle RawPen}@anchor{470b}
@deffnx {Κλάση} turtle.RawPen (canvas)

@*Παράμετροι: 
@code{canvas} – a @code{tkinter.Canvas}, a @ref{470c,,ScrolledCanvas} or a
@ref{46fc,,TurtleScreen}


Create a turtle.  The turtle has all methods described above as «methods of
Turtle/RawTurtle».
@end deffn

@geindex Turtle (κλάση σε turtle)
@anchor{library/turtle turtle Turtle}@anchor{470d}
@deffn {Κλάση} turtle.Turtle

Subclass of RawTurtle, has the same interface but draws on a default
@ref{4681,,Screen} object created automatically when needed for the first time.
@end deffn

@geindex TurtleScreen (κλάση σε turtle)
@anchor{library/turtle turtle TurtleScreen}@anchor{46fc}
@deffn {Κλάση} turtle.TurtleScreen (cv)

@*Παράμετροι: 
@code{cv} – a @code{tkinter.Canvas}


Provides screen oriented methods like @ref{46cf,,bgcolor()} etc. that are described
above.
@end deffn

@geindex Screen (κλάση σε turtle)
@anchor{library/turtle turtle Screen}@anchor{4681}
@deffn {Κλάση} turtle.Screen

Subclass of TurtleScreen, with @ref{4708,,four methods added}.
@end deffn

@geindex ScrolledCanvas (κλάση σε turtle)
@anchor{library/turtle turtle ScrolledCanvas}@anchor{470c}
@deffn {Κλάση} turtle.ScrolledCanvas (master)

@*Παράμετροι: 
@code{master} – some Tkinter widget to contain the ScrolledCanvas, i.e.
a Tkinter-canvas with scrollbars added


Used by class Screen, which thus automatically provides a ScrolledCanvas as
playground for the turtles.
@end deffn

@geindex Shape (κλάση σε turtle)
@anchor{library/turtle turtle Shape}@anchor{46ff}
@deffn {Κλάση} turtle.Shape (type_, data)

@*Παράμετροι: 
@code{type_} – one of the strings «polygon», «image», «compound»


Data structure modeling shapes.  The pair @code{(type_, data)} must follow this
specification:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

`type_'

@tab

`data'

@item

«polygon»

@tab

a polygon-tuple, i.e. a tuple of pairs of coordinates

@item

«image»

@tab

an image  (in this form only used internally!)

@item

«compound»

@tab

@code{None} (a compound shape has to be constructed using the
@ref{4700,,addcomponent()} method)

@end multitable


@geindex addcomponent() (μέθοδος της turtle.Shape)
@anchor{library/turtle turtle Shape addcomponent}@anchor{4700}
@deffn {Μέθοδος} addcomponent (poly, fill, outline=None)

@*Παράμετροι: 

@itemize *

@item 
@code{poly} – a polygon, i.e. a tuple of pairs of numbers

@item 
@code{fill} – a color the `poly' will be filled with

@item 
@code{outline} – a color for the poly’s outline (if given)
@end itemize


Example:

@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

See @ref{46fe,,Compound shapes}.
@end deffn
@end deffn

@geindex Vec2D (κλάση σε turtle)
@anchor{library/turtle turtle Vec2D}@anchor{46ef}
@deffn {Κλάση} turtle.Vec2D (x, y)

A two-dimensional vector class, used as a helper class for implementing
turtle graphics.  May be useful for turtle graphics programs too.  Derived
from tuple, so a vector is a tuple!

Provides (for `a', `b' vectors, `k' number):


@itemize *

@item 
@code{a + b} vector addition

@item 
@code{a - b} vector subtraction

@item 
@code{a * b} inner product

@item 
@code{k * a} and @code{a * k} multiplication with scalar

@item 
@code{abs(a)} absolute value of a

@item 
@code{a.rotate(angle)} rotation
@end itemize
@end deffn

@node Explanation<2>,Help and configuration,Public classes,turtle — Turtle graphics
@anchor{library/turtle explanation}@anchor{470e}@anchor{library/turtle turtle-explanation}@anchor{4680}
@subsubsection Explanation


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{470d,,Turtle} instance will automatically create a @ref{4681,,Screen}
instance if one is not already present.

@code{Turtle} is a subclass of @ref{470a,,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{470c,,ScrolledCanvas}
or @ref{46fc,,TurtleScreen}.

@ref{46fc,,TurtleScreen} is the basic drawing surface for a
turtle. @ref{4681,,Screen} is a subclass of @code{TurtleScreen}, and
includes @ref{4708,,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{470c,,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 Help and configuration,turtledemo — Demo scripts,Explanation<2>,turtle — Turtle graphics
@anchor{library/turtle help-and-configuration}@anchor{470f}
@subsubsection Help and configuration


@menu
* How to use help:: 
* Translation of docstrings into different languages:: 
* How to configure Screen and Turtles:: 

@end menu

@node How to use help,Translation of docstrings into different languages,,Help and configuration
@anchor{library/turtle how-to-use-help}@anchor{4710}
@subsubsection How to use help


The public methods of the Screen and Turtle classes are documented extensively
via docstrings.  So these can be used as online-help via the Python help
facilities:


@itemize -

@item 
When using IDLE, tooltips show the signatures and first lines of the
docstrings of typed in function-/method calls.

@item 
Calling @ref{ca9,,help()} on methods or functions displays the 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 
The docstrings of the functions which are derived from methods have a modified
form:

@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

These modified docstrings are created automatically together with the function
definitions that are derived from the methods at import time.

@node Translation of docstrings into different languages,How to configure Screen and Turtles,How to use help,Help and configuration
@anchor{library/turtle translation-of-docstrings-into-different-languages}@anchor{4711}
@subsubsection Translation of docstrings into different languages


There is a utility to create a dictionary the keys of which are the method names
and the values of which are the docstrings of the public methods of the classes
Screen and Turtle.

@geindex write_docstringdict() (στη μονάδα turtle)
@anchor{library/turtle turtle write_docstringdict}@anchor{4712}
@deffn {Συνάρτηση} turtle.write_docstringdict (filename='turtle_docstringdict')

@*Παράμετροι: 
@code{filename} – a string, used as filename


Create and write docstring-dictionary to a Python script with the given
filename.  This function has to be called explicitly (it is not used by the
turtle graphics classes).  The docstring dictionary will be written to the
Python script @code{`filename'.py}.  It is intended to serve as a template
for translation of the docstrings into different languages.
@end deffn

If you (or your students) want to use @code{turtle} with online help in your
native language, you have to translate the docstrings and save the resulting
file as e.g. @code{turtle_docstringdict_german.py}.

If you have an appropriate entry in your @code{turtle.cfg} file this dictionary
will be read in at import time and will replace the original English docstrings.

At the time of this writing there are docstring dictionaries in German and in
Italian.  (Requests please to @email{glingl@@aon.at}.)

@node How to configure Screen and Turtles,,Translation of docstrings into different languages,Help and configuration
@anchor{library/turtle how-to-configure-screen-and-turtles}@anchor{4713}
@subsubsection How to configure Screen and Turtles


The built-in default configuration mimics the appearance and behaviour of the
old turtle module in order to retain best possible compatibility with it.

If you want to use a different configuration which better reflects the features
of this module or which better fits to your needs, e.g. for use in a classroom,
you can prepare a configuration file @code{turtle.cfg} which will be read at import
time and modify the configuration according to its settings.

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

Short explanation of selected entries:


@itemize -

@item 
The first four lines correspond to the arguments of the @ref{46eb,,Screen.setup}
method.

@item 
Line 5 and 6 correspond to the arguments of the method
@ref{46d3,,Screen.screensize}.

@item 
`shape' can be any of the built-in shapes, e.g: arrow, turtle, etc.  For more
info try @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 
If you want to reflect the turtle its state, you have to use @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 @code{turtle}).

@item 
The entries `exampleturtle' and `examplescreen' define the names of these
objects as they occur in the docstrings.  The transformation of
method-docstrings to function-docstrings will delete these names from the
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{46ea,,exitonclick()} to enter the
mainloop.
@end itemize

There can be a @code{turtle.cfg} file in the directory where @code{turtle} is
stored and an additional one in the current working directory.  The latter will
override the settings of the first one.

The @code{Lib/turtledemo} directory contains a @code{turtle.cfg} file.  You can
study it as an example and see its effects when running the demos (preferably
not from within the demo-viewer).

@node turtledemo — Demo scripts,Changes since Python 2 6,Help and configuration,turtle — Turtle graphics
@anchor{library/turtle module-turtledemo}@anchor{10b}@anchor{library/turtle turtledemo-demo-scripts}@anchor{4714}
@subsubsection @code{turtledemo} — Demo scripts


@geindex module; turtledemo

The @code{turtledemo} package includes a set of demo scripts.  These
scripts can be run and viewed using the supplied demo viewer as follows:

@example
python -m turtledemo
@end example

Alternatively, you can run the demo scripts individually.  For example,

@example
python -m turtledemo.bytedesign
@end example

The @code{turtledemo} package directory contains:


@itemize -

@item 
A demo viewer @code{__main__.py} which can be used to view the sourcecode
of the scripts and run them at the same time.

@item 
Multiple scripts demonstrating different features of the @code{turtle}
module.  Examples can be accessed via the Examples menu.  They can also
be run standalone.

@item 
A @code{turtle.cfg} file which serves as an example of how to write
and use such files.
@end itemize

The demo scripts are:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Name

@tab

Description

@tab

Features

@item

@code{bytedesign}

@tab

complex classical
turtle graphics pattern

@tab

@ref{46d6,,tracer()}, @ref{46d5,,delay()},
@ref{46d7,,update()}

@item

@code{chaos}

@tab

graphs Verhulst dynamics,
shows that computer’s
computations can generate
results sometimes against the
common sense expectations

@tab

world coordinates

@item

@code{clock}

@tab

analog clock showing time
of your computer

@tab

turtles as clock’s
hands, @ref{46dd,,ontimer()}

@item

@code{colormixer}

@tab

experiment with r, g, b

@tab

@ref{46c4,,ondrag()}

@item

@code{forest}

@tab

3 breadth-first trees

@tab

randomization

@item

@code{fractalcurves}

@tab

Hilbert & Koch curves

@tab

recursion

@item

@code{lindenmayer}

@tab

ethnomathematics
(indian kolams)

@tab

L-System

@item

@code{minimal_hanoi}

@tab

Towers of Hanoi

@tab

Rectangular Turtles
as Hanoi discs
(@ref{46ba,,shape()}, @ref{46bc,,shapesize()})

@item

@code{nim}

@tab

play the classical nim game
with three heaps of sticks
against the computer.

@tab

turtles as nimsticks,
event driven (mouse,
keyboard)

@item

@code{paint}

@tab

super minimalistic
drawing program

@tab

@ref{46c2,,onclick()}

@item

@code{peace}

@tab

elementary

@tab

turtle: appearance
and animation

@item

@code{penrose}

@tab

aperiodic tiling with
kites and darts

@tab

@ref{4696,,stamp()}

@item

@code{planet_and_moon}

@tab

simulation of
gravitational system

@tab

compound shapes,
@ref{46ef,,Vec2D}

@item

@code{rosette}

@tab

a pattern from the wikipedia
article on turtle graphics

@tab

@ref{46c8,,clone()},
@ref{4699,,undo()}

@item

@code{round_dance}

@tab

dancing turtles rotating
pairwise in opposite
direction

@tab

compound shapes, @ref{46c8,,clone()}
@ref{46bc,,shapesize()}, @ref{46bf,,tilt()},
@ref{46c1,,get_shapepoly()}, @ref{46d7,,update()}

@item

@code{sorting_animate}

@tab

visual demonstration of
different sorting methods

@tab

simple alignment,
randomization

@item

@code{tree}

@tab

a (graphical) breadth
first tree (using generators)

@tab

@ref{46c8,,clone()}

@item

@code{two_canvases}

@tab

simple design

@tab

turtles on two
canvases

@item

@code{yinyang}

@tab

another elementary example

@tab

@ref{4694,,circle()}

@end multitable


Have fun!

@node Changes since Python 2 6,Changes since Python 3 0,turtledemo — Demo scripts,turtle — Turtle graphics
@anchor{library/turtle changes-since-python-2-6}@anchor{4715}
@subsubsection Changes since Python 2.6



@itemize -

@item 
The methods @ref{46d6,,Turtle.tracer}, @ref{46e8,,Turtle.window_width} and
@ref{46e7,,Turtle.window_height} have been eliminated.
Methods with these names and functionality are now available only
as methods of @ref{4681,,Screen}. The functions derived from these remain
available. (In fact already in Python 2.6 these methods were merely
duplications of the corresponding
@ref{46fc,,TurtleScreen}/@code{Screen} methods.)

@item 
The method @code{Turtle.fill()} has been eliminated.
The behaviour of @ref{467b,,begin_fill()} and @ref{467c,,end_fill()}
have changed slightly: now every filling process must be completed with an
@code{end_fill()} call.

@item 
A method @ref{46b1,,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 Changes since Python 3 0,,Changes since Python 2 6,turtle — Turtle graphics
@anchor{library/turtle changes-since-python-3-0}@anchor{4716}
@subsubsection Changes since Python 3.0



@itemize -

@item 
The @ref{470d,,Turtle} methods @ref{46be,,shearfactor()}, @ref{46c0,,shapetransform()} and
@ref{46c1,,get_shapepoly()} have been added. Thus the full range of
regular linear transforms is now available for transforming turtle shapes.
@ref{b0d,,tiltangle()} has been enhanced in functionality: it now can
be used to get or set the tilt angle.

@item 
The @ref{4681,,Screen} method @ref{46db,,onkeypress()} has been added as a complement to
@ref{46d9,,onkey()}. As the latter binds actions to the key release event,
an alias: @ref{46da,,onkeyrelease()} was also added for it.

@item 
The method @ref{46de,,Screen.mainloop} has been added,
so there is no longer a need to use the standalone @code{mainloop()} function
when working with @ref{4681,,Screen} and @ref{470d,,Turtle} objects.

@item 
Two input methods have been added: @ref{1e71,,Screen.textinput} and
@ref{1e72,,Screen.numinput}. These pop up input dialogs and return
strings and numbers respectively.
@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()))

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Other sections I have in mind are
@c Tkinter internals
@c Freezing Tkinter applications

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Εργαλεία Ανάπτυξης,Debugging and profiling,Γραφικές επαφές χρηστών με το Tk,The Python Standard Library
@anchor{library/development doc}@anchor{4717}@anchor{library/development development}@anchor{4718}@anchor{library/development development-tools}@anchor{4719}@anchor{library/development translation-repo}@anchor{471a}
@section Εργαλεία Ανάπτυξης


Τα modules που περιγράφονται σε αυτό το κεφάλαιο σας βοηθούν να γράψετε λογισμικό. Για παράδειγμα, το module @ref{bd,,pydoc} παίρνει ένα module και δημιουργεί τεκμηρίωση βάσει του περιεχομένου του. Τα modules @ref{3d,,doctest} και @ref{10f,,unittest} παρέχουν πλαίσια για τη συγγραφή ελέγχων μονάδας που εκτελούν αυτόματα τον κώδικα και επαληθεύουν ότι παράγεται το αναμενόμενο αποτέλεσμα.

Ο κατάλογος των modules που περιγράφονται σε αυτό το κεφάλαιο είναι:

@menu
* typing — Support for type hints:: 
* pydoc — Documentation generator and online help system:: 
* Python Development Mode:: 
* doctest — Test interactive Python examples:: 
* unittest — Unit testing framework:: 
* unittest.mock — mock object library: unittest mock — mock object library. 
* unittest.mock — ξεκινώντας: unittest mock — ξεκινώντας. 
* test — Regression tests package for Python:: 
* test.support — Utilities for the Python test suite: test support — Utilities for the Python test suite. 
* test.support.socket_helper — Utilities for socket tests: test support socket_helper — Utilities for socket tests. 
* test.support.script_helper — Utilities for the Python execution tests: test support script_helper — Utilities for the Python execution tests. 
* test.support.bytecode_helper — Support tools for testing correct bytecode generation: test support bytecode_helper — Support tools for testing correct bytecode generation. 
* test.support.threading_helper — Utilities for threading tests: test support threading_helper — Utilities for threading tests. 
* test.support.os_helper — Utilities for os tests: test support os_helper — Utilities for os tests. 
* test.support.import_helper — Utilities for import tests: test support import_helper — Utilities for import tests. 
* test.support.warnings_helper — Utilities for warnings tests: test support warnings_helper — Utilities for warnings tests. 

@end menu

@node typing — Support for type hints,pydoc — Documentation generator and online help system,,Εργαλεία Ανάπτυξης
@anchor{library/typing doc}@anchor{471b}@anchor{library/typing typing-support-for-type-hints}@anchor{471c}
@subsection @code{typing} — Support for type hints


@c import typing
@c from dataclasses import dataclass
@c from typing import *

@geindex module; typing
@anchor{library/typing module-typing}@anchor{10d}

Added in version 3.5.


`Source code:' Lib/typing.py@footnote{https://github.com/python/cpython/tree/main/Lib/typing.py}

@cartouche
@quotation Σημείωση 
The Python runtime does not enforce function and variable type annotations.
They can be used by third party tools such as @ref{775,,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{327,,float}, as indicated by the @ref{25c1,,type hint}
@code{edge_length: float}. The function is expected to return an instance
of @ref{1df,,str}, as indicated by the @code{-> str} hint.

While type hints can be simple classes like @ref{327,,float} or @ref{1df,,str},
they can also be more complex. The @ref{10d,,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 Δείτε επίσης



@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.python.org/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:: 
* Type aliases:: 
* NewType:: 
* Annotating callable objects:: 
* Generics:: 
* Annotating tuples:: 
* The type of class objects:: 
* Annotating generators and coroutines:: 
* User-defined generic types:: 
* The Any type:: 
* Nominal vs structural subtyping:: 
* Module contents: Module contents<5>. 
* Deprecation Timeline of Major Features:: 

@end menu

@node Specification for the Python Type System,Type aliases,,typing — Support for type hints
@anchor{library/typing relevant-peps}@anchor{471d}@anchor{library/typing specification-for-the-python-type-system}@anchor{471e}
@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.python.org/en/latest/spec/index.html}.

@node Type aliases,NewType,Specification for the Python Type System,typing — Support for type hints
@anchor{library/typing id2}@anchor{471f}@anchor{library/typing type-aliases}@anchor{870}
@subsubsection Type aliases


A type alias is defined using the @ref{85a,,type} statement, which creates
an instance of @ref{52a,,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

Type aliases are useful for simplifying complex type signatures. For example:

@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{85a,,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{ba9,,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,Type aliases,typing — Support for type hints
@anchor{library/typing distinct}@anchor{4720}@anchor{library/typing newtype}@anchor{4721}
@subsubsection NewType


Use the @ref{10b1,,NewType} helper to create distinct types:

@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. This is useful in helping catch logical errors:

@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

You may still perform all @code{int} operations on a variable of type @code{UserId},
but the result will always be of type @code{int}. This lets you pass in a
@code{UserId} wherever an @code{int} might be expected, but will prevent you from
accidentally creating a @code{UserId} in an invalid way:

@example
# 'output' is of type 'int', not 'UserId'
output = UserId(23413) + UserId(54341)
@end example

Note that these checks are enforced only by the static type checker. At runtime,
the statement @code{Derived = NewType('Derived', Base)} will make @code{Derived} a
callable that immediately returns whatever parameter you pass it. That means
the expression @code{Derived(some_value)} does not create a new class or introduce
much overhead beyond that of a regular function call.

More precisely, the expression @code{some_value is Derived(some_value)} is always
true at runtime.

It is invalid to create a subtype of @code{Derived}:

@example
from typing import NewType

UserId = NewType('UserId', int)

# Fails at runtime and does not pass type checking
class AdminUserId(UserId): pass
@end example

However, it is possible to create a @ref{10b1,,NewType} based on a “derived” @code{NewType}:

@example
from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)
@end example

and typechecking for @code{ProUserId} will work as expected.

See 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} for more details.

@cartouche
@quotation Σημείωση 
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.

In contrast, @code{NewType} declares one type to be a `subtype' of another.
Doing @code{Derived = NewType('Derived', Original)} will make the static type
checker treat @code{Derived} as a `subclass' of @code{Original}, which means a
value of type @code{Original} cannot be used in places where a value of type
@code{Derived} is expected. This is useful when you want to prevent logic
errors with minimal runtime cost.
@end quotation
@end cartouche


Added in version 3.5.2.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.11: The performance of calling @code{NewType} has been restored to its level in
Python 3.9.


@node Annotating callable objects,Generics,NewType,typing — Support for type hints
@anchor{library/typing annotating-callable-objects}@anchor{4722}@anchor{library/typing annotating-callables}@anchor{28cb}
@subsubsection Annotating callable objects


Functions – or other @ref{2fa4,,callable} objects – can be annotated using
@ref{bc6,,collections.abc.Callable} or deprecated @ref{ba5,,typing.Callable}.
@code{Callable[[int], str]} signifies a function that takes a single parameter
of type @ref{326,,int} and returns a @ref{1df,,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

@geindex ...;ellipsis literal

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{295,,ParamSpec}, @ref{ba4,,Concatenate}, or an ellipsis (@code{...}). 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{4723,,overloaded functions}, or
functions that have keyword-only parameters. However, these signatures can be
expressed by defining a @ref{76c,,Protocol} class with a
@ref{961,,__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

Callables which take other callables as arguments may indicate that their
parameter types are dependent on each other using @ref{295,,ParamSpec}.
Additionally, if that callable adds or removes arguments from other
callables, the @ref{ba4,,Concatenate} operator may be used.  They
take the form @code{Callable[ParamSpecVariable, ReturnType]} and
@code{Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType]}
respectively.


Άλλαξε στην έκδοση 3.10: @code{Callable} now supports @ref{295,,ParamSpec} and @ref{ba4,,Concatenate}.
See 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} for more details.



@subsubheading Δείτε επίσης


The documentation for @ref{295,,ParamSpec} and @ref{ba4,,Concatenate} provides
examples of usage in @code{Callable}.


@node Generics,Annotating tuples,Annotating callable objects,typing — Support for type hints
@anchor{library/typing generics}@anchor{25bf}@anchor{library/typing id3}@anchor{4724}
@subsubsection Generics


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{7a5,,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{294,,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


Άλλαξε στην έκδοση 3.12: Syntactic support for generics is new in Python 3.12.


@node Annotating tuples,The type of class objects,Generics,typing — Support for type hints
@anchor{library/typing annotating-tuples}@anchor{28cc}@anchor{library/typing id4}@anchor{4725}
@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{4d9,,list} only accepts one type argument, so a type checker would emit an
error on the @code{y} assignment above. Similarly,
@ref{c9c,,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{1ce,,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

@geindex ...;ellipsis literal

To denote a tuple which could be of `any' length, and in which all elements are
of the same type @code{T}, use the literal ellipsis @code{...}: @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 — Support for type hints
@anchor{library/typing the-type-of-class-objects}@anchor{4726}@anchor{library/typing type-of-class-objects}@anchor{4727}
@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{4728,,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{186,,type} are classes, @ref{a9a,,Any},
@ref{25bf,,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{186,,type}, which is the root of Python’s
@ref{25b3,,metaclass hierarchy}.

@node Annotating generators and coroutines,User-defined generic types,The type of class objects,typing — Support for type hints
@anchor{library/typing annotating-generators-and-coroutines}@anchor{2baf}@anchor{library/typing id5}@anchor{4729}
@subsubsection Annotating generators and coroutines


A generator can be annotated using the generic type
@ref{1193,,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{1193,,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{28aa,,Iterable[YieldType]}
or @ref{28ab,,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{104a,,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{1197,,AsyncIterable[YieldType]}
and @ref{1196,,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{1195,,Coroutine[YieldType@comma{} SendType@comma{} ReturnType]}.
Generic arguments correspond to those of @ref{1193,,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 User-defined generic types,The Any type,Annotating generators and coroutines,typing — Support for type hints
@anchor{library/typing user-defined-generic-types}@anchor{472a}@anchor{library/typing user-defined-generics}@anchor{8df}
@subsubsection User-defined generic types


A user-defined class can be defined as a generic class.

@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{472b,,type variable} @code{T} . This also makes @code{T} valid as
a type within the class body.

Generic classes implicitly inherit from @ref{19f2,,Generic}. For compatibility
with Python 3.11 and lower, it is also possible to inherit explicitly from
@code{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{b21,,__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{294,,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

Each type variable argument to @ref{19f2,,Generic} must be distinct.
This is thus invalid:

@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

In this case @code{MyDict} has a single parameter, @code{T}.

Using a generic class without specifying type parameters assumes
@ref{a9a,,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


Άλλαξε στην έκδοση 3.7: @ref{19f2,,Generic} no longer has a custom metaclass.



Άλλαξε στην έκδοση 3.12: Syntactic support for generics and type aliases is new in version 3.12.
Previously, generic classes had to explicitly inherit from @ref{19f2,,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 @code{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{295,,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{295,,ParamSpec} can also be created using explicit
inheritance from @ref{19f2,,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{294,,TypeVar} and @ref{295,,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{295,,ParamSpec} may not have correct
@code{__parameters__} after substitution in some cases because they
are intended primarily for static type checking.


Άλλαξε στην έκδοση 3.10: @ref{19f2,,Generic} can now be parameterized over parameter expressions.
See @ref{295,,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 @code{typing} module are @ref{183,,hashable} and
comparable for equality.

@node The Any type,Nominal vs structural subtyping,User-defined generic types,typing — Support for type hints
@anchor{library/typing the-any-type}@anchor{472c}
@subsubsection The @code{Any} type


A special kind of type is @ref{a9a,,Any}. A static type checker will treat
every type as being compatible with @code{Any} and @code{Any} as being
compatible with every type.

This means that it is possible to perform any operation or method call on a
value of type @ref{a9a,,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{a9a,,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{1df,,str} and receives an @ref{326,,int} value at
runtime!

Furthermore, all functions without a return type or parameter types will
implicitly default to using @ref{a9a,,Any}:

@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

This behavior allows @ref{a9a,,Any} to be used as an `escape hatch' when you
need to mix dynamically and statically typed code.

Contrast the behavior of @ref{a9a,,Any} with the behavior of @ref{e4d,,object}.
Similar to @code{Any}, every type is a subtype of @code{object}. However,
unlike @code{Any}, the reverse is not true: @code{object} is `not' a
subtype of every other type.

That means when the type of a value is @ref{e4d,,object}, a type checker will
reject almost all operations on it, and assigning it to a variable (or using
it as a return value) of a more specialized type is a type error. For example:

@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

Use @ref{e4d,,object} to indicate that a value could be any type in a typesafe
manner. Use @ref{a9a,,Any} to indicate that a value is dynamically typed.

@node Nominal vs structural subtyping,Module contents<5>,The Any type,typing — Support for type hints
@anchor{library/typing nominal-vs-structural-subtyping}@anchor{472d}
@subsubsection Nominal vs structural subtyping


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{28aa,,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

@geindex Python Enhancement Proposals; PEP 544
PEP 544@footnote{https://peps.python.org/pep-0544/} solves this problem by allowing users to write
the above code without explicit base classes in the class definition,
allowing @code{Bucket} to be implicitly considered a subtype of both @code{Sized}
and @code{Iterable[int]} by static type checkers. This is known as
`structural subtyping' (or static duck-typing):

@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

Moreover, by subclassing a special class @ref{76c,,Protocol}, a user
can define new custom protocols to fully enjoy structural subtyping
(see examples below).

@node Module contents<5>,Deprecation Timeline of Major Features,Nominal vs structural subtyping,typing — Support for type hints
@anchor{library/typing module-contents}@anchor{472e}
@subsubsection Module contents


The @code{typing} module defines the following classes, functions and decorators.

@menu
* Special typing primitives:: 
* Protocols: Protocols<4>. 
* ABCs and Protocols for working with I/O:: 
* Functions and decorators:: 
* Introspection helpers:: 
* Constant:: 
* Deprecated aliases:: 

@end menu

@node Special typing primitives,Protocols<4>,,Module contents<5>
@anchor{library/typing special-typing-primitives}@anchor{472f}
@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{4730}
@subsubsection Special types


These can be used as types in annotations. They do not support subscription
using @code{[]}.

@geindex Any (στη μονάδα typing)
@anchor{library/typing typing Any}@anchor{a9a}
@deffn {Δεδομένα} typing.Any

Special type indicating an unconstrained type.


@itemize *

@item 
Every type is compatible with @code{Any}.

@item 
@code{Any} is compatible with every type.
@end itemize


Άλλαξε στην έκδοση 3.11: @code{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 (στη μονάδα typing)
@anchor{library/typing typing AnyStr}@anchor{7a4}
@deffn {Δεδομένα} typing.AnyStr

A @ref{4731,,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{1df,,str} or
@ref{1c7,,bytes} arguments but cannot allow the two to mix.

For example:

@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{a9a,,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


Καταργήθηκε από την έκδοση 3.13, θα αφαιρεθεί στην έκδοση 3.18: Deprecated in favor of the new @ref{7a5,,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 (στη μονάδα typing)
@anchor{library/typing typing LiteralString}@anchor{9c8}
@deffn {Δεδομένα} 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.


Added in version 3.11.

@end deffn

@geindex Never (στη μονάδα typing)
@geindex NoReturn (στη μονάδα typing)
@anchor{library/typing typing Never}@anchor{a96}
@deffn {Δεδομένα} typing.Never
@anchor{library/typing typing NoReturn}@anchor{4732}
@deffnx {Δεδομένα} 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{4ff,,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{a95,,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.


Added in version 3.6.2: Added @code{NoReturn}.



Added in version 3.11: Added @code{Never}.

@end deffn

@geindex Self (στη μονάδα typing)
@anchor{library/typing typing Self}@anchor{9c5}
@deffn {Δεδομένα} typing.Self

Special type to represent the current enclosed class.

For example:

@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{69a,,classmethod}s that are used as alternative constructors and return instances
of the @code{cls} parameter.

@item 
Annotating an @ref{9c6,,__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.


Added in version 3.11.

@end deffn

@geindex TypeAlias (στη μονάδα typing)
@anchor{library/typing typing TypeAlias}@anchor{ba9}
@deffn {Δεδομένα} typing.TypeAlias

Special annotation for explicitly declaring a @ref{870,,type alias}.

For example:

@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.


Added in version 3.10.



Αποσύρθηκε στην έκδοση 3.12: @code{TypeAlias} is deprecated in favor of the @ref{85a,,type} statement,
which creates instances of @ref{52a,,TypeAliasType}
and which natively supports forward references.
Note that while @code{TypeAlias} and @code{TypeAliasType} serve
similar purposes and have similar names, they are distinct and the
latter is not the type of the former.
Removal of @code{TypeAlias} is not currently planned, but users
are encouraged to migrate to @code{type} statements.

@end deffn

@node Special forms,Building generic types and type aliases,Special types,Special typing primitives
@anchor{library/typing special-forms}@anchor{4733}
@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 (κλάση σε typing)
@anchor{library/typing typing Union}@anchor{341}
@deffn {Κλάση} 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 
The arguments must be types and there must be at least one.

@item 
Unions of unions are flattened, e.g.:

@example
Union[Union[int, str], float] == Union[int, str, float]
@end example

However, this does not apply to unions referenced through a type
alias, to avoid forcing evaluation of the underlying @ref{52a,,TypeAliasType}:

@example
type A = Union[int, str]
Union[A, float] != Union[int, str, float]
@end example

@item 
Unions of a single argument vanish, e.g.:

@example
Union[int] == int  # The constructor actually returns int
@end example

@item 
Redundant arguments are skipped, e.g.:

@example
Union[int, str, int] == Union[int, str] == int | str
@end example

@item 
When comparing unions, the argument order is ignored, e.g.:

@example
Union[int, str] == Union[str, int]
@end example

@item 
You cannot subclass or instantiate a @code{Union}.

@item 
You cannot write @code{Union[X][Y]}.
@end itemize


Άλλαξε στην έκδοση 3.7: Don’t remove explicit subclasses from unions at runtime.



Άλλαξε στην έκδοση 3.10: Unions can now be written as @code{X | Y}. See
@ref{ba2,,union type expressions}.



Άλλαξε στην έκδοση 3.14: @ref{527,,types.UnionType} is now an alias for @code{Union}, and both
@code{Union[int, str]} and @code{int | str} create instances of the same class.
To check whether an object is a @code{Union} at runtime, use
@code{isinstance(obj, Union)}. For compatibility with earlier versions of
Python, use
@code{get_origin(obj) is typing.Union or get_origin(obj) is types.UnionType}.

@end deffn

@geindex Optional (στη μονάδα typing)
@anchor{library/typing typing Optional}@anchor{aa0}
@deffn {Δεδομένα} typing.Optional

@code{Optional[X]} is equivalent to @code{X | None} (or @code{Union[X, None]}).

Note that this is not the same concept as an optional argument,
which is one that has a default.  An optional argument with a
default does not require the @code{Optional} qualifier on its type
annotation just because it is optional. For example:

@example
def foo(arg: int = 0) -> None:
    ...
@end example

On the other hand, if an explicit value of @code{None} is allowed, the
use of @code{Optional} is appropriate, whether the argument is optional
or not. For example:

@example
def foo(arg: Optional[int] = None) -> None:
    ...
@end example


Άλλαξε στην έκδοση 3.10: Optional can now be written as @code{X | None}. See
@ref{ba2,,union type expressions}.

@end deffn

@geindex Concatenate (στη μονάδα typing)
@anchor{library/typing typing Concatenate}@anchor{ba4}
@deffn {Δεδομένα} typing.Concatenate

Special form for annotating higher-order functions.

@geindex ...;ellipsis literal

@code{Concatenate} can be used in conjunction with @ref{28cb,,Callable} and
@ref{295,,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 valid when used in @ref{28cb,,Callable} type hints
and when instantiating user-defined generic classes with @code{ParamSpec} parameters.
The last parameter to @code{Concatenate} must be a @code{ParamSpec} or
ellipsis (@code{...}).

For example, to annotate a decorator @code{with_lock} which provides a
@ref{1a10,,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{295,,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


Added in version 3.10.



@subsubheading Δείτε επίσης



@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{295,,ParamSpec}

@item 
@ref{28cb,,Annotating callable objects}
@end itemize

@end deffn

@geindex Literal (στη μονάδα typing)
@anchor{library/typing typing Literal}@anchor{c2d}
@deffn {Δεδομένα} 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.

For example:

@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[...]} cannot be subclassed. At runtime, an arbitrary value
is allowed as type argument to @code{Literal[...]}, but type checkers may
impose restrictions. See 
@geindex Python Enhancement Proposals; PEP 586
PEP 586@footnote{https://peps.python.org/pep-0586/} for more details about literal types.

Additional details:


@itemize *

@item 
The arguments must be literal values and there must be at least one.

@item 
Nested @code{Literal} types are flattened, e.g.:

@example
assert Literal[Literal[1, 2], 3] == Literal[1, 2, 3]
@end example

However, this does not apply to @code{Literal} types referenced through a type
alias, to avoid forcing evaluation of the underlying @ref{52a,,TypeAliasType}:

@example
type A = Literal[1, 2]
assert Literal[A, 3] != Literal[1, 2, 3]
@end example

@item 
Redundant arguments are skipped, e.g.:

@example
assert Literal[1, 2, 1] == Literal[1, 2]
@end example

@item 
When comparing literals, the argument order is ignored, e.g.:

@example
assert Literal[1, 2] == Literal[2, 1]
@end example

@item 
You cannot subclass or instantiate a @code{Literal}.

@item 
You cannot write @code{Literal[X][Y]}.
@end itemize


Added in version 3.8.



Άλλαξε στην έκδοση 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{291,,TypeError} exception during equality comparisons
if one of their parameters are not @ref{183,,hashable}.

@end deffn

@geindex ClassVar (στη μονάδα typing)
@anchor{library/typing typing ClassVar}@anchor{76e}
@deffn {Δεδομένα} typing.ClassVar

Special type construct 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. Usage:

@example
class Starship:
    stats: ClassVar[dict[str, int]] = @{@} # class variable
    damage: int = 10                     # instance variable
@end example

@code{ClassVar} accepts only types and cannot be further subscribed.

@code{ClassVar} is not a class itself, and should not
be used with @ref{2ef,,isinstance()} or @ref{2f0,,issubclass()}.
@code{ClassVar} does not change Python runtime behavior, but
it can be used by third-party type checkers. For example, a type checker
might flag the following code as an error:

@example
enterprise_d = Starship(3000)
enterprise_d.stats = @{@} # Error, setting class variable on instance
Starship.stats = @{@}     # This is OK
@end example


Added in version 3.5.3.



Άλλαξε στην έκδοση 3.13: @code{ClassVar} can now be nested in @ref{76f,,Final} and vice versa.

@end deffn

@geindex Final (στη μονάδα typing)
@anchor{library/typing typing Final}@anchor{76f}
@deffn {Δεδομένα} 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.

For example:

@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

There is no runtime checking of these properties. See 
@geindex Python Enhancement Proposals; PEP 591
PEP 591@footnote{https://peps.python.org/pep-0591/} for
more details.


Added in version 3.8.



Άλλαξε στην έκδοση 3.13: @code{Final} can now be nested in @ref{76e,,ClassVar} and vice versa.

@end deffn

@geindex Required (στη μονάδα typing)
@anchor{library/typing typing Required}@anchor{9c2}
@deffn {Δεδομένα} typing.Required

Special typing construct to mark a @ref{290,,TypedDict} key as required.

This is mainly useful for @code{total=False} TypedDicts. See @ref{290,,TypedDict}
and 
@geindex Python Enhancement Proposals; PEP 655
PEP 655@footnote{https://peps.python.org/pep-0655/} for more details.


Added in version 3.11.

@end deffn

@geindex NotRequired (στη μονάδα typing)
@anchor{library/typing typing NotRequired}@anchor{9c3}
@deffn {Δεδομένα} typing.NotRequired

Special typing construct to mark a @ref{290,,TypedDict} key as potentially
missing.

See @ref{290,,TypedDict} and 
@geindex Python Enhancement Proposals; PEP 655
PEP 655@footnote{https://peps.python.org/pep-0655/} for more details.


Added in version 3.11.

@end deffn

@geindex ReadOnly (στη μονάδα typing)
@anchor{library/typing typing ReadOnly}@anchor{696}
@deffn {Δεδομένα} typing.ReadOnly

A special typing construct to mark an item of a @ref{290,,TypedDict} as read-only.

For example:

@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{290,,TypedDict} and 
@geindex Python Enhancement Proposals; PEP 705
PEP 705@footnote{https://peps.python.org/pep-0705/} for more details.


Added in version 3.13.

@end deffn

@geindex Annotated (στη μονάδα typing)
@anchor{library/typing typing Annotated}@anchor{d09}
@deffn {Δεδομένα} 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{aa1,,@@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{2ef,,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

The first argument to @code{Annotated} must be a valid type. Multiple metadata
elements can be supplied as @code{Annotated} supports variadic arguments. The
order of the metadata elements is preserved and matters for equality checks:

@example
@@dataclass
class ctype:
     kind: str

a1 = Annotated[int, ValueRange(3, 10), ctype("char")]
a2 = Annotated[int, ctype("char"), ValueRange(3, 10)]

assert a1 != a2  # Order matters
@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.

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

However, this does not apply to @code{Annotated} types referenced through a type
alias, to avoid forcing evaluation of the underlying @ref{52a,,TypeAliasType}:

@example
type From3To10[T] = Annotated[T, ValueRange(3, 10)]
assert Annotated[From3To10[int], ctype("char")] != Annotated[
   int, ValueRange(3, 10), ctype("char")
]
@end example

Duplicated metadata elements are not removed:

@example
assert Annotated[int, ValueRange(3, 10)] != Annotated[
    int, ValueRange(3, 10), ValueRange(3, 10)
]
@end example

@code{Annotated} can be used with nested and generic aliases:

@quotation

@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
@end quotation

@code{Annotated} cannot be used with an unpacked @ref{293,,TypeVarTuple}:

@example
type Variadic[*Ts] = Annotated[*Ts, Ann1] = Annotated[T1, T2, T3, ..., Ann1]  # NOT valid
@end example

where @code{T1}, @code{T2}, … are @ref{294,,TypeVars}. This is invalid as
only one type should be passed to Annotated.

By default, @ref{a9e,,get_type_hints()} strips the metadata from annotations.
Pass @code{include_extras=True} to have the metadata preserved:

@quotation

@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
@end quotation

At runtime, the metadata associated with an @code{Annotated} type can be
retrieved via the @code{__metadata__} attribute:

@quotation

@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
@end quotation

If you want to retrieve the original type wrapped by @code{Annotated}, use the
@code{__origin__} attribute:

@quotation

@example
>>> from typing import Annotated, get_origin
>>> Password = Annotated[str, "secret"]
>>> Password.__origin__
<class 'str'>
@end example
@end quotation

Note that using @ref{314,,get_origin()} will return @code{Annotated} itself:

@quotation

@example
>>> get_origin(Password)
typing.Annotated
@end example
@end quotation


@subsubheading Δείτε επίσης



@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



Added in version 3.9.

@end deffn

@geindex TypeForm (στη μονάδα typing)
@anchor{library/typing typing TypeForm}@anchor{28f}
@deffn {Δεδομένα} typing.TypeForm

A special form representing the value that results from evaluating a
type expression.

This value encodes the information supplied in the type expression, and
it represents the type described by that type expression.

When used in a type expression, @code{TypeForm} describes a set of type form
objects. It accepts a single type argument, which must be a valid type
expression. @code{TypeForm[T]} describes the set of all type form objects that
represent the type @code{T} or types assignable to @code{T}.

@code{TypeForm(obj)} simply returns @code{obj} unchanged. This is useful for
explicitly marking a value as a type form for static type checkers.

Example:

@example
from typing import Any, TypeForm

def cast[T](typ: TypeForm[T], value: Any) -> T: ...

reveal_type(cast(int, "x"))  # Revealed type is "int"
@end example

See 
@geindex Python Enhancement Proposals; PEP 747
PEP 747@footnote{https://peps.python.org/pep-0747/} for details.


Added in version 3.15.

@end deffn

@geindex TypeIs (στη μονάδα typing)
@anchor{library/typing typing TypeIs}@anchor{697}
@deffn {Δεδομένα} 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{698,,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

For example:

@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}).


Added in version 3.13.

@end deffn

@geindex TypeGuard (στη μονάδα typing)
@anchor{library/typing typing TypeGuard}@anchor{698}
@deffn {Δεδομένα} 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{697,,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.

For example:

@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


Added in version 3.10.

@end deffn

@geindex Unpack (στη μονάδα typing)
@anchor{library/typing typing Unpack}@anchor{1bb1}
@deffn {Δεδομένα} typing.Unpack

Typing operator to conceptually mark an object as having been unpacked.

For example, using the unpack operator @code{*} on a
@ref{4734,,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{293,,typing.TypeVarTuple} and
@ref{1ce,,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{290,,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.


Added in 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{4735}
@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{7a5,,type parameter lists} and the @ref{85a,,type} statement).
For compatibility with Python 3.11 and earlier, they can also be created
without the dedicated syntax, as documented below.

@geindex Generic (κλάση σε typing)
@anchor{library/typing typing Generic}@anchor{19f2}
@deffn {Κλάση} typing.Generic

Abstract base class for generic types.

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{86e,,Language Reference}.

This class can then be used as follows:

@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{86f,,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 (κλάση σε typing)
@anchor{library/typing typevar}@anchor{472b}@anchor{library/typing typing TypeVar}@anchor{294}
@deffn {Κλάση} typing.TypeVar (name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)

Type variable.

The preferred way to construct a type variable is via the dedicated syntax
for @ref{86f,,generic functions},
@ref{86e,,generic classes}, and
@ref{871,,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{19f2,,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{7a5,,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{4731}
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{291,,TypeError}.

@geindex __name__ (ιδιότητα της typing.TypeVar)
@anchor{library/typing typing TypeVar __name__}@anchor{4736}
@deffn {Ιδιότητα} __name__

The name of the type variable.
@end deffn

@geindex __covariant__ (ιδιότητα της typing.TypeVar)
@anchor{library/typing typing TypeVar __covariant__}@anchor{4737}
@deffn {Ιδιότητα} __covariant__

Whether the type var has been explicitly marked as covariant.
@end deffn

@geindex __contravariant__ (ιδιότητα της typing.TypeVar)
@anchor{library/typing typing TypeVar __contravariant__}@anchor{4738}
@deffn {Ιδιότητα} __contravariant__

Whether the type var has been explicitly marked as contravariant.
@end deffn

@geindex __infer_variance__ (ιδιότητα της typing.TypeVar)
@anchor{library/typing typing TypeVar __infer_variance__}@anchor{4739}
@deffn {Ιδιότητα} __infer_variance__

Whether the type variable’s variance should be inferred by type checkers.


Added in version 3.12.

@end deffn

@geindex __bound__ (ιδιότητα της typing.TypeVar)
@anchor{library/typing typing TypeVar __bound__}@anchor{473a}
@deffn {Ιδιότητα} __bound__

The upper bound of the type variable, if any.


Άλλαξε στην έκδοση 3.12: For type variables created through @ref{7a5,,type parameter syntax},
the bound is evaluated only when the attribute is accessed, not when
the type variable is created (see @ref{872,,Καθυστερημένη εκτίμηση}).

@end deffn

@geindex evaluate_bound() (μέθοδος της typing.TypeVar)
@anchor{library/typing typing TypeVar evaluate_bound}@anchor{473b}
@deffn {Μέθοδος} evaluate_bound ()

An @ref{473c,,evaluate function} corresponding to the @ref{473a,,__bound__} attribute.
When called directly, this method supports only the @ref{40b,,VALUE}
format, which is equivalent to accessing the @code{__bound__} attribute directly,
but the method object can be passed to @ref{473d,,annotationlib.call_evaluate_function()}
to evaluate the value in a different format.


Added in version 3.14.

@end deffn

@geindex __constraints__ (ιδιότητα της typing.TypeVar)
@anchor{library/typing typing TypeVar __constraints__}@anchor{473e}
@deffn {Ιδιότητα} __constraints__

A tuple containing the constraints of the type variable, if any.


Άλλαξε στην έκδοση 3.12: For type variables created through @ref{7a5,,type parameter syntax},
the constraints are evaluated only when the attribute is accessed, not when
the type variable is created (see @ref{872,,Καθυστερημένη εκτίμηση}).

@end deffn

@geindex evaluate_constraints() (μέθοδος της typing.TypeVar)
@anchor{library/typing typing TypeVar evaluate_constraints}@anchor{473f}
@deffn {Μέθοδος} evaluate_constraints ()

An @ref{473c,,evaluate function} corresponding to the @ref{473e,,__constraints__} attribute.
When called directly, this method supports only the @ref{40b,,VALUE}
format, which is equivalent to accessing the @code{__constraints__} attribute directly,
but the method object can be passed to @ref{473d,,annotationlib.call_evaluate_function()}
to evaluate the value in a different format.


Added in version 3.14.

@end deffn

@geindex __default__ (ιδιότητα της typing.TypeVar)
@anchor{library/typing typing TypeVar __default__}@anchor{4740}
@deffn {Ιδιότητα} __default__

The default value of the type variable, or @ref{76a,,typing.NoDefault} if it
has no default.


Added in version 3.13.

@end deffn

@geindex evaluate_default() (μέθοδος της typing.TypeVar)
@anchor{library/typing typing TypeVar evaluate_default}@anchor{4741}
@deffn {Μέθοδος} evaluate_default ()

An @ref{473c,,evaluate function} corresponding to the @ref{4740,,__default__} attribute.
When called directly, this method supports only the @ref{40b,,VALUE}
format, which is equivalent to accessing the @code{__default__} attribute directly,
but the method object can be passed to @ref{473d,,annotationlib.call_evaluate_function()}
to evaluate the value in a different format.


Added in version 3.14.

@end deffn

@geindex has_default() (μέθοδος της typing.TypeVar)
@anchor{library/typing typing TypeVar has_default}@anchor{4742}
@deffn {Μέθοδος} has_default ()

Return whether or not the type variable has a default value. This is equivalent
to checking whether @ref{4740,,__default__} is not the @ref{76a,,typing.NoDefault}
singleton, except that it does not force evaluation of the
@ref{872,,lazily evaluated} default value.


Added in version 3.13.

@end deffn


Άλλαξε στην έκδοση 3.12: Type variables can now be declared using the
@ref{7a5,,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.



Άλλαξε στην έκδοση 3.13: Support for default values was added.

@end deffn

@geindex TypeVarTuple (κλάση σε typing)
@anchor{library/typing typevartuple}@anchor{4734}@anchor{library/typing typing TypeVarTuple}@anchor{293}
@deffn {Κλάση} typing.TypeVarTuple (name, *, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)

Type variable tuple. A specialized form of @ref{472b,,type variable}
that enables `variadic' generics.

Type variable tuples can be declared in @ref{7a5,,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{1bb1,,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__ (ιδιότητα της typing.TypeVarTuple)
@anchor{library/typing typing TypeVarTuple __name__}@anchor{4743}
@deffn {Ιδιότητα} __name__

The name of the type variable tuple.
@end deffn

@geindex __covariant__ (ιδιότητα της typing.TypeVarTuple)
@anchor{library/typing typing TypeVarTuple __covariant__}@anchor{4744}
@deffn {Ιδιότητα} __covariant__

Whether the type variable tuple has been explicitly marked as covariant.


Added in version 3.15.

@end deffn

@geindex __contravariant__ (ιδιότητα της typing.TypeVarTuple)
@anchor{library/typing typing TypeVarTuple __contravariant__}@anchor{4745}
@deffn {Ιδιότητα} __contravariant__

Whether the type variable tuple has been explicitly marked as contravariant.


Added in version 3.15.

@end deffn

@geindex __infer_variance__ (ιδιότητα της typing.TypeVarTuple)
@anchor{library/typing typing TypeVarTuple __infer_variance__}@anchor{4746}
@deffn {Ιδιότητα} __infer_variance__

Whether the type variable tuple’s variance should be inferred by type checkers.


Added in version 3.15.

@end deffn

@geindex __default__ (ιδιότητα της typing.TypeVarTuple)
@anchor{library/typing typing TypeVarTuple __default__}@anchor{4747}
@deffn {Ιδιότητα} __default__

The default value of the type variable tuple, or @ref{76a,,typing.NoDefault} if it
has no default.


Added in version 3.13.

@end deffn

@geindex evaluate_default() (μέθοδος της typing.TypeVarTuple)
@anchor{library/typing typing TypeVarTuple evaluate_default}@anchor{4748}
@deffn {Μέθοδος} evaluate_default ()

An @ref{473c,,evaluate function} corresponding to the @ref{4747,,__default__} attribute.
When called directly, this method supports only the @ref{40b,,VALUE}
format, which is equivalent to accessing the @code{__default__} attribute directly,
but the method object can be passed to @ref{473d,,annotationlib.call_evaluate_function()}
to evaluate the value in a different format.


Added in version 3.14.

@end deffn

@geindex has_default() (μέθοδος της typing.TypeVarTuple)
@anchor{library/typing typing TypeVarTuple has_default}@anchor{4749}
@deffn {Μέθοδος} has_default ()

Return whether or not the type variable tuple has a default value. This is equivalent
to checking whether @ref{4747,,__default__} is not the @ref{76a,,typing.NoDefault}
singleton, except that it does not force evaluation of the
@ref{872,,lazily evaluated} default value.


Added in version 3.13.

@end deffn

Type variable tuples 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{294,,TypeVar}, but its actual semantics are yet to be decided.


Added in version 3.11.



Άλλαξε στην έκδοση 3.12: Type variable tuples can now be declared using the
@ref{7a5,,type parameter} syntax introduced by 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.



Άλλαξε στην έκδοση 3.13: Support for default values was added.



Άλλαξε στην έκδοση 3.15: Added support for the @code{bound}, @code{covariant}, @code{contravariant}, and
@code{infer_variance} parameters.

@end deffn

@geindex ParamSpec (κλάση σε typing)
@anchor{library/typing typing ParamSpec}@anchor{295}
@deffn {Κλάση} typing.ParamSpec (name, *, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)

Parameter specification variable.  A specialized version of
@ref{472b,,type variables}.

In @ref{7a5,,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{19f2,,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{294,,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{a9a,,Any}.

@item 
@ref{474a,,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 (ιδιότητα της typing.ParamSpec)
@anchor{library/typing typing ParamSpec args}@anchor{474b}
@deffn {Ιδιότητα} args
@end deffn

@geindex kwargs (ιδιότητα της typing.ParamSpec)
@anchor{library/typing typing ParamSpec kwargs}@anchor{474c}
@deffn {Ιδιότητα} 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{ba6,,ParamSpecArgs} and @ref{ba7,,ParamSpecKwargs}.
@end deffn

@geindex __name__ (ιδιότητα της typing.ParamSpec)
@anchor{library/typing typing ParamSpec __name__}@anchor{474d}
@deffn {Ιδιότητα} __name__

The name of the parameter specification.
@end deffn

@geindex __covariant__ (ιδιότητα της typing.ParamSpec)
@anchor{library/typing typing ParamSpec __covariant__}@anchor{474e}
@deffn {Ιδιότητα} __covariant__

Whether the parameter specification has been explicitly marked as covariant.
@end deffn

@geindex __contravariant__ (ιδιότητα της typing.ParamSpec)
@anchor{library/typing typing ParamSpec __contravariant__}@anchor{474f}
@deffn {Ιδιότητα} __contravariant__

Whether the parameter specification has been explicitly marked as contravariant.
@end deffn

@geindex __infer_variance__ (ιδιότητα της typing.ParamSpec)
@anchor{library/typing typing ParamSpec __infer_variance__}@anchor{4750}
@deffn {Ιδιότητα} __infer_variance__

Whether the parameter specification’s variance should be inferred by type checkers.


Added in version 3.12.

@end deffn

@geindex __default__ (ιδιότητα της typing.ParamSpec)
@anchor{library/typing typing ParamSpec __default__}@anchor{4751}
@deffn {Ιδιότητα} __default__

The default value of the parameter specification, or @ref{76a,,typing.NoDefault} if it
has no default.


Added in version 3.13.

@end deffn

@geindex evaluate_default() (μέθοδος της typing.ParamSpec)
@anchor{library/typing typing ParamSpec evaluate_default}@anchor{4752}
@deffn {Μέθοδος} evaluate_default ()

An @ref{473c,,evaluate function} corresponding to the @ref{4751,,__default__} attribute.
When called directly, this method supports only the @ref{40b,,VALUE}
format, which is equivalent to accessing the @code{__default__} attribute directly,
but the method object can be passed to @ref{473d,,annotationlib.call_evaluate_function()}
to evaluate the value in a different format.


Added in version 3.14.

@end deffn

@geindex has_default() (μέθοδος της typing.ParamSpec)
@anchor{library/typing typing ParamSpec has_default}@anchor{4753}
@deffn {Μέθοδος} has_default ()

Return whether or not the parameter specification has a default value. This is equivalent
to checking whether @ref{4751,,__default__} is not the @ref{76a,,typing.NoDefault}
singleton, except that it does not force evaluation of the
@ref{872,,lazily evaluated} default value.


Added in 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{294,,TypeVar}.  However the actual semantics of these keywords are yet to
be decided.


Added in version 3.10.



Άλλαξε στην έκδοση 3.12: Parameter specifications can now be declared using the
@ref{7a5,,type parameter} syntax introduced by 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.



Άλλαξε στην έκδοση 3.13: Support for default values was added.


@cartouche
@quotation Σημείωση 
Only parameter specification variables defined in global scope can
be pickled.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης



@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{ba4,,Concatenate}

@item 
@ref{28cb,,Annotating callable objects}
@end itemize

@end deffn

@geindex ParamSpecArgs (στη μονάδα typing)
@geindex ParamSpecKwargs (στη μονάδα typing)
@anchor{library/typing typing ParamSpecArgs}@anchor{ba6}
@deffn {Δεδομένα} typing.ParamSpecArgs
@anchor{library/typing typing ParamSpecKwargs}@anchor{ba7}
@deffnx {Δεδομένα} typing.ParamSpecKwargs

Arguments and keyword arguments attributes of a @ref{295,,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{314,,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


Added in version 3.10.

@end deffn

@geindex TypeAliasType (κλάση σε typing)
@anchor{library/typing typing TypeAliasType}@anchor{52a}
@deffn {Κλάση} typing.TypeAliasType (name, value, *, type_params=(), qualname=None)

The type of type aliases created through the @ref{85a,,type} statement.

Example:

@example
>>> type Alias = int
>>> type(Alias)
<class 'typing.TypeAliasType'>
@end example


Added in version 3.12.


@geindex __name__ (ιδιότητα της typing.TypeAliasType)
@anchor{library/typing typing TypeAliasType __name__}@anchor{4754}
@deffn {Ιδιότητα} __name__

The name of the type alias:

@example
>>> type Alias = int
>>> Alias.__name__
'Alias'
@end example
@end deffn

@geindex __qualname__ (ιδιότητα της typing.TypeAliasType)
@anchor{library/typing typing TypeAliasType __qualname__}@anchor{4755}
@deffn {Ιδιότητα} __qualname__

The @ref{1f19,,qualified name} of the type alias:

@example
>>> class Class:
...     type Alias = int
...
>>> Class.Alias.__qualname__
'Class.Alias'
@end example


Added in version 3.15.

@end deffn

@geindex __module__ (ιδιότητα της typing.TypeAliasType)
@anchor{library/typing typing TypeAliasType __module__}@anchor{4756}
@deffn {Ιδιότητα} __module__

The name of the module in which the type alias was defined:

@example
>>> type Alias = int
>>> Alias.__module__
'__main__'
@end example

This attribute is writable.


Άλλαξε στην έκδοση 3.15: The attribute is now writable.

@end deffn

@geindex __type_params__ (ιδιότητα της typing.TypeAliasType)
@anchor{library/typing typing TypeAliasType __type_params__}@anchor{4757}
@deffn {Ιδιότητα} __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__ (ιδιότητα της typing.TypeAliasType)
@anchor{library/typing typing TypeAliasType __value__}@anchor{4758}
@deffn {Ιδιότητα} __value__

The type alias’s value. This is @ref{872,,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

@geindex evaluate_value() (μέθοδος της typing.TypeAliasType)
@anchor{library/typing typing TypeAliasType evaluate_value}@anchor{4759}
@deffn {Μέθοδος} evaluate_value ()

An @ref{473c,,evaluate function} corresponding to the @ref{4758,,__value__} attribute.
When called directly, this method supports only the @ref{40b,,VALUE}
format, which is equivalent to accessing the @code{__value__} attribute directly,
but the method object can be passed to @ref{473d,,annotationlib.call_evaluate_function()}
to evaluate the value in a different format:

@example
>>> type Alias = undefined
>>> Alias.__value__
Traceback (most recent call last):
...
NameError: name 'undefined' is not defined
>>> from annotationlib import Format, call_evaluate_function
>>> Alias.evaluate_value(Format.VALUE)
Traceback (most recent call last):
...
NameError: name 'undefined' is not defined
>>> call_evaluate_function(Alias.evaluate_value, Format.FORWARDREF)
ForwardRef('undefined')
@end example


Added in version 3.14.

@end deffn

@subsubheading Unpacking


Type aliases support star unpacking using the @code{*Alias} syntax.
This is equivalent to using @code{Unpack[Alias]} directly:

@example
>>> type Alias = tuple[int, str]
>>> type Unpacked = tuple[bool, *Alias]
>>> Unpacked.__value__
tuple[bool, typing.Unpack[Alias]]
@end example


Added in version 3.14.

@end deffn

@node Other special directives,,Building generic types and type aliases,Special typing primitives
@anchor{library/typing other-special-directives}@anchor{475a}
@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 (κλάση σε typing)
@anchor{library/typing typing NamedTuple}@anchor{2e4}
@deffn {Κλάση} typing.NamedTuple

Typed version of @ref{1cf,,collections.namedtuple()}.

Usage:

@example
class Employee(NamedTuple):
    name: str
    id: int
@end example

This is equivalent to:

@example
Employee = collections.namedtuple('Employee', ['name', 'id'])
@end example

To give a field a default value, you can assign to it in the class body:

@example
class Employee(NamedTuple):
    name: str
    id: int = 3

employee = Employee('Guido')
assert employee.id == 3
@end example

Fields with a default value must come after any fields without a default.

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{1cf,,namedtuple()}
API.)

@code{NamedTuple} subclasses can also have docstrings and methods:

@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

Backward-compatible usage:

@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


Άλλαξε στην έκδοση 3.6: Added support for 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/} variable annotation syntax.



Άλλαξε στην έκδοση 3.6.1: Added support for default values, methods, and docstrings.



Άλλαξε στην έκδοση 3.8: The @code{_field_types} and @code{__annotations__} attributes are
now regular dictionaries instead of instances of @code{OrderedDict}.



Άλλαξε στην έκδοση 3.9: Removed the @code{_field_types} attribute in favor of the more
standard @code{__annotations__} attribute which has the same information.



Άλλαξε στην έκδοση 3.9: @code{NamedTuple} is now a function rather than a class.
It can still be used as a class base, as described above.



Άλλαξε στην έκδοση 3.11: Added support for generic namedtuples.



Άλλαξε στην έκδοση 3.14: Using @ref{443,,super()} (and the @code{__class__} @ref{1ab7,,closure variable}) in methods of @code{NamedTuple} subclasses
is unsupported and causes a @ref{291,,TypeError}.

@end deffn

@geindex NewType (κλάση σε typing)
@anchor{library/typing typing NewType}@anchor{10b1}
@deffn {Κλάση} typing.NewType (name, tp)

Helper class to create low-overhead @ref{4720,,distinct types}.

A @code{NewType} is considered a distinct type by a typechecker. At runtime,
however, calling a @code{NewType} returns its argument unchanged.

Usage:

@example
UserId = NewType('UserId', int)  # Declare the NewType "UserId"
first_user = UserId(1)  # "UserId" returns the argument unchanged at runtime
@end example

@geindex __module__ (ιδιότητα της typing.NewType)
@anchor{library/typing typing NewType __module__}@anchor{475b}
@deffn {Ιδιότητα} __module__

The name of the module in which the new type is defined.
@end deffn

@geindex __name__ (ιδιότητα της typing.NewType)
@anchor{library/typing typing NewType __name__}@anchor{475c}
@deffn {Ιδιότητα} __name__

The name of the new type.
@end deffn

@geindex __supertype__ (ιδιότητα της typing.NewType)
@anchor{library/typing typing NewType __supertype__}@anchor{475d}
@deffn {Ιδιότητα} __supertype__

The type that the new type is based on.
@end deffn


Added in version 3.5.2.



Άλλαξε στην έκδοση 3.10: @code{NewType} is now a class rather than a function.

@end deffn

@geindex Protocol (κλάση σε typing)
@anchor{library/typing typing Protocol}@anchor{76c}
@deffn {Κλάση} typing.Protocol (Generic)

Base class for protocol classes.

Protocol classes are defined like this:

@example
class Proto(Protocol):
    def meth(self) -> int:
        ...
@end example

Such classes are primarily used with static type checkers that recognize
structural subtyping (static duck-typing), for example:

@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{861,,runtime_checkable()} (described later) act as simple-minded runtime
protocols that check only the presence of given attributes, ignoring their
type signatures. Protocol classes without this decorator cannot be used
as the second argument to @ref{2ef,,isinstance()} or @ref{2f0,,issubclass()}.

Protocol classes can be generic, for example:

@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


Added in version 3.8.



Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.20: It is deprecated to call @ref{2ef,,isinstance()} and @ref{2f0,,issubclass()} checks on
protocol classes that were not explicitly decorated with @code{runtime_checkable()}
but that inherit from a runtime-checkable protocol class. This will throw
a @ref{291,,TypeError} in Python 3.20.

@end deffn

@geindex runtime_checkable() (στη μονάδα typing)
@anchor{library/typing typing runtime_checkable}@anchor{861}
@deffn {Συνάρτηση} @@typing.runtime_checkable

Mark a protocol class as a runtime protocol.

Such a protocol can be used with @ref{2ef,,isinstance()} and @ref{2f0,,issubclass()}.
This allows a simple-minded structural check, very similar to «one trick ponies»
in @ref{1f,,collections.abc} such as @ref{28aa,,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

Runtime checkability of protocols is not inherited. A subclass of a runtime-checkable protocol
is only runtime-checkable if it is explicitly marked as such, regardless of class hierarchy:

@example
@@runtime_checkable
class Iterable(Protocol):
    def __iter__(self): ...

# Without @@runtime_checkable, Reversible would no longer be runtime-checkable.
@@runtime_checkable
class Reversible(Iterable, Protocol):
    def __reversed__(self): ...
@end example

This decorator raises @ref{291,,TypeError} when applied to a non-protocol class.

@cartouche
@quotation Σημείωση 
@code{runtime_checkable()} will check only the presence of the required
methods or attributes, not their type signatures or types.
For example, @ref{f40,,ssl.SSLObject}
is a class, therefore it passes an @ref{2f0,,issubclass()}
check against @ref{28cb,,Callable}. However, the
@code{ssl.SSLObject.__init__} method exists only to raise a
@ref{291,,TypeError} with a more informative message, therefore making
it impossible to call (instantiate) @code{ssl.SSLObject}.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
An @ref{2ef,,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{8e2,,hasattr()} calls for structural checks in performance-sensitive
code.
@end quotation
@end cartouche


Added in version 3.8.



Άλλαξε στην έκδοση 3.12: The internal implementation of @ref{2ef,,isinstance()} checks against
runtime-checkable protocols now uses @ref{8a5,,inspect.getattr_static()}
to look up attributes (previously, @ref{8e2,,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.



Άλλαξε στην έκδοση 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{2ef,,isinstance()} checks comparing objects to the
protocol. See @ref{8e1,,What’s new in Python 3.12}
for more details.



Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.20: It is deprecated to call @ref{2ef,,isinstance()} and @ref{2f0,,issubclass()} checks on
protocol classes that were not explicitly decorated with @code{runtime_checkable()}
but that inherit from a runtime-checkable protocol class. This will throw
a @ref{291,,TypeError} in Python 3.20.

@end deffn

@geindex TypedDict (κλάση σε typing)
@anchor{library/typing typing TypedDict}@anchor{290}
@deffn {Κλάση} typing.TypedDict (dict)

Special construct to add type hints to a dictionary.
At runtime «@code{TypedDict} instances» are simply @ref{188,,dicts}.

@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{188,,dict}:

@example
Point2D = TypedDict('Point2D', @{'x': int, 'y': int, 'label': str@})
@end example

This functional syntax allows defining keys which are not valid
@ref{2491,,identifiers}, for example because they are
keywords or contain hyphens, or when key names must not be
@ref{2293,,mangled} like regular private names:

@example
# raises SyntaxError
class Point2D(TypedDict):
    in: int  # 'in' is a keyword
    x-y: int  # name with hyphens

class Definition(TypedDict):
    __schema: str  # mangled to `_Definition__schema`

# OK, functional syntax
Point2D = TypedDict('Point2D', @{'in': int, 'x-y': int@})
Definition = TypedDict('Definition', @{'__schema': str@})  # not mangled
@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{9c3,,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{9c2,,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

By default, a @code{TypedDict} is open, meaning that it may contain additional keys
at runtime beyond those defined in the class body. The `closed' class argument can
be used to control this; if @code{closed=True}, the @code{TypedDict} cannot contain additional keys.

@example
class ClosedPoint(TypedDict, closed=True):
    x: int
    y: int

class ClosedPoint3D(ClosedPoint):  # type checker error: cannot add keys to a closed TypedDict
    z: int
@end example

Setting @code{closed=False} explicitly requests the default open behavior. If the argument is not
passed, this state is inherited from the parent class.

In addition to being open or closed, a @code{TypedDict} can also be configured to have extra items.
If the `extra_items' class argument is set to a type, the @code{TypedDict} can contain arbitrary
additional keys, but the values of those keys must be of the specified type.

@example
class ExtraItemsPoint(TypedDict, extra_items=int):
    x: int
    y: int

point: ExtraItemsPoint = @{'x': 1, 'y': 2, 'anything': 3@}  # OK
@end example

The `extra_items' argument is also inherited through subclassing. It is unset
by default, and it may not be used together with the `closed' argument.

A @code{TypedDict} cannot inherit from a non-@code{TypedDict} class,
except for @ref{19f2,,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{19f2,,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{bb6,,Annotations Best Practices} for more information on annotations best practices)
and the following attributes:

@geindex __total__ (ιδιότητα της typing.TypedDict)
@anchor{library/typing typing TypedDict __total__}@anchor{475e}
@deffn {Ιδιότητα} __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{9c3,,NotRequired}, or it may inherit from another
@code{TypedDict} with @code{total=False}. Therefore, it is generally better to use
@ref{475f,,__required_keys__} and @ref{4760,,__optional_keys__} for introspection.
@end deffn

@geindex __required_keys__ (ιδιότητα της typing.TypedDict)
@anchor{library/typing typing TypedDict __required_keys__}@anchor{475f}
@deffn {Ιδιότητα} __required_keys__


Added in version 3.9.

@end deffn

@geindex __optional_keys__ (ιδιότητα της typing.TypedDict)
@anchor{library/typing typing TypedDict __optional_keys__}@anchor{4760}
@deffn {Ιδιότητα} __optional_keys__

@code{Point2D.__required_keys__} and @code{Point2D.__optional_keys__} return
@ref{9d4,,frozenset} objects containing required and non-required keys, respectively.

Keys marked with @ref{9c2,,Required} will always appear in @code{__required_keys__}
and keys marked with @ref{9c3,,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


Added in version 3.9.


@cartouche
@quotation Σημείωση 
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

@geindex __readonly_keys__ (ιδιότητα της typing.TypedDict)
@anchor{library/typing typing TypedDict __readonly_keys__}@anchor{4761}
@deffn {Ιδιότητα} __readonly_keys__

A @ref{9d4,,frozenset} containing the names of all read-only keys. Keys
are read-only if they carry the @ref{696,,ReadOnly} qualifier.


Added in version 3.13.

@end deffn

@geindex __mutable_keys__ (ιδιότητα της typing.TypedDict)
@anchor{library/typing typing TypedDict __mutable_keys__}@anchor{4762}
@deffn {Ιδιότητα} __mutable_keys__

A @ref{9d4,,frozenset} containing the names of all mutable keys. Keys
are mutable if they do not carry the @ref{696,,ReadOnly} qualifier.


Added in version 3.13.

@end deffn

@geindex __closed__ (ιδιότητα της typing.TypedDict)
@anchor{library/typing typing TypedDict __closed__}@anchor{4763}
@deffn {Ιδιότητα} __closed__

The value of the `closed' class argument. It can be @code{True}, @code{False}, or @ref{a65,,None}.
@end deffn

@geindex __extra_items__ (ιδιότητα της typing.TypedDict)
@anchor{library/typing typing TypedDict __extra_items__}@anchor{4764}
@deffn {Ιδιότητα} __extra_items__

The value of the `extra_items' class argument. It can be a valid type or @ref{4765,,NoExtraItems}.
@end deffn

See the TypedDict@footnote{https://typing.python.org/en/latest/spec/typeddict.html#typeddict} section in the typing documentation for more examples and detailed rules.


Added in version 3.8.



Άλλαξε στην έκδοση 3.9: @code{TypedDict} is now a function rather than a class.
It can still be used as a class base, as described above.



Άλλαξε στην έκδοση 3.11: Added support for marking individual keys as @ref{9c2,,Required} or @ref{9c3,,NotRequired}.
See 
@geindex Python Enhancement Proposals; PEP 655
PEP 655@footnote{https://peps.python.org/pep-0655/}.



Άλλαξε στην έκδοση 3.11: Added support for generic @code{TypedDict}s.



Άλλαξε στην έκδοση 3.13: Removed support for the keyword-argument method of creating @code{TypedDict}s.



Άλλαξε στην έκδοση 3.13: Support for the @ref{696,,ReadOnly} qualifier was added. See 
@geindex Python Enhancement Proposals; PEP 705
PEP 705@footnote{https://peps.python.org/pep-0705/}.



Άλλαξε στην έκδοση 3.15: Support for the `closed' and `extra_items' class arguments was added. See 
@geindex Python Enhancement Proposals; PEP 728
PEP 728@footnote{https://peps.python.org/pep-0728/}.

@end deffn

@node Protocols<4>,ABCs and Protocols for working with I/O,Special typing primitives,Module contents<5>
@anchor{library/typing protocols}@anchor{4766}
@subsubsection Protocols


The following protocols are provided by the @code{typing} module. All are decorated
with @ref{861,,@@runtime_checkable}.

@geindex SupportsAbs (κλάση σε typing)
@anchor{library/typing typing SupportsAbs}@anchor{4767}
@deffn {Κλάση} typing.SupportsAbs

An ABC with one abstract method @code{__abs__} that is covariant
in its return type.
@end deffn

@geindex SupportsBytes (κλάση σε typing)
@anchor{library/typing typing SupportsBytes}@anchor{9e1}
@deffn {Κλάση} typing.SupportsBytes

An ABC with one abstract method @code{__bytes__}.
@end deffn

@geindex SupportsComplex (κλάση σε typing)
@anchor{library/typing typing SupportsComplex}@anchor{9e0}
@deffn {Κλάση} typing.SupportsComplex

An ABC with one abstract method @code{__complex__}.
@end deffn

@geindex SupportsFloat (κλάση σε typing)
@anchor{library/typing typing SupportsFloat}@anchor{4768}
@deffn {Κλάση} typing.SupportsFloat

An ABC with one abstract method @code{__float__}.
@end deffn

@geindex SupportsIndex (κλάση σε typing)
@anchor{library/typing typing SupportsIndex}@anchor{e09}
@deffn {Κλάση} typing.SupportsIndex

An ABC with one abstract method @code{__index__}.


Added in version 3.8.

@end deffn

@geindex SupportsInt (κλάση σε typing)
@anchor{library/typing typing SupportsInt}@anchor{e08}
@deffn {Κλάση} typing.SupportsInt

An ABC with one abstract method @code{__int__}.
@end deffn

@geindex SupportsRound (κλάση σε typing)
@anchor{library/typing typing SupportsRound}@anchor{4769}
@deffn {Κλάση} typing.SupportsRound

An ABC with one abstract method @code{__round__}
that is covariant in its return type.
@end deffn

@node ABCs and Protocols for working with I/O,Functions and decorators,Protocols<4>,Module contents<5>
@anchor{library/typing abcs-and-protocols-for-working-with-i-o}@anchor{476a}@anchor{library/typing typing-io}@anchor{3383}
@subsubsection ABCs and Protocols for working with I/O


@geindex IO (κλάση σε typing)
@geindex TextIO (κλάση σε typing)
@geindex BinaryIO (κλάση σε typing)
@anchor{library/typing typing IO}@anchor{4c6}
@deffn {Κλάση} typing.IO [AnyStr]
@anchor{library/typing typing TextIO}@anchor{4c7}
@deffnx {Κλάση} typing.TextIO
@anchor{library/typing typing BinaryIO}@anchor{4c8}
@deffnx {Κλάση} typing.BinaryIO

Generic class @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{32b,,open()}. Please note that these classes are not protocols, and
their interface is fairly broad.
@end deffn

The protocols @ref{4c4,,io.Reader} and @ref{4c5,,io.Writer} offer a simpler
alternative for argument types, when only the @code{read()} or @code{write()}
methods are accessed, respectively:

@example
def read_and_write(reader: Reader[str], writer: Writer[bytes]):
    data = reader.read()
    writer.write(data.encode())
@end example

Also consider using @ref{28aa,,collections.abc.Iterable} for iterating over
the lines of an input stream:

@example
def read_config(stream: Iterable[str]):
    for line in stream:
        ...
@end example

@node Functions and decorators,Introspection helpers,ABCs and Protocols for working with I/O,Module contents<5>
@anchor{library/typing functions-and-decorators}@anchor{476b}
@subsubsection Functions and decorators


@geindex cast() (στη μονάδα typing)
@anchor{library/typing typing cast}@anchor{474a}
@deffn {Συνάρτηση} typing.cast (typ, val)

Cast a value to a type.

This returns the value unchanged.  To the type checker this
signals that the return value has the designated type, but at
runtime we intentionally don’t check anything (we want this
to be as fast as possible).
@end deffn

@geindex assert_type() (στη μονάδα typing)
@anchor{library/typing typing assert_type}@anchor{a99}
@deffn {Συνάρτηση} typing.assert_type (val, typ, /)

Ask a static type checker to confirm that `val' has an inferred type of `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

This function is useful for ensuring the type checker’s understanding of a
script is in line with the developer’s intentions:

@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


Added in version 3.11.

@end deffn

@geindex assert_never() (στη μονάδα typing)
@anchor{library/typing typing assert_never}@anchor{a95}
@deffn {Συνάρτηση} typing.assert_never (arg, /)

Ask a static type checker to confirm that a line of code is unreachable.

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{326,,int} or a @ref{1df,,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{327,,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{a96,,Never}, and nothing
else.

At runtime, this throws an exception when called.


@subsubheading Δείτε επίσης


Unreachable Code and Exhaustiveness Checking@footnote{https://typing.python.org/en/latest/guides/unreachable.html} has more
information about exhaustiveness checking with static typing.



Added in version 3.11.

@end deffn

@geindex reveal_type() (στη μονάδα typing)
@anchor{library/typing typing reveal_type}@anchor{a98}
@deffn {Συνάρτηση} 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

This can be useful when you want to debug how your type checker
handles a particular piece of code.

At runtime, this function prints the runtime type of its argument to
@ref{d05,,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.


Added in version 3.11.

@end deffn

@geindex dataclass_transform() (στη μονάδα typing)
@anchor{library/typing typing dataclass_transform}@anchor{8e4}
@deffn {Συνάρτηση} @@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{6e6,,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{6e6,,@@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

On a base class:

@example
@@dataclass_transform()
class ModelBase: ...

class CustomerModel(ModelBase):
    id: int
    name: str
@end example

On a metaclass:

@example
@@dataclass_transform()
class ModelMeta(type): ...

class ModelBase(metaclass=ModelMeta): ...

class CustomerModel(ModelBase):
    id: int
    name: str
@end example

The @code{CustomerModel} classes defined above will
be treated by type checkers similarly to classes created with
@ref{6e6,,@@dataclasses.dataclass}.
For example, type checkers will assume these classes have
@code{__init__} methods that accept @code{id} and @code{name}.

The decorated class, metaclass, or function may accept the following bool
arguments which type checkers will assume have the same effect as they
would have on the
@ref{6e6,,@@dataclasses.dataclass} decorator: @code{init},
@code{eq}, @code{order}, @code{unsafe_hash}, @code{frozen}, @code{match_args},
@code{kw_only}, and @code{slots}. It must be possible for the value of these
arguments (@code{True} or @code{False}) to be statically evaluated.

The arguments to the @code{dataclass_transform} decorator can be used to
customize the default behaviors of the decorated class, metaclass, or
function:

@*Παράμετροι: 

@itemize *

@item 
@code{eq_default} (@ref{5ef,,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{5ef,,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{5ef,,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{5ef,,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}.


Added in version 3.12.



@item 
@code{field_specifiers} (@ref{1ce,,tuple}@code{[}@ref{bc6,,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{1945,,dataclasses.field()}.
Defaults to @code{()}.

@item 
@code{**kwargs} (@code{Any}) – Arbitrary other keyword arguments are accepted in order to allow for
possible future 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


At runtime, this decorator records its arguments in the
@code{__dataclass_transform__} attribute on the decorated object.
It has no other runtime effect.

See 
@geindex Python Enhancement Proposals; PEP 681
PEP 681@footnote{https://peps.python.org/pep-0681/} for more details.


Added in version 3.11.

@end deffn

@geindex overload() (στη μονάδα typing)
@anchor{library/typing overload}@anchor{4723}@anchor{library/typing typing overload}@anchor{476c}
@deffn {Συνάρτηση} @@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{59a,,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.


Άλλαξε στην έκδοση 3.11: Overloaded functions can now be introspected at runtime using
@ref{a9c,,get_overloads()}.

@end deffn

@geindex get_overloads() (στη μονάδα typing)
@anchor{library/typing typing get_overloads}@anchor{a9c}
@deffn {Συνάρτηση} typing.get_overloads (func)

Return a sequence of @ref{476c,,@@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{476c,,@@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()} can be used for introspecting an overloaded function at
runtime.


Added in version 3.11.

@end deffn

@geindex clear_overloads() (στη μονάδα typing)
@anchor{library/typing typing clear_overloads}@anchor{a9d}
@deffn {Συνάρτηση} typing.clear_overloads ()

Clear all registered overloads in the internal registry.

This can be used to reclaim the memory used by the registry.


Added in version 3.11.

@end deffn

@geindex final() (στη μονάδα typing)
@anchor{library/typing typing final}@anchor{a9b}
@deffn {Συνάρτηση} @@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.

For example:

@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

There is no runtime checking of these properties. See 
@geindex Python Enhancement Proposals; PEP 591
PEP 591@footnote{https://peps.python.org/pep-0591/} for
more details.


Added in version 3.8.



Άλλαξε στην έκδοση 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() (στη μονάδα typing)
@anchor{library/typing typing no_type_check}@anchor{aa1}
@deffn {Συνάρτηση} @@typing.no_type_check

Decorator to indicate that annotations are not type hints.

This works as a class or function @ref{b18,,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 override() (στη μονάδα typing)
@anchor{library/typing typing override}@anchor{869}
@deffn {Συνάρτηση} @@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.


Added in version 3.12.

@end deffn

@geindex disjoint_base() (στη μονάδα typing)
@anchor{library/typing typing disjoint_base}@anchor{292}
@deffn {Συνάρτηση} @@typing.disjoint_base

Decorator to mark a class as a disjoint base.

Type checkers do not allow child classes of a disjoint base @code{C} to
inherit from other disjoint bases that are not parent or child classes of @code{C}.

For example:

@example
@@disjoint_base
class Disjoint1: pass

@@disjoint_base
class Disjoint2: pass

class Disjoint3(Disjoint1, Disjoint2): pass  # Type checker error
@end example

Type checkers can use knowledge of disjoint bases to detect unreachable code
and determine when two types can overlap.

The corresponding runtime concept is a solid base (see @ref{2291,,Multiple inheritance}).
Classes that are solid bases at runtime can be marked with @code{@@disjoint_base} in stub files.
Users may also mark other classes as disjoint bases to indicate to type checkers that
multiple inheritance with other disjoint bases should not be allowed.

Note that the concept of a solid base is a CPython implementation
detail, and the exact set of standard library classes that are
disjoint bases at runtime may change in future versions of Python.


Added in version 3.15.

@end deffn

@geindex type_check_only() (στη μονάδα typing)
@anchor{library/typing typing type_check_only}@anchor{476d}
@deffn {Συνάρτηση} @@typing.type_check_only

Decorator to mark a class or function as unavailable at runtime.

This decorator is itself not available at runtime. It is mainly
intended to mark classes that are defined in type stub files if
an implementation returns an instance of a private class:

@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

Note that returning instances of private classes is not recommended.
It is usually preferable to make such classes public.
@end deffn

@node Introspection helpers,Constant,Functions and decorators,Module contents<5>
@anchor{library/typing introspection-helpers}@anchor{476e}
@subsubsection Introspection helpers


@geindex get_type_hints() (στη μονάδα typing)
@anchor{library/typing typing get_type_hints}@anchor{a9e}
@deffn {Συνάρτηση} typing.get_type_hints (obj, globalns=None, localns=None, include_extras=False, *, format=Format.VALUE)

Return a dictionary containing type hints for a function, method, module,
class object, or other callable object.

This is often the same as @ref{66c,,annotationlib.get_annotations()}, but this
function makes the following changes to the annotations dictionary:


@itemize *

@item 
Forward references encoded as string literals or @ref{1dd3,,ForwardRef}
objects are handled by evaluating them in `globalns', `localns', and
(where applicable) `obj'’s @ref{7a5,,type parameter} namespace.
If `globalns' or `localns' is not given, appropriate namespace
dictionaries are inferred from `obj'.

@item 
@code{None} is replaced with @ref{c2a,,types.NoneType}.

@item 
If @ref{aa1,,@@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{2569,,C.__mro__} and iteratively
combining
@ref{110a,,annotations} of each base class. Annotations
on classes appearing earlier in the @ref{2784,,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, ...]}, @code{Required[T]}, @code{NotRequired[T]}, and @code{ReadOnly[T]}
with @code{T}, unless `include_extras' is set to @code{True} (see
@ref{d09,,Annotated} for more information).
@end itemize

@cartouche
@quotation Προσοχή 
This function may execute arbitrary code contained in annotations.
See @ref{476f,,Security implications of introspecting annotations} for more information.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
If @ref{40b,,Format.VALUE} is used and any
forward references in the annotations of `obj' are not resolvable, a
@ref{665,,NameError} exception is raised. For example, this can happen
with names imported under @ref{10b0,,if TYPE_CHECKING}.
More generally, any kind of exception can be raised if an annotation
contains invalid Python code.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Calling @code{get_type_hints()} on an instance is not supported.
To retrieve annotations for an instance, call
@code{get_type_hints()} on the instance’s class instead
(for example, @code{get_type_hints(type(obj))}).
@end quotation
@end cartouche


Άλλαξε στην έκδοση 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{d09,,Annotated} for more information.



Άλλαξε στην έκδοση 3.11: Previously, @code{Optional[t]} was added for function and method annotations
if a default value equal to @code{None} was set.
Now the annotation is returned unchanged.



Άλλαξε στην έκδοση 3.14: Added the @code{format} parameter. See the documentation on
@ref{66c,,annotationlib.get_annotations()} for more information.



Άλλαξε στην έκδοση 3.14: Calling @code{get_type_hints()} on instances is no longer supported.
Some instances were accepted in earlier versions as an undocumented
implementation detail.

@end deffn

@geindex get_origin() (στη μονάδα typing)
@anchor{library/typing typing get_origin}@anchor{314}
@deffn {Συνάρτηση} 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{1e,,collections} class, it will be normalized to the original class.
If @code{X} is an instance of @ref{ba6,,ParamSpecArgs} or @ref{ba7,,ParamSpecKwargs},
return the underlying @ref{295,,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


Added in version 3.8.

@end deffn

@geindex get_args() (στη μονάδα typing)
@anchor{library/typing typing get_args}@anchor{315}
@deffn {Συνάρτηση} 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{c2d,,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


Added in version 3.8.

@end deffn

@geindex get_protocol_members() (στη μονάδα typing)
@anchor{library/typing typing get_protocol_members}@anchor{76b}
@deffn {Συνάρτηση} typing.get_protocol_members (tp)

Return the set of members defined in a @ref{76c,,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{291,,TypeError} for arguments that are not Protocols.


Added in version 3.13.

@end deffn

@geindex is_protocol() (στη μονάδα typing)
@anchor{library/typing typing is_protocol}@anchor{76d}
@deffn {Συνάρτηση} typing.is_protocol (tp)

Determine if a type is a @ref{76c,,Protocol}.

For example:

@example
class P(Protocol):
    def a(self) -> str: ...
    b: int

is_protocol(P)    # => True
is_protocol(int)  # => False
@end example


Added in version 3.13.

@end deffn

@geindex is_typeddict() (στη μονάδα typing)
@anchor{library/typing typing is_typeddict}@anchor{c2e}
@deffn {Συνάρτηση} typing.is_typeddict (tp)

Check if a type is a @ref{290,,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


Added in version 3.10.

@end deffn

@geindex ForwardRef (κλάση σε typing)
@anchor{library/typing typing ForwardRef}@anchor{1dd3}
@deffn {Κλάση} 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 Σημείωση 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} generic types such as @code{list["SomeClass"]} will not be
implicitly transformed into @code{list[ForwardRef("SomeClass")]} and thus
will not automatically resolve to @code{list[SomeClass]}.
@end quotation
@end cartouche


Added in version 3.7.4.



Άλλαξε στην έκδοση 3.14: This is now an alias for @ref{1967,,annotationlib.ForwardRef}. Several undocumented
behaviors of this class have been changed; for example, after a @code{ForwardRef} has
been evaluated, the evaluated value is no longer cached.

@end deffn

@geindex evaluate_forward_ref() (στη μονάδα typing)
@anchor{library/typing typing evaluate_forward_ref}@anchor{151}
@deffn {Συνάρτηση} typing.evaluate_forward_ref (forward_ref, *, owner=None, globals=None, locals=None, type_params=None, format=annotationlib.Format.VALUE)

Evaluate an @ref{1967,,annotationlib.ForwardRef} as a @ref{25c1,,type hint}.

This is similar to calling @ref{150,,annotationlib.ForwardRef.evaluate()},
but unlike that method, @code{evaluate_forward_ref()} also
recursively evaluates forward references nested within the type hint.

See the documentation for @ref{150,,annotationlib.ForwardRef.evaluate()} for
the meaning of the `owner', `globals', `locals', `type_params', and `format' parameters.

@cartouche
@quotation Προσοχή 
This function may execute arbitrary code contained in annotations.
See @ref{476f,,Security implications of introspecting annotations} for more information.
@end quotation
@end cartouche


Added in version 3.14.

@end deffn

@geindex NoDefault (στη μονάδα typing)
@anchor{library/typing typing NoDefault}@anchor{76a}
@deffn {Δεδομένα} 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


Added in version 3.13.

@end deffn

@geindex NoExtraItems (στη μονάδα typing)
@anchor{library/typing typing NoExtraItems}@anchor{4765}
@deffn {Δεδομένα} typing.NoExtraItems

A @ref{18b,,sentinel} object used to indicate that a @ref{290,,TypedDict}
does not have the `extra_items' class argument.

@example
>>> from typing import TypedDict, NoExtraItems
>>> class Point(TypedDict):
...     x: int
...     y: int
...
>>> Point.__extra_items__ is NoExtraItems
True
@end example
@end deffn

@node Constant,Deprecated aliases,Introspection helpers,Module contents<5>
@anchor{library/typing constant}@anchor{4770}
@subsubsection Constant


@geindex TYPE_CHECKING (στη μονάδα typing)
@anchor{library/typing typing TYPE_CHECKING}@anchor{10b0}
@deffn {Δεδομένα} typing.TYPE_CHECKING

A special constant that is assumed to be @code{True} by 3rd party static
type checkers. It’s @code{False} at runtime.

A module which is expensive to import, and which only contain types
used for typing annotations, can be safely imported inside an
@code{if TYPE_CHECKING:} block.  This prevents the module from actually
being imported at runtime; annotations aren’t eagerly evaluated
(see 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/}) so using undefined symbols in annotations is
harmless–as long as you don’t later examine them.
Your static type analysis tool will set @code{TYPE_CHECKING} to
@code{True} during static type analysis, which means the module will
be imported and the types will be checked properly during such analysis.

Usage:

@example
if TYPE_CHECKING:
    import expensive_mod

def fun(arg: expensive_mod.SomeType) -> None:
    local_var: expensive_mod.AnotherType = other_fun()
@end example

If you occasionally need to examine type annotations at runtime
which may contain undefined symbols, use
@ref{66c,,annotationlib.get_annotations()} with a @code{format} parameter
of @ref{40d,,annotationlib.Format.STRING} or
@ref{40c,,annotationlib.Format.FORWARDREF} to safely retrieve the
annotations without raising @ref{665,,NameError}.


Added in version 3.5.2.

@end deffn
@anchor{library/typing generic-concrete-collections}@anchor{4771}
@node Deprecated aliases,,Constant,Module contents<5>
@anchor{library/typing deprecated-aliases}@anchor{4772}@anchor{library/typing id6}@anchor{4773}
@subsubsection Deprecated aliases


This module defines several deprecated aliases to pre-existing
standard library classes. These were originally included in the @code{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 @code{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{4774}@anchor{library/typing corresponding-to-built-in-types}@anchor{4775}
@subsubsection Aliases to built-in types


@geindex Dict (κλάση σε typing)
@anchor{library/typing typing Dict}@anchor{4776}
@deffn {Κλάση} typing.Dict (dict, MutableMapping[KT, VT])

Deprecated alias to @ref{188,,dict}.

Note that to annotate arguments, it is preferred
to use an abstract collection type such as @ref{c9c,,Mapping}
rather than to use @ref{188,,dict} or @code{typing.Dict}.


Αποσύρθηκε στην έκδοση 3.9: @ref{188,,builtins.dict} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex List (κλάση σε typing)
@anchor{library/typing typing List}@anchor{4777}
@deffn {Κλάση} typing.List (list, MutableSequence[T])

Deprecated alias to @ref{4d9,,list}.

Note that to annotate arguments, it is preferred
to use an abstract collection type such as
@ref{156d,,Sequence} or @ref{28aa,,Iterable}
rather than to use @ref{4d9,,list} or @code{typing.List}.


Αποσύρθηκε στην έκδοση 3.9: @ref{4d9,,builtins.list} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Set (κλάση σε typing)
@anchor{library/typing typing Set}@anchor{4778}
@deffn {Κλάση} typing.Set (set, MutableSet[T])

Deprecated alias to @ref{42b,,builtins.set}.

Note that to annotate arguments, it is preferred
to use an abstract collection type such as @ref{28a1,,collections.abc.Set}
rather than to use @ref{42b,,set} or @ref{4778,,typing.Set}.


Αποσύρθηκε στην έκδοση 3.9: @ref{42b,,builtins.set} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex FrozenSet (κλάση σε typing)
@anchor{library/typing typing FrozenSet}@anchor{4779}
@deffn {Κλάση} typing.FrozenSet (frozenset, AbstractSet[T_co])

Deprecated alias to @ref{9d4,,builtins.frozenset}.


Αποσύρθηκε στην έκδοση 3.9: @ref{9d4,,builtins.frozenset}
now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Tuple (στη μονάδα typing)
@anchor{library/typing typing Tuple}@anchor{477a}
@deffn {Δεδομένα} typing.Tuple

Deprecated alias for @ref{1ce,,tuple}.

@ref{1ce,,tuple} and @code{Tuple} are special-cased in the type system; see
@ref{28cc,,Annotating tuples} for more details.


Αποσύρθηκε στην έκδοση 3.9: @ref{1ce,,builtins.tuple} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Type (κλάση σε typing)
@anchor{library/typing typing Type}@anchor{4728}
@deffn {Κλάση} typing.Type (Generic[CT_co])

Deprecated alias to @ref{186,,type}.

See @ref{4727,,The type of class objects} for details on using @ref{186,,type} or
@code{typing.Type} in type annotations.


Added in version 3.5.2.



Αποσύρθηκε στην έκδοση 3.9: @ref{186,,builtins.type} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.

@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{477b}@anchor{library/typing corresponding-to-types-in-collections}@anchor{477c}
@subsubsection Aliases to types in @code{collections}


@geindex DefaultDict (κλάση σε typing)
@anchor{library/typing typing DefaultDict}@anchor{477d}
@deffn {Κλάση} typing.DefaultDict (collections.defaultdict, MutableMapping[KT, VT])

Deprecated alias to @ref{1565,,collections.defaultdict}.


Added in version 3.5.2.



Αποσύρθηκε στην έκδοση 3.9: @ref{1565,,collections.defaultdict} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex OrderedDict (κλάση σε typing)
@anchor{library/typing typing OrderedDict}@anchor{477e}
@deffn {Κλάση} typing.OrderedDict (collections.OrderedDict, MutableMapping[KT, VT])

Deprecated alias to @ref{9d5,,collections.OrderedDict}.


Added in version 3.7.2.



Αποσύρθηκε στην έκδοση 3.9: @ref{9d5,,collections.OrderedDict} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex ChainMap (κλάση σε typing)
@anchor{library/typing typing ChainMap}@anchor{477f}
@deffn {Κλάση} typing.ChainMap (collections.ChainMap, MutableMapping[KT, VT])

Deprecated alias to @ref{fdb,,collections.ChainMap}.


Added in version 3.6.1.



Αποσύρθηκε στην έκδοση 3.9: @ref{fdb,,collections.ChainMap} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Counter (κλάση σε typing)
@anchor{library/typing typing Counter}@anchor{4780}
@deffn {Κλάση} typing.Counter (collections.Counter, Dict[T, int])

Deprecated alias to @ref{204,,collections.Counter}.


Added in version 3.6.1.



Αποσύρθηκε στην έκδοση 3.9: @ref{204,,collections.Counter} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Deque (κλάση σε typing)
@anchor{library/typing typing Deque}@anchor{4781}
@deffn {Κλάση} typing.Deque (deque, MutableSequence[T])

Deprecated alias to @ref{9d6,,collections.deque}.


Added in version 3.6.1.



Αποσύρθηκε στην έκδοση 3.9: @ref{9d6,,collections.deque} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.

@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{4782}@anchor{library/typing other-concrete-types}@anchor{4783}
@subsubsection Aliases to other concrete types


@geindex Pattern (κλάση σε typing)
@geindex Match (κλάση σε typing)
@anchor{library/typing typing Pattern}@anchor{b13}
@deffn {Κλάση} typing.Pattern
@anchor{library/typing typing Match}@anchor{4784}
@deffnx {Κλάση} typing.Match

Deprecated aliases corresponding to the return types from
@ref{f93,,re.compile()} and @ref{15d3,,re.search()}.

These types (and the corresponding functions) are generic over
@ref{7a4,,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]}.


Αποσύρθηκε στην έκδοση 3.9: Classes @code{Pattern} and @code{Match} from @ref{c1,,re} now support @code{[]}.
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Text (κλάση σε typing)
@anchor{library/typing typing Text}@anchor{340}
@deffn {Κλάση} typing.Text

Deprecated alias for @ref{1df,,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}.

Use @code{Text} to indicate that a value must contain a unicode string in
a manner that is compatible with both Python 2 and Python 3:

@example
def add_unicode_checkmark(text: Text) -> Text:
    return text + u' \u2713'
@end example


Added in version 3.5.2.



Αποσύρθηκε στην έκδοση 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{1df,,str} instead of @code{Text}.

@end deffn
@anchor{library/typing abstract-base-classes}@anchor{4785}
@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{4786}@anchor{library/typing corresponding-to-collections-in-collections-abc}@anchor{4787}
@subsubsection Aliases to container ABCs in @code{collections.abc}


@geindex AbstractSet (κλάση σε typing)
@anchor{library/typing typing AbstractSet}@anchor{4788}
@deffn {Κλάση} typing.AbstractSet (Collection[T_co])

Deprecated alias to @ref{28a1,,collections.abc.Set}.


Αποσύρθηκε στην έκδοση 3.9: @ref{28a1,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex ByteString (κλάση σε typing)
@anchor{library/typing typing ByteString}@anchor{2e3}
@deffn {Κλάση} typing.ByteString (Sequence[int])

Deprecated alias to @ref{2cb,,collections.abc.ByteString}.

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj}
implements the @ref{311,,buffer protocol} at runtime. For use in
type annotations, either use @ref{312,,Buffer} or a union
that explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} was originally intended to be an abstract class that
would serve as a supertype of both @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
However, since the ABC never had any methods, knowing that an object was an
instance of @code{ByteString} never actually told you anything useful
about the object. Other common buffer types such as @ref{1d2,,memoryview} were
also never understood as subtypes of @code{ByteString} (either at runtime
or by static type checkers).

See 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} for more details.


Καταργήθηκε από την έκδοση 3.9, θα αφαιρεθεί στην έκδοση 3.17.

@end deffn

@geindex Collection (κλάση σε typing)
@anchor{library/typing typing Collection}@anchor{10af}
@deffn {Κλάση} typing.Collection (Sized, Iterable[T_co], Container[T_co])

Deprecated alias to @ref{1047,,collections.abc.Collection}.


Added in version 3.6.



Αποσύρθηκε στην έκδοση 3.9: @ref{1047,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Container (κλάση σε typing)
@anchor{library/typing typing Container}@anchor{4789}
@deffn {Κλάση} typing.Container (Generic[T_co])

Deprecated alias to @ref{28ac,,collections.abc.Container}.


Αποσύρθηκε στην έκδοση 3.9: @ref{28ac,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex ItemsView (κλάση σε typing)
@anchor{library/typing typing ItemsView}@anchor{478a}
@deffn {Κλάση} typing.ItemsView (MappingView, AbstractSet[tuple[KT_co, VT_co]])

Deprecated alias to @ref{28b0,,collections.abc.ItemsView}.


Αποσύρθηκε στην έκδοση 3.9: @ref{28b0,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex KeysView (κλάση σε typing)
@anchor{library/typing typing KeysView}@anchor{478b}
@deffn {Κλάση} typing.KeysView (MappingView, AbstractSet[KT_co])

Deprecated alias to @ref{28af,,collections.abc.KeysView}.


Αποσύρθηκε στην έκδοση 3.9: @ref{28af,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Mapping (κλάση σε typing)
@anchor{library/typing typing Mapping}@anchor{478c}
@deffn {Κλάση} typing.Mapping (Collection[KT], Generic[KT, VT_co])

Deprecated alias to @ref{c9c,,collections.abc.Mapping}.


Αποσύρθηκε στην έκδοση 3.9: @ref{c9c,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex MappingView (κλάση σε typing)
@anchor{library/typing typing MappingView}@anchor{478d}
@deffn {Κλάση} typing.MappingView (Sized)

Deprecated alias to @ref{28ae,,collections.abc.MappingView}.


Αποσύρθηκε στην έκδοση 3.9: @ref{28ae,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex MutableMapping (κλάση σε typing)
@anchor{library/typing typing MutableMapping}@anchor{478e}
@deffn {Κλάση} typing.MutableMapping (Mapping[KT, VT])

Deprecated alias to @ref{1459,,collections.abc.MutableMapping}.


Αποσύρθηκε στην έκδοση 3.9: @ref{1459,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex MutableSequence (κλάση σε typing)
@anchor{library/typing typing MutableSequence}@anchor{478f}
@deffn {Κλάση} typing.MutableSequence (Sequence[T])

Deprecated alias to @ref{6c6,,collections.abc.MutableSequence}.


Αποσύρθηκε στην έκδοση 3.9: @ref{6c6,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex MutableSet (κλάση σε typing)
@anchor{library/typing typing MutableSet}@anchor{4790}
@deffn {Κλάση} typing.MutableSet (AbstractSet[T])

Deprecated alias to @ref{28ad,,collections.abc.MutableSet}.


Αποσύρθηκε στην έκδοση 3.9: @ref{28ad,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Sequence (κλάση σε typing)
@anchor{library/typing typing Sequence}@anchor{4791}
@deffn {Κλάση} typing.Sequence (Reversible[T_co], Collection[T_co])

Deprecated alias to @ref{156d,,collections.abc.Sequence}.


Αποσύρθηκε στην έκδοση 3.9: @ref{156d,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex ValuesView (κλάση σε typing)
@anchor{library/typing typing ValuesView}@anchor{4792}
@deffn {Κλάση} typing.ValuesView (MappingView, Collection[_VT_co])

Deprecated alias to @ref{28b1,,collections.abc.ValuesView}.


Αποσύρθηκε στην έκδοση 3.9: @ref{28b1,,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{a9f,,Τύπος Generic Alias}.

@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{4793}@anchor{library/typing asynchronous-programming}@anchor{4794}
@subsubsection Aliases to asynchronous ABCs in @code{collections.abc}


@geindex Coroutine (κλάση σε typing)
@anchor{library/typing typing Coroutine}@anchor{1f25}
@deffn {Κλάση} typing.Coroutine (Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])

Deprecated alias to @ref{1195,,collections.abc.Coroutine}.

See @ref{2baf,,Annotating generators and coroutines}
for details on using @ref{1195,,collections.abc.Coroutine}
and @code{typing.Coroutine} in type annotations.


Added in version 3.5.3.



Αποσύρθηκε στην έκδοση 3.9: @ref{1195,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex AsyncGenerator (κλάση σε typing)
@anchor{library/typing typing AsyncGenerator}@anchor{1baf}
@deffn {Κλάση} typing.AsyncGenerator (AsyncIterator[YieldType], Generic[YieldType, SendType])

Deprecated alias to @ref{104a,,collections.abc.AsyncGenerator}.

See @ref{2baf,,Annotating generators and coroutines}
for details on using @ref{104a,,collections.abc.AsyncGenerator}
and @code{typing.AsyncGenerator} in type annotations.


Added in version 3.6.1.



Αποσύρθηκε στην έκδοση 3.9: @ref{104a,,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{a9f,,Τύπος Generic Alias}.



Άλλαξε στην έκδοση 3.13: The @code{SendType} parameter now has a default.

@end deffn

@geindex AsyncIterable (κλάση σε typing)
@anchor{library/typing typing AsyncIterable}@anchor{4795}
@deffn {Κλάση} typing.AsyncIterable (Generic[T_co])

Deprecated alias to @ref{1197,,collections.abc.AsyncIterable}.


Added in version 3.5.2.



Αποσύρθηκε στην έκδοση 3.9: @ref{1197,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex AsyncIterator (κλάση σε typing)
@anchor{library/typing typing AsyncIterator}@anchor{4796}
@deffn {Κλάση} typing.AsyncIterator (AsyncIterable[T_co])

Deprecated alias to @ref{1196,,collections.abc.AsyncIterator}.


Added in version 3.5.2.



Αποσύρθηκε στην έκδοση 3.9: @ref{1196,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Awaitable (κλάση σε typing)
@anchor{library/typing typing Awaitable}@anchor{4797}
@deffn {Κλάση} typing.Awaitable (Generic[T_co])

Deprecated alias to @ref{1194,,collections.abc.Awaitable}.


Added in version 3.5.2.



Αποσύρθηκε στην έκδοση 3.9: @ref{1194,,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{a9f,,Τύπος Generic Alias}.

@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{4798}@anchor{library/typing corresponding-to-other-types-in-collections-abc}@anchor{4799}
@subsubsection Aliases to other ABCs in @code{collections.abc}


@geindex Iterable (κλάση σε typing)
@anchor{library/typing typing Iterable}@anchor{479a}
@deffn {Κλάση} typing.Iterable (Generic[T_co])

Deprecated alias to @ref{28aa,,collections.abc.Iterable}.


Αποσύρθηκε στην έκδοση 3.9: @ref{28aa,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Iterator (κλάση σε typing)
@anchor{library/typing typing Iterator}@anchor{479b}
@deffn {Κλάση} typing.Iterator (Iterable[T_co])

Deprecated alias to @ref{28ab,,collections.abc.Iterator}.


Αποσύρθηκε στην έκδοση 3.9: @ref{28ab,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Callable (στη μονάδα typing)
@anchor{library/typing typing Callable}@anchor{ba5}
@deffn {Δεδομένα} typing.Callable

Deprecated alias to @ref{bc6,,collections.abc.Callable}.

See @ref{28cb,,Annotating callable objects} for details on how to use
@ref{bc6,,collections.abc.Callable} and @code{typing.Callable} in type annotations.


Αποσύρθηκε στην έκδοση 3.9: @ref{bc6,,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{a9f,,Τύπος Generic Alias}.



Άλλαξε στην έκδοση 3.10: @code{Callable} now supports @ref{295,,ParamSpec} and @ref{ba4,,Concatenate}.
See 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} for more details.

@end deffn

@geindex Generator (κλάση σε typing)
@anchor{library/typing typing Generator}@anchor{1bae}
@deffn {Κλάση} typing.Generator (Iterator[YieldType], Generic[YieldType, SendType, ReturnType])

Deprecated alias to @ref{1193,,collections.abc.Generator}.

See @ref{2baf,,Annotating generators and coroutines}
for details on using @ref{1193,,collections.abc.Generator}
and @code{typing.Generator} in type annotations.


Αποσύρθηκε στην έκδοση 3.9: @ref{1193,,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{a9f,,Τύπος Generic Alias}.



Άλλαξε στην έκδοση 3.13: Default values for the send and return types were added.

@end deffn

@geindex Hashable (κλάση σε typing)
@anchor{library/typing typing Hashable}@anchor{900}
@deffn {Κλάση} typing.Hashable

Deprecated alias to @ref{902,,collections.abc.Hashable}.


Αποσύρθηκε στην έκδοση 3.12: Use @ref{902,,collections.abc.Hashable} directly instead.

@end deffn

@geindex Reversible (κλάση σε typing)
@anchor{library/typing typing Reversible}@anchor{479c}
@deffn {Κλάση} typing.Reversible (Iterable[T_co])

Deprecated alias to @ref{1048,,collections.abc.Reversible}.


Αποσύρθηκε στην έκδοση 3.9: @ref{1048,,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{a9f,,Τύπος Generic Alias}.

@end deffn

@geindex Sized (κλάση σε typing)
@anchor{library/typing typing Sized}@anchor{901}
@deffn {Κλάση} typing.Sized

Deprecated alias to @ref{903,,collections.abc.Sized}.


Αποσύρθηκε στην έκδοση 3.12: Use @ref{903,,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{479d}@anchor{library/typing context-manager-types}@anchor{479e}
@subsubsection Aliases to @code{contextlib} ABCs


@geindex ContextManager (κλάση σε typing)
@anchor{library/typing typing ContextManager}@anchor{104e}
@deffn {Κλάση} typing.ContextManager (Generic[T_co, ExitT_co])

Deprecated alias to @ref{104d,,contextlib.AbstractContextManager}.

The first type parameter, @code{T_co}, represents the type returned by
the @ref{9c6,,__enter__()} method. The optional second type parameter, @code{ExitT_co},
which defaults to @code{bool | None}, represents the type returned by the
@ref{16a5,,__exit__()} method.


Added in version 3.5.4.



Αποσύρθηκε στην έκδοση 3.9: @ref{104d,,contextlib.AbstractContextManager}
now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.



Άλλαξε στην έκδοση 3.13: Added the optional second type parameter, @code{ExitT_co}.

@end deffn

@geindex AsyncContextManager (κλάση σε typing)
@anchor{library/typing typing AsyncContextManager}@anchor{1bac}
@deffn {Κλάση} typing.AsyncContextManager (Generic[T_co, AExitT_co])

Deprecated alias to @ref{eeb,,contextlib.AbstractAsyncContextManager}.

The first type parameter, @code{T_co}, represents the type returned by
the @ref{2613,,__aenter__()} method. The optional second type parameter, @code{AExitT_co},
which defaults to @code{bool | None}, represents the type returned by the
@ref{1bad,,__aexit__()} method.


Added in version 3.6.2.



Αποσύρθηκε στην έκδοση 3.9: @ref{eeb,,contextlib.AbstractAsyncContextManager}
now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{a9f,,Τύπος Generic Alias}.



Άλλαξε στην έκδοση 3.13: Added the optional second type parameter, @code{AExitT_co}.

@end deffn

@node Deprecation Timeline of Major Features,,Module contents<5>,typing — Support for type hints
@anchor{library/typing deprecation-timeline-of-major-features}@anchor{479f}
@subsubsection Deprecation Timeline of Major Features


Certain features in @code{typing} are deprecated and may be removed in a future
version of Python. The following table summarizes major deprecations for your
convenience. This is subject to change, and not all deprecations are listed.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Feature

@tab

Deprecated in

@tab

Projected removal

@tab

PEP/issue

@item

@code{typing} versions of standard collections

@tab

3.9

@tab

Undecided (see @ref{4772,,Deprecated aliases} for more information)

@tab

@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/}

@item

@ref{2e3,,typing.ByteString}

@tab

3.9

@tab

3.17

@tab

gh-91896@footnote{https://github.com/python/cpython/issues/91896}

@item

@ref{340,,typing.Text}

@tab

3.11

@tab

Undecided

@tab

gh-92332@footnote{https://github.com/python/cpython/issues/92332}

@item

@ref{900,,typing.Hashable} and @ref{901,,typing.Sized}

@tab

3.12

@tab

Undecided

@tab

gh-94309@footnote{https://github.com/python/cpython/issues/94309}

@item

@ref{ba9,,typing.TypeAlias}

@tab

3.12

@tab

Undecided

@tab

@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}

@item

@ref{7a4,,typing.AnyStr}

@tab

3.13

@tab

3.18

@tab

gh-105578@footnote{https://github.com/python/cpython/issues/105578}

@end multitable


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node pydoc — Documentation generator and online help system,Python Development Mode,typing — Support for type hints,Εργαλεία Ανάπτυξης
@anchor{library/pydoc doc}@anchor{47a0}@anchor{library/pydoc module-pydoc}@anchor{bd}@anchor{library/pydoc pydoc-documentation-generator-and-online-help-system}@anchor{47a1}@anchor{library/pydoc translation-repo}@anchor{47a2}
@subsection @code{pydoc} — Documentation generator and online help system


@geindex module; pydoc

`Source code:' Lib/pydoc.py@footnote{https://github.com/python/cpython/tree/main/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{cf4,,__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{1b52,,inspect.getcomments()}).

The built-in function @ref{ca9,,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

at a shell prompt will display documentation on the @ref{e2,,sys} module, in a
style similar to the manual pages shown by the Unix @code{man} command.  The
argument to @code{pydoc} can be the name of a function, module, or package,
or a dotted reference to a class, method, or function within a module or module
in a package.  If the argument to @code{pydoc} looks like a path (that is,
it contains the path separator for your operating system, such as a slash in
Unix), and refers to an existing Python source file, then documentation is
produced for that file.

@cartouche
@quotation Σημείωση 
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 μεταβλητή περιβάλλοντος; MANPAGER
@code{MANPAGER} or the
@geindex PAGER
@geindex μεταβλητή περιβάλλοντος; PAGER
@code{PAGER} environment variable is set, @code{pydoc} will use its
value as a pagination program. When both are set, 
@geindex MANPAGER
@geindex μεταβλητή περιβάλλοντος; MANPAGER
@code{MANPAGER} is used.

Specifying a @code{-w} flag before the argument will cause HTML documentation
to be written out to a file in the current directory, instead of displaying text
on the console.

Specifying a @code{-k} flag before the argument will search the synopsis
lines of all available modules for the keyword given as the argument, again in a
manner similar to the Unix @code{man} command.  The synopsis line of a
module is the first line of its documentation string.

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.

When @code{pydoc} generates documentation, it uses the current environment
and path to locate modules.  Thus, invoking @code{pydoc spam}
documents precisely the version of the module you would get if you started the
Python interpreter and typed @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.


Άλλαξε στην έκδοση 3.2: Added the @code{-b} option.



Άλλαξε στην έκδοση 3.3: The @code{-g} command line option was removed.



Άλλαξε στην έκδοση 3.4: @code{pydoc} now uses @ref{4bd,,inspect.signature()} rather than
@ref{b1f,,inspect.getfullargspec()} to extract signature information from
callables.



Άλλαξε στην έκδοση 3.7: Added the @code{-n} option.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python Development Mode,doctest — Test interactive Python examples,pydoc — Documentation generator and online help system,Εργαλεία Ανάπτυξης
@anchor{library/devmode doc}@anchor{47a3}@anchor{library/devmode devmode}@anchor{70d}@anchor{library/devmode python-development-mode}@anchor{47a4}@anchor{library/devmode translation-repo}@anchor{47a5}
@subsection Python Development Mode



Added in 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{178,,-X dev} command line option or by
setting the 
@geindex PYTHONDEVMODE
@geindex μεταβλητή περιβάλλοντος; PYTHONDEVMODE
@ref{eb5,,PYTHONDEVMODE} environment variable to @code{1}.

See also @ref{3dc,,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{47a6}
@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{2319,,warning filter}. The
following warnings are shown:


@itemize *

@item 
@ref{2c9,,DeprecationWarning}

@item 
@ref{907,,ImportWarning}

@item 
@ref{c9b,,PendingDeprecationWarning}

@item 
@ref{74f,,ResourceWarning}
@end itemize

Normally, the above warnings are filtered by the default @ref{2319,,warning filters}.

It behaves as if the @ref{1c0,,-W default} command line option is used.

Use the @ref{1c0,,-W error} command line option or set the
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,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{1028,,PyMem_SetupDebugHooks()} C function.

It behaves as if the 
@geindex PYTHONMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,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 μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,PYTHONMALLOC} environment variable to
@code{default}.

@item 
Call @ref{219,,faulthandler.enable()} at Python startup to install handlers for
the @ref{1428,,SIGSEGV}, @ref{1429,,SIGFPE},
@ref{142a,,SIGABRT}, @ref{142b,,SIGBUS} and
@ref{142c,,SIGILL} signals to dump the Python traceback on a crash.

It behaves as if the @ref{178,,-X faulthandler} command line option is
used or if the 
@geindex PYTHONFAULTHANDLER
@geindex μεταβλητή περιβάλλοντος; PYTHONFAULTHANDLER
@ref{142d,,PYTHONFAULTHANDLER} environment variable is set to
@code{1}.

@item 
Enable @ref{2328,,asyncio debug mode}. For example,
@ref{b,,asyncio} checks for coroutines that were not awaited and logs them.

It behaves as if the 
@geindex PYTHONASYNCIODEBUG
@geindex μεταβλητή περιβάλλοντος; PYTHONASYNCIODEBUG
@ref{2327,,PYTHONASYNCIODEBUG} environment variable is set
to @code{1}.

@item 
Check the `encoding' and `errors' arguments for string encoding and decoding
operations. Examples: @ref{32b,,open()}, @ref{ca7,,str.encode()} and
@ref{ca8,,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{70a,,io.IOBase} destructor logs @code{close()} exceptions.

@item 
Set the @ref{206f,,dev_mode} attribute of @ref{a7c,,sys.flags} to
@code{True}.
@end itemize

The Python Development Mode does not enable the @ref{108,,tracemalloc} module by
default, because the overhead cost (to performance and memory) would be too
large. Enabling the @code{tracemalloc} module provides additional information
on the origin of some errors. For example, @ref{74f,,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{431,,-O} command line
option from removing @ref{d31,,assert} statements nor from setting
@ref{bb7,,__debug__} to @code{False}.

The Python Development Mode can only be enabled at the Python startup. Its
value can be read from @ref{a7c,,sys.flags.dev_mode}.


Άλλαξε στην έκδοση 3.8: The @ref{70a,,io.IOBase} destructor now logs @code{close()} exceptions.



Άλλαξε στην έκδοση 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{47a7}
@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{74f,,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{108,,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{47a8}
@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{74f,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node doctest — Test interactive Python examples,unittest — Unit testing framework,Python Development Mode,Εργαλεία Ανάπτυξης
@anchor{library/doctest doc}@anchor{47a9}@anchor{library/doctest doctest-test-interactive-python-examples}@anchor{47aa}@anchor{library/doctest module-doctest}@anchor{3d}@anchor{library/doctest translation-repo}@anchor{47ab}
@subsection @code{doctest} — Test interactive Python examples


@geindex module; doctest

`Source code:' Lib/doctest.py@footnote{https://github.com/python/cpython/tree/main/Lib/doctest.py}


__________________________________________________________________


The @code{doctest} module searches for pieces of text that look like interactive
Python sessions, and then executes those sessions to verify that they work
exactly as shown.  There are several common ways to use doctest:


@itemize *

@item 
To check that a module’s docstrings are up-to-date by verifying that all
interactive examples still work as documented.

@item 
To perform regression testing by verifying that interactive examples from a
test file or a test object work as expected.

@item 
To write tutorial documentation for a package, liberally illustrated with
input-output examples.  Depending on whether the examples or the expository text
are emphasized, this has the flavor of «literate testing» or «executable
documentation».
@end itemize

Here’s a complete but small example module:

@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

If you run @code{example.py} directly from the command line, @code{doctest}
works its magic:

@example
$ python example.py
$
@end example

There’s no output!  That’s normal, and it means all the examples worked.  Pass
@code{-v} to the script, and @code{doctest} prints a detailed log of what
it’s trying, and prints a summary at the end:

@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

And so on, eventually ending with:

@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 @code{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}.


Added in version 3.13: Output is colorized by default and can be
@ref{1af,,controlled using environment variables}.


@menu
* Simple Usage; Checking Examples in Docstrings: Simple Usage Checking Examples in Docstrings. 
* Simple Usage; Checking Examples in a Text File: Simple Usage Checking Examples in a Text File. 
* Command-line Usage:: 
* How It Works:: 
* Basic API:: 
* Unittest API:: 
* Advanced API:: 
* Debugging:: 
* Soapbox:: 

@end menu

@node Simple Usage Checking Examples in Docstrings,Simple Usage Checking Examples in a Text File,,doctest — Test interactive Python examples
@anchor{library/doctest doctest-simple-testmod}@anchor{47ac}@anchor{library/doctest simple-usage-checking-examples-in-docstrings}@anchor{47ad}
@subsubsection Simple Usage: Checking Examples in Docstrings


The simplest way to start using doctest (but not necessarily the way you’ll
continue to do it) is to end each module @code{M} with:

@example
if __name__ == "__main__":
    import doctest
    doctest.testmod()
@end example

@code{doctest} then examines docstrings in module @code{M}.

Running the module as a script causes the examples in the docstrings to get
executed and verified:

@example
python M.py
@end example

This won’t display anything unless an example fails, in which case the failing
example(s) and the cause(s) of the failure(s) are printed to stdout, and the
final line of output is @code{***Test Failed*** N failures.}, where `N' is the
number of examples that failed.

Run it with the @code{-v} switch instead:

@example
python M.py -v
@end example

and a detailed report of all examples tried is printed to standard output, along
with assorted summaries at the end.

You can force verbose mode by passing @code{verbose=True} to @ref{180f,,testmod()}, or
prohibit it by passing @code{verbose=False}.  In either of those cases,
@ref{1609,,sys.argv} is not examined by @code{testmod()} (so passing @code{-v} or not
has no effect).

There is also a command line shortcut for running @ref{180f,,testmod()}, see section
@ref{47ae,,Command-line Usage}.

For more information on @ref{180f,,testmod()}, see section @ref{47af,,Basic API}.

@node Simple Usage Checking Examples in a Text File,Command-line Usage,Simple Usage Checking Examples in Docstrings,doctest — Test interactive Python examples
@anchor{library/doctest doctest-simple-testfile}@anchor{47b0}@anchor{library/doctest simple-usage-checking-examples-in-a-text-file}@anchor{47b1}
@subsubsection Simple Usage: Checking Examples in a Text File


Another simple application of doctest is testing interactive examples in a text
file.  This can be done with the @ref{47b2,,testfile()} function:

@example
import doctest
doctest.testfile("example.txt")
@end example

That short script executes and verifies any interactive Python examples
contained in the file @code{example.txt}.  The file content is treated as if it
were a single giant docstring; the file doesn’t need to contain a Python
program!   For example, perhaps @code{example.txt} contains this:

@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

Running @code{doctest.testfile("example.txt")} then finds the error in this
documentation:

@example
File "./example.txt", line 14, in example.txt
Failed example:
    factorial(6)
Expected:
    120
Got:
    720
@end example

As with @ref{180f,,testmod()}, @ref{47b2,,testfile()} won’t display anything unless an
example fails.  If an example does fail, then the failing example(s) and the
cause(s) of the failure(s) are printed to stdout, using the same format as
@code{testmod()}.

By default, @ref{47b2,,testfile()} looks for files in the calling module’s directory.
See section @ref{47af,,Basic API} for a description of the optional arguments
that can be used to tell it to look for files in other locations.

Like @ref{180f,,testmod()}, @ref{47b2,,testfile()}”s verbosity can be set with the
@code{-v} command-line switch or with the optional keyword argument
`verbose'.

There is also a command line shortcut for running @ref{47b2,,testfile()}, see section
@ref{47ae,,Command-line Usage}.

For more information on @ref{47b2,,testfile()}, see section @ref{47af,,Basic API}.

@node Command-line Usage,How It Works,Simple Usage Checking Examples in a Text File,doctest — Test interactive Python examples
@anchor{library/doctest command-line-usage}@anchor{47b3}@anchor{library/doctest doctest-cli}@anchor{47ae}
@subsubsection Command-line Usage


The @code{doctest} module can be invoked as a script from the command line:

@example
python -m doctest [-v] [-o OPTION] [-f] file [file ...]
@end example

@geindex doctest command line option; -v
@geindex doctest command line option; --verbose
@anchor{library/doctest cmdoption-doctest-v}@anchor{47b4}@anchor{library/doctest cmdoption-doctest-verbose}@anchor{47b5}
@deffn {Option} @w{-}v, @w{-}@w{-}verbose

Detailed report of all examples tried is printed to standard output,
along with assorted summaries at the end:

@example
python -m doctest -v example.py
@end example

This will import @code{example.py} as a standalone module and run
@ref{180f,,testmod()} on it. Note that this may not work correctly if the
file is part of a package and imports other submodules from that package.

If the file name does not end with @code{.py}, @code{doctest} infers
that it must be run with @ref{47b2,,testfile()} instead:

@example
python -m doctest -v example.txt
@end example
@end deffn

@geindex doctest command line option; -o
@geindex doctest command line option; --option
@anchor{library/doctest cmdoption-doctest-o}@anchor{47b6}@anchor{library/doctest cmdoption-doctest-option}@anchor{47b7}
@deffn {Option} @w{-}o, @w{-}@w{-}option <option>

Option flags control various aspects of doctest’s behavior, see section
@ref{12de,,Option Flags}.


Added in version 3.4.

@end deffn

@geindex doctest command line option; -f
@geindex doctest command line option; --fail-fast
@anchor{library/doctest cmdoption-doctest-f}@anchor{47b8}@anchor{library/doctest cmdoption-doctest-fail-fast}@anchor{47b9}
@deffn {Option} @w{-}f, @w{-}@w{-}fail@w{-}fast

This is shorthand for @code{-o FAIL_FAST}.


Added in version 3.4.

@end deffn

@node How It Works,Basic API,Command-line Usage,doctest — Test interactive Python examples
@anchor{library/doctest doctest-how-it-works}@anchor{47ba}@anchor{library/doctest how-it-works}@anchor{47bb}
@subsubsection How It Works


This section examines in detail how doctest works: which docstrings it looks at,
how it finds interactive examples, what execution context it uses, how it
handles exceptions, and how option flags can be used to control its behavior.
This is the information that you need to know to write doctest examples; for
information about actually running doctest on these examples, see the following
sections.

@menu
* Which Docstrings Are Examined?:: 
* How are Docstring Examples Recognized?:: 
* What’s the Execution Context?:: 
* What About Exceptions?:: 
* Option Flags:: 
* Directives:: 
* Warnings: Warnings<2>. 

@end menu

@node Which Docstrings Are Examined?,How are Docstring Examples Recognized?,,How It Works
@anchor{library/doctest doctest-which-docstrings}@anchor{47bc}@anchor{library/doctest which-docstrings-are-examined}@anchor{47bd}
@subsubsection Which Docstrings Are Examined?


The module docstring, and all function, class and method docstrings are
searched.  Objects imported into the module are not searched.

@geindex __test__ (ιδιότητα της module)
@anchor{library/doctest module __test__}@anchor{47be}
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.

Any classes found are recursively searched similarly, to test docstrings in
their contained methods and nested classes.

@cartouche
@quotation Σημείωση 
@code{doctest} can only automatically discover classes and functions that are
defined at the module level or inside other classes.

Since nested classes and functions only exist when an outer function
is called, they cannot be discovered. Define them outside to make them visible.
@end quotation
@end cartouche

@node How are Docstring Examples Recognized?,What’s the Execution Context?,Which Docstrings Are Examined?,How It Works
@anchor{library/doctest doctest-finding-examples}@anchor{47bf}@anchor{library/doctest how-are-docstring-examples-recognized}@anchor{47c0}
@subsubsection How are Docstring Examples Recognized?


In most cases a copy-and-paste of an interactive console session works fine,
but doctest isn’t trying to do an exact emulation of any specific Python shell.

@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

Any expected output must immediately follow the final @code{'>>> '} or @code{'... '}
line containing the code, and the expected output (if any) extends to the next
@code{'>>> '} or all-whitespace line.

The fine print:


@itemize *

@item 
Expected output cannot contain an all-whitespace line, since such a line is
taken to signal the end of expected output.  If expected output does contain a
blank line, put @code{<BLANKLINE>} in your doctest example each place a blank line
is expected.

@item 
All hard tab characters are expanded to spaces, using 8-column tab stops.
Tabs in output generated by the tested code are not modified.  Because any
hard tabs in the sample output `are' expanded, this means that if the code
output includes hard tabs, the only way the doctest can pass is if the
@ref{47c1,,NORMALIZE_WHITESPACE} option or @ref{47c2,,directive}
is in effect.
Alternatively, the test can be rewritten to capture the output and compare it
to an expected value as part of the test.  This handling of tabs in the
source was arrived at through trial and error, and has proven to be the least
error prone way of handling them.  It is possible to use a different
algorithm for handling tabs by writing a custom @ref{47c3,,DocTestParser} class.

@item 
Output to stdout is captured, but not output to stderr (exception tracebacks
are captured via a different means).

@item 
If you continue a line via backslashing in an interactive session, or for any
other reason use a backslash, you should use a raw docstring, which will
preserve your backslashes exactly as you type them:

@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

Otherwise, the backslash will be interpreted as part of the string. For example,
the @code{\n} above would be interpreted as a newline character.  Alternatively, you
can double each backslash in the doctest version (and not use a raw string):

@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 
The starting column doesn’t matter:

@example
>>> assert "Easy!"
      >>> import math
          >>> math.floor(1.9)
          1
@end example

and as many leading whitespace characters are stripped from the expected output
as appeared in the initial @code{'>>> '} line that started the example.
@end itemize

@node What’s the Execution Context?,What About Exceptions?,How are Docstring Examples Recognized?,How It Works
@anchor{library/doctest doctest-execution-context}@anchor{47c4}@anchor{library/doctest what-s-the-execution-context}@anchor{47c5}
@subsubsection What’s the Execution Context?


By default, each time @code{doctest} finds a docstring to test, it uses a
`shallow copy' of @code{M}’s globals, so that running tests doesn’t change the
module’s real globals, and so that one test in @code{M} can’t leave behind
crumbs that accidentally allow another test to work.  This means examples can
freely use any names defined at top-level in @code{M}, and names defined earlier
in the docstring being run. Examples cannot see names defined in other
docstrings.

You can force use of your own dict as the execution context by passing
@code{globs=your_dict} to @ref{180f,,testmod()} or @ref{47b2,,testfile()} instead.

@node What About Exceptions?,Option Flags,What’s the Execution Context?,How It Works
@anchor{library/doctest doctest-exceptions}@anchor{47c6}@anchor{library/doctest what-about-exceptions}@anchor{47c7}
@subsubsection What About Exceptions?


No problem, provided that the traceback is the only output produced by the
example:  just paste in the traceback. @footnote{
Examples containing both expected output and an exception are not supported.
Trying to guess where one ends and the other begins is too error-prone, and that
also makes for a confusing test.
} Since tracebacks contain details
that are likely to change rapidly (for example, exact file paths and line
numbers), this is one case where doctest works hard to be flexible in what it
accepts.

Simple example:

@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

That doctest succeeds if @ref{277,,ValueError} is raised, with the @code{list.remove(x):
x not in list} detail as shown.

The expected output for an exception must start with a traceback header, which
may be either of the following two lines, indented the same as the first line of
the example:

@example
Traceback (most recent call last):
Traceback (innermost last):
@end example

The traceback header is followed by an optional traceback stack, whose contents
are ignored by doctest.  The traceback stack is typically omitted, or copied
verbatim from an interactive session.

The traceback stack is followed by the most interesting part: the line(s)
containing the exception type and detail.  This is usually the last line of a
traceback, but can extend across multiple lines if the exception has a
multi-line detail:

@example
>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: multi
    line
detail
@end example

The last three lines (starting with @ref{277,,ValueError}) are compared against the
exception’s type and detail, and the rest are ignored.

Best practice is to omit the traceback stack, unless it adds significant
documentation value to the example.  So the last example is probably better as:

@example
>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
    ...
ValueError: multi
    line
detail
@end example

Note that tracebacks are treated very specially.  In particular, in the
rewritten example, the use of @code{...} is independent of doctest’s
@ref{1810,,ELLIPSIS} option.  The ellipsis in that example could be left out, or
could just as well be three (or three hundred) commas or digits, or an indented
transcript of a Monty Python skit.

Some details you should read once, but won’t need to remember:


@itemize *

@item 
Doctest can’t guess whether your expected output came from an exception
traceback or from ordinary printing.  So, e.g., an example that expects
@code{ValueError: 42 is prime} will pass whether @ref{277,,ValueError} is actually
raised or if the example merely prints that traceback text.  In practice,
ordinary output rarely begins with a traceback header line, so this doesn’t
create real problems.

@item 
Each line of the traceback stack (if present) must be indented further than
the first line of the example, `or' start with a non-alphanumeric character.
The first line following the traceback header indented the same and starting
with an alphanumeric is taken to be the start of the exception detail.  Of
course this does the right thing for genuine tracebacks.

@item 
When the @ref{16ad,,IGNORE_EXCEPTION_DETAIL} doctest option is specified,
everything following the leftmost colon and any module information in the
exception name is ignored.

@item 
The interactive shell omits the traceback header line for some
@ref{17e,,SyntaxError}s.  But doctest uses the traceback header line to
distinguish exceptions from non-exceptions.  So in the rare case where you need
to test a @code{SyntaxError} that omits the traceback header, you will need to
manually add the traceback header line to your test example.
@end itemize

@geindex ^ (caret);marker


@itemize *

@item 
For some exceptions, Python displays the position of the error using @code{^}
markers and tildes:

@example
>>> 1 + None
  File "<stdin>", line 1
    1 + None
    ~~^~~~~~
TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'
@end example

Since the lines showing the position of the error come before the exception type
and detail, they are not checked by doctest.  For example, the following test
would pass, even though it puts the @code{^} marker in the wrong location:

@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{47c8}
@node Option Flags,Directives,What About Exceptions?,How It Works
@anchor{library/doctest doctest-options}@anchor{12de}@anchor{library/doctest option-flags}@anchor{47c9}
@subsubsection Option Flags


A number of option flags control various aspects of doctest’s behavior.
Symbolic names for the flags are supplied as module constants, which can be
@ref{26c4,,bitwise ORed} together and passed to various functions.
The names can also be used in @ref{47c2,,doctest directives},
and may be passed to the doctest command line interface via the @code{-o} option.

The first group of options define test semantics, controlling aspects of how
doctest decides whether actual output matches an example’s expected output:

@geindex DONT_ACCEPT_TRUE_FOR_1 (στη μονάδα doctest)
@anchor{library/doctest doctest DONT_ACCEPT_TRUE_FOR_1}@anchor{47ca}
@deffn {Δεδομένα} doctest.DONT_ACCEPT_TRUE_FOR_1

By default, if an expected output block contains just @code{1}, an actual output
block containing just @code{1} or just @code{True} is considered to be a match, and
similarly for @code{0} versus @code{False}.  When @ref{47ca,,DONT_ACCEPT_TRUE_FOR_1} is
specified, neither substitution is allowed.  The default behavior caters to that
Python changed the return type of many functions from integer to boolean;
doctests expecting «little integer» output still work in these cases.  This
option will probably go away, but not for several years.
@end deffn

@geindex <BLANKLINE>

@geindex DONT_ACCEPT_BLANKLINE (στη μονάδα doctest)
@anchor{library/doctest doctest DONT_ACCEPT_BLANKLINE}@anchor{47cb}
@deffn {Δεδομένα} doctest.DONT_ACCEPT_BLANKLINE

By default, if an expected output block contains a line containing only the
string @code{<BLANKLINE>}, then that line will match a blank line in the actual
output.  Because a genuinely blank line delimits the expected output, this is
the only way to communicate that a blank line is expected.  When
@ref{47cb,,DONT_ACCEPT_BLANKLINE} is specified, this substitution is not allowed.
@end deffn

@geindex NORMALIZE_WHITESPACE (στη μονάδα doctest)
@anchor{library/doctest doctest NORMALIZE_WHITESPACE}@anchor{47c1}
@deffn {Δεδομένα} doctest.NORMALIZE_WHITESPACE

When specified, all sequences of whitespace (blanks and newlines) are treated as
equal.  Any sequence of whitespace within the expected output will match any
sequence of whitespace within the actual output. By default, whitespace must
match exactly. @ref{47c1,,NORMALIZE_WHITESPACE} is especially useful when a line of
expected output is very long, and you want to wrap it across multiple lines in
your source.
@end deffn

@geindex ...;in doctests

@geindex ELLIPSIS (στη μονάδα doctest)
@anchor{library/doctest doctest ELLIPSIS}@anchor{1810}
@deffn {Δεδομένα} doctest.ELLIPSIS

When specified, an ellipsis marker (@code{...}) in the expected output can match
any substring in the actual output.  This includes substrings that span line
boundaries, and empty substrings, so it’s best to keep usage of this simple.
Complicated uses can lead to the same kinds of «oops, it matched too much!»
surprises that @code{.*} is prone to in regular expressions.
@end deffn

@geindex IGNORE_EXCEPTION_DETAIL (στη μονάδα doctest)
@anchor{library/doctest doctest IGNORE_EXCEPTION_DETAIL}@anchor{16ad}
@deffn {Δεδομένα} 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{291,,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{1810,,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.


Άλλαξε στην έκδοση 3.2: @ref{16ad,,IGNORE_EXCEPTION_DETAIL} now also ignores any information relating
to the module containing the exception under test.

@end deffn

@geindex SKIP (στη μονάδα doctest)
@anchor{library/doctest doctest SKIP}@anchor{47cc}
@deffn {Δεδομένα} doctest.SKIP

When specified, do not run the example at all.  This can be useful in contexts
where doctest examples serve as both documentation and test cases, and an
example should be included for documentation purposes, but should not be
checked.  E.g., the example’s output might be random; or the example might
depend on resources which would be unavailable to the test driver.

The SKIP flag can also be used for temporarily «commenting out» examples.
@end deffn

@geindex COMPARISON_FLAGS (στη μονάδα doctest)
@anchor{library/doctest doctest COMPARISON_FLAGS}@anchor{47cd}
@deffn {Δεδομένα} doctest.COMPARISON_FLAGS

A bitmask or’ing together all the comparison flags above.
@end deffn

The second group of options controls how test failures are reported:

@geindex REPORT_UDIFF (στη μονάδα doctest)
@anchor{library/doctest doctest REPORT_UDIFF}@anchor{1811}
@deffn {Δεδομένα} doctest.REPORT_UDIFF

When specified, failures that involve multi-line expected and actual outputs are
displayed using a unified diff.
@end deffn

@geindex REPORT_CDIFF (στη μονάδα doctest)
@anchor{library/doctest doctest REPORT_CDIFF}@anchor{1812}
@deffn {Δεδομένα} doctest.REPORT_CDIFF

When specified, failures that involve multi-line expected and actual outputs
will be displayed using a context diff.
@end deffn

@geindex REPORT_NDIFF (στη μονάδα doctest)
@anchor{library/doctest doctest REPORT_NDIFF}@anchor{1813}
@deffn {Δεδομένα} doctest.REPORT_NDIFF

When specified, differences are computed by @code{difflib.Differ}, using the same
algorithm as the popular @code{ndiff.py} utility. This is the only method that
marks differences within lines as well as across lines.  For example, if a line
of expected output contains digit @code{1} where actual output contains letter
@code{l}, a line is inserted with a caret marking the mismatching column positions.
@end deffn

@geindex REPORT_ONLY_FIRST_FAILURE (στη μονάδα doctest)
@anchor{library/doctest doctest REPORT_ONLY_FIRST_FAILURE}@anchor{47ce}
@deffn {Δεδομένα} doctest.REPORT_ONLY_FIRST_FAILURE

When specified, display the first failing example in each doctest, but suppress
output for all remaining examples.  This will prevent doctest from reporting
correct examples that break because of earlier failures; but it might also hide
incorrect examples that fail independently of the first failure.  When
@ref{47ce,,REPORT_ONLY_FIRST_FAILURE} is specified, the remaining examples are
still run, and still count towards the total number of failures reported; only
the output is suppressed.
@end deffn

@geindex FAIL_FAST (στη μονάδα doctest)
@anchor{library/doctest doctest FAIL_FAST}@anchor{12df}
@deffn {Δεδομένα} doctest.FAIL_FAST

When specified, exit after the first failing example and don’t attempt to run
the remaining examples. Thus, the number of failures reported will be at most
1.  This flag may be useful during debugging, since examples after the first
failure won’t even produce debugging output.
@end deffn

@geindex REPORTING_FLAGS (στη μονάδα doctest)
@anchor{library/doctest doctest REPORTING_FLAGS}@anchor{47cf}
@deffn {Δεδομένα} doctest.REPORTING_FLAGS

A bitmask or’ing together all the reporting flags above.
@end deffn

There is also a way to register new option flag names, though this isn’t
useful unless you intend to extend @code{doctest} internals via subclassing:

@geindex register_optionflag() (στη μονάδα doctest)
@anchor{library/doctest doctest register_optionflag}@anchor{47d0}
@deffn {Συνάρτηση} doctest.register_optionflag (name)

Create a new option flag with a given name, and return the new flag’s integer
value.  @code{register_optionflag()} can be used when subclassing
@ref{47d1,,OutputChecker} or @ref{47d2,,DocTestRunner} to create new options that are
supported by your subclasses.  @code{register_optionflag()} should always be
called using the following idiom:

@example
MY_FLAG = register_optionflag('MY_FLAG')
@end example
@end deffn

@geindex # (hash);in doctests
@geindex + (plus);in doctests
@geindex - (minus);in doctests

@node Directives,Warnings<2>,Option Flags,How It Works
@anchor{library/doctest directives}@anchor{47d3}@anchor{library/doctest doctest-directives}@anchor{47c2}
@subsubsection Directives


Doctest directives may be used to modify the @ref{12de,,option flags} for an individual example.  Doctest directives are
special Python comments following an example’s source code:

@example
@anchor{library/doctest grammar-token-doctest-directive}@anchor{47d4}directive:             "#" "doctest:" @ref{47d5,,directive_options}
@anchor{library/doctest grammar-token-doctest-directive_options}@anchor{47d5}directive_options:     @ref{47d6,,directive_option} ("," @ref{47d6,,directive_option})*
@anchor{library/doctest grammar-token-doctest-directive_option}@anchor{47d6}directive_option:      @ref{47d7,,on_or_off} @ref{47d8,,directive_option_name}
@anchor{library/doctest grammar-token-doctest-on_or_off}@anchor{47d7}on_or_off:             "+" | "-"
@anchor{library/doctest grammar-token-doctest-directive_option_name}@anchor{47d8}directive_option_name: "DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...
@end example

Whitespace is not allowed between the @code{+} or @code{-} and the directive option
name.  The directive option name can be any of the option flag names explained
above.

An example’s doctest directives modify doctest’s behavior for that single
example.  Use @code{+} to enable the named behavior, or @code{-} to disable it.

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

Note that since all options are disabled by default, and directives apply only
to the example they appear in, enabling options (via @code{+} in a directive) is
usually the only meaningful choice.  However, option flags can also be passed to
functions that run doctests, establishing different defaults.  In such cases,
disabling an option via @code{-} in a directive can be useful.

@node Warnings<2>,,Directives,How It Works
@anchor{library/doctest doctest-warnings}@anchor{47d9}@anchor{library/doctest warnings}@anchor{47da}
@subsubsection Warnings


@code{doctest} is serious about requiring exact matches in expected output.  If
even a single character doesn’t match, the test fails.  This will probably
surprise you a few times, as you learn exactly what Python does and doesn’t
guarantee about output.  For example, when printing a set, Python doesn’t
guarantee that the element is printed in any particular order, so a test like

@example
>>> foo()
@{"spam", "eggs"@}
@end example

is vulnerable!  One workaround is to do

@example
>>> foo() == @{"spam", "eggs"@}
True
@end example

instead.  Another is to do

@example
>>> d = sorted(foo())
>>> d
['eggs', 'spam']
@end example

There are others, but you get the idea.

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{1810,,ELLIPSIS} directive gives a nice approach for the last example:

@example
>>> C()  # doctest: +ELLIPSIS
<C object at 0x...>
@end example

Floating-point numbers are also subject to small output variations across
platforms, because Python defers to the platform C library for some
floating-point calculations, and C libraries vary widely in quality here.

@example
>>> 1000**0.1  # risky
1.9952623149688797
>>> round(1000**0.1, 9) # safer
1.995262315
>>> print(f'@{1000**0.1:.4f@}') # much safer
1.9953
@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

Simple fractions are also easier for people to understand, and that makes for
better documentation.

@node Basic API,Unittest API,How It Works,doctest — Test interactive Python examples
@anchor{library/doctest basic-api}@anchor{47db}@anchor{library/doctest doctest-basic-api}@anchor{47af}
@subsubsection Basic API


The functions @ref{180f,,testmod()} and @ref{47b2,,testfile()} provide a simple interface to
doctest that should be sufficient for most basic uses.  For a less formal
introduction to these two functions, see sections @ref{47ac,,Simple Usage; Checking Examples in Docstrings}
and @ref{47b0,,Simple Usage; Checking Examples in a Text File}.

@geindex testfile() (στη μονάδα doctest)
@anchor{library/doctest doctest testfile}@anchor{47b2}
@deffn {Συνάρτηση} 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)

All arguments except `filename' are optional, and should be specified in keyword
form.

Test examples in the file named `filename'.  Return @code{(failure_count,
test_count)}.

Optional argument `module_relative' specifies how the filename should be
interpreted:


@itemize *

@item 
If `module_relative' is @code{True} (the default), then `filename' specifies an
OS-independent module-relative path.  By default, this path is relative to the
calling module’s directory; but if the `package' argument is specified, then it
is relative to that package.  To ensure OS-independence, `filename' should use
@code{/} characters to separate path segments, and may not be an absolute path
(i.e., it may not begin with @code{/}).

@item 
If `module_relative' is @code{False}, then `filename' specifies an OS-specific
path.  The path may be absolute or relative; relative paths are resolved with
respect to the current working directory.
@end itemize

Optional argument `name' gives the name of the test; by default, or if @code{None},
@code{os.path.basename(filename)} is used.

Optional argument `package' is a Python package or the name of a Python package
whose directory should be used as the base directory for a module-relative
filename.  If no package is specified, then the calling module’s directory is
used as the base directory for module-relative filenames.  It is an error to
specify `package' if `module_relative' is @code{False}.

Optional argument `globs' gives a dict to be used as the globals when executing
examples.  A new shallow copy of this dict is created for the doctest, so its
examples start with a clean slate. By default, or if @code{None}, a new empty dict
is used.

Optional argument `extraglobs' gives a dict merged into the globals used to
execute examples.  This works like @ref{1807,,dict.update()}:  if `globs' and
`extraglobs' have a common key, the associated value in `extraglobs' appears in
the combined dict.  By default, or if @code{None}, no extra globals are used.  This
is an advanced feature that allows parameterization of doctests.  For example, a
doctest can be written for a base class, using a generic name for the class,
then reused to test any number of subclasses by passing an `extraglobs' dict
mapping the generic name to the subclass to be tested.

Optional argument `verbose' prints lots of stuff if true, and prints only
failures if false; by default, or if @code{None}, it’s true if and only if @code{'-v'}
is in @ref{1609,,sys.argv}.

Optional argument `report' prints a summary at the end when true, else prints
nothing at the end.  In verbose mode, the summary is detailed, else the summary
is very brief (in fact, empty if all tests passed).

Optional argument `optionflags' (default value @code{0}) takes the
@ref{26c4,,bitwise OR} of option flags.
See section @ref{12de,,Option Flags}.

Optional argument `raise_on_error' defaults to false.  If true, an exception is
raised upon the first failure or unexpected exception in an example.  This
allows failures to be post-mortem debugged. Default behavior is to continue
running examples.

Optional argument `parser' specifies a @ref{47c3,,DocTestParser} (or subclass) that
should be used to extract tests from the files.  It defaults to a normal parser
(i.e., @code{DocTestParser()}).

Optional argument `encoding' specifies an encoding that should be used to
convert the file to unicode.
@end deffn

@geindex testmod() (στη μονάδα doctest)
@anchor{library/doctest doctest testmod}@anchor{180f}
@deffn {Συνάρτηση} doctest.testmod (m=None, name=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False)

All arguments are optional, and all except for `m' should be specified in
keyword form.

Test examples in docstrings in functions and classes reachable from module `m'
(or module @ref{1,,__main__} if `m' is not supplied or is @code{None}), starting with
@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.

Only docstrings attached to objects belonging to module `m' are searched.

Return @code{(failure_count, test_count)}.

Optional argument `name' gives the name of the module; by default, or if
@code{None}, @code{m.__name__} is used.

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{47dc,,doctest.master.summarize} in
conjunction with @code{testmod()} continues to get output for objects with no
tests. The `exclude_empty' argument to the newer @ref{1bb3,,DocTestFinder}
constructor defaults to true.

Optional arguments `extraglobs', `verbose', `report', `optionflags',
`raise_on_error', and `globs' are the same as for function @ref{47b2,,testfile()}
above, except that `globs' defaults to @code{m.__dict__}.
@end deffn

@geindex run_docstring_examples() (στη μονάδα doctest)
@anchor{library/doctest doctest run_docstring_examples}@anchor{47dd}
@deffn {Συνάρτηση} doctest.run_docstring_examples (f, globs, verbose=False, name='NoName', compileflags=None, optionflags=0)

Test examples associated with object `f'; for example, `f' may be a string,
a module, a function, or a class object.

A shallow copy of dictionary argument `globs' is used for the execution context.

Optional argument `name' is used in failure messages, and defaults to
@code{"NoName"}.

If optional argument `verbose' is true, output is generated even if there are no
failures.  By default, output is generated only in case of an example failure.

Optional argument `compileflags' gives the set of flags that should be used by
the Python compiler when running the examples.  By default, or if @code{None},
flags are deduced corresponding to the set of future features found in `globs'.

Optional argument `optionflags' works as for function @ref{47b2,,testfile()} above.
@end deffn

@node Unittest API,Advanced API,Basic API,doctest — Test interactive Python examples
@anchor{library/doctest doctest-unittest-api}@anchor{47de}@anchor{library/doctest unittest-api}@anchor{47df}
@subsubsection Unittest API


As your collection of doctest’ed modules grows, you’ll want a way to run all
their doctests systematically.  @code{doctest} provides two functions that can
be used to create @ref{10f,,unittest} test suites from modules and text files
containing doctests.  To integrate with @code{unittest} test discovery, include
a @ref{47e0,,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

There are two main functions for creating @ref{11ad,,unittest.TestSuite} instances
from text files and modules with doctests:

@geindex DocFileSuite() (στη μονάδα doctest)
@anchor{library/doctest doctest DocFileSuite}@anchor{1a14}
@deffn {Συνάρτηση} doctest.DocFileSuite (*paths, module_relative=True, package=None, setUp=None, tearDown=None, globs=None, optionflags=0, parser=DocTestParser(), encoding=None)

Convert doctest tests from one or more text files to a
@ref{11ad,,unittest.TestSuite}.

The returned @ref{11ad,,unittest.TestSuite} is to be run by the unittest
framework and runs the interactive examples in each file.
Each file is run as a separate unit test, and each example in a file
is run as a @ref{138b,,subtest}.
If any example in a file fails, then the synthesized unit test fails.
The traceback for failure or error contains 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.

Pass one or more paths (as strings) to text files to be examined.

Options may be provided as keyword arguments:

Optional argument `module_relative' specifies how the filenames in `paths'
should be interpreted:


@itemize *

@item 
If `module_relative' is @code{True} (the default), then each filename in
`paths' specifies an OS-independent module-relative path.  By default, this
path is relative to the calling module’s directory; but if the `package'
argument is specified, then it is relative to that package.  To ensure
OS-independence, each filename should use @code{/} characters to separate path
segments, and may not be an absolute path (i.e., it may not begin with
@code{/}).

@item 
If `module_relative' is @code{False}, then each filename in `paths' specifies
an OS-specific path.  The path may be absolute or relative; relative paths
are resolved with respect to the current working directory.
@end itemize

Optional argument `package' is a Python package or the name of a Python
package whose directory should be used as the base directory for
module-relative filenames in `paths'.  If no package is specified, then the
calling module’s directory is used as the base directory for module-relative
filenames.  It is an error to specify `package' if `module_relative' is
@code{False}.

Optional argument `setUp' specifies a set-up function for the test suite.
This is called before running the tests in each file.  The `setUp' function
will be passed a @ref{1c31,,DocTest} object.  The `setUp' function can access the
test globals as the @ref{47e1,,globs} attribute of the test passed.

Optional argument `tearDown' specifies a tear-down function for the test
suite.  This is called after running the tests in each file.  The `tearDown'
function will be passed a @ref{1c31,,DocTest} object.  The `tearDown' function can
access the test globals as the @ref{47e1,,globs} attribute of the test
passed.

Optional argument `globs' is a dictionary containing the initial global
variables for the tests.  A new copy of this dictionary is created for each
test.  By default, `globs' is a new empty dictionary.

Optional argument `optionflags' specifies the default doctest options for the
tests, created by or-ing together individual option flags.  See section
@ref{12de,,Option Flags}. See function @ref{47e2,,set_unittest_reportflags()} below
for a better way to set reporting options.

Optional argument `parser' specifies a @ref{47c3,,DocTestParser} (or subclass)
that should be used to extract tests from the files.  It defaults to a normal
parser (i.e., @code{DocTestParser()}).

Optional argument `encoding' specifies an encoding that should be used to
convert the file to unicode.

The global @code{__file__} is added to the globals provided to doctests loaded
from a text file using @code{DocFileSuite()}.


Άλλαξε στην έκδοση 3.15: Run each example as a @ref{138b,,subtest}.

@end deffn

@geindex DocTestSuite() (στη μονάδα doctest)
@anchor{library/doctest doctest DocTestSuite}@anchor{11ac}
@deffn {Συνάρτηση} doctest.DocTestSuite (module=None, globs=None, extraglobs=None, test_finder=None, setUp=None, tearDown=None, optionflags=0, checker=None)

Convert doctest tests for a module to a @ref{11ad,,unittest.TestSuite}.

The returned @ref{11ad,,unittest.TestSuite} is to be run by the unittest
framework and runs each doctest in the module.
Each docstring is run as a separate unit test, and each example in
a docstring is run as a @ref{138b,,subtest}.
If any of the doctests fail, then the synthesized unit test fails.
The traceback for failure or error contains 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.

Optional argument `module' provides the module to be tested.  It can be a module
object or a (possibly dotted) module name.  If not specified, the module calling
this function is used.

Optional argument `globs' is a dictionary containing the initial global
variables for the tests.  A new copy of this dictionary is created for each
test.  By default, `globs' is the module’s @ref{2561,,__dict__}.

Optional argument `extraglobs' specifies an extra set of global variables, which
is merged into `globs'.  By default, no extra globals are used.

Optional argument `test_finder' is the @ref{1bb3,,DocTestFinder} object (or a
drop-in replacement) that is used to extract doctests from the module.

Optional arguments `setUp', `tearDown', and `optionflags' are the same as for
function @ref{1a14,,DocFileSuite()} above, but they are called for each docstring.

This function uses the same search technique as @ref{180f,,testmod()}.


Άλλαξε στην έκδοση 3.5: @code{DocTestSuite()} returns an empty @ref{11ad,,unittest.TestSuite} if `module'
contains no docstrings instead of raising @ref{277,,ValueError}.



Άλλαξε στην έκδοση 3.15: Run each example as a @ref{138b,,subtest}.

@end deffn

Under the covers, @ref{11ac,,DocTestSuite()} creates a @ref{11ad,,unittest.TestSuite} out
of @code{doctest.DocTestCase} instances, and @code{DocTestCase} is a
subclass of @ref{52f,,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{10f,,unittest} integration.

Similarly, @ref{1a14,,DocFileSuite()} creates a @ref{11ad,,unittest.TestSuite} out of
@code{doctest.DocFileCase} instances, and @code{DocFileCase} is a subclass
of @code{DocTestCase}.

So both ways of creating a @ref{11ad,,unittest.TestSuite} run instances of
@code{DocTestCase}.  This is important for a subtle reason: when you run
@code{doctest} functions yourself, you can control the @code{doctest} options in
use directly, by passing option flags to @code{doctest} functions.  However, if
you’re writing a @ref{10f,,unittest} framework, @code{unittest} ultimately controls
when and how tests get run.  The framework author typically wants to control
@code{doctest} reporting options (perhaps, e.g., specified by command line
options), but there’s no way to pass options through @code{unittest} to
@code{doctest} test runners.

For this reason, @code{doctest} also supports a notion of @code{doctest}
reporting flags specific to @ref{10f,,unittest} support, via this function:

@geindex set_unittest_reportflags() (στη μονάδα doctest)
@anchor{library/doctest doctest set_unittest_reportflags}@anchor{47e2}
@deffn {Συνάρτηση} doctest.set_unittest_reportflags (flags)

Set the @code{doctest} reporting flags to use.

Argument `flags' takes the @ref{26c4,,bitwise OR} of option flags.  See
section @ref{12de,,Option Flags}.  Only «reporting flags» can be used.

This is a module-global setting, and affects all future doctests run by module
@ref{10f,,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 @code{unittest} reporting flags are
@ref{26c4,,bitwise ORed} into the option flags, and the option flags
so augmented are passed to the @ref{47d2,,DocTestRunner} instance created to
run the doctest.  If any reporting flags were specified when the
@code{DocTestCase} instance was constructed, @code{doctest}’s
@code{unittest} reporting flags are ignored.

The value of the @ref{10f,,unittest} reporting flags in effect before the function
was called is returned by the function.
@end deffn

@node Advanced API,Debugging,Unittest API,doctest — Test interactive Python examples
@anchor{library/doctest advanced-api}@anchor{47e3}@anchor{library/doctest doctest-advanced-api}@anchor{47e4}
@subsubsection Advanced API


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{47e5,,Example}: A single Python @ref{2e17,,statement}, paired with its expected
output.

@item 
@ref{1c31,,DocTest}: A collection of @ref{47e5,,Example}s, typically extracted
from a single docstring or text file.
@end itemize

Additional processing classes are defined to find, parse, and run, and check
doctest examples:


@itemize *

@item 
@ref{1bb3,,DocTestFinder}: Finds all docstrings in a given module, and uses a
@ref{47c3,,DocTestParser} to create a @ref{1c31,,DocTest} from every docstring that
contains interactive examples.

@item 
@ref{47c3,,DocTestParser}: Creates a @ref{1c31,,DocTest} object from a string (such
as an object’s docstring).

@item 
@ref{47d2,,DocTestRunner}: Executes the examples in a @ref{1c31,,DocTest}, and uses
an @ref{47d1,,OutputChecker} to verify their output.

@item 
@ref{47d1,,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
* DocTest Objects:: 
* Example Objects:: 
* DocTestFinder objects:: 
* DocTestParser objects:: 
* TestResults objects:: 
* DocTestRunner objects:: 
* OutputChecker objects:: 

@end menu

@node DocTest Objects,Example Objects,,Advanced API
@anchor{library/doctest doctest-doctest}@anchor{47e6}@anchor{library/doctest doctest-objects}@anchor{47e7}
@subsubsection DocTest Objects


@geindex DocTest (κλάση σε doctest)
@anchor{library/doctest doctest DocTest}@anchor{1c31}
@deffn {Κλάση} 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.

@code{DocTest} defines the following attributes.  They are initialized by
the constructor, and should not be modified directly.

@geindex examples (ιδιότητα της doctest.DocTest)
@anchor{library/doctest doctest DocTest examples}@anchor{47e8}
@deffn {Ιδιότητα} examples

A list of @ref{47e5,,Example} objects encoding the individual interactive Python
examples that should be run by this test.
@end deffn

@geindex globs (ιδιότητα της doctest.DocTest)
@anchor{library/doctest doctest DocTest globs}@anchor{47e1}
@deffn {Ιδιότητα} 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{47e1,,globs}
after the test is run.
@end deffn

@geindex name (ιδιότητα της doctest.DocTest)
@anchor{library/doctest doctest DocTest name}@anchor{47e9}
@deffn {Ιδιότητα} name

A string name identifying the @code{DocTest}.  Typically, this is the name
of the object or file that the test was extracted from.
@end deffn

@geindex filename (ιδιότητα της doctest.DocTest)
@anchor{library/doctest doctest DocTest filename}@anchor{47ea}
@deffn {Ιδιότητα} filename

The name of the file that this @code{DocTest} was extracted from; or
@code{None} if the filename is unknown, or if the @code{DocTest} was not
extracted from a file.
@end deffn

@geindex lineno (ιδιότητα της doctest.DocTest)
@anchor{library/doctest doctest DocTest lineno}@anchor{1a07}
@deffn {Ιδιότητα} lineno

The line number within @ref{47ea,,filename} where this @code{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 (ιδιότητα της doctest.DocTest)
@anchor{library/doctest doctest DocTest docstring}@anchor{47eb}
@deffn {Ιδιότητα} 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 Example Objects,DocTestFinder objects,DocTest Objects,Advanced API
@anchor{library/doctest doctest-example}@anchor{47ec}@anchor{library/doctest example-objects}@anchor{47ed}
@subsubsection Example Objects


@geindex Example (κλάση σε doctest)
@anchor{library/doctest doctest Example}@anchor{47e5}
@deffn {Κλάση} 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.

@code{Example} defines the following attributes.  They are initialized by
the constructor, and should not be modified directly.

@geindex source (ιδιότητα της doctest.Example)
@anchor{library/doctest doctest Example source}@anchor{47ee}
@deffn {Ιδιότητα} 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 (ιδιότητα της doctest.Example)
@anchor{library/doctest doctest Example want}@anchor{47ef}
@deffn {Ιδιότητα} want

The expected output from running the example’s source code (either from
stdout, or a traceback in case of exception).  @ref{47ef,,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 (ιδιότητα της doctest.Example)
@anchor{library/doctest doctest Example exc_msg}@anchor{47f0}
@deffn {Ιδιότητα} 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{c26,,traceback.format_exception_only()}.  @ref{47f0,,exc_msg} ends with a newline
unless it’s @code{None}.  The constructor adds a newline if needed.
@end deffn

@geindex lineno (ιδιότητα της doctest.Example)
@anchor{library/doctest doctest Example lineno}@anchor{47f1}
@deffn {Ιδιότητα} 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 (ιδιότητα της doctest.Example)
@anchor{library/doctest doctest Example indent}@anchor{47f2}
@deffn {Ιδιότητα} 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 (ιδιότητα της doctest.Example)
@anchor{library/doctest doctest Example options}@anchor{47f3}
@deffn {Ιδιότητα} 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{47d2,,DocTestRunner}’s @ref{12de,,optionflags}).
By default, no options are set.
@end deffn
@end deffn

@node DocTestFinder objects,DocTestParser objects,Example Objects,Advanced API
@anchor{library/doctest doctest-doctestfinder}@anchor{47f4}@anchor{library/doctest doctestfinder-objects}@anchor{47f5}
@subsubsection DocTestFinder objects


@geindex DocTestFinder (κλάση σε doctest)
@anchor{library/doctest doctest DocTestFinder}@anchor{1bb3}
@deffn {Κλάση} doctest.DocTestFinder (verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True)

A processing class used to extract the @ref{1c31,,DocTest}s that are relevant to
a given object, from its docstring and the docstrings of its contained objects.
@code{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{47c3,,DocTestParser} object (or a
drop-in replacement) that is used to extract doctests from docstrings.

If the optional argument `recurse' is false, then @ref{1c75,,DocTestFinder.find()}
will only examine the given object, and not any contained objects.

If the optional argument `exclude_empty' is false, then
@ref{1c75,,DocTestFinder.find()} will include tests for objects with empty docstrings.

@code{DocTestFinder} defines the following method:

@geindex find() (μέθοδος της doctest.DocTestFinder)
@anchor{library/doctest doctest DocTestFinder find}@anchor{1c75}
@deffn {Μέθοδος} find (obj[, name][, module][, globs][, extraglobs])

Return a list of the @ref{1c31,,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{1c31,,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 
To find the name of the file containing the object.

@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{1c31,,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 @code{DocTest}.
If `globs' is not specified, then it defaults to the module’s
@ref{2561,,__dict__}, if specified, or @code{@{@}} otherwise.
If `extraglobs' is not specified, then it defaults to @code{@{@}}.
@end deffn
@end deffn

@node DocTestParser objects,TestResults objects,DocTestFinder objects,Advanced API
@anchor{library/doctest doctest-doctestparser}@anchor{47f6}@anchor{library/doctest doctestparser-objects}@anchor{47f7}
@subsubsection DocTestParser objects


@geindex DocTestParser (κλάση σε doctest)
@anchor{library/doctest doctest DocTestParser}@anchor{47c3}
@deffn {Κλάση} doctest.DocTestParser

A processing class used to extract interactive examples from a string, and use
them to create a @ref{1c31,,DocTest} object.

@code{DocTestParser} defines the following methods:

@geindex get_doctest() (μέθοδος της doctest.DocTestParser)
@anchor{library/doctest doctest DocTestParser get_doctest}@anchor{47f8}
@deffn {Μέθοδος} get_doctest (string, globs, name, filename, lineno)

Extract all doctest examples from the given string, and collect them into a
@ref{1c31,,DocTest} object.

`globs', `name', `filename', and `lineno' are attributes for the new
@code{DocTest} object.  See the documentation for @ref{1c31,,DocTest} for more
information.
@end deffn

@geindex get_examples() (μέθοδος της doctest.DocTestParser)
@anchor{library/doctest doctest DocTestParser get_examples}@anchor{47f9}
@deffn {Μέθοδος} get_examples (string, name='<string>')

Extract all doctest examples from the given string, and return them as a list
of @ref{47e5,,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() (μέθοδος της doctest.DocTestParser)
@anchor{library/doctest doctest DocTestParser parse}@anchor{47fa}
@deffn {Μέθοδος} parse (string, name='<string>')

Divide the given string into examples and intervening text, and return them as
a list of alternating @ref{47e5,,Example}s and strings. Line numbers for the
@code{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 TestResults objects,DocTestRunner objects,DocTestParser objects,Advanced API
@anchor{library/doctest testresults-objects}@anchor{47fb}
@subsubsection TestResults objects


@geindex TestResults (κλάση σε doctest)
@anchor{library/doctest doctest TestResults}@anchor{47fc}
@deffn {Κλάση} doctest.TestResults (failed, attempted)

@geindex failed (ιδιότητα της doctest.TestResults)
@anchor{library/doctest doctest TestResults failed}@anchor{47fd}
@deffn {Ιδιότητα} failed

Number of failed tests.
@end deffn

@geindex attempted (ιδιότητα της doctest.TestResults)
@anchor{library/doctest doctest TestResults attempted}@anchor{47fe}
@deffn {Ιδιότητα} attempted

Number of attempted tests.
@end deffn

@geindex skipped (ιδιότητα της doctest.TestResults)
@anchor{library/doctest doctest TestResults skipped}@anchor{6f5}
@deffn {Ιδιότητα} skipped

Number of skipped tests.


Added in version 3.13.

@end deffn
@end deffn

@node DocTestRunner objects,OutputChecker objects,TestResults objects,Advanced API
@anchor{library/doctest doctest-doctestrunner}@anchor{47ff}@anchor{library/doctest doctestrunner-objects}@anchor{4800}
@subsubsection DocTestRunner objects


@geindex DocTestRunner (κλάση σε doctest)
@anchor{library/doctest doctest DocTestRunner}@anchor{47d2}
@deffn {Κλάση} doctest.DocTestRunner (checker=None, verbose=None, optionflags=0)

A processing class used to execute and verify the interactive examples in a
@ref{1c31,,DocTest}.

The comparison between expected outputs and actual outputs is done by an
@ref{47d1,,OutputChecker}.  This comparison may be customized with a number of
option flags; see section @ref{12de,,Option Flags} for more information.  If the
option flags are insufficient, then the comparison may also be customized by
passing a subclass of @code{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{6f3,,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{1a15,,report_skip()}, @ref{4801,,report_start()}, @ref{4802,,report_success()},
@ref{4803,,report_unexpected_exception()}, and @ref{4804,,report_failure()}.

The optional keyword argument `checker' specifies the @ref{47d1,,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 @code{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{12de,,Option Flags}.

The test runner accumulates statistics. The aggregated number of attempted,
failed and skipped examples is also available via the @ref{4805,,tries},
@ref{4806,,failures} and @ref{6f4,,skips} attributes. The @ref{6f3,,run()} and
@ref{47dc,,summarize()} methods return a @ref{47fc,,TestResults} instance.

@code{DocTestRunner} defines the following methods:

@geindex report_skip() (μέθοδος της doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner report_skip}@anchor{1a15}
@deffn {Μέθοδος} report_skip (out, test, example)

Report that the given example was skipped.  This method is provided to
allow subclasses of @code{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{6f3,,DocTestRunner.run()}.


Added in version 3.15.

@end deffn

@geindex report_start() (μέθοδος της doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner report_start}@anchor{4801}
@deffn {Μέθοδος} 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 @code{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{6f3,,DocTestRunner.run()}.
@end deffn

@geindex report_success() (μέθοδος της doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner report_success}@anchor{4802}
@deffn {Μέθοδος} report_success (out, test, example, got)

Report that the given example ran successfully.  This method is provided to
allow subclasses of @code{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{6f3,,DocTestRunner.run()}.
@end deffn

@geindex report_failure() (μέθοδος της doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner report_failure}@anchor{4804}
@deffn {Μέθοδος} report_failure (out, test, example, got)

Report that the given example failed.  This method is provided to allow
subclasses of @code{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{6f3,,DocTestRunner.run()}.
@end deffn

@geindex report_unexpected_exception() (μέθοδος της doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner report_unexpected_exception}@anchor{4803}
@deffn {Μέθοδος} 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 @code{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{a7a,,sys.exc_info()}). `test' is the test containing `example'.  `out' is the
output function that was passed to @ref{6f3,,DocTestRunner.run()}.
@end deffn

@geindex run() (μέθοδος της doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner run}@anchor{6f3}
@deffn {Μέθοδος} run (test, compileflags=None, out=None, clear_globs=True)

Run the examples in `test' (a @ref{1c31,,DocTest} object), and display the
results using the writer function `out'. Return a @ref{47fc,,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 @code{DocTestRunner}’s
output checker, and the results are formatted by the
@code{DocTestRunner.report_*()} methods.
@end deffn

@geindex summarize() (μέθοδος της doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner summarize}@anchor{47dc}
@deffn {Μέθοδος} summarize (verbose=None)

Print a summary of all the test cases that have been run by this DocTestRunner,
and return a @ref{47fc,,TestResults} instance.

The optional `verbose' argument controls how detailed the summary is.  If the
verbosity is not specified, then the @code{DocTestRunner}’s verbosity is
used.
@end deffn

@ref{47c3,,DocTestParser} has the following attributes:

@geindex tries (ιδιότητα της doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner tries}@anchor{4805}
@deffn {Ιδιότητα} tries

Number of attempted examples.
@end deffn

@geindex failures (ιδιότητα της doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner failures}@anchor{4806}
@deffn {Ιδιότητα} failures

Number of failed examples.
@end deffn

@geindex skips (ιδιότητα της doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner skips}@anchor{6f4}
@deffn {Ιδιότητα} skips

Number of skipped examples.


Added in version 3.13.

@end deffn
@end deffn

@node OutputChecker objects,,DocTestRunner objects,Advanced API
@anchor{library/doctest doctest-outputchecker}@anchor{4807}@anchor{library/doctest outputchecker-objects}@anchor{4808}
@subsubsection OutputChecker objects


@geindex OutputChecker (κλάση σε doctest)
@anchor{library/doctest doctest OutputChecker}@anchor{47d1}
@deffn {Κλάση} doctest.OutputChecker

A class used to check the whether the actual output from a doctest example
matches the expected output.  @code{OutputChecker} defines two methods:
@ref{4809,,check_output()}, which compares a given pair of outputs, and returns @code{True}
if they match; and @ref{480a,,output_difference()}, which returns a string describing
the differences between two outputs.

@code{OutputChecker} defines the following methods:

@geindex check_output() (μέθοδος της doctest.OutputChecker)
@anchor{library/doctest doctest OutputChecker check_output}@anchor{4809}
@deffn {Μέθοδος} 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{12de,,Option Flags} for more information about option flags.
@end deffn

@geindex output_difference() (μέθοδος της doctest.OutputChecker)
@anchor{library/doctest doctest OutputChecker output_difference}@anchor{480a}
@deffn {Μέθοδος} 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 Debugging,Soapbox,Advanced API,doctest — Test interactive Python examples
@anchor{library/doctest debugging}@anchor{480b}@anchor{library/doctest doctest-debugging}@anchor{480c}
@subsubsection Debugging


Doctest provides several mechanisms for debugging doctest examples:


@itemize *

@item 
Several functions convert doctests to executable Python programs, which can be
run under the Python debugger, @ref{aa,,pdb}.

@item 
The @ref{480d,,DebugRunner} class is a subclass of @ref{47d2,,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{10f,,unittest} cases generated by @ref{11ac,,DocTestSuite()} support the
@ref{480e,,debug()} method defined by @ref{52f,,unittest.TestCase}.

@item 
You can add a call to @ref{4fa,,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

Then an interactive Python session may look like this:

@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() (στη μονάδα doctest)
@anchor{library/doctest doctest script_from_examples}@anchor{480f}
@deffn {Συνάρτηση} doctest.script_from_examples (s)

Convert text with examples to a 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

displays:

@example
# Set x and y to 1 and 2.
x, y = 1, 2
#
# Print their sum:
print(x+y)
# Expected:
## 3
@end example

This function is used internally by other functions (see below), but can also be
useful when you want to transform an interactive Python session into a Python
script.
@end deffn

@geindex testsource() (στη μονάδα doctest)
@anchor{library/doctest doctest testsource}@anchor{4810}
@deffn {Συνάρτηση} doctest.testsource (module, name)

Convert the doctest for an object to a script.

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{480f,,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() (στη μονάδα doctest)
@anchor{library/doctest doctest debug}@anchor{480e}
@deffn {Συνάρτηση} doctest.debug (module, name, pm=False)

Debug the doctests for an object.

The `module' and `name' arguments are the same as for function
@ref{4810,,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{aa,,pdb}.

A shallow copy of @code{module.__dict__} is used for both local and global
execution context.

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{177d,,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{185,,exec()} call to @ref{4811,,pdb.run()}.
@end deffn

@geindex debug_src() (στη μονάδα doctest)
@anchor{library/doctest doctest debug_src}@anchor{4812}
@deffn {Συνάρτηση} doctest.debug_src (src, pm=False, globs=None)

Debug the doctests in a string.

This is like function @ref{480e,,debug()} above, except that a string containing
doctest examples is specified directly, via the `src' argument.

Optional argument `pm' has the same meaning as in function @ref{480e,,debug()} above.

Optional argument `globs' gives a dictionary to use as both local and global
execution context.  If not specified, or @code{None}, an empty dictionary is used.
If specified, a shallow copy of the dictionary is used.
@end deffn

The @ref{480d,,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 @code{DebugRunner}’s docstring (which is a
doctest!) for more details:

@geindex DebugRunner (κλάση σε doctest)
@anchor{library/doctest doctest DebugRunner}@anchor{480d}
@deffn {Κλάση} doctest.DebugRunner (checker=None, verbose=None, optionflags=0)

A subclass of @ref{47d2,,DocTestRunner} that raises an exception as soon as a
failure is encountered.  If an unexpected exception occurs, an
@ref{4813,,UnexpectedException} exception is raised, containing the test, the
example, and the original exception.  If the output doesn’t match, then a
@ref{4814,,DocTestFailure} exception is raised, containing the test, the example, and
the actual output.

For information about the constructor parameters and methods, see the
documentation for @ref{47d2,,DocTestRunner} in section @ref{47e4,,Advanced API}.
@end deffn

There are two exceptions that may be raised by @ref{480d,,DebugRunner} instances:

@geindex DocTestFailure
@anchor{library/doctest doctest DocTestFailure}@anchor{4814}
@deffn {Εξαίρεση} doctest.DocTestFailure (test, example, got)

An exception raised by @ref{47d2,,DocTestRunner} to signal that a doctest example’s
actual output did not match its expected output. The constructor arguments are
used to initialize the attributes of the same names.
@end deffn

@ref{4814,,DocTestFailure} defines the following attributes:

@geindex test (ιδιότητα της doctest.DocTestFailure)
@anchor{library/doctest doctest DocTestFailure test}@anchor{4815}
@deffn {Ιδιότητα} DocTestFailure.test

The @ref{1c31,,DocTest} object that was being run when the example failed.
@end deffn

@geindex example (ιδιότητα της doctest.DocTestFailure)
@anchor{library/doctest doctest DocTestFailure example}@anchor{4816}
@deffn {Ιδιότητα} DocTestFailure.example

The @ref{47e5,,Example} that failed.
@end deffn

@geindex got (ιδιότητα της doctest.DocTestFailure)
@anchor{library/doctest doctest DocTestFailure got}@anchor{4817}
@deffn {Ιδιότητα} DocTestFailure.got

The example’s actual output.
@end deffn

@geindex UnexpectedException
@anchor{library/doctest doctest UnexpectedException}@anchor{4813}
@deffn {Εξαίρεση} doctest.UnexpectedException (test, example, exc_info)

An exception raised by @ref{47d2,,DocTestRunner} to signal that a doctest
example raised an unexpected exception.  The constructor arguments are used
to initialize the attributes of the same names.
@end deffn

@ref{4813,,UnexpectedException} defines the following attributes:

@geindex test (ιδιότητα της doctest.UnexpectedException)
@anchor{library/doctest doctest UnexpectedException test}@anchor{4818}
@deffn {Ιδιότητα} UnexpectedException.test

The @ref{1c31,,DocTest} object that was being run when the example failed.
@end deffn

@geindex example (ιδιότητα της doctest.UnexpectedException)
@anchor{library/doctest doctest UnexpectedException example}@anchor{4819}
@deffn {Ιδιότητα} UnexpectedException.example

The @ref{47e5,,Example} that failed.
@end deffn

@geindex exc_info (ιδιότητα της doctest.UnexpectedException)
@anchor{library/doctest doctest UnexpectedException exc_info}@anchor{481a}
@deffn {Ιδιότητα} UnexpectedException.exc_info

A tuple containing information about the unexpected exception, as returned by
@ref{a7a,,sys.exc_info()}.
@end deffn

@node Soapbox,,Debugging,doctest — Test interactive Python examples
@anchor{library/doctest doctest-soapbox}@anchor{481b}@anchor{library/doctest soapbox}@anchor{481c}
@subsubsection Soapbox


As mentioned in the introduction, @code{doctest} has grown to have three primary
uses:


@enumerate 

@item 
Checking examples in docstrings.

@item 
Regression testing.

@item 
Executable documentation / literate testing.
@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 @code{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{47b2,,testfile()} or @ref{1a14,,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 @ref{47be,,__test__} dictionary mapping from regression test topics to
docstrings containing test cases.
@end itemize

When you have placed your tests in a module, the module can itself be the test
runner.  When a test fails, you can arrange for your test runner to re-run only
the failing doctest while you debug the problem.  Here is a minimal example of
such a test runner:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node unittest — Unit testing framework,unittest mock — mock object library,doctest — Test interactive Python examples,Εργαλεία Ανάπτυξης
@anchor{library/unittest doc}@anchor{481d}@anchor{library/unittest module-unittest}@anchor{10f}@anchor{library/unittest translation-repo}@anchor{481e}@anchor{library/unittest unittest-unit-testing-framework}@anchor{481f}
@subsection @code{unittest} — Unit testing framework


@geindex module; unittest

`Source code:' Lib/unittest/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/unittest/__init__.py}


__________________________________________________________________


(If you are already familiar with the basic concepts of testing, you might want
to skip to @ref{4820,,the list of assert methods}.)

The @code{unittest} unit testing framework was originally inspired by JUnit
and has a similar flavor as major unit testing frameworks in other
languages.  It supports test automation, sharing of setup and shutdown code
for tests, aggregation of tests into collections, and independence of the
tests from the reporting framework.

To achieve this, @code{unittest} supports some important concepts in an
object-oriented way:


@table @asis

@item test fixture

A `test fixture' represents the preparation needed to perform one or more
tests, and any associated cleanup actions.  This may involve, for example,
creating temporary or proxy databases, directories, or starting a server
process.

@item test case

A `test case' is the individual unit of testing.  It checks for a specific
response to a particular set of inputs.  @code{unittest} provides a base class,
@ref{52f,,TestCase}, which may be used to create new test cases.

@item test suite

A `test suite' is a collection of test cases, test suites, or both.  It is
used to aggregate tests that should be executed together.

@item test runner

A `test runner' is a component which orchestrates the execution of tests
and provides the outcome to the user.  The runner may use a graphical interface,
a textual interface, or return a special value to indicate the results of
executing the tests.
@end table


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{3d,,doctest}

Another test-support module with a very different flavor.

@item Simple Smalltalk Testing: With Patterns@footnote{https://web.archive.org/web/20150315073817/http://www.xprogramming.com/testfram.htm}

Kent Beck’s original paper on testing frameworks using the pattern shared
by @code{unittest}.

@item pytest@footnote{https://docs.pytest.org/}

Third-party unittest framework with a lighter-weight syntax for writing
tests.  For example, @code{assert func(10) == 42}.

@item The Python Testing Tools Taxonomy@footnote{https://wiki.python.org/moin/PythonTestingToolsTaxonomy}

An extensive list of Python testing tools including functional testing
frameworks and mock object libraries.

@item Testing in Python Mailing List@footnote{http://lists.idyll.org/listinfo/testing-in-python}

A special-interest-group for discussion of testing, and testing tools,
in 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
* Basic example:: 
* Command-Line Interface: Command-Line Interface<2>. 
* Test Discovery:: 
* Organizing test code:: 
* Re-using old test code:: 
* Skipping tests and expected failures:: 
* Distinguishing test iterations using subtests:: 
* Classes and functions:: 
* Class and Module Fixtures:: 
* Signal Handling:: 

@end menu

@node Basic example,Command-Line Interface<2>,,unittest — Unit testing framework
@anchor{library/unittest basic-example}@anchor{4821}@anchor{library/unittest unittest-minimal-example}@anchor{4822}
@subsubsection Basic example


The @code{unittest} module provides a rich set of tools for constructing and
running tests.  This section demonstrates that a small subset of the tools
suffice to meet the needs of most users.

Here is a short script to test three string methods:

@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

A test case is created by subclassing @ref{52f,,unittest.TestCase}.  The three
individual tests are defined with methods whose names start with the letters
@code{test}.  This naming convention informs the test runner about which methods
represent tests.

The crux of each test is a call to @ref{937,,assertEqual()} to check for an
expected result; @ref{935,,assertTrue()} or @ref{936,,assertFalse()}
to verify a condition; or @ref{93b,,assertRaises()} to verify that a
specific exception gets raised.  These methods are used instead of the
@ref{d31,,assert} statement so the test runner can accumulate all test results
and produce a report.

The @ref{16de,,setUp()} and @ref{16df,,tearDown()} methods allow you
to define instructions that will be executed before and after each test method.
They are covered in more detail in the section @ref{4823,,Organizing test code}.

The final block shows a simple way to run the tests. @ref{138c,,unittest.main()}
provides a command-line interface to the test script.  When run from the command
line, the above script produces an output that looks like this:

@example
...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK
@end example

Passing the @code{-v} option to your test script will instruct @ref{138c,,unittest.main()}
to enable a higher level of verbosity, and produce the following output:

@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

The above examples show the most commonly used @code{unittest} features which
are sufficient to meet many everyday testing needs.  The remainder of the
documentation explores the full feature set from first principles.


Άλλαξε στην έκδοση 3.11: The behavior of returning a value from a test method (other than the default
@code{None} value), is now deprecated.


@node Command-Line Interface<2>,Test Discovery,Basic example,unittest — Unit testing framework
@anchor{library/unittest command-line-interface}@anchor{4824}@anchor{library/unittest unittest-command-line-interface}@anchor{4825}
@subsubsection Command-Line Interface


The unittest module can be used from the command line to run tests from
modules, classes or even individual test methods:

@example
python -m unittest test_module1 test_module2
python -m unittest test_module.TestClass
python -m unittest test_module.TestClass.test_method
@end example

You can pass in a list with any combination of module names, and fully
qualified class or method names.

Test modules can be specified by file path as well:

@example
python -m unittest tests/test_something.py
@end example

This allows you to use the shell filename completion to specify the test module.
The file specified must still be importable as a module. The path is converted
to a module name by removing the “.py” and converting path separators into “.”.
If you want to execute a test file that isn’t importable as a module you should
execute the file directly instead.

You can run tests with more detail (higher verbosity) by passing in the -v flag:

@example
python -m unittest -v test_module
@end example

When executed without arguments @ref{4826,,Test Discovery} is started:

@example
python -m unittest
@end example

For a list of all the command-line options:

@example
python -m unittest -h
@end example


Άλλαξε στην έκδοση 3.2: In earlier versions it was only possible to run individual test methods and
not modules or classes.



Added in version 3.14: Output is colorized by default and can be
@ref{1af,,controlled using environment variables}.


@menu
* Command-line options: Command-line options<4>. 

@end menu

@node Command-line options<4>,,,Command-Line Interface<2>
@anchor{library/unittest command-line-options}@anchor{4827}
@subsubsection Command-line options


@code{unittest} supports these command-line options:

@geindex unittest command line option; -b
@geindex unittest command line option; --buffer
@anchor{library/unittest cmdoption-unittest-b}@anchor{16d6}@anchor{library/unittest cmdoption-unittest-buffer}@anchor{4828}
@deffn {Option} @w{-}b, @w{-}@w{-}buffer

The standard output and standard error streams are buffered during the test
run. Output during a passing test is discarded. Output is echoed normally
on test fail or error and is added to the failure messages.
@end deffn

@geindex unittest command line option; -c
@geindex unittest command line option; --catch
@anchor{library/unittest cmdoption-unittest-c}@anchor{16d7}@anchor{library/unittest cmdoption-unittest-catch}@anchor{4829}
@deffn {Option} @w{-}c, @w{-}@w{-}catch

@code{Control}-@code{C} during the test run waits for the current test to end and then
reports all the results so far. A second @code{Control}-@code{C} raises the normal
@ref{d96,,KeyboardInterrupt} exception.

See @ref{482a,,Signal Handling} for the functions that provide this functionality.
@end deffn

@geindex unittest command line option; -f
@geindex unittest command line option; --failfast
@anchor{library/unittest cmdoption-unittest-f}@anchor{16d9}@anchor{library/unittest cmdoption-unittest-failfast}@anchor{482b}
@deffn {Option} @w{-}f, @w{-}@w{-}failfast

Stop the test run on the first error or failure.
@end deffn

@geindex unittest command line option; -k
@anchor{library/unittest cmdoption-unittest-k}@anchor{482c}
@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.

Patterns that contain a wildcard character (@code{*}) are matched against the
test name using @ref{1e4c,,fnmatch.fnmatchcase()}; otherwise simple case-sensitive
substring matching is used.

Patterns are matched against the fully qualified test method name as
imported by the test loader.

For example, @code{-k foo} matches @code{foo_tests.SomeTest.test_something},
@code{bar_tests.SomeTest.test_foo}, but not @code{bar_tests.FooTest.test_something}.
@end deffn

@geindex unittest command line option; --locals
@anchor{library/unittest cmdoption-unittest-locals}@anchor{482d}
@deffn {Option} @w{-}@w{-}locals

Show local variables in tracebacks.
@end deffn

@geindex unittest command line option; --durations
@anchor{library/unittest cmdoption-unittest-durations}@anchor{482e}
@deffn {Option} @w{-}@w{-}durations N

Show the N slowest test cases (N=0 for all).
@end deffn


Added in version 3.2: The command-line options @code{-b}, @code{-c} and @code{-f} were added.



Added in version 3.5: The command-line option @code{--locals}.



Added in version 3.7: The command-line option @code{-k}.



Added in version 3.12: The command-line option @code{--durations}.


The command line can also be used for test discovery, for running all of the
tests in a project or just a subset.

@node Test Discovery,Organizing test code,Command-Line Interface<2>,unittest — Unit testing framework
@anchor{library/unittest test-discovery}@anchor{482f}@anchor{library/unittest unittest-test-discovery}@anchor{4826}
@subsubsection Test Discovery



Added in version 3.2.


Unittest supports simple test discovery. In order to be compatible with test
discovery, all of the test files must be @ref{222d,,modules} or
@ref{223d,,packages} importable from the top-level directory of
the project (this means that their filenames must be valid @ref{2491,,identifiers}).

Test discovery is implemented in @ref{138e,,TestLoader.discover()}, but can also be
used from the command line. The basic command-line usage is:

@example
cd project_directory
python -m unittest discover
@end example

@cartouche
@quotation Σημείωση 
As a shortcut, @code{python -m unittest} is the equivalent of
@code{python -m unittest discover}. If you want to pass arguments to test
discovery the @code{discover} sub-command must be used explicitly.
@end quotation
@end cartouche

The @code{discover} sub-command has the following options:

@geindex unittest-discover command line option; -v
@geindex unittest-discover command line option; --verbose
@anchor{library/unittest cmdoption-unittest-discover-v}@anchor{4830}@anchor{library/unittest cmdoption-unittest-discover-verbose}@anchor{4831}
@deffn {Option} @w{-}v, @w{-}@w{-}verbose

Verbose output
@end deffn

@geindex unittest-discover command line option; -s
@geindex unittest-discover command line option; --start-directory
@anchor{library/unittest cmdoption-unittest-discover-s}@anchor{4832}@anchor{library/unittest cmdoption-unittest-discover-start-directory}@anchor{4833}
@deffn {Option} @w{-}s, @w{-}@w{-}start@w{-}directory directory

Directory to start discovery (@code{.} default)
@end deffn

@geindex unittest-discover command line option; -p
@geindex unittest-discover command line option; --pattern
@anchor{library/unittest cmdoption-unittest-discover-p}@anchor{4834}@anchor{library/unittest cmdoption-unittest-discover-pattern}@anchor{4835}
@deffn {Option} @w{-}p, @w{-}@w{-}pattern pattern

Pattern to match test files (@code{test*.py} default)
@end deffn

@geindex unittest-discover command line option; -t
@geindex unittest-discover command line option; --top-level-directory
@anchor{library/unittest cmdoption-unittest-discover-t}@anchor{4836}@anchor{library/unittest cmdoption-unittest-discover-top-level-directory}@anchor{4837}
@deffn {Option} @w{-}t, @w{-}@w{-}top@w{-}level@w{-}directory directory

Top level directory of project (defaults to start directory)
@end deffn

The @ref{4832,,-s}, @ref{4834,,-p}, and @ref{4836,,-t} options can be passed in
as positional arguments in that order. The following two command lines
are equivalent:

@example
python -m unittest discover -s project_directory -p "*_test.py"
python -m unittest discover project_directory "*_test.py"
@end example

As well as being a path it is possible to pass a package name, for example
@code{myproject.subpackage.test}, as the start directory. The package name you
supply will then be imported and its location on the filesystem will be used
as the start directory.

@cartouche
@quotation Προσοχή 
Test discovery loads tests by importing them. Once test discovery has found
all the test files from the start directory you specify it turns the paths
into package names to import. For example @code{foo/bar/baz.py} will be
imported as @code{foo.bar.baz}.

If you have a package installed globally and attempt test discovery on
a different copy of the package then the import `could' happen from the
wrong place. If this happens test discovery will warn you and exit.

If you supply the start directory as a package name rather than a
path to a directory then discover assumes that whichever location it
imports from is the location you intended, so you will not get the
warning.
@end quotation
@end cartouche

Test modules and packages can customize test loading and discovery by through
the @ref{4838,,load_tests protocol}.


Άλλαξε στην έκδοση 3.4: Test discovery supports @ref{52e,,namespace packages}.



Άλλαξε στην έκδοση 3.11: Test discovery dropped the @ref{52e,,namespace packages}
support. It has been broken since Python 3.7.
Start directory and its subdirectories containing tests must be regular
package that have @code{__init__.py} file.

If the start directory is the dotted name of the package, the ancestor packages
can be namespace packages.



Άλλαξε στην έκδοση 3.14: Test discovery supports @ref{52e,,namespace package} as start directory again.
To avoid scanning directories unrelated to Python,
tests are not searched in subdirectories that do not contain @code{__init__.py}.


@node Organizing test code,Re-using old test code,Test Discovery,unittest — Unit testing framework
@anchor{library/unittest organizing-test-code}@anchor{4839}@anchor{library/unittest organizing-tests}@anchor{4823}
@subsubsection Organizing test code


The basic building blocks of unit testing are `test cases' — single
scenarios that must be set up and checked for correctness.  In @code{unittest},
test cases are represented by @ref{52f,,unittest.TestCase} instances.
To make your own test cases you must write subclasses of
@ref{52f,,TestCase} or use @ref{1c7f,,FunctionTestCase}.

The testing code of a @ref{52f,,TestCase} instance should be entirely self
contained, such that it can be run either in isolation or in arbitrary
combination with any number of other test cases.

The simplest @ref{52f,,TestCase} subclass will simply implement a test method
(i.e. a method whose name starts with @code{test}) in order to perform specific
testing code:

@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{4820,,assert* methods}
provided by the @ref{52f,,TestCase} base class.  If the test fails, an
exception will be raised with an explanatory message, and @code{unittest}
will identify the test case as a `failure'.  Any other exceptions will be
treated as `errors'.

Tests can be numerous, and their set-up can be repetitive.  Luckily, we
can factor out set-up code by implementing a method called
@ref{16de,,setUp()}, which the testing framework will automatically
call for every single test we run:

@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 Σημείωση 
The order in which the various tests will be run is determined
by sorting the test method names with respect to the built-in
ordering for strings.
@end quotation
@end cartouche

If the @ref{16de,,setUp()} method raises an exception while the test is
running, the framework will consider the test to have suffered an error, and
the test method will not be executed.

Similarly, we can provide a @ref{16df,,tearDown()} method that tidies up
after the test method has been run:

@example
import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def tearDown(self):
        self.widget.dispose()
@end example

If @ref{16de,,setUp()} succeeded, @ref{16df,,tearDown()} will be
run whether the test method succeeded or not.

Such a working environment for the testing code is called a
`test fixture'.  A new TestCase instance is created as a unique
test fixture used to execute each individual test method.  Thus
@ref{16de,,setUp()}, @ref{16df,,tearDown()}, and @code{TestCase.__init__()}
will be called once per test.

It is recommended that you use TestCase implementations to group tests together
according to the features they test.  @code{unittest} provides a mechanism for
this: the `test suite', represented by @code{unittest}’s
@ref{11ad,,TestSuite} class.  In most cases, calling @ref{138c,,unittest.main()} will do
the right thing and collect all the module’s test cases for you and execute
them.

However, should you want to customize the building of your test suite,
you can do it yourself:

@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

You can place the definitions of test cases and test suites in the same modules
as the code they are to test (such as @code{widget.py}), but there are several
advantages to placing the test code in a separate module, such as
@code{test_widget.py}:


@itemize *

@item 
The test module can be run standalone from the command line.

@item 
The test code can more easily be separated from shipped code.

@item 
There is less temptation to change test code to fit the code it tests without
a good reason.

@item 
Test code should be modified much less frequently than the code it tests.

@item 
Tested code can be refactored more easily.

@item 
Tests for modules written in C must be in separate modules anyway, so why not
be consistent?

@item 
If the testing strategy changes, there is no need to change the source code.
@end itemize

@node Re-using old test code,Skipping tests and expected failures,Organizing test code,unittest — Unit testing framework
@anchor{library/unittest legacy-unit-tests}@anchor{483a}@anchor{library/unittest re-using-old-test-code}@anchor{483b}
@subsubsection Re-using old test code


Some users will find that they have existing test code that they would like to
run from @code{unittest}, without converting every old test function to a
@ref{52f,,TestCase} subclass.

For this reason, @code{unittest} provides a @ref{1c7f,,FunctionTestCase} class.
This subclass of @ref{52f,,TestCase} can be used to wrap an existing test
function.  Set-up and tear-down functions can also be provided.

Given the following test function:

@example
def testSomething():
    something = makeSomething()
    assert something.name is not None
    # ...
@end example

one can create an equivalent test case instance as follows, with optional
set-up and tear-down methods:

@example
testcase = unittest.FunctionTestCase(testSomething,
                                     setUp=makeSomethingDB,
                                     tearDown=deleteSomethingDB)
@end example

@cartouche
@quotation Σημείωση 
Even though @ref{1c7f,,FunctionTestCase} can be used to quickly convert an
existing test base over to a @code{unittest}-based system, this approach is
not recommended.  Taking the time to set up proper @ref{52f,,TestCase}
subclasses will make future test refactorings infinitely easier.
@end quotation
@end cartouche

In some cases, the existing tests may have been written using the @ref{3d,,doctest}
module.  If so, @code{doctest} provides a @ref{11ac,,DocTestSuite} class that can
automatically build @ref{11ad,,unittest.TestSuite} instances from the existing
@code{doctest}-based tests.

@node Skipping tests and expected failures,Distinguishing test iterations using subtests,Re-using old test code,unittest — Unit testing framework
@anchor{library/unittest skipping-tests-and-expected-failures}@anchor{483c}@anchor{library/unittest unittest-skipping}@anchor{483d}
@subsubsection Skipping tests and expected failures



Added in version 3.1.


Unittest supports skipping individual test methods and even whole classes of
tests.  In addition, it supports marking a test as an «expected failure,» a test
that is broken and will fail, but shouldn’t be counted as a failure on a
@ref{1510,,TestResult}.

Skipping a test is simply a matter of using the @ref{1fae,,skip()} @ref{b18,,decorator}
or one of its conditional variants, calling @ref{483e,,TestCase.skipTest()} within a
@ref{16de,,setUp()} or test method, or raising @ref{138d,,SkipTest} directly.

Basic skipping looks like this:

@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

This is the output of running the example above in verbose mode:

@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

Classes can be skipped just like methods:

@example
@@unittest.skip("showing class skipping")
class MySkippedTestCase(unittest.TestCase):
    def test_not_run(self):
        pass
@end example

@ref{16de,,TestCase.setUp()} can also skip the test.  This is useful when a resource
that needs to be set up is not available.

Expected failures use the @ref{483f,,expectedFailure()} decorator.

@example
class ExpectedFailureTestCase(unittest.TestCase):
    @@unittest.expectedFailure
    def test_fail(self):
        self.assertEqual(1, 0, "broken")
@end example

It’s easy to roll your own skipping decorators by making a decorator that calls
@ref{1fae,,skip()} on the test when it wants it to be skipped.  This decorator skips
the test unless the passed object has a certain attribute:

@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

The following decorators and exception implement test skipping and expected failures:

@geindex skip() (στη μονάδα unittest)
@anchor{library/unittest unittest skip}@anchor{1fae}
@deffn {Συνάρτηση} @@unittest.skip (reason)

Unconditionally skip the decorated test.  `reason' should describe why the
test is being skipped.
@end deffn

@geindex skipIf() (στη μονάδα unittest)
@anchor{library/unittest unittest skipIf}@anchor{4840}
@deffn {Συνάρτηση} @@unittest.skipIf (condition, reason)

Skip the decorated test if `condition' is true.
@end deffn

@geindex skipUnless() (στη μονάδα unittest)
@anchor{library/unittest unittest skipUnless}@anchor{4841}
@deffn {Συνάρτηση} @@unittest.skipUnless (condition, reason)

Skip the decorated test unless `condition' is true.
@end deffn

@geindex expectedFailure() (στη μονάδα unittest)
@anchor{library/unittest unittest expectedFailure}@anchor{483f}
@deffn {Συνάρτηση} @@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{138d}
@deffn {Εξαίρεση} unittest.SkipTest (reason)

This exception is raised to skip a test.

Usually you can use @ref{483e,,TestCase.skipTest()} or one of the skipping
decorators instead of raising this directly.
@end deffn

Skipped tests will not have @ref{16de,,setUp()} or @ref{16df,,tearDown()} run around them.
Skipped classes will not have @ref{e12,,setUpClass()} or @ref{16dc,,tearDownClass()} run.
Skipped modules will not have @ref{e11,,setUpModule()} or @ref{16db,,tearDownModule()} run.

@node Distinguishing test iterations using subtests,Classes and functions,Skipping tests and expected failures,unittest — Unit testing framework
@anchor{library/unittest distinguishing-test-iterations-using-subtests}@anchor{4842}@anchor{library/unittest subtests}@anchor{138b}
@subsubsection Distinguishing test iterations using subtests



Added in version 3.4.


When there are very small differences among your tests, for
instance some parameters, unittest allows you to distinguish them inside
the body of a test method using the @ref{138a,,subTest()} context manager.

For example, the following test:

@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

will produce the following output:

@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

Without using a subtest, execution would stop after the first failure,
and the error would be less easy to diagnose because the value of @code{i}
wouldn’t be displayed:

@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 and functions,Class and Module Fixtures,Distinguishing test iterations using subtests,unittest — Unit testing framework
@anchor{library/unittest classes-and-functions}@anchor{4843}@anchor{library/unittest unittest-contents}@anchor{4844}
@subsubsection Classes and functions


This section describes in depth the API of @code{unittest}.

@menu
* Test cases:: 
* Grouping tests:: 
* Loading and running tests:: 

@end menu

@node Test cases,Grouping tests,,Classes and functions
@anchor{library/unittest test-cases}@anchor{4845}@anchor{library/unittest testcase-objects}@anchor{4846}
@subsubsection Test cases


@geindex TestCase (κλάση σε unittest)
@anchor{library/unittest unittest TestCase}@anchor{52f}
@deffn {Κλάση} unittest.TestCase (methodName='runTest')

Instances of the @code{TestCase} class represent the logical test units
in the @code{unittest} universe.  This class is intended to be used as a base
class, with specific tests being implemented by concrete subclasses.  This class
implements the interface needed by the test runner to allow it to drive the
tests, and methods that the test code can use to check for and report various
kinds of failure.

Each instance of @code{TestCase} will run a single base method: the method
named `methodName'.
In most uses of @code{TestCase}, you will neither change
the `methodName' nor reimplement the default @code{runTest()} method.


Άλλαξε στην έκδοση 3.2: @code{TestCase} can be instantiated successfully without providing a
`methodName'. This makes it easier to experiment with @code{TestCase}
from the interactive interpreter.


@code{TestCase} instances provide three groups of methods: one group used
to run the test, another used by the test implementation to check conditions
and report failures, and some inquiry methods allowing information about the
test itself to be gathered.

Methods in the first group (running the test) are:

@geindex setUp() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase setUp}@anchor{16de}
@deffn {Μέθοδος} setUp ()

Method called to prepare the test fixture.  This is called immediately
before calling the test method; other than @ref{a97,,AssertionError} or @ref{138d,,SkipTest},
any exception raised by this method will be considered an error rather than
a test failure. The default implementation does nothing.
@end deffn

@geindex tearDown() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase tearDown}@anchor{16df}
@deffn {Μέθοδος} tearDown ()

Method called immediately after the test method has been called and the
result recorded.  This is called even if the test method raised an
exception, so the implementation in subclasses may need to be particularly
careful about checking internal state.  Any exception, other than
@ref{a97,,AssertionError} or @ref{138d,,SkipTest}, raised by this method will be
considered an additional error rather than a test failure (thus increasing
the total number of reported errors). This method will only be called if
the @ref{16de,,setUp()} succeeds, regardless of the outcome of the test method.
The default implementation does nothing.
@end deffn

@geindex setUpClass() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase setUpClass}@anchor{e12}
@deffn {Μέθοδος} setUpClass ()

A class method called before tests in an individual class are run.
@code{setUpClass} is called with the class as the only argument
and must be decorated as a @ref{69a,,classmethod()}:

@example
@@classmethod
def setUpClass(cls):
    ...
@end example

See @ref{4847,,Class and Module Fixtures} for more details.


Added in version 3.2.

@end deffn

@geindex tearDownClass() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase tearDownClass}@anchor{16dc}
@deffn {Μέθοδος} tearDownClass ()

A class method called after tests in an individual class have run.
@code{tearDownClass} is called with the class as the only argument
and must be decorated as a @ref{69a,,classmethod()}:

@example
@@classmethod
def tearDownClass(cls):
    ...
@end example

See @ref{4847,,Class and Module Fixtures} for more details.


Added in version 3.2.

@end deffn

@geindex run() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase run}@anchor{150f}
@deffn {Μέθοδος} run (result=None)

Run the test, collecting the result into the @ref{1510,,TestResult} object
passed as `result'.  If `result' is omitted or @code{None}, a temporary
result object is created (by calling the @ref{4848,,defaultTestResult()}
method) and used. The result object is returned to @code{run()}”s
caller.

The same effect may be had by simply calling the @code{TestCase}
instance.


Άλλαξε στην έκδοση 3.3: Previous versions of @code{run} did not return the result. Neither did
calling an instance.

@end deffn

@geindex skipTest() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase skipTest}@anchor{483e}
@deffn {Μέθοδος} skipTest (reason)

Calling this during a test method or @ref{16de,,setUp()} skips the current
test.  See @ref{483d,,Skipping tests and expected failures} for more information.


Added in version 3.1.

@end deffn

@geindex subTest() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase subTest}@anchor{138a}
@deffn {Μέθοδος} subTest (msg=None, **params)

Return a context manager which executes the enclosed code block as a
subtest.  `msg' and `params' are optional, arbitrary values which are
displayed whenever a subtest fails, allowing you to identify them
clearly.

A test case can contain any number of subtest declarations, and
they can be arbitrarily nested.

See @ref{138b,,Distinguishing test iterations using subtests} for more information.


Added in version 3.4.

@end deffn

@geindex debug() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase debug}@anchor{1e40}
@deffn {Μέθοδος} debug ()

Run the test without collecting the result.  This allows exceptions raised
by the test to be propagated to the caller, and can be used to support
running tests under a debugger.
@end deffn
@anchor{library/unittest assert-methods}@anchor{4820}
The @code{TestCase} class provides several assert methods to check for and
report failures.  The following table lists the most commonly used methods
(see the tables below for more assert methods):


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Method

@tab

Checks that

@tab

New in

@item

@ref{937,,assertEqual(a@comma{} b)}

@tab

@code{a == b}

@tab

@item

@ref{938,,assertNotEqual(a@comma{} b)}

@tab

@code{a != b}

@tab

@item

@ref{935,,assertTrue(x)}

@tab

@code{bool(x) is True}

@tab

@item

@ref{936,,assertFalse(x)}

@tab

@code{bool(x) is False}

@tab

@item

@ref{16e0,,assertIs(a@comma{} b)}

@tab

@code{a is b}

@tab

3.1

@item

@ref{16e1,,assertIsNot(a@comma{} b)}

@tab

@code{a is not b}

@tab

3.1

@item

@ref{162f,,assertIsNone(x)}

@tab

@code{x is None}

@tab

3.1

@item

@ref{1630,,assertIsNotNone(x)}

@tab

@code{x is not None}

@tab

3.1

@item

@ref{16e9,,assertIn(a@comma{} b)}

@tab

@code{a in b}

@tab

3.1

@item

@ref{16ea,,assertNotIn(a@comma{} b)}

@tab

@code{a not in b}

@tab

3.1

@item

@ref{16e2,,assertIsInstance(a@comma{} b)}

@tab

@code{isinstance(a, b)}

@tab

3.2

@item

@ref{16e3,,assertNotIsInstance(a@comma{} b)}

@tab

@code{not isinstance(a, b)}

@tab

3.2

@item

@ref{532,,assertIsSubclass(a@comma{} b)}

@tab

@code{issubclass(a, b)}

@tab

3.14

@item

@ref{533,,assertNotIsSubclass(a@comma{} b)}

@tab

@code{not issubclass(a, b)}

@tab

3.14

@end multitable


All the assert methods accept a `msg' argument that, if specified, is used
as the error message on failure (see also @ref{16da,,longMessage}).
Note that the `msg' keyword argument can be passed to @ref{93b,,assertRaises()},
@ref{93d,,assertRaisesRegex()}, @ref{2a0,,assertWarns()}, @ref{2a1,,assertWarnsRegex()}
only when they are used as a context manager.

@geindex assertEqual() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertEqual}@anchor{937}
@deffn {Μέθοδος} assertEqual (first, second, msg=None)

Test that `first' and `second' are equal.  If the values do not
compare equal, the test will fail.

In addition, if `first' and `second' are the exact same type and one of
list, tuple, dict, set, frozenset or str or any type that a subclass
registers with @ref{16ed,,addTypeEqualityFunc()} the type-specific equality
function will be called in order to generate a more useful default
error message (see also the @ref{4849,,list of type-specific methods}).


Άλλαξε στην έκδοση 3.1: Added the automatic calling of type-specific equality function.



Άλλαξε στην έκδοση 3.2: @ref{16e8,,assertMultiLineEqual()} added as the default type equality
function for comparing strings.

@end deffn

@geindex assertNotEqual() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertNotEqual}@anchor{938}
@deffn {Μέθοδος} assertNotEqual (first, second, msg=None)

Test that `first' and `second' are not equal.  If the values do
compare equal, the test will fail.
@end deffn

@geindex assertTrue() (μέθοδος της unittest.TestCase)
@geindex assertFalse() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertTrue}@anchor{935}
@deffn {Μέθοδος} assertTrue (expr, msg=None)
@anchor{library/unittest unittest TestCase assertFalse}@anchor{936}
@deffnx {Μέθοδος} assertFalse (expr, msg=None)

Test that `expr' is true (or false).

Note that this is equivalent to @code{bool(expr) is True} and not to @code{expr
is True} (use @code{assertIs(expr, True)} for the latter).  This method
should also be avoided when more specific methods are available (e.g.
@code{assertEqual(a, b)} instead of @code{assertTrue(a == b)}), because they
provide a better error message in case of failure.
@end deffn

@geindex assertIs() (μέθοδος της unittest.TestCase)
@geindex assertIsNot() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertIs}@anchor{16e0}
@deffn {Μέθοδος} assertIs (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertIsNot}@anchor{16e1}
@deffnx {Μέθοδος} assertIsNot (first, second, msg=None)

Test that `first' and `second' are (or are not) the same object.


Added in version 3.1.

@end deffn

@geindex assertIsNone() (μέθοδος της unittest.TestCase)
@geindex assertIsNotNone() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertIsNone}@anchor{162f}
@deffn {Μέθοδος} assertIsNone (expr, msg=None)
@anchor{library/unittest unittest TestCase assertIsNotNone}@anchor{1630}
@deffnx {Μέθοδος} assertIsNotNone (expr, msg=None)

Test that `expr' is (or is not) @code{None}.


Added in version 3.1.

@end deffn

@geindex assertIn() (μέθοδος της unittest.TestCase)
@geindex assertNotIn() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertIn}@anchor{16e9}
@deffn {Μέθοδος} assertIn (member, container, msg=None)
@anchor{library/unittest unittest TestCase assertNotIn}@anchor{16ea}
@deffnx {Μέθοδος} assertNotIn (member, container, msg=None)

Test that `member' is (or is not) in `container'.


Added in version 3.1.

@end deffn

@geindex assertIsInstance() (μέθοδος της unittest.TestCase)
@geindex assertNotIsInstance() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertIsInstance}@anchor{16e2}
@deffn {Μέθοδος} assertIsInstance (obj, cls, msg=None)
@anchor{library/unittest unittest TestCase assertNotIsInstance}@anchor{16e3}
@deffnx {Μέθοδος} assertNotIsInstance (obj, cls, msg=None)

Test that `obj' is (or is not) an instance of `cls' (which can be a
class or a tuple of classes, as supported by @ref{2ef,,isinstance()}).
To check for the exact type, use @ref{16e0,,assertIs(type(obj)@comma{} cls)}.


Added in version 3.2.

@end deffn

@geindex assertIsSubclass() (μέθοδος της unittest.TestCase)
@geindex assertNotIsSubclass() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertIsSubclass}@anchor{532}
@deffn {Μέθοδος} assertIsSubclass (cls, superclass, msg=None)
@anchor{library/unittest unittest TestCase assertNotIsSubclass}@anchor{533}
@deffnx {Μέθοδος} assertNotIsSubclass (cls, superclass, msg=None)

Test that `cls' is (or is not) a subclass of `superclass' (which can be a
class or a tuple of classes, as supported by @ref{2f0,,issubclass()}).
To check for the exact type, use @ref{16e0,,assertIs(cls@comma{} superclass)}.


Added in version 3.14.

@end deffn

It is also possible to check the production of exceptions, warnings, and
log messages using the following methods:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

Method

@tab

Checks that

@tab

New in

@item

@ref{93b,,assertRaises(exc@comma{} fun@comma{} *args@comma{} **kwds)}

@tab

@code{fun(*args, **kwds)} raises `exc'

@tab

@item

@ref{93d,,assertRaisesRegex(exc@comma{} r@comma{} fun@comma{} *args@comma{} **kwds)}

@tab

@code{fun(*args, **kwds)} raises `exc'
and the message matches regex `r'

@tab

3.1

@item

@ref{2a0,,assertWarns(warn@comma{} fun@comma{} *args@comma{} **kwds)}

@tab

@code{fun(*args, **kwds)} raises `warn'

@tab

3.2

@item

@ref{2a1,,assertWarnsRegex(warn@comma{} r@comma{} fun@comma{} *args@comma{} **kwds)}

@tab

@code{fun(*args, **kwds)} raises `warn'
and the message matches regex `r'

@tab

3.2

@item

@ref{29f,,assertLogs(logger@comma{} level)}

@tab

The @code{with} block logs on `logger'
with minimum `level'

@tab

3.4

@item

@ref{c30,,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() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertRaises}@anchor{93b}
@deffn {Μέθοδος} assertRaises (exception, callable, *args, **kwds)

@deffnx {Μέθοδος} assertRaises (exception, *, msg=None)

Test that an exception is raised when `callable' is called with any
positional or keyword arguments that are also passed to
@code{assertRaises()}.  The test passes if `exception' is raised, is an
error if another exception is raised, or fails if no exception is raised.
To catch any of a group of exceptions, a tuple containing the exception
classes may be passed as `exception'.

If only the `exception' and possibly the `msg' arguments are given,
return a context manager so that the code under test can be written
inline rather than as a function:

@example
with self.assertRaises(SomeException):
    do_something()
@end example

When used as a context manager, @code{assertRaises()} accepts the
additional keyword argument `msg'.

The context manager will store the caught exception object in its
@code{exception} attribute.  This can be useful if the intention
is to perform additional checks on the exception raised:

@example
with self.assertRaises(SomeException) as cm:
    do_something()

the_exception = cm.exception
self.assertEqual(the_exception.error_code, 3)
@end example


Άλλαξε στην έκδοση 3.1: Added the ability to use @code{assertRaises()} as a context manager.



Άλλαξε στην έκδοση 3.2: Added the @code{exception} attribute.



Άλλαξε στην έκδοση 3.3: Added the `msg' keyword argument when used as a context manager.

@end deffn

@geindex assertRaisesRegex() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertRaisesRegex}@anchor{93d}
@deffn {Μέθοδος} assertRaisesRegex (exception, regex, callable, *args, **kwds)

@deffnx {Μέθοδος} assertRaisesRegex (exception, regex, *, msg=None)

Like @ref{93b,,assertRaises()} but also tests that `regex' matches
on the string representation of the raised exception.  `regex' may be
a regular expression object or a string containing a regular expression
suitable for use by @ref{15d3,,re.search()}.  Examples:

@example
self.assertRaisesRegex(ValueError, "invalid literal for.*XYZ'$",
                       int, 'XYZ')
@end example

or:

@example
with self.assertRaisesRegex(ValueError, 'literal'):
   int('XYZ')
@end example


Added in version 3.1: Added under the name @code{assertRaisesRegexp}.



Άλλαξε στην έκδοση 3.2: Renamed to @code{assertRaisesRegex()}.



Άλλαξε στην έκδοση 3.3: Added the `msg' keyword argument when used as a context manager.

@end deffn

@geindex assertWarns() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertWarns}@anchor{2a0}
@deffn {Μέθοδος} assertWarns (warning, callable, *args, **kwds)

@deffnx {Μέθοδος} assertWarns (warning, *, msg=None)

Test that a warning is triggered when `callable' is called with any
positional or keyword arguments that are also passed to
@code{assertWarns()}.  The test passes if `warning' is triggered and
fails if it isn’t.  Any exception is an error.
To catch any of a group of warnings, a tuple containing the warning
classes may be passed as `warnings'.

If only the `warning' and possibly the `msg' arguments are given,
return a context manager so that the code under test can be written
inline rather than as a function:

@example
with self.assertWarns(SomeWarning):
    do_something()
@end example

When used as a context manager, @code{assertWarns()} accepts the
additional keyword argument `msg'.

The context manager will store the caught warning object in its
@code{warning} attribute, and the source line which triggered the
warnings in the @code{filename} and @code{lineno} attributes.
This can be useful if the intention is to perform additional checks
on the warning caught:

@example
with self.assertWarns(SomeWarning) as cm:
    do_something()

self.assertIn('myfile.py', cm.filename)
self.assertEqual(320, cm.lineno)
@end example

The context managers can be nested to test that multiple different
warnings are emitted:

@example
with (self.assertWarns(SomeWarning),
      self.assertWarns(OtherWarning)):
    do_something()
@end example

This method works regardless of the warning filters in place when it
is called.


Added in version 3.2.



Άλλαξε στην έκδοση 3.3: Added the `msg' keyword argument when used as a context manager.



Άλλαξε στην έκδοση 3.15: Warnings that do not match the specified category are no longer
swallowed.
Nested context managers are now supported.

@end deffn

@geindex assertWarnsRegex() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertWarnsRegex}@anchor{2a1}
@deffn {Μέθοδος} assertWarnsRegex (warning, regex, callable, *args, **kwds)

@deffnx {Μέθοδος} assertWarnsRegex (warning, regex, *, msg=None)

Like @ref{2a0,,assertWarns()} but also tests that `regex' matches on the
message of the triggered warning.  `regex' may be a regular expression
object or a string containing a regular expression suitable for use
by @ref{15d3,,re.search()}.  Example:

@example
self.assertWarnsRegex(DeprecationWarning,
                      r'legacy_function\(\) is deprecated',
                      legacy_function, 'XYZ')
@end example

or:

@example
with self.assertWarnsRegex(RuntimeWarning, 'unsafe frobnicating'):
    frobnicate('/etc/passwd')
@end example

The context managers can be nested to test that multiple different
warnings are emitted:

@example
with (self.assertWarns(SomeWarning, regex1),
      self.assertWarns(OtherWarning, regex2)):
    do_something()
@end example


Added in version 3.2.



Άλλαξε στην έκδοση 3.3: Added the `msg' keyword argument when used as a context manager.



Άλλαξε στην έκδοση 3.15: Warnings that do not match the specified category or regex are
no longer swallowed.
Nested context managers are now supported.

@end deffn

@geindex assertLogs() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertLogs}@anchor{29f}
@deffn {Μέθοδος} assertLogs (logger=None, level=None, formatter=None)

A context manager to test that at least one message is logged on
the `logger' or one of its children, with at least the given
`level'.

If given, `logger' should be a @ref{f0c,,logging.Logger} object or a
@ref{1df,,str} giving the name of a logger.  The default is the root
logger, which will catch all messages that were not blocked by a
non-propagating descendent logger.

If given, `level' should be either a numeric logging level or
its string equivalent (for example either @code{"ERROR"} or
@ref{22d0,,logging.ERROR}).  The default is @ref{22ce,,logging.INFO}.

If given, `formatter' should be a @ref{1839,,logging.Formatter} object.
The default is a formatter with format string
@code{"%(levelname)s:%(name)s:%(message)s"}

The test passes if at least one message emitted inside the @code{with}
block matches the `logger' and `level' conditions, otherwise it fails.

The object returned by the context manager is a recording helper
which keeps tracks of the matching log messages.  It has two
attributes:

@geindex records (ιδιότητα της unittest.TestCase)
@anchor{library/unittest unittest TestCase records}@anchor{484a}
@deffn {Ιδιότητα} records

A list of @ref{138f,,logging.LogRecord} objects of the matching
log messages.
@end deffn

@geindex output (ιδιότητα της unittest.TestCase)
@anchor{library/unittest unittest TestCase output}@anchor{484b}
@deffn {Ιδιότητα} output

A list of @ref{1df,,str} objects with the formatted output of
matching messages.
@end deffn

Example:

@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


Added in version 3.4.



Άλλαξε στην έκδοση 3.15: Now accepts a `formatter' to control how messages are formatted.

@end deffn

@geindex assertNoLogs() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertNoLogs}@anchor{c30}
@deffn {Μέθοδος} 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{f0c,,logging.Logger} object or a
@ref{1df,,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{22d0,,logging.ERROR}).  The default is @ref{22ce,,logging.INFO}.

Unlike @ref{29f,,assertLogs()}, nothing will be returned by the context
manager.


Added in version 3.10.

@end deffn

There are also other methods used to perform more specific checks, such as:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} 
@headitem

Method

@tab

Checks that

@tab

New in

@item

@ref{939,,assertAlmostEqual(a@comma{} b)}

@tab

@code{round(a-b, 7) == 0}

@tab

@item

@ref{93a,,assertNotAlmostEqual(a@comma{} b)}

@tab

@code{round(a-b, 7) != 0}

@tab

@item

@ref{16e4,,assertGreater(a@comma{} b)}

@tab

@code{a > b}

@tab

3.1

@item

@ref{16e5,,assertGreaterEqual(a@comma{} b)}

@tab

@code{a >= b}

@tab

3.1

@item

@ref{16e6,,assertLess(a@comma{} b)}

@tab

@code{a < b}

@tab

3.1

@item

@ref{16e7,,assertLessEqual(a@comma{} b)}

@tab

@code{a <= b}

@tab

3.1

@item

@ref{93c,,assertRegex(s@comma{} r)}

@tab

@code{r.search(s)}

@tab

3.1

@item

@ref{93e,,assertNotRegex(s@comma{} r)}

@tab

@code{not r.search(s)}

@tab

3.2

@item

@ref{15d1,,assertCountEqual(a@comma{} b)}

@tab

`a' contains the same elements
as `b', regardless of their
order.

@tab

3.2

@item

@ref{534,,assertStartsWith(a@comma{} b)}

@tab

@code{a.startswith(b)}

@tab

3.14

@item

@ref{535,,assertNotStartsWith(a@comma{} b)}

@tab

@code{not a.startswith(b)}

@tab

3.14

@item

@ref{536,,assertEndsWith(a@comma{} b)}

@tab

@code{a.endswith(b)}

@tab

3.14

@item

@ref{537,,assertNotEndsWith(a@comma{} b)}

@tab

@code{not a.endswith(b)}

@tab

3.14

@item

@ref{530,,assertHasAttr(a@comma{} b)}

@tab

@code{hastattr(a, b)}

@tab

3.14

@item

@ref{531,,assertNotHasAttr(a@comma{} b)}

@tab

@code{not hastattr(a, b)}

@tab

3.14

@end multitable


@geindex assertAlmostEqual() (μέθοδος της unittest.TestCase)
@geindex assertNotAlmostEqual() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertAlmostEqual}@anchor{939}
@deffn {Μέθοδος} assertAlmostEqual (first, second, places=7, msg=None, delta=None)
@anchor{library/unittest unittest TestCase assertNotAlmostEqual}@anchor{93a}
@deffnx {Μέθοδος} assertNotAlmostEqual (first, second, places=7, msg=None, delta=None)

Test that `first' and `second' are approximately (or not approximately)
equal by computing the difference, rounding to the given number of
decimal `places' (default 7), and comparing to zero.  Note that these
methods round the values to the given number of `decimal places' (i.e.
like the @ref{167f,,round()} function) and not `significant digits'.

If `delta' is supplied instead of `places' then the difference
between `first' and `second' must be less or equal to (or greater than) `delta'.

Supplying both `delta' and `places' raises a @ref{291,,TypeError}.


Άλλαξε στην έκδοση 3.2: @code{assertAlmostEqual()} automatically considers almost equal objects
that compare equal.  @code{assertNotAlmostEqual()} automatically fails
if the objects compare equal.  Added the `delta' keyword argument.

@end deffn

@geindex assertGreater() (μέθοδος της unittest.TestCase)
@geindex assertGreaterEqual() (μέθοδος της unittest.TestCase)
@geindex assertLess() (μέθοδος της unittest.TestCase)
@geindex assertLessEqual() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertGreater}@anchor{16e4}
@deffn {Μέθοδος} assertGreater (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertGreaterEqual}@anchor{16e5}
@deffnx {Μέθοδος} assertGreaterEqual (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertLess}@anchor{16e6}
@deffnx {Μέθοδος} assertLess (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertLessEqual}@anchor{16e7}
@deffnx {Μέθοδος} assertLessEqual (first, second, msg=None)

Test that `first' is respectively >, >=, < or <= than `second' depending
on the method name.  If not, the test will fail:

@example
>>> self.assertGreaterEqual(3, 4)
AssertionError: "3" unexpectedly not greater than or equal to "4"
@end example


Added in version 3.1.

@end deffn

@geindex assertRegex() (μέθοδος της unittest.TestCase)
@geindex assertNotRegex() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertRegex}@anchor{93c}
@deffn {Μέθοδος} assertRegex (text, regex, msg=None)
@anchor{library/unittest unittest TestCase assertNotRegex}@anchor{93e}
@deffnx {Μέθοδος} assertNotRegex (text, regex, msg=None)

Test that a `regex' search matches (or does not match) `text'.  In case
of failure, the error message will include the pattern and the `text' (or
the pattern and the part of `text' that unexpectedly matched).  `regex'
may be a regular expression object or a string containing a regular
expression suitable for use by @ref{15d3,,re.search()}.


Added in version 3.1: Added under the name @code{assertRegexpMatches}.



Άλλαξε στην έκδοση 3.2: The method @code{assertRegexpMatches()} has been renamed to
@code{assertRegex()}.



Added in version 3.2: @code{assertNotRegex()}.

@end deffn

@geindex assertCountEqual() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertCountEqual}@anchor{15d1}
@deffn {Μέθοδος} assertCountEqual (first, second, msg=None)

Test that sequence `first' contains the same elements as `second',
regardless of their order. When they don’t, an error message listing the
differences between the sequences will be generated.

Duplicate elements are `not' ignored when comparing `first' and
`second'. It verifies whether each element has the same count in both
sequences. Equivalent to:
@code{assertEqual(Counter(list(first)), Counter(list(second)))}
but works with sequences of unhashable objects as well.


Added in version 3.2.

@end deffn

@geindex assertStartsWith() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertStartsWith}@anchor{534}
@deffn {Μέθοδος} assertStartsWith (s, prefix, msg=None)
@end deffn

@geindex assertNotStartsWith() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertNotStartsWith}@anchor{535}
@deffn {Μέθοδος} assertNotStartsWith (s, prefix, msg=None)

Test that the Unicode or byte string `s' starts (or does not start)
with a `prefix'.
`prefix' can also be a tuple of strings to try.


Added in version 3.14.

@end deffn

@geindex assertEndsWith() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertEndsWith}@anchor{536}
@deffn {Μέθοδος} assertEndsWith (s, suffix, msg=None)
@end deffn

@geindex assertNotEndsWith() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertNotEndsWith}@anchor{537}
@deffn {Μέθοδος} assertNotEndsWith (s, suffix, msg=None)

Test that the Unicode or byte string `s' ends (or does not end)
with a `suffix'.
`suffix' can also be a tuple of strings to try.


Added in version 3.14.

@end deffn

@geindex assertHasAttr() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertHasAttr}@anchor{530}
@deffn {Μέθοδος} assertHasAttr (obj, name, msg=None)
@end deffn

@geindex assertNotHasAttr() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertNotHasAttr}@anchor{531}
@deffn {Μέθοδος} assertNotHasAttr (obj, name, msg=None)

Test that the object `obj' has (or has not) an attribute `name'.


Added in version 3.14.

@end deffn
@anchor{library/unittest type-specific-methods}@anchor{4849}
The @ref{937,,assertEqual()} method dispatches the equality check for objects of
the same type to different type-specific methods.  These methods are already
implemented for most of the built-in types, but it’s also possible to
register new methods using @ref{16ed,,addTypeEqualityFunc()}:

@geindex addTypeEqualityFunc() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase addTypeEqualityFunc}@anchor{16ed}
@deffn {Μέθοδος} addTypeEqualityFunc (typeobj, function)

Registers a type-specific method called by @ref{937,,assertEqual()} to check
if two objects of exactly the same `typeobj' (not subclasses) compare
equal.  `function' must take two positional arguments and a third msg=None
keyword argument just as @code{assertEqual()} does.  It must raise
@ref{484c,,self.failureException(msg)} when inequality
between the first two parameters is detected – possibly providing useful
information and explaining the inequalities in details in the error
message.


Added in version 3.1.

@end deffn

The list of type-specific methods automatically used by
@ref{937,,assertEqual()} are summarized in the following table.  Note
that it’s usually not necessary to invoke these methods directly.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} 
@headitem

Method

@tab

Used to compare

@tab

New in

@item

@ref{16e8,,assertMultiLineEqual(a@comma{} b)}

@tab

strings

@tab

3.1

@item

@ref{162e,,assertSequenceEqual(a@comma{} b)}

@tab

sequences

@tab

3.1

@item

@ref{162c,,assertListEqual(a@comma{} b)}

@tab

lists

@tab

3.1

@item

@ref{162d,,assertTupleEqual(a@comma{} b)}

@tab

tuples

@tab

3.1

@item

@ref{162a,,assertSetEqual(a@comma{} b)}

@tab

sets or frozensets

@tab

3.1

@item

@ref{162b,,assertDictEqual(a@comma{} b)}

@tab

dicts

@tab

3.1

@end multitable


@geindex assertMultiLineEqual() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertMultiLineEqual}@anchor{16e8}
@deffn {Μέθοδος} assertMultiLineEqual (first, second, msg=None)

Test that the multiline string `first' is equal to the string `second'.
When not equal a diff of the two strings highlighting the differences
will be included in the error message. This method is used by default
when comparing strings with @ref{937,,assertEqual()}.


Added in version 3.1.

@end deffn

@geindex assertSequenceEqual() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertSequenceEqual}@anchor{162e}
@deffn {Μέθοδος} assertSequenceEqual (first, second, msg=None, seq_type=None)

Tests that two sequences are equal.  If a `seq_type' is supplied, both
`first' and `second' must be instances of `seq_type' or a failure will
be raised.  If the sequences are different an error message is
constructed that shows the difference between the two.

This method is not called directly by @ref{937,,assertEqual()}, but
it’s used to implement @ref{162c,,assertListEqual()} and
@ref{162d,,assertTupleEqual()}.


Added in version 3.1.

@end deffn

@geindex assertListEqual() (μέθοδος της unittest.TestCase)
@geindex assertTupleEqual() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertListEqual}@anchor{162c}
@deffn {Μέθοδος} assertListEqual (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertTupleEqual}@anchor{162d}
@deffnx {Μέθοδος} assertTupleEqual (first, second, msg=None)

Tests that two lists or tuples are equal.  If not, an error message is
constructed that shows only the differences between the two.  An error
is also raised if either of the parameters are of the wrong type.
These methods are used by default when comparing lists or tuples with
@ref{937,,assertEqual()}.


Added in version 3.1.

@end deffn

@geindex assertSetEqual() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertSetEqual}@anchor{162a}
@deffn {Μέθοδος} assertSetEqual (first, second, msg=None)

Tests that two sets are equal.  If not, an error message is constructed
that lists the differences between the sets.  This method is used by
default when comparing sets or frozensets with @ref{937,,assertEqual()}.

Fails if either of `first' or `second' does not have a @ref{2891,,difference()}
method.


Added in version 3.1.

@end deffn

@geindex assertDictEqual() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase assertDictEqual}@anchor{162b}
@deffn {Μέθοδος} assertDictEqual (first, second, msg=None)

Test that two dictionaries are equal.  If not, an error message is
constructed that shows the differences in the dictionaries. This
method will be used by default to compare dictionaries in
calls to @ref{937,,assertEqual()}.


Added in version 3.1.

@end deffn
@anchor{library/unittest other-methods-and-attrs}@anchor{484d}
Finally the @code{TestCase} provides the following methods and attributes:

@geindex fail() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase fail}@anchor{484e}
@deffn {Μέθοδος} fail (msg=None)

Signals a test failure unconditionally, with `msg' or @code{None} for
the error message.
@end deffn

@geindex failureException (ιδιότητα της unittest.TestCase)
@anchor{library/unittest unittest TestCase failureException}@anchor{484c}
@deffn {Ιδιότητα} failureException

This class attribute gives the exception raised by the test method.  If a
test framework needs to use a specialized exception, possibly to carry
additional information, it must subclass this exception in order to «play
fair» with the framework.  The initial value of this attribute is
@ref{a97,,AssertionError}.
@end deffn

@geindex longMessage (ιδιότητα της unittest.TestCase)
@anchor{library/unittest unittest TestCase longMessage}@anchor{16da}
@deffn {Ιδιότητα} longMessage

This class attribute determines what happens when a custom failure message
is passed as the msg argument to an assertXYY call that fails.
@code{True} is the default value. In this case, the custom message is appended
to the end of the standard failure message.
When set to @code{False}, the custom message replaces the standard message.

The class setting can be overridden in individual test methods by assigning
an instance attribute, self.longMessage, to @code{True} or @code{False} before
calling the assert methods.

The class setting gets reset before each test call.


Added in version 3.1.

@end deffn

@geindex maxDiff (ιδιότητα της unittest.TestCase)
@anchor{library/unittest unittest TestCase maxDiff}@anchor{15d2}
@deffn {Ιδιότητα} maxDiff

This attribute controls the maximum length of diffs output by assert
methods that report diffs on failure. It defaults to 80*8 characters.
Assert methods affected by this attribute are
@ref{162e,,assertSequenceEqual()} (including all the sequence comparison
methods that delegate to it), @ref{162b,,assertDictEqual()} and
@ref{16e8,,assertMultiLineEqual()}.

Setting @code{maxDiff} to @code{None} means that there is no maximum length of
diffs.


Added in version 3.2.

@end deffn

Testing frameworks can use the following methods to collect information on
the test:

@geindex countTestCases() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase countTestCases}@anchor{484f}
@deffn {Μέθοδος} countTestCases ()

Return the number of tests represented by this test object.  For
@code{TestCase} instances, this will always be @code{1}.
@end deffn

@geindex defaultTestResult() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase defaultTestResult}@anchor{4848}
@deffn {Μέθοδος} defaultTestResult ()

Return an instance of the test result class that should be used for this
test case class (if no other result instance is provided to the
@ref{150f,,run()} method).

For @code{TestCase} instances, this will always be an instance of
@ref{1510,,TestResult}; subclasses of @code{TestCase} should override this
as necessary.
@end deffn

@geindex id() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase id}@anchor{4850}
@deffn {Μέθοδος} id ()

Return a string identifying the specific test case.  This is usually the
full name of the test method, including the module and class name.
@end deffn

@geindex shortDescription() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase shortDescription}@anchor{4851}
@deffn {Μέθοδος} shortDescription ()

Returns a description of the test, or @code{None} if no description
has been provided.  The default implementation of this method
returns the first line of the test method’s docstring, if available,
or @code{None}.


Άλλαξε στην έκδοση 3.1: In 3.1 this was changed to add the test name to the short description
even in the presence of a docstring.  This caused compatibility issues
with unittest extensions and adding the test name was moved to the
@ref{93f,,TextTestResult} in Python 3.2.

@end deffn

@geindex addCleanup() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase addCleanup}@anchor{e43}
@deffn {Μέθοδος} addCleanup (function, /, *args, **kwargs)

Add a function to be called after @ref{16df,,tearDown()} to cleanup resources
used during the test. Functions will be called in reverse order to the
order they are added (@abbr{LIFO}).  They
are called with any arguments and keyword arguments passed into
@code{addCleanup()} when they are added.

If @ref{16de,,setUp()} fails, meaning that @ref{16df,,tearDown()} is not called,
then any cleanup functions added will still be called.


Added in version 3.1.

@end deffn

@geindex enterContext() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase enterContext}@anchor{aa6}
@deffn {Μέθοδος} enterContext (cm)

Enter the supplied @ref{478,,context manager}.  If successful, also
add its @ref{16a5,,__exit__()} method as a cleanup function by
@ref{e43,,addCleanup()} and return the result of the
@ref{9c6,,__enter__()} method.


Added in version 3.11.

@end deffn

@geindex doCleanups() (μέθοδος της unittest.TestCase)
@anchor{library/unittest unittest TestCase doCleanups}@anchor{16dd}
@deffn {Μέθοδος} doCleanups ()

This method is called unconditionally after @ref{16df,,tearDown()}, or
after @ref{16de,,setUp()} if @code{setUp()} raises an exception.

It is responsible for calling all the cleanup functions added by
@ref{e43,,addCleanup()}. If you need cleanup functions to be called
`prior' to @ref{16df,,tearDown()} then you can call @code{doCleanups()}
yourself.

@code{doCleanups()} pops methods off the stack of cleanup
functions one at a time, so it can be called at any time.


Added in version 3.1.

@end deffn

@geindex addClassCleanup() (μέθοδος κλάσης της unittest.TestCase)
@anchor{library/unittest unittest TestCase addClassCleanup}@anchor{e10}
@deffn {Μέθοδος} classmethod addClassCleanup (function, /, *args, **kwargs)

Add a function to be called after @ref{16dc,,tearDownClass()} to cleanup
resources used during the test class. Functions will be called in reverse
order to the order they are added (@abbr{LIFO}).
They are called with any arguments and keyword arguments passed into
@code{addClassCleanup()} when they are added.

If @ref{e12,,setUpClass()} fails, meaning that @ref{16dc,,tearDownClass()} is not
called, then any cleanup functions added will still be called.


Added in version 3.8.

@end deffn

@geindex enterClassContext() (μέθοδος κλάσης της unittest.TestCase)
@anchor{library/unittest unittest TestCase enterClassContext}@anchor{aa7}
@deffn {Μέθοδος} classmethod enterClassContext (cm)

Enter the supplied @ref{478,,context manager}.  If successful, also
add its @ref{16a5,,__exit__()} method as a cleanup function by
@ref{e10,,addClassCleanup()} and return the result of the
@ref{9c6,,__enter__()} method.


Added in version 3.11.

@end deffn

@geindex doClassCleanups() (μέθοδος κλάσης της unittest.TestCase)
@anchor{library/unittest unittest TestCase doClassCleanups}@anchor{4852}
@deffn {Μέθοδος} classmethod doClassCleanups ()

This method is called unconditionally after @ref{16dc,,tearDownClass()}, or
after @ref{e12,,setUpClass()} if @code{setUpClass()} raises an exception.

It is responsible for calling all the cleanup functions added by
@ref{e10,,addClassCleanup()}. If you need cleanup functions to be called
`prior' to @ref{16dc,,tearDownClass()} then you can call
@code{doClassCleanups()} yourself.

@code{doClassCleanups()} pops methods off the stack of cleanup
functions one at a time, so it can be called at any time.


Added in version 3.8.

@end deffn
@end deffn

@geindex IsolatedAsyncioTestCase (κλάση σε unittest)
@anchor{library/unittest unittest IsolatedAsyncioTestCase}@anchor{342}
@deffn {Κλάση} unittest.IsolatedAsyncioTestCase (methodName='runTest')

This class provides an API similar to @ref{52f,,TestCase} and also accepts
coroutines as test functions.


Added in version 3.8.


@geindex loop_factory (ιδιότητα της unittest.IsolatedAsyncioTestCase)
@anchor{library/unittest unittest IsolatedAsyncioTestCase loop_factory}@anchor{4853}
@deffn {Ιδιότητα} loop_factory

The `loop_factory' passed to @ref{30a,,asyncio.Runner}. Override
in subclasses with @ref{1c6d,,asyncio.EventLoop} to avoid using the
asyncio policy system.


Added in version 3.13.

@end deffn

@geindex asyncSetUp() (μέθοδος της unittest.IsolatedAsyncioTestCase)
@anchor{library/unittest unittest IsolatedAsyncioTestCase asyncSetUp}@anchor{4854}
@deffn {Μέθοδος} async asyncSetUp ()

Method called to prepare the test fixture. This is called after @ref{16de,,TestCase.setUp()}.
This is called immediately before calling the test method; other than
@ref{a97,,AssertionError} or @ref{138d,,SkipTest}, any exception raised by this method
will be considered an error rather than a test failure. The default implementation
does nothing.
@end deffn

@geindex asyncTearDown() (μέθοδος της unittest.IsolatedAsyncioTestCase)
@anchor{library/unittest unittest IsolatedAsyncioTestCase asyncTearDown}@anchor{4855}
@deffn {Μέθοδος} async asyncTearDown ()

Method called immediately after the test method has been called and the
result recorded.  This is called before @ref{16df,,tearDown()}. This is called even if
the test method raised an exception, so the implementation in subclasses may need
to be particularly careful about checking internal state.  Any exception, other than
@ref{a97,,AssertionError} or @ref{138d,,SkipTest}, raised by this method will be
considered an additional error rather than a test failure (thus increasing
the total number of reported errors). This method will only be called if
the @ref{4854,,asyncSetUp()} succeeds, regardless of the outcome of the test method.
The default implementation does nothing.
@end deffn

@geindex addAsyncCleanup() (μέθοδος της unittest.IsolatedAsyncioTestCase)
@anchor{library/unittest unittest IsolatedAsyncioTestCase addAsyncCleanup}@anchor{4856}
@deffn {Μέθοδος} addAsyncCleanup (function, /, *args, **kwargs)

This method accepts a coroutine that can be used as a cleanup function.
@end deffn

@geindex enterAsyncContext() (μέθοδος της unittest.IsolatedAsyncioTestCase)
@anchor{library/unittest unittest IsolatedAsyncioTestCase enterAsyncContext}@anchor{aa8}
@deffn {Μέθοδος} async enterAsyncContext (cm)

Enter the supplied @ref{9d2,,asynchronous context manager}.  If successful,
also add its @ref{1bad,,__aexit__()} method as a cleanup function by
@ref{4856,,addAsyncCleanup()} and return the result of the
@ref{2613,,__aenter__()} method.


Added in version 3.11.

@end deffn

@geindex run() (μέθοδος της unittest.IsolatedAsyncioTestCase)
@anchor{library/unittest unittest IsolatedAsyncioTestCase run}@anchor{4857}
@deffn {Μέθοδος} run (result=None)

Sets up a new event loop to run the test, collecting the result into
the @ref{1510,,TestResult} object passed as `result'.  If `result' is
omitted or @code{None}, a temporary result object is created (by calling
the @ref{4848,,defaultTestResult()} method) and used. The result object is
returned to @code{run()}”s caller. At the end of the test all the tasks
in the event loop are cancelled.
@end deffn

An example illustrating the order:

@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

After running the test, @code{events} would contain @code{["setUp", "asyncSetUp", "test_response", "asyncTearDown", "tearDown", "cleanup"]}.
@end deffn

@geindex FunctionTestCase (κλάση σε unittest)
@anchor{library/unittest unittest FunctionTestCase}@anchor{1c7f}
@deffn {Κλάση} unittest.FunctionTestCase (testFunc, setUp=None, tearDown=None, description=None)

This class implements the portion of the @ref{52f,,TestCase} interface which
allows the test runner to drive the test, but does not provide the methods
which test code can use to check and report errors.  This is used to create
test cases using legacy test code, allowing it to be integrated into a
@code{unittest}-based test framework.
@end deffn

@node Grouping tests,Loading and running tests,Test cases,Classes and functions
@anchor{library/unittest grouping-tests}@anchor{4858}@anchor{library/unittest testsuite-objects}@anchor{4859}
@subsubsection Grouping tests


@geindex TestSuite (κλάση σε unittest)
@anchor{library/unittest unittest TestSuite}@anchor{11ad}
@deffn {Κλάση} unittest.TestSuite (tests=())

This class represents an aggregation of individual test cases and test suites.
The class presents the interface needed by the test runner to allow it to be run
as any other test case.  Running a @code{TestSuite} instance is the same as
iterating over the suite, running each test individually.

If `tests' is given, it must be an iterable of individual test cases or other
test suites that will be used to build the suite initially. Additional methods
are provided to add test cases and suites to the collection later on.

@code{TestSuite} objects behave much like @ref{52f,,TestCase} objects, except
they do not actually implement a test.  Instead, they are used to aggregate
tests into groups of tests that should be run together. Some additional
methods are available to add tests to @code{TestSuite} instances:

@geindex addTest() (μέθοδος της unittest.TestSuite)
@anchor{library/unittest unittest TestSuite addTest}@anchor{485a}
@deffn {Μέθοδος} addTest (test)

Add a @ref{52f,,TestCase} or @code{TestSuite} to the suite.
@end deffn

@geindex addTests() (μέθοδος της unittest.TestSuite)
@anchor{library/unittest unittest TestSuite addTests}@anchor{485b}
@deffn {Μέθοδος} addTests (tests)

Add all the tests from an iterable of @ref{52f,,TestCase} and @code{TestSuite}
instances to this test suite.

This is equivalent to iterating over `tests', calling @ref{485a,,addTest()} for
each element.
@end deffn

@code{TestSuite} shares the following methods with @ref{52f,,TestCase}:

@geindex run() (μέθοδος της unittest.TestSuite)
@anchor{library/unittest unittest TestSuite run}@anchor{485c}
@deffn {Μέθοδος} run (result)

Run the tests associated with this suite, collecting the result into the
test result object passed as `result'.  Note that unlike
@ref{150f,,TestCase.run()}, @code{TestSuite.run()} requires the result object to
be passed in.
@end deffn

@geindex debug() (μέθοδος της unittest.TestSuite)
@anchor{library/unittest unittest TestSuite debug}@anchor{485d}
@deffn {Μέθοδος} debug ()

Run the tests associated with this suite without collecting the
result. This allows exceptions raised by the test to be propagated to the
caller and can be used to support running tests under a debugger.
@end deffn

@geindex countTestCases() (μέθοδος της unittest.TestSuite)
@anchor{library/unittest unittest TestSuite countTestCases}@anchor{485e}
@deffn {Μέθοδος} countTestCases ()

Return the number of tests represented by this test object, including all
individual tests and sub-suites.
@end deffn

@geindex __iter__() (μέθοδος της unittest.TestSuite)
@anchor{library/unittest unittest TestSuite __iter__}@anchor{13d1}
@deffn {Μέθοδος} __iter__ ()

Tests grouped by a @code{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{485c,,TestSuite.run()} must be the
same for each call iteration. After @code{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.


Άλλαξε στην έκδοση 3.2: In earlier versions the @code{TestSuite} accessed tests directly rather
than through iteration, so overriding @code{__iter__()} wasn’t sufficient
for providing tests.



Άλλαξε στην έκδοση 3.4: In earlier versions the @code{TestSuite} held references to each
@ref{52f,,TestCase} after @ref{485c,,TestSuite.run()}. Subclasses can restore
that behavior by overriding @code{TestSuite._removeTestAtIndex()}.

@end deffn

In the typical usage of a @code{TestSuite} object, the @ref{485c,,run()} method
is invoked by a @code{TestRunner} rather than by the end-user test harness.
@end deffn

@node Loading and running tests,,Grouping tests,Classes and functions
@anchor{library/unittest loading-and-running-tests}@anchor{485f}
@subsubsection Loading and running tests


@geindex TestLoader (κλάση σε unittest)
@anchor{library/unittest unittest TestLoader}@anchor{792}
@deffn {Κλάση} unittest.TestLoader

The @code{TestLoader} class is used to create test suites from classes and
modules.  Normally, there is no need to create an instance of this class; the
@code{unittest} module provides an instance that can be shared as
@ref{4860,,unittest.defaultTestLoader}.  Using a subclass or instance, however,
allows customization of some configurable properties.

@code{TestLoader} objects have the following attributes:

@geindex errors (ιδιότητα της unittest.TestLoader)
@anchor{library/unittest unittest TestLoader errors}@anchor{123d}
@deffn {Ιδιότητα} 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.


Added in version 3.5.

@end deffn

@code{TestLoader} objects have the following methods:

@geindex loadTestsFromTestCase() (μέθοδος της unittest.TestLoader)
@anchor{library/unittest unittest TestLoader loadTestsFromTestCase}@anchor{794}
@deffn {Μέθοδος} loadTestsFromTestCase (testCaseClass)

Return a suite of all test cases contained in the @ref{52f,,TestCase}-derived
@code{testCaseClass}.

A test case instance is created for each method named by
@ref{795,,getTestCaseNames()}. By default these are the method names
beginning with @code{test}. If @code{getTestCaseNames()} returns no
methods, but the @code{runTest()} method is implemented, a single test
case is created for that method instead.
@end deffn

@geindex loadTestsFromModule() (μέθοδος της unittest.TestLoader)
@anchor{library/unittest unittest TestLoader loadTestsFromModule}@anchor{793}
@deffn {Μέθοδος} loadTestsFromModule (module, *, pattern=None)

Return a suite of all test cases contained in the given module. This
method searches `module' for classes derived from @ref{52f,,TestCase} and
creates an instance of the class for each test method defined for the
class.

@cartouche
@quotation Σημείωση 
While using a hierarchy of @ref{52f,,TestCase}-derived classes can be
convenient in sharing fixtures and helper functions, defining test
methods on base classes that are not intended to be instantiated
directly does not play well with this method.  Doing so, however, can
be useful when the fixtures are different and defined in subclasses.
@end quotation
@end cartouche

If a module provides a @code{load_tests} function it will be called to
load the tests. This allows modules to customize test loading.
This is the @ref{4838,,load_tests protocol}.  The `pattern' argument is passed as
the third argument to @code{load_tests}.


Άλλαξε στην έκδοση 3.2: Support for @code{load_tests} added.



Άλλαξε στην έκδοση 3.5: Support for a keyword-only argument `pattern' has been added.



Άλλαξε στην έκδοση 3.12: The undocumented and unofficial `use_load_tests' parameter has been
removed.

@end deffn

@geindex loadTestsFromName() (μέθοδος της unittest.TestLoader)
@anchor{library/unittest unittest TestLoader loadTestsFromName}@anchor{16eb}
@deffn {Μέθοδος} loadTestsFromName (name, module=None)

Return a suite of all test cases given a string specifier.

The specifier `name' is a «dotted name» that may resolve either to a
module, a test case class, a test method within a test case class, a
@ref{11ad,,TestSuite} instance, or a callable object which returns a
@ref{52f,,TestCase} or @code{TestSuite} instance.  These checks are
applied in the order listed here; that is, a method on a possible test
case class will be picked up as «a test method within a test case class»,
rather than «a callable object».

For example, if you have a module @code{SampleTests} containing a
@ref{52f,,TestCase}-derived class @code{SampleTestCase} with three test
methods (@code{test_one()}, @code{test_two()}, and @code{test_three()}), the
specifier @code{'SampleTests.SampleTestCase'} would cause this method to
return a suite which will run all three test methods. Using the specifier
@code{'SampleTests.SampleTestCase.test_two'} would cause it to return a test
suite which will run only the @code{test_two()} test method. The specifier
can refer to modules and packages which have not been imported; they will
be imported as a side-effect.

The method optionally resolves `name' relative to the given `module'.


Άλλαξε στην έκδοση 3.5: If an @ref{1bd,,ImportError} or @ref{1a9,,AttributeError} occurs while traversing
`name' then a synthetic test that raises that error when run will be
returned. These errors are included in the errors accumulated by
self.errors.

@end deffn

@geindex loadTestsFromNames() (μέθοδος της unittest.TestLoader)
@anchor{library/unittest unittest TestLoader loadTestsFromNames}@anchor{4861}
@deffn {Μέθοδος} loadTestsFromNames (names, module=None)

Similar to @ref{16eb,,loadTestsFromName()}, but takes a sequence of names rather
than a single name.  The return value is a test suite which supports all
the tests defined for each name.
@end deffn

@geindex getTestCaseNames() (μέθοδος της unittest.TestLoader)
@anchor{library/unittest unittest TestLoader getTestCaseNames}@anchor{795}
@deffn {Μέθοδος} getTestCaseNames (testCaseClass)

Return a sorted sequence of method names found within `testCaseClass';
this should be a subclass of @ref{52f,,TestCase}.
@end deffn

@geindex discover() (μέθοδος της unittest.TestLoader)
@anchor{library/unittest unittest TestLoader discover}@anchor{138e}
@deffn {Μέθοδος} discover (start_dir, pattern='test*.py', top_level_dir=None)

Find all the test modules by recursing into subdirectories from the
specified start directory, and return a TestSuite object containing them.
Only test files that match `pattern' will be loaded. (Using shell style
pattern matching.) Only module names that are importable (i.e. are valid
Python identifiers) will be loaded.

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.

If importing a module fails, for example due to a syntax error, then
this will be recorded as a single error and discovery will continue.  If
the import failure is due to @ref{138d,,SkipTest} being raised, it will be
recorded as a skip instead of an error.

If a package (a directory containing a file named @code{__init__.py}) is
found, the package will be checked for a @code{load_tests} function. If this
exists then it will be called
@code{package.load_tests(loader, tests, pattern)}. Test discovery takes care
to ensure that a package is only checked for tests once during an
invocation, even if the load_tests function itself calls
@code{loader.discover}.

If @code{load_tests} exists then discovery does `not' recurse into the
package, @code{load_tests} is responsible for loading all tests in the
package.

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' can be a dotted module name as well as a directory.


Added in version 3.2.



Άλλαξε στην έκδοση 3.4: Modules that raise @ref{138d,,SkipTest} on import are recorded as skips,
not errors.

`start_dir' can be a @ref{52e,,namespace packages}.

Paths are sorted before being imported so that execution order is the
same even if the underlying file system’s ordering is not dependent
on file name.



Άλλαξε στην έκδοση 3.5: 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.



Άλλαξε στην έκδοση 3.11: `start_dir' can not be a @ref{52e,,namespace packages}.
It has been broken since Python 3.7, and Python 3.11 officially removes it.



Άλλαξε στην έκδοση 3.13: `top_level_dir' is only stored for the duration of `discover' call.



Άλλαξε στην έκδοση 3.14: `start_dir' can once again be a @ref{52e,,namespace package}.

@end deffn

The following attributes of a @code{TestLoader} can be configured either by
subclassing or assignment on an instance:

@geindex testMethodPrefix (ιδιότητα της unittest.TestLoader)
@anchor{library/unittest unittest TestLoader testMethodPrefix}@anchor{4862}
@deffn {Ιδιότητα} testMethodPrefix

String giving the prefix of method names which will be interpreted as test
methods.  The default value is @code{'test'}.

This affects @ref{795,,getTestCaseNames()} and all the @code{loadTestsFrom*}
methods.
@end deffn

@geindex sortTestMethodsUsing (ιδιότητα της unittest.TestLoader)
@anchor{library/unittest unittest TestLoader sortTestMethodsUsing}@anchor{4863}
@deffn {Ιδιότητα} sortTestMethodsUsing

Function to be used to compare method names when sorting them in
@ref{795,,getTestCaseNames()} and all the @code{loadTestsFrom*} methods.
@end deffn

@geindex suiteClass (ιδιότητα της unittest.TestLoader)
@anchor{library/unittest unittest TestLoader suiteClass}@anchor{16ec}
@deffn {Ιδιότητα} suiteClass

Callable object that constructs a test suite from a list of tests. No
methods on the resulting object are needed.  The default value is the
@ref{11ad,,TestSuite} class.

This affects all the @code{loadTestsFrom*} methods.
@end deffn

@geindex testNamePatterns (ιδιότητα της unittest.TestLoader)
@anchor{library/unittest unittest TestLoader testNamePatterns}@anchor{4864}
@deffn {Ιδιότητα} 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{1e4c,,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.


Added in version 3.7.

@end deffn
@end deffn

@geindex TestResult (κλάση σε unittest)
@anchor{library/unittest unittest TestResult}@anchor{1510}
@deffn {Κλάση} unittest.TestResult

This class is used to compile information about which tests have succeeded
and which have failed.

A @code{TestResult} object stores the results of a set of tests.  The
@ref{52f,,TestCase} and @ref{11ad,,TestSuite} classes ensure that results are
properly recorded; test authors do not need to worry about recording the
outcome of tests.

Testing frameworks built on top of @code{unittest} may want access to the
@code{TestResult} object generated by running a set of tests for reporting
purposes; a @code{TestResult} instance is returned by the
@code{TestRunner.run()} method for this purpose.

@code{TestResult} instances have the following attributes that will be of
interest when inspecting the results of running a set of tests:

@geindex errors (ιδιότητα της unittest.TestResult)
@anchor{library/unittest unittest TestResult errors}@anchor{4865}
@deffn {Ιδιότητα} errors

A list containing 2-tuples of @ref{52f,,TestCase} instances and strings
holding formatted tracebacks. Each tuple represents a test which raised an
unexpected exception.
@end deffn

@geindex failures (ιδιότητα της unittest.TestResult)
@anchor{library/unittest unittest TestResult failures}@anchor{4866}
@deffn {Ιδιότητα} failures

A list containing 2-tuples of @ref{52f,,TestCase} instances and strings
holding formatted tracebacks. Each tuple represents a test where a failure
was explicitly signalled using the @ref{4820,,assert* methods}.
@end deffn

@geindex skipped (ιδιότητα της unittest.TestResult)
@anchor{library/unittest unittest TestResult skipped}@anchor{4867}
@deffn {Ιδιότητα} skipped

A list containing 2-tuples of @ref{52f,,TestCase} instances and strings
holding the reason for skipping the test.


Added in version 3.1.

@end deffn

@geindex expectedFailures (ιδιότητα της unittest.TestResult)
@anchor{library/unittest unittest TestResult expectedFailures}@anchor{4868}
@deffn {Ιδιότητα} expectedFailures

A list containing 2-tuples of @ref{52f,,TestCase} instances and strings
holding formatted tracebacks.  Each tuple represents an expected failure
or error of the test case.
@end deffn

@geindex unexpectedSuccesses (ιδιότητα της unittest.TestResult)
@anchor{library/unittest unittest TestResult unexpectedSuccesses}@anchor{4869}
@deffn {Ιδιότητα} unexpectedSuccesses

A list containing @ref{52f,,TestCase} instances that were marked as expected
failures, but succeeded.
@end deffn

@geindex collectedDurations (ιδιότητα της unittest.TestResult)
@anchor{library/unittest unittest TestResult collectedDurations}@anchor{1c82}
@deffn {Ιδιότητα} collectedDurations

A list containing 2-tuples of test case names and floats
representing the elapsed time of each test which was run.


Added in version 3.12.

@end deffn

@geindex shouldStop (ιδιότητα της unittest.TestResult)
@anchor{library/unittest unittest TestResult shouldStop}@anchor{486a}
@deffn {Ιδιότητα} shouldStop

Set to @code{True} when the execution of tests should stop by @ref{486b,,stop()}.
@end deffn

@geindex testsRun (ιδιότητα της unittest.TestResult)
@anchor{library/unittest unittest TestResult testsRun}@anchor{486c}
@deffn {Ιδιότητα} testsRun

The total number of tests run so far.
@end deffn

@geindex buffer (ιδιότητα της unittest.TestResult)
@anchor{library/unittest unittest TestResult buffer}@anchor{486d}
@deffn {Ιδιότητα} buffer

If set to true, @code{sys.stdout} and @code{sys.stderr} will be buffered in between
@ref{486e,,startTest()} and @ref{486f,,stopTest()} being called. Collected output will
only be echoed onto the real @code{sys.stdout} and @code{sys.stderr} if the test
fails or errors. Any output is also attached to the failure / error message.


Added in version 3.2.

@end deffn

@geindex failfast (ιδιότητα της unittest.TestResult)
@anchor{library/unittest unittest TestResult failfast}@anchor{4870}
@deffn {Ιδιότητα} failfast

If set to true @ref{486b,,stop()} will be called on the first failure or error,
halting the test run.


Added in version 3.2.

@end deffn

@geindex tb_locals (ιδιότητα της unittest.TestResult)
@anchor{library/unittest unittest TestResult tb_locals}@anchor{4871}
@deffn {Ιδιότητα} tb_locals

If set to true then local variables will be shown in tracebacks.


Added in version 3.5.

@end deffn

@geindex wasSuccessful() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult wasSuccessful}@anchor{4872}
@deffn {Μέθοδος} wasSuccessful ()

Return @code{True} if all tests run so far have passed, otherwise returns
@code{False}.


Άλλαξε στην έκδοση 3.4: Returns @code{False} if there were any @ref{4869,,unexpectedSuccesses}
from tests marked with the @ref{483f,,expectedFailure()} decorator.

@end deffn

@geindex stop() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult stop}@anchor{486b}
@deffn {Μέθοδος} stop ()

This method can be called to signal that the set of tests being run should
be aborted by setting the @ref{486a,,shouldStop} attribute to @code{True}.
@code{TestRunner} objects should respect this flag and return without
running any additional tests.

For example, this feature is used by the @ref{1cb9,,TextTestRunner} class to
stop the test framework when the user signals an interrupt from the
keyboard.  Interactive tools which provide @code{TestRunner}
implementations can use this in a similar manner.
@end deffn

The following methods of the @code{TestResult} class are used to maintain
the internal data structures, and may be extended in subclasses to support
additional reporting requirements.  This is particularly useful in building
tools which support interactive reporting while tests are being run.

@geindex startTest() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult startTest}@anchor{486e}
@deffn {Μέθοδος} startTest (test)

Called when the test case `test' is about to be run.
@end deffn

@geindex stopTest() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult stopTest}@anchor{486f}
@deffn {Μέθοδος} stopTest (test)

Called after the test case `test' has been executed, regardless of the
outcome.
@end deffn

@geindex startTestRun() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult startTestRun}@anchor{16ee}
@deffn {Μέθοδος} startTestRun ()

Called once before any tests are executed.


Added in version 3.1.

@end deffn

@geindex stopTestRun() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult stopTestRun}@anchor{16ef}
@deffn {Μέθοδος} stopTestRun ()

Called once after all tests are executed.


Added in version 3.1.

@end deffn

@geindex addError() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult addError}@anchor{1e43}
@deffn {Μέθοδος} addError (test, err)

Called when the test case `test' raises an unexpected exception. `err' is a
tuple of the form returned by @ref{a7a,,sys.exc_info()}: @code{(type, value,
traceback)}.

The default implementation appends a tuple @code{(test, formatted_err)} to
the instance’s @ref{4865,,errors} attribute, where `formatted_err' is a
formatted traceback derived from `err'.
@end deffn

@geindex addFailure() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult addFailure}@anchor{1e42}
@deffn {Μέθοδος} addFailure (test, err)

Called when the test case `test' signals a failure. `err' is a tuple of
the form returned by @ref{a7a,,sys.exc_info()}: @code{(type, value, traceback)}.

The default implementation appends a tuple @code{(test, formatted_err)} to
the instance’s @ref{4866,,failures} attribute, where `formatted_err' is a
formatted traceback derived from `err'.
@end deffn

@geindex addSuccess() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult addSuccess}@anchor{4873}
@deffn {Μέθοδος} addSuccess (test)

Called when the test case `test' succeeds.

The default implementation does nothing.
@end deffn

@geindex addSkip() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult addSkip}@anchor{1e44}
@deffn {Μέθοδος} addSkip (test, reason)

Called when the test case `test' is skipped.  `reason' is the reason the
test gave for skipping.

The default implementation appends a tuple @code{(test, reason)} to the
instance’s @ref{4867,,skipped} attribute.
@end deffn

@geindex addExpectedFailure() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult addExpectedFailure}@anchor{4874}
@deffn {Μέθοδος} addExpectedFailure (test, err)

Called when the test case `test' fails or errors, but was marked with
the @ref{483f,,expectedFailure()} decorator.

The default implementation appends a tuple @code{(test, formatted_err)} to
the instance’s @ref{4868,,expectedFailures} attribute, where `formatted_err'
is a formatted traceback derived from `err'.
@end deffn

@geindex addUnexpectedSuccess() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult addUnexpectedSuccess}@anchor{4875}
@deffn {Μέθοδος} addUnexpectedSuccess (test)

Called when the test case `test' was marked with the
@ref{483f,,expectedFailure()} decorator, but succeeded.

The default implementation appends the test to the instance’s
@ref{4869,,unexpectedSuccesses} attribute.
@end deffn

@geindex addSubTest() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult addSubTest}@anchor{1e45}
@deffn {Μέθοδος} addSubTest (test, subtest, outcome)

Called when a subtest finishes.  `test' is the test case
corresponding to the test method.  `subtest' is a custom
@ref{52f,,TestCase} instance describing the subtest.

If `outcome' is @ref{a65,,None}, the subtest succeeded.  Otherwise,
it failed with an exception where `outcome' is a tuple of the form
returned by @ref{a7a,,sys.exc_info()}: @code{(type, value, traceback)}.

The default implementation does nothing when the outcome is a
success, and records subtest failures as normal failures.


Added in version 3.4.

@end deffn

@geindex addDuration() (μέθοδος της unittest.TestResult)
@anchor{library/unittest unittest TestResult addDuration}@anchor{1cba}
@deffn {Μέθοδος} addDuration (test, elapsed)

Called when the test case finishes.  `elapsed' is the time represented in
seconds, and it includes the execution of cleanup functions.


Added in version 3.12.

@end deffn
@end deffn

@geindex TextTestResult (κλάση σε unittest)
@anchor{library/unittest unittest TextTestResult}@anchor{93f}
@deffn {Κλάση} unittest.TextTestResult (stream, descriptions, verbosity, *, durations=None)

A concrete implementation of @ref{1510,,TestResult} used by the
@ref{1cb9,,TextTestRunner}. Subclasses should accept @code{**kwargs} to ensure
compatibility as the interface changes.


Added in version 3.2.



Άλλαξε στην έκδοση 3.12: Added the `durations' keyword parameter.

@end deffn

@geindex defaultTestLoader (στη μονάδα unittest)
@anchor{library/unittest unittest defaultTestLoader}@anchor{4860}
@deffn {Δεδομένα} unittest.defaultTestLoader

Instance of the @ref{792,,TestLoader} class intended to be shared.  If no
customization of the @code{TestLoader} is needed, this instance can be used
instead of repeatedly creating new instances.
@end deffn

@geindex TextTestRunner (κλάση σε unittest)
@anchor{library/unittest unittest TextTestRunner}@anchor{1cb9}
@deffn {Κλάση} unittest.TextTestRunner (stream=None, descriptions=True, verbosity=1, failfast=False, buffer=False, resultclass=None, warnings=None, *, tb_locals=False, durations=None)

A basic test runner implementation that outputs results to a stream. If `stream'
is @code{None}, the default, @ref{d05,,sys.stderr} is used as the output stream. This class
has a few configurable parameters, but is essentially very simple.  Graphical
applications which run test suites should provide alternate implementations. Such
implementations should accept @code{**kwargs} as the interface to construct runners
changes when features are added to unittest.

By default this runner shows @ref{2c9,,DeprecationWarning},
@ref{c9b,,PendingDeprecationWarning}, @ref{74f,,ResourceWarning} and
@ref{907,,ImportWarning} even if they are @ref{4876,,ignored by default}.  This behavior can
be overridden using Python’s @code{-Wd} or @code{-Wa} options
(see @ref{2318,,Warning control}) and leaving
`warnings' to @code{None}.


Άλλαξε στην έκδοση 3.2: Added the `warnings' parameter.



Άλλαξε στην έκδοση 3.2: The default stream is set to @ref{d05,,sys.stderr} at instantiation time rather
than import time.



Άλλαξε στην έκδοση 3.5: Added the `tb_locals' parameter.



Άλλαξε στην έκδοση 3.12: Added the `durations' parameter.


@geindex _makeResult() (μέθοδος της unittest.TextTestRunner)
@anchor{library/unittest unittest TextTestRunner _makeResult}@anchor{4877}
@deffn {Μέθοδος} _makeResult ()

This method returns the instance of @code{TestResult} used by @ref{4878,,run()}.
It is not intended to be called directly, but can be overridden in
subclasses to provide a custom @code{TestResult}.

@code{_makeResult()} instantiates the class or callable passed in the
@code{TextTestRunner} constructor as the @code{resultclass} argument. It
defaults to @ref{93f,,TextTestResult} if no @code{resultclass} is provided.
The result class is instantiated with the following arguments:

@example
stream, descriptions, verbosity
@end example
@end deffn

@geindex run() (μέθοδος της unittest.TextTestRunner)
@anchor{library/unittest unittest TextTestRunner run}@anchor{4878}
@deffn {Μέθοδος} run (test)

This method is the main public interface to the @code{TextTestRunner}. This
method takes a @ref{11ad,,TestSuite} or @ref{52f,,TestCase} instance. A
@ref{1510,,TestResult} is created by calling
@ref{4877,,_makeResult()} and the test(s) are run and the
results printed to stdout.
@end deffn
@end deffn

@geindex main() (στη μονάδα unittest)
@anchor{library/unittest unittest main}@anchor{138c}
@deffn {Συνάρτηση} 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)

A command-line program that loads a set of tests from `module' and runs them;
this is primarily for making test modules conveniently executable.
The simplest use for this function is to include the following line at the
end of a test script:

@example
if __name__ == '__main__':
    unittest.main()
@end example

You can run tests with more detailed information by passing in the verbosity
argument:

@example
if __name__ == '__main__':
    unittest.main(verbosity=2)
@end example

The `defaultTest' argument is either the name of a single test or an
iterable of test names to run if no test names are specified via `argv'.  If
not specified or @code{None} and no test names are provided via `argv', all
tests found in `module' are run.

The `argv' argument can be a list of options passed to the program, with the
first element being the program name.  If not specified or @code{None},
the values of @ref{1609,,sys.argv} are used.

The `testRunner' argument can either be a test runner class or an already
created instance of it. By default @code{main} calls @ref{4ff,,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.

The `testLoader' argument has to be a @ref{792,,TestLoader} instance,
and defaults to @ref{4860,,defaultTestLoader}.

@code{main} supports being used from the interactive interpreter by passing in the
argument @code{exit=False}. This displays the result on standard output without
calling @ref{4ff,,sys.exit()}:

@example
>>> from unittest import main
>>> main(module='test_module', exit=False)
@end example

The `failfast', `catchbreak' and `buffer' parameters have the same
effect as the same-name @ref{4827,,command-line options}.

The `warnings' argument specifies the @ref{1cc,,warning filter}
that should be used while running the tests.  If it’s not specified, it will
remain @code{None} if a @code{-W} option is passed to @code{python}
(see @ref{2318,,Warning control}),
otherwise it will be set to @code{'default'}.

Calling @code{main} returns an object with the @code{result} attribute that contains
the result of the tests run as a @ref{1510,,unittest.TestResult}.


Άλλαξε στην έκδοση 3.1: The `exit' parameter was added.



Άλλαξε στην έκδοση 3.2: The `verbosity', `failfast', `catchbreak', `buffer'
and `warnings' parameters were added.



Άλλαξε στην έκδοση 3.4: The `defaultTest' parameter was changed to also accept an iterable of
test names.

@end deffn

@menu
* load_tests Protocol:: 

@end menu

@node load_tests Protocol,,,Loading and running tests
@anchor{library/unittest id1}@anchor{4838}@anchor{library/unittest load-tests-protocol}@anchor{47e0}
@subsubsection load_tests Protocol



Added in version 3.2.


Modules or packages can customize how tests are loaded from them during normal
test runs or test discovery by implementing a function called @code{load_tests}.

If a test module defines @code{load_tests} it will be called by
@ref{793,,TestLoader.loadTestsFromModule()} with the following arguments:

@example
load_tests(loader, standard_tests, pattern)
@end example

where `pattern' is passed straight through from @code{loadTestsFromModule}.  It
defaults to @code{None}.

It should return a @ref{11ad,,TestSuite}.

`loader' is the instance of @ref{792,,TestLoader} doing the loading.
`standard_tests' are the tests that would be loaded by default from the
module. It is common for test modules to only want to add or remove tests
from the standard set of tests.
The third argument is used when loading packages as part of test discovery.

A typical @code{load_tests} function that loads tests from a specific set of
@ref{52f,,TestCase} classes may look like:

@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

If discovery is started in a directory containing a package, either from the
command line or by calling @ref{138e,,TestLoader.discover()}, then the package
@code{__init__.py} will be checked for @code{load_tests}.  If that function does
not exist, discovery will recurse into the package as though it were just
another directory.  Otherwise, discovery of the package’s tests will be left up
to @code{load_tests} which is called with the following arguments:

@example
load_tests(loader, standard_tests, pattern)
@end example

This should return a @ref{11ad,,TestSuite} representing all the tests
from the package. (@code{standard_tests} will only contain tests
collected from @code{__init__.py}.)

Because the pattern is passed into @code{load_tests} the package is free to
continue (and potentially modify) test discovery. A “do nothing”
@code{load_tests} function for a test package would look like:

@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


Άλλαξε στην έκδοση 3.5: Discovery no longer checks package names for matching `pattern' due to the
impossibility of package names matching the default pattern.


@node Class and Module Fixtures,Signal Handling,Classes and functions,unittest — Unit testing framework
@anchor{library/unittest class-and-module-fixtures}@anchor{4847}
@subsubsection Class and Module Fixtures


Class and module level fixtures are implemented in @ref{11ad,,TestSuite}. When
the test suite encounters a test from a new class then
@ref{16dc,,tearDownClass()} from the previous class (if there is one)
is called, followed by @ref{e12,,setUpClass()} from the new class.

Similarly if a test is from a different module from the previous test then
@code{tearDownModule} from the previous module is run, followed by
@code{setUpModule} from the new module.

After all the tests have run the final @code{tearDownClass} and
@code{tearDownModule} are run.

Note that shared fixtures do not play well with [potential] features like test
parallelization and they break test isolation. They should be used with care.

The default ordering of tests created by the unittest test loaders is to group
all tests from the same modules and classes together. This will lead to
@code{setUpClass} / @code{setUpModule} (etc) being called exactly once per class and
module. If you randomize the order, so that tests from different modules and
classes are adjacent to each other, then these shared fixture functions may be
called multiple times in a single test run.

Shared fixtures are not intended to work with suites with non-standard
ordering. A @code{BaseTestSuite} still exists for frameworks that don’t want to
support shared fixtures.

If there are any exceptions raised during one of the shared fixture functions
the test is reported as an error. Because there is no corresponding test
instance an @code{_ErrorHolder} object (that has the same interface as a
@ref{52f,,TestCase}) is created to represent the error. If you are just using
the standard unittest test runner then this detail doesn’t matter, but if you
are a framework author it may be relevant.

@menu
* setUpClass and tearDownClass:: 
* setUpModule and tearDownModule:: 

@end menu

@node setUpClass and tearDownClass,setUpModule and tearDownModule,,Class and Module Fixtures
@anchor{library/unittest setupclass-and-teardownclass}@anchor{4879}
@subsubsection setUpClass and tearDownClass


These must be implemented as class methods:

@example
import unittest

class Test(unittest.TestCase):
    @@classmethod
    def setUpClass(cls):
        cls._connection = createExpensiveConnectionObject()

    @@classmethod
    def tearDownClass(cls):
        cls._connection.destroy()
@end example

If you want the @code{setUpClass} and @code{tearDownClass} on base classes called
then you must call up to them yourself. The implementations in
@ref{52f,,TestCase} are empty.

If an exception is raised during a @code{setUpClass} then the tests in the class
are not run and the @code{tearDownClass} is not run. Skipped classes will not
have @code{setUpClass} or @code{tearDownClass} run. If the exception is a
@ref{138d,,SkipTest} exception then the class will be reported as having been skipped
instead of as an error.

@node setUpModule and tearDownModule,,setUpClass and tearDownClass,Class and Module Fixtures
@anchor{library/unittest setupmodule-and-teardownmodule}@anchor{487a}
@subsubsection setUpModule and tearDownModule


@geindex setUpModule() (στη μονάδα unittest)
@geindex tearDownModule() (στη μονάδα unittest)
@anchor{library/unittest unittest setUpModule}@anchor{e11}
These should be implemented as functions:

@example
def setUpModule():
    createConnection()

def tearDownModule():
    closeConnection()
@end example

If an exception is raised in a @code{setUpModule} then none of the tests in the
module will be run and the @code{tearDownModule} will not be run. If the exception is a
@ref{138d,,SkipTest} exception then the module will be reported as having been skipped
instead of as an error.

To add cleanup code that must be run even in the case of an exception, use
@code{addModuleCleanup}:

@geindex addModuleCleanup() (στη μονάδα unittest)
@anchor{library/unittest unittest addModuleCleanup}@anchor{e0f}
@deffn {Συνάρτηση} unittest.addModuleCleanup (function, /, *args, **kwargs)

Add a function to be called after @ref{16db,,tearDownModule()} to cleanup
resources used during the test class. Functions will be called in reverse
order to the order they are added (@abbr{LIFO}).
They are called with any arguments and keyword arguments passed into
@ref{e0f,,addModuleCleanup()} when they are added.

If @ref{e11,,setUpModule()} fails, meaning that @ref{16db,,tearDownModule()} is not
called, then any cleanup functions added will still be called.


Added in version 3.8.

@end deffn

@geindex enterModuleContext() (στη μονάδα unittest)
@anchor{library/unittest unittest enterModuleContext}@anchor{aa9}
@deffn {Συνάρτηση} unittest.enterModuleContext (cm)

Enter the supplied @ref{478,,context manager}.  If successful, also
add its @ref{16a5,,__exit__()} method as a cleanup function by
@ref{e0f,,addModuleCleanup()} and return the result of the
@ref{9c6,,__enter__()} method.


Added in version 3.11.

@end deffn

@geindex doModuleCleanups() (στη μονάδα unittest)
@anchor{library/unittest unittest doModuleCleanups}@anchor{1a31}
@deffn {Συνάρτηση} unittest.doModuleCleanups ()

This function is called unconditionally after @ref{16db,,tearDownModule()}, or
after @ref{e11,,setUpModule()} if @code{setUpModule()} raises an exception.

It is responsible for calling all the cleanup functions added by
@ref{e0f,,addModuleCleanup()}. If you need cleanup functions to be called
`prior' to @ref{16db,,tearDownModule()} then you can call
@code{doModuleCleanups()} yourself.

@code{doModuleCleanups()} pops methods off the stack of cleanup
functions one at a time, so it can be called at any time.


Added in version 3.8.

@end deffn

@node Signal Handling,,Class and Module Fixtures,unittest — Unit testing framework
@anchor{library/unittest signal-handling}@anchor{482a}
@subsubsection Signal Handling



Added in version 3.2.


The @ref{16d7,,-c/--catch} command-line option to unittest,
along with the @code{catchbreak} parameter to @ref{138c,,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{d96,,KeyboardInterrupt} in the usual way.

The control-c handling signal handler attempts to remain compatible with code or
tests that install their own @ref{4df,,signal.SIGINT} handler. If the @code{unittest}
handler is called but `isn’t' the installed @code{signal.SIGINT} handler,
i.e. it has been replaced by the system under test and delegated to, then it
calls the default handler. This will normally be the expected behavior by code
that replaces an installed handler and delegates to it. For individual tests
that need @code{unittest} control-c handling disabled the @ref{16d8,,removeHandler()}
decorator can be used.

There are a few utility functions for framework authors to enable control-c
handling functionality within test frameworks.

@geindex installHandler() (στη μονάδα unittest)
@anchor{library/unittest unittest installHandler}@anchor{487b}
@deffn {Συνάρτηση} unittest.installHandler ()

Install the control-c handler. When a @ref{4df,,signal.SIGINT} is received
(usually in response to the user pressing control-c) all registered results
have @ref{486b,,stop()} called.
@end deffn

@geindex registerResult() (στη μονάδα unittest)
@anchor{library/unittest unittest registerResult}@anchor{487c}
@deffn {Συνάρτηση} unittest.registerResult (result)

Register a @ref{1510,,TestResult} object for control-c handling. Registering a
result stores a weak reference to it, so it doesn’t prevent the result from
being garbage collected.

Registering a @ref{1510,,TestResult} object has no side-effects if control-c
handling is not enabled, so test frameworks can unconditionally register
all results they create independently of whether or not handling is enabled.
@end deffn

@geindex removeResult() (στη μονάδα unittest)
@anchor{library/unittest unittest removeResult}@anchor{487d}
@deffn {Συνάρτηση} unittest.removeResult (result)

Remove a registered result. Once a result has been removed then
@ref{486b,,stop()} will no longer be called on that result object in
response to a control-c.
@end deffn

@geindex removeHandler() (στη μονάδα unittest)
@anchor{library/unittest unittest removeHandler}@anchor{16d8}
@deffn {Συνάρτηση} unittest.removeHandler (function=None)

When called without arguments this function removes the control-c handler
if it has been installed. This function can also be used as a test decorator
to temporarily remove the handler while the test is being executed:

@example
@@unittest.removeHandler
def test_signal_handling(self):
    ...
@end example
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node unittest mock — mock object library,unittest mock — ξεκινώντας,unittest — Unit testing framework,Εργαλεία Ανάπτυξης
@anchor{library/unittest mock doc}@anchor{487e}@anchor{library/unittest mock module-unittest mock}@anchor{110}@anchor{library/unittest mock translation-repo}@anchor{487f}@anchor{library/unittest mock unittest-mock-mock-object-library}@anchor{4880}
@subsection @code{unittest.mock} — mock object library


@geindex module; unittest.mock


Added in version 3.3.


`Source code:' Lib/unittest/mock.py@footnote{https://github.com/python/cpython/tree/main/Lib/unittest/mock.py}


__________________________________________________________________


@code{unittest.mock} is a library for testing in Python. It allows you to
replace parts of your system under test with mock objects and make assertions
about how they have been used.

@code{unittest.mock} provides a core @ref{e0e,,Mock} class removing the need to
create a host of stubs throughout your test suite. After performing an
action, you can make assertions about which methods / attributes were used
and arguments they were called with. You can also specify return values and
set needed attributes in the normal way.

Additionally, mock provides a @ref{1243,,patch()} decorator that handles patching
module and class level attributes within the scope of a test, along with
@ref{18b,,sentinel} for creating unique objects. See the @ref{4881,,quick guide} for
some examples of how to use @ref{e0e,,Mock}, @ref{1240,,MagicMock} and
@code{patch()}.

Mock is designed for use with @ref{10f,,unittest} and
is based on the “action -> assertion” pattern instead of “record -> replay”
used by many mocking frameworks.

There is a backport of @code{unittest.mock} for earlier versions of Python,
available as mock@footnote{https://pypi.org/project/mock/} on PyPI.

@menu
* Quick Guide:: 
* The Mock Class:: 
* 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 Quick Guide,The Mock Class,,unittest mock — mock object library
@anchor{library/unittest mock quick-guide}@anchor{4881}
@subsubsection Quick Guide


@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

@ref{e0e,,Mock} and @ref{1240,,MagicMock} objects create all attributes and
methods as you access them and store details of how they have been used. You
can configure them, to specify return values or limit what attributes are
available, and then make assertions about how they have been used:

@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{4882,,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

Mock has many other ways you can configure it and control its behaviour. For
example the `spec' argument configures the mock to take its specification
from another object. Attempting to access attributes or methods on the mock
that don’t exist on the spec will fail with an @ref{1a9,,AttributeError}.

The @ref{1243,,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 Σημείωση 
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{module.ClassName1} is passed in first.

With @ref{1243,,patch()} it matters that you patch objects in the namespace where they
are looked up. This is normally straightforward, but for a quick guide
read @ref{4883,,where to patch}.
@end quotation
@end cartouche

As well as a decorator @ref{1243,,patch()} can be used as a context manager in a with
statement:

@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

There is also @ref{1b7a,,patch.dict()} for setting values in a dictionary just
during a scope and restoring the dictionary to its original state when the test
ends:

@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 supports the mocking of Python @ref{4884,,magic methods}. The
easiest way of using magic methods is with the @ref{1240,,MagicMock} class. It
allows you to do things like:

@example
>>> mock = MagicMock()
>>> mock.__str__.return_value = 'foobarbaz'
>>> str(mock)
'foobarbaz'
>>> mock.__str__.assert_called_with()
@end example

Mock allows you to assign functions (or other Mock instances) to magic methods
and they will be called appropriately. The @ref{1240,,MagicMock} class is just a Mock
variant that has all of the magic methods pre-created for you (well, all the
useful ones anyway).

The following is an example of using magic methods with the ordinary Mock
class:

@example
>>> mock = Mock()
>>> mock.__str__ = Mock(return_value='wheeeeee')
>>> str(mock)
'wheeeeee'
@end example

For ensuring that the mock objects in your tests have the same api as the
objects they are replacing, you can use @ref{4885,,auto-speccing}.
Auto-speccing can be done through the `autospec' argument to patch, or the
@ref{1b4e,,create_autospec()} function. Auto-speccing creates mock objects that
have the same attributes and methods as the objects they are replacing, and
any functions and methods (including constructors) have the same call
signature as the real object.

This ensures that your mocks will fail in the same way as your production
code if they are used incorrectly:

@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

@ref{1b4e,,create_autospec()} can also be used on classes, where it copies the signature of
the @code{__init__} method, and on callable objects where it copies the signature of
the @code{__call__} method.

@node The Mock Class,The patchers,Quick Guide,unittest mock — mock object library
@anchor{library/unittest mock the-mock-class}@anchor{4886}
@subsubsection The Mock Class


@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

@ref{e0e,,Mock} is a flexible mock object intended to replace the use of stubs and
test doubles throughout your code. Mocks are callable and create attributes as
new mocks when you access them @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{1a9,,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{4884,,magic methods}.
}. Accessing the same attribute will always
return the same mock. Mocks record how you use them, allowing you to make
assertions about what your code has done to them.

@ref{1240,,MagicMock} is a subclass of @ref{e0e,,Mock} with all the magic methods
pre-created and ready to use. There are also non-callable variants, useful
when you are mocking out objects that aren’t callable:
@ref{4887,,NonCallableMock} and @ref{4888,,NonCallableMagicMock}

The @ref{1243,,patch()} decorators makes it easy to temporarily replace classes
in a particular module with a @ref{e0e,,Mock} object. By default @code{patch()} will create
a @ref{1240,,MagicMock} for you. You can specify an alternative class of @code{Mock} using
the `new_callable' argument to @code{patch()}.

@geindex Mock (κλάση σε unittest.mock)
@anchor{library/unittest mock unittest mock Mock}@anchor{e0e}
@deffn {Κλάση} unittest.mock.Mock (spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)

Create a new @code{Mock} object. @code{Mock} takes several optional arguments
that specify the behaviour of the Mock object:


@itemize *

@item 
`spec': This can be either a list of strings or an existing object (a
class or instance) that acts as the specification for the mock object. If
you pass in an object then a list of strings is formed by calling dir on
the object (excluding unsupported magic attributes and methods).
Accessing any attribute not in this list will raise an @ref{1a9,,AttributeError}.

If `spec' is an object (rather than a list of strings) then
@ref{184f,,__class__} returns the class of the spec object. This
allows mocks to pass @ref{2ef,,isinstance()} tests.

@item 
`spec_set': A stricter variant of `spec'. If used, attempting to `set'
or get an attribute on the mock that isn’t on the object passed as
`spec_set' will raise an @ref{1a9,,AttributeError}.

@item 
`side_effect': A function to be called whenever the Mock is called. See
the @ref{4882,,side_effect} attribute. Useful for raising exceptions or
dynamically changing return values. The function is called with the same
arguments as the mock, and unless it returns @ref{4889,,DEFAULT}, the return
value of this function is used as the return value.

Alternatively `side_effect' can be an exception class or instance. In
this case the exception will be raised when the mock is called.

If `side_effect' is an iterable then each call to the mock will return
the next value from the iterable.

A `side_effect' can be cleared by setting it to @code{None}.

@item 
`return_value': The value returned when the mock is called. By default
this is a new Mock (created on first access). See the
@ref{488a,,return_value} attribute.

@item 
`unsafe': By default, accessing any attribute whose name starts with
`assert', `assret', `asert', `aseert' or `assrt' will raise an
@ref{1a9,,AttributeError}. Passing @code{unsafe=True} will allow access to
these attributes.


Added in version 3.5.


@item 
`wraps': Item for the mock object to wrap. If `wraps' is not @code{None} then
calling the Mock will pass the call through to the wrapped object
(returning the real result). Attribute access on the mock will return a
Mock object that wraps the corresponding attribute of the wrapped
object (so attempting to access an attribute that doesn’t exist will
raise an @ref{1a9,,AttributeError}).

If the mock has an explicit `return_value' set then calls are not passed
to the wrapped object and the `return_value' is returned instead.

@item 
`name': If the mock has a name then it will be used in the repr of the
mock. This can be useful for debugging. The name is propagated to child
mocks.
@end itemize

Mocks can also be called with arbitrary keyword arguments. These will be
used to set attributes on the mock after it is created. See the
@ref{488b,,configure_mock()} method for details.

@geindex assert_called() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_called}@anchor{10b4}
@deffn {Μέθοδος} assert_called ()

Assert that the mock was called at least once.

@example
>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called()
@end example


Added in version 3.6.

@end deffn

@geindex assert_called_once() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_called_once}@anchor{10b5}
@deffn {Μέθοδος} assert_called_once ()

Assert that the mock was called exactly once.

@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


Added in version 3.6.

@end deffn

@geindex assert_called_with() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_called_with}@anchor{1ff2}
@deffn {Μέθοδος} 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() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_called_once_with}@anchor{488c}
@deffn {Μέθοδος} 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() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_any_call}@anchor{488d}
@deffn {Μέθοδος} assert_any_call (*args, **kwargs)

assert the mock has been called with the specified arguments.

The assert passes if the mock has `ever' been called, unlike
@ref{1ff2,,assert_called_with()} and @ref{488c,,assert_called_once_with()} that
only pass if the call is the most recent one, and in the case of
@code{assert_called_once_with()} it must also be the only call.

@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() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_has_calls}@anchor{1c2a}
@deffn {Μέθοδος} assert_has_calls (calls, any_order=False)

assert the mock has been called with the specified calls.
The @ref{488e,,mock_calls} list is checked for the calls.

If `any_order' is false then the calls must be
sequential. There can be extra calls before or after the
specified calls.

If `any_order' is true then the calls can be in any order, but
they must all appear in @ref{488e,,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() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_not_called}@anchor{123f}
@deffn {Μέθοδος} assert_not_called ()

Assert the mock was never called.

@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


Added in version 3.5.

@end deffn

@geindex reset_mock() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock reset_mock}@anchor{10b6}
@deffn {Μέθοδος} reset_mock (*, return_value=False, side_effect=False)

The reset_mock method resets all the call attributes on a mock object:

@example
>>> mock = Mock(return_value=None)
>>> mock('hello')
>>> mock.called
True
>>> mock.reset_mock()
>>> mock.called
False
@end example

This can be useful where you want to make a series of assertions that
reuse the same object.

`return_value' parameter when set to @code{True} resets @ref{488a,,return_value}:

@example
>>> mock = Mock(return_value=5)
>>> mock('hello')
5
>>> mock.reset_mock(return_value=True)
>>> mock('hello')
<Mock name='mock()' id='...'>
@end example

`side_effect' parameter when set to @code{True} resets @ref{4882,,side_effect}:

@example
>>> mock = Mock(side_effect=ValueError)
>>> mock('hello')
Traceback (most recent call last):
  ...
ValueError
>>> mock.reset_mock(side_effect=True)
>>> mock('hello')
<Mock name='mock()' id='...'>
@end example

Note that @code{reset_mock()} `doesn’t' clear the
@ref{488a,,return_value}, @ref{4882,,side_effect} or any child attributes you have
set using normal assignment by default.

Child mocks are reset as well.


Άλλαξε στην έκδοση 3.6: Added two keyword-only arguments to the reset_mock function.

@end deffn

@geindex mock_add_spec() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock mock_add_spec}@anchor{488f}
@deffn {Μέθοδος} mock_add_spec (spec, spec_set=False)

Add a spec to a mock. `spec' can either be an object or a
list of strings. Only attributes on the `spec' can be fetched as
attributes from the mock.

If `spec_set' is true then only attributes on the spec can be set.
@end deffn

@geindex attach_mock() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock attach_mock}@anchor{1b69}
@deffn {Μέθοδος} attach_mock (mock, attribute)

Attach a mock as an attribute of this one, replacing its name and
parent. Calls to the attached mock will be recorded in the
@ref{4890,,method_calls} and @ref{488e,,mock_calls} attributes of this one.
@end deffn

@geindex configure_mock() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock configure_mock}@anchor{488b}
@deffn {Μέθοδος} configure_mock (**kwargs)

Set attributes on the mock through keyword arguments.

Attributes plus return values and side effects can be set on child
mocks using standard dot notation and unpacking a dictionary in the
method call:

@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

The same thing can be achieved in the constructor call to mocks:

@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

@code{configure_mock()} exists to make it easier to do configuration
after the mock has been created.
@end deffn

@geindex __dir__() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock __dir__}@anchor{4891}
@deffn {Μέθοδος} __dir__ ()

@code{Mock} objects limit the results of @code{dir(some_mock)} to useful results.
For mocks with a `spec' this includes all the permitted attributes
for the mock.

See @ref{4892,,FILTER_DIR} for what this filtering does, and how to
switch it off.
@end deffn

@geindex _get_child_mock() (μέθοδος της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock _get_child_mock}@anchor{4893}
@deffn {Μέθοδος} _get_child_mock (**kw)

Create the child mocks for attributes and return value.
By default child mocks will be the same type as the parent.
Subclasses of Mock may want to override this to customize the way
child mocks are made.

For non-callable mocks the callable variant will be used (rather than
any custom subclass).
@end deffn

@geindex called (ιδιότητα της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock called}@anchor{4894}
@deffn {Ιδιότητα} called

A boolean representing whether or not the mock object has been called:

@example
>>> mock = Mock(return_value=None)
>>> mock.called
False
>>> mock()
>>> mock.called
True
@end example
@end deffn

@geindex call_count (ιδιότητα της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock call_count}@anchor{19a6}
@deffn {Ιδιότητα} call_count

An integer telling you how many times the mock object has been called:

@example
>>> mock = Mock(return_value=None)
>>> mock.call_count
0
>>> mock()
>>> mock()
>>> mock.call_count
2
@end example
@end deffn

@geindex return_value (ιδιότητα της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock return_value}@anchor{488a}
@deffn {Ιδιότητα} return_value

Set this to configure the value returned by calling the mock:

@example
>>> mock = Mock()
>>> mock.return_value = 'fish'
>>> mock()
'fish'
@end example

The default return value is a mock object and you can configure it in
the normal way:

@example
>>> mock = Mock()
>>> mock.return_value.attribute = sentinel.Attribute
>>> mock.return_value()
<Mock name='mock()()' id='...'>
>>> mock.return_value.assert_called_with()
@end example

@ref{488a,,return_value} can also be set in the constructor:

@example
>>> mock = Mock(return_value=3)
>>> mock.return_value
3
>>> mock()
3
@end example
@end deffn

@geindex side_effect (ιδιότητα της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock side_effect}@anchor{4882}
@deffn {Ιδιότητα} side_effect

This can either be a function to be called when the mock is called,
an iterable or an exception (class or instance) to be raised.

If you pass in a function it will be called with same arguments as the
mock and unless the function returns the @ref{4889,,DEFAULT} singleton the
call to the mock will then return whatever the function returns. If the
function returns @code{DEFAULT} then the mock will return its normal
value (from the @ref{488a,,return_value}).

If you pass in an iterable, it is used to retrieve an iterator which
must yield a value on every call.  This value can either be an exception
instance to be raised, or a value to be returned from the call to the
mock (@ref{4889,,DEFAULT} handling is identical to the function case).

An example of a mock that raises an exception (to test exception
handling of an API):

@example
>>> mock = Mock()
>>> mock.side_effect = Exception('Boom!')
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!
@end example

Using @ref{4882,,side_effect} to return a sequence of values:

@example
>>> mock = Mock()
>>> mock.side_effect = [3, 2, 1]
>>> mock(), mock(), mock()
(3, 2, 1)
@end example

Using a callable:

@example
>>> mock = Mock(return_value=3)
>>> def side_effect(*args, **kwargs):
...     return DEFAULT
...
>>> mock.side_effect = side_effect
>>> mock()
3
@end example

@ref{4882,,side_effect} can be set in the constructor. Here’s an example that
adds one to the value the mock is called with and returns it:

@example
>>> side_effect = lambda value: value + 1
>>> mock = Mock(side_effect=side_effect)
>>> mock(3)
4
>>> mock(-8)
-7
@end example

Setting @ref{4882,,side_effect} to @code{None} clears it:

@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 (ιδιότητα της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock call_args}@anchor{1f5d}
@deffn {Ιδιότητα} 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 positional 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

@ref{1f5d,,call_args}, along with members of the lists @ref{4895,,call_args_list},
@ref{4890,,method_calls} and @ref{488e,,mock_calls} are @ref{1fa3,,call} objects.
These are tuples, so they can be unpacked to get at the individual
arguments and make more complex assertions. See
@ref{4896,,calls as tuples}.


Άλλαξε στην έκδοση 3.8: Added @code{args} and @code{kwargs} properties.

@end deffn

@geindex call_args_list (ιδιότητα της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock call_args_list}@anchor{4895}
@deffn {Ιδιότητα} 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{1fa3,,call} object can be used for conveniently constructing lists of
calls to compare with @ref{4895,,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{4895,,call_args_list} are @ref{1fa3,,call} objects. These can be
unpacked as tuples to get at the individual arguments. See
@ref{4896,,calls as tuples}.
@end deffn

@geindex method_calls (ιδιότητα της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock method_calls}@anchor{4890}
@deffn {Ιδιότητα} 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{4890,,method_calls} are @ref{1fa3,,call} objects. These can be
unpacked as tuples to get at the individual arguments. See
@ref{4896,,calls as tuples}.
@end deffn

@geindex mock_calls (ιδιότητα της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock mock_calls}@anchor{488e}
@deffn {Ιδιότητα} mock_calls

@ref{488e,,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{488e,,mock_calls} are @ref{1fa3,,call} objects. These can be
unpacked as tuples to get at the individual arguments. See
@ref{4896,,calls as tuples}.

@cartouche
@quotation Σημείωση 
The way @ref{488e,,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__ (ιδιότητα της unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock __class__}@anchor{4897}
@deffn {Ιδιότητα} __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{2ef,,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{2ef,,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 (κλάση σε unittest.mock)
@anchor{library/unittest mock unittest mock NonCallableMock}@anchor{4887}
@deffn {Κλάση} unittest.mock.NonCallableMock (spec=None, wraps=None, name=None, spec_set=None, **kwargs)

A non-callable version of @ref{e0e,,Mock}. The constructor parameters have the same
meaning of @code{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{2ef,,isinstance()} tests:

@example
>>> mock = Mock(spec=SomeClass)
>>> isinstance(mock, SomeClass)
True
>>> mock = Mock(spec_set=SomeClass())
>>> isinstance(mock, SomeClass)
True
@end example

The @ref{e0e,,Mock} classes have support for mocking magic methods. See @ref{4884,,magic methods} for the full details.

The mock classes and the @ref{1243,,patch()} decorators all take arbitrary keyword
arguments for configuration. For the @code{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{1ff2,,assert_called_with()},
@ref{488c,,assert_called_once_with()}, @ref{1c2a,,assert_has_calls()} and
@ref{488d,,assert_any_call()}.  When @ref{4885,,Autospeccing}, it will also
apply to method calls on the mock object.


Άλλαξε στην έκδοση 3.4: Added signature introspection on specced and autospecced mock objects.


@geindex PropertyMock (κλάση σε unittest.mock)
@anchor{library/unittest mock unittest mock PropertyMock}@anchor{4898}
@deffn {Κλάση} unittest.mock.PropertyMock (*args, **kwargs)

A mock intended to be used as a @ref{6bb,,property}, or other
@ref{21f,,descriptor}, on a class. @code{PropertyMock} provides
@ref{188a,,__get__()} and @ref{25aa,,__set__()} methods
so you can specify a return value when it is fetched.

Fetching a @code{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{4898,,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 Προσοχή 
If an @ref{1a9,,AttributeError} is raised by @ref{4898,,PropertyMock},
it will be interpreted as a missing descriptor and
@ref{8e3,,__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{8e3,,__getattr__()} for details.
@end quotation
@end cartouche

@geindex AsyncMock (κλάση σε unittest.mock)
@anchor{library/unittest mock unittest mock AsyncMock}@anchor{e0d}
@deffn {Κλάση} 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{1240,,MagicMock}. The @code{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()
>>> inspect.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 @code{AsyncMock} object.
@end itemize

Setting the `spec' of a @ref{e0e,,Mock} or @ref{1240,,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{e0e,,Mock}, @ref{1240,,MagicMock}, or @code{AsyncMock}
to a class with asynchronous and synchronous functions will automatically
detect the synchronous functions and set them as @code{MagicMock} (if the
parent mock is @code{AsyncMock} or @code{MagicMock}) or @code{Mock} (if
the parent mock is @code{Mock}). All asynchronous functions will be
@code{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


Added in version 3.8.


@geindex assert_awaited() (μέθοδος της unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_awaited}@anchor{4899}
@deffn {Μέθοδος} 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() (μέθοδος της unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_awaited_once}@anchor{489a}
@deffn {Μέθοδος} 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() (μέθοδος της unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_awaited_with}@anchor{489b}
@deffn {Μέθοδος} 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() (μέθοδος της unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_awaited_once_with}@anchor{489c}
@deffn {Μέθοδος} 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() (μέθοδος της unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_any_await}@anchor{489d}
@deffn {Μέθοδος} 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() (μέθοδος της unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_has_awaits}@anchor{489e}
@deffn {Μέθοδος} assert_has_awaits (calls, any_order=False)

Assert the mock has been awaited with the specified calls.
The @ref{1f5c,,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{1f5c,,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() (μέθοδος της unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_not_awaited}@anchor{489f}
@deffn {Μέθοδος} assert_not_awaited ()

Assert that the mock was never awaited.

@example
>>> mock = AsyncMock()
>>> mock.assert_not_awaited()
@end example
@end deffn

@geindex reset_mock() (μέθοδος της unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock reset_mock}@anchor{48a0}
@deffn {Μέθοδος} reset_mock (*args, **kwargs)

See @ref{10b6,,Mock.reset_mock()}. Also sets @ref{48a1,,await_count} to 0,
@ref{48a2,,await_args} to None, and clears the @ref{1f5c,,await_args_list}.
@end deffn

@geindex await_count (ιδιότητα της unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock await_count}@anchor{48a1}
@deffn {Ιδιότητα} 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 (ιδιότητα της unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock await_args}@anchor{48a2}
@deffn {Ιδιότητα} 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{1f5d,,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 (ιδιότητα της unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock await_args_list}@anchor{1f5c}
@deffn {Ιδιότητα} 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 (κλάση σε unittest.mock)
@anchor{library/unittest mock unittest mock ThreadingMock}@anchor{48a3}
@deffn {Κλάση} 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{1240,,MagicMock} for multithreading tests. The
@code{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{48a4,,ThreadingMock.DEFAULT_TIMEOUT} attribute, which defaults to blocking (@code{None}).

You can configure the global default timeout by setting @ref{48a4,,ThreadingMock.DEFAULT_TIMEOUT}.

@geindex wait_until_called() (μέθοδος της unittest.mock.ThreadingMock)
@anchor{library/unittest mock unittest mock ThreadingMock wait_until_called}@anchor{48a5}
@deffn {Μέθοδος} 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{a97,,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() (μέθοδος της unittest.mock.ThreadingMock)
@anchor{library/unittest mock unittest mock ThreadingMock wait_until_any_call_with}@anchor{48a6}
@deffn {Μέθοδος} 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{a97,,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 (ιδιότητα της unittest.mock.ThreadingMock)
@anchor{library/unittest mock unittest mock ThreadingMock DEFAULT_TIMEOUT}@anchor{48a4}
@deffn {Ιδιότητα} DEFAULT_TIMEOUT

Global default timeout in seconds to create instances of @code{ThreadingMock}.
@end deffn


Added in 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,,The Mock Class
@anchor{library/unittest mock calling}@anchor{48a7}
@subsubsection Calling


Mock objects are callable. The call will return the value set as the
@ref{488a,,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{1f5d,,call_args} and @ref{4895,,call_args_list}.

If @ref{4882,,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{4882,,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{4882,,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{488a,,return_value} from inside @ref{4882,,side_effect}, or return @ref{4889,,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{4882,,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{4882,,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{fba,,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,The Mock Class
@anchor{library/unittest mock deleting-attributes}@anchor{48a8}@anchor{library/unittest mock id2}@anchor{48a9}
@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{8e2,,hasattr()} call, or raise an
@ref{1a9,,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{1a9,,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,The Mock Class
@anchor{library/unittest mock mock-names-and-the-name-attribute}@anchor{48aa}
@subsubsection Mock names and the name attribute


Since «name» is an argument to the @ref{e0e,,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{488b,,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,The Mock Class
@anchor{library/unittest mock attaching-mocks-as-attributes}@anchor{48ab}
@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{4890,,method_calls} and @ref{488e,,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{1243,,patch()} are automatically given names. To
attach mocks that have names to a parent you use the @ref{1b69,,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,The Mock Class,unittest mock — mock object library
@anchor{library/unittest mock the-patchers}@anchor{48ac}
@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{48ad}
@subsubsection patch


@cartouche
@quotation Σημείωση 
The key is to do the patching in the right namespace. See the section @ref{48ae,,where to patch}.
@end quotation
@end cartouche

@geindex patch() (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock patch}@anchor{1243}
@deffn {Συνάρτηση} unittest.mock.patch (target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

@code{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{e0d,,AsyncMock} if the patched object is an async function or
a @ref{1240,,MagicMock} otherwise.
If @code{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 @code{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 @code{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{1240,,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{e0d,,AsyncMock}
is used for async functions and @ref{1240,,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{291,,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{1b4e,,create_autospec()} function and
@ref{4885,,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 @code{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 Σημείωση 

Άλλαξε στην έκδοση 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{52f,,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. @code{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{10f,,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 @code{patch()} is creating a mock object for you.

@code{patch()} takes arbitrary keyword arguments. These will be passed to
@ref{e0d,,AsyncMock} if the patched object is asynchronous, to
@ref{1240,,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{1243,,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{1240,,MagicMock} `instance'. If the
class is instantiated in the code under test then it will be the
@ref{488a,,return_value} of the mock that will be used.

If the class is instantiated multiple times you could use
@ref{4882,,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{488a,,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{1243,,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{1240,,MagicMock} for the created mock. For example, if
you wanted a @ref{4887,,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{12d4,,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{1243,,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{488a,,return_value} and @ref{4882,,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{1243,,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{1a9,,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{1243,,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


Άλλαξε στην έκδοση 3.8: @ref{1243,,patch()} now returns an @ref{e0d,,AsyncMock} if the target is an async function.


@node patch object,patch dict,patch,The patchers
@anchor{library/unittest mock patch-object}@anchor{48af}
@subsubsection patch.object


@geindex patch.object() (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock patch object}@anchor{1b25}
@deffn {Συνάρτηση} 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.

@code{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{1243,,patch()}. Like @code{patch()},
@code{patch.object()} takes arbitrary keyword arguments for configuring the mock
object it creates.

When used as a class decorator @code{patch.object()} honours @code{patch.TEST_PREFIX}
for choosing which methods to wrap.
@end deffn

You can either call @ref{1b25,,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{1b25,,patch.object()} have the same
meaning as they do for @ref{1243,,patch()}.

@node patch dict,patch multiple,patch object,The patchers
@anchor{library/unittest mock patch-dict}@anchor{48b0}
@subsubsection patch.dict


@geindex patch.dict() (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock patch dict}@anchor{1b7a}
@deffn {Συνάρτηση} 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, where the restored dictionary is a
copy of the dictionary as it was before 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.

@code{patch.dict()} can also be called with arbitrary keyword arguments to set
values in the dictionary.


Άλλαξε στην έκδοση 3.8: @code{patch.dict()} now returns the patched dictionary when used as a context
manager.

@end deffn

@ref{1b7a,,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{1b7a,,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{48b1,,TEST_PREFIX}.

@ref{1b7a,,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{1b7a,,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{1b7a,,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{787,,__getitem__()}, @ref{1670,,__setitem__()},
@ref{1671,,__delitem__()} and either @ref{229a,,__iter__()} or
@ref{175c,,__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{48b2}
@subsubsection patch.multiple


@geindex patch.multiple() (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock patch multiple}@anchor{48b3}
@deffn {Συνάρτηση} 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{4889,,DEFAULT} as the value if you want @code{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 @code{patch.multiple()} is
used as a context manager.

@code{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{1243,,patch()}. These arguments will
be applied to `all' patches done by @code{patch.multiple()}.

When used as a class decorator @code{patch.multiple()} honours @code{patch.TEST_PREFIX}
for choosing which methods to wrap.
@end deffn

If you want @ref{48b3,,patch.multiple()} to create mocks for you, then you can use
@ref{4889,,DEFAULT} as the value. If you use @code{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{48b3,,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{1243,,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{48b3,,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{48b4}@anchor{library/unittest mock start-and-stop}@anchor{48b5}
@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{1243,,patch()}, @ref{1b25,,patch.object()} or @ref{1b7a,,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{1243,,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{52f,,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 Προσοχή 
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{e43,,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{48b6,,patch.stopall()}.

@geindex patch.stopall() (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock patch stopall}@anchor{48b6}
@deffn {Συνάρτηση} 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{48b7}@anchor{library/unittest mock patch-builtins}@anchor{48b8}
@subsubsection patch builtins


You can patch any builtins within a module. The following example patches
builtin @ref{252c,,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{48b9}@anchor{library/unittest mock test-prefix}@anchor{48b1}
@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{792,,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{48ba}
@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{48ae}@anchor{library/unittest mock where-to-patch}@anchor{4883}
@subsubsection Where to patch


@ref{1243,,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{1243,,patch()}. The problem is that when we import module b, which we will have to
do when it imports @code{SomeClass} from module a. If we use @code{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{48bb}
@subsubsection Patching Descriptors and Proxy Objects


Both @ref{48ad,,patch} and @ref{48af,,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{48bc}
@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{4884}@anchor{library/unittest mock mocking-magic-methods}@anchor{48bd}
@subsubsection Mocking Magic Methods


@ref{e0e,,Mock} supports mocking the Python protocol methods, also known as
@ref{48be,,«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{20a,,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{4890,,method_calls}, but they
are recorded in @ref{488e,,mock_calls}.

@cartouche
@quotation Σημείωση 
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{1a9,,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__} and @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


Άλλαξε στην έκδοση 3.8: Added support for @ref{1010,,os.PathLike.__fspath__()}.



Άλλαξε στην έκδοση 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{48bf}
@subsubsection Magic Mock


There are two @code{MagicMock} variants: @ref{1240,,MagicMock} and @ref{4888,,NonCallableMagicMock}.

@geindex MagicMock (κλάση σε unittest.mock)
@anchor{library/unittest mock unittest mock MagicMock}@anchor{1240}
@deffn {Κλάση} unittest.mock.MagicMock (*args, **kw)

@code{MagicMock} is a subclass of @ref{e0e,,Mock} with default implementations
of most of the @ref{48be,,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{e0e,,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 (κλάση σε unittest.mock)
@anchor{library/unittest mock unittest mock NonCallableMagicMock}@anchor{4888}
@deffn {Κλάση} unittest.mock.NonCallableMagicMock (*args, **kw)

A non-callable version of @ref{1240,,MagicMock}.

The constructor parameters have the same meaning as for
@ref{1240,,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{1240,,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{440,,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{__len__}: @code{0}

@item 
@code{__iter__}: @code{iter([])}

@item 
@code{__exit__}: @code{False}

@item 
@code{__aexit__}: @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

For example:

@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{4882,,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__} and @code{__delete__}

@item 
@code{__reversed__} and @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{48c0}
@subsubsection Helpers


@menu
* sentinel:: 
* DEFAULT:: 
* call:: 
* create_autospec:: 
* ANY:: 
* FILTER_DIR:: 
* mock_open:: 
* Autospeccing:: 
* Sealing mocks:: 

@end menu

@node sentinel,DEFAULT,,Helpers
@anchor{library/unittest mock sentinel}@anchor{48c1}
@subsubsection sentinel


@geindex sentinel (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock sentinel}@anchor{f5f}
@deffn {Δεδομένα} 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.


Άλλαξε στην έκδοση 3.7: The @code{sentinel} attributes now preserve their identity when they are
@ref{29,,copied} or @ref{ab,,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{18b,,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,call,sentinel,Helpers
@anchor{library/unittest mock default}@anchor{48c2}
@subsubsection DEFAULT


@geindex DEFAULT (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock DEFAULT}@anchor{4889}
@deffn {Δεδομένα} unittest.mock.DEFAULT

The @code{DEFAULT} object is a pre-created sentinel (actually
@code{sentinel.DEFAULT}). It can be used by @ref{4882,,side_effect}
functions to indicate that the normal return value should be used.
@end deffn

@node call,create_autospec,DEFAULT,Helpers
@anchor{library/unittest mock call}@anchor{48c3}
@subsubsection call


@geindex call() (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock call}@anchor{1fa3}
@deffn {Συνάρτηση} unittest.mock.call (*args, **kwargs)

@code{call()} is a helper object for making simpler assertions, for comparing with
@ref{1f5d,,call_args}, @ref{4895,,call_args_list},
@ref{488e,,mock_calls} and @ref{4890,,method_calls}. @code{call()} can also be
used with @ref{1c2a,,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() (μέθοδος της unittest.mock.call)
@anchor{library/unittest mock unittest mock call call_list}@anchor{48c4}
@deffn {Μέθοδος} call.call_list ()

For a call object that represents multiple calls, @code{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{488e,,mock_calls} on a mock. Manually constructing
the sequence of calls can be tedious.

@ref{48c4,,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{4896}
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{1f5d,,Mock.call_args}, @ref{4895,,Mock.call_args_list} and
@ref{488e,,Mock.mock_calls} attributes can be introspected to get at the individual
arguments they contain.

The @code{call} objects in @ref{1f5d,,Mock.call_args} and @ref{4895,,Mock.call_args_list}
are two-tuples of (positional args, keyword args) whereas the @code{call} objects
in @ref{488e,,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,call,Helpers
@anchor{library/unittest mock create-autospec}@anchor{48c5}
@subsubsection create_autospec


@geindex create_autospec() (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock create_autospec}@anchor{1b4e}
@deffn {Συνάρτηση} 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{1a9,,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.

@code{create_autospec()} also takes arbitrary keyword arguments that are passed to
the constructor of the created mock.
@end deffn

See @ref{4885,,Autospeccing} for examples of how to use auto-speccing with
@ref{1b4e,,create_autospec()} and the `autospec' argument to @ref{1243,,patch()}.


Άλλαξε στην έκδοση 3.8: @ref{1b4e,,create_autospec()} now returns an @ref{e0d,,AsyncMock} if the target is
an async function.


@node ANY,FILTER_DIR,create_autospec,Helpers
@anchor{library/unittest mock any}@anchor{48c6}
@subsubsection ANY


@geindex ANY (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock ANY}@anchor{1fa1}
@deffn {Δεδομένα} 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{1f5d,,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{1ff2,,assert_called_with()} and
@ref{488c,,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{1fa1,,ANY} can also be used in comparisons with call lists like
@ref{488e,,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{1fa1,,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{48c7}
@subsubsection FILTER_DIR


@geindex FILTER_DIR (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock FILTER_DIR}@anchor{4892}
@deffn {Δεδομένα} unittest.mock.FILTER_DIR
@end deffn

@ref{4892,,FILTER_DIR} is a module level variable that controls the way mock objects
respond to @ref{a23,,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{e0e,,Mock} rather than the thing being
mocked) underscore and double underscore prefixed attributes have been
filtered from the result of calling @ref{a23,,dir()} on a @code{Mock}. If you dislike this
behaviour you can switch it off by setting the module level switch
@ref{4892,,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{4892,,FILTER_DIR}.

@node mock_open,Autospeccing,FILTER_DIR,Helpers
@anchor{library/unittest mock mock-open}@anchor{48c8}
@subsubsection mock_open


@geindex mock_open() (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock mock_open}@anchor{1390}
@deffn {Συνάρτηση} unittest.mock.mock_open (mock=None, read_data=None)

A helper function to create a mock to replace the use of @ref{32b,,open()}. It works
for @code{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{1240,,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{11d0,,read()},
@ref{16ce,,readline()}, and @ref{29bb,,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.


Άλλαξε στην έκδοση 3.4: Added @ref{16ce,,readline()} and @ref{29bb,,readlines()} support.
The mock of @ref{11d0,,read()} changed to consume `read_data' rather
than returning it on each call.



Άλλαξε στην έκδοση 3.5: `read_data' is now reset on each call to the `mock'.



Άλλαξε στην έκδοση 3.8: Added @ref{229a,,__iter__()} to implementation so that iteration
(such as in for loops) correctly consumes `read_data'.

@end deffn

Using @ref{32b,,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{32b,,open()} it is the
`returned object' that is used as a context manager (and has @ref{9c6,,__enter__()} and
@ref{16a5,,__exit__()} called).

Mocking context managers with a @ref{1240,,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{4885}@anchor{library/unittest mock autospeccing}@anchor{48c9}
@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{291,,TypeError} if they are
called incorrectly.

Before I explain how auto-speccing works, here’s why it is needed.

@ref{e0e,,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.


Άλλαξε στην έκδοση 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.

@code{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.header_items()
<mock.Mock object at 0x...>
>>> mock.header_items.assret_called_with()  # Intentional typo!
@end example

Auto-speccing solves this problem. You can either pass @code{autospec=True} to
@ref{1243,,patch()} / @ref{1b25,,patch.object()} or use the @ref{1b4e,,create_autospec()} function to create a
mock with a spec. If you use the @code{autospec=True} argument to @code{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{1243,,patch()} calls and then be protected against bugs due to typos and api
changes.

As well as using `autospec' through @ref{1243,,patch()} there is a
@ref{1b4e,,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{a23,,dir()} - that are done.
}.

A more serious problem is that it is common for instance attributes to be
created in the @ref{2fa,,__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{2fa,,__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{1243,,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{48ca}
@subsubsection Sealing mocks


@c from unittest.mock import seal

@geindex seal() (στη μονάδα unittest.mock)
@anchor{library/unittest mock unittest mock seal}@anchor{f60}
@deffn {Συνάρτηση} 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


Added in 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{48cb}
@subsubsection Order of precedence of @code{side_effect}, @code{return_value} and `wraps'


The order of their precedence is:


@enumerate 

@item 
@ref{4882,,side_effect}

@item 
@ref{488a,,return_value}

@item 
`wraps'
@end enumerate

If all three are set, mock will return the value from @ref{4882,,side_effect},
ignoring @ref{488a,,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{4882,,side_effect}, if you reassign
its value back to @code{None}, the order of precedence will be checked between
@ref{488a,,return_value} and the wrapped object, ignoring
@code{side_effect}.

@example
>>> order_mock.get_value.side_effect = None
>>> order_mock.get_value()
'second'
@end example

If the value being returned by @ref{4882,,side_effect} is @ref{4889,,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{e0e,,Mock} wraps an object, the default value of
@ref{488a,,return_value} will be @ref{4889,,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{4882,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node unittest mock — ξεκινώντας,test — Regression tests package for Python,unittest mock — mock object library,Εργαλεία Ανάπτυξης
@anchor{library/unittest mock-examples doc}@anchor{48cc}@anchor{library/unittest mock-examples translation-repo}@anchor{48cd}@anchor{library/unittest mock-examples unittest-mock-getting-started}@anchor{48ce}
@subsection @code{unittest.mock} — ξεκινώντας



Added in version 3.3.

@anchor{library/unittest mock-examples getting-started}@anchor{48cf}
@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
* Χρήση της Προσομοίωσης (Mock): Χρήση της Προσομοίωσης Mock. 
* Patch decorators:: 
* Further examples:: 

@end menu

@node Χρήση της Προσομοίωσης Mock,Patch decorators,,unittest mock — ξεκινώντας
@anchor{library/unittest mock-examples using-mock}@anchor{48d0}
@subsubsection Χρήση της Προσομοίωσης (Mock)


@menu
* Mock patching methods:: 
* Mock for method calls on an object:: 
* Mocking classes:: 
* Ονομασία των προσομοιώσεών σας:: 
* Tracking all calls:: 
* Setting return values and attributes:: 
* Πρόκληση εξαιρέσεων με προσομοιώσεις:: 
* Συναρτήσεις παρενέργειας και iterables:: 
* Προσομοίωση ασύγχρονων επαναληπτών:: 
* Προσομοίωση ασύγχρονου διαχειριστή περιεχομένου:: 
* Creating a mock from an existing object:: 
* Χρήση του side_effect για επιστροφή περιεχομένου ανά αρχείο:: 

@end menu

@node Mock patching methods,Mock for method calls on an object,,Χρήση της Προσομοίωσης Mock
@anchor{library/unittest mock-examples mock-patching-methods}@anchor{48d1}
@subsubsection Mock patching methods


Κοινές χρήσεις για αντικείμενα @ref{e0e,,Mock} περιλαμβάνουν:


@itemize *

@item 
Επιδιόρθωση (Patching) μεθόδων

@item 
Καταγραφή κλήσεων μεθόδων σε αντικείμενα
@end itemize

Ίσως θέλετε να αντικαταστήσετε μια μέθοδο σε ένα αντικείμενο για να ελέγξετε ότι καλείται με τα σωστά ορίσματα από ένα άλλο μέρος του συστήματος:

@example
>>> real = SomeClass()
>>> real.method = MagicMock(name='method')
>>> real.method(3, 4, 5, key='value')
<MagicMock name='method()' id='...'>
@end example

Μόλις χρησιμοποιηθεί η προσομοίωσή μας (@code{real.method} σε αυτό το παράδειγμα) θα έχει μεθόδους και χαρακτηριστικά που σας επιτρέπουν να κάνετε δηλώσεις σχετικά με το πώς έχει χρησιμοποιηθεί.

@cartouche
@quotation Σημείωση 
Στα περισσότερα από αυτά τα παραδείγματα οι κλάσεις @ref{e0e,,Mock} και @ref{1240,,MagicMock} είναι εναλλάξιμες. Καθώς η @code{MagicMock} είναι η πιο ικανή κλάση, αποτελεί μια λογική επιλογή για χρήση από προεπιλογή.
@end quotation
@end cartouche

Μόλις κληθεί η προσομοίωση, το χαρακτηριστικό @ref{4894,,called} ορίζεται σε @code{True}. Πιο σημαντικό είναι ότι μπορούμε να χρησιμοποιήσουμε τη μέθοδο @ref{1ff2,,assert_called_with()} ή @ref{488c,,assert_called_once_with()} για να ελέγξουμε ότι κλήθηκε με τα σωστά ορίσματα.

Αυτό το παράδειγμα ελέγχει ότι η κλήση της @code{ProductionClass().method} έχει ως αποτέλεσμα μια κλήση στη μέθοδο @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 Mock for method calls on an object,Mocking classes,Mock patching methods,Χρήση της Προσομοίωσης Mock
@anchor{library/unittest mock-examples mock-for-method-calls-on-an-object}@anchor{48d2}
@subsubsection Mock for method calls on an object


Στο τελευταίο παράδειγμα επιδιορθώσαμε μια μέθοδο απευθείας σε ένα αντικείμενο για να ελέγξουμε ότι κλήθηκε σωστά. Μια άλλη κοινή χρήση είναι να περάσουμε ένα αντικείμενο σε μια μέθοδο (ή σε κάποιο μέρος του συστήματος υπό δοκιμή) και στη συνέχεια να ελέγξουμε ότι χρησιμοποιείται με τον σωστό τρόπο.

Η απλή @code{ProductionClass} παρακάτω έχει μια μέθοδο @code{closer}. Εάν κληθεί με ένα αντικείμενο, τότε καλεί τη μέθοδο @code{close} σε αυτό.

@example
>>> class ProductionClass:
...     def closer(self, something):
...         something.close()
...
@end example

Έτσι, για να το δοκιμάσουμε, πρέπει να περάσουμε ένα αντικείμενο με μια μέθοδο @code{close} και να ελέγξουμε ότι κλήθηκε σωστά.

@example
>>> real = ProductionClass()
>>> mock = Mock()
>>> real.closer(mock)
>>> mock.close.assert_called_with()
@end example

Δεν χρειάζεται να κάνουμε καμία εργασία για να παρέχουμε τη μέθοδο “close” στην προσομοίωσή μας. Η πρόσβαση στο close τη δημιουργεί. Έτσι, αν το “close” δεν έχει ήδη κληθεί, τότε η πρόσβαση σε αυτό στη δοκιμή θα το δημιουργήσει, αλλά η @ref{1ff2,,assert_called_with()} θα κάνει raise μια εξαίρεση αποτυχίας.

@node Mocking classes,Ονομασία των προσομοιώσεών σας,Mock for method calls on an object,Χρήση της Προσομοίωσης Mock
@anchor{library/unittest mock-examples mocking-classes}@anchor{48d3}
@subsubsection Mocking classes


Μια συνηθισμένη περίπτωση χρήσης είναι η προσομοίωση κλάσεων που δημιουργούνται από τον κώδικα υπό δοκιμή. Όταν επιδιορθώνετε (patch) μια κλάση, τότε αυτή η κλάση αντικαθίσταται με μια προσομοίωση. Τα στιγμιότυπα δημιουργούνται με την `κλήση της κλάσης'. Αυτό σημαίνει ότι έχετε πρόσβαση στο «στιγμιότυπο προσομοίωσης» εξετάζοντας την τιμή επιστροφής της προσομοιωμένης κλάσης.

Στο παρακάτω παράδειγμα έχουμε μια συνάρτηση @code{some_function} που δημιουργεί ένα στιγμιότυπο της @code{Foo} και καλεί μια μέθοδο σε αυτό. Η κλήση στη @ref{1243,,patch()} αντικαθιστά την κλάση @code{Foo} με μια προσομοίωση. Το στιγμιότυπο της @code{Foo} είναι το αποτέλεσμα της κλήσης της προσομοίωσης, οπότε διαμορφώνεται τροποποιώντας το χαρακτηριστικό @ref{488a,,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 Ονομασία των προσομοιώσεών σας,Tracking all calls,Mocking classes,Χρήση της Προσομοίωσης Mock
@anchor{library/unittest mock-examples naming-your-mocks}@anchor{48d4}
@subsubsection Ονομασία των προσομοιώσεών σας


Μπορεί να είναι χρήσιμο να δώσετε στις προσομοιώσεις σας ένα όνομα. Το όνομα εμφανίζεται στην αναπαράσταση (repr) της προσομοίωσης και μπορεί να είναι χρήσιμο όταν η προσομοίωση εμφανίζεται σε μηνύματα αποτυχίας δοκιμών. Το όνομα επίσης μεταδίδεται σε χαρακτηριστικά ή μεθόδους της προσομοίωσης:

@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,Ονομασία των προσομοιώσεών σας,Χρήση της Προσομοίωσης Mock
@anchor{library/unittest mock-examples tracking-all-calls}@anchor{48d5}
@subsubsection Tracking all calls


Συχνά θέλετε να παρακολουθείτε περισσότερες από μία κλήσεις σε μια μέθοδο. Το χαρακτηριστικό @ref{488e,,mock_calls} καταγράφει όλες τις κλήσεις σε θυγατρικά χαρακτηριστικά της προσομοίωσης - και επίσης στα παιδιά τους.

@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

Εάν κάνετε μια δήλωση σχετικά με το @code{mock_calls} και έχουν κληθεί απροσδόκητες μέθοδοι, τότε η δήλωση θα αποτύχει. Αυτό είναι χρήσιμο επειδή εκτός από το να δηλώνετε ότι οι κλήσεις που περιμένατε έχουν γίνει, ελέγχετε επίσης ότι έγιναν με τη σωστή σειρά και χωρίς επιπλέον κλήσεις:

Χρησιμοποιήστε το αντικείμενο @ref{1fa3,,call} για να κατασκευάσετε λίστες για σύγκριση με το @code{mock_calls}:

@example
>>> expected = [call.method(), call.attribute.method(10, x=53)]
>>> mock.mock_calls == expected
True
@end example

Ωστόσο, οι παράμετροι σε κλήσεις που επιστρέφουν προσομοιώσεις δεν καταγράφονται, που σημαίνει ότι δεν είναι δυνατή η παρακολούθηση εμφωλευμένων κλήσεων όπου οι παράμετροι που χρησιμοποιούνται για τη δημιουργία προγόνων είναι σημαντικοί:

@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,Πρόκληση εξαιρέσεων με προσομοιώσεις,Tracking all calls,Χρήση της Προσομοίωσης Mock
@anchor{library/unittest mock-examples setting-return-values-and-attributes}@anchor{48d6}
@subsubsection Setting return values and attributes


Ορισμός των τιμών επιστροφής σε ένα αντικείμενο προσομοίωσης είναι εξαιρετικά εύκολος:

@example
>>> mock = Mock()
>>> mock.return_value = 3
>>> mock()
3
@end example

Φυσικά μπορείτε να κάνετε το ίδιο για μεθόδους στην προσομοίωση:

@example
>>> mock = Mock()
>>> mock.method.return_value = 3
>>> mock.method()
3
@end example

Η τιμή επιστροφής μπορεί επίσης να οριστεί στον κατασκευαστή:

@example
>>> mock = Mock(return_value=3)
>>> mock()
3
@end example

Εάν χρειάζεστε έναν ορισμό χαρακτηριστικού στην προσομοίωσή σας, απλώς κάντε το:

@example
>>> mock = Mock()
>>> mock.x = 3
>>> mock.x
3
@end example

Μερικές φορές θέλετε να προσομοιώσετε μια πιο σύνθετη κατάσταση, όπως για παράδειγμα @code{mock.connection.cursor().execute("SELECT 1")}. Εάν θέλαμε αυτή τη κλήση να επιστρέψει μια λίστα, τότε πρέπει να διαμορφώσουμε το αποτέλεσμα της εμφωλευμένης κλήσης.

Μπορούμε να χρησιμοποιήσουμε το αντικείμενο @ref{1fa3,,call} για να κατασκευάσουμε την λίστα των κλήσεων σε μια «αλυσιδωτή κλήση» όπως αυτή για εύκολη δήλωση αργότερα:

@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

Είναι η κλήση στο @code{.call_list()} που μετατρέπει το αντικείμενο κλήσης σε μια λίστα κλήσεων που αντιπροσωπεύουν τις αλυσιδωτές κλήσεις.

@node Πρόκληση εξαιρέσεων με προσομοιώσεις,Συναρτήσεις παρενέργειας και iterables,Setting return values and attributes,Χρήση της Προσομοίωσης Mock
@anchor{library/unittest mock-examples raising-exceptions-with-mocks}@anchor{48d7}
@subsubsection Πρόκληση εξαιρέσεων με προσομοιώσεις


Ένα χρήσιμο χαρακτηριστικό είναι το @ref{4882,,side_effect}. Εάν το ορίσετε σε μια κλάση εξαίρεσης ή ένα στιγμιότυπο, τότε η εξαίρεση θα γίνει raise όταν κληθεί η προσομοίωση.

@example
>>> mock = Mock(side_effect=Exception('Boom!'))
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!
@end example

@node Συναρτήσεις παρενέργειας και iterables,Προσομοίωση ασύγχρονων επαναληπτών,Πρόκληση εξαιρέσεων με προσομοιώσεις,Χρήση της Προσομοίωσης Mock
@anchor{library/unittest mock-examples side-effect-functions-and-iterables}@anchor{48d8}
@subsubsection Συναρτήσεις παρενέργειας και iterables


Το @code{side_effect} μπορεί επίσης να οριστεί σε μια συνάρτηση ή ένα iterable. Η χρήση του @code{side_effect} ως iterable είναι όταν η προσομοίωσή σας πρόκειται να κληθεί αρκετές φορές, και θέλετε κάθε κλήση να επιστρέφει μια διαφορετική τιμή. Όταν ορίζετε το @code{side_effect} σε ένα iterable, κάθε κλήση στην προσομοίωση επιστρέφει την επόμενη τιμή από το iterable:

@example
>>> mock = MagicMock(side_effect=[4, 5, 6])
>>> mock()
4
>>> mock()
5
>>> mock()
6
@end example

Για πιο προηγμένες χρήσεις, όπως η δυναμική μεταβολή των τιμών επιστροφής ανάλογα με το πώς καλείται η προσομοίωση, το @code{side_effect} μπορεί να είναι μια συνάρτηση. Η συνάρτηση θα κληθεί με τα ίδια ορίσματα με την προσομοίωση. Ό,τι επιστρέφει η συνάρτηση είναι αυτό που επιστρέφει η κλήση:

@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 Προσομοίωση ασύγχρονων επαναληπτών,Προσομοίωση ασύγχρονου διαχειριστή περιεχομένου,Συναρτήσεις παρενέργειας και iterables,Χρήση της Προσομοίωσης Mock
@anchor{library/unittest mock-examples mocking-asynchronous-iterators}@anchor{48d9}
@subsubsection Προσομοίωση ασύγχρονων επαναληπτών


Από την έκδοση Python 3.8, οι @code{AsyncMock} και @code{MagicMock} έχουν υποστήριξη για την προσομοίωση @ref{1130,,ασύγχρονων επαναληπτών} μέσω του @code{__aiter__}. Το χαρακτηριστικό @ref{488a,,return_value} του @code{__aiter__} μπορεί να χρησιμοποιηθεί για να ορίσει τις τιμές επιστροφής που θα χρησιμοποιηθούν για την επανάληψη.

@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 Προσομοίωση ασύγχρονου διαχειριστή περιεχομένου,Creating a mock from an existing object,Προσομοίωση ασύγχρονων επαναληπτών,Χρήση της Προσομοίωσης Mock
@anchor{library/unittest mock-examples mocking-asynchronous-context-manager}@anchor{48da}
@subsubsection Προσομοίωση ασύγχρονου διαχειριστή περιεχομένου


Από την έκδοση Python 3.8, οι @code{AsyncMock} και @code{MagicMock} έχουν υποστήριξη για την προσομοίωση @ref{9f3,,ασύγχρονων διαχειριστών} μέσω των @code{__aenter__} και @code{__aexit__}. Από προεπιλογή, οι @code{__aenter__} και @code{__aexit__} είναι στιγμιότυπα @code{AsyncMock} που επιστρέφουν μια ασύγχρονη συνάρτηση.

@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,Χρήση του side_effect για επιστροφή περιεχομένου ανά αρχείο,Προσομοίωση ασύγχρονου διαχειριστή περιεχομένου,Χρήση της Προσομοίωσης Mock
@anchor{library/unittest mock-examples creating-a-mock-from-an-existing-object}@anchor{48db}
@subsubsection Creating a mock from an existing object


Ένα πρόβλημα με την υπερβολική χρήση της προσομοίωσης είναι ότι συνδέει τις δοκιμές σας με την υλοποίηση των προσομοιώσεών σας αντί με τον πραγματικό κώδικα. Υποθέστε ότι έχετε μια κλάση που υλοποιεί την @code{some_method}. Σε μια δοκιμή για μια άλλη κλάση, παρέχετε μια προσομοίωση αυτού του αντικειμένου που `επίσης' παρέχει την @code{some_method}. Εάν αργότερα αναδιαρθρώσετε την πρώτη κλάση, έτσι ώστε να μην έχει πλέον την @code{some_method} - τότε οι δοκιμές σας θα συνεχίσουν να περνούν, παρόλο που ο κώδικάς σας είναι τώρα σπασμένος!

@ref{e0e,,Mock} σας επιτρέπει να παρέχετε ένα αντικείμενο ως προδιαγραφή για την προσομοίωση, χρησιμοποιώντας το όρισμα λέξης-κλειδιού `spec'. Η πρόσβαση σε μεθόδους / χαρακτηριστικά στην προσομοίωση που δεν υπάρχουν στο αντικείμενο προδιαγραφής σας θα γίνει raise αμέσως ένα σφάλμα χαρακτηριστικού. Εάν αλλάξετε την υλοποίηση της προδιαγραφής σας, τότε οι δοκιμές που χρησιμοποιούν αυτή την κλάση θα αρχίσουν να αποτυγχάνουν αμέσως χωρίς να χρειάζεται να δημιουργήσετε ένα στιγμιότυπο της κλάσης σε αυτές τις δοκιμές.

@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

Η χρήση μιας προδιαγραφής επιτρέπει επίσης μια πιο έξυπνη αντιστοίχιση των κλήσεων που γίνονται στην προσομοίωση, ανεξάρτητα από το αν ορισμένες παράμετροι περάστηκαν ως ορισμένες ή ονομαστικές παραμέτρους:

@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

Εάν θέλετε αυτή η πιο έξυπνη αντιστοίχιση να λειτουργεί επίσης με κλήσεις μεθόδων στην προσομοίωση, μπορείτε να χρησιμοποιήσετε @ref{4885,,auto-speccing}.

Εάν θέλετε μια πιο ισχυρή μορφή προδιαγραφής που αποτρέπει τον ορισμό αυθαίρετων χαρακτηριστικών καθώς και την πρόσβαση σε αυτά, τότε μπορείτε να χρησιμοποιήσετε το `spec_set' αντί για το `spec'.

@node Χρήση του side_effect για επιστροφή περιεχομένου ανά αρχείο,,Creating a mock from an existing object,Χρήση της Προσομοίωσης Mock
@anchor{library/unittest mock-examples using-side-effect-to-return-per-file-content}@anchor{48dc}
@subsubsection Χρήση του side_effect για επιστροφή περιεχομένου ανά αρχείο


Η @ref{1390,,mock_open()} χρησιμοποιείται για την επιδιόρθωση (patch) της @ref{32b,,open()} μεθόδου. Το @ref{4882,,side_effect} μπορεί να χρησιμοποιηθεί για την επιστροφή ενός νέου αντικειμένου Mock ανά κλήση. Αυτό μπορεί να χρησιμοποιηθεί για την επιστροφή διαφορετικών περιεχομένων ανά αρχείο που αποθηκεύονται σε ένα λεξικό:

@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,Χρήση της Προσομοίωσης Mock,unittest mock — ξεκινώντας
@anchor{library/unittest mock-examples patch-decorators}@anchor{48dd}
@subsubsection Patch decorators


@cartouche
@quotation Σημείωση 
Με την @ref{1243,,patch()} έχει σημασία να επιδιορθώνετε αντικείμενα στο χώρο ονομάτων όπου αναζητούνται. Αυτό είναι συνήθως απλό, αλλά για έναν γρήγορο οδηγό διαβάστε @ref{4883,,where to patch}.
@end quotation
@end cartouche

Μια κοινή ανάγκη στις δοκιμές είναι να επιδιορθώσετε ένα χαρακτηριστικό κλάσης ή ένα χαρακτηριστικό μονάδας, για παράδειγμα επιδιόρθωση ενός ενσωματωμένου ή επιδιόρθωση μιας κλάσης σε μια μονάδα για να ελέγξετε ότι δημιουργείται. Οι μονάδες και οι κλάσεις είναι ουσιαστικά παγκόσμιες, οπότε η επιδιόρθωση σε αυτές πρέπει να αναιρεθεί μετά τη δοκιμή ή η επιδιόρθωση θα επιμείνει σε άλλες δοκιμές και θα προκαλέσει προβλήματα που είναι δύσκολα να διαγνωστούν.

Η προσομοίωση παρέχει τρεις βολικούς διακοσμητές για αυτό: @ref{1243,,patch()}, @ref{1b25,,patch.object()} και @ref{1b7a,,patch.dict()}. Η @code{patch} παίρνει μια μοναδική συμβολοσειρά, της μορφής @code{package.module.Class.attribute} για να καθορίσει το χαρακτηριστικό που επιδιορθώνετε. Επίσης παίρνει προαιρετικά μια τιμή με την οποία θέλετε να αντικατασταθεί το χαρακτηριστικό (ή η κλάση ή οτιδήποτε). “patch.object” παίρνει ένα αντικείμενο και το όνομα του χαρακτηριστικού που θα θέλατε να επιδιορθώσετε, συν προαιρετικά την τιμή με την οποία θα το επιδιορθώσετε.

@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

Εάν επιδιορθώνετε ένα module (συμπεριλαμβανομένου του @ref{13,,builtins}), τότε χρησιμοποιήστε την @ref{1243,,patch()} αντί για την @ref{1b25,,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

Το όνομα του module μπορεί να είναι “τελεία”, με τη μορφή @code{package.module} εάν χρειάζεται:

@example
>>> @@patch('package.module.ClassName.attribute', sentinel.attribute)
... def test():
...     from package.module import ClassName
...     assert ClassName.attribute == sentinel.attribute
...
>>> test()
@end example

Ένα ωραίο μοτίβο είναι να διακοσμείτε πραγματικά τις μεθόδους δοκιμής:

@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

Εάν θέλετε να επιδιορθώσετε με μια προσομοίωση, μπορείτε να χρησιμοποιήσετε @ref{1243,,patch()} με μόνο ένα όρισμα (ή @ref{1b25,,patch.object()} με δύο ορίσματα). Η προσομοίωση θα δημιουργηθεί για εσάς και θα περαστεί στη συνάρτηση / μέθοδο δοκιμής:

@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

Μπορείτε να στοιβάξετε πολλαπλούς διακοσμητές επιδιόρθωσης χρησιμοποιώντας

@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

Όταν εμφωλεύετε διακοσμητές επιδιόρθωσης, οι προσομοιώσεις περνιούνται στη διακοσμημένη συνάρτηση με την ίδια σειρά που εφαρμόστηκαν (η κανονική τάξη `Python' με την οποία εφαρμόζονται οι διακοσμητές). Αυτό σημαίνει από κάτω προς τα πάνω, οπότε στο παραπάνω παράδειγμα η προσομοίωση για το @code{test_module.ClassName2} περνάει πρώτη.

Υπάρχει επίσης η @ref{1b7a,,patch.dict()} για τον ορισμό τιμών σε ένα λεξικό μόνο κατά τη διάρκεια ενός πεδίου και την αποκατάσταση του λεξικού στην αρχική του κατάσταση όταν τελειώνει η δοκιμή:

@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} και η @code{patch.dict} μπορούν όλες να χρησιμοποιηθούν ως διαχειριστές συμφραζομένων.

Όπου χρησιμοποιείτε την @ref{1243,,patch()} για να δημιουργήσετε μια προσομοίωση για εσάς, μπορείτε να λάβετε μια αναφορά στην προσομοίωση χρησιμοποιώντας τη μορφή «as» της δήλωσης with:

@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

Ως εναλλακτική, η @code{patch}, η @code{patch.object} και η @code{patch.dict} μπορούν να χρησιμοποιηθούν ως διακοσμητές κλάσης. Όταν χρησιμοποιούνται με αυτόν τον τρόπο, είναι το ίδιο με την εφαρμογή του διακοσμητή ξεχωριστά σε κάθε μέθοδο του οποίου το όνομα ξεκινά με «test».

@node Further examples,,Patch decorators,unittest mock — ξεκινώντας
@anchor{library/unittest mock-examples further-examples}@anchor{48de}@anchor{library/unittest mock-examples id1}@anchor{48df}
@subsubsection Further examples


Εδώ είναι μερικά ακόμη παραδείγματα για μερικά ελαφρώς πιο προηγμένα σενάρια.

@menu
* Προσομοίωση αλυσιδωτών κλήσεων:: 
* Μερική προσομοίωση:: 
* Mocking a generator method:: 
* Εφαρμογή της ίδιας επιδιόρθωσης σε κάθε μέθοδο δοκιμής:: 
* Mocking unbound methods:: 
* Έλεγχος πολλαπλών κλήσεων με προσομοίωση:: 
* Αντιμετώπιση μεταβλητών ορισμάτων:: 
* Nesting patches:: 
* Προσομοίωση ενός λεξικού με το MagicMock:: 
* Υποκλάσεις Mock και τα χαρακτηριστικά τους:: 
* Προσομοίωση εισαγωγών με το patch.dict: Προσομοίωση εισαγωγών με το patch dict. 
* Παρακολούθηση της σειράς κλήσεων και λιγότερο λεκτικές δηλώσεις κλήσεων:: 
* Πιο σύνθετη αντιστοίχιση ορισμάτων:: 

@end menu

@node Προσομοίωση αλυσιδωτών κλήσεων,Μερική προσομοίωση,,Further examples
@anchor{library/unittest mock-examples mocking-chained-calls}@anchor{48e0}
@subsubsection Προσομοίωση αλυσιδωτών κλήσεων


Η προσομοίωση αλυσιδωτών κλήσεων είναι στην πραγματικότητα απλή με την προσομοίωση μόλις κατανοήσετε το χαρακτηριστικό @ref{488a,,return_value}. Όταν καλείται μια προσομοίωση για πρώτη φορά, ή λαμβάνετε την @code{return_value} της πριν καλεστεί, δημιουργείται μια νέα @ref{e0e,,Mock}.

Αυτό σημαίνει ότι μπορείτε να δείτε πώς έχει χρησιμοποιηθεί το αντικείμενο που επιστρέφεται από μια κλήση σε ένα προσομοιωμένο αντικείμενο, εξετάζοντας την προσομοίωση @code{return_value}:

@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

Από εδώ είναι ένα απλό βήμα για τη διαμόρφωση και στη συνέχεια τη δημιουργία δηλώσεων σχετικά με τις αλυσιδωτές κλήσεις. Φυσικά μια άλλη εναλλακτική είναι να γράψετε τον κώδικά σας με πιο δοκιμαστικό τρόπο από την αρχή…

Λοιπόν, υποθέτουμε ότι έχουμε κάποιο κώδικα που μοιάζει λίγο με αυτό:

@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

Υποθέτοντας ότι το @code{BackendProvider} έχει ήδη δοκιμαστεί καλά, πώς δοκιμάζουμε τη @code{method()}; Συγκεκριμένα, θέλουμε να δοκιμάσουμε ότι η ενότητα κώδικα @code{# more code} χρησιμοποιεί το αντικείμενο απόκρισης με τον σωστό τρόπο.

Καθώς αυτή η αλυσίδα κλήσεων γίνεται από ένα χαρακτηριστικό στιγμιότυπου, μπορούμε να επιδιορθώσουμε (monkey patch) το χαρακτηριστικό @code{backend} σε ένα στιγμιότυπο @code{Something}. Σε αυτή την συγκεκριμένη περίπτωση, μας ενδιαφέρει μόνο η τιμή επιστροφής από την τελική κλήση στο @code{start_call}, οπότε δεν έχουμε πολλή διαμόρφωση να κάνουμε. Ας υποθέσουμε ότι το αντικείμενο που επιστρέφει είναι “σαν αρχείο”, οπότε θα διασφαλίσουμε ότι το αντικείμενο απόκρισης μας χρησιμοποιεί την ενσωματωμένη @ref{32b,,open()} ως το @code{spec} της.

Για να το κάνουμε αυτό, δημιουργούμε ένα στιγμιότυπο προσομοίωσης ως το mock backend μας και δημιουργούμε ένα αντικείμενο προσομοίωσης απόκρισης για αυτό. Για να ορίσουμε την απόκριση ως την τιμή επιστροφής για εκείνο το τελικό @code{start_call}, θα μπορούσαμε να κάνουμε αυτό:

@example
mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response
@end example

Μπορούμε να το κάνουμε με έναν ελαφρώς πιο ωραίο τρόπο χρησιμοποιώντας τη @ref{488b,,configure_mock()} μέθοδο για να ορίσουμε απευθείας την τιμή επιστροφής για εμάς:

@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

Με αυτά, επιδιορθώνουμε (monkey patch) το «mock backend» στη θέση του και μπορούμε να κάνουμε την πραγματική κλήση:

@example
>>> something.backend = mock_backend
>>> something.method()
@end example

Με το χαρακτηριστικό @ref{488e,,mock_calls} μπορούμε να ελέγξουμε την αλυσιδωτή κλήση με μια μοναδική δήλωση. Μια αλυσιδωτή κλήση είναι πολλές κλήσεις σε μία γραμμή κώδικα, οπότε θα υπάρχουν πολλές εισαγωγές στο @code{mock_calls}. Μπορούμε να χρησιμοποιήσουμε τη @ref{48c4,,call.call_list()} για να δημιουργήσουμε αυτή τη λίστα κλήσεων για εμάς:

@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 Μερική προσομοίωση,Mocking a generator method,Προσομοίωση αλυσιδωτών κλήσεων,Further examples
@anchor{library/unittest mock-examples partial-mocking}@anchor{48e1}
@subsubsection Μερική προσομοίωση


Για ορισμένες δοκιμές, μπορεί να θέλετε να προσομοιώσετε μια κλήση στη @ref{186c,,datetime.date.today()} για να επιστρέψετε μια γνωστή ημερομηνία, αλλά δεν θέλετε να αποτρέψετε τον κώδικα υπό δοκιμή από τη δημιουργία νέων αντικειμένων ημερομηνίας. Δυστυχώς, η @ref{48d,,datetime.date} είναι γραμμένη σε C, οπότε δεν μπορείτε απλώς να κάνετε monkey-patch στη στατική @code{datetime.date.today()} μέθοδο.

Αντίθετα, μπορείτε ουσιαστικά να τυλίξετε την κλάση ημερομηνίας με μια προσομοίωση, ενώ περνάτε κλήσεις στον κατασκευαστή στην πραγματική κλάση (και επιστρέφοντας πραγματικά στιγμιότυπα).

Η @ref{1243,,patch decorator} χρησιμοποιείται εδώ για να επιδιορθώσετε την κλάση ημερομηνίας στο μοντέλο υπό δοκιμή. Το χαρακτηριστικό @ref{4882,,side_effect} στην προσομοίωση της κλάσης ημερομηνίας ρυθμίζεται στη συνέχεια σε μια συνάρτηση λάμδα που επιστρέφει μια πραγματική ημερομηνία. Όταν καλείται η προσομοίωση της κλάσης ημερομηνίας, θα κατασκευαστεί και θα επιστραφεί μια πραγματική ημερομηνία από το @code{side_effect}.

@example
>>> import datetime as dt
>>> with patch('mymodule.date') as mock_date:
...     mock_date.today.return_value = dt.date(2010, 10, 8)
...     mock_date.side_effect = lambda *args, **kw: dt.date(*args, **kw)
...
...     assert mymodule.date.today() == dt.date(2010, 10, 8)
...     assert mymodule.date(2009, 6, 8) == dt.date(2009, 6, 8)
@end example

Σημειώστε ότι δεν επιδιορθώνουμε παγκοσμίως την @ref{48d,,datetime.date}, αλλά επιδιορθώνουμε την @code{date} στο μοντέλο που τη `χρησιμοποιεί'. Δείτε @ref{4883,,where to patch}.

Όταν καλείται το @code{date.today()}, επιστρέφεται μια γνωστή ημερομηνία, αλλά οι κλήσεις στον κατασκευαστή @code{date(...)} εξακολουθούν να επιστρέφουν κανονικές ημερομηνίες. Χωρίς αυτό, μπορεί να βρεθείτε να πρέπει να υπολογίσετε ένα αναμενόμενο αποτέλεσμα χρησιμοποιώντας ακριβώς τον ίδιο αλγόριθμο με τον κώδικα υπό δοκιμή, που είναι ένα κλασικό αντι-μοτίβο δοκιμών.

Οι κλήσεις στον κατασκευαστή ημερομηνίας καταγράφονται στα χαρακτηριστικά του @code{mock_date} (@code{call_count} και φίλοι), τα οποία μπορεί επίσης να είναι χρήσιμα για τις δοκιμές σας.

Ένας εναλλακτικός τρόπος αντιμετώπισης της προσομοίωσης ημερομηνιών ή άλλων ενσωματωμένων κλάσεων, συζητείται σε αυτή την καταχώρηση ιστολογίου@footnote{https://williambert.online/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/}.

@node Mocking a generator method,Εφαρμογή της ίδιας επιδιόρθωσης σε κάθε μέθοδο δοκιμής,Μερική προσομοίωση,Further examples
@anchor{library/unittest mock-examples mocking-a-generator-method}@anchor{48e2}
@subsubsection Mocking a generator method


Μια γεννήτρια Python είναι μια συνάρτηση ή μέθοδος που χρησιμοποιεί τη @ref{d93,,yield} δήλωση για να επιστρέψει μια σειρά τιμών όταν γίνεται επανάληψη πάνω της @footnote{
Υπάρχουν επίσης εκφράσεις γεννητριών και πιο @uref{http://www.dabeaz.com/coroutines/index.html,προηγμένες χρήσεις} γεννητριών, αλλά δεν μας απασχολούν εδώ. Μια πολύ καλή εισαγωγή στις γεννήτριες και πόσο ισχυρές είναι: @uref{http://www.dabeaz.com/generators/,Generator Tricks for Systems Programmers}.
}.

Μια μέθοδος / συνάρτηση γεννήτριας καλείται για να επιστρέψει το αντικείμενο γεννήτριας. Είναι το αντικείμενο γεννήτριας που στη συνέχεια επαναλαμβάνεται. Η μέθοδος πρωτοκόλλου για την επανάληψη είναι η @ref{229a,,__iter__()}, οπότε μπορούμε να την προσομοιώσουμε χρησιμοποιώντας μια @ref{1240,,MagicMock}.

Εδώ είναι ένα παράδειγμα κλάσης με μια μέθοδο «iter» που υλοποιείται ως γεννήτρια:

@example
>>> class Foo:
...     def iter(self):
...         for i in [1, 2, 3]:
...             yield i
...
>>> foo = Foo()
>>> list(foo.iter())
[1, 2, 3]
@end example

Πώς θα προσομοιώναμε αυτή την κλάση, και συγκεκριμένα τη μέθοδο της «iter»;

Για να διαμορφώσουμε τις τιμές που επιστρέφονται από την επανάληψη (ρητά στην κλήση στη @ref{4d9,,list}), πρέπει να διαμορφώσουμε το αντικείμενο που επιστρέφεται από την κλήση στο @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 Εφαρμογή της ίδιας επιδιόρθωσης σε κάθε μέθοδο δοκιμής,Mocking unbound methods,Mocking a generator method,Further examples
@anchor{library/unittest mock-examples applying-the-same-patch-to-every-test-method}@anchor{48e3}
@subsubsection Εφαρμογή της ίδιας επιδιόρθωσης σε κάθε μέθοδο δοκιμής


Εάν θέλετε να υπάρχουν πολλές επιδιορθώσεις για πολλαπλές μεθόδους δοκιμής, ο προφανής τρόπος είναι να εφαρμόσετε τους διακοσμητές επιδιόρθωσης σε κάθε μέθοδο. Αυτό μπορεί να φαίνεται σαν περιττή επανάληψη. Αντίθετα, μπορείτε να χρησιμοποιήσετε την @ref{1243,,patch()} (σε όλες τις διάφορες μορφές της) ως διακοσμητή κλάσης. Αυτό εφαρμόζει τις επιδιορθώσεις σε όλες τις μεθόδους δοκιμής στην κλάση. Μια μέθοδος δοκιμής αναγνωρίζεται από μεθόδους των οποίων τα ονόματα ξεκινούν με @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

Ένας εναλλακτικός τρόπος διαχείρισης των επιδιορθώσεων είναι η χρήση των @ref{48b5,,patch methods; start and stop}. Αυτά σας επιτρέπουν να μετακινήσετε την επιδιόρθωση στις μεθόδους σας @code{setUp} και @code{tearDown}.

@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

Εάν χρησιμοποιήσετε αυτήν την τεχνική, πρέπει να διασφαλίσετε ότι η επιδιόρθωση αναιρείται καλώντας το @code{stop}. Αυτό μπορεί να είναι πιο περίπλοκο από ό,τι μπορεί να νομίζετε, επειδή εάν γίνει raise μια εξαίρεση στο setUp, τότε το tearDown δεν καλείται. Η @ref{e43,,unittest.TestCase.addCleanup()} καθιστά αυτό πιο εύκολο:

@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,Έλεγχος πολλαπλών κλήσεων με προσομοίωση,Εφαρμογή της ίδιας επιδιόρθωσης σε κάθε μέθοδο δοκιμής,Further examples
@anchor{library/unittest mock-examples mocking-unbound-methods}@anchor{48e4}
@subsubsection Mocking unbound methods


Μερικές φορές μια δοκιμή χρειάζεται να επιδιορθώσει μια `μη δεσμευμένη μέθοδο', που σημαίνει την επιδιόρθωση της μεθόδου στην κλάση αντί για το στιγμιότυπο. Για να κάνετε δηλώσεις σχετικά με το ποια αντικείμενα καλούσαν αυτή τη συγκεκριμένη μέθοδο, πρέπει να περάσετε το @code{self} ως πρώτο όρισμα. Το πρόβλημα είναι ότι δεν μπορείτε να επιδιορθώσετε με μια προσομοίωση για αυτό, επειδή αν αντικαταστήσετε μια μη δεσμευμένη μέθοδο με μια προσομοίωση, δεν γίνεται δεσμευμένη μέθοδος όταν ανακτάται από το στιγμιότυπο, και έτσι δεν περνάει το @code{self}. Η λύση είναι να επιδιορθώσετε τη μη δεσμευμένη μέθοδο με μια πραγματική συνάρτηση αντί για αυτό. Ο διακοσμητής @ref{1243,,patch()} το καθιστά τόσο απλό να επιδιορθώνετε μεθόδους με μια προσομοίωση που η ανάγκη δημιουργίας μιας πραγματικής συνάρτησης γίνεται ενοχλητική.

Εάν περάσετε το @code{autospec=True} στην επιδιόρθωση, τότε γίνεται η επιδιόρθωση με ένα `πραγματικό' αντικείμενο συνάρτησης. Αυτό το αντικείμενο συνάρτησης έχει την ίδια υπογραφή με αυτό που αντικαθιστά, αλλά αναθέτει σε μια προσομοίωση κάτω από την κουκούλα. Ακόμα λαμβάνετε την προσομοίωσή σας που δημιουργείται αυτόματα με ακριβώς τον ίδιο τρόπο όπως πριν. Αυτό που σημαίνει, όμως, είναι ότι αν το χρησιμοποιήσετε για να επιδιορθώσετε μια μη δεσμευμένη μέθοδο σε μια κλάση, η προσομοιωμένη συνάρτηση θα μετατραπεί σε δεσμευμένη μέθοδο εάν ανακτηθεί από ένα στιγμιότυπο. Θα έχει το @code{self} που περνάει ως πρώτο όρισμα, που είναι ακριβώς αυτό που χρειαζόταν:

@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

Εάν δεν χρησιμοποιήσουμε το @code{autospec=True}, τότε η μη δεσμευμένη μέθοδος επιδιορθώνεται με ένα στιγμιότυπο Mock αντίθετα, και δεν καλείται με το @code{self}.

@node Έλεγχος πολλαπλών κλήσεων με προσομοίωση,Αντιμετώπιση μεταβλητών ορισμάτων,Mocking unbound methods,Further examples
@anchor{library/unittest mock-examples checking-multiple-calls-with-mock}@anchor{48e5}
@subsubsection Έλεγχος πολλαπλών κλήσεων με προσομοίωση


Η προσομοίωση έχει ένα ωραίο API για τη δημιουργία δηλώσεων σχετικά με το πώς χρησιμοποιούνται τα αντικείμενα προσομοίωσής σας.

@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

Εάν η προσομοίωσή σας καλείται μόνο μία φορά, μπορείτε να χρησιμοποιήσετε τη @ref{488c,,assert_called_once_with()} μέθοδο που επίσης δηλώνει ότι το @ref{19a6,,call_count} είναι ένα.

@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

Και οι δύο @code{assert_called_with} και @code{assert_called_once_with} κάνουν δηλώσεις σχετικά με την `τελευταία' κλήση. Εάν η προσομοίωσή σας πρόκειται να καλείται πολλές φορές, και θέλετε να κάνετε δηλώσεις σχετικά με `όλες' αυτές τις κλήσεις, μπορείτε να χρησιμοποιήσετε το @ref{4895,,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

Ο βοηθός @ref{1fa3,,call} καθιστά εύκολο να κάνετε δηλώσεις σχετικά με αυτές τις κλήσεις. Μπορείτε να δημιουργήσετε μια λίστα με τις αναμενόμενες κλήσεις και να τη συγκρίνετε με το @code{call_args_list}. Αυτό μοιάζει αξιοσημείωτα με το repr του @code{call_args_list}:

@example
>>> expected = [call(1, 2, 3), call(4, 5, 6), call()]
>>> mock.call_args_list == expected
True
@end example

@node Αντιμετώπιση μεταβλητών ορισμάτων,Nesting patches,Έλεγχος πολλαπλών κλήσεων με προσομοίωση,Further examples
@anchor{library/unittest mock-examples coping-with-mutable-arguments}@anchor{48e6}
@subsubsection Αντιμετώπιση μεταβλητών ορισμάτων


Μια άλλη κατάσταση που είναι σπάνια, αλλά μπορεί να σας δαγκώσει, είναι όταν η προσομοίωσή σας καλείται με μεταβλητά ορίσματα. Το @code{call_args} και το @code{call_args_list} αποθηκεύουν `αναφορές' στα ορίσματα. Εάν τα ορίσματα μεταβλητοποιηθούν από τον κώδικα υπό δοκιμή, τότε δεν μπορείτε πλέον να κάνετε δηλώσεις σχετικά με το ποιες ήταν οι τιμές όταν κλήθηκε η προσομοίωση.

Εδώ είναι μερικοί παραδείγματα κώδικα που δείχνουν το πρόβλημα. Φανταστείτε τις παρακάτω συναρτήσεις ορισμένες στο “mymodule”:

@example
def frob(val):
    pass

def grob(val):
    "First frob and then clear val"
    frob(val)
    val.clear()
@end example

Όταν προσπαθήσουμε να δοκιμάσουμε ότι το @code{grob} καλεί το @code{frob} με το σωστό όρισμα, δείτε τι συμβαίνει:

@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

Μια πιθανότητα θα ήταν για την προσομοίωση να αντιγράψει τα ορίσματα που περνάτε. Αυτό θα μπορούσε στη συνέχεια να προκαλέσει προβλήματα εάν κάνετε δηλώσεις που βασίζονται στην ταυτότητα αντικειμένου για την ισότητα.

Here’s one solution that uses the @ref{4882,,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 we’re using `another' mock to store the arguments so that we can use the
mock methods for doing the assertion. Again a helper function sets this up for
us.

@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} καλείται με την προσομοίωση που θα κληθεί. Επιστρέφει μια νέα προσομοίωση στην οποία κάνουμε τη δήλωση. Η συνάρτηση @code{side_effect} κάνει ένα αντίγραφο των ορισμάτων και καλεί τη @code{new_mock} με το αντίγραφο.

@cartouche
@quotation Σημείωση 
Εάν η προσομοίωσή σας πρόκειται να χρησιμοποιηθεί μόνο μία φορά, υπάρχει ένας ευκολότερος τρόπος ελέγχου των ορισμάτων στο σημείο που καλούνται. Μπορείτε απλά να κάνετε τον έλεγχο μέσα σε μια @code{side_effect} συνάρτηση.

@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

Μια εναλλακτική προσέγγιση είναι να δημιουργήσετε μια υποκλάση της @ref{e0e,,Mock} ή @ref{1240,,MagicMock} που αντιγράφει (χρησιμοποιώντας τη @ref{f2b,,copy.deepcopy()}) τα ορίσματα. Εδώ είναι ένα παράδειγμα υλοποίησης:

@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

Όταν υποκλάσετε το @code{Mock} ή το @code{MagicMock}, όλα τα δυναμικά δημιουργημένα χαρακτηριστικά, και το @code{return_value} θα χρησιμοποιούν την υποκλάση σας αυτόματα. Αυτό σημαίνει ότι όλα τα παιδιά ενός @code{CopyingMock} θα έχουν επίσης τον τύπο @code{CopyingMock}.

@node Nesting patches,Προσομοίωση ενός λεξικού με το MagicMock,Αντιμετώπιση μεταβλητών ορισμάτων,Further examples
@anchor{library/unittest mock-examples nesting-patches}@anchor{48e7}
@subsubsection Nesting patches


Η χρήση της επιδιόρθωσης ως διαχειριστής περιβάλλοντος είναι ωραία, αλλά αν κάνετε πολλαπλές επιδιορθώσεις, μπορεί να καταλήξετε με επικαλυπτόμενες δηλώσεις with που εσοχίζουν όλο και περισσότερο προς τα δεξιά:

@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

Με τις λειτουργίες καθαρισμού του unittest και το @ref{48b5,,patch methods; start and stop} μπορούμε να επιτύχουμε το ίδιο αποτέλεσμα χωρίς την εμφωλευμένη εσοχή. Μια απλή βοηθητική μέθοδος, @code{create_patch}, τοποθετεί την επιδιόρθωση στη θέση της και επιστρέφει την δημιουργημένη προσομοίωση για εμάς:

@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 Προσομοίωση ενός λεξικού με το MagicMock,Υποκλάσεις Mock και τα χαρακτηριστικά τους,Nesting patches,Further examples
@anchor{library/unittest mock-examples mocking-a-dictionary-with-magicmock}@anchor{48e8}
@subsubsection Προσομοίωση ενός λεξικού με το MagicMock


Ίσως θέλετε να προσομοιώσετε ένα λεξικό ή άλλο αντικείμενο κοντέινερ, καταγράφοντας όλη την πρόσβαση σε αυτό, ενώ εξακολουθεί να συμπεριφέρεται σαν λεξικό.

Μπορούμε να το κάνουμε αυτό με την @ref{1240,,MagicMock}, η οποία θα συμπεριφέρεται σαν λεξικό, και χρησιμοποιώντας το @ref{4882,,side_effect} για να αναθέσουμε την πρόσβαση στο λεξικό σε ένα πραγματικό υποκείμενο λεξικό που είναι υπό τον έλεγχό μας.

Όταν οι μέθοδοι @ref{787,,__getitem__()} και @ref{1670,,__setitem__()} του @code{MagicMock} μας καλούνται (κανονική πρόσβαση λεξικού), τότε το @code{side_effect} καλείται με το κλειδί (και στην περίπτωση του @code{__setitem__} και την τιμή επίσης). Μπορούμε επίσης να ελέγξουμε τι επιστρέφεται.

Μετά τη χρήση του @code{MagicMock}, μπορούμε να χρησιμοποιήσουμε χαρακτηριστικά όπως το @ref{4895,,call_args_list} για να κάνουμε δηλώσεις σχετικά με το πώς χρησιμοποιήθηκε το λεξικό:

@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 Σημείωση 
Μια εναλλακτική λύση στη χρήση του @code{MagicMock} είναι να χρησιμοποιήσετε το @code{Mock} και να παρέχετε `μόνο' τις μαγικές μεθόδους που θέλετε συγκεκριμένα:

@example
>>> mock = Mock()
>>> mock.__getitem__ = Mock(side_effect=getitem)
>>> mock.__setitem__ = Mock(side_effect=setitem)
@end example

Μια `τρίτη' επιλογή είναι να χρησιμοποιήσετε το @code{MagicMock} αλλά περνώντας το @code{dict} ως όρισμα `spec' (ή `spec_set'), έτσι ώστε το δημιουργημένο @code{MagicMock} να έχει διαθέσιμες μόνο τις μαγικές μεθόδους λεξικού:

@example
>>> mock = MagicMock(spec_set=dict)
>>> mock.__getitem__.side_effect = getitem
>>> mock.__setitem__.side_effect = setitem
@end example
@end quotation
@end cartouche

Με αυτές τις λειτουργίες side effect στη θέση τους, το @code{mock} θα συμπεριφέρεται σαν ένα κανονικό λεξικό αλλά καταγράφοντας την πρόσβαση. Ακόμα κάνει raise μια @ref{7df,,KeyError} εάν προσπαθήσετε να αποκτήσετε πρόσβαση σε ένα κλειδί που δεν υπάρχει.

@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

Μετά τη χρήση του, μπορείτε να κάνετε δηλώσεις σχετικά με την πρόσβαση χρησιμοποιώντας τις κανονικές μεθόδους και χαρακτηριστικά προσομοίωσης:

@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 και τα χαρακτηριστικά τους,Προσομοίωση εισαγωγών με το patch dict,Προσομοίωση ενός λεξικού με το MagicMock,Further examples
@anchor{library/unittest mock-examples mock-subclasses-and-their-attributes}@anchor{48e9}
@subsubsection Υποκλάσεις Mock και τα χαρακτηριστικά τους


Υπάρχουν διάφοροι λόγοι για τους οποίους μπορεί να θέλετε να υποκλάσετε την @ref{e0e,,Mock}. Ένας λόγος μπορεί να είναι η προσθήκη βοηθητικών μεθόδων. Εδώ είναι ένα ανόητο παράδειγμα:

@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

Η τυπική συμπεριφορά για τα στιγμιότυπα @code{Mock} είναι ότι τα χαρακτηριστικά και οι επιστρεφόμενες τιμές προσομοιώσεων είναι του ίδιου τύπου με την προσομοίωση στην οποία έχουν πρόσβαση. Αυτό διασφαλίζει ότι τα χαρακτηριστικά @code{Mock} είναι @code{Mocks} και τα χαρακτηριστικά @code{MagicMock} είναι @code{MagicMocks} @footnote{
Μια εξαίρεση σε αυτόν τον κανόνα είναι οι μη κλητές προσομοιώσεις. Τα χαρακτηριστικά χρησιμοποιούν την κλητή παραλλαγή επειδή διαφορετικά οι μη κλητές προσομοιώσεις δεν θα μπορούσαν να έχουν κλητές μεθόδους.
}. Έτσι, εάν υποκλάσετε για να προσθέσετε βοηθητικές μεθόδους, τότε θα είναι επίσης διαθέσιμες στα χαρακτηριστικά και στην επιστρεφόμενη τιμή προσομοίωσης των στιγμιότυπων της υποκλάσης σας.

@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

Μερικές φορές αυτό είναι άβολο. Για παράδειγμα, ένας χρήστης@footnote{https://code.google.com/archive/p/mock/issues/105} υποκλάσει την προσομοίωση για να δημιουργήσει έναν προσαρμογέα Twisted@footnote{https://twisted.org/documents/11.0.0/api/twisted.python.components.html}. Η εφαρμογή αυτού και στα χαρακτηριστικά προκαλεί πραγματικά σφάλματα.

@code{Mock} (σε όλες τις παραλλαγές του) χρησιμοποιεί μια μέθοδο που ονομάζεται @code{_get_child_mock} για να δημιουργήσει αυτές τις «υπο-προσομοιώσεις» για χαρακτηριστικά και επιστρεφόμενες τιμές. Μπορείτε να αποτρέψετε τη χρήση της υποκλάσης σας για χαρακτηριστικά, υπερκαλύπτοντας αυτή τη μέθοδο. Η υπογραφή είναι ότι λαμβάνει αυθαίρετα ορίσματα λέξεων-κλειδιών (@code{**kwargs}) που στη συνέχεια περνιούνται στον κατασκευαστή προσομοιώσεων:

@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 Προσομοίωση εισαγωγών με το patch dict,Παρακολούθηση της σειράς κλήσεων και λιγότερο λεκτικές δηλώσεις κλήσεων,Υποκλάσεις Mock και τα χαρακτηριστικά τους,Further examples
@anchor{library/unittest mock-examples mocking-imports-with-patch-dict}@anchor{48ea}
@subsubsection Προσομοίωση εισαγωγών με το patch.dict


Μια κατάσταση όπου η προσομοίωση μπορεί να είναι δύσκολη είναι όταν έχετε μια τοπική εισαγωγή μέσα σε μια συνάρτηση. Αυτές είναι πιο δύσκολες για προσομοίωση επειδή δεν χρησιμοποιούν ένα αντικείμενο από το χώρο ονομάτων του module που μπορούμε να επιδιορθώσουμε.

Γενικά, οι τοπικές εισαγωγές πρέπει να αποφεύγονται. Κάποιες φορές γίνονται για να αποτραπούν οι κυκλικές εξαρτήσεις, για τις οποίες υπάρχει `συνήθως' ένας πολύ καλύτερος τρόπος για να λυθεί το πρόβλημα (αναδιαμόρφωση του κώδικα) ή για να αποτραπούν τα «προκαταβολικά κόστη» καθυστερώντας την εισαγωγή. Αυτό μπορεί επίσης να λυθεί με καλύτερους τρόπους από μια άνευ όρων τοπική εισαγωγή (αποθηκεύστε το module ως χαρακτηριστικό κλάσης ή module και κάντε την εισαγωγή μόνο στην πρώτη χρήση).

Ανεξάρτητα από αυτό, υπάρχει ένας τρόπος να χρησιμοποιήσετε το @code{mock} για να επηρεάσετε τα αποτελέσματα μιας εισαγωγής. Η εισαγωγή ανακτά ένα `αντικείμενο' από το λεξικό @ref{19ba,,sys.modules}. Σημειώστε ότι ανακτά ένα `αντικείμενο', το οποίο δεν χρειάζεται να είναι ένα module. Η εισαγωγή ενός module για πρώτη φορά έχει ως αποτέλεσμα τη τοποθέτηση ενός αντικειμένου module στο @code{sys.modules}, οπότε συνήθως όταν εισάγετε κάτι, λαμβάνετε πίσω ένα module. Ωστόσο, αυτό δεν χρειάζεται να είναι η περίπτωση.

Αυτό σημαίνει ότι μπορείτε να χρησιμοποιήσετε το @ref{1b7a,,patch.dict()} για να τοποθετήσετε `προσωρινά' μια προσομοίωση στο @ref{19ba,,sys.modules}. Οποιεσδήποτε εισαγωγές ενώ αυτή η επιδιόρθωση είναι ενεργή θα ανακτούν την προσομοίωση. Όταν ολοκληρωθεί η επιδιόρθωση (η διακοσμημένη συνάρτηση εξέρχεται, το σώμα της δήλωσης with ολοκληρώνεται ή καλείται το @code{patcher.stop()}), τότε ό,τι υπήρχε προηγουμένως θα αποκατασταθεί με ασφάλεια.

Εδώ είναι ένα παράδειγμα που προσομοιώνει το module “fooble”.

@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

Όπως μπορείτε να δείτε, το @code{import fooble} πετυχαίνει, αλλά κατά την έξοδο δεν παραμένει κανένα “fooble” στο @ref{19ba,,sys.modules}.

Αυτό λειτουργεί επίσης για τη μορφή @code{from module import name}:

@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

Με λίγη περισσότερη δουλειά, μπορείτε επίσης να προσομοιώσετε εισαγωγές πακέτων:

@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 Παρακολούθηση της σειράς κλήσεων και λιγότερο λεκτικές δηλώσεις κλήσεων,Πιο σύνθετη αντιστοίχιση ορισμάτων,Προσομοίωση εισαγωγών με το patch dict,Further examples
@anchor{library/unittest mock-examples tracking-order-of-calls-and-less-verbose-call-assertions}@anchor{48eb}
@subsubsection Παρακολούθηση της σειράς κλήσεων και λιγότερο λεκτικές δηλώσεις κλήσεων


Η @ref{e0e,,Mock} σας επιτρέπει να παρακολουθείτε τη `σειρά' των κλήσεων μεθόδων στις προσομοιώσεις σας μέσω του χαρακτηριστικού @ref{4890,,method_calls}. Αυτό δεν σας επιτρέπει να παρακολουθείτε τη σειρά των κλήσεων μεταξύ ξεχωριστών αντικειμένων προσομοίωσης, ωστόσο μπορούμε να χρησιμοποιήσουμε το @ref{488e,,mock_calls} για να επιτύχουμε το ίδιο αποτέλεσμα.

Επειδή οι προσομοιώσεις παρακολουθούν τις κλήσεις σε υπο-προσομοιώσεις στο @code{mock_calls}, και η πρόσβαση σε ένα αυθαίρετο χαρακτηριστικό μιας προσομοίωσης δημιουργεί μια υπο-προσομοίωση, μπορούμε να δημιουργήσουμε τις ξεχωριστές προσομοιώσεις μας από μια γονική. Οι κλήσεις σε αυτές τις υπο-προσομοιώσεις θα καταγράφονται στη συνέχεια, με σειρά, στο @code{mock_calls} της γονικής:

@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

Μπορούμε στη συνέχεια να κάνουμε δηλώσεις σχετικά με τις κλήσεις, συμπεριλαμβανομένης της σειράς, συγκρίνοντας με το χαρακτηριστικό @code{mock_calls} στην προσομοίωση διαχειριστή:

@example
>>> expected_calls = [call.foo.something(), call.bar.other.thing()]
>>> manager.mock_calls == expected_calls
True
@end example

Αν το @code{patch} δημιουργεί και τοποθετεί τις προσομοιώσεις σας, τότε μπορείτε να τις επισυνάψετε σε μια διαχειριστική προσομοίωση χρησιμοποιώντας τη μέθοδο @ref{1b69,,attach_mock()}. Μετά την επισύναψη, οι κλήσεις θα καταγράφονται στο @code{mock_calls} του διαχειριστή.

@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

Εάν έχουν γίνει πολλές κλήσεις, αλλά σας ενδιαφέρει μόνο μια συγκεκριμένη ακολουθία από αυτές, τότε μια εναλλακτική είναι να χρησιμοποιήσετε τη μέθοδο @ref{1c2a,,assert_has_calls()}. Αυτή λαμβάνει μια λίστα κλήσεων (κατασκευασμένη με το @ref{1fa3,,call} αντικείμενο). Εάν αυτή η ακολουθία κλήσεων βρίσκεται στο @ref{488e,,mock_calls}, τότε η δήλωση πετυχαίνει.

@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

Ακόμα κι αν η αλυσιδωτή κλήση @code{m.one().two().three()} δεν είναι οι μόνες κλήσεις που έχουν γίνει στην προσομοίωση, η δήλωση εξακολουθεί να πετυχαίνει.

Μερικές φορές μια προσομοίωση μπορεί να έχει γίνει πολλές κλήσεις σε αυτήν, και σας ενδιαφέρει μόνο να κάνετε δηλώσεις για `μερικές' από αυτές τις κλήσεις. Μπορεί να μην σας ενδιαφέρει καν η σειρά. Σε αυτή την περίπτωση, μπορείτε να περάσετε το @code{any_order=True} στο @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 Πιο σύνθετη αντιστοίχιση ορισμάτων,,Παρακολούθηση της σειράς κλήσεων και λιγότερο λεκτικές δηλώσεις κλήσεων,Further examples
@anchor{library/unittest mock-examples more-complex-argument-matching}@anchor{48ec}
@subsubsection Πιο σύνθετη αντιστοίχιση ορισμάτων


Χρησιμοποιώντας την ίδια βασική έννοια με το @ref{1fa1,,ANY}, μπορούμε να υλοποιήσουμε αντιστοιχίσεις για να κάνουμε πιο σύνθετες δηλώσεις σχετικά με αντικείμενα που χρησιμοποιούνται ως ορίσματα σε προσομοιώσεις.

Ας υποθέσουμε ότι αναμένουμε να περαστεί κάποιο αντικείμενο σε μια προσομοίωση που κανονικά συγκρίνεται ως ίσο βάσει της ταυτότητας του αντικειμένου (που είναι το προεπιλεγμένο της Python για καθορισμένες από τον χρήστη κλάσεις). Για να χρησιμοποιήσουμε τη @ref{1ff2,,assert_called_with()}, θα πρέπει να περάσουμε το ακριβώς ίδιο αντικείμενο. Εάν μας ενδιαφέρουν μόνο μερικά από τα χαρακτηριστικά αυτού του αντικειμένου, τότε μπορούμε να δημιουργήσουμε έναν αντιστοιχιστή που θα ελέγχει αυτά τα χαρακτηριστικά για εμάς.

Μπορείτε να δείτε σε αυτό το παράδειγμα πώς μια “τυπική” κλήση στο @code{assert_called_with} δεν είναι επαρκής:

@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

Μια συνάρτηση σύγκρισης για την κλάση μας @code{Foo} μπορεί να μοιάζει κάπως έτσι:

@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

Και ένα αντικείμενο αντιστοίχισης που μπορεί να χρησιμοποιεί συναρτήσεις σύγκρισης όπως αυτή για τη λειτουργία ισότητας του θα μοιάζει κάπως έτσι:

@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

Βάζοντας όλα αυτά μαζί:

@example
>>> match_foo = Matcher(compare, Foo(1, 2))
>>> mock.assert_called_with(match_foo)
@end example

Το @code{Matcher} δημιουργείται με τη συνάρτηση σύγκρισης και το αντικείμενο που θέλουμε να συγκρίνουμε. Στο @code{assert_called_with}, θα κληθεί η μέθοδος ισότητας του @code{Matcher}, η οποία συγκρίνει το αντικείμενο με το οποίο κλήθηκε η προσομοίωση με αυτό που δημιουργήσαμε τον αντιστοιχιστή μας. Εάν ταιριάζουν, τότε το @code{assert_called_with} περνάει, και αν δεν ταιριάζουν, γίνεται raise μια @ref{a97,,AssertionError}:

@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

Με λίγη τροποποίηση, θα μπορούσατε να κάνετε τη συνάρτηση σύγκρισης να κάνει raise απευθείας την @ref{a97,,AssertionError} και να παρέχει ένα πιο χρήσιμο μήνυμα αποτυχίας.

Από την έκδοση 1.5, η βιβλιοθήκη δοκιμών Python PyHamcrest@footnote{https://pyhamcrest.readthedocs.io/} παρέχει παρόμοια λειτουργικότητα, που μπορεί να είναι χρήσιμη εδώ, με τη μορφή του αντιστοιχιστή ισότητας (hamcrest.library.integration.match_equality@footnote{https://pyhamcrest.readthedocs.io/en/release-1.8/integration/#module-hamcrest.library.integration.match_equality}).

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node test — Regression tests package for Python,test support — Utilities for the Python test suite,unittest mock — ξεκινώντας,Εργαλεία Ανάπτυξης
@anchor{library/test doc}@anchor{48ed}@anchor{library/test module-test}@anchor{eb}@anchor{library/test test-regression-tests-package-for-python}@anchor{48ee}@anchor{library/test translation-repo}@anchor{48ef}
@subsection @code{test} — Regression tests package for Python


@geindex module; test

@cartouche
@quotation Σημείωση 
The @code{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 @code{test} package contains all regression tests for Python as well as the
modules @ref{ed,,test.support} and @ref{ec,,test.regrtest}.
@code{test.support} is used to enhance your tests while
@code{test.regrtest} drives the testing suite.

Each module in the @code{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{10f,,unittest} or @ref{3d,,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 Δείτε επίσης



@table @asis

@item Module @ref{10f,,unittest}

Writing PyUnit regression tests.

@item Module @ref{3d,,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{48f0}@anchor{library/test writing-unit-tests-for-the-test-package}@anchor{48f1}
@subsubsection Writing Unit Tests for the @code{test} package


It is preferred that tests that use the @ref{10f,,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{ec,,test.regrtest},
on its own as a script that supports the @ref{10f,,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{52f,,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 @code{unittest.TestCase}.
@end itemize


@subsubheading Δείτε επίσης



@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{ec}@anchor{library/test regrtest}@anchor{13b2}@anchor{library/test running-tests-using-the-command-line-interface}@anchor{48f2}
@subsubsection Running tests using the command-line interface


@geindex module; test.regrtest

The @code{test} package can be run as a script to drive Python’s regression
test suite, thanks to the @ref{4ca,,-m} option: @code{python -m test}. Under
the hood, it uses @code{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
@code{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 @code{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 @code{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.


Added in version 3.14: Output is colorized by default and can be
@ref{1af,,controlled using environment variables}.


@node test support — Utilities for the Python test suite,test support socket_helper — Utilities for socket tests,test — Regression tests package for Python,Εργαλεία Ανάπτυξης
@anchor{library/test module-test support}@anchor{ed}@anchor{library/test test-support-utilities-for-the-python-test-suite}@anchor{48f3}
@subsection @code{test.support} — Utilities for the Python test suite


@geindex module; test.support

The @code{test.support} module provides support for Python’s regression
test suite.

@cartouche
@quotation Σημείωση 
@code{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{48f4}
@deffn {Εξαίρεση} test.support.TestFailed

Exception to be raised when a test fails. This is deprecated in favor of
@ref{10f,,unittest}-based tests and @ref{52f,,unittest.TestCase}’s assertion
methods.
@end deffn

@geindex ResourceDenied
@anchor{library/test test support ResourceDenied}@anchor{48f5}
@deffn {Εξαίρεση} test.support.ResourceDenied

Subclass of @ref{138d,,unittest.SkipTest}. Raised when a resource (such as a
network connection) is not available. Raised by the @ref{48f6,,requires()}
function.
@end deffn

The @code{test.support} module defines the following constants:

@geindex verbose (στη μονάδα test.support)
@anchor{library/test test support verbose}@anchor{48f7}
@deffn {Δεδομένα} 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{ec,,test.regrtest}.
@end deffn

@geindex is_jython (στη μονάδα test.support)
@anchor{library/test test support is_jython}@anchor{48f8}
@deffn {Δεδομένα} test.support.is_jython

@code{True} if the running interpreter is Jython.
@end deffn

@geindex is_android (στη μονάδα test.support)
@anchor{library/test test support is_android}@anchor{48f9}
@deffn {Δεδομένα} test.support.is_android

@code{True} if @code{sys.platform} is @code{android}.
@end deffn

@geindex is_emscripten (στη μονάδα test.support)
@anchor{library/test test support is_emscripten}@anchor{48fa}
@deffn {Δεδομένα} test.support.is_emscripten

@code{True} if @code{sys.platform} is @code{emscripten}.
@end deffn

@geindex is_wasi (στη μονάδα test.support)
@anchor{library/test test support is_wasi}@anchor{48fb}
@deffn {Δεδομένα} test.support.is_wasi

@code{True} if @code{sys.platform} is @code{wasi}.
@end deffn

@geindex is_apple_mobile (στη μονάδα test.support)
@anchor{library/test test support is_apple_mobile}@anchor{48fc}
@deffn {Δεδομένα} test.support.is_apple_mobile

@code{True} if @code{sys.platform} is @code{ios}, @code{tvos}, or @code{watchos}.
@end deffn

@geindex is_apple (στη μονάδα test.support)
@anchor{library/test test support is_apple}@anchor{48fd}
@deffn {Δεδομένα} test.support.is_apple

@code{True} if @code{sys.platform} is @code{darwin} or @code{is_apple_mobile} is @code{True}.
@end deffn

@geindex unix_shell (στη μονάδα test.support)
@anchor{library/test test support unix_shell}@anchor{48fe}
@deffn {Δεδομένα} test.support.unix_shell

Path for shell if not on Windows; otherwise @code{None}.
@end deffn

@geindex LOOPBACK_TIMEOUT (στη μονάδα test.support)
@anchor{library/test test support LOOPBACK_TIMEOUT}@anchor{1f8d}
@deffn {Δεδομένα} 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{115c,,connect()},
@ref{115d,,recv()} and @ref{1160,,send()} methods of
@ref{115a,,socket.socket}.

Its default value is 5 seconds.

See also @ref{1f8e,,INTERNET_TIMEOUT}.
@end deffn

@geindex INTERNET_TIMEOUT (στη μονάδα test.support)
@anchor{library/test test support INTERNET_TIMEOUT}@anchor{1f8e}
@deffn {Δεδομένα} 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 @code{INTERNET_TIMEOUT} should not mark a test as
failed, but skip the test instead: see
@ref{48ff,,transient_internet()}.

Its default value is 1 minute.

See also @ref{1f8d,,LOOPBACK_TIMEOUT}.
@end deffn

@geindex SHORT_TIMEOUT (στη μονάδα test.support)
@anchor{library/test test support SHORT_TIMEOUT}@anchor{1e5a}
@deffn {Δεδομένα} 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 @code{SHORT_TIMEOUT} starts to fail randomly on slow
buildbots, use @ref{1f8f,,LONG_TIMEOUT} instead.

Its default value is 30 seconds.
@end deffn

@geindex LONG_TIMEOUT (στη μονάδα test.support)
@anchor{library/test test support LONG_TIMEOUT}@anchor{1f8f}
@deffn {Δεδομένα} 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{1f8d,,LOOPBACK_TIMEOUT}, @ref{1f8e,,INTERNET_TIMEOUT} and
@ref{1e5a,,SHORT_TIMEOUT}.
@end deffn

@geindex PGO (στη μονάδα test.support)
@anchor{library/test test support PGO}@anchor{4900}
@deffn {Δεδομένα} test.support.PGO

Set when tests can be skipped when they are not useful for PGO.
@end deffn

@geindex PIPE_MAX_SIZE (στη μονάδα test.support)
@anchor{library/test test support PIPE_MAX_SIZE}@anchor{4901}
@deffn {Δεδομένα} 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 (στη μονάδα test.support)
@anchor{library/test test support Py_DEBUG}@anchor{4902}
@deffn {Δεδομένα} test.support.Py_DEBUG

@code{True} if Python was built with the @ref{19eb,,Py_DEBUG} macro
defined, that is, if
Python was @ref{3dc,,built in debug mode}.


Added in version 3.12.

@end deffn

@geindex SOCK_MAX_SIZE (στη μονάδα test.support)
@anchor{library/test test support SOCK_MAX_SIZE}@anchor{4903}
@deffn {Δεδομένα} 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 (στη μονάδα test.support)
@anchor{library/test test support TEST_SUPPORT_DIR}@anchor{4904}
@deffn {Δεδομένα} test.support.TEST_SUPPORT_DIR

Set to the top level directory that contains @code{test.support}.
@end deffn

@geindex TEST_HOME_DIR (στη μονάδα test.support)
@anchor{library/test test support TEST_HOME_DIR}@anchor{4905}
@deffn {Δεδομένα} test.support.TEST_HOME_DIR

Set to the top level directory for the test package.
@end deffn

@geindex TEST_DATA_DIR (στη μονάδα test.support)
@anchor{library/test test support TEST_DATA_DIR}@anchor{4906}
@deffn {Δεδομένα} test.support.TEST_DATA_DIR

Set to the @code{data} directory within the test package.
@end deffn

@geindex MAX_Py_ssize_t (στη μονάδα test.support)
@anchor{library/test test support MAX_Py_ssize_t}@anchor{4907}
@deffn {Δεδομένα} test.support.MAX_Py_ssize_t

Set to @ref{156e,,sys.maxsize} for big memory tests.
@end deffn

@geindex max_memuse (στη μονάδα test.support)
@anchor{library/test test support max_memuse}@anchor{4908}
@deffn {Δεδομένα} test.support.max_memuse

Set by @ref{4909,,set_memlimit()} as the memory limit for big memory tests.
Limited by @ref{4907,,MAX_Py_ssize_t}.
@end deffn

@geindex real_max_memuse (στη μονάδα test.support)
@anchor{library/test test support real_max_memuse}@anchor{490a}
@deffn {Δεδομένα} test.support.real_max_memuse

Set by @ref{4909,,set_memlimit()} as the memory limit for big memory tests.  Not
limited by @ref{4907,,MAX_Py_ssize_t}.
@end deffn

@geindex MISSING_C_DOCSTRINGS (στη μονάδα test.support)
@anchor{library/test test support MISSING_C_DOCSTRINGS}@anchor{490b}
@deffn {Δεδομένα} 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{238e,,configure --without-doc-strings} option.

See also the @ref{490c,,HAVE_DOCSTRINGS} variable.
@end deffn

@geindex HAVE_DOCSTRINGS (στη μονάδα test.support)
@anchor{library/test test support HAVE_DOCSTRINGS}@anchor{490c}
@deffn {Δεδομένα} test.support.HAVE_DOCSTRINGS

Set to @code{True} if function docstrings are available.
See the @ref{431,,python -OO} option, which strips docstrings of functions implemented in Python.

See also the @ref{490b,,MISSING_C_DOCSTRINGS} variable.
@end deffn

@geindex TEST_HTTP_URL (στη μονάδα test.support)
@anchor{library/test test support TEST_HTTP_URL}@anchor{490d}
@deffn {Δεδομένα} test.support.TEST_HTTP_URL

Define the URL of a dedicated HTTP server for the network tests.
@end deffn

@geindex ALWAYS_EQ (στη μονάδα test.support)
@anchor{library/test test support ALWAYS_EQ}@anchor{490e}
@deffn {Δεδομένα} test.support.ALWAYS_EQ

Object that is equal to anything.  Used to test mixed type comparison.
@end deffn

@geindex NEVER_EQ (στη μονάδα test.support)
@anchor{library/test test support NEVER_EQ}@anchor{490f}
@deffn {Δεδομένα} test.support.NEVER_EQ

Object that is not equal to anything (even to @ref{490e,,ALWAYS_EQ}).
Used to test mixed type comparison.
@end deffn

@geindex LARGEST (στη μονάδα test.support)
@anchor{library/test test support LARGEST}@anchor{4910}
@deffn {Δεδομένα} test.support.LARGEST

Object that is greater than anything (except itself).
Used to test mixed type comparison.
@end deffn

@geindex SMALLEST (στη μονάδα test.support)
@anchor{library/test test support SMALLEST}@anchor{4911}
@deffn {Δεδομένα} test.support.SMALLEST

Object that is less than anything (except itself).
Used to test mixed type comparison.
@end deffn

The @code{test.support} module defines the following functions:

@geindex busy_retry() (στη μονάδα test.support)
@anchor{library/test test support busy_retry}@anchor{4912}
@deffn {Συνάρτηση} 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{a97,,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() (στη μονάδα test.support)
@anchor{library/test test support sleeping_retry}@anchor{4913}
@deffn {Συνάρτηση} 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{4912,,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() (στη μονάδα test.support)
@anchor{library/test test support is_resource_enabled}@anchor{4914}
@deffn {Συνάρτηση} 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{ec,,test.regrtest} is executing the
tests.
@end deffn

@geindex get_resource_value() (στη μονάδα test.support)
@anchor{library/test test support get_resource_value}@anchor{4915}
@deffn {Συνάρτηση} test.support.get_resource_value (resource)

Return the value specified for `resource' (as @code{-u @var{resource}=@var{value}}).
Return @code{None} if `resource' is disabled or no value is specified.
@end deffn

@geindex python_is_optimized() (στη μονάδα test.support)
@anchor{library/test test support python_is_optimized}@anchor{4916}
@deffn {Συνάρτηση} test.support.python_is_optimized ()

Return @code{True} if Python was not built with @code{-O0} or @code{-Og}.
@end deffn

@geindex with_pymalloc() (στη μονάδα test.support)
@anchor{library/test test support with_pymalloc}@anchor{4917}
@deffn {Συνάρτηση} test.support.with_pymalloc ()

Return @code{_testcapi.WITH_PYMALLOC}.
@end deffn

@geindex requires() (στη μονάδα test.support)
@anchor{library/test test support requires}@anchor{48f6}
@deffn {Συνάρτηση} test.support.requires (resource, msg=None)

Raise @ref{48f5,,ResourceDenied} if `resource' is not available. `msg' is the
argument to @code{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{ec,,test.regrtest}.
@end deffn

@geindex sortdict() (στη μονάδα test.support)
@anchor{library/test test support sortdict}@anchor{4918}
@deffn {Συνάρτηση} test.support.sortdict (dict)

Return a repr of `dict' with keys sorted.
@end deffn

@geindex findfile() (στη μονάδα test.support)
@anchor{library/test test support findfile}@anchor{4919}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support)
@anchor{library/test test support get_pagesize}@anchor{491a}
@deffn {Συνάρτηση} test.support.get_pagesize ()

Get size of a page in bytes.


Added in version 3.12.

@end deffn

@geindex setswitchinterval() (στη μονάδα test.support)
@anchor{library/test test support setswitchinterval}@anchor{491b}
@deffn {Συνάρτηση} test.support.setswitchinterval (interval)

Set the @ref{d16,,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() (στη μονάδα test.support)
@anchor{library/test test support check_impl_detail}@anchor{491c}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support)
@anchor{library/test test support set_memlimit}@anchor{4909}
@deffn {Συνάρτηση} test.support.set_memlimit (limit)

Set the values for @ref{4908,,max_memuse} and @ref{490a,,real_max_memuse} for big
memory tests.
@end deffn

@geindex record_original_stdout() (στη μονάδα test.support)
@anchor{library/test test support record_original_stdout}@anchor{491d}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support)
@anchor{library/test test support get_original_stdout}@anchor{491e}
@deffn {Συνάρτηση} test.support.get_original_stdout ()

Return the original stdout set by @ref{491d,,record_original_stdout()} or
@code{sys.stdout} if it’s not set.
@end deffn

@geindex args_from_interpreter_flags() (στη μονάδα test.support)
@anchor{library/test test support args_from_interpreter_flags}@anchor{491f}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support)
@anchor{library/test test support optim_args_from_interpreter_flags}@anchor{4920}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support)
@geindex captured_stdout() (στη μονάδα test.support)
@geindex captured_stderr() (στη μονάδα test.support)
@anchor{library/test test support captured_stdin}@anchor{4921}
@deffn {Συνάρτηση} test.support.captured_stdin ()
@anchor{library/test test support captured_stdout}@anchor{4922}
@deffnx {Συνάρτηση} test.support.captured_stdout ()
@anchor{library/test test support captured_stderr}@anchor{1fc7}
@deffnx {Συνάρτηση} test.support.captured_stderr ()

A context managers that temporarily replaces the named stream with
@ref{12d4,,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() (στη μονάδα test.support)
@anchor{library/test test support disable_faulthandler}@anchor{4923}
@deffn {Συνάρτηση} test.support.disable_faulthandler ()

A context manager that temporary disables @ref{5b,,faulthandler}.
@end deffn

@geindex gc_collect() (στη μονάδα test.support)
@anchor{library/test test support gc_collect}@anchor{4924}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support)
@anchor{library/test test support disable_gc}@anchor{4925}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support)
@anchor{library/test test support swap_attr}@anchor{4926}
@deffn {Συνάρτηση} test.support.swap_attr (obj, attr, new_val)

Context manager to swap out an attribute with a new object.

Usage:

@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() (στη μονάδα test.support)
@anchor{library/test test support swap_item}@anchor{4927}
@deffn {Συνάρτηση} test.support.swap_item (obj, attr, new_val)

Context manager to swap out an item with a new object.

Usage:

@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() (στη μονάδα test.support)
@anchor{library/test test support flush_std_streams}@anchor{4928}
@deffn {Συνάρτηση} test.support.flush_std_streams ()

Call the @code{flush()} method on @ref{e9c,,sys.stdout} and then on
@ref{d05,,sys.stderr}. It can be used to make sure that the logs order is
consistent before writing into stderr.


Added in version 3.11.

@end deffn

@geindex print_warning() (στη μονάδα test.support)
@anchor{library/test test support print_warning}@anchor{4929}
@deffn {Συνάρτηση} test.support.print_warning (msg)

Print a warning into @ref{492a,,sys.__stderr__}. Format the message as:
@code{f"Warning -- @{msg@}"}. If `msg' is made of multiple lines, add
@code{"Warning -- "} prefix to each line.


Added in version 3.9.

@end deffn

@geindex wait_process() (στη μονάδα test.support)
@anchor{library/test test support wait_process}@anchor{1f51}
@deffn {Συνάρτηση} 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{a97,,AssertionError} if the process exit code is not equal to
`exitcode'.

If the process runs longer than `timeout' seconds (@ref{1e5a,,SHORT_TIMEOUT} by
default), kill the process and raise an @ref{a97,,AssertionError}. The timeout
feature is not available on Windows.


Added in version 3.9.

@end deffn

@geindex calcobjsize() (στη μονάδα test.support)
@anchor{library/test test support calcobjsize}@anchor{492b}
@deffn {Συνάρτηση} test.support.calcobjsize (fmt)

Return the size of the @ref{19b,,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() (στη μονάδα test.support)
@anchor{library/test test support calcvobjsize}@anchor{492c}
@deffn {Συνάρτηση} test.support.calcvobjsize (fmt)

Return the size of the @ref{492d,,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() (στη μονάδα test.support)
@anchor{library/test test support checksizeof}@anchor{492e}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support)
@anchor{library/test test support anticipate_failure}@anchor{492f}
@deffn {Συνάρτηση} @@test.support.anticipate_failure (condition)

A decorator to conditionally mark tests with
@ref{483f,,unittest.expectedFailure()}. Any use of this decorator should
have an associated comment identifying the relevant tracker issue.
@end deffn

@geindex system_must_validate_cert() (στη μονάδα test.support)
@anchor{library/test test support system_must_validate_cert}@anchor{4930}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support)
@anchor{library/test test support run_with_locale}@anchor{4931}
@deffn {Συνάρτηση} @@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() (στη μονάδα test.support)
@anchor{library/test test support run_with_tz}@anchor{4932}
@deffn {Συνάρτηση} @@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() (στη μονάδα test.support)
@anchor{library/test test support requires_freebsd_version}@anchor{4933}
@deffn {Συνάρτηση} @@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() (στη μονάδα test.support)
@anchor{library/test test support requires_linux_version}@anchor{4934}
@deffn {Συνάρτηση} @@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() (στη μονάδα test.support)
@anchor{library/test test support requires_mac_version}@anchor{4935}
@deffn {Συνάρτηση} @@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() (στη μονάδα test.support)
@anchor{library/test test support requires_gil_enabled}@anchor{4936}
@deffn {Συνάρτηση} @@test.support.requires_gil_enabled

Decorator for skipping tests on the free-threaded build.  If the
@ref{411,,GIL} is disabled, the test is skipped.
@end deffn

@geindex requires_IEEE_754() (στη μονάδα test.support)
@anchor{library/test test support requires_IEEE_754}@anchor{4937}
@deffn {Συνάρτηση} @@test.support.requires_IEEE_754

Decorator for skipping tests on non-IEEE 754 platforms.
@end deffn

@geindex requires_zlib() (στη μονάδα test.support)
@anchor{library/test test support requires_zlib}@anchor{4938}
@deffn {Συνάρτηση} @@test.support.requires_zlib

Decorator for skipping tests if @ref{13c,,zlib} doesn’t exist.
@end deffn

@geindex requires_gzip() (στη μονάδα test.support)
@anchor{library/test test support requires_gzip}@anchor{4939}
@deffn {Συνάρτηση} @@test.support.requires_gzip

Decorator for skipping tests if @ref{6a,,gzip} doesn’t exist.
@end deffn

@geindex requires_bz2() (στη μονάδα test.support)
@anchor{library/test test support requires_bz2}@anchor{493a}
@deffn {Συνάρτηση} @@test.support.requires_bz2

Decorator for skipping tests if @ref{14,,bz2} doesn’t exist.
@end deffn

@geindex requires_lzma() (στη μονάδα test.support)
@anchor{library/test test support requires_lzma}@anchor{493b}
@deffn {Συνάρτηση} @@test.support.requires_lzma

Decorator for skipping tests if @ref{8d,,lzma} doesn’t exist.
@end deffn

@geindex requires_resource() (στη μονάδα test.support)
@anchor{library/test test support requires_resource}@anchor{493c}
@deffn {Συνάρτηση} @@test.support.requires_resource (resource)

Decorator for skipping tests if `resource' is not available.
@end deffn

@geindex requires_docstrings() (στη μονάδα test.support)
@anchor{library/test test support requires_docstrings}@anchor{493d}
@deffn {Συνάρτηση} @@test.support.requires_docstrings

Decorator for only running the test if @ref{490c,,HAVE_DOCSTRINGS}.
@end deffn

@geindex requires_limited_api() (στη μονάδα test.support)
@anchor{library/test test support requires_limited_api}@anchor{493e}
@deffn {Συνάρτηση} @@test.support.requires_limited_api

Decorator for only running the test if @ref{829,,Limited C API}
is available.
@end deffn

@geindex cpython_only() (στη μονάδα test.support)
@anchor{library/test test support cpython_only}@anchor{493f}
@deffn {Συνάρτηση} @@test.support.cpython_only

Decorator for tests only applicable to CPython.
@end deffn

@geindex impl_detail() (στη μονάδα test.support)
@anchor{library/test test support impl_detail}@anchor{4940}
@deffn {Συνάρτηση} @@test.support.impl_detail (msg=None, **guards)

Decorator for invoking @ref{491c,,check_impl_detail()} on `guards'.  If that
returns @code{False}, then uses `msg' as the reason for skipping the test.
@end deffn

@geindex thread_unsafe() (στη μονάδα test.support)
@anchor{library/test test support thread_unsafe}@anchor{4941}
@deffn {Συνάρτηση} @@test.support.thread_unsafe (reason=None)

Decorator for marking tests as thread-unsafe.  This test always runs in one
thread even when invoked with @code{--parallel-threads}.
@end deffn

@geindex no_tracing() (στη μονάδα test.support)
@anchor{library/test test support no_tracing}@anchor{4942}
@deffn {Συνάρτηση} @@test.support.no_tracing

Decorator to temporarily turn off tracing for the duration of the test.
@end deffn

@geindex refcount_test() (στη μονάδα test.support)
@anchor{library/test test support refcount_test}@anchor{4943}
@deffn {Συνάρτηση} @@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() (στη μονάδα test.support)
@anchor{library/test test support bigmemtest}@anchor{4944}
@deffn {Συνάρτηση} @@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() (στη μονάδα test.support)
@anchor{library/test test support bigaddrspacetest}@anchor{4945}
@deffn {Συνάρτηση} @@test.support.bigaddrspacetest

Decorator for tests that fill the address space.
@end deffn

@geindex linked_to_musl() (στη μονάδα test.support)
@anchor{library/test test support linked_to_musl}@anchor{4946}
@deffn {Συνάρτηση} test.support.linked_to_musl ()

Return @code{False} if there is no evidence the interpreter was compiled with
@code{musl}, otherwise return a version triple, either @code{(0, 0, 0)} if the
version is unknown, or the actual version if it is known.  Intended for use
in @code{skip} decorators.  @code{emscripten} and @code{wasi} are assumed to be
compiled with @code{musl}; otherwise @code{platform.libc_ver} is checked.
@end deffn

@geindex check_syntax_error() (στη μονάδα test.support)
@anchor{library/test test support check_syntax_error}@anchor{4947}
@deffn {Συνάρτηση} 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{10f,,unittest} instance for the test.  `errtext' is the
regular expression which should match the string representation of the
raised @ref{17e,,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() (στη μονάδα test.support)
@anchor{library/test test support open_urlresource}@anchor{4948}
@deffn {Συνάρτηση} test.support.open_urlresource (url, *args, **kw)

Open `url'.  If open fails, raises @ref{48f4,,TestFailed}.
@end deffn

@geindex reap_children() (στη μονάδα test.support)
@anchor{library/test test support reap_children}@anchor{4949}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support)
@anchor{library/test test support get_attribute}@anchor{494a}
@deffn {Συνάρτηση} test.support.get_attribute (obj, name)

Get an attribute, raising @ref{138d,,unittest.SkipTest} if @ref{1a9,,AttributeError}
is raised.
@end deffn

@geindex catch_unraisable_exception() (στη μονάδα test.support)
@anchor{library/test test support catch_unraisable_exception}@anchor{1fad}
@deffn {Συνάρτηση} test.support.catch_unraisable_exception ()

Context manager catching unraisable exception using
@ref{70c,,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.

Usage:

@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


Added in version 3.8.

@end deffn

@geindex load_package_tests() (στη μονάδα test.support)
@anchor{library/test test support load_package_tests}@anchor{494b}
@deffn {Συνάρτηση} test.support.load_package_tests (pkg_dir, loader, standard_tests, pattern)

Generic implementation of the @ref{10f,,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() (στη μονάδα test.support)
@anchor{library/test test support detect_api_mismatch}@anchor{494c}
@deffn {Συνάρτηση} 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 “__”.


Added in version 3.5.

@end deffn

@geindex patch() (στη μονάδα test.support)
@anchor{library/test test support patch}@anchor{494d}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support)
@anchor{library/test test support run_in_subinterp}@anchor{494e}
@deffn {Συνάρτηση} test.support.run_in_subinterp (code)

Run `code' in subinterpreter.  Raise @ref{138d,,unittest.SkipTest} if
@ref{108,,tracemalloc} is enabled.
@end deffn

@geindex check_free_after_iterating() (στη μονάδα test.support)
@anchor{library/test test support check_free_after_iterating}@anchor{494f}
@deffn {Συνάρτηση} test.support.check_free_after_iterating (test, iter, cls, args=())

Assert instances of `cls' are deallocated after iterating.
@end deffn

@geindex missing_compiler_executable() (στη μονάδα test.support)
@anchor{library/test test support missing_compiler_executable}@anchor{4950}
@deffn {Συνάρτηση} 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__() (στη μονάδα test.support)
@anchor{library/test test support check__all__}@anchor{1f27}
@deffn {Συνάρτηση} 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{28d3,,__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


Added in version 3.6.

@end deffn

@geindex skip_if_broken_multiprocessing_synchronize() (στη μονάδα test.support)
@anchor{library/test test support skip_if_broken_multiprocessing_synchronize}@anchor{1f28}
@deffn {Συνάρτηση} 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{53c,,OSError}.


Added in version 3.10.

@end deffn

@geindex check_disallow_instantiation() (στη μονάδα test.support)
@anchor{library/test test support check_disallow_instantiation}@anchor{4951}
@deffn {Συνάρτηση} test.support.check_disallow_instantiation (test_case, tp, *args, **kwds)

Assert that type `tp' cannot be instantiated using `args' and `kwds'.


Added in version 3.10.

@end deffn

@geindex adjust_int_max_str_digits() (στη μονάδα test.support)
@anchor{library/test test support adjust_int_max_str_digits}@anchor{4952}
@deffn {Συνάρτηση} test.support.adjust_int_max_str_digits (max_digits)

This function returns a context manager that will change the global
@ref{1b11,,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.


Added in version 3.11.

@end deffn

The @code{test.support} module defines the following classes:

@geindex SuppressCrashReport (κλάση σε test.support)
@anchor{library/test test support SuppressCrashReport}@anchor{4953}
@deffn {Κλάση} 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{3e7,,resource.setrlimit()} is used to set
@ref{4954,,resource.RLIMIT_CORE}’s soft limit to 0 to prevent coredump file
creation.

On both platforms, the old value is restored by @ref{16a5,,__exit__()}.
@end deffn

@geindex SaveSignals (κλάση σε test.support)
@anchor{library/test test support SaveSignals}@anchor{4955}
@deffn {Κλάση} test.support.SaveSignals

Class to save and restore signal handlers registered by the Python signal
handler.

@geindex save() (μέθοδος της test.support.SaveSignals)
@anchor{library/test test support SaveSignals save}@anchor{4956}
@deffn {Μέθοδος} save (self)

Save the signal handlers to a dictionary mapping signal numbers to the
current signal handler.
@end deffn

@geindex restore() (μέθοδος της test.support.SaveSignals)
@anchor{library/test test support SaveSignals restore}@anchor{4957}
@deffn {Μέθοδος} restore (self)

Set the signal numbers from the @ref{4956,,save()} dictionary to the saved
handler.
@end deffn
@end deffn

@geindex Matcher (κλάση σε test.support)
@anchor{library/test test support Matcher}@anchor{4958}
@deffn {Κλάση} test.support.Matcher

@geindex matches() (μέθοδος της test.support.Matcher)
@anchor{library/test test support Matcher matches}@anchor{4959}
@deffn {Μέθοδος} matches (self, d, **kwargs)

Try to match a single dict with the supplied arguments.
@end deffn

@geindex match_value() (μέθοδος της test.support.Matcher)
@anchor{library/test test support Matcher match_value}@anchor{495a}
@deffn {Μέθοδος} 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,Εργαλεία Ανάπτυξης
@anchor{library/test module-test support socket_helper}@anchor{f2}@anchor{library/test test-support-socket-helper-utilities-for-socket-tests}@anchor{495b}
@subsection @code{test.support.socket_helper} — Utilities for socket tests


@geindex module; test.support.socket_helper

The @code{test.support.socket_helper} module provides support for socket tests.


Added in version 3.9.


@geindex IPV6_ENABLED (στη μονάδα test.support.socket_helper)
@anchor{library/test test support socket_helper IPV6_ENABLED}@anchor{495c}
@deffn {Δεδομένα} 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() (στη μονάδα test.support.socket_helper)
@anchor{library/test test support socket_helper find_unused_port}@anchor{495d}
@deffn {Συνάρτηση} 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{1da7,,AF_INET},
@ref{1698,,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{495e,,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 @code{bind_port()} over
@code{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() (στη μονάδα test.support.socket_helper)
@anchor{library/test test support socket_helper bind_port}@anchor{495e}
@deffn {Συνάρτηση} 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{1da7,,AF_INET} and @code{sock.type} is
@ref{1698,,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() (στη μονάδα test.support.socket_helper)
@anchor{library/test test support socket_helper bind_unix_socket}@anchor{495f}
@deffn {Συνάρτηση} test.support.socket_helper.bind_unix_socket (sock, addr)

Bind a Unix socket, raising @ref{138d,,unittest.SkipTest} if
@ref{10f9,,PermissionError} is raised.
@end deffn

@geindex skip_unless_bind_unix_socket() (στη μονάδα test.support.socket_helper)
@anchor{library/test test support socket_helper skip_unless_bind_unix_socket}@anchor{4960}
@deffn {Συνάρτηση} @@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() (στη μονάδα test.support.socket_helper)
@anchor{library/test test support socket_helper transient_internet}@anchor{48ff}
@deffn {Συνάρτηση} test.support.socket_helper.transient_internet (resource_name, *, timeout=30.0, errnos=())

A context manager that raises @ref{48f5,,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,Εργαλεία Ανάπτυξης
@anchor{library/test module-test support script_helper}@anchor{f1}@anchor{library/test test-support-script-helper-utilities-for-the-python-execution-tests}@anchor{4961}
@subsection @code{test.support.script_helper} — Utilities for the Python execution tests


@geindex module; test.support.script_helper

The @code{test.support.script_helper} module provides support for Python’s
script execution tests.

@geindex interpreter_requires_environment() (στη μονάδα test.support.script_helper)
@anchor{library/test test support script_helper interpreter_requires_environment}@anchor{4962}
@deffn {Συνάρτηση} 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 μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} is one way to get most of the testsuite to run
in that situation.  
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} or 
@geindex PYTHONUSERSITE
@geindex μεταβλητή περιβάλλοντος; 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() (στη μονάδα test.support.script_helper)
@anchor{library/test test support script_helper run_python_until_end}@anchor{4963}
@deffn {Συνάρτηση} 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}.


Άλλαξε στην έκδοση 3.9: The function no longer strips whitespaces from `stderr'.

@end deffn

@geindex assert_python_ok() (στη μονάδα test.support.script_helper)
@anchor{library/test test support script_helper assert_python_ok}@anchor{4964}
@deffn {Συνάρτηση} 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}.


Άλλαξε στην έκδοση 3.9: The function no longer strips whitespaces from `stderr'.

@end deffn

@geindex assert_python_failure() (στη μονάδα test.support.script_helper)
@anchor{library/test test support script_helper assert_python_failure}@anchor{4965}
@deffn {Συνάρτηση} 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{4964,,assert_python_ok()} for more options.


Άλλαξε στην έκδοση 3.9: The function no longer strips whitespaces from `stderr'.

@end deffn

@geindex spawn_python() (στη μονάδα test.support.script_helper)
@anchor{library/test test support script_helper spawn_python}@anchor{4966}
@deffn {Συνάρτηση} 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{6bf,,subprocess.Popen()}. Returns a
@ref{6bf,,subprocess.Popen} object.
@end deffn

@geindex kill_python() (στη μονάδα test.support.script_helper)
@anchor{library/test test support script_helper kill_python}@anchor{4967}
@deffn {Συνάρτηση} test.support.script_helper.kill_python (p)

Run the given @ref{6bf,,subprocess.Popen} process until completion and return
stdout.
@end deffn

@geindex make_script() (στη μονάδα test.support.script_helper)
@anchor{library/test test support script_helper make_script}@anchor{4968}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support.script_helper)
@anchor{library/test test support script_helper make_zip_script}@anchor{4969}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support.script_helper)
@anchor{library/test test support script_helper make_pkg}@anchor{496a}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support.script_helper)
@anchor{library/test test support script_helper make_zip_pkg}@anchor{496b}
@deffn {Συνάρτηση} 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,Εργαλεία Ανάπτυξης
@anchor{library/test module-test support bytecode_helper}@anchor{ee}@anchor{library/test test-support-bytecode-helper-support-tools-for-testing-correct-bytecode-generation}@anchor{496c}
@subsection @code{test.support.bytecode_helper} — Support tools for testing correct bytecode generation


@geindex module; test.support.bytecode_helper

The @code{test.support.bytecode_helper} module provides support for testing
and inspecting bytecode generation.


Added in version 3.9.


The module defines the following class:

@geindex BytecodeTestCase (κλάση σε test.support.bytecode_helper)
@anchor{library/test test support bytecode_helper BytecodeTestCase}@anchor{496d}
@deffn {Κλάση} test.support.bytecode_helper.BytecodeTestCase (unittest.TestCase)

This class has custom assertion methods for inspecting bytecode.
@end deffn

@geindex get_disassembly_as_string() (μέθοδος της test.support.bytecode_helper.BytecodeTestCase)
@anchor{library/test test support bytecode_helper BytecodeTestCase get_disassembly_as_string}@anchor{496e}
@deffn {Μέθοδος} BytecodeTestCase.get_disassembly_as_string (co)

Return the disassembly of `co' as string.
@end deffn

@geindex assertInBytecode() (μέθοδος της test.support.bytecode_helper.BytecodeTestCase)
@anchor{library/test test support bytecode_helper BytecodeTestCase assertInBytecode}@anchor{496f}
@deffn {Μέθοδος} BytecodeTestCase.assertInBytecode (x, opname, argval=_UNSPECIFIED)

Return instr if `opname' is found, otherwise throws @ref{a97,,AssertionError}.
@end deffn

@geindex assertNotInBytecode() (μέθοδος της test.support.bytecode_helper.BytecodeTestCase)
@anchor{library/test test support bytecode_helper BytecodeTestCase assertNotInBytecode}@anchor{4970}
@deffn {Μέθοδος} BytecodeTestCase.assertNotInBytecode (x, opname, argval=_UNSPECIFIED)

Throws @ref{a97,,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,Εργαλεία Ανάπτυξης
@anchor{library/test module-test support threading_helper}@anchor{f3}@anchor{library/test test-support-threading-helper-utilities-for-threading-tests}@anchor{4971}
@subsection @code{test.support.threading_helper} — Utilities for threading tests


@geindex module; test.support.threading_helper

The @code{test.support.threading_helper} module provides support for threading tests.


Added in version 3.10.


@geindex join_thread() (στη μονάδα test.support.threading_helper)
@anchor{library/test test support threading_helper join_thread}@anchor{4972}
@deffn {Συνάρτηση} test.support.threading_helper.join_thread (thread, timeout=None)

Join a `thread' within `timeout'.  Raise an @ref{a97,,AssertionError} if thread
is still alive after `timeout' seconds.
@end deffn

@geindex reap_threads() (στη μονάδα test.support.threading_helper)
@anchor{library/test test support threading_helper reap_threads}@anchor{4973}
@deffn {Συνάρτηση} @@test.support.threading_helper.reap_threads

Decorator to ensure the threads are cleaned up even if the test fails.
@end deffn

@geindex start_threads() (στη μονάδα test.support.threading_helper)
@anchor{library/test test support threading_helper start_threads}@anchor{4974}
@deffn {Συνάρτηση} 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{387f,,threading.Event.set()}.
@code{start_threads} will attempt to join the started threads upon exit.
@end deffn

@geindex threading_cleanup() (στη μονάδα test.support.threading_helper)
@anchor{library/test test support threading_helper threading_cleanup}@anchor{4975}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support.threading_helper)
@anchor{library/test test support threading_helper threading_setup}@anchor{4976}
@deffn {Συνάρτηση} test.support.threading_helper.threading_setup ()

Return current thread count and copy of dangling threads.
@end deffn

@geindex wait_threads_exit() (στη μονάδα test.support.threading_helper)
@anchor{library/test test support threading_helper wait_threads_exit}@anchor{4977}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support.threading_helper)
@anchor{library/test test support threading_helper catch_threading_exception}@anchor{4978}
@deffn {Συνάρτηση} test.support.threading_helper.catch_threading_exception ()

Context manager catching @ref{420,,threading.Thread} exception using
@ref{c23,,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{c23,,threading.excepthook()} documentation.

These attributes are deleted at the context manager exit.

Usage:

@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


Added in version 3.8.

@end deffn

@geindex run_concurrently() (στη μονάδα test.support.threading_helper)
@anchor{library/test test support threading_helper run_concurrently}@anchor{4979}
@deffn {Συνάρτηση} test.support.threading_helper.run_concurrently (worker_func, nthreads, args=(), kwargs=@{@})

Run the worker function concurrently in multiple threads.
Re-raises an exception if any thread raises one, after all threads have
finished.
@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,Εργαλεία Ανάπτυξης
@anchor{library/test module-test support os_helper}@anchor{f0}@anchor{library/test test-support-os-helper-utilities-for-os-tests}@anchor{497a}
@subsection @code{test.support.os_helper} — Utilities for os tests


@geindex module; test.support.os_helper

The @code{test.support.os_helper} module provides support for os tests.


Added in version 3.10.


@geindex FS_NONASCII (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper FS_NONASCII}@anchor{497b}
@deffn {Δεδομένα} test.support.os_helper.FS_NONASCII

A non-ASCII character encodable by @ref{1013,,os.fsencode()}.
@end deffn

@geindex SAVEDCWD (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper SAVEDCWD}@anchor{497c}
@deffn {Δεδομένα} test.support.os_helper.SAVEDCWD

Set to @ref{1b26,,os.getcwd()}.
@end deffn

@geindex TESTFN (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper TESTFN}@anchor{497d}
@deffn {Δεδομένα} 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 (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper TESTFN_NONASCII}@anchor{497e}
@deffn {Δεδομένα} test.support.os_helper.TESTFN_NONASCII

Set to a filename containing the @ref{497b,,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 (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper TESTFN_UNENCODABLE}@anchor{497f}
@deffn {Δεδομένα} 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 (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper TESTFN_UNDECODABLE}@anchor{4980}
@deffn {Δεδομένα} 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 (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper TESTFN_UNICODE}@anchor{4981}
@deffn {Δεδομένα} test.support.os_helper.TESTFN_UNICODE

Set to a non-ASCII name for a temporary file.
@end deffn

@geindex EnvironmentVarGuard (κλάση σε test.support.os_helper)
@anchor{library/test test support os_helper EnvironmentVarGuard}@anchor{1785}
@deffn {Κλάση} 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.


Άλλαξε στην έκδοση 3.1: Added dictionary interface.

@end deffn

@geindex FakePath (κλάση σε test.support.os_helper)
@anchor{library/test test support os_helper FakePath}@anchor{4982}
@deffn {Κλάση} test.support.os_helper.FakePath (path)

Simple @ref{79f,,path-like object}.  It implements the
@ref{1010,,__fspath__()}
method which just returns the `path' argument.  If `path' is an exception,
it will be raised in @code{__fspath__()}.
@end deffn

@geindex set() (μέθοδος της test.support.os_helper.EnvironmentVarGuard)
@anchor{library/test test support os_helper EnvironmentVarGuard set}@anchor{4983}
@deffn {Μέθοδος} EnvironmentVarGuard.set (envvar, value)

Temporarily set the environment variable @code{envvar} to the value of
@code{value}.
@end deffn

@geindex unset() (μέθοδος της test.support.os_helper.EnvironmentVarGuard)
@anchor{library/test test support os_helper EnvironmentVarGuard unset}@anchor{1a9a}
@deffn {Μέθοδος} EnvironmentVarGuard.unset (envvar, *others)

Temporarily unset one or more environment variables.


Άλλαξε στην έκδοση 3.14: More than one environment variable can be unset.

@end deffn

@geindex can_symlink() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper can_symlink}@anchor{4984}
@deffn {Συνάρτηση} test.support.os_helper.can_symlink ()

Return @code{True} if the OS supports symbolic links, @code{False}
otherwise.
@end deffn

@geindex can_xattr() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper can_xattr}@anchor{4985}
@deffn {Συνάρτηση} test.support.os_helper.can_xattr ()

Return @code{True} if the OS supports xattr, @code{False}
otherwise.
@end deffn

@geindex change_cwd() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper change_cwd}@anchor{4986}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper create_empty_file}@anchor{4987}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper fd_count}@anchor{4988}
@deffn {Συνάρτηση} test.support.os_helper.fd_count ()

Count the number of open file descriptors.
@end deffn

@geindex fs_is_case_insensitive() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper fs_is_case_insensitive}@anchor{4989}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper make_bad_fd}@anchor{498a}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper rmdir}@anchor{498b}
@deffn {Συνάρτηση} test.support.os_helper.rmdir (filename)

Call @ref{149f,,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() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper rmtree}@anchor{498c}
@deffn {Συνάρτηση} test.support.os_helper.rmtree (path)

Call @ref{335,,shutil.rmtree()} on `path' or call @ref{8b1,,os.lstat()} and
@ref{149f,,os.rmdir()} to remove a path and its contents.  As with @ref{498b,,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() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper skip_unless_symlink}@anchor{498d}
@deffn {Συνάρτηση} @@test.support.os_helper.skip_unless_symlink

A decorator for running tests that require support for symbolic links.
@end deffn

@geindex skip_unless_xattr() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper skip_unless_xattr}@anchor{498e}
@deffn {Συνάρτηση} @@test.support.os_helper.skip_unless_xattr

A decorator for running tests that require support for xattr.
@end deffn

@geindex temp_cwd() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper temp_cwd}@anchor{498f}
@deffn {Συνάρτηση} 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{730,,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() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper temp_dir}@anchor{4990}
@deffn {Συνάρτηση} 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{730,,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() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper temp_umask}@anchor{4991}
@deffn {Συνάρτηση} test.support.os_helper.temp_umask (umask)

A context manager that temporarily sets the process umask.
@end deffn

@geindex unlink() (στη μονάδα test.support.os_helper)
@anchor{library/test test support os_helper unlink}@anchor{4992}
@deffn {Συνάρτηση} test.support.os_helper.unlink (filename)

Call @ref{14a1,,os.unlink()} on `filename'.  As with @ref{498b,,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,Εργαλεία Ανάπτυξης
@anchor{library/test module-test support import_helper}@anchor{ef}@anchor{library/test test-support-import-helper-utilities-for-import-tests}@anchor{4993}
@subsection @code{test.support.import_helper} — Utilities for import tests


@geindex module; test.support.import_helper

The @code{test.support.import_helper} module provides support for import tests.


Added in version 3.10.


@geindex forget() (στη μονάδα test.support.import_helper)
@anchor{library/test test support import_helper forget}@anchor{4994}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support.import_helper)
@anchor{library/test test support import_helper import_fresh_module}@anchor{1e59}
@deffn {Συνάρτηση} 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{1bd,,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{1bd,,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


Added in version 3.1.

@end deffn

@geindex import_module() (στη μονάδα test.support.import_helper)
@anchor{library/test test support import_helper import_module}@anchor{4995}
@deffn {Συνάρτηση} 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{138d,,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{518,,sys.platform}.


Added in version 3.1.

@end deffn

@geindex modules_setup() (στη μονάδα test.support.import_helper)
@anchor{library/test test support import_helper modules_setup}@anchor{4996}
@deffn {Συνάρτηση} test.support.import_helper.modules_setup ()

Return a copy of @ref{19ba,,sys.modules}.
@end deffn

@geindex modules_cleanup() (στη μονάδα test.support.import_helper)
@anchor{library/test test support import_helper modules_cleanup}@anchor{4997}
@deffn {Συνάρτηση} 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() (στη μονάδα test.support.import_helper)
@anchor{library/test test support import_helper unload}@anchor{4998}
@deffn {Συνάρτηση} test.support.import_helper.unload (name)

Delete `name' from @code{sys.modules}.
@end deffn

@geindex make_legacy_pyc() (στη μονάδα test.support.import_helper)
@anchor{library/test test support import_helper make_legacy_pyc}@anchor{4999}
@deffn {Συνάρτηση} 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 (κλάση σε test.support.import_helper)
@anchor{library/test test support import_helper CleanImport}@anchor{499a}
@deffn {Κλάση} 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{2c9,,DeprecationWarning} on import.  Example usage:

@example
with CleanImport('foo'):
    importlib.import_module('foo')  # New reference.
@end example
@end deffn

@geindex DirsOnSysPath (κλάση σε test.support.import_helper)
@anchor{library/test test support import_helper DirsOnSysPath}@anchor{499b}
@deffn {Κλάση} test.support.import_helper.DirsOnSysPath (*paths)

A context manager to temporarily add directories to @ref{194,,sys.path}.

This makes a copy of @ref{194,,sys.path}, appends any directories given
as positional arguments, then reverts @code{sys.path} to the copied
settings when the context ends.

Note that `all' @ref{194,,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,Εργαλεία Ανάπτυξης
@anchor{library/test module-test support warnings_helper}@anchor{f4}@anchor{library/test test-support-warnings-helper-utilities-for-warnings-tests}@anchor{499c}
@subsection @code{test.support.warnings_helper} — Utilities for warnings tests


@geindex module; test.support.warnings_helper

The @code{test.support.warnings_helper} module provides support for warnings tests.


Added in version 3.10.


@geindex ignore_warnings() (στη μονάδα test.support.warnings_helper)
@anchor{library/test test support warnings_helper ignore_warnings}@anchor{499d}
@deffn {Συνάρτηση} test.support.warnings_helper.ignore_warnings (*, category)

Suppress warnings that are instances of `category',
which must be @ref{290e,,Warning} or a subclass.
Roughly equivalent to @ref{423,,warnings.catch_warnings()}
with @ref{aae,,warnings.simplefilter('ignore'@comma{} category=category)}.
For example:

@example
@@warning_helper.ignore_warnings(category=DeprecationWarning)
def test_suppress_warning():
    # do something
@end example


Added in version 3.8.

@end deffn

@geindex check_no_resource_warning() (στη μονάδα test.support.warnings_helper)
@anchor{library/test test support warnings_helper check_no_resource_warning}@anchor{499e}
@deffn {Συνάρτηση} test.support.warnings_helper.check_no_resource_warning (testcase)

Context manager to check that no @ref{74f,,ResourceWarning} was raised.  You
must remove the object which may emit @code{ResourceWarning} before the
end of the context manager.
@end deffn

@geindex check_syntax_warning() (στη μονάδα test.support.warnings_helper)
@anchor{library/test test support warnings_helper check_syntax_warning}@anchor{499f}
@deffn {Συνάρτηση} 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{44a,,SyntaxWarning} is emitted only once, and that it
will be converted to a @ref{17e,,SyntaxError} when turned into error.
`testcase' is the @ref{10f,,unittest} instance for the test.  `errtext' is the
regular expression which should match the string representation of the
emitted @code{SyntaxWarning} and raised @code{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.


Added in version 3.8.

@end deffn

@geindex check_warnings() (στη μονάδα test.support.warnings_helper)
@anchor{library/test test support warnings_helper check_warnings}@anchor{49a0}
@deffn {Συνάρτηση} test.support.warnings_helper.check_warnings (*filters, quiet=True)

A convenience wrapper for @ref{423,,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{aae,,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{423,,catch_warnings()} is available via the recorder object’s
@ref{11b,,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, @code{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.


Άλλαξε στην έκδοση 3.2: New optional arguments `filters' and `quiet'.

@end deffn

@geindex WarningsRecorder (κλάση σε test.support.warnings_helper)
@anchor{library/test test support warnings_helper WarningsRecorder}@anchor{49a1}
@deffn {Κλάση} test.support.warnings_helper.WarningsRecorder

Class used to record warnings for unit tests. See documentation of
@ref{49a0,,check_warnings()} above for more details.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Debugging and profiling,Software Packaging and Distribution,Εργαλεία Ανάπτυξης,The Python Standard Library
@anchor{library/debug doc}@anchor{49a2}@anchor{library/debug debugging-and-profiling}@anchor{49a3}@anchor{library/debug translation-repo}@anchor{49a4}
@section Debugging and profiling


Αυτές οι βιβλιοθήκες σας βοηθούν στην ανάπτυξη με την Python: ο αποσφαλματωτής (debugger) σας επιτρέπει να εκτελείτε τον κώδικα βήμα προς βήμα, να αναλύετε στοίβες κλήσεων και να ορίζετε σημεία διακοπής κ.ά., ενώ τα εργαλεία ανάλυσης απόδοσης εκτελούν τον κώδικα και σας παρέχουν λεπτομερή ανάλυση των χρόνων εκτέλεσης, επιτρέποντάς σας να εντοπίσετε σημεία συμφόρησης στα προγράμματά σας. Τα συμβάντα ελέγχου παρέχουν ορατότητα στις συμπεριφορές κατά τον χρόνο εκτέλεσης, οι οποίες διαφορετικά θα απαιτούσαν παρεμβατική αποσφαλμάτωση ή επιδιόρθωση.

@geindex audit events
@anchor{library/audit_events audit-events}@anchor{1e0a}
@menu
* Audit events table:: 
* bdb — Debugger framework:: 
* faulthandler — Dump the Python traceback:: 
* pdb — The Python Debugger:: 
* profiling — Python profilers:: 
* pstats — Statistics for profilers:: 
* timeit — Μέτρηση χρόνου εκτέλεσης μικρών αποσπασμάτων κώδικα:: 
* trace — Ιχνηλάτηση ή παρακολούθηση εκτέλεσης εντολών Python:: 
* tracemalloc — Trace memory allocations:: 

@end menu

@node Audit events table,bdb — Debugger framework,,Debugging and profiling
@anchor{library/audit_events doc}@anchor{49a5}@anchor{library/audit_events audit-events-table}@anchor{49a6}
@subsection Audit events table


This table contains all events raised by @ref{1b36,,sys.audit()} or
@ref{808,,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/}).

See @ref{49a7,,sys.addaudithook()} and @ref{49a8,,PySys_AddAuditHook()} for
information on handling these events.

`Λεπτομέρεια υλοποίησης CPython:' This table is generated from the CPython documentation, and may not
represent events raised by other implementations. See your runtime
specific documentation for actual events raised.


@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{49a9,,[1]}

@item

array.__new__

@tab

@code{typecode}, @code{initializer}

@tab

@ref{6c5,,[1]}

@item

builtins.breakpoint

@tab

@code{breakpointhook}

@tab

@ref{4f9,,[1]}

@item

builtins.id

@tab

@code{id}

@tab

@ref{17c5,,[1]}

@item

builtins.input

@tab

@code{prompt}

@tab

@ref{167d,,[1]}

@item

builtins.input/result

@tab

@code{result}

@tab

@ref{167d,,[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{2e1,,[1]}

@item

compile

@tab

@code{source}, @code{filename}

@tab

@ref{1c8,,[1]}

@item

cpython.PyConfig_Set

@tab

@code{name}, @code{value}

@tab

@ref{5aa,,[1]}

@item

cpython.PyInterpreterState_Clear

@tab



@tab

@ref{49aa,,[1]}

@item

cpython.PyInterpreterState_New

@tab



@tab

@ref{49ab,,[1]}

@item

cpython._PySys_ClearAuditHooks

@tab



@tab

@ref{10cf,,[1]}

@item

cpython.remote_debugger_script

@tab

@code{script_path}

@tab

@ref{49ac,,[1]}

@item

cpython.run_command

@tab

@code{command}

@tab

@ref{445,,[1]}

@item

cpython.run_file

@tab

@code{filename}

@tab

@ref{49ad,,[1]}

@item

cpython.run_interactivehook

@tab

@code{hook}

@tab

@ref{1371,,[1]}

@item

cpython.run_module

@tab

@code{module-name}

@tab

@ref{4ca,,[1]}

@item

cpython.run_startup

@tab

@code{filename}

@tab

@ref{453,,[1]}

@item

cpython.run_stdin

@tab



@tab

@ref{49ae,,[1]}@ref{49af,,[2]}@ref{49b0,,[3]}

@item

ctypes.addressof

@tab

@code{obj}

@tab

@ref{3595,,[1]}

@item

ctypes.call_function

@tab

@code{func_pointer}, @code{arguments}

@tab

@ref{358f,,[1]}

@item

ctypes.cdata

@tab

@code{address}

@tab

@ref{359f,,[1]}

@item

ctypes.cdata/buffer

@tab

@code{pointer}, @code{size}, @code{offset}

@tab

@ref{35a4,,[1]}@ref{35a5,,[2]}

@item

ctypes.create_string_buffer

@tab

@code{init}, @code{size}

@tab

@ref{3548,,[1]}

@item

ctypes.create_unicode_buffer

@tab

@code{init}, @code{size}

@tab

@ref{1fa4,,[1]}

@item

ctypes.dlopen

@tab

@code{name}

@tab

@ref{3588,,[1]}

@item

ctypes.dlsym

@tab

@code{library}, @code{name}

@tab

@ref{3588,,[1]}

@item

ctypes.dlsym/handle

@tab

@code{handle}, @code{name}

@tab

@ref{3588,,[1]}

@item

ctypes.get_errno

@tab



@tab

@ref{3580,,[1]}

@item

ctypes.get_last_error

@tab



@tab

@ref{3582,,[1]}

@item

ctypes.memoryview_at

@tab

@code{address}, @code{size}, @code{readonly}

@tab

@ref{49b1,,[1]}

@item

ctypes.set_errno

@tab

@code{errno}

@tab

@ref{3581,,[1]}

@item

ctypes.set_exception

@tab

@code{code}

@tab

@ref{358f,,[1]}

@item

ctypes.set_last_error

@tab

@code{error}

@tab

@ref{3583,,[1]}

@item

ctypes.string_at

@tab

@code{ptr}, @code{size}

@tab

@ref{482,,[1]}

@item

ctypes.wstring_at

@tab

@code{ptr}, @code{size}

@tab

@ref{359e,,[1]}

@item

ensurepip.bootstrap

@tab

@code{root}

@tab

@ref{49b2,,[1]}

@item

exec

@tab

@code{code_object}

@tab

@ref{184,,[1]}@ref{185,,[2]}

@item

fcntl.fcntl

@tab

@code{fd}, @code{cmd}, @code{arg}

@tab

@ref{1962,,[1]}

@item

fcntl.flock

@tab

@code{fd}, @code{operation}

@tab

@ref{49b3,,[1]}

@item

fcntl.ioctl

@tab

@code{fd}, @code{request}, @code{arg}

@tab

@ref{181d,,[1]}

@item

fcntl.lockf

@tab

@code{fd}, @code{cmd}, @code{len}, @code{start}, @code{whence}

@tab

@ref{178f,,[1]}

@item

ftplib.connect

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{4246,,[1]}

@item

ftplib.sendcmd

@tab

@code{self}, @code{cmd}

@tab

@ref{424b,,[1]}@ref{424c,,[2]}

@item

function.__new__

@tab

@code{code}

@tab

@ref{c59,,[1]}

@item

gc.get_objects

@tab

@code{generation}

@tab

@ref{bdd,,[1]}

@item

gc.get_referents

@tab

@code{objs}

@tab

@ref{bdf,,[1]}

@item

gc.get_referrers

@tab

@code{objs}

@tab

@ref{bde,,[1]}

@item

glob.glob

@tab

@code{pathname}, @code{recursive}

@tab

@ref{2d4,,[1]}@ref{be1,,[2]}

@item

glob.glob/2

@tab

@code{pathname}, @code{recursive}, @code{root_dir}, @code{dir_fd}

@tab

@ref{2d4,,[1]}@ref{be1,,[2]}

@item

http.client.connect

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{4228,,[1]}

@item

http.client.send

@tab

@code{self}, @code{data}

@tab

@ref{422d,,[1]}

@item

imaplib.open

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{cd4,,[1]}

@item

imaplib.send

@tab

@code{self}, @code{data}

@tab

@ref{429d,,[1]}

@item

import

@tab

@code{module}, @code{filename}, @code{sys.path}, @code{sys.meta_path}, @code{sys.path_hooks}

@tab

@ref{9da,,[1]}

@item

marshal.dumps

@tab

@code{value}, @code{version}

@tab

@ref{2f6a,,[1]}

@item

marshal.load

@tab



@tab

@ref{1fe5,,[1]}

@item

marshal.loads

@tab

@code{bytes}

@tab

@ref{1fe5,,[1]}

@item

mmap.__new__

@tab

@code{fileno}, @code{length}, @code{access}, @code{offset}

@tab

@ref{23c,,[1]}

@item

msvcrt.get_osfhandle

@tab

@code{fd}

@tab

@ref{49b4,,[1]}

@item

msvcrt.locking

@tab

@code{fd}, @code{mode}, @code{nbytes}

@tab

@ref{49b5,,[1]}

@item

msvcrt.open_osfhandle

@tab

@code{handle}, @code{flags}

@tab

@ref{49b6,,[1]}

@item

object.__delattr__

@tab

@code{obj}, @code{name}

@tab

@ref{256e,,[1]}

@item

object.__getattr__

@tab

@code{obj}, @code{name}

@tab

@ref{f90,,[1]}

@item

object.__setattr__

@tab

@code{obj}, @code{name}, @code{value}

@tab

@ref{256d,,[1]}

@item

open

@tab

@code{path}, @code{mode}, @code{flags}

@tab

@ref{32b,,[1]}@ref{92b,,[2]}@ref{114b,,[3]}

@item

os.add_dll_directory

@tab

@code{path}

@tab

@ref{dae,,[1]}

@item

os.chdir

@tab

@code{path}

@tab

@ref{a02,,[1]}@ref{1142,,[2]}

@item

os.chflags

@tab

@code{path}, @code{flags}

@tab

@ref{1499,,[1]}@ref{329f,,[2]}

@item

os.chmod

@tab

@code{path}, @code{mode}, @code{dir_fd}

@tab

@ref{72c,,[1]}@ref{72d,,[2]}@ref{72b,,[3]}

@item

os.chown

@tab

@code{path}, @code{uid}, @code{gid}, @code{dir_fd}

@tab

@ref{149a,,[1]}@ref{1143,,[2]}@ref{32a0,,[3]}

@item

os.exec

@tab

@code{path}, @code{args}, @code{env}

@tab

@ref{3310,,[1]}

@item

os.fork

@tab



@tab

@ref{6bd,,[1]}

@item

os.forkpty

@tab



@tab

@ref{6be,,[1]}

@item

os.fwalk

@tab

@code{top}, @code{topdown}, @code{onerror}, @code{follow_symlinks}, @code{dir_fd}

@tab

@ref{f18,,[1]}

@item

os.getxattr

@tab

@code{path}, @code{attribute}

@tab

@ref{14b0,,[1]}

@item

os.kill

@tab

@code{pid}, @code{sig}

@tab

@ref{170c,,[1]}

@item

os.killpg

@tab

@code{pgid}, @code{sig}

@tab

@ref{1fab,,[1]}

@item

os.link

@tab

@code{src}, @code{dst}, @code{src_dir_fd}, @code{dst_dir_fd}

@tab

@ref{149b,,[1]}

@item

os.listdir

@tab

@code{path}

@tab

@ref{14a6,,[1]}

@item

os.listdrives

@tab



@tab

@ref{8ae,,[1]}

@item

os.listmounts

@tab

@code{volume}

@tab

@ref{8b0,,[1]}

@item

os.listvolumes

@tab



@tab

@ref{8af,,[1]}

@item

os.listxattr

@tab

@code{path}

@tab

@ref{14b1,,[1]}

@item

os.lockf

@tab

@code{fd}, @code{cmd}, @code{len}

@tab

@ref{14bf,,[1]}

@item

os.mkdir

@tab

@code{path}, @code{mode}, @code{dir_fd}

@tab

@ref{72f,,[1]}@ref{72e,,[2]}

@item

os.posix_spawn

@tab

@code{path}, @code{argv}, @code{env}

@tab

@ref{731,,[1]}@ref{1949,,[2]}

@item

os.putenv

@tab

@code{key}, @code{value}

@tab

@ref{4e7,,[1]}

@item

os.remove

@tab

@code{path}, @code{dir_fd}

@tab

@ref{149c,,[1]}@ref{32a5,,[2]}@ref{14a1,,[3]}

@item

os.removexattr

@tab

@code{path}, @code{attribute}

@tab

@ref{14b2,,[1]}

@item

os.rename

@tab

@code{src}, @code{dst}, @code{src_dir_fd}, @code{dst_dir_fd}

@tab

@ref{149d,,[1]}@ref{32a6,,[2]}@ref{149e,,[3]}

@item

os.rmdir

@tab

@code{path}, @code{dir_fd}

@tab

@ref{149f,,[1]}

@item

os.scandir

@tab

@code{path}

@tab

@ref{e23,,[1]}

@item

os.setxattr

@tab

@code{path}, @code{attribute}, @code{value}, @code{flags}

@tab

@ref{14b3,,[1]}

@item

os.spawn

@tab

@code{mode}, @code{path}, @code{args}, @code{env}

@tab

@ref{586,,[1]}

@item

os.startfile

@tab

@code{path}, @code{operation}

@tab

@ref{1e79,,[1]}

@item

os.startfile/2

@tab

@code{path}, @code{operation}, @code{arguments}, @code{cwd}, @code{show_cmd}

@tab

@ref{1e79,,[1]}

@item

os.symlink

@tab

@code{src}, @code{dst}, @code{dir_fd}

@tab

@ref{14a0,,[1]}

@item

os.system

@tab

@code{command}

@tab

@ref{17ff,,[1]}

@item

os.truncate

@tab

@code{fd}, @code{length}

@tab

@ref{1148,,[1]}@ref{11ef,,[2]}

@item

os.unsetenv

@tab

@code{key}

@tab

@ref{4e8,,[1]}

@item

os.utime

@tab

@code{path}, @code{times}, @code{ns}, @code{dir_fd}

@tab

@ref{14a2,,[1]}

@item

os.walk

@tab

@code{top}, @code{topdown}, @code{onerror}, @code{followlinks}

@tab

@ref{8b9,,[1]}

@item

pathlib.Path.glob

@tab

@code{self}, @code{pattern}

@tab

@ref{73a,,[1]}

@item

pathlib.Path.rglob

@tab

@code{self}, @code{pattern}

@tab

@ref{73b,,[1]}

@item

pdb.Pdb

@tab



@tab

@ref{4fb,,[1]}

@item

pickle.find_class

@tab

@code{module}, @code{name}

@tab

@ref{19b5,,[1]}

@item

poplib.connect

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{cf0,,[1]}@ref{cf1,,[2]}

@item

poplib.putline

@tab

@code{self}, @code{line}

@tab

@ref{cf0,,[1]}@ref{cf1,,[2]}

@item

pty.spawn

@tab

@code{argv}

@tab

@ref{132c,,[1]}

@item

resource.prlimit

@tab

@code{pid}, @code{resource}, @code{limits}

@tab

@ref{3e8,,[1]}

@item

resource.setrlimit

@tab

@code{resource}, @code{limits}

@tab

@ref{3e7,,[1]}

@item

setopencodehook

@tab



@tab

@ref{1c9e,,[1]}

@item

shutil.chown

@tab

@code{path}, @code{user}, @code{group}

@tab

@ref{74b,,[1]}

@item

shutil.copyfile

@tab

@code{src}, @code{dst}

@tab

@ref{e1e,,[1]}@ref{e1f,,[2]}@ref{e1d,,[3]}

@item

shutil.copymode

@tab

@code{src}, @code{dst}

@tab

@ref{e1e,,[1]}@ref{1c2c,,[2]}

@item

shutil.copystat

@tab

@code{src}, @code{dst}

@tab

@ref{e1f,,[1]}@ref{14da,,[2]}

@item

shutil.copytree

@tab

@code{src}, @code{dst}

@tab

@ref{ded,,[1]}

@item

shutil.make_archive

@tab

@code{base_name}, @code{format}, @code{root_dir}, @code{base_dir}

@tab

@ref{8c3,,[1]}

@item

shutil.move

@tab

@code{src}, @code{dst}

@tab

@ref{e20,,[1]}

@item

shutil.rmtree

@tab

@code{path}, @code{dir_fd}

@tab

@ref{335,,[1]}

@item

shutil.unpack_archive

@tab

@code{filename}, @code{extract_dir}, @code{format}

@tab

@ref{882,,[1]}

@item

signal.pthread_kill

@tab

@code{thread_id}, @code{signalnum}

@tab

@ref{14dd,,[1]}

@item

smtplib.connect

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{1913,,[1]}

@item

smtplib.send

@tab

@code{self}, @code{data}

@tab

@ref{cfa,,[1]}

@item

socket.__new__

@tab

@code{self}, @code{family}, @code{type}, @code{protocol}

@tab

@ref{115a,,[1]}

@item

socket.bind

@tab

@code{self}, @code{address}

@tab

@ref{18dc,,[1]}

@item

socket.connect

@tab

@code{self}, @code{address}

@tab

@ref{115c,,[1]}@ref{18db,,[2]}

@item

socket.getaddrinfo

@tab

@code{host}, @code{port}, @code{family}, @code{type}, @code{protocol}

@tab

@ref{1925,,[1]}

@item

socket.gethostbyaddr

@tab

@code{ip_address}

@tab

@ref{1e7a,,[1]}

@item

socket.gethostbyname

@tab

@code{hostname}

@tab

@ref{3bdf,,[1]}@ref{1e7b,,[2]}

@item

socket.gethostname

@tab



@tab

@ref{324b,,[1]}

@item

socket.getnameinfo

@tab

@code{sockaddr}

@tab

@ref{1c42,,[1]}

@item

socket.getservbyname

@tab

@code{servicename}, @code{protocolname}

@tab

@ref{3be1,,[1]}

@item

socket.getservbyport

@tab

@code{port}, @code{protocolname}

@tab

@ref{3be2,,[1]}

@item

socket.sendmsg

@tab

@code{self}, @code{address}

@tab

@ref{88c,,[1]}

@item

socket.sendto

@tab

@code{self}, @code{address}

@tab

@ref{1162,,[1]}

@item

socket.sethostname

@tab

@code{name}

@tab

@ref{14e7,,[1]}

@item

sqlite3.connect

@tab

@code{database}

@tab

@ref{3e0,,[1]}

@item

sqlite3.connect/handle

@tab

@code{connection_handle}

@tab

@ref{3e0,,[1]}

@item

sqlite3.enable_load_extension

@tab

@code{connection}, @code{enabled}

@tab

@ref{c17,,[1]}

@item

sqlite3.load_extension

@tab

@code{connection}, @code{path}

@tab

@ref{8c8,,[1]}

@item

subprocess.Popen

@tab

@code{executable}, @code{args}, @code{cwd}, @code{env}

@tab

@ref{6bf,,[1]}

@item

sys._current_exceptions

@tab



@tab

@ref{8d2,,[1]}

@item

sys._current_frames

@tab



@tab

@ref{17d5,,[1]}

@item

sys._getframe

@tab

@code{frame}

@tab

@ref{ace,,[1]}

@item

sys._getframemodulename

@tab

@code{depth}

@tab

@ref{1cde,,[1]}

@item

sys.addaudithook

@tab



@tab

@ref{49a8,,[1]}@ref{49a7,,[2]}

@item

sys.excepthook

@tab

@code{hook}, @code{type}, @code{value}, @code{traceback}

@tab

@ref{be5,,[1]}

@item

sys.monitoring.register_callback

@tab

@code{func}

@tab

@ref{49b7,,[1]}

@item

sys.remote_exec

@tab

@code{pid}

@tab

@ref{49b8,,[1]}

@item

sys.set_asyncgen_hooks_finalizer

@tab



@tab

@ref{1baa,,[1]}

@item

sys.set_asyncgen_hooks_firstiter

@tab



@tab

@ref{1baa,,[1]}

@item

sys.setprofile

@tab



@tab

@ref{18a0,,[1]}

@item

sys.settrace

@tab



@tab

@ref{55c,,[1]}

@item

sys.unraisablehook

@tab

@code{hook}, @code{unraisable}

@tab

@ref{70c,,[1]}

@item

syslog.closelog

@tab



@tab

@ref{94c,,[1]}

@item

syslog.openlog

@tab

@code{ident}, @code{logoption}, @code{facility}

@tab

@ref{94b,,[1]}

@item

syslog.setlogmask

@tab

@code{maskpri}

@tab

@ref{49b9,,[1]}

@item

syslog.syslog

@tab

@code{priority}, @code{message}

@tab

@ref{94d,,[1]}

@item

tempfile.mkdtemp

@tab

@code{fullpath}

@tab

@ref{15da,,[1]}@ref{730,,[2]}

@item

tempfile.mkstemp

@tab

@code{fullpath}

@tab

@ref{8d6,,[1]}@ref{1a0d,,[2]}@ref{2ef1,,[3]}

@item

time.sleep

@tab

@code{secs}

@tab

@ref{49ba,,[1]}

@item

urllib.Request

@tab

@code{fullurl}, @code{data}, @code{headers}, @code{method}

@tab

@ref{57f,,[1]}

@item

webbrowser.open

@tab

@code{url}

@tab

@ref{1923,,[1]}

@item

winreg.ConnectRegistry

@tab

@code{computer_name}, @code{key}

@tab

@ref{49bb,,[1]}

@item

winreg.CreateKey

@tab

@code{key}, @code{sub_key}, @code{access}

@tab

@ref{49bc,,[1]}@ref{1707,,[2]}

@item

winreg.DeleteKey

@tab

@code{key}, @code{sub_key}, @code{access}

@tab

@ref{49bd,,[1]}@ref{1708,,[2]}

@item

winreg.DeleteTree

@tab

@code{key}, @code{sub_key}

@tab

@ref{19ea,,[1]}

@item

winreg.DeleteValue

@tab

@code{key}, @code{value}

@tab

@ref{49be,,[1]}

@item

winreg.DisableReflectionKey

@tab

@code{key}

@tab

@ref{1709,,[1]}

@item

winreg.EnableReflectionKey

@tab

@code{key}

@tab

@ref{170a,,[1]}

@item

winreg.EnumKey

@tab

@code{key}, @code{index}

@tab

@ref{49bf,,[1]}

@item

winreg.EnumValue

@tab

@code{key}, @code{index}

@tab

@ref{49c0,,[1]}

@item

winreg.ExpandEnvironmentStrings

@tab

@code{str}

@tab

@ref{179a,,[1]}

@item

winreg.LoadKey

@tab

@code{key}, @code{sub_key}, @code{file_name}

@tab

@ref{49c1,,[1]}

@item

winreg.OpenKey

@tab

@code{key}, @code{sub_key}, @code{access}

@tab

@ref{49c2,,[1]}

@item

winreg.OpenKey/result

@tab

@code{key}

@tab

@ref{49bc,,[1]}@ref{1707,,[2]}@ref{49c2,,[3]}

@item

winreg.PyHKEY.Detach

@tab

@code{key}

@tab

@ref{49c3,,[1]}

@item

winreg.QueryInfoKey

@tab

@code{key}

@tab

@ref{49c4,,[1]}

@item

winreg.QueryReflectionKey

@tab

@code{key}

@tab

@ref{170b,,[1]}

@item

winreg.QueryValue

@tab

@code{key}, @code{sub_key}, @code{value_name}

@tab

@ref{49c5,,[1]}@ref{19a8,,[2]}

@item

winreg.SaveKey

@tab

@code{key}, @code{file_name}

@tab

@ref{49c6,,[1]}

@item

winreg.SetValue

@tab

@code{key}, @code{sub_key}, @code{type}, @code{value}

@tab

@ref{49c7,,[1]}@ref{1d02,,[2]}

@end multitable


The following events are raised internally and do not correspond to any
public API of CPython:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {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

_posixsubprocess.fork_exec

@tab

@code{exec_list}, @code{args}, @code{env}

@item

ctypes.PyObj_FromPtr

@tab

@code{obj}

@end multitable



Added in version 3.14: The @code{_posixsubprocess.fork_exec} internal audit event.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node bdb — Debugger framework,faulthandler — Dump the Python traceback,Audit events table,Debugging and profiling
@anchor{library/bdb doc}@anchor{49c8}@anchor{library/bdb bdb-debugger-framework}@anchor{49c9}@anchor{library/bdb module-bdb}@anchor{10}@anchor{library/bdb translation-repo}@anchor{49ca}
@subsection @code{bdb} — Debugger framework


@geindex module; bdb

`Source code:' Lib/bdb.py@footnote{https://github.com/python/cpython/tree/main/Lib/bdb.py}


__________________________________________________________________


The @code{bdb} module handles basic debugger functions, like setting breakpoints
or managing execution via the debugger.

The following exception is defined:

@geindex BdbQuit
@anchor{library/bdb bdb BdbQuit}@anchor{500}
@deffn {Εξαίρεση} bdb.BdbQuit

Exception raised by the @ref{550,,Bdb} class for quitting the debugger.
@end deffn

The @code{bdb} module also defines two classes:

@geindex Breakpoint (κλάση σε bdb)
@anchor{library/bdb bdb Breakpoint}@anchor{49cb}
@deffn {Κλάση} 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{49cc,,bpbynumber}
and by @code{(file, line)} pairs through @ref{49cd,,bplist}.  The former points to
a single instance of class @code{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{49ce,,file name} should
be in canonical form.  If a @ref{49cf,,funcname} is defined, a breakpoint
@ref{49d0,,hit} will be counted when the first line of that function is
executed.  A @ref{49d1,,conditional} breakpoint always counts a
@code{hit}.

@code{Breakpoint} instances have the following methods:

@geindex deleteMe() (μέθοδος της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint deleteMe}@anchor{49d2}
@deffn {Μέθοδος} 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() (μέθοδος της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint enable}@anchor{49d3}
@deffn {Μέθοδος} enable ()

Mark the breakpoint as enabled.
@end deffn

@geindex disable() (μέθοδος της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint disable}@anchor{49d4}
@deffn {Μέθοδος} disable ()

Mark the breakpoint as disabled.
@end deffn

@geindex bpformat() (μέθοδος της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint bpformat}@anchor{49d5}
@deffn {Μέθοδος} 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


Added in version 3.2.

@end deffn

@geindex bpprint() (μέθοδος της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint bpprint}@anchor{49d6}
@deffn {Μέθοδος} bpprint (out=None)

Print the output of @ref{49d5,,bpformat()} to the file `out', or if it is
@code{None}, to standard output.
@end deffn

@code{Breakpoint} instances have the following attributes:

@geindex file (ιδιότητα της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint file}@anchor{49ce}
@deffn {Ιδιότητα} file

File name of the @code{Breakpoint}.
@end deffn

@geindex line (ιδιότητα της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint line}@anchor{49d7}
@deffn {Ιδιότητα} line

Line number of the @code{Breakpoint} within @ref{49ce,,file}.
@end deffn

@geindex temporary (ιδιότητα της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint temporary}@anchor{49d8}
@deffn {Ιδιότητα} temporary

@code{True} if a @code{Breakpoint} at (file, line) is temporary.
@end deffn

@geindex cond (ιδιότητα της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint cond}@anchor{49d1}
@deffn {Ιδιότητα} cond

Condition for evaluating a @code{Breakpoint} at (file, line).
@end deffn

@geindex funcname (ιδιότητα της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint funcname}@anchor{49cf}
@deffn {Ιδιότητα} funcname

Function name that defines whether a @code{Breakpoint} is hit upon
entering the function.
@end deffn

@geindex enabled (ιδιότητα της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint enabled}@anchor{49d9}
@deffn {Ιδιότητα} enabled

@code{True} if @code{Breakpoint} is enabled.
@end deffn

@geindex bpbynumber (ιδιότητα της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint bpbynumber}@anchor{49cc}
@deffn {Ιδιότητα} bpbynumber

Numeric index for a single instance of a @code{Breakpoint}.
@end deffn

@geindex bplist (ιδιότητα της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint bplist}@anchor{49cd}
@deffn {Ιδιότητα} bplist

Dictionary of @code{Breakpoint} instances indexed by
(@ref{49ce,,file}, @ref{49d7,,line}) tuples.
@end deffn

@geindex ignore (ιδιότητα της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint ignore}@anchor{49da}
@deffn {Ιδιότητα} ignore

Number of times to ignore a @code{Breakpoint}.
@end deffn

@geindex hits (ιδιότητα της bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint hits}@anchor{49d0}
@deffn {Ιδιότητα} hits

Count of the number of times a @code{Breakpoint} has been hit.
@end deffn
@end deffn

@geindex Bdb (κλάση σε bdb)
@anchor{library/bdb bdb Bdb}@anchor{550}
@deffn {Κλάση} bdb.Bdb (skip=None, backend='settrace')

The @code{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{4fb,,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.

The `backend' argument specifies the backend to use for @code{Bdb}. It
can be either @code{'settrace'} or @code{'monitoring'}. @code{'settrace'} uses
@ref{55c,,sys.settrace()} which has the best backward compatibility. The
@code{'monitoring'} backend uses the new @ref{e3,,sys.monitoring} that was
introduced in Python 3.12, which can be much more efficient because it
can disable unused events. We are trying to keep the exact interfaces
for both backends, but there are some differences. The debugger developers
are encouraged to use the @code{'monitoring'} backend to achieve better
performance.


Άλλαξε στην έκδοση 3.1: Added the `skip' parameter.



Άλλαξε στην έκδοση 3.14: Added the `backend' parameter.


The following methods of @code{Bdb} normally don’t need to be overridden.

@geindex canonic() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb canonic}@anchor{49db}
@deffn {Μέθοδος} canonic (filename)

Return canonical form of `filename'.

For real file names, the canonical form is an operating-system-dependent,
@ref{2e71,,case-normalized} @ref{16bf,,absolute path}. A `filename' with angle brackets, such as @code{"<stdin>"}
generated in interactive mode, is returned unchanged.
@end deffn

@geindex start_trace() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb start_trace}@anchor{49dc}
@deffn {Μέθοδος} start_trace (self)

Start tracing. For @code{'settrace'} backend, this method is equivalent to
@code{sys.settrace(self.trace_dispatch)}


Added in version 3.14.

@end deffn

@geindex stop_trace() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb stop_trace}@anchor{49dd}
@deffn {Μέθοδος} stop_trace (self)

Stop tracing. For @code{'settrace'} backend, this method is equivalent to
@code{sys.settrace(None)}


Added in version 3.14.

@end deffn

@geindex reset() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb reset}@anchor{49de}
@deffn {Μέθοδος} reset ()

Set the @code{botframe}, @code{stopframe}, @code{returnframe} and
@ref{49df,,quitting} attributes with values ready to start debugging.
@end deffn

@geindex trace_dispatch() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb trace_dispatch}@anchor{49e0}
@deffn {Μέθοδος} 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"}: An exception has occurred.
@end itemize

For all the events, specialized functions (see below) are called.

The `arg' parameter depends on the previous event.

See the documentation for @ref{55c,,sys.settrace()} for more information on the
trace function.  For more information on code and frame objects, refer to
@ref{2520,,Η τυπική ιεραρχία τύπου}.
@end deffn

@geindex dispatch_line() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb dispatch_line}@anchor{49e1}
@deffn {Μέθοδος} dispatch_line (frame)

If the debugger should stop on the current line, invoke the
@ref{49e2,,user_line()} method (which should be overridden in subclasses).
Raise a @ref{500,,BdbQuit} exception if the @ref{49df,,quitting} flag is set
(which can be set from @code{user_line()}).  Return a reference to the
@ref{49e0,,trace_dispatch()} method for further tracing in that scope.
@end deffn

@geindex dispatch_call() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb dispatch_call}@anchor{49e3}
@deffn {Μέθοδος} dispatch_call (frame, arg)

If the debugger should stop on this function call, invoke the
@ref{49e4,,user_call()} method (which should be overridden in subclasses).
Raise a @ref{500,,BdbQuit} exception if the @ref{49df,,quitting} flag is set
(which can be set from @code{user_call()}).  Return a reference to the
@ref{49e0,,trace_dispatch()} method for further tracing in that scope.
@end deffn

@geindex dispatch_return() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb dispatch_return}@anchor{49e5}
@deffn {Μέθοδος} dispatch_return (frame, arg)

If the debugger should stop on this function return, invoke the
@ref{49e6,,user_return()} method (which should be overridden in subclasses).
Raise a @ref{500,,BdbQuit} exception if the @ref{49df,,quitting} flag is set
(which can be set from @code{user_return()}).  Return a reference to the
@ref{49e0,,trace_dispatch()} method for further tracing in that scope.
@end deffn

@geindex dispatch_exception() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb dispatch_exception}@anchor{49e7}
@deffn {Μέθοδος} dispatch_exception (frame, arg)

If the debugger should stop at this exception, invokes the
@ref{49e8,,user_exception()} method (which should be overridden in subclasses).
Raise a @ref{500,,BdbQuit} exception if the @ref{49df,,quitting} flag is set
(which can be set from @code{user_exception()}).  Return a reference to the
@ref{49e0,,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_module() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb is_skipped_module}@anchor{49e9}
@deffn {Μέθοδος} is_skipped_module (module_name)

Return @code{True} if `module_name' matches any skip pattern.
@end deffn

@geindex stop_here() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb stop_here}@anchor{49ea}
@deffn {Μέθοδος} stop_here (frame)

Return @code{True} if `frame' is below the starting frame in the stack.
@end deffn

@geindex break_here() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb break_here}@anchor{49eb}
@deffn {Μέθοδος} 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{49ec,,effective()}.
@end deffn

@geindex break_anywhere() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb break_anywhere}@anchor{49ed}
@deffn {Μέθοδος} 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() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb user_call}@anchor{49e4}
@deffn {Μέθοδος} user_call (frame, argument_list)

Called from @ref{49e3,,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() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb user_line}@anchor{49e2}
@deffn {Μέθοδος} user_line (frame)

Called from @ref{49e1,,dispatch_line()} when either @ref{49ea,,stop_here()} or
@ref{49eb,,break_here()} returns @code{True}.
@end deffn

@geindex user_return() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb user_return}@anchor{49e6}
@deffn {Μέθοδος} user_return (frame, return_value)

Called from @ref{49e5,,dispatch_return()} when @ref{49ea,,stop_here()} returns @code{True}.
@end deffn

@geindex user_exception() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb user_exception}@anchor{49e8}
@deffn {Μέθοδος} user_exception (frame, exc_info)

Called from @ref{49e7,,dispatch_exception()} when @ref{49ea,,stop_here()}
returns @code{True}.
@end deffn

@geindex do_clear() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb do_clear}@anchor{49ee}
@deffn {Μέθοδος} 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() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb set_step}@anchor{49ef}
@deffn {Μέθοδος} set_step ()

Stop after one line of code.
@end deffn

@geindex set_next() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb set_next}@anchor{49f0}
@deffn {Μέθοδος} set_next (frame)

Stop on the next line in or below the given frame.
@end deffn

@geindex set_return() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb set_return}@anchor{49f1}
@deffn {Μέθοδος} set_return (frame)

Stop when returning from the given frame.
@end deffn

@geindex set_until() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb set_until}@anchor{49f2}
@deffn {Μέθοδος} 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() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb set_trace}@anchor{49f3}
@deffn {Μέθοδος} set_trace ([frame])

Start debugging from `frame'.  If `frame' is not specified, debugging
starts from caller’s frame.


Άλλαξε στην έκδοση 3.13: @ref{49f4,,set_trace()} will enter the debugger immediately, rather than
on the next line of code to be executed.

@end deffn

@geindex set_continue() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb set_continue}@anchor{49f5}
@deffn {Μέθοδος} 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() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb set_quit}@anchor{49df}
@deffn {Μέθοδος} set_quit ()

@geindex quitting (bdb.Bdb attribute)

Set the @code{quitting} attribute to @code{True}.  This raises @ref{500,,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() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb set_break}@anchor{49f6}
@deffn {Μέθοδος} 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{49db,,canonic()} method.
@end deffn

@geindex clear_break() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb clear_break}@anchor{49f7}
@deffn {Μέθοδος} clear_break (filename, lineno)

Delete the breakpoints in `filename' and `lineno'.  If none were set,
return an error message.
@end deffn

@geindex clear_bpbynumber() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb clear_bpbynumber}@anchor{49f8}
@deffn {Μέθοδος} clear_bpbynumber (arg)

Delete the breakpoint which has the index `arg' in the
@ref{49cc,,Breakpoint.bpbynumber}.  If `arg' is not numeric or out of range,
return an error message.
@end deffn

@geindex clear_all_file_breaks() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb clear_all_file_breaks}@anchor{49f9}
@deffn {Μέθοδος} clear_all_file_breaks (filename)

Delete all breakpoints in `filename'.  If none were set, return an error
message.
@end deffn

@geindex clear_all_breaks() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb clear_all_breaks}@anchor{49fa}
@deffn {Μέθοδος} clear_all_breaks ()

Delete all existing breakpoints.  If none were set, return an error
message.
@end deffn

@geindex get_bpbynumber() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb get_bpbynumber}@anchor{49fb}
@deffn {Μέθοδος} 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{277,,ValueError} is raised.


Added in version 3.2.

@end deffn

@geindex get_break() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb get_break}@anchor{49fc}
@deffn {Μέθοδος} get_break (filename, lineno)

Return @code{True} if there is a breakpoint for `lineno' in `filename'.
@end deffn

@geindex get_breaks() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb get_breaks}@anchor{49fd}
@deffn {Μέθοδος} 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() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb get_file_breaks}@anchor{49fe}
@deffn {Μέθοδος} get_file_breaks (filename)

Return all breakpoints in `filename', or an empty list if none are set.
@end deffn

@geindex get_all_breaks() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb get_all_breaks}@anchor{49ff}
@deffn {Μέθοδος} get_all_breaks ()

Return all breakpoints that are set.
@end deffn

Derived classes and clients can call the following methods to disable and
restart events to achieve better performance. These methods only work
when using the @code{'monitoring'} backend.

@geindex disable_current_event() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb disable_current_event}@anchor{4a00}
@deffn {Μέθοδος} disable_current_event ()

Disable the current event until the next time @ref{4a01,,restart_events()} is
called. This is helpful when the debugger is not interested in the current
line.


Added in version 3.14.

@end deffn

@geindex restart_events() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb restart_events}@anchor{4a01}
@deffn {Μέθοδος} restart_events ()

Restart all the disabled events. This function is automatically called in
@code{dispatch_*} methods after @code{user_*} methods are called. If the
@code{dispatch_*} methods are not overridden, the disabled events will be
restarted after each user interaction.


Added in version 3.14.

@end deffn

Derived classes and clients can call the following methods to get a data
structure representing a stack trace.

@geindex get_stack() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb get_stack}@anchor{4a02}
@deffn {Μέθοδος} 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() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb format_stack_entry}@anchor{4a03}
@deffn {Μέθοδος} 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 
The input arguments.

@item 
The return value.

@item 
The line of code (if it exists).
@end itemize
@end deffn

The following two methods can be called by clients to use a debugger to debug
a @ref{2e17,,statement}, given as a string.

@geindex run() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb run}@anchor{4a04}
@deffn {Μέθοδος} run (cmd, globals=None, locals=None)

Debug a statement executed via the @ref{185,,exec()} function.  `globals'
defaults to @code{__main__.__dict__}, `locals' defaults to `globals'.
@end deffn

@geindex runeval() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb runeval}@anchor{4a05}
@deffn {Μέθοδος} runeval (expr, globals=None, locals=None)

Debug an expression executed via the @ref{184,,eval()} function.  `globals' and
`locals' have the same meaning as in @ref{4a04,,run()}.
@end deffn

@geindex runctx() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb runctx}@anchor{4a06}
@deffn {Μέθοδος} runctx (cmd, globals, locals)

For backwards compatibility.  Calls the @ref{4a04,,run()} method.
@end deffn

@geindex runcall() (μέθοδος της bdb.Bdb)
@anchor{library/bdb bdb Bdb runcall}@anchor{e40}
@deffn {Μέθοδος} 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() (στη μονάδα bdb)
@anchor{library/bdb bdb checkfuncname}@anchor{4a07}
@deffn {Συνάρτηση} bdb.checkfuncname (b, frame)

Return @code{True} if we should break here, depending on the way the
@ref{49cb,,Breakpoint} `b' was set.

If it was set via line number, it checks if
@ref{49d7,,b.line} is the same as the one in `frame'.
If the breakpoint was set via
@ref{49cf,,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() (στη μονάδα bdb)
@anchor{library/bdb bdb effective}@anchor{49ec}
@deffn {Συνάρτηση} 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{49cd,,bplist} for the
(@ref{49ce,,file}, @ref{49d7,,line})
(which must exist) that is @ref{49d9,,enabled}, for
which @ref{4a07,,checkfuncname()} is true, and that has neither a false
@ref{49d1,,condition} nor positive
@ref{49da,,ignore} count.  The `flag', meaning that a
temporary breakpoint should be deleted, is @code{False} only when the
@code{cond} cannot be evaluated (in which case,
@code{ignore} count is ignored).

If no such entry exists, then @code{(None, None)} is returned.
@end deffn

@geindex set_trace() (στη μονάδα bdb)
@anchor{library/bdb bdb set_trace}@anchor{49f4}
@deffn {Συνάρτηση} bdb.set_trace ()

Start debugging with a @ref{550,,Bdb} instance from caller’s frame.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node faulthandler — Dump the Python traceback,pdb — The Python Debugger,bdb — Debugger framework,Debugging and profiling
@anchor{library/faulthandler doc}@anchor{4a08}@anchor{library/faulthandler faulthandler-dump-the-python-traceback}@anchor{4a09}@anchor{library/faulthandler module-faulthandler}@anchor{5b}@anchor{library/faulthandler translation-repo}@anchor{4a0a}
@subsection @code{faulthandler} — Dump the Python traceback


@geindex module; faulthandler


Added in 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{219,,faulthandler.enable()} to
install fault handlers for the @ref{1428,,SIGSEGV},
@ref{1429,,SIGFPE}, @ref{142a,,SIGABRT}, @ref{142b,,SIGBUS}, and
@ref{142c,,SIGILL} signals. You can also
enable them at startup by setting the 
@geindex PYTHONFAULTHANDLER
@geindex μεταβλητή περιβάλλοντος; PYTHONFAULTHANDLER
@ref{142d,,PYTHONFAULTHANDLER} environment
variable or by using the @ref{178,,-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 per thread, and 100 threads
(configurable via `max_threads').

@item 
The order is reversed: the most recent call is shown first.
@end itemize

By default, the Python traceback is written to @ref{d05,,sys.stderr}. To see
tracebacks, applications must be run in the terminal. A log file can
alternatively be passed to @ref{219,,faulthandler.enable()}.

The module is implemented in C, so tracebacks can be dumped on a crash or when
Python is deadlocked.

The @ref{70d,,Python Development Mode} calls @ref{219,,faulthandler.enable()}
at Python startup.


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{aa,,pdb}

Interactive source code debugger for Python programs.

@item Module @ref{107,,traceback}

Standard interface to extract, format and print stack traces of Python programs.
@end table


@menu
* Dumping the traceback:: 
* Dumping the C stack:: 
* Fault handler state:: 
* Dumping the tracebacks after a timeout:: 
* Dumping the traceback on a user signal:: 
* Issue with file descriptors:: 
* Example: Example<12>. 

@end menu

@node Dumping the traceback,Dumping the C stack,,faulthandler — Dump the Python traceback
@anchor{library/faulthandler dumping-the-traceback}@anchor{4a0b}
@subsubsection Dumping the traceback


@geindex dump_traceback() (στη μονάδα faulthandler)
@anchor{library/faulthandler faulthandler dump_traceback}@anchor{21a}
@deffn {Συνάρτηση} faulthandler.dump_traceback (file=sys.stderr, all_threads=True, *, max_threads=100)

Dump the tracebacks of all threads into `file'. If `all_threads' is
@code{False}, dump only the current thread. `max_threads' caps the number
of threads dumped.


@subsubheading Δείτε επίσης


@ref{1236,,traceback.print_tb()}, which can be used to print a traceback object.



Άλλαξε στην έκδοση 3.5: Added support for passing file descriptor to this function.



Άλλαξε στην έκδοση 3.15: Added the `max_threads' keyword argument.

@end deffn

@node Dumping the C stack,Fault handler state,Dumping the traceback,faulthandler — Dump the Python traceback
@anchor{library/faulthandler dumping-the-c-stack}@anchor{4a0c}
@subsubsection Dumping the C stack



Added in version 3.14.


@geindex dump_c_stack() (στη μονάδα faulthandler)
@anchor{library/faulthandler faulthandler dump_c_stack}@anchor{49f}
@deffn {Συνάρτηση} faulthandler.dump_c_stack (file=sys.stderr)

Dump the C stack trace of the current thread into `file'.

If the Python build does not support it or the operating system
does not provide a stack trace, then this prints an error in place
of a dumped C stack.
@end deffn

@menu
* C Stack Compatibility:: 

@end menu

@node C Stack Compatibility,,,Dumping the C stack
@anchor{library/faulthandler c-stack-compatibility}@anchor{49e}@anchor{library/faulthandler id1}@anchor{4a0d}
@subsubsection C Stack Compatibility


If the system does not support the C-level @code{backtrace(3)@footnote{https://manpages.debian.org/backtrace(3)}}
or @code{dladdr1(3)@footnote{https://manpages.debian.org/dladdr1(3)}}, then C stack dumps will not work.
An error will be printed instead of the stack.

Additionally, some compilers do not support @ref{ae3,,CPython’s}
implementation of C stack dumps. As a result, a different error may be printed
instead of the stack, even if the operating system supports dumping stacks.

@cartouche
@quotation Σημείωση 
Dumping C stacks can be arbitrarily slow, depending on the DWARF level
of the binaries in the call stack.
@end quotation
@end cartouche

@node Fault handler state,Dumping the tracebacks after a timeout,Dumping the C stack,faulthandler — Dump the Python traceback
@anchor{library/faulthandler fault-handler-state}@anchor{4a0e}
@subsubsection Fault handler state


@geindex enable() (στη μονάδα faulthandler)
@anchor{library/faulthandler faulthandler enable}@anchor{219}
@deffn {Συνάρτηση} faulthandler.enable (file=sys.stderr, all_threads=True, c_stack=True, *, max_threads=100)

Enable the fault handler: install handlers for the @ref{1428,,SIGSEGV},
@ref{1429,,SIGFPE}, @ref{142a,,SIGABRT}, @ref{142b,,SIGBUS}
and @ref{142c,,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{4a0f,,issue with file descriptors}.

If `c_stack' is @code{True}, then the C stack trace is printed after the Python
traceback, unless the system does not support it. See @ref{49f,,dump_c_stack()} for
more information on compatibility.

`max_threads' caps the number of threads dumped when a fatal signal fires.


Άλλαξε στην έκδοση 3.5: Added support for passing file descriptor to this function.



Άλλαξε στην έκδοση 3.6: On Windows, a handler for Windows exception is also installed.



Άλλαξε στην έκδοση 3.10: The dump now mentions if a garbage collector collection is running
if `all_threads' is true.



Άλλαξε στην έκδοση 3.14: Only the current thread is dumped if the @ref{411,,GIL} is disabled to
prevent the risk of data races.



Άλλαξε στην έκδοση 3.14: The dump now displays the C stack trace if `c_stack' is true.



Άλλαξε στην έκδοση 3.15: Added the `max_threads' keyword argument.

@end deffn

@geindex disable() (στη μονάδα faulthandler)
@anchor{library/faulthandler faulthandler disable}@anchor{4a10}
@deffn {Συνάρτηση} faulthandler.disable ()

Disable the fault handler: uninstall the signal handlers installed by
@ref{219,,enable()}.
@end deffn

@geindex is_enabled() (στη μονάδα faulthandler)
@anchor{library/faulthandler faulthandler is_enabled}@anchor{4a11}
@deffn {Συνάρτηση} 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{4a12}
@subsubsection Dumping the tracebacks after a timeout


@geindex dump_traceback_later() (στη μονάδα faulthandler)
@anchor{library/faulthandler faulthandler dump_traceback_later}@anchor{21b}
@deffn {Συνάρτηση} faulthandler.dump_traceback_later (timeout, repeat=False, file=sys.stderr, exit=False, *, max_threads=100)

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. `max_threads' caps the number of threads dumped.

The `file' must be kept open until the traceback is dumped or
@ref{4a13,,cancel_dump_traceback_later()} is called: see @ref{4a0f,,issue with file descriptors}.

This function is implemented using a watchdog thread.


Άλλαξε στην έκδοση 3.5: Added support for passing file descriptor to this function.



Άλλαξε στην έκδοση 3.7: This function is now always available.



Άλλαξε στην έκδοση 3.15: Added the `max_threads' keyword argument.

@end deffn

@geindex cancel_dump_traceback_later() (στη μονάδα faulthandler)
@anchor{library/faulthandler faulthandler cancel_dump_traceback_later}@anchor{4a13}
@deffn {Συνάρτηση} faulthandler.cancel_dump_traceback_later ()

Cancel the last call to @ref{21b,,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{4a14}
@subsubsection Dumping the traceback on a user signal


@geindex register() (στη μονάδα faulthandler)
@anchor{library/faulthandler faulthandler register}@anchor{21c}
@deffn {Συνάρτηση} faulthandler.register (signum, file=sys.stderr, all_threads=True, chain=False, *, max_threads=100)

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}.
`max_threads' caps the number of threads dumped.

The `file' must be kept open until the signal is unregistered by
@ref{4a15,,unregister()}: see @ref{4a0f,,issue with file descriptors}.

Not available on Windows.


Άλλαξε στην έκδοση 3.5: Added support for passing file descriptor to this function.



Άλλαξε στην έκδοση 3.15: Added the `max_threads' keyword argument.

@end deffn

@geindex unregister() (στη μονάδα faulthandler)
@anchor{library/faulthandler faulthandler unregister}@anchor{4a15}
@deffn {Συνάρτηση} faulthandler.unregister (signum)

Unregister a user signal: uninstall the handler of the `signum' signal
installed by @ref{21c,,register()}. Return @code{True} if the signal was registered,
@code{False} otherwise.

Not available on Windows.
@end deffn

@node Issue with file descriptors,Example<12>,Dumping the traceback on a user signal,faulthandler — Dump the Python traceback
@anchor{library/faulthandler faulthandler-fd}@anchor{4a0f}@anchor{library/faulthandler issue-with-file-descriptors}@anchor{4a16}
@subsubsection Issue with file descriptors


@ref{219,,enable()}, @ref{21b,,dump_traceback_later()} and @ref{21c,,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{f20,,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 Example<12>,,Issue with file descriptors,faulthandler — Dump the Python traceback
@anchor{library/faulthandler example}@anchor{4a17}
@subsubsection Example


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 "/opt/python/Lib/ctypes/__init__.py", line 486 in string_at
  File "<stdin>", line 1 in <module>

Current thread's C stack trace (most recent call first):
  Binary file "/opt/python/python", at _Py_DumpStack+0x42 [0x5b27f7d7147e]
  Binary file "/opt/python/python", at +0x32dcbd [0x5b27f7d85cbd]
  Binary file "/opt/python/python", at +0x32df8a [0x5b27f7d85f8a]
  Binary file "/usr/lib/libc.so.6", at +0x3def0 [0x77b73226bef0]
  Binary file "/usr/lib/libc.so.6", at +0x17ef9c [0x77b7323acf9c]
  Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0xcdf6 [0x77b7315dddf6]
  Binary file "/usr/lib/libffi.so.8", at +0x7976 [0x77b73158f976]
  Binary file "/usr/lib/libffi.so.8", at +0x413c [0x77b73158c13c]
  Binary file "/usr/lib/libffi.so.8", at ffi_call+0x12e [0x77b73158ef0e]
  Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33]
  Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa]
  Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0xc624 [0x77b7315dd624]
  Binary file "/opt/python/python", at _PyObject_MakeTpCall+0xce [0x5b27f7b73883]
  Binary file "/opt/python/python", at +0x11bab6 [0x5b27f7b73ab6]
  Binary file "/opt/python/python", at PyObject_Vectorcall+0x23 [0x5b27f7b73b04]
  Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x490c [0x5b27f7cbb302]
  Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
  Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
  Binary file "/opt/python/python", at PyEval_EvalCode+0xc5 [0x5b27f7cd9ba3]
  Binary file "/opt/python/python", at +0x255957 [0x5b27f7cad957]
  Binary file "/opt/python/python", at +0x255ab4 [0x5b27f7cadab4]
  Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x6c3e [0x5b27f7cbd634]
  Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
  Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
  Binary file "/opt/python/python", at +0x11b6e1 [0x5b27f7b736e1]
  Binary file "/opt/python/python", at +0x11d348 [0x5b27f7b75348]
  Binary file "/opt/python/python", at +0x11d626 [0x5b27f7b75626]
  Binary file "/opt/python/python", at PyObject_Call+0x20 [0x5b27f7b7565e]
  Binary file "/opt/python/python", at +0x32a67a [0x5b27f7d8267a]
  Binary file "/opt/python/python", at +0x32a7f8 [0x5b27f7d827f8]
  Binary file "/opt/python/python", at +0x32ac1b [0x5b27f7d82c1b]
  Binary file "/opt/python/python", at Py_RunMain+0x31 [0x5b27f7d82ebe]
  <truncated rest of calls>
Segmentation fault
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node pdb — The Python Debugger,profiling — Python profilers,faulthandler — Dump the Python traceback,Debugging and profiling
@anchor{library/pdb doc}@anchor{4a18}@anchor{library/pdb debugger}@anchor{4a19}@anchor{library/pdb module-pdb}@anchor{aa}@anchor{library/pdb pdb-the-python-debugger}@anchor{4a1a}@anchor{library/pdb translation-repo}@anchor{4a1b}
@subsection @code{pdb} — The Python Debugger


@geindex module; pdb

`Source code:' Lib/pdb.py@footnote{https://github.com/python/cpython/tree/main/Lib/pdb.py}

@geindex debugging


__________________________________________________________________


The module @code{pdb} defines an interactive source code debugger for Python
programs.  It supports setting (conditional) breakpoints and single stepping at
the source line level, inspection of stack frames, source code listing, and
evaluation of arbitrary Python code in the context of any stack frame.  It also
supports post-mortem debugging and can be called under program control.

@geindex Pdb (class in pdb)
@geindex module;bdb
@geindex module;cmd

The debugger is extensible – it is actually defined as the class @ref{4fb,,Pdb}.
This is currently undocumented but easily understood by reading the source.  The
extension interface uses the modules @ref{10,,bdb} and @ref{1a,,cmd}.


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{5b,,faulthandler}

Used to dump Python tracebacks explicitly, on a fault, after a timeout,
or on a user signal.

@item Module @ref{107,,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{4a1c,,continue} command.


Άλλαξε στην έκδοση 3.7: The built-in @ref{4f9,,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


Άλλαξε στην έκδοση 3.3: Tab-completion via the @ref{c2,,readline} module is available for commands and
command arguments, e.g. the current global and local names are offered as
arguments of the @code{p} command.


@menu
* Command-line interface: Command-line interface<7>. 
* Debugger commands:: 

@end menu

@node Command-line interface<7>,Debugger commands,,pdb — The Python Debugger
@anchor{library/pdb command-line-interface}@anchor{4a1d}@anchor{library/pdb pdb-cli}@anchor{55d}
@subsubsection Command-line interface


You can also invoke @code{pdb} from the command line to debug other scripts.  For
example:

@example
python -m pdb [-c command] (-m module | -p pid | pyfile) [args ...]
@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.

@geindex pdb command line option; -c
@geindex pdb command line option; --command
@anchor{library/pdb cmdoption-pdb-c}@anchor{4a1e}@anchor{library/pdb cmdoption-pdb-command}@anchor{4a1f}
@deffn {Option} @w{-}c, @w{-}@w{-}command <command>

To execute commands as if given in a @code{.pdbrc} file; see
@ref{4a20,,Debugger commands}.


Άλλαξε στην έκδοση 3.2: Added the @code{-c} option.

@end deffn

@geindex pdb command line option; -m
@anchor{library/pdb cmdoption-pdb-m}@anchor{4a21}
@deffn {Option} @w{-}m <module>

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.


Άλλαξε στην έκδοση 3.7: Added the @code{-m} option.

@end deffn

@geindex pdb command line option; -p
@geindex pdb command line option; --pid
@anchor{library/pdb cmdoption-pdb-p}@anchor{4f8}@anchor{library/pdb cmdoption-pdb-pid}@anchor{4a22}
@deffn {Option} @w{-}p, @w{-}@w{-}pid <pid>

Attach to the process with the specified PID.


Added in version 3.14.

@end deffn

To attach to a running Python process for remote debugging, use the @code{-p} or
@code{--pid} option with the target process’s PID:

@example
python -m pdb -p 1234
@end example

@cartouche
@quotation Σημείωση 
Attaching to a process that is blocked in a system call or waiting for I/O
will only work once the next bytecode instruction is executed or when the
process receives a signal.
@end quotation
@end cartouche

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

The typical usage to inspect a crashed program is:

@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


Άλλαξε στην έκδοση 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{6ad,,optimized scope}.


The module defines the following functions; each enters the debugger in a
slightly different way:

@geindex run() (στη μονάδα pdb)
@anchor{library/pdb pdb run}@anchor{4811}
@deffn {Συνάρτηση} pdb.run (statement, globals=None, locals=None)

Execute the `statement' (given as a string or a code object) under debugger
control.  The debugger prompt appears before any code is executed; you can
set breakpoints and type @ref{4a1c,,continue}, or you can step through the
statement using @ref{4a23,,step} or @ref{4a24,,next} (all these commands are
explained below).  The optional `globals' and `locals' arguments specify the
environment in which the code is executed; by default the dictionary of the
module @ref{1,,__main__} is used.  (See the explanation of the built-in
@ref{185,,exec()} or @ref{184,,eval()} functions.)
@end deffn

@geindex runeval() (στη μονάδα pdb)
@anchor{library/pdb pdb runeval}@anchor{4a25}
@deffn {Συνάρτηση} pdb.runeval (expression, globals=None, locals=None)

Evaluate the `expression' (given as a string or a code object) under debugger
control.  When @code{runeval()} returns, it returns the value of the
`expression'.  Otherwise this function is similar to @ref{4811,,run()}.
@end deffn

@geindex runcall() (στη μονάδα pdb)
@anchor{library/pdb pdb runcall}@anchor{4a26}
@deffn {Συνάρτηση} pdb.runcall (function, *args, **kwds)

Call the `function' (a function or method object, not a string) with the
given arguments.  When @code{runcall()} returns, it returns whatever the
function call returned.  The debugger prompt appears as soon as the function
is entered.
@end deffn

@geindex set_trace() (στη μονάδα pdb)
@anchor{library/pdb pdb set_trace}@anchor{4fa}
@deffn {Συνάρτηση} pdb.set_trace (*, header=None, commands=None)

Enter the debugger at the calling stack frame.  This is useful to hard-code
a breakpoint at a given point in a program, even if the code is not
otherwise being debugged (e.g. when an assertion fails).  If given,
`header' is printed to the console just before debugging begins.
The `commands' argument, if given, is a list of commands to execute
when the debugger starts.


Άλλαξε στην έκδοση 3.7: The keyword-only argument `header'.



Άλλαξε στην έκδοση 3.13: @code{set_trace()} will enter the debugger immediately, rather than
on the next line of code to be executed.



Added in version 3.14: The `commands' argument.

@end deffn

@geindex set_trace_async() (στη μονάδα pdb)
@anchor{library/pdb pdb set_trace_async}@anchor{501}
@deffn {Συνάρτηση} awaitable pdb.set_trace_async (*, header=None, commands=None)

async version of @ref{4fa,,set_trace()}. This function should be used inside an
async function with @ref{432,,await}.

@example
async def f():
    await pdb.set_trace_async()
@end example

@ref{432,,await} statements are supported if the debugger is invoked by this function.


Added in version 3.14.

@end deffn

@geindex post_mortem() (στη μονάδα pdb)
@anchor{library/pdb pdb post_mortem}@anchor{177d}
@deffn {Συνάρτηση} pdb.post_mortem (t=None)

Enter post-mortem debugging of the given exception or
@ref{eba,,traceback object}. If no value is given, it uses
the exception that is currently being handled, or raises @code{ValueError} if
there isn’t one.


Άλλαξε στην έκδοση 3.13: Support for exception objects was added.

@end deffn

@geindex pm() (στη μονάδα pdb)
@anchor{library/pdb pdb pm}@anchor{742}
@deffn {Συνάρτηση} pdb.pm ()

Enter post-mortem debugging of the exception found in
@ref{8ce,,sys.last_exc}.
@end deffn

@geindex set_default_backend() (στη μονάδα pdb)
@anchor{library/pdb pdb set_default_backend}@anchor{4a27}
@deffn {Συνάρτηση} pdb.set_default_backend (backend)

There are two supported backends for pdb: @code{'settrace'} and @code{'monitoring'}.
See @ref{550,,bdb.Bdb} for details. The user can set the default backend to
use if none is specified when instantiating @ref{4fb,,Pdb}. If no backend is
specified, the default is @code{'settrace'}.

@cartouche
@quotation Σημείωση 
@ref{4f9,,breakpoint()} and @ref{4fa,,set_trace()} will not be affected by this
function. They always use @code{'monitoring'} backend.
@end quotation
@end cartouche


Added in version 3.14.

@end deffn

@geindex get_default_backend() (στη μονάδα pdb)
@anchor{library/pdb pdb get_default_backend}@anchor{4a28}
@deffn {Συνάρτηση} pdb.get_default_backend ()

Returns the default backend for pdb.


Added in version 3.14.

@end deffn

The @code{run*} functions and @ref{4fa,,set_trace()} are aliases for instantiating the
@ref{4fb,,Pdb} class and calling the method of the same name.  If you want to
access further features, you have to do this yourself:

@geindex Pdb (κλάση σε pdb)
@anchor{library/pdb pdb Pdb}@anchor{4fb}
@deffn {Κλάση} pdb.Pdb (completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True, mode=None, backend=None, colorize=False)

@code{Pdb} is the debugger class.

The `completekey', `stdin' and `stdout' arguments are passed to the
underlying @ref{1a78,,cmd.Cmd} class; see the description there.

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. @footnote{
Whether a frame is considered to originate in a certain module
is determined by the @code{__name__} in the frame globals.
}

By default, Pdb sets a handler for the SIGINT signal (which is sent when the
user presses @code{Ctrl}-@code{C} on the console) when you give a @ref{4a1c,,continue} command.
This allows you to break into the debugger again by pressing @code{Ctrl}-@code{C}.  If you
want Pdb not to touch the SIGINT handler, set `nosigint' to true.

The `readrc' argument defaults to true and controls whether Pdb will load
.pdbrc files from the filesystem.

The `mode' argument specifies how the debugger was invoked.
It impacts the workings of some debugger commands.
Valid values are @code{'inline'} (used by the breakpoint() builtin),
@code{'cli'} (used by the command line invocation)
or @code{None} (for backwards compatible behaviour, as before the `mode'
argument was added).

The `backend' argument specifies the backend to use for the debugger. If @code{None}
is passed, the default backend will be used. See @ref{4a27,,set_default_backend()}.
Otherwise the supported backends are @code{'settrace'} and @code{'monitoring'}.

The `colorize' argument, if set to @code{True}, will enable colorized output in the
debugger, if color is supported. This will highlight source code displayed in pdb.

Example call to enable tracing with `skip':

@example
import pdb; pdb.Pdb(skip=['django.*']).set_trace()
@end example

Raises an @ref{1e65,,auditing event} @code{pdb.Pdb} with no arguments.


Άλλαξε στην έκδοση 3.1: Added the `skip' parameter.



Άλλαξε στην έκδοση 3.2: Added the `nosigint' parameter.
Previously, a SIGINT handler was never set by Pdb.



Άλλαξε στην έκδοση 3.6: The `readrc' argument.



Added in version 3.14: Added the `mode' argument.



Added in version 3.14: Added the `backend' argument.



Added in version 3.14: Added the `colorize' argument.



Άλλαξε στην έκδοση 3.14: Inline breakpoints like @ref{4f9,,breakpoint()} or @ref{4fa,,pdb.set_trace()} will
always stop the program at calling frame, ignoring the `skip' pattern (if any).


@geindex run() (μέθοδος της pdb.Pdb)
@geindex runeval() (μέθοδος της pdb.Pdb)
@geindex runcall() (μέθοδος της pdb.Pdb)
@geindex set_trace() (μέθοδος της pdb.Pdb)
@anchor{library/pdb pdb Pdb run}@anchor{4a29}
@deffn {Μέθοδος} run (statement, globals=None, locals=None)
@anchor{library/pdb pdb Pdb runeval}@anchor{4a2a}
@deffnx {Μέθοδος} runeval (expression, globals=None, locals=None)
@anchor{library/pdb pdb Pdb runcall}@anchor{4a2b}
@deffnx {Μέθοδος} runcall (function, *args, **kwds)
@anchor{library/pdb pdb Pdb set_trace}@anchor{4fc}
@deffnx {Μέθοδος} set_trace ()

See the documentation for the functions explained above.
@end deffn
@end deffn

@node Debugger commands,,Command-line interface<7>,pdb — The Python Debugger
@anchor{library/pdb debugger-commands}@anchor{4a20}@anchor{library/pdb id2}@anchor{4a2c}
@subsubsection Debugger commands


The commands recognized by the debugger are listed below.  Most commands can be
abbreviated to one or two letters as indicated; e.g. @code{h(elp)} means that
either @code{h} or @code{help} can be used to enter the help command (but not @code{he}
or @code{hel}, nor @code{H} or @code{Help} or @code{HELP}).  Arguments to commands must be
separated by whitespace (spaces or tabs).  Optional arguments are enclosed in
square brackets (@code{[]}) in the command syntax; the square brackets must not be
typed.  Alternatives in the command syntax are separated by a vertical bar
(@code{|}).

Entering a blank line repeats the last command entered.  Exception: if the last
command was a @ref{4a2d,,list} command, the next 11 lines are listed.

Commands that the debugger doesn’t recognize are assumed to be Python statements
and are executed in the context of the program being debugged.  Python
statements can also be prefixed with an exclamation point (@code{!}).  This is a
powerful way to inspect the program being debugged; it is even possible to
change a variable or call a function.  When an exception occurs in such a
statement, the exception name is printed but the debugger’s state is not
changed.


Άλλαξε στην έκδοση 3.13: Expressions/Statements whose prefix is a pdb command are now correctly
identified and executed.


The debugger supports @ref{4a2e,,aliases}.  Aliases can have
parameters which allows one a certain level of adaptability to the context under
examination.

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 four 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

@item 
@code{$_asynctask}: the asyncio task if pdb stops in an async function
@end itemize


Added in version 3.12: Added the `convenience variable' feature.



Added in version 3.14: Added the @code{$_asynctask} convenience variable.


@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.


Άλλαξε στην έκδοση 3.2: @code{.pdbrc} can now contain commands that continue debugging, such as
@ref{4a1c,,continue} or @ref{4a24,,next}.  Previously, these commands had no
effect.



Άλλαξε στην έκδοση 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{4a2f}
@deffn {Pdbcommand} h(elp) [command]

Without argument, print the list of available commands.  With a `command' as
argument, print help about that command.  @code{help pdb} displays the full
documentation (the docstring of the @code{pdb} module).  Since the `command'
argument must be an identifier, @code{help exec} must be entered to get help on
the @code{!} command.
@end deffn

@geindex where (pdb command)
@anchor{library/pdb pdbcommand-where}@anchor{4a30}
@deffn {Pdbcommand} w(here) [count]

Print a stack trace, with the most recent frame at the bottom.  if `count'
is 0, print the current frame entry. If `count' is negative, print the least
recent - `count' frames. If `count' is positive, print the most recent
`count' frames.  An arrow (@code{>})
indicates the current frame, which determines the context of most commands.


Άλλαξε στην έκδοση 3.14: `count' argument is added.

@end deffn

@geindex down (pdb command)
@anchor{library/pdb pdbcommand-down}@anchor{4a31}
@deffn {Pdbcommand} d(own) [count]

Move the current frame `count' (default one) levels down in the stack trace
(to a newer frame).
@end deffn

@geindex up (pdb command)
@anchor{library/pdb pdbcommand-up}@anchor{4a32}
@deffn {Pdbcommand} u(p) [count]

Move the current frame `count' (default one) levels up in the stack trace (to
an older frame).
@end deffn

@geindex break (pdb command)
@anchor{library/pdb pdbcommand-break}@anchor{4a33}
@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{194,,sys.path}.  Acceptable 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.

If a second argument is present, it is an expression which must evaluate to
true before the breakpoint is honored.

Without argument, list all breaks, including for each breakpoint, the number
of times that breakpoint has been hit, the current ignore count, and the
associated condition if any.

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{4a34}
@deffn {Pdbcommand} tbreak [([filename:]lineno | function) [, condition]]

Temporary breakpoint, which is removed automatically when it is first hit.
The arguments are the same as for @ref{4a33,,break}.
@end deffn

@geindex clear (pdb command)
@anchor{library/pdb pdbcommand-clear}@anchor{4a35}
@deffn {Pdbcommand} cl(ear) [filename:lineno | bpnumber ...]

With a `filename:lineno' argument, clear all the breakpoints at this line.
With a space separated list of breakpoint numbers, clear those breakpoints.
Without argument, clear all breaks (but first ask confirmation).
@end deffn

@geindex disable (pdb command)
@anchor{library/pdb pdbcommand-disable}@anchor{4a36}
@deffn {Pdbcommand} disable bpnumber [bpnumber ...]

Disable the breakpoints given as a space separated list of breakpoint
numbers.  Disabling a breakpoint means it cannot cause the program to stop
execution, but unlike clearing a breakpoint, it remains in the list of
breakpoints and can be (re-)enabled.
@end deffn

@geindex enable (pdb command)
@anchor{library/pdb pdbcommand-enable}@anchor{4a37}
@deffn {Pdbcommand} enable bpnumber [bpnumber ...]

Enable the breakpoints specified.
@end deffn

@geindex ignore (pdb command)
@anchor{library/pdb pdbcommand-ignore}@anchor{4a38}
@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{4a39}
@deffn {Pdbcommand} condition bpnumber [condition]

Set a new `condition' for the breakpoint, an expression which must evaluate
to true before the breakpoint is honored.  If `condition' is absent, any
existing condition is removed; i.e., the breakpoint is made unconditional.
@end deffn

@geindex commands (pdb command)
@anchor{library/pdb pdbcommand-commands}@anchor{4fe}
@deffn {Pdbcommand} commands [bpnumber]

Specify a list of commands for breakpoint number `bpnumber'.  The commands
themselves appear on the following lines.  Type a line containing just
@code{end} to terminate the commands. An example:

@example
(Pdb) commands 1
(com) p some_variable
(com) end
(Pdb)
@end example

To remove all commands from a breakpoint, type @code{commands} and follow it
immediately with @code{end}; that is, give no commands.

With no `bpnumber' argument, @code{commands} refers to the most recently set
breakpoint that still exists.

You can use breakpoint commands to start your program up again.  Simply use
the @ref{4a1c,,continue} command, or @ref{4a23,,step},
or any other command that resumes execution.

Specifying any command resuming execution
(currently @ref{4a1c,,continue}, @ref{4a23,,step}, @ref{4a24,,next},
@ref{4a3a,,return}, @ref{4a3b,,until}, @ref{4a3c,,jump}, @ref{4a3d,,quit} and their abbreviations)
terminates the command list (as if
that command was immediately followed by end). This is because any time you
resume execution (even with a simple next or step), you may encounter another
breakpoint—which could have its own command list, leading to ambiguities about
which list to execute.

If the list of commands contains the @code{silent} command, or a command that
resumes execution, then the breakpoint message containing information about
the frame is not displayed.


Άλλαξε στην έκδοση 3.14: Frame information will not be displayed if a command that resumes execution
is present in the command list.

@end deffn

@geindex step (pdb command)
@anchor{library/pdb pdbcommand-step}@anchor{4a23}
@deffn {Pdbcommand} s(tep)

Execute the current line, stop at the first possible occasion (either in a
function that is called or on the next line in the current function).
@end deffn

@geindex next (pdb command)
@anchor{library/pdb pdbcommand-next}@anchor{4a24}
@deffn {Pdbcommand} n(ext)

Continue execution until the next line in the current function is reached or
it returns.  (The difference between @ref{4a24,,next} and @ref{4a23,,step} is
that @code{step} stops inside a called function, while @code{next}
executes called functions at (nearly) full speed, only stopping at the next
line in the current function.)
@end deffn

@geindex until (pdb command)
@anchor{library/pdb pdbcommand-until}@anchor{4a3b}
@deffn {Pdbcommand} unt(il) [lineno]

Without argument, continue execution until the line with a number greater
than the current one is reached.

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.


Άλλαξε στην έκδοση 3.2: Allow giving an explicit line number.

@end deffn

@geindex return (pdb command)
@anchor{library/pdb pdbcommand-return}@anchor{4a3a}
@deffn {Pdbcommand} r(eturn)

Continue execution until the current function returns.
@end deffn

@geindex continue (pdb command)
@anchor{library/pdb pdbcommand-continue}@anchor{4a1c}
@deffn {Pdbcommand} c(ont(inue))

Continue execution, only stop when a breakpoint is encountered.
@end deffn

@geindex jump (pdb command)
@anchor{library/pdb pdbcommand-jump}@anchor{4a3c}
@deffn {Pdbcommand} j(ump) lineno

Set the next line that will be executed.  Only available in the bottom-most
frame.  This lets you jump back and execute code again, or jump forward to
skip code that you don’t want to run.

It should be noted that not all jumps are allowed – for instance it is not
possible to jump into the middle of a @ref{321,,for} loop or out of a
@ref{44c,,finally} clause.
@end deffn

@geindex list (pdb command)
@anchor{library/pdb pdbcommand-list}@anchor{4a2d}
@deffn {Pdbcommand} l(ist) [first[, last]]

List source code for the current file.  Without arguments, list 11 lines
around the current line or continue the previous listing.  With @code{.} as
argument, list 11 lines around the current line.  With one argument,
list 11 lines around at that line.  With two arguments, list the given range;
if the second argument is less than the first, it is interpreted as a count.

The current line in the current frame is indicated by @code{->}.  If an
exception is being debugged, the line where the exception was originally
raised or propagated is indicated by @code{>>}, if it differs from the current
line.


Άλλαξε στην έκδοση 3.2: Added the @code{>>} marker.

@end deffn

@geindex ll (pdb command)
@anchor{library/pdb pdbcommand-ll}@anchor{4a3e}
@deffn {Pdbcommand} ll | longlist

List all source code for the current function or frame.  Interesting lines
are marked as for @ref{4a2d,,list}.


Added in version 3.2.

@end deffn

@geindex args (pdb command)
@anchor{library/pdb pdbcommand-args}@anchor{4a3f}
@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{1320}
@deffn {Pdbcommand} p expression

Evaluate `expression' in the current context and print its value.

@cartouche
@quotation Σημείωση 
@code{print()} can also be used, but is not a debugger command — this executes the
Python @ref{131f,,print()} function.
@end quotation
@end cartouche
@end deffn

@geindex pp (pdb command)
@anchor{library/pdb pdbcommand-pp}@anchor{4a40}
@deffn {Pdbcommand} pp expression

Like the @ref{1320,,p} command, except the value of `expression' is
pretty-printed using the @ref{b3,,pprint} module.
@end deffn

@geindex whatis (pdb command)
@anchor{library/pdb pdbcommand-whatis}@anchor{4a41}
@deffn {Pdbcommand} whatis expression

Print the type of `expression'.
@end deffn

@geindex source (pdb command)
@anchor{library/pdb pdbcommand-source}@anchor{4a42}
@deffn {Pdbcommand} source expression

Try to get source code of `expression' and display it.


Added in version 3.2.

@end deffn

@geindex display (pdb command)
@anchor{library/pdb pdbcommand-display}@anchor{4fd}
@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 Σημείωση 
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

Example:

@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


Added in version 3.2.

@end deffn

@geindex undisplay (pdb command)
@anchor{library/pdb pdbcommand-undisplay}@anchor{4a43}
@deffn {Pdbcommand} undisplay [expression]

Do not display `expression' anymore in the current frame.  Without
`expression', clear all display expressions for the current frame.


Added in version 3.2.

@end deffn

@geindex interact (pdb command)
@anchor{library/pdb pdbcommand-interact}@anchor{4a44}
@deffn {Pdbcommand} interact

Start an interactive interpreter (using the @ref{1b,,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 Σημείωση 
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


Added in version 3.2.



Άλλαξε στην έκδοση 3.13: @code{exit()} and @code{quit()} can be used to exit the @ref{4a44,,interact}
command.



Άλλαξε στην έκδοση 3.13: @ref{4a44,,interact} directs its output to the debugger’s
output channel rather than @ref{d05,,sys.stderr}.

@end deffn

@geindex alias (pdb command)
@anchor{library/pdb debugger-aliases}@anchor{4a2e}@anchor{library/pdb pdbcommand-alias}@anchor{4a45}
@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.

Aliases may be nested and can contain anything that can be legally typed at
the pdb prompt.  Note that internal pdb commands `can' be overridden by
aliases.  Such a command is then hidden until the alias is removed.  Aliasing
is recursively applied to the first word of the command line; all other words
in the line are left alone.

As an example, here are two useful aliases (especially when placed in the
@code{.pdbrc} file):

@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{4a46}
@deffn {Pdbcommand} unalias name

Delete the specified alias `name'.
@end deffn

@geindex ! (pdb command)
@anchor{library/pdb pdbcommand-0}@anchor{4a47}
@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{6b5,,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{4a48}
@deffn {Pdbcommand} run [args ...]
@anchor{library/pdb pdbcommand-restart}@anchor{4a49}
@deffnx {Pdbcommand} restart [args ...]

Restart the debugged Python program.  If `args' is supplied, it is split
with @ref{cc,,shlex} and the result is used as the new @ref{1609,,sys.argv}.
History, breakpoints, actions and debugger options are preserved.
@ref{4a49,,restart} is an alias for @ref{4a48,,run}.


Άλλαξε στην έκδοση 3.14: @ref{4a48,,run} and @ref{4a49,,restart} commands are disabled when the
debugger is invoked in @code{'inline'} mode.

@end deffn

@geindex quit (pdb command)
@anchor{library/pdb pdbcommand-quit}@anchor{4a3d}
@deffn {Pdbcommand} q(uit)

Quit from the debugger.  The program being executed is aborted.
An end-of-file input is equivalent to @ref{4a3d,,quit}.

A confirmation prompt will be shown if the debugger is invoked in
@code{'inline'} mode. Either @code{y}, @code{Y}, @code{<Enter>} or @code{EOF}
will confirm the quit.


Άλλαξε στην έκδοση 3.14: A confirmation prompt will be shown if the debugger is invoked in
@code{'inline'} mode. After the confirmation, the debugger will call
@ref{4ff,,sys.exit()} immediately, instead of raising @ref{500,,bdb.BdbQuit}
in the next trace event.

@end deffn

@geindex debug (pdb command)
@anchor{library/pdb pdbcommand-debug}@anchor{4a4a}
@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{4a4b}
@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{743}
@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{exceptions <number>} to switch to that exception.

Example:

@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


Added in version 3.13.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node profiling — Python profilers,pstats — Statistics for profilers,pdb — The Python Debugger,Debugging and profiling
@anchor{library/profiling doc}@anchor{4a4c}@anchor{library/profiling module-profiling}@anchor{b5}@anchor{library/profiling profiling-module}@anchor{4a4d}@anchor{library/profiling profiling-python-profilers}@anchor{4a4e}@anchor{library/profiling translation-repo}@anchor{4a4f}
@subsection @code{profiling} — Python profilers


@geindex module; profiling


Added in version 3.15.


`Source code:' Lib/profiling/@footnote{https://github.com/python/cpython/tree/main/Lib/profiling/}


__________________________________________________________________


@geindex statistical profiling
@geindex profiling@comma{} statistical
@geindex deterministic profiling
@geindex profiling@comma{} deterministic

@menu
* Introduction to profiling:: 
* Choosing a profiler:: 
* Quick start:: 
* Understanding profile output:: 
* Legacy compatibility:: 

@end menu

@node Introduction to profiling,Choosing a profiler,,profiling — Python profilers
@anchor{library/profiling introduction-to-profiling}@anchor{4a50}
@subsubsection Introduction to profiling


A `profile' is a set of statistics that describes how often and for how
long various parts of a program execute. These statistics help identify
performance bottlenecks and guide optimization efforts. Python provides two
fundamentally different approaches to collecting this information: statistical
sampling and deterministic tracing.

The @code{profiling} package organizes Python’s built-in profiling tools under
a single namespace. It contains two submodules, each implementing a different
profiling methodology:


@table @asis

@item @ref{b6,,profiling.sampling}

A statistical profiler that periodically samples the call stack. Run scripts
directly or attach to running processes by PID. Provides multiple output
formats (flame graphs, heatmaps, Firefox Profiler), GIL analysis, GC tracking,
and multiple profiling modes (wall-clock, CPU, GIL) with virtually no overhead.

@item @ref{b7,,profiling.tracing}

A deterministic profiler that traces every function call, return, and
exception event. Provides exact call counts and precise timing information,
capturing every invocation including very fast functions.
@end table

@cartouche
@quotation Σημείωση 
The profiler modules are designed to provide an execution profile for a
given program, not for benchmarking purposes. For benchmarking, use the
@ref{f8,,timeit} module, which provides reasonably accurate timing
measurements. This distinction is particularly important when comparing
Python code against C code: deterministic profilers introduce overhead for
Python code but not for C-level functions, which can skew comparisons.
@end quotation
@end cartouche

@node Choosing a profiler,Quick start,Introduction to profiling,profiling — Python profilers
@anchor{library/profiling choosing-a-profiler}@anchor{4a51}@anchor{library/profiling id1}@anchor{4a52}
@subsubsection Choosing a profiler


For most performance analysis, use the statistical profiler
(@ref{b6,,profiling.sampling}). It has minimal overhead, works for both development
and production, and provides rich visualization options including flame graphs,
heatmaps, GIL analysis, and more.

Use the deterministic profiler (@ref{b7,,profiling.tracing}) when you need `exact
call counts' and cannot afford to miss any function calls. Since it instruments
every function call and return, it will capture even very fast functions that
complete between sampling intervals. The tradeoff is higher overhead.

The following table summarizes the key differences:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Feature

@tab

Statistical sampling
(@ref{b6,,profiling.sampling})

@tab

Deterministic
(@ref{b7,,profiling.tracing})

@item

`Overhead'

@tab

Virtually none

@tab

Moderate

@item

`Accuracy'

@tab

Statistical estimate

@tab

Exact call counts

@item

`Output formats'

@tab

pstats, flame graph, heatmap,
gecko, collapsed

@tab

pstats

@item

`Profiling modes'

@tab

Wall-clock, CPU, GIL

@tab

Wall-clock

@item

`Special frames'

@tab

GC, native (C extensions)

@tab

N/A

@item

`Attach to PID'

@tab

Yes

@tab

No

@end multitable


@menu
* When to use statistical sampling:: 
* When to use deterministic tracing:: 

@end menu

@node When to use statistical sampling,When to use deterministic tracing,,Choosing a profiler
@anchor{library/profiling when-to-use-statistical-sampling}@anchor{4a53}
@subsubsection When to use statistical sampling


The statistical profiler (@ref{b6,,profiling.sampling}) is recommended for most
performance analysis tasks. Use it the same way you would use
@ref{b7,,profiling.tracing}:

@example
python -m profiling.sampling run script.py
@end example

One of the main strengths of the sampling profiler is its variety of output
formats. Beyond traditional pstats tables, it can generate interactive
flame graphs that visualize call hierarchies, line-level source heatmaps that
show exactly where time is spent in your code, and Firefox Profiler output for
timeline-based analysis.

The profiler also provides insight into Python interpreter behavior that
deterministic profiling cannot capture. Use @code{--mode gil} to identify GIL
contention in multi-threaded code, @code{--mode cpu} to measure actual CPU time
excluding I/O waits, or inspect @code{<GC>} frames to understand garbage collection
overhead. The @code{--native} option reveals time spent in C extensions, helping
distinguish Python overhead from library performance.

For multi-threaded applications, the @code{-a} option samples all threads
simultaneously, showing how work is distributed. And for production debugging,
the @code{attach} command connects to any running Python process by PID without
requiring a restart or code changes.

@node When to use deterministic tracing,,When to use statistical sampling,Choosing a profiler
@anchor{library/profiling when-to-use-deterministic-tracing}@anchor{4a54}
@subsubsection When to use deterministic tracing


The deterministic profiler (@ref{b7,,profiling.tracing}) instruments every function
call and return. This approach has higher overhead than sampling, but guarantees
complete coverage of program execution.

The primary reason to choose deterministic tracing is when you need exact call
counts. Statistical profiling estimates frequency based on sampling, which may
undercount short-lived functions that complete between samples. If you need to
verify that an optimization actually reduced the number of function calls, or
if you want to trace the complete call graph to understand caller-callee
relationships, deterministic tracing is the right choice.

Deterministic tracing also excels at capturing functions that execute in
microseconds. Such functions may not appear frequently enough in statistical
samples, but deterministic tracing records every invocation regardless of
duration.

@node Quick start,Understanding profile output,Choosing a profiler,profiling — Python profilers
@anchor{library/profiling quick-start}@anchor{4a55}
@subsubsection Quick start


This section provides the minimal steps needed to start profiling. For complete
documentation, see the dedicated pages for each profiler.

@menu
* Statistical profiling:: 
* Deterministic profiling:: 

@end menu

@node Statistical profiling,Deterministic profiling,,Quick start
@anchor{library/profiling statistical-profiling}@anchor{4a56}
@subsubsection Statistical profiling


To profile a script, use the @ref{b6,,profiling.sampling} module with the @code{run}
command:

@example
python -m profiling.sampling run script.py
python -m profiling.sampling run -m mypackage.module
@end example

This runs the script under the profiler and prints a summary of where time was
spent. For an interactive flame graph:

@example
python -m profiling.sampling run --flamegraph script.py
@end example

To profile an already-running process, use the @code{attach} command with the
process ID:

@example
python -m profiling.sampling attach 1234
@end example

For custom settings, specify the sampling interval (in microseconds) and
duration (in seconds):

@example
python -m profiling.sampling run -i 50 -d 30 script.py
@end example

@node Deterministic profiling,,Statistical profiling,Quick start
@anchor{library/profiling deterministic-profiling}@anchor{4a57}
@subsubsection Deterministic profiling


To profile a script from the command line:

@example
python -m profiling.tracing script.py
@end example

To profile a piece of code programmatically:

@example
import profiling.tracing
profiling.tracing.run('my_function()')
@end example

This executes the given code under the profiler and prints a summary showing
exact function call counts and timing.

@node Understanding profile output,Legacy compatibility,Quick start,profiling — Python profilers
@anchor{library/profiling profile-output}@anchor{4a58}@anchor{library/profiling understanding-profile-output}@anchor{4a59}
@subsubsection Understanding profile output


Both profilers collect function-level statistics, though they present them in
different formats. The sampling profiler offers multiple visualizations
(flame graphs, heatmaps, Firefox Profiler, pstats tables), while the
deterministic profiler produces pstats-compatible output. Regardless of format,
the underlying concepts are the same.

Key profiling concepts:


@table @asis

@item `Direct time' (also called `self time' or `tottime')

Time spent executing code in the function itself, excluding time spent in
functions it called. High direct time indicates the function contains
expensive operations.

@item `Cumulative time' (also called `total time' or `cumtime')

Time spent in the function and all functions it called. This measures the
total cost of calling a function, including its entire call subtree.

@item `Call count' (also called `ncalls' or `samples')

How many times the function was called (deterministic) or sampled
(statistical). In deterministic profiling, this is exact. In statistical
profiling, it represents the number of times the function appeared in a
stack sample.

@item `Primitive calls'

Calls that are not induced by recursion. When a function recurses, the total
call count includes recursive invocations, but primitive calls counts only
the initial entry. Displayed as @code{total/primitive} (for example, @code{3/1}
means three total calls, one primitive).

@item `Caller/Callee relationships'

Which functions called a given function (callers) and which functions it
called (callees). Flame graphs visualize this as nested rectangles; pstats
can display it via the @ref{4a5a,,print_callers()} and
@ref{4a5b,,print_callees()} methods.
@end table

@node Legacy compatibility,,Understanding profile output,profiling — Python profilers
@anchor{library/profiling legacy-compatibility}@anchor{4a5c}
@subsubsection Legacy compatibility


For backward compatibility, the @code{cProfile} module remains available as an
alias to @ref{b7,,profiling.tracing}. Existing code using @code{import cProfile} will
continue to work without modification in all future Python versions.


Αποσύρθηκε στην έκδοση 3.15: The pure Python @ref{b4,,profile} module is deprecated and will be removed in
Python 3.17. Use @ref{b7,,profiling.tracing} (or its alias @code{cProfile})
instead. See @code{profile} for migration guidance.



@subsubheading Δείτε επίσης



@table @asis

@item @ref{b6,,profiling.sampling}

Statistical sampling profiler with flame graphs, heatmaps, and GIL analysis.
Recommended for most users.

@item @ref{b7,,profiling.tracing}

Deterministic tracing profiler for exact call counts.

@item @ref{b8,,pstats}

Statistics analysis and formatting for profile data.

@item @ref{f8,,timeit}

Module for measuring execution time of small code snippets.
@end table


@subsubheading Submodules


@menu
* profiling.tracing — Deterministic profiler: profiling tracing — Deterministic profiler. 
* profiling.sampling — Statistical profiler: profiling sampling — Statistical profiler. 

@end menu

@node profiling tracing — Deterministic profiler,profiling sampling — Statistical profiler,,Legacy compatibility
@anchor{library/profiling tracing doc}@anchor{4a5d}@anchor{library/profiling tracing module-profiling tracing}@anchor{b7}@anchor{library/profiling tracing profiling-tracing}@anchor{4a5e}@anchor{library/profiling tracing profiling-tracing-deterministic-profiler}@anchor{4a5f}
@subsubsection @code{profiling.tracing} — Deterministic profiler


@geindex module; profiling.tracing


Added in version 3.15.


`Source code:' Lib/profiling/tracing/@footnote{https://github.com/python/cpython/tree/main/Lib/profiling/tracing/}


__________________________________________________________________


The @code{profiling.tracing} module provides deterministic profiling of Python
programs. It monitors every function call, function return, and exception event,
recording precise timing for each. This approach provides exact call counts and
complete visibility into program execution, making it ideal for development and
testing scenarios.

@cartouche
@quotation Σημείωση 
This module is also available as @code{cProfile} for backward compatibility.
The @code{cProfile} name will continue to work in all future Python versions.
Use whichever import style suits your codebase:

@example
# Preferred (new style)
import profiling.tracing
profiling.tracing.run('my_function()')

# Also works (backward compatible)
import cProfile
cProfile.run('my_function()')
@end example
@end quotation
@end cartouche

@menu
* What is deterministic profiling?:: 
* Command-line interface: Command-line interface<8>. 
* Programmatic usage examples:: 
* Module reference:: 
* Using a custom timer:: 
* Limitations:: 

@end menu

@node What is deterministic profiling?,Command-line interface<8>,,profiling tracing — Deterministic profiler
@anchor{library/profiling tracing what-is-deterministic-profiling}@anchor{4a60}
@subsubsection What is deterministic profiling?


`Deterministic profiling' captures every function call, function return,
and exception event during program execution. The profiler measures the precise
time intervals between these events, providing exact statistics about how the
program behaves.

In contrast to @ref{4a61,,statistical profiling}, which samples
the call stack periodically to estimate where time is spent, deterministic
profiling records every event. This means you get exact call counts rather than
statistical approximations. The trade-off is that instrumenting every event
introduces overhead that can slow down program execution.

Python’s interpreted nature makes deterministic profiling practical. The
interpreter already dispatches events for function calls and returns, so the
profiler can hook into this mechanism without requiring code modification. The
overhead tends to be moderate relative to the inherent cost of interpretation,
making deterministic profiling suitable for most development workflows.

Deterministic profiling helps answer questions like:


@itemize -

@item 
How many times was this function called?

@item 
What is the complete call graph of my program?

@item 
Which functions are called by a particular function?

@item 
Are there unexpected function calls happening?
@end itemize

Call count statistics can identify bugs (surprising counts) and inline
expansion opportunities (high call counts). Internal time statistics reveal
«hot loops» that warrant optimization. Cumulative time statistics help identify
algorithmic inefficiencies. The handling of cumulative times in this profiler
allows direct comparison of recursive and iterative implementations.

@node Command-line interface<8>,Programmatic usage examples,What is deterministic profiling?,profiling tracing — Deterministic profiler
@anchor{library/profiling tracing command-line-interface}@anchor{4a62}@anchor{library/profiling tracing profiling-tracing-cli}@anchor{4a63}
@subsubsection Command-line interface


The @code{profiling.tracing} module can be invoked as a script to profile
another script or module:

@example
python -m profiling.tracing [-o output_file] [-s sort_order] (-m module | script.py)
@end example

This runs the specified script or module under the profiler and prints the
results to standard output (or saves them to a file).

@geindex profiling.tracing command line option; -o
@anchor{library/profiling tracing cmdoption-profiling tracing-o}@anchor{4a64}
@deffn {Option} @w{-}o <output_file>

Write the profile results to a file instead of standard output. The output
file can be read by the @ref{b8,,pstats} module for later analysis.
@end deffn

@geindex profiling.tracing command line option; -s
@anchor{library/profiling tracing cmdoption-profiling tracing-s}@anchor{4a65}
@deffn {Option} @w{-}s <sort_order>

Sort the output by the specified key. This accepts any of the sort keys
recognized by @ref{4a66,,pstats.Stats.sort_stats()}, such as @code{cumulative},
@code{time}, @code{calls}, or @code{name}. This option only applies when
@ref{4a64,,-o} is not specified.
@end deffn

@geindex profiling.tracing command line option; -m
@anchor{library/profiling tracing cmdoption-profiling tracing-m}@anchor{4a67}
@deffn {Option} @w{-}m <module>

Profile a module instead of a script. The module is located using the
standard import mechanism.


Added in version 3.7: The @code{-m} option for @code{cProfile}.



Added in version 3.8: The @code{-m} option for @ref{b4,,profile}.

@end deffn

@node Programmatic usage examples,Module reference,Command-line interface<8>,profiling tracing — Deterministic profiler
@anchor{library/profiling tracing programmatic-usage-examples}@anchor{4a68}
@subsubsection Programmatic usage examples


For more control over profiling, use the module’s functions and classes
directly.

@menu
* Basic profiling:: 
* Using the Profile class:: 

@end menu

@node Basic profiling,Using the Profile class,,Programmatic usage examples
@anchor{library/profiling tracing basic-profiling}@anchor{4a69}
@subsubsection Basic profiling


The simplest approach uses the @code{run()} function:

@example
import profiling.tracing
profiling.tracing.run('my_function()')
@end example

This profiles the given code string and prints a summary to standard output.
To save results for later analysis:

@example
profiling.tracing.run('my_function()', 'output.prof')
@end example

@node Using the Profile class,,Basic profiling,Programmatic usage examples
@anchor{library/profiling tracing using-the-profile-class}@anchor{4a6a}
@subsubsection Using the @code{Profile} class


The @code{Profile} class provides fine-grained control:

@example
import profiling.tracing
import pstats
from io import StringIO

pr = profiling.tracing.Profile()
pr.enable()
# ... code to profile ...
pr.disable()

# Print results
s = StringIO()
ps = pstats.Stats(pr, stream=s).sort_stats(pstats.SortKey.CUMULATIVE)
ps.print_stats()
print(s.getvalue())
@end example

The @code{Profile} class also works as a context manager:

@example
import profiling.tracing

with profiling.tracing.Profile() as pr:
    # ... code to profile ...

pr.print_stats()
@end example

@node Module reference,Using a custom timer,Programmatic usage examples,profiling tracing — Deterministic profiler
@anchor{library/profiling tracing module-reference}@anchor{4a6b}
@subsubsection Module reference


@geindex run() (στη μονάδα profiling.tracing)
@anchor{library/profiling tracing profiling tracing run}@anchor{4a6c}
@deffn {Συνάρτηση} profiling.tracing.run (command, filename=None, sort=-1)

Profile execution of a command and print or save the results.

This function executes the `command' string using @ref{185,,exec()} in the
@code{__main__} module’s namespace:

@example
exec(command, __main__.__dict__, __main__.__dict__)
@end example

If `filename' is not provided, the function creates a @ref{4a6d,,pstats.Stats}
instance and prints a summary to standard output. If `filename' is
provided, the raw profile data is saved to that file for later analysis
with @ref{b8,,pstats}.

The `sort' argument specifies the sort order for printed output, accepting
any value recognized by @ref{4a66,,pstats.Stats.sort_stats()}.
@end deffn

@geindex runctx() (στη μονάδα profiling.tracing)
@anchor{library/profiling tracing profiling tracing runctx}@anchor{4a6e}
@deffn {Συνάρτηση} profiling.tracing.runctx (command, globals, locals, filename=None, sort=-1)

Profile execution of a command with explicit namespaces.

Like @ref{4a6c,,run()}, but executes the command with the specified `globals'
and `locals' mappings instead of using the @code{__main__} module’s namespace:

@example
exec(command, globals, locals)
@end example
@end deffn

@geindex Profile (κλάση σε profiling.tracing)
@anchor{library/profiling tracing profiling tracing Profile}@anchor{4a6f}
@deffn {Κλάση} profiling.tracing.Profile (timer=None, timeunit=0.0, subcalls=True, builtins=True)

A profiler object that collects execution statistics.

The optional `timer' argument specifies a custom timing function. If not
provided, the profiler uses a platform-appropriate default timer. When
supplying a custom timer, it must return a single number representing the
current time. If the timer returns integers, use `timeunit' to specify the
duration of one time unit (for example, @code{0.001} for milliseconds).

The `subcalls' argument controls whether the profiler tracks call
relationships between functions. The `builtins' argument controls whether
built-in functions are profiled.


Άλλαξε στην έκδοση 3.8: Added context manager support.


@geindex enable() (μέθοδος της profiling.tracing.Profile)
@anchor{library/profiling tracing profiling tracing Profile enable}@anchor{4a70}
@deffn {Μέθοδος} enable ()

Start collecting profiling data.
@end deffn

@geindex disable() (μέθοδος της profiling.tracing.Profile)
@anchor{library/profiling tracing profiling tracing Profile disable}@anchor{4a71}
@deffn {Μέθοδος} disable ()

Stop collecting profiling data.
@end deffn

@geindex create_stats() (μέθοδος της profiling.tracing.Profile)
@anchor{library/profiling tracing profiling tracing Profile create_stats}@anchor{4a72}
@deffn {Μέθοδος} create_stats ()

Stop collecting data and record the results internally as the current
profile.
@end deffn

@geindex print_stats() (μέθοδος της profiling.tracing.Profile)
@anchor{library/profiling tracing profiling tracing Profile print_stats}@anchor{4a73}
@deffn {Μέθοδος} print_stats (sort=-1)

Create a @ref{4a6d,,pstats.Stats} object from the current profile and print
the results to standard output.

The `sort' argument specifies the sorting order. It accepts a single
key or a tuple of keys for multi-level sorting, using the same values
as @ref{4a66,,pstats.Stats.sort_stats()}.


Added in version 3.13: Support for a tuple of sort keys.

@end deffn

@geindex dump_stats() (μέθοδος της profiling.tracing.Profile)
@anchor{library/profiling tracing profiling tracing Profile dump_stats}@anchor{4a74}
@deffn {Μέθοδος} dump_stats (filename)

Write the current profile data to `filename'. The file can be read by
@ref{4a6d,,pstats.Stats} for later analysis.
@end deffn

@geindex run() (μέθοδος της profiling.tracing.Profile)
@anchor{library/profiling tracing profiling tracing Profile run}@anchor{4a75}
@deffn {Μέθοδος} run (cmd)

Profile the command string via @ref{185,,exec()}.
@end deffn

@geindex runctx() (μέθοδος της profiling.tracing.Profile)
@anchor{library/profiling tracing profiling tracing Profile runctx}@anchor{4a76}
@deffn {Μέθοδος} runctx (cmd, globals, locals)

Profile the command string via @ref{185,,exec()} with the specified
namespaces.
@end deffn

@geindex runcall() (μέθοδος της profiling.tracing.Profile)
@anchor{library/profiling tracing profiling tracing Profile runcall}@anchor{4a77}
@deffn {Μέθοδος} runcall (func, /, *args, **kwargs)

Profile a function call. Returns whatever `func' returns:

@example
result = pr.runcall(my_function, arg1, arg2, keyword=value)
@end example
@end deffn
@end deffn

@cartouche
@quotation Σημείωση 
Profiling requires that the profiled code returns normally. If the
interpreter terminates (for example, via @ref{4ff,,sys.exit()}) during
profiling, no results will be available.
@end quotation
@end cartouche

@node Using a custom timer,Limitations,Module reference,profiling tracing — Deterministic profiler
@anchor{library/profiling tracing using-a-custom-timer}@anchor{4a78}
@subsubsection Using a custom timer


The @ref{4a6f,,Profile} class accepts a custom timing function, allowing you to
measure different aspects of execution such as wall-clock time or CPU time.
Pass the timing function to the constructor:

@example
pr = profiling.tracing.Profile(my_timer_function)
@end example

The timer function must return a single number representing the current time.
If it returns integers, also specify `timeunit' to indicate the duration of
one unit:

@example
# Timer returns time in milliseconds
pr = profiling.tracing.Profile(my_ms_timer, 0.001)
@end example

For best performance, the timer function should be as fast as possible. The
profiler calls it frequently, so timer overhead directly affects profiling
overhead.

The @ref{f7,,time} module provides several functions suitable for use as custom
timers:


@itemize -

@item 
@ref{e49,,time.perf_counter()} for high-resolution wall-clock time

@item 
@ref{e4a,,time.process_time()} for CPU time (excluding sleep)

@item 
@ref{75d,,time.monotonic()} for monotonic clock time
@end itemize

@node Limitations,,Using a custom timer,profiling tracing — Deterministic profiler
@anchor{library/profiling tracing limitations}@anchor{4a79}
@subsubsection Limitations


Deterministic profiling has inherent limitations related to timing accuracy.

The underlying timer typically has a resolution of about one millisecond.
Measurements cannot be more accurate than this resolution. With enough
measurements, timing errors tend to average out, but individual measurements
may be imprecise.

There is also latency between when an event occurs and when the profiler
captures the timestamp. Similarly, there is latency after reading the
timestamp before user code resumes. Functions called frequently accumulate
this latency, which can make them appear slower than they actually are. This
error is typically less than one clock tick per call but can become
significant for functions called many times.

The @code{profiling.tracing} module (and its @code{cProfile} alias) is
implemented as a C extension with low overhead, so these timing issues are
less pronounced than with the deprecated pure Python @ref{b4,,profile} module.


@subsubheading Δείτε επίσης



@table @asis

@item @ref{b5,,profiling}

Overview of Python profiling tools and guidance on choosing a profiler.

@item @ref{b6,,profiling.sampling}

Statistical sampling profiler for production use.

@item @ref{b8,,pstats}

Statistics analysis and formatting for profile data.

@item @ref{b4,,profile}

Deprecated pure Python profiler (includes calibration documentation).
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node profiling sampling — Statistical profiler,,profiling tracing — Deterministic profiler,Legacy compatibility
@anchor{library/profiling sampling doc}@anchor{4a7a}@anchor{library/profiling sampling module-profiling sampling}@anchor{b6}@anchor{library/profiling sampling profiling-sampling}@anchor{4a61}@anchor{library/profiling sampling profiling-sampling-statistical-profiler}@anchor{4a7b}@anchor{library/profiling sampling translation-repo}@anchor{4a7c}
@subsubsection @code{profiling.sampling} — Statistical profiler


@geindex module; profiling.sampling


Added in version 3.15.


`Source code:' Lib/profiling/sampling/@footnote{https://github.com/python/cpython/tree/main/Lib/profiling/sampling/}


__________________________________________________________________


@image{python-figures/tachyon-logo,,,Tachyon logo,png}

The @code{profiling.sampling} module, named `Tachyon', provides statistical
profiling of Python programs through periodic stack sampling. Tachyon can
run scripts directly or attach to any running Python process without requiring
code changes or restarts. Because sampling occurs externally to the target
process, overhead is virtually zero, making Tachyon suitable for both
development and production environments.

@menu
* What is statistical profiling?:: 
* Quick examples:: 
* Commands:: 
* Sampling configuration:: 
* Profiling modes:: 
* Output formats:: 
* Record and replay workflow:: 
* Live mode:: 
* Async-aware profiling:: 
* Command-line interface: Command-line interface<9>. 

@end menu

@node What is statistical profiling?,Quick examples,,profiling sampling — Statistical profiler
@anchor{library/profiling sampling what-is-statistical-profiling}@anchor{4a7d}
@subsubsection What is statistical profiling?


Statistical profiling builds a picture of program behavior by periodically
capturing snapshots of the call stack. Rather than instrumenting every function
call and return as deterministic profilers do, Tachyon reads the call stack at
regular intervals to record what code is currently running.

This approach rests on a simple principle: functions that consume significant
CPU time will appear frequently in the collected samples. By gathering thousands
of samples over a profiling session, Tachyon constructs an accurate statistical
estimate of where time is spent. The more samples collected, the
more precise this estimate becomes.


@cartouche
@quotation Σημείωση 
An interactive visualization of sampling profiling is available in the
HTML version of this documentation.
@end quotation
@end cartouche

@menu
* How time is estimated:: 
* When to use a different approach:: 

@end menu

@node How time is estimated,When to use a different approach,,What is statistical profiling?
@anchor{library/profiling sampling how-time-is-estimated}@anchor{4a7e}
@subsubsection How time is estimated


The time values shown in Tachyon’s output are `estimates derived from sample
counts', not direct measurements. Tachyon counts how many times each function
appears in the collected samples, then multiplies by the sampling interval to
estimate time.

For example, with a 10 kHz sampling rate over a 10-second profile,
Tachyon collects approximately 100,000 samples. If a function appears in 5,000
samples (5% of total), Tachyon estimates it consumed 5% of the 10-second
duration, or about 500 milliseconds. This is a statistical estimate, not a
precise measurement.

The accuracy of these estimates depends on sample count. With 100,000 samples,
a function showing 5% has a margin of error of roughly ±0.5%. With only 1,000
samples, the same 5% measurement could actually represent anywhere from 3% to
7% of real time.

This is why longer profiling durations and shorter sampling intervals produce
more reliable results—they collect more samples. For most performance
analysis, the default settings provide sufficient accuracy to identify
bottlenecks and guide optimization efforts.

Because sampling is statistical, results will vary slightly between runs. A
function showing 12% in one run might show 11% or 13% in the next. This is
normal and expected. Focus on the overall pattern rather than exact percentages,
and don’t worry about small variations between runs.

@node When to use a different approach,,How time is estimated,What is statistical profiling?
@anchor{library/profiling sampling when-to-use-a-different-approach}@anchor{4a7f}
@subsubsection When to use a different approach


Statistical sampling is not ideal for every situation.

For very short scripts that complete in under one second, the profiler may not
collect enough samples for reliable results. Use @ref{b7,,profiling.tracing}
instead, or run the script in a loop to extend profiling time.

When you need exact call counts, sampling cannot provide them. Sampling
estimates frequency from snapshots, so if you need to know precisely how many
times a function was called, use @ref{b7,,profiling.tracing}.

When comparing two implementations where the difference might be only 1-2%,
sampling noise can obscure real differences. Use @ref{f8,,timeit} for
micro-benchmarks or @ref{b7,,profiling.tracing} for precise measurements.

The key difference from @ref{b7,,profiling.tracing} is how measurement happens.
A tracing profiler instruments your code, recording every function call and
return. This provides exact call counts and precise timing but adds overhead
to every function call. A sampling profiler, by contrast, observes the program
from outside at fixed intervals without modifying its execution. Think of the
difference like this: tracing is like having someone follow you and write down
every step you take, while sampling is like taking photographs every second
and inferring your path from those snapshots.

This external observation model is what makes sampling profiling practical for
production use. The profiled program runs at full speed because there is no
instrumentation code running inside it, and the target process is never stopped
or paused during sampling—Tachyon reads the call stack directly from the
process’s memory while it continues to run. You can attach to a live server,
collect data, and detach without the application ever knowing it was observed.
The trade-off is that very short-lived functions may be missed if they happen
to complete between samples.

Statistical profiling excels at answering the question, «Where is my program
spending time?» It reveals hotspots and bottlenecks in production code where
deterministic profiling overhead would be unacceptable. For exact call counts
and complete call graphs, use @ref{b7,,profiling.tracing} instead.

@node Quick examples,Commands,What is statistical profiling?,profiling sampling — Statistical profiler
@anchor{library/profiling sampling quick-examples}@anchor{4a80}
@subsubsection Quick examples


Profile a script and see the results immediately:

@example
python -m profiling.sampling run script.py
@end example

Profile a module with arguments:

@example
python -m profiling.sampling run -m mypackage.module arg1 arg2
@end example

Generate an interactive flame graph:

@example
python -m profiling.sampling run --flamegraph -o profile.html script.py
@end example

Attach to a running process by PID:

@example
python -m profiling.sampling attach 12345
@end example

Print a single snapshot of a running process’s stack:

@example
python -m profiling.sampling dump 12345
@end example

Use live mode for real-time monitoring (press @code{q} to quit):

@example
python -m profiling.sampling run --live script.py
@end example

Profile for 60 seconds with a faster sampling rate:

@example
python -m profiling.sampling run -d 60 -r 20khz script.py
@end example

Generate a line-by-line heatmap:

@example
python -m profiling.sampling run --heatmap script.py
@end example

Enable opcode-level profiling to see which bytecode instructions are executing:

@example
python -m profiling.sampling run --opcodes --flamegraph script.py
@end example

@node Commands,Sampling configuration,Quick examples,profiling sampling — Statistical profiler
@anchor{library/profiling sampling commands}@anchor{4a81}
@subsubsection Commands


Tachyon operates through several subcommands. @code{run} and @code{attach} collect
samples over time; @code{dump} captures a single snapshot; @code{replay} converts
binary profiles to other formats.

@menu
* The run command:: 
* The attach command:: 
* The dump command:: 
* The replay command:: 
* Profiling in production:: 
* Platform requirements:: 
* Version compatibility:: 

@end menu

@node The run command,The attach command,,Commands
@anchor{library/profiling sampling the-run-command}@anchor{4a82}
@subsubsection The @code{run} command


The @code{run} command launches a Python script or module and profiles it from
startup:

@example
python -m profiling.sampling run script.py
python -m profiling.sampling run -m mypackage.module
@end example

When profiling a script, the profiler starts the target in a subprocess, waits
for it to initialize, then begins collecting samples. The @code{-m} flag
indicates that the target should be run as a module (equivalent to
@code{python -m}). Arguments after the target are passed through to the
profiled program:

@example
python -m profiling.sampling run script.py --config settings.yaml
@end example

@node The attach command,The dump command,The run command,Commands
@anchor{library/profiling sampling the-attach-command}@anchor{4a83}
@subsubsection The @code{attach} command


The @code{attach} command connects to an already-running Python process by its
process ID:

@example
python -m profiling.sampling attach 12345
@end example

This command is particularly valuable for investigating performance issues in
production systems. The target process requires no modification and need not
be restarted. The profiler attaches, collects samples for the specified
duration, then detaches and produces output.

@example
python -m profiling.sampling attach --live 12345
python -m profiling.sampling attach --flamegraph -d 30 -o profile.html 12345
@end example

On most systems, attaching to another process requires appropriate permissions.
See @ref{4a84,,Platform requirements} for platform-specific requirements.

@node The dump command,The replay command,The attach command,Commands
@anchor{library/profiling sampling dump-command}@anchor{4a85}@anchor{library/profiling sampling the-dump-command}@anchor{4a86}
@subsubsection The @code{dump} command


The @code{dump} command prints a single snapshot of a running process’s Python
stack and exits, similar to a traceback:

@example
python -m profiling.sampling dump 12345
@end example

Unlike @code{attach}, @code{dump} does not run a sampling loop: it reads the
stack once. This is useful for investigating hung or unresponsive
processes, or for answering «what is this process doing right now?».

The output mirrors a traceback (most recent call last) and annotates each
thread with its current state (main thread, has GIL, on CPU, waiting for
GIL, has exception, or idle):

@example
Stack dump for PID 12345, thread 140735 (main thread, has GIL, on CPU; most recent call last):
  File "server.py", line 28, in serve
    await handle_request(req)
  File "handler.py", line 91, in handle_request
    result = expensive_call(req)
@end example

When the target’s source files are readable, @code{dump} prints the source
line for each frame and highlights the executing expression.

Like @code{attach}, @code{dump} requires permission to read the target process’s
memory. See @ref{4a84,,Platform requirements}.

The @code{dump} command supports the following options:


@table @asis

@item @code{-a}, @code{--all-threads}

Dump every thread in the target process. Without this flag only the main
thread is shown.

@item @code{--native}

Include synthetic @code{<native>} frames marking transitions into C
extensions or other non-Python code.

@item @code{--no-gc}

Hide the synthetic @code{<GC>} frames that mark active garbage collection.

@item @code{--opcodes}

Annotate each frame with the bytecode opcode the thread is currently
executing (for example, @code{opcode=CALL_KW}). Useful for
instruction-level investigation, including identifying specializations
chosen by the adaptive interpreter.

@item @code{--async-aware}

Reconstruct stacks across @code{await} boundaries. @code{dump} walks the task
graph and emits one section per task, with @code{<task>} markers separating
coroutines awaiting each other.

@item @code{--async-mode @{running,all@}}

Controls which tasks are included when @code{--async-aware} is enabled.
@code{running} shows only the task currently executing on each thread;
@code{all} (the default for @code{dump}) also includes tasks suspended on a
wait. @code{attach}’s default for this flag is @code{running}; @code{dump}
defaults to @code{all} because a single snapshot is most useful when it
shows the full task graph.

@item @code{--blocking}

Pause every thread in the target while reading its stack and resume
them after. Guarantees a fully consistent snapshot at the cost of
briefly stopping the target. Without it, @code{dump} reads memory while
the target keeps running, which is faster but can occasionally produce
a torn stack.
@end table

@node The replay command,Profiling in production,The dump command,Commands
@anchor{library/profiling sampling replay-command}@anchor{4a87}@anchor{library/profiling sampling the-replay-command}@anchor{4a88}
@subsubsection The @code{replay} command


The @code{replay} command converts binary profile files to other output formats:

@example
python -m profiling.sampling replay profile.bin
python -m profiling.sampling replay --flamegraph -o profile.html profile.bin
@end example

This command is useful when you have captured profiling data in binary format
and want to analyze it later or convert it to a visualization format. Binary
profiles can be replayed multiple times to different formats without
re-profiling.

@example
# Convert binary to pstats (default, prints to stdout)
python -m profiling.sampling replay profile.bin

# Convert binary to flame graph
python -m profiling.sampling replay --flamegraph -o output.html profile.bin

# Convert binary to gecko format for Firefox Profiler
python -m profiling.sampling replay --gecko -o profile.json profile.bin

# Convert binary to heatmap
python -m profiling.sampling replay --heatmap -o my_heatmap profile.bin
@end example

@node Profiling in production,Platform requirements,The replay command,Commands
@anchor{library/profiling sampling profiling-in-production}@anchor{4a89}
@subsubsection Profiling in production


The sampling profiler is designed for production use. It imposes no measurable
overhead on the target process because it reads memory externally rather than
instrumenting code. The target application continues running at full speed and
is unaware it is being profiled.

When profiling production systems, keep these guidelines in mind:

Start with shorter durations (10-30 seconds) to get quick results, then extend
if you need more statistical accuracy. By default, profiling runs until the
target process completes, which is usually sufficient to identify major hotspots.

If possible, profile during representative load rather than peak traffic.
Profiles collected during normal operation are easier to interpret than those
collected during unusual spikes.

The profiler itself consumes some CPU on the machine where it runs (not on the
target process). On the same machine, this is typically negligible. When
profiling remote processes, network latency does not affect the target.

Results from production may differ from development due to different data
sizes, concurrent load, or caching effects. This is expected and is often
exactly what you want to capture.

@node Platform requirements,Version compatibility,Profiling in production,Commands
@anchor{library/profiling sampling platform-requirements}@anchor{4a8a}@anchor{library/profiling sampling profiling-permissions}@anchor{4a84}
@subsubsection Platform requirements


The profiler reads the target process’s memory to capture stack traces. This
requires elevated permissions on most operating systems.

`Linux'

On Linux, the profiler uses @code{ptrace} or @code{process_vm_readv} to read the
target process’s memory. This typically requires one of:


@itemize -

@item 
Running as root

@item 
Having the @code{CAP_SYS_PTRACE} capability

@item 
Adjusting the Yama ptrace scope: @code{/proc/sys/kernel/yama/ptrace_scope}
@end itemize

The default ptrace_scope of 1 restricts ptrace to parent processes only. To
allow attaching to any process owned by the same user, set it to 0:

@example
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
@end example

`macOS'

On macOS, the profiler uses @code{task_for_pid()} to access the target process.
This requires one of:


@itemize -

@item 
Running as root

@item 
The profiler binary having the @code{com.apple.security.cs.debugger} entitlement

@item 
System Integrity Protection (SIP) being disabled (not recommended)
@end itemize

`Windows'

On Windows, the profiler requires administrative privileges or the
@code{SeDebugPrivilege} privilege to read another process’s memory.

@node Version compatibility,,Platform requirements,Commands
@anchor{library/profiling sampling version-compatibility}@anchor{4a8b}
@subsubsection Version compatibility


The profiler and target process must run the same Python minor version (for
example, both Python 3.15). Attaching from Python 3.14 to a Python 3.15 process
is not supported.

Additional restrictions apply to pre-release Python versions: if either the
profiler or target is running a pre-release (alpha, beta, or release candidate),
both must run the exact same version.

On free-threaded Python builds, the profiler cannot attach from a free-threaded
build to a standard build, or vice versa.

@node Sampling configuration,Profiling modes,Commands,profiling sampling — Statistical profiler
@anchor{library/profiling sampling sampling-configuration}@anchor{4a8c}
@subsubsection Sampling configuration


Before exploring the various output formats and visualization options, it is
important to understand how to configure the sampling process itself. The
profiler offers several options that control how frequently samples are
collected, how long profiling runs, which threads are observed, and what
additional context is captured in each sample.

The default configuration works well for most use cases:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Default

@item

Default for @code{--sampling-rate} / @code{-r}

@tab

1 kHz

@item

Default for @code{--duration} / @code{-d}

@tab

Run to completion

@item

Default for @code{--all-threads} / @code{-a}

@tab

Main thread only

@item

Default for @code{--native}

@tab

No @code{<native>} frames (C code time attributed to caller)

@item

Default for @code{--no-gc}

@tab

@code{<GC>} frames included when garbage collection is active

@item

Default for @code{--mode}

@tab

Wall-clock mode (all samples recorded)

@item

Default for @code{--realtime-stats}

@tab

Disabled

@item

Default for @code{--subprocesses}

@tab

Disabled

@item

Default for @code{--blocking}

@tab

Disabled (non-blocking sampling)

@end multitable


@menu
* Sampling rate and duration:: 
* Thread selection:: 
* Blocking mode:: 
* Special frames:: 
* Opcode-aware profiling:: 
* Real-time statistics:: 
* Subprocess profiling:: 
* Sampling efficiency:: 

@end menu

@node Sampling rate and duration,Thread selection,,Sampling configuration
@anchor{library/profiling sampling sampling-rate-and-duration}@anchor{4a8d}
@subsubsection Sampling rate and duration


The two most fundamental parameters are the sampling rate and duration.
Together, these determine how many samples will be collected during a profiling
session.

The @ref{4a8e,,--sampling-rate} option (@ref{4a8e,,-r}) sets how frequently samples
are collected. The default is 1 kHz (1,000 samples per second):

@example
python -m profiling.sampling run -r 20khz script.py
@end example

Higher rates capture more samples and provide finer-grained data at the
cost of slightly higher profiler CPU usage. Lower rates reduce profiler
overhead but may miss short-lived functions. For most applications, the
default rate provides a good balance between accuracy and overhead.

The @ref{4a8f,,--duration} option (@ref{4a8f,,-d}) sets how long to profile in seconds. By
default, profiling continues until the target process exits or is interrupted:

@example
python -m profiling.sampling run -d 60 script.py
@end example

Specifying a duration is useful when attaching to long-running processes or when
you want to limit profiling to a specific time window. When profiling a script,
the default behavior of running to completion is usually what you want.

@node Thread selection,Blocking mode,Sampling rate and duration,Sampling configuration
@anchor{library/profiling sampling thread-selection}@anchor{4a90}
@subsubsection Thread selection


Python programs often use multiple threads, whether explicitly through the
@ref{f6,,threading} module or implicitly through libraries that manage thread
pools.

By default, the profiler samples only the main thread. The @ref{4a91,,--all-threads}
option (@ref{4a91,,-a}) enables sampling of all threads in the process:

@example
python -m profiling.sampling run -a script.py
@end example

Multi-thread profiling reveals how work is distributed across threads and can
identify threads that are blocked or starved. Each thread’s samples are
combined in the output, with the ability to filter by thread in some formats.
This option is particularly useful when investigating concurrency issues or
when work is distributed across a thread pool.

@node Blocking mode,Special frames,Thread selection,Sampling configuration
@anchor{library/profiling sampling blocking-mode}@anchor{4a92}@anchor{library/profiling sampling id1}@anchor{4a93}
@subsubsection Blocking mode


By default, Tachyon reads the target process’s memory without stopping it.
This non-blocking approach is ideal for most profiling scenarios because it
imposes virtually zero overhead on the target application: the profiled
program runs at full speed and is unaware it is being observed.

However, non-blocking sampling can occasionally produce incomplete or
inconsistent stack traces in applications with many generators or coroutines
that rapidly switch between yield points, or in programs with very fast-changing
call stacks where functions enter and exit between the start and end of a single
stack read, resulting in reconstructed stacks that mix frames from different
execution states or that never actually existed.

For these cases, the @ref{4a94,,--blocking} option stops the target process during
each sample:

@example
python -m profiling.sampling run --blocking script.py
python -m profiling.sampling attach --blocking 12345
@end example

When blocking mode is enabled, the profiler suspends the target process,
reads its stack, then resumes it. This guarantees that each captured stack
represents a real, consistent snapshot of what the process was doing at that
instant. The trade-off is that the target process runs slower because it is
repeatedly paused.

@cartouche
@quotation Προειδοποίηση 
Do not use very high sample rates (low @code{--interval} values) with blocking
mode. Suspending and resuming a process takes time, and if the sampling
interval is too short, the target will spend more time stopped than running.
For blocking mode, intervals of 1000 microseconds (1 millisecond) or higher
are recommended. The default 100 microsecond interval may cause noticeable
slowdown in the target application.
@end quotation
@end cartouche

Use blocking mode only when you observe inconsistent stacks in your profiles,
particularly with generator-heavy or coroutine-heavy code. For most
applications, the default non-blocking mode provides accurate results with
zero impact on the target process.

@node Special frames,Opcode-aware profiling,Blocking mode,Sampling configuration
@anchor{library/profiling sampling special-frames}@anchor{4a95}
@subsubsection Special frames


The profiler can inject artificial frames into the captured stacks to provide
additional context about what the interpreter is doing at the moment each
sample is taken. These synthetic frames help distinguish different types of
execution that would otherwise be invisible.

The @ref{4a96,,--native} option adds @code{<native>} frames to indicate when Python has
called into C code (extension modules, built-in functions, or the interpreter
itself):

@example
python -m profiling.sampling run --native script.py
@end example

These frames help distinguish time spent in Python code versus time spent in
native libraries. Without this option, native code execution appears as time
in the Python function that made the call. This is useful when optimizing
code that makes heavy use of C extensions like NumPy or database drivers.

By default, the profiler includes @code{<GC>} frames when garbage collection is
active. The @ref{4a97,,--no-gc} option suppresses these frames:

@example
python -m profiling.sampling run --no-gc script.py
@end example

GC frames help identify programs where garbage collection consumes significant
time, which may indicate memory allocation patterns worth optimizing. If you
see substantial time in @code{<GC>} frames, consider investigating object
allocation rates or using object pooling.

@node Opcode-aware profiling,Real-time statistics,Special frames,Sampling configuration
@anchor{library/profiling sampling opcode-aware-profiling}@anchor{4a98}
@subsubsection Opcode-aware profiling


The @ref{4a99,,--opcodes} option enables instruction-level profiling that captures
which Python bytecode instructions are executing at each sample:

@example
python -m profiling.sampling run --opcodes --flamegraph script.py
@end example

This feature provides visibility into Python’s bytecode execution, including
adaptive specialization optimizations. When a generic instruction like
@code{LOAD_ATTR} is specialized at runtime into a more efficient variant like
@code{LOAD_ATTR_INSTANCE_VALUE}, the profiler shows both the specialized name
and the base instruction.

Opcode information appears in several output formats:


@itemize -

@item 
`Flame graphs': Hovering over a frame displays a tooltip with a bytecode
instruction breakdown, showing which opcodes consumed time in that function

@item 
`Heatmap': Expandable bytecode panels per source line show instruction
breakdown with specialization percentages

@item 
`Live mode': An opcode panel shows instruction-level statistics for the
selected function, accessible via keyboard navigation

@item 
`Gecko format': Opcode transitions are emitted as interval markers in the
Firefox Profiler timeline
@end itemize

This level of detail is particularly useful for:


@itemize -

@item 
Understanding the performance impact of Python’s adaptive specialization

@item 
Identifying hot bytecode instructions that might benefit from optimization

@item 
Analyzing the effectiveness of different code patterns at the instruction level

@item 
Debugging performance issues that occur at the bytecode level
@end itemize

The @ref{4a99,,--opcodes} option is compatible with @ref{4a9a,,--live}, @ref{4a9b,,--flamegraph},
@ref{4a9c,,--heatmap}, and @ref{4a9d,,--gecko} formats. It requires additional memory to store
opcode information and may slightly reduce sampling performance, but provides
unprecedented visibility into Python’s execution model.

@node Real-time statistics,Subprocess profiling,Opcode-aware profiling,Sampling configuration
@anchor{library/profiling sampling real-time-statistics}@anchor{4a9e}
@subsubsection Real-time statistics


The @ref{4a9f,,--realtime-stats} option displays sampling rate statistics during
profiling:

@example
python -m profiling.sampling run --realtime-stats script.py
@end example

This shows the actual achieved sampling rate, which may be lower than requested
if the profiler cannot keep up. The statistics help verify that profiling is
working correctly and that sufficient samples are being collected. See
@ref{4aa0,,Sampling efficiency} for details on interpreting these metrics.

@node Subprocess profiling,Sampling efficiency,Real-time statistics,Sampling configuration
@anchor{library/profiling sampling subprocess-profiling}@anchor{4aa1}
@subsubsection Subprocess profiling


The @ref{4aa2,,--subprocesses} option enables automatic profiling of subprocesses
spawned by the target:

@example
python -m profiling.sampling run --subprocesses script.py
python -m profiling.sampling attach --subprocesses 12345
@end example

When enabled, the profiler monitors the target process for child process
creation. When a new Python child process is detected, a separate profiler
instance is automatically spawned to profile it. This is useful for
applications that use @ref{98,,multiprocessing}, @ref{df,,subprocess},
@ref{24,,concurrent.futures} with @ref{206,,ProcessPoolExecutor},
or other process spawning mechanisms.


@float LiteralBlock

@caption{worker_pool.py}

@example
from concurrent.futures import ProcessPoolExecutor
import math

def compute_factorial(n):
    total = 0
    for i in range(50):
        total += math.factorial(n)
    return total

if __name__ == "__main__":
    numbers = [5000 + i * 100 for i in range(50)]
    with ProcessPoolExecutor(max_workers=4) as executor:
        results = list(executor.map(compute_factorial, numbers))
    print(f"Computed @{len(results)@} factorials")
@end example

@end float


@example
python -m profiling.sampling run --subprocesses --flamegraph worker_pool.py
@end example

This produces separate flame graphs for the main process and each worker
process: @code{flamegraph_<main_pid>.html}, @code{flamegraph_<worker1_pid>.html},
and so on.

Each subprocess receives its own output file. The filename is derived from
the specified output path (or the default) with the subprocess’s process ID
appended:


@itemize -

@item 
If you specify @code{-o profile.html}, subprocesses produce @code{profile_12345.html},
@code{profile_12346.html}, and so on

@item 
With default output, subprocesses produce files like @code{flamegraph_12345.html}
or directories like @code{heatmap_12345}

@item 
For pstats format (which defaults to stdout), subprocesses produce files like
@code{profile_12345.pstats}
@end itemize

The subprocess profilers inherit most sampling options from the parent (sampling
rate, duration, thread selection, native frames, GC frames, async-aware mode,
and output format). All Python descendant processes are profiled recursively,
including grandchildren and further descendants.

Subprocess detection works by periodically scanning for new descendants of
the target process and checking whether each new process is a Python process
by probing the process memory for Python runtime structures. Non-Python
subprocesses (such as shell commands or external tools) are ignored.

There is a limit of 100 concurrent subprocess profilers to prevent resource
exhaustion in programs that spawn many processes. If this limit is reached,
additional subprocesses are not profiled and a warning is printed.

The @ref{4aa2,,--subprocesses} option is incompatible with @ref{4a9a,,--live} mode
because live mode uses an interactive terminal interface that cannot
accommodate multiple concurrent profiler displays.

@node Sampling efficiency,,Subprocess profiling,Sampling configuration
@anchor{library/profiling sampling id2}@anchor{4aa3}@anchor{library/profiling sampling sampling-efficiency}@anchor{4aa0}
@subsubsection Sampling efficiency


Sampling efficiency metrics help assess the quality of the collected data.
These metrics appear in the profiler’s terminal output and in the flame graph
sidebar.

`Sampling efficiency' is the percentage of sample attempts that succeeded.
Each sample attempt reads the target process’s call stack from memory. An
attempt can fail if the process is in an inconsistent state at the moment of
reading, such as during a context switch or while the interpreter is updating
its internal structures. A low efficiency may indicate that the profiler could
not keep up with the requested sampling rate, often due to system load or an
overly aggressive interval setting.

`Missed samples' is the percentage of expected samples that were not
collected. Based on the configured interval and duration, the profiler expects
to collect a certain number of samples. Some samples may be missed if the
profiler falls behind schedule, for example when the system is under heavy
load. A small percentage of missed samples is normal and does not significantly
affect the statistical accuracy of the profile.

Both metrics are informational. Even with some failed attempts or missed
samples, the profile remains statistically valid as long as enough samples
were collected. The profiler reports the actual number of samples captured,
which you can use to judge whether the data is sufficient for your analysis.

@node Profiling modes,Output formats,Sampling configuration,profiling sampling — Statistical profiler
@anchor{library/profiling sampling profiling-modes}@anchor{4aa4}
@subsubsection Profiling modes


The sampling profiler supports four modes that control which samples are
recorded. The mode determines what the profile measures: total elapsed time,
CPU execution time, time spent holding the global interpreter lock, or
exception handling.

@menu
* Wall-clock mode:: 
* CPU mode:: 
* Comparing wall-clock and CPU profiles:: 
* GIL mode:: 
* Exception mode:: 

@end menu

@node Wall-clock mode,CPU mode,,Profiling modes
@anchor{library/profiling sampling wall-clock-mode}@anchor{4aa5}
@subsubsection Wall-clock mode


Wall-clock mode (@ref{4aa6,,--mode}@code{=wall}) captures all samples regardless of what the
thread is doing. This is the default mode and provides a complete picture of
where time passes during program execution:

@example
python -m profiling.sampling run --mode=wall script.py
@end example

In wall-clock mode, samples are recorded whether the thread is actively
executing Python code, waiting for I/O, blocked on a lock, or sleeping.
This makes wall-clock profiling ideal for understanding the overall time
distribution in your program, including time spent waiting.

If your program spends significant time in I/O operations, network calls, or
sleep, wall-clock mode will show these waits as time attributed to the calling
function. This is often exactly what you want when optimizing end-to-end
latency.

@node CPU mode,Comparing wall-clock and CPU profiles,Wall-clock mode,Profiling modes
@anchor{library/profiling sampling cpu-mode}@anchor{4aa7}
@subsubsection CPU mode


CPU mode (@ref{4aa6,,--mode}@code{=cpu}) records samples only when the thread is actually
executing on a CPU core:

@example
python -m profiling.sampling run --mode=cpu script.py
@end example

Samples taken while the thread is sleeping, blocked on I/O, or waiting for
a lock are discarded. The resulting profile shows where CPU cycles are consumed,
filtering out idle time.

CPU mode is useful when you want to focus on computational hotspots without
being distracted by I/O waits. If your program alternates between computation
and network calls, CPU mode reveals which computational sections are most
expensive.

@node Comparing wall-clock and CPU profiles,GIL mode,CPU mode,Profiling modes
@anchor{library/profiling sampling comparing-wall-clock-and-cpu-profiles}@anchor{4aa8}
@subsubsection Comparing wall-clock and CPU profiles


Running both wall-clock and CPU mode profiles can reveal whether a function’s
time is spent computing or waiting.

If a function appears prominently in both profiles, it is a true computational
hotspot—actively using the CPU. Optimization should focus on algorithmic
improvements or more efficient code.

If a function is high in wall-clock mode but low or absent in CPU mode, it is
I/O-bound or waiting. The function spends most of its time waiting for network,
disk, locks, or sleep. CPU optimization won’t help here; consider async I/O,
connection pooling, or reducing wait time instead.

@example
import time

def do_sleep():
    time.sleep(2)

def do_compute():
    sum(i**2 for i in range(1000000))

if __name__ == "__main__":
    do_sleep()
    do_compute()
@end example

@example
python -m profiling.sampling run --mode=wall script.py  # do_sleep ~98%, do_compute ~1%
python -m profiling.sampling run --mode=cpu script.py   # do_sleep absent, do_compute dominates
@end example

@node GIL mode,Exception mode,Comparing wall-clock and CPU profiles,Profiling modes
@anchor{library/profiling sampling gil-mode}@anchor{4aa9}
@subsubsection GIL mode


GIL mode (@ref{4aa6,,--mode}@code{=gil}) records samples only when the thread holds Python’s
global interpreter lock:

@example
python -m profiling.sampling run --mode=gil script.py
@end example

The GIL is held only while executing Python bytecode. When Python calls into
C extensions, performs I/O operations, or executes native code, the GIL is
typically released. This means GIL mode effectively measures time spent
running Python code specifically, filtering out time in native libraries.

In multi-threaded programs, GIL mode reveals which code is preventing other
threads from running Python bytecode. Since only one thread can hold the GIL
at a time, functions that appear frequently in GIL mode profiles are
monopolizing the interpreter.

GIL mode helps answer questions like «which functions are monopolizing the
GIL?» and «why are my other threads starving?» It can also be useful in
single-threaded programs to distinguish Python execution time from time spent
in C extensions or I/O.

@example
import hashlib

def hash_work():
    # C extension - releases GIL during computation
    for _ in range(200):
        hashlib.sha256(b"data" * 250000).hexdigest()

def python_work():
    # Pure Python - holds GIL during computation
    for _ in range(3):
        sum(i**2 for i in range(1000000))

if __name__ == "__main__":
    hash_work()
    python_work()
@end example

@example
python -m profiling.sampling run --mode=cpu script.py  # hash_work ~42%, python_work ~38%
python -m profiling.sampling run --mode=gil script.py  # hash_work ~5%, python_work ~60%
@end example

@node Exception mode,,GIL mode,Profiling modes
@anchor{library/profiling sampling exception-mode}@anchor{4aaa}
@subsubsection Exception mode


Exception mode (@code{--mode=exception}) records samples only when a thread has
an active exception:

@example
python -m profiling.sampling run --mode=exception script.py
@end example

Samples are recorded in two situations: when an exception is being propagated
up the call stack (after @code{raise} but before being caught), or when code is
executing inside an @code{except} block where exception information is still
present in the thread state.

The following example illustrates which code regions are captured:

@example
def example():
    try:
        raise ValueError("error")    # Captured: exception being raised
    except ValueError:
        process_error()              # Captured: inside except block
    finally:
        cleanup()                    # NOT captured: exception already handled

def example_propagating():
    try:
        try:
            raise ValueError("error")
        finally:
            cleanup()                # Captured: exception propagating through
    except ValueError:
        pass

def example_no_exception():
    try:
        do_work()
    finally:
        cleanup()                    # NOT captured: no exception involved
@end example

Note that @code{finally} blocks are only captured when an exception is actively
propagating through them. Once an @code{except} block finishes executing, Python
clears the exception information before running any subsequent @code{finally}
block. Similarly, @code{finally} blocks that run during normal execution (when no
exception was raised) are not captured because no exception state is present.

This mode is useful for understanding where your program spends time handling
errors. Exception handling can be a significant source of overhead in code
that uses exceptions for flow control (such as @code{StopIteration} in iterators)
or in applications that process many error conditions (such as network servers
handling connection failures).

Exception mode helps answer questions like «how much time is spent handling
exceptions?» and «which exception handlers are the most expensive?» It can
reveal hidden performance costs in code that catches and processes many
exceptions, even when those exceptions are handled gracefully. For example,
if a parsing library uses exceptions internally to signal format errors, this
mode will capture time spent in those handlers even if the calling code never
sees the exceptions.

@node Output formats,Record and replay workflow,Profiling modes,profiling sampling — Statistical profiler
@anchor{library/profiling sampling output-formats}@anchor{4aab}
@subsubsection Output formats


The profiler produces output in several formats, each suited to different
analysis workflows. The format is selected with a command-line flag, and
output goes to stdout, a file, or a directory depending on the format.

@menu
* pstats format:: 
* Collapsed stacks format:: 
* Flame graph format:: 
* Gecko format:: 
* Heatmap format:: 
* Binary format:: 

@end menu

@node pstats format,Collapsed stacks format,,Output formats
@anchor{library/profiling sampling pstats-format}@anchor{4aac}
@subsubsection pstats format


The pstats format (@ref{4aad,,--pstats}) produces a text table similar to what
deterministic profilers generate. This is the default output format:

@example
python -m profiling.sampling run script.py
python -m profiling.sampling run --pstats script.py
@end example


@float Figure

@image{python-figures/tachyon-pstats,418.0pt,,Tachyon pstats terminal output,png}

@caption{The pstats format displays profiling results in a color-coded table showing
function hotspots, sample counts, and timing estimates.}

@end float


Output appears on stdout by default:

@example
Profile Stats (Mode: wall):
     nsamples  sample%    tottime (ms)  cumul%   cumtime (ms)  filename:lineno(function)
       234/892    11.7%       234.00     44.6%       892.00    server.py:145(handle_request)
       156/156     7.8%       156.00      7.8%       156.00    <built-in>:0(socket.recv)
        98/421     4.9%        98.00     21.1%       421.00    parser.py:67(parse_message)
@end example

The columns show sampling counts and estimated times:


@itemize -

@item 
`nsamples': Displayed as @code{direct/cumulative} (for example, @code{10/50}).
Direct samples are when the function was at the top of the stack, actively
executing. Cumulative samples are when the function appeared anywhere on the
stack, including when it was waiting for functions it called. If a function
shows @code{10/50}, it was directly executing in 10 samples and was on the call
stack in 50 samples total.

@item 
`sample%' and `cumul%': Percentages of total samples for direct and
cumulative counts respectively.

@item 
`tottime' and `cumtime': Estimated wall-clock time based on sample counts
and the profiling duration. Time units are selected automatically based on
the magnitude: seconds for large values, milliseconds for moderate values,
or microseconds for small values.
@end itemize

The output includes a legend explaining each column and a summary of
interesting functions that highlights:


@itemize -

@item 
`Hot spots': Functions with high direct/cumulative sample ratio (ratio
close to 1.0). These functions spend most of their time executing their own
code rather than waiting for callees. High ratios indicate where CPU time
is actually consumed.

@item 
`Indirect calls': Functions with large differences between cumulative and
direct samples. These are orchestration functions that delegate work to
other functions. They appear frequently on the stack but rarely at the top.

@item 
`Call magnification': Functions where cumulative samples far exceed direct
samples (high cumulative/direct multiplier). These are frequently-nested
functions that appear deep in many call chains.
@end itemize

Use @ref{4aae,,--no-summary} to suppress both the legend and summary sections.

To save pstats output to a binary file instead of stdout:

@example
python -m profiling.sampling run -o profile.pstats script.py
@end example

The pstats format supports several options for controlling the display.
The @ref{4aaf,,--sort} option determines the column used for ordering results:

@example
python -m profiling.sampling run --sort=tottime script.py
python -m profiling.sampling run --sort=cumtime script.py
python -m profiling.sampling run --sort=nsamples script.py
@end example

The @ref{4ab0,,--limit} option restricts output to the top N entries:

@example
python -m profiling.sampling run --limit=30 script.py
@end example

The @ref{4aae,,--no-summary} option suppresses the header summary that precedes the
statistics table.

@node Collapsed stacks format,Flame graph format,pstats format,Output formats
@anchor{library/profiling sampling collapsed-stacks-format}@anchor{4ab1}
@subsubsection Collapsed stacks format


Collapsed stacks format (@ref{4ab2,,--collapsed}) produces one line per unique call
stack, with a count of how many times that stack was sampled:

@example
python -m profiling.sampling run --collapsed script.py
@end example

The output looks like:

@example
main;process_data;parse_json;decode_utf8 42
main;process_data;parse_json 156
main;handle_request;send_response 89
@end example

Each line contains semicolon-separated function names representing the call
stack from bottom to top, followed by a space and the sample count. This
format is designed for compatibility with external flame graph tools,
particularly Brendan Gregg’s @code{flamegraph.pl} script.

To generate a flame graph from collapsed stacks:

@example
python -m profiling.sampling run --collapsed script.py > stacks.txt
flamegraph.pl stacks.txt > profile.svg
@end example

The resulting SVG can be viewed in any web browser and provides an interactive
visualization where you can click to zoom into specific call paths.

@node Flame graph format,Gecko format,Collapsed stacks format,Output formats
@anchor{library/profiling sampling flame-graph-format}@anchor{4ab3}
@subsubsection Flame graph format


Flame graph format (@ref{4a9b,,--flamegraph}) produces a self-contained HTML file with
an interactive flame graph visualization:

@example
python -m profiling.sampling run --flamegraph script.py
python -m profiling.sampling run --flamegraph -o profile.html script.py
@end example


@float Figure

@image{python-figures/tachyon-flamegraph,418.0pt,,Tachyon interactive flame graph,png}

@caption{The flame graph visualization shows call stacks as nested rectangles, with
width proportional to time spent. The sidebar displays runtime statistics,
GIL metrics, and hotspot functions.}

@end float



If no output file is specified, the profiler generates a filename based on
the process ID (for example, @code{flamegraph.12345.html}).

The generated HTML file requires no external dependencies and can be opened
directly in a web browser. The visualization displays call stacks as nested
rectangles, with width proportional to time spent. Hovering over a rectangle
shows details about that function including source code context, and clicking
zooms into that portion of the call tree.

The flame graph interface includes:


@itemize -

@item 
A sidebar showing profile summary, thread statistics, sampling efficiency
metrics (see @ref{4aa0,,Sampling efficiency}), and top hotspot functions

@item 
Search functionality supporting both function name matching and
@code{file.py:42} line patterns

@item 
Per-thread filtering via dropdown

@item 
Dark/light theme toggle (preference saved across sessions)

@item 
SVG export for saving the current view
@end itemize

The thread statistics section shows runtime behavior metrics:


@itemize -

@item 
`GIL Held': percentage of samples where a thread held the global interpreter
lock (actively running Python code)

@item 
`GIL Released': percentage of samples where no thread held the GIL

@item 
`Waiting GIL': percentage of samples where a thread was waiting to acquire
the GIL

@item 
`GC': percentage of samples during garbage collection
@end itemize

These statistics help identify GIL contention and understand how time is
distributed between Python execution, native code, and waiting.

Flame graphs are particularly effective for identifying deep call stacks and
understanding the hierarchical structure of time consumption. Wide rectangles
at the top indicate functions that consume significant time either directly
or through their callees.

@menu
* Differential flame graphs:: 

@end menu

@node Differential flame graphs,,,Flame graph format
@anchor{library/profiling sampling differential-flame-graphs}@anchor{4ab4}
@subsubsection Differential flame graphs


Differential flame graphs compare two profiling runs to highlight where
performance changed. This helps identify regressions introduced by code changes
and validate that optimizations achieved their intended effect:

@example
# Capture baseline profile
python -m profiling.sampling run --binary -o baseline.bin script.py

# After modifying code, generate differential flamegraph
python -m profiling.sampling run --diff-flamegraph baseline.bin -o diff.html script.py
@end example

The visualization draws the current profile with frame widths showing current
time consumption, then applies color to indicate how each function changed
relative to the baseline.

`Color coding':


@itemize -

@item 
`Red': Functions consuming more time (regressions). Lighter shades indicate
modest increases, while darker shades show severe regressions.

@item 
`Blue': Functions consuming less time (improvements). Lighter shades for
modest reductions, darker shades for significant speedups.

@item 
`Gray': Minimal or no change.

@item 
`Purple': New functions not present in the baseline.
@end itemize

Frame colors indicate changes in `direct time' (time when the function was at
the top of the stack, actively executing), not cumulative time including callees.
Hovering over a frame shows comparison details including baseline time, current
time, and the percentage change.

Some call paths may disappear entirely between profiles. These are called
`elided stacks' and occur when optimizations eliminate code paths or certain
branches stop executing. If elided stacks are present, an elided toggle appears
allowing you to switch between the main differential view and an elided-only
view that shows just the removed paths (colored purple).

@node Gecko format,Heatmap format,Flame graph format,Output formats
@anchor{library/profiling sampling gecko-format}@anchor{4ab5}
@subsubsection Gecko format


Gecko format (@ref{4a9d,,--gecko}) produces JSON output compatible with the Firefox
Profiler:

@example
python -m profiling.sampling run --gecko script.py
python -m profiling.sampling run --gecko -o profile.json script.py
@end example

The Firefox Profiler@footnote{https://profiler.firefox.com} is a sophisticated
web-based tool originally built for profiling Firefox itself. It provides
features beyond basic flame graphs, including a timeline view, call tree
exploration, and marker visualization. See the
Firefox Profiler documentation@footnote{https://profiler.firefox.com/docs/#/} for
detailed usage instructions.

To use the output, open the Firefox Profiler in your browser and load the
JSON file. The profiler runs entirely client-side, so your profiling data
never leaves your machine.

Gecko format automatically collects additional metadata about GIL state and
CPU activity, enabling analysis features specific to Python’s threading model.
The profiler emits interval markers that appear as colored bands in the
Firefox Profiler timeline:


@itemize -

@item 
`GIL markers': show when threads hold or release the global interpreter lock

@item 
`CPU markers': show when threads are executing on CPU versus idle

@item 
`Code type markers': distinguish Python code from native (C extension) code

@item 
`GC markers': indicate garbage collection activity
@end itemize

For this reason, the @ref{4aa6,,--mode} option is not available with Gecko format;
all relevant data is captured automatically.


@float Figure

@image{python-figures/tachyon-gecko-calltree,418.0pt,,Firefox Profiler Call Tree view,png}

@caption{The Call Tree view shows the complete call hierarchy with sample counts
and percentages. The sidebar displays detailed statistics for the
selected function including running time and sample distribution.}

@end float



@float Figure

@image{python-figures/tachyon-gecko-flamegraph,418.0pt,,Firefox Profiler Flame Graph view,png}

@caption{The Flame Graph visualization shows call stacks as nested rectangles.
Functions names are visible in the call hierarchy.}

@end float



@float Figure

@image{python-figures/tachyon-gecko-opcodes,418.0pt,,Firefox Profiler Marker Chart with opcodes,png}

@caption{The Marker Chart displays interval markers including CPU state, GIL
status, and opcodes. With @code{--opcodes} enabled, bytecode instructions
like @code{BINARY_OP_ADD_FLOAT}, @code{CALL_PY_EXACT_ARGS}, and
@code{CALL_LIST_APPEND} appear as markers showing execution over time.}

@end float


@node Heatmap format,Binary format,Gecko format,Output formats
@anchor{library/profiling sampling heatmap-format}@anchor{4ab6}
@subsubsection Heatmap format


Heatmap format (@ref{4a9c,,--heatmap}) generates an interactive HTML visualization
showing sample counts at the source line level:

@example
python -m profiling.sampling run --heatmap script.py
python -m profiling.sampling run --heatmap -o my_heatmap script.py
@end example


@float Figure

@image{python-figures/tachyon-heatmap,418.0pt,,Tachyon heatmap visualization,png}

@caption{The heatmap overlays sample counts directly on your source code. Lines are
color-coded from cool (few samples) to hot (many samples). Navigation
buttons (▲▼) let you jump between callers and callees.}

@end float


Unlike other formats that produce a single file, heatmap output creates a
directory containing HTML files for each profiled source file. If no output
path is specified, the directory is named @code{heatmap_PID}.

The heatmap visualization displays your source code with a color gradient
indicating how many samples were collected at each line. Hot lines (many
samples) appear in warm colors, while cold lines (few or no samples) appear
in cool colors. This view helps pinpoint exactly which lines of code are
responsible for time consumption.

The heatmap interface provides several interactive features:


@itemize -

@item 
`Coloring modes': toggle between «Self Time» (direct execution) and
«Total Time» (cumulative, including time in called functions)

@item 
`Cold code filtering': show all lines or only lines with samples

@item 
`Call graph navigation': each line shows navigation buttons (▲ for callers,
▼ for callees) that let you trace execution paths through your code. When
multiple functions called or were called from a line, a menu appears showing
all options with their sample counts.

@item 
`Scroll minimap': a vertical overview showing the heat distribution across
the entire file

@item 
`Hierarchical index': files organized by type (stdlib, site-packages,
project) with aggregate sample counts per folder

@item 
`Dark/light theme': toggle with preference saved across sessions

@item 
`Line linking': click line numbers to create shareable URLs
@end itemize

When opcode-level profiling is enabled with @ref{4a99,,--opcodes}, each hot line
can be expanded to show which bytecode instructions consumed time:


@float Figure

@image{python-figures/tachyon-heatmap-with-opcodes,418.0pt,,Heatmap with expanded bytecode panel,png}

@caption{Expanding a hot line reveals the bytecode instructions executed, including
specialized variants. The panel shows sample counts per instruction and the
overall specialization percentage for the line.}

@end float



Heatmaps are especially useful when you know which file contains a performance
issue but need to identify the specific lines. Many developers prefer this
format because it maps directly to their source code, making it easy to read
and navigate. For smaller scripts and focused analysis, heatmaps provide an
intuitive view that shows exactly where time is spent without requiring
interpretation of hierarchical visualizations.

@node Binary format,,Heatmap format,Output formats
@anchor{library/profiling sampling binary-format}@anchor{4ab7}
@subsubsection Binary format


Binary format (@ref{4ab8,,--binary}) produces a compact binary file for efficient
storage of profiling data:

@example
python -m profiling.sampling run --binary -o profile.bin script.py
python -m profiling.sampling attach --binary -o profile.bin 12345
@end example

The @ref{4ab9,,--compression} option controls data compression:


@itemize -

@item 
@code{auto} (default): Use zstd compression if available, otherwise no
compression

@item 
@code{zstd}: Force zstd compression (requires @ref{23,,compression.zstd} support)

@item 
@code{none}: Disable compression
@end itemize

@example
python -m profiling.sampling run --binary --compression=zstd -o profile.bin script.py
@end example

To analyze binary profiles, use the @ref{4a87,,The replay command} to convert them to
other formats like flame graphs or pstats output.

@node Record and replay workflow,Live mode,Output formats,profiling sampling — Statistical profiler
@anchor{library/profiling sampling record-and-replay-workflow}@anchor{4aba}
@subsubsection Record and replay workflow


The binary format combined with the replay command enables a record-and-replay
workflow that separates data capture from analysis. Rather than generating
visualizations during profiling, you capture raw data to a compact binary file
and convert it to different formats later.

This approach has three main benefits:


@itemize -

@item 
Sampling runs faster because the work of building data structures for
visualization is deferred until replay.

@item 
A single binary capture can be converted to multiple output formats
without re-profiling: pstats for a quick overview, flame graph for visual
exploration, heatmap for line-level detail.

@item 
Binary files are compact and easy to share with colleagues who can convert
them to their preferred format.
@end itemize

A typical workflow:

@example
# Capture profile in production or during tests
python -m profiling.sampling attach --binary -o profile.bin 12345

# Later, analyze with different formats
python -m profiling.sampling replay profile.bin
python -m profiling.sampling replay --flamegraph -o profile.html profile.bin
python -m profiling.sampling replay --heatmap -o heatmap profile.bin
@end example

@node Live mode,Async-aware profiling,Record and replay workflow,profiling sampling — Statistical profiler
@anchor{library/profiling sampling live-mode}@anchor{4abb}
@subsubsection Live mode


Live mode (@ref{4a9a,,--live}) provides a terminal-based real-time view of profiling
data, similar to the @code{top} command for system processes:

@example
python -m profiling.sampling run --live script.py
python -m profiling.sampling attach --live 12345
@end example


@float Figure

@image{python-figures/tachyon-live-mode-2,418.0pt,,Tachyon live mode showing all threads,gif}

@end float


Live mode displays real-time profiling statistics, showing combined
data from multiple threads in a multi-threaded application.

The display updates continuously as new samples arrive, showing the current
hottest functions. This mode requires the @ref{2e,,curses} module, which is
available on Unix-like systems but not on Windows. The terminal must be at
least 60 columns wide and 12 lines tall; larger terminals display more columns.

The header displays the top 3 hottest functions, sampling efficiency metrics,
and thread status statistics (GIL held percentage, CPU usage, GC time). The
main table shows function statistics with the currently sorted column indicated
by an arrow (▼).

When @ref{4a99,,--opcodes} is enabled, an additional opcode panel appears below the
main table, showing instruction-level statistics for the currently selected
function. This panel displays which bytecode instructions are executing most
frequently, including specialized variants and their base opcodes.


@float Figure

@image{python-figures/tachyon-live-mode-1,418.0pt,,Tachyon live mode with opcode panel,gif}

@end float


Live mode with @code{--opcodes} enabled shows an opcode panel with a bytecode
instruction breakdown for the selected function.

@menu
* Keyboard commands:: 

@end menu

@node Keyboard commands,,,Live mode
@anchor{library/profiling sampling keyboard-commands}@anchor{4abc}
@subsubsection Keyboard commands


Within live mode, keyboard commands control the display:


@table @asis

@item @code{q}

Quit the profiler and return to the shell.

@item @code{s} / @code{S}

Cycle through sort orders forward/backward (sample count, percentage,
total time, cumulative percentage, cumulative time).

@item @code{p}

Pause or resume display updates. Sampling continues in the background
while the display is paused, so you can freeze the view to examine results
without stopping data collection.

@item @code{r}

Reset all statistics and start fresh. This is disabled after profiling
finishes to prevent accidental data loss.

@item @code{/}

Enter filter mode to search for functions by name. The filter uses
case-insensitive substring matching against the filename and function name.
Type a pattern and press Enter to apply, or Escape to cancel. Glob patterns
and regular expressions are not supported.

@item @code{c}

Clear the current filter and show all functions again.

@item @code{t}

Toggle between viewing all threads combined or per-thread statistics.
In per-thread mode, a thread counter (for example, @code{1/4}) appears showing
your position among the available threads.

@item @code{←} @code{→} or @code{↑} @code{↓}

In per-thread view, navigate between threads. Navigation wraps around
from the last thread to the first and vice versa.

@item @code{+} / @code{-}

Increase or decrease the display refresh rate. The range is 0.05 seconds
(20 Hz, very responsive) to 1.0 second (1 Hz, lower overhead). Faster refresh
rates use more CPU. The default is 0.1 seconds (10 Hz).

@item @code{x}

Toggle trend indicators that show whether functions are becoming hotter
or cooler over time. When enabled, increasing metrics appear in green and
decreasing metrics appear in red, comparing each update to the previous one.

@item @code{h} or @code{?}

Show the help screen with all available commands.

@item @code{j} / @code{k} (or @code{Up} / @code{Down})

Navigate through opcode entries in the opcode panel (when @code{--opcodes} is
enabled). These keys scroll through the instruction-level statistics for the
currently selected function.
@end table

When profiling finishes (duration expires or target process exits), the display
shows a «PROFILING COMPLETE» banner and freezes the final results. You can
still navigate, sort, and filter the results before pressing @code{q} to exit.

Live mode is incompatible with output format options (@ref{4ab2,,--collapsed},
@ref{4a9b,,--flamegraph}, and so on) because it uses an interactive terminal
interface rather than producing file output.

@node Async-aware profiling,Command-line interface<9>,Live mode,profiling sampling — Statistical profiler
@anchor{library/profiling sampling async-aware-profiling}@anchor{4abd}
@subsubsection Async-aware profiling


For programs using @ref{b,,asyncio}, the profiler offers async-aware mode
(@ref{4abe,,--async-aware}) that reconstructs call stacks based on the task structure
rather than the raw Python frames:

@example
python -m profiling.sampling run --async-aware async_script.py
@end example

Standard profiling of async code can be confusing because the physical call
stack often shows event loop internals rather than the logical flow of your
coroutines. Async-aware mode addresses this by tracking which task is running
and presenting stacks that reflect the @code{await} chain.

@example
import asyncio

async def fetch(url):
    await asyncio.sleep(0.1)
    return url

async def main():
    for _ in range(50):
        await asyncio.gather(fetch("a"), fetch("b"), fetch("c"))

if __name__ == "__main__":
    asyncio.run(main())
@end example

@example
python -m profiling.sampling run --async-aware --flamegraph -o out.html script.py
@end example

@cartouche
@quotation Σημείωση 
Async-aware profiling requires the target process to have the @ref{b,,asyncio}
module loaded. If you profile a script before it imports asyncio, async-aware
mode will not be able to capture task information.
@end quotation
@end cartouche

@menu
* Async modes:: 
* Task markers and stack reconstruction:: 
* Option restrictions:: 

@end menu

@node Async modes,Task markers and stack reconstruction,,Async-aware profiling
@anchor{library/profiling sampling async-modes}@anchor{4abf}
@subsubsection Async modes


The @ref{4ac0,,--async-mode} option controls which tasks appear in the profile:

@example
python -m profiling.sampling run --async-aware --async-mode=running async_script.py
python -m profiling.sampling run --async-aware --async-mode=all async_script.py
@end example

With @ref{4ac0,,--async-mode}@code{=running} (the default), only the task currently executing
on the CPU is profiled. This shows where your program is actively spending time
and is the typical choice for performance analysis.

With @ref{4ac0,,--async-mode}@code{=all}, tasks that are suspended (awaiting I/O, locks, or
other tasks) are also included. This mode is useful for understanding what your
program is waiting on, but produces larger profiles since every suspended task
appears in each sample.

@node Task markers and stack reconstruction,Option restrictions,Async modes,Async-aware profiling
@anchor{library/profiling sampling task-markers-and-stack-reconstruction}@anchor{4ac1}
@subsubsection Task markers and stack reconstruction


In async-aware profiles, you will see @code{<task>} frames that mark boundaries
between asyncio tasks. These are synthetic frames inserted by the profiler to
show the task structure. The task name appears as the function name in these
frames.

When a task awaits another task, the profiler reconstructs the logical call
chain by following the @code{await} relationships. Only «leaf» tasks (tasks that
no other task is currently awaiting) generate their own stack entries. Tasks
being awaited by other tasks appear as part of their awaiter’s stack instead.

If a task has multiple awaiters (a diamond pattern in the task graph), the
profiler deterministically selects one parent and annotates the task marker
with the number of parents, for example @code{MyTask (2 parents)}. This indicates
that alternate execution paths exist but are not shown in this particular stack.

@node Option restrictions,,Task markers and stack reconstruction,Async-aware profiling
@anchor{library/profiling sampling option-restrictions}@anchor{4ac2}
@subsubsection Option restrictions


Async-aware mode uses a different stack reconstruction mechanism and is
incompatible with: @ref{4a96,,--native}, @ref{4a97,,--no-gc}, @ref{4a91,,--all-threads}, and
@ref{4aa6,,--mode}@code{=cpu} or @code{--mode}@code{=gil}.

@node Command-line interface<9>,,Async-aware profiling,profiling sampling — Statistical profiler
@anchor{library/profiling sampling command-line-interface}@anchor{4ac3}
@subsubsection Command-line interface


The complete command-line interface for reference.

@menu
* Global options:: 
* Dump options:: 
* Sampling options:: 
* Mode options:: 
* Output options:: 
* pstats display options:: 
* Run command options:: 

@end menu

@node Global options,Dump options,,Command-line interface<9>
@anchor{library/profiling sampling global-options}@anchor{4ac4}
@subsubsection Global options


@geindex profiling.sampling command line option; run
@anchor{library/profiling sampling cmdoption-profiling sampling-arg-run}@anchor{4ac5}
@deffn {Option} run

Run and profile a Python script or module.
@end deffn

@geindex profiling.sampling command line option; attach
@anchor{library/profiling sampling cmdoption-profiling sampling-arg-attach}@anchor{4ac6}
@deffn {Option} attach

Attach to and profile a running process by PID.
@end deffn

@geindex profiling.sampling command line option; dump
@anchor{library/profiling sampling cmdoption-profiling sampling-arg-dump}@anchor{4ac7}
@deffn {Option} dump

Print a single one-shot snapshot of a running process’s Python stack.
@end deffn

@geindex profiling.sampling command line option; replay
@anchor{library/profiling sampling cmdoption-profiling sampling-arg-replay}@anchor{4ac8}
@deffn {Option} replay

Convert a binary profile file to another output format.
@end deffn

@node Dump options,Sampling options,Global options,Command-line interface<9>
@anchor{library/profiling sampling dump-options}@anchor{4ac9}
@subsubsection Dump options


The following options apply to the @code{dump} subcommand:

@geindex profiling.sampling command line option; -a
@geindex profiling.sampling command line option; --all-threads
@anchor{library/profiling sampling cmdoption-profiling sampling-a}@anchor{4a91}@anchor{library/profiling sampling cmdoption-profiling sampling-all-threads}@anchor{4aca}
@deffn {Option} @w{-}a, @w{-}@w{-}all@w{-}threads

Dump all threads in the target process instead of just the main thread.
@end deffn

@geindex profiling.sampling command line option; --native
@anchor{library/profiling sampling cmdoption-profiling sampling-native}@anchor{4a96}
@deffn {Option} @w{-}@w{-}native

Include @code{<native>} frames for non-Python code.
@end deffn

@geindex profiling.sampling command line option; --no-gc
@anchor{library/profiling sampling cmdoption-profiling sampling-no-gc}@anchor{4a97}
@deffn {Option} @w{-}@w{-}no@w{-}gc

Exclude @code{<GC>} frames for active garbage collection.
@end deffn

@geindex profiling.sampling command line option; --opcodes
@anchor{library/profiling sampling cmdoption-profiling sampling-opcodes}@anchor{4a99}
@deffn {Option} @w{-}@w{-}opcodes

Show bytecode opcode names when available.
@end deffn

@geindex profiling.sampling command line option; --async-aware
@anchor{library/profiling sampling cmdoption-profiling sampling-async-aware}@anchor{4abe}
@deffn {Option} @w{-}@w{-}async@w{-}aware

Reconstruct the stack across @code{await} boundaries for asyncio
applications.
@end deffn

@geindex profiling.sampling command line option; --async-mode
@anchor{library/profiling sampling cmdoption-profiling sampling-async-mode}@anchor{4ac0}
@deffn {Option} @w{-}@w{-}async@w{-}mode <mode>

Async stack mode: @code{running} (only the running task) or @code{all}
(all tasks including waiting). Defaults to @code{all} for @code{dump}.
Requires @ref{4abe,,--async-aware}.
@end deffn

@geindex profiling.sampling command line option; --blocking
@anchor{library/profiling sampling cmdoption-profiling sampling-blocking}@anchor{4a94}
@deffn {Option} @w{-}@w{-}blocking

Pause all threads in the target process while reading the stack.
@end deffn

@node Sampling options,Mode options,Dump options,Command-line interface<9>
@anchor{library/profiling sampling sampling-options}@anchor{4acb}
@subsubsection Sampling options


@geindex profiling.sampling command line option; -r
@geindex profiling.sampling command line option; --sampling-rate
@anchor{library/profiling sampling cmdoption-profiling sampling-r}@anchor{4a8e}@anchor{library/profiling sampling cmdoption-profiling sampling-sampling-rate}@anchor{4acc}
@deffn {Option} @w{-}r <rate>, @w{-}@w{-}sampling@w{-}rate <rate>

Sampling rate (for example, @code{10000}, @code{10khz}, @code{10k}). Default: @code{1khz}.
@end deffn

@geindex profiling.sampling command line option; -d
@geindex profiling.sampling command line option; --duration
@anchor{library/profiling sampling cmdoption-profiling sampling-d}@anchor{4a8f}@anchor{library/profiling sampling cmdoption-profiling sampling-duration}@anchor{4acd}
@deffn {Option} @w{-}d <seconds>, @w{-}@w{-}duration <seconds>

Profiling duration in seconds. Default: run to completion.
@end deffn

@geindex profiling.sampling command line option; -a
@geindex profiling.sampling command line option; --all-threads
@anchor{library/profiling sampling cmdoption-profiling sampling-0}@anchor{4ace}@anchor{library/profiling sampling cmdoption-profiling sampling-1}@anchor{4acf}
@deffn {Option} @w{-}a, @w{-}@w{-}all@w{-}threads

Sample all threads, not just the main thread.
@end deffn

@geindex profiling.sampling command line option; --realtime-stats
@anchor{library/profiling sampling cmdoption-profiling sampling-realtime-stats}@anchor{4a9f}
@deffn {Option} @w{-}@w{-}realtime@w{-}stats

Display sampling statistics during profiling.
@end deffn

@geindex profiling.sampling command line option; --native
@anchor{library/profiling sampling cmdoption-profiling sampling-2}@anchor{4ad0}
@deffn {Option} @w{-}@w{-}native

Include @code{<native>} frames for non-Python code.
@end deffn

@geindex profiling.sampling command line option; --no-gc
@anchor{library/profiling sampling cmdoption-profiling sampling-3}@anchor{4ad1}
@deffn {Option} @w{-}@w{-}no@w{-}gc

Exclude @code{<GC>} frames for garbage collection.
@end deffn

@geindex profiling.sampling command line option; --async-aware
@anchor{library/profiling sampling cmdoption-profiling sampling-4}@anchor{4ad2}
@deffn {Option} @w{-}@w{-}async@w{-}aware

Enable async-aware profiling for asyncio programs.
@end deffn

@geindex profiling.sampling command line option; --opcodes
@anchor{library/profiling sampling cmdoption-profiling sampling-5}@anchor{4ad3}
@deffn {Option} @w{-}@w{-}opcodes

Gather bytecode opcode information for instruction-level profiling. Shows
which bytecode instructions are executing, including specializations.
Compatible with @code{--live}, @code{--flamegraph}, @code{--heatmap}, and @code{--gecko}
formats only.
@end deffn

@geindex profiling.sampling command line option; --subprocesses
@anchor{library/profiling sampling cmdoption-profiling sampling-subprocesses}@anchor{4aa2}
@deffn {Option} @w{-}@w{-}subprocesses

Also profile subprocesses. Each subprocess gets its own profiler
instance and output file. Incompatible with @code{--live}.
@end deffn

@geindex profiling.sampling command line option; --blocking
@anchor{library/profiling sampling cmdoption-profiling sampling-6}@anchor{4ad4}
@deffn {Option} @w{-}@w{-}blocking

Pause the target process during each sample. This ensures consistent
stack traces at the cost of slowing down the target. Use with longer
intervals (1000 µs or higher) to minimize impact. See @ref{4a92,,Blocking mode}
for details.
@end deffn

@node Mode options,Output options,Sampling options,Command-line interface<9>
@anchor{library/profiling sampling mode-options}@anchor{4ad5}
@subsubsection Mode options


@geindex profiling.sampling command line option; --mode
@anchor{library/profiling sampling cmdoption-profiling sampling-mode}@anchor{4aa6}
@deffn {Option} @w{-}@w{-}mode <mode>

Sampling mode: @code{wall} (default), @code{cpu}, @code{gil}, or @code{exception}.
The @code{cpu}, @code{gil}, and @code{exception} modes are incompatible with
@code{--async-aware}.
@end deffn

@geindex profiling.sampling command line option; --async-mode
@anchor{library/profiling sampling cmdoption-profiling sampling-7}@anchor{4ad6}
@deffn {Option} @w{-}@w{-}async@w{-}mode <mode>

Async profiling mode: @code{running} (default) or @code{all}.
Requires @code{--async-aware}.
@end deffn

@node Output options,pstats display options,Mode options,Command-line interface<9>
@anchor{library/profiling sampling output-options}@anchor{4ad7}
@subsubsection Output options


@geindex profiling.sampling command line option; --pstats
@anchor{library/profiling sampling cmdoption-profiling sampling-pstats}@anchor{4aad}
@deffn {Option} @w{-}@w{-}pstats

Generate pstats statistics. This is the default.
When written to stdout, the output is a text table; with @ref{4ad8,,-o},
it is a binary pstats file.
@end deffn

@geindex profiling.sampling command line option; --collapsed
@anchor{library/profiling sampling cmdoption-profiling sampling-collapsed}@anchor{4ab2}
@deffn {Option} @w{-}@w{-}collapsed

Generate collapsed stack format for external flame graph tools.
@end deffn

@geindex profiling.sampling command line option; --flamegraph
@anchor{library/profiling sampling cmdoption-profiling sampling-flamegraph}@anchor{4a9b}
@deffn {Option} @w{-}@w{-}flamegraph

Generate self-contained HTML flame graph.
@end deffn

@geindex profiling.sampling command line option; --diff-flamegraph
@anchor{library/profiling sampling cmdoption-profiling sampling-diff-flamegraph}@anchor{4ad9}
@deffn {Option} @w{-}@w{-}diff@w{-}flamegraph <baseline.bin>

Generate differential flamegraph comparing to a baseline binary profile.
@end deffn

@geindex profiling.sampling command line option; --gecko
@anchor{library/profiling sampling cmdoption-profiling sampling-gecko}@anchor{4a9d}
@deffn {Option} @w{-}@w{-}gecko

Generate Gecko JSON format for Firefox Profiler.
@end deffn

@geindex profiling.sampling command line option; --heatmap
@anchor{library/profiling sampling cmdoption-profiling sampling-heatmap}@anchor{4a9c}
@deffn {Option} @w{-}@w{-}heatmap

Generate HTML heatmap with line-level sample counts.
@end deffn

@geindex profiling.sampling command line option; --binary
@anchor{library/profiling sampling cmdoption-profiling sampling-binary}@anchor{4ab8}
@deffn {Option} @w{-}@w{-}binary

Generate high-performance binary format for later conversion with the
@code{replay} command.
@end deffn

@geindex profiling.sampling command line option; --compression
@anchor{library/profiling sampling cmdoption-profiling sampling-compression}@anchor{4ab9}
@deffn {Option} @w{-}@w{-}compression <type>

Compression for binary format: @code{auto} (use zstd if available, default),
@code{zstd}, or @code{none}.
@end deffn

@geindex profiling.sampling command line option; -o
@geindex profiling.sampling command line option; --output
@anchor{library/profiling sampling cmdoption-profiling sampling-o}@anchor{4ad8}@anchor{library/profiling sampling cmdoption-profiling sampling-output}@anchor{4ada}
@deffn {Option} @w{-}o <path>, @w{-}@w{-}output <path>

Output file or directory path. Default behavior varies by format:
@ref{4aad,,--pstats} prints a text table to stdout, while @code{-o} writes a
binary pstats file. Other formats generate a file named
@code{<format>_<PID>.<ext>} (for example, @code{flamegraph_12345.html}).
@ref{4a9c,,--heatmap} creates a directory named @code{heatmap_<PID>}.
@end deffn

@geindex profiling.sampling command line option; --browser
@anchor{library/profiling sampling cmdoption-profiling sampling-browser}@anchor{4adb}
@deffn {Option} @w{-}@w{-}browser

Automatically open HTML output (@ref{4a9b,,--flamegraph} and
@ref{4a9c,,--heatmap}) in your default web browser after generation.
When profiling with @ref{4aa2,,--subprocesses}, only the main process
opens the browser; subprocess outputs are never auto-opened.
@end deffn

@node pstats display options,Run command options,Output options,Command-line interface<9>
@anchor{library/profiling sampling pstats-display-options}@anchor{4adc}
@subsubsection pstats display options


These options apply only to pstats format output.

@geindex profiling.sampling command line option; --sort
@anchor{library/profiling sampling cmdoption-profiling sampling-sort}@anchor{4aaf}
@deffn {Option} @w{-}@w{-}sort <key>

Sort order: @code{nsamples}, @code{tottime}, @code{cumtime}, @code{sample-pct},
@code{cumul-pct}, @code{nsamples-cumul}, or @code{name}. Default: @code{nsamples}.
@end deffn

@geindex profiling.sampling command line option; -l
@geindex profiling.sampling command line option; --limit
@anchor{library/profiling sampling cmdoption-profiling sampling-l}@anchor{4ab0}@anchor{library/profiling sampling cmdoption-profiling sampling-limit}@anchor{4add}
@deffn {Option} @w{-}l <count>, @w{-}@w{-}limit <count>

Maximum number of entries to display. Default: 15.
@end deffn

@geindex profiling.sampling command line option; --no-summary
@anchor{library/profiling sampling cmdoption-profiling sampling-no-summary}@anchor{4aae}
@deffn {Option} @w{-}@w{-}no@w{-}summary

Omit the Legend and Summary of Interesting Functions sections from output.
@end deffn

@node Run command options,,pstats display options,Command-line interface<9>
@anchor{library/profiling sampling run-command-options}@anchor{4ade}
@subsubsection Run command options


@geindex profiling.sampling command line option; -m
@geindex profiling.sampling command line option; --module
@anchor{library/profiling sampling cmdoption-profiling sampling-m}@anchor{4adf}@anchor{library/profiling sampling cmdoption-profiling sampling-module}@anchor{4ae0}
@deffn {Option} @w{-}m, @w{-}@w{-}module

Treat the target as a module name rather than a script path.
@end deffn

@geindex profiling.sampling command line option; --live
@anchor{library/profiling sampling cmdoption-profiling sampling-live}@anchor{4a9a}
@deffn {Option} @w{-}@w{-}live

Start interactive terminal interface instead of batch profiling.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item @ref{b5,,profiling}

Overview of Python profiling tools and guidance on choosing a profiler.

@item @ref{b7,,profiling.tracing}

Deterministic tracing profiler for exact call counts and timing.

@item @ref{b8,,pstats}

Statistics analysis for profile data.

@item Firefox Profiler@footnote{https://profiler.firefox.com}

Web-based profiler that accepts Gecko format output. See the
documentation@footnote{https://profiler.firefox.com/docs/#/} for usage details.

@item FlameGraph@footnote{https://github.com/brendangregg/FlameGraph}

Tools for generating flame graphs from collapsed stack format.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node pstats — Statistics for profilers,timeit — Μέτρηση χρόνου εκτέλεσης μικρών αποσπασμάτων κώδικα,profiling — Python profilers,Debugging and profiling
@anchor{library/pstats doc}@anchor{4ae1}@anchor{library/pstats module-pstats}@anchor{b8}@anchor{library/pstats pstats-module}@anchor{4ae2}@anchor{library/pstats pstats-statistics-for-profilers}@anchor{4ae3}@anchor{library/pstats translation-repo}@anchor{4ae4}
@subsection @code{pstats} — Statistics for profilers


@geindex module; pstats

`Source code:' Lib/pstats.py@footnote{https://github.com/python/cpython/tree/main/Lib/pstats.py}


__________________________________________________________________


The @code{pstats} module provides tools for reading, manipulating, and
displaying profiling statistics generated by Python’s profilers. It reads
output from both @ref{b7,,profiling.tracing} (deterministic profiler) and
@ref{b6,,profiling.sampling} (statistical profiler).

@menu
* Reading and displaying profile data:: 
* The Stats class:: 
* Command-line interface: Command-line interface<10>. 

@end menu

@node Reading and displaying profile data,The Stats class,,pstats — Statistics for profilers
@anchor{library/pstats reading-and-displaying-profile-data}@anchor{4ae5}
@subsubsection Reading and displaying profile data


The @ref{4a6d,,Stats} class is the primary interface for working with profile
data. It can read statistics from files or directly from a
@ref{4a6f,,Profile} object.

Load statistics from a file and print a basic report:

@example
import pstats

p = pstats.Stats('profile_output.prof')
p.print_stats()
@end example

The @ref{4a6d,,Stats} object provides methods for sorting and filtering the
data before printing. For example, to see the ten functions with the highest
cumulative time:

@example
from pstats import SortKey

p = pstats.Stats('profile_output.prof')
p.sort_stats(SortKey.CUMULATIVE).print_stats(10)
@end example

@menu
* Working with statistics:: 
* Filtering output:: 
* Analyzing call relationships:: 
* Combining multiple profiles:: 

@end menu

@node Working with statistics,Filtering output,,Reading and displaying profile data
@anchor{library/pstats working-with-statistics}@anchor{4ae6}
@subsubsection Working with statistics


The @ref{4a6d,,Stats} class supports method chaining, making it convenient to
perform multiple operations:

@example
p = pstats.Stats('restats')
p.strip_dirs().sort_stats(-1).print_stats()
@end example

The @ref{4ae7,,strip_dirs()} method removes directory paths from filenames,
making the output more compact. The @ref{4a66,,sort_stats()} method accepts
various keys to control the sort order.

Different sort keys highlight different aspects of performance:

@example
from pstats import SortKey

# Functions that consume the most cumulative time
p.sort_stats(SortKey.CUMULATIVE).print_stats(10)

# Functions that consume the most time in their own code
p.sort_stats(SortKey.TIME).print_stats(10)

# Functions sorted by name
p.sort_stats(SortKey.NAME).print_stats()
@end example

@node Filtering output,Analyzing call relationships,Working with statistics,Reading and displaying profile data
@anchor{library/pstats filtering-output}@anchor{4ae8}
@subsubsection Filtering output


The @ref{4ae9,,print_stats()} method accepts restrictions that filter
which functions are displayed. Restrictions can be integers (limiting the
count), floats between 0 and 1 (selecting a percentage), or strings (matching
function names via regular expression).

Print only the top 10%:

@example
p.print_stats(.1)
@end example

Print only functions whose names contain «init»:

@example
p.print_stats('init')
@end example

Combine restrictions (they apply sequentially):

@example
# Top 10%, then only those containing "init"
p.print_stats(.1, 'init')

# Functions in files matching "foo:", limited to top 50%
p.sort_stats(SortKey.FILENAME).print_stats('foo:', .5)
@end example

@node Analyzing call relationships,Combining multiple profiles,Filtering output,Reading and displaying profile data
@anchor{library/pstats analyzing-call-relationships}@anchor{4aea}
@subsubsection Analyzing call relationships


The @ref{4a5a,,print_callers()} method shows which functions called each
displayed function:

@example
p.print_callers()
@end example

The @ref{4a5b,,print_callees()} method shows the opposite relationship,
listing which functions each displayed function called:

@example
p.print_callees()
@end example

Both methods accept the same restriction arguments as @ref{4ae9,,print_stats()}.

@node Combining multiple profiles,,Analyzing call relationships,Reading and displaying profile data
@anchor{library/pstats combining-multiple-profiles}@anchor{4aeb}
@subsubsection Combining multiple profiles


Statistics from multiple profiling runs can be combined into a single
@ref{4a6d,,Stats} object:

@example
# Load multiple files at once
p = pstats.Stats('run1.prof', 'run2.prof', 'run3.prof')

# Or add files incrementally
p = pstats.Stats('run1.prof')
p.add('run2.prof')
p.add('run3.prof')
@end example

When files are combined, statistics for identical functions (same file, line,
and name) are accumulated, giving an aggregate view across all profiling runs.

@node The Stats class,Command-line interface<10>,Reading and displaying profile data,pstats — Statistics for profilers
@anchor{library/pstats the-stats-class}@anchor{4aec}
@subsubsection The @code{Stats} class


@geindex Stats (κλάση σε pstats)
@anchor{library/pstats pstats Stats}@anchor{4a6d}
@deffn {Κλάση} pstats.Stats (*filenames_or_profile, stream=sys.stdout)

Create a statistics object from profile data.

The arguments can be filenames (strings or path-like objects) or
@ref{4a6f,,Profile} objects. If multiple sources are
provided, their statistics are combined.

The `stream' argument specifies where output from @ref{4ae9,,print_stats()} and
related methods is written. It defaults to @ref{e9c,,sys.stdout}.

The profile data format is specific to the Python version that created it.
There is no compatibility guarantee between Python versions or between
different profilers.

@geindex strip_dirs() (μέθοδος της pstats.Stats)
@anchor{library/pstats pstats Stats strip_dirs}@anchor{4ae7}
@deffn {Μέθοδος} strip_dirs ()

Remove leading path information from all filenames.

This method modifies the object in place and returns it for method
chaining. After stripping, the statistics are considered to be in
random order.

If stripping causes two functions to become indistinguishable (same
filename, line number, and function name), their statistics are
combined into a single entry.
@end deffn

@geindex add() (μέθοδος της pstats.Stats)
@anchor{library/pstats pstats Stats add}@anchor{4aed}
@deffn {Μέθοδος} add (*filenames)

Add profiling data from additional files.

The files must have been created by the same profiler type. Statistics
for identical functions are accumulated.
@end deffn

@geindex dump_stats() (μέθοδος της pstats.Stats)
@anchor{library/pstats pstats Stats dump_stats}@anchor{4aee}
@deffn {Μέθοδος} dump_stats (filename)

Save the current statistics to a file.

The file is created if it does not exist and overwritten if it does.
The saved data can be loaded by creating a new @code{Stats} object.
@end deffn

@geindex sort_stats() (μέθοδος της pstats.Stats)
@anchor{library/pstats pstats Stats sort_stats}@anchor{4a66}
@deffn {Μέθοδος} sort_stats (*keys)

Sort the statistics according to the specified criteria.

Each key can be a string or a @ref{4aef,,SortKey} enum member. When
multiple keys are provided, later keys break ties in earlier keys.

Using @ref{4aef,,SortKey} enum members is preferred over strings as it
provides better error checking:

@example
from pstats import SortKey
p.sort_stats(SortKey.CUMULATIVE)
@end example

Valid sort keys:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

String

@tab

Enum

@tab

Meaning

@item

@code{'calls'}

@tab

@code{SortKey.CALLS}

@tab

call count

@item

@code{'cumulative'}

@tab

@code{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

@code{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

@code{SortKey.PCALLS}

@tab

primitive call count

@item

@code{'line'}

@tab

@code{SortKey.LINE}

@tab

line number

@item

@code{'name'}

@tab

@code{SortKey.NAME}

@tab

function name

@item

@code{'nfl'}

@tab

@code{SortKey.NFL}

@tab

name/file/line

@item

@code{'stdname'}

@tab

@code{SortKey.STDNAME}

@tab

standard name

@item

@code{'time'}

@tab

@code{SortKey.TIME}

@tab

internal time

@item

@code{'tottime'}

@tab

N/A

@tab

internal time

@end multitable


All sorts on statistics are in descending order (most time consuming
first), while name, file, and line number sorts are ascending
(alphabetical).

The difference between @code{SortKey.NFL} and @code{SortKey.STDNAME} is that
NFL sorts line numbers numerically while STDNAME sorts them as strings.
@code{sort_stats(SortKey.NFL)} is equivalent to
@code{sort_stats(SortKey.NAME, SortKey.FILENAME, SortKey.LINE)}.

For backward compatibility, the numeric arguments @code{-1}, @code{0}, @code{1},
and @code{2} are also accepted, meaning @code{'stdname'}, @code{'calls'},
@code{'time'}, and @code{'cumulative'} respectively.


Added in version 3.7: The @ref{4aef,,SortKey} enum.

@end deffn

@geindex reverse_order() (μέθοδος της pstats.Stats)
@anchor{library/pstats pstats Stats reverse_order}@anchor{4af0}
@deffn {Μέθοδος} reverse_order ()

Reverse the current sort order.

By default, the sort direction is chosen appropriately for the sort key
(descending for time-based keys, ascending for name-based keys). This
method inverts that choice.
@end deffn

@geindex print_stats() (μέθοδος της pstats.Stats)
@anchor{library/pstats pstats Stats print_stats}@anchor{4ae9}
@deffn {Μέθοδος} print_stats (*restrictions)

Print a report of the profiling statistics.

The output includes a header line summarizing the data, followed by a
table of function statistics sorted according to the last
@ref{4a66,,sort_stats()} call.

Restrictions filter the output. Each restriction is either:


@itemize -

@item 
An integer: limits output to that many entries

@item 
A float between 0.0 and 1.0: selects that fraction of entries

@item 
A string: matches function names via regular expression
@end itemize

Restrictions are applied sequentially. For example:

@example
print_stats(.1, 'foo:')
@end example

First limits to the top 10%, then filters to functions matching “foo:”.
@end deffn

@geindex print_callers() (μέθοδος της pstats.Stats)
@anchor{library/pstats pstats Stats print_callers}@anchor{4a5a}
@deffn {Μέθοδος} print_callers (*restrictions)

Print the callers of each function in the statistics.

For each function in the filtered results, shows which functions called
it and how often.

With @ref{b7,,profiling.tracing} (or @code{cProfile}), each caller line
shows three numbers: the number of calls from that caller, and the
total and cumulative times for those specific calls.

Accepts the same restriction arguments as @ref{4ae9,,print_stats()}.
@end deffn

@geindex print_callees() (μέθοδος της pstats.Stats)
@anchor{library/pstats pstats Stats print_callees}@anchor{4a5b}
@deffn {Μέθοδος} print_callees (*restrictions)

Print the functions called by each function in the statistics.

This is the inverse of @ref{4a5a,,print_callers()}, showing which functions
each listed function called.

Accepts the same restriction arguments as @ref{4ae9,,print_stats()}.
@end deffn

@geindex get_stats_profile() (μέθοδος της pstats.Stats)
@anchor{library/pstats pstats Stats get_stats_profile}@anchor{4af1}
@deffn {Μέθοδος} get_stats_profile ()

Return a @code{StatsProfile} object containing the statistics.

The returned object provides programmatic access to the profile data,
with function names mapped to @code{FunctionProfile} objects
containing timing and call count information.


Added in version 3.9.

@end deffn
@end deffn

@geindex SortKey (κλάση σε pstats)
@anchor{library/pstats pstats SortKey}@anchor{4aef}
@deffn {Κλάση} pstats.SortKey

An enumeration of valid sort keys for @ref{4a66,,Stats.sort_stats()}.

@geindex CALLS (ιδιότητα της pstats.SortKey)
@anchor{library/pstats pstats SortKey CALLS}@anchor{4af2}
@deffn {Ιδιότητα} CALLS

Sort by call count.
@end deffn

@geindex CUMULATIVE (ιδιότητα της pstats.SortKey)
@anchor{library/pstats pstats SortKey CUMULATIVE}@anchor{4af3}
@deffn {Ιδιότητα} CUMULATIVE

Sort by cumulative time.
@end deffn

@geindex FILENAME (ιδιότητα της pstats.SortKey)
@anchor{library/pstats pstats SortKey FILENAME}@anchor{4af4}
@deffn {Ιδιότητα} FILENAME

Sort by file name.
@end deffn

@geindex LINE (ιδιότητα της pstats.SortKey)
@anchor{library/pstats pstats SortKey LINE}@anchor{4af5}
@deffn {Ιδιότητα} LINE

Sort by line number.
@end deffn

@geindex NAME (ιδιότητα της pstats.SortKey)
@anchor{library/pstats pstats SortKey NAME}@anchor{4af6}
@deffn {Ιδιότητα} NAME

Sort by function name.
@end deffn

@geindex NFL (ιδιότητα της pstats.SortKey)
@anchor{library/pstats pstats SortKey NFL}@anchor{4af7}
@deffn {Ιδιότητα} NFL

Sort by name, then file, then line number (numeric line sort).
@end deffn

@geindex PCALLS (ιδιότητα της pstats.SortKey)
@anchor{library/pstats pstats SortKey PCALLS}@anchor{4af8}
@deffn {Ιδιότητα} PCALLS

Sort by primitive (non-recursive) call count.
@end deffn

@geindex STDNAME (ιδιότητα της pstats.SortKey)
@anchor{library/pstats pstats SortKey STDNAME}@anchor{4af9}
@deffn {Ιδιότητα} STDNAME

Sort by standard name (string-based line sort).
@end deffn

@geindex TIME (ιδιότητα της pstats.SortKey)
@anchor{library/pstats pstats SortKey TIME}@anchor{4afa}
@deffn {Ιδιότητα} TIME

Sort by internal time (time in function excluding subcalls).
@end deffn
@end deffn

@node Command-line interface<10>,,The Stats class,pstats — Statistics for profilers
@anchor{library/pstats command-line-interface}@anchor{4afb}@anchor{library/pstats pstats-cli}@anchor{4afc}
@subsubsection Command-line interface


The @code{pstats} module can be invoked as a script to interactively browse
profile data:

@example
python -m pstats profile_output.prof
@end example

This opens a line-oriented interface (built on @ref{1a,,cmd}) for examining the
statistics. Type @code{help} at the prompt for available commands.


@subsubheading Δείτε επίσης



@table @asis

@item @ref{b5,,profiling}

Overview of Python profiling tools.

@item @ref{b7,,profiling.tracing}

Deterministic tracing profiler.

@item @ref{b6,,profiling.sampling}

Statistical sampling profiler.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node timeit — Μέτρηση χρόνου εκτέλεσης μικρών αποσπασμάτων κώδικα,trace — Ιχνηλάτηση ή παρακολούθηση εκτέλεσης εντολών Python,pstats — Statistics for profilers,Debugging and profiling
@anchor{library/timeit doc}@anchor{4afd}@anchor{library/timeit module-timeit}@anchor{f8}@anchor{library/timeit timeit-measure-execution-time-of-small-code-snippets}@anchor{4afe}@anchor{library/timeit translation-repo}@anchor{4aff}
@subsection @code{timeit} — Μέτρηση χρόνου εκτέλεσης μικρών αποσπασμάτων κώδικα


@geindex module; timeit

`Πηγαίος κώδικας:' Lib/timeit.py@footnote{https://github.com/python/cpython/tree/main/Lib/timeit.py}

@geindex Δοκιμή απόδοσης
@geindex Απόδοση


__________________________________________________________________


Αυτό το module παρέχει έναν απλό τρόπο για να μετρήσετε τον χρόνο εκτέλεσης μικρών αποσπασμάτων κώδικα Python. Διαθέτει τόσο @ref{4b00,,Command-line interface} όσο και @ref{4b01,,callable}. Αποφεύγει αρκετές συνηθισμένες παγίδες στη μέτρηση χρόνου εκτέλεσης. Δείτε επίσης την εισαγωγή του Tim Peters στο κεφάλαιο «Αλγόριθμοι» της δεύτερης έκδοσης του `Python Cookbook', που εκδόθηκε από την O’Reilly.

@menu
* Basic examples:: 
* Python interface:: 
* Command-line interface: Command-line interface<11>. 
* Παραδείγματα: Παραδείγματα<5>. 

@end menu

@node Basic examples,Python interface,,timeit — Μέτρηση χρόνου εκτέλεσης μικρών αποσπασμάτων κώδικα
@anchor{library/timeit basic-examples}@anchor{4b02}
@subsubsection Basic examples


Το παρακάτω παράδειγμα δείχνει πώς η @ref{4b00,,Command-line interface} μπορεί να χρησιμοποιηθεί για να συγκρίνει τρεις διαφορετικές εκφράσεις:

@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

Αυτό μπορεί να επιτευχθεί από το @ref{4b01,,Python interface} ως εξής:

@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

Μπορεί επίσης να δοθεί μια καλέσιμη συνάρτηση από το @ref{4b01,,Python interface}:

@example
>>> timeit.timeit(lambda: "-".join(map(str, range(100))), number=10000)
0.19665591977536678
@end example

Σημειώστε όμως ότι η @ref{122f,,timeit()} θα καθορίσει αυτόματα τον αριθμό των επαναλήψεων μόνο όταν χρησιμοποιείται η διεπαφή γραμμής εντολών. Στην ενότητα @ref{4b03,,Παραδείγματα} μπορείτε να βρείτε πιο προχωρημένα παραδείγματα.

@node Python interface,Command-line interface<11>,Basic examples,timeit — Μέτρηση χρόνου εκτέλεσης μικρών αποσπασμάτων κώδικα
@anchor{library/timeit id1}@anchor{4b04}@anchor{library/timeit python-interface}@anchor{4b01}
@subsubsection Python interface


Το module ορίζει τρεις βοηθητικές συναρτήσεις και μία δημόσια κλάση:

@geindex timeit() (στη μονάδα timeit)
@anchor{library/timeit timeit timeit}@anchor{122f}
@deffn {Συνάρτηση} timeit.timeit (stmt='pass', setup='pass', timer=<default timer>, number=1000000, globals=None)

Δημιουργεί ένα στιγμιότυπο της κλάσης @ref{186a,,Timer} με τη δοσμένη εντολή, τον κώδικα `setup' και τη συνάρτηση `timer' και εκτελεί τη μέθοδο @ref{10a9,,timeit()} με `number' εκτελέσεις. Η προαιρετική παράμετρος `globals' καθορίζει το namespace στο οποίο θα εκτελεστεί ο κώδικας.


Άλλαξε στην έκδοση 3.5: Προστέθηκε η προαιρετική παράμετρος `globals'.

@end deffn

@geindex repeat() (στη μονάδα timeit)
@anchor{library/timeit timeit repeat}@anchor{4b05}
@deffn {Συνάρτηση} timeit.repeat (stmt='pass', setup='pass', timer=<default timer>, repeat=5, number=1000000, globals=None)

Δημιουργεί ένα στιγμιότυπο της κλάσης @ref{186a,,Timer} με τη δοσμένη εντολή, τον κώδικα `setup' και τη συνάρτηση `timer' και εκτελεί τη μέθοδο @ref{4b06,,repeat()} με το δοσμένο πλήθος `repeat' και `number' εκτελέσεις. Η προαιρετική παράμετρος `globals' καθορίζει το namespace στο οποίο θα εκτελεστεί ο κώδικας.


Άλλαξε στην έκδοση 3.5: Προστέθηκε η προαιρετική παράμετρος `globals'.



Άλλαξε στην έκδοση 3.7: Η προεπιλεγμένη τιμή του `repeat' άλλαξε από 3 σε 5.

@end deffn

@geindex default_timer() (στη μονάδα timeit)
@anchor{library/timeit timeit default_timer}@anchor{4b07}
@deffn {Συνάρτηση} timeit.default_timer ()

Ο προεπιλεγμένος χρονομετρητής, που είναι πάντα το time.perf_counter(), επιστρέφει δευτερόλεπτα ως float. Εναλλακτικά, το time.perf_counter_ns επιστρέφει ακέραια νανοδευτερόλεπτα.


Άλλαξε στην έκδοση 3.3: Η @ref{e49,,time.perf_counter()} είναι πλέον ο προεπιλεγμένος χρονομετρητής.

@end deffn

@geindex Timer (κλάση σε timeit)
@anchor{library/timeit timeit Timer}@anchor{186a}
@deffn {Κλάση} timeit.Timer (stmt='pass', setup='pass', timer=<timer function>, globals=None)

Κλάση για τη μέτρηση της ταχύτητας εκτέλεσης μικρών αποσπασμάτων κώδικα.

The constructor takes a statement to be timed, an additional statement used
for setup, and a timer function.  Both statements default to @code{'pass'};
the timer function is platform-dependent (see the module doc string).
`stmt' and `setup' may also contain multiple statements separated by @code{;}
or newlines, as long as they don’t contain multi-line string literals.  The
statement will by default be executed within timeit’s namespace; this behavior
can be controlled by passing a namespace to `globals'.

Για να μετρήσετε τον χρόνο εκτέλεσης της πρώτης εντολής, χρησιμοποιήστε τη μέθοδο @ref{10a9,,timeit()}. Οι μέθοδοι @ref{4b06,,repeat()} και @ref{283,,autorange()} είναι μέθοδοι ευκολίας για να καλέσετε τη @code{timeit()} πολλές φορές.

Ο χρόνος εκτέλεσης του `setup' εξαιρείται από τη συνολική χρονομετρημένη εκτέλεση.

Οι παράμετροι `stmt' και `setup' μπορούν επίσης να πάρουν αντικείμενα που είναι καλέσιμα χωρίς ορίσματα. Αυτό θα ενσωματώσει κλήσεις σε αυτά σε μια συνάρτηση χρονομέτρησης που θα εκτελείται στη συνέχεια από τη @ref{10a9,,timeit()}. Σημειώστε ότι το κόστος χρονομέτρησης είναι λίγο μεγαλύτερο σε αυτή την περίπτωση λόγω των επιπλέον κλήσεων των συναρτήσεων.


Άλλαξε στην έκδοση 3.5: Προστέθηκε η προαιρετική παράμετρος `globals'.


@geindex timeit() (μέθοδος της timeit.Timer)
@anchor{library/timeit timeit Timer timeit}@anchor{10a9}
@deffn {Μέθοδος} timeit (number=1000000)

Χρονομετρεί `number' εκτελέσεις της κύριας εντολής. Αυτή εκτελεί την εντολή setup μία φορά και στη συνέχεια επιστρέφει το χρόνο που απαιτείται για να εκτελέσει την κύρια εντολή πολλές φορές. Ο προεπιλεγμένος χρονομετρητής επιστρέφει δευτερόλεπτα ως float. Το όρισμα είναι ο αριθμός των επαναλήψεων, με προεπιλογή το ένα εκατομμύριο. Η κύρια εντολή, η εντολή setup και η συνάρτηση χρονομέτρησης που θα χρησιμοποιηθούν περνιούνται στον κατασκευαστή.

@cartouche
@quotation Σημείωση 
Από προεπιλογή, η @ref{10a9,,timeit()} απενεργοποιεί προσωρινά τον @ref{19de,,garbage collection} κατά τη διάρκεια της χρονομέτρησης. Το πλεονέκτημα αυτής της προσέγγισης είναι ότι καθιστά τις ανεξάρτητες χρονομετρήσεις πιο συγκρίσιμες. Το μειονέκτημα είναι ότι ο GC μπορεί να είναι σημαντικό συστατικό της απόδοσης της λειτουργίας που μετράται. Αν ισχύει αυτό, ο GC μπορεί να ενεργοποιηθεί ξανά ως η πρώτη εντολή στο `setup' string. Για παράδειγμα:

@example
timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
@end example
@end quotation
@end cartouche
@end deffn

@geindex autorange() (μέθοδος της timeit.Timer)
@anchor{library/timeit timeit Timer autorange}@anchor{283}
@deffn {Μέθοδος} autorange (callback=None, target_time=None)

Καθορίζει αυτόματα πόσες φορές θα καλέσει τη @ref{10a9,,timeit()}.

This is a convenience function that calls @ref{10a9,,timeit()} repeatedly
so that the total time >= `Timer.target_time' seconds, returning the eventual
(number of loops, time taken for that number of loops). It calls
@code{timeit()} with increasing numbers from the sequence 1, 2, 5,
10, 20, 50, … until the time taken is at least `target_time' seconds.

Εάν το `callback' είναι δοσμένο και δεν είναι @code{None}, θα κληθεί μετά από κάθε δοκιμή με δύο ορίσματα: @code{callback(number, time_taken)}.


Added in version 3.6.



Άλλαξε στην έκδοση 3.15: The optional `target_time' parameter was added.

@end deffn

@geindex repeat() (μέθοδος της timeit.Timer)
@anchor{library/timeit timeit Timer repeat}@anchor{4b06}
@deffn {Μέθοδος} repeat (repeat=5, number=1000000)

Καλέστε τη @ref{10a9,,timeit()} μερικές φορές.

Αυτή είναι μια συνάρτηση ευκολίας που καλεί τη @ref{10a9,,timeit()} επανειλημμένα, επιστρέφοντας μια λίστα αποτελεσμάτων.  Το πρώτο όρισμα καθορίζει πόσες φορές να καλέσει τη @code{timeit()}.  Το δεύτερο όρισμα καθορίζει το όρισμα `number' για τη @code{timeit()}.

@cartouche
@quotation Σημείωση 
Είναι δελεαστικό να υπολογίσετε τον μέσο όρο και την τυπική απόκλιση από το αποτέλεσμα vector και να τα αναφέρετε. Ωστόσο, αυτό δεν είναι πολύ χρήσιμο. Σε μια τυπική περίπτωση, η χαμηλότερη τιμή δίνει ένα κατώτατο όριο για το πόσο γρήγορα μπορεί να εκτελέσει το μηχάνημα σας το συγκεκριμένο απόσπασμα κώδικα∙ οι υψηλότερες τιμές στο αποτέλεσμα vector συνήθως δεν προκαλούνται από μεταβλητότητα στην ταχύτητα της Python, αλλά από άλλες διεργασίες που παρεμβαίνουν στην ακρίβεια της χρονομέτρησής σας. Έτσι, η @ref{12b9,,min()} του αποτελέσματος είναι πιθανώς ο μόνος αριθμός που θα πρέπει να σας ενδιαφέρει. Μετά από αυτό, θα πρέπει να εξετάσετε ολόκληρο το vector και να εφαρμόσετε κοινή λογική αντί για στατιστικά.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.7: Η προεπιλεγμένη τιμή του `repeat' άλλαξε από 3 σε 5.

@end deffn

@geindex print_exc() (μέθοδος της timeit.Timer)
@anchor{library/timeit timeit Timer print_exc}@anchor{4b08}
@deffn {Μέθοδος} print_exc (file=None)

Βοηθός για την εκτύπωση μιας ανίχνευσης από τον χρονομετρημένο κώδικα.

Τυπική χρήση:

@example
t = Timer(...)       # outside the try/except
try:
    t.timeit(...)    # or t.repeat(...)
except Exception:
    t.print_exc()
@end example

Το πλεονέκτημα σε σχέση με την τυπική ανίχνευση είναι ότι οι γραμμές πηγαίου κώδικα στο μεταγλωττισμένο πρότυπο θα εμφανίζονται. Η προαιρετική παράμετρος `file' καθορίζει πού θα σταλεί η ανίχνευση· η προεπιλογή είναι @ref{d05,,sys.stderr}.
@end deffn
@end deffn

@node Command-line interface<11>,Παραδείγματα<5>,Python interface,timeit — Μέτρηση χρόνου εκτέλεσης μικρών αποσπασμάτων κώδικα
@anchor{library/timeit command-line-interface}@anchor{4b09}@anchor{library/timeit timeit-command-line-interface}@anchor{4b00}
@subsubsection Command-line interface


Όταν καλείται ως πρόγραμμα από τη γραμμή εντολών, χρησιμοποιείται η εξής μορφή:

@example
python -m timeit [-n N] [-r N] [-u U] [-s S] [-p] [-v] [-h] [statement ...]
@end example

Όπου γίνονται κατανοητές οι εξής επιλογές:

@geindex timeit command line option; -n
@geindex timeit command line option; --number
@anchor{library/timeit cmdoption-timeit-n}@anchor{4b0a}@anchor{library/timeit cmdoption-timeit-number}@anchor{4b0b}
@deffn {Option} @w{-}n N, @w{-}@w{-}number=N

πόσες φορές να εκτελεστεί η “statement”
@end deffn

@geindex timeit command line option; -r
@geindex timeit command line option; --repeat
@anchor{library/timeit cmdoption-timeit-r}@anchor{4b0c}@anchor{library/timeit cmdoption-timeit-repeat}@anchor{4b0d}
@deffn {Option} @w{-}r N, @w{-}@w{-}repeat=N

πόσες φορές να επαναληφθεί ο χρονομετρητής (προεπιλογή 5)
@end deffn

@geindex timeit command line option; -s
@geindex timeit command line option; --setup
@anchor{library/timeit cmdoption-timeit-s}@anchor{4b0e}@anchor{library/timeit cmdoption-timeit-setup}@anchor{4b0f}
@deffn {Option} @w{-}s S, @w{-}@w{-}setup=S

δήλωση που θα εκτελείται μία φορά αρχικά (προεπιλογή @code{pass})
@end deffn

@geindex timeit command line option; -p
@geindex timeit command line option; --process
@anchor{library/timeit cmdoption-timeit-p}@anchor{4b10}@anchor{library/timeit cmdoption-timeit-process}@anchor{4b11}
@deffn {Option} @w{-}p, @w{-}@w{-}process

μετράει τον χρόνο διεργασίας, όχι τον χρόνο ρολογιού, χρησιμοποιώντας την @ref{e4a,,time.process_time()} αντί της @ref{e49,,time.perf_counter()}, που είναι η προεπιλογή


Added in version 3.3.

@end deffn

@geindex timeit command line option; -u
@geindex timeit command line option; --unit
@anchor{library/timeit cmdoption-timeit-u}@anchor{4b12}@anchor{library/timeit cmdoption-timeit-unit}@anchor{4b13}
@deffn {Option} @w{-}u, @w{-}@w{-}unit=U

καθορίζει μια μονάδα χρόνου για την έξοδο του χρονομέτρου· μπορεί να επιλέξει @code{nsec}, @code{usec}, @code{msec} ή @code{sec}


Added in version 3.5.

@end deffn

@geindex timeit command line option; -t
@geindex timeit command line option; --target-time
@anchor{library/timeit cmdoption-timeit-t}@anchor{4b14}@anchor{library/timeit cmdoption-timeit-target-time}@anchor{4b15}
@deffn {Option} @w{-}t, @w{-}@w{-}target@w{-}time=T

if @ref{4b0a,,--number} is 0, the code will run until it takes at
least this many seconds (default: 0.2)


Added in version 3.15.

@end deffn

@geindex timeit command line option; -v
@geindex timeit command line option; --verbose
@anchor{library/timeit cmdoption-timeit-v}@anchor{4b16}@anchor{library/timeit cmdoption-timeit-verbose}@anchor{4b17}
@deffn {Option} @w{-}v, @w{-}@w{-}verbose

τυπώνει τα ακατέργαστα αποτελέσματα χρονομέτρησης· επαναλάβετε για περισσότερη ακρίβεια ψηφίων
@end deffn

@geindex timeit command line option; -h
@geindex timeit command line option; --help
@anchor{library/timeit cmdoption-timeit-h}@anchor{4b18}@anchor{library/timeit cmdoption-timeit-help}@anchor{4b19}
@deffn {Option} @w{-}h, @w{-}@w{-}help

τυπώνει ένα σύντομο μήνυμα χρήσης και εξέρχεται
@end deffn

Μια πολυγραμμική δήλωση μπορεί να δοθεί καθορίζοντας κάθε γραμμή ως ξεχωριστό όρισμα δήλωσης∙ οι εσοχές είναι δυνατές περικλείοντας ένα όρισμα σε εισαγωγικά και χρησιμοποιώντας αρχικά κενά.  Πολλαπλές επιλογές @ref{4b0e,,-s} θεωρούνται παρόμοιες.

If @ref{4b0a,,-n} is not given, a suitable number of loops is calculated by trying
increasing numbers from the sequence 1, 2, 5, 10, 20, 50, … until the total
time is at least @ref{4b14,,--target-time} seconds (default: 0.2).

Οι μετρήσεις της @ref{4b07,,default_timer()} μπορεί να επηρεαστούν από άλλα προγράμματα που εκτελούνται στο ίδιο μηχάνημα, οπότε το καλύτερο πράγμα που μπορείτε να κάνετε όταν απαιτείται ακριβής χρονομέτρηση είναι να επαναλάβετε τη χρονομέτρηση μερικές φορές και να χρησιμοποιήσετε τον καλύτερο χρόνο. Η επιλογή @ref{4b0c,,-r} είναι καλή γι” αυτό· η προεπιλογή των 5 επαναλήψεων είναι μάλλον αρκετή στις περισσότερες περιπτώσεις. Μπορείτε να χρησιμοποιήσετε την @ref{e4a,,time.process_time()} για να μετρήσετε τον χρόνο CPU.

@cartouche
@quotation Σημείωση 
Υπάρχει μια συγκεκριμένη βασική καθυστέρηση που σχετίζεται με την εκτέλεση μιας δήλωσης pass. Ο κώδικας εδώ δεν προσπαθεί να την αποκρύψει, αλλά θα πρέπει να είστε ενήμεροι γι” αυτήν.  Η βασική καθυστέρηση μπορεί να μετρηθεί καλώντας το πρόγραμμα χωρίς ορίσματα, και μπορεί να διαφέρει μεταξύ των εκδόσεων της Python.
@end quotation
@end cartouche


Added in version 3.15: Output is in color by default and can be
@ref{1af,,controlled using environment variables}.


@node Παραδείγματα<5>,,Command-line interface<11>,timeit — Μέτρηση χρόνου εκτέλεσης μικρών αποσπασμάτων κώδικα
@anchor{library/timeit examples}@anchor{4b1a}@anchor{library/timeit timeit-examples}@anchor{4b03}
@subsubsection Παραδείγματα


Είναι δυνατόν να δοθεί μια δήλωση setup που εκτελείται μόνο μία φορά στην αρχή:

@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

Στην έξοδο, υπάρχουν τρία πεδία. Ο αριθμός επαναλήψεων, που σας λέει πόσες φορές το σώμα της δήλωσης εκτελέστηκε ανά επανάληψη του χρονομετρημένου βρόχου. Ο αριθμός των επαναλήψεων (“best of 5”) που σας λέει πόσες φορές η χρονομέτρηση επαναλήφθηκε, και τέλος ο χρόνος που χρειάστηκε το σώμα της δήλωσης κατά μέσο όρο μέσα στην καλύτερη επανάληψη του χρονομετρημένου βρόχου. Δηλαδή, ο χρόνος που χρειάστηκε η ταχύτερη επανάληψη διαιρούμενος με τον αριθμό επαναλήψεων.

@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

Το ίδιο μπορεί να γίνει χρησιμοποιώντας την κλάση @ref{186a,,Timer} και τις μεθόδους της:

@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

Τα παρακάτω παραδείγματα δείχνουν πως να χρονομετρήσετε εκφράσεις που περιέχουν πολλαπλές γραμμές. Εδώ συγκρίνουμε το κόστος της χρήσης της @ref{8e2,,hasattr()} σε σχέση με το @ref{ad6,,try}/@ref{447,,except} για να ελέγξουμε για απουσία και παρουσία χαρακτηριστικών αντικειμένων:

@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

To give the @code{timeit} module access to functions you define, you can pass a
`setup' parameter which contains an import statement:

@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

Μια άλλη επιλογή είναι να περάσετε τη @ref{1e01,,globals()} στην παράμετρο `globals', η οποία θα προκαλέσει την εκτέλεση του κώδικα στο τρέχον global namespace σας. Αυτό μπορεί να είναι πιο βολικό από το να καθορίσετε μεμονωμένα τις εισαγωγές (imports):

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node trace — Ιχνηλάτηση ή παρακολούθηση εκτέλεσης εντολών Python,tracemalloc — Trace memory allocations,timeit — Μέτρηση χρόνου εκτέλεσης μικρών αποσπασμάτων κώδικα,Debugging and profiling
@anchor{library/trace doc}@anchor{4b1b}@anchor{library/trace module-trace}@anchor{106}@anchor{library/trace trace-trace-or-track-python-statement-execution}@anchor{4b1c}@anchor{library/trace translation-repo}@anchor{4b1d}
@subsection @code{trace} — Ιχνηλάτηση ή παρακολούθηση εκτέλεσης εντολών Python


@geindex module; trace

`Source code:' Lib/trace.py@footnote{https://github.com/python/cpython/tree/main/Lib/trace.py}


__________________________________________________________________


The @code{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 Δείτε επίσης



@table @asis

@item Coverage.py@footnote{https://coverage.readthedocs.io/}

Ένα δημοφιλές εργαλείο (διανέμεται από τρίτους) που παράγει αποτελέσματα σε HTML και διαθέτει ανεπτυγμένες δυνατότητες όπως branch coverage.
@end table


@menu
* Οδηγίες χρήσης γραμμής εντολών:: 
* Προγραμματιστική διεπαφή:: 

@end menu

@node Οδηγίες χρήσης γραμμής εντολών,Προγραμματιστική διεπαφή,,trace — Ιχνηλάτηση ή παρακολούθηση εκτέλεσης εντολών Python
@anchor{library/trace command-line-usage}@anchor{4b1e}@anchor{library/trace trace-cli}@anchor{4b1f}
@subsubsection Οδηγίες χρήσης γραμμής εντολών


The @code{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

Το παραπάνω θα εκτελέσει το αρχείο @code{somefile.py} και θα παράγει μια σημειωμένη λίστα με όλα τα Python modules που εισήχθησαν κατά την εκτέλεση στον τρέχων φάκελο.

@geindex trace command line option; --help
@anchor{library/trace cmdoption-trace-help}@anchor{4b20}
@deffn {Option} @w{-}@w{-}help

Εμφανίζει τις οδηγίες χρήσης και τερματίζει την εκτέλεση.
@end deffn

@geindex trace command line option; --version
@anchor{library/trace cmdoption-trace-version}@anchor{4b21}
@deffn {Option} @w{-}@w{-}version

Εμφανίζει την έκδοση του module και τερματίζει την εκτέλεση.
@end deffn


Added in version 3.8: Added @code{--module} option that allows running an executable module.


@menu
* Κύριες επιλογές:: 
* Τροποποιητές:: 
* Φίλτρα:: 

@end menu

@node Κύριες επιλογές,Τροποποιητές,,Οδηγίες χρήσης γραμμής εντολών
@anchor{library/trace main-options}@anchor{4b22}
@subsubsection Κύριες επιλογές


At least one of the following options must be specified when invoking
@code{trace}.  The @ref{4b23,,--listfuncs} option is mutually exclusive with
the @ref{4b24,,--trace} and @ref{4b25,,--count} options. When
@code{--listfuncs} is provided, neither @code{--count} nor
@code{--trace} are accepted, and vice versa.

@geindex trace command line option; -c
@geindex trace command line option; --count
@anchor{library/trace cmdoption-trace-c}@anchor{4b25}@anchor{library/trace cmdoption-trace-count}@anchor{4b26}
@deffn {Option} @w{-}c, @w{-}@w{-}count

Κατά την ολοκλήρωση του προγράμματος δημιουργεί ένα σύνολο από σημειωμένα αρχεία όπου φαίνεται πόσες φορές εκτελέσθηκε κάθε έκφραση. Βλέπε επίσης @ref{4b27,,--coverdir}, @ref{4b28,,--file} και @ref{4b29,,--no-report} παρακάτω.
@end deffn

@geindex trace command line option; -t
@geindex trace command line option; --trace
@anchor{library/trace cmdoption-trace-t}@anchor{4b24}@anchor{library/trace cmdoption-trace-trace}@anchor{4b2a}
@deffn {Option} @w{-}t, @w{-}@w{-}trace

Εμφανίζει τις γραμμές όπως εκτελούνται.
@end deffn

@geindex trace command line option; -l
@geindex trace command line option; --listfuncs
@anchor{library/trace cmdoption-trace-l}@anchor{4b23}@anchor{library/trace cmdoption-trace-listfuncs}@anchor{4b2b}
@deffn {Option} @w{-}l, @w{-}@w{-}listfuncs

Εμφανίζει τις συναρτήσεις που εκτελούνται τρέχοντας το πρόγραμμα.
@end deffn

@geindex trace command line option; -r
@geindex trace command line option; --report
@anchor{library/trace cmdoption-trace-r}@anchor{4b2c}@anchor{library/trace cmdoption-trace-report}@anchor{4b2d}
@deffn {Option} @w{-}r, @w{-}@w{-}report

Παράγει μία σημειωμένη λίστα από την πρότερη εκτέλεση ενός προγράμματος που χρησιμοποίησε την επιλογή @ref{4b25,,--count} και @ref{4b28,,--file}. Δεν εκτελείται κάποιος κώδικας με την παρούσα επιλογή.
@end deffn

@geindex trace command line option; -T
@geindex trace command line option; --trackcalls
@anchor{library/trace cmdoption-trace-T}@anchor{4b2e}@anchor{library/trace cmdoption-trace-trackcalls}@anchor{4b2f}
@deffn {Option} @w{-}T, @w{-}@w{-}trackcalls

Εμφανίζει τις σχέσεις κλήσεων που δημιουργούνται εκτελώντας το πρόγραμμα.
@end deffn

@node Τροποποιητές,Φίλτρα,Κύριες επιλογές,Οδηγίες χρήσης γραμμής εντολών
@anchor{library/trace modifiers}@anchor{4b30}
@subsubsection Τροποποιητές


@geindex trace command line option; -f
@geindex trace command line option; --file
@anchor{library/trace cmdoption-trace-f}@anchor{4b28}@anchor{library/trace cmdoption-trace-file}@anchor{4b31}
@deffn {Option} @w{-}f, @w{-}@w{-}file=<file>

Όνομα αρχείου όπου σωρεύονται οι μετρήσεις πολλαπλών ιχνηλατήσεων.  Πρέπει να χρησιμοποιείται με την επιλογή @ref{4b25,,--count}.
@end deffn

@geindex trace command line option; -C
@geindex trace command line option; --coverdir
@anchor{library/trace cmdoption-trace-C}@anchor{4b27}@anchor{library/trace cmdoption-trace-coverdir}@anchor{4b32}
@deffn {Option} @w{-}C, @w{-}@w{-}coverdir=<dir>

Κατάλογος όπου αποθηκεύονται τα αρχεία αναφοράς. Η αναφορά κάλυψης (coverage report) για το @code{package.module} εγγράφεται στο αρχείο @code{`dir'/`package'/`module'.cover}.
@end deffn

@geindex trace command line option; -m
@geindex trace command line option; --missing
@anchor{library/trace cmdoption-trace-m}@anchor{4b33}@anchor{library/trace cmdoption-trace-missing}@anchor{4b34}
@deffn {Option} @w{-}m, @w{-}@w{-}missing

Κατά την παραγωγή σημειωμένων λιστών, σημειώνει τις γραμμές που δεν εκτελέστηκαν με  @code{>>>>>>}.
@end deffn

@geindex trace command line option; -s
@geindex trace command line option; --summary
@anchor{library/trace cmdoption-trace-s}@anchor{4b35}@anchor{library/trace cmdoption-trace-summary}@anchor{4b36}
@deffn {Option} @w{-}s, @w{-}@w{-}summary

Κατά την χρήση της επιλογής @ref{4b25,,--count} ή της επιλογής @ref{4b2c,,--report}, γράφει μία σύντομη περίληψη για κάθε αρχείο που επεξεργάζεται.
@end deffn

@geindex trace command line option; -R
@geindex trace command line option; --no-report
@anchor{library/trace cmdoption-trace-R}@anchor{4b29}@anchor{library/trace cmdoption-trace-no-report}@anchor{4b37}
@deffn {Option} @w{-}R, @w{-}@w{-}no@w{-}report

Δεν δημιουργεί σημειωμένες λίστες. Αυτή η επιλογή είναι χρήσιμη εάν σκοπεύετε να κάνετε πολλές εκτελέσεις με την επιλογή @ref{4b25,,--count} και τελικώς δημιουργήσετε ένα ενιαίο σύνολο σημειωμένων λιστών.
@end deffn

@geindex trace command line option; -g
@geindex trace command line option; --timing
@anchor{library/trace cmdoption-trace-g}@anchor{4b38}@anchor{library/trace cmdoption-trace-timing}@anchor{4b39}
@deffn {Option} @w{-}g, @w{-}@w{-}timing

Προθεμάτιζει κάθε γραμμή με τον χρόνο που παρήλθε από την εκκίνηση του προγράμματος. Χρησιμοποιείται μόνο κατά την ιχνηλάτηση.
@end deffn

@node Φίλτρα,,Τροποποιητές,Οδηγίες χρήσης γραμμής εντολών
@anchor{library/trace filters}@anchor{4b3a}
@subsubsection Φίλτρα


Αυτές οι επιλογές μπορούν να επαναληφθούν πολλαπλές φορές.

@geindex trace command line option; --ignore-module
@anchor{library/trace cmdoption-trace-ignore-module}@anchor{4b3b}
@deffn {Option} @w{-}@w{-}ignore@w{-}module=<mod>

Αγνόησε κάθε ένα από τα δεδομένα modules και submodules (εάν είναι πακέτο). Το όρισμα μπορεί να είναι μία λίστα από ονόματα διαχωρισμένα με κόμμα.
@end deffn

@geindex trace command line option; --ignore-dir
@anchor{library/trace cmdoption-trace-ignore-dir}@anchor{4b3c}
@deffn {Option} @w{-}@w{-}ignore@w{-}dir=<dir>

Αγνοεί όλα τα modules και πακέτα στους δεδομένους φακέλους και υποφακέλους. Το όρισμα μπορεί να είναι μία λίστα από φάκελους που χωρίζονται με @ref{2322,,os.pathsep}.
@end deffn

@node Προγραμματιστική διεπαφή,,Οδηγίες χρήσης γραμμής εντολών,trace — Ιχνηλάτηση ή παρακολούθηση εκτέλεσης εντολών Python
@anchor{library/trace programmatic-interface}@anchor{4b3d}@anchor{library/trace trace-api}@anchor{4b3e}
@subsubsection Προγραμματιστική διεπαφή


@geindex Trace (κλάση σε trace)
@anchor{library/trace trace Trace}@anchor{4b3f}
@deffn {Κλάση} trace.Trace (count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

Δημιουργεί ένα αντικείμενο για την ιχνηλάτηση της εκτέλεσης μίας μόνο εντολής ή έκφρασης. Όλες οι παράμετροι είναι προαιρετικές. Η `count' επιτρέπει την αρίθμηση των γραμμών. Η `trace' επιτρέπει την ιχνηλάτηση εκτελέσεων ανά γραμμή. Η `countfuncs' επιτρέπει την αρίθμηση των συναρτήσεων που εκλήθησαν κατά την εκτέλεση. Η `countcallers' επιτρέπει την ιχνηλάτηση συσχετισμένων κλήσεων. Η `ignoremods' είναι μία λίστα με modules ή πακέτα προς παράβλεψη. Η `ignoredirs' είναι μία λίστα φακέλων με προς παράβλεψη modules ή πακέτα. Η `infile' είναι το όνομα του αρχείου εκ του οποίου θα ληφθούν αποθηκευμένα αποτελέσματα ιχνηλατήσεων. Η `outfile' είναι το όνομα του αρχείου εις το οποίο θα εγγραφούν τα νεώτερα αποτελέσματα ιχνηλάτησης. Η `timing' ενεργοποιεί μία χρονοσφραγίδα σχετική με την έναρξη της εμφάνισης ιχνηλάτησης.

@geindex run() (μέθοδος της trace.Trace)
@anchor{library/trace trace Trace run}@anchor{4b40}
@deffn {Μέθοδος} run (cmd)

Εκτελεί την εντολή και συλλέγει στατιστικά από την εκτέλεση με τις τρέχουσες επιλογές ιχνηλάτησης. Η `cmd' πρέπει να είναι μία συμβολοσειρά ή αντικείμενο κώδικα, κατάλληλο για διαβίβαση στην συνάρτηση @ref{185,,exec()}.
@end deffn

@geindex runctx() (μέθοδος της trace.Trace)
@anchor{library/trace trace Trace runctx}@anchor{4b41}
@deffn {Μέθοδος} runctx (cmd, globals=None, locals=None)

Εκτελεί την εντολή και συλλέγει στατιστικά από την εκτέλεση με τις τρέχουσες επιλογές ιχνηλάτησης, στο ορισμένο καθολικό και τοπικό περιβάλλον. Εάν δεν ορισθούν, οι `globals' και `locals' λαμβάνουν την τιμή κενού dictionary.
@end deffn

@geindex runfunc() (μέθοδος της trace.Trace)
@anchor{library/trace trace Trace runfunc}@anchor{e41}
@deffn {Μέθοδος} runfunc (func, /, *args, **kwds)

Καλεί την `func' με τα δεδομένα ορίσματα υπό τον έλεγχο του αντικειμένου @ref{4b3f,,Trace} με τις τρέχουσες επιλογές ιχνηλάτησης.
@end deffn

@geindex results() (μέθοδος της trace.Trace)
@anchor{library/trace trace Trace results}@anchor{4b42}
@deffn {Μέθοδος} results ()

Επιστρέφει ένα αντικείμενο @ref{4b43,,CoverageResults} που περιέχει τα σωρευτικά αποτελέσματα όλων των προηγούμενων κλήσεων στις @code{run}, @code{runctx} και @code{runfunc} για το δοθέν @ref{4b3f,,Trace} στιγμιότυπο. Δεν επαναφέρει τα συσσωρευμένα αποτελέσματα ιχνηλατήσεων.
@end deffn
@end deffn

@geindex CoverageResults (κλάση σε trace)
@anchor{library/trace trace CoverageResults}@anchor{4b43}
@deffn {Κλάση} trace.CoverageResults

Ένας περιέκτης για αποτελέσματα κάλυψης (coverage results), που δημιουργείται από τη @ref{4b42,,Trace.results()}. Δεν πρέπει να δημιουργείται απευθείας από τον χρήστη.

@geindex update() (μέθοδος της trace.CoverageResults)
@anchor{library/trace trace CoverageResults update}@anchor{4b44}
@deffn {Μέθοδος} update (other)

Συγχωνεύει δεδομένα από ένα άλλο αντικείμενο @ref{4b43,,CoverageResults}.
@end deffn

@geindex write_results() (μέθοδος της trace.CoverageResults)
@anchor{library/trace trace CoverageResults write_results}@anchor{4b45}
@deffn {Μέθοδος} write_results (show_missing=True, summary=False, coverdir=None, *, ignore_missing_files=False)

Γράφει τα αποτελέσματα κάλυψης. Ορίστε την `show_missing' για να εμφανίζονται οι γραμμές που δεν εκτελέσθηκαν. Ορίστε την `summary' ώστε να συμπεριληφθεί στο αποτέλεσμα η περίληψη κάλυψης ανά module. Η `coverdir' προσδιορίζει τον φάκελο εις τον οποίο θα εγγραφούν τα αρχεία με τα αποτελέσματα. Εάν είναι @code{None} τα αποτελέσματα για κάθε αρχείο εγγράφονται στον φάκελο του αρχείου αυτού.

Εάν η `ignore_missing_files' είναι @code{True}, η κάλυψη για μη υπάρχοντα αρχεία  αγνοείται σιωπηρά. Ειδαλλιώς, ένα μη υπάρχον αρχείο θα εγείρει @ref{243,,FileNotFoundError}.


Άλλαξε στην έκδοση 3.13: Προστέθηκε η παράμετρος `ignore_missing_files'.

@end deffn
@end deffn

Ένα απλό παράδειγμα που υποδεικνύει τη χρήση της προγραμματιστικής διεπαφής:

@example
import sys
import trace

# δημιούργησε ένα αντικείμενο Trace λέγοντάς του τι να αγνοήσει και
# εάν θα κάνει ιχνηλάτηση, αρίθμηση γραμμών ή και τα δύο.
tracer = trace.Trace(
    ignoredirs=[sys.prefix, sys.exec_prefix],
    trace=0,
    count=1)

# τρέξε τη νέα εντολή χρησιμοποιώντας τον δεδομένο ιχνηλάτη
tracer.run('main()')

# φτιάξε μια αναφορά τοποθετώντας το αποτέλεσμα στον τρέχων φάκελο
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tracemalloc — Trace memory allocations,,trace — Ιχνηλάτηση ή παρακολούθηση εκτέλεσης εντολών Python,Debugging and profiling
@anchor{library/tracemalloc doc}@anchor{4b46}@anchor{library/tracemalloc module-tracemalloc}@anchor{108}@anchor{library/tracemalloc tracemalloc-trace-memory-allocations}@anchor{4b47}@anchor{library/tracemalloc translation-repo}@anchor{4b48}
@subsection @code{tracemalloc} — Trace memory allocations


@geindex module; tracemalloc


Added in version 3.4.


`Source code:' Lib/tracemalloc.py@footnote{https://github.com/python/cpython/tree/main/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 μεταβλητή περιβάλλοντος; PYTHONTRACEMALLOC
@ref{231c,,PYTHONTRACEMALLOC} environment
variable to @code{1}, or by using @ref{178,,-X} @code{tracemalloc} command line
option. The @ref{231b,,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 μεταβλητή περιβάλλοντος; PYTHONTRACEMALLOC
@ref{231c,,PYTHONTRACEMALLOC} environment variable to @code{25}, or use the
@ref{178,,-X} @code{tracemalloc=25} command line option.

@menu
* Examples: Examples<27>. 
* API:: 

@end menu

@node Examples<27>,API,,tracemalloc — Trace memory allocations
@anchor{library/tracemalloc examples}@anchor{4b49}
@subsubsection Examples


@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,,Examples<27>
@anchor{library/tracemalloc display-the-top-10}@anchor{4b4a}
@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{1e,,collections} module allocated @code{244 KiB} to build
@ref{1cf,,namedtuple} types.

See @ref{4b4b,,Snapshot.statistics()} for more options.

@node Compute differences,Get the traceback of a memory block,Display the top 10,Examples<27>
@anchor{library/tracemalloc compute-differences}@anchor{4b4c}
@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{88,,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{4b4d,,Snapshot.dump()} method to analyze the snapshot offline. Then use the
@ref{4b4e,,Snapshot.load()} method reload the snapshot.

@node Get the traceback of a memory block,Pretty top,Compute differences,Examples<27>
@anchor{library/tracemalloc get-the-traceback-of-a-memory-block}@anchor{4b4f}
@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{7a,,importlib} module to
load data (bytecode and constants) from modules: @code{870.1 KiB}. The traceback is
where the @code{importlib} loaded data most recently: on the @code{import pdb}
line of the @ref{3d,,doctest} module. The traceback may change if a new module is
loaded.

@node Pretty top,,Get the traceback of a memory block,Examples<27>
@anchor{library/tracemalloc pretty-top}@anchor{4b50}
@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{4b4b,,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{4b51}
@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{4b52,,get_traced_memory()} and @ref{d07,,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

Output:

@example
first_size=664, first_peak=3592984
second_size=804, second_peak=29704
@end example

Using @ref{d07,,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{231b,,start()} call. Without the call to
@code{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{4d9,,list}, and writing
@code{sum(range(...))}).

@node API,,Examples<27>,tracemalloc — Trace memory allocations
@anchor{library/tracemalloc api}@anchor{4b53}
@subsubsection API


@menu
* Functions: Functions<9>. 
* DomainFilter:: 
* Filter:: 
* Frame:: 
* Snapshot:: 
* Statistic:: 
* StatisticDiff:: 
* Trace:: 
* Traceback:: 

@end menu

@node Functions<9>,DomainFilter,,API
@anchor{library/tracemalloc functions}@anchor{4b54}
@subsubsection Functions


@geindex clear_traces() (στη μονάδα tracemalloc)
@anchor{library/tracemalloc tracemalloc clear_traces}@anchor{4b55}
@deffn {Συνάρτηση} tracemalloc.clear_traces ()

Clear traces of memory blocks allocated by Python.

See also @ref{1acf,,stop()}.
@end deffn

@geindex get_object_traceback() (στη μονάδα tracemalloc)
@anchor{library/tracemalloc tracemalloc get_object_traceback}@anchor{2126}
@deffn {Συνάρτηση} tracemalloc.get_object_traceback (obj)

Get the traceback where the Python object `obj' was allocated.
Return a @ref{f55,,Traceback} instance, or @code{None} if the @code{tracemalloc}
module is not tracing memory allocations or did not trace the allocation of
the object.

See also @ref{bde,,gc.get_referrers()} and @ref{1cda,,sys.getsizeof()} functions.
@end deffn

@geindex get_traceback_limit() (στη μονάδα tracemalloc)
@anchor{library/tracemalloc tracemalloc get_traceback_limit}@anchor{4b56}
@deffn {Συνάρτηση} tracemalloc.get_traceback_limit ()

Get the maximum number of frames stored in the traceback of a trace.

The @code{tracemalloc} module must be tracing memory allocations to
get the limit, otherwise an exception is raised.

The limit is set by the @ref{231b,,start()} function.
@end deffn

@geindex get_traced_memory() (στη μονάδα tracemalloc)
@anchor{library/tracemalloc tracemalloc get_traced_memory}@anchor{4b52}
@deffn {Συνάρτηση} tracemalloc.get_traced_memory ()

Get the current size and peak size of memory blocks traced by the
@code{tracemalloc} module as a tuple: @code{(current: int, peak: int)}.
@end deffn

@geindex reset_peak() (στη μονάδα tracemalloc)
@anchor{library/tracemalloc tracemalloc reset_peak}@anchor{d07}
@deffn {Συνάρτηση} tracemalloc.reset_peak ()

Set the peak size of memory blocks traced by the @code{tracemalloc} module
to the current size.

Do nothing if the @code{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{4b55,,clear_traces()}. Snapshots taken with
@ref{4b57,,take_snapshot()} before a call to @code{reset_peak()} can be
meaningfully compared to snapshots taken after the call.

See also @ref{4b52,,get_traced_memory()}.


Added in version 3.9.

@end deffn

@geindex get_tracemalloc_memory() (στη μονάδα tracemalloc)
@anchor{library/tracemalloc tracemalloc get_tracemalloc_memory}@anchor{4b58}
@deffn {Συνάρτηση} tracemalloc.get_tracemalloc_memory ()

Get the memory usage in bytes of the @code{tracemalloc} module used to store
traces of memory blocks.
Return an @ref{326,,int}.
@end deffn

@geindex is_tracing() (στη μονάδα tracemalloc)
@anchor{library/tracemalloc tracemalloc is_tracing}@anchor{4b59}
@deffn {Συνάρτηση} tracemalloc.is_tracing ()

@code{True} if the @code{tracemalloc} module is tracing Python memory
allocations, @code{False} otherwise.

See also @ref{231b,,start()} and @ref{1acf,,stop()} functions.
@end deffn

@geindex start() (στη μονάδα tracemalloc)
@anchor{library/tracemalloc tracemalloc start}@anchor{231b}
@deffn {Συνάρτηση} 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{4b5a,,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{4b5b,,Snapshot.compare_to()} and @ref{4b4b,,Snapshot.statistics()} methods.

Storing more frames increases the memory and CPU overhead of the
@code{tracemalloc} module. Use the @ref{4b58,,get_tracemalloc_memory()} function
to measure how much memory is used by the @code{tracemalloc} module.

The 
@geindex PYTHONTRACEMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONTRACEMALLOC
@ref{231c,,PYTHONTRACEMALLOC} environment variable
(@code{PYTHONTRACEMALLOC=NFRAME}) and the @ref{178,,-X} @code{tracemalloc=NFRAME}
command line option can be used to start tracing at startup.

See also @ref{1acf,,stop()}, @ref{4b59,,is_tracing()} and @ref{4b56,,get_traceback_limit()}
functions.
@end deffn

@geindex stop() (στη μονάδα tracemalloc)
@anchor{library/tracemalloc tracemalloc stop}@anchor{1acf}
@deffn {Συνάρτηση} 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{4b57,,take_snapshot()} function to take a snapshot of traces before
clearing them.

See also @ref{231b,,start()}, @ref{4b59,,is_tracing()} and @ref{4b55,,clear_traces()}
functions.
@end deffn

@geindex take_snapshot() (στη μονάδα tracemalloc)
@anchor{library/tracemalloc tracemalloc take_snapshot}@anchor{4b57}
@deffn {Συνάρτηση} tracemalloc.take_snapshot ()

Take a snapshot of traces of memory blocks allocated by Python. Return a new
@ref{4b5c,,Snapshot} instance.

The snapshot does not include memory blocks allocated before the
@code{tracemalloc} module started to trace memory allocations.

Tracebacks of traces are limited to @ref{4b56,,get_traceback_limit()} frames. Use
the `nframe' parameter of the @ref{231b,,start()} function to store more frames.

The @code{tracemalloc} module must be tracing memory allocations to take a
snapshot, see the @ref{231b,,start()} function.

See also the @ref{2126,,get_object_traceback()} function.
@end deffn

@node DomainFilter,Filter,Functions<9>,API
@anchor{library/tracemalloc domainfilter}@anchor{4b5d}
@subsubsection DomainFilter


@geindex DomainFilter (κλάση σε tracemalloc)
@anchor{library/tracemalloc tracemalloc DomainFilter}@anchor{10ad}
@deffn {Κλάση} tracemalloc.DomainFilter (inclusive: bool, domain: int)

Filter traces of memory blocks by their address space (domain).


Added in version 3.6.


@geindex inclusive (ιδιότητα της tracemalloc.DomainFilter)
@anchor{library/tracemalloc tracemalloc DomainFilter inclusive}@anchor{4b5e}
@deffn {Ιδιότητα} inclusive

If `inclusive' is @code{True} (include), match memory blocks allocated
in the address space @ref{4b5f,,domain}.

If `inclusive' is @code{False} (exclude), match memory blocks not allocated
in the address space @ref{4b5f,,domain}.
@end deffn

@geindex domain (ιδιότητα της tracemalloc.DomainFilter)
@anchor{library/tracemalloc tracemalloc DomainFilter domain}@anchor{4b5f}
@deffn {Ιδιότητα} 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{4b60}
@subsubsection Filter


@geindex Filter (κλάση σε tracemalloc)
@anchor{library/tracemalloc tracemalloc Filter}@anchor{4b61}
@deffn {Κλάση} 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{1e4b,,fnmatch.fnmatch()} function for the syntax of
`filename_pattern'. The @code{'.pyc'} file extension is
replaced with @code{'.py'}.

Examples:


@itemize *

@item 
@code{Filter(True, subprocess.__file__)} only includes traces of the
@ref{df,,subprocess} module

@item 
@code{Filter(False, tracemalloc.__file__)} excludes traces of the
@code{tracemalloc} module

@item 
@code{Filter(False, "<unknown>")} excludes empty tracebacks
@end itemize


Άλλαξε στην έκδοση 3.5: The @code{'.pyo'} file extension is no longer replaced with @code{'.py'}.



Άλλαξε στην έκδοση 3.6: Added the @ref{4b62,,domain} attribute.


@geindex domain (ιδιότητα της tracemalloc.Filter)
@anchor{library/tracemalloc tracemalloc Filter domain}@anchor{4b62}
@deffn {Ιδιότητα} 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 (ιδιότητα της tracemalloc.Filter)
@anchor{library/tracemalloc tracemalloc Filter inclusive}@anchor{4b63}
@deffn {Ιδιότητα} inclusive

If `inclusive' is @code{True} (include), only match memory blocks allocated
in a file with a name matching @ref{4b64,,filename_pattern} at line number
@ref{4b65,,lineno}.

If `inclusive' is @code{False} (exclude), ignore memory blocks allocated in
a file with a name matching @ref{4b64,,filename_pattern} at line number
@ref{4b65,,lineno}.
@end deffn

@geindex lineno (ιδιότητα της tracemalloc.Filter)
@anchor{library/tracemalloc tracemalloc Filter lineno}@anchor{4b65}
@deffn {Ιδιότητα} lineno

Line number (@code{int}) of the filter. If `lineno' is @code{None}, the filter
matches any line number.
@end deffn

@geindex filename_pattern (ιδιότητα της tracemalloc.Filter)
@anchor{library/tracemalloc tracemalloc Filter filename_pattern}@anchor{4b64}
@deffn {Ιδιότητα} filename_pattern

Filename pattern of the filter (@code{str}). Read-only property.
@end deffn

@geindex all_frames (ιδιότητα της tracemalloc.Filter)
@anchor{library/tracemalloc tracemalloc Filter all_frames}@anchor{4b66}
@deffn {Ιδιότητα} 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{4b56,,get_traceback_limit()} function and @ref{4b67,,Snapshot.traceback_limit}
attribute.
@end deffn
@end deffn

@node Frame,Snapshot,Filter,API
@anchor{library/tracemalloc frame}@anchor{4b68}
@subsubsection Frame


@geindex Frame (κλάση σε tracemalloc)
@anchor{library/tracemalloc tracemalloc Frame}@anchor{4b69}
@deffn {Κλάση} tracemalloc.Frame

Frame of a traceback.

The @ref{f55,,Traceback} class is a sequence of @code{Frame} instances.

@geindex filename (ιδιότητα της tracemalloc.Frame)
@anchor{library/tracemalloc tracemalloc Frame filename}@anchor{4b6a}
@deffn {Ιδιότητα} filename

Filename (@code{str}).
@end deffn

@geindex lineno (ιδιότητα της tracemalloc.Frame)
@anchor{library/tracemalloc tracemalloc Frame lineno}@anchor{4b6b}
@deffn {Ιδιότητα} lineno

Line number (@code{int}).
@end deffn
@end deffn

@node Snapshot,Statistic,Frame,API
@anchor{library/tracemalloc snapshot}@anchor{4b6c}
@subsubsection Snapshot


@geindex Snapshot (κλάση σε tracemalloc)
@anchor{library/tracemalloc tracemalloc Snapshot}@anchor{4b5c}
@deffn {Κλάση} tracemalloc.Snapshot

Snapshot of traces of memory blocks allocated by Python.

The @ref{4b57,,take_snapshot()} function creates a snapshot instance.

@geindex compare_to() (μέθοδος της tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot compare_to}@anchor{4b5b}
@deffn {Μέθοδος} 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{4b6d,,StatisticDiff} instances grouped by `key_type'.

See the @ref{4b4b,,Snapshot.statistics()} method for `key_type' and `cumulative'
parameters.

The result is sorted from the biggest to the smallest by: absolute value
of @ref{4b6e,,StatisticDiff.size_diff}, @ref{4b6f,,StatisticDiff.size}, absolute
value of @ref{4b70,,StatisticDiff.count_diff}, @ref{4b71,,Statistic.count} and
then by @ref{4b72,,StatisticDiff.traceback}.
@end deffn

@geindex dump() (μέθοδος της tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot dump}@anchor{4b4d}
@deffn {Μέθοδος} dump (filename)

Write the snapshot into a file.

Use @ref{4b4e,,load()} to reload the snapshot.
@end deffn

@geindex filter_traces() (μέθοδος της tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot filter_traces}@anchor{4b73}
@deffn {Μέθοδος} filter_traces (filters)

Create a new @code{Snapshot} instance with a filtered @ref{4b74,,traces}
sequence, `filters' is a list of @ref{10ad,,DomainFilter} and
@ref{4b61,,Filter} instances.  If `filters' is an empty list, return a new
@code{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.


Άλλαξε στην έκδοση 3.6: @ref{10ad,,DomainFilter} instances are now also accepted in `filters'.

@end deffn

@geindex load() (μέθοδος κλάσης της tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot load}@anchor{4b4e}
@deffn {Μέθοδος} classmethod load (filename)

Load a snapshot from a file.

See also @ref{4b4d,,dump()}.
@end deffn

@geindex statistics() (μέθοδος της tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot statistics}@anchor{4b4b}
@deffn {Μέθοδος} statistics (key_type: str, cumulative: bool = False)

Get statistics as a sorted list of @ref{4b75,,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' equal to
@code{'filename'} and @code{'lineno'}.

The result is sorted from the biggest to the smallest by:
@ref{4b76,,Statistic.size}, @ref{4b71,,Statistic.count} and then by
@ref{4b77,,Statistic.traceback}.
@end deffn

@geindex traceback_limit (ιδιότητα της tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot traceback_limit}@anchor{4b67}
@deffn {Ιδιότητα} traceback_limit

Maximum number of frames stored in the traceback of @ref{4b74,,traces}:
result of the @ref{4b56,,get_traceback_limit()} when the snapshot was taken.
@end deffn

@geindex traces (ιδιότητα της tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot traces}@anchor{4b74}
@deffn {Ιδιότητα} traces

Traces of all memory blocks allocated by Python: sequence of
@ref{4b78,,Trace} instances.

The sequence has an undefined order. Use the @ref{4b4b,,Snapshot.statistics()}
method to get a sorted list of statistics.
@end deffn
@end deffn

@node Statistic,StatisticDiff,Snapshot,API
@anchor{library/tracemalloc statistic}@anchor{4b79}
@subsubsection Statistic


@geindex Statistic (κλάση σε tracemalloc)
@anchor{library/tracemalloc tracemalloc Statistic}@anchor{4b75}
@deffn {Κλάση} tracemalloc.Statistic

Statistic on memory allocations.

@ref{4b4b,,Snapshot.statistics()} returns a list of @code{Statistic} instances.

See also the @ref{4b6d,,StatisticDiff} class.

@geindex count (ιδιότητα της tracemalloc.Statistic)
@anchor{library/tracemalloc tracemalloc Statistic count}@anchor{4b71}
@deffn {Ιδιότητα} count

Number of memory blocks (@code{int}).
@end deffn

@geindex size (ιδιότητα της tracemalloc.Statistic)
@anchor{library/tracemalloc tracemalloc Statistic size}@anchor{4b76}
@deffn {Ιδιότητα} size

Total size of memory blocks in bytes (@code{int}).
@end deffn

@geindex traceback (ιδιότητα της tracemalloc.Statistic)
@anchor{library/tracemalloc tracemalloc Statistic traceback}@anchor{4b77}
@deffn {Ιδιότητα} traceback

Traceback where the memory block was allocated, @ref{f55,,Traceback}
instance.
@end deffn
@end deffn

@node StatisticDiff,Trace,Statistic,API
@anchor{library/tracemalloc statisticdiff}@anchor{4b7a}
@subsubsection StatisticDiff


@geindex StatisticDiff (κλάση σε tracemalloc)
@anchor{library/tracemalloc tracemalloc StatisticDiff}@anchor{4b6d}
@deffn {Κλάση} tracemalloc.StatisticDiff

Statistic difference on memory allocations between an old and a new
@ref{4b5c,,Snapshot} instance.

@ref{4b5b,,Snapshot.compare_to()} returns a list of @code{StatisticDiff}
instances. See also the @ref{4b75,,Statistic} class.

@geindex count (ιδιότητα της tracemalloc.StatisticDiff)
@anchor{library/tracemalloc tracemalloc StatisticDiff count}@anchor{4b7b}
@deffn {Ιδιότητα} 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 (ιδιότητα της tracemalloc.StatisticDiff)
@anchor{library/tracemalloc tracemalloc StatisticDiff count_diff}@anchor{4b70}
@deffn {Ιδιότητα} 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 (ιδιότητα της tracemalloc.StatisticDiff)
@anchor{library/tracemalloc tracemalloc StatisticDiff size}@anchor{4b6f}
@deffn {Ιδιότητα} 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 (ιδιότητα της tracemalloc.StatisticDiff)
@anchor{library/tracemalloc tracemalloc StatisticDiff size_diff}@anchor{4b6e}
@deffn {Ιδιότητα} 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 (ιδιότητα της tracemalloc.StatisticDiff)
@anchor{library/tracemalloc tracemalloc StatisticDiff traceback}@anchor{4b72}
@deffn {Ιδιότητα} traceback

Traceback where the memory blocks were allocated, @ref{f55,,Traceback}
instance.
@end deffn
@end deffn

@node Trace,Traceback,StatisticDiff,API
@anchor{library/tracemalloc trace}@anchor{4b7c}
@subsubsection Trace


@geindex Trace (κλάση σε tracemalloc)
@anchor{library/tracemalloc tracemalloc Trace}@anchor{4b78}
@deffn {Κλάση} tracemalloc.Trace

Trace of a memory block.

The @ref{4b74,,Snapshot.traces} attribute is a sequence of @code{Trace}
instances.


Άλλαξε στην έκδοση 3.6: Added the @ref{4b7d,,domain} attribute.


@geindex domain (ιδιότητα της tracemalloc.Trace)
@anchor{library/tracemalloc tracemalloc Trace domain}@anchor{4b7d}
@deffn {Ιδιότητα} 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 (ιδιότητα της tracemalloc.Trace)
@anchor{library/tracemalloc tracemalloc Trace size}@anchor{4b7e}
@deffn {Ιδιότητα} size

Size of the memory block in bytes (@code{int}).
@end deffn

@geindex traceback (ιδιότητα της tracemalloc.Trace)
@anchor{library/tracemalloc tracemalloc Trace traceback}@anchor{4b7f}
@deffn {Ιδιότητα} traceback

Traceback where the memory block was allocated, @ref{f55,,Traceback}
instance.
@end deffn
@end deffn

@node Traceback,,Trace,API
@anchor{library/tracemalloc traceback}@anchor{4b80}
@subsubsection Traceback


@geindex Traceback (κλάση σε tracemalloc)
@anchor{library/tracemalloc tracemalloc Traceback}@anchor{f55}
@deffn {Κλάση} tracemalloc.Traceback

Sequence of @ref{4b69,,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{4b56,,get_traceback_limit()} frames. See the @ref{4b57,,take_snapshot()} function.
The original number of frames of the traceback is stored in the
@ref{4b5a,,Traceback.total_nframe} attribute. That allows one to know if a traceback
has been truncated by the traceback limit.

The @ref{4b7f,,Trace.traceback} attribute is a @code{Traceback} instance.


Άλλαξε στην έκδοση 3.7: Frames are now sorted from the oldest to the most recent, instead of most recent to oldest.


@geindex total_nframe (ιδιότητα της tracemalloc.Traceback)
@anchor{library/tracemalloc tracemalloc Traceback total_nframe}@anchor{4b5a}
@deffn {Ιδιότητα} 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


Άλλαξε στην έκδοση 3.9: The @ref{4b5a,,Traceback.total_nframe} attribute was added.


@geindex format() (μέθοδος της tracemalloc.Traceback)
@anchor{library/tracemalloc tracemalloc Traceback format}@anchor{f56}
@deffn {Μέθοδος} format (limit=None, most_recent_first=False)

Format the traceback as a list of lines. Use the @ref{88,,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{4b81,,traceback.format_tb()} function, except that
@code{format()} does not include newlines.

Example:

@example
print("Traceback (most recent call first):")
for line in traceback:
    print(line)
@end example

Output:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Software Packaging and Distribution,Python Runtime Services,Debugging and profiling,The Python Standard Library
@anchor{library/distribution doc}@anchor{4b82}@anchor{library/distribution software-packaging-and-distribution}@anchor{4b83}@anchor{library/distribution translation-repo}@anchor{4b84}
@section Software Packaging and Distribution


These libraries help you with publishing and installing Python software.
While these modules are designed to work in conjunction with the
Python Package Index@footnote{https://pypi.org}, they can also be used
with a local index server, or without any index server at all.

@menu
* ensurepip — Bootstrapping the pip installer:: 
* venv — Creation of virtual environments:: 
* zipapp — Διαχείριση εκτελέσιμων αρχείων zip Python:: 

@end menu

@node ensurepip — Bootstrapping the pip installer,venv — Creation of virtual environments,,Software Packaging and Distribution
@anchor{library/ensurepip doc}@anchor{4b85}@anchor{library/ensurepip ensurepip-bootstrapping-the-pip-installer}@anchor{4b86}@anchor{library/ensurepip module-ensurepip}@anchor{58}
@subsection @code{ensurepip} — Bootstrapping the @code{pip} installer


@geindex module; ensurepip


Added in version 3.4.


`Source code:' Lib/ensurepip@footnote{https://github.com/python/cpython/tree/main/Lib/ensurepip}


__________________________________________________________________


The @code{ensurepip} package provides support for bootstrapping the @code{pip}
installer into an existing Python installation or virtual environment. This
bootstrapping approach reflects the fact that @code{pip} is an independent
project with its own release cycle, and the latest available stable version
is bundled with maintenance and feature releases of the CPython reference
interpreter.

In most cases, end users of Python shouldn’t need to invoke this module
directly (as @code{pip} should be bootstrapped by default), but it may be
needed if installing @code{pip} was skipped when installing Python (or
when creating a virtual environment) or after explicitly uninstalling
@code{pip}.

@cartouche
@quotation Σημείωση 
This module `does not' access the internet. All of the components
needed to bootstrap @code{pip} are included as internal parts of the
package.
@end quotation
@end cartouche

This is an @ref{2347,,optional module}.
If it is missing from your copy of CPython,
look for documentation from your distributor (that is,
whoever provided Python to you).
If you are the distributor, see @ref{2345,,Requirements for optional modules}.

@c Similar notes appear in the docs of the modules:
@c - zipfile
@c - tarfile


@subsubheading Δείτε επίσης



@table @asis

@item @ref{12a6,,Installing Python modules}

The end user guide for installing Python packages

@geindex Python Enhancement Proposals; PEP 453

@item PEP 453@footnote{https://peps.python.org/pep-0453/}: Explicit bootstrapping of pip in Python installations

The original rationale and specification for this module.
@end table


@c include for modules that don't work on WASM or mobile platforms

@ref{232d,,Διαθεσιμότητα}: not Android, not iOS, not WASI.

This module is not supported on @ref{244d,,mobile platforms}
or @ref{1d67,,WebAssembly platforms}.

@menu
* Command-line interface: Command-line interface<12>. 
* Module API:: 

@end menu

@node Command-line interface<12>,Module API,,ensurepip — Bootstrapping the pip installer
@anchor{library/ensurepip command-line-interface}@anchor{4b87}@anchor{library/ensurepip ensurepip-cli}@anchor{4b88}
@subsubsection Command-line interface


The command line interface is invoked using the interpreter’s @code{-m} switch.

The simplest possible invocation is:

@example
python -m ensurepip
@end example

This invocation will install @code{pip} if it is not already installed,
but otherwise does nothing. To ensure the installed version of @code{pip}
is at least as recent as the one available in @code{ensurepip}, pass the
@code{--upgrade} option:

@example
python -m ensurepip --upgrade
@end example

By default, @code{pip} is installed into the current virtual environment
(if one is active) or into the system site packages (if there is no
active virtual environment). The installation location can be controlled
through two additional command line options:

@geindex ensurepip command line option; --root
@anchor{library/ensurepip cmdoption-ensurepip-root}@anchor{4b89}
@deffn {Option} @w{-}@w{-}root <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.
@end deffn

@geindex ensurepip command line option; --user
@anchor{library/ensurepip cmdoption-ensurepip-user}@anchor{4b8a}
@deffn {Option} @w{-}@w{-}user

Installs @code{pip} into the user site packages directory rather than globally
for the current Python installation (this option is not permitted inside an
active virtual environment).
@end deffn

By default, the scripts @code{pipX} and @code{pipX.Y} will be installed (where
X.Y stands for the version of Python used to invoke @code{ensurepip}). The
scripts installed can be controlled through two additional command line
options:

@geindex ensurepip command line option; --altinstall
@anchor{library/ensurepip cmdoption-ensurepip-altinstall}@anchor{4b8b}
@deffn {Option} @w{-}@w{-}altinstall

If an alternate installation is requested, the @code{pipX} script will `not' be
installed.
@end deffn

@geindex ensurepip command line option; --default-pip
@anchor{library/ensurepip cmdoption-ensurepip-default-pip}@anchor{4b8c}
@deffn {Option} @w{-}@w{-}default@w{-}pip

If a «default pip» installation is requested, the @code{pip} script will be
installed in addition to the two regular scripts.
@end deffn

Providing both of the script selection options will trigger an exception.

@node Module API,,Command-line interface<12>,ensurepip — Bootstrapping the pip installer
@anchor{library/ensurepip module-api}@anchor{4b8d}
@subsubsection Module API


@code{ensurepip} exposes two functions for programmatic use:

@geindex version() (στη μονάδα ensurepip)
@anchor{library/ensurepip ensurepip version}@anchor{4b8e}
@deffn {Συνάρτηση} ensurepip.version ()

Returns a string specifying the available version of pip that will be
installed when bootstrapping an environment.
@end deffn

@geindex bootstrap() (στη μονάδα ensurepip)
@anchor{library/ensurepip ensurepip bootstrap}@anchor{49b2}
@deffn {Συνάρτηση} ensurepip.bootstrap (root=None, upgrade=False, user=False, altinstall=False, default_pip=False, verbosity=0)

Bootstraps @code{pip} into the current or designated environment.

`root' specifies an alternative root directory to install relative to.
If `root' is @code{None}, then installation uses the default install location
for the current environment.

`upgrade' indicates whether or not to upgrade an existing installation
of an earlier version of @code{pip} to the available version.

`user' indicates whether to use the user scheme rather than installing
globally.

By default, the scripts @code{pipX} and @code{pipX.Y} will be installed (where
X.Y stands for the current version of Python).

If `altinstall' is set, then @code{pipX} will `not' be installed.

If `default_pip' is set, then @code{pip} will be installed in addition to
the two regular scripts.

Setting both `altinstall' and `default_pip' will trigger
@ref{277,,ValueError}.

`verbosity' controls the level of output to @ref{e9c,,sys.stdout} from the
bootstrapping operation.

Raises an @ref{1e65,,auditing event} @code{ensurepip.bootstrap} with argument @code{root}.

@cartouche
@quotation Σημείωση 
The bootstrapping process has side effects on both @code{sys.path} and
@code{os.environ}. Invoking the command line interface in a subprocess
instead allows these side effects to be avoided.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
The bootstrapping process may install additional modules required by
@code{pip}, but other software should not assume those dependencies will
always be present by default (as the dependencies may be removed in a
future version of @code{pip}).
@end quotation
@end cartouche
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node venv — Creation of virtual environments,zipapp — Διαχείριση εκτελέσιμων αρχείων zip Python,ensurepip — Bootstrapping the pip installer,Software Packaging and Distribution
@anchor{library/venv doc}@anchor{4b8f}@anchor{library/venv module-venv}@anchor{11a}@anchor{library/venv translation-repo}@anchor{4b90}@anchor{library/venv venv-creation-of-virtual-environments}@anchor{4b91}
@subsection @code{venv} — Creation of virtual environments


@geindex module; venv


Added in version 3.3.


`Source code:' Lib/venv/@footnote{https://github.com/python/cpython/tree/main/Lib/venv/}

@geindex Environments;virtual


__________________________________________________________________

@anchor{library/venv venv-def}@anchor{3a9}@anchor{library/venv venv-intro}@anchor{4b92}
The @code{venv} module supports creating lightweight «virtual environments»,
each with their own independent set of Python packages installed in
their @ref{cf,,site} directories.
A virtual environment is created on top of an existing
Python installation, known as the virtual environment’s «base» Python, and by
default is isolated from the packages in the base environment,
so that only those explicitly installed in the virtual environment are
available. See @ref{4b93,,Virtual Environments} and @code{site}’s
@ref{4b94,,virtual environments documentation}
for more information.

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 Δείτε επίσης


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{232d,,Διαθεσιμότητα}: not Android, not iOS, not WASI.

This module is not supported on @ref{244d,,mobile platforms}
or @ref{1d67,,WebAssembly platforms}.

@menu
* Creating virtual environments:: 
* How venvs work:: 
* API: API<2>. 
* An example of extending EnvBuilder:: 

@end menu

@node Creating virtual environments,How venvs work,,venv — Creation of virtual environments
@anchor{library/venv creating-virtual-environments}@anchor{4b95}
@subsubsection Creating virtual environments


@ref{3a9,,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{Lib\site-packages}).
If an existing directory is specified, it will be re-used.


Άλλαξε στην έκδοση 3.5: The use of @code{venv} is now recommended for creating virtual environments.



Καταργήθηκε από την έκδοση 3.6, αφαιρέθηκε στην έκδοση 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

The command, if run with @code{-h}, will show the available options:

@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.

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

@geindex venv command line option; ENV_DIR
@anchor{library/venv venv-cli}@anchor{4b96}@anchor{library/venv cmdoption-venv-arg-ENV_DIR}@anchor{4b97}
@deffn {Option} ENV_DIR

A required argument specifying the directory to create the environment in.
@end deffn

@geindex venv command line option; --system-site-packages
@anchor{library/venv cmdoption-venv-system-site-packages}@anchor{4b98}
@deffn {Option} @w{-}@w{-}system@w{-}site@w{-}packages

Give the virtual environment access to the system site-packages directory.
@end deffn

@geindex venv command line option; --symlinks
@anchor{library/venv cmdoption-venv-symlinks}@anchor{4b99}
@deffn {Option} @w{-}@w{-}symlinks

Try to use symlinks rather than copies, when symlinks are not the default for the platform.
@end deffn

@geindex venv command line option; --copies
@anchor{library/venv cmdoption-venv-copies}@anchor{4b9a}
@deffn {Option} @w{-}@w{-}copies

Try to use copies rather than symlinks, even when symlinks are the default for the platform.
@end deffn

@geindex venv command line option; --clear
@anchor{library/venv cmdoption-venv-clear}@anchor{4b9b}
@deffn {Option} @w{-}@w{-}clear

Delete the contents of the environment directory if it already exists, before environment creation.
@end deffn

@geindex venv command line option; --upgrade
@anchor{library/venv cmdoption-venv-upgrade}@anchor{4b9c}
@deffn {Option} @w{-}@w{-}upgrade

Upgrade the environment directory to use this version of Python, assuming Python has been upgraded in-place.
@end deffn

@geindex venv command line option; --without-pip
@anchor{library/venv cmdoption-venv-without-pip}@anchor{4b9d}
@deffn {Option} @w{-}@w{-}without@w{-}pip

Skips installing or upgrading pip in the virtual environment (pip is bootstrapped by default).
@end deffn

@geindex venv command line option; --prompt
@anchor{library/venv cmdoption-venv-prompt}@anchor{4b9e}
@deffn {Option} @w{-}@w{-}prompt <PROMPT>

Provides an alternative prompt prefix for this environment.
@end deffn

@geindex venv command line option; --upgrade-deps
@anchor{library/venv cmdoption-venv-upgrade-deps}@anchor{4b9f}
@deffn {Option} @w{-}@w{-}upgrade@w{-}deps

Upgrade core dependencies (pip) to the latest version in PyPI.
@end deffn

@geindex venv command line option; --without-scm-ignore-files
@anchor{library/venv cmdoption-venv-without-scm-ignore-files}@anchor{4ba0}
@deffn {Option} @w{-}@w{-}without@w{-}scm@w{-}ignore@w{-}files

Skips adding SCM ignore files to the environment directory (Git is supported by default).
@end deffn


Άλλαξε στην έκδοση 3.4: Installs pip by default, added the @code{--without-pip}  and @code{--copies}
options.



Άλλαξε στην έκδοση 3.4: In earlier versions, if the target directory already existed, an error was
raised, unless the @code{--clear} or @code{--upgrade} option was provided.



Άλλαξε στην έκδοση 3.9: Add @code{--upgrade-deps} option to upgrade pip + setuptools to the latest on PyPI.



Άλλαξε στην έκδοση 3.12: @code{setuptools} is no longer a core venv dependency.



Άλλαξε στην έκδοση 3.13: Added the @code{--without-scm-ignore-files} option.



Άλλαξε στην έκδοση 3.13: @code{venv} now creates a @code{.gitignore} file for Git by default.


@cartouche
@quotation Σημείωση 
While symlinks are supported on Windows, they are not recommended. Of
particular note is that double-clicking @code{python.exe} in File Explorer
will resolve the symlink eagerly and ignore the virtual environment.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
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.

Unless the @code{--without-pip} option is given, @ref{58,,ensurepip} will be
invoked to bootstrap @code{pip} into the virtual environment.

Multiple paths can be given to @code{venv}, in which case an identical virtual
environment will be created, according to the given options, at each provided
path.

@node How venvs work,API<2>,Creating virtual environments,venv — Creation of virtual environments
@anchor{library/venv how-venvs-work}@anchor{4ba1}@anchor{library/venv venv-explanation}@anchor{86a}
@subsubsection How venvs work


When a Python interpreter is running from a virtual environment,
@ref{3ab,,sys.prefix} and @ref{3a8,,sys.exec_prefix}
point to the directories of the virtual environment,
whereas @ref{3aa,,sys.base_prefix} and @ref{3a7,,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 μεταβλητή περιβάλλοντος; 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

Platform

@tab

Shell

@tab

Command to activate virtual environment

@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



Added in version 3.4: @code{fish} and @code{csh} activation scripts.



Added in version 3.8: PowerShell activation scripts installed under POSIX for PowerShell Core
support.


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 μεταβλητή περιβάλλοντος; PATH
@code{PATH}. On Windows, «shebang» line processing is supported if
you have the @ref{9bc,,Διαχειριστής εγκατάστασης Python} 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 μεταβλητή περιβάλλοντος; 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 Προειδοποίηση 
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>,An example of extending EnvBuilder,How venvs work,venv — Creation of virtual environments
@anchor{library/venv api}@anchor{4ba2}@anchor{library/venv venv-api}@anchor{12a3}
@subsubsection API


The high-level method described above makes use of a simple API which provides
mechanisms for third-party virtual environment creators to customize environment
creation according to their needs, the @ref{772,,EnvBuilder} class.

@geindex EnvBuilder (κλάση σε venv)
@anchor{library/venv venv EnvBuilder}@anchor{772}
@deffn {Κλάση} venv.EnvBuilder (system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None, upgrade_deps=False, *, scm_ignore_files=frozenset())

The @code{EnvBuilder} class accepts the following keyword arguments on
instantiation:


@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{58,,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{4ba3,,create_git_ignore_file()}.
@end itemize


Άλλαξε στην έκδοση 3.4: Added the @code{with_pip} parameter



Άλλαξε στην έκδοση 3.6: Added the @code{prompt} parameter



Άλλαξε στην έκδοση 3.9: Added the @code{upgrade_deps} parameter



Άλλαξε στην έκδοση 3.13: Added the @code{scm_ignore_files} parameter


@code{EnvBuilder} may be used as a base class.

@geindex create() (μέθοδος της venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder create}@anchor{4ba4}
@deffn {Μέθοδος} create (env_dir)

Create a virtual environment by specifying the target directory
(absolute or relative to the current directory) which is to contain the
virtual environment.  The @code{create} method will either create the
environment in the specified directory, or raise an appropriate
exception.

The @code{create} method of the @code{EnvBuilder} class illustrates the
hooks available for subclass customization:

@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

Each of the methods @ref{4ba5,,ensure_directories()},
@ref{4ba6,,create_configuration()}, @ref{4ba7,,setup_python()},
@ref{4ba8,,setup_scripts()} and @ref{4ba9,,post_setup()} can be overridden.
@end deffn

@geindex ensure_directories() (μέθοδος της venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder ensure_directories}@anchor{4ba5}
@deffn {Μέθοδος} 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 @code{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{6ea,,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{4baa,,install_scripts()}).

@item 
@code{env_name} - The name of the virtual environment. Used for
@code{__VENV_NAME__} in activation scripts (see @ref{4baa,,install_scripts()}).

@item 
@code{prompt} - The prompt to be used by the activation scripts. Used for
@code{__VENV_PROMPT__} in activation scripts (see @ref{4baa,,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{platlib_path} - The platlib 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{4baa,,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{4baa,,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


Άλλαξε στην έκδοση 3.11: The `venv'
@ref{65c,,sysconfig installation scheme}
is used to construct the paths of the created directories.



Άλλαξε στην έκδοση 3.12: The attribute @code{lib_path} was added to the context, and the context
object was documented.



Άλλαξε στην έκδοση 3.15: The attribute @code{platlib_path} was added to the context.

@end deffn

@geindex create_configuration() (μέθοδος της venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder create_configuration}@anchor{4ba6}
@deffn {Μέθοδος} create_configuration (context)

Creates the @code{pyvenv.cfg} configuration file in the environment.
@end deffn

@geindex setup_python() (μέθοδος της venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder setup_python}@anchor{4ba7}
@deffn {Μέθοδος} setup_python (context)

Creates a copy or symlink to the Python executable in the environment.
On POSIX systems, if a specific executable @code{python3.x} was used,
symlinks to @code{python} and @code{python3} will be created pointing to that
executable, unless files with those names already exist.
@end deffn

@geindex setup_scripts() (μέθοδος της venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder setup_scripts}@anchor{4ba8}
@deffn {Μέθοδος} setup_scripts (context)

Installs activation scripts appropriate to the platform into the virtual
environment.
@end deffn

@geindex upgrade_dependencies() (μέθοδος της venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder upgrade_dependencies}@anchor{4bab}
@deffn {Μέθοδος} 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.


Added in version 3.9.



Άλλαξε στην έκδοση 3.12: setuptools@footnote{https://pypi.org/project/setuptools/} is no longer a core venv dependency.

@end deffn

@geindex post_setup() (μέθοδος της venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder post_setup}@anchor{4ba9}
@deffn {Μέθοδος} post_setup (context)

A placeholder method which can be overridden in third party
implementations to pre-install packages in the virtual environment or
perform other post-creation steps.
@end deffn

@geindex install_scripts() (μέθοδος της venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder install_scripts}@anchor{4baa}
@deffn {Μέθοδος} install_scripts (context, path)

This method can be
called from @ref{4ba8,,setup_scripts()} or @ref{4ba9,,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{3228,,os.name} are copied after some text
replacement of placeholders:


@itemize *

@item 
@code{__VENV_DIR__} is replaced with the absolute path of the environment
directory.

@item 
@code{__VENV_NAME__} is replaced with the environment name (final path
segment of environment directory).

@item 
@code{__VENV_PROMPT__} is replaced with the prompt (the environment
name surrounded by parentheses and with a following space)

@item 
@code{__VENV_BIN_NAME__} is replaced with the name of the bin directory
(either @code{bin} or @code{Scripts}).

@item 
@code{__VENV_PYTHON__} is replaced with the absolute path of the
environment’s executable.
@end itemize

The directories are allowed to exist (for when an existing environment
is being upgraded).
@end deffn

@geindex create_git_ignore_file() (μέθοδος της venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder create_git_ignore_file}@anchor{4ba3}
@deffn {Μέθοδος} 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.


Added in version 3.13.

@end deffn


Άλλαξε στην έκδοση 3.7.2: Windows now uses redirector scripts for @code{python[w].exe} instead of
copying the actual binaries. In 3.7.2 only @ref{4ba7,,setup_python()} does
nothing unless running from a build in the source tree.



Άλλαξε στην έκδοση 3.7.3: Windows copies the redirector scripts as part of @ref{4ba7,,setup_python()}
instead of @ref{4ba8,,setup_scripts()}. This was not the case in 3.7.2.
When using symlinks, the original executables will be linked.

@end deffn

There is also a module-level convenience function:

@geindex create() (στη μονάδα venv)
@anchor{library/venv venv create}@anchor{773}
@deffn {Συνάρτηση} venv.create (env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False, prompt=None, upgrade_deps=False, *, scm_ignore_files=frozenset())

Create an @ref{772,,EnvBuilder} with the given keyword arguments, and call its
@ref{4ba4,,create()} method with the `env_dir' argument.


Added in version 3.3.



Άλλαξε στην έκδοση 3.4: Added the `with_pip' parameter



Άλλαξε στην έκδοση 3.6: Added the `prompt' parameter



Άλλαξε στην έκδοση 3.9: Added the `upgrade_deps' parameter



Άλλαξε στην έκδοση 3.13: Added the `scm_ignore_files' parameter

@end deffn

@node An example of extending EnvBuilder,,API<2>,venv — Creation of virtual environments
@anchor{library/venv an-example-of-extending-envbuilder}@anchor{4bac}
@subsubsection An example of extending @code{EnvBuilder}


The following script shows how to extend @ref{772,,EnvBuilder} by implementing a
subclass which installs setuptools and pip into a created virtual environment:

@example
import os
import os.path
from subprocess import Popen, PIPE
import sys
from threading import Thread
from urllib.parse import urlsplit
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, _, _ = urlsplit(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

This script is also available for download online@footnote{https://gist.github.com/vsajip/4673395}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node zipapp — Διαχείριση εκτελέσιμων αρχείων zip Python,,venv — Creation of virtual environments,Software Packaging and Distribution
@anchor{library/zipapp doc}@anchor{4bad}@anchor{library/zipapp module-zipapp}@anchor{139}@anchor{library/zipapp translation-repo}@anchor{4bae}@anchor{library/zipapp zipapp-manage-executable-python-zip-archives}@anchor{4baf}
@subsection @code{zipapp} — Διαχείριση εκτελέσιμων αρχείων zip Python


@geindex module; zipapp


Added in version 3.5.


`Πηγαίος κώδικας:' Lib/zipapp.py@footnote{https://github.com/python/cpython/tree/main/Lib/zipapp.py}

@geindex Εκτελέσιμα Αρχεία Zip


__________________________________________________________________


Το παρόν module παρέχει εργαλεία για τη διαχείριση της δημιουργίας αρχείων zip που περιέχουν κώδικα Python, τα οποία μπορούν να @ref{230a,,executed directly by the Python interpreter}. Το module παρέχει τόσο μια @ref{4bb0,,Διεπαφή Γραμμής Εντολών} όσο και ένα  @ref{4bb1,,Διεπαφή Python}.

@menu
* Βασικό Παράδειγμα:: 
* Διεπαφή Γραμμής Εντολών: Διεπαφή Γραμμής Εντολών<2>. 
* Διεπαφή Python:: 
* Παραδείγματα: Παραδείγματα<6>. 
* Καθορισμός του Διερμηνέα:: 
* Δημιουργία Αυτόνομων Εφαρμογών με το zipapp:: 
* Η Μορφή Αρχείου Εφαρμογής Zip της Python:: 

@end menu

@node Βασικό Παράδειγμα,Διεπαφή Γραμμής Εντολών<2>,,zipapp — Διαχείριση εκτελέσιμων αρχείων zip Python
@anchor{library/zipapp basic-example}@anchor{4bb2}
@subsubsection Βασικό Παράδειγμα


Το παρακάτω παράδειγμα δείχνει πώς μπορεί να χρησιμοποιηθεί η @ref{4bb0,,Διεπαφή Γραμμής Εντολών} για να δημιουργήσει ένα εκτελέσιμο αρχείο από έναν φάκελο που περιέχει κώδικα Python. Όταν εκτελείται, το αρχείο θα εκτελέσει τη συνάρτηση @code{main} από το module @code{myapp} στο αρχείο.

@example
$ python -m zipapp myapp -m "myapp:main"
$ python myapp.pyz
<output from myapp>
@end example

@node Διεπαφή Γραμμής Εντολών<2>,Διεπαφή Python,Βασικό Παράδειγμα,zipapp — Διαχείριση εκτελέσιμων αρχείων zip Python
@anchor{library/zipapp command-line-interface}@anchor{4bb3}@anchor{library/zipapp zipapp-command-line-interface}@anchor{4bb0}
@subsubsection Διεπαφή Γραμμής Εντολών


Όταν καλείται ως πρόγραμμα από τη γραμμή εντολών, χρησιμοποιείται η παρακάτω μορφή:

@example
$ python -m zipapp source [options]
@end example

Αν το `source' είναι ένας φάκελος, αυτό θα δημιουργήσει ένα αρχείο από τα περιεχόμενα του `source'. Αν το `source' είναι ένα αρχείο, θα πρέπει να είναι ένα αρχείο, και θα αντιγραφεί στο αρχείο προορισμού (ή το περιεχόμενο της γραμμής shebang θα εμφανιστεί αν έχει καθοριστεί η επιλογή –info).

Οι παρακάτω επιλογές γίνονται κατανοητές:

@geindex zipapp command line option; -o
@geindex zipapp command line option; --output
@anchor{library/zipapp cmdoption-zipapp-o}@anchor{4bb4}@anchor{library/zipapp cmdoption-zipapp-output}@anchor{4bb5}
@deffn {Option} @w{-}o <output>, @w{-}@w{-}output=<output>

Γράφει την έξοδο σε ένα αρχείο με όνομα `output'. Αν αυτή η επιλογή δεν καθοριστεί, το όνομα του αρχείου εξόδου θα είναι το ίδιο με το εισαγωγικό `source', με την προσθήκη της επέκτασης @code{.pyz}. Αν καθοριστεί ένα ρητό όνομα αρχείου, χρησιμοποιείται όπως είναι (έτσι θα πρέπει να συμπεριληφθεί μια επέκταση @code{.pyz} αν απαιτείται).

Ένα όνομα αρχείου εξόδου πρέπει να καθοριστεί αν το `source' είναι ένα αρχείο (και σε αυτή την περίπτωση, το `output' δεν πρέπει να είναι το ίδιο με το `source').
@end deffn

@geindex zipapp command line option; -p
@geindex zipapp command line option; --python
@anchor{library/zipapp cmdoption-zipapp-p}@anchor{4bb6}@anchor{library/zipapp cmdoption-zipapp-python}@anchor{4bb7}
@deffn {Option} @w{-}p <interpreter>, @w{-}@w{-}python=<interpreter>

Προσθέτει μια γραμμή @code{#!} στο αρχείο που καθορίζει το `interpreter' ως την εντολή που θα εκτελεστεί. Επίσης, σε POSIX, καθιστά το αρχείο εκτελέσιμο. Η προεπιλογή είναι να μην γράφεται καμία γραμμή @code{#!} και να μην καθίσταται το αρχείο εκτελέσιμο.
@end deffn

@geindex zipapp command line option; -m
@geindex zipapp command line option; --main
@anchor{library/zipapp cmdoption-zipapp-m}@anchor{4bb8}@anchor{library/zipapp cmdoption-zipapp-main}@anchor{4bb9}
@deffn {Option} @w{-}m <mainfn>, @w{-}@w{-}main=<mainfn>

Γράφει ένα αρχείο @code{__main__.py} στο αρχείο που εκτελεί το `mainfn'. Το `mainfn' πρέπει να έχει τη μορφή «pkg.mod:fn», όπου «pkg.mod» είναι ένα πακέτο/module στο αρχείο, και «fn» είναι μια καλούμενη συνάρτηση στο δεδομένο module. Το αρχείο @code{__main__.py} θα εκτελέσει αυτή τη συνάρτηση.

Η επιλογή @ref{4bb8,,--main} δεν μπορεί να καθοριστεί κατά την αντιγραφή ενός αρχείου.
@end deffn

@geindex zipapp command line option; -c
@geindex zipapp command line option; --compress
@anchor{library/zipapp cmdoption-zipapp-c}@anchor{4bba}@anchor{library/zipapp cmdoption-zipapp-compress}@anchor{4bbb}
@deffn {Option} @w{-}c, @w{-}@w{-}compress

Συμπιέζει τα αρχεία με τη μέθοδο deflate, μειώνοντας το μέγεθος του αρχείου εξόδου. Από προεπιλογή, τα αρχεία αποθηκεύονται χωρίς συμπίεση στο αρχείο.

Η επιλογή @ref{4bba,,--compress} δεν έχει καμία επίδραση κατά την αντιγραφή ενός αρχείου.


Added in version 3.7.

@end deffn

@geindex zipapp command line option; --info
@anchor{library/zipapp cmdoption-zipapp-info}@anchor{4bbc}
@deffn {Option} @w{-}@w{-}info

Εμφανίζει τον ενσωματωμένο διερμηνέα στο αρχείο, για διαγνωστικούς σκοπούς. Σε αυτή την περίπτωση, αγνοούνται όλες οι άλλες επιλογές και το SOURCE πρέπει να είναι ένα αρχείο, όχι ένας φάκελος.
@end deffn

@geindex zipapp command line option; -h
@geindex zipapp command line option; --help
@anchor{library/zipapp cmdoption-zipapp-h}@anchor{4bbd}@anchor{library/zipapp cmdoption-zipapp-help}@anchor{4bbe}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Εκτυπώνει ένα σύντομο μήνυμα χρήσης και εξέρχεται.
@end deffn

@node Διεπαφή Python,Παραδείγματα<6>,Διεπαφή Γραμμής Εντολών<2>,zipapp — Διαχείριση εκτελέσιμων αρχείων zip Python
@anchor{library/zipapp python-api}@anchor{4bbf}@anchor{library/zipapp zipapp-python-api}@anchor{4bb1}
@subsubsection Διεπαφή Python


Το module ορίζει δύο συναρτήσεις ευκολίας:

@geindex create_archive() (στη μονάδα zipapp)
@anchor{library/zipapp zipapp create_archive}@anchor{f6e}
@deffn {Συνάρτηση} zipapp.create_archive (source, target=None, interpreter=None, main=None, filter=None, compressed=False)

Δημιουργεί ένα αρχείο εφαρμογής από το `source'. Η πηγή μπορεί να είναι οποιοδήποτε από τα παρακάτω:


@itemize *

@item 
Το όνομα ενός φακέλου, ή ένα @ref{79f,,path-like object} που αναφέρεται σε έναν φάκελο, οπότε θα δημιουργηθεί ένα νέο αρχείο εφαρμογής από το περιεχόμενο αυτού του φακέλου.

@item 
Το όνομα ενός υπάρχοντος αρχείου εφαρμογής, ή ένα @ref{79f,,path-like object} που αναφέρεται σε ένα τέτοιο αρχείο, οπότε το αρχείο αντιγράφεται στο προορισμό (τροποποιώντας το για να αντικατοπτρίζει την τιμή που δίνεται για το όρισμα `interpreter'). Το όνομα του αρχείου θα πρέπει να περιλαμβάνει την επέκταση @code{.pyz}, αν απαιτείται.

@item 
Ένα αντικείμενο αρχείου ανοιχτό για ανάγνωση σε λειτουργία bytes. Το περιεχόμενο του αρχείου θα πρέπει να είναι ένα αρχείο εφαρμογής, και το αντικείμενο αρχείου θεωρείται ότι είναι τοποθετημένο στην αρχή του αρχείου.
@end itemize

Το όρισμα `target' καθορίζει που θα γραφτεί το αποτέλεσμα του αρχείου:


@itemize *

@item 
Αν είναι το όνομα ενός αρχείου, ή ένα @ref{79f,,path-like object}, το αρχείο θα γραφτεί σε αυτό το αρχείο.

@item 
Αν είναι ένα ανοιχτό αντικείμενο αρχείου, το αρχείο θα γραφτεί σε αυτό το αντικείμενο αρχείου, το οποίο πρέπει να είναι ανοιχτό για εγγραφή σε λειτουργία bytes.

@item 
Αν το όρισμα προορισμού παραλειφθεί (ή είναι @code{None}), η πηγή πρέπει να είναι ένας φάκελος και ο προορισμός θα είναι ένα αρχείο με το ίδιο όνομα με την πηγή, με μια επέκταση @code{.pyz} προστιθέμενη.
@end itemize

Το όρισμα `interpreter' καθορίζει το όνομα του διερμηνέα Python με τον οποίο θα εκτελείται το αρχείο. Γράφεται ως μια γραμμή «shebang» στην αρχή του αρχείου. Σε POSIX, αυτό θα ερμηνευτεί από το λειτουργικό σύστημα, και σε Windows θα διαχειριστεί από τον διερμηνέα Python. Η παράλειψη του `interpreter' έχει ως αποτέλεσμα να μην γραφτεί καμία γραμμή shebang. Αν καθοριστεί ένας διερμηνέας, και ο προορισμός είναι ένα όνομα αρχείου, θα τεθεί το εκτελέσιμο bit του αρχείου προορισμού.

Το όρισμα `main' καθορίζει το όνομα μιας καλούμενης συνάρτησης που θα χρησιμοποιηθεί ως το κύριο πρόγραμμα για το αρχείο. Μπορεί να καθοριστεί μόνο αν η πηγή είναι ένας φάκελος, και η πηγή δεν περιέχει ήδη ένα αρχείο @code{__main__.py}. Το όρισμα `main' θα πρέπει να έχει τη μορφή «pkg.module:callable» και το αρχείο θα εκτελείται με την εισαγωγή «pkg.module» και την εκτέλεση της δεδομένης καλούμενης συνάρτησης χωρίς ορίσματα. Είναι σφάλμα να παραλειφθεί το `main' αν η πηγή είναι ένας φάκελος και δεν περιέχει ένα αρχείο @code{__main__.py}, καθώς διαφορετικά το παραγόμενο αρχείο δεν θα ήταν εκτελέσιμο.

Το προαιρετικό όρισμα `filter' καθορίζει μια συνάρτηση callback που περνάει ένα αντικείμενο Path που αναπαριστά το μονοπάτι του αρχείου που προστίθεται (σχετικό με τον φάκελο πηγής). Θα πρέπει να επιστρέφει @code{True} αν το αρχείο πρέπει να προστεθεί.

Το προαιρετικό όρισμα `compressed' καθορίζει αν τα αρχεία συμπιέζονται. Αν οριστεί σε @code{True}, τα αρχεία στο αρχείο συμπιέζονται με τη μέθοδο deflate. Διαφορετικά, τα αρχεία αποθηκεύονται χωρίς συμπίεση. Αυτό το όρισμα δεν έχει καμία επίδραση κατά την αντιγραφή ενός υπάρχοντος αρχείου.

Αν ένα αντικείμενο αρχείου καθοριστεί για το `source' ή το `target', είναι ευθύνη του καλούντος να το κλείσει μετά την κλήση της create_archive.

Κατά την αντιγραφή ενός υπάρχοντος αρχείου, τα αντικείμενα αρχείων που παρέχονται χρειάζονται μόνο τις μεθόδους @code{read} και @code{readline}, ή @code{write}. Όταν δημιουργείται ένα αρχείο από έναν φάκελο, αν το target είναι ένα αντικείμενο αρχείου, θα περαστεί στην κλάση @code{zipfile.ZipFile} και πρέπει να παρέχει τις μεθόδους που χρειάζεται αυτή η κλάση.


Άλλαξε στην έκδοση 3.7: Προστέθηκαν οι παράμετροι `filter' και `compressed'.

@end deffn

@geindex get_interpreter() (στη μονάδα zipapp)
@anchor{library/zipapp zipapp get_interpreter}@anchor{4bc0}
@deffn {Συνάρτηση} zipapp.get_interpreter (archive)

Επιστρέφει τον διερμηνέα που καθορίζεται στη γραμμή @code{#!} στην αρχή του αρχείου. Αν δεν υπάρχει γραμμή @code{#!}, επιστρέφει @ref{a65,,None}. Το `archive' μπορεί να είναι ένα όνομα αρχείου ή ένα αντικείμενο που μοιάζει με αρχείο και είναι ανοιχτό για ανάγνωση σε bytes.
@end deffn

@node Παραδείγματα<6>,Καθορισμός του Διερμηνέα,Διεπαφή Python,zipapp — Διαχείριση εκτελέσιμων αρχείων zip Python
@anchor{library/zipapp examples}@anchor{4bc1}@anchor{library/zipapp zipapp-examples}@anchor{4bc2}
@subsubsection Παραδείγματα


Συσκευάζει έναν φάκελο σε ένα αρχείο, και το εκτελεί.

@example
$ python -m zipapp myapp
$ python myapp.pyz
<output from myapp>
@end example

Το ίδιο μπορεί να γίνει χρησιμοποιώντας τη συνάρτηση @ref{f6e,,create_archive()}:

@example
>>> import zipapp
>>> zipapp.create_archive('myapp', 'myapp.pyz')
@end example

Για να κάνετε την εφαρμογή άμεσα εκτελέσιμη σε POSIX, καθορίστε έναν διερμηνέα που θα χρησιμοποιηθεί.

@example
$ python -m zipapp myapp -p "/usr/bin/env python"
$ ./myapp.pyz
<output from myapp>
@end example

Για να αντικαταστήσετε τη γραμμή shebang σε ένα υπάρχον αρχείο, δημιουργήστε ένα τροποποιημένο αρχείο χρησιμοποιώντας τη συνάρτηση @ref{f6e,,create_archive()}:

@example
>>> import zipapp
>>> zipapp.create_archive('old_archive.pyz', 'new_archive.pyz', '/usr/bin/python3')
@end example

Για να ενημερώσετε το αρχείο στη θέση του, κάντε την αντικατάσταση στη μνήμη χρησιμοποιώντας ένα αντικείμενο @ref{1255,,BytesIO}, και στη συνέχεια αντικαταστήστε την πηγή. Σημειώστε ότι υπάρχει κίνδυνος κατά την αντικατάσταση ενός αρχείου στη θέση του ότι ένα σφάλμα θα οδηγήσει στην απώλεια του αρχικού αρχείου. Αυτός ο κώδικας δεν προστατεύει από τέτοια σφάλματα, αλλά ο κώδικας παραγωγής θα πρέπει να το κάνει. Επίσης, αυτή η μέθοδος θα λειτουργήσει μόνο αν το αρχείο χωράει στη μνήμη:

@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 Καθορισμός του Διερμηνέα,Δημιουργία Αυτόνομων Εφαρμογών με το zipapp,Παραδείγματα<6>,zipapp — Διαχείριση εκτελέσιμων αρχείων zip Python
@anchor{library/zipapp specifying-the-interpreter}@anchor{4bc3}@anchor{library/zipapp zipapp-specifying-the-interpreter}@anchor{4bc4}
@subsubsection Καθορισμός του Διερμηνέα


Σημειώστε ότι αν καθορίσετε έναν διερμηνέα και στη συνέχεια διανείμετε το αρχείο εφαρμογής σας, πρέπει να διασφαλίσετε ότι ο διερμηνέας που χρησιμοποιείται είναι φορητός. Ο διερμηνέας Python για Windows υποστηρίζει τις περισσότερες κοινές μορφές γραμμής @code{#!} POSIX, αλλά υπάρχουν και άλλα ζητήματα που πρέπει να ληφθούν υπόψη:


@itemize *

@item 
Αν χρησιμοποιήσετε «/usr/bin/env python» (ή άλλες μορφές της εντολής «python», όπως «/usr/bin/python»), πρέπει να λάβετε υπόψη ότι οι χρήστες σας μπορεί να έχουν είτε Python 2 είτε Python 3 ως προεπιλογή, και να γράψετε τον κώδικά σας ώστε να λειτουργεί και στις δύο εκδόσεις.

@item 
Αν χρησιμοποιήσετε μια ρητή έκδοση, για παράδειγμα «/usr/bin/env python3», η εφαρμογή σας δεν θα λειτουργήσει για χρήστες που δεν έχουν αυτή την έκδοση. (Αυτό μπορεί να είναι αυτό που θέλετε αν δεν έχετε κάνει τον κώδικά σας συμβατό με την Python 2).

@item 
Δεν υπάρχει τρόπος να πείτε «python X.Y ή νεότερη», οπότε να είστε προσεκτικοί όταν χρησιμοποιείτε μια ακριβή έκδοση όπως «/usr/bin/env python3.4», καθώς θα χρειαστεί να αλλάξετε τη γραμμή shebang για χρήστες της Python 3.5, για παράδειγμα.
@end itemize

Συνήθως, θα πρέπει να χρησιμοποιήσετε ένα «/usr/bin/env python2» ή «/usr/bin/env python3», ανάλογα με το αν ο κώδικάς σας είναι γραμμένος για την Python 2 ή 3.

@node Δημιουργία Αυτόνομων Εφαρμογών με το zipapp,Η Μορφή Αρχείου Εφαρμογής Zip της Python,Καθορισμός του Διερμηνέα,zipapp — Διαχείριση εκτελέσιμων αρχείων zip Python
@anchor{library/zipapp creating-standalone-applications-with-zipapp}@anchor{4bc5}
@subsubsection Δημιουργία Αυτόνομων Εφαρμογών με το zipapp


Using the @code{zipapp} module, it is possible to create self-contained Python
programs, which can be distributed to end users who only need to have a
suitable version of Python installed on their system.  The key to doing this
is to bundle all of the application’s dependencies into the archive, along
with the application code.

Τα βήματα για τη δημιουργία ενός αυτόνομου αρχείου είναι τα εξής:


@enumerate 

@item 
Δημιουργήστε την εφαρμογή σας σε έναν φάκελο όπως συνήθως, έτσι ώστε να έχετε έναν φάκελο @code{myapp} που περιέχει ένα αρχείο @code{__main__.py} και οποιονδήποτε υποστηρικτικό κώδικα εφαρμογής.

@item 
Εγκαταστήστε όλες τις εξαρτήσεις της εφαρμογής σας στον φάκελο @code{myapp}, χρησιμοποιώντας το pip:

@example
$ python -m pip install -r requirements.txt --target myapp
@end example

(αυτό υποθέτει ότι έχετε τις απαιτήσεις του έργου σας σε ένα αρχείο @code{requirements.txt} - αν όχι, μπορείτε απλώς να καταγράψετε τις εξαρτήσεις χειροκίνητα στη γραμμή εντολών του pip).

@item 
Συσκευάστε την εφαρμογή χρησιμοποιώντας:

@example
$ python -m zipapp -p "interpreter" myapp
@end example
@end enumerate

Αυτό θα παράγει ένα αυτόνομο εκτελέσιμο, το οποίο μπορεί να εκτελεστεί σε οποιαδήποτε μηχανή με τον κατάλληλο διερμηνέα διαθέσιμο. Δείτε @ref{4bc4,,Καθορισμός του Διερμηνέα} για λεπτομέρειες. Μπορεί να αποσταλεί στους χρήστες ως ένα μόνο αρχείο.

Σε Unix, το αρχείο @code{myapp.pyz} είναι εκτελέσιμο όπως είναι. Μπορείτε να μετονομάσετε το αρχείο για να αφαιρέσετε την επέκταση @code{.pyz} αν προτιμάτε ένα «καθαρό» όνομα εντολής. Σε Windows, το αρχείο @code{myapp.pyz[w]} είναι εκτελέσιμο λόγω του γεγονότος ότι ο διερμηνέας Python καταχωρεί τις επεκτάσεις αρχείων @code{.pyz} και @code{.pyzw} κατά την εγκατάσταση.

@menu
* Προειδοποιήσεις:: 

@end menu

@node Προειδοποιήσεις,,,Δημιουργία Αυτόνομων Εφαρμογών με το zipapp
@anchor{library/zipapp caveats}@anchor{4bc6}
@subsubsection Προειδοποιήσεις


Αν η εφαρμογή σας εξαρτάται από ένα πακέτο που περιλαμβάνει μια επέκταση C, αυτό το πακέτο δεν μπορεί να εκτελεστεί από ένα αρχείο zip (αυτό είναι περιορισμός του λειτουργικού συστήματος, καθώς ο εκτελέσιμος κώδικας πρέπει να είναι παρών στο σύστημα αρχείων για να τον φορτώσει ο φορτωτής του λειτουργικού συστήματος). Σε αυτή την περίπτωση, μπορείτε να εξαιρέσετε αυτή την εξάρτηση από το αρχείο zip, και είτε να απαιτήσετε από τους χρήστες σας να το έχουν εγκατεστημένο, είτε να το αποστείλετε μαζί με το αρχείο zip και να προσθέσετε κώδικα στο @code{__main__.py} για να συμπεριλάβετε τον φάκελο που περιέχει το αποσυμπιεσμένο module στο @code{sys.path}. Σε αυτή την περίπτωση, θα πρέπει να διασφαλίσετε ότι θα αποστείλετε κατάλληλα δυαδικά αρχεία για την αρχιτεκτονική/αρχιτεκτονικές (και ενδεχομένως να επιλέξετε την κατάλληλη έκδοση για να προσθέσετε στο @code{sys.path} κατά τη διάρκεια εκτέλεσης, με βάση τη μηχανή του χρήστη).

@node Η Μορφή Αρχείου Εφαρμογής Zip της Python,,Δημιουργία Αυτόνομων Εφαρμογών με το zipapp,zipapp — Διαχείριση εκτελέσιμων αρχείων zip Python
@anchor{library/zipapp the-python-zip-application-archive-format}@anchor{4bc7}
@subsubsection Η Μορφή Αρχείου Εφαρμογής Zip της Python


Η Python μπορεί να εκτελεί αρχεία zip που περιέχουν ένα αρχείο @code{__main__.py} από την έκδοση 2.6. Για να εκτελεστεί από την Python, ένα αρχείο εφαρμογής απλά πρέπει να είναι ένα τυπικό αρχείο zip που περιέχει ένα αρχείο @code{__main__.py} το οποίο θα εκτελείται ως το σημείο εισόδου για την εφαρμογή. Όπως συνήθως για οποιοδήποτε Python script, ο γονέας του script (σε αυτή την περίπτωση το αρχείο zip) θα τοποθετηθεί στο @ref{194,,sys.path} και έτσι περαιτέρω modules μπορούν να εισαχθούν από το αρχείο zip.

Η μορφή αρχείου zip επιτρέπει την προσθήκη αυθαίρετων δεδομένων στην αρχή ενός αρχείου zip. Η μορφή αρχείου εφαρμογής zip χρησιμοποιεί αυτή την ικανότητα για να προσθέσει μια τυπική γραμμή «shebang» POSIX στην αρχή του αρχείου (@code{#!/path/to/interpreter}).

Επίσημα, η μορφή αρχείου εφαρμογής zip της Python είναι επομένως:


@enumerate 

@item 
Μια προαιρετική γραμμή shebang, που περιέχει τους χαρακτήρες @code{b'#!'} ακολουθούμενους από ένα όνομα διερμηνέα, και στη συνέχεια έναν χαρακτήρα newline (@code{b'\n'}). Το όνομα του διερμηνέα μπορεί να είναι οτιδήποτε αποδεκτό από την επεξεργασία «shebang» του λειτουργικού συστήματος, ή τον διερμηνέα Python σε Windows. Ο διερμηνέας θα πρέπει να κωδικοποιείται σε UTF-8 σε Windows, και σε @ref{1017,,sys.getfilesystemencoding()} σε POSIX.

@item 
Τυπικά δεδομένα αρχείου zip, όπως παράγονται από το module @ref{13a,,zipfile}. Το περιεχόμενο του αρχείου zip `πρέπει' να περιλαμβάνει ένα αρχείο @code{__main__.py} (το οποίο πρέπει να βρίσκεται στο «root» του αρχείου zip - δηλαδή, δεν μπορεί να βρίσκεται σε υποφάκελο). Τα δεδομένα του αρχείου zip μπορεί να είναι συμπιεσμένα ή μη συμπιεσμένα.
@end enumerate

Αν ένα αρχείο εφαρμογής έχει μια γραμμή shebang, μπορεί να έχει ρυθμιστεί το εκτελέσιμο bit σε συστήματα POSIX, για να επιτρέπεται η άμεση εκτέλεσή του.

Δεν υπάρχει απαίτηση να χρησιμοποιούνται τα εργαλεία σε αυτό το module για τη δημιουργία αρχείων εφαρμογής - το module είναι μια ευκολία, αλλά τα αρχεία σε παραπάνω μορφή που δημιουργούνται με οποιονδήποτε τρόπο είναι αποδεκτά από την Python.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python Runtime Services,Custom Python Interpreters,Software Packaging and Distribution,The Python Standard Library
@anchor{library/python doc}@anchor{4bc8}@anchor{library/python python}@anchor{4bc9}@anchor{library/python python-runtime-services}@anchor{4bca}@anchor{library/python translation-repo}@anchor{4bcb}
@section Python Runtime Services


The modules described in this chapter provide a wide range of services related
to the Python interpreter and its interaction with its environment.  Here’s an
overview:

@menu
* sys — System-specific parameters and functions:: 
* sys.monitoring — Execution event monitoring: sys monitoring — Execution event monitoring. 
* sysconfig — Provide access to Python’s configuration information:: 
* builtins — Built-in objects:: 
* __main__ — Top-level code environment:: 
* warnings — Έλεγχος προειδοποιήσεων:: 
* dataclasses — Data Classes:: 
* contextlib — Utilities for with-statement contexts:: 
* abc — Abstract Base Classes:: 
* atexit — Exit handlers:: 
* traceback — Print or retrieve a stack traceback:: 
* __future__ — Future statement definitions:: 
* gc — Garbage Collector interface:: 
* inspect — Inspect live objects:: 
* annotationlib — Functionality for introspecting annotations:: 
* site — Site-specific configuration hook:: 

@end menu

@node sys — System-specific parameters and functions,sys monitoring — Execution event monitoring,,Python Runtime Services
@anchor{library/sys doc}@anchor{4bcc}@anchor{library/sys module-sys}@anchor{e2}@anchor{library/sys sys-system-specific-parameters-and-functions}@anchor{4bcd}
@subsection @code{sys} — System-specific parameters and functions


@geindex module; sys


__________________________________________________________________


This module provides access to some variables used or maintained by the
interpreter and to functions that interact strongly with the interpreter. It is
always available. Unless explicitly noted otherwise, all variables are read-only.

@geindex abi_info (στη μονάδα sys)
@anchor{library/sys sys abi_info}@anchor{26e}
@deffn {Δεδομένα} sys.abi_info


Added in version 3.15.


An object containing information about the ABI of the currently running
Python interpreter.
It should include information that affect the CPython ABI in ways that
require a specific build of the interpreter chosen from variants that can
co-exist on a single machine.
For example, it does not encode the base OS (Linux or Windows), but does
include pointer size since some systems support both 32- and 64-bit builds.
The available entries are the same on all platforms;
e.g. `pointer_size' is available even on 64-bit-only architectures.

The following attributes are available:

@geindex pointer_bits (ιδιότητα της sys.abi_info)
@anchor{library/sys sys abi_info pointer_bits}@anchor{4bce}
@deffn {Ιδιότητα} abi_info.pointer_bits

The width of pointers in bits, as an integer,
equivalent to @code{8 * sizeof(void *)}.
Usually, this is  @code{32} or @code{64}.
@end deffn

@geindex free_threaded (ιδιότητα της sys.abi_info)
@anchor{library/sys sys abi_info free_threaded}@anchor{4bcf}
@deffn {Ιδιότητα} abi_info.free_threaded

A Boolean indicating whether the interpreter was built with
@ref{487,,free threading} support.
This reflects either the presence of the @ref{6a5,,--disable-gil}
@code{configure} option (on Unix)
or setting the @code{DisableGil} property (on Windows).
@end deffn

@geindex debug (ιδιότητα της sys.abi_info)
@anchor{library/sys sys abi_info debug}@anchor{4bd0}
@deffn {Ιδιότητα} abi_info.debug

A Boolean indicating whether the interpreter was built in
@ref{3dc,,debug mode}.
This reflects either the presence of the @ref{853,,--with-pydebug}
@code{configure} option (on Unix)
or the @code{Debug} configuration (on Windows).
@end deffn

@geindex byteorder (ιδιότητα της sys.abi_info)
@anchor{library/sys sys abi_info byteorder}@anchor{4bd1}
@deffn {Ιδιότητα} abi_info.byteorder

A string indicating the native byte order,
either @code{'big'} or @code{'little'}.
This is the same as the @ref{27f1,,byteorder} attribute.
@end deffn
@end deffn

@geindex abiflags (στη μονάδα sys)
@anchor{library/sys sys abiflags}@anchor{e28}
@deffn {Δεδομένα} sys.abiflags

On POSIX systems where Python was built with the standard @code{configure}
script, this contains the ABI flags as specified by 
@geindex Python Enhancement Proposals; PEP 3149
PEP 3149@footnote{https://peps.python.org/pep-3149/}.


Added in version 3.2.



Άλλαξε στην έκδοση 3.8: Default flags became an empty string (@code{m} flag for pymalloc has been
removed).


@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex addaudithook() (στη μονάδα sys)
@anchor{library/sys sys addaudithook}@anchor{49a7}
@deffn {Συνάρτηση} sys.addaudithook (hook)

Append the callable `hook' to the list of active auditing hooks for the
current (sub)interpreter.

When an auditing event is raised through the @ref{1b36,,sys.audit()} function, each
hook will be called in the order it was added with the event name and the
tuple of arguments. Native hooks added by @ref{49a8,,PySys_AddAuditHook()} are
called first, followed by hooks added in the current (sub)interpreter.  Hooks
can then log the event, raise an exception to abort the operation,
or terminate the process entirely.

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{49a8,,PySys_AddAuditHook()} before initialising the runtime, and any
modules allowing arbitrary memory modification (such as @ref{2d,,ctypes}) should
be completely removed or closely monitored.


Calling @ref{49a7,,sys.addaudithook()} will itself raise an auditing event
named @code{sys.addaudithook} with no arguments. If any
existing hooks raise an exception derived from @ref{30d,,RuntimeError}, the
new hook will not be added and the exception suppressed. As a result,
callers cannot assume that their hook has been added unless they control
all existing hooks.


See the @ref{1e0a,,audit events table} for all events raised by
CPython, and 
@geindex Python Enhancement Proposals; PEP 578
PEP 578@footnote{https://peps.python.org/pep-0578/} for the original design discussion.


Added in version 3.8.



Άλλαξε στην έκδοση 3.8.1: Exceptions derived from @ref{d9e,,Exception} but not @ref{30d,,RuntimeError}
are no longer suppressed.


`Λεπτομέρεια υλοποίησης CPython:' When tracing is enabled (see @ref{55c,,settrace()}), Python hooks are only
traced if the callable has a @code{__cantrace__} member that is set to a
true value. Otherwise, trace functions will skip the hook.
@end deffn

@geindex argv (στη μονάδα sys)
@anchor{library/sys sys argv}@anchor{1609}
@deffn {Δεδομένα} sys.argv

The list of command line arguments passed to a Python script. @code{argv[0]} is the
script name (it is operating system dependent whether this is a full pathname or
not).  If the command was executed using the @ref{445,,-c} command line option to
the interpreter, @code{argv[0]} is set to the string @code{'-c'}.  If no script name
was passed to the Python interpreter, @code{argv[0]} is the empty string.

To loop over the standard input, or the list of files given on the
command line, see the @ref{5e,,fileinput} module.

See also @ref{c19,,sys.orig_argv}.

@cartouche
@quotation Σημείωση 
On Unix, command line arguments are passed by bytes from OS.  Python decodes
them with filesystem encoding and «surrogateescape» error handler.
When you need original bytes, you can get it by
@code{[os.fsencode(arg) for arg in sys.argv]}.
@end quotation
@end cartouche
@end deffn

@geindex audit() (στη μονάδα sys)
@anchor{library/sys auditing}@anchor{1e65}@anchor{library/sys sys audit}@anchor{1b36}
@deffn {Συνάρτηση} sys.audit (event, *args)

@geindex auditing

Raise an auditing event and trigger any active auditing hooks.
`event' is a string identifying the event, and `args' may contain
optional arguments with more information about the event.  The
number and types of arguments for a given event are considered a
public and stable API and should not be modified between releases.

For example, one auditing event is named @code{os.chdir}. This event has
one argument called `path' that will contain the requested new
working directory.

@ref{1b36,,sys.audit()} will call the existing auditing hooks, passing
the event name and arguments, and will re-raise the first exception
from any hook. In general, if an exception is raised, it should not
be handled and the process should be terminated as quickly as
possible. This allows hook implementations to decide how to respond
to particular events: they can merely log the event or abort the
operation by raising an exception.

Hooks are added using the @ref{49a7,,sys.addaudithook()} or
@ref{49a8,,PySys_AddAuditHook()} functions.

The native equivalent of this function is @ref{808,,PySys_Audit()}. Using the
native function is preferred when possible.

See the @ref{1e0a,,audit events table} for all events raised by
CPython.


Added in version 3.8.

@end deffn

@geindex base_exec_prefix (στη μονάδα sys)
@anchor{library/sys sys base_exec_prefix}@anchor{3a7}
@deffn {Δεδομένα} sys.base_exec_prefix

Equivalent to @ref{3a8,,exec_prefix}, but referring to the base Python installation.

When running under @ref{4b93,,Virtual Environments},
@ref{3a8,,exec_prefix} gets overwritten to the virtual environment prefix.
@code{base_exec_prefix}, conversely, does not change, and always points to
the base Python installation.
Refer to @ref{4b93,,Virtual Environments} for more information.


Added in version 3.3.

@end deffn

@geindex base_prefix (στη μονάδα sys)
@anchor{library/sys sys base_prefix}@anchor{3aa}
@deffn {Δεδομένα} sys.base_prefix

Equivalent to @ref{3ab,,prefix}, but referring to the base Python installation.

When running under @ref{3a9,,virtual environment},
@ref{3ab,,prefix} gets overwritten to the virtual environment prefix.
@code{base_prefix}, conversely, does not change, and always points to
the base Python installation.
Refer to @ref{4b93,,Virtual Environments} for more information.


Added in version 3.3.

@end deffn

@geindex byteorder (στη μονάδα sys)
@anchor{library/sys sys byteorder}@anchor{27f1}
@deffn {Δεδομένα} sys.byteorder

An indicator of the native byte order.  This will have the value @code{'big'} on
big-endian (most-significant byte first) platforms, and @code{'little'} on
little-endian (least-significant byte first) platforms.
@end deffn

@geindex builtin_module_names (στη μονάδα sys)
@anchor{library/sys sys builtin_module_names}@anchor{2236}
@deffn {Δεδομένα} 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{c1a,,sys.stdlib_module_names} list.
@end deffn

@geindex call_tracing() (στη μονάδα sys)
@anchor{library/sys sys call_tracing}@anchor{1dbd}
@deffn {Συνάρτηση} 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{55c,,settrace()} or @ref{18a0,,setprofile()} to avoid infinite recursion.
@code{call_tracing()} enables explicit recursion of the tracing function.
@end deffn

@geindex copyright (στη μονάδα sys)
@anchor{library/sys sys copyright}@anchor{4bd2}
@deffn {Δεδομένα} sys.copyright

A string containing the copyright pertaining to the Python interpreter.
@end deffn

@geindex _clear_type_cache() (στη μονάδα sys)
@anchor{library/sys sys _clear_type_cache}@anchor{344}
@deffn {Συνάρτηση} sys._clear_type_cache ()

Clear the internal type cache. The type cache is used to speed up attribute
and method lookups. Use the function `only' to drop unnecessary references
during reference leak debugging.

This function should be used for internal and specialized purposes only.


Αποσύρθηκε στην έκδοση 3.13: Use the more general @ref{345,,_clear_internal_caches()} function instead.

@end deffn

@geindex _clear_internal_caches() (στη μονάδα sys)
@anchor{library/sys sys _clear_internal_caches}@anchor{345}
@deffn {Συνάρτηση} 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.


Added in version 3.13.

@end deffn

@geindex _current_frames() (στη μονάδα sys)
@anchor{library/sys sys _current_frames}@anchor{17d5}
@deffn {Συνάρτηση} sys._current_frames ()

Return a dictionary mapping each thread’s identifier to the topmost stack frame
currently active in that thread at the time the function is called. Note that
functions in the @ref{107,,traceback} module can build the call stack given such a
frame.

This is most useful for debugging deadlock:  this function does not require the
deadlocked threads” cooperation, and such threads” call stacks are frozen for as
long as they remain deadlocked.  The frame returned for a non-deadlocked thread
may bear no relationship to that thread’s current activity by the time calling
code examines the frame.

This function should be used for internal and specialized purposes only.

Raises an @ref{1e65,,auditing event} @code{sys._current_frames} with no arguments.
@end deffn

@geindex _current_exceptions() (στη μονάδα sys)
@anchor{library/sys sys _current_exceptions}@anchor{8d2}
@deffn {Συνάρτηση} 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.

This function should be used for internal and specialized purposes only.

Raises an @ref{1e65,,auditing event} @code{sys._current_exceptions} with no arguments.


Άλλαξε στην έκδοση 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() (στη μονάδα sys)
@anchor{library/sys sys breakpointhook}@anchor{e9f}
@deffn {Συνάρτηση} sys.breakpointhook ()

This hook function is called by built-in @ref{4f9,,breakpoint()}.  By default,
it drops you into the @ref{aa,,pdb} debugger, but it can be set to any other
function so that you can choose which debugger gets used.

The signature of this function is dependent on what it calls.  For example,
the default binding (e.g. @code{pdb.set_trace()}) expects no arguments, but
you might bind it to a function that expects additional arguments
(positional and/or keyword).  The built-in @code{breakpoint()} function passes
its @code{*args} and @code{**kws} straight through.  Whatever
@code{breakpointhooks()} returns is returned from @code{breakpoint()}.

The default implementation first consults the environment variable
@geindex PYTHONBREAKPOINT
@geindex μεταβλητή περιβάλλοντος; PYTHONBREAKPOINT
@ref{ea0,,PYTHONBREAKPOINT}.  If that is set to @code{"0"} then this function
returns immediately; i.e. it is a no-op.  If the environment variable is
not set, or is set to the empty string, @code{pdb.set_trace()} is called.
Otherwise this variable should name a function to run, using Python’s
dotted-import nomenclature, e.g. @code{package.subpackage.module.function}.
In this case, @code{package.subpackage.module} would be imported and the
resulting module must have a callable named @code{function()}.  This is run,
passing in @code{*args} and @code{**kws}, and whatever @code{function()} returns,
@code{sys.breakpointhook()} returns to the built-in @ref{4f9,,breakpoint()}
function.

Note that if anything goes wrong while importing the callable named by
@geindex PYTHONBREAKPOINT
@geindex μεταβλητή περιβάλλοντος; PYTHONBREAKPOINT
@ref{ea0,,PYTHONBREAKPOINT}, a @ref{6dd,,RuntimeWarning} is reported and the
breakpoint is ignored.

Also note that if @code{sys.breakpointhook()} is overridden programmatically,
@geindex PYTHONBREAKPOINT
@geindex μεταβλητή περιβάλλοντος; PYTHONBREAKPOINT
@ref{ea0,,PYTHONBREAKPOINT} is `not' consulted.


Added in version 3.7.

@end deffn

@geindex _debugmallocstats() (στη μονάδα sys)
@anchor{library/sys sys _debugmallocstats}@anchor{4bd3}
@deffn {Συνάρτηση} sys._debugmallocstats ()

Print low-level information to stderr about the state of CPython’s memory
allocator.

If Python is @ref{3dc,,built in debug mode} (@ref{853,,configure --with-pydebug option}), it also performs some expensive
internal consistency checks.


Added in version 3.3.


`Λεπτομέρεια υλοποίησης CPython:' This function is specific to CPython.  The exact output format is not
defined here, and may change.
@end deffn

@geindex dllhandle (στη μονάδα sys)
@anchor{library/sys sys dllhandle}@anchor{4bd4}
@deffn {Δεδομένα} sys.dllhandle

Integer specifying the handle of the Python DLL.

@ref{232d,,Διαθεσιμότητα}: Windows.
@end deffn

@geindex displayhook() (στη μονάδα sys)
@anchor{library/sys sys displayhook}@anchor{18c1}
@deffn {Συνάρτηση} sys.displayhook (value)

If `value' is not @code{None}, this function prints @code{repr(value)} to
@code{sys.stdout}, and saves `value' in @code{builtins._}. If @code{repr(value)} is
not encodable to @code{sys.stdout.encoding} with @code{sys.stdout.errors} error
handler (which is probably @code{'strict'}), encode it to
@code{sys.stdout.encoding} with @code{'backslashreplace'} error handler.

@code{sys.displayhook} is called on the result of evaluating an @ref{25c4,,expression}
entered in an interactive Python session.  The display of these values can be
customized by assigning another one-argument function to @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


Άλλαξε στην έκδοση 3.2: Use @code{'backslashreplace'} error handler on @ref{a67,,UnicodeEncodeError}.

@end deffn

@geindex dont_write_bytecode (στη μονάδα sys)
@anchor{library/sys sys dont_write_bytecode}@anchor{4bd5}
@deffn {Δεδομένα} sys.dont_write_bytecode

If this is true, Python won’t try to write @code{.pyc} files on the
import of source modules.  This value is initially set to @code{True} or
@code{False} depending on the @ref{1770,,-B} command line option and the
@geindex PYTHONDONTWRITEBYTECODE
@geindex μεταβλητή περιβάλλοντος; PYTHONDONTWRITEBYTECODE
@ref{1771,,PYTHONDONTWRITEBYTECODE} environment variable, but you can set it
yourself to control bytecode file generation.
@end deffn

@geindex _emscripten_info (στη μονάδα sys)
@anchor{library/sys sys _emscripten_info}@anchor{1d8a}
@deffn {Δεδομένα} sys._emscripten_info

A @ref{a3d,,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 (ιδιότητα της sys._emscripten_info)
@anchor{library/sys sys _emscripten_info emscripten_version}@anchor{4bd6}
@deffn {Ιδιότητα} _emscripten_info.emscripten_version

Emscripten version as tuple of ints (major, minor, micro), e.g. @code{(3, 1, 8)}.
@end deffn

@geindex runtime (ιδιότητα της sys._emscripten_info)
@anchor{library/sys sys _emscripten_info runtime}@anchor{4bd7}
@deffn {Ιδιότητα} _emscripten_info.runtime

Runtime string, e.g. browser user agent, @code{'Node.js v14.18.2'}, or @code{'UNKNOWN'}.
@end deffn

@geindex pthreads (ιδιότητα της sys._emscripten_info)
@anchor{library/sys sys _emscripten_info pthreads}@anchor{4bd8}
@deffn {Ιδιότητα} _emscripten_info.pthreads

@code{True} if Python is compiled with Emscripten pthreads support.
@end deffn

@geindex shared_memory (ιδιότητα της sys._emscripten_info)
@anchor{library/sys sys _emscripten_info shared_memory}@anchor{4bd9}
@deffn {Ιδιότητα} _emscripten_info.shared_memory

@code{True} if Python is compiled with shared memory support.
@end deffn

@ref{232d,,Διαθεσιμότητα}: Emscripten.


Added in version 3.11.

@end deffn

@geindex pycache_prefix (στη μονάδα sys)
@anchor{library/sys sys pycache_prefix}@anchor{d6d}
@deffn {Δεδομένα} 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{21,,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.

A relative path is interpreted relative to the current working directory.

This value is initially set based on the value of the @ref{178,,-X}
@code{pycache_prefix=PATH} command-line option or the
@geindex PYTHONPYCACHEPREFIX
@geindex μεταβλητή περιβάλλοντος; PYTHONPYCACHEPREFIX
@ref{d6c,,PYTHONPYCACHEPREFIX} environment variable (command-line takes
precedence). If neither are set, it is @code{None}.


Added in version 3.8.

@end deffn

@geindex excepthook() (στη μονάδα sys)
@anchor{library/sys sys excepthook}@anchor{be5}
@deffn {Συνάρτηση} sys.excepthook (type, value, traceback)

This function prints out a given traceback and exception to @code{sys.stderr}.

When an exception other than @ref{10f7,,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}.


Raise an auditing event @code{sys.excepthook} with arguments @code{hook},
@code{type}, @code{value}, @code{traceback} when an uncaught exception occurs.
If no hook has been set, @code{hook} may be @code{None}. If any hook raises
an exception derived from @ref{30d,,RuntimeError} the call to the hook will
be suppressed. Otherwise, the audit hook exception will be reported as
unraisable and @code{sys.excepthook} will be called.



@subsubheading Δείτε επίσης


The @ref{70c,,sys.unraisablehook()} function handles unraisable exceptions
and the @ref{c23,,threading.excepthook()} function handles exception raised
by @ref{e00,,threading.Thread.run()}.

@end deffn

@geindex __breakpointhook__ (στη μονάδα sys)
@geindex __displayhook__ (στη μονάδα sys)
@geindex __excepthook__ (στη μονάδα sys)
@geindex __unraisablehook__ (στη μονάδα sys)
@anchor{library/sys sys __breakpointhook__}@anchor{4bda}
@deffn {Δεδομένα} sys.__breakpointhook__
@anchor{library/sys sys __displayhook__}@anchor{4bdb}
@deffnx {Δεδομένα} sys.__displayhook__
@anchor{library/sys sys __excepthook__}@anchor{4bdc}
@deffnx {Δεδομένα} sys.__excepthook__
@anchor{library/sys sys __unraisablehook__}@anchor{4bdd}
@deffnx {Δεδομένα} sys.__unraisablehook__

These objects contain the original values of @code{breakpointhook},
@code{displayhook}, @code{excepthook}, and @code{unraisablehook} at the start of the
program.  They are saved so that @code{breakpointhook}, @code{displayhook} and
@code{excepthook}, @code{unraisablehook} can be restored in case they happen to
get replaced with broken or alternative objects.


Added in version 3.7: __breakpointhook__



Added in version 3.8: __unraisablehook__

@end deffn

@geindex exception() (στη μονάδα sys)
@anchor{library/sys sys exception}@anchor{a7b}
@deffn {Συνάρτηση} 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}.


Added in version 3.11.

@end deffn

@geindex exc_info() (στη μονάδα sys)
@anchor{library/sys sys exc_info}@anchor{a7a}
@deffn {Συνάρτηση} sys.exc_info ()

This function returns the old-style representation of the handled
exception. If an exception @code{e} is currently handled (so
@ref{a7b,,exception()} would return @code{e}), @code{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{9b9,,BaseException}), the exception itself, and a @ref{eba,,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.


Άλλαξε στην έκδοση 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 @code{exc_info()}.

@end deffn

@geindex exec_prefix (στη μονάδα sys)
@anchor{library/sys sys exec_prefix}@anchor{3a8}
@deffn {Δεδομένα} sys.exec_prefix

A string giving the site-specific directory prefix where the platform-dependent
Python files are installed; by default, this is also @code{'/usr/local'}.  This can
be set at build time with the @code{--exec-prefix} argument to the
@code{configure} script.  Specifically, all configuration files (e.g. the
@code{pyconfig.h} header file) are installed in the directory
@code{`exec_prefix'/lib/python`X.Y'/config}, and shared library modules are
installed in @code{`exec_prefix'/lib/python`X.Y'/lib-dynload}, where `X.Y'
is the version number of Python, for example @code{3.2}.

@cartouche
@quotation Σημείωση 
If a @ref{3a9,,virtual environment} is in effect, this @code{exec_prefix}
will point to the virtual environment. The value for the Python installation
will still be available, via @ref{3a7,,base_exec_prefix}.
Refer to @ref{4b93,,Virtual Environments} for more information.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.14: When running under a @ref{3a9,,virtual environment},
@ref{3ab,,prefix} and @code{exec_prefix} are now set to the virtual
environment prefix by the @ref{1953,,path initialization},
instead of @ref{cf,,site}. This means that @code{prefix} and
@code{exec_prefix} always point to the virtual environment, even when
@code{site} is disabled (@ref{1551,,-S}).

@end deffn

@geindex executable (στη μονάδα sys)
@anchor{library/sys sys executable}@anchor{3ac}
@deffn {Δεδομένα} sys.executable

A string giving the absolute path of the executable binary for the Python
interpreter, on systems where this makes sense. If Python is unable to retrieve
the real path to its executable, @ref{3ac,,sys.executable} will be an empty string
or @code{None}.
@end deffn

@geindex exit() (στη μονάδα sys)
@anchor{library/sys sys exit}@anchor{4ff}
@deffn {Συνάρτηση} sys.exit ([arg])

Raise a @ref{10f7,,SystemExit} exception, signaling an intention to exit the interpreter.

The optional argument `arg' can be an integer giving the exit status
(defaulting to zero), or another type of object.  If it is an integer, zero
is considered «successful termination» and any nonzero value is considered
«abnormal termination» by shells and the like.  Most systems require it to be
in the range 0–127, and produce undefined results otherwise.  Some systems
have a convention for assigning specific meanings to specific exit codes, but
these are generally underdeveloped; Unix programs generally use 2 for command
line syntax errors and 1 for all other kinds of errors.  If another type of
object is passed, @code{None} is equivalent to passing zero, and any other
object is printed to @ref{d05,,stderr} and results in an exit code of 1.  In
particular, @code{sys.exit("some error message")} is a quick way to exit a
program when an error occurs.

Since @code{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 @ref{44c,,finally} clauses of
@ref{ad6,,try} statements are honored, and it is possible to intercept the
exit attempt at an outer level.


Άλλαξε στην έκδοση 3.6: If an error occurs in the cleanup after the Python interpreter
has caught @ref{10f7,,SystemExit} (such as an error flushing buffered data
in the standard streams), the exit status is changed to 120.

@end deffn

@geindex flags (στη μονάδα sys)
@anchor{library/sys sys flags}@anchor{a7c}
@deffn {Δεδομένα} sys.flags

The @ref{a3d,,named tuple} `flags' exposes the status of command line
flags.  Flags should only be accessed only by name and not by index.  The
attributes are read only.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex debug (ιδιότητα της sys.flags)
@anchor{library/sys sys flags debug}@anchor{4bde}
@deffn {Ιδιότητα} flags.debug
@end deffn

@tab

@ref{2312,,-d}

@item

@geindex inspect (ιδιότητα της sys.flags)
@anchor{library/sys sys flags inspect}@anchor{198a}
@deffn {Ιδιότητα} flags.inspect
@end deffn

@tab

@ref{187d,,-i}

@item

@geindex interactive (ιδιότητα της sys.flags)
@anchor{library/sys sys flags interactive}@anchor{4bdf}
@deffn {Ιδιότητα} flags.interactive
@end deffn

@tab

@ref{187d,,-i}

@item

@geindex isolated (ιδιότητα της sys.flags)
@anchor{library/sys sys flags isolated}@anchor{4be0}
@deffn {Ιδιότητα} flags.isolated
@end deffn

@tab

@ref{d28,,-I}

@item

@geindex optimize (ιδιότητα της sys.flags)
@anchor{library/sys sys flags optimize}@anchor{4be1}
@deffn {Ιδιότητα} flags.optimize
@end deffn

@tab

@ref{431,,-O} or @ref{116e,,-OO}

@item

@geindex dont_write_bytecode (ιδιότητα της sys.flags)
@anchor{library/sys sys flags dont_write_bytecode}@anchor{4be2}
@deffn {Ιδιότητα} flags.dont_write_bytecode
@end deffn

@tab

@ref{1770,,-B}

@item

@geindex no_user_site (ιδιότητα της sys.flags)
@anchor{library/sys sys flags no_user_site}@anchor{4be3}
@deffn {Ιδιότητα} flags.no_user_site
@end deffn

@tab

@ref{1732,,-s}

@item

@geindex no_site (ιδιότητα της sys.flags)
@anchor{library/sys sys flags no_site}@anchor{4be4}
@deffn {Ιδιότητα} flags.no_site
@end deffn

@tab

@ref{1551,,-S}

@item

@geindex ignore_environment (ιδιότητα της sys.flags)
@anchor{library/sys sys flags ignore_environment}@anchor{4be5}
@deffn {Ιδιότητα} flags.ignore_environment
@end deffn

@tab

@ref{d27,,-E}

@item

@geindex verbose (ιδιότητα της sys.flags)
@anchor{library/sys sys flags verbose}@anchor{4be6}
@deffn {Ιδιότητα} flags.verbose
@end deffn

@tab

@ref{17c7,,-v}

@item

@geindex bytes_warning (ιδιότητα της sys.flags)
@anchor{library/sys sys flags bytes_warning}@anchor{4be7}
@deffn {Ιδιότητα} flags.bytes_warning
@end deffn

@tab

@ref{2ed,,-b}

@item

@geindex quiet (ιδιότητα της sys.flags)
@anchor{library/sys sys flags quiet}@anchor{4be8}
@deffn {Ιδιότητα} flags.quiet
@end deffn

@tab

@ref{1994,,-q}

@item

@geindex hash_randomization (ιδιότητα της sys.flags)
@anchor{library/sys sys flags hash_randomization}@anchor{4be9}
@deffn {Ιδιότητα} flags.hash_randomization
@end deffn

@tab

@ref{2065,,-R}

@item

@geindex dev_mode (ιδιότητα της sys.flags)
@anchor{library/sys sys flags dev_mode}@anchor{206f}
@deffn {Ιδιότητα} flags.dev_mode
@end deffn

@tab

@ref{178,,-X dev} (@ref{70d,,Python Development Mode})

@item

@geindex utf8_mode (ιδιότητα της sys.flags)
@anchor{library/sys sys flags utf8_mode}@anchor{4bea}
@deffn {Ιδιότητα} flags.utf8_mode
@end deffn

@tab

@ref{178,,-X utf8}

@item

@geindex safe_path (ιδιότητα της sys.flags)
@anchor{library/sys sys flags safe_path}@anchor{741}
@deffn {Ιδιότητα} flags.safe_path
@end deffn

@tab

@ref{9a3,,-P}

@item

@geindex int_max_str_digits (ιδιότητα της sys.flags)
@anchor{library/sys sys flags int_max_str_digits}@anchor{28d7}
@deffn {Ιδιότητα} flags.int_max_str_digits
@end deffn

@tab

@ref{178,,-X int_max_str_digits}
(@ref{9ec,,integer string conversion length limitation})

@item

@geindex warn_default_encoding (ιδιότητα της sys.flags)
@anchor{library/sys sys flags warn_default_encoding}@anchor{4beb}
@deffn {Ιδιότητα} flags.warn_default_encoding
@end deffn

@tab

@ref{178,,-X warn_default_encoding}

@item

@geindex gil (ιδιότητα της sys.flags)
@anchor{library/sys sys flags gil}@anchor{4bec}
@deffn {Ιδιότητα} flags.gil
@end deffn

@tab

@ref{178,,-X gil} and 
@geindex PYTHON_GIL
@geindex μεταβλητή περιβάλλοντος; PYTHON_GIL
@ref{6a6,,PYTHON_GIL}

@item

@geindex thread_inherit_context (ιδιότητα της sys.flags)
@anchor{library/sys sys flags thread_inherit_context}@anchor{41f}
@deffn {Ιδιότητα} flags.thread_inherit_context
@end deffn

@tab

@ref{178,,-X thread_inherit_context} and
@geindex PYTHON_THREAD_INHERIT_CONTEXT
@geindex μεταβλητή περιβάλλοντος; PYTHON_THREAD_INHERIT_CONTEXT
@ref{1a90,,PYTHON_THREAD_INHERIT_CONTEXT}

@item

@geindex context_aware_warnings (ιδιότητα της sys.flags)
@anchor{library/sys sys flags context_aware_warnings}@anchor{42f}
@deffn {Ιδιότητα} flags.context_aware_warnings
@end deffn

@tab

@ref{178,,-X context_aware_warnings} and
@geindex PYTHON_CONTEXT_AWARE_WARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHON_CONTEXT_AWARE_WARNINGS
@ref{1a83,,PYTHON_CONTEXT_AWARE_WARNINGS}

@end multitable



Άλλαξε στην έκδοση 3.2: Added @code{quiet} attribute for the new @ref{1994,,-q} flag.



Added in version 3.2.3: The @code{hash_randomization} attribute.



Άλλαξε στην έκδοση 3.3: Removed obsolete @code{division_warning} attribute.



Άλλαξε στην έκδοση 3.4: Added @code{isolated} attribute for @ref{d28,,-I} @code{isolated} flag.



Άλλαξε στην έκδοση 3.7: Added the @code{dev_mode} attribute for the new @ref{70d,,Python Development Mode} and the @code{utf8_mode} attribute for the new  @ref{178,,-X}
@code{utf8} flag.



Άλλαξε στην έκδοση 3.10: Added @code{warn_default_encoding} attribute for @ref{178,,-X} @code{warn_default_encoding} flag.



Άλλαξε στην έκδοση 3.11: Added the @code{safe_path} attribute for @ref{9a3,,-P} option.



Άλλαξε στην έκδοση 3.11: Added the @code{int_max_str_digits} attribute.



Άλλαξε στην έκδοση 3.13: Added the @code{gil} attribute.



Άλλαξε στην έκδοση 3.14: Added the @code{thread_inherit_context} attribute.



Άλλαξε στην έκδοση 3.14: Added the @code{context_aware_warnings} attribute.

@end deffn

@geindex float_info (στη μονάδα sys)
@anchor{library/sys sys float_info}@anchor{1fbf}
@deffn {Δεδομένα} sys.float_info

A @ref{a3d,,named tuple} holding information about the float type. It
contains low level information about the precision and internal
representation.  The values correspond to the various floating-point
constants defined in the standard header file @code{float.h} for the “C”
programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard
@ref{4bed,,[C99]}, “Characteristics of floating types”, for details.
Attributes of the @code{float_info} named tuple



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

attribute

@tab

float.h macro

@tab

explanation

@item

@geindex epsilon (ιδιότητα της sys.float_info)
@anchor{library/sys sys float_info epsilon}@anchor{4bee}
@deffn {Ιδιότητα} 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.

See also @ref{ce1,,math.ulp()}.

@item

@geindex dig (ιδιότητα της sys.float_info)
@anchor{library/sys sys float_info dig}@anchor{4bef}
@deffn {Ιδιότητα} 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 (ιδιότητα της sys.float_info)
@anchor{library/sys sys float_info mant_dig}@anchor{4bf0}
@deffn {Ιδιότητα} 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 (ιδιότητα της sys.float_info)
@anchor{library/sys sys float_info max}@anchor{4bf1}
@deffn {Ιδιότητα} float_info.max
@end deffn

@tab

@code{DBL_MAX}

@tab

The maximum representable positive finite float.

@item

@geindex max_exp (ιδιότητα της sys.float_info)
@anchor{library/sys sys float_info max_exp}@anchor{4bf2}
@deffn {Ιδιότητα} 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 (ιδιότητα της sys.float_info)
@anchor{library/sys sys float_info max_10_exp}@anchor{4bf3}
@deffn {Ιδιότητα} 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 (ιδιότητα της sys.float_info)
@anchor{library/sys sys float_info min}@anchor{2c98}
@deffn {Ιδιότητα} float_info.min
@end deffn

@tab

@code{DBL_MIN}

@tab

The minimum representable positive `normalized' float.

Use @ref{ce1,,math.ulp(0.0)} to get the smallest positive
`denormalized' representable float.

@item

@geindex min_exp (ιδιότητα της sys.float_info)
@anchor{library/sys sys float_info min_exp}@anchor{4bf4}
@deffn {Ιδιότητα} 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 (ιδιότητα της sys.float_info)
@anchor{library/sys sys float_info min_10_exp}@anchor{4bf5}
@deffn {Ιδιότητα} 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 (ιδιότητα της sys.float_info)
@anchor{library/sys sys float_info radix}@anchor{4bf6}
@deffn {Ιδιότητα} float_info.radix
@end deffn

@tab

@code{FLT_RADIX}

@tab

The radix of exponent representation.

@item

@geindex rounds (ιδιότητα της sys.float_info)
@anchor{library/sys sys float_info rounds}@anchor{4bf7}
@deffn {Ιδιότητα} 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{4bef,,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

But for strings with more than @ref{4bef,,sys.float_info.dig} significant digits,
this isn’t always true:

@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 (στη μονάδα sys)
@anchor{library/sys sys float_repr_style}@anchor{169f}
@deffn {Δεδομένα} sys.float_repr_style

A string indicating how the @ref{45b,,repr()} function behaves for
floats.  If the string has value @code{'short'} then for a finite
float @code{x}, @code{repr(x)} aims to produce a short string with the
property that @code{float(repr(x)) == x}.  This is the usual behaviour
in Python 3.1 and later.  Otherwise, @code{float_repr_style} has value
@code{'legacy'} and @code{repr(x)} behaves in the same way as it did in
versions of Python prior to 3.1.


Added in version 3.1.

@end deffn

@geindex getallocatedblocks() (στη μονάδα sys)
@anchor{library/sys sys getallocatedblocks}@anchor{1370}
@deffn {Συνάρτηση} 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{345,,_clear_internal_caches()} and @ref{44f,,gc.collect()} to get more
predictable results.

If a Python build or implementation cannot reasonably compute this
information, @code{getallocatedblocks()} is allowed to return 0 instead.


Added in version 3.4.

@end deffn

@geindex getunicodeinternedsize() (στη μονάδα sys)
@anchor{library/sys sys getunicodeinternedsize}@anchor{4bf8}
@deffn {Συνάρτηση} sys.getunicodeinternedsize ()

Return the number of unicode objects that have been interned.


Added in version 3.12.

@end deffn

@geindex getandroidapilevel() (στη μονάδα sys)
@anchor{library/sys sys getandroidapilevel}@anchor{f49}
@deffn {Συνάρτηση} 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{1bd0,,platform.android_ver()}.

@ref{232d,,Διαθεσιμότητα}: Android.


Added in version 3.7.

@end deffn

@geindex getdefaultencoding() (στη μονάδα sys)
@anchor{library/sys sys getdefaultencoding}@anchor{4bf9}
@deffn {Συνάρτηση} sys.getdefaultencoding ()

Return @code{'utf-8'}. This is the name of the default string encoding, used
in methods like @ref{ca7,,str.encode()}.
@end deffn

@geindex getdlopenflags() (στη μονάδα sys)
@anchor{library/sys sys getdlopenflags}@anchor{18b0}
@deffn {Συνάρτηση} 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{a5,,os} module (@code{RTLD_@var{xxx}} constants, e.g.
@ref{14c4,,os.RTLD_LAZY}).

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex getfilesystemencoding() (στη μονάδα sys)
@anchor{library/sys sys getfilesystemencoding}@anchor{1017}
@deffn {Συνάρτηση} sys.getfilesystemencoding ()

Get the @ref{948,,filesystem encoding}:
the encoding used with the filesystem error handler to convert between Unicode filenames and bytes
filenames. The filesystem error handler is returned from
@ref{10a3,,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.

@ref{1013,,os.fsencode()} and @ref{1012,,os.fsdecode()} should be used to ensure that
the correct encoding and errors mode are used.

The @ref{948,,filesystem encoding and error handler} are configured at Python
startup by the @ref{b6f,,PyConfig_Read()} function: see
@ref{62e,,filesystem_encoding} and
@ref{62f,,filesystem_errors} members of @ref{60b,,PyConfig}.


Άλλαξε στην έκδοση 3.2: @code{getfilesystemencoding()} result cannot be @code{None} anymore.



Άλλαξε στην έκδοση 3.6: Windows is no longer guaranteed to return @code{'mbcs'}. See 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/}
and @ref{30e,,_enablelegacywindowsfsencoding()} for more information.



Άλλαξε στην έκδοση 3.7: Return @code{'utf-8'} if the @ref{a46,,Python UTF-8 Mode} is
enabled.

@end deffn

@geindex getfilesystemencodeerrors() (στη μονάδα sys)
@anchor{library/sys sys getfilesystemencodeerrors}@anchor{10a3}
@deffn {Συνάρτηση} sys.getfilesystemencodeerrors ()

Get the @ref{948,,filesystem error handler}: the error handler used with the filesystem encoding to convert between Unicode
filenames and bytes filenames. The filesystem encoding is returned from
@ref{1017,,getfilesystemencoding()}.

@ref{1013,,os.fsencode()} and @ref{1012,,os.fsdecode()} should be used to ensure that
the correct encoding and errors mode are used.

The @ref{948,,filesystem encoding and error handler} are configured at Python
startup by the @ref{b6f,,PyConfig_Read()} function: see
@ref{62e,,filesystem_encoding} and
@ref{62f,,filesystem_errors} members of @ref{60b,,PyConfig}.


Added in version 3.6.

@end deffn

@geindex get_int_max_str_digits() (στη μονάδα sys)
@anchor{library/sys sys get_int_max_str_digits}@anchor{1a12}
@deffn {Συνάρτηση} sys.get_int_max_str_digits ()

Returns the current value for the @ref{9ec,,integer string conversion length limitation}. See also @ref{1b11,,set_int_max_str_digits()}.


Added in version 3.11.

@end deffn

@geindex get_lazy_imports() (στη μονάδα sys)
@anchor{library/sys sys get_lazy_imports}@anchor{17b}
@deffn {Συνάρτηση} sys.get_lazy_imports ()

Returns the current lazy imports mode as a string.


@itemize *

@item 
@code{"normal"}: Only imports explicitly marked with the @code{lazy} keyword
are lazy

@item 
@code{"all"}: All top-level imports are potentially lazy

@item 
@code{"none"}: All lazy imports are suppressed (even explicitly marked
ones)
@end itemize

See also @ref{17a,,set_lazy_imports()} and 
@geindex Python Enhancement Proposals; PEP 810
PEP 810@footnote{https://peps.python.org/pep-0810/}.


Added in version 3.15.

@end deffn

@geindex get_lazy_imports_filter() (στη μονάδα sys)
@anchor{library/sys sys get_lazy_imports_filter}@anchor{4bfa}
@deffn {Συνάρτηση} sys.get_lazy_imports_filter ()

Returns the current lazy imports filter function, or @code{None} if no
filter is set.

The filter function is called for every potentially lazy import to
determine whether it should actually be lazy. See
@ref{17c,,set_lazy_imports_filter()} for details on the filter function
signature.


Added in version 3.15.

@end deffn

@geindex getrefcount() (στη μονάδα sys)
@anchor{library/sys sys getrefcount}@anchor{54a}
@deffn {Συνάρτηση} sys.getrefcount (object)

Return the reference count of the `object'.  The count returned is generally one
higher than you might expect, because it includes the (temporary) reference as
an argument to @code{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{398,,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.

`Λεπτομέρεια υλοποίησης CPython:' @ref{398,,Immortal} objects with a large reference count can be
identified via @ref{517,,_is_immortal()}.


Άλλαξε στην έκδοση 3.12: Immortal objects have very large refcounts that do not match
the actual number of references to the object.

@end deffn

@geindex getrecursionlimit() (στη μονάδα sys)
@anchor{library/sys sys getrecursionlimit}@anchor{8d4}
@deffn {Συνάρτηση} sys.getrecursionlimit ()

Return the current value of the recursion limit, the maximum depth of the Python
interpreter stack.  This limit prevents infinite recursion from causing an
overflow of the C stack and crashing Python.  It can be set by
@ref{8d3,,setrecursionlimit()}.
@end deffn

@geindex getsizeof() (στη μονάδα sys)
@anchor{library/sys sys getsizeof}@anchor{1cda}
@deffn {Συνάρτηση} sys.getsizeof (object[, default])

Return the size of an object in bytes. The object can be any type of
object. All built-in objects will return correct results, but this
does not have to hold true for third-party extensions as it is implementation
specific.

Only the memory consumption directly attributed to the object is
accounted for, not the memory consumption of objects it refers to.

If given, `default' will be returned if the object does not provide means to
retrieve the size.  Otherwise a @ref{291,,TypeError} will be raised.

@code{getsizeof()} calls the object’s @code{__sizeof__} method and adds an
additional garbage collector overhead if the object is managed by the garbage
collector.

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 @code{getsizeof()} recursively to find the size of
containers and all their contents.
@end deffn

@geindex getswitchinterval() (στη μονάδα sys)
@anchor{library/sys sys getswitchinterval}@anchor{d15}
@deffn {Συνάρτηση} sys.getswitchinterval ()

Return the interpreter’s «thread switch interval» in seconds; see
@ref{d16,,setswitchinterval()}.


Added in version 3.2.

@end deffn

@geindex _getframe() (στη μονάδα sys)
@anchor{library/sys sys _getframe}@anchor{ace}
@deffn {Συνάρτηση} sys._getframe ([depth])

Return a frame object from the call stack.  If optional integer `depth' is
given, return the frame object that many calls below the top of the stack.  If
that is deeper than the call stack, @ref{277,,ValueError} is raised.  The default
for `depth' is zero, returning the frame at the top of the call stack.

Raises an @ref{1e65,,auditing event} @code{sys._getframe} with argument @code{frame}.

`Λεπτομέρεια υλοποίησης CPython:' This function should be used for internal and specialized purposes only.
It is not guaranteed to exist in all implementations of Python.
@end deffn

@geindex _getframemodulename() (στη μονάδα sys)
@anchor{library/sys sys _getframemodulename}@anchor{1cde}
@deffn {Συνάρτηση} 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{1e65,,auditing event} @code{sys._getframemodulename} with argument @code{depth}.

`Λεπτομέρεια υλοποίησης CPython:' This function should be used for internal and specialized purposes only.
It is not guaranteed to exist in all implementations of Python.


Added in version 3.12.

@end deffn

@geindex getobjects() (στη μονάδα sys)
@anchor{library/sys sys getobjects}@anchor{516}
@deffn {Συνάρτηση} sys.getobjects (limit[, type])

This function only exists if CPython was built using the
specialized configure option @ref{828,,--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{4bfb,,PyInterpreterConfig.use_main_obmalloc} set to 1
or using @ref{1d2f,,Py_NewInterpreter()}, and the
@ref{410,,main interpreter}).
Mixing objects from different interpreters may lead to crashes
or other unexpected behavior.

`Λεπτομέρεια υλοποίησης CPython:' This function should be used for specialized purposes only.
It is not guaranteed to exist in all implementations of Python.


Άλλαξε στην έκδοση 3.14: The result may include objects from other interpreters.

@end deffn

@geindex getprofile() (στη μονάδα sys)
@anchor{library/sys sys getprofile}@anchor{1783}
@deffn {Συνάρτηση} sys.getprofile ()

@geindex profile function
@geindex profiler

Get the profiler function as set by @ref{18a0,,setprofile()}.
@end deffn

@geindex gettrace() (στη μονάδα sys)
@anchor{library/sys sys gettrace}@anchor{1784}
@deffn {Συνάρτηση} sys.gettrace ()

@geindex trace function
@geindex debugger

Get the trace function as set by @ref{55c,,settrace()}.

`Λεπτομέρεια υλοποίησης CPython:' The @code{gettrace()} function is intended only for implementing debuggers,
profilers, coverage tools and the like.  Its behavior is part of the
implementation platform, rather than part of the language definition, and
thus may not be available in all Python implementations.
@end deffn

@geindex getwindowsversion() (στη μονάδα sys)
@anchor{library/sys sys getwindowsversion}@anchor{10a4}
@deffn {Συνάρτηση} sys.getwindowsversion ()

Return a named tuple describing the Windows version
currently running.  The named elements are `major', `minor',
`build', `platform', `service_pack', `service_pack_minor',
`service_pack_major', `suite_mask', `product_type' and
`platform_version'. `service_pack' contains a string,
`platform_version' a 3-tuple and all other values are
integers. The components can also be accessed by name, so
@code{sys.getwindowsversion()[0]} is equivalent to
@code{sys.getwindowsversion().major}. For compatibility with prior
versions, only the first 5 elements are retrievable by indexing.

`platform' will be @code{2} (VER_PLATFORM_WIN32_NT).

`product_type' may be one of the following values:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constant

@tab

Meaning

@item

@code{1} (VER_NT_WORKSTATION)

@tab

The system is a workstation.

@item

@code{2} (VER_NT_DOMAIN_CONTROLLER)

@tab

The system is a domain
controller.

@item

@code{3} (VER_NT_SERVER)

@tab

The system is a server, but not
a domain controller.

@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 Σημείωση 
`platform_version' derives the version from kernel32.dll which can be of a different
version than the OS version. Please use @ref{af,,platform} module for achieving accurate
OS version.
@end quotation
@end cartouche

@ref{232d,,Διαθεσιμότητα}: Windows.


Άλλαξε στην έκδοση 3.2: Changed to a named tuple and added `service_pack_minor',
`service_pack_major', `suite_mask', and `product_type'.



Άλλαξε στην έκδοση 3.6: Added `platform_version'

@end deffn

@geindex get_asyncgen_hooks() (στη μονάδα sys)
@anchor{library/sys sys get_asyncgen_hooks}@anchor{1dbe}
@deffn {Συνάρτηση} sys.get_asyncgen_hooks ()

Returns an `asyncgen_hooks' object, which is similar to a
@ref{1cf,,namedtuple} of the form @code{(firstiter, finalizer)},
where `firstiter' and `finalizer' are expected to be either @code{None} or
functions which take an @ref{3b87,,asynchronous generator iterator} as an
argument, and are used to schedule finalization of an asynchronous
generator by an event loop.


Added in version 3.6: See 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/} for more details.


@cartouche
@quotation Σημείωση 
This function has been added on a provisional basis (see 
@geindex Python Enhancement Proposals; PEP 411
PEP 411@footnote{https://peps.python.org/pep-0411/}
for details.)
@end quotation
@end cartouche
@end deffn

@geindex get_coroutine_origin_tracking_depth() (στη μονάδα sys)
@anchor{library/sys sys get_coroutine_origin_tracking_depth}@anchor{f4a}
@deffn {Συνάρτηση} sys.get_coroutine_origin_tracking_depth ()

Get the current coroutine origin tracking depth, as set by
@ref{f4b,,set_coroutine_origin_tracking_depth()}.


Added in version 3.7.


@cartouche
@quotation Σημείωση 
This function has been added on a provisional basis (see 
@geindex Python Enhancement Proposals; PEP 411
PEP 411@footnote{https://peps.python.org/pep-0411/}
for details.)  Use it only for debugging purposes.
@end quotation
@end cartouche
@end deffn

@geindex hash_info (στη μονάδα sys)
@anchor{library/sys sys hash_info}@anchor{13a8}
@deffn {Δεδομένα} sys.hash_info

A @ref{a3d,,named tuple} giving parameters of the numeric hash
implementation.  For more details about hashing of numeric types, see
@ref{27f8,,Κατακερματισμός των αριθμητικών τύπων}.

@geindex width (ιδιότητα της sys.hash_info)
@anchor{library/sys sys hash_info width}@anchor{4bfc}
@deffn {Ιδιότητα} hash_info.width

The width in bits used for hash values
@end deffn

@geindex modulus (ιδιότητα της sys.hash_info)
@anchor{library/sys sys hash_info modulus}@anchor{27f9}
@deffn {Ιδιότητα} hash_info.modulus

The prime modulus P used for numeric hash scheme
@end deffn

@geindex inf (ιδιότητα της sys.hash_info)
@anchor{library/sys sys hash_info inf}@anchor{4bfd}
@deffn {Ιδιότητα} hash_info.inf

The hash value returned for a positive infinity
@end deffn

@geindex nan (ιδιότητα της sys.hash_info)
@anchor{library/sys sys hash_info nan}@anchor{4bfe}
@deffn {Ιδιότητα} hash_info.nan

(This attribute is no longer used)
@end deffn

@geindex imag (ιδιότητα της sys.hash_info)
@anchor{library/sys sys hash_info imag}@anchor{4bff}
@deffn {Ιδιότητα} hash_info.imag

The multiplier used for the imaginary part of a complex number
@end deffn

@geindex algorithm (ιδιότητα της sys.hash_info)
@anchor{library/sys sys hash_info algorithm}@anchor{4c00}
@deffn {Ιδιότητα} hash_info.algorithm

The name of the algorithm for hashing of str, bytes, and memoryview
@end deffn

@geindex hash_bits (ιδιότητα της sys.hash_info)
@anchor{library/sys sys hash_info hash_bits}@anchor{4c01}
@deffn {Ιδιότητα} hash_info.hash_bits

The internal output size of the hash algorithm
@end deffn

@geindex seed_bits (ιδιότητα της sys.hash_info)
@anchor{library/sys sys hash_info seed_bits}@anchor{4c02}
@deffn {Ιδιότητα} hash_info.seed_bits

The size of the seed key of the hash algorithm
@end deffn

@geindex cutoff (ιδιότητα της sys.hash_info)
@anchor{library/sys sys hash_info cutoff}@anchor{4c03}
@deffn {Ιδιότητα} hash_info.cutoff

Cutoff for small string DJBX33A optimization in range @code{[1, cutoff)}.
@end deffn


Added in version 3.2.



Άλλαξε στην έκδοση 3.4: Added `algorithm', `hash_bits', `seed_bits', and `cutoff'.

@end deffn

@geindex hexversion (στη μονάδα sys)
@anchor{library/sys sys hexversion}@anchor{4c04}
@deffn {Δεδομένα} sys.hexversion

The version number encoded as a single integer.  This is guaranteed to increase
with each version, including proper support for non-production releases.  For
example, to test that the Python interpreter is at least version 1.5.2, use:

@example
if sys.hexversion >= 0x010502F0:
    # use some advanced feature
    ...
else:
    # use an alternative implementation or warn the user
    ...
@end example

This is called @code{hexversion} since it only really looks meaningful when viewed
as the result of passing it to the built-in @ref{1674,,hex()} function.  The
@ref{a3d,,named tuple}  @ref{2fc,,sys.version_info} may be used for a more
human-friendly encoding of the same information.

More details of @code{hexversion} can be found at @ref{4c05,,API and ABI Versioning}.
@end deffn

@geindex implementation (στη μονάδα sys)
@anchor{library/sys sys implementation}@anchor{926}
@deffn {Δεδομένα} sys.implementation

An object containing information about the implementation of the
currently running Python interpreter.  The following attributes are
required to exist in all Python implementations.

`name' is the implementation’s identifier, e.g. @code{'cpython'}.  The actual
string is defined by the Python implementation, but it is guaranteed to be
lower case.

`version' is a named tuple, in the same format as
@ref{2fc,,sys.version_info}.  It represents the version of the Python
`implementation'.  This has a distinct meaning from the specific
version of the Python `language' to which the currently running
interpreter conforms, which @code{sys.version_info} represents.  For
example, for PyPy 1.8 @code{sys.implementation.version} might be
@code{sys.version_info(1, 8, 0, 'final', 0)}, whereas @code{sys.version_info}
would be @code{sys.version_info(2, 7, 2, 'final', 0)}.  For CPython they
are the same value, since it is the reference implementation.

`hexversion' is the implementation version in hexadecimal format, like
@ref{4c04,,sys.hexversion}.

`cache_tag' is the tag used by the import machinery in the filenames of
cached modules.  By convention, it would be a composite of the
implementation’s name and version, like @code{'cpython-33'}.  However, a
Python implementation may use some other value if appropriate.  If
@code{cache_tag} is set to @code{None}, it indicates that module caching should
be disabled.

`supports_isolated_interpreters' is a boolean value, whether
this implementation supports multiple isolated interpreters.
It is @code{True} for CPython on most platforms.  Platforms with
this support implement the low-level @code{_interpreters} module.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 684
PEP 684@footnote{https://peps.python.org/pep-0684/}, 
@geindex Python Enhancement Proposals; PEP 734
PEP 734@footnote{https://peps.python.org/pep-0734/}, and @ref{25,,concurrent.interpreters}.


@ref{926,,sys.implementation} may contain additional attributes specific to
the Python implementation.  These non-standard attributes must start with
an underscore, and are not described here.  Regardless of its contents,
@code{sys.implementation} will not change during a run of the interpreter,
nor between implementation versions.  (It may change between Python
language versions, however.)  See 
@geindex Python Enhancement Proposals; PEP 421
PEP 421@footnote{https://peps.python.org/pep-0421/} for more information.


Added in version 3.3.



Άλλαξε στην έκδοση 3.14: Added @code{supports_isolated_interpreters} field.


@cartouche
@quotation Σημείωση 
The addition of new required attributes must go through the normal PEP
process. See 
@geindex Python Enhancement Proposals; PEP 421
PEP 421@footnote{https://peps.python.org/pep-0421/} for more information.
@end quotation
@end cartouche
@end deffn

@geindex int_info (στη μονάδα sys)
@anchor{library/sys sys int_info}@anchor{1638}
@deffn {Δεδομένα} sys.int_info

A @ref{a3d,,named tuple} that holds information about Python’s internal
representation of integers.  The attributes are read only.

@geindex bits_per_digit (ιδιότητα της sys.int_info)
@anchor{library/sys sys int_info bits_per_digit}@anchor{4c06}
@deffn {Ιδιότητα} 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 (ιδιότητα της sys.int_info)
@anchor{library/sys sys int_info sizeof_digit}@anchor{4c07}
@deffn {Ιδιότητα} int_info.sizeof_digit

The size in bytes of the C type used to represent a digit.
@end deffn

@geindex default_max_str_digits (ιδιότητα της sys.int_info)
@anchor{library/sys sys int_info default_max_str_digits}@anchor{28d8}
@deffn {Ιδιότητα} int_info.default_max_str_digits

The default value for @ref{1a12,,sys.get_int_max_str_digits()}
when it is not otherwise explicitly configured.
@end deffn

@geindex str_digits_check_threshold (ιδιότητα της sys.int_info)
@anchor{library/sys sys int_info str_digits_check_threshold}@anchor{4c08}
@deffn {Ιδιότητα} int_info.str_digits_check_threshold

The minimum non-zero value for @ref{1b11,,sys.set_int_max_str_digits()},
@geindex PYTHONINTMAXSTRDIGITS
@geindex μεταβλητή περιβάλλοντος; PYTHONINTMAXSTRDIGITS
@ref{1d38,,PYTHONINTMAXSTRDIGITS}, or @ref{178,,-X int_max_str_digits}.
@end deffn


Added in version 3.1.



Άλλαξε στην έκδοση 3.11: Added @ref{28d8,,default_max_str_digits} and
@ref{4c08,,str_digits_check_threshold}.

@end deffn

@geindex __interactivehook__ (στη μονάδα sys)
@anchor{library/sys sys __interactivehook__}@anchor{1371}
@deffn {Δεδομένα} sys.__interactivehook__

When this attribute exists, its value is automatically called (with no
arguments) when the interpreter is launched in @ref{656,,interactive mode}.  This is done after the 
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP} file is
read, so that you can set this hook there.  The @ref{cf,,site} module
@ref{1372,,sets this}.


Raises an @ref{1e65,,auditing event}
@code{cpython.run_interactivehook} with the hook object as the argument when
the hook is called on startup.



Added in version 3.4.

@end deffn

@geindex intern() (στη μονάδα sys)
@anchor{library/sys sys intern}@anchor{1680}
@deffn {Συνάρτηση} sys.intern (string)

Enter `string' in the table of «interned» strings and return the interned string
– which is `string' itself or a copy. Interning strings is useful to gain a
little performance on dictionary lookup – if the keys in a dictionary are
interned, and the lookup key is interned, the key comparisons (after hashing)
can be done by a pointer compare instead of a string compare.  Normally, the
names used in Python programs are automatically interned, and the dictionaries
used to hold module, class or instance attributes have interned keys.

Interned strings are not @ref{398,,immortal}; you must keep a reference to the
return value of @code{intern()} around to benefit from it.
@end deffn

@geindex _is_gil_enabled() (στη μονάδα sys)
@anchor{library/sys sys _is_gil_enabled}@anchor{4c09}
@deffn {Συνάρτηση} sys._is_gil_enabled ()

Return @ref{fcc,,True} if the @ref{411,,GIL} is enabled and @ref{ef5,,False} if
it is disabled.


Added in version 3.13.


`Λεπτομέρεια υλοποίησης CPython:' It is not guaranteed to exist in all implementations of Python.
@end deffn

@geindex is_finalizing() (στη μονάδα sys)
@anchor{library/sys sys is_finalizing}@anchor{e4f}
@deffn {Συνάρτηση} sys.is_finalizing ()

Return @ref{fcc,,True} if the main Python interpreter is
@ref{1a0,,shutting down}. Return @ref{ef5,,False} otherwise.

See also the @ref{68a,,PythonFinalizationError} exception.


Added in version 3.5.

@end deffn

@geindex _jit (στη μονάδα sys)
@anchor{library/sys sys _jit}@anchor{519}
@deffn {Δεδομένα} sys._jit

Utilities for observing just-in-time compilation.

`Λεπτομέρεια υλοποίησης CPython:' JIT compilation is an `experimental implementation detail' of CPython.
@code{sys._jit} is not guaranteed to exist or behave the same way in all
Python implementations, versions, or build configurations.


Added in version 3.14.


@geindex _jit.is_available() (στη μονάδα sys)
@anchor{library/sys sys _jit is_available}@anchor{662}
@deffn {Συνάρτηση} _jit.is_available ()

Return @code{True} if the current Python executable supports JIT compilation,
and @code{False} otherwise.  This can be controlled by building CPython with
the @code{--experimental-jit} option on Windows, and the
@ref{661,,--enable-experimental-jit} option on all other platforms.
@end deffn

@geindex _jit.is_enabled() (στη μονάδα sys)
@anchor{library/sys sys _jit is_enabled}@anchor{663}
@deffn {Συνάρτηση} _jit.is_enabled ()

Return @code{True} if JIT compilation is enabled for the current Python
process (implies @ref{662,,sys._jit.is_available()}), and @code{False} otherwise.
If JIT compilation is available, this can be controlled by setting the
@geindex PYTHON_JIT
@geindex μεταβλητή περιβάλλοντος; PYTHON_JIT
@ref{660,,PYTHON_JIT} environment variable to @code{0} (disabled) or @code{1}
(enabled) at interpreter startup.
@end deffn

@geindex _jit.is_active() (στη μονάδα sys)
@anchor{library/sys sys _jit is_active}@anchor{1a89}
@deffn {Συνάρτηση} _jit.is_active ()

Return @code{True} if the topmost Python frame is currently executing JIT
code (implies @ref{663,,sys._jit.is_enabled()}), and @code{False} otherwise.

@cartouche
@quotation Σημείωση 
This function is intended for testing and debugging the JIT itself.
It should be avoided for any other purpose.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Due to the nature of tracing JIT compilers, repeated calls to this
function may give surprising results. For example, branching on its
return value will likely lead to unexpected behavior (if doing so
causes JIT code to be entered or exited):

@example
>>> for warmup in range(BIG_NUMBER):
...     # This line is "hot", and is eventually JIT-compiled:
...     if sys._jit.is_active():
...         # This line is "cold", and is run in the interpreter:
...         assert sys._jit.is_active()
...
Traceback (most recent call last):
  File "<stdin>", line 5, in <module>
    assert sys._jit.is_active()
           ~~~~~~~~~~~~~~~~~~^^
AssertionError
@end example
@end quotation
@end cartouche
@end deffn
@end deffn

@geindex last_exc (στη μονάδα sys)
@anchor{library/sys sys last_exc}@anchor{8ce}
@deffn {Δεδομένα} 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{aa,,pdb}
module for more information.)


Added in version 3.12.

@end deffn

@geindex _is_immortal() (στη μονάδα sys)
@anchor{library/sys sys _is_immortal}@anchor{517}
@deffn {Συνάρτηση} sys._is_immortal (op)

Return @ref{fcc,,True} if the given object is @ref{398,,immortal}, @ref{ef5,,False}
otherwise.

@cartouche
@quotation Σημείωση 
Objects that are immortal (and thus return @code{True} upon being passed
to this function) are not guaranteed to be immortal in future versions,
and vice versa for mortal objects.
@end quotation
@end cartouche


Added in version 3.14.


`Λεπτομέρεια υλοποίησης CPython:' This function should be used for specialized purposes only.
It is not guaranteed to exist in all implementations of Python.
@end deffn

@geindex _is_interned() (στη μονάδα sys)
@anchor{library/sys sys _is_interned}@anchor{75a}
@deffn {Συνάρτηση} sys._is_interned (string)

Return @ref{fcc,,True} if the given string is «interned», @ref{ef5,,False}
otherwise.


Added in version 3.13.


`Λεπτομέρεια υλοποίησης CPython:' It is not guaranteed to exist in all implementations of Python.
@end deffn

@geindex last_type (στη μονάδα sys)
@geindex last_value (στη μονάδα sys)
@geindex last_traceback (στη μονάδα sys)
@anchor{library/sys sys last_type}@anchor{8cf}
@deffn {Δεδομένα} sys.last_type
@anchor{library/sys sys last_value}@anchor{8d0}
@deffnx {Δεδομένα} sys.last_value
@anchor{library/sys sys last_traceback}@anchor{8d1}
@deffnx {Δεδομένα} sys.last_traceback

These three variables are deprecated; use @ref{8ce,,sys.last_exc} instead.
They hold the legacy representation of @code{sys.last_exc}, as returned
from @ref{a7a,,exc_info()} above.
@end deffn

@geindex maxsize (στη μονάδα sys)
@anchor{library/sys sys maxsize}@anchor{156e}
@deffn {Δεδομένα} sys.maxsize

An integer giving the maximum value a variable of type @ref{e24,,Py_ssize_t} can
take.  It’s usually @code{2**31 - 1} on a 32-bit platform and @code{2**63 - 1} on a
64-bit platform.
@end deffn

@geindex maxunicode (στη μονάδα sys)
@anchor{library/sys sys maxunicode}@anchor{13f5}
@deffn {Δεδομένα} sys.maxunicode

An integer giving the value of the largest Unicode code point,
i.e. @code{1114111} (@code{0x10FFFF} in hexadecimal).


Άλλαξε στην έκδοση 3.3: Before 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/}, @code{sys.maxunicode} used to be either @code{0xFFFF}
or @code{0x10FFFF}, depending on the configuration option that specified
whether Unicode characters were stored as UCS-2 or UCS-4.

@end deffn

@geindex meta_path (στη μονάδα sys)
@anchor{library/sys sys meta_path}@anchor{10e3}
@deffn {Δεδομένα} sys.meta_path

A list of @ref{1418,,meta path finder} objects that have their
@ref{c3f,,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
@code{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{2243,,__path__}
attribute is passed in as a second argument. The method returns a
@ref{2554,,module spec}, or @code{None} if the module cannot be found.


@subsubheading Δείτε επίσης



@table @asis

@item @ref{c44,,importlib.abc.MetaPathFinder}

The abstract base class defining the interface of finder objects on
@code{meta_path}.

@item @ref{245d,,importlib.machinery.ModuleSpec}

The concrete class which
@ref{c3f,,find_spec()} should return
instances of.
@end table



Άλλαξε στην έκδοση 3.4: @ref{2554,,Module specs} were introduced in Python 3.4, by
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/}.



Άλλαξε στην έκδοση 3.12: Removed the fallback that looked for a @code{find_module()} method
if a @code{meta_path} entry didn’t have a
@ref{c3f,,find_spec()} method.

@end deffn

@geindex modules (στη μονάδα sys)
@anchor{library/sys sys modules}@anchor{19ba}
@deffn {Δεδομένα} 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 (στη μονάδα sys)
@anchor{library/sys sys orig_argv}@anchor{c19}
@deffn {Δεδομένα} sys.orig_argv

The list of the original command line arguments passed to the Python
executable.

The elements of @ref{c19,,sys.orig_argv} are the arguments to the Python interpreter,
while the elements of @ref{1609,,sys.argv} are the arguments to the user’s program.
Arguments consumed by the interpreter itself will be present in @code{sys.orig_argv}
and missing from @code{sys.argv}.


Added in version 3.10.

@end deffn

@geindex path (στη μονάδα sys)
@anchor{library/sys sys path}@anchor{194}
@deffn {Δεδομένα} sys.path

@geindex module;search;path

A list of strings that specifies the search path for modules. Initialized from
the environment variable 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH}, plus an installation-dependent
default.

By default, as initialized upon program startup, a potentially unsafe path
is prepended to @ref{194,,sys.path} (`before' the entries inserted as a result
of 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,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{9a3,,-P} command
line option or the 
@geindex PYTHONSAFEPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONSAFEPATH
@ref{9a4,,PYTHONSAFEPATH} environment variable.

A program is free to modify this list for its own purposes.  Only strings
should be added to @ref{194,,sys.path}; all other data types are
ignored during import.


@subsubheading Δείτε επίσης



@itemize *

@item 
Module @ref{cf,,site} This describes how to use .pth files to
extend @ref{194,,sys.path}.
@end itemize

@end deffn

@geindex path_hooks (στη μονάδα sys)
@anchor{library/sys sys path_hooks}@anchor{13cd}
@deffn {Δεδομένα} sys.path_hooks

A list of callables that take a path argument to try to create a
@ref{263e,,finder} for the path. If a finder can be created, it is to be
returned by the callable, else raise @ref{1bd,,ImportError}.

Originally specified in 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}.
@end deffn

@geindex path_importer_cache (στη μονάδα sys)
@anchor{library/sys sys path_importer_cache}@anchor{9db}
@deffn {Δεδομένα} sys.path_importer_cache

A dictionary acting as a cache for @ref{263e,,finder} objects. The keys are
paths that have been passed to @ref{13cd,,sys.path_hooks} and the values are
the finders that are found. If a path is a valid file system path but no
finder is found on @code{sys.path_hooks} then @code{None} is
stored.

Originally specified in 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}.
@end deffn

@geindex platform (στη μονάδα sys)
@anchor{library/sys sys platform}@anchor{518}
@deffn {Δεδομένα} sys.platform

A string containing a platform identifier. Known values are:


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

System

@tab

@code{platform} value

@item

AIX

@tab

@code{'aix'}

@item

Android

@tab

@code{'android'}

@item

Emscripten

@tab

@code{'emscripten'}

@item

FreeBSD

@tab

@code{'freebsd'}

@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'}, `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('sunos'):
    # SunOS-specific code here...
@end example


Άλλαξε στην έκδοση 3.3: On Linux, @ref{518,,sys.platform} doesn’t contain the major version anymore.
It is always @code{'linux'}, instead of @code{'linux2'} or @code{'linux3'}.



Άλλαξε στην έκδοση 3.8: On AIX, @ref{518,,sys.platform} doesn’t contain the major version anymore.
It is always @code{'aix'}, instead of @code{'aix5'} or @code{'aix7'}.



Άλλαξε στην έκδοση 3.13: On Android, @ref{518,,sys.platform} now returns @code{'android'} rather than
@code{'linux'}.



Άλλαξε στην έκδοση 3.14: On FreeBSD, @ref{518,,sys.platform} doesn’t contain the major version anymore.
It is always @code{'freebsd'}, instead of @code{'freebsd13'} or @code{'freebsd14'}.



@subsubheading Δείτε επίσης


@ref{3228,,os.name} has a coarser granularity.  @ref{14c2,,os.uname()} gives
system-dependent version information.

The @ref{af,,platform} module provides detailed checks for the
system’s identity.

@end deffn

@geindex platlibdir (στη μονάδα sys)
@anchor{library/sys sys platlibdir}@anchor{2a9}
@deffn {Δεδομένα} sys.platlibdir

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 which gives the following @code{sys.path}
paths (where @code{X.Y} is the Python @code{major.minor} version):


@itemize *

@item 
@code{/usr/lib64/pythonX.Y/}:
Standard library (like @code{os.py} of the @ref{a5,,os} module)

@item 
@code{/usr/lib64/pythonX.Y/lib-dynload/}:
C extension modules of the standard library (like the @ref{5a,,errno} module,
the exact filename is platform specific)

@item 
@code{/usr/lib/pythonX.Y/site-packages/} (always use @code{lib}, not
@ref{2a9,,sys.platlibdir}): Third-party modules

@item 
@code{/usr/lib64/pythonX.Y/site-packages/}:
C extension modules of third-party packages
@end itemize


Added in version 3.9.

@end deffn

@geindex prefix (στη μονάδα sys)
@anchor{library/sys sys prefix}@anchor{3ab}
@deffn {Δεδομένα} 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{233c,,--prefix}
argument to the @code{configure} script.  See
@ref{65c,,Installation paths} for derived paths.

@cartouche
@quotation Σημείωση 
If a @ref{3a9,,virtual environment} is in effect, this @code{prefix}
will point to the virtual environment. The value for the Python installation
will still be available, via @ref{3aa,,base_prefix}.
Refer to @ref{4b93,,Virtual Environments} for more information.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.14: When running under a @ref{3a9,,virtual environment},
@code{prefix} and @ref{3a8,,exec_prefix} are now set to the virtual
environment prefix by the @ref{1953,,path initialization},
instead of @ref{cf,,site}. This means that @code{prefix} and
@code{exec_prefix} always point to the virtual environment, even when
@code{site} is disabled (@ref{1551,,-S}).

@end deffn

@geindex ps1 (στη μονάδα sys)
@geindex ps2 (στη μονάδα sys)
@anchor{library/sys sys ps1}@anchor{2323}
@deffn {Δεδομένα} sys.ps1
@anchor{library/sys sys ps2}@anchor{2324}
@deffnx {Δεδομένα} sys.ps2

@geindex interpreter prompts
@geindex prompts@comma{} interpreter
@geindex >>>;interpreter prompt
@geindex ...;interpreter prompt

Strings specifying the primary and secondary prompt of the interpreter.  These
are only defined if the interpreter is in interactive mode.  Their initial
values in this case are @code{'>>> '} and @code{'... '}.  If a non-string object is
assigned to either variable, its @ref{1df,,str()} is re-evaluated each time the
interpreter prepares to read a new interactive command; this can be used to
implement a dynamic prompt.
@end deffn

@geindex setdlopenflags() (στη μονάδα sys)
@anchor{library/sys sys setdlopenflags}@anchor{14cb}
@deffn {Συνάρτηση} 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{a5,,os} module (@code{RTLD_@var{xxx}} constants, e.g.
@ref{14c4,,os.RTLD_LAZY}).

@ref{232d,,Διαθεσιμότητα}: Unix.
@end deffn

@geindex set_int_max_str_digits() (στη μονάδα sys)
@anchor{library/sys sys set_int_max_str_digits}@anchor{1b11}
@deffn {Συνάρτηση} sys.set_int_max_str_digits (maxdigits)

Set the @ref{9ec,,integer string conversion length limitation} used by this interpreter. See also
@ref{1a12,,get_int_max_str_digits()}.


Added in version 3.11.

@end deffn

@geindex set_lazy_imports() (στη μονάδα sys)
@anchor{library/sys sys set_lazy_imports}@anchor{17a}
@deffn {Συνάρτηση} sys.set_lazy_imports (mode)

Sets the global lazy imports mode. The `mode' parameter must be one of
the following strings:


@itemize *

@item 
@code{"normal"}: Only imports explicitly marked with the @code{lazy} keyword
are lazy

@item 
@code{"all"}: All top-level imports become potentially lazy

@item 
@code{"none"}: All lazy imports are suppressed (even explicitly marked
ones)
@end itemize

This function is intended for advanced users who need to control lazy
imports across their entire application. Library developers should
generally not use this function as it affects the runtime execution of
applications.

In addition to the mode, lazy imports can be controlled via the filter
provided by @ref{17c,,set_lazy_imports_filter()}.

See also @ref{17b,,get_lazy_imports()} and 
@geindex Python Enhancement Proposals; PEP 810
PEP 810@footnote{https://peps.python.org/pep-0810/}.


Added in version 3.15.

@end deffn

@geindex set_lazy_imports_filter() (στη μονάδα sys)
@anchor{library/sys sys set_lazy_imports_filter}@anchor{17c}
@deffn {Συνάρτηση} sys.set_lazy_imports_filter (filter)

Sets the lazy imports filter callback. The `filter' parameter must be a
callable or @code{None} to clear the filter.

The filter function is called for every potentially lazy import to
determine whether it should actually be lazy. It must have the following
signature:

@example
def filter(importing_module: str, imported_module: str,
           fromlist: tuple[str, ...] | None) -> bool
@end example

Where:


@itemize *

@item 
`importing_module' is the name of the module doing the import

@item 
`imported_module' is the resolved name of the module being imported
(for example, @code{lazy from .spam import eggs} passes
@code{package.spam})

@item 
`fromlist' is the tuple of names being imported (for @code{from ... import}
statements), or @code{None} for regular imports
@end itemize

The filter should return @code{True} to allow the import to be lazy, or
@code{False} to force an eager import.

This is an advanced feature intended for specialized users who need
fine-grained control over lazy import behavior.

See also @ref{4bfa,,get_lazy_imports_filter()} and 
@geindex Python Enhancement Proposals; PEP 810
PEP 810@footnote{https://peps.python.org/pep-0810/}.


Added in version 3.15.

@end deffn

@geindex setprofile() (στη μονάδα sys)
@anchor{library/sys sys setprofile}@anchor{18a0}
@deffn {Συνάρτηση} sys.setprofile (profilefunc)

@geindex profile function
@geindex profiler

Set the system’s profile function, which allows you to implement a Python source
code profiler in Python.  See chapter @ref{4c0a,,profile — Pure Python profiler} for more information on the
Python profiler.  The system’s profile function is called similarly to the
system’s trace function (see @ref{55c,,settrace()}), but it is called with different events,
for example it isn’t called for each executed line of code (only on call and return,
but the return event is reported even when an exception has been set). The function is
thread-specific, but there is no way for the profiler to know about context switches between
threads, so it does not make sense to use this in the presence of multiple threads. Also,
its return value is not used, so it can simply return @code{None}.  Error in the profile
function will cause itself unset.

@cartouche
@quotation Σημείωση 
The same tracing mechanism is used for @code{setprofile()} as @ref{55c,,settrace()}.
To trace calls with @code{setprofile()} inside a tracing function
(e.g. in a debugger breakpoint), see @ref{1dbd,,call_tracing()}.
@end quotation
@end cartouche

Profile functions should have three arguments: `frame', `event', and
`arg'. `frame' is the current stack frame.  `event' is a string: @code{'call'},
@code{'return'}, @code{'c_call'}, @code{'c_return'}, or @code{'c_exception'}. `arg' depends
on the event type.

The events have the following meaning:


@table @asis

@item @code{'call'}

A function is called (or some other code block entered).  The
profile function is called; `arg' is @code{None}.

@item @code{'return'}

A function (or other code block) is about to return.  The profile
function is called; `arg' is the value that will be returned, or @code{None}
if the event is caused by an exception being raised.

@item @code{'c_call'}

A C function is about to be called.  This may be an extension function or
a built-in.  `arg' is the C function object.

@item @code{'c_return'}

A C function has returned. `arg' is the C function object.

@item @code{'c_exception'}

A C function has raised an exception.  `arg' is the C function object.
@end table

Raises an @ref{1e65,,auditing event} @code{sys.setprofile} with no arguments.
@end deffn

@geindex setrecursionlimit() (στη μονάδα sys)
@anchor{library/sys sys setrecursionlimit}@anchor{8d3}
@deffn {Συνάρτηση} sys.setrecursionlimit (limit)

Set the maximum depth of the Python interpreter stack to `limit'.  This limit
prevents infinite recursion from causing an overflow of the C stack and crashing
Python.

The highest possible limit is platform-dependent.  A user may need to set the
limit higher when they have a program that requires deep recursion and a platform
that supports a higher limit.  This should be done with care, because a too-high
limit can lead to a crash.

If the new limit is too low at the current recursion depth, a
@ref{1121,,RecursionError} exception is raised.


Άλλαξε στην έκδοση 3.5.1: A @ref{1121,,RecursionError} exception is now raised if the new limit is too
low at the current recursion depth.

@end deffn

@geindex setswitchinterval() (στη μονάδα sys)
@anchor{library/sys sys setswitchinterval}@anchor{d16}
@deffn {Συνάρτηση} sys.setswitchinterval (interval)

Set the interpreter’s thread switch interval (in seconds).  This floating-point
value determines the ideal duration of the «timeslices» allocated to
concurrently running Python threads.  Please note that the actual value
can be higher, especially if long-running internal functions or methods
are used.  Also, which thread becomes scheduled at the end of the interval
is the operating system’s decision.  The interpreter doesn’t have its
own scheduler.


Added in version 3.2.

@end deffn

@geindex settrace() (στη μονάδα sys)
@anchor{library/sys sys settrace}@anchor{55c}
@deffn {Συνάρτηση} sys.settrace (tracefunc)

@geindex trace function
@geindex debugger

Set the system’s trace function, which allows you to implement a Python
source code debugger in Python.  The function is thread-specific; for a
debugger to support multiple threads, it must register a trace function using
@code{settrace()} for each thread being debugged or use @ref{c20,,threading.settrace()}.

Trace functions should have three arguments: `frame', `event', and
`arg'. `frame' is the @ref{acd,,current stack frame}. `event' is a string: @code{'call'},
@code{'line'}, @code{'return'}, @code{'exception'} or @code{'opcode'}.  `arg' depends on
the event type.

The trace function is invoked (with `event' set to @code{'call'}) whenever a new
local scope is entered; it should return a reference to a local trace
function to be used for the new scope, or @code{None} if the scope shouldn’t be
traced.

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.

If there is any error occurred in the trace function, it will be unset, just
like @code{settrace(None)} is called.

@cartouche
@quotation Σημείωση 
Tracing is disabled while calling the trace function (e.g. a function set by
@code{settrace()}). For recursive tracing see @ref{1dbd,,call_tracing()}.
@end quotation
@end cartouche

The events have the following meaning:


@table @asis

@item @code{'call'}

A function is called (or some other code block entered).  The
global trace function is called; `arg' is @code{None}; the return value
specifies the local trace function.

@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{f9b,,f_trace_lines} to @ref{ef5,,False} on that
@ref{acd,,frame}.

@item @code{'return'}

A function (or other code block) is about to return.  The local trace
function is called; `arg' is the value that will be returned, or @code{None}
if the event is caused by an exception being raised.  The trace function’s
return value is ignored.

@item @code{'exception'}

An exception has occurred.  The local trace function is called; `arg' is a
tuple @code{(exception, value, traceback)}; the return value specifies the
new local trace function.

@item @code{'opcode'}

The interpreter is about to execute a new opcode (see @ref{3b,,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{f9c,,f_trace_opcodes} to @ref{fcc,,True} on the
@ref{acd,,frame}.
@end table

Note that as an exception is propagated down the chain of callers, an
@code{'exception'} event is generated at each level.

For more fine-grained usage, it’s possible to set a trace function by
assigning @code{frame.f_trace = tracefunc} explicitly, rather than relying on
it being set indirectly via the return value from an already installed
trace function. This is also required for activating the trace function on
the current frame, which @code{settrace()} doesn’t do. Note that in order
for this to work, a global tracing function must have been installed
with @code{settrace()} in order to enable the runtime tracing machinery,
but it doesn’t need to be the same tracing function (e.g. it could be a
low overhead tracing function that simply returns @code{None} to disable
itself immediately on each frame).

For more information on code and frame objects, refer to @ref{2520,,Η τυπική ιεραρχία τύπου}.

Raises an @ref{1e65,,auditing event} @code{sys.settrace} with no arguments.

`Λεπτομέρεια υλοποίησης CPython:' The @code{settrace()} function is intended only for implementing debuggers,
profilers, coverage tools and the like.  Its behavior is part of the
implementation platform, rather than part of the language definition, and
thus may not be available in all Python implementations.


Άλλαξε στην έκδοση 3.7: @code{'opcode'} event type added; @ref{f9b,,f_trace_lines} and
@ref{f9c,,f_trace_opcodes} attributes added to frames

@end deffn

@geindex set_asyncgen_hooks() (στη μονάδα sys)
@anchor{library/sys sys set_asyncgen_hooks}@anchor{1baa}
@deffn {Συνάρτηση} sys.set_asyncgen_hooks ([firstiter] [, finalizer])

Accepts two optional keyword arguments which are callables that accept an
@ref{3b87,,asynchronous generator iterator} as an argument. The `firstiter'
callable will be called when an asynchronous generator is iterated for the
first time. The `finalizer' will be called when an asynchronous generator
is about to be garbage collected.

Raises an @ref{1e65,,auditing event} @code{sys.set_asyncgen_hooks_firstiter} with no arguments.

Raises an @ref{1e65,,auditing event} @code{sys.set_asyncgen_hooks_finalizer} with no arguments.

Two auditing events are raised because the underlying API consists of two
calls, each of which must raise its own event.


Added in version 3.6: See 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/} for more details, and for a reference example of a
`finalizer' method see the implementation of
@code{asyncio.Loop.shutdown_asyncgens} in
Lib/asyncio/base_events.py@footnote{https://github.com/python/cpython/tree/main/Lib/asyncio/base_events.py}


@cartouche
@quotation Σημείωση 
This function has been added on a provisional basis (see 
@geindex Python Enhancement Proposals; PEP 411
PEP 411@footnote{https://peps.python.org/pep-0411/}
for details.)
@end quotation
@end cartouche
@end deffn

@geindex set_coroutine_origin_tracking_depth() (στη μονάδα sys)
@anchor{library/sys sys set_coroutine_origin_tracking_depth}@anchor{f4b}
@deffn {Συνάρτηση} 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}.

To enable, pass a `depth' value greater than zero; this sets the
number of frames whose information will be captured. To disable,
set `depth' to zero.

This setting is thread-specific.


Added in version 3.7.


@cartouche
@quotation Σημείωση 
This function has been added on a provisional basis (see 
@geindex Python Enhancement Proposals; PEP 411
PEP 411@footnote{https://peps.python.org/pep-0411/}
for details.)  Use it only for debugging purposes.
@end quotation
@end cartouche
@end deffn

@geindex activate_stack_trampoline() (στη μονάδα sys)
@anchor{library/sys sys activate_stack_trampoline}@anchor{885}
@deffn {Συνάρτηση} sys.activate_stack_trampoline (backend, /)

Activate the stack profiler trampoline `backend'.
The only supported backend is @code{"perf"}.

Stack trampolines cannot be activated if the JIT is active.

@ref{232d,,Διαθεσιμότητα}: Linux.


Added in version 3.12.



@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{6b7,,Python support for the perf map compatible profilers}

@item 
@indicateurl{https://perf.wiki.kernel.org}
@end itemize

@end deffn

@geindex deactivate_stack_trampoline() (στη μονάδα sys)
@anchor{library/sys sys deactivate_stack_trampoline}@anchor{886}
@deffn {Συνάρτηση} sys.deactivate_stack_trampoline ()

Deactivate the current stack profiler trampoline backend.

If no stack profiler is activated, this function has no effect.

@ref{232d,,Διαθεσιμότητα}: Linux.


Added in version 3.12.

@end deffn

@geindex is_stack_trampoline_active() (στη μονάδα sys)
@anchor{library/sys sys is_stack_trampoline_active}@anchor{887}
@deffn {Συνάρτηση} sys.is_stack_trampoline_active ()

Return @code{True} if a stack profiler trampoline is active.

@ref{232d,,Διαθεσιμότητα}: Linux.


Added in version 3.12.

@end deffn

@geindex remote_exec() (στη μονάδα sys)
@anchor{library/sys sys remote_exec}@anchor{418}
@deffn {Συνάρτηση} sys.remote_exec (pid, script)

Executes `script', a file containing Python code in the remote
process with the given `pid'.

This function returns immediately, and the code will be executed by the
target process’s main thread at the next available opportunity, similarly
to how signals are handled. There is no interface to determine when the
code has been executed. The caller is responsible for making sure that
the file still exists whenever the remote process tries to read it and that
it hasn’t been overwritten.

The remote process must be running a CPython interpreter of the same major
and minor version as the local process. If either the local or remote
interpreter is pre-release (alpha, beta, or release candidate) then the
local and remote interpreters must be the same exact version.

See @ref{4c0b,,Remote debugging attachment protocol} for more information about the remote debugging
mechanism.


When the code is executed in the remote process, an
@ref{1e65,,auditing event} @code{sys.remote_exec} is raised with
the `pid' and the path to the script file.
This event is raised in the process that called @ref{418,,sys.remote_exec()}.



When the script is executed in the remote process, an
@ref{1e65,,auditing event}
@code{cpython.remote_debugger_script} is raised
with the path in the remote process.
This event is raised in the remote process, not the one
that called @ref{418,,sys.remote_exec()}.


@ref{232d,,Διαθεσιμότητα}: Unix, Windows.


Added in version 3.14: See 
@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/} for more details.

@end deffn

@geindex _enablelegacywindowsfsencoding() (στη μονάδα sys)
@anchor{library/sys sys _enablelegacywindowsfsencoding}@anchor{30e}
@deffn {Συνάρτηση} sys._enablelegacywindowsfsencoding ()

Changes the @ref{948,,filesystem encoding and error handler} to “mbcs” and
“replace” respectively, for consistency with versions of Python prior to
3.6.

This is equivalent to defining the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,PYTHONLEGACYWINDOWSFSENCODING}
environment variable before launching Python.

See also @ref{1017,,sys.getfilesystemencoding()} and
@ref{10a3,,sys.getfilesystemencodeerrors()}.

@ref{232d,,Διαθεσιμότητα}: Windows.

@cartouche
@quotation Σημείωση 
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 μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,PYTHONLEGACYWINDOWSFSENCODING} instead.
@end quotation
@end cartouche


Added in version 3.6: See 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} for more details.



Καταργήθηκε από την έκδοση 3.13, αφαιρέθηκε στην έκδοση 3.16: Use 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,PYTHONLEGACYWINDOWSFSENCODING} instead.

@end deffn

@geindex stdin (στη μονάδα sys)
@geindex stdout (στη μονάδα sys)
@geindex stderr (στη μονάδα sys)
@anchor{library/sys sys stdin}@anchor{94a}
@deffn {Δεδομένα} sys.stdin
@anchor{library/sys sys stdout}@anchor{e9c}
@deffnx {Δεδομένα} sys.stdout
@anchor{library/sys sys stderr}@anchor{d05}
@deffnx {Δεδομένα} sys.stderr

@ref{156c,,File objects} used by the interpreter for standard
input, output and errors:


@itemize *

@item 
@code{stdin} is used for all interactive input (including calls to
@ref{167d,,input()});

@item 
@code{stdout} is used for the output of @ref{131f,,print()} and @ref{25c4,,expression}
statements and for the prompts of @ref{167d,,input()};

@item 
The interpreter’s own prompts and its error messages go to @code{stderr}.
@end itemize

These streams are regular @ref{225c,,text files} like those
returned by the @ref{32b,,open()} function.  Their parameters are chosen as
follows:


@itemize *

@item 
The encoding and error handling are is initialized from
@ref{835,,PyConfig.stdio_encoding} and @ref{4c0c,,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{74d,,locale encoding} if the process is not initially attached
to a console.

The special behaviour of the console can be overridden
by setting the environment variable PYTHONLEGACYWINDOWSSTDIO
before starting Python. In that case, the console codepages are
used as for any other character device.

Under all platforms, you can override the character encoding by
setting the 
@geindex PYTHONIOENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONIOENCODING
@ref{13b3,,PYTHONIOENCODING} environment variable before
starting Python or by using the new @ref{178,,-X} @code{utf8} command
line option and 
@geindex PYTHONUTF8
@geindex μεταβλητή περιβάλλοντος; PYTHONUTF8
@ref{1ad,,PYTHONUTF8} environment variable.  However,
for the Windows console, this only applies when
@geindex PYTHONLEGACYWINDOWSSTDIO
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSSTDIO
@ref{1019,,PYTHONLEGACYWINDOWSSTDIO} is also set.

@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{1f7f,,-u} command-line option or setting the
@geindex PYTHONUNBUFFERED
@geindex μεταβλητή περιβάλλοντος; PYTHONUNBUFFERED
@ref{1f80,,PYTHONUNBUFFERED} environment variable.
@end itemize


Άλλαξε στην έκδοση 3.9: Non-interactive @code{stderr} is now line-buffered instead of fully
buffered.


@cartouche
@quotation Σημείωση 
To write or read binary data from/to the standard streams, use the
underlying binary @ref{1648,,buffer} object.  For example, to
write bytes to @code{stdout}, use @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{12d4,,io.StringIO} which
do not support the @code{buffer} attribute.
@end quotation
@end cartouche
@end deffn

@geindex __stdin__ (στη μονάδα sys)
@geindex __stdout__ (στη μονάδα sys)
@geindex __stderr__ (στη μονάδα sys)
@anchor{library/sys sys __stdin__}@anchor{4c0d}
@deffn {Δεδομένα} sys.__stdin__
@anchor{library/sys sys __stdout__}@anchor{2f20}
@deffnx {Δεδομένα} sys.__stdout__
@anchor{library/sys sys __stderr__}@anchor{492a}
@deffnx {Δεδομένα} sys.__stderr__

These objects contain the original values of @code{stdin}, @code{stderr} and
@code{stdout} at the start of the program.  They are used during finalization,
and could be useful to print to the actual standard stream no matter if the
@code{sys.std*} object has been redirected.

It can also be used to restore the actual files to known working file objects
in case they have been overwritten with a broken object.  However, the
preferred way to do this is to explicitly save the previous stream before
replacing it, and restore the saved object.

@cartouche
@quotation Σημείωση 
Under some conditions @code{stdin}, @code{stdout} and @code{stderr} as well as the
original values @code{__stdin__}, @code{__stdout__} and @code{__stderr__} can be
@code{None}. It is usually the case for Windows GUI apps that aren’t connected
to a console and Python apps started with @code{pythonw}.
@end quotation
@end cartouche
@end deffn

@geindex stdlib_module_names (στη μονάδα sys)
@anchor{library/sys sys stdlib_module_names}@anchor{c1a}
@deffn {Δεδομένα} 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{2236,,sys.builtin_module_names} list.


Added in version 3.10.

@end deffn

@geindex thread_info (στη μονάδα sys)
@anchor{library/sys sys thread_info}@anchor{14fb}
@deffn {Δεδομένα} sys.thread_info

A @ref{a3d,,named tuple} holding information about the thread
implementation.

@geindex name (ιδιότητα της sys.thread_info)
@anchor{library/sys sys thread_info name}@anchor{4c0e}
@deffn {Ιδιότητα} 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 (ιδιότητα της sys.thread_info)
@anchor{library/sys sys thread_info lock}@anchor{4c0f}
@deffn {Ιδιότητα} 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} if this information is unknown
@end itemize
@end deffn

@geindex version (ιδιότητα της sys.thread_info)
@anchor{library/sys sys thread_info version}@anchor{4c10}
@deffn {Ιδιότητα} 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


Added in version 3.3.

@end deffn

@geindex tracebacklimit (στη μονάδα sys)
@anchor{library/sys sys tracebacklimit}@anchor{1b5c}
@deffn {Δεδομένα} sys.tracebacklimit

When this variable is set to an integer value, it determines the maximum number
of levels of traceback information printed when an unhandled exception occurs.
The default is @code{1000}.  When set to @code{0} or less, all traceback information
is suppressed and only the exception type and value are printed.
@end deffn

@geindex unraisablehook() (στη μονάδα sys)
@anchor{library/sys sys unraisablehook}@anchor{70c}
@deffn {Συνάρτηση} sys.unraisablehook (unraisable, /)

Handle an unraisable exception.

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{44f,,gc.collect()}).

The `unraisable' argument has the following attributes:


@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}. Similar to the @ref{107,,traceback} module,
this adds color to exceptions by default. This can be disabled using
@ref{1af,,environment variables}.

@ref{70c,,sys.unraisablehook()} can be overridden to control how unraisable
exceptions are handled.


Άλλαξε στην έκδοση 3.15: Exceptions are now printed with colorful text.



@subsubheading Δείτε επίσης


@ref{be5,,excepthook()} which handles uncaught exceptions.


@cartouche
@quotation Προειδοποίηση 
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}.



Added in version 3.8.

@end deffn

@geindex version (στη μονάδα sys)
@anchor{library/sys sys version}@anchor{6a8}
@deffn {Δεδομένα} sys.version

A string containing the version number of the Python interpreter plus additional
information on the build number and compiler used.  This string is displayed
when the interactive interpreter is started.  Do not extract version information
out of it, rather, use @ref{2fc,,version_info} and the functions provided by the
@ref{af,,platform} module.
@end deffn

@geindex api_version (στη μονάδα sys)
@anchor{library/sys sys api_version}@anchor{4c11}
@deffn {Δεδομένα} sys.api_version

The C API version, equivalent to the C macro @ref{4c12,,PYTHON_API_VERSION}.
Defined for backwards compatibility.

Currently, this constant is not updated in new Python versions, and is not
useful for versioning. This may change in the future.
@end deffn

@geindex version_info (στη μονάδα sys)
@anchor{library/sys sys version_info}@anchor{2fc}
@deffn {Δεδομένα} sys.version_info

A tuple containing the five components of the version number: `major', `minor',
`micro', `releaselevel', and `serial'.  All values except `releaselevel' are
integers; the release level is @code{'alpha'}, @code{'beta'}, @code{'candidate'}, or
@code{'final'}.  The @code{version_info} value corresponding to the Python version 2.0
is @code{(2, 0, 0, 'final', 0)}.  The components can also be accessed by name,
so @code{sys.version_info[0]} is equivalent to @code{sys.version_info.major}
and so on.


Άλλαξε στην έκδοση 3.1: Added named component attributes.

@end deffn

@geindex warnoptions (στη μονάδα sys)
@anchor{library/sys sys warnoptions}@anchor{3a5}
@deffn {Δεδομένα} sys.warnoptions

This is an implementation detail of the warnings framework; do not modify this
value.  Refer to the @ref{11b,,warnings} module for more information on the warnings
framework.
@end deffn

@geindex winver (στη μονάδα sys)
@anchor{library/sys sys winver}@anchor{4c13}
@deffn {Δεδομένα} 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 @code{sys}
module for informational purposes; modifying this value has no effect on the
registry keys used by Python.

@ref{232d,,Διαθεσιμότητα}: Windows.
@end deffn


@deffn {Δεδομένα} sys.monitoring

Namespace containing functions and constants for register callbacks
and controlling monitoring events.
See  @ref{e3,,sys.monitoring} for details.
@end deffn

@geindex _xoptions (στη μονάδα sys)
@anchor{library/sys sys _xoptions}@anchor{231f}
@deffn {Δεδομένα} sys._xoptions

A dictionary of the various implementation-specific flags passed through
the @ref{178,,-X} command-line option.  Option names are either mapped to
their values, if given explicitly, or to @ref{fcc,,True}.  Example:

@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

`Λεπτομέρεια υλοποίησης CPython:' This is a CPython-specific way of accessing options passed through
@ref{178,,-X}.  Other implementations may export them through other
means, or not at all.


Added in version 3.2.

@end deffn

@subsubheading Citations


@anchor{library/sys c99}@anchor{4bed}@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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node sys monitoring — Execution event monitoring,sysconfig — Provide access to Python’s configuration information,sys — System-specific parameters and functions,Python Runtime Services
@anchor{library/sys monitoring doc}@anchor{4c14}@anchor{library/sys monitoring module-sys monitoring}@anchor{e3}@anchor{library/sys monitoring sys-monitoring-execution-event-monitoring}@anchor{4c15}@anchor{library/sys monitoring translation-repo}@anchor{4c16}
@subsection @code{sys.monitoring} — Execution event monitoring


@geindex module; sys.monitoring


Added in version 3.12.



__________________________________________________________________


@cartouche
@quotation Σημείωση 
@code{sys.monitoring} is a namespace within the @ref{e2,,sys} module,
not an independent module, and @code{import sys.monitoring} would fail
with a @ref{1be,,ModuleNotFoundError}. Instead, 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 @code{sys.monitoring} namespace provides means to
receive callbacks when events of interest occur.

The monitoring API consists of three components:


@itemize *

@item 
@ref{4c17,,Tool identifiers}

@item 
@ref{4c18,,Events}

@item 
@ref{4c19,,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{4c17}
@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{4c1a}
@subsubsection Registering and using tools


@geindex use_tool_id() (στη μονάδα sys.monitoring)
@anchor{library/sys monitoring sys monitoring use_tool_id}@anchor{4c1b}
@deffn {Συνάρτηση} 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{277,,ValueError} if `tool_id' is in use.
@end deffn

@geindex clear_tool_id() (στη μονάδα sys.monitoring)
@anchor{library/sys monitoring sys monitoring clear_tool_id}@anchor{1b49}
@deffn {Συνάρτηση} sys.monitoring.clear_tool_id (tool_id: int, /) -> None

Unregister all events and callback functions associated with `tool_id'.
@end deffn

@geindex free_tool_id() (στη μονάδα sys.monitoring)
@anchor{library/sys monitoring sys monitoring free_tool_id}@anchor{4c1c}
@deffn {Συνάρτηση} sys.monitoring.free_tool_id (tool_id: int, /) -> None

Should be called once a tool no longer requires `tool_id'.
Will call @ref{1b49,,clear_tool_id()} before releasing `tool_id'.
@end deffn

@geindex get_tool() (στη μονάδα sys.monitoring)
@anchor{library/sys monitoring sys monitoring get_tool}@anchor{4c1d}
@deffn {Συνάρτηση} 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{4c18}
@subsubsection Events


The following events are supported:

@geindex BRANCH_LEFT (monitoring event)
@anchor{library/sys monitoring monitoring-event-BRANCH_LEFT}@anchor{51b}
@deffn {monitoring-event} sys.monitoring.events.BRANCH_LEFT

A conditional branch goes left.

It is up to the tool to determine how to present «left» and «right» branches.
There is no guarantee which branch is «left» and which is «right», except
that it will be consistent for the duration of the program.
@end deffn

@geindex BRANCH_RIGHT (monitoring event)
@anchor{library/sys monitoring monitoring-event-BRANCH_RIGHT}@anchor{51c}
@deffn {monitoring-event} sys.monitoring.events.BRANCH_RIGHT

A conditional branch goes right.
@end deffn

@geindex CALL (monitoring event)
@anchor{library/sys monitoring monitoring-event-CALL}@anchor{1bc7}
@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{4c1e}
@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{4c1f}
@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{274}
@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{4c20}
@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{4c21}
@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{4c22}
@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{4c23}
@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{4c24}
@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{4c25}
@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{271}
@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{272}
@deffn {monitoring-event} sys.monitoring.events.PY_UNWIND

Exit from a Python function during exception unwinding. This includes exceptions raised directly within the
function and that are allowed to continue to propagate.
@end deffn

@geindex PY_YIELD (monitoring event)
@anchor{library/sys monitoring monitoring-event-PY_YIELD}@anchor{4c26}
@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{273}
@deffn {monitoring-event} sys.monitoring.events.RAISE

An exception is raised, except those that cause a @ref{4c27,,STOP_ITERATION} event.
@end deffn

@geindex RERAISE (monitoring event)
@anchor{library/sys monitoring monitoring-event-RERAISE}@anchor{275}
@deffn {monitoring-event} sys.monitoring.events.RERAISE

An exception is re-raised, for example at the end of a @ref{44c,,finally} block.
@end deffn

@geindex STOP_ITERATION (monitoring event)
@anchor{library/sys monitoring monitoring-event-STOP_ITERATION}@anchor{4c27}
@deffn {monitoring-event} sys.monitoring.events.STOP_ITERATION

An artificial @ref{fba,,StopIteration} is raised; see @ref{4c28,,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{4c24,,PY_RETURN} and @ref{4c25,,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{4c29}
@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

Setting this event deactivates all events.
@end deffn

@menu
* Local events:: 
* Deprecated event:: 
* Ancillary events:: 
* Other events:: 
* The STOP_ITERATION event:: 

@end menu

@node Local events,Deprecated event,,Events
@anchor{library/sys monitoring local-events}@anchor{4c2a}@anchor{library/sys monitoring monitoring-event-local}@anchor{4c2b}
@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
per location. The local events are:


@itemize *

@item 
@ref{4c25,,PY_START}

@item 
@ref{4c23,,PY_RESUME}

@item 
@ref{4c24,,PY_RETURN}

@item 
@ref{4c26,,PY_YIELD}

@item 
@ref{1bc7,,CALL}

@item 
@ref{4c22,,LINE}

@item 
@ref{4c20,,INSTRUCTION}

@item 
@ref{4c21,,JUMP}

@item 
@ref{51b,,BRANCH_LEFT}

@item 
@ref{51c,,BRANCH_RIGHT}

@item 
@ref{4c27,,STOP_ITERATION}
@end itemize

@node Deprecated event,Ancillary events,Local events,Events
@anchor{library/sys monitoring deprecated-event}@anchor{4c2c}
@subsubsection Deprecated event



@itemize *

@item 
@code{BRANCH}
@end itemize

The @code{BRANCH} event is deprecated in 3.14.
Using @ref{51b,,BRANCH_LEFT} and @ref{51c,,BRANCH_RIGHT}
events will give much better performance as they can be disabled
independently.

@node Ancillary events,Other events,Deprecated event,Events
@anchor{library/sys monitoring ancillary-events}@anchor{4c2d}@anchor{library/sys monitoring monitoring-ancillary-events}@anchor{4c2e}
@subsubsection Ancillary events


Ancillary events can be monitored like other events, but are controlled
by another event:


@itemize *

@item 
@ref{4c1e,,C_RAISE}

@item 
@ref{4c1f,,C_RETURN}
@end itemize

The @ref{4c1f,,C_RETURN} and @ref{4c1e,,C_RAISE} events
are controlled by the @ref{1bc7,,CALL} event.
@code{C_RETURN} and @code{C_RAISE} events will only be
seen if the corresponding @code{CALL} event is being monitored.

@node Other events,The STOP_ITERATION event,Ancillary events,Events
@anchor{library/sys monitoring monitoring-event-global}@anchor{270}@anchor{library/sys monitoring other-events}@anchor{4c2f}
@subsubsection Other events


Other events are not necessarily tied to a specific location in the
program and cannot be individually disabled per location.

The other events that can be monitored are:


@itemize *

@item 
@ref{271,,PY_THROW}

@item 
@ref{272,,PY_UNWIND}

@item 
@ref{273,,RAISE}

@item 
@ref{274,,EXCEPTION_HANDLED}

@item 
@ref{275,,RERAISE}
@end itemize


Άλλαξε στην έκδοση 3.15: Other events can now be turned on and disabled on a per code object
basis. Returning @ref{276,,DISABLE} from a callback disables the event
for the entire code object (for the current tool).


@node The STOP_ITERATION event,,Other events,Events
@anchor{library/sys monitoring the-stop-iteration-event}@anchor{4c28}
@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{fba,,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{4c27,,STOP_ITERATION} event is provided.
@code{STOP_ITERATION} can be locally disabled.

Note that the @ref{4c27,,STOP_ITERATION} event and the
@ref{273,,RAISE} event for a @ref{fba,,StopIteration} exception are
equivalent, and are treated as interchangeable when generating events.
Implementations will favor @code{STOP_ITERATION} for performance
reasons, but may generate a @code{RAISE} event with a
@code{StopIteration}.

@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{4c30}
@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 and/or for a particular code object. An event will trigger only once,
even if it is turned on both globally and locally.

@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{4c31}
@subsubsection Setting events globally


Events can be controlled globally by modifying the set of events being monitored.

@geindex get_events() (στη μονάδα sys.monitoring)
@anchor{library/sys monitoring sys monitoring get_events}@anchor{4c32}
@deffn {Συνάρτηση} sys.monitoring.get_events (tool_id: int, /) -> int

Returns the @code{int} representing all the active events.
@end deffn

@geindex set_events() (στη μονάδα sys.monitoring)
@anchor{library/sys monitoring sys monitoring set_events}@anchor{4c33}
@deffn {Συνάρτηση} sys.monitoring.set_events (tool_id: int, event_set: int, /) -> None

Activates all events which are set in `event_set'.
Raises a @ref{277,,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{4c34}
@subsubsection Per code object events


Events can also be controlled on a per code object basis. The functions
defined below which accept a @ref{2e1,,types.CodeType} should be prepared
to accept a look-alike object from functions which are not defined
in Python (see @ref{694,,Monitoring C API}).

@geindex get_local_events() (στη μονάδα sys.monitoring)
@anchor{library/sys monitoring sys monitoring get_local_events}@anchor{4c35}
@deffn {Συνάρτηση} sys.monitoring.get_local_events (tool_id: int, code: CodeType, /) -> int

Returns all the @ref{4c2b,,local events} for `code'
@end deffn

@geindex set_local_events() (στη μονάδα sys.monitoring)
@anchor{library/sys monitoring sys monitoring set_local_events}@anchor{4c36}
@deffn {Συνάρτηση} sys.monitoring.set_local_events (tool_id: int, code: CodeType, event_set: int, /) -> None

Activates all the @ref{4c2b,,local events} for `code'
which are set in `event_set'. Raises a @ref{277,,ValueError} if `tool_id' is not
in use.
@end deffn

@node Disabling events,,Per code object events,Turning events on and off
@anchor{library/sys monitoring disabling-events}@anchor{4c37}
@subsubsection Disabling events


@geindex DISABLE (στη μονάδα sys.monitoring)
@anchor{library/sys monitoring sys monitoring DISABLE}@anchor{276}
@deffn {Δεδομένα} sys.monitoring.DISABLE

A special value that can be returned from a callback function to disable
events for the current code location.
@end deffn

@ref{4c2b,,Local events} can be disabled for a specific code
location by returning @ref{276,,sys.monitoring.DISABLE} from a callback function.
This does not change which events are set, or any other code locations for the
same event.

@ref{270,,Other events} can be disabled on a per code
object basis by returning @ref{276,,sys.monitoring.DISABLE} from a callback
function. This disables the event for the entire code object (for the current
tool).

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() (στη μονάδα sys.monitoring)
@anchor{library/sys monitoring sys monitoring restart_events}@anchor{4c38}
@deffn {Συνάρτηση} sys.monitoring.restart_events () -> None

Enable all the events that were disabled by @ref{276,,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{4c19}@anchor{library/sys monitoring registering-callback-functions}@anchor{4c39}
@subsubsection Registering callback functions


@geindex register_callback() (στη μονάδα sys.monitoring)
@anchor{library/sys monitoring sys monitoring register_callback}@anchor{49b7}
@deffn {Συνάρτηση} 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 @code{register_callback()} returns @code{None}.

Raises an @ref{1e65,,auditing event} @code{sys.monitoring.register_callback} with argument @code{func}.
@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.

Callbacks are called only once regardless if the event is turned on both
globally and locally. As such, if an event could be turned on for both global
and local events by your code then the callback needs to be written to handle
either trigger.

@menu
* Callback function arguments:: 

@end menu

@node Callback function arguments,,,Registering callback functions
@anchor{library/sys monitoring callback-function-arguments}@anchor{4c3a}
@subsubsection Callback function arguments


@geindex MISSING (στη μονάδα sys.monitoring)
@anchor{library/sys monitoring sys monitoring MISSING}@anchor{4c3b}
@deffn {Δεδομένα} 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.
Callback functions returning an object other than @ref{276,,DISABLE} will have no effect.
Different events will provide the callback function with different arguments, as follows:


@itemize *

@item 
@ref{4c25,,PY_START} and @ref{4c23,,PY_RESUME}:

@example
func(code: CodeType, instruction_offset: int) -> object
@end example

@item 
@ref{4c24,,PY_RETURN} and @ref{4c26,,PY_YIELD}:

@example
func(code: CodeType, instruction_offset: int, retval: object) -> object
@end example

@item 
@ref{1bc7,,CALL}, @ref{4c1e,,C_RAISE} and @ref{4c1f,,C_RETURN}
(`arg0' can be @ref{4c3b,,MISSING} specifically):

@example
func(code: CodeType, instruction_offset: int, callable: object, arg0: object) -> object
@end example

`code' represents the code object where the call is being made, while
`callable' is the object that is about to be called (and thus
triggered the event).
If there are no arguments, `arg0' is set to @ref{4c3b,,sys.monitoring.MISSING}.

For instance methods, `callable' will be the function object as found on the
class with `arg0' set to the instance (i.e. the @code{self} argument to the
method).

@item 
@ref{273,,RAISE}, @ref{275,,RERAISE}, @ref{274,,EXCEPTION_HANDLED},
@ref{272,,PY_UNWIND}, @ref{271,,PY_THROW} and @ref{4c27,,STOP_ITERATION}:

@example
func(code: CodeType, instruction_offset: int, exception: BaseException) -> object
@end example

@item 
@ref{4c22,,LINE}:

@example
func(code: CodeType, line_number: int) -> object
@end example

@item 
@ref{51b,,BRANCH_LEFT}, @ref{51c,,BRANCH_RIGHT} and @ref{4c21,,JUMP}:

@example
func(code: CodeType, instruction_offset: int, destination_offset: int) -> object
@end example

Note that the `destination_offset' is where the code will next execute.

@item 
@ref{4c20,,INSTRUCTION}:

@example
func(code: CodeType, instruction_offset: int) -> object
@end example
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node sysconfig — Provide access to Python’s configuration information,builtins — Built-in objects,sys monitoring — Execution event monitoring,Python Runtime Services
@anchor{library/sysconfig doc}@anchor{4c3c}@anchor{library/sysconfig module-sysconfig}@anchor{e4}@anchor{library/sysconfig sysconfig-provide-access-to-python-s-configuration-information}@anchor{4c3d}@anchor{library/sysconfig translation-repo}@anchor{4c3e}
@subsection @code{sysconfig} — Provide access to Python’s configuration information


@geindex module; sysconfig


Added in version 3.2.


`Source code:' Lib/sysconfig@footnote{https://github.com/python/cpython/tree/main/Lib/sysconfig}

@geindex configuration information


__________________________________________________________________


The @code{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:: 
* Other functions: Other functions<3>. 
* Command-line usage: Command-line usage<4>. 

@end menu

@node Configuration variables,Installation paths,,sysconfig — Provide access to Python’s configuration information
@anchor{library/sysconfig configuration-variables}@anchor{4c3f}
@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}.

@code{sysconfig} puts all variables found in these files in a dictionary that
can be accessed using @ref{51e,,get_config_vars()} or @ref{41e,,get_config_var()}.

Notice that on Windows, it’s a much smaller set.

@geindex get_config_vars() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig get_config_vars}@anchor{51e}
@deffn {Συνάρτηση} 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() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig get_config_var}@anchor{41e}
@deffn {Συνάρτηση} 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{4c40}@anchor{library/sysconfig installation-paths}@anchor{65c}
@subsubsection Installation paths


Python uses an installation scheme that differs depending on the platform and on
the installation options.  These schemes are stored in @code{sysconfig} under
unique identifiers based on the value returned by @ref{3228,,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{16c1,,site.USER_BASE}).

@item 
`posix_venv': scheme for @ref{11a,,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{11a,,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{2325}@anchor{library/sysconfig user-scheme}@anchor{4c41}
@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{16c1,,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{2315,,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{4c42}
@subsubsection @code{posix_user}



@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Path

@tab

Installation directory

@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

`data'

@tab

@code{`userbase'}

@end multitable


@node nt_user,osx_framework_user,posix_user,User scheme
@anchor{library/sysconfig nt-user}@anchor{4c43}
@subsubsection @code{nt_user}



@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Path

@tab

Installation directory

@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

`data'

@tab

@code{`userbase'}

@end multitable


@node osx_framework_user,,nt_user,User scheme
@anchor{library/sysconfig osx-framework-user}@anchor{4c44}
@subsubsection @code{osx_framework_user}



@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Path

@tab

Installation directory

@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

`data'

@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{4c45}@anchor{library/sysconfig sysconfig-home-scheme}@anchor{4c46}
@subsubsection Home scheme


The idea behind the «home scheme» is that you build and maintain a personal
stash of Python modules.  This scheme’s name is derived from the idea of a
«home» directory on Unix, since it’s not unusual for a Unix user to make their
home directory have a layout similar to @code{/usr/} or @code{/usr/local/}.
This scheme can be used by anyone, regardless of the operating system they
are installing for.

@menu
* posix_home:: 

@end menu

@node posix_home,,,Home scheme
@anchor{library/sysconfig posix-home}@anchor{4c47}
@subsubsection @code{posix_home}



@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Path

@tab

Installation directory

@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

`data'

@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{4c48}@anchor{library/sysconfig sysconfig-prefix-scheme}@anchor{4c49}
@subsubsection Prefix scheme


The «prefix scheme» is useful when you wish to use one Python installation to
perform the build/install (i.e., to run the setup script), but install modules
into the third-party module directory of a different Python installation (or
something that looks like a different Python installation).  If this sounds a
trifle unusual, it is—that’s why the user and home schemes come before.  However,
there are at least two known cases where the prefix scheme will be useful.

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{4c4a}
@subsubsection @code{posix_prefix}



@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Path

@tab

Installation directory

@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

`data'

@tab

@code{`prefix'}

@end multitable


@node nt,,posix_prefix,Prefix scheme
@anchor{library/sysconfig nt}@anchor{4c4b}
@subsubsection @code{nt}



@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Path

@tab

Installation directory

@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

`data'

@tab

@code{`prefix'}

@end multitable


@node Installation path functions,Other functions<3>,Prefix scheme,sysconfig — Provide access to Python’s configuration information
@anchor{library/sysconfig installation-path-functions}@anchor{4c4c}
@subsubsection Installation path functions


@code{sysconfig} provides some functions to determine these installation paths.

@geindex get_scheme_names() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig get_scheme_names}@anchor{4c4d}
@deffn {Συνάρτηση} sysconfig.get_scheme_names ()

Return a tuple containing all schemes currently supported in
@code{sysconfig}.
@end deffn

@geindex get_default_scheme() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig get_default_scheme}@anchor{1daf}
@deffn {Συνάρτηση} sysconfig.get_default_scheme ()

Return the default scheme name for the current platform.


Added in version 3.10: This function was previously named @code{_get_default_scheme()} and
considered an implementation detail.



Άλλαξε στην έκδοση 3.11: When Python runs from a virtual environment,
the `venv' scheme is returned.

@end deffn

@geindex get_preferred_scheme() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig get_preferred_scheme}@anchor{a7f}
@deffn {Συνάρτηση} 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{4c4d,,get_scheme_names()}. It
can be passed to @code{sysconfig} functions that take a `scheme' argument,
such as @ref{156,,get_paths()}.


Added in version 3.10.



Άλλαξε στην έκδοση 3.11: When Python runs from a virtual environment and @code{key="prefix"},
the `venv' scheme is returned.

@end deffn

@geindex _get_preferred_schemes() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig _get_preferred_schemes}@anchor{4c4e}
@deffn {Συνάρτηση} 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{1daf,,get_default_scheme()} and
@ref{a7f,,get_preferred_scheme()} instead.


Added in version 3.10.

@end deffn

@geindex get_path_names() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig get_path_names}@anchor{4c4f}
@deffn {Συνάρτηση} sysconfig.get_path_names ()

Return a tuple containing all path names currently supported in
@code{sysconfig}.
@end deffn

@geindex get_path() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig get_path}@anchor{16d2}
@deffn {Συνάρτηση} 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{4c4f,,get_path_names()}.

@code{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}.

@code{get_path()} will use the variables returned by @ref{51e,,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{4c4d,,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{51e,,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{7df,,KeyError}.
@end deffn

@geindex get_paths() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig get_paths}@anchor{156}
@deffn {Συνάρτηση} sysconfig.get_paths ([scheme[, vars[, expand]]])

Return a dictionary containing all installation paths corresponding to an
installation scheme. See @ref{16d2,,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, @code{get_paths()} will raise a
@ref{7df,,KeyError}.
@end deffn

@node Other functions<3>,Command-line usage<4>,Installation path functions,sysconfig — Provide access to Python’s configuration information
@anchor{library/sysconfig other-functions}@anchor{4c50}
@subsubsection Other functions


@geindex get_python_version() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig get_python_version}@anchor{15e9}
@deffn {Συνάρτηση} 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() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig get_platform}@anchor{15e8}
@deffn {Συνάρτηση} 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{14c2,,os.uname()}), although the
exact information included depends on the OS; e.g., on Linux, the kernel
version isn’t particularly important.

Examples of returned values:


@itemize -

@item 
linux-x86_64

@item 
linux-aarch64

@item 
solaris-2.6-sun4u
@end itemize

Windows:


@itemize -

@item 
win-amd64 (64-bit Windows on AMD64, aka x86_64, Intel64, and EM64T)

@item 
win-arm64 (64-bit Windows on ARM64, aka AArch64)

@item 
win32 (all others - specifically, sys.platform is returned)
@end itemize

POSIX based OS:


@itemize -

@item 
linux-x86_64

@item 
macosx-15.5-arm64

@item 
macosx-26.0-universal2 (macOS on Apple Silicon or Intel)

@item 
android-24-arm64_v8a
@end itemize

For other non-POSIX platforms, currently just returns @ref{518,,sys.platform}.
@end deffn

@geindex is_python_build() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig is_python_build}@anchor{2dd}
@deffn {Συνάρτηση} 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() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig parse_config_h}@anchor{4c51}
@deffn {Συνάρτηση} 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() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig get_config_h_filename}@anchor{4c52}
@deffn {Συνάρτηση} sysconfig.get_config_h_filename ()

Return the path of @code{pyconfig.h}.
@end deffn

@geindex get_makefile_filename() (στη μονάδα sysconfig)
@anchor{library/sysconfig sysconfig get_makefile_filename}@anchor{4c53}
@deffn {Συνάρτηση} sysconfig.get_makefile_filename ()

Return the path of @code{Makefile}.
@end deffn
@anchor{library/sysconfig sysconfig-cli}@anchor{4c54}
@node Command-line usage<4>,,Other functions<3>,sysconfig — Provide access to Python’s configuration information
@anchor{library/sysconfig command-line-usage}@anchor{4c55}@anchor{library/sysconfig using-sysconfig-as-a-script}@anchor{4c56}
@subsubsection Command-line usage


You can use @code{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{15e8,,get_platform()}, @ref{15e9,,get_python_version()}, @ref{16d2,,get_path()} and
@ref{51e,,get_config_vars()}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node builtins — Built-in objects,__main__ — Top-level code environment,sysconfig — Provide access to Python’s configuration information,Python Runtime Services
@anchor{library/builtins doc}@anchor{4c57}@anchor{library/builtins builtins-built-in-objects}@anchor{4c58}@anchor{library/builtins module-builtins}@anchor{13}@anchor{library/builtins translation-repo}@anchor{4c59}
@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{32b,,open()}.

This module is not normally accessed explicitly by most applications, but can be
useful in modules that provide objects with the same name as a built-in value,
but in which the built-in of that name is also needed.  For example, in a module
that wants to implement an @ref{32b,,open()} function that wraps the built-in
@code{open()}, this module can be used directly:

@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

As an implementation detail, most modules have the name @code{__builtins__} made
available as part of their globals.  The value of @code{__builtins__} is normally
either this module or the value of this module’s @ref{1bf,,__dict__} attribute.
Since this is an implementation detail, it may not be used by alternate
implementations of Python.


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{266d,,Built-in Constants}

@item 
@ref{1e1e,,Built-in Exceptions}

@item 
@ref{1601,,Ενσωματωμένες (Built-in) Συναρτήσεις}

@item 
@ref{27e3,,Τύποι Built-in}
@end itemize


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node __main__ — Top-level code environment,warnings — Έλεγχος προειδοποιήσεων,builtins — Built-in objects,Python Runtime Services
@anchor{library/__main__ doc}@anchor{4c5a}@anchor{library/__main__ main-top-level-code-environment}@anchor{4c5b}@anchor{library/__main__ module-__main__}@anchor{1}@anchor{library/__main__ translation-repo}@anchor{4c5c}
@subsection @code{__main__} — Top-level code environment


@geindex module; __main__


__________________________________________________________________


In Python, the special name @code{__main__} is used for two important constructs:


@enumerate 

@item 
the name of the top-level environment of the program, which can be
checked using the @code{__name__ == '__main__'} expression; and

@item 
the @code{__main__.py} file in Python packages.
@end enumerate

Both of these mechanisms are related to Python modules; how users interact with
them and how they interact with each other.  They are explained in detail
below.  If you’re new to Python modules, see the tutorial section
@ref{222d,,Modules} for an introduction.

@menu
* __name__ == '__main__':: 
* __main__.py in Python Packages: __main__ py in Python Packages. 
* import __main__:: 

@end menu

@node __name__ == '__main__',__main__ py in Python Packages,,__main__ — Top-level code environment
@anchor{library/__main__ name-equals-main}@anchor{4c5d}@anchor{library/__main__ name-main}@anchor{4c5e}
@subsubsection @code{__name__ == '__main__'}


When a Python module or package is imported, @code{__name__} is set to the
module’s name.  Usually, this is the name of the Python file itself without the
@code{.py} extension:

@example
>>> import configparser
>>> configparser.__name__
'configparser'
@end example

If the file is part of a package, @code{__name__} will also include the parent
package’s path:

@example
>>> from concurrent.futures import process
>>> process.__name__
'concurrent.futures.process'
@end example

However, if the module is executed in the top-level code environment,
its @code{__name__} is set to the string @code{'__main__'}.

@menu
* What is the «top-level code environment»?:: 
* Idiomatic Usage:: 
* Packaging Considerations:: 

@end menu

@node What is the «top-level code environment»?,Idiomatic Usage,,__name__ == '__main__'
@anchor{library/__main__ what-is-the-top-level-code-environment}@anchor{4c5f}
@subsubsection What is the «top-level code environment»?


@code{__main__} is the name of the environment where top-level code is run.
«Top-level code» is the first user-specified Python module that starts running.
It’s «top-level» because it imports all other modules that the program needs.
Sometimes «top-level code» is called an `entry point' to the application.

The top-level code environment can be:


@itemize *

@item 
the scope of an interactive prompt:

@example
>>> __name__
'__main__'
@end example

@item 
the Python module passed to the Python interpreter as a file argument:

@example
$ python helloworld.py
Hello, world!
@end example

@item 
the Python module or package passed to the Python interpreter with the
@ref{4ca,,-m} argument:

@example
$ python -m tarfile
usage: tarfile.py [-h] [-v] (...)
@end example

@item 
Python code read by the Python interpreter from standard input:

@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 
Python code passed to the Python interpreter with the @ref{445,,-c} argument:

@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

In each of these situations, the top-level module’s @code{__name__} is set to
@code{'__main__'}.

As a result, a module can discover whether or not it is running in the
top-level environment by checking its own @code{__name__}, which allows a common
idiom for conditionally executing code when the module is not initialized from
an import statement:

@example
if __name__ == '__main__':
    # Execute when the module is not initialized from an import statement.
    ...
@end example


@subsubheading Δείτε επίσης


For a more detailed look at how @code{__name__} is set in all situations, see
the tutorial section @ref{222d,,Modules}.


@node Idiomatic Usage,Packaging Considerations,What is the «top-level code environment»?,__name__ == '__main__'
@anchor{library/__main__ idiomatic-usage}@anchor{4c60}
@subsubsection Idiomatic Usage


Some modules contain code that is intended for script use only, like parsing
command-line arguments or fetching data from standard input.  If a module
like this was imported from a different module, for example to unit test
it, the script code would unintentionally execute as well.

This is where using the @code{if __name__ == '__main__'} code block comes in
handy. Code within this block won’t run unless the module is executed in the
top-level environment.

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

Note that if the module didn’t encapsulate code inside the @code{main} function
but instead put it directly within the @code{if __name__ == '__main__'} block,
the @code{phrase} variable would be global to the entire module.  This is
error-prone as other functions within the module could be unintentionally using
the global variable instead of a local name.  A @code{main} function solves this
problem.

Using a @code{main} function has the added benefit of the @code{echo} function itself
being isolated and importable elsewhere. When @code{echo.py} is imported, the
@code{echo} and @code{main} functions will be defined, but neither of them will be
called, because @code{__name__ != '__main__'}.

@node Packaging Considerations,,Idiomatic Usage,__name__ == '__main__'
@anchor{library/__main__ packaging-considerations}@anchor{4c61}
@subsubsection Packaging Considerations


@code{main} functions are often used to create command-line tools by specifying
them as entry points for console scripts.  When this is done,
pip@footnote{https://pip.pypa.io/} inserts the function call into a template script,
where the return value of @code{main} is passed into @ref{4ff,,sys.exit()}.
For example:

@example
sys.exit(main())
@end example

Since the call to @code{main} is wrapped in @ref{4ff,,sys.exit()}, the expectation is
that your function will return some value acceptable as an input to
@code{sys.exit()}; typically, an integer or @code{None} (which is implicitly
returned if your function does not have a return statement).

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.

In particular, be careful about returning strings from your @code{main} function.
@ref{4ff,,sys.exit()} will interpret a string argument as a failure message, so
your program will have an exit code of @code{1}, indicating failure, and the
string will be written to @ref{d05,,sys.stderr}.  The @code{echo.py} example from
earlier exemplifies using the @code{sys.exit(main())} convention.


@subsubheading Δείτε επίσης


Python Packaging User Guide@footnote{https://packaging.python.org/}
contains a collection of tutorials and references on how to distribute and
install Python packages with modern tools.


@node __main__ py in Python Packages,import __main__,__name__ == '__main__',__main__ — Top-level code environment
@anchor{library/__main__ main-py-in-python-packages}@anchor{4c62}
@subsubsection @code{__main__.py} in Python Packages


If you are not familiar with Python packages, see section @ref{223d,,Πακέτα}
of the tutorial.  Most commonly, the @code{__main__.py} file is used to provide
a command-line interface for a package. Consider the following hypothetical
package, «bandclass»:

@example
bandclass
  ├── __init__.py
  ├── __main__.py
  └── student.py
@end example

@code{__main__.py} will be executed when the package itself is invoked
directly from the command line using the @ref{4ca,,-m} flag. For example:

@example
$ python -m bandclass
@end example

This command will cause @code{__main__.py} to run. How you utilize this mechanism
will depend on the nature of the package you are writing, but in this
hypothetical case, it might make sense to allow the teacher to search for
students:

@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

Note that @code{from .student import search_students} is an example of a relative
import.  This import style can be used when referencing modules within a
package.  For more details, see @ref{2241,,Intra-package αναφορές} in the
@ref{222d,,Modules} section of the tutorial.

@menu
* Idiomatic Usage: Idiomatic Usage<2>. 

@end menu

@node Idiomatic Usage<2>,,,__main__ py in Python Packages
@anchor{library/__main__ id1}@anchor{4c63}
@subsubsection Idiomatic Usage


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.

If used, an @code{if __name__ == '__main__'} block will still work as expected
for a @code{__main__.py} file within a package, because its @code{__name__}
attribute will include the package’s path if imported:

@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 Δείτε επίσης


See @ref{11a,,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]}.

See @ref{c6,,runpy} for more details on the @ref{4ca,,-m} flag to the
interpreter executable.

See @ref{139,,zipapp} for how to run applications packaged as `.zip' files. In
this case Python looks for a @code{__main__.py} file in the root directory of
the archive.


@node import __main__,,__main__ py in Python Packages,__main__ — Top-level code environment
@anchor{library/__main__ import-main}@anchor{4c64}
@subsubsection @code{import __main__}


Regardless of which module a Python program was started with, other modules
running within that same program can import the top-level environment’s scope
(@ref{222e,,namespace}) by importing the @code{__main__} module.  This doesn’t import
a @code{__main__.py} file but rather whichever module that received the special
name @code{'__main__'}.

Here is an example module that consumes the @code{__main__} namespace:

@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`!')

    print(__main__.my_name)
@end example

Example usage of this module could be as follows:

@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

Now, if we started our program, the result would look like this:

@example
$ python start.py
Define the variable `my_name`!
@end example

The exit code of the program would be 1, indicating an error. Uncommenting the
line with @code{my_name = "Dinsdale"} fixes the program and now it exits with
status code 0, indicating success:

@example
$ python start.py
Dinsdale
@end example

Note that importing @code{__main__} doesn’t cause any issues with unintentionally
running top-level code meant for script use which is put in the
@code{if __name__ == "__main__"} block of the @code{start} module. Why does this work?

Python inserts an empty @code{__main__} module in @ref{19ba,,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 @code{sys.modules}, Python passes that to @code{namely}.
See @ref{2655,,Special considerations for __main__} in the
import system’s reference for details on how this works.

The Python REPL is another example of a «top-level environment», so anything
defined in the REPL becomes part of the @code{__main__} scope:

@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

The @code{__main__} scope is used in the implementation of @ref{aa,,pdb} and
@ref{c5,,rlcompleter}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node warnings — Έλεγχος προειδοποιήσεων,dataclasses — Data Classes,__main__ — Top-level code environment,Python Runtime Services
@anchor{library/warnings doc}@anchor{4c65}@anchor{library/warnings module-warnings}@anchor{11b}@anchor{library/warnings translation-repo}@anchor{4c66}@anchor{library/warnings warnings-warning-control}@anchor{4c67}
@subsection @code{warnings} — Έλεγχος προειδοποιήσεων


@geindex module; warnings

`Πηγαίος κώδικας:' Lib/warnings.py@footnote{https://github.com/python/cpython/tree/main/Lib/warnings.py}

@geindex προειδοποιήσεις


__________________________________________________________________


Τα μηνύματα προειδοποίησης συνήθως εκδίδονται σε καταστάσεις όπου είναι χρήσιμο να ειδοποιηθεί ο χρήστης για κάποια κατάσταση σε ένα πρόγραμμα, όπου αυτή η κατάσταση (κανονικά) δεν δικαιολογεί την πρόκληση εξαίρεσης και τον τερματισμό του προγράμματος. Για παράδειγμα, μπορεί να θέλετε να εκδώσετε μια προειδοποίηση όταν ένα πρόγραμμα χρησιμοποιεί ένα απαρχαιωμένο module.

Οι προγραμματιστές Python εκδίδουν προειδοποιήσεις καλώντας τη συνάρτηση @ref{18bb,,warn()} που ορίζεται σε αυτό το module. (Οι προγραμματιστές C χρησιμοποιούν @ref{17ee,,PyErr_WarnEx()}; δείτε @ref{4c68,,Exception Handling} για λεπτομέρειες).

Τα μηνύματα προειδοποίησης συνήθως γράφονται στο @ref{d05,,sys.stderr}, αλλά η διάθεσή τους μπορεί να αλλάξει ευέλικτα, από την αγνόηση όλων των προειδοποιήσεων έως την μετατροπή τους σε εξαιρέσεις. Η διάθεση των προειδοποιήσεων μπορεί να διαφέρει με βάση την @ref{290d,,warning category}, το κείμενο του μηνύματος προειδοποίησης και την πηγή όπου εκδίδεται. Οι επαναλήψεις μιας συγκεκριμένης προειδοποίησης για την ίδια πηγή συνήθως καταστέλλονται.

Υπάρχουν δύο στάδια στον έλεγχο προειδοποιήσεων: πρώτον, κάθε φορά που εκδίδεται μια προειδοποίηση, γίνεται μια εκτίμηση για το αν πρέπει να εκδοθεί ένα μήνυμα ή όχι. Στη συνέχεια, εάν πρέπει να εκδοθεί ένα μήνυμα, διαμορφώνεται και εκτυπώνεται χρησιμοποιώντας ένα ρυθμιζόμενο από τον χρήστη hook.

Η εκτίμηση για το αν θα εκδοθεί ένα μήνυμα προειδοποίησης ελέγχεται από το @ref{1cc,,warning filter}, το οποίο είναι μια ακολουθία κανόνων και ενεργειών αντιστοίχισης. Οι κανόνες μπορούν να προστεθούν στο φίλτρο καλώντας @ref{184b,,filterwarnings()} και να επαναφερθούν στην προεπιλεγμένη κατάστασή τους καλώντας @ref{4c69,,resetwarnings()}.

Η εκτύπωση των μηνυμάτων προειδοποίησης γίνεται καλώντας @ref{4c6a,,showwarning()}, η οποία μπορεί να αντικατασταθεί. Η προεπιλεγμένη υλοποίηση αυτής της συνάρτησης διαμορφώνει το μήνυμα καλώντας @ref{1fe7,,formatwarning()}, η οποία είναι επίσης διαθέσιμη για χρήση από προσαρμοσμένες υλοποιήσεις.


@subsubheading Δείτε επίσης


Η @ref{33fe,,logging.captureWarnings()} σας επιτρέπει να χειρίζεστε όλες τις προειδοποιήσεις με την τυπική υποδομή καταγραφής.


@menu
* Κατηγορίες Προειδοποίησης:: 
* Το Φίλτρο Προειδοποιήσεων:: 
* Προσωρινή Καταστολή Προειδοποιήσεων:: 
* Δοκιμή Προειδοποιήσεων:: 
* Ενημέρωση κώδικα για νέες εκδόσεις εξαρτήσεων:: 
* Διαθέσιμες λειτουργίες:: 
* Διαθέσιμοι Context Managers:: 
* Συγχρονισμένη ασφάλεια των Context Managers:: 

@end menu

@node Κατηγορίες Προειδοποίησης,Το Φίλτρο Προειδοποιήσεων,,warnings — Έλεγχος προειδοποιήσεων
@anchor{library/warnings id1}@anchor{4c6b}@anchor{library/warnings warning-categories}@anchor{290d}
@subsubsection Κατηγορίες Προειδοποίησης


Υπάρχουν αρκετές ενσωματωμένες εξαιρέσεις που αντιπροσωπεύουν κατηγορίες προειδοποιήσεων. Αυτή η κατηγοριοποίηση είναι χρήσιμη για να μπορείτε να φιλτράρετε ομάδες προειδοποιήσεων.

Παρόλο που τεχνικά αυτές είναι @ref{290b,,built-in exceptions}, τεκμηριώνονται εδώ, επειδή εννοιολογικά ανήκουν στο μηχανισμό προειδοποιήσεων.

Ο κώδικας χρήστη μπορεί να ορίσει επιπλέον κατηγορίες προειδοποιήσεων υποκατηγοριοποιώντας μία από τις τυπικές κατηγορίες προειδοποιήσεων. Μια κατηγορία προειδοποίησης πρέπει πάντα να είναι υποκλάση της κλάσης @ref{290e,,Warning}.

Οι ακόλουθες κλάσεις κατηγοριών προειδοποιήσεων ορίζονται επί του παρόντος:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Κλάση

@tab

Περιγραφή

@item

@ref{290e,,Warning}

@tab

Αυτή είναι η βασική κλάση όλων των κατηγοριών προειδοποιήσεων. Είναι μια υποκλάση της @ref{d9e,,Exception}.

@item

@ref{290f,,UserWarning}

@tab

Η προεπιλεγμένη κατηγορία για την @ref{18bb,,warn()}.

@item

@ref{2c9,,DeprecationWarning}

@tab

Βασική κατηγορία για προειδοποιήσεις σχετικά με απαρχαιωμένες λειτουργίες όταν αυτές οι προειδοποιήσεις προορίζονται για άλλους προγραμματιστές Python (αγνοούνται από προεπιλογή, εκτός εάν ενεργοποιούνται από κώδικα στο @code{__main__}).

@item

@ref{44a,,SyntaxWarning}

@tab

Βασική κατηγορία για προειδοποιήσεις σχετικά με αμφίβολες συντακτικές λειτουργίες (συνήθως εκδίδονται κατά τη μεταγλώττιση κώδικα πηγής Python και επομένως δεν μπορούν να κατασταλούν από τα φίλτρα χρόνου εκτέλεσης)

@item

@ref{6dd,,RuntimeWarning}

@tab

Βασική κατηγορία για προειδοποιήσεις σχετικά με αμφίβολες λειτουργίες χρόνου εκτέλεσης.

@item

@ref{847,,FutureWarning}

@tab

Βασική κατηγορία για προειδοποιήσεις σχετικά με απαρχαιωμένες λειτουργίες όταν αυτές οι προειδοποιήσεις προορίζονται για τελικούς χρήστες εφαρμογών που είναι γραμμένες σε Python.

@item

@ref{c9b,,PendingDeprecationWarning}

@tab

Βασική κατηγορία για προειδοποιήσεις σχετικά με λειτουργίες που θα απαρχαιωθούν στο μέλλον (αγνοούνται από προεπιλογή).

@item

@ref{907,,ImportWarning}

@tab

Βασική κατηγορία για προειδοποιήσεις που ενεργοποιούνται κατά τη διαδικασία εισαγωγής ενός module (αγνοούνται από προεπιλογή).

@item

@ref{17c6,,UnicodeWarning}

@tab

Βασική κατηγορία για προειδοποιήσεις που σχετίζονται με το Unicode.

@item

@ref{2ee,,BytesWarning}

@tab

Βασική κατηγορία για προειδοποιήσεις που σχετίζονται με @ref{1c7,,bytes} και @ref{1c6,,bytearray}.

@item

@ref{74f,,ResourceWarning}

@tab

Βασική κατηγορία για προειδοποιήσεις που σχετίζονται με τη χρήση πόρων (αγνοούνται από προεπιλογή).

@end multitable



Άλλαξε στην έκδοση 3.7: Προηγουμένως, οι @ref{2c9,,DeprecationWarning} και @ref{847,,FutureWarning} διακρίνονταν με βάση το αν μια λειτουργία αφαιρούνταν εντελώς ή άλλαζε τη συμπεριφορά της. Τώρα διακρίνονται με βάση το κοινό στο οποίο απευθύνονται και τον τρόπο με τον οποίο χειρίζονται τα προεπιλεγμένα φίλτρα προειδοποιήσεων.


@node Το Φίλτρο Προειδοποιήσεων,Προσωρινή Καταστολή Προειδοποιήσεων,Κατηγορίες Προειδοποίησης,warnings — Έλεγχος προειδοποιήσεων
@anchor{library/warnings the-warnings-filter}@anchor{4c6c}@anchor{library/warnings warning-filter}@anchor{1cc}
@subsubsection Το Φίλτρο Προειδοποιήσεων


Το φίλτρο προειδοποιήσεων ελέγχει αν οι προειδοποιήσεις αγνοούνται, εμφανίζονται ή μετατρέπονται σε σφάλματα (προκαλώντας εξαίρεση).

Εννοιολογικά, το φίλτρο προειδοποιήσεων διατηρεί μια διατεταγμένη λίστα προδιαγραφών φίλτρων. Κάθε συγκεκριμένη προειδοποίηση αντιστοιχίζεται σε κάθε προδιαγραφή φίλτρου στη λίστα με τη σειρά μέχρι να βρεθεί μια αντιστοιχία. Το φίλτρο καθορίζει τη διάθεση της αντιστοιχίας. Κάθε καταχώριση είναι μια πλειάδα της μορφής (`action', `message', `category', `module', `lineno'), όπου:


@itemize *

@item 
`action' είναι μία από τις ακόλουθες συμβολοσειρές:


@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Τιμή

@tab

Διάθεση

@item

@code{"default"}

@tab

εκτυπώνει την πρώτη εμφάνιση των ταιριασμένων προειδοποιήσεων για κάθε τοποθεσία (module + αριθμός γραμμής) όπου εκδίδεται η προειδοποίηση

@item

@code{"error"}

@tab

μετατρέπει τις ταιριασμένες προειδοποιήσεις σε εξαιρέσεις

@item

@code{"ignore"}

@tab

ποτέ δεν εκτυπώνει τις ταιριασμένες προειδοποιήσεις

@item

@code{"always"}

@tab

πάντα εκτυπώνει τις ταιριασμένες προειδοποιήσεις

@item

@code{"all"}

@tab

ψευδώνυμο για το «always»

@item

@code{"module"}

@tab

εκτυπώνει την πρώτη εμφάνιση των ταιριασμένων προειδοποιήσεων για κάθε module όπου εκδίδεται η προειδοποίηση (ανεξάρτητα από τον αριθμό γραμμής)

@item

@code{"once"}

@tab

εκτυπώνει μόνο την πρώτη εμφάνιση των ταιριασμένων προειδοποιήσεων, ανεξάρτητα από την τοποθεσία

@end multitable


@item 
`message' is a string containing a regular expression that the start of
the warning message must match, case-insensitively.  In @ref{1c0,,-W} and
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,PYTHONWARNINGS}, if `message' starts and ends with a forward slash
(@code{/}), it specifies a regular expression as above;
otherwise it is a literal string that the start of the
warning message must match (case-insensitively), ignoring any whitespace at
the start or end of `message'.

@item 
Το `category' είναι μια κλάση (μια υποκλάση της @ref{290e,,Warning}) της οποίας η κατηγορία προειδοποίησης πρέπει να είναι υποκλάση για να ταιριάζει.

@item 
`module' is a string containing a regular expression that the start of the
fully qualified module name must match, case-sensitively.  In @ref{1c0,,-W} and
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,PYTHONWARNINGS}, if `module' starts and ends with a forward slash
(@code{/}), it specifies a regular expression as above;
otherwise it 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' είναι ένας ακέραιος αριθμός με τον οποίο πρέπει να ταιριάζει ο αριθμός γραμμής όπου συνέβη η προειδοποίηση, ή @code{0} για να ταιριάζουν όλοι οι αριθμοί γραμμών.
@end itemize

Δεδομένου ότι η κλάση @ref{290e,,Warning} προέρχεται από την ενσωματωμένη κλάση @ref{d9e,,Exception}, για να μετατρέψουμε μια προειδοποίηση σε σφάλμα απλώς προκαλούμε @code{category(message)}.

Εάν αναφερθεί μια προειδοποίηση και δεν ταιριάζει με κανένα καταχωρημένο φίλτρο, τότε εφαρμόζεται η ενέργεια «default» (εξ ου και το όνομά της).

@menu
* Κριτήρια Καταστολής Επαναλαμβανόμενων Προειδοποιήσεων:: 
* Περιγραφή Φίλτρων Προειδοποιήσεων:: 
* Προεπιλεγμένο φίλτρο προειδοποιήσεων:: 
* Αντικατάσταση του προεπιλεγμένου φίλτρου:: 

@end menu

@node Κριτήρια Καταστολής Επαναλαμβανόμενων Προειδοποιήσεων,Περιγραφή Φίλτρων Προειδοποιήσεων,,Το Φίλτρο Προειδοποιήσεων
@anchor{library/warnings id2}@anchor{4c6d}@anchor{library/warnings repeated-warning-suppression-criteria}@anchor{4c6e}
@subsubsection Κριτήρια Καταστολής Επαναλαμβανόμενων Προειδοποιήσεων


Τα φίλτρα που καταστέλλουν τις επαναλαμβανόμενες προειδοποιήσεις εφαρμόζουν τα ακόλουθα κριτήρια για να προσδιορίσουν αν μια προειδοποίηση θεωρείται επανάληψη:


@itemize -

@item 
@code{"default"}: Μια προειδοποίηση θεωρείται επανάληψη μόνο αν τα (`message', `category', `module', `lineno') είναι όλα τα ίδια.

@item 
@code{"module"}: Μια προειδοποίηση θεωρείται επανάληψη αν τα (`message', `category', `module') είναι τα ίδια, αγνοώντας τον αριθμό γραμμής.

@item 
@code{"once"}: Μια προειδοποίηση θεωρείται επανάληψη αν τα (`message', `category') είναι τα ίδια, αγνοώντας το module και τον αριθμό γραμμής.
@end itemize

@node Περιγραφή Φίλτρων Προειδοποιήσεων,Προεπιλεγμένο φίλτρο προειδοποιήσεων,Κριτήρια Καταστολής Επαναλαμβανόμενων Προειδοποιήσεων,Το Φίλτρο Προειδοποιήσεων
@anchor{library/warnings describing-warning-filters}@anchor{2319}@anchor{library/warnings id3}@anchor{4c6f}
@subsubsection Περιγραφή Φίλτρων Προειδοποιήσεων


The warnings filter is initialized by @ref{1c0,,-W} options passed to the Python
interpreter command line and the 
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,PYTHONWARNINGS} environment variable.
The interpreter saves the arguments for all supplied entries without
interpretation in @ref{3a5,,sys.warnoptions}; the @code{warnings} module parses these
when it is first imported (invalid options are ignored, after printing a
message to @ref{d05,,sys.stderr}).

Τα μεμονωμένα φίλτρα προειδοποιήσεων καθορίζονται ως ακολουθία πεδίων διαχωρισμένων με άνω και κάτω τελεία:

@example
action:message:category:module:line
@end example

Η σημασία του καθενός από αυτά τα πεδία περιγράφεται στο @ref{1cc,,Το Φίλτρο Προειδοποιήσεων}. Όταν απαριθμούνται πολλαπλά φίλτρα σε μία μόνο γραμμή (όπως για το 
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,PYTHONWARNINGS}), τα μεμονωμένα φίλτρα διαχωρίζονται με κόμματα και τα φίλτρα που απαριθμούνται αργότερα έχουν προτεραιότητα έναντι αυτών που απαριθμούνται πριν από αυτά (καθώς εφαρμόζονται από αριστερά προς τα δεξιά, και τα πιο πρόσφατα εφαρμοσμένα φίλτρα έχουν προτεραιότητα έναντι των προηγούμενων).

Τα συνήθως χρησιμοποιούμενα φίλτρα προειδοποιήσεων εφαρμόζονται είτε σε όλες τις προειδοποιήσεις, προειδοποιήσεις σε μια συγκεκριμένη κατηγορία ή προειδοποιήσεις που προκαλούνται από συγκεκριμένα modules ή πακέτα. Μερικά παραδείγματα:

@example
default                      # Εμφάνιση όλων των προειδοποιήσεων (ακόμη και αυτών που αγνοούνται από προεπιλογή)
ignore                       # Αγνόηση όλων των προειδοποιήσεων
error                        # Μετατροπή όλων των προειδοποιήσεων σε σφάλματα
error::ResourceWarning       # Αντιμετώπιση των μηνυμάτων ResourceWarning ως σφάλματα
default::DeprecationWarning  # Εμφάνιση μηνυμάτων DeprecationWarning
ignore,default:::mymodule    # Αναφορά μόνο προειδοποιήσεων που ενεργοποιούνται από το "mymodule"
error:::mymodule             # Μετατροπή προειδοποιήσεων σε σφάλματα στο "mymodule"
@end example

@node Προεπιλεγμένο φίλτρο προειδοποιήσεων,Αντικατάσταση του προεπιλεγμένου φίλτρου,Περιγραφή Φίλτρων Προειδοποιήσεων,Το Φίλτρο Προειδοποιήσεων
@anchor{library/warnings default-warning-filter}@anchor{4c70}@anchor{library/warnings id4}@anchor{4c71}
@subsubsection Προεπιλεγμένο φίλτρο προειδοποιήσεων


Από προεπιλογή, η Python εγκαθιστά αρκετά φίλτρα προειδοποιήσεων, τα οποία μπορούν να αντικατασταθούν από την επιλογή γραμμής εντολών @ref{1c0,,-W}, τη μεταβλητή περιβάλλοντος 
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,PYTHONWARNINGS} και κλήσεις στη @ref{184b,,filterwarnings()}.

Σε κανονικές εκδόσεις, το προεπιλεγμένο φίλτρο προειδοποιήσεων έχει τις ακόλουθες καταχωρήσεις (με σειρά προτεραιότητας):

@example
default::DeprecationWarning:__main__
ignore::DeprecationWarning
ignore::PendingDeprecationWarning
ignore::ImportWarning
ignore::ResourceWarning
@end example

Σε μια @ref{3dc,,debug build}, η λίστα των προεπιλεγμένων φίλτρων προειδοποιήσεων είναι κενή.


Άλλαξε στην έκδοση 3.2: @ref{2c9,,DeprecationWarning} αγνοείται πλέον από προεπιλογή επιπλέον της @ref{c9b,,PendingDeprecationWarning}.



Άλλαξε στην έκδοση 3.7: @ref{2c9,,DeprecationWarning} εμφανίζεται ξανά από προεπιλογή όταν ενεργοποιείται άμεσα από κώδικα στο @code{__main__}.



Άλλαξε στην έκδοση 3.7: @ref{2ee,,BytesWarning} δεν εμφανίζεται πλέον στη λίστα προεπιλεγμένων φίλτρων και αντ” αυτού διαμορφώνεται μέσω @ref{3a5,,sys.warnoptions} όταν @ref{2ed,,-b} καθορίζεται δύο φορές.


@node Αντικατάσταση του προεπιλεγμένου φίλτρου,,Προεπιλεγμένο φίλτρο προειδοποιήσεων,Το Φίλτρο Προειδοποιήσεων
@anchor{library/warnings overriding-the-default-filter}@anchor{4c72}@anchor{library/warnings warning-disable}@anchor{4c73}
@subsubsection Αντικατάσταση του προεπιλεγμένου φίλτρου


Οι προγραμματιστές εφαρμογών γραμμένων σε Python μπορεί να επιθυμούν να αποκρύψουν `όλες' τις προειδοποιήσεις επιπέδου Python από τους χρήστες τους από προεπιλογή, και να τις εμφανίζουν μόνο κατά την εκτέλεση δοκιμών ή άλλως εργαζόμενοι στην εφαρμογή. Το χαρακτηριστικό @ref{3a5,,sys.warnoptions} που χρησιμοποιείται για τη μετάδοση διαμορφώσεων φίλτρων στον διερμηνέα μπορεί να χρησιμοποιηθεί ως δείκτης για να υποδείξει αν οι προειδοποιήσεις πρέπει να απενεργοποιηθούν ή όχι:

@example
import sys

if not sys.warnoptions:
    import warnings
    warnings.simplefilter("ignore")
@end example

Οι προγραμματιστές εργαλείων εκτέλεσης δοκιμών για κώδικα Python συνιστάται να διασφαλίζουν αντ” αυτού ότι `όλες' οι προειδοποιήσεις εμφανίζονται από προεπιλογή για τον κώδικα υπό δοκιμή, χρησιμοποιώντας κώδικα όπως:

@example
import sys

if not sys.warnoptions:
    import os, warnings
    warnings.simplefilter("default") # Αλλαγή του φίλτρου σε αυτή τη διαδικασία
    os.environ["PYTHONWARNINGS"] = "default" # Επηρεάζει επίσης τις υποδιαδικασίες
@end example

Τέλος, οι προγραμματιστές διαδραστικών κελυφών που εκτελούν κώδικα χρήστη σε ένα namespace διαφορετικό από το @code{__main__} συνιστάται να διασφαλίζουν ότι τα μηνύματα @ref{2c9,,DeprecationWarning} γίνονται ορατά από προεπιλογή, χρησιμοποιώντας κώδικα όπως ο παρακάτω (όπου το @code{user_ns} είναι το module που χρησιμοποιείται για την εκτέλεση κώδικα που εισάγεται διαδραστικά):

@example
import warnings
warnings.filterwarnings("default", category=DeprecationWarning,
                                   module=user_ns.get("__name__"))
@end example

@node Προσωρινή Καταστολή Προειδοποιήσεων,Δοκιμή Προειδοποιήσεων,Το Φίλτρο Προειδοποιήσεων,warnings — Έλεγχος προειδοποιήσεων
@anchor{library/warnings temporarily-suppressing-warnings}@anchor{4c74}@anchor{library/warnings warning-suppress}@anchor{4c75}
@subsubsection Προσωρινή Καταστολή Προειδοποιήσεων


Εάν χρησιμοποιείτε κώδικα που γνωρίζετε ότι θα προκαλέσει μια προειδοποίηση, όπως μια απαρχαιωμένη λειτουργία, αλλά δεν θέλετε να δείτε την προειδοποίηση (ακόμη και όταν οι προειδοποιήσεις έχουν ρυθμιστεί ρητά μέσω της γραμμής εντολών), τότε είναι δυνατό να καταστείλετε την προειδοποίηση χρησιμοποιώντας τον @ref{423,,catch_warnings} context manager:

@example
import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    fxn()
@end example

Ενώ βρίσκεστε μέσα στον context manager, όλες οι προειδοποιήσεις θα απλώς θα αγνοούνται. Αυτό σας επιτρέπει να χρησιμοποιείτε γνωστό απαρχαιωμένο κώδικα χωρίς να χρειάζεται να δείτε την προειδοποίηση, χωρίς να καταστέλλετε την προειδοποίηση για άλλο κώδικα που μπορεί να μην είναι ενήμερος για τη χρήση απαρχαιωμένου κώδικα.

@quotation

@cartouche
@quotation Σημείωση 
Δείτε το @ref{4c76,,Συγχρονισμένη ασφάλεια των Context Managers} για λεπτομέρειες σχετικά με την ασφάλεια ταυτόχρονης εκτέλεσης του @ref{423,,catch_warnings} context manager όταν χρησιμοποιείται σε προγράμματα που χρησιμοποιούν πολλαπλές νηματοειδείς διαδικασίες ή ασύγχρονες λειτουργίες.
@end quotation
@end cartouche
@end quotation

@node Δοκιμή Προειδοποιήσεων,Ενημέρωση κώδικα για νέες εκδόσεις εξαρτήσεων,Προσωρινή Καταστολή Προειδοποιήσεων,warnings — Έλεγχος προειδοποιήσεων
@anchor{library/warnings testing-warnings}@anchor{4c77}@anchor{library/warnings warning-testing}@anchor{4c78}
@subsubsection Δοκιμή Προειδοποιήσεων


Για να δοκιμάσετε προειδοποιήσεις που προκαλούνται από κώδικα, χρησιμοποιήστε τον @ref{423,,catch_warnings} context manager. Με αυτόν μπορείτε προσωρινά να μεταβάλλετε το φίλτρο προειδοποιήσεων για να διευκολύνετε τις δοκιμές σας. Για παράδειγμα, κάντε το ακόλουθο για να καταγράψετε όλες τις προειδοποιήσεις που έχουν προκληθεί για έλεγχο:

@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

Μπορείτε επίσης να κάνετε όλες τις προειδοποιήσεις να είναι εξαιρέσεις χρησιμοποιώντας το @code{error} αντί για το @code{always}. Ένα πράγμα που πρέπει να γνωρίζετε είναι ότι εάν μια προειδοποίηση έχει ήδη προκληθεί λόγω ενός κανόνα @code{once}/@code{default}, τότε ανεξάρτητα από τα φίλτρα που έχουν οριστεί, η προειδοποίηση δεν θα εμφανιστεί ξανά εκτός εάν έχει καθαριστεί το μητρώο προειδοποιήσεων που σχετίζεται με την προειδοποίηση.

Μόλις ο context manager τερματιστεί, το φίλτρο προειδοποιήσεων επαναφέρεται στην κατάσταση που βρισκόταν όταν εισήλθε το context. Αυτό αποτρέπει τις δοκιμές από το να αλλάζουν το φίλτρο προειδοποιήσεων με απροσδόκητους τρόπους μεταξύ των δοκιμών και να οδηγούν σε απροσδιόριστα αποτελέσματα δοκιμών.

@quotation

@cartouche
@quotation Σημείωση 
Δείτε το @ref{4c76,,Συγχρονισμένη ασφάλεια των Context Managers} για λεπτομέρειες σχετικά με την ασφάλεια ταυτόχρονης εκτέλεσης του @ref{423,,catch_warnings} context manager όταν χρησιμοποιείται σε προγράμματα που χρησιμοποιούν πολλαπλές νηματοειδείς διαδικασίες ή ασύγχρονες λειτουργίες.
@end quotation
@end cartouche
@end quotation

Όταν δοκιμάζετε πολλαπλές λειτουργίες που προκαλούν τον ίδιο τύπο προειδοποίησης, είναι σημαντικό να τις δοκιμάζετε με τρόπο που να επιβεβαιώνει ότι κάθε λειτουργία προκαλεί μια νέα προειδοποίηση (π.χ. ρυθμίστε τις προειδοποιήσεις να προκαλούνται ως εξαιρέσεις και ελέγξτε ότι οι λειτουργίες προκαλούν εξαιρέσεις, ελέγξτε ότι το μήκος της λίστας προειδοποιήσεων συνεχίζει να αυξάνεται μετά από κάθε λειτουργία, ή αλλιώς διαγράψτε τις προηγούμενες καταχωρίσεις από τη λίστα προειδοποιήσεων πριν από κάθε νέα λειτουργία).

@node Ενημέρωση κώδικα για νέες εκδόσεις εξαρτήσεων,Διαθέσιμες λειτουργίες,Δοκιμή Προειδοποιήσεων,warnings — Έλεγχος προειδοποιήσεων
@anchor{library/warnings updating-code-for-new-versions-of-dependencies}@anchor{4c79}@anchor{library/warnings warning-ignored}@anchor{4876}
@subsubsection Ενημέρωση κώδικα για νέες εκδόσεις εξαρτήσεων


Οι κατηγορίες προειδοποιήσεων που ενδιαφέρουν κυρίως τους προγραμματιστές Python (αντί για τους τελικούς χρήστες εφαρμογών γραμμένων σε Python) αγνοούνται από προεπιλογή.

Σημειωτέον, αυτή η λίστα «αγνοείται από προεπιλογή» περιλαμβάνει την @ref{2c9,,DeprecationWarning} (για κάθε module εκτός από το @code{__main__}), που σημαίνει ότι οι προγραμματιστές πρέπει να βεβαιωθούν ότι δοκιμάζουν τον κώδικά τους με τις συνήθεις αγνοούμενες προειδοποιήσεις να γίνονται ορατές, προκειμένου να λαμβάνουν έγκαιρες ειδοποιήσεις για μελλοντικές αλλαγές που σπάνε το API (είτε στην τυπική βιβλιοθήκη είτε σε πακέτα τρίτων).

Στην ιδανική περίπτωση, ο κώδικας θα έχει μια κατάλληλη σουίτα δοκιμών, και το εργαλείο εκτέλεσης δοκιμών θα φροντίζει να ενεργοποιεί όλες τις προειδοποιήσεις αυτοματοποιημένα κατά την εκτέλεση δοκιμών (το εργαλείο εκτέλεσης δοκιμών που παρέχεται από το module @ref{10f,,unittest} το κάνει αυτό).

Σε λιγότερο ιδανικές περιπτώσεις, οι εφαρμογές μπορούν να ελεγχθούν για τη χρήση απαρχαιωμένων διεπαφών περνώντας @ref{1c0,,-Wd} στον διερμηνέα Python (αυτή είναι συντομογραφία για @code{-W default}) ή ρυθμίζοντας @code{PYTHONWARNINGS=default} στο περιβάλλον. Αυτό ενεργοποιεί την προεπιλεγμένη διαχείριση για όλες τις προειδοποιήσεις, συμπεριλαμβανομένων αυτών που αγνοούνται από προεπιλογή. Για να αλλάξετε ποια ενέργεια λαμβάνεται για τις αντιμετωπιζόμενες προειδοποιήσεις, μπορείτε να αλλάξετε ποιο όρισμα περνιέται στο @code{-W} (π.χ. @code{-W error}). Δείτε τη σημαία @code{-W} για περισσότερες λεπτομέρειες σχετικά με το τι είναι δυνατό.

@node Διαθέσιμες λειτουργίες,Διαθέσιμοι Context Managers,Ενημέρωση κώδικα για νέες εκδόσεις εξαρτήσεων,warnings — Έλεγχος προειδοποιήσεων
@anchor{library/warnings available-functions}@anchor{4c7a}@anchor{library/warnings warning-functions}@anchor{4c7b}
@subsubsection Διαθέσιμες λειτουργίες


@geindex warn() (στη μονάδα warnings)
@anchor{library/warnings warnings warn}@anchor{18bb}
@deffn {Συνάρτηση} warnings.warn (message, category=None, stacklevel=1, source=None, *, skip_file_prefixes=())

Εκδίδει μια προειδοποίηση, ή ίσως την αγνοεί ή κάνει raise μια εξαίρεση. Το `category' επιχείρημα, αν δοθεί, πρέπει να είναι μια @ref{290d,,warning category class}· η προεπιλογή είναι @ref{290f,,UserWarning}. Εναλλακτικά, το `message' μπορεί να είναι μια @ref{290e,,Warning} παρουσία, στην οποία περίπτωση το `category' θα αγνοηθεί και θα χρησιμοποιηθεί το @code{message.__class__}. Σε αυτή την περίπτωση, το κείμενο του μηνύματος θα είναι @code{str(message)}. Αυτή η λειτουργία προκαλεί μια εξαίρεση αν η συγκεκριμένη προειδοποίηση που εκδίδεται μετατραπεί σε σφάλμα από το @ref{1cc,,warnings filter}. Το `stacklevel' επιχείρημα μπορεί να χρησιμοποιηθεί από wrapper functions γραμμένες σε Python, όπως αυτό:

@example
def deprecated_api(message):
    warnings.warn(message, DeprecationWarning, stacklevel=2)
@end example

Αυτό κάνει την προειδοποίηση να αναφέρεται στον καλούντα της @code{deprecated_api}, αντί στην πηγή της ίδιας της @code{deprecated_api} (δεδομένου ότι το δεύτερο θα αναιρούσε τον σκοπό του μηνύματος προειδοποίησης).

Το `skip_file_prefixes' όρισμα λέξεων-κλειδιών μπορεί να χρησιμοποιηθεί για να υποδείξει ποια stack frames αγνοούνται κατά την καταμέτρηση των επιπέδων στοίβας. Αυτό μπορεί να είναι χρήσιμο όταν θέλετε η προειδοποίηση να εμφανίζεται πάντα σε σημεία κλήσης εκτός ενός πακέτου όταν ένα σταθερό `stacklevel' δεν ταιριάζει σε όλες τις διαδρομές κλήσης ή είναι διαφορετικά δύσκολο να διατηρηθεί. Εάν παρέχεται, πρέπει να είναι μια πλειάδα συμβολοσειρών. Όταν παρέχονται προθέματα, το stacklevel παρακάμπτεται αυτοματοποιημένα ώστε να είναι @code{max(2, stacklevel)}. Για να προκαλέσετε την απόδοση μιας προειδοποίησης στον καλούντα από εκτός του τρέχοντος πακέτου, μπορείτε να γράψετε:

@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

Αυτό κάνει την προειδοποίηση να αναφέρεται τόσο στα σημεία κλήσης της @code{example.lower.one_way()} όσο και της @code{package.higher.another_way()} μόνο από κώδικα κλήσης που ζει εκτός του πακέτου @code{example}.

`source', αν παρέχεται, είναι το καταστραμμένο αντικείμενο που εξέπεμψε μια @ref{74f,,ResourceWarning}.


Άλλαξε στην έκδοση 3.6: Προστέθηκε η παράμετρος `source'.



Άλλαξε στην έκδοση 3.12: Προστέθηκε το `skip_file_prefixes'.

@end deffn

@geindex warn_explicit() (στη μονάδα warnings)
@anchor{library/warnings warnings warn_explicit}@anchor{2ab}
@deffn {Συνάρτηση} warnings.warn_explicit (message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)

Αυτή είναι μια διεπαφή χαμηλού επιπέδου στη λειτουργικότητα της @ref{18bb,,warn()}, με την οποία περνιούνται ρητά το μήνυμα, η κατηγορία, το όνομα αρχείου και ο αριθμός γραμμής, και προαιρετικά άλλα ορίσματα. Το `message' πρέπει να είναι μια συμβολοσειρά και το `category' μια υποκλάση του @ref{290e,,Warning} ή το `message' μπορεί να είναι μια παρουσία @code{Warning}, στην οποία περίπτωση το `category' θα αγνοηθεί.

`module', if supplied, should be the module name.
If no module is passed, the module regular expression in
@ref{1cc,,warnings filter} will be tested against the module
names constructed from the path components starting from all parent
directories (with @code{/__init__.py}, @code{.py} and, on Windows, @code{.pyw}
stripped) and against the filename with @code{.py} stripped.
For example, when the filename is @code{'/path/to/package/module.py'}, it will
be tested against  @code{'path.to.package.module'}, @code{'to.package.module'}
@code{'package.module'}, @code{'module'}, and @code{'/path/to/package/module'}.

`registry', αν παρέχεται, θα πρέπει να είναι το @code{__warningregistry__} λεξικό του module. Εάν δεν περνιέται μητρώο, κάθε προειδοποίηση αντιμετωπίζεται ως η πρώτη εμφάνιση, δηλαδή, οι ενέργειες φίλτρου @code{"default"}, @code{"module"} και @code{"once"} αντιμετωπίζονται ως @code{"always"}.

`module_globals', αν παρέχεται, θα πρέπει να είναι το παγκόσμιο namespace που χρησιμοποιείται από τον κώδικα για τον οποίο εκδίδεται η προειδοποίηση. (Αυτό το όρισμα χρησιμοποιείται για την υποστήριξη εμφάνισης πηγής για modules που βρίσκονται σε αρχεία zip ή άλλες πηγές εισαγωγής εκτός συστήματος αρχείων).

`source', αν παρέχεται, είναι το καταστραμμένο αντικείμενο που εξέπεμψε μια @ref{74f,,ResourceWarning}.


Άλλαξε στην έκδοση 3.6: Προσθήκη της παραμέτρου `source'.



Άλλαξε στην έκδοση 3.15: If no module is passed, test the filter regular expression against
module names created from the path, not only the path itself.

@end deffn

@geindex showwarning() (στη μονάδα warnings)
@anchor{library/warnings warnings showwarning}@anchor{4c6a}
@deffn {Συνάρτηση} warnings.showwarning (message, category, filename, lineno, file=None, line=None)

Γράφει μια προειδοποίηση σε ένα αρχείο. Η προεπιλεγμένη υλοποίηση καλεί τη @code{formatwarning(message, category, filename, lineno, line)} και γράφει τη συμβολοσειρά αποτέλεσμα στο `file', που έχει προεπιλογή το @ref{d05,,sys.stderr}. Μπορείτε να αντικαταστήσετε αυτή τη λειτουργία με οποιοδήποτε καλέσιμο αναθέτοντας στην @code{warnings.showwarning}. Το `line' είναι μια γραμμή πηγαίου κώδικα που θα συμπεριληφθεί στο μήνυμα προειδοποίησης· αν το `line' δεν παρέχεται, η @ref{4c6a,,showwarning()} θα προσπαθήσει να διαβάσει τη γραμμή που καθορίζεται από το `filename' και το `lineno'.
@end deffn

@geindex formatwarning() (στη μονάδα warnings)
@anchor{library/warnings warnings formatwarning}@anchor{1fe7}
@deffn {Συνάρτηση} warnings.formatwarning (message, category, filename, lineno, line=None)

Μορφοποιεί μια προειδοποίηση με τον τυπικό τρόπο. Αυτό επιστρέφει μια συμβολοσειρά που μπορεί να περιέχει ενσωματωμένες αλλαγές γραμμής και τελειώνει σε αλλαγή γραμμής. Το `line' είναι μια γραμμή πηγαίου κώδικα που θα συμπεριληφθεί στο μήνυμα προειδοποίησης· αν το `line' δεν παρέχεται, η @ref{1fe7,,formatwarning()} θα προσπαθήσει να διαβάσει τη γραμμή που καθορίζεται από το `filename' και το `lineno'.
@end deffn

@geindex filterwarnings() (στη μονάδα warnings)
@anchor{library/warnings warnings filterwarnings}@anchor{184b}
@deffn {Συνάρτηση} warnings.filterwarnings (action, message='@w{'}, category=Warning, module='@w{'}, lineno=0, append=False)

Εισάγει μια καταχώριση στη λίστα @ref{1cc,,προδιαγραφών φίλτρων προειδοποιήσεων}. Η καταχώριση εισάγεται στην αρχή από προεπιλογή· αν το `append' είναι αληθές, εισάγεται στο τέλος. Αυτό ελέγχει τους τύπους των επιχειρημάτων, συντάσσει τις κανονικές εκφράσεις `message' και `module', και τις εισάγει ως πλειάδα στη λίστα φίλτρων προειδοποιήσεων. Οι καταχωρίσεις πιο κοντά στην αρχή της λίστας παρακάμπτουν τις καταχωρίσεις αργότερα στη λίστα, αν και οι δύο ταιριάζουν σε μια συγκεκριμένη προειδοποίηση. Τα παραλειφθέντα επιχειρήματα έχουν προεπιλογή μια τιμή που ταιριάζει με τα πάντα.
@end deffn

@geindex simplefilter() (στη μονάδα warnings)
@anchor{library/warnings warnings simplefilter}@anchor{aae}
@deffn {Συνάρτηση} warnings.simplefilter (action, category=Warning, lineno=0, append=False)

Εισάγει μια απλή καταχώριση στη λίστα @ref{1cc,,προδιαγραφών φίλτρων προειδοποιήσεων}. Η σημασία των παραμέτρων της λειτουργίας είναι όπως για την @ref{184b,,filterwarnings()}, αλλά δεν χρειάζονται κανονικές εκφράσεις καθώς το φίλτρο που εισάγεται ταιριάζει πάντα με οποιοδήποτε μήνυμα σε οποιοδήποτε module αρκεί να ταιριάζουν η κατηγορία και ο αριθμός γραμμής.
@end deffn

@geindex resetwarnings() (στη μονάδα warnings)
@anchor{library/warnings warnings resetwarnings}@anchor{4c69}
@deffn {Συνάρτηση} warnings.resetwarnings ()

Επαναφέρει το φίλτρο προειδοποιήσεων. Αυτό απορρίπτει την επίδραση όλων των προηγούμενων κλήσεων στην @ref{184b,,filterwarnings()}, συμπεριλαμβανομένων των επιλογών γραμμής εντολών @ref{1c0,,-W} και κλήσεων στην @ref{aae,,simplefilter()}.
@end deffn

@geindex deprecated() (στη μονάδα warnings)
@anchor{library/warnings warnings deprecated}@anchor{695}
@deffn {Συνάρτηση} @@warnings.deprecated (msg, *, category=DeprecationWarning, stacklevel=1)

Διακοσμητής για να υποδείξει ότι μια κλάση, λειτουργία ή υπερφόρτωση είναι απαρχαιωμένη.

Όταν αυτός ο διακοσμητής εφαρμόζεται σε ένα αντικείμενο, μπορεί να εκδοθούν προειδοποιήσεις απαρχαιώσεως κατά την εκτέλεση όταν το αντικείμενο χρησιμοποιείται. Οι @ref{775,,static type checkers} θα παράγουν επίσης μια διάγνωση κατά τη χρήση του απαρχαιωμένου αντικειμένου.

Χρήση:

@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

Η προειδοποίηση που καθορίζεται από το `category' θα εκδοθεί κατά την εκτέλεση κατά τη χρήση απαρχαιωμένων αντικειμένων. Για λειτουργίες, αυτό συμβαίνει κατά τις κλήσεις· για κλάσεις, κατά την διαδικασία δημιουργίας στιγμιοτύπου και τη δημιουργία υποκλάσεων. Εάν το `category' είναι @code{None}, δεν εκδίδεται καμία προειδοποίηση κατά την εκτέλεση. Το `stacklevel' καθορίζει πού εκδίδεται η προειδοποίηση. Εάν είναι @code{1} (η προεπιλογή), η προειδοποίηση εκδίδεται στον άμεσο καλούντα του απαρχαιωμένου αντικειμένου· αν είναι υψηλότερο, εκδίδεται πιο ψηλά στη στοίβα. Η συμπεριφορά του στατικού ελεγκτή τύπων δεν επηρεάζεται από τα επιχειρήματα `category' και `stacklevel'.

Το μήνυμα απαρχαιώσεως που περνάει στον διακοσμητή αποθηκεύεται στο @code{__deprecated__} χαρακτηριστικό στο διακοσμημένο αντικείμενο. Εάν εφαρμόζεται σε μια υπερφόρτωση, ο διακοσμητής πρέπει να είναι μετά τον @ref{476c,,@@~typing.overload} διακοσμητή για να υπάρχει το χαρακτηριστικό στην υπερφόρτωση όπως επιστρέφεται από τη @ref{a9c,,typing.get_overloads()}.


Added in version 3.13: Δείτε το 
@geindex Python Enhancement Proposals; PEP 702
PEP 702@footnote{https://peps.python.org/pep-0702/}.

@end deffn

@node Διαθέσιμοι Context Managers,Συγχρονισμένη ασφάλεια των Context Managers,Διαθέσιμες λειτουργίες,warnings — Έλεγχος προειδοποιήσεων
@anchor{library/warnings available-context-managers}@anchor{4c7c}
@subsubsection Διαθέσιμοι Context Managers


@geindex catch_warnings (κλάση σε warnings)
@anchor{library/warnings warnings catch_warnings}@anchor{423}
@deffn {Κλάση} warnings.catch_warnings (*, record=False, module=None, action=None, category=Warning, lineno=0, append=False)

Ένας context manager που αντιγράφει και, κατά την έξοδο, επαναφέρει το φίλτρο προειδοποιήσεων και τη @ref{4c6a,,showwarning()} λειτουργία. Αν το `record' επιχείρημα είναι @ref{ef5,,False} (η προεπιλογή) ο context manager επιστρέφει @ref{a65,,None} κατά την είσοδο. Αν το `record' είναι @ref{fcc,,True}, επιστρέφεται μια λίστα που γεμίζει προοδευτικά με αντικείμενα όπως βλέπονται από μια προσαρμοσμένη @code{showwarning()} λειτουργία (που επίσης καταστέλλει την έξοδο στο @code{sys.stdout}). Κάθε αντικείμενο στη λίστα έχει χαρακτηριστικά με τα ίδια ονόματα με τα επιχειρήματα της @code{showwarning()}.

The `module' argument takes a module that will be used instead of the
module returned when you import @code{warnings} whose filter will be
protected. This argument exists primarily for testing the @code{warnings}
module itself.

Αν το όρισμα `action' δεν είναι @code{None}, τα υπόλοιπα ορίσματα περνιούνται στην @ref{aae,,simplefilter()} σαν να είχε κληθεί αμέσως κατά την είσοδο στο context.

Δείτε το @ref{1cc,,Το Φίλτρο Προειδοποιήσεων} για τη σημασία των παραμέτρων `category' και `lineno'.

@cartouche
@quotation Σημείωση 
Δείτε το @ref{4c76,,Συγχρονισμένη ασφάλεια των Context Managers} για λεπτομέρειες σχετικά με την ασφάλεια ταυτόχρονης εκτέλεσης του @ref{423,,catch_warnings} context manager όταν χρησιμοποιείται σε προγράμματα που χρησιμοποιούν πολλαπλές νηματοειδείς διαδικασίες ή ασύγχρονες λειτουργίες.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.11: Προστέθηκαν οι παράμετροι `action', `category', `lineno' και `append'.

@end deffn

@node Συγχρονισμένη ασφάλεια των Context Managers,,Διαθέσιμοι Context Managers,warnings — Έλεγχος προειδοποιήσεων
@anchor{library/warnings concurrent-safety-of-context-managers}@anchor{4c7d}@anchor{library/warnings warning-concurrent-safe}@anchor{4c76}
@subsubsection Συγχρονισμένη ασφάλεια των Context Managers


Η συμπεριφορά του @ref{423,,catch_warnings} context manager εξαρτάται από τη @ref{42f,,sys.flags.context_aware_warnings} σημαία. Αν η σημαία είναι αληθής, ο context manager συμπεριφέρεται με τρόπο ασφαλή για συγχρονισμό και αλλιώς όχι. Η ασφάλεια για συγχρονισμό σημαίνει ότι είναι τόσο ασφαλής για νήματα όσο και ασφαλής για χρήση μέσα σε @ref{39fe,,asyncio coroutines} και εργασίες. Το να είναι ασφαλές για νήματα σημαίνει ότι η συμπεριφορά είναι προβλέψιμη σε ένα πρόγραμμα με πολλαπλά νήματα. Η σημαία έχει προεπιλογή να είναι αληθής για builds με ελεύθερα νήματα και ψευδής αλλιώς.

If the @ref{42f,,context_aware_warnings} flag is false, then
@ref{423,,catch_warnings} will modify the global attributes of the
@code{warnings} module.  This is not safe if used within a concurrent program
(using multiple threads or using asyncio coroutines).  For example, if two
or more threads use the @code{catch_warnings} class at the same time, the
behavior is undefined.

Αν η σημαία είναι αληθής, το @ref{423,,catch_warnings} δεν θα τροποποιήσει τα παγκόσμια χαρακτηριστικά και θα χρησιμοποιήσει αντ” αυτού μια @ref{1a9d,,ContextVar} για να αποθηκεύσει την νεοσυσταθείσα κατάσταση φιλτραρίσματος προειδοποιήσεων. Μια μεταβλητή context παρέχει αποθήκευση τοπική στο νήμα και καθιστά τη χρήση της @code{catch_warnings} ασφαλή για νήματα.

Η παράμετρος `record' του context handler συμπεριφέρεται επίσης διαφορετικά ανάλογα με την τιμή της σημαίας. Όταν το `record' είναι αληθές και η σημαία είναι ψευδής, ο context manager λειτουργεί αντικαθιστώντας και στη συνέχεια αργότερα επαναφέροντας τη @ref{4c6a,,showwarning()} λειτουργία του module. Αυτό δεν είναι ασφαλές για συγχρονισμό.

Όταν το `record' είναι αληθές και η σημαία είναι αληθής, η @ref{4c6a,,showwarning()} λειτουργία δεν αντικαθίσταται. Αντ” αυτού, η κατάσταση καταγραφής υποδεικνύεται από ένα εσωτερικό χαρακτηριστικό στη μεταβλητή context. Σε αυτή την περίπτωση, η @code{showwarning()} λειτουργία δεν θα επαναφερθεί κατά την έξοδο από τον context handler.

Η @ref{42f,,context_aware_warnings} σημαία μπορεί να οριστεί με την @ref{178,,-X context_aware_warnings} επιλογή γραμμής εντολών ή με τη μεταβλητή περιβάλλοντος 
@geindex PYTHON_CONTEXT_AWARE_WARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHON_CONTEXT_AWARE_WARNINGS
@ref{1a83,,PYTHON_CONTEXT_AWARE_WARNINGS}.

@quotation

@cartouche
@quotation Σημείωση 
Είναι πιθανό ότι οι περισσότερες εφαρμογές που επιθυμούν συμπεριφορά ασφαλή για νήματα του warnings module θα θέλουν επίσης να ορίσουν τη @ref{41f,,thread_inherit_context} σημαία σε αληθές. Αυτή η σημαία προκαλεί τα νήματα που δημιουργούνται από την @ref{420,,threading.Thread} να ξεκινούν με ένα αντίγραφο των μεταβλητών context από το νήμα που τα ξεκινά. Όταν είναι αληθής, το context που καθιερώνεται από την @ref{423,,catch_warnings} σε ένα νήμα θα ισχύει επίσης για νέα νήματα που ξεκινούν από αυτό. Αν είναι ψευδής, τα νέα νήματα θα ξεκινούν με μια κενή μεταβλητή context προειδοποιήσεων, που σημαίνει ότι οποιοδήποτε φιλτράρισμα που καθιερώθηκε από έναν @code{catch_warnings} context manager δεν θα είναι πλέον ενεργό.
@end quotation
@end cartouche
@end quotation


Άλλαξε στην έκδοση 3.14: Προστέθηκε η @ref{42f,,sys.flags.context_aware_warnings} σημαία και η χρήση μιας μεταβλητής context για την @ref{423,,catch_warnings} αν η σημαία είναι αληθής. Οι προηγούμενες εκδόσεις της Python συμπεριφέρονταν σαν να ήταν η σημαία πάντα ορισμένη σε ψευδής.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node dataclasses — Data Classes,contextlib — Utilities for with-statement contexts,warnings — Έλεγχος προειδοποιήσεων,Python Runtime Services
@anchor{library/dataclasses doc}@anchor{4c7e}@anchor{library/dataclasses dataclasses-data-classes}@anchor{4c7f}@anchor{library/dataclasses module-dataclasses}@anchor{32}@anchor{library/dataclasses translation-repo}@anchor{4c80}
@subsection @code{dataclasses} — Data Classes


@geindex module; dataclasses

`Source code:' Lib/dataclasses.py@footnote{https://github.com/python/cpython/tree/main/Lib/dataclasses.py}


__________________________________________________________________


This module provides a decorator and functions for automatically
adding generated @ref{1e57,,special methods} such as @ref{2fa,,__init__()} and
@ref{1bc,,__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/}.

The member variables to use in these generated methods are defined
using 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/} type annotations.  For example, this code:

@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.


Added in version 3.7.


@menu
* Module contents: Module contents<6>. 
* Post-init processing:: 
* Class variables:: 
* Init-only variables:: 
* Frozen instances:: 
* Inheritance:: 
* Re-ordering of keyword-only parameters in __init__(): Re-ordering of keyword-only parameters in __init__. 
* Default factory functions:: 
* Mutable default values:: 
* Descriptor-typed fields:: 

@end menu

@node Module contents<6>,Post-init processing,,dataclasses — Data Classes
@anchor{library/dataclasses module-contents}@anchor{4c81}
@subsubsection Module contents


@geindex dataclass() (στη μονάδα dataclasses)
@anchor{library/dataclasses dataclasses dataclass}@anchor{6e6}
@deffn {Συνάρτηση} @@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{b18,,decorator} that is used to add generated
@ref{1e57,,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{110a,,type annotation}.  With two
exceptions described below, nothing in @code{@@dataclass}
examines the type specified in the variable annotation.

The order of the fields in all of the generated methods is the
order in which they appear in the class definition.

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{2fa,,__init__()} method will be
generated.

If the class already defines @code{__init__()}, this parameter is
ignored.

@item 
`repr': If true (the default), a @ref{1bc,,__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{ec0,,__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{1645,,__lt__()},
@ref{16af,,__le__()}, @ref{16b0,,__gt__()}, and @ref{16b1,,__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{277,,ValueError} is raised.

If the class already defines any of @code{__lt__()},
@code{__le__()}, @code{__gt__()}, or @code{__ge__()}, then
@ref{291,,TypeError} is raised.

@item 
`unsafe_hash': If true, force @code{dataclasses} to create a
@ref{ec1,,__hash__()} method, even though it may not be safe to do so.
Otherwise, generate a @code{__hash__()} method according to how
`eq' and `frozen' are set.
The default value is @code{False}.

@code{__hash__()} is used by built-in @ref{9e2,,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{ec1,,__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{291,,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{e4d,,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.
See the @ref{4c82,,discussion} below.

If @ref{256d,,__setattr__()} or @ref{256e,,__delattr__()} is defined in the class
and `frozen' is true, then @ref{291,,TypeError} is raised.

@item 
`match_args': If true (the default is @code{True}), the
@ref{1e6c,,__match_args__} tuple will be created from the list of
non keyword-only parameters to the generated @ref{2fa,,__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


Added in 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{2fa,,__init__()}
parameter generated from a keyword-only field must be specified
with a keyword when @code{__init__()} is called. See the @ref{253c,,parameter}
glossary entry for details.  Also see the
@ref{1907,,KW_ONLY} section.

Keyword-only fields are not included in @code{__match_args__}.
@end itemize

@quotation


Added in version 3.10.

@end quotation


@itemize -

@item 
`slots': If true (the default is @code{False}), @ref{188d,,__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{291,,TypeError}
is raised.
@end itemize

@quotation

@cartouche
@quotation Προειδοποίηση 
Passing parameters to a base class @ref{a22,,__init_subclass__()}
when using @code{slots=True} will result in a @ref{291,,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


Added in version 3.10.



Άλλαξε στην έκδοση 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{25af,,overriding them}.
Therefore, do not use @code{__slots__} to retrieve the field names of a
dataclass. Use @ref{1b4f,,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{1399,,weakref-able}.
It is an error to specify @code{weakref_slot=True}
without also specifying @code{slots=True}.
@end itemize

@quotation


Added in version 3.11.

@end quotation

@code{field}s may optionally specify a default value, using normal
Python syntax:

@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{2fa,,__init__()} method, which will be defined as:

@example
def __init__(self, a: int, b: int = 0):
@end example

@ref{291,,TypeError} will be raised if a field without a default value
follows a field with a default value.  This is true whether this
occurs in a single class, or as a result of class inheritance.
@end deffn

@geindex field() (στη μονάδα dataclasses)
@anchor{library/dataclasses dataclasses field}@anchor{1945}
@deffn {Συνάρτηση} dataclasses.field (*, default=MISSING, default_factory=MISSING, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=MISSING, doc=None)

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

As shown above, the @ref{1906,,MISSING} value is a sentinel object used to
detect if some parameters are provided by the user. This sentinel is
used because @code{None} is a valid value for some parameters with
a distinct meaning.  No code should directly use the @code{MISSING} value.

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{2fa,,__init__()} method.

@item 
`repr': If true (the default), this field is included in the
string returned by the generated @ref{1bc,,__repr__()} method.

@item 
`hash': This can be a bool or @code{None}.  If true, this field is
included in the generated @ref{ec1,,__hash__()} method.  If false,
this field is excluded from the generated @code{__hash__()}.
If @code{None} (the default), use the value of `compare': this would
normally be the expected behavior, since a field should be included
in the hash if it’s used for comparisons.  Setting this value to anything
other than @code{None} is discouraged.

One possible reason to set @code{hash=False} but @code{compare=True}
would be if a field is expensive to compute a hash value for,
that field is needed for equality testing, and there are other
fields that contribute to the type’s hash value.  Even if a field
is excluded from the hash, it will still be used for comparisons.

@item 
`compare': If true (the default), this field is included in the
generated equality and comparison methods (@ref{ec0,,__eq__()},
@ref{16b0,,__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{189,,MappingProxyType()} to make it read-only, and exposed
on the @ref{1b6e,,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{2fa,,__init__()} method’s
parameters are computed.

Keyword-only fields are also not included in @code{__match_args__}.
@end itemize

@quotation


Added in version 3.10.

@end quotation


@itemize -

@item 
`doc': optional docstring for this field.
@end itemize

@quotation


Added in version 3.14.

@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{6e6,,@@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.


Άλλαξε στην έκδοση 3.15: If `metadata' is @code{None}, use an empty @ref{182,,frozendict}, instead
of a @ref{189,,MappingProxyType()} of an empty @ref{188,,dict}.

@end deffn

@geindex Field (κλάση σε dataclasses)
@anchor{library/dataclasses dataclasses Field}@anchor{1b6e}
@deffn {Κλάση} dataclasses.Field

@code{Field} objects describe each defined field. These objects
are created internally, and are returned by the @ref{1b4f,,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{1945,,field()} function.
@end itemize

Other attributes may exist, but they are private and must not be
inspected or relied on.
@end deffn

@geindex InitVar (κλάση σε dataclasses)
@anchor{library/dataclasses dataclasses InitVar}@anchor{1dae}
@deffn {Κλάση} dataclasses.InitVar

@code{InitVar[T]} type annotations describe variables that are @ref{4c83,,init-only}. Fields annotated with @code{InitVar}
are considered pseudo-fields, and thus are neither returned by the
@ref{1b4f,,fields()} function nor used in any way except adding them as
parameters to @ref{2fa,,__init__()} and an optional
@ref{4c84,,__post_init__()}.
@end deffn

@geindex fields() (στη μονάδα dataclasses)
@anchor{library/dataclasses dataclasses fields}@anchor{1b4f}
@deffn {Συνάρτηση} dataclasses.fields (class_or_instance)

Returns a tuple of @ref{1b6e,,Field} objects that define the fields for this
dataclass.  Accepts either a dataclass, or an instance of a dataclass.
Raises @ref{291,,TypeError} if not passed a dataclass or instance of one.
Does not return pseudo-fields which are @code{ClassVar} or @code{InitVar}.
@end deffn

@geindex asdict() (στη μονάδα dataclasses)
@anchor{library/dataclasses dataclasses asdict}@anchor{190d}
@deffn {Συνάρτηση} 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,
frozendicts, lists, and tuples are recursed into.  Other objects are copied
with @ref{f2b,,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

To create a shallow copy, the following workaround may be used:

@example
@{field.name: getattr(obj, field.name) for field in fields(obj)@}
@end example

@code{asdict()} raises @ref{291,,TypeError} if `obj' is not a dataclass
instance.
@end deffn

@geindex astuple() (στη μονάδα dataclasses)
@anchor{library/dataclasses dataclasses astuple}@anchor{190e}
@deffn {Συνάρτηση} 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, frozendicts, lists,
and tuples are recursed into. Other objects are copied with
@ref{f2b,,copy.deepcopy()}.

Continuing from the previous example:

@example
assert astuple(p) == (10, 20)
assert astuple(c) == ([(0, 0), (10, 4)],)
@end example

To create a shallow copy, the following workaround may be used:

@example
tuple(getattr(obj, field.name) for field in dataclasses.fields(obj))
@end example

@code{astuple()} raises @ref{291,,TypeError} if `obj' is not a dataclass
instance.
@end deffn

@geindex make_dataclass() (στη μονάδα dataclasses)
@anchor{library/dataclasses dataclasses make_dataclass}@anchor{1a84}
@deffn {Συνάρτηση} 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, decorator=dataclass)

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{a9a,,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{6e6,,@@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.

The `decorator' parameter is a callable that will be used to create the dataclass.
It should take the class object as a first argument and the same keyword arguments
as @ref{6e6,,@@dataclass}. By default, the @code{@@dataclass}
function is used.

This function is not strictly required, because any Python
mechanism for creating a new class with @ref{66b,,__annotations__} can
then apply the @ref{6e6,,@@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

Is equivalent to:

@example
@@dataclass
class C:
    x: int
    y: 'typing.Any'
    z: int = 5

    def add_one(self):
        return self.x + 1
@end example


Added in version 3.14: Added the `decorator' parameter.

@end deffn

@geindex replace() (στη μονάδα dataclasses)
@anchor{library/dataclasses dataclasses replace}@anchor{1c70}
@deffn {Συνάρτηση} 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{291,,TypeError}.  If keys in `changes' are not
field names of the given dataclass, raises @code{TypeError}.

The newly returned object is created by calling the @ref{2fa,,__init__()}
method of the dataclass.  This ensures that
@ref{4c84,,__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{4c84,,__post_init__()}.

It is an error for `changes' to contain any fields that are
defined as having @code{init=False}.  A @ref{277,,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{4c84,,__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{45a,,copy.replace()}.
@end deffn

@geindex is_dataclass() (στη μονάδα dataclasses)
@anchor{library/dataclasses dataclasses is_dataclass}@anchor{1e0e}
@deffn {Συνάρτηση} 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}.

If you need to know if a class is an instance of a dataclass (and
not a dataclass itself), then add a further check for @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 (στη μονάδα dataclasses)
@anchor{library/dataclasses dataclasses MISSING}@anchor{1906}
@deffn {Δεδομένα} dataclasses.MISSING

A sentinel value signifying a missing default or default_factory.
@end deffn

@geindex KW_ONLY (στη μονάδα dataclasses)
@anchor{library/dataclasses dataclasses KW_ONLY}@anchor{1907}
@deffn {Δεδομένα} 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{2fa,,__init__()} parameters that must be specified as keywords when
the class is instantiated.

In this example, the fields @code{y} and @code{z} will be marked as keyword-only fields:

@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}.


Added in version 3.10.

@end deffn

@geindex FrozenInstanceError
@anchor{library/dataclasses dataclasses FrozenInstanceError}@anchor{190f}
@deffn {Εξαίρεση} dataclasses.FrozenInstanceError

Raised when an implicitly defined @ref{256d,,__setattr__()} or
@ref{256e,,__delattr__()} is called on a dataclass which was defined with
@code{frozen=True}. It is a subclass of @ref{1a9,,AttributeError}.
@end deffn

@node Post-init processing,Class variables,Module contents<6>,dataclasses — Data Classes
@anchor{library/dataclasses id1}@anchor{4c85}@anchor{library/dataclasses post-init-processing}@anchor{4c86}
@subsubsection Post-init processing


@geindex __post_init__() (στη μονάδα dataclasses)
@anchor{library/dataclasses dataclasses __post_init__}@anchor{4c84}
@deffn {Συνάρτηση} dataclasses.__post_init__ ()

When defined on the class, it will be called by the generated
@ref{2fa,,__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.

Among other uses, this allows for initializing field values that
depend on one or more other fields.  For example:

@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{2fa,,__init__()} method generated by @ref{6e6,,@@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{4c84,,__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{1c70,,replace()} handles @code{init=False} fields.

@node Class variables,Init-only variables,Post-init processing,dataclasses — Data Classes
@anchor{library/dataclasses class-variables}@anchor{4c87}@anchor{library/dataclasses dataclasses-class-variables}@anchor{4c88}
@subsubsection Class variables


One of the few places where @ref{6e6,,@@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{76e,,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{1b4f,,fields()} function.

@node Init-only variables,Frozen instances,Class variables,dataclasses — Data Classes
@anchor{library/dataclasses dataclasses-init-only-variables}@anchor{4c83}@anchor{library/dataclasses init-only-variables}@anchor{4c89}
@subsubsection Init-only variables


Another place where @ref{6e6,,@@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 @ref{1dae,,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{1b4f,,fields()} function.  Init-only fields are added as
parameters to the generated @ref{2fa,,__init__()} method, and are passed to
the optional @ref{4c84,,__post_init__()} method.  They are not otherwise used
by dataclasses.

For example, suppose a field will be initialized from a database, if a
value is not provided when creating the class:

@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{1b4f,,fields()} will return @ref{1b6e,,Field} objects for @code{i} and
@code{j}, but not for @code{database}.

@node Frozen instances,Inheritance,Init-only variables,dataclasses — Data Classes
@anchor{library/dataclasses dataclasses-frozen}@anchor{4c82}@anchor{library/dataclasses frozen-instances}@anchor{4c8a}
@subsubsection Frozen instances


It is not possible to create truly immutable Python objects.  However,
by passing @code{frozen=True} to the @ref{6e6,,@@dataclass} decorator you can
emulate immutability.  In that case, dataclasses will add
@ref{256d,,__setattr__()} and @ref{256e,,__delattr__()} methods to the class.  These
methods will raise a @ref{190f,,FrozenInstanceError} when invoked.

There is a tiny performance penalty when using @code{frozen=True}:
@ref{2fa,,__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 Inheritance,Re-ordering of keyword-only parameters in __init__,Frozen instances,dataclasses — Data Classes
@anchor{library/dataclasses dataclasses-inheritance}@anchor{4c8b}@anchor{library/dataclasses inheritance}@anchor{4c8c}
@subsubsection Inheritance


When the dataclass is being created by the @ref{6e6,,@@dataclass} decorator,
it looks through all of the class’s base classes in reverse MRO (that
is, starting at @ref{e4d,,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{326,,int}, as specified in class @code{C}.

The generated @ref{2fa,,__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__,Default factory functions,Inheritance,dataclasses — Data Classes
@anchor{library/dataclasses re-ordering-of-keyword-only-parameters-in-init}@anchor{4c8d}
@subsubsection Re-ordering of keyword-only parameters in @code{__init__()}


After the parameters needed for @ref{2fa,,__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

Note that the parameters have been re-ordered from how they appear in
the list of fields: parameters derived from regular fields are
followed by parameters derived from keyword-only fields.

The relative ordering of keyword-only parameters is maintained in the
re-ordered @code{__init__()} parameter list.

@node Default factory functions,Mutable default values,Re-ordering of keyword-only parameters in __init__,dataclasses — Data Classes
@anchor{library/dataclasses default-factory-functions}@anchor{4c8e}
@subsubsection Default factory functions


If a @ref{1945,,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{2fa,,__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 Mutable default values,Descriptor-typed fields,Default factory functions,dataclasses — Data Classes
@anchor{library/dataclasses mutable-default-values}@anchor{4c8f}
@subsubsection Mutable default values


Python stores default member variable values in class attributes.
Consider this example, not using dataclasses:

@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.

Using dataclasses, `if' this code was valid:

@example
@@dataclass
class D:
    x: list = []      # This code raises ValueError
    def add(self, element):
        self.x.append(element)
@end example

it would generate code similar to:

@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{6e6,,@@dataclass} decorator will raise a @ref{277,,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.

Using default factory functions is a way to create new instances of
mutable types as default values for fields:

@example
@@dataclass
class D:
    x: list = field(default_factory=list)

assert D().x is not D().x
@end example


Άλλαξε στην έκδοση 3.11: Instead of looking for and disallowing objects of type @ref{4d9,,list},
@ref{188,,dict}, or @ref{42b,,set}, unhashable objects are now not allowed as
default values.  Unhashability is used to approximate
mutability.


@node Descriptor-typed fields,,Mutable default values,dataclasses — Data Classes
@anchor{library/dataclasses descriptor-typed-fields}@anchor{4c90}
@subsubsection Descriptor-typed fields


Fields that are assigned @ref{100d,,descriptor objects} as their
default value have the following special behaviors:


@itemize *

@item 
The value for the field passed to the dataclass’s @ref{2fa,,__init__()} method is
passed to the descriptor’s @ref{25aa,,__set__()} method rather than overwriting the
descriptor object.

@item 
Similarly, when getting or setting the field, the descriptor’s
@ref{188a,,__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{6e6,,@@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{1a9,,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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node contextlib — Utilities for with-statement contexts,abc — Abstract Base Classes,dataclasses — Data Classes,Python Runtime Services
@anchor{library/contextlib doc}@anchor{4c91}@anchor{library/contextlib contextlib-utilities-for-with-statement-contexts}@anchor{4c92}@anchor{library/contextlib module-contextlib}@anchor{27}@anchor{library/contextlib translation-repo}@anchor{4c93}
@subsection @code{contextlib} — Utilities for @code{with}-statement contexts


@geindex module; contextlib

`Source code:' Lib/contextlib.py@footnote{https://github.com/python/cpython/tree/main/Lib/contextlib.py}


__________________________________________________________________


This module provides utilities for common tasks involving the @ref{20a,,with}
statement. For more information see also @ref{2601,,Τύποι Διαχείρισης Περιεχομένου} and
@ref{2572,,Με τους Διαχειριστές Περιβάλλοντος Δήλωσης}.

@menu
* Utilities:: 
* Examples and Recipes: Examples and Recipes<2>. 
* Single use@comma{} reusable and reentrant context managers: Single use reusable and reentrant context managers. 

@end menu

@node Utilities,Examples and Recipes<2>,,contextlib — Utilities for with-statement contexts
@anchor{library/contextlib utilities}@anchor{4c94}
@subsubsection Utilities


Functions and classes provided:

@geindex AbstractContextManager (κλάση σε contextlib)
@anchor{library/contextlib contextlib AbstractContextManager}@anchor{104d}
@deffn {Κλάση} contextlib.AbstractContextManager

An @ref{155f,,abstract base class} for classes that implement
@ref{9c6,,__enter__()} and @ref{16a5,,__exit__()}. A default
implementation for @code{__enter__()} is provided which returns
@code{self} while @code{__exit__()} is an abstract method which by default
returns @code{None}. See also the definition of @ref{2601,,Τύποι Διαχείρισης Περιεχομένου}.


Added in version 3.6.

@end deffn

@geindex AbstractAsyncContextManager (κλάση σε contextlib)
@anchor{library/contextlib contextlib AbstractAsyncContextManager}@anchor{eeb}
@deffn {Κλάση} contextlib.AbstractAsyncContextManager

An @ref{155f,,abstract base class} for classes that implement
@ref{2613,,__aenter__()} and @ref{1bad,,__aexit__()}. A default
implementation for @code{__aenter__()} is provided which returns
@code{self} while @code{__aexit__()} is an abstract method which by default
returns @code{None}. See also the definition of
@ref{9f3,,Ασύγχρονοι Διαχειριστές Περιβάλλοντος}.


Added in version 3.7.

@end deffn

@geindex contextmanager() (στη μονάδα contextlib)
@anchor{library/contextlib contextlib contextmanager}@anchor{20e}
@deffn {Συνάρτηση} @@contextlib.contextmanager

This function is a @ref{b18,,decorator} that can be used to define a factory
function for @ref{20a,,with} statement context managers, without needing to
create a class or separate @ref{9c6,,__enter__()} and @ref{16a5,,__exit__()} methods.

While many objects natively support use in with statements, sometimes a
resource needs to be managed that isn’t a context manager in its own right,
and doesn’t implement a @code{close()} method for use with @code{contextlib.closing}.

An abstract example would be the following to ensure correct resource
management:

@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

The function being decorated must return a @ref{1409,,generator}-iterator when
called. This iterator must yield exactly one value, which will be bound to
the targets in the @ref{20a,,with} statement’s @code{as} clause, if any.

At the point where the generator yields, the block nested in the @ref{20a,,with}
statement is executed.  The generator is then resumed after the block is exited.
If an unhandled exception occurs in the block, it is reraised inside the
generator at the point where the yield occurred.  Thus, you can use a
@ref{ad6,,try}…@ref{447,,except}…@ref{44c,,finally} statement to trap
the error (if any), or ensure that some cleanup takes place. If an exception is
trapped merely in order to log it or to perform some action (rather than to
suppress it entirely), the generator must reraise that exception. Otherwise the
generator context manager will indicate to the @code{with} statement that
the exception has been handled, and execution will resume with the statement
immediately following the @code{with} statement.

@code{contextmanager()} uses @ref{20c,,ContextDecorator} so the context managers
it creates can be used as decorators as well as in @ref{20a,,with} statements.
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 @code{contextmanager()} to meet the requirement that context
managers support multiple invocations in order to be used as decorators).


Άλλαξε στην έκδοση 3.2: Use of @ref{20c,,ContextDecorator}.

@end deffn

@geindex asynccontextmanager() (στη μονάδα contextlib)
@anchor{library/contextlib contextlib asynccontextmanager}@anchor{20f}
@deffn {Συνάρτηση} @@contextlib.asynccontextmanager

Similar to @ref{20e,,contextmanager()}, but creates an
@ref{9f3,,asynchronous context manager}.

This function is a @ref{b18,,decorator} that can be used to define a factory
function for @ref{20b,,async with} statement asynchronous context managers,
without needing to create a class or separate @ref{2613,,__aenter__()} and
@ref{1bad,,__aexit__()} methods. It must be applied to an @ref{2692,,asynchronous generator} function.

A simple example:

@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


Added in version 3.7.


Context managers defined with @code{asynccontextmanager()} can be used
either as decorators or with @ref{20b,,async with} statements:

@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 @code{asynccontextmanager()} to meet the requirement that context
managers support multiple invocations in order to be used as decorators.


Άλλαξε στην έκδοση 3.10: Async context managers created with @code{asynccontextmanager()} can
be used as decorators.

@end deffn

@geindex closing() (στη μονάδα contextlib)
@anchor{library/contextlib contextlib closing}@anchor{3ec}
@deffn {Συνάρτηση} contextlib.closing (thing)

Return a context manager that closes `thing' upon completion of the block.  This
is basically equivalent to:

@example
from contextlib import contextmanager

@@contextmanager
def closing(thing):
    try:
        yield thing
    finally:
        thing.close()
@end example

And lets you write code like this:

@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

without needing to explicitly close @code{page}.  Even if an error occurs,
@code{page.close()} will be called when the @ref{20a,,with} block is exited.

@cartouche
@quotation Σημείωση 
Most types managing resources support the @ref{478,,context manager} protocol,
which closes `thing' on leaving the @ref{20a,,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{57f,,urlopen()} would normally be used in a context manager.
@end quotation
@end cartouche
@end deffn

@geindex aclosing() (στη μονάδα contextlib)
@anchor{library/contextlib contextlib aclosing}@anchor{bc9}
@deffn {Συνάρτηση} 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{428,,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).


Added in version 3.10.

@end deffn

@geindex nullcontext() (στη μονάδα contextlib)
@anchor{library/contextlib simplifying-support-for-single-optional-context-managers}@anchor{4c95}@anchor{library/contextlib contextlib nullcontext}@anchor{bca}
@deffn {Συνάρτηση} contextlib.nullcontext (enter_result=None)

Return a context manager that returns `enter_result' from @ref{9c6,,__enter__()}, but
otherwise does nothing. It is intended to be used as a stand-in for an
optional context manager, for example:

@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

An example using `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{9f3,,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


Added in version 3.7.



Άλλαξε στην έκδοση 3.10: @ref{9d2,,asynchronous context manager} support was added.

@end deffn

@geindex suppress() (στη μονάδα contextlib)
@anchor{library/contextlib contextlib suppress}@anchor{12d3}
@deffn {Συνάρτηση} 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.

As with any other mechanism that completely suppresses exceptions, this
context manager should be used only to cover very specific errors where
silently continuing with program execution is known to be the right
thing to do.

For example:

@example
from contextlib import suppress

with suppress(FileNotFoundError):
    os.remove('somefile.tmp')

with suppress(FileNotFoundError):
    os.remove('someotherfile.tmp')
@end example

This code is equivalent to:

@example
try:
    os.remove('somefile.tmp')
except FileNotFoundError:
    pass

try:
    os.remove('someotherfile.tmp')
except FileNotFoundError:
    pass
@end example

This context manager is @ref{4c96,,reentrant}.

If the code within the @code{with} block raises a
@ref{767,,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{1c3f,,derive()}
method.


Added in version 3.4.



Άλλαξε στην έκδοση 3.12: @code{suppress} now supports suppressing exceptions raised as
part of a @ref{767,,BaseExceptionGroup}.

@end deffn

@geindex redirect_stdout() (στη μονάδα contextlib)
@anchor{library/contextlib contextlib redirect_stdout}@anchor{119f}
@deffn {Συνάρτηση} contextlib.redirect_stdout (new_target)

Context manager for temporarily redirecting @ref{e9c,,sys.stdout} to
another @ref{156c,,file object}.

This tool adds flexibility to existing functions or classes whose output
is hardwired to @ref{e9c,,sys.stdout}.

For example, the output of @ref{ca9,,help()} normally is sent to `sys.stdout'.
You can capture that output in a string by redirecting the output to an
@ref{12d4,,io.StringIO} object. The replacement stream is returned from the
@ref{9c6,,__enter__()} method and so is available as the target of the
@ref{20a,,with} statement:

@example
with redirect_stdout(io.StringIO()) as f:
    help(pow)
s = f.getvalue()
@end example

To send the output of @ref{ca9,,help()} to a file on disk, redirect the output
to a regular file:

@example
with open('help.txt', 'w') as f:
    with redirect_stdout(f):
        help(pow)
@end example

To send the output of @ref{ca9,,help()} to `sys.stderr':

@example
with redirect_stdout(sys.stderr):
    help(pow)
@end example

Note that the global side effect on @ref{e9c,,sys.stdout} means that this
context manager is not suitable for use in library code and most threaded
applications. It also has no effect on the output of subprocesses.
However, it is still a useful approach for many utility scripts.

This context manager is @ref{4c96,,reentrant}.


Added in version 3.4.

@end deffn

@geindex redirect_stderr() (στη μονάδα contextlib)
@anchor{library/contextlib contextlib redirect_stderr}@anchor{119e}
@deffn {Συνάρτηση} contextlib.redirect_stderr (new_target)

Similar to @ref{119f,,redirect_stdout()} but redirecting the global
@ref{d05,,sys.stderr} to another @ref{156c,,file object}.

This context manager is @ref{4c96,,reentrant}.


Added in version 3.5.

@end deffn

@geindex chdir() (στη μονάδα contextlib)
@anchor{library/contextlib contextlib chdir}@anchor{a01}
@deffn {Συνάρτηση} 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{a02,,chdir()}, it changes the current
working directory upon entering and restores the old one on exit.

This context manager is @ref{4c96,,reentrant}.


Added in version 3.11.

@end deffn

@geindex ContextDecorator (κλάση σε contextlib)
@anchor{library/contextlib contextlib ContextDecorator}@anchor{20c}
@deffn {Κλάση} contextlib.ContextDecorator

A base class that enables a context manager to also be used as a decorator.

Context managers inheriting from @code{ContextDecorator} have to implement
@ref{9c6,,__enter__()} and @ref{16a5,,__exit__()} as normal.
@code{__exit__} retains its optional
exception handling even when used as a decorator.

@code{ContextDecorator} is used by @ref{20e,,contextmanager()}, so you get this
functionality automatically.

Example of @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

This change is just syntactic sugar for any construct of the following form:

@example
def f():
    with cm():
        # Do stuff
@end example

@code{ContextDecorator} lets you instead write:

@example
@@cm()
def f():
    # Do stuff
@end example

It makes it clear that the @code{cm} applies to the whole function, rather than
just a piece of it (and saving an indentation level is nice, too).

Existing context managers that already have a base class can be extended by
using @code{ContextDecorator} as a mixin class:

@example
from contextlib import ContextDecorator

class mycontext(ContextBaseClass, ContextDecorator):
    def __enter__(self):
        return self

    def __exit__(self, *exc):
        return False
@end example

@cartouche
@quotation Σημείωση 
As the decorated function must be able to be called multiple times, the
underlying context manager must support use in multiple @ref{20a,,with}
statements. If this is not the case, then the original construct with the
explicit @code{with} statement inside the function should be used.
@end quotation
@end cartouche

When the decorated callable is a generator function, coroutine function, or
asynchronous generator function, the returned wrapper is of the same kind
and keeps the context manager open for the lifetime of the iteration or
await rather than only for the call that creates the generator or coroutine
object.  Wrapped generators and asynchronous generators are explicitly
closed when iteration ends, as if by @ref{3ec,,closing()} or @ref{bc9,,aclosing()}.

@cartouche
@quotation Σημείωση 
For asynchronous generators the wrapper re-yields each value with
@code{async for}; values sent with @ref{cab,,asend()} and exceptions
thrown with @ref{906,,athrow()} are not forwarded to the wrapped
generator.
@end quotation
@end cartouche


Added in version 3.2.



Άλλαξε στην έκδοση 3.15: Decorating a generator function, coroutine function, or asynchronous
generator function now keeps the context manager open across iteration
or await.  Previously the context manager exited as soon as the
generator or coroutine object was created.

@end deffn

@geindex AsyncContextDecorator (κλάση σε contextlib)
@anchor{library/contextlib contextlib AsyncContextDecorator}@anchor{20d}
@deffn {Κλάση} contextlib.AsyncContextDecorator

Similar to @ref{20c,,ContextDecorator}, but the context manager is entered
and exited with @ref{20b,,async with}.  Decorate coroutine functions and
asynchronous generator functions with this class; the returned wrapper is
of the same kind.

@cartouche
@quotation Σημείωση 
Synchronous functions and generators are accepted, but the wrapper is
always asynchronous, so the decorated callable must then be awaited or
iterated with @code{async for}.  If that change of calling convention is
not intended, use @ref{20c,,ContextDecorator} instead.
@end quotation
@end cartouche

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


Added in version 3.10.



Άλλαξε στην έκδοση 3.15: Decorating an asynchronous generator function now keeps the context
manager open across iteration.  Previously the context manager exited
as soon as the generator object was created.  Synchronous functions
and synchronous generator functions are also now accepted, with an
asynchronous wrapper returned.

@end deffn

@geindex ExitStack (κλάση σε contextlib)
@anchor{library/contextlib contextlib ExitStack}@anchor{208}
@deffn {Κλάση} contextlib.ExitStack

A context manager that is designed to make it easy to programmatically
combine other context managers and cleanup functions, especially those
that are optional or otherwise driven by input data.

For example, a set of files may easily be handled in a single with
statement as follows:

@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{9c6,,__enter__()} method returns the @code{ExitStack} instance, and
performs no additional operations.

Each instance maintains a stack of registered callbacks that are called in
reverse order when the instance is closed (either explicitly or implicitly
at the end of a @ref{20a,,with} statement). Note that callbacks are `not'
invoked implicitly when the context stack instance is garbage collected.

This stack model is used so that context managers that acquire their
resources in their @code{__init__} method (such as file objects) can be
handled correctly.

Since registered callbacks are invoked in the reverse order of
registration, this ends up behaving as if multiple nested @ref{20a,,with}
statements had been used with the registered set of callbacks. This even
extends to exception handling - if an inner callback suppresses or replaces
an exception, then outer callbacks will be passed arguments based on that
updated state.

This is a relatively low level API that takes care of the details of
correctly unwinding the stack of exit callbacks. It provides a suitable
foundation for higher level context managers that manipulate the exit
stack in application specific ways.


Added in version 3.3.


@geindex enter_context() (μέθοδος της contextlib.ExitStack)
@anchor{library/contextlib contextlib ExitStack enter_context}@anchor{9d0}
@deffn {Μέθοδος} enter_context (cm)

Enters a new context manager and adds its @ref{16a5,,__exit__()} method to
the callback stack. The return value is the result of the context
manager’s own @ref{9c6,,__enter__()} method.

These context managers may suppress exceptions just as they normally
would if used directly as part of a @ref{20a,,with} statement.


Άλλαξε στην έκδοση 3.11: Raises @ref{291,,TypeError} instead of @ref{1a9,,AttributeError} if `cm'
is not a context manager.



Άλλαξε στην έκδοση 3.15: Added support for arbitrary descriptors @code{__enter__()} and
@code{__exit__()}.

@end deffn

@geindex push() (μέθοδος της contextlib.ExitStack)
@anchor{library/contextlib contextlib ExitStack push}@anchor{4c97}
@deffn {Μέθοδος} push (exit)

Adds a context manager’s @ref{16a5,,__exit__()} method to the callback stack.

As @code{__enter__} is `not' invoked, this method can be used to cover
part of an @ref{9c6,,__enter__()} implementation with a context manager’s own
@ref{16a5,,__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{16a5,,__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{16a5,,__exit__()} methods can.

The passed in object is returned from the function, allowing this
method to be used as a function decorator.


Άλλαξε στην έκδοση 3.15: Added support for arbitrary descriptors @code{__exit__()}.

@end deffn

@geindex callback() (μέθοδος της contextlib.ExitStack)
@anchor{library/contextlib contextlib ExitStack callback}@anchor{e45}
@deffn {Μέθοδος} callback (callback, /, *args, **kwds)

Accepts an arbitrary callback function and arguments and adds it to
the callback stack.

Unlike the other methods, callbacks added this way cannot suppress
exceptions (as they are never passed the exception details).

The passed in callback is returned from the function, allowing this
method to be used as a function decorator.
@end deffn

@geindex pop_all() (μέθοδος της contextlib.ExitStack)
@anchor{library/contextlib contextlib ExitStack pop_all}@anchor{4c98}
@deffn {Μέθοδος} pop_all ()

Transfers the callback stack to a fresh @code{ExitStack} instance
and returns it. No callbacks are invoked by this operation - instead,
they will now be invoked when the new stack is closed (either
explicitly or implicitly at the end of a @ref{20a,,with} statement).

For example, a group of files can be opened as an «all or nothing»
operation as follows:

@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() (μέθοδος της contextlib.ExitStack)
@anchor{library/contextlib contextlib ExitStack close}@anchor{4c99}
@deffn {Μέθοδος} close ()

Immediately unwinds the callback stack, invoking callbacks in the
reverse order of registration. For any context managers and exit
callbacks registered, the arguments passed in will indicate that no
exception occurred.
@end deffn
@end deffn

@geindex AsyncExitStack (κλάση σε contextlib)
@anchor{library/contextlib contextlib AsyncExitStack}@anchor{209}
@deffn {Κλάση} contextlib.AsyncExitStack

An @ref{9f3,,asynchronous context manager}, similar
to @ref{208,,ExitStack}, that supports combining both synchronous and
asynchronous context managers, as well as having coroutines for
cleanup logic.

The @ref{4c99,,close()} method is not implemented; @ref{4c9a,,aclose()} must be used
instead.

@geindex enter_async_context() (μέθοδος της contextlib.AsyncExitStack)
@anchor{library/contextlib contextlib AsyncExitStack enter_async_context}@anchor{9d1}
@deffn {Μέθοδος} async enter_async_context (cm)

Similar to @ref{9d0,,ExitStack.enter_context()} but expects an asynchronous context
manager.


Άλλαξε στην έκδοση 3.11: Raises @ref{291,,TypeError} instead of @ref{1a9,,AttributeError} if `cm'
is not an asynchronous context manager.



Άλλαξε στην έκδοση 3.15: Added support for arbitrary descriptors @code{__aenter__()} and @code{__aexit__()}.

@end deffn

@geindex push_async_exit() (μέθοδος της contextlib.AsyncExitStack)
@anchor{library/contextlib contextlib AsyncExitStack push_async_exit}@anchor{4c9b}
@deffn {Μέθοδος} push_async_exit (exit)

Similar to @ref{4c97,,ExitStack.push()} but expects either an asynchronous context manager
or a coroutine function.


Άλλαξε στην έκδοση 3.15: Added support for arbitrary descriptors @code{__aexit__()}.

@end deffn

@geindex push_async_callback() (μέθοδος της contextlib.AsyncExitStack)
@anchor{library/contextlib contextlib AsyncExitStack push_async_callback}@anchor{e46}
@deffn {Μέθοδος} push_async_callback (callback, /, *args, **kwds)

Similar to @ref{e45,,ExitStack.callback()} but expects a coroutine function.
@end deffn

@geindex aclose() (μέθοδος της contextlib.AsyncExitStack)
@anchor{library/contextlib contextlib AsyncExitStack aclose}@anchor{4c9a}
@deffn {Μέθοδος} async aclose ()

Similar to @ref{4c99,,ExitStack.close()} but properly handles awaitables.
@end deffn

Continuing the example for @ref{20f,,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


Added in version 3.7.

@end deffn

@node Examples and Recipes<2>,Single use reusable and reentrant context managers,Utilities,contextlib — Utilities for with-statement contexts
@anchor{library/contextlib examples-and-recipes}@anchor{4c9c}
@subsubsection Examples and Recipes


This section describes some examples and recipes for making effective use of
the tools provided by @code{contextlib}.

@menu
* Supporting a variable number of context managers:: 
* Catching exceptions from __enter__ methods:: 
* Cleaning up in an __enter__ implementation:: 
* Replacing any use of try-finally and flag variables:: 
* Using a context manager as a function decorator:: 

@end menu

@node Supporting a variable number of context managers,Catching exceptions from __enter__ methods,,Examples and Recipes<2>
@anchor{library/contextlib supporting-a-variable-number-of-context-managers}@anchor{4c9d}
@subsubsection Supporting a variable number of context managers


The primary use case for @ref{208,,ExitStack} is the one given in the class
documentation: supporting a variable number of context managers and other
cleanup operations in a single @ref{20a,,with} statement. The variability
may come from the number of context managers needed being driven by user
input (such as opening a user specified collection of files), or from
some of the context managers being optional:

@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

As shown, @ref{208,,ExitStack} also makes it quite easy to use @ref{20a,,with}
statements to manage arbitrary resources that don’t natively support the
context management protocol.

@node Catching exceptions from __enter__ methods,Cleaning up in an __enter__ implementation,Supporting a variable number of context managers,Examples and Recipes<2>
@anchor{library/contextlib catching-exceptions-from-enter-methods}@anchor{4c9e}
@subsubsection Catching exceptions from @code{__enter__} methods


It is occasionally desirable to catch exceptions from an @ref{9c6,,__enter__()}
method implementation, `without' inadvertently catching exceptions from
the @ref{20a,,with} statement body or the context manager’s @ref{16a5,,__exit__()}
method. By using @ref{208,,ExitStack} the steps in the context management
protocol can be separated slightly in order to allow this:

@example
stack = ExitStack()
try:
    x = stack.enter_context(cm)
except Exception:
    # handle __enter__ exception
else:
    with stack:
        # Handle normal case
@end example

Actually needing to do this is likely to indicate that the underlying API
should be providing a direct resource management interface for use with
@ref{ad6,,try}/@ref{447,,except}/@ref{44c,,finally} statements, but not
all APIs are well designed in that regard. When a context manager is the
only resource management API provided, then @ref{208,,ExitStack} can make it
easier to handle various situations that can’t be handled directly in a
@ref{20a,,with} statement.

@node Cleaning up in an __enter__ implementation,Replacing any use of try-finally and flag variables,Catching exceptions from __enter__ methods,Examples and Recipes<2>
@anchor{library/contextlib cleaning-up-in-an-enter-implementation}@anchor{4c9f}
@subsubsection Cleaning up in an @code{__enter__} implementation


As noted in the documentation of @ref{4c97,,ExitStack.push()}, this
method can be useful in cleaning up an already allocated resource if later
steps in the @ref{9c6,,__enter__()} implementation fail.

Here’s an example of doing this for a context manager that accepts resource
acquisition and release functions, along with an optional validation function,
and maps them to the context management protocol:

@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 Replacing any use of try-finally and flag variables,Using a context manager as a function decorator,Cleaning up in an __enter__ implementation,Examples and Recipes<2>
@anchor{library/contextlib replacing-any-use-of-try-finally-and-flag-variables}@anchor{4ca0}
@subsubsection Replacing any use of @code{try-finally} and flag variables


A pattern you will sometimes see is a @code{try-finally} statement with a flag
variable to indicate whether or not the body of the @code{finally} clause should
be executed. In its simplest form (that can’t already be handled just by
using an @code{except} clause instead), it looks something like this:

@example
cleanup_needed = True
try:
    result = perform_operation()
    if result:
        cleanup_needed = False
finally:
    if cleanup_needed:
        cleanup_resources()
@end example

As with any @code{try} statement based code, this can cause problems for
development and review, because the setup code and the cleanup code can end
up being separated by arbitrarily long sections of code.

@ref{208,,ExitStack} makes it possible to instead register a callback for
execution at the end of a @code{with} statement, and then later decide to skip
executing that callback:

@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.

If a particular application uses this pattern a lot, it can be simplified
even further by means of a small helper class:

@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

If the resource cleanup isn’t already neatly bundled into a standalone
function, then it is still possible to use the decorator form of
@ref{e45,,ExitStack.callback()} to declare the resource cleanup in
advance:

@example
from contextlib import ExitStack

with ExitStack() as stack:
    @@stack.callback
    def cleanup_resources():
        ...
    result = perform_operation()
    if result:
        stack.pop_all()
@end example

Due to the way the decorator protocol works, a callback function
declared this way cannot take any parameters. Instead, any resources to
be released must be accessed as closure variables.

@node Using a context manager as a function decorator,,Replacing any use of try-finally and flag variables,Examples and Recipes<2>
@anchor{library/contextlib using-a-context-manager-as-a-function-decorator}@anchor{4ca1}
@subsubsection Using a context manager as a function decorator


@ref{20c,,ContextDecorator} makes it possible to use a context manager in
both an ordinary @code{with} statement and also as a function decorator.

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,
inheriting from @ref{20c,,ContextDecorator} provides both capabilities in a
single definition:

@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

Instances of this class can be used as both a context manager:

@example
with track_entry_and_exit('widget loader'):
    print('Some time consuming activity goes here')
    load_widget()
@end example

And also as a function decorator:

@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{9c6,,__enter__()}. If that value is needed, then it is still necessary to use
an explicit @code{with} statement.


@subsubheading Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 343

@item PEP 343@footnote{https://peps.python.org/pep-0343/} - The «with» statement

The specification, background, and examples for the Python @ref{20a,,with}
statement.
@end table


@node Single use reusable and reentrant context managers,,Examples and Recipes<2>,contextlib — Utilities for with-statement contexts
@anchor{library/contextlib single-use-reusable-and-reentrant-cms}@anchor{12d5}@anchor{library/contextlib single-use-reusable-and-reentrant-context-managers}@anchor{4ca2}
@subsubsection Single use, reusable and reentrant context managers


Most context managers are written in a way that means they can only be
used effectively in a @ref{20a,,with} statement once. These single use
context managers must be created afresh each time they’re used -
attempting to use them a second time will trigger an exception or
otherwise not work correctly.

This common limitation means that it is generally advisable to create
context managers directly in the header of the @ref{20a,,with} statement
where they are used (as shown in all of the usage examples above).

Files are an example of effectively single use context managers, since
the first @ref{20a,,with} statement will close the file, preventing any
further IO operations using that file object.

Context managers created using @ref{20e,,contextmanager()} are also single use
context managers, and will complain about the underlying generator failing
to yield if an attempt is made to use them a second time:

@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
* Reentrant context managers:: 
* Reusable context managers:: 

@end menu

@node Reentrant context managers,Reusable context managers,,Single use reusable and reentrant context managers
@anchor{library/contextlib reentrant-cms}@anchor{4c96}@anchor{library/contextlib reentrant-context-managers}@anchor{4ca3}
@subsubsection Reentrant context managers


More sophisticated context managers may be «reentrant». These context
managers can not only be used in multiple @ref{20a,,with} statements,
but may also be used `inside' a @code{with} statement that is already
using the same context manager.

@ref{2df,,threading.RLock} is an example of a reentrant context manager, as are
@ref{12d3,,suppress()}, @ref{119f,,redirect_stdout()}, and @ref{a01,,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

Real world examples of reentrancy are more likely to involve multiple
functions calling each other and hence be far more complicated than this
example.

Note also that being reentrant is `not' the same thing as being thread safe.
@ref{119f,,redirect_stdout()}, for example, is definitely not thread safe, as it
makes a global modification to the system state by binding @ref{e9c,,sys.stdout}
to a different stream.

@node Reusable context managers,,Reentrant context managers,Single use reusable and reentrant context managers
@anchor{library/contextlib reusable-cms}@anchor{4ca4}@anchor{library/contextlib reusable-context-managers}@anchor{4ca5}
@subsubsection Reusable context managers


Distinct from both single use and reentrant context managers are «reusable»
context managers (or, to be completely explicit, «reusable, but not
reentrant» context managers, since reentrant context managers are also
reusable). These context managers support being used multiple times, but
will fail (or otherwise not work correctly) if the specific context manager
instance has already been used in a containing with statement.

@ref{1a10,,threading.Lock} is an example of a reusable, but not reentrant,
context manager (for a reentrant lock, it is necessary to use
@ref{2df,,threading.RLock} instead).

Another example of a reusable, but not reentrant, context manager is
@ref{208,,ExitStack}, as it invokes `all' currently registered callbacks
when leaving any with statement, regardless of where those callbacks
were added:

@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

As the output from the example shows, reusing a single stack object across
multiple with statements works correctly, but attempting to nest them
will cause the stack to be cleared at the end of the innermost with
statement, which is unlikely to be desirable behaviour.

Using separate @ref{208,,ExitStack} instances instead of reusing a single
instance avoids that problem:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node abc — Abstract Base Classes,atexit — Exit handlers,contextlib — Utilities for with-statement contexts,Python Runtime Services
@anchor{library/abc doc}@anchor{4ca6}@anchor{library/abc abc-abstract-base-classes}@anchor{4ca7}@anchor{library/abc module-abc}@anchor{4}@anchor{library/abc translation-repo}@anchor{4ca8}
@subsection @code{abc} — Abstract Base Classes


@geindex module; abc

`Source code:' Lib/abc.py@footnote{https://github.com/python/cpython/tree/main/Lib/abc.py}


__________________________________________________________________


This module provides the infrastructure for defining @ref{155f,,abstract base classes} (ABCs) in Python, as outlined in 
@geindex Python Enhancement Proposals; PEP 3119
PEP 3119@footnote{https://peps.python.org/pep-3119/};
see the PEP for why this was added to Python. (See also 
@geindex Python Enhancement Proposals; PEP 3141
PEP 3141@footnote{https://peps.python.org/pep-3141/} and the
@ref{a2,,numbers} module regarding a type hierarchy for numbers based on ABCs.)

The @ref{1e,,collections} module has some concrete classes that derive from
ABCs; these can, of course, be further derived. In addition, the
@ref{1f,,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{183,,hashable} or if it is a @ref{1564,,mapping}.

This module provides the metaclass @ref{12c9,,ABCMeta} for defining ABCs and
a helper class @ref{12c8,,ABC} to alternatively define ABCs through inheritance:

@geindex ABC (κλάση σε abc)
@anchor{library/abc abc ABC}@anchor{12c8}
@deffn {Κλάση} abc.ABC

A helper class that has @ref{12c9,,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{12c9,,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


Added in version 3.4.

@end deffn

@geindex ABCMeta (κλάση σε abc)
@anchor{library/abc abc ABCMeta}@anchor{12c9}
@deffn {Κλάση} abc.ABCMeta

Metaclass for defining Abstract Base Classes (ABCs).

Use this metaclass to create an ABC.  An ABC can be subclassed directly, and
then acts as a mix-in class.  You can also register unrelated concrete
classes (even built-in classes) and unrelated ABCs as «virtual subclasses» –
these and their descendants will be considered subclasses of the registering
ABC by the built-in @ref{2f0,,issubclass()} function, but the registering ABC
won’t show up in their MRO (Method Resolution Order) nor will method
implementations defined by the registering ABC be callable (not even via
@ref{443,,super()}). @footnote{
C++ programmers should note that Python’s virtual base class
concept is not the same as C++”s.
}

Classes created with a metaclass of @code{ABCMeta} have the following method:

@geindex register() (μέθοδος της abc.ABCMeta)
@anchor{library/abc abc ABCMeta register}@anchor{1436}
@deffn {Μέθοδος} register (subclass)

Register `subclass' as a «virtual subclass» of this ABC. For
example:

@example
from abc import ABC

class MyABC(ABC):
    pass

MyABC.register(tuple)

assert issubclass(tuple, MyABC)
assert isinstance((), MyABC)
@end example


Άλλαξε στην έκδοση 3.3: Returns the registered subclass, to allow usage as a class decorator.



Άλλαξε στην έκδοση 3.4: To detect calls to @code{register()}, you can use the
@ref{12c7,,get_cache_token()} function.

@end deffn

You can also override this method in an abstract base class:

@geindex __subclasshook__() (μέθοδος της abc.ABCMeta)
@anchor{library/abc abc ABCMeta __subclasshook__}@anchor{2bad}
@deffn {Μέθοδος} __subclasshook__ (subclass)

(Must be defined as a class method.)

Check whether `subclass' is considered a subclass of this ABC.  This means
that you can customize the behavior of @ref{2f0,,issubclass()} further without the
need to call @ref{1436,,register()} on every class you want to consider a
subclass of the ABC.  (This class method is called from the
@ref{25bd,,__subclasscheck__()} method of the ABC.)

This method should return @code{True}, @code{False} or @ref{440,,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

For a demonstration of these concepts, look at this example ABC definition:

@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{102d,,__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{2bad,,__subclasshook__()} class method defined here says that any class
that has an @ref{102d,,__iter__()} method in its
@ref{1bf,,__dict__} (or in that of one of its base classes, accessed
via the @ref{2569,,__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{102d,,__iter__()} method (it uses
the old-style iterable protocol, defined in terms of @ref{1989,,__len__()} and
@ref{787,,__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() (στη μονάδα abc)
@anchor{library/abc abc abstractmethod}@anchor{1433}
@deffn {Συνάρτηση} @@abc.abstractmethod

A decorator indicating abstract methods.

Using this decorator requires that the class’s metaclass is @ref{12c9,,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{4ca9,,update_abstractmethods()} function.  The
@code{abstractmethod()} only affects subclasses derived using regular
inheritance; «virtual subclasses» registered with the ABC’s
@ref{1436,,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{6bb,,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 Σημείωση 
Unlike Java abstract methods, these abstract
methods may have an implementation. This implementation can be
called via the @ref{443,,super()} mechanism from the class that
overrides it.  This could be useful as an end-point for a
super-call in a framework that uses cooperative
multiple-inheritance.
@end quotation
@end cartouche
@end deffn

The @code{abc} module also supports the following legacy decorators:

@geindex abstractclassmethod() (στη μονάδα abc)
@anchor{library/abc abc abstractclassmethod}@anchor{1434}
@deffn {Συνάρτηση} @@abc.abstractclassmethod


Added in version 3.2.



Αποσύρθηκε στην έκδοση 3.3: It is now possible to use @ref{69a,,classmethod} with
@ref{1433,,abstractmethod()}, making this decorator redundant.


A subclass of the built-in @ref{69a,,classmethod()}, indicating an abstract
classmethod. Otherwise it is similar to @ref{1433,,abstractmethod()}.

This special case is deprecated, as the @ref{69a,,classmethod()} decorator
is now correctly identified as abstract when applied to an abstract
method:

@example
class C(ABC):
    @@classmethod
    @@abstractmethod
    def my_abstract_classmethod(cls, arg):
        ...
@end example
@end deffn

@geindex abstractstaticmethod() (στη μονάδα abc)
@anchor{library/abc abc abstractstaticmethod}@anchor{1435}
@deffn {Συνάρτηση} @@abc.abstractstaticmethod


Added in version 3.2.



Αποσύρθηκε στην έκδοση 3.3: It is now possible to use @ref{666,,staticmethod} with
@ref{1433,,abstractmethod()}, making this decorator redundant.


A subclass of the built-in @ref{666,,staticmethod()}, indicating an abstract
staticmethod. Otherwise it is similar to @ref{1433,,abstractmethod()}.

This special case is deprecated, as the @ref{666,,staticmethod()} decorator
is now correctly identified as abstract when applied to an abstract
method:

@example
class C(ABC):
    @@staticmethod
    @@abstractmethod
    def my_abstract_staticmethod(arg):
        ...
@end example
@end deffn

@geindex abstractproperty() (στη μονάδα abc)
@anchor{library/abc abc abstractproperty}@anchor{1432}
@deffn {Συνάρτηση} @@abc.abstractproperty


Αποσύρθηκε στην έκδοση 3.3: It is now possible to use @ref{6bb,,property}, @ref{1be2,,property.getter()},
@ref{1be3,,property.setter()} and @ref{1be4,,property.deleter()} with
@ref{1433,,abstractmethod()}, making this decorator redundant.


A subclass of the built-in @ref{6bb,,property()}, indicating an abstract
property.

This special case is deprecated, as the @ref{6bb,,property()} decorator
is now correctly identified as abstract when applied to an abstract
method:

@example
class C(ABC):
    @@property
    @@abstractmethod
    def my_abstract_property(self):
        ...
@end example

The above example defines a read-only property; you can also define a
read-write abstract property by appropriately marking one or more of the
underlying methods as abstract:

@example
class C(ABC):
    @@property
    def x(self):
        ...

    @@x.setter
    @@abstractmethod
    def x(self, val):
        ...
@end example

If only some components are abstract, only those components need to be
updated to create a concrete property in a subclass:

@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() (στη μονάδα abc)
@anchor{library/abc abc get_cache_token}@anchor{12c7}
@deffn {Συνάρτηση} abc.get_cache_token ()

Returns the current abstract base class cache token.

The token is an opaque object (that supports equality testing) identifying
the current version of the abstract base class cache for virtual subclasses.
The token changes with every call to @ref{1436,,ABCMeta.register()} on any ABC.


Added in version 3.4.

@end deffn

@geindex update_abstractmethods() (στη μονάδα abc)
@anchor{library/abc abc update_abstractmethods}@anchor{4ca9}
@deffn {Συνάρτηση} abc.update_abstractmethods (cls)

A function to recalculate an abstract class’s abstraction status. This
function should be called if a class’s abstract methods have been
implemented or changed after it was created. Usually, this function should
be called from within a class decorator.

Returns `cls', to allow usage as a class decorator.

If `cls' is not an instance of @ref{12c9,,ABCMeta}, does nothing.

@cartouche
@quotation Σημείωση 
This function assumes that `cls'’s superclasses are already updated.
It does not update any subclasses.
@end quotation
@end cartouche


Added in version 3.10.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node atexit — Exit handlers,traceback — Print or retrieve a stack traceback,abc — Abstract Base Classes,Python Runtime Services
@anchor{library/atexit doc}@anchor{4caa}@anchor{library/atexit atexit-exit-handlers}@anchor{4cab}@anchor{library/atexit module-atexit}@anchor{d}@anchor{library/atexit translation-repo}@anchor{4cac}
@subsection @code{atexit} — Exit handlers


@geindex module; atexit


__________________________________________________________________


The @code{atexit} module defines functions to register and unregister cleanup
functions.  Functions thus registered are automatically executed upon normal
interpreter termination.  @code{atexit} runs these functions in the `reverse'
order in which they were registered; if you register @code{A}, @code{B}, and @code{C},
at interpreter termination time they will be run in the order @code{C}, @code{B},
@code{A}.

`Note:' The functions registered via this module are not called when the
program is killed by a signal not handled by Python, when a Python fatal
internal error is detected, or when @ref{28f5,,os._exit()} is called.

`Note:' The effect of registering or unregistering functions from within
a cleanup function is undefined.


Άλλαξε στην έκδοση 3.7: When used with C-API subinterpreters, registered functions
are local to the interpreter they were registered in.


@geindex register() (στη μονάδα atexit)
@anchor{library/atexit atexit register}@anchor{c54}
@deffn {Συνάρτηση} atexit.register (func, *args, **kwargs)

Register `func' as a function to be executed at termination.  Any optional
arguments that are to be passed to `func' must be passed as arguments to
@code{register()}.  It is possible to register the same function and arguments
more than once.

At normal program termination (for instance, if @ref{4ff,,sys.exit()} is called or
the main module’s execution completes), all functions registered are called in
last in, first out order.  The assumption is that lower level modules will
normally be imported before higher level modules and thus must be cleaned up
later.

If an exception is raised during execution of the exit handlers, a traceback is
printed (unless @ref{10f7,,SystemExit} is raised) and the exception information is
saved.  After all exit handlers have had a chance to run, the last exception to
be raised is re-raised.

This function returns `func', which makes it possible to use it as a
decorator.

@cartouche
@quotation Προειδοποίηση 
Starting new threads or calling @ref{6bd,,os.fork()} from a registered
function can lead to race condition between the main Python
runtime thread freeing thread states while internal @ref{f6,,threading}
routines or the new process try to use that state. This can lead to
crashes rather than clean shutdown.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.12: Attempts to start a new thread or @ref{6bd,,os.fork()} a new process
in a registered function now leads to @ref{30d,,RuntimeError}.

@end deffn

@geindex unregister() (στη μονάδα atexit)
@anchor{library/atexit atexit unregister}@anchor{1980}
@deffn {Συνάρτηση} atexit.unregister (func)

Remove `func' from the list of functions to be run at interpreter shutdown.
@code{unregister()} silently does nothing if `func' was not previously
registered.  If `func' has been registered more than once, every occurrence
of that function in the @code{atexit} call stack will be removed.  Equality
comparisons (@code{==}) are used internally during unregistration, so function
references do not need to have matching identities.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{c2,,readline}

Useful example of @code{atexit} to read and write @ref{c2,,readline} history
files.
@end table


@menu
* atexit Example:: 

@end menu

@node atexit Example,,,atexit — Exit handlers
@anchor{library/atexit atexit-example}@anchor{4cad}@anchor{library/atexit id1}@anchor{4cae}
@subsubsection @code{atexit} Example


The following simple example demonstrates how a module can initialize a counter
from a file when it is imported and save the counter’s updated value
automatically when the program terminates without relying on the application
making an explicit call into this module at termination.

@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

Positional and keyword arguments may also be passed to @ref{c54,,register()} to be
passed along to the registered function when it is called:

@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

Usage as a @ref{b18,,decorator}:

@example
import atexit

@@atexit.register
def goodbye():
    print('You are now leaving the Python sector.')
@end example

This only works with functions that can be called without arguments.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node traceback — Print or retrieve a stack traceback,__future__ — Future statement definitions,atexit — Exit handlers,Python Runtime Services
@anchor{library/traceback doc}@anchor{4caf}@anchor{library/traceback module-traceback}@anchor{107}@anchor{library/traceback traceback-print-or-retrieve-a-stack-traceback}@anchor{4cb0}@anchor{library/traceback translation-repo}@anchor{4cb1}
@subsection @code{traceback} — Print or retrieve a stack traceback


@geindex module; traceback

`Source code:' Lib/traceback.py@footnote{https://github.com/python/cpython/tree/main/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{eba,,traceback objects} — these are
objects of type @ref{eb8,,types.TracebackType},
which are assigned to the @ref{166b,,__traceback__} field of
@ref{9b9,,BaseException} instances.


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{5b,,faulthandler}

Used to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal.

@item Module @ref{aa,,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{764,,TracebackException} class and its helper classes
@ref{1234,,StackSummary} and @ref{1235,,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


Added in version 3.13: Output is colorized by default and can be
@ref{1af,,controlled using environment variables}.


@menu
* Module-Level Functions: Module-Level Functions<2>. 
* TracebackException Objects:: 
* StackSummary Objects:: 
* FrameSummary Objects:: 
* Examples of Using the Module-Level Functions:: 
* Examples of Using TracebackException:: 

@end menu

@node Module-Level Functions<2>,TracebackException Objects,,traceback — Print or retrieve a stack traceback
@anchor{library/traceback module-level-functions}@anchor{4cb2}
@subsubsection Module-Level Functions


@geindex print_tb() (στη μονάδα traceback)
@anchor{library/traceback traceback print_tb}@anchor{1236}
@deffn {Συνάρτηση} traceback.print_tb (tb, limit=None, file=None)

Print up to `limit' stack trace entries from
@ref{eba,,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{d05,,sys.stderr}; otherwise it should be an open
@ref{156c,,file} or @ref{19b1,,file-like object} to
receive the output.

@cartouche
@quotation Σημείωση 
The meaning of the `limit' parameter is different than the meaning
of @ref{1b5c,,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


Άλλαξε στην έκδοση 3.5: Added negative `limit' support.

@end deffn

@geindex print_exception() (στη μονάδα traceback)
@anchor{library/traceback traceback print_exception}@anchor{c27}
@deffn {Συνάρτηση} traceback.print_exception (exc, /[, value, tb], limit=None, file=None, chain=True)

Print exception information and stack trace entries from
@ref{eba,,traceback object}
`tb' to `file'. This differs from @ref{1236,,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{17e,,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{1236,,print_tb()}.
If `chain' is true (the default), then chained exceptions (the
@ref{166d,,__cause__} or @ref{166c,,__context__}
attributes of the exception) will be
printed as well, like the interpreter itself does when printing an unhandled
exception.


Άλλαξε στην έκδοση 3.5: The `etype' argument is ignored and inferred from the type of `value'.



Άλλαξε στην έκδοση 3.10: The `etype' parameter has been renamed to `exc' and is now
positional-only.

@end deffn

@geindex print_exc() (στη μονάδα traceback)
@anchor{library/traceback traceback print_exc}@anchor{1e1b}
@deffn {Συνάρτηση} traceback.print_exc (limit=None, file=None, chain=True)

This is a shorthand for @code{print_exception(sys.exception(), limit=limit, file=file,
chain=chain)}.
@end deffn

@geindex print_last() (στη μονάδα traceback)
@anchor{library/traceback traceback print_last}@anchor{4cb3}
@deffn {Συνάρτηση} traceback.print_last (limit=None, file=None, chain=True)

This is a shorthand for @code{print_exception(sys.last_exc, limit=limit, file=file,
chain=chain)}.  In general it will work only after an exception has reached
an interactive prompt (see @ref{8ce,,sys.last_exc}).
@end deffn

@geindex print_stack() (στη μονάδα traceback)
@anchor{library/traceback traceback print_stack}@anchor{1237}
@deffn {Συνάρτηση} 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{acd,,stack frame}
to start.  The optional `file' argument has the same meaning as for
@ref{1236,,print_tb()}.


Άλλαξε στην έκδοση 3.5: Added negative `limit' support.

@end deffn

@geindex extract_tb() (στη μονάδα traceback)
@anchor{library/traceback traceback extract_tb}@anchor{4cb4}
@deffn {Συνάρτηση} traceback.extract_tb (tb, limit=None)

Return a @ref{1234,,StackSummary} object representing a list of «pre-processed»
stack trace entries extracted from the
@ref{eba,,traceback object} `tb'.  It is useful
for alternate formatting of stack traces.  The optional `limit' argument has
the same meaning as for @ref{1236,,print_tb()}.  A «pre-processed» stack trace
entry is a @ref{1235,,FrameSummary} object containing attributes
@ref{4cb5,,filename}, @ref{4cb6,,lineno},
@ref{4cb7,,name}, and @ref{4cb8,,line} representing the
information that is usually printed for a stack trace.
@end deffn

@geindex extract_stack() (στη μονάδα traceback)
@anchor{library/traceback traceback extract_stack}@anchor{4cb9}
@deffn {Συνάρτηση} traceback.extract_stack (f=None, limit=None)

Extract the raw traceback from the current
@ref{acd,,stack frame}.  The return value has
the same format as for @ref{4cb4,,extract_tb()}.  The optional `f' and `limit'
arguments have the same meaning as for @ref{1237,,print_stack()}.
@end deffn

@geindex print_list() (στη μονάδα traceback)
@anchor{library/traceback traceback print_list}@anchor{1b0f}
@deffn {Συνάρτηση} traceback.print_list (extracted_list, file=None)

Print the list of tuples as returned by @ref{4cb4,,extract_tb()} or
@ref{4cb9,,extract_stack()} as a formatted stack trace to the given file.
If `file' is @code{None}, the output is written to @ref{d05,,sys.stderr}.
@end deffn

@geindex format_list() (στη μονάδα traceback)
@anchor{library/traceback traceback format_list}@anchor{4cba}
@deffn {Συνάρτηση} traceback.format_list (extracted_list)

Given a list of tuples or @ref{1235,,FrameSummary} objects as returned by
@ref{4cb4,,extract_tb()} or @ref{4cb9,,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() (στη μονάδα traceback)
@anchor{library/traceback traceback format_exception_only}@anchor{c26}
@deffn {Συνάρτηση} 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{8d0,,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{17e,,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{28e0,,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{767,,BaseExceptionGroup}, the nested exceptions are included as
well, recursively, with indentation relative to their nesting depth.


Άλλαξε στην έκδοση 3.10: The `etype' parameter has been renamed to `exc' and is now
positional-only.



Άλλαξε στην έκδοση 3.11: The returned list now includes any
@ref{28e0,,notes} attached to the exception.



Άλλαξε στην έκδοση 3.13: `show_group' parameter was added.

@end deffn

@geindex format_exception() (στη μονάδα traceback)
@anchor{library/traceback traceback format_exception}@anchor{c25}
@deffn {Συνάρτηση} 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{c27,,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 @code{print_exception()}.


Άλλαξε στην έκδοση 3.5: The `etype' argument is ignored and inferred from the type of `value'.



Άλλαξε στην έκδοση 3.10: This function’s behavior and signature were modified to match
@ref{c27,,print_exception()}.

@end deffn

@geindex format_exc() (στη μονάδα traceback)
@anchor{library/traceback traceback format_exc}@anchor{4cbb}
@deffn {Συνάρτηση} 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() (στη μονάδα traceback)
@anchor{library/traceback traceback format_tb}@anchor{4b81}
@deffn {Συνάρτηση} traceback.format_tb (tb, limit=None)

A shorthand for @code{format_list(extract_tb(tb, limit))}.
@end deffn

@geindex format_stack() (στη μονάδα traceback)
@anchor{library/traceback traceback format_stack}@anchor{4cbc}
@deffn {Συνάρτηση} traceback.format_stack (f=None, limit=None)

A shorthand for @code{format_list(extract_stack(f, limit))}.
@end deffn

@geindex clear_frames() (στη μονάδα traceback)
@anchor{library/traceback traceback clear_frames}@anchor{137d}
@deffn {Συνάρτηση} traceback.clear_frames (tb)

Clears the local variables of all the stack frames in a
@ref{eba,,traceback} `tb'
by calling the @ref{784,,clear()} method of each
@ref{acd,,frame object}.


Added in version 3.4.

@end deffn

@geindex walk_stack() (στη μονάδα traceback)
@anchor{library/traceback traceback walk_stack}@anchor{1232}
@deffn {Συνάρτηση} traceback.walk_stack (f)

Walk a stack following @ref{b6b,,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{4cbd,,StackSummary.extract()}.


Added in version 3.5.



Άλλαξε στην έκδοση 3.14: This function previously returned a generator that would walk the stack
when first iterated over. The generator returned now is the state of the
stack when @code{walk_stack} is called.

@end deffn

@geindex walk_tb() (στη μονάδα traceback)
@anchor{library/traceback traceback walk_tb}@anchor{1233}
@deffn {Συνάρτηση} traceback.walk_tb (tb)

Walk a traceback following @ref{eb9,,tb_next} yielding the frame and
line number
for each frame. This helper is used with @ref{4cbd,,StackSummary.extract()}.


Added in version 3.5.

@end deffn

@node TracebackException Objects,StackSummary Objects,Module-Level Functions<2>,traceback — Print or retrieve a stack traceback
@anchor{library/traceback tracebackexception-objects}@anchor{4cbe}
@subsubsection @code{TracebackException} Objects



Added in 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{eba,,traceback} and @ref{acd,,frame} objects.
In addition, they expose more options to configure the output compared to
the module-level functions described above.

@geindex TracebackException (κλάση σε traceback)
@anchor{library/traceback traceback TracebackException}@anchor{764}
@deffn {Κλάση} 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{1234,,StackSummary}
class.

If `compact' is true, only data that is required by
@code{TracebackException}’s @ref{439,,format()} method
is saved in the class attributes. In particular, the
@ref{4cbf,,__context__} field is calculated only if @ref{4cc0,,__cause__} is
@code{None} and @ref{4cc1,,__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{767,,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.


Άλλαξε στην έκδοση 3.10: Added the `compact' parameter.



Άλλαξε στην έκδοση 3.11: Added the `max_group_width' and `max_group_depth' parameters.


@geindex __cause__ (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException __cause__}@anchor{4cc0}
@deffn {Ιδιότητα} __cause__

A @code{TracebackException} of the original
@ref{166d,,__cause__}.
@end deffn

@geindex __context__ (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException __context__}@anchor{4cbf}
@deffn {Ιδιότητα} __context__

A @code{TracebackException} of the original
@ref{166c,,__context__}.
@end deffn

@geindex exceptions (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException exceptions}@anchor{4cc2}
@deffn {Ιδιότητα} exceptions

If @code{self} represents an @ref{6d8,,ExceptionGroup}, this field holds a list of
@code{TracebackException} instances representing the nested exceptions.
Otherwise it is @code{None}.


Added in version 3.11.

@end deffn

@geindex __suppress_context__ (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException __suppress_context__}@anchor{4cc1}
@deffn {Ιδιότητα} __suppress_context__

The @ref{270a,,__suppress_context__} value from the original
exception.
@end deffn

@geindex __notes__ (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException __notes__}@anchor{4cc3}
@deffn {Ιδιότητα} __notes__

The @ref{28e0,,__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.


Added in version 3.11.

@end deffn

@geindex stack (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException stack}@anchor{4cc4}
@deffn {Ιδιότητα} stack

A @ref{1234,,StackSummary} representing the traceback.
@end deffn

@geindex exc_type (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException exc_type}@anchor{765}
@deffn {Ιδιότητα} exc_type

The class of the original traceback.


Αποσύρθηκε στην έκδοση 3.13.

@end deffn

@geindex exc_type_str (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException exc_type_str}@anchor{763}
@deffn {Ιδιότητα} exc_type_str

String display of the class of the original exception.


Added in version 3.13.

@end deffn

@geindex filename (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException filename}@anchor{4cc5}
@deffn {Ιδιότητα} filename

For syntax errors - the file name where the error occurred.
@end deffn

@geindex lineno (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException lineno}@anchor{4cc6}
@deffn {Ιδιότητα} lineno

For syntax errors - the line number where the error occurred.
@end deffn

@geindex end_lineno (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException end_lineno}@anchor{4cc7}
@deffn {Ιδιότητα} end_lineno

For syntax errors - the end line number where the error occurred.
Can be @code{None} if not present.


Added in version 3.10.

@end deffn

@geindex text (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException text}@anchor{4cc8}
@deffn {Ιδιότητα} text

For syntax errors - the text where the error occurred.
@end deffn

@geindex offset (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException offset}@anchor{4cc9}
@deffn {Ιδιότητα} offset

For syntax errors - the offset into the text where the error occurred.
@end deffn

@geindex end_offset (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException end_offset}@anchor{4cca}
@deffn {Ιδιότητα} end_offset

For syntax errors - the end offset into the text where the error occurred.
Can be @code{None} if not present.


Added in version 3.10.

@end deffn

@geindex msg (ιδιότητα της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException msg}@anchor{4ccb}
@deffn {Ιδιότητα} msg

For syntax errors - the compiler error message.
@end deffn

@geindex from_exception() (μέθοδος κλάσης της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException from_exception}@anchor{4ccc}
@deffn {Μέθοδος} 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{1234,,StackSummary} class.

Note that when locals are captured, they are also shown in the traceback.
@end deffn

@geindex print() (μέθοδος της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException print}@anchor{a92}
@deffn {Μέθοδος} print (*, file=None, chain=True)

Print to `file' (default @code{sys.stderr}) the exception information returned by
@ref{439,,format()}.


Added in version 3.11.

@end deffn

@geindex format() (μέθοδος της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException format}@anchor{4ccd}
@deffn {Μέθοδος} format (*, chain=True)

Format the exception.

If `chain' is not @code{True}, @ref{4cc0,,__cause__} and @ref{4cbf,,__context__}
will not be formatted.

The return value is a generator of strings, each ending in a newline and
some containing internal newlines. @ref{c27,,print_exception()}
is a wrapper around this method which just prints the lines to a file.
@end deffn

@geindex format_exception_only() (μέθοδος της traceback.TracebackException)
@anchor{library/traceback traceback TracebackException format_exception_only}@anchor{766}
@deffn {Μέθοδος} 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{17e,,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{767,,BaseExceptionGroup}, the nested exceptions are included as
well, recursively, with indentation relative to their nesting depth.


Άλλαξε στην έκδοση 3.11: The exception’s @ref{28e0,,notes} are now
included in the output.



Άλλαξε στην έκδοση 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{4cce}
@subsubsection @code{StackSummary} Objects



Added in version 3.5.


@code{StackSummary} objects represent a call stack ready for formatting.

@geindex StackSummary (κλάση σε traceback)
@anchor{library/traceback traceback StackSummary}@anchor{1234}
@deffn {Κλάση} traceback.StackSummary

@geindex extract() (μέθοδος κλάσης της traceback.StackSummary)
@anchor{library/traceback traceback StackSummary extract}@anchor{4cbd}
@deffn {Μέθοδος} 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{1232,,walk_stack()} or
@ref{1233,,walk_tb()}).

If `limit' is supplied, only this many frames are taken from `frame_gen'.
If `lookup_lines' is @code{False}, the returned @ref{1235,,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.


Άλλαξε στην έκδοση 3.12: Exceptions raised from @ref{45b,,repr()} on a local variable (when
`capture_locals' is @code{True}) are no longer propagated to the caller.

@end deffn

@geindex from_list() (μέθοδος κλάσης της traceback.StackSummary)
@anchor{library/traceback traceback StackSummary from_list}@anchor{4ccf}
@deffn {Μέθοδος} classmethod from_list (a_list)

Construct a @code{StackSummary} object from a supplied list of
@ref{1235,,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() (μέθοδος της traceback.StackSummary)
@anchor{library/traceback traceback StackSummary format}@anchor{4cd0}
@deffn {Μέθοδος} format ()

Returns a list of strings ready for printing.  Each string in the
resulting list corresponds to a single @ref{acd,,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.


Άλλαξε στην έκδοση 3.6: Long sequences of repeated frames are now abbreviated.

@end deffn

@geindex format_frame_summary() (μέθοδος της traceback.StackSummary)
@anchor{library/traceback traceback StackSummary format_frame_summary}@anchor{a91}
@deffn {Μέθοδος} format_frame_summary (frame_summary)

Returns a string for printing one of the @ref{acd,,frames}
involved in the stack.
This method is called for each @ref{1235,,FrameSummary} object to be
printed by @ref{4cd0,,StackSummary.format()}. If it returns @code{None}, the
frame is omitted from the output.


Added in 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{4cd1}
@subsubsection @code{FrameSummary} Objects



Added in version 3.5.


A @code{FrameSummary} object represents a single @ref{acd,,frame}
in a @ref{eba,,traceback}.

@geindex FrameSummary (κλάση σε traceback)
@anchor{library/traceback traceback FrameSummary}@anchor{1235}
@deffn {Κλάση} traceback.FrameSummary (filename, lineno, name, *, lookup_line=True, locals=None, line=None, end_lineno=None, colno=None, end_colno=None)

Represents a single @ref{acd,,frame} in the
@ref{eba,,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{4cb8,,line}
attribute accessed (which also happens when casting it to a @ref{1ce,,tuple}).
@code{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 (ιδιότητα της traceback.FrameSummary)
@anchor{library/traceback traceback FrameSummary filename}@anchor{4cb5}
@deffn {Ιδιότητα} filename

The filename of the source code for this frame. Equivalent to accessing
@ref{1712,,f.f_code.co_filename} on a
@ref{acd,,frame object} `f'.
@end deffn

@geindex lineno (ιδιότητα της traceback.FrameSummary)
@anchor{library/traceback traceback FrameSummary lineno}@anchor{4cb6}
@deffn {Ιδιότητα} lineno

The line number of the source code for this frame.
@end deffn

@geindex name (ιδιότητα της traceback.FrameSummary)
@anchor{library/traceback traceback FrameSummary name}@anchor{4cb7}
@deffn {Ιδιότητα} name

Equivalent to accessing @ref{2579,,f.f_code.co_name} on
a @ref{acd,,frame object} `f'.
@end deffn

@geindex line (ιδιότητα της traceback.FrameSummary)
@anchor{library/traceback traceback FrameSummary line}@anchor{4cb8}
@deffn {Ιδιότητα} 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

@geindex end_lineno (ιδιότητα της traceback.FrameSummary)
@anchor{library/traceback traceback FrameSummary end_lineno}@anchor{4cd2}
@deffn {Ιδιότητα} end_lineno

The last line number of the source code for this frame.
By default, it is set to @code{lineno} and indexation starts from 1.


Άλλαξε στην έκδοση 3.13: The default value changed from @code{None} to @code{lineno}.

@end deffn

@geindex colno (ιδιότητα της traceback.FrameSummary)
@anchor{library/traceback traceback FrameSummary colno}@anchor{4cd3}
@deffn {Ιδιότητα} colno

The column number of the source code for this frame.
By default, it is @code{None} and indexation starts from 0.
@end deffn

@geindex end_colno (ιδιότητα της traceback.FrameSummary)
@anchor{library/traceback traceback FrameSummary end_colno}@anchor{4cd4}
@deffn {Ιδιότητα} end_colno

The last column number of the source code for this frame.
By default, it is @code{None} and indexation starts from 0.
@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{4cd5}@anchor{library/traceback traceback-example}@anchor{4cd6}
@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{1b,,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{4cd7}
@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node __future__ — Future statement definitions,gc — Garbage Collector interface,traceback — Print or retrieve a stack traceback,Python Runtime Services
@anchor{library/__future__ doc}@anchor{4cd8}@anchor{library/__future__ future-future-statement-definitions}@anchor{4cd9}@anchor{library/__future__ module-__future__}@anchor{0}@anchor{library/__future__ translation-repo}@anchor{4cda}
@subsection @code{__future__} — Future statement definitions


@geindex module; __future__

`Source code:' Lib/__future__.py@footnote{https://github.com/python/cpython/tree/main/Lib/__future__.py}


__________________________________________________________________


Imports of the form @code{from __future__ import feature} are called
@ref{670,,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 @code{__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 
To avoid confusing existing tools that analyze import statements and expect to
find the modules they’re importing.

@item 
To document when incompatible changes were introduced, and when they will be
— or were — made mandatory.  This is a form of executable documentation, and
can be inspected programmatically via importing @code{__future__} and examining
its contents.

@item 
To ensure that @ref{670,,future statements} run under releases prior to
Python 2.1 at least yield runtime exceptions (the import of @code{__future__}
will fail, because there was no module of that name prior to 2.1).
@end itemize

@menu
* Module Contents: Module Contents<2>. 

@end menu

@node Module Contents<2>,,,__future__ — Future statement definitions
@anchor{library/__future__ module-contents}@anchor{4cdb}
@subsubsection Module Contents


No feature description will ever be deleted from @code{__future__}. Since its
introduction in Python 2.1 the following features have found their way into the
language using this mechanism:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

feature

@tab

optional in

@tab

mandatory in

@tab

effect

@item

@geindex nested_scopes (στη μονάδα __future__)
@anchor{library/__future__ future__ nested_scopes}@anchor{4cdc}
@deffn {Δεδομένα} __future__.nested_scopes
@end deffn

@tab

2.1.0b1

@tab

2.2

@tab

@geindex Python Enhancement Proposals; PEP 227
PEP 227@footnote{https://peps.python.org/pep-0227/}: `Statically Nested Scopes'

@item

@geindex generators (στη μονάδα __future__)
@anchor{library/__future__ future__ generators}@anchor{4cdd}
@deffn {Δεδομένα} __future__.generators
@end deffn

@tab

2.2.0a1

@tab

2.3

@tab

@geindex Python Enhancement Proposals; PEP 255
PEP 255@footnote{https://peps.python.org/pep-0255/}: `Simple Generators'

@item

@geindex division (στη μονάδα __future__)
@anchor{library/__future__ future__ division}@anchor{4cde}
@deffn {Δεδομένα} __future__.division
@end deffn

@tab

2.2.0a2

@tab

3.0

@tab

@geindex Python Enhancement Proposals; PEP 238
PEP 238@footnote{https://peps.python.org/pep-0238/}: `Changing the Division Operator'

@item

@geindex absolute_import (στη μονάδα __future__)
@anchor{library/__future__ future__ absolute_import}@anchor{4cdf}
@deffn {Δεδομένα} __future__.absolute_import
@end deffn

@tab

2.5.0a1

@tab

3.0

@tab

@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/}: `Imports: Multi-Line and Absolute/Relative'

@item

@geindex with_statement (στη μονάδα __future__)
@anchor{library/__future__ future__ with_statement}@anchor{4ce0}
@deffn {Δεδομένα} __future__.with_statement
@end deffn

@tab

2.5.0a1

@tab

2.6

@tab

@geindex Python Enhancement Proposals; PEP 343
PEP 343@footnote{https://peps.python.org/pep-0343/}: `The “with” Statement'

@item

@geindex print_function (στη μονάδα __future__)
@anchor{library/__future__ future__ print_function}@anchor{4ce1}
@deffn {Δεδομένα} __future__.print_function
@end deffn

@tab

2.6.0a2

@tab

3.0

@tab

@geindex Python Enhancement Proposals; PEP 3105
PEP 3105@footnote{https://peps.python.org/pep-3105/}: `Make print a function'

@item

@geindex unicode_literals (στη μονάδα __future__)
@anchor{library/__future__ future__ unicode_literals}@anchor{4ce2}
@deffn {Δεδομένα} __future__.unicode_literals
@end deffn

@tab

2.6.0a2

@tab

3.0

@tab

@geindex Python Enhancement Proposals; PEP 3112
PEP 3112@footnote{https://peps.python.org/pep-3112/}: `Bytes literals in Python 3000'

@item

@geindex generator_stop (στη μονάδα __future__)
@anchor{library/__future__ future__ generator_stop}@anchor{4ce3}
@deffn {Δεδομένα} __future__.generator_stop
@end deffn

@tab

3.5.0b1

@tab

3.7

@tab

@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/}: `StopIteration handling inside generators'

@item

@geindex annotations (στη μονάδα __future__)
@anchor{library/__future__ future__ annotations}@anchor{4ce4}
@deffn {Δεδομένα} __future__.annotations
@end deffn

@tab

3.7.0b1

@tab

Never @footnote{
@code{from __future__ import annotations} was previously scheduled to
become mandatory in Python 3.10, but the change was delayed and ultimately
canceled. This feature will eventually be deprecated and removed. See
@geindex Python Enhancement Proposals; PEP 649
@uref{https://peps.python.org/pep-0649/,PEP 649} and 
@geindex Python Enhancement Proposals; PEP 749
@uref{https://peps.python.org/pep-0749/,PEP 749}.
}

@tab

@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/}: `Postponed evaluation of annotations',
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/}: `Deferred evaluation of annotations using descriptors'

@end multitable


@c XXX Adding a new entry?  Remember to update simple_stmts.rst, too.

@geindex _Feature (κλάση σε __future__)
@anchor{library/__future__ future-classes}@anchor{4ce5}@anchor{library/__future__ future__ _Feature}@anchor{27c1}
@deffn {Κλάση} __future__._Feature

Each statement in @code{__future__.py} is of the form:

@example
FeatureName = _Feature(OptionalRelease, MandatoryRelease,
                       CompilerFlag)
@end example

where, normally, `OptionalRelease' is less than `MandatoryRelease', and both are
5-tuples of the same form as @ref{2fc,,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() (μέθοδος της __future__._Feature)
@anchor{library/__future__ future__ _Feature getOptionalRelease}@anchor{4ce6}
@deffn {Μέθοδος} _Feature.getOptionalRelease ()

`OptionalRelease' records the first release in which the feature was accepted.
@end deffn

@geindex getMandatoryRelease() (μέθοδος της __future__._Feature)
@anchor{library/__future__ future__ _Feature getMandatoryRelease}@anchor{4ce7}
@deffn {Μέθοδος} _Feature.getMandatoryRelease ()

In the case of a `MandatoryRelease' that has not yet occurred,
`MandatoryRelease' predicts the release in which the feature will become part of
the language.

Else `MandatoryRelease' records when the feature became part of the language; in
releases at or after that, modules no longer need a future statement to use the
feature in question, but may continue to use such imports.

`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 (ιδιότητα της __future__._Feature)
@anchor{library/__future__ future__ _Feature compiler_flag}@anchor{2587}
@deffn {Ιδιότητα} _Feature.compiler_flag

`CompilerFlag' is the (bitfield) flag that should be passed in the fourth
argument to the built-in function @ref{1c8,,compile()} to enable the feature in
dynamically compiled code.  This flag is stored in the @code{_Feature.compiler_flag}
attribute on @ref{27c1,,_Feature} instances.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item @ref{670,,Μελλοντικές δηλώσεις}

How the compiler treats future imports.

@geindex Python Enhancement Proposals; PEP 236

@item PEP 236@footnote{https://peps.python.org/pep-0236/} - Back to the __future__

The original proposal for the __future__ mechanism.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node gc — Garbage Collector interface,inspect — Inspect live objects,__future__ — Future statement definitions,Python Runtime Services
@anchor{library/gc doc}@anchor{4ce8}@anchor{library/gc gc-garbage-collector-interface}@anchor{4ce9}@anchor{library/gc module-gc}@anchor{63}@anchor{library/gc translation-repo}@anchor{4cea}
@subsection @code{gc} — Garbage Collector interface


@geindex module; gc


__________________________________________________________________


This module provides an interface to the optional garbage collector.  It
provides the ability to disable the collector, tune the collection frequency,
and set debugging options.  It also provides access to unreachable objects that
the collector found but cannot free.  Since the collector supplements the
reference counting already used in Python, you can disable the collector if you
are sure your program does not create reference cycles.  Automatic collection
can be disabled by calling @code{gc.disable()}.  To debug a leaking program call
@code{gc.set_debug(gc.DEBUG_LEAK)}. Notice that this includes
@code{gc.DEBUG_SAVEALL}, causing garbage-collected objects to be saved in
gc.garbage for inspection.

The @code{gc} module provides the following functions:

@geindex enable() (στη μονάδα gc)
@anchor{library/gc gc enable}@anchor{4ceb}
@deffn {Συνάρτηση} gc.enable ()

Enable automatic garbage collection.
@end deffn

@geindex disable() (στη μονάδα gc)
@anchor{library/gc gc disable}@anchor{4cec}
@deffn {Συνάρτηση} gc.disable ()

Disable automatic garbage collection.
@end deffn

@geindex isenabled() (στη μονάδα gc)
@anchor{library/gc gc isenabled}@anchor{4ced}
@deffn {Συνάρτηση} gc.isenabled ()

Return @code{True} if automatic collection is enabled.
@end deffn

@geindex collect() (στη μονάδα gc)
@anchor{library/gc gc collect}@anchor{44f}
@deffn {Συνάρτηση} 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{277,,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{327,,float}.

The effect of calling @code{gc.collect()} while the interpreter is already
performing a collection is undefined.


Άλλαξε στην έκδοση 3.14: @code{generation=1} performs an increment of collection.



Άλλαξε στην έκδοση 3.14.5: @code{generation=1} performs collection of the middle generation.

@end deffn

@geindex set_debug() (στη μονάδα gc)
@anchor{library/gc gc set_debug}@anchor{4cee}
@deffn {Συνάρτηση} gc.set_debug (flags)

Set the garbage collection debugging flags. Debugging information will be
written to @code{sys.stderr}.  See below for a list of debugging flags which can be
combined using bit operations to control debugging.
@end deffn

@geindex get_debug() (στη μονάδα gc)
@anchor{library/gc gc get_debug}@anchor{4cef}
@deffn {Συνάρτηση} gc.get_debug ()

Return the debugging flags currently set.
@end deffn

@geindex get_objects() (στη μονάδα gc)
@anchor{library/gc gc get_objects}@anchor{bdd}
@deffn {Συνάρτηση} 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.


Άλλαξε στην έκδοση 3.8: New `generation' parameter.



Άλλαξε στην έκδοση 3.14: Generation 1 is removed



Άλλαξε στην έκδοση 3.14.5: Generation 1 is reintroduced to maintain GC behavior from 3.13.


Raises an @ref{1e65,,auditing event} @code{gc.get_objects} with argument @code{generation}.
@end deffn

@geindex get_stats() (στη μονάδα gc)
@anchor{library/gc gc get_stats}@anchor{557}
@deffn {Συνάρτηση} gc.get_stats ()

Return a list of three per-generation dictionaries containing collection
statistics since interpreter start.  The number of keys may change
in the future, but currently each dictionary will contain the following
items:


@itemize *

@item 
@code{collections} is the number of times this generation was collected;

@item 
@code{collected} is the total number of objects collected inside this
generation;

@item 
@code{uncollectable} is the total number of objects which were found
to be uncollectable (and were therefore moved to the @ref{156a,,garbage}
list) inside this generation;

@item 
@code{candidates} is the total number of objects in this generation which were
considered for collection and traversed;

@item 
@code{duration} is the total time in seconds spent in collections for this
generation.
@end itemize


Added in version 3.4.



Άλλαξε στην έκδοση 3.15: Add @code{duration} and @code{candidates}.

@end deffn

@geindex set_threshold() (στη μονάδα gc)
@anchor{library/gc gc set_threshold}@anchor{555}
@deffn {Συνάρτηση} gc.set_threshold (threshold0[, threshold1[, threshold2]])

Set the garbage collection thresholds (the collection frequency). Setting
`threshold0' to zero disables collection.

The GC classifies objects into three generations depending on how many
collection sweeps they have survived.  New objects are placed in the youngest
generation (generation @code{0}).  If an object survives a collection it is moved
into the next older generation.  Since generation @code{2} is the oldest
generation, objects in that generation remain there after a collection.  In
order to decide when to run, the collector keeps track of the number object
allocations and deallocations since the last collection.  When the number of
allocations minus the number of deallocations exceeds `threshold0', collection
starts.  Initially only generation @code{0} is examined.  If generation @code{0} has
been examined more than `threshold1' times since generation @code{1} has been
examined, then generation @code{1} is examined as well.
With the third generation, things are a bit more complicated,
see Collecting the oldest generation@footnote{https://github.com/python/cpython/blob/ff0ef0a54bef26fc507fbf9b7a6009eb7d3f17f5/InternalDocs/garbage_collector.md#collecting-the-oldest-generation} for more information.

See Garbage collector design@footnote{https://github.com/python/cpython/blob/3.15/InternalDocs/garbage_collector.md} for more information.


Άλλαξε στην έκδοση 3.14: `threshold2' is ignored



Άλλαξε στην έκδοση 3.14.5: `threshold2' is restored to match Python 3.13 behavior.

@end deffn

@geindex get_count() (στη μονάδα gc)
@anchor{library/gc gc get_count}@anchor{556}
@deffn {Συνάρτηση} gc.get_count ()

Return the current collection  counts as a tuple of @code{(count0, count1,
count2)}.
@end deffn

@geindex get_threshold() (στη μονάδα gc)
@anchor{library/gc gc get_threshold}@anchor{554}
@deffn {Συνάρτηση} gc.get_threshold ()

Return the current collection thresholds as a tuple of @code{(threshold0,
threshold1, threshold2)}.
@end deffn

@geindex get_referrers() (στη μονάδα gc)
@anchor{library/gc gc get_referrers}@anchor{bde}
@deffn {Συνάρτηση} gc.get_referrers (*objs)

Return the list of objects that directly refer to any of objs. This function
will only locate those containers which support garbage collection; extension
types which do refer to other objects but do not support garbage collection will
not be found.

Note that objects which have already been dereferenced, but which live in cycles
and have not yet been collected by the garbage collector can be listed among the
resulting referrers.  To get only currently live objects, call @ref{44f,,collect()}
before calling @code{get_referrers()}.

@cartouche
@quotation Προειδοποίηση 
Care must be taken when using objects returned by @code{get_referrers()} because
some of them could still be under construction and hence in a temporarily
invalid state. Avoid using @code{get_referrers()} for any purpose other than
debugging.
@end quotation
@end cartouche

Raises an @ref{1e65,,auditing event} @code{gc.get_referrers} with argument @code{objs}.
@end deffn

@geindex get_referents() (στη μονάδα gc)
@anchor{library/gc gc get_referents}@anchor{bdf}
@deffn {Συνάρτηση} gc.get_referents (*objs)

Return a list of objects directly referred to by any of the arguments. The
referents returned are those objects visited by the arguments” C-level
@ref{36b,,tp_traverse} methods (if any), and may not be all objects actually
directly reachable.  @code{tp_traverse} methods are supported only by objects
that support garbage collection, and are only required to visit objects that may
be involved in a cycle.  So, for example, if an integer is directly reachable
from an argument, that integer object may or may not appear in the result list.

Raises an @ref{1e65,,auditing event} @code{gc.get_referents} with argument @code{objs}.
@end deffn

@geindex is_tracked() (στη μονάδα gc)
@anchor{library/gc gc is_tracked}@anchor{16b2}
@deffn {Συνάρτηση} gc.is_tracked (obj)

Returns @code{True} if the object is currently tracked by the garbage collector,
@code{False} otherwise.  As a general rule, instances of atomic types aren’t
tracked and instances of non-atomic types (containers, user-defined
objects…) are.  However, some type-specific optimizations can be present
in order to suppress the garbage collector footprint of simple instances
(e.g. dicts containing only atomic keys and values):

@example
>>> gc.is_tracked(0)
False
>>> gc.is_tracked("a")
False
>>> gc.is_tracked([])
True
>>> gc.is_tracked(@{@})
False
>>> gc.is_tracked(@{"a": 1@})
True
@end example


Added in version 3.1.

@end deffn

@geindex is_finalized() (στη μονάδα gc)
@anchor{library/gc gc is_finalized}@anchor{ccd}
@deffn {Συνάρτηση} gc.is_finalized (obj)

Returns @code{True} if the given object has been finalized by the
garbage collector, @code{False} otherwise.

@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


Added in version 3.9.

@end deffn

@geindex freeze() (στη μονάδα gc)
@anchor{library/gc gc freeze}@anchor{ef8}
@deffn {Συνάρτηση} 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.


Added in version 3.7.

@end deffn

@geindex unfreeze() (στη μονάδα gc)
@anchor{library/gc gc unfreeze}@anchor{ef9}
@deffn {Συνάρτηση} gc.unfreeze ()

Unfreeze the objects in the permanent generation, put them back into the
oldest generation.


Added in version 3.7.

@end deffn

@geindex get_freeze_count() (στη μονάδα gc)
@anchor{library/gc gc get_freeze_count}@anchor{efa}
@deffn {Συνάρτηση} gc.get_freeze_count ()

Return the number of objects in the permanent generation.


Added in version 3.7.

@end deffn

The following variables are provided for read-only access (you can mutate the
values but should not rebind them):

@geindex garbage (στη μονάδα gc)
@anchor{library/gc gc garbage}@anchor{156a}
@deffn {Δεδομένα} gc.garbage

A list of objects which the collector found to be unreachable but could
not be freed (uncollectable objects).  Starting with Python 3.4, this
list should be empty most of the time, except when using instances of
C extension types with a non-@code{NULL} @code{tp_del} slot.

If @ref{4cf0,,DEBUG_SAVEALL} is set, then all unreachable objects will be
added to this list rather than freed.


Άλλαξε στην έκδοση 3.2: If this list is non-empty at @ref{1a0,,interpreter shutdown}, a
@ref{74f,,ResourceWarning} is emitted, which is silent by default.  If
@ref{156b,,DEBUG_UNCOLLECTABLE} is set, in addition all uncollectable objects
are printed.



Άλλαξε στην έκδοση 3.4: Following 
@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/}, objects with a @ref{13a6,,__del__()} method don’t end
up in @ref{156a,,gc.garbage} anymore.

@end deffn

@geindex callbacks (στη μονάδα gc)
@anchor{library/gc gc callbacks}@anchor{1474}
@deffn {Δεδομένα} gc.callbacks

A list of callbacks that will be invoked by the garbage collector before and
after collection.  The callbacks will be called with two arguments,
`phase' and `info'.

`phase' can be one of two values:

@quotation

«start»: The garbage collection is about to start.

«stop»: The garbage collection has finished.
@end quotation

`info' is a dict providing more information for the callback.  The following
keys are currently defined:

@quotation

«generation»: The oldest generation being collected.

«collected»: When `phase' is «stop», the number of objects
successfully collected.

«uncollectable»: When `phase' is «stop», the number of objects
that could not be collected and were put in @ref{156a,,garbage}.

«candidates»: When `phase' is «stop», the total number of objects in this
generation which were considered for collection and traversed.

«duration»: When `phase' is «stop», the time in seconds spent in the
collection.
@end quotation

Applications can add their own callbacks to this list.  The primary
use cases are:

@quotation

Gathering statistics about garbage collection, such as how often
various generations are collected, and how long the collection
takes.

Allowing applications to identify and clear their own uncollectable
types when they appear in @ref{156a,,garbage}.
@end quotation


Added in version 3.3.



Άλλαξε στην έκδοση 3.15: Add «duration» and «candidates».

@end deffn

The following constants are provided for use with @ref{4cee,,set_debug()}:

@geindex DEBUG_STATS (στη μονάδα gc)
@anchor{library/gc gc DEBUG_STATS}@anchor{4cf1}
@deffn {Δεδομένα} gc.DEBUG_STATS

Print statistics during collection.  This information can be useful when tuning
the collection frequency.
@end deffn

@geindex DEBUG_COLLECTABLE (στη μονάδα gc)
@anchor{library/gc gc DEBUG_COLLECTABLE}@anchor{4cf2}
@deffn {Δεδομένα} gc.DEBUG_COLLECTABLE

Print information on collectable objects found.
@end deffn

@geindex DEBUG_UNCOLLECTABLE (στη μονάδα gc)
@anchor{library/gc gc DEBUG_UNCOLLECTABLE}@anchor{156b}
@deffn {Δεδομένα} gc.DEBUG_UNCOLLECTABLE

Print information of uncollectable objects found (objects which are not
reachable but cannot be freed by the collector).  These objects will be added
to the @code{garbage} list.


Άλλαξε στην έκδοση 3.2: Also print the contents of the @ref{156a,,garbage} list at
@ref{1a0,,interpreter shutdown}, if it isn’t empty.

@end deffn

@geindex DEBUG_SAVEALL (στη μονάδα gc)
@anchor{library/gc gc DEBUG_SAVEALL}@anchor{4cf0}
@deffn {Δεδομένα} gc.DEBUG_SAVEALL

When set, all unreachable objects found will be appended to `garbage' rather
than being freed.  This can be useful for debugging a leaking program.
@end deffn

@geindex DEBUG_LEAK (στη μονάδα gc)
@anchor{library/gc gc DEBUG_LEAK}@anchor{4cf3}
@deffn {Δεδομένα} gc.DEBUG_LEAK

The debugging flags necessary for the collector to print information about a
leaking program (equal to @code{DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE |
DEBUG_SAVEALL}).
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node inspect — Inspect live objects,annotationlib — Functionality for introspecting annotations,gc — Garbage Collector interface,Python Runtime Services
@anchor{library/inspect doc}@anchor{4cf4}@anchor{library/inspect inspect-inspect-live-objects}@anchor{4cf5}@anchor{library/inspect translation-repo}@anchor{4cf6}
@subsection @code{inspect} — Inspect live objects


@c import inspect
@c from inspect import *

@geindex module; inspect
@anchor{library/inspect module-inspect}@anchor{81}
`Source code:' Lib/inspect.py@footnote{https://github.com/python/cpython/tree/main/Lib/inspect.py}


__________________________________________________________________


The @code{inspect} module provides several useful functions to help get
information about live objects such as modules, classes, methods, functions,
tracebacks, frame objects, and code objects.  For example, it can help you
examine the contents of a class, retrieve the source code of a method, extract
and format the argument list for a function, or get all the information you need
to display a detailed traceback.

There are four main kinds of services provided by this module: type checking,
getting source code, inspecting classes and functions, and examining the
interpreter stack.

@menu
* Types and members:: 
* Retrieving source code:: 
* Introspecting callables with the Signature object:: 
* Classes and functions: Classes and functions<2>. 
* The interpreter stack:: 
* Fetching attributes statically:: 
* Current State of Generators@comma{} Coroutines@comma{} and Asynchronous Generators: Current State of Generators Coroutines and Asynchronous Generators. 
* Code Objects Bit Flags:: 
* Buffer flags:: 
* Command-line interface: Command-line interface<13>. 

@end menu

@node Types and members,Retrieving source code,,inspect — Inspect live objects
@anchor{library/inspect inspect-types}@anchor{1f83}@anchor{library/inspect types-and-members}@anchor{4cf7}
@subsubsection Types and members


The @ref{1de9,,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 @code{getmembers()}.
They also help you determine when you can expect to find the following special
attributes (see @ref{2552,,Χαρακτηριστικά που σχετίζονται με εισαγωγή σε αντικείμενα modules} 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

Attribute

@tab

Description

@item

class

@tab

__doc__

@tab

documentation string

@item

@tab

__name__

@tab

name with which this
class was defined

@item

@tab

__qualname__

@tab

qualified name

@item

@tab

__module__

@tab

name of module in which
this class was defined

@item

@tab

__type_params__

@tab

A tuple containing the
@ref{7a5,,type parameters} of
a generic class

@item

method

@tab

__doc__

@tab

documentation string

@item

@tab

__name__

@tab

name with which this
method was defined

@item

@tab

__qualname__

@tab

qualified name

@item

@tab

__func__

@tab

function object
containing implementation
of method

@item

@tab

__self__

@tab

instance to which this
method is bound, or
@code{None}

@item

@tab

__module__

@tab

name of module in which
this method was defined

@item

function

@tab

__doc__

@tab

documentation string

@item

@tab

__name__

@tab

name with which this
function was defined

@item

@tab

__qualname__

@tab

qualified name

@item

@tab

__code__

@tab

code object containing
compiled function
@ref{6b3,,bytecode}

@item

@tab

__defaults__

@tab

tuple of any default
values for positional or
keyword parameters

@item

@tab

__kwdefaults__

@tab

mapping of any default
values for keyword-only
parameters

@item

@tab

__globals__

@tab

global namespace in which
this function was defined

@item

@tab

__builtins__

@tab

builtins namespace

@item

@tab

__annotations__

@tab

mapping of parameters
names to annotations;
@code{"return"} key is
reserved for return
annotations.

@item

@tab

__type_params__

@tab

A tuple containing the
@ref{7a5,,type parameters} of
a generic function

@item

@tab

__module__

@tab

name of module in which
this function was defined

@item

traceback

@tab

tb_frame

@tab

frame object at this
level

@item

@tab

tb_lasti

@tab

index of last attempted
instruction in bytecode

@item

@tab

tb_lineno

@tab

current line number in
Python source code

@item

@tab

tb_next

@tab

next inner traceback
object (called by this
level)

@item

frame

@tab

f_back

@tab

next outer frame object
(this frame’s caller)

@item

@tab

f_builtins

@tab

builtins namespace seen
by this frame

@item

@tab

f_code

@tab

code object being
executed in this frame

@item

@tab

f_globals

@tab

global namespace seen by
this frame

@item

@tab

f_lasti

@tab

index of last attempted
instruction in bytecode

@item

@tab

f_lineno

@tab

current line number in
Python source code

@item

@tab

f_locals

@tab

local namespace seen by
this frame

@item

@tab

f_generator

@tab

returns the generator or
coroutine object that
owns this frame, or
@code{None} if the frame is
of a regular function

@item

@tab

f_trace

@tab

tracing function for this
frame, or @code{None}

@item

@tab

f_trace_lines

@tab

indicate whether a
tracing event is
triggered for each source
source line

@item

@tab

f_trace_opcodes

@tab

indicate whether
per-opcode events are
requested

@item

@tab

clear()

@tab

used to clear all
references to local
variables

@item

code

@tab

co_argcount

@tab

number of arguments (not
including keyword only
arguments, * or **
args)

@item

@tab

co_code

@tab

string of raw compiled
bytecode

@item

@tab

co_cellvars

@tab

tuple of names of cell
variables (referenced by
containing scopes)

@item

@tab

co_consts

@tab

tuple of constants used
in the bytecode

@item

@tab

co_filename

@tab

name of file in which
this code object was
created

@item

@tab

co_firstlineno

@tab

number of first line in
Python source code

@item

@tab

co_flags

@tab

bitmap of @code{CO_*} flags,
read more @ref{2586,,here}

@item

@tab

co_freevars

@tab

tuple of names of free
variables (referenced via
a function’s closure)

@item

@tab

co_posonlyargcount

@tab

number of positional only
arguments

@item

@tab

co_kwonlyargcount

@tab

number of keyword only
arguments (not including
** arg)

@item

@tab

co_name

@tab

name with which this code
object was defined

@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

number of local variables

@item

@tab

co_stacksize

@tab

virtual machine stack
space required

@item

@tab

co_varnames

@tab

tuple of names of
arguments and local
variables

@item

@tab

co_lines()

@tab

returns an iterator that
yields successive
bytecode ranges

@item

@tab

co_positions()

@tab

returns an iterator of
source code positions for
each bytecode instruction

@item

@tab

replace()

@tab

returns a copy of the
code object with new
values

@item

generator

@tab

__name__

@tab

name

@item

@tab

__qualname__

@tab

qualified name

@item

@tab

gi_frame

@tab

frame

@item

@tab

gi_running

@tab

is the generator running?

@item

@tab

gi_suspended

@tab

is the generator
suspended?

@item

@tab

gi_code

@tab

code

@item

@tab

gi_yieldfrom

@tab

object being iterated by
@code{yield from}, or
@code{None}

@item

@tab

gi_state

@tab

state of the generator,
one of @code{GEN_CREATED},
@code{GEN_RUNNING},
@code{GEN_SUSPENDED}, or
@code{GEN_CLOSED}

@item

async generator

@tab

__name__

@tab

name

@item

@tab

__qualname__

@tab

qualified name

@item

@tab

ag_await

@tab

object being awaited on,
or @code{None}

@item

@tab

ag_frame

@tab

frame

@item

@tab

ag_running

@tab

is the generator running?

@item

@tab

ag_suspended

@tab

is the generator
suspended?

@item

@tab

ag_code

@tab

code

@item

@tab

ag_state

@tab

state of the async
generator, one of
@code{AGEN_CREATED},
@code{AGEN_RUNNING},
@code{AGEN_SUSPENDED}, or
@code{AGEN_CLOSED}

@item

coroutine

@tab

__name__

@tab

name

@item

@tab

__qualname__

@tab

qualified name

@item

@tab

cr_await

@tab

object being awaited on,
or @code{None}

@item

@tab

cr_frame

@tab

frame

@item

@tab

cr_running

@tab

is the coroutine running?

@item

@tab

cr_suspended

@tab

is the coroutine
suspended?

@item

@tab

cr_code

@tab

code

@item

@tab

cr_origin

@tab

where coroutine was
created, or @code{None}. See
@ref{f4b,,sys.set_coroutine_origin_tracking_depth()}

@item

@tab

cr_state

@tab

state of the coroutine,
one of @code{CORO_CREATED},
@code{CORO_RUNNING},
@code{CORO_SUSPENDED}, or
@code{CORO_CLOSED}

@item

builtin

@tab

__doc__

@tab

documentation string

@item

@tab

__name__

@tab

original name of this
function or method

@item

@tab

__qualname__

@tab

qualified name

@item

@tab

__self__

@tab

instance to which a
method is bound, or
@code{None}

@end multitable



Άλλαξε στην έκδοση 3.5: Add @code{__qualname__} and @code{gi_yieldfrom} attributes to generators.

The @code{__name__} attribute of generators is now set from the function
name, instead of the code name, and it can now be modified.



Άλλαξε στην έκδοση 3.7: Add @code{cr_origin} attribute to coroutines.



Άλλαξε στην έκδοση 3.10: Add @code{__builtins__} attribute to functions.



Άλλαξε στην έκδοση 3.11: Add @code{gi_suspended} attribute to generators.



Άλλαξε στην έκδοση 3.11: Add @code{cr_suspended} attribute to coroutines.



Άλλαξε στην έκδοση 3.12: Add @code{ag_suspended} attribute to async generators.



Άλλαξε στην έκδοση 3.14: Add @code{f_generator} attribute to frames.



Άλλαξε στην έκδοση 3.15: Add @code{gi_state} attribute to generators, @code{cr_state} attribute to
coroutines, and @code{ag_state} attribute to async generators.


@geindex getmembers() (στη μονάδα inspect)
@anchor{library/inspect inspect getmembers}@anchor{1de9}
@deffn {Συνάρτηση} inspect.getmembers (object[, predicate])

Return all the members of an object in a list of @code{(name, value)}
pairs sorted by name. If the optional `predicate' argument—which will be
called with the @code{value} object of each member—is supplied, only members
for which the predicate returns a true value are included.

@cartouche
@quotation Σημείωση 
@code{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{1935,,__dir__()}.
@end quotation
@end cartouche
@end deffn

@geindex getmembers_static() (στη μονάδα inspect)
@anchor{library/inspect inspect getmembers_static}@anchor{a38}
@deffn {Συνάρτηση} 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 Σημείωση 
@code{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


Added in version 3.11.

@end deffn

@geindex getmodulename() (στη μονάδα inspect)
@anchor{library/inspect inspect getmodulename}@anchor{10f0}
@deffn {Συνάρτηση} inspect.getmodulename (path)

Return the name of the module named by the file `path', without including the
names of enclosing packages. The file extension is checked against all of
the entries in @ref{4cf8,,importlib.machinery.all_suffixes()}. If it matches,
the final path component is returned with the extension removed.
Otherwise, @code{None} is returned.

Note that this function `only' returns a meaningful name for actual
Python modules - paths that potentially refer to Python packages will
still return @code{None}.


Άλλαξε στην έκδοση 3.3: The function is based directly on @ref{7a,,importlib}.

@end deffn

@geindex ismodule() (στη μονάδα inspect)
@anchor{library/inspect inspect ismodule}@anchor{4cf9}
@deffn {Συνάρτηση} inspect.ismodule (object)

Return @code{True} if the object is a module.
@end deffn

@geindex isclass() (στη μονάδα inspect)
@anchor{library/inspect inspect isclass}@anchor{4cfa}
@deffn {Συνάρτηση} inspect.isclass (object)

Return @code{True} if the object is a class, whether built-in or created in Python
code.
@end deffn

@geindex ismethod() (στη μονάδα inspect)
@anchor{library/inspect inspect ismethod}@anchor{4cfb}
@deffn {Συνάρτηση} inspect.ismethod (object)

Return @code{True} if the object is a bound method written in Python.
@end deffn

@geindex ispackage() (στη μονάδα inspect)
@anchor{library/inspect inspect ispackage}@anchor{4c0}
@deffn {Συνάρτηση} inspect.ispackage (object)

Return @code{True} if the object is a @ref{4c1,,package}.


Added in version 3.14.

@end deffn

@geindex isfunction() (στη μονάδα inspect)
@anchor{library/inspect inspect isfunction}@anchor{4cfc}
@deffn {Συνάρτηση} inspect.isfunction (object)

Return @code{True} if the object is a Python function, which includes functions
created by a @ref{2dce,,lambda} expression.
@end deffn

@geindex isgeneratorfunction() (στη μονάδα inspect)
@anchor{library/inspect inspect isgeneratorfunction}@anchor{1d59}
@deffn {Συνάρτηση} inspect.isgeneratorfunction (object)

Return @code{True} if the object is a Python generator function.


Άλλαξε στην έκδοση 3.8: Functions wrapped in @ref{4a6,,functools.partial()} now return @code{True} if the
wrapped function is a Python generator function.



Άλλαξε στην έκδοση 3.13: Functions wrapped in @ref{4a7,,functools.partialmethod()} now return @code{True}
if the wrapped function is a Python generator function.

@end deffn

@geindex isgenerator() (στη μονάδα inspect)
@anchor{library/inspect inspect isgenerator}@anchor{4cfd}
@deffn {Συνάρτηση} inspect.isgenerator (object)

Return @code{True} if the object is a generator.
@end deffn

@geindex iscoroutinefunction() (στη μονάδα inspect)
@anchor{library/inspect inspect iscoroutinefunction}@anchor{302}
@deffn {Συνάρτηση} inspect.iscoroutinefunction (object)

Return @code{True} if the object is a @ref{112c,,coroutine function} (a function
defined with an @ref{9cf,,async def} syntax), a @ref{4a6,,functools.partial()}
wrapping a coroutine function, or a sync function marked with
@ref{8a1,,markcoroutinefunction()}.


Added in version 3.5.



Άλλαξε στην έκδοση 3.8: Functions wrapped in @ref{4a6,,functools.partial()} now return @code{True} if the
wrapped function is a @ref{112c,,coroutine function}.



Άλλαξε στην έκδοση 3.12: Sync functions marked with @ref{8a1,,markcoroutinefunction()} now return
@code{True}.



Άλλαξε στην έκδοση 3.13: Functions wrapped in @ref{4a7,,functools.partialmethod()} now return @code{True}
if the wrapped function is a @ref{112c,,coroutine function}.

@end deffn

@geindex markcoroutinefunction() (στη μονάδα inspect)
@anchor{library/inspect inspect markcoroutinefunction}@anchor{8a1}
@deffn {Συνάρτηση} inspect.markcoroutinefunction (func)

Decorator to mark a callable as a @ref{112c,,coroutine function} if it would not
otherwise be detected by @ref{302,,iscoroutinefunction()}.

This may be of use for sync functions that return a @ref{8a2,,coroutine}, if
the function is passed to an API that requires @ref{302,,iscoroutinefunction()}.

When possible, using an @ref{9cf,,async def} function is preferred. Also
acceptable is calling the function and testing the return with
@ref{11ca,,iscoroutine()}.


Added in version 3.12.

@end deffn

@geindex iscoroutine() (στη μονάδα inspect)
@anchor{library/inspect inspect iscoroutine}@anchor{11ca}
@deffn {Συνάρτηση} inspect.iscoroutine (object)

Return @code{True} if the object is a @ref{8a2,,coroutine} created by an
@ref{9cf,,async def} function.


Added in version 3.5.

@end deffn

@geindex isawaitable() (στη μονάδα inspect)
@anchor{library/inspect inspect isawaitable}@anchor{11cb}
@deffn {Συνάρτηση} inspect.isawaitable (object)

Return @code{True} if the object can be used in @ref{432,,await} expression.

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


Added in version 3.5.

@end deffn

@geindex isasyncgenfunction() (στη μονάδα inspect)
@anchor{library/inspect inspect isasyncgenfunction}@anchor{1d5a}
@deffn {Συνάρτηση} inspect.isasyncgenfunction (object)

Return @code{True} if the object is an @ref{2692,,asynchronous generator} function,
for example:

@example
>>> async def agen():
...     yield 1
...
>>> inspect.isasyncgenfunction(agen)
True
@end example


Added in version 3.6.



Άλλαξε στην έκδοση 3.8: Functions wrapped in @ref{4a6,,functools.partial()} now return @code{True} if the
wrapped function is an @ref{2692,,asynchronous generator} function.



Άλλαξε στην έκδοση 3.13: Functions wrapped in @ref{4a7,,functools.partialmethod()} now return @code{True}
if the wrapped function is a @ref{2692,,asynchronous generator} function.

@end deffn

@geindex isasyncgen() (στη μονάδα inspect)
@anchor{library/inspect inspect isasyncgen}@anchor{4cfe}
@deffn {Συνάρτηση} inspect.isasyncgen (object)

Return @code{True} if the object is an @ref{3b87,,asynchronous generator iterator}
created by an @ref{2692,,asynchronous generator} function.


Added in version 3.6.

@end deffn

@geindex istraceback() (στη μονάδα inspect)
@anchor{library/inspect inspect istraceback}@anchor{4cff}
@deffn {Συνάρτηση} inspect.istraceback (object)

Return @code{True} if the object is a traceback.
@end deffn

@geindex isframe() (στη μονάδα inspect)
@anchor{library/inspect inspect isframe}@anchor{4d00}
@deffn {Συνάρτηση} inspect.isframe (object)

Return @code{True} if the object is a frame.
@end deffn

@geindex iscode() (στη μονάδα inspect)
@anchor{library/inspect inspect iscode}@anchor{4d01}
@deffn {Συνάρτηση} inspect.iscode (object)

Return @code{True} if the object is a code.
@end deffn

@geindex isbuiltin() (στη μονάδα inspect)
@anchor{library/inspect inspect isbuiltin}@anchor{4d02}
@deffn {Συνάρτηση} inspect.isbuiltin (object)

Return @code{True} if the object is a built-in function or a bound built-in method.
@end deffn

@geindex ismethodwrapper() (στη μονάδα inspect)
@anchor{library/inspect inspect ismethodwrapper}@anchor{a39}
@deffn {Συνάρτηση} inspect.ismethodwrapper (object)

Return @code{True} if the type of object is a @ref{a3a,,MethodWrapperType}.

These are instances of @ref{a3a,,MethodWrapperType}, such as @ref{a0f,,__str__()},
@ref{ec0,,__eq__()} and @ref{1bc,,__repr__()}.


Added in version 3.11.

@end deffn

@geindex isroutine() (στη μονάδα inspect)
@anchor{library/inspect inspect isroutine}@anchor{1dd6}
@deffn {Συνάρτηση} inspect.isroutine (object)

Return @code{True} if the object is a user-defined or built-in function or method.
@end deffn

@geindex isabstract() (στη μονάδα inspect)
@anchor{library/inspect inspect isabstract}@anchor{4d03}
@deffn {Συνάρτηση} inspect.isabstract (object)

Return @code{True} if the object is an abstract base class.
@end deffn

@geindex ismethoddescriptor() (στη μονάδα inspect)
@anchor{library/inspect inspect ismethoddescriptor}@anchor{1b63}
@deffn {Συνάρτηση} inspect.ismethoddescriptor (object)

Return @code{True} if the object is a method descriptor, but not if
@ref{4cfb,,ismethod()}, @ref{4cfa,,isclass()}, @ref{4cfc,,isfunction()} or @ref{4d02,,isbuiltin()}
are true.

This, for example, is true of @code{int.__add__}.  An object passing this test
has a @ref{188a,,__get__()} method, but not a @ref{25aa,,__set__()}
method or a @ref{1b64,,__delete__()} method.  Beyond that, the set of
attributes varies.  A @ref{140e,,__name__} attribute is usually
sensible, and @ref{cf4,,__doc__} often is.

Methods implemented via descriptors that also pass one of the other tests
return @code{False} from the @code{ismethoddescriptor()} test, simply because the
other tests promise more – you can, e.g., count on having the
@ref{16a1,,__func__} attribute (etc) when an object passes
@ref{4cfb,,ismethod()}.


Άλλαξε στην έκδοση 3.13: This function no longer incorrectly reports objects with @ref{188a,,__get__()}
and @ref{1b64,,__delete__()}, but not @ref{25aa,,__set__()}, as being method
descriptors (such objects are data descriptors, not method descriptors).

@end deffn

@geindex isdatadescriptor() (στη μονάδα inspect)
@anchor{library/inspect inspect isdatadescriptor}@anchor{4d04}
@deffn {Συνάρτηση} inspect.isdatadescriptor (object)

Return @code{True} if the object is a data descriptor.

Data descriptors have a @ref{25aa,,__set__} or a @ref{1b64,,__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{140e,,__name__} and @code{__doc__} attributes
(properties, getsets, and members have both of these attributes), but this is
not guaranteed.
@end deffn

@geindex isgetsetdescriptor() (στη μονάδα inspect)
@anchor{library/inspect inspect isgetsetdescriptor}@anchor{4d05}
@deffn {Συνάρτηση} inspect.isgetsetdescriptor (object)

Return @code{True} if the object is a getset descriptor.

`Λεπτομέρεια υλοποίησης CPython:' getsets are attributes defined in extension modules via
@ref{f77,,PyGetSetDef} structures.  For Python implementations without such
types, this method will always return @code{False}.
@end deffn

@geindex ismemberdescriptor() (στη μονάδα inspect)
@anchor{library/inspect inspect ismemberdescriptor}@anchor{4d06}
@deffn {Συνάρτηση} inspect.ismemberdescriptor (object)

Return @code{True} if the object is a member descriptor.

`Λεπτομέρεια υλοποίησης CPython:' Member descriptors are attributes defined in extension modules via
@ref{95a,,PyMemberDef} structures.  For Python implementations without such
types, this method will always return @code{False}.
@end deffn

@node Retrieving source code,Introspecting callables with the Signature object,Types and members,inspect — Inspect live objects
@anchor{library/inspect inspect-source}@anchor{4d07}@anchor{library/inspect retrieving-source-code}@anchor{4d08}
@subsubsection Retrieving source code


@geindex getdoc() (στη μονάδα inspect)
@anchor{library/inspect inspect getdoc}@anchor{22c}
@deffn {Συνάρτηση} inspect.getdoc (object, *, inherit_class_doc=True, fallback_to_class_doc=True)

Get the documentation string for an object, cleaned up with @ref{1c34,,cleandoc()}.
If the documentation string for an object is not provided:


@itemize *

@item 
if the object is a class and `inherit_class_doc' is true (by default),
retrieve the documentation string from the inheritance hierarchy;

@item 
if the object is a method, a property or a descriptor, retrieve
the documentation string from the inheritance hierarchy;

@item 
otherwise, if `fallback_to_class_doc' is true (by default), retrieve
the documentation string from the class of the object.
@end itemize

Return @code{None} if the documentation string is invalid or missing.


Άλλαξε στην έκδοση 3.5: Documentation strings are now inherited if not overridden.



Άλλαξε στην έκδοση 3.15: Added parameters `inherit_class_doc' and `fallback_to_class_doc'.

Documentation strings on @ref{94e,,cached_property}
objects are now inherited if not overridden.

@end deffn

@geindex getcomments() (στη μονάδα inspect)
@anchor{library/inspect inspect getcomments}@anchor{1b52}
@deffn {Συνάρτηση} inspect.getcomments (object)

Return in a single string any lines of comments immediately preceding the
object’s source code (for a class, function, or method), or at the top of the
Python source file (if the object is a module).  If the object’s source code
is unavailable, return @code{None}.  This could happen if the object has been
defined in C or the interactive shell.
@end deffn

@geindex getfile() (στη μονάδα inspect)
@anchor{library/inspect inspect getfile}@anchor{2072}
@deffn {Συνάρτηση} inspect.getfile (object)

Return the name of the (text or binary) file in which an object was defined.
This will fail with a @ref{291,,TypeError} if the object is a built-in module,
class, or function.
@end deffn

@geindex getmodule() (στη μονάδα inspect)
@anchor{library/inspect inspect getmodule}@anchor{1d6a}
@deffn {Συνάρτηση} 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() (στη μονάδα inspect)
@anchor{library/inspect inspect getsourcefile}@anchor{1d6b}
@deffn {Συνάρτηση} 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{291,,TypeError} if the object is a built-in module, class, or
function.
@end deffn

@geindex getsourcelines() (στη μονάδα inspect)
@anchor{library/inspect inspect getsourcelines}@anchor{19f3}
@deffn {Συνάρτηση} 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{53c,,OSError} is raised if the source code cannot
be retrieved.
A @ref{291,,TypeError} is raised if the object is a built-in module, class, or
function.


Άλλαξε στην έκδοση 3.3: @ref{53c,,OSError} is raised instead of @ref{13fb,,IOError}, now an alias of the
former.

@end deffn

@geindex getsource() (στη μονάδα inspect)
@anchor{library/inspect inspect getsource}@anchor{1a04}
@deffn {Συνάρτηση} 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{53c,,OSError} is raised if the source code
cannot be retrieved.
A @ref{291,,TypeError} is raised if the object is a built-in module, class, or
function.


Άλλαξε στην έκδοση 3.3: @ref{53c,,OSError} is raised instead of @ref{13fb,,IOError}, now an alias of the
former.

@end deffn

@geindex cleandoc() (στη μονάδα inspect)
@anchor{library/inspect inspect cleandoc}@anchor{1c34}
@deffn {Συνάρτηση} inspect.cleandoc (doc)

Clean up indentation from docstrings that are indented to line up with blocks
of code.

All leading whitespace is removed from the first line.  Any leading whitespace
that can be uniformly removed from the second line onwards is removed.  Empty
lines at the beginning and end are subsequently removed.  Also, all tabs are
expanded to spaces.
@end deffn

@node Introspecting callables with the Signature object,Classes and functions<2>,Retrieving source code,inspect — Inspect live objects
@anchor{library/inspect inspect-signature-object}@anchor{4d09}@anchor{library/inspect introspecting-callables-with-the-signature-object}@anchor{4d0a}
@subsubsection Introspecting callables with the Signature object



Added in version 3.3.


The @ref{6e8,,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() (στη μονάδα inspect)
@anchor{library/inspect inspect signature}@anchor{4bd}
@deffn {Συνάρτηση} inspect.signature (callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False, annotation_format=Format.VALUE)

Return a @ref{6e8,,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

Accepts a wide range of Python callables, from plain functions and classes to
@ref{4a6,,functools.partial()} objects.

If some of the annotations are strings (e.g., because
@code{from __future__ import annotations} was used), @code{signature()} will
attempt to automatically un-stringize the annotations using
@ref{66c,,annotationlib.get_annotations()}.  The
`globals', `locals', and `eval_str' parameters are passed
into @code{annotationlib.get_annotations()} when resolving the
annotations; see the documentation for @code{annotationlib.get_annotations()}
for instructions on how to use these parameters. A member of the
@ref{4be,,annotationlib.Format} enum can be passed to the
`annotation_format' parameter to control the format of the returned
annotations. For example, use
@code{annotation_format=annotationlib.Format.STRING} to return annotations in string
format.

Raises @ref{277,,ValueError} if no signature can be provided, and
@ref{291,,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{66c,,annotationlib.get_annotations()}
could potentially raise any kind of exception.

A slash (/) in the signature of a function denotes that the parameters prior
to it are positional-only. For more info, see
@ref{27cf,,the FAQ entry on positional-only parameters}.


Άλλαξε στην έκδοση 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.)



Άλλαξε στην έκδοση 3.10: The `globals', `locals', and `eval_str' parameters were added.



Άλλαξε στην έκδοση 3.14: The `annotation_format' parameter was added.


@cartouche
@quotation Σημείωση 
Some callables may not be introspectable in certain implementations of
Python.  For example, in CPython, some built-in functions defined in
C provide no metadata about their arguments.
@end quotation
@end cartouche

`Λεπτομέρεια υλοποίησης 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 (κλάση σε inspect)
@anchor{library/inspect inspect Signature}@anchor{6e8}
@deffn {Κλάση} 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{6e9,,Parameter} object in its @ref{4d0b,,parameters} collection.

The optional `parameters' argument is a sequence of @ref{6e9,,Parameter}
objects, which is validated to check that there are no parameters with
duplicate names, and that the parameters are in the right order, i.e.
positional-only first, then positional-or-keyword, and that parameters with
defaults follow parameters without defaults.

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{4d0c,,Signature.replace()} or
@ref{45a,,copy.replace()} to make a modified copy.


Άλλαξε στην έκδοση 3.5: @code{Signature} objects are now picklable and @ref{183,,hashable}.


@geindex empty (ιδιότητα της inspect.Signature)
@anchor{library/inspect inspect Signature empty}@anchor{4d0d}
@deffn {Ιδιότητα} empty

A special class-level marker to specify absence of a return annotation.
@end deffn

@geindex parameters (ιδιότητα της inspect.Signature)
@anchor{library/inspect inspect Signature parameters}@anchor{4d0b}
@deffn {Ιδιότητα} parameters

An ordered mapping of parameters” names to the corresponding
@ref{6e9,,Parameter} objects.  Parameters appear in strict definition
order, including keyword-only parameters.


Άλλαξε στην έκδοση 3.7: Python only explicitly guaranteed that it preserved the declaration
order of keyword-only parameters as of version 3.7, although in practice
this order had always been preserved in Python 3.

@end deffn

@geindex return_annotation (ιδιότητα της inspect.Signature)
@anchor{library/inspect inspect Signature return_annotation}@anchor{4d0e}
@deffn {Ιδιότητα} return_annotation

The «return» annotation for the callable.  If the callable has no «return»
annotation, this attribute is set to @ref{4d0d,,Signature.empty}.
@end deffn

@geindex bind() (μέθοδος της inspect.Signature)
@anchor{library/inspect inspect Signature bind}@anchor{1ab6}
@deffn {Μέθοδος} bind (*args, **kwargs)

Create a mapping from positional and keyword arguments to parameters.
Returns @ref{1411,,BoundArguments} if @code{*args} and @code{**kwargs} match the
signature, or raises a @ref{291,,TypeError}.
@end deffn

@geindex bind_partial() (μέθοδος της inspect.Signature)
@anchor{library/inspect inspect Signature bind_partial}@anchor{4d0f}
@deffn {Μέθοδος} bind_partial (*args, **kwargs)

Works the same way as @ref{1ab6,,Signature.bind()}, but allows the omission of
some required arguments (mimics @ref{4a6,,functools.partial()} behavior.)
Returns @ref{1411,,BoundArguments}, or raises a @ref{291,,TypeError} if the
passed arguments do not match the signature.
@end deffn

@geindex replace() (μέθοδος της inspect.Signature)
@anchor{library/inspect inspect Signature replace}@anchor{4d0c}
@deffn {Μέθοδος} replace (*[, parameters][, return_annotation])

Create a new @code{Signature} instance based on the instance
@code{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{4d0d,,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

@code{Signature} objects are also supported by the generic function
@ref{45a,,copy.replace()}.
@end deffn

@geindex format() (μέθοδος της inspect.Signature)
@anchor{library/inspect inspect Signature format}@anchor{4bf}
@deffn {Μέθοδος} format (*, max_width=None, quote_annotation_strings=True)

Create a string representation of the @code{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.

If `quote_annotation_strings' is False, @ref{409,,annotations}
in the signature are displayed without opening and closing quotation
marks if they are strings. This is useful if the signature was created with the
@ref{40d,,STRING} format or if
@code{from __future__ import annotations} was used.


Added in version 3.13.



Άλλαξε στην έκδοση 3.14: The `unquote_annotations' parameter was added.

@end deffn

@geindex from_callable() (μέθοδος κλάσης της inspect.Signature)
@anchor{library/inspect inspect Signature from_callable}@anchor{b20}
@deffn {Μέθοδος} classmethod from_callable (obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

Return a @code{Signature} (or its subclass) object for a given callable
`obj'.

This method simplifies subclassing of @code{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{4bd,,signature()}.


Added in version 3.5.



Άλλαξε στην έκδοση 3.10: The `globals', `locals', and `eval_str' parameters were added.

@end deffn
@end deffn

@geindex Parameter (κλάση σε inspect)
@anchor{library/inspect inspect Parameter}@anchor{6e9}
@deffn {Κλάση} 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{4d10,,Parameter.replace()} or @ref{45a,,copy.replace()} to create a modified copy.


Άλλαξε στην έκδοση 3.5: Parameter objects are now picklable and @ref{183,,hashable}.


@geindex empty (ιδιότητα της inspect.Parameter)
@anchor{library/inspect inspect Parameter empty}@anchor{4d11}
@deffn {Ιδιότητα} empty

A special class-level marker to specify absence of default values and
annotations.
@end deffn

@geindex name (ιδιότητα της inspect.Parameter)
@anchor{library/inspect inspect Parameter name}@anchor{4d12}
@deffn {Ιδιότητα} name

The name of the parameter as a string.  The name must be a valid
Python identifier.

`Λεπτομέρεια υλοποίησης CPython:' CPython generates implicit parameter names of the form @code{.0} on the
code objects used to implement comprehensions and generator
expressions.


Άλλαξε στην έκδοση 3.6: These parameter names are now exposed by this module as names like
@code{implicit0}.

@end deffn

@geindex default (ιδιότητα της inspect.Parameter)
@anchor{library/inspect inspect Parameter default}@anchor{4d13}
@deffn {Ιδιότητα} default

The default value for the parameter.  If the parameter has no default
value, this attribute is set to @ref{4d11,,Parameter.empty}.
@end deffn

@geindex annotation (ιδιότητα της inspect.Parameter)
@anchor{library/inspect inspect Parameter annotation}@anchor{4d14}
@deffn {Ιδιότητα} annotation

The annotation for the parameter.  If the parameter has no annotation,
this attribute is set to @ref{4d11,,Parameter.empty}.
@end deffn

@geindex kind (ιδιότητα της inspect.Parameter)
@anchor{library/inspect inspect Parameter kind}@anchor{4d15}
@deffn {Ιδιότητα} kind

Describes how argument values are bound to the parameter.  The possible
values are accessible via @code{Parameter} (like @code{Parameter.KEYWORD_ONLY}),
and support comparison and ordering, in the following order:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Name

@tab

Meaning

@item

`POSITIONAL_ONLY'

@tab

Value must be supplied as a positional
argument. Positional only parameters are
those which appear before a @code{/} entry (if
present) in a Python function definition.

@item

`POSITIONAL_OR_KEYWORD'

@tab

Value may be supplied as either a keyword or
positional argument (this is the standard
binding behaviour for functions implemented
in Python.)

@item

`VAR_POSITIONAL'

@tab

A tuple of positional arguments that aren’t
bound to any other parameter. This
corresponds to a @code{*args} parameter in a
Python function definition.

@item

`KEYWORD_ONLY'

@tab

Value must be supplied as a keyword argument.
Keyword only parameters are those which
appear after a @code{*} or @code{*args} entry in a
Python function definition.

@item

`VAR_KEYWORD'

@tab

A dict of keyword arguments that aren’t bound
to any other parameter. This corresponds to a
@code{**kwargs} parameter in a Python function
definition.

@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 (ιδιότητα της inspect.Parameter.kind)
@anchor{library/inspect inspect Parameter kind description}@anchor{4d16}
@deffn {Ιδιότητα} kind.description

Describes an enum value of @ref{4d15,,Parameter.kind}.


Added in 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() (μέθοδος της inspect.Parameter)
@anchor{library/inspect inspect Parameter replace}@anchor{4d10}
@deffn {Μέθοδος} replace (*[, name][, kind][, default][, annotation])

Create a new @code{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{4d11,,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

@code{Parameter} objects are also supported by the generic function
@ref{45a,,copy.replace()}.
@end deffn


Άλλαξε στην έκδοση 3.4: In Python 3.3 @code{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 (κλάση σε inspect)
@anchor{library/inspect inspect BoundArguments}@anchor{1411}
@deffn {Κλάση} inspect.BoundArguments

Result of a @ref{1ab6,,Signature.bind()} or @ref{4d0f,,Signature.bind_partial()} call.
Holds the mapping of arguments to the function’s parameters.

@geindex arguments (ιδιότητα της inspect.BoundArguments)
@anchor{library/inspect inspect BoundArguments arguments}@anchor{cdb}
@deffn {Ιδιότητα} arguments

A mutable mapping of parameters” names to arguments” values.
Contains only explicitly bound arguments.  Changes in @ref{cdb,,arguments}
will reflect in @ref{4d17,,args} and @ref{4d18,,kwargs}.

Should be used in conjunction with @ref{4d0b,,Signature.parameters} for any
argument processing purposes.

@cartouche
@quotation Σημείωση 
Arguments for which @ref{1ab6,,Signature.bind()} or
@ref{4d0f,,Signature.bind_partial()} relied on a default value are skipped.
However, if needed, use @ref{11c9,,BoundArguments.apply_defaults()} to add
them.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.9: @ref{cdb,,arguments} is now of type @ref{188,,dict}. Formerly, it was of
type @ref{9d5,,collections.OrderedDict}.

@end deffn

@geindex args (ιδιότητα της inspect.BoundArguments)
@anchor{library/inspect inspect BoundArguments args}@anchor{4d17}
@deffn {Ιδιότητα} args

A tuple of positional arguments values.  Dynamically computed from the
@ref{cdb,,arguments} attribute.
@end deffn

@geindex kwargs (ιδιότητα της inspect.BoundArguments)
@anchor{library/inspect inspect BoundArguments kwargs}@anchor{4d18}
@deffn {Ιδιότητα} kwargs

A dict of keyword arguments values.  Dynamically computed from the
@ref{cdb,,arguments} attribute.  Arguments that can be passed positionally
are included in @ref{4d17,,args} instead.
@end deffn

@geindex signature (ιδιότητα της inspect.BoundArguments)
@anchor{library/inspect inspect BoundArguments signature}@anchor{4d19}
@deffn {Ιδιότητα} signature

A reference to the parent @ref{6e8,,Signature} object.
@end deffn

@geindex apply_defaults() (μέθοδος της inspect.BoundArguments)
@anchor{library/inspect inspect BoundArguments apply_defaults}@anchor{11c9}
@deffn {Μέθοδος} apply_defaults ()

Set default values for missing arguments.

For variable-positional arguments (@code{*args}) the default is an
empty tuple.

For variable-keyword arguments (@code{**kwargs}) the default is an
empty dict.

@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


Added in version 3.5.

@end deffn

The @ref{4d17,,args} and @ref{4d18,,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 Δείτε επίσης



@table @asis

@geindex Python Enhancement Proposals; PEP 362

@item PEP 362@footnote{https://peps.python.org/pep-0362/} - Function Signature Object.

The detailed specification, implementation details and examples.
@end table


@node Classes and functions<2>,The interpreter stack,Introspecting callables with the Signature object,inspect — Inspect live objects
@anchor{library/inspect classes-and-functions}@anchor{4d1a}@anchor{library/inspect inspect-classes-functions}@anchor{4d1b}
@subsubsection Classes and functions


@geindex getclasstree() (στη μονάδα inspect)
@anchor{library/inspect inspect getclasstree}@anchor{4d1c}
@deffn {Συνάρτηση} inspect.getclasstree (classes, unique=False)

Arrange the given list of classes into a hierarchy of nested lists. Where a
nested list appears, it contains classes derived from the class whose entry
immediately precedes the list.  Each entry is a 2-tuple containing a class and a
tuple of its base classes.  If the `unique' argument is true, exactly one entry
appears in the returned structure for each class in the given list.  Otherwise,
classes using multiple inheritance and their descendants will appear multiple
times.
@end deffn

@geindex getfullargspec() (στη μονάδα inspect)
@anchor{library/inspect inspect getfullargspec}@anchor{b1f}
@deffn {Συνάρτηση} inspect.getfullargspec (func, *, annotation_format=Format.VALUE)

Get the names and default values of a Python function’s parameters.  A
@ref{a3d,,named tuple} is returned:

@code{FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults,
annotations)}

`args' is a list of the positional parameter names.
`varargs' is the name of the @code{*} parameter or @code{None} if arbitrary
positional arguments are not accepted.
`varkw' is the name of the @code{**} parameter or @code{None} if arbitrary
keyword arguments are not accepted.
`defaults' is an `n'-tuple of default argument values corresponding to the
last `n' positional parameters, or @code{None} if there are no such defaults
defined.
`kwonlyargs' is a list of keyword-only parameter names in declaration order.
`kwonlydefaults' is a dictionary mapping parameter names from `kwonlyargs'
to the default values used if no argument is supplied.
`annotations' is a dictionary mapping parameter names to annotations.
The special key @code{"return"} is used to report the function return value
annotation (if any).

Note that @ref{4bd,,signature()} and
@ref{4d09,,Signature Object} provide the recommended
API for callable introspection, and support additional behaviours (like
positional-only arguments) that are sometimes encountered in extension module
APIs. This function is retained primarily for use in code that needs to
maintain compatibility with the Python 2 @code{inspect} module API.

A member of the
@ref{4be,,annotationlib.Format} enum can be passed to the
`annotation_format' parameter to control the format of the returned
annotations. For example, use
@code{annotation_format=annotationlib.Format.STRING} to return annotations in string
format. Note that with the default @code{VALUE} format, creation of some argspecs
may raise an exception.


Άλλαξε στην έκδοση 3.4: This function is now based on @ref{4bd,,signature()}, but still ignores
@code{__wrapped__} attributes and includes the already bound first
parameter in the signature output for bound methods.



Άλλαξε στην έκδοση 3.6: This method was previously documented as deprecated in favour of
@ref{4bd,,signature()} in Python 3.5, but that decision has been reversed
in order to restore a clearly supported standard interface for
single-source Python 2/3 code migrating away from the legacy
@code{getargspec()} API.



Άλλαξε στην έκδοση 3.7: Python only explicitly guaranteed that it preserved the declaration
order of keyword-only parameters as of version 3.7, although in practice
this order had always been preserved in Python 3.



Άλλαξε στην έκδοση 3.15: The `annotation_format' parameter was added.

@end deffn

@geindex getargvalues() (στη μονάδα inspect)
@anchor{library/inspect inspect getargvalues}@anchor{126d}
@deffn {Συνάρτηση} inspect.getargvalues (frame)

Get information about arguments passed into a particular frame.  A
@ref{a3d,,named tuple} @code{ArgInfo(args, varargs, keywords, locals)} is
returned. `args' is a list of the argument names.  `varargs' and `keywords'
are the names of the @code{*} and @code{**} arguments or @code{None}.  `locals' is the
locals dictionary of the given frame.

@cartouche
@quotation Σημείωση 
This function was inadvertently marked as deprecated in Python 3.5.
@end quotation
@end cartouche
@end deffn

@geindex formatargvalues() (στη μονάδα inspect)
@anchor{library/inspect inspect formatargvalues}@anchor{126e}
@deffn {Συνάρτηση} inspect.formatargvalues (args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])

Format a pretty argument spec from the four values returned by
@ref{126d,,getargvalues()}.  The format* arguments are the corresponding optional
formatting functions that are called to turn names and values into strings.

@cartouche
@quotation Σημείωση 
This function was inadvertently marked as deprecated in Python 3.5.
@end quotation
@end cartouche
@end deffn

@geindex getmro() (στη μονάδα inspect)
@anchor{library/inspect inspect getmro}@anchor{4d1d}
@deffn {Συνάρτηση} inspect.getmro (cls)

Return a tuple of class cls’s base classes, including cls, in method resolution
order.  No class appears more than once in this tuple. Note that the method
resolution order depends on cls’s type.  Unless a very peculiar user-defined
metatype is in use, cls will be the first element of the tuple.
@end deffn

@geindex getcallargs() (στη μονάδα inspect)
@anchor{library/inspect inspect getcallargs}@anchor{126c}
@deffn {Συνάρτηση} 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


Added in version 3.2.



Αποσύρθηκε στην έκδοση 3.5: Use @ref{1ab6,,Signature.bind()} and @ref{4d0f,,Signature.bind_partial()} instead.

@end deffn

@geindex getclosurevars() (στη μονάδα inspect)
@anchor{library/inspect inspect getclosurevars}@anchor{1481}
@deffn {Συνάρτηση} inspect.getclosurevars (func)

Get the mapping of external name references in a Python function or
method `func' to their current values. A
@ref{a3d,,named tuple} @code{ClosureVars(nonlocals, globals, builtins, unbound)}
is returned. `nonlocals' maps referenced names to lexical closure
variables, `globals' to the function’s module globals and `builtins' to
the builtins visible from the function body. `unbound' is the set of names
referenced in the function that could not be resolved at all given the
current module globals and builtins.

@ref{291,,TypeError} is raised if `func' is not a Python function or method.


Added in version 3.3.

@end deffn

@geindex unwrap() (στη μονάδα inspect)
@anchor{library/inspect inspect unwrap}@anchor{1306}
@deffn {Συνάρτηση} inspect.unwrap (func, *, stop=None)

Get the object wrapped by `func'. It follows the chain of @code{__wrapped__}
attributes returning the last object in the chain.

`stop' is an optional callback accepting an object in the wrapper chain
as its sole argument that allows the unwrapping to be terminated early if
the callback returns a true value. If the callback never returns a true
value, the last object in the chain is returned as usual. For example,
@ref{4bd,,signature()} uses this to stop unwrapping if any object in the
chain has a @code{__signature__} attribute defined.

@ref{277,,ValueError} is raised if a cycle is encountered.


Added in version 3.4.

@end deffn

@geindex get_annotations() (στη μονάδα inspect)
@anchor{library/inspect inspect get_annotations}@anchor{bec}
@deffn {Συνάρτηση} inspect.get_annotations (obj, *, globals=None, locals=None, eval_str=False, format=annotationlib.Format.VALUE)

Compute the annotations dict for an object.

This is an alias for @ref{66c,,annotationlib.get_annotations()}; see the documentation
of that function for more information.

@cartouche
@quotation Προσοχή 
This function may execute arbitrary code contained in annotations.
See @ref{476f,,Security implications of introspecting annotations} for more information.
@end quotation
@end cartouche


Added in version 3.10.



Άλλαξε στην έκδοση 3.14: This function is now an alias for @ref{66c,,annotationlib.get_annotations()}.
Calling it as @code{inspect.get_annotations} will continue to work.

@end deffn

@node The interpreter stack,Fetching attributes statically,Classes and functions<2>,inspect — Inspect live objects
@anchor{library/inspect inspect-stack}@anchor{4d1e}@anchor{library/inspect the-interpreter-stack}@anchor{4d1f}
@subsubsection The interpreter stack


Some of the following functions return
@ref{a3b,,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 (κλάση σε inspect)
@anchor{library/inspect inspect FrameInfo}@anchor{a3b}
@deffn {Κλάση} inspect.FrameInfo

@geindex frame (ιδιότητα της inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo frame}@anchor{4d20}
@deffn {Ιδιότητα} frame

The @ref{acd,,frame object} that the record corresponds to.
@end deffn

@geindex filename (ιδιότητα της inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo filename}@anchor{4d21}
@deffn {Ιδιότητα} filename

The file name associated with the code being executed by the frame this record
corresponds to.
@end deffn

@geindex lineno (ιδιότητα της inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo lineno}@anchor{4d22}
@deffn {Ιδιότητα} 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 (ιδιότητα της inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo function}@anchor{4d23}
@deffn {Ιδιότητα} function

The function name that is being executed by the frame this record corresponds to.
@end deffn

@geindex code_context (ιδιότητα της inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo code_context}@anchor{4d24}
@deffn {Ιδιότητα} 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 (ιδιότητα της inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo index}@anchor{4d25}
@deffn {Ιδιότητα} index

The index of the current line being executed in the @ref{4d24,,code_context} list.
@end deffn

@geindex positions (ιδιότητα της inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo positions}@anchor{4d26}
@deffn {Ιδιότητα} positions

A @ref{1b58,,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


Άλλαξε στην έκδοση 3.5: Return a @ref{a3d,,named tuple} instead of a @ref{1ce,,tuple}.



Άλλαξε στην έκδοση 3.11: @code{FrameInfo} is now a class instance
(that is backwards compatible with the previous @ref{a3d,,named tuple}).

@end deffn

@geindex Traceback (κλάση σε inspect)
@anchor{library/inspect inspect Traceback}@anchor{a3c}
@deffn {Κλάση} inspect.Traceback

@geindex filename (ιδιότητα της inspect.Traceback)
@anchor{library/inspect inspect Traceback filename}@anchor{4d27}
@deffn {Ιδιότητα} filename

The file name associated with the code being executed by the frame this traceback
corresponds to.
@end deffn

@geindex lineno (ιδιότητα της inspect.Traceback)
@anchor{library/inspect inspect Traceback lineno}@anchor{4d28}
@deffn {Ιδιότητα} 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 (ιδιότητα της inspect.Traceback)
@anchor{library/inspect inspect Traceback function}@anchor{4d29}
@deffn {Ιδιότητα} function

The function name that is being executed by the frame this traceback corresponds to.
@end deffn

@geindex code_context (ιδιότητα της inspect.Traceback)
@anchor{library/inspect inspect Traceback code_context}@anchor{4d2a}
@deffn {Ιδιότητα} 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 (ιδιότητα της inspect.Traceback)
@anchor{library/inspect inspect Traceback index}@anchor{4d2b}
@deffn {Ιδιότητα} index

The index of the current line being executed in the @ref{4d2a,,code_context} list.
@end deffn

@geindex positions (ιδιότητα της inspect.Traceback)
@anchor{library/inspect inspect Traceback positions}@anchor{4d2c}
@deffn {Ιδιότητα} positions

A @ref{1b58,,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


Άλλαξε στην έκδοση 3.11: @code{Traceback} is now a class instance
(that is backwards compatible with the previous @ref{a3d,,named tuple}).

@end deffn

@cartouche
@quotation Σημείωση 
Keeping references to frame objects, as found in the first element of the frame
records these functions return, can cause your program to create reference
cycles.  Once a reference cycle has been created, the lifespan of all objects
which can be accessed from the objects which form the cycle can become much
longer even if Python’s optional cycle detector is enabled.  If such cycles must
be created, it is important to ensure they are explicitly broken to avoid the
delayed destruction of objects and increased memory consumption which occurs.

Though the cycle detector will catch these, destruction of the frames (and local
variables) can be made deterministic by removing the cycle in a
@ref{44c,,finally} clause.  This is also important if the cycle detector was
disabled when Python was compiled or using @ref{4cec,,gc.disable()}.  For example:

@example
def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # do something with the frame
    finally:
        del frame
@end example

If you want to keep the frame around (for example to print a traceback
later), you can also break reference cycles by using the
@ref{784,,frame.clear()} method.
@end quotation
@end cartouche

The optional `context' argument supported by most of these functions specifies
the number of lines of context to return, which are centered around the current
line.

@geindex getframeinfo() (στη μονάδα inspect)
@anchor{library/inspect inspect getframeinfo}@anchor{a3e}
@deffn {Συνάρτηση} inspect.getframeinfo (frame, context=1)

Get information about a frame or traceback object.  A @ref{a3c,,Traceback} object
is returned.


Άλλαξε στην έκδοση 3.11: A @ref{a3c,,Traceback} object is returned instead of a named tuple.

@end deffn

@geindex getouterframes() (στη μονάδα inspect)
@anchor{library/inspect inspect getouterframes}@anchor{a3f}
@deffn {Συνάρτηση} inspect.getouterframes (frame, context=1)

Get a list of @ref{a3b,,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.


Άλλαξε στην έκδοση 3.5: A list of @ref{a3d,,named tuples}
@code{FrameInfo(frame, filename, lineno, function, code_context, index)}
is returned.



Άλλαξε στην έκδοση 3.11: A list of @ref{a3b,,FrameInfo} objects is returned.

@end deffn

@geindex getinnerframes() (στη μονάδα inspect)
@anchor{library/inspect inspect getinnerframes}@anchor{a40}
@deffn {Συνάρτηση} inspect.getinnerframes (traceback, context=1)

Get a list of @ref{a3b,,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.


Άλλαξε στην έκδοση 3.5: A list of @ref{a3d,,named tuples}
@code{FrameInfo(frame, filename, lineno, function, code_context, index)}
is returned.



Άλλαξε στην έκδοση 3.11: A list of @ref{a3b,,FrameInfo} objects is returned.

@end deffn

@geindex currentframe() (στη μονάδα inspect)
@anchor{library/inspect inspect currentframe}@anchor{acf}
@deffn {Συνάρτηση} inspect.currentframe ()

Return the frame object for the caller’s stack frame.

`Λεπτομέρεια υλοποίησης CPython:' This function relies on Python stack frame support in the interpreter,
which isn’t guaranteed to exist in all implementations of Python.  If
running in an implementation without Python stack frame support this
function returns @code{None}.
@end deffn

@geindex stack() (στη μονάδα inspect)
@anchor{library/inspect inspect stack}@anchor{a41}
@deffn {Συνάρτηση} inspect.stack (context=1)

Return a list of @ref{a3b,,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.


Άλλαξε στην έκδοση 3.5: A list of @ref{a3d,,named tuples}
@code{FrameInfo(frame, filename, lineno, function, code_context, index)}
is returned.



Άλλαξε στην έκδοση 3.11: A list of @ref{a3b,,FrameInfo} objects is returned.

@end deffn

@geindex trace() (στη μονάδα inspect)
@anchor{library/inspect inspect trace}@anchor{a42}
@deffn {Συνάρτηση} inspect.trace (context=1)

Return a list of @ref{a3b,,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.


Άλλαξε στην έκδοση 3.5: A list of @ref{a3d,,named tuples}
@code{FrameInfo(frame, filename, lineno, function, code_context, index)}
is returned.



Άλλαξε στην έκδοση 3.11: A list of @ref{a3b,,FrameInfo} objects is returned.

@end deffn

@node Fetching attributes statically,Current State of Generators Coroutines and Asynchronous Generators,The interpreter stack,inspect — Inspect live objects
@anchor{library/inspect fetching-attributes-statically}@anchor{4d2d}
@subsubsection Fetching attributes statically


Both @ref{f8f,,getattr()} and @ref{8e2,,hasattr()} can trigger code execution when
fetching or checking for the existence of attributes. Descriptors, like
properties, will be invoked and @ref{8e3,,__getattr__()} and
@ref{f90,,__getattribute__()}
may be called.

For cases where you want passive introspection, like documentation tools, this
can be inconvenient. @ref{8a5,,getattr_static()} has the same signature as @ref{f8f,,getattr()}
but avoids executing code when it fetches attributes.

@geindex getattr_static() (στη μονάδα inspect)
@anchor{library/inspect inspect getattr_static}@anchor{8a5}
@deffn {Συνάρτηση} inspect.getattr_static (obj, attr, default=None)

Retrieve attributes without triggering dynamic lookup via the
descriptor protocol, @ref{8e3,,__getattr__()}
or @ref{f90,,__getattribute__()}.

Note: this function may not be able to retrieve all attributes
that getattr can fetch (like dynamically created attributes)
and may find attributes that getattr can’t (like descriptors
that raise AttributeError). It can also return descriptors objects
instead of instance members.

If the instance @ref{1bf,,__dict__} is shadowed by another member (for
example a property) then this function will be unable to find instance
members.


Added in version 3.2.

@end deffn

@ref{8a5,,getattr_static()} does not resolve descriptors, for example slot descriptors or
getset descriptors on objects implemented in C. The descriptor object
is returned instead of the underlying attribute.

You can handle these with code like the following. Note that
for arbitrary getset descriptors invoking these may trigger
code execution:

@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,Code Objects Bit Flags,Fetching attributes statically,inspect — Inspect live objects
@anchor{library/inspect current-state-of-generators-coroutines-and-asynchronous-generators}@anchor{4d2e}
@subsubsection Current State of Generators, Coroutines, and Asynchronous Generators


When implementing coroutine schedulers and for other advanced uses of
generators, it is useful to determine whether a generator is currently
executing, is waiting to start or resume or execution, or has already
terminated. @ref{15dc,,getgeneratorstate()} allows the current state of a
generator to be determined easily.

@geindex getgeneratorstate() (στη μονάδα inspect)
@anchor{library/inspect inspect getgeneratorstate}@anchor{15dc}
@deffn {Συνάρτηση} inspect.getgeneratorstate (generator)

Get current state of a generator-iterator.

Possible states are:


@itemize *

@item 
GEN_CREATED: Waiting to start execution.

@item 
GEN_RUNNING: Currently being executed by the interpreter.

@item 
GEN_SUSPENDED: Currently suspended at a yield expression.

@item 
GEN_CLOSED: Execution has completed.
@end itemize


Added in version 3.2.

@end deffn

@geindex getcoroutinestate() (στη μονάδα inspect)
@anchor{library/inspect inspect getcoroutinestate}@anchor{11cd}
@deffn {Συνάρτηση} inspect.getcoroutinestate (coroutine)

Get current state of a coroutine object.  The function is intended to be
used with coroutine objects created by @ref{9cf,,async def} functions, but
will accept any coroutine-like object that has @code{cr_running} and
@code{cr_frame} attributes.

Possible states are:


@itemize *

@item 
CORO_CREATED: Waiting to start execution.

@item 
CORO_RUNNING: Currently being executed by the interpreter.

@item 
CORO_SUSPENDED: Currently suspended at an await expression.

@item 
CORO_CLOSED: Execution has completed.
@end itemize


Added in version 3.5.

@end deffn

@geindex getasyncgenstate() (στη μονάδα inspect)
@anchor{library/inspect inspect getasyncgenstate}@anchor{8a3}
@deffn {Συνάρτηση} 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{9cf,,async def} functions which use the @ref{d93,,yield} statement,
but will accept any asynchronous generator-like object that has
@code{ag_running} and @code{ag_frame} attributes.

Possible states are:


@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


Added in version 3.12.

@end deffn

The current internal state of the generator can also be queried. This is
mostly useful for testing purposes, to ensure that internal state is being
updated as expected:

@geindex getgeneratorlocals() (στη μονάδα inspect)
@anchor{library/inspect inspect getgeneratorlocals}@anchor{1482}
@deffn {Συνάρτηση} inspect.getgeneratorlocals (generator)

Get the mapping of live local variables in `generator' to their current
values.  A dictionary is returned that maps from variable names to values.
This is the equivalent of calling @ref{28b,,locals()} in the body of the
generator, and all the same caveats apply.

If `generator' is a @ref{1409,,generator} with no currently associated frame,
then an empty dictionary is returned.  @ref{291,,TypeError} is raised if
`generator' is not a Python generator object.

`Λεπτομέρεια υλοποίησης CPython:' This function relies on the generator exposing a Python stack frame
for introspection, which isn’t guaranteed to be the case in all
implementations of Python. In such cases, this function will always
return an empty dictionary.


Added in version 3.3.

@end deffn

@geindex getcoroutinelocals() (στη μονάδα inspect)
@anchor{library/inspect inspect getcoroutinelocals}@anchor{11cc}
@deffn {Συνάρτηση} inspect.getcoroutinelocals (coroutine)

This function is analogous to @ref{1482,,getgeneratorlocals()}, but
works for coroutine objects created by @ref{9cf,,async def} functions.


Added in version 3.5.

@end deffn

@geindex getasyncgenlocals() (στη μονάδα inspect)
@anchor{library/inspect inspect getasyncgenlocals}@anchor{8a4}
@deffn {Συνάρτηση} inspect.getasyncgenlocals (agen)

This function is analogous to @ref{1482,,getgeneratorlocals()}, but
works for asynchronous generator objects created by @ref{9cf,,async def}
functions which use the @ref{d93,,yield} statement.


Added in version 3.12.

@end deffn

@node Code Objects Bit Flags,Buffer flags,Current State of Generators Coroutines and Asynchronous Generators,inspect — Inspect live objects
@anchor{library/inspect code-objects-bit-flags}@anchor{4d2f}@anchor{library/inspect inspect-module-co-flags}@anchor{2586}
@subsubsection Code Objects Bit Flags


Python code objects have a @ref{1afc,,co_flags} attribute,
which is a bitmap of the following flags:

@geindex CO_OPTIMIZED (στη μονάδα inspect)
@anchor{library/inspect inspect CO_OPTIMIZED}@anchor{4d30}
@deffn {Δεδομένα} inspect.CO_OPTIMIZED

The code object is optimized, using fast locals.
@end deffn

@geindex CO_NEWLOCALS (στη μονάδα inspect)
@anchor{library/inspect inspect CO_NEWLOCALS}@anchor{4d31}
@deffn {Δεδομένα} inspect.CO_NEWLOCALS

If set, a new dict will be created for the frame’s @ref{28d,,f_locals}
when the code object is executed.
@end deffn

@geindex CO_VARARGS (στη μονάδα inspect)
@anchor{library/inspect inspect CO_VARARGS}@anchor{4d32}
@deffn {Δεδομένα} inspect.CO_VARARGS

The code object has a variable positional parameter (@code{*args}-like).
@end deffn

@geindex CO_VARKEYWORDS (στη μονάδα inspect)
@anchor{library/inspect inspect CO_VARKEYWORDS}@anchor{4d33}
@deffn {Δεδομένα} inspect.CO_VARKEYWORDS

The code object has a variable keyword parameter (@code{**kwargs}-like).
@end deffn

@geindex CO_NESTED (στη μονάδα inspect)
@anchor{library/inspect inspect CO_NESTED}@anchor{4d34}
@deffn {Δεδομένα} inspect.CO_NESTED

The flag is set when the code object is a nested function.
@end deffn

@geindex CO_GENERATOR (στη μονάδα inspect)
@anchor{library/inspect inspect CO_GENERATOR}@anchor{4d35}
@deffn {Δεδομένα} inspect.CO_GENERATOR

The flag is set when the code object is a generator function, i.e.
a generator object is returned when the code object is executed.
@end deffn

@geindex CO_COROUTINE (στη μονάδα inspect)
@anchor{library/inspect inspect CO_COROUTINE}@anchor{4d36}
@deffn {Δεδομένα} inspect.CO_COROUTINE

The flag is set when the code object is a coroutine function.
When the code object is executed it returns a coroutine object.
See 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} for more details.


Added in version 3.5.

@end deffn

@geindex CO_ITERABLE_COROUTINE (στη μονάδα inspect)
@anchor{library/inspect inspect CO_ITERABLE_COROUTINE}@anchor{4d37}
@deffn {Δεδομένα} inspect.CO_ITERABLE_COROUTINE

The flag is used to transform generators into generator-based
coroutines.  Generator objects with this flag can be used in
@code{await} expression, and can @code{yield from} coroutine objects.
See 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} for more details.


Added in version 3.5.

@end deffn

@geindex CO_ASYNC_GENERATOR (στη μονάδα inspect)
@anchor{library/inspect inspect CO_ASYNC_GENERATOR}@anchor{4d38}
@deffn {Δεδομένα} inspect.CO_ASYNC_GENERATOR

The flag is set when the code object is an asynchronous generator
function.  When the code object is executed it returns an
asynchronous generator object.  See 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/} for more details.


Added in version 3.6.

@end deffn

@geindex CO_HAS_DOCSTRING (στη μονάδα inspect)
@anchor{library/inspect inspect CO_HAS_DOCSTRING}@anchor{2588}
@deffn {Δεδομένα} inspect.CO_HAS_DOCSTRING

The flag is set when there is a docstring for the code object in
the source code. If set, it will be the first item in
@ref{1abf,,co_consts}.


Added in version 3.14.

@end deffn

@geindex CO_METHOD (στη μονάδα inspect)
@anchor{library/inspect inspect CO_METHOD}@anchor{4d39}
@deffn {Δεδομένα} inspect.CO_METHOD

The flag is set when the code object is a function defined in class
scope.


Added in version 3.14.

@end deffn

@cartouche
@quotation Σημείωση 
The flags are specific to CPython, and may not be defined in other
Python implementations.  Furthermore, the flags are an implementation
detail, and can be removed or deprecated in future Python releases.
It’s recommended to use public APIs from the @code{inspect} module
for any introspection needs.
@end quotation
@end cartouche

@node Buffer flags,Command-line interface<13>,Code Objects Bit Flags,inspect — Inspect live objects
@anchor{library/inspect buffer-flags}@anchor{4d3a}
@subsubsection Buffer flags


@geindex BufferFlags (κλάση σε inspect)
@anchor{library/inspect inspect BufferFlags}@anchor{87a}
@deffn {Κλάση} inspect.BufferFlags

This is an @ref{105d,,enum.IntFlag} that represents the flags that
can be passed to the @ref{879,,__buffer__()} method of objects
implementing the @ref{311,,buffer protocol}.

The meaning of the flags is explained at @ref{4d3b,,Buffer request types}.

@geindex SIMPLE (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags SIMPLE}@anchor{4d3c}
@deffn {Ιδιότητα} SIMPLE
@end deffn

@geindex WRITABLE (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags WRITABLE}@anchor{4d3d}
@deffn {Ιδιότητα} WRITABLE
@end deffn

@geindex FORMAT (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags FORMAT}@anchor{4d3e}
@deffn {Ιδιότητα} FORMAT
@end deffn

@geindex ND (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags ND}@anchor{4d3f}
@deffn {Ιδιότητα} ND
@end deffn

@geindex STRIDES (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags STRIDES}@anchor{4d40}
@deffn {Ιδιότητα} STRIDES
@end deffn

@geindex C_CONTIGUOUS (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags C_CONTIGUOUS}@anchor{4d41}
@deffn {Ιδιότητα} C_CONTIGUOUS
@end deffn

@geindex F_CONTIGUOUS (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags F_CONTIGUOUS}@anchor{4d42}
@deffn {Ιδιότητα} F_CONTIGUOUS
@end deffn

@geindex ANY_CONTIGUOUS (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags ANY_CONTIGUOUS}@anchor{4d43}
@deffn {Ιδιότητα} ANY_CONTIGUOUS
@end deffn

@geindex INDIRECT (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags INDIRECT}@anchor{4d44}
@deffn {Ιδιότητα} INDIRECT
@end deffn

@geindex CONTIG (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags CONTIG}@anchor{4d45}
@deffn {Ιδιότητα} CONTIG
@end deffn

@geindex CONTIG_RO (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags CONTIG_RO}@anchor{4d46}
@deffn {Ιδιότητα} CONTIG_RO
@end deffn

@geindex STRIDED (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags STRIDED}@anchor{4d47}
@deffn {Ιδιότητα} STRIDED
@end deffn

@geindex STRIDED_RO (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags STRIDED_RO}@anchor{4d48}
@deffn {Ιδιότητα} STRIDED_RO
@end deffn

@geindex RECORDS (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags RECORDS}@anchor{4d49}
@deffn {Ιδιότητα} RECORDS
@end deffn

@geindex RECORDS_RO (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags RECORDS_RO}@anchor{4d4a}
@deffn {Ιδιότητα} RECORDS_RO
@end deffn

@geindex FULL (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags FULL}@anchor{4d4b}
@deffn {Ιδιότητα} FULL
@end deffn

@geindex FULL_RO (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags FULL_RO}@anchor{4d4c}
@deffn {Ιδιότητα} FULL_RO
@end deffn

@geindex READ (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags READ}@anchor{1b14}
@deffn {Ιδιότητα} READ
@end deffn

@geindex WRITE (ιδιότητα της inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags WRITE}@anchor{1b15}
@deffn {Ιδιότητα} WRITE
@end deffn


Added in version 3.12.

@end deffn

@node Command-line interface<13>,,Buffer flags,inspect — Inspect live objects
@anchor{library/inspect command-line-interface}@anchor{4d4d}@anchor{library/inspect inspect-module-cli}@anchor{1305}
@subsubsection Command-line interface


The @code{inspect} module also provides a basic introspection capability
from the command line.

By default, accepts the name of a module and prints the source of that
module. A class or function within the module can be printed instead by
appending a colon and the qualified name of the target object.

@geindex inspect command line option; --details
@anchor{library/inspect cmdoption-inspect-details}@anchor{4d4e}
@deffn {Option} @w{-}@w{-}details

Print information about the specified object rather than the source code
@end deffn


Άλλαξε στην έκδοση 3.15: The @code{--details} option now supports basic introspection for modules
without available source code and indicates when modules are frozen.
It also indicates when the given target reference is not the canonical
name of the referenced object.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node annotationlib — Functionality for introspecting annotations,site — Site-specific configuration hook,inspect — Inspect live objects,Python Runtime Services
@anchor{library/annotationlib doc}@anchor{4d4f}@anchor{library/annotationlib annotationlib-functionality-for-introspecting-annotations}@anchor{4d50}@anchor{library/annotationlib module-annotationlib}@anchor{6}@anchor{library/annotationlib translation-repo}@anchor{4d51}
@subsection @code{annotationlib} — Functionality for introspecting annotations


@geindex module; annotationlib


Added in version 3.14.


`Source code:' Lib/annotationlib.py@footnote{https://github.com/python/cpython/tree/main/Lib/annotationlib.py}

@c import annotationlib
@c from annotationlib import *


__________________________________________________________________


The @code{annotationlib} module provides tools for introspecting
@ref{409,,annotations} on modules, classes, and functions.

Annotations are @ref{872,,lazily evaluated} and often contain
forward references to objects that are not yet defined when the annotation
is created. This module provides a set of low-level tools that can be used to retrieve annotations in a reliable way, even
in the presence of forward references and other edge cases.

This module supports retrieving annotations in three main formats
(see @ref{4be,,Format}), each of which works best for different use cases:


@itemize *

@item 
@ref{40b,,VALUE} evaluates the annotations and returns their value.
This is most straightforward to work with, but it may raise errors,
for example if the annotations contain references to undefined names.

@item 
@ref{40c,,FORWARDREF} returns @ref{1967,,ForwardRef} objects
for annotations that cannot be resolved, allowing you to inspect the
annotations without evaluating them. This is useful when you need to
work with annotations that may contain unresolved forward references.

@item 
@ref{40d,,STRING} returns the annotations as a string, similar
to how it would appear in the source file. This is useful for documentation
generators that want to display annotations in a readable way.
@end itemize

The @ref{66c,,get_annotations()} function is the main entry point for
retrieving annotations. Given a function, class, or module, it returns
an annotations dictionary in the requested format. This module also provides
functionality for working directly with the @ref{40a,,annotate function}
that is used to evaluate annotations, such as @ref{66e,,get_annotate_from_class_namespace()}
and @ref{19cf,,call_annotate_function()}, as well as the
@ref{473d,,call_evaluate_function()} function for working with
@ref{473c,,evaluate functions}.

@cartouche
@quotation Προσοχή 
Most functionality in this module can execute arbitrary code; see
@ref{476f,,the security section} for more information.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/} proposed the current model for how annotations work in Python.

@geindex Python Enhancement Proposals; PEP 749
PEP 749@footnote{https://peps.python.org/pep-0749/} expanded on various aspects of 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/} and introduced the
@code{annotationlib} module.

@ref{bb6,,Annotations Best Practices} provides best practices for working with
annotations.

typing-extensions@footnote{https://pypi.org/project/typing-extensions/} provides a backport of @ref{66c,,get_annotations()}
that works on earlier versions of Python.


@menu
* Annotation semantics:: 
* Classes: Classes<2>. 
* Functions: Functions<10>. 
* Recipes: Recipes<2>. 
* Limitations of the STRING format:: 
* Limitations of the FORWARDREF format:: 
* Security implications of introspecting annotations:: 

@end menu

@node Annotation semantics,Classes<2>,,annotationlib — Functionality for introspecting annotations
@anchor{library/annotationlib annotation-semantics}@anchor{4d52}
@subsubsection Annotation semantics


The way annotations are evaluated has changed over the history of Python 3,
and currently still depends on a @ref{670,,future import}.
There have been execution models for annotations:


@itemize *

@item 
`Stock semantics' (default in Python 3.0 through 3.13; see 
@geindex Python Enhancement Proposals; PEP 3107
PEP 3107@footnote{https://peps.python.org/pep-3107/}
and 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}): Annotations are evaluated eagerly, as they are
encountered in the source code.

@item 
`Stringified annotations' (used with @code{from __future__ import annotations}
in Python 3.7 and newer; see 
@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/}): Annotations are stored as
strings only.

@item 
`Deferred evaluation' (default in Python 3.14 and newer; see 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/} and
@geindex Python Enhancement Proposals; PEP 749
PEP 749@footnote{https://peps.python.org/pep-0749/}): Annotations are evaluated lazily, only when they are accessed.
@end itemize

As an example, consider the following program:

@example
def func(a: Cls) -> None:
    print(a)

class Cls: pass

print(func.__annotations__)
@end example

This will behave as follows:


@itemize *

@item 
Under stock semantics (Python 3.13 and earlier), it will throw a
@ref{665,,NameError} at the line where @code{func} is defined,
because @code{Cls} is an undefined name at that point.

@item 
Under stringified annotations (if @code{from __future__ import annotations}
is used), it will print @code{@{'a': 'Cls', 'return': 'None'@}}.

@item 
Under deferred evaluation (Python 3.14 and later), it will print
@code{@{'a': <class 'Cls'>, 'return': None@}}.
@end itemize

Stock semantics were used when function annotations were first introduced
in Python 3.0 (by 
@geindex Python Enhancement Proposals; PEP 3107
PEP 3107@footnote{https://peps.python.org/pep-3107/}) because this was the simplest, most obvious
way to implement annotations. The same execution model was used when variable
annotations were introduced in Python 3.6 (by 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}). However,
stock semantics caused problems when using annotations as type hints,
such as a need to refer to names that are not yet defined when the
annotation is encountered. In addition, there were performance problems
with executing annotations at module import time. Therefore, in Python 3.7,
@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/} introduced the ability to store annotations as strings using the
@code{from __future__ import annotations} syntax. The plan at the time was to
eventually make this behavior the default, but a problem appeared:
stringified annotations are more difficult to process for those who
introspect annotations at runtime. An alternative proposal, 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/},
introduced the third execution model, deferred evaluation, and was implemented
in Python 3.14. Stringified annotations are still used if
@code{from __future__ import annotations} is present, but this behavior will
eventually be removed.

@node Classes<2>,Functions<10>,Annotation semantics,annotationlib — Functionality for introspecting annotations
@anchor{library/annotationlib classes}@anchor{4d53}
@subsubsection Classes


@geindex Format (κλάση σε annotationlib)
@anchor{library/annotationlib annotationlib Format}@anchor{4be}
@deffn {Κλάση} annotationlib.Format

An @ref{109d,,IntEnum} describing the formats in which annotations
can be returned. Members of the enum, or their equivalent integer values,
can be passed to @ref{66c,,get_annotations()} and other functions in this
module, as well as to @ref{1b95,,__annotate__} functions.

@geindex VALUE (ιδιότητα της annotationlib.Format)
@anchor{library/annotationlib annotationlib Format VALUE}@anchor{40b}
@deffn {Ιδιότητα} VALUE = 1

Values are the result of evaluating the annotation expressions.
@end deffn

@geindex VALUE_WITH_FAKE_GLOBALS (ιδιότητα της annotationlib.Format)
@anchor{library/annotationlib annotationlib Format VALUE_WITH_FAKE_GLOBALS}@anchor{4d54}
@deffn {Ιδιότητα} VALUE_WITH_FAKE_GLOBALS = 2

Special value used to signal that an annotate function is being
evaluated in a special environment with fake globals. When passed this
value, annotate functions should either return the same value as for
the @ref{40b,,Format.VALUE} format, or raise @ref{59a,,NotImplementedError}
to signal that they do not support execution in this environment.
This format is only used internally and should not be passed to
the functions in this module.
@end deffn

@geindex FORWARDREF (ιδιότητα της annotationlib.Format)
@anchor{library/annotationlib annotationlib Format FORWARDREF}@anchor{40c}
@deffn {Ιδιότητα} FORWARDREF = 3

Values are real annotation values (as per @ref{40b,,Format.VALUE} format)
for defined values, and @ref{1967,,ForwardRef} proxies for undefined
values. Real objects may contain references to @code{ForwardRef}
proxy objects.
@end deffn

@geindex STRING (ιδιότητα της annotationlib.Format)
@anchor{library/annotationlib annotationlib Format STRING}@anchor{40d}
@deffn {Ιδιότητα} STRING = 4

Values are the text string of the annotation as it appears in the
source code, up to modifications including, but not restricted to,
whitespace normalizations and constant values optimizations.

The exact values of these strings may change in future versions of Python.
@end deffn


Added in version 3.14.

@end deffn

@geindex ForwardRef (κλάση σε annotationlib)
@anchor{library/annotationlib annotationlib ForwardRef}@anchor{1967}
@deffn {Κλάση} annotationlib.ForwardRef

A proxy object for forward references in annotations.

Instances of this class are returned when the @ref{40c,,FORWARDREF}
format is used and annotations contain a name that cannot be resolved.
This can happen when a forward reference is used in an annotation, such as
when a class is referenced before it is defined.

@geindex __forward_arg__ (ιδιότητα της annotationlib.ForwardRef)
@anchor{library/annotationlib annotationlib ForwardRef __forward_arg__}@anchor{4d55}
@deffn {Ιδιότητα} __forward_arg__

A string containing the code that was evaluated to produce the
@code{ForwardRef}. The string may not be exactly equivalent
to the original source.
@end deffn

@geindex evaluate() (μέθοδος της annotationlib.ForwardRef)
@anchor{library/annotationlib annotationlib ForwardRef evaluate}@anchor{150}
@deffn {Μέθοδος} evaluate (*, owner=None, globals=None, locals=None, type_params=None, format=Format.VALUE)

Evaluate the forward reference, returning its value.

If the `format' argument is @ref{40b,,VALUE} (the default),
this method may throw an exception, such as @ref{665,,NameError}, if the forward
reference refers to a name that cannot be resolved. The arguments to this
method can be used to provide bindings for names that would otherwise
be undefined. If the `format' argument is @ref{40c,,FORWARDREF},
the method will never throw an exception, but may return a @code{ForwardRef}
instance. For example, if the forward reference object contains the code
@code{list[undefined]}, where @code{undefined} is a name that is not defined,
evaluating it with the @code{FORWARDREF} format will return
@code{list[ForwardRef('undefined')]}. If the `format' argument is
@ref{40d,,STRING}, the method will return @ref{4d55,,__forward_arg__}.

The `owner' parameter provides the preferred mechanism for passing scope
information to this method. The owner of a @code{ForwardRef} is the
object that contains the annotation from which the @code{ForwardRef}
derives, such as a module object, type object, or function object.

The `globals', `locals', and `type_params' parameters provide a more precise
mechanism for influencing the names that are available when the @code{ForwardRef}
is evaluated. `globals' and `locals' are passed to @ref{184,,eval()}, representing
the global and local namespaces in which the name is evaluated.
The `type_params' parameter is relevant for objects created using the native
syntax for @ref{86e,,generic classes} and @ref{86f,,functions}.
It is a tuple of @ref{7a5,,type parameters} that are in scope
while the forward reference is being evaluated. For example, if evaluating a
@code{ForwardRef} retrieved from an annotation found in the class namespace
of a generic class @code{C}, `type_params' should be set to @code{C.__type_params__}.

@code{ForwardRef} instances returned by @ref{66c,,get_annotations()}
retain references to information about the scope they originated from,
so calling this method with no further arguments may be sufficient to
evaluate such objects. @code{ForwardRef} instances created by other
means may not have any information about their scope, so passing
arguments to this method may be necessary to evaluate them successfully.

If no `owner', `globals', `locals', or `type_params' are provided and the
@code{ForwardRef} does not contain information about its origin,
empty globals and locals dictionaries are used.
@end deffn


Added in version 3.14.

@end deffn

@node Functions<10>,Recipes<2>,Classes<2>,annotationlib — Functionality for introspecting annotations
@anchor{library/annotationlib functions}@anchor{4d56}
@subsubsection Functions


@geindex annotations_to_string() (στη μονάδα annotationlib)
@anchor{library/annotationlib annotationlib annotations_to_string}@anchor{4d57}
@deffn {Συνάρτηση} annotationlib.annotations_to_string (annotations)

Convert an annotations dict containing runtime values to a
dict containing only strings. If the values are not already strings,
they are converted using @ref{1a7e,,type_repr()}.
This is meant as a helper for user-provided
annotate functions that support the @ref{40d,,STRING} format but
do not have access to the code creating the annotations.

For example, this is used to implement the @ref{40d,,STRING} for
@ref{290,,typing.TypedDict} classes created through the functional syntax:

@example
>>> from typing import TypedDict
>>> Movie = TypedDict("movie", @{"name": str, "year": int@})
>>> get_annotations(Movie, format=Format.STRING)
@{'name': 'str', 'year': 'int'@}
@end example


Added in version 3.14.

@end deffn

@geindex call_annotate_function() (στη μονάδα annotationlib)
@anchor{library/annotationlib annotationlib call_annotate_function}@anchor{19cf}
@deffn {Συνάρτηση} annotationlib.call_annotate_function (annotate, format, *, owner=None)

Call the @ref{40a,,annotate function} `annotate' with the given `format',
a member of the @ref{4be,,Format} enum, and return the annotations
dictionary produced by the function.

This helper function is required because annotate functions generated by
the compiler for functions, classes, and modules only support
the @ref{40b,,VALUE} format when called directly.
To support other formats, this function calls the annotate function
in a special environment that allows it to produce annotations in the
other formats. This is a useful building block when implementing
functionality that needs to partially evaluate annotations while a class
is being constructed.

`owner' is the object that owns the annotation function, usually
a function, class, or module. If provided, it is used in the
@ref{40c,,FORWARDREF} format to produce a @ref{1967,,ForwardRef}
object that carries more information.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 649#the-stringizer-and-the-fake-globals-environment
PEP 649@footnote{https://peps.python.org/pep-0649/#the-stringizer-and-the-fake-globals-environment}
contains an explanation of the implementation technique used by this
function.



Added in version 3.14.

@end deffn

@geindex call_evaluate_function() (στη μονάδα annotationlib)
@anchor{library/annotationlib annotationlib call_evaluate_function}@anchor{473d}
@deffn {Συνάρτηση} annotationlib.call_evaluate_function (evaluate, format, *, owner=None)

Call the @ref{473c,,evaluate function} `evaluate' with the given `format',
a member of the @ref{4be,,Format} enum, and return the value produced by
the function. This is similar to @ref{19cf,,call_annotate_function()},
but the latter always returns a dictionary mapping strings to annotations,
while this function returns a single value.

This is intended for use with the evaluate functions generated for lazily
evaluated elements related to type aliases and type parameters:


@itemize *

@item 
@ref{4759,,typing.TypeAliasType.evaluate_value()}, the value of type aliases

@item 
@ref{473b,,typing.TypeVar.evaluate_bound()}, the bound of type variables

@item 
@ref{473f,,typing.TypeVar.evaluate_constraints()}, the constraints of
type variables

@item 
@ref{4741,,typing.TypeVar.evaluate_default()}, the default value of
type variables

@item 
@ref{4752,,typing.ParamSpec.evaluate_default()}, the default value of
parameter specifications

@item 
@ref{4748,,typing.TypeVarTuple.evaluate_default()}, the default value of
type variable tuples
@end itemize

`owner' is the object that owns the evaluate function, such as the type
alias or type variable object.

`format' can be used to control the format in which the value is returned:

@example
>>> type Alias = undefined
>>> call_evaluate_function(Alias.evaluate_value, Format.VALUE)
Traceback (most recent call last):
...
NameError: name 'undefined' is not defined
>>> call_evaluate_function(Alias.evaluate_value, Format.FORWARDREF)
ForwardRef('undefined')
>>> call_evaluate_function(Alias.evaluate_value, Format.STRING)
'undefined'
@end example


Added in version 3.14.

@end deffn

@geindex get_annotate_from_class_namespace() (στη μονάδα annotationlib)
@anchor{library/annotationlib annotationlib get_annotate_from_class_namespace}@anchor{66e}
@deffn {Συνάρτηση} annotationlib.get_annotate_from_class_namespace (namespace)

Retrieve the @ref{40a,,annotate function} from a class namespace dictionary `namespace'.
Return @code{None} if the namespace does not contain an annotate function.
This is primarily useful before the class has been fully created (e.g., in a metaclass);
after the class exists, the annotate function can be retrieved with @code{cls.__annotate__}.
See @ref{4d58,,below} for an example using this function in a metaclass.


Added in version 3.14.

@end deffn

@geindex get_annotations() (στη μονάδα annotationlib)
@anchor{library/annotationlib annotationlib get_annotations}@anchor{66c}
@deffn {Συνάρτηση} annotationlib.get_annotations (obj, *, globals=None, locals=None, eval_str=False, format=Format.VALUE)

Compute the annotations dict for an object.

`obj' may be a callable, class, module, or other object with
@ref{1b95,,__annotate__} or @ref{66b,,__annotations__} attributes.
Passing any other object raises @ref{291,,TypeError}.

The `format' parameter controls the format in which annotations are returned,
and must be a member of the @ref{4be,,Format} enum or its integer equivalent.
The different formats work as follows:


@itemize *

@item 
VALUE: @code{object.__annotations__} is tried first; if that does not exist,
the @code{object.__annotate__} function is called if it exists.

@item 
FORWARDREF: If @code{object.__annotations__} exists and can be evaluated successfully,
it is used; otherwise, the @code{object.__annotate__} function is called. If it
does not exist either, @code{object.__annotations__} is tried again and any error
from accessing it is re-raised.


@itemize *

@item 
When calling @code{object.__annotate__} it is first called with @ref{40c,,FORWARDREF}.
If this is not implemented, it will then check if @ref{4d54,,VALUE_WITH_FAKE_GLOBALS}
is supported and use that in the fake globals environment.
If neither of these formats are supported, it will fall back to using @ref{40b,,VALUE}.
If @code{VALUE} fails, the error from this call will be raised.
@end itemize

@item 
STRING: If @code{object.__annotate__} exists, it is called first;
otherwise, @code{object.__annotations__} is used and stringified
using @ref{4d57,,annotations_to_string()}.


@itemize *

@item 
When calling @code{object.__annotate__} it is first called with @ref{40d,,STRING}.
If this is not implemented, it will then check if @ref{4d54,,VALUE_WITH_FAKE_GLOBALS}
is supported and use that in the fake globals environment.
If neither of these formats are supported, it will fall back to using @ref{40b,,VALUE}
with the result converted using @ref{4d57,,annotations_to_string()}.
If @code{VALUE} fails, the error from this call will be raised.
@end itemize
@end itemize

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 `eval_str' is true, values of type @code{str} will
be un-stringized using @ref{184,,eval()}. This is intended
for use with stringized annotations
(@code{from __future__ import annotations}). It is an error
to set `eval_str' to true with formats other than @ref{40b,,Format.VALUE}.

@item 
If `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, as well as annotations
on metaclasses. 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.
@end itemize

`eval_str' controls whether or not values of type @code{str} are
replaced with the result of calling @ref{184,,eval()} on those values:


@itemize *

@item 
If eval_str is true, @ref{184,,eval()} is called on values of type
@code{str}. (Note that @code{get_annotations()} doesn’t catch
exceptions; if @code{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

`globals' and `locals' are passed in to @ref{184,,eval()}; see the documentation
for @code{eval()} for more information. If `globals' or `locals'
is @code{None}, this function may replace that value with a
context-specific default, contingent on @code{type(obj)}:


@itemize *

@item 
If `obj' is a module, `globals' defaults to @code{obj.__dict__}.

@item 
If `obj' is a class, `globals' defaults to
@code{sys.modules[obj.__module__].__dict__} and `locals' defaults
to the `obj' class namespace.

@item 
If `obj' is a callable, `globals' defaults to
@ref{1678,,obj.__globals__},
although if `obj' is a wrapped function (using
@ref{13cb,,functools.update_wrapper()}) or a @ref{4a6,,functools.partial} object,
it is unwrapped until a non-wrapped function is found.
@end itemize

Calling @code{get_annotations()} is best practice for accessing the
annotations dict of any object. See @ref{bb6,,Annotations Best Practices} for
more information on annotations best practices.

@example
>>> def f(a: int, b: str) -> float:
...     pass
>>> get_annotations(f)
@{'a': <class 'int'>, 'b': <class 'str'>, 'return': <class 'float'>@}
@end example


Added in version 3.14.

@end deffn

@geindex type_repr() (στη μονάδα annotationlib)
@anchor{library/annotationlib annotationlib type_repr}@anchor{1a7e}
@deffn {Συνάρτηση} annotationlib.type_repr (value)

Convert an arbitrary Python value to a format suitable for use by the
@ref{40d,,STRING} format. This calls @ref{45b,,repr()} for most
objects, but has special handling for some objects, such as type objects.

This is meant as a helper for user-provided
annotate functions that support the @ref{40d,,STRING} format but
do not have access to the code creating the annotations. It can also
be used to provide a user-friendly string representation for other
objects that contain values that are commonly encountered in annotations.


Added in version 3.14.

@end deffn

@node Recipes<2>,Limitations of the STRING format,Functions<10>,annotationlib — Functionality for introspecting annotations
@anchor{library/annotationlib recipes}@anchor{4d59}
@subsubsection Recipes


@menu
* Using annotations in a metaclass:: 
* Creating a custom callable annotate function:: 

@end menu

@node Using annotations in a metaclass,Creating a custom callable annotate function,,Recipes<2>
@anchor{library/annotationlib annotationlib-metaclass}@anchor{4d58}@anchor{library/annotationlib using-annotations-in-a-metaclass}@anchor{4d5a}
@subsubsection Using annotations in a metaclass


A @ref{25b3,,metaclass} may want to inspect or even modify the annotations
in a class body during class creation. Doing so requires retrieving annotations
from the class namespace dictionary. For classes created with
@code{from __future__ import annotations}, the annotations will be in the @code{__annotations__}
key of the dictionary. For other classes with annotations,
@ref{66e,,get_annotate_from_class_namespace()} can be used to get the
annotate function, and @ref{19cf,,call_annotate_function()} can be used to call it and
retrieve the annotations. Using the @ref{40c,,FORWARDREF} format will usually
be best, because this allows the annotations to refer to names that cannot yet be
resolved when the class is created.

To modify the annotations, it is best to create a wrapper annotate function
that calls the original annotate function, makes any necessary adjustments, and
returns the result.

Below is an example of a metaclass that filters out all @ref{76e,,typing.ClassVar}
annotations from the class and puts them in a separate attribute:

@example
import annotationlib
import typing

class ClassVarSeparator(type):
   def __new__(mcls, name, bases, ns):
      if "__annotations__" in ns:  # from __future__ import annotations
         annotations = ns["__annotations__"]
         classvar_keys = @{
            key for key, value in annotations.items()
            # Use string comparison for simplicity; a more robust solution
            # could use annotationlib.ForwardRef.evaluate
            if value.startswith("ClassVar")
         @}
         classvars = @{key: annotations[key] for key in classvar_keys@}
         ns["__annotations__"] = @{
            key: value for key, value in annotations.items()
            if key not in classvar_keys
         @}
         wrapped_annotate = None
      elif annotate := annotationlib.get_annotate_from_class_namespace(ns):
         annotations = annotationlib.call_annotate_function(
            annotate, format=annotationlib.Format.FORWARDREF
         )
         classvar_keys = @{
            key for key, value in annotations.items()
            if typing.get_origin(value) is typing.ClassVar
         @}
         classvars = @{key: annotations[key] for key in classvar_keys@}

         def wrapped_annotate(format):
            annos = annotationlib.call_annotate_function(annotate, format, owner=typ)
            return @{key: value for key, value in annos.items() if key not in classvar_keys@}

      else:  # no annotations
         classvars = @{@}
         wrapped_annotate = None
      typ = super().__new__(mcls, name, bases, ns)

      if wrapped_annotate is not None:
         # Wrap the original __annotate__ with a wrapper that removes ClassVars
         typ.__annotate__ = wrapped_annotate
      typ.classvars = classvars  # Store the ClassVars in a separate attribute
      return typ
@end example

@node Creating a custom callable annotate function,,Using annotations in a metaclass,Recipes<2>
@anchor{library/annotationlib creating-a-custom-callable-annotate-function}@anchor{4d5b}
@subsubsection Creating a custom callable annotate function


Custom @ref{40a,,annotate functions} may be literal functions like those
automatically generated for functions, classes, and modules. Or, they may wish to utilise
the encapsulation provided by classes, in which case any @ref{2fa4,,callable} can be used as
an annotate function.

To provide the @ref{40b,,VALUE}, @ref{40d,,STRING}, or
@ref{40c,,FORWARDREF} formats directly, an @ref{40a,,annotate function} must provide
the following attribute:


@itemize *

@item 
A callable @code{__call__} with signature @code{__call__(format, /) -> dict}, that does not
raise a @ref{59a,,NotImplementedError} when called with a supported format.
@end itemize

To provide the @ref{4d54,,VALUE_WITH_FAKE_GLOBALS} format, which is used to
automatically generate @ref{40d,,STRING} or @ref{40c,,FORWARDREF} if they are
not supported directly, @ref{40a,,annotate functions} must provide the
following attributes:


@itemize *

@item 
A callable @code{__call__} with signature @code{__call__(format, /) -> dict}, that does not
raise a @ref{59a,,NotImplementedError} when called with
@ref{4d54,,VALUE_WITH_FAKE_GLOBALS}.

@item 
A @ref{6eb,,code object} @code{__code__} containing the compiled code for the
annotate function.

@item 
Optional: A tuple of the function’s positional defaults @code{__kwdefaults__}, if the
function represented by @code{__code__} uses any positional defaults.

@item 
Optional: A dict of the function’s keyword defaults @code{__defaults__}, if the function
represented by @code{__code__} uses any keyword defaults.

@item 
Optional: All other @ref{1f83,,function attributes}.
@end itemize

@example
class Annotate:
    called_formats = []

    def __call__(self, format=None, /, *, _self=None):
        # When called with fake globals, `_self` will be the
        # actual self value, and `self` will be the format.
        if _self is not None:
            self, format = _self, self

        self.called_formats.append(format)
        if format <= 2:  # VALUE or VALUE_WITH_FAKE_GLOBALS
            return @{"x": MyType@}
        raise NotImplementedError

    __code__ = __call__.__code__
    __defaults__ = (None,)
    __kwdefaults__ = property(lambda self: dict(_self=self))

    __globals__ = @{@}
    __builtins__ = @{@}
    __closure__ = None
@end example

This can then be called with:

@example
>>> from annotationlib import call_annotate_function, Format
>>> call_annotate_function(Annotate(), format=Format.STRING)
@{'x': 'MyType'@}
@end example

Or used as the annotate function for an object:

@example
>>> from annotationlib import get_annotations, Format
>>> class C:
...   pass
>>> C.__annotate__ = Annotate()
>>> get_annotations(Annotate(), format=Format.STRING)
@{'x': 'MyType'@}
@end example

@node Limitations of the STRING format,Limitations of the FORWARDREF format,Recipes<2>,annotationlib — Functionality for introspecting annotations
@anchor{library/annotationlib limitations-of-the-string-format}@anchor{4d5c}
@subsubsection Limitations of the @code{STRING} format


The @ref{40d,,STRING} format is meant to approximate the source code
of the annotation, but the implementation strategy used means that it is not
always possible to recover the exact source code.

First, the stringifier of course cannot recover any information that is not present in
the compiled code, including comments, whitespace, parenthesization, and operations that
get simplified by the compiler.

Second, the stringifier can intercept almost all operations that involve names looked
up in some scope, but it cannot intercept operations that operate fully on constants.
As a corollary, this also means it is not safe to request the @code{STRING} format on
untrusted code: Python is powerful enough that it is possible to achieve arbitrary
code execution even with no access to any globals or builtins. For example:

@example
>>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__.__builtins__["print"]("Hello world")): pass
...
>>> annotationlib.get_annotations(f, format=annotationlib.Format.STRING)
Hello world
@{'x': 'None'@}
@end example

@cartouche
@quotation Σημείωση 
This particular example works as of the time of writing, but it relies on
implementation details and is not guaranteed to work in the future.
@end quotation
@end cartouche

Among the different kinds of expressions that exist in Python,
as represented by the @ref{9,,ast} module, some expressions are supported,
meaning that the @code{STRING} format can generally recover the original source code;
others are unsupported, meaning that they may result in incorrect output or an error.

The following are supported (sometimes with caveats):


@itemize *

@item 
@ref{1fa2,,ast.BinOp}

@item 
@ref{4d5d,,ast.UnaryOp}


@itemize *

@item 
@ref{4d5e,,ast.Invert} (@code{~}), @ref{4d5f,,ast.UAdd} (@code{+}), and @ref{4d60,,ast.USub} (@code{-}) are supported

@item 
@ref{4d61,,ast.Not} (@code{not}) is not supported
@end itemize

@item 
@ref{1f3d,,ast.Dict} (except when using @code{**} unpacking)

@item 
@ref{4d62,,ast.Set}

@item 
@ref{4d63,,ast.Compare}


@itemize *

@item 
@ref{4d64,,ast.Eq} and @ref{4d65,,ast.NotEq} are supported

@item 
@ref{4d66,,ast.Lt}, @ref{4d67,,ast.LtE}, @ref{4d68,,ast.Gt}, and @ref{4d69,,ast.GtE} are supported, but the operand may be flipped

@item 
@ref{4d6a,,ast.Is}, @ref{4d6b,,ast.IsNot}, @ref{4d6c,,ast.In}, and @ref{4d6d,,ast.NotIn} are not supported
@end itemize

@item 
@ref{4d6e,,ast.Call} (except when using @code{**} unpacking)

@item 
@ref{569,,ast.Constant} (though not the exact representation of the constant; for example, escape
sequences in strings are lost; hexadecimal numbers are converted to decimal)

@item 
@ref{4d6f,,ast.Attribute} (assuming the value is not a constant)

@item 
@ref{4d70,,ast.Subscript} (assuming the value is not a constant)

@item 
@ref{4d71,,ast.Starred} (@code{*} unpacking)

@item 
@ref{1f17,,ast.Name}

@item 
@ref{4d72,,ast.List}

@item 
@ref{4d73,,ast.Tuple}

@item 
@ref{4d74,,ast.Slice}
@end itemize

The following are unsupported, but throw an informative error when encountered by the
stringifier:


@itemize *

@item 
@ref{4d75,,ast.FormattedValue} (f-strings; error is not detected if conversion specifiers like @code{!r}
are used)

@item 
@ref{1c62,,ast.JoinedStr} (f-strings)
@end itemize

The following are unsupported and result in incorrect output:


@itemize *

@item 
@ref{4d76,,ast.BoolOp} (@code{and} and @code{or})

@item 
@ref{4d77,,ast.IfExp}

@item 
@ref{4d78,,ast.Lambda}

@item 
@ref{4d79,,ast.ListComp}

@item 
@ref{4d7a,,ast.SetComp}

@item 
@ref{4d7b,,ast.DictComp}

@item 
@ref{4d7c,,ast.GeneratorExp}
@end itemize

The following are disallowed in annotation scopes and therefore not relevant:


@itemize *

@item 
@ref{4d7d,,ast.NamedExpr} (@code{:=})

@item 
@ref{4d7e,,ast.Await}

@item 
@ref{4d7f,,ast.Yield}

@item 
@ref{4d80,,ast.YieldFrom}
@end itemize

@node Limitations of the FORWARDREF format,Security implications of introspecting annotations,Limitations of the STRING format,annotationlib — Functionality for introspecting annotations
@anchor{library/annotationlib limitations-of-the-forwardref-format}@anchor{4d81}
@subsubsection Limitations of the @code{FORWARDREF} format


The @ref{40c,,FORWARDREF} format aims to produce real values as much
as possible, with anything that cannot be resolved replaced with
@ref{1967,,ForwardRef} objects. It is affected by broadly the same Limitations
as the @ref{40d,,STRING} format: annotations that perform operations on
literals or that use unsupported expression types may raise exceptions when
evaluated using the @code{FORWARDREF} format.

Below are a few examples of the behavior with unsupported expressions:

@example
>>> from annotationlib import get_annotations, Format
>>> def zerodiv(x: 1 / 0): ...
>>> get_annotations(zerodiv, format=Format.STRING)
Traceback (most recent call last):
  ...
ZeroDivisionError: division by zero
>>> get_annotations(zerodiv, format=Format.FORWARDREF)
Traceback (most recent call last):
  ...
ZeroDivisionError: division by zero
>>> def ifexp(x: 1 if y else 0): ...
>>> get_annotations(ifexp, format=Format.STRING)
@{'x': '1'@}
@end example

@node Security implications of introspecting annotations,,Limitations of the FORWARDREF format,annotationlib — Functionality for introspecting annotations
@anchor{library/annotationlib annotationlib-security}@anchor{476f}@anchor{library/annotationlib security-implications-of-introspecting-annotations}@anchor{4d82}
@subsubsection Security implications of introspecting annotations


Much of the functionality in this module involves executing code related to annotations,
which can then do arbitrary things. For example,
@ref{66c,,get_annotations()} may call an arbitrary @ref{40a,,annotate function}, and
@ref{150,,ForwardRef.evaluate()} may call @ref{184,,eval()} on an arbitrary string. Code contained
in an annotation might make arbitrary system calls, enter an infinite loop, or perform any
other operation. This is also true for any access of the @ref{66b,,__annotations__} attribute,
and for various functions in the @ref{10d,,typing} module that work with annotations, such as
@ref{a9e,,typing.get_type_hints()}.

Any security issue arising from this also applies immediately after importing
code that may contain untrusted annotations: importing code can always cause arbitrary operations
to be performed. However, it is unsafe to accept strings or other input from an untrusted source and
pass them to any of the APIs for introspecting annotations, for example by editing an
@code{__annotations__} dictionary or directly creating a @ref{1967,,ForwardRef} object.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node site — Site-specific configuration hook,,annotationlib — Functionality for introspecting annotations,Python Runtime Services
@anchor{library/site doc}@anchor{4d83}@anchor{library/site module-site}@anchor{cf}@anchor{library/site site-site-specific-configuration-hook}@anchor{4d84}@anchor{library/site translation-repo}@anchor{4d85}
@subsection @code{site} — Site-specific configuration hook


@geindex module; site

`Source code:' Lib/site.py@footnote{https://github.com/python/cpython/tree/main/Lib/site.py}


__________________________________________________________________


`This module is automatically imported during initialization.' The automatic
import can be suppressed using the interpreter’s @ref{1551,,-S} option.

@geindex module;search;path

Importing this module normally appends site-specific paths to the module search path
and adds @ref{27df,,callables}, including @ref{ca9,,help()} to the built-in
namespace. However, Python startup option @ref{1551,,-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{2316,,main()} function.


Άλλαξε στην έκδοση 3.3: Importing the module used to trigger paths manipulation even when using
@ref{1551,,-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{198,,free-threaded build}, and is
appended if @code{"t"} is present in the @ref{e28,,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.


Άλλαξε στην έκδοση 3.5: Support for the «site-python» directory has been removed.



Άλλαξε στην έκδοση 3.13: On Unix, @ref{487,,Free threading} Python installations are
identified by the «t» suffix in the version-specific directory name, such as
@code{lib/python3.13t/}.



Άλλαξε στην έκδοση 3.14: @code{site} is no longer responsible for updating @ref{3ab,,sys.prefix} and
@ref{3a8,,sys.exec_prefix} on @ref{4b93,,Virtual Environments}. This is
now done during the @ref{1953,,path initialization}. As a result,
under @ref{4b93,,Virtual Environments}, @code{sys.prefix} and
@code{sys.exec_prefix} no longer depend on the @code{site} initialization,
and are therefore unaffected by @ref{1551,,-S}.

@anchor{library/site site-virtual-environments-configuration}@anchor{4b94}
When running under a @ref{4b93,,virtual environment},
the @code{pyvenv.cfg} file in @ref{3ab,,sys.prefix} is checked for site-specific
configurations. If the @code{include-system-site-packages} key exists and is set to
@code{true} (case-insensitive), the system-level prefixes will be searched for
site-packages, otherwise they won’t.  If the system-level prefixes are not searched then
the user site prefixes are also implicitly not searched for site-packages.

@geindex # (hash);comment
@geindex statement;import

The @code{site} module recognizes two startup configuration files of the form
@code{`name'.pth} for path configurations, and @code{`name'.start} for
pre-first-line code execution.  Both files can exist in one of the four
directories mentioned above.  Within each directory, these files are sorted
alphabetically by filename, then parsed in sorted order.

@menu
* Path extensions (.pth files): Path extensions pth files. 
* Startup entry points (.start files): Startup entry points start files. 
* Startup file examples:: 
* Migrating from import lines in .pth files to .start files: Migrating from import lines in pth files to start files. 
* sitecustomize:: 
* usercustomize:: 
* Readline configuration:: 
* Module contents: Module contents<7>. 
* Command-line interface: Command-line interface<14>. 

@end menu

@node Path extensions pth files,Startup entry points start files,,site — Site-specific configuration hook
@anchor{library/site path-extensions-pth-files}@anchor{4d86}@anchor{library/site site-pth-files}@anchor{193}
@subsubsection Path extensions (@code{.pth} files)


@code{`name'.pth} contains additional items (one per line) to be appended to
@code{sys.path}.  Items that name non-existing directories 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.

For backward compatibility, lines starting with @code{import} (followed by space
or tab) are executed with @ref{185,,exec()}.


Άλλαξε στην έκδοση 3.13: The @code{.pth} files are now decoded by UTF-8 at first and then by the
@ref{74d,,locale encoding} if it fails.



Άλλαξε στην έκδοση 3.15: @code{.pth} file lines starting with @code{import} are deprecated.  During
the deprecation period, such lines are still executed (except in the case
below), but a diagnostic message is emitted only when the @ref{17c7,,-v} flag
is given.

@code{import} lines in @code{`name'.pth} are silently ignored when a
@ref{195,,matching} @code{`name'.start} file exists.

Errors on individual lines no longer abort processing of the rest of the
file.  Each error is reported and the remaining lines continue to be
processed.



Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.20: Decoding @code{`name'.pth} files in any encoding other than @code{utf-8-sig}
is deprecated in Python 3.15, and support for decoding from the locale
encoding will be removed in Python 3.20.

@code{import} lines in @code{`name'.pth} files are deprecated and will be
silently ignored in Python 3.18 and 3.19.  In Python 3.20 a warning will be
produced for @code{import} lines in @code{`name'.pth} files.


@node Startup entry points start files,Startup file examples,Path extensions pth files,site — Site-specific configuration hook
@anchor{library/site site-start-files}@anchor{195}@anchor{library/site startup-entry-points-start-files}@anchor{4d87}
@subsubsection Startup entry points (@code{.start} files)



Added in version 3.15.


A startup entry point file is a file whose name has the form
@code{`name'.start} and exists in one of the site-packages directories
described above.  Each file specifies entry points to be called during
interpreter startup, using the @code{pkg.mod:callable} syntax understood by
@ref{1904,,pkgutil.resolve_name()}.

Each non-blank line that does not begin with @code{#} must contain an entry
point reference in the form @code{pkg.mod:callable}.  The colon and callable
portion are mandatory.  Each callable is invoked with no arguments, and
any return value is discarded.

@code{.start} files are processed after all @code{.pth} path extensions
have been applied to @ref{194,,sys.path}, ensuring that paths are available
before any startup code runs.

Unlike @ref{194,,sys.path} extensions from @code{.pth} files, duplicate entry
points are `not' de-duplicated — if an entry point appears more than once,
it will be called more than once.

If an exception occurs during resolution or invocation of an entry point,
a traceback is printed to @ref{d05,,sys.stderr} and processing continues with
the remaining entry points.

@code{.start} files must be encoded in UTF-8.

@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/} defined the original specification for these features.

@cartouche
@quotation Σημείωση 
If a @code{`name'.start} file exists alongside a @code{`name'.pth} file
with the same base name, any @code{import} lines in the @code{.pth} file are
ignored in favor of the entry points in the @code{.start} file.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Executable lines (@code{import} lines in @code{`name'.pth} files and
@code{`name'.start} file entry points) are always run at Python startup
(unless @ref{1551,,-S} is given to disable the @code{site.py} module entirely),
regardless of whether a particular module is actually going to be used.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
@code{`name'.start} files invoke @ref{1904,,pkgutil.resolve_name()} with
@code{strict=True}, which requires the full @code{pkg.mod:callable} form.
@end quotation
@end cartouche

@geindex package
@geindex path;configuration;file

@node Startup file examples,Migrating from import lines in pth files to start files,Startup entry points start files,site — Site-specific configuration hook
@anchor{library/site startup-file-examples}@anchor{4d88}
@subsubsection Startup file examples


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
sub-subdirectories, @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.

Let’s say that there is also a @code{foo.start} file containing the
following:

@example
# foo package startup code

foo.submod:initialize
@end example

Now, after @code{sys.path} has been extended as above, and before Python turns
control over to user code, the @code{foo.submod} module is imported and the
@code{initialize()} function from that module is called.

@node Migrating from import lines in pth files to start files,sitecustomize,Startup file examples,site — Site-specific configuration hook
@anchor{library/site migrating-from-import-lines-in-pth-files-to-start-files}@anchor{4d89}@anchor{library/site site-migration-guide}@anchor{4d8a}
@subsubsection Migrating from @code{import} lines in @code{.pth} files to @code{.start} files


If your package currently ships a @code{`name'.pth} file, you can keep all
@code{sys.path} extension lines unchanged.  Only @code{import} lines need to be
migrated.

To migrate, create a callable (taking zero arguments) within an importable
module in your package.  Reference it as a @code{pkg.mod:callable} entry point
in a matching @code{`name'.start} file.  Move everything on your @code{import}
line after the first semi-colon into the @code{callable()} function.

If your package must straddle older Pythons that do not support 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/}
and newer Pythons that do, change the @code{import} lines in your
@code{`name'.pth} to use the following form:

@example
import pkg.mod; pkg.mod.callable()
@end example

Older Pythons will execute these @code{import} lines, while newer Pythons will
ignore them in favor of the @code{`name'.start} file.  After the straddling
period, remove all @code{import} lines from your @code{.pth} files.

@node sitecustomize,usercustomize,Migrating from import lines in pth files to start files,site — Site-specific configuration hook
@anchor{library/site module-sitecustomize}@anchor{d0}@anchor{library/site sitecustomize}@anchor{4d8b}
@subsubsection @code{sitecustomize}


@geindex module; sitecustomize

After these path manipulations, an attempt is made to import a module named
@code{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{1bd,,ImportError} or its subclass
exception, and the exception’s @ref{1902,,name}
attribute equals @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 @code{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{117}@anchor{library/site usercustomize}@anchor{4d8c}
@subsubsection @code{usercustomize}


@geindex module; usercustomize

After this, an attempt is made to import a module named @code{usercustomize},
which can perform arbitrary user-specific customizations, if
@ref{4d8d,,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{1732,,-s}.  If this import fails with an @ref{1bd,,ImportError} or
its subclass exception, and the exception’s @ref{1902,,name}
attribute equals @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{d0,,sitecustomize} and @code{usercustomize} is still attempted.

@node Readline configuration,Module contents<7>,usercustomize,site — Site-specific configuration hook
@anchor{library/site readline-configuration}@anchor{4d8e}@anchor{library/site rlcompleter-config}@anchor{1372}
@subsubsection Readline configuration


On systems that support @ref{c2,,readline}, this module will also import and
configure the @ref{c5,,rlcompleter} module, if Python is started in
@ref{656,,interactive mode} and without the @ref{1551,,-S} option.
The default behavior is to enable tab completion and to use
@code{~/.python_history} as the history save file.  To disable it, delete (or
override) the @ref{1371,,sys.__interactivehook__} attribute in your
@ref{d0,,sitecustomize} or @ref{117,,usercustomize} module or your
@geindex PYTHONSTARTUP
@geindex μεταβλητή περιβάλλοντος; PYTHONSTARTUP
@ref{453,,PYTHONSTARTUP} file.


Άλλαξε στην έκδοση 3.4: Activation of rlcompleter and history was made automatic.


@node Module contents<7>,Command-line interface<14>,Readline configuration,site — Site-specific configuration hook
@anchor{library/site module-contents}@anchor{4d8f}
@subsubsection Module contents


@geindex PREFIXES (στη μονάδα site)
@anchor{library/site site PREFIXES}@anchor{4d90}
@deffn {Δεδομένα} site.PREFIXES

A list of prefixes for site-packages directories.
@end deffn

@geindex ENABLE_USER_SITE (στη μονάδα site)
@anchor{library/site site ENABLE_USER_SITE}@anchor{4d8d}
@deffn {Δεδομένα} 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{1732,,-s} or
@geindex PYTHONNOUSERSITE
@geindex μεταβλητή περιβάλλοντος; PYTHONNOUSERSITE
@ref{1733,,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 (στη μονάδα site)
@anchor{library/site site USER_SITE}@anchor{2315}
@deffn {Δεδομένα} site.USER_SITE

Path to the user site-packages for the running Python.  Can be @code{None} if
@ref{15e6,,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 (στη μονάδα site)
@anchor{library/site site USER_BASE}@anchor{16c1}
@deffn {Δεδομένα} site.USER_BASE

Path to the base directory for the user site-packages.  Can be @code{None} if
@ref{15e5,,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{2325,,user installation scheme}.
See also 
@geindex PYTHONUSERBASE
@geindex μεταβλητή περιβάλλοντος; PYTHONUSERBASE
@ref{1731,,PYTHONUSERBASE}.
@end deffn

@geindex main() (στη μονάδα site)
@anchor{library/site site main}@anchor{2316}
@deffn {Συνάρτηση} 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{1551,,-S} flag.


Άλλαξε στην έκδοση 3.3: This function used to be called unconditionally.

@end deffn

@geindex addsitedir() (στη μονάδα site)
@anchor{library/site site addsitedir}@anchor{2463}
@deffn {Συνάρτηση} site.addsitedir (sitedir, known_paths=None, *, defer_processing_start_files=False)

Add a directory to sys.path and parse the @code{.pth} and @code{.start}
files found in that directory.  Typically used in @ref{d0,,sitecustomize} or
@ref{117,,usercustomize} (see above).

The `known_paths' argument is an optional set of case-normalized paths
used to prevent duplicate @ref{194,,sys.path} entries.  When @code{None} (the
default), the set is built from the current @code{sys.path}.

While @code{.pth} and @code{.start} files are always parsed, set
`defer_processing_start_files' to @code{True} to prevent processing the
startup data found in those files, so that you can process them explicitly
(this is typically used by the @ref{2316,,main()} function).


Άλλαξε στην έκδοση 3.15: Also processes @code{.start} files.  See @ref{195,,Startup entry points (.start files)}.
All @code{.pth} and @code{.start} files are now read and
accumulated before any path extensions, @code{import} line execution,
or entry point invocations take place.

@end deffn

@geindex getsitepackages() (στη μονάδα site)
@anchor{library/site site getsitepackages}@anchor{15e4}
@deffn {Συνάρτηση} site.getsitepackages ()

Return a list containing all global site-packages directories.


Added in version 3.2.

@end deffn

@geindex getuserbase() (στη μονάδα site)
@anchor{library/site site getuserbase}@anchor{15e5}
@deffn {Συνάρτηση} site.getuserbase ()

Return the path of the user base directory, @ref{16c1,,USER_BASE}.  If it is not
initialized yet, this function will also set it, respecting
@geindex PYTHONUSERBASE
@geindex μεταβλητή περιβάλλοντος; PYTHONUSERBASE
@ref{1731,,PYTHONUSERBASE}.


Added in version 3.2.

@end deffn

@geindex getusersitepackages() (στη μονάδα site)
@anchor{library/site site getusersitepackages}@anchor{15e6}
@deffn {Συνάρτηση} site.getusersitepackages ()

Return the path of the user-specific site-packages directory,
@ref{2315,,USER_SITE}.  If it is not initialized yet, this function will also set
it, respecting @ref{16c1,,USER_BASE}.  To determine if the user-specific
site-packages was added to @code{sys.path} @ref{4d8d,,ENABLE_USER_SITE} should be
used.


Added in version 3.2.

@end deffn

@node Command-line interface<14>,,Module contents<7>,site — Site-specific configuration hook
@anchor{library/site command-line-interface}@anchor{4d91}@anchor{library/site site-commandline}@anchor{4d92}
@subsubsection Command-line interface


The @code{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{194,,sys.path} on the standard output, followed by the value of
@ref{16c1,,USER_BASE} and whether the directory exists, then the same thing for
@ref{2315,,USER_SITE}, and finally the value of @ref{4d8d,,ENABLE_USER_SITE}.

@geindex site command line option; --user-base
@anchor{library/site cmdoption-site-user-base}@anchor{4d93}
@deffn {Option} @w{-}@w{-}user@w{-}base

Print the path to the user base directory.
@end deffn

@geindex site command line option; --user-site
@anchor{library/site cmdoption-site-user-site}@anchor{4d94}
@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{2322,,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 Δείτε επίσης



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 370
PEP 370@footnote{https://peps.python.org/pep-0370/} – Per user site-packages directory

@item 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/} – Startup entry points and the deprecation of import lines in @code{.pth} files

@item 
@ref{1953,,The initialization of the sys.path module search path} – The initialization of @ref{194,,sys.path}.
@end itemize


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)


@subsubheading Δείτε επίσης



@itemize *

@item 
See the @ref{25,,concurrent.interpreters} module, which similarly
exposes core runtime functionality.
@end itemize


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Custom Python Interpreters,Importing Modules,Python Runtime Services,The Python Standard Library
@anchor{library/custominterp doc}@anchor{4d95}@anchor{library/custominterp custom-python-interpreters}@anchor{4d96}@anchor{library/custominterp custominterp}@anchor{4d97}@anchor{library/custominterp translation-repo}@anchor{4d98}
@section Custom Python Interpreters


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{1b,,code} module.  (The @ref{1d,,codeop} module is lower-level, used
to support compiling a possibly incomplete chunk of Python code.)

The full list of modules described in this chapter is:

@menu
* code — Interpreter base classes:: 
* codeop — Compile Python code:: 

@end menu

@node code — Interpreter base classes,codeop — Compile Python code,,Custom Python Interpreters
@anchor{library/code doc}@anchor{4d99}@anchor{library/code code-interpreter-base-classes}@anchor{4d9a}@anchor{library/code module-code}@anchor{1b}
@subsection @code{code} — Interpreter base classes


@geindex module; code

`Source code:' Lib/code.py@footnote{https://github.com/python/cpython/tree/main/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 (κλάση σε code)
@anchor{library/code code InteractiveInterpreter}@anchor{1b5b}
@deffn {Κλάση} 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}.

Note that functions and classes objects created under an
@code{InteractiveInterpreter} instance will belong to the namespace
specified by `locals'.
They are only pickleable if `locals' is the namespace of an existing
module.
@end deffn

@geindex InteractiveConsole (κλάση σε code)
@anchor{library/code code InteractiveConsole}@anchor{2a1e}
@deffn {Κλάση} code.InteractiveConsole (locals=None, filename='<console>', *, local_exit=False)

Closely emulate the behavior of the interactive Python interpreter. This class
builds on @ref{1b5b,,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{10f7,,SystemExit}, but
instead return to the calling code.


Άλλαξε στην έκδοση 3.13: Added `local_exit' parameter.

@end deffn

@geindex interact() (στη μονάδα code)
@anchor{library/code code interact}@anchor{1ab4}
@deffn {Συνάρτηση} 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{2a1e,,InteractiveConsole} and sets `readfunc' to be used as
the @ref{4d9b,,InteractiveConsole.raw_input()} method, if provided.  If `local' is
provided, it is passed to the @code{InteractiveConsole} constructor for
use as the default namespace for the interpreter loop.  If `local_exit' is provided,
it is passed to the @code{InteractiveConsole} constructor.  The @ref{4d9c,,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.


Άλλαξε στην έκδοση 3.6: Added `exitmsg' parameter.



Άλλαξε στην έκδοση 3.13: Added `local_exit' parameter.

@end deffn

@geindex compile_command() (στη μονάδα code)
@anchor{library/code code compile_command}@anchor{4d9d}
@deffn {Συνάρτηση} 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{17e,,SyntaxError} if the command is complete and contains a syntax error, or
raises @ref{c57,,OverflowError} or @ref{277,,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{4d9e}@anchor{library/code interpreter-objects}@anchor{4d9f}
@subsubsection Interactive Interpreter Objects


@geindex runsource() (μέθοδος της code.InteractiveInterpreter)
@anchor{library/code code InteractiveInterpreter runsource}@anchor{4da0}
@deffn {Μέθοδος} InteractiveInterpreter.runsource (source, filename='<input>', symbol='single')

Compile and run some source in the interpreter. Arguments are the same as for
@ref{4d9d,,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{4d9d,,compile_command()} raised an exception
(@ref{17e,,SyntaxError} or @ref{c57,,OverflowError}).  A syntax traceback will be
printed by calling the @ref{4da1,,showsyntaxerror()} method.  @code{runsource()}
returns @code{False}.

@item 
The input is incomplete, and more input is required; @ref{4d9d,,compile_command()}
returned @code{None}. @code{runsource()} returns @code{True}.

@item 
The input is complete; @ref{4d9d,,compile_command()} returned a code object.  The
code is executed by calling the @ref{4da2,,runcode()} (which also handles run-time
exceptions, except for @ref{10f7,,SystemExit}). @code{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() (μέθοδος της code.InteractiveInterpreter)
@anchor{library/code code InteractiveInterpreter runcode}@anchor{4da2}
@deffn {Μέθοδος} InteractiveInterpreter.runcode (code)

Execute a code object. When an exception occurs, @ref{1187,,showtraceback()} is called
to display a traceback.  All exceptions are caught except @ref{10f7,,SystemExit},
which is allowed to propagate.

A note about @ref{d96,,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() (μέθοδος της code.InteractiveInterpreter)
@anchor{library/code code InteractiveInterpreter showsyntaxerror}@anchor{4da1}
@deffn {Μέθοδος} 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{4da3,,write()} method.
@end deffn

@geindex showtraceback() (μέθοδος της code.InteractiveInterpreter)
@anchor{library/code code InteractiveInterpreter showtraceback}@anchor{1187}
@deffn {Μέθοδος} 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{4da3,,write()} method.


Άλλαξε στην έκδοση 3.5: The full chained traceback is displayed instead
of just the primary traceback.

@end deffn

@geindex write() (μέθοδος της code.InteractiveInterpreter)
@anchor{library/code code InteractiveInterpreter write}@anchor{4da3}
@deffn {Μέθοδος} 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{4da4}@anchor{library/code interactive-console-objects}@anchor{4da5}
@subsubsection Interactive Console Objects


The @ref{2a1e,,InteractiveConsole} class is a subclass of
@ref{1b5b,,InteractiveInterpreter}, and so offers all the methods of the
interpreter objects as well as the following additions.

@geindex interact() (μέθοδος της code.InteractiveConsole)
@anchor{library/code code InteractiveConsole interact}@anchor{4d9c}
@deffn {Μέθοδος} 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.


Άλλαξε στην έκδοση 3.4: To suppress printing any banner, pass an empty string.



Άλλαξε στην έκδοση 3.6: Print an exit message when exiting.

@end deffn

@geindex push() (μέθοδος της code.InteractiveConsole)
@anchor{library/code code InteractiveConsole push}@anchor{4da6}
@deffn {Μέθοδος} 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{4da0,,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() (μέθοδος της code.InteractiveConsole)
@anchor{library/code code InteractiveConsole resetbuffer}@anchor{4da7}
@deffn {Μέθοδος} InteractiveConsole.resetbuffer ()

Remove any unhandled source text from the input buffer.
@end deffn

@geindex raw_input() (μέθοδος της code.InteractiveConsole)
@anchor{library/code code InteractiveConsole raw_input}@anchor{4d9b}
@deffn {Μέθοδος} 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{167e,,EOFError} is raised.
The base implementation reads from @code{sys.stdin}; a subclass may replace this
with a different implementation.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node codeop — Compile Python code,,code — Interpreter base classes,Custom Python Interpreters
@anchor{library/codeop doc}@anchor{4da8}@anchor{library/codeop codeop-compile-python-code}@anchor{4da9}@anchor{library/codeop module-codeop}@anchor{1d}@anchor{library/codeop translation-repo}@anchor{4daa}
@subsection @code{codeop} — Compile Python code


@geindex module; codeop

`Source code:' Lib/codeop.py@footnote{https://github.com/python/cpython/tree/main/Lib/codeop.py}


__________________________________________________________________


The @code{codeop} module provides utilities upon which the Python
read-eval-print loop can be emulated, as is done in the @ref{1b,,code} module.  As
a result, you probably don’t want to use the module directly; if you want to
include such a loop in your program you probably want to use the @code{code}
module instead.

There are two parts to this job:


@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

The @code{codeop} module provides a way of doing each of these things, and a way
of doing them both.

To do just the former:

@geindex compile_command() (στη μονάδα codeop)
@anchor{library/codeop codeop compile_command}@anchor{1d51}
@deffn {Συνάρτηση} 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.

If there is a problem with `source', an exception will be raised.
@ref{17e,,SyntaxError} is raised if there is invalid Python syntax, and
@ref{c57,,OverflowError} or @ref{277,,ValueError} if there is an invalid literal.

The `symbol' argument determines whether `source' is compiled as a statement
(@code{'single'}, the default), as a sequence of @ref{2e17,,statement} (@code{'exec'}) or
as an @ref{25c4,,expression} (@code{'eval'}).  Any other value will
cause @ref{277,,ValueError} to be raised.

@cartouche
@quotation Σημείωση 
It is possible (but not likely) that the parser stops parsing with a
successful outcome before reaching the end of the source; in this case,
trailing symbols may be ignored instead of causing an error.  For example,
a backslash followed by two newlines may be followed by arbitrary garbage.
This will be fixed once the API for the parser is better.
@end quotation
@end cartouche
@end deffn

@geindex Compile (κλάση σε codeop)
@anchor{library/codeop codeop Compile}@anchor{4dab}
@deffn {Κλάση} codeop.Compile

Instances of this class have @ref{961,,__call__()} methods identical in signature to
the built-in function @ref{1c8,,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 (κλάση σε codeop)
@anchor{library/codeop codeop CommandCompiler}@anchor{4dac}
@deffn {Κλάση} codeop.CommandCompiler

Instances of this class have @ref{961,,__call__()} methods identical in signature to
@ref{1d51,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Importing Modules,Python Language Services,Custom Python Interpreters,The Python Standard Library
@anchor{library/modules doc}@anchor{4dad}@anchor{library/modules importing-modules}@anchor{4dae}@anchor{library/modules modules}@anchor{4daf}@anchor{library/modules translation-repo}@anchor{4db0}
@section Importing Modules


The modules described in this chapter provide new ways to import other Python
modules and hooks for customizing the import process.

The full list of modules described in this chapter is:

@menu
* zipimport — Import modules from Zip archives:: 
* pkgutil — Package extension utility:: 
* modulefinder — Find modules used by a script:: 
* runpy — Locating and executing Python modules:: 
* importlib — The implementation of import:: 
* importlib.resources – Ανάγνωση@comma{} άνοιγμα και πρόσβαση σε πόρους πακέτων: importlib resources – Ανάγνωση άνοιγμα και πρόσβαση σε πόρους πακέτων. 
* importlib.resources.abc – Abstract base classes for resources: importlib resources abc – Abstract base classes for resources. 
* importlib.metadata – Accessing package metadata: importlib 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,,Importing Modules
@anchor{library/zipimport doc}@anchor{4db1}@anchor{library/zipimport module-zipimport}@anchor{13b}@anchor{library/zipimport zipimport-import-modules-from-zip-archives}@anchor{4db2}
@subsection @code{zipimport} — Import modules from Zip archives


@geindex module; zipimport

`Source code:' Lib/zipimport.py@footnote{https://github.com/python/cpython/tree/main/Lib/zipimport.py}


__________________________________________________________________


This module adds the ability to import Python modules (@code{*.py},
@code{*.pyc}) and packages from ZIP-format archives. It is usually not
needed to use the @code{zipimport} module explicitly; it is automatically used
by the built-in @ref{9da,,import} mechanism for @ref{194,,sys.path} items that are paths
to ZIP archives.

Typically, @ref{194,,sys.path} is a list of directory names as strings.  This module
also allows an item of @code{sys.path} to be a string naming a ZIP file archive.
The ZIP archive can contain a subdirectory structure to support package imports,
and a path within the archive can be specified to only import from a
subdirectory.  For example, the path @code{example.zip/lib/} would only
import from the @code{lib/} subdirectory within the archive.

Any files may be present in the ZIP archive, but importers are only invoked for
@code{.py} and @code{.pyc} files.  ZIP import of dynamic modules
(@code{.pyd}, @code{.so}) is disallowed. Note that 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.


Άλλαξε στην έκδοση 3.15: Zstandard (`zstd') compressed zip file entries are supported.



Άλλαξε στην έκδοση 3.13: ZIP64 is supported



Άλλαξε στην έκδοση 3.8: Previously, ZIP archives with an archive comment were not supported.



@subsubheading Δείτε επίσης



@table @asis

@item PKZIP Application Note@footnote{https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT}

Documentation on the ZIP file format by Phil Katz, the creator of the format and
algorithms used.

@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/}.

@item @ref{7a,,importlib} - The implementation of the import machinery

Package providing the relevant protocols for all importers to
implement.
@end table


This module defines an exception:

@geindex ZipImportError
@anchor{library/zipimport zipimport ZipImportError}@anchor{4db3}
@deffn {Εξαίρεση} zipimport.ZipImportError

Exception raised by zipimporter objects. It’s a subclass of @ref{1bd,,ImportError},
so it can be caught as @code{ImportError}, too.
@end deffn

@menu
* zipimporter Objects:: 
* Examples: Examples<28>. 

@end menu

@node zipimporter Objects,Examples<28>,,zipimport — Import modules from Zip archives
@anchor{library/zipimport id1}@anchor{4db4}@anchor{library/zipimport zipimporter-objects}@anchor{4db5}
@subsubsection zipimporter Objects


@ref{4db6,,zipimporter} is the class for importing ZIP files.

@geindex zipimporter (κλάση σε zipimport)
@anchor{library/zipimport zipimport zipimporter}@anchor{4db6}
@deffn {Κλάση} zipimport.zipimporter (archivepath)

Create a new zipimporter instance. `archivepath' must be a path to a ZIP
file, or to a specific path within a ZIP file.  For example, an `archivepath'
of @code{foo/bar.zip/lib} will look for modules in the @code{lib} directory
inside the ZIP file @code{foo/bar.zip} (provided that it exists).

@ref{4db3,,ZipImportError} is raised if `archivepath' doesn’t point to a valid ZIP
archive.


Άλλαξε στην έκδοση 3.12: Methods @code{find_loader()} and @code{find_module()}, deprecated in 3.10 are
now removed.  Use @ref{c35,,find_spec()} instead.


@geindex create_module() (μέθοδος της zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter create_module}@anchor{c36}
@deffn {Μέθοδος} create_module (spec)

Implementation of @ref{106f,,importlib.abc.Loader.create_module()} that returns
@ref{a65,,None} to explicitly request the default semantics.


Added in version 3.10.

@end deffn

@geindex exec_module() (μέθοδος της zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter exec_module}@anchor{2e9}
@deffn {Μέθοδος} exec_module (module)

Implementation of @ref{c40,,importlib.abc.Loader.exec_module()}.


Added in version 3.10.

@end deffn

@geindex find_spec() (μέθοδος της zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter find_spec}@anchor{c35}
@deffn {Μέθοδος} find_spec (fullname, target=None)

An implementation of @ref{c42,,importlib.abc.PathEntryFinder.find_spec()}.


Added in version 3.10.

@end deffn

@geindex get_code() (μέθοδος της zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter get_code}@anchor{4db7}
@deffn {Μέθοδος} get_code (fullname)

Return the code object for the specified module. Raise
@ref{4db3,,ZipImportError} if the module couldn’t be imported.
@end deffn

@geindex get_data() (μέθοδος της zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter get_data}@anchor{4db8}
@deffn {Μέθοδος} get_data (pathname)

Return the data associated with `pathname'. Raise @ref{53c,,OSError} if the
file wasn’t found.


Άλλαξε στην έκδοση 3.3: @ref{13fb,,IOError} used to be raised, it is now an alias of @ref{53c,,OSError}.

@end deffn

@geindex get_filename() (μέθοδος της zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter get_filename}@anchor{4db9}
@deffn {Μέθοδος} get_filename (fullname)

Return the value @code{__file__} would be set to if the specified module
was imported. Raise @ref{4db3,,ZipImportError} if the module couldn’t be
imported.


Added in version 3.1.

@end deffn

@geindex get_source() (μέθοδος της zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter get_source}@anchor{4dba}
@deffn {Μέθοδος} get_source (fullname)

Return the source code for the specified module. Raise
@ref{4db3,,ZipImportError} if the module couldn’t be found, return
@ref{a65,,None} if the archive does contain the module, but has no source
for it.
@end deffn

@geindex is_package() (μέθοδος της zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter is_package}@anchor{4dbb}
@deffn {Μέθοδος} is_package (fullname)

Return @code{True} if the module specified by `fullname' is a package. Raise
@ref{4db3,,ZipImportError} if the module couldn’t be found.
@end deffn

@geindex invalidate_caches() (μέθοδος της zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter invalidate_caches}@anchor{c37}
@deffn {Μέθοδος} invalidate_caches ()

Clear out the internal cache of information about files found within
the ZIP archive.


Added in version 3.10.

@end deffn

@geindex archive (ιδιότητα της zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter archive}@anchor{4dbc}
@deffn {Ιδιότητα} archive

The file name of the importer’s associated ZIP file, without a possible
subpath.
@end deffn

@geindex prefix (ιδιότητα της zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter prefix}@anchor{4dbd}
@deffn {Ιδιότητα} prefix

The subpath within the ZIP file where modules are searched.  This is the
empty string for zipimporter objects which point to the root of the ZIP
file.
@end deffn

The @ref{4dbc,,archive} and @ref{4dbd,,prefix} attributes, when combined with a
slash, equal the original `archivepath' argument given to the
@code{zipimporter} constructor.
@end deffn

@node Examples<28>,,zipimporter Objects,zipimport — Import modules from Zip archives
@anchor{library/zipimport examples}@anchor{4dbe}@anchor{library/zipimport zipimport-examples}@anchor{4dbf}
@subsubsection Examples


Here is an example that imports a module from a ZIP archive - note that the
@code{zipimport} module is not explicitly used.

@example
$ unzip -l example_archive.zip
Archive:  example_archive.zip
  Length     Date   Time    Name
 --------    ----   ----    ----
     8467  01-01-00 12:30   example.py
 --------                   -------
     8467                   1 file
@end example

@example
>>> import sys
>>> # Add the archive to the front of the module search path
>>> sys.path.insert(0, 'example_archive.zip')
>>> import example
>>> example.__file__
'example_archive.zip/example.py'
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node pkgutil — Package extension utility,modulefinder — Find modules used by a script,zipimport — Import modules from Zip archives,Importing Modules
@anchor{library/pkgutil doc}@anchor{4dc0}@anchor{library/pkgutil module-pkgutil}@anchor{ae}@anchor{library/pkgutil pkgutil-package-extension-utility}@anchor{4dc1}@anchor{library/pkgutil translation-repo}@anchor{4dc2}
@subsection @code{pkgutil} — Package extension utility


@geindex module; pkgutil

`Source code:' Lib/pkgutil.py@footnote{https://github.com/python/cpython/tree/main/Lib/pkgutil.py}


__________________________________________________________________


This module provides utilities for the import system, in particular package
support.

@geindex ModuleInfo (κλάση σε pkgutil)
@anchor{library/pkgutil pkgutil ModuleInfo}@anchor{1101}
@deffn {Κλάση} pkgutil.ModuleInfo (module_finder, name, ispkg)

A namedtuple that holds a brief summary of a module’s info.


Added in version 3.6.

@end deffn

@geindex extend_path() (στη μονάδα pkgutil)
@anchor{library/pkgutil pkgutil extend_path}@anchor{1b3f}
@deffn {Συνάρτηση} pkgutil.extend_path (path, name)

Extend the search path for the modules which comprise a package.  Intended
use is to place the following code in a package’s @code{__init__.py}:

@example
from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)
@end example

For each directory on @ref{194,,sys.path} that has a subdirectory that matches the
package name, add the subdirectory to the package’s
@ref{2243,,__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{cf,,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).

If the input path is not a list (as is the case for frozen packages) it is
returned unchanged.  The input path is not modified; an extended copy is
returned.  Items are only appended to the copy at the end.

It is assumed that @ref{194,,sys.path} is a sequence.  Items of @code{sys.path}
that are not strings referring to existing directories are ignored. Unicode
items on @code{sys.path} that cause errors when used as filenames may cause
this function to raise an exception (in line with @ref{dd4,,os.path.isdir()}
behavior).
@end deffn

@geindex get_importer() (στη μονάδα pkgutil)
@anchor{library/pkgutil pkgutil get_importer}@anchor{4dc3}
@deffn {Συνάρτηση} pkgutil.get_importer (path_item)

Retrieve a @ref{263e,,finder} for the given `path_item'.

The returned finder is cached in @ref{9db,,sys.path_importer_cache} if it was
newly created by a path hook.

The cache (or part of it) can be cleared manually if a rescan of
@ref{13cd,,sys.path_hooks} is necessary.


Άλλαξε στην έκδοση 3.3: Updated to be based directly on @ref{7a,,importlib} rather than relying
on the package internal 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} import emulation.

@end deffn

@geindex iter_importers() (στη μονάδα pkgutil)
@anchor{library/pkgutil pkgutil iter_importers}@anchor{1542}
@deffn {Συνάρτηση} pkgutil.iter_importers (fullname='@w{'})

Yield @ref{263e,,finder} objects for the given module name.

If `fullname' contains a @code{'.'}, the finders will be for the package
containing `fullname', otherwise they will be all registered top level
finders (i.e. those on both @ref{10e3,,sys.meta_path} and @ref{13cd,,sys.path_hooks}).

If the named module is in a package, that package is imported as a side
effect of invoking this function.

If no module name is specified, all top level finders are produced.


Άλλαξε στην έκδοση 3.3: Updated to be based directly on @ref{7a,,importlib} rather than relying
on the package internal 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} import emulation.

@end deffn

@geindex iter_modules() (στη μονάδα pkgutil)
@anchor{library/pkgutil pkgutil iter_modules}@anchor{1100}
@deffn {Συνάρτηση} pkgutil.iter_modules (path=None, prefix='@w{'})

Yields @ref{1101,,ModuleInfo} for all submodules on `path', or, if
`path' is @code{None}, all top-level modules on @ref{194,,sys.path}.

`path' should be either @code{None} or a list of paths to look for modules in.

`prefix' is a string to output on the front of every module name on output.

@cartouche
@quotation Σημείωση 
Only works for a @ref{263e,,finder} which defines an @code{iter_modules()}
method. This interface is non-standard, so the module also provides
implementations for @ref{141a,,importlib.machinery.FileFinder} and
@ref{4db6,,zipimport.zipimporter}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: Updated to be based directly on @ref{7a,,importlib} rather than relying
on the package internal 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} import emulation.

@end deffn

@geindex walk_packages() (στη μονάδα pkgutil)
@anchor{library/pkgutil pkgutil walk_packages}@anchor{fbe}
@deffn {Συνάρτηση} pkgutil.walk_packages (path=None, prefix='@w{'}, onerror=None)

Yields @ref{1101,,ModuleInfo} for all modules recursively on
`path', or, if `path' is @code{None}, all accessible modules.

`path' should be either @code{None} or a list of paths to look for modules in.

`prefix' is a string to output on the front of every module name on output.

Note that this function must import all `packages' (`not' all modules!) on
the given `path', in order to access the @code{__path__} attribute to find
submodules.

`onerror' is a function which gets called with one argument (the name of the
package which was being imported) if any exception occurs while trying to
import a package.  If no `onerror' function is supplied, @ref{1bd,,ImportError}s
are caught and ignored, while all other exceptions are propagated,
terminating the search.

Examples:

@example
# list all modules python can access
walk_packages()

# list all submodules of ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')
@end example

@cartouche
@quotation Σημείωση 
Only works for a @ref{263e,,finder} which defines an @code{iter_modules()}
method. This interface is non-standard, so the module also provides
implementations for @ref{141a,,importlib.machinery.FileFinder} and
@ref{4db6,,zipimport.zipimporter}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: Updated to be based directly on @ref{7a,,importlib} rather than relying
on the package internal 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} import emulation.

@end deffn

@geindex get_data() (στη μονάδα pkgutil)
@anchor{library/pkgutil pkgutil get_data}@anchor{4dc4}
@deffn {Συνάρτηση} pkgutil.get_data (package, resource)

Get a resource from a package.

This is a wrapper for the @ref{1c30,,loader}
@ref{4dc5,,get_data} API.  The
`package' argument should be the name of a package, in standard module format
(@code{foo.bar}).  The `resource' argument should be in the form of a relative
filename, using @code{/} as the path separator.

The function returns a binary string that is the contents of the specified
resource.

This function uses the @ref{1c30,,loader} method
@ref{4dc6,,get_data()}
to support modules installed in the filesystem, but also in zip files,
databases, or elsewhere.

For packages located in the filesystem, which have already been imported,
this is the rough equivalent of:

@example
d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()
@end example

Like the @ref{32b,,open()} function, @code{get_data()} can follow parent
directories (@code{../}) and absolute paths (starting with @code{/} or @code{C:/},
for example).
It can open compilation/installation artifacts like @code{.py} and @code{.pyc}
files or files with @ref{2d9,,reserved filenames}.
To be compatible with non-filesystem loaders, avoid using these features.

@cartouche
@quotation Προειδοποίηση 
This function is intended for trusted input.
It does not verify that `resource' «belongs» to `package'.
@end quotation
@end cartouche

If you use a user-provided `resource' path, consider verifying it.
For example, require an alphanumeric filename with a known extension, or
install and check a list of known resources.

If the package cannot be located or loaded, or it uses a @ref{1c30,,loader}
which does not support @ref{4dc5,,get_data},
then @code{None} is returned.  In particular, the loader for
@ref{52e,,namespace packages} does not support
@code{get_data}.


@subsubheading Δείτε επίσης


The @ref{7e,,importlib.resources} module provides structured access to
module resources.

@end deffn

@geindex resolve_name() (στη μονάδα pkgutil)
@anchor{library/pkgutil pkgutil resolve_name}@anchor{1904}
@deffn {Συνάρτηση} pkgutil.resolve_name (name, *, strict=False)

Resolve a name to an object.

This functionality is used in numerous places in the standard library (see
bpo-12915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12915}) - and equivalent functionality is also in widely used
third-party packages such as setuptools, Django and Pyramid.

It is expected that `name' will be a string in one of the following
formats, where W is shorthand for a valid Python identifier and dot stands
for a literal period in these pseudo-regexes:


@itemize *

@item 
@code{W(.W)*}

@item 
@code{W(.W)*:(W(.W)*)?}

@item 
@code{W(.W)*:(W(.W)*)}
@end itemize

The first form is intended for backward compatibility only. It assumes that
some part of the dotted name is a package, and the rest is an object
somewhere within that package, possibly nested inside other objects.
Because the place where the package stops and the object hierarchy starts
can’t be inferred by inspection, repeated attempts to import must be done
with this form.

In the second form, the caller makes the division point clear through the
provision of a single colon: the dotted name to the left of the colon is a
package to be imported, and the dotted name to the right is the object
hierarchy within that package. Only one import is needed in this form. If
it ends with the colon, then a module object is returned.

The first two forms are accepted when @code{strict=False} (the default).

The third form requires both the module name and callable, separated by
a colon. Only this form is accepted when @code{strict=True}.

The function will return an object (which might be a module), or raise one
of the following exceptions:

@ref{277,,ValueError} – if `name' isn’t in a recognised format.

@ref{1bd,,ImportError} – if an import failed when it shouldn’t have.

@ref{1a9,,AttributeError} – If a failure occurred when traversing the object
hierarchy within the imported package to get to the desired object.


Added in version 3.9.



Άλλαξε στην έκδοση 3.15: The optional keyword-only @code{strict} flag was added.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node modulefinder — Find modules used by a script,runpy — Locating and executing Python modules,pkgutil — Package extension utility,Importing Modules
@anchor{library/modulefinder doc}@anchor{4dc7}@anchor{library/modulefinder module-modulefinder}@anchor{95}@anchor{library/modulefinder modulefinder-find-modules-used-by-a-script}@anchor{4dc8}@anchor{library/modulefinder translation-repo}@anchor{4dc9}
@subsection @code{modulefinder} — Find modules used by a script


@geindex module; modulefinder

`Source code:' Lib/modulefinder.py@footnote{https://github.com/python/cpython/tree/main/Lib/modulefinder.py}


__________________________________________________________________


This module provides a @ref{1fd4,,ModuleFinder} class that can be used to determine
the set of modules imported by a script. @code{modulefinder.py} can also be run as
a script, giving the filename of a Python script as its argument, after which a
report of the imported modules will be printed.

@geindex AddPackagePath() (στη μονάδα modulefinder)
@anchor{library/modulefinder modulefinder AddPackagePath}@anchor{4dca}
@deffn {Συνάρτηση} modulefinder.AddPackagePath (pkg_name, path)

Record that the package named `pkg_name' can be found in the specified `path'.
@end deffn

@geindex ReplacePackage() (στη μονάδα modulefinder)
@anchor{library/modulefinder modulefinder ReplacePackage}@anchor{4dcb}
@deffn {Συνάρτηση} modulefinder.ReplacePackage (oldname, newname)

Allows specifying that the module named `oldname' is in fact the package named
`newname'.
@end deffn

@geindex ModuleFinder (κλάση σε modulefinder)
@anchor{library/modulefinder modulefinder ModuleFinder}@anchor{1fd4}
@deffn {Κλάση} modulefinder.ModuleFinder (path=None, debug=0, excludes=[], replace_paths=[])

This class provides @ref{4dcc,,run_script()} and @ref{4dcd,,report()} methods to determine
the set of modules imported by a script. `path' can be a list of directories to
search for modules; if not specified, @code{sys.path} is used.  `debug' sets the
debugging level; higher values make the class print debugging messages about
what it’s doing. `excludes' is a list of module names to exclude from the
analysis. `replace_paths' is a list of @code{(oldpath, newpath)} tuples that will
be replaced in module paths.

@geindex report() (μέθοδος της modulefinder.ModuleFinder)
@anchor{library/modulefinder modulefinder ModuleFinder report}@anchor{4dcd}
@deffn {Μέθοδος} report ()

Print a report to standard output that lists the modules imported by the
script and their paths, as well as modules that are missing or seem to be
missing.
@end deffn

@geindex run_script() (μέθοδος της modulefinder.ModuleFinder)
@anchor{library/modulefinder modulefinder ModuleFinder run_script}@anchor{4dcc}
@deffn {Μέθοδος} run_script (pathname)

Analyze the contents of the `pathname' file, which must contain Python
code.
@end deffn

@geindex modules (ιδιότητα της modulefinder.ModuleFinder)
@anchor{library/modulefinder modulefinder ModuleFinder modules}@anchor{4dce}
@deffn {Ιδιότητα} modules

A dictionary mapping module names to modules. See
@ref{4dcf,,Example usage of ModuleFinder}.
@end deffn
@end deffn

@menu
* Example usage of ModuleFinder:: 

@end menu

@node Example usage of ModuleFinder,,,modulefinder — Find modules used by a script
@anchor{library/modulefinder example-usage-of-modulefinder}@anchor{4dd0}@anchor{library/modulefinder modulefinder-example}@anchor{4dcf}
@subsubsection Example usage of @code{ModuleFinder}


The script that is going to get analyzed later on (bacon.py):

@example
import re, itertools

try:
    import baconhameggs
except ImportError:
    pass

try:
    import guido.python.ham
except ImportError:
    pass
@end example

The script that will output the report of 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

Sample output (may vary depending on the 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node runpy — Locating and executing Python modules,importlib — The implementation of import,modulefinder — Find modules used by a script,Importing Modules
@anchor{library/runpy doc}@anchor{4dd1}@anchor{library/runpy module-runpy}@anchor{c6}@anchor{library/runpy runpy-locating-and-executing-python-modules}@anchor{4dd2}@anchor{library/runpy translation-repo}@anchor{4dd3}
@subsection @code{runpy} — Locating and executing Python modules


@geindex module; runpy

`Source code:' Lib/runpy.py@footnote{https://github.com/python/cpython/tree/main/Lib/runpy.py}


__________________________________________________________________


The @code{runpy} module is used to locate and run Python modules without
importing them first. Its main use is to implement the @ref{4ca,,-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 @code{runpy} function has returned.
If that limitation is not acceptable for a given use case, @ref{7a,,importlib}
is likely to be a more suitable choice than this module.

The @code{runpy} module provides two functions:

@geindex run_module() (στη μονάδα runpy)
@anchor{library/runpy runpy run_module}@anchor{1901}
@deffn {Συνάρτηση} 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 @code{run_module()}.

The special global variables @code{__name__}, @code{__spec__}, @code{__file__},
@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{a65,,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{__loader__} and @code{__package__} are
@ref{2552,,set as normal} based on the module spec.

If the argument `alter_sys' is supplied and evaluates to @ref{fcc,,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{e2,,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 Δείτε επίσης


The @ref{4ca,,-m} option offering equivalent functionality from the
command line.



Άλλαξε στην έκδοση 3.1: Added ability to execute packages by looking for a @ref{1,,__main__} submodule.



Άλλαξε στην έκδοση 3.2: Added @code{__cached__} global variable (see 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}).



Άλλαξε στην έκδοση 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}.



Άλλαξε στην έκδοση 3.12: The setting of @code{__cached__}, @code{__loader__}, and
@code{__package__} are deprecated. See
@ref{245d,,ModuleSpec} for alternatives.



Άλλαξε στην έκδοση 3.15: @code{__cached__} is no longer set.

@end deffn

@geindex run_path() (στη μονάδα runpy)
@anchor{library/runpy runpy run_path}@anchor{6ae}
@deffn {Συνάρτηση} 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{194,,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{194,,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 @code{run_path()}.

The special global variables @code{__name__}, @code{__spec__}, @code{__file__},
@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{a65,,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{__loader__} and
@code{__package__} will all be set to @ref{a65,,None}.

If `file_path' is a reference to a valid @ref{194,,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{__loader__} and @code{__package__} will be
@ref{2552,,set as normal} based on the module spec.

A number of alterations are also made to the @ref{e2,,sys} module. Firstly,
@ref{194,,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 @code{sys} are reverted before the function
returns.

Note that, unlike @ref{1901,,run_module()}, the alterations made to @ref{e2,,sys}
are not optional in this function as these adjustments are essential to
allowing the execution of @ref{194,,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 Δείτε επίσης


@ref{230a,,Interface options} for equivalent functionality on the
command line (@code{python path/to/script}).



Added in version 3.2.



Άλλαξε στην έκδοση 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{194,,sys.path} entry rather
than being executed directly.



Άλλαξε στην έκδοση 3.12: The setting of @code{__cached__}, @code{__loader__}, and
@code{__package__} are deprecated.



Άλλαξε στην έκδοση 3.15: @code{__cached__} is no longer set.

@end deffn


@subsubheading Δείτε επίσης



@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.

@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{1f98,,Command line and environment} - CPython command line details

The @ref{927,,importlib.import_module()} function


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node importlib — The implementation of import,importlib resources – Ανάγνωση άνοιγμα και πρόσβαση σε πόρους πακέτων,runpy — Locating and executing Python modules,Importing Modules
@anchor{library/importlib doc}@anchor{4dd4}@anchor{library/importlib importlib-the-implementation-of-import}@anchor{4dd5}@anchor{library/importlib module-importlib}@anchor{7a}@anchor{library/importlib translation-repo}@anchor{4dd6}
@subsection @code{importlib} — The implementation of @code{import}


@geindex module; importlib


Added in version 3.1.


`Source code:' Lib/importlib/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/importlib/__init__.py}


__________________________________________________________________


@menu
* Introduction: Introduction<11>. 
* Functions: Functions<11>. 
* importlib.abc – Abstract base classes related to import: importlib abc – Abstract base classes related to import. 
* importlib.machinery – Importers and path hooks: importlib machinery – Importers and path hooks. 
* importlib.util – Utility code for importers: importlib util – Utility code for importers. 
* Examples: Examples<29>. 

@end menu

@node Introduction<11>,Functions<11>,,importlib — The implementation of import
@anchor{library/importlib introduction}@anchor{4dd7}
@subsubsection Introduction


The purpose of the @code{importlib} package is three-fold.

One is to provide the
implementation of the @ref{9da,,import} statement (and thus, by extension, the
@ref{ca6,,__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{9da,,import} are exposed in this
package, making it easier for users to create their own custom objects (known
generically as an @ref{263f,,importer}) to participate in the import process.

Three, the package contains modules exposing additional functionality for
managing aspects of Python packages:


@itemize *

@item 
@ref{7d,,importlib.metadata} presents access to metadata from third-party
distributions.

@item 
@ref{7e,,importlib.resources} provides routines for accessing non-code
«resources» from Python packages.
@end itemize


@subsubheading Δείτε επίσης



@table @asis

@item @ref{9da,,Η εντολή import}

The language reference for the @ref{9da,,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{19ba,,sys.modules}).

@item The @ref{1415,,__import__()} function

The @ref{9da,,import} statement is syntactic sugar for this function.

@item @ref{1953,,The initialization of the sys.path module search path}

The initialization of @ref{194,,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 Functions<11>,importlib abc – Abstract base classes related to import,Introduction<11>,importlib — The implementation of import
@anchor{library/importlib functions}@anchor{4dd8}
@subsubsection Functions


@geindex __import__() (στη μονάδα importlib)
@anchor{library/importlib importlib __import__}@anchor{1415}
@deffn {Συνάρτηση} importlib.__import__ (name, globals=None, locals=None, fromlist=(), level=0)

An implementation of the built-in @code{__import__()} function.

@cartouche
@quotation Σημείωση 
Programmatic importing of modules should use @ref{927,,import_module()}
instead of this function.
@end quotation
@end cartouche
@end deffn

@geindex import_module() (στη μονάδα importlib)
@anchor{library/importlib importlib import_module}@anchor{927}
@deffn {Συνάρτηση} 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 @code{import_module()} function acts as a simplifying wrapper around
@ref{1415,,importlib.__import__()}. This means all semantics of the function are
derived from @code{importlib.__import__()}. The most important difference
between these two functions is that @code{import_module()} returns the
specified package or module (e.g. @code{pkg.mod}), while @ref{ca6,,__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{fcf,,invalidate_caches()} in order for the new module to be
noticed by the import system.

If the module cannot be imported, @code{import_module()} will raise
@ref{1bd,,ImportError} or an appropriate subclass like
@ref{1be,,ModuleNotFoundError}.


Άλλαξε στην έκδοση 3.3: Parent packages are automatically imported.

@end deffn

@geindex invalidate_caches() (στη μονάδα importlib)
@anchor{library/importlib importlib invalidate_caches}@anchor{fcf}
@deffn {Συνάρτηση} importlib.invalidate_caches ()

Invalidate the internal caches of finders stored at
@ref{10e3,,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.


Added in version 3.3.



Άλλαξε στην έκδοση 3.10: Namespace packages created/installed in a different @ref{194,,sys.path}
location after the same namespace was already imported are noticed.

@end deffn

@geindex reload() (στη μονάδα importlib)
@anchor{library/importlib importlib reload}@anchor{928}
@deffn {Συνάρτηση} 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{19ba,,sys.modules}).

When @code{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{1c30,,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{ad6,,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{e2,,sys}, @ref{1,,__main__}, @ref{13,,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{1650,,from} …
@ref{9da,,import} …, calling @code{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.


Added in version 3.4.



Άλλαξε στην έκδοση 3.7: @ref{1be,,ModuleNotFoundError} is raised when the module being reloaded lacks
a @ref{245d,,ModuleSpec}.


@cartouche
@quotation Προειδοποίηση 
This function is not thread-safe. Calling it from multiple threads can result
in unexpected behavior. It’s recommended to use the @ref{1a10,,threading.Lock}
or other synchronization primitives for thread-safe module reloading.
@end quotation
@end cartouche
@end deffn

@node importlib abc – Abstract base classes related to import,importlib machinery – Importers and path hooks,Functions<11>,importlib — The implementation of import
@anchor{library/importlib importlib-abc-abstract-base-classes-related-to-import}@anchor{4dd9}@anchor{library/importlib module-importlib abc}@anchor{7b}
@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/main/Lib/importlib/abc.py}


__________________________________________________________________


The @code{importlib.abc} module contains all of the core abstract base classes
used by @ref{9da,,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 (κλάση σε importlib.abc)
@anchor{library/importlib importlib abc MetaPathFinder}@anchor{c44}
@deffn {Κλάση} importlib.abc.MetaPathFinder

An abstract base class representing a @ref{1418,,meta path finder}.


Added in version 3.3.



Άλλαξε στην έκδοση 3.10: No longer a subclass of @code{Finder}.


@geindex find_spec() (μέθοδος της importlib.abc.MetaPathFinder)
@anchor{library/importlib importlib abc MetaPathFinder find_spec}@anchor{c3f}
@deffn {Μέθοδος} find_spec (fullname, path, target=None)

An abstract method for finding a @ref{2554,,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{2243,,__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{c43,,importlib.util.spec_from_loader()} may be useful for implementing
concrete @code{MetaPathFinders}.


Added in version 3.4.

@end deffn

@geindex invalidate_caches() (μέθοδος της importlib.abc.MetaPathFinder)
@anchor{library/importlib importlib abc MetaPathFinder invalidate_caches}@anchor{4dda}
@deffn {Μέθοδος} invalidate_caches ()

An optional method which, when called, should invalidate any internal
cache used by the finder. Used by @ref{fcf,,importlib.invalidate_caches()}
when invalidating the caches of all finders on @ref{10e3,,sys.meta_path}.


Άλλαξε στην έκδοση 3.4: Returns @code{None} when called instead of @ref{440,,NotImplemented}.

@end deffn

@geindex discover() (μέθοδος της importlib.abc.MetaPathFinder)
@anchor{library/importlib importlib abc MetaPathFinder discover}@anchor{194b}
@deffn {Μέθοδος} discover (parent=None)

An optional method which searches for possible specs with given `parent'
module spec. If `parent' is `None', @code{MetaPathFinder.discover()} will
search for top-level modules.

Returns an iterable of possible specs.

Raises @ref{277,,ValueError} if `parent' is not a package module.

@cartouche
@quotation Προειδοποίηση 
This method can potentially yield a very large number of objects, and
it may carry out IO operations when computing these values.

Because of this, it will generally be desirable to compute the result
values on-the-fly, as they are needed. As such, the returned object is
only guaranteed to be an @ref{28aa,,iterable},
instead of a @ref{4d9,,list} or other
@ref{1047,,collection} type.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn
@end deffn

@geindex PathEntryFinder (κλάση σε importlib.abc)
@anchor{library/importlib importlib abc PathEntryFinder}@anchor{c45}
@deffn {Κλάση} importlib.abc.PathEntryFinder

An abstract base class representing a @ref{1419,,path entry finder}.  Though
it bears some similarities to @ref{c44,,MetaPathFinder}, @code{PathEntryFinder}
is meant for use only within the path-based import subsystem provided
by @ref{13cc,,importlib.machinery.PathFinder}.


Added in version 3.3.



Άλλαξε στην έκδοση 3.10: No longer a subclass of @code{Finder}.


@geindex find_spec() (μέθοδος της importlib.abc.PathEntryFinder)
@anchor{library/importlib importlib abc PathEntryFinder find_spec}@anchor{c42}
@deffn {Μέθοδος} find_spec (fullname, target=None)

An abstract method for finding a @ref{2554,,spec} for
the specified module.  The finder will search for the module only
within the @ref{264e,,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{c43,,importlib.util.spec_from_loader()}
may be useful for implementing concrete @code{PathEntryFinders}.


Added in version 3.4.

@end deffn

@geindex invalidate_caches() (μέθοδος της importlib.abc.PathEntryFinder)
@anchor{library/importlib importlib abc PathEntryFinder invalidate_caches}@anchor{4ddb}
@deffn {Μέθοδος} invalidate_caches ()

An optional method which, when called, should invalidate any internal
cache used by the finder. Used by
@ref{fce,,importlib.machinery.PathFinder.invalidate_caches()}
when invalidating the caches of all cached finders.
@end deffn

@geindex discover() (μέθοδος της importlib.abc.PathEntryFinder)
@anchor{library/importlib importlib abc PathEntryFinder discover}@anchor{194c}
@deffn {Μέθοδος} discover (parent=None)

An optional method which searches for possible specs with given `parent'
module spec. If `parent' is `None', @code{PathEntryFinder.discover()} will
search for top-level modules.

Returns an iterable of possible specs.

Raises @ref{277,,ValueError} if `parent' is not a package module.

@cartouche
@quotation Προειδοποίηση 
This method can potentially yield a very large number of objects, and
it may carry out IO operations when computing these values.

Because of this, it will generally be desirable to compute the result
values on-the-fly, as they are needed. As such, the returned object is
only guaranteed to be an @ref{28aa,,iterable},
instead of a @ref{4d9,,list} or other
@ref{1047,,collection} type.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn
@end deffn

@geindex Loader (κλάση σε importlib.abc)
@anchor{library/importlib importlib abc Loader}@anchor{1275}
@deffn {Κλάση} importlib.abc.Loader

@quotation

An abstract base class for a @ref{1c30,,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{4ddc,,importlib.resources.abc.ResourceReader}.


Άλλαξε στην έκδοση 3.7: Introduced the optional @code{get_resource_reader()} method.

@end quotation


Άλλαξε στην έκδοση 3.15: Removed the @code{load_module()} method.

@geindex create_module() (μέθοδος της importlib.abc.Loader)
@anchor{library/importlib importlib abc Loader create_module}@anchor{106f}
@deffn {Μέθοδος} 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.


Added in version 3.4.



Άλλαξε στην έκδοση 3.6: This method is no longer optional when
@ref{c40,,exec_module()} is defined.

@end deffn

@geindex exec_module() (μέθοδος της importlib.abc.Loader)
@anchor{library/importlib importlib abc Loader exec_module}@anchor{c40}
@deffn {Μέθοδος} 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 @code{exec_module()} is called.  When this method exists,
@ref{106f,,create_module()} must be defined.


Added in version 3.4.



Άλλαξε στην έκδοση 3.6: @ref{106f,,create_module()} must also be defined.

@end deffn

@end deffn

@geindex ResourceLoader (κλάση σε importlib.abc)
@anchor{library/importlib importlib abc ResourceLoader}@anchor{fa7}
@deffn {Κλάση} importlib.abc.ResourceLoader

`Superseded by TraversableResources'

@quotation

An abstract base class for a @ref{1c30,,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.


Αποσύρθηκε στην έκδοση 3.7: This ABC is deprecated in favour of supporting resource loading
through @ref{571,,importlib.resources.abc.TraversableResources}.
This class exists for backwards compatibility only with other ABCs in
this module.


@geindex get_data() (μέθοδος της importlib.abc.ResourceLoader)
@anchor{library/importlib importlib abc ResourceLoader get_data}@anchor{4dc5}
@deffn {Μέθοδος} abstractmethod get_data (path)

@quotation

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{53c,,OSError} is to be raised if the `path' cannot
be found. The `path' is expected to be constructed using a module’s
@ref{255a,,__file__} attribute or an item from a package’s
@ref{2243,,__path__}.


Άλλαξε στην έκδοση 3.4: Raises @ref{53c,,OSError} instead of @ref{59a,,NotImplementedError}.

@end quotation
@end deffn
@end quotation
@end deffn

@geindex InspectLoader (κλάση σε importlib.abc)
@anchor{library/importlib importlib abc InspectLoader}@anchor{12fe}
@deffn {Κλάση} importlib.abc.InspectLoader

An abstract base class for a @ref{1c30,,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() (μέθοδος της importlib.abc.InspectLoader)
@anchor{library/importlib importlib abc InspectLoader get_code}@anchor{12ff}
@deffn {Μέθοδος} 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{1bd,,ImportError} if loader cannot find the
requested module.

@cartouche
@quotation Σημείωση 
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


Άλλαξε στην έκδοση 3.4: No longer abstract and a concrete implementation is provided.

@end deffn

@geindex get_source() (μέθοδος της importlib.abc.InspectLoader)
@anchor{library/importlib importlib abc InspectLoader get_source}@anchor{1302}
@deffn {Μέθοδος} abstractmethod get_source (fullname)

@quotation

An abstract method to return the source of a module. It is returned as
a text string using @ref{10f1,,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{1bd,,ImportError} if the loader cannot find the module specified.


Άλλαξε στην έκδοση 3.4: Raises @ref{1bd,,ImportError} instead of @ref{59a,,NotImplementedError}.

@end quotation
@end deffn

@geindex is_package() (μέθοδος της importlib.abc.InspectLoader)
@anchor{library/importlib importlib abc InspectLoader is_package}@anchor{4ddd}
@deffn {Μέθοδος} is_package (fullname)

An optional method to return a true value if the module is a package, a
false value otherwise. @ref{1bd,,ImportError} is raised if the
@ref{1c30,,loader} cannot find the module.


Άλλαξε στην έκδοση 3.4: Raises @ref{1bd,,ImportError} instead of @ref{59a,,NotImplementedError}.

@end deffn

@geindex source_to_code() (στατική μέθοδος της importlib.abc.InspectLoader)
@anchor{library/importlib importlib abc InspectLoader source_to_code}@anchor{1cb}
@deffn {Μέθοδος} static source_to_code (data, path='<string>', fullname=None)

Create a code object from Python source.

The `data' argument can be whatever the @ref{1c8,,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__)}.

The optional argument `fullname' specifies the module name.
It is needed to unambiguous @ref{1cc,,filter} syntax
warnings by module name.


Added in version 3.4.



Άλλαξε στην έκδοση 3.5: Made the method static.



Added in version 3.15: Added the `fullname' parameter.

@end deffn

@geindex exec_module() (μέθοδος της importlib.abc.InspectLoader)
@anchor{library/importlib importlib abc InspectLoader exec_module}@anchor{13bb}
@deffn {Μέθοδος} exec_module (module)

Implementation of @ref{c40,,Loader.exec_module()}.


Added in version 3.4.

@end deffn
@end deffn

@geindex ExecutionLoader (κλάση σε importlib.abc)
@anchor{library/importlib importlib abc ExecutionLoader}@anchor{4dde}
@deffn {Κλάση} importlib.abc.ExecutionLoader

An abstract base class which inherits from @ref{12fe,,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() (μέθοδος της importlib.abc.ExecutionLoader)
@anchor{library/importlib importlib abc ExecutionLoader get_filename}@anchor{4ddf}
@deffn {Μέθοδος} abstractmethod get_filename (fullname)

@quotation

An abstract method that is to return the value of
@ref{255a,,__file__} for the specified module. If no path is
available, @ref{1bd,,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.


Άλλαξε στην έκδοση 3.4: Raises @ref{1bd,,ImportError} instead of @ref{59a,,NotImplementedError}.

@end quotation
@end deffn
@end deffn

@geindex FileLoader (κλάση σε importlib.abc)
@anchor{library/importlib importlib abc FileLoader}@anchor{141b}
@deffn {Κλάση} importlib.abc.FileLoader (fullname, path)

An abstract base class which inherits from @ref{fa7,,ResourceLoader} and
@ref{4dde,,ExecutionLoader}, providing concrete implementations of
@ref{4dc5,,ResourceLoader.get_data()} and @ref{4ddf,,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.


Added in version 3.3.



Άλλαξε στην έκδοση 3.15: Removed the @code{load_module()} method.


@geindex name (ιδιότητα της importlib.abc.FileLoader)
@anchor{library/importlib importlib abc FileLoader name}@anchor{4de0}
@deffn {Ιδιότητα} name

The name of the module the loader can handle.
@end deffn

@geindex path (ιδιότητα της importlib.abc.FileLoader)
@anchor{library/importlib importlib abc FileLoader path}@anchor{4de1}
@deffn {Ιδιότητα} path

Path to the file of the module.
@end deffn

@geindex get_filename() (μέθοδος της importlib.abc.FileLoader)
@anchor{library/importlib importlib abc FileLoader get_filename}@anchor{4de2}
@deffn {Μέθοδος} abstractmethod get_filename (fullname)

Returns @ref{4de1,,path}.
@end deffn

@geindex get_data() (μέθοδος της importlib.abc.FileLoader)
@anchor{library/importlib importlib abc FileLoader get_data}@anchor{4dc6}
@deffn {Μέθοδος} abstractmethod get_data (path)

Reads `path' as a binary file and returns the bytes from it.
@end deffn
@end deffn

@geindex SourceLoader (κλάση σε importlib.abc)
@anchor{library/importlib importlib abc SourceLoader}@anchor{4de3}
@deffn {Κλάση} importlib.abc.SourceLoader

An abstract base class for implementing source (and optionally bytecode)
file loading. The class inherits from both @ref{fa7,,ResourceLoader} and
@ref{4dde,,ExecutionLoader}, requiring the implementation of:


@itemize *

@item 
@ref{4dc5,,ResourceLoader.get_data()}

@item 

@table @asis

@item @ref{4ddf,,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{59a,,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.


Άλλαξε στην έκδοση 3.15: Removed the @code{load_module()} method.


@geindex path_stats() (μέθοδος της importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader path_stats}@anchor{1533}
@deffn {Μέθοδος} path_stats (path)

Optional abstract method which returns a @ref{188,,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{53c,,OSError} is raised.


Added in version 3.3.



Άλλαξε στην έκδοση 3.4: Raise @ref{53c,,OSError} instead of @ref{59a,,NotImplementedError}.

@end deffn

@geindex path_mtime() (μέθοδος της importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader path_mtime}@anchor{1532}
@deffn {Μέθοδος} path_mtime (path)

Optional abstract method which returns the modification time for the
specified path.


Αποσύρθηκε στην έκδοση 3.3: This method is deprecated in favour of @ref{1533,,path_stats()}.  You don’t
have to implement it, but it is still available for compatibility
purposes. Raise @ref{53c,,OSError} if the path cannot be handled.



Άλλαξε στην έκδοση 3.4: Raise @ref{53c,,OSError} instead of @ref{59a,,NotImplementedError}.

@end deffn

@geindex set_data() (μέθοδος της importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader set_data}@anchor{4de4}
@deffn {Μέθοδος} 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{2908,,errno.EACCES}/@ref{10f9,,PermissionError}), do not propagate the
exception.


Άλλαξε στην έκδοση 3.4: No longer raises @ref{59a,,NotImplementedError} when called.

@end deffn

@geindex get_code() (μέθοδος της importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader get_code}@anchor{4de5}
@deffn {Μέθοδος} get_code (fullname)

Concrete implementation of @ref{12ff,,InspectLoader.get_code()}.
@end deffn

@geindex exec_module() (μέθοδος της importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader exec_module}@anchor{13bc}
@deffn {Μέθοδος} exec_module (module)

Concrete implementation of @ref{c40,,Loader.exec_module()}.


Added in version 3.4.

@end deffn

@geindex get_source() (μέθοδος της importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader get_source}@anchor{13ca}
@deffn {Μέθοδος} get_source (fullname)

Concrete implementation of @ref{1302,,InspectLoader.get_source()}.
@end deffn

@geindex is_package() (μέθοδος της importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader is_package}@anchor{4de6}
@deffn {Μέθοδος} is_package (fullname)

Concrete implementation of @ref{4ddd,,InspectLoader.is_package()}. A module
is determined to be a package if its file path (as provided by
@ref{4ddf,,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

@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{4de7}@anchor{library/importlib module-importlib machinery}@anchor{7c}
@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/main/Lib/importlib/machinery.py}


__________________________________________________________________


This module contains the various objects that help @ref{9da,,import}
find and load modules.

@geindex SOURCE_SUFFIXES (στη μονάδα importlib.machinery)
@anchor{library/importlib importlib machinery SOURCE_SUFFIXES}@anchor{923}
@deffn {Δεδομένα} importlib.machinery.SOURCE_SUFFIXES

A list of strings representing the recognized file suffixes for source
modules.


Added in version 3.3.

@end deffn

@geindex DEBUG_BYTECODE_SUFFIXES (στη μονάδα importlib.machinery)
@anchor{library/importlib importlib machinery DEBUG_BYTECODE_SUFFIXES}@anchor{1ad1}
@deffn {Δεδομένα} importlib.machinery.DEBUG_BYTECODE_SUFFIXES

A list of strings representing the file suffixes for non-optimized bytecode
modules.


Added in version 3.3.



Αποσύρθηκε στην έκδοση 3.5: Use @ref{925,,BYTECODE_SUFFIXES} instead.

@end deffn

@geindex OPTIMIZED_BYTECODE_SUFFIXES (στη μονάδα importlib.machinery)
@anchor{library/importlib importlib machinery OPTIMIZED_BYTECODE_SUFFIXES}@anchor{1ad2}
@deffn {Δεδομένα} importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES

A list of strings representing the file suffixes for optimized bytecode
modules.


Added in version 3.3.



Αποσύρθηκε στην έκδοση 3.5: Use @ref{925,,BYTECODE_SUFFIXES} instead.

@end deffn

@geindex BYTECODE_SUFFIXES (στη μονάδα importlib.machinery)
@anchor{library/importlib importlib machinery BYTECODE_SUFFIXES}@anchor{925}
@deffn {Δεδομένα} importlib.machinery.BYTECODE_SUFFIXES

A list of strings representing the recognized file suffixes for bytecode
modules (including the leading dot).


Added in version 3.3.



Άλλαξε στην έκδοση 3.5: The value is no longer dependent on @code{__debug__}.

@end deffn

@geindex EXTENSION_SUFFIXES (στη μονάδα importlib.machinery)
@anchor{library/importlib importlib machinery EXTENSION_SUFFIXES}@anchor{924}
@deffn {Δεδομένα} importlib.machinery.EXTENSION_SUFFIXES

A list of strings representing the recognized file suffixes for
extension modules.


Added in version 3.3.

@end deffn

@geindex all_suffixes() (στη μονάδα importlib.machinery)
@anchor{library/importlib importlib machinery all_suffixes}@anchor{4cf8}
@deffn {Συνάρτηση} 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{10f0,,inspect.getmodulename()}).


Added in version 3.3.

@end deffn

@geindex BuiltinImporter (κλάση σε importlib.machinery)
@anchor{library/importlib importlib machinery BuiltinImporter}@anchor{1070}
@deffn {Κλάση} importlib.machinery.BuiltinImporter

An @ref{263f,,importer} for built-in modules. All known built-in modules are
listed in @ref{2236,,sys.builtin_module_names}. This class implements the
@ref{c44,,importlib.abc.MetaPathFinder} and
@ref{12fe,,importlib.abc.InspectLoader} ABCs.

Only class methods are defined by this class to alleviate the need for
instantiation.


Άλλαξε στην έκδοση 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 (κλάση σε importlib.machinery)
@anchor{library/importlib importlib machinery FrozenImporter}@anchor{13c8}
@deffn {Κλάση} importlib.machinery.FrozenImporter

An @ref{263f,,importer} for frozen modules. This class implements the
@ref{c44,,importlib.abc.MetaPathFinder} and
@ref{12fe,,importlib.abc.InspectLoader} ABCs.

Only class methods are defined by this class to alleviate the need for
instantiation.


Άλλαξε στην έκδοση 3.4: Gained @code{create_module()} and @code{exec_module()}
methods.

@end deffn

@geindex WindowsRegistryFinder (κλάση σε importlib.machinery)
@anchor{library/importlib importlib machinery WindowsRegistryFinder}@anchor{10e2}
@deffn {Κλάση} importlib.machinery.WindowsRegistryFinder

@ref{263e,,Finder} for modules declared in the Windows registry.  This class
implements the @ref{c44,,importlib.abc.MetaPathFinder} ABC.

Only class methods are defined by this class to alleviate the need for
instantiation.


Added in version 3.3.



Αποσύρθηκε στην έκδοση 3.6: Use @ref{cf,,site} configuration instead. Future versions of Python may
not enable this finder by default.

@end deffn

@geindex PathFinder (κλάση σε importlib.machinery)
@anchor{library/importlib importlib machinery PathFinder}@anchor{13cc}
@deffn {Κλάση} importlib.machinery.PathFinder

A @ref{263e,,Finder} for @ref{194,,sys.path} and package @code{__path__} attributes.
This class implements the @ref{c44,,importlib.abc.MetaPathFinder} ABC.

Only class methods are defined by this class to alleviate the need for
instantiation.

@geindex find_spec() (μέθοδος κλάσης της importlib.machinery.PathFinder)
@anchor{library/importlib importlib machinery PathFinder find_spec}@anchor{13ba}
@deffn {Μέθοδος} classmethod find_spec (fullname, path=None, target=None)

Class method that attempts to find a @ref{2554,,spec}
for the module specified by `fullname' on @ref{194,,sys.path} or, if
defined, on `path'. For each path entry that is searched,
@ref{9db,,sys.path_importer_cache} is checked. If a non-false object
is found then it is used as the @ref{1419,,path entry finder} to look
for the module being searched for. If no entry is found in
@code{sys.path_importer_cache}, then @ref{13cd,,sys.path_hooks} is
searched for a finder for the path entry and, if found, is stored
in @code{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.


Added in version 3.4.



Άλλαξε στην έκδοση 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{9db,,sys.path_importer_cache}.

@end deffn

@geindex invalidate_caches() (μέθοδος κλάσης της importlib.machinery.PathFinder)
@anchor{library/importlib importlib machinery PathFinder invalidate_caches}@anchor{fce}
@deffn {Μέθοδος} classmethod invalidate_caches ()

Calls @ref{4ddb,,importlib.abc.PathEntryFinder.invalidate_caches()} on all
finders stored in @ref{9db,,sys.path_importer_cache} that define the method.
Otherwise entries in @code{sys.path_importer_cache} set to @code{None} are
deleted.


Άλλαξε στην έκδοση 3.7: Entries of @code{None} in @ref{9db,,sys.path_importer_cache} are deleted.

@end deffn


Άλλαξε στην έκδοση 3.4: Calls objects in @ref{13cd,,sys.path_hooks} with the current working
directory for @code{'@w{'}} (i.e. the empty string).

@end deffn

@geindex FileFinder (κλάση σε importlib.machinery)
@anchor{library/importlib importlib machinery FileFinder}@anchor{141a}
@deffn {Κλάση} importlib.machinery.FileFinder (path, *loader_details)

A concrete implementation of @ref{c45,,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{fcf,,importlib.invalidate_caches()}.


Added in version 3.3.


@geindex path (ιδιότητα της importlib.machinery.FileFinder)
@anchor{library/importlib importlib machinery FileFinder path}@anchor{4de8}
@deffn {Ιδιότητα} path

The path the finder will search in.
@end deffn

@geindex find_spec() (μέθοδος της importlib.machinery.FileFinder)
@anchor{library/importlib importlib machinery FileFinder find_spec}@anchor{1274}
@deffn {Μέθοδος} find_spec (fullname, target=None)

Attempt to find the spec to handle `fullname' within @ref{4de8,,path}.


Added in version 3.4.

@end deffn

@geindex invalidate_caches() (μέθοδος της importlib.machinery.FileFinder)
@anchor{library/importlib importlib machinery FileFinder invalidate_caches}@anchor{4de9}
@deffn {Μέθοδος} invalidate_caches ()

Clear out the internal cache.
@end deffn

@geindex path_hook() (μέθοδος κλάσης της importlib.machinery.FileFinder)
@anchor{library/importlib importlib machinery FileFinder path_hook}@anchor{4dea}
@deffn {Μέθοδος} classmethod path_hook (*loader_details)

A class method which returns a closure for use on @ref{13cd,,sys.path_hooks}.
An instance of @code{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{1bd,,ImportError} is raised.
@end deffn
@end deffn

@geindex NamespacePath (κλάση σε importlib.machinery)
@anchor{library/importlib importlib machinery NamespacePath}@anchor{19d1}
@deffn {Κλάση} importlib.machinery.NamespacePath (name, path, path_finder)

Represents a @ref{52e,,namespace package}’s path (@ref{2243,,module.__path__}).

When its @code{__path__} value is accessed it will be recomputed if necessary.
This keeps it in-sync with the global state (@ref{19ba,,sys.modules}).

The `name' argument is the name of the namespace module.

The `path' argument is the initial path value.

The `path_finder' argument is the callable used to recompute the path value.
The callable has the same signature as @ref{c3f,,importlib.abc.MetaPathFinder.find_spec()}.

When the parent’s @ref{2243,,module.__path__} attribute is updated, the path
value is recomputed.

If the parent module is missing from @ref{19ba,,sys.modules}, then
@ref{1be,,ModuleNotFoundError} will be raised.

For top-level modules, the parent module’s path is @ref{194,,sys.path}.

@cartouche
@quotation Σημείωση 
@ref{fce,,PathFinder.invalidate_caches()} invalidates @code{NamespacePath},
forcing the path value to be recomputed next time it is accessed.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn

@geindex SourceFileLoader (κλάση σε importlib.machinery)
@anchor{library/importlib importlib machinery SourceFileLoader}@anchor{141c}
@deffn {Κλάση} importlib.machinery.SourceFileLoader (fullname, path)

A concrete implementation of @ref{4de3,,importlib.abc.SourceLoader} by
subclassing @ref{141b,,importlib.abc.FileLoader} and providing some concrete
implementations of other methods.


Added in version 3.3.



Άλλαξε στην έκδοση 3.15: Removed the @code{load_module()} method.


@geindex name (ιδιότητα της importlib.machinery.SourceFileLoader)
@anchor{library/importlib importlib machinery SourceFileLoader name}@anchor{4deb}
@deffn {Ιδιότητα} name

The name of the module that this loader will handle.
@end deffn

@geindex path (ιδιότητα της importlib.machinery.SourceFileLoader)
@anchor{library/importlib importlib machinery SourceFileLoader path}@anchor{4dec}
@deffn {Ιδιότητα} path

The path to the source file.
@end deffn

@geindex is_package() (μέθοδος της importlib.machinery.SourceFileLoader)
@anchor{library/importlib importlib machinery SourceFileLoader is_package}@anchor{4ded}
@deffn {Μέθοδος} is_package (fullname)

Return @code{True} if @ref{4dec,,path} appears to be for a package.
@end deffn

@geindex path_stats() (μέθοδος της importlib.machinery.SourceFileLoader)
@anchor{library/importlib importlib machinery SourceFileLoader path_stats}@anchor{4dee}
@deffn {Μέθοδος} path_stats (path)

Concrete implementation of @ref{1533,,importlib.abc.SourceLoader.path_stats()}.
@end deffn

@geindex set_data() (μέθοδος της importlib.machinery.SourceFileLoader)
@anchor{library/importlib importlib machinery SourceFileLoader set_data}@anchor{4def}
@deffn {Μέθοδος} set_data (path, data)

Concrete implementation of @ref{4de4,,importlib.abc.SourceLoader.set_data()}.
@end deffn
@end deffn

@geindex SourcelessFileLoader (κλάση σε importlib.machinery)
@anchor{library/importlib importlib machinery SourcelessFileLoader}@anchor{141d}
@deffn {Κλάση} importlib.machinery.SourcelessFileLoader (fullname, path)

A concrete implementation of @ref{141b,,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.


Added in version 3.3.



Άλλαξε στην έκδοση 3.15: Removed the @code{load_module()} method.


@geindex name (ιδιότητα της importlib.machinery.SourcelessFileLoader)
@anchor{library/importlib importlib machinery SourcelessFileLoader name}@anchor{4df0}
@deffn {Ιδιότητα} name

The name of the module the loader will handle.
@end deffn

@geindex path (ιδιότητα της importlib.machinery.SourcelessFileLoader)
@anchor{library/importlib importlib machinery SourcelessFileLoader path}@anchor{4df1}
@deffn {Ιδιότητα} path

The path to the bytecode file.
@end deffn

@geindex is_package() (μέθοδος της importlib.machinery.SourcelessFileLoader)
@anchor{library/importlib importlib machinery SourcelessFileLoader is_package}@anchor{4df2}
@deffn {Μέθοδος} is_package (fullname)

Determines if the module is a package based on @ref{4df1,,path}.
@end deffn

@geindex get_code() (μέθοδος της importlib.machinery.SourcelessFileLoader)
@anchor{library/importlib importlib machinery SourcelessFileLoader get_code}@anchor{4df3}
@deffn {Μέθοδος} get_code (fullname)

Returns the code object for @ref{4df0,,name} created from @ref{4df1,,path}.
@end deffn

@geindex get_source() (μέθοδος της importlib.machinery.SourcelessFileLoader)
@anchor{library/importlib importlib machinery SourcelessFileLoader get_source}@anchor{4df4}
@deffn {Μέθοδος} get_source (fullname)

Returns @code{None} as bytecode files have no source when this loader is
used.
@end deffn
@end deffn

@geindex ExtensionFileLoader (κλάση σε importlib.machinery)
@anchor{library/importlib importlib machinery ExtensionFileLoader}@anchor{1071}
@deffn {Κλάση} importlib.machinery.ExtensionFileLoader (fullname, path)

A concrete implementation of @ref{4dde,,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.


Added in version 3.3.



Άλλαξε στην έκδοση 3.12: Multi-phase init is now required for use in subinterpreters.


@geindex name (ιδιότητα της importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader name}@anchor{4df5}
@deffn {Ιδιότητα} name

Name of the module the loader supports.
@end deffn

@geindex path (ιδιότητα της importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader path}@anchor{4df6}
@deffn {Ιδιότητα} path

Path to the extension module.
@end deffn

@geindex create_module() (μέθοδος της importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader create_module}@anchor{4df7}
@deffn {Μέθοδος} 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/}.


Added in version 3.5.

@end deffn

@geindex exec_module() (μέθοδος της importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader exec_module}@anchor{4df8}
@deffn {Μέθοδος} 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/}.


Added in version 3.5.

@end deffn

@geindex is_package() (μέθοδος της importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader is_package}@anchor{4df9}
@deffn {Μέθοδος} is_package (fullname)

Returns @code{True} if the file path points to a package’s @code{__init__}
module based on @ref{924,,EXTENSION_SUFFIXES}.
@end deffn

@geindex get_code() (μέθοδος της importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader get_code}@anchor{4dfa}
@deffn {Μέθοδος} get_code (fullname)

Returns @code{None} as extension modules lack a code object.
@end deffn

@geindex get_source() (μέθοδος της importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader get_source}@anchor{4dfb}
@deffn {Μέθοδος} get_source (fullname)

Returns @code{None} as extension modules do not have source code.
@end deffn

@geindex get_filename() (μέθοδος της importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader get_filename}@anchor{1303}
@deffn {Μέθοδος} get_filename (fullname)

Returns @ref{4df6,,path}.


Added in version 3.4.

@end deffn
@end deffn

@geindex NamespaceLoader (κλάση σε importlib.machinery)
@anchor{library/importlib importlib machinery NamespaceLoader}@anchor{1300}
@deffn {Κλάση} importlib.machinery.NamespaceLoader (name, path, path_finder)

A concrete implementation of @ref{12fe,,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


Added in version 3.11.

@end deffn

@geindex ModuleSpec (κλάση σε importlib.machinery)
@anchor{library/importlib importlib machinery ModuleSpec}@anchor{245d}
@deffn {Κλάση} 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{2555,,__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{255a,,__file__} at runtime and this will not be
automatically reflected in the module’s
@ref{4dfc,,__spec__.origin}, and vice versa.


Added in version 3.4.


@geindex name (ιδιότητα της importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec name}@anchor{2556}
@deffn {Ιδιότητα} name

The module’s fully qualified name (see @ref{172f,,module.__name__}).
The @ref{263e,,finder} should always set this attribute to a non-empty string.
@end deffn

@geindex loader (ιδιότητα της importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec loader}@anchor{300}
@deffn {Ιδιότητα} loader

The @ref{1c30,,loader} used to load the module (see @ref{2ff,,module.__loader__}).
The @ref{263e,,finder} should always set this attribute.
@end deffn

@geindex origin (ιδιότητα της importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec origin}@anchor{4dfc}
@deffn {Ιδιότητα} origin

The location the @ref{1c30,,loader} should use to load the module
(see @ref{255a,,module.__file__}).
For example, for modules loaded from a @code{.py} file this is the filename.
The @ref{263e,,finder} should always set this attribute to a meaningful value
for the 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 (ιδιότητα της importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec submodule_search_locations}@anchor{2559}
@deffn {Ιδιότητα} submodule_search_locations

A (possibly empty) @ref{8ff,,sequence} of strings enumerating the locations
in which a package’s submodules will be found
(see @ref{2243,,module.__path__}). Most of the time there will only be a
single directory in this list.

The @ref{263e,,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 (ιδιότητα της importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec loader_state}@anchor{4dfd}
@deffn {Ιδιότητα} loader_state

The @ref{263e,,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 (ιδιότητα της importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec cached}@anchor{58b}
@deffn {Ιδιότητα} cached

The filename of a compiled version of the module’s code.
The @ref{263e,,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 (ιδιότητα της importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec parent}@anchor{58d}
@deffn {Ιδιότητα} 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{58c,,module.__package__}.
If the module is a package then this is the same as @ref{2556,,name}.
@end deffn

@geindex has_location (ιδιότητα της importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec has_location}@anchor{4dfe}
@deffn {Ιδιότητα} has_location

@code{True} if the spec’s @ref{4dfc,,origin} refers to a loadable location,
@code{False} otherwise.  This value impacts how @code{origin} is interpreted
and how the module’s @ref{255a,,__file__} is populated.
@end deffn
@end deffn

@geindex AppleFrameworkLoader (κλάση σε importlib.machinery)
@anchor{library/importlib importlib machinery AppleFrameworkLoader}@anchor{245c}
@deffn {Κλάση} importlib.machinery.AppleFrameworkLoader (name, path)

A specialization of @ref{1071,,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 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 traversal.
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.


Added in version 3.13.


@ref{232d,,Διαθεσιμότητα}: iOS.

@geindex name (ιδιότητα της importlib.machinery.AppleFrameworkLoader)
@anchor{library/importlib importlib machinery AppleFrameworkLoader name}@anchor{4dff}
@deffn {Ιδιότητα} name

Name of the module the loader supports.
@end deffn

@geindex path (ιδιότητα της importlib.machinery.AppleFrameworkLoader)
@anchor{library/importlib importlib machinery AppleFrameworkLoader path}@anchor{4e00}
@deffn {Ιδιότητα} path

Path to the @code{.fwork} file for the extension module.
@end deffn
@end deffn

@node importlib util – Utility code for importers,Examples<29>,importlib machinery – Importers and path hooks,importlib — The implementation of import
@anchor{library/importlib importlib-util-utility-code-for-importers}@anchor{4e01}@anchor{library/importlib module-importlib util}@anchor{80}
@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/main/Lib/importlib/util.py}


__________________________________________________________________


This module contains the various objects that help in the construction of
an @ref{263f,,importer}.

@geindex MAGIC_NUMBER (στη μονάδα importlib.util)
@anchor{library/importlib importlib util MAGIC_NUMBER}@anchor{922}
@deffn {Δεδομένα} importlib.util.MAGIC_NUMBER

The bytes which represent the bytecode version number. If you need help with
loading/writing bytecode then consider @ref{4de3,,importlib.abc.SourceLoader}.


Added in version 3.4.

@end deffn

@geindex cache_from_source() (στη μονάδα importlib.util)
@anchor{library/importlib importlib util cache_from_source}@anchor{330}
@deffn {Συνάρτηση} importlib.util.cache_from_source (path, *, 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{59a,,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{277,,ValueError} is raised.


Added in version 3.4.



Άλλαξε στην έκδοση 3.5: The `optimization' parameter was added and the `debug_override' parameter
was deprecated.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.15: The `debug_override' parameter was removed.

@end deffn

@geindex source_from_cache() (στη μονάδα importlib.util)
@anchor{library/importlib importlib util source_from_cache}@anchor{929}
@deffn {Συνάρτηση} 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{277,,ValueError} is raised. If
@code{sys.implementation.cache_tag} is not defined,
@ref{59a,,NotImplementedError} is raised.


Added in version 3.4.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex decode_source() (στη μονάδα importlib.util)
@anchor{library/importlib importlib util decode_source}@anchor{1301}
@deffn {Συνάρτηση} 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{1302,,importlib.abc.InspectLoader.get_source()}).


Added in version 3.4.

@end deffn

@geindex resolve_name() (στη μονάδα importlib.util)
@anchor{library/importlib importlib util resolve_name}@anchor{cd9}
@deffn {Συνάρτηση} 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{1bd,,ImportError} is raised if `name' is a relative module name but
`package' is a false value (e.g. @code{None} or the empty string).
@code{ImportError} is also raised if a relative name would escape its
containing package (e.g. requesting @code{..bacon} from within the @code{spam}
package).


Added in version 3.3.



Άλλαξε στην έκδοση 3.9: To improve consistency with import statements, raise
@ref{1bd,,ImportError} instead of @ref{277,,ValueError} for invalid relative
import attempts.

@end deffn

@geindex find_spec() (στη μονάδα importlib.util)
@anchor{library/importlib importlib util find_spec}@anchor{7a7}
@deffn {Συνάρτηση} importlib.util.find_spec (name, package=None)

Find the @ref{2554,,spec} for a module, optionally relative to
the specified `package' name. If the module is in @ref{19ba,,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{277,,ValueError} is raised).
Otherwise a search using @ref{10e3,,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()}.


Added in version 3.4.



Άλλαξε στην έκδοση 3.7: Raises @ref{1be,,ModuleNotFoundError} instead of @ref{1a9,,AttributeError} if
`package' is in fact not a package (i.e. lacks a
@ref{2243,,__path__} attribute).

@end deffn

@geindex module_from_spec() (στη μονάδα importlib.util)
@anchor{library/importlib importlib util module_from_spec}@anchor{11c6}
@deffn {Συνάρτηση} importlib.util.module_from_spec (spec)

Create a new module based on `spec' and
@ref{106f,,spec.loader.create_module}.

If @ref{106f,,spec.loader.create_module}
does not return @code{None}, then any pre-existing attributes will not be reset.
Also, no @ref{1a9,,AttributeError} will be raised if triggered while accessing
`spec' or setting an attribute on the module.

This function is preferred over using @ref{11c7,,types.ModuleType} to create a
new module as `spec' is used to set as many import-controlled attributes on
the module as possible.


Added in version 3.5.

@end deffn

@geindex spec_from_loader() (στη μονάδα importlib.util)
@anchor{library/importlib importlib util spec_from_loader}@anchor{c43}
@deffn {Συνάρτηση} importlib.util.spec_from_loader (name, loader, *, origin=None, is_package=None)

A factory function for creating a @ref{245d,,ModuleSpec}
instance based on a loader.  The parameters have the same meaning as they do
for ModuleSpec.  The function uses available @ref{1c30,,loader} APIs, such as
@code{InspectLoader.is_package()}, to fill in any missing
information on the spec.


Added in version 3.4.

@end deffn

@geindex spec_from_file_location() (στη μονάδα importlib.util)
@anchor{library/importlib importlib util spec_from_file_location}@anchor{1072}
@deffn {Συνάρτηση} importlib.util.spec_from_file_location (name, location, *, loader=None, submodule_search_locations=None)

A factory function for creating a @ref{245d,,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.


Added in version 3.4.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex source_hash() (στη μονάδα importlib.util)
@anchor{library/importlib importlib util source_hash}@anchor{f04}
@deffn {Συνάρτηση} importlib.util.source_hash (source_bytes)

Return the hash of `source_bytes' as bytes. A hash-based @code{.pyc} file embeds
the @code{source_hash()} of the corresponding source file’s contents in its
header.


Added in version 3.7.

@end deffn

@geindex _incompatible_extension_module_restrictions() (στη μονάδα importlib.util)
@anchor{library/importlib importlib util _incompatible_extension_module_restrictions}@anchor{4e02}
@deffn {Συνάρτηση} 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 Προειδοποίηση 
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


Added in version 3.12.

@end deffn

@geindex LazyLoader (κλάση σε importlib.util)
@anchor{library/importlib importlib util LazyLoader}@anchor{106e}
@deffn {Κλάση} 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{c40,,exec_module()} as control over what module type
is used for the module is required. For those same reasons, the loader’s
@ref{106f,,create_module()} method must return @code{None} or a
type for which its @code{__class__} attribute can be mutated along with not
using @ref{9d9,,slots}. Finally, modules which substitute the object
placed into @ref{19ba,,sys.modules} will not work as there is no way to properly
replace the module references throughout the interpreter safely;
@ref{277,,ValueError} is raised if such a substitution is detected.

@cartouche
@quotation Σημείωση 
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


Added in version 3.5.



Άλλαξε στην έκδοση 3.6: Began calling @ref{106f,,create_module()}, removing the
compatibility warning for @ref{1070,,importlib.machinery.BuiltinImporter} and
@ref{1071,,importlib.machinery.ExtensionFileLoader}.


@geindex factory() (μέθοδος κλάσης της importlib.util.LazyLoader)
@anchor{library/importlib importlib util LazyLoader factory}@anchor{4e03}
@deffn {Μέθοδος} 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 Examples<29>,,importlib util – Utility code for importers,importlib — The implementation of import
@anchor{library/importlib examples}@anchor{4e04}@anchor{library/importlib importlib-examples}@anchor{4e05}
@subsubsection Examples


@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,,Examples<29>
@anchor{library/importlib importing-programmatically}@anchor{4e06}
@subsubsection Importing programmatically


To programmatically import a module, use @ref{927,,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,Examples<29>
@anchor{library/importlib checking-if-a-module-can-be-imported}@anchor{4e07}
@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{7a7,,importlib.util.find_spec()}.

Note that if @code{name} is a submodule (contains a dot),
@ref{7a7,,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,Examples<29>
@anchor{library/importlib importing-a-source-file-directly}@anchor{4e08}
@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{194,,sys.path} being searched. Alternatives should first be considered first,
such as modifying @code{sys.path} when a proper module is required, or using
@ref{6ae,,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,Examples<29>
@anchor{library/importlib implementing-lazy-imports}@anchor{4e09}
@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,Examples<29>
@anchor{library/importlib setting-up-an-importer}@anchor{4e0a}
@subsubsection Setting up an importer


For deep customizations of import, you typically want to implement an
@ref{263f,,importer}. This means managing both the @ref{263e,,finder} and @ref{1c30,,loader}
side of things. For finders there are two flavours to choose from depending on
your needs: a @ref{1418,,meta path finder} or a @ref{1419,,path entry finder}. The
former is what you would put on @ref{10e3,,sys.meta_path} while the latter is what
you create using a @ref{2650,,path entry hook} on @ref{13cd,,sys.path_hooks} which works
with @ref{194,,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,Examples<29>
@anchor{library/importlib approximating-importlib-import-module}@anchor{4e0b}
@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{927,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node importlib resources – Ανάγνωση άνοιγμα και πρόσβαση σε πόρους πακέτων,importlib resources abc – Abstract base classes for resources,importlib — The implementation of import,Importing Modules
@anchor{library/importlib resources doc}@anchor{4e0c}@anchor{library/importlib resources importlib-resources-package-resource-reading-opening-and-access}@anchor{4e0d}@anchor{library/importlib resources module-importlib resources}@anchor{7e}@anchor{library/importlib resources translation-repo}@anchor{4e0e}
@subsection @code{importlib.resources} – Ανάγνωση, άνοιγμα και πρόσβαση σε πόρους πακέτων


@geindex module; importlib.resources

`Πηγαίος κώδικας:' Lib/importlib/resources/__init__.py@footnote{https://github.com/python/cpython/tree/main/Lib/importlib/resources/__init__.py}


__________________________________________________________________



Added in version 3.7.


Αυτό το module αξιοποιεί το σύστημα εισαγωγής της Python για να παρέχει πρόσβαση σε `πόρους' εντός `πακέτων'.

«Πόροι» είναι πόροι που μοιάζουν με αρχεία και σχετίζονται με ένα module ή πακέτο στην Python. Οι πόροι μπορεί να περιέχονται απευθείας σε ένα πακέτο, μέσα σε έναν υποκατάλογο που περιλαμβάνεται σε αυτό το πακέτο, ή δίπλα σε modules έξω από ένα πακέτο. Οι πόροι μπορεί να είναι μορφής κειμένου ή δυαδικής μορφής. Ως αποτέλεσμα, ο πηγαίος κώδικας των modules της Python (.py) ενός πακέτου και τα αποτελέσματα μεταγλώττισης (pycache) και τα αποτελέσματα εγκατάστασης (όπως @ref{2d9,,reserved filenames} σε καταλόγους) είναι τεχνικά de-facto πόροι αυτού του πακέτου. Ωστόσο, στην πράξη, οι πόροι είναι κυρίως εκείνα τα μη-Python αρχεία που εκτίθενται συγκεκριμένα από τον συγγραφέα του πακέτου.

Οι πόροι μπορούν να ανοίξουν ή να διαβαστούν είτε σε δυαδική κατάσταση είτε σε κατάσταση κειμένου.

Οι πόροι είναι κατά κάποιο τρόπο ανάλογοι με αρχεία μέσα σε καταλόγους, αν και είναι σημαντικό να θυμόμαστε ότι αυτή είναι απλώς μια μεταφορά. Οι πόροι και τα πακέτα `δεν' χρειάζεται να υπάρχουν ως φυσικά αρχεία και κατάλογοι στο σύστημα αρχείων: για παράδειγμα, ένα πακέτο και οι πόροι του μπορούν να εισαχθούν από ένα αρχείο zip χρησιμοποιώντας το @ref{13b,,zipimport}.

@cartouche
@quotation Προειδοποίηση 
@code{importlib.resources} follows the same security model as the built-in
@ref{32b,,open()} function. Passing untrusted inputs to the functions
in this module is unsafe.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Το αυτόνομο backport αυτού του module παρέχει περισσότερες πληροφορίες στα using importlib.resources@footnote{https://importlib-resources.readthedocs.io/en/latest/using.html} και migrating from pkg_resources to importlib.resources@footnote{https://importlib-resources.readthedocs.io/en/latest/migration.html}.
@end quotation
@end cartouche

Οι @ref{1275,,Loaders} που επιθυμούν να υποστηρίξουν ανάγνωση πόρων θα πρέπει να υλοποιήσουν μια μέθοδο @code{get_resource_reader(fullname)} όπως ορίζεται από την κλάση @ref{4ddc,,importlib.resources.abc.ResourceReader}.

@geindex Anchor (κλάση σε importlib.resources)
@anchor{library/importlib resources importlib resources Anchor}@anchor{4e0f}
@deffn {Κλάση} importlib.resources.Anchor

Αντιπροσωπεύει μία άγκυρα (anchor) για πόρους, είτε ένα @ref{11c7,,module object} είτε ένα όνομα module ως συμβολοσειρά. Ορίζεται ως @code{Union[str, ModuleType]}.
@end deffn

@geindex files() (στη μονάδα importlib.resources)
@anchor{library/importlib resources importlib resources files}@anchor{2d7}
@deffn {Συνάρτηση} importlib.resources.files (anchor: Anchor | None = None)

Επιστρέφει ένα αντικείμενο @ref{572,,Traversable} που αντιπροσωπεύει το δοχείο των πόρων (σκεφτείτε έναν κατάλογο) και τους πόρους του (σκεφτείτε αρχεία). Ένα Traversable μπορεί να περιέχει και άλλα δοχεία (σκεφτείτε υποκαταλόγους).

Το `anchor' είναι μια προαιρετική κλάση @ref{4e0f,,Anchor}. Αν το anchor είναι πακέτο, οι πόροι επιλύονται σε αυτό το πακέτο. Αν είναι module, οι πόροι επιλύονται δίπλα σε αυτό το module (στο ίδιο πακέτο ή στη ρίζα του πακέτου). Αν το anchor παραλειφθεί, χρησιμοποιείται το module του καλούντος.


Added in version 3.9.



Άλλαξε στην έκδοση 3.12: `package' parameter was renamed to `anchor'.
`package' was still accepted, but deprecated.



Άλλαξε στην έκδοση 3.15: `package' parameter was fully removed. `anchor' can now be a
non-package module and if omitted will default to the caller’s module.
`package' is no longer accepted since Python 3.15. Consider passing the
anchor positionally or using @code{importlib_resources >= 5.10} for a
compatible interface on older Pythons.

@end deffn

@geindex as_file() (στη μονάδα importlib.resources)
@anchor{library/importlib resources importlib resources as_file}@anchor{89f}
@deffn {Συνάρτηση} importlib.resources.as_file (traversable)

Δεδομένου ενός αντικειμένου @ref{572,,Traversable} που αντιπροσωπεύει ένα αρχείο ή κατάλογο, συνήθως από το @ref{2d7,,importlib.resources.files()}, επιστρέφει ένα context manager για χρήση σε μια @ref{20a,,with} πρόταση. Ο context manager παρέχει ένα αντικείμενο @ref{4ee,,pathlib.Path}.

Η έξοδος από τον context manager καθαρίζει οποιοδήποτε προσωρινό αρχείο ή κατάλογο που δημιουργήθηκε όταν ο πόρος εξήχθη, π.χ. από ένα αρχείο zip.

Χρησιμοποιήστε το @code{as_file} όταν οι μέθοδοι του Traversable (όπως @code{read_text}, κλπ) δεν επαρκούν και απαιτείται ένα πραγματικό αρχείο ή κατάλογος στο σύστημα αρχείων.


Added in version 3.9.



Άλλαξε στην έκδοση 3.12: Προστέθηκε υποστήριξη για `traversable' που αντιπροσωπεύει έναν κατάλογο.

@end deffn

@menu
* Λειτουργικό API:: 

@end menu

@node Λειτουργικό API,,,importlib resources – Ανάγνωση άνοιγμα και πρόσβαση σε πόρους πακέτων
@anchor{library/importlib resources functional-api}@anchor{4e10}@anchor{library/importlib resources importlib-resources-functional}@anchor{4e11}
@subsubsection Λειτουργικό API


Ένα σύνολο απλοποιημένων, βοηθών συμβατών με προηγούμενες εκδόσεις είναι διαθέσιμο. Αυτά επιτρέπουν κοινές λειτουργίες σε μια κλήση συνάρτησης.

Για όλες τις παρακάτω λειτουργίες:


@itemize -

@item 
Το `anchor' είναι μια @ref{4e0f,,Anchor}, όπως στη @ref{2d7,,files()}. Σε αντίθεση με τα @code{αρχεία}, ενδέχεται να μην παραλειφθεί.

@item 
Τα `path_names' είναι στοιχεία του ονόματος διαδρομής ενός πόρου, σε σχέση με το anchor. Για παράδειγμα, για να λάβετε το κείμενο του πόρου με το όνομα @code{info.txt}, χρησιμοποιήστε:

@example
importlib.resources.read_text(my_module, "info.txt")
@end example

Όπως @ref{572,,Traversable.joinpath}, Τα μεμονωμένα στοιχεία θα πρέπει να χρησιμοποιούν κάθετε (@code{/}) ως διαχωριστές διαδρομή. Για παράδειγμα, τα ακόλουθα είναι ισοδύναμα:

@example
importlib.resources.read_binary(my_module, "pics/painting.png")
importlib.resources.read_binary(my_module, "pics", "painting.png")
@end example

Για λόγους συμβατότητας προς τα πίσω, οι συναρτήσεις που διαβάζουν κείμενο απαιτούν ένα ρητό όρισμα `encoding' εάν δίνονται πολλά `path_names'. Για παράδειγμα, για να λάβετε το κείμενο του @code{info/chapter1.txt}, χρησιμοποιήστε:

@example
importlib.resources.read_text(my_module, "info", "chapter1.txt",
                              encoding='utf-8')
@end example
@end itemize

@geindex open_binary() (στη μονάδα importlib.resources)
@anchor{library/importlib resources importlib resources open_binary}@anchor{703}
@deffn {Συνάρτηση} importlib.resources.open_binary (anchor, *path_names)

Ανοίξτε τον πόρο με όνομα για δυαδική ανάγνωση.

Δείτε @ref{4e11,,the introduction} για λεπτομέρειες σχετικά με το `anchor' και `path_names'.

Αυτή η συνάρτηση επιστρέφει ένα αντικείμενο @ref{4c8,,BinaryIO}, ένα δυαδικό ρεύμα εισόδου για ανάγνωση.

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

@example
files(anchor).joinpath(*path_names).open('rb')
@end example


Άλλαξε στην έκδοση 3.13: Γίνονται αποδεκτά πολλά `path_names'.

@end deffn

@geindex open_text() (στη μονάδα importlib.resources)
@anchor{library/importlib resources importlib resources open_text}@anchor{704}
@deffn {Συνάρτηση} importlib.resources.open_text (anchor, *path_names, encoding='utf-8', errors='strict')

Ανοίγει τον δεδομένο πόρο για ανάγνωση κειμένου. Από προεπιλογή, τα περιεχόμενα διαβάζονται ως αυστηρά UTF-8.

Δείτε @ref{4e11,,the introduction} για λεπτομέρειες σχετικά με το `anchor' και το `path_names'. Τα `encoding' και `errors' έχουν την ίδια σημασία όπως στο ενσωματωμένο @ref{32b,,open()}.

Για λόγους συμβατότητας για προηγούμενες εκδόσεις, το όρισμα `encoding' πρέπει να δίνεται ρητά εάν υπάρχουν πολλά `path_names'. Αυτό ο περιορισμός έχει προγραμματιστεί να καταργηθεί στην Python 3.15.

Αυτή η συνάρτηση επιστρέφει ένα @ref{4c7,,TextIO} αντικείμενο, δηλαδή ένα ρεύμα εισόδου για ανάγνωση.

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

@example
files(anchor).joinpath(*path_names).open('r', encoding=encoding)
@end example


Άλλαξε στην έκδοση 3.13: Πολλαπλά `path_names' γίνονται δεκτά. Τα `encoding' και `errors' πρέπει να δίνονται ως ορίσματα λέξεων-κλειδιών.

@end deffn

@geindex read_binary() (στη μονάδα importlib.resources)
@anchor{library/importlib resources importlib resources read_binary}@anchor{706}
@deffn {Συνάρτηση} importlib.resources.read_binary (anchor, *path_names)

Διαβάζει και επιστρέφει τα περιεχόμενα του δεδομένου πόρου ως @ref{1c7,,bytes}.

Δείτε @ref{4e11,,the introduction} για λεπτομέρειες σχετικά με το `anchor' και `path_names'.

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

@example
files(anchor).joinpath(*path_names).read_bytes()
@end example


Άλλαξε στην έκδοση 3.13: Γίνονται αποδεκτά πολλά `path_names'.

@end deffn

@geindex read_text() (στη μονάδα importlib.resources)
@anchor{library/importlib resources importlib resources read_text}@anchor{707}
@deffn {Συνάρτηση} importlib.resources.read_text (anchor, *path_names, encoding='utf-8', errors='strict')

Διαβάζει και επιστρέφει τα περιεχόμενα του δεδομένου πόρου μέσα στο ως @ref{1df,,str}. Από προεπιλογή, τα περιεχόμενα διαβάζονται ως αυστηρό UTF-8.

Δείτε @ref{4e11,,the introduction} για λεπτομέρειες σχετικά με το `anchor' και το `path_names'. Τα `encoding' και `errors' έχουν την ίδια σημασία όπως στο ενσωματωμένο @ref{32b,,open()}.

Για λόγους συμβατότητας για προηγούμενες εκδόσεις, το όρισμα `encoding' πρέπει να δίνεται ρητά εάν υπάρχουν πολλά `path_names'. Αυτό ο περιορισμός έχει προγραμματιστεί να καταργηθεί στην Python 3.15.

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

@example
files(anchor).joinpath(*path_names).read_text(encoding=encoding)
@end example


Άλλαξε στην έκδοση 3.13: Πολλαπλά `path_names' γίνονται δεκτά. Τα `encoding' και `errors' πρέπει να δίνονται ως ορίσματα λέξεων-κλειδιών.

@end deffn

@geindex path() (στη μονάδα importlib.resources)
@anchor{library/importlib resources importlib resources path}@anchor{705}
@deffn {Συνάρτηση} importlib.resources.path (anchor, *path_names)

Παρέχει τη διαδρομή του `resource' ως πραγματική διαδρομή συστήματος αρχείων. Αυτή η συνάρτηση επιστρέφει ένα διαχειριστή περιεχομένου για χρήση σε μια @ref{20a,,with} πρόταση. Ο διαχειριστής περιεχομένου παρέχει ένα αντικείμενο @ref{4ee,,pathlib.Path}.

Η έξοδος από τον context manager καθαρίζει οποιοδήποτε προσωρινό αρχείο που δημιουργήθηκε, π.χ. όταν ο πόρος χρειάστηκε να εξαχθεί από ένα αρχείο zip.

Για παράδειγμα, η μέθοδος @ref{bfc,,stat()} απαιτεί μια πραγματική διαδρομή συστήματος αρχείων· μπορεί να χρησιμοποιηθεί ως εξής:

@example
with importlib.resources.path(anchor, "resource.txt") as fspath:
    result = fspath.stat()
@end example

Δείτε @ref{4e11,,the introduction} για λεπτομέρειες σχετικά με το `anchor' και `path_names'.

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

@example
as_file(files(anchor).joinpath(*path_names))
@end example


Άλλαξε στην έκδοση 3.13: Πολλαπλά `path_names' γίνονται δεκτά. Τα `encoding' και `errors' πρέπει να δίνονται ως ορίσματα λέξεων-κλειδιών.

@end deffn

@geindex is_resource() (στη μονάδα importlib.resources)
@anchor{library/importlib resources importlib resources is_resource}@anchor{702}
@deffn {Συνάρτηση} importlib.resources.is_resource (anchor, *path_names)

Επιστρέφετε @code{True} εάν υπάρχει ο δεδομένος πόρος, διαφορετικά @code{False}. Αυτή η συνάρτηση δεν θεωρεί τους καταλόγους ως πόρους.

Δείτε @ref{4e11,,the introduction} για λεπτομέρειες σχετικά με το `anchor' και `path_names'.

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

@example
files(anchor).joinpath(*path_names).is_file()
@end example


Άλλαξε στην έκδοση 3.13: Γίνονται αποδεκτά πολλά `path_names'.

@end deffn

@geindex contents() (στη μονάδα importlib.resources)
@anchor{library/importlib resources importlib resources contents}@anchor{708}
@deffn {Συνάρτηση} importlib.resources.contents (anchor, *path_names)

Επιστρέφει ένα iterable πάνω στα ονομασμένα στοιχεία μέσα στο πακέτο ή στη διαδρομή. Το iterable επιστρέφει τα ονόματα των πόρων (π.χ. αρχεία) και μη-πόρους (π.χ. καταλόγους) ως @ref{1df,,str}. Το iterable δεν επαναλαμβάνεται σε υποκαταλόγους.

Δείτε @ref{4e11,,the introduction} για λεπτομέρειες σχετικά με το `anchor' και `path_names'.

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

@example
for resource in files(anchor).joinpath(*path_names).iterdir():
    yield resource.name
@end example


Αποσύρθηκε στην έκδοση 3.11: Προτιμήστε το @code{iterdir()} όπως παραπάνω, το οποίο προσφέρει περισσότερο έλεγχο στα αποτελέσματα και πιο πλούσια λειτουργικότητα.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node importlib resources abc – Abstract base classes for resources,importlib metadata – Accessing package metadata,importlib resources – Ανάγνωση άνοιγμα και πρόσβαση σε πόρους πακέτων,Importing Modules
@anchor{library/importlib resources abc doc}@anchor{4e12}@anchor{library/importlib resources abc importlib-resources-abc-abstract-base-classes-for-resources}@anchor{4e13}@anchor{library/importlib resources abc module-importlib resources abc}@anchor{7f}@anchor{library/importlib resources abc translation-repo}@anchor{4e14}
@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/main/Lib/importlib/resources/abc.py}


__________________________________________________________________



Added in version 3.11.


@geindex ResourceReader (κλάση σε importlib.resources.abc)
@anchor{library/importlib resources abc importlib resources abc ResourceReader}@anchor{4ddc}
@deffn {Κλάση} importlib.resources.abc.ResourceReader

`Superseded by TraversableResources'

An @ref{155f,,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{79f,,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{a65,,None}. An object compatible with this ABC should only be
returned when the specified module is a package.


Αποσύρθηκε στην έκδοση 3.12: Use @ref{571,,importlib.resources.abc.TraversableResources} instead.


@geindex open_resource() (μέθοδος της importlib.resources.abc.ResourceReader)
@anchor{library/importlib resources abc importlib resources abc ResourceReader open_resource}@anchor{4e15}
@deffn {Μέθοδος} abstractmethod open_resource (resource)

Returns an opened, @ref{19b1,,file-like object} for binary reading
of the `resource'.

If the resource cannot be found, @ref{243,,FileNotFoundError} is
raised.
@end deffn

@geindex resource_path() (μέθοδος της importlib.resources.abc.ResourceReader)
@anchor{library/importlib resources abc importlib resources abc ResourceReader resource_path}@anchor{4e16}
@deffn {Μέθοδος} abstractmethod resource_path (resource)

Returns the file system path to the `resource'.

If the resource does not concretely exist on the file system,
raise @ref{243,,FileNotFoundError}.
@end deffn

@geindex is_resource() (μέθοδος της importlib.resources.abc.ResourceReader)
@anchor{library/importlib resources abc importlib resources abc ResourceReader is_resource}@anchor{4e17}
@deffn {Μέθοδος} abstractmethod is_resource (path)

Returns @code{True} if the named `path' is considered a resource.
@ref{243,,FileNotFoundError} is raised if `path' does not exist.


Άλλαξε στην έκδοση 3.10: The argument `name' was renamed to `path'.

@end deffn

@geindex contents() (μέθοδος της importlib.resources.abc.ResourceReader)
@anchor{library/importlib resources abc importlib resources abc ResourceReader contents}@anchor{4e18}
@deffn {Μέθοδος} abstractmethod contents ()

Returns an @ref{15ce,,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{4e17,,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 (κλάση σε importlib.resources.abc)
@anchor{library/importlib resources abc importlib resources abc Traversable}@anchor{572}
@deffn {Κλάση} importlib.resources.abc.Traversable

An object with a subset of @ref{4ee,,pathlib.Path} methods suitable for
traversing directories and opening files.

For a representation of the object on the file-system, use
@ref{89f,,importlib.resources.as_file()}.

@geindex name (ιδιότητα της importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable name}@anchor{4e19}
@deffn {Ιδιότητα} name

Abstract. The base name of this object without any parent references.
@end deffn

@geindex iterdir() (μέθοδος της importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable iterdir}@anchor{4e1a}
@deffn {Μέθοδος} abstractmethod iterdir ()

Yield Traversable objects in self.
@end deffn

@geindex is_dir() (μέθοδος της importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable is_dir}@anchor{4e1b}
@deffn {Μέθοδος} abstractmethod is_dir ()

Return @code{True} if self is a directory.
@end deffn

@geindex is_file() (μέθοδος της importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable is_file}@anchor{4e1c}
@deffn {Μέθοδος} abstractmethod is_file ()

Return @code{True} if self is a file.
@end deffn

@geindex joinpath() (μέθοδος της importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable joinpath}@anchor{4e1d}
@deffn {Μέθοδος} 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


Άλλαξε στην έκδοση 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__() (μέθοδος της importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable __truediv__}@anchor{4e1e}
@deffn {Μέθοδος} abstractmethod __truediv__ (child)

Return Traversable child in self.
Equivalent to @code{joinpath(child)}.
@end deffn

@geindex open() (μέθοδος της importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable open}@anchor{4e1f}
@deffn {Μέθοδος} 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{2e55,,pathlib.Path.open}).

When opening as text, accepts encoding parameters such as those
accepted by @ref{b9c,,io.TextIOWrapper}.
@end deffn

@geindex read_bytes() (μέθοδος της importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable read_bytes}@anchor{4e20}
@deffn {Μέθοδος} read_bytes ()

Read contents of self as bytes.
@end deffn

@geindex read_text() (μέθοδος της importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable read_text}@anchor{4e21}
@deffn {Μέθοδος} read_text (encoding=None)

Read contents of self as text.
@end deffn
@end deffn

@geindex TraversableResources (κλάση σε importlib.resources.abc)
@anchor{library/importlib resources abc importlib resources abc TraversableResources}@anchor{571}
@deffn {Κλάση} importlib.resources.abc.TraversableResources

An abstract base class for resource readers capable of serving
the @ref{2d7,,importlib.resources.files()} interface. Subclasses
@ref{4ddc,,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() (μέθοδος της importlib.resources.abc.TraversableResources)
@anchor{library/importlib resources abc importlib resources abc TraversableResources files}@anchor{4e22}
@deffn {Μέθοδος} abstractmethod files ()

Returns a @ref{572,,importlib.resources.abc.Traversable} object for the loaded
package.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node importlib metadata – Accessing package metadata,The initialization of the sys path module search path,importlib resources abc – Abstract base classes for resources,Importing Modules
@anchor{library/importlib metadata doc}@anchor{4e23}@anchor{library/importlib metadata importlib-metadata-accessing-package-metadata}@anchor{4e24}@anchor{library/importlib metadata module-importlib metadata}@anchor{7d}@anchor{library/importlib metadata translation-repo}@anchor{4e25}@anchor{library/importlib metadata using}@anchor{4e26}
@subsection @code{importlib.metadata} – Accessing package metadata


@geindex module; importlib.metadata


Added in version 3.8.



Άλλαξε στην έκδοση 3.10: @code{importlib.metadata} is no longer provisional.


`Source code:' Lib/importlib/metadata/__init__.py@footnote{https://github.com/python/cpython/tree/main/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
provides the entry point and metadata APIs that were previously
exposed by the now-removed @code{pkg_resources} package. Along with
@ref{7e,,importlib.resources}, it supersedes @code{pkg_resources}.

@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 Σημαντικό 
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{be9,,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{194,,sys.path}. Through an extension mechanism, the metadata can live almost
anywhere.


@subsubheading Δείτε επίσης



@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
* Overview: Overview<3>. 
* Functional API:: 
* Distributions:: 
* Distribution Discovery:: 
* Implementing Custom Providers:: 

@end menu

@node Overview<3>,Functional API,,importlib metadata – Accessing package metadata
@anchor{library/importlib metadata overview}@anchor{4e27}
@subsubsection Overview


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{788,,EntryPoint} objects.

You can get the @ref{4e28,,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{4e29,,distribution’s version number}, list its
@ref{4e2a,,constituent files}, and get a list of the distribution’s
@ref{4e2b,,Distribution requirements}.

@geindex PackageNotFoundError
@anchor{library/importlib metadata importlib metadata PackageNotFoundError}@anchor{19cd}
@deffn {Εξαίρεση} importlib.metadata.PackageNotFoundError

Subclass of @ref{1be,,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 Functional API,Distributions,Overview<3>,importlib metadata – Accessing package metadata
@anchor{library/importlib metadata functional-api}@anchor{4e2c}
@subsubsection Functional API


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,,Functional API
@anchor{library/importlib metadata entry-points}@anchor{788}@anchor{library/importlib metadata id2}@anchor{4e2d}
@subsubsection Entry points


@geindex entry_points() (στη μονάδα importlib.metadata)
@anchor{library/importlib metadata importlib metadata entry_points}@anchor{4e2e}
@deffn {Συνάρτηση} importlib.metadata.entry_points (**select_params)

Returns a @ref{4e2f,,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: to query for entry points based on @code{EntryPoint.dist} attribute,
use @ref{4e30,,Distribution.entry_points()} instead (as different @ref{194f,,Distribution}
instances do not currently compare equal, even if they have the same attributes)
@end deffn

@geindex EntryPoints (κλάση σε importlib.metadata)
@anchor{library/importlib metadata importlib metadata EntryPoints}@anchor{4e2f}
@deffn {Κλάση} 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 (κλάση σε importlib.metadata)
@anchor{library/importlib metadata importlib metadata EntryPoint}@anchor{4e31}
@deffn {Κλάση} 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.


Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.13: @code{EntryPoint} objects no longer present a tuple-like interface
(@ref{787,,__getitem__()}).


@node Distribution metadata,Distribution versions,Entry points,Functional API
@anchor{library/importlib metadata distribution-metadata}@anchor{4e32}@anchor{library/importlib metadata metadata}@anchor{4e28}
@subsubsection Distribution metadata


@geindex metadata() (στη μονάδα importlib.metadata)
@anchor{library/importlib metadata importlib metadata metadata}@anchor{4e33}
@deffn {Συνάρτηση} importlib.metadata.metadata (distribution_name)

Return the distribution metadata corresponding to the named
distribution package as a @ref{4e34,,PackageMetadata} instance.

Raises @ref{19cd,,PackageNotFoundError} if the named distribution
package is not installed in the current Python environment.
@end deffn

@geindex PackageMetadata (κλάση σε importlib.metadata)
@anchor{library/importlib metadata importlib metadata PackageMetadata}@anchor{4e34}
@deffn {Κλάση} 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{4e34,,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.


Άλλαξε στην έκδοση 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,Functional API
@anchor{library/importlib metadata distribution-versions}@anchor{4e35}@anchor{library/importlib metadata version}@anchor{4e29}
@subsubsection Distribution versions


@geindex version() (στη μονάδα importlib.metadata)
@anchor{library/importlib metadata importlib metadata version}@anchor{1b79}
@deffn {Συνάρτηση} importlib.metadata.version (distribution_name)

Return the installed distribution package
version@footnote{https://packaging.python.org/en/latest/specifications/core-metadata/#version}
for the named distribution package.

Raises @ref{19cd,,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,Functional API
@anchor{library/importlib metadata distribution-files}@anchor{4e36}@anchor{library/importlib metadata files}@anchor{4e2a}
@subsubsection Distribution files


@geindex files() (στη μονάδα importlib.metadata)
@anchor{library/importlib metadata importlib metadata files}@anchor{4e37}
@deffn {Συνάρτηση} importlib.metadata.files (distribution_name)

Return the full set of files contained within the named
distribution package as @ref{1950,,PackagePath} instances.

Raises @ref{19cd,,PackageNotFoundError} if the named distribution
package is not installed in the current Python environment.

Returns @ref{a65,,None} if the distribution is found but the installation
database records reporting the files associated with the distribution package
are missing.
@end deffn

@geindex PackagePath (κλάση σε importlib.metadata)
@anchor{library/importlib metadata importlib metadata PackagePath}@anchor{1950}
@deffn {Κλάση} importlib.metadata.PackagePath

A @ref{8b6,,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, also:

@geindex locate() (μέθοδος της importlib.metadata.PackagePath)
@anchor{library/importlib metadata importlib metadata PackagePath locate}@anchor{4e38}
@deffn {Μέθοδος} locate ()

If possible, return the concrete @ref{4e39,,SimplePath} allowing to access data,
or raise a @ref{59a,,NotImplementedError} otherwise.
@end deffn
@end deffn

@geindex SimplePath (κλάση σε importlib.metadata)
@anchor{library/importlib metadata importlib metadata SimplePath}@anchor{4e39}
@deffn {Κλάση} importlib.metadata.SimplePath

A protocol representing a minimal subset of @ref{4ee,,pathlib.Path} that allows to
check if it @code{exists()}, to traverse using @code{joinpath()} and @code{parent},
and to retrieve data using @code{read_text()} and @code{read_bytes()}.
@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. 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{a65,,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,Functional API
@anchor{library/importlib metadata distribution-requirements}@anchor{4e3a}@anchor{library/importlib metadata requirements}@anchor{4e2b}
@subsubsection Distribution requirements


@geindex requires() (στη μονάδα importlib.metadata)
@anchor{library/importlib metadata importlib metadata requires}@anchor{4e3b}
@deffn {Συνάρτηση} importlib.metadata.requires (distribution_name)

Return the declared dependency specifiers for the named
distribution package.

Raises @ref{19cd,,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{be9}
@node Mapping import to distribution packages,,Distribution requirements,Functional API
@anchor{library/importlib metadata import-distribution-package-mapping}@anchor{4e3c}@anchor{library/importlib metadata mapping-import-to-distribution-packages}@anchor{4e3d}
@subsubsection Mapping import to distribution packages


@geindex packages_distributions() (στη μονάδα importlib.metadata)
@anchor{library/importlib metadata importlib metadata packages_distributions}@anchor{4e3e}
@deffn {Συνάρτηση} importlib.metadata.packages_distributions ()

Return a mapping from the top level module and import package
names found via @ref{10e3,,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.


Added in version 3.10.


@node Distributions,Distribution Discovery,Functional API,importlib metadata – Accessing package metadata
@anchor{library/importlib metadata distributions}@anchor{bea}@anchor{library/importlib metadata id9}@anchor{4e3f}
@subsubsection Distributions


While the module level API described above is the most common and convenient usage,
all that information is accessible from the @ref{194f,,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}.
Get the concrete @code{Distribution} subclass instance for an installed
distribution package by calling the @ref{4e40,,distribution()} function:

@example
>>> from importlib.metadata import distribution
>>> dist = distribution('wheel')
>>> type(dist)
<class 'importlib.metadata.PathDistribution'>
@end example

@geindex distribution() (στη μονάδα importlib.metadata)
@anchor{library/importlib metadata importlib metadata distribution}@anchor{4e40}
@deffn {Συνάρτηση} importlib.metadata.distribution (distribution_name)

Return a @ref{194f,,Distribution} instance describing the named
distribution package.

Raises @ref{19cd,,PackageNotFoundError} if the named distribution
package is not installed in the current Python environment.
@end deffn

Thus, an alternative way to get e.g. the version number is through the
@ref{4e41,,Distribution.version} attribute:

@example
>>> dist.version
'0.32.3'
@end example

The same applies for @ref{4e2e,,entry_points()} and @ref{4e37,,files()}.

@geindex Distribution (κλάση σε importlib.metadata)
@anchor{library/importlib metadata importlib metadata Distribution}@anchor{194f}
@deffn {Κλάση} 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.

@geindex at() (στατική μέθοδος της importlib.metadata.Distribution)
@anchor{library/importlib metadata importlib metadata Distribution at}@anchor{4e42}
@deffn {Μέθοδος} static at (path)
@end deffn

@geindex from_name() (μέθοδος κλάσης της importlib.metadata.Distribution)
@anchor{library/importlib metadata importlib metadata Distribution from_name}@anchor{4e43}
@deffn {Μέθοδος} classmethod from_name (name)

Return a @code{Distribution} instance at the given path or
with the given name.
@end deffn

@geindex discover() (μέθοδος κλάσης της importlib.metadata.Distribution)
@anchor{library/importlib metadata importlib metadata Distribution discover}@anchor{4e44}
@deffn {Μέθοδος} classmethod discover (*, context=None, **kwargs)

Returns an iterable of @code{Distribution} instances for all packages
(see @ref{4e45,,distribution-discovery}).

The optional argument `context' is a @ref{4e46,,DistributionFinder.Context}
instance, used to modify the search for distributions. Alternatively,
`kwargs' may contain keyword arguments for constructing a new
@code{DistributionFinder.Context}.
@end deffn

@geindex metadata (ιδιότητα της importlib.metadata.Distribution)
@anchor{library/importlib metadata importlib metadata Distribution metadata}@anchor{4e47}
@deffn {Ιδιότητα} metadata: @ref{4e34,,PackageMetadata}

There are all kinds of additional metadata available on @code{Distribution}
instances as a @ref{4e34,,PackageMetadata} instance:

@example
>>> dist.metadata['Requires-Python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
>>> dist.metadata['License']
'MIT'
@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.
@end deffn

@geindex name (ιδιότητα της importlib.metadata.Distribution)
@anchor{library/importlib metadata importlib metadata Distribution name}@anchor{4e48}
@deffn {Ιδιότητα} name: @ref{1df,,str}
@end deffn

@geindex requires (ιδιότητα της importlib.metadata.Distribution)
@anchor{library/importlib metadata importlib metadata Distribution requires}@anchor{4e49}
@deffn {Ιδιότητα} requires: @ref{4d9,,list}[@ref{1df,,str}]
@end deffn

@geindex version (ιδιότητα της importlib.metadata.Distribution)
@anchor{library/importlib metadata importlib metadata Distribution version}@anchor{4e41}
@deffn {Ιδιότητα} version: @ref{1df,,str}

A few metadata fields are also available as shortcut properties.


Added in version 3.10: The @code{name} shortcut was added.

@end deffn

@geindex origin (ιδιότητα της importlib.metadata.Distribution)
@anchor{library/importlib metadata importlib metadata Distribution origin}@anchor{4e4a}
@deffn {Ιδιότητα} origin

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 (for non-editable packages, @code{origin} is @ref{a65,,None}):

@example
>>> dist.origin.url
'file:///path/to/wheel-0.32.3.editable-py3-none-any.whl'
@end example

The @code{origin} object follows the Direct URL Data Structure@footnote{https://packaging.python.org/en/latest/specifications/direct-url-data-structure/}.


Added in version 3.13.

@end deffn

@geindex entry_points (ιδιότητα της importlib.metadata.Distribution)
@anchor{library/importlib metadata importlib metadata Distribution entry_points}@anchor{4e30}
@deffn {Ιδιότητα} entry_points: @ref{4e2f,,EntryPoints}

The entry points provided by this distribution package.
@end deffn

@geindex files (ιδιότητα της importlib.metadata.Distribution)
@anchor{library/importlib metadata importlib metadata Distribution files}@anchor{4e4b}
@deffn {Ιδιότητα} files: @ref{4d9,,list}[@ref{1950,,PackagePath}] | @ref{a65,,None}

All files contained in this distribution package.
Like @ref{4e37,,files()}, this returns @ref{a65,,None} if there are no records.
@end deffn

The following two abstract methods need to be implemented when @ref{4e4c,,implementing-custom-providers}:

@geindex locate_file() (μέθοδος της importlib.metadata.Distribution)
@anchor{library/importlib metadata importlib metadata Distribution locate_file}@anchor{4e4d}
@deffn {Μέθοδος} locate_file (path)

Like @code{PackagePath.locate()}, return a @ref{4e39,,SimplePath} for the given path.
Takes a @ref{100f,,os.PathLike} or a @ref{1df,,str}.
@end deffn

@geindex read_text() (μέθοδος της importlib.metadata.Distribution)
@anchor{library/importlib metadata importlib metadata Distribution read_text}@anchor{4e4e}
@deffn {Μέθοδος} read_text (filename)

A shortcut for @code{distribution.locate_file(filename).read_text()}.
@end deffn
@end deffn

@node Distribution Discovery,Implementing Custom Providers,Distributions,importlib metadata – Accessing package metadata
@anchor{library/importlib metadata distribution-discovery}@anchor{4e45}@anchor{library/importlib metadata id12}@anchor{4e4f}
@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{1c7,,bytes} objects on @code{sys.path}.

@item 
@code{importlib.metadata} will incidentally honor @ref{4ee,,pathlib.Path} objects on @code{sys.path} even though such values will be ignored for imports.
@end itemize

@geindex DistributionFinder (κλάση σε importlib.metadata)
@anchor{library/importlib metadata importlib metadata DistributionFinder}@anchor{4e50}
@deffn {Κλάση} importlib.metadata.DistributionFinder

A @ref{c44,,MetaPathFinder} subclass capable of discovering
installed distributions.

Custom providers should implement this interface in order to
supply metadata.

@quotation

@geindex DistributionFinder.Context (κλάση σε importlib.metadata)
@anchor{library/importlib metadata importlib metadata DistributionFinder Context}@anchor{4e46}
@deffn {Κλάση} Context (**kwargs)

A @code{Context} gives a custom provider a means to
solicit additional details from the callers of distribution discovery
functions like @ref{4e51,,distributions()} or @ref{4e44,,Distribution.discover()}
beyond @code{.name} and @code{.path} when searching
for distributions.

For example, a provider could expose suites of packages in either a
«public» or «private» @code{realm}. A caller of distribution discovery
functions may wish to query only for distributions in a particular realm
and could call @code{distributions(realm="private")} to signal to the
custom provider to only include distributions from that
realm.

Each @code{DistributionFinder} must expect any parameters and should
attempt to honor the canonical parameters defined below when
appropriate.

See the section on @ref{4e4c,,Implementing Custom Providers} for more details.

@geindex name (ιδιότητα της importlib.metadata.DistributionFinder.Context)
@anchor{library/importlib metadata importlib metadata DistributionFinder Context name}@anchor{4e52}
@deffn {Ιδιότητα} name

Specific name for which a distribution finder should match.

A @code{.name} of @code{None} matches all distributions.
@end deffn

@geindex path (ιδιότητα της importlib.metadata.DistributionFinder.Context)
@anchor{library/importlib metadata importlib metadata DistributionFinder Context path}@anchor{4e53}
@deffn {Ιδιότητα} path

A property providing the sequence of directory paths that a
distribution finder should search.

Typically refers to Python installed package paths such as
«site-packages» directories and defaults to @ref{194,,sys.path}.
@end deffn
@end deffn
@end quotation
@end deffn

@geindex distributions() (στη μονάδα importlib.metadata)
@anchor{library/importlib metadata importlib metadata distributions}@anchor{4e51}
@deffn {Συνάρτηση} importlib.metadata.distributions (**kwargs)

Returns an iterable of @ref{194f,,Distribution} instances for all packages.

The `kwargs' argument may contain either a keyword argument @code{context}, a
@ref{4e46,,DistributionFinder.Context} instance, or pass keyword arguments for
constructing a new @code{DistributionFinder.Context}. The
@code{DistributionFinder.Context} is used to modify the search for
distributions.
@end deffn

@node Implementing Custom Providers,,Distribution Discovery,importlib metadata – Accessing package metadata
@anchor{library/importlib metadata id14}@anchor{4e54}@anchor{library/importlib metadata implementing-custom-providers}@anchor{4e4c}
@subsubsection Implementing Custom Providers


@code{importlib.metadata} address two API surfaces, one for `consumers'
and another for `providers'. Most users are consumers, consuming
metadata provided by the packages. There are other use-cases, however,
where users wish to expose metadata through some other mechanism,
such as alongside a custom importer. Such a use case calls for a
`custom provider'.

Because Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package} metadata
is not available through @ref{194,,sys.path} searches, or
package loaders directly,
the metadata for a distribution is found through import
system @ref{263c,,finders}. To find a distribution package’s metadata,
@code{importlib.metadata} queries the list of @ref{1418,,meta path finders} on
@ref{10e3,,sys.meta_path}.

The implementation has hooks integrated into the @code{PathFinder},
serving metadata for distribution packages found on the file system.

The abstract class @ref{c44,,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{10e3,,sys.meta_path} and presents this extended interface as the
@ref{4e50,,DistributionFinder} abstract base class, which defines this abstract
method:

@example
@@abc.abstractmethod
def find_distributions(context=DistributionFinder.Context()) -> Iterable[Distribution]:
    """Return an iterable of all Distribution instances capable of
    loading the metadata for packages for the indicated `@w{`}context`@w{`}.
    """
@end example

The @ref{4e46,,DistributionFinder.Context} object provides
@ref{4e53,,path} and
@ref{4e52,,name} properties indicating the path to
search and name to match and may supply other relevant context sought by the
consumer.

In practice, 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
* Example: Example<13>. 

@end menu

@node Example<13>,,,Implementing Custom Providers
@anchor{library/importlib metadata example}@anchor{4e55}
@subsubsection Example


Imagine 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
@ref{4e50,,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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node The initialization of the sys path module search path,,importlib metadata – Accessing package metadata,Importing Modules
@anchor{library/sys_path_init doc}@anchor{4e56}@anchor{library/sys_path_init sys-path-init}@anchor{1953}@anchor{library/sys_path_init the-initialization-of-the-sys-path-module-search-path}@anchor{4e57}@anchor{library/sys_path_init translation-repo}@anchor{4e58}
@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{194,,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{445,,-c}
command, or @ref{4ca,,-m} module.

The 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,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 Σημείωση 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} will affect all installed Python versions/environments.
Be wary of setting this in your shell profile or global environment variables.
The @ref{cf,,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{2442,,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 μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,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{2a9,,sys.platlibdir} and 
@geindex PYTHONPLATLIBDIR
@geindex μεταβλητή περιβάλλοντος; PYTHONPLATLIBDIR
@ref{1f18,,PYTHONPLATLIBDIR}.

Once found, @code{prefix} and @code{exec_prefix} are available at
@ref{3aa,,sys.base_prefix} and @ref{3a7,,sys.base_exec_prefix} respectively.

If 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} is not set, and a @code{pyvenv.cfg} file is found alongside
the main executable, or in its parent directory, @ref{3ab,,sys.prefix} and
@ref{3a8,,sys.exec_prefix} get set to the directory containing @code{pyvenv.cfg},
otherwise they are set to the same value as @ref{3aa,,sys.base_prefix} and
@ref{3a7,,sys.base_exec_prefix}, respectively.
This is used by @ref{4b93,,Virtual Environments}.

Finally, the @ref{cf,,site} module is processed and @code{site-packages}
directories are added to the module search path.  The 
@geindex PYTHONUSERBASE
@geindex μεταβλητή περιβάλλοντος; PYTHONUSERBASE
@ref{1731,,PYTHONUSERBASE}
environment variable controls where is searched for user site-packages and the
@geindex PYTHONNOUSERSITE
@geindex μεταβλητή περιβάλλοντος; PYTHONNOUSERSITE
@ref{1733,,PYTHONNOUSERSITE} environment variable prevents searching for user
site-packages all together.  A common way to customize the search path is to
create @ref{d0,,sitecustomize} or @ref{117,,usercustomize} modules as described in the
@code{site} module documentation.

@cartouche
@quotation Σημείωση 
The command line options @ref{d27,,-E}, @ref{9a3,,-P}, @ref{d28,,-I},
@ref{1551,,-S} and @ref{1732,,-s} further affect path calculations, see their
documentation for details.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.14: @ref{3ab,,sys.prefix} and @ref{3a8,,sys.exec_prefix} are now set to the
@code{pyvenv.cfg} directory during the path initialization. This was previously
done by @ref{cf,,site}, therefore affected by @ref{1551,,-S}.


@menu
* Virtual Environments:: 
* _pth files:: 
* Embedded Python:: 

@end menu

@node Virtual Environments,_pth files,,The initialization of the sys path module search path
@anchor{library/sys_path_init sys-path-init-virtual-environments}@anchor{4b93}@anchor{library/sys_path_init virtual-environments}@anchor{4e59}
@subsubsection Virtual Environments


Virtual environments place a @code{pyvenv.cfg} file in their prefix, which causes
@ref{3ab,,sys.prefix} and @ref{3a8,,sys.exec_prefix} to point to them, instead of the
base installation.

The @code{prefix} and @code{exec_prefix} values of the base installation are available
at @ref{3aa,,sys.base_prefix} and @ref{3a7,,sys.base_exec_prefix}.

As well as being used as a marker to identify virtual environments,
@code{pyvenv.cfg} may also be used to configure the @ref{cf,,site} initialization.
Please refer to @code{site}’s
@ref{4b94,,virtual environments documentation}.

@cartouche
@quotation Σημείωση 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} overrides the @code{pyvenv.cfg} detection.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
There are other ways «virtual environments» could be implemented.
This documentation refers to implementations based on the @code{pyvenv.cfg}
mechanism, such as @ref{11a,,venv}, that many virtual environment implementations
follow.
@end quotation
@end cartouche

@node _pth files,Embedded Python,Virtual Environments,The initialization of the sys path module search path
@anchor{library/sys_path_init pth-files}@anchor{4e5a}
@subsubsection _pth files


To completely override @ref{194,,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 @code{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.

When the file exists, all registry and environment variables are ignored,
isolated mode is enabled, and @ref{cf,,site} is not imported unless one line in the
file specifies @code{import site}. Blank paths and lines starting with @code{#} are
ignored. Each path may be absolute or relative to the location of the file.
Import statements other than to @code{site} are not permitted, and arbitrary code
cannot be specified.

Note that @code{.pth} files (without leading underscore) will be processed normally
by the @ref{cf,,site} module when @code{import site} has been specified.

@node Embedded Python,,_pth files,The initialization of the sys path module search path
@anchor{library/sys_path_init embedded-python}@anchor{4e5b}
@subsubsection Embedded Python


If Python is embedded within another application @ref{60a,,Py_InitializeFromConfig()} and
the @ref{60b,,PyConfig} structure can be used to initialize Python. The path specific
details are described at @ref{c80,,Python Path Configuration}.


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{fdf,,Εύρεση modules} for detailed Windows notes.

@item 
@ref{2331,,Χρήση της Python σε πλατφόρμες Unix} for Unix details.
@end itemize


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python Language Services,MS Windows Specific Services,Importing Modules,The Python Standard Library
@anchor{library/language doc}@anchor{4e5c}@anchor{library/language language}@anchor{4e5d}@anchor{library/language python-language-services}@anchor{4e5e}@anchor{library/language translation-repo}@anchor{4e5f}
@section Python Language Services


Python provides a number of modules to assist in working with the Python
language.  These modules support tokenizing, parsing, syntax analysis, bytecode
disassembly, and various other facilities.

These modules include:

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

@end menu

@node ast — Abstract syntax trees,symtable — Access to the compiler’s symbol tables,,Python Language Services
@anchor{library/ast doc}@anchor{4e60}@anchor{library/ast ast-abstract-syntax-trees}@anchor{4e61}@anchor{library/ast module-ast}@anchor{9}
@subsection @code{ast} — Abstract syntax trees


@geindex module; ast

@c import ast

`Source code:' Lib/ast.py@footnote{https://github.com/python/cpython/tree/main/Lib/ast.py}


__________________________________________________________________


The @code{ast} module helps Python applications to process trees of the Python
abstract syntax grammar.  The abstract syntax itself might change with each
Python release; this module helps to find out programmatically what the current
grammar looks like.

An abstract syntax tree can be generated by passing @ref{4e62,,ast.PyCF_ONLY_AST} as
a flag to the @ref{1c8,,compile()} built-in function, or using the @ref{1c9,,parse()}
helper provided in this module.  The result will be a tree of objects whose
classes all inherit from @ref{2ec,,ast.AST}.  An abstract syntax tree can be
compiled into a Python code object using the built-in @code{compile()} function.

@menu
* Abstract grammar:: 
* Node classes:: 
* ast helpers:: 
* Compiler flags: Compiler flags<2>. 
* Command-line usage: Command-line usage<5>. 

@end menu

@node Abstract grammar,Node classes,,ast — Abstract syntax trees
@anchor{library/ast abstract-grammar}@anchor{4e63}@anchor{library/ast id1}@anchor{4e64}
@subsubsection Abstract grammar


The abstract grammar is currently defined as follows:

@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, int? is_lazy)
          | ImportFrom(identifier? module, alias* names, int? level, int? is_lazy)

          | 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)
         | Interpolation(expr value, constant str, int conversion, expr? format_spec)
         | JoinedStr(expr* values)
         | TemplateStr(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 Node classes,ast helpers,Abstract grammar,ast — Abstract syntax trees
@anchor{library/ast ast-nodes}@anchor{2c8}@anchor{library/ast node-classes}@anchor{4e65}
@subsubsection Node classes


@geindex AST (κλάση σε ast)
@anchor{library/ast ast AST}@anchor{2ec}
@deffn {Κλάση} ast.AST

This is the abstract base of all AST node classes.  The actual node classes are
derived from the @code{Parser/Python.asdl} file, which is reproduced
@ref{4e63,,above}.  They are defined in the @code{_ast} C
module and re-exported in @code{ast}.

There is one class defined for each left-hand side symbol in the abstract
grammar (for example, @code{ast.stmt} or @code{ast.expr}).  In addition,
there is one class defined for each constructor on the right-hand side; these
classes inherit from the classes for the left-hand side trees.  For example,
@ref{1fa2,,ast.BinOp} inherits from @code{ast.expr}.  For production rules
with alternatives (aka «sums»), the left-hand side class is abstract: only
instances of specific constructor nodes are ever created.

@geindex ? (question mark);in AST grammar

@geindex * (asterisk);in AST grammar

@geindex _fields (ιδιότητα της ast.AST)
@anchor{library/ast ast AST _fields}@anchor{19da}
@deffn {Ιδιότητα} _fields

Each concrete class has an attribute @code{_fields} which gives the names
of all child nodes.

Each instance of a concrete class has one attribute for each child node,
of the type as defined in the grammar.  For example, @ref{1fa2,,ast.BinOp}
instances have an attribute @code{left} of type @code{ast.expr}.

If these attributes are marked as optional in the grammar (using a
question mark), the value might be @code{None}.  If the attributes can have
zero-or-more values (marked with an asterisk), the values are represented
as Python lists.  All possible attributes must be present and have valid
values when compiling an AST with @ref{1c8,,compile()}.
@end deffn

@geindex _field_types (ιδιότητα της ast.AST)
@anchor{library/ast ast AST _field_types}@anchor{6ca}
@deffn {Ιδιότητα} _field_types

The @code{_field_types} attribute on each concrete class is a dictionary
mapping field names (as also listed in @ref{19da,,_fields}) to their types.

@example
>>> ast.TypeVar._field_types
@{'name': <class 'str'>, 'bound': ast.expr | None, 'default_value': ast.expr | None@}
@end example


Added in version 3.13.

@end deffn

@geindex lineno (ιδιότητα της ast.AST)
@geindex col_offset (ιδιότητα της ast.AST)
@geindex end_lineno (ιδιότητα της ast.AST)
@geindex end_col_offset (ιδιότητα της ast.AST)
@anchor{library/ast ast AST lineno}@anchor{4e66}
@deffn {Ιδιότητα} lineno
@anchor{library/ast ast AST col_offset}@anchor{4e67}
@deffnx {Ιδιότητα} col_offset
@anchor{library/ast ast AST end_lineno}@anchor{4e68}
@deffnx {Ιδιότητα} end_lineno
@anchor{library/ast ast AST end_col_offset}@anchor{4e69}
@deffnx {Ιδιότητα} end_col_offset

Instances of @code{ast.expr} and @code{ast.stmt} subclasses have
@ref{4e66,,lineno}, @ref{4e67,,col_offset}, @ref{4e68,,end_lineno}, and
@ref{4e69,,end_col_offset} attributes.  The @code{lineno} and @code{end_lineno}
are the first and last line numbers of source text span (1-indexed so the
first line is line 1) and the @code{col_offset} and @code{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.

Note that the end positions are not required by the compiler and are
therefore optional. The end offset is `after' the last symbol, for example
one can get the source segment of a one-line expression node using
@code{source_line[node.col_offset : node.end_col_offset]}.
@end deffn

The constructor of a class @code{ast.T} parses its arguments as follows:


@itemize *

@item 
If there are positional arguments, there must be as many as there are items
in @code{T._fields}; they will be assigned as attributes of these names.

@item 
If there are keyword arguments, they will set the attributes of the same
names to the given values.
@end itemize

For example, to create and populate an @ref{4d5d,,ast.UnaryOp} node, you could
use

@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{6c9,,Load()}. If any other field is omitted, a @ref{2c9,,DeprecationWarning} is raised
and the AST node will not have this field. In Python 3.15, this condition will
raise an error.
@end deffn


Άλλαξε στην έκδοση 3.8: Class @ref{569,,ast.Constant} is now used for all constants.



Άλλαξε στην έκδοση 3.9: Simple indices are represented by their value, extended slices are
represented as tuples.



Άλλαξε στην έκδοση 3.13: AST node constructors were changed to provide sensible defaults for omitted
fields: optional fields now default to @code{None}, list fields default to an
empty list, and fields of type @code{ast.expr_context} default to
@ref{6c9,,Load()}. Previously, omitted attributes would not exist on constructed
nodes (accessing them raised @ref{1a9,,AttributeError}).



Άλλαξε στην έκδοση 3.14: The @ref{1bc,,__repr__()} output of @ref{2ec,,AST} nodes includes
the values of the node fields.



Καταργήθηκε από την έκδοση 3.8, αφαιρέθηκε στην έκδοση 3.14: Previous versions of Python provided the AST classes @code{ast.Num},
@code{ast.Str}, @code{ast.Bytes}, @code{ast.NameConstant} and
@code{ast.Ellipsis}, which were deprecated in Python 3.8. These classes
were removed in Python 3.14, and their functionality has been replaced with
@ref{569,,ast.Constant}.



Αποσύρθηκε στην έκδοση 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.



Καταργήθηκε από την έκδοση 3.13, αφαιρέθηκε στην έκδοση 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. These cases now raise a @ref{291,,TypeError}.



Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.20: In the @ref{4e63,,grammar above}, the AST node classes that
correspond to production rules with variants (aka «sums») are abstract
classes. Previous versions of Python allowed for the creation of direct
instances of these abstract node classes. This behavior is deprecated and
will be removed in Python 3.20.


@cartouche
@quotation Σημείωση 
The descriptions of the specific node classes displayed here
were initially adapted from the fantastic Green Tree Snakes@footnote{https://greentreesnakes.readthedocs.io/en/latest/} project and
all its contributors.
@end quotation
@end cartouche

@menu
* Root nodes:: 
* Literals: Literals<2>. 
* Variables:: 
* Expressions: Expressions<2>. 
* Statements:: 
* Control flow:: 
* Pattern matching:: 
* Type annotations:: 
* Type parameters:: 
* Function and class definitions:: 
* Async and await:: 

@end menu

@node Root nodes,Literals<2>,,Node classes
@anchor{library/ast ast-root-nodes}@anchor{4e6a}@anchor{library/ast root-nodes}@anchor{4e6b}
@subsubsection Root nodes


@geindex Module (κλάση σε ast)
@anchor{library/ast ast Module}@anchor{4e6c}
@deffn {Κλάση} ast.Module (body, type_ignores)

A Python module, as with @ref{2798,,file input}.
Node type generated by @ref{1c9,,ast.parse()} in the default @code{"exec"} `mode'.

@code{body} is a @ref{4d9,,list} of the module’s @ref{4e6d,,Statements}.

@code{type_ignores} is a @ref{4d9,,list} of the module’s type ignore comments;
see @ref{1c9,,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 (κλάση σε ast)
@anchor{library/ast ast Expression}@anchor{4e6e}
@deffn {Κλάση} ast.Expression (body)

A single Python @ref{279e,,expression input}.
Node type generated by @ref{1c9,,ast.parse()} when `mode' is @code{"eval"}.

@code{body} is a single node,
one of the @ref{4e6f,,expression types}.

@example
>>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))
Expression(
    body=Constant(value=123))
@end example
@end deffn

@geindex Interactive (κλάση σε ast)
@anchor{library/ast ast Interactive}@anchor{1aa0}
@deffn {Κλάση} ast.Interactive (body)

A single @ref{279b,,interactive input}, like in @ref{6a0,,Διαδραστική Λειτουργία}.
Node type generated by @ref{1c9,,ast.parse()} when `mode' is @code{"single"}.

@code{body} is a @ref{4d9,,list} of @ref{4e6d,,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 (κλάση σε ast)
@anchor{library/ast ast FunctionType}@anchor{4e70}
@deffn {Κλάση} 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{1c9,,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{4d9,,list} of @ref{4e6f,,expression nodes}.

@code{returns} is a single @ref{4e6f,,expression node}.

@example
>>> print(ast.dump(ast.parse('(int, str) -> List[int]', mode='func_type'), indent=4))
FunctionType(
    argtypes=[
        Name(id='int'),
        Name(id='str')],
    returns=Subscript(
        value=Name(id='List'),
        slice=Name(id='int')))
@end example


Added in version 3.8.

@end deffn

@node Literals<2>,Variables,Root nodes,Node classes
@anchor{library/ast literals}@anchor{4e71}
@subsubsection Literals


@geindex Constant (κλάση σε ast)
@anchor{library/ast ast Constant}@anchor{569}
@deffn {Κλάση} ast.Constant (value, kind)

A constant value. The @code{value} attribute of the @code{Constant} literal contains the
Python object it represents. The values represented can be instances of @ref{1df,,str},
@ref{1c7,,bytes}, @ref{326,,int}, @ref{327,,float}, @ref{328,,complex}, and @ref{5ef,,bool},
and the constants @ref{a65,,None} and @ref{2519,,Ellipsis}.

The @code{kind} attribute is an optional string. For string literals with a
@code{u} prefix, @code{kind} is set to @code{'u'}. For all other
constants, @code{kind} is @code{None}.

@example
>>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))
Expression(
    body=Constant(value=123))
>>> print(ast.dump(ast.parse("u'hello'", mode='eval'), indent=4))
Expression(
    body=Constant(value='hello', kind='u'))
@end example
@end deffn

@geindex FormattedValue (κλάση σε ast)
@anchor{library/ast ast FormattedValue}@anchor{4d75}
@deffn {Κλάση} ast.FormattedValue (value, conversion, format_spec)

Node representing a single formatting field in an f-string. If the string
contains a single formatting field and nothing else the node can be
isolated otherwise it appears in @ref{1c62,,JoinedStr}.


@itemize *

@item 
@code{value} is any expression node (such as a literal, a variable, or a
function call).

@item 
@code{conversion} is an integer:


@itemize *

@item 
-1: no formatting

@item 
97 (@code{ord('a')}): @code{!a} @ref{1789,,ASCII} formatting

@item 
114 (@code{ord('r')}): @code{!r} @ref{45b,,repr()} formatting

@item 
115 (@code{ord('s')}): @code{!s} @ref{1df,,string} formatting
@end itemize

@item 
@code{format_spec} is a @ref{1c62,,JoinedStr} node representing the formatting
of the value, or @code{None} if no format was specified. Both
@code{conversion} and @code{format_spec} can be set at the same time.
@end itemize
@end deffn

@geindex JoinedStr (κλάση σε ast)
@anchor{library/ast ast JoinedStr}@anchor{1c62}
@deffn {Κλάση} ast.JoinedStr (values)

An f-string, comprising a series of @ref{4d75,,FormattedValue} and @ref{569,,Constant}
nodes.

@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'),
                conversion=-1),
            Constant(value=') is '),
            FormattedValue(
                value=Call(
                    func=Name(id='sin'),
                    args=[
                        Name(id='a')]),
                conversion=-1,
                format_spec=JoinedStr(
                    values=[
                        Constant(value='.3')]))]))
@end example
@end deffn

@geindex TemplateStr (κλάση σε ast)
@anchor{library/ast ast TemplateStr}@anchor{4e72}
@deffn {Κλάση} ast.TemplateStr (values, /)


Added in version 3.14.


Node representing a template string literal, comprising a series of
@ref{19cc,,Interpolation} and @ref{569,,Constant} nodes.
These nodes may be any order, and do not need to be interleaved.

@example
>>> expr = ast.parse('t"@{name@} finished @{place:ordinal@}"', mode='eval')
>>> print(ast.dump(expr, indent=4))
Expression(
    body=TemplateStr(
        values=[
            Interpolation(
                value=Name(id='name'),
                str='name',
                conversion=-1),
            Constant(value=' finished '),
            Interpolation(
                value=Name(id='place'),
                str='place',
                conversion=-1,
                format_spec=JoinedStr(
                    values=[
                        Constant(value='ordinal')]))]))
@end example
@end deffn

@geindex Interpolation (κλάση σε ast)
@anchor{library/ast ast Interpolation}@anchor{19cc}
@deffn {Κλάση} ast.Interpolation (value, str, conversion, format_spec=None)


Added in version 3.14.


Node representing a single interpolation field in a template string literal.


@itemize *

@item 
@code{value} is any expression node (such as a literal, a variable, or a
function call).
This has the same meaning as @code{FormattedValue.value}.

@item 
@code{str} is a constant containing the text of the interpolation expression.

If @code{str} is set to @code{None}, then @code{value} is used to generate code
when calling @ref{cb6,,ast.unparse()}. This no longer guarantees that the
generated code is identical to the original and is intended for code
generation.

@item 
@code{conversion} is an integer:


@itemize *

@item 
-1: no conversion

@item 
97 (@code{ord('a')}): @code{!a} @ref{1789,,ASCII} conversion

@item 
114 (@code{ord('r')}): @code{!r} @ref{45b,,repr()} conversion

@item 
115 (@code{ord('s')}): @code{!s} @ref{1df,,string} conversion
@end itemize

This has the same meaning as @code{FormattedValue.conversion}.

@item 
@code{format_spec} is a @ref{1c62,,JoinedStr} node representing the formatting
of the value, or @code{None} if no format was specified. Both
@code{conversion} and @code{format_spec} can be set at the same time.
This has the same meaning as @code{FormattedValue.format_spec}.
@end itemize
@end deffn

@geindex List (κλάση σε ast)
@geindex Tuple (κλάση σε ast)
@anchor{library/ast ast List}@anchor{4d72}
@deffn {Κλάση} ast.List (elts, ctx)
@anchor{library/ast ast Tuple}@anchor{4d73}
@deffnx {Κλάση} ast.Tuple (elts, ctx)

A list or tuple. @code{elts} holds a list of nodes representing the elements.
@code{ctx} is @ref{4e73,,Store} if the container is an assignment target (i.e.
@code{(x,y)=something}), and @ref{6c9,,Load} otherwise.

@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)]))
>>> 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)]))
@end example
@end deffn

@geindex Set (κλάση σε ast)
@anchor{library/ast ast Set}@anchor{4d62}
@deffn {Κλάση} ast.Set (elts)

A set. @code{elts} holds a list of nodes representing the set’s elements.

@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 (κλάση σε ast)
@anchor{library/ast ast Dict}@anchor{1f3d}
@deffn {Κλάση} ast.Dict (keys, values)

A dictionary. @code{keys} and @code{values} hold lists of nodes representing the
keys and the values respectively, in matching order (what would be returned
when calling @code{dictionary.keys()} and @code{dictionary.values()}).

When doing dictionary unpacking using dictionary literals the expression to be
expanded goes in the @code{values} list, with a @code{None} at the corresponding
position in @code{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')]))
@end example
@end deffn

@node Variables,Expressions<2>,Literals<2>,Node classes
@anchor{library/ast variables}@anchor{4e74}
@subsubsection Variables


@geindex Name (κλάση σε ast)
@anchor{library/ast ast Name}@anchor{1f17}
@deffn {Κλάση} ast.Name (id, ctx)

A variable name. @code{id} holds the name as a string, and @code{ctx} is one of
the following types.
@end deffn

@geindex Load (κλάση σε ast)
@geindex Store (κλάση σε ast)
@geindex Del (κλάση σε ast)
@anchor{library/ast ast Load}@anchor{6c9}
@deffn {Κλάση} ast.Load
@anchor{library/ast ast Store}@anchor{4e73}
@deffnx {Κλάση} ast.Store
@anchor{library/ast ast Del}@anchor{4e75}
@deffnx {Κλάση} ast.Del

Variable references can be used to load the value of a variable, to assign
a new value to it, or to delete it. Variable references are given a context
to distinguish these cases.

@example
>>> print(ast.dump(ast.parse('a'), indent=4))
Module(
    body=[
        Expr(
            value=Name(id='a'))])

>>> 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 (κλάση σε ast)
@anchor{library/ast ast Starred}@anchor{4d71}
@deffn {Κλάση} ast.Starred (value, ctx)

A @code{*var} variable reference. @code{value} holds the variable, typically a
@ref{1f17,,Name} node. This type must be used when building a @ref{4d6e,,Call}
node with @code{*args}.

@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'))])
@end example
@end deffn

@node Expressions<2>,Statements,Variables,Node classes
@anchor{library/ast ast-expressions}@anchor{4e6f}@anchor{library/ast expressions}@anchor{4e76}
@subsubsection Expressions


@geindex Expr (κλάση σε ast)
@anchor{library/ast ast Expr}@anchor{4e77}
@deffn {Κλάση} ast.Expr (value)

When an expression, such as a function call, appears as a statement by itself
with its return value not used or stored, it is wrapped in this container.
@code{value} holds one of the other nodes in this section, a @ref{569,,Constant}, a
@ref{1f17,,Name}, a @ref{4d78,,Lambda}, a @ref{4d7f,,Yield} or @ref{4d80,,YieldFrom} node.

@example
>>> print(ast.dump(ast.parse('-a'), indent=4))
Module(
    body=[
        Expr(
            value=UnaryOp(
                op=USub(),
                operand=Name(id='a')))])
@end example
@end deffn

@geindex UnaryOp (κλάση σε ast)
@anchor{library/ast ast UnaryOp}@anchor{4d5d}
@deffn {Κλάση} ast.UnaryOp (op, operand)

A unary operation. @code{op} is the operator, and @code{operand} any expression
node.
@end deffn

@geindex UAdd (κλάση σε ast)
@geindex USub (κλάση σε ast)
@geindex Not (κλάση σε ast)
@geindex Invert (κλάση σε ast)
@anchor{library/ast ast UAdd}@anchor{4d5f}
@deffn {Κλάση} ast.UAdd
@anchor{library/ast ast USub}@anchor{4d60}
@deffnx {Κλάση} ast.USub
@anchor{library/ast ast Not}@anchor{4d61}
@deffnx {Κλάση} ast.Not
@anchor{library/ast ast Invert}@anchor{4d5e}
@deffnx {Κλάση} ast.Invert

Unary operator tokens. @code{Not} is the @code{not} keyword, @code{Invert}
is the @code{~} operator.

@example
>>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4))
Expression(
    body=UnaryOp(
        op=Not(),
        operand=Name(id='x')))
@end example
@end deffn

@geindex BinOp (κλάση σε ast)
@anchor{library/ast ast BinOp}@anchor{1fa2}
@deffn {Κλάση} ast.BinOp (left, op, right)

A binary operation (like addition or division). @code{op} is the operator, and
@code{left} and @code{right} are any expression nodes.

@example
>>> print(ast.dump(ast.parse('x + y', mode='eval'), indent=4))
Expression(
    body=BinOp(
        left=Name(id='x'),
        op=Add(),
        right=Name(id='y')))
@end example
@end deffn

@geindex Add (κλάση σε ast)
@geindex Sub (κλάση σε ast)
@geindex Mult (κλάση σε ast)
@geindex Div (κλάση σε ast)
@geindex FloorDiv (κλάση σε ast)
@geindex Mod (κλάση σε ast)
@geindex Pow (κλάση σε ast)
@geindex LShift (κλάση σε ast)
@geindex RShift (κλάση σε ast)
@geindex BitOr (κλάση σε ast)
@geindex BitXor (κλάση σε ast)
@geindex BitAnd (κλάση σε ast)
@geindex MatMult (κλάση σε ast)
@anchor{library/ast ast Add}@anchor{4e78}
@deffn {Κλάση} ast.Add
@anchor{library/ast ast Sub}@anchor{4e79}
@deffnx {Κλάση} ast.Sub
@anchor{library/ast ast Mult}@anchor{4e7a}
@deffnx {Κλάση} ast.Mult
@anchor{library/ast ast Div}@anchor{4e7b}
@deffnx {Κλάση} ast.Div
@anchor{library/ast ast FloorDiv}@anchor{4e7c}
@deffnx {Κλάση} ast.FloorDiv
@anchor{library/ast ast Mod}@anchor{4e7d}
@deffnx {Κλάση} ast.Mod
@anchor{library/ast ast Pow}@anchor{4e7e}
@deffnx {Κλάση} ast.Pow
@anchor{library/ast ast LShift}@anchor{4e7f}
@deffnx {Κλάση} ast.LShift
@anchor{library/ast ast RShift}@anchor{4e80}
@deffnx {Κλάση} ast.RShift
@anchor{library/ast ast BitOr}@anchor{4e81}
@deffnx {Κλάση} ast.BitOr
@anchor{library/ast ast BitXor}@anchor{4e82}
@deffnx {Κλάση} ast.BitXor
@anchor{library/ast ast BitAnd}@anchor{4e83}
@deffnx {Κλάση} ast.BitAnd
@anchor{library/ast ast MatMult}@anchor{4e84}
@deffnx {Κλάση} ast.MatMult

Binary operator tokens.
@end deffn

@geindex BoolOp (κλάση σε ast)
@anchor{library/ast ast BoolOp}@anchor{4d76}
@deffn {Κλάση} ast.BoolOp (op, values)

A boolean operation, “or” or “and”. @code{op} is @ref{4e85,,Or} or @ref{4e86,,And}.
@code{values} are the values involved. Consecutive operations with the same
operator, such as @code{a or b or c}, are collapsed into one node with several
values.

This doesn’t include @code{not}, which is a @ref{4d5d,,UnaryOp}.

@example
>>> print(ast.dump(ast.parse('x or y', mode='eval'), indent=4))
Expression(
    body=BoolOp(
        op=Or(),
        values=[
            Name(id='x'),
            Name(id='y')]))
@end example
@end deffn

@geindex And (κλάση σε ast)
@geindex Or (κλάση σε ast)
@anchor{library/ast ast And}@anchor{4e86}
@deffn {Κλάση} ast.And
@anchor{library/ast ast Or}@anchor{4e85}
@deffnx {Κλάση} ast.Or

Boolean operator tokens.
@end deffn

@geindex Compare (κλάση σε ast)
@anchor{library/ast ast Compare}@anchor{4d63}
@deffn {Κλάση} ast.Compare (left, ops, comparators)

A comparison of two or more values. @code{left} is the first value in the
comparison, @code{ops} the list of operators, and @code{comparators} the list
of values after the first element in the comparison.

@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'),
            Constant(value=10)]))
@end example
@end deffn

@geindex Eq (κλάση σε ast)
@geindex NotEq (κλάση σε ast)
@geindex Lt (κλάση σε ast)
@geindex LtE (κλάση σε ast)
@geindex Gt (κλάση σε ast)
@geindex GtE (κλάση σε ast)
@geindex Is (κλάση σε ast)
@geindex IsNot (κλάση σε ast)
@geindex In (κλάση σε ast)
@geindex NotIn (κλάση σε ast)
@anchor{library/ast ast Eq}@anchor{4d64}
@deffn {Κλάση} ast.Eq
@anchor{library/ast ast NotEq}@anchor{4d65}
@deffnx {Κλάση} ast.NotEq
@anchor{library/ast ast Lt}@anchor{4d66}
@deffnx {Κλάση} ast.Lt
@anchor{library/ast ast LtE}@anchor{4d67}
@deffnx {Κλάση} ast.LtE
@anchor{library/ast ast Gt}@anchor{4d68}
@deffnx {Κλάση} ast.Gt
@anchor{library/ast ast GtE}@anchor{4d69}
@deffnx {Κλάση} ast.GtE
@anchor{library/ast ast Is}@anchor{4d6a}
@deffnx {Κλάση} ast.Is
@anchor{library/ast ast IsNot}@anchor{4d6b}
@deffnx {Κλάση} ast.IsNot
@anchor{library/ast ast In}@anchor{4d6c}
@deffnx {Κλάση} ast.In
@anchor{library/ast ast NotIn}@anchor{4d6d}
@deffnx {Κλάση} ast.NotIn

Comparison operator tokens.
@end deffn

@geindex Call (κλάση σε ast)
@anchor{library/ast ast Call}@anchor{4d6e}
@deffn {Κλάση} ast.Call (func, args, keywords)

A function call. @code{func} is the function, which will often be a
@ref{1f17,,Name} or @ref{4d6f,,Attribute} object. Of the arguments:


@itemize *

@item 
@code{args} holds a list of the arguments passed by position.

@item 
@code{keywords} holds a list of @ref{4e87,,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'),
        args=[
            Name(id='a'),
            Starred(
                value=Name(id='d'))],
        keywords=[
            keyword(
                arg='b',
                value=Name(id='c')),
            keyword(
                value=Name(id='e'))]))
@end example
@end deffn

@geindex keyword (κλάση σε ast)
@anchor{library/ast ast keyword}@anchor{4e87}
@deffn {Κλάση} 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 (κλάση σε ast)
@anchor{library/ast ast IfExp}@anchor{4d77}
@deffn {Κλάση} ast.IfExp (test, body, orelse)

An expression such as @code{a if b else c}. Each field holds a single node, so
in the following example, all three are @ref{1f17,,Name} nodes.

@example
>>> print(ast.dump(ast.parse('a if b else c', mode='eval'), indent=4))
Expression(
    body=IfExp(
        test=Name(id='b'),
        body=Name(id='a'),
        orelse=Name(id='c')))
@end example
@end deffn

@geindex Attribute (κλάση σε ast)
@anchor{library/ast ast Attribute}@anchor{4d6f}
@deffn {Κλάση} ast.Attribute (value, attr, ctx)

Attribute access, e.g. @code{d.keys}. @code{value} is a node, typically a
@ref{1f17,,Name}. @code{attr} is a bare string giving the name of the attribute,
and @code{ctx} is @ref{6c9,,Load}, @ref{4e73,,Store} or @ref{4e75,,Del} according to how
the attribute is acted on.

@example
>>> print(ast.dump(ast.parse('snake.colour', mode='eval'), indent=4))
Expression(
    body=Attribute(
        value=Name(id='snake'),
        attr='colour'))
@end example
@end deffn

@geindex NamedExpr (κλάση σε ast)
@anchor{library/ast ast NamedExpr}@anchor{4d7d}
@deffn {Κλάση} ast.NamedExpr (target, value)

A named expression. This AST node is produced by the assignment expressions
operator (also known as the walrus operator). As opposed to the @ref{4e88,,Assign}
node in which the first argument can be multiple nodes, in this case both
@code{target} and @code{value} must be single nodes.

@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


Added in version 3.8.

@end deffn

@menu
* Subscripting:: 
* Comprehensions:: 

@end menu

@node Subscripting,Comprehensions,,Expressions<2>
@anchor{library/ast subscripting}@anchor{4e89}
@subsubsection Subscripting


@geindex Subscript (κλάση σε ast)
@anchor{library/ast ast Subscript}@anchor{4d70}
@deffn {Κλάση} ast.Subscript (value, slice, ctx)

A subscript, such as @code{l[1]}. @code{value} is the subscripted object
(usually sequence or mapping). @code{slice} is an index, slice or key.
It can be a @ref{4d73,,Tuple} and contain a @ref{4d74,,Slice}.
@code{ctx} is @ref{6c9,,Load}, @ref{4e73,,Store} or @ref{4e75,,Del}
according to the action performed with the subscript.

@example
>>> print(ast.dump(ast.parse('l[1:2, 3]', mode='eval'), indent=4))
Expression(
    body=Subscript(
        value=Name(id='l'),
        slice=Tuple(
            elts=[
                Slice(
                    lower=Constant(value=1),
                    upper=Constant(value=2)),
                Constant(value=3)])))
@end example
@end deffn

@geindex Slice (κλάση σε ast)
@anchor{library/ast ast Slice}@anchor{4d74}
@deffn {Κλάση} ast.Slice (lower, upper, step)

Regular slicing (on the form @code{lower:upper} or @code{lower:upper:step}).
Can occur only inside the `slice' field of @ref{4d70,,Subscript}, either
directly or as an element of @ref{4d73,,Tuple}.

@example
>>> print(ast.dump(ast.parse('l[1:2]', mode='eval'), indent=4))
Expression(
    body=Subscript(
        value=Name(id='l'),
        slice=Slice(
            lower=Constant(value=1),
            upper=Constant(value=2))))
@end example
@end deffn

@node Comprehensions,,Subscripting,Expressions<2>
@anchor{library/ast comprehensions}@anchor{4e8a}
@subsubsection Comprehensions


@geindex ListComp (κλάση σε ast)
@geindex SetComp (κλάση σε ast)
@geindex GeneratorExp (κλάση σε ast)
@geindex DictComp (κλάση σε ast)
@anchor{library/ast ast ListComp}@anchor{4d79}
@deffn {Κλάση} ast.ListComp (elt, generators)
@anchor{library/ast ast SetComp}@anchor{4d7a}
@deffnx {Κλάση} ast.SetComp (elt, generators)
@anchor{library/ast ast GeneratorExp}@anchor{4d7c}
@deffnx {Κλάση} ast.GeneratorExp (elt, generators)
@anchor{library/ast ast DictComp}@anchor{4d7b}
@deffnx {Κλάση} ast.DictComp (key, value, generators)

List and set comprehensions, generator expressions, and dictionary
comprehensions. @code{elt} (or @code{key} and @code{value}) is a single node
representing the part that will be evaluated for each item.

@code{generators} is a list of @ref{4e8b,,comprehension} nodes.

@example
>>> print(ast.dump(
...     ast.parse('[x for x in numbers]', mode='eval'),
...     indent=4,
... ))
Expression(
    body=ListComp(
        elt=Name(id='x'),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers'),
                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'),
        value=BinOp(
            left=Name(id='x'),
            op=Pow(),
            right=Constant(value=2)),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers'),
                is_async=0)]))
>>> print(ast.dump(
...     ast.parse('@{x for x in numbers@}', mode='eval'),
...     indent=4,
... ))
Expression(
    body=SetComp(
        elt=Name(id='x'),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers'),
                is_async=0)]))
@end example
@end deffn

@geindex comprehension (κλάση σε ast)
@anchor{library/ast ast comprehension}@anchor{4e8b}
@deffn {Κλάση} ast.comprehension (target, iter, ifs, is_async)

One @code{for} clause in a comprehension. @code{target} is the reference to use for
each element - typically a @ref{1f17,,Name} or @ref{4d73,,Tuple} node. @code{iter}
is the object to iterate over. @code{ifs} is a list of test expressions: each
@code{for} clause can have multiple @code{ifs}.

@code{is_async} indicates a comprehension is asynchronous (using an
@code{async for} instead of @code{for}). The value is an integer (0 or 1).

@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'),
            args=[
                Name(id='c')]),
        generators=[
            comprehension(
                target=Name(id='line', ctx=Store()),
                iter=Name(id='file'),
                is_async=0),
            comprehension(
                target=Name(id='c', ctx=Store()),
                iter=Name(id='line'),
                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'),
            op=Pow(),
            right=Constant(value=2)),
        generators=[
            comprehension(
                target=Name(id='n', ctx=Store()),
                iter=Name(id='it'),
                ifs=[
                    Compare(
                        left=Name(id='n'),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=5)]),
                    Compare(
                        left=Name(id='n'),
                        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'),
        generators=[
            comprehension(
                target=Name(id='i', ctx=Store()),
                iter=Name(id='soc'),
                is_async=1)]))
@end example
@end deffn

@node Statements,Control flow,Expressions<2>,Node classes
@anchor{library/ast ast-statements}@anchor{4e6d}@anchor{library/ast statements}@anchor{4e8c}
@subsubsection Statements


@geindex Assign (κλάση σε ast)
@anchor{library/ast ast Assign}@anchor{4e88}
@deffn {Κλάση} ast.Assign (targets, value, type_comment)

An assignment. @code{targets} is a list of nodes, and @code{value} is a single node.

Multiple nodes in @code{targets} represents assigning the same value to each.
Unpacking is represented by putting a @ref{4d73,,Tuple} or @ref{4d72,,List}
within @code{targets}.

@geindex type_comment (ιδιότητα της ast.Assign)
@anchor{library/ast ast Assign type_comment}@anchor{4e8d}
@deffn {Ιδιότητα} type_comment

@code{type_comment} is an optional string with the type annotation as a comment.
@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'))])
@end example
@end deffn

@geindex AnnAssign (κλάση σε ast)
@anchor{library/ast ast AnnAssign}@anchor{4e8e}
@deffn {Κλάση} ast.AnnAssign (target, annotation, value, simple)

An assignment with a type annotation. @code{target} is a single node and can
be a @ref{1f17,,Name}, an @ref{4d6f,,Attribute} or a @ref{4d70,,Subscript}.
@code{annotation} is the annotation, such as a @ref{569,,Constant} or @code{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{1f17,,Name} node that does not appear between parentheses; all other
targets are considered complex. Only simple targets appear in
the @ref{66b,,__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'),
            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'),
            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'),
                attr='b',
                ctx=Store()),
            annotation=Name(id='int'),
            simple=0)])

>>> print(ast.dump(ast.parse('a[1]: int'), indent=4)) # Subscript annotation
Module(
    body=[
        AnnAssign(
            target=Subscript(
                value=Name(id='a'),
                slice=Constant(value=1),
                ctx=Store()),
            annotation=Name(id='int'),
            simple=0)])
@end example
@end deffn

@geindex AugAssign (κλάση σε ast)
@anchor{library/ast ast AugAssign}@anchor{4e8f}
@deffn {Κλάση} ast.AugAssign (target, op, value)

Augmented assignment, such as @code{a += 1}. In the following example,
@code{target} is a @ref{1f17,,Name} node for @code{x} (with the @ref{4e73,,Store}
context), @code{op} is @ref{4e78,,Add}, and @code{value} is a @ref{569,,Constant} with
value for 1.

The @code{target} attribute cannot be of class @ref{4d73,,Tuple} or @ref{4d72,,List},
unlike the targets of @ref{4e88,,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 (κλάση σε ast)
@anchor{library/ast ast Raise}@anchor{4e90}
@deffn {Κλάση} ast.Raise (exc, cause)

A @code{raise} statement. @code{exc} is the exception object to be raised, normally a
@ref{4d6e,,Call} or @ref{1f17,,Name}, or @code{None} for a standalone @code{raise}.
@code{cause} is the optional part for @code{y} in @code{raise x from y}.

@example
>>> print(ast.dump(ast.parse('raise x from y'), indent=4))
Module(
    body=[
        Raise(
            exc=Name(id='x'),
            cause=Name(id='y'))])
@end example
@end deffn

@geindex Assert (κλάση σε ast)
@anchor{library/ast ast Assert}@anchor{4e91}
@deffn {Κλάση} ast.Assert (test, msg)

An assertion. @code{test} holds the condition, such as a @ref{4d63,,Compare} node.
@code{msg} holds the failure message.

@example
>>> print(ast.dump(ast.parse('assert x,y'), indent=4))
Module(
    body=[
        Assert(
            test=Name(id='x'),
            msg=Name(id='y'))])
@end example
@end deffn

@geindex Delete (κλάση σε ast)
@anchor{library/ast ast Delete}@anchor{4e92}
@deffn {Κλάση} ast.Delete (targets)

Represents a @code{del} statement. @code{targets} is a list of nodes, such as
@ref{1f17,,Name}, @ref{4d6f,,Attribute} or @ref{4d70,,Subscript} nodes.

@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 (κλάση σε ast)
@anchor{library/ast ast Pass}@anchor{4e93}
@deffn {Κλάση} ast.Pass

A @code{pass} statement.

@example
>>> print(ast.dump(ast.parse('pass'), indent=4))
Module(
    body=[
        Pass()])
@end example
@end deffn

@geindex TypeAlias (κλάση σε ast)
@anchor{library/ast ast TypeAlias}@anchor{1c5b}
@deffn {Κλάση} ast.TypeAlias (name, type_params, value)

A @ref{870,,type alias} created through the @ref{85a,,type}
statement. @code{name} is the name of the alias, @code{type_params} is a list of
@ref{4e94,,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'))])
@end example


Added in version 3.12.

@end deffn

Other statements which are only applicable inside functions or loops are
described in other sections.

@menu
* Imports:: 

@end menu

@node Imports,,,Statements
@anchor{library/ast imports}@anchor{4e95}
@subsubsection Imports


@geindex Import (κλάση σε ast)
@anchor{library/ast ast Import}@anchor{4e96}
@deffn {Κλάση} ast.Import (names)

An import statement. @code{names} is a list of @ref{1e6b,,alias} nodes.

@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')],
            is_lazy=0)])
@end example
@end deffn

@geindex ImportFrom (κλάση σε ast)
@anchor{library/ast ast ImportFrom}@anchor{4e97}
@deffn {Κλάση} ast.ImportFrom (module, names, level)

Represents @code{from x import y}. @code{module} is a raw string of the “from” name,
without any leading dots, or @code{None} for statements such as @code{from . import foo}.
@code{level} is an integer holding the level of the relative import (0 means
absolute import).

@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,
            is_lazy=0)])
@end example
@end deffn

@geindex alias (κλάση σε ast)
@anchor{library/ast ast alias}@anchor{1e6b}
@deffn {Κλάση} ast.alias (name, asname)

Both parameters are raw strings of the names. @code{asname} can be @code{None} if
the regular name is to be used.

@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,
            is_lazy=0)])
@end example
@end deffn

@node Control flow,Pattern matching,Statements,Node classes
@anchor{library/ast control-flow}@anchor{4e98}
@subsubsection Control flow


@cartouche
@quotation Σημείωση 
Optional clauses such as @code{else} are stored as an empty list if they’re
not present.
@end quotation
@end cartouche

@geindex If (κλάση σε ast)
@anchor{library/ast ast If}@anchor{4e99}
@deffn {Κλάση} ast.If (test, body, orelse)

An @code{if} statement. @code{test} holds a single node, such as a @ref{4d63,,Compare}
node. @code{body} and @code{orelse} each hold a list of nodes.

@code{elif} clauses don’t have a special representation in the AST, but rather
appear as extra @code{If} nodes within the @code{orelse} section of the
previous one.

@example
>>> print(ast.dump(ast.parse("""
... if x:
...    ...
... elif y:
...    ...
... else:
...    ...
... """), indent=4))
Module(
    body=[
        If(
            test=Name(id='x'),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                If(
                    test=Name(id='y'),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))],
                    orelse=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example
@end deffn

@geindex For (κλάση σε ast)
@anchor{library/ast ast For}@anchor{4e9a}
@deffn {Κλάση} 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{1f17,,Name}, @ref{4d73,,Tuple}, @ref{4d72,,List}, @ref{4d6f,,Attribute} or
@ref{4d70,,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 (ιδιότητα της ast.For)
@anchor{library/ast ast For type_comment}@anchor{4e9b}
@deffn {Ιδιότητα} type_comment

@code{type_comment} is an optional string with the type annotation as a comment.
@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'),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))])])
@end example
@end deffn

@geindex While (κλάση σε ast)
@anchor{library/ast ast While}@anchor{4e9c}
@deffn {Κλάση} ast.While (test, body, orelse)

A @code{while} loop. @code{test} holds the condition, such as a @ref{4d63,,Compare}
node.

@example
>>> print(ast.dump(ast.parse("""
... while x:
...    ...
... else:
...    ...
... """), indent=4))
Module(
    body=[
        While(
            test=Name(id='x'),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))])])
@end example
@end deffn

@geindex Break (κλάση σε ast)
@geindex Continue (κλάση σε ast)
@anchor{library/ast ast Break}@anchor{4e9d}
@deffn {Κλάση} ast.Break
@anchor{library/ast ast Continue}@anchor{4e9e}
@deffnx {Κλάση} ast.Continue

The @code{break} and @code{continue} statements.

@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'),
            body=[
                If(
                    test=Compare(
                        left=Name(id='a'),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=5)]),
                    body=[
                        Break()],
                    orelse=[
                        Continue()])])])
@end example
@end deffn

@geindex Try (κλάση σε ast)
@anchor{library/ast ast Try}@anchor{4e9f}
@deffn {Κλάση} ast.Try (body, handlers, orelse, finalbody)

@code{try} blocks. All attributes are list of nodes to execute, except for
@code{handlers}, which is a list of @ref{4ea0,,ExceptHandler} nodes.

@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'),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                ExceptHandler(
                    type=Name(id='OtherException'),
                    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 (κλάση σε ast)
@anchor{library/ast ast TryStar}@anchor{4ea1}
@deffn {Κλάση} ast.TryStar (body, handlers, orelse, finalbody)

@code{try} blocks which are followed by @code{except*} clauses. The attributes are the
same as for @ref{4e9f,,Try} but the @ref{4ea0,,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'),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Added in version 3.11.

@end deffn

@geindex ExceptHandler (κλάση σε ast)
@anchor{library/ast ast ExceptHandler}@anchor{4ea0}
@deffn {Κλάση} ast.ExceptHandler (type, name, body)

A single @code{except} clause. @code{type} is the exception type it will match,
typically a @ref{1f17,,Name} node (or @code{None} for a catch-all @code{except:} clause).
@code{name} is a raw string for the name to hold the exception, or @code{None} if
the clause doesn’t have @code{as foo}. @code{body} is a list of nodes.

@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'),
                        op=Add(),
                        right=Constant(value=1)))],
            handlers=[
                ExceptHandler(
                    type=Name(id='TypeError'),
                    body=[
                        Pass()])])])
@end example
@end deffn

@geindex With (κλάση σε ast)
@anchor{library/ast ast With}@anchor{4ea2}
@deffn {Κλάση} ast.With (items, body, type_comment)

A @code{with} block. @code{items} is a list of @ref{4ea3,,withitem} nodes representing
the context managers, and @code{body} is the indented block inside the context.

@geindex type_comment (ιδιότητα της ast.With)
@anchor{library/ast ast With type_comment}@anchor{4ea4}
@deffn {Ιδιότητα} type_comment

@code{type_comment} is an optional string with the type annotation as a comment.
@end deffn
@end deffn

@geindex withitem (κλάση σε ast)
@anchor{library/ast ast withitem}@anchor{4ea3}
@deffn {Κλάση} ast.withitem (context_expr, optional_vars)

A single context manager in a @code{with} block. @code{context_expr} is the context
manager, often a @ref{4d6e,,Call} node. @code{optional_vars} is a @ref{1f17,,Name},
@ref{4d73,,Tuple} or @ref{4d72,,List} for the @code{as foo} part, or @code{None} if that
isn’t used.

@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'),
                    optional_vars=Name(id='b', ctx=Store())),
                withitem(
                    context_expr=Name(id='c'),
                    optional_vars=Name(id='d', ctx=Store()))],
            body=[
                Expr(
                    value=Call(
                        func=Name(id='something'),
                        args=[
                            Name(id='b'),
                            Name(id='d')]))])])
@end example
@end deffn

@node Pattern matching,Type annotations,Control flow,Node classes
@anchor{library/ast pattern-matching}@anchor{4ea5}
@subsubsection Pattern matching


@geindex Match (κλάση σε ast)
@anchor{library/ast ast Match}@anchor{4ea6}
@deffn {Κλάση} 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{4ea7,,match_case} nodes with the different cases.


Added in version 3.10.

@end deffn

@geindex match_case (κλάση σε ast)
@anchor{library/ast ast match_case}@anchor{4ea7}
@deffn {Κλάση} 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{2ec,,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'),
            cases=[
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchAs(name='x')]),
                    guard=Compare(
                        left=Name(id='x'),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=0)]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='tuple')),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Added in version 3.10.

@end deffn

@geindex MatchValue (κλάση σε ast)
@anchor{library/ast ast MatchValue}@anchor{4ea8}
@deffn {Κλάση} 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'),
            cases=[
                match_case(
                    pattern=MatchValue(
                        value=Constant(value='Relevant')),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Added in version 3.10.

@end deffn

@geindex MatchSingleton (κλάση σε ast)
@anchor{library/ast ast MatchSingleton}@anchor{4ea9}
@deffn {Κλάση} 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'),
            cases=[
                match_case(
                    pattern=MatchSingleton(value=None),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Added in version 3.10.

@end deffn

@geindex MatchSequence (κλάση σε ast)
@anchor{library/ast ast MatchSequence}@anchor{4eaa}
@deffn {Κλάση} 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'),
            cases=[
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchValue(
                                value=Constant(value=1)),
                            MatchValue(
                                value=Constant(value=2))]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Added in version 3.10.

@end deffn

@geindex MatchStar (κλάση σε ast)
@anchor{library/ast ast MatchStar}@anchor{4eab}
@deffn {Κλάση} 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'),
            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


Added in version 3.10.

@end deffn

@geindex MatchMapping (κλάση σε ast)
@anchor{library/ast ast MatchMapping}@anchor{4eac}
@deffn {Κλάση} 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'),
            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


Added in version 3.10.

@end deffn

@geindex MatchClass (κλάση σε ast)
@anchor{library/ast ast MatchClass}@anchor{4ead}
@deffn {Κλάση} 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'),
            cases=[
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='Point2D'),
                        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'),
                        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


Added in version 3.10.

@end deffn

@geindex MatchAs (κλάση σε ast)
@anchor{library/ast ast MatchAs}@anchor{4eae}
@deffn {Κλάση} 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'),
            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


Added in version 3.10.

@end deffn

@geindex MatchOr (κλάση σε ast)
@anchor{library/ast ast MatchOr}@anchor{4eaf}
@deffn {Κλάση} 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'),
            cases=[
                match_case(
                    pattern=MatchOr(
                        patterns=[
                            MatchSequence(
                                patterns=[
                                    MatchAs(name='x')]),
                            MatchAs(name='y')]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Added in version 3.10.

@end deffn

@node Type annotations,Type parameters,Pattern matching,Node classes
@anchor{library/ast type-annotations}@anchor{4eb0}
@subsubsection Type annotations


@geindex TypeIgnore (κλάση σε ast)
@anchor{library/ast ast TypeIgnore}@anchor{1d0d}
@deffn {Κλάση} ast.TypeIgnore (lineno, tag)

A @code{# type: ignore} comment located at `lineno'.
`tag' is the optional tag specified by the form @code{# type: ignore <tag>}.

@example
>>> print(ast.dump(ast.parse('x = 1 # type: ignore', type_comments=True), indent=4))
Module(
    body=[
        Assign(
            targets=[
                Name(id='x', ctx=Store())],
            value=Constant(value=1))],
    type_ignores=[
        TypeIgnore(lineno=1, tag='@w{'})])
>>> print(ast.dump(ast.parse('x: bool = 1 # type: ignore[assignment]', type_comments=True), indent=4))
Module(
    body=[
        AnnAssign(
            target=Name(id='x', ctx=Store()),
            annotation=Name(id='bool'),
            value=Constant(value=1),
            simple=1)],
    type_ignores=[
        TypeIgnore(lineno=1, tag='[assignment]')])
@end example

@cartouche
@quotation Σημείωση 
@code{TypeIgnore} nodes are not generated when the `type_comments' parameter
is set to @code{False} (default).  See @ref{1c9,,ast.parse()} for more details.
@end quotation
@end cartouche


Added in version 3.8.

@end deffn

@node Type parameters,Function and class definitions,Type annotations,Node classes
@anchor{library/ast ast-type-params}@anchor{4e94}@anchor{library/ast type-parameters}@anchor{4eb1}
@subsubsection Type parameters


@ref{7a5,,Type parameters} can exist on classes, functions, and type
aliases.

@geindex TypeVar (κλάση σε ast)
@anchor{library/ast ast TypeVar}@anchor{4eb2}
@deffn {Κλάση} ast.TypeVar (name, bound, default_value)

A @ref{294,,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{4d73,,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'),
                    default_value=Name(id='bool'))],
            value=Subscript(
                value=Name(id='list'),
                slice=Name(id='T')))])
@end example


Added in version 3.12.



Άλλαξε στην έκδοση 3.13: Added the `default_value' parameter.

@end deffn

@geindex ParamSpec (κλάση σε ast)
@anchor{library/ast ast ParamSpec}@anchor{4eb3}
@deffn {Κλάση} ast.ParamSpec (name, default_value)

A @ref{295,,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'),
                            Name(id='str')]))],
            value=Subscript(
                value=Name(id='Callable'),
                slice=Tuple(
                    elts=[
                        Name(id='P'),
                        Name(id='int')])))])
@end example


Added in version 3.12.



Άλλαξε στην έκδοση 3.13: Added the `default_value' parameter.

@end deffn

@geindex TypeVarTuple (κλάση σε ast)
@anchor{library/ast ast TypeVarTuple}@anchor{4eb4}
@deffn {Κλάση} ast.TypeVarTuple (name, default_value)

A @ref{293,,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())],
            value=Subscript(
                value=Name(id='tuple'),
                slice=Tuple(
                    elts=[
                        Starred(
                            value=Name(id='Ts'))])))])
@end example


Added in version 3.12.



Άλλαξε στην έκδοση 3.13: Added the `default_value' parameter.

@end deffn

@node Function and class definitions,Async and await,Type parameters,Node classes
@anchor{library/ast function-and-class-definitions}@anchor{4eb5}
@subsubsection Function and class definitions


@geindex FunctionDef (κλάση σε ast)
@anchor{library/ast ast FunctionDef}@anchor{1c7e}
@deffn {Κλάση} ast.FunctionDef (name, args, body, decorator_list, returns, type_comment, type_params)

A function definition.


@itemize *

@item 
@code{name} is a raw string of the function name.

@item 
@code{args} is an @ref{4eb6,,arguments} node.

@item 
@code{body} is the list of nodes inside the function.

@item 
@code{decorator_list} is the list of decorators to be applied, stored outermost
first (i.e. the first in the list will be applied last).

@item 
@code{returns} is the return annotation.

@item 
@code{type_params} is a list of @ref{4e94,,type parameters}.
@end itemize

@geindex type_comment (ιδιότητα της ast.FunctionDef)
@anchor{library/ast ast FunctionDef type_comment}@anchor{4eb7}
@deffn {Ιδιότητα} type_comment

@code{type_comment} is an optional string with the type annotation as a comment.
@end deffn


Άλλαξε στην έκδοση 3.12: Added @code{type_params}.

@end deffn

@geindex Lambda (κλάση σε ast)
@anchor{library/ast ast Lambda}@anchor{4d78}
@deffn {Κλάση} ast.Lambda (args, body)

@code{lambda} is a minimal function definition that can be used inside an
expression. Unlike @ref{1c7e,,FunctionDef}, @code{body} holds a single node.

@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 (κλάση σε ast)
@anchor{library/ast ast arguments}@anchor{4eb6}
@deffn {Κλάση} ast.arguments (posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults)

The arguments for a function.


@itemize *

@item 
@code{posonlyargs}, @code{args} and @code{kwonlyargs} are lists of @ref{4eb8,,arg} nodes.

@item 
@code{vararg} and @code{kwarg} are single @ref{4eb8,,arg} nodes, referring to the
@code{*args, **kwargs} parameters.

@item 
@code{kw_defaults} is a list of default values for keyword-only arguments. If
one is @code{None}, the corresponding argument is required.

@item 
@code{defaults} is a list of default values for arguments that can be passed
positionally. If there are fewer defaults, they correspond to the last n
arguments.
@end itemize
@end deffn

@geindex arg (κλάση σε ast)
@anchor{library/ast ast arg}@anchor{4eb8}
@deffn {Κλάση} 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{1f17,,Name} node.

@geindex type_comment (ιδιότητα της ast.arg)
@anchor{library/ast ast arg type_comment}@anchor{4eb9}
@deffn {Ιδιότητα} type_comment

@code{type_comment} is an optional string with the type annotation as a comment
@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'),
                Name(id='decorator2')],
            returns=Constant(value='return annotation'))])
@end example
@end deffn

@geindex Return (κλάση σε ast)
@anchor{library/ast ast Return}@anchor{4eba}
@deffn {Κλάση} ast.Return (value)

A @code{return} statement.

@example
>>> print(ast.dump(ast.parse('return 4'), indent=4))
Module(
    body=[
        Return(
            value=Constant(value=4))])
@end example
@end deffn

@geindex Yield (κλάση σε ast)
@geindex YieldFrom (κλάση σε ast)
@anchor{library/ast ast Yield}@anchor{4d7f}
@deffn {Κλάση} ast.Yield (value)
@anchor{library/ast ast YieldFrom}@anchor{4d80}
@deffnx {Κλάση} ast.YieldFrom (value)

A @code{yield} or @code{yield from} expression. Because these are expressions, they
must be wrapped in an @ref{4e77,,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')))])

>>> print(ast.dump(ast.parse('yield from x'), indent=4))
Module(
    body=[
        Expr(
            value=YieldFrom(
                value=Name(id='x')))])
@end example
@end deffn

@geindex Global (κλάση σε ast)
@geindex Nonlocal (κλάση σε ast)
@anchor{library/ast ast Global}@anchor{4ebb}
@deffn {Κλάση} ast.Global (names)
@anchor{library/ast ast Nonlocal}@anchor{4ebc}
@deffnx {Κλάση} ast.Nonlocal (names)

@code{global} and @code{nonlocal} statements. @code{names} is a list of raw strings.

@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 (κλάση σε ast)
@anchor{library/ast ast ClassDef}@anchor{1c7c}
@deffn {Κλάση} ast.ClassDef (name, bases, keywords, body, decorator_list, type_params)

A class definition.


@itemize *

@item 
@code{name} is a raw string for the class name

@item 
@code{bases} is a list of nodes for explicitly specified base classes.

@item 
@code{keywords} is a list of @ref{4e87,,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 
@code{body} is a list of nodes representing the code within the class
definition.

@item 
@code{decorator_list} is a list of nodes, as in @ref{1c7e,,FunctionDef}.

@item 
@code{type_params} is a list of @ref{4e94,,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'),
                Name(id='base2')],
            keywords=[
                keyword(
                    arg='metaclass',
                    value=Name(id='meta'))],
            body=[
                Pass()],
            decorator_list=[
                Name(id='decorator1'),
                Name(id='decorator2')])])
@end example


Άλλαξε στην έκδοση 3.12: Added @code{type_params}.

@end deffn

@node Async and await,,Function and class definitions,Node classes
@anchor{library/ast async-and-await}@anchor{4ebd}
@subsubsection Async and await


@geindex AsyncFunctionDef (κλάση σε ast)
@anchor{library/ast ast AsyncFunctionDef}@anchor{1c7d}
@deffn {Κλάση} ast.AsyncFunctionDef (name, args, body, decorator_list, returns, type_comment, type_params)

An @code{async def} function definition. Has the same fields as
@ref{1c7e,,FunctionDef}.


Άλλαξε στην έκδοση 3.12: Added @code{type_params}.

@end deffn

@geindex Await (κλάση σε ast)
@anchor{library/ast ast Await}@anchor{4d7e}
@deffn {Κλάση} ast.Await (value)

An @code{await} expression. @code{value} is what it waits for.
Only valid in the body of an @ref{1c7d,,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'))))])])
@end example

@geindex AsyncFor (κλάση σε ast)
@geindex AsyncWith (κλάση σε ast)
@anchor{library/ast ast AsyncFor}@anchor{4ebe}
@deffn {Κλάση} ast.AsyncFor (target, iter, body, orelse, type_comment)
@anchor{library/ast ast AsyncWith}@anchor{4ebf}
@deffnx {Κλάση} ast.AsyncWith (items, body, type_comment)

@code{async for} loops and @code{async with} context managers. They have the same
fields as @ref{4e9a,,For} and @ref{4ea2,,With}, respectively. Only valid in the
body of an @ref{1c7d,,AsyncFunctionDef}.
@end deffn

@cartouche
@quotation Σημείωση 
When a string is parsed by @ref{1c9,,ast.parse()}, operator nodes (subclasses
of @code{ast.operator}, @code{ast.unaryop}, @code{ast.cmpop},
@code{ast.boolop} and @code{ast.expr_context}) on the returned tree
will be singletons. Changes to one will be reflected in all other
occurrences of the same value (for example, @ref{4e78,,ast.Add}).
@end quotation
@end cartouche

@node ast helpers,Compiler flags<2>,Node classes,ast — Abstract syntax trees
@anchor{library/ast ast-helpers}@anchor{4ec0}
@subsubsection @code{ast} helpers


Apart from the node classes, the @code{ast} module defines these utility functions
and classes for traversing abstract syntax trees:

@geindex parse() (στη μονάδα ast)
@anchor{library/ast ast parse}@anchor{1c9}
@deffn {Συνάρτηση} ast.parse (source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None, optimize=-1, module=None)

Parse the source into an AST node.  Equivalent to @code{compile(source,
filename, mode, flags=FLAGS_VALUE, optimize=optimize, module=module)},
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{4ec1,,ast.PyCF_TYPE_COMMENTS} to the
flags passed to @ref{1c8,,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{4e6c,,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{1d4,,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{277,,ValueError} is raised.

@cartouche
@quotation Προειδοποίηση 
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{17e,,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{1c9,,ast.parse()} won’t do any scoping checks, which the
compilation step does.
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
It is possible to crash the Python interpreter with a
sufficiently large/complex string due to stack depth limitations
in Python’s AST compiler.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.8: Added @code{type_comments}, @code{mode='func_type'} and @code{feature_version}.



Άλλαξε στην έκδοση 3.13: The minimum supported version for @code{feature_version} is now @code{(3, 7)}.
The @code{optimize} argument was added.



Added in version 3.15: Added the `module' parameter.

@end deffn

@geindex unparse() (στη μονάδα ast)
@anchor{library/ast ast unparse}@anchor{cb6}
@deffn {Συνάρτηση} ast.unparse (ast_obj)

Unparse an @ref{2ec,,ast.AST} object and generate a string with code
that would produce an equivalent @code{ast.AST} object if parsed
back with @ref{1c9,,ast.parse()}.

@cartouche
@quotation Προειδοποίηση 
The produced code string will not necessarily be equal to the original
code that generated the @ref{2ec,,ast.AST} object (without any compiler
optimizations, such as constant tuples/frozensets).
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
Trying to unparse a highly complex expression would result with
@ref{1121,,RecursionError}.
@end quotation
@end cartouche


Added in version 3.9.

@end deffn

@geindex literal_eval() (στη μονάδα ast)
@anchor{library/ast ast literal_eval}@anchor{fd7}
@deffn {Συνάρτηση} 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{184,,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 Προειδοποίηση 
It is possible to crash the Python interpreter due to stack depth
limitations in Python’s AST compiler.

It can raise @ref{277,,ValueError}, @ref{291,,TypeError}, @ref{17e,,SyntaxError},
@ref{18fa,,MemoryError} and @ref{1121,,RecursionError} depending on the malformed
input.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.2: Now allows bytes and set literals.



Άλλαξε στην έκδοση 3.9: Now supports creating empty sets with @code{'set()'}.



Άλλαξε στην έκδοση 3.10: For string inputs, leading spaces and tabs are now stripped.

@end deffn

@geindex get_docstring() (στη μονάδα ast)
@anchor{library/ast ast get_docstring}@anchor{2028}
@deffn {Συνάρτηση} ast.get_docstring (node, clean=True)

Return the docstring of the given `node' (which must be a
@ref{1c7e,,FunctionDef}, @ref{1c7d,,AsyncFunctionDef}, @ref{1c7c,,ClassDef},
or @ref{4e6c,,Module} node), or @code{None} if it has no docstring.
If `clean' is true, clean up the docstring’s indentation with
@ref{1c34,,inspect.cleandoc()}.


Άλλαξε στην έκδοση 3.5: @ref{1c7d,,AsyncFunctionDef} is now supported.

@end deffn

@geindex get_source_segment() (στη μονάδα ast)
@anchor{library/ast ast get_source_segment}@anchor{d9c}
@deffn {Συνάρτηση} ast.get_source_segment (source, node, *, padded=False)

Get source code segment of the `source' that generated `node'.
If some location information (@ref{4e66,,lineno}, @ref{4e68,,end_lineno},
@ref{4e67,,col_offset}, or @ref{4e69,,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.


Added in version 3.8.

@end deffn

@geindex fix_missing_locations() (στη μονάδα ast)
@anchor{library/ast ast fix_missing_locations}@anchor{4ec2}
@deffn {Συνάρτηση} ast.fix_missing_locations (node)

When you compile a node tree with @ref{1c8,,compile()}, the compiler expects
@ref{4e66,,lineno} and @ref{4e67,,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() (στη μονάδα ast)
@anchor{library/ast ast increment_lineno}@anchor{1d0c}
@deffn {Συνάρτηση} ast.increment_lineno (node, n=1)

Increment the line number and end line number of each node in the tree
starting at `node' by `n'. This is useful to «move code» to a different
location in a file.
@end deffn

@geindex copy_location() (στη μονάδα ast)
@anchor{library/ast ast copy_location}@anchor{4ec3}
@deffn {Συνάρτηση} ast.copy_location (new_node, old_node)

Copy source location (@ref{4e66,,lineno}, @ref{4e67,,col_offset}, @ref{4e68,,end_lineno},
and @ref{4e69,,end_col_offset}) from `old_node' to `new_node' if possible,
and return `new_node'.
@end deffn

@geindex iter_fields() (στη μονάδα ast)
@anchor{library/ast ast iter_fields}@anchor{4ec4}
@deffn {Συνάρτηση} ast.iter_fields (node)

Yield a tuple of @code{(fieldname, value)} for each field in @code{node._fields}
that is present on `node'.
@end deffn

@geindex iter_child_nodes() (στη μονάδα ast)
@anchor{library/ast ast iter_child_nodes}@anchor{4ec5}
@deffn {Συνάρτηση} ast.iter_child_nodes (node)

Yield all direct child nodes of `node', that is, all fields that are nodes
and all items of fields that are lists of nodes.
@end deffn

@geindex walk() (στη μονάδα ast)
@anchor{library/ast ast walk}@anchor{4ec6}
@deffn {Συνάρτηση} ast.walk (node)

Recursively yield all descendant nodes in the tree starting at `node'
(including `node' itself), in no specified order.  This is useful if you only
want to modify nodes in place and don’t care about the context.
@end deffn

@geindex NodeVisitor (κλάση σε ast)
@anchor{library/ast ast NodeVisitor}@anchor{56a}
@deffn {Κλάση} ast.NodeVisitor

A node visitor base class that walks the abstract syntax tree and calls a
visitor function for every node found.  This function may return a value
which is forwarded by the @ref{4ec7,,visit()} method.

This class is meant to be subclassed, with the subclass adding visitor
methods.

@geindex visit() (μέθοδος της ast.NodeVisitor)
@anchor{library/ast ast NodeVisitor visit}@anchor{4ec7}
@deffn {Μέθοδος} visit (node)

Visit a node.  The default implementation calls the method called
@code{self.visit_@var{classname}} where `classname' is the name of the node
class, or @ref{4ec8,,generic_visit()} if that method doesn’t exist.
@end deffn

@geindex generic_visit() (μέθοδος της ast.NodeVisitor)
@anchor{library/ast ast NodeVisitor generic_visit}@anchor{4ec8}
@deffn {Μέθοδος} generic_visit (node)

This visitor calls @ref{4ec7,,visit()} on all children of the node.

Note that child nodes of nodes that have a custom visitor method won’t be
visited unless the visitor calls @code{generic_visit()} or visits them
itself.
@end deffn

@geindex visit_Constant() (μέθοδος της ast.NodeVisitor)
@anchor{library/ast ast NodeVisitor visit_Constant}@anchor{e32}
@deffn {Μέθοδος} visit_Constant (node)

Handles all constant nodes.
@end deffn

Don’t use the @code{NodeVisitor} if you want to apply changes to nodes
during traversal.  For this a special visitor exists
(@ref{4ec9,,NodeTransformer}) that allows modifications.


Καταργήθηκε από την έκδοση 3.8, αφαιρέθηκε στην έκδοση 3.14: Methods @code{visit_Num()}, @code{visit_Str()}, @code{visit_Bytes()},
@code{visit_NameConstant()} and @code{visit_Ellipsis()} will not be called
in Python 3.14+.  Add the @ref{e32,,visit_Constant()} method instead to handle
all constant nodes.

@end deffn

@geindex NodeTransformer (κλάση σε ast)
@anchor{library/ast ast NodeTransformer}@anchor{4ec9}
@deffn {Κλάση} ast.NodeTransformer

A @ref{56a,,NodeVisitor} subclass that walks the abstract syntax tree and
allows modification of nodes.

The @code{NodeTransformer} will walk the AST and use the return value of
the visitor methods to replace or remove the old node.  If the return value
of the visitor method is @code{None}, the node will be removed from its
location, otherwise it is replaced with the return value.  The return value
may be the original node in which case no replacement takes place.

Here is an example transformer that rewrites all occurrences of name lookups
(@code{foo}) to @code{data['foo']}:

@example
class RewriteName(NodeTransformer):

    def visit_Name(self, node):
        return Subscript(
            value=Name(id='data'),
            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{4ec8,,generic_visit()}
method for the node first.

For nodes that were part of a collection of statements (that applies to all
statement nodes), the visitor may also return a list of nodes rather than
just a single node.

If @code{NodeTransformer} introduces new nodes (that weren’t part of
original tree) without giving them location information (such as
@ref{4e66,,lineno}), @ref{4ec2,,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

Usually you use the transformer like this:

@example
node = YourTransformer().visit(node)
@end example
@end deffn

@geindex dump() (στη μονάδα ast)
@anchor{library/ast ast dump}@anchor{1e1}
@deffn {Συνάρτηση} ast.dump (node, annotate_fields=True, include_attributes=False, *, color=False, indent=None, show_empty=False)

Return a formatted dump of the tree in `node'.  This is mainly useful for
debugging purposes.  If `annotate_fields' is true (by default),
the returned string will show the names and the values for fields.
If `annotate_fields' is false, the result string will be more compact by
omitting unambiguous field names.  Attributes such as line
numbers and column offsets are not dumped by default.  If this is wanted,
`include_attributes' can be set to true.

If `color' is @code{True}, the returned string is syntax highlighted using
ANSI escape sequences.
If @code{False} (the default), colored output is always disabled.

If `indent' is a non-negative integer or string, then the tree will be
pretty-printed with that indent level.  An indent level
of 0, negative, or @code{""} will only insert newlines.  @code{None} (the default)
selects the single line representation. Using a positive integer indent
indents that many spaces per level.  If `indent' is a string (such as @code{"\t"}),
that string is used to indent each level.

If `show_empty' is false (the default), optional empty lists and
@code{Load()} values will be omitted from the output.
Optional @code{None} values are always omitted.

@example
>>> tree = ast.parse('print(None)', '?', 'eval')
>>> print(ast.dump(tree, indent=4))
Expression(
    body=Call(
        func=Name(id='print'),
        args=[
            Constant(value=None)]))
>>> print(ast.dump(tree, indent=4, show_empty=True))
Expression(
    body=Call(
        func=Name(id='print', ctx=Load()),
        args=[
            Constant(value=None)],
        keywords=[]))
@end example


Άλλαξε στην έκδοση 3.9: Added the `indent' option.



Άλλαξε στην έκδοση 3.13: Added the `show_empty' option.



Άλλαξε στην έκδοση 3.15: Omit optional @code{Load()} values by default.



Άλλαξε στην έκδοση 3.15: Added the `color' parameter.

@end deffn

@geindex compare() (στη μονάδα ast)
@anchor{library/ast ast compare}@anchor{459}
@deffn {Συνάρτηση} ast.compare (a, b, /, *, compare_attributes=False)

Recursively compares two ASTs.

`compare_attributes' affects whether AST attributes are considered
in the comparison. If `compare_attributes' is @code{False} (default), then
attributes are ignored. Otherwise they must all be equal. This
option is useful to check whether the ASTs are structurally equal but
differ in whitespace or similar details. Attributes include line numbers
and column offsets.


Added in version 3.14.

@end deffn

@node Compiler flags<2>,Command-line usage<5>,ast helpers,ast — Abstract syntax trees
@anchor{library/ast ast-compiler-flags}@anchor{27c0}@anchor{library/ast compiler-flags}@anchor{4eca}
@subsubsection Compiler flags


The following flags may be passed to @ref{1c8,,compile()} in order to change
effects on the compilation of a program:

@geindex PyCF_ALLOW_TOP_LEVEL_AWAIT (στη μονάδα ast)
@anchor{library/ast ast PyCF_ALLOW_TOP_LEVEL_AWAIT}@anchor{4ecb}
@deffn {Δεδομένα} ast.PyCF_ALLOW_TOP_LEVEL_AWAIT

Enables support for top-level @code{await}, @code{async for}, @code{async with}
and async comprehensions.


Added in version 3.8.

@end deffn

@geindex PyCF_ONLY_AST (στη μονάδα ast)
@anchor{library/ast ast PyCF_ONLY_AST}@anchor{4e62}
@deffn {Δεδομένα} ast.PyCF_ONLY_AST

Generates and returns an abstract syntax tree instead of returning a
compiled code object.
@end deffn

@geindex PyCF_OPTIMIZED_AST (στη μονάδα ast)
@anchor{library/ast ast PyCF_OPTIMIZED_AST}@anchor{4ecc}
@deffn {Δεδομένα} ast.PyCF_OPTIMIZED_AST

The returned AST is optimized according to the `optimize' argument
in @ref{1c8,,compile()} or @ref{1c9,,ast.parse()}.


Added in version 3.13.

@end deffn

@geindex PyCF_TYPE_COMMENTS (στη μονάδα ast)
@anchor{library/ast ast PyCF_TYPE_COMMENTS}@anchor{4ec1}
@deffn {Δεδομένα} ast.PyCF_TYPE_COMMENTS

Enables support for 
@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/} style type comments
(@code{# type: <type>}, @code{# type: ignore <stuff>}).


Added in version 3.8.

@end deffn

@node Command-line usage<5>,,Compiler flags<2>,ast — Abstract syntax trees
@anchor{library/ast ast-cli}@anchor{1e2}@anchor{library/ast command-line-usage}@anchor{4ecd}
@subsubsection Command-line usage



Added in version 3.9.



Άλλαξε στην έκδοση 3.15: The output is now syntax highlighted by default. This can be
@ref{1af,,controlled using environment variables}.


The @code{ast} module can be executed as a script from the command line.
It is as simple as:

@example
python -m ast [-m <mode>] [-a] [infile]
@end example

The following options are accepted:

@geindex ast command line option; -h
@geindex ast command line option; --help
@anchor{library/ast cmdoption-ast-h}@anchor{4ece}@anchor{library/ast cmdoption-ast-help}@anchor{4ecf}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Show the help message and exit.
@end deffn

@geindex ast command line option; -m
@geindex ast command line option; --mode
@anchor{library/ast cmdoption-ast-m}@anchor{4ed0}
@deffn {Option} @w{-}m <mode>
@anchor{library/ast cmdoption-ast-mode}@anchor{4ed1}
@deffnx {Option} @w{-}@w{-}mode <mode>

Specify what kind of code must be compiled, like the `mode' argument
in @ref{1c9,,parse()}.
@end deffn

@geindex ast command line option; --no-type-comments
@anchor{library/ast cmdoption-ast-no-type-comments}@anchor{4ed2}
@deffn {Option} @w{-}@w{-}no@w{-}type@w{-}comments

Don’t parse type comments.
@end deffn

@geindex ast command line option; -a
@geindex ast command line option; --include-attributes
@anchor{library/ast cmdoption-ast-a}@anchor{4ed3}@anchor{library/ast cmdoption-ast-include-attributes}@anchor{4ed4}
@deffn {Option} @w{-}a, @w{-}@w{-}include@w{-}attributes

Include attributes such as line numbers and column offsets.
@end deffn

@geindex ast command line option; -i
@geindex ast command line option; --indent
@anchor{library/ast cmdoption-ast-i}@anchor{4ed5}
@deffn {Option} @w{-}i <indent>
@anchor{library/ast cmdoption-ast-indent}@anchor{4ed6}
@deffnx {Option} @w{-}@w{-}indent <indent>

Indentation of nodes in AST (number of spaces).
@end deffn

@geindex ast command line option; --feature-version
@anchor{library/ast cmdoption-ast-feature-version}@anchor{45c}
@deffn {Option} @w{-}@w{-}feature@w{-}version <version>

Python version in the format 3.x (for example, 3.10). Defaults to the
current version of the interpreter.


Added in version 3.14.

@end deffn

@geindex ast command line option; -O
@geindex ast command line option; --optimize
@anchor{library/ast cmdoption-ast-O}@anchor{4ed7}
@deffn {Option} @w{-}O <level>
@anchor{library/ast cmdoption-ast-optimize}@anchor{45d}
@deffnx {Option} @w{-}@w{-}optimize <level>

Optimization level for parser. Defaults to no optimization.


Added in version 3.14.

@end deffn

@geindex ast command line option; --show-empty
@anchor{library/ast cmdoption-ast-show-empty}@anchor{45e}
@deffn {Option} @w{-}@w{-}show@w{-}empty

Show empty lists and fields that are @code{None}. Defaults to not showing empty
objects.


Added in version 3.14.

@end deffn

If @code{infile} is specified its contents are parsed to AST and dumped
to stdout.  Otherwise, the content is read from stdin.


@subsubheading Δείτε επίσης


Green Tree Snakes@footnote{https://greentreesnakes.readthedocs.io/}, an external
documentation resource, has good details on working with Python ASTs.

ASTTokens@footnote{https://asttokens.readthedocs.io/en/latest/user-guide.html}
annotates Python ASTs with the positions of tokens and text in the source
code that generated them. This is helpful for tools that make source code
transformations.

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/} parses code as a Concrete Syntax
Tree that looks like an ast tree and keeps all formatting details. It’s
useful for building automated refactoring (codemod) applications and
linters.

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.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node symtable — Access to the compiler’s symbol tables,token — Constants used with Python parse trees,ast — Abstract syntax trees,Python Language Services
@anchor{library/symtable doc}@anchor{4ed8}@anchor{library/symtable module-symtable}@anchor{e1}@anchor{library/symtable symtable-access-to-the-compiler-s-symbol-tables}@anchor{4ed9}@anchor{library/symtable translation-repo}@anchor{4eda}
@subsection @code{symtable} — Access to the compiler’s symbol tables


@geindex module; symtable

`Source code:' Lib/symtable.py@footnote{https://github.com/python/cpython/tree/main/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.  @code{symtable} provides an interface to examine these
tables.

@menu
* Generating Symbol Tables:: 
* Examining Symbol Tables:: 
* Command-Line Usage: Command-Line Usage<2>. 

@end menu

@node Generating Symbol Tables,Examining Symbol Tables,,symtable — Access to the compiler’s symbol tables
@anchor{library/symtable generating-symbol-tables}@anchor{4edb}
@subsubsection Generating Symbol Tables


@geindex symtable() (στη μονάδα symtable)
@anchor{library/symtable symtable symtable}@anchor{1ca}
@deffn {Συνάρτηση} symtable.symtable (code, filename, compile_type, *, module=None)

Return the toplevel @ref{4edc,,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{1c8,,compile()}.
The optional argument `module' specifies the module name.
It is needed to unambiguous @ref{1cc,,filter} syntax warnings
by module name.


Added in version 3.15: Added the `module' parameter.

@end deffn

@node Examining Symbol Tables,Command-Line Usage<2>,Generating Symbol Tables,symtable — Access to the compiler’s symbol tables
@anchor{library/symtable examining-symbol-tables}@anchor{4edd}
@subsubsection Examining Symbol Tables


@geindex SymbolTableType (κλάση σε symtable)
@anchor{library/symtable symtable SymbolTableType}@anchor{1b66}
@deffn {Κλάση} symtable.SymbolTableType

An enumeration indicating the type of a @ref{4edc,,SymbolTable} object.

@geindex MODULE (ιδιότητα της symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType MODULE}@anchor{4ede}
@deffn {Ιδιότητα} MODULE = "module"

Used for the symbol table of a module.
@end deffn

@geindex FUNCTION (ιδιότητα της symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType FUNCTION}@anchor{4edf}
@deffn {Ιδιότητα} FUNCTION = "function"

Used for the symbol table of a function.
@end deffn

@geindex CLASS (ιδιότητα της symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType CLASS}@anchor{4ee0}
@deffn {Ιδιότητα} CLASS = "class"

Used for the symbol table of a class.
@end deffn

The following members refer to different flavors of
@ref{6b4,,annotation scopes}.

@geindex ANNOTATION (ιδιότητα της symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType ANNOTATION}@anchor{4ee1}
@deffn {Ιδιότητα} ANNOTATION = "annotation"

Used for annotations if @code{from __future__ import annotations} is active.
@end deffn

@geindex TYPE_ALIAS (ιδιότητα της symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType TYPE_ALIAS}@anchor{4ee2}
@deffn {Ιδιότητα} TYPE_ALIAS = "type alias"

Used for the symbol table of @ref{85a,,type} constructions.
@end deffn

@geindex TYPE_PARAMETERS (ιδιότητα της symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType TYPE_PARAMETERS}@anchor{4ee3}
@deffn {Ιδιότητα} TYPE_PARAMETERS = "type parameters"

Used for the symbol table of @ref{86f,,generic functions}
or @ref{86e,,generic classes}.
@end deffn

@geindex TYPE_VARIABLE (ιδιότητα της symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType TYPE_VARIABLE}@anchor{4ee4}
@deffn {Ιδιότητα} 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


Added in version 3.13.

@end deffn

@geindex SymbolTable (κλάση σε symtable)
@anchor{library/symtable symtable SymbolTable}@anchor{4edc}
@deffn {Κλάση} symtable.SymbolTable

A namespace table for a block.  The constructor is not public.

@geindex get_type() (μέθοδος της symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_type}@anchor{1b67}
@deffn {Μέθοδος} get_type ()

Return the type of the symbol table.  Possible values are members
of the @ref{1b66,,SymbolTableType} enumeration.


Άλλαξε στην έκδοση 3.12: Added @code{'annotation'},  @code{'TypeVar bound'}, @code{'type alias'},
and @code{'type parameter'} as possible return values.



Άλλαξε στην έκδοση 3.13: Return values are members of the @ref{1b66,,SymbolTableType} enumeration.

The exact values of the returned string may change in the future,
and thus, it is recommended to use @ref{1b66,,SymbolTableType} members
instead of hard-coded strings.

@end deffn

@geindex get_id() (μέθοδος της symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_id}@anchor{4ee5}
@deffn {Μέθοδος} get_id ()

Return the table’s identifier.
@end deffn

@geindex get_name() (μέθοδος της symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_name}@anchor{4ee6}
@deffn {Μέθοδος} 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{1b67,,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{294,,TypeVar} bound scopes, it is the name of the @code{TypeVar}.
@end deffn

@geindex get_lineno() (μέθοδος της symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_lineno}@anchor{4ee7}
@deffn {Μέθοδος} get_lineno ()

Return the number of the first line in the block this table represents.
@end deffn

@geindex is_optimized() (μέθοδος της symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable is_optimized}@anchor{4ee8}
@deffn {Μέθοδος} is_optimized ()

Return @code{True} if the locals in this table can be optimized.
@end deffn

@geindex is_nested() (μέθοδος της symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable is_nested}@anchor{4ee9}
@deffn {Μέθοδος} is_nested ()

Return @code{True} if the block is a nested class or function.
@end deffn

@geindex has_children() (μέθοδος της symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable has_children}@anchor{4eea}
@deffn {Μέθοδος} has_children ()

Return @code{True} if the block has nested namespaces within it.  These can
be obtained with @ref{4eeb,,get_children()}.
@end deffn

@geindex get_identifiers() (μέθοδος της symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_identifiers}@anchor{4eec}
@deffn {Μέθοδος} get_identifiers ()

Return a view object containing the names of symbols in the table.
See the @ref{289e,,documentation of view objects}.
@end deffn

@geindex lookup() (μέθοδος της symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable lookup}@anchor{4eed}
@deffn {Μέθοδος} lookup (name)

Lookup `name' in the table and return a @ref{511,,Symbol} instance.
@end deffn

@geindex get_symbols() (μέθοδος της symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_symbols}@anchor{4eee}
@deffn {Μέθοδος} get_symbols ()

Return a list of @ref{511,,Symbol} instances for names in the table.
@end deffn

@geindex get_children() (μέθοδος της symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_children}@anchor{4eeb}
@deffn {Μέθοδος} get_children ()

Return a list of the nested symbol tables.
@end deffn
@end deffn

@geindex Function (κλάση σε symtable)
@anchor{library/symtable symtable Function}@anchor{4eef}
@deffn {Κλάση} symtable.Function

A namespace for a function or method.  This class inherits from
@ref{4edc,,SymbolTable}.

@geindex get_parameters() (μέθοδος της symtable.Function)
@anchor{library/symtable symtable Function get_parameters}@anchor{4ef0}
@deffn {Μέθοδος} get_parameters ()

Return a tuple containing names of parameters to this function.
@end deffn

@geindex get_locals() (μέθοδος της symtable.Function)
@anchor{library/symtable symtable Function get_locals}@anchor{4ef1}
@deffn {Μέθοδος} get_locals ()

Return a tuple containing names of locals in this function.
@end deffn

@geindex get_globals() (μέθοδος της symtable.Function)
@anchor{library/symtable symtable Function get_globals}@anchor{4ef2}
@deffn {Μέθοδος} get_globals ()

Return a tuple containing names of globals in this function.
@end deffn

@geindex get_nonlocals() (μέθοδος της symtable.Function)
@anchor{library/symtable symtable Function get_nonlocals}@anchor{4ef3}
@deffn {Μέθοδος} get_nonlocals ()

Return a tuple containing names of explicitly declared nonlocals in this function.
@end deffn

@geindex get_frees() (μέθοδος της symtable.Function)
@anchor{library/symtable symtable Function get_frees}@anchor{4ef4}
@deffn {Μέθοδος} get_frees ()

Return a tuple containing names of @ref{1ab7,,free (closure) variables}
in this function.
@end deffn

@geindex get_cells() (μέθοδος της symtable.Function)
@anchor{library/symtable symtable Function get_cells}@anchor{26b}
@deffn {Μέθοδος} get_cells ()

Return a tuple containing names of @ref{1ab7,,cell variables} in this table.


Added in version 3.15.

@end deffn
@end deffn

@geindex Class (κλάση σε symtable)
@anchor{library/symtable symtable Class}@anchor{4ef5}
@deffn {Κλάση} symtable.Class

A namespace of a class.  This class inherits from @ref{4edc,,SymbolTable}.
@end deffn

@geindex Symbol (κλάση σε symtable)
@anchor{library/symtable symtable Symbol}@anchor{511}
@deffn {Κλάση} symtable.Symbol

An entry in a @ref{4edc,,SymbolTable} corresponding to an identifier in the
source.  The constructor is not public.

@geindex get_name() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol get_name}@anchor{4ef6}
@deffn {Μέθοδος} get_name ()

Return the symbol’s name.
@end deffn

@geindex is_referenced() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_referenced}@anchor{4ef7}
@deffn {Μέθοδος} is_referenced ()

Return @code{True} if the symbol is used in its block.
@end deffn

@geindex is_imported() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_imported}@anchor{4ef8}
@deffn {Μέθοδος} is_imported ()

Return @code{True} if the symbol is created from an import statement.
@end deffn

@geindex is_parameter() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_parameter}@anchor{4ef9}
@deffn {Μέθοδος} is_parameter ()

Return @code{True} if the symbol is a parameter.
@end deffn

@geindex is_type_parameter() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_type_parameter}@anchor{1b68}
@deffn {Μέθοδος} is_type_parameter ()

Return @code{True} if the symbol is a type parameter.


Added in version 3.14.

@end deffn

@geindex is_global() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_global}@anchor{4efa}
@deffn {Μέθοδος} is_global ()

Return @code{True} if the symbol is global.
@end deffn

@geindex is_nonlocal() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_nonlocal}@anchor{1ffc}
@deffn {Μέθοδος} is_nonlocal ()

Return @code{True} if the symbol is nonlocal.
@end deffn

@geindex is_declared_global() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_declared_global}@anchor{16ca}
@deffn {Μέθοδος} is_declared_global ()

Return @code{True} if the symbol is declared global with a global statement.
@end deffn

@geindex is_local() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_local}@anchor{4efb}
@deffn {Μέθοδος} is_local ()

Return @code{True} if the symbol is local to its block.
@end deffn

@geindex is_annotated() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_annotated}@anchor{4efc}
@deffn {Μέθοδος} is_annotated ()

Return @code{True} if the symbol is annotated.


Added in version 3.6.

@end deffn

@geindex is_free() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_free}@anchor{4efd}
@deffn {Μέθοδος} is_free ()

Return @code{True} if the symbol is referenced in its block, but not assigned
to.
@end deffn

@geindex is_cell() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_cell}@anchor{26c}
@deffn {Μέθοδος} is_cell ()

Return @code{True} if the symbol is referenced but not assigned in a nested block.


Added in version 3.15.

@end deffn

@geindex is_free_class() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_free_class}@anchor{514}
@deffn {Μέθοδος} is_free_class ()

Return `True' if a class-scoped symbol is free from
the perspective of a method.

Consider the following example:

@example
def f():
    x = 1  # function-scoped
    class C:
        x = 2  # class-scoped
        def method(self):
            return x
@end example

In this example, the class-scoped symbol @code{x} is considered to
be free from the perspective of @code{C.method}, thereby allowing
the latter to return `1' at runtime and not `2'.


Added in version 3.14.

@end deffn

@geindex is_assigned() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_assigned}@anchor{4efe}
@deffn {Μέθοδος} is_assigned ()

Return @code{True} if the symbol is assigned to in its block.
@end deffn

@geindex is_comp_iter() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_comp_iter}@anchor{513}
@deffn {Μέθοδος} is_comp_iter ()

Return @code{True} if the symbol is a comprehension iteration variable.


Added in version 3.14.

@end deffn

@geindex is_comp_cell() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_comp_cell}@anchor{512}
@deffn {Μέθοδος} is_comp_cell ()

Return @code{True} if the symbol is a cell in an inlined comprehension.


Added in version 3.14.

@end deffn

@geindex is_namespace() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol is_namespace}@anchor{4eff}
@deffn {Μέθοδος} 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.

For example:

@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() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol get_namespaces}@anchor{4f00}
@deffn {Μέθοδος} get_namespaces ()

Return a list of namespaces bound to this name.
@end deffn

@geindex get_namespace() (μέθοδος της symtable.Symbol)
@anchor{library/symtable symtable Symbol get_namespace}@anchor{4f01}
@deffn {Μέθοδος} get_namespace ()

Return the namespace bound to this name. If more than one or no namespace
is bound to this name, a @ref{277,,ValueError} is raised.
@end deffn
@end deffn

@node Command-Line Usage<2>,,Examining Symbol Tables,symtable — Access to the compiler’s symbol tables
@anchor{library/symtable command-line-usage}@anchor{4f02}@anchor{library/symtable symtable-cli}@anchor{4f03}
@subsubsection Command-Line Usage



Added in version 3.13.


The @code{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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node token — Constants used with Python parse trees,keyword — Testing for Python keywords,symtable — Access to the compiler’s symbol tables,Python Language Services
@anchor{library/token doc}@anchor{4f04}@anchor{library/token module-token}@anchor{103}@anchor{library/token token-constants-used-with-python-parse-trees}@anchor{4f05}@anchor{library/token translation-repo}@anchor{4f06}
@subsection @code{token} — Constants used with Python parse trees


@geindex module; token

`Source code:' Lib/token.py@footnote{https://github.com/python/cpython/tree/main/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.

The module also provides a mapping from numeric codes to names and some
functions.  The functions mirror definitions in the Python C header files.

Note that a token’s value may depend on tokenizer options. For example, a
@code{"+"} token may be reported as either @ref{4f07,,PLUS} or @ref{247b,,OP}, or
a @code{"match"} token may be either @ref{24aa,,NAME} or @ref{4f08,,SOFT_KEYWORD}.

@geindex tok_name (στη μονάδα token)
@anchor{library/token token tok_name}@anchor{4f09}
@deffn {Δεδομένα} token.tok_name

Dictionary mapping the numeric values of the constants defined in this module
back to name strings, allowing more human-readable representation of parse trees
to be generated.
@end deffn

@geindex ISTERMINAL() (στη μονάδα token)
@anchor{library/token token ISTERMINAL}@anchor{4f0a}
@deffn {Συνάρτηση} token.ISTERMINAL (x)

Return @code{True} for terminal token values.
@end deffn

@geindex ISNONTERMINAL() (στη μονάδα token)
@anchor{library/token token ISNONTERMINAL}@anchor{4f0b}
@deffn {Συνάρτηση} token.ISNONTERMINAL (x)

Return @code{True} for non-terminal token values.
@end deffn

@geindex ISEOF() (στη μονάδα token)
@anchor{library/token token ISEOF}@anchor{4f0c}
@deffn {Συνάρτηση} token.ISEOF (x)

Return @code{True} if `x' is the marker indicating the end of input.
@end deffn

The token constants are:

@geindex NAME (στη μονάδα token)
@anchor{library/token token NAME}@anchor{24aa}
@deffn {Δεδομένα} token.NAME

Token value that indicates an @ref{2491,,identifier or keyword}.
@end deffn

@geindex NUMBER (στη μονάδα token)
@anchor{library/token token NUMBER}@anchor{24ab}
@deffn {Δεδομένα} token.NUMBER

Token value that indicates a @ref{2492,,numeric literal}
@end deffn

@geindex STRING (στη μονάδα token)
@anchor{library/token token STRING}@anchor{24ac}
@deffn {Δεδομένα} token.STRING

Token value that indicates a @ref{2490,,string or byte literal},
excluding @ref{43a,,formatted string literals}.
The token string is not interpreted:
it includes the surrounding quotation marks and the prefix (if given);
backslashes are included literally, without processing escape sequences.
@end deffn

@geindex OP (στη μονάδα token)
@anchor{library/token token OP}@anchor{247b}
@deffn {Δεδομένα} token.OP

A generic token value that indicates an
@ref{247d,,operator} or @ref{247c,,delimiter}.

`Λεπτομέρεια υλοποίησης CPython:' This value is only reported by the @ref{104,,tokenize} module.
Internally, the tokenizer uses
@ref{250f,,exact token types} instead.
@end deffn

@geindex COMMENT (στη μονάδα token)
@anchor{library/token token COMMENT}@anchor{4f0d}
@deffn {Δεδομένα} token.COMMENT

Token value used to indicate a comment.
The parser ignores @code{COMMENT} tokens.
@end deffn

@geindex NEWLINE (στη μονάδα token)
@anchor{library/token token NEWLINE}@anchor{2485}
@deffn {Δεδομένα} token.NEWLINE

Token value that indicates the end of a @ref{2496,,logical line}.
@end deffn

@geindex NL (στη μονάδα token)
@anchor{library/token token NL}@anchor{4f0e}
@deffn {Δεδομένα} token.NL

Token value used to indicate a non-terminating newline.
@code{NL} tokens are generated when a logical line of code is continued
over multiple physical lines. The parser ignores @code{NL} tokens.
@end deffn

@geindex INDENT (στη μονάδα token)
@anchor{library/token token INDENT}@anchor{22ec}
@deffn {Δεδομένα} token.INDENT

Token value used at the beginning of a @ref{2496,,logical line}
to indicate the start of an @ref{248d,,indented block}.
@end deffn

@geindex DEDENT (στη μονάδα token)
@anchor{library/token token DEDENT}@anchor{24a3}
@deffn {Δεδομένα} token.DEDENT

Token value used at the beginning of a @ref{2496,,logical line}
to indicate the end of an @ref{248d,,indented block}.
@end deffn

@geindex FSTRING_START (στη μονάδα token)
@anchor{library/token token FSTRING_START}@anchor{24e2}
@deffn {Δεδομένα} token.FSTRING_START

Token value used to indicate the beginning of an
@ref{43a,,f-string literal}.

`Λεπτομέρεια υλοποίησης CPython:' The token string includes the prefix and the opening quote(s), but none
of the contents of the literal.
@end deffn

@geindex FSTRING_MIDDLE (στη μονάδα token)
@anchor{library/token token FSTRING_MIDDLE}@anchor{24e3}
@deffn {Δεδομένα} token.FSTRING_MIDDLE

Token value used for literal text inside an @ref{43a,,f-string literal},
including format specifications.

`Λεπτομέρεια υλοποίησης CPython:' Replacement fields (that is, the non-literal parts of f-strings) use
the same tokens as other expressions, and are delimited by
@ref{4f0f,,LBRACE}, @ref{4f10,,RBRACE}, @ref{4f11,,EXCLAMATION} and @ref{4f12,,COLON}
tokens.
@end deffn

@geindex FSTRING_END (στη μονάδα token)
@anchor{library/token token FSTRING_END}@anchor{24e4}
@deffn {Δεδομένα} token.FSTRING_END

Token value used to indicate the end of a @ref{43a,,f-string}.

`Λεπτομέρεια υλοποίησης CPython:' The token string contains the closing quote(s).
@end deffn

@geindex TSTRING_START (στη μονάδα token)
@anchor{library/token token TSTRING_START}@anchor{4f13}
@deffn {Δεδομένα} token.TSTRING_START

Token value used to indicate the beginning of a template string literal.

`Λεπτομέρεια υλοποίησης CPython:' The token string includes the prefix and the opening quote(s), but none
of the contents of the literal.


Added in version 3.14.

@end deffn

@geindex TSTRING_MIDDLE (στη μονάδα token)
@anchor{library/token token TSTRING_MIDDLE}@anchor{4f14}
@deffn {Δεδομένα} token.TSTRING_MIDDLE

Token value used for literal text inside a template string literal
including format specifications.

`Λεπτομέρεια υλοποίησης CPython:' Replacement fields (that is, the non-literal parts of t-strings) use
the same tokens as other expressions, and are delimited by
@ref{4f0f,,LBRACE}, @ref{4f10,,RBRACE}, @ref{4f11,,EXCLAMATION} and @ref{4f12,,COLON}
tokens.


Added in version 3.14.

@end deffn

@geindex TSTRING_END (στη μονάδα token)
@anchor{library/token token TSTRING_END}@anchor{4f15}
@deffn {Δεδομένα} token.TSTRING_END

Token value used to indicate the end of a template string literal.

`Λεπτομέρεια υλοποίησης CPython:' The token string contains the closing quote(s).


Added in version 3.14.

@end deffn

@geindex ENDMARKER (στη μονάδα token)
@anchor{library/token token ENDMARKER}@anchor{24a7}
@deffn {Δεδομένα} token.ENDMARKER

Token value that indicates the end of input.
Used in @ref{2794,,top-level grammar rules}.
@end deffn

@geindex ENCODING (στη μονάδα token)
@anchor{library/token token ENCODING}@anchor{4f16}
@deffn {Δεδομένα} token.ENCODING

Token value that indicates the encoding used to decode the source bytes
into text. The first token returned by @ref{8e9,,tokenize.tokenize()} will
always be an @code{ENCODING} token.

`Λεπτομέρεια υλοποίησης CPython:' This token type isn’t used by the C tokenizer but is needed for
the @ref{104,,tokenize} module.
@end deffn

The following token types are not produced by the @ref{104,,tokenize} module,
and are defined for special uses in the tokenizer or parser:

@geindex TYPE_IGNORE (στη μονάδα token)
@anchor{library/token token TYPE_IGNORE}@anchor{4f17}
@deffn {Δεδομένα} token.TYPE_IGNORE

Token value indicating that a @code{type: ignore} comment was recognized.
Such tokens are produced instead of regular @ref{4f0d,,COMMENT} tokens only
with the @ref{4ec1,,PyCF_TYPE_COMMENTS} flag.
@end deffn

@geindex TYPE_COMMENT (στη μονάδα token)
@anchor{library/token token TYPE_COMMENT}@anchor{4f18}
@deffn {Δεδομένα} token.TYPE_COMMENT

Token value indicating that a type comment was recognized.
Such tokens are produced instead of regular @ref{4f0d,,COMMENT} tokens only
with the @ref{4ec1,,PyCF_TYPE_COMMENTS} flag.
@end deffn

@geindex SOFT_KEYWORD (στη μονάδα token)
@anchor{library/token token SOFT_KEYWORD}@anchor{4f08}
@deffn {Δεδομένα} token.SOFT_KEYWORD

Token value indicating a @ref{be6,,soft keyword}.

The tokenizer never produces this value.
To check for a soft keyword, pass a @ref{24aa,,NAME} token’s string to
@ref{4f19,,keyword.issoftkeyword()}.
@end deffn

@geindex ERRORTOKEN (στη μονάδα token)
@anchor{library/token token ERRORTOKEN}@anchor{4f1a}
@deffn {Δεδομένα} token.ERRORTOKEN

Token value used to indicate wrong input.

The @ref{104,,tokenize} module generally indicates errors by
raising exceptions instead of emitting this token.
It can also emit tokens such as @ref{247b,,OP} or @ref{24aa,,NAME} with strings that
are later rejected by the parser.
@end deffn
@anchor{library/token token-operators-delimiters}@anchor{250f}
The remaining tokens represent specific @ref{247d,,operators} and
@ref{247c,,delimiters}.
(The @ref{104,,tokenize} module reports these as @ref{247b,,OP}; see @code{exact_type}
in the @code{tokenize} documentation for details.)

@c Auto-generated by Tools/build/generate_token.py


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Token

@tab

Value

@item

@geindex LPAR (στη μονάδα token)
@anchor{library/token token LPAR}@anchor{4f1b}
@deffn {Δεδομένα} token.LPAR
@end deffn

@tab

@code{"("}

@item

@geindex RPAR (στη μονάδα token)
@anchor{library/token token RPAR}@anchor{4f1c}
@deffn {Δεδομένα} token.RPAR
@end deffn

@tab

@code{")"}

@item

@geindex LSQB (στη μονάδα token)
@anchor{library/token token LSQB}@anchor{4f1d}
@deffn {Δεδομένα} token.LSQB
@end deffn

@tab

@code{"["}

@item

@geindex RSQB (στη μονάδα token)
@anchor{library/token token RSQB}@anchor{4f1e}
@deffn {Δεδομένα} token.RSQB
@end deffn

@tab

@code{"]"}

@item

@geindex COLON (στη μονάδα token)
@anchor{library/token token COLON}@anchor{4f12}
@deffn {Δεδομένα} token.COLON
@end deffn

@tab

@code{":"}

@item

@geindex COMMA (στη μονάδα token)
@anchor{library/token token COMMA}@anchor{4f1f}
@deffn {Δεδομένα} token.COMMA
@end deffn

@tab

@code{","}

@item

@geindex SEMI (στη μονάδα token)
@anchor{library/token token SEMI}@anchor{4f20}
@deffn {Δεδομένα} token.SEMI
@end deffn

@tab

@code{";"}

@item

@geindex PLUS (στη μονάδα token)
@anchor{library/token token PLUS}@anchor{4f07}
@deffn {Δεδομένα} token.PLUS
@end deffn

@tab

@code{"+"}

@item

@geindex MINUS (στη μονάδα token)
@anchor{library/token token MINUS}@anchor{4f21}
@deffn {Δεδομένα} token.MINUS
@end deffn

@tab

@code{"-"}

@item

@geindex STAR (στη μονάδα token)
@anchor{library/token token STAR}@anchor{4f22}
@deffn {Δεδομένα} token.STAR
@end deffn

@tab

@code{"*"}

@item

@geindex SLASH (στη μονάδα token)
@anchor{library/token token SLASH}@anchor{4f23}
@deffn {Δεδομένα} token.SLASH
@end deffn

@tab

@code{"/"}

@item

@geindex VBAR (στη μονάδα token)
@anchor{library/token token VBAR}@anchor{4f24}
@deffn {Δεδομένα} token.VBAR
@end deffn

@tab

@code{"|"}

@item

@geindex AMPER (στη μονάδα token)
@anchor{library/token token AMPER}@anchor{4f25}
@deffn {Δεδομένα} token.AMPER
@end deffn

@tab

@code{"&"}

@item

@geindex LESS (στη μονάδα token)
@anchor{library/token token LESS}@anchor{4f26}
@deffn {Δεδομένα} token.LESS
@end deffn

@tab

@code{"<"}

@item

@geindex GREATER (στη μονάδα token)
@anchor{library/token token GREATER}@anchor{4f27}
@deffn {Δεδομένα} token.GREATER
@end deffn

@tab

@code{">"}

@item

@geindex EQUAL (στη μονάδα token)
@anchor{library/token token EQUAL}@anchor{4f28}
@deffn {Δεδομένα} token.EQUAL
@end deffn

@tab

@code{"="}

@item

@geindex DOT (στη μονάδα token)
@anchor{library/token token DOT}@anchor{4f29}
@deffn {Δεδομένα} token.DOT
@end deffn

@tab

@code{"."}

@item

@geindex PERCENT (στη μονάδα token)
@anchor{library/token token PERCENT}@anchor{4f2a}
@deffn {Δεδομένα} token.PERCENT
@end deffn

@tab

@code{"%"}

@item

@geindex LBRACE (στη μονάδα token)
@anchor{library/token token LBRACE}@anchor{4f0f}
@deffn {Δεδομένα} token.LBRACE
@end deffn

@tab

@code{"@{"}

@item

@geindex RBRACE (στη μονάδα token)
@anchor{library/token token RBRACE}@anchor{4f10}
@deffn {Δεδομένα} token.RBRACE
@end deffn

@tab

@code{"@}"}

@item

@geindex EQEQUAL (στη μονάδα token)
@anchor{library/token token EQEQUAL}@anchor{4f2b}
@deffn {Δεδομένα} token.EQEQUAL
@end deffn

@tab

@code{"=="}

@item

@geindex NOTEQUAL (στη μονάδα token)
@anchor{library/token token NOTEQUAL}@anchor{4f2c}
@deffn {Δεδομένα} token.NOTEQUAL
@end deffn

@tab

@code{"!="}

@item

@geindex LESSEQUAL (στη μονάδα token)
@anchor{library/token token LESSEQUAL}@anchor{4f2d}
@deffn {Δεδομένα} token.LESSEQUAL
@end deffn

@tab

@code{"<="}

@item

@geindex GREATEREQUAL (στη μονάδα token)
@anchor{library/token token GREATEREQUAL}@anchor{4f2e}
@deffn {Δεδομένα} token.GREATEREQUAL
@end deffn

@tab

@code{">="}

@item

@geindex TILDE (στη μονάδα token)
@anchor{library/token token TILDE}@anchor{4f2f}
@deffn {Δεδομένα} token.TILDE
@end deffn

@tab

@code{"~"}

@item

@geindex CIRCUMFLEX (στη μονάδα token)
@anchor{library/token token CIRCUMFLEX}@anchor{4f30}
@deffn {Δεδομένα} token.CIRCUMFLEX
@end deffn

@tab

@code{"^"}

@item

@geindex LEFTSHIFT (στη μονάδα token)
@anchor{library/token token LEFTSHIFT}@anchor{4f31}
@deffn {Δεδομένα} token.LEFTSHIFT
@end deffn

@tab

@code{"<<"}

@item

@geindex RIGHTSHIFT (στη μονάδα token)
@anchor{library/token token RIGHTSHIFT}@anchor{4f32}
@deffn {Δεδομένα} token.RIGHTSHIFT
@end deffn

@tab

@code{">>"}

@item

@geindex DOUBLESTAR (στη μονάδα token)
@anchor{library/token token DOUBLESTAR}@anchor{4f33}
@deffn {Δεδομένα} token.DOUBLESTAR
@end deffn

@tab

@code{"**"}

@item

@geindex PLUSEQUAL (στη μονάδα token)
@anchor{library/token token PLUSEQUAL}@anchor{4f34}
@deffn {Δεδομένα} token.PLUSEQUAL
@end deffn

@tab

@code{"+="}

@item

@geindex MINEQUAL (στη μονάδα token)
@anchor{library/token token MINEQUAL}@anchor{4f35}
@deffn {Δεδομένα} token.MINEQUAL
@end deffn

@tab

@code{"-="}

@item

@geindex STAREQUAL (στη μονάδα token)
@anchor{library/token token STAREQUAL}@anchor{4f36}
@deffn {Δεδομένα} token.STAREQUAL
@end deffn

@tab

@code{"*="}

@item

@geindex SLASHEQUAL (στη μονάδα token)
@anchor{library/token token SLASHEQUAL}@anchor{4f37}
@deffn {Δεδομένα} token.SLASHEQUAL
@end deffn

@tab

@code{"/="}

@item

@geindex PERCENTEQUAL (στη μονάδα token)
@anchor{library/token token PERCENTEQUAL}@anchor{4f38}
@deffn {Δεδομένα} token.PERCENTEQUAL
@end deffn

@tab

@code{"%="}

@item

@geindex AMPEREQUAL (στη μονάδα token)
@anchor{library/token token AMPEREQUAL}@anchor{4f39}
@deffn {Δεδομένα} token.AMPEREQUAL
@end deffn

@tab

@code{"&="}

@item

@geindex VBAREQUAL (στη μονάδα token)
@anchor{library/token token VBAREQUAL}@anchor{4f3a}
@deffn {Δεδομένα} token.VBAREQUAL
@end deffn

@tab

@code{"|="}

@item

@geindex CIRCUMFLEXEQUAL (στη μονάδα token)
@anchor{library/token token CIRCUMFLEXEQUAL}@anchor{4f3b}
@deffn {Δεδομένα} token.CIRCUMFLEXEQUAL
@end deffn

@tab

@code{"^="}

@item

@geindex LEFTSHIFTEQUAL (στη μονάδα token)
@anchor{library/token token LEFTSHIFTEQUAL}@anchor{4f3c}
@deffn {Δεδομένα} token.LEFTSHIFTEQUAL
@end deffn

@tab

@code{"<<="}

@item

@geindex RIGHTSHIFTEQUAL (στη μονάδα token)
@anchor{library/token token RIGHTSHIFTEQUAL}@anchor{4f3d}
@deffn {Δεδομένα} token.RIGHTSHIFTEQUAL
@end deffn

@tab

@code{">>="}

@item

@geindex DOUBLESTAREQUAL (στη μονάδα token)
@anchor{library/token token DOUBLESTAREQUAL}@anchor{4f3e}
@deffn {Δεδομένα} token.DOUBLESTAREQUAL
@end deffn

@tab

@code{"**="}

@item

@geindex DOUBLESLASH (στη μονάδα token)
@anchor{library/token token DOUBLESLASH}@anchor{4f3f}
@deffn {Δεδομένα} token.DOUBLESLASH
@end deffn

@tab

@code{"//"}

@item

@geindex DOUBLESLASHEQUAL (στη μονάδα token)
@anchor{library/token token DOUBLESLASHEQUAL}@anchor{4f40}
@deffn {Δεδομένα} token.DOUBLESLASHEQUAL
@end deffn

@tab

@code{"//="}

@item

@geindex AT (στη μονάδα token)
@anchor{library/token token AT}@anchor{4f41}
@deffn {Δεδομένα} token.AT
@end deffn

@tab

@code{"@@"}

@item

@geindex ATEQUAL (στη μονάδα token)
@anchor{library/token token ATEQUAL}@anchor{4f42}
@deffn {Δεδομένα} token.ATEQUAL
@end deffn

@tab

@code{"@@="}

@item

@geindex RARROW (στη μονάδα token)
@anchor{library/token token RARROW}@anchor{4f43}
@deffn {Δεδομένα} token.RARROW
@end deffn

@tab

@code{"->"}

@item

@geindex ELLIPSIS (στη μονάδα token)
@anchor{library/token token ELLIPSIS}@anchor{4f44}
@deffn {Δεδομένα} token.ELLIPSIS
@end deffn

@tab

@code{"..."}

@item

@geindex COLONEQUAL (στη μονάδα token)
@anchor{library/token token COLONEQUAL}@anchor{4f45}
@deffn {Δεδομένα} token.COLONEQUAL
@end deffn

@tab

@code{":="}

@item

@geindex EXCLAMATION (στη μονάδα token)
@anchor{library/token token EXCLAMATION}@anchor{4f11}
@deffn {Δεδομένα} token.EXCLAMATION
@end deffn

@tab

@code{"!"}

@end multitable


The following non-token constants are provided:

@geindex N_TOKENS (στη μονάδα token)
@anchor{library/token token N_TOKENS}@anchor{4f46}
@deffn {Δεδομένα} token.N_TOKENS

The number of token types defined in this module.
@end deffn

@c NT_OFFSET is deliberately undocumented; if you need it you should be
@c reading the source

@geindex EXACT_TOKEN_TYPES (στη μονάδα token)
@anchor{library/token token EXACT_TOKEN_TYPES}@anchor{1b07}
@deffn {Δεδομένα} token.EXACT_TOKEN_TYPES

A dictionary mapping the string representation of a token to its numeric code.


Added in version 3.8.

@end deffn


Άλλαξε στην έκδοση 3.5: Added @code{AWAIT} and @code{ASYNC} tokens.



Άλλαξε στην έκδοση 3.7: Added @ref{4f0d,,COMMENT}, @ref{4f0e,,NL} and @ref{4f16,,ENCODING} tokens.



Άλλαξε στην έκδοση 3.7: Removed @code{AWAIT} and @code{ASYNC} tokens. «async» and «await» are
now tokenized as @ref{24aa,,NAME} tokens.



Άλλαξε στην έκδοση 3.8: Added @ref{4f18,,TYPE_COMMENT}, @ref{4f17,,TYPE_IGNORE}, @ref{4f45,,COLONEQUAL}.
Added @code{AWAIT} and @code{ASYNC} tokens back (they’re needed
to support parsing older Python versions for @ref{1c9,,ast.parse()} with
@code{feature_version} set to 6 or lower).



Άλλαξε στην έκδοση 3.12: Added @ref{4f11,,EXCLAMATION}.



Άλλαξε στην έκδοση 3.13: Removed @code{AWAIT} and @code{ASYNC} tokens again.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node keyword — Testing for Python keywords,tokenize — Tokenizer for Python source,token — Constants used with Python parse trees,Python Language Services
@anchor{library/keyword doc}@anchor{4f47}@anchor{library/keyword keyword-testing-for-python-keywords}@anchor{4f48}@anchor{library/keyword module-keyword}@anchor{87}@anchor{library/keyword translation-repo}@anchor{4f49}
@subsection @code{keyword} — Testing for Python keywords


@geindex module; keyword

`Source code:' Lib/keyword.py@footnote{https://github.com/python/cpython/tree/main/Lib/keyword.py}


__________________________________________________________________


This module allows a Python program to determine if a string is a
@ref{247a,,keyword} or @ref{be6,,soft keyword}.

@geindex iskeyword() (στη μονάδα keyword)
@anchor{library/keyword keyword iskeyword}@anchor{2846}
@deffn {Συνάρτηση} keyword.iskeyword (s)

Return @code{True} if `s' is a Python @ref{247a,,keyword}.
@end deffn

@geindex kwlist (στη μονάδα keyword)
@anchor{library/keyword keyword kwlist}@anchor{4f4a}
@deffn {Δεδομένα} keyword.kwlist

Sequence containing all the @ref{247a,,keywords} defined for the
interpreter.  If any keywords are defined to only be active when particular
@ref{0,,__future__} statements are in effect, these will be included as well.
@end deffn

@geindex issoftkeyword() (στη μονάδα keyword)
@anchor{library/keyword keyword issoftkeyword}@anchor{4f19}
@deffn {Συνάρτηση} keyword.issoftkeyword (s)

Return @code{True} if `s' is a Python @ref{be6,,soft keyword}.


Added in version 3.9.

@end deffn

@geindex softkwlist (στη μονάδα keyword)
@anchor{library/keyword keyword softkwlist}@anchor{4f4b}
@deffn {Δεδομένα} keyword.softkwlist

Sequence containing all the @ref{be6,,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.


Added in version 3.9.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tokenize — Tokenizer for Python source,tabnanny — Detection of ambiguous indentation,keyword — Testing for Python keywords,Python Language Services
@anchor{library/tokenize doc}@anchor{4f4c}@anchor{library/tokenize module-tokenize}@anchor{104}@anchor{library/tokenize tokenize-tokenizer-for-python-source}@anchor{4f4d}@anchor{library/tokenize translation-repo}@anchor{4f4e}
@subsection @code{tokenize} — Tokenizer for Python source


@geindex module; tokenize

`Source code:' Lib/tokenize.py@footnote{https://github.com/python/cpython/tree/main/Lib/tokenize.py}


__________________________________________________________________


The @code{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.

To simplify token stream handling, all @ref{247d,,operator} and
@ref{247c,,delimiter} tokens and @ref{2519,,Ellipsis} are returned using
the generic @ref{247b,,OP} token type.  The exact
type can be determined by checking the @code{exact_type} property on the
@ref{a3d,,named tuple} returned from @ref{8e9,,tokenize.tokenize()}.

@cartouche
@quotation Προειδοποίηση 
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{1c9,,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
* Tokenizing input:: 
* Command-line usage: Command-line usage<6>. 
* Examples: Examples<30>. 

@end menu

@node Tokenizing input,Command-line usage<6>,,tokenize — Tokenizer for Python source
@anchor{library/tokenize tokenizing-input}@anchor{4f4f}
@subsubsection Tokenizing input


The primary entry point is a @ref{1409,,generator}:

@geindex tokenize() (στη μονάδα tokenize)
@anchor{library/tokenize tokenize tokenize}@anchor{8e9}
@deffn {Συνάρτηση} tokenize.tokenize (readline)

The @code{tokenize()} generator requires one argument, `readline', which
must be a callable object which provides the same interface as the
@ref{16ce,,io.IOBase.readline()} method of file objects.  Each call to the
function should return one line of input as 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{a3d,,named tuple}
with the field names:
@code{type string start end line}.

The returned @ref{a3d,,named tuple} has an additional property named
@code{exact_type} that contains the exact operator type for
@ref{247b,,OP} tokens.  For all other token types @code{exact_type}
equals the named tuple @code{type} field.


Άλλαξε στην έκδοση 3.1: Added support for named tuples.



Άλλαξε στην έκδοση 3.3: Added support for @code{exact_type}.


@code{tokenize()} determines the source encoding of the file by looking for a
UTF-8 BOM or encoding cookie, according to 
@geindex Python Enhancement Proposals; PEP 263
PEP 263@footnote{https://peps.python.org/pep-0263/}.
@end deffn

@geindex generate_tokens() (στη μονάδα tokenize)
@anchor{library/tokenize tokenize generate_tokens}@anchor{8ea}
@deffn {Συνάρτηση} tokenize.generate_tokens (readline)

Tokenize a source reading unicode strings instead of bytes.

Like @ref{8e9,,tokenize()}, the `readline' argument is a callable returning
a single line of input. However, @code{generate_tokens()} expects `readline'
to return a str object rather than bytes.

The result is an iterator yielding named tuples, exactly like
@ref{8e9,,tokenize()}. It does not yield an @ref{4f16,,ENCODING} token.
@end deffn

All constants from the @ref{103,,token} module are also exported from
@code{tokenize}.

Another function is provided to reverse the tokenization process. This is
useful for creating tools that tokenize a script, modify the token stream, and
write back the modified script.

@geindex untokenize() (στη μονάδα tokenize)
@anchor{library/tokenize tokenize untokenize}@anchor{1ad4}
@deffn {Συνάρτηση} tokenize.untokenize (iterable)

Converts tokens back into Python source code.  The `iterable' must return
sequences with at least two elements, the token type and the token string.
Any additional sequence elements are ignored.

The result is guaranteed to tokenize back to match the input so that the
conversion is lossless and round-trips are assured.  The guarantee applies
only to the token type and token string as the spacing between tokens
(column positions) may change.

It returns bytes, encoded using the @ref{4f16,,ENCODING} token, which
is the first token sequence output by @ref{8e9,,tokenize()}. If there is no
encoding token in the input, it returns a str instead.
@end deffn

@ref{8e9,,tokenize()} needs to detect the encoding of source files it tokenizes. The
function it uses to do this is available:

@geindex detect_encoding() (στη μονάδα tokenize)
@anchor{library/tokenize tokenize detect_encoding}@anchor{19ce}
@deffn {Συνάρτηση} tokenize.detect_encoding (readline)

The @code{detect_encoding()} function is used to detect the encoding that
should be used to decode a Python source file. It requires one argument,
readline, in the same way as the @ref{8e9,,tokenize()} generator.

It will call readline a maximum of twice, and return the encoding used
(as a string) and a list of any lines (not decoded from bytes) it has read
in.

It detects the encoding from the presence of a UTF-8 BOM or an encoding
cookie as specified in 
@geindex Python Enhancement Proposals; PEP 263
PEP 263@footnote{https://peps.python.org/pep-0263/}. If both a BOM and a cookie are present,
but disagree, a @ref{17e,,SyntaxError} will be raised. Note that if the BOM is found,
@code{'utf-8-sig'} will be returned as an encoding.

If no encoding is specified, then the default of @code{'utf-8'} will be
returned.

Use @ref{2f05,,open()} to open Python source files: it uses
@code{detect_encoding()} to detect the file encoding.
@end deffn

@geindex open() (στη μονάδα tokenize)
@anchor{library/tokenize tokenize open}@anchor{2f05}
@deffn {Συνάρτηση} tokenize.open (filename)

Open a file in read only mode using the encoding detected by
@ref{19ce,,detect_encoding()}.


Added in version 3.2.

@end deffn

@geindex TokenError
@anchor{library/tokenize tokenize TokenError}@anchor{94f}
@deffn {Εξαίρεση} tokenize.TokenError

Raised when either a docstring or expression that may be split over several
lines is not completed anywhere in the file, for example:

@example
"""Beginning of
docstring
@end example

or:

@example
[1,
 2,
 3
@end example
@end deffn

@node Command-line usage<6>,Examples<30>,Tokenizing input,tokenize — Tokenizer for Python source
@anchor{library/tokenize command-line-usage}@anchor{4f50}@anchor{library/tokenize tokenize-cli}@anchor{286}
@subsubsection Command-line usage



Added in version 3.3.


The @code{tokenize} module can be executed as a script from the command line.
It is as simple as:

@example
python -m tokenize [-e] [filename.py]
@end example

The following options are accepted:

@geindex tokenize command line option; -h
@geindex tokenize command line option; --help
@anchor{library/tokenize cmdoption-tokenize-h}@anchor{4f51}@anchor{library/tokenize cmdoption-tokenize-help}@anchor{4f52}
@deffn {Option} @w{-}h, @w{-}@w{-}help

show this help message and exit
@end deffn

@geindex tokenize command line option; -e
@geindex tokenize command line option; --exact
@anchor{library/tokenize cmdoption-tokenize-e}@anchor{4f53}@anchor{library/tokenize cmdoption-tokenize-exact}@anchor{4f54}
@deffn {Option} @w{-}e, @w{-}@w{-}exact

display token names using the exact type
@end deffn

If @code{filename.py} is specified its contents are tokenized to stdout.
Otherwise, tokenization is performed on stdin.


Added in version 3.15: Output is in color by default and can be
@ref{1af,,controlled using environment variables}.


@node Examples<30>,,Command-line usage<6>,tokenize — Tokenizer for Python source
@anchor{library/tokenize examples}@anchor{4f55}
@subsubsection Examples


Example of a script rewriter that transforms float literals into Decimal
objects:

@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

Example of tokenizing from the command line.  The script:

@example
def say_hello():
    print("Hello, World!")

say_hello()
@end example

will be tokenized to the following output where the first column is the range
of the line/column coordinates where the token is found, the second column is
the name of the token, and the final column is the value of the token (if any):

@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

The exact token type names can be displayed using the @ref{4f53,,-e} option:

@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{8ea,,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{8e9,,tokenize()}:

@example
import tokenize

with open('hello.py', 'rb') as f:
    tokens = tokenize.tokenize(f.readline)
    for token in tokens:
        print(token)
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tabnanny — Detection of ambiguous indentation,pyclbr — Python module browser support,tokenize — Tokenizer for Python source,Python Language Services
@anchor{library/tabnanny doc}@anchor{4f56}@anchor{library/tabnanny module-tabnanny}@anchor{e6}@anchor{library/tabnanny tabnanny-detection-of-ambiguous-indentation}@anchor{4f57}@anchor{library/tabnanny translation-repo}@anchor{4f58}
@subsection @code{tabnanny} — Detection of ambiguous indentation


@geindex module; tabnanny

`Source code:' Lib/tabnanny.py@footnote{https://github.com/python/cpython/tree/main/Lib/tabnanny.py}


__________________________________________________________________


For the time being this module is intended to be called as a script. However it
is possible to import it into an IDE and use the function @ref{4f59,,check()}
described below.

@cartouche
@quotation Σημείωση 
The API provided by this module is likely to change in future releases; such
changes may not be backward compatible.
@end quotation
@end cartouche

@geindex check() (στη μονάδα tabnanny)
@anchor{library/tabnanny tabnanny check}@anchor{4f59}
@deffn {Συνάρτηση} tabnanny.check (file_or_dir)

If `file_or_dir' is a directory and not a symbolic link, then recursively
descend the directory tree named by `file_or_dir', checking all @code{.py}
files along the way.  If `file_or_dir' is an ordinary Python source file, it
is checked for whitespace related problems.  The diagnostic messages are
written to standard output using the @ref{131f,,print()} function.
@end deffn

@geindex verbose (στη μονάδα tabnanny)
@anchor{library/tabnanny tabnanny verbose}@anchor{4f5a}
@deffn {Δεδομένα} tabnanny.verbose

Flag indicating whether to print verbose messages. This is incremented by the
@code{-v} option if called as a script.
@end deffn

@geindex filename_only (στη μονάδα tabnanny)
@anchor{library/tabnanny tabnanny filename_only}@anchor{4f5b}
@deffn {Δεδομένα} tabnanny.filename_only

Flag indicating whether to print only the filenames of files containing
whitespace related problems.  This is set to true by the @code{-q} option if called
as a script.
@end deffn

@geindex NannyNag
@anchor{library/tabnanny tabnanny NannyNag}@anchor{4f5c}
@deffn {Εξαίρεση} tabnanny.NannyNag

Raised by @ref{4f5d,,process_tokens()} if detecting an ambiguous indent. Captured and
handled in @ref{4f59,,check()}.
@end deffn

@geindex process_tokens() (στη μονάδα tabnanny)
@anchor{library/tabnanny tabnanny process_tokens}@anchor{4f5d}
@deffn {Συνάρτηση} tabnanny.process_tokens (tokens)

This function is used by @ref{4f59,,check()} to process tokens generated by the
@ref{104,,tokenize} module.
@end deffn

@c XXX document errprint, format_witnesses, Whitespace, check_equal, indents,
@c reset_globals


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{104,,tokenize}

Lexical scanner for Python source code.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node pyclbr — Python module browser support,py_compile — Compile Python source files,tabnanny — Detection of ambiguous indentation,Python Language Services
@anchor{library/pyclbr doc}@anchor{4f5e}@anchor{library/pyclbr module-pyclbr}@anchor{bc}@anchor{library/pyclbr pyclbr-python-module-browser-support}@anchor{4f5f}@anchor{library/pyclbr translation-repo}@anchor{4f60}
@subsection @code{pyclbr} — Python module browser support


@geindex module; pyclbr

`Source code:' Lib/pyclbr.py@footnote{https://github.com/python/cpython/tree/main/Lib/pyclbr.py}


__________________________________________________________________


The @code{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() (στη μονάδα pyclbr)
@anchor{library/pyclbr pyclbr readmodule}@anchor{c04}
@deffn {Συνάρτηση} 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() (στη μονάδα pyclbr)
@anchor{library/pyclbr pyclbr readmodule_ex}@anchor{c05}
@deffn {Συνάρτηση} 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


Added in 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
* Function Objects:: 
* Class Objects:: 

@end menu

@node Function Objects,Class Objects,,pyclbr — Python module browser support
@anchor{library/pyclbr function-objects}@anchor{4f61}@anchor{library/pyclbr pyclbr-function-objects}@anchor{4f62}
@subsubsection Function Objects


@geindex Function (κλάση σε pyclbr)
@anchor{library/pyclbr pyclbr Function}@anchor{4f63}
@deffn {Κλάση} pyclbr.Function

Class @code{Function} instances describe functions defined by def
statements.  They have the following attributes:

@geindex file (ιδιότητα της pyclbr.Function)
@anchor{library/pyclbr pyclbr Function file}@anchor{4f64}
@deffn {Ιδιότητα} file

Name of the file in which the function is defined.
@end deffn

@geindex module (ιδιότητα της pyclbr.Function)
@anchor{library/pyclbr pyclbr Function module}@anchor{4f65}
@deffn {Ιδιότητα} module

The name of the module defining the function described.
@end deffn

@geindex name (ιδιότητα της pyclbr.Function)
@anchor{library/pyclbr pyclbr Function name}@anchor{4f66}
@deffn {Ιδιότητα} name

The name of the function.
@end deffn

@geindex lineno (ιδιότητα της pyclbr.Function)
@anchor{library/pyclbr pyclbr Function lineno}@anchor{4f67}
@deffn {Ιδιότητα} lineno

The line number in the file where the definition starts.
@end deffn

@geindex parent (ιδιότητα της pyclbr.Function)
@anchor{library/pyclbr pyclbr Function parent}@anchor{4f68}
@deffn {Ιδιότητα} parent

For top-level functions, @code{None}.  For nested functions, the parent.


Added in version 3.7.

@end deffn

@geindex children (ιδιότητα της pyclbr.Function)
@anchor{library/pyclbr pyclbr Function children}@anchor{4f69}
@deffn {Ιδιότητα} children

A @ref{188,,dictionary} mapping names to descriptors for nested functions and
classes.


Added in version 3.7.

@end deffn

@geindex is_async (ιδιότητα της pyclbr.Function)
@anchor{library/pyclbr pyclbr Function is_async}@anchor{4f6a}
@deffn {Ιδιότητα} is_async

@code{True} for functions that are defined with the
@ref{9cf,,async} prefix, @code{False} otherwise.


Added in version 3.10.

@end deffn
@end deffn

@node Class Objects,,Function Objects,pyclbr — Python module browser support
@anchor{library/pyclbr class-objects}@anchor{4f6b}@anchor{library/pyclbr pyclbr-class-objects}@anchor{4f6c}
@subsubsection Class Objects


@geindex Class (κλάση σε pyclbr)
@anchor{library/pyclbr pyclbr Class}@anchor{4f6d}
@deffn {Κλάση} pyclbr.Class

Class @code{Class} instances describe classes defined by class
statements.  They have the same attributes as @ref{4f63,,Functions}
and two more.

@geindex file (ιδιότητα της pyclbr.Class)
@anchor{library/pyclbr pyclbr Class file}@anchor{4f6e}
@deffn {Ιδιότητα} file

Name of the file in which the class is defined.
@end deffn

@geindex module (ιδιότητα της pyclbr.Class)
@anchor{library/pyclbr pyclbr Class module}@anchor{4f6f}
@deffn {Ιδιότητα} module

The name of the module defining the class described.
@end deffn

@geindex name (ιδιότητα της pyclbr.Class)
@anchor{library/pyclbr pyclbr Class name}@anchor{4f70}
@deffn {Ιδιότητα} name

The name of the class.
@end deffn

@geindex lineno (ιδιότητα της pyclbr.Class)
@anchor{library/pyclbr pyclbr Class lineno}@anchor{4f71}
@deffn {Ιδιότητα} lineno

The line number in the file where the definition starts.
@end deffn

@geindex parent (ιδιότητα της pyclbr.Class)
@anchor{library/pyclbr pyclbr Class parent}@anchor{4f72}
@deffn {Ιδιότητα} parent

For top-level classes, @code{None}.  For nested classes, the parent.


Added in version 3.7.

@end deffn

@geindex children (ιδιότητα της pyclbr.Class)
@anchor{library/pyclbr pyclbr Class children}@anchor{4f73}
@deffn {Ιδιότητα} children

A dictionary mapping names to descriptors for nested functions and
classes.


Added in version 3.7.

@end deffn

@geindex super (ιδιότητα της pyclbr.Class)
@anchor{library/pyclbr pyclbr Class super}@anchor{4f74}
@deffn {Ιδιότητα} 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{c05,,readmodule_ex()}
are listed as a string with the class name instead of as
@code{Class} objects.
@end deffn

@geindex methods (ιδιότητα της pyclbr.Class)
@anchor{library/pyclbr pyclbr Class methods}@anchor{4f75}
@deffn {Ιδιότητα} methods

A @ref{188,,dictionary} mapping method names to line numbers.
This can be derived from the newer @ref{4f73,,children} dictionary,
but remains for
back-compatibility.
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node py_compile — Compile Python source files,compileall — Byte-compile Python libraries,pyclbr — Python module browser support,Python Language Services
@anchor{library/py_compile doc}@anchor{4f76}@anchor{library/py_compile module-py_compile}@anchor{bb}@anchor{library/py_compile py-compile-compile-python-source-files}@anchor{4f77}@anchor{library/py_compile translation-repo}@anchor{4f78}
@subsection @code{py_compile} — Compile Python source files


@geindex module; py_compile

`Source code:' Lib/py_compile.py@footnote{https://github.com/python/cpython/tree/main/Lib/py_compile.py}

@geindex file;byte-code


__________________________________________________________________


The @code{py_compile} module provides a function to generate a byte-code file
from a source file, and another function used when the module source file is
invoked as a script.

Though not often needed, this function can be useful when installing modules for
shared use, especially if some of the users may not have permission to write the
byte-code cache files in the directory containing the source code.

@geindex PyCompileError
@anchor{library/py_compile py_compile PyCompileError}@anchor{4f79}
@deffn {Εξαίρεση} py_compile.PyCompileError

Exception raised when an error occurs while attempting to compile the file.
@end deffn

@geindex compile() (στη μονάδα py_compile)
@anchor{library/py_compile py_compile compile}@anchor{de9}
@deffn {Συνάρτηση} 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{4f79,,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.

The `doraise' and `quiet' arguments determine how errors are handled while
compiling file. If `quiet' is 0 or 1, and `doraise' is false, the default
behaviour is enabled: an error string is written to @code{sys.stderr}, and the
function returns @code{None} instead of a path. If `doraise' is true,
a @ref{4f79,,PyCompileError} is raised instead. However if `quiet' is 2,
no message is written, and `doraise' has no effect.

If the path that `cfile' becomes (either explicitly specified or computed)
is a symlink or non-regular file, @ref{13c9,,FileExistsError} will be raised.
This is to act as a warning that import will turn those paths into regular
files if it is allowed to write byte-compiled files to those paths. This is
a side-effect of import using file renaming to place the final byte-compiled
file into place to prevent concurrent file writing issues.

`optimize' controls the optimization level and is passed to the built-in
@code{compile()} function.  The default of @code{-1} selects the optimization
level of the current interpreter.

`invalidation_mode' should be a member of the @ref{4f7a,,PycInvalidationMode}
enum and controls how the generated bytecode cache is invalidated at
runtime.  The default is @ref{4f7b,,PycInvalidationMode.CHECKED_HASH} if
the 
@geindex SOURCE_DATE_EPOCH
@geindex μεταβλητή περιβάλλοντος; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} environment variable is set, otherwise
the default is @ref{4f7c,,PycInvalidationMode.TIMESTAMP}.


Άλλαξε στην έκδοση 3.2: Changed default value of `cfile' to be 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}-compliant.  Previous
default was `file' + @code{'c'} (@code{'o'} if optimization was enabled).
Also added the `optimize' parameter.



Άλλαξε στην έκδοση 3.4: Changed code to use @ref{7a,,importlib} for the byte-code cache file writing.
This means file creation/writing semantics now match what @code{importlib}
does, e.g. permissions, write-and-move semantics, etc. Also added the
caveat that @ref{13c9,,FileExistsError} is raised if `cfile' is a symlink or
non-regular file.



Άλλαξε στην έκδοση 3.7: The `invalidation_mode' parameter was added as specified in 
@geindex Python Enhancement Proposals; PEP 552
PEP 552@footnote{https://peps.python.org/pep-0552/}.
If the 
@geindex SOURCE_DATE_EPOCH
@geindex μεταβλητή περιβάλλοντος; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} environment variable is set,
`invalidation_mode' will be forced to
@ref{4f7b,,PycInvalidationMode.CHECKED_HASH}.



Άλλαξε στην έκδοση 3.7.2: The 
@geindex SOURCE_DATE_EPOCH
@geindex μεταβλητή περιβάλλοντος; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} environment variable no longer
overrides the value of the `invalidation_mode' argument, and determines
its default value instead.



Άλλαξε στην έκδοση 3.8: The `quiet' parameter was added.

@end deffn

@geindex PycInvalidationMode (κλάση σε py_compile)
@anchor{library/py_compile py_compile PycInvalidationMode}@anchor{4f7a}
@deffn {Κλάση} 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{9e3,,Ακύρωση cached bytecode} for more information on how Python invalidates
@code{.pyc} files at runtime.


Added in version 3.7.


@geindex TIMESTAMP (ιδιότητα της py_compile.PycInvalidationMode)
@anchor{library/py_compile py_compile PycInvalidationMode TIMESTAMP}@anchor{4f7c}
@deffn {Ιδιότητα} TIMESTAMP

The @code{.pyc} file includes the timestamp and size of the source file,
which Python will compare against the metadata of the source file at
runtime to determine if the @code{.pyc} file needs to be regenerated.
@end deffn

@geindex CHECKED_HASH (ιδιότητα της py_compile.PycInvalidationMode)
@anchor{library/py_compile py_compile PycInvalidationMode CHECKED_HASH}@anchor{4f7b}
@deffn {Ιδιότητα} CHECKED_HASH

The @code{.pyc} file includes a hash of the source file content, which Python
will compare against the source at runtime to determine if the @code{.pyc}
file needs to be regenerated.
@end deffn

@geindex UNCHECKED_HASH (ιδιότητα της py_compile.PycInvalidationMode)
@anchor{library/py_compile py_compile PycInvalidationMode UNCHECKED_HASH}@anchor{4f7d}
@deffn {Ιδιότητα} UNCHECKED_HASH

Like @ref{4f7b,,CHECKED_HASH}, the @code{.pyc} file includes a hash of the source
file content. However, Python will at runtime assume the @code{.pyc} file is
up to date and not validate the @code{.pyc} against the source file at all.

This option is useful when the @code{.pycs} are kept up to date by some
system external to Python like a build system.
@end deffn
@end deffn

@menu
* Command-Line Interface: Command-Line Interface<3>. 

@end menu

@node Command-Line Interface<3>,,,py_compile — Compile Python source files
@anchor{library/py_compile command-line-interface}@anchor{4f7e}@anchor{library/py_compile py-compile-cli}@anchor{4f7f}
@subsubsection Command-Line Interface


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 python--m-py_compile command line option; <file>
@geindex python--m-py_compile command line option; -
@anchor{library/py_compile cmdoption-python-m-py_compile-arg-file}@anchor{4f80}
@deffn {Option} <file> ... <fileN>
@anchor{library/py_compile cmdoption-python-m-py_compile}@anchor{4f81}
@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 python--m-py_compile command line option; -q
@geindex python--m-py_compile command line option; --quiet
@anchor{library/py_compile cmdoption-python-m-py_compile-q}@anchor{4f82}@anchor{library/py_compile cmdoption-python-m-py_compile-quiet}@anchor{4f83}
@deffn {Option} @w{-}q, @w{-}@w{-}quiet

Suppress errors output.
@end deffn


Άλλαξε στην έκδοση 3.2: Added support for @code{-}.



Άλλαξε στην έκδοση 3.10: Added support for @ref{4f82,,-q}.



@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{21,,compileall}

Utilities to compile all Python source files in a directory tree.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node compileall — Byte-compile Python libraries,dis — Disassembler for Python bytecode,py_compile — Compile Python source files,Python Language Services
@anchor{library/compileall doc}@anchor{4f84}@anchor{library/compileall compileall-byte-compile-python-libraries}@anchor{4f85}@anchor{library/compileall module-compileall}@anchor{21}@anchor{library/compileall translation-repo}@anchor{4f86}
@subsection @code{compileall} — Byte-compile Python libraries


@geindex module; compileall

`Source code:' Lib/compileall.py@footnote{https://github.com/python/cpython/tree/main/Lib/compileall.py}


__________________________________________________________________


This module provides some utility functions to support installing Python
libraries.  These functions compile Python source files in a directory tree.
This module can be used to create the cached byte-code files at library
installation time, which makes them available for use even by users who don’t
have write permission to the library directories.

@c include for modules that don't work on WASM

@ref{232d,,Διαθεσιμότητα}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1d67,,WebAssembly platforms} for more information.

@menu
* Command-line use:: 
* Public functions:: 

@end menu

@node Command-line use,Public functions,,compileall — Byte-compile Python libraries
@anchor{library/compileall command-line-use}@anchor{4f87}@anchor{library/compileall compileall-cli}@anchor{4f88}
@subsubsection Command-line use


This module can work as a script (using @code{python -m compileall}) to
compile Python sources.

@geindex compileall command line option; directory
@geindex compileall command line option; file
@anchor{library/compileall cmdoption-compileall-arg-directory}@anchor{4f89}
@deffn {Option} directory ...
@anchor{library/compileall cmdoption-compileall-arg-file}@anchor{4f8a}
@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 compileall command line option; -l
@anchor{library/compileall cmdoption-compileall-l}@anchor{4f8b}
@deffn {Option} @w{-}l

Do not recurse into subdirectories, only compile source code files directly
contained in the named or implied directories.
@end deffn

@geindex compileall command line option; -f
@anchor{library/compileall cmdoption-compileall-f}@anchor{4f8c}
@deffn {Option} @w{-}f

Force rebuild even if timestamps are up-to-date.
@end deffn

@geindex compileall command line option; -q
@anchor{library/compileall cmdoption-compileall-q}@anchor{4f8d}
@deffn {Option} @w{-}q

Do not print the list of files compiled. If passed once, error messages will
still be printed. If passed twice (@code{-qq}), all output is suppressed.
@end deffn

@geindex compileall command line option; -d
@anchor{library/compileall cmdoption-compileall-d}@anchor{4f8e}
@deffn {Option} @w{-}d destdir

Directory prepended to the path to each file being compiled.  This will
appear in compilation time tracebacks, and is also compiled in to the
byte-code file, where it will be used in tracebacks and other messages in
cases where the source file does not exist at the time the byte-code file is
executed.
@end deffn

@geindex compileall command line option; -s
@anchor{library/compileall cmdoption-compileall-s}@anchor{4f8f}
@deffn {Option} @w{-}s strip_prefix

Remove the given prefix from paths recorded in the @code{.pyc} files.
Paths are made relative to the prefix.

This option can be used with @code{-p} but not with @code{-d}.
@end deffn

@geindex compileall command line option; -p
@anchor{library/compileall cmdoption-compileall-p}@anchor{4f90}
@deffn {Option} @w{-}p prepend_prefix

Prepend the given prefix to paths recorded in the @code{.pyc} files.
Use @code{-p /} to make the paths absolute.

This option can be used with @code{-s} but not with @code{-d}.
@end deffn

@geindex compileall command line option; -x
@anchor{library/compileall cmdoption-compileall-x}@anchor{4f91}
@deffn {Option} @w{-}x regex

regex is used to search the full path to each file considered for
compilation, and if the regex produces a match, the file is skipped.
@end deffn

@geindex compileall command line option; -i
@anchor{library/compileall cmdoption-compileall-i}@anchor{4f92}
@deffn {Option} @w{-}i list

Read the file @code{list} and add each line that it contains to the list of
files and directories to compile.  If @code{list} is @code{-}, read lines from
@code{stdin}.
@end deffn

@geindex compileall command line option; -b
@anchor{library/compileall cmdoption-compileall-b}@anchor{4f93}
@deffn {Option} @w{-}b

Write the byte-code files to their legacy locations and names, which may
overwrite byte-code files created by another version of Python.  The default
is to write files to their 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} locations and names, which allows
byte-code files from multiple versions of Python to coexist.
@end deffn

@geindex compileall command line option; -r
@anchor{library/compileall cmdoption-compileall-r}@anchor{4f94}
@deffn {Option} @w{-}r

Control the maximum recursion level for subdirectories.
If this is given, then @code{-l} option will not be taken into account.
@code{python -m compileall <directory> -r 0} is equivalent to
@code{python -m compileall <directory> -l}.
@end deffn

@geindex compileall command line option; -j
@anchor{library/compileall cmdoption-compileall-j}@anchor{4f95}
@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{6e0,,os.process_cpu_count()}
will be used.
@end deffn

@geindex compileall command line option; --invalidation-mode
@anchor{library/compileall cmdoption-compileall-invalidation-mode}@anchor{4f96}
@deffn {Option} @w{-}@w{-}invalidation@w{-}mode [timestamp|checked@w{-}hash|unchecked@w{-}hash]

Control how the generated byte-code files are invalidated at runtime.
The @code{timestamp} value, means that @code{.pyc} files with the source timestamp
and size embedded will be generated. The @code{checked-hash} and
@code{unchecked-hash} values cause hash-based pycs to be generated. Hash-based
pycs embed a hash of the source file contents rather than a timestamp. See
@ref{9e3,,Ακύρωση cached bytecode} for more information on how Python validates
bytecode cache files at runtime.
The default is @code{timestamp} if the 
@geindex SOURCE_DATE_EPOCH
@geindex μεταβλητή περιβάλλοντος; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} environment
variable is not set, and @code{checked-hash} if the @code{SOURCE_DATE_EPOCH}
environment variable is set.
@end deffn

@geindex compileall command line option; -o
@anchor{library/compileall cmdoption-compileall-o}@anchor{4f97}
@deffn {Option} @w{-}o level

Compile with the given optimization level. May be used multiple times
to compile for multiple levels at a time (for example,
@code{compileall -o 1 -o 2}).
@end deffn

@geindex compileall command line option; -e
@anchor{library/compileall cmdoption-compileall-e}@anchor{4f98}
@deffn {Option} @w{-}e dir

Ignore symlinks pointing outside the given directory.
@end deffn

@geindex compileall command line option; --hardlink-dupes
@anchor{library/compileall cmdoption-compileall-hardlink-dupes}@anchor{4f99}
@deffn {Option} @w{-}@w{-}hardlink@w{-}dupes

If two @code{.pyc} files with different optimization level have
the same content, use hard links to consolidate duplicate files.
@end deffn


Άλλαξε στην έκδοση 3.2: Added the @code{-i}, @code{-b} and @code{-h} options.



Άλλαξε στην έκδοση 3.5: Added the  @code{-j}, @code{-r}, and @code{-qq} options.  @code{-q} option
was changed to a multilevel value.  @code{-b} will always produce a
byte-code file ending in @code{.pyc}, never @code{.pyo}.



Άλλαξε στην έκδοση 3.7: Added the @code{--invalidation-mode} option.



Άλλαξε στην έκδοση 3.9: Added the @code{-s}, @code{-p}, @code{-e} and @code{--hardlink-dupes} options.
Raised the default recursion limit from 10 to
@ref{8d4,,sys.getrecursionlimit()}.
Added the possibility to specify the @code{-o} option multiple times.


There is no command-line option to control the optimization level used by the
@ref{1c8,,compile()} function, because the Python interpreter itself already
provides the option: @code{python -O -m compileall}.

Similarly, the @ref{1c8,,compile()} function respects the @ref{d6d,,sys.pycache_prefix}
setting. The generated bytecode cache will only be useful if @code{compile()} is
run with the same @code{sys.pycache_prefix} (if any) that will be used at
runtime.

@node Public functions,,Command-line use,compileall — Byte-compile Python libraries
@anchor{library/compileall public-functions}@anchor{4f9a}
@subsubsection Public functions


@geindex compile_dir() (στη μονάδα compileall)
@anchor{library/compileall compileall compile_dir}@anchor{ee8}
@deffn {Συνάρτηση} 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)

Recursively descend the directory tree named by `dir', compiling all @code{.py}
files along the way. Return a true value if all the files compiled successfully,
and a false value otherwise.

The `maxlevels' parameter is used to limit the depth of the recursion; it
defaults to @code{sys.getrecursionlimit()}.

If `ddir' is given, it is prepended to the path to each file being compiled
for use in compilation time tracebacks, and is also compiled in to the
byte-code file, where it will be used in tracebacks and other messages in
cases where the source file does not exist at the time the byte-code file is
executed.

If `force' is true, modules are re-compiled even if the timestamps are up to
date.

If `rx' is given, its @code{search} method is called on the complete path to each
file considered for compilation, and if it returns a true value, the file
is skipped. This can be used to exclude files matching a regular expression,
given as a @ref{1331,,re.Pattern} object.

If `quiet' is @code{False} or @code{0} (the default), the filenames and other
information are printed to standard out. Set to @code{1}, only errors are
printed. Set to @code{2}, all output is suppressed.

If `legacy' is true, byte-code files are written to their legacy locations
and names, which may overwrite byte-code files created by another version of
Python.  The default is to write files to their 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} locations and
names, which allows byte-code files from multiple versions of Python to
coexist.

`optimize' specifies the optimization level for the compiler.  It is passed to
the built-in @ref{1c8,,compile()} function. Accepts also a sequence of optimization
levels which lead to multiple compilations of one @code{.py} file in one call.

The argument `workers' specifies how many workers are used to
compile files in parallel. The default is to not use multiple workers.
If the platform can’t use multiple workers and `workers' argument is given,
then sequential compilation will be used as a fallback.  If `workers'
is 0, the number of cores in the system is used.  If `workers' is
lower than @code{0}, a @ref{277,,ValueError} will be raised.

`invalidation_mode' should be a member of the
@ref{4f7a,,py_compile.PycInvalidationMode} enum and controls how the generated
pycs are invalidated at runtime.

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{100f,,os.PathLike}.

If `hardlink_dupes' is true and two @code{.pyc} files with different optimization
level have the same content, use hard links to consolidate duplicate files.


Άλλαξε στην έκδοση 3.2: Added the `legacy' and `optimize' parameter.



Άλλαξε στην έκδοση 3.5: Added the `workers' parameter.



Άλλαξε στην έκδοση 3.5: `quiet' parameter was changed to a multilevel value.



Άλλαξε στην έκδοση 3.5: The `legacy' parameter only writes out @code{.pyc} files, not @code{.pyo} files
no matter what the value of `optimize' is.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.



Άλλαξε στην έκδοση 3.7: The `invalidation_mode' parameter was added.



Άλλαξε στην έκδοση 3.7.2: The `invalidation_mode' parameter’s default value is updated to @code{None}.



Άλλαξε στην έκδοση 3.8: Setting `workers' to 0 now chooses the optimal number of cores.



Άλλαξε στην έκδοση 3.9: Added `stripdir', `prependdir', `limit_sl_dest' and `hardlink_dupes' arguments.
Default value of `maxlevels' was changed from @code{10} to @code{sys.getrecursionlimit()}

@end deffn

@geindex compile_file() (στη μονάδα compileall)
@anchor{library/compileall compileall compile_file}@anchor{1199}
@deffn {Συνάρτηση} 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 the file with path `fullname'. Return a true value if the file
compiled successfully, and a false value otherwise.

If `ddir' is given, it is prepended to the path to the file being compiled
for use in compilation time tracebacks, and is also compiled in to the
byte-code file, where it will be used in tracebacks and other messages in
cases where the source file does not exist at the time the byte-code file is
executed.

If `rx' is given, its @code{search} method is passed the full path name to the
file being compiled, and if it returns a true value, the file is not
compiled and @code{True} is returned. This can be used to exclude files matching
a regular expression, given as a @ref{1331,,re.Pattern} object.

If `quiet' is @code{False} or @code{0} (the default), the filenames and other
information are printed to standard out. Set to @code{1}, only errors are
printed. Set to @code{2}, all output is suppressed.

If `legacy' is true, byte-code files are written to their legacy locations
and names, which may overwrite byte-code files created by another version of
Python.  The default is to write files to their 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} locations and
names, which allows byte-code files from multiple versions of Python to
coexist.

`optimize' specifies the optimization level for the compiler.  It is passed to
the built-in @ref{1c8,,compile()} function. Accepts also a sequence of optimization
levels which lead to multiple compilations of one @code{.py} file in one call.

`invalidation_mode' should be a member of the
@ref{4f7a,,py_compile.PycInvalidationMode} enum and controls how the generated
pycs are invalidated at runtime.

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{100f,,os.PathLike}.

If `hardlink_dupes' is true and two @code{.pyc} files with different optimization
level have the same content, use hard links to consolidate duplicate files.


Added in version 3.2.



Άλλαξε στην έκδοση 3.5: `quiet' parameter was changed to a multilevel value.



Άλλαξε στην έκδοση 3.5: The `legacy' parameter only writes out @code{.pyc} files, not @code{.pyo} files
no matter what the value of `optimize' is.



Άλλαξε στην έκδοση 3.7: The `invalidation_mode' parameter was added.



Άλλαξε στην έκδοση 3.7.2: The `invalidation_mode' parameter’s default value is updated to @code{None}.



Άλλαξε στην έκδοση 3.9: Added `stripdir', `prependdir', `limit_sl_dest' and `hardlink_dupes' arguments.

@end deffn

@geindex compile_path() (στη μονάδα compileall)
@anchor{library/compileall compileall compile_path}@anchor{119a}
@deffn {Συνάρτηση} compileall.compile_path (skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

Byte-compile all the @code{.py} files found along @code{sys.path}. Return a
true value if all the files compiled successfully, and a false value otherwise.

If `skip_curdir' is true (the default), the current directory is not included
in the search.  All other parameters are passed to the @ref{ee8,,compile_dir()}
function.  Note that unlike the other compile functions, @code{maxlevels}
defaults to @code{0}.


Άλλαξε στην έκδοση 3.2: Added the `legacy' and `optimize' parameter.



Άλλαξε στην έκδοση 3.5: `quiet' parameter was changed to a multilevel value.



Άλλαξε στην έκδοση 3.5: The `legacy' parameter only writes out @code{.pyc} files, not @code{.pyo} files
no matter what the value of `optimize' is.



Άλλαξε στην έκδοση 3.7: The `invalidation_mode' parameter was added.



Άλλαξε στην έκδοση 3.7.2: The `invalidation_mode' parameter’s default value is updated to @code{None}.

@end deffn

To force a recompile of all the @code{.py} files in the @code{Lib/}
subdirectory and all its subdirectories:

@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 Δείτε επίσης



@table @asis

@item Module @ref{bb,,py_compile}

Byte-compile a single source file.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node dis — Disassembler for Python bytecode,pickletools — Tools for pickle developers,compileall — Byte-compile Python libraries,Python Language Services
@anchor{library/dis doc}@anchor{4f9b}@anchor{library/dis dis-disassembler-for-python-bytecode}@anchor{4f9c}@anchor{library/dis module-dis}@anchor{3b}@anchor{library/dis translation-repo}@anchor{4f9d}
@subsection @code{dis} — Disassembler for Python bytecode


@geindex module; dis

`Source code:' Lib/dis.py@footnote{https://github.com/python/cpython/tree/main/Lib/dis.py}

@c import dis
@c def myfunc(alist):
@c     return len(alist)


__________________________________________________________________


The @code{dis} module supports the analysis of CPython @ref{6b3,,bytecode} by
disassembling it. The CPython bytecode which this module takes as an input is
defined in the file @code{Include/opcode.h} and used by the compiler and the
interpreter.

`Λεπτομέρεια υλοποίησης CPython:' Bytecode is an implementation detail of the CPython interpreter.  No
guarantees are made that bytecode will not be added, removed, or changed
between versions of Python.  Use of this module should not be considered to
work across Python VMs or Python releases.


Άλλαξε στην έκδοση 3.6: Use 2 bytes for each instruction. Previously the number of bytes varied
by instruction.



Άλλαξε στην έκδοση 3.10: The argument of jump, exception handling and loop instructions is now
the instruction offset rather than the byte offset.



Άλλαξε στην έκδοση 3.11: Some instructions are accompanied by one or more inline cache entries,
which take the form of @ref{ae6,,CACHE} instructions. These instructions
are hidden by default, but can be shown by passing @code{show_caches=True} to
any @code{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}.



Άλλαξε στην έκδοση 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{ae6,,CACHE} entries.

As a consequence, the presence of the @ref{ae6,,CACHE} instructions is
transparent for forward jumps but needs to be taken into account when
reasoning about backward jumps.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.14: The @ref{499,,-P} command-line option
and the @code{show_positions} argument were added.

The @ref{49a,,-S} command-line option is 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_BORROW         0 (alist)
              CALL                     1
              RETURN_VALUE
@end example

(The «2» is a line number).

@menu
* Command-line interface: Command-line interface<15>. 
* Bytecode analysis:: 
* Analysis functions:: 
* Python Bytecode Instructions:: 
* Opcode collections:: 

@end menu

@node Command-line interface<15>,Bytecode analysis,,dis — Disassembler for Python bytecode
@anchor{library/dis command-line-interface}@anchor{4f9e}@anchor{library/dis dis-cli}@anchor{4f9f}
@subsubsection Command-line interface


The @code{dis} module can be invoked as a script from the command line:

@example
python -m dis [-h] [-C] [-O] [-P] [-S] [infile]
@end example

The following options are accepted:

@geindex dis command line option; -h
@geindex dis command line option; --help
@anchor{library/dis cmdoption-dis-h}@anchor{4fa0}@anchor{library/dis cmdoption-dis-help}@anchor{4fa1}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Display usage and exit.
@end deffn

@geindex dis command line option; -C
@geindex dis command line option; --show-caches
@anchor{library/dis cmdoption-dis-C}@anchor{4fa2}@anchor{library/dis cmdoption-dis-show-caches}@anchor{4fa3}
@deffn {Option} @w{-}C, @w{-}@w{-}show@w{-}caches

Show inline caches.


Added in version 3.13.

@end deffn

@geindex dis command line option; -O
@geindex dis command line option; --show-offsets
@anchor{library/dis cmdoption-dis-O}@anchor{6f0}@anchor{library/dis cmdoption-dis-show-offsets}@anchor{4fa4}
@deffn {Option} @w{-}O, @w{-}@w{-}show@w{-}offsets

Show offsets of instructions.


Added in version 3.13.

@end deffn

@geindex dis command line option; -P
@geindex dis command line option; --show-positions
@anchor{library/dis cmdoption-dis-P}@anchor{499}@anchor{library/dis cmdoption-dis-show-positions}@anchor{4fa5}
@deffn {Option} @w{-}P, @w{-}@w{-}show@w{-}positions

Show positions of instructions in the source code.


Added in version 3.14.

@end deffn

@geindex dis command line option; -S
@geindex dis command line option; --specialized
@anchor{library/dis cmdoption-dis-S}@anchor{49a}@anchor{library/dis cmdoption-dis-specialized}@anchor{4fa6}
@deffn {Option} @w{-}S, @w{-}@w{-}specialized

Show specialized bytecode.


Added in version 3.14.

@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 Bytecode analysis,Analysis functions,Command-line interface<15>,dis — Disassembler for Python bytecode
@anchor{library/dis bytecode-analysis}@anchor{4fa7}
@subsubsection Bytecode analysis



Added in version 3.4.


The bytecode analysis API allows pieces of Python code to be wrapped in a
@ref{495,,Bytecode} object that provides easy access to details of the compiled
code.

@geindex Bytecode (κλάση σε dis)
@anchor{library/dis dis Bytecode}@anchor{495}
@deffn {Κλάση} dis.Bytecode (x, *, first_line=None, current_offset=None, show_caches=False, adaptive=False, show_offsets=False, show_positions=False)

Analyse the bytecode corresponding to a function, generator, asynchronous
generator, coroutine, method, string of source code, or a code object (as
returned by @ref{1c8,,compile()}).

This is a convenience wrapper around many of the functions listed below, most
notably @ref{6f1,,get_instructions()}, as iterating over a @code{Bytecode}
instance yields the bytecode operations as @ref{494,,Instruction} instances.

If `first_line' is not @code{None}, it indicates the line number that should be
reported for the first source line in the disassembled code.  Otherwise, the
source line information (if any) is taken directly from the disassembled code
object.

If `current_offset' is not @code{None}, it refers to an instruction offset in the
disassembled code. Setting this means @ref{12da,,dis()} will display a «current
instruction» marker against the specified opcode.

If `show_caches' is @code{True}, @ref{12da,,dis()} will display inline cache
entries used by the interpreter to specialize the bytecode.

If `adaptive' is @code{True}, @ref{12da,,dis()} will display specialized bytecode
that may be different from the original bytecode.

If `show_offsets' is @code{True}, @ref{12da,,dis()} will include instruction
offsets in the output.

If `show_positions' is @code{True}, @ref{12da,,dis()} will include instruction
source code positions in the output.

@geindex from_traceback() (μέθοδος κλάσης της dis.Bytecode)
@anchor{library/dis dis Bytecode from_traceback}@anchor{12db}
@deffn {Μέθοδος} classmethod from_traceback (tb, *, show_caches=False)

Construct a @code{Bytecode} instance from the given traceback, setting
`current_offset' to the instruction responsible for the exception.
@end deffn

@geindex Bytecode.codeobj (στη μονάδα dis)
@anchor{library/dis dis Bytecode codeobj}@anchor{4fa8}
@deffn {Δεδομένα} codeobj

The compiled code object.
@end deffn

@geindex Bytecode.first_line (στη μονάδα dis)
@anchor{library/dis dis Bytecode first_line}@anchor{4fa9}
@deffn {Δεδομένα} first_line

The first source line of the code object (if available)
@end deffn

@geindex dis() (μέθοδος της dis.Bytecode)
@anchor{library/dis dis Bytecode dis}@anchor{12da}
@deffn {Μέθοδος} dis ()

Return a formatted view of the bytecode operations (the same as printed by
@ref{496,,dis.dis()}, but returned as a multi-line string).
@end deffn

@geindex info() (μέθοδος της dis.Bytecode)
@anchor{library/dis dis Bytecode info}@anchor{4faa}
@deffn {Μέθοδος} info ()

Return a formatted multi-line string with detailed information about the
code object, like @ref{15df,,code_info()}.
@end deffn


Άλλαξε στην έκδοση 3.7: This can now handle coroutine and asynchronous generator objects.



Άλλαξε στην έκδοση 3.11: Added the `show_caches' and `adaptive' parameters.



Άλλαξε στην έκδοση 3.13: Added the `show_offsets' parameter



Άλλαξε στην έκδοση 3.14: Added the `show_positions' parameter.

@end deffn

Example:

@example
>>> bytecode = dis.Bytecode(myfunc)
>>> for instr in bytecode:
...     print(instr.opname)
...
RESUME
LOAD_GLOBAL
LOAD_FAST_BORROW
CALL
RETURN_VALUE
@end example

@node Analysis functions,Python Bytecode Instructions,Bytecode analysis,dis — Disassembler for Python bytecode
@anchor{library/dis analysis-functions}@anchor{4fab}
@subsubsection Analysis functions


The @code{dis} module also defines the following analysis functions that convert
the input directly to the desired output. They can be useful if only a single
operation is being performed, so the intermediate analysis object isn’t useful:

@geindex code_info() (στη μονάδα dis)
@anchor{library/dis dis code_info}@anchor{15df}
@deffn {Συνάρτηση} dis.code_info (x)

Return a formatted multi-line string with detailed code object information
for the supplied function, generator, asynchronous generator, coroutine,
method, source code string or code object.

Note that the exact contents of code info strings are highly implementation
dependent and they may change arbitrarily across Python VMs or Python
releases.


Added in version 3.2.



Άλλαξε στην έκδοση 3.7: This can now handle coroutine and asynchronous generator objects.

@end deffn

@geindex show_code() (στη μονάδα dis)
@anchor{library/dis dis show_code}@anchor{12d9}
@deffn {Συνάρτηση} dis.show_code (x, *, file=None)

Print detailed code object information for the supplied function, method,
source code string or code object to `file' (or @code{sys.stdout} if `file'
is not specified).

This is a convenient shorthand for @code{print(code_info(x), file=file)},
intended for interactive exploration at the interpreter prompt.


Added in version 3.2.



Άλλαξε στην έκδοση 3.4: Added `file' parameter.

@end deffn

@geindex dis() (στη μονάδα dis)
@anchor{library/dis dis dis}@anchor{496}
@deffn {Συνάρτηση} dis.dis (x=None, *, file=None, depth=None, show_caches=False, adaptive=False, show_offsets=False, show_positions=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{6b4,,annotation scopes}.
Strings are first compiled to code objects with the @ref{1c8,,compile()}
built-in function before being disassembled.  If no object is provided, this
function disassembles the last traceback.

The disassembly is written as text to the supplied `file' argument if
provided and to @code{sys.stdout} otherwise.

The maximal depth of recursion is limited by `depth' unless it is @code{None}.
@code{depth=0} means no recursion.

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.


Άλλαξε στην έκδοση 3.4: Added `file' parameter.



Άλλαξε στην έκδοση 3.7: Implemented recursive disassembling and added `depth' parameter.



Άλλαξε στην έκδοση 3.7: This can now handle coroutine and asynchronous generator objects.



Άλλαξε στην έκδοση 3.11: Added the `show_caches' and `adaptive' parameters.



Άλλαξε στην έκδοση 3.13: Added the `show_offsets' parameter.



Άλλαξε στην έκδοση 3.14: Added the `show_positions' parameter.

@end deffn

@geindex distb() (στη μονάδα dis)
@anchor{library/dis dis distb}@anchor{497}
@deffn {Συνάρτηση} dis.distb (tb=None, *, file=None, show_caches=False, adaptive=False, show_offset=False, show_positions=False)

Disassemble the top-of-stack function of a traceback, using the last
traceback if none was passed.  The instruction causing the exception is
indicated.

The disassembly is written as text to the supplied `file' argument if
provided and to @code{sys.stdout} otherwise.


Άλλαξε στην έκδοση 3.4: Added `file' parameter.



Άλλαξε στην έκδοση 3.11: Added the `show_caches' and `adaptive' parameters.



Άλλαξε στην έκδοση 3.13: Added the `show_offsets' parameter.



Άλλαξε στην έκδοση 3.14: Added the `show_positions' parameter.

@end deffn

@geindex disassemble() (στη μονάδα dis)
@geindex disco() (στη μονάδα dis)
@anchor{library/dis dis disassemble}@anchor{498}
@deffn {Συνάρτηση} dis.disassemble (code, lasti=-1, *, file=None, show_caches=False, adaptive=False, show_offsets=False, show_positions=False)
@anchor{library/dis dis disco}@anchor{4fac}
@deffnx {Συνάρτηση} dis.disco (code, lasti=-1, *, file=None, show_caches=False, adaptive=False, show_offsets=False, show_positions=False)

Disassemble a code object, indicating the last instruction if `lasti' was
provided.  The output is divided in the following columns:


@enumerate 

@item 
the source code location of the instruction. Complete location information
is shown if `show_positions' is true. Otherwise (the default) only the
line number is displayed.

@item 
the current instruction, indicated as @code{-->},

@item 
a labelled instruction, indicated with @code{>>},

@item 
the address of the instruction,

@item 
the operation code name,

@item 
operation parameters, and

@item 
interpretation of the parameters in parentheses.
@end enumerate

The parameter interpretation recognizes local and global variable names,
constant values, branch targets, and compare operators.

The disassembly is written as text to the supplied `file' argument if
provided and to @code{sys.stdout} otherwise.


Άλλαξε στην έκδοση 3.4: Added `file' parameter.



Άλλαξε στην έκδοση 3.11: Added the `show_caches' and `adaptive' parameters.



Άλλαξε στην έκδοση 3.13: Added the `show_offsets' parameter.



Άλλαξε στην έκδοση 3.14: Added the `show_positions' parameter.

@end deffn

@geindex get_instructions() (στη μονάδα dis)
@anchor{library/dis dis get_instructions}@anchor{6f1}
@deffn {Συνάρτηση} dis.get_instructions (x, *, first_line=None, show_caches=False, adaptive=False)

Return an iterator over the instructions in the supplied function, method,
source code string or code object.

The iterator generates a series of @ref{494,,Instruction} named tuples giving
the details of each operation in the supplied code.

If `first_line' is not @code{None}, it indicates the line number that should be
reported for the first source line in the disassembled code.  Otherwise, the
source line information (if any) is taken directly from the disassembled code
object.

The `adaptive' parameter works as it does in @ref{3b,,dis()}.


Added in version 3.4.



Άλλαξε στην έκδοση 3.11: Added the `show_caches' and `adaptive' parameters.



Άλλαξε στην έκδοση 3.13: The `show_caches' parameter is deprecated and has no effect. The iterator
generates the @ref{494,,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() (στη μονάδα dis)
@anchor{library/dis dis findlinestarts}@anchor{4fad}
@deffn {Συνάρτηση} dis.findlinestarts (code)

This generator function uses the @ref{32d,,co_lines()} method
of the @ref{6eb,,code object} `code' to find the offsets which
are starts of
lines in the source code.  They are generated as @code{(offset, lineno)} pairs.


Άλλαξε στην έκδοση 3.6: Line numbers can be decreasing. Before, they were always increasing.



Άλλαξε στην έκδοση 3.10: The 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/} @ref{32d,,co_lines()} method is used instead of the
@ref{2584,,co_firstlineno} and @code{codeobject.co_lnotab}
attributes of the @ref{6eb,,code object}.



Άλλαξε στην έκδοση 3.13: Line numbers can be @code{None} for bytecode that does not map to source lines.

@end deffn

@geindex findlabels() (στη μονάδα dis)
@anchor{library/dis dis findlabels}@anchor{4fae}
@deffn {Συνάρτηση} 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() (στη μονάδα dis)
@anchor{library/dis dis stack_effect}@anchor{12dc}
@deffn {Συνάρτηση} 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}, @code{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.


Added in version 3.4.



Άλλαξε στην έκδοση 3.8: Added `jump' parameter.



Άλλαξε στην έκδοση 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 Python Bytecode Instructions,Opcode collections,Analysis functions,dis — Disassembler for Python bytecode
@anchor{library/dis bytecodes}@anchor{9b1}@anchor{library/dis python-bytecode-instructions}@anchor{4faf}
@subsubsection Python Bytecode Instructions


The @ref{6f1,,get_instructions()} function and @ref{495,,Bytecode} class provide
details of bytecode instructions as @ref{494,,Instruction} instances:

@geindex Instruction (κλάση σε dis)
@anchor{library/dis dis Instruction}@anchor{494}
@deffn {Κλάση} dis.Instruction

Details for a bytecode operation

@geindex Instruction.opcode (στη μονάδα dis)
@anchor{library/dis dis Instruction opcode}@anchor{4fb0}
@deffn {Δεδομένα} opcode

numeric code for operation, corresponding to the opcode values listed
below and the bytecode values in the @ref{4fb1,,Opcode collections}.
@end deffn

@geindex Instruction.opname (στη μονάδα dis)
@anchor{library/dis dis Instruction opname}@anchor{4fb2}
@deffn {Δεδομένα} opname

human readable name for operation
@end deffn

@geindex Instruction.baseopcode (στη μονάδα dis)
@anchor{library/dis dis Instruction baseopcode}@anchor{4fb3}
@deffn {Δεδομένα} baseopcode

numeric code for the base operation if operation is specialized;
otherwise equal to @ref{4fb0,,opcode}
@end deffn

@geindex Instruction.baseopname (στη μονάδα dis)
@anchor{library/dis dis Instruction baseopname}@anchor{4fb4}
@deffn {Δεδομένα} baseopname

human readable name for the base operation if operation is specialized;
otherwise equal to @ref{4fb5,,opname}
@end deffn

@geindex Instruction.arg (στη μονάδα dis)
@anchor{library/dis dis Instruction arg}@anchor{4fb6}
@deffn {Δεδομένα} arg

numeric argument to operation (if any), otherwise @code{None}
@end deffn

@geindex Instruction.oparg (στη μονάδα dis)
@anchor{library/dis dis Instruction oparg}@anchor{4fb7}
@deffn {Δεδομένα} oparg

alias for @ref{4fb6,,arg}
@end deffn

@geindex Instruction.argval (στη μονάδα dis)
@anchor{library/dis dis Instruction argval}@anchor{4fb8}
@deffn {Δεδομένα} argval

resolved arg value (if any), otherwise @code{None}
@end deffn

@geindex Instruction.argrepr (στη μονάδα dis)
@anchor{library/dis dis Instruction argrepr}@anchor{4fb9}
@deffn {Δεδομένα} argrepr

human readable description of operation argument (if any),
otherwise an empty string.
@end deffn

@geindex Instruction.offset (στη μονάδα dis)
@anchor{library/dis dis Instruction offset}@anchor{4fba}
@deffn {Δεδομένα} offset

start index of operation within bytecode sequence
@end deffn

@geindex Instruction.start_offset (στη μονάδα dis)
@anchor{library/dis dis Instruction start_offset}@anchor{4fbb}
@deffn {Δεδομένα} start_offset

start index of operation within bytecode sequence, including prefixed
@code{EXTENDED_ARG} operations if present; otherwise equal to @ref{4fba,,offset}
@end deffn

@geindex Instruction.cache_offset (στη μονάδα dis)
@anchor{library/dis dis Instruction cache_offset}@anchor{4fbc}
@deffn {Δεδομένα} cache_offset

start index of the cache entries following the operation
@end deffn

@geindex Instruction.end_offset (στη μονάδα dis)
@anchor{library/dis dis Instruction end_offset}@anchor{4fbd}
@deffn {Δεδομένα} end_offset

end index of the cache entries following the operation
@end deffn

@geindex Instruction.starts_line (στη μονάδα dis)
@anchor{library/dis dis Instruction starts_line}@anchor{4fbe}
@deffn {Δεδομένα} starts_line

@code{True} if this opcode starts a source line, otherwise @code{False}
@end deffn

@geindex Instruction.line_number (στη μονάδα dis)
@anchor{library/dis dis Instruction line_number}@anchor{4fbf}
@deffn {Δεδομένα} line_number

source line number associated with this opcode (if any), otherwise @code{None}
@end deffn

@geindex Instruction.is_jump_target (στη μονάδα dis)
@anchor{library/dis dis Instruction is_jump_target}@anchor{4fc0}
@deffn {Δεδομένα} is_jump_target

@code{True} if other code jumps to here, otherwise @code{False}
@end deffn

@geindex Instruction.jump_target (στη μονάδα dis)
@anchor{library/dis dis Instruction jump_target}@anchor{4fc1}
@deffn {Δεδομένα} jump_target

bytecode index of the jump target if this is a jump operation,
otherwise @code{None}
@end deffn

@geindex Instruction.positions (στη μονάδα dis)
@anchor{library/dis dis Instruction positions}@anchor{4fc2}
@deffn {Δεδομένα} positions

@ref{1b58,,dis.Positions} object holding the
start and end locations that are covered by this instruction.
@end deffn

@geindex Instruction.cache_info (στη μονάδα dis)
@anchor{library/dis dis Instruction cache_info}@anchor{4fc3}
@deffn {Δεδομένα} cache_info

Information about the cache entries of this instruction, as
triplets of the form @code{(name, size, data)}, where the @code{name}
and @code{size} describe the cache format and data is the contents
of the cache. @code{cache_info} is @code{None} if the instruction does not have
caches.
@end deffn


Added in version 3.4.



Άλλαξε στην έκδοση 3.11: Field @code{positions} is added.



Άλλαξε στην έκδοση 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 (κλάση σε dis)
@anchor{library/dis dis Positions}@anchor{1b58}
@deffn {Κλάση} dis.Positions

In case the information is not available, some fields might be @code{None}.

@geindex Positions.lineno (στη μονάδα dis)
@anchor{library/dis dis Positions lineno}@anchor{4fc4}
@deffn {Δεδομένα} lineno
@end deffn

@geindex Positions.end_lineno (στη μονάδα dis)
@anchor{library/dis dis Positions end_lineno}@anchor{4fc5}
@deffn {Δεδομένα} end_lineno
@end deffn

@geindex Positions.col_offset (στη μονάδα dis)
@anchor{library/dis dis Positions col_offset}@anchor{4fc6}
@deffn {Δεδομένα} col_offset
@end deffn

@geindex Positions.end_col_offset (στη μονάδα dis)
@anchor{library/dis dis Positions end_col_offset}@anchor{4fc7}
@deffn {Δεδομένα} end_col_offset
@end deffn


Added in 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{4fc8}
@deffn {Opcode} NOP

Do nothing code.  Used as a placeholder by the bytecode optimizer, and to
generate line tracing events.
@end deffn

@geindex NOT_TAKEN (opcode)
@anchor{library/dis opcode-NOT_TAKEN}@anchor{5a4}
@deffn {Opcode} NOT_TAKEN

Do nothing code.
Used by the interpreter to record @ref{51b,,BRANCH_LEFT}
and @ref{51c,,BRANCH_RIGHT} events for @ref{e3,,sys.monitoring}.


Added in version 3.14.

@end deffn

@geindex POP_ITER (opcode)
@anchor{library/dis opcode-POP_ITER}@anchor{59f}
@deffn {Opcode} POP_ITER

Removes the iterator from the top of the stack.


Added in version 3.14.

@end deffn

@geindex POP_TOP (opcode)
@anchor{library/dis opcode-POP_TOP}@anchor{1a5b}
@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{4fc9}
@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.


Added in version 3.12.

@end deffn

@geindex END_SEND (opcode)
@anchor{library/dis opcode-END_SEND}@anchor{4fca}
@deffn {Opcode} END_SEND

Implements @code{del STACK[-2]}.
Used to clean up when a generator exits.


Added in version 3.12.

@end deffn

@geindex COPY (opcode)
@anchor{library/dis opcode-COPY}@anchor{af5}
@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


Added in version 3.11.

@end deffn

@geindex SWAP (opcode)
@anchor{library/dis opcode-SWAP}@anchor{af6}
@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


Added in version 3.11.

@end deffn

@geindex CACHE (opcode)
@anchor{library/dis opcode-CACHE}@anchor{ae6}
@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.


Added in 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{4fcb}
@deffn {Opcode} UNARY_NEGATIVE

Implements @code{STACK[-1] = -STACK[-1]}.
@end deffn

@geindex UNARY_NOT (opcode)
@anchor{library/dis opcode-UNARY_NOT}@anchor{1c67}
@deffn {Opcode} UNARY_NOT

Implements @code{STACK[-1] = not STACK[-1]}.


Άλλαξε στην έκδοση 3.13: This instruction now requires an exact @ref{5ef,,bool} operand.

@end deffn

@geindex UNARY_INVERT (opcode)
@anchor{library/dis opcode-UNARY_INVERT}@anchor{4fcc}
@deffn {Opcode} UNARY_INVERT

Implements @code{STACK[-1] = ~STACK[-1]}.
@end deffn

@geindex GET_ITER (opcode)
@anchor{library/dis opcode-GET_ITER}@anchor{4fcd}
@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{4fce}
@deffn {Opcode} GET_YIELD_FROM_ITER

If @code{STACK[-1]} is a @ref{f9e,,generator iterator} or @ref{8a2,,coroutine} object
it is left as is.  Otherwise, implements @code{STACK[-1] = iter(STACK[-1])}.


Added in version 3.5.

@end deffn

@geindex TO_BOOL (opcode)
@anchor{library/dis opcode-TO_BOOL}@anchor{1c64}
@deffn {Opcode} TO_BOOL

Implements @code{STACK[-1] = bool(STACK[-1])}.


Added in 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{595}
@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


Added in version 3.11.



Άλλαξε στην έκδοση 3.14: With oparg :@code{NB_SUBSCR}, implements binary subscript (replaces opcode @code{BINARY_SUBSCR})

@end deffn

@geindex STORE_SUBSCR (opcode)
@anchor{library/dis opcode-STORE_SUBSCR}@anchor{1da5}
@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{4fcf}
@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{8ee}
@deffn {Opcode} BINARY_SLICE

Implements:

@example
end = STACK.pop()
start = STACK.pop()
container = STACK.pop()
STACK.append(container[start:end])
@end example


Added in version 3.12.

@end deffn

@geindex STORE_SLICE (opcode)
@anchor{library/dis opcode-STORE_SLICE}@anchor{8ef}
@deffn {Opcode} STORE_SLICE

Implements:

@example
end = STACK.pop()
start = STACK.pop()
container = STACK.pop()
value = STACK.pop()
container[start:end] = value
@end example


Added in version 3.12.

@end deffn

`Coroutine opcodes'

@geindex GET_AWAITABLE (opcode)
@anchor{library/dis opcode-GET_AWAITABLE}@anchor{1dc1}
@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{4d37,,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


Added in version 3.5.



Άλλαξε στην έκδοση 3.11: Previously, this instruction did not have an oparg.

@end deffn

@geindex GET_AITER (opcode)
@anchor{library/dis opcode-GET_AITER}@anchor{4fd0}
@deffn {Opcode} GET_AITER

Implements @code{STACK[-1] = STACK[-1].__aiter__()}.


Added in version 3.5.



Άλλαξε στην έκδοση 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{4fd1}
@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}.


Added in version 3.5.

@end deffn

@geindex END_ASYNC_FOR (opcode)
@anchor{library/dis opcode-END_ASYNC_FOR}@anchor{e6f}
@deffn {Opcode} END_ASYNC_FOR

Terminates an @ref{e70,,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{1ffe,,StopAsyncIteration}, it is re-raised.


Added in version 3.8.



Άλλαξε στην έκδοση 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{8f2}
@deffn {Opcode} CLEANUP_THROW

Handles an exception raised during a @ref{905,,throw()} or
@ref{199e,,close()} call through the current frame.  If @code{STACK[-1]} is an
instance of @ref{fba,,StopIteration}, pop three values from the stack and push
its @code{value} member.  Otherwise, re-raise @code{STACK[-1]}.


Added in version 3.12.

@end deffn

`Miscellaneous opcodes'

@geindex SET_ADD (opcode)
@anchor{library/dis opcode-SET_ADD}@anchor{4fd2}
@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{4fd3}
@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{e71}
@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.


Added in version 3.1.



Άλλαξε στην έκδοση 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{4fd2,,SET_ADD}, @ref{4fd3,,LIST_APPEND} and @ref{e71,,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{1d1e}
@deffn {Opcode} RETURN_VALUE

Returns with @code{STACK[-1]} to the caller of the function.
@end deffn

@geindex YIELD_VALUE (opcode)
@anchor{library/dis opcode-YIELD_VALUE}@anchor{7b3}
@deffn {Opcode} YIELD_VALUE

Yields @code{STACK.pop()} from a @ref{1409,,generator}.


Άλλαξε στην έκδοση 3.11: oparg set to be the stack depth.



Άλλαξε στην έκδοση 3.12: oparg set to be the exception block depth, for efficient closing of generators.



Άλλαξε στην έκδοση 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{1109}
@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{110a,,variable annotations}
statically.


Added in version 3.6.

@end deffn

@geindex POP_EXCEPT (opcode)
@anchor{library/dis opcode-POP_EXCEPT}@anchor{4fd4}
@deffn {Opcode} POP_EXCEPT

Pops a value from the stack, which is used to restore the exception state.


Άλλαξε στην έκδοση 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{4fd5}
@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{c5e,,f_lasti} of the current frame.


Added in version 3.9.



Άλλαξε στην έκδοση 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{af0}
@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.


Added in version 3.11.

@end deffn

@geindex CHECK_EXC_MATCH (opcode)
@anchor{library/dis opcode-CHECK_EXC_MATCH}@anchor{af7}
@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.


Added in version 3.11.

@end deffn

@geindex CHECK_EG_MATCH (opcode)
@anchor{library/dis opcode-CHECK_EG_MATCH}@anchor{aef}
@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}.


Added in version 3.11.

@end deffn

@geindex WITH_EXCEPT_START (opcode)
@anchor{library/dis opcode-WITH_EXCEPT_START}@anchor{4fd6}
@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{20a,,with} statement.


Added in version 3.9.



Άλλαξε στην έκδοση 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_COMMON_CONSTANT (opcode)
@anchor{library/dis opcode-LOAD_COMMON_CONSTANT}@anchor{599}
@deffn {Opcode} LOAD_COMMON_CONSTANT

Pushes a common constant onto the stack. The interpreter contains a hardcoded
list of constants supported by this instruction.  Used by the @ref{d31,,assert}
statement to load @ref{a97,,AssertionError}.


Added in version 3.14.

@end deffn

@geindex LOAD_BUILD_CLASS (opcode)
@anchor{library/dis opcode-LOAD_BUILD_CLASS}@anchor{4fd7}
@deffn {Opcode} LOAD_BUILD_CLASS

Pushes @code{builtins.__build_class__()} onto the stack.  It is later called
to construct a class.
@end deffn

@geindex GET_LEN (opcode)
@anchor{library/dis opcode-GET_LEN}@anchor{4fd8}
@deffn {Opcode} GET_LEN

Perform @code{STACK.append(len(STACK[-1]))}. Used in @ref{1d4,,match} statements where
comparison with structure of pattern is needed.


Added in version 3.10.

@end deffn

@geindex MATCH_MAPPING (opcode)
@anchor{library/dis opcode-MATCH_MAPPING}@anchor{4fd9}
@deffn {Opcode} MATCH_MAPPING

If @code{STACK[-1]} is an instance of @ref{c9c,,collections.abc.Mapping} (or, more
technically: if it has the @ref{1e4f,,Py_TPFLAGS_MAPPING} flag set in its
@ref{1e68,,tp_flags}), push @code{True} onto the stack.  Otherwise,
push @code{False}.


Added in version 3.10.

@end deffn

@geindex MATCH_SEQUENCE (opcode)
@anchor{library/dis opcode-MATCH_SEQUENCE}@anchor{4fda}
@deffn {Opcode} MATCH_SEQUENCE

If @code{STACK[-1]} is an instance of @ref{156d,,collections.abc.Sequence} and is `not' an instance
of @ref{1df,,str}/@ref{1c7,,bytes}/@ref{1c6,,bytearray} (or, more technically: if it has
the @ref{1e50,,Py_TPFLAGS_SEQUENCE} flag set in its @ref{1e68,,tp_flags}),
push @code{True} onto the stack.  Otherwise, push @code{False}.


Added in version 3.10.

@end deffn

@geindex MATCH_KEYS (opcode)
@anchor{library/dis opcode-MATCH_KEYS}@anchor{afe}
@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{1ce,,tuple}
containing the corresponding values. Otherwise, push @code{None}.


Added in version 3.10.



Άλλαξε στην έκδοση 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{4fdb}
@deffn {Opcode} STORE_NAME (namei)

Implements @code{name = STACK.pop()}. `namei' is the index of `name' in the attribute
@ref{2583,,co_names} of the @ref{6eb,,code object}.
The compiler tries to use @ref{1c69,,STORE_FAST} or @ref{4fdc,,STORE_GLOBAL} if possible.
@end deffn

@geindex DELETE_NAME (opcode)
@anchor{library/dis opcode-DELETE_NAME}@anchor{4fdd}
@deffn {Opcode} DELETE_NAME (namei)

Implements @code{del name}, where `namei' is the index into @ref{2583,,co_names}
attribute of the @ref{6eb,,code object}.
@end deffn

@geindex UNPACK_SEQUENCE (opcode)
@anchor{library/dis opcode-UNPACK_SEQUENCE}@anchor{1dc3}
@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{4fde}
@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{1dc2}
@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{2583,,co_names} of the
@ref{6eb,,code object}.
@end deffn

@geindex DELETE_ATTR (opcode)
@anchor{library/dis opcode-DELETE_ATTR}@anchor{4fdf}
@deffn {Opcode} DELETE_ATTR (namei)

Implements:

@example
obj = STACK.pop()
del obj.name
@end example

where `namei' is the index of name into @ref{2583,,co_names} of the
@ref{6eb,,code object}.
@end deffn

@geindex STORE_GLOBAL (opcode)
@anchor{library/dis opcode-STORE_GLOBAL}@anchor{4fdc}
@deffn {Opcode} STORE_GLOBAL (namei)

Works as @ref{4fdb,,STORE_NAME}, but stores the name as a global.
@end deffn

@geindex DELETE_GLOBAL (opcode)
@anchor{library/dis opcode-DELETE_GLOBAL}@anchor{4fe0}
@deffn {Opcode} DELETE_GLOBAL (namei)

Works as @ref{4fdd,,DELETE_NAME}, but deletes a global name.
@end deffn

@geindex LOAD_CONST (opcode)
@anchor{library/dis opcode-LOAD_CONST}@anchor{4fe1}
@deffn {Opcode} LOAD_CONST (consti)

Pushes @code{co_consts[consti]} onto the stack.
@end deffn

@geindex LOAD_SMALL_INT (opcode)
@anchor{library/dis opcode-LOAD_SMALL_INT}@anchor{59d}
@deffn {Opcode} LOAD_SMALL_INT (i)

Pushes the integer @code{i} onto the stack.
@code{i} must be in @code{range(256)}


Added in version 3.14.

@end deffn

@geindex LOAD_NAME (opcode)
@anchor{library/dis opcode-LOAD_NAME}@anchor{4fe2}
@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{8f7}
@deffn {Opcode} LOAD_LOCALS

Pushes a reference to the locals dictionary onto the stack.  This is used
to prepare namespace dictionaries for @ref{8f5,,LOAD_FROM_DICT_OR_DEREF}
and @ref{8f6,,LOAD_FROM_DICT_OR_GLOBALS}.


Added in version 3.12.

@end deffn

@geindex LOAD_FROM_DICT_OR_GLOBALS (opcode)
@anchor{library/dis opcode-LOAD_FROM_DICT_OR_GLOBALS}@anchor{8f6}
@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{1c60,,LOAD_GLOBAL}.
This is used for loading global variables in
@ref{6b4,,annotation scopes} within class bodies.


Added in version 3.12.

@end deffn

@geindex BUILD_TEMPLATE (opcode)
@anchor{library/dis opcode-BUILD_TEMPLATE}@anchor{597}
@deffn {Opcode} BUILD_TEMPLATE

Constructs a new @ref{415,,Template} instance from a tuple
of strings and a tuple of interpolations and pushes the resulting object
onto the stack:

@example
interpolations = STACK.pop()
strings = STACK.pop()
STACK.append(_build_template(strings, interpolations))
@end example


Added in version 3.14.

@end deffn

@geindex BUILD_INTERPOLATION (opcode)
@anchor{library/dis opcode-BUILD_INTERPOLATION}@anchor{596}
@deffn {Opcode} BUILD_INTERPOLATION (format)

Constructs a new @ref{416,,Interpolation} instance from a
value and its source expression and pushes the resulting object onto the
stack.

If no conversion or format specification is present, @code{format} is set to
@code{2}.

If the low bit of @code{format} is set, it indicates that the interpolation
contains a format specification.

If @code{format >> 2} is non-zero, it indicates that the interpolation
contains a conversion. The value of @code{format >> 2} is the conversion type
(@code{0} for no conversion, @code{1} for @code{!s}, @code{2} for @code{!r}, and
@code{3} for @code{!a}):

@example
conversion = format >> 2
if format & 1:
    format_spec = STACK.pop()
else:
    format_spec = None
expression = STACK.pop()
value = STACK.pop()
STACK.append(_build_interpolation(value, expression, conversion, format_spec))
@end example


Added in version 3.14.

@end deffn

@geindex BUILD_TUPLE (opcode)
@anchor{library/dis opcode-BUILD_TUPLE}@anchor{4fe3}
@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{4fe4}
@deffn {Opcode} BUILD_LIST (count)

Works as @ref{4fe3,,BUILD_TUPLE}, but creates a list.
@end deffn

@geindex BUILD_SET (opcode)
@anchor{library/dis opcode-BUILD_SET}@anchor{4fe5}
@deffn {Opcode} BUILD_SET (count)

Works as @ref{4fe3,,BUILD_TUPLE}, but creates a set.
@end deffn

@geindex BUILD_MAP (opcode)
@anchor{library/dis opcode-BUILD_MAP}@anchor{598}
@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]@}}.


Άλλαξε στην έκδοση 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_STRING (opcode)
@anchor{library/dis opcode-BUILD_STRING}@anchor{1106}
@deffn {Opcode} BUILD_STRING (count)

Concatenates `count' strings from the stack and pushes the resulting string
onto the stack.


Added in version 3.6.

@end deffn

@geindex LIST_EXTEND (opcode)
@anchor{library/dis opcode-LIST_EXTEND}@anchor{4fe6}
@deffn {Opcode} LIST_EXTEND (i)

Implements:

@example
seq = STACK.pop()
list.extend(STACK[-i], seq)
@end example

Used to build lists.


Added in version 3.9.

@end deffn

@geindex SET_UPDATE (opcode)
@anchor{library/dis opcode-SET_UPDATE}@anchor{4fe7}
@deffn {Opcode} SET_UPDATE (i)

Implements:

@example
seq = STACK.pop()
set.update(STACK[-i], seq)
@end example

Used to build sets.


Added in version 3.9.

@end deffn

@geindex DICT_UPDATE (opcode)
@anchor{library/dis opcode-DICT_UPDATE}@anchor{4fe8}
@deffn {Opcode} DICT_UPDATE (i)

Implements:

@example
map = STACK.pop()
dict.update(STACK[-i], map)
@end example

Used to build dicts.


Added in version 3.9.

@end deffn

@geindex DICT_MERGE (opcode)
@anchor{library/dis opcode-DICT_MERGE}@anchor{4fe9}
@deffn {Opcode} DICT_MERGE (i)

Like @ref{4fe8,,DICT_UPDATE} but raises an exception for duplicate keys.


Added in version 3.9.

@end deffn

@geindex LOAD_ATTR (opcode)
@anchor{library/dis opcode-LOAD_ATTR}@anchor{8ed}
@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{af3,,CALL}
or @ref{5a1,,CALL_KW} when calling the unbound method.
Otherwise, @code{NULL} and the object returned by
the attribute lookup are pushed.


Άλλαξε στην έκδοση 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{8eb}
@deffn {Opcode} LOAD_SUPER_ATTR (namei)

This opcode implements @ref{443,,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{8ed,,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{8ed,,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{443,,super()} (unset means zero-argument).


Added in version 3.12.

@end deffn

@geindex COMPARE_OP (opcode)
@anchor{library/dis opcode-COMPARE_OP}@anchor{d32}
@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}.


Άλλαξε στην έκδοση 3.13: The fifth-lowest bit of the oparg now indicates a forced conversion to
@ref{5ef,,bool}.

@end deffn

@geindex IS_OP (opcode)
@anchor{library/dis opcode-IS_OP}@anchor{1b56}
@deffn {Opcode} IS_OP (invert)

Performs @code{is} comparison, or @code{is not} if @code{invert} is 1.


Added in version 3.9.

@end deffn

@geindex CONTAINS_OP (opcode)
@anchor{library/dis opcode-CONTAINS_OP}@anchor{1b55}
@deffn {Opcode} CONTAINS_OP (invert)

Performs @code{in} comparison, or @code{not in} if @code{invert} is 1.


Added in version 3.9.

@end deffn

@geindex IMPORT_NAME (opcode)
@anchor{library/dis opcode-IMPORT_NAME}@anchor{4fea}
@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{ca6,,__import__()}.
The module object is pushed onto the stack.  The current namespace is not affected: for a proper import statement, a subsequent @ref{1c69,,STORE_FAST} instruction
modifies the namespace.
@end deffn

@geindex IMPORT_FROM (opcode)
@anchor{library/dis opcode-IMPORT_FROM}@anchor{4feb}
@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{1c69,,STORE_FAST} instruction.
@end deffn

@geindex JUMP_FORWARD (opcode)
@anchor{library/dis opcode-JUMP_FORWARD}@anchor{1b85}
@deffn {Opcode} JUMP_FORWARD (delta)

Increments bytecode counter by `delta'.
@end deffn

@geindex JUMP_BACKWARD (opcode)
@anchor{library/dis opcode-JUMP_BACKWARD}@anchor{af8}
@deffn {Opcode} JUMP_BACKWARD (delta)

Decrements bytecode counter by `delta'. Checks for interrupts.


Added in version 3.11.

@end deffn

@geindex JUMP_BACKWARD_NO_INTERRUPT (opcode)
@anchor{library/dis opcode-JUMP_BACKWARD_NO_INTERRUPT}@anchor{aec}
@deffn {Opcode} JUMP_BACKWARD_NO_INTERRUPT (delta)

Decrements bytecode counter by `delta'. Does not check for interrupts.


Added in version 3.11.

@end deffn

@geindex POP_JUMP_IF_TRUE (opcode)
@anchor{library/dis opcode-POP_JUMP_IF_TRUE}@anchor{1c65}
@deffn {Opcode} POP_JUMP_IF_TRUE (delta)

If @code{STACK[-1]} is true, increments the bytecode counter by `delta'.
@code{STACK[-1]} is popped.


Άλλαξε στην έκδοση 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).



Άλλαξε στην έκδοση 3.12: This is no longer a pseudo-instruction.



Άλλαξε στην έκδοση 3.13: This instruction now requires an exact @ref{5ef,,bool} operand.

@end deffn

@geindex POP_JUMP_IF_FALSE (opcode)
@anchor{library/dis opcode-POP_JUMP_IF_FALSE}@anchor{1c66}
@deffn {Opcode} POP_JUMP_IF_FALSE (delta)

If @code{STACK[-1]} is false, increments the bytecode counter by `delta'.
@code{STACK[-1]} is popped.


Άλλαξε στην έκδοση 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).



Άλλαξε στην έκδοση 3.12: This is no longer a pseudo-instruction.



Άλλαξε στην έκδοση 3.13: This instruction now requires an exact @ref{5ef,,bool} operand.

@end deffn

@geindex POP_JUMP_IF_NOT_NONE (opcode)
@anchor{library/dis opcode-POP_JUMP_IF_NOT_NONE}@anchor{1d7c}
@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.


Added in version 3.11.



Άλλαξε στην έκδοση 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{1d7b}
@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.


Added in version 3.11.



Άλλαξε στην έκδοση 3.12: This is no longer a pseudo-instruction.

@end deffn

@geindex FOR_ITER (opcode)
@anchor{library/dis opcode-FOR_ITER}@anchor{1cc4}
@deffn {Opcode} FOR_ITER (delta)

@code{STACK[-1]} is an @ref{6ce,,iterator}.  Call its @ref{1672,,__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'.


Άλλαξε στην έκδοση 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{1c60}
@deffn {Opcode} LOAD_GLOBAL (namei)

Loads the global named @code{co_names[namei>>1]} onto the stack.


Άλλαξε στην έκδοση 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{4fec}
@deffn {Opcode} LOAD_FAST (var_num)

Pushes a reference to the local @code{co_varnames[var_num]} onto the stack.


Άλλαξε στην έκδοση 3.12: This opcode is now only used in situations where the local variable is
guaranteed to be initialized. It cannot raise @ref{18d8,,UnboundLocalError}.

@end deffn

@geindex LOAD_FAST_BORROW (opcode)
@anchor{library/dis opcode-LOAD_FAST_BORROW}@anchor{59b}
@deffn {Opcode} LOAD_FAST_BORROW (var_num)

Pushes a borrowed reference to the local @code{co_varnames[var_num]} onto the
stack.


Added in version 3.14.

@end deffn

@geindex LOAD_FAST_LOAD_FAST (opcode)
@anchor{library/dis opcode-LOAD_FAST_LOAD_FAST}@anchor{4fed}
@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.


Added in version 3.13.

@end deffn

@geindex LOAD_FAST_BORROW_LOAD_FAST_BORROW (opcode)
@anchor{library/dis opcode-LOAD_FAST_BORROW_LOAD_FAST_BORROW}@anchor{59c}
@deffn {Opcode} LOAD_FAST_BORROW_LOAD_FAST_BORROW (var_nums)

Pushes borrowed references to @code{co_varnames[var_nums >> 4]} and
@code{co_varnames[var_nums & 15]} onto the stack.


Added in version 3.14.

@end deffn

@geindex LOAD_FAST_CHECK (opcode)
@anchor{library/dis opcode-LOAD_FAST_CHECK}@anchor{8f4}
@deffn {Opcode} LOAD_FAST_CHECK (var_num)

Pushes a reference to the local @code{co_varnames[var_num]} onto the stack,
raising an @ref{18d8,,UnboundLocalError} if the local variable has not been
initialized.


Added in version 3.12.

@end deffn

@geindex LOAD_FAST_AND_CLEAR (opcode)
@anchor{library/dis opcode-LOAD_FAST_AND_CLEAR}@anchor{8f3}
@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}.


Added in version 3.12.

@end deffn

@geindex STORE_FAST (opcode)
@anchor{library/dis opcode-STORE_FAST}@anchor{1c69}
@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{4fee}
@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]}.


Added in version 3.13.

@end deffn

@geindex STORE_FAST_LOAD_FAST (opcode)
@anchor{library/dis opcode-STORE_FAST_LOAD_FAST}@anchor{4fef}
@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.


Added in version 3.13.

@end deffn

@geindex DELETE_FAST (opcode)
@anchor{library/dis opcode-DELETE_FAST}@anchor{4ff0}
@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{aed}
@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.


Added in version 3.11.

@end deffn

@geindex LOAD_DEREF (opcode)
@anchor{library/dis opcode-LOAD_DEREF}@anchor{4ff1}
@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.


Άλλαξε στην έκδοση 3.11: @code{i} is no longer offset by the length of @ref{257f,,co_varnames}.

@end deffn

@geindex LOAD_FROM_DICT_OR_DEREF (opcode)
@anchor{library/dis opcode-LOAD_FROM_DICT_OR_DEREF}@anchor{8f5}
@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{4ff1,,LOAD_DEREF}. This is used for loading
@ref{1ab7,,closure variables} in class bodies (which previously used
@code{LOAD_CLASSDEREF}) and in
@ref{6b4,,annotation scopes} within class bodies.


Added in version 3.12.

@end deffn

@geindex STORE_DEREF (opcode)
@anchor{library/dis opcode-STORE_DEREF}@anchor{4ff2}
@deffn {Opcode} STORE_DEREF (i)

Stores @code{STACK.pop()} into the cell contained in slot @code{i} of the «fast locals»
storage.


Άλλαξε στην έκδοση 3.11: @code{i} is no longer offset by the length of @ref{257f,,co_varnames}.

@end deffn

@geindex DELETE_DEREF (opcode)
@anchor{library/dis opcode-DELETE_DEREF}@anchor{4ff3}
@deffn {Opcode} DELETE_DEREF (i)

Empties the cell contained in slot @code{i} of the «fast locals» storage.
Used by the @ref{1d1d,,del} statement.


Added in version 3.2.



Άλλαξε στην έκδοση 3.11: @code{i} is no longer offset by the length of @ref{257f,,co_varnames}.

@end deffn

@geindex COPY_FREE_VARS (opcode)
@anchor{library/dis opcode-COPY_FREE_VARS}@anchor{aeb}
@deffn {Opcode} COPY_FREE_VARS (n)

Copies the @code{n} @ref{1ab7,,free (closure) variables} from the closure
into the frame. Removes the need for special code on the caller’s side when calling
closures.


Added in version 3.11.

@end deffn

@geindex RAISE_VARARGS (opcode)
@anchor{library/dis opcode-RAISE_VARARGS}@anchor{4ff4}
@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{af3}
@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.


Added in version 3.11.



Άλλαξε στην έκδοση 3.13: The callable now always appears at the same position on the stack.



Άλλαξε στην έκδοση 3.13: Calls with keyword arguments are now handled by @ref{5a1,,CALL_KW}.

@end deffn

@geindex CALL_KW (opcode)
@anchor{library/dis opcode-CALL_KW}@anchor{5a1}
@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{1ce,,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.


Added in version 3.13.

@end deffn

@geindex CALL_FUNCTION_EX (opcode)
@anchor{library/dis opcode-CALL_FUNCTION_EX}@anchor{1108}
@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.


Added in version 3.6.

@end deffn

@geindex PUSH_NULL (opcode)
@anchor{library/dis opcode-PUSH_NULL}@anchor{af4}
@deffn {Opcode} PUSH_NULL

Pushes a @code{NULL} to the stack.
Used in the call sequence to match the @code{NULL} pushed by
@ref{8ed,,LOAD_ATTR} for non-method calls.


Added in version 3.11.

@end deffn

@geindex MAKE_FUNCTION (opcode)
@anchor{library/dis opcode-MAKE_FUNCTION}@anchor{1107}
@deffn {Opcode} MAKE_FUNCTION

Pushes a new function object on the stack built from the code object at @code{STACK[-1]}.


Άλλαξε στην έκδοση 3.10: Flag value @code{0x04} is a tuple of strings instead of dictionary



Άλλαξε στην έκδοση 3.11: Qualified name at @code{STACK[-1]} was removed.



Άλλαξε στην έκδοση 3.13: Extra function attributes on the stack, signaled by oparg flags, were
removed. They now use @ref{4ff5,,SET_FUNCTION_ATTRIBUTE}.

@end deffn

@geindex SET_FUNCTION_ATTRIBUTE (opcode)
@anchor{library/dis opcode-SET_FUNCTION_ATTRIBUTE}@anchor{4ff5}
@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

@item 
@code{0x10} the @ref{40a,,annotate function} for the function object
@end itemize


Added in version 3.13.



Άλλαξε στην έκδοση 3.14: Added @code{0x10} to indicate the annotate function for the function object.

@end deffn

@geindex BUILD_SLICE (opcode)
@anchor{library/dis opcode-BUILD_SLICE}@anchor{4ff6}
@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{1d0,,slice()} built-in function for more information.
@end deffn

@geindex EXTENDED_ARG (opcode)
@anchor{library/dis opcode-EXTENDED_ARG}@anchor{1d1c}
@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{4ff7}
@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{1df,,str()} on `value'

@item 
@code{oparg == 2}: call @ref{45b,,repr()} on `value'

@item 
@code{oparg == 3}: call @ref{1789,,ascii()} on `value'
@end itemize

Used for implementing formatted string literals (f-strings).


Added in version 3.13.

@end deffn

@geindex FORMAT_SIMPLE (opcode)
@anchor{library/dis opcode-FORMAT_SIMPLE}@anchor{4ff8}
@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 string literals (f-strings).


Added in version 3.13.

@end deffn

@geindex FORMAT_WITH_SPEC (opcode)
@anchor{library/dis opcode-FORMAT_WITH_SPEC}@anchor{4ff9}
@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 string literals (f-strings).


Added in version 3.13.

@end deffn

@geindex MATCH_CLASS (opcode)
@anchor{library/dis opcode-MATCH_CLASS}@anchor{afd}
@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}.


Added in version 3.10.



Άλλαξε στην έκδοση 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{7b4}
@deffn {Opcode} RESUME (context)

A no-op. Performs internal tracing, debugging and optimization checks.

The @code{context} operand 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.


Added in version 3.11.



Άλλαξε στην έκδοση 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{ae9}
@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.


Added in version 3.11.

@end deffn

@geindex SEND (opcode)
@anchor{library/dis opcode-SEND}@anchor{aea}
@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{fba,,StopIteration}, pop the top value from the stack,
push the exception’s @code{value} attribute, and increment the bytecode counter
by `delta'.


Added in version 3.11.

@end deffn

@geindex HAVE_ARGUMENT (opcode)
@anchor{library/dis opcode-HAVE_ARGUMENT}@anchor{89b}
@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{79e,,hasarg} collection instead.


Άλλαξε στην έκδοση 3.6: Now every instruction has an argument, but opcodes @code{< HAVE_ARGUMENT}
ignore it. Before, only opcodes @code{>= HAVE_ARGUMENT} had an argument.



Άλλαξε στην έκδοση 3.12: Pseudo instructions were added to the @code{dis} module, and for them
it is not true that comparison with @code{HAVE_ARGUMENT} indicates whether
they use their arg.



Αποσύρθηκε στην έκδοση 3.13: Use @ref{79e,,hasarg} instead.

@end deffn

@geindex CALL_INTRINSIC_1 (opcode)
@anchor{library/dis opcode-CALL_INTRINSIC_1}@anchor{8f0}
@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{294,,typing.TypeVar}

@item

@code{INTRINSIC_PARAMSPEC}

@tab

Creates a
@ref{295,,typing.ParamSpec}

@item

@code{INTRINSIC_TYPEVARTUPLE}

@tab

Creates a
@ref{293,,typing.TypeVarTuple}

@item

@code{INTRINSIC_SUBSCRIPT_GENERIC}

@tab

Returns @ref{19f2,,typing.Generic}
subscripted with the argument

@item

@code{INTRINSIC_TYPEALIAS}

@tab

Creates a
@ref{52a,,typing.TypeAliasType};
used in the @ref{85a,,type}
statement. The argument is a tuple
of the type alias’s name,
type parameters, and value.

@end multitable



Added in version 3.12.

@end deffn

@geindex CALL_INTRINSIC_2 (opcode)
@anchor{library/dis opcode-CALL_INTRINSIC_2}@anchor{8f1}
@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{6d8,,ExceptionGroup} to raise
from a @code{try-except*}.

@item

@code{INTRINSIC_TYPEVAR_WITH_BOUND}

@tab

Creates a @ref{294,,typing.TypeVar}
with a bound.

@item

@code{INTRINSIC_TYPEVAR_WITH_CONSTRAINTS}

@tab

Creates a
@ref{294,,typing.TypeVar} with
constraints.

@item

@code{INTRINSIC_SET_FUNCTION_TYPE_PARAMS}

@tab

Sets the @code{__type_params__}
attribute of a function.

@end multitable



Added in version 3.12.

@end deffn

@geindex LOAD_SPECIAL (opcode)
@anchor{library/dis opcode-LOAD_SPECIAL}@anchor{59e}
@deffn {Opcode} LOAD_SPECIAL

Performs special method lookup on @code{STACK[-1]}.
If @code{type(STACK[-1]).__xxx__} is a method, leave
@code{type(STACK[-1]).__xxx__; STACK[-1]} on the stack.
If @code{type(STACK[-1]).__xxx__} is not a method, leave
@code{STACK[-1].__xxx__; NULL} on the stack.


Added in version 3.14.

@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{4ffa}
@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{4ffb}
@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{4ffc}
@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{20a,,with} and @ref{20b,,async with}
constructs, which push the return value of the context manager’s
@ref{9c6,,__enter__()} or @ref{2613,,__aenter__()} to the stack.
@end deffn

@geindex POP_BLOCK (opcode)
@anchor{library/dis opcode-POP_BLOCK}@anchor{4ffd}
@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)
@geindex JUMP_NO_INTERRUPT (opcode)
@anchor{library/dis opcode-JUMP}@anchor{4ffe}
@deffn {Opcode} JUMP
@anchor{library/dis opcode-JUMP_NO_INTERRUPT}@anchor{1d9f}
@deffnx {Opcode} JUMP_NO_INTERRUPT

Undirected relative jump instructions which are replaced by their
directed (forward/backward) counterparts by the assembler.
@end deffn

@geindex JUMP_IF_TRUE (opcode)
@geindex JUMP_IF_FALSE (opcode)
@anchor{library/dis opcode-JUMP_IF_TRUE}@anchor{5a2}
@deffn {Opcode} JUMP_IF_TRUE
@anchor{library/dis opcode-JUMP_IF_FALSE}@anchor{5a3}
@deffnx {Opcode} JUMP_IF_FALSE

Conditional jumps which do not impact the stack. Replaced by the sequence
@code{COPY 1}, @code{TO_BOOL}, @code{POP_JUMP_IF_TRUE/FALSE}.
@end deffn

@geindex LOAD_CLOSURE (opcode)
@anchor{library/dis opcode-LOAD_CLOSURE}@anchor{1c63}
@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.


Άλλαξε στην έκδοση 3.13: This opcode is now a pseudo-instruction.

@end deffn

@node Opcode collections,,Python Bytecode Instructions,dis — Disassembler for Python bytecode
@anchor{library/dis id1}@anchor{4fff}@anchor{library/dis opcode-collections}@anchor{4fb1}
@subsubsection Opcode collections


These collections are provided for automatic introspection of bytecode
instructions:


Άλλαξε στην έκδοση 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 (στη μονάδα dis)
@anchor{library/dis dis opname}@anchor{4fb5}
@deffn {Δεδομένα} dis.opname

Sequence of operation names, indexable using the bytecode.
@end deffn

@geindex opmap (στη μονάδα dis)
@anchor{library/dis dis opmap}@anchor{5000}
@deffn {Δεδομένα} dis.opmap

Dictionary mapping operation names to bytecodes.
@end deffn

@geindex cmp_op (στη μονάδα dis)
@anchor{library/dis dis cmp_op}@anchor{5001}
@deffn {Δεδομένα} dis.cmp_op

Sequence of all compare operation names.
@end deffn

@geindex hasarg (στη μονάδα dis)
@anchor{library/dis dis hasarg}@anchor{79e}
@deffn {Δεδομένα} dis.hasarg

Sequence of bytecodes that use their argument.


Added in version 3.12.

@end deffn

@geindex hasconst (στη μονάδα dis)
@anchor{library/dis dis hasconst}@anchor{5002}
@deffn {Δεδομένα} dis.hasconst

Sequence of bytecodes that access a constant.
@end deffn

@geindex hasfree (στη μονάδα dis)
@anchor{library/dis dis hasfree}@anchor{5003}
@deffn {Δεδομένα} dis.hasfree

Sequence of bytecodes that access a @ref{1ab7,,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 (στη μονάδα dis)
@anchor{library/dis dis hasname}@anchor{5004}
@deffn {Δεδομένα} dis.hasname

Sequence of bytecodes that access an attribute by name.
@end deffn

@geindex hasjump (στη μονάδα dis)
@anchor{library/dis dis hasjump}@anchor{5005}
@deffn {Δεδομένα} dis.hasjump

Sequence of bytecodes that have a jump target. All jumps
are relative.


Added in version 3.13.

@end deffn

@geindex haslocal (στη μονάδα dis)
@anchor{library/dis dis haslocal}@anchor{5006}
@deffn {Δεδομένα} dis.haslocal

Sequence of bytecodes that access a local variable.
@end deffn

@geindex hascompare (στη μονάδα dis)
@anchor{library/dis dis hascompare}@anchor{5007}
@deffn {Δεδομένα} dis.hascompare

Sequence of bytecodes of Boolean operations.
@end deffn

@geindex hasexc (στη μονάδα dis)
@anchor{library/dis dis hasexc}@anchor{89c}
@deffn {Δεδομένα} dis.hasexc

Sequence of bytecodes that set an exception handler.


Added in version 3.12.

@end deffn

@geindex hasjrel (στη μονάδα dis)
@anchor{library/dis dis hasjrel}@anchor{5008}
@deffn {Δεδομένα} dis.hasjrel

Sequence of bytecodes that have a relative jump target.


Αποσύρθηκε στην έκδοση 3.13: All jumps are now relative. Use @ref{5005,,hasjump}.

@end deffn

@geindex hasjabs (στη μονάδα dis)
@anchor{library/dis dis hasjabs}@anchor{5009}
@deffn {Δεδομένα} dis.hasjabs

Sequence of bytecodes that have an absolute jump target.


Αποσύρθηκε στην έκδοση 3.13: All jumps are now relative. This list is empty.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node pickletools — Tools for pickle developers,,dis — Disassembler for Python bytecode,Python Language Services
@anchor{library/pickletools doc}@anchor{500a}@anchor{library/pickletools module-pickletools}@anchor{ac}@anchor{library/pickletools pickletools-tools-for-pickle-developers}@anchor{500b}@anchor{library/pickletools translation-repo}@anchor{500c}
@subsection @code{pickletools} — Tools for pickle developers


@geindex module; pickletools

`Source code:' Lib/pickletools.py@footnote{https://github.com/python/cpython/tree/main/Lib/pickletools.py}


__________________________________________________________________


This module contains various constants relating to the intimate details of the
@ref{ab,,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 @code{pickle};
ordinary users of the @code{pickle} module probably won’t find the
@code{pickletools} module relevant.

@menu
* Command-line usage: Command-line usage<7>. 
* Programmatic interface:: 

@end menu

@node Command-line usage<7>,Programmatic interface,,pickletools — Tools for pickle developers
@anchor{library/pickletools command-line-usage}@anchor{500d}@anchor{library/pickletools pickletools-cli}@anchor{2f53}
@subsubsection Command-line usage



Added in 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
* Command-line options: Command-line options<5>. 

@end menu

@node Command-line options<5>,,,Command-line usage<7>
@anchor{library/pickletools command-line-options}@anchor{500e}
@subsubsection Command-line options


@geindex pickletools command line option; -a
@geindex pickletools command line option; --annotate
@anchor{library/pickletools cmdoption-pickletools-a}@anchor{500f}@anchor{library/pickletools cmdoption-pickletools-annotate}@anchor{5010}
@deffn {Option} @w{-}a, @w{-}@w{-}annotate

Annotate each line with a short opcode description.
@end deffn

@geindex pickletools command line option; -o
@geindex pickletools command line option; --output
@anchor{library/pickletools cmdoption-pickletools-o}@anchor{5011}@anchor{library/pickletools cmdoption-pickletools-output}@anchor{5012}
@deffn {Option} @w{-}o, @w{-}@w{-}output=<file>

Name of a file where the output should be written.
@end deffn

@geindex pickletools command line option; -l
@geindex pickletools command line option; --indentlevel
@anchor{library/pickletools cmdoption-pickletools-l}@anchor{5013}@anchor{library/pickletools cmdoption-pickletools-indentlevel}@anchor{5014}
@deffn {Option} @w{-}l, @w{-}@w{-}indentlevel=<num>

The number of blanks by which to indent a new MARK level.
@end deffn

@geindex pickletools command line option; -m
@geindex pickletools command line option; --memo
@anchor{library/pickletools cmdoption-pickletools-m}@anchor{5015}@anchor{library/pickletools cmdoption-pickletools-memo}@anchor{5016}
@deffn {Option} @w{-}m, @w{-}@w{-}memo

When multiple objects are disassembled, preserve memo between
disassemblies.
@end deffn

@geindex pickletools command line option; -p
@geindex pickletools command line option; --preamble
@anchor{library/pickletools cmdoption-pickletools-p}@anchor{5017}@anchor{library/pickletools cmdoption-pickletools-preamble}@anchor{5018}
@deffn {Option} @w{-}p, @w{-}@w{-}preamble=<preamble>

When more than one pickle file is specified, print given preamble
before each disassembly.
@end deffn

@geindex pickletools command line option; pickle_file
@anchor{library/pickletools cmdoption-pickletools-arg-pickle_file}@anchor{5019}
@deffn {Option} pickle_file

A pickle file to read, or @code{-} to indicate reading from standard input.
@end deffn


Added in version 3.15: Output is in color by default and can be
@ref{1af,,controlled using environment variables}.


@node Programmatic interface,,Command-line usage<7>,pickletools — Tools for pickle developers
@anchor{library/pickletools programmatic-interface}@anchor{501a}
@subsubsection Programmatic interface


@geindex dis() (στη μονάδα pickletools)
@anchor{library/pickletools pickletools dis}@anchor{1080}
@deffn {Συνάρτηση} 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.


Άλλαξε στην έκδοση 3.2: Added the `annotate' parameter.

@end deffn

@geindex genops() (στη μονάδα pickletools)
@anchor{library/pickletools pickletools genops}@anchor{501b}
@deffn {Συνάρτηση} pickletools.genops (pickle)

Provides an @ref{6ce,,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() (στη μονάδα pickletools)
@anchor{library/pickletools pickletools optimize}@anchor{2f3b}
@deffn {Συνάρτηση} 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node MS Windows Specific Services,Unix-specific services,Python Language Services,The Python Standard Library
@anchor{library/windows doc}@anchor{501c}@anchor{library/windows ms-windows-specific-services}@anchor{501d}@anchor{library/windows mswin-specific-services}@anchor{2411}@anchor{library/windows translation-repo}@anchor{501e}
@section MS Windows Specific Services


This chapter describes modules that are only available on MS Windows platforms.

@menu
* msvcrt — Useful routines from the MS VC++ runtime:: 
* winreg — Windows registry access:: 
* winsound — Διεπαφή αναπαραγωγής ήχου για Windows:: 

@end menu

@node msvcrt — Useful routines from the MS VC++ runtime,winreg — Windows registry access,,MS Windows Specific Services
@anchor{library/msvcrt doc}@anchor{501f}@anchor{library/msvcrt module-msvcrt}@anchor{97}@anchor{library/msvcrt msvcrt-useful-routines-from-the-ms-vc-runtime}@anchor{5020}
@subsection @code{msvcrt} — Useful routines from the MS VC++ runtime


@geindex module; msvcrt

`Source code:' PC/msvcrtmodule.c@footnote{https://github.com/python/cpython/tree/main/PC/msvcrtmodule.c}


__________________________________________________________________


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{65,,getpass} module uses
this in the implementation of the @ref{65,,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.

@ref{232d,,Διαθεσιμότητα}: Windows.


Άλλαξε στην έκδοση 3.3: Operations in this module now raise @ref{53c,,OSError} where @ref{13fb,,IOError}
was raised.


@menu
* File Operations:: 
* Console I/O:: 
* Other Functions:: 

@end menu

@node File Operations,Console I/O,,msvcrt — Useful routines from the MS VC++ runtime
@anchor{library/msvcrt file-operations}@anchor{5021}@anchor{library/msvcrt msvcrt-files}@anchor{5022}
@subsubsection File Operations


@geindex locking() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt locking}@anchor{49b5}
@deffn {Συνάρτηση} msvcrt.locking (fd, mode, nbytes)

Lock part of a file based on file descriptor `fd' from the C runtime. Raises
@ref{53c,,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{1e65,,auditing event} @code{msvcrt.locking} with arguments @code{fd}, @code{mode}, @code{nbytes}.
@end deffn

@geindex LK_LOCK (στη μονάδα msvcrt)
@geindex LK_RLCK (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt LK_LOCK}@anchor{5023}
@deffn {Δεδομένα} msvcrt.LK_LOCK
@anchor{library/msvcrt msvcrt LK_RLCK}@anchor{5024}
@deffnx {Δεδομένα} 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{53c,,OSError} is raised.
@end deffn

@geindex LK_NBLCK (στη μονάδα msvcrt)
@geindex LK_NBRLCK (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt LK_NBLCK}@anchor{5025}
@deffn {Δεδομένα} msvcrt.LK_NBLCK
@anchor{library/msvcrt msvcrt LK_NBRLCK}@anchor{5026}
@deffnx {Δεδομένα} msvcrt.LK_NBRLCK

Locks the specified bytes. If the bytes cannot be locked, @ref{53c,,OSError} is
raised.
@end deffn

@geindex LK_UNLCK (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt LK_UNLCK}@anchor{5027}
@deffn {Δεδομένα} msvcrt.LK_UNLCK

Unlocks the specified bytes, which must have been previously locked.
@end deffn

@geindex setmode() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt setmode}@anchor{5028}
@deffn {Συνάρτηση} 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{3279,,os.O_TEXT}; for binary, it should be
@ref{326a,,os.O_BINARY}.
@end deffn

@geindex open_osfhandle() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt open_osfhandle}@anchor{49b6}
@deffn {Συνάρτηση} 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{326c,,os.O_APPEND},
@ref{3268,,os.O_RDONLY}, @ref{3279,,os.O_TEXT} and @ref{3274,,os.O_NOINHERIT}.
The returned file descriptor may be used as a parameter
to @ref{2571,,os.fdopen()} to create a file object.

The file descriptor is inheritable by default. Pass @ref{3274,,os.O_NOINHERIT}
flag to make it non inheritable.

Raises an @ref{1e65,,auditing event} @code{msvcrt.open_osfhandle} with arguments @code{handle}, @code{flags}.
@end deffn

@geindex get_osfhandle() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt get_osfhandle}@anchor{49b4}
@deffn {Συνάρτηση} msvcrt.get_osfhandle (fd)

Return the file handle for the file descriptor `fd'. Raises @ref{53c,,OSError} if
`fd' is not recognized.

Raises an @ref{1e65,,auditing event} @code{msvcrt.get_osfhandle} with argument @code{fd}.
@end deffn

@node Console I/O,Other Functions,File Operations,msvcrt — Useful routines from the MS VC++ runtime
@anchor{library/msvcrt console-i-o}@anchor{5029}@anchor{library/msvcrt msvcrt-console}@anchor{502a}
@subsubsection Console I/O


@geindex kbhit() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt kbhit}@anchor{502b}
@deffn {Συνάρτηση} msvcrt.kbhit ()

Returns a nonzero value if a keypress is waiting to be read. Otherwise,
return 0.
@end deffn

@geindex getch() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt getch}@anchor{502c}
@deffn {Συνάρτηση} 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}-@code{C} keypress cannot be read with this function.
@end deffn

@geindex getwch() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt getwch}@anchor{1797}
@deffn {Συνάρτηση} msvcrt.getwch ()

Wide char variant of @ref{502c,,getch()}, returning a Unicode value.
@end deffn

@geindex getche() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt getche}@anchor{502d}
@deffn {Συνάρτηση} msvcrt.getche ()

Similar to @ref{502c,,getch()}, but the keypress will be echoed if it represents a
printable character.
@end deffn

@geindex getwche() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt getwche}@anchor{1798}
@deffn {Συνάρτηση} msvcrt.getwche ()

Wide char variant of @ref{502d,,getche()}, returning a Unicode value.
@end deffn

@geindex putch() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt putch}@anchor{502e}
@deffn {Συνάρτηση} msvcrt.putch (char)

Print the byte string `char' to the console without buffering.
@end deffn

@geindex putwch() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt putwch}@anchor{1799}
@deffn {Συνάρτηση} msvcrt.putwch (unicode_char)

Wide char variant of @ref{502e,,putch()}, accepting a Unicode value.
@end deffn

@geindex ungetch() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt ungetch}@anchor{502f}
@deffn {Συνάρτηση} 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{502c,,getch()} or @ref{502d,,getche()}.
@end deffn

@geindex ungetwch() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt ungetwch}@anchor{5030}
@deffn {Συνάρτηση} msvcrt.ungetwch (unicode_char)

Wide char variant of @ref{502f,,ungetch()}, accepting a Unicode value.
@end deffn

@node Other Functions,,Console I/O,msvcrt — Useful routines from the MS VC++ runtime
@anchor{library/msvcrt msvcrt-other}@anchor{5031}@anchor{library/msvcrt other-functions}@anchor{5032}
@subsubsection Other Functions


@geindex heapmin() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt heapmin}@anchor{5033}
@deffn {Συνάρτηση} msvcrt.heapmin ()

Force the @code{malloc()} heap to clean itself up and return unused blocks to
the operating system. On failure, this raises @ref{53c,,OSError}.
@end deffn

@geindex set_error_mode() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt set_error_mode}@anchor{5034}
@deffn {Συνάρτηση} 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{5035,,REPORT_ERRMODE}. Returns the old setting
or -1 if an error occurs. Only available in
@ref{3dc,,debug build of Python}.
@end deffn

@geindex OUT_TO_DEFAULT (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt OUT_TO_DEFAULT}@anchor{5036}
@deffn {Δεδομένα} msvcrt.OUT_TO_DEFAULT

Error sink is determined by the app’s type. Only available in
@ref{3dc,,debug build of Python}.
@end deffn

@geindex OUT_TO_STDERR (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt OUT_TO_STDERR}@anchor{5037}
@deffn {Δεδομένα} msvcrt.OUT_TO_STDERR

Error sink is a standard error. Only available in
@ref{3dc,,debug build of Python}.
@end deffn

@geindex OUT_TO_MSGBOX (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt OUT_TO_MSGBOX}@anchor{5038}
@deffn {Δεδομένα} msvcrt.OUT_TO_MSGBOX

Error sink is a message box. Only available in
@ref{3dc,,debug build of Python}.
@end deffn

@geindex REPORT_ERRMODE (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt REPORT_ERRMODE}@anchor{5035}
@deffn {Δεδομένα} msvcrt.REPORT_ERRMODE

Report the current error mode value. Only available in
@ref{3dc,,debug build of Python}.
@end deffn

@geindex CrtSetReportMode() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt CrtSetReportMode}@anchor{5039}
@deffn {Συνάρτηση} 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{3dc,,debug build of Python}.
@end deffn

@geindex CrtSetReportFile() (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt CrtSetReportFile}@anchor{503a}
@deffn {Συνάρτηση} msvcrt.CrtSetReportFile (type, file)

After you use @ref{5039,,CrtSetReportMode()} to specify @ref{503b,,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{3dc,,debug build of Python}.
@end deffn

@geindex CRT_WARN (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt CRT_WARN}@anchor{503c}
@deffn {Δεδομένα} msvcrt.CRT_WARN

Warnings, messages, and information that doesn’t need immediate attention.
@end deffn

@geindex CRT_ERROR (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt CRT_ERROR}@anchor{503d}
@deffn {Δεδομένα} msvcrt.CRT_ERROR

Errors, unrecoverable problems, and issues that require immediate attention.
@end deffn

@geindex CRT_ASSERT (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt CRT_ASSERT}@anchor{503e}
@deffn {Δεδομένα} msvcrt.CRT_ASSERT

Assertion failures.
@end deffn

@geindex CRTDBG_MODE_DEBUG (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt CRTDBG_MODE_DEBUG}@anchor{503f}
@deffn {Δεδομένα} msvcrt.CRTDBG_MODE_DEBUG

Writes the message to the debugger’s output window.
@end deffn

@geindex CRTDBG_MODE_FILE (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt CRTDBG_MODE_FILE}@anchor{503b}
@deffn {Δεδομένα} msvcrt.CRTDBG_MODE_FILE

Writes the message to a user-supplied file handle. @ref{503a,,CrtSetReportFile()}
should be called to define the specific file or stream to use as
the destination.
@end deffn

@geindex CRTDBG_MODE_WNDW (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt CRTDBG_MODE_WNDW}@anchor{5040}
@deffn {Δεδομένα} 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 (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt CRTDBG_REPORT_MODE}@anchor{5041}
@deffn {Δεδομένα} msvcrt.CRTDBG_REPORT_MODE

Returns current `mode' for the specified `type'.
@end deffn

@geindex CRT_ASSEMBLY_VERSION (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt CRT_ASSEMBLY_VERSION}@anchor{1704}
@deffn {Δεδομένα} msvcrt.CRT_ASSEMBLY_VERSION

The CRT Assembly version, from the @code{crtassem.h} header file.
@end deffn

@geindex VC_ASSEMBLY_PUBLICKEYTOKEN (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt VC_ASSEMBLY_PUBLICKEYTOKEN}@anchor{1705}
@deffn {Δεδομένα} msvcrt.VC_ASSEMBLY_PUBLICKEYTOKEN

The VC Assembly public key token, from the @code{crtassem.h} header file.
@end deffn

@geindex LIBRARIES_ASSEMBLY_NAME_PREFIX (στη μονάδα msvcrt)
@anchor{library/msvcrt msvcrt LIBRARIES_ASSEMBLY_NAME_PREFIX}@anchor{1706}
@deffn {Δεδομένα} msvcrt.LIBRARIES_ASSEMBLY_NAME_PREFIX

The Libraries Assembly name prefix, from the @code{crtassem.h} header file.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node winreg — Windows registry access,winsound — Διεπαφή αναπαραγωγής ήχου για Windows,msvcrt — Useful routines from the MS VC++ runtime,MS Windows Specific Services
@anchor{library/winreg doc}@anchor{5042}@anchor{library/winreg module-winreg}@anchor{11f}@anchor{library/winreg translation-repo}@anchor{5043}@anchor{library/winreg winreg-windows-registry-access}@anchor{5044}
@subsection @code{winreg} — Windows registry access


@geindex module; winreg

`Source code:' PC/winreg.c@footnote{https://github.com/python/cpython/tree/main/PC/winreg.c}


__________________________________________________________________


These functions expose the Windows registry API to Python.  Instead of using an
integer as the registry handle, a @ref{5045,,handle object} is used
to ensure that the handles are closed correctly, even if the programmer neglects
to explicitly close them.

@ref{232d,,Διαθεσιμότητα}: Windows.
@anchor{library/winreg exception-changed}@anchor{5046}

Άλλαξε στην έκδοση 3.3: Several functions in this module used to raise a
@ref{13fd,,WindowsError}, which is now an alias of @ref{53c,,OSError}.


@menu
* Functions: Functions<12>. 
* Constants: Constants<10>. 
* Registry Handle Objects:: 

@end menu

@node Functions<12>,Constants<10>,,winreg — Windows registry access
@anchor{library/winreg functions}@anchor{5047}@anchor{library/winreg id1}@anchor{5048}
@subsubsection Functions


This module offers the following functions:

@geindex CloseKey() (στη μονάδα winreg)
@anchor{library/winreg winreg CloseKey}@anchor{5049}
@deffn {Συνάρτηση} winreg.CloseKey (hkey)

Closes a previously opened registry key.  The `hkey' argument specifies a
previously opened key.

@cartouche
@quotation Σημείωση 
If `hkey' is not closed using this method (or via @ref{504a,,hkey.Close()}), it is closed when the `hkey' object is destroyed by
Python.
@end quotation
@end cartouche
@end deffn

@geindex ConnectRegistry() (στη μονάδα winreg)
@anchor{library/winreg winreg ConnectRegistry}@anchor{49bb}
@deffn {Συνάρτηση} winreg.ConnectRegistry (computer_name, key)

Establishes a connection to a predefined registry handle on another computer,
and returns a @ref{5045,,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{53c,,OSError} exception is raised.

Raises an @ref{1e65,,auditing event} @code{winreg.ConnectRegistry} with arguments @code{computer_name}, @code{key}.


Άλλαξε στην έκδοση 3.3: See @ref{5046,,above}.

@end deffn

@geindex CreateKey() (στη μονάδα winreg)
@anchor{library/winreg winreg CreateKey}@anchor{49bc}
@deffn {Συνάρτηση} winreg.CreateKey (key, sub_key)

Creates or opens the specified key, returning a
@ref{5045,,handle object}.

`key' is an already open key, or one of the predefined
@ref{504b,,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{53c,,OSError} exception is raised.

Raises an @ref{1e65,,auditing event} @code{winreg.CreateKey} with arguments @code{key}, @code{sub_key}, @code{access}.

Raises an @ref{1e65,,auditing event} @code{winreg.OpenKey/result} with argument @code{key}.


Άλλαξε στην έκδοση 3.3: See @ref{5046,,above}.

@end deffn

@geindex CreateKeyEx() (στη μονάδα winreg)
@anchor{library/winreg winreg CreateKeyEx}@anchor{1707}
@deffn {Συνάρτηση} winreg.CreateKeyEx (key, sub_key, reserved=0, access=KEY_WRITE)

Creates or opens the specified key, returning a
@ref{5045,,handle object}.

`key' is an already open key, or one of the predefined
@ref{504b,,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{504c,,KEY_WRITE}.  See
@ref{504d,,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{53c,,OSError} exception is raised.

Raises an @ref{1e65,,auditing event} @code{winreg.CreateKey} with arguments @code{key}, @code{sub_key}, @code{access}.

Raises an @ref{1e65,,auditing event} @code{winreg.OpenKey/result} with argument @code{key}.


Added in version 3.2.



Άλλαξε στην έκδοση 3.3: See @ref{5046,,above}.

@end deffn

@geindex DeleteKey() (στη μονάδα winreg)
@anchor{library/winreg winreg DeleteKey}@anchor{49bd}
@deffn {Συνάρτηση} winreg.DeleteKey (key, sub_key)

Deletes the specified key.

`key' is an already open key, or one of the predefined
@ref{504b,,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{53c,,OSError} exception is raised.

Raises an @ref{1e65,,auditing event} @code{winreg.DeleteKey} with arguments @code{key}, @code{sub_key}, @code{access}.


Άλλαξε στην έκδοση 3.3: See @ref{5046,,above}.

@end deffn

@geindex DeleteKeyEx() (στη μονάδα winreg)
@anchor{library/winreg winreg DeleteKeyEx}@anchor{1708}
@deffn {Συνάρτηση} 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{504b,,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{504e,,KEY_WOW64_64KEY}.
On 32-bit Windows, the WOW64 constants are ignored.
See @ref{504d,,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{53c,,OSError} exception is raised.

On unsupported Windows versions, @ref{59a,,NotImplementedError} is raised.

Raises an @ref{1e65,,auditing event} @code{winreg.DeleteKey} with arguments @code{key}, @code{sub_key}, @code{access}.


Added in version 3.2.



Άλλαξε στην έκδοση 3.3: See @ref{5046,,above}.

@end deffn

@geindex DeleteTree() (στη μονάδα winreg)
@anchor{library/winreg winreg DeleteTree}@anchor{19ea}
@deffn {Συνάρτηση} winreg.DeleteTree (key, sub_key=None)

Deletes the specified key and all its subkeys and values recursively.

`key' is an already open key, or one of the predefined
@ref{504b,,HKEY_* constants}.

`sub_key' is a string that names the subkey to delete. If @code{None},
deletes all subkeys and values of the specified key.

This function deletes a key and all its descendants. If `sub_key' is
@code{None}, all subkeys and values of the specified key are deleted.

Raises an @ref{1e65,,auditing event} @code{winreg.DeleteTree} with arguments @code{key}, @code{sub_key}.


Added in version 3.15.

@end deffn

@geindex DeleteValue() (στη μονάδα winreg)
@anchor{library/winreg winreg DeleteValue}@anchor{49be}
@deffn {Συνάρτηση} winreg.DeleteValue (key, value)

Removes a named value from a registry key.

`key' is an already open key, or one of the predefined
@ref{504b,,HKEY_* constants}.

`value' is a string that identifies the value to remove.

Raises an @ref{1e65,,auditing event} @code{winreg.DeleteValue} with arguments @code{key}, @code{value}.
@end deffn

@geindex EnumKey() (στη μονάδα winreg)
@anchor{library/winreg winreg EnumKey}@anchor{49bf}
@deffn {Συνάρτηση} 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{504b,,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{53c,,OSError} exception is
raised, indicating, no more values are available.

Raises an @ref{1e65,,auditing event} @code{winreg.EnumKey} with arguments @code{key}, @code{index}.


Άλλαξε στην έκδοση 3.3: See @ref{5046,,above}.

@end deffn

@geindex EnumValue() (στη μονάδα winreg)
@anchor{library/winreg winreg EnumValue}@anchor{49c0}
@deffn {Συνάρτηση} 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{504b,,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{53c,,OSError} exception is
raised, indicating no more values.

The result is a tuple of 3 items:


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Meaning

@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{1d02,,SetValueEx()})

@end multitable


Raises an @ref{1e65,,auditing event} @code{winreg.EnumValue} with arguments @code{key}, @code{index}.


Άλλαξε στην έκδοση 3.3: See @ref{5046,,above}.

@end deffn

@geindex % (percent);environment variables expansion (Windows)

@geindex ExpandEnvironmentStrings() (στη μονάδα winreg)
@anchor{library/winreg winreg ExpandEnvironmentStrings}@anchor{179a}
@deffn {Συνάρτηση} winreg.ExpandEnvironmentStrings (str)

Expands environment variable placeholders @code{%NAME%} in strings like
@ref{504f,,REG_EXPAND_SZ}:

@example
>>> ExpandEnvironmentStrings('%windir%')
'C:\\Windows'
@end example

Raises an @ref{1e65,,auditing event} @code{winreg.ExpandEnvironmentStrings} with argument @code{str}.
@end deffn

@geindex FlushKey() (στη μονάδα winreg)
@anchor{library/winreg winreg FlushKey}@anchor{5050}
@deffn {Συνάρτηση} 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{504b,,HKEY_* constants}.

It is not necessary to call @code{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{5049,,CloseKey()}, the
@code{FlushKey()} method returns only when all the data has been written to the
registry. An application should only call @code{FlushKey()} if it requires
absolute certainty that registry changes are on disk.

@cartouche
@quotation Σημείωση 
If you don’t know whether a @code{FlushKey()} call is required, it probably
isn’t.
@end quotation
@end cartouche
@end deffn

@geindex LoadKey() (στη μονάδα winreg)
@anchor{library/winreg winreg LoadKey}@anchor{49c1}
@deffn {Συνάρτηση} 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{49bb,,ConnectRegistry()} or one of the constants
@ref{5051,,HKEY_USERS} or @ref{5052,,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{49c6,,SaveKey()} function. Under the file allocation
table (FAT) file system, the filename may not have an extension.

A call to @code{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{49bb,,ConnectRegistry()}, then the path
specified in `file_name' is relative to the remote computer.

Raises an @ref{1e65,,auditing event} @code{winreg.LoadKey} with arguments @code{key}, @code{sub_key}, @code{file_name}.
@end deffn

@geindex OpenKey() (στη μονάδα winreg)
@geindex OpenKeyEx() (στη μονάδα winreg)
@anchor{library/winreg winreg OpenKey}@anchor{49c2}
@deffn {Συνάρτηση} winreg.OpenKey (key, sub_key, reserved=0, access=KEY_READ)
@anchor{library/winreg winreg OpenKeyEx}@anchor{5053}
@deffnx {Συνάρτηση} winreg.OpenKeyEx (key, sub_key, reserved=0, access=KEY_READ)

Opens the specified key, returning a @ref{5045,,handle object}.

`key' is an already open key, or one of the predefined
@ref{504b,,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{5054,,KEY_READ}.  See @ref{504d,,Access Rights} for other allowed values.

The result is a new handle to the specified key.

If the function fails, @ref{53c,,OSError} is raised.

Raises an @ref{1e65,,auditing event} @code{winreg.OpenKey} with arguments @code{key}, @code{sub_key}, @code{access}.

Raises an @ref{1e65,,auditing event} @code{winreg.OpenKey/result} with argument @code{key}.


Άλλαξε στην έκδοση 3.2: Allow the use of named arguments.



Άλλαξε στην έκδοση 3.3: See @ref{5046,,above}.

@end deffn

@geindex QueryInfoKey() (στη μονάδα winreg)
@anchor{library/winreg winreg QueryInfoKey}@anchor{49c4}
@deffn {Συνάρτηση} winreg.QueryInfoKey (key)

Returns information about a key, as a tuple.

`key' is an already open key, or one of the predefined
@ref{504b,,HKEY_* constants}.

The result is a tuple of 3 items:


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Meaning

@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{1e65,,auditing event} @code{winreg.QueryInfoKey} with argument @code{key}.
@end deffn

@geindex QueryValue() (στη μονάδα winreg)
@anchor{library/winreg winreg QueryValue}@anchor{49c5}
@deffn {Συνάρτηση} 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{504b,,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{49c7,,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{19a8,,QueryValueEx()} if possible.

Raises an @ref{1e65,,auditing event} @code{winreg.QueryValue} with arguments @code{key}, @code{sub_key}, @code{value_name}.
@end deffn

@geindex QueryValueEx() (στη μονάδα winreg)
@anchor{library/winreg winreg QueryValueEx}@anchor{19a8}
@deffn {Συνάρτηση} 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{504b,,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

Meaning

@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{1d02,,SetValueEx()})

@end multitable


Raises an @ref{1e65,,auditing event} @code{winreg.QueryValue} with arguments @code{key}, @code{sub_key}, @code{value_name}.
@end deffn

@geindex SaveKey() (στη μονάδα winreg)
@anchor{library/winreg winreg SaveKey}@anchor{49c6}
@deffn {Συνάρτηση} 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{504b,,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{49c1,,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{1e65,,auditing event} @code{winreg.SaveKey} with arguments @code{key}, @code{file_name}.
@end deffn

@geindex SetValue() (στη μονάδα winreg)
@anchor{library/winreg winreg SetValue}@anchor{49c7}
@deffn {Συνάρτηση} 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{504b,,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{5055,,REG_SZ}, meaning only strings are supported.  Use the @ref{1d02,,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{5056,,KEY_SET_VALUE} access.

Raises an @ref{1e65,,auditing event} @code{winreg.SetValue} with arguments @code{key}, @code{sub_key}, @code{type}, @code{value}.
@end deffn

@geindex SetValueEx() (στη μονάδα winreg)
@anchor{library/winreg winreg SetValueEx}@anchor{1d02}
@deffn {Συνάρτηση} 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{504b,,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{5057,,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{5056,,KEY_SET_VALUE} access.

To open the key, use the @ref{49bc,,CreateKey()} or @ref{49c2,,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{1e65,,auditing event} @code{winreg.SetValue} with arguments @code{key}, @code{sub_key}, @code{type}, @code{value}.
@end deffn

@geindex DisableReflectionKey() (στη μονάδα winreg)
@anchor{library/winreg winreg DisableReflectionKey}@anchor{1709}
@deffn {Συνάρτηση} 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{504b,,HKEY_* constants}.

Will generally raise @ref{59a,,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{1e65,,auditing event} @code{winreg.DisableReflectionKey} with argument @code{key}.
@end deffn

@geindex EnableReflectionKey() (στη μονάδα winreg)
@anchor{library/winreg winreg EnableReflectionKey}@anchor{170a}
@deffn {Συνάρτηση} winreg.EnableReflectionKey (key)

Restores registry reflection for the specified disabled key.

`key' is an already open key, or one of the predefined @ref{504b,,HKEY_* constants}.

Will generally raise @ref{59a,,NotImplementedError} if executed on a 32-bit operating
system.

Restoring reflection for a key does not affect reflection of any subkeys.

Raises an @ref{1e65,,auditing event} @code{winreg.EnableReflectionKey} with argument @code{key}.
@end deffn

@geindex QueryReflectionKey() (στη μονάδα winreg)
@anchor{library/winreg winreg QueryReflectionKey}@anchor{170b}
@deffn {Συνάρτηση} winreg.QueryReflectionKey (key)

Determines the reflection state for the specified key.

`key' is an already open key, or one of the predefined
@ref{504b,,HKEY_* constants}.

Returns @code{True} if reflection is disabled.

Will generally raise @ref{59a,,NotImplementedError} if executed on a 32-bit
operating system.

Raises an @ref{1e65,,auditing event} @code{winreg.QueryReflectionKey} with argument @code{key}.
@end deffn

@node Constants<10>,Registry Handle Objects,Functions<12>,winreg — Windows registry access
@anchor{library/winreg constants}@anchor{5058}@anchor{library/winreg id2}@anchor{5059}
@subsubsection Constants


The following constants are defined for use in many @code{winreg} functions.

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

@end menu

@node HKEY_* Constants,Access Rights,,Constants<10>
@anchor{library/winreg hkey-constants}@anchor{504b}@anchor{library/winreg id3}@anchor{505a}
@subsubsection HKEY_* Constants


@geindex HKEY_CLASSES_ROOT (στη μονάδα winreg)
@anchor{library/winreg winreg HKEY_CLASSES_ROOT}@anchor{505b}
@deffn {Δεδομένα} 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 (στη μονάδα winreg)
@anchor{library/winreg winreg HKEY_CURRENT_USER}@anchor{505c}
@deffn {Δεδομένα} 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 (στη μονάδα winreg)
@anchor{library/winreg winreg HKEY_LOCAL_MACHINE}@anchor{5052}
@deffn {Δεδομένα} 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 (στη μονάδα winreg)
@anchor{library/winreg winreg HKEY_USERS}@anchor{5051}
@deffn {Δεδομένα} 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 (στη μονάδα winreg)
@anchor{library/winreg winreg HKEY_PERFORMANCE_DATA}@anchor{505d}
@deffn {Δεδομένα} 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 (στη μονάδα winreg)
@anchor{library/winreg winreg HKEY_CURRENT_CONFIG}@anchor{505e}
@deffn {Δεδομένα} winreg.HKEY_CURRENT_CONFIG

Contains information about the current hardware profile of the
local computer system.
@end deffn

@geindex HKEY_DYN_DATA (στη μονάδα winreg)
@anchor{library/winreg winreg HKEY_DYN_DATA}@anchor{505f}
@deffn {Δεδομένα} winreg.HKEY_DYN_DATA

This key is not used in versions of Windows after 98.
@end deffn

@node Access Rights,Value Types,HKEY_* Constants,Constants<10>
@anchor{library/winreg access-rights}@anchor{504d}@anchor{library/winreg id4}@anchor{5060}
@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 (στη μονάδα winreg)
@anchor{library/winreg winreg KEY_ALL_ACCESS}@anchor{5061}
@deffn {Δεδομένα} winreg.KEY_ALL_ACCESS

Combines the STANDARD_RIGHTS_REQUIRED, @ref{5062,,KEY_QUERY_VALUE},
@ref{5056,,KEY_SET_VALUE}, @ref{5063,,KEY_CREATE_SUB_KEY},
@ref{5064,,KEY_ENUMERATE_SUB_KEYS}, @ref{5065,,KEY_NOTIFY},
and @ref{5066,,KEY_CREATE_LINK} access rights.
@end deffn

@geindex KEY_WRITE (στη μονάδα winreg)
@anchor{library/winreg winreg KEY_WRITE}@anchor{504c}
@deffn {Δεδομένα} winreg.KEY_WRITE

Combines the STANDARD_RIGHTS_WRITE, @ref{5056,,KEY_SET_VALUE}, and
@ref{5063,,KEY_CREATE_SUB_KEY} access rights.
@end deffn

@geindex KEY_READ (στη μονάδα winreg)
@anchor{library/winreg winreg KEY_READ}@anchor{5054}
@deffn {Δεδομένα} winreg.KEY_READ

Combines the STANDARD_RIGHTS_READ, @ref{5062,,KEY_QUERY_VALUE},
@ref{5064,,KEY_ENUMERATE_SUB_KEYS}, and @ref{5065,,KEY_NOTIFY} values.
@end deffn

@geindex KEY_EXECUTE (στη μονάδα winreg)
@anchor{library/winreg winreg KEY_EXECUTE}@anchor{5067}
@deffn {Δεδομένα} winreg.KEY_EXECUTE

Equivalent to @ref{5054,,KEY_READ}.
@end deffn

@geindex KEY_QUERY_VALUE (στη μονάδα winreg)
@anchor{library/winreg winreg KEY_QUERY_VALUE}@anchor{5062}
@deffn {Δεδομένα} winreg.KEY_QUERY_VALUE

Required to query the values of a registry key.
@end deffn

@geindex KEY_SET_VALUE (στη μονάδα winreg)
@anchor{library/winreg winreg KEY_SET_VALUE}@anchor{5056}
@deffn {Δεδομένα} winreg.KEY_SET_VALUE

Required to create, delete, or set a registry value.
@end deffn

@geindex KEY_CREATE_SUB_KEY (στη μονάδα winreg)
@anchor{library/winreg winreg KEY_CREATE_SUB_KEY}@anchor{5063}
@deffn {Δεδομένα} winreg.KEY_CREATE_SUB_KEY

Required to create a subkey of a registry key.
@end deffn

@geindex KEY_ENUMERATE_SUB_KEYS (στη μονάδα winreg)
@anchor{library/winreg winreg KEY_ENUMERATE_SUB_KEYS}@anchor{5064}
@deffn {Δεδομένα} winreg.KEY_ENUMERATE_SUB_KEYS

Required to enumerate the subkeys of a registry key.
@end deffn

@geindex KEY_NOTIFY (στη μονάδα winreg)
@anchor{library/winreg winreg KEY_NOTIFY}@anchor{5065}
@deffn {Δεδομένα} 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 (στη μονάδα winreg)
@anchor{library/winreg winreg KEY_CREATE_LINK}@anchor{5066}
@deffn {Δεδομένα} 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{5068}@anchor{library/winreg bit-specific}@anchor{5069}
@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 (στη μονάδα winreg)
@anchor{library/winreg winreg KEY_WOW64_64KEY}@anchor{504e}
@deffn {Δεδομένα} 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 (στη μονάδα winreg)
@anchor{library/winreg winreg KEY_WOW64_32KEY}@anchor{506a}
@deffn {Δεδομένα} 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,Constants<10>
@anchor{library/winreg id5}@anchor{506b}@anchor{library/winreg value-types}@anchor{5057}
@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 (στη μονάδα winreg)
@anchor{library/winreg winreg REG_BINARY}@anchor{506c}
@deffn {Δεδομένα} winreg.REG_BINARY

Binary data in any form.
@end deffn

@geindex REG_DWORD (στη μονάδα winreg)
@anchor{library/winreg winreg REG_DWORD}@anchor{506d}
@deffn {Δεδομένα} winreg.REG_DWORD

32-bit number.
@end deffn

@geindex REG_DWORD_LITTLE_ENDIAN (στη μονάδα winreg)
@anchor{library/winreg winreg REG_DWORD_LITTLE_ENDIAN}@anchor{506e}
@deffn {Δεδομένα} winreg.REG_DWORD_LITTLE_ENDIAN

A 32-bit number in little-endian format. Equivalent to @ref{506d,,REG_DWORD}.
@end deffn

@geindex REG_DWORD_BIG_ENDIAN (στη μονάδα winreg)
@anchor{library/winreg winreg REG_DWORD_BIG_ENDIAN}@anchor{506f}
@deffn {Δεδομένα} winreg.REG_DWORD_BIG_ENDIAN

A 32-bit number in big-endian format.
@end deffn

@geindex REG_EXPAND_SZ (στη μονάδα winreg)
@anchor{library/winreg winreg REG_EXPAND_SZ}@anchor{504f}
@deffn {Δεδομένα} winreg.REG_EXPAND_SZ

Null-terminated string containing references to environment
variables (@code{%PATH%}).
@end deffn

@geindex REG_LINK (στη μονάδα winreg)
@anchor{library/winreg winreg REG_LINK}@anchor{5070}
@deffn {Δεδομένα} winreg.REG_LINK

A Unicode symbolic link.
@end deffn

@geindex REG_MULTI_SZ (στη μονάδα winreg)
@anchor{library/winreg winreg REG_MULTI_SZ}@anchor{1fb3}
@deffn {Δεδομένα} 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 (στη μονάδα winreg)
@anchor{library/winreg winreg REG_NONE}@anchor{5071}
@deffn {Δεδομένα} winreg.REG_NONE

No defined value type.
@end deffn

@geindex REG_QWORD (στη μονάδα winreg)
@anchor{library/winreg winreg REG_QWORD}@anchor{10be}
@deffn {Δεδομένα} winreg.REG_QWORD

A 64-bit number.


Added in version 3.6.

@end deffn

@geindex REG_QWORD_LITTLE_ENDIAN (στη μονάδα winreg)
@anchor{library/winreg winreg REG_QWORD_LITTLE_ENDIAN}@anchor{5072}
@deffn {Δεδομένα} winreg.REG_QWORD_LITTLE_ENDIAN

A 64-bit number in little-endian format. Equivalent to @ref{10be,,REG_QWORD}.


Added in version 3.6.

@end deffn

@geindex REG_RESOURCE_LIST (στη μονάδα winreg)
@anchor{library/winreg winreg REG_RESOURCE_LIST}@anchor{5073}
@deffn {Δεδομένα} winreg.REG_RESOURCE_LIST

A device-driver resource list.
@end deffn

@geindex REG_FULL_RESOURCE_DESCRIPTOR (στη μονάδα winreg)
@anchor{library/winreg winreg REG_FULL_RESOURCE_DESCRIPTOR}@anchor{5074}
@deffn {Δεδομένα} winreg.REG_FULL_RESOURCE_DESCRIPTOR

A hardware setting.
@end deffn

@geindex REG_RESOURCE_REQUIREMENTS_LIST (στη μονάδα winreg)
@anchor{library/winreg winreg REG_RESOURCE_REQUIREMENTS_LIST}@anchor{5075}
@deffn {Δεδομένα} winreg.REG_RESOURCE_REQUIREMENTS_LIST

A hardware resource list.
@end deffn

@geindex REG_SZ (στη μονάδα winreg)
@anchor{library/winreg winreg REG_SZ}@anchor{5055}
@deffn {Δεδομένα} winreg.REG_SZ

A null-terminated string.
@end deffn

@node Registry Handle Objects,,Constants<10>,winreg — Windows registry access
@anchor{library/winreg handle-object}@anchor{5045}@anchor{library/winreg registry-handle-objects}@anchor{5076}
@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{504a,,Close()} method on the object, or the @ref{5049,,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{167a,,__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 equality comparison semantics, so handle objects will
compare equal if they both reference the same underlying Windows handle value.
Closed handle objects (those with a handle value of zero) always compare equal.

Handle objects can be converted to an integer (e.g., using the built-in
@ref{326,,int()} function), in which case the underlying Windows handle value is
returned.  You can also use the @ref{49c3,,Detach()} method to return the
integer handle, and also disconnect the Windows handle from the handle object.

@geindex Close() (μέθοδος της winreg.PyHKEY)
@anchor{library/winreg winreg PyHKEY Close}@anchor{504a}
@deffn {Μέθοδος} PyHKEY.Close ()

Closes the underlying Windows handle.

If the handle is already closed, no error is raised.
@end deffn

@geindex Detach() (μέθοδος της winreg.PyHKEY)
@anchor{library/winreg winreg PyHKEY Detach}@anchor{49c3}
@deffn {Μέθοδος} 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{1e65,,auditing event} @code{winreg.PyHKEY.Detach} with argument @code{key}.
@end deffn

@geindex __enter__() (μέθοδος της winreg.PyHKEY)
@geindex __exit__() (μέθοδος της winreg.PyHKEY)
@anchor{library/winreg winreg PyHKEY __enter__}@anchor{5077}
@deffn {Μέθοδος} PyHKEY.__enter__ ()
@anchor{library/winreg winreg PyHKEY __exit__}@anchor{5078}
@deffnx {Μέθοδος} PyHKEY.__exit__ (*exc_info)

The HKEY object implements @ref{9c6,,__enter__()} and
@ref{16a5,,__exit__()} and thus supports the context protocol for the
@ref{20a,,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{20a,,with} block.
@end deffn


Άλλαξε στην έκδοση 3.15: Handle objects are now compared by their underlying Windows handle value
instead of object identity for equality comparisons.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node winsound — Διεπαφή αναπαραγωγής ήχου για Windows,,winreg — Windows registry access,MS Windows Specific Services
@anchor{library/winsound doc}@anchor{5079}@anchor{library/winsound module-winsound}@anchor{120}@anchor{library/winsound translation-repo}@anchor{507a}@anchor{library/winsound winsound-sound-playing-interface-for-windows}@anchor{507b}
@subsection @code{winsound} — Διεπαφή αναπαραγωγής ήχου για Windows


@geindex module; winsound

`Source code:' PC/winsound.c@footnote{https://github.com/python/cpython/tree/main/PC/winsound.c}


__________________________________________________________________


The @code{winsound} module provides access to the basic sound-playing machinery
provided by Windows platforms.  It includes functions and several constants.

@ref{232d,,Διαθεσιμότητα}: Windows.

@menu
* Functions: Functions<13>. 
* Constants: Constants<11>. 

@end menu

@node Functions<13>,Constants<11>,,winsound — Διεπαφή αναπαραγωγής ήχου για Windows
@anchor{library/winsound functions}@anchor{507c}
@subsubsection Functions


@geindex Beep() (στη μονάδα winsound)
@anchor{library/winsound winsound Beep}@anchor{10c0}
@deffn {Συνάρτηση} winsound.Beep (frequency, duration)

Εκπέμπει ηχητικό σήμα από το ηχείο του υπολογιστή. Η παράμετρος `frequency' καθορίζει τη συχνότητα, σε hertz, του ήχου και πρέπει να είναι στο εύρος 37 έως 32.767. Η παράμετρος `duration' καθορίζει τον αριθμό των χιλιοστών του δευτερολέπτου που θα διαρκέσει ο ήχος. Εάν το σύστημα δεν μπορεί να κάνει ηχητικό σήμα στο ηχείο, γίνεται raise μια @ref{30d,,RuntimeError}.
@end deffn

@geindex PlaySound() (στη μονάδα winsound)
@anchor{library/winsound winsound PlaySound}@anchor{10c2}
@deffn {Συνάρτηση} winsound.PlaySound (sound, flags)

Καλεί την υποκείμενη συνάρτηση @code{PlaySound()} από το API της πλατφόρμας. Η παράμετρος `sound' μπορεί να είναι ένα όνομα αρχείου, ένα ψευδώνυμο συστήματος ήχου, δεδομένα ήχου ως @ref{436,,bytes-like object}, ή @code{None}. Η ερμηνεία της εξαρτάται από την τιμή των `flags', τα οποία μπορούν να είναι ένας bitwise ORed συνδυασμός των σταθερών που περιγράφονται παρακάτω. Εάν η παράμετρος `sound' είναι @code{None}, οποιοσδήποτε ήχος κύματος που παίζει αυτή τη στιγμή σταματά. Εάν το σύστημα υποδεικνύει σφάλμα, κάνει raise μια εξαίρεση @ref{30d,,RuntimeError}.
@end deffn

@geindex MessageBeep() (στη μονάδα winsound)
@anchor{library/winsound winsound MessageBeep}@anchor{10c1}
@deffn {Συνάρτηση} winsound.MessageBeep (type=MB_OK)

Καλεί την υποκείμενη συνάρτηση @code{MessageBeep()} από το API της πλατφόρμας. Αυτό αναπαράγει έναν ήχο όπως καθορίζεται στο μητρώο. Το όρισμα `type' καθορίζει ποιος ήχος θα αναπαραχθεί. Οι δυνατές τιμές είναι @code{-1}, @code{MB_ICONASTERISK}, @code{MB_ICONEXCLAMATION}, @code{MB_ICONHAND}, @code{MB_ICONQUESTION} και @code{MB_OK}, όλες περιγράφονται παρακάτω. Η τιμή @code{-1} παράγει ένα «απλό ηχητικό σήμα». Αυτό είναι το τελικό εφεδρικό αν δεν μπορεί να αναπαραχθεί άλλος ήχος. Εάν το σύστημα υποδεικνύει σφάλμα, γίνεται raise μια @ref{30d,,RuntimeError}.
@end deffn

@node Constants<11>,,Functions<13>,winsound — Διεπαφή αναπαραγωγής ήχου για Windows
@anchor{library/winsound constants}@anchor{507d}
@subsubsection Constants


@geindex SND_FILENAME (στη μονάδα winsound)
@anchor{library/winsound winsound SND_FILENAME}@anchor{507e}
@deffn {Δεδομένα} winsound.SND_FILENAME

The `sound' παράμετρος είναι το όνομα ενός αρχείου WAV. Μην το χρησιμοποιείτε με @ref{507f,,SND_ALIAS}.
@end deffn

@geindex SND_ALIAS (στη μονάδα winsound)
@anchor{library/winsound winsound SND_ALIAS}@anchor{507f}
@deffn {Δεδομένα} winsound.SND_ALIAS

Η παράμετρος `sound' είναι ένα όνομα συσχέτισης ήχου από το μητρώο. Εάν το μητρώο δεν περιέχει τέτοιο όνομα, αναπαράγει τον προεπιλεγμένο ήχο του συστήματος, εκτός εάν έχει καθοριστεί επίσης @ref{5080,,SND_NODEFAULT}. Εάν δεν είναι εγγεγραμμένος κανένας προεπιλεγμένος ήχος, γίνεται raise μια @ref{30d,,RuntimeError}. Μην το χρησιμοποιείτε με @ref{507e,,SND_FILENAME}.

Όλα τα συστήματα Win32 υποστηρίζουν τουλάχιστον τα παρακάτω. Τα περισσότερα συστήματα υποστηρίζουν πολύ περισσότερα:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@ref{10c2,,PlaySound()} `name'

@tab

Αντίστοιχο όνομα ήχου στον Πίνακα Ελέγχου

@item

@code{'SystemAsterisk'}

@tab

Αστερίσκος

@item

@code{'SystemExclamation'}

@tab

Αναφώνηση

@item

@code{'SystemExit'}

@tab

Έξοδος από τα Windows

@item

@code{'SystemHand'}

@tab

Κρίσιμη Διακοπή

@item

@code{'SystemQuestion'}

@tab

Ερώτηση

@end multitable


Για παράδειγμα:

@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 (στη μονάδα winsound)
@anchor{library/winsound winsound SND_LOOP}@anchor{5081}
@deffn {Δεδομένα} winsound.SND_LOOP

Αναπαράγει τον ήχο επανειλημμένα. Η σημαία @ref{5082,,SND_ASYNC} πρέπει επίσης να χρησιμοποιηθεί για να αποφευχθεί το μπλοκάρισμα. Δεν μπορεί να χρησιμοποιηθεί με @ref{5083,,SND_MEMORY}.
@end deffn

@geindex SND_MEMORY (στη μονάδα winsound)
@anchor{library/winsound winsound SND_MEMORY}@anchor{5083}
@deffn {Δεδομένα} winsound.SND_MEMORY

The `sound' παράμετρος της @ref{10c2,,PlaySound()} είναι μια εικόνα μνήμης ενός αρχείου WAV, ως @ref{436,,bytes-like object}.

@cartouche
@quotation Σημείωση 
Αυτό το module δεν υποστηρίζει την αναπαραγωγή από μια εικόνα μνήμης ασύγχρονα, οπότε ένας συνδυασμός αυτής της σημαίας και της @ref{5082,,SND_ASYNC} θα εγείρει @ref{30d,,RuntimeError}.
@end quotation
@end cartouche
@end deffn

@geindex SND_PURGE (στη μονάδα winsound)
@anchor{library/winsound winsound SND_PURGE}@anchor{5084}
@deffn {Δεδομένα} winsound.SND_PURGE

Σταματά την αναπαραγωγή όλων των περιπτώσεων του καθορισμένου ήχου.

@cartouche
@quotation Σημείωση 
Αυτή η σημαία δεν υποστηρίζεται σε σύγχρονες πλατφόρμες Windows.
@end quotation
@end cartouche
@end deffn

@geindex SND_ASYNC (στη μονάδα winsound)
@anchor{library/winsound winsound SND_ASYNC}@anchor{5082}
@deffn {Δεδομένα} winsound.SND_ASYNC

Επιστρέφει άμεσα, επιτρέποντας στους ήχους να αναπαράγονται ασύγχρονα.
@end deffn

@geindex SND_NODEFAULT (στη μονάδα winsound)
@anchor{library/winsound winsound SND_NODEFAULT}@anchor{5080}
@deffn {Δεδομένα} winsound.SND_NODEFAULT

Εάν ο καθορισμένος ήχος δεν μπορεί να βρεθεί, μην αναπαράγετε τον προεπιλεγμένο ήχο του συστήματος.
@end deffn

@geindex SND_NOSTOP (στη μονάδα winsound)
@anchor{library/winsound winsound SND_NOSTOP}@anchor{5085}
@deffn {Δεδομένα} winsound.SND_NOSTOP

Μην διακόπτετε τους ήχους που παίζουν αυτή τη στιγμή.
@end deffn

@geindex SND_NOWAIT (στη μονάδα winsound)
@anchor{library/winsound winsound SND_NOWAIT}@anchor{5086}
@deffn {Δεδομένα} winsound.SND_NOWAIT

Επιστρέφει άμεσα εάν ο οδηγός ήχου είναι απασχολημένος.

@cartouche
@quotation Σημείωση 
Αυτή η σημαία δεν υποστηρίζεται σε σύγχρονες πλατφόρμες Windows.
@end quotation
@end cartouche
@end deffn

@geindex SND_APPLICATION (στη μονάδα winsound)
@anchor{library/winsound winsound SND_APPLICATION}@anchor{5087}
@deffn {Δεδομένα} winsound.SND_APPLICATION

Η παράμετρος `sound' είναι ένα ψευδώνυμο συγκεκριμένης εφαρμογής στο μητρώο. Αυτή η σημαία μπορεί να συνδυαστεί με τη σημαία @ref{507f,,SND_ALIAS} για να καθορίσει ένα ψευδώνυμο ήχου που ορίζεται από την εφαρμογή.
@end deffn

@geindex SND_SENTRY (στη μονάδα winsound)
@anchor{library/winsound winsound SND_SENTRY}@anchor{5088}
@deffn {Δεδομένα} winsound.SND_SENTRY

Πυροδοτεί ένα γεγονός SoundSentry όταν αναπαράγεται ο ήχος.


Added in version 3.14.

@end deffn

@geindex SND_SYNC (στη μονάδα winsound)
@anchor{library/winsound winsound SND_SYNC}@anchor{5089}
@deffn {Δεδομένα} winsound.SND_SYNC

Ο ήχος αναπαράγεται συγχρονισμένα. Αυτή είναι η προεπιλεγμένη συμπεριφορά.


Added in version 3.14.

@end deffn

@geindex SND_SYSTEM (στη μονάδα winsound)
@anchor{library/winsound winsound SND_SYSTEM}@anchor{508a}
@deffn {Δεδομένα} winsound.SND_SYSTEM

Αναθέτει τον ήχο στην συνεδρία ήχου για ήχους ειδοποίησης συστήματος.


Added in version 3.14.

@end deffn

@geindex MB_ICONASTERISK (στη μονάδα winsound)
@anchor{library/winsound winsound MB_ICONASTERISK}@anchor{508b}
@deffn {Δεδομένα} winsound.MB_ICONASTERISK

Αναπαράγει τον ήχο @code{SystemDefault}.
@end deffn

@geindex MB_ICONEXCLAMATION (στη μονάδα winsound)
@anchor{library/winsound winsound MB_ICONEXCLAMATION}@anchor{508c}
@deffn {Δεδομένα} winsound.MB_ICONEXCLAMATION

Αναπαράγει τον ήχο @code{SystemExclamation}.
@end deffn

@geindex MB_ICONHAND (στη μονάδα winsound)
@anchor{library/winsound winsound MB_ICONHAND}@anchor{508d}
@deffn {Δεδομένα} winsound.MB_ICONHAND

Αναπαράγει τον ήχο @code{SystemHand}.
@end deffn

@geindex MB_ICONQUESTION (στη μονάδα winsound)
@anchor{library/winsound winsound MB_ICONQUESTION}@anchor{508e}
@deffn {Δεδομένα} winsound.MB_ICONQUESTION

Αναπαράγει τον ήχο @code{SystemQuestion}.
@end deffn

@geindex MB_OK (στη μονάδα winsound)
@anchor{library/winsound winsound MB_OK}@anchor{508f}
@deffn {Δεδομένα} winsound.MB_OK

Αναπαράγει τον ήχο @code{SystemDefault}.
@end deffn

@geindex MB_ICONERROR (στη μονάδα winsound)
@anchor{library/winsound winsound MB_ICONERROR}@anchor{5090}
@deffn {Δεδομένα} winsound.MB_ICONERROR

Αναπαράγει τον ήχο @code{SystemHand}.


Added in version 3.14.

@end deffn

@geindex MB_ICONINFORMATION (στη μονάδα winsound)
@anchor{library/winsound winsound MB_ICONINFORMATION}@anchor{5091}
@deffn {Δεδομένα} winsound.MB_ICONINFORMATION

Αναπαράγει τον ήχο @code{SystemDefault}.


Added in version 3.14.

@end deffn

@geindex MB_ICONSTOP (στη μονάδα winsound)
@anchor{library/winsound winsound MB_ICONSTOP}@anchor{5092}
@deffn {Δεδομένα} winsound.MB_ICONSTOP

Αναπαράγει τον ήχο @code{SystemHand}.


Added in version 3.14.

@end deffn

@geindex MB_ICONWARNING (στη μονάδα winsound)
@anchor{library/winsound winsound MB_ICONWARNING}@anchor{5093}
@deffn {Δεδομένα} winsound.MB_ICONWARNING

Αναπαράγει τον ήχο @code{SystemExclamation}.


Added in version 3.14.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Unix-specific services,Command-line interface Διεπαφή Γραμμής Εντολών CLI για modules,MS Windows Specific Services,The Python Standard Library
@anchor{library/unix doc}@anchor{5094}@anchor{library/unix translation-repo}@anchor{5095}@anchor{library/unix unix}@anchor{5096}@anchor{library/unix unix-specific-services}@anchor{5097}
@section Unix-specific services


The modules described in this chapter provide interfaces to features that are
unique to the Unix operating system, or in some cases to some or many variants
of it.  Here’s an overview:

@menu
* shlex — Simple lexical analysis:: 
* posix — The most common POSIX system calls:: 
* pwd — Η βάση δεδομένων κωδικών πρόσβασης:: 
* grp — The group database:: 
* termios — POSIX style tty control:: 
* tty — Terminal control functions:: 
* pty — Βοηθητικά προγράμματα ψευδοτερματικού:: 
* fcntl — The fcntl and ioctl system calls:: 
* resource — Resource usage information:: 
* syslog — Unix syslog library routines:: 

@end menu

@node shlex — Simple lexical analysis,posix — The most common POSIX system calls,,Unix-specific services
@anchor{library/shlex doc}@anchor{5098}@anchor{library/shlex module-shlex}@anchor{cc}@anchor{library/shlex shlex-simple-lexical-analysis}@anchor{5099}
@subsection @code{shlex} — Simple lexical analysis


@geindex module; shlex

`Source code:' Lib/shlex.py@footnote{https://github.com/python/cpython/tree/main/Lib/shlex.py}


__________________________________________________________________


The @ref{108a,,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 @code{shlex} module defines the following functions:

@geindex split() (στη μονάδα shlex)
@anchor{library/shlex shlex split}@anchor{949}
@deffn {Συνάρτηση} shlex.split (s, comments=False, posix=True)

Split the string `s' using shell-like syntax. If `comments' is @ref{ef5,,False}
(the default), the parsing of comments in the given string will be disabled
(setting the @ref{509a,,commenters} attribute of the
@ref{108a,,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.


Άλλαξε στην έκδοση 3.12: Passing @code{None} for `s' argument now raises an exception, rather than
reading @ref{94a,,sys.stdin}.

@end deffn

@geindex join() (στη μονάδα shlex)
@anchor{library/shlex shlex join}@anchor{deb}
@deffn {Συνάρτηση} shlex.join (split_command)

Concatenate the tokens of the list `split_command' and return a string.
This function is the inverse of @ref{949,,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{781,,quote()}).


Added in version 3.8.

@end deffn

@geindex quote() (στη μονάδα shlex)
@anchor{library/shlex shlex quote}@anchor{781}
@deffn {Συνάρτηση} 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{399d}
@cartouche
@quotation Προειδοποίηση 
The @code{shlex} module is `only designed for Unix shells'.

The @code{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{f45,,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

@code{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{949,,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


Added in version 3.3.

@end deffn

The @code{shlex} module defines the following class:

@geindex shlex (κλάση σε shlex)
@anchor{library/shlex shlex shlex}@anchor{108a}
@deffn {Κλάση} shlex.shlex (instream=None, infile=None, posix=False, punctuation_chars=False)

A @ref{108a,,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{225b,,read()} and @ref{2296,,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{509b,,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 @code{shlex} instance will
operate in compatibility mode.  When operating in POSIX mode,
@code{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{509c,,wordchars} attribute that appear in
`punctuation_chars' will be removed from @code{wordchars}.  See
@ref{108b,,Improved Compatibility with Shells} for more information. `punctuation_chars'
can be set only upon @code{shlex} instance creation and can’t be
modified later.


Άλλαξε στην έκδοση 3.6: The `punctuation_chars' parameter was added.

@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{26,,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{509d}@anchor{library/shlex shlex-objects}@anchor{509e}
@subsubsection shlex Objects


A @ref{108a,,shlex} instance has the following methods:

@geindex get_token() (μέθοδος της shlex.shlex)
@anchor{library/shlex shlex shlex get_token}@anchor{509f}
@deffn {Μέθοδος} shlex.get_token ()

Return a token.  If tokens have been stacked using @ref{50a0,,push_token()}, pop a
token off the stack.  Otherwise, read one from the input stream.  If reading
encounters an immediate end-of-file, @ref{50a1,,eof} is returned (the empty
string (@code{'@w{'}}) in non-POSIX mode, and @code{None} in POSIX mode).
@end deffn

@geindex push_token() (μέθοδος της shlex.shlex)
@anchor{library/shlex shlex shlex push_token}@anchor{50a0}
@deffn {Μέθοδος} shlex.push_token (str)

Push the argument onto the token stack.
@end deffn

@geindex read_token() (μέθοδος της shlex.shlex)
@anchor{library/shlex shlex shlex read_token}@anchor{50a2}
@deffn {Μέθοδος} 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() (μέθοδος της shlex.shlex)
@anchor{library/shlex shlex shlex sourcehook}@anchor{50a3}
@deffn {Μέθοδος} shlex.sourcehook (filename)

When @ref{108a,,shlex} detects a source request (see @ref{50a4,,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{32b,,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{70b,,close()} method of the sourced input stream when it returns
EOF.

For more explicit control of source stacking, use the @ref{50a5,,push_source()} and
@ref{50a6,,pop_source()} methods.
@end deffn

@geindex push_source() (μέθοδος της shlex.shlex)
@anchor{library/shlex shlex shlex push_source}@anchor{50a5}
@deffn {Μέθοδος} 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{50a3,,sourcehook()} method.
@end deffn

@geindex pop_source() (μέθοδος της shlex.shlex)
@anchor{library/shlex shlex shlex pop_source}@anchor{50a6}
@deffn {Μέθοδος} 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() (μέθοδος της shlex.shlex)
@anchor{library/shlex shlex shlex error_leader}@anchor{50a7}
@deffn {Μέθοδος} 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 @code{shlex} users to generate error
messages in the standard, parseable format understood by Emacs and other Unix
tools.
@end deffn

Instances of @ref{108a,,shlex} subclasses have some public instance
variables which either control lexical analysis or can be used for debugging:

@geindex commenters (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex commenters}@anchor{509a}
@deffn {Ιδιότητα} 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 (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex wordchars}@anchor{509c}
@deffn {Ιδιότητα} 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{1fa6,,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{50a8,,whitespace_split} is set to @code{True}, this will have no
effect.
@end deffn

@geindex whitespace (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex whitespace}@anchor{50a9}
@deffn {Ιδιότητα} 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 (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex escape}@anchor{50aa}
@deffn {Ιδιότητα} 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 (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex quotes}@anchor{50ab}
@deffn {Ιδιότητα} 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 (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex escapedquotes}@anchor{50ac}
@deffn {Ιδιότητα} shlex.escapedquotes

Characters in @ref{50ab,,quotes} that will interpret escape characters defined in
@ref{50aa,,escape}.  This is only used in POSIX mode, and includes just @code{'"'} by
default.
@end deffn

@geindex whitespace_split (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex whitespace_split}@anchor{50a8}
@deffn {Ιδιότητα} shlex.whitespace_split

If @code{True}, tokens will only be split in whitespaces.  This is useful, for
example, for parsing command lines with @ref{108a,,shlex}, getting
tokens in a similar way to shell arguments.  When used in combination with
@ref{1fa6,,punctuation_chars}, tokens will be split on whitespace in addition to
those characters.


Άλλαξε στην έκδοση 3.8: The @ref{1fa6,,punctuation_chars} attribute was made compatible with the
@ref{50a8,,whitespace_split} attribute.

@end deffn

@geindex infile (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex infile}@anchor{509b}
@deffn {Ιδιότητα} 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 (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex instream}@anchor{50ad}
@deffn {Ιδιότητα} shlex.instream

The input stream from which this @ref{108a,,shlex} instance is reading
characters.
@end deffn

@geindex source (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex source}@anchor{50a4}
@deffn {Ιδιότητα} 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{70b,,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 (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex debug}@anchor{50ae}
@deffn {Ιδιότητα} shlex.debug

If this attribute is numeric and @code{1} or more, a @ref{108a,,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 (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex lineno}@anchor{50af}
@deffn {Ιδιότητα} shlex.lineno

Source line number (count of newlines seen so far plus one).
@end deffn

@geindex token (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex token}@anchor{50b0}
@deffn {Ιδιότητα} shlex.token

The token buffer.  It may be useful to examine this when catching exceptions.
@end deffn

@geindex eof (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex eof}@anchor{50a1}
@deffn {Ιδιότητα} 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 (ιδιότητα της shlex.shlex)
@anchor{library/shlex shlex shlex punctuation_chars}@anchor{1fa6}
@deffn {Ιδιότητα} 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.


Added in version 3.6.

@end deffn

@node Parsing Rules,Improved Compatibility with Shells,shlex Objects,shlex — Simple lexical analysis
@anchor{library/shlex parsing-rules}@anchor{50b1}@anchor{library/shlex shlex-parsing-rules}@anchor{50b2}
@subsubsection Parsing Rules


When operating in non-POSIX mode, @ref{108a,,shlex} will try to obey 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{50a8,,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{108a,,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{108a,,shlex} will try to obey 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{50ac,,escapedquotes} (e.g. @code{"'"}) preserve the literal value
of all characters within the quotes;

@item 
Enclosing characters in quotes which are part of
@ref{50ac,,escapedquotes} (e.g. @code{'"'}) preserves the literal value
of all characters within the quotes, with the exception of the characters
mentioned in @ref{50aa,,escape}.  The escape characters retain their
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{a65,,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{50b3}@anchor{library/shlex improved-shell-compatibility}@anchor{108b}
@subsubsection Improved Compatibility with Shells



Added in version 3.6.


The @ref{cc,,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 Σημείωση 
When @code{punctuation_chars} is specified, the @ref{509c,,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{50a8,,whitespace_split} when using
@ref{1fa6,,punctuation_chars}, which will negate
@ref{509c,,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{108a,,shlex}.)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node posix — The most common POSIX system calls,pwd — Η βάση δεδομένων κωδικών πρόσβασης,shlex — Simple lexical analysis,Unix-specific services
@anchor{library/posix doc}@anchor{50b4}@anchor{library/posix module-posix}@anchor{b2}@anchor{library/posix posix-the-most-common-posix-system-calls}@anchor{50b5}@anchor{library/posix translation-repo}@anchor{50b6}
@subsection @code{posix} — The most common POSIX system calls


@geindex module; posix


__________________________________________________________________


This module provides access to operating system functionality that is
standardized by the C Standard and the POSIX standard (a thinly disguised Unix
interface).

@ref{232d,,Διαθεσιμότητα}: Unix.

@geindex module;os

`Do not import this module directly.'  Instead, import the module @ref{a5,,os},
which provides a `portable' version of this interface.  On Unix, the @code{os}
module provides a superset of the @code{posix} interface.  On non-Unix operating
systems the @code{posix} module is not available, but a subset is always
available through the @code{os} interface.  Once @code{os} is imported, there is
`no' performance penalty in using it instead of @code{posix}.  In addition,
@code{os} provides some additional functionality, such as automatically calling
@ref{4e7,,putenv()} when an entry in @code{os.environ} is changed.

Errors are reported as exceptions; the usual exceptions are given for type
errors, while errors reported by the system calls raise @ref{53c,,OSError}.

@menu
* Large File Support:: 
* Notable Module Contents:: 

@end menu

@node Large File Support,Notable Module Contents,,posix — The most common POSIX system calls
@anchor{library/posix large-file-support}@anchor{50b7}@anchor{library/posix posix-large-files}@anchor{50b8}
@subsubsection Large File Support


@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

On large-file-capable Linux systems, this might work:

@example
CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \
        ./configure
@end example

@node Notable Module Contents,,Large File Support,posix — The most common POSIX system calls
@anchor{library/posix notable-module-contents}@anchor{50b9}@anchor{library/posix posix-contents}@anchor{50ba}
@subsubsection Notable Module Contents


In addition to many functions described in the @ref{a5,,os} module documentation,
@code{posix} defines the following data item:

@geindex environ (στη μονάδα posix)
@anchor{library/posix posix environ}@anchor{50bb}
@deffn {Δεδομένα} posix.environ

A dictionary representing the string environment at the time the interpreter
was started. Keys and values are bytes on Unix and str on Windows. For
example, @code{environ[b'HOME']} (@code{environ['HOME']} on Windows) is the
pathname of your home directory, equivalent to @code{getenv("HOME")} in C.

Modifying this dictionary does not affect the string environment passed on by
@ref{323e,,execv()}, @ref{585,,popen()} or @ref{17ff,,system()}; if you need to
change the environment, pass @code{environ} to @ref{14a5,,execve()} or add
variable assignments and export statements to the command string for
@code{system()} or @code{popen()}.


Άλλαξε στην έκδοση 3.2: On Unix, keys and values are bytes.


@cartouche
@quotation Σημείωση 
The @ref{a5,,os} module provides an alternate implementation of @code{environ}
which updates the environment on modification. Note also that updating
@ref{4e5,,os.environ} will render this dictionary obsolete. Use of the
@code{os} module version of this is recommended over direct access to the
@code{posix} module.
@end quotation
@end cartouche
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node pwd — Η βάση δεδομένων κωδικών πρόσβασης,grp — The group database,posix — The most common POSIX system calls,Unix-specific services
@anchor{library/pwd doc}@anchor{50bc}@anchor{library/pwd module-pwd}@anchor{ba}@anchor{library/pwd pwd-the-password-database}@anchor{50bd}@anchor{library/pwd translation-repo}@anchor{50be}
@subsection @code{pwd} — Η βάση δεδομένων κωδικών πρόσβασης


@geindex module; pwd


__________________________________________________________________


Αυτό το module παρέχει πρόσβαση στη βάση δεδομένων λογαριασμών χρηστών και κωδικών πρόσβασης του Unix. Είναι διαθέσιμο σε όλες τις εκδόσεις του Unix.

@ref{232d,,Διαθεσιμότητα}: Unix, not WASI, not iOS.

Οι εγγραφές της βάσης δεδομένων κωδικών πρόσβασης αναφέρονται ως ένα αντικείμενο παρόμοιο με πλειάδα, του οποίου τα χαρακτηριστικά αντιστοιχούν στα μέλη της δομής @code{passwd} (Πεδίο χαρακτηριστικού παρακάτω, δείτε @code{<pwd.h>}):


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Δείκτης

@tab

Χαρακτηριστικό

@tab

Σημασία

@item

0

@tab

@code{pw_name}

@tab

Όνομα σύνδεσης

@item

1

@tab

@code{pw_passwd}

@tab

Προαιρετικός κρυπτογραφημένος κωδικός πρόσβασης

@item

2

@tab

@code{pw_uid}

@tab

Αριθμητικό αναγνωριστικό χρήστη

@item

3

@tab

@code{pw_gid}

@tab

Αριθμητικό αναγνωριστικό γκρουπ

@item

4

@tab

@code{pw_gecos}

@tab

Όνομα χρήστη ή πεδίο σχολίου

@item

5

@tab

@code{pw_dir}

@tab

Κατάλογος αρχικού καταλόγου χρήστη

@item

6

@tab

@code{pw_shell}

@tab

Διερμηνέας εντολών χρήστη

@end multitable


Τα στοιχεία uid και gid είναι ακέραιοι, όλα τα άλλα είναι συμβολοσειρές. @ref{7df,,KeyError} γίνεται raise εάν η ζητούμενη εγγραφή δεν μπορεί να βρεθεί.

@cartouche
@quotation Σημείωση 
Στο παραδοσιακό Unix, το πεδίο @code{pw_passwd} συνήθως περιέχει έναν κωδικό πρόσβασης κρυπτογραφημένο με έναν αλγόριθμο που προέρχεται από το DES. Ωστόσο, τα περισσότερα σύγχρονα unices χρησιμοποιούν ένα λεγόμενο σύστημα `shadow password'. Σε αυτά τα unices, το πεδίο `pw_passwd' περιέχει μόνο έναν αστερίσκο (@code{'*'}) ή το γράμμα @code{'x'} όπου ο κρυπτογραφημένος κωδικός πρόσβασης αποθηκεύεται σε ένα αρχείο @code{/etc/shadow} που δεν είναι αναγνώσιμο από όλους. Το αν το πεδίο `pw_passwd' περιέχει κάτι χρήσιμο εξαρτάται από το σύστημα.
@end quotation
@end cartouche

Ορίζει τα ακόλουθα στοιχεία:

@geindex getpwuid() (στη μονάδα pwd)
@anchor{library/pwd pwd getpwuid}@anchor{2000}
@deffn {Συνάρτηση} pwd.getpwuid (uid)

Επιστρέφει την εγγραφή της βάσης δεδομένων κωδικών πρόσβασης για το δεδομένο αριθμητικό αναγνωριστικό χρήστη.
@end deffn

@geindex getpwnam() (στη μονάδα pwd)
@anchor{library/pwd pwd getpwnam}@anchor{398d}
@deffn {Συνάρτηση} pwd.getpwnam (name)

Επιστρέφει την εγγραφή της βάσης δεδομένων κωδικών πρόσβασης για το δεδομένο όνομα χρήστη.
@end deffn

@geindex getpwall() (στη μονάδα pwd)
@anchor{library/pwd pwd getpwall}@anchor{50bf}
@deffn {Συνάρτηση} pwd.getpwall ()

Επιστρέφει μια λίστα με όλες τις διαθέσιμες εγγραφές της βάσης δεδομένων κωδικών πρόσβασης, σε τυχαία σειρά.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{69,,grp}

Μια διεπαφή στη βάση δεδομένων ομάδων, παρόμοια με αυτή.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node grp — The group database,termios — POSIX style tty control,pwd — Η βάση δεδομένων κωδικών πρόσβασης,Unix-specific services
@anchor{library/grp doc}@anchor{50c0}@anchor{library/grp grp-the-group-database}@anchor{50c1}@anchor{library/grp module-grp}@anchor{69}@anchor{library/grp translation-repo}@anchor{50c2}
@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{232d,,Διαθεσιμότητα}: 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

Attribute

@tab

Meaning

@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{398c,,getgrnam()} or @ref{10e0,,getgrgid()}.)

It defines the following items:

@geindex getgrgid() (στη μονάδα grp)
@anchor{library/grp grp getgrgid}@anchor{10e0}
@deffn {Συνάρτηση} grp.getgrgid (id)

Return the group database entry for the given numeric group ID. @ref{7df,,KeyError}
is raised if the entry asked for cannot be found.


Άλλαξε στην έκδοση 3.10: @ref{291,,TypeError} is raised for non-integer arguments like floats or strings.

@end deffn

@geindex getgrnam() (στη μονάδα grp)
@anchor{library/grp grp getgrnam}@anchor{398c}
@deffn {Συνάρτηση} grp.getgrnam (name)

Return the group database entry for the given group name. @ref{7df,,KeyError} is
raised if the entry asked for cannot be found.
@end deffn

@geindex getgrall() (στη μονάδα grp)
@anchor{library/grp grp getgrall}@anchor{1b09}
@deffn {Συνάρτηση} grp.getgrall ()

Return a list of all available group entries, in arbitrary order.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{ba,,pwd}

An interface to the user database, similar to this.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node termios — POSIX style tty control,tty — Terminal control functions,grp — The group database,Unix-specific services
@anchor{library/termios doc}@anchor{50c3}@anchor{library/termios module-termios}@anchor{ea}@anchor{library/termios termios-posix-style-tty-control}@anchor{50c4}@anchor{library/termios translation-repo}@anchor{50c5}
@subsection @code{termios} — POSIX style tty control


@geindex module; termios

@geindex POSIX;I/O control
@geindex tty;I/O control


__________________________________________________________________


This module provides an interface to the POSIX calls for tty I/O control. For a
complete description of these calls, see @code{termios(3)@footnote{https://manpages.debian.org/termios(3)}} Unix manual
page.  It is only available for those Unix versions that support POSIX
`termios' style tty I/O control configured during installation.

@ref{232d,,Διαθεσιμότητα}: Unix.

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 a @ref{156c,,file object}, such as @code{sys.stdin} itself.

This module also defines all the constants needed to work with the functions
provided here; these have the same name as their counterparts in C.  Please
refer to your system documentation for more information on using these terminal
control interfaces.

The module defines the following functions:

@geindex tcgetattr() (στη μονάδα termios)
@anchor{library/termios termios tcgetattr}@anchor{1bfc}
@deffn {Συνάρτηση} termios.tcgetattr (fd)

Return a list containing the tty attributes for file descriptor `fd', as
follows: @code{[iflag, oflag, cflag, lflag, ispeed, ospeed, cc]} where `cc' is a
list of the tty special characters (each a string of length 1, except the
items with indices @code{VMIN} and @code{VTIME}, which are integers when
these fields are defined).  The interpretation of the flags and the speeds as
well as the indexing in the `cc' array must be done using the symbolic
constants defined in the @code{termios} module.
@end deffn

@geindex tcsetattr() (στη μονάδα termios)
@anchor{library/termios termios tcsetattr}@anchor{1c6f}
@deffn {Συνάρτηση} 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{1bfc,,tcgetattr()}.  The `when' argument
determines when the attributes are changed:

@geindex TCSANOW (στη μονάδα termios)
@anchor{library/termios termios TCSANOW}@anchor{50c6}
@deffn {Δεδομένα} termios.TCSANOW

Change attributes immediately.
@end deffn

@geindex TCSADRAIN (στη μονάδα termios)
@anchor{library/termios termios TCSADRAIN}@anchor{50c7}
@deffn {Δεδομένα} termios.TCSADRAIN

Change attributes after transmitting all queued output.
@end deffn

@geindex TCSAFLUSH (στη μονάδα termios)
@anchor{library/termios termios TCSAFLUSH}@anchor{50c8}
@deffn {Δεδομένα} termios.TCSAFLUSH

Change attributes after transmitting all queued output and
discarding all queued input.
@end deffn
@end deffn

@geindex tcsendbreak() (στη μονάδα termios)
@anchor{library/termios termios tcsendbreak}@anchor{50c9}
@deffn {Συνάρτηση} termios.tcsendbreak (fd, duration)

Send a break on file descriptor `fd'.  A zero `duration' sends a break for
0.25–0.5 seconds; a nonzero `duration' has a system dependent meaning.
@end deffn

@geindex tcdrain() (στη μονάδα termios)
@anchor{library/termios termios tcdrain}@anchor{50ca}
@deffn {Συνάρτηση} termios.tcdrain (fd)

Wait until all output written to file descriptor `fd' has been transmitted.
@end deffn

@geindex tcflush() (στη μονάδα termios)
@anchor{library/termios termios tcflush}@anchor{50cb}
@deffn {Συνάρτηση} termios.tcflush (fd, queue)

Discard queued data on file descriptor `fd'.  The `queue' selector specifies
which queue: @code{TCIFLUSH} for the input queue, @code{TCOFLUSH} for the
output queue, or @code{TCIOFLUSH} for both queues.
@end deffn

@geindex tcflow() (στη μονάδα termios)
@anchor{library/termios termios tcflow}@anchor{50cc}
@deffn {Συνάρτηση} termios.tcflow (fd, action)

Suspend or resume input or output on file descriptor `fd'.  The `action'
argument can be @code{TCOOFF} to suspend output, @code{TCOON} to restart
output, @code{TCIOFF} to suspend input, or @code{TCION} to restart input.
@end deffn

@geindex tcgetwinsize() (στη μονάδα termios)
@anchor{library/termios termios tcgetwinsize}@anchor{50cd}
@deffn {Συνάρτηση} 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}.


Added in version 3.11.

@end deffn

@geindex tcsetwinsize() (στη μονάδα termios)
@anchor{library/termios termios tcsetwinsize}@anchor{192e}
@deffn {Συνάρτηση} 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{50cd,,tcgetwinsize()}. Requires at least one of the pairs
(@code{termios.TIOCGWINSZ}, @code{termios.TIOCSWINSZ});
(@code{termios.TIOCGSIZE}, @code{termios.TIOCSSIZE}) to be defined.


Added in version 3.11.

@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{109,,tty}

Convenience functions for common terminal control operations.
@end table


@menu
* Example: Example<14>. 

@end menu

@node Example<14>,,,termios — POSIX style tty control
@anchor{library/termios example}@anchor{50ce}@anchor{library/termios termios-example}@anchor{50cf}
@subsubsection Example


Here’s a function that prompts for a password with echoing turned off.  Note the
technique using a separate @ref{1bfc,,tcgetattr()} call and a @ref{ad6,,try} …
@ref{44c,,finally} statement to ensure that the old tty attributes are restored
exactly no matter what happens:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tty — Terminal control functions,pty — Βοηθητικά προγράμματα ψευδοτερματικού,termios — POSIX style tty control,Unix-specific services
@anchor{library/tty doc}@anchor{50d0}@anchor{library/tty module-tty}@anchor{109}@anchor{library/tty translation-repo}@anchor{50d1}@anchor{library/tty tty-terminal-control-functions}@anchor{50d2}
@subsection @code{tty} — Terminal control functions


@geindex module; tty

`Source code:' Lib/tty.py@footnote{https://github.com/python/cpython/tree/main/Lib/tty.py}


__________________________________________________________________


The @code{tty} module defines functions for putting the tty into cbreak and raw
modes.

@ref{232d,,Διαθεσιμότητα}: Unix.

Because it requires the @ref{ea,,termios} module, it will work only on Unix.

The @code{tty} module defines the following functions:

@geindex cfmakeraw() (στη μονάδα tty)
@anchor{library/tty tty cfmakeraw}@anchor{1c49}
@deffn {Συνάρτηση} tty.cfmakeraw (mode)

Convert the tty attribute list `mode', which is a list like the one returned
by @ref{1bfc,,termios.tcgetattr()}, to that of a tty in raw mode.


Added in version 3.12.

@end deffn

@geindex cfmakecbreak() (στη μονάδα tty)
@anchor{library/tty tty cfmakecbreak}@anchor{1bfe}
@deffn {Συνάρτηση} tty.cfmakecbreak (mode)

Convert the tty attribute list `mode', which is a list like the one returned
by @ref{1bfc,,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.


Added in version 3.12.



Άλλαξε στην έκδοση 3.12.2: The @code{ICRNL} flag is no longer cleared. This matches Linux and macOS
@code{stty cbreak} behavior and what @ref{1bfd,,setcbreak()} historically did.

@end deffn

@geindex setraw() (στη μονάδα tty)
@anchor{library/tty tty setraw}@anchor{1c48}
@deffn {Συνάρτηση} tty.setraw (fd, when=termios.TCSAFLUSH)

Change the mode of the file descriptor `fd' to raw. If `when' is omitted, it
defaults to @ref{50c8,,termios.TCSAFLUSH}, and is passed to
@ref{1c6f,,termios.tcsetattr()}. The return value of @ref{1bfc,,termios.tcgetattr()}
is saved before setting `fd' to raw mode; this value is returned.


Άλλαξε στην έκδοση 3.12: The return value is now the original tty attributes, instead of @code{None}.

@end deffn

@geindex setcbreak() (στη μονάδα tty)
@anchor{library/tty tty setcbreak}@anchor{1bfd}
@deffn {Συνάρτηση} tty.setcbreak (fd, when=termios.TCSAFLUSH)

Change the mode of file descriptor `fd' to cbreak. If `when' is omitted, it
defaults to @ref{50c8,,termios.TCSAFLUSH}, and is passed to
@ref{1c6f,,termios.tcsetattr()}. The return value of @ref{1bfc,,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.


Άλλαξε στην έκδοση 3.12: The return value is now the original tty attributes, instead of @code{None}.



Άλλαξε στην έκδοση 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 Δείτε επίσης



@table @asis

@item Module @ref{ea,,termios}

Low-level terminal control interface.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node pty — Βοηθητικά προγράμματα ψευδοτερματικού,fcntl — The fcntl and ioctl system calls,tty — Terminal control functions,Unix-specific services
@anchor{library/pty doc}@anchor{50d3}@anchor{library/pty module-pty}@anchor{b9}@anchor{library/pty pty-pseudo-terminal-utilities}@anchor{50d4}@anchor{library/pty translation-repo}@anchor{50d5}
@subsection @code{pty} — Βοηθητικά προγράμματα ψευδοτερματικού


@geindex module; pty

`Πηγαίος κώδικας:' Lib/pty.py@footnote{https://github.com/python/cpython/tree/main/Lib/pty.py}


__________________________________________________________________


The @code{pty} module defines operations for handling the pseudo-terminal
concept: starting another process and being able to write to and read from its
controlling terminal programmatically.

@ref{232d,,Διαθεσιμότητα}: Unix.

Η διαχείριση ψευδοτερματικού είναι εξαιρετικά εξαρτώμενη από την πλατφόρμα. Αυτός ο κώδικας έχει δοκιμαστεί κυρίως σε Linux, FreeBSD και macOS (υποτίθεται ότι λειτουργεί σε άλλες πλατφόρμες POSIX αλλά δεν έχει δοκιμαστεί διεξοδώς).

The @code{pty} module defines the following functions:

@geindex fork() (στη μονάδα pty)
@anchor{library/pty pty fork}@anchor{1cca}
@deffn {Συνάρτηση} pty.fork ()

Αντιγραφή. Συνδέστε το τερματικό ελέγχου του παιδιού σε ένα ψευδοτερματικό. Η επιστρεφόμενη τιμή είναι @code{(pid, fd)}. Σημειώστε ότι το παιδί λαμβάνει `pid' 0, και το `fd' είναι `invalid'. Η επιστρεφόμενη τιμή του γονέα είναι το `pid' του παιδιού, και το `fd' είναι ένας περιγραφέας αρχείου συνδεδεμένος με το τερματικό ελέγχου του παιδιού (και επίσης με την τυπική είσοδο και έξοδο του παιδιού).

The returned file descriptor `fd' is @ref{12aa,,non-inheritable}.

@cartouche
@quotation Προειδοποίηση 
Σε macOS η χρήση αυτής της λειτουργίας είναι μη ασφαλής όταν αναμιγνύεται με τη χρήση ανώτερων συστημικών APIs, και αυτό περιλαμβάνει τη χρήση @ref{114,,urllib.request}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.15: The returned file descriptor is now made non-inheritable.

@end deffn

@geindex openpty() (στη μονάδα pty)
@anchor{library/pty pty openpty}@anchor{579}
@deffn {Συνάρτηση} pty.openpty ()

Ανοίξτε ένα νέο ζεύγος ψευδοτερματικών, χρησιμοποιώντας @ref{327f,,os.openpty()} αν είναι δυνατόν, ή κώδικα προσομοίωσης για γενικά συστήματα Unix. Επιστρέφει ένα ζεύγος περιγραφέων αρχείων @code{(master, slave)}, για το κύριο και το δευτερεύον άκρο, αντίστοιχα.
@end deffn

@geindex spawn() (στη μονάδα pty)
@anchor{library/pty pty spawn}@anchor{132c}
@deffn {Συνάρτηση} pty.spawn (argv[, master_read[, stdin_read]])

Δημιουργήστε μια διαδικασία, και συνδέστε το τερματικό ελέγχου της με την τυπική είσοδο/έξοδο της τρέχουσας διαδικασίας. Αυτό χρησιμοποιείται συχνά για να αποπροσανατολίσει προγράμματα που επιμένουν να διαβάζουν από το τερματικό ελέγχου. Αναμένεται ότι η διαδικασία που ξεκίνησε πίσω από το pty θα τερματιστεί τελικά, και όταν το κάνει `spawn' θα επιστρέψει.

Ένας βρόχος αντιγράφει την STDIN της τρέχουσας διαδικασίας στο παιδί και τα δεδομένα που λαμβάνονται από το παιδί στην STDOUT της τρέχουσας διαδικασίας. Δεν ειδοποιείται το παιδί εάν η STDIN της τρέχουσας διαδικασίας κλείσει.

Οι συναρτήσεις `master_read' και `stdin_read' λαμβάνουν έναν περιγραφέα αρχείου από τον οποίο πρέπει να διαβάσουν, και θα πρέπει πάντα να επιστρέφουν ένα byte string. Για να αναγκάσετε το spawn να επιστρέψει πριν τερματιστεί η διαδικασία παιδί, θα πρέπει να επιστραφεί ένας κενός πίνακας byte για να σηματοδοτήσει το τέλος του αρχείου.

Η προεπιλεγμένη υλοποίηση και για τις δύο συναρτήσεις θα διαβάσει και θα επιστρέψει έως και 1024 bytes κάθε φορά που καλείται η συνάρτηση. Στην κλήση `master_read' περνάει ο περιγραφέας αρχείου του κύριου ψευδοτερματικού για να διαβάσει την έξοδο από τη διαδικασία παιδί, και στην `stdin_read' περνάει ο περιγραφέας αρχείου 0, για να διαβάσει από την τυπική είσοδο της διαδικασίας γονέα.

Επιστροφή ενός κενό πίνακα byte από οποιαδήποτε κλήση ερμηνεύεται ως κατάσταση τέλους-αρχείου (EOF), και αυτή η κλήση δεν θα κληθεί μετά από αυτό. Εάν η `stdin_read' σηματοδοτήσει EOF, το τερματικό ελέγχου δεν μπορεί πλέον να επικοινωνήσει με τη διαδικασία γονέα ή τη διαδικασία παιδί. Εκτός εάν η διαδικασία παιδί θα τερματιστεί χωρίς καμία είσοδο, το `spawn' θα συνεχίσει να εκτελείται επ” άπειρον. Εάν η `master_read' σηματοδοτήσει EOF, προκύπτει η ίδια συμπεριφορά (τουλάχιστον στο linux).

Επιστρέφει την τιμή κατάστασης εξόδου από @ref{1153,,os.waitpid()} στη διαδικασία παιδί.

Η συνάρτηση @ref{cea,,os.waitstatus_to_exitcode()} μπορεί να χρησιμοποιηθεί για να μετατρέψει την κατάσταση εξόδου σε κωδικό εξόδου.

Κάνει raise ένα @ref{1e65,,auditing event} @code{pty.spawn} με όρισμα @code{argv}.


Άλλαξε στην έκδοση 3.4: Η συνάρτηση @ref{132c,,spawn()} τώρα επιστρέφει την τιμή κατάστασης από @ref{1153,,os.waitpid()} στη διαδικασία παιδί.

@end deffn

@menu
* Παράδειγμα: Παράδειγμα<2>. 

@end menu

@node Παράδειγμα<2>,,,pty — Βοηθητικά προγράμματα ψευδοτερματικού
@anchor{library/pty example}@anchor{50d6}
@subsubsection Παράδειγμα


Το ακόλουθο πρόγραμμα λειτουργεί όπως η εντολή Unix @code{script(1)@footnote{https://manpages.debian.org/script(1)}}, χρησιμοποιώντας ένα ψευδοτερματικό για να καταγράψει όλη την είσοδο και έξοδο μιας συνεδρίας τερματικού σε ένα «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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node fcntl — The fcntl and ioctl system calls,resource — Resource usage information,pty — Βοηθητικά προγράμματα ψευδοτερματικού,Unix-specific services
@anchor{library/fcntl doc}@anchor{50d7}@anchor{library/fcntl fcntl-the-fcntl-and-ioctl-system-calls}@anchor{50d8}@anchor{library/fcntl module-fcntl}@anchor{5c}@anchor{library/fcntl translation-repo}@anchor{50d9}
@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{232d,,Διαθεσιμότητα}: 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{70a,,io.IOBase} object, such as @code{sys.stdin}
itself, which provides a @ref{19b2,,fileno()} that returns a genuine file
descriptor.


Άλλαξε στην έκδοση 3.3: Operations in this module used to raise an @ref{13fb,,IOError} where they now
raise an @ref{53c,,OSError}.



Άλλαξε στην έκδοση 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{dcd,,os.memfd_create()} file
descriptors.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.12: On Linux >= 4.5, the @code{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».



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.14: On Linux >= 6.1, the @code{fcntl} module exposes the @code{F_DUPFD_QUERY}
to query a file descriptor pointing to the same file.


The module defines the following functions:

@geindex fcntl() (στη μονάδα fcntl)
@anchor{library/fcntl fcntl fcntl}@anchor{1962}
@deffn {Συνάρτηση} fcntl.fcntl (fd, cmd, arg=0, /)

Perform the operation `cmd' on file descriptor `fd' (file objects providing
a @ref{19b2,,fileno()} method are accepted as well).  The values used
for `cmd' are operating system dependent, and are available as constants
in the @code{fcntl} module, using the same names as used in the relevant C
header files. The argument `arg' can either be an integer value, a
@ref{436,,bytes-like object}, or a string.
The type and size of `arg' must match the type and size of
the argument of the operation as specified in the relevant C documentation.

When `arg' is an integer, the function returns the integer
return value of the C @code{fcntl()} call.

When the argument is bytes-like object, it represents a binary structure,
for example, created by @ref{161b,,struct.pack()}.
A string value is encoded to binary using the UTF-8 encoding.
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{1c7,,bytes} object.
The length of the returned object will be the same as the length of the
`arg' argument.

If the @code{fcntl()} call fails, an @ref{53c,,OSError} is raised.

@cartouche
@quotation Σημείωση 
If the type or size of `arg' does not match the type or size
of the operation’s argument (for example, if an integer is
passed when a pointer is expected, or the information returned in
the buffer by the operating system is larger than the size of `arg'),
this is most likely to result in a segmentation violation or
a more subtle data corruption.
@end quotation
@end cartouche

Raises an @ref{1e65,,auditing event} @code{fcntl.fcntl} with arguments @code{fd}, @code{cmd}, @code{arg}.


Άλλαξε στην έκδοση 3.14: Add support of arbitrary @ref{436,,bytes-like objects},
not only @ref{1c7,,bytes}.



Άλλαξε στην έκδοση 3.15: The size of bytes-like objects is no longer limited to 1024 bytes.

@end deffn

@geindex ioctl() (στη μονάδα fcntl)
@anchor{library/fcntl fcntl ioctl}@anchor{181d}
@deffn {Συνάρτηση} fcntl.ioctl (fd, request, arg=0, mutate_flag=True, /)

This function is identical to the @ref{1962,,fcntl()} function, except
that the argument handling is even more complicated.

The `request' parameter is limited to values that can fit in 32-bits
or 64-bits, depending on the platform.
Additional constants of interest for use as the `request' argument can be
found in the @ref{ea,,termios} module, under the same names as used in
the relevant C header files.

The parameter `arg' can be an integer, a @ref{436,,bytes-like object},
or a string.
The type and size of `arg' must match the type and size of
the argument of the operation as specified in the relevant C documentation.

If `arg' does not support the read-write buffer interface or
the `mutate_flag' is false, behavior is as for the @ref{1962,,fcntl()}
function.

If `arg' supports the read-write buffer interface (like @ref{1c6,,bytearray})
and `mutate_flag' is true (the default), then the buffer is (in effect) passed
to the underlying @code{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 @code{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 @code{ioctl()} and copied back
into the supplied buffer.

If the @code{ioctl()} call fails, an @ref{53c,,OSError} exception is raised.

@cartouche
@quotation Σημείωση 
If the type or size of `arg' does not match the type or size
of the operation’s argument (for example, if an integer is
passed when a pointer is expected, or the information returned in
the buffer by the operating system is larger than the size of `arg'),
this is most likely to result in a segmentation violation or
a more subtle data corruption.
@end quotation
@end cartouche

An example:

@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{1e65,,auditing event} @code{fcntl.ioctl} with arguments @code{fd}, @code{request}, @code{arg}.


Άλλαξε στην έκδοση 3.14: The GIL is always released during a system call.
System calls failing with EINTR are automatically retried.



Άλλαξε στην έκδοση 3.15: The size of not mutated bytes-like objects is no longer
limited to 1024 bytes.

@end deffn

@geindex flock() (στη μονάδα fcntl)
@anchor{library/fcntl fcntl flock}@anchor{49b3}
@deffn {Συνάρτηση} fcntl.flock (fd, operation, /)

Perform the lock operation `operation' on file descriptor `fd' (file objects providing
a @ref{19b2,,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{53c,,OSError} exception is raised.

Raises an @ref{1e65,,auditing event} @code{fcntl.flock} with arguments @code{fd}, @code{operation}.
@end deffn

@geindex lockf() (στη μονάδα fcntl)
@anchor{library/fcntl fcntl lockf}@anchor{178f}
@deffn {Συνάρτηση} fcntl.lockf (fd, cmd, len=0, start=0, whence=0, /)

This is essentially a wrapper around the @ref{1962,,fcntl()} locking calls.
`fd' is the file descriptor (file objects providing a @ref{19b2,,fileno()}
method are accepted as well) of the file to lock or unlock, and `cmd'
is one of the following values:

@geindex LOCK_UN (στη μονάδα fcntl)
@anchor{library/fcntl fcntl LOCK_UN}@anchor{50da}
@deffn {Δεδομένα} fcntl.LOCK_UN

Release an existing lock.
@end deffn

@geindex LOCK_SH (στη μονάδα fcntl)
@anchor{library/fcntl fcntl LOCK_SH}@anchor{50db}
@deffn {Δεδομένα} fcntl.LOCK_SH

Acquire a shared lock.
@end deffn

@geindex LOCK_EX (στη μονάδα fcntl)
@anchor{library/fcntl fcntl LOCK_EX}@anchor{50dc}
@deffn {Δεδομένα} fcntl.LOCK_EX

Acquire an exclusive lock.
@end deffn

@geindex LOCK_NB (στη μονάδα fcntl)
@anchor{library/fcntl fcntl LOCK_NB}@anchor{50dd}
@deffn {Δεδομένα} 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{53c,,OSError} will be raised and the exception will have an `errno'
attribute set to @ref{2908,,EACCES} or @ref{28f9,,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{1631,,io.IOBase.seek()}, specifically:


@itemize *

@item 
@code{0} – relative to the start of the file (@ref{1632,,os.SEEK_SET})

@item 
@code{1} – relative to the current buffer position (@ref{1633,,os.SEEK_CUR})

@item 
@code{2} – relative to the end of the file (@ref{1634,,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{1e65,,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{1c7,,bytes} object.  The
structure lay-out for the `lockdata' variable is system dependent — therefore
using the @ref{49b3,,flock()} call may be better.


@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{a5,,os}

If the locking flags @ref{17d1,,O_SHLOCK} and @ref{17d2,,O_EXLOCK} are
present in the @ref{a5,,os} module (on BSD only), the @ref{114b,,os.open()}
function provides an alternative to the @ref{178f,,lockf()} and @ref{49b3,,flock()}
functions.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node resource — Resource usage information,syslog — Unix syslog library routines,fcntl — The fcntl and ioctl system calls,Unix-specific services
@anchor{library/resource doc}@anchor{50de}@anchor{library/resource module-resource}@anchor{c4}@anchor{library/resource resource-resource-usage-information}@anchor{50df}@anchor{library/resource translation-repo}@anchor{50e0}
@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{232d,,Διαθεσιμότητα}: 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{53c,,OSError} is raised on syscall failure.

@geindex error
@anchor{library/resource resource error}@anchor{50e1}
@deffn {Εξαίρεση} resource.error

A deprecated alias of @ref{53c,,OSError}.


Άλλαξε στην έκδοση 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{53c,,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{50e2}
@subsubsection Resource Limits


Resources usage can be limited using the @ref{3e7,,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 (στη μονάδα resource)
@anchor{library/resource resource RLIM_INFINITY}@anchor{3e6}
@deffn {Δεδομένα} resource.RLIM_INFINITY

Constant used to represent the limit for an unlimited resource.


Άλλαξε στην έκδοση 3.15: It is now always positive.
Previously, it could be negative, such as -1 or -3.

@end deffn

@geindex RLIM_SAVED_CUR (στη μονάδα resource)
@anchor{library/resource resource RLIM_SAVED_CUR}@anchor{252}
@deffn {Δεδομένα} resource.RLIM_SAVED_CUR
@end deffn

@geindex RLIM_SAVED_MAX (στη μονάδα resource)
@anchor{library/resource resource RLIM_SAVED_MAX}@anchor{253}
@deffn {Δεδομένα} resource.RLIM_SAVED_MAX

Constants used to represent the soft and hard limit values if they
cannot be represented in the @code{rlim_t} value in C.
Can be equal to @ref{3e6,,RLIM_INFINITY}.


Added in version 3.15.

@end deffn

@geindex getrlimit() (στη μονάδα resource)
@anchor{library/resource resource getrlimit}@anchor{1a05}
@deffn {Συνάρτηση} resource.getrlimit (resource)

Returns a tuple @code{(soft, hard)} with the current soft and hard limits of
`resource'. Raises @ref{277,,ValueError} if an invalid resource is specified, or
@ref{50e1,,error} if the underlying system call fails unexpectedly.
@end deffn

@geindex setrlimit() (στη μονάδα resource)
@anchor{library/resource resource setrlimit}@anchor{3e7}
@deffn {Συνάρτηση} 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{3e6,,RLIM_INFINITY} can be used to request a limit that is
unlimited.

Raises @ref{277,,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{3e6,,RLIM_INFINITY} when the hard or
system limit for that resource is not unlimited will result in a
@code{ValueError}.  A process with the effective UID of super-user can
request any valid limit value, including unlimited, but @code{ValueError}
will still be raised if the requested limit exceeds the system imposed
limit.

@code{setrlimit} may also raise @ref{50e1,,error} if the underlying system call
fails.

VxWorks only supports setting @ref{50e3,,RLIMIT_NOFILE}.

Raises an @ref{1e65,,auditing event} @code{resource.setrlimit} with arguments @code{resource}, @code{limits}.
@end deffn

@geindex prlimit() (στη μονάδα resource)
@anchor{library/resource resource prlimit}@anchor{3e8}
@deffn {Συνάρτηση} resource.prlimit (pid, resource[, limits])

Combines @ref{3e7,,setrlimit()} and @ref{1a05,,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 @code{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{1403,,ProcessLookupError} when `pid' can’t be found and
@ref{10f9,,PermissionError} when the user doesn’t have @code{CAP_SYS_RESOURCE} for
the process.

Raises an @ref{1e65,,auditing event} @code{resource.prlimit} with arguments @code{pid}, @code{resource}, @code{limits}.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.36 with glibc >= 2.13.


Added in version 3.4.

@end deffn

These symbols define resources whose consumption can be controlled using the
@ref{3e7,,setrlimit()} and @ref{1a05,,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 (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_CORE}@anchor{4954}
@deffn {Δεδομένα} 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 (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_CPU}@anchor{50e4}
@deffn {Δεδομένα} resource.RLIMIT_CPU

The maximum amount of processor time (in seconds) that a process can use. If
this limit is exceeded, a @ref{3cb8,,SIGXCPU} signal is sent to the process. (See
the @ref{ce,,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 (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_FSIZE}@anchor{50e5}
@deffn {Δεδομένα} resource.RLIMIT_FSIZE

The maximum size of a file which the process may create.
@end deffn

@geindex RLIMIT_DATA (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_DATA}@anchor{50e6}
@deffn {Δεδομένα} resource.RLIMIT_DATA

The maximum size (in bytes) of the process’s heap.
@end deffn

@geindex RLIMIT_STACK (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_STACK}@anchor{50e7}
@deffn {Δεδομένα} 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 (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_RSS}@anchor{50e8}
@deffn {Δεδομένα} resource.RLIMIT_RSS

The maximum resident set size that should be made available to the process.
@end deffn

@geindex RLIMIT_NPROC (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_NPROC}@anchor{50e9}
@deffn {Δεδομένα} resource.RLIMIT_NPROC

The maximum number of processes the current process may create.
@end deffn

@geindex RLIMIT_NOFILE (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_NOFILE}@anchor{50e3}
@deffn {Δεδομένα} resource.RLIMIT_NOFILE

The maximum number of open file descriptors for the current process.
@end deffn

@geindex RLIMIT_OFILE (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_OFILE}@anchor{50ea}
@deffn {Δεδομένα} resource.RLIMIT_OFILE

The BSD name for @ref{50e3,,RLIMIT_NOFILE}.
@end deffn

@geindex RLIMIT_MEMLOCK (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_MEMLOCK}@anchor{50eb}
@deffn {Δεδομένα} resource.RLIMIT_MEMLOCK

The maximum address space which may be locked in memory.
@end deffn

@geindex RLIMIT_VMEM (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_VMEM}@anchor{50ec}
@deffn {Δεδομένα} resource.RLIMIT_VMEM

The largest area of mapped memory which the process may occupy.
Usually an alias of @ref{50ed,,RLIMIT_AS}.

@ref{232d,,Διαθεσιμότητα}: Solaris, FreeBSD, NetBSD.
@end deffn

@geindex RLIMIT_AS (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_AS}@anchor{50ed}
@deffn {Δεδομένα} resource.RLIMIT_AS

The maximum area (in bytes) of address space which may be taken by the process.
@end deffn

@geindex RLIMIT_MSGQUEUE (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_MSGQUEUE}@anchor{1334}
@deffn {Δεδομένα} resource.RLIMIT_MSGQUEUE

The number of bytes that can be allocated for POSIX message queues.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.8.


Added in version 3.4.

@end deffn

@geindex RLIMIT_NICE (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_NICE}@anchor{1335}
@deffn {Δεδομένα} resource.RLIMIT_NICE

The ceiling for the process’s nice level (calculated as 20 - rlim_cur).

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.12.


Added in version 3.4.

@end deffn

@geindex RLIMIT_RTPRIO (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_RTPRIO}@anchor{1336}
@deffn {Δεδομένα} resource.RLIMIT_RTPRIO

The ceiling of the real-time priority.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.12.


Added in version 3.4.

@end deffn

@geindex RLIMIT_RTTIME (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_RTTIME}@anchor{1337}
@deffn {Δεδομένα} 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{232d,,Διαθεσιμότητα}: Linux >= 2.6.25.


Added in version 3.4.

@end deffn

@geindex RLIMIT_SIGPENDING (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_SIGPENDING}@anchor{1338}
@deffn {Δεδομένα} resource.RLIMIT_SIGPENDING

The number of signals which the process may queue.

@ref{232d,,Διαθεσιμότητα}: Linux >= 2.6.8.


Added in version 3.4.

@end deffn

@geindex RLIMIT_SBSIZE (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_SBSIZE}@anchor{1339}
@deffn {Δεδομένα} 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{232d,,Διαθεσιμότητα}: FreeBSD, NetBSD.


Added in version 3.4.

@end deffn

@geindex RLIMIT_SWAP (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_SWAP}@anchor{133a}
@deffn {Δεδομένα} 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{232d,,Διαθεσιμότητα}: FreeBSD >= 8.


Added in version 3.4.

@end deffn

@geindex RLIMIT_NPTS (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_NPTS}@anchor{133b}
@deffn {Δεδομένα} resource.RLIMIT_NPTS

The maximum number of pseudo-terminals created by this user id.

@ref{232d,,Διαθεσιμότητα}: FreeBSD >= 8.


Added in version 3.4.

@end deffn

@geindex RLIMIT_KQUEUES (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_KQUEUES}@anchor{1e9c}
@deffn {Δεδομένα} resource.RLIMIT_KQUEUES

The maximum number of kqueues this user id is allowed to create.

@ref{232d,,Διαθεσιμότητα}: FreeBSD >= 11.


Added in version 3.10.

@end deffn

@geindex RLIMIT_NTHR (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_NTHR}@anchor{24f}
@deffn {Δεδομένα} resource.RLIMIT_NTHR

The maximum number of threads for this user id, not counting the main
and kernel threads.

@ref{232d,,Διαθεσιμότητα}: NetBSD >= 7.0.


Added in version 3.15.

@end deffn

@geindex RLIMIT_PIPEBUF (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_PIPEBUF}@anchor{1a03}
@deffn {Δεδομένα} resource.RLIMIT_PIPEBUF

The maximum total size of in-kernel buffers for bi-directional pipes/fifos
that this user id is allowed to consume.

@ref{232d,,Διαθεσιμότητα}: FreeBSD >= 14.2.


Added in version 3.15.

@end deffn

@geindex RLIMIT_THREADS (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_THREADS}@anchor{251}
@deffn {Δεδομένα} resource.RLIMIT_THREADS

The maximum number of threads each process can create.

@ref{232d,,Διαθεσιμότητα}: AIX.


Added in version 3.15.

@end deffn

@geindex RLIMIT_UMTXP (στη μονάδα resource)
@anchor{library/resource resource RLIMIT_UMTXP}@anchor{250}
@deffn {Δεδομένα} resource.RLIMIT_UMTXP

The limit of the number of process-shared Posix thread library objects
allocated by user id.

@ref{232d,,Διαθεσιμότητα}: FreeBSD >= 11.


Added in version 3.15.

@end deffn

@node Resource Usage,,Resource Limits,resource — Resource usage information
@anchor{library/resource resource-usage}@anchor{50ee}
@subsubsection Resource Usage


These functions are used to retrieve resource usage information:

@geindex getrusage() (στη μονάδα resource)
@anchor{library/resource resource getrusage}@anchor{17d3}
@deffn {Συνάρτηση} 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.

A simple example:

@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 in user mode or number of times
the process was swapped out of main memory. Some values are dependent on the
clock tick interval, 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} {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Field

@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{277,,ValueError} if an invalid `who' parameter is
specified. It may also raise @ref{50e1,,error} exception in unusual circumstances.
@end deffn

@geindex getpagesize() (στη μονάδα resource)
@anchor{library/resource resource getpagesize}@anchor{50ef}
@deffn {Συνάρτηση} 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{17d3,,getrusage()}
function to specify which processes information should be provided for.

@geindex RUSAGE_SELF (στη μονάδα resource)
@anchor{library/resource resource RUSAGE_SELF}@anchor{50f0}
@deffn {Δεδομένα} resource.RUSAGE_SELF

Pass to @ref{17d3,,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 (στη μονάδα resource)
@anchor{library/resource resource RUSAGE_CHILDREN}@anchor{50f1}
@deffn {Δεδομένα} resource.RUSAGE_CHILDREN

Pass to @ref{17d3,,getrusage()} to request resources consumed by child processes
of the calling process which have been terminated and waited for.
@end deffn

@geindex RUSAGE_BOTH (στη μονάδα resource)
@anchor{library/resource resource RUSAGE_BOTH}@anchor{50f2}
@deffn {Δεδομένα} resource.RUSAGE_BOTH

Pass to @ref{17d3,,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 (στη μονάδα resource)
@anchor{library/resource resource RUSAGE_THREAD}@anchor{50f3}
@deffn {Δεδομένα} resource.RUSAGE_THREAD

Pass to @ref{17d3,,getrusage()} to request resources consumed by the current
thread.  May not be available on all systems.


Added in version 3.2.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node syslog — Unix syslog library routines,,resource — Resource usage information,Unix-specific services
@anchor{library/syslog doc}@anchor{50f4}@anchor{library/syslog module-syslog}@anchor{e5}@anchor{library/syslog syslog-unix-syslog-library-routines}@anchor{50f5}@anchor{library/syslog translation-repo}@anchor{50f6}
@subsection @code{syslog} — Unix syslog library routines


@geindex module; syslog


__________________________________________________________________


This module provides an interface to the Unix @code{syslog} library routines.
Refer to the Unix manual pages for a detailed description of the @code{syslog}
facility.

@ref{232d,,Διαθεσιμότητα}: 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{8c,,logging.handlers} module as @ref{a4c,,SysLogHandler}.

The module defines the following functions:

@geindex syslog() (στη μονάδα syslog)
@anchor{library/syslog syslog syslog}@anchor{94d}
@deffn {Συνάρτηση} syslog.syslog (message)

@deffnx {Συνάρτηση} syslog.syslog (priority, message)

Send the string `message' to the system logger.  A trailing newline is added
if necessary.  Each message is tagged with a priority composed of a
`facility' and a `level'.  The optional `priority' argument, which defaults
to @ref{50f7,,LOG_INFO}, determines the message priority.  If the facility is
not encoded in `priority' using logical-or (@code{LOG_INFO | LOG_USER}), the
value given in the @ref{94b,,openlog()} call is used.

If @ref{94b,,openlog()} has not been called prior to the call to @code{syslog()},
@code{openlog()} will be called with no arguments.

Raises an @ref{1e65,,auditing event} @code{syslog.syslog} with arguments @code{priority}, @code{message}.


Άλλαξε στην έκδοση 3.2: In previous versions, @ref{94b,,openlog()} would not be called automatically if
it wasn’t called prior to the call to @code{syslog()}, deferring to the syslog
implementation to call @code{openlog()}.



Άλλαξε στην έκδοση 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{94b,,openlog()} must be called in the main interpreter before @code{syslog()} may be used
in a subinterpreter.  Otherwise it will raise @ref{30d,,RuntimeError}.

@end deffn

@geindex openlog() (στη μονάδα syslog)
@anchor{library/syslog syslog openlog}@anchor{94b}
@deffn {Συνάρτηση} syslog.openlog ([ident[, logoption[, facility]]])

Logging options of subsequent @ref{e5,,syslog()} calls can be set by calling
@code{openlog()}.  @code{syslog()} will call @code{openlog()} with no arguments
if the log is not currently open.

The optional `ident' keyword argument is a string which is prepended to every
message, and defaults to @code{sys.argv[0]} with leading path components
stripped.  The optional `logoption' keyword argument (default is 0) is a bit
field – see below for possible values to combine.  The optional `facility'
keyword argument (default is @ref{50f8,,LOG_USER}) sets the default facility for
messages which do not have a facility explicitly encoded.

Raises an @ref{1e65,,auditing event} @code{syslog.openlog} with arguments @code{ident}, @code{logoption}, @code{facility}.


Άλλαξε στην έκδοση 3.2: In previous versions, keyword arguments were not allowed, and `ident' was
required.



Άλλαξε στην έκδοση 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{30d,,RuntimeError} if called in a subinterpreter.

@end deffn

@geindex closelog() (στη μονάδα syslog)
@anchor{library/syslog syslog closelog}@anchor{94c}
@deffn {Συνάρτηση} syslog.closelog ()

Reset the syslog module values and call the system library @code{closelog()}.

This causes the module to behave as it does when initially imported.  For
example, @ref{94b,,openlog()} will be called on the first @ref{e5,,syslog()} call (if
@code{openlog()} hasn’t already been called), and `ident' and other
@code{openlog()} parameters are reset to defaults.

Raises an @ref{1e65,,auditing event} @code{syslog.closelog} with no arguments.


Άλλαξε στην έκδοση 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{30d,,RuntimeError} if called in a subinterpreter.

@end deffn

@geindex setlogmask() (στη μονάδα syslog)
@anchor{library/syslog syslog setlogmask}@anchor{49b9}
@deffn {Συνάρτηση} syslog.setlogmask (maskpri)

Set the priority mask to `maskpri' and return the previous mask value.  Calls
to @ref{e5,,syslog()} with a priority level not set in `maskpri' are ignored.
The default is to log all priorities.  The function @code{LOG_MASK(pri)}
calculates the mask for the individual priority `pri'.  The function
@code{LOG_UPTO(pri)} calculates the mask for all priorities up to and including
`pri'.

Raises an @ref{1e65,,auditing event} @code{syslog.setlogmask} with argument @code{maskpri}.
@end deffn

The module defines the following constants:

@geindex LOG_EMERG (στη μονάδα syslog)
@geindex LOG_ALERT (στη μονάδα syslog)
@geindex LOG_CRIT (στη μονάδα syslog)
@geindex LOG_ERR (στη μονάδα syslog)
@geindex LOG_WARNING (στη μονάδα syslog)
@geindex LOG_NOTICE (στη μονάδα syslog)
@geindex LOG_INFO (στη μονάδα syslog)
@geindex LOG_DEBUG (στη μονάδα syslog)
@anchor{library/syslog syslog LOG_EMERG}@anchor{50f9}
@deffn {Δεδομένα} syslog.LOG_EMERG
@anchor{library/syslog syslog LOG_ALERT}@anchor{50fa}
@deffnx {Δεδομένα} syslog.LOG_ALERT
@anchor{library/syslog syslog LOG_CRIT}@anchor{50fb}
@deffnx {Δεδομένα} syslog.LOG_CRIT
@anchor{library/syslog syslog LOG_ERR}@anchor{50fc}
@deffnx {Δεδομένα} syslog.LOG_ERR
@anchor{library/syslog syslog LOG_WARNING}@anchor{50fd}
@deffnx {Δεδομένα} syslog.LOG_WARNING
@anchor{library/syslog syslog LOG_NOTICE}@anchor{50fe}
@deffnx {Δεδομένα} syslog.LOG_NOTICE
@anchor{library/syslog syslog LOG_INFO}@anchor{50f7}
@deffnx {Δεδομένα} syslog.LOG_INFO
@anchor{library/syslog syslog LOG_DEBUG}@anchor{50ff}
@deffnx {Δεδομένα} syslog.LOG_DEBUG

Priority levels (high to low).
@end deffn

@geindex LOG_AUTH (στη μονάδα syslog)
@geindex LOG_AUTHPRIV (στη μονάδα syslog)
@geindex LOG_CRON (στη μονάδα syslog)
@geindex LOG_DAEMON (στη μονάδα syslog)
@geindex LOG_FTP (στη μονάδα syslog)
@geindex LOG_INSTALL (στη μονάδα syslog)
@geindex LOG_KERN (στη μονάδα syslog)
@geindex LOG_LAUNCHD (στη μονάδα syslog)
@geindex LOG_LPR (στη μονάδα syslog)
@geindex LOG_MAIL (στη μονάδα syslog)
@geindex LOG_NETINFO (στη μονάδα syslog)
@geindex LOG_NEWS (στη μονάδα syslog)
@geindex LOG_RAS (στη μονάδα syslog)
@geindex LOG_REMOTEAUTH (στη μονάδα syslog)
@geindex LOG_SYSLOG (στη μονάδα syslog)
@geindex LOG_USER (στη μονάδα syslog)
@geindex LOG_UUCP (στη μονάδα syslog)
@geindex LOG_LOCAL0 (στη μονάδα syslog)
@geindex LOG_LOCAL1 (στη μονάδα syslog)
@geindex LOG_LOCAL2 (στη μονάδα syslog)
@geindex LOG_LOCAL3 (στη μονάδα syslog)
@geindex LOG_LOCAL4 (στη μονάδα syslog)
@geindex LOG_LOCAL5 (στη μονάδα syslog)
@geindex LOG_LOCAL6 (στη μονάδα syslog)
@geindex LOG_LOCAL7 (στη μονάδα syslog)
@anchor{library/syslog syslog LOG_AUTH}@anchor{5100}
@deffn {Δεδομένα} syslog.LOG_AUTH
@anchor{library/syslog syslog LOG_AUTHPRIV}@anchor{5101}
@deffnx {Δεδομένα} syslog.LOG_AUTHPRIV
@anchor{library/syslog syslog LOG_CRON}@anchor{5102}
@deffnx {Δεδομένα} syslog.LOG_CRON
@anchor{library/syslog syslog LOG_DAEMON}@anchor{5103}
@deffnx {Δεδομένα} syslog.LOG_DAEMON
@anchor{library/syslog syslog LOG_FTP}@anchor{5104}
@deffnx {Δεδομένα} syslog.LOG_FTP
@anchor{library/syslog syslog LOG_INSTALL}@anchor{5105}
@deffnx {Δεδομένα} syslog.LOG_INSTALL
@anchor{library/syslog syslog LOG_KERN}@anchor{5106}
@deffnx {Δεδομένα} syslog.LOG_KERN
@anchor{library/syslog syslog LOG_LAUNCHD}@anchor{5107}
@deffnx {Δεδομένα} syslog.LOG_LAUNCHD
@anchor{library/syslog syslog LOG_LPR}@anchor{5108}
@deffnx {Δεδομένα} syslog.LOG_LPR
@anchor{library/syslog syslog LOG_MAIL}@anchor{5109}
@deffnx {Δεδομένα} syslog.LOG_MAIL
@anchor{library/syslog syslog LOG_NETINFO}@anchor{510a}
@deffnx {Δεδομένα} syslog.LOG_NETINFO
@anchor{library/syslog syslog LOG_NEWS}@anchor{510b}
@deffnx {Δεδομένα} syslog.LOG_NEWS
@anchor{library/syslog syslog LOG_RAS}@anchor{510c}
@deffnx {Δεδομένα} syslog.LOG_RAS
@anchor{library/syslog syslog LOG_REMOTEAUTH}@anchor{510d}
@deffnx {Δεδομένα} syslog.LOG_REMOTEAUTH
@anchor{library/syslog syslog LOG_SYSLOG}@anchor{510e}
@deffnx {Δεδομένα} syslog.LOG_SYSLOG
@anchor{library/syslog syslog LOG_USER}@anchor{50f8}
@deffnx {Δεδομένα} syslog.LOG_USER
@anchor{library/syslog syslog LOG_UUCP}@anchor{510f}
@deffnx {Δεδομένα} syslog.LOG_UUCP
@anchor{library/syslog syslog LOG_LOCAL0}@anchor{5110}
@deffnx {Δεδομένα} syslog.LOG_LOCAL0
@anchor{library/syslog syslog LOG_LOCAL1}@anchor{5111}
@deffnx {Δεδομένα} syslog.LOG_LOCAL1
@anchor{library/syslog syslog LOG_LOCAL2}@anchor{5112}
@deffnx {Δεδομένα} syslog.LOG_LOCAL2
@anchor{library/syslog syslog LOG_LOCAL3}@anchor{5113}
@deffnx {Δεδομένα} syslog.LOG_LOCAL3
@anchor{library/syslog syslog LOG_LOCAL4}@anchor{5114}
@deffnx {Δεδομένα} syslog.LOG_LOCAL4
@anchor{library/syslog syslog LOG_LOCAL5}@anchor{5115}
@deffnx {Δεδομένα} syslog.LOG_LOCAL5
@anchor{library/syslog syslog LOG_LOCAL6}@anchor{5116}
@deffnx {Δεδομένα} syslog.LOG_LOCAL6
@anchor{library/syslog syslog LOG_LOCAL7}@anchor{5117}
@deffnx {Δεδομένα} syslog.LOG_LOCAL7

Facilities, depending on availability in @code{<syslog.h>} for @ref{5101,,LOG_AUTHPRIV},
@ref{5104,,LOG_FTP}, @ref{510a,,LOG_NETINFO}, @ref{510d,,LOG_REMOTEAUTH},
@ref{5105,,LOG_INSTALL} and @ref{510c,,LOG_RAS}.


Άλλαξε στην έκδοση 3.13: Added @ref{5104,,LOG_FTP}, @ref{510a,,LOG_NETINFO}, @ref{510d,,LOG_REMOTEAUTH},
@ref{5105,,LOG_INSTALL}, @ref{510c,,LOG_RAS}, and @ref{5107,,LOG_LAUNCHD}.

@end deffn

@geindex LOG_PID (στη μονάδα syslog)
@geindex LOG_CONS (στη μονάδα syslog)
@geindex LOG_NDELAY (στη μονάδα syslog)
@geindex LOG_ODELAY (στη μονάδα syslog)
@geindex LOG_NOWAIT (στη μονάδα syslog)
@geindex LOG_PERROR (στη μονάδα syslog)
@anchor{library/syslog syslog LOG_PID}@anchor{5118}
@deffn {Δεδομένα} syslog.LOG_PID
@anchor{library/syslog syslog LOG_CONS}@anchor{5119}
@deffnx {Δεδομένα} syslog.LOG_CONS
@anchor{library/syslog syslog LOG_NDELAY}@anchor{511a}
@deffnx {Δεδομένα} syslog.LOG_NDELAY
@anchor{library/syslog syslog LOG_ODELAY}@anchor{511b}
@deffnx {Δεδομένα} syslog.LOG_ODELAY
@anchor{library/syslog syslog LOG_NOWAIT}@anchor{511c}
@deffnx {Δεδομένα} syslog.LOG_NOWAIT
@anchor{library/syslog syslog LOG_PERROR}@anchor{511d}
@deffnx {Δεδομένα} syslog.LOG_PERROR

Log options, depending on availability in @code{<syslog.h>} for
@ref{511b,,LOG_ODELAY}, @ref{511c,,LOG_NOWAIT} and @ref{511d,,LOG_PERROR}.
@end deffn

@menu
* Examples: Examples<31>. 

@end menu

@node Examples<31>,,,syslog — Unix syslog library routines
@anchor{library/syslog examples}@anchor{511e}
@subsubsection Examples


@menu
* Simple example:: 

@end menu

@node Simple example,,,Examples<31>
@anchor{library/syslog simple-example}@anchor{511f}
@subsubsection Simple example


A simple set of examples:

@example
import syslog

syslog.syslog('Processing started')
if error:
    syslog.syslog(syslog.LOG_ERR, 'Processing started')
@end example

An example of setting some log options, these would include the process ID in
logged messages, and write the messages to the destination facility used for
mail logging:

@example
syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL)
syslog.syslog('E-mail processing initiated...')
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Command-line interface Διεπαφή Γραμμής Εντολών CLI για modules,Superseded modules,Unix-specific services,The Python Standard Library
@anchor{library/cmdline doc}@anchor{5120}@anchor{library/cmdline library-cmdline}@anchor{5121}@anchor{library/cmdline modules-command-line-interface-cli}@anchor{5122}@anchor{library/cmdline translation-repo}@anchor{5123}
@section Command-line interface (Διεπαφή Γραμμής Εντολών) (CLI) για modules


Τα παρακάτω modules έχουν command-line interface.


@itemize *

@item 
@ref{1e2,,ast}

@item 
@ref{3a07,,asyncio}

@item 
@ref{f,,base64}

@item 
@ref{201,,calendar}

@item 
@ref{1b,,code}

@item 
@ref{4f88,,compileall}

@item 
@code{cProfile}: see @ref{4a63,,profiling.tracing}

@item 
@ref{4f9f,,dis}

@item 
@ref{47ae,,doctest}

@item 
@code{encodings.rot_13}

@item 
@ref{4b88,,ensurepip}

@item 
@ref{5d,,filecmp}

@item 
@ref{5e,,fileinput}

@item 
@ref{61,,ftplib}

@item 
@ref{3080,,gzip}

@item 
@ref{227,,http.server}

@item 
@ref{4655,,idlelib}

@item 
@ref{1305,,inspect}

@item 
@ref{4cb,,json}

@item 
@ref{4d3,,mimetypes}

@item 
@ref{55d,,pdb}

@item 
@ref{2f52,,pickle}

@item 
@ref{2f53,,pickletools}

@item 
@ref{349c,,platform}

@item 
@ref{b1,,poplib}

@item 
@ref{4a61,,profiling.sampling}

@item 
@ref{4a63,,profiling.tracing}

@item 
@ref{4afc,,pstats}

@item 
@ref{4f7f,,py_compile}

@item 
@ref{bc,,pyclbr}

@item 
@ref{bd,,pydoc}

@item 
@ref{bf,,quopri}

@item 
@ref{68d,,random}

@item 
@ref{c6,,runpy}

@item 
@ref{4d92,,site}

@item 
@ref{257,,sqlite3}

@item 
@ref{4f03,,symtable}

@item 
@ref{4c54,,sysconfig}

@item 
@ref{e6,,tabnanny}

@item 
@ref{1374,,tarfile}

@item 
@code{this}

@item 
@ref{4b00,,timeit}

@item 
@ref{286,,tokenize}

@item 
@ref{4b1f,,trace}

@item 
@ref{10b,,turtledemo}

@item 
@ref{4825,,unittest}

@item 
@ref{862,,uuid}

@item 
@ref{4b96,,venv}

@item 
@ref{410d,,webbrowser}

@item 
@ref{4bb0,,zipapp}

@item 
@ref{30ef,,zipfile}
@end itemize

Δείτε επίσης το @ref{1f98,,Python command-line interface}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Superseded modules,Removed Modules,Command-line interface Διεπαφή Γραμμής Εντολών CLI για modules,The Python Standard Library
@anchor{library/superseded doc}@anchor{5124}@anchor{library/superseded superseded}@anchor{5125}@anchor{library/superseded superseded-modules}@anchor{5126}@anchor{library/superseded translation-repo}@anchor{5127}
@section Superseded modules


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{64,,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{a4,,optparse} and @ref{7,,argparse}).

Alternatively, modules may appear in this chapter because they are deprecated
outright, and awaiting removal in a future release, or they are
@ref{1a7,,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 — C-style parser for command line options:: 
* profile — Pure Python profiler:: 

@end menu

@node getopt — C-style parser for command line options,profile — Pure Python profiler,,Superseded modules
@anchor{library/getopt doc}@anchor{5128}@anchor{library/getopt getopt-c-style-parser-for-command-line-options}@anchor{5129}@anchor{library/getopt module-getopt}@anchor{64}
@subsection @code{getopt} — C-style parser for command line options


@geindex module; getopt

`Source code:' Lib/getopt.py@footnote{https://github.com/python/cpython/tree/main/Lib/getopt.py}

@cartouche
@quotation Σημείωση 
This module is considered feature complete. A more declarative and
extensible alternative to this API is provided in the @ref{a4,,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{7,,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{7,,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{a4,,optparse} module. See @ref{35ca,,Choosing an argument parsing library} for
additional details.

This module provides two functions and an
exception:

@geindex getopt() (στη μονάδα getopt)
@anchor{library/getopt getopt getopt}@anchor{185d}
@deffn {Συνάρτηση} 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{':'}) and options that accept an optional argument followed by
two colons (@code{'::'}); i.e., the same format that Unix @code{getopt()} uses.

@cartouche
@quotation Σημείωση 
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', if specified, must be a list of strings with the names of the
long options which should be supported.  The leading @code{'--'} characters
should not be included in the option name.  Long options which require an
argument should be followed by an equal sign (@code{'='}).
Long options which accept an optional argument should be followed by
an equal sign and question mark (@code{'=?'}).
To accept only long options, `shortopts' should be an
empty string.  Long options on the command line can be recognized so long as
they provide a prefix of the option name that matches exactly one of the
accepted options.  For example, if `longopts' is @code{['foo', 'frob']}, the
option @code{--fo} will match as @code{--foo}, but @code{--f} will
not match uniquely, so @ref{1b0a,,GetoptError} will be raised.

The return value consists of two elements: the first is a list of @code{(option,
value)} pairs; the second is the list of program arguments left after the
option list was stripped (this is a trailing slice of `args').  Each
option-and-value pair returned has the option as its first element, prefixed
with a hyphen for short options (e.g., @code{'-x'}) or two hyphens for long
options (e.g., @code{'--long-option'}), and the option argument as its
second element, or an empty string if the option has no argument.  The
options occur in the list in the same order in which they were found, thus
allowing multiple occurrences.  Long and short options may be mixed.


Άλλαξε στην έκδοση 3.14: Optional arguments are supported.

@end deffn

@geindex gnu_getopt() (στη μονάδα getopt)
@anchor{library/getopt getopt gnu_getopt}@anchor{185c}
@deffn {Συνάρτηση} getopt.gnu_getopt (args, shortopts, longopts=[])

This function works like @ref{64,,getopt()}, except that GNU style scanning mode is
used by default. This means that option and non-option arguments may be
intermixed. The @code{getopt()} function stops processing options as soon as a
non-option argument is encountered.

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.

If the first character of the option string is @code{'-'}, non-option arguments
that are followed by options are added to the list of option-and-value pairs
as a pair that has @code{None} as its first element and the list of non-option
arguments as its second element.
The second element of the @code{gnu_getopt()} result is a list of
program arguments after the last option.


Άλλαξε στην έκδοση 3.14: Support for returning intermixed options and non-option arguments in order.

@end deffn

@geindex GetoptError
@anchor{library/getopt getopt GetoptError}@anchor{1b0a}
@deffn {Εξαίρεση} 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{512a}
@deffn {Εξαίρεση} getopt.error

Alias for @ref{1b0a,,GetoptError}; for backward compatibility.
@end deffn

An example using only Unix style options:

@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

Using long option names is equally easy:

@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

Optional arguments should be specified explicitly:

@example
>>> s = '-Con -C --color=off --color a1 a2'
>>> args = s.split()
>>> args
['-Con', '-C', '--color=off', '--color', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'C::', ['color=?'])
>>> optlist
[('-C', 'on'), ('-C', '@w{'}), ('--color', 'off'), ('--color', '@w{'})]
>>> args
['a1', 'a2']
@end example

The order of options and non-option arguments can be preserved:

@example
>>> s = 'a1 -x a2 a3 a4 --long a5 a6'
>>> args = s.split()
>>> args
['a1', '-x', 'a2', 'a3', 'a4', '--long', 'a5', 'a6']
>>> optlist, args = getopt.gnu_getopt(args, '-x:', ['long='])
>>> optlist
[(None, ['a1']), ('-x', 'a2'), (None, ['a3', 'a4']), ('--long', 'a5')]
>>> args
['a6']
@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{a4,,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{7,,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{35ca,,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 Δείτε επίσης



@table @asis

@item Module @ref{a4,,optparse}

Declarative command line option parsing.

@item Module @ref{7,,argparse}

More opinionated command line option and argument parsing library.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node profile — Pure Python profiler,,getopt — C-style parser for command line options,Superseded modules
@anchor{library/profile doc}@anchor{512b}@anchor{library/profile module-profile}@anchor{b4}@anchor{library/profile profile}@anchor{4c0a}@anchor{library/profile profile-pure-python-profiler}@anchor{512c}@anchor{library/profile translation-repo}@anchor{512d}
@subsection @code{profile} — Pure Python profiler


@geindex module; profile

`Source code:' Lib/profile.py@footnote{https://github.com/python/cpython/tree/main/Lib/profile.py}


__________________________________________________________________



Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.17.


The @code{profile} module is deprecated and will be removed in Python 3.17.
Use @ref{b7,,profiling.tracing} instead.

The @code{profile} module provides a pure Python implementation of a
deterministic profiler. While useful for understanding profiler internals or
extending profiler behavior through subclassing, its pure Python implementation
introduces significant overhead compared to the C-based @ref{b7,,profiling.tracing}
module.

For most profiling tasks, use:


@itemize -

@item 
@ref{b6,,profiling.sampling} for production debugging with zero overhead

@item 
@ref{b7,,profiling.tracing} for development and testing
@end itemize

@menu
* Migration:: 
* profile and profiling.tracing module reference: profile and profiling tracing module reference. 
* Differences from profiling.tracing: Differences from profiling tracing. 
* What is deterministic profiling?: What is deterministic profiling?<2>. 
* Limitations: Limitations<2>. 
* Calibration:: 
* Using a custom timer: Using a custom timer<2>. 

@end menu

@node Migration,profile and profiling tracing module reference,,profile — Pure Python profiler
@anchor{library/profile migration}@anchor{512e}
@subsubsection Migration


Migrating from @code{profile} to @ref{b7,,profiling.tracing} is straightforward.
The APIs are compatible:

@example
# Old (deprecated)
import profile
profile.run('my_function()')

# New (recommended)
import profiling.tracing
profiling.tracing.run('my_function()')
@end example

For most code, replacing @code{import profile} with @code{import profiling.tracing}
(and using @code{profiling.tracing} instead of @code{profile} throughout) provides
a straightforward migration path.

@cartouche
@quotation Σημείωση 
The @code{cProfile} module remains available as a backward-compatible alias
to @ref{b7,,profiling.tracing}. Existing code using @code{import cProfile} will
continue to work without modification.
@end quotation
@end cartouche

@node profile and profiling tracing module reference,Differences from profiling tracing,Migration,profile — Pure Python profiler
@anchor{library/profile profile-and-profiling-tracing-module-reference}@anchor{512f}
@subsubsection @code{profile} and @code{profiling.tracing} module reference


Both the @code{profile} and @ref{b7,,profiling.tracing} modules provide the
following functions:

@geindex run() (στη μονάδα profile)
@anchor{library/profile profile run}@anchor{5130}
@deffn {Συνάρτηση} profile.run (command, filename=None, sort=-1)

This function takes a single argument that can be passed to the @ref{185,,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{4a6d,,Stats}
instance and prints a simple profiling report. If the sort value is specified,
it is passed to this @code{Stats} instance to control how the
results are sorted.
@end deffn

@geindex runctx() (στη μονάδα profile)
@anchor{library/profile profile runctx}@anchor{5131}
@deffn {Συνάρτηση} profile.runctx (command, globals, locals, filename=None, sort=-1)

This function is similar to @ref{5130,,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{5130,,run()} function above.
@end deffn

@geindex Profile (κλάση σε profile)
@anchor{library/profile profile Profile}@anchor{da7}
@deffn {Κλάση} 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 @ref{4a6c,,profiling.tracing.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 @code{Profile} class allows formatting profile results
without writing the profile data to a file:

@example
import profiling.tracing
import pstats
import io
from pstats import SortKey

pr = profiling.tracing.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 @code{Profile} class can also be used as a context manager (supported
only in @ref{b7,,profiling.tracing}, not in the deprecated @code{profile}
module; see @ref{2601,,Τύποι Διαχείρισης Περιεχομένου}):

@example
import profiling.tracing

with profiling.tracing.Profile() as pr:
    # ... do something ...

    pr.print_stats()
@end example


Άλλαξε στην έκδοση 3.8: Added context manager support.


@geindex enable() (μέθοδος της profile.Profile)
@anchor{library/profile profile Profile enable}@anchor{5132}
@deffn {Μέθοδος} enable ()

Start collecting profiling data. Only in @ref{b7,,profiling.tracing}.
@end deffn

@geindex disable() (μέθοδος της profile.Profile)
@anchor{library/profile profile Profile disable}@anchor{5133}
@deffn {Μέθοδος} disable ()

Stop collecting profiling data. Only in @ref{b7,,profiling.tracing}.
@end deffn

@geindex create_stats() (μέθοδος της profile.Profile)
@anchor{library/profile profile Profile create_stats}@anchor{5134}
@deffn {Μέθοδος} create_stats ()

Stop collecting profiling data and record the results internally
as the current profile.
@end deffn

@geindex print_stats() (μέθοδος της profile.Profile)
@anchor{library/profile profile Profile print_stats}@anchor{5135}
@deffn {Μέθοδος} print_stats (sort=-1)

Create a @ref{4a6d,,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{4a66,,pstats.Stats.sort_stats()}.


Added in version 3.13: @code{print_stats()} now accepts a tuple of keys.

@end deffn

@geindex dump_stats() (μέθοδος της profile.Profile)
@anchor{library/profile profile Profile dump_stats}@anchor{5136}
@deffn {Μέθοδος} dump_stats (filename)

Write the results of the current profile to `filename'.
@end deffn

@geindex run() (μέθοδος της profile.Profile)
@anchor{library/profile profile Profile run}@anchor{5137}
@deffn {Μέθοδος} run (cmd)

Profile the cmd via @ref{185,,exec()}.
@end deffn

@geindex runctx() (μέθοδος της profile.Profile)
@anchor{library/profile profile Profile runctx}@anchor{5138}
@deffn {Μέθοδος} runctx (cmd, globals, locals)

Profile the cmd via @ref{185,,exec()} with the specified global and
local environment.
@end deffn

@geindex runcall() (μέθοδος της profile.Profile)
@anchor{library/profile profile Profile runcall}@anchor{e3f}
@deffn {Μέθοδος} 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{4ff,,sys.exit()} call
during the called command/function execution) no profiling results will be
printed.

@node Differences from profiling tracing,What is deterministic profiling?<2>,profile and profiling tracing module reference,profile — Pure Python profiler
@anchor{library/profile differences-from-profiling-tracing}@anchor{5139}
@subsubsection Differences from @code{profiling.tracing}


The @code{profile} module differs from @ref{b7,,profiling.tracing} in several
ways:

`Higher overhead.' The pure Python implementation is significantly slower
than the C implementation, making it unsuitable for profiling long-running
programs or performance-sensitive code.

`Calibration support.' The @code{profile} module supports calibration to
compensate for profiling overhead. This is not needed in @ref{b7,,profiling.tracing}
because the C implementation has negligible overhead.

`Custom timers.' Both modules support custom timers, but @code{profile}
accepts timer functions that return tuples (like @ref{14c1,,os.times()}), while
@ref{b7,,profiling.tracing} requires a function returning a single number.

`Subclassing.' The pure Python implementation is easier to subclass and
extend for custom profiling behavior.

@node What is deterministic profiling?<2>,Limitations<2>,Differences from profiling tracing,profile — Pure Python profiler
@anchor{library/profile deterministic-profiling}@anchor{513a}@anchor{library/profile what-is-deterministic-profiling}@anchor{513b}
@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
provided by the @ref{b6,,profiling.sampling} module) periodically 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<2>,Calibration,What is deterministic profiling?<2>,profile — Pure Python profiler
@anchor{library/profile limitations}@anchor{513c}@anchor{library/profile profile-limitations}@anchor{513d}
@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 the deprecated @code{profile} module than
with the lower-overhead @ref{b7,,profiling.tracing}.  For this reason,
@code{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<2>,Limitations<2>,profile — Pure Python profiler
@anchor{library/profile calibration}@anchor{513e}@anchor{library/profile profile-calibration}@anchor{513f}
@subsubsection Calibration


The profiler of the @code{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{513d,,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<2>,,Calibration,profile — Pure Python profiler
@anchor{library/profile profile-timers}@anchor{5140}@anchor{library/profile using-a-custom-timer}@anchor{5141}
@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 @ref{da7,,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{da7,,profile.Profile} or @ref{4a6f,,profiling.tracing.Profile},
@code{your_time_func}’s return value will be interpreted differently:


@table @asis

@item @ref{da7,,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{14c1,,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{513f,,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{14c1,,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 @ref{4a6f,,profiling.tracing.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 @ref{da7,,Profile} instance as follows:

@example
pr = profiling.tracing.Profile(your_integer_time_func, 0.001)
@end example

As the @ref{4a6f,,profiling.tracing.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{f7,,time} that can be used to make
precise measurements of process or wall-clock time. For example, see
@ref{e49,,time.perf_counter()}.


@subsubheading Δείτε επίσης



@table @asis

@item @ref{b5,,profiling}

Overview of Python profiling tools.

@item @ref{b7,,profiling.tracing}

Recommended replacement for this module.

@item @ref{b8,,pstats}

Statistical analysis and formatting for profile data.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Removed Modules,Security Considerations<3>,Superseded modules,The Python Standard Library
@anchor{library/removed doc}@anchor{5142}@anchor{library/removed removed}@anchor{5143}@anchor{library/removed removed-modules}@anchor{5144}@anchor{library/removed translation-repo}@anchor{5145}
@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 — Read and write AIFF and AIFC files:: 
* asynchat — Διαχειριστής εντολών/απαντήσεων ασύγχρονων υποδοχών:: 
* asyncore — Asynchronous socket handler:: 
* audioop — Manipulate raw audio data:: 
* cgi — Common Gateway Interface support:: 
* cgitb — Traceback manager for CGI scripts:: 
* chunk — Read IFF chunked data:: 
* crypt — Function to check Unix passwords:: 
* distutils — Building and installing Python modules:: 
* imghdr — Determine the type of an image:: 
* imp — Access the import internals:: 
* mailcap — Mailcap file handling:: 
* msilib — Read and write Microsoft Installer files:: 
* nis — Interface to Sun’s NIS (Yellow Pages): nis — Interface to Sun’s NIS Yellow Pages. 
* nntplib — NNTP protocol client:: 
* ossaudiodev — Access to OSS-compatible audio devices:: 
* pipes — Interface to shell pipelines:: 
* smtpd — SMTP Server:: 
* sndhdr — Determine type of sound file:: 
* spwd — The shadow password database:: 
* sunau — Read and write Sun AU files:: 
* telnetlib — Telnet client:: 
* uu — Encode and decode uuencode files:: 
* xdrlib — Encode and decode XDR data:: 

@end menu

@node aifc — Read and write AIFF and AIFC files,asynchat — Διαχειριστής εντολών/απαντήσεων ασύγχρονων υποδοχών,,Removed Modules
@anchor{library/aifc doc}@anchor{5146}@anchor{library/aifc aifc-read-and-write-aiff-and-aifc-files}@anchor{5147}@anchor{library/aifc module-aifc}@anchor{5}
@subsection @code{aifc} — Read and write AIFF and AIFC files


@geindex module; aifc


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node asynchat — Διαχειριστής εντολών/απαντήσεων ασύγχρονων υποδοχών,asyncore — Asynchronous socket handler,aifc — Read and write AIFF and AIFC files,Removed Modules
@anchor{library/asynchat doc}@anchor{5148}@anchor{library/asynchat asynchat-asynchronous-socket-command-response-handler}@anchor{5149}@anchor{library/asynchat module-asynchat}@anchor{a}@anchor{library/asynchat translation-repo}@anchor{514a}
@subsection @code{asynchat} — Διαχειριστής εντολών/απαντήσεων ασύγχρονων υποδοχών


@geindex module; asynchat


Καταργήθηκε από την έκδοση 3.6, αφαιρέθηκε στην έκδοση 3.12.


Αυτό το module δεν αποτελεί πλέον μέρος της βασικής βιβλιοθήκης της Python. Αφαιρέθηκε στην έκδοση @ref{911,,Python 3.12} αφού είχε ήδη καταργηθεί στην Python 3.6. Η αφαίρεση αποφασίστηκε στο 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

Οι εφαρμογές θα πρέπει να χρησιμοποιούν το module @ref{b,,asyncio}.

Η τελευταία έκδοση της Python που περιλάμβανε το module @code{asynchat} ήταν η Python 3.11@footnote{https://docs.python.org/3.11/library/asynchat.html}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node asyncore — Asynchronous socket handler,audioop — Manipulate raw audio data,asynchat — Διαχειριστής εντολών/απαντήσεων ασύγχρονων υποδοχών,Removed Modules
@anchor{library/asyncore doc}@anchor{514b}@anchor{library/asyncore asyncore-asynchronous-socket-handler}@anchor{514c}@anchor{library/asyncore module-asyncore}@anchor{c}@anchor{library/asyncore translation-repo}@anchor{514d}
@subsection @code{asyncore} — Asynchronous socket handler


@geindex module; asyncore


Καταργήθηκε από την έκδοση 3.6, αφαιρέθηκε στην έκδοση 3.12.


This module is no longer part of the Python standard library.
It was @ref{911,,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{b,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node audioop — Manipulate raw audio data,cgi — Common Gateway Interface support,asyncore — Asynchronous socket handler,Removed Modules
@anchor{library/audioop doc}@anchor{514e}@anchor{library/audioop audioop-manipulate-raw-audio-data}@anchor{514f}@anchor{library/audioop module-audioop}@anchor{e}@anchor{library/audioop translation-repo}@anchor{5150}
@subsection @code{audioop} — Manipulate raw audio data


@geindex module; audioop


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node cgi — Common Gateway Interface support,cgitb — Traceback manager for CGI scripts,audioop — Manipulate raw audio data,Removed Modules
@anchor{library/cgi doc}@anchor{5151}@anchor{library/cgi cgi-common-gateway-interface-support}@anchor{5152}@anchor{library/cgi module-cgi}@anchor{16}@anchor{library/cgi translation-repo}@anchor{5153}
@subsection @code{cgi} — Common Gateway Interface support


@geindex module; cgi


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node cgitb — Traceback manager for CGI scripts,chunk — Read IFF chunked data,cgi — Common Gateway Interface support,Removed Modules
@anchor{library/cgitb doc}@anchor{5154}@anchor{library/cgitb cgitb-traceback-manager-for-cgi-scripts}@anchor{5155}@anchor{library/cgitb module-cgitb}@anchor{17}@anchor{library/cgitb translation-repo}@anchor{5156}
@subsection @code{cgitb} — Traceback manager for CGI scripts


@geindex module; cgitb


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{5157}@anchor{library/chunk chunk-read-iff-chunked-data}@anchor{5158}@anchor{library/chunk module-chunk}@anchor{18}@anchor{library/chunk translation-repo}@anchor{5159}
@subsection @code{chunk} — Read IFF chunked data


@geindex module; chunk


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{515a}@anchor{library/crypt crypt-function-to-check-unix-passwords}@anchor{515b}@anchor{library/crypt module-crypt}@anchor{2b}@anchor{library/crypt translation-repo}@anchor{515c}
@subsection @code{crypt} — Function to check Unix passwords


@geindex module; crypt


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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{6b,,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/}, or argon2-cffi@footnote{https://pypi.org/project/argon2-cffi/}.
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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{515d}@anchor{library/distutils distutils-building-and-installing-python-modules}@anchor{515e}@anchor{library/distutils module-distutils}@anchor{3c}@anchor{library/distutils translation-repo}@anchor{515f}
@subsection @code{distutils} — Building and installing Python modules


@geindex module; distutils


Καταργήθηκε από την έκδοση 3.10, αφαιρέθηκε στην έκδοση 3.12.


This module is no longer part of the Python standard library.
It was @ref{917,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{5160}@anchor{library/imghdr imghdr-determine-the-type-of-an-image}@anchor{5161}@anchor{library/imghdr module-imghdr}@anchor{78}@anchor{library/imghdr translation-repo}@anchor{5162}
@subsection @code{imghdr} — Determine the type of an image


@geindex module; imghdr


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node imp — Access the import internals,mailcap — Mailcap file handling,imghdr — Determine the type of an image,Removed Modules
@anchor{library/imp doc}@anchor{5163}@anchor{library/imp imp-access-the-import-internals}@anchor{5164}@anchor{library/imp module-imp}@anchor{79}@anchor{library/imp translation-repo}@anchor{5165}
@subsection @code{imp} — Access the import internals


@geindex module; imp


Καταργήθηκε από την έκδοση 3.4, αφαιρέθηκε στην έκδοση 3.12.


This module is no longer part of the Python standard library.
It was @ref{921,,removed in Python 3.12} after
being deprecated in Python 3.4.

The @ref{921,,removal notice} includes guidance for
migrating code from @code{imp} to @ref{7a,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node mailcap — Mailcap file handling,msilib — Read and write Microsoft Installer files,imp — Access the import internals,Removed Modules
@anchor{library/mailcap doc}@anchor{5166}@anchor{library/mailcap mailcap-mailcap-file-handling}@anchor{5167}@anchor{library/mailcap module-mailcap}@anchor{8f}@anchor{library/mailcap translation-repo}@anchor{5168}
@subsection @code{mailcap} — Mailcap file handling


@geindex module; mailcap


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{5169}@anchor{library/msilib module-msilib}@anchor{96}@anchor{library/msilib msilib-read-and-write-microsoft-installer-files}@anchor{516a}@anchor{library/msilib translation-repo}@anchor{516b}
@subsection @code{msilib} — Read and write Microsoft Installer files


@geindex module; msilib


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{516c}@anchor{library/nis module-nis}@anchor{a0}@anchor{library/nis nis-interface-to-suns-nis-yellow-pages}@anchor{516d}@anchor{library/nis translation-repo}@anchor{516e}
@subsection @code{nis} — Interface to Sun’s NIS (Yellow Pages)


@geindex module; nis


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{516f}@anchor{library/nntplib module-nntplib}@anchor{a1}@anchor{library/nntplib nntplib-nntp-protocol-client}@anchor{5170}@anchor{library/nntplib translation-repo}@anchor{5171}
@subsection @code{nntplib} — NNTP protocol client


@geindex module; nntplib


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node ossaudiodev — Access to OSS-compatible audio devices,pipes — Interface to shell pipelines,nntplib — NNTP protocol client,Removed Modules
@anchor{library/ossaudiodev doc}@anchor{5172}@anchor{library/ossaudiodev module-ossaudiodev}@anchor{a7}@anchor{library/ossaudiodev ossaudiodev-access-to-oss-compatible-audio-devices}@anchor{5173}@anchor{library/ossaudiodev translation-repo}@anchor{5174}
@subsection @code{ossaudiodev} — Access to OSS-compatible audio devices


@geindex module; ossaudiodev


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node pipes — Interface to shell pipelines,smtpd — SMTP Server,ossaudiodev — Access to OSS-compatible audio devices,Removed Modules
@anchor{library/pipes doc}@anchor{5175}@anchor{library/pipes module-pipes}@anchor{ad}@anchor{library/pipes pipes-interface-to-shell-pipelines}@anchor{5176}@anchor{library/pipes translation-repo}@anchor{5177}
@subsection @code{pipes} — Interface to shell pipelines


@geindex module; pipes


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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{df,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node smtpd — SMTP Server,sndhdr — Determine type of sound file,pipes — Interface to shell pipelines,Removed Modules
@anchor{library/smtpd doc}@anchor{5178}@anchor{library/smtpd module-smtpd}@anchor{d1}@anchor{library/smtpd smtpd-smtp-server}@anchor{5179}@anchor{library/smtpd translation-repo}@anchor{517a}
@subsection @code{smtpd} — SMTP Server


@geindex module; smtpd


Καταργήθηκε από την έκδοση 3.6, αφαιρέθηκε στην έκδοση 3.12.


This module is no longer part of the Python standard library.
It was @ref{911,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node sndhdr — Determine type of sound file,spwd — The shadow password database,smtpd — SMTP Server,Removed Modules
@anchor{library/sndhdr doc}@anchor{517b}@anchor{library/sndhdr module-sndhdr}@anchor{d3}@anchor{library/sndhdr sndhdr-determine-type-of-sound-file}@anchor{517c}@anchor{library/sndhdr translation-repo}@anchor{517d}
@subsection @code{sndhdr} — Determine type of sound file


@geindex module; sndhdr


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@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{517e}@anchor{library/spwd module-spwd}@anchor{d6}@anchor{library/spwd spwd-the-shadow-password-database}@anchor{517f}@anchor{library/spwd translation-repo}@anchor{5180}
@subsection @code{spwd} — The shadow password database


@geindex module; spwd


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node sunau — Read and write Sun AU files,telnetlib — Telnet client,spwd — The shadow password database,Removed Modules
@anchor{library/sunau doc}@anchor{5181}@anchor{library/sunau module-sunau}@anchor{e0}@anchor{library/sunau sunau-read-and-write-sun-au-files}@anchor{5182}@anchor{library/sunau translation-repo}@anchor{5183}
@subsection @code{sunau} — Read and write Sun AU files


@geindex module; sunau


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node telnetlib — Telnet client,uu — Encode and decode uuencode files,sunau — Read and write Sun AU files,Removed Modules
@anchor{library/telnetlib doc}@anchor{5184}@anchor{library/telnetlib module-telnetlib}@anchor{e8}@anchor{library/telnetlib telnetlib-telnet-client}@anchor{5185}@anchor{library/telnetlib translation-repo}@anchor{5186}
@subsection @code{telnetlib} — Telnet client


@geindex module; telnetlib


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node uu — Encode and decode uuencode files,xdrlib — Encode and decode XDR data,telnetlib — Telnet client,Removed Modules
@anchor{library/uu doc}@anchor{5187}@anchor{library/uu module-uu}@anchor{118}@anchor{library/uu translation-repo}@anchor{5188}@anchor{library/uu uu-encode-and-decode-uuencode-files}@anchor{5189}
@subsection @code{uu} — Encode and decode uuencode files


@geindex module; uu


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node xdrlib — Encode and decode XDR data,,uu — Encode and decode uuencode files,Removed Modules
@anchor{library/xdrlib doc}@anchor{518a}@anchor{library/xdrlib module-xdrlib}@anchor{128}@anchor{library/xdrlib translation-repo}@anchor{518b}@anchor{library/xdrlib xdrlib-encode-and-decode-xdr-data}@anchor{518c}
@subsection @code{xdrlib} — Encode and decode XDR data


@geindex module; xdrlib


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.13.


This module is no longer part of the Python standard library.
It was @ref{682,,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}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@geindex security considerations
@anchor{library/security_warnings security-warnings}@anchor{518d}
@node Security Considerations<3>,,Removed Modules,The Python Standard Library
@anchor{library/security_warnings doc}@anchor{518e}@anchor{library/security_warnings security-considerations}@anchor{518f}@anchor{library/security_warnings translation-repo}@anchor{5190}
@section Security Considerations


The following modules have specific security considerations:


@itemize *

@item 
@ref{f,,base64}: @ref{3ef8,,base64 security considerations} in
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}

@item 
@ref{6b,,hashlib}: @ref{31ed,,all constructors take a «usedforsecurity» keyword-only argument disabling known insecure and blocked algorithms}

@item 
@ref{75,,http.server} is not suitable for production use, only implementing
basic security checks. See the @ref{4333,,security considerations}.

@item 
@ref{8a,,logging}: @ref{3406,,Logging configuration uses eval()}

@item 
@ref{98,,multiprocessing}: @ref{38d0,,Connection.recv() uses pickle}

@item 
@ref{ab,,pickle}: @ref{2f3e,,Restricting globals in pickle}

@item 
@ref{c0,,random} shouldn’t be used for security purposes, use @ref{c8,,secrets}
instead

@item 
@ref{cb,,shelve}: @ref{2f61,,shelve is based on pickle and thus unsuitable for dealing with untrusted sources}

@item 
@ref{d8,,ssl}: @ref{3ad9,,SSL/TLS security considerations}

@item 
@ref{df,,subprocess}: @ref{399c,,Subprocess security considerations}

@item 
@ref{e9,,tempfile}: @ref{2efa,,mktemp is deprecated due to vulnerability to race conditions}

@item 
@ref{129,,xml}: @ref{3f34,,XML security}

@item 
@ref{13a,,zipfile}: @ref{30fe,,maliciously prepared .zip files can cause disk volume exhaustion}
@end itemize

The @ref{d28,,-I} command line option can be used to run Python in isolated
mode. When it cannot be used, the @ref{9a3,,-P} option or the
@geindex PYTHONSAFEPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONSAFEPATH
@ref{9a4,,PYTHONSAFEPATH} environment variable can be used to not prepend a
potentially unsafe path to @ref{194,,sys.path} such as the current directory, the
script’s directory or an empty string.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Επέκταση και Ενσωμάτωση του Διερμηνέα της Python,Python/C API reference manual,The Python Standard Library,Top
@anchor{extending/index doc}@anchor{5191}@anchor{extending/index extending-and-embedding-the-python-interpreter}@anchor{5192}@anchor{extending/index extending-index}@anchor{21aa}@anchor{extending/index translation-repo}@anchor{5193}
@chapter Επέκταση και Ενσωμάτωση του Διερμηνέα της Python


This document describes how to write modules in C or C++ to extend the Python
interpreter with new modules.  Those modules can do what Python code does –
define functions, object types and methods – but also interact with native
libraries or achieve better performance by avoiding the overhead of an
interpreter.  The document also describes how
to embed the Python interpreter in another application, for use as an extension
language.  Finally, it shows how to compile and link extension modules so that
they can be loaded dynamically (at run time) into the interpreter, if the
underlying operating system supports this feature.

This document assumes basic knowledge about C and Python.  For an informal
introduction to Python, see @ref{21a9,,Οδηγός εκμάθησης Python}.  @ref{3f8,,Εγχειρίδιο Αναφοράς της Γλώσσας Python}
gives a more formal definition of the language.  @ref{3f7,,The Python Standard Library} documents
the existing object types, functions and modules (both built-in and written in
Python) that give the language its wide application range.

Για μια λεπτομερή περιγραφή ολόκληρου του Python/C API, δείτε το ξεχωριστό @ref{21ab,,Python/C API reference manual}.

To support extensions, Python’s C API (Application Programmers Interface)
defines a set of functions, macros and variables that provide access to most
aspects of the Python run-time system.  The Python API is incorporated in a C
source file by including the header @code{"Python.h"}.

@cartouche
@quotation Σημείωση 
The C extension interface is specific to CPython, and extension modules do
not work on other Python implementations.  In many cases, it is possible to
avoid writing C extensions and preserve portability to other implementations.
For example, if your use case is calling C library functions or system calls,
you should consider using the @ref{2d,,ctypes} module or the cffi@footnote{https://cffi.readthedocs.io/} library rather than writing
custom C code.
These modules let you write Python code to interface with C code and are more
portable between implementations of Python than writing and compiling a C
extension module.
@end quotation
@end cartouche
@anchor{extending/first-extension-module extending-simpleexample}@anchor{5194}
@menu
* Your first C API extension module:: 
* Using the C API; Assorted topics: Using the C API Assorted topics. 
* Defining Extension Types; Tutorial: Defining Extension Types Tutorial. 
* Defining Extension Types; Assorted Topics: Defining Extension Types Assorted Topics. 
* Κατασκευή Επεκτάσεων C και C++:: 
* Building C and C++ Extensions on Windows:: 
* Embedding Python in Another Application:: 
* Προτεινόμενα εργαλεία τρίτων:: 
* C API Tutorial:: 
* Guides for intermediate topics:: 
* Ενσωμάτωση του χρόνου εκτέλεσης της CPython σε μεγαλύτερη εφαρμογή:: 

@end menu

@node Your first C API extension module,Using the C API Assorted topics,,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python
@anchor{extending/first-extension-module doc}@anchor{5195}@anchor{extending/first-extension-module first-extension-module}@anchor{5196}@anchor{extending/first-extension-module your-first-c-api-extension-module}@anchor{5197}
@section Your first C API extension module


This tutorial will take you through creating a simple
Python extension module written in C or C++.

We will use the low-level Python C API directly.
For easier ways to create extension modules, see
the @ref{5198,,recommended third party tools}.

The tutorial assumes basic knowledge about Python: you should be able to
define functions in Python code before starting to write them in C.
See @ref{21a9,,Οδηγός εκμάθησης Python} for an introduction to Python itself.

The tutorial should be approachable for anyone who can write a basic C library.
While we will mention several concepts that a C beginner would not be expected
to know, like @code{static} functions or linkage declarations, understanding these
is not necessary for success.

We will focus on giving you a «feel» of what Python’s C API is like.
It will not teach you important concepts, like error handling
and reference counting, which are covered in later chapters.

We will assume that you use a Unix-like system (including macOS and
Linux), or Windows.
On other systems, you might need to adjust some details – for example,
a system command name.

You need to have a suitable C compiler and Python development headers installed.
On Linux, headers are often in a package like @code{python3-dev}
or @code{python3-devel}.

You need to be able to install Python packages.
This tutorial uses pip@footnote{https://pip.pypa.io/} (@code{pip install}), but you
can substitute any tool that can build and install @code{pyproject.toml}-based
projects, like uv@footnote{https://docs.astral.sh/uv/} (@code{uv pip install}).
Preferably, have a @ref{3a9,,virtual environment} activated.

@cartouche
@quotation Σημείωση 
This tutorial uses APIs that were added in CPython 3.15.
To create an extension that’s compatible with earlier versions of CPython,
please follow an earlier version of this documentation.

This tutorial uses C syntax added in C11 and C++20.
If your extension needs to be compatible with earlier standards,
please follow tutorials in documentation for Python 3.14 or below.
@end quotation
@end cartouche

@menu
* What we’ll do:: 
* Start with the headers:: 
* Running your build tool:: 
* Module export hook:: 
* The slot table:: 
* Exposing a function:: 
* Returning an integer:: 
* Accepting a string:: 
* The result:: 
* Appendix; Other build tools: Appendix Other build tools. 

@end menu

@node What we’ll do,Start with the headers,,Your first C API extension module
@anchor{extending/first-extension-module what-we-ll-do}@anchor{5199}
@subsection What we’ll do


Let’s create an extension module called @code{spam} @footnote{
@code{spam} is the favorite food of Monty Python fans…
},
which will include a Python interface to the C
standard library function @code{system()}.
This function is defined in @code{stdlib.h}.
It takes a C string as argument, runs the argument as a system
command, and returns a result value as an integer.
A manual page for @code{system()} might summarize it this way:

@example
#include <stdlib.h>
int system(const char *command);
@end example

Note that like many functions in the C standard library,
this function is already exposed in Python.
In production, use @ref{17ff,,os.system()} or @ref{f45,,subprocess.run()}
rather than the module you’ll write here.

We want this function to be callable from Python as follows:

@example
>>> import spam
>>> status = spam.system("whoami")
User Name
>>> status
0
@end example

@cartouche
@quotation Σημείωση 
The system command @code{whoami} prints out your username.
It’s useful in tutorials like this one because it has the same name on
both Unix and Windows.
@end quotation
@end cartouche

@node Start with the headers,Running your build tool,What we’ll do,Your first C API extension module
@anchor{extending/first-extension-module start-with-the-headers}@anchor{519a}
@subsection Start with the headers


Begin by creating a directory for this tutorial, and switching to it
on the command line.
Then, create a file named @code{spammodule.c} in your directory.
@footnote{
The source file name is entirely up to you,
though some tools can be picky about the @code{.c} extension.
This tutorial uses the traditional @code{*module.c} suffix.
Some people would just use @code{spam.c} to implement a module
named @code{spam},
projects where Python isn’t the primary language might use @code{py_spam.c},
and so on.
}

In this file, we’ll include two headers: @code{Python.h} to pull in
all declarations of the Python C API, and @code{stdlib.h} for the
@code{system()} function. @footnote{
Including @code{stdlib.h} is technically not necessary,
since @code{Python.h} includes it and
@ref{519b,,several other standard headers} for its own use
or for backwards compatibility.
However, it is good practice to explicitly include what you need.
}

Add the following lines to @code{spammodule.c}:

@example
#include <Python.h>
#include <stdlib.h>     // for system()
@end example

Be sure to put @code{stdlib.h}, and any other standard library includes,
`after' @code{Python.h}.
On some systems, Python may define some pre-processor definitions
that affect the standard headers.

@node Running your build tool,Module export hook,Start with the headers,Your first C API extension module
@anchor{extending/first-extension-module running-your-build-tool}@anchor{519c}
@subsection Running your build tool


With only the includes in place, your extension won’t do anything.
Still, it’s a good time to compile it and try to import it.
This will ensure that your build tool works, so that you can make
and test incremental changes as you follow the rest of the text.

CPython itself does not come with a tool to build extension modules;
it is recommended to use a third-party project for this.
In this tutorial, we’ll use meson-python@footnote{https://mesonbuild.com/meson-python/}.
(If you want to use another one, see @ref{519d,,Appendix; Other build tools}.)

@c at the time of writing, meson-python has the least overhead for a
@c simple extension using PyModExport.
@c Change this if another tool makes things easier.

@code{meson-python} requires defining a «project» using two extra files.

First, add @code{pyproject.toml} with these contents:

@example
[build-system]
build-backend = 'mesonpy'
requires = ['meson-python']

[project]
# Placeholder project information
# (change this before distributing the module)
name = 'sampleproject'
version = '0'
@end example

Then, create @code{meson.build} containing the following:

@example
project('sampleproject', 'c')

py = import('python').find_installation(pure: false)

py.extension_module(
   'spam',          # name of the importable Python module
   'spammodule.c',  # the C source file
   install: true,
)
@end example

@cartouche
@quotation Σημείωση 
See meson-python documentation@footnote{meson-python} for details on
configuration.
@end quotation
@end cartouche

Now, build install the `project in the current directory' (@code{.}) via @code{pip}:

@example
python -m pip -v install .
@end example

The @code{-v} (@code{--verbose}) option causes @code{pip} to show the output from
the compiler, which is often useful during development.

@cartouche
@quotation Πρακτική συμβουλή 
If you don’t have @code{pip} installed, run @code{python -m ensurepip},
preferably in a @ref{3a9,,virtual environment}.
(Or, if you prefer another tool that can build and install
@code{pyproject.toml}-based projects, use that.)
@end quotation
@end cartouche

Note that you will need to run this command again every time you change your
extension.
Unlike Python, C has an explicit compilation step.

When your extension is compiled and installed, start Python and try to
import it.
This should fail with the following exception:

@example
>>> import spam
Traceback (most recent call last):
   ...
ImportError: dynamic module does not define module export function (PyModExport_spam or PyInit_spam)
@end example

@node Module export hook,The slot table,Running your build tool,Your first C API extension module
@anchor{extending/first-extension-module module-export-hook}@anchor{519e}
@subsection Module export hook


The exception you got when you tried to import the module told you that Python
is looking for a «module export function», also known as a
@ref{38d,,module export hook}.
Let’s define one.

First, add a prototype below the @code{#include} lines:

@example

PyMODEXPORT_FUNC PyModExport_spam(void);

@end example

@cartouche
@quotation Πρακτική συμβουλή 
The prototype is not strictly necessary, but some modern compilers emit
warnings without it.
It’s generally better to add the prototype than to disable the warning.
@end quotation
@end cartouche

The @ref{1990,,PyMODEXPORT_FUNC} macro declares the function’s
return type, and adds any special linkage declarations needed
to make the function visible and usable when CPython loads it.

After the prototype, add the function itself.
For now, make it return @code{NULL}:

@example
PyMODEXPORT_FUNC
PyModExport_spam(void)
@{
   return NULL;
@}
@end example

Compile and load the module again.
You should get a different error this time.

@example
>>> import spam
Traceback (most recent call last):
   ...
SystemError: module export hook for module 'spam' failed without setting an exception
@end example

Simply returning @code{NULL} is `not' correct behavior for an export hook,
and CPython complains about it.
That’s good – it means that CPython found the function!
Let’s now make it do something useful.

@node The slot table,Exposing a function,Module export hook,Your first C API extension module
@anchor{extending/first-extension-module the-slot-table}@anchor{519f}
@subsection The slot table


Rather than @code{NULL}, the export hook should return the information needed to
create a module.
Let’s start with the basics: the name and docstring.

The information should be defined in an array of
@ref{19d,,PySlot} entries, which are essentially key-value pairs.
Define this array just before your export hook:

@example
PyABIInfo_VAR(abi_info);

static PySlot spam_slots[] = @{
   PySlot_STATIC_DATA(Py_mod_abi, &abi_info),
   PySlot_STATIC_DATA(Py_mod_name, "spam"),
   PySlot_STATIC_DATA(Py_mod_doc, "A wonderful module with an example function"),
   PySlot_END
@};
@end example

The @ref{388,,PySlot_STATIC_DATA} macro is used when the slot value
(here: @code{&abi_info}, @code{"spam"}, and the docstring) is a pointer to constant,
statically allocated data.

The @code{PyABIInfo_VAR(abi_info);} macro and the @ref{358,,Py_mod_abi} slot
are a bit of boilerplate that helps prevent extensions compiled for
a different version of Python from crashing the interpreter.

For both @ref{51a0,,Py_mod_name} and @ref{51a1,,Py_mod_doc}, the values are C
strings – that is, NUL-terminated, UTF-8 encoded byte arrays.

Note @code{PySlot_END} sentinel entry at the end.
This marks the end of the array.
If you forget it, you’ll trigger undefined behavior.

The array is defined as @code{static} – that is, not visible outside this @code{.c} file.
This will be a common theme.
CPython only needs to access the export hook; all global variables
and all other functions should generally be @code{static}, so that they don’t
clash with other extensions.

Return this array from your export hook instead of @code{NULL}:

@example
PyMODEXPORT_FUNC
PyModExport_spam(void)
@{
   return spam_slots;
@}
@end example

Now, recompile and try it out:

@example
>>> import spam
>>> print(spam)
<module 'spam' from '/home/encukou/dev/cpython/spam.so'>
@end example

You have an extension module!
Try @code{help(spam)} to see the docstring.

The next step will be adding a function.

@node Exposing a function,Returning an integer,The slot table,Your first C API extension module
@anchor{extending/first-extension-module backtoexample}@anchor{51a2}@anchor{extending/first-extension-module exposing-a-function}@anchor{51a3}
@subsection Exposing a function


To expose the @code{system()} C function directly to Python,
we’ll need to write a layer of glue code to convert arguments from Python
objects to C values, and the C return value back to Python.

One of the simplest ways to write glue code is a «@ref{18a9,,METH_O}» function,
which takes two Python objects and returns one.
All Python objects – regardless of the Python type – are represented in C
as pointers to the @ref{19b,,PyObject} structure.

Add such a function above the slots array:

@example
static PyObject *
spam_system(PyObject *self, PyObject *arg)
@{
   Py_RETURN_NONE;
@}
@end example

For now, we ignore the arguments, and use the @ref{1815,,Py_RETURN_NONE}
macro, which expands to a @code{return} statement that properly returns
a Python @ref{a65,,None} object.

Recompile your extension to make sure you don’t have syntax errors.
We haven’t yet added @code{spam_system} to the module, so you might get a
warning that @code{spam_system} is unused.

@menu
* Method definitions:: 

@end menu

@node Method definitions,,,Exposing a function
@anchor{extending/first-extension-module method-definitions}@anchor{51a4}@anchor{extending/first-extension-module methodtable}@anchor{51a5}
@subsubsection Method definitions


To expose the C function to Python, you will need to provide several pieces of
information in a structure called
@ref{1879,,PyMethodDef} @footnote{
The @code{PyMethodDef} structure is also used
to create methods of classes, so there’s no separate
«@code{PyFunctionDef}».
}:


@itemize *

@item 
@code{ml_name}: the name of the Python function;

@item 
@code{ml_doc}: a docstring;

@item 
@code{ml_meth}: the C function to be called; and

@item 
@code{ml_flags}: a set of flags describing details like how Python arguments are
passed to the C function.
We’ll use @ref{18a9,,METH_O} here – the flag that matches our
@code{spam_system} function’s signature.
@end itemize

Because modules typically create several functions, these definitions
need to be collected in an array, with a zero-filled sentinel at the end.
Add this array just below the @code{spam_system} function:

@example

static PyMethodDef spam_methods[] = @{
    @{
        .ml_name="system",
        .ml_meth=spam_system,
        .ml_flags=METH_O,
        .ml_doc="Execute a shell command.",
    @},
    @{NULL, NULL, 0, NULL@}        /* Sentinel */
@};

@end example

As with module slots, a zero-filled sentinel marks the end of the array.

Next, we’ll add the method to the module.
Add a @ref{51a6,,Py_mod_methods} slot to your @ref{1879,,PyMethodDef} array:

@example

PyABIInfo_VAR(abi_info);

static PySlot spam_slots[] = @{
    PySlot_STATIC_DATA(Py_mod_abi, &abi_info),
    PySlot_STATIC_DATA(Py_mod_name, "spam"),
    PySlot_STATIC_DATA(Py_mod_doc, "A wonderful module with an example function"),
    PySlot_STATIC_DATA(Py_mod_methods, spam_methods),
    PySlot_END
@};

@end example

Recompile your extension again, and test it.
Be sure to restart the Python interpreter, so that @code{import spam} picks
up the new version of the module.

You should now be able to call the function:

@example
>>> import spam
>>> print(spam.system)
<built-in function system>
>>> print(spam.system('whoami'))
None
@end example

Note that our @code{spam.system} does not yet run the @code{whoami} command;
it only returns @code{None}.

Check that the function accepts exactly one argument, as specified by
the @ref{18a9,,METH_O} flag:

@example
>>> print(spam.system('too', 'many', 'arguments'))
Traceback (most recent call last):
   ...
TypeError: spam.system() takes exactly one argument (3 given)
@end example

@node Returning an integer,Accepting a string,Exposing a function,Your first C API extension module
@anchor{extending/first-extension-module returning-an-integer}@anchor{51a7}
@subsection Returning an integer


Now, let’s take a look at the return value.
Instead of @code{None}, we’ll want @code{spam.system} to return a number – that is,
a Python @ref{326,,int} object.
Eventually this will be the exit code of a system command,
but let’s start with a fixed value, say, @code{3}.

The Python C API provides a function to create a Python @ref{326,,int} object
from a C @code{int} value: @ref{1dca,,PyLong_FromLong()}. @footnote{
The name @ref{1dca,,PyLong_FromLong()}
might not seem obvious.
@code{PyLong} refers to a the Python @ref{326,,int}, which was originally
called @code{long}; the @code{FromLong} refers to the C @code{long} (or @code{long int})
type.
}

To call it, replace the @code{Py_RETURN_NONE} with the following 3 lines:

@c this could be a one-liner, but we want to show the data types here

@example
static PyObject *
spam_system(PyObject *self, PyObject *arg)
@{
   int status = 3;
   PyObject *result = PyLong_FromLong(status);
   return result;
@}
@end example

Recompile, restart the Python interpreter again,
and check that the function now returns 3:

@example
>>> import spam
>>> spam.system('whoami')
3
@end example

@node Accepting a string,The result,Returning an integer,Your first C API extension module
@anchor{extending/first-extension-module accepting-a-string}@anchor{51a8}
@subsection Accepting a string


Finally, let’s handle the function argument.

Our C function, @code{spam_system()}, takes two arguments.
The first one, @code{PyObject *self}, will be set to the @code{spam} module
object.
This isn’t useful in our case, so we’ll ignore it.

The other one, @code{PyObject *arg}, will be set to the object that the user
passed from Python.
We expect that it should be a Python string.
In order to use the information in it, we will need
to convert it to a C value – in this case, a C string (@code{const char *}).

There’s a slight type mismatch here: Python’s @ref{1df,,str} objects store
Unicode text, but C strings are arrays of bytes.
So, we’ll need to `encode' the data, and we’ll use the UTF-8 encoding for it.
(UTF-8 might not always be correct for system commands, but it’s what
@ref{ca7,,str.encode()} uses by default,
and the C API has special support for it.)

The function to encode a Python string into a UTF-8 buffer is named
@ref{c6f,,PyUnicode_AsUTF8AndSize()} @footnote{
Here, @code{PyUnicode} refers to the original name of
the Python @ref{1df,,str} class: @code{unicode}.

The @code{AndSize} part of the name refers to the fact that this function can
also retrieve the size of the buffer, using an output argument.
We don’t need this, so we set the second argument to NULL.
}.
Call it like this:

@example
static PyObject *
spam_system(PyObject *self, PyObject *arg)
@{
   const char *command = PyUnicode_AsUTF8AndSize(arg, NULL);
   int status = 3;
   PyObject *result = PyLong_FromLong(status);
   return result;
@}
@end example

If @ref{c6f,,PyUnicode_AsUTF8AndSize()} is successful, `command' will point to the
resulting C string – a zero-terminated array of bytes @footnote{
We’re ignoring the fact that Python strings can also
contain NUL bytes, which terminate a C string.
In other words, our function will treat @code{spam.system("foo\0bar")} as
@code{spam.system("foo")}.
This possibility can lead to security issues, so the real @code{os.system}
function size checks for this case and raises an error.
}.
This buffer is managed by the `arg' object, which means we don’t need to free
it, but we must follow some rules:


@itemize *

@item 
We should only use the buffer inside the @code{spam_system} function.
After @code{spam_system} returns, `arg' and the buffer it manages might be
garbage-collected.

@item 
We must not modify it. This is why we use @code{const}.
@end itemize

If @ref{c6f,,PyUnicode_AsUTF8AndSize()} was `not' successful, it returns a @code{NULL}
pointer.
When calling `any' Python C API, we always need to handle such error cases.
The way to do this in general is left for later chapters of this documentation.
For now, be assured that we are already handling errors from
@ref{1dca,,PyLong_FromLong()} correctly.

For the @ref{c6f,,PyUnicode_AsUTF8AndSize()} call, the correct way to handle
errors is returning @code{NULL} from @code{spam_system}.
Add an @code{if} block for this:

@example
static PyObject *
spam_system(PyObject *self, PyObject *arg)
@{
   const char *command = PyUnicode_AsUTF8AndSize(arg);
   if (command == NULL) @{
      return NULL;
   @}
   int status = 3;
   PyObject *result = PyLong_FromLong(status);
   return result;
@}
@end example

To test that error handling works, compile again, restart Python so that
@code{import spam} picks up the new version of your module, and try passing
a non-string value to your function:

@example
>>> import spam
>>> spam.system(3)
Traceback (most recent call last):
   ...
TypeError: bad argument type for built-in operation
@end example

Now, all that is left is calling the C library function @code{system()} with
the @code{char *} buffer, and using its result instead of the @code{3}:

@example
static PyObject *
spam_system(PyObject *self, PyObject *arg)
@{
   const char *command = PyUnicode_AsUTF8AndSize(arg);
   if (command == NULL) @{
      return NULL;
   @}
   int status = system(command);
   PyObject *result = PyLong_FromLong(status);
   return result;
@}
@end example

Compile your module, restart Python, and test.
This time, you should see your username – the output of the @code{whoami}
system command:

@example
>>> import spam
>>> result = spam.system('whoami')
User Name
>>> result
0
@end example

You can also test with other commands, like @code{ls}, @code{dir}, or one
that doesn’t exist:

@example
>>> import spam
>>> result = spam.system('nonexistent-command')
sh: line 1: nonexistent-command: command not found
>>> result
32512
@end example

@node The result,Appendix Other build tools,Accepting a string,Your first C API extension module
@anchor{extending/first-extension-module the-result}@anchor{51a9}
@subsection The result


Congratulations!
You have written a complete Python C API extension module,
and completed this tutorial!

Here is the entire source file, for your convenience:
@anchor{extending/first-extension-module extending-spammodule-source}@anchor{51aa}
@example
/// Includes

#include <Python.h>
#include <stdlib.h>     // for system()

/// Implementation of spam.system

static PyObject *
spam_system(PyObject *self, PyObject *arg)
@{
   const char *command = PyUnicode_AsUTF8AndSize(arg, NULL);
   if (command == NULL) @{
      return NULL;
   @}
   int status = system(command);
   PyObject *result = PyLong_FromLong(status);
   return result;
@}

/// Module method table

static PyMethodDef spam_methods[] = @{
    @{
        .ml_name="system",
        .ml_meth=spam_system,
        .ml_flags=METH_O,
        .ml_doc="Execute a shell command.",
    @},
    @{NULL, NULL, 0, NULL@}        /* Sentinel */
@};

/// Module slot table

PyABIInfo_VAR(abi_info);

static PySlot spam_slots[] = @{
    PySlot_STATIC_DATA(Py_mod_abi, &abi_info),
    PySlot_STATIC_DATA(Py_mod_name, "spam"),
    PySlot_STATIC_DATA(Py_mod_doc, "A wonderful module with an example function"),
    PySlot_STATIC_DATA(Py_mod_methods, spam_methods),
    PySlot_END
@};

/// Export hook prototype

PyMODEXPORT_FUNC PyModExport_spam(void);

/// Module export hook

PyMODEXPORT_FUNC
PyModExport_spam(void)
@{
   return spam_slots;
@}
@end example

@node Appendix Other build tools,,The result,Your first C API extension module
@anchor{extending/first-extension-module appendix-other-build-tools}@anchor{51ab}@anchor{extending/first-extension-module first-extension-other-tools}@anchor{519d}
@subsection Appendix: Other build tools


You should be able to follow this tutorial – except the
`Running your build tool' section itself – with a build tool other
than @code{meson-python}.

The Python Packaging User Guide has a list of recommended tools@footnote{https://packaging.python.org/en/latest/guides/tool-recommendations/#build-backends-for-extension-modules};
be sure to choose one for the C language.

@menu
* Workaround for missing PyInit function:: 
* Compiling directly:: 

@end menu

@node Workaround for missing PyInit function,Compiling directly,,Appendix Other build tools
@anchor{extending/first-extension-module workaround-for-missing-pyinit-function}@anchor{51ac}
@subsubsection Workaround for missing PyInit function


If your build tool output complains about missing @code{PyInit_spam},
add the following function to your module for now:

@example
// A workaround
void *PyInit_spam(void) @{ return NULL; @}
@end example

This is a shim for an old-style @ref{38d,,initialization function},
which was required in extension modules for CPython 3.14 and below.
Current CPython does not need it, but some build tools may still assume that
all extension modules need to define it.

If you use this workaround, you will get the exception
@code{SystemError: initialization of spam failed without raising an exception}
instead of
@code{ImportError: dynamic module does not define module export function}.

@node Compiling directly,,Workaround for missing PyInit function,Appendix Other build tools
@anchor{extending/first-extension-module compiling-directly}@anchor{51ad}
@subsubsection Compiling directly


Using a third-party build tool is heavily recommended,
as it will take care of various details of your platform and Python
installation, of naming the resulting extension, and, later, of distributing
your work.

If you are building an extension for as `specific' system, or for yourself
only, you might instead want to run your compiler directly.
The way to do this is system-specific; be prepared for issues you will need
to solve yourself.

@menu
* Linux:: 

@end menu

@node Linux,,,Compiling directly
@anchor{extending/first-extension-module linux}@anchor{51ae}
@subsubsection Linux


On Linux, the Python development package may include a @code{python3-config}
command that prints out the required compiler flags.
If you use it, check that it corresponds to the CPython interpreter you’ll use
to load the module.
Then, start with the following command:

@example
gcc --shared $(python3-config --cflags --ldflags) spammodule.c -o spam.so
@end example

This should generate a @code{spam.so} file that you need to put in a directory
on @ref{194,,sys.path}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Using the C API Assorted topics,Defining Extension Types Tutorial,Your first C API extension module,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python
@anchor{extending/extending doc}@anchor{51af}@anchor{extending/extending extending-intro}@anchor{51b0}@anchor{extending/extending translation-repo}@anchor{51b1}@anchor{extending/extending using-the-c-api-assorted-topics}@anchor{51b2}
@section Using the C API: Assorted topics


The @ref{5196,,tutorial} walked you through
creating a C API extension module, but left many areas unexplained.
This document looks at several concepts that you’ll need to learn
in order to write more complex extensions.

@menu
* Errors and Exceptions:: 
* Embedding an extension:: 
* Calling Python Functions from C:: 
* Extracting Parameters in Extension Functions:: 
* Keyword Parameters for Extension Functions:: 
* Building Arbitrary Values:: 
* Reference Counts:: 
* Writing Extensions in C++:: 
* Providing a C API for an Extension Module:: 

@end menu

@node Errors and Exceptions,Embedding an extension,,Using the C API Assorted topics
@anchor{extending/extending errors-and-exceptions}@anchor{51b3}@anchor{extending/extending extending-errors}@anchor{51b4}
@subsection Errors and Exceptions


An important convention throughout the Python interpreter is the following: when
a function fails, it should set an exception condition and return an error value
(usually @code{-1} or a @code{NULL} pointer).  Exception information is stored in
three members of the interpreter’s thread state.  These are @code{NULL} if
there is no exception.  Otherwise they are the C equivalents of the members
of the Python tuple returned by @ref{a7a,,sys.exc_info()}.  These are the
exception type, exception instance, and a traceback object.  It is important
to know about them to understand how errors are passed around.

The Python API defines a number of functions to set various types of exceptions.

The most common one is @ref{980,,PyErr_SetString()}.  Its arguments are an exception
object and a C string.  The exception object is usually a predefined object like
@ref{51b5,,PyExc_ZeroDivisionError}.  The C string indicates the cause of the error
and is converted to a Python string object and stored as the «associated value»
of the exception.

Another useful function is @ref{51b6,,PyErr_SetFromErrno()}, which only takes an
exception argument and constructs the associated value by inspection of the
global variable @code{errno}.  The most general function is
@ref{97f,,PyErr_SetObject()}, which takes two object arguments, the exception and
its associated value.  You don’t need to @ref{974,,Py_INCREF()} the objects passed
to any of these functions.

You can test non-destructively whether an exception has been set with
@ref{1ea5,,PyErr_Occurred()}.  This returns the current exception object, or @code{NULL}
if no exception has occurred.  You normally don’t need to call
@code{PyErr_Occurred()} to see whether an error occurred in a function call,
since you should be able to tell from the return value.

When a function `f' that calls another function `g' detects that the latter
fails, `f' should itself return an error value (usually @code{NULL} or @code{-1}).  It
should `not' call one of the @code{PyErr_*} functions — one has already
been called by `g'. `f'’s caller is then supposed to also return an error
indication to `its' caller, again `without' calling @code{PyErr_*}, and so on
— the most detailed cause of the error was already reported by the function
that first detected it.  Once the error reaches the Python interpreter’s main
loop, this aborts the currently executing Python code and tries to find an
exception handler specified by the Python programmer.

(There are situations where a module can actually give a more detailed error
message by calling another @code{PyErr_*} function, and in such cases it is
fine to do so.  As a general rule, however, this is not necessary, and can cause
information about the cause of the error to be lost: most operations can fail
for a variety of reasons.)

To ignore an exception set by a function call that failed, the exception
condition must be cleared explicitly by calling @ref{13d9,,PyErr_Clear()}.  The only
time C code should call @code{PyErr_Clear()} is if it doesn’t want to pass the
error on to the interpreter but wants to handle it completely by itself
(possibly by trying something else, or pretending nothing went wrong).

Every failing @code{malloc()} call must be turned into an exception — the
direct caller of @code{malloc()} (or @code{realloc()}) must call
@ref{51b7,,PyErr_NoMemory()} and return a failure indicator itself.  All the
object-creating functions (for example, @ref{1dca,,PyLong_FromLong()}) already do
this, so this note is only relevant to those who call @code{malloc()} directly.

Also note that, with the important exception of @ref{3b1,,PyArg_ParseTuple()} and
friends, functions that return an integer status usually return a positive value
or zero for success and @code{-1} for failure, like Unix system calls.

Finally, be careful to clean up garbage (by making @ref{b6e,,Py_XDECREF()} or
@ref{975,,Py_DECREF()} calls for objects you have already created) when you return
an error indicator!

The choice of which exception to raise is entirely yours.  There are predeclared
C objects corresponding to all built-in Python exceptions, such as
@ref{51b5,,PyExc_ZeroDivisionError}, which you can use directly. Of course, you
should choose exceptions wisely — don’t use @ref{51b8,,PyExc_TypeError} to mean
that a file couldn’t be opened (that should probably be @ref{51b9,,PyExc_OSError}).
If something’s wrong with the argument list, the @ref{3b1,,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,
@ref{51ba,,PyExc_ValueError} is appropriate.

You can also define a new exception that is unique to your module.
The simplest way to do this is to declare a static global object variable at
the beginning of the file:

@example
static PyObject *SpamError = NULL;
@end example

and initialize it by calling @ref{160e,,PyErr_NewException()} in the module’s
@ref{d46,,Py_mod_exec} function (@code{spam_module_exec()}):

@example
SpamError = PyErr_NewException("spam.error", NULL, NULL);
@end example

Since @code{SpamError} is a global variable, it will be overwritten every time
the module is reinitialized, when the @ref{d46,,Py_mod_exec} function is called.

For now, let’s avoid the issue: we will block repeated initialization by raising an
@ref{1bd,,ImportError}:

@example
static PyObject *SpamError = NULL;

static int
spam_module_exec(PyObject *m)
@{
    if (SpamError != NULL) @{
        PyErr_SetString(PyExc_ImportError,
                        "cannot initialize spam module more than once");
        return -1;
    @}
    SpamError = PyErr_NewException("spam.error", NULL, NULL);
    if (PyModule_AddObjectRef(m, "SpamError", SpamError) < 0) @{
        return -1;
    @}

    return 0;
@}

static PyModuleDef_Slot spam_module_slots[] = @{
    @{Py_mod_exec, spam_module_exec@},
    @{0, NULL@}
@};

static struct PyModuleDef spam_module = @{
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "spam",
    .m_size = 0,  // non-negative
    .m_slots = spam_module_slots,
@};

PyMODINIT_FUNC
PyInit_spam(void)
@{
    return PyModuleDef_Init(&spam_module);
@}
@end example

Note that the Python name for the exception object is @code{spam.error}.  The
@ref{160e,,PyErr_NewException()} function may create a class with the base class
being @ref{d9e,,Exception} (unless another class is passed in instead of @code{NULL}),
described in @ref{1e1e,,Built-in Exceptions}.

Note also that the @code{SpamError} variable retains a reference to the newly
created exception class; this is intentional!  Since the exception could be
removed from the module by external code, an owned reference to the class is
needed to ensure that it will not be discarded, causing @code{SpamError} to
become a dangling pointer. Should it become a dangling pointer, C code which
raises the exception could cause a core dump or other unintended side effects.

For now, the @ref{975,,Py_DECREF()} call to remove this reference is missing.
Even when the Python interpreter shuts down, the global @code{SpamError}
variable will not be garbage-collected. It will «leak».
We did, however, ensure that this will happen at most once per process.

We discuss the use of @ref{1875,,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{980,,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 Embedding an extension,Calling Python Functions from C,Errors and Exceptions,Using the C API Assorted topics
@anchor{extending/extending compilation}@anchor{51bb}@anchor{extending/extending embedding-an-extension}@anchor{51bc}
@subsection Embedding an extension


If you want to make your module a permanent
part of the Python interpreter, you will have to change the configuration setup
and rebuild the interpreter.  On Unix, place
your file (@code{spammodule.c} for example) in the @code{Modules/} directory
of an unpacked source distribution, add a line to the file
@code{Modules/Setup.local} describing your file:

@example
spam spammodule.o
@end example

and rebuild the interpreter by running @code{make} in the toplevel
directory.  You can also run @code{make} in the @code{Modules/}
subdirectory, but then you must first rebuild @code{Makefile} there by running
“@code{make} Makefile”.  (This is necessary each time you change the
@code{Setup} file.)

If your module requires additional libraries to link with, these can be listed
on the line in the configuration file as well, for instance:

@example
spam spammodule.o -lX11
@end example

@node Calling Python Functions from C,Extracting Parameters in Extension Functions,Embedding an extension,Using the C API Assorted topics
@anchor{extending/extending calling-python-functions-from-c}@anchor{51bd}@anchor{extending/extending callingpython}@anchor{51be}
@subsection Calling Python Functions from C


The tutorial concentrated on making C functions callable from Python.  The
reverse is also useful: calling Python functions from C. This is especially the
case for libraries that support so-called «callback» functions.  If a C
interface makes use of callbacks, the equivalent Python often needs to provide a
callback mechanism to the Python programmer; the implementation will require
calling the Python callback functions from a C callback.  Other uses are also
imaginable.

Fortunately, the Python interpreter is easily called recursively, and there is a
standard interface to call a Python function.  (I won’t dwell on how to call the
Python parser with a particular string as input — if you’re interested, have a
look at the implementation of the @ref{445,,-c} command line option in
@code{Modules/main.c} from the Python source code.)

Calling a Python function is easy.  First, the Python program must somehow pass
you the Python function object.  You should provide a function (or some other
interface) to do this.  When this function is called, save a pointer to the
Python function object (be careful to @ref{974,,Py_INCREF()} it!) in a global
variable — or wherever you see fit. For example, the following function might
be part of a module definition:

@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

This function must be registered with the interpreter using the
@ref{18aa,,METH_VARARGS} flag in @ref{51bf,,PyMethodDef.ml_flags}.  The
@ref{3b1,,PyArg_ParseTuple()} function and its arguments are documented in section
@ref{51c0,,Extracting Parameters in Extension Functions}.

The macros @ref{e29,,Py_XINCREF()} and @ref{b6e,,Py_XDECREF()} increment/decrement the
reference count of an object and are safe in the presence of @code{NULL} pointers
(but note that `temp' will not be  @code{NULL} in this context).  More info on them
in section @ref{51c1,,Reference Counts}.

@geindex PyObject_CallObject (C function)

Later, when it is time to call the function, you call the C function
@ref{51c2,,PyObject_CallObject()}.  This function has two arguments, both pointers to
arbitrary Python objects: the Python function, and the argument list.  The
argument list must always be a tuple object, whose length is the number of
arguments.  To call the Python function with no arguments, pass in @code{NULL}, or
an empty tuple; to call it with one argument, pass a singleton tuple.
@ref{5ee,,Py_BuildValue()} returns a tuple when its format string consists of zero
or more format codes between parentheses.  For example:

@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{51c2,,PyObject_CallObject()} returns a Python object pointer: this is the return
value of the Python function.  @code{PyObject_CallObject()} is
«reference-count-neutral» with respect to its arguments.  In the example a new
tuple was created to serve as the argument list, which is
@ref{975,,Py_DECREF()}-ed immediately after the @code{PyObject_CallObject()}
call.

The return value of @ref{51c2,,PyObject_CallObject()} is «new»: either it is a brand
new object, or it is an existing object whose reference count has been
incremented.  So, unless you want to save it in a global variable, you should
somehow @ref{975,,Py_DECREF()} the result, even (especially!) if you are not
interested in its value.

Before you do this, however, it is important to check that the return value
isn’t @code{NULL}.  If it is, the Python function terminated by raising an exception.
If the C code that called @ref{51c2,,PyObject_CallObject()} is called from Python, it
should now return an error indication to its Python caller, so the interpreter
can print a stack trace, or the calling Python code can handle the exception.
If this is not possible or desirable, the exception should be cleared by calling
@ref{13d9,,PyErr_Clear()}.  For example:

@example
if (result == NULL)
    return NULL; /* Pass error back */
...use result...
Py_DECREF(result);
@end example

Depending on the desired interface to the Python callback function, you may also
have to provide an argument list to @ref{51c2,,PyObject_CallObject()}.  In some cases
the argument list is also provided by the Python program, through the same
interface that specified the callback function.  It can then be saved and used
in the same manner as the function object.  In other cases, you may have to
construct a new tuple to pass as the argument list.  The simplest way to do this
is to call @ref{5ee,,Py_BuildValue()}.  For example, if you want to pass an integral
event code, you might use the following code:

@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

Note the placement of @code{Py_DECREF(arglist)} immediately after the call, before
the error check!  Also note that strictly speaking this code is not complete:
@ref{5ee,,Py_BuildValue()} may run out of memory, and this should be checked.

You may also call a function with keyword arguments by using
@ref{82f,,PyObject_Call()}, which supports arguments and keyword arguments.  As in
the above example, we use @ref{5ee,,Py_BuildValue()} to construct the dictionary.

@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

@geindex PyArg_ParseTuple (C function)

@node Extracting Parameters in Extension Functions,Keyword Parameters for Extension Functions,Calling Python Functions from C,Using the C API Assorted topics
@anchor{extending/extending extracting-parameters-in-extension-functions}@anchor{51c3}@anchor{extending/extending parsetuple}@anchor{51c0}
@subsection Extracting Parameters in Extension Functions


The @ref{5196,,tutorial} uses a «@ref{18a9,,METH_O}»
function, which is limited to a single Python argument.
If you want more, you can use @ref{18aa,,METH_VARARGS} instead.
With this flag, the C function will receive a @ref{1ce,,tuple} of arguments
instead of a single object.

For unpacking the tuple, CPython provides the @ref{3b1,,PyArg_ParseTuple()}
function, declared as follows:

@example
int PyArg_ParseTuple(PyObject *arg, const char *format, ...);
@end example

The `arg' argument must be a tuple object containing an argument list passed
from Python to a C function.  The `format' argument must be a format string,
whose syntax is explained in @ref{601,,Parsing arguments and building values} in the Python/C API Reference
Manual.  The remaining arguments must be addresses of variables whose type is
determined by the format string.

For example, to receive a single Python @ref{1df,,str} object and turn it
into a C buffer, you would use @code{"s"} as the format string:

@example
const char *command;
if (!PyArg_ParseTuple(args, "s", &command)) @{
    return NULL;
@}
@end example

If an error is detected in the argument list, @code{PyArg_ParseTuple()}
returns @code{NULL} (the error indicator for functions returning object pointers);
your function may return @code{NULL}, relying on the exception set by
@ref{3b1,,PyArg_ParseTuple()}.

Note that while @ref{3b1,,PyArg_ParseTuple()} checks that the Python arguments have
the required types, it cannot check the validity of the addresses of C variables
passed to the call: if you make mistakes there, your code will probably crash or
at least overwrite random bits in memory.  So be careful!

Note that any Python object references which are provided to the caller are
`borrowed' references; do not decrement their reference count!

Some example calls:

@example
#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 Keyword Parameters for Extension Functions,Building Arbitrary Values,Extracting Parameters in Extension Functions,Using the C API Assorted topics
@anchor{extending/extending keyword-parameters-for-extension-functions}@anchor{51c4}@anchor{extending/extending parsetupleandkeywords}@anchor{51c5}
@subsection Keyword Parameters for Extension Functions


If you also want your function to accept
@ref{10cc,,keyword arguments}, use the @ref{51c6,,METH_KEYWORDS}
flag in combination with @ref{18aa,,METH_VARARGS}.
(@code{METH_KEYWORDS} can also be used with other flags; see its
documentation for the allowed combinations.)

In this case, the C function should accept a third @code{PyObject *} parameter
which will be a dictionary of keywords.
Use @ref{818,,PyArg_ParseTupleAndKeywords()} to parse the arguments to such a
function.

@geindex PyArg_ParseTupleAndKeywords (C function)

The @ref{818,,PyArg_ParseTupleAndKeywords()} function is declared as follows:

@example
int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
                                const char *format, char * const *kwlist, ...);
@end example

The `arg' and `format' parameters are identical to those of the
@ref{3b1,,PyArg_ParseTuple()} function.  The `kwdict' parameter is the dictionary of
keywords received as the third parameter from the Python runtime.  The `kwlist'
parameter is a @code{NULL}-terminated list of strings which identify the parameters;
the names are matched with the type information from `format' from left to
right.  On success, @ref{818,,PyArg_ParseTupleAndKeywords()} returns true, otherwise
it returns false and raises an appropriate exception.

@cartouche
@quotation Σημείωση 
Nested tuples cannot be parsed when using keyword arguments!  Keyword parameters
passed in which are not present in the `kwlist' will cause @ref{291,,TypeError} to
be raised.
@end quotation
@end cartouche

@geindex Philbrick@comma{} Geoff

Here is an example module which uses keywords, based on an example by 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 */
@};
@end example

@node Building Arbitrary Values,Reference Counts,Keyword Parameters for Extension Functions,Using the C API Assorted topics
@anchor{extending/extending building-arbitrary-values}@anchor{51c7}@anchor{extending/extending buildvalue}@anchor{51c8}
@subsection Building Arbitrary Values


This function is the counterpart to @ref{3b1,,PyArg_ParseTuple()}.  It is declared
as follows:

@example
PyObject *Py_BuildValue(const char *format, ...);
@end example

It recognizes a set of format units similar to the ones recognized by
@ref{3b1,,PyArg_ParseTuple()}, but the arguments (which are input to the function,
not output) must not be pointers, just values.  It returns a new Python object,
suitable for returning from a C function called from Python.

One difference with @ref{3b1,,PyArg_ParseTuple()}: while the latter requires its
first argument to be a tuple (since Python argument lists are always represented
as tuples internally), @ref{5ee,,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.

Examples (to the left the call, to the right the resulting Python value):

@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 Reference Counts,Writing Extensions in C++,Building Arbitrary Values,Using the C API Assorted topics
@anchor{extending/extending refcounts}@anchor{51c1}@anchor{extending/extending reference-counts}@anchor{51c9}
@subsection Reference Counts


In languages like C or C++, the programmer is responsible for dynamic allocation
and deallocation of memory on the heap.  In C, this is done using the functions
@code{malloc()} and @code{free()}.  In C++, the operators @code{new} and
@code{delete} are used with essentially the same meaning and we’ll restrict
the following discussion to the C case.

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.

Common causes of memory leaks are unusual paths through the code.  For instance,
a function may allocate a block of memory, do some calculation, and then free
the block again.  Now a change in the requirements for the function may add a
test to the calculation that detects an error condition and can return
prematurely from the function.  It’s easy to forget to free the allocated memory
block when taking this premature exit, especially when it is added later to the
code.  Such leaks, once introduced, often go undetected for a long time: the
error exit is taken only in a small fraction of all calls, and most modern
machines have plenty of virtual memory, so the leak only becomes apparent in a
long-running process that uses the leaking function frequently.  Therefore, it’s
important to prevent leaks from happening by having a coding convention or
strategy that minimizes this kind of errors.

Since Python makes heavy use of @code{malloc()} and @code{free()}, it needs a
strategy to avoid memory leaks as well as the use of freed memory.  The chosen
method is called `reference counting'.  The principle is simple: every
object contains a counter, which is incremented when a reference to the object
is stored somewhere, and which is decremented when a reference to it is deleted.
When the counter reaches zero, the last reference to the object has been deleted
and the object is freed.

An alternative strategy is called `automatic garbage collection'.
(Sometimes, reference counting is also referred to as a garbage collection
strategy, hence my use of «automatic» to distinguish the two.)  The big
advantage of automatic garbage collection is that the user doesn’t need to call
@code{free()} explicitly.  (Another claimed advantage is an improvement in speed
or memory usage — this is no hard fact however.)  The disadvantage is that for
C, there is no truly portable automatic garbage collector, while reference
counting can be implemented portably (as long as the functions @code{malloc()}
and @code{free()} are available — which the C Standard guarantees). Maybe some
day a sufficiently portable automatic garbage collector will be available for C.
Until then, we’ll have to live with reference counts.

While Python uses the traditional reference counting implementation, it also
offers a cycle detector that works to detect reference cycles.  This allows
applications to not worry about creating direct or indirect circular references;
these are the weakness of garbage collection implemented using only reference
counting.  Reference cycles consist of objects which contain (possibly indirect)
references to themselves, so that each object in the cycle has a reference count
which is non-zero.  Typical reference counting implementations are not able to
reclaim the memory belonging to any objects in a reference cycle, or referenced
from the objects in the cycle, even though there are no further references to
the cycle itself.

The cycle detector is able to detect garbage cycles and can reclaim them.
The @ref{63,,gc} module exposes a way to run the detector (the
@ref{44f,,collect()} function), as well as configuration
interfaces and the ability to disable the detector at runtime.

@menu
* Reference Counting in Python:: 
* Ownership Rules:: 
* Thin Ice:: 
* NULL Pointers:: 

@end menu

@node Reference Counting in Python,Ownership Rules,,Reference Counts
@anchor{extending/extending refcountsinpython}@anchor{51ca}@anchor{extending/extending reference-counting-in-python}@anchor{51cb}
@subsubsection Reference Counting in Python


There are two macros, @code{Py_INCREF(x)} and @code{Py_DECREF(x)}, which handle the
incrementing and decrementing of the reference count. @ref{975,,Py_DECREF()} also
frees the object when the count reaches zero. For flexibility, it doesn’t call
@code{free()} directly — rather, it makes a call through a function pointer in
the object’s `type object'.  For this purpose (and others), every object
also contains a pointer to its type object.

The big question now remains: when to use @code{Py_INCREF(x)} and @code{Py_DECREF(x)}?
Let’s first introduce some terms.  Nobody «owns» an object; however, you can
`own a reference' to an object.  An object’s reference count is now defined
as the number of owned references to it.  The owner of a reference is
responsible for calling @ref{975,,Py_DECREF()} when the reference is no longer
needed.  Ownership of a reference can be transferred.  There are three ways to
dispose of an owned reference: pass it on, store it, or call @code{Py_DECREF()}.
Forgetting to dispose of an owned reference creates a memory leak.

It is also possible to `borrow' @footnote{
The metaphor of «borrowing» a reference is not completely correct:
the owner still has a copy of the reference.
} a reference to an object.  The
borrower of a reference should not call @ref{975,,Py_DECREF()}.  The borrower must
not hold on to the object longer than the owner from which it was borrowed.
Using a borrowed reference after the owner has disposed of it risks using freed
memory and should be avoided completely @footnote{
Checking that the reference count is at least 1
`does not work' — the
reference count itself could be in freed memory and may thus be reused for
another object!
}.

The advantage of borrowing over owning a reference is that you don’t need to
take care of disposing of the reference on all possible paths through the code
— in other words, with a borrowed reference you don’t run the risk of leaking
when a premature exit is taken.  The disadvantage of borrowing over owning is
that there are some subtle situations where in seemingly correct code a borrowed
reference can be used after the owner from which it was borrowed has in fact
disposed of it.

A borrowed reference can be changed into an owned reference by calling
@ref{974,,Py_INCREF()}.  This does not affect the status of the owner from which the
reference was borrowed — it creates a new owned reference, and gives full
owner responsibilities (the new owner must dispose of the reference properly, as
well as the previous owner).

@node Ownership Rules,Thin Ice,Reference Counting in Python,Reference Counts
@anchor{extending/extending ownership-rules}@anchor{51cc}@anchor{extending/extending ownershiprules}@anchor{51cd}
@subsubsection Ownership Rules


Whenever an object reference is passed into or out of a function, it is part of
the function’s interface specification whether ownership is transferred with the
reference or not.

Most functions that return a reference to an object pass on ownership with the
reference.  In particular, all functions whose function it is to create a new
object, such as @ref{1dca,,PyLong_FromLong()} and @ref{5ee,,Py_BuildValue()}, pass
ownership to the receiver.  Even if the object is not actually new, you still
receive ownership of a new reference to that object.  For instance,
@code{PyLong_FromLong()} maintains a cache of popular values and can return a
reference to a cached item.

Many functions that extract objects from other objects also transfer ownership
with the reference, for instance @ref{7e6,,PyObject_GetAttrString()}.  The picture
is less clear, here, however, since a few common routines are exceptions:
@ref{51ce,,PyTuple_GetItem()}, @ref{7f5,,PyList_GetItem()}, @ref{81c,,PyDict_GetItem()}, and
@ref{81d,,PyDict_GetItemString()} all return references that you borrow from the
tuple, list or dictionary.

The function @ref{7f2,,PyImport_AddModule()} also returns a borrowed reference, even
though it may actually create the object it returns: this is possible because an
owned reference to the object is stored in @code{sys.modules}.

When you pass an object reference into another function, in general, the
function borrows the reference from you — if it needs to store it, it will use
@ref{974,,Py_INCREF()} to become an independent owner.  There are exactly two
important exceptions to this rule: @ref{51cf,,PyTuple_SetItem()} and
@ref{1adb,,PyList_SetItem()}.  These functions take over ownership of the item passed
to them — even if they fail!  (Note that @ref{51d0,,PyDict_SetItem()} and friends
don’t take over ownership — they are «normal.»)

When a C function is called from Python, it borrows references to its arguments
from the caller.  The caller owns a reference to the object, so the borrowed
reference’s lifetime is guaranteed until the function returns.  Only when such a
borrowed reference must be stored or passed on, it must be turned into an owned
reference by calling @ref{974,,Py_INCREF()}.

The object reference returned from a C function that is called from Python must
be an owned reference — ownership is transferred from the function to its
caller.

@node Thin Ice,NULL Pointers,Ownership Rules,Reference Counts
@anchor{extending/extending thin-ice}@anchor{51d1}@anchor{extending/extending thinice}@anchor{51d2}
@subsubsection Thin Ice


There are a few situations where seemingly harmless use of a borrowed reference
can lead to problems.  These all have to do with implicit invocations of the
interpreter, which can cause the owner of a reference to dispose of it.

The first and most important case to know about is using @ref{975,,Py_DECREF()} on
an unrelated object while borrowing a reference to a list item.  For instance:

@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

This function first borrows a reference to @code{list[0]}, then replaces
@code{list[1]} with the value @code{0}, and finally prints the borrowed reference.
Looks harmless, right?  But it’s not!

Let’s follow the control flow into @ref{1adb,,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. Internally,
@code{PyList_SetItem()} calls @ref{975,,Py_DECREF()} on the replaced item,
which invokes replaced item’s corresponding
@ref{51d3,,tp_dealloc} function. During
deallocation, @code{tp_dealloc} calls
@ref{e6c,,tp_finalize}, which is mapped to the
@code{__del__()} method for class instances (see 
@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/}). This entire
sequence happens synchronously within the @code{PyList_SetItem()} call.

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}.

The solution, once you know the source of the problem, is easy: temporarily
increment the reference count.  The correct version of the function reads:

@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…

The second case of problems with a borrowed reference is a variant involving
threads.  Normally, multiple threads in the Python interpreter can’t get in each
other’s way, because there is a @ref{685,,global lock}
protecting Python’s entire object space.
However, it is possible to temporarily release this lock using the macro
@ref{51d4,,Py_BEGIN_ALLOW_THREADS}, and to re-acquire it using
@ref{e4e,,Py_END_ALLOW_THREADS}.  This is common around blocking I/O calls, to
let other threads use the processor while waiting for the I/O to complete.
Obviously, the following function has the same problem as the previous one:

@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 NULL Pointers,,Thin Ice,Reference Counts
@anchor{extending/extending null-pointers}@anchor{51d5}@anchor{extending/extending nullpointers}@anchor{51d6}
@subsubsection NULL Pointers


In general, functions that take object references as arguments do not expect you
to pass them @code{NULL} pointers, and will dump core (or cause later core dumps) if
you do so.  Functions that return object references generally return @code{NULL} only
to indicate that an exception occurred.  The reason for not testing for @code{NULL}
arguments is that functions often pass the objects they receive on to other
function — if each function were to test for @code{NULL}, there would be a lot of
redundant tests and the code would run more slowly.

It is better to test for @code{NULL} only at the «source:» when a pointer that may be
@code{NULL} is received, for example, from @code{malloc()} or from a function that
may raise an exception.

The macros @ref{974,,Py_INCREF()} and @ref{975,,Py_DECREF()} do not check for @code{NULL}
pointers — however, their variants @ref{e29,,Py_XINCREF()} and @ref{b6e,,Py_XDECREF()}
do.

The macros for checking for a particular object type (@code{Pytype_Check()}) don’t
check for @code{NULL} pointers — again, there is much code that calls several of
these in a row to test an object against various different expected types, and
this would generate redundant tests.  There are no variants with @code{NULL}
checking.

The C function calling mechanism guarantees that the argument list passed to C
functions (@code{args} in the examples) is never @code{NULL} — in fact it guarantees
that it is always a tuple @footnote{
These guarantees don’t hold when you use the
«old» style calling convention —
this is still found in much existing code.
}.

It is a severe error to ever let a @code{NULL} pointer «escape» to the Python user.

@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 Writing Extensions in C++,Providing a C API for an Extension Module,Reference Counts,Using the C API Assorted topics
@anchor{extending/extending cplusplus}@anchor{51d7}@anchor{extending/extending writing-extensions-in-c}@anchor{51d8}
@subsection Writing Extensions in C++


It is possible to write extension modules in C++.  Some restrictions apply.  If
the main program (the Python interpreter) is compiled and linked by the C
compiler, global or static objects with constructors cannot be used.  This is
not a problem if the main program is linked by the C++ compiler.  Functions that
will be called by the Python interpreter (in particular, module initialization
functions) have to be declared using @code{extern "C"}. It is unnecessary to
enclose the Python header files in @code{extern "C" @{...@}} — they use this form
already if the symbol @code{__cplusplus} is defined (all recent C++ compilers
define this symbol).

@node Providing a C API for an Extension Module,,Writing Extensions in C++,Using the C API Assorted topics
@anchor{extending/extending providing-a-c-api-for-an-extension-module}@anchor{51d9}@anchor{extending/extending using-capsules}@anchor{1702}
@subsection Providing a C API for an Extension Module


Many extension modules just provide new functions and types to be used from
Python, but sometimes the code in an extension module can be useful for other
extension modules. For example, an extension module could implement a type
«collection» which works like lists without order. Just like the standard Python
list type has a C API which permits extension modules to create and manipulate
lists, this new collection type should have a set of C functions for direct
manipulation from other extension modules.

At first sight this seems easy: just write the functions (without declaring them
@code{static}, of course), provide an appropriate header file, and document
the C API. And in fact this would work if all extension modules were always
linked statically with the Python interpreter. When modules are used as shared
libraries, however, the symbols defined in one module may not be visible to
another module. The details of visibility depend on the operating system; some
systems use one global namespace for the Python interpreter and all extension
modules (Windows, for example), whereas others require an explicit list of
imported symbols at module link time (AIX is one example), or offer a choice of
different strategies (most Unices). And even if symbols are globally visible,
the module whose functions one wishes to call might not have been loaded yet!

Portability therefore requires not to make any assumptions about symbol
visibility. This means that all symbols in extension modules should be declared
@code{static}, except for the module’s initialization function, in order to
avoid name clashes with other extension modules. And it means that symbols
that `should' be accessible from
other extension modules must be exported in a different way.

Python provides a special mechanism to pass C-level information (pointers) from
one extension module to another one: Capsules. A Capsule is a Python data type
which stores a pointer (void*).  Capsules can only be created and
accessed via their C API, but they can be passed around like any other Python
object. In particular,  they can be assigned to a name in an extension module’s
namespace. Other extension modules can then import this module, retrieve the
value of this name, and then retrieve the pointer from the Capsule.

There are many ways in which Capsules can be used to export the C API of an
extension module. Each function could get its own Capsule, or all C API pointers
could be stored in an array whose address is published in a Capsule. And the
various tasks of storing and retrieving the pointers can be distributed in
different ways between the module providing the code and the client modules.

Whichever method you choose, it’s important to name your Capsules properly.
The function @ref{51da,,PyCapsule_New()} takes a name parameter
(const char*); you’re permitted to pass in a @code{NULL} name, but
we strongly encourage you to specify a name.  Properly named Capsules provide
a degree of runtime type-safety; there is no feasible way to tell one unnamed
Capsule from another.

In particular, Capsules used to expose C APIs should be given a name following
this convention:

@example
modulename.attributename
@end example

The convenience function @ref{1e07,,PyCapsule_Import()} makes it easy to
load a C API provided via a Capsule, but only if the Capsule’s name
matches this convention.  This behavior gives C API users a high degree
of certainty that the Capsule they load contains the correct C API.

The following example demonstrates an approach that puts most of the burden on
the writer of the exporting module, which is appropriate for commonly used
library modules. It stores all C API pointers (just one in the example!) in an
array of void pointers which becomes the value of a Capsule. The header
file corresponding to the module provides a macro that takes care of importing
the module and retrieving its C API pointers; client modules only have to call
this macro before accessing the C API.

The exporting module is a modification of the @code{spam} module from the
@ref{5196,,tutorial}.
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

In the beginning of the module, right after the line

@example
#include <Python.h>
@end example

two more lines must be added:

@example
#define SPAM_MODULE
#include "spammodule.h"
@end example

The @code{#define} is used to tell the header file that it is being included in the
exporting module, not a client module. Finally, the module’s @ref{d46,,mod_exec} function must take care of initializing the C API pointer array:

@example
static int
spam_module_exec(PyObject *m)
@{
    static void *PySpam_API[PySpam_API_pointers];
    PyObject *c_api_object;

    /* 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) @{
        return -1;
    @}

    return 0;
@}
@end example

Note that @code{PySpam_API} is declared @code{static}; otherwise the pointer
array would disappear when @code{PyInit_spam()} terminates!

The bulk of the work is in the header file @code{spammodule.h}, which looks
like this:

@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 @ref{d46,,mod_exec} function:

@example
static int
client_module_exec(PyObject *m)
@{
    if (import_spam() < 0) @{
        return -1;
    @}
    /* additional initialization can happen here */
    return 0;
@}
@end example

The main disadvantage of this approach is that the file @code{spammodule.h} is
rather complicated. However, the basic structure is the same for each function
that is exported, so it has to be learned only once.

Finally it should be mentioned that Capsules offer additional functionality,
which is especially useful for memory allocation and deallocation of the pointer
stored in a Capsule. The details are described in the Python/C API Reference
Manual in the section @ref{2c04,,Capsules} and in the implementation of Capsules (files
@code{Include/pycapsule.h} and @code{Objects/pycapsule.c} in the Python source
code distribution).

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Defining Extension Types Tutorial,Defining Extension Types Assorted Topics,Using the C API Assorted topics,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python
@anchor{extending/newtypes_tutorial doc}@anchor{1db5}@anchor{extending/newtypes_tutorial defining-extension-types-tutorial}@anchor{51db}@anchor{extending/newtypes_tutorial defining-new-types}@anchor{51dc}@anchor{extending/newtypes_tutorial translation-repo}@anchor{51dd}
@section Defining Extension Types: Tutorial


Python allows the writer of a C extension module to define new types that
can be manipulated from Python code, much like the built-in @ref{1df,,str}
and @ref{4d9,,list} types.  The code for all extension types follows a
pattern, but there are some details that you need to understand before you
can get started.  This document is a gentle introduction to the topic.

@menu
* The Basics:: 
* Adding data and methods to the Basic example:: 
* Providing finer control over data attributes:: 
* Supporting cyclic garbage collection:: 
* Subclassing other types:: 

@end menu

@node The Basics,Adding data and methods to the Basic example,,Defining Extension Types Tutorial
@anchor{extending/newtypes_tutorial dnt-basics}@anchor{51de}@anchor{extending/newtypes_tutorial the-basics}@anchor{51df}
@subsection The Basics


The @ref{ae3,,CPython} runtime sees all Python objects as variables of type
@ref{19b,,PyObject}*, which serves as a «base type» for all Python objects.
The @ref{19b,,PyObject} structure itself only contains the object’s
@ref{2c5,,reference count} and a pointer to the object’s «type object».
This is where the action is; the type object determines which (C) functions
get called by the interpreter when, for instance, an attribute gets looked up
on an object, a method called, or it is multiplied by another object.  These
C functions are called «type methods».

So, if you want to define a new extension type, you need to create a new type
object.

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 Σημείωση 
What we’re showing here is the traditional way of defining `static'
extension types.  It should be adequate for most uses.  The C API also
allows defining heap-allocated extension types using the
@ref{38e,,PyType_FromSpec()} function, which isn’t covered in this tutorial.
@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 int
custom_module_exec(PyObject *m)
@{
    if (PyType_Ready(&CustomType) < 0) @{
        return -1;
    @}

    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) @{
        return -1;
    @}

    return 0;
@}

static PyModuleDef_Slot custom_module_slots[] = @{
    @{Py_mod_exec, custom_module_exec@},
    // Just use this while using static types
    @{Py_mod_multiple_interpreters, Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED@},
    @{0, NULL@}
@};

static PyModuleDef custom_module = @{
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "custom",
    .m_doc = "Example module that creates an extension type.",
    .m_size = 0,
    .m_slots = custom_module_slots,
@};

PyMODINIT_FUNC
PyInit_custom(void)
@{
    return PyModuleDef_Init(&custom_module);
@}
@end example

Now that’s quite a bit to take in at once, but hopefully bits will seem familiar
from the previous chapter.  This file defines three things:


@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 define and execute the @code{custom} module: this is the
@code{PyInit_custom} function and the associated @code{custom_module} struct for
defining the module, and the @code{custom_module_exec} function to set up
a fresh module object.
@end enumerate

The first bit is:

@example
typedef struct @{
    PyObject_HEAD
@} CustomObject;
@end example

This is what a Custom object will contain.  @code{PyObject_HEAD} is mandatory
at the start of each object struct and defines a field called @code{ob_base}
of type @ref{19b,,PyObject}, containing a pointer to a type object and a
reference count (these can be accessed using the macros @ref{5f5,,Py_TYPE}
and @ref{54b,,Py_REFCNT} respectively).  The reason for the macro is to
abstract away the layout and to enable additional fields in @ref{3dc,,debug builds}.

@cartouche
@quotation Σημείωση 
There is no semicolon above after the @ref{1682,,PyObject_HEAD} macro.
Be wary of adding one by accident: some compilers will complain.
@end quotation
@end cartouche

Of course, objects generally store additional data besides the standard
@code{PyObject_HEAD} boilerplate; for example, here is the definition for
standard Python floats:

@example
typedef struct @{
    PyObject_HEAD
    double ob_fval;
@} PyFloatObject;
@end example

The second bit is the definition of the type object.

@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 Σημείωση 
We recommend using C99-style designated initializers as above, to
avoid listing all the @ref{e6b,,PyTypeObject} fields that you don’t care
about and also to avoid caring about the fields” declaration order.
@end quotation
@end cartouche

The actual definition of @ref{e6b,,PyTypeObject} in @code{object.h} has
many more @ref{d55,,fields} than the definition above.  The
remaining fields will be filled with zeros by the C compiler, and it’s
common practice to not specify them explicitly unless you need them.

We’re going to pick it apart, one field at a time:

@example
.ob_base = PyVarObject_HEAD_INIT(NULL, 0)
@end example

This line is mandatory boilerplate to initialize the @code{ob_base}
field mentioned above.

@example
.tp_name = "custom.Custom",
@end example

The name of our type.  This will appear in the default textual representation of
our objects and in some error messages, for example:

@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{bd,,pydoc} and @ref{ab,,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{25b0,,tp_itemsize} is
only used for variable-sized objects and should otherwise be zero.

@cartouche
@quotation Σημείωση 
If you want your type to be subclassable from Python, and your type has the same
@ref{d4f,,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{184e,,__bases__}, or else it will not be able to call your type’s
@ref{982,,__new__()} method without getting an error.  You can avoid this problem by
ensuring that your type has a larger value for @code{tp_basicsize} than its
base type does.  Most of the time, this will be true anyway, because either your
base type will be @ref{e4d,,object}, or else you will be adding data members to
your base type, and therefore increasing its size.
@end quotation
@end cartouche

We set the class flags to @ref{51e0,,Py_TPFLAGS_DEFAULT}.

@example
.tp_flags = Py_TPFLAGS_DEFAULT,
@end example

All types should include this constant in their flags.  It enables all of the
members defined until at least Python 3.3.  If you need further members,
you will need to OR the corresponding flags.

We provide a doc string for the type in @ref{51e1,,tp_doc}.

@example
.tp_doc = PyDoc_STR("Custom objects"),
@end example

To enable object creation, we have to provide a @ref{981,,tp_new}
handler.  This is the equivalent of the Python method @ref{982,,__new__()}, but
has to be specified explicitly.  In this case, we can just use the default
implementation provided by the API function @ref{51e2,,PyType_GenericNew()}.

@example
.tp_new = PyType_GenericNew,
@end example

Everything else in the file should be familiar, except for some code in
@code{custom_module_exec()}:

@example
if (PyType_Ready(&CustomType) < 0) @{
    return -1;
@}
@end example

This initializes the @code{Custom} type, filling in a number of members
to the appropriate default values, including @ref{51e3,,ob_type} that we initially
set to @code{NULL}.

@example
if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) @{
    return -1;
@}
@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

in a file called @code{setup.py}; then typing

@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.

That wasn’t so hard, was it?

Of course, the current Custom type is pretty uninteresting. It has no data and
doesn’t do anything. It can’t even be subclassed.

@node Adding data and methods to the Basic example,Providing finer control over data attributes,The Basics,Defining Extension Types Tutorial
@anchor{extending/newtypes_tutorial adding-data-and-methods-to-the-basic-example}@anchor{51e4}
@subsection Adding data and methods to the Basic example


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(PyObject *op)
@{
    CustomObject *self = (CustomObject *) op;
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free(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 = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
        if (self->first == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->last = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
        if (self->last == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->number = 0;
    @}
    return (PyObject *) self;
@}

static int
Custom_init(PyObject *op, PyObject *args, PyObject *kwds)
@{
    CustomObject *self = (CustomObject *) op;
    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(PyObject *op, PyObject *Py_UNUSED(dummy))
@{
    CustomObject *self = (CustomObject *) op;
    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", 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 = Custom_init,
    .tp_dealloc = Custom_dealloc,
    .tp_members = Custom_members,
    .tp_methods = Custom_methods,
@};

static int
custom_module_exec(PyObject *m)
@{
    if (PyType_Ready(&CustomType) < 0) @{
        return -1;
    @}

    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) @{
        return -1;
    @}

    return 0;
@}

static PyModuleDef_Slot custom_module_slots[] = @{
    @{Py_mod_exec, custom_module_exec@},
    @{Py_mod_multiple_interpreters, Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED@},
    @{0, NULL@}
@};

static PyModuleDef custom_module = @{
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "custom2",
    .m_doc = "Example module that creates an extension type.",
    .m_size = 0,
    .m_slots = custom_module_slots,
@};

PyMODINIT_FUNC
PyInit_custom2(void)
@{
    return PyModuleDef_Init(&custom_module);
@}
@end example

This version of the module has a number of changes.

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.

The object structure is updated accordingly:

@example
typedef struct @{
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
@} CustomObject;
@end example

Because we now have data to manage, we have to be more careful about object
allocation and deallocation.  At a minimum, we need a deallocation method:

@example
static void
Custom_dealloc(PyObject *op)
@{
    CustomObject *self = (CustomObject *) op;
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free(self);
@}
@end example

which is assigned to the @ref{51d3,,tp_dealloc} member:

@example
.tp_dealloc = Custom_dealloc,
@end example

This method first clears the reference counts of the two Python attributes.
@ref{b6e,,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{51e5,,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 Σημείωση 
The explicit cast to @code{CustomObject *} above is needed because we defined
@code{Custom_dealloc} to take a @code{PyObject *} argument, as the @code{tp_dealloc}
function pointer expects to receive a @code{PyObject *} argument.
By assigning to the @code{tp_dealloc} slot of a type, we declare
that it can only be called with instances of our @code{CustomObject}
class, so the cast to @code{(CustomObject *)} is safe.
This is object-oriented polymorphism, in C!

In existing code, or in previous versions of this tutorial,
you might see similar functions take a pointer to the subtype
object structure (@code{CustomObject*}) directly, like this:

@example
Custom_dealloc(CustomObject *self)
@{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject *) self);
@}
...
.tp_dealloc = (destructor) Custom_dealloc,
@end example

This does the same thing on all architectures that CPython
supports, but according to the C standard, it invokes
undefined behavior.
@end quotation
@end cartouche

We want to make sure that the first and last names are initialized to empty
strings, so we provide a @code{tp_new} implementation:

@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

and install it in the @ref{981,,tp_new} member:

@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{982,,__new__()} method.
It is not required to define a @code{tp_new} member, and indeed many extension
types will simply reuse @ref{51e2,,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} is passed the type being instantiated (not necessarily @code{CustomType},
if a subclass is instantiated) and any arguments passed when the type was
called, and is expected to return the instance created.  @code{tp_new} handlers
always accept positional and keyword arguments, but they often ignore the
arguments, leaving the argument handling to initializer (a.k.a. @code{tp_init}
in C or @code{__init__} in Python) methods.

@cartouche
@quotation Σημείωση 
@code{tp_new} shouldn’t call @code{tp_init} explicitly, as the interpreter
will do it itself.
@end quotation
@end cartouche

The @code{tp_new} implementation calls the @ref{51e6,,tp_alloc}
slot to allocate memory:

@example
self = (CustomObject *) type->tp_alloc(type, 0);
@end example

Since memory allocation may fail, we must check the @ref{51e6,,tp_alloc}
result against @code{NULL} before proceeding.

@cartouche
@quotation Σημείωση 
We didn’t fill the @ref{51e6,,tp_alloc} slot ourselves. Rather
@ref{b5e,,PyType_Ready()} fills it for us by inheriting it from our base class,
which is @ref{e4d,,object} by default.  Most types use the default allocation
strategy.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
If you are creating a co-operative @ref{981,,tp_new} (one
that calls a base type’s @code{tp_new} or @ref{982,,__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 @code{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{291,,TypeError}.)
@end quotation
@end cartouche

We also define an initialization function which accepts arguments to provide
initial values for our instance:

@example
static int
Custom_init(PyObject *op, PyObject *args, PyObject *kwds)
@{
    CustomObject *self = (CustomObject *) op;
    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

by filling the @ref{983,,tp_init} slot.

@example
.tp_init = Custom_init,
@end example

The @ref{983,,tp_init} slot is exposed in Python as the
@ref{2fa,,__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{ab,,pickle} module by default
doesn’t call @ref{2fa,,__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

But this would be risky.  Our type doesn’t restrict the type of the
@code{first} member, so it could be any kind of object.  It could have a
destructor that causes code to be executed that tries to access the
@code{first} member; or that destructor could detach the
@ref{1a1,,thread state} and let arbitrary code run in other
threads that accesses and modifies our object.

To be paranoid and protect ourselves against this possibility, we almost
always reassign members before decrementing their reference counts.  When
don’t we have to do this?


@itemize *

@item 
when we absolutely know that the reference count is greater than 1;

@item 
when we know that deallocation of the object @footnote{
This is true when we know that the object is a basic type, like a string or a
float.
} will neither detach
the @ref{1a1,,thread state} nor cause any calls back into our type’s code;

@item 
when decrementing a reference count in a @ref{51d3,,tp_dealloc}
handler on a type which doesn’t support cyclic garbage collection @footnote{
We relied on this in the @ref{51d3,,tp_dealloc} handler
in this example, because our type doesn’t support garbage collection.
}.
@end itemize

We want to expose our instance variables as attributes. There are a
number of ways to do that. The simplest way is to define member definitions:

@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

and put the definitions in the @ref{51e7,,tp_members} slot:

@example
.tp_members = Custom_members,
@end example

Each member definition has a member name, type, offset, access flags and
documentation string.  See the @ref{51e8,,Generic Attribute Management} section
below for details.

A disadvantage of this approach is that it doesn’t provide a way to restrict the
types of objects that can be assigned to the Python attributes.  We expect the
first and last names to be strings, but any Python objects can be assigned.
Further, the attributes can be deleted, setting the C pointers to @code{NULL}.  Even
though we can make sure the members are initialized to non-@code{NULL} values, the
members can be set to @code{NULL} if the attributes are deleted.

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(PyObject *op, PyObject *Py_UNUSED(dummy))
@{
    CustomObject *self = (CustomObject *) op;
    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.

Now that we’ve defined the method, we need to create an array of method
definitions:

@example
static PyMethodDef Custom_methods[] = @{
    @{"name", Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    @},
    @{NULL@}  /* Sentinel */
@};
@end example

(note that we used the @ref{1876,,METH_NOARGS} flag to indicate that the method
is expecting no arguments other than `self')

and assign it to the @ref{51e9,,tp_methods} slot:

@example
.tp_methods = Custom_methods,
@end example

Finally, we’ll make our type usable as a base class for subclassing.  We’ve
written our methods carefully so far so that they don’t make any assumptions
about the type of the object being created or used, so all we need to do is
to add the @ref{51ea,,Py_TPFLAGS_BASETYPE} to our class flag definition:

@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{d45,,PyModuleDef} struct, and update the full class
name in the @ref{e6b,,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 Providing finer control over data attributes,Supporting cyclic garbage collection,Adding data and methods to the Basic example,Defining Extension Types Tutorial
@anchor{extending/newtypes_tutorial providing-finer-control-over-data-attributes}@anchor{51eb}
@subsection Providing finer control over data attributes


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(PyObject *op)
@{
    CustomObject *self = (CustomObject *) op;
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free(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 = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
        if (self->first == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->last = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
        if (self->last == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->number = 0;
    @}
    return (PyObject *) self;
@}

static int
Custom_init(PyObject *op, PyObject *args, PyObject *kwds)
@{
    CustomObject *self = (CustomObject *) op;
    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(PyObject *op, void *closure)
@{
    CustomObject *self = (CustomObject *) op;
    return Py_NewRef(self->first);
@}

static int
Custom_setfirst(PyObject *op, PyObject *value, void *closure)
@{
    CustomObject *self = (CustomObject *) op;
    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(PyObject *op, void *closure)
@{
    CustomObject *self = (CustomObject *) op;
    return Py_NewRef(self->last);
@}

static int
Custom_setlast(PyObject *op, PyObject *value, void *closure)
@{
    CustomObject *self = (CustomObject *) op;
    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", Custom_getfirst, Custom_setfirst,
     "first name", NULL@},
    @{"last", Custom_getlast, Custom_setlast,
     "last name", NULL@},
    @{NULL@}  /* Sentinel */
@};

static PyObject *
Custom_name(PyObject *op, PyObject *Py_UNUSED(dummy))
@{
    CustomObject *self = (CustomObject *) op;
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
@}

static PyMethodDef Custom_methods[] = @{
    @{"name", 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 = Custom_init,
    .tp_dealloc = Custom_dealloc,
    .tp_members = Custom_members,
    .tp_methods = Custom_methods,
    .tp_getset = Custom_getsetters,
@};

static int
custom_module_exec(PyObject *m)
@{
    if (PyType_Ready(&CustomType) < 0) @{
        return -1;
    @}

    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) @{
        return -1;
    @}

    return 0;
@}

static PyModuleDef_Slot custom_module_slots[] = @{
    @{Py_mod_exec, custom_module_exec@},
    @{Py_mod_multiple_interpreters, Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED@},
    @{0, NULL@}
@};

static PyModuleDef custom_module = @{
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "custom3",
    .m_doc = "Example module that creates an extension type.",
    .m_size = 0,
    .m_slots = custom_module_slots,
@};

PyMODINIT_FUNC
PyInit_custom3(void)
@{
    return PyModuleDef_Init(&custom_module);
@}
@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(PyObject *op, void *closure)
@{
    CustomObject *self = (CustomObject *) op;
    Py_INCREF(self->first);
    return self->first;
@}

static int
Custom_setfirst(PyObject *op, PyObject *value, void *closure)
@{
    CustomObject *self = (CustomObject *) op;
    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.

We create an array of @ref{f77,,PyGetSetDef} structures:

@example
static PyGetSetDef Custom_getsetters[] = @{
    @{"first", Custom_getfirst, Custom_setfirst,
     "first name", NULL@},
    @{"last", Custom_getlast, Custom_setlast,
     "last name", NULL@},
    @{NULL@}  /* Sentinel */
@};
@end example

and register it in the @ref{51ec,,tp_getset} slot:

@example
.tp_getset = Custom_getsetters,
@end example

The last item in a @ref{f77,,PyGetSetDef} structure is the «closure» mentioned
above.  In this case, we aren’t using a closure, so we just pass @code{NULL}.

We also remove the member definitions for these attributes:

@example
static PyMemberDef Custom_members[] = @{
    @{"number", Py_T_INT, offsetof(CustomObject, number), 0,
     "custom number"@},
    @{NULL@}  /* Sentinel */
@};
@end example

We also need to update the @ref{983,,tp_init} handler to only
allow strings @footnote{
We now know that the first and last members are strings, so perhaps we
could be less careful about decrementing their reference counts, however,
we accept instances of string subclasses.  Even though deallocating normal
strings won’t call back into our objects, we can’t guarantee that deallocating
an instance of a string subclass won’t call back into our objects.
} to be passed:

@example
static int
Custom_init(PyObject *op, PyObject *args, PyObject *kwds)
@{
    CustomObject *self = (CustomObject *) op;
    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

With these changes, we can assure that the @code{first} and @code{last} members are
never @code{NULL} so we can remove checks for @code{NULL} values in almost all cases.
This means that most of the @ref{b6e,,Py_XDECREF()} calls can be converted to
@ref{975,,Py_DECREF()} calls.  The only place we can’t change these calls is in
the @code{tp_dealloc} implementation, where there is the possibility that the
initialization of these members failed in @code{tp_new}.

We also rename the module initialization function and module name in the
initialization function, as we did before, and we add an extra definition to the
@code{setup.py} file.

@node Supporting cyclic garbage collection,Subclassing other types,Providing finer control over data attributes,Defining Extension Types Tutorial
@anchor{extending/newtypes_tutorial supporting-cyclic-garbage-collection}@anchor{51ed}
@subsection Supporting cyclic garbage collection


Python has a @ref{19de,,cyclic garbage collector (GC)} that
can identify unneeded objects even when their reference counts are not zero.
This can happen when objects are involved in cycles.  For example, consider:

@example
>>> l = []
>>> l.append(l)
>>> del l
@end example

In this example, we create a list that contains itself. When we delete it, it
still has a reference from itself. Its reference count doesn’t drop to zero.
Fortunately, Python’s cyclic garbage collector will eventually figure out that
the list is garbage and free it.

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{
Also, even with our attributes restricted to strings instances, the user
could pass arbitrary @ref{1df,,str} subclasses and therefore still create
reference cycles.
}.
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(PyObject *op, visitproc visit, void *arg)
@{
    CustomObject *self = (CustomObject *) op;
    Py_VISIT(self->first);
    Py_VISIT(self->last);
    return 0;
@}

static int
Custom_clear(PyObject *op)
@{
    CustomObject *self = (CustomObject *) op;
    Py_CLEAR(self->first);
    Py_CLEAR(self->last);
    return 0;
@}

static void
Custom_dealloc(PyObject *op)
@{
    PyObject_GC_UnTrack(op);
    (void)Custom_clear(op);
    Py_TYPE(op)->tp_free(op);
@}

static PyObject *
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
@{
    CustomObject *self;
    self = (CustomObject *) type->tp_alloc(type, 0);
    if (self != NULL) @{
        self->first = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
        if (self->first == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->last = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
        if (self->last == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->number = 0;
    @}
    return (PyObject *) self;
@}

static int
Custom_init(PyObject *op, PyObject *args, PyObject *kwds)
@{
    CustomObject *self = (CustomObject *) op;
    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(PyObject *op, void *closure)
@{
    CustomObject *self = (CustomObject *) op;
    return Py_NewRef(self->first);
@}

static int
Custom_setfirst(PyObject *op, PyObject *value, void *closure)
@{
    CustomObject *self = (CustomObject *) op;
    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(PyObject *op, void *closure)
@{
    CustomObject *self = (CustomObject *) op;
    return Py_NewRef(self->last);
@}

static int
Custom_setlast(PyObject *op, PyObject *value, void *closure)
@{
    CustomObject *self = (CustomObject *) op;
    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", Custom_getfirst, Custom_setfirst,
     "first name", NULL@},
    @{"last", Custom_getlast, Custom_setlast,
     "last name", NULL@},
    @{NULL@}  /* Sentinel */
@};

static PyObject *
Custom_name(PyObject *op, PyObject *Py_UNUSED(dummy))
@{
    CustomObject *self = (CustomObject *) op;
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
@}

static PyMethodDef Custom_methods[] = @{
    @{"name", 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 = Custom_init,
    .tp_dealloc = Custom_dealloc,
    .tp_traverse = Custom_traverse,
    .tp_clear = Custom_clear,
    .tp_members = Custom_members,
    .tp_methods = Custom_methods,
    .tp_getset = Custom_getsetters,
@};

static int
custom_module_exec(PyObject *m)
@{
    if (PyType_Ready(&CustomType) < 0) @{
        return -1;
    @}

    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) @{
        return -1;
    @}

    return 0;
@}

static PyModuleDef_Slot custom_module_slots[] = @{
    @{Py_mod_exec, custom_module_exec@},
    @{Py_mod_multiple_interpreters, Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED@},
    @{0, NULL@}
@};

static PyModuleDef custom_module = @{
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "custom4",
    .m_doc = "Example module that creates an extension type.",
    .m_size = 0,
    .m_slots = custom_module_slots,
@};

PyMODINIT_FUNC
PyInit_custom4(void)
@{
    return PyModuleDef_Init(&custom_module);
@}
@end example

First, the traversal method lets the cyclic GC know about subobjects that could
participate in cycles:

@example
static int
Custom_traverse(PyObject *op, visitproc visit, void *arg)
@{
    CustomObject *self = (CustomObject *) op;
    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 provides a @ref{51ee,,Py_VISIT()} macro that automates calling visit
functions.  With @code{Py_VISIT()}, we can minimize the amount of boilerplate
in @code{Custom_traverse}:

@example
static int
Custom_traverse(PyObject *op, visitproc visit, void *arg)
@{
    CustomObject *self = (CustomObject *) op;
    Py_VISIT(self->first);
    Py_VISIT(self->last);
    return 0;
@}
@end example

@cartouche
@quotation Σημείωση 
The @ref{36b,,tp_traverse} implementation must name its
arguments exactly `visit' and `arg' in order to use @ref{51ee,,Py_VISIT()}.
@end quotation
@end cartouche

Second, we need to provide a method for clearing any subobjects that can
participate in cycles:

@example
static int
Custom_clear(PyObject *op)
@{
    CustomObject *self = (CustomObject *) op;
    Py_CLEAR(self->first);
    Py_CLEAR(self->last);
    return 0;
@}
@end example

Notice the use of the @ref{97c,,Py_CLEAR()} macro.  It is the recommended and safe
way to clear data attributes of arbitrary types while decrementing
their reference counts.  If you were to call @ref{b6e,,Py_XDECREF()} instead
on the attribute before setting it to @code{NULL}, there is a possibility
that the attribute’s destructor would call back into code that reads the
attribute again (`especially' if there is a reference cycle).

@cartouche
@quotation Σημείωση 
You could emulate @ref{97c,,Py_CLEAR()} by writing:

@example
PyObject *tmp;
tmp = self->first;
self->first = NULL;
Py_XDECREF(tmp);
@end example

Nevertheless, it is much easier and less error-prone to always
use @ref{97c,,Py_CLEAR()} when deleting an attribute.  Don’t
try to micro-optimize at the expense of robustness!
@end quotation
@end cartouche

The deallocator @code{Custom_dealloc} may call arbitrary code when clearing
attributes.  It means the circular GC can be triggered inside the function.
Since the GC assumes reference count is not zero, we need to untrack the object
from the GC by calling @ref{18a7,,PyObject_GC_UnTrack()} before clearing members.
Here is our reimplemented deallocator using @code{PyObject_GC_UnTrack()}
and @code{Custom_clear}:

@example
static void
Custom_dealloc(PyObject *op)
@{
    PyObject_GC_UnTrack(op);
    (void)Custom_clear(op);
    Py_TYPE(op)->tp_free(op);
@}
@end example

Finally, we add the @ref{39e,,Py_TPFLAGS_HAVE_GC} flag to the class flags:

@example
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
@end example

That’s pretty much it.  If we had written custom @ref{51e6,,tp_alloc} or
@ref{51e5,,tp_free} handlers, we’d need to modify them for cyclic
garbage collection.  Most extensions will use the versions automatically provided.

@node Subclassing other types,,Supporting cyclic garbage collection,Defining Extension Types Tutorial
@anchor{extending/newtypes_tutorial subclassing-other-types}@anchor{51ef}
@subsection Subclassing other types


It is possible to create new extension types that are derived from existing
types. It is easiest to inherit from the built in types, since an extension can
easily use the @ref{e6b,,PyTypeObject} it needs. It can be difficult to share
these @code{PyTypeObject} structures between extension modules.

In this example we will create a @code{SubList} type that inherits from the
built-in @ref{4d9,,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(PyObject *op, PyObject *Py_UNUSED(dummy))
@{
    SubListObject *self = (SubListObject *) op;
    self->state++;
    return PyLong_FromLong(self->state);
@}

static PyMethodDef SubList_methods[] = @{
    @{"increment", SubList_increment, METH_NOARGS,
     PyDoc_STR("increment state counter")@},
    @{NULL@},
@};

static int
SubList_init(PyObject *op, PyObject *args, PyObject *kwds)
@{
    SubListObject *self = (SubListObject *) op;
    if (PyList_Type.tp_init(op, args, kwds) < 0)
        return -1;
    self->state = 0;
    return 0;
@}

static PyTypeObject SubListType = @{
    .ob_base = 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 = SubList_init,
    .tp_methods = SubList_methods,
@};

static int
sublist_module_exec(PyObject *m)
@{
    SubListType.tp_base = &PyList_Type;
    if (PyType_Ready(&SubListType) < 0) @{
        return -1;
    @}

    if (PyModule_AddObjectRef(m, "SubList", (PyObject *) &SubListType) < 0) @{
        return -1;
    @}

    return 0;
@}

static PyModuleDef_Slot sublist_module_slots[] = @{
    @{Py_mod_exec, sublist_module_exec@},
    @{Py_mod_multiple_interpreters, Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED@},
    @{0, NULL@}
@};

static PyModuleDef sublist_module = @{
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "sublist",
    .m_doc = "Example module that creates an extension type.",
    .m_size = 0,
    .m_slots = sublist_module_slots,
@};

PyMODINIT_FUNC
PyInit_sublist(void)
@{
    return PyModuleDef_Init(&sublist_module);
@}
@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

The primary difference for derived type objects is that the base type’s
object structure must be the first value.  The base type will already include
the @ref{1682,,PyObject_HEAD()} at the beginning of its 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(PyObject *op, PyObject *args, PyObject *kwds)
@{
    SubListObject *self = (SubListObject *) op;
    if (PyList_Type.tp_init(op, args, kwds) < 0)
        return -1;
    self->state = 0;
    return 0;
@}
@end example

We see above how to call through to the @ref{2fa,,__init__()} method of the base
type.

This pattern is important when writing a type with custom
@ref{981,,tp_new} and @ref{51d3,,tp_dealloc}
members.  The @code{tp_new} handler should not actually
create the memory for the object with its @ref{51e6,,tp_alloc},
but let the base class handle it by calling its own @code{tp_new}.

The @ref{e6b,,PyTypeObject} struct supports a @ref{2567,,tp_base}
specifying the type’s concrete base class.  Due to cross-platform compiler
issues, you can’t fill that field directly with a reference to
@ref{51f0,,PyList_Type}; it should be done in the @ref{d46,,Py_mod_exec}
function:

@example
static int
sublist_module_exec(PyObject *m)
@{
    SubListType.tp_base = &PyList_Type;
    if (PyType_Ready(&SubListType) < 0) @{
        return -1;
    @}

    if (PyModule_AddObjectRef(m, "SubList", (PyObject *) &SubListType) < 0) @{
        return -1;
    @}

    return 0;
@}
@end example

Before calling @ref{b5e,,PyType_Ready()}, the type structure must have the
@ref{2567,,tp_base} slot filled in.  When we are deriving an
existing type, it is not necessary to fill out the @ref{51e6,,tp_alloc}
slot with @ref{51e2,,PyType_GenericNew()} – the allocation function from the base
type will be inherited.

After that, calling @ref{b5e,,PyType_Ready()} and adding the type object to the
module is the same as with the basic @code{Custom} examples.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Defining Extension Types Assorted Topics,Κατασκευή Επεκτάσεων C και C++,Defining Extension Types Tutorial,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python
@anchor{extending/newtypes doc}@anchor{51f1}@anchor{extending/newtypes defining-extension-types-assorted-topics}@anchor{51f2}@anchor{extending/newtypes new-types-topics}@anchor{51f3}@anchor{extending/newtypes translation-repo}@anchor{51f4}
@section Defining Extension Types: Assorted Topics

@anchor{extending/newtypes dnt-type-methods}@anchor{51f5}
This section aims to give a quick fly-by on the various type methods you can
implement and what they do.

Here is the definition of @ref{e6b,,PyTypeObject}, with some fields only used in
@ref{3dc,,debug builds} omitted:

@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 */
    PyMethodDef *tp_methods;
    PyMemberDef *tp_members;
    PyGetSetDef *tp_getset;
    // Strong reference on a heap type, borrowed reference on a static type
    PyTypeObject *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; /* no longer used */
    void *tp_subclasses;  /* for static builtin types this is an index */
    PyObject *tp_weaklist; /* not used for static builtin types */
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6.
     * If zero, the cache is invalid and must be initialized.
     */
    unsigned int tp_version_tag;

    destructor tp_finalize;
    vectorcallfunc tp_vectorcall;

    /* bitset of which type-watchers care about this type */
    unsigned char tp_watched;

    /* Number of tp_version_tag values used.
     * Set to _Py_ATTR_CACHE_UNUSED if the attribute cache is
     * disabled for this type (e.g. due to custom MRO entries).
     * Otherwise, limited to MAX_VERSIONS_PER_CLASS (defined elsewhere).
     */
    uint16_t tp_versions_used;
@} PyTypeObject;
@end example

Now that’s a `lot' of methods.  Don’t worry too much though – if you have
a type you want to define, the chances are very good that you will only
implement a handful of these.

As you probably expect by now, we’re going to go over this and give more
information about the various handlers.  We won’t go in the order they are
defined in the structure, because there is a lot of historical baggage that
impacts the ordering of the fields.  It’s often easiest to find an example
that includes the fields you need and then change the values to suit your new
type.

@example
const char *tp_name; /* For printing */
@end example

The name of the type – as mentioned in the previous chapter, this will appear in
various places, almost entirely for diagnostic purposes. Try to choose something
that will be helpful in such a situation!

@example
Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */
@end example

These fields tell the runtime how much memory to allocate when new objects of
this type are created.  Python has some built-in support for variable length
structures (think: strings, tuples) which is where the @ref{25b0,,tp_itemsize} field
comes in.  This will be dealt with later.

@example
const char *tp_doc;
@end example

Here you can put a string (or its address) that you want returned when the
Python script references @code{obj.__doc__} to retrieve the doc string.

Now we come to the basic type methods – the ones most extension types will
implement.

@menu
* Finalization and De-allocation:: 
* Object Presentation:: 
* Attribute Management:: 
* Object Comparison:: 
* Abstract Protocol Support:: 
* Weak Reference Support:: 
* More Suggestions:: 

@end menu

@node Finalization and De-allocation,Object Presentation,,Defining Extension Types Assorted Topics
@anchor{extending/newtypes finalization-and-de-allocation}@anchor{51f6}
@subsection Finalization and De-allocation


@geindex object;deallocation
@geindex deallocation@comma{} object
@geindex object;finalization
@geindex finalization@comma{} of objects

@example
destructor tp_dealloc;
@end example

This function is called when the reference count of the instance of your type is
reduced to zero and the Python interpreter wants to reclaim it.  If your type
has memory to free or other clean-up to perform, you can put it here.  The
object itself needs to be freed here as well.  Here is an example of this
function:

@example
static void
newdatatype_dealloc(PyObject *op)
@{
    newdatatypeobject *self = (newdatatypeobject *) op;
    free(self->obj_UnderlyingDatatypePtr);
    Py_TYPE(self)->tp_free(self);
@}
@end example

If your type supports garbage collection, the destructor should call
@ref{18a7,,PyObject_GC_UnTrack()} before clearing any member fields:

@example
static void
newdatatype_dealloc(PyObject *op)
@{
    newdatatypeobject *self = (newdatatypeobject *) op;
    PyObject_GC_UnTrack(op);
    Py_CLEAR(self->other_obj);
    ...
    Py_TYPE(self)->tp_free(self);
@}
@end example

@geindex PyErr_Fetch (C function)
@geindex PyErr_Restore (C function)

One important requirement of the deallocator function is that it leaves any
pending exceptions alone.  This is important since deallocators are frequently
called as the interpreter unwinds the Python stack; when the stack is unwound
due to an exception (rather than normal returns), nothing is done to protect the
deallocators from seeing that an exception has already been set.  Any actions
which a deallocator performs which may cause additional Python code to be
executed may detect that an exception has been set.  This can lead to misleading
errors from the interpreter.  The proper way to protect against this is to save
a pending exception before performing the unsafe action, and restoring it when
done.  This can be done using the @ref{63b,,PyErr_Fetch()} and
@ref{63e,,PyErr_Restore()} functions:

@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(self)->tp_free(self);
@}
@end example

@cartouche
@quotation Σημείωση 
There are limitations to what you can safely do in a deallocator function.
First, if your type supports garbage collection (using @ref{36b,,tp_traverse}
and/or @ref{51f7,,tp_clear}), some of the object’s members can have been
cleared or finalized by the time @ref{51d3,,tp_dealloc} is called.  Second, in
@code{tp_dealloc}, your object is in an unstable state: its reference
count is equal to zero.  Any call to a non-trivial object or API (as in the
example above) might end up calling @code{tp_dealloc} again, causing a
double free and a crash.

Starting with Python 3.4, it is recommended not to put any complex
finalization code in @ref{51d3,,tp_dealloc}, and instead use the new
@ref{e6c,,tp_finalize} type method.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/} explains the new finalization scheme.

@end quotation
@end cartouche

@geindex string;object representation
@geindex built-in function;repr

@node Object Presentation,Attribute Management,Finalization and De-allocation,Defining Extension Types Assorted Topics
@anchor{extending/newtypes object-presentation}@anchor{51f8}
@subsection Object Presentation


In Python, there are two ways to generate a textual representation of an object:
the @ref{45b,,repr()} function, and the @ref{1df,,str()} function.  (The @ref{131f,,print()}
function just calls @code{str()}.)  These handlers are both optional.

@example
reprfunc tp_repr;
reprfunc tp_str;
@end example

The @ref{51f9,,tp_repr} handler should return a string object containing a
representation of the instance for which it is called.  Here is a simple
example:

@example
static PyObject *
newdatatype_repr(PyObject *op)
@{
    newdatatypeobject *self = (newdatatypeobject *) op;
    return PyUnicode_FromFormat("Repr-ified_newdatatype@{@{size:%d@}@}",
                                self->obj_UnderlyingDatatypePtr->size);
@}
@end example

If no @ref{51f9,,tp_repr} handler is specified, the interpreter will supply a
representation that uses the type’s @ref{1ea6,,tp_name} and a uniquely identifying
value for the object.

The @ref{51fa,,tp_str} handler is to @ref{1df,,str()} what the @ref{51f9,,tp_repr} handler
described above is to @ref{45b,,repr()}; that is, it is called when Python code calls
@code{str()} on an instance of your object.  Its implementation is very similar
to the @code{tp_repr} function, but the resulting string is intended for human
consumption.  If @code{tp_str} is not specified, the @code{tp_repr} handler is
used instead.

Here is a simple example:

@example
static PyObject *
newdatatype_str(PyObject *op)
@{
    newdatatypeobject *self = (newdatatypeobject *) op;
    return PyUnicode_FromFormat("Stringified_newdatatype@{@{size:%d@}@}",
                                self->obj_UnderlyingDatatypePtr->size);
@}
@end example

@node Attribute Management,Object Comparison,Object Presentation,Defining Extension Types Assorted Topics
@anchor{extending/newtypes attribute-management}@anchor{51fb}
@subsection Attribute Management


For every object which can support attributes, the corresponding type must
provide the functions that control how the attributes are resolved.  There needs
to be a function which can retrieve attributes (if any are defined), and another
to set attributes (if setting attributes is allowed).  Removing an attribute is
a special case, for which the new value passed to the handler is @code{NULL}.

Python supports two pairs of attribute handlers; a type that supports attributes
only needs to implement the functions for one pair.  The difference is that one
pair takes the name of the attribute as a char*, while the other
accepts a @ref{19b,,PyObject}*.  Each type can use whichever pair makes more
sense for the implementation’s convenience.

@example
getattrfunc  tp_getattr;        /* char * version */
setattrfunc  tp_setattr;
/* ... */
getattrofunc tp_getattro;       /* PyObject * version */
setattrofunc tp_setattro;
@end example

If accessing attributes of an object is always a simple operation (this will be
explained shortly), there are generic implementations which can be used to
provide the @ref{19b,,PyObject}* version of the attribute management functions.
The actual need for type-specific attribute handlers almost completely
disappeared starting with Python 2.2, though there are many examples which have
not been updated to use some of the new generic mechanism that is available.

@menu
* Generic Attribute Management:: 
* Type-specific Attribute Management:: 

@end menu

@node Generic Attribute Management,Type-specific Attribute Management,,Attribute Management
@anchor{extending/newtypes generic-attribute-management}@anchor{51e8}@anchor{extending/newtypes id1}@anchor{51fc}
@subsubsection Generic Attribute Management


Most extension types only use `simple' attributes.  So, what makes the
attributes simple?  There are only a couple of conditions that must be met:


@enumerate 

@item 
The name of the attributes must be known when @ref{b5e,,PyType_Ready()} is
called.

@item 
No special processing is needed to record that an attribute was looked up or
set, nor do actions need to be taken based on the value.
@end enumerate

Note that this list does not place any restrictions on the values of the
attributes, when the values are computed, or how relevant data is stored.

When @ref{b5e,,PyType_Ready()} is called, it uses three tables referenced by the
type object to create @ref{21f,,descriptor}s which are placed in the dictionary of the
type object.  Each descriptor controls access to one attribute of the instance
object.  Each of the tables is optional; if all three are @code{NULL}, instances of
the type will only have attributes that are inherited from their base type, and
should leave the @ref{1c6a,,tp_getattro} and @ref{51fd,,tp_setattro} fields @code{NULL} as
well, allowing the base type to handle attributes.

The tables are declared as three fields of the type object:

@example
struct PyMethodDef *tp_methods;
struct PyMemberDef *tp_members;
struct PyGetSetDef *tp_getset;
@end example

If @ref{51e9,,tp_methods} is not @code{NULL}, it must refer to an array of
@ref{1879,,PyMethodDef} structures.  Each entry in the table is an instance of this
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{51fe,,ml_name} field of the sentinel must be @code{NULL}.

The second table is used to define attributes which map directly to data stored
in the instance.  A variety of primitive C types are supported, and access may
be read-only or read-write.  The structures in the table are defined as:

@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{21f,,descriptor} will be constructed and added to the
type which will be able to extract a value from the instance structure.  The
@ref{51ff,,type} field should contain a type code like @ref{98e,,Py_T_INT} or
@ref{98f,,Py_T_DOUBLE}; the value will be used to determine how to
convert Python values to and from C values.  The @ref{5200,,flags} field is used to
store flags which control how the attribute can be accessed: you can set it to
@ref{990,,Py_READONLY} to prevent Python code from setting it.

An interesting advantage of using the @ref{51e7,,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{2284,,__doc__} attribute.

As with the @ref{51e9,,tp_methods} table, a sentinel entry with a @ref{51fe,,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 Type-specific Attribute Management,,Generic Attribute Management,Attribute Management
@anchor{extending/newtypes type-specific-attribute-management}@anchor{5201}
@subsubsection Type-specific Attribute Management


For simplicity, only the char* version will be demonstrated here; the
type of the name parameter is the only difference between the char*
and @ref{19b,,PyObject}* flavors of the interface. This example effectively does
the same thing as the generic example above, but does not use the generic
support added in Python 2.2.  It explains how the handler functions are
called, so that if you do need to extend their functionality, you’ll understand
what needs to be done.

The @ref{5202,,tp_getattr} handler is called when the object requires an attribute
look-up.  It is called in the same situations where the @ref{8e3,,__getattr__()}
method of a class would be called.

Here is an example:

@example
static PyObject *
newdatatype_getattr(PyObject *op, char *name)
@{
    newdatatypeobject *self = (newdatatypeobject *) op;
    if (strcmp(name, "data") == 0) @{
        return PyLong_FromLong(self->data);
    @}

    PyErr_Format(PyExc_AttributeError,
                 "'%.100s' object has no attribute '%.400s'",
                 Py_TYPE(self)->tp_name, name);
    return NULL;
@}
@end example

The @ref{5203,,tp_setattr} handler is called when the @ref{256d,,__setattr__()} or
@ref{256e,,__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
@code{tp_setattr} handler should be set to @code{NULL}.

@example
static int
newdatatype_setattr(PyObject *op, char *name, PyObject *v)
@{
    PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);
    return -1;
@}
@end example

@node Object Comparison,Abstract Protocol Support,Attribute Management,Defining Extension Types Assorted Topics
@anchor{extending/newtypes object-comparison}@anchor{5204}
@subsection Object Comparison


@example
richcmpfunc tp_richcompare;
@end example

The @ref{5205,,tp_richcompare} handler is called when comparisons are needed.  It is
analogous to the @ref{25a3,,rich comparison methods}, like
@code{__lt__()}, and also called by @ref{5206,,PyObject_RichCompare()} and
@ref{1f7e,,PyObject_RichCompareBool()}.

This function is called with two Python objects and the operator as arguments,
where the operator is one of @code{Py_EQ}, @code{Py_NE}, @code{Py_LE}, @code{Py_GE},
@code{Py_LT} or @code{Py_GT}.  It should compare the two objects with respect to the
specified operator and return @code{Py_True} or @code{Py_False} if the comparison is
successful, @code{Py_NotImplemented} to indicate that comparison is not
implemented and the other object’s comparison method should be tried, or @code{NULL}
if an exception was set.

Here is a sample implementation, for a datatype that is considered equal if the
size of an internal pointer is equal:

@example
static PyObject *
newdatatype_richcmp(PyObject *lhs, PyObject *rhs, int op)
@{
    newdatatypeobject *obj1 = (newdatatypeobject *) lhs;
    newdatatypeobject *obj2 = (newdatatypeobject *) rhs;
    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;
    return Py_NewRef(result);
 @}
@end example

@node Abstract Protocol Support,Weak Reference Support,Object Comparison,Defining Extension Types Assorted Topics
@anchor{extending/newtypes abstract-protocol-support}@anchor{5207}
@subsection Abstract Protocol Support


Python supports a variety of `abstract' “protocols;” the specific interfaces
provided to use these interfaces are documented in @ref{5208,,Abstract Objects Layer}.

A number of these abstract interfaces were defined early in the development of
the Python implementation.  In particular, the number, mapping, and sequence
protocols have been part of Python since the beginning.  Other protocols have
been added over time.  For protocols which depend on several handler routines
from the type implementation, the older protocols have been defined as optional
blocks of handlers referenced by the type object.  For newer protocols there are
additional slots in the main type object, with a flag bit being set to indicate
that the slots are present and should be checked by the interpreter.  (The flag
bit does not indicate that the slot values are non-@code{NULL}. The flag may be set
to indicate the presence of a slot, but a slot may still be unfilled.)

@example
PyNumberMethods   *tp_as_number;
PySequenceMethods *tp_as_sequence;
PyMappingMethods  *tp_as_mapping;
@end example

If you wish your object to be able to act like a number, a sequence, or a
mapping object, then you place the address of a structure that implements the C
type @ref{17c0,,PyNumberMethods}, @ref{5209,,PySequenceMethods}, or
@ref{520a,,PyMappingMethods}, respectively. It is up to you to fill in this
structure with appropriate values. You can find examples of the use of each of
these in the @code{Objects} directory of the Python source distribution.

@example
hashfunc tp_hash;
@end example

This function, if you choose to provide it, should return a hash number for an
instance of your data type. Here is a simple example:

@example
static Py_hash_t
newdatatype_hash(PyObject *op)
@{
    newdatatypeobject *self = (newdatatypeobject *) op;
    Py_hash_t result;
    result = self->some_size + 32767 * self->some_number;
    if (result == -1) @{
        result = -2;
    @}
    return result;
@}
@end example

@ref{1608,,Py_hash_t} is a signed integer type with a platform-varying width.
Returning @code{-1} from @ref{520b,,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

This function is called when an instance of your data type is «called», for
example, if @code{obj1} is an instance of your data type and the Python script
contains @code{obj1('hello')}, the @ref{962,,tp_call} handler is invoked.

This function takes three arguments:


@enumerate 

@item 
`self' is the instance of the data type which is the subject of the call.
If the call is @code{obj1('hello')}, then `self' is @code{obj1}.

@item 
`args' is a tuple containing the arguments to the call.  You can use
@ref{3b1,,PyArg_ParseTuple()} to extract the arguments.

@item 
`kwds' is a dictionary of keyword arguments that were passed. If this is
non-@code{NULL} and you support keyword arguments, use
@ref{818,,PyArg_ParseTupleAndKeywords()} to extract the arguments.  If you
do not want to support keyword arguments and this is non-@code{NULL}, raise a
@ref{291,,TypeError} with a message saying that keyword arguments are not supported.
@end enumerate

Here is a toy @code{tp_call} implementation:

@example
static PyObject *
newdatatype_call(PyObject *op, PyObject *args, PyObject *kwds)
@{
    newdatatypeobject *self = (newdatatypeobject *) op;
    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",
        self->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{1891,,tp_iter} corresponds
to the Python @ref{102d,,__iter__()} method, while @ref{1892,,tp_iternext}
corresponds to the Python @ref{1672,,__next__()} method.

Any @ref{15ce,,iterable} object must implement the @ref{1891,,tp_iter}
handler, which must return an @ref{6ce,,iterator} object.  Here the same guidelines
apply as for Python classes:


@itemize *

@item 
For collections (such as lists and tuples) which can support multiple
independent iterators, a new iterator should be created and returned by
each call to @ref{1891,,tp_iter}.

@item 
Objects which can only be iterated over once (usually due to side effects of
iteration, such as file objects) can implement @ref{1891,,tp_iter}
by returning a new reference to themselves – and should also therefore
implement the @ref{1892,,tp_iternext}  handler.
@end itemize

Any @ref{6ce,,iterator} object should implement both @ref{1891,,tp_iter}
and @ref{1892,,tp_iternext}.  An iterator’s
@code{tp_iter} handler should return a new reference
to the iterator.  Its @code{tp_iternext} handler should
return a new reference to the next object in the iteration, if there is one.
If the iteration has reached the end, @code{tp_iternext}
may return @code{NULL} without setting an exception, or it may set
@ref{fba,,StopIteration} `in addition' to returning @code{NULL}; avoiding
the exception can yield slightly better performance.  If an actual error
occurs, @code{tp_iternext} should always set an exception
and return @code{NULL}.

@node Weak Reference Support,More Suggestions,Abstract Protocol Support,Defining Extension Types Assorted Topics
@anchor{extending/newtypes weak-reference-support}@anchor{520c}@anchor{extending/newtypes weakref-support}@anchor{2be0}
@subsection Weak Reference Support


One of the goals of Python’s weak reference implementation is to allow any type
to participate in the weak reference mechanism without incurring the overhead on
performance-critical objects (such as numbers).


@subsubheading Δείτε επίσης


Documentation for the @ref{11d,,weakref} module.


For an object to be weakly referenceable, the extension type must set the
@code{Py_TPFLAGS_MANAGED_WEAKREF} bit of the @ref{1e68,,tp_flags}
field. The legacy @ref{d50,,tp_weaklistoffset} field should
be left as zero.

If this flag is set, @ref{39e,,Py_TPFLAGS_HAVE_GC} should also be set.

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{97a,,PyObject_ClearWeakRefs()}):

@example
static void
Trivial_dealloc(PyObject *op)
@{
    /* Clear weakrefs first before calling any destructors */
    PyObject_ClearWeakRefs(op);
    /* ... remainder of destruction code omitted for brevity ... */
    Py_TYPE(op)->tp_free(op);
@}
@end example

@node More Suggestions,,Weak Reference Support,Defining Extension Types Assorted Topics
@anchor{extending/newtypes more-suggestions}@anchor{520d}
@subsection More Suggestions


In order to learn how to implement any specific method for your new data type,
get the @ref{ae3,,CPython} source code.  Go to the @code{Objects} directory,
then search the C source files for @code{tp_} plus the function you want
(for example, @code{tp_richcompare}).  You will find examples of the function
you want to implement.

When you need to verify that an object is a concrete instance of the type you
are implementing, use the @ref{1eab,,PyObject_TypeCheck()} function.  A sample of
its use might be something like the following:

@example
if (!PyObject_TypeCheck(some_object, &MyType)) @{
    PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");
    return NULL;
@}
@end example


@subsubheading Δείτε επίσης



@table @asis

@item Download CPython source releases.

@indicateurl{https://www.python.org/downloads/source/}

@item The CPython project on GitHub, where the CPython source code is developed.

@indicateurl{https://github.com/python/cpython}
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Κατασκευή Επεκτάσεων C και C++,Building C and C++ Extensions on Windows,Defining Extension Types Assorted Topics,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python
@anchor{extending/building doc}@anchor{520e}@anchor{extending/building building}@anchor{520f}@anchor{extending/building building-c-and-c-extensions}@anchor{5210}@anchor{extending/building translation-repo}@anchor{5211}
@section Κατασκευή Επεκτάσεων C και C++


Μια επέκταση C για τη CPython είναι μια κοινόχρηστη βιβλιοθήκη (π.χ. ένα αρχείο @code{.so} στο Linux, @code{.pyd} στα Windows), η οποία εξάγει μια `συνάρτηση αρχικοποίησης'.

Δείτε το @ref{5212,,Defining extension modules} για περισσότερες λεπτομέρειες.
@anchor{extending/building install-index}@anchor{12a7}
@menu
* Κατασκευή Επεκτάσεων C και C++ με το setuptools:: 

@end menu

@node Κατασκευή Επεκτάσεων C και C++ με το setuptools,,,Κατασκευή Επεκτάσεων C και C++
@anchor{extending/building building-c-and-c-extensions-with-setuptools}@anchor{5213}@anchor{extending/building setuptools-index}@anchor{12a8}
@subsection Κατασκευή Επεκτάσεων C και C++ με το setuptools


Η κατασκευή, η συσκευασία και η διανομή modules επέκτασης γίνεται καλύτερα με εργαλεία τρίτων και είναι εκτός πεδίου εφαρμογής αυτού του εγγράφου. Ένα κατάλληλο εργαλείο είναι το Setuptools, η τεκμηρίωση του οποίου βρίσκεται στη διεύθυνση @indicateurl{https://setuptools.pypa.io/en/latest/setuptools.html}.

Το module @ref{3c,,distutils}, η οποία περιλαμβανόταν στην τυπική βιβλιοθήκη μέχρι την Python 3.12, διατηρείται πλέον ως μέρος του Setuptools.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Building C and C++ Extensions on Windows,Embedding Python in Another Application,Κατασκευή Επεκτάσεων C και C++,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python
@anchor{extending/windows doc}@anchor{5214}@anchor{extending/windows building-c-and-c-extensions-on-windows}@anchor{5215}@anchor{extending/windows building-on-windows}@anchor{2415}@anchor{extending/windows translation-repo}@anchor{5216}
@section Building C and C++ Extensions on Windows


This chapter briefly explains how to create a Windows extension module for
Python using Microsoft Visual C++, and follows with more detailed background
information on how it works.  The explanatory material is useful for both the
Windows programmer learning to build Python extensions and the Unix programmer
interested in producing software which can be successfully built on both Unix
and Windows.

Module authors are encouraged to use the distutils approach for building
extension modules, instead of the one described in this section. You will still
need the C compiler that was used to build Python; typically Microsoft Visual
C++.

@cartouche
@quotation Σημείωση 
This chapter mentions a number of filenames that include an encoded Python
version number.  These filenames are represented with the version number shown
as @code{XY}; in practice, @code{'X'} will be the major version number and @code{'Y'}
will be the minor version number of the Python release you’re working with.  For
example, if you are using Python 2.2.1, @code{XY} will actually be @code{22}.
@end quotation
@end cartouche

@menu
* A Cookbook Approach:: 
* Differences Between Unix and Windows:: 
* Using DLLs in Practice:: 

@end menu

@node A Cookbook Approach,Differences Between Unix and Windows,,Building C and C++ Extensions on Windows
@anchor{extending/windows a-cookbook-approach}@anchor{5217}@anchor{extending/windows win-cookbook}@anchor{5218}
@subsection A Cookbook Approach


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{12a8,,Κατασκευή Επεκτάσεων C και C++ με το 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/main/PCbuild/winsound.vcxproj} standard library module.

@node Differences Between Unix and Windows,Using DLLs in Practice,A Cookbook Approach,Building C and C++ Extensions on Windows
@anchor{extending/windows differences-between-unix-and-windows}@anchor{5219}@anchor{extending/windows dynamic-linking}@anchor{521a}
@subsection Differences Between Unix and Windows


Unix and Windows use completely different paradigms for run-time loading of
code.  Before you try to build a module that can be dynamically loaded, be aware
of how your system works.

In Unix, a shared object (@code{.so}) file contains code to be used by the
program, and also the names of functions and data that it expects to find in the
program.  When the file is joined to the program, all references to those
functions and data in the file’s code are changed to point to the actual
locations in the program where the functions and data are placed in memory.
This is basically a link operation.

In Windows, a dynamic-link library (@code{.dll}) file has no dangling
references.  Instead, an access to functions or data goes through a lookup
table.  So the DLL code does not have to be fixed up at runtime to refer to the
program’s memory; instead, the code already uses the DLL’s lookup table, and the
lookup table is modified at runtime to point to the functions and data.

In Unix, there is only one type of library file (@code{.a}) which contains code
from several object files (@code{.o}).  During the link step to create a shared
object file (@code{.so}), the linker may find that it doesn’t know where an
identifier is defined.  The linker will look for it in the object files in the
libraries; if it finds it, it will include all the code from that object file.

In Windows, there are two types of library, a static library and an import
library (both called @code{.lib}).  A static library is like a Unix @code{.a}
file; it contains code to be included as necessary. An import library is
basically used only to reassure the linker that a certain identifier is legal,
and will be present in the program when the DLL is loaded.  So the linker uses
the information from the import library to build the lookup table for using
identifiers that are not included in the DLL.  When an application or a DLL is
linked, an import library may be generated, which will need to be used for all
future DLLs that depend on the symbols in the application or DLL.

Suppose you are building two dynamic-load modules, B and C, which should share
another block of code A.  On Unix, you would `not' pass @code{A.a} to the
linker for @code{B.so} and @code{C.so}; that would cause it to be included
twice, so that B and C would each have their own copy.  In Windows, building
@code{A.dll} will also build @code{A.lib}.  You `do' pass @code{A.lib} to the
linker for B and C.  @code{A.lib} does not contain code; it just contains
information which will be used at runtime to access A’s code.

In Windows, using an import library is sort of like using @code{import spam}; it
gives you access to spam’s names, but does not create a separate copy.  On Unix,
linking with a library is more like @code{from spam import *}; it does create a
separate copy.

@geindex Py_NO_LINK_LIB (C macro)
@anchor{extending/windows c Py_NO_LINK_LIB}@anchor{657}
@deffn {C Μακροεντολή} Py_NO_LINK_LIB

Turn off the implicit, @code{#pragma}-based linkage with the Python
library, performed inside CPython header files.


Added in version 3.14.

@end deffn

@node Using DLLs in Practice,,Differences Between Unix and Windows,Building C and C++ Extensions on Windows
@anchor{extending/windows using-dlls-in-practice}@anchor{521b}@anchor{extending/windows win-dlls}@anchor{521c}
@subsection Using DLLs in Practice


Windows Python is built in Microsoft Visual C++; using other compilers may or
may not work.  The rest of this section is MSVC++ specific.

When creating DLLs in Windows, you can use the CPython library in two ways:


@enumerate 

@item 
By default, inclusion of @code{PC/pyconfig.h} directly or via
@code{Python.h} triggers an implicit, configure-aware link with the
library.  The header file chooses @code{pythonXY_d.lib} for Debug,
@code{pythonXY.lib} for Release, and @code{pythonX.lib} for Release with
the @ref{521d,,Limited API} enabled.

To build two DLLs, spam and ni (which uses C functions found in spam), you
could use these commands:

@example
cl /LD /I/python/include spam.c
cl /LD /I/python/include ni.c spam.lib
@end example

The first command created three files: @code{spam.obj}, @code{spam.dll}
and @code{spam.lib}.  @code{Spam.dll} does not contain any Python
functions (such as @ref{3b1,,PyArg_ParseTuple()}), but it does know how to find
the Python code thanks to the implicitly linked @code{pythonXY.lib}.

The second command created @code{ni.dll} (and @code{.obj} and
@code{.lib}), which knows how to find the necessary functions from spam,
and also from the Python executable.

@item 
Manually by defining @ref{657,,Py_NO_LINK_LIB} macro before including
@code{Python.h}. You must pass @code{pythonXY.lib} to the linker.

To build two DLLs, spam and ni (which uses C functions found in spam), you
could use these commands:

@example
cl /LD /DPy_NO_LINK_LIB /I/python/include spam.c ../libs/pythonXY.lib
cl /LD /DPy_NO_LINK_LIB /I/python/include ni.c spam.lib ../libs/pythonXY.lib
@end example

The first command created three files: @code{spam.obj}, @code{spam.dll}
and @code{spam.lib}.  @code{Spam.dll} does not contain any Python
functions (such as @ref{3b1,,PyArg_ParseTuple()}), but it does know how to find
the Python code thanks to @code{pythonXY.lib}.

The second command created @code{ni.dll} (and @code{.obj} and
@code{.lib}), which knows how to find the necessary functions from spam,
and also from the Python executable.
@end enumerate

Not every identifier is exported to the lookup table.  If you want any other
modules (including Python) to be able to see your identifiers, you have to say
@code{_declspec(dllexport)}, as in @code{void _declspec(dllexport) initspam(void)} or
@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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Embedding Python in Another Application,Προτεινόμενα εργαλεία τρίτων,Building C and C++ Extensions on Windows,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python
@anchor{extending/embedding doc}@anchor{521e}@anchor{extending/embedding embedding}@anchor{244c}@anchor{extending/embedding embedding-python-in-another-application}@anchor{521f}@anchor{extending/embedding translation-repo}@anchor{5220}
@section Embedding Python in Another Application


The previous chapters discussed how to extend Python, that is, how to extend the
functionality of Python by attaching a library of C functions to it.  It is also
possible to do it the other way around: enrich your C/C++ application by
embedding Python in it.  Embedding provides your application with the ability to
implement some of the functionality of your application in Python rather than C
or C++. This can be used for many purposes; one example would be to allow users
to tailor the application to their needs by writing some scripts in Python.  You
can also use it yourself if some of the functionality can be written in Python
more easily.

Embedding Python is similar to extending it, but not quite.  The difference is
that when you extend Python, the main program of the application is still the
Python interpreter, while if you embed Python, the main program may have nothing
to do with Python — instead, some parts of the application occasionally call
the Python interpreter to run some Python code.

So if you are embedding Python, you are providing your own main program.  One of
the things this main program has to do is initialize the Python interpreter.  At
the very least, you have to call the function @ref{673,,Py_Initialize()}.  There are
optional calls to pass command line arguments to Python.  Then later you can
call the interpreter from any part of the application.

There are several different ways to call the interpreter: you can pass a string
containing Python statements to @ref{5221,,PyRun_SimpleString()}, or you can pass a
stdio file pointer and a file name (for identification in error messages only)
to @ref{5222,,PyRun_SimpleFile()}.  You can also call the lower-level operations
described in the previous chapters to construct and use Python objects.


@subsubheading Δείτε επίσης



@table @asis

@item @ref{21ab,,Python/C API reference manual}

The details of Python’s C interface are given in this manual. A great deal of
necessary information can be found here.
@end table


@menu
* Very High Level Embedding:: 
* Beyond Very High Level Embedding; An overview: Beyond Very High Level Embedding An overview. 
* Pure Embedding:: 
* Extending Embedded Python:: 
* Embedding Python in C++:: 
* Compiling and Linking under Unix-like systems:: 

@end menu

@node Very High Level Embedding,Beyond Very High Level Embedding An overview,,Embedding Python in Another Application
@anchor{extending/embedding high-level-embedding}@anchor{5223}@anchor{extending/embedding very-high-level-embedding}@anchor{5224}
@subsection Very High Level Embedding


The simplest form of embedding Python is the use of the very high level
interface. This interface is intended to execute a Python script without needing
to interact with the application directly. This can for example be used to
perform some operation on a file.

@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 Σημείωση 
@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{81f,,Strings and buffers} for a description of this macro.
@end quotation
@end cartouche

Setting @ref{608,,PyConfig.program_name} should be called before
@ref{60a,,Py_InitializeFromConfig()} to inform the interpreter about paths to Python run-time
libraries.  Next, the Python interpreter is initialized with
@ref{673,,Py_Initialize()}, followed by the execution of a hard-coded Python script
that prints the date and time.  Afterwards, the @ref{10cf,,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{5222,,PyRun_SimpleFile()} function, which saves you the
trouble of allocating memory space and loading the file contents.

@node Beyond Very High Level Embedding An overview,Pure Embedding,Very High Level Embedding,Embedding Python in Another Application
@anchor{extending/embedding beyond-very-high-level-embedding-an-overview}@anchor{5225}@anchor{extending/embedding lower-level-embedding}@anchor{5226}
@subsection Beyond Very High Level Embedding: An overview


The high level interface gives you the ability to execute arbitrary pieces of
Python code from your application, but exchanging data values is quite
cumbersome to say the least. If you want that, you should use lower level calls.
At the cost of having to write more C code, you can achieve almost anything.

It should be noted that extending Python and embedding Python is quite the same
activity, despite the different intent. Most topics discussed in the previous
chapters are still valid. To show this, consider what the extension code from
Python to C really does:


@enumerate 

@item 
Convert data values from Python to C,

@item 
Perform a function call to a C routine using the converted values, and

@item 
Convert the data values from the call from C to Python.
@end enumerate

When embedding Python, the interface code does:


@enumerate 

@item 
Convert data values from C to Python,

@item 
Perform a function call to a Python interface routine using the converted
values, and

@item 
Convert the data values from the call from Python to C.
@end enumerate

As you can see, the data conversion steps are simply swapped to accommodate the
different direction of the cross-language transfer. The only difference is the
routine that you call between both data conversions. When extending, you call a
C routine, when embedding, you call a Python routine.

This chapter will not discuss how to convert data from Python to C and vice
versa.  Also, proper use of references and dealing with errors is assumed to be
understood.  Since these aspects do not differ from extending the interpreter,
you can refer to earlier chapters for the required information.

@node Pure Embedding,Extending Embedded Python,Beyond Very High Level Embedding An overview,Embedding Python in Another Application
@anchor{extending/embedding id1}@anchor{5227}@anchor{extending/embedding pure-embedding}@anchor{5228}
@subsection Pure Embedding


The first program aims to execute a function in a Python script. Like in the
section about the very high level interface, the Python interpreter does not
directly interact with the application (but that will change in the next
section).

The code to run a function defined in a Python script is:

@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

This code loads a Python script using @code{argv[1]}, and calls the function named
in @code{argv[2]}.  Its integer arguments are the other values of the @code{argv}
array.  If you @ref{5229,,compile and link} this program (let’s call
the finished executable @code{call}), and use it to execute a Python
script, such as:

@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

then the result should be:

@example
$ call multiply multiply 3 2
Will compute 3 times 2
Result of call: 6
@end example

Although the program is quite large for its functionality, most of the code is
for data conversion between Python and C, and for error reporting.  The
interesting part with respect to embedding Python starts with

@example
Py_Initialize();
pName = PyUnicode_DecodeFSDefault(argv[1]);
/* Error checking of pName left out */
pModule = PyImport_Import(pName);
@end example

After initializing the interpreter, the script is loaded using
@ref{179e,,PyImport_Import()}.  This routine needs a Python string as its argument,
which is constructed using the @ref{1c8e,,PyUnicode_DecodeFSDefault()} data
conversion routine.

@example
pFunc = PyObject_GetAttrString(pModule, argv[2]);
/* pFunc is a new reference */

if (pFunc && PyCallable_Check(pFunc)) @{
    ...
@}
Py_XDECREF(pFunc);
@end example

Once the script is loaded, the name we’re looking for is retrieved using
@ref{7e6,,PyObject_GetAttrString()}.  If the name exists, and the object returned is
callable, you can safely assume that it is a function.  The program then
proceeds by constructing a tuple of arguments as normal.  The call to the Python
function is then made with:

@example
pValue = PyObject_CallObject(pFunc, pArgs);
@end example

Upon return of the function, @code{pValue} is either @code{NULL} or it contains a
reference to the return value of the function.  Be sure to release the reference
after examining the value.

@node Extending Embedded Python,Embedding Python in C++,Pure Embedding,Embedding Python in Another Application
@anchor{extending/embedding extending-embedded-python}@anchor{522a}@anchor{extending/embedding extending-with-embedding}@anchor{522b}
@subsection Extending Embedded Python


Until now, the embedded Python interpreter had no access to functionality from
the application itself.  The Python API allows this by extending the embedded
interpreter.  That is, the embedded interpreter gets extended with routines
provided by the application. While it sounds complex, it is not so bad.  Simply
forget for a while that the application starts the Python interpreter.  Instead,
consider the application to be a set of subroutines, and write some glue code
that gives Python access to those routines, just like you would write a normal
Python extension.  For example:

@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 emb_module_methods[] = @{
    @{"numargs", emb_numargs, METH_VARARGS,
     "Return the number of arguments received by the process."@},
    @{NULL, NULL, 0, NULL@}
@};

static struct PyModuleDef emb_module = @{
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "emb",
    .m_size = 0,
    .m_methods = emb_module_methods,
@};

static PyObject*
PyInit_emb(void)
@{
    return PyModuleDef_Init(&emb_module);
@}
@end example

Insert the above code just above the @code{main()} function. Also, insert the
following two statements before the call to @ref{673,,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

In a real application, the methods will expose an API of the application to
Python.

@c TODO: threads, code examples do not really behave well if errors happen
@c (what to watch out for)

@node Embedding Python in C++,Compiling and Linking under Unix-like systems,Extending Embedded Python,Embedding Python in Another Application
@anchor{extending/embedding embedding-python-in-c}@anchor{522c}@anchor{extending/embedding embeddingincplusplus}@anchor{522d}
@subsection Embedding Python in C++


It is also possible to embed Python in a C++ program; precisely how this is done
will depend on the details of the C++ system used; in general you will need to
write the main program in C++, and use the C++ compiler to compile and link your
program.  There is no need to recompile Python itself using C++.

@node Compiling and Linking under Unix-like systems,,Embedding Python in C++,Embedding Python in Another Application
@anchor{extending/embedding compiling}@anchor{5229}@anchor{extending/embedding compiling-and-linking-under-unix-like-systems}@anchor{522e}
@subsection Compiling and Linking under Unix-like systems


It is not necessarily trivial to find the right flags to pass to your
compiler (and linker) in order to embed the Python interpreter into your
application, particularly because Python needs to load library modules
implemented as C dynamic extensions (@code{.so} files) linked against
it.

To find out the required compiler and linker flags, you can execute the
@code{python`X.Y'-config} script which is generated as part of the
installation process (a @code{python3-config} script may also be
available).  This script has several options, of which the following will
be directly useful to you:


@itemize *

@item 
@code{pythonX.Y-config --cflags} will give you the recommended flags when
compiling:

@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} will give you the recommended flags
when linking:

@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 Σημείωση 
To avoid confusion between several Python installations (and especially
between the system Python and your own compiled Python), it is recommended
that you use the absolute path to @code{python`X.Y'-config}, as in the above
example.
@end quotation
@end cartouche

If this procedure doesn’t work for you (it is not guaranteed to work for
all Unix-like platforms; however, we welcome @ref{522f,,bug reports})
you will have to read your system’s documentation about dynamic linking and/or
examine Python’s @code{Makefile} (use @ref{4c53,,sysconfig.get_makefile_filename()}
to find its location) and compilation
options.  In this case, the @ref{e4,,sysconfig} module is a useful tool to
programmatically extract the configuration values that you will want to
combine together.  For example:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Προτεινόμενα εργαλεία τρίτων,C API Tutorial,Embedding Python in Another Application,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python
@anchor{extending/index recommended-third-party-tools}@anchor{5230}
@section Προτεινόμενα εργαλεία τρίτων


This document only covers the basic tools for creating extensions provided
as part of this version of CPython. Some @ref{5198,,third party tools} offer both simpler and more sophisticated approaches to creating
C and C++ extensions for Python.

While this document is aimed at extension authors, it should also be helpful to
the authors of such tools.
For example, the tutorial module can serve as a simple test case for a build
tool or sample expected output of a code generator.

@node C API Tutorial,Guides for intermediate topics,Προτεινόμενα εργαλεία τρίτων,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python
@anchor{extending/index c-api-tutorial}@anchor{5231}
@section C API Tutorial


This tutorial describes how to write a simple module in C or C++,
using the Python C API – that is, using the basic tools provided
as part of this version of CPython.


@enumerate 

@item 
@ref{5196,,Your first C API extension module}
@end enumerate

@node Guides for intermediate topics,Ενσωμάτωση του χρόνου εκτέλεσης της CPython σε μεγαλύτερη εφαρμογή,C API Tutorial,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python
@anchor{extending/index guides-for-intermediate-topics}@anchor{5232}
@section Guides for intermediate topics


Αυτό το μέρος του οδηγού καλύπτει τη δημιουργία επεκτάσεων σε C και C++ χωρίς τη βοήθεια εργαλείων τρίτων. Απευθύνεται κυρίως σε δημιουργούς αυτών των εργαλείων, παρά ως προτεινόμενη μέθοδος για τη δημιουργία δικών σας επεκτάσεων σε C.


@itemize *

@item 
@ref{51b0,,Using the C API; Assorted topics}

@item 
@ref{51dc,,Defining Extension Types; Tutorial}

@item 
@ref{51f3,,Defining Extension Types; Assorted Topics}

@item 
@ref{520f,,Κατασκευή Επεκτάσεων C και C++}

@item 
@ref{2415,,Building C and C++ Extensions on Windows}
@end itemize

@node Ενσωμάτωση του χρόνου εκτέλεσης της CPython σε μεγαλύτερη εφαρμογή,,Guides for intermediate topics,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python
@anchor{extending/index embedding-the-cpython-runtime-in-a-larger-application}@anchor{5233}
@section Ενσωμάτωση του χρόνου εκτέλεσης της CPython σε μεγαλύτερη εφαρμογή


Μερικές φορές, αντί να δημιουργήσουμε μια επέκταση που εκτελείται μέσα στον διερμηνέα της Python ως κύρια εφαρμογή, είναι προτιμότερο να ενσωματώσουμε τον χρόνο εκτέλεσης της CPython σε μια μεγαλύτερη εφαρμογή. Αυτή η ενότητα καλύπτει μερικές λεπτομέρειες για το πώς να το κάνετε αυτό με επιτυχία.


@itemize *

@item 
@ref{244c,,Embedding Python in Another Application}
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python/C API reference manual,Installing Python modules,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python,Top
@anchor{c-api/index doc}@anchor{5234}@anchor{c-api/index c-api-index}@anchor{21ab}@anchor{c-api/index python-c-api-reference-manual}@anchor{5235}@anchor{c-api/index translation-repo}@anchor{5236}
@chapter Python/C API reference manual


This manual documents the API used by C and C++ programmers who want to write
extension modules or embed Python.  It is a companion to @ref{21aa,,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python},
which describes the general principles of extension writing but does not
document the API functions in detail.

@menu
* Introduction: Introduction<12>. 
* C API and ABI Stability:: 
* The Very High Level Layer:: 
* Reference Counting:: 
* Exception Handling:: 
* Defining extension modules:: 
* Definition slots:: 
* Utilities: Utilities<2>. 
* Abstract Objects Layer:: 
* Concrete Objects Layer:: 
* Interpreter initialization and finalization:: 
* Thread states and the global interpreter lock:: 
* Asynchronous notifications:: 
* Operating system thread APIs:: 
* Synchronization primitives: Synchronization primitives<2>. 
* Thread-local storage support:: 
* Multiple interpreters in a Python process:: 
* Profiling and tracing:: 
* Reference tracing:: 
* Python Initialization Configuration:: 
* Memory Management:: 
* Object Implementation Support:: 
* API and ABI Versioning:: 
* Monitoring C API:: 
* Generating Execution Events:: 

@end menu

@node Introduction<12>,C API and ABI Stability,,Python/C API reference manual
@anchor{c-api/intro doc}@anchor{5237}@anchor{c-api/intro api-intro}@anchor{5238}@anchor{c-api/intro introduction}@anchor{5239}
@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
* Language version compatibility:: 
* Coding standards:: 
* Include Files:: 
* Useful macros:: 
* Objects@comma{} Types and Reference Counts: Objects Types and Reference Counts. 
* Exceptions: Exceptions<22>. 
* Embedding Python:: 
* Debugging Builds:: 
* Recommended third party tools:: 

@end menu

@node Language version compatibility,Coding standards,,Introduction<12>
@anchor{c-api/intro language-version-compatibility}@anchor{523a}
@subsection Language version compatibility


Python’s C API is compatible with C11 and C++11 versions of C and C++.

This is a lower limit: the C API does not require features from later
C/C++ versions.
You do `not' need to enable your compiler’s «c11 mode».

@node Coding standards,Include Files,Language version compatibility,Introduction<12>
@anchor{c-api/intro coding-standards}@anchor{523b}
@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{b63}@anchor{c-api/intro include-files}@anchor{523c}
@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 Σημείωση 
Since Python may define some pre-processor definitions which affect the standard
headers on some systems, you `must' include @code{Python.h} before any standard
headers are included.

It is recommended to always define @code{PY_SSIZE_T_CLEAN} before including
@code{Python.h}.  See @ref{601,,Parsing arguments and building values} 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 Σημείωση 
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{233c,,prefix} and
@ref{233d,,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{233c,,prefix} include the platform specific headers from
@ref{233d,,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++.

@menu
* System includes:: 

@end menu

@node System includes,,,Include Files
@anchor{c-api/intro capi-system-includes}@anchor{519b}@anchor{c-api/intro system-includes}@anchor{523d}
@subsubsection System includes


@quotation

@code{Python.h} includes several standard header files.
C extensions should include the standard headers that they use,
and should not rely on these implicit includes.
The implicit includes are:


@itemize *

@item 
@code{<assert.h>}

@item 
@code{<intrin.h>} (on Windows)

@item 
@code{<inttypes.h>}

@item 
@code{<limits.h>}

@item 
@code{<math.h>}

@item 
@code{<stdarg.h>}

@item 
@code{<string.h>}

@item 
@code{<wchar.h>}

@item 
@code{<sys/types.h>} (if present)
@end itemize

The following are included for backwards compatibility, unless using
@ref{829,,Limited API} 3.13 or newer:


@itemize *

@item 
@code{<ctype.h>}

@item 
@code{<unistd.h>} (on POSIX)
@end itemize

The following are included for backwards compatibility, unless using
@ref{829,,Limited API} 3.11 or newer:


@itemize *

@item 
@code{<errno.h>}

@item 
@code{<stdio.h>}

@item 
@code{<stdlib.h>}
@end itemize
@end quotation

@cartouche
@quotation Σημείωση 
Since Python may define some pre-processor definitions which affect the standard
headers on some systems, you `must' include @code{Python.h} before any standard
headers are included.
@end quotation
@end cartouche

@node Useful macros,Objects Types and Reference Counts,Include Files,Introduction<12>
@anchor{c-api/intro useful-macros}@anchor{523e}
@subsection Useful macros


Several useful macros are defined in the Python header files.  Many are
defined closer to where they are useful (for example, @ref{1815,,Py_RETURN_NONE},
@ref{1875,,PyMODINIT_FUNC}).
Others of a more general utility are defined here.  This is not necessarily a
complete listing.

@geindex Py_CAN_START_THREADS (C macro)
@anchor{c-api/intro c Py_CAN_START_THREADS}@anchor{523f}
@deffn {C Μακροεντολή} Py_CAN_START_THREADS

If this macro is defined, then the current system is able to start threads.

Currently, all systems supported by CPython (per 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/}), with the
exception of some WebAssembly platforms, support starting threads.


Added in version 3.13.

@end deffn

@geindex Py_GETENV (C macro)
@anchor{c-api/intro c Py_GETENV}@anchor{5240}
@deffn {C Μακροεντολή} Py_GETENV (s)

Like @code{getenv(@var{s})}, but returns @code{NULL} if @ref{d27,,-E} was passed
on the command line (see @ref{61e,,PyConfig.use_environment}).
@end deffn

@menu
* Docstring macros:: 
* General utility macros:: 
* Declaration utilities:: 
* Outdated macros:: 

@end menu

@node Docstring macros,General utility macros,,Useful macros
@anchor{c-api/intro docstring-macros}@anchor{5241}
@subsubsection Docstring macros


@geindex PyDoc_STRVAR (C macro)
@anchor{c-api/intro c PyDoc_STRVAR}@anchor{1f4f}
@deffn {C Μακροεντολή} PyDoc_STRVAR (name, str)

Creates a variable with name `name' that can be used in docstrings.
If Python is built without docstrings (@ref{238e,,--without-doc-strings}),
the value will be an empty string.

Example:

@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

Expands to @code{PyDoc_VAR(@var{name}) = PyDoc_STR(@var{str})}.
@end deffn

@geindex PyDoc_STR (C macro)
@anchor{c-api/intro c PyDoc_STR}@anchor{1d92}
@deffn {C Μακροεντολή} PyDoc_STR (str)

Expands to the given input string, or an empty string
if docstrings are disabled (@ref{238e,,--without-doc-strings}).

Example:

@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

@geindex PyDoc_VAR (C macro)
@anchor{c-api/intro c PyDoc_VAR}@anchor{1fdf}
@deffn {C Μακροεντολή} PyDoc_VAR (name)

Declares a static character array variable with the given `name'.
Expands to @code{static const char @var{name}[]}

For example:

@example
PyDoc_VAR(python_doc) = PyDoc_STR(
   "A genus of constricting snakes in the Pythonidae family native "
   "to the tropics and subtropics of the Eastern Hemisphere.");
@end example
@end deffn

@node General utility macros,Declaration utilities,Docstring macros,Useful macros
@anchor{c-api/intro general-utility-macros}@anchor{5242}
@subsubsection General utility macros


The following macros are for common tasks not specific to Python.

@geindex Py_UNUSED (C macro)
@anchor{c-api/intro c Py_UNUSED}@anchor{1c90}
@deffn {C Μακροεντολή} 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; @}}.


Added in version 3.4.

@end deffn

@geindex Py_GCC_ATTRIBUTE (C macro)
@anchor{c-api/intro c Py_GCC_ATTRIBUTE}@anchor{5243}
@deffn {C Μακροεντολή} Py_GCC_ATTRIBUTE (name)

Use a GCC attribute `name', hiding it from compilers that don’t support GCC
attributes (such as MSVC).

This expands to @code{__attribute__((@var{name)})} on a GCC compiler,
and expands to nothing on compilers that don’t support GCC attributes.
@end deffn

@menu
* Numeric utilities:: 
* Assertion utilities:: 
* Type size utilities:: 
* Macro definition utilities:: 

@end menu

@node Numeric utilities,Assertion utilities,,General utility macros
@anchor{c-api/intro numeric-utilities}@anchor{5244}
@subsubsection Numeric utilities


@geindex Py_ABS (C macro)
@anchor{c-api/intro c Py_ABS}@anchor{5245}
@deffn {C Μακροεντολή} Py_ABS (x)

Return the absolute value of @code{x}.

The argument may be evaluated more than once.
Consequently, do not pass an expression with side-effects directly
to this macro.

If the result cannot be represented (for example, if @code{x} has
@code{INT_MIN} value for int type), the behavior is
undefined.

Corresponds roughly to @code{((@var{x}) < 0 ? -(@var{x}) : (@var{x}))}


Added in version 3.3.

@end deffn

@geindex Py_MAX (C macro)
@geindex Py_MIN (C macro)
@anchor{c-api/intro c Py_MAX}@anchor{5246}
@deffn {C Μακροεντολή} Py_MAX (x, y)
@anchor{c-api/intro c Py_MIN}@anchor{5247}
@deffnx {C Μακροεντολή} Py_MIN (x, y)

Return the larger or smaller of the arguments, respectively.

Any arguments may be evaluated more than once.
Consequently, do not pass an expression with side-effects directly
to this macro.

@code{Py_MAX} corresponds roughly to
@code{(((@var{x}) > (@var{y})) ? (@var{x}) : (@var{y}))}.


Added in version 3.3.

@end deffn

@geindex Py_ARITHMETIC_RIGHT_SHIFT (C macro)
@anchor{c-api/intro c Py_ARITHMETIC_RIGHT_SHIFT}@anchor{5248}
@deffn {C Μακροεντολή} Py_ARITHMETIC_RIGHT_SHIFT (type, integer, positions)

Similar to @code{@var{integer} >> @var{positions}}, but forces sign extension,
as the C standard does not define whether a right-shift of a signed
integer will perform sign extension or a zero-fill.

`integer' should be any signed integer type.
`positions' is the number of positions to shift to the right.

Both `integer' and `positions' can be evaluated more than once;
consequently, avoid directly passing a function call or some other
operation with side-effects to this macro. Instead, store the result as a
variable and then pass it.

`type' is unused and only kept for backwards compatibility. Historically,
`type' was used to cast `integer'.


Άλλαξε στην έκδοση 3.1: This macro is now valid for all signed integer types, not just those for
which @code{unsigned type} is legal. As a result, `type' is no longer
used.

@end deffn

@geindex Py_CHARMASK (C macro)
@anchor{c-api/intro c Py_CHARMASK}@anchor{5249}
@deffn {C Μακροεντολή} 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

@node Assertion utilities,Type size utilities,Numeric utilities,General utility macros
@anchor{c-api/intro assertion-utilities}@anchor{524a}
@subsubsection Assertion utilities


@geindex Py_UNREACHABLE (C macro)
@anchor{c-api/intro c Py_UNREACHABLE}@anchor{f73}
@deffn {C Μακροεντολή} 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.

In debug mode, and on unsupported compilers, the macro expands to a call to
@ref{d4b,,Py_FatalError()}.

A use for @code{Py_UNREACHABLE()} is following a call to a function that
never returns but that is not declared @code{_Noreturn}.

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{d4b,,Py_FatalError()} can be used.


Added in version 3.7.

@end deffn

@geindex Py_SAFE_DOWNCAST (C macro)
@anchor{c-api/intro c Py_SAFE_DOWNCAST}@anchor{524b}
@deffn {C Μακροεντολή} Py_SAFE_DOWNCAST (value, larger, smaller)

Cast `value' to type `smaller' from type `larger', validating that no
information was lost.

On release builds of Python, this is roughly equivalent to
@code{((@var{smaller}) @var{value})}
(in C++, @code{static_cast<@var{smaller}>(@var{value})} will be used instead).

On debug builds (implying that @ref{19eb,,Py_DEBUG} is defined), this asserts
that no information was lost with the cast from `larger' to `smaller'.

`value', `larger', and `smaller' may all be evaluated more than once in the
expression; consequently, do not pass an expression with side-effects
directly to this macro.
@end deffn

@geindex Py_BUILD_ASSERT (C macro)
@anchor{c-api/intro c Py_BUILD_ASSERT}@anchor{1bbd}
@deffn {C Μακροεντολή} Py_BUILD_ASSERT (cond)

Asserts a compile-time condition `cond', as a statement.
The build will fail if the condition is false or cannot be evaluated at compile time.

Corresponds roughly to @code{static_assert(@var{cond})} on C23 and above.

For example:

@example
Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));
@end example


Added in version 3.3.

@end deffn

@geindex Py_BUILD_ASSERT_EXPR (C macro)
@anchor{c-api/intro c Py_BUILD_ASSERT_EXPR}@anchor{1bbe}
@deffn {C Μακροεντολή} Py_BUILD_ASSERT_EXPR (cond)

Asserts a compile-time condition `cond', as an expression that evaluates to @code{0}.
The build will fail if the condition is false or cannot be evaluated at compile time.

For example:

@example
#define foo_to_char(foo) \
    ((char *)(foo) + Py_BUILD_ASSERT_EXPR(offsetof(struct foo, string) == 0))
@end example


Added in version 3.3.

@end deffn

@node Type size utilities,Macro definition utilities,Assertion utilities,General utility macros
@anchor{c-api/intro type-size-utilities}@anchor{524c}
@subsubsection Type size utilities


@geindex Py_ARRAY_LENGTH (C macro)
@anchor{c-api/intro c Py_ARRAY_LENGTH}@anchor{524d}
@deffn {C Μακροεντολή} Py_ARRAY_LENGTH (array)

Compute the length of a statically allocated C array at compile time.

The `array' argument must be a C array with a size known at compile time.
Passing an array with an unknown size, such as a heap-allocated array,
will result in a compilation error on some compilers, or otherwise produce
incorrect results.

This is roughly equivalent to:

@example
sizeof(array) / sizeof((array)[0])
@end example
@end deffn

@geindex Py_MEMBER_SIZE (C macro)
@anchor{c-api/intro c Py_MEMBER_SIZE}@anchor{524e}
@deffn {C Μακροεντολή} Py_MEMBER_SIZE (type, member)

Return the size of a structure (`type') `member' in bytes.

Corresponds roughly to @code{sizeof(((@var{type} *)NULL)->@var{member})}.


Added in version 3.6.

@end deffn

@node Macro definition utilities,,Type size utilities,General utility macros
@anchor{c-api/intro macro-definition-utilities}@anchor{524f}
@subsubsection Macro definition utilities


@geindex Py_FORCE_EXPANSION (C macro)
@anchor{c-api/intro c Py_FORCE_EXPANSION}@anchor{5250}
@deffn {C Μακροεντολή} Py_FORCE_EXPANSION (X)

This is equivalent to @code{@var{X}}, which is useful for token-pasting in
macros, as macro expansions in `X' are forcefully evaluated by the
preprocessor.
@end deffn

@geindex Py_STRINGIFY (C macro)
@anchor{c-api/intro c Py_STRINGIFY}@anchor{5251}
@deffn {C Μακροεντολή} Py_STRINGIFY (x)

Convert @code{x} to a C string.  For example, @code{Py_STRINGIFY(123)} returns
@code{"123"}.


Added in version 3.4.

@end deffn

@node Declaration utilities,Outdated macros,General utility macros,Useful macros
@anchor{c-api/intro declaration-utilities}@anchor{5252}
@subsubsection Declaration utilities


The following macros can be used in declarations.
They are most useful for defining the C API itself, and have limited use
for extension authors.
Most of them expand to compiler-specific spellings of common extensions
to the C language.

@geindex Py_ALWAYS_INLINE (C macro)
@anchor{c-api/intro c Py_ALWAYS_INLINE}@anchor{1e62}
@deffn {C Μακροεντολή} Py_ALWAYS_INLINE

Ask the compiler to always inline a static inline function. The compiler can
ignore it and decide to not inline the function.

Corresponds to @code{always_inline} attribute in GCC and @code{__forceinline}
in MSVC.

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{3dc,,built in debug mode} (if the @ref{19eb,,Py_DEBUG}
macro is defined), the @ref{1e62,,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


Added in version 3.11.

@end deffn

@geindex Py_NO_INLINE (C macro)
@anchor{c-api/intro c Py_NO_INLINE}@anchor{1a6a}
@deffn {C Μακροεντολή} 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}).

Corresponds to the @code{noinline} attribute/specification on GCC and MSVC.

Usage:

@example
Py_NO_INLINE static int random(void) @{ return 4; @}
@end example


Added in version 3.11.

@end deffn

@geindex Py_DEPRECATED (C macro)
@anchor{c-api/intro c Py_DEPRECATED}@anchor{e6a}
@deffn {C Μακροεντολή} Py_DEPRECATED (version)

Use this to declare APIs that were deprecated in a specific CPython version.
The macro must be placed before the symbol name.

Example:

@example
Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
@end example


Άλλαξε στην έκδοση 3.8: MSVC support was added.

@end deffn

@geindex Py_LOCAL (C macro)
@anchor{c-api/intro c Py_LOCAL}@anchor{17ec}
@deffn {C Μακροεντολή} Py_LOCAL (type)

Declare a function returning the specified `type' using a fast-calling
qualifier for functions that are local to the current file.
Semantically, this is equivalent to @code{static @var{type}}.
@end deffn

@geindex Py_LOCAL_INLINE (C macro)
@anchor{c-api/intro c Py_LOCAL_INLINE}@anchor{17ed}
@deffn {C Μακροεντολή} Py_LOCAL_INLINE (type)

Equivalent to @ref{17ec,,Py_LOCAL} but additionally requests the function
be inlined.
@end deffn

@geindex Py_LOCAL_SYMBOL (C macro)
@anchor{c-api/intro c Py_LOCAL_SYMBOL}@anchor{5253}
@deffn {C Μακροεντολή} Py_LOCAL_SYMBOL

Macro used to declare a symbol as local to the shared library (hidden).
On supported platforms, it ensures the symbol is not exported.

On compatible versions of GCC/Clang, it
expands to @code{__attribute__((visibility("hidden")))}.
@end deffn

@geindex Py_EXPORTED_SYMBOL (C macro)
@anchor{c-api/intro c Py_EXPORTED_SYMBOL}@anchor{5254}
@deffn {C Μακροεντολή} Py_EXPORTED_SYMBOL

Macro used to declare a symbol (function or data) as exported.
On Windows, this expands to @code{__declspec(dllexport)}.
On compatible versions of GCC/Clang, it
expands to @code{__attribute__((visibility("default")))}.
This macro is for defining the C API itself; extension modules should not use it.
@end deffn

@geindex Py_IMPORTED_SYMBOL (C macro)
@anchor{c-api/intro c Py_IMPORTED_SYMBOL}@anchor{5255}
@deffn {C Μακροεντολή} Py_IMPORTED_SYMBOL

Macro used to declare a symbol as imported.
On Windows, this expands to @code{__declspec(dllimport)}.
This macro is for defining the C API itself; extension modules should not use it.
@end deffn

@geindex PyAPI_FUNC (C macro)
@anchor{c-api/intro c PyAPI_FUNC}@anchor{5256}
@deffn {C Μακροεντολή} PyAPI_FUNC (type)

Macro used by CPython to declare a function as part of the C API.
Its expansion depends on the platform and build configuration.
This macro is intended for defining CPython’s C API itself;
extension modules should not use it for their own symbols.
@end deffn

@geindex PyAPI_DATA (C macro)
@anchor{c-api/intro c PyAPI_DATA}@anchor{5257}
@deffn {C Μακροεντολή} PyAPI_DATA (type)

Macro used by CPython to declare a public global variable as part of the C API.
Its expansion depends on the platform and build configuration.
This macro is intended for defining CPython’s C API itself;
extension modules should not use it for their own symbols.
@end deffn

@node Outdated macros,,Declaration utilities,Useful macros
@anchor{c-api/intro outdated-macros}@anchor{5258}
@subsubsection Outdated macros


The following @ref{1a7,,soft deprecated} macros have been used to features that
have been standardized in C11 (or previous standards).

@geindex Py_ALIGNED (C macro)
@anchor{c-api/intro c Py_ALIGNED}@anchor{3c5}
@deffn {C Μακροεντολή} Py_ALIGNED (num)

On some GCC-like compilers, specify alignment to `num' bytes.
This does nothing on other compilers.

Use the standard @code{alignas} specifier rather than this macro.


@ref{1a7,,Soft deprecated} since version 3.15.

@end deffn

@geindex PY_FORMAT_SIZE_T (C macro)
@anchor{c-api/intro c PY_FORMAT_SIZE_T}@anchor{3c6}
@deffn {C Μακροεντολή} PY_FORMAT_SIZE_T

The @code{printf()} formatting modifier for @code{size_t}.
Use @code{"z"} directly instead.


@ref{1a7,,Soft deprecated} since version 3.15.

@end deffn

@geindex Py_LL (C macro)
@geindex Py_ULL (C macro)
@anchor{c-api/intro c Py_LL}@anchor{3c7}
@deffn {C Μακροεντολή} Py_LL (number)
@anchor{c-api/intro c Py_ULL}@anchor{3c8}
@deffnx {C Μακροεντολή} Py_ULL (number)

Use `number' as a @code{long long} or @code{unsigned long long} integer literal,
respectively.

Expands to `number' followed by @code{LL} or @code{LLU}, respectively, but will
expand to some compiler-specific suffixes on some older compilers.

Consider using the C99 standard suffixes @code{LL} and @code{LLU} directly.


@ref{1a7,,Soft deprecated} since version 3.15.

@end deffn

@geindex PY_LONG_LONG (C macro)
@geindex PY_INT32_T (C macro)
@geindex PY_UINT32_T (C macro)
@geindex PY_INT64_T (C macro)
@geindex PY_UINT64_T (C macro)
@anchor{c-api/intro c PY_LONG_LONG}@anchor{3c9}
@deffn {C Μακροεντολή} PY_LONG_LONG
@anchor{c-api/intro c PY_INT32_T}@anchor{3cd}
@deffnx {C Μακροεντολή} PY_INT32_T
@anchor{c-api/intro c PY_UINT32_T}@anchor{3ce}
@deffnx {C Μακροεντολή} PY_UINT32_T
@anchor{c-api/intro c PY_INT64_T}@anchor{3cf}
@deffnx {C Μακροεντολή} PY_INT64_T
@anchor{c-api/intro c PY_UINT64_T}@anchor{3d0}
@deffnx {C Μακροεντολή} PY_UINT64_T

Aliases for the types @code{long long}, @code{int32_t},
@code{uint32_t}. @code{int64_t} and @code{uint64_t},
respectively.
Historically, these types needed compiler-specific extensions.


@ref{1a7,,Soft deprecated} since version 3.15.

@end deffn

@geindex PY_LLONG_MIN (C macro)
@geindex PY_LLONG_MAX (C macro)
@geindex PY_ULLONG_MAX (C macro)
@geindex PY_SIZE_MAX (C macro)
@anchor{c-api/intro c PY_LLONG_MIN}@anchor{3ca}
@deffn {C Μακροεντολή} PY_LLONG_MIN
@anchor{c-api/intro c PY_LLONG_MAX}@anchor{3cb}
@deffnx {C Μακροεντολή} PY_LLONG_MAX
@anchor{c-api/intro c PY_ULLONG_MAX}@anchor{3cc}
@deffnx {C Μακροεντολή} PY_ULLONG_MAX
@anchor{c-api/intro c PY_SIZE_MAX}@anchor{3d1}
@deffnx {C Μακροεντολή} PY_SIZE_MAX

Aliases for the values @code{LLONG_MIN}, @code{LLONG_MAX},
@code{ULLONG_MAX}, and @code{SIZE_MAX}, respectively.
Use these standard names instead.

The required header, @code{<limits.h>},
@ref{519b,,is included} in @code{Python.h}.


@ref{1a7,,Soft deprecated} since version 3.15.

@end deffn

@geindex Py_MEMCPY (C macro)
@anchor{c-api/intro c Py_MEMCPY}@anchor{1b9d}
@deffn {C Μακροεντολή} Py_MEMCPY (dest, src, n)

This is an alias to @code{memcpy()}.


@ref{1a7,,Soft deprecated} since version 3.14: Use @code{memcpy()} directly instead.

@end deffn

@geindex Py_UNICODE_SIZE (C macro)
@anchor{c-api/intro c Py_UNICODE_SIZE}@anchor{3d2}
@deffn {C Μακροεντολή} Py_UNICODE_SIZE

Size of the @code{wchar_t} type.
Use @code{sizeof(wchar_t)} or @code{WCHAR_WIDTH/8} instead.

The required header for the latter, @code{<limits.h>},
@ref{519b,,is included} in @code{Python.h}.


@ref{1a7,,Soft deprecated} since version 3.15.

@end deffn

@geindex Py_UNICODE_WIDE (C macro)
@anchor{c-api/intro c Py_UNICODE_WIDE}@anchor{3d4}
@deffn {C Μακροεντολή} Py_UNICODE_WIDE

Defined if @code{wchar_t} can hold a Unicode character (UCS-4).
Use @code{sizeof(wchar_t) >= 4} instead


@ref{1a7,,Soft deprecated} since version 3.15.

@end deffn

@geindex Py_VA_COPY (C macro)
@anchor{c-api/intro c Py_VA_COPY}@anchor{3d3}
@deffn {C Μακροεντολή} Py_VA_COPY

This is an alias to the C99-standard @code{va_copy} function.

Historically, this would use a compiler-specific method to copy a @code{va_list}.


Άλλαξε στην έκδοση 3.6: This is now an alias to @code{va_copy}.



@ref{1a7,,Soft deprecated} since version 3.15.

@end deffn

@node Objects Types and Reference Counts,Exceptions<22>,Useful macros,Introduction<12>
@anchor{c-api/intro api-objects}@anchor{5259}@anchor{c-api/intro objects-types-and-reference-counts}@anchor{525a}
@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{19b,,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{19b,,PyObject}, only pointer variables of type PyObject* can  be
declared.  The sole exception are the type objects; since these must never be
deallocated, they are typically static @ref{e6b,,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{2520,,Η τυπική ιεραρχία τύπου}).  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
* Reference Counts: Reference Counts<2>. 
* Types: Types<2>. 

@end menu

@node Reference Counts<2>,Types<2>,,Objects Types and Reference Counts
@anchor{c-api/intro api-refcounts}@anchor{525b}@anchor{c-api/intro reference-counts}@anchor{525c}
@subsubsection Reference Counts


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{7da,,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 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{974,,Py_INCREF()} to take a new reference to an
object (i.e. increment its reference count by one),
and @ref{975,,Py_DECREF()} to release that reference (i.e. decrement the
reference count by one).  The @code{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{7da,,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 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{975,,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{7da,,strong reference}
(i.e. increment the reference count) of the object they return.
This leaves the caller with the responsibility to call @ref{975,,Py_DECREF()} when
they are done with the result; this soon becomes second nature.

@menu
* Reference Count Details:: 

@end menu

@node Reference Count Details,,,Reference Counts<2>
@anchor{c-api/intro api-refcountdetails}@anchor{525d}@anchor{c-api/intro reference-count-details}@anchor{525e}
@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{975,,Py_DECREF()} or @ref{b6e,,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{603,,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{1adb,,PyList_SetItem()} and @ref{51cf,,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{1dca,,PyLong_FromLong()} returns a new reference which is immediately
stolen by @ref{51cf,,PyTuple_SetItem()}.  When you want to keep using an object
although the reference to it will be stolen, use @ref{974,,Py_INCREF()} to grab
another reference before calling the reference-stealing function.

Incidentally, @ref{51cf,,PyTuple_SetItem()} is the `only' way to set tuple items;
@ref{2022,,PySequence_SetItem()} and @ref{525f,,PyObject_SetItem()} refuse to do this
since tuples are an immutable data type.  You should only use
@code{PyTuple_SetItem()} for tuples that you are creating yourself.

Equivalent code for populating a list can be written using @ref{5260,,PyList_New()}
and @ref{1adb,,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{5ee,,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{525f,,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{7e2,,PyObject_GetItem()} and  @ref{2021,,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{7f5,,PyList_GetItem()}, you
don’t own the reference — but if you obtain the same item from the same list
using @ref{2021,,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{7f5,,PyList_GetItem()}, and once
using @ref{2021,,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<2>,,Reference Counts<2>,Objects Types and Reference Counts
@anchor{c-api/intro api-types}@anchor{5261}@anchor{c-api/intro types}@anchor{5262}
@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{e24}
@deffn {C Τύπος} type Py_ssize_t
` Μέρος του @ref{95c,,Σταθερό 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{e24,,Py_ssize_t}.
@end deffn

@node Exceptions<22>,Embedding Python,Objects Types and Reference Counts,Introduction<12>
@anchor{c-api/intro api-exceptions}@anchor{5263}@anchor{c-api/intro exceptions}@anchor{5264}
@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{1ea5,,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{1ea5,,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{980,,PyErr_SetString()} is the most common (though not the most general)
function to set the exception state, and @ref{13d9,,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{ad6,,try} …
@ref{447,,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{a7a,,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{5265,,PyErr_ExceptionMatches()} and
@ref{13d9,,PyErr_Clear()} to handle specific exceptions, and the use of
@ref{b6e,,Py_XDECREF()} to dispose of owned references that may be @code{NULL} (note the
@code{'X'} in the name; @ref{975,,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 Embedding Python,Debugging Builds,Exceptions<22>,Introduction<12>
@anchor{c-api/intro api-embedding}@anchor{5266}@anchor{c-api/intro embedding-python}@anchor{5267}
@subsection Embedding 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{673,,Py_Initialize()}. This initializes
the table of loaded modules, and creates the fundamental modules
@ref{13,,builtins}, @ref{1,,__main__}, and @ref{e2,,sys}.  It also
initializes the module search path (@code{sys.path}).

@ref{673,,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{607,,PyConfig.argv} and @ref{1ee6,,PyConfig.parse_argv} must be set: see
@ref{837,,Python Initialization Configuration}.

On most systems (in particular, on Unix and Windows, although the details are
slightly different), @ref{673,,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 μεταβλητή περιβάλλοντος; 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 μεταβλητή περιβάλλοντος; PATH
@code{PATH}.)  The user can override this behavior by setting the
environment variable 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME}, or insert additional directories in
front of the standard path by setting 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH}.

The embedding application can steer the search by setting
@ref{608,,PyConfig.program_name} `before' calling
@ref{60a,,Py_InitializeFromConfig()}. Note that
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} still overrides this and 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} is still
inserted in front of the standard path.

@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{673,,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{10cf,,Py_FinalizeEx()}.  The function @ref{191f,,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 @code{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,Recommended third party tools,Embedding Python,Introduction<12>
@anchor{c-api/intro api-debugging}@anchor{5268}@anchor{c-api/intro debugging-builds}@anchor{5269}
@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{19eb}
@deffn {C Μακροεντολή} Py_DEBUG
@end deffn

Compiling the interpreter with the @code{Py_DEBUG} macro defined produces
what is generally meant by @ref{3dc,,a debug build of Python}.

On Unix, @code{Py_DEBUG} can be enabled by adding @ref{853,,--with-pydebug}
to the @code{./configure} command. This will also disable compiler optimization.

On Windows, selecting a debug build (e.g., by passing the @ref{2312,,-d} option to
@code{PCbuild/build.bat}) automatically enables @code{Py_DEBUG}.
Additionally, the presence of the not-Python-specific @code{_DEBUG} macro,
when defined by the compiler, will also implicitly enable @code{Py_DEBUG}.

In addition to the reference count debugging described below, extra checks are
performed. See @ref{3dc,,Python Debug Build} for more details.

Defining @code{Py_TRACE_REFS} enables reference tracing
(see the @ref{828,,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{19b,,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 Recommended third party tools,,Debugging Builds,Introduction<12>
@anchor{c-api/intro c-api-tools}@anchor{5198}@anchor{c-api/intro recommended-third-party-tools}@anchor{526a}
@subsection Recommended third party tools


The following third party tools offer both simpler and more sophisticated
approaches to creating C, C++ and Rust extensions for Python:


@itemize *

@item 
Cython@footnote{https://cython.org/}

@item 
cffi@footnote{https://cffi.readthedocs.io}

@item 
HPy@footnote{https://hpyproject.org/}

@item 
nanobind@footnote{https://github.com/wjakob/nanobind} (C++)

@item 
Numba@footnote{https://numba.pydata.org/}

@item 
pybind11@footnote{https://pybind11.readthedocs.io/} (C++)

@item 
PyO3@footnote{https://pyo3.rs/} (Rust)

@item 
SWIG@footnote{https://www.swig.org}
@end itemize

Using tools such as these can help avoid writing code that is tightly bound to
a particular version of CPython, avoid reference counting errors, and focus
more on your own code than on using the CPython API. In general, new versions
of Python can be supported by updating the tool, and your code will often use
newer and more efficient APIs automatically. Some tools also support compiling
for other implementations of Python from a single set of sources.

These projects are not supported by the same people who maintain Python, and
issues need to be raised with the projects directly. Remember to check that the
project is still maintained and supported, as the list above may become
outdated.


@subsubheading Δείτε επίσης



@table @asis

@item Python Packaging User Guide: Binary Extensions@footnote{https://packaging.python.org/guides/packaging-binary-extensions/}

The Python Packaging User Guide not only covers several available
tools that simplify the creation of binary extensions, but also
discusses the various reasons why creating an extension module may be
desirable in the first place.
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node C API and ABI Stability,The Very High Level Layer,Introduction<12>,Python/C API reference manual
@anchor{c-api/stable doc}@anchor{526b}@anchor{c-api/stable c-api-and-abi-stability}@anchor{526c}@anchor{c-api/stable stable}@anchor{95c}@anchor{c-api/stable translation-repo}@anchor{526d}
@section C API and ABI Stability


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{526e,,Platform Considerations} 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{954,,Unstable API}, may change in minor versions without
a deprecation period. It is marked by the @code{PyUnstable} prefix in names.

@item 
@ref{829,,Limited API}, is compatible across several minor releases.
When @ref{84d,,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:: 
* Stable Application Binary Interfaces:: 
* Platform Considerations:: 
* ABI Checking:: 
* Contents of Limited API:: 

@end menu

@node Unstable C API,Stable Application Binary Interfaces,,C API and ABI Stability
@anchor{c-api/stable id1}@anchor{526f}@anchor{c-api/stable unstable-c-api}@anchor{954}
@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.
@anchor{c-api/stable stable-abi}@anchor{197}
@node Stable Application Binary Interfaces,Platform Considerations,Unstable C API,C API and ABI Stability
@anchor{c-api/stable stable-application-binary-interface}@anchor{521d}@anchor{c-api/stable stable-application-binary-interfaces}@anchor{5270}
@subsection Stable Application Binary Interfaces


Python’s `Stable ABI' allows extensions to be compatible with multiple
versions of Python, without recompilation.

@cartouche
@quotation Σημείωση 
For simplicity, this document talks about `extensions', but Stable ABI
works the same way for all uses of the API – for example, embedding Python.
@end quotation
@end cartouche

There are two Stable ABIs:


@itemize -

@item 
@code{abi3}, introduced in Python 3.2, is compatible with
`non'-@ref{198,,free-threaded} builds of CPython.

@item 
@code{abi3t}, introduced in Python 3.15, is compatible with
@ref{198,,free-threaded} builds of CPython.
It has stricter API limitations than @code{abi3}.

@quotation


Added in version 3.15: @code{abi3t} was added in 
@geindex Python Enhancement Proposals; PEP 803
PEP 803@footnote{https://peps.python.org/pep-0803/}

@end quotation
@end itemize

It is possible for an extension to be compiled for `both' @code{abi3} and
@code{abi3t} at the same time; the result will be compatible with
both free-threaded and non-free-threaded builds of Python.
Currently, this has no downsides compared to compiling for @code{abi3t} only.

Each Stable ABI is versioned using the first two numbers of the Python version.
For example, Stable ABI 3.14 corresponds to Python 3.14.
An extension compiled for Stable ABI 3.x is ABI-compatible with Python 3.x
and above.

Extensions that target a stable ABI must only use a limited subset of
the C API. This subset is known as the `Limited API'; its contents
are @ref{b79,,listed below}.

On Windows, extensions that use a Stable ABI should be linked against
@code{python3.dll} rather than a version-specific library such as
@code{python39.dll}.
This library only exposes the relevant symbols.

On some platforms, Python will look for and load shared library files named
with the @code{abi3} or @code{abi3t} tag (for example, @code{mymodule.abi3.so}).
@ref{198,,Free-threaded} interpreters only recognize the
@code{abi3t} tag, while non-free-threaded ones will prefer @code{abi3} but fall back
to @code{abi3t}.
Thus, extensions compatible with both ABIs should use the @code{abi3t} tag.

Python does not necessarily check that extensions it loads
have compatible ABI.
Extension authors are encouraged to add a check using the @ref{358,,Py_mod_abi}
slot or the @ref{359,,PyABIInfo_Check()} function, but the user
(or their packaging tool) is ultimately responsible for ensuring that,
for example, extensions built for Stable ABI 3.10 are not installed for lower
versions of Python.

All functions in Stable ABI are present as functions in Python’s shared
library, not solely as macros.
This makes them usable are usable from languages that don’t use the C
preprocessor, including Python’s @ref{2d,,ctypes}.

@menu
* Compiling for Stable ABI:: 
* Stable ABI Scope and Performance:: 
* Stable ABI Caveats:: 

@end menu

@node Compiling for Stable ABI,Stable ABI Scope and Performance,,Stable Application Binary Interfaces
@anchor{c-api/stable abi3-compiling}@anchor{19e}@anchor{c-api/stable compiling-for-stable-abi}@anchor{5271}
@subsubsection Compiling for Stable ABI


@cartouche
@quotation Σημείωση 
Build tools (such as, for example, meson-python, scikit-build-core,
or Setuptools) often have a mechanism for setting macros and synchronizing
them with extension filenames and other metadata.
Prefer using such a mechanism, if it exists, over defining the
macros manually.

The rest of this section is mainly relevant for tool authors, and for
people who compile extensions manually.


@subsubheading Δείτε επίσης


list of recommended tools@footnote{https://packaging.python.org/en/latest/guides/tool-recommendations/#build-backends-for-extension-modules} in the Python Packaging User Guide

@end quotation
@end cartouche

To compile for a Stable ABI, define one or both of the following macros
to the lowest Python version your extension should support, in
@ref{5ac,,Py_PACK_VERSION} format.
Typically, you should choose a specific value rather than the version of
the Python headers you are compiling against.

The macros must be defined before including @code{Python.h}.
Since @ref{5ac,,Py_PACK_VERSION} is not available at this point, you
will need to use the numeric value directly.
For reference, the values for a few recent Python versions are:


@example
0x30b0000  /* Py_PACK_VERSION(3.11) */
0x30c0000  /* Py_PACK_VERSION(3.12) */
0x30d0000  /* Py_PACK_VERSION(3.13) */
0x30e0000  /* Py_PACK_VERSION(3.14) */
0x30f0000  /* Py_PACK_VERSION(3.15) */
0x3100000  /* Py_PACK_VERSION(3.16) */
@end example


When one of the macros is defined, @code{Python.h} will only expose API that is
compatible with the given Stable ABI – that is, the
@ref{b79,,Limited API} plus some definitions that need to be
visible to the compiler but should not be used directly.
When both are defined, @code{Python.h} will only expose API compatible with
both Stable ABIs.

@geindex Py_LIMITED_API (C macro)
@anchor{c-api/stable c Py_LIMITED_API}@anchor{84d}
@deffn {C Μακροεντολή} Py_LIMITED_API

Target @code{abi3}, that is,
non-@ref{198,,free-threaded builds} of CPython.
See @ref{19e,,above} for common information.
@end deffn

@geindex Py_TARGET_ABI3T (C macro)
@anchor{c-api/stable c Py_TARGET_ABI3T}@anchor{5272}
@deffn {C Μακροεντολή} Py_TARGET_ABI3T

Target @code{abi3t}, that is,
@ref{198,,free-threaded builds} of CPython.
See @ref{19e,,above} for common information.


Added in version 3.15.

@end deffn

Both macros specify a target ABI; the different naming style is due to
backwards compatibility.

@cartouche
@quotation Historical note 
You can also define @code{Py_LIMITED_API} as @code{3}. This works the same as
@code{0x03020000} (Python 3.2, the version that introduced Stable ABI).
@end quotation
@end cartouche

When both are defined, @code{Python.h} may, or may not, redefine
@code{Py_LIMITED_API} to match @code{Py_TARGET_ABI3T}.

On a @ref{198,,free-threaded build} – that is, when
@ref{191e,,Py_GIL_DISABLED} is defined – @code{Py_TARGET_ABI3T}
defaults to the value of @code{Py_LIMITED_API}.
This means that there are two ways to build for both @code{abi3} and @code{abi3t}:


@itemize -

@item 
define both @code{Py_LIMITED_API} and @code{Py_TARGET_ABI3T}, or

@item 
define only @code{Py_LIMITED_API} and:


@itemize -

@item 
on Windows, define @code{Py_GIL_DISABLED};

@item 
on other systems, use the headers of free-threaded build of Python.
@end itemize
@end itemize

@node Stable ABI Scope and Performance,Stable ABI Caveats,Compiling for Stable ABI,Stable Application Binary Interfaces
@anchor{c-api/stable limited-api-scope-and-performance}@anchor{5273}@anchor{c-api/stable stable-abi-scope-and-performance}@anchor{5274}
@subsubsection Stable ABI Scope and Performance


The goal for Stable ABI is to allow everything that is possible with the
full C API, but possibly with a performance penalty.
Generally, compatibility with Stable ABI will require some changes to an
extension’s source code.

For example, while @ref{7f5,,PyList_GetItem()} is available, its «unsafe» macro
variant @ref{5275,,PyList_GET_ITEM()} is not.
The macro can be faster because it can rely on version-specific implementation
details of the list object.

For another example, when `not' compiling for Stable ABI, some C API
functions are inlined or replaced by macros.
Compiling for Stable ABI disables this inlining, allowing stability as
Python’s data structures are improved, but possibly reducing performance.

By leaving out the @code{Py_LIMITED_API} or @code{Py_TARGET_ABI3T}
definition, it is possible to compile Stable-ABI-compatible source
for a version-specific ABI.
A potentially faster version-specific extension can then be distributed
alongside a version compiled for Stable ABI – a slower but more compatible
fallback.

@node Stable ABI Caveats,,Stable ABI Scope and Performance,Stable Application Binary Interfaces
@anchor{c-api/stable limited-api-caveats}@anchor{5276}@anchor{c-api/stable stable-abi-caveats}@anchor{5277}
@subsubsection Stable ABI Caveats


Note that compiling for Stable ABI is `not' a complete guarantee that code will
be compatible with the expected Python versions.
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.

One issue that the @ref{5272,,Py_TARGET_ABI3T} and @ref{84d,,Py_LIMITED_API}
macros do not guard against is calling a function with arguments that are
invalid in a lower Python version.
For example, consider a function that starts accepting @code{NULL} for an
argument. In Python 3.9, @code{NULL} now selects a default behavior, but in
Python 3.8, the argument will be used directly, causing a @code{NULL} dereference
and crash. A similar argument works for fields of structs.

For these reasons, we recommend testing an extension with `all' minor Python
versions it supports.

We also recommend reviewing documentation of all used API to check
if it is explicitly part of the Limited API. Even with @code{Py_LIMITED_API}
defined, a few private declarations are exposed for technical reasons (or
even unintentionally, as bugs).

Also note that while compiling with @code{Py_LIMITED_API} 3.8 means that the
extension should `load' on Python 3.12, and `compile' with Python 3.12,
the same source will not necessarily compile with @code{Py_LIMITED_API}
set to 3.12.
In general, parts of the Limited API may be deprecated and removed,
provided that Stable ABI stays stable.

@node Platform Considerations,ABI Checking,Stable Application Binary Interfaces,C API and ABI Stability
@anchor{c-api/stable platform-considerations}@anchor{5278}@anchor{c-api/stable stable-abi-platform}@anchor{526e}
@subsection Platform Considerations


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{197,,Stable ABIs}, these details define a “platform”. They
usually depend on the OS type and processor architecture

It is the responsibility of each particular distributor of Python
to ensure that all Python versions on a particular platform are built
in a way that does not break the Stable ABIs, or the version-specific ABIs.
This is the case with Windows and macOS releases from @code{python.org} and many
third-party distributors.

@node ABI Checking,Contents of Limited API,Platform Considerations,C API and ABI Stability
@anchor{c-api/stable abi-checking}@anchor{5279}
@subsection ABI Checking



Added in version 3.15.


Python includes a rudimentary check for ABI compatibility.

This check is not comprehensive.
It only guards against common cases of incompatible modules being
installed for the wrong interpreter.
It also does not take @ref{526e,,platform incompatibilities}
into account.
It can only be done after an extension is successfully loaded.

Despite these limitations, it is recommended that extension modules use this
mechanism, so that detectable incompatibilities raise exceptions rather than
crash.

Most modules can use this check via the @ref{358,,Py_mod_abi}
slot and the @ref{35a,,PyABIInfo_VAR} macro, for example like this:

@example
PyABIInfo_VAR(abi_info);

static PyModuleDef_Slot mymodule_slots[] = @{
   @{Py_mod_abi, &abi_info@},
   ...
@};
@end example

The full API is described below for advanced use cases.

@geindex PyABIInfo_Check (C function)
@anchor{c-api/stable c PyABIInfo_Check}@anchor{359}
@deffn {C Συνάρτηση} int PyABIInfo_Check (PyABIInfo *info, const char *module_name)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Verify that the given `info' is compatible with the currently running
interpreter.

Return 0 on success. On failure, raise an exception and return -1.

If the ABI is incompatible, the raised exception will be @ref{1bd,,ImportError}.

The `module_name' argument can be @code{NULL}, or point to a NUL-terminated
UTF-8-encoded string used for error messages.

Note that if `info' describes the ABI that the current code uses (as defined
by @ref{35a,,PyABIInfo_VAR}, for example), using any other Python C API
may lead to crashes.
In particular, it is not safe to examine the raised exception.


Added in version 3.15.

@end deffn

@geindex PyABIInfo_VAR (C macro)
@anchor{c-api/stable c PyABIInfo_VAR}@anchor{35a}
@deffn {C Μακροεντολή} PyABIInfo_VAR (NAME)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Define a static @ref{527a,,PyABIInfo} variable with the given `NAME' that
describes the ABI that the current code will use.
This macro expands to:

@example
static PyABIInfo NAME = @{
    1, 0,
    PyABIInfo_DEFAULT_FLAGS,
    PY_VERSION_HEX,
    PyABIInfo_DEFAULT_ABI_VERSION
@}
@end example


Added in version 3.15.

@end deffn

@geindex PyABIInfo (C type)
@anchor{c-api/stable c PyABIInfo}@anchor{527a}
@deffn {C Τύπος} type PyABIInfo
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών) από την έκδοση 3.15.'
@geindex PyABIInfo.abiinfo_major_version (C member)
@anchor{c-api/stable c PyABIInfo abiinfo_major_version}@anchor{527b}
@deffn {C Μέλος} uint8_t abiinfo_major_version

The major version of @ref{527a,,PyABIInfo}. Can be set to:


@itemize *

@item 
@code{0} to skip all checking, or

@item 
@code{1} to specify this version of @code{PyABIInfo}.
@end itemize
@end deffn

@geindex PyABIInfo.abiinfo_minor_version (C member)
@anchor{c-api/stable c PyABIInfo abiinfo_minor_version}@anchor{527c}
@deffn {C Μέλος} uint8_t abiinfo_minor_version

The minor version of @ref{527a,,PyABIInfo}.
Must be set to @code{0}; larger values are reserved for backwards-compatible
future versions of @code{PyABIInfo}.
@end deffn

@geindex PyABIInfo.flags (C member)
@anchor{c-api/stable c PyABIInfo flags}@anchor{527d}
@deffn {C Μέλος} uint16_t flags

This field is usually set to the following macro:

@geindex PyABIInfo_DEFAULT_FLAGS (C macro)
@anchor{c-api/stable c PyABIInfo_DEFAULT_FLAGS}@anchor{527e}
@deffn {C Μακροεντολή} PyABIInfo_DEFAULT_FLAGS
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Default flags, based on current values of macros such as
@ref{84d,,Py_LIMITED_API} and @ref{191e,,Py_GIL_DISABLED}.
@end deffn

Alternately, the field can be set to the following flags, combined
by bitwise OR.
Unused bits must be set to zero.

ABI variant – one of:

@quotation

@geindex PyABIInfo_STABLE (C macro)
@anchor{c-api/stable c PyABIInfo_STABLE}@anchor{527f}
@deffn {C Μακροεντολή} PyABIInfo_STABLE
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Specifies that Stable ABI is used.
@end deffn

@geindex PyABIInfo_INTERNAL (C macro)
@anchor{c-api/stable c PyABIInfo_INTERNAL}@anchor{5280}
@deffn {C Μακροεντολή} PyABIInfo_INTERNAL

Specifies ABI specific to a particular build of CPython.
Internal use only.
@end deffn
@end quotation

Free-threading compatibility – one of:

@quotation

@geindex PyABIInfo_FREETHREADED (C macro)
@anchor{c-api/stable c PyABIInfo_FREETHREADED}@anchor{5281}
@deffn {C Μακροεντολή} PyABIInfo_FREETHREADED
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Specifies ABI compatible with @ref{198,,free-threaded builds} of CPython.
(That is, ones compiled with @ref{6a5,,--disable-gil}; with @code{t}
in @ref{e28,,sys.abiflags})
@end deffn

@geindex PyABIInfo_GIL (C macro)
@anchor{c-api/stable c PyABIInfo_GIL}@anchor{5282}
@deffn {C Μακροεντολή} PyABIInfo_GIL
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Specifies ABI compatible with non-free-threaded builds of CPython
(ones compiled `without' @ref{6a5,,--disable-gil}).
@end deffn

@geindex PyABIInfo_FREETHREADING_AGNOSTIC (C macro)
@anchor{c-api/stable c PyABIInfo_FREETHREADING_AGNOSTIC}@anchor{5283}
@deffn {C Μακροεντολή} PyABIInfo_FREETHREADING_AGNOSTIC
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Specifies ABI compatible with both free-threaded and
non-free-threaded builds of CPython, that is, both
@code{abi3} and @code{abi3t}.
@end deffn
@end quotation
@end deffn

@geindex PyABIInfo.build_version (C member)
@anchor{c-api/stable c PyABIInfo build_version}@anchor{5284}
@deffn {C Μέλος} uint32_t build_version

The version of the Python headers used to build the code, in the format
used by @ref{5af,,PY_VERSION_HEX}.

This can be set to @code{0} to skip any checks related to this field.
This option is meant mainly for projects that do not use the CPython
headers directly, and do not emulate a specific version of them.
@end deffn

@geindex PyABIInfo.abi_version (C member)
@anchor{c-api/stable c PyABIInfo abi_version}@anchor{5285}
@deffn {C Μέλος} uint32_t abi_version

The ABI version.

For Stable ABI, this field should be the value of
@ref{84d,,Py_LIMITED_API} or @ref{5272,,Py_TARGET_ABI3T}.
If both are defined, use the smaller value.
(If @code{Py_LIMITED_API} is @code{3}; use
@ref{5ac,,Py_PACK_VERSION}(3, 2) instead of @code{3}.)

Otherwise, it should be set to @ref{5af,,PY_VERSION_HEX}.

It can also be set to @code{0} to skip any checks related to this field.

@geindex PyABIInfo_DEFAULT_ABI_VERSION (C macro)
@anchor{c-api/stable c PyABIInfo_DEFAULT_ABI_VERSION}@anchor{5286}
@deffn {C Μακροεντολή} PyABIInfo_DEFAULT_ABI_VERSION
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
The value that should be used for this field, based on current
values of macros such as @ref{84d,,Py_LIMITED_API},
@ref{5af,,PY_VERSION_HEX} and @ref{191e,,Py_GIL_DISABLED}.
@end deffn
@end deffn


Added in version 3.15.

@end deffn
@anchor{c-api/stable limited-c-api}@anchor{829}
@node Contents of Limited API,,ABI Checking,C API and ABI Stability
@anchor{c-api/stable contents-of-limited-api}@anchor{5287}@anchor{c-api/stable limited-api-list}@anchor{b79}
@subsection Contents of Limited API


This is the definitive list of @ref{829,,Limited API} for
Python 3.16:



@itemize *

@item 
@ref{1877,,METH_CLASS}

@item 
@ref{1819,,METH_COEXIST}

@item 
@ref{34b,,METH_FASTCALL}

@item 
@ref{d39,,METH_METHOD}

@item 
@ref{1876,,METH_NOARGS}

@item 
@ref{18a9,,METH_O}

@item 
@ref{1878,,METH_STATIC}

@item 
@ref{18aa,,METH_VARARGS}

@item 
@ref{965,,PY_VECTORCALL_ARGUMENTS_OFFSET}

@item 
@ref{527a,,PyABIInfo}

@item 
@ref{359,,PyABIInfo_Check()}

@item 
@ref{5286,,PyABIInfo_DEFAULT_ABI_VERSION}

@item 
@ref{527e,,PyABIInfo_DEFAULT_FLAGS}

@item 
@ref{5281,,PyABIInfo_FREETHREADED}

@item 
@ref{5283,,PyABIInfo_FREETHREADING_AGNOSTIC}

@item 
@ref{5282,,PyABIInfo_GIL}

@item 
@ref{527f,,PyABIInfo_STABLE}

@item 
@ref{35a,,PyABIInfo_VAR}

@item 
@ref{5288,,PyAIter_Check()}

@item 
@ref{1a6b,,PyArg_Parse()}

@item 
@ref{3b1,,PyArg_ParseTuple()}

@item 
@ref{818,,PyArg_ParseTupleAndKeywords()}

@item 
@ref{18a8,,PyArg_UnpackTuple()}

@item 
@ref{5289,,PyArg_VaParse()}

@item 
@ref{819,,PyArg_VaParseTupleAndKeywords()}

@item 
@ref{528a,,PyArg_ValidateKeywordArguments()}

@item 
@ref{528b,,PyBUF_ANY_CONTIGUOUS}

@item 
@ref{528c,,PyBUF_CONTIG}

@item 
@ref{528d,,PyBUF_CONTIG_RO}

@item 
@ref{1759,,PyBUF_C_CONTIGUOUS}

@item 
@ref{528e,,PyBUF_FORMAT}

@item 
@ref{528f,,PyBUF_FULL}

@item 
@ref{5290,,PyBUF_FULL_RO}

@item 
@ref{175a,,PyBUF_F_CONTIGUOUS}

@item 
@ref{5291,,PyBUF_INDIRECT}

@item 
@ref{5292,,PyBUF_MAX_NDIM}

@item 
@ref{5293,,PyBUF_ND}

@item 
@ref{1c13,,PyBUF_READ}

@item 
@ref{5294,,PyBUF_RECORDS}

@item 
@ref{5295,,PyBUF_RECORDS_RO}

@item 
@ref{5296,,PyBUF_SIMPLE}

@item 
@ref{5297,,PyBUF_STRIDED}

@item 
@ref{5298,,PyBUF_STRIDED_RO}

@item 
@ref{5299,,PyBUF_STRIDES}

@item 
@ref{1758,,PyBUF_WRITABLE}

@item 
@ref{1c14,,PyBUF_WRITE}

@item 
@ref{529a,,PyBaseObject_Type}

@item 
@ref{529b,,PyBool_FromLong()}

@item 
@ref{529c,,PyBool_Type}

@item 
@ref{b41,,PyBuffer_FillContiguousStrides()}

@item 
@ref{b42,,PyBuffer_FillInfo()}

@item 
@ref{b3e,,PyBuffer_FromContiguous()}

@item 
@ref{b3b,,PyBuffer_GetPointer()}

@item 
@ref{b40,,PyBuffer_IsContiguous()}

@item 
@ref{82d,,PyBuffer_Release()}

@item 
@ref{b3c,,PyBuffer_SizeFromFormat()}

@item 
@ref{b3d,,PyBuffer_ToContiguous()}

@item 
@ref{529d,,PyByteArrayIter_Type}

@item 
@ref{529e,,PyByteArray_AsString()}

@item 
@ref{529f,,PyByteArray_Concat()}

@item 
@ref{174b,,PyByteArray_FromObject()}

@item 
@ref{174c,,PyByteArray_FromStringAndSize()}

@item 
@ref{52a0,,PyByteArray_Resize()}

@item 
@ref{52a1,,PyByteArray_Size()}

@item 
@ref{52a2,,PyByteArray_Type}

@item 
@ref{52a3,,PyBytesIter_Type}

@item 
@ref{c5d,,PyBytes_AsString()}

@item 
@ref{52a4,,PyBytes_AsStringAndSize()}

@item 
@ref{52a5,,PyBytes_Concat()}

@item 
@ref{52a6,,PyBytes_ConcatAndDel()}

@item 
@ref{52a7,,PyBytes_DecodeEscape()}

@item 
@ref{1ffa,,PyBytes_FromFormat()}

@item 
@ref{52a8,,PyBytes_FromFormatV()}

@item 
@ref{52a9,,PyBytes_FromObject()}

@item 
@ref{52aa,,PyBytes_FromString()}

@item 
@ref{3b2,,PyBytes_FromStringAndSize()}

@item 
@ref{52ab,,PyBytes_Repr()}

@item 
@ref{52ac,,PyBytes_Size()}

@item 
@ref{52ad,,PyBytes_Type}

@item 
@ref{181a,,PyCFunction}

@item 
@ref{52ae,,PyCFunctionFast}

@item 
@ref{52af,,PyCFunctionFastWithKeywords}

@item 
@ref{52b0,,PyCFunctionWithKeywords}

@item 
@ref{52b1,,PyCFunction_GetFlags()}

@item 
@ref{52b2,,PyCFunction_GetFunction()}

@item 
@ref{52b3,,PyCFunction_GetSelf()}

@item 
@ref{1ea7,,PyCFunction_New()}

@item 
@ref{1f6a,,PyCFunction_NewEx()}

@item 
@ref{52b4,,PyCFunction_Type}

@item 
@ref{1ea1,,PyCMethod_New()}

@item 
@ref{52b5,,PyCallIter_New()}

@item 
@ref{52b6,,PyCallIter_Type}

@item 
@ref{52b7,,PyCallable_Check()}

@item 
@ref{52b8,,PyCapsule_Destructor}

@item 
@ref{52b9,,PyCapsule_GetContext()}

@item 
@ref{52ba,,PyCapsule_GetDestructor()}

@item 
@ref{52bb,,PyCapsule_GetName()}

@item 
@ref{52bc,,PyCapsule_GetPointer()}

@item 
@ref{1e07,,PyCapsule_Import()}

@item 
@ref{1701,,PyCapsule_IsValid()}

@item 
@ref{51da,,PyCapsule_New()}

@item 
@ref{52bd,,PyCapsule_SetContext()}

@item 
@ref{52be,,PyCapsule_SetDestructor()}

@item 
@ref{52bf,,PyCapsule_SetName()}

@item 
@ref{52c0,,PyCapsule_SetPointer()}

@item 
@ref{52c1,,PyCapsule_Type}

@item 
@ref{52c2,,PyClassMethodDescr_Type}

@item 
@ref{52c3,,PyCodec_BackslashReplaceErrors()}

@item 
@ref{3a1,,PyCodec_Decode()}

@item 
@ref{52c4,,PyCodec_Decoder()}

@item 
@ref{3a2,,PyCodec_Encode()}

@item 
@ref{52c5,,PyCodec_Encoder()}

@item 
@ref{52c6,,PyCodec_IgnoreErrors()}

@item 
@ref{52c7,,PyCodec_IncrementalDecoder()}

@item 
@ref{52c8,,PyCodec_IncrementalEncoder()}

@item 
@ref{52c9,,PyCodec_KnownEncoding()}

@item 
@ref{52ca,,PyCodec_LookupError()}

@item 
@ref{1260,,PyCodec_NameReplaceErrors()}

@item 
@ref{52cb,,PyCodec_Register()}

@item 
@ref{52cc,,PyCodec_RegisterError()}

@item 
@ref{52cd,,PyCodec_ReplaceErrors()}

@item 
@ref{52ce,,PyCodec_StreamReader()}

@item 
@ref{52cf,,PyCodec_StreamWriter()}

@item 
@ref{52d0,,PyCodec_StrictErrors()}

@item 
@ref{c6d,,PyCodec_Unregister()}

@item 
@ref{52d1,,PyCodec_XMLCharRefReplaceErrors()}

@item 
@ref{52d2,,PyComplex_FromDoubles()}

@item 
@ref{1c1b,,PyComplex_ImagAsDouble()}

@item 
@ref{1c1a,,PyComplex_RealAsDouble()}

@item 
@ref{52d3,,PyComplex_Type}

@item 
@ref{368,,PyCriticalSection}

@item 
@ref{52d4,,PyCriticalSection2}

@item 
@ref{52d5,,PyCriticalSection2_Begin()}

@item 
@ref{52d6,,PyCriticalSection2_End()}

@item 
@ref{52d7,,PyCriticalSection_Begin()}

@item 
@ref{52d8,,PyCriticalSection_End()}

@item 
@ref{52d9,,PyDescr_NewClassMethod()}

@item 
@ref{52da,,PyDescr_NewGetSet()}

@item 
@ref{52db,,PyDescr_NewMember()}

@item 
@ref{1f69,,PyDescr_NewMethod()}

@item 
@ref{52dc,,PyDictItems_Type}

@item 
@ref{52dd,,PyDictIterItem_Type}

@item 
@ref{52de,,PyDictIterKey_Type}

@item 
@ref{52df,,PyDictIterValue_Type}

@item 
@ref{52e0,,PyDictKeys_Type}

@item 
@ref{52e1,,PyDictProxy_New()}

@item 
@ref{52e2,,PyDictProxy_Type}

@item 
@ref{52e3,,PyDictRevIterItem_Type}

@item 
@ref{52e4,,PyDictRevIterKey_Type}

@item 
@ref{52e5,,PyDictRevIterValue_Type}

@item 
@ref{52e6,,PyDictValues_Type}

@item 
@ref{52e7,,PyDict_Clear()}

@item 
@ref{7d7,,PyDict_Contains()}

@item 
@ref{84f,,PyDict_Copy()}

@item 
@ref{52e8,,PyDict_DelItem()}

@item 
@ref{52e9,,PyDict_DelItemString()}

@item 
@ref{81c,,PyDict_GetItem()}

@item 
@ref{7d8,,PyDict_GetItemRef()}

@item 
@ref{81d,,PyDict_GetItemString()}

@item 
@ref{634,,PyDict_GetItemStringRef()}

@item 
@ref{7d9,,PyDict_GetItemWithError()}

@item 
@ref{52ea,,PyDict_Items()}

@item 
@ref{52eb,,PyDict_Keys()}

@item 
@ref{52ec,,PyDict_Merge()}

@item 
@ref{52ed,,PyDict_MergeFromSeq2()}

@item 
@ref{52ee,,PyDict_New()}

@item 
@ref{1b9c,,PyDict_Next()}

@item 
@ref{7db,,PyDict_SetDefaultRef()}

@item 
@ref{51d0,,PyDict_SetItem()}

@item 
@ref{1b9b,,PyDict_SetItemString()}

@item 
@ref{52ef,,PyDict_Size()}

@item 
@ref{52f0,,PyDict_Type}

@item 
@ref{52f1,,PyDict_Update()}

@item 
@ref{52f2,,PyDict_Values()}

@item 
@ref{52f3,,PyEllipsis_Type}

@item 
@ref{52f4,,PyEnum_Type}

@item 
@ref{52f5,,PyErr_BadArgument()}

@item 
@ref{52f6,,PyErr_BadInternalCall()}

@item 
@ref{880,,PyErr_CheckSignals()}

@item 
@ref{13d9,,PyErr_Clear()}

@item 
@code{PyErr_Display()}

@item 
@ref{648,,PyErr_DisplayException()}

@item 
@ref{5265,,PyErr_ExceptionMatches()}

@item 
@ref{63b,,PyErr_Fetch()}

@item 
@ref{1262,,PyErr_Format()}

@item 
@ref{1261,,PyErr_FormatV()}

@item 
@ref{b54,,PyErr_GetExcInfo()}

@item 
@ref{b51,,PyErr_GetHandledException()}

@item 
@ref{63c,,PyErr_GetRaisedException()}

@item 
@ref{52f7,,PyErr_GivenExceptionMatches()}

@item 
@ref{160e,,PyErr_NewException()}

@item 
@ref{160d,,PyErr_NewExceptionWithDoc()}

@item 
@ref{51b7,,PyErr_NoMemory()}

@item 
@ref{63d,,PyErr_NormalizeException()}

@item 
@ref{1ea5,,PyErr_Occurred()}

@item 
@ref{1f21,,PyErr_Print()}

@item 
@ref{52f8,,PyErr_PrintEx()}

@item 
@ref{52f9,,PyErr_ProgramText()}

@item 
@ref{10d1,,PyErr_ResourceWarning()}

@item 
@ref{63e,,PyErr_Restore()}

@item 
@ref{52fa,,PyErr_SetExcFromWindowsErr()}

@item 
@ref{1c8c,,PyErr_SetExcFromWindowsErrWithFilename()}

@item 
@ref{52fb,,PyErr_SetExcFromWindowsErrWithFilenameObject()}

@item 
@ref{52fc,,PyErr_SetExcFromWindowsErrWithFilenameObjects()}

@item 
@ref{b53,,PyErr_SetExcInfo()}

@item 
@ref{51b6,,PyErr_SetFromErrno()}

@item 
@ref{1c8b,,PyErr_SetFromErrnoWithFilename()}

@item 
@ref{52fd,,PyErr_SetFromErrnoWithFilenameObject()}

@item 
@ref{52fe,,PyErr_SetFromErrnoWithFilenameObjects()}

@item 
@ref{52ff,,PyErr_SetFromWindowsErr()}

@item 
@ref{1c8d,,PyErr_SetFromWindowsErrWithFilename()}

@item 
@ref{b52,,PyErr_SetHandledException()}

@item 
@ref{10f5,,PyErr_SetImportError()}

@item 
@ref{10d0,,PyErr_SetImportErrorSubclass()}

@item 
@ref{5300,,PyErr_SetInterrupt()}

@item 
@ref{c74,,PyErr_SetInterruptEx()}

@item 
@ref{5301,,PyErr_SetNone()}

@item 
@ref{97f,,PyErr_SetObject()}

@item 
@ref{63f,,PyErr_SetRaisedException()}

@item 
@ref{980,,PyErr_SetString()}

@item 
@ref{5302,,PyErr_SyntaxLocation()}

@item 
@ref{5303,,PyErr_SyntaxLocationEx()}

@item 
@ref{17ee,,PyErr_WarnEx()}

@item 
@ref{1c93,,PyErr_WarnExplicit()}

@item 
@ref{5304,,PyErr_WarnFormat()}

@item 
@ref{7e8,,PyErr_WriteUnraisable()}

@item 
@ref{83a,,PyEval_AcquireThread()}

@item 
@ref{c5c,,PyEval_EvalCode()}

@item 
@ref{1cd9,,PyEval_EvalCodeEx()}

@item 
@ref{5305,,PyEval_EvalFrame()}

@item 
@ref{13d6,,PyEval_EvalFrameEx()}

@item 
@ref{7ea,,PyEval_GetBuiltins()}

@item 
@ref{1d37,,PyEval_GetFrame()}

@item 
@ref{7e9,,PyEval_GetFrameBuiltins()}

@item 
@ref{7eb,,PyEval_GetFrameGlobals()}

@item 
@ref{7ed,,PyEval_GetFrameLocals()}

@item 
@ref{5306,,PyEval_GetFuncDesc()}

@item 
@ref{5307,,PyEval_GetFuncName()}

@item 
@ref{7ec,,PyEval_GetGlobals()}

@item 
@ref{7ee,,PyEval_GetLocals()}

@item 
@ref{1bc3,,PyEval_InitThreads()}

@item 
@ref{5308,,PyEval_ReleaseThread()}

@item 
@ref{839,,PyEval_RestoreThread()}

@item 
@ref{838,,PyEval_SaveThread()}

@item 
@ref{5309,,PyExc_ArithmeticError}

@item 
@ref{530a,,PyExc_AssertionError}

@item 
@ref{530b,,PyExc_AttributeError}

@item 
@ref{530c,,PyExc_BaseException}

@item 
@ref{530d,,PyExc_BaseExceptionGroup}

@item 
@ref{530e,,PyExc_BlockingIOError}

@item 
@ref{530f,,PyExc_BrokenPipeError}

@item 
@ref{5310,,PyExc_BufferError}

@item 
@ref{5311,,PyExc_BytesWarning}

@item 
@ref{5312,,PyExc_ChildProcessError}

@item 
@ref{5313,,PyExc_ConnectionAbortedError}

@item 
@ref{5314,,PyExc_ConnectionError}

@item 
@ref{5315,,PyExc_ConnectionRefusedError}

@item 
@ref{5316,,PyExc_ConnectionResetError}

@item 
@ref{5317,,PyExc_DeprecationWarning}

@item 
@ref{5318,,PyExc_EOFError}

@item 
@ref{5319,,PyExc_EncodingWarning}

@item 
@ref{531a,,PyExc_EnvironmentError}

@item 
@ref{531b,,PyExc_Exception}

@item 
@ref{531c,,PyExc_FileExistsError}

@item 
@ref{531d,,PyExc_FileNotFoundError}

@item 
@ref{531e,,PyExc_FloatingPointError}

@item 
@ref{531f,,PyExc_FutureWarning}

@item 
@ref{5320,,PyExc_GeneratorExit}

@item 
@ref{5321,,PyExc_IOError}

@item 
@ref{5322,,PyExc_ImportError}

@item 
@ref{5323,,PyExc_ImportWarning}

@item 
@ref{5324,,PyExc_IndentationError}

@item 
@ref{5325,,PyExc_IndexError}

@item 
@ref{5326,,PyExc_InterruptedError}

@item 
@ref{5327,,PyExc_IsADirectoryError}

@item 
@ref{5328,,PyExc_KeyError}

@item 
@ref{5329,,PyExc_KeyboardInterrupt}

@item 
@ref{532a,,PyExc_LookupError}

@item 
@ref{532b,,PyExc_MemoryError}

@item 
@ref{532c,,PyExc_ModuleNotFoundError}

@item 
@ref{532d,,PyExc_NameError}

@item 
@ref{532e,,PyExc_NotADirectoryError}

@item 
@ref{532f,,PyExc_NotImplementedError}

@item 
@ref{51b9,,PyExc_OSError}

@item 
@ref{5330,,PyExc_OverflowError}

@item 
@ref{5331,,PyExc_PendingDeprecationWarning}

@item 
@ref{5332,,PyExc_PermissionError}

@item 
@ref{5333,,PyExc_ProcessLookupError}

@item 
@ref{1263,,PyExc_RecursionError}

@item 
@ref{5334,,PyExc_ReferenceError}

@item 
@ref{5335,,PyExc_ResourceWarning}

@item 
@ref{5336,,PyExc_RuntimeError}

@item 
@ref{5337,,PyExc_RuntimeWarning}

@item 
@ref{5338,,PyExc_StopAsyncIteration}

@item 
@ref{5339,,PyExc_StopIteration}

@item 
@ref{533a,,PyExc_SyntaxError}

@item 
@ref{533b,,PyExc_SyntaxWarning}

@item 
@ref{533c,,PyExc_SystemError}

@item 
@ref{533d,,PyExc_SystemExit}

@item 
@ref{533e,,PyExc_TabError}

@item 
@ref{533f,,PyExc_TimeoutError}

@item 
@ref{51b8,,PyExc_TypeError}

@item 
@ref{5340,,PyExc_UnboundLocalError}

@item 
@ref{5341,,PyExc_UnicodeDecodeError}

@item 
@ref{5342,,PyExc_UnicodeEncodeError}

@item 
@ref{5343,,PyExc_UnicodeError}

@item 
@ref{5344,,PyExc_UnicodeTranslateError}

@item 
@ref{5345,,PyExc_UnicodeWarning}

@item 
@ref{5346,,PyExc_UserWarning}

@item 
@ref{51ba,,PyExc_ValueError}

@item 
@ref{5347,,PyExc_Warning}

@item 
@ref{5348,,PyExc_WindowsError}

@item 
@ref{51b5,,PyExc_ZeroDivisionError}

@item 
@ref{e2a,,PyExceptionClass_Name()}

@item 
@ref{970,,PyException_GetArgs()}

@item 
@ref{5349,,PyException_GetCause()}

@item 
@ref{534a,,PyException_GetContext()}

@item 
@ref{534b,,PyException_GetTraceback()}

@item 
@ref{971,,PyException_SetArgs()}

@item 
@ref{534c,,PyException_SetCause()}

@item 
@ref{534d,,PyException_SetContext()}

@item 
@ref{1fbe,,PyException_SetTraceback()}

@item 
@ref{534e,,PyFile_FromFd()}

@item 
@ref{534f,,PyFile_GetLine()}

@item 
@ref{5350,,PyFile_WriteObject()}

@item 
@ref{5351,,PyFile_WriteString()}

@item 
@ref{5352,,PyFilter_Type}

@item 
@ref{e2e,,PyFloat_AsDouble()}

@item 
@ref{5353,,PyFloat_FromDouble()}

@item 
@ref{5354,,PyFloat_FromString()}

@item 
@ref{1793,,PyFloat_GetInfo()}

@item 
@ref{1791,,PyFloat_GetMax()}

@item 
@ref{1792,,PyFloat_GetMin()}

@item 
@ref{5355,,PyFloat_Type}

@item 
@ref{b68,,PyFrameObject}

@item 
@ref{b69,,PyFrame_GetCode()}

@item 
@ref{b6a,,PyFrame_GetLineNumber()}

@item 
@ref{17e7,,PyFrozenSet_New()}

@item 
@ref{5356,,PyFrozenSet_Type}

@item 
@ref{d56,,PyGC_Collect()}

@item 
@ref{c7b,,PyGC_Disable()}

@item 
@ref{c7a,,PyGC_Enable()}

@item 
@ref{c7c,,PyGC_IsEnabled()}

@item 
@ref{1a5,,PyGILState_Ensure()}

@item 
@ref{5357,,PyGILState_GetThisThreadState()}

@item 
@ref{1a6,,PyGILState_Release()}

@item 
@ref{5358,,PyGILState_STATE}

@item 
@ref{f77,,PyGetSetDef}

@item 
@ref{5359,,PyGetSetDescr_Type}

@item 
@ref{7f2,,PyImport_AddModule()}

@item 
@ref{535a,,PyImport_AddModuleObject()}

@item 
@ref{7f1,,PyImport_AddModuleRef()}

@item 
@ref{1d1a,,PyImport_AppendInittab()}

@item 
@ref{535b,,PyImport_ExecCodeModule()}

@item 
@ref{535c,,PyImport_ExecCodeModuleEx()}

@item 
@ref{535d,,PyImport_ExecCodeModuleObject()}

@item 
@ref{535e,,PyImport_ExecCodeModuleWithPathnames()}

@item 
@ref{1c8a,,PyImport_GetImporter()}

@item 
@ref{154c,,PyImport_GetMagicNumber()}

@item 
@ref{535f,,PyImport_GetMagicTag()}

@item 
@ref{f71,,PyImport_GetModule()}

@item 
@ref{5360,,PyImport_GetModuleDict()}

@item 
@ref{179e,,PyImport_Import()}

@item 
@ref{5361,,PyImport_ImportFrozenModule()}

@item 
@ref{5362,,PyImport_ImportFrozenModuleObject()}

@item 
@ref{3a3,,PyImport_ImportModule()}

@item 
@ref{154d,,PyImport_ImportModuleLevel()}

@item 
@ref{5363,,PyImport_ImportModuleLevelObject()}

@item 
@ref{5364,,PyImport_ReloadModule()}

@item 
@ref{d52,,PyIndex_Check()}

@item 
@ref{5365,,PyInterpreterGuard}

@item 
@ref{5366,,PyInterpreterGuard_Close()}

@item 
@ref{5367,,PyInterpreterGuard_FromCurrent()}

@item 
@ref{5368,,PyInterpreterGuard_FromView()}

@item 
@ref{c90,,PyInterpreterState}

@item 
@ref{49aa,,PyInterpreterState_Clear()}

@item 
@ref{5369,,PyInterpreterState_Delete()}

@item 
@ref{83b,,PyInterpreterState_Get()}

@item 
@ref{536a,,PyInterpreterState_GetDict()}

@item 
@ref{f84,,PyInterpreterState_GetID()}

@item 
@ref{49ab,,PyInterpreterState_New()}

@item 
@ref{536b,,PyInterpreterView}

@item 
@ref{536c,,PyInterpreterView_Close()}

@item 
@ref{536d,,PyInterpreterView_FromCurrent()}

@item 
@ref{536e,,PyInterpreterView_FromMain()}

@item 
@ref{1ea8,,PyIter_Check()}

@item 
@ref{5c6,,PyIter_Next()}

@item 
@ref{5c5,,PyIter_NextItem()}

@item 
@ref{c6e,,PyIter_Send()}

@item 
@ref{536f,,PyListIter_Type}

@item 
@ref{5370,,PyListRevIter_Type}

@item 
@ref{5371,,PyList_Append()}

@item 
@ref{5372,,PyList_AsTuple()}

@item 
@ref{7f5,,PyList_GetItem()}

@item 
@ref{7f4,,PyList_GetItemRef()}

@item 
@ref{5373,,PyList_GetSlice()}

@item 
@ref{1ada,,PyList_Insert()}

@item 
@ref{5260,,PyList_New()}

@item 
@ref{5374,,PyList_Reverse()}

@item 
@ref{1adb,,PyList_SetItem()}

@item 
@ref{5375,,PyList_SetSlice()}

@item 
@ref{17bc,,PyList_Size()}

@item 
@ref{5376,,PyList_Sort()}

@item 
@ref{51f0,,PyList_Type}

@item 
@ref{1970,,PyLongExport}

@item 
@ref{196f,,PyLongLayout}

@item 
@ref{5cb,,PyLongObject}

@item 
@ref{5377,,PyLongRangeIter_Type}

@item 
@ref{1971,,PyLongWriter}

@item 
@ref{5d7,,PyLongWriter_Create()}

@item 
@ref{5d9,,PyLongWriter_Discard()}

@item 
@ref{5d8,,PyLongWriter_Finish()}

@item 
@ref{1b87,,PyLong_AsDouble()}

@item 
@ref{7fa,,PyLong_AsInt()}

@item 
@ref{5cc,,PyLong_AsInt32()}

@item 
@ref{5cd,,PyLong_AsInt64()}

@item 
@ref{7fb,,PyLong_AsLong()}

@item 
@ref{160b,,PyLong_AsLongAndOverflow()}

@item 
@ref{5378,,PyLong_AsLongLong()}

@item 
@ref{160a,,PyLong_AsLongLongAndOverflow()}

@item 
@ref{7fc,,PyLong_AsNativeBytes()}

@item 
@ref{5379,,PyLong_AsSize_t()}

@item 
@ref{537a,,PyLong_AsSsize_t()}

@item 
@ref{5ce,,PyLong_AsUInt32()}

@item 
@ref{5cf,,PyLong_AsUInt64()}

@item 
@ref{537b,,PyLong_AsUnsignedLong()}

@item 
@ref{1639,,PyLong_AsUnsignedLongLong()}

@item 
@ref{1fba,,PyLong_AsUnsignedLongLongMask()}

@item 
@ref{537c,,PyLong_AsUnsignedLongMask()}

@item 
@ref{537d,,PyLong_AsVoidPtr()}

@item 
@ref{5d5,,PyLong_Export()}

@item 
@ref{5d6,,PyLong_FreeExport()}

@item 
@ref{d0e,,PyLong_FromDouble()}

@item 
@ref{5d0,,PyLong_FromInt32()}

@item 
@ref{5d1,,PyLong_FromInt64()}

@item 
@ref{1dca,,PyLong_FromLong()}

@item 
@ref{1dcb,,PyLong_FromLongLong()}

@item 
@ref{7fd,,PyLong_FromNativeBytes()}

@item 
@ref{1ae0,,PyLong_FromSize_t()}

@item 
@ref{1ac2,,PyLong_FromSsize_t()}

@item 
@ref{537e,,PyLong_FromString()}

@item 
@ref{5d2,,PyLong_FromUInt32()}

@item 
@ref{5d3,,PyLong_FromUInt64()}

@item 
@ref{1ade,,PyLong_FromUnsignedLong()}

@item 
@ref{1adf,,PyLong_FromUnsignedLongLong()}

@item 
@ref{7fe,,PyLong_FromUnsignedNativeBytes()}

@item 
@ref{537f,,PyLong_FromVoidPtr()}

@item 
@ref{5380,,PyLong_GetInfo()}

@item 
@ref{5d4,,PyLong_GetNativeLayout()}

@item 
@ref{5381,,PyLong_Type}

@item 
@ref{1990,,PyMODEXPORT_FUNC}

@item 
@ref{5382,,PyMap_Type}

@item 
@ref{5383,,PyMapping_Check()}

@item 
@ref{7e3,,PyMapping_GetItemString()}

@item 
@ref{7e0,,PyMapping_GetOptionalItem()}

@item 
@ref{7e1,,PyMapping_GetOptionalItemString()}

@item 
@ref{814,,PyMapping_HasKey()}

@item 
@ref{816,,PyMapping_HasKeyString()}

@item 
@ref{815,,PyMapping_HasKeyStringWithError()}

@item 
@ref{813,,PyMapping_HasKeyWithError()}

@item 
@ref{f7c,,PyMapping_Items()}

@item 
@ref{f7a,,PyMapping_Keys()}

@item 
@ref{5384,,PyMapping_Length()}

@item 
@ref{5385,,PyMapping_SetItemString()}

@item 
@ref{2024,,PyMapping_Size()}

@item 
@ref{f7b,,PyMapping_Values()}

@item 
@ref{125e,,PyMem_Calloc()}

@item 
@ref{17e4,,PyMem_Free()}

@item 
@ref{1024,,PyMem_Malloc()}

@item 
@ref{824,,PyMem_RawCalloc()}

@item 
@ref{826,,PyMem_RawFree()}

@item 
@ref{2bf,,PyMem_RawMalloc()}

@item 
@ref{825,,PyMem_RawRealloc()}

@item 
@ref{13da,,PyMem_Realloc()}

@item 
@ref{95a,,PyMemberDef}

@item 
@ref{5386,,PyMemberDescr_Type}

@item 
@ref{98c,,PyMember_GetOne()}

@item 
@ref{98d,,PyMember_SetOne()}

@item 
@ref{b43,,PyMemoryView_FromBuffer()}

@item 
@ref{1519,,PyMemoryView_FromMemory()}

@item 
@ref{5387,,PyMemoryView_FromObject()}

@item 
@ref{5388,,PyMemoryView_GetContiguous()}

@item 
@ref{5389,,PyMemoryView_Type}

@item 
@ref{1879,,PyMethodDef}

@item 
@ref{538a,,PyMethodDescr_Type}

@item 
@ref{d45,,PyModuleDef}

@item 
@ref{538b,,PyModuleDef_Base}

@item 
@ref{538c,,PyModuleDef_Init()}

@item 
@ref{538d,,PyModuleDef_Slot}

@item 
@ref{538e,,PyModuleDef_Type}

@item 
@ref{7ff,,PyModule_Add()}

@item 
@ref{538f,,PyModule_AddFunctions()}

@item 
@ref{18de,,PyModule_AddIntConstant()}

@item 
@ref{801,,PyModule_AddObject()}

@item 
@ref{800,,PyModule_AddObjectRef()}

@item 
@ref{18df,,PyModule_AddStringConstant()}

@item 
@ref{d3d,,PyModule_AddType()}

@item 
@ref{5390,,PyModule_Create2()}

@item 
@ref{5391,,PyModule_Exec()}

@item 
@ref{394,,PyModule_ExecDef()}

@item 
@ref{393,,PyModule_FromDefAndSpec2()}

@item 
@ref{38c,,PyModule_FromSlotsAndSpec()}

@item 
@ref{5392,,PyModule_GetDef()}

@item 
@ref{5393,,PyModule_GetDict()}

@item 
@ref{640,,PyModule_GetFilename()}

@item 
@ref{641,,PyModule_GetFilenameObject()}

@item 
@ref{5394,,PyModule_GetName()}

@item 
@ref{5395,,PyModule_GetNameObject()}

@item 
@ref{d48,,PyModule_GetState()}

@item 
@ref{5396,,PyModule_GetStateSize()}

@item 
@ref{36f,,PyModule_GetState_DuringGC()}

@item 
@ref{5397,,PyModule_GetToken()}

@item 
@ref{370,,PyModule_GetToken_DuringGC()}

@item 
@ref{5398,,PyModule_New()}

@item 
@ref{5399,,PyModule_NewObject()}

@item 
@ref{539a,,PyModule_SetDocString()}

@item 
@ref{539b,,PyModule_Type}

@item 
@ref{539c,,PyNumber_Absolute()}

@item 
@ref{539d,,PyNumber_Add()}

@item 
@ref{539e,,PyNumber_And()}

@item 
@ref{539f,,PyNumber_AsSsize_t()}

@item 
@ref{e2b,,PyNumber_Check()}

@item 
@ref{53a0,,PyNumber_Divmod()}

@item 
@ref{e2d,,PyNumber_Float()}

@item 
@ref{53a1,,PyNumber_FloorDivide()}

@item 
@ref{53a2,,PyNumber_InPlaceAdd()}

@item 
@ref{53a3,,PyNumber_InPlaceAnd()}

@item 
@ref{53a4,,PyNumber_InPlaceFloorDivide()}

@item 
@ref{53a5,,PyNumber_InPlaceLshift()}

@item 
@ref{1265,,PyNumber_InPlaceMatrixMultiply()}

@item 
@ref{53a6,,PyNumber_InPlaceMultiply()}

@item 
@ref{53a7,,PyNumber_InPlaceOr()}

@item 
@ref{53a8,,PyNumber_InPlacePower()}

@item 
@ref{53a9,,PyNumber_InPlaceRemainder()}

@item 
@ref{53aa,,PyNumber_InPlaceRshift()}

@item 
@ref{53ab,,PyNumber_InPlaceSubtract()}

@item 
@ref{53ac,,PyNumber_InPlaceTrueDivide()}

@item 
@ref{53ad,,PyNumber_InPlaceXor()}

@item 
@ref{c69,,PyNumber_Index()}

@item 
@ref{53ae,,PyNumber_Invert()}

@item 
@ref{e2c,,PyNumber_Long()}

@item 
@ref{53af,,PyNumber_Lshift()}

@item 
@ref{1264,,PyNumber_MatrixMultiply()}

@item 
@ref{53b0,,PyNumber_Multiply()}

@item 
@ref{53b1,,PyNumber_Negative()}

@item 
@ref{53b2,,PyNumber_Or()}

@item 
@ref{53b3,,PyNumber_Positive()}

@item 
@ref{53b4,,PyNumber_Power()}

@item 
@ref{53b5,,PyNumber_Remainder()}

@item 
@ref{53b6,,PyNumber_Rshift()}

@item 
@ref{53b7,,PyNumber_Subtract()}

@item 
@ref{1d70,,PyNumber_ToBase()}

@item 
@ref{53b8,,PyNumber_TrueDivide()}

@item 
@ref{53b9,,PyNumber_Xor()}

@item 
@ref{642,,PyOS_AfterFork()}

@item 
@ref{643,,PyOS_AfterFork_Child()}

@item 
@ref{f7e,,PyOS_AfterFork_Parent()}

@item 
@ref{f7d,,PyOS_BeforeFork()}

@item 
@ref{1d9b,,PyOS_CheckStack()}

@item 
@ref{10d2,,PyOS_FSPath()}

@item 
@ref{986,,PyOS_InputHook}

@item 
@ref{1f36,,PyOS_InterruptOccurred()}

@item 
@ref{53ba,,PyOS_double_to_string()}

@item 
@ref{18e0,,PyOS_getsig()}

@item 
@ref{1f2f,,PyOS_mystricmp()}

@item 
@ref{1f2e,,PyOS_mystrnicmp()}

@item 
@ref{18e1,,PyOS_setsig()}

@item 
@ref{53bb,,PyOS_sighandler_t}

@item 
@ref{18ab,,PyOS_snprintf()}

@item 
@ref{163a,,PyOS_string_to_double()}

@item 
@ref{53bc,,PyOS_strtol()}

@item 
@ref{53bd,,PyOS_strtoul()}

@item 
@ref{18ac,,PyOS_vsnprintf()}

@item 
@ref{19b,,PyObject}

@item 
@ref{c75,,PyObject.ob_refcnt}

@item 
@ref{51e3,,PyObject.ob_type}

@item 
@ref{53be,,PyObject_ASCII()}

@item 
@ref{53bf,,PyObject_AsFileDescriptor()}

@item 
@ref{53c0,,PyObject_Bytes()}

@item 
@ref{82f,,PyObject_Call()}

@item 
@ref{351,,PyObject_CallFinalizerFromDealloc()}

@item 
@ref{831,,PyObject_CallFunction()}

@item 
@ref{53c1,,PyObject_CallFunctionObjArgs()}

@item 
@ref{3b6,,PyObject_CallMethod()}

@item 
@ref{1fce,,PyObject_CallMethodObjArgs()}

@item 
@ref{82e,,PyObject_CallNoArgs()}

@item 
@ref{51c2,,PyObject_CallObject()}

@item 
@ref{125f,,PyObject_Calloc()}

@item 
@ref{82b,,PyObject_CheckBuffer()}

@item 
@ref{97a,,PyObject_ClearWeakRefs()}

@item 
@ref{b3f,,PyObject_CopyData()}

@item 
@ref{1a6d,,PyObject_DelAttr()}

@item 
@ref{1a6e,,PyObject_DelAttrString()}

@item 
@ref{53c2,,PyObject_DelItem()}

@item 
@ref{53c3,,PyObject_DelItemString()}

@item 
@ref{53c4,,PyObject_Dir()}

@item 
@ref{53c5,,PyObject_Format()}

@item 
@ref{1023,,PyObject_Free()}

@item 
@ref{18a5,,PyObject_GC_Del()}

@item 
@ref{d3f,,PyObject_GC_IsFinalized()}

@item 
@ref{d3e,,PyObject_GC_IsTracked()}

@item 
@ref{18a6,,PyObject_GC_Track()}

@item 
@ref{18a7,,PyObject_GC_UnTrack()}

@item 
@ref{53c6,,PyObject_GenericGetAttr()}

@item 
@ref{1efa,,PyObject_GenericGetDict()}

@item 
@ref{53c7,,PyObject_GenericSetAttr()}

@item 
@ref{53c8,,PyObject_GenericSetDict()}

@item 
@ref{53c9,,PyObject_GetAIter()}

@item 
@ref{3b7,,PyObject_GetAttr()}

@item 
@ref{7e6,,PyObject_GetAttrString()}

@item 
@ref{82c,,PyObject_GetBuffer()}

@item 
@ref{7e2,,PyObject_GetItem()}

@item 
@ref{53ca,,PyObject_GetIter()}

@item 
@ref{7e4,,PyObject_GetOptionalAttr()}

@item 
@ref{7e5,,PyObject_GetOptionalAttrString()}

@item 
@ref{19a,,PyObject_GetTypeData()}

@item 
@ref{36c,,PyObject_GetTypeData_DuringGC()}

@item 
@ref{810,,PyObject_HasAttr()}

@item 
@ref{812,,PyObject_HasAttrString()}

@item 
@ref{811,,PyObject_HasAttrStringWithError()}

@item 
@ref{80f,,PyObject_HasAttrWithError()}

@item 
@ref{649,,PyObject_Hash()}

@item 
@ref{1769,,PyObject_HashNotImplemented()}

@item 
@ref{e2f,,PyObject_Init()}

@item 
@ref{1f34,,PyObject_InitVar()}

@item 
@ref{1257,,PyObject_IsInstance()}

@item 
@ref{1258,,PyObject_IsSubclass()}

@item 
@ref{53cb,,PyObject_IsTrue()}

@item 
@ref{53cc,,PyObject_Length()}

@item 
@ref{1026,,PyObject_Malloc()}

@item 
@ref{53cd,,PyObject_Not()}

@item 
@ref{17e5,,PyObject_Realloc()}

@item 
@ref{13d7,,PyObject_Repr()}

@item 
@ref{5206,,PyObject_RichCompare()}

@item 
@ref{1f7e,,PyObject_RichCompareBool()}

@item 
@ref{53ce,,PyObject_SelfIter()}

@item 
@ref{1927,,PyObject_SetAttr()}

@item 
@ref{1a6c,,PyObject_SetAttrString()}

@item 
@ref{525f,,PyObject_SetItem()}

@item 
@ref{53cf,,PyObject_Size()}

@item 
@ref{13d8,,PyObject_Str()}

@item 
@ref{53d0,,PyObject_Type()}

@item 
@ref{963,,PyObject_Vectorcall()}

@item 
@ref{964,,PyObject_VectorcallMethod()}

@item 
@ref{53d1,,PyProperty_Type}

@item 
@ref{53d2,,PyRangeIter_Type}

@item 
@ref{53d3,,PyRange_Type}

@item 
@ref{53d4,,PyReversed_Type}

@item 
@ref{53d5,,PySeqIter_New()}

@item 
@ref{53d6,,PySeqIter_Type}

@item 
@ref{53d7,,PySequence_Check()}

@item 
@ref{53d8,,PySequence_Concat()}

@item 
@ref{605,,PySequence_Contains()}

@item 
@ref{53d9,,PySequence_Count()}

@item 
@ref{2023,,PySequence_DelItem()}

@item 
@ref{53da,,PySequence_DelSlice()}

@item 
@ref{1ac6,,PySequence_Fast()}

@item 
@ref{2021,,PySequence_GetItem()}

@item 
@ref{53db,,PySequence_GetSlice()}

@item 
@ref{604,,PySequence_In()}

@item 
@ref{53dc,,PySequence_InPlaceConcat()}

@item 
@ref{53dd,,PySequence_InPlaceRepeat()}

@item 
@ref{53de,,PySequence_Index()}

@item 
@ref{53df,,PySequence_Length()}

@item 
@ref{53e0,,PySequence_List()}

@item 
@ref{53e1,,PySequence_Repeat()}

@item 
@ref{2022,,PySequence_SetItem()}

@item 
@ref{53e2,,PySequence_SetSlice()}

@item 
@ref{2020,,PySequence_Size()}

@item 
@ref{53e3,,PySequence_Tuple()}

@item 
@ref{53e4,,PySetIter_Type}

@item 
@ref{17e8,,PySet_Add()}

@item 
@ref{53e5,,PySet_Clear()}

@item 
@ref{17ea,,PySet_Contains()}

@item 
@ref{17e9,,PySet_Discard()}

@item 
@ref{17e6,,PySet_New()}

@item 
@ref{53e6,,PySet_Pop()}

@item 
@ref{17eb,,PySet_Size()}

@item 
@ref{53e7,,PySet_Type}

@item 
@ref{646,,PySlice_AdjustIndices()}

@item 
@ref{53e8,,PySlice_GetIndices()}

@item 
@ref{644,,PySlice_GetIndicesEx()}

@item 
@ref{53e9,,PySlice_New()}

@item 
@ref{53ea,,PySlice_Type}

@item 
@ref{645,,PySlice_Unpack()}

@item 
@ref{19d,,PySlot}

@item 
@ref{383,,PySlot_DATA}

@item 
@ref{389,,PySlot_END}

@item 
@ref{384,,PySlot_FUNC}

@item 
@ref{386,,PySlot_INT64}

@item 
@ref{53eb,,PySlot_INTPTR}

@item 
@ref{53ec,,PySlot_OPTIONAL}

@item 
@ref{38a,,PySlot_PTR}

@item 
@ref{38b,,PySlot_PTR_STATIC}

@item 
@ref{385,,PySlot_SIZE}

@item 
@ref{53ed,,PySlot_STATIC}

@item 
@ref{388,,PySlot_STATIC_DATA}

@item 
@ref{387,,PySlot_UINT64}

@item 
@ref{53ee,,PyState_AddModule()}

@item 
@ref{53ef,,PyState_FindModule()}

@item 
@ref{53f0,,PyState_RemoveModule()}

@item 
@ref{f79,,PyStructSequence_Desc}

@item 
@ref{f78,,PyStructSequence_Field}

@item 
@ref{53f1,,PyStructSequence_GetItem()}

@item 
@ref{53f2,,PyStructSequence_New()}

@item 
@ref{53f3,,PyStructSequence_NewType()}

@item 
@ref{53f4,,PyStructSequence_SetItem()}

@item 
@ref{d4a,,PyStructSequence_UnnamedField}

@item 
@ref{53f5,,PySuper_Type}

@item 
@ref{808,,PySys_Audit()}

@item 
@ref{807,,PySys_AuditTuple()}

@item 
@ref{53f6,,PySys_FormatStderr()}

@item 
@ref{53f7,,PySys_FormatStdout()}

@item 
@ref{352,,PySys_GetAttr()}

@item 
@ref{353,,PySys_GetAttrString()}

@item 
@ref{356,,PySys_GetObject()}

@item 
@ref{354,,PySys_GetOptionalAttr()}

@item 
@ref{355,,PySys_GetOptionalAttrString()}

@item 
@ref{53f8,,PySys_GetXOptions()}

@item 
@ref{1bc2,,PySys_SetArgv()}

@item 
@ref{1bc1,,PySys_SetArgvEx()}

@item 
@ref{53f9,,PySys_SetObject()}

@item 
@ref{53fa,,PySys_WriteStderr()}

@item 
@ref{53fb,,PySys_WriteStdout()}

@item 
@ref{b6c,,PyThreadState}

@item 
@ref{53fc,,PyThreadStateToken}

@item 
@ref{1b9e,,PyThreadState_Clear()}

@item 
@ref{1f7b,,PyThreadState_Delete()}

@item 
@ref{53fd,,PyThreadState_Ensure()}

@item 
@ref{53fe,,PyThreadState_EnsureFromView()}

@item 
@ref{809,,PyThreadState_Get()}

@item 
@ref{53ff,,PyThreadState_GetDict()}

@item 
@ref{b6d,,PyThreadState_GetFrame()}

@item 
@ref{d3b,,PyThreadState_GetID()}

@item 
@ref{d3a,,PyThreadState_GetInterpreter()}

@item 
@ref{5400,,PyThreadState_New()}

@item 
@ref{5401,,PyThreadState_Release()}

@item 
@ref{f82,,PyThreadState_SetAsyncExc()}

@item 
@ref{5402,,PyThreadState_Swap()}

@item 
@ref{5403,,PyThread_GetInfo()}

@item 
@ref{654,,PyThread_ReInitTLS()}

@item 
@ref{5404,,PyThread_acquire_lock()}

@item 
@ref{5405,,PyThread_acquire_lock_timed()}

@item 
@ref{5406,,PyThread_allocate_lock()}

@item 
@ref{64a,,PyThread_create_key()}

@item 
@ref{64c,,PyThread_delete_key()}

@item 
@ref{652,,PyThread_delete_key_value()}

@item 
@ref{5407,,PyThread_exit_thread()}

@item 
@ref{5408,,PyThread_free_lock()}

@item 
@ref{650,,PyThread_get_key_value()}

@item 
@ref{5409,,PyThread_get_stacksize()}

@item 
@ref{540a,,PyThread_get_thread_ident()}

@item 
@ref{1d9c,,PyThread_get_thread_native_id()}

@item 
@ref{540b,,PyThread_init_thread()}

@item 
@ref{540c,,PyThread_release_lock()}

@item 
@ref{64e,,PyThread_set_key_value()}

@item 
@ref{540d,,PyThread_set_stacksize()}

@item 
@ref{2018,,PyThread_start_new_thread()}

@item 
@ref{64b,,PyThread_tss_alloc()}

@item 
@ref{540e,,PyThread_tss_create()}

@item 
@ref{653,,PyThread_tss_delete()}

@item 
@ref{64d,,PyThread_tss_free()}

@item 
@ref{651,,PyThread_tss_get()}

@item 
@ref{540f,,PyThread_tss_is_created()}

@item 
@ref{64f,,PyThread_tss_set()}

@item 
@ref{5410,,PyTraceBack_Here()}

@item 
@ref{5411,,PyTraceBack_Print()}

@item 
@ref{5412,,PyTraceBack_Type}

@item 
@ref{5413,,PyTupleIter_Type}

@item 
@ref{51ce,,PyTuple_GetItem()}

@item 
@ref{5414,,PyTuple_GetSlice()}

@item 
@ref{830,,PyTuple_New()}

@item 
@ref{5415,,PyTuple_Pack()}

@item 
@ref{51cf,,PyTuple_SetItem()}

@item 
@ref{5416,,PyTuple_Size()}

@item 
@ref{5417,,PyTuple_Type}

@item 
@ref{e6b,,PyTypeObject}

@item 
@ref{5418,,PyType_ClearCache()}

@item 
@ref{5dc,,PyType_Freeze()}

@item 
@ref{391,,PyType_FromMetaclass()}

@item 
@ref{390,,PyType_FromModuleAndSpec()}

@item 
@ref{376,,PyType_FromSlots()}

@item 
@ref{38e,,PyType_FromSpec()}

@item 
@ref{38f,,PyType_FromSpecWithBases()}

@item 
@ref{e30,,PyType_GenericAlloc()}

@item 
@ref{51e2,,PyType_GenericNew()}

@item 
@ref{5dd,,PyType_GetBaseByToken()}

@item 
@ref{371,,PyType_GetBaseByToken_DuringGC()}

@item 
@ref{1f31,,PyType_GetFlags()}

@item 
@ref{80a,,PyType_GetFullyQualifiedName()}

@item 
@ref{d37,,PyType_GetModule()}

@item 
@ref{827,,PyType_GetModuleByDef()}

@item 
@ref{5419,,PyType_GetModuleByToken()}

@item 
@ref{373,,PyType_GetModuleByToken_DuringGC()}

@item 
@ref{80c,,PyType_GetModuleName()}

@item 
@ref{d38,,PyType_GetModuleState()}

@item 
@ref{36e,,PyType_GetModuleState_DuringGC()}

@item 
@ref{372,,PyType_GetModule_DuringGC()}

@item 
@ref{b36,,PyType_GetName()}

@item 
@ref{b37,,PyType_GetQualName()}

@item 
@ref{c72,,PyType_GetSlot()}

@item 
@ref{955,,PyType_GetTypeDataSize()}

@item 
@ref{541a,,PyType_IsSubtype()}

@item 
@ref{1d77,,PyType_Modified()}

@item 
@ref{b5e,,PyType_Ready()}

@item 
@ref{541b,,PyType_Slot}

@item 
@ref{1c8f,,PyType_Spec}

@item 
@ref{958,,PyType_Type}

@item 
@ref{541c,,PyUnicodeDecodeError_Create()}

@item 
@ref{541d,,PyUnicodeDecodeError_GetEncoding()}

@item 
@ref{541e,,PyUnicodeDecodeError_GetEnd()}

@item 
@ref{541f,,PyUnicodeDecodeError_GetObject()}

@item 
@ref{5420,,PyUnicodeDecodeError_GetReason()}

@item 
@ref{5421,,PyUnicodeDecodeError_GetStart()}

@item 
@ref{5422,,PyUnicodeDecodeError_SetEnd()}

@item 
@ref{5423,,PyUnicodeDecodeError_SetReason()}

@item 
@ref{5424,,PyUnicodeDecodeError_SetStart()}

@item 
@ref{5425,,PyUnicodeEncodeError_GetEncoding()}

@item 
@ref{1b1a,,PyUnicodeEncodeError_GetEnd()}

@item 
@ref{5426,,PyUnicodeEncodeError_GetObject()}

@item 
@ref{5427,,PyUnicodeEncodeError_GetReason()}

@item 
@ref{1b1d,,PyUnicodeEncodeError_GetStart()}

@item 
@ref{5428,,PyUnicodeEncodeError_SetEnd()}

@item 
@ref{5429,,PyUnicodeEncodeError_SetReason()}

@item 
@ref{542a,,PyUnicodeEncodeError_SetStart()}

@item 
@ref{542b,,PyUnicodeIter_Type}

@item 
@ref{542c,,PyUnicodeTranslateError_GetEnd()}

@item 
@ref{542d,,PyUnicodeTranslateError_GetObject()}

@item 
@ref{542e,,PyUnicodeTranslateError_GetReason()}

@item 
@ref{542f,,PyUnicodeTranslateError_GetStart()}

@item 
@ref{5430,,PyUnicodeTranslateError_SetEnd()}

@item 
@ref{5431,,PyUnicodeTranslateError_SetReason()}

@item 
@ref{5432,,PyUnicodeTranslateError_SetStart()}

@item 
@ref{5433,,PyUnicode_Append()}

@item 
@ref{5434,,PyUnicode_AppendAndDel()}

@item 
@ref{153b,,PyUnicode_AsASCIIString()}

@item 
@ref{5435,,PyUnicode_AsCharmapString()}

@item 
@ref{5436,,PyUnicode_AsEncodedString()}

@item 
@ref{153a,,PyUnicode_AsLatin1String()}

@item 
@ref{153c,,PyUnicode_AsMBCSString()}

@item 
@ref{1539,,PyUnicode_AsRawUnicodeEscapeString()}

@item 
@ref{1521,,PyUnicode_AsUCS4()}

@item 
@ref{c8e,,PyUnicode_AsUCS4Copy()}

@item 
@ref{5437,,PyUnicode_AsUTF16String()}

@item 
@ref{5438,,PyUnicode_AsUTF32String()}

@item 
@ref{c6f,,PyUnicode_AsUTF8AndSize()}

@item 
@ref{1537,,PyUnicode_AsUTF8String()}

@item 
@ref{1538,,PyUnicode_AsUnicodeEscapeString()}

@item 
@ref{2025,,PyUnicode_AsWideChar()}

@item 
@ref{c8f,,PyUnicode_AsWideCharString()}

@item 
@ref{1c68,,PyUnicode_BuildEncodingMap()}

@item 
@ref{c8a,,PyUnicode_Compare()}

@item 
@ref{160c,,PyUnicode_CompareWithASCIIString()}

@item 
@ref{154a,,PyUnicode_Concat()}

@item 
@ref{5439,,PyUnicode_Contains()}

@item 
@ref{543a,,PyUnicode_Count()}

@item 
@ref{1fb7,,PyUnicode_Decode()}

@item 
@ref{543b,,PyUnicode_DecodeASCII()}

@item 
@ref{543c,,PyUnicode_DecodeCharmap()}

@item 
@ref{543d,,PyUnicode_DecodeCodePageStateful()}

@item 
@ref{1c8e,,PyUnicode_DecodeFSDefault()}

@item 
@ref{543e,,PyUnicode_DecodeFSDefaultAndSize()}

@item 
@ref{543f,,PyUnicode_DecodeLatin1()}

@item 
@ref{5440,,PyUnicode_DecodeLocale()}

@item 
@ref{f87,,PyUnicode_DecodeLocaleAndSize()}

@item 
@ref{5441,,PyUnicode_DecodeMBCS()}

@item 
@ref{5442,,PyUnicode_DecodeMBCSStateful()}

@item 
@ref{5443,,PyUnicode_DecodeRawUnicodeEscape()}

@item 
@ref{5444,,PyUnicode_DecodeUTF16()}

@item 
@ref{5445,,PyUnicode_DecodeUTF16Stateful()}

@item 
@ref{5446,,PyUnicode_DecodeUTF32()}

@item 
@ref{5447,,PyUnicode_DecodeUTF32Stateful()}

@item 
@ref{5448,,PyUnicode_DecodeUTF7()}

@item 
@ref{5449,,PyUnicode_DecodeUTF7Stateful()}

@item 
@ref{544a,,PyUnicode_DecodeUTF8()}

@item 
@ref{1d15,,PyUnicode_DecodeUTF8Stateful()}

@item 
@ref{544b,,PyUnicode_DecodeUnicodeEscape()}

@item 
@ref{153d,,PyUnicode_EncodeCodePage()}

@item 
@ref{201e,,PyUnicode_EncodeFSDefault()}

@item 
@ref{f88,,PyUnicode_EncodeLocale()}

@item 
@ref{5df,,PyUnicode_Equal()}

@item 
@ref{80e,,PyUnicode_EqualToUTF8()}

@item 
@ref{80d,,PyUnicode_EqualToUTF8AndSize()}

@item 
@ref{10d3,,PyUnicode_FSConverter()}

@item 
@ref{97b,,PyUnicode_FSDecoder()}

@item 
@ref{544c,,PyUnicode_Find()}

@item 
@ref{c8c,,PyUnicode_FindChar()}

@item 
@ref{544d,,PyUnicode_Format()}

@item 
@ref{544e,,PyUnicode_FromEncodedObject()}

@item 
@ref{81e,,PyUnicode_FromFormat()}

@item 
@ref{979,,PyUnicode_FromFormatV()}

@item 
@ref{544f,,PyUnicode_FromObject()}

@item 
@ref{5450,,PyUnicode_FromOrdinal()}

@item 
@ref{5451,,PyUnicode_FromString()}

@item 
@ref{5452,,PyUnicode_FromStringAndSize()}

@item 
@ref{1535,,PyUnicode_FromWideChar()}

@item 
@ref{5453,,PyUnicode_GetDefaultEncoding()}

@item 
@ref{c86,,PyUnicode_GetLength()}

@item 
@ref{3b5,,PyUnicode_InternFromString()}

@item 
@ref{c84,,PyUnicode_InternInPlace()}

@item 
@ref{1f78,,PyUnicode_IsIdentifier()}

@item 
@ref{154b,,PyUnicode_Join()}

@item 
@ref{1abc,,PyUnicode_Partition()}

@item 
@ref{1abd,,PyUnicode_RPartition()}

@item 
@ref{1abb,,PyUnicode_RSplit()}

@item 
@ref{151a,,PyUnicode_ReadChar()}

@item 
@ref{5454,,PyUnicode_Replace()}

@item 
@ref{5455,,PyUnicode_Resize()}

@item 
@ref{5456,,PyUnicode_RichCompare()}

@item 
@ref{5457,,PyUnicode_Split()}

@item 
@ref{5458,,PyUnicode_Splitlines()}

@item 
@ref{c89,,PyUnicode_Substring()}

@item 
@ref{c8b,,PyUnicode_Tailmatch()}

@item 
@ref{5459,,PyUnicode_Translate()}

@item 
@ref{545a,,PyUnicode_Type}

@item 
@ref{151b,,PyUnicode_WriteChar()}

@item 
@ref{492d,,PyVarObject}

@item 
@ref{545b,,PyVarObject.ob_base}

@item 
@ref{545c,,PyVarObject.ob_size}

@item 
@ref{95f,,PyVectorcall_Call()}

@item 
@ref{95e,,PyVectorcall_NARGS()}

@item 
@code{PyWeakReference}

@item 
@ref{3a4,,PyWeakref_GetRef()}

@item 
@ref{545d,,PyWeakref_NewProxy()}

@item 
@ref{1ddf,,PyWeakref_NewRef()}

@item 
@ref{545e,,PyWrapperDescr_Type}

@item 
@ref{545f,,PyWrapper_New()}

@item 
@ref{5460,,PyZip_Type}

@item 
@ref{5461,,Py_ASNATIVEBYTES_ALLOW_INDEX}

@item 
@ref{5462,,Py_ASNATIVEBYTES_BIG_ENDIAN}

@item 
@ref{5463,,Py_ASNATIVEBYTES_DEFAULTS}

@item 
@ref{5464,,Py_ASNATIVEBYTES_LITTLE_ENDIAN}

@item 
@ref{5465,,Py_ASNATIVEBYTES_NATIVE_ENDIAN}

@item 
@ref{5466,,Py_ASNATIVEBYTES_REJECT_NEGATIVE}

@item 
@ref{5467,,Py_ASNATIVEBYTES_UNSIGNED_BUFFER}

@item 
@ref{991,,Py_AUDIT_READ}

@item 
@ref{d49,,Py_AddPendingCall()}

@item 
@ref{5468,,Py_AtExit()}

@item 
@ref{51d4,,Py_BEGIN_ALLOW_THREADS}

@item 
@ref{5469,,Py_BEGIN_CRITICAL_SECTION}

@item 
@ref{546a,,Py_BEGIN_CRITICAL_SECTION2}

@item 
@ref{546b,,Py_BLOCK_THREADS}

@item 
@ref{5ee,,Py_BuildValue()}

@item 
@ref{d89,,Py_BytesMain()}

@item 
@ref{c5b,,Py_CompileString()}

@item 
@ref{546c,,Py_DecRef()}

@item 
@ref{f85,,Py_DecodeLocale()}

@item 
@ref{e4e,,Py_END_ALLOW_THREADS}

@item 
@ref{546d,,Py_END_CRITICAL_SECTION}

@item 
@ref{546e,,Py_END_CRITICAL_SECTION2}

@item 
@ref{f86,,Py_EncodeLocale()}

@item 
@ref{1a6f,,Py_EndInterpreter()}

@item 
@ref{5fe,,Py_EnterRecursiveCall()}

@item 
@ref{1104,,Py_Exit()}

@item 
@ref{d4b,,Py_FatalError()}

@item 
@code{Py_FileSystemDefaultEncodeErrors}

@item 
@code{Py_FileSystemDefaultEncoding}

@item 
@ref{672,,Py_Finalize()}

@item 
@ref{10cf,,Py_FinalizeEx()}

@item 
@ref{546f,,Py_GenericAlias()}

@item 
@ref{5470,,Py_GenericAliasType}

@item 
@ref{17d4,,Py_GetBuildInfo()}

@item 
@ref{5471,,Py_GetCompiler()}

@item 
@ref{7ef,,Py_GetConstant()}

@item 
@ref{7f0,,Py_GetConstantBorrowed()}

@item 
@ref{5472,,Py_GetCopyright()}

@item 
@ref{5473,,Py_GetPlatform()}

@item 
@ref{5474,,Py_GetRecursionLimit()}

@item 
@ref{5475,,Py_GetVersion()}

@item 
@code{Py_HasFileSystemDefaultEncoding}

@item 
@ref{19bb,,Py_IS_TYPE()}

@item 
@ref{5476,,Py_IncRef()}

@item 
@ref{673,,Py_Initialize()}

@item 
@ref{5477,,Py_InitializeEx()}

@item 
@ref{c76,,Py_Is()}

@item 
@ref{c79,,Py_IsFalse()}

@item 
@ref{7f3,,Py_IsFinalizing()}

@item 
@ref{191f,,Py_IsInitialized()}

@item 
@ref{c77,,Py_IsNone()}

@item 
@ref{c78,,Py_IsTrue()}

@item 
@ref{d3c,,Py_LeaveRecursiveCall()}

@item 
@ref{fe2,,Py_Main()}

@item 
@ref{5478,,Py_MakePendingCalls()}

@item 
@ref{1d2f,,Py_NewInterpreter()}

@item 
@ref{c70,,Py_NewRef()}

@item 
@ref{5ad,,Py_PACK_FULL_VERSION()}

@item 
@ref{5ac,,Py_PACK_VERSION()}

@item 
@ref{990,,Py_READONLY}

@item 
@ref{54b,,Py_REFCNT()}

@item 
@ref{959,,Py_RELATIVE_OFFSET}

@item 
@ref{5479,,Py_ReprEnter()}

@item 
@ref{547a,,Py_ReprLeave()}

@item 
@ref{b62,,Py_SET_SIZE()}

@item 
@ref{b61,,Py_SIZE()}

@item 
@ref{1bc0,,Py_SetProgramName()}

@item 
@ref{1bbf,,Py_SetPythonHome()}

@item 
@ref{547b,,Py_SetRecursionLimit()}

@item 
@ref{51ea,,Py_TPFLAGS_BASETYPE}

@item 
@ref{51e0,,Py_TPFLAGS_DEFAULT}

@item 
@ref{39e,,Py_TPFLAGS_HAVE_GC}

@item 
@ref{95d,,Py_TPFLAGS_HAVE_VECTORCALL}

@item 
@ref{956,,Py_TPFLAGS_ITEMS_AT_END}

@item 
@ref{547c,,Py_TPFLAGS_METHOD_DESCRIPTOR}

@item 
@ref{547d,,Py_TP_USE_SPEC}

@item 
@ref{5f5,,Py_TYPE()}

@item 
@ref{547e,,Py_T_BOOL}

@item 
@ref{547f,,Py_T_BYTE}

@item 
@ref{5480,,Py_T_CHAR}

@item 
@ref{98f,,Py_T_DOUBLE}

@item 
@ref{5481,,Py_T_FLOAT}

@item 
@ref{98e,,Py_T_INT}

@item 
@ref{5482,,Py_T_LONG}

@item 
@ref{5483,,Py_T_LONGLONG}

@item 
@ref{993,,Py_T_OBJECT_EX}

@item 
@ref{5484,,Py_T_PYSSIZET}

@item 
@ref{5485,,Py_T_SHORT}

@item 
@ref{5486,,Py_T_STRING}

@item 
@ref{5487,,Py_T_STRING_INPLACE}

@item 
@ref{5488,,Py_T_UBYTE}

@item 
@ref{5489,,Py_T_UINT}

@item 
@ref{548a,,Py_T_ULONG}

@item 
@ref{548b,,Py_T_ULONGLONG}

@item 
@ref{548c,,Py_T_USHORT}

@item 
@ref{301,,Py_UCS4}

@item 
@ref{548d,,Py_UNBLOCK_THREADS}

@item 
@code{Py_UTF8Mode}

@item 
@ref{548e,,Py_VaBuildValue()}

@item 
@ref{5ae,,Py_Version}

@item 
@ref{c71,,Py_XNewRef()}

@item 
@ref{548f,,Py_am_aiter}

@item 
@ref{5490,,Py_am_anext}

@item 
@ref{5491,,Py_am_await}

@item 
@ref{5492,,Py_am_send}

@item 
@ref{5493,,Py_bf_getbuffer}

@item 
@ref{5494,,Py_bf_releasebuffer}

@item 
@ref{b3a,,Py_buffer}

@item 
@code{Py_intptr_t}

@item 
@ref{358,,Py_mod_abi}

@item 
@ref{5495,,Py_mod_create}

@item 
@ref{51a1,,Py_mod_doc}

@item 
@ref{d46,,Py_mod_exec}

@item 
@ref{691,,Py_mod_gil}

@item 
@ref{51a6,,Py_mod_methods}

@item 
@ref{5496,,Py_mod_multiple_interpreters}

@item 
@ref{51a0,,Py_mod_name}

@item 
@ref{37b,,Py_mod_slots}

@item 
@ref{5497,,Py_mod_state_clear}

@item 
@ref{5498,,Py_mod_state_free}

@item 
@ref{5499,,Py_mod_state_size}

@item 
@ref{549a,,Py_mod_state_traverse}

@item 
@ref{549b,,Py_mod_token}

@item 
@ref{549c,,Py_mp_ass_subscript}

@item 
@ref{549d,,Py_mp_length}

@item 
@ref{549e,,Py_mp_subscript}

@item 
@ref{549f,,Py_nb_absolute}

@item 
@ref{54a0,,Py_nb_add}

@item 
@ref{54a1,,Py_nb_and}

@item 
@ref{54a2,,Py_nb_bool}

@item 
@ref{54a3,,Py_nb_divmod}

@item 
@ref{54a4,,Py_nb_float}

@item 
@ref{54a5,,Py_nb_floor_divide}

@item 
@ref{54a6,,Py_nb_index}

@item 
@ref{54a7,,Py_nb_inplace_add}

@item 
@ref{54a8,,Py_nb_inplace_and}

@item 
@ref{54a9,,Py_nb_inplace_floor_divide}

@item 
@ref{54aa,,Py_nb_inplace_lshift}

@item 
@ref{54ab,,Py_nb_inplace_matrix_multiply}

@item 
@ref{54ac,,Py_nb_inplace_multiply}

@item 
@ref{54ad,,Py_nb_inplace_or}

@item 
@ref{54ae,,Py_nb_inplace_power}

@item 
@ref{54af,,Py_nb_inplace_remainder}

@item 
@ref{54b0,,Py_nb_inplace_rshift}

@item 
@ref{54b1,,Py_nb_inplace_subtract}

@item 
@ref{54b2,,Py_nb_inplace_true_divide}

@item 
@ref{54b3,,Py_nb_inplace_xor}

@item 
@ref{54b4,,Py_nb_int}

@item 
@ref{54b5,,Py_nb_invert}

@item 
@ref{54b6,,Py_nb_lshift}

@item 
@ref{54b7,,Py_nb_matrix_multiply}

@item 
@ref{54b8,,Py_nb_multiply}

@item 
@ref{54b9,,Py_nb_negative}

@item 
@ref{54ba,,Py_nb_or}

@item 
@ref{54bb,,Py_nb_positive}

@item 
@ref{54bc,,Py_nb_power}

@item 
@ref{54bd,,Py_nb_remainder}

@item 
@ref{54be,,Py_nb_rshift}

@item 
@ref{54bf,,Py_nb_subtract}

@item 
@ref{54c0,,Py_nb_true_divide}

@item 
@ref{54c1,,Py_nb_xor}

@item 
@ref{377,,Py_slot_end}

@item 
@ref{378,,Py_slot_invalid}

@item 
@ref{379,,Py_slot_subslots}

@item 
@ref{54c2,,Py_sq_ass_item}

@item 
@ref{54c3,,Py_sq_concat}

@item 
@ref{54c4,,Py_sq_contains}

@item 
@ref{54c5,,Py_sq_inplace_concat}

@item 
@ref{54c6,,Py_sq_inplace_repeat}

@item 
@ref{54c7,,Py_sq_item}

@item 
@ref{54c8,,Py_sq_length}

@item 
@ref{54c9,,Py_sq_repeat}

@item 
@ref{e24,,Py_ssize_t}

@item 
@ref{54ca,,Py_tp_alloc}

@item 
@ref{54cb,,Py_tp_base}

@item 
@ref{54cc,,Py_tp_bases}

@item 
@ref{37d,,Py_tp_basicsize}

@item 
@ref{54cd,,Py_tp_call}

@item 
@ref{54ce,,Py_tp_clear}

@item 
@ref{54cf,,Py_tp_dealloc}

@item 
@ref{54d0,,Py_tp_del}

@item 
@ref{54d1,,Py_tp_descr_get}

@item 
@ref{54d2,,Py_tp_descr_set}

@item 
@ref{54d3,,Py_tp_doc}

@item 
@ref{37e,,Py_tp_extra_basicsize}

@item 
@ref{54d4,,Py_tp_finalize}

@item 
@ref{380,,Py_tp_flags}

@item 
@ref{54d5,,Py_tp_free}

@item 
@ref{54d6,,Py_tp_getattr}

@item 
@ref{54d7,,Py_tp_getattro}

@item 
@ref{54d8,,Py_tp_getset}

@item 
@ref{54d9,,Py_tp_hash}

@item 
@ref{54da,,Py_tp_init}

@item 
@ref{54db,,Py_tp_is_gc}

@item 
@ref{37f,,Py_tp_itemsize}

@item 
@ref{54dc,,Py_tp_iter}

@item 
@ref{54dd,,Py_tp_iternext}

@item 
@ref{54de,,Py_tp_members}

@item 
@ref{381,,Py_tp_metaclass}

@item 
@ref{54df,,Py_tp_methods}

@item 
@ref{382,,Py_tp_module}

@item 
@ref{37c,,Py_tp_name}

@item 
@ref{54e0,,Py_tp_new}

@item 
@ref{54e1,,Py_tp_repr}

@item 
@ref{54e2,,Py_tp_richcompare}

@item 
@ref{54e3,,Py_tp_setattr}

@item 
@ref{54e4,,Py_tp_setattro}

@item 
@ref{37a,,Py_tp_slots}

@item 
@ref{54e5,,Py_tp_str}

@item 
@ref{5de,,Py_tp_token}

@item 
@ref{54e6,,Py_tp_traverse}

@item 
@ref{54e7,,Py_tp_vectorcall}

@item 
@code{Py_uintptr_t}

@item 
@ref{54e8,,allocfunc}

@item 
@ref{54e9,,binaryfunc}

@item 
@ref{54ea,,descrgetfunc}

@item 
@ref{54eb,,descrsetfunc}

@item 
@ref{54ec,,destructor}

@item 
@ref{54ed,,getattrfunc}

@item 
@ref{54ee,,getattrofunc}

@item 
@ref{54ef,,getbufferproc}

@item 
@ref{54f0,,getiterfunc}

@item 
@ref{54f1,,getter}

@item 
@ref{54f2,,hashfunc}

@item 
@ref{54f3,,initproc}

@item 
@ref{54f4,,inquiry}

@item 
@ref{54f5,,iternextfunc}

@item 
@ref{54f6,,lenfunc}

@item 
@ref{54f7,,newfunc}

@item 
@ref{54f8,,objobjargproc}

@item 
@ref{54f9,,objobjproc}

@item 
@ref{54fa,,releasebufferproc}

@item 
@ref{54fb,,reprfunc}

@item 
@ref{54fc,,richcmpfunc}

@item 
@ref{54fd,,setattrfunc}

@item 
@ref{54fe,,setattrofunc}

@item 
@ref{54ff,,setter}

@item 
@ref{5500,,ssizeargfunc}

@item 
@ref{5501,,ssizeobjargproc}

@item 
@code{ssizessizeargfunc}

@item 
@code{ssizessizeobjargproc}

@item 
@code{symtable}

@item 
@ref{5502,,ternaryfunc}

@item 
@ref{5503,,traverseproc}

@item 
@ref{5504,,unaryfunc}

@item 
@ref{960,,vectorcallfunc}

@item 
@ref{5505,,visitproc}
@end itemize


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node The Very High Level Layer,Reference Counting,C API and ABI Stability,Python/C API reference manual
@anchor{c-api/veryhigh doc}@anchor{5506}@anchor{c-api/veryhigh the-very-high-level-layer}@anchor{5507}@anchor{c-api/veryhigh translation-repo}@anchor{5508}@anchor{c-api/veryhigh veryhigh}@anchor{5509}
@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{550a,,Py_eval_input},
@ref{550b,,Py_file_input}, @ref{550c,,Py_single_input}, and
@ref{550d,,Py_func_type_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{550e}
@deffn {C Συνάρτηση} int PyRun_AnyFile (FILE *fp, const char *filename)

This is a simplified interface to @ref{550f,,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{5510}
@deffn {C Συνάρτηση} int PyRun_AnyFileFlags (FILE *fp, const char *filename, PyCompilerFlags *flags)

This is a simplified interface to @ref{550f,,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{5511}
@deffn {C Συνάρτηση} int PyRun_AnyFileEx (FILE *fp, const char *filename, int closeit)

This is a simplified interface to @ref{550f,,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{550f}
@deffn {C Συνάρτηση} 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{5512,,PyRun_InteractiveLoop()}, otherwise return the result of
@ref{5222,,PyRun_SimpleFile()}.  `filename' is decoded from the filesystem
encoding (@ref{1017,,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{5221}
@deffn {C Συνάρτηση} int PyRun_SimpleString (const char *command)

This is a simplified interface to @ref{5513,,PyRun_SimpleStringFlags()} below,
leaving the @ref{e67,,PyCompilerFlags}* argument set to @code{NULL}.
@end deffn

@geindex PyRun_SimpleStringFlags (C function)
@anchor{c-api/veryhigh c PyRun_SimpleStringFlags}@anchor{5513}
@deffn {C Συνάρτηση} 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 @code{__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{10f7,,SystemExit} is raised, this
function will not return @code{-1}, but exit the process, as long as
@ref{615,,PyConfig.inspect} is zero.
@end deffn

@geindex PyRun_SimpleFile (C function)
@anchor{c-api/veryhigh c PyRun_SimpleFile}@anchor{5222}
@deffn {C Συνάρτηση} int PyRun_SimpleFile (FILE *fp, const char *filename)

This is a simplified interface to @ref{1ec0,,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{5514}
@deffn {C Συνάρτηση} int PyRun_SimpleFileEx (FILE *fp, const char *filename, int closeit)

This is a simplified interface to @ref{1ec0,,PyRun_SimpleFileExFlags()} below,
leaving `flags' set to @code{NULL}.
@end deffn

@geindex PyRun_SimpleFileExFlags (C function)
@anchor{c-api/veryhigh c PyRun_SimpleFileExFlags}@anchor{1ec0}
@deffn {C Συνάρτηση} int PyRun_SimpleFileExFlags (FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

Similar to @ref{5513,,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{948,,filesystem encoding and error handler}.
If `closeit' is true, the file is closed before
@code{PyRun_SimpleFileExFlags()} returns.

@cartouche
@quotation Σημείωση 
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_InteractiveOneObject (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveOneObject}@anchor{5515}
@deffn {C Συνάρτηση} int PyRun_InteractiveOneObject (FILE *fp, PyObject *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' must be a Python
@ref{1df,,str} object.

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_InteractiveOne (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveOne}@anchor{5516}
@deffn {C Συνάρτηση} int PyRun_InteractiveOne (FILE *fp, const char *filename)

This is a simplified interface to @ref{5517,,PyRun_InteractiveOneFlags()} below,
leaving `flags' set to @code{NULL}.
@end deffn

@geindex PyRun_InteractiveOneFlags (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveOneFlags}@anchor{5517}
@deffn {C Συνάρτηση} int PyRun_InteractiveOneFlags (FILE *fp, const char *filename, PyCompilerFlags *flags)

Similar to @ref{5515,,PyRun_InteractiveOneObject()}, but `filename' is a
const char*, which is decoded from the
@ref{948,,filesystem encoding and error handler}.
@end deffn

@geindex PyRun_InteractiveLoop (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveLoop}@anchor{5512}
@deffn {C Συνάρτηση} int PyRun_InteractiveLoop (FILE *fp, const char *filename)

This is a simplified interface to @ref{5518,,PyRun_InteractiveLoopFlags()} below,
leaving `flags' set to @code{NULL}.
@end deffn

@geindex PyRun_InteractiveLoopFlags (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveLoopFlags}@anchor{5518}
@deffn {C Συνάρτηση} 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{948,,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{986}
@deffn {C Μεταβλητή} int (*PyOS_InputHook)(void)
` Μέρος του @ref{95c,,Σταθερό 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 @code{Modules/_tkinter.c} in the
Python source code.


Άλλαξε στην έκδοση 3.12: This function is only called from the
@ref{410,,main interpreter}.

@end deffn

@geindex PyOS_ReadlineFunctionPointer (C var)
@anchor{c-api/veryhigh c PyOS_ReadlineFunctionPointer}@anchor{987}
@deffn {C Μεταβλητή} 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{c2,,readline} module sets
this hook to provide line-editing and tab-completion features.

The result must be a string allocated by @ref{2bf,,PyMem_RawMalloc()} or
@ref{825,,PyMem_RawRealloc()}, or @code{NULL} if an error occurred.


Άλλαξε στην έκδοση 3.4: The result must be allocated by @ref{2bf,,PyMem_RawMalloc()} or
@ref{825,,PyMem_RawRealloc()}, instead of being allocated by
@ref{1024,,PyMem_Malloc()} or @ref{13da,,PyMem_Realloc()}.



Άλλαξε στην έκδοση 3.12: This function is only called from the
@ref{410,,main interpreter}.

@end deffn

@geindex PyRun_String (C function)
@anchor{c-api/veryhigh c PyRun_String}@anchor{1fb0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyRun_String (const char *str, int start, PyObject *globals, PyObject *locals)
`Επιστρεφόμενη τιμή: New reference.'
This is a simplified interface to @ref{5519,,PyRun_StringFlags()} below, leaving
`flags' set to @code{NULL}.
@end deffn

@geindex PyRun_StringFlags (C function)
@anchor{c-api/veryhigh c PyRun_StringFlags}@anchor{5519}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyRun_StringFlags (const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
`Επιστρεφόμενη τιμή: New reference.'
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 symbol and must be one of the @ref{551a,,available start symbols}.

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{551b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyRun_File (FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
`Επιστρεφόμενη τιμή: New reference.'
This is a simplified interface to @ref{551c,,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{551d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyRun_FileEx (FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
`Επιστρεφόμενη τιμή: New reference.'
This is a simplified interface to @ref{551c,,PyRun_FileExFlags()} below, leaving
`flags' set to @code{NULL}.
@end deffn

@geindex PyRun_FileFlags (C function)
@anchor{c-api/veryhigh c PyRun_FileFlags}@anchor{551e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyRun_FileFlags (FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
`Επιστρεφόμενη τιμή: New reference.'
This is a simplified interface to @ref{551c,,PyRun_FileExFlags()} below, leaving
`closeit' set to @code{0}.
@end deffn

@geindex PyRun_FileExFlags (C function)
@anchor{c-api/veryhigh c PyRun_FileExFlags}@anchor{551c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyRun_FileExFlags (FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
`Επιστρεφόμενη τιμή: New reference.'
Similar to @ref{5519,,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{948,,filesystem encoding and error handler}.
If `closeit' is true, the file is closed before @ref{551c,,PyRun_FileExFlags()}
returns.
@end deffn

@geindex Py_CompileString (C function)
@anchor{c-api/veryhigh c Py_CompileString}@anchor{c5b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *Py_CompileString (const char *str, const char *filename, int start)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is a simplified interface to @ref{551f,,Py_CompileStringFlags()} below, leaving
`flags' set to @code{NULL}.
@end deffn

@geindex Py_CompileStringFlags (C function)
@anchor{c-api/veryhigh c Py_CompileStringFlags}@anchor{551f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *Py_CompileStringFlags (const char *str, const char *filename, int start, PyCompilerFlags *flags)
`Επιστρεφόμενη τιμή: New reference.'
This is a simplified interface to @ref{5520,,Py_CompileStringExFlags()} below, with
`optimize' set to @code{-1}.
@end deffn

@geindex Py_CompileStringObject (C function)
@anchor{c-api/veryhigh c Py_CompileStringObject}@anchor{5521}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *Py_CompileStringObject (const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
`Επιστρεφόμενη τιμή: New reference.'
Parse and compile the Python source code in `str', returning the resulting code
object.  The start symbol is given by `start'; this can be used to constrain the
code which can be compiled and should be @ref{551a,,available start symbols}.  The filename specified by
`filename' is used to construct the code object and may appear in tracebacks or
@ref{17e,,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{431,,-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).


Added in version 3.4.

@end deffn

@geindex Py_CompileStringExFlags (C function)
@anchor{c-api/veryhigh c Py_CompileStringExFlags}@anchor{5520}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *Py_CompileStringExFlags (const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
`Επιστρεφόμενη τιμή: New reference.'
Like @ref{5521,,Py_CompileStringObject()}, but `filename' is a byte string
decoded from the @ref{948,,filesystem encoding and error handler}.


Added in version 3.2.

@end deffn

@geindex PyEval_EvalCode (C function)
@anchor{c-api/veryhigh c PyEval_EvalCode}@anchor{c5c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyEval_EvalCode (PyObject *co, PyObject *globals, PyObject *locals)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is a simplified interface to @ref{1cd9,,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{1cd9}
@deffn {C Συνάρτηση} @ref{19b,,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)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{7a3,,keyword-only} arguments and a closure tuple of cells.
@end deffn

@geindex PyEval_EvalFrame (C function)
@anchor{c-api/veryhigh c PyEval_EvalFrame}@anchor{5305}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyEval_EvalFrame (PyFrameObject *f)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Evaluate an execution frame.  This is a simplified interface to
@ref{13d6,,PyEval_EvalFrameEx()}, for backward compatibility.
@end deffn

@geindex PyEval_EvalFrameEx (C function)
@anchor{c-api/veryhigh c PyEval_EvalFrameEx}@anchor{13d6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyEval_EvalFrameEx (PyFrameObject *f, int throwflag)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{905,,throw()}
methods of generator objects.


Άλλαξε στην έκδοση 3.4: This function now includes a debug assertion to help ensure that it
does not silently discard an active exception.

@end deffn

@geindex PyEval_MergeCompilerFlags (C function)
@anchor{c-api/veryhigh c PyEval_MergeCompilerFlags}@anchor{5522}
@deffn {C Συνάρτηση} 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 PyCompilerFlags (C struct)
@anchor{c-api/veryhigh c PyCompilerFlags}@anchor{e67}
@deffn {C Struct} 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{5523,,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{5523}
@deffn {C Μέλος} int cf_flags

Compiler flags.
@end deffn

@geindex PyCompilerFlags.cf_feature_version (C member)
@anchor{c-api/veryhigh c PyCompilerFlags cf_feature_version}@anchor{5524}
@deffn {C Μέλος} 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{5523,,cf_flags}.
@end deffn


Άλλαξε στην έκδοση 3.8: Added `cf_feature_version' field.


The available compiler flags are accessible as macros:

@geindex PyCF_ALLOW_TOP_LEVEL_AWAIT (C macro)
@geindex PyCF_ONLY_AST (C macro)
@geindex PyCF_OPTIMIZED_AST (C macro)
@geindex PyCF_TYPE_COMMENTS (C macro)
@anchor{c-api/veryhigh c PyCF_ALLOW_TOP_LEVEL_AWAIT}@anchor{5525}
@deffn {C Μακροεντολή} PyCF_ALLOW_TOP_LEVEL_AWAIT
@anchor{c-api/veryhigh c PyCF_ONLY_AST}@anchor{5526}
@deffnx {C Μακροεντολή} PyCF_ONLY_AST
@anchor{c-api/veryhigh c PyCF_OPTIMIZED_AST}@anchor{5527}
@deffnx {C Μακροεντολή} PyCF_OPTIMIZED_AST
@anchor{c-api/veryhigh c PyCF_TYPE_COMMENTS}@anchor{5528}
@deffnx {C Μακροεντολή} PyCF_TYPE_COMMENTS

See @ref{27c0,,compiler flags} in documentation of the
@code{ast} Python module, which exports these constants under
the same names.
@end deffn

The «@code{PyCF}» flags above can be combined with «@code{CO_FUTURE}» flags such
as @ref{5529,,CO_FUTURE_ANNOTATIONS} to enable features normally
selectable using @ref{670,,future statements}.
See @ref{552a,,Code Object Flags} for a complete list.
@end deffn

@menu
* Available start symbols:: 
* Stack Effects:: 

@end menu

@node Available start symbols,Stack Effects,,The Very High Level Layer
@anchor{c-api/veryhigh available-start-symbols}@anchor{552b}@anchor{c-api/veryhigh start-symbols}@anchor{551a}
@subsection Available start symbols


@geindex Py_eval_input (C var)
@anchor{c-api/veryhigh c Py_eval_input}@anchor{550a}
@deffn {C Μεταβλητή} int Py_eval_input

@geindex Py_CompileString (C function)

The start symbol from the Python grammar for isolated expressions; for use with
@ref{c5b,,Py_CompileString()}.
@end deffn

@geindex Py_file_input (C var)
@anchor{c-api/veryhigh c Py_file_input}@anchor{550b}
@deffn {C Μεταβλητή} 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{c5b,,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{550c}
@deffn {C Μεταβλητή} int Py_single_input

@geindex Py_CompileString (C function)

The start symbol from the Python grammar for a single statement; for use with
@ref{c5b,,Py_CompileString()}. This is the symbol used for the interactive
interpreter loop.
@end deffn

@geindex Py_func_type_input (C var)
@anchor{c-api/veryhigh c Py_func_type_input}@anchor{550d}
@deffn {C Μεταβλητή} int Py_func_type_input

@geindex Py_CompileString (C function)

The start symbol from the Python grammar for a function type; for use with
@ref{c5b,,Py_CompileString()}. This is used to parse «signature type comments»
from 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}.

This requires the @ref{5526,,PyCF_ONLY_AST} flag to be set.


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{4e70,,ast.FunctionType}

@item 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}
@end itemize



Added in version 3.8.

@end deffn

@node Stack Effects,,Available start symbols,The Very High Level Layer
@anchor{c-api/veryhigh stack-effects}@anchor{552c}
@subsection Stack Effects



@subsubheading Δείτε επίσης


@ref{12dc,,dis.stack_effect()}


@geindex PY_INVALID_STACK_EFFECT (C macro)
@anchor{c-api/veryhigh c PY_INVALID_STACK_EFFECT}@anchor{552d}
@deffn {C Μακροεντολή} PY_INVALID_STACK_EFFECT

Sentinel value representing an invalid stack effect.

This is currently equivalent to @code{INT_MAX}.


Added in version 3.8.

@end deffn

@geindex PyCompile_OpcodeStackEffect (C function)
@anchor{c-api/veryhigh c PyCompile_OpcodeStackEffect}@anchor{552e}
@deffn {C Συνάρτηση} int PyCompile_OpcodeStackEffect (int opcode, int oparg)

Compute the stack effect of `opcode' with argument `oparg'.

On success, this function returns the stack effect; on failure, this
returns @ref{552d,,PY_INVALID_STACK_EFFECT}.


Added in version 3.4.

@end deffn

@geindex PyCompile_OpcodeStackEffectWithJump (C function)
@anchor{c-api/veryhigh c PyCompile_OpcodeStackEffectWithJump}@anchor{201f}
@deffn {C Συνάρτηση} int PyCompile_OpcodeStackEffectWithJump (int opcode, int oparg, int jump)

Similar to @ref{552e,,PyCompile_OpcodeStackEffect()}, but don’t include the
stack effect of jumping if `jump' is zero.

If `jump' is @code{0}, this will not include the stack effect of jumping, but
if `jump' is @code{1} or @code{-1}, this will include it.

On success, this function returns the stack effect; on failure, this
returns @ref{552d,,PY_INVALID_STACK_EFFECT}.


Added in version 3.8.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Reference Counting,Exception Handling,The Very High Level Layer,Python/C API reference manual
@anchor{c-api/refcounting doc}@anchor{552f}@anchor{c-api/refcounting countingrefs}@anchor{5530}@anchor{c-api/refcounting reference-counting}@anchor{5531}@anchor{c-api/refcounting translation-repo}@anchor{5532}
@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{54b}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} Py_REFCNT (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
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{398,,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{c7e,,Py_SET_REFCNT()} function to set an object reference count.

@cartouche
@quotation Σημείωση 
On @ref{198,,free-threaded builds} of Python, returning 1
isn’t sufficient to determine if it’s safe to treat `o' as having no
access by other threads. Use @ref{5f2,,PyUnstable_Object_IsUniquelyReferenced()}
for that instead.

See also the function @ref{5f3,,PyUnstable_Object_IsUniqueReferencedTemporary()}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.10: @ref{54b,,Py_REFCNT()} is changed to the inline static function.



Άλλαξε στην έκδοση 3.11: The parameter type is no longer const @ref{19b,,PyObject}*.

@end deffn

@geindex Py_SET_REFCNT (C function)
@anchor{c-api/refcounting c Py_SET_REFCNT}@anchor{c7e}
@deffn {C Συνάρτηση} void Py_SET_REFCNT (PyObject *o, Py_ssize_t refcnt)

Set the object `o' reference counter to `refcnt'.

On @ref{235a,,Python build with Free Threading}, if
`refcnt' is larger than @code{UINT32_MAX}, the object is made @ref{398,,immortal}.

This function has no effect on @ref{398,,immortal} objects.


Added in version 3.9.



Άλλαξε στην έκδοση 3.12: Immortal objects are not modified.

@end deffn

@geindex Py_INCREF (C function)
@anchor{c-api/refcounting c Py_INCREF}@anchor{974}
@deffn {C Συνάρτηση} void Py_INCREF (PyObject *o)

Indicate taking a new @ref{7da,,strong reference} to object `o',
indicating it is in use and should not be destroyed.

This function has no effect on @ref{398,,immortal} objects.

This function is usually used to convert a @ref{603,,borrowed reference} to a
@ref{7da,,strong reference} in-place. The @ref{c70,,Py_NewRef()} function can be
used to create a new strong reference.

When done using the object, release is by calling @ref{975,,Py_DECREF()}.

The object must not be @code{NULL}; if you aren’t sure that it isn’t
@code{NULL}, use @ref{e29,,Py_XINCREF()}.

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.


Άλλαξε στην έκδοση 3.12: Immortal objects are not modified.

@end deffn

@geindex Py_XINCREF (C function)
@anchor{c-api/refcounting c Py_XINCREF}@anchor{e29}
@deffn {C Συνάρτηση} void Py_XINCREF (PyObject *o)

Similar to @ref{974,,Py_INCREF()}, but the object `o' can be @code{NULL},
in which case this has no effect.

See also @ref{c71,,Py_XNewRef()}.
@end deffn

@geindex Py_NewRef (C function)
@anchor{c-api/refcounting c Py_NewRef}@anchor{c70}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *Py_NewRef (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Create a new @ref{7da,,strong reference} to an object:
call @ref{974,,Py_INCREF()} on `o' and return the object `o'.

When the @ref{7da,,strong reference} is no longer needed, @ref{975,,Py_DECREF()}
should be called on it to release the reference.

The object `o' must not be @code{NULL}; use @ref{c71,,Py_XNewRef()} if `o' can be
@code{NULL}.

For example:

@example
Py_INCREF(obj);
self->attr = obj;
@end example

can be written as:

@example
self->attr = Py_NewRef(obj);
@end example

See also @ref{974,,Py_INCREF()}.


Added in version 3.10.

@end deffn

@geindex Py_XNewRef (C function)
@anchor{c-api/refcounting c Py_XNewRef}@anchor{c71}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *Py_XNewRef (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Similar to @ref{c70,,Py_NewRef()}, but the object `o' can be NULL.

If the object `o' is @code{NULL}, the function just returns @code{NULL}.


Added in version 3.10.

@end deffn

@geindex Py_DECREF (C function)
@anchor{c-api/refcounting c Py_DECREF}@anchor{975}
@deffn {C Συνάρτηση} void Py_DECREF (PyObject *o)

Release a @ref{7da,,strong reference} to object `o', indicating the
reference is no longer used.

This function has no effect on @ref{398,,immortal} objects.

Once the last @ref{7da,,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.

This function is usually used to delete a @ref{7da,,strong reference} before
exiting its scope.

The object must not be @code{NULL}; if you aren’t sure that it isn’t @code{NULL},
use @ref{b6e,,Py_XDECREF()}.

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 Προειδοποίηση 
The deallocation function can cause arbitrary Python code to be invoked (e.g.
when a class instance with a @ref{13a6,,__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{975,,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 @code{Py_DECREF()} for the temporary variable.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.12: Immortal objects are not modified.

@end deffn

@geindex Py_XDECREF (C function)
@anchor{c-api/refcounting c Py_XDECREF}@anchor{b6e}
@deffn {C Συνάρτηση} void Py_XDECREF (PyObject *o)

Similar to @ref{975,,Py_DECREF()}, but the object `o' can be @code{NULL},
in which case this has no effect.
The same warning from @code{Py_DECREF()} applies here as well.
@end deffn

@geindex Py_CLEAR (C function)
@anchor{c-api/refcounting c Py_CLEAR}@anchor{97c}
@deffn {C Συνάρτηση} void Py_CLEAR (PyObject *o)

Release a @ref{7da,,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{975,,Py_DECREF()}, except that the argument is also set to @code{NULL}.  The warning
for @code{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.


Άλλαξε στην έκδοση 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{5476}
@deffn {C Συνάρτηση} void Py_IncRef (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Indicate taking a new @ref{7da,,strong reference} to object `o'.
A function version of @ref{e29,,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{546c}
@deffn {C Συνάρτηση} void Py_DecRef (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Release a @ref{7da,,strong reference} to object `o'.
A function version of @ref{b6e,,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{97d}
@deffn {C Μακροεντολή} Py_SETREF (dst, src)

Macro safely releasing a @ref{7da,,strong reference} to object `dst'
and setting `dst' to `src'.

As in case of @ref{97c,,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.


Added in version 3.6.



Άλλαξε στην έκδοση 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{97e}
@deffn {C Μακροεντολή} Py_XSETREF (dst, src)

Variant of @ref{97d,,Py_SETREF} macro that uses @ref{b6e,,Py_XDECREF()} instead
of @ref{975,,Py_DECREF()}.


Added in version 3.6.



Άλλαξε στην έκδοση 3.12: The macro arguments are now only evaluated once. If an argument has side
effects, these are no longer duplicated.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Exception Handling,Defining extension modules,Reference Counting,Python/C API reference manual
@anchor{c-api/exceptions doc}@anchor{5533}@anchor{c-api/exceptions exception-handling}@anchor{5534}@anchor{c-api/exceptions exceptionhandling}@anchor{4c68}@anchor{c-api/exceptions translation-repo}@anchor{5535}
@section Exception Handling


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 Σημείωση 
The error indicator is `not' the result of @ref{a7a,,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:: 
* Raising exceptions:: 
* Issuing warnings:: 
* Querying the error indicator:: 
* Signal Handling: Signal Handling<2>. 
* Exception Classes:: 
* Exception Objects:: 
* Unicode Exception Objects:: 
* Recursion Control:: 
* Exception and warning types:: 
* Tracebacks:: 

@end menu

@node Printing and clearing,Raising exceptions,,Exception Handling
@anchor{c-api/exceptions printing-and-clearing}@anchor{5536}
@subsection Printing and clearing


@geindex PyErr_Clear (C function)
@anchor{c-api/exceptions c PyErr_Clear}@anchor{13d9}
@deffn {C Συνάρτηση} void PyErr_Clear ()
` Μέρος του @ref{95c,,Σταθερό 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{52f8}
@deffn {C Συνάρτηση} void PyErr_PrintEx (int set_sys_last_vars)
` Μέρος του @ref{95c,,Σταθερό 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{8ce,,sys.last_exc} is
set to the printed exception. For backwards compatibility, the
deprecated variables @ref{8cf,,sys.last_type}, @ref{8d0,,sys.last_value} and
@ref{8d1,,sys.last_traceback} are also set to the type, value and traceback
of this exception, respectively.


Άλλαξε στην έκδοση 3.12: The setting of @ref{8ce,,sys.last_exc} was added.

@end deffn

@geindex PyErr_Print (C function)
@anchor{c-api/exceptions c PyErr_Print}@anchor{1f21}
@deffn {C Συνάρτηση} void PyErr_Print ()
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Alias for @code{PyErr_PrintEx(1)}.
@end deffn

@geindex PyErr_WriteUnraisable (C function)
@anchor{c-api/exceptions c PyErr_WriteUnraisable}@anchor{7e8}
@deffn {C Συνάρτηση} void PyErr_WriteUnraisable (PyObject *obj)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Call @ref{70c,,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{13a6,,__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.


Άλλαξε στην έκδοση 3.4: Print a traceback. Print only traceback if `obj' is @code{NULL}.



Άλλαξε στην έκδοση 3.8: Use @ref{70c,,sys.unraisablehook()}.

@end deffn

@geindex PyErr_FormatUnraisable (C function)
@anchor{c-api/exceptions c PyErr_FormatUnraisable}@anchor{7e7}
@deffn {C Συνάρτηση} void PyErr_FormatUnraisable (const char *format, ...)

Similar to @ref{7e8,,PyErr_WriteUnraisable()}, but the `format' and subsequent
parameters help format the warning message; they have the same meaning and
values as in @ref{81e,,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.


Added in version 3.13.

@end deffn

@geindex PyErr_DisplayException (C function)
@anchor{c-api/exceptions c PyErr_DisplayException}@anchor{648}
@deffn {C Συνάρτηση} void PyErr_DisplayException (PyObject *exc)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
Print the standard traceback display of @code{exc} to @code{sys.stderr}, including
chained exceptions and notes.


Added in version 3.12.

@end deffn

@node Raising exceptions,Issuing warnings,Printing and clearing,Exception Handling
@anchor{c-api/exceptions raising-exceptions}@anchor{5537}
@subsection Raising 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{980}
@deffn {C Συνάρτηση} void PyErr_SetString (PyObject *type, const char *message)
` Μέρος του @ref{95c,,Σταθερό 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. @ref{5336,,PyExc_RuntimeError}.  You need not create a new
@ref{7da,,strong reference} to it (e.g. with @ref{974,,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{97f}
@deffn {C Συνάρτηση} void PyErr_SetObject (PyObject *type, PyObject *value)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This function is similar to @ref{980,,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{1262}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_Format (PyObject *exception, const char *format, ...)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό 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{81e,,PyUnicode_FromFormat()}. `format' is an ASCII-encoded
string.
@end deffn

@geindex PyErr_FormatV (C function)
@anchor{c-api/exceptions c PyErr_FormatV}@anchor{1261}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_FormatV (PyObject *exception, const char *format, va_list vargs)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.5.'
Same as @ref{1262,,PyErr_Format()}, but taking a @code{va_list} argument rather
than a variable number of arguments.


Added in version 3.5.

@end deffn

@geindex PyErr_SetNone (C function)
@anchor{c-api/exceptions c PyErr_SetNone}@anchor{5301}
@deffn {C Συνάρτηση} void PyErr_SetNone (PyObject *type)
` Μέρος του @ref{95c,,Σταθερό 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{52f5}
@deffn {C Συνάρτηση} int PyErr_BadArgument ()
` Μέρος του @ref{95c,,Σταθερό 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{51b7}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_NoMemory ()
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό 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{51b6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_SetFromErrno (PyObject *type)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό 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{880,,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{52fd}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_SetFromErrnoWithFilenameObject (PyObject *type, PyObject *filenameObject)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{51b6,,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{53c,,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{52fe}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_SetFromErrnoWithFilenameObjects (PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Similar to @ref{52fd,,PyErr_SetFromErrnoWithFilenameObject()}, but takes a second
filename object, for raising errors when a function that takes two filenames
fails.


Added in version 3.4.

@end deffn

@geindex PyErr_SetFromErrnoWithFilename (C function)
@anchor{c-api/exceptions c PyErr_SetFromErrnoWithFilename}@anchor{1c8b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_SetFromErrnoWithFilename (PyObject *type, const char *filename)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{52fd,,PyErr_SetFromErrnoWithFilenameObject()}, but the filename
is given as a C string.  `filename' is decoded from the @ref{948,,filesystem encoding and error handler}.
@end deffn

@geindex PyErr_SetFromWindowsErr (C function)
@anchor{c-api/exceptions c PyErr_SetFromWindowsErr}@anchor{52ff}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_SetFromWindowsErr (int ierr)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI} on Windows από την έκδοση 3.7.'
This is a convenience function to raise @ref{53c,,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 @code{OSError} object with the @ref{28eb,,winerror}
attribute set to the error code, the @ref{28ec,,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{232d,,Διαθεσιμότητα}: Windows.
@end deffn

@geindex PyErr_SetExcFromWindowsErr (C function)
@anchor{c-api/exceptions c PyErr_SetExcFromWindowsErr}@anchor{52fa}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_SetExcFromWindowsErr (PyObject *type, int ierr)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI} on Windows από την έκδοση 3.7.'
Similar to @ref{52ff,,PyErr_SetFromWindowsErr()}, with an additional parameter
specifying the exception type to be raised.

@ref{232d,,Διαθεσιμότητα}: Windows.
@end deffn

@geindex PyErr_SetFromWindowsErrWithFilename (C function)
@anchor{c-api/exceptions c PyErr_SetFromWindowsErrWithFilename}@anchor{1c8d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_SetFromWindowsErrWithFilename (int ierr, const char *filename)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI} on Windows από την έκδοση 3.7.'
Similar to @ref{52ff,,PyErr_SetFromWindowsErr()}, with the additional behavior
that if `filename' is not @code{NULL}, it is decoded from the filesystem
encoding (@ref{1012,,os.fsdecode()}) and passed to the constructor of
@ref{53c,,OSError} as a third parameter to be used to define the
@code{filename} attribute of the exception instance.

@ref{232d,,Διαθεσιμότητα}: Windows.
@end deffn

@geindex PyErr_SetExcFromWindowsErrWithFilenameObject (C function)
@anchor{c-api/exceptions c PyErr_SetExcFromWindowsErrWithFilenameObject}@anchor{52fb}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_SetExcFromWindowsErrWithFilenameObject (PyObject *type, int ierr, PyObject *filename)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI} on Windows από την έκδοση 3.7.'
Similar to @ref{52fa,,PyErr_SetExcFromWindowsErr()}, with the additional behavior
that if `filename' is not @code{NULL}, it is passed to the constructor of
@ref{53c,,OSError} as a third parameter to be used to define the
@code{filename} attribute of the exception instance.

@ref{232d,,Διαθεσιμότητα}: Windows.
@end deffn

@geindex PyErr_SetExcFromWindowsErrWithFilenameObjects (C function)
@anchor{c-api/exceptions c PyErr_SetExcFromWindowsErrWithFilenameObjects}@anchor{52fc}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_SetExcFromWindowsErrWithFilenameObjects (PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI} on Windows από την έκδοση 3.7.'
Similar to @ref{52fb,,PyErr_SetExcFromWindowsErrWithFilenameObject()},
but accepts a second filename object.

@ref{232d,,Διαθεσιμότητα}: Windows.


Added in version 3.4.

@end deffn

@geindex PyErr_SetExcFromWindowsErrWithFilename (C function)
@anchor{c-api/exceptions c PyErr_SetExcFromWindowsErrWithFilename}@anchor{1c8c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_SetExcFromWindowsErrWithFilename (PyObject *type, int ierr, const char *filename)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI} on Windows από την έκδοση 3.7.'
Similar to @ref{1c8d,,PyErr_SetFromWindowsErrWithFilename()}, with an additional
parameter specifying the exception type to be raised.

@ref{232d,,Διαθεσιμότητα}: Windows.
@end deffn

@geindex PyErr_SetImportError (C function)
@anchor{c-api/exceptions c PyErr_SetImportError}@anchor{10f5}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_SetImportError (PyObject *msg, PyObject *name, PyObject *path)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
This is a convenience function to raise @ref{1bd,,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 @code{ImportError}’s respective @code{name}
and @code{path} attributes.


Added in version 3.3.

@end deffn

@geindex PyErr_SetImportErrorSubclass (C function)
@anchor{c-api/exceptions c PyErr_SetImportErrorSubclass}@anchor{10d0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_SetImportErrorSubclass (PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.6.'
Much like @ref{10f5,,PyErr_SetImportError()} but this function allows for
specifying a subclass of @ref{1bd,,ImportError} to raise.


Added in version 3.6.

@end deffn

@geindex PyErr_SyntaxLocationObject (C function)
@anchor{c-api/exceptions c PyErr_SyntaxLocationObject}@anchor{5538}
@deffn {C Συνάρτηση} 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{17e,,SyntaxError}, then it sets additional
attributes, which make the exception printing subsystem think the exception
is a @code{SyntaxError}.


Added in version 3.4.

@end deffn

@geindex PyErr_RangedSyntaxLocationObject (C function)
@anchor{c-api/exceptions c PyErr_RangedSyntaxLocationObject}@anchor{5539}
@deffn {C Συνάρτηση} void PyErr_RangedSyntaxLocationObject (PyObject *filename, int lineno, int col_offset, int end_lineno, int end_col_offset)

Similar to @ref{5538,,PyErr_SyntaxLocationObject()}, but also sets the
`end_lineno' and `end_col_offset' information for the current exception.


Added in version 3.10.

@end deffn

@geindex PyErr_SyntaxLocationEx (C function)
@anchor{c-api/exceptions c PyErr_SyntaxLocationEx}@anchor{5303}
@deffn {C Συνάρτηση} void PyErr_SyntaxLocationEx (const char *filename, int lineno, int col_offset)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Like @ref{5538,,PyErr_SyntaxLocationObject()}, but `filename' is a byte string
decoded from the @ref{948,,filesystem encoding and error handler}.


Added in version 3.2.

@end deffn

@geindex PyErr_SyntaxLocation (C function)
@anchor{c-api/exceptions c PyErr_SyntaxLocation}@anchor{5302}
@deffn {C Συνάρτηση} void PyErr_SyntaxLocation (const char *filename, int lineno)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Like @ref{5303,,PyErr_SyntaxLocationEx()}, but the `col_offset' parameter is
omitted.
@end deffn

@geindex PyErr_BadInternalCall (C function)
@anchor{c-api/exceptions c PyErr_BadInternalCall}@anchor{52f6}
@deffn {C Συνάρτηση} void PyErr_BadInternalCall ()
` Μέρος του @ref{95c,,Σταθερό 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

@geindex PyErr_ProgramTextObject (C function)
@anchor{c-api/exceptions c PyErr_ProgramTextObject}@anchor{553a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_ProgramTextObject (PyObject *filename, int lineno)

Get the source line in `filename' at line `lineno'. `filename' should be a
Python @ref{1df,,str} object.

On success, this function returns a Python string object with the found line.
On failure, this function returns @code{NULL} without an exception set.
@end deffn

@geindex PyErr_ProgramText (C function)
@anchor{c-api/exceptions c PyErr_ProgramText}@anchor{52f9}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_ProgramText (const char *filename, int lineno)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{553a,,PyErr_ProgramTextObject()}, but `filename' is a
const char*, which is decoded with the
@ref{948,,filesystem encoding and error handler}, instead of a
Python object reference.
@end deffn

@node Issuing warnings,Querying the error indicator,Raising exceptions,Exception Handling
@anchor{c-api/exceptions issuing-warnings}@anchor{553b}
@subsection Issuing warnings


Use these functions to issue warnings from C code.  They mirror similar
functions exported by the Python @ref{11b,,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{975,,Py_DECREF()} owned references and return
an error value).

@geindex PyErr_WarnEx (C function)
@anchor{c-api/exceptions c PyErr_WarnEx}@anchor{17ee}
@deffn {C Συνάρτηση} int PyErr_WarnEx (PyObject *category, const char *message, Py_ssize_t stack_level)
` Μέρος του @ref{95c,,Σταθερό 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{17ee,,PyErr_WarnEx()}, 2 is  the function above that,
and so forth.

Warning categories must be subclasses of @ref{5347,,PyExc_Warning};
@code{PyExc_Warning} is a subclass of @ref{531b,,PyExc_Exception};
the default warning category is @ref{5337,,PyExc_RuntimeWarning}. The standard
Python warning categories are available as global variables whose names are
enumerated at @ref{553c,,Warning types}.

For information about warning control, see the documentation for the
@ref{11b,,warnings} module and the @ref{1c0,,-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{553d}
@deffn {C Συνάρτηση} 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{2ab,,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.


Added in version 3.4.

@end deffn

@geindex PyErr_WarnExplicit (C function)
@anchor{c-api/exceptions c PyErr_WarnExplicit}@anchor{1c93}
@deffn {C Συνάρτηση} int PyErr_WarnExplicit (PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{553d,,PyErr_WarnExplicitObject()} except that `message' and
`module' are UTF-8 encoded strings, and `filename' is decoded from the
@ref{948,,filesystem encoding and error handler}.
@end deffn

@geindex PyErr_WarnFormat (C function)
@anchor{c-api/exceptions c PyErr_WarnFormat}@anchor{5304}
@deffn {C Συνάρτηση} int PyErr_WarnFormat (PyObject *category, Py_ssize_t stack_level, const char *format, ...)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Function similar to @ref{17ee,,PyErr_WarnEx()}, but use
@ref{81e,,PyUnicode_FromFormat()} to format the warning message.  `format' is
an ASCII-encoded string.


Added in version 3.2.

@end deffn

@geindex PyErr_WarnExplicitFormat (C function)
@anchor{c-api/exceptions c PyErr_WarnExplicitFormat}@anchor{553e}
@deffn {C Συνάρτηση} int PyErr_WarnExplicitFormat (PyObject *category, const char *filename, int lineno, const char *module, PyObject *registry, const char *format, ...)

Similar to @ref{1c93,,PyErr_WarnExplicit()}, but uses
@ref{81e,,PyUnicode_FromFormat()} to format the warning message. `format' is
an ASCII-encoded string.


Added in version 3.2.

@end deffn

@geindex PyErr_ResourceWarning (C function)
@anchor{c-api/exceptions c PyErr_ResourceWarning}@anchor{10d1}
@deffn {C Συνάρτηση} int PyErr_ResourceWarning (PyObject *source, Py_ssize_t stack_level, const char *format, ...)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.6.'
Function similar to @ref{5304,,PyErr_WarnFormat()}, but `category' is
@ref{74f,,ResourceWarning} and it passes `source' to @code{warnings.WarningMessage}.


Added in version 3.6.

@end deffn

@node Querying the error indicator,Signal Handling<2>,Issuing warnings,Exception Handling
@anchor{c-api/exceptions querying-the-error-indicator}@anchor{553f}
@subsection Querying the error indicator


@geindex PyErr_Occurred (C function)
@anchor{c-api/exceptions c PyErr_Occurred}@anchor{1ea5}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_Occurred ()
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό 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{63e,,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{975,,Py_DECREF()}
it.

The caller must have an @ref{1a1,,attached thread state}.

@cartouche
@quotation Σημείωση 
Do not compare the return value to a specific exception; use
@ref{5265,,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{5265}
@deffn {C Συνάρτηση} int PyErr_ExceptionMatches (PyObject *exc)
` Μέρος του @ref{95c,,Σταθερό 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{52f7}
@deffn {C Συνάρτηση} int PyErr_GivenExceptionMatches (PyObject *given, PyObject *exc)
` Μέρος του @ref{95c,,Σταθερό 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{63c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_GetRaisedException (void)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.

For example:

@example
@{
   PyObject *exc = PyErr_GetRaisedException();

   /* ... code that might produce other errors ... */

   PyErr_SetRaisedException(exc);
@}
@end example


@subsubheading Δείτε επίσης


@ref{b51,,PyErr_GetHandledException()},
to save the exception currently being handled.



Added in version 3.12.

@end deffn

@geindex PyErr_SetRaisedException (C function)
@anchor{c-api/exceptions c PyErr_SetRaisedException}@anchor{63f}
@deffn {C Συνάρτηση} void PyErr_SetRaisedException (PyObject *exc)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
Set `exc' as the exception currently being raised,
clearing the existing exception if one is set.

@cartouche
@quotation Προειδοποίηση 
This call steals a reference to `exc', which must be a valid exception.
@end quotation
@end cartouche


Added in version 3.12.

@end deffn

@geindex PyErr_Fetch (C function)
@anchor{c-api/exceptions c PyErr_Fetch}@anchor{63b}
@deffn {C Συνάρτηση} void PyErr_Fetch (PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
` Μέρος του @ref{95c,,Σταθερό ABI}.'

Αποσύρθηκε στην έκδοση 3.12: Use @ref{63c,,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 Σημείωση 
This function is normally only used by legacy code that needs to catch
exceptions or save and restore the error indicator temporarily.

For example:

@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{63e}
@deffn {C Συνάρτηση} void PyErr_Restore (PyObject *type, PyObject *value, PyObject *traceback)
` Μέρος του @ref{95c,,Σταθερό ABI}.'

Αποσύρθηκε στην έκδοση 3.12: Use @ref{63f,,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 Σημείωση 
This function is normally only used by legacy code that needs to
save and restore the error indicator temporarily.
Use @ref{63b,,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{63d}
@deffn {C Συνάρτηση} void PyErr_NormalizeException (PyObject **exc, PyObject **val, PyObject **tb)
` Μέρος του @ref{95c,,Σταθερό ABI}.'

Αποσύρθηκε στην έκδοση 3.12: Use @ref{63c,,PyErr_GetRaisedException()} instead,
to avoid any possible de-normalization.


Under certain circumstances, the values returned by @ref{63b,,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 Σημείωση 
This function `does not' implicitly set the
@ref{166b,,__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{b51}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_GetHandledException (void)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Retrieve the active exception instance, as would be returned by @ref{a7b,,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 Σημείωση 
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{b52,,PyErr_SetHandledException()} to restore or
clear the exception state.
@end quotation
@end cartouche


Added in version 3.11.

@end deffn

@geindex PyErr_SetHandledException (C function)
@anchor{c-api/exceptions c PyErr_SetHandledException}@anchor{b52}
@deffn {C Συνάρτηση} void PyErr_SetHandledException (PyObject *exc)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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 Σημείωση 
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{b51,,PyErr_GetHandledException()} to get the exception
state.
@end quotation
@end cartouche


Added in version 3.11.

@end deffn

@geindex PyErr_GetExcInfo (C function)
@anchor{c-api/exceptions c PyErr_GetExcInfo}@anchor{b54}
@deffn {C Συνάρτηση} void PyErr_GetExcInfo (PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Retrieve the old-style representation of the exception info, as known from
@ref{a7a,,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{b51,,PyErr_GetHandledException()}.

@cartouche
@quotation Σημείωση 
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{b53,,PyErr_SetExcInfo()} to restore or clear the
exception state.
@end quotation
@end cartouche


Added in version 3.3.

@end deffn

@geindex PyErr_SetExcInfo (C function)
@anchor{c-api/exceptions c PyErr_SetExcInfo}@anchor{b53}
@deffn {C Συνάρτηση} void PyErr_SetExcInfo (PyObject *type, PyObject *value, PyObject *traceback)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{b52,,PyErr_SetHandledException()}.

@cartouche
@quotation Σημείωση 
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{b54,,PyErr_GetExcInfo()} to read the exception
state.
@end quotation
@end cartouche


Added in version 3.3.



Άλλαξε στην έκδοση 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 Signal Handling<2>,Exception Classes,Querying the error indicator,Exception Handling
@anchor{c-api/exceptions signal-handling}@anchor{5540}
@subsection Signal Handling


@geindex PyErr_CheckSignals (C function)
@anchor{c-api/exceptions c PyErr_CheckSignals}@anchor{880}
@deffn {C Συνάρτηση} int PyErr_CheckSignals ()
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex module;signal
@geindex SIGINT (C macro)
@geindex KeyboardInterrupt (built-in exception)

Handle external interruptions, such as signals or activating a debugger,
whose processing has been delayed until it is safe
to run Python code and/or raise exceptions.

For example, pressing @code{Ctrl}-@code{C} causes a terminal to send the
@ref{4df,,signal.SIGINT} signal.
This function executes the corresponding Python signal handler, which,
by default, raises the @ref{d96,,KeyboardInterrupt} exception.

@code{PyErr_CheckSignals()} should be called by long-running C code
frequently enough so that the response appears immediate to humans.

Handlers invoked by this function currently include:


@itemize -

@item 
Signal handlers, including Python functions registered using
the @ref{ce,,signal} module.

Signal handlers are only run in the main thread of the main interpreter.

(This is where the function got the name: originally, signals
were the only way to interrupt the interpreter.)

@item 
Running the garbage collector, if necessary.

@item 
Executing a pending @ref{4c0b,,remote debugger} script.

@item 
Raise the exception set by @ref{f82,,PyThreadState_SetAsyncExc()}.
@end itemize

If any handler raises an exception, immediately return @code{-1} with that
exception set.
Any remaining interruptions are left to be processed on the next
@ref{880,,PyErr_CheckSignals()} invocation, if appropriate.

If all handlers finish successfully, or there are no handlers to run,
return @code{0}.


Άλλαξε στην έκδοση 3.12: This function may now invoke the garbage collector.



Άλλαξε στην έκδοση 3.14: This function may now execute a remote debugger script, if remote
debugging is enabled.



Άλλαξε στην έκδοση 3.15: The exception set by @ref{f82,,PyThreadState_SetAsyncExc()} is now raised.

@end deffn

@geindex PyErr_SetInterrupt (C function)
@anchor{c-api/exceptions c PyErr_SetInterrupt}@anchor{5300}
@deffn {C Συνάρτηση} void PyErr_SetInterrupt ()
` Μέρος του @ref{95c,,Σταθερό 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 Σημείωση 
This function is async-signal-safe.  It can be called without
an @ref{1a1,,attached thread state} 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{c74}
@deffn {C Συνάρτηση} int PyErr_SetInterruptEx (int signum)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
@geindex module;signal
@geindex KeyboardInterrupt (built-in exception)

Simulate the effect of a signal arriving. The next time
@ref{880,,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{1dac,,signal.SIG_DFL} or @ref{1dab,,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 Σημείωση 
This function is async-signal-safe.  It can be called without
an @ref{1a1,,attached thread state} and from a C signal handler.
@end quotation
@end cartouche


Added in version 3.10.

@end deffn

@geindex PySignal_SetWakeupFd (C function)
@anchor{c-api/exceptions c PySignal_SetWakeupFd}@anchor{177e}
@deffn {C Συνάρτηση} 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{f2d,,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.


Άλλαξε στην έκδοση 3.5: On Windows, the function now also supports socket handles.

@end deffn

@node Exception Classes,Exception Objects,Signal Handling<2>,Exception Handling
@anchor{c-api/exceptions exception-classes}@anchor{5541}
@subsection Exception Classes


@geindex PyErr_NewException (C function)
@anchor{c-api/exceptions c PyErr_NewException}@anchor{160e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_NewException (const char *name, PyObject *base, PyObject *dict)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{d9e,,Exception} (accessible in C as
@ref{531b,,PyExc_Exception}).

The @ref{80b,,__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{160d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyErr_NewExceptionWithDoc (const char *name, const char *doc, PyObject *base, PyObject *dict)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Same as @ref{160e,,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.


Added in version 3.2.

@end deffn

@geindex PyExceptionClass_Check (C function)
@anchor{c-api/exceptions c PyExceptionClass_Check}@anchor{5542}
@deffn {C Συνάρτηση} int PyExceptionClass_Check (PyObject *ob)

Return non-zero if `ob' is an exception class, zero otherwise. This function always succeeds.
@end deffn

@geindex PyExceptionClass_Name (C function)
@anchor{c-api/exceptions c PyExceptionClass_Name}@anchor{e2a}
@deffn {C Συνάρτηση} const char *PyExceptionClass_Name (PyObject *ob)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.8.'
Return @ref{1ea6,,tp_name} of the exception class `ob'.
@end deffn

@geindex PyException_HEAD (C macro)
@anchor{c-api/exceptions c PyException_HEAD}@anchor{5543}
@deffn {C Μακροεντολή} PyException_HEAD

This is a macro including the base fields for an
exception object.

This was included in Python’s C API by mistake and is not designed for use
in extensions. For creating custom exception objects, use
@ref{160e,,PyErr_NewException()} or otherwise create a class inheriting from
@ref{530c,,PyExc_BaseException}.


@ref{1a7,,Soft deprecated} since version 3.15.

@end deffn

@node Exception Objects,Unicode Exception Objects,Exception Classes,Exception Handling
@anchor{c-api/exceptions exception-objects}@anchor{5544}
@subsection Exception Objects


@geindex PyExceptionInstance_Check (C function)
@anchor{c-api/exceptions c PyExceptionInstance_Check}@anchor{5545}
@deffn {C Συνάρτηση} int PyExceptionInstance_Check (PyObject *op)

Return true if `op' is an instance of @ref{9b9,,BaseException}, false
otherwise. This function always succeeds.
@end deffn

@geindex PyExceptionInstance_Class (C macro)
@anchor{c-api/exceptions c PyExceptionInstance_Class}@anchor{5546}
@deffn {C Μακροεντολή} PyExceptionInstance_Class (op)

Equivalent to @ref{5f5,,Py_TYPE(op)}.
@end deffn

@geindex PyException_GetTraceback (C function)
@anchor{c-api/exceptions c PyException_GetTraceback}@anchor{534b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyException_GetTraceback (PyObject *ex)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the traceback associated with the exception as a new reference, as
accessible from Python through the @ref{166b,,__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{1fbe}
@deffn {C Συνάρτηση} int PyException_SetTraceback (PyObject *ex, PyObject *tb)
` Μέρος του @ref{95c,,Σταθερό 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{534a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyException_GetContext (PyObject *ex)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{166c,,__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{534d}
@deffn {C Συνάρτηση} void PyException_SetContext (PyObject *ex, PyObject *ctx)
` Μέρος του @ref{95c,,Σταθερό 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{5349}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyException_GetCause (PyObject *ex)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{166d,,__cause__} attribute.
@end deffn

@geindex PyException_SetCause (C function)
@anchor{c-api/exceptions c PyException_SetCause}@anchor{534c}
@deffn {C Συνάρτηση} void PyException_SetCause (PyObject *ex, PyObject *cause)
` Μέρος του @ref{95c,,Σταθερό 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{270a,,__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{970}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyException_GetArgs (PyObject *ex)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
Return @ref{972,,args} of exception `ex'.
@end deffn

@geindex PyException_SetArgs (C function)
@anchor{c-api/exceptions c PyException_SetArgs}@anchor{971}
@deffn {C Συνάρτηση} void PyException_SetArgs (PyObject *ex, PyObject *args)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
Set @ref{972,,args} of exception `ex' to `args'.
@end deffn

@geindex PyUnstable_Exc_PrepReraiseStar (C function)
@anchor{c-api/exceptions c PyUnstable_Exc_PrepReraiseStar}@anchor{5547}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnstable_Exc_PrepReraiseStar (PyObject *orig, PyObject *excs)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@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{6d8,,ExceptionGroup} that needs to be reraised in the end, or
@code{None} if there is nothing to reraise.


Added in version 3.12.

@end deffn

@node Unicode Exception Objects,Recursion Control,Exception Objects,Exception Handling
@anchor{c-api/exceptions unicode-exception-objects}@anchor{5548}@anchor{c-api/exceptions unicodeexceptions}@anchor{674}
@subsection Unicode Exception Objects


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{541c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicodeDecodeError_Create (const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a @ref{dd7,,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{541d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicodeDecodeError_GetEncoding (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetEncoding}@anchor{5425}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicodeEncodeError_GetEncoding (PyObject *exc)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{541f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicodeDecodeError_GetObject (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetObject}@anchor{5426}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicodeEncodeError_GetObject (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeTranslateError_GetObject}@anchor{542d}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicodeTranslateError_GetObject (PyObject *exc)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{5421}
@deffn {C Συνάρτηση} int PyUnicodeDecodeError_GetStart (PyObject *exc, Py_ssize_t *start)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetStart}@anchor{1b1d}
@deffnx {C Συνάρτηση} int PyUnicodeEncodeError_GetStart (PyObject *exc, Py_ssize_t *start)
@anchor{c-api/exceptions c PyUnicodeTranslateError_GetStart}@anchor{542f}
@deffnx {C Συνάρτηση} int PyUnicodeTranslateError_GetStart (PyObject *exc, Py_ssize_t *start)
` Μέρος του @ref{95c,,Σταθερό 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.

If the @ref{1b1b,,UnicodeError.object} is an empty sequence, the resulting
`start' is @code{0}. Otherwise, it is clipped to @code{[0, len(object) - 1]}.


@subsubheading Δείτε επίσης


@ref{1ae1,,UnicodeError.start}

@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{5424}
@deffn {C Συνάρτηση} int PyUnicodeDecodeError_SetStart (PyObject *exc, Py_ssize_t start)
@anchor{c-api/exceptions c PyUnicodeEncodeError_SetStart}@anchor{542a}
@deffnx {C Συνάρτηση} int PyUnicodeEncodeError_SetStart (PyObject *exc, Py_ssize_t start)
@anchor{c-api/exceptions c PyUnicodeTranslateError_SetStart}@anchor{5432}
@deffnx {C Συνάρτηση} int PyUnicodeTranslateError_SetStart (PyObject *exc, Py_ssize_t start)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Set the `start' attribute of the given exception object to `start'.
Return @code{0} on success, @code{-1} on failure.

@cartouche
@quotation Σημείωση 
While passing a negative `start' does not raise an exception,
the corresponding getters will not consider it as a relative
offset.
@end quotation
@end cartouche
@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{541e}
@deffn {C Συνάρτηση} int PyUnicodeDecodeError_GetEnd (PyObject *exc, Py_ssize_t *end)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetEnd}@anchor{1b1a}
@deffnx {C Συνάρτηση} int PyUnicodeEncodeError_GetEnd (PyObject *exc, Py_ssize_t *end)
@anchor{c-api/exceptions c PyUnicodeTranslateError_GetEnd}@anchor{542c}
@deffnx {C Συνάρτηση} int PyUnicodeTranslateError_GetEnd (PyObject *exc, Py_ssize_t *end)
` Μέρος του @ref{95c,,Σταθερό 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.

If the @ref{1b1b,,UnicodeError.object} is an empty sequence, the resulting
`end' is @code{0}. Otherwise, it is clipped to @code{[1, len(object)]}.
@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{5422}
@deffn {C Συνάρτηση} int PyUnicodeDecodeError_SetEnd (PyObject *exc, Py_ssize_t end)
@anchor{c-api/exceptions c PyUnicodeEncodeError_SetEnd}@anchor{5428}
@deffnx {C Συνάρτηση} int PyUnicodeEncodeError_SetEnd (PyObject *exc, Py_ssize_t end)
@anchor{c-api/exceptions c PyUnicodeTranslateError_SetEnd}@anchor{5430}
@deffnx {C Συνάρτηση} int PyUnicodeTranslateError_SetEnd (PyObject *exc, Py_ssize_t end)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Set the `end' attribute of the given exception object to `end'.  Return @code{0}
on success, @code{-1} on failure.


@subsubheading Δείτε επίσης


@ref{1ae2,,UnicodeError.end}

@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{5420}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicodeDecodeError_GetReason (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetReason}@anchor{5427}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicodeEncodeError_GetReason (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeTranslateError_GetReason}@anchor{542e}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicodeTranslateError_GetReason (PyObject *exc)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{5423}
@deffn {C Συνάρτηση} int PyUnicodeDecodeError_SetReason (PyObject *exc, const char *reason)
@anchor{c-api/exceptions c PyUnicodeEncodeError_SetReason}@anchor{5429}
@deffnx {C Συνάρτηση} int PyUnicodeEncodeError_SetReason (PyObject *exc, const char *reason)
@anchor{c-api/exceptions c PyUnicodeTranslateError_SetReason}@anchor{5431}
@deffnx {C Συνάρτηση} int PyUnicodeTranslateError_SetReason (PyObject *exc, const char *reason)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Set the `reason' attribute of the given exception object to `reason'.  Return
@code{0} on success, @code{-1} on failure.
@end deffn

@node Recursion Control,Exception and warning types,Unicode Exception Objects,Exception Handling
@anchor{c-api/exceptions recursion}@anchor{5549}@anchor{c-api/exceptions recursion-control}@anchor{554a}
@subsection Recursion Control


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{985,,call protocol} takes care of recursion handling.

@geindex Py_EnterRecursiveCall (C function)
@anchor{c-api/exceptions c Py_EnterRecursiveCall}@anchor{5fe}
@deffn {C Συνάρτηση} int Py_EnterRecursiveCall (const char *where)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.9.'
Marks a point where a recursive C-level call is about to be performed.

The function then checks if the stack limit is reached.  If this is the
case, a @ref{1121,,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{1121,,RecursionError} message caused by the recursion
depth limit.


@subsubheading Δείτε επίσης


The @ref{395,,PyUnstable_ThreadState_SetStackProtection()} function.



Άλλαξε στην έκδοση 3.9: This function is now also available in the @ref{829,,limited API}.

@end deffn

@geindex Py_LeaveRecursiveCall (C function)
@anchor{c-api/exceptions c Py_LeaveRecursiveCall}@anchor{d3c}
@deffn {C Συνάρτηση} void Py_LeaveRecursiveCall (void)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.9.'
Ends a @ref{5fe,,Py_EnterRecursiveCall()}.  Must be called once for each
`successful' invocation of @code{Py_EnterRecursiveCall()}.


Άλλαξε στην έκδοση 3.9: This function is now also available in the @ref{829,,limited API}.

@end deffn

Properly implementing @ref{51f9,,tp_repr} for container types requires
special recursion handling.  In addition to protecting the stack,
@code{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{159c,,reprlib.recursive_repr()}.

@geindex Py_ReprEnter (C function)
@anchor{c-api/exceptions c Py_ReprEnter}@anchor{5479}
@deffn {C Συνάρτηση} int Py_ReprEnter (PyObject *object)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Called at the beginning of the @ref{51f9,,tp_repr} implementation to
detect cycles.

If the object has already been processed, the function returns a
positive integer.  In that case the @ref{51f9,,tp_repr} implementation
should return a string object indicating a cycle.  As examples,
@ref{188,,dict} objects return @code{@{...@}} and @ref{4d9,,list} objects
return @code{[...]}.

The function will return a negative integer if the recursion limit
is reached.  In that case the @ref{51f9,,tp_repr} implementation should
typically return @code{NULL}.

Otherwise, the function returns zero and the @ref{51f9,,tp_repr}
implementation can continue normally.
@end deffn

@geindex Py_ReprLeave (C function)
@anchor{c-api/exceptions c Py_ReprLeave}@anchor{547a}
@deffn {C Συνάρτηση} void Py_ReprLeave (PyObject *object)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Ends a @ref{5479,,Py_ReprEnter()}.  Must be called once for each
invocation of @code{Py_ReprEnter()} that returns zero.
@end deffn

@geindex Py_GetRecursionLimit (C function)
@anchor{c-api/exceptions c Py_GetRecursionLimit}@anchor{5474}
@deffn {C Συνάρτηση} int Py_GetRecursionLimit (void)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Get the recursion limit for the current interpreter. It can be set with
@ref{547b,,Py_SetRecursionLimit()}. The recursion limit prevents the
Python interpreter stack from growing infinitely.

This function cannot fail, and the caller must hold an
@ref{1a1,,attached thread state}.


@subsubheading Δείτε επίσης


@ref{8d4,,sys.getrecursionlimit()}

@end deffn

@geindex Py_SetRecursionLimit (C function)
@anchor{c-api/exceptions c Py_SetRecursionLimit}@anchor{547b}
@deffn {C Συνάρτηση} void Py_SetRecursionLimit (int new_limit)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Set the recursion limit for the current interpreter.

This function cannot fail, and the caller must hold an
@ref{1a1,,attached thread state}.


@subsubheading Δείτε επίσης


@ref{8d3,,sys.setrecursionlimit()}

@end deffn

@node Exception and warning types,Tracebacks,Recursion Control,Exception Handling
@anchor{c-api/exceptions exception-and-warning-types}@anchor{554b}@anchor{c-api/exceptions standardexceptions}@anchor{554c}
@subsection Exception and warning types


All standard Python exceptions and warning categories are available as global
variables whose names are @code{PyExc_} followed by the Python exception name.
These have the type @ref{19b,,PyObject}*; they are all class objects.

For completeness, here are all the variables:

@menu
* Exception types:: 
* OSError aliases:: 
* Warning types:: 

@end menu

@node Exception types,OSError aliases,,Exception and warning types
@anchor{c-api/exceptions exception-types}@anchor{554d}
@subsubsection Exception types



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

C name

@tab

Python name

@item

@geindex PyExc_BaseException (C var)
@anchor{c-api/exceptions c PyExc_BaseException}@anchor{530c}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_BaseException
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{9b9,,BaseException}

@item

@geindex PyExc_BaseExceptionGroup (C var)
@anchor{c-api/exceptions c PyExc_BaseExceptionGroup}@anchor{530d}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_BaseExceptionGroup
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

@ref{767,,BaseExceptionGroup}

@item

@geindex PyExc_Exception (C var)
@anchor{c-api/exceptions c PyExc_Exception}@anchor{531b}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_Exception
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{d9e,,Exception}

@item

@geindex PyExc_ArithmeticError (C var)
@anchor{c-api/exceptions c PyExc_ArithmeticError}@anchor{5309}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ArithmeticError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{28e1,,ArithmeticError}

@item

@geindex PyExc_AssertionError (C var)
@anchor{c-api/exceptions c PyExc_AssertionError}@anchor{530a}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_AssertionError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{a97,,AssertionError}

@item

@geindex PyExc_AttributeError (C var)
@anchor{c-api/exceptions c PyExc_AttributeError}@anchor{530b}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_AttributeError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{1a9,,AttributeError}

@item

@geindex PyExc_BlockingIOError (C var)
@anchor{c-api/exceptions c PyExc_BlockingIOError}@anchor{530e}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_BlockingIOError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{4c3,,BlockingIOError}

@item

@geindex PyExc_BrokenPipeError (C var)
@anchor{c-api/exceptions c PyExc_BrokenPipeError}@anchor{530f}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_BrokenPipeError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{1404,,BrokenPipeError}

@item

@geindex PyExc_BufferError (C var)
@anchor{c-api/exceptions c PyExc_BufferError}@anchor{5310}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_BufferError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{1998,,BufferError}

@item

@geindex PyExc_ChildProcessError (C var)
@anchor{c-api/exceptions c PyExc_ChildProcessError}@anchor{5312}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ChildProcessError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{1400,,ChildProcessError}

@item

@geindex PyExc_ConnectionAbortedError (C var)
@anchor{c-api/exceptions c PyExc_ConnectionAbortedError}@anchor{5313}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ConnectionAbortedError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{1405,,ConnectionAbortedError}

@item

@geindex PyExc_ConnectionError (C var)
@anchor{c-api/exceptions c PyExc_ConnectionError}@anchor{5314}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ConnectionError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{11bf,,ConnectionError}

@item

@geindex PyExc_ConnectionRefusedError (C var)
@anchor{c-api/exceptions c PyExc_ConnectionRefusedError}@anchor{5315}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ConnectionRefusedError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{1406,,ConnectionRefusedError}

@item

@geindex PyExc_ConnectionResetError (C var)
@anchor{c-api/exceptions c PyExc_ConnectionResetError}@anchor{5316}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ConnectionResetError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{1407,,ConnectionResetError}

@item

@geindex PyExc_EOFError (C var)
@anchor{c-api/exceptions c PyExc_EOFError}@anchor{5318}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_EOFError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{167e,,EOFError}

@item

@geindex PyExc_FileExistsError (C var)
@anchor{c-api/exceptions c PyExc_FileExistsError}@anchor{531c}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_FileExistsError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{13c9,,FileExistsError}

@item

@geindex PyExc_FileNotFoundError (C var)
@anchor{c-api/exceptions c PyExc_FileNotFoundError}@anchor{531d}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_FileNotFoundError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{243,,FileNotFoundError}

@item

@geindex PyExc_FloatingPointError (C var)
@anchor{c-api/exceptions c PyExc_FloatingPointError}@anchor{531e}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_FloatingPointError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{28e2,,FloatingPointError}

@item

@geindex PyExc_GeneratorExit (C var)
@anchor{c-api/exceptions c PyExc_GeneratorExit}@anchor{5320}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_GeneratorExit
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{176a,,GeneratorExit}

@item

@geindex PyExc_ImportCycleError (C var)
@anchor{c-api/exceptions c PyExc_ImportCycleError}@anchor{554e}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ImportCycleError
@end deffn

@tab

@ref{28e7,,ImportCycleError}

@item

@geindex PyExc_ImportError (C var)
@anchor{c-api/exceptions c PyExc_ImportError}@anchor{5322}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ImportError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{1bd,,ImportError}

@item

@geindex PyExc_IndentationError (C var)
@anchor{c-api/exceptions c PyExc_IndentationError}@anchor{5324}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_IndentationError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{b89,,IndentationError}

@item

@geindex PyExc_IndexError (C var)
@anchor{c-api/exceptions c PyExc_IndexError}@anchor{5325}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_IndexError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{18d7,,IndexError}

@item

@geindex PyExc_InterruptedError (C var)
@anchor{c-api/exceptions c PyExc_InterruptedError}@anchor{5326}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_InterruptedError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{1141,,InterruptedError}

@item

@geindex PyExc_IsADirectoryError (C var)
@anchor{c-api/exceptions c PyExc_IsADirectoryError}@anchor{5327}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_IsADirectoryError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{1401,,IsADirectoryError}

@item

@geindex PyExc_KeyError (C var)
@anchor{c-api/exceptions c PyExc_KeyError}@anchor{5328}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_KeyError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{7df,,KeyError}

@item

@geindex PyExc_KeyboardInterrupt (C var)
@anchor{c-api/exceptions c PyExc_KeyboardInterrupt}@anchor{5329}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_KeyboardInterrupt
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{d96,,KeyboardInterrupt}

@item

@geindex PyExc_LookupError (C var)
@anchor{c-api/exceptions c PyExc_LookupError}@anchor{532a}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_LookupError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{25da,,LookupError}

@item

@geindex PyExc_MemoryError (C var)
@anchor{c-api/exceptions c PyExc_MemoryError}@anchor{532b}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_MemoryError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{18fa,,MemoryError}

@item

@geindex PyExc_ModuleNotFoundError (C var)
@anchor{c-api/exceptions c PyExc_ModuleNotFoundError}@anchor{532c}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ModuleNotFoundError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.6.'
@end deffn

@tab

@ref{1be,,ModuleNotFoundError}

@item

@geindex PyExc_NameError (C var)
@anchor{c-api/exceptions c PyExc_NameError}@anchor{532d}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_NameError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{665,,NameError}

@item

@geindex PyExc_NotADirectoryError (C var)
@anchor{c-api/exceptions c PyExc_NotADirectoryError}@anchor{532e}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_NotADirectoryError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{1402,,NotADirectoryError}

@item

@geindex PyExc_NotImplementedError (C var)
@anchor{c-api/exceptions c PyExc_NotImplementedError}@anchor{532f}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_NotImplementedError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{59a,,NotImplementedError}

@item

@geindex PyExc_OSError (C var)
@anchor{c-api/exceptions c PyExc_OSError}@anchor{51b9}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_OSError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{53c,,OSError}

@item

@geindex PyExc_OverflowError (C var)
@anchor{c-api/exceptions c PyExc_OverflowError}@anchor{5330}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_OverflowError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{c57,,OverflowError}

@item

@geindex PyExc_PermissionError (C var)
@anchor{c-api/exceptions c PyExc_PermissionError}@anchor{5332}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_PermissionError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{10f9,,PermissionError}

@item

@geindex PyExc_ProcessLookupError (C var)
@anchor{c-api/exceptions c PyExc_ProcessLookupError}@anchor{5333}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ProcessLookupError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{1403,,ProcessLookupError}

@item

@geindex PyExc_PythonFinalizationError (C var)
@anchor{c-api/exceptions c PyExc_PythonFinalizationError}@anchor{554f}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_PythonFinalizationError
@end deffn

@tab

@ref{68a,,PythonFinalizationError}

@item

@geindex PyExc_RecursionError (C var)
@anchor{c-api/exceptions c PyExc_RecursionError}@anchor{1263}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_RecursionError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{1121,,RecursionError}

@item

@geindex PyExc_ReferenceError (C var)
@anchor{c-api/exceptions c PyExc_ReferenceError}@anchor{5334}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ReferenceError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{18af,,ReferenceError}

@item

@geindex PyExc_RuntimeError (C var)
@anchor{c-api/exceptions c PyExc_RuntimeError}@anchor{5336}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_RuntimeError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{30d,,RuntimeError}

@item

@geindex PyExc_StopAsyncIteration (C var)
@anchor{c-api/exceptions c PyExc_StopAsyncIteration}@anchor{5338}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_StopAsyncIteration
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{1ffe,,StopAsyncIteration}

@item

@geindex PyExc_StopIteration (C var)
@anchor{c-api/exceptions c PyExc_StopIteration}@anchor{5339}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_StopIteration
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{fba,,StopIteration}

@item

@geindex PyExc_SyntaxError (C var)
@anchor{c-api/exceptions c PyExc_SyntaxError}@anchor{533a}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_SyntaxError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{17e,,SyntaxError}

@item

@geindex PyExc_SystemError (C var)
@anchor{c-api/exceptions c PyExc_SystemError}@anchor{533c}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_SystemError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{3ea,,SystemError}

@item

@geindex PyExc_SystemExit (C var)
@anchor{c-api/exceptions c PyExc_SystemExit}@anchor{533d}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_SystemExit
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{10f7,,SystemExit}

@item

@geindex PyExc_TabError (C var)
@anchor{c-api/exceptions c PyExc_TabError}@anchor{533e}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_TabError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{950,,TabError}

@item

@geindex PyExc_TimeoutError (C var)
@anchor{c-api/exceptions c PyExc_TimeoutError}@anchor{533f}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_TimeoutError
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{c0e,,TimeoutError}

@item

@geindex PyExc_TypeError (C var)
@anchor{c-api/exceptions c PyExc_TypeError}@anchor{51b8}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_TypeError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{291,,TypeError}

@item

@geindex PyExc_UnboundLocalError (C var)
@anchor{c-api/exceptions c PyExc_UnboundLocalError}@anchor{5340}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_UnboundLocalError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{18d8,,UnboundLocalError}

@item

@geindex PyExc_UnicodeDecodeError (C var)
@anchor{c-api/exceptions c PyExc_UnicodeDecodeError}@anchor{5341}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_UnicodeDecodeError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{dd7,,UnicodeDecodeError}

@item

@geindex PyExc_UnicodeEncodeError (C var)
@anchor{c-api/exceptions c PyExc_UnicodeEncodeError}@anchor{5342}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_UnicodeEncodeError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{a67,,UnicodeEncodeError}

@item

@geindex PyExc_UnicodeError (C var)
@anchor{c-api/exceptions c PyExc_UnicodeError}@anchor{5343}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_UnicodeError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{675,,UnicodeError}

@item

@geindex PyExc_UnicodeTranslateError (C var)
@anchor{c-api/exceptions c PyExc_UnicodeTranslateError}@anchor{5344}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_UnicodeTranslateError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{1b1c,,UnicodeTranslateError}

@item

@geindex PyExc_ValueError (C var)
@anchor{c-api/exceptions c PyExc_ValueError}@anchor{51ba}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ValueError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{277,,ValueError}

@item

@geindex PyExc_ZeroDivisionError (C var)
@anchor{c-api/exceptions c PyExc_ZeroDivisionError}@anchor{51b5}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ZeroDivisionError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{d11,,ZeroDivisionError}

@end multitable



Added in version 3.3: @ref{530e,,PyExc_BlockingIOError}, @ref{530f,,PyExc_BrokenPipeError},
@ref{5312,,PyExc_ChildProcessError}, @ref{5314,,PyExc_ConnectionError},
@ref{5313,,PyExc_ConnectionAbortedError}, @ref{5315,,PyExc_ConnectionRefusedError},
@ref{5316,,PyExc_ConnectionResetError}, @ref{531c,,PyExc_FileExistsError},
@ref{531d,,PyExc_FileNotFoundError}, @ref{5326,,PyExc_InterruptedError},
@ref{5327,,PyExc_IsADirectoryError}, @ref{532e,,PyExc_NotADirectoryError},
@ref{5332,,PyExc_PermissionError}, @ref{5333,,PyExc_ProcessLookupError}
and @ref{533f,,PyExc_TimeoutError} were introduced following 
@geindex Python Enhancement Proposals; PEP 3151
PEP 3151@footnote{https://peps.python.org/pep-3151/}.



Added in version 3.5: @ref{5338,,PyExc_StopAsyncIteration} and @ref{1263,,PyExc_RecursionError}.



Added in version 3.6: @ref{532c,,PyExc_ModuleNotFoundError}.



Added in version 3.11: @ref{530d,,PyExc_BaseExceptionGroup}.


@node OSError aliases,Warning types,Exception types,Exception and warning types
@anchor{c-api/exceptions oserror-aliases}@anchor{5550}
@subsubsection OSError aliases


The following are a compatibility aliases to @ref{51b9,,PyExc_OSError}.


Άλλαξε στην έκδοση 3.3: These aliases used to be separate exception types.



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

C name

@tab

Python name

@tab

Notes

@item

@geindex PyExc_EnvironmentError (C var)
@anchor{c-api/exceptions c PyExc_EnvironmentError}@anchor{531a}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_EnvironmentError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{53c,,OSError}

@tab

@item

@geindex PyExc_IOError (C var)
@anchor{c-api/exceptions c PyExc_IOError}@anchor{5321}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_IOError
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{53c,,OSError}

@tab

@item

@geindex PyExc_WindowsError (C var)
@anchor{c-api/exceptions c PyExc_WindowsError}@anchor{5348}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_WindowsError
` Μέρος του @ref{95c,,Σταθερό ABI} on Windows από την έκδοση 3.7.'
@end deffn

@tab

@ref{53c,,OSError}

@tab

@ref{5551,,[win]}

@end multitable


Notes:

@anchor{c-api/exceptions win}@anchor{5551}@w{(win)} 
@code{PyExc_WindowsError} is only defined on Windows; protect code that uses this by testing that the preprocessor macro @code{MS_WINDOWS} is defined.

@node Warning types,,OSError aliases,Exception and warning types
@anchor{c-api/exceptions standardwarningcategories}@anchor{553c}@anchor{c-api/exceptions warning-types}@anchor{5552}
@subsubsection Warning types



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

C name

@tab

Python name

@item

@geindex PyExc_Warning (C var)
@anchor{c-api/exceptions c PyExc_Warning}@anchor{5347}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_Warning
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{290e,,Warning}

@item

@geindex PyExc_BytesWarning (C var)
@anchor{c-api/exceptions c PyExc_BytesWarning}@anchor{5311}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_BytesWarning
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{2ee,,BytesWarning}

@item

@geindex PyExc_DeprecationWarning (C var)
@anchor{c-api/exceptions c PyExc_DeprecationWarning}@anchor{5317}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_DeprecationWarning
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{2c9,,DeprecationWarning}

@item

@geindex PyExc_EncodingWarning (C var)
@anchor{c-api/exceptions c PyExc_EncodingWarning}@anchor{5319}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_EncodingWarning
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
@end deffn

@tab

@ref{231d,,EncodingWarning}

@item

@geindex PyExc_FutureWarning (C var)
@anchor{c-api/exceptions c PyExc_FutureWarning}@anchor{531f}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_FutureWarning
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{847,,FutureWarning}

@item

@geindex PyExc_ImportWarning (C var)
@anchor{c-api/exceptions c PyExc_ImportWarning}@anchor{5323}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ImportWarning
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{907,,ImportWarning}

@item

@geindex PyExc_PendingDeprecationWarning (C var)
@anchor{c-api/exceptions c PyExc_PendingDeprecationWarning}@anchor{5331}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_PendingDeprecationWarning
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{c9b,,PendingDeprecationWarning}

@item

@geindex PyExc_ResourceWarning (C var)
@anchor{c-api/exceptions c PyExc_ResourceWarning}@anchor{5335}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_ResourceWarning
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@end deffn

@tab

@ref{74f,,ResourceWarning}

@item

@geindex PyExc_RuntimeWarning (C var)
@anchor{c-api/exceptions c PyExc_RuntimeWarning}@anchor{5337}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_RuntimeWarning
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{6dd,,RuntimeWarning}

@item

@geindex PyExc_SyntaxWarning (C var)
@anchor{c-api/exceptions c PyExc_SyntaxWarning}@anchor{533b}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_SyntaxWarning
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{44a,,SyntaxWarning}

@item

@geindex PyExc_UnicodeWarning (C var)
@anchor{c-api/exceptions c PyExc_UnicodeWarning}@anchor{5345}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_UnicodeWarning
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{17c6,,UnicodeWarning}

@item

@geindex PyExc_UserWarning (C var)
@anchor{c-api/exceptions c PyExc_UserWarning}@anchor{5346}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyExc_UserWarning
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{290f,,UserWarning}

@end multitable



Added in version 3.2: @ref{5335,,PyExc_ResourceWarning}.



Added in version 3.10: @ref{5319,,PyExc_EncodingWarning}.


@node Tracebacks,,Exception and warning types,Exception Handling
@anchor{c-api/exceptions tracebacks}@anchor{5553}
@subsection Tracebacks


@geindex PyTraceBack_Type (C var)
@anchor{c-api/exceptions c PyTraceBack_Type}@anchor{5412}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyTraceBack_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Type object for traceback objects. This is available as
@ref{eb8,,types.TracebackType} in the Python layer.
@end deffn

@geindex PyTraceBack_Check (C function)
@anchor{c-api/exceptions c PyTraceBack_Check}@anchor{5554}
@deffn {C Συνάρτηση} int PyTraceBack_Check (PyObject *op)

Return true if `op' is a traceback object, false otherwise. This function
does not account for subtypes.
@end deffn

@geindex PyTraceBack_Here (C function)
@anchor{c-api/exceptions c PyTraceBack_Here}@anchor{5410}
@deffn {C Συνάρτηση} int PyTraceBack_Here (PyFrameObject *f)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Replace the @ref{166b,,__traceback__} attribute on the current
exception with a new traceback prepending `f' to the existing chain.

Calling this function without an exception set is undefined behavior.

This function returns @code{0} on success, and returns @code{-1} with an
exception set on failure.
@end deffn

@geindex PyTraceBack_Print (C function)
@anchor{c-api/exceptions c PyTraceBack_Print}@anchor{5411}
@deffn {C Συνάρτηση} int PyTraceBack_Print (PyObject *tb, PyObject *f)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Write the traceback `tb' into the file `f'.

This function returns @code{0} on success, and returns @code{-1} with an
exception set on failure.
@end deffn

@geindex PyUnstable_DumpTraceback (C function)
@anchor{c-api/exceptions c PyUnstable_DumpTraceback}@anchor{399}
@deffn {C Συνάρτηση} const char *PyUnstable_DumpTraceback (int fd, PyThreadState *tstate)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Write a trace of the Python stack in `tstate' into the file `fd'.  The format
looks like:

@example
Traceback (most recent call first):
  File "xxx", line xxx in <xxx>
  File "xxx", line xxx in <xxx>
  ...
  File "xxx", line xxx in <xxx>
@end example

This function is meant to debug situations such as segfaults, fatal errors,
and similar. The file and function names it outputs are encoded to ASCII with
backslashreplace and truncated to 500 characters. It writes only the first
100 frames; further frames are truncated with the line @code{...}.

This function will return @code{NULL} on success, or an error message on error.

This function is intended for use in crash scenarios such as signal handlers
for SIGSEGV, where the interpreter may be in an inconsistent state. Given
that it reads interpreter data structures that may be partially modified, the
function might produce incomplete output or it may even crash itself.

The caller does not need to hold an @ref{1a1,,attached thread state}, nor does
`tstate' need to be attached.


Added in version 3.15.

@end deffn

@geindex PyUnstable_DumpTracebackThreads (C function)
@anchor{c-api/exceptions c PyUnstable_DumpTracebackThreads}@anchor{39a}
@deffn {C Συνάρτηση} const char *PyUnstable_DumpTracebackThreads (int fd, PyInterpreterState *interp, PyThreadState *current_tstate, Py_ssize_t max_threads)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Write the traces of all Python threads in `interp' into the file `fd'.

If `interp' is @code{NULL} then this function will try to identify the current
interpreter using thread-specific storage. If it cannot, it will return an
error.

If `current_tstate' is not @code{NULL} then it will be used to identify what the
current thread is in the written output. If it is @code{NULL} then this function
will identify the current thread using thread-specific storage. It is not an
error if the function is unable to get the current Python thread state.

This function will return @code{NULL} on success, or an error message on error.

This function is meant to debug debug situations such as segfaults, fatal
errors, and similar. It calls @ref{399,,PyUnstable_DumpTraceback()} for each
thread. It only writes the tracebacks of the first `max_threads' threads,
further output is truncated with the line @code{...}. If `max_threads' is 0, the
function will use a default value of 100 for the argument.

This function is intended for use in crash scenarios such as signal handlers
for SIGSEGV, where the interpreter may be in an inconsistent state. Given
that it reads interpreter data structures that may be partially modified, the
function might produce incomplete output or it may even crash itself.

The caller does not need to hold an @ref{1a1,,attached thread state}, nor does
`current_tstate' need to be attached.

@cartouche
@quotation Προειδοποίηση 
On the @ref{198,,free-threaded build}, this function is not thread-safe. If
another thread deletes its @ref{1a70,,thread state} while this function is being
called, the process will likely crash.
@end quotation
@end cartouche


Added in version 3.15.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Defining extension modules,Definition slots,Exception Handling,Python/C API reference manual
@anchor{c-api/extension-modules doc}@anchor{5555}@anchor{c-api/extension-modules defining-extension-modules}@anchor{5556}@anchor{c-api/extension-modules extension-modules}@anchor{5212}@anchor{c-api/extension-modules translation-repo}@anchor{5557}
@section Defining extension modules


A C extension for CPython is a shared library (for example, a @code{.so} file
on Linux, @code{.pyd} DLL on Windows), which is loadable into the Python process
(for example, it is compiled with compatible compiler settings), and which
exports an `export hook' function (or an
old-style @ref{5558,,initialization function}).

To be importable by default (that is, by
@ref{1071,,importlib.machinery.ExtensionFileLoader}),
the shared library must be available on @ref{194,,sys.path},
and must be named after the module name plus an extension listed in
@ref{924,,importlib.machinery.EXTENSION_SUFFIXES}.

@cartouche
@quotation Σημείωση 
Building, packaging and distributing extension modules is best done with
third-party tools, and is out of scope of this document.
One suitable tool is Setuptools, whose documentation can be found at
@indicateurl{https://setuptools.pypa.io/en/latest/setuptools.html}.
@end quotation
@end cartouche

@menu
* Extension export hook:: 
* Multi-phase initialization:: 
* Multiple module instances:: 
* PyInit function:: 

@end menu

@node Extension export hook,Multi-phase initialization,,Defining extension modules
@anchor{c-api/extension-modules extension-export-hook}@anchor{38d}@anchor{c-api/extension-modules id1}@anchor{5559}
@subsection Extension export hook



Added in version 3.15: Support for the @code{PyModExport_@var{<name>}} export hook was added in Python
3.15. The older way of defining modules is still available: consult either
the @ref{5558,,PyInit function} section or earlier versions of this
documentation if you plan to support earlier Python versions.


The export hook must be an exported function with the following signature:

@geindex PyModExport_modulename (C function)
@anchor{c-api/extension-modules c PyModExport_modulename}@anchor{19c}
@deffn {C Συνάρτηση} @ref{19d,,PySlot} *PyModExport_modulename (void)
@end deffn

For modules with ASCII-only names, the @ref{38d,,export hook}
must be named @code{PyModExport_@var{<name>}},
with @code{<name>} replaced by the module’s name.

For non-ASCII module names, the export hook must instead be named
@code{PyModExportU_@var{<name>}} (note the @code{U}), with @code{<name>} encoded using
Python’s `punycode' encoding with hyphens replaced by underscores. In Python:

@example
def hook_name(name):
    try:
        suffix = b'_' + name.encode('ascii')
    except UnicodeEncodeError:
        suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
    return b'PyModExport' + suffix
@end example

The export hook returns an array of @ref{19d,,PySlot} entries,
terminated by an entry with a slot ID of @code{0}.
These slots describe how the module should be created and initialized.

This array must remain valid and constant until interpreter shutdown.
Typically, it should use @code{static} storage.
Prefer using the @ref{5495,,Py_mod_create} and @ref{d46,,Py_mod_exec} slots
for any dynamic behavior.

The export hook may return @code{NULL} with an exception set to signal failure.

It is recommended to define the export hook function using a helper macro:

@geindex PyMODEXPORT_FUNC (C macro)
@anchor{c-api/extension-modules c PyMODEXPORT_FUNC}@anchor{1990}
@deffn {C Μακροεντολή} PyMODEXPORT_FUNC
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Declare an extension module export hook.
This macro:


@itemize *

@item 
specifies the @ref{19d,,PySlot}* return type,

@item 
adds any special linkage declarations required by the platform, and

@item 
for C++, declares the function as @code{extern "C"}.
@end itemize
@end deffn

For example, a module called @code{spam} would be defined like this:

@example
PyABIInfo_VAR(abi_info);

static PySlot spam_slots[] = @{
    PySlot_STATIC_DATA(Py_mod_abi, &abi_info),
    PySlot_STATIC_DATA(Py_mod_name, "spam"),
    PySlot_FUNC(Py_mod_init, spam_init_function),
    ...
    PySlot_END
@};

PyMODEXPORT_FUNC
PyModExport_spam(void)
@{
    return spam_slots;
@}
@end example

The export hook is typically the only non-@code{static}
item defined in the module’s C source.

The hook should be kept short – ideally, one line as above.
If you do need to use Python C API in this function, it is recommended to call
@code{PyABIInfo_Check(&abi_info, "modulename")} first to raise an exception,
rather than crash, in common cases of ABI mismatch.

@cartouche
@quotation Σημείωση 
It is possible to export multiple modules from a single shared library by
defining multiple export hooks.
However, importing  them requires a custom importer or suitably named
copies/links of the extension file, because Python’s import machinery only
finds the function corresponding to the filename.
See the Multiple modules in one library@footnote{https://peps.python.org/pep-0489/#multiple-modules-in-one-library}
section in 
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/} for details.
@end quotation
@end cartouche

@node Multi-phase initialization,Multiple module instances,Extension export hook,Defining extension modules
@anchor{c-api/extension-modules id2}@anchor{555a}@anchor{c-api/extension-modules multi-phase-initialization}@anchor{555b}
@subsection Multi-phase initialization


The process of creating an extension module follows several phases:


@itemize -

@item 
Python finds and calls the export hook to get information on how to
create the module.

@item 
Before any substantial code is executed, Python can determine which
capabilities the module supports, and it can adjust the environment or
refuse loading an incompatible extension.
Slots like @ref{358,,Py_mod_abi}, @ref{691,,Py_mod_gil} and
@ref{5496,,Py_mod_multiple_interpreters} influence this step.

@item 
By default, Python itself then creates the module object – that is, it does
the equivalent of calling @ref{982,,__new__()} when creating an object.
This step can be overridden using the @ref{5495,,Py_mod_create} slot.

@item 
Python sets initial module attributes like @ref{58c,,__package__} and
@ref{2ff,,__loader__}, and inserts the module object into
@ref{19ba,,sys.modules}.

@item 
Afterwards, the module object is initialized in an extension-specific way
– the equivalent of @ref{2fa,,__init__()} when creating an object,
or of executing top-level code in a Python-language module.
The behavior is specified using the @ref{d46,,Py_mod_exec} slot.
@end itemize

This is called `multi-phase initialization' to distinguish it from the legacy
(but still supported) @ref{555c,,single-phase initialization},
where an initialization function returns a fully constructed module.


Άλλαξε στην έκδοση 3.5: Added support for multi-phase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).


@node Multiple module instances,PyInit function,Multi-phase initialization,Defining extension modules
@anchor{c-api/extension-modules multiple-module-instances}@anchor{555d}
@subsection Multiple module instances


By default, extension modules are not singletons.
For example, if the @ref{19ba,,sys.modules} entry is removed and the module
is re-imported, a new module object is created and, typically, populated with
fresh method and type objects.
The old module is subject to normal garbage collection.
This mirrors the behavior of pure-Python modules.

Additional module instances may be created in
@ref{410,,sub-interpreters}
or after Python runtime reinitialization
(@ref{672,,Py_Finalize()} and @ref{673,,Py_Initialize()}).
In these cases, sharing Python objects between module instances would likely
cause crashes or undefined behavior.

To avoid such issues, each instance of an extension module should
be `isolated': changes to one instance should not implicitly affect the others,
and all state owned by the module, including references to Python objects,
should be specific to a particular module instance.
See @ref{412,,Isolating Extension Modules} for more details and a practical guide.

A simpler way to avoid these issues is
@ref{555e,,raising an error on repeated initialization}.

All modules are expected to support
@ref{410,,sub-interpreters}, or otherwise explicitly
signal a lack of support.
This is usually achieved by isolation or blocking repeated initialization,
as above.
A module may also be limited to the main interpreter using
the @ref{5496,,Py_mod_multiple_interpreters} slot.

@node PyInit function,,Multiple module instances,Defining extension modules
@anchor{c-api/extension-modules extension-pyinit}@anchor{5558}@anchor{c-api/extension-modules pyinit-function}@anchor{555f}
@subsection @code{PyInit} function



@ref{1a7,,Soft deprecated} since version 3.15: This functionality will not get new features,
but there are no plans to remove it.


Instead of @ref{19c,,PyModExport_modulename()}, an extension module can define
an older-style `initialization function' with the signature:

@geindex PyInit_modulename (C function)
@anchor{c-api/extension-modules c PyInit_modulename}@anchor{5560}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyInit_modulename (void)
@end deffn

Its name should be @code{PyInit_@var{<name>}}, with @code{<name>} replaced by the
name of the module.
For non-ASCII module names, use @code{PyInitU_@var{<name>}} instead, with
@code{<name>} encoded in the same way as for the
@ref{38d,,export hook} (that is, using Punycode
with underscores).

If a module exports both @code{PyInit_@var{<name>}} and
@code{PyModExport_@var{<name>}}, the @code{PyInit_@var{<name>}} function
is ignored.

Like with @ref{1990,,PyMODEXPORT_FUNC}, it is recommended to define the
initialization function using a helper macro:

@geindex PyMODINIT_FUNC (C macro)
@anchor{c-api/extension-modules c PyMODINIT_FUNC}@anchor{1875}
@deffn {C Μακροεντολή} PyMODINIT_FUNC

Declare an extension module initialization function.
This macro:


@itemize *

@item 
specifies the @ref{19b,,PyObject}* return type,

@item 
adds any special linkage declarations required by the platform, and

@item 
for C++, declares the function as @code{extern "C"}.
@end itemize
@end deffn

Normally, the initialization function (@code{PyInit_modulename}) returns
a @ref{d45,,PyModuleDef} instance with non-@code{NULL}
@ref{196c,,m_slots}. This allows Python to use
@ref{555b,,multi-phase initialization}.

Before it is returned, the @code{PyModuleDef} instance must be initialized
using the following function:

@geindex PyModuleDef_Init (C function)
@anchor{c-api/extension-modules c PyModuleDef_Init}@anchor{538c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyModuleDef_Init (PyModuleDef *def)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.5.'
Ensure a module definition is a properly initialized Python object that
correctly reports its type and a reference count.

Return `def' cast to @code{PyObject*}, or @code{NULL} if an error occurred.

Calling this function is required before returning a @ref{d45,,PyModuleDef}
from a module initialization function.
It should not be used in other contexts.

Note that Python assumes that @code{PyModuleDef} structures are statically
allocated.
This function may return either a new reference or a borrowed one;
this reference must not be released.


Added in version 3.5.

@end deffn

For example, a module called @code{spam} would be defined like this:

@example
static struct PyModuleDef spam_module = @{
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "spam",
    ...
@};

PyMODINIT_FUNC
PyInit_spam(void)
@{
    return PyModuleDef_Init(&spam_module);
@}
@end example

@menu
* Legacy single-phase initialization:: 

@end menu

@node Legacy single-phase initialization,,,PyInit function
@anchor{c-api/extension-modules legacy-single-phase-initialization}@anchor{5561}@anchor{c-api/extension-modules single-phase-initialization}@anchor{555c}
@subsubsection Legacy single-phase initialization



@ref{1a7,,Soft deprecated} since version 3.15: Single-phase initialization is a legacy mechanism to initialize extension
modules, with known drawbacks and design flaws. Extension module authors
are encouraged to use multi-phase initialization instead.

However, there are no plans to remove support for it.


In single-phase initialization, the old-style
@ref{5558,,initialization function} (@code{PyInit_modulename})
should create, populate and return a module object.
This is typically done using @ref{5562,,PyModule_Create()} and functions like
@ref{800,,PyModule_AddObjectRef()}.

Single-phase initialization differs from the @ref{555b,,default}
in the following ways:


@itemize *

@item 
Single-phase modules are, or rather `contain', “singletons”.

When the module is first initialized, Python saves the contents of
the module’s @code{__dict__} (that is, typically, the module’s functions and
types).

For subsequent imports, Python does not call the initialization function
again.
Instead, it creates a new module object with a new @code{__dict__}, and copies
the saved contents to it.
For example, given a single-phase module @code{_testsinglephase}
@footnote{
@code{_testsinglephase} is an internal module used
in CPython’s self-test suite; your installation may or may not
include it.
} that defines a function @code{sum} and an exception class
@code{error}:

@example
>>> import sys
>>> import _testsinglephase as one
>>> del sys.modules['_testsinglephase']
>>> import _testsinglephase as two
>>> one is two
False
>>> one.__dict__ is two.__dict__
False
>>> one.sum is two.sum
True
>>> one.error is two.error
True
@end example

The exact behavior should be considered a CPython implementation detail.

@item 
To work around the fact that @code{PyInit_modulename} does not take a `spec'
argument, some state of the import machinery is saved and applied to the
first suitable module created during the @code{PyInit_modulename} call.
Specifically, when a sub-module is imported, this mechanism prepends the
parent package name to the name of the module.

A single-phase @code{PyInit_modulename} function should create “its” module
object as soon as possible, before any other module objects can be created.

@item 
Non-ASCII module names (@code{PyInitU_modulename}) are not supported.

@item 
Single-phase modules support module lookup functions like
@ref{53ef,,PyState_FindModule()}.

@item 
The module’s @ref{196c,,PyModuleDef.m_slots} must be NULL.
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Definition slots,Utilities<2>,Defining extension modules,Python/C API reference manual
@anchor{c-api/slots doc}@anchor{5563}@anchor{c-api/slots capi-slots}@anchor{375}@anchor{c-api/slots definition-slots}@anchor{5564}@anchor{c-api/slots translation-repo}@anchor{5565}
@section Definition slots


To define @ref{5566,,module objects} and
@ref{5567,,classes} using the C API, you may use
an array of `slots' – essentally, key-value pairs that describe features
of the object to create.
This decouples the data from the structures used at runtime, allowing CPython
– and other Python C API implementations – to update the stuctures without
breaking backwards compatibility.

This section documents slots in general.
For object-specific behavior and slot values, see documentation for functions
that apply slots:


@itemize -

@item 
@ref{376,,PyType_FromSlots()} for types;

@item 
@ref{38c,,PyModule_FromSlotsAndSpec()} and @ref{38d,,Extension export hook}
for modules.
@end itemize

When slots are passed to a function that applies them, the function will
not modify the slot array, nor any data it points to (recursively).
After the function is done, the caller is allowed to modify or deallocate
the array and any data it points to (recursively), except data
explicitly marked with @ref{53ed,,PySlot_STATIC}.

Except when documented otherwise, multiple slots with the same ID
(@ref{5568,,sl_id}) may not occur in a single slots array.


Added in version 3.15: Slot arrays generalize an earlier way of defining objects:
using @ref{1c8f,,PyType_Spec} with @ref{541b,,PyType_Slot} for types, and
@ref{d45,,PyModuleDef} with @ref{538d,,PyModuleDef_Slot} for modules.
The earlier API is @ref{1a7,,soft deprecated}; there are no plans to remove it.


Entries of the slots array use the following structure:

@geindex PySlot (C type)
@anchor{c-api/slots c PySlot}@anchor{19d}
@deffn {C Τύπος} type PySlot
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών) από την έκδοση 3.15.'
An entry in a slots array. Defined as:

@example
typedef struct @{
    uint16_t sl_id;
    uint16_t sl_flags;
    uint32_t _reserved;  // must be 0
    union @{
        void *sl_ptr;
        void (*sl_func)(void);
        Py_ssize_t sl_size;
        int64_t sl_int64;
        uint64_t sl_uint64;
    @};
@} PySlot;
@end example

@geindex PySlot.sl_id (C member)
@anchor{c-api/slots c PySlot sl_id}@anchor{5568}
@deffn {C Μέλος} uint16_t sl_id

A slot ID, chosen from:


@itemize -

@item 
@code{Py_slot_*} values documented in @ref{5569,,Common slot IDs} below;

@item 
@code{Py_mod_*} values for modules, as documented in @ref{556a,,Module definition};

@item 
Values for types, as documented in @ref{556b,,Type slot IDs}.
@end itemize

A @code{sl_id} of zero (@ref{377,,Py_slot_end}) marks the end of a
slots array.
@end deffn

@geindex PySlot.sl_ptr (C member)
@geindex PySlot.sl_func (C member)
@geindex PySlot.sl_size (C member)
@geindex PySlot.sl_int64 (C member)
@geindex PySlot.sl_uint64 (C member)
@anchor{c-api/slots c PySlot sl_ptr}@anchor{556c}
@deffn {C Μέλος} void *sl_ptr
@anchor{c-api/slots c PySlot sl_func}@anchor{556d}
@deffnx {C Μέλος} void (*sl_func)(void)
@anchor{c-api/slots c PySlot sl_size}@anchor{556e}
@deffnx {C Μέλος} @ref{e24,,Py_ssize_t} sl_size
@anchor{c-api/slots c PySlot sl_int64}@anchor{556f}
@deffnx {C Μέλος} int64_t sl_int64
@anchor{c-api/slots c PySlot sl_uint64}@anchor{5570}
@deffnx {C Μέλος} uint64_t sl_uint64

The data for the slot.
These members are part of an anonymous union;
the member to use depends on which data type is required by the slot ID:
data pointer, function pointer, size, signed or unsigned
integer, respectively.

Except when documented otherwise for a specific slot ID, pointers
(that is @code{sl_ptr} and @code{sl_func}) may not be NULL.
@end deffn

@geindex PySlot.sl_flags (C member)
@anchor{c-api/slots c PySlot sl_flags}@anchor{5571}
@deffn {C Μέλος} uint16_t sl_flags

Zero or more of the following flags, OR-ed together:

@geindex PySlot_STATIC (C macro)
@anchor{c-api/slots c PySlot_STATIC}@anchor{53ed}
@deffn {C Μακροεντολή} PySlot_STATIC
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
All data the slot points to is statically allocated and constant.
Thus, the interpreter does not need to copy the information.

This flag is implied for function pointers.

The flag applies even to data the slot points to “indirectly”,
except for slots nested via @ref{379,,Py_slot_subslots} which may
have their own @code{PySlot_STATIC} flags.
For example, if applied to a @ref{54de,,Py_tp_members} slot that
points to an array of @ref{95a,,PyMemberDef} structures,
then the entire array, as well as the name and doc strings
in its elements, must be static and constant.
@end deffn

@geindex PySlot_INTPTR (C macro)
@anchor{c-api/slots c PySlot_INTPTR}@anchor{53eb}
@deffn {C Μακροεντολή} PySlot_INTPTR
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
The data is stored in @code{sl_ptr}; CPython will cast it to
the appropriate type.

This flag can simplify porting from the older @ref{541b,,PyType_Slot}
and @ref{538d,,PyModuleDef_Slot} structures.
@end deffn

@geindex PySlot_OPTIONAL (C macro)
@anchor{c-api/slots c PySlot_OPTIONAL}@anchor{53ec}
@deffn {C Μακροεντολή} PySlot_OPTIONAL
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
If the slot ID is unknown, the interpreter should ignore the
slot, rather than fail.

For example, if Python 3.16 adds a new feature with a new slot ID,attr
the corresponding slot may be marked @code{PySlot_OPTIONAL}
so that Python 3.15 ignores it.

Note that the «optionality» only applies to unknown slot IDs.
This flag does not make Python skip invalid values of known slots.
@end deffn
@end deffn


Added in version 3.15.

@end deffn

@menu
* Convenience macros:: 
* Common slot IDs:: 

@end menu

@node Convenience macros,Common slot IDs,,Definition slots
@anchor{c-api/slots convenience-macros}@anchor{5572}
@subsection Convenience macros


@geindex PySlot_DATA (C macro)
@geindex PySlot_FUNC (C macro)
@geindex PySlot_SIZE (C macro)
@geindex PySlot_INT64 (C macro)
@geindex PySlot_UINT64 (C macro)
@geindex PySlot_STATIC_DATA (C macro)
@anchor{c-api/slots c PySlot_DATA}@anchor{383}
@deffn {C Μακροεντολή} PySlot_DATA (name, value)
@anchor{c-api/slots c PySlot_FUNC}@anchor{384}
@deffnx {C Μακροεντολή} PySlot_FUNC (name, value)
@anchor{c-api/slots c PySlot_SIZE}@anchor{385}
@deffnx {C Μακροεντολή} PySlot_SIZE (name, value)
@anchor{c-api/slots c PySlot_INT64}@anchor{386}
@deffnx {C Μακροεντολή} PySlot_INT64 (name, value)
@anchor{c-api/slots c PySlot_UINT64}@anchor{387}
@deffnx {C Μακροεντολή} PySlot_UINT64 (name, value)
@anchor{c-api/slots c PySlot_STATIC_DATA}@anchor{388}
@deffnx {C Μακροεντολή} PySlot_STATIC_DATA (name, value)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Convenience macros to define @code{PySlot} structures with
@ref{5568,,sl_id} and a particular union member set.

@code{PySlot_STATIC_DATA} sets the @ref{53ed,,PySlot_STATIC} flag;
others set no flags.

Note that these macros use `designated initializers', a C language feature
that C++ added in the 2020 version of the standard.
If your code needs to be compatible with C++11 or older,
use @ref{38a,,PySlot_PTR} instead.

Defined as:

@example
#define PySlot_DATA(NAME, VALUE) \
   @{.sl_id=NAME, .sl_ptr=(void*)(VALUE)@}

#define PySlot_FUNC(NAME, VALUE) \
   @{.sl_id=NAME, .sl_func=(VALUE)@}

#define PySlot_SIZE(NAME, VALUE) \
   @{.sl_id=NAME, .sl_size=(VALUE)@}

#define PySlot_INT64(NAME, VALUE) \
   @{.sl_id=NAME, .sl_int64=(VALUE)@}

#define PySlot_UINT64(NAME, VALUE) \
   @{.sl_id=NAME, .sl_uint64=(VALUE)@}

#define PySlot_STATIC_DATA(NAME, VALUE) \
   @{.sl_id=NAME, .sl_flags=PySlot_STATIC, .sl_ptr=(VALUE)@}
@end example


Added in version 3.15.

@end deffn

@geindex PySlot_END (C macro)
@anchor{c-api/slots c PySlot_END}@anchor{389}
@deffn {C Μακροεντολή} PySlot_END
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Convenience macro to mark the end of a @code{PySlot} array.

Defined as:

@example
#define PySlot_END @{0@}
@end example


Added in version 3.15.

@end deffn

@geindex PySlot_PTR (C macro)
@geindex PySlot_PTR_STATIC (C macro)
@anchor{c-api/slots c PySlot_PTR}@anchor{38a}
@deffn {C Μακροεντολή} PySlot_PTR (name, value)
@anchor{c-api/slots c PySlot_PTR_STATIC}@anchor{38b}
@deffnx {C Μακροεντολή} PySlot_PTR_STATIC (name, value)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Convenience macros for use in C++11-compatible code.
This version of C++ does not allow setting arbitrary union members in
literals; instead, these macros set the @ref{53eb,,PySlot_INTPTR} flag and cast
the value to @code{(void*)}.

Defined as:

@example
#define PySlot_PTR(NAME, VALUE) \
   @{NAME, PySlot_INTPTR, @{0@}, @{(void*)(VALUE)@}@}

#define PySlot_PTR_STATIC(NAME, VALUE) \
   @{NAME, PySlot_INTPTR|Py_SLOT_STATIC, @{0@}, @{(void*)(VALUE)@}@}
@end example


Added in version 3.15.

@end deffn

@node Common slot IDs,,Convenience macros,Definition slots
@anchor{c-api/slots common-slot-ids}@anchor{5573}@anchor{c-api/slots pyslot-common-ids}@anchor{5569}
@subsection Common slot IDs


The following slot IDs may be used in both type and module definitions.

@geindex Py_slot_end (C macro)
@anchor{c-api/slots c Py_slot_end}@anchor{377}
@deffn {C Μακροεντολή} Py_slot_end
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Marks the end of a slots array.
Defined as zero.


Added in version 3.15.

@end deffn

@geindex Py_slot_subslots (C macro)
@anchor{c-api/slots c Py_slot_subslots}@anchor{379}
@deffn {C Μακροεντολή} Py_slot_subslots
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Nested slots array.

The value (@ref{556c,,sl_ptr}) should point to an array of
@ref{19d,,PySlot} structures.
The slots in the array (up to but not including the zero-ID
terminator) will be treated as if they were inserted if the current
slot array, at the point @code{Py_slot_subslots} appears.

Slot nesting depth is limited to 5 levels.
This restriction may be lifted in the future.


Added in version 3.15.

@end deffn

@geindex Py_slot_invalid (C macro)
@anchor{c-api/slots c Py_slot_invalid}@anchor{378}
@deffn {C Μακροεντολή} Py_slot_invalid
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Reserved; will always be treated as an unknown slot ID.
Defined as @code{UINT16_MAX} (@code{0xFFFF}).

When used with the @ref{53ec,,PySlot_OPTIONAL} flag, defines a slot with
no effect.
Without the flag, processing a slot with this ID will fail.


Added in version 3.15.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Utilities<2>,Abstract Objects Layer,Definition slots,Python/C API reference manual
@anchor{c-api/utilities doc}@anchor{5574}@anchor{c-api/utilities id1}@anchor{5575}@anchor{c-api/utilities translation-repo}@anchor{5576}@anchor{c-api/utilities utilities}@anchor{5577}
@section Utilities


The functions in this chapter perform various utility tasks, ranging from
helping C code be more portable across platforms, using Python modules from C,
and parsing function arguments and constructing Python values from C values.

@menu
* Operating System Utilities:: 
* System Functions:: 
* Process Control:: 
* Importing Modules: Importing Modules<2>. 
* Data marshalling support:: 
* Parsing arguments and building values:: 
* String conversion and formatting:: 
* Character classification and conversion:: 
* PyHash API:: 
* Reflection:: 
* Codec registry and support functions:: 
* PyTime C API:: 
* Support for Perf Maps:: 

@end menu

@node Operating System Utilities,System Functions,,Utilities<2>
@anchor{c-api/sys doc}@anchor{5578}@anchor{c-api/sys operating-system-utilities}@anchor{5579}@anchor{c-api/sys os}@anchor{557a}
@subsection Operating System Utilities


@geindex PyOS_FSPath (C function)
@anchor{c-api/sys c PyOS_FSPath}@anchor{10d2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyOS_FSPath (PyObject *path)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.6.'
Return the file system representation for `path'. If the object is a
@ref{1df,,str} or @ref{1c7,,bytes} object, then a new
@ref{7da,,strong reference} is returned.
If the object implements the @ref{100f,,os.PathLike} interface,
then @ref{1010,,__fspath__()} is returned as long as it is a
@code{str} or @code{bytes} object. Otherwise @ref{291,,TypeError} is raised
and @code{NULL} is returned.


Added in version 3.6.

@end deffn

@geindex Py_FdIsInteractive (C function)
@anchor{c-api/sys c Py_FdIsInteractive}@anchor{557b}
@deffn {C Συνάρτηση} 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{613,,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{f7d}
@deffn {C Συνάρτηση} void PyOS_BeforeFork ()
` Μέρος του @ref{95c,,Σταθερό ABI} on platforms with fork() από την έκδοση 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 Προειδοποίηση 
The C @code{fork()} call should only be made from the
@ref{557c,,«main» thread} (of the
@ref{410,,«main» interpreter}).  The same is
true for @code{PyOS_BeforeFork()}.
@end quotation
@end cartouche


Added in version 3.7.

@end deffn

@geindex PyOS_AfterFork_Parent (C function)
@anchor{c-api/sys c PyOS_AfterFork_Parent}@anchor{f7e}
@deffn {C Συνάρτηση} void PyOS_AfterFork_Parent ()
` Μέρος του @ref{95c,,Σταθερό ABI} on platforms with fork() από την έκδοση 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 Προειδοποίηση 
The C @code{fork()} call should only be made from the
@ref{557c,,«main» thread} (of the
@ref{410,,«main» interpreter}).  The same is
true for @code{PyOS_AfterFork_Parent()}.
@end quotation
@end cartouche


Added in version 3.7.

@end deffn

@geindex PyOS_AfterFork_Child (C function)
@anchor{c-api/sys c PyOS_AfterFork_Child}@anchor{643}
@deffn {C Συνάρτηση} void PyOS_AfterFork_Child ()
` Μέρος του @ref{95c,,Σταθερό ABI} on platforms with fork() από την έκδοση 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 Προειδοποίηση 
The C @code{fork()} call should only be made from the
@ref{557c,,«main» thread} (of the
@ref{410,,«main» interpreter}).  The same is
true for @code{PyOS_AfterFork_Child()}.
@end quotation
@end cartouche


Added in version 3.7.



@subsubheading Δείτε επίσης


@ref{332,,os.register_at_fork()} allows registering custom Python functions
to be called by @ref{f7d,,PyOS_BeforeFork()},
@ref{f7e,,PyOS_AfterFork_Parent()} and  @ref{643,,PyOS_AfterFork_Child()}.

@end deffn

@geindex PyOS_AfterFork (C function)
@anchor{c-api/sys c PyOS_AfterFork}@anchor{642}
@deffn {C Συνάρτηση} void PyOS_AfterFork ()
` Μέρος του @ref{95c,,Σταθερό 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.


Αποσύρθηκε στην έκδοση 3.7: This function is superseded by @ref{643,,PyOS_AfterFork_Child()}.

@end deffn

@geindex PyOS_CheckStack (C function)
@anchor{c-api/sys c PyOS_CheckStack}@anchor{1d9b}
@deffn {C Συνάρτηση} int PyOS_CheckStack ()
` Μέρος του @ref{95c,,Σταθερό ABI} on platforms with USE_STACKCHECK από την έκδοση 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{53bb}
@deffn {C Τύπος} typedef void (*PyOS_sighandler_t)(int)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyOS_getsig (C function)
@anchor{c-api/sys c PyOS_getsig}@anchor{18e0}
@deffn {C Συνάρτηση} @ref{53bb,,PyOS_sighandler_t} PyOS_getsig (int i)
` Μέρος του @ref{95c,,Σταθερό 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{18e1}
@deffn {C Συνάρτηση} @ref{53bb,,PyOS_sighandler_t} PyOS_setsig (int i, PyOS_sighandler_t h)
` Μέρος του @ref{95c,,Σταθερό 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 PyOS_InterruptOccurred (C function)
@anchor{c-api/sys c PyOS_InterruptOccurred}@anchor{1f36}
@deffn {C Συνάρτηση} int PyOS_InterruptOccurred (void)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Check if a @code{SIGINT} signal has been received.

Returns @code{1} if a @code{SIGINT} has occurred and clears the signal flag,
or @code{0} otherwise.

In most cases, you should prefer @ref{880,,PyErr_CheckSignals()} over this function.
@code{PyErr_CheckSignals()} invokes the appropriate signal handlers
for all pending signals, allowing Python code to handle the signal properly.
This function only detects @code{SIGINT} and does not invoke any Python
signal handlers.

This function is async-signal-safe and this function cannot fail.
The caller must hold an @ref{1a1,,attached thread state}.
@end deffn

@geindex Py_DecodeLocale (C function)
@anchor{c-api/sys c Py_DecodeLocale}@anchor{f85}
@deffn {C Συνάρτηση} wchar_t *Py_DecodeLocale (const char *arg, size_t *size)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@cartouche
@quotation Προειδοποίηση 
This function should not be called directly: use the @ref{60b,,PyConfig}
API with the @ref{d7c,,PyConfig_SetBytesString()} function which ensures
that @ref{4516,,Python is preinitialized}.

This function must not be called before @ref{4516,,Python is preinitialized} and so that the LC_CTYPE locale is properly configured: see
the @ref{631,,Py_PreInitialize()} function.
@end quotation
@end cartouche

Decode a byte string from the @ref{948,,filesystem encoding and error handler}.
If the error handler is @ref{2a6a,,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{826,,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{948,,filesystem encoding and error handler} are selected by
@ref{b6f,,PyConfig_Read()}: see @ref{62e,,filesystem_encoding} and
@ref{62f,,filesystem_errors} members of @ref{60b,,PyConfig}.

Decoding errors should never happen, unless there is a bug in the C
library.

Use the @ref{f86,,Py_EncodeLocale()} function to encode the character string
back to a byte string.


@subsubheading Δείτε επίσης


The @ref{543e,,PyUnicode_DecodeFSDefaultAndSize()} and
@ref{f87,,PyUnicode_DecodeLocaleAndSize()} functions.



Added in version 3.5.



Άλλαξε στην έκδοση 3.7: The function now uses the UTF-8 encoding in the @ref{a46,,Python UTF-8 Mode}.



Άλλαξε στην έκδοση 3.8: The function now uses the UTF-8 encoding on Windows if
@ref{62b,,PyPreConfig.legacy_windows_fs_encoding} is zero;

@end deffn

@geindex Py_EncodeLocale (C function)
@anchor{c-api/sys c Py_EncodeLocale}@anchor{f86}
@deffn {C Συνάρτηση} char *Py_EncodeLocale (const wchar_t *text, size_t *error_pos)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Encode a wide character string to the @ref{948,,filesystem encoding and error handler}. If the error handler is @ref{2a6a,,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{17e4,,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{948,,filesystem encoding and error handler} are selected by
@ref{b6f,,PyConfig_Read()}: see @ref{62e,,filesystem_encoding} and
@ref{62f,,filesystem_errors} members of @ref{60b,,PyConfig}.

Use the @ref{f85,,Py_DecodeLocale()} function to decode the bytes string back
to a wide character string.

@cartouche
@quotation Προειδοποίηση 
This function must not be called before @ref{4516,,Python is preinitialized} and so that the LC_CTYPE locale is properly configured: see
the @ref{631,,Py_PreInitialize()} function.
@end quotation
@end cartouche


@subsubheading Δείτε επίσης


The @ref{201e,,PyUnicode_EncodeFSDefault()} and
@ref{f88,,PyUnicode_EncodeLocale()} functions.



Added in version 3.5.



Άλλαξε στην έκδοση 3.7: The function now uses the UTF-8 encoding in the @ref{a46,,Python UTF-8 Mode}.



Άλλαξε στην έκδοση 3.8: The function now uses the UTF-8 encoding on Windows if
@ref{62b,,PyPreConfig.legacy_windows_fs_encoding} is zero.

@end deffn

@geindex Py_fopen (C function)
@anchor{c-api/sys c Py_fopen}@anchor{5c0}
@deffn {C Συνάρτηση} FILE *Py_fopen (PyObject *path, const char *mode)

Similar to @code{fopen()}, but `path' is a Python object and
an exception is set on error.

`path' must be a @ref{1df,,str} object, a @ref{1c7,,bytes} object,
or a @ref{79f,,path-like object}.

On success, return the new file pointer.
On error, set an exception and return @code{NULL}.

The file must be closed by @ref{5c1,,Py_fclose()} rather than calling directly
@code{fclose()}.

The file descriptor is created non-inheritable (
@geindex Python Enhancement Proposals; PEP 446
PEP 446@footnote{https://peps.python.org/pep-0446/}).

The caller must have an @ref{1a1,,attached thread state}.


Added in version 3.14.

@end deffn

@geindex Py_fclose (C function)
@anchor{c-api/sys c Py_fclose}@anchor{5c1}
@deffn {C Συνάρτηση} int Py_fclose (FILE *file)

Close a file that was opened by @ref{5c0,,Py_fopen()}.

On success, return @code{0}.
On error, return @code{EOF} and @code{errno} is set to indicate the error.
In either case, any further access (including another call to
@ref{5c1,,Py_fclose()}) to the stream results in undefined behavior.


Added in version 3.14.

@end deffn

@node System Functions,Process Control,Operating System Utilities,Utilities<2>
@anchor{c-api/sys system-functions}@anchor{557d}@anchor{c-api/sys systemfunctions}@anchor{557e}
@subsection System Functions


These are utility functions that make functionality from the @ref{e2,,sys} module
accessible to C code.  They all work with the current interpreter thread’s
@code{sys} module’s dict, which is contained in the internal thread state structure.

@geindex PySys_GetAttr (C function)
@anchor{c-api/sys c PySys_GetAttr}@anchor{352}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySys_GetAttr (PyObject *name)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Get the attribute `name' of the @ref{e2,,sys} module.
Return a @ref{7da,,strong reference}.
Raise @ref{30d,,RuntimeError} and return @code{NULL} if it does not exist or
if the @code{sys} module cannot be found.

If the non-existing object should not be treated as a failure, you can use
@ref{354,,PySys_GetOptionalAttr()} instead.


Added in version 3.15.

@end deffn

@geindex PySys_GetAttrString (C function)
@anchor{c-api/sys c PySys_GetAttrString}@anchor{353}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySys_GetAttrString (const char *name)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
This is the same as @ref{352,,PySys_GetAttr()}, but `name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.

If the non-existing object should not be treated as a failure, you can use
@ref{355,,PySys_GetOptionalAttrString()} instead.


Added in version 3.15.

@end deffn

@geindex PySys_GetOptionalAttr (C function)
@anchor{c-api/sys c PySys_GetOptionalAttr}@anchor{354}
@deffn {C Συνάρτηση} int PySys_GetOptionalAttr (PyObject *name, PyObject **result)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Variant of @ref{352,,PySys_GetAttr()} which doesn’t raise
exception if the object does not exist.


@itemize *

@item 
Set `*result' to a new @ref{7da,,strong reference} to the object and
return @code{1} if the object exists.

@item 
Set `*result' to @code{NULL} and return @code{0} without setting an exception
if the object does not exist.

@item 
Set an exception, set `*result' to @code{NULL}, and return @code{-1},
if an error occurred.
@end itemize


Added in version 3.15.

@end deffn

@geindex PySys_GetOptionalAttrString (C function)
@anchor{c-api/sys c PySys_GetOptionalAttrString}@anchor{355}
@deffn {C Συνάρτηση} int PySys_GetOptionalAttrString (const char *name, PyObject **result)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
This is the same as @ref{354,,PySys_GetOptionalAttr()}, but `name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.


Added in version 3.15.

@end deffn

@geindex PySys_GetObject (C function)
@anchor{c-api/sys c PySys_GetObject}@anchor{356}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySys_GetObject (const char *name)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{353,,PySys_GetAttrString()}, but return a @ref{603,,borrowed reference} and return @code{NULL} `without' setting exception on failure.

Preserves exception that was set before the call.
@end deffn

@geindex PySys_SetObject (C function)
@anchor{c-api/sys c PySys_SetObject}@anchor{53f9}
@deffn {C Συνάρτηση} int PySys_SetObject (const char *name, PyObject *v)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Set `name' in the @ref{e2,,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_WriteStdout (C function)
@anchor{c-api/sys c PySys_WriteStdout}@anchor{53fb}
@deffn {C Συνάρτηση} void PySys_WriteStdout (const char *format, ...)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Write the output string described by `format' to @ref{e9c,,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{e9c,,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{53fa}
@deffn {C Συνάρτηση} void PySys_WriteStderr (const char *format, ...)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
As @ref{53fb,,PySys_WriteStdout()}, but write to @ref{d05,,sys.stderr} or `stderr'
instead.
@end deffn

@geindex PySys_FormatStdout (C function)
@anchor{c-api/sys c PySys_FormatStdout}@anchor{53f7}
@deffn {C Συνάρτηση} void PySys_FormatStdout (const char *format, ...)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Function similar to PySys_WriteStdout() but format the message using
@ref{979,,PyUnicode_FromFormatV()} and don’t truncate the message to an
arbitrary length.


Added in version 3.2.

@end deffn

@geindex PySys_FormatStderr (C function)
@anchor{c-api/sys c PySys_FormatStderr}@anchor{53f6}
@deffn {C Συνάρτηση} void PySys_FormatStderr (const char *format, ...)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
As @ref{53f7,,PySys_FormatStdout()}, but write to @ref{d05,,sys.stderr} or `stderr'
instead.


Added in version 3.2.

@end deffn

@geindex PySys_GetXOptions (C function)
@anchor{c-api/sys c PySys_GetXOptions}@anchor{53f8}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySys_GetXOptions ()
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Return the current dictionary of @ref{178,,-X} options, similarly to
@ref{231f,,sys._xoptions}.  On error, @code{NULL} is returned and an exception is
set.


Added in version 3.2.

@end deffn

@geindex PySys_Audit (C function)
@anchor{c-api/sys c PySys_Audit}@anchor{808}
@deffn {C Συνάρτηση} int PySys_Audit (const char *event, const char *format, ...)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{5ee,,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{e24,,Py_ssize_t}, regardless of whether @code{PY_SSIZE_T_CLEAN} was defined.

@ref{1b36,,sys.audit()} performs the same function from Python code.

See also @ref{807,,PySys_AuditTuple()}.


Added in version 3.8.



Άλλαξε στην έκδοση 3.8.2: Require @ref{e24,,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{807}
@deffn {C Συνάρτηση} int PySys_AuditTuple (const char *event, PyObject *args)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Similar to @ref{808,,PySys_Audit()}, but pass arguments as a Python object.
`args' must be a @ref{1ce,,tuple}. To pass no arguments, `args' can be `NULL'.


Added in version 3.13.

@end deffn

@geindex PySys_AddAuditHook (C function)
@anchor{c-api/sys c PySys_AddAuditHook}@anchor{49a8}
@deffn {C Συνάρτηση} 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{673,,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{d9e,,Exception} (other errors will not be silenced).

The hook function is always called with an @ref{1a1,,attached thread state} 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{1e0a,,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{d9e,,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{557f}
@deffn {C Τύπος} typedef int (*Py_AuditHookFunction)(const char *event, @ref{19b,,PyObject} *args, void *userData)

The type of the hook function.
`event' is the C string event argument passed to @ref{808,,PySys_Audit()} or
@ref{807,,PySys_AuditTuple()}.
`args' is guaranteed to be a @ref{5580,,PyTupleObject}.
`userData' is the argument passed to PySys_AddAuditHook().
@end deffn


Added in version 3.8.

@end deffn

@node Process Control,Importing Modules<2>,System Functions,Utilities<2>
@anchor{c-api/sys process-control}@anchor{5581}@anchor{c-api/sys processcontrol}@anchor{5582}
@subsection Process Control


@geindex Py_FatalError (C function)
@anchor{c-api/sys c Py_FatalError}@anchor{d4b}
@deffn {C Συνάρτηση} void Py_FatalError (const char *message)
` Μέρος του @ref{95c,,Σταθερό 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.


Άλλαξε στην έκδοση 3.9: Log the function name automatically.

@end deffn

@geindex Py_Exit (C function)
@anchor{c-api/sys c Py_Exit}@anchor{1104}
@deffn {C Συνάρτηση} void Py_Exit (int status)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex Py_FinalizeEx (C function)
@geindex exit (C function)

Exit the current process.  This calls @ref{10cf,,Py_FinalizeEx()} and then calls the
standard C library function @code{exit(status)}.  If @code{Py_FinalizeEx()}
indicates an error, the exit status is set to 120.


Άλλαξε στην έκδοση 3.6: Errors from finalization no longer ignored.

@end deffn

@geindex Py_AtExit (C function)
@anchor{c-api/sys c Py_AtExit}@anchor{5468}
@deffn {C Συνάρτηση} int Py_AtExit (void (*func)())
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex Py_FinalizeEx (C function)
@geindex cleanup functions

Register a cleanup function to be called by @ref{10cf,,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{5468,,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 Δείτε επίσης


@ref{1b19,,PyUnstable_AtExit()} for passing a @code{void *data} argument.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Importing Modules<2>,Data marshalling support,Process Control,Utilities<2>
@anchor{c-api/import doc}@anchor{5583}@anchor{c-api/import importing}@anchor{5584}@anchor{c-api/import importing-modules}@anchor{5585}@anchor{c-api/import translation-repo}@anchor{5586}
@subsection Importing Modules


@geindex PyImport_ImportModule (C function)
@anchor{c-api/import c PyImport_ImportModule}@anchor{3a3}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_ImportModule (const char *name)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex package variable;__all__
@geindex __all__ (package variable)
@geindex modules (in module sys)

This is a wrapper around @ref{179e,,PyImport_Import()} which takes a
const char* as an argument instead of a @ref{19b,,PyObject}*.
@end deffn

@geindex PyImport_ImportModuleEx (C function)
@anchor{c-api/import c PyImport_ImportModuleEx}@anchor{154e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_ImportModuleEx (const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
`Επιστρεφόμενη τιμή: New reference.'
@geindex built-in function;__import__

Import a module.  This is best described by referring to the built-in Python
function @ref{ca6,,__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{ca6,,__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{3a3,,PyImport_ImportModule()}.
@end deffn

@geindex PyImport_ImportModuleLevelObject (C function)
@anchor{c-api/import c PyImport_ImportModuleLevelObject}@anchor{5363}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_ImportModuleLevelObject (PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Import a module.  This is best described by referring to the built-in Python
function @ref{ca6,,__import__()}, as the standard @code{__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{ca6,,__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.


Added in version 3.3.

@end deffn

@geindex PyImport_ImportModuleLevel (C function)
@anchor{c-api/import c PyImport_ImportModuleLevel}@anchor{154d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_ImportModuleLevel (const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{5363,,PyImport_ImportModuleLevelObject()}, but the name is a
UTF-8 encoded string instead of a Unicode object.


Άλλαξε στην έκδοση 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{179e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_Import (PyObject *name)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{ca6,,__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{5364}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_ReloadModule (PyObject *m)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{7f1}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_AddModuleRef (const char *name)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{7da,,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{3a3,,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.


Added in version 3.13.

@end deffn

@geindex PyImport_AddModuleObject (C function)
@anchor{c-api/import c PyImport_AddModuleObject}@anchor{535a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_AddModuleObject (PyObject *name)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Similar to @ref{7f1,,PyImport_AddModuleRef()}, but return a @ref{603,,borrowed reference} and `name' is a Python @ref{1df,,str} object.


Added in version 3.3.

@end deffn

@geindex PyImport_AddModule (C function)
@anchor{c-api/import c PyImport_AddModule}@anchor{7f2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_AddModule (const char *name)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{7f1,,PyImport_AddModuleRef()}, but return a @ref{603,,borrowed reference}.
@end deffn

@geindex PyImport_ExecCodeModule (C function)
@anchor{c-api/import c PyImport_ExecCodeModule}@anchor{535b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_ExecCodeModule (const char *name, PyObject *co)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{1c8,,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{19ba,,sys.modules} in error cases, even if `name' was already
in @code{sys.modules} on entry to @ref{535b,,PyImport_ExecCodeModule()}.  Leaving
incompletely initialized modules in @code{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{2555,,__spec__} and @ref{2ff,,__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{141c,,SourceFileLoader} otherwise.

The module’s @ref{255a,,__file__} attribute will be set to the code
object’s @ref{1712,,co_filename}.

This function will reload the module if it was already imported.  See
@ref{5364,,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{535c,,PyImport_ExecCodeModuleEx()} and
@ref{535e,,PyImport_ExecCodeModuleWithPathnames()}.


Άλλαξε στην έκδοση 3.12: The setting of @code{__cached__} and @ref{2ff,,__loader__}
is deprecated. See @ref{245d,,ModuleSpec} for
alternatives.



Άλλαξε στην έκδοση 3.15: @code{__cached__} is no longer set.

@end deffn

@geindex PyImport_ExecCodeModuleEx (C function)
@anchor{c-api/import c PyImport_ExecCodeModuleEx}@anchor{535c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_ExecCodeModuleEx (const char *name, PyObject *co, const char *pathname)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Like @ref{535b,,PyImport_ExecCodeModule()}, but the @ref{255a,,__file__}
attribute of the module object is set to `pathname' if it is non-@code{NULL}.

See also @ref{535e,,PyImport_ExecCodeModuleWithPathnames()}.
@end deffn

@geindex PyImport_ExecCodeModuleObject (C function)
@anchor{c-api/import c PyImport_ExecCodeModuleObject}@anchor{535d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_ExecCodeModuleObject (PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Like @ref{535c,,PyImport_ExecCodeModuleEx()}, but the path to any compiled file
via `cpathname' is used appropriately when non-@code{NULL}.  Of the three
functions, this is the preferred one to use.


Added in version 3.3.



Άλλαξε στην έκδοση 3.12: Setting @code{__cached__} is deprecated. See
@ref{245d,,ModuleSpec} for alternatives.



Άλλαξε στην έκδοση 3.15: @code{__cached__} no longer set.

@end deffn

@geindex PyImport_ExecCodeModuleWithPathnames (C function)
@anchor{c-api/import c PyImport_ExecCodeModuleWithPathnames}@anchor{535e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_ExecCodeModuleWithPathnames (const char *name, PyObject *co, const char *pathname, const char *cpathname)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Like @ref{535d,,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}.


Added in version 3.2.



Άλλαξε στην έκδοση 3.3: Uses @code{imp.source_from_cache()} in calculating the source path if
only the bytecode path is provided.



Άλλαξε στην έκδοση 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{154c}
@deffn {C Συνάρτηση} long PyImport_GetMagicNumber ()
` Μέρος του @ref{95c,,Σταθερό 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.


Άλλαξε στην έκδοση 3.3: Return value of @code{-1} upon failure.

@end deffn

@geindex PyImport_GetMagicTag (C function)
@anchor{c-api/import c PyImport_GetMagicTag}@anchor{535f}
@deffn {C Συνάρτηση} const char *PyImport_GetMagicTag ()
` Μέρος του @ref{95c,,Σταθερό 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.


Added in version 3.2.

@end deffn

@geindex PyImport_GetModuleDict (C function)
@anchor{c-api/import c PyImport_GetModuleDict}@anchor{5360}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_GetModuleDict ()
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό 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{f71}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_GetModule (PyObject *name)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.


Added in version 3.7.

@end deffn

@geindex PyImport_GetImporter (C function)
@anchor{c-api/import c PyImport_GetImporter}@anchor{1c8a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_GetImporter (PyObject *path)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a finder object for a @ref{194,,sys.path}/@code{pkg.__path__} item
`path', possibly by fetching it from the @ref{9db,,sys.path_importer_cache}
dict.  If it wasn’t yet cached, traverse @ref{13cd,,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{2643,,path based finder} could not find a
finder for this path item. Cache the result in @code{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{5362}
@deffn {C Συνάρτηση} int PyImport_ImportFrozenModuleObject (PyObject *name)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{3a3,,PyImport_ImportModule()}.  (Note the misnomer — this function would
reload the module if it was already imported.)


Added in version 3.3.



Άλλαξε στην έκδοση 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{5361}
@deffn {C Συνάρτηση} int PyImport_ImportFrozenModule (const char *name)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{5362,,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{b57}
@deffn {C Struct} 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


Άλλαξε στην έκδοση 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{3572}
@deffn {C Μεταβλητή} const struct @ref{b57,,_frozen} *PyImport_FrozenModules

This pointer is initialized to point to an array of @ref{b57,,_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{1d1a}
@deffn {C Συνάρτηση} int PyImport_AppendInittab (const char *name, PyObject *(*initfunc)(void))
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Add a single module to the existing table of built-in modules.  This is a
convenience wrapper around @ref{1d1b,,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{673,,Py_Initialize()}.
@end deffn

@geindex _inittab (C struct)
@anchor{c-api/import c _inittab}@anchor{5587}
@deffn {C Struct} 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{1d1b,,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{5588}
@deffn {C Μέλος} 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{5589}
@deffn {C Μέλος} @ref{19b,,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{1d1b}
@deffn {C Συνάρτηση} 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{5588,,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{673,,Py_Initialize()}.

If Python is initialized multiple times, @ref{1d1a,,PyImport_AppendInittab()} or
@ref{1d1b,,PyImport_ExtendInittab()} must be called before each Python
initialization.
@end deffn

@geindex PyImport_Inittab (C var)
@anchor{c-api/import c PyImport_Inittab}@anchor{1d19}
@deffn {C Μεταβλητή} struct @ref{5587,,_inittab} *PyImport_Inittab

The table of built-in modules used by Python initialization. Do not use this directly;
use @ref{1d1a,,PyImport_AppendInittab()} and @ref{1d1b,,PyImport_ExtendInittab()}
instead.
@end deffn

@geindex PyImport_ImportModuleAttr (C function)
@anchor{c-api/import c PyImport_ImportModuleAttr}@anchor{5c3}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_ImportModuleAttr (PyObject *mod_name, PyObject *attr_name)
`Επιστρεφόμενη τιμή: New reference.'
Import the module `mod_name' and get its attribute `attr_name'.

Names must be Python @ref{1df,,str} objects.

Helper function combining @ref{179e,,PyImport_Import()} and
@ref{3b7,,PyObject_GetAttr()}. For example, it can raise @ref{1bd,,ImportError} if
the module is not found, and @ref{1a9,,AttributeError} if the attribute doesn’t
exist.


Added in version 3.14.

@end deffn

@geindex PyImport_ImportModuleAttrString (C function)
@anchor{c-api/import c PyImport_ImportModuleAttrString}@anchor{5c4}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_ImportModuleAttrString (const char *mod_name, const char *attr_name)
`Επιστρεφόμενη τιμή: New reference.'
Similar to @ref{5c3,,PyImport_ImportModuleAttr()}, but names are UTF-8 encoded
strings instead of Python @ref{1df,,str} objects.


Added in version 3.14.

@end deffn

@geindex PyImport_GetLazyImportsMode (C function)
@anchor{c-api/import c PyImport_GetLazyImportsMode}@anchor{558a}
@deffn {C Συνάρτηση} @ref{558b,,PyImport_LazyImportsMode} PyImport_GetLazyImportsMode ()

Gets the current lazy imports mode.


Added in version 3.15.

@end deffn

@geindex PyImport_GetLazyImportsFilter (C function)
@anchor{c-api/import c PyImport_GetLazyImportsFilter}@anchor{558c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_GetLazyImportsFilter ()

Return a @ref{7da,,strong reference} to the current lazy imports filter,
or @code{NULL} if none exists. This function always succeeds.


Added in version 3.15.

@end deffn

@geindex PyImport_SetLazyImportsMode (C function)
@anchor{c-api/import c PyImport_SetLazyImportsMode}@anchor{558d}
@deffn {C Συνάρτηση} int PyImport_SetLazyImportsMode (PyImport_LazyImportsMode mode)

Similar to @ref{5c3,,PyImport_ImportModuleAttr()}, but names are UTF-8 encoded
strings instead of Python @ref{1df,,str} objects.

This function always returns @code{0}.


Added in version 3.15.

@end deffn

@geindex PyImport_SetLazyImportsFilter (C function)
@anchor{c-api/import c PyImport_SetLazyImportsFilter}@anchor{558e}
@deffn {C Συνάρτηση} int PyImport_SetLazyImportsFilter (PyObject *filter)

Sets the current lazy imports filter. The `filter' should be a callable that
will receive @code{(importing_module_name, imported_module_name, [fromlist])}
when an import can potentially be lazy. The @code{imported_module_name} value
is the resolved module name, so @code{lazy from .spam import eggs} passes
@code{package.spam}. The callable must return @code{True} if the import should be
lazy and @code{False} otherwise.

Return @code{0} on success and @code{-1} with an exception set otherwise.


Added in version 3.15.

@end deffn

@geindex PyImport_LazyImportsMode (C type)
@anchor{c-api/import c PyImport_LazyImportsMode}@anchor{558b}
@deffn {C Τύπος} type PyImport_LazyImportsMode

Enumeration of possible lazy import modes.

@geindex PyImport_LazyImportsMode.PyImport_LAZY_NORMAL (C enumerator)
@anchor{c-api/import c PyImport_LazyImportsMode PyImport_LAZY_NORMAL}@anchor{558f}
@deffn {C Enumerator} enumerator PyImport_LAZY_NORMAL

Respect the @code{lazy} keyword in source code. This is the default mode.
@end deffn

@geindex PyImport_LazyImportsMode.PyImport_LAZY_ALL (C enumerator)
@anchor{c-api/import c PyImport_LazyImportsMode PyImport_LAZY_ALL}@anchor{5590}
@deffn {C Enumerator} enumerator PyImport_LAZY_ALL

Make all imports lazy by default.
@end deffn

@geindex PyImport_LazyImportsMode.PyImport_LAZY_NONE (C enumerator)
@anchor{c-api/import c PyImport_LazyImportsMode PyImport_LAZY_NONE}@anchor{5591}
@deffn {C Enumerator} enumerator PyImport_LAZY_NONE

Disable lazy imports entirely. Even explicit @code{lazy} statements become
eager imports.
@end deffn


Added in version 3.15.

@end deffn

@geindex PyImport_CreateModuleFromInitfunc (C function)
@anchor{c-api/import c PyImport_CreateModuleFromInitfunc}@anchor{369}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyImport_CreateModuleFromInitfunc (PyObject *spec, PyObject *(*initfunc)(void))

This function is a building block that enables embedders to implement
the @ref{106f,,create_module()} step of custom
static extension importers (e.g. of statically-linked extensions).

`spec' must be a @ref{245d,,ModuleSpec} object.

`initfunc' must be an @ref{38d,,initialization function},
the same as for @ref{1d1a,,PyImport_AppendInittab()}.

On success, create and return a module object.
This module will not be initialized; call @ref{5391,,PyModule_Exec()}
to initialize it.
(Custom importers should do this in their
@ref{c40,,exec_module()} method.)

On error, return NULL with an exception set.


Added in version 3.15.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Data marshalling support,Parsing arguments and building values,Importing Modules<2>,Utilities<2>
@anchor{c-api/marshal doc}@anchor{5592}@anchor{c-api/marshal data-marshalling-support}@anchor{5593}@anchor{c-api/marshal marshalling-utils}@anchor{5594}@anchor{c-api/marshal translation-repo}@anchor{5595}
@subsection Data marshalling support


These routines allow C code to work with serialized objects using the same
data format as the @ref{90,,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 several versions of the data format; see
the @ref{90,,Python module documentation} for details.

@geindex Py_MARSHAL_VERSION (C macro)
@anchor{c-api/marshal c Py_MARSHAL_VERSION}@anchor{5596}
@deffn {C Μακροεντολή} Py_MARSHAL_VERSION

The current format version. See @ref{2f69,,marshal.version}.
@end deffn

@geindex PyMarshal_WriteLongToFile (C function)
@anchor{c-api/marshal c PyMarshal_WriteLongToFile}@anchor{b75}
@deffn {C Συνάρτηση} 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{1ea5,,PyErr_Occurred()} to check for that.
@end deffn

@geindex PyMarshal_WriteObjectToFile (C function)
@anchor{c-api/marshal c PyMarshal_WriteObjectToFile}@anchor{b76}
@deffn {C Συνάρτηση} 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{1ea5,,PyErr_Occurred()} to check for that.
@end deffn

@geindex PyMarshal_WriteObjectToString (C function)
@anchor{c-api/marshal c PyMarshal_WriteObjectToString}@anchor{b78}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMarshal_WriteObjectToString (PyObject *value, int version)
`Επιστρεφόμενη τιμή: New reference.'
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{5597}
@deffn {C Συνάρτηση} 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{167e,,EOFError}) and returns
@code{-1}.
@end deffn

@geindex PyMarshal_ReadShortFromFile (C function)
@anchor{c-api/marshal c PyMarshal_ReadShortFromFile}@anchor{5598}
@deffn {C Συνάρτηση} 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{167e,,EOFError}) and returns
@code{-1}.
@end deffn

@geindex PyMarshal_ReadObjectFromFile (C function)
@anchor{c-api/marshal c PyMarshal_ReadObjectFromFile}@anchor{5599}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMarshal_ReadObjectFromFile (FILE *file)
`Επιστρεφόμενη τιμή: New reference.'
Return a Python object from the data stream in a FILE* opened for
reading.

On error, sets the appropriate exception (@ref{167e,,EOFError}, @ref{277,,ValueError}
or @ref{291,,TypeError}) and returns @code{NULL}.
@end deffn

@geindex PyMarshal_ReadLastObjectFromFile (C function)
@anchor{c-api/marshal c PyMarshal_ReadLastObjectFromFile}@anchor{559a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMarshal_ReadLastObjectFromFile (FILE *file)
`Επιστρεφόμενη τιμή: New reference.'
Return a Python object from the data stream in a FILE* opened for
reading.  Unlike @ref{5599,,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 this variant if you are certain that you won’t be reading
anything else from the file.

On error, sets the appropriate exception (@ref{167e,,EOFError}, @ref{277,,ValueError}
or @ref{291,,TypeError}) and returns @code{NULL}.
@end deffn

@geindex PyMarshal_ReadObjectFromString (C function)
@anchor{c-api/marshal c PyMarshal_ReadObjectFromString}@anchor{b77}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMarshal_ReadObjectFromString (const char *data, Py_ssize_t len)
`Επιστρεφόμενη τιμή: New reference.'
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{167e,,EOFError}, @ref{277,,ValueError}
or @ref{291,,TypeError}) and returns @code{NULL}.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Parsing arguments and building values,String conversion and formatting,Data marshalling support,Utilities<2>
@anchor{c-api/arg doc}@anchor{559b}@anchor{c-api/arg arg-parsing}@anchor{601}@anchor{c-api/arg parsing-arguments-and-building-values}@anchor{559c}@anchor{c-api/arg translation-repo}@anchor{559d}
@subsection Parsing arguments and building values


These functions are useful when creating your own extension functions and
methods.  Additional information and examples are available in
@ref{21aa,,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python}.

The first three of these functions described, @ref{3b1,,PyArg_ParseTuple()},
@ref{818,,PyArg_ParseTupleAndKeywords()}, and @ref{1a6b,,PyArg_Parse()}, all use `format
strings' which are used to tell the function about the expected arguments.  The
format strings use the same syntax for each of these functions.

@menu
* Parsing arguments: Parsing arguments<2>. 
* Building values:: 

@end menu

@node Parsing arguments<2>,Building values,,Parsing arguments and building values
@anchor{c-api/arg parsing-arguments}@anchor{559e}
@subsubsection Parsing arguments


A format string consists of zero or more «format units.»  A format unit
describes one Python object; it is usually a single character or a parenthesized
sequence of format units.  With a few exceptions, a format unit that is not a
parenthesized sequence normally corresponds to a single address argument to
these functions.  In the following description, the quoted form is the format
unit; the entry in (round) parentheses is the Python object type that matches
the format unit; and the entry in [square] brackets is the type of the C
variable(s) whose address should be passed.

@menu
* Strings and buffers:: 
* Numbers:: 
* Other objects:: 
* API Functions:: 

@end menu

@node Strings and buffers,Numbers,,Parsing arguments<2>
@anchor{c-api/arg arg-parsing-string-and-buffers}@anchor{81f}@anchor{c-api/arg strings-and-buffers}@anchor{559f}
@subsubsection Strings and buffers


@cartouche
@quotation Σημείωση 
On Python 3.12 and older, the macro @code{PY_SSIZE_T_CLEAN} must be
defined before including @code{Python.h} to use all @code{#} variants of
formats (@code{s#}, @code{y#}, etc.) explained below.
This is not necessary on Python 3.13 and later.
@end quotation
@end cartouche

These formats allow accessing an object as a contiguous chunk of memory.
You don’t have to provide raw storage for the returned unicode or bytes
area.

Unless otherwise stated, buffers are not NUL-terminated.

There are three ways strings and buffers can be converted to C:


@itemize *

@item 
Formats such as @code{y*} and @code{s*} fill a @ref{b3a,,Py_buffer} structure.
This locks the underlying buffer so that the caller can subsequently use
the buffer even inside a @ref{51d4,,Py_BEGIN_ALLOW_THREADS}
block without the risk of mutable data being resized or destroyed.
As a result, `you have to call' @ref{82d,,PyBuffer_Release()} after you have
finished processing the data (or in any early abort case).

@item 
The @code{es}, @code{es#}, @code{et} and @code{et#} formats allocate the result buffer.
`You have to call' @ref{17e4,,PyMem_Free()} after you have finished
processing the data (or in any early abort case).

@item @anchor{c-api/arg c-arg-borrowed-buffer}@anchor{602}
Other formats take a @ref{1df,,str} or a read-only @ref{436,,bytes-like object},
such as @ref{1c7,,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{b45,,PyBufferProcs.bf_releasebuffer} field must be @code{NULL}.
This disallows common mutable objects such as @ref{1c6,,bytearray},
but also some read-only objects such as @ref{1d2,,memoryview} of
@ref{1c7,,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{1df,,str}) [const char *]

Convert a Unicode object to a C pointer to a character string.
A pointer to an existing string is stored in the character pointer
variable whose address you pass.  The C string is NUL-terminated.
The Python string must not contain embedded null code points; if it does,
a @ref{277,,ValueError} exception is raised. Unicode objects are converted
to C strings using @code{'utf-8'} encoding. If this conversion fails, a
@ref{675,,UnicodeError} is raised.

@cartouche
@quotation Σημείωση 
This format does not accept @ref{436,,bytes-like objects}.  If you want to accept
filesystem paths and convert them to C character strings, it is
preferable to use the @code{O&} format with @ref{10d3,,PyUnicode_FSConverter()}
as `converter'.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.5: Previously, @ref{291,,TypeError} was raised when embedded null code points
were encountered in the Python string.


@item @code{s*} (@ref{1df,,str} or @ref{436,,bytes-like object}) [Py_buffer]

This format accepts Unicode objects as well as bytes-like objects.
It fills a @ref{b3a,,Py_buffer} structure provided by the caller.
In this case the resulting C string may contain embedded NUL bytes.
Unicode objects are converted to C strings using @code{'utf-8'} encoding.

@item @code{s#} (@ref{1df,,str}, read-only @ref{436,,bytes-like object}) [const char *, @ref{e24,,Py_ssize_t}]

Like @code{s*}, except that it provides a @ref{602,,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{1df,,str} or @code{None}) [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{1df,,str}, @ref{436,,bytes-like object} or @code{None}) [Py_buffer]

Like @code{s*}, but the Python object may also be @code{None}, in which case the
@code{buf} member of the @ref{b3a,,Py_buffer} structure is set to @code{NULL}.

@item @code{z#} (@ref{1df,,str}, read-only @ref{436,,bytes-like object} or @code{None}) [const char *, @ref{e24,,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} (read-only @ref{436,,bytes-like object}) [const char *]

This format converts a bytes-like object to a C pointer to a
@ref{602,,borrowed} character string;
it does not accept Unicode objects.  The bytes buffer must not
contain embedded null bytes; if it does, a @ref{277,,ValueError}
exception is raised.


Άλλαξε στην έκδοση 3.5: Previously, @ref{291,,TypeError} was raised when embedded null bytes were
encountered in the bytes buffer.


@item @code{y*} (@ref{436,,bytes-like object}) [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{436,,bytes-like object}) [const char *, @ref{e24,,Py_ssize_t}]

This variant on @code{s#} doesn’t accept Unicode objects, only bytes-like
objects.

@item @code{S} (@ref{1c7,,bytes}) [PyBytesObject *]

Requires that the Python object is a @ref{1c7,,bytes} object, without
attempting any conversion.  Raises @ref{291,,TypeError} if the object is not
a bytes object.  The C variable may also be declared as @ref{19b,,PyObject}*.

@item @code{Y} (@ref{1c6,,bytearray}) [PyByteArrayObject *]

Requires that the Python object is a @ref{1c6,,bytearray} object, without
attempting any conversion.  Raises @ref{291,,TypeError} if the object is not
a @code{bytearray} object. The C variable may also be declared as @ref{19b,,PyObject}*.

@item @code{U} (@ref{1df,,str}) [PyObject *]

Requires that the Python object is a Unicode object, without attempting
any conversion.  Raises @ref{291,,TypeError} if the object is not a Unicode
object.  The C variable may also be declared as @ref{19b,,PyObject}*.

@item @code{w*} (read-write @ref{436,,bytes-like object}) [Py_buffer]

This format accepts any object which implements the read-write buffer
interface. It fills a @ref{b3a,,Py_buffer} structure provided by the caller.
The buffer may contain embedded null bytes. The caller has to call
@ref{82d,,PyBuffer_Release()} when it is done with the buffer.

@item @code{es} (@ref{1df,,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{3b1,,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{17e4,,PyMem_Free()} to
free the allocated buffer after use.

@item @code{et} (@ref{1df,,str}, @ref{1c7,,bytes} or @ref{1c6,,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{1df,,str}) [const char *encoding, char **buffer, @ref{e24,,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.

There are two modes of operation:

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{17e4,,PyMem_Free()} to free the allocated buffer after usage.

If `*buffer' points to a non-@code{NULL} pointer (an already allocated buffer),
@ref{3b1,,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{277,,ValueError} will be set.

In both cases, `*buffer_length' is set to the length of the encoded data
without the trailing NUL byte.

@item @code{et#} (@ref{1df,,str}, @ref{1c7,,bytes} or @ref{1c6,,bytearray}) [const char *encoding, char **buffer, @ref{e24,,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


Άλλαξε στην έκδοση 3.12: @code{u}, @code{u#}, @code{Z}, and @code{Z#} are removed because they used a legacy
@code{Py_UNICODE*} representation.


@node Numbers,Other objects,Strings and buffers,Parsing arguments<2>
@anchor{c-api/arg numbers}@anchor{55a0}
@subsubsection Numbers


These formats allow representing Python numbers or single characters as C numbers.
Formats that require @ref{326,,int}, @ref{327,,float} or @ref{328,,complex} can
also use the corresponding special methods @ref{43d,,__index__()},
@ref{d92,,__float__()} or @ref{9de,,__complex__()} to convert
the Python object to the required type.

For signed integer formats, @ref{c57,,OverflowError} is raised if the value
is out of range for the C type.
For unsigned integer formats, the
most significant bits are silently truncated when the receiving field is too
small to receive the value, and @ref{2c9,,DeprecationWarning} is emitted when
the value is larger than the maximal value for the C type or less than
the minimal value for the corresponding signed integer type of the same size.


@table @asis

@item @code{b} (@ref{326,,int}) [unsigned char]

Convert a nonnegative Python integer to an unsigned tiny integer, stored in a C
unsigned char.

@item @code{B} (@ref{326,,int}) [unsigned char]

Convert a Python integer to a tiny integer without overflow checking, stored in a C
unsigned char.
Convert a Python integer to a C unsigned char.

@item @code{h} (@ref{326,,int}) [short int]

Convert a Python integer to a C short int.

@item @code{H} (@ref{326,,int}) [unsigned short int]

Convert a Python integer to a C unsigned short int.

@item @code{i} (@ref{326,,int}) [int]

Convert a Python integer to a plain C int.

@item @code{I} (@ref{326,,int}) [unsigned int]

Convert a Python integer to a C unsigned int.

@item @code{l} (@ref{326,,int}) [long int]

Convert a Python integer to a C long int.

@item @code{k} (@ref{326,,int}) [unsigned long]

Convert a Python integer to a C unsigned long.


Άλλαξε στην έκδοση 3.14: Use @ref{43d,,__index__()} if available.


@item @code{L} (@ref{326,,int}) [long long]

Convert a Python integer to a C long long.

@item @code{K} (@ref{326,,int}) [unsigned long long]

Convert a Python integer to a C unsigned long long.


Άλλαξε στην έκδοση 3.14: Use @ref{43d,,__index__()} if available.


@item @code{n} (@ref{326,,int}) [@ref{e24,,Py_ssize_t}]

Convert a Python integer to a C @ref{e24,,Py_ssize_t}.

@item @code{c} (@ref{1c7,,bytes} or @ref{1c6,,bytearray} of length 1) [char]

Convert a Python byte, represented as a @ref{1c7,,bytes} or
@ref{1c6,,bytearray} object of length 1, to a C char.


Άλλαξε στην έκδοση 3.3: Allow @ref{1c6,,bytearray} objects.


@item @code{C} (@ref{1df,,str} of length 1) [int]

Convert a Python character, represented as a @ref{1df,,str} object of
length 1, to a C int.

@item @code{f} (@ref{327,,float}) [float]

Convert a Python floating-point number to a C float.

@item @code{d} (@ref{327,,float}) [double]

Convert a Python floating-point number to a C double.

@item @code{D} (@ref{328,,complex}) [Py_complex]

Convert a Python complex number to a C @ref{3bc,,Py_complex} structure.
@end table


Αποσύρθηκε στην έκδοση 3.15: For unsigned integer formats @code{B}, @code{H}, @code{I}, @code{k} and @code{K},
@ref{2c9,,DeprecationWarning} is emitted when the value is larger than
the maximal value for the C type or less than the minimal value for
the corresponding signed integer type of the same size.


@node Other objects,API Functions,Numbers,Parsing arguments<2>
@anchor{c-api/arg other-objects}@anchor{55a1}
@subsubsection Other objects



@table @asis

@item @code{O} (object) [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{7da,,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!} (object) [`typeobject', 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{19b,,PyObject}*) into which
the object pointer is stored.  If the Python object does not have the required
type, @ref{291,,TypeError} is raised.
@end table
@anchor{c-api/arg o-ampersand}@anchor{55a2}

@table @asis

@item @code{O&} (object) [`converter', `address']

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.

@geindex Py_CLEANUP_SUPPORTED (C macro)
@anchor{c-api/arg c Py_CLEANUP_SUPPORTED}@anchor{55a3}
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.

Examples of converters: @ref{10d3,,PyUnicode_FSConverter()} and
@ref{97b,,PyUnicode_FSDecoder()}.


Άλλαξε στην έκδοση 3.1: @code{Py_CLEANUP_SUPPORTED} was added.


@item @code{p} (@ref{5ef,,bool}) [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{1a80,,Έλεγχος Έγκυρης Τιμής} for more
information about how Python tests values for truth.


Added in version 3.3.


@item @code{(items)} (sequence) [`matching-items']

The object must be a Python sequence (except @ref{1df,,str}, @ref{1c7,,bytes}
or @ref{1c6,,bytearray}) whose length is the number of format units
in `items'.  The C arguments must correspond to the individual format units in
`items'.  Format units for sequences may be nested.

If `items' contains format units which store a @ref{602,,borrowed buffer} (@code{s}, @code{s#}, @code{z}, @code{z#}, @code{y}, or @code{y#})
or a @ref{603,,borrowed reference} (@code{S}, @code{Y}, @code{U}, @code{O}, or @code{O!}),
the object must be a Python tuple.
The `converter' for the @code{O&} format unit in `items' must not store
a borrowed buffer or a borrowed reference.


Άλλαξε στην έκδοση 3.14: @ref{1df,,str} and @ref{1c6,,bytearray} objects no longer accepted as a sequence.



Αποσύρθηκε στην έκδοση 3.14: Non-tuple sequences are deprecated if `items' contains format units
which store a borrowed buffer or a borrowed reference.

@end table

A few other characters have a meaning in a format string.  These may not occur
inside nested parentheses.  They are:


@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{3b1,,PyArg_ParseTuple()} does not touch the contents of the corresponding C
variable(s).

@item @code{$}

@ref{818,,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.


Added in 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{3b1,,PyArg_ParseTuple()} raises).

@item @code{;}

The list of format units ends here; the string after the semicolon is used as
the error message `instead' of the default error message.  @code{:} and @code{;}
mutually exclude each other.
@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)!

Additional arguments passed to these functions must be addresses of variables
whose type is determined by the format string; these are used to store values
from the input tuple.  There are a few cases, as described in the list of format
units above, where these parameters are used as input values; they should match
what is specified for the corresponding format unit in that case.

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 API Functions,,Other objects,Parsing arguments<2>
@anchor{c-api/arg api-functions}@anchor{55a4}
@subsubsection API Functions


@geindex PyArg_ParseTuple (C function)
@anchor{c-api/arg c PyArg_ParseTuple}@anchor{3b1}
@deffn {C Συνάρτηση} int PyArg_ParseTuple (PyObject *args, const char *format, ...)
` Μέρος του @ref{95c,,Σταθερό 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{5289}
@deffn {C Συνάρτηση} int PyArg_VaParse (PyObject *args, const char *format, va_list vargs)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Identical to @ref{3b1,,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{818}
@deffn {C Συνάρτηση} int PyArg_ParseTupleAndKeywords (PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)
` Μέρος του @ref{95c,,Σταθερό 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{e47,,positional-only parameters}.
Returns true on success; on failure, it returns false and raises the
appropriate exception.

@cartouche
@quotation Σημείωση 
The `keywords' parameter declaration is char *const* in C and
const char *const* in C++.
This can be overridden with the @ref{81a,,PY_CXX_CONST} macro.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.6: Added support for @ref{e47,,positional-only parameters}.



Άλλαξε στην έκδοση 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{819}
@deffn {C Συνάρτηση} int PyArg_VaParseTupleAndKeywords (PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Identical to @ref{818,,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{528a}
@deffn {C Συνάρτηση} int PyArg_ValidateKeywordArguments (PyObject*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Ensure that the keys in the keywords argument dictionary are strings.  This
is only needed if @ref{818,,PyArg_ParseTupleAndKeywords()} is not used, since the
latter already does this check.


Added in version 3.2.

@end deffn

@geindex PyArg_Parse (C function)
@anchor{c-api/arg c PyArg_Parse}@anchor{1a6b}
@deffn {C Συνάρτηση} int PyArg_Parse (PyObject *args, const char *format, ...)
` Μέρος του @ref{95c,,Σταθερό 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.

Example:

@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_ParseArray (C function)
@anchor{c-api/arg c PyArg_ParseArray}@anchor{349}
@deffn {C Συνάρτηση} int PyArg_ParseArray (PyObject *const *args, Py_ssize_t nargs, const char *format, ...)

Parse the parameters of a function that takes only array parameters into
local variables (that is, a function using the @ref{34b,,METH_FASTCALL}
calling convention).
Returns true on success; on failure, it returns false and raises the
appropriate exception.


Added in version 3.15.

@end deffn

@geindex PyArg_ParseArrayAndKeywords (C function)
@anchor{c-api/arg c PyArg_ParseArrayAndKeywords}@anchor{34a}
@deffn {C Συνάρτηση} int PyArg_ParseArrayAndKeywords (PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames, const char *format, const char *const *kwlist, ...)

Parse the parameters of a function that takes both array and keyword
parameters into local variables (that is, a function using the
@ref{34b,,METH_FASTCALL} @code{|} @ref{51c6,,METH_KEYWORDS} calling convention).
Returns true on success; on failure, it returns false and raises the
appropriate exception.


Added in version 3.15.

@end deffn

@geindex PyArg_UnpackTuple (C function)
@anchor{c-api/arg c PyArg_UnpackTuple}@anchor{18a8}
@deffn {C Συνάρτηση} int PyArg_UnpackTuple (PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
` Μέρος του @ref{95c,,Σταθερό 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{18aa,,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{19b,,PyObject}* variable; these will be filled in with the values from
`args'; they will contain @ref{603,,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{18a8,,PyArg_UnpackTuple()} in this example is entirely equivalent to
this call to @ref{3b1,,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{81a}
@deffn {C Μακροεντολή} PY_CXX_CONST

The value to be inserted, if any, before char *const*
in the `keywords' parameter declaration of
@ref{818,,PyArg_ParseTupleAndKeywords()} and
@ref{819,,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}.


Added in version 3.13.

@end deffn

@node Building values,,Parsing arguments<2>,Parsing arguments and building values
@anchor{c-api/arg building-values}@anchor{55a5}
@subsubsection Building values


@geindex Py_BuildValue (C function)
@anchor{c-api/arg c Py_BuildValue}@anchor{5ee}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *Py_BuildValue (const char *format, ...)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{5ee,,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{5ee,,Py_BuildValue()}.  In other words, if your code invokes @code{malloc()}
and passes the allocated memory to @code{Py_BuildValue()}, your code is
responsible for calling @code{free()} for that memory once
@code{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{1df,,str} or @code{None}) [const char *]

Convert a null-terminated C string to a Python @ref{1df,,str} object using @code{'utf-8'}
encoding. If the C string pointer is @code{NULL}, @code{None} is used.

@item @code{s#} (@ref{1df,,str} or @code{None}) [const char *, @ref{e24,,Py_ssize_t}]

Convert a C string and its length to a Python @ref{1df,,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{1c7,,bytes}) [const char *]

This converts a C string to a Python @ref{1c7,,bytes} object.  If the C
string pointer is @code{NULL}, @code{None} is returned.

@item @code{y#} (@ref{1c7,,bytes}) [const char *, @ref{e24,,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{1df,,str} or @code{None}) [const char *]

Same as @code{s}.

@item @code{z#} (@ref{1df,,str} or @code{None}) [const char *, @ref{e24,,Py_ssize_t}]

Same as @code{s#}.

@item @code{u} (@ref{1df,,str}) [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{1df,,str}) [const wchar_t *, @ref{e24,,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{1df,,str} or @code{None}) [const char *]

Same as @code{s}.

@item @code{U#} (@ref{1df,,str} or @code{None}) [const char *, @ref{e24,,Py_ssize_t}]

Same as @code{s#}.

@item @code{i} (@ref{326,,int}) [int]

Convert a plain C int to a Python integer object.

@item @code{b} (@ref{326,,int}) [char]

Convert a plain C char to a Python integer object.

@item @code{h} (@ref{326,,int}) [short int]

Convert a plain C short int to a Python integer object.

@item @code{l} (@ref{326,,int}) [long int]

Convert a C long int to a Python integer object.

@item @code{B} (@ref{326,,int}) [unsigned char]

Convert a C unsigned char to a Python integer object.

@item @code{H} (@ref{326,,int}) [unsigned short int]

Convert a C unsigned short int to a Python integer object.

@item @code{I} (@ref{326,,int}) [unsigned int]

Convert a C unsigned int to a Python integer object.

@item @code{k} (@ref{326,,int}) [unsigned long]

Convert a C unsigned long to a Python integer object.

@item @code{L} (@ref{326,,int}) [long long]

Convert a C long long to a Python integer object.
@end table
@anchor{c-api/arg capi-py-buildvalue-format-k}@anchor{1a93}

@table @asis

@item @code{K} (@ref{326,,int}) [unsigned long long]

Convert a C unsigned long long to a Python integer object.

@item @code{n} (@ref{326,,int}) [@ref{e24,,Py_ssize_t}]

Convert a C @ref{e24,,Py_ssize_t} to a Python integer.

@item @code{p} (@ref{5ef,,bool}) [int]

Convert a C int to a Python @ref{5ef,,bool} object.

Be aware that this format requires an @code{int} argument.
Unlike most other contexts in C, variadic arguments are not coerced to
a suitable type automatically.
You can convert another type (for example, a pointer or a float) to a
suitable @code{int} value using @code{(x) ? 1 : 0} or @code{!!x}.


Added in version 3.14.


@item @code{c} (@ref{1c7,,bytes} of length 1) [char]

Convert a C int representing a byte to a Python @ref{1c7,,bytes} object of
length 1.

@item @code{C} (@ref{1df,,str} of length 1) [int]

Convert a C int representing a character to Python @ref{1df,,str}
object of length 1.

@item @code{d} (@ref{327,,float}) [double]

Convert a C double to a Python floating-point number.

@item @code{f} (@ref{327,,float}) [float]

Convert a C float to a Python floating-point number.

@item @code{D} (@ref{328,,complex}) [Py_complex *]

Convert a C @ref{3bc,,Py_complex} structure to a Python complex number.

@item @code{O} (object) [PyObject *]

Pass a Python object untouched but create a new
@ref{7da,,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{5ee,,Py_BuildValue()} will return @code{NULL} but won’t
raise an exception.  If no exception has been raised yet, @ref{3ea,,SystemError} is
set.

@item @code{S} (object) [PyObject *]

Same as @code{O}.

@item @code{N} (object) [PyObject *]

Same as @code{O}, except it doesn’t create a new @ref{7da,,strong reference}.
Useful when the object is created by a call to an object constructor in the
argument list.

@item @code{O&} (object) [`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{1ce,,tuple}) [`matching-items']

Convert a sequence of C values to a Python tuple with the same number of items.

@item @code{[items]} (@ref{4d9,,list}) [`matching-items']

Convert a sequence of C values to a Python list with the same number of items.

@item @code{@{items@}} (@ref{188,,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{3ea,,SystemError} exception is
set and @code{NULL} returned.
@end deffn

@geindex Py_VaBuildValue (C function)
@anchor{c-api/arg c Py_VaBuildValue}@anchor{548e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *Py_VaBuildValue (const char *format, va_list vargs)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Identical to @ref{5ee,,Py_BuildValue()}, except that it accepts a va_list
rather than a variable number of arguments.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node String conversion and formatting,Character classification and conversion,Parsing arguments and building values,Utilities<2>
@anchor{c-api/conversion doc}@anchor{55a6}@anchor{c-api/conversion string-conversion}@anchor{55a7}@anchor{c-api/conversion string-conversion-and-formatting}@anchor{55a8}@anchor{c-api/conversion translation-repo}@anchor{55a9}
@subsection String conversion and formatting


Functions for number conversion and formatted string output.

@geindex PyOS_snprintf (C function)
@anchor{c-api/conversion c PyOS_snprintf}@anchor{18ab}
@deffn {C Συνάρτηση} int PyOS_snprintf (char *str, size_t size, const char *format, ...)
` Μέρος του @ref{95c,,Σταθερό 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{18ac}
@deffn {C Συνάρτηση} int PyOS_vsnprintf (char *str, size_t size, const char *format, va_list va)
` Μέρος του @ref{95c,,Σταθερό 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{18ab,,PyOS_snprintf()} and @ref{18ac,,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}, the output conversion failed and @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{53bd}
@deffn {C Συνάρτηση} unsigned long PyOS_strtoul (const char *str, char **ptr, int base)
` Μέρος του @ref{95c,,Σταθερό 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)}}.


Added in version 3.2.

@end deffn

@geindex PyOS_strtol (C function)
@anchor{c-api/conversion c PyOS_strtol}@anchor{53bc}
@deffn {C Συνάρτηση} long PyOS_strtol (const char *str, char **ptr, int base)
` Μέρος του @ref{95c,,Σταθερό 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{53bd,,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)}}.


Added in version 3.2.

@end deffn

@geindex PyOS_string_to_double (C function)
@anchor{c-api/conversion c PyOS_string_to_double}@anchor{163a}
@deffn {C Συνάρτηση} double PyOS_string_to_double (const char *s, char **endptr, PyObject *overflow_exception)
` Μέρος του @ref{95c,,Σταθερό 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{327,,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{277,,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{INFINITY} (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}.


Added in version 3.1.

@end deffn

@geindex PyOS_double_to_string (C function)
@anchor{c-api/conversion c PyOS_double_to_string}@anchor{53ba}
@deffn {C Συνάρτηση} char *PyOS_double_to_string (double val, char format_code, int precision, int flags, int *ptype)
` Μέρος του @ref{95c,,Σταθερό 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{45b,,repr()} format.

`flags' can be zero or more of the following values or-ed together:

@geindex Py_DTSF_SIGN (C macro)
@anchor{c-api/conversion c Py_DTSF_SIGN}@anchor{55aa}
@deffn {C Μακροεντολή} Py_DTSF_SIGN

Always precede the returned string with a sign
character, even if `val' is non-negative.
@end deffn

@geindex Py_DTSF_ADD_DOT_0 (C macro)
@anchor{c-api/conversion c Py_DTSF_ADD_DOT_0}@anchor{55ab}
@deffn {C Μακροεντολή} Py_DTSF_ADD_DOT_0

Ensure that the returned string will not look like an integer.
@end deffn

@geindex Py_DTSF_ALT (C macro)
@anchor{c-api/conversion c Py_DTSF_ALT}@anchor{55ac}
@deffn {C Μακροεντολή} Py_DTSF_ALT

Apply «alternate» formatting rules.
See the documentation for the @ref{18ab,,PyOS_snprintf()} @code{'#'} specifier for
details.
@end deffn

@geindex Py_DTSF_NO_NEG_0 (C macro)
@anchor{c-api/conversion c Py_DTSF_NO_NEG_0}@anchor{55ad}
@deffn {C Μακροεντολή} Py_DTSF_NO_NEG_0

Negative zero is converted to positive zero.


Added in version 3.11.

@end deffn

If `ptype' is non-@code{NULL}, then the value it points to will be set to one
of the following constants depending on the type of `val':


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

`*ptype'

@tab

type of `val'

@item

@geindex Py_DTST_FINITE (C macro)
@anchor{c-api/conversion c Py_DTST_FINITE}@anchor{55ae}
@deffn {C Μακροεντολή} Py_DTST_FINITE
@end deffn

@tab

finite number

@item

@geindex Py_DTST_INFINITE (C macro)
@anchor{c-api/conversion c Py_DTST_INFINITE}@anchor{55af}
@deffn {C Μακροεντολή} Py_DTST_INFINITE
@end deffn

@tab

infinite number

@item

@geindex Py_DTST_NAN (C macro)
@anchor{c-api/conversion c Py_DTST_NAN}@anchor{55b0}
@deffn {C Μακροεντολή} Py_DTST_NAN
@end deffn

@tab

not a number

@end multitable


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{17e4,,PyMem_Free()}.


Added in version 3.1.

@end deffn

@geindex PyOS_mystricmp (C function)
@geindex PyOS_mystrnicmp (C function)
@anchor{c-api/conversion c PyOS_mystricmp}@anchor{1f2f}
@deffn {C Συνάρτηση} int PyOS_mystricmp (const char *str1, const char *str2)
@anchor{c-api/conversion c PyOS_mystrnicmp}@anchor{1f2e}
@deffnx {C Συνάρτηση} int PyOS_mystrnicmp (const char *str1, const char *str2, Py_ssize_t size)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Case insensitive comparison of strings. These functions work almost
identically to @code{strcmp()} and @code{strncmp()} (respectively),
except that they ignore the case of ASCII characters.

Return @code{0} if the strings are equal, a negative value if `str1' sorts
lexicographically before `str2', or a positive value if it sorts after.

In the `str1' or `str2' arguments, a NUL byte marks the end of the string.
For @code{PyOS_mystrnicmp()}, the `size' argument gives the maximum size
of the string, as if NUL was present at the index given by `size'.

These functions do not use the locale.
@end deffn

@geindex PyOS_stricmp (C function)
@geindex PyOS_strnicmp (C function)
@anchor{c-api/conversion c PyOS_stricmp}@anchor{55b1}
@deffn {C Συνάρτηση} int PyOS_stricmp (const char *str1, const char *str2)
@anchor{c-api/conversion c PyOS_strnicmp}@anchor{55b2}
@deffnx {C Συνάρτηση} int PyOS_strnicmp (const char *str1, const char *str2, Py_ssize_t size)

Case insensitive comparison of strings.

On Windows, these are aliases of @code{stricmp()} and @code{strnicmp()},
respectively.

On other platforms, they are aliases of @ref{1f2f,,PyOS_mystricmp()} and
@ref{1f2e,,PyOS_mystrnicmp()}, respectively.
@end deffn

@node Character classification and conversion,PyHash API,String conversion and formatting,Utilities<2>
@anchor{c-api/conversion character-classification-and-conversion}@anchor{55b3}
@subsection Character classification and conversion


The following macros provide locale-independent (unlike the C standard library
@code{ctype.h}) character classification and conversion.
The argument must be a signed or unsigned char.

@geindex Py_ISALNUM (C macro)
@anchor{c-api/conversion c Py_ISALNUM}@anchor{16f6}
@deffn {C Μακροεντολή} Py_ISALNUM (c)

Return true if the character `c' is an alphanumeric character.
@end deffn

@geindex Py_ISALPHA (C macro)
@anchor{c-api/conversion c Py_ISALPHA}@anchor{16f7}
@deffn {C Μακροεντολή} Py_ISALPHA (c)

Return true if the character `c' is an alphabetic character (@code{a-z} and @code{A-Z}).
@end deffn

@geindex Py_ISDIGIT (C macro)
@anchor{c-api/conversion c Py_ISDIGIT}@anchor{16f8}
@deffn {C Μακροεντολή} Py_ISDIGIT (c)

Return true if the character `c' is a decimal digit (@code{0-9}).
@end deffn

@geindex Py_ISLOWER (C macro)
@anchor{c-api/conversion c Py_ISLOWER}@anchor{16f9}
@deffn {C Μακροεντολή} Py_ISLOWER (c)

Return true if the character `c' is a lowercase ASCII letter (@code{a-z}).
@end deffn

@geindex Py_ISUPPER (C macro)
@anchor{c-api/conversion c Py_ISUPPER}@anchor{16fb}
@deffn {C Μακροεντολή} Py_ISUPPER (c)

Return true if the character `c' is an uppercase ASCII letter (@code{A-Z}).
@end deffn

@geindex Py_ISSPACE (C macro)
@anchor{c-api/conversion c Py_ISSPACE}@anchor{16fa}
@deffn {C Μακροεντολή} Py_ISSPACE (c)

Return true if the character `c' is a whitespace character (space, tab,
carriage return, newline, vertical tab, or form feed).
@end deffn

@geindex Py_ISXDIGIT (C macro)
@anchor{c-api/conversion c Py_ISXDIGIT}@anchor{16fc}
@deffn {C Μακροεντολή} Py_ISXDIGIT (c)

Return true if the character `c' is a hexadecimal digit (@code{0-9}, @code{a-f}, and
@code{A-F}).
@end deffn

@geindex Py_TOLOWER (C macro)
@anchor{c-api/conversion c Py_TOLOWER}@anchor{16fd}
@deffn {C Μακροεντολή} Py_TOLOWER (c)

Return the lowercase equivalent of the character `c'.
@end deffn

@geindex Py_TOUPPER (C macro)
@anchor{c-api/conversion c Py_TOUPPER}@anchor{16fe}
@deffn {C Μακροεντολή} Py_TOUPPER (c)

Return the uppercase equivalent of the character `c'.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node PyHash API,Reflection,Character classification and conversion,Utilities<2>
@anchor{c-api/hash doc}@anchor{55b4}@anchor{c-api/hash pyhash-api}@anchor{55b5}@anchor{c-api/hash translation-repo}@anchor{55b6}
@subsection PyHash API


See also the @ref{520b,,PyTypeObject.tp_hash} member and @ref{27f8,,Κατακερματισμός των αριθμητικών τύπων}.

@geindex Py_hash_t (C type)
@anchor{c-api/hash c Py_hash_t}@anchor{1608}
@deffn {C Τύπος} type Py_hash_t

Hash value type: signed integer.


Added in version 3.2.

@end deffn

@geindex Py_uhash_t (C type)
@anchor{c-api/hash c Py_uhash_t}@anchor{55b7}
@deffn {C Τύπος} type Py_uhash_t

Hash value type: unsigned integer.


Added in version 3.2.

@end deffn

@geindex Py_HASH_ALGORITHM (C macro)
@anchor{c-api/hash c Py_HASH_ALGORITHM}@anchor{3b0}
@deffn {C Μακροεντολή} Py_HASH_ALGORITHM

A numerical value indicating the algorithm for hashing of @ref{1df,,str},
@ref{1c7,,bytes}, and @ref{1d2,,memoryview}.

The algorithm name is exposed by @ref{4c00,,sys.hash_info.algorithm}.


Added in version 3.4.

@end deffn

@geindex Py_HASH_FNV (C macro)
@geindex Py_HASH_SIPHASH24 (C macro)
@geindex Py_HASH_SIPHASH13 (C macro)
@anchor{c-api/hash c Py_HASH_FNV}@anchor{55b8}
@deffn {C Μακροεντολή} Py_HASH_FNV
@anchor{c-api/hash c Py_HASH_SIPHASH24}@anchor{55b9}
@deffnx {C Μακροεντολή} Py_HASH_SIPHASH24
@anchor{c-api/hash c Py_HASH_SIPHASH13}@anchor{55ba}
@deffnx {C Μακροεντολή} Py_HASH_SIPHASH13

Numerical values to compare to @ref{3b0,,Py_HASH_ALGORITHM} to determine
which algorithm is used for hashing. The hash algorithm can be configured
via the configure @ref{23a2,,--with-hash-algorithm} option.


Added in version 3.4: Add @code{Py_HASH_FNV} and @code{Py_HASH_SIPHASH24}.



Added in version 3.11: Add @code{Py_HASH_SIPHASH13}.

@end deffn

@geindex Py_HASH_CUTOFF (C macro)
@anchor{c-api/hash c Py_HASH_CUTOFF}@anchor{55bb}
@deffn {C Μακροεντολή} Py_HASH_CUTOFF

Buffers of length in range @code{[1, Py_HASH_CUTOFF)} are hashed using DJBX33A
instead of the algorithm described by @ref{3b0,,Py_HASH_ALGORITHM}.


@itemize -

@item 
A @code{Py_HASH_CUTOFF} of 0 disables the optimization.

@item 
@code{Py_HASH_CUTOFF} must be non-negative and less or equal than 7.
@end itemize

32-bit platforms should use a cutoff smaller than 64-bit platforms because
it is easier to create colliding strings. A cutoff of 7 on 64-bit platforms
and 5 on 32-bit platforms should provide a decent safety margin.

This corresponds to the @ref{4c03,,sys.hash_info.cutoff} constant.


Added in version 3.4.

@end deffn

@geindex PyHASH_MODULUS (C macro)
@anchor{c-api/hash c PyHASH_MODULUS}@anchor{1bf1}
@deffn {C Μακροεντολή} PyHASH_MODULUS

The Mersenne prime@footnote{https://en.wikipedia.org/wiki/Mersenne_prime} @code{P = 2**n -1},
used for numeric hash scheme.

This corresponds to the @ref{27f9,,sys.hash_info.modulus} constant.


Added in version 3.13.

@end deffn

@geindex PyHASH_BITS (C macro)
@anchor{c-api/hash c PyHASH_BITS}@anchor{1bf2}
@deffn {C Μακροεντολή} PyHASH_BITS

The exponent @code{n} of @code{P} in @ref{1bf1,,PyHASH_MODULUS}.


Added in version 3.13.

@end deffn

@geindex PyHASH_MULTIPLIER (C macro)
@anchor{c-api/hash c PyHASH_MULTIPLIER}@anchor{1ba1}
@deffn {C Μακροεντολή} PyHASH_MULTIPLIER

Prime multiplier used in string and various other hashes.


Added in version 3.13.

@end deffn

@geindex PyHASH_INF (C macro)
@anchor{c-api/hash c PyHASH_INF}@anchor{1bf3}
@deffn {C Μακροεντολή} PyHASH_INF

The hash value returned for a positive infinity.

This corresponds to the @ref{4bfd,,sys.hash_info.inf} constant.


Added in version 3.13.

@end deffn

@geindex PyHASH_IMAG (C macro)
@anchor{c-api/hash c PyHASH_IMAG}@anchor{1bf4}
@deffn {C Μακροεντολή} PyHASH_IMAG

The multiplier used for the imaginary part of a complex number.

This corresponds to the @ref{4bff,,sys.hash_info.imag} constant.


Added in version 3.13.

@end deffn

@geindex PyHash_FuncDef (C type)
@anchor{c-api/hash c PyHash_FuncDef}@anchor{55bc}
@deffn {C Τύπος} type PyHash_FuncDef

Hash function definition used by @ref{55bd,,PyHash_GetFuncDef()}.

@geindex PyHash_FuncDef.hash (C member)
@anchor{c-api/hash c PyHash_FuncDef hash}@anchor{55be}
@deffn {C Μέλος} @ref{1608,,Py_hash_t} (*const hash)(const void*, @ref{e24,,Py_ssize_t})

Hash function.
@end deffn

@geindex PyHash_FuncDef.name (C member)
@anchor{c-api/hash c PyHash_FuncDef name}@anchor{55bf}
@deffn {C Μέλος} const char *name

Hash function name (UTF-8 encoded string).

This corresponds to the @ref{4c00,,sys.hash_info.algorithm} constant.
@end deffn

@geindex PyHash_FuncDef.hash_bits (C member)
@anchor{c-api/hash c PyHash_FuncDef hash_bits}@anchor{55c0}
@deffn {C Μέλος} const int hash_bits

Internal size of the hash value in bits.

This corresponds to the @ref{4c01,,sys.hash_info.hash_bits} constant.
@end deffn

@geindex PyHash_FuncDef.seed_bits (C member)
@anchor{c-api/hash c PyHash_FuncDef seed_bits}@anchor{55c1}
@deffn {C Μέλος} const int seed_bits

Size of seed input in bits.

This corresponds to the @ref{4c02,,sys.hash_info.seed_bits} constant.
@end deffn


Added in version 3.4.

@end deffn

@geindex PyHash_GetFuncDef (C function)
@anchor{c-api/hash c PyHash_GetFuncDef}@anchor{55bd}
@deffn {C Συνάρτηση} @ref{55bc,,PyHash_FuncDef} *PyHash_GetFuncDef (void)

Get the hash function definition.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 456
PEP 456@footnote{https://peps.python.org/pep-0456/} «Secure and interchangeable hash algorithm».



Added in version 3.4.

@end deffn

@geindex Py_HashPointer (C function)
@anchor{c-api/hash c Py_HashPointer}@anchor{638}
@deffn {C Συνάρτηση} @ref{1608,,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}.


Added in version 3.13.

@end deffn

@geindex Py_HashBuffer (C function)
@anchor{c-api/hash c Py_HashBuffer}@anchor{5c2}
@deffn {C Συνάρτηση} @ref{1608,,Py_hash_t} Py_HashBuffer (const void *ptr, Py_ssize_t len)

Compute and return the hash value of a buffer of `len' bytes
starting at address `ptr'. The hash is guaranteed to match that of
@ref{1c7,,bytes}, @ref{1d2,,memoryview}, and other built-in objects
that implement the @ref{311,,buffer protocol}.

Use this function to implement hashing for immutable objects whose
@ref{5205,,tp_richcompare} function compares to another
object’s buffer.

`len' must be greater than or equal to @code{0}.

This function always succeeds.


Added in version 3.14.

@end deffn

@geindex PyObject_GenericHash (C function)
@anchor{c-api/hash c PyObject_GenericHash}@anchor{802}
@deffn {C Συνάρτηση} @ref{1608,,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.

`Λεπτομέρεια υλοποίησης CPython:' In CPython, it is equivalent to @ref{638,,Py_HashPointer()}.


Added in version 3.13.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Reflection,Codec registry and support functions,PyHash API,Utilities<2>
@anchor{c-api/reflection doc}@anchor{55c2}@anchor{c-api/reflection id1}@anchor{55c3}@anchor{c-api/reflection reflection}@anchor{55c4}@anchor{c-api/reflection translation-repo}@anchor{55c5}
@subsection Reflection


@geindex PyEval_GetBuiltins (C function)
@anchor{c-api/reflection c PyEval_GetBuiltins}@anchor{7ea}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyEval_GetBuiltins (void)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'

Αποσύρθηκε στην έκδοση 3.13: Use @ref{7e9,,PyEval_GetFrameBuiltins()} instead.


Return a dictionary of the builtins in the current execution frame,
or the interpreter of the thread state if no frame is currently executing.
@end deffn

@geindex PyEval_GetLocals (C function)
@anchor{c-api/reflection c PyEval_GetLocals}@anchor{7ee}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyEval_GetLocals (void)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'

Αποσύρθηκε στην έκδοση 3.13: Use either @ref{7ed,,PyEval_GetFrameLocals()} to obtain the same behaviour as calling
@ref{28b,,locals()} in Python code, or else call @ref{84e,,PyFrame_GetLocals()} on the result
of @ref{1d37,,PyEval_GetFrame()} to access the @ref{28d,,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{28b,,locals()} for details of the mapping returned at different scopes.

As this function returns a @ref{603,,borrowed reference}, the dictionary returned for
@ref{6ad,,optimized scopes} is cached on the frame object and will remain
alive as long as the frame object does. Unlike @ref{7ed,,PyEval_GetFrameLocals()} and
@ref{28b,,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.


Άλλαξε στην έκδοση 3.13: As part of 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}, @ref{84e,,PyFrame_GetLocals()}, @ref{28b,,locals()}, and
@ref{28d,,FrameType.f_locals} no longer make use of the shared cache
dictionary. Refer to the @ref{681,,What’s New entry} for
additional details.

@end deffn

@geindex PyEval_GetGlobals (C function)
@anchor{c-api/reflection c PyEval_GetGlobals}@anchor{7ec}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyEval_GetGlobals (void)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'

Αποσύρθηκε στην έκδοση 3.13: Use @ref{7eb,,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{1d37}
@deffn {C Συνάρτηση} @ref{b68,,PyFrameObject} *PyEval_GetFrame (void)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the @ref{1a1,,attached thread state}’s frame, which is @code{NULL} if no frame is
currently executing.

See also @ref{b6d,,PyThreadState_GetFrame()}.
@end deffn

@geindex PyEval_GetFrameBuiltins (C function)
@anchor{c-api/reflection c PyEval_GetFrameBuiltins}@anchor{7e9}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyEval_GetFrameBuiltins (void)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Return a dictionary of the builtins in the current execution frame,
or the interpreter of the thread state if no frame is currently executing.


Added in version 3.13.

@end deffn

@geindex PyEval_GetFrameLocals (C function)
@anchor{c-api/reflection c PyEval_GetFrameLocals}@anchor{7ed}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyEval_GetFrameLocals (void)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{28b,,locals()} in Python code.

To access @ref{28d,,f_locals} on the current frame without making an independent
snapshot in @ref{6ad,,optimized scopes}, call @ref{84e,,PyFrame_GetLocals()}
on the result of @ref{1d37,,PyEval_GetFrame()}.


Added in version 3.13.

@end deffn

@geindex PyEval_GetFrameGlobals (C function)
@anchor{c-api/reflection c PyEval_GetFrameGlobals}@anchor{7eb}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyEval_GetFrameGlobals (void)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{1e01,,globals()} in Python code.


Added in version 3.13.

@end deffn

@geindex PyEval_GetFuncName (C function)
@anchor{c-api/reflection c PyEval_GetFuncName}@anchor{5307}
@deffn {C Συνάρτηση} const char *PyEval_GetFuncName (PyObject *func)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the name of `func' if it is a function, class or instance object, else the
name of `func's type.
@end deffn

@geindex PyEval_GetFuncDesc (C function)
@anchor{c-api/reflection c PyEval_GetFuncDesc}@anchor{5306}
@deffn {C Συνάρτηση} const char *PyEval_GetFuncDesc (PyObject *func)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a description string, depending on the type of `func'.
Return values include «()» for functions and methods, « constructor»,
« instance», and « object».  Concatenated with the result of
@ref{5307,,PyEval_GetFuncName()}, the result will be a description of
`func'.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Codec registry and support functions,PyTime C API,Reflection,Utilities<2>
@anchor{c-api/codec doc}@anchor{55c6}@anchor{c-api/codec codec-registry}@anchor{10ec}@anchor{c-api/codec codec-registry-and-support-functions}@anchor{55c7}@anchor{c-api/codec translation-repo}@anchor{55c8}
@subsection Codec registry and support functions


@geindex PyCodec_Register (C function)
@anchor{c-api/codec c PyCodec_Register}@anchor{52cb}
@deffn {C Συνάρτηση} int PyCodec_Register (PyObject *search_function)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Register a new codec search function.

As a 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{c6d}
@deffn {C Συνάρτηση} int PyCodec_Unregister (PyObject *search_function)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.


Added in version 3.10.

@end deffn

@geindex PyCodec_KnownEncoding (C function)
@anchor{c-api/codec c PyCodec_KnownEncoding}@anchor{52c9}
@deffn {C Συνάρτηση} int PyCodec_KnownEncoding (const char *encoding)
` Μέρος του @ref{95c,,Σταθερό 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{3a2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_Encode (PyObject *object, const char *encoding, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{25da,,LookupError} if no encoder can be found.
@end deffn

@geindex PyCodec_Decode (C function)
@anchor{c-api/codec c PyCodec_Decode}@anchor{3a1}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_Decode (PyObject *object, const char *encoding, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{25da,,LookupError} if no decoder can be found.
@end deffn

@menu
* Codec lookup API:: 
* Registry API for Unicode encoding error handlers:: 
* Codec utility variables:: 

@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{55c9}
@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{7df,,KeyError} is set
and @code{NULL} returned.

@geindex PyCodec_Encoder (C function)
@anchor{c-api/codec c PyCodec_Encoder}@anchor{52c5}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_Encoder (const char *encoding)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Get an encoder function for the given `encoding'.
@end deffn

@geindex PyCodec_Decoder (C function)
@anchor{c-api/codec c PyCodec_Decoder}@anchor{52c4}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_Decoder (const char *encoding)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Get a decoder function for the given `encoding'.
@end deffn

@geindex PyCodec_IncrementalEncoder (C function)
@anchor{c-api/codec c PyCodec_IncrementalEncoder}@anchor{52c8}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_IncrementalEncoder (const char *encoding, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Get an @ref{2a4d,,IncrementalEncoder} object for the given `encoding'.
@end deffn

@geindex PyCodec_IncrementalDecoder (C function)
@anchor{c-api/codec c PyCodec_IncrementalDecoder}@anchor{52c7}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_IncrementalDecoder (const char *encoding, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Get an @ref{2a4e,,IncrementalDecoder} object for the given `encoding'.
@end deffn

@geindex PyCodec_StreamReader (C function)
@anchor{c-api/codec c PyCodec_StreamReader}@anchor{52ce}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_StreamReader (const char *encoding, PyObject *stream, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Get a @ref{2a52,,StreamReader} factory function for the given `encoding'.
@end deffn

@geindex PyCodec_StreamWriter (C function)
@anchor{c-api/codec c PyCodec_StreamWriter}@anchor{52cf}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_StreamWriter (const char *encoding, PyObject *stream, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Get a @ref{2a51,,StreamWriter} factory function for the given `encoding'.
@end deffn

@node Registry API for Unicode encoding error handlers,Codec utility variables,Codec lookup API,Codec registry and support functions
@anchor{c-api/codec registry-api-for-unicode-encoding-error-handlers}@anchor{55ca}
@subsubsection Registry API for Unicode encoding error handlers


@geindex PyCodec_RegisterError (C function)
@anchor{c-api/codec c PyCodec_RegisterError}@anchor{52cc}
@deffn {C Συνάρτηση} int PyCodec_RegisterError (const char *name, PyObject *error)
` Μέρος του @ref{95c,,Σταθερό 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{a67,,UnicodeEncodeError}, @ref{dd7,,UnicodeDecodeError} or
@ref{1b1c,,UnicodeTranslateError} that holds information about the problematic
sequence of characters or bytes and their offset in the original string (see
@ref{674,,Unicode Exception Objects} 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{52ca}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_LookupError (const char *name)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{52d0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_StrictErrors (PyObject *exc)
`Επιστρεφόμενη τιμή: Πάντοτε NULL.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Raise `exc' as an exception.
@end deffn

@geindex PyCodec_IgnoreErrors (C function)
@anchor{c-api/codec c PyCodec_IgnoreErrors}@anchor{52c6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_IgnoreErrors (PyObject *exc)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Ignore the unicode error, skipping the faulty input.
@end deffn

@geindex PyCodec_ReplaceErrors (C function)
@anchor{c-api/codec c PyCodec_ReplaceErrors}@anchor{52cd}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_ReplaceErrors (PyObject *exc)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{52d1}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_XMLCharRefReplaceErrors (PyObject *exc)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{52c3}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_BackslashReplaceErrors (PyObject *exc)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{1260}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCodec_NameReplaceErrors (PyObject *exc)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Replace the unicode encode error with @code{\N@{...@}} escapes.


Added in version 3.5.

@end deffn

@node Codec utility variables,,Registry API for Unicode encoding error handlers,Codec registry and support functions
@anchor{c-api/codec codec-utility-variables}@anchor{55cb}
@subsubsection Codec utility variables


@geindex Py_hexdigits (C var)
@anchor{c-api/codec c Py_hexdigits}@anchor{55cc}
@deffn {C Μεταβλητή} const char *Py_hexdigits

A string constant containing the lowercase hexadecimal digits: @code{"0123456789abcdef"}.


Added in version 3.3.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node PyTime C API,Support for Perf Maps,Codec registry and support functions,Utilities<2>
@anchor{c-api/time doc}@anchor{692}@anchor{c-api/time c-api-time}@anchor{7cb}@anchor{c-api/time pytime-c-api}@anchor{55cd}@anchor{c-api/time translation-repo}@anchor{55ce}
@subsection PyTime C API



Added in version 3.13.


The clock C API provides access to system clocks.
It is similar to the Python @ref{f7,,time} module.

For C API related to the @ref{33,,datetime} module, see @ref{55cf,,DateTime Objects}.

@menu
* Types: Types<3>. 
* Clock Functions:: 
* Raw Clock Functions:: 
* Conversion functions:: 

@end menu

@node Types<3>,Clock Functions,,PyTime C API
@anchor{c-api/time types}@anchor{55d0}
@subsubsection Types


@geindex PyTime_t (C type)
@anchor{c-api/time c PyTime_t}@anchor{7cc}
@deffn {C Τύπος} 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{7d4,,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{7cd}
@deffn {C Μεταβλητή} @ref{7cc,,PyTime_t} PyTime_MIN

Minimum value of @ref{7cc,,PyTime_t}.
@end deffn

@geindex PyTime_MAX (C var)
@anchor{c-api/time c PyTime_MAX}@anchor{7ce}
@deffn {C Μεταβλητή} @ref{7cc,,PyTime_t} PyTime_MAX

Maximum value of @ref{7cc,,PyTime_t}.
@end deffn

@node Clock Functions,Raw Clock Functions,Types<3>,PyTime C API
@anchor{c-api/time clock-functions}@anchor{55d1}
@subsubsection Clock Functions


The following functions take a pointer to a @ref{7cc,,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 @ref{5330,,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 an @ref{1a1,,attached thread state}.

@geindex PyTime_Monotonic (C function)
@anchor{c-api/time c PyTime_Monotonic}@anchor{7d0}
@deffn {C Συνάρτηση} int PyTime_Monotonic (PyTime_t *result)

Read the monotonic clock.
See @ref{75d,,time.monotonic()} for important details on this clock.
@end deffn

@geindex PyTime_PerfCounter (C function)
@anchor{c-api/time c PyTime_PerfCounter}@anchor{7d2}
@deffn {C Συνάρτηση} int PyTime_PerfCounter (PyTime_t *result)

Read the performance counter.
See @ref{e49,,time.perf_counter()} for important details on this clock.
@end deffn

@geindex PyTime_Time (C function)
@anchor{c-api/time c PyTime_Time}@anchor{7d4}
@deffn {C Συνάρτηση} int PyTime_Time (PyTime_t *result)

Read the “wall clock” time.
See @ref{75e,,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{55d2}
@subsubsection Raw Clock Functions


Similar to clock functions, but don’t set an exception on error and don’t
require the caller to have an @ref{1a1,,attached thread state}.

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, @ref{1a1,,attach} a @ref{1a70,,thread state},
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{7d1}
@deffn {C Συνάρτηση} int PyTime_MonotonicRaw (PyTime_t *result)

Similar to @ref{7d0,,PyTime_Monotonic()},
but don’t set an exception on error and don’t require an @ref{1a1,,attached thread state}.
@end deffn

@geindex PyTime_PerfCounterRaw (C function)
@anchor{c-api/time c PyTime_PerfCounterRaw}@anchor{7d3}
@deffn {C Συνάρτηση} int PyTime_PerfCounterRaw (PyTime_t *result)

Similar to @ref{7d2,,PyTime_PerfCounter()},
but don’t set an exception on error and don’t require an @ref{1a1,,attached thread state}.
@end deffn

@geindex PyTime_TimeRaw (C function)
@anchor{c-api/time c PyTime_TimeRaw}@anchor{7d5}
@deffn {C Συνάρτηση} int PyTime_TimeRaw (PyTime_t *result)

Similar to @ref{7d4,,PyTime_Time()},
but don’t set an exception on error and don’t require an @ref{1a1,,attached thread state}.
@end deffn

@node Conversion functions,,Raw Clock Functions,PyTime C API
@anchor{c-api/time conversion-functions}@anchor{55d3}
@subsubsection Conversion functions


@geindex PyTime_AsSecondsDouble (C function)
@anchor{c-api/time c PyTime_AsSecondsDouble}@anchor{7cf}
@deffn {C Συνάρτηση} 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Support for Perf Maps,,PyTime C API,Utilities<2>
@anchor{c-api/perfmaps doc}@anchor{55d4}@anchor{c-api/perfmaps perfmaps}@anchor{55d5}@anchor{c-api/perfmaps support-for-perf-maps}@anchor{55d6}@anchor{c-api/perfmaps translation-repo}@anchor{55d7}
@subsection Support for Perf Maps


On supported platforms (Linux and macOS), 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} or
samply@footnote{https://github.com/mstange/samply/}). 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 an @ref{1a1,,attached thread state} is not required for these APIs.

@geindex PyUnstable_PerfMapState_Init (C function)
@anchor{c-api/perfmaps c PyUnstable_PerfMapState_Init}@anchor{1cad}
@deffn {C Συνάρτηση} int PyUnstable_PerfMapState_Init (void)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@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{1cac,,PyUnstable_WritePerfMapEntry()}). Normally, there’s no need
to call this explicitly; just use @code{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{1cac}
@deffn {C Συνάρτηση} int PyUnstable_WritePerfMapEntry (const void *code_addr, size_t code_size, const char *entry_name)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@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{1cad,,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 @code{PyUnstable_PerfMapState_Init()} on failure.
@end deffn

@geindex PyUnstable_PerfMapState_Fini (C function)
@anchor{c-api/perfmaps c PyUnstable_PerfMapState_Fini}@anchor{1cae}
@deffn {C Συνάρτηση} void PyUnstable_PerfMapState_Fini (void)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Close the perf map file opened by @ref{1cad,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Abstract Objects Layer,Concrete Objects Layer,Utilities<2>,Python/C API reference manual
@anchor{c-api/abstract doc}@anchor{55d8}@anchor{c-api/abstract abstract}@anchor{5208}@anchor{c-api/abstract abstract-objects-layer}@anchor{55d9}@anchor{c-api/abstract translation-repo}@anchor{55da}
@section Abstract Objects Layer


The functions in this chapter interact with Python objects regardless of their
type, or with wide classes of object types (e.g. all numerical types, or all
sequence types).  When used on object types for which they do not apply, they
will raise a Python exception.

It is not possible to use these functions on objects that are not properly
initialized, such as a list object that has been created by @ref{5260,,PyList_New()},
but whose items have not been set to some non-@code{NULL} value yet.

@menu
* Object Protocol:: 
* Call Protocol:: 
* Number Protocol:: 
* Sequence Protocol:: 
* Mapping Protocol:: 
* Iterator Protocol:: 
* Buffer Protocol:: 

@end menu

@node Object Protocol,Call Protocol,,Abstract Objects Layer
@anchor{c-api/object doc}@anchor{55db}@anchor{c-api/object object}@anchor{55dc}@anchor{c-api/object object-protocol}@anchor{55dd}
@subsection Object Protocol


@geindex Py_GetConstant (C function)
@anchor{c-api/object c Py_GetConstant}@anchor{7ef}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *Py_GetConstant (unsigned int constant_id)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Get a @ref{7da,,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

Value

@tab

Returned object

@item

@geindex Py_CONSTANT_NONE (C macro)
@anchor{c-api/object c Py_CONSTANT_NONE}@anchor{55de}
@deffn {C Μακροεντολή} Py_CONSTANT_NONE
@end deffn

@tab

@code{0}

@tab

@ref{a65,,None}

@item

@geindex Py_CONSTANT_FALSE (C macro)
@anchor{c-api/object c Py_CONSTANT_FALSE}@anchor{55df}
@deffn {C Μακροεντολή} Py_CONSTANT_FALSE
@end deffn

@tab

@code{1}

@tab

@ref{ef5,,False}

@item

@geindex Py_CONSTANT_TRUE (C macro)
@anchor{c-api/object c Py_CONSTANT_TRUE}@anchor{55e0}
@deffn {C Μακροεντολή} Py_CONSTANT_TRUE
@end deffn

@tab

@code{2}

@tab

@ref{fcc,,True}

@item

@geindex Py_CONSTANT_ELLIPSIS (C macro)
@anchor{c-api/object c Py_CONSTANT_ELLIPSIS}@anchor{55e1}
@deffn {C Μακροεντολή} Py_CONSTANT_ELLIPSIS
@end deffn

@tab

@code{3}

@tab

@ref{2519,,Ellipsis}

@item

@geindex Py_CONSTANT_NOT_IMPLEMENTED (C macro)
@anchor{c-api/object c Py_CONSTANT_NOT_IMPLEMENTED}@anchor{55e2}
@deffn {C Μακροεντολή} Py_CONSTANT_NOT_IMPLEMENTED
@end deffn

@tab

@code{4}

@tab

@ref{440,,NotImplemented}

@item

@geindex Py_CONSTANT_ZERO (C macro)
@anchor{c-api/object c Py_CONSTANT_ZERO}@anchor{55e3}
@deffn {C Μακροεντολή} 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{55e4}
@deffn {C Μακροεντολή} 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{55e5}
@deffn {C Μακροεντολή} 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{55e6}
@deffn {C Μακροεντολή} 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{55e7}
@deffn {C Μακροεντολή} 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.


Added in version 3.13.


`Λεπτομέρεια υλοποίησης CPython:' In CPython, all of these constants are @ref{398,,immortal}.
@end deffn

@geindex Py_GetConstantBorrowed (C function)
@anchor{c-api/object c Py_GetConstantBorrowed}@anchor{7f0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *Py_GetConstantBorrowed (unsigned int constant_id)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Similar to @ref{7ef,,Py_GetConstant()}, but return a @ref{603,,borrowed reference}.

This function is primarily intended for backwards compatibility:
using @ref{7ef,,Py_GetConstant()} is recommended for new code.

The reference is borrowed from the interpreter, and is valid until the
interpreter finalization.


Added in version 3.13.

@end deffn

@geindex Py_NotImplemented (C var)
@anchor{c-api/object c Py_NotImplemented}@anchor{55e8}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *Py_NotImplemented

The @code{NotImplemented} singleton, used to signal that an operation is
not implemented for the given type combination.
@end deffn

@geindex Py_RETURN_NOTIMPLEMENTED (C macro)
@anchor{c-api/object c Py_RETURN_NOTIMPLEMENTED}@anchor{19e5}
@deffn {C Μακροεντολή} Py_RETURN_NOTIMPLEMENTED

Properly handle returning @ref{55e8,,Py_NotImplemented} from within a C
function (that is, create a new @ref{7da,,strong reference}
to @ref{440,,NotImplemented} and return it).
@end deffn

@geindex Py_PRINT_RAW (C macro)
@anchor{c-api/object c Py_PRINT_RAW}@anchor{55e9}
@deffn {C Μακροεντολή} Py_PRINT_RAW

Flag to be used with multiple functions that print the object (like
@ref{18fe,,PyObject_Print()} and @ref{5350,,PyFile_WriteObject()}).
If passed, these functions use the @ref{1df,,str()} of the object
instead of the @ref{45b,,repr()}.
@end deffn

@geindex PyObject_Print (C function)
@anchor{c-api/object c PyObject_Print}@anchor{18fe}
@deffn {C Συνάρτηση} 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{55e9,,Py_PRINT_RAW}; if given, the @ref{1df,,str()} of the object is written
instead of the @ref{45b,,repr()}.
@end deffn

@geindex PyObject_Dump (C function)
@anchor{c-api/object c PyObject_Dump}@anchor{374}
@deffn {C Συνάρτηση} void PyObject_Dump (PyObject *op)

Dump an object `op' to @code{stderr}. This should only be used for debugging.

The output is intended to try dumping objects even after memory corruption:


@itemize *

@item 
Information is written starting with fields that are the least likely to
crash when accessed.

@item 
This function can be called without an @ref{1a1,,attached thread state}, but
it’s not recommended to do so: it can cause deadlocks.

@item 
An object that does not belong to the current interpreter may be dumped,
but this may also cause crashes or unintended behavior.

@item 
Implement a heuristic to detect if the object memory has been freed. Don’t
display the object contents in this case, only its memory address.

@item 
The output format may change at any time.
@end itemize

Example of output:

@example
object address  : 0x7f80124702c0
object refcount : 2
object type     : 0x9902e0
object type name: str
object repr     : 'abcdef'
@end example


Added in version 3.15.

@end deffn

@geindex PyObject_HasAttrWithError (C function)
@anchor{c-api/object c PyObject_HasAttrWithError}@anchor{80f}
@deffn {C Συνάρτηση} int PyObject_HasAttrWithError (PyObject *o, PyObject *attr_name)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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}.


Added in version 3.13.

@end deffn

@geindex PyObject_HasAttrStringWithError (C function)
@anchor{c-api/object c PyObject_HasAttrStringWithError}@anchor{811}
@deffn {C Συνάρτηση} int PyObject_HasAttrStringWithError (PyObject *o, const char *attr_name)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
This is the same as @ref{80f,,PyObject_HasAttrWithError()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.


Added in version 3.13.

@end deffn

@geindex PyObject_HasAttr (C function)
@anchor{c-api/object c PyObject_HasAttr}@anchor{810}
@deffn {C Συνάρτηση} int PyObject_HasAttr (PyObject *o, PyObject *attr_name)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Returns @code{1} if `o' has the attribute `attr_name', and @code{0} otherwise.
This function always succeeds.

@cartouche
@quotation Σημείωση 
Exceptions that occur when this calls @ref{8e3,,__getattr__()} and
@ref{f90,,__getattribute__()} methods aren’t propagated,
but instead given to @ref{70c,,sys.unraisablehook()}.
For proper error handling, use @ref{80f,,PyObject_HasAttrWithError()},
@ref{7e4,,PyObject_GetOptionalAttr()} or @ref{3b7,,PyObject_GetAttr()} instead.
@end quotation
@end cartouche
@end deffn

@geindex PyObject_HasAttrString (C function)
@anchor{c-api/object c PyObject_HasAttrString}@anchor{812}
@deffn {C Συνάρτηση} int PyObject_HasAttrString (PyObject *o, const char *attr_name)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is the same as @ref{810,,PyObject_HasAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.

@cartouche
@quotation Σημείωση 
Exceptions that occur when this calls @ref{8e3,,__getattr__()} and
@ref{f90,,__getattribute__()} methods or while creating the temporary
@ref{1df,,str} object are silently ignored.
For proper error handling, use @ref{811,,PyObject_HasAttrStringWithError()},
@ref{7e5,,PyObject_GetOptionalAttrString()}
or @ref{7e6,,PyObject_GetAttrString()} instead.
@end quotation
@end cartouche
@end deffn

@geindex PyObject_GetAttr (C function)
@anchor{c-api/object c PyObject_GetAttr}@anchor{3b7}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_GetAttr (PyObject *o, PyObject *attr_name)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{7e4,,PyObject_GetOptionalAttr()} instead.
@end deffn

@geindex PyObject_GetAttrString (C function)
@anchor{c-api/object c PyObject_GetAttrString}@anchor{7e6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_GetAttrString (PyObject *o, const char *attr_name)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is the same as @ref{3b7,,PyObject_GetAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.

If the missing attribute should not be treated as a failure, you can use
@ref{7e5,,PyObject_GetOptionalAttrString()} instead.
@end deffn

@geindex PyObject_GetOptionalAttr (C function)
@anchor{c-api/object c PyObject_GetOptionalAttr}@anchor{7e4}
@deffn {C Συνάρτηση} int PyObject_GetOptionalAttr (PyObject *obj, PyObject *attr_name, PyObject **result);
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Variant of @ref{3b7,,PyObject_GetAttr()} which doesn’t raise
@ref{1a9,,AttributeError} if the attribute is not found.

If the attribute is found, return @code{1} and set `*result' to a new
@ref{7da,,strong reference} to the attribute.
If the attribute is not found, return @code{0} and set `*result' to @code{NULL};
the @ref{1a9,,AttributeError} is silenced.
If an error other than @code{AttributeError} is raised, return @code{-1} and
set `*result' to @code{NULL}.


Added in version 3.13.

@end deffn

@geindex PyObject_GetOptionalAttrString (C function)
@anchor{c-api/object c PyObject_GetOptionalAttrString}@anchor{7e5}
@deffn {C Συνάρτηση} int PyObject_GetOptionalAttrString (PyObject *obj, const char *attr_name, PyObject **result);
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
This is the same as @ref{7e4,,PyObject_GetOptionalAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.


Added in version 3.13.

@end deffn

@geindex PyObject_GenericGetAttr (C function)
@anchor{c-api/object c PyObject_GenericGetAttr}@anchor{53c6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_GenericGetAttr (PyObject *o, PyObject *name)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Generic attribute getter function that is meant to be put into a type
object’s @code{tp_getattro} slot.  It looks for a descriptor in the dictionary
of classes in the object’s MRO as well as an attribute in the object’s
@ref{1bf,,__dict__} (if present).  As outlined in @ref{100d,,Υλοποίηση Περιγραφέων},
data descriptors take preference over instance attributes, while non-data
descriptors don’t.  Otherwise, an @ref{1a9,,AttributeError} is raised.
@end deffn

@geindex PyObject_SetAttr (C function)
@anchor{c-api/object c PyObject_SetAttr}@anchor{1927}
@deffn {C Συνάρτηση} int PyObject_SetAttr (PyObject *o, PyObject *attr_name, PyObject *v)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Set the value of the attribute named `attr_name', for object `o', 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.attr_name = v}.

If `v' is @code{NULL}, the attribute is deleted. This behaviour is deprecated
in favour of using @ref{1a6d,,PyObject_DelAttr()}, but there are currently no
plans to remove it.

The function must not be called with a @code{NULL} `v' and an exception set.
This case can arise from forgetting @code{NULL} checks and would delete the
attribute.


Άλλαξε στην έκδοση 3.15: Must not be called with NULL value if an exception is set.

@end deffn

@geindex PyObject_SetAttrString (C function)
@anchor{c-api/object c PyObject_SetAttrString}@anchor{1a6c}
@deffn {C Συνάρτηση} int PyObject_SetAttrString (PyObject *o, const char *attr_name, PyObject *v)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is the same as @ref{1927,,PyObject_SetAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.

If `v' is @code{NULL}, the attribute is deleted, but this feature is
deprecated in favour of using @ref{1a6e,,PyObject_DelAttrString()}.

The function must not be called with a @code{NULL} `v' and an exception set.
This case can arise from forgetting @code{NULL} checks and would delete the
attribute.

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{5451,,PyUnicode_FromString()} and @ref{1927,,PyObject_SetAttr()} directly.
For more details, see @ref{3b5,,PyUnicode_InternFromString()}, which may be
used internally to create a key object.


Άλλαξε στην έκδοση 3.15: Must not be called with NULL value if an exception is set.

@end deffn

@geindex PyObject_GenericSetAttr (C function)
@anchor{c-api/object c PyObject_GenericSetAttr}@anchor{53c7}
@deffn {C Συνάρτηση} int PyObject_GenericSetAttr (PyObject *o, PyObject *name, PyObject *value)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Generic attribute setter and deleter function that is meant
to be put into a type object’s @ref{51fd,,tp_setattro}
slot.  It looks for a data descriptor in the
dictionary of classes in the object’s MRO, and if found it takes preference
over setting or deleting the attribute in the instance dictionary. Otherwise, the
attribute is set or deleted in the object’s @ref{1bf,,__dict__} (if present).
On success, @code{0} is returned, otherwise an @ref{1a9,,AttributeError}
is raised and @code{-1} is returned.
@end deffn

@geindex PyObject_DelAttr (C function)
@anchor{c-api/object c PyObject_DelAttr}@anchor{1a6d}
@deffn {C Συνάρτηση} int PyObject_DelAttr (PyObject *o, PyObject *attr_name)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Delete attribute named `attr_name', for object `o'. Returns @code{-1} on failure.
This is the equivalent of the Python statement @code{del o.attr_name}.
@end deffn

@geindex PyObject_DelAttrString (C function)
@anchor{c-api/object c PyObject_DelAttrString}@anchor{1a6e}
@deffn {C Συνάρτηση} int PyObject_DelAttrString (PyObject *o, const char *attr_name)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
This is the same as @ref{1a6d,,PyObject_DelAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,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{5451,,PyUnicode_FromString()} and @ref{1a6d,,PyObject_DelAttr()} directly.
For more details, see @ref{3b5,,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{1efa}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_GenericGetDict (PyObject *o, void *context)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
A generic implementation for the getter of a @code{__dict__} descriptor. It
creates the dictionary if necessary.

This function may also be called to get the @ref{1bf,,__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{3b7,,PyObject_GetAttr()}
when accessing an attribute on the object.

On failure, returns @code{NULL} with an exception set.


Added in version 3.3.

@end deffn

@geindex PyObject_GenericSetDict (C function)
@anchor{c-api/object c PyObject_GenericSetDict}@anchor{53c8}
@deffn {C Συνάρτηση} int PyObject_GenericSetDict (PyObject *o, PyObject *value, void *context)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
A generic implementation for the setter of a @code{__dict__} descriptor. This
implementation does not allow the dictionary to be deleted.


Added in version 3.3.

@end deffn

@geindex _PyObject_GetDictPtr (C function)
@anchor{c-api/object c _PyObject_GetDictPtr}@anchor{55ea}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} **_PyObject_GetDictPtr (PyObject *obj)

Return a pointer to @ref{1bf,,__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{3b7,,PyObject_GetAttr()}
when accessing an attribute on the object.
@end deffn

@geindex PyObject_RichCompare (C function)
@anchor{c-api/object c PyObject_RichCompare}@anchor{5206}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_RichCompare (PyObject *o1, PyObject *o2, int opid)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Compare the values of `o1' and `o2' using the operation specified by `opid',
which must be one of @ref{55eb,,Py_LT}, @ref{55ec,,Py_LE}, @ref{55ed,,Py_EQ},
@ref{55ee,,Py_NE}, @ref{55ef,,Py_GT}, or @ref{55f0,,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{1f7e}
@deffn {C Συνάρτηση} int PyObject_RichCompareBool (PyObject *o1, PyObject *o2, int opid)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Compare the values of `o1' and `o2' using the operation specified by `opid',
like @ref{5206,,PyObject_RichCompare()}, but returns @code{-1} on error, @code{0} if
the result is false, @code{1} otherwise.
@end deffn

@cartouche
@quotation Σημείωση 
If `o1' and `o2' are the same object, @ref{1f7e,,PyObject_RichCompareBool()}
will always return @code{1} for @ref{55ed,,Py_EQ} and @code{0} for @ref{55ee,,Py_NE}.
@end quotation
@end cartouche

@geindex PyObject_Format (C function)
@anchor{c-api/object c PyObject_Format}@anchor{53c5}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_Format (PyObject *obj, PyObject *format_spec)
` Μέρος του @ref{95c,,Σταθερό 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{13d7}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_Repr (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{45b,,repr()} built-in function.

If argument is @code{NULL}, return the string @code{'<NULL>'}.


Άλλαξε στην έκδοση 3.4: This function now includes a debug assertion to help ensure that it
does not silently discard an active exception.

@end deffn

@geindex PyObject_ASCII (C function)
@anchor{c-api/object c PyObject_ASCII}@anchor{53be}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_ASCII (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex built-in function;ascii

As @ref{13d7,,PyObject_Repr()}, compute a string representation of object `o', but
escape the non-ASCII characters in the string returned by
@code{PyObject_Repr()} with @code{\x}, @code{\u} or @code{\U} escapes.  This generates
a string similar to that returned by @code{PyObject_Repr()} in Python 2.
Called by the @ref{1789,,ascii()} built-in function.

If argument is @code{NULL}, return the string @code{'<NULL>'}.

@geindex string;PyObject_Str (C function)
@end deffn

@geindex PyObject_Str (C function)
@anchor{c-api/object c PyObject_Str}@anchor{13d8}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_Str (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{1df,,str()} built-in function
and, therefore, by the @ref{131f,,print()} function.

If argument is @code{NULL}, return the string @code{'<NULL>'}.


Άλλαξε στην έκδοση 3.4: This function now includes a debug assertion to help ensure that it
does not silently discard an active exception.

@end deffn

@geindex PyObject_Bytes (C function)
@anchor{c-api/object c PyObject_Bytes}@anchor{53c0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_Bytes (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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.

If argument is @code{NULL}, return the @ref{1c7,,bytes} object @code{b'<NULL>'}.
@end deffn

@geindex PyObject_IsSubclass (C function)
@anchor{c-api/object c PyObject_IsSubclass}@anchor{1258}
@deffn {C Συνάρτηση} int PyObject_IsSubclass (PyObject *derived, PyObject *cls)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return @code{1} if the class `derived' is identical to or derived from the class
`cls', otherwise return @code{0}.  In case of an error, return @code{-1}.

If `cls' is a tuple, the check will be done against every entry in `cls'.
The result will be @code{1} when at least one of the checks returns @code{1},
otherwise it will be @code{0}.

If `cls' has a @ref{25bd,,__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{2569,,cls.__mro__}.

Normally only class objects, i.e. instances of @ref{186,,type} or a derived
class, are considered classes.  However, objects can override this by having
a @ref{184e,,__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{1257}
@deffn {C Συνάρτηση} int PyObject_IsInstance (PyObject *inst, PyObject *cls)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return @code{1} if `inst' is an instance of the class `cls' or a subclass of
`cls', or @code{0} if not.  On error, returns @code{-1} and sets an exception.

If `cls' is a tuple, the check will be done against every entry in `cls'.
The result will be @code{1} when at least one of the checks returns @code{1},
otherwise it will be @code{0}.

If `cls' has a @ref{25bc,,__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{184f,,__class__} attribute.

An object `cls' can override if it is considered a class, and what its base
classes are, by having a @ref{184e,,__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{649}
@deffn {C Συνάρτηση} @ref{1608,,Py_hash_t} PyObject_Hash (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό 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)}.


Άλλαξε στην έκδοση 3.2: The return type is now Py_hash_t.  This is a signed integer the same size
as @ref{e24,,Py_ssize_t}.

@end deffn

@geindex PyObject_HashNotImplemented (C function)
@anchor{c-api/object c PyObject_HashNotImplemented}@anchor{1769}
@deffn {C Συνάρτηση} @ref{1608,,Py_hash_t} PyObject_HashNotImplemented (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Set a @ref{291,,TypeError} indicating that @code{type(o)} is not @ref{183,,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{53cb}
@deffn {C Συνάρτηση} int PyObject_IsTrue (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό 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{53cd}
@deffn {C Συνάρτηση} int PyObject_Not (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό 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{53d0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_Type (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{3ea,,SystemError} and returns @code{NULL}.  This
is equivalent to the Python expression @code{type(o)}.
This function creates a new @ref{7da,,strong reference} to the return value.
There’s really no reason to use this
function instead of the @ref{5f5,,Py_TYPE()} function, which returns a
pointer of type @ref{e6b,,PyTypeObject}*, except when a new
strong reference is needed.
@end deffn

@geindex PyObject_TypeCheck (C function)
@anchor{c-api/object c PyObject_TypeCheck}@anchor{1eab}
@deffn {C Συνάρτηση} 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{53cf}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyObject_Size (PyObject *o)
@anchor{c-api/object c PyObject_Length}@anchor{53cc}
@deffnx {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyObject_Length (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό 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{13ad}
@deffn {C Συνάρτηση} @ref{e24,,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{12bc,,__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)}.


Added in version 3.4.

@end deffn

@geindex PyObject_GetItem (C function)
@anchor{c-api/object c PyObject_GetItem}@anchor{7e2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_GetItem (PyObject *o, PyObject *key)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{525f}
@deffn {C Συνάρτηση} int PyObject_SetItem (PyObject *o, PyObject *key, PyObject *v)
` Μέρος του @ref{95c,,Σταθερό 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{53c2}
@deffn {C Συνάρτηση} int PyObject_DelItem (PyObject *o, PyObject *key)
` Μέρος του @ref{95c,,Σταθερό 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{53c3}
@deffn {C Συνάρτηση} int PyObject_DelItemString (PyObject *o, const char *key)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is the same as @ref{53c2,,PyObject_DelItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.
@end deffn

@geindex PyObject_Dir (C function)
@anchor{c-api/object c PyObject_Dir}@anchor{53c4}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_Dir (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{1ea5,,PyErr_Occurred()} will return false.
@end deffn

@geindex PyObject_GetIter (C function)
@anchor{c-api/object c PyObject_GetIter}@anchor{53ca}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_GetIter (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{291,,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{53ce}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_SelfIter (PyObject *obj)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is equivalent to the Python @code{__iter__(self): return self} method.
It is intended for @ref{6ce,,iterator} types, to be used in the @ref{1891,,PyTypeObject.tp_iter} slot.
@end deffn

@geindex PyObject_GetAIter (C function)
@anchor{c-api/object c PyObject_GetAIter}@anchor{53c9}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_GetAIter (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{291,,TypeError} and
returns @code{NULL} if the object cannot be iterated.


Added in version 3.10.

@end deffn

@geindex PyObject_GetTypeData (C function)
@anchor{c-api/object c PyObject_GetTypeData}@anchor{19a}
@deffn {C Συνάρτηση} void *PyObject_GetTypeData (PyObject *o, PyTypeObject *cls)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{199,,PyType_Spec.basicsize}.
Python does not check this.

On error, set an exception and return @code{NULL}.


Added in version 3.12.

@end deffn

@geindex PyType_GetTypeDataSize (C function)
@anchor{c-api/object c PyType_GetTypeDataSize}@anchor{955}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyType_GetTypeDataSize (PyTypeObject *cls)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
Return the size of the instance memory space reserved for `cls', i.e. the size of the
memory @ref{19a,,PyObject_GetTypeData()} returns.

This may be larger than requested using @ref{199,,-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{199,,PyType_Spec.basicsize}.
Python does not check this.

On error, set an exception and return a negative value.


Added in version 3.12.

@end deffn

@geindex PyObject_GetItemData (C function)
@anchor{c-api/object c PyObject_GetItemData}@anchor{957}
@deffn {C Συνάρτηση} void *PyObject_GetItemData (PyObject *o)

Get a pointer to per-item data for a class with
@ref{956,,Py_TPFLAGS_ITEMS_AT_END}.

On error, set an exception and return @code{NULL}.
@ref{291,,TypeError} is raised if `o' does not have
@ref{956,,Py_TPFLAGS_ITEMS_AT_END} set.


Added in version 3.12.

@end deffn

@geindex PyObject_VisitManagedDict (C function)
@anchor{c-api/object c PyObject_VisitManagedDict}@anchor{803}
@deffn {C Συνάρτηση} 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{39c,,Py_TPFLAGS_MANAGED_DICT} flag set.


Added in version 3.13.

@end deffn

@geindex PyObject_ClearManagedDict (C function)
@anchor{c-api/object c PyObject_ClearManagedDict}@anchor{804}
@deffn {C Συνάρτηση} void PyObject_ClearManagedDict (PyObject *obj)

Clear the managed dictionary of `obj'.

This function must only be called in a clear function of the type which
has the @ref{39c,,Py_TPFLAGS_MANAGED_DICT} flag set.


Added in version 3.13.

@end deffn

@geindex PyUnstable_Object_EnableDeferredRefcount (C function)
@anchor{c-api/object c PyUnstable_Object_EnableDeferredRefcount}@anchor{5f1}
@deffn {C Συνάρτηση} int PyUnstable_Object_EnableDeferredRefcount (PyObject *obj)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Enable deferred reference counting@footnote{https://peps.python.org/pep-0703/#deferred-reference-counting} on `obj',
if supported by the runtime.  In the @ref{487,,free-threaded} build,
this allows the interpreter to avoid reference count adjustments to `obj',
which may improve multi-threaded performance.  The tradeoff is
that `obj' will only be deallocated by the tracing garbage collector, and
not when the interpreter no longer has any references to it.

This function returns @code{1} if deferred reference counting is enabled on `obj',
and @code{0} if deferred reference counting is not supported or if the hint was
ignored by the interpreter, such as when deferred reference counting is already
enabled on `obj'. This function is thread-safe, and cannot fail.

This function does nothing on builds with the @ref{411,,GIL} enabled, which do
not support deferred reference counting. This also does nothing if `obj' is not
an object tracked by the garbage collector (see @ref{16b2,,gc.is_tracked()} and
@ref{d3e,,PyObject_GC_IsTracked()}).

This function is intended to be used soon after `obj' is created,
by the code that creates it, such as in the object’s @ref{981,,tp_new}
slot.


Added in version 3.14.

@end deffn

@geindex PyUnstable_Object_IsUniqueReferencedTemporary (C function)
@anchor{c-api/object c PyUnstable_Object_IsUniqueReferencedTemporary}@anchor{5f3}
@deffn {C Συνάρτηση} int PyUnstable_Object_IsUniqueReferencedTemporary (PyObject *obj)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Check if `obj' is a unique temporary object.
Returns @code{1} if `obj' is known to be a unique temporary object,
and @code{0} otherwise.  This function cannot fail, but the check is
conservative, and may return @code{0} in some cases even if `obj' is a unique
temporary object.

If an object is a unique temporary, it is guaranteed that the current code
has the only reference to the object. For arguments to C functions, this
should be used instead of checking if the reference count is @code{1}. Starting
with Python 3.14, the interpreter internally avoids some reference count
modifications when loading objects onto the operands stack by
@ref{603,,borrowing} references when possible, which means
that a reference count of @code{1} by itself does not guarantee that a function
argument uniquely referenced.

In the example below, @code{my_func} is called with a unique temporary object
as its argument:

@example
my_func([1, 2, 3])
@end example

In the example below, @code{my_func} is `not' called with a unique temporary
object as its argument, even if its refcount is @code{1}:

@example
my_list = [1, 2, 3]
my_func(my_list)
@end example

See also the function @ref{54b,,Py_REFCNT()}.


Added in version 3.14.

@end deffn

@geindex PyUnstable_IsImmortal (C function)
@anchor{c-api/object c PyUnstable_IsImmortal}@anchor{5f0}
@deffn {C Συνάρτηση} int PyUnstable_IsImmortal (PyObject *obj)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

This function returns non-zero if `obj' is @ref{398,,immortal}, and zero
otherwise. This function cannot fail.

@cartouche
@quotation Σημείωση 
Objects that are immortal in one CPython version are not guaranteed to
be immortal in another.
@end quotation
@end cartouche


Added in version 3.14.

@end deffn

@geindex PyUnstable_TryIncRef (C function)
@anchor{c-api/object c PyUnstable_TryIncRef}@anchor{1aea}
@deffn {C Συνάρτηση} int PyUnstable_TryIncRef (PyObject *obj)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Increments the reference count of `obj' if it is not zero.  Returns @code{1}
if the object’s reference count was successfully incremented. Otherwise,
this function returns @code{0}.

@ref{1aeb,,PyUnstable_EnableTryIncRef()} must have been called
earlier on `obj' or this function may spuriously return @code{0} in the
@ref{198,,free-threaded build}.

This function is logically equivalent to the following C code, except that
it behaves atomically in the @ref{198,,free-threaded build}:

@example
if (Py_REFCNT(op) > 0) @{
   Py_INCREF(op);
   return 1;
@}
return 0;
@end example

This is intended as a building block for managing weak references
without the overhead of a Python @ref{55f1,,weak reference object}.

Typically, correct use of this function requires support from `obj'’s
deallocator (@ref{51d3,,tp_dealloc}).
For example, the following sketch could be adapted to implement a
«weakmap» that works like a @ref{1b45,,WeakValueDictionary}
for a specific type:

@example
PyMutex mutex;

PyObject *
add_entry(weakmap_key_type *key, PyObject *value)
@{
    PyUnstable_EnableTryIncRef(value);
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_add_entry(weakmap, key, value);
    PyMutex_Unlock(&mutex);
    Py_RETURN_NONE;
@}

PyObject *
get_value(weakmap_key_type *key)
@{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    PyObject *result = weakmap_find(weakmap, key);
    if (PyUnstable_TryIncRef(result)) @{
        // `result` is safe to use
        PyMutex_Unlock(&mutex);
        return result;
    @}
    // if we get here, `result` is starting to be garbage-collected,
    // but has not been removed from the weakmap yet
    PyMutex_Unlock(&mutex);
    return NULL;
@}

// tp_dealloc function for weakmap values
void
value_dealloc(PyObject *value)
@{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_remove_value(weakmap, value);

    ...
    PyMutex_Unlock(&mutex);
@}
@end example


Added in version 3.14.

@end deffn

@geindex PyUnstable_EnableTryIncRef (C function)
@anchor{c-api/object c PyUnstable_EnableTryIncRef}@anchor{1aeb}
@deffn {C Συνάρτηση} void PyUnstable_EnableTryIncRef (PyObject *obj)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Enables subsequent uses of @ref{1aea,,PyUnstable_TryIncRef()} on `obj'.  The
caller must hold a @ref{7da,,strong reference} to `obj' when calling this.


Added in version 3.14.

@end deffn

@geindex PyUnstable_Object_IsUniquelyReferenced (C function)
@anchor{c-api/object c PyUnstable_Object_IsUniquelyReferenced}@anchor{5f2}
@deffn {C Συνάρτηση} int PyUnstable_Object_IsUniquelyReferenced (PyObject *op)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Determine if `op' only has one reference.

On GIL-enabled builds, this function is equivalent to
@ref{54b,,Py_REFCNT}(@ref{5f2,,op}) == 1.

On a @ref{198,,free-threaded build}, this checks if `op'’s
@ref{2c5,,reference count} is equal to one and additionally checks if `op'
is only used by this thread. @ref{54b,,Py_REFCNT}(@ref{5f2,,op}) == 1 is `not'
thread-safe on free-threaded builds; prefer this function.

The caller must hold an @ref{1a1,,attached thread state}, despite the fact
that this function doesn’t call into the Python interpreter. This function
cannot fail.


Added in version 3.14.

@end deffn

@geindex PyUnstable_SetImmortal (C function)
@anchor{c-api/object c PyUnstable_SetImmortal}@anchor{397}
@deffn {C Συνάρτηση} int PyUnstable_SetImmortal (PyObject *op)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Marks the object `op' @ref{398,,immortal}. The argument should be uniquely referenced by
the calling thread. This is intended to be used for reducing reference counting contention
in the @ref{198,,free-threaded build} for objects which are shared across threads.

This is a one-way process: objects can only be made immortal; they cannot be
made mortal once again. Immortal objects do not participate in reference counting
and will never be garbage collected. If the object is GC-tracked, it is untracked.

This function is intended to be used soon after `op' is created, by the code that
creates it, such as in the object’s @ref{981,,tp_new} slot.
Returns 1 if the object was made immortal and returns 0 if it was not.
This function cannot fail.


Added in version 3.15.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Call Protocol,Number Protocol,Object Protocol,Abstract Objects Layer
@anchor{c-api/call doc}@anchor{55f2}@anchor{c-api/call call}@anchor{985}@anchor{c-api/call call-protocol}@anchor{55f3}@anchor{c-api/call translation-repo}@anchor{55f4}
@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{55f5}
@subsubsection The `tp_call' Protocol


Instances of classes that set @ref{962,,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{981,,tp_new} and @ref{983,,tp_init}
also pass arguments this way.

To call an object, use @ref{82f,,PyObject_Call()} or another
@ref{55f6,,call API}.

@node The Vectorcall Protocol,Object Calling API,The tp_call Protocol,Call Protocol
@anchor{c-api/call the-vectorcall-protocol}@anchor{55f7}@anchor{c-api/call vectorcall}@anchor{95b}
@subsubsection The Vectorcall Protocol



Added in 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{82f,,PyObject_Call()}).
Therefore, a class supporting vectorcall must also implement
@ref{962,,tp_call}.
Moreover, the callable must behave the same
regardless of which protocol is used.
The recommended way to achieve this is by setting
@code{tp_call} to @ref{95f,,PyVectorcall_Call()}.
This bears repeating:

@cartouche
@quotation Προειδοποίηση 
A class supporting vectorcall `must' also implement
@ref{962,,tp_call} with the same semantics.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.12: The @ref{95d,,Py_TPFLAGS_HAVE_VECTORCALL} flag is now removed from a class
when the class’s @ref{961,,__call__()} method is reassigned.
(This internally sets @ref{962,,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{5fb,,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{95d,,Py_TPFLAGS_HAVE_VECTORCALL} flag and setting
@ref{55f8,,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{960}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*vectorcallfunc)(@ref{19b,,PyObject} *callable, @ref{19b,,PyObject} *const *args, size_t nargsf, @ref{19b,,PyObject} *kwnames)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{965,,PY_VECTORCALL_ARGUMENTS_OFFSET} flag.
To get the actual number of positional arguments from `nargsf',
use @ref{95e,,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{965}
@deffn {C Μακροεντολή} PY_VECTORCALL_ARGUMENTS_OFFSET
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{964,,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{965,,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.


Added in version 3.8.

@end deffn

To call an object that implements vectorcall, use a @ref{55f6,,call API}
function as with any other callable.
@ref{963,,PyObject_Vectorcall()} will usually be most efficient.

@menu
* Recursion Control: Recursion Control<2>. 
* Vectorcall Support API:: 

@end menu

@node Recursion Control<2>,Vectorcall Support API,,The Vectorcall Protocol
@anchor{c-api/call recursion-control}@anchor{55f9}
@subsubsection Recursion Control


When using `tp_call', callees do not need to worry about
@ref{5549,,recursion}: CPython uses
@ref{5fe,,Py_EnterRecursiveCall()} and @ref{d3c,,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,,Recursion Control<2>,The Vectorcall Protocol
@anchor{c-api/call vectorcall-support-api}@anchor{55fa}
@subsubsection Vectorcall Support API


@geindex PyVectorcall_NARGS (C function)
@anchor{c-api/call c PyVectorcall_NARGS}@anchor{95e}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyVectorcall_NARGS (size_t nargsf)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.


Added in version 3.8.

@end deffn

@geindex PyVectorcall_Function (C function)
@anchor{c-api/call c PyVectorcall_Function}@anchor{55fb}
@deffn {C Συνάρτηση} @ref{960,,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}.


Added in version 3.9.

@end deffn

@geindex PyVectorcall_Call (C function)
@anchor{c-api/call c PyVectorcall_Call}@anchor{95f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyVectorcall_Call (PyObject *callable, PyObject *tuple, PyObject *dict)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
Call `callable'’s @ref{960,,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{962,,tp_call} slot or be used in an implementation of @code{tp_call}.
It does not check the @ref{95d,,Py_TPFLAGS_HAVE_VECTORCALL} flag
and it does not fall back to @code{tp_call}.


Added in version 3.8.

@end deffn

@node Object Calling API,Call Support API,The Vectorcall Protocol,Call Protocol
@anchor{c-api/call capi-call}@anchor{55f6}@anchor{c-api/call object-calling-api}@anchor{55fc}
@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

Function

@tab

callable

@tab

args

@tab

kwargs

@item

@ref{82f,,PyObject_Call()}

@tab

@code{PyObject *}

@tab

tuple

@tab

dict/@code{NULL}

@item

@ref{82e,,PyObject_CallNoArgs()}

@tab

@code{PyObject *}

@tab

—

@tab

—

@item

@ref{d40,,PyObject_CallOneArg()}

@tab

@code{PyObject *}

@tab

1 object

@tab

—

@item

@ref{51c2,,PyObject_CallObject()}

@tab

@code{PyObject *}

@tab

tuple/@code{NULL}

@tab

—

@item

@ref{831,,PyObject_CallFunction()}

@tab

@code{PyObject *}

@tab

format

@tab

—

@item

@ref{3b6,,PyObject_CallMethod()}

@tab

obj + @code{char*}

@tab

format

@tab

—

@item

@ref{53c1,,PyObject_CallFunctionObjArgs()}

@tab

@code{PyObject *}

@tab

variadic

@tab

—

@item

@ref{1fce,,PyObject_CallMethodObjArgs()}

@tab

obj + name

@tab

variadic

@tab

—

@item

@ref{55fd,,PyObject_CallMethodNoArgs()}

@tab

obj + name

@tab

—

@tab

—

@item

@ref{55fe,,PyObject_CallMethodOneArg()}

@tab

obj + name

@tab

1 object

@tab

—

@item

@ref{963,,PyObject_Vectorcall()}

@tab

@code{PyObject *}

@tab

vectorcall

@tab

vectorcall

@item

@ref{55ff,,PyObject_VectorcallDict()}

@tab

@code{PyObject *}

@tab

vectorcall

@tab

dict/@code{NULL}

@item

@ref{964,,PyObject_VectorcallMethod()}

@tab

arg + name

@tab

vectorcall

@tab

vectorcall

@end multitable


@geindex PyObject_Call (C function)
@anchor{c-api/call c PyObject_Call}@anchor{82f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_Call (PyObject *callable, PyObject *args, PyObject *kwargs)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Call a callable Python object `callable', with arguments given by the
tuple `args', and named arguments given by the dictionary `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.

This is the equivalent of the Python expression:
@code{callable(*args, **kwargs)}.
@end deffn

@geindex PyObject_CallNoArgs (C function)
@anchor{c-api/call c PyObject_CallNoArgs}@anchor{82e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_CallNoArgs (PyObject *callable)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.


Added in version 3.9.

@end deffn

@geindex PyObject_CallOneArg (C function)
@anchor{c-api/call c PyObject_CallOneArg}@anchor{d40}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_CallOneArg (PyObject *callable, PyObject *arg)
`Επιστρεφόμενη τιμή: New reference.'
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.


Added in version 3.9.

@end deffn

@geindex PyObject_CallObject (C function)
@anchor{c-api/call c PyObject_CallObject}@anchor{51c2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_CallObject (PyObject *callable, PyObject *args)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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.

This is the equivalent of the Python expression: @code{callable(*args)}.
@end deffn

@geindex PyObject_CallFunction (C function)
@anchor{c-api/call c PyObject_CallFunction}@anchor{831}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_CallFunction (PyObject *callable, const char *format, ...)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Call a callable Python object `callable', with a variable number of C arguments.
The C arguments are described using a @ref{5ee,,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.

This is the equivalent of the Python expression: @code{callable(*args)}.

Note that if you only pass @ref{19b,,PyObject}* args,
@ref{53c1,,PyObject_CallFunctionObjArgs()} is a faster alternative.


Άλλαξε στην έκδοση 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{3b6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_CallMethod (PyObject *obj, const char *name, const char *format, ...)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Call the method named `name' of object `obj' with a variable number of C
arguments.  The C arguments are described by a @ref{5ee,,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{19b,,PyObject}* args,
@ref{1fce,,PyObject_CallMethodObjArgs()} is a faster alternative.


Άλλαξε στην έκδοση 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{53c1}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_CallFunctionObjArgs (PyObject *callable, ...)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Call a callable Python object `callable', with a variable number of
@ref{19b,,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{1fce}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_CallMethodObjArgs (PyObject *obj, PyObject *name, ...)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{19b,,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{55fd}
@deffn {C Συνάρτηση} @ref{19b,,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.


Added in version 3.9.

@end deffn

@geindex PyObject_CallMethodOneArg (C function)
@anchor{c-api/call c PyObject_CallMethodOneArg}@anchor{55fe}
@deffn {C Συνάρτηση} @ref{19b,,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.


Added in version 3.9.

@end deffn

@geindex _PyObject_Vectorcall (C function)

@geindex PyObject_Vectorcall (C function)
@anchor{c-api/call c _PyObject_Vectorcall}@anchor{5600}@anchor{c-api/call c PyObject_Vectorcall}@anchor{963}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_Vectorcall (PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
Call a callable Python object `callable'.
The arguments are the same as for @ref{960,,vectorcallfunc}.
If `callable' supports @ref{95b,,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.


Added in version 3.8: as @code{_PyObject_Vectorcall}



Άλλαξε στην έκδοση 3.9: Renamed to the current name, without the leading underscore.
The old provisional name is @ref{1a7,,soft deprecated}.

@end deffn

@geindex PyObject_VectorcallDict (C function)
@anchor{c-api/call c PyObject_VectorcallDict}@anchor{55ff}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_VectorcallDict (PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

Call `callable' with positional arguments passed exactly as in the @ref{95b,,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.


Added in version 3.9.

@end deffn

@geindex PyObject_VectorcallMethod (C function)
@anchor{c-api/call c PyObject_VectorcallMethod}@anchor{964}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_VectorcallMethod (PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{965,,PY_VECTORCALL_ARGUMENTS_OFFSET} if the value of @code{args[0]} may
temporarily be changed. Keyword arguments can be passed just like in
@ref{963,,PyObject_Vectorcall()}.

If the object has the @ref{547c,,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.


Added in version 3.9.

@end deffn

@node Call Support API,,Object Calling API,Call Protocol
@anchor{c-api/call call-support-api}@anchor{5601}
@subsubsection Call Support API


@geindex PyCallable_Check (C function)
@anchor{c-api/call c PyCallable_Check}@anchor{52b7}
@deffn {C Συνάρτηση} int PyCallable_Check (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Determine if the object `o' is callable.  Return @code{1} if the object is callable
and @code{0} otherwise.  This function always succeeds.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Number Protocol,Sequence Protocol,Call Protocol,Abstract Objects Layer
@anchor{c-api/number doc}@anchor{5602}@anchor{c-api/number number}@anchor{5603}@anchor{c-api/number number-protocol}@anchor{5604}@anchor{c-api/number translation-repo}@anchor{5605}
@subsection Number Protocol


@geindex PyNumber_Check (C function)
@anchor{c-api/number c PyNumber_Check}@anchor{e2b}
@deffn {C Συνάρτηση} int PyNumber_Check (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Returns @code{1} if the object `o' provides numeric protocols, and false otherwise.
This function always succeeds.


Άλλαξε στην έκδοση 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{539d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Add (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53b7}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Subtract (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53b0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Multiply (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{1264}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_MatrixMultiply (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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}.


Added in version 3.5.

@end deffn

@geindex PyNumber_FloorDivide (C function)
@anchor{c-api/number c PyNumber_FloorDivide}@anchor{53a1}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_FloorDivide (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53b8}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_TrueDivide (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53b5}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Remainder (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53a0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Divmod (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex built-in function;divmod

See the built-in function @ref{d6a,,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{53b4}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Power (PyObject *o1, PyObject *o2, PyObject *o3)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex built-in function;pow

See the built-in function @ref{441,,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{5606,,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{53b1}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Negative (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53b3}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Positive (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{539c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Absolute (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53ae}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Invert (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53af}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Lshift (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53b6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Rshift (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{539e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_And (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53b9}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Xor (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53b2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Or (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53a2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlaceAdd (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53ab}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlaceSubtract (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53a6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlaceMultiply (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{1265}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlaceMatrixMultiply (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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}.


Added in version 3.5.

@end deffn

@geindex PyNumber_InPlaceFloorDivide (C function)
@anchor{c-api/number c PyNumber_InPlaceFloorDivide}@anchor{53a4}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlaceFloorDivide (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53ac}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlaceTrueDivide (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53a9}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlaceRemainder (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53a8}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlacePower (PyObject *o1, PyObject *o2, PyObject *o3)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex built-in function;pow

See the built-in function @ref{441,,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{5606,,Py_None}, or an in-place variant of
@code{pow(o1, o2, o3)} otherwise. If `o3' is to be ignored, pass @code{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{53a5}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlaceLshift (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53aa}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlaceRshift (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53a3}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlaceAnd (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53ad}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlaceXor (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53a7}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_InPlaceOr (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{e2c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Long (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{e2d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Float (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{c69}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_Index (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Returns the `o' converted to a Python int on success or @code{NULL} with a
@ref{291,,TypeError} exception raised on failure.


Άλλαξε στην έκδοση 3.10: The result always has exact type @ref{326,,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{1d70}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyNumber_ToBase (PyObject *n, int base)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{c69,,PyNumber_Index()} first.
@end deffn

@geindex PyNumber_AsSsize_t (C function)
@anchor{c-api/number c PyNumber_AsSsize_t}@anchor{539f}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyNumber_AsSsize_t (PyObject *o, PyObject *exc)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Returns `o' converted to a @ref{e24,,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{e24,,Py_ssize_t} value would raise an @ref{c57,,OverflowError}, then the
`exc' argument is the type of exception that will be raised (usually
@ref{18d7,,IndexError} or @code{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{d52}
@deffn {C Συνάρτηση} int PyIndex_Check (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Sequence Protocol,Mapping Protocol,Number Protocol,Abstract Objects Layer
@anchor{c-api/sequence doc}@anchor{5607}@anchor{c-api/sequence sequence}@anchor{5608}@anchor{c-api/sequence sequence-protocol}@anchor{5609}@anchor{c-api/sequence translation-repo}@anchor{560a}
@subsection Sequence Protocol


@geindex PySequence_Check (C function)
@anchor{c-api/sequence c PySequence_Check}@anchor{53d7}
@deffn {C Συνάρτηση} int PySequence_Check (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό 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{787,,__getitem__()}
method, unless they are @ref{188,,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{2020}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PySequence_Size (PyObject *o)
@anchor{c-api/sequence c PySequence_Length}@anchor{53df}
@deffnx {C Συνάρτηση} @ref{e24,,Py_ssize_t} PySequence_Length (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό 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{53d8}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySequence_Concat (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53e1}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySequence_Repeat (PyObject *o, Py_ssize_t count)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53dc}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySequence_InPlaceConcat (PyObject *o1, PyObject *o2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53dd}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySequence_InPlaceRepeat (PyObject *o, Py_ssize_t count)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{2021}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySequence_GetItem (PyObject *o, Py_ssize_t i)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53db}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySequence_GetSlice (PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{2022}
@deffn {C Συνάρτηση} int PySequence_SetItem (PyObject *o, Py_ssize_t i, PyObject *v)
` Μέρος του @ref{95c,,Σταθερό 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{2023,,PySequence_DelItem()}.
@end deffn

@geindex PySequence_DelItem (C function)
@anchor{c-api/sequence c PySequence_DelItem}@anchor{2023}
@deffn {C Συνάρτηση} int PySequence_DelItem (PyObject *o, Py_ssize_t i)
` Μέρος του @ref{95c,,Σταθερό 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{53e2}
@deffn {C Συνάρτηση} int PySequence_SetSlice (PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
` Μέρος του @ref{95c,,Σταθερό 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{53da}
@deffn {C Συνάρτηση} int PySequence_DelSlice (PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
` Μέρος του @ref{95c,,Σταθερό 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{53d9}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PySequence_Count (PyObject *o, PyObject *value)
` Μέρος του @ref{95c,,Σταθερό 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{605}
@deffn {C Συνάρτηση} int PySequence_Contains (PyObject *o, PyObject *value)
` Μέρος του @ref{95c,,Σταθερό 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_In (C function)
@anchor{c-api/sequence c PySequence_In}@anchor{604}
@deffn {C Συνάρτηση} int PySequence_In (PyObject *o, PyObject *value)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Alias for @ref{605,,PySequence_Contains()}.


@ref{1a7,,Soft deprecated} since version 3.14: The function should no longer be used to write new code.

@end deffn

@geindex PySequence_Index (C function)
@anchor{c-api/sequence c PySequence_Index}@anchor{53de}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PySequence_Index (PyObject *o, PyObject *value)
` Μέρος του @ref{95c,,Σταθερό 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{53e0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySequence_List (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53e3}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySequence_Tuple (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{1ac6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySequence_Fast (PyObject *o, const char *m)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{291,,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{5580,,PyTupleObject} or a @ref{2929,,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{5f6}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PySequence_Fast_GET_SIZE (PyObject *o)

Returns the length of `o', assuming that `o' was returned by
@ref{1ac6,,PySequence_Fast()} and that `o' is not @code{NULL}.  The size can also be
retrieved by calling @ref{2020,,PySequence_Size()} on `o', but
@ref{5f6,,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{5f7}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySequence_Fast_GET_ITEM (PyObject *o, Py_ssize_t i)
`Επιστρεφόμενη τιμή: Borrowed reference.'
Return the `i'th element of `o', assuming that `o' was returned by
@ref{1ac6,,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{5f8}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} **PySequence_Fast_ITEMS (PyObject *o)

Return the underlying array of PyObject pointers.  Assumes that `o' was returned
by @ref{1ac6,,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{560b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySequence_ITEM (PyObject *o, Py_ssize_t i)
`Επιστρεφόμενη τιμή: New reference.'
Return the `i'th element of `o' or @code{NULL} on failure. Faster form of
@ref{2021,,PySequence_GetItem()} but without checking that
@ref{53d7,,PySequence_Check()} on `o' is true and without adjustment for negative
indices.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Mapping Protocol,Iterator Protocol,Sequence Protocol,Abstract Objects Layer
@anchor{c-api/mapping doc}@anchor{560c}@anchor{c-api/mapping mapping}@anchor{560d}@anchor{c-api/mapping mapping-protocol}@anchor{560e}@anchor{c-api/mapping translation-repo}@anchor{560f}
@subsection Mapping Protocol


See also @ref{7e2,,PyObject_GetItem()}, @ref{525f,,PyObject_SetItem()} and
@ref{53c2,,PyObject_DelItem()}.

@geindex PyMapping_Check (C function)
@anchor{c-api/mapping c PyMapping_Check}@anchor{5383}
@deffn {C Συνάρτηση} int PyMapping_Check (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό 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{787,,__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{2024}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyMapping_Size (PyObject *o)
@anchor{c-api/mapping c PyMapping_Length}@anchor{5384}
@deffnx {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyMapping_Length (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex built-in function;len

Returns the number of keys in object `o' on success, and @code{-1} on failure.
This is equivalent to the Python expression @code{len(o)}.
@end deffn

@geindex PyMapping_GetItemString (C function)
@anchor{c-api/mapping c PyMapping_GetItemString}@anchor{7e3}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMapping_GetItemString (PyObject *o, const char *key)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is the same as @ref{7e2,,PyObject_GetItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.
@end deffn

@geindex PyMapping_GetOptionalItem (C function)
@anchor{c-api/mapping c PyMapping_GetOptionalItem}@anchor{7e0}
@deffn {C Συνάρτηση} int PyMapping_GetOptionalItem (PyObject *obj, PyObject *key, PyObject **result)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Variant of @ref{7e2,,PyObject_GetItem()} which doesn’t raise
@ref{7df,,KeyError} if the key is not found.

If the key is found, return @code{1} and set `*result' to a new
@ref{7da,,strong reference} to the corresponding value.
If the key is not found, return @code{0} and set `*result' to @code{NULL};
the @ref{7df,,KeyError} is silenced.
If an error other than @code{KeyError} is raised, return @code{-1} and
set `*result' to @code{NULL}.


Added in version 3.13.

@end deffn

@geindex PyMapping_GetOptionalItemString (C function)
@anchor{c-api/mapping c PyMapping_GetOptionalItemString}@anchor{7e1}
@deffn {C Συνάρτηση} int PyMapping_GetOptionalItemString (PyObject *obj, const char *key, PyObject **result)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
This is the same as @ref{7e0,,PyMapping_GetOptionalItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.


Added in version 3.13.

@end deffn

@geindex PyMapping_SetItemString (C function)
@anchor{c-api/mapping c PyMapping_SetItemString}@anchor{5385}
@deffn {C Συνάρτηση} int PyMapping_SetItemString (PyObject *o, const char *key, PyObject *v)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is the same as @ref{525f,,PyObject_SetItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.
@end deffn

@geindex PyMapping_DelItem (C function)
@anchor{c-api/mapping c PyMapping_DelItem}@anchor{5610}
@deffn {C Συνάρτηση} int PyMapping_DelItem (PyObject *o, PyObject *key)

This is an alias of @ref{53c2,,PyObject_DelItem()}.
@end deffn

@geindex PyMapping_DelItemString (C function)
@anchor{c-api/mapping c PyMapping_DelItemString}@anchor{5611}
@deffn {C Συνάρτηση} int PyMapping_DelItemString (PyObject *o, const char *key)

This is the same as @ref{53c2,,PyObject_DelItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.
@end deffn

@geindex PyMapping_HasKeyWithError (C function)
@anchor{c-api/mapping c PyMapping_HasKeyWithError}@anchor{813}
@deffn {C Συνάρτηση} int PyMapping_HasKeyWithError (PyObject *o, PyObject *key)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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}.


Added in version 3.13.

@end deffn

@geindex PyMapping_HasKeyStringWithError (C function)
@anchor{c-api/mapping c PyMapping_HasKeyStringWithError}@anchor{815}
@deffn {C Συνάρτηση} int PyMapping_HasKeyStringWithError (PyObject *o, const char *key)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
This is the same as @ref{813,,PyMapping_HasKeyWithError()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.


Added in version 3.13.

@end deffn

@geindex PyMapping_HasKey (C function)
@anchor{c-api/mapping c PyMapping_HasKey}@anchor{814}
@deffn {C Συνάρτηση} int PyMapping_HasKey (PyObject *o, PyObject *key)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
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}.
This function always succeeds.

@cartouche
@quotation Σημείωση 
Exceptions which occur when this calls the @ref{787,,__getitem__()}
method are silently ignored.
For proper error handling, use @ref{813,,PyMapping_HasKeyWithError()},
@ref{7e0,,PyMapping_GetOptionalItem()} or @ref{7e2,,PyObject_GetItem()} instead.
@end quotation
@end cartouche
@end deffn

@geindex PyMapping_HasKeyString (C function)
@anchor{c-api/mapping c PyMapping_HasKeyString}@anchor{816}
@deffn {C Συνάρτηση} int PyMapping_HasKeyString (PyObject *o, const char *key)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is the same as @ref{814,,PyMapping_HasKey()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.

@cartouche
@quotation Σημείωση 
Exceptions that occur when this calls the @ref{787,,__getitem__()}
method or while creating the temporary @ref{1df,,str}
object are silently ignored.
For proper error handling, use @ref{815,,PyMapping_HasKeyStringWithError()},
@ref{7e1,,PyMapping_GetOptionalItemString()} or
@ref{7e3,,PyMapping_GetItemString()} instead.
@end quotation
@end cartouche
@end deffn

@geindex PyMapping_Keys (C function)
@anchor{c-api/mapping c PyMapping_Keys}@anchor{f7a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMapping_Keys (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
On success, return a list of the keys in object `o'.  On failure, return
@code{NULL}.


Άλλαξε στην έκδοση 3.7: Previously, the function returned a list or a tuple.

@end deffn

@geindex PyMapping_Values (C function)
@anchor{c-api/mapping c PyMapping_Values}@anchor{f7b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMapping_Values (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
On success, return a list of the values in object `o'.  On failure, return
@code{NULL}.


Άλλαξε στην έκδοση 3.7: Previously, the function returned a list or a tuple.

@end deffn

@geindex PyMapping_Items (C function)
@anchor{c-api/mapping c PyMapping_Items}@anchor{f7c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMapping_Items (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
On success, return a list of the items in object `o', where each item is a
tuple containing a key-value pair.  On failure, return @code{NULL}.


Άλλαξε στην έκδοση 3.7: Previously, the function returned a list or a tuple.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Iterator Protocol,Buffer Protocol,Mapping Protocol,Abstract Objects Layer
@anchor{c-api/iter doc}@anchor{5612}@anchor{c-api/iter iterator}@anchor{5613}@anchor{c-api/iter iterator-protocol}@anchor{5614}@anchor{c-api/iter translation-repo}@anchor{5615}
@subsection Iterator Protocol


There are two functions specifically for working with iterators.

@geindex PyIter_Check (C function)
@anchor{c-api/iter c PyIter_Check}@anchor{1ea8}
@deffn {C Συνάρτηση} int PyIter_Check (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.8.'
Return non-zero if the object `o' can be safely passed to
@ref{5c5,,PyIter_NextItem()} and @code{0} otherwise.
This function always succeeds.
@end deffn

@geindex PyAIter_Check (C function)
@anchor{c-api/iter c PyAIter_Check}@anchor{5288}
@deffn {C Συνάρτηση} int PyAIter_Check (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Return non-zero if the object `o' provides the @code{AsyncIterator}
protocol, and @code{0} otherwise.  This function always succeeds.


Added in version 3.10.

@end deffn

@geindex PyIter_NextItem (C function)
@anchor{c-api/iter c PyIter_NextItem}@anchor{5c5}
@deffn {C Συνάρτηση} int PyIter_NextItem (PyObject *iter, PyObject **item)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
Return @code{1} and set `item' to a @ref{7da,,strong reference} of the
next value of the iterator `iter' on success.
Return @code{0} and set `item' to @code{NULL} if there are no remaining values.
Return @code{-1}, set `item' to @code{NULL} and set an exception on error.


Added in version 3.14.

@end deffn

@geindex PyIter_Next (C function)
@anchor{c-api/iter c PyIter_Next}@anchor{5c6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyIter_Next (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is an older version of @code{PyIter_NextItem()},
which is retained for backwards compatibility.
Prefer @ref{5c5,,PyIter_NextItem()}.

Return the next value from the iterator `o'.  The object must be an iterator
according to @ref{1ea8,,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

@geindex PySendResult (C type)
@anchor{c-api/iter c PySendResult}@anchor{5616}
@deffn {C Τύπος} type PySendResult

The enum value used to represent different results of @ref{c6e,,PyIter_Send()}.


Added in version 3.10.

@end deffn

@geindex PyIter_Send (C function)
@anchor{c-api/iter c PyIter_Send}@anchor{c6e}
@deffn {C Συνάρτηση} @ref{5616,,PySendResult} PyIter_Send (PyObject *iter, PyObject *arg, PyObject **presult)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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 an exception. `presult' is set to @code{NULL}.
@end itemize


Added in version 3.10.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@geindex buffer protocol
@geindex buffer interface;(see buffer protocol)
@geindex buffer object;(see buffer protocol)

@node Buffer Protocol,,Iterator Protocol,Abstract Objects Layer
@anchor{c-api/buffer doc}@anchor{5617}@anchor{c-api/buffer buffer-protocol}@anchor{5618}@anchor{c-api/buffer bufferobjects}@anchor{311}@anchor{c-api/buffer translation-repo}@anchor{5619}
@subsection Buffer Protocol


Certain objects available in Python wrap access to an underlying memory
array or `buffer'.  Such objects include the built-in @ref{1c7,,bytes} and
@ref{1c6,,bytearray}, and some extension types like @ref{6c5,,array.array}.
Third-party libraries may define their own types for special purposes, such
as image processing or numeric analysis.

While each of these types have their own semantics, they share the common
characteristic of being backed by a possibly large memory buffer.  It is
then desirable, in some situations, to access that buffer directly and
without intermediate copying.

Python provides such a facility at the C and Python level in the form of the
@ref{311,,buffer protocol}.  This protocol has two sides:

@geindex PyBufferProcs (C type)


@itemize -

@item 
on the producer side, a type can export a «buffer interface» which allows
objects of that type to expose information about their underlying buffer.
This interface is described in the section @ref{561a,,Buffer Object Structures}; for
Python see @ref{2605,,Εξομοίωση τύπων buffer}.

@item 
on the consumer side, several means are available to obtain a pointer to
the raw underlying data of an object (for example a method parameter). For
Python see @ref{1d2,,memoryview}.
@end itemize

Simple objects such as @ref{1c7,,bytes} and @ref{1c6,,bytearray} expose their
underlying buffer in byte-oriented form.  Other forms are possible; for example,
the elements exposed by an @ref{6c5,,array.array} can be multi-byte values.

An example consumer of the buffer interface is the @ref{1099,,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{1ab9,,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.

There are two ways for a consumer of the buffer interface to acquire a buffer
over a target object:


@itemize *

@item 
call @ref{82c,,PyObject_GetBuffer()} with the right parameters;

@item 
call @ref{3b1,,PyArg_ParseTuple()} (or one of its siblings) with one of the
@code{y*}, @code{w*} or @code{s*} @ref{601,,format codes}.
@end itemize

In both cases, @ref{82d,,PyBuffer_Release()} must be called when the buffer
isn’t needed anymore.  Failure to do so could lead to various issues such as
resource leaks.


Added in version 3.12: The buffer protocol is now accessible in Python, see
@ref{2605,,Εξομοίωση τύπων buffer} and @ref{1d2,,memoryview}.


@menu
* Buffer structure:: 
* Buffer request types:: 
* Complex arrays:: 
* Buffer-related functions:: 

@end menu

@node Buffer structure,Buffer request types,,Buffer Protocol
@anchor{c-api/buffer buffer-structure}@anchor{561b}@anchor{c-api/buffer id1}@anchor{561c}
@subsubsection Buffer structure


Buffer structures (or simply «buffers») are useful as a way to expose the
binary data from another object to the Python programmer.  They can also be
used as a zero-copy slicing mechanism.  Using their ability to reference a
block of memory, it is possible to expose any data to the Python programmer
quite easily.  The memory could be a large, constant array in a C extension,
it could be a raw block of memory for manipulation before passing to an
operating system library, or it could be used to pass around structured data
in its native, in-memory format.

Contrary to most data types exposed by the Python interpreter, buffers
are not @ref{19b,,PyObject} pointers but rather simple C structures.  This
allows them to be created and copied very simply.  When a generic wrapper
around a buffer is needed, a @ref{561d,,memoryview} object
can be created.

For short instructions how to write an exporting object, see
@ref{561a,,Buffer Object Structures}. For obtaining
a buffer, see @ref{82c,,PyObject_GetBuffer()}.

@geindex Py_buffer (C type)
@anchor{c-api/buffer c Py_buffer}@anchor{b3a}
@deffn {C Τύπος} type Py_buffer
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών) από την έκδοση 3.11.'
@geindex Py_buffer.buf (C member)
@anchor{c-api/buffer c Py_buffer buf}@anchor{561e}
@deffn {C Μέλος} 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{561f,,strides}
the value may point to the end of the memory block.

For @ref{287e,,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{5620}
@deffn {C Μέλος} @ref{19b,,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{82d,,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{b43,,PyMemoryView_FromBuffer()} or @ref{b42,,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{5621}
@deffn {C Μέλος} @ref{e24,,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{5296,,PyBUF_SIMPLE} or @ref{1758,,PyBUF_WRITABLE}.
@end deffn

@geindex Py_buffer.readonly (C member)
@anchor{c-api/buffer c Py_buffer readonly}@anchor{5622}
@deffn {C Μέλος} int readonly

An indicator of whether the buffer is read-only. This field is controlled
by the @ref{1758,,PyBUF_WRITABLE} flag.
@end deffn

@geindex Py_buffer.itemsize (C member)
@anchor{c-api/buffer c Py_buffer itemsize}@anchor{5623}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} itemsize

Item size in bytes of a single element. Same as the value of @ref{1f9a,,struct.calcsize()}
called on non-@code{NULL} @ref{5624,,format} values.

Important exception: If a consumer requests a buffer without the
@ref{528e,,PyBUF_FORMAT} flag, @ref{5624,,format} will
be set to  @code{NULL},  but @ref{5623,,itemsize} still has
the value for the original format.

If @ref{5625,,shape} is present, the equality
@code{product(shape) * itemsize == len} still holds and the consumer
can use @ref{5623,,itemsize} to navigate the buffer.

If @ref{5625,,shape} is @code{NULL} as a result of a @ref{5296,,PyBUF_SIMPLE}
or a @ref{1758,,PyBUF_WRITABLE} request, the consumer must disregard
@ref{5623,,itemsize} and assume @code{itemsize == 1}.
@end deffn

@geindex Py_buffer.format (C member)
@anchor{c-api/buffer c Py_buffer format}@anchor{5624}
@deffn {C Μέλος} char *format

A `NULL' terminated string in @ref{de,,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{528e,,PyBUF_FORMAT} flag.
@end deffn

@geindex Py_buffer.ndim (C member)
@anchor{c-api/buffer c Py_buffer ndim}@anchor{5626}
@deffn {C Μέλος} int ndim

The number of dimensions the memory represents as an n-dimensional array.
If it is @code{0}, @ref{561e,,buf} points to a single item representing
a scalar. In this case, @ref{5625,,shape}, @ref{561f,,strides}
and @ref{5627,,suboffsets} MUST be @code{NULL}.
The maximum number of dimensions is given by @ref{5292,,PyBUF_MAX_NDIM}.
@end deffn

@geindex Py_buffer.shape (C member)
@anchor{c-api/buffer c Py_buffer shape}@anchor{5625}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} *shape

An array of @ref{e24,,Py_ssize_t} of length @ref{5626,,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{5621,,len}.

Shape values are restricted to @code{shape[n] >= 0}. The case
@code{shape[n] == 0} requires special attention. See @ref{5628,,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{561f}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} *strides

An array of @ref{e24,,Py_ssize_t} of length @ref{5626,,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{5628,,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{5627}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} *suboffsets

An array of @ref{e24,,Py_ssize_t} of length @ref{5626,,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{5628,,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{5629}
@deffn {C Μέλος} 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{5292}
@deffn {C Μακροεντολή} PyBUF_MAX_NDIM
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
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,Buffer structure,Buffer Protocol
@anchor{c-api/buffer buffer-request-types}@anchor{4d3b}@anchor{c-api/buffer id2}@anchor{562a}
@subsubsection Buffer request types


Buffers are usually obtained by sending a buffer request to an exporting
object via @ref{82c,,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{b3a,,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{562b}
@subsubsection request-independent fields


The following fields are not influenced by `flags' and must always be filled in
with the correct values: @ref{5620,,obj}, @ref{561e,,buf},
@ref{5621,,len}, @ref{5623,,itemsize}, @ref{5626,,ndim}.

@node readonly format,shape strides suboffsets,request-independent fields,Buffer request types
@anchor{c-api/buffer readonly-format}@anchor{562c}
@subsubsection readonly, format


@quotation

@geindex PyBUF_WRITABLE (C macro)
@anchor{c-api/buffer c PyBUF_WRITABLE}@anchor{1758}
@deffn {C Μακροεντολή} PyBUF_WRITABLE
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Controls the @ref{5622,,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{5296,,PyBUF_SIMPLE} | @ref{1758,,PyBUF_WRITABLE}
can be used to request a simple writable buffer.
@end deffn

@geindex PyBUF_WRITEABLE (C macro)
@anchor{c-api/buffer c PyBUF_WRITEABLE}@anchor{562d}
@deffn {C Μακροεντολή} PyBUF_WRITEABLE

This is an alias to @ref{1758,,PyBUF_WRITABLE}.


@ref{1a7,,Soft deprecated} since version 3.13.

@end deffn

@geindex PyBUF_FORMAT (C macro)
@anchor{c-api/buffer c PyBUF_FORMAT}@anchor{528e}
@deffn {C Μακροεντολή} PyBUF_FORMAT
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Controls the @ref{5624,,format} field. If set, this field MUST
be filled in correctly. Otherwise, this field MUST be @code{NULL}.
@end deffn
@end quotation

@ref{1758,,PyBUF_WRITABLE} can be |”d to any of the flags in the next section.
Since @ref{5296,,PyBUF_SIMPLE} is defined as 0, @code{PyBUF_WRITABLE}
can be used as a stand-alone flag to request a simple writable buffer.

@ref{528e,,PyBUF_FORMAT} must be |”d to any of the flags except @ref{5296,,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{562e}
@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{5291}
@deffn {C Μακροεντολή} PyBUF_INDIRECT
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

yes

@tab

if needed

@item

@geindex PyBUF_STRIDES (C macro)
@anchor{c-api/buffer c PyBUF_STRIDES}@anchor{5299}
@deffn {C Μακροεντολή} PyBUF_STRIDES
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

yes

@tab

NULL

@item

@geindex PyBUF_ND (C macro)
@anchor{c-api/buffer c PyBUF_ND}@anchor{5293}
@deffn {C Μακροεντολή} PyBUF_ND
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

NULL

@tab

NULL

@item

@geindex PyBUF_SIMPLE (C macro)
@anchor{c-api/buffer c PyBUF_SIMPLE}@anchor{5296}
@deffn {C Μακροεντολή} PyBUF_SIMPLE
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@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{562f}
@subsubsection contiguity requests


C or Fortran @ref{287e,,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{1759}
@deffn {C Μακροεντολή} PyBUF_C_CONTIGUOUS
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

yes

@tab

NULL

@tab

C

@item

@geindex PyBUF_F_CONTIGUOUS (C macro)
@anchor{c-api/buffer c PyBUF_F_CONTIGUOUS}@anchor{175a}
@deffn {C Μακροεντολή} PyBUF_F_CONTIGUOUS
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

yes

@tab

NULL

@tab

F

@item

@geindex PyBUF_ANY_CONTIGUOUS (C macro)
@anchor{c-api/buffer c PyBUF_ANY_CONTIGUOUS}@anchor{528b}
@deffn {C Μακροεντολή} PyBUF_ANY_CONTIGUOUS
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

yes

@tab

NULL

@tab

C or F

@item

@ref{5293,,PyBUF_ND}

@tab

yes

@tab

NULL

@tab

NULL

@tab

C

@end multitable


@node compound requests,,contiguity requests,Buffer request types
@anchor{c-api/buffer compound-requests}@anchor{5630}
@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{b40,,PyBuffer_IsContiguous()} to determine contiguity.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxx} {xxxxxxxxxx} {xxxxxxxxxxxx} {xxxxxxxxxx} 
@headitem

Request

@tab

shape

@tab

strides

@tab

suboffsets

@tab

contig

@tab

readonly

@tab

format

@item

@geindex PyBUF_FULL (C macro)
@anchor{c-api/buffer c PyBUF_FULL}@anchor{528f}
@deffn {C Μακροεντολή} PyBUF_FULL
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

yes

@tab

if needed

@tab

U

@tab

0

@tab

yes

@item

@geindex PyBUF_FULL_RO (C macro)
@anchor{c-api/buffer c PyBUF_FULL_RO}@anchor{5290}
@deffn {C Μακροεντολή} PyBUF_FULL_RO
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

yes

@tab

if needed

@tab

U

@tab

1 or 0

@tab

yes

@item

@geindex PyBUF_RECORDS (C macro)
@anchor{c-api/buffer c PyBUF_RECORDS}@anchor{5294}
@deffn {C Μακροεντολή} PyBUF_RECORDS
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

yes

@tab

NULL

@tab

U

@tab

0

@tab

yes

@item

@geindex PyBUF_RECORDS_RO (C macro)
@anchor{c-api/buffer c PyBUF_RECORDS_RO}@anchor{5295}
@deffn {C Μακροεντολή} PyBUF_RECORDS_RO
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

yes

@tab

NULL

@tab

U

@tab

1 or 0

@tab

yes

@item

@geindex PyBUF_STRIDED (C macro)
@anchor{c-api/buffer c PyBUF_STRIDED}@anchor{5297}
@deffn {C Μακροεντολή} PyBUF_STRIDED
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

yes

@tab

NULL

@tab

U

@tab

0

@tab

NULL

@item

@geindex PyBUF_STRIDED_RO (C macro)
@anchor{c-api/buffer c PyBUF_STRIDED_RO}@anchor{5298}
@deffn {C Μακροεντολή} PyBUF_STRIDED_RO
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

yes

@tab

NULL

@tab

U

@tab

1 or 0

@tab

NULL

@item

@geindex PyBUF_CONTIG (C macro)
@anchor{c-api/buffer c PyBUF_CONTIG}@anchor{528c}
@deffn {C Μακροεντολή} PyBUF_CONTIG
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@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{528d}
@deffn {C Μακροεντολή} PyBUF_CONTIG_RO
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@end deffn

@tab

yes

@tab

NULL

@tab

NULL

@tab

C

@tab

1 or 0

@tab

NULL

@end multitable


@node Complex arrays,Buffer-related functions,Buffer request types,Buffer Protocol
@anchor{c-api/buffer complex-arrays}@anchor{5628}
@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{5631}
@subsubsection NumPy-style: shape and strides


The logical structure of NumPy-style arrays is defined by @ref{5623,,itemsize},
@ref{5626,,ndim}, @ref{5625,,shape} and @ref{561f,,strides}.

If @code{ndim == 0}, the memory location pointed to by @ref{561e,,buf} is
interpreted as a scalar of size @ref{5623,,itemsize}. In that case,
both @ref{5625,,shape} and @ref{561f,,strides} are @code{NULL}.

If @ref{561f,,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{561e,,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{5632}
@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{561e,,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 Buffer-related functions,,Complex arrays,Buffer Protocol
@anchor{c-api/buffer buffer-related-functions}@anchor{5633}
@subsubsection Buffer-related functions


@geindex PyObject_CheckBuffer (C function)
@anchor{c-api/buffer c PyObject_CheckBuffer}@anchor{82b}
@deffn {C Συνάρτηση} int PyObject_CheckBuffer (PyObject *obj)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{82c,,PyObject_GetBuffer()} will
succeed.  This function always succeeds.
@end deffn

@geindex PyObject_GetBuffer (C function)
@anchor{c-api/buffer c PyObject_GetBuffer}@anchor{82c}
@deffn {C Συνάρτηση} int PyObject_GetBuffer (PyObject *exporter, Py_buffer *view, int flags)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{1998,,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{561a,,Buffer Object Structures}).

Successful calls to @ref{82c,,PyObject_GetBuffer()} must be paired with calls
to @ref{82d,,PyBuffer_Release()}, similar to @code{malloc()} and @code{free()}.
Thus, after the consumer is done with the buffer, @code{PyBuffer_Release()}
must be called exactly once.
@end deffn

@geindex PyBuffer_Release (C function)
@anchor{c-api/buffer c PyBuffer_Release}@anchor{82d}
@deffn {C Συνάρτηση} void PyBuffer_Release (Py_buffer *view)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Release the buffer `view' and release the @ref{7da,,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{82c,,PyObject_GetBuffer()}.
@end deffn

@geindex PyBuffer_SizeFromFormat (C function)
@anchor{c-api/buffer c PyBuffer_SizeFromFormat}@anchor{b3c}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyBuffer_SizeFromFormat (const char *format)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Return the implied @ref{5623,,itemsize} from @ref{5624,,format}.
On error, raise an exception and return -1.


Added in version 3.9.

@end deffn

@geindex PyBuffer_IsContiguous (C function)
@anchor{c-api/buffer c PyBuffer_IsContiguous}@anchor{b40}
@deffn {C Συνάρτηση} int PyBuffer_IsContiguous (const Py_buffer *view, char order)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{287e,,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{b3b}
@deffn {C Συνάρτηση} void *PyBuffer_GetPointer (const Py_buffer *view, const Py_ssize_t *indices)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{b3e}
@deffn {C Συνάρτηση} int PyBuffer_FromContiguous (const Py_buffer *view, const void *buf, Py_ssize_t len, char order)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Copy contiguous `len' bytes from `buf' to `view'.
`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.
@end deffn

@geindex PyBuffer_ToContiguous (C function)
@anchor{c-api/buffer c PyBuffer_ToContiguous}@anchor{b3d}
@deffn {C Συνάρτηση} int PyBuffer_ToContiguous (void *buf, const Py_buffer *src, Py_ssize_t len, char order)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{b3f}
@deffn {C Συνάρτηση} int PyObject_CopyData (PyObject *dest, PyObject *src)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{b41}
@deffn {C Συνάρτηση} void PyBuffer_FillContiguousStrides (int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Fill the `strides' array with byte-strides of a @ref{287e,,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{b42}
@deffn {C Συνάρτηση} int PyBuffer_FillInfo (Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{1758,,PyBUF_WRITABLE} is set in `flags'.

On success, set @code{view->obj} to a new reference to `exporter' and
return 0. Otherwise, raise @ref{1998,,BufferError}, set
@code{view->obj} to @code{NULL} and return @code{-1};

If this function is used as part of a @ref{561a,,getbufferproc},
`exporter' MUST be set to the exporting object and `flags' must be passed
unmodified. Otherwise, `exporter' MUST be @code{NULL}.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Concrete Objects Layer,Interpreter initialization and finalization,Abstract Objects Layer,Python/C API reference manual
@anchor{c-api/concrete doc}@anchor{5634}@anchor{c-api/concrete concrete}@anchor{5635}@anchor{c-api/concrete concrete-objects-layer}@anchor{5636}@anchor{c-api/concrete translation-repo}@anchor{5637}
@section Concrete Objects Layer


The functions in this chapter are specific to certain Python object types.
Passing them an object of the wrong type is not a good idea; if you receive an
object from a Python program and you are not sure that it has the right type,
you must perform a type check first; for example, to check that an object is a
dictionary, use @ref{5638,,PyDict_Check()}.  The chapter is structured like the
«family tree» of Python object types.

@cartouche
@quotation Προειδοποίηση 
While the functions described in this chapter carefully check the type of the
objects which are passed in, many of them do not check for @code{NULL} being passed
instead of a valid object.  Allowing @code{NULL} to be passed in can cause memory
access violations and immediate termination of the interpreter.
@end quotation
@end cartouche

@menu
* Fundamental Objects:: 
* Numeric Objects:: 
* Sequence Objects:: 
* Container Objects:: 
* Function Objects: Function Objects<2>. 
* Other Objects:: 
* C API for extension modules:: 

@end menu

@node Fundamental Objects,Numeric Objects,,Concrete Objects Layer
@anchor{c-api/concrete fundamental}@anchor{5639}@anchor{c-api/concrete fundamental-objects}@anchor{563a}
@subsection Fundamental Objects


This section describes Python type objects and the singleton object @code{None}.

@menu
* Type Objects:: 
* The None Object:: 

@end menu

@node Type Objects,The None Object,,Fundamental Objects
@anchor{c-api/type doc}@anchor{563b}@anchor{c-api/type type-objects}@anchor{563c}@anchor{c-api/type typeobjects}@anchor{563d}
@subsubsection Type Objects


@geindex object;type

@geindex PyTypeObject (C type)
@anchor{c-api/type c PyTypeObject}@anchor{e6b}
@deffn {C Τύπος} type PyTypeObject
` Μέρος του @ref{95c,,Σταθερό ABI} (ως μια αδιαφανής κατασκευή).'
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{958}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyType_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is the type object for type objects; it is the same object as
@ref{186,,type} in the Python layer.
@end deffn

@geindex PyType_Check (C function)
@anchor{c-api/type c PyType_Check}@anchor{1f79}
@deffn {C Συνάρτηση} 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{1f7a}
@deffn {C Συνάρτηση} 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{5418}
@deffn {C Συνάρτηση} unsigned int PyType_ClearCache ()
` Μέρος του @ref{95c,,Σταθερό 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{1f31}
@deffn {C Συνάρτηση} unsigned long PyType_GetFlags (PyTypeObject *type)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the @ref{1e68,,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
@code{tp_flags} itself is not part of the @ref{829,,limited API}.


Added in version 3.2.



Άλλαξε στην έκδοση 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{1c91}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_GetDict (PyTypeObject *type)

Return the type object’s internal namespace, which is otherwise only
exposed via a read-only proxy (@ref{101b,,cls.__dict__}).
This is a
replacement for accessing @ref{1c92,,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{3b7,,PyObject_GetAttr()}) isn’t adequate.

Extension modules should continue to use @code{tp_dict},
directly or indirectly, when setting up their own types.


Added in version 3.12.

@end deffn

@geindex PyType_Modified (C function)
@anchor{c-api/type c PyType_Modified}@anchor{1d77}
@deffn {C Συνάρτηση} void PyType_Modified (PyTypeObject *type)
` Μέρος του @ref{95c,,Σταθερό 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{96a}
@deffn {C Συνάρτηση} 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{96b,,PyType_Watch()}. In case of
error (e.g. no more watcher IDs available), return @code{-1} and set an
exception.

In free-threaded builds, @ref{96a,,PyType_AddWatcher()} is not thread-safe,
so it must be called at start up (before spawning the first thread).


Added in version 3.12.

@end deffn

@geindex PyType_ClearWatcher (C function)
@anchor{c-api/type c PyType_ClearWatcher}@anchor{563e}
@deffn {C Συνάρτηση} int PyType_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' (previously returned from
@ref{96a,,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{96a,,PyType_AddWatcher()}.


Added in version 3.12.

@end deffn

@geindex PyType_Watch (C function)
@anchor{c-api/type c PyType_Watch}@anchor{96b}
@deffn {C Συνάρτηση} int PyType_Watch (int watcher_id, PyObject *type)

Mark `type' as watched. The callback granted `watcher_id' by
@ref{96a,,PyType_AddWatcher()} will be called whenever
@ref{1d77,,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.)

The callback is also invoked when a watched heap type is deallocated.

An extension should never call @code{PyType_Watch} with a `watcher_id' that was
not returned to it by a previous call to @ref{96a,,PyType_AddWatcher()}.


Added in version 3.12.



Άλλαξε στην έκδοση 3.15: The callback is now also invoked when a watched heap type is deallocated.

@end deffn

@geindex PyType_Unwatch (C function)
@anchor{c-api/type c PyType_Unwatch}@anchor{563f}
@deffn {C Συνάρτηση} int PyType_Unwatch (int watcher_id, PyObject *type)

Mark `type' as not watched. This undoes a previous call to
@ref{96b,,PyType_Watch()}. `type' must not be @code{NULL}.

An extension should never call this function with a `watcher_id' that was
not returned to it by a previous call to @ref{96a,,PyType_AddWatcher()}.

On success, this function returns @code{0}. On failure, this function returns
@code{-1} with an exception set.


Added in version 3.12.

@end deffn

@geindex PyType_WatchCallback (C type)
@anchor{c-api/type c PyType_WatchCallback}@anchor{191d}
@deffn {C Τύπος} typedef int (*PyType_WatchCallback)(@ref{19b,,PyObject} *type)

Type of a type-watcher callback function.

The callback must not modify `type' or cause @ref{1d77,,PyType_Modified()} to be
called on `type' or any type in its MRO; violating this rule could cause
infinite recursion.

The callback may be called during type deallocation. In this case, the type
object is temporarily resurrected (its reference count is at least 1) and all
its attributes are still valid. However, the callback should not store new
strong references to the type, as this would resurrect the object and prevent
its deallocation.


Added in version 3.12.



Άλλαξε στην έκδοση 3.15: The callback may now be called during deallocation of a watched heap type.

@end deffn

@geindex PyType_HasFeature (C function)
@anchor{c-api/type c PyType_HasFeature}@anchor{1f30}
@deffn {C Συνάρτηση} 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_FastSubclass (C function)
@anchor{c-api/type c PyType_FastSubclass}@anchor{5640}
@deffn {C Συνάρτηση} int PyType_FastSubclass (PyTypeObject *type, int flag)

Return non-zero if the type object `type' sets the subclass flag `flag'.
Subclass flags are denoted by
@ref{5641,,Py_TPFLAGS_*_SUBCLASS}.
This function is used by many @code{_Check} functions for common types.


@subsubheading Δείτε επίσης


@ref{1eab,,PyObject_TypeCheck()}, which is used as a slower alternative in
@code{_Check} functions for types that don’t come with subclass flags.

@end deffn

@geindex PyType_IS_GC (C function)
@anchor{c-api/type c PyType_IS_GC}@anchor{5642}
@deffn {C Συνάρτηση} int PyType_IS_GC (PyTypeObject *o)

Return true if the type object includes support for the cycle detector; this
tests the type flag @ref{39e,,Py_TPFLAGS_HAVE_GC}.
@end deffn

@geindex PyType_IsSubtype (C function)
@anchor{c-api/type c PyType_IsSubtype}@anchor{541a}
@deffn {C Συνάρτηση} int PyType_IsSubtype (PyTypeObject *a, PyTypeObject *b)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return true if `a' is a subtype of `b'.

This function only checks for actual subtypes, which means that
@ref{25bd,,__subclasscheck__()} is not called on `b'.  Call
@ref{1258,,PyObject_IsSubclass()} to do the same check that @ref{2f0,,issubclass()}
would do.
@end deffn

@geindex PyType_GenericAlloc (C function)
@anchor{c-api/type c PyType_GenericAlloc}@anchor{e30}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_GenericAlloc (PyTypeObject *type, Py_ssize_t nitems)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Generic handler for the @ref{51e6,,tp_alloc} slot of a type
object.  Uses Python’s default memory allocation mechanism to allocate memory
for a new instance, zeros the memory, then initializes the memory as if by
calling @ref{e2f,,PyObject_Init()} or @ref{1f34,,PyObject_InitVar()}.

Do not call this directly to allocate memory for an object; call the type’s
@ref{51e6,,tp_alloc} slot instead.

For types that support garbage collection (i.e., the
@ref{39e,,Py_TPFLAGS_HAVE_GC} flag is set), this function behaves like
@ref{e68,,PyObject_GC_New} or @ref{e69,,PyObject_GC_NewVar} (except the
memory is guaranteed to be zeroed before initialization), and should be
paired with @ref{18a5,,PyObject_GC_Del()} in @ref{51e5,,tp_free}.
Otherwise, it behaves like @ref{d4d,,PyObject_New} or
@ref{d4e,,PyObject_NewVar} (except the memory is guaranteed to be zeroed
before initialization) and should be paired with @ref{1023,,PyObject_Free()} in
@code{tp_free}.
@end deffn

@geindex PyType_GenericNew (C function)
@anchor{c-api/type c PyType_GenericNew}@anchor{51e2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_GenericNew (PyTypeObject *type, PyObject *args, PyObject *kwds)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Generic handler for the @ref{981,,tp_new} slot of a type
object.  Creates a new instance using the type’s
@ref{51e6,,tp_alloc} slot and returns the resulting object.
@end deffn

@geindex PyType_Ready (C function)
@anchor{c-api/type c PyType_Ready}@anchor{b5e}
@deffn {C Συνάρτηση} int PyType_Ready (PyTypeObject *type)
` Μέρος του @ref{95c,,Σταθερό 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 Σημείωση 
If some of the base classes implements the GC protocol and the provided
type does not include the @ref{39e,,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
@code{Py_TPFLAGS_HAVE_GC} in its flags then it `must' implement the
GC protocol itself by at least implementing the
@ref{36b,,tp_traverse} handle.
@end quotation
@end cartouche
@end deffn

@geindex PyType_GetName (C function)
@anchor{c-api/type c PyType_GetName}@anchor{b36}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_GetName (PyTypeObject *type)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Return the type’s name. Equivalent to getting the type’s
@ref{184d,,__name__} attribute.


Added in version 3.11.

@end deffn

@geindex PyType_GetQualName (C function)
@anchor{c-api/type c PyType_GetQualName}@anchor{b37}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_GetQualName (PyTypeObject *type)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Return the type’s qualified name. Equivalent to getting the
type’s @ref{2565,,__qualname__} attribute.


Added in version 3.11.

@end deffn

@geindex PyType_GetFullyQualifiedName (C function)
@anchor{c-api/type c PyType_GetFullyQualifiedName}@anchor{80a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_GetFullyQualifiedName (PyTypeObject *type)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Return the type’s fully qualified name. Equivalent to
@code{f"@{type.__module__@}.@{type.__qualname__@}"}, or @ref{2565,,type.__qualname__}
if @ref{80b,,type.__module__} is not a string or is equal to @code{"builtins"}.


Added in version 3.13.

@end deffn

@geindex PyType_GetModuleName (C function)
@anchor{c-api/type c PyType_GetModuleName}@anchor{80c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_GetModuleName (PyTypeObject *type)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Return the type’s module name. Equivalent to getting the
@ref{80b,,type.__module__} attribute.


Added in version 3.13.

@end deffn

@geindex PyType_GetSlot (C function)
@anchor{c-api/type c PyType_GetSlot}@anchor{c72}
@deffn {C Συνάρτηση} void *PyType_GetSlot (PyTypeObject *type, int slot)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{5643,,PyType_Slot.slot} for possible values of the `slot' argument.


Added in version 3.4.



Άλλαξε στην έκδοση 3.10: @ref{c72,,PyType_GetSlot()} can now accept all types.
Previously, it was limited to @ref{d2f,,heap types}.

@end deffn

@geindex PyType_GetModule (C function)
@anchor{c-api/type c PyType_GetModule}@anchor{d37}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_GetModule (PyTypeObject *type)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Return the module object associated with the given type when the type was
created using @ref{390,,PyType_FromModuleAndSpec()}.

The returned reference is @ref{603,,borrowed} from `type',
and will be valid as long as you hold a reference to `type'.
Do not release it with @ref{975,,Py_DECREF()} or similar.

If no module is associated with the given type, sets @ref{291,,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{b46,,PyCMethod} to get the class that defines the method.
See @ref{5419,,PyType_GetModuleByToken()} for cases when @code{PyCMethod}
cannot be used.


Added in version 3.9.

@end deffn

@geindex PyType_GetModuleState (C function)
@anchor{c-api/type c PyType_GetModuleState}@anchor{d38}
@deffn {C Συνάρτηση} void *PyType_GetModuleState (PyTypeObject *type)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Return the state of the module object associated with the given type.
This is a shortcut for calling @ref{d48,,PyModule_GetState()} on the result
of @ref{d37,,PyType_GetModule()}.

If no module is associated with the given type, sets @ref{291,,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.


Added in version 3.9.

@end deffn

@geindex PyType_GetModuleByToken (C function)
@anchor{c-api/type c PyType_GetModuleByToken}@anchor{5419}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_GetModuleByToken (PyTypeObject *type, const void *mod_token)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Find the first superclass whose module has the given
@ref{5644,,module token}, and return that module.

If no module is found, raises a @ref{291,,TypeError} and returns @code{NULL}.

This function is intended to be used together with
@ref{d48,,PyModule_GetState()} to get module state from slot methods (such as
@ref{983,,tp_init} or @ref{5645,,nb_add})
and other places where a method’s defining class cannot be passed using the
@ref{b46,,PyCMethod} calling convention.


Added in version 3.15.

@end deffn

@geindex PyType_GetModuleByDef (C function)
@anchor{c-api/type c PyType_GetModuleByDef}@anchor{827}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_GetModuleByDef (PyTypeObject *type, struct PyModuleDef *def)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Find the first superclass whose module was created from the given
@ref{d45,,PyModuleDef} `def', or whose @ref{5644,,module token}
is equal to `def', and return that module.

Note that modules created from a @ref{d45,,PyModuleDef} always have their
token set to the @code{PyModuleDef}’s address.
In other words, this function is equivalent to
@ref{5419,,PyType_GetModuleByToken()}, except that it:


@itemize -

@item 
returns a borrowed reference, and

@item 
has a non-@code{void*} argument type (which is a cosmetic difference in C).
@end itemize

The returned reference is @ref{603,,borrowed} from `type',
and will be valid as long as you hold a reference to `type'.
Do not release it with @ref{975,,Py_DECREF()} or similar.


Added in version 3.11.

@end deffn

@geindex PyType_GetBaseByToken (C function)
@anchor{c-api/type c PyType_GetBaseByToken}@anchor{5dd}
@deffn {C Συνάρτηση} int PyType_GetBaseByToken (PyTypeObject *type, void *tp_token, PyTypeObject **result)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
Find the first superclass in `type'’s @ref{2784,,method resolution order} whose
@ref{5de,,Py_tp_token} token is equal to `tp_token'.


@itemize *

@item 
If found, set `*result' to a new @ref{7da,,strong reference}
to it and return @code{1}.

@item 
If not found, set `*result' to @code{NULL} and return @code{0}.

@item 
On error, set `*result' to @code{NULL} and return @code{-1} with an
exception set.
@end itemize

The `result' argument may be @code{NULL}, in which case `*result' is not set.
Use this if you need only the return value.

The `tp_token' argument may not be @code{NULL}.


Added in version 3.14.

@end deffn

@geindex PyUnstable_Type_AssignVersionTag (C function)
@anchor{c-api/type c PyUnstable_Type_AssignVersionTag}@anchor{5646}
@deffn {C Συνάρτηση} int PyUnstable_Type_AssignVersionTag (PyTypeObject *type)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@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.


Added in version 3.12.

@end deffn

@geindex PyType_SUPPORTS_WEAKREFS (C function)
@anchor{c-api/type c PyType_SUPPORTS_WEAKREFS}@anchor{5647}
@deffn {C Συνάρτηση} int PyType_SUPPORTS_WEAKREFS (PyTypeObject *type)

Return true if instances of `type' support creating weak references, false
otherwise. This function always succeeds. `type' must not be @code{NULL}.


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{55f1,,Weak Reference Objects}

@item 
@ref{11d,,weakref}
@end itemize

@end deffn

@menu
* Creating Heap-Allocated Types:: 
* Soft-deprecated API:: 

@end menu

@node Creating Heap-Allocated Types,Soft-deprecated API,,Type Objects
@anchor{c-api/type creating-heap-allocated-types}@anchor{5648}@anchor{c-api/type creating-heap-types}@anchor{5567}
@subsubsection Creating Heap-Allocated Types


The following function is used to create @ref{d2f,,heap types}:

@geindex PyType_FromSlots (C function)
@anchor{c-api/type c PyType_FromSlots}@anchor{376}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_FromSlots (const PySlot *slots)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Create and return a @ref{d2f,,heap type} from a @code{PySlot}
array.
See @ref{375,,Definition slots} for general information on slots,
and @ref{556b,,Type slot IDs} for slots specific to type creation.

This function calls @ref{b5e,,PyType_Ready()} on the new type.

Note that this function does `not' fully match the behavior of
calling @ref{186,,type()} or using the @ref{167c,,class} statement.
With user-provided base types or metaclasses, prefer
@ref{55f6,,calling} @code{type} (or the metaclass)
over @code{PyType_From*} functions.
Specifically:


@itemize *

@item 
@ref{982,,__new__()} is not called on the new class
(and it must be set to @code{type.__new__}).

@item 
@ref{2fa,,__init__()} is not called on the new class.

@item 
@ref{a22,,__init_subclass__()} is not called on any bases.

@item 
@ref{100c,,__set_name__()} is not called on new descriptors.
@end itemize

Slots are typically defined as a global static constant arrays.
However, sometimes slot values are not statically known at compile time.
For example, slots like @ref{54cc,,Py_tp_bases}, @ref{381,,Py_tp_metaclass}
and @ref{382,,Py_tp_module} require live Python objects.
In this case, it is recommended to put such slots on the stack,
and use @ref{379,,Py_slot_subslots} to refer to an array of static slots.
For example:

@example
static const PySlot my_slots[] = @{
   PySlot_STATIC_DATA(Py_tp_name, "MyClass"),
   PySlot_FUNC(Py_tp_repr, my_repr_func),
   ...
   PySlot_END
@};

PyObject *make_my_class(PyObject *module) @{
   PySlot all_slots[] = @{
      PySlot_STATIC_DATA(Py_slot_subslots, my_slots),
      PySlot_DATA(Py_tp_module, module),
      PySlot_END
   @};
   return PyType_FromSlots(all_slots);
@}
@end example
@end deffn

Heap types created without the @ref{5fb,,Py_TPFLAGS_IMMUTABLETYPE} flag may be
modified, for example by setting attributes on them, as with classes defined
in Python code.
Sometimes, such modifications are necessary to fully initialize a type,
but you may wish to prevent users from changing the type after
the initialization is done:

@geindex PyType_Freeze (C function)
@anchor{c-api/type c PyType_Freeze}@anchor{5dc}
@deffn {C Συνάρτηση} int PyType_Freeze (PyTypeObject *type)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
Make a type immutable: set the @ref{5fb,,Py_TPFLAGS_IMMUTABLETYPE} flag.

All base classes of `type' must be immutable.

On success, return @code{0}.
On error, set an exception and return @code{-1}.

The type must not be used before it’s made immutable. For example, type
instances must not be created before the type is made immutable.


Added in version 3.14.

@end deffn

@menu
* Type slot IDs:: 

@end menu

@node Type slot IDs,,,Creating Heap-Allocated Types
@anchor{c-api/type pyslot-type-slot-ids}@anchor{556b}@anchor{c-api/type type-slot-ids}@anchor{5649}
@subsubsection Type slot IDs


Most type slot IDs are named like the field names of the structures
@ref{e6b,,PyTypeObject}, @ref{17c0,,PyNumberMethods},
@ref{5209,,PySequenceMethods}, @ref{520a,,PyMappingMethods} and
@ref{564a,,PyAsyncMethods} with an added @code{Py_} prefix.
For example, use:


@itemize *

@item 
@ref{54cf,,Py_tp_dealloc} to set @ref{51d3,,PyTypeObject.tp_dealloc}

@item 
@ref{54a0,,Py_nb_add} to set @ref{5645,,PyNumberMethods.nb_add}

@item 
@ref{54c8,,Py_sq_length} to set @ref{564b,,PySequenceMethods.sq_length}
@end itemize

The following slots need additional considerations when specified as slots:


@itemize *

@item 
@ref{37c,,Py_tp_name}

@item 
@ref{37d,,Py_tp_basicsize} and @ref{37e,,Py_tp_extra_basicsize}

@item 
@ref{37f,,Py_tp_itemsize}

@item 
@ref{380,,Py_tp_flags}
@end itemize

Additional slots do not directly correspond to a @code{PyTypeObject}
struct field:


@itemize *

@item 
@ref{5de,,Py_tp_token}

@item 
@ref{381,,Py_tp_metaclass}

@item 
@ref{382,,Py_tp_module}
@end itemize

The following “offset” fields cannot be set using @ref{541b,,PyType_Slot}:


@itemize *

@item 
@ref{d50,,tp_weaklistoffset}
(use @ref{39d,,Py_TPFLAGS_MANAGED_WEAKREF} instead if possible)

@item 
@ref{564c,,tp_dictoffset}
(use @ref{39c,,Py_TPFLAGS_MANAGED_DICT} instead if possible)

@item 
@ref{55f8,,tp_vectorcall_offset}
(use @code{"__vectorcalloffset__"} in @ref{564d,,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{54de,,Py_tp_members}.
See @ref{564d,,PyMemberDef documentation}
for details.

The following internal fields cannot be set at all when creating a heap
type:


@itemize *

@item 
@ref{1c92,,tp_dict},
@ref{564e,,tp_mro},
@ref{564f,,tp_cache},
@ref{977,,tp_subclasses}, and
@ref{5650,,tp_weaklist}.
@end itemize

The @ref{54cb,,Py_tp_base} slot is equivalent to @ref{54cc,,Py_tp_bases};
both may be set either to a type or a tuple of types.
If both are specified, the value of @code{Py_tp_bases}
is used.

Slot values may not be @code{NULL}, except for the following:


@itemize *

@item 
@ref{54d3,,Py_tp_doc}

@item 
@ref{5de,,Py_tp_token} (for clarity, prefer @ref{547d,,Py_TP_USE_SPEC}
rather than @code{NULL})
@end itemize


Άλλαξε στην έκδοση 3.9: Slots in @ref{5651,,PyBufferProcs} may be set in the unlimited API.



Άλλαξε στην έκδοση 3.11: @ref{b44,,bf_getbuffer} and
@ref{b45,,bf_releasebuffer} are now available
under the @ref{829,,limited API}.



Άλλαξε στην έκδοση 3.14: The field @ref{1b9a,,tp_vectorcall} can now be set
using @ref{54e7,,Py_tp_vectorcall}.  See the field’s documentation
for details.



Άλλαξε στην έκδοση 3.15: The @ref{54cc,,Py_tp_bases} slot may be set to a single type object,
making it equivalent to the @ref{54cb,,Py_tp_base} slot.
Previously, a tuple of types was required.


The following slots correspond to fields in the underlying type structure,
but need extra remarks for use as slots:

@geindex Py_tp_name (C macro)
@anchor{c-api/type c Py_tp_name}@anchor{37c}
@deffn {C Μακροεντολή} Py_tp_name
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for the name of the type,
used to set @ref{1ea6,,PyTypeObject.tp_name}.

This slot (or @ref{5652,,PyType_Spec.name()}) is required to create a type.

This may not be used in @ref{5653,,PyType_Spec.slots}.
Use @ref{5652,,PyType_Spec.name()} instead.

`Λεπτομέρεια υλοποίησης CPython:' CPython processes slots in order.
It is recommended to put @code{Py_tp_name} at the beginning of the slots
array, so that if processing of a later slots fails, error messages
can include the name.


Added in version 3.15.

@end deffn

@geindex Py_tp_basicsize (C macro)
@anchor{c-api/type c Py_tp_basicsize}@anchor{37d}
@deffn {C Μακροεντολή} Py_tp_basicsize
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for the size of the instance in bytes.
It is used to set @ref{d4f,,PyTypeObject.tp_basicsize}.

The value must be positive.

This may not be used in @ref{5653,,PyType_Spec.slots}.
Use @ref{199,,PyType_Spec.basicsize()} instead.

This slot may not be used with @ref{c72,,PyType_GetSlot()}.
Use @ref{d4f,,PyTypeObject.tp_basicsize} instead if needed, but be aware
that a type’s size is often considered an implementation detail.


Added in version 3.15.

@end deffn

@geindex Py_tp_extra_basicsize (C macro)
@anchor{c-api/type c Py_tp_extra_basicsize}@anchor{37e}
@deffn {C Μακροεντολή} Py_tp_extra_basicsize
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for type data size in bytes, that is,
how much space instances of the class need `in addition'
to space needed for superclasses.

The value is used, together with the size of superclasses, to set
@ref{d4f,,PyTypeObject.tp_basicsize}.
Python will insert padding as needed to meet
@code{tp_basicsize}’s alignment requirements.

Use @ref{19a,,PyObject_GetTypeData()} to get a pointer to subclass-specific
memory reserved this way.

The value must be positive.
To specify that instances need no additional size (that is, size should be
inherited), omit the @code{Py_tp_extra_basicsize} slot rather than
set it to zero.

Specifying both @ref{37d,,Py_tp_basicsize} and
@code{Py_tp_extra_basicsize} is an error.

This may not be used in @ref{5653,,PyType_Spec.slots}.
Use negative @ref{199,,PyType_Spec.basicsize()} instead.

This slot may not be used with @ref{c72,,PyType_GetSlot()}.


Added in version 3.15.

@end deffn

@geindex Py_tp_itemsize (C macro)
@anchor{c-api/type c Py_tp_itemsize}@anchor{37f}
@deffn {C Μακροεντολή} Py_tp_itemsize
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for the size of one element of a
variable-size type, in bytes.
Used to set @ref{25b0,,PyTypeObject.tp_itemsize}.
See @code{tp_itemsize} documentation for caveats.

The value must be positive.

If this slot is missing, @ref{25b0,,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{25b0,,tp_itemsize}).

@item 
The requested @ref{199,,PyType_Spec.basicsize} is positive,
suggesting that the memory layout of the base class is known.

@item 
The requested @ref{199,,PyType_Spec.basicsize} is zero,
suggesting that the subclass does not access the instance’s memory
directly.

@item 
With the @ref{956,,Py_TPFLAGS_ITEMS_AT_END} flag.
@end itemize

This may not be used in @ref{5653,,PyType_Spec.slots}.
Use @ref{5654,,PyType_Spec.itemsize()} instead.

This slot may not be used with @ref{c72,,PyType_GetSlot()}.


Added in version 3.15.

@end deffn

@geindex Py_tp_flags (C macro)
@anchor{c-api/type c Py_tp_flags}@anchor{380}
@deffn {C Μακροεντολή} Py_tp_flags
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for type flags, used to set
@ref{1e68,,PyTypeObject.tp_flags}.

The @code{Py_TPFLAGS_HEAPTYPE} flag is not set,
@ref{38f,,PyType_FromSpecWithBases()} sets it automatically.

This may not be used in @ref{5653,,PyType_Spec.slots}.
Use negative @ref{199,,PyType_Spec.basicsize()} instead.

This slot may not be used with @ref{c72,,PyType_GetSlot()}.
Use @ref{1f31,,PyType_GetFlags()} instead.


Added in version 3.15.

@end deffn

The following slots do not correspond to public fields in the
underlying structures:

@geindex Py_tp_metaclass (C macro)
@anchor{c-api/type c Py_tp_metaclass}@anchor{381}
@deffn {C Μακροεντολή} Py_tp_metaclass
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for the metaclass used to construct
the resulting type object.
When omitted the metaclass is derived from bases
(@ref{54cc,,Py_tp_bases} or the `bases' argument of
@ref{391,,PyType_FromMetaclass()}).

Metaclasses that override @ref{981,,tp_new} are not
supported, except if @code{tp_new} is @code{NULL}.

This may not be used in @ref{5653,,PyType_Spec.slots}.
Use @ref{391,,PyType_FromMetaclass()} to specify a metaclass with
@code{PyType_Spec}.

This slot may not be used with @ref{c72,,PyType_GetSlot()}.
Use @ref{5f5,,Py_TYPE()} on the type object instead.


Added in version 3.15.

@end deffn

@geindex Py_tp_module (C macro)
@anchor{c-api/type c Py_tp_module}@anchor{382}
@deffn {C Μακροεντολή} Py_tp_module
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for recording the module in which
the new class is defined.

The value must be a module object.
The module is associated with the new type and can later be
retrieved with @ref{d37,,PyType_GetModule()}.
The associated module is not inherited by subclasses; it must be specified
for each class individually.

This may not be used in @ref{5653,,PyType_Spec.slots}.
Use @ref{391,,PyType_FromMetaclass()} to specify a module with
@code{PyType_Spec}.

This slot may not be used with @ref{c72,,PyType_GetSlot()}.
Use @ref{d37,,PyType_GetModule()} instead.


Added in version 3.15.

@end deffn

@geindex Py_tp_token (C macro)
@anchor{c-api/type c Py_tp_token}@anchor{5de}
@deffn {C Μακροεντολή} Py_tp_token
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
@ref{5568,,Slot ID} for recording a static memory layout ID
for a class.

If the class is defined using a @ref{1c8f,,PyType_Spec}, and that spec is
statically allocated, the token can be set to the spec using the special
value @ref{547d,,Py_TP_USE_SPEC}:

@example
static PyType_Slot foo_slots[] = @{
   @{Py_tp_token, Py_TP_USE_SPEC@},
@end example

It can also be set to an arbitrary pointer, but you must ensure that:


@itemize *

@item 
The pointer outlives the class, so it’s not reused for something else
while the class exists.

@item 
It «belongs» to the extension module where the class lives, so it will not
clash with other extensions.
@end itemize

Use @ref{5dd,,PyType_GetBaseByToken()} to check if a class’s superclass has
a given token – that is, check whether the memory layout is compatible.

To get the token for a given class (without considering superclasses),
use @ref{c72,,PyType_GetSlot()} with @code{Py_tp_token}.


Added in version 3.14.


@geindex Py_TP_USE_SPEC (C macro)
@anchor{c-api/type c Py_TP_USE_SPEC}@anchor{547d}
@deffn {C Μακροεντολή} Py_TP_USE_SPEC
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
Used as a value with @ref{5de,,Py_tp_token} to set the token to the
class’s @ref{1c8f,,PyType_Spec}.
May only be used for classes defined using @code{PyType_Spec}.

Expands to @code{NULL}.


Added in version 3.14.

@end deffn
@end deffn

@geindex Py_tp_slots (C macro)
@anchor{c-api/type c Py_tp_slots}@anchor{37a}
@deffn {C Μακροεντολή} Py_tp_slots
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} that works like
@ref{379,,Py_slot_subslots}, except it specifies an array of
@ref{541b,,PyType_Slot} structures.


Added in version 3.15.

@end deffn

@node Soft-deprecated API,,Creating Heap-Allocated Types,Type Objects
@anchor{c-api/type soft-deprecated-api}@anchor{5655}
@subsubsection Soft-deprecated API


The following functions are @ref{1a7,,soft deprecated}.
They will continue to work, but new features will be added as slots for
@ref{376,,PyType_FromSlots()}, not as arguments to new @code{PyType_From*} functions.

@geindex PyType_FromMetaclass (C function)
@anchor{c-api/type c PyType_FromMetaclass}@anchor{391}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_FromMetaclass (PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
Create and return a @ref{d2f,,heap type} from the `spec'
(see @ref{c82,,Py_TPFLAGS_HEAPTYPE}).

A non-@code{NULL} `metaclass' argument corresponds to the
@ref{381,,Py_tp_metaclass} slot.

A non-@code{NULL} `bases' argument corresponds to the @ref{54cc,,Py_tp_bases}
slot, and takes precedence over @code{Py_tp_bases} and
@code{Py_tp_bases} slots.

A non-@code{NULL} `module' argument corresponds to the
@ref{382,,Py_tp_module} slot.

This function calls @ref{b5e,,PyType_Ready()} on the new type.

Note that this function does `not' fully match the behavior of
calling @ref{186,,type()} or using the @ref{167c,,class} statement.
See the note in @ref{376,,PyType_FromSlots()} documentation for details.


Added in version 3.12.



@ref{1a7,,Soft deprecated} since version 3.16.0a0 (unreleased): Prefer @ref{376,,PyType_FromSlots()} in new code.

@end deffn

@geindex PyType_FromModuleAndSpec (C function)
@anchor{c-api/type c PyType_FromModuleAndSpec}@anchor{390}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_FromModuleAndSpec (PyObject *module, PyType_Spec *spec, PyObject *bases)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Equivalent to @code{PyType_FromMetaclass(NULL, module, spec, bases)}.


Added in version 3.9.



Άλλαξε στην έκδοση 3.10: The function now accepts a single class as the `bases' argument and
@code{NULL} as the @code{tp_doc} slot.



Άλλαξε στην έκδοση 3.12: The function now finds and uses a metaclass corresponding to the provided
base classes.  Previously, only @ref{186,,type} instances were returned.

The @ref{981,,tp_new} of the metaclass is `ignored'.
which may result in incomplete initialization.
Creating classes whose metaclass overrides
@code{tp_new} is deprecated.



Άλλαξε στην έκδοση 3.14: Creating classes whose metaclass overrides
@ref{981,,tp_new} is no longer allowed.



@ref{1a7,,Soft deprecated} since version 3.16.0a0 (unreleased): Prefer @ref{376,,PyType_FromSlots()} in new code.

@end deffn

@geindex PyType_FromSpecWithBases (C function)
@anchor{c-api/type c PyType_FromSpecWithBases}@anchor{38f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_FromSpecWithBases (PyType_Spec *spec, PyObject *bases)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.3.'
Equivalent to @code{PyType_FromMetaclass(NULL, NULL, spec, bases)}.


Added in version 3.3.



Άλλαξε στην έκδοση 3.12: The function now finds and uses a metaclass corresponding to the provided
base classes.  Previously, only @ref{186,,type} instances were returned.

The @ref{981,,tp_new} of the metaclass is `ignored'.
which may result in incomplete initialization.
Creating classes whose metaclass overrides
@code{tp_new} is deprecated.



Άλλαξε στην έκδοση 3.14: Creating classes whose metaclass overrides
@ref{981,,tp_new} is no longer allowed.



@ref{1a7,,Soft deprecated} since version 3.16.0a0 (unreleased): Prefer @ref{376,,PyType_FromSlots()} in new code.

@end deffn

@geindex PyType_FromSpec (C function)
@anchor{c-api/type c PyType_FromSpec}@anchor{38e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_FromSpec (PyType_Spec *spec)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Equivalent to @code{PyType_FromMetaclass(NULL, NULL, spec, NULL)}.


Άλλαξε στην έκδοση 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{186,,type} instances were returned.

The @ref{981,,tp_new} of the metaclass is `ignored'.
which may result in incomplete initialization.
Creating classes whose metaclass overrides
@code{tp_new} is deprecated.



Άλλαξε στην έκδοση 3.14: Creating classes whose metaclass overrides
@ref{981,,tp_new} is no longer allowed.



@ref{1a7,,Soft deprecated} since version 3.16.0a0 (unreleased): Prefer @ref{376,,PyType_FromSlots()} in new code.

@end deffn

@geindex PyType_Spec (C type)
@anchor{c-api/type c PyType_Spec}@anchor{1c8f}
@deffn {C Τύπος} type PyType_Spec
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών).'
Structure defining a type’s behavior, used for soft-deprecated functions
like @ref{391,,PyType_FromMetaclass()}.

This structure contains several members that can instead be specified
as @ref{556b,,slots} for @ref{376,,PyType_FromSlots()},
and an array of slot entries with a simpler structure.

@geindex PyType_Spec.name (C member)
@anchor{c-api/type c PyType_Spec name}@anchor{5652}
@deffn {C Μέλος} const char *name

Corresponds to @ref{37c,,Py_tp_name}.
@end deffn

@geindex PyType_Spec.basicsize (C member)
@anchor{c-api/type c PyType_Spec basicsize}@anchor{199}
@deffn {C Μέλος} int basicsize

If positive, corresponds to @ref{37d,,Py_tp_basicsize}.

If negative, corresponds to @ref{37e,,Py_tp_extra_basicsize} set to
the absolute value.


Άλλαξε στην έκδοση 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{5654}
@deffn {C Μέλος} int itemsize

Corresponds to @ref{37f,,Py_tp_itemsize}.
@end deffn

@geindex PyType_Spec.flags (C member)
@anchor{c-api/type c PyType_Spec flags}@anchor{5656}
@deffn {C Μέλος} unsigned int flags

Corresponds to @ref{380,,Py_tp_flags}.
@end deffn

@geindex PyType_Spec.slots (C member)
@anchor{c-api/type c PyType_Spec slots}@anchor{5653}
@deffn {C Μέλος} @ref{541b,,PyType_Slot} *slots

Array of @ref{541b,,PyType_Slot} (not @ref{19d,,PySlot}) structures.

Terminated by the special slot value @code{@{0, NULL@}}.
Each slot ID should be specified at most once.

@geindex PyType_Slot (C type)
@anchor{c-api/type c PyType_Slot}@anchor{541b}
@deffn {C Τύπος} type PyType_Slot
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών).'
Structure defining optional functionality of a type, used for
soft-deprecated functions like @ref{391,,PyType_FromMetaclass()}.

Note that a @code{PyType_Slot} array may be included in a
@code{PySlot} array using @ref{37a,,Py_tp_slots},
and vice versa using @ref{379,,Py_slot_subslots}.

Each @code{PyType_Slot} structure @code{tpslot} is interpreted
as the following @ref{19d,,PySlot} structure:

@example
(PySlot)@{
   .sl_id=tpslot.slot,
   .sl_flags=PySlot_INTPTR | sub_static,
   .sl_ptr=tpslot.func
@}
@end example

where @code{sub_static} is @code{PySlot_STATIC} if the slot requires
the flag (such as for @ref{54df,,Py_tp_methods}), or if this flag
is present on the «parent» @code{Py_tp_slots} slot (if any).

@geindex PyType_Slot.slot (C member)
@anchor{c-api/type c PyType_Slot slot}@anchor{5643}
@deffn {C Μέλος} int slot

Corresponds to @ref{5568,,PySlot.sl_id}.
@end deffn

@geindex PyType_Slot.pfunc (C member)
@anchor{c-api/type c PyType_Slot pfunc}@anchor{5657}
@deffn {C Μέλος} void *pfunc

Corresponds to @ref{556c,,PySlot.sl_ptr}.
@end deffn
@end deffn
@end deffn
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node The None Object,,Type Objects,Fundamental Objects
@anchor{c-api/none doc}@anchor{5658}@anchor{c-api/none noneobject}@anchor{5659}@anchor{c-api/none the-none-object}@anchor{565a}@anchor{c-api/none translation-repo}@anchor{565b}
@subsubsection The @code{None} Object


@geindex object;None

Note that the @ref{e6b,,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{5606}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *Py_None

The Python @code{None} object, denoting lack of value.  This object has no methods
and is @ref{398,,immortal}.


Άλλαξε στην έκδοση 3.12: @ref{5606,,Py_None} is @ref{398,,immortal}.

@end deffn

@geindex Py_RETURN_NONE (C macro)
@anchor{c-api/none c Py_RETURN_NONE}@anchor{1815}
@deffn {C Μακροεντολή} Py_RETURN_NONE

Return @ref{5606,,Py_None} from a function.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Numeric Objects,Sequence Objects,Fundamental Objects,Concrete Objects Layer
@anchor{c-api/concrete numeric-objects}@anchor{565c}@anchor{c-api/concrete numericobjects}@anchor{565d}
@subsection Numeric Objects


@geindex object;numeric

@menu
* Integer Objects:: 
* Boolean Objects:: 
* Floating-Point Objects:: 
* Complex Number Objects:: 

@end menu

@node Integer Objects,Boolean Objects,,Numeric Objects
@anchor{c-api/long doc}@anchor{565e}@anchor{c-api/long integer-objects}@anchor{565f}@anchor{c-api/long longobjects}@anchor{5660}
@subsubsection Integer Objects


@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{1ea5,,PyErr_Occurred()} to disambiguate.

@geindex PyLongObject (C type)
@anchor{c-api/long c PyLongObject}@anchor{5cb}
@deffn {C Τύπος} type PyLongObject
` Μέρος του @ref{95c,,Σταθερό ABI} (ως μια αδιαφανής κατασκευή).'
This subtype of @ref{19b,,PyObject} represents a Python integer object.
@end deffn

@geindex PyLong_Type (C var)
@anchor{c-api/long c PyLong_Type}@anchor{5381}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyLong_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This instance of @ref{e6b,,PyTypeObject} represents the Python integer type.
This is the same object as @ref{326,,int} in the Python layer.
@end deffn

@geindex PyLong_Check (C function)
@anchor{c-api/long c PyLong_Check}@anchor{5661}
@deffn {C Συνάρτηση} int PyLong_Check (PyObject *p)

Return true if its argument is a @ref{5cb,,PyLongObject} or a subtype of
@code{PyLongObject}.  This function always succeeds.
@end deffn

@geindex PyLong_CheckExact (C function)
@anchor{c-api/long c PyLong_CheckExact}@anchor{5662}
@deffn {C Συνάρτηση} int PyLong_CheckExact (PyObject *p)

Return true if its argument is a @ref{5cb,,PyLongObject}, but not a subtype of
@code{PyLongObject}.  This function always succeeds.
@end deffn

@geindex PyLong_FromLong (C function)
@anchor{c-api/long c PyLong_FromLong}@anchor{1dca}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromLong (long v)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a new @ref{5cb,,PyLongObject} object from `v', or @code{NULL} on failure.

`Λεπτομέρεια υλοποίησης CPython:' CPython keeps an array of integer objects for all integers
between @code{-5} and @code{1024}.  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{1ade}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromUnsignedLong (unsigned long v)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a new @ref{5cb,,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{1ac2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromSsize_t (Py_ssize_t v)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a new @ref{5cb,,PyLongObject} object from a C @ref{e24,,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{1ae0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromSize_t (size_t v)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a new @ref{5cb,,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{1dcb}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromLongLong (long long v)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a new @ref{5cb,,PyLongObject} object from a C long long, or @code{NULL}
on failure.
@end deffn

@geindex PyLong_FromInt32 (C function)
@geindex PyLong_FromInt64 (C function)
@anchor{c-api/long c PyLong_FromInt32}@anchor{5d0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromInt32 (int32_t value)
@anchor{c-api/long c PyLong_FromInt64}@anchor{5d1}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromInt64 (int64_t value)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
Return a new @ref{5cb,,PyLongObject} object from a signed C
int32_t or int64_t, or @code{NULL}
with an exception set on failure.


Added in version 3.14.

@end deffn

@geindex PyLong_FromUnsignedLongLong (C function)
@anchor{c-api/long c PyLong_FromUnsignedLongLong}@anchor{1adf}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromUnsignedLongLong (unsigned long long v)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a new @ref{5cb,,PyLongObject} object from a C unsigned long long,
or @code{NULL} on failure.
@end deffn

@geindex PyLong_FromUInt32 (C function)
@geindex PyLong_FromUInt64 (C function)
@anchor{c-api/long c PyLong_FromUInt32}@anchor{5d2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromUInt32 (uint32_t value)
@anchor{c-api/long c PyLong_FromUInt64}@anchor{5d3}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromUInt64 (uint64_t value)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
Return a new @ref{5cb,,PyLongObject} object from an unsigned C
uint32_t or uint64_t, or @code{NULL}
with an exception set on failure.


Added in version 3.14.

@end deffn

@geindex PyLong_FromDouble (C function)
@anchor{c-api/long c PyLong_FromDouble}@anchor{d0e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromDouble (double v)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a new @ref{5cb,,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{537e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromString (const char *str, char **pend, int base)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a new @ref{5cb,,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{24fc,,Λεκτικά ακεραίων} definition; in this case, leading
zeros in a non-zero decimal number raises a @ref{277,,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, @code{ValueError} will be raised.


@subsubheading Δείτε επίσης


@ref{7fc,,PyLong_AsNativeBytes()} and
@ref{7fd,,PyLong_FromNativeBytes()} functions can be used to convert
a @ref{5cb,,PyLongObject} to/from an array of bytes in base @code{256}.

@end deffn

@geindex PyLong_FromUnicodeObject (C function)
@anchor{c-api/long c PyLong_FromUnicodeObject}@anchor{c8d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromUnicodeObject (PyObject *u, int base)
`Επιστρεφόμενη τιμή: New reference.'
Convert a sequence of Unicode digits in the string `u' to a Python integer
value.


Added in version 3.3.

@end deffn

@geindex PyLong_FromVoidPtr (C function)
@anchor{c-api/long c PyLong_FromVoidPtr}@anchor{537f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromVoidPtr (void *p)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a Python integer from the pointer `p'. The pointer value can be
retrieved from the resulting value using @ref{537d,,PyLong_AsVoidPtr()}.
@end deffn

@geindex PyLong_FromNativeBytes (C function)
@anchor{c-api/long c PyLong_FromNativeBytes}@anchor{7fd}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromNativeBytes (const void *buffer, size_t n_bytes, int flags)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
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{7fc,,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{7fe,,PyLong_FromUnsignedNativeBytes()}. Other flags are ignored.


Added in version 3.13.

@end deffn

@geindex PyLong_FromUnsignedNativeBytes (C function)
@anchor{c-api/long c PyLong_FromUnsignedNativeBytes}@anchor{7fe}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_FromUnsignedNativeBytes (const void *buffer, size_t n_bytes, int flags)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
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{7fc,,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.


Added in version 3.13.

@end deffn

@geindex PyLong_FromPid (C macro)
@anchor{c-api/long c PyLong_FromPid}@anchor{5663}
@deffn {C Μακροεντολή} PyLong_FromPid (pid)

Macro for creating a Python integer from a process identifier.

This can be defined as an alias to @ref{1dca,,PyLong_FromLong()} or
@ref{1dcb,,PyLong_FromLongLong()}, depending on the size of the system’s
PID type.


Added in version 3.2.

@end deffn

@geindex PyLong_AsLong (C function)
@anchor{c-api/long c PyLong_AsLong}@anchor{7fb}
@deffn {C Συνάρτηση} long PyLong_AsLong (PyObject *obj)
` Μέρος του @ref{95c,,Σταθερό 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{5cb,,PyLongObject}, first call its @ref{43d,,__index__()} method
(if present) to convert it to a @code{PyLongObject}.

Raise @ref{c57,,OverflowError} if the value of `obj' is out of range for a
long.

Returns @code{-1} on error.  Use @ref{1ea5,,PyErr_Occurred()} to disambiguate.


Άλλαξε στην έκδοση 3.8: Use @ref{43d,,__index__()} if available.



Άλλαξε στην έκδοση 3.10: This function will no longer use @ref{43c,,__int__()}.


@geindex PyLong_AS_LONG (C function)
@anchor{c-api/long c PyLong_AS_LONG}@anchor{5664}
@deffn {C Συνάρτηση} long PyLong_AS_LONG (PyObject *obj)

Exactly equivalent to the preferred @code{PyLong_AsLong}. In particular,
it can fail with @ref{c57,,OverflowError} or another exception.


@ref{1a7,,Soft deprecated} since version 3.14.

@end deffn
@end deffn

@geindex PyLong_AsInt (C function)
@anchor{c-api/long c PyLong_AsInt}@anchor{7fa}
@deffn {C Συνάρτηση} int PyLong_AsInt (PyObject *obj)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Similar to @ref{7fb,,PyLong_AsLong()}, but store the result in a C
int instead of a C long.


Added in version 3.13.

@end deffn

@geindex PyLong_AsLongAndOverflow (C function)
@anchor{c-api/long c PyLong_AsLongAndOverflow}@anchor{160b}
@deffn {C Συνάρτηση} long PyLong_AsLongAndOverflow (PyObject *obj, int *overflow)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a C long representation of `obj'.  If `obj' is not an
instance of @ref{5cb,,PyLongObject}, first call its @ref{43d,,__index__()}
method (if present) to convert it to a @code{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{1ea5,,PyErr_Occurred()} to disambiguate.


Άλλαξε στην έκδοση 3.8: Use @ref{43d,,__index__()} if available.



Άλλαξε στην έκδοση 3.10: This function will no longer use @ref{43c,,__int__()}.

@end deffn

@geindex PyLong_AsLongLong (C function)
@anchor{c-api/long c PyLong_AsLongLong}@anchor{5378}
@deffn {C Συνάρτηση} long long PyLong_AsLongLong (PyObject *obj)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex OverflowError (built-in exception)

Return a C long long representation of `obj'.  If `obj' is not an
instance of @ref{5cb,,PyLongObject}, first call its @ref{43d,,__index__()} method
(if present) to convert it to a @code{PyLongObject}.

Raise @ref{c57,,OverflowError} if the value of `obj' is out of range for a
long long.

Returns @code{-1} on error.  Use @ref{1ea5,,PyErr_Occurred()} to disambiguate.


Άλλαξε στην έκδοση 3.8: Use @ref{43d,,__index__()} if available.



Άλλαξε στην έκδοση 3.10: This function will no longer use @ref{43c,,__int__()}.

@end deffn

@geindex PyLong_AsLongLongAndOverflow (C function)
@anchor{c-api/long c PyLong_AsLongLongAndOverflow}@anchor{160a}
@deffn {C Συνάρτηση} long long PyLong_AsLongLongAndOverflow (PyObject *obj, int *overflow)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a C long long representation of `obj'.  If `obj' is not an
instance of @ref{5cb,,PyLongObject}, first call its @ref{43d,,__index__()} method
(if present) to convert it to a @code{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{1ea5,,PyErr_Occurred()} to disambiguate.


Added in version 3.2.



Άλλαξε στην έκδοση 3.8: Use @ref{43d,,__index__()} if available.



Άλλαξε στην έκδοση 3.10: This function will no longer use @ref{43c,,__int__()}.

@end deffn

@geindex PyLong_AsSsize_t (C function)
@anchor{c-api/long c PyLong_AsSsize_t}@anchor{537a}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyLong_AsSsize_t (PyObject *pylong)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex PY_SSIZE_T_MAX (C macro)
@geindex OverflowError (built-in exception)

Return a C @ref{e24,,Py_ssize_t} representation of `pylong'.  `pylong' must
be an instance of @ref{5cb,,PyLongObject}.

Raise @ref{c57,,OverflowError} if the value of `pylong' is out of range for a
@ref{e24,,Py_ssize_t}.

Returns @code{-1} on error.  Use @ref{1ea5,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsUnsignedLong (C function)
@anchor{c-api/long c PyLong_AsUnsignedLong}@anchor{537b}
@deffn {C Συνάρτηση} unsigned long PyLong_AsUnsignedLong (PyObject *pylong)
` Μέρος του @ref{95c,,Σταθερό 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{5cb,,PyLongObject}.

Raise @ref{c57,,OverflowError} if the value of `pylong' is out of range for a
unsigned long.

Returns @code{(unsigned long)-1} on error.
Use @ref{1ea5,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsSize_t (C function)
@anchor{c-api/long c PyLong_AsSize_t}@anchor{5379}
@deffn {C Συνάρτηση} size_t PyLong_AsSize_t (PyObject *pylong)
` Μέρος του @ref{95c,,Σταθερό 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{5cb,,PyLongObject}.

Raise @ref{c57,,OverflowError} if the value of `pylong' is out of range for a
@code{size_t}.

Returns @code{(size_t)-1} on error.
Use @ref{1ea5,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsUnsignedLongLong (C function)
@anchor{c-api/long c PyLong_AsUnsignedLongLong}@anchor{1639}
@deffn {C Συνάρτηση} unsigned long long PyLong_AsUnsignedLongLong (PyObject *pylong)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex OverflowError (built-in exception)

Return a C unsigned long long representation of `pylong'.  `pylong'
must be an instance of @ref{5cb,,PyLongObject}.

Raise @ref{c57,,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{1ea5,,PyErr_Occurred()} to disambiguate.


Άλλαξε στην έκδοση 3.1: A negative `pylong' now raises @ref{c57,,OverflowError}, not @ref{291,,TypeError}.

@end deffn

@geindex PyLong_AsUnsignedLongMask (C function)
@anchor{c-api/long c PyLong_AsUnsignedLongMask}@anchor{537c}
@deffn {C Συνάρτηση} unsigned long PyLong_AsUnsignedLongMask (PyObject *obj)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a C unsigned long representation of `obj'.  If `obj' is not
an instance of @ref{5cb,,PyLongObject}, first call its @ref{43d,,__index__()}
method (if present) to convert it to a @code{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{1ea5,,PyErr_Occurred()} to
disambiguate.


Άλλαξε στην έκδοση 3.8: Use @ref{43d,,__index__()} if available.



Άλλαξε στην έκδοση 3.10: This function will no longer use @ref{43c,,__int__()}.

@end deffn

@geindex PyLong_AsUnsignedLongLongMask (C function)
@anchor{c-api/long c PyLong_AsUnsignedLongLongMask}@anchor{1fba}
@deffn {C Συνάρτηση} unsigned long long PyLong_AsUnsignedLongLongMask (PyObject *obj)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a C unsigned long long representation of `obj'.  If `obj'
is not an instance of @ref{5cb,,PyLongObject}, first call its
@ref{43d,,__index__()} method (if present) to convert it to a
@code{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{1ea5,,PyErr_Occurred()}
to disambiguate.


Άλλαξε στην έκδοση 3.8: Use @ref{43d,,__index__()} if available.



Άλλαξε στην έκδοση 3.10: This function will no longer use @ref{43c,,__int__()}.

@end deffn

@geindex PyLong_AsInt32 (C function)
@geindex PyLong_AsInt64 (C function)
@anchor{c-api/long c PyLong_AsInt32}@anchor{5cc}
@deffn {C Συνάρτηση} int PyLong_AsInt32 (PyObject *obj, int32_t *value)
@anchor{c-api/long c PyLong_AsInt64}@anchor{5cd}
@deffnx {C Συνάρτηση} int PyLong_AsInt64 (PyObject *obj, int64_t *value)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
Set `*value' to a signed C int32_t or int64_t
representation of `obj'.

If `obj' is not an instance of @ref{5cb,,PyLongObject}, first call its
@ref{43d,,__index__()} method (if present) to convert it to a
@code{PyLongObject}.

If the `obj' value is out of range, raise an @ref{c57,,OverflowError}.

Set `*value' and return @code{0} on success.
Set an exception and return @code{-1} on error.

`value' must not be @code{NULL}.


Added in version 3.14.

@end deffn

@geindex PyLong_AsUInt32 (C function)
@geindex PyLong_AsUInt64 (C function)
@anchor{c-api/long c PyLong_AsUInt32}@anchor{5ce}
@deffn {C Συνάρτηση} int PyLong_AsUInt32 (PyObject *obj, uint32_t *value)
@anchor{c-api/long c PyLong_AsUInt64}@anchor{5cf}
@deffnx {C Συνάρτηση} int PyLong_AsUInt64 (PyObject *obj, uint64_t *value)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
Set `*value' to an unsigned C uint32_t or uint64_t
representation of `obj'.

If `obj' is not an instance of @ref{5cb,,PyLongObject}, first call its
@ref{43d,,__index__()} method (if present) to convert it to a
@code{PyLongObject}.


@itemize *

@item 
If `obj' is negative, raise a @ref{277,,ValueError}.

@item 
If the `obj' value is out of range, raise an @ref{c57,,OverflowError}.
@end itemize

Set `*value' and return @code{0} on success.
Set an exception and return @code{-1} on error.

`value' must not be @code{NULL}.


Added in version 3.14.

@end deffn

@geindex PyLong_AsDouble (C function)
@anchor{c-api/long c PyLong_AsDouble}@anchor{1b87}
@deffn {C Συνάρτηση} double PyLong_AsDouble (PyObject *pylong)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a C double representation of `pylong'.  `pylong' must be
an instance of @ref{5cb,,PyLongObject}.

Raise @ref{c57,,OverflowError} if the value of `pylong' is out of range for a
double.

Returns @code{-1.0} on error.  Use @ref{1ea5,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsVoidPtr (C function)
@anchor{c-api/long c PyLong_AsVoidPtr}@anchor{537d}
@deffn {C Συνάρτηση} void *PyLong_AsVoidPtr (PyObject *pylong)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Convert a Python integer `pylong' to a C void pointer.
If `pylong' cannot be converted, an @ref{c57,,OverflowError} will be raised.  This
is only assured to produce a usable void pointer for values created
with @ref{537f,,PyLong_FromVoidPtr()}.

Returns @code{NULL} on error.  Use @ref{1ea5,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsNativeBytes (C function)
@anchor{c-api/long c PyLong_AsNativeBytes}@anchor{7fc}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyLong_AsNativeBytes (PyObject *pylong, void *buffer, Py_ssize_t n_bytes, int flags)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
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: remaining bytes filled by
copies of the sign bit.

If the returned value is greater than `n_bytes', the value was
truncated: as many of the lowest bits of the value as could fit are written,
and the higher bits are ignored. This matches the typical behavior
of a C-style downcast.

@cartouche
@quotation Σημείωση 
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 Σημείωση 
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

Flag

@tab

Value

@item

@geindex Py_ASNATIVEBYTES_DEFAULTS (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_DEFAULTS}@anchor{5463}
@deffn {C Μακροεντολή} Py_ASNATIVEBYTES_DEFAULTS
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
@end deffn

@tab

@code{-1}

@item

@geindex Py_ASNATIVEBYTES_BIG_ENDIAN (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_BIG_ENDIAN}@anchor{5462}
@deffn {C Μακροεντολή} Py_ASNATIVEBYTES_BIG_ENDIAN
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
@end deffn

@tab

@code{0}

@item

@geindex Py_ASNATIVEBYTES_LITTLE_ENDIAN (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_LITTLE_ENDIAN}@anchor{5464}
@deffn {C Μακροεντολή} Py_ASNATIVEBYTES_LITTLE_ENDIAN
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
@end deffn

@tab

@code{1}

@item

@geindex Py_ASNATIVEBYTES_NATIVE_ENDIAN (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_NATIVE_ENDIAN}@anchor{5465}
@deffn {C Μακροεντολή} Py_ASNATIVEBYTES_NATIVE_ENDIAN
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
@end deffn

@tab

@code{3}

@item

@geindex Py_ASNATIVEBYTES_UNSIGNED_BUFFER (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_UNSIGNED_BUFFER}@anchor{5467}
@deffn {C Μακροεντολή} Py_ASNATIVEBYTES_UNSIGNED_BUFFER
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
@end deffn

@tab

@code{4}

@item

@geindex Py_ASNATIVEBYTES_REJECT_NEGATIVE (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_REJECT_NEGATIVE}@anchor{5466}
@deffn {C Μακροεντολή} Py_ASNATIVEBYTES_REJECT_NEGATIVE
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
@end deffn

@tab

@code{8}

@item

@geindex Py_ASNATIVEBYTES_ALLOW_INDEX (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_ALLOW_INDEX}@anchor{5461}
@deffn {C Μακροεντολή} Py_ASNATIVEBYTES_ALLOW_INDEX
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
@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{43d,,__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{291,,TypeError}.

@cartouche
@quotation Σημείωση 
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


Added in version 3.13.

@end deffn

@geindex PyLong_AsPid (C macro)
@anchor{c-api/long c PyLong_AsPid}@anchor{1bd8}
@deffn {C Μακροεντολή} PyLong_AsPid (pid)

Macro for converting a Python integer into a process identifier.

This can be defined as an alias to @ref{7fb,,PyLong_AsLong()},
@ref{1dcb,,PyLong_FromLongLong()}, or @ref{7fa,,PyLong_AsInt()}, depending on the
size of the system’s PID type.


Added in version 3.2.

@end deffn

@geindex PyLong_GetSign (C function)
@anchor{c-api/long c PyLong_GetSign}@anchor{5c7}
@deffn {C Συνάρτηση} int PyLong_GetSign (PyObject *obj, int *sign)

Get the sign of the integer object `obj'.

On success, set `*sign' to the integer sign  (0, -1 or +1 for zero, negative or
positive integer, respectively) and return 0.

On failure, return -1 with an exception set.  This function always succeeds
if `obj' is a @ref{5cb,,PyLongObject} or its subtype.


Added in version 3.14.

@end deffn

@geindex PyLong_IsPositive (C function)
@anchor{c-api/long c PyLong_IsPositive}@anchor{5c8}
@deffn {C Συνάρτηση} int PyLong_IsPositive (PyObject *obj)

Check if the integer object `obj' is positive (@code{obj > 0}).

If `obj' is an instance of @ref{5cb,,PyLongObject} or its subtype,
return @code{1} when it’s positive and @code{0} otherwise.  Else set an
exception and return @code{-1}.


Added in version 3.14.

@end deffn

@geindex PyLong_IsNegative (C function)
@anchor{c-api/long c PyLong_IsNegative}@anchor{5c9}
@deffn {C Συνάρτηση} int PyLong_IsNegative (PyObject *obj)

Check if the integer object `obj' is negative (@code{obj < 0}).

If `obj' is an instance of @ref{5cb,,PyLongObject} or its subtype,
return @code{1} when it’s negative and @code{0} otherwise.  Else set an
exception and return @code{-1}.


Added in version 3.14.

@end deffn

@geindex PyLong_IsZero (C function)
@anchor{c-api/long c PyLong_IsZero}@anchor{5ca}
@deffn {C Συνάρτηση} int PyLong_IsZero (PyObject *obj)

Check if the integer object `obj' is zero.

If `obj' is an instance of @ref{5cb,,PyLongObject} or its subtype,
return @code{1} when it’s zero and @code{0} otherwise.  Else set an
exception and return @code{-1}.


Added in version 3.14.

@end deffn

@geindex PyLong_GetInfo (C function)
@anchor{c-api/long c PyLong_GetInfo}@anchor{5380}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLong_GetInfo (void)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
On success, return a read only @ref{a3d,,named tuple}, that holds
information about Python’s internal representation of integers.
See @ref{1638,,sys.int_info} for description of individual fields.

On failure, return @code{NULL} with an exception set.


Added in version 3.1.

@end deffn

@geindex PyUnstable_Long_IsCompact (C function)
@anchor{c-api/long c PyUnstable_Long_IsCompact}@anchor{988}
@deffn {C Συνάρτηση} int PyUnstable_Long_IsCompact (const PyLongObject *op)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@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{989,,PyUnstable_Long_CompactValue()}; for others fall back to a
@ref{5379,,PyLong_As*} function or
@ref{7fc,,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.


Added in version 3.12.

@end deffn

@geindex PyUnstable_Long_CompactValue (C function)
@anchor{c-api/long c PyUnstable_Long_CompactValue}@anchor{989}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyUnstable_Long_CompactValue (const PyLongObject *op)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

If `op' is compact, as determined by @ref{988,,PyUnstable_Long_IsCompact()},
return its value.

Otherwise, the return value is undefined.


Added in version 3.12.

@end deffn

@menu
* Export API:: 
* PyLongWriter API:: 
* Deprecated API:: 

@end menu

@node Export API,PyLongWriter API,,Integer Objects
@anchor{c-api/long export-api}@anchor{5665}
@subsubsection Export API



Added in version 3.14.


@geindex PyLongLayout (C type)
@anchor{c-api/long c PyLongLayout}@anchor{196f}
@deffn {C Τύπος} type PyLongLayout
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών) από την έκδοση 3.15.'
Layout of an array of «digits» («limbs» in the GMP terminology), used to
represent absolute value for arbitrary precision integers.

Use @ref{5d4,,PyLong_GetNativeLayout()} to get the native layout of Python
@ref{326,,int} objects, used internally for integers with «big enough»
absolute value.

See also @ref{1638,,sys.int_info} which exposes similar information in Python.

@geindex PyLongLayout.bits_per_digit (C member)
@anchor{c-api/long c PyLongLayout bits_per_digit}@anchor{5666}
@deffn {C Μέλος} uint8_t bits_per_digit

Bits per digit. For example, a 15 bit digit means that bits 0-14 contain
meaningful information.
@end deffn

@geindex PyLongLayout.digit_size (C member)
@anchor{c-api/long c PyLongLayout digit_size}@anchor{5667}
@deffn {C Μέλος} uint8_t digit_size

Digit size in bytes. For example, a 15 bit digit will require at least 2
bytes.
@end deffn

@geindex PyLongLayout.digits_order (C member)
@anchor{c-api/long c PyLongLayout digits_order}@anchor{5668}
@deffn {C Μέλος} int8_t digits_order

Digits order:


@itemize -

@item 
@code{1} for most significant digit first

@item 
@code{-1} for least significant digit first
@end itemize
@end deffn

@geindex PyLongLayout.digit_endianness (C member)
@anchor{c-api/long c PyLongLayout digit_endianness}@anchor{5669}
@deffn {C Μέλος} int8_t digit_endianness

Digit endianness:


@itemize -

@item 
@code{1} for most significant byte first (big endian)

@item 
@code{-1} for least significant byte first (little endian)
@end itemize
@end deffn
@end deffn

@geindex PyLong_GetNativeLayout (C function)
@anchor{c-api/long c PyLong_GetNativeLayout}@anchor{5d4}
@deffn {C Συνάρτηση} const @ref{196f,,PyLongLayout} *PyLong_GetNativeLayout (void)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Get the native layout of Python @ref{326,,int} objects.

See the @ref{196f,,PyLongLayout} structure.

The function must not be called before Python initialization nor after
Python finalization. The returned layout is valid until Python is
finalized. The layout is the same for all Python sub-interpreters
in a process, and so it can be cached.
@end deffn

@geindex PyLongExport (C type)
@anchor{c-api/long c PyLongExport}@anchor{1970}
@deffn {C Τύπος} type PyLongExport
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών) από την έκδοση 3.15.'
Export of a Python @ref{326,,int} object.

There are two cases:


@itemize *

@item 
If @ref{566a,,digits} is @code{NULL}, only use the @ref{566b,,value} member.

@item 
If @ref{566a,,digits} is not @code{NULL}, use @ref{566c,,negative},
@ref{566d,,ndigits} and @code{digits} members.
@end itemize

@geindex PyLongExport.value (C member)
@anchor{c-api/long c PyLongExport value}@anchor{566b}
@deffn {C Μέλος} int64_t value

The native integer value of the exported @ref{326,,int} object.
Only valid if @ref{566a,,digits} is @code{NULL}.
@end deffn

@geindex PyLongExport.negative (C member)
@anchor{c-api/long c PyLongExport negative}@anchor{566c}
@deffn {C Μέλος} uint8_t negative

@code{1} if the number is negative, @code{0} otherwise.
Only valid if @ref{566a,,digits} is not @code{NULL}.
@end deffn

@geindex PyLongExport.ndigits (C member)
@anchor{c-api/long c PyLongExport ndigits}@anchor{566d}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} ndigits

Number of digits in @ref{566a,,digits} array.
Only valid if @code{digits} is not @code{NULL}.
@end deffn

@geindex PyLongExport.digits (C member)
@anchor{c-api/long c PyLongExport digits}@anchor{566a}
@deffn {C Μέλος} const void *digits

Read-only array of unsigned digits. Can be @code{NULL}.
@end deffn
@end deffn

@geindex PyLong_Export (C function)
@anchor{c-api/long c PyLong_Export}@anchor{5d5}
@deffn {C Συνάρτηση} int PyLong_Export (PyObject *obj, PyLongExport *export_long)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Export a Python @ref{326,,int} object.

`export_long' must point to a @ref{1970,,PyLongExport} structure allocated
by the caller. It must not be @code{NULL}.

On success, fill in `*export_long' and return @code{0}.
On error, set an exception and return @code{-1}.

@ref{5d6,,PyLong_FreeExport()} must be called when the export is no longer
needed.

@quotation

`Λεπτομέρεια υλοποίησης CPython:' This function always succeeds if `obj' is a Python @ref{326,,int} object
or a subclass.
@end quotation
@end deffn

@geindex PyLong_FreeExport (C function)
@anchor{c-api/long c PyLong_FreeExport}@anchor{5d6}
@deffn {C Συνάρτηση} void PyLong_FreeExport (PyLongExport *export_long)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Release the export `export_long' created by @ref{5d5,,PyLong_Export()}.

`Λεπτομέρεια υλοποίησης CPython:' Calling @ref{5d6,,PyLong_FreeExport()} is optional if `export_long->digits'
is @code{NULL}.
@end deffn

@node PyLongWriter API,Deprecated API,Export API,Integer Objects
@anchor{c-api/long pylongwriter-api}@anchor{566e}
@subsubsection PyLongWriter API


The @ref{1971,,PyLongWriter} API can be used to import an integer.


Added in version 3.14.


@geindex PyLongWriter (C type)
@anchor{c-api/long c PyLongWriter}@anchor{1971}
@deffn {C Τύπος} type PyLongWriter
` Μέρος του @ref{95c,,Σταθερό ABI} (ως μια αδιαφανής κατασκευή) από την έκδοση 3.15.'
A Python @ref{326,,int} writer instance.

The instance must be destroyed by @ref{5d8,,PyLongWriter_Finish()} or
@ref{5d9,,PyLongWriter_Discard()}.
@end deffn

@geindex PyLongWriter_Create (C function)
@anchor{c-api/long c PyLongWriter_Create}@anchor{5d7}
@deffn {C Συνάρτηση} @ref{1971,,PyLongWriter} *PyLongWriter_Create (int negative, Py_ssize_t ndigits, void **digits)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Create a @ref{1971,,PyLongWriter}.

On success, allocate `*digits' and return a writer.
On error, set an exception and return @code{NULL}.

`negative' is @code{1} if the number is negative, or @code{0} otherwise.

`ndigits' is the number of digits in the `digits' array. It must be
greater than 0.

`digits' must not be NULL.

After a successful call to this function, the caller should fill in the
array of digits `digits' and then call @ref{5d8,,PyLongWriter_Finish()} to get
a Python @ref{326,,int}.
The layout of `digits' is described by @ref{5d4,,PyLong_GetNativeLayout()}.

Digits must be in the range [@code{0}; @code{(1 << bits_per_digit) - 1}]
(where the @ref{5666,,bits_per_digit} is the number of bits
per digit).
Any unused most significant digits must be set to @code{0}.

Alternately, call @ref{5d9,,PyLongWriter_Discard()} to destroy the writer
instance without creating an @ref{326,,int} object.
@end deffn

@geindex PyLongWriter_Finish (C function)
@anchor{c-api/long c PyLongWriter_Finish}@anchor{5d8}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyLongWriter_Finish (PyLongWriter *writer)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Finish a @ref{1971,,PyLongWriter} created by @ref{5d7,,PyLongWriter_Create()}.

On success, return a Python @ref{326,,int} object.
On error, set an exception and return @code{NULL}.

The function takes care of normalizing the digits and converts the object
to a compact integer if needed.

The writer instance and the `digits' array are invalid after the call.
@end deffn

@geindex PyLongWriter_Discard (C function)
@anchor{c-api/long c PyLongWriter_Discard}@anchor{5d9}
@deffn {C Συνάρτηση} void PyLongWriter_Discard (PyLongWriter *writer)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Discard a @ref{1971,,PyLongWriter} created by @ref{5d7,,PyLongWriter_Create()}.

If `writer' is @code{NULL}, no operation is performed.

The writer instance and the `digits' array are invalid after the call.
@end deffn

@node Deprecated API,,PyLongWriter API,Integer Objects
@anchor{c-api/long deprecated-api}@anchor{566f}
@subsubsection Deprecated API


These macros are @ref{1a7,,soft deprecated}. They describe parameters
of the internal representation of @ref{5cb,,PyLongObject} instances.

Use @ref{5d4,,PyLong_GetNativeLayout()} instead, along with @ref{5d5,,PyLong_Export()}
to read integer data or @ref{1971,,PyLongWriter} to write it.
These currently use the same layout, but are designed to continue working correctly
even if CPython’s internal integer representation changes.

@geindex PyLong_SHIFT (C macro)
@anchor{c-api/long c PyLong_SHIFT}@anchor{5670}
@deffn {C Μακροεντολή} PyLong_SHIFT

This is equivalent to @ref{5666,,bits_per_digit} in
the output of @ref{5d4,,PyLong_GetNativeLayout()}.
@end deffn

@geindex PyLong_BASE (C macro)
@anchor{c-api/long c PyLong_BASE}@anchor{1df7}
@deffn {C Μακροεντολή} PyLong_BASE

This is currently equivalent to 1 << @ref{5670,,PyLong_SHIFT}.
@end deffn

@geindex PyLong_MASK (C macro)
@anchor{c-api/long c PyLong_MASK}@anchor{5671}
@deffn {C Μακροεντολή} PyLong_MASK

This is currently equivalent to (1 << @ref{5670,,PyLong_SHIFT}) - 1
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Boolean Objects,Floating-Point Objects,Integer Objects,Numeric Objects
@anchor{c-api/bool doc}@anchor{5672}@anchor{c-api/bool boolean-objects}@anchor{5673}@anchor{c-api/bool boolobjects}@anchor{5674}@anchor{c-api/bool translation-repo}@anchor{5675}
@subsubsection Boolean Objects


Booleans in Python are implemented as a subclass of integers.  There are only
two booleans, @ref{5676,,Py_False} and @ref{5677,,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{529c}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyBool_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This instance of @ref{e6b,,PyTypeObject} represents the Python boolean type; it
is the same object as @ref{5ef,,bool} in the Python layer.
@end deffn

@geindex PyBool_Check (C function)
@anchor{c-api/bool c PyBool_Check}@anchor{5678}
@deffn {C Συνάρτηση} int PyBool_Check (PyObject *o)

Return true if `o' is of type @ref{529c,,PyBool_Type}.  This function always
succeeds.
@end deffn

@geindex Py_False (C var)
@anchor{c-api/bool c Py_False}@anchor{5676}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *Py_False

The Python @code{False} object.  This object has no methods and is
@ref{398,,immortal}.


Άλλαξε στην έκδοση 3.12: @ref{5676,,Py_False} is @ref{398,,immortal}.

@end deffn

@geindex Py_True (C var)
@anchor{c-api/bool c Py_True}@anchor{5677}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *Py_True

The Python @code{True} object.  This object has no methods and is
@ref{398,,immortal}.


Άλλαξε στην έκδοση 3.12: @ref{5677,,Py_True} is @ref{398,,immortal}.

@end deffn

@geindex Py_RETURN_FALSE (C macro)
@anchor{c-api/bool c Py_RETURN_FALSE}@anchor{1817}
@deffn {C Μακροεντολή} Py_RETURN_FALSE

Return @ref{5676,,Py_False} from a function.
@end deffn

@geindex Py_RETURN_TRUE (C macro)
@anchor{c-api/bool c Py_RETURN_TRUE}@anchor{1816}
@deffn {C Μακροεντολή} Py_RETURN_TRUE

Return @ref{5677,,Py_True} from a function.
@end deffn

@geindex PyBool_FromLong (C function)
@anchor{c-api/bool c PyBool_FromLong}@anchor{529b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyBool_FromLong (long v)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return @ref{5677,,Py_True} or @ref{5676,,Py_False}, depending on the truth value of `v'.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Floating-Point Objects,Complex Number Objects,Boolean Objects,Numeric Objects
@anchor{c-api/float doc}@anchor{5679}@anchor{c-api/float floating-point-objects}@anchor{567a}@anchor{c-api/float floatobjects}@anchor{567b}@anchor{c-api/float translation-repo}@anchor{567c}
@subsubsection Floating-Point Objects


@geindex object;floating-point

@geindex PyFloatObject (C type)
@anchor{c-api/float c PyFloatObject}@anchor{567d}
@deffn {C Τύπος} type PyFloatObject

This subtype of @ref{19b,,PyObject} represents a Python floating-point object.
@end deffn

@geindex PyFloat_Type (C var)
@anchor{c-api/float c PyFloat_Type}@anchor{5355}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyFloat_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This instance of @ref{e6b,,PyTypeObject} represents the Python floating-point
type.  This is the same object as @ref{327,,float} in the Python layer.
@end deffn

@geindex PyFloat_Check (C function)
@anchor{c-api/float c PyFloat_Check}@anchor{567e}
@deffn {C Συνάρτηση} int PyFloat_Check (PyObject *p)

Return true if its argument is a @ref{567d,,PyFloatObject} or a subtype of
@code{PyFloatObject}.  This function always succeeds.
@end deffn

@geindex PyFloat_CheckExact (C function)
@anchor{c-api/float c PyFloat_CheckExact}@anchor{567f}
@deffn {C Συνάρτηση} int PyFloat_CheckExact (PyObject *p)

Return true if its argument is a @ref{567d,,PyFloatObject}, but not a subtype of
@code{PyFloatObject}.  This function always succeeds.
@end deffn

@geindex PyFloat_FromString (C function)
@anchor{c-api/float c PyFloat_FromString}@anchor{5354}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFloat_FromString (PyObject *str)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a @ref{567d,,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{5353}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFloat_FromDouble (double v)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a @ref{567d,,PyFloatObject} object from `v', or @code{NULL} on failure.
@end deffn

@geindex PyFloat_AsDouble (C function)
@anchor{c-api/float c PyFloat_AsDouble}@anchor{e2e}
@deffn {C Συνάρτηση} double PyFloat_AsDouble (PyObject *pyfloat)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a C double representation of the contents of `pyfloat'.  If
`pyfloat' is not a Python floating-point object but has a @ref{d92,,__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{43d,,__index__()}.
This method returns @code{-1.0} upon failure, so one should call
@ref{1ea5,,PyErr_Occurred()} to check for errors.


Άλλαξε στην έκδοση 3.8: Use @ref{43d,,__index__()} if available.

@end deffn

@geindex PyFloat_AS_DOUBLE (C function)
@anchor{c-api/float c PyFloat_AS_DOUBLE}@anchor{5680}
@deffn {C Συνάρτηση} 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{1793}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFloat_GetInfo (void)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a structseq instance which contains information about the
precision, minimum and maximum values of a float. It’s a thin wrapper
around the header file @code{float.h}.
@end deffn

@geindex PyFloat_GetMax (C function)
@anchor{c-api/float c PyFloat_GetMax}@anchor{1791}
@deffn {C Συνάρτηση} double PyFloat_GetMax ()
` Μέρος του @ref{95c,,Σταθερό 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{1792}
@deffn {C Συνάρτηση} double PyFloat_GetMin ()
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the minimum normalized positive float `DBL_MIN' as C double.
@end deffn

@geindex Py_INFINITY (C macro)
@anchor{c-api/float c Py_INFINITY}@anchor{5681}
@deffn {C Μακροεντολή} Py_INFINITY

This macro expands to a constant expression of type double, that
represents the positive infinity.

It is equivalent to the @code{INFINITY} macro from the C11 standard
@code{<math.h>} header.


@ref{1a7,,Soft deprecated} since version 3.15.

@end deffn

@geindex Py_NAN (C macro)
@anchor{c-api/float c Py_NAN}@anchor{5682}
@deffn {C Μακροεντολή} Py_NAN

This macro expands to a constant expression of type double, that
represents a quiet not-a-number (qNaN) value.

On most platforms, this is equivalent to the @code{NAN} macro from
the C11 standard @code{<math.h>} header.
@end deffn

@geindex Py_HUGE_VAL (C macro)
@anchor{c-api/float c Py_HUGE_VAL}@anchor{5683}
@deffn {C Μακροεντολή} Py_HUGE_VAL

Equivalent to @code{INFINITY}.


@ref{1a7,,Soft deprecated} since version 3.14.

@end deffn

@geindex Py_MATH_E (C macro)
@anchor{c-api/float c Py_MATH_E}@anchor{5684}
@deffn {C Μακροεντολή} Py_MATH_E

The definition (accurate for a double type) of the @ref{2c94,,math.e} constant.
@end deffn

@geindex Py_MATH_El (C macro)
@anchor{c-api/float c Py_MATH_El}@anchor{5685}
@deffn {C Μακροεντολή} Py_MATH_El

High precision (long double) definition of @ref{2c94,,e} constant.


Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.20.

@end deffn

@geindex Py_MATH_PI (C macro)
@anchor{c-api/float c Py_MATH_PI}@anchor{5686}
@deffn {C Μακροεντολή} Py_MATH_PI

The definition (accurate for a double type) of the @ref{2c93,,math.pi} constant.
@end deffn

@geindex Py_MATH_PIl (C macro)
@anchor{c-api/float c Py_MATH_PIl}@anchor{5687}
@deffn {C Μακροεντολή} Py_MATH_PIl

High precision (long double) definition of @ref{2c93,,pi} constant.


Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.20.

@end deffn

@geindex Py_MATH_TAU (C macro)
@anchor{c-api/float c Py_MATH_TAU}@anchor{5688}
@deffn {C Μακροεντολή} Py_MATH_TAU

The definition (accurate for a double type) of the @ref{2c95,,math.tau} constant.


Added in version 3.6.

@end deffn

@geindex Py_RETURN_NAN (C macro)
@anchor{c-api/float c Py_RETURN_NAN}@anchor{5689}
@deffn {C Μακροεντολή} Py_RETURN_NAN

Return @ref{a53,,math.nan} from a function.

On most platforms, this is equivalent to @code{return PyFloat_FromDouble(NAN)}.
@end deffn

@geindex Py_RETURN_INF (C macro)
@anchor{c-api/float c Py_RETURN_INF}@anchor{568a}
@deffn {C Μακροεντολή} Py_RETURN_INF (sign)

Return @ref{1043,,math.inf} or @code{-math.inf} from a function,
depending on the sign of `sign'.

On most platforms, this is equivalent to the following:

@example
return PyFloat_FromDouble(copysign(INFINITY, sign));
@end example
@end deffn

@geindex Py_IS_FINITE (C macro)
@anchor{c-api/float c Py_IS_FINITE}@anchor{568b}
@deffn {C Μακροεντολή} Py_IS_FINITE (X)

Return @code{1} if the given floating-point number `X' is finite,
that is, it is normal, subnormal or zero, but not infinite or NaN.
Return @code{0} otherwise.


@ref{1a7,,Soft deprecated} since version 3.14: Use @code{isfinite} instead.

@end deffn

@geindex Py_IS_INFINITY (C macro)
@anchor{c-api/float c Py_IS_INFINITY}@anchor{568c}
@deffn {C Μακροεντολή} Py_IS_INFINITY (X)

Return @code{1} if the given floating-point number `X' is positive or negative
infinity.  Return @code{0} otherwise.


@ref{1a7,,Soft deprecated} since version 3.14: Use @code{isinf} instead.

@end deffn

@geindex Py_IS_NAN (C macro)
@anchor{c-api/float c Py_IS_NAN}@anchor{1818}
@deffn {C Μακροεντολή} Py_IS_NAN (X)

Return @code{1} if the given floating-point number `X' is a not-a-number (NaN)
value.  Return @code{0} otherwise.


@ref{1a7,,Soft deprecated} since version 3.14: Use @code{isnan} instead.

@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{568d}
@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:


@itemize *

@item 
The 2-byte format is the IEEE 754 binary16 half-precision format.

@item 
The 4-byte format is the IEEE 754 binary32 single-precision format.

@item 
The 8-byte format is the IEEE 754 binary64 double-precision format.
@end itemize

The NaN type may not be preserved on some platforms while unpacking (signaling
NaNs become quiet NaNs), for example on x86 systems in 32-bit mode.

It’s assumed that the double type has the IEEE 754 binary64 double
precision format.  What happens if it’s not true is partly accidental (alas).
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.  The
packing of special numbers like INFs and NaNs (if such things exist on the
platform) may not be handled correctly, and attempting to unpack a bytes string
containing an IEEE INF or NaN may raise an exception.


Added in 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{568e}
@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} and @code{p+7}), zero if you
want big-endian format (exponent first, at `p'). Use the @code{PY_LITTLE_ENDIAN}
constant to select the native endian: it is equal to @code{0} on big
endian processor, or @code{1} on little endian processor.

Return value: @code{0} if all is OK, @code{-1} if error (and an exception is set,
most likely @ref{c57,,OverflowError}).

@geindex PyFloat_Pack2 (C function)
@anchor{c-api/float c PyFloat_Pack2}@anchor{b47}
@deffn {C Συνάρτηση} int PyFloat_Pack2 (double x, 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{b48}
@deffn {C Συνάρτηση} int PyFloat_Pack4 (double x, 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{b49}
@deffn {C Συνάρτηση} int PyFloat_Pack8 (double x, char *p, int le)

Pack a C double as the IEEE 754 binary64 double precision format.

`Λεπτομέρεια υλοποίησης CPython:' This function always succeeds in CPython.
@end deffn

@node Unpack functions,,Pack functions,Pack and Unpack functions
@anchor{c-api/float unpack-functions}@anchor{568f}
@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'). Use the @code{PY_LITTLE_ENDIAN} constant to
select the native endian: it is equal to @code{0} on big endian processor, or @code{1}
on little endian processor.

Return value: The unpacked double.  On error, this is @code{-1.0} and
@ref{1ea5,,PyErr_Occurred()} is true (and an exception is set, most likely
@ref{c57,,OverflowError}).

`Λεπτομέρεια υλοποίησης CPython:' These functions always succeed in CPython.

@geindex PyFloat_Unpack2 (C function)
@anchor{c-api/float c PyFloat_Unpack2}@anchor{b4a}
@deffn {C Συνάρτηση} double PyFloat_Unpack2 (const 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{b4b}
@deffn {C Συνάρτηση} double PyFloat_Unpack4 (const 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{b4c}
@deffn {C Συνάρτηση} double PyFloat_Unpack8 (const char *p, int le)

Unpack the IEEE 754 binary64 double precision format as a C double.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Complex Number Objects,,Floating-Point Objects,Numeric Objects
@anchor{c-api/complex doc}@anchor{5690}@anchor{c-api/complex complex-number-objects}@anchor{5691}@anchor{c-api/complex complexobjects}@anchor{5692}@anchor{c-api/complex translation-repo}@anchor{5693}
@subsubsection Complex Number Objects


@geindex object;complex number

@geindex PyComplexObject (C type)
@anchor{c-api/complex c PyComplexObject}@anchor{3b9}
@deffn {C Τύπος} type PyComplexObject

This subtype of @ref{19b,,PyObject} represents a Python complex number object.

@geindex PyComplexObject.cval (C member)
@anchor{c-api/complex c PyComplexObject cval}@anchor{3b8}
@deffn {C Μέλος} @ref{3bc,,Py_complex} cval

The complex number value, using the C @ref{3bc,,Py_complex} representation.


Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.20: Use @ref{3ba,,PyComplex_AsCComplex()} and
@ref{3bb,,PyComplex_FromCComplex()} to convert a
Python complex number to/from the C @ref{3bc,,Py_complex}
representation.

@end deffn
@end deffn

@geindex PyComplex_Type (C var)
@anchor{c-api/complex c PyComplex_Type}@anchor{52d3}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyComplex_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This instance of @ref{e6b,,PyTypeObject} represents the Python complex number
type. It is the same object as @ref{328,,complex} in the Python layer.
@end deffn

@geindex PyComplex_Check (C function)
@anchor{c-api/complex c PyComplex_Check}@anchor{5694}
@deffn {C Συνάρτηση} int PyComplex_Check (PyObject *p)

Return true if its argument is a @ref{3b9,,PyComplexObject} or a subtype of
@code{PyComplexObject}.  This function always succeeds.
@end deffn

@geindex PyComplex_CheckExact (C function)
@anchor{c-api/complex c PyComplex_CheckExact}@anchor{5695}
@deffn {C Συνάρτηση} int PyComplex_CheckExact (PyObject *p)

Return true if its argument is a @ref{3b9,,PyComplexObject}, but not a subtype of
@code{PyComplexObject}.  This function always succeeds.
@end deffn

@geindex PyComplex_FromDoubles (C function)
@anchor{c-api/complex c PyComplex_FromDoubles}@anchor{52d2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyComplex_FromDoubles (double real, double imag)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a new @ref{3b9,,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{1c1a}
@deffn {C Συνάρτηση} double PyComplex_RealAsDouble (PyObject *op)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the real part of `op' as a C double.

If `op' is not a Python complex number object but has a
@ref{9de,,__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{e2e,,PyFloat_AsDouble()} and
returns its result.

Upon failure, this method returns @code{-1.0} with an exception set, so one
should call @ref{1ea5,,PyErr_Occurred()} to check for errors.


Άλλαξε στην έκδοση 3.13: Use @ref{9de,,__complex__()} if available.

@end deffn

@geindex PyComplex_ImagAsDouble (C function)
@anchor{c-api/complex c PyComplex_ImagAsDouble}@anchor{1c1b}
@deffn {C Συνάρτηση} double PyComplex_ImagAsDouble (PyObject *op)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the imaginary part of `op' as a C double.

If `op' is not a Python complex number object but has a
@ref{9de,,__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{e2e,,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{1ea5,,PyErr_Occurred()} to check for errors.


Άλλαξε στην έκδοση 3.13: Use @ref{9de,,__complex__()} if available.

@end deffn

@geindex Py_complex (C type)
@anchor{c-api/complex c Py_complex}@anchor{3bc}
@deffn {C Τύπος} type Py_complex

This C structure defines an export format for a Python complex
number object.

@geindex Py_complex.real (C member)
@geindex Py_complex.imag (C member)
@anchor{c-api/complex c Py_complex real}@anchor{5696}
@deffn {C Μέλος} double real
@anchor{c-api/complex c Py_complex imag}@anchor{5697}
@deffnx {C Μέλος} double imag
@end deffn

The structure is defined as:

@example
typedef struct @{
    double real;
    double imag;
@} Py_complex;
@end example
@end deffn

@geindex PyComplex_FromCComplex (C function)
@anchor{c-api/complex c PyComplex_FromCComplex}@anchor{3bb}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyComplex_FromCComplex (Py_complex v)
`Επιστρεφόμενη τιμή: New reference.'
Create a new Python complex number object from a C @ref{3bc,,Py_complex} value.
Return @code{NULL} with an exception set on error.
@end deffn

@geindex PyComplex_AsCComplex (C function)
@anchor{c-api/complex c PyComplex_AsCComplex}@anchor{3ba}
@deffn {C Συνάρτηση} @ref{3bc,,Py_complex} PyComplex_AsCComplex (PyObject *op)

Return the @ref{3bc,,Py_complex} value of the complex number `op'.

If `op' is not a Python complex number object but has a @ref{9de,,__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{d92,,__float__()}.  If @code{__float__()} is not defined then it falls back
to @ref{43d,,__index__()}.

Upon failure, this method returns @ref{3bc,,Py_complex}
with @ref{5696,,real} set to @code{-1.0} and with an exception set, so one
should call @ref{1ea5,,PyErr_Occurred()} to check for errors.


Άλλαξε στην έκδοση 3.8: Use @ref{43d,,__index__()} if available.

@end deffn

@menu
* Complex Numbers as C Structures:: 

@end menu

@node Complex Numbers as C Structures,,,Complex Number Objects
@anchor{c-api/complex complex-numbers-as-c-structures}@anchor{5698}
@subsubsection Complex Numbers as C Structures


The API also provides functions for working with complex numbers, using the
@ref{3bc,,Py_complex} representation.  Note that the functions which accept
these structures as parameters and return them as results do so `by value'
rather than dereferencing them through pointers.

Please note, that these functions are @ref{1a7,,soft deprecated} since Python
3.15.  Avoid using this API in a new code to do complex arithmetic: either use
the Number Protocol@footnote{number} API or use native complex types, like
double complex.

@geindex _Py_c_sum (C function)
@anchor{c-api/complex c _Py_c_sum}@anchor{3bd}
@deffn {C Συνάρτηση} @ref{3bc,,Py_complex} _Py_c_sum (Py_complex left, Py_complex right)

Return the sum of two complex numbers, using the C @ref{3bc,,Py_complex}
representation.


Αποσύρθηκε στην έκδοση 3.15.

@end deffn

@geindex _Py_c_diff (C function)
@anchor{c-api/complex c _Py_c_diff}@anchor{3be}
@deffn {C Συνάρτηση} @ref{3bc,,Py_complex} _Py_c_diff (Py_complex left, Py_complex right)

Return the difference between two complex numbers, using the C
@ref{3bc,,Py_complex} representation.


Αποσύρθηκε στην έκδοση 3.15.

@end deffn

@geindex _Py_c_neg (C function)
@anchor{c-api/complex c _Py_c_neg}@anchor{3bf}
@deffn {C Συνάρτηση} @ref{3bc,,Py_complex} _Py_c_neg (Py_complex num)

Return the negation of the complex number `num', using the C
@ref{3bc,,Py_complex} representation.


Αποσύρθηκε στην έκδοση 3.15.

@end deffn

@geindex _Py_c_prod (C function)
@anchor{c-api/complex c _Py_c_prod}@anchor{3c0}
@deffn {C Συνάρτηση} @ref{3bc,,Py_complex} _Py_c_prod (Py_complex left, Py_complex right)

Return the product of two complex numbers, using the C @ref{3bc,,Py_complex}
representation.


Αποσύρθηκε στην έκδοση 3.15.

@end deffn

@geindex _Py_c_quot (C function)
@anchor{c-api/complex c _Py_c_quot}@anchor{3c1}
@deffn {C Συνάρτηση} @ref{3bc,,Py_complex} _Py_c_quot (Py_complex dividend, Py_complex divisor)

Return the quotient of two complex numbers, using the C @ref{3bc,,Py_complex}
representation.

If `divisor' is null, this method returns zero and sets
@code{errno} to @code{EDOM}.


Αποσύρθηκε στην έκδοση 3.15.

@end deffn

@geindex _Py_c_pow (C function)
@anchor{c-api/complex c _Py_c_pow}@anchor{3c2}
@deffn {C Συνάρτηση} @ref{3bc,,Py_complex} _Py_c_pow (Py_complex num, Py_complex exp)

Return the exponentiation of `num' by `exp', using the C @ref{3bc,,Py_complex}
representation.

If `num' is null and `exp' is not a positive real number,
this method returns zero and sets @code{errno} to @code{EDOM}.

Set @code{errno} to @code{ERANGE} on overflows.


Αποσύρθηκε στην έκδοση 3.15.

@end deffn

@geindex _Py_c_abs (C function)
@anchor{c-api/complex c _Py_c_abs}@anchor{3c3}
@deffn {C Συνάρτηση} double _Py_c_abs (Py_complex num)

Return the absolute value of the complex number `num'.

Set @code{errno} to @code{ERANGE} on overflows.


Αποσύρθηκε στην έκδοση 3.15.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Sequence Objects,Container Objects,Numeric Objects,Concrete Objects Layer
@anchor{c-api/concrete sequence-objects}@anchor{5699}@anchor{c-api/concrete sequenceobjects}@anchor{569a}
@subsection Sequence Objects


@geindex object;sequence

Generic operations on sequence objects were discussed in the previous chapter;
this section deals with the specific kinds of sequence objects that are
intrinsic to the Python language.

@c XXX sort out unicode, str, bytes and bytearray

@menu
* Bytes Objects:: 
* PyBytesWriter:: 
* Byte Array Objects:: 
* Unicode Objects and Codecs:: 
* Tuple Objects:: 
* Struct Sequence Objects:: 
* List Objects:: 

@end menu

@node Bytes Objects,PyBytesWriter,,Sequence Objects
@anchor{c-api/bytes doc}@anchor{569b}@anchor{c-api/bytes bytes-objects}@anchor{569c}@anchor{c-api/bytes bytesobjects}@anchor{569d}
@subsubsection Bytes Objects


These functions raise @ref{291,,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{b71}
@deffn {C Τύπος} type PyBytesObject

This subtype of @ref{19b,,PyObject} represents a Python bytes object.
@end deffn

@geindex PyBytes_Type (C var)
@anchor{c-api/bytes c PyBytes_Type}@anchor{52ad}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyBytes_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This instance of @ref{e6b,,PyTypeObject} represents the Python bytes type; it
is the same object as @ref{1c7,,bytes} in the Python layer.
@end deffn

@geindex PyBytes_Check (C function)
@anchor{c-api/bytes c PyBytes_Check}@anchor{1743}
@deffn {C Συνάρτηση} 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{569e}
@deffn {C Συνάρτηση} 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{52aa}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyBytes_FromString (const char *v)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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{3b2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyBytes_FromStringAndSize (const char *v, Py_ssize_t len)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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.


@ref{1a7,,Soft deprecated} since version 3.15: Use the @ref{3b4,,PyBytesWriter} API instead of
@code{PyBytes_FromStringAndSize(NULL, len)}.

@end deffn

@geindex PyBytes_FromFormat (C function)
@anchor{c-api/bytes c PyBytes_FromFormat}@anchor{1ffa}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyBytes_FromFormat (const char *format, ...)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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

Format Characters

@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

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

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{e24,,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{52a8}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyBytes_FromFormatV (const char *format, va_list vargs)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Identical to @ref{1ffa,,PyBytes_FromFormat()} except that it takes exactly two
arguments.
@end deffn

@geindex PyBytes_FromObject (C function)
@anchor{c-api/bytes c PyBytes_FromObject}@anchor{52a9}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyBytes_FromObject (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Return the bytes representation of object `o' that implements the buffer
protocol.

@cartouche
@quotation Σημείωση 
If the object implements the buffer protocol, then the buffer
must not be mutated while the bytes object is being created.
@end quotation
@end cartouche
@end deffn

@geindex PyBytes_Size (C function)
@anchor{c-api/bytes c PyBytes_Size}@anchor{52ac}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyBytes_Size (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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{569f}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyBytes_GET_SIZE (PyObject *o)
` Thread safety: @ref{292b,,Atomic}.'
Similar to @ref{52ac,,PyBytes_Size()}, but without error checking.
@end deffn

@geindex PyBytes_AsString (C function)
@anchor{c-api/bytes c PyBytes_AsString}@anchor{c5d}
@deffn {C Συνάρτηση} char *PyBytes_AsString (PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
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{c5d,,PyBytes_AsString()} returns @code{NULL}
and raises @ref{291,,TypeError}.
@end deffn

@geindex PyBytes_AS_STRING (C function)
@anchor{c-api/bytes c PyBytes_AS_STRING}@anchor{56a0}
@deffn {C Συνάρτηση} char *PyBytes_AS_STRING (PyObject *string)
` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Similar to @ref{c5d,,PyBytes_AsString()}, but without error checking.
@end deffn

@geindex PyBytes_AsStringAndSize (C function)
@anchor{c-api/bytes c PyBytes_AsStringAndSize}@anchor{52a4}
@deffn {C Συνάρτηση} int PyBytes_AsStringAndSize (PyObject *obj, char **buffer, Py_ssize_t *length)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
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{277,,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{52a4,,PyBytes_AsStringAndSize()}
returns @code{-1} and raises @ref{291,,TypeError}.


Άλλαξε στην έκδοση 3.5: Previously, @ref{291,,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{52a5}
@deffn {C Συνάρτηση} void PyBytes_Concat (PyObject **bytes, PyObject *newpart)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
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.

@cartouche
@quotation Σημείωση 
If `newpart' implements the buffer protocol, then the buffer
must not be mutated while the new bytes object is being created.
@end quotation
@end cartouche
@end deffn

@geindex PyBytes_ConcatAndDel (C function)
@anchor{c-api/bytes c PyBytes_ConcatAndDel}@anchor{52a6}
@deffn {C Συνάρτηση} void PyBytes_ConcatAndDel (PyObject **bytes, PyObject *newpart)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Create a new bytes object in `*bytes' containing the contents of `newpart'
appended to `bytes'.  This version releases the @ref{7da,,strong reference}
to `newpart' (i.e. decrements its reference count).

@cartouche
@quotation Σημείωση 
If `newpart' implements the buffer protocol, then the buffer
must not be mutated while the new bytes object is being created.
@end quotation
@end cartouche
@end deffn

@geindex PyBytes_Join (C function)
@anchor{c-api/bytes c PyBytes_Join}@anchor{5b0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyBytes_Join (PyObject *sep, PyObject *iterable)
` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Similar to @code{sep.join(iterable)} in Python.

`sep' must be Python @ref{1c7,,bytes} object.
(Note that @ref{154b,,PyUnicode_Join()} accepts @code{NULL} separator and treats
it as a space, whereas @ref{5b0,,PyBytes_Join()} doesn’t accept @code{NULL}
separator.)

`iterable' must be an iterable object yielding objects that implement the
@ref{311,,buffer protocol}.

On success, return a new @ref{1c7,,bytes} object.
On error, set an exception and return @code{NULL}.


Added in version 3.14.


@cartouche
@quotation Σημείωση 
If `iterable' objects implement the buffer protocol, then the buffers
must not be mutated while the new bytes object is being created.
@end quotation
@end cartouche
@end deffn

@geindex _PyBytes_Resize (C function)
@anchor{c-api/bytes c _PyBytes_Resize}@anchor{3b3}
@deffn {C Συνάρτηση} int _PyBytes_Resize (PyObject **bytes, Py_ssize_t newsize)
` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
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{18fa,,MemoryError} is set, and @code{-1} is
returned.


@ref{1a7,,Soft deprecated} since version 3.15: Use the @ref{3b4,,PyBytesWriter} API instead.

@end deffn

@geindex PyBytes_Repr (C function)
@anchor{c-api/bytes c PyBytes_Repr}@anchor{52ab}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyBytes_Repr (PyObject *bytes, int smartquotes)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Get the string representation of `bytes'. This function is currently used to
implement @code{bytes.__repr__()} in Python.

This function does not do type checking; it is undefined behavior to pass
`bytes' as a non-bytes object or @code{NULL}.

If `smartquotes' is true, the representation will use a double-quoted string
instead of single-quoted string when single-quotes are present in `bytes'.
For example, the byte string @code{'Python'} would be represented as
@code{b"'Python'"} when `smartquotes' is true, or @code{b'\'Python\'@w{'}} when it is
false.

On success, this function returns a @ref{7da,,strong reference} to a
@ref{1df,,str} object containing the representation. On failure, this
returns @code{NULL} with an exception set.
@end deffn

@geindex PyBytes_DecodeEscape (C function)
@anchor{c-api/bytes c PyBytes_DecodeEscape}@anchor{52a7}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyBytes_DecodeEscape (const char *s, Py_ssize_t len, const char *errors, Py_ssize_t unicode, const char *recode_encoding)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Unescape a backslash-escaped string `s'. `s' must not be @code{NULL}.
`len' must be the size of `s'.

`errors' must be one of @code{"strict"}, @code{"replace"}, or @code{"ignore"}. If
`errors' is @code{NULL}, then @code{"strict"} is used by default.

On success, this function returns a @ref{7da,,strong reference} to a Python
@ref{1c7,,bytes} object containing the unescaped string. On failure, this
function returns @code{NULL} with an exception set.


Άλλαξε στην έκδοση 3.9: `unicode' and `recode_encoding' are now unused.

@end deffn

@node PyBytesWriter,Byte Array Objects,Bytes Objects,Sequence Objects
@anchor{c-api/bytes id10}@anchor{56a1}@anchor{c-api/bytes pybyteswriter}@anchor{35b}
@subsubsection PyBytesWriter


The @ref{3b4,,PyBytesWriter} API can be used to create a Python @ref{1c7,,bytes}
object.


Added in version 3.15.


@geindex PyBytesWriter (C type)
@anchor{c-api/bytes c PyBytesWriter}@anchor{3b4}
@deffn {C Τύπος} type PyBytesWriter

A bytes writer instance.

The API is `not thread safe': a writer should only be used by a single
thread at the same time.

The instance must be destroyed by @ref{360,,PyBytesWriter_Finish()} on
success, or @ref{35d,,PyBytesWriter_Discard()} on error.
@end deffn

@menu
* Create@comma{} Finish@comma{} Discard: Create Finish Discard. 
* High-level API:: 
* Getters:: 
* Low-level API:: 

@end menu

@node Create Finish Discard,High-level API,,PyBytesWriter
@anchor{c-api/bytes create-finish-discard}@anchor{56a2}
@subsubsection Create, Finish, Discard


@geindex PyBytesWriter_Create (C function)
@anchor{c-api/bytes c PyBytesWriter_Create}@anchor{35c}
@deffn {C Συνάρτηση} @ref{3b4,,PyBytesWriter} *PyBytesWriter_Create (Py_ssize_t size)

Create a @ref{3b4,,PyBytesWriter} to write `size' bytes.

If `size' is greater than zero, allocate `size' bytes, and set the
writer size to `size'. The caller is responsible to write `size'
bytes using @ref{362,,PyBytesWriter_GetData()}.
This function does not overallocate.

On error, set an exception and return @code{NULL}.

`size' must be positive or zero.
@end deffn

@geindex PyBytesWriter_Finish (C function)
@anchor{c-api/bytes c PyBytesWriter_Finish}@anchor{360}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyBytesWriter_Finish (PyBytesWriter *writer)

Finish a @ref{3b4,,PyBytesWriter} created by
@ref{35c,,PyBytesWriter_Create()}.

On success, return a Python @ref{1c7,,bytes} object.
On error, set an exception and return @code{NULL}.

The writer instance is invalid after the call in any case.
No API can be called on the writer after @ref{360,,PyBytesWriter_Finish()}.
@end deffn

@geindex PyBytesWriter_FinishWithSize (C function)
@anchor{c-api/bytes c PyBytesWriter_FinishWithSize}@anchor{35f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyBytesWriter_FinishWithSize (PyBytesWriter *writer, Py_ssize_t size)

Similar to @ref{360,,PyBytesWriter_Finish()}, but resize the writer
to `size' bytes before creating the @ref{1c7,,bytes} object.
@end deffn

@geindex PyBytesWriter_FinishWithPointer (C function)
@anchor{c-api/bytes c PyBytesWriter_FinishWithPointer}@anchor{35e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyBytesWriter_FinishWithPointer (PyBytesWriter *writer, void *buf)

Similar to @ref{360,,PyBytesWriter_Finish()}, but resize the writer
using `buf' pointer before creating the @ref{1c7,,bytes} object.

Set an exception and return @code{NULL} if `buf' pointer is outside the
internal buffer bounds.

Function pseudo-code:

@example
Py_ssize_t size = (char*)buf - (char*)PyBytesWriter_GetData(writer);
return PyBytesWriter_FinishWithSize(writer, size);
@end example
@end deffn

@geindex PyBytesWriter_Discard (C function)
@anchor{c-api/bytes c PyBytesWriter_Discard}@anchor{35d}
@deffn {C Συνάρτηση} void PyBytesWriter_Discard (PyBytesWriter *writer)

Discard a @ref{3b4,,PyBytesWriter} created by @ref{35c,,PyBytesWriter_Create()}.

Do nothing if `writer' is @code{NULL}.

The writer instance is invalid after the call.
No API can be called on the writer after @ref{35d,,PyBytesWriter_Discard()}.
@end deffn

@node High-level API,Getters,Create Finish Discard,PyBytesWriter
@anchor{c-api/bytes high-level-api}@anchor{56a3}
@subsubsection High-level API


@geindex PyBytesWriter_WriteBytes (C function)
@anchor{c-api/bytes c PyBytesWriter_WriteBytes}@anchor{367}
@deffn {C Συνάρτηση} int PyBytesWriter_WriteBytes (PyBytesWriter *writer, const void *bytes, Py_ssize_t size)

Grow the `writer' internal buffer by `size' bytes,
write `size' bytes of `bytes' at the `writer' end,
and add `size' to the `writer' size.

If `size' is equal to @code{-1}, call @code{strlen(bytes)} to get the
string length.

On success, return @code{0}.
On error, set an exception and return @code{-1}.
@end deffn

@geindex PyBytesWriter_Format (C function)
@anchor{c-api/bytes c PyBytesWriter_Format}@anchor{361}
@deffn {C Συνάρτηση} int PyBytesWriter_Format (PyBytesWriter *writer, const char *format, ...)

Similar to @ref{1ffa,,PyBytes_FromFormat()}, but write the output directly at
the writer end. Grow the writer internal buffer on demand. Then add the
written size to the writer size.

On success, return @code{0}.
On error, set an exception and return @code{-1}.
@end deffn

@node Getters,Low-level API,High-level API,PyBytesWriter
@anchor{c-api/bytes getters}@anchor{56a4}
@subsubsection Getters


@geindex PyBytesWriter_GetSize (C function)
@anchor{c-api/bytes c PyBytesWriter_GetSize}@anchor{363}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyBytesWriter_GetSize (PyBytesWriter *writer)

Get the writer size.

The function cannot fail.
@end deffn

@geindex PyBytesWriter_GetData (C function)
@anchor{c-api/bytes c PyBytesWriter_GetData}@anchor{362}
@deffn {C Συνάρτηση} void *PyBytesWriter_GetData (PyBytesWriter *writer)

Get the writer data: start of the internal buffer.

The pointer is valid until @ref{360,,PyBytesWriter_Finish()} or
@ref{35d,,PyBytesWriter_Discard()} is called on `writer'.

The function cannot fail.
@end deffn

@node Low-level API,,Getters,PyBytesWriter
@anchor{c-api/bytes low-level-api}@anchor{56a5}
@subsubsection Low-level API


@geindex PyBytesWriter_Resize (C function)
@anchor{c-api/bytes c PyBytesWriter_Resize}@anchor{366}
@deffn {C Συνάρτηση} int PyBytesWriter_Resize (PyBytesWriter *writer, Py_ssize_t size)

Resize the writer to `size' bytes. It can be used to enlarge or to
shrink the writer.
This function typically overallocates to achieve amortized performance when
resizing multiple times.

Newly allocated bytes are left uninitialized.

On success, return @code{0}.
On error, set an exception and return @code{-1}.

`size' must be positive or zero.
@end deffn

@geindex PyBytesWriter_Grow (C function)
@anchor{c-api/bytes c PyBytesWriter_Grow}@anchor{365}
@deffn {C Συνάρτηση} int PyBytesWriter_Grow (PyBytesWriter *writer, Py_ssize_t grow)

Resize the writer by adding `grow' bytes to the current writer size.
This function typically overallocates to achieve amortized performance when
resizing multiple times.

Newly allocated bytes are left uninitialized.

On success, return @code{0}.
On error, set an exception and return @code{-1}.

`size' can be negative to shrink the writer.
@end deffn

@geindex PyBytesWriter_GrowAndUpdatePointer (C function)
@anchor{c-api/bytes c PyBytesWriter_GrowAndUpdatePointer}@anchor{364}
@deffn {C Συνάρτηση} void *PyBytesWriter_GrowAndUpdatePointer (PyBytesWriter *writer, Py_ssize_t size, void *buf)

Similar to @ref{365,,PyBytesWriter_Grow()}, but update also the `buf'
pointer.

The `buf' pointer is moved if the internal buffer is moved in memory.
The `buf' relative position within the internal buffer is left
unchanged.

On error, set an exception and return @code{NULL}.

`buf' must not be @code{NULL}.

Function pseudo-code:

@example
Py_ssize_t pos = (char*)buf - (char*)PyBytesWriter_GetData(writer);
if (PyBytesWriter_Grow(writer, size) < 0) @{
    return NULL;
@}
return (char*)PyBytesWriter_GetData(writer) + pos;
@end example
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Byte Array Objects,Unicode Objects and Codecs,PyBytesWriter,Sequence Objects
@anchor{c-api/bytearray doc}@anchor{56a6}@anchor{c-api/bytearray byte-array-objects}@anchor{56a7}@anchor{c-api/bytearray bytearrayobjects}@anchor{56a8}@anchor{c-api/bytearray translation-repo}@anchor{56a9}
@subsubsection Byte Array Objects


@geindex object;bytearray

@geindex PyByteArrayObject (C type)
@anchor{c-api/bytearray c PyByteArrayObject}@anchor{56aa}
@deffn {C Τύπος} type PyByteArrayObject

This subtype of @ref{19b,,PyObject} represents a Python bytearray object.
@end deffn

@geindex PyByteArray_Type (C var)
@anchor{c-api/bytearray c PyByteArray_Type}@anchor{52a2}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyByteArray_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This instance of @ref{e6b,,PyTypeObject} represents the Python bytearray type;
it is the same object as @ref{1c6,,bytearray} in the Python layer.
@end deffn

@menu
* Type check macros:: 
* Direct API functions:: 
* Macros:: 

@end menu

@node Type check macros,Direct API functions,,Byte Array Objects
@anchor{c-api/bytearray type-check-macros}@anchor{56ab}
@subsubsection Type check macros


@geindex PyByteArray_Check (C function)
@anchor{c-api/bytearray c PyByteArray_Check}@anchor{56ac}
@deffn {C Συνάρτηση} int PyByteArray_Check (PyObject *o)

Return true if the object `o' is a bytearray object or an instance of a
subtype of the bytearray type.  This function always succeeds.
@end deffn

@geindex PyByteArray_CheckExact (C function)
@anchor{c-api/bytearray c PyByteArray_CheckExact}@anchor{56ad}
@deffn {C Συνάρτηση} int PyByteArray_CheckExact (PyObject *o)

Return true if the object `o' is a bytearray object, but not an instance of a
subtype of the bytearray type.  This function always succeeds.
@end deffn

@node Direct API functions,Macros,Type check macros,Byte Array Objects
@anchor{c-api/bytearray direct-api-functions}@anchor{56ae}
@subsubsection Direct API functions


@geindex PyByteArray_FromObject (C function)
@anchor{c-api/bytearray c PyByteArray_FromObject}@anchor{174b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyByteArray_FromObject (PyObject *o)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Return a new bytearray object from any object, `o', that implements the
@ref{311,,buffer protocol}.

On failure, return @code{NULL} with an exception set.

@cartouche
@quotation Σημείωση 
If the object implements the buffer protocol, then the buffer
must not be mutated while the bytearray object is being created.
@end quotation
@end cartouche
@end deffn

@geindex PyByteArray_FromStringAndSize (C function)
@anchor{c-api/bytearray c PyByteArray_FromStringAndSize}@anchor{174c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyByteArray_FromStringAndSize (const char *string, Py_ssize_t len)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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{529f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyByteArray_Concat (PyObject *a, PyObject *b)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Concat bytearrays `a' and `b' and return a new bytearray with the result.

On failure, return @code{NULL} with an exception set.

@cartouche
@quotation Σημείωση 
If the object implements the buffer protocol, then the buffer
must not be mutated while the bytearray object is being created.
@end quotation
@end cartouche
@end deffn

@geindex PyByteArray_Size (C function)
@anchor{c-api/bytearray c PyByteArray_Size}@anchor{52a1}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyByteArray_Size (PyObject *bytearray)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Return the size of `bytearray' after checking for a @code{NULL} pointer.
@end deffn

@geindex PyByteArray_AsString (C function)
@anchor{c-api/bytearray c PyByteArray_AsString}@anchor{529e}
@deffn {C Συνάρτηση} char *PyByteArray_AsString (PyObject *bytearray)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Return the contents of `bytearray' as a char array after checking for a
@code{NULL} pointer.  The returned array always has an extra
null byte appended.

@cartouche
@quotation Σημείωση 
It is not thread-safe to mutate the bytearray object while using the returned char array.
@end quotation
@end cartouche
@end deffn

@geindex PyByteArray_Resize (C function)
@anchor{c-api/bytearray c PyByteArray_Resize}@anchor{52a0}
@deffn {C Συνάρτηση} int PyByteArray_Resize (PyObject *bytearray, Py_ssize_t len)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Resize the internal buffer of `bytearray' to `len'.
Failure is a @code{-1} return with an exception set.


Άλλαξε στην έκδοση 3.14: A negative `len' will now result in an exception being set and -1 returned.

@end deffn

@node Macros,,Direct API functions,Byte Array Objects
@anchor{c-api/bytearray macros}@anchor{56af}
@subsubsection Macros


These macros trade safety for speed and they don’t check pointers.

@geindex PyByteArray_AS_STRING (C function)
@anchor{c-api/bytearray c PyByteArray_AS_STRING}@anchor{56b0}
@deffn {C Συνάρτηση} char *PyByteArray_AS_STRING (PyObject *bytearray)
` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Similar to @ref{529e,,PyByteArray_AsString()}, but without error checking.

@cartouche
@quotation Σημείωση 
It is not thread-safe to mutate the bytearray object while using the returned char array.
@end quotation
@end cartouche
@end deffn

@geindex PyByteArray_GET_SIZE (C function)
@anchor{c-api/bytearray c PyByteArray_GET_SIZE}@anchor{56b1}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyByteArray_GET_SIZE (PyObject *bytearray)
` Thread safety: @ref{292b,,Atomic}.'
Similar to @ref{52a1,,PyByteArray_Size()}, but without error checking.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Unicode Objects and Codecs,Tuple Objects,Byte Array Objects,Sequence Objects
@anchor{c-api/unicode doc}@anchor{1549}@anchor{c-api/unicode translation-repo}@anchor{56b2}@anchor{c-api/unicode unicode-objects-and-codecs}@anchor{56b3}@anchor{c-api/unicode unicodeobjects}@anchor{56b4}
@subsubsection Unicode Objects and Codecs


@menu
* Unicode Objects:: 
* Built-in Codecs:: 
* Methods and Slot Functions:: 
* PyUnicodeWriter:: 
* Deprecated API: Deprecated API<2>. 

@end menu

@node Unicode Objects,Built-in Codecs,,Unicode Objects and Codecs
@anchor{c-api/unicode unicode-objects}@anchor{56b5}
@subsubsection Unicode Objects


Since the implementation of 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/} in Python 3.3, Unicode objects internally
use a variety of representations, in order to allow handling the complete range
of Unicode characters while staying memory efficient.  There are special cases
for strings where all code points are below 128, 256, or 65536; otherwise, code
points must be below 1114112 (which is the full Unicode range).

UTF-8 representation is created on demand and cached in the Unicode object.

@cartouche
@quotation Σημείωση 
The @ref{b7a,,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
* Unicode Type:: 
* Unicode Character Properties:: 
* Creating and accessing Unicode strings:: 
* Locale Encoding:: 
* File System Encoding:: 
* wchar_t Support:: 

@end menu

@node Unicode Type,Unicode Character Properties,,Unicode Objects
@anchor{c-api/unicode unicode-type}@anchor{56b6}
@subsubsection Unicode Type


These are the basic Unicode object types used for the Unicode implementation in
Python:

@geindex PyUnicode_Type (C var)
@anchor{c-api/unicode c PyUnicode_Type}@anchor{545a}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyUnicode_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This instance of @ref{e6b,,PyTypeObject} represents the Python Unicode type.
It is exposed to Python code as @ref{1df,,str}.
@end deffn

@geindex PyUnicodeIter_Type (C var)
@anchor{c-api/unicode c PyUnicodeIter_Type}@anchor{542b}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyUnicodeIter_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This instance of @ref{e6b,,PyTypeObject} represents the Python Unicode
iterator type. It is used to iterate over Unicode string objects.
@end deffn

@geindex Py_UCS4 (C type)
@geindex Py_UCS2 (C type)
@geindex Py_UCS1 (C type)
@anchor{c-api/unicode c Py_UCS4}@anchor{301}
@deffn {C Τύπος} type Py_UCS4
@anchor{c-api/unicode c Py_UCS2}@anchor{151d}
@deffnx {C Τύπος} type Py_UCS2
@anchor{c-api/unicode c Py_UCS1}@anchor{151c}
@deffnx {C Τύπος} type Py_UCS1
` Μέρος του @ref{95c,,Σταθερό ABI}.'
These types are typedefs for unsigned integer types wide enough to contain
characters of 32 bits, 16 bits and 8 bits, respectively.  When dealing with
single Unicode characters, use @ref{301,,Py_UCS4}.


Added in version 3.3.

@end deffn

@geindex PyASCIIObject (C type)
@geindex PyCompactUnicodeObject (C type)
@geindex PyUnicodeObject (C type)
@anchor{c-api/unicode c PyASCIIObject}@anchor{151e}
@deffn {C Τύπος} type PyASCIIObject
@anchor{c-api/unicode c PyCompactUnicodeObject}@anchor{151f}
@deffnx {C Τύπος} type PyCompactUnicodeObject
@anchor{c-api/unicode c PyUnicodeObject}@anchor{b73}
@deffnx {C Τύπος} type PyUnicodeObject

These subtypes of @ref{19b,,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 @code{PyObject} pointers.


Added in version 3.3.


The structure of a particular object can be determined using the following
macros.
The macros cannot fail; their behavior is undefined if their argument
is not a Python Unicode object.

@geindex PyUnicode_IS_COMPACT (C macro)
@anchor{c-api/unicode c PyUnicode_IS_COMPACT}@anchor{56b7}
@deffn {C Μακροεντολή} PyUnicode_IS_COMPACT (o)

True if `o' uses the @ref{151f,,PyCompactUnicodeObject} structure.


Added in version 3.3.

@end deffn

@geindex PyUnicode_IS_COMPACT_ASCII (C macro)
@anchor{c-api/unicode c PyUnicode_IS_COMPACT_ASCII}@anchor{56b8}
@deffn {C Μακροεντολή} PyUnicode_IS_COMPACT_ASCII (o)

True if `o' uses the @ref{151e,,PyASCIIObject} structure.


Added in version 3.3.

@end deffn
@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{56b9}
@deffn {C Συνάρτηση} 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{56ba}
@deffn {C Συνάρτηση} 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_GET_LENGTH (C function)
@anchor{c-api/unicode c PyUnicode_GET_LENGTH}@anchor{c87}
@deffn {C Συνάρτηση} @ref{e24,,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).


Added in 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{1523}
@deffn {C Συνάρτηση} @ref{151c,,Py_UCS1} *PyUnicode_1BYTE_DATA (PyObject *unicode)
@anchor{c-api/unicode c PyUnicode_2BYTE_DATA}@anchor{1524}
@deffnx {C Συνάρτηση} @ref{151d,,Py_UCS2} *PyUnicode_2BYTE_DATA (PyObject *unicode)
@anchor{c-api/unicode c PyUnicode_4BYTE_DATA}@anchor{1525}
@deffnx {C Συνάρτηση} @ref{301,,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{1526,,PyUnicode_KIND()} to select the right function.


Added in 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{1527}
@deffn {C Μακροεντολή} PyUnicode_1BYTE_KIND
@anchor{c-api/unicode c PyUnicode_2BYTE_KIND}@anchor{1528}
@deffnx {C Μακροεντολή} PyUnicode_2BYTE_KIND
@anchor{c-api/unicode c PyUnicode_4BYTE_KIND}@anchor{1529}
@deffnx {C Μακροεντολή} PyUnicode_4BYTE_KIND

Return values of the @ref{1526,,PyUnicode_KIND()} macro.


Added in version 3.3.



Άλλαξε στην έκδοση 3.12: @code{PyUnicode_WCHAR_KIND} has been removed.

@end deffn

@geindex PyUnicode_KIND (C function)
@anchor{c-api/unicode c PyUnicode_KIND}@anchor{1526}
@deffn {C Συνάρτηση} 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).


Added in version 3.3.

@end deffn

@geindex PyUnicode_DATA (C function)
@anchor{c-api/unicode c PyUnicode_DATA}@anchor{1522}
@deffn {C Συνάρτηση} 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).


Added in version 3.3.

@end deffn

@geindex PyUnicode_WRITE (C function)
@anchor{c-api/unicode c PyUnicode_WRITE}@anchor{152c}
@deffn {C Συνάρτηση} void PyUnicode_WRITE (int kind, void *data, Py_ssize_t index, Py_UCS4 value)

Write the code point `value' to the given zero-based `index' in a string.

The `kind' value and `data' pointer must have been obtained from a
string using @ref{1526,,PyUnicode_KIND()} and @ref{1522,,PyUnicode_DATA()}
respectively. You must hold a reference to that string while calling
@code{PyUnicode_WRITE()}. All requirements of
@ref{151b,,PyUnicode_WriteChar()} also apply.

The function performs no checks for any of its requirements,
and is intended for usage in loops.


Added in version 3.3.

@end deffn

@geindex PyUnicode_READ (C function)
@anchor{c-api/unicode c PyUnicode_READ}@anchor{152a}
@deffn {C Συνάρτηση} @ref{301,,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{1522,,PyUnicode_DATA()}).  No checks or ready calls are performed.


Added in version 3.3.

@end deffn

@geindex PyUnicode_READ_CHAR (C function)
@anchor{c-api/unicode c PyUnicode_READ_CHAR}@anchor{152b}
@deffn {C Συνάρτηση} @ref{301,,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{152a,,PyUnicode_READ()} if you
do multiple consecutive reads.


Added in version 3.3.

@end deffn

@geindex PyUnicode_MAX_CHAR_VALUE (C function)
@anchor{c-api/unicode c PyUnicode_MAX_CHAR_VALUE}@anchor{152d}
@deffn {C Συνάρτηση} @ref{301,,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.


Added in version 3.3.

@end deffn

@geindex PyUnicode_IsIdentifier (C function)
@anchor{c-api/unicode c PyUnicode_IsIdentifier}@anchor{1f78}
@deffn {C Συνάρτηση} int PyUnicode_IsIdentifier (PyObject *unicode)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return @code{1} if the string is a valid identifier according to the language
definition, section @ref{2491,,Ονόματα (αναγνωριστικά και λέξεις-κλειδιά)}. Return @code{0} otherwise.


Άλλαξε στην έκδοση 3.9: The function does not call @ref{d4b,,Py_FatalError()} anymore if the string
is not ready.

@end deffn

@geindex PyUnicode_IS_ASCII (C function)
@anchor{c-api/unicode c PyUnicode_IS_ASCII}@anchor{56bb}
@deffn {C Συνάρτηση} unsigned int PyUnicode_IS_ASCII (PyObject *unicode)

Return true if the string only contains ASCII characters.
Equivalent to @ref{eb7,,str.isascii()}.


Added in version 3.2.

@end deffn

@geindex PyUnstable_Unicode_GET_CACHED_HASH (C function)
@anchor{c-api/unicode c PyUnstable_Unicode_GET_CACHED_HASH}@anchor{357}
@deffn {C Συνάρτηση} @ref{1608,,Py_hash_t} PyUnstable_Unicode_GET_CACHED_HASH (PyObject *str)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

If the hash of `str', as returned by @ref{649,,PyObject_Hash()}, has been
cached and is immediately available, return it.
Otherwise, return @code{-1} `without' setting an exception.

If `str' is not a string (that is, if @code{PyUnicode_Check(obj)}
is false), the behavior is undefined.

This function never fails with an exception.

Note that there are no guarantees on when an object’s hash is cached,
and the (non-)existence of a cached hash does not imply that the string has
any other properties.
@end deffn

@node Unicode Character Properties,Creating and accessing Unicode strings,Unicode Type,Unicode Objects
@anchor{c-api/unicode unicode-character-properties}@anchor{56bc}
@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{1ebb}
@deffn {C Συνάρτηση} 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{56bd}
@deffn {C Συνάρτηση} 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{56be}
@deffn {C Συνάρτηση} 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{56bf}
@deffn {C Συνάρτηση} 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{56c0}
@deffn {C Συνάρτηση} 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{56c1}
@deffn {C Συνάρτηση} 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{56c2}
@deffn {C Συνάρτηση} 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{56c3}
@deffn {C Συνάρτηση} 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{56c4}
@deffn {C Συνάρτηση} 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{56c5}
@deffn {C Συνάρτηση} 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{56c6}
@deffn {C Συνάρτηση} int Py_UNICODE_ISPRINTABLE (Py_UCS4 ch)

Return @code{1} or @code{0} depending on whether `ch' is a printable character,
in the sense of @ref{1191,,str.isprintable()}.
@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{56c7}
@deffn {C Συνάρτηση} @ref{301,,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{56c8}
@deffn {C Συνάρτηση} @ref{301,,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{56c9}
@deffn {C Συνάρτηση} @ref{301,,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{56ca}
@deffn {C Συνάρτηση} 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{56cb}
@deffn {C Συνάρτηση} 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{56cc}
@deffn {C Συνάρτηση} 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{56cd}
@deffn {C Συνάρτηση} 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{56ce}
@deffn {C Συνάρτηση} 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{56cf}
@deffn {C Συνάρτηση} 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_HIGH_SURROGATE (C function)
@anchor{c-api/unicode c Py_UNICODE_HIGH_SURROGATE}@anchor{56d0}
@deffn {C Συνάρτηση} @ref{301,,Py_UCS4} Py_UNICODE_HIGH_SURROGATE (Py_UCS4 ch)

Return the high UTF-16 surrogate (@code{0xD800} to @code{0xDBFF}) for a Unicode
code point in the range @code{[0x10000; 0x10FFFF]}.
@end deffn

@geindex Py_UNICODE_LOW_SURROGATE (C function)
@anchor{c-api/unicode c Py_UNICODE_LOW_SURROGATE}@anchor{56d1}
@deffn {C Συνάρτηση} @ref{301,,Py_UCS4} Py_UNICODE_LOW_SURROGATE (Py_UCS4 ch)

Return the low UTF-16 surrogate (@code{0xDC00} to @code{0xDFFF}) for a Unicode
code point in the range @code{[0x10000; 0x10FFFF]}.
@end deffn

@geindex Py_UNICODE_JOIN_SURROGATES (C function)
@anchor{c-api/unicode c Py_UNICODE_JOIN_SURROGATES}@anchor{56d2}
@deffn {C Συνάρτηση} @ref{301,,Py_UCS4} Py_UNICODE_JOIN_SURROGATES (Py_UCS4 high, Py_UCS4 low)

Join two surrogate code points and return a single @ref{301,,Py_UCS4} value.
`high' and `low' are respectively the leading and trailing surrogates in a
surrogate pair. `high' must be in the range @code{[0xD800; 0xDBFF]} and `low' must
be in the range @code{[0xDC00; 0xDFFF]}.
@end deffn

@node Creating and accessing Unicode strings,Locale Encoding,Unicode Character Properties,Unicode Objects
@anchor{c-api/unicode creating-and-accessing-unicode-strings}@anchor{56d3}
@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{c7f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_New (Py_ssize_t size, Py_UCS4 maxchar)
`Επιστρεφόμενη τιμή: New reference.'
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.

On error, set an exception and return @code{NULL}.

After creation, the string can be filled by @ref{151b,,PyUnicode_WriteChar()},
@ref{c88,,PyUnicode_CopyCharacters()}, @ref{1536,,PyUnicode_Fill()},
@ref{152c,,PyUnicode_WRITE()} or similar.
Since strings are supposed to be immutable, take care to not “use” the
result while it is being modified. In particular, before it’s filled
with its final contents, a string:


@itemize -

@item 
must not be hashed,

@item 
must not be @ref{c6f,,converted to UTF-8},
or another non-«canonical» representation,

@item 
must not have its reference count changed,

@item 
must not be shared with code that might do one of the above.
@end itemize

This list is not exhaustive. Avoiding these uses is your responsibility;
Python does not always check these requirements.

To avoid accidentally exposing a partially-written string object, prefer
using the @ref{5e0,,PyUnicodeWriter} API, or one of the @code{PyUnicode_From*}
functions below.


Added in version 3.3.

@end deffn

@geindex PyUnicode_FromKindAndData (C function)
@anchor{c-api/unicode c PyUnicode_FromKindAndData}@anchor{1520}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_FromKindAndData (int kind, const void *buffer, Py_ssize_t size)
`Επιστρεφόμενη τιμή: New reference.'
Create a new Unicode object with the given `kind' (possible values are
@ref{1527,,PyUnicode_1BYTE_KIND} etc., as returned by
@ref{1526,,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{1529,,PyUnicode_4BYTE_KIND}) and it consists only of codepoints in
the UCS1 range, it will be transformed into UCS1
(@ref{1527,,PyUnicode_1BYTE_KIND}).


Added in version 3.3.

@end deffn

@geindex PyUnicode_FromStringAndSize (C function)
@anchor{c-api/unicode c PyUnicode_FromStringAndSize}@anchor{5452}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_FromStringAndSize (const char *str, Py_ssize_t size)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{3ea,,SystemError} when:


@itemize *

@item 
`size' < 0,

@item 
`str' is @code{NULL} and `size' > 0
@end itemize


Άλλαξε στην έκδοση 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{5451}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_FromString (const char *str)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{81e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_FromFormat (const char *format, ...)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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.

A conversion specifier contains two or more characters and has the following
components, which must occur in this order:


@enumerate 

@item 
The @code{'%'} character, which marks the start of the specifier.

@item 
Conversion flags (optional), which affect the result of some conversion
types.

@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 
Length modifier (optional).

@item 
Conversion type.
@end enumerate

The conversion flag characters are:


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Flag

@tab

Meaning

@item

@code{0}

@tab

The conversion will be zero padded for numeric values.

@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{19b,,PyObject}*

@tab

The result of calling @ref{1789,,ascii()}.

@item

@code{U}

@tab

@ref{19b,,PyObject}*

@tab

A Unicode object.

@item

@code{V}

@tab

@ref{19b,,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{19b,,PyObject}*

@tab

The result of calling @ref{13d8,,PyObject_Str()}.

@item

@code{R}

@tab

@ref{19b,,PyObject}*

@tab

The result of calling @ref{13d7,,PyObject_Repr()}.

@item

@code{T}

@tab

@ref{19b,,PyObject}*

@tab

Get the fully qualified name of an object type;
call @ref{80a,,PyType_GetFullyQualifiedName()}.

@item

@code{#T}

@tab

@ref{19b,,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{e6b,,PyTypeObject}*

@tab

Get the fully qualified name of a type;
call @ref{80a,,PyType_GetFullyQualifiedName()}.

@item

@code{#N}

@tab

@ref{e6b,,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 Σημείωση 
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 Σημείωση 
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


Άλλαξε στην έκδοση 3.2: Support for @code{"%lld"} and @code{"%llu"} added.



Άλλαξε στην έκδοση 3.3: Support for @code{"%li"}, @code{"%lli"} and @code{"%zi"} added.



Άλλαξε στην έκδοση 3.4: Support width and precision formatter for @code{"%s"}, @code{"%A"}, @code{"%U"},
@code{"%V"}, @code{"%S"}, @code{"%R"} added.



Άλλαξε στην έκδοση 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{3ea,,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.



Άλλαξε στην έκδοση 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{979}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_FromFormatV (const char *format, va_list vargs)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Identical to @ref{81e,,PyUnicode_FromFormat()} except that it takes exactly two
arguments.
@end deffn

@geindex PyUnicode_FromObject (C function)
@anchor{c-api/unicode c PyUnicode_FromObject}@anchor{544f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_FromObject (PyObject *obj)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{7da,,strong reference} to the object.

Objects other than Unicode or its subtypes will cause a @ref{291,,TypeError}.
@end deffn

@geindex PyUnicode_FromOrdinal (C function)
@anchor{c-api/unicode c PyUnicode_FromOrdinal}@anchor{5450}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_FromOrdinal (int ordinal)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a Unicode Object from the given Unicode code point `ordinal'.

The ordinal must be in @code{range(0x110000)}. A @ref{277,,ValueError} is
raised in the case it is not.
@end deffn

@geindex PyUnicode_FromEncodedObject (C function)
@anchor{c-api/unicode c PyUnicode_FromEncodedObject}@anchor{544e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_FromEncodedObject (PyObject *obj, const char *encoding, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Decode an encoded object `obj' to a Unicode object.

@ref{1c7,,bytes}, @ref{1c6,,bytearray} and other
@ref{436,,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{56d4,,Built-in Codecs} for details).

All other objects, including Unicode objects, cause a @ref{291,,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_Append (C function)
@anchor{c-api/unicode c PyUnicode_Append}@anchor{5433}
@deffn {C Συνάρτηση} void PyUnicode_Append (PyObject **p_left, PyObject *right)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Append the string `right' to the end of `p_left'.
`p_left' must point to a @ref{7da,,strong reference} to a Unicode object;
@code{PyUnicode_Append()} releases («steals») this reference.

On error, set `*p_left' to @code{NULL} and set an exception.

On success, set `*p_left' to a new strong reference to the result.
@end deffn

@geindex PyUnicode_AppendAndDel (C function)
@anchor{c-api/unicode c PyUnicode_AppendAndDel}@anchor{5434}
@deffn {C Συνάρτηση} void PyUnicode_AppendAndDel (PyObject **p_left, PyObject *right)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The function is similar to @ref{5433,,PyUnicode_Append()}, with the only
difference being that it decrements the reference count of `right' by one.
@end deffn

@geindex PyUnicode_BuildEncodingMap (C function)
@anchor{c-api/unicode c PyUnicode_BuildEncodingMap}@anchor{1c68}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_BuildEncodingMap (PyObject *string)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a mapping suitable for decoding a custom single-byte encoding.
Given a Unicode string `string' of up to 256 characters representing an encoding
table, returns either a compact internal mapping object or a dictionary
mapping character ordinals to byte values. Raises a @ref{291,,TypeError} and
return @code{NULL} on invalid input.


Added in version 3.2.

@end deffn

@geindex PyUnicode_GetDefaultEncoding (C function)
@anchor{c-api/unicode c PyUnicode_GetDefaultEncoding}@anchor{5453}
@deffn {C Συνάρτηση} const char *PyUnicode_GetDefaultEncoding (void)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the name of the default string encoding, @code{"utf-8"}.
See @ref{4bf9,,sys.getdefaultencoding()}.

The returned string does not need to be freed, and is valid
until interpreter shutdown.
@end deffn

@geindex PyUnicode_GetLength (C function)
@anchor{c-api/unicode c PyUnicode_GetLength}@anchor{c86}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyUnicode_GetLength (PyObject *unicode)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Return the length of the Unicode object, in code points.

On error, set an exception and return @code{-1}.


Added in version 3.3.

@end deffn

@geindex PyUnicode_CopyCharacters (C function)
@anchor{c-api/unicode c PyUnicode_CopyCharacters}@anchor{c88}
@deffn {C Συνάρτηση} @ref{e24,,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.

The string must not have been “used” yet.
See @ref{c7f,,PyUnicode_New()} for details.


Added in version 3.3.

@end deffn

@geindex PyUnicode_Resize (C function)
@anchor{c-api/unicode c PyUnicode_Resize}@anchor{5455}
@deffn {C Συνάρτηση} int PyUnicode_Resize (PyObject **unicode, Py_ssize_t length);
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Resize a Unicode object `*unicode' to the new `length' in code points.

Try to resize the string in place (which is usually faster than allocating
a new string and copying characters), or create a new string.

`*unicode' is modified to point to the new (resized) object and @code{0} is
returned on success. Otherwise, @code{-1} is returned and an exception is set,
and `*unicode' is left untouched.

The function doesn’t check string content, the result may not be a
string in canonical representation.
@end deffn

@geindex PyUnicode_Fill (C function)
@anchor{c-api/unicode c PyUnicode_Fill}@anchor{1536}
@deffn {C Συνάρτηση} @ref{e24,,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.

The string must not have been “used” yet.
See @ref{c7f,,PyUnicode_New()} for details.

Return the number of written characters, or return @code{-1} and raise an
exception on error.


Added in version 3.3.

@end deffn

@geindex PyUnicode_WriteChar (C function)
@anchor{c-api/unicode c PyUnicode_WriteChar}@anchor{151b}
@deffn {C Συνάρτηση} int PyUnicode_WriteChar (PyObject *unicode, Py_ssize_t index, Py_UCS4 character)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Write a `character' to the string `unicode' at the zero-based `index'.
Return @code{0} on success, @code{-1} on error with an exception set.

This function checks that `unicode' is a Unicode object, that the index is
not out of bounds, and that the object’s reference count is one.
See @ref{152c,,PyUnicode_WRITE()} for a version that skips these checks,
making them your responsibility.

The string must not have been “used” yet.
See @ref{c7f,,PyUnicode_New()} for details.


Added in version 3.3.

@end deffn

@geindex PyUnicode_ReadChar (C function)
@anchor{c-api/unicode c PyUnicode_ReadChar}@anchor{151a}
@deffn {C Συνάρτηση} @ref{301,,Py_UCS4} PyUnicode_ReadChar (PyObject *unicode, Py_ssize_t index)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{152b,,PyUnicode_READ_CHAR()}, which performs no error checking.

Return character on success, @code{-1} on error with an exception set.


Added in version 3.3.

@end deffn

@geindex PyUnicode_Substring (C function)
@anchor{c-api/unicode c PyUnicode_Substring}@anchor{c89}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_Substring (PyObject *unicode, Py_ssize_t start, Py_ssize_t end)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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}.


Added in version 3.3.

@end deffn

@geindex PyUnicode_AsUCS4 (C function)
@anchor{c-api/unicode c PyUnicode_AsUCS4}@anchor{1521}
@deffn {C Συνάρτηση} @ref{301,,Py_UCS4} *PyUnicode_AsUCS4 (PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{3ea,,SystemError} if `buflen' is smaller than the length of
`unicode').  `buffer' is returned on success.


Added in version 3.3.

@end deffn

@geindex PyUnicode_AsUCS4Copy (C function)
@anchor{c-api/unicode c PyUnicode_AsUCS4Copy}@anchor{c8e}
@deffn {C Συνάρτηση} @ref{301,,Py_UCS4} *PyUnicode_AsUCS4Copy (PyObject *unicode)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Copy the string `unicode' into a new UCS4 buffer that is allocated using
@ref{1024,,PyMem_Malloc()}.  If this fails, @code{NULL} is returned with a
@ref{18fa,,MemoryError} set.  The returned buffer always has an extra
null code point appended.


Added in version 3.3.

@end deffn

@node Locale Encoding,File System Encoding,Creating and accessing Unicode strings,Unicode Objects
@anchor{c-api/unicode locale-encoding}@anchor{56d5}
@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{f87}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeLocaleAndSize (const char *str, Py_ssize_t length, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{543e,,PyUnicode_DecodeFSDefaultAndSize()} to decode a string from
the @ref{948,,filesystem encoding and error handler}.

This function ignores the @ref{a46,,Python UTF-8 Mode}.


@subsubheading Δείτε επίσης


The @ref{f85,,Py_DecodeLocale()} function.



Added in version 3.3.



Άλλαξε στην έκδοση 3.7: The function now also uses the current locale encoding for the
@code{surrogateescape} error handler, except on Android. Previously, @ref{f85,,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{5440}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeLocale (const char *str, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Similar to @ref{f87,,PyUnicode_DecodeLocaleAndSize()}, but compute the string
length using @code{strlen()}.


Added in version 3.3.

@end deffn

@geindex PyUnicode_EncodeLocale (C function)
@anchor{c-api/unicode c PyUnicode_EncodeLocale}@anchor{f88}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_EncodeLocale (PyObject *unicode, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{1c7,,bytes} object. `unicode' cannot
contain embedded null characters.

Use @ref{201e,,PyUnicode_EncodeFSDefault()} to encode a string to the
@ref{948,,filesystem encoding and error handler}.

This function ignores the @ref{a46,,Python UTF-8 Mode}.


@subsubheading Δείτε επίσης


The @ref{f86,,Py_EncodeLocale()} function.



Added in version 3.3.



Άλλαξε στην έκδοση 3.7: The function now also uses the current locale encoding for the
@code{surrogateescape} error handler, except on Android. Previously,
@ref{f86,,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,Unicode Objects
@anchor{c-api/unicode file-system-encoding}@anchor{56d6}
@subsubsection File System Encoding


Functions encoding to and decoding from the @ref{948,,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{1c7,,bytes} during argument parsing, the @code{"O&"}
converter should be used, passing @code{PyUnicode_FSConverter()} as the
conversion function:

@geindex PyUnicode_FSConverter (C function)
@anchor{c-api/unicode c PyUnicode_FSConverter}@anchor{10d3}
@deffn {C Συνάρτηση} int PyUnicode_FSConverter (PyObject *obj, void *result)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@ref{601,,PyArg_Parse* converter}: encode @ref{1df,,str} objects – obtained directly or
through the @ref{100f,,os.PathLike} interface – to @ref{1c7,,bytes} using
@ref{201e,,PyUnicode_EncodeFSDefault()}; @code{bytes} objects are output as-is.
`result' must be an address of a C variable of type @ref{19b,,PyObject}*
(or @ref{b71,,PyBytesObject}*).
On success, set the variable to a new @ref{7da,,strong reference} to
a @ref{569d,,bytes object} which must be released
when it is no longer used and return a non-zero value
(@ref{55a3,,Py_CLEANUP_SUPPORTED}).
Embedded null bytes are not allowed in the result.
On failure, return @code{0} with an exception set.

If `obj' is @code{NULL}, the function releases a strong reference
stored in the variable referred by `result' and returns @code{1}.


Added in version 3.1.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

To decode file names to @ref{1df,,str} during argument parsing, the @code{"O&"}
converter should be used, passing @code{PyUnicode_FSDecoder()} as the
conversion function:

@geindex PyUnicode_FSDecoder (C function)
@anchor{c-api/unicode c PyUnicode_FSDecoder}@anchor{97b}
@deffn {C Συνάρτηση} int PyUnicode_FSDecoder (PyObject *obj, void *result)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@ref{601,,PyArg_Parse* converter}: decode @ref{1c7,,bytes} objects – obtained either
directly or indirectly through the @ref{100f,,os.PathLike} interface – to
@ref{1df,,str} using @ref{543e,,PyUnicode_DecodeFSDefaultAndSize()}; @code{str}
objects are output as-is.
`result' must be an address of a C variable of type @ref{19b,,PyObject}*
(or @ref{b73,,PyUnicodeObject}*).
On success, set the variable to a new @ref{7da,,strong reference} to
a @ref{56b4,,Unicode object} which must be released
when it is no longer used and return a non-zero value
(@ref{55a3,,Py_CLEANUP_SUPPORTED}).
Embedded null characters are not allowed in the result.
On failure, return @code{0} with an exception set.

If `obj' is @code{NULL}, release the strong reference
to the object referred to by `result' and return @code{1}.


Added in version 3.2.



Άλλαξε στην έκδοση 3.6: Accepts a @ref{79f,,path-like object}.

@end deffn

@geindex PyUnicode_DecodeFSDefaultAndSize (C function)
@anchor{c-api/unicode c PyUnicode_DecodeFSDefaultAndSize}@anchor{543e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeFSDefaultAndSize (const char *str, Py_ssize_t size)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Decode a string from the @ref{948,,filesystem encoding and error handler}.

If you need to decode a string from the current locale encoding, use
@ref{f87,,PyUnicode_DecodeLocaleAndSize()}.


@subsubheading Δείτε επίσης


The @ref{f85,,Py_DecodeLocale()} function.



Άλλαξε στην έκδοση 3.6: The @ref{948,,filesystem error handler} is now used.

@end deffn

@geindex PyUnicode_DecodeFSDefault (C function)
@anchor{c-api/unicode c PyUnicode_DecodeFSDefault}@anchor{1c8e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeFSDefault (const char *str)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Decode a null-terminated string from the @ref{948,,filesystem encoding and error handler}.

If the string length is known, use
@ref{543e,,PyUnicode_DecodeFSDefaultAndSize()}.


Άλλαξε στην έκδοση 3.6: The @ref{948,,filesystem error handler} is now used.

@end deffn

@geindex PyUnicode_EncodeFSDefault (C function)
@anchor{c-api/unicode c PyUnicode_EncodeFSDefault}@anchor{201e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_EncodeFSDefault (PyObject *unicode)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Encode a Unicode object to the @ref{948,,filesystem encoding and error handler}, and return @ref{1c7,,bytes}. Note that the resulting @code{bytes}
object can contain null bytes.

If you need to encode a string to the current locale encoding, use
@ref{f88,,PyUnicode_EncodeLocale()}.


@subsubheading Δείτε επίσης


The @ref{f86,,Py_EncodeLocale()} function.



Added in version 3.2.



Άλλαξε στην έκδοση 3.6: The @ref{948,,filesystem error handler} is now used.

@end deffn

@node wchar_t Support,,File System Encoding,Unicode Objects
@anchor{c-api/unicode wchar-t-support}@anchor{56d7}
@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{1535}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_FromWideChar (const wchar_t *wstr, Py_ssize_t size)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{2025}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyUnicode_AsWideChar (PyObject *unicode, wchar_t *wstr, Py_ssize_t size)
` Μέρος του @ref{95c,,Σταθερό 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{c8f}
@deffn {C Συνάρτηση} wchar_t *PyUnicode_AsWideCharString (PyObject *unicode, Py_ssize_t *size)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{277,,ValueError} is raised.

Returns a buffer allocated by @ref{18c6,,PyMem_New} (use
@ref{17e4,,PyMem_Free()} to free it) on success. On error, returns @code{NULL}
and `*size' is undefined. Raises a @ref{18fa,,MemoryError} if memory allocation
is failed.


Added in version 3.2.



Άλλαξε στην έκδοση 3.7: Raises a @ref{277,,ValueError} if `size' is @code{NULL} and the wchar_t*
string contains null characters.

@end deffn

@node Built-in Codecs,Methods and Slot Functions,Unicode Objects,Unicode Objects and Codecs
@anchor{c-api/unicode built-in-codecs}@anchor{56d8}@anchor{c-api/unicode builtincodecs}@anchor{56d4}
@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{1df,,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{10d3,,PyUnicode_FSConverter()} for encoding file names. This uses the
@ref{948,,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{277,,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:: 

@end menu

@node Generic Codecs,UTF-8 Codecs,,Built-in Codecs
@anchor{c-api/unicode generic-codecs}@anchor{56d9}
@subsubsection Generic Codecs


The following macro is provided:

@geindex Py_UNICODE_REPLACEMENT_CHARACTER (C macro)
@anchor{c-api/unicode c Py_UNICODE_REPLACEMENT_CHARACTER}@anchor{56da}
@deffn {C Μακροεντολή} Py_UNICODE_REPLACEMENT_CHARACTER

The Unicode code point @code{U+FFFD} (replacement character).

This Unicode character is used as the replacement character during
decoding if the `errors' argument is set to «replace».
@end deffn

These are the generic codec APIs:

@geindex PyUnicode_Decode (C function)
@anchor{c-api/unicode c PyUnicode_Decode}@anchor{1fb7}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_Decode (const char *str, Py_ssize_t size, const char *encoding, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{1df,,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{5436}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_AsEncodedString (PyObject *unicode, const char *encoding, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{ca7,,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{56db}
@subsubsection UTF-8 Codecs


These are the UTF-8 codec APIs:

@geindex PyUnicode_DecodeUTF8 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF8}@anchor{544a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeUTF8 (const char *str, Py_ssize_t size, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{1d15}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeUTF8Stateful (const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
If `consumed' is @code{NULL}, behave like @ref{544a,,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{1537}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_AsUTF8String (PyObject *unicode)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{c6f}
@deffn {C Συνάρτηση} const char *PyUnicode_AsUTF8AndSize (PyObject *unicode, Py_ssize_t *size)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.


Added in version 3.3.



Άλλαξε στην έκδοση 3.7: The return type is now @code{const char *} rather than @code{char *}.



Άλλαξε στην έκδοση 3.10: This function is a part of the @ref{829,,limited API}.

@end deffn

@geindex PyUnicode_AsUTF8 (C function)
@anchor{c-api/unicode c PyUnicode_AsUTF8}@anchor{637}
@deffn {C Συνάρτηση} const char *PyUnicode_AsUTF8 (PyObject *unicode)

As @ref{c6f,,PyUnicode_AsUTF8AndSize()}, but does not store the size.

@cartouche
@quotation Προειδοποίηση 
This function does not have any special behavior for
null characters@footnote{https://en.wikipedia.org/wiki/Null_character} embedded within
`unicode'. As a result, strings containing null characters will remain in the returned
string, which some C functions might interpret as the end of the string, leading to
truncation. If truncation is an issue, it is recommended to use @ref{c6f,,PyUnicode_AsUTF8AndSize()}
instead.
@end quotation
@end cartouche


Added in version 3.3.



Άλλαξε στην έκδοση 3.7: The return type is now @code{const char *} rather than @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{56dc}
@subsubsection UTF-32 Codecs


These are the UTF-32 codec APIs:

@geindex PyUnicode_DecodeUTF32 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF32}@anchor{5446}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeUTF32 (const char *str, Py_ssize_t size, const char *errors, int *byteorder)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{5447}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeUTF32Stateful (const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
If `consumed' is @code{NULL}, behave like @ref{5446,,PyUnicode_DecodeUTF32()}. If
`consumed' is not @code{NULL}, @ref{5447,,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{5438}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_AsUTF32String (PyObject *unicode)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{56dd}
@subsubsection UTF-16 Codecs


These are the UTF-16 codec APIs:

@geindex PyUnicode_DecodeUTF16 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF16}@anchor{5444}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeUTF16 (const char *str, Py_ssize_t size, const char *errors, int *byteorder)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{5445}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeUTF16Stateful (const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
If `consumed' is @code{NULL}, behave like @ref{5444,,PyUnicode_DecodeUTF16()}. If
`consumed' is not @code{NULL}, @ref{5445,,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{5437}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_AsUTF16String (PyObject *unicode)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{56de}
@subsubsection UTF-7 Codecs


These are the UTF-7 codec APIs:

@geindex PyUnicode_DecodeUTF7 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF7}@anchor{5448}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeUTF7 (const char *str, Py_ssize_t size, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{5449}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeUTF7Stateful (const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
If `consumed' is @code{NULL}, behave like @ref{5448,,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{56df}
@subsubsection Unicode-Escape Codecs


These are the «Unicode Escape» codec APIs:

@geindex PyUnicode_DecodeUnicodeEscape (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUnicodeEscape}@anchor{544b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeUnicodeEscape (const char *str, Py_ssize_t size, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{1538}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_AsUnicodeEscapeString (PyObject *unicode)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{56e0}
@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{5443}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeRawUnicodeEscape (const char *str, Py_ssize_t size, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{1539}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_AsRawUnicodeEscapeString (PyObject *unicode)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{56e1}
@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{543f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeLatin1 (const char *str, Py_ssize_t size, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{153a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_AsLatin1String (PyObject *unicode)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{56e2}
@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{543b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeASCII (const char *str, Py_ssize_t size, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{153b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_AsASCIIString (PyObject *unicode)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{56e3}
@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{787,,__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{543c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeCharmap (const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{25da,,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{5435}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_AsCharmapString (PyObject *unicode, PyObject *mapping)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{25da,,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{5459}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_Translate (PyObject *unicode, PyObject *table, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{787,,__getitem__()} interface; dictionaries
and sequences work well.  Unmapped character ordinals (ones which cause a
@ref{25da,,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,,Character Map Codecs,Built-in Codecs
@anchor{c-api/unicode mbcs-codecs-for-windows}@anchor{56e4}
@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{5441}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeMBCS (const char *str, Py_ssize_t size, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} on Windows από την έκδοση 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{5442}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeMBCSStateful (const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} on Windows από την έκδοση 3.7.'
If `consumed' is @code{NULL}, behave like @ref{5441,,PyUnicode_DecodeMBCS()}. If
`consumed' is not @code{NULL}, @ref{5442,,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_DecodeCodePageStateful (C function)
@anchor{c-api/unicode c PyUnicode_DecodeCodePageStateful}@anchor{543d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_DecodeCodePageStateful (int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} on Windows από την έκδοση 3.7.'
Similar to @ref{5442,,PyUnicode_DecodeMBCSStateful()}, except uses the code page
specified by `code_page'.
@end deffn

@geindex PyUnicode_AsMBCSString (C function)
@anchor{c-api/unicode c PyUnicode_AsMBCSString}@anchor{153c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_AsMBCSString (PyObject *unicode)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} on Windows από την έκδοση 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{153d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_EncodeCodePage (int code_page, PyObject *unicode, const char *errors)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} on Windows από την έκδοση 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.


Added in version 3.3.

@end deffn

@node Methods and Slot Functions,PyUnicodeWriter,Built-in Codecs,Unicode Objects and Codecs
@anchor{c-api/unicode methods-and-slot-functions}@anchor{56e5}@anchor{c-api/unicode unicodemethodsandslots}@anchor{56e6}
@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{154a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_Concat (PyObject *left, PyObject *right)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Concat two strings giving a new Unicode string.
@end deffn

@geindex PyUnicode_Split (C function)
@anchor{c-api/unicode c PyUnicode_Split}@anchor{5457}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_Split (PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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.

On error, return @code{NULL} with an exception set.

Equivalent to @ref{125b,,str.split()}.
@end deffn

@geindex PyUnicode_RSplit (C function)
@anchor{c-api/unicode c PyUnicode_RSplit}@anchor{1abb}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_RSplit (PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{5457,,PyUnicode_Split()}, but splitting will be done beginning
at the end of the string.

On error, return @code{NULL} with an exception set.

Equivalent to @ref{15fa,,str.rsplit()}.
@end deffn

@geindex PyUnicode_Splitlines (C function)
@anchor{c-api/unicode c PyUnicode_Splitlines}@anchor{5458}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_Splitlines (PyObject *unicode, int keepends)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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_Partition (C function)
@anchor{c-api/unicode c PyUnicode_Partition}@anchor{1abc}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_Partition (PyObject *unicode, PyObject *sep)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Split a Unicode string at the first occurrence of `sep', and return
a 3-tuple containing the part before the separator, the separator itself,
and the part after the separator. If the separator is not found,
return a 3-tuple containing the string itself, followed by two empty strings.

`sep' must not be empty.

On error, return @code{NULL} with an exception set.

Equivalent to @ref{125c,,str.partition()}.
@end deffn

@geindex PyUnicode_RPartition (C function)
@anchor{c-api/unicode c PyUnicode_RPartition}@anchor{1abd}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_RPartition (PyObject *unicode, PyObject *sep)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{1abc,,PyUnicode_Partition()}, but split a Unicode string at the
last occurrence of `sep'. If the separator is not found, return a 3-tuple
containing two empty strings, followed by the string itself.

`sep' must not be empty.

On error, return @code{NULL} with an exception set.

Equivalent to @ref{15fd,,str.rpartition()}.
@end deffn

@geindex PyUnicode_Join (C function)
@anchor{c-api/unicode c PyUnicode_Join}@anchor{154b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_Join (PyObject *separator, PyObject *seq)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{c8b}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyUnicode_Tailmatch (PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
` Μέρος του @ref{95c,,Σταθερό 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{544c}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyUnicode_Find (PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
` Μέρος του @ref{95c,,Σταθερό 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{c8c}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyUnicode_FindChar (PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.


Added in version 3.3.



Άλλαξε στην έκδοση 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{543a}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyUnicode_Count (PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
` Μέρος του @ref{95c,,Σταθερό 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{5454}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_Replace (PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{c8a}
@deffn {C Συνάρτηση} int PyUnicode_Compare (PyObject *left, PyObject *right)
` Μέρος του @ref{95c,,Σταθερό 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{1ea5,,PyErr_Occurred()} to check for errors.


@subsubheading Δείτε επίσης


The @ref{5df,,PyUnicode_Equal()} function.

@end deffn

@geindex PyUnicode_Equal (C function)
@anchor{c-api/unicode c PyUnicode_Equal}@anchor{5df}
@deffn {C Συνάρτηση} int PyUnicode_Equal (PyObject *a, PyObject *b)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
Test if two strings are equal:


@itemize *

@item 
Return @code{1} if `a' is equal to `b'.

@item 
Return @code{0} if `a' is not equal to `b'.

@item 
Set a @ref{291,,TypeError} exception and return @code{-1} if `a' or `b' is not a
@ref{1df,,str} object.
@end itemize

The function always succeeds if `a' and `b' are @ref{1df,,str} objects.

The function works for @ref{1df,,str} subclasses, but does not honor custom
@code{__eq__()} method.


@subsubheading Δείτε επίσης


The @ref{c8a,,PyUnicode_Compare()} function.



Added in version 3.14.

@end deffn

@geindex PyUnicode_EqualToUTF8AndSize (C function)
@anchor{c-api/unicode c PyUnicode_EqualToUTF8AndSize}@anchor{80d}
@deffn {C Συνάρτηση} int PyUnicode_EqualToUTF8AndSize (PyObject *unicode, const char *string, Py_ssize_t size)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.


Added in version 3.13.

@end deffn

@geindex PyUnicode_EqualToUTF8 (C function)
@anchor{c-api/unicode c PyUnicode_EqualToUTF8}@anchor{80e}
@deffn {C Συνάρτηση} int PyUnicode_EqualToUTF8 (PyObject *unicode, const char *string)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Similar to @ref{80d,,PyUnicode_EqualToUTF8AndSize()}, but compute `string'
length using @code{strlen()}.
If the Unicode object contains null characters, false (@code{0}) is returned.


Added in version 3.13.

@end deffn

@geindex PyUnicode_CompareWithASCIIString (C function)
@anchor{c-api/unicode c PyUnicode_CompareWithASCIIString}@anchor{160c}
@deffn {C Συνάρτηση} int PyUnicode_CompareWithASCIIString (PyObject *unicode, const char *string)
` Μέρος του @ref{95c,,Σταθερό 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{5456}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_RichCompare (PyObject *left, PyObject *right, int op)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Rich compare two Unicode strings and return one of the following:


@itemize *

@item 
@code{NULL} in case an exception was raised

@item 
@ref{5677,,Py_True} or @ref{5676,,Py_False} for successful comparisons

@item 
@ref{55e8,,Py_NotImplemented} in case the type combination is unknown
@end itemize

Possible values for `op' are @ref{55ef,,Py_GT}, @ref{55f0,,Py_GE}, @ref{55ed,,Py_EQ},
@ref{55ee,,Py_NE}, @ref{55eb,,Py_LT}, and @ref{55ec,,Py_LE}.
@end deffn

@geindex PyUnicode_Format (C function)
@anchor{c-api/unicode c PyUnicode_Format}@anchor{544d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_Format (PyObject *format, PyObject *args)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{5439}
@deffn {C Συνάρτηση} int PyUnicode_Contains (PyObject *unicode, PyObject *substr)
` Μέρος του @ref{95c,,Σταθερό 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{c84}
@deffn {C Συνάρτηση} void PyUnicode_InternInPlace (PyObject **p_unicode)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Intern the argument *@ref{c84,,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 *p_unicode, it sets *p_unicode to
it (releasing the reference to the old string object and creating a new
@ref{7da,,strong reference} to the interned string object), otherwise it leaves
*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{1df,,str} may not be interned, that is,
@ref{56ba,,PyUnicode_CheckExact}(*@ref{c84,,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{3b5}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicode_InternFromString (const char *str)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
A combination of @ref{5451,,PyUnicode_FromString()} and
@ref{c84,,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{398,,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{5451,,PyUnicode_FromString()} and
@ref{c84,,PyUnicode_InternInPlace()} directly.
@end deffn

@geindex PyUnicode_CHECK_INTERNED (C function)
@anchor{c-api/unicode c PyUnicode_CHECK_INTERNED}@anchor{56e7}
@deffn {C Συνάρτηση} unsigned int PyUnicode_CHECK_INTERNED (PyObject *str)

Return a non-zero value if `str' is interned, zero if not.
The `str' argument must be a string; this is not checked.
This function always succeeds.

`Λεπτομέρεια υλοποίησης CPython:' A non-zero return value may carry additional information
about `how' the string is interned.
The meaning of such non-zero values, as well as each specific string’s
intern-related details, may change between CPython versions.
@end deffn

@node PyUnicodeWriter,Deprecated API<2>,Methods and Slot Functions,Unicode Objects and Codecs
@anchor{c-api/unicode pyunicodewriter}@anchor{56e8}
@subsubsection PyUnicodeWriter


The @ref{5e0,,PyUnicodeWriter} API can be used to create a Python @ref{1df,,str}
object.


Added in version 3.14.


@geindex PyUnicodeWriter (C type)
@anchor{c-api/unicode c PyUnicodeWriter}@anchor{5e0}
@deffn {C Τύπος} type PyUnicodeWriter

A Unicode writer instance.

The instance must be destroyed by @ref{5e4,,PyUnicodeWriter_Finish()} on
success, or @ref{5e3,,PyUnicodeWriter_Discard()} on error.
@end deffn

@geindex PyUnicodeWriter_Create (C function)
@anchor{c-api/unicode c PyUnicodeWriter_Create}@anchor{5e1}
@deffn {C Συνάρτηση} @ref{5e0,,PyUnicodeWriter} *PyUnicodeWriter_Create (Py_ssize_t length)

Create a Unicode writer instance.

`length' must be greater than or equal to @code{0}.

If `length' is greater than @code{0}, preallocate an internal buffer of
`length' characters.

Set an exception and return @code{NULL} on error.
@end deffn

@geindex PyUnicodeWriter_Finish (C function)
@anchor{c-api/unicode c PyUnicodeWriter_Finish}@anchor{5e4}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnicodeWriter_Finish (PyUnicodeWriter *writer)

Return the final Python @ref{1df,,str} object and destroy the writer instance.

Set an exception and return @code{NULL} on error.

The writer instance is invalid after this call.
@end deffn

@geindex PyUnicodeWriter_Discard (C function)
@anchor{c-api/unicode c PyUnicodeWriter_Discard}@anchor{5e3}
@deffn {C Συνάρτηση} void PyUnicodeWriter_Discard (PyUnicodeWriter *writer)

Discard the internal Unicode buffer and destroy the writer instance.

If `writer' is @code{NULL}, no operation is performed.

The writer instance is invalid after this call.
@end deffn

@geindex PyUnicodeWriter_WriteChar (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteChar}@anchor{5e7}
@deffn {C Συνάρτηση} int PyUnicodeWriter_WriteChar (PyUnicodeWriter *writer, Py_UCS4 ch)

Write the single Unicode character `ch' into `writer'.

On success, return @code{0}.
On error, set an exception, leave the writer unchanged, and return @code{-1}.
@end deffn

@geindex PyUnicodeWriter_WriteUTF8 (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteUTF8}@anchor{5ec}
@deffn {C Συνάρτηση} int PyUnicodeWriter_WriteUTF8 (PyUnicodeWriter *writer, const char *str, Py_ssize_t size)

Decode the string `str' from UTF-8 in strict mode and write the output into `writer'.

`size' is the string length in bytes. If `size' is equal to @code{-1}, call
@code{strlen(str)} to get the string length.

On success, return @code{0}.
On error, set an exception, leave the writer unchanged, and return @code{-1}.

See also @ref{5e2,,PyUnicodeWriter_DecodeUTF8Stateful()}.
@end deffn

@geindex PyUnicodeWriter_WriteASCII (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteASCII}@anchor{5e6}
@deffn {C Συνάρτηση} int PyUnicodeWriter_WriteASCII (PyUnicodeWriter *writer, const char *str, Py_ssize_t size)

Write the ASCII string `str' into `writer'.

`size' is the string length in bytes. If `size' is equal to @code{-1}, call
@code{strlen(str)} to get the string length.

`str' must only contain ASCII characters. The behavior is undefined if
`str' contains non-ASCII characters.

On success, return @code{0}.
On error, set an exception, leave the writer unchanged, and return @code{-1}.
@end deffn

@geindex PyUnicodeWriter_WriteWideChar (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteWideChar}@anchor{5ed}
@deffn {C Συνάρτηση} int PyUnicodeWriter_WriteWideChar (PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)

Write the wide string `str' into `writer'.

`size' is a number of wide characters. If `size' is equal to @code{-1}, call
@code{wcslen(str)} to get the string length.

On success, return @code{0}.
On error, set an exception, leave the writer unchanged, and return @code{-1}.
@end deffn

@geindex PyUnicodeWriter_WriteUCS4 (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteUCS4}@anchor{5eb}
@deffn {C Συνάρτηση} int PyUnicodeWriter_WriteUCS4 (PyUnicodeWriter *writer, const Py_UCS4 *str, Py_ssize_t size)

Writer the UCS4 string `str' into `writer'.

`size' is a number of UCS4 characters.

On success, return @code{0}.
On error, set an exception, leave the writer unchanged, and return @code{-1}.
@end deffn

@geindex PyUnicodeWriter_WriteStr (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteStr}@anchor{5e9}
@deffn {C Συνάρτηση} int PyUnicodeWriter_WriteStr (PyUnicodeWriter *writer, PyObject *obj)

Call @ref{13d8,,PyObject_Str()} on `obj' and write the output into `writer'.

On success, return @code{0}.
On error, set an exception, leave the writer unchanged, and return @code{-1}.

To write a @ref{1df,,str} subclass which overrides the @ref{a0f,,__str__()}
method, @ref{544f,,PyUnicode_FromObject()} can be used to get the original
string.
@end deffn

@geindex PyUnicodeWriter_WriteRepr (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteRepr}@anchor{5e8}
@deffn {C Συνάρτηση} int PyUnicodeWriter_WriteRepr (PyUnicodeWriter *writer, PyObject *obj)

Call @ref{13d7,,PyObject_Repr()} on `obj' and write the output into `writer'.

If `obj' is @code{NULL}, write the string @code{"<NULL>"} into `writer'.

On success, return @code{0}.
On error, set an exception, leave the writer unchanged, and return @code{-1}.


Άλλαξε στην έκδοση 3.14.4: Added support for @code{NULL}.

@end deffn

@geindex PyUnicodeWriter_WriteSubstring (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteSubstring}@anchor{5ea}
@deffn {C Συνάρτηση} int PyUnicodeWriter_WriteSubstring (PyUnicodeWriter *writer, PyObject *str, Py_ssize_t start, Py_ssize_t end)

Write the substring @code{str[start:end]} into `writer'.

`str' must be Python @ref{1df,,str} object. `start' must be greater than or
equal to 0, and less than or equal to `end'. `end' must be less than or
equal to `str' length.

On success, return @code{0}.
On error, set an exception, leave the writer unchanged, and return @code{-1}.
@end deffn

@geindex PyUnicodeWriter_Format (C function)
@anchor{c-api/unicode c PyUnicodeWriter_Format}@anchor{5e5}
@deffn {C Συνάρτηση} int PyUnicodeWriter_Format (PyUnicodeWriter *writer, const char *format, ...)

Similar to @ref{81e,,PyUnicode_FromFormat()}, but write the output directly into `writer'.

On success, return @code{0}.
On error, set an exception, leave the writer unchanged, and return @code{-1}.
@end deffn

@geindex PyUnicodeWriter_DecodeUTF8Stateful (C function)
@anchor{c-api/unicode c PyUnicodeWriter_DecodeUTF8Stateful}@anchor{5e2}
@deffn {C Συνάρτηση} int PyUnicodeWriter_DecodeUTF8Stateful (PyUnicodeWriter *writer, const char *string, Py_ssize_t length, const char *errors, Py_ssize_t *consumed)

Decode the string `str' from UTF-8 with `errors' error handler and write the
output into `writer'.

`size' is the string length in bytes. If `size' is equal to @code{-1}, call
@code{strlen(str)} to get the string length.

`errors' is an @ref{1d6c,,error handler} name, such as
@code{"replace"}. If `errors' is @code{NULL}, use the strict error handler.

If `consumed' is not @code{NULL}, set `*consumed' to the number of decoded
bytes on success.
If `consumed' is @code{NULL}, treat trailing incomplete UTF-8 byte sequences
as an error.

On success, return @code{0}.
On error, set an exception, leave the writer unchanged, and return @code{-1}.

See also @ref{5ec,,PyUnicodeWriter_WriteUTF8()}.
@end deffn

@node Deprecated API<2>,,PyUnicodeWriter,Unicode Objects and Codecs
@anchor{c-api/unicode deprecated-api}@anchor{56e9}
@subsubsection Deprecated API


The following API is deprecated.

@geindex Py_UNICODE (C type)
@anchor{c-api/unicode c Py_UNICODE}@anchor{b7a}
@deffn {C Τύπος} 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.
Please use @code{wchar_t} directly instead.


Άλλαξε στην έκδοση 3.3: In previous versions, this was a 16-bit type or a 32-bit type depending on
whether you selected a «narrow» or «wide» Unicode version of Python at
build time.



Καταργήθηκε από την έκδοση 3.13, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex PyUnicode_READY (C function)
@anchor{c-api/unicode c PyUnicode_READY}@anchor{647}
@deffn {C Συνάρτηση} int PyUnicode_READY (PyObject *unicode)

Do nothing and return @code{0}.
This API is kept only for backward compatibility, but there are no plans
to remove it.


Added in version 3.3.



Αποσύρθηκε στην έκδοση 3.10: This API does nothing since Python 3.12.
Previously, this needed to be called for each string created using
the old API (@code{PyUnicode_FromUnicode()} or similar).

@end deffn

@geindex PyUnicode_IS_READY (C function)
@anchor{c-api/unicode c PyUnicode_IS_READY}@anchor{56ea}
@deffn {C Συνάρτηση} unsigned int PyUnicode_IS_READY (PyObject *unicode)

Do nothing and return @code{1}.
This API is kept only for backward compatibility, but there are no plans
to remove it.


Added in version 3.3.



Αποσύρθηκε στην έκδοση 3.14: This API does nothing since Python 3.12.
Previously, this could be called to check if
@ref{647,,PyUnicode_READY()} is necessary.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Tuple Objects,Struct Sequence Objects,Unicode Objects and Codecs,Sequence Objects
@anchor{c-api/tuple doc}@anchor{56eb}@anchor{c-api/tuple translation-repo}@anchor{56ec}@anchor{c-api/tuple tuple-objects}@anchor{56ed}@anchor{c-api/tuple tupleobjects}@anchor{56ee}
@subsubsection Tuple Objects


@geindex object;tuple

@geindex PyTupleObject (C type)
@anchor{c-api/tuple c PyTupleObject}@anchor{5580}
@deffn {C Τύπος} type PyTupleObject

This subtype of @ref{19b,,PyObject} represents a Python tuple object.
@end deffn

@geindex PyTuple_Type (C var)
@anchor{c-api/tuple c PyTuple_Type}@anchor{5417}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyTuple_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This instance of @ref{e6b,,PyTypeObject} represents the Python tuple type; it
is the same object as @ref{1ce,,tuple} in the Python layer.
@end deffn

@geindex PyTuple_Check (C function)
@anchor{c-api/tuple c PyTuple_Check}@anchor{56ef}
@deffn {C Συνάρτηση} 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{56f0}
@deffn {C Συνάρτηση} 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{830}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyTuple_New (Py_ssize_t len)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Return a new tuple object of size `len',
or @code{NULL} with an exception set on failure.
@end deffn

@geindex PyTuple_FromArray (C function)
@anchor{c-api/tuple c PyTuple_FromArray}@anchor{36a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyTuple_FromArray (PyObject *const *array, Py_ssize_t size)
` Thread safety: @ref{292b,,Atomic}.'
Create a tuple of `size' items and copy references from `array' to the new
tuple.

`array' can be NULL if `size' is @code{0}.

On success, return a new reference.
On error, set an exception and return @code{NULL}.


Added in version 3.15.

@end deffn

@geindex PyTuple_Pack (C function)
@anchor{c-api/tuple c PyTuple_Pack}@anchor{5415}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyTuple_Pack (Py_ssize_t n, ...)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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{5416}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyTuple_Size (PyObject *p)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Take a pointer to a tuple object, and return the size of that tuple.
On error, return @code{-1} with an exception set.
@end deffn

@geindex PyTuple_GET_SIZE (C function)
@anchor{c-api/tuple c PyTuple_GET_SIZE}@anchor{56f1}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyTuple_GET_SIZE (PyObject *p)
` Thread safety: @ref{292b,,Atomic}.'
Like @ref{5416,,PyTuple_Size()}, but without error checking.
@end deffn

@geindex PyTuple_GetItem (C function)
@anchor{c-api/tuple c PyTuple_GetItem}@anchor{51ce}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyTuple_GetItem (PyObject *p, Py_ssize_t pos)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
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{18d7,,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{7da,,strong reference}, use
@ref{c70,,Py_NewRef(PyTuple_GetItem(...))}
or @ref{2021,,PySequence_GetItem()}.
@end deffn

@geindex PyTuple_GET_ITEM (C function)
@anchor{c-api/tuple c PyTuple_GET_ITEM}@anchor{56f2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyTuple_GET_ITEM (PyObject *p, Py_ssize_t pos)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Like @ref{51ce,,PyTuple_GetItem()}, but does no checking of its arguments.
@end deffn

@geindex PyTuple_GetSlice (C function)
@anchor{c-api/tuple c PyTuple_GetSlice}@anchor{5414}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyTuple_GetSlice (PyObject *p, Py_ssize_t low, Py_ssize_t high)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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{51cf}
@deffn {C Συνάρτηση} int PyTuple_SetItem (PyObject *p, Py_ssize_t pos, PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
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{18d7,,IndexError} exception. This function should only be used to fill in brand new tuples;
using it on an existing tuple is thread-unsafe.

@cartouche
@quotation Σημείωση 
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{821}
@deffn {C Συνάρτηση} void PyTuple_SET_ITEM (PyObject *p, Py_ssize_t pos, PyObject *o)
` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Like @ref{51cf,,PyTuple_SetItem()}, but does no error checking, and should `only' be
used to fill in brand new tuples, using it on an existing tuple is thread-unsafe.

Bounds checking is performed as an assertion if Python is built in
@ref{3dc,,debug mode} or @ref{820,,with assertions}.

@cartouche
@quotation Σημείωση 
This function «steals» a reference to `o', and, unlike
@ref{51cf,,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

@cartouche
@quotation Προειδοποίηση 
This macro should `only' be used on tuples that are newly created.
Using this macro on a tuple that is already in use (or in other words, has
a refcount > 1) could lead to undefined behavior.
@end quotation
@end cartouche
@end deffn

@geindex _PyTuple_Resize (C function)
@anchor{c-api/tuple c _PyTuple_Resize}@anchor{18ad}
@deffn {C Συνάρτηση} int _PyTuple_Resize (PyObject **p, Py_ssize_t newsize)
` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
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{18fa,,MemoryError} or @ref{3ea,,SystemError}.
@end deffn

@node Struct Sequence Objects,List Objects,Tuple Objects,Sequence Objects
@anchor{c-api/tuple id1}@anchor{56f3}@anchor{c-api/tuple struct-sequence-objects}@anchor{1568}
@subsubsection Struct Sequence Objects


A struct sequence object is a @ref{a3d,,named tuple}, that is, a sequence
whose items can also be accessed through attributes.
It is similar to @ref{1cf,,collections.namedtuple()}, but provides a slightly
different interface.

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{53f3}
@deffn {C Συνάρτηση} @ref{e6b,,PyTypeObject} *PyStructSequence_NewType (PyStructSequence_Desc *desc)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Create a new struct sequence type from the data in `desc', described below. Instances
of the resulting type can be created with @ref{53f2,,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{13ac}
@deffn {C Συνάρτηση} void PyStructSequence_InitType (PyTypeObject *type, PyStructSequence_Desc *desc)
` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
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{13ab}
@deffn {C Συνάρτηση} int PyStructSequence_InitType2 (PyTypeObject *type, PyStructSequence_Desc *desc)
` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
Like @ref{13ac,,PyStructSequence_InitType()}, but returns @code{0} on success
and @code{-1} with an exception set on failure.


Added in version 3.4.

@end deffn

@geindex PyStructSequence_Desc (C type)
@anchor{c-api/tuple c PyStructSequence_Desc}@anchor{f79}
@deffn {C Τύπος} type PyStructSequence_Desc
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών).'
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{56f4}
@deffn {C Μέλος} 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{56f5}
@deffn {C Μέλος} 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{56f6}
@deffn {C Μέλος} @ref{f78,,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{56f7}
@deffn {C Μέλος} 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{f78}
@deffn {C Τύπος} type PyStructSequence_Field
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών).'
Describes a field of a struct sequence. As a struct sequence is modeled as a
tuple, all fields are typed as @ref{19b,,PyObject}*.  The index in the
@ref{56f6,,fields} array of
the @ref{f79,,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{56f8}
@deffn {C Μέλος} const char *name

Name for the field or @code{NULL} to end the list of named fields,
set to @ref{d4a,,PyStructSequence_UnnamedField} to leave unnamed.
@end deffn

@geindex PyStructSequence_Field.doc (C member)
@anchor{c-api/tuple c PyStructSequence_Field doc}@anchor{56f9}
@deffn {C Μέλος} 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{d4a}
@deffn {C Μεταβλητή} const char *const PyStructSequence_UnnamedField
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Special value for a field name to leave it unnamed.


Άλλαξε στην έκδοση 3.9: The type was changed from @code{char *}.

@end deffn

@geindex PyStructSequence_New (C function)
@anchor{c-api/tuple c PyStructSequence_New}@anchor{53f2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyStructSequence_New (PyTypeObject *type)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Creates an instance of `type', which must have been created with
@ref{53f3,,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{53f1}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyStructSequence_GetItem (PyObject *p, Py_ssize_t pos)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Return the object at position `pos' in the struct sequence pointed to by `p'.
The returned reference is borrowed from the struct sequence `p'
(that is: it is only valid as long as you hold a reference to `p').

Bounds checking is performed as an assertion if Python is built in
@ref{3dc,,debug mode} or @ref{820,,with assertions}.
@end deffn

@geindex PyStructSequence_GET_ITEM (C function)
@anchor{c-api/tuple c PyStructSequence_GET_ITEM}@anchor{56fa}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyStructSequence_GET_ITEM (PyObject *p, Py_ssize_t pos)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Alias to @ref{53f1,,PyStructSequence_GetItem()}.


Άλλαξε στην έκδοση 3.13: Now implemented as an alias to @ref{53f1,,PyStructSequence_GetItem()}.

@end deffn

@geindex PyStructSequence_SetItem (C function)
@anchor{c-api/tuple c PyStructSequence_SetItem}@anchor{53f4}
@deffn {C Συνάρτηση} void PyStructSequence_SetItem (PyObject *p, Py_ssize_t pos, PyObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Sets the field at index `pos' of the struct sequence `p' to value `o'.  Like
@ref{821,,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{3dc,,debug mode} or @ref{820,,with assertions}.

@cartouche
@quotation Σημείωση 
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{56fb}
@deffn {C Συνάρτηση} void PyStructSequence_SET_ITEM (PyObject *p, Py_ssize_t *pos, PyObject *o)
` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Alias to @ref{53f4,,PyStructSequence_SetItem()}.


Άλλαξε στην έκδοση 3.13: Now implemented as an alias to @ref{53f4,,PyStructSequence_SetItem()}.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node List Objects,,Struct Sequence Objects,Sequence Objects
@anchor{c-api/list doc}@anchor{56fc}@anchor{c-api/list list-objects}@anchor{56fd}@anchor{c-api/list listobjects}@anchor{56fe}@anchor{c-api/list translation-repo}@anchor{56ff}
@subsubsection List Objects


@geindex object;list

@geindex PyListObject (C type)
@anchor{c-api/list c PyListObject}@anchor{2929}
@deffn {C Τύπος} type PyListObject

This subtype of @ref{19b,,PyObject} represents a Python list object.
@end deffn

@geindex PyList_Type (C var)
@anchor{c-api/list c PyList_Type}@anchor{51f0}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyList_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This instance of @ref{e6b,,PyTypeObject} represents the Python list type.
This is the same object as @ref{4d9,,list} in the Python layer.
@end deffn

@geindex PyList_Check (C function)
@anchor{c-api/list c PyList_Check}@anchor{5700}
@deffn {C Συνάρτηση} int PyList_Check (PyObject *p)
` Thread safety: @ref{292b,,Atomic}.'
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{5701}
@deffn {C Συνάρτηση} int PyList_CheckExact (PyObject *p)
` Thread safety: @ref{292b,,Atomic}.'
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{5260}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyList_New (Py_ssize_t len)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Return a new list of length `len' on success, or @code{NULL} on failure.

@cartouche
@quotation Σημείωση 
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{2022,,PySequence_SetItem()} or expose the object to Python code before
setting all items to a real object with @ref{1adb,,PyList_SetItem()} or
@ref{822,,PyList_SET_ITEM()}. The following APIs are safe APIs before
the list is fully initialized: @code{PyList_SetItem()} and @code{PyList_SET_ITEM()}.
@end quotation
@end cartouche
@end deffn

@geindex PyList_Size (C function)
@anchor{c-api/list c PyList_Size}@anchor{17bc}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyList_Size (PyObject *list)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
@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{5702}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyList_GET_SIZE (PyObject *list)
` Thread safety: @ref{292b,,Atomic}.'
Similar to @ref{17bc,,PyList_Size()}, but without error checking.
@end deffn

@geindex PyList_GetItemRef (C function)
@anchor{c-api/list c PyList_GetItemRef}@anchor{7f4}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyList_GetItemRef (PyObject *list, Py_ssize_t index)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'` Thread safety: @ref{292b,,Atomic}.'
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{18d7,,IndexError} exception.


Added in version 3.13.

@end deffn

@geindex PyList_GetItem (C function)
@anchor{c-api/list c PyList_GetItem}@anchor{7f5}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyList_GetItem (PyObject *list, Py_ssize_t index)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Like @ref{7f4,,PyList_GetItemRef()}, but returns a
@ref{603,,borrowed reference} instead of a @ref{7da,,strong reference}.

@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, the returned
@ref{603,,borrowed reference} may become invalid if another thread modifies
the list concurrently. Prefer @ref{7f4,,PyList_GetItemRef()}, which returns
a @ref{7da,,strong reference}.
@end quotation
@end cartouche
@end deffn

@geindex PyList_GET_ITEM (C function)
@anchor{c-api/list c PyList_GET_ITEM}@anchor{5275}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyList_GET_ITEM (PyObject *list, Py_ssize_t i)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Similar to @ref{7f5,,PyList_GetItem()}, but without error checking.

@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, the returned
@ref{603,,borrowed reference} may become invalid if another thread modifies
the list concurrently. Prefer @ref{7f4,,PyList_GetItemRef()}, which returns
a @ref{7da,,strong reference}.
@end quotation
@end cartouche
@end deffn

@geindex PyList_SetItem (C function)
@anchor{c-api/list c PyList_SetItem}@anchor{1adb}
@deffn {C Συνάρτηση} int PyList_SetItem (PyObject *list, Py_ssize_t index, PyObject *item)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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{18d7,,IndexError}
exception.

@cartouche
@quotation Σημείωση 
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{822}
@deffn {C Συνάρτηση} void PyList_SET_ITEM (PyObject *list, Py_ssize_t i, PyObject *o)
` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Macro form of @ref{1adb,,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{3dc,,debug mode} or @ref{820,,with assertions}.

@cartouche
@quotation Σημείωση 
This macro «steals» a reference to `item', and, unlike
@ref{1adb,,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

@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, this macro has no internal
synchronization. It is normally only used to fill in new lists where no
other thread has a reference to the list. If the list may be shared,
use @ref{1adb,,PyList_SetItem()} instead, which uses a @ref{2927,,per-object lock}.
@end quotation
@end cartouche
@end deffn

@geindex PyList_Insert (C function)
@anchor{c-api/list c PyList_Insert}@anchor{1ada}
@deffn {C Συνάρτηση} int PyList_Insert (PyObject *list, Py_ssize_t index, PyObject *item)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
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{5371}
@deffn {C Συνάρτηση} int PyList_Append (PyObject *list, PyObject *item)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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{5373}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyList_GetSlice (PyObject *list, Py_ssize_t low, Py_ssize_t high)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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{5375}
@deffn {C Συνάρτηση} int PyList_SetSlice (PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
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.

@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, when `itemlist' is a @ref{4d9,,list},
both `list' and `itemlist' are locked for the duration of the operation.
For other iterables (or @code{NULL}), only `list' is locked.
@end quotation
@end cartouche
@end deffn

@geindex PyList_Extend (C function)
@anchor{c-api/list c PyList_Extend}@anchor{7f6}
@deffn {C Συνάρτηση} int PyList_Extend (PyObject *list, PyObject *iterable)
` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
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{4d9,,list}
object. Return 0 on success.


Added in version 3.13.


@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, when `iterable' is a @ref{4d9,,list},
@ref{42b,,set}, @ref{188,,dict}, or dict view, both `list' and `iterable'
(or its underlying dict) are locked for the duration of the operation.
For other iterables, only `list' is locked; `iterable' may be
concurrently modified by another thread.
@end quotation
@end cartouche
@end deffn

@geindex PyList_Clear (C function)
@anchor{c-api/list c PyList_Clear}@anchor{7f7}
@deffn {C Συνάρτηση} int PyList_Clear (PyObject *list)
` Thread safety: @ref{292b,,Atomic}.'
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{4d9,,list}
object.  Return 0 on success.


Added in version 3.13.

@end deffn

@geindex PyList_Sort (C function)
@anchor{c-api/list c PyList_Sort}@anchor{5376}
@deffn {C Συνάρτηση} int PyList_Sort (PyObject *list)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Sort the items of `list' in place.  Return @code{0} on success, @code{-1} on
failure.  This is equivalent to @code{list.sort()}.

@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, element comparison via
@ref{1645,,__lt__()} can execute arbitrary Python code, during which
the @ref{2927,,per-object lock} may be temporarily released. For built-in
types (@ref{1df,,str}, @ref{326,,int}, @ref{327,,float}), the lock is not
released during comparison.
@end quotation
@end cartouche
@end deffn

@geindex PyList_Reverse (C function)
@anchor{c-api/list c PyList_Reverse}@anchor{5374}
@deffn {C Συνάρτηση} int PyList_Reverse (PyObject *list)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
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{5372}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyList_AsTuple (PyObject *list)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
@geindex built-in function;tuple

Return a new tuple object containing the contents of `list'; equivalent to
@code{tuple(list)}.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Container Objects,Function Objects<2>,Sequence Objects,Concrete Objects Layer
@anchor{c-api/concrete container-objects}@anchor{5703}@anchor{c-api/concrete mapobjects}@anchor{5704}
@subsection Container Objects


@geindex object;mapping

@menu
* Dictionary objects:: 
* Set Objects:: 

@end menu

@node Dictionary objects,Set Objects,,Container Objects
@anchor{c-api/dict doc}@anchor{5705}@anchor{c-api/dict dictionary-objects}@anchor{5706}@anchor{c-api/dict dictobjects}@anchor{5707}
@subsubsection Dictionary objects


@geindex object;dictionary

@geindex PyDictObject (C type)
@anchor{c-api/dict c PyDictObject}@anchor{83e}
@deffn {C Τύπος} type PyDictObject

This subtype of @ref{19b,,PyObject} represents a Python dictionary object.
@end deffn

@geindex PyDict_Type (C var)
@anchor{c-api/dict c PyDict_Type}@anchor{52f0}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDict_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This instance of @ref{e6b,,PyTypeObject} represents the Python dictionary
type.  This is the same object as @ref{188,,dict} in the Python layer.
@end deffn

@geindex PyDict_Check (C function)
@anchor{c-api/dict c PyDict_Check}@anchor{5638}
@deffn {C Συνάρτηση} int PyDict_Check (PyObject *p)
` Thread safety: @ref{292b,,Atomic}.'
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{5708}
@deffn {C Συνάρτηση} int PyDict_CheckExact (PyObject *p)
` Thread safety: @ref{292b,,Atomic}.'
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{52ee}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDict_New ()
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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{52e1}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDictProxy_New (PyObject *mapping)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a @ref{189,,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.

The first argument can be a @ref{188,,dict}, a @ref{182,,frozendict}, or a
mapping.


Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDictProxy_Type (C var)
@anchor{c-api/dict c PyDictProxy_Type}@anchor{52e2}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDictProxy_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type object for mapping proxy objects created by
@ref{52e1,,PyDictProxy_New()} and for the read-only @code{__dict__} attribute
of many built-in types. A @ref{52e2,,PyDictProxy_Type} instance provides a
dynamic, read-only view of an underlying dictionary: changes to the
underlying dictionary are reflected in the proxy, but the proxy itself
does not support mutation operations. This corresponds to
@ref{189,,types.MappingProxyType} in Python.
@end deffn

@geindex PyDict_Clear (C function)
@anchor{c-api/dict c PyDict_Clear}@anchor{52e7}
@deffn {C Συνάρτηση} void PyDict_Clear (PyObject *p)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Empty an existing dictionary of all key-value pairs.

Do nothing if the argument is not a @ref{188,,dict} or a @code{dict}
subclass.
@end deffn

@geindex PyDict_Contains (C function)
@anchor{c-api/dict c PyDict_Contains}@anchor{7d7}
@deffn {C Συνάρτηση} int PyDict_Contains (PyObject *p, PyObject *key)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Determine if dictionary `p' contains `key'.  If an item in `p' 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}.

The first argument can be a @ref{188,,dict} or a @ref{182,,frozendict}.

@cartouche
@quotation Σημείωση 
The operation is atomic on @ref{198,,free threading}
when `key' is @ref{1df,,str}, @ref{326,,int}, @ref{327,,float}, @ref{5ef,,bool} or @ref{1c7,,bytes}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDict_ContainsString (C function)
@anchor{c-api/dict c PyDict_ContainsString}@anchor{7d6}
@deffn {C Συνάρτηση} int PyDict_ContainsString (PyObject *p, const char *key)
` Thread safety: @ref{292b,,Atomic}.'
This is the same as @ref{7d7,,PyDict_Contains()}, but `key' is specified as a
const char* UTF-8 encoded bytes string, rather than a
@ref{19b,,PyObject}*.

The first argument can be a @ref{188,,dict} or a @ref{182,,frozendict}.


Added in version 3.13.



Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDict_Copy (C function)
@anchor{c-api/dict c PyDict_Copy}@anchor{84f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDict_Copy (PyObject *p)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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{51d0}
@deffn {C Συνάρτηση} int PyDict_SetItem (PyObject *p, PyObject *key, PyObject *val)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Insert `val' into the dictionary `p' with a key of `key'.  `key' must be
@ref{183,,hashable}; if it isn’t, @ref{291,,TypeError} will be raised. Return
@code{0} on success or @code{-1} on failure.  This function `does not' steal a
reference to `val'.

@cartouche
@quotation Σημείωση 
The operation is atomic on @ref{198,,free threading}
when `key' is @ref{1df,,str}, @ref{326,,int}, @ref{327,,float}, @ref{5ef,,bool} or @ref{1c7,,bytes}.
@end quotation
@end cartouche
@end deffn

@geindex PyDict_SetItemString (C function)
@anchor{c-api/dict c PyDict_SetItemString}@anchor{1b9b}
@deffn {C Συνάρτηση} int PyDict_SetItemString (PyObject *p, const char *key, PyObject *val)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
This is the same as @ref{51d0,,PyDict_SetItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.
@end deffn

@geindex PyDict_DelItem (C function)
@anchor{c-api/dict c PyDict_DelItem}@anchor{52e8}
@deffn {C Συνάρτηση} int PyDict_DelItem (PyObject *p, PyObject *key)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Remove the entry in dictionary `p' with key `key'. `key' must be @ref{183,,hashable};
if it isn’t, @ref{291,,TypeError} is raised.
If `key' is not in the dictionary, @ref{7df,,KeyError} is raised.
Return @code{0} on success or @code{-1} on failure.

@cartouche
@quotation Σημείωση 
The operation is atomic on @ref{198,,free threading}
when `key' is @ref{1df,,str}, @ref{326,,int}, @ref{327,,float}, @ref{5ef,,bool} or @ref{1c7,,bytes}.
@end quotation
@end cartouche
@end deffn

@geindex PyDict_DelItemString (C function)
@anchor{c-api/dict c PyDict_DelItemString}@anchor{52e9}
@deffn {C Συνάρτηση} int PyDict_DelItemString (PyObject *p, const char *key)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
This is the same as @ref{52e8,,PyDict_DelItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{19b,,PyObject}*.
@end deffn

@geindex PyDict_GetItemRef (C function)
@anchor{c-api/dict c PyDict_GetItemRef}@anchor{7d8}
@deffn {C Συνάρτηση} int PyDict_GetItemRef (PyObject *p, PyObject *key, PyObject **result)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Return a new @ref{7da,,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{7da,,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, set `*result' to @code{NULL} and return @code{-1}.
@end itemize

The first argument can be a @ref{188,,dict} or a @ref{182,,frozendict}.

@cartouche
@quotation Σημείωση 
The operation is atomic on @ref{198,,free threading}
when `key' is @ref{1df,,str}, @ref{326,,int}, @ref{327,,float}, @ref{5ef,,bool} or @ref{1c7,,bytes}.
@end quotation
@end cartouche


Added in version 3.13.



Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.


See also the @ref{7e2,,PyObject_GetItem()} function.
@end deffn

@geindex PyDict_GetItem (C function)
@anchor{c-api/dict c PyDict_GetItem}@anchor{81c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDict_GetItem (PyObject *p, PyObject *key)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Return a @ref{603,,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.

The first argument can be a @ref{188,,dict} or a @ref{182,,frozendict}.

@cartouche
@quotation Σημείωση 
Exceptions that occur while this calls @ref{ec1,,__hash__()} and
@ref{ec0,,__eq__()} methods are silently ignored.
Prefer the @ref{7d9,,PyDict_GetItemWithError()} function instead.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, the returned
@ref{603,,borrowed reference} may become invalid if another thread modifies
the dictionary concurrently. Prefer @ref{7d8,,PyDict_GetItemRef()}, which
returns a @ref{7da,,strong reference}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.10: Calling this API without an @ref{1a1,,attached thread state} had been allowed for historical
reason. It is no longer allowed.



Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDict_GetItemWithError (C function)
@anchor{c-api/dict c PyDict_GetItemWithError}@anchor{7d9}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDict_GetItemWithError (PyObject *p, PyObject *key)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Variant of @ref{81c,,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.

@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, the returned
@ref{603,,borrowed reference} may become invalid if another thread modifies
the dictionary concurrently. Prefer @ref{7d8,,PyDict_GetItemRef()}, which
returns a @ref{7da,,strong reference}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDict_GetItemString (C function)
@anchor{c-api/dict c PyDict_GetItemString}@anchor{81d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDict_GetItemString (PyObject *p, const char *key)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
This is the same as @ref{81c,,PyDict_GetItem()}, but `key' is specified as a
const char* UTF-8 encoded bytes string, rather than a
@ref{19b,,PyObject}*.

@cartouche
@quotation Σημείωση 
Exceptions that occur while this calls @ref{ec1,,__hash__()} and
@ref{ec0,,__eq__()} methods or while creating the temporary @ref{1df,,str}
object are silently ignored.
Prefer using the @ref{7d9,,PyDict_GetItemWithError()} function with your own
@ref{5451,,PyUnicode_FromString()} `key' instead.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, the returned
@ref{603,,borrowed reference} may become invalid if another thread modifies
the dictionary concurrently. Prefer @ref{634,,PyDict_GetItemStringRef()},
which returns a @ref{7da,,strong reference}.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDict_GetItemStringRef (C function)
@anchor{c-api/dict c PyDict_GetItemStringRef}@anchor{634}
@deffn {C Συνάρτηση} int PyDict_GetItemStringRef (PyObject *p, const char *key, PyObject **result)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'` Thread safety: @ref{292b,,Atomic}.'
Similar to @ref{7d8,,PyDict_GetItemRef()}, but `key' is specified as a
const char* UTF-8 encoded bytes string, rather than a
@ref{19b,,PyObject}*.


Added in version 3.13.



Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDict_SetDefault (C function)
@anchor{c-api/dict c PyDict_SetDefault}@anchor{7dc}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDict_SetDefault (PyObject *p, PyObject *key, PyObject *defaultobj)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
This is the same as the Python-level @ref{1421,,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.


Added in version 3.4.


@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, the returned
@ref{603,,borrowed reference} may become invalid if another thread modifies
the dictionary concurrently. Prefer @ref{7db,,PyDict_SetDefaultRef()},
which returns a @ref{7da,,strong reference}.
@end quotation
@end cartouche
@end deffn

@geindex PyDict_SetDefaultRef (C function)
@anchor{c-api/dict c PyDict_SetDefaultRef}@anchor{7db}
@deffn {C Συνάρτηση} int PyDict_SetDefaultRef (PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
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{7da,,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.

@cartouche
@quotation Σημείωση 
The operation is atomic on @ref{198,,free threading}
when `key' is @ref{1df,,str}, @ref{326,,int}, @ref{327,,float}, @ref{5ef,,bool} or @ref{1c7,,bytes}.
@end quotation
@end cartouche


Added in version 3.13.

@end deffn

@geindex PyDict_Pop (C function)
@anchor{c-api/dict c PyDict_Pop}@anchor{635}
@deffn {C Συνάρτηση} int PyDict_Pop (PyObject *p, PyObject *key, PyObject **result)
` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Remove `key' from dictionary `p' and optionally return the removed value.
Do not raise @ref{7df,,KeyError} if the key is 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

Similar to @ref{7de,,dict.pop()}, but without the default value and
not raising @ref{7df,,KeyError} if the key is missing.

@cartouche
@quotation Σημείωση 
The operation is atomic on @ref{198,,free threading}
when `key' is @ref{1df,,str}, @ref{326,,int}, @ref{327,,float}, @ref{5ef,,bool} or @ref{1c7,,bytes}.
@end quotation
@end cartouche


Added in version 3.13.

@end deffn

@geindex PyDict_PopString (C function)
@anchor{c-api/dict c PyDict_PopString}@anchor{7dd}
@deffn {C Συνάρτηση} int PyDict_PopString (PyObject *p, const char *key, PyObject **result)
` Thread safety: @ref{292b,,Atomic}.'
Similar to @ref{635,,PyDict_Pop()}, but `key' is specified as a
const char* UTF-8 encoded bytes string, rather than a
@ref{19b,,PyObject}*.


Added in version 3.13.

@end deffn

@geindex PyDict_Items (C function)
@anchor{c-api/dict c PyDict_Items}@anchor{52ea}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDict_Items (PyObject *p)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Return a @ref{2929,,PyListObject} containing all the items from the dictionary.

The first argument can be a @ref{188,,dict} or a @ref{182,,frozendict}.


Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDict_Keys (C function)
@anchor{c-api/dict c PyDict_Keys}@anchor{52eb}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDict_Keys (PyObject *p)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Return a @ref{2929,,PyListObject} containing all the keys from the dictionary.

The first argument can be a @ref{188,,dict} or a @ref{182,,frozendict}.


Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDict_Values (C function)
@anchor{c-api/dict c PyDict_Values}@anchor{52f2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDict_Values (PyObject *p)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Return a @ref{2929,,PyListObject} containing all the values from the dictionary
`p'.

The first argument can be a @ref{188,,dict} or a @ref{182,,frozendict}.


Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDict_Size (C function)
@anchor{c-api/dict c PyDict_Size}@anchor{52ef}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyDict_Size (PyObject *p)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
@geindex built-in function;len

Return the number of items in the dictionary.  This is equivalent to
@code{len(p)} on a dictionary.

The argument can be a @ref{188,,dict} or a @ref{182,,frozendict}.


Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDict_GET_SIZE (C function)
@anchor{c-api/dict c PyDict_GET_SIZE}@anchor{5709}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyDict_GET_SIZE (PyObject *p)
` Thread safety: @ref{292b,,Atomic}.'
Similar to @ref{52ef,,PyDict_Size()}, but without error checking.


Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDict_Next (C function)
@anchor{c-api/dict c PyDict_Next}@anchor{1b9c}
@deffn {C Συνάρτηση} int PyDict_Next (PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Iterate over all key-value pairs in the dictionary `p'.  The
@ref{e24,,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{19b,,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.

The first argument can be a @ref{188,,dict} or a @ref{182,,frozendict}.

For example:

@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{487,,free-threaded}
build without external synchronization for a mutable @ref{188,,dict}. You can use
@ref{5469,,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

The function is thread-safe on a @ref{182,,frozendict}.

@cartouche
@quotation Σημείωση 
On the free-threaded build, this function can be used safely inside a
critical section. However, the references returned for `pkey' and `pvalue'
are @ref{603,,borrowed} and are only valid while the
critical section is held. If you need to use these objects outside the
critical section or when the critical section can be suspended, create a
@ref{7da,,strong reference} (for example, using
@ref{c70,,Py_NewRef()}).
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.15: Also accept @ref{182,,frozendict}.

@end deffn

@geindex PyDict_Merge (C function)
@anchor{c-api/dict c PyDict_Merge}@anchor{52ec}
@deffn {C Συνάρτηση} int PyDict_Merge (PyObject *a, PyObject *b, int override)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Iterate over mapping object `b' adding key-value pairs to dictionary `a'.
`b' may be a dictionary, or any object supporting @ref{f7a,,PyMapping_Keys()}
and @ref{7e2,,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.

@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, when `b' is a
@ref{188,,dict} (with the standard iterator), both `a' and `b' are locked
for the duration of the operation. When `b' is a non-dict mapping, only
`a' is locked; `b' may be concurrently modified by another thread.
@end quotation
@end cartouche
@end deffn

@geindex PyDict_Update (C function)
@anchor{c-api/dict c PyDict_Update}@anchor{52f1}
@deffn {C Συνάρτηση} int PyDict_Update (PyObject *a, PyObject *b)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
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{52f1,,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.

@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, when `b' is a
@ref{188,,dict} (with the standard iterator), both `a' and `b' are locked
for the duration of the operation. When `b' is a non-dict mapping, only
`a' is locked; `b' may be concurrently modified by another thread.
@end quotation
@end cartouche
@end deffn

@geindex PyDict_MergeFromSeq2 (C function)
@anchor{c-api/dict c PyDict_MergeFromSeq2}@anchor{52ed}
@deffn {C Συνάρτηση} int PyDict_MergeFromSeq2 (PyObject *a, PyObject *seq2, int override)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
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

@cartouche
@quotation Σημείωση 
In the @ref{487,,free-threaded} build, only `a' is locked.
The iteration over `seq2' is not synchronized; `seq2' may be concurrently
modified by another thread.
@end quotation
@end cartouche
@end deffn

@geindex PyDict_AddWatcher (C function)
@anchor{c-api/dict c PyDict_AddWatcher}@anchor{5fc}
@deffn {C Συνάρτηση} int PyDict_AddWatcher (PyDict_WatchCallback callback)
` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Register `callback' as a dictionary watcher. Return a non-negative integer
id which must be passed to future calls to @ref{969,,PyDict_Watch()}. In case
of error (e.g. no more watcher IDs available), return @code{-1} and set an
exception.

@cartouche
@quotation Σημείωση 
This function is not internally synchronized. In the
@ref{487,,free-threaded} build, callers should ensure no
concurrent calls to @ref{5fc,,PyDict_AddWatcher()} or
@ref{570a,,PyDict_ClearWatcher()} are in progress.
@end quotation
@end cartouche


Added in version 3.12.

@end deffn

@geindex PyDict_ClearWatcher (C function)
@anchor{c-api/dict c PyDict_ClearWatcher}@anchor{570a}
@deffn {C Συνάρτηση} int PyDict_ClearWatcher (int watcher_id)
` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
Clear watcher identified by `watcher_id' previously returned from
@ref{5fc,,PyDict_AddWatcher()}. Return @code{0} on success, @code{-1} on error (e.g.
if the given `watcher_id' was never registered.)

@cartouche
@quotation Σημείωση 
This function is not internally synchronized. In the
@ref{487,,free-threaded} build, callers should ensure no
concurrent calls to @ref{5fc,,PyDict_AddWatcher()} or
@ref{570a,,PyDict_ClearWatcher()} are in progress.
@end quotation
@end cartouche


Added in version 3.12.

@end deffn

@geindex PyDict_Watch (C function)
@anchor{c-api/dict c PyDict_Watch}@anchor{969}
@deffn {C Συνάρτηση} int PyDict_Watch (int watcher_id, PyObject *dict)
` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
Mark dictionary `dict' as watched. The callback granted `watcher_id' by
@ref{5fc,,PyDict_AddWatcher()} will be called when `dict' is modified or
deallocated. Return @code{0} on success or @code{-1} on error.


Added in version 3.12.

@end deffn

@geindex PyDict_Unwatch (C function)
@anchor{c-api/dict c PyDict_Unwatch}@anchor{18fd}
@deffn {C Συνάρτηση} int PyDict_Unwatch (int watcher_id, PyObject *dict)
` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
Mark dictionary `dict' as no longer watched. The callback granted
`watcher_id' by @ref{5fc,,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.


Added in version 3.12.

@end deffn

@geindex PyDict_WatchEvent (C type)
@anchor{c-api/dict c PyDict_WatchEvent}@anchor{570b}
@deffn {C Τύπος} 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}.


Added in version 3.12.

@end deffn

@geindex PyDict_WatchCallback (C type)
@anchor{c-api/dict c PyDict_WatchCallback}@anchor{570c}
@deffn {C Τύπος} typedef int (*PyDict_WatchCallback)(@ref{570b,,PyDict_WatchEvent} event, @ref{19b,,PyObject} *dict, @ref{19b,,PyObject} *key, @ref{19b,,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{7e8,,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.


Added in version 3.12.

@end deffn

@menu
* Dictionary view objects:: 
* Frozen dictionary objects:: 
* Ordered dictionaries:: 

@end menu

@node Dictionary view objects,Frozen dictionary objects,,Dictionary objects
@anchor{c-api/dict dictionary-view-objects}@anchor{570d}
@subsubsection Dictionary view objects


@geindex PyDictViewSet_Check (C function)
@anchor{c-api/dict c PyDictViewSet_Check}@anchor{570e}
@deffn {C Συνάρτηση} int PyDictViewSet_Check (PyObject *op)

Return true if `op' is a view of a set inside a dictionary. This is currently
equivalent to @ref{570f,,PyDictKeys_Check}(@ref{570e,,op}) || @ref{5710,,PyDictItems_Check}(op). This
function always succeeds.
@end deffn

@geindex PyDictKeys_Type (C var)
@anchor{c-api/dict c PyDictKeys_Type}@anchor{52e0}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDictKeys_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Type object for a view of dictionary keys. In Python, this is the type of
the object returned by @ref{bad,,dict.keys()}.
@end deffn

@geindex PyDictKeys_Check (C function)
@anchor{c-api/dict c PyDictKeys_Check}@anchor{570f}
@deffn {C Συνάρτηση} int PyDictKeys_Check (PyObject *op)

Return true if `op' is an instance of a dictionary keys view. This function
always succeeds.
@end deffn

@geindex PyDictValues_Type (C var)
@anchor{c-api/dict c PyDictValues_Type}@anchor{52e6}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDictValues_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Type object for a view of dictionary values. In Python, this is the type of
the object returned by @ref{bae,,dict.values()}.
@end deffn

@geindex PyDictValues_Check (C function)
@anchor{c-api/dict c PyDictValues_Check}@anchor{5711}
@deffn {C Συνάρτηση} int PyDictValues_Check (PyObject *op)

Return true if `op' is an instance of a dictionary values view. This function
always succeeds.
@end deffn

@geindex PyDictItems_Type (C var)
@anchor{c-api/dict c PyDictItems_Type}@anchor{52dc}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDictItems_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Type object for a view of dictionary items. In Python, this is the type of
the object returned by @ref{baf,,dict.items()}.
@end deffn

@geindex PyDictItems_Check (C function)
@anchor{c-api/dict c PyDictItems_Check}@anchor{5710}
@deffn {C Συνάρτηση} int PyDictItems_Check (PyObject *op)

Return true if `op' is an instance of a dictionary items view. This function
always succeeds.
@end deffn

@node Frozen dictionary objects,Ordered dictionaries,Dictionary view objects,Dictionary objects
@anchor{c-api/dict frozen-dictionary-objects}@anchor{5712}
@subsubsection Frozen dictionary objects



Added in version 3.15.


@geindex PyFrozenDict_Type (C var)
@anchor{c-api/dict c PyFrozenDict_Type}@anchor{5713}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyFrozenDict_Type

This instance of @ref{e6b,,PyTypeObject} represents the Python frozen
dictionary type.
This is the same object as @ref{182,,frozendict} in the Python layer.
@end deffn

@geindex PyAnyDict_Check (C function)
@anchor{c-api/dict c PyAnyDict_Check}@anchor{34c}
@deffn {C Συνάρτηση} int PyAnyDict_Check (PyObject *p)

Return true if `p' is a @ref{188,,dict} object, a @ref{182,,frozendict} object,
or an instance of a subtype of the @code{dict} or @code{frozendict}
type.
This function always succeeds.
@end deffn

@geindex PyAnyDict_CheckExact (C function)
@anchor{c-api/dict c PyAnyDict_CheckExact}@anchor{34d}
@deffn {C Συνάρτηση} int PyAnyDict_CheckExact (PyObject *p)

Return true if `p' is a @ref{188,,dict} object or a @ref{182,,frozendict} object,
but not an instance of a subtype of the @code{dict} or
@code{frozendict} type.
This function always succeeds.
@end deffn

@geindex PyFrozenDict_Check (C function)
@anchor{c-api/dict c PyFrozenDict_Check}@anchor{34e}
@deffn {C Συνάρτηση} int PyFrozenDict_Check (PyObject *p)

Return true if `p' is a @ref{182,,frozendict} object or an instance of a
subtype of the @code{frozendict} type.
This function always succeeds.
@end deffn

@geindex PyFrozenDict_CheckExact (C function)
@anchor{c-api/dict c PyFrozenDict_CheckExact}@anchor{34f}
@deffn {C Συνάρτηση} int PyFrozenDict_CheckExact (PyObject *p)

Return true if `p' is a @ref{182,,frozendict} object, but not an instance of a
subtype of the @code{frozendict} type.
This function always succeeds.
@end deffn

@geindex PyFrozenDict_New (C function)
@anchor{c-api/dict c PyFrozenDict_New}@anchor{350}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFrozenDict_New (PyObject *iterable)

Return a new @ref{182,,frozendict} from an iterable, or @code{NULL} on failure
with an exception set.

Create an empty dictionary if `iterable' is @code{NULL}.
@end deffn

@node Ordered dictionaries,,Frozen dictionary objects,Dictionary objects
@anchor{c-api/dict ordered-dictionaries}@anchor{5714}
@subsubsection Ordered dictionaries


Python’s C API provides interface for @ref{9d5,,collections.OrderedDict} from C.
Since Python 3.7, dictionaries are ordered by default, so there is usually
little need for these functions; prefer @code{PyDict*} where possible.

@geindex PyODict_Type (C var)
@anchor{c-api/dict c PyODict_Type}@anchor{5715}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyODict_Type

Type object for ordered dictionaries. This is the same object as
@ref{9d5,,collections.OrderedDict} in the Python layer.
@end deffn

@geindex PyODict_Check (C function)
@anchor{c-api/dict c PyODict_Check}@anchor{5716}
@deffn {C Συνάρτηση} int PyODict_Check (PyObject *od)

Return true if `od' is an ordered dictionary object or an instance of a
subtype of the @ref{9d5,,OrderedDict} type.  This function
always succeeds.
@end deffn

@geindex PyODict_CheckExact (C function)
@anchor{c-api/dict c PyODict_CheckExact}@anchor{5717}
@deffn {C Συνάρτηση} int PyODict_CheckExact (PyObject *od)

Return true if `od' is an ordered dictionary object, but not an instance of
a subtype of the @ref{9d5,,OrderedDict} type.
This function always succeeds.
@end deffn

@geindex PyODictKeys_Type (C var)
@anchor{c-api/dict c PyODictKeys_Type}@anchor{5718}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyODictKeys_Type

Analogous to @ref{52e0,,PyDictKeys_Type} for ordered dictionaries.
@end deffn

@geindex PyODictValues_Type (C var)
@anchor{c-api/dict c PyODictValues_Type}@anchor{5719}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyODictValues_Type

Analogous to @ref{52e6,,PyDictValues_Type} for ordered dictionaries.
@end deffn

@geindex PyODictItems_Type (C var)
@anchor{c-api/dict c PyODictItems_Type}@anchor{571a}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyODictItems_Type

Analogous to @ref{52dc,,PyDictItems_Type} for ordered dictionaries.
@end deffn

@geindex PyODict_New (C function)
@anchor{c-api/dict c PyODict_New}@anchor{571b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyODict_New (void)

Return a new empty ordered dictionary, or @code{NULL} on failure.

This is analogous to @ref{52ee,,PyDict_New()}.
@end deffn

@geindex PyODict_SetItem (C function)
@anchor{c-api/dict c PyODict_SetItem}@anchor{571c}
@deffn {C Συνάρτηση} int PyODict_SetItem (PyObject *od, PyObject *key, PyObject *value)

Insert `value' into the ordered dictionary `od' with a key of `key'.
Return @code{0} on success or @code{-1} with an exception set on failure.

This is analogous to @ref{51d0,,PyDict_SetItem()}.
@end deffn

@geindex PyODict_DelItem (C function)
@anchor{c-api/dict c PyODict_DelItem}@anchor{571d}
@deffn {C Συνάρτηση} int PyODict_DelItem (PyObject *od, PyObject *key)

Remove the entry in the ordered dictionary `od' with key `key'.
Return @code{0} on success or @code{-1} with an exception set on failure.

This is analogous to @ref{52e8,,PyDict_DelItem()}.
@end deffn

These are @ref{1a7,,soft deprecated} aliases to @code{PyDict} APIs:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@code{PyODict}

@tab

@code{PyDict}

@item

@geindex PyODict_GetItem (C macro)
@anchor{c-api/dict c PyODict_GetItem}@anchor{571e}
@deffn {C Μακροεντολή} PyODict_GetItem (od, key)
@end deffn

@tab

@ref{81c,,PyDict_GetItem()}

@item

@geindex PyODict_GetItemWithError (C macro)
@anchor{c-api/dict c PyODict_GetItemWithError}@anchor{571f}
@deffn {C Μακροεντολή} PyODict_GetItemWithError (od, key)
@end deffn

@tab

@ref{7d9,,PyDict_GetItemWithError()}

@item

@geindex PyODict_GetItemString (C macro)
@anchor{c-api/dict c PyODict_GetItemString}@anchor{5720}
@deffn {C Μακροεντολή} PyODict_GetItemString (od, key)
@end deffn

@tab

@ref{81d,,PyDict_GetItemString()}

@item

@geindex PyODict_Contains (C macro)
@anchor{c-api/dict c PyODict_Contains}@anchor{5721}
@deffn {C Μακροεντολή} PyODict_Contains (od, key)
@end deffn

@tab

@ref{7d7,,PyDict_Contains()}

@item

@geindex PyODict_Size (C macro)
@anchor{c-api/dict c PyODict_Size}@anchor{5722}
@deffn {C Μακροεντολή} PyODict_Size (od)
@end deffn

@tab

@ref{52ef,,PyDict_Size()}

@item

@geindex PyODict_SIZE (C macro)
@anchor{c-api/dict c PyODict_SIZE}@anchor{5723}
@deffn {C Μακροεντολή} PyODict_SIZE (od)
@end deffn

@tab

@ref{5709,,PyDict_GET_SIZE()}

@end multitable


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Set Objects,,Dictionary objects,Container Objects
@anchor{c-api/set doc}@anchor{5724}@anchor{c-api/set set-objects}@anchor{5725}@anchor{c-api/set setobjects}@anchor{5726}@anchor{c-api/set translation-repo}@anchor{5727}
@subsubsection Set Objects


@geindex object;set
@geindex object;frozenset

This section details the public API for @ref{42b,,set} and @ref{9d4,,frozenset}
objects.  Any functionality not listed below is best accessed using either
the abstract object protocol (including @ref{3b6,,PyObject_CallMethod()},
@ref{1f7e,,PyObject_RichCompareBool()}, @ref{649,,PyObject_Hash()},
@ref{13d7,,PyObject_Repr()}, @ref{53cb,,PyObject_IsTrue()}, @ref{18fe,,PyObject_Print()}, and
@ref{53ca,,PyObject_GetIter()}) or the abstract number protocol (including
@ref{539e,,PyNumber_And()}, @ref{53b7,,PyNumber_Subtract()}, @ref{53b2,,PyNumber_Or()},
@ref{53b9,,PyNumber_Xor()}, @ref{53a3,,PyNumber_InPlaceAnd()},
@ref{53ab,,PyNumber_InPlaceSubtract()}, @ref{53a7,,PyNumber_InPlaceOr()}, and
@ref{53ad,,PyNumber_InPlaceXor()}).

@geindex PySetObject (C type)
@anchor{c-api/set c PySetObject}@anchor{5728}
@deffn {C Τύπος} type PySetObject

This subtype of @ref{19b,,PyObject} is used to hold the internal data for both
@ref{42b,,set} and @ref{9d4,,frozenset} objects.  It is like a @ref{83e,,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{53e7}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PySet_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is an instance of @ref{e6b,,PyTypeObject} representing the Python
@ref{42b,,set} type.
@end deffn

@geindex PyFrozenSet_Type (C var)
@anchor{c-api/set c PyFrozenSet_Type}@anchor{5356}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyFrozenSet_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is an instance of @ref{e6b,,PyTypeObject} representing the Python
@ref{9d4,,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{5729}
@deffn {C Συνάρτηση} int PySet_Check (PyObject *p)

Return true if `p' is a @ref{42b,,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{572a}
@deffn {C Συνάρτηση} int PyFrozenSet_Check (PyObject *p)

Return true if `p' is a @ref{9d4,,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{572b}
@deffn {C Συνάρτηση} int PyAnySet_Check (PyObject *p)

Return true if `p' is a @ref{42b,,set} object, a @ref{9d4,,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{c73}
@deffn {C Συνάρτηση} int PySet_CheckExact (PyObject *p)

Return true if `p' is a @ref{42b,,set} object but not an instance of a
subtype.  This function always succeeds.


Added in version 3.10.

@end deffn

@geindex PyAnySet_CheckExact (C function)
@anchor{c-api/set c PyAnySet_CheckExact}@anchor{572c}
@deffn {C Συνάρτηση} int PyAnySet_CheckExact (PyObject *p)

Return true if `p' is a @ref{42b,,set} object or a @ref{9d4,,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{572d}
@deffn {C Συνάρτηση} int PyFrozenSet_CheckExact (PyObject *p)

Return true if `p' is a @ref{9d4,,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{17e6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySet_New (PyObject *iterable)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Return a new @ref{42b,,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{291,,TypeError} if `iterable' is not
actually iterable.  The constructor is also useful for copying a set
(@code{c=set(s)}).

@cartouche
@quotation Σημείωση 
The operation is atomic on @ref{198,,free threading}
when `iterable' is a @ref{42b,,set}, @ref{9d4,,frozenset}, @ref{188,,dict} or @ref{182,,frozendict}.
@end quotation
@end cartouche
@end deffn

@geindex PyFrozenSet_New (C function)
@anchor{c-api/set c PyFrozenSet_New}@anchor{17e7}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFrozenSet_New (PyObject *iterable)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Return a new @ref{9d4,,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{291,,TypeError} if `iterable' is
not actually iterable.

@cartouche
@quotation Σημείωση 
The operation is atomic on @ref{198,,free threading}
when `iterable' is a @ref{42b,,set}, @ref{9d4,,frozenset}, @ref{188,,dict} or @ref{182,,frozendict}.
@end quotation
@end cartouche
@end deffn

The following functions and macros are available for instances of @ref{42b,,set}
or @ref{9d4,,frozenset} or instances of their subtypes.

@geindex PySet_Size (C function)
@anchor{c-api/set c PySet_Size}@anchor{17eb}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PySet_Size (PyObject *anyset)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
@geindex built-in function;len

Return the length of a @ref{42b,,set} or @ref{9d4,,frozenset} object. Equivalent to
@code{len(anyset)}.  Raises a @ref{3ea,,SystemError} if `anyset' is not a
@code{set}, @code{frozenset}, or an instance of a subtype.
@end deffn

@geindex PySet_GET_SIZE (C function)
@anchor{c-api/set c PySet_GET_SIZE}@anchor{572e}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PySet_GET_SIZE (PyObject *anyset)
` Thread safety: @ref{292b,,Atomic}.'
Macro form of @ref{17eb,,PySet_Size()} without error checking.
@end deffn

@geindex PySet_Contains (C function)
@anchor{c-api/set c PySet_Contains}@anchor{17ea}
@deffn {C Συνάρτηση} int PySet_Contains (PyObject *anyset, PyObject *key)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Return @code{1} if found, @code{0} if not found, and @code{-1} if an error is encountered.  Unlike
the Python @ref{175c,,__contains__()} method, this function does not automatically
convert unhashable sets into temporary frozensets.  Raise a @ref{291,,TypeError} if
the `key' is unhashable. Raise @ref{3ea,,SystemError} if `anyset' is not a
@ref{42b,,set}, @ref{9d4,,frozenset}, or an instance of a subtype.

@cartouche
@quotation Σημείωση 
The operation is atomic on @ref{198,,free threading}
when `key' is @ref{1df,,str}, @ref{326,,int}, @ref{327,,float}, @ref{5ef,,bool} or @ref{1c7,,bytes}.
@end quotation
@end cartouche
@end deffn

@geindex PySet_Add (C function)
@anchor{c-api/set c PySet_Add}@anchor{17e8}
@deffn {C Συνάρτηση} int PySet_Add (PyObject *set, PyObject *key)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
Add `key' to a @ref{42b,,set} instance.  Also works with @ref{9d4,,frozenset}
instances (like @ref{51cf,,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{291,,TypeError} if the `key' is
unhashable. Raise a @ref{18fa,,MemoryError} if there is no room to grow.  Raise a
@ref{3ea,,SystemError} if `set' is not an instance of @code{set} or its
subtype.

@cartouche
@quotation Σημείωση 
The operation is atomic on @ref{198,,free threading}
when `key' is @ref{1df,,str}, @ref{326,,int}, @ref{327,,float}, @ref{5ef,,bool} or @ref{1c7,,bytes}.
@end quotation
@end cartouche
@end deffn

The following functions are available for instances of @ref{42b,,set} or its
subtypes but not for instances of @ref{9d4,,frozenset} or its subtypes.

@geindex PySet_Discard (C function)
@anchor{c-api/set c PySet_Discard}@anchor{17e9}
@deffn {C Συνάρτηση} int PySet_Discard (PyObject *set, PyObject *key)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2926,,Safe for concurrent use on the same object}.'
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{7df,,KeyError} for missing keys.  Raise a
@ref{291,,TypeError} if the `key' is unhashable.  Unlike the Python @ref{2899,,discard()}
method, this function does not automatically convert unhashable sets into
temporary frozensets. Raise @ref{3ea,,SystemError} if `set' is not an
instance of @ref{42b,,set} or its subtype.

@cartouche
@quotation Σημείωση 
The operation is atomic on @ref{198,,free threading}
when `key' is @ref{1df,,str}, @ref{326,,int}, @ref{327,,float}, @ref{5ef,,bool} or @ref{1c7,,bytes}.
@end quotation
@end cartouche
@end deffn

@geindex PySet_Pop (C function)
@anchor{c-api/set c PySet_Pop}@anchor{53e6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySet_Pop (PyObject *set)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
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{7df,,KeyError} if the
set is empty. Raise a @ref{3ea,,SystemError} if `set' is not an instance of
@ref{42b,,set} or its subtype.
@end deffn

@geindex PySet_Clear (C function)
@anchor{c-api/set c PySet_Clear}@anchor{53e5}
@deffn {C Συνάρτηση} int PySet_Clear (PyObject *set)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Empty an existing set of all elements. Return @code{0} on
success. Return @code{-1} and raise @ref{3ea,,SystemError} if `set' is not an instance of
@ref{42b,,set} or its subtype.

@cartouche
@quotation Σημείωση 
In the @ref{198,,free-threaded build}, the set is emptied before its entries
are cleared, so other threads will observe an empty set rather than
intermediate states.
@end quotation
@end cartouche
@end deffn

@menu
* Deprecated API: Deprecated API<3>. 

@end menu

@node Deprecated API<3>,,,Set Objects
@anchor{c-api/set deprecated-api}@anchor{572f}
@subsubsection Deprecated API


@geindex PySet_MINSIZE (C macro)
@anchor{c-api/set c PySet_MINSIZE}@anchor{5730}
@deffn {C Μακροεντολή} PySet_MINSIZE

A constant representing the size of an internal
preallocated table inside @ref{5728,,PySetObject} instances.

This is documented solely for completeness, as there are no guarantees
that a given version of CPython uses preallocated tables with a fixed
size.
In code that does not deal with unstable set internals,
@code{PySet_MINSIZE} can be replaced with a small constant like @code{8}.

If looking for the size of a set, use @ref{17eb,,PySet_Size()} instead.


@ref{1a7,,Soft deprecated} since version 3.14.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Function Objects<2>,Other Objects,Container Objects,Concrete Objects Layer
@anchor{c-api/concrete function-objects}@anchor{5731}@anchor{c-api/concrete otherobjects}@anchor{5732}
@subsection Function Objects


@menu
* Function Objects: Function Objects<3>. 
* Instance Method Objects:: 
* Method Objects:: 
* Cell Objects:: 
* Code Objects:: 
* Code Object Flags:: 
* Extra information:: 

@end menu

@node Function Objects<3>,Instance Method Objects,,Function Objects<2>
@anchor{c-api/function doc}@anchor{5733}@anchor{c-api/function function-objects}@anchor{5734}@anchor{c-api/function id1}@anchor{5735}
@subsubsection Function Objects


@geindex object;function

There are a few functions specific to Python functions.

@geindex PyFunctionObject (C type)
@anchor{c-api/function c PyFunctionObject}@anchor{968}
@deffn {C Τύπος} type PyFunctionObject

The C structure used for functions.
@end deffn

@geindex PyFunction_Type (C var)
@anchor{c-api/function c PyFunction_Type}@anchor{5736}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyFunction_Type

@geindex MethodType (in module types)

This is an instance of @ref{e6b,,PyTypeObject} and represents the Python function
type.  It is exposed to Python programmers as @code{types.FunctionType}.
@end deffn

@geindex PyFunction_Check (C function)
@anchor{c-api/function c PyFunction_Check}@anchor{5737}
@deffn {C Συνάρτηση} int PyFunction_Check (PyObject *o)

Return true if `o' is a function object (has type @ref{5736,,PyFunction_Type}).
The parameter must not be @code{NULL}.  This function always succeeds.
@end deffn

@geindex PyFunction_New (C function)
@anchor{c-api/function c PyFunction_New}@anchor{5738}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_New (PyObject *code, PyObject *globals)
`Επιστρεφόμενη τιμή: New reference.'
Return a new function object associated with the code object `code'. `globals'
must be a dictionary with the global variables accessible to the function.

The function’s docstring and name are retrieved from the code object.
@ref{253b,,__module__}
is retrieved from `globals'. The argument defaults, annotations and closure are
set to @code{NULL}. @ref{253a,,__qualname__} is set to the same value as
the code object’s @ref{257a,,co_qualname} field.
@end deffn

@geindex PyFunction_NewWithQualName (C function)
@anchor{c-api/function c PyFunction_NewWithQualName}@anchor{5739}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_NewWithQualName (PyObject *code, PyObject *globals, PyObject *qualname)
`Επιστρεφόμενη τιμή: New reference.'
As @ref{5738,,PyFunction_New()}, but also allows setting the function object’s
@ref{253a,,__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{257a,,co_qualname} field.


Added in version 3.3.

@end deffn

@geindex PyFunction_GetCode (C function)
@anchor{c-api/function c PyFunction_GetCode}@anchor{573a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GetCode (PyObject *op)
`Επιστρεφόμενη τιμή: Borrowed reference.'
Return the code object associated with the function object `op'.
@end deffn

@geindex PyFunction_GetGlobals (C function)
@anchor{c-api/function c PyFunction_GetGlobals}@anchor{573b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GetGlobals (PyObject *op)
`Επιστρεφόμενη τιμή: Borrowed reference.'
Return the globals dictionary associated with the function object `op'.
@end deffn

@geindex PyFunction_GetModule (C function)
@anchor{c-api/function c PyFunction_GetModule}@anchor{573c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GetModule (PyObject *op)
`Επιστρεφόμενη τιμή: Borrowed reference.'
Return a @ref{603,,borrowed reference} to the @ref{253b,,__module__}
attribute of the @ref{79b,,function object} `op'.
It can be `NULL'.

This is normally a @ref{1df,,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{573d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GetDefaults (PyObject *op)
`Επιστρεφόμενη τιμή: Borrowed reference.'
Return the argument default values of the function object `op'. This can be a
tuple of arguments or @code{NULL}.
@end deffn

@geindex PyFunction_SetDefaults (C function)
@anchor{c-api/function c PyFunction_SetDefaults}@anchor{573e}
@deffn {C Συνάρτηση} int PyFunction_SetDefaults (PyObject *op, PyObject *defaults)

Set the argument default values for the function object `op'. `defaults' must be
@code{Py_None} or a tuple.

Raises @ref{3ea,,SystemError} and returns @code{-1} on failure.
@end deffn

@geindex PyFunction_SetVectorcall (C function)
@anchor{c-api/function c PyFunction_SetVectorcall}@anchor{967}
@deffn {C Συνάρτηση} 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!


Added in version 3.12.

@end deffn

@geindex PyFunction_GetKwDefaults (C function)
@anchor{c-api/function c PyFunction_GetKwDefaults}@anchor{573f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GetKwDefaults (PyObject *op)
`Επιστρεφόμενη τιμή: Borrowed reference.'
Return the keyword-only argument default values of the function object `op'. This can be a
dictionary of arguments or @code{NULL}.
@end deffn

@geindex PyFunction_SetKwDefaults (C function)
@anchor{c-api/function c PyFunction_SetKwDefaults}@anchor{5740}
@deffn {C Συνάρτηση} int PyFunction_SetKwDefaults (PyObject *op, PyObject *defaults)

Set the keyword-only argument default values of the function object `op'.
`defaults' must be a dictionary of keyword-only arguments or @code{Py_None}.

This function returns @code{0} on success, and returns @code{-1} with an exception
set on failure.
@end deffn

@geindex PyFunction_GetClosure (C function)
@anchor{c-api/function c PyFunction_GetClosure}@anchor{5741}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GetClosure (PyObject *op)
`Επιστρεφόμενη τιμή: Borrowed reference.'
Return the closure associated with the function object `op'. This can be @code{NULL}
or a tuple of cell objects.
@end deffn

@geindex PyFunction_SetClosure (C function)
@anchor{c-api/function c PyFunction_SetClosure}@anchor{5742}
@deffn {C Συνάρτηση} int PyFunction_SetClosure (PyObject *op, PyObject *closure)

Set the closure associated with the function object `op'. `closure' must be
@code{Py_None} or a tuple of cell objects.

Raises @ref{3ea,,SystemError} and returns @code{-1} on failure.
@end deffn

@geindex PyFunction_GetAnnotations (C function)
@anchor{c-api/function c PyFunction_GetAnnotations}@anchor{1d35}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GetAnnotations (PyObject *op)
`Επιστρεφόμενη τιμή: Borrowed reference.'
Return the annotations of the function object `op'. This can be a
mutable dictionary or @code{NULL}.
@end deffn

@geindex PyFunction_SetAnnotations (C function)
@anchor{c-api/function c PyFunction_SetAnnotations}@anchor{5743}
@deffn {C Συνάρτηση} int PyFunction_SetAnnotations (PyObject *op, PyObject *annotations)

Set the annotations for the function object `op'. `annotations'
must be a dictionary or @code{Py_None}.

Raises @ref{3ea,,SystemError} and returns @code{-1} on failure.
@end deffn

@geindex PyFunction_GET_CODE (C function)
@geindex PyFunction_GET_GLOBALS (C function)
@geindex PyFunction_GET_MODULE (C function)
@geindex PyFunction_GET_DEFAULTS (C function)
@geindex PyFunction_GET_KW_DEFAULTS (C function)
@geindex PyFunction_GET_CLOSURE (C function)
@geindex PyFunction_GET_ANNOTATIONS (C function)
@anchor{c-api/function c PyFunction_GET_CODE}@anchor{5744}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GET_CODE (PyObject *op)
@anchor{c-api/function c PyFunction_GET_GLOBALS}@anchor{5745}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GET_GLOBALS (PyObject *op)
@anchor{c-api/function c PyFunction_GET_MODULE}@anchor{5746}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GET_MODULE (PyObject *op)
@anchor{c-api/function c PyFunction_GET_DEFAULTS}@anchor{5747}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GET_DEFAULTS (PyObject *op)
@anchor{c-api/function c PyFunction_GET_KW_DEFAULTS}@anchor{5748}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GET_KW_DEFAULTS (PyObject *op)
@anchor{c-api/function c PyFunction_GET_CLOSURE}@anchor{5749}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GET_CLOSURE (PyObject *op)
@anchor{c-api/function c PyFunction_GET_ANNOTATIONS}@anchor{574a}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyFunction_GET_ANNOTATIONS (PyObject *op)
`Επιστρεφόμενη τιμή: Borrowed reference.'
These functions are similar to their @code{PyFunction_Get*} counterparts, but
do not do type checking. Passing anything other than an instance of
@ref{5736,,PyFunction_Type} is undefined behavior.
@end deffn

@geindex PyFunction_AddWatcher (C function)
@anchor{c-api/function c PyFunction_AddWatcher}@anchor{574b}
@deffn {C Συνάρτηση} 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{574c,,PyFunction_ClearWatcher()}.
In case of error (e.g. no more watcher IDs available),
return @code{-1} and set an exception.


Added in version 3.12.

@end deffn

@geindex PyFunction_ClearWatcher (C function)
@anchor{c-api/function c PyFunction_ClearWatcher}@anchor{574c}
@deffn {C Συνάρτηση} int PyFunction_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' previously returned from
@ref{574b,,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.)


Added in version 3.12.

@end deffn

@geindex PyFunction_WatchEvent (C type)
@anchor{c-api/function c PyFunction_WatchEvent}@anchor{574d}
@deffn {C Τύπος} type PyFunction_WatchEvent

@quotation

Enumeration of possible function watcher events:


@itemize -

@item 
@code{PyFunction_EVENT_CREATE}

@item 
@code{PyFunction_EVENT_DESTROY}

@item 
@code{PyFunction_EVENT_MODIFY_CODE}

@item 
@code{PyFunction_EVENT_MODIFY_DEFAULTS}

@item 
@code{PyFunction_EVENT_MODIFY_KWDEFAULTS}
@end itemize
@end quotation


Added in version 3.12: 


@itemize -

@item 
@code{PyFunction_PYFUNC_EVENT_MODIFY_QUALNAME}
@end itemize



Added in version 3.15.

@end deffn

@geindex PyFunction_WatchCallback (C type)
@anchor{c-api/function c PyFunction_WatchCallback}@anchor{574e}
@deffn {C Τύπος} typedef int (*PyFunction_WatchCallback)(@ref{574d,,PyFunction_WatchEvent} event, @ref{968,,PyFunctionObject} *func, @ref{19b,,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{603,,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 `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{7e8,,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.


Added in version 3.12.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Instance Method Objects,Method Objects,Function Objects<3>,Function Objects<2>
@anchor{c-api/method doc}@anchor{574f}@anchor{c-api/method instance-method-objects}@anchor{5750}@anchor{c-api/method instancemethod-objects}@anchor{5751}@anchor{c-api/method translation-repo}@anchor{5752}
@subsubsection Instance Method Objects


@geindex object;instancemethod

An instance method is a wrapper for a @ref{181a,,PyCFunction} and the new way
to bind a @code{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{5753}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyInstanceMethod_Type

This instance of @ref{e6b,,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{5754}
@deffn {C Συνάρτηση} int PyInstanceMethod_Check (PyObject *o)

Return true if `o' is an instance method object (has type
@ref{5753,,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{5755}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyInstanceMethod_New (PyObject *func)
`Επιστρεφόμενη τιμή: New reference.'
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{5756}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyInstanceMethod_Function (PyObject *im)
`Επιστρεφόμενη τιμή: Borrowed reference.'
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{5757}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyInstanceMethod_GET_FUNCTION (PyObject *im)
`Επιστρεφόμενη τιμή: Borrowed reference.'
Macro version of @ref{5756,,PyInstanceMethod_Function()} which avoids error checking.
@end deffn

@node Method Objects,Cell Objects,Instance Method Objects,Function Objects<2>
@anchor{c-api/method id1}@anchor{5758}@anchor{c-api/method method-objects}@anchor{5759}
@subsubsection Method Objects


@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{575a}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyMethod_Type

@geindex MethodType (in module types)

This instance of @ref{e6b,,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{575b}
@deffn {C Συνάρτηση} int PyMethod_Check (PyObject *o)

Return true if `o' is a method object (has type @ref{575a,,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{575c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMethod_New (PyObject *func, PyObject *self)
`Επιστρεφόμενη τιμή: New reference.'
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{575d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMethod_Function (PyObject *meth)
`Επιστρεφόμενη τιμή: Borrowed reference.'
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{575e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMethod_GET_FUNCTION (PyObject *meth)
`Επιστρεφόμενη τιμή: Borrowed reference.'
Macro version of @ref{575d,,PyMethod_Function()} which avoids error checking.
@end deffn

@geindex PyMethod_Self (C function)
@anchor{c-api/method c PyMethod_Self}@anchor{575f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMethod_Self (PyObject *meth)
`Επιστρεφόμενη τιμή: Borrowed reference.'
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{5760}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMethod_GET_SELF (PyObject *meth)
`Επιστρεφόμενη τιμή: Borrowed reference.'
Macro version of @ref{575f,,PyMethod_Self()} which avoids error checking.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Cell Objects,Code Objects,Method Objects,Function Objects<2>
@anchor{c-api/cell doc}@anchor{5761}@anchor{c-api/cell cell-objects}@anchor{aee}@anchor{c-api/cell id1}@anchor{5762}@anchor{c-api/cell translation-repo}@anchor{5763}
@subsubsection Cell Objects


«Cell» objects are used to implement variables referenced by multiple scopes.
For each such variable, a cell object is created to store the value; the local
variables of each stack frame that references the value contain a reference to
the cells from outer scopes which also use that variable.  When the value is
accessed, the value contained in the cell is used instead of the cell object
itself.  This de-referencing of the cell object requires support from the
generated byte-code; these are not automatically de-referenced when accessed.
Cell objects are not likely to be useful elsewhere.

@geindex PyCellObject (C type)
@anchor{c-api/cell c PyCellObject}@anchor{5764}
@deffn {C Τύπος} type PyCellObject

The C structure used for cell objects.
@end deffn

@geindex PyCell_Type (C var)
@anchor{c-api/cell c PyCell_Type}@anchor{5765}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyCell_Type

The type object corresponding to cell objects.
@end deffn

@geindex PyCell_Check (C function)
@anchor{c-api/cell c PyCell_Check}@anchor{5766}
@deffn {C Συνάρτηση} 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{5767}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCell_New (PyObject *ob)
`Επιστρεφόμενη τιμή: New reference.'
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{5768}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCell_Get (PyObject *cell)
`Επιστρεφόμενη τιμή: New reference.'
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{5769}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCell_GET (PyObject *cell)
`Επιστρεφόμενη τιμή: Borrowed reference.'
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{576a}
@deffn {C Συνάρτηση} 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{c81}
@deffn {C Συνάρτηση} 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@geindex object;code
@geindex code object

@node Code Objects,Code Object Flags,Cell Objects,Function Objects<2>
@anchor{c-api/code doc}@anchor{576b}@anchor{c-api/code code-objects}@anchor{576c}@anchor{c-api/code codeobjects}@anchor{9b4}@anchor{c-api/code translation-repo}@anchor{576d}
@subsubsection Code Objects


Code objects are a low-level detail of the CPython implementation.
Each one represents a chunk of executable code that hasn’t yet been
bound into a function.

@geindex PyCodeObject (C type)
@anchor{c-api/code c PyCodeObject}@anchor{b59}
@deffn {C Τύπος} type PyCodeObject

The C structure of the objects used to describe code objects.  The
fields of this type are subject to change at any time.
@end deffn

@geindex PyCode_Type (C var)
@anchor{c-api/code c PyCode_Type}@anchor{576e}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyCode_Type

This is an instance of @ref{e6b,,PyTypeObject} representing the Python
@ref{6eb,,code object}.
@end deffn

@geindex PyCode_Check (C function)
@anchor{c-api/code c PyCode_Check}@anchor{576f}
@deffn {C Συνάρτηση} int PyCode_Check (PyObject *co)

Return true if `co' is a @ref{6eb,,code object}.
This function always succeeds.
@end deffn

@geindex PyCode_GetNumFree (C function)
@anchor{c-api/code c PyCode_GetNumFree}@anchor{5770}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyCode_GetNumFree (PyCodeObject *co)

Return the number of @ref{1ab7,,free (closure) variables}
in a code object.
@end deffn

@geindex PyUnstable_Code_GetFirstFree (C function)
@anchor{c-api/code c PyUnstable_Code_GetFirstFree}@anchor{81b}
@deffn {C Συνάρτηση} int PyUnstable_Code_GetFirstFree (PyCodeObject *co)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Return the position of the first @ref{1ab7,,free (closure) variable}
in a code object.


Άλλαξε στην έκδοση 3.13: Renamed from @code{PyCode_GetFirstFree} as part of @ref{954,,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{5771}
@deffn {C Συνάρτηση} @ref{b59,,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 Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Return a new code object.  If you need a dummy code object to create a frame,
use @ref{16f5,,PyCode_NewEmpty()} instead.

Since the definition of the bytecode changes often, calling
@ref{5771,,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.


Άλλαξε στην έκδοση 3.11: Added @code{qualname} and @code{exceptiontable} parameters.


@geindex PyCode_New (C function)


Άλλαξε στην έκδοση 3.12: Renamed from @code{PyCode_New} as part of @ref{954,,Unstable C API}.
The old name is deprecated, but will remain available until the
signature changes again.

@end deffn

@geindex PyCode_NewWithPosOnlyArgs (C function)

@geindex PyUnstable_Code_NewWithPosOnlyArgs (C function)
@anchor{c-api/code c PyCode_NewWithPosOnlyArgs}@anchor{5772}@anchor{c-api/code c PyUnstable_Code_NewWithPosOnlyArgs}@anchor{5773}
@deffn {C Συνάρτηση} @ref{b59,,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 Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Similar to @ref{5771,,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.


Added in version 3.8: as @code{PyCode_NewWithPosOnlyArgs}



Άλλαξε στην έκδοση 3.11: Added @code{qualname} and  @code{exceptiontable} parameters.



Άλλαξε στην έκδοση 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{16f5}
@deffn {C Συνάρτηση} @ref{b59,,PyCodeObject} *PyCode_NewEmpty (const char *filename, const char *funcname, int firstlineno)
`Επιστρεφόμενη τιμή: New reference.'
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{c5f}
@deffn {C Συνάρτηση} 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{b6a,,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{9b3}
@deffn {C Συνάρτηση} 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.


Added in version 3.11.

@end deffn

@geindex PyCode_GetCode (C function)
@anchor{c-api/code c PyCode_GetCode}@anchor{b5a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCode_GetCode (PyCodeObject *co)

Equivalent to the Python code @code{getattr(co, 'co_code')}.
Returns a strong reference to a @ref{b71,,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.


Added in version 3.11.

@end deffn

@geindex PyCode_GetVarnames (C function)
@anchor{c-api/code c PyCode_GetVarnames}@anchor{b5b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCode_GetVarnames (PyCodeObject *co)

Equivalent to the Python code @code{getattr(co, 'co_varnames')}.
Returns a new reference to a @ref{5580,,PyTupleObject} containing the names of
the local variables. On error, @code{NULL} is returned and an exception
is raised.


Added in version 3.11.

@end deffn

@geindex PyCode_GetCellvars (C function)
@anchor{c-api/code c PyCode_GetCellvars}@anchor{b5c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCode_GetCellvars (PyCodeObject *co)

Equivalent to the Python code @code{getattr(co, 'co_cellvars')}.
Returns a new reference to a @ref{5580,,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.


Added in version 3.11.

@end deffn

@geindex PyCode_GetFreevars (C function)
@anchor{c-api/code c PyCode_GetFreevars}@anchor{b5d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCode_GetFreevars (PyCodeObject *co)

Equivalent to the Python code @code{getattr(co, 'co_freevars')}.
Returns a new reference to a @ref{5580,,PyTupleObject} containing the names of
the @ref{1ab7,,free (closure) variables}. On error, @code{NULL} is returned
and an exception is raised.


Added in version 3.11.

@end deffn

@geindex PyCode_AddWatcher (C function)
@anchor{c-api/code c PyCode_AddWatcher}@anchor{96c}
@deffn {C Συνάρτηση} 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{96d,,PyCode_ClearWatcher()}.
In case of error (e.g. no more watcher IDs available),
return @code{-1} and set an exception.


Added in version 3.12.

@end deffn

@geindex PyCode_ClearWatcher (C function)
@anchor{c-api/code c PyCode_ClearWatcher}@anchor{96d}
@deffn {C Συνάρτηση} int PyCode_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' previously returned from
@ref{96c,,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.)


Added in version 3.12.

@end deffn

@geindex PyCodeEvent (C type)
@anchor{c-api/code c PyCodeEvent}@anchor{5774}
@deffn {C Τύπος} type PyCodeEvent

Enumeration of possible code object watcher events:
- @code{PY_CODE_EVENT_CREATE}
- @code{PY_CODE_EVENT_DESTROY}


Added in version 3.12.

@end deffn

@geindex PyCode_WatchCallback (C type)
@anchor{c-api/code c PyCode_WatchCallback}@anchor{5775}
@deffn {C Τύπος} typedef int (*PyCode_WatchCallback)(@ref{5774,,PyCodeEvent} event, @ref{b59,,PyCodeObject} *co)

Type of a code object watcher callback function.

If `event' is @code{PY_CODE_EVENT_CREATE}, then the callback is invoked
after `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{7e8,,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.


Added in version 3.12.

@end deffn

@geindex PyCode_Optimize (C function)
@anchor{c-api/code c PyCode_Optimize}@anchor{5776}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCode_Optimize (PyObject *code, PyObject *consts, PyObject *names, PyObject *lnotab_obj)

This is a function that does nothing.

Prior to Python 3.10, this function would perform basic optimizations to a
code object.


Άλλαξε στην έκδοση 3.10: This function now does nothing.



@ref{1a7,,Soft deprecated} since version 3.13.

@end deffn

@node Code Object Flags,Extra information,Code Objects,Function Objects<2>
@anchor{c-api/code c-codeobject-flags}@anchor{552a}@anchor{c-api/code code-object-flags}@anchor{5777}
@subsubsection Code Object Flags


Code objects contain a bit-field of flags, which can be retrieved as the
@ref{1afc,,co_flags} Python attribute (for example using
@ref{7e6,,PyObject_GetAttrString()}), and set using a `flags' argument to
@ref{5771,,PyUnstable_Code_New()} and similar functions.

Flags whose names start with @code{CO_FUTURE_} correspond to features normally
selectable by @ref{670,,future statements}. These flags can be used in
@ref{5523,,PyCompilerFlags.cf_flags}.
Note that many @code{CO_FUTURE_} flags are mandatory in current versions of
Python, and setting them has no effect.

The following flags are available.
For their meaning, see the linked documentation of their Python equivalents.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Flag

@tab

Meaning

@item

@geindex CO_OPTIMIZED (C macro)
@anchor{c-api/code c CO_OPTIMIZED}@anchor{5778}
@deffn {C Μακροεντολή} CO_OPTIMIZED
@end deffn

@tab

@ref{4d30,,inspect.CO_OPTIMIZED}

@item

@geindex CO_NEWLOCALS (C macro)
@anchor{c-api/code c CO_NEWLOCALS}@anchor{5779}
@deffn {C Μακροεντολή} CO_NEWLOCALS
@end deffn

@tab

@ref{4d31,,inspect.CO_NEWLOCALS}

@item

@geindex CO_VARARGS (C macro)
@anchor{c-api/code c CO_VARARGS}@anchor{577a}
@deffn {C Μακροεντολή} CO_VARARGS
@end deffn

@tab

@ref{4d32,,inspect.CO_VARARGS}

@item

@geindex CO_VARKEYWORDS (C macro)
@anchor{c-api/code c CO_VARKEYWORDS}@anchor{577b}
@deffn {C Μακροεντολή} CO_VARKEYWORDS
@end deffn

@tab

@ref{4d33,,inspect.CO_VARKEYWORDS}

@item

@geindex CO_NESTED (C macro)
@anchor{c-api/code c CO_NESTED}@anchor{577c}
@deffn {C Μακροεντολή} CO_NESTED
@end deffn

@tab

@ref{4d34,,inspect.CO_NESTED}

@item

@geindex CO_GENERATOR (C macro)
@anchor{c-api/code c CO_GENERATOR}@anchor{577d}
@deffn {C Μακροεντολή} CO_GENERATOR
@end deffn

@tab

@ref{4d35,,inspect.CO_GENERATOR}

@item

@geindex CO_COROUTINE (C macro)
@anchor{c-api/code c CO_COROUTINE}@anchor{577e}
@deffn {C Μακροεντολή} CO_COROUTINE
@end deffn

@tab

@ref{4d36,,inspect.CO_COROUTINE}

@item

@geindex CO_ITERABLE_COROUTINE (C macro)
@anchor{c-api/code c CO_ITERABLE_COROUTINE}@anchor{577f}
@deffn {C Μακροεντολή} CO_ITERABLE_COROUTINE
@end deffn

@tab

@ref{4d37,,inspect.CO_ITERABLE_COROUTINE}

@item

@geindex CO_ASYNC_GENERATOR (C macro)
@anchor{c-api/code c CO_ASYNC_GENERATOR}@anchor{5780}
@deffn {C Μακροεντολή} CO_ASYNC_GENERATOR
@end deffn

@tab

@ref{4d38,,inspect.CO_ASYNC_GENERATOR}

@item

@geindex CO_HAS_DOCSTRING (C macro)
@anchor{c-api/code c CO_HAS_DOCSTRING}@anchor{5781}
@deffn {C Μακροεντολή} CO_HAS_DOCSTRING
@end deffn

@tab

@ref{2588,,inspect.CO_HAS_DOCSTRING}

@item

@geindex CO_METHOD (C macro)
@anchor{c-api/code c CO_METHOD}@anchor{5782}
@deffn {C Μακροεντολή} CO_METHOD
@end deffn

@tab

@ref{4d39,,inspect.CO_METHOD}

@item

@geindex CO_FUTURE_DIVISION (C macro)
@anchor{c-api/code c CO_FUTURE_DIVISION}@anchor{5783}
@deffn {C Μακροεντολή} CO_FUTURE_DIVISION
@end deffn

@tab

no effect (@ref{4cde,,__future__.division})

@item

@geindex CO_FUTURE_ABSOLUTE_IMPORT (C macro)
@anchor{c-api/code c CO_FUTURE_ABSOLUTE_IMPORT}@anchor{5784}
@deffn {C Μακροεντολή} CO_FUTURE_ABSOLUTE_IMPORT
@end deffn

@tab

no effect (@ref{4cdf,,__future__.absolute_import})

@item

@geindex CO_FUTURE_WITH_STATEMENT (C macro)
@anchor{c-api/code c CO_FUTURE_WITH_STATEMENT}@anchor{5785}
@deffn {C Μακροεντολή} CO_FUTURE_WITH_STATEMENT
@end deffn

@tab

no effect (@ref{4ce0,,__future__.with_statement})

@item

@geindex CO_FUTURE_PRINT_FUNCTION (C macro)
@anchor{c-api/code c CO_FUTURE_PRINT_FUNCTION}@anchor{5786}
@deffn {C Μακροεντολή} CO_FUTURE_PRINT_FUNCTION
@end deffn

@tab

no effect (@ref{4ce1,,__future__.print_function})

@item

@geindex CO_FUTURE_UNICODE_LITERALS (C macro)
@anchor{c-api/code c CO_FUTURE_UNICODE_LITERALS}@anchor{5787}
@deffn {C Μακροεντολή} CO_FUTURE_UNICODE_LITERALS
@end deffn

@tab

no effect (@ref{4ce2,,__future__.unicode_literals})

@item

@geindex CO_FUTURE_GENERATOR_STOP (C macro)
@anchor{c-api/code c CO_FUTURE_GENERATOR_STOP}@anchor{5788}
@deffn {C Μακροεντολή} CO_FUTURE_GENERATOR_STOP
@end deffn

@tab

no effect (@ref{4ce3,,__future__.generator_stop})

@item

@geindex CO_FUTURE_ANNOTATIONS (C macro)
@anchor{c-api/code c CO_FUTURE_ANNOTATIONS}@anchor{5529}
@deffn {C Μακροεντολή} CO_FUTURE_ANNOTATIONS
@end deffn

@tab

@ref{4ce4,,__future__.annotations}

@end multitable


@node Extra information,,Code Object Flags,Function Objects<2>
@anchor{c-api/code extra-information}@anchor{5789}
@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 _PyEval_RequestCodeExtraIndex (C function)

@geindex PyUnstable_Eval_RequestCodeExtraIndex (C function)
@anchor{c-api/code c _PyEval_RequestCodeExtraIndex}@anchor{578a}@anchor{c-api/code c PyUnstable_Eval_RequestCodeExtraIndex}@anchor{1959}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyUnstable_Eval_RequestCodeExtraIndex (freefunc free)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Return a new 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{546c,,Py_DecRef()} when storing @ref{19b,,PyObject}.


Added in version 3.6: as @code{_PyEval_RequestCodeExtraIndex}



Άλλαξε στην έκδοση 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 _PyCode_GetExtra (C function)

@geindex PyUnstable_Code_GetExtra (C function)
@anchor{c-api/code c _PyCode_GetExtra}@anchor{578b}@anchor{c-api/code c PyUnstable_Code_GetExtra}@anchor{1958}
@deffn {C Συνάρτηση} int PyUnstable_Code_GetExtra (PyObject *code, Py_ssize_t index, void **extra)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@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.


Added in version 3.6: as @code{_PyCode_GetExtra}



Άλλαξε στην έκδοση 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 _PyCode_SetExtra (C function)

@geindex PyUnstable_Code_SetExtra (C function)
@anchor{c-api/code c _PyCode_SetExtra}@anchor{578c}@anchor{c-api/code c PyUnstable_Code_SetExtra}@anchor{1957}
@deffn {C Συνάρτηση} int PyUnstable_Code_SetExtra (PyObject *code, Py_ssize_t index, void *extra)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@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.


Added in version 3.6: as @code{_PyCode_SetExtra}



Άλλαξε στην έκδοση 3.12: Renamed to @code{PyUnstable_Code_SetExtra}.
The old private name is deprecated, but will be available until the API
changes.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Other Objects,C API for extension modules,Function Objects<2>,Concrete Objects Layer
@anchor{c-api/concrete other-objects}@anchor{578d}
@subsection Other Objects


@menu
* File objects:: 
* Module Objects:: 
* Iterator Objects:: 
* Descriptor Objects:: 
* Slice Objects:: 
* MemoryView objects:: 
* Pickle buffer objects:: 
* Weak Reference Objects: Weak Reference Objects<2>. 
* Capsules: Capsules<2>. 
* Sentinel objects:: 
* Frame objects:: 
* Generator Objects:: 
* Coroutine Objects:: 
* Context Variables Objects:: 
* Objects for Type Hinting:: 

@end menu

@node File objects,Module Objects,,Other Objects
@anchor{c-api/file doc}@anchor{578e}@anchor{c-api/file file-objects}@anchor{578f}@anchor{c-api/file fileobjects}@anchor{5790}
@subsubsection File objects


@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{82,,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 @code{io} APIs instead.

@geindex PyFile_FromFd (C function)
@anchor{c-api/file c PyFile_FromFd}@anchor{534e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFile_FromFd (int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{92b,,io.open()} function documentation.

@cartouche
@quotation Προειδοποίηση 
Since Python streams have their own buffering layer, mixing them with
OS-level file descriptors can produce various issues (such as unexpected
ordering of data).
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.2: Ignore `name' attribute.

@end deffn

@geindex PyObject_AsFileDescriptor (C function)
@anchor{c-api/file c PyObject_AsFileDescriptor}@anchor{53bf}
@deffn {C Συνάρτηση} int PyObject_AsFileDescriptor (PyObject *p)
` Μέρος του @ref{95c,,Σταθερό 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{19b2,,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{534f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFile_GetLine (PyObject *p, int n)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex EOFError (built-in exception)

Equivalent to @code{p.readline([n])}, this function reads one line from the
object `p'.  `p' may be a file object or any object with a
@ref{16ce,,readline()}
method.  If `n' is @code{0}, exactly one line is read, regardless of the length of
the line.  If `n' is greater than @code{0}, no more than `n' bytes will be read
from the file; a partial line can be returned.  In both cases, an empty string
is returned if the end of the file is reached immediately.  If `n' is less than
@code{0}, however, one line is read regardless of length, but @ref{167e,,EOFError} is
raised if the end of the file is reached immediately.
@end deffn

@geindex PyFile_SetOpenCodeHook (C function)
@anchor{c-api/file c PyFile_SetOpenCodeHook}@anchor{1c9e}
@deffn {C Συνάρτηση} int PyFile_SetOpenCodeHook (Py_OpenCodeHookFunction handler)

Overrides the normal behavior of @ref{1943,,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{5791}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*Py_OpenCodeHookFunction)(@ref{19b,,PyObject}*, void*)

Equivalent of @ref{19b,,PyObject} *(*)(PyObject *path, void *userData), where `path' is guaranteed to be
@ref{b73,,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{1c9e,,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{673,,Py_Initialize()}.

Raises an @ref{1e65,,auditing event} @code{setopencodehook} with no arguments.


Added in version 3.8.

@end deffn

@geindex PyFile_OpenCodeObject (C function)
@anchor{c-api/file c PyFile_OpenCodeObject}@anchor{5792}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFile_OpenCodeObject (PyObject *path)

Open `path' with the mode @code{'rb'}. `path' must be a Python @ref{1df,,str}
object. The behavior of this function may be overridden by
@ref{1c9e,,PyFile_SetOpenCodeHook()} to allow for some preprocessing of the
text.

This is analogous to @ref{1943,,io.open_code()} in Python.

On success, this function returns a @ref{7da,,strong reference} to a Python
file object. On failure, this function returns @code{NULL} with an exception
set.


Added in version 3.8.

@end deffn

@geindex PyFile_OpenCode (C function)
@anchor{c-api/file c PyFile_OpenCode}@anchor{5793}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFile_OpenCode (const char *path)

Similar to @ref{5792,,PyFile_OpenCodeObject()}, but `path' is a
UTF-8 encoded const char*.


Added in version 3.8.

@end deffn

@geindex PyFile_WriteObject (C function)
@anchor{c-api/file c PyFile_WriteObject}@anchor{5350}
@deffn {C Συνάρτηση} int PyFile_WriteObject (PyObject *obj, PyObject *p, int flags)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex Py_PRINT_RAW (C macro)

Write object `obj' to file object `p'.  The only supported flag for `flags' is
@ref{55e9,,Py_PRINT_RAW}; if given, the @ref{1df,,str()} of the object is written
instead of the @ref{45b,,repr()}.

If `obj' is @code{NULL}, write the string @code{"<NULL>"}.

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{5351}
@deffn {C Συνάρτηση} int PyFile_WriteString (const char *s, PyObject *p)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Write string `s' to file object `p'.  Return @code{0} on success or @code{-1} on
failure; the appropriate exception will be set.
@end deffn

@menu
* Soft-deprecated API: Soft-deprecated API<2>. 

@end menu

@node Soft-deprecated API<2>,,,File objects
@anchor{c-api/file soft-deprecated-api}@anchor{5794}
@subsubsection Soft-deprecated API



@ref{1a7,,Soft deprecated} since version 3.15.


These are APIs that were included in Python’s C API
by mistake. They are documented solely for completeness; use other
@code{PyFile*} APIs instead.

@geindex PyFile_NewStdPrinter (C function)
@anchor{c-api/file c PyFile_NewStdPrinter}@anchor{5795}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFile_NewStdPrinter (int fd)

Use @ref{534e,,PyFile_FromFd()} with defaults (@code{fd, NULL, "w", -1, NULL, NULL, NULL, 0}) instead.
@end deffn

@geindex PyStdPrinter_Type (C var)
@anchor{c-api/file c PyStdPrinter_Type}@anchor{5796}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyStdPrinter_Type

Type of file-like objects used internally at Python startup when @ref{82,,io} is
not yet available.
Use Python @ref{32b,,open()} or @ref{534e,,PyFile_FromFd()} to create file objects instead.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Module Objects,Iterator Objects,File objects,Other Objects
@anchor{c-api/module doc}@anchor{5797}@anchor{c-api/module module-objects}@anchor{5798}@anchor{c-api/module moduleobjects}@anchor{5566}@anchor{c-api/module translation-repo}@anchor{5799}
@subsubsection Module Objects


@geindex object;module

@geindex PyModule_Type (C var)
@anchor{c-api/module c PyModule_Type}@anchor{539b}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyModule_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex ModuleType (in module types)

This instance of @ref{e6b,,PyTypeObject} represents the Python module type.  This
is exposed to Python programs as @ref{11c7,,types.ModuleType}.
@end deffn

@geindex PyModule_Check (C function)
@anchor{c-api/module c PyModule_Check}@anchor{579a}
@deffn {C Συνάρτηση} 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{579b}
@deffn {C Συνάρτηση} int PyModule_CheckExact (PyObject *p)

Return true if `p' is a module object, but not a subtype of
@ref{539b,,PyModule_Type}.  This function always succeeds.
@end deffn

@geindex PyModule_NewObject (C function)
@anchor{c-api/module c PyModule_NewObject}@anchor{5399}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyModule_NewObject (PyObject *name)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{172f,,module.__name__} set to `name'.
The module’s @code{__name__}, @ref{1de7,,__doc__},
@ref{58c,,__package__} and @ref{2ff,,__loader__} attributes are
filled in (all but @code{__name__} are set to @code{None}). The caller is
responsible for setting a @ref{255a,,__file__} attribute.

Return @code{NULL} with an exception set on error.


Added in version 3.3.



Άλλαξε στην έκδοση 3.4: @ref{58c,,__package__} and @ref{2ff,,__loader__} are now set to
@code{None}.

@end deffn

@geindex PyModule_New (C function)
@anchor{c-api/module c PyModule_New}@anchor{5398}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyModule_New (const char *name)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{5399,,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{5393}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyModule_GetDict (PyObject *module)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex __dict__ (module attribute)

Return the dictionary object that implements `module'’s namespace; this object
is the same as the @ref{1bf,,__dict__} attribute of the module object.
If `module' is not a module object (or a subtype of a module object),
@ref{3ea,,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{1bf,,__dict__}.

The returned reference is borrowed from the module; it is valid until
the module is destroyed.
@end deffn

@geindex PyModule_GetNameObject (C function)
@anchor{c-api/module c PyModule_GetNameObject}@anchor{5395}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyModule_GetNameObject (PyObject *module)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
@geindex __name__ (module attribute)
@geindex SystemError (built-in exception)

Return `module'’s @ref{172f,,__name__} value.  If the module does not
provide one, or if it is not a string, @ref{3ea,,SystemError} is raised and
@code{NULL} is returned.


Added in version 3.3.

@end deffn

@geindex PyModule_GetName (C function)
@anchor{c-api/module c PyModule_GetName}@anchor{5394}
@deffn {C Συνάρτηση} const char *PyModule_GetName (PyObject *module)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{5395,,PyModule_GetNameObject()} but return the name encoded to
@code{'utf-8'}.

The returned buffer is only valid until the module is renamed or destroyed.
Note that Python code may rename a module by setting its @ref{172f,,__name__}
attribute.
@end deffn

@geindex PyModule_GetDef (C function)
@anchor{c-api/module c PyModule_GetDef}@anchor{5392}
@deffn {C Συνάρτηση} @ref{d45,,PyModuleDef} *PyModule_GetDef (PyObject *module)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a pointer to the @ref{d45,,PyModuleDef} struct from which the module was
created, or @code{NULL} if the module wasn’t created from a definition.

On error, return @code{NULL} with an exception set.
Use @ref{1ea5,,PyErr_Occurred()} to tell this case apart from a missing
@code{PyModuleDef}.
@end deffn

@geindex PyModule_GetFilenameObject (C function)
@anchor{c-api/module c PyModule_GetFilenameObject}@anchor{641}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyModule_GetFilenameObject (PyObject *module)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{255a,,__file__} attribute.  If this is not defined, or if it is not a
string, raise @ref{3ea,,SystemError} and return @code{NULL}; otherwise return
a reference to a Unicode object.


Added in version 3.2.

@end deffn

@geindex PyModule_GetFilename (C function)
@anchor{c-api/module c PyModule_GetFilename}@anchor{640}
@deffn {C Συνάρτηση} const char *PyModule_GetFilename (PyObject *module)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{641,,PyModule_GetFilenameObject()} but return the filename
encoded to “utf-8”.

The returned buffer is only valid until the module’s @ref{255a,,__file__} attribute
is reassigned or the module is destroyed.


Αποσύρθηκε στην έκδοση 3.2: @ref{640,,PyModule_GetFilename()} raises @ref{a67,,UnicodeEncodeError} on
unencodable filenames, use @ref{641,,PyModule_GetFilenameObject()} instead.

@end deffn
@anchor{c-api/module c-module-slots}@anchor{556a}
@menu
* Module definition:: 
* Module state:: 
* Creating extension modules dynamically:: 
* Module definition struct:: 
* Support functions:: 

@end menu

@node Module definition,Module state,,Module Objects
@anchor{c-api/module module-definition}@anchor{579c}@anchor{c-api/module pymoduledef-slot}@anchor{579d}
@subsubsection Module definition


Modules created using the C API are typically defined using an
array of @ref{19d,,PySlot} structs, which provides a «description» of how a
module should be created.
See @ref{375,,Definition slots} for more information on slots in general.


Άλλαξε στην έκδοση 3.15: Previously, a @ref{d45,,PyModuleDef} struct was necessary to define modules.
The older way of defining modules is still available: consult either the
@ref{579e,,Module definition struct} section or earlier versions of this documentation
if you plan to support earlier Python versions.


The slots array is usually used to define an extension module’s “main”
module object (see @ref{5212,,Defining extension modules} for details).
It can also be used to
@ref{579f,,create extension modules dynamically}.

Unless specified otherwise, the same slot ID may not be repeated
in an array of slots.

@menu
* Metadata slots:: 
* Feature slots:: 
* Creation and initialization slots:: 

@end menu

@node Metadata slots,Feature slots,,Module definition
@anchor{c-api/module metadata-slots}@anchor{57a0}
@subsubsection Metadata slots


@geindex Py_mod_name (C macro)
@anchor{c-api/module c Py_mod_name}@anchor{51a0}
@deffn {C Μακροεντολή} Py_mod_name
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for the name of the new module,
as a NUL-terminated UTF8-encoded @code{const char *}.

Note that modules are typically created using a
@ref{245d,,ModuleSpec}, and when they are, the
name from the spec will be used instead of @code{Py_mod_name}.
However, it is still recommended to include this slot for introspection
and debugging purposes.


Added in version 3.15: Use @ref{57a1,,PyModuleDef.m_name} instead to support previous versions.

@end deffn

@geindex Py_mod_doc (C macro)
@anchor{c-api/module c Py_mod_doc}@anchor{51a1}
@deffn {C Μακροεντολή} Py_mod_doc
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for the docstring of the new
module, as a NUL-terminated UTF8-encoded @code{const char *}.

Usually it is set to a variable created with @ref{1f4f,,PyDoc_STRVAR}.


Added in version 3.15: Use @ref{57a2,,PyModuleDef.m_doc} instead to support previous versions.

@end deffn

@node Feature slots,Creation and initialization slots,Metadata slots,Module definition
@anchor{c-api/module feature-slots}@anchor{57a3}
@subsubsection Feature slots


@geindex Py_mod_abi (C macro)
@anchor{c-api/module c Py_mod_abi}@anchor{358}
@deffn {C Μακροεντολή} Py_mod_abi
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} whose value points to
a @ref{527a,,PyABIInfo} structure describing the ABI that
the extension is using.

A suitable @code{PyABIInfo} variable can be defined using the
@ref{35a,,PyABIInfo_VAR} macro, as in:

@example
PyABIInfo_VAR(abi_info);

static PySlot mymodule_slots[] = @{
   PySlot_DATA(Py_mod_abi, &abi_info),
   ...
@};
@end example

When creating a module, Python checks the value of this slot
using @ref{359,,PyABIInfo_Check()}.

This slot is required, except for modules created from
@ref{d45,,PyModuleDef}.


Added in version 3.15.

@end deffn

@geindex Py_mod_multiple_interpreters (C macro)
@anchor{c-api/module c Py_mod_multiple_interpreters}@anchor{5496}
@deffn {C Μακροεντολή} Py_mod_multiple_interpreters
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@ref{5568,,Slot ID} whose value is one of:

@geindex Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED (C macro)
@anchor{c-api/module c Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED}@anchor{57a4}
@deffn {C Μακροεντολή} 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{57a5}
@deffn {C Μακροεντολή} Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED

The module supports being imported in subinterpreters,
but only when they share the main interpreter’s GIL.
(See @ref{412,,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{57a6}
@deffn {C Μακροεντολή} Py_MOD_PER_INTERPRETER_GIL_SUPPORTED

The module supports being imported in subinterpreters,
even when they have their own GIL.
(See @ref{412,,Isolating Extension Modules}.)
@end deffn

This slot determines whether or not importing this module
in a subinterpreter will fail.

If @code{Py_mod_multiple_interpreters} is not specified, the import
machinery defaults to @code{Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED}.


Added in version 3.12.

@end deffn

@geindex Py_mod_gil (C macro)
@anchor{c-api/module c Py_mod_gil}@anchor{691}
@deffn {C Μακροεντολή} Py_mod_gil
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
@ref{5568,,Slot ID} whose value is one of:

@geindex Py_MOD_GIL_USED (C macro)
@anchor{c-api/module c Py_MOD_GIL_USED}@anchor{57a7}
@deffn {C Μακροεντολή} 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{57a8}
@deffn {C Μακροεντολή} 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{6a5,,--disable-gil}.  Otherwise, it determines whether or not importing
this module will cause the GIL to be automatically enabled. See
@ref{67f,,Free-threaded CPython} for more detail.

If @code{Py_mod_gil} is not specified, the import machinery defaults to
@code{Py_MOD_GIL_USED}.


Added in version 3.13.

@end deffn

@node Creation and initialization slots,,Feature slots,Module definition
@anchor{c-api/module creation-and-initialization-slots}@anchor{57a9}
@subsubsection Creation and initialization slots


@geindex Py_mod_create (C macro)
@anchor{c-api/module c Py_mod_create}@anchor{5495}
@deffn {C Μακροεντολή} Py_mod_create
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.5.'
@ref{5568,,Slot ID} for a function that creates
the module object itself.
The function must have the signature:

@anchor{c-api/module c Py_mod_create create_module}@anchor{57aa}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *create_module (PyObject *spec, PyModuleDef *def)
@end deffn

The function will be called with:


@itemize -

@item 
`spec': a @code{ModuleSpec}-like object, meaning that any attributes defined
for @ref{245d,,importlib.machinery.ModuleSpec} have matching semantics.
However, any of the attributes may be missing.

@item 
`def': @code{NULL}, or the module definition if the module is created from one.
@end itemize

The function 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.

If @code{Py_mod_create} is not specified, the import machinery will create
a normal module object using @ref{5398,,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{539b,,PyModule_Type}.
However, some slots may only be used with
@code{PyModule_Type} instances; in particular:


@itemize -

@item 
@ref{d46,,Py_mod_exec},

@item 
@ref{57ab,,module state slots} (@code{Py_mod_state_*}),

@item 
@ref{549b,,Py_mod_token}.
@end itemize


Added in version 3.5.



Άλλαξε στην έκδοση 3.15: The `slots' argument may be a @code{ModuleSpec}-like object, rather than
a true @ref{245d,,ModuleSpec} instance.
Note that previous versions of CPython did not enforce this.

The `def' argument may now be @code{NULL}, since modules are not necessarily
made from definitions.

@end deffn

@geindex Py_mod_exec (C macro)
@anchor{c-api/module c Py_mod_exec}@anchor{d46}
@deffn {C Μακροεντολή} Py_mod_exec
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.5.'
@ref{5568,,Slot ID} for a function that will
`execute', or initialize, the module.
This function does the equivalent to executing the code of a Python module:
typically, it adds classes and constants to the module.
The signature of the function is:

@anchor{c-api/module c Py_mod_exec exec_module}@anchor{57ac}
@deffn {C Συνάρτηση} int exec_module (PyObject *module)
@end deffn

See the @ref{57ad,,Support functions} section for some useful
functions to call.

For backwards compatibility, the @ref{196c,,PyModuleDef.m_slots} array may
contain multiple @code{Py_mod_exec} slots; these are processed in the
order they appear in the array.
Elsewhere (that is, in arguments to @ref{38c,,PyModule_FromSlotsAndSpec()}
and in return values of @code{PyModExport_@var{<name>}}), repeating the slot
is not allowed.


Added in version 3.5.



Άλλαξε στην έκδοση 3.15: Repeated @code{Py_mod_exec} slots are disallowed, except in
@ref{196c,,PyModuleDef.m_slots}.

@end deffn

@geindex Py_mod_methods (C macro)
@anchor{c-api/module c Py_mod_methods}@anchor{51a6}
@deffn {C Μακροεντολή} Py_mod_methods
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for a table of module-level
functions, as an array of @ref{1879,,PyMethodDef} values suitable as the
`functions' argument to @ref{538f,,PyModule_AddFunctions()}.

Like other slot IDs, a slots array may only contain one
@code{Py_mod_methods} entry.
To add functions from multiple @ref{1879,,PyMethodDef} arrays, call
@ref{538f,,PyModule_AddFunctions()} in the @ref{d46,,Py_mod_exec} function.

The table must be statically allocated (or otherwise guaranteed to outlive
the module object).


Added in version 3.15: Use @ref{57ae,,PyModuleDef.m_methods} instead to support previous versions.

@end deffn

@node Module state,Creating extension modules dynamically,Module definition,Module Objects
@anchor{c-api/module ext-module-state}@anchor{57af}@anchor{c-api/module module-state}@anchor{57b0}
@subsubsection Module state


Extension modules can have `module state' – a
piece of memory that is allocated on module creation,
and freed when the module object is deallocated.
The module state is specified using @ref{57ab,,dedicated slots}.

A typical use of module state is storing an exception type – or indeed `any'
type object defined by the module –

Unlike the module’s Python attributes, Python code cannot replace or delete
data stored in module state.

Keeping per-module information in attributes and module state, rather than in
static globals, makes module objects `isolated' and safer for use in
multiple sub-interpreters.
It also helps Python do an orderly clean-up when it shuts down.

Extensions that keep references to Python objects as part of module state must
implement @ref{549a,,Py_mod_state_traverse} and @ref{5497,,Py_mod_state_clear}
functions to avoid reference leaks.

To retrieve the state from a given module, use the following functions:

@geindex PyModule_GetState (C function)
@anchor{c-api/module c PyModule_GetState}@anchor{d48}
@deffn {C Συνάρτηση} void *PyModule_GetState (PyObject *module)
` Μέρος του @ref{95c,,Σταθερό 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{5499,,Py_mod_state_size}.

On error, return @code{NULL} with an exception set.
Use @ref{1ea5,,PyErr_Occurred()} to tell this case apart from missing
module state.
@end deffn

@geindex PyModule_GetStateSize (C function)
@anchor{c-api/module c PyModule_GetStateSize}@anchor{5396}
@deffn {C Συνάρτηση} int PyModule_GetStateSize (PyObject *module, Py_ssize_t *result)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Set `*result' to the size of `module'’s state, as specified
using @ref{5499,,Py_mod_state_size} (or @ref{d47,,PyModuleDef.m_size}),
and return 0.

On error, set `*result' to -1, and return -1 with an exception set.


Added in version 3.15.

@end deffn

@menu
* Slots for defining module state:: 
* Module token:: 

@end menu

@node Slots for defining module state,Module token,,Module state
@anchor{c-api/module ext-module-state-slots}@anchor{57ab}@anchor{c-api/module slots-for-defining-module-state}@anchor{57b1}
@subsubsection Slots for defining module state


The following @ref{5568,,slot IDs}  are available for
defining the module state.

@geindex Py_mod_state_size (C macro)
@anchor{c-api/module c Py_mod_state_size}@anchor{5499}
@deffn {C Μακροεντολή} Py_mod_state_size
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for the size of the module state,
in bytes.

Setting the value 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.

See 
@geindex Python Enhancement Proposals; PEP 3121
PEP 3121@footnote{https://peps.python.org/pep-3121/} for more details.

Use @ref{5396,,PyModule_GetStateSize()} to retrieve the size of a given module.


Added in version 3.15: Use @ref{d47,,PyModuleDef.m_size} instead to support previous versions.

@end deffn

@geindex Py_mod_state_traverse (C macro)
@anchor{c-api/module c Py_mod_state_traverse}@anchor{549a}
@deffn {C Μακροεντολή} Py_mod_state_traverse
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for a traversal function to call
during GC traversal of the module object.

The signature of the function, and meanings of the arguments,
is similar as for @ref{36b,,PyTypeObject.tp_traverse}:

@anchor{c-api/module c Py_mod_state_traverse traverse_module_state}@anchor{57b2}
@deffn {C Συνάρτηση} int traverse_module_state (PyObject *module, visitproc visit, void *arg)
@end deffn

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{d46,,Py_mod_exec} function). More
precisely, this function is not called if the state size
(@ref{5499,,Py_mod_state_size}) is greater than 0 and the module state
(as returned by @ref{d48,,PyModule_GetState()}) is @code{NULL}.


Added in version 3.15: Use @ref{d47,,PyModuleDef.m_size} instead to support previous versions.

@end deffn

@geindex Py_mod_state_clear (C macro)
@anchor{c-api/module c Py_mod_state_clear}@anchor{5497}
@deffn {C Μακροεντολή} Py_mod_state_clear
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for a clear function to call
during GC clearing of the module object.

The signature of the function is:

@anchor{c-api/module c Py_mod_state_clear clear_module_state}@anchor{57b3}
@deffn {C Συνάρτηση} int clear_module_state (PyObject *module)
@end deffn

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{d46,,Py_mod_exec} function). More
precisely, this function is not called if the state size
(@ref{5499,,Py_mod_state_size}) is greater than 0 and the module state
(as returned by @ref{d48,,PyModule_GetState()}) is @code{NULL}.

Like @ref{51f7,,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
the @ref{5498,,Py_mod_state_free} function is called directly.


Added in version 3.15: Use @ref{d43,,PyModuleDef.m_clear} instead to support previous versions.

@end deffn

@geindex Py_mod_state_free (C macro)
@anchor{c-api/module c Py_mod_state_free}@anchor{5498}
@deffn {C Μακροεντολή} Py_mod_state_free
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for a function to call during
deallocation of the module object.

The signature of the function is:

@anchor{c-api/module c Py_mod_state_free free_module_state}@anchor{57b4}
@deffn {C Συνάρτηση} int free_module_state (PyObject *module)
@end deffn

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{d46,,Py_mod_exec} function). More
precisely, this function is not called if the state size
(@ref{5499,,Py_mod_state_size}) is greater than 0 and the module state
(as returned by @ref{d48,,PyModule_GetState()}) is @code{NULL}.


Added in version 3.15: Use @ref{d44,,PyModuleDef.m_free} instead to support previous versions.

@end deffn

@node Module token,,Slots for defining module state,Module state
@anchor{c-api/module ext-module-token}@anchor{5644}@anchor{c-api/module module-token}@anchor{57b5}
@subsubsection Module token


Each module may have an associated `token': a pointer-sized value intended to
identify of the module state’s memory layout.
This means that if you have a module object, but you are not sure if it
“belongs” to your extension, you can check using code like this:

@example
PyObject *module = <the module in question>

void *module_token;
if (PyModule_GetToken(module, &module_token) < 0) @{
    return NULL;
@}
if (module_token != your_token) @{
    PyErr_SetString(PyExc_ValueError, "unexpected module")
    return NULL;
@}

// This module's state has the expected memory layout; it's safe to cast
struct my_state state = (struct my_state*)PyModule_GetState(module)
@end example

A module’s token – and the `your_token' value to use in the above code – is:


@itemize -

@item 
For modules created with @ref{d45,,PyModuleDef}: the address of that
@code{PyModuleDef};

@item 
For modules defined with the @ref{549b,,Py_mod_token} slot: the value
of that slot;

@item 
For modules created from an @code{PyModExport_*}
@ref{38d,,export hook}: the slots array that the export
hook returned (unless overridden with @ref{549b,,Py_mod_token}).
@end itemize

@geindex Py_mod_token (C macro)
@anchor{c-api/module c Py_mod_token}@anchor{549b}
@deffn {C Μακροεντολή} Py_mod_token
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} for the module token.

If you use this slot to set the module token (rather than rely on the
default), you must ensure that:


@itemize *

@item 
The pointer outlives the class, so it’s not reused for something else
while the class exists.

@item 
It «belongs» to the extension module where the class lives, so it will not
clash with other extensions.

@item 
If the token points to a @ref{d45,,PyModuleDef} struct, the module should
behave as if it was created from that @code{PyModuleDef}.
In particular, the module state must have matching layout and semantics.
@end itemize

Modules created from @ref{d45,,PyModuleDef} always use the address of
the @code{PyModuleDef} as the token.
This means that @code{Py_mod_token} cannot be used in
@ref{196c,,PyModuleDef.m_slots}.


Added in version 3.15.

@end deffn

@geindex PyModule_GetToken (C function)
@anchor{c-api/module c PyModule_GetToken}@anchor{5397}
@deffn {C Συνάρτηση} int PyModule_GetToken (PyObject *module, void **result)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Set `*result' to the module token for `module' and return 0.

On error, set `*result' to NULL, and return -1 with an exception set.


Added in version 3.15.

@end deffn

See also @ref{5419,,PyType_GetModuleByToken()}.

@node Creating extension modules dynamically,Module definition struct,Module state,Module Objects
@anchor{c-api/module creating-extension-modules-dynamically}@anchor{57b6}@anchor{c-api/module module-from-slots}@anchor{579f}
@subsubsection Creating extension modules dynamically


The following functions may be used to create an extension module dynamically,
rather than from an extension’s @ref{38d,,export hook}.

@geindex PyModule_FromSlotsAndSpec (C function)
@anchor{c-api/module c PyModule_FromSlotsAndSpec}@anchor{38c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyModule_FromSlotsAndSpec (const PySlot *slots, PyObject *spec)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Create a new module object, given an array of @ref{579d,,slots}
and the @ref{245d,,ModuleSpec} `spec'.

The `slots' argument must point to an array of @ref{19d,,PySlot}
structures, terminated by an entry with slot ID of 0
(typically written as @ref{389,,PySlot_END}).
The array must include a @ref{358,,Py_mod_abi} entry.

The `spec' argument may be any @code{ModuleSpec}-like object, as described
in @ref{5495,,Py_mod_create} documentation.
Currently, the `spec' must have a @code{name} attribute.

On success, return the new module.
On error, return @code{NULL} with an exception set.

Note that this does not process the module’s execution slot
(@ref{d46,,Py_mod_exec}).
Both @code{PyModule_FromSlotsAndSpec()} and @ref{5391,,PyModule_Exec()}
must be called to fully initialize a module.
(See also @ref{555b,,Multi-phase initialization}.)


Added in version 3.15.

@end deffn

@geindex PyModule_Exec (C function)
@anchor{c-api/module c PyModule_Exec}@anchor{5391}
@deffn {C Συνάρτηση} int PyModule_Exec (PyObject *module)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Execute the @ref{d46,,Py_mod_exec} slot(s) of `module'.

On success, return 0.
On error, return -1 with an exception set.

For clarity: If `module' has no slots, for example if it uses
@ref{555c,,legacy single-phase initialization},
this function does nothing and returns 0.


Added in version 3.15.

@end deffn

@node Module definition struct,Support functions,Creating extension modules dynamically,Module Objects
@anchor{c-api/module module-definition-struct}@anchor{57b7}@anchor{c-api/module pymoduledef}@anchor{579e}
@subsubsection Module definition struct


Traditionally, extension modules were defined using a `module definition'
as the “description» of how a module should be created.
Rather than using an array of @ref{579d,,slots} directly,
the definition has dedicated members for most common functionality,
and allows additional slots as an extension mechanism.

This way of defining modules is still available and there are no plans to
remove it.

@geindex PyModuleDef (C type)
@anchor{c-api/module c PyModuleDef}@anchor{d45}
@deffn {C Τύπος} type PyModuleDef
` Μέρος του @ref{95c,,Σταθερό ABI} (see below).'
The module definition struct, which holds information needed to create
a module object.

This structure must be statically allocated (or be otherwise guaranteed
to be valid while any modules created from it exist).
Usually, there is only one variable of this type for each extension module
defined this way.

The struct, including all members, is part of the
@ref{197,,Stable ABI} for non-free-threaded builds (@code{abi3}).
In the Stable ABI for free-threaded builds (@code{abi3t}),
this struct is opaque, and unusable in practice; see @ref{579d,,Module definition}
for a replacement.

@geindex PyModuleDef.m_base (C member)
@anchor{c-api/module c PyModuleDef m_base}@anchor{57b8}
@deffn {C Μέλος} @ref{538b,,PyModuleDef_Base} m_base

Always initialize this member to @ref{57b9,,PyModuleDef_HEAD_INIT}:

@geindex PyModuleDef_Base (C type)
@anchor{c-api/module c PyModuleDef_Base}@anchor{538b}
@deffn {C Τύπος} type PyModuleDef_Base
` Μέρος του @ref{95c,,Σταθερό ABI} (see below).'
The type of @code{PyModuleDef.m_base}.

The struct is part of the @ref{197,,Stable ABI} for
non-free-threaded builds (@code{abi3}).
In the Stable ABI for Free-Threaded Builds
(@code{abi3t}), this struct is opaque, and unusable in practice.
@end deffn

@geindex PyModuleDef_HEAD_INIT (C macro)
@anchor{c-api/module c PyModuleDef_HEAD_INIT}@anchor{57b9}
@deffn {C Μακροεντολή} PyModuleDef_HEAD_INIT

The required initial value for @code{PyModuleDef.m_base}.
@end deffn
@end deffn

@geindex PyModuleDef.m_name (C member)
@anchor{c-api/module c PyModuleDef m_name}@anchor{57a1}
@deffn {C Μέλος} const char *m_name

Corresponds to the @ref{51a0,,Py_mod_name} slot.
@end deffn

@geindex PyModuleDef.m_doc (C member)
@anchor{c-api/module c PyModuleDef m_doc}@anchor{57a2}
@deffn {C Μέλος} const char *m_doc

These members correspond to the @ref{51a1,,Py_mod_doc} slot.
Setting this to NULL is equivalent to omitting the slot.
@end deffn

@geindex PyModuleDef.m_size (C member)
@anchor{c-api/module c PyModuleDef m_size}@anchor{d47}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} m_size

Corresponds to the @ref{5499,,Py_mod_state_size} slot.
Setting this to zero is equivalent to omitting the slot.

When using @ref{555c,,legacy single-phase initialization}
or when creating modules dynamically using @ref{5562,,PyModule_Create()}
or @ref{5390,,PyModule_Create2()}, @code{m_size} may be set to -1.
This indicates that the module does not support sub-interpreters,
because it has global state.
@end deffn

@geindex PyModuleDef.m_methods (C member)
@anchor{c-api/module c PyModuleDef m_methods}@anchor{57ae}
@deffn {C Μέλος} @ref{1879,,PyMethodDef} *m_methods

Corresponds to the @ref{51a6,,Py_mod_methods} slot.
Setting this to NULL is equivalent to omitting the slot.
@end deffn

@geindex PyModuleDef.m_slots (C member)
@anchor{c-api/module c PyModuleDef m_slots}@anchor{196c}
@deffn {C Μέλος} @ref{538d,,PyModuleDef_Slot} *m_slots

An array of additional slots, terminated by a @code{@{0, NULL@}} entry.
Note that the entries use the older @ref{538d,,PyModuleDef_Slot} structure,
rather than @ref{19d,,PySlot}.

If the array contains slots corresponding to @ref{d45,,PyModuleDef}
members, the values must match.
For example, if you use @ref{51a0,,Py_mod_name} in @code{m_slots},
@ref{57a1,,PyModuleDef.m_name} must be set to the same pointer
(not just an equal string).


Άλλαξε στην έκδοση 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{57ba}
@deffn {C Μέλος} @ref{54f4,,inquiry} m_reload
@end deffn
@end quotation


@geindex PyModuleDef_Slot (C type)
@anchor{c-api/module c PyModuleDef_Slot}@anchor{538d}
@deffn {C Τύπος} type PyModuleDef_Slot
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών) από την έκδοση 3.5.'
Older structure defining additional slots of a module.

Note that a @code{PyModuleDef_Slot} array may be included in a
@code{PySlot} array using @ref{37b,,Py_mod_slots},
and vice versa using @ref{379,,Py_slot_subslots}.

Each @code{PyModuleDef_Slot} structure @code{modslot} is interpreted
as the following @ref{19d,,PySlot} structure:

@example
(PySlot)@{
   .sl_id=modslot.slot,
   .sl_flags=PySlot_INTPTR | sub_static,
   .sl_ptr=modslot.value
@}
@end example

where @code{sub_static} is @code{PySlot_STATIC} if the slot requires
the flag (such as for @ref{51a6,,Py_mod_methods}), or if this flag
is present on the «parent» @code{Py_mod_slots} slot (if any).

@geindex PyModuleDef_Slot.slot (C member)
@anchor{c-api/module c PyModuleDef_Slot slot}@anchor{57bb}
@deffn {C Μέλος} int slot

Corresponds to @ref{5568,,PySlot.sl_id}.
@end deffn

@geindex PyModuleDef_Slot.value (C member)
@anchor{c-api/module c PyModuleDef_Slot value}@anchor{57bc}
@deffn {C Μέλος} void *value

Corresponds to @ref{556c,,PySlot.sl_ptr}.
@end deffn


Added in version 3.5.

@end deffn
@end deffn

@geindex PyModuleDef.m_traverse (C member)
@geindex PyModuleDef.m_clear (C member)
@geindex PyModuleDef.m_free (C member)
@anchor{c-api/module c PyModuleDef m_traverse}@anchor{d42}
@deffn {C Μέλος} @ref{5503,,traverseproc} m_traverse
@anchor{c-api/module c PyModuleDef m_clear}@anchor{d43}
@deffnx {C Μέλος} @ref{54f4,,inquiry} m_clear
@anchor{c-api/module c PyModuleDef m_free}@anchor{d44}
@deffnx {C Μέλος} @ref{57bd,,freefunc} m_free

These members correspond to the @ref{549a,,Py_mod_state_traverse},
@ref{5497,,Py_mod_state_clear}, and @ref{5498,,Py_mod_state_free} slots,
respectively.

Setting these members to NULL is equivalent to omitting the
corresponding slots.


Άλλαξε στην έκδοση 3.9: @ref{d42,,m_traverse}, @ref{d43,,m_clear} and @ref{d44,,m_free}
functions are no longer called before the module state is allocated.

@end deffn
@end deffn

@geindex PyModuleDef_Type (C var)
@anchor{c-api/module c PyModuleDef_Type}@anchor{538e}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyModuleDef_Type
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.5.'
The type of @code{PyModuleDef} objects.
@end deffn

@geindex Py_mod_slots (C macro)
@anchor{c-api/module c Py_mod_slots}@anchor{37b}
@deffn {C Μακροεντολή} Py_mod_slots
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
@ref{5568,,Slot ID} that works like
@ref{379,,Py_slot_subslots}, except it specifies an array of
@ref{538d,,PyModuleDef_Slot} structures.


Added in version 3.15.

@end deffn
@anchor{c-api/module moduledef-dynamic}@anchor{57be}
The following API can be used to create modules from a @code{PyModuleDef}
struct:

@geindex PyModule_Create (C function)
@anchor{c-api/module c PyModule_Create}@anchor{5562}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyModule_Create (PyModuleDef *def)
`Επιστρεφόμενη τιμή: New reference.'
Create a new module object, given the definition in `def'.
This is a macro that calls @ref{5390,,PyModule_Create2()} with
`module_api_version' set to @ref{4c12,,PYTHON_API_VERSION}, or
to @ref{57bf,,PYTHON_ABI_VERSION} if using the
@ref{829,,limited API}.
@end deffn

@geindex PyModule_Create2 (C function)
@anchor{c-api/module c PyModule_Create2}@anchor{5390}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyModule_Create2 (PyModuleDef *def, int module_api_version)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{6dd,,RuntimeWarning} is emitted.

Return @code{NULL} with an exception set on error.

This function does not support slots.
The @ref{196c,,m_slots} member of `def' must be @code{NULL}.

@cartouche
@quotation Σημείωση 
Most uses of this function should be using @ref{5562,,PyModule_Create()}
instead; only use this if you are sure you need it.
@end quotation
@end cartouche
@end deffn

@geindex PyModule_FromDefAndSpec (C function)
@anchor{c-api/module c PyModule_FromDefAndSpec}@anchor{392}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyModule_FromDefAndSpec (PyModuleDef *def, PyObject *spec)
`Επιστρεφόμενη τιμή: New reference.'
This macro calls @ref{393,,PyModule_FromDefAndSpec2()} with
`module_api_version' set to @ref{4c12,,PYTHON_API_VERSION}, or
to @ref{57bf,,PYTHON_ABI_VERSION} if using the
@ref{829,,limited API}.


Added in version 3.5.



@ref{1a7,,Soft deprecated} since version 3.16.0a0 (unreleased): Prefer @ref{38c,,PyModule_FromSlotsAndSpec()} in new code.

@end deffn

@geindex PyModule_FromDefAndSpec2 (C function)
@anchor{c-api/module c PyModule_FromDefAndSpec2}@anchor{393}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyModule_FromDefAndSpec2 (PyModuleDef *def, PyObject *spec, int module_api_version)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{6dd,,RuntimeWarning} is emitted.

Return @code{NULL} with an exception set on error.

Note that this does not process execution slots (@ref{d46,,Py_mod_exec}).
Both @code{PyModule_FromDefAndSpec} and @code{PyModule_ExecDef} must be called
to fully initialize a module.

@cartouche
@quotation Σημείωση 
Most uses of this function should be using @ref{392,,PyModule_FromDefAndSpec()}
instead; only use this if you are sure you need it.
@end quotation
@end cartouche


Added in version 3.5.



@ref{1a7,,Soft deprecated} since version 3.16.0a0 (unreleased): Prefer @ref{38c,,PyModule_FromSlotsAndSpec()} in new code.

@end deffn

@geindex PyModule_ExecDef (C function)
@anchor{c-api/module c PyModule_ExecDef}@anchor{394}
@deffn {C Συνάρτηση} int PyModule_ExecDef (PyObject *module, PyModuleDef *def)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Process any execution slots (@ref{d46,,Py_mod_exec}) given in `def'.


Added in version 3.5.



@ref{1a7,,Soft deprecated} since version 3.16.0a0 (unreleased): To run a module’s own execution slots, prefer @ref{5391,,PyModule_Exec()},
which works on modules that were not created from a
@ref{d45,,PyModuleDef} structure.

@end deffn

@geindex PYTHON_API_VERSION (C macro)
@geindex PYTHON_API_STRING (C macro)
@anchor{c-api/module c PYTHON_API_VERSION}@anchor{4c12}
@deffn {C Μακροεντολή} PYTHON_API_VERSION
@anchor{c-api/module c PYTHON_API_STRING}@anchor{57c0}
@deffnx {C Μακροεντολή} PYTHON_API_STRING

The C API version, as an integer (@code{1013}) and string (@code{"1013"}), respectively.
Defined for backwards compatibility.

Currently, this constant is not updated in new Python versions, and is not
useful for versioning. This may change in the future.
@end deffn

@geindex PYTHON_ABI_VERSION (C macro)
@geindex PYTHON_ABI_STRING (C macro)
@anchor{c-api/module c PYTHON_ABI_VERSION}@anchor{57bf}
@deffn {C Μακροεντολή} PYTHON_ABI_VERSION
@anchor{c-api/module c PYTHON_ABI_STRING}@anchor{57c1}
@deffnx {C Μακροεντολή} PYTHON_ABI_STRING

Defined as @code{3} and @code{"3"}, respectively, for backwards compatibility.

Currently, this constant is not updated in new Python versions, and is not
useful for versioning. This may change in the future.
@end deffn

@node Support functions,,Module definition struct,Module Objects
@anchor{c-api/module capi-module-support-functions}@anchor{57ad}@anchor{c-api/module support-functions}@anchor{57c2}
@subsubsection Support functions


The following functions are provided to help initialize a module object.
They are intended for a module’s execution slot (@ref{d46,,Py_mod_exec}),
the initialization function for legacy @ref{555c,,single-phase initialization},
or code that creates modules dynamically.

@geindex PyModule_AddObjectRef (C function)
@anchor{c-api/module c PyModule_AddObjectRef}@anchor{800}
@deffn {C Συνάρτηση} int PyModule_AddObjectRef (PyObject *module, const char *name, PyObject *value)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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}.

Example usage:

@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

To be convenient, the function accepts @code{NULL} `value' with an exception
set. In this case, return @code{-1} and just leave the raised exception
unchanged.

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{5451,,PyUnicode_FromString()} and @ref{1927,,PyObject_SetAttr()} directly.
For more details, see @ref{3b5,,PyUnicode_InternFromString()}, which may be
used internally to create a key object.


Added in version 3.10.

@end deffn

@geindex PyModule_Add (C function)
@anchor{c-api/module c PyModule_Add}@anchor{7ff}
@deffn {C Συνάρτηση} int PyModule_Add (PyObject *module, const char *name, PyObject *value)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Similar to @ref{800,,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.

Example usage:

@example
if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) @{
    goto error;
@}
@end example


Added in version 3.13.

@end deffn

@geindex PyModule_AddObject (C function)
@anchor{c-api/module c PyModule_AddObject}@anchor{801}
@deffn {C Συνάρτηση} int PyModule_AddObject (PyObject *module, const char *name, PyObject *value)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Similar to @ref{800,,PyModule_AddObjectRef()}, but steals a reference to
`value' on success (if it returns @code{0}).

The new @ref{7ff,,PyModule_Add()} or @ref{800,,PyModule_AddObjectRef()}
functions are recommended, since it is
easy to introduce reference leaks by misusing the
@ref{801,,PyModule_AddObject()} function.

@cartouche
@quotation Σημείωση 
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{b6e,,Py_XDECREF()} `value' manually on error.
@end quotation
@end cartouche

Example usage:

@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


@ref{1a7,,Soft deprecated} since version 3.13.

@end deffn

@geindex PyModule_AddIntConstant (C function)
@anchor{c-api/module c PyModule_AddIntConstant}@anchor{18de}
@deffn {C Συνάρτηση} int PyModule_AddIntConstant (PyObject *module, const char *name, long value)
` Μέρος του @ref{95c,,Σταθερό 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{1dca,,PyLong_FromLong()} and
@ref{800,,PyModule_AddObjectRef()}; see their documentation for details.
@end deffn

@geindex PyModule_AddStringConstant (C function)
@anchor{c-api/module c PyModule_AddStringConstant}@anchor{18df}
@deffn {C Συνάρτηση} int PyModule_AddStringConstant (PyObject *module, const char *name, const char *value)
` Μέρος του @ref{95c,,Σταθερό 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{3b5,,PyUnicode_InternFromString()} and @ref{800,,PyModule_AddObjectRef()};
see their documentation for details.
@end deffn

@geindex PyModule_AddIntMacro (C macro)
@anchor{c-api/module c PyModule_AddIntMacro}@anchor{1795}
@deffn {C Μακροεντολή} 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{1794}
@deffn {C Μακροεντολή} 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{d3d}
@deffn {C Συνάρτηση} int PyModule_AddType (PyObject *module, PyTypeObject *type)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Add a type object to `module'.
The type object is finalized by calling internally @ref{b5e,,PyType_Ready()}.
The name of the type object is taken from the last component of
@ref{1ea6,,tp_name} after dot.
Return @code{-1} with an exception set on error, @code{0} on success.


Added in version 3.9.

@end deffn

@geindex PyModule_AddFunctions (C function)
@anchor{c-api/module c PyModule_AddFunctions}@anchor{538f}
@deffn {C Συνάρτηση} int PyModule_AddFunctions (PyObject *module, PyMethodDef *functions)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Add the functions from the @code{NULL} terminated `functions' array to `module'.
Refer to the @ref{1879,,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} (such as when using @ref{555b,,Multi-phase initialization},
@code{PyModule_Create}, or @code{PyModule_FromDefAndSpec}).
Some module authors may prefer defining functions in multiple
@ref{1879,,PyMethodDef} arrays; in that case they should call this function
directly.

The `functions' array must be statically allocated (or otherwise guaranteed
to outlive the module object).


Added in version 3.5.

@end deffn

@geindex PyModule_SetDocString (C function)
@anchor{c-api/module c PyModule_SetDocString}@anchor{539a}
@deffn {C Συνάρτηση} int PyModule_SetDocString (PyObject *module, const char *docstring)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Set the docstring for `module' to `docstring'.
This function is called automatically when creating a module from
@code{PyModuleDef} (such as when using @ref{555b,,Multi-phase initialization},
@code{PyModule_Create}, or @code{PyModule_FromDefAndSpec}).

Return @code{0} on success.
Return @code{-1} with an exception set on error.


Added in version 3.5.

@end deffn

@geindex PyUnstable_Module_SetGIL (C function)
@anchor{c-api/module c PyUnstable_Module_SetGIL}@anchor{6a9}
@deffn {C Συνάρτηση} int PyUnstable_Module_SetGIL (PyObject *module, void *gil)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@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{691,,Py_mod_gil}. It must be called during `module'’s initialization
function when using @ref{555c,,Legacy single-phase initialization}.
If this function is not called during module initialization, the
import machinery assumes the module does not support running without the
GIL. This function is only available in Python builds configured with
@ref{6a5,,--disable-gil}.
Return @code{-1} with an exception set on error, @code{0} on success.


Added in version 3.13.

@end deffn

@menu
* Module lookup (single-phase initialization): Module lookup single-phase initialization. 

@end menu

@node Module lookup single-phase initialization,,,Support functions
@anchor{c-api/module module-lookup-single-phase-initialization}@anchor{57c3}
@subsubsection Module lookup (single-phase initialization)


The legacy @ref{555c,,single-phase initialization}
initialization scheme creates singleton modules that can be looked up
in the context of the current interpreter. This allows the module object to be
retrieved later with only a reference to the module definition.

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{53ef}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyState_FindModule (PyModuleDef *def)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό 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{53ee,,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{53ee}
@deffn {C Συνάρτηση} int PyState_AddModule (PyObject *module, PyModuleDef *def)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.3.'
Attaches the module object passed to the function to the interpreter state. This allows
the module object to be accessible via @ref{53ef,,PyState_FindModule()}.

Only effective on modules created using single-phase initialization.

Python calls @code{PyState_AddModule} automatically after importing a module
that uses @ref{555c,,single-phase initialization},
so it is unnecessary (but harmless) to call it from module initialization
code. An explicit call is needed only if the module’s own init code
subsequently calls @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).

If a module was attached previously using the same `def', it is replaced
by the new `module'.

The caller must have an @ref{1a1,,attached thread state}.

Return @code{-1} with an exception set on error, @code{0} on success.


Added in version 3.3.

@end deffn

@geindex PyState_RemoveModule (C function)
@anchor{c-api/module c PyState_RemoveModule}@anchor{53f0}
@deffn {C Συνάρτηση} int PyState_RemoveModule (PyModuleDef *def)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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 have an @ref{1a1,,attached thread state}.


Added in version 3.3.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Iterator Objects,Descriptor Objects,Module Objects,Other Objects
@anchor{c-api/iterator doc}@anchor{57c4}@anchor{c-api/iterator id1}@anchor{57c5}@anchor{c-api/iterator iterator-objects}@anchor{57c6}@anchor{c-api/iterator translation-repo}@anchor{57c7}
@subsubsection Iterator Objects


Python provides two general-purpose iterator objects.  The first, a sequence
iterator, works with an arbitrary sequence supporting the @ref{787,,__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{53d6}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PySeqIter_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Type object for iterator objects returned by @ref{53d5,,PySeqIter_New()} and the
one-argument form of the @ref{bb4,,iter()} built-in function for built-in sequence
types.
@end deffn

@geindex PySeqIter_Check (C function)
@anchor{c-api/iterator c PySeqIter_Check}@anchor{57c8}
@deffn {C Συνάρτηση} int PySeqIter_Check (PyObject *op)

Return true if the type of `op' is @ref{53d6,,PySeqIter_Type}.  This function
always succeeds.
@end deffn

@geindex PySeqIter_New (C function)
@anchor{c-api/iterator c PySeqIter_New}@anchor{53d5}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySeqIter_New (PyObject *seq)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return an iterator that works with a general sequence object, `seq'.  The
iteration ends when the sequence raises @ref{18d7,,IndexError} for the subscripting
operation.
@end deffn

@geindex PyCallIter_Type (C var)
@anchor{c-api/iterator c PyCallIter_Type}@anchor{52b6}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyCallIter_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Type object for iterator objects returned by @ref{52b5,,PyCallIter_New()} and the
two-argument form of the @ref{bb4,,iter()} built-in function.
@end deffn

@geindex PyCallIter_Check (C function)
@anchor{c-api/iterator c PyCallIter_Check}@anchor{57c9}
@deffn {C Συνάρτηση} int PyCallIter_Check (PyObject *op)

Return true if the type of `op' is @ref{52b6,,PyCallIter_Type}.  This
function always succeeds.
@end deffn

@geindex PyCallIter_New (C function)
@anchor{c-api/iterator c PyCallIter_New}@anchor{52b5}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCallIter_New (PyObject *callable, PyObject *sentinel)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return a new iterator.  The first parameter, `callable', can be any Python
callable object that can be called with no parameters; each call to it should
return the next item in the iteration.  When `callable' returns a value equal to
`sentinel', the iteration will be terminated.
@end deffn

@menu
* Range Objects:: 
* Builtin Iterator Types:: 
* Other Iterator Objects:: 

@end menu

@node Range Objects,Builtin Iterator Types,,Iterator Objects
@anchor{c-api/iterator range-objects}@anchor{57ca}
@subsubsection Range Objects


@geindex PyRange_Type (C var)
@anchor{c-api/iterator c PyRange_Type}@anchor{53d3}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyRange_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type object for @ref{d0f,,range} objects.
@end deffn

@geindex PyRange_Check (C function)
@anchor{c-api/iterator c PyRange_Check}@anchor{57cb}
@deffn {C Συνάρτηση} int PyRange_Check (PyObject *o)

Return true if the object `o' is an instance of a @ref{d0f,,range} object.
This function always succeeds.
@end deffn

@node Builtin Iterator Types,Other Iterator Objects,Range Objects,Iterator Objects
@anchor{c-api/iterator builtin-iterator-types}@anchor{57cc}
@subsubsection Builtin Iterator Types


These are built-in iteration types that are included in Python’s C API, but
provide no additional functions. They are here for completeness.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

C type

@tab

Python type

@item

@geindex PyEnum_Type (C var)
@anchor{c-api/iterator c PyEnum_Type}@anchor{52f4}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyEnum_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{1823,,enumerate}

@item

@geindex PyFilter_Type (C var)
@anchor{c-api/iterator c PyFilter_Type}@anchor{5352}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyFilter_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{c3b,,filter}

@item

@geindex PyMap_Type (C var)
@anchor{c-api/iterator c PyMap_Type}@anchor{5382}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyMap_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{43e,,map}

@item

@geindex PyReversed_Type (C var)
@anchor{c-api/iterator c PyReversed_Type}@anchor{53d4}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyReversed_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{c3c,,reversed}

@item

@geindex PyZip_Type (C var)
@anchor{c-api/iterator c PyZip_Type}@anchor{5460}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyZip_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@tab

@ref{43f,,zip}

@end multitable


@node Other Iterator Objects,,Builtin Iterator Types,Iterator Objects
@anchor{c-api/iterator other-iterator-objects}@anchor{57cd}
@subsubsection Other Iterator Objects


@geindex PyByteArrayIter_Type (C var)
@anchor{c-api/iterator c PyByteArrayIter_Type}@anchor{529d}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyByteArrayIter_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyBytesIter_Type (C var)
@anchor{c-api/iterator c PyBytesIter_Type}@anchor{52a3}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyBytesIter_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyListIter_Type (C var)
@anchor{c-api/iterator c PyListIter_Type}@anchor{536f}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyListIter_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyListRevIter_Type (C var)
@anchor{c-api/iterator c PyListRevIter_Type}@anchor{5370}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyListRevIter_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PySetIter_Type (C var)
@anchor{c-api/iterator c PySetIter_Type}@anchor{53e4}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PySetIter_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyTupleIter_Type (C var)
@anchor{c-api/iterator c PyTupleIter_Type}@anchor{5413}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyTupleIter_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyRangeIter_Type (C var)
@anchor{c-api/iterator c PyRangeIter_Type}@anchor{53d2}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyRangeIter_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyLongRangeIter_Type (C var)
@anchor{c-api/iterator c PyLongRangeIter_Type}@anchor{5377}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyLongRangeIter_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyDictIterKey_Type (C var)
@anchor{c-api/iterator c PyDictIterKey_Type}@anchor{52de}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDictIterKey_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyDictRevIterKey_Type (C var)
@anchor{c-api/iterator c PyDictRevIterKey_Type}@anchor{52e4}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDictRevIterKey_Type
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.8.'
@end deffn

@geindex PyDictIterValue_Type (C var)
@anchor{c-api/iterator c PyDictIterValue_Type}@anchor{52df}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDictIterValue_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyDictRevIterValue_Type (C var)
@anchor{c-api/iterator c PyDictRevIterValue_Type}@anchor{52e5}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDictRevIterValue_Type
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.8.'
@end deffn

@geindex PyDictIterItem_Type (C var)
@anchor{c-api/iterator c PyDictIterItem_Type}@anchor{52dd}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDictIterItem_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyDictRevIterItem_Type (C var)
@anchor{c-api/iterator c PyDictRevIterItem_Type}@anchor{52e3}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDictRevIterItem_Type
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.8.'
@end deffn

@geindex PyODictIter_Type (C var)
@anchor{c-api/iterator c PyODictIter_Type}@anchor{57ce}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyODictIter_Type

Type objects for iterators of various built-in objects.

Do not create instances of these directly; prefer calling
@ref{53ca,,PyObject_GetIter()} instead.

Note that there is no guarantee that a given built-in type uses a given iterator
type. For example, iterating over @ref{d0f,,range} will use one of two iterator
types depending on the size of the range. Other types may start using a
similar scheme in the future, without warning.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Descriptor Objects,Slice Objects,Iterator Objects,Other Objects
@anchor{c-api/descriptor doc}@anchor{57cf}@anchor{c-api/descriptor descriptor-objects}@anchor{57d0}@anchor{c-api/descriptor id1}@anchor{57d1}@anchor{c-api/descriptor translation-repo}@anchor{57d2}
@subsubsection Descriptor Objects


«Descriptors» are objects that describe some attribute of an object. They are
found in the dictionary of type objects.

@geindex PyDescr_NewGetSet (C function)
@anchor{c-api/descriptor c PyDescr_NewGetSet}@anchor{52da}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDescr_NewGetSet (PyTypeObject *type, struct PyGetSetDef *getset)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a new get-set descriptor for extension type `type' from the
@ref{f77,,PyGetSetDef} structure `getset'.

Get-set descriptors expose attributes implemented by C getter and setter
functions rather than stored directly in the instance. This is the same kind
of descriptor created for entries in @ref{51ec,,tp_getset}, and
it appears in Python as a @ref{2bfc,,types.GetSetDescriptorType} object.

On success, return a @ref{7da,,strong reference} to the descriptor. Return
@code{NULL} with an exception set on failure.
@end deffn

@geindex PyDescr_NewMember (C function)
@anchor{c-api/descriptor c PyDescr_NewMember}@anchor{52db}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDescr_NewMember (PyTypeObject *type, struct PyMemberDef *member)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a new member descriptor for extension type `type' from the
@ref{95a,,PyMemberDef} structure `member'.

Member descriptors expose fields in the type’s C struct as Python
attributes. This is the same kind of descriptor created for entries in
@ref{51e7,,tp_members}, and it appears in Python as a
@ref{2bfd,,types.MemberDescriptorType} object.

On success, return a @ref{7da,,strong reference} to the descriptor. Return
@code{NULL} with an exception set on failure.
@end deffn

@geindex PyMemberDescr_Type (C var)
@anchor{c-api/descriptor c PyMemberDescr_Type}@anchor{5386}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyMemberDescr_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type object for member descriptor objects created from
@ref{95a,,PyMemberDef} structures. These descriptors expose fields of a
C struct as attributes on a type, and correspond
to @ref{2bfd,,types.MemberDescriptorType} objects in Python.
@end deffn

@geindex PyGetSetDescr_Type (C var)
@anchor{c-api/descriptor c PyGetSetDescr_Type}@anchor{5359}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyGetSetDescr_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type object for get/set descriptor objects created from
@ref{f77,,PyGetSetDef} structures. These descriptors implement attributes
whose value is computed by C getter and setter functions, and are used
for many built-in type attributes. They correspond to
@ref{2bfc,,types.GetSetDescriptorType} objects in Python.
@end deffn

@geindex PyDescr_NewMethod (C function)
@anchor{c-api/descriptor c PyDescr_NewMethod}@anchor{1f69}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDescr_NewMethod (PyTypeObject *type, struct PyMethodDef *meth)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a new method descriptor for extension type `type' from the
@ref{1879,,PyMethodDef} structure `meth'.

Method descriptors expose C functions as methods on a type. This is the same
kind of descriptor created for entries in
@ref{51e9,,tp_methods}, and it appears in Python as a
@ref{f59,,types.MethodDescriptorType} object.

On success, return a @ref{7da,,strong reference} to the descriptor. Return
@code{NULL} with an exception set on failure.
@end deffn

@geindex PyMethodDescr_Type (C var)
@anchor{c-api/descriptor c PyMethodDescr_Type}@anchor{538a}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyMethodDescr_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type object for method descriptor objects created from
@ref{1879,,PyMethodDef} structures. These descriptors expose C functions as
methods on a type, and correspond to @ref{f59,,types.MethodDescriptorType}
objects in Python.
@end deffn

@geindex wrapperbase (C struct)
@anchor{c-api/descriptor c wrapperbase}@anchor{57d3}
@deffn {C Struct} struct wrapperbase

Describes a slot wrapper used by @ref{57d4,,PyDescr_NewWrapper()}.

Each @code{wrapperbase} record stores the Python-visible name and metadata for a
special method implemented by a type slot, together with the wrapper
function used to adapt that slot to Python’s calling convention.
@end deffn

@geindex PyDescr_NewWrapper (C function)
@anchor{c-api/descriptor c PyDescr_NewWrapper}@anchor{57d4}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDescr_NewWrapper (PyTypeObject *type, struct wrapperbase *base, void *wrapped)
`Επιστρεφόμενη τιμή: New reference.'
Create a new wrapper descriptor for extension type `type' from the
@ref{57d3,,wrapperbase} structure `base' and the wrapped slot function
pointer
`wrapped'.

Wrapper descriptors expose special methods implemented by type slots. This
is the same kind of descriptor that CPython creates for slot-based special
methods such as @code{__repr__} or @code{__add__}, and it appears in Python as a
@ref{f58,,types.WrapperDescriptorType} object.

On success, return a @ref{7da,,strong reference} to the descriptor. Return
@code{NULL} with an exception set on failure.
@end deffn

@geindex PyWrapperDescr_Type (C var)
@anchor{c-api/descriptor c PyWrapperDescr_Type}@anchor{545e}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyWrapperDescr_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type object for wrapper descriptor objects created by
@ref{57d4,,PyDescr_NewWrapper()} and @ref{545f,,PyWrapper_New()}. Wrapper
descriptors are used internally to expose special methods implemented
via wrapper structures, and appear in Python as
@ref{f58,,types.WrapperDescriptorType} objects.
@end deffn

@geindex PyDescr_NewClassMethod (C function)
@anchor{c-api/descriptor c PyDescr_NewClassMethod}@anchor{52d9}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDescr_NewClassMethod (PyTypeObject *type, PyMethodDef *method)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a new class method descriptor for extension type `type' from the
@ref{1879,,PyMethodDef} structure `method'.

Class method descriptors expose C methods that receive the class rather than
an instance when accessed. This is the same kind of descriptor created for
@code{METH_CLASS} entries in @ref{51e9,,tp_methods}, and it
appears in Python as a @ref{f5a,,types.ClassMethodDescriptorType} object.

On success, return a @ref{7da,,strong reference} to the descriptor. Return
@code{NULL} with an exception set on failure.
@end deffn

@geindex PyDescr_IsData (C function)
@anchor{c-api/descriptor c PyDescr_IsData}@anchor{1ea9}
@deffn {C Συνάρτηση} int PyDescr_IsData (PyObject *descr)

Return non-zero if the descriptor object `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{545f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyWrapper_New (PyObject *d, PyObject *self)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a new bound wrapper object from the wrapper descriptor `d' and the
instance `self'.

This is the bound form of a wrapper descriptor created by
@ref{57d4,,PyDescr_NewWrapper()}. CPython creates these objects when a slot
wrapper is accessed through an instance, and they appear in Python as
@ref{a3a,,types.MethodWrapperType} objects.

On success, return a @ref{7da,,strong reference} to the wrapper object. Return
@code{NULL} with an exception set on failure.
@end deffn

@geindex PyDescr_COMMON (C macro)
@anchor{c-api/descriptor c PyDescr_COMMON}@anchor{57d5}
@deffn {C Μακροεντολή} PyDescr_COMMON

This is a macro including the common fields for a
descriptor object.

This was included in Python’s C API by mistake; do not use it in extensions.
For creating custom descriptor objects, create a class implementing the
descriptor protocol (@ref{57d6,,tp_descr_get} and
@ref{1eaa,,tp_descr_set}).


@ref{1a7,,Soft deprecated} since version 3.15.

@end deffn

@menu
* Built-in descriptors:: 

@end menu

@node Built-in descriptors,,,Descriptor Objects
@anchor{c-api/descriptor built-in-descriptors}@anchor{57d7}
@subsubsection Built-in descriptors


@geindex PyProperty_Type (C var)
@anchor{c-api/descriptor c PyProperty_Type}@anchor{53d1}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyProperty_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type object for property objects. This is the same object as
@ref{6bb,,property} in the Python layer.
@end deffn

@geindex PySuper_Type (C var)
@anchor{c-api/descriptor c PySuper_Type}@anchor{53f5}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PySuper_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type object for super objects. This is the same object as
@ref{443,,super} in the Python layer.
@end deffn

@geindex PyClassMethod_Type (C var)
@anchor{c-api/descriptor c PyClassMethod_Type}@anchor{57d8}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyClassMethod_Type

The type of class method objects. This is the same object as
@ref{69a,,classmethod} in the Python layer.
@end deffn

@geindex PyClassMethodDescr_Type (C var)
@anchor{c-api/descriptor c PyClassMethodDescr_Type}@anchor{52c2}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyClassMethodDescr_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type object for C-level class method descriptor objects.
This is the type of the descriptors created for @ref{69a,,classmethod()} defined
in C extension types, and corresponds to
@ref{f5a,,types.ClassMethodDescriptorType} objects in Python.
@end deffn

@geindex PyClassMethod_New (C function)
@anchor{c-api/descriptor c PyClassMethod_New}@anchor{57d9}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyClassMethod_New (PyObject *callable)

Create a new @ref{69a,,classmethod} object wrapping `callable'.
`callable' must be a callable object and must not be @code{NULL}.

On success, this function returns a @ref{7da,,strong reference} to a new class
method descriptor. On failure, this function returns @code{NULL} with an
exception set.
@end deffn

@geindex PyStaticMethod_Type (C var)
@anchor{c-api/descriptor c PyStaticMethod_Type}@anchor{57da}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyStaticMethod_Type

The type of static method objects. This is the same object as
@ref{666,,staticmethod} in the Python layer.
@end deffn

@geindex PyStaticMethod_New (C function)
@anchor{c-api/descriptor c PyStaticMethod_New}@anchor{57db}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyStaticMethod_New (PyObject *callable)

Create a new @ref{666,,staticmethod} object wrapping `callable'.
`callable' must be a callable object and must not be @code{NULL}.

On success, this function returns a @ref{7da,,strong reference} to a new static
method descriptor. On failure, this function returns @code{NULL} with an
exception set.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Slice Objects,MemoryView objects,Descriptor Objects,Other Objects
@anchor{c-api/slice doc}@anchor{57dc}@anchor{c-api/slice id1}@anchor{57dd}@anchor{c-api/slice slice-objects}@anchor{57de}@anchor{c-api/slice translation-repo}@anchor{57df}
@subsubsection Slice Objects


@geindex PySlice_Type (C var)
@anchor{c-api/slice c PySlice_Type}@anchor{53ea}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PySlice_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type object for slice objects.  This is the same as @ref{1d0,,slice} in the
Python layer.
@end deffn

@geindex PySlice_Check (C function)
@anchor{c-api/slice c PySlice_Check}@anchor{57e0}
@deffn {C Συνάρτηση} 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{53e9}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySlice_New (PyObject *start, PyObject *stop, PyObject *step)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{53e8}
@deffn {C Συνάρτηση} int PySlice_GetIndices (PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
` Μέρος του @ref{95c,,Σταθερό 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.


Άλλαξε στην έκδοση 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{644}
@deffn {C Συνάρτηση} 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)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Usable replacement for @ref{53e8,,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 Σημείωση 
This function is considered not safe for resizable sequences.
Its invocation should be replaced by a combination of
@ref{645,,PySlice_Unpack()} and @ref{646,,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


Άλλαξε στην έκδοση 3.2: The parameter type for the `slice' parameter was @code{PySliceObject*}
before.



Άλλαξε στην έκδοση 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.



Αποσύρθηκε στην έκδοση 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{645}
@deffn {C Συνάρτηση} int PySlice_Unpack (PyObject *slice, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.


Added in version 3.6.1.

@end deffn

@geindex PySlice_AdjustIndices (C function)
@anchor{c-api/slice c PySlice_AdjustIndices}@anchor{646}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PySlice_AdjustIndices (Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t step)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.


Added in version 3.6.1.

@end deffn

@menu
* Ellipsis Object:: 

@end menu

@node Ellipsis Object,,,Slice Objects
@anchor{c-api/slice ellipsis-object}@anchor{57e1}
@subsubsection Ellipsis Object


@geindex PyEllipsis_Type (C var)
@anchor{c-api/slice c PyEllipsis_Type}@anchor{52f3}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyEllipsis_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type of Python @ref{2519,,Ellipsis} object.  Same as @ref{c29,,types.EllipsisType}
in the Python layer.
@end deffn

@geindex Py_Ellipsis (C var)
@anchor{c-api/slice c Py_Ellipsis}@anchor{57e2}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *Py_Ellipsis

The Python @code{Ellipsis} object.  This object has no methods.  Like
@ref{5606,,Py_None}, it is an @ref{398,,immortal} singleton object.


Άλλαξε στην έκδοση 3.12: @ref{57e2,,Py_Ellipsis} is immortal.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@geindex object;memoryview
@anchor{c-api/memoryview memoryview-objects}@anchor{561d}
@node MemoryView objects,Pickle buffer objects,Slice Objects,Other Objects
@anchor{c-api/memoryview doc}@anchor{57e3}@anchor{c-api/memoryview id1}@anchor{57e4}@anchor{c-api/memoryview translation-repo}@anchor{57e5}
@subsubsection MemoryView objects


A @ref{1d2,,memoryview} object exposes the C level @ref{311,,buffer interface} as a Python object which can then be passed around like
any other object.

@geindex PyMemoryView_Type (C var)
@anchor{c-api/memoryview c PyMemoryView_Type}@anchor{5389}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyMemoryView_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This instance of @ref{e6b,,PyTypeObject} represents the Python memoryview
type. This is the same object as @ref{1d2,,memoryview} in the Python layer.
@end deffn

@geindex PyMemoryView_FromObject (C function)
@anchor{c-api/memoryview c PyMemoryView_FromObject}@anchor{5387}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMemoryView_FromObject (PyObject *obj)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a memoryview object from an object that provides the buffer interface.
If `obj' supports writable buffer exports, the memoryview object will be
read/write, otherwise it may be either read-only or read/write at the
discretion of the exporter.
@end deffn

@geindex PyBUF_READ (C macro)
@anchor{c-api/memoryview c PyBUF_READ}@anchor{1c13}
@deffn {C Μακροεντολή} PyBUF_READ
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Flag to request a readonly buffer.
@end deffn

@geindex PyBUF_WRITE (C macro)
@anchor{c-api/memoryview c PyBUF_WRITE}@anchor{1c14}
@deffn {C Μακροεντολή} PyBUF_WRITE
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Flag to request a writable buffer.
@end deffn

@geindex PyMemoryView_FromMemory (C function)
@anchor{c-api/memoryview c PyMemoryView_FromMemory}@anchor{1519}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMemoryView_FromMemory (char *mem, Py_ssize_t size, int flags)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Create a memoryview object using `mem' as the underlying buffer.
`flags' can be one of @ref{1c13,,PyBUF_READ} or @ref{1c14,,PyBUF_WRITE}.


Added in version 3.3.

@end deffn

@geindex PyMemoryView_FromBuffer (C function)
@anchor{c-api/memoryview c PyMemoryView_FromBuffer}@anchor{b43}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMemoryView_FromBuffer (const Py_buffer *view)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
Create a memoryview object wrapping the given buffer structure `view'.
For simple byte buffers, @ref{1519,,PyMemoryView_FromMemory()} is the preferred
function.
@end deffn

@geindex PyMemoryView_GetContiguous (C function)
@anchor{c-api/memoryview c PyMemoryView_GetContiguous}@anchor{5388}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMemoryView_GetContiguous (PyObject *obj, int buffertype, char order)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a memoryview object to a @ref{287e,,contiguous} chunk of memory (in either
“C” or “F’ortran `order') from an object that defines the buffer
interface. If memory is contiguous, the memoryview object points to the
original memory. Otherwise, a copy is made and the memoryview points to a
new bytes object.

`buffertype' can be one of @ref{1c13,,PyBUF_READ} or @ref{1c14,,PyBUF_WRITE}.
@end deffn

@geindex PyMemoryView_Check (C function)
@anchor{c-api/memoryview c PyMemoryView_Check}@anchor{57e6}
@deffn {C Συνάρτηση} 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{1d2,,memoryview}.  This
function always succeeds.
@end deffn

@geindex PyMemoryView_GET_BUFFER (C function)
@anchor{c-api/memoryview c PyMemoryView_GET_BUFFER}@anchor{57e7}
@deffn {C Συνάρτηση} @ref{b3a,,Py_buffer} *PyMemoryView_GET_BUFFER (PyObject *mview)

Return a pointer to the memoryview’s private copy of the exporter’s buffer.
`mview' `must' be a memoryview instance; this macro doesn’t check its type,
you must do it yourself or you will risk crashes.
@end deffn

@geindex PyMemoryView_GET_BASE (C function)
@anchor{c-api/memoryview c PyMemoryView_GET_BASE}@anchor{57e8}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMemoryView_GET_BASE (PyObject *mview)

Return either a pointer to the exporting object that the memoryview is based
on or @code{NULL} if the memoryview has been created by one of the functions
@ref{1519,,PyMemoryView_FromMemory()} or @ref{b43,,PyMemoryView_FromBuffer()}.
`mview' `must' be a memoryview instance.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@geindex object;PickleBuffer
@anchor{c-api/picklebuffer picklebuffer-objects}@anchor{57e9}
@node Pickle buffer objects,Weak Reference Objects<2>,MemoryView objects,Other Objects
@anchor{c-api/picklebuffer doc}@anchor{57ea}@anchor{c-api/picklebuffer pickle-buffer-objects}@anchor{57eb}@anchor{c-api/picklebuffer translation-repo}@anchor{57ec}
@subsubsection Pickle buffer objects



Added in version 3.8.


A @ref{1908,,pickle.PickleBuffer} object wraps a @ref{311,,buffer-providing object} for out-of-band data transfer with the @ref{ab,,pickle} module.

@geindex PyPickleBuffer_Type (C var)
@anchor{c-api/picklebuffer c PyPickleBuffer_Type}@anchor{57ed}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyPickleBuffer_Type

This instance of @ref{e6b,,PyTypeObject} represents the Python pickle buffer type.
This is the same object as @ref{1908,,pickle.PickleBuffer} in the Python layer.
@end deffn

@geindex PyPickleBuffer_Check (C function)
@anchor{c-api/picklebuffer c PyPickleBuffer_Check}@anchor{57ee}
@deffn {C Συνάρτηση} int PyPickleBuffer_Check (PyObject *op)

Return true if `op' is a pickle buffer instance.
This function always succeeds.
@end deffn

@geindex PyPickleBuffer_FromObject (C function)
@anchor{c-api/picklebuffer c PyPickleBuffer_FromObject}@anchor{57ef}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyPickleBuffer_FromObject (PyObject *obj)

Create a pickle buffer from the object `obj'.

This function will fail if `obj' doesn’t support the @ref{311,,buffer protocol}.

On success, return a new pickle buffer instance.
On failure, set an exception and return @code{NULL}.

Analogous to calling @ref{1908,,pickle.PickleBuffer} with `obj' in Python.
@end deffn

@geindex PyPickleBuffer_GetBuffer (C function)
@anchor{c-api/picklebuffer c PyPickleBuffer_GetBuffer}@anchor{57f0}
@deffn {C Συνάρτηση} const @ref{b3a,,Py_buffer} *PyPickleBuffer_GetBuffer (PyObject *picklebuf)

Get a pointer to the underlying @ref{b3a,,Py_buffer} that the pickle buffer wraps.

The returned pointer is valid as long as `picklebuf' is alive and has not been
released. The caller must not modify or free the returned @ref{b3a,,Py_buffer}.
If the pickle buffer has been released, raise @ref{277,,ValueError}.

On success, return a pointer to the buffer view.
On failure, set an exception and return @code{NULL}.
@end deffn

@geindex PyPickleBuffer_Release (C function)
@anchor{c-api/picklebuffer c PyPickleBuffer_Release}@anchor{57f1}
@deffn {C Συνάρτηση} int PyPickleBuffer_Release (PyObject *picklebuf)

Release the underlying buffer held by the pickle buffer.

Return @code{0} on success. On failure, set an exception and return @code{-1}.

Analogous to calling @ref{2f40,,pickle.PickleBuffer.release()} in Python.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Weak Reference Objects<2>,Capsules<2>,Pickle buffer objects,Other Objects
@anchor{c-api/weakref doc}@anchor{57f2}@anchor{c-api/weakref translation-repo}@anchor{57f3}@anchor{c-api/weakref weak-reference-objects}@anchor{57f4}@anchor{c-api/weakref weakrefobjects}@anchor{55f1}
@subsubsection Weak Reference Objects


Python supports `weak references' as first-class objects.  There are two
specific object types which directly implement weak references.  The first is a
simple reference object, and the second acts as a proxy for the original object
as much as it can.

@geindex PyWeakref_Check (C function)
@anchor{c-api/weakref c PyWeakref_Check}@anchor{57f5}
@deffn {C Συνάρτηση} 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{57f6}
@deffn {C Συνάρτηση} int PyWeakref_CheckRef (PyObject *ob)

Return non-zero if `ob' is a reference object or a subclass of the reference
type.  This function always succeeds.
@end deffn

@geindex PyWeakref_CheckRefExact (C function)
@anchor{c-api/weakref c PyWeakref_CheckRefExact}@anchor{57f7}
@deffn {C Συνάρτηση} int PyWeakref_CheckRefExact (PyObject *ob)

Return non-zero if `ob' is a reference object, but not a subclass of the
reference type.  This function always succeeds.
@end deffn

@geindex PyWeakref_CheckProxy (C function)
@anchor{c-api/weakref c PyWeakref_CheckProxy}@anchor{57f8}
@deffn {C Συνάρτηση} 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{1ddf}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyWeakref_NewRef (PyObject *ob, PyObject *callback)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{291,,TypeError}.


@subsubheading Δείτε επίσης


@ref{5647,,PyType_SUPPORTS_WEAKREFS()} for checking if `ob' is weakly
referenceable.

@end deffn

@geindex PyWeakref_NewProxy (C function)
@anchor{c-api/weakref c PyWeakref_NewProxy}@anchor{545d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyWeakref_NewProxy (PyObject *ob, PyObject *callback)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{291,,TypeError}.


@subsubheading Δείτε επίσης


@ref{5647,,PyType_SUPPORTS_WEAKREFS()} for checking if `ob' is weakly
referenceable.

@end deffn

@geindex PyWeakref_GetRef (C function)
@anchor{c-api/weakref c PyWeakref_GetRef}@anchor{3a4}
@deffn {C Συνάρτηση} int PyWeakref_GetRef (PyObject *ref, PyObject **pobj)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Get a @ref{7da,,strong reference} to the referenced object from a weak
reference, `ref', into `*pobj'.


@itemize *

@item 
On success, set `*pobj' to a new @ref{7da,,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


Added in version 3.13.

@end deffn

@geindex PyWeakref_IsDead (C function)
@anchor{c-api/weakref c PyWeakref_IsDead}@anchor{1aff}
@deffn {C Συνάρτηση} int PyWeakref_IsDead (PyObject *ref)

Test if the weak reference `ref' is dead. Returns 1 if the reference is
dead, 0 if it is alive, and -1 with an error set if `ref' is not a weak
reference object.


Added in version 3.14.

@end deffn

@geindex PyObject_ClearWeakRefs (C function)
@anchor{c-api/weakref c PyObject_ClearWeakRefs}@anchor{97a}
@deffn {C Συνάρτηση} void PyObject_ClearWeakRefs (PyObject *object)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This function is called by the @ref{51d3,,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{1ba2}
@deffn {C Συνάρτηση} void PyUnstable_Object_ClearWeakRefsNoCallbacks (PyObject *object)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Clears the weakrefs for `object' without calling the callbacks.

This function is called by the @ref{51d3,,tp_dealloc} handler
for types with finalizers (i.e., @ref{13a6,,__del__()}).  The handler for
those objects first calls @ref{97a,,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{97a,,PyObject_ClearWeakRefs()} to clear weakrefs instead of this function.


Added in version 3.13.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Capsules<2>,Sentinel objects,Weak Reference Objects<2>,Other Objects
@anchor{c-api/capsule doc}@anchor{57f9}@anchor{c-api/capsule capsules}@anchor{2c04}@anchor{c-api/capsule id1}@anchor{57fa}@anchor{c-api/capsule translation-repo}@anchor{57fb}
@subsubsection Capsules


@geindex object;Capsule

Refer to @ref{1702,,Providing a C API for an Extension Module} for more information on using these objects.


Added in version 3.1.


@geindex PyCapsule (C type)
@anchor{c-api/capsule c PyCapsule}@anchor{1617}
@deffn {C Τύπος} type PyCapsule

This subtype of @ref{19b,,PyObject} represents an opaque value, useful for C
extension modules which 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_Type (C var)
@anchor{c-api/capsule c PyCapsule_Type}@anchor{52c1}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyCapsule_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type object corresponding to capsule objects. This is the same object
as @ref{2c03,,types.CapsuleType} in the Python layer.
@end deffn

@geindex PyCapsule_Destructor (C type)
@anchor{c-api/capsule c PyCapsule_Destructor}@anchor{52b8}
@deffn {C Τύπος} type PyCapsule_Destructor
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type of a destructor callback for a capsule.  Defined as:

@example
typedef void (*PyCapsule_Destructor)(PyObject *);
@end example

See @ref{51da,,PyCapsule_New()} for the semantics of PyCapsule_Destructor
callbacks.
@end deffn

@geindex PyCapsule_CheckExact (C function)
@anchor{c-api/capsule c PyCapsule_CheckExact}@anchor{57fc}
@deffn {C Συνάρτηση} int PyCapsule_CheckExact (PyObject *p)
` Thread safety: @ref{292b,,Atomic}.'
Return true if its argument is a @ref{1617,,PyCapsule}.  This function always
succeeds.
@end deffn

@geindex PyCapsule_New (C function)
@anchor{c-api/capsule c PyCapsule_New}@anchor{51da}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCapsule_New (void *pointer, const char *name, PyCapsule_Destructor destructor)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{292b,,Atomic}.'
Create a @ref{1617,,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{1e07,,PyCapsule_Import()}.
@end deffn

@geindex PyCapsule_GetPointer (C function)
@anchor{c-api/capsule c PyCapsule_GetPointer}@anchor{52bc}
@deffn {C Συνάρτηση} void *PyCapsule_GetPointer (PyObject *capsule, const char *name)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
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{52ba}
@deffn {C Συνάρτηση} @ref{52b8,,PyCapsule_Destructor} PyCapsule_GetDestructor (PyObject *capsule)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
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{1701,,PyCapsule_IsValid()} or
@ref{1ea5,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyCapsule_GetContext (C function)
@anchor{c-api/capsule c PyCapsule_GetContext}@anchor{52b9}
@deffn {C Συνάρτηση} void *PyCapsule_GetContext (PyObject *capsule)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
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{1701,,PyCapsule_IsValid()} or
@ref{1ea5,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyCapsule_GetName (C function)
@anchor{c-api/capsule c PyCapsule_GetName}@anchor{52bb}
@deffn {C Συνάρτηση} const char *PyCapsule_GetName (PyObject *capsule)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
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{1701,,PyCapsule_IsValid()} or
@ref{1ea5,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyCapsule_Import (C function)
@anchor{c-api/capsule c PyCapsule_Import}@anchor{1e07}
@deffn {C Συνάρτηση} void *PyCapsule_Import (const char *name, int no_block)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{291f,,Safe to call from multiple threads with external synchronization only}.'
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.

This function splits `name' on the @code{.} character, and imports the first
element. It then processes further elements using attribute lookups.

Return the capsule’s internal `pointer' on success.  On failure, set an
exception and return @code{NULL}.

@cartouche
@quotation Σημείωση 
If `name' points to an attribute of some submodule or subpackage, this
submodule or subpackage must be previously imported using other means
(for example, by using @ref{3a3,,PyImport_ImportModule()}) for the
attribute lookups to succeed.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.3: `no_block' has no effect anymore.

@end deffn

@geindex PyCapsule_IsValid (C function)
@anchor{c-api/capsule c PyCapsule_IsValid}@anchor{1701}
@deffn {C Συνάρτηση} int PyCapsule_IsValid (PyObject *capsule, const char *name)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
Determines whether or not `capsule' is a valid capsule.  A valid capsule is
non-@code{NULL}, passes @ref{57fc,,PyCapsule_CheckExact()}, has a non-@code{NULL} pointer
stored in it, and its internal name matches the `name' parameter.  (See
@ref{52bc,,PyCapsule_GetPointer()} for information on how capsule names are
compared.)

In other words, if @ref{1701,,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{52bd}
@deffn {C Συνάρτηση} int PyCapsule_SetContext (PyObject *capsule, void *context)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
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{52be}
@deffn {C Συνάρτηση} int PyCapsule_SetDestructor (PyObject *capsule, PyCapsule_Destructor destructor)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
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{52bf}
@deffn {C Συνάρτηση} int PyCapsule_SetName (PyObject *capsule, const char *name)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
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{52c0}
@deffn {C Συνάρτηση} int PyCapsule_SetPointer (PyObject *capsule, void *pointer)
` Μέρος του @ref{95c,,Σταθερό ABI}.'` Thread safety: @ref{2924,,Safe to call without external synchronization on distinct objects}.'
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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Sentinel objects,Frame objects,Capsules<2>,Other Objects
@anchor{c-api/sentinel doc}@anchor{57fd}@anchor{c-api/sentinel sentinel-objects}@anchor{57fe}@anchor{c-api/sentinel sentinelobjects}@anchor{57ff}@anchor{c-api/sentinel translation-repo}@anchor{5800}
@subsubsection Sentinel objects


@geindex PySentinel_Type (C var)
@anchor{c-api/sentinel c PySentinel_Type}@anchor{5801}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PySentinel_Type

This instance of @ref{e6b,,PyTypeObject} represents the Python
@ref{18b,,sentinel} type.  This is the same object as @code{sentinel}.


Added in version 3.15.

@end deffn

@geindex PySentinel_Check (C function)
@anchor{c-api/sentinel c PySentinel_Check}@anchor{5802}
@deffn {C Συνάρτηση} int PySentinel_Check (PyObject *o)

Return true if `o' is a @ref{18b,,sentinel} object.  The @code{sentinel} type
does not allow subclasses, so this check is exact.


Added in version 3.15.

@end deffn

@geindex PySentinel_New (C function)
@anchor{c-api/sentinel c PySentinel_New}@anchor{5803}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PySentinel_New (const char *name, const char *module_name)
`Επιστρεφόμενη τιμή: New reference.'
Return a new @ref{18b,,sentinel} object with @ref{27d7,,__name__} set to
`name' and @ref{27d8,,__module__} set to `module_name'.
`name' must not be @code{NULL}. If `module_name' is @code{NULL}, @code{__module__}
is set to @code{None}.
Return @code{NULL} with an exception set on failure.

For pickling to work, `module_name' must be the name of an importable
module, and the sentinel must be accessible from that module under a
path matching `name'.  Pickle treats `name' as a global variable name
in `module_name' (see @ref{d97,,object.__reduce__()}).


Added in version 3.15.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Frame objects,Generator Objects,Sentinel objects,Other Objects
@anchor{c-api/frame doc}@anchor{5804}@anchor{c-api/frame frame-objects}@anchor{5805}@anchor{c-api/frame translation-repo}@anchor{5806}
@subsubsection Frame objects


@geindex PyFrameObject (C type)
@anchor{c-api/frame c PyFrameObject}@anchor{b68}
@deffn {C Τύπος} type PyFrameObject
` Μέρος του @ref{95c,,Σταθερό ABI} (ως μια αδιαφανής κατασκευή).'
The C structure of the objects used to describe frame objects.

There are no public members in this structure.


Άλλαξε στην έκδοση 3.11: The members of this structure were removed from the public C API.
Refer to the @ref{b67,,What’s New entry}
for details.

@end deffn

The @ref{1d37,,PyEval_GetFrame()} and @ref{b6d,,PyThreadState_GetFrame()} functions
can be used to get a frame object.

See also @ref{55c4,,Reflection}.

@geindex PyFrame_Type (C var)
@anchor{c-api/frame c PyFrame_Type}@anchor{b66}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyFrame_Type

The type of frame objects.
It is the same object as @ref{1de6,,types.FrameType} in the Python layer.


Άλλαξε στην έκδοση 3.11: Previously, this type was only available after including
@code{<frameobject.h>}.

@end deffn

@geindex PyFrame_New (C function)
@anchor{c-api/frame c PyFrame_New}@anchor{1cee}
@deffn {C Συνάρτηση} @ref{b68,,PyFrameObject} *PyFrame_New (PyThreadState *tstate, PyCodeObject *code, PyObject *globals, PyObject *locals)

Create a new frame object. This function returns a @ref{7da,,strong reference}
to the new frame object on success, and returns @code{NULL} with an exception
set on failure.
@end deffn

@geindex PyFrame_Check (C function)
@anchor{c-api/frame c PyFrame_Check}@anchor{b64}
@deffn {C Συνάρτηση} int PyFrame_Check (PyObject *obj)

Return non-zero if `obj' is a frame object.


Άλλαξε στην έκδοση 3.11: Previously, this function was only available after including
@code{<frameobject.h>}.

@end deffn

@geindex PyFrame_GetBack (C function)
@anchor{c-api/frame c PyFrame_GetBack}@anchor{b65}
@deffn {C Συνάρτηση} @ref{b68,,PyFrameObject} *PyFrame_GetBack (PyFrameObject *frame)
`Επιστρεφόμενη τιμή: New reference.'
Get the `frame' next outer frame.

Return a @ref{7da,,strong reference}, or @code{NULL} if `frame' has no outer
frame.
This raises no exceptions.


Added in version 3.9.

@end deffn

@geindex PyFrame_GetBuiltins (C function)
@anchor{c-api/frame c PyFrame_GetBuiltins}@anchor{b4d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFrame_GetBuiltins (PyFrameObject *frame)
`Επιστρεφόμενη τιμή: New reference.'
Get the `frame'’s @ref{258f,,f_builtins} attribute.

Return a @ref{7da,,strong reference}. The result cannot be @code{NULL}.


Added in version 3.11.

@end deffn

@geindex PyFrame_GetCode (C function)
@anchor{c-api/frame c PyFrame_GetCode}@anchor{b69}
@deffn {C Συνάρτηση} @ref{b59,,PyCodeObject} *PyFrame_GetCode (PyFrameObject *frame)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Get the `frame' code.

Return a @ref{7da,,strong reference}.

The result (frame code) cannot be @code{NULL}.


Added in version 3.9.

@end deffn

@geindex PyFrame_GetGenerator (C function)
@anchor{c-api/frame c PyFrame_GetGenerator}@anchor{b4e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFrame_GetGenerator (PyFrameObject *frame)
`Επιστρεφόμενη τιμή: New reference.'
Get the generator, coroutine, or async generator that owns this frame,
or @code{NULL} if this frame is not owned by a generator.
Does not raise an exception, even if the return value is @code{NULL}.

Return a @ref{7da,,strong reference}, or @code{NULL}.


Added in version 3.11.

@end deffn

@geindex PyFrame_GetGlobals (C function)
@anchor{c-api/frame c PyFrame_GetGlobals}@anchor{b4f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFrame_GetGlobals (PyFrameObject *frame)
`Επιστρεφόμενη τιμή: New reference.'
Get the `frame'’s @ref{258e,,f_globals} attribute.

Return a @ref{7da,,strong reference}. The result cannot be @code{NULL}.


Added in version 3.11.

@end deffn

@geindex PyFrame_GetLasti (C function)
@anchor{c-api/frame c PyFrame_GetLasti}@anchor{b50}
@deffn {C Συνάρτηση} int PyFrame_GetLasti (PyFrameObject *frame)

Get the `frame'’s @ref{c5e,,f_lasti} attribute.

Returns -1 if @code{frame.f_lasti} is @code{None}.


Added in version 3.11.

@end deffn

@geindex PyFrame_GetVar (C function)
@anchor{c-api/frame c PyFrame_GetVar}@anchor{96e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFrame_GetVar (PyFrameObject *frame, PyObject *name)
`Επιστρεφόμενη τιμή: New reference.'
Get the variable `name' of `frame'.


@itemize *

@item 
Return a @ref{7da,,strong reference} to the variable value on success.

@item 
Raise @ref{665,,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{1df,,str}.


Added in version 3.12.

@end deffn

@geindex PyFrame_GetVarString (C function)
@anchor{c-api/frame c PyFrame_GetVarString}@anchor{96f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFrame_GetVarString (PyFrameObject *frame, const char *name)
`Επιστρεφόμενη τιμή: New reference.'
Similar to @ref{96e,,PyFrame_GetVar()}, but the variable name is a C string
encoded in UTF-8.


Added in version 3.12.

@end deffn

@geindex PyFrame_GetLocals (C function)
@anchor{c-api/frame c PyFrame_GetLocals}@anchor{84e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyFrame_GetLocals (PyFrameObject *frame)
`Επιστρεφόμενη τιμή: New reference.'
Get the `frame'’s @ref{28d,,f_locals} attribute.
If the frame refers to an @ref{6ad,,optimized scope}, this returns a
write-through proxy object that allows modifying the locals.
In all other cases (classes, modules, @ref{185,,exec()}, @ref{184,,eval()}) it returns
the mapping representing the frame locals directly (as described for
@ref{28b,,locals()}).

Return a @ref{7da,,strong reference}.


Added in version 3.11.



Άλλαξε στην έκδοση 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{5807,,PyFrameLocalsProxy_Type}.

@end deffn

@geindex PyFrame_GetLineNumber (C function)
@anchor{c-api/frame c PyFrame_GetLineNumber}@anchor{b6a}
@deffn {C Συνάρτηση} int PyFrame_GetLineNumber (PyFrameObject *frame)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Return the line number that `frame' is currently executing.
@end deffn

@menu
* Frame locals proxies:: 
* Legacy local variable APIs:: 
* Internal frames:: 

@end menu

@node Frame locals proxies,Legacy local variable APIs,,Frame objects
@anchor{c-api/frame frame-locals-proxies}@anchor{5808}
@subsubsection Frame locals proxies



Added in version 3.13.


The @ref{28d,,f_locals} attribute on a @ref{acd,,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{5807}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyFrameLocalsProxy_Type

The type of frame @ref{28b,,locals()} proxy objects.
@end deffn

@geindex PyFrameLocalsProxy_Check (C function)
@anchor{c-api/frame c PyFrameLocalsProxy_Check}@anchor{5809}
@deffn {C Συνάρτηση} int PyFrameLocalsProxy_Check (PyObject *obj)

Return non-zero if `obj' is a frame @ref{28b,,locals()} proxy.
@end deffn

@node Legacy local variable APIs,Internal frames,Frame locals proxies,Frame objects
@anchor{c-api/frame legacy-local-variable-apis}@anchor{580a}
@subsubsection Legacy local variable APIs


These APIs are @ref{1a7,,soft deprecated}. As of Python 3.13, they do nothing.
They exist solely for backwards compatibility.

@geindex PyFrame_LocalsToFast (C function)
@anchor{c-api/frame c PyFrame_LocalsToFast}@anchor{580b}
@deffn {C Συνάρτηση} void PyFrame_LocalsToFast (PyFrameObject *f, int clear)

Prior to Python 3.13, this function would copy the @ref{28d,,f_locals}
attribute of `f' to the internal «fast» array of local variables, allowing
changes in frame objects to be visible to the interpreter. If `clear' was
true, this function would process variables that were unset in the locals
dictionary.


@ref{1a7,,Soft deprecated} since version 3.13: This function now does nothing.

@end deffn

@geindex PyFrame_FastToLocals (C function)
@anchor{c-api/frame c PyFrame_FastToLocals}@anchor{580c}
@deffn {C Συνάρτηση} void PyFrame_FastToLocals (PyFrameObject *f)

Prior to Python 3.13, this function would copy the internal «fast» array
of local variables (which is used by the interpreter) to the
@ref{28d,,f_locals} attribute of `f', allowing changes in local
variables to be visible to frame objects.


@ref{1a7,,Soft deprecated} since version 3.13: This function now does nothing.

@end deffn

@geindex PyFrame_FastToLocalsWithError (C function)
@anchor{c-api/frame c PyFrame_FastToLocalsWithError}@anchor{580d}
@deffn {C Συνάρτηση} int PyFrame_FastToLocalsWithError (PyFrameObject *f)

Prior to Python 3.13, this function was similar to
@ref{580c,,PyFrame_FastToLocals()}, but would return @code{0} on success, and
@code{-1} with an exception set on failure.


@ref{1a7,,Soft deprecated} since version 3.13: This function now does nothing.

@end deffn


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}


@node Internal frames,,Legacy local variable APIs,Frame objects
@anchor{c-api/frame internal-frames}@anchor{580e}
@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{1b81}
@deffn {C Struct} struct _PyInterpreterFrame

The interpreter’s internal frame representation.


Added in version 3.11.

@end deffn

@geindex PyUnstable_InterpreterFrame_GetCode (C function)
@anchor{c-api/frame c PyUnstable_InterpreterFrame_GetCode}@anchor{580f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnstable_InterpreterFrame_GetCode (struct _PyInterpreterFrame *frame);

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

@quotation

Return a @ref{7da,,strong reference} to the code object for the frame.
@end quotation


Added in version 3.12.

@end deffn

@geindex PyUnstable_InterpreterFrame_GetLasti (C function)
@anchor{c-api/frame c PyUnstable_InterpreterFrame_GetLasti}@anchor{5810}
@deffn {C Συνάρτηση} int PyUnstable_InterpreterFrame_GetLasti (struct _PyInterpreterFrame *frame);

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Return the byte offset into the last executed instruction.


Added in version 3.12.

@end deffn

@geindex PyUnstable_InterpreterFrame_GetLine (C function)
@anchor{c-api/frame c PyUnstable_InterpreterFrame_GetLine}@anchor{5811}
@deffn {C Συνάρτηση} int PyUnstable_InterpreterFrame_GetLine (struct _PyInterpreterFrame *frame);

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Return the currently executing line number, or -1 if there is no line number.


Added in version 3.12.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Generator Objects,Coroutine Objects,Frame objects,Other Objects
@anchor{c-api/gen doc}@anchor{5812}@anchor{c-api/gen gen-objects}@anchor{5813}@anchor{c-api/gen generator-objects}@anchor{5814}@anchor{c-api/gen translation-repo}@anchor{5815}
@subsubsection Generator Objects


Generator objects are what Python uses to implement generator iterators. They
are normally created by iterating over a function that yields values, rather
than explicitly calling @ref{5816,,PyGen_New()} or @ref{5817,,PyGen_NewWithQualName()}.

@geindex PyGenObject (C type)
@anchor{c-api/gen c PyGenObject}@anchor{5818}
@deffn {C Τύπος} type PyGenObject

The C structure used for generator objects.
@end deffn

@geindex PyGen_Type (C var)
@anchor{c-api/gen c PyGen_Type}@anchor{5819}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyGen_Type

The type object corresponding to generator objects.
@end deffn

@geindex PyGen_Check (C function)
@anchor{c-api/gen c PyGen_Check}@anchor{581a}
@deffn {C Συνάρτηση} 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{581b}
@deffn {C Συνάρτηση} int PyGen_CheckExact (PyObject *ob)

Return true if `ob'’s type is @ref{5819,,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{5816}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyGen_New (PyFrameObject *frame)
`Επιστρεφόμενη τιμή: New reference.'
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{5817}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyGen_NewWithQualName (PyFrameObject *frame, PyObject *name, PyObject *qualname)
`Επιστρεφόμενη τιμή: New reference.'
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

@geindex PyGen_GetCode (C function)
@anchor{c-api/gen c PyGen_GetCode}@anchor{581c}
@deffn {C Συνάρτηση} @ref{b59,,PyCodeObject} *PyGen_GetCode (PyGenObject *gen)

Return a new @ref{7da,,strong reference} to the code object wrapped by `gen'.
This function always succeeds.
@end deffn

@menu
* Asynchronous Generator Objects:: 
* Deprecated API: Deprecated API<4>. 

@end menu

@node Asynchronous Generator Objects,Deprecated API<4>,,Generator Objects
@anchor{c-api/gen asynchronous-generator-objects}@anchor{581d}
@subsubsection Asynchronous Generator Objects



@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/}


@geindex PyAsyncGen_Type (C var)
@anchor{c-api/gen c PyAsyncGen_Type}@anchor{581e}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyAsyncGen_Type

The type object corresponding to asynchronous generator objects. This is
available as @ref{2bf8,,types.AsyncGeneratorType} in the Python layer.


Added in version 3.6.

@end deffn

@geindex PyAsyncGen_New (C function)
@anchor{c-api/gen c PyAsyncGen_New}@anchor{581f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyAsyncGen_New (PyFrameObject *frame, PyObject *name, PyObject *qualname)

Create a new asynchronous generator wrapping `frame', with @code{__name__} and
@code{__qualname__} set to `name' and `qualname'. `frame' is stolen by this
function and must not be @code{NULL}.

On success, this function returns a @ref{7da,,strong reference} to the
new asynchronous generator. On failure, this function returns @code{NULL}
with an exception set.


Added in version 3.6.

@end deffn

@geindex PyAsyncGen_CheckExact (C function)
@anchor{c-api/gen c PyAsyncGen_CheckExact}@anchor{5820}
@deffn {C Συνάρτηση} int PyAsyncGen_CheckExact (PyObject *op)

Return true if `op' is an asynchronous generator object, false otherwise.
This function always succeeds.


Added in version 3.6.

@end deffn

@node Deprecated API<4>,,Asynchronous Generator Objects,Generator Objects
@anchor{c-api/gen deprecated-api}@anchor{5821}
@subsubsection Deprecated API


@geindex PyAsyncGenASend_CheckExact (C macro)
@anchor{c-api/gen c PyAsyncGenASend_CheckExact}@anchor{5822}
@deffn {C Μακροεντολή} PyAsyncGenASend_CheckExact (op)

This is an API that was included in Python’s C API
by mistake.

It is solely here for completeness; do not use this API.


@ref{1a7,,Soft deprecated} since version 3.14.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Coroutine Objects,Context Variables Objects,Generator Objects,Other Objects
@anchor{c-api/coro doc}@anchor{5823}@anchor{c-api/coro coro-objects}@anchor{127e}@anchor{c-api/coro coroutine-objects}@anchor{5824}@anchor{c-api/coro translation-repo}@anchor{5825}
@subsubsection Coroutine Objects



Added in version 3.5.


Coroutine objects are what functions declared with an @code{async} keyword
return.

@geindex PyCoroObject (C type)
@anchor{c-api/coro c PyCoroObject}@anchor{5826}
@deffn {C Τύπος} type PyCoroObject

The C structure used for coroutine objects.
@end deffn

@geindex PyCoro_Type (C var)
@anchor{c-api/coro c PyCoro_Type}@anchor{5827}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyCoro_Type

The type object corresponding to coroutine objects.
@end deffn

@geindex PyCoro_CheckExact (C function)
@anchor{c-api/coro c PyCoro_CheckExact}@anchor{5828}
@deffn {C Συνάρτηση} int PyCoro_CheckExact (PyObject *ob)

Return true if `ob'’s type is @ref{5827,,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{5829}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCoro_New (PyFrameObject *frame, PyObject *name, PyObject *qualname)
`Επιστρεφόμενη τιμή: New reference.'
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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Context Variables Objects,Objects for Type Hinting,Coroutine Objects,Other Objects
@anchor{c-api/contextvars doc}@anchor{582a}@anchor{c-api/contextvars context-variables-objects}@anchor{582b}@anchor{c-api/contextvars contextvarsobjects}@anchor{ebe}@anchor{c-api/contextvars translation-repo}@anchor{582c}
@subsubsection Context Variables Objects

@anchor{c-api/contextvars contextvarsobjects-pointertype-change}@anchor{fe3}

Added in version 3.7.



Άλλαξε στην έκδοση 3.7.1: 

@cartouche
@quotation Σημείωση 
In Python 3.7.1 the signatures of all context variables
C APIs were `changed' to use @ref{19b,,PyObject} pointers instead
of @ref{582d,,PyContext}, @ref{582e,,PyContextVar}, and
@ref{582f,,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{28,,contextvars} module.

@geindex PyContext (C type)
@anchor{c-api/contextvars c PyContext}@anchor{582d}
@deffn {C Τύπος} type PyContext

The C structure used to represent a @ref{421,,contextvars.Context}
object.
@end deffn

@geindex PyContextVar (C type)
@anchor{c-api/contextvars c PyContextVar}@anchor{582e}
@deffn {C Τύπος} type PyContextVar

The C structure used to represent a @ref{1a9d,,contextvars.ContextVar}
object.
@end deffn

@geindex PyContextToken (C type)
@anchor{c-api/contextvars c PyContextToken}@anchor{582f}
@deffn {C Τύπος} type PyContextToken

The C structure used to represent a @ref{479,,contextvars.Token} object.
@end deffn

@geindex PyContext_Type (C var)
@anchor{c-api/contextvars c PyContext_Type}@anchor{5830}
@deffn {C Μεταβλητή} @ref{e6b,,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{5831}
@deffn {C Μεταβλητή} @ref{e6b,,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{5832}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyContextToken_Type

The type object representing the `context variable token' type.
@end deffn

Type-check macros:

@geindex PyContext_CheckExact (C function)
@anchor{c-api/contextvars c PyContext_CheckExact}@anchor{5833}
@deffn {C Συνάρτηση} int PyContext_CheckExact (PyObject *o)

Return true if `o' is of type @ref{5830,,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{5834}
@deffn {C Συνάρτηση} int PyContextVar_CheckExact (PyObject *o)

Return true if `o' is of type @ref{5831,,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{5835}
@deffn {C Συνάρτηση} int PyContextToken_CheckExact (PyObject *o)

Return true if `o' is of type @ref{5832,,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{5836}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyContext_New (void)
`Επιστρεφόμενη τιμή: New reference.'
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{5837}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyContext_Copy (PyObject *ctx)
`Επιστρεφόμενη τιμή: New reference.'
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{5838}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyContext_CopyCurrent (void)
`Επιστρεφόμενη τιμή: New reference.'
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{5839}
@deffn {C Συνάρτηση} 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{583a}
@deffn {C Συνάρτηση} 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

@geindex PyContext_AddWatcher (C function)
@anchor{c-api/contextvars c PyContext_AddWatcher}@anchor{1b9f}
@deffn {C Συνάρτηση} int PyContext_AddWatcher (PyContext_WatchCallback callback)

Register `callback' as a context object watcher for the current interpreter.
Return an ID which may be passed to @ref{1ba0,,PyContext_ClearWatcher()}.
In case of error (e.g. no more watcher IDs available),
return @code{-1} and set an exception.


Added in version 3.14.

@end deffn

@geindex PyContext_ClearWatcher (C function)
@anchor{c-api/contextvars c PyContext_ClearWatcher}@anchor{1ba0}
@deffn {C Συνάρτηση} int PyContext_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' previously returned from
@ref{1b9f,,PyContext_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.)


Added in version 3.14.

@end deffn

@geindex PyContextEvent (C type)
@anchor{c-api/contextvars c PyContextEvent}@anchor{583b}
@deffn {C Τύπος} type PyContextEvent

Enumeration of possible context object watcher events:


@itemize -

@item 
@code{Py_CONTEXT_SWITCHED}: The @ref{1b77,,current context} has switched to a
different context.  The object passed to the watch callback is the
now-current @ref{421,,contextvars.Context} object, or None if no context is
current.
@end itemize


Added in version 3.14.

@end deffn

@geindex PyContext_WatchCallback (C type)
@anchor{c-api/contextvars c PyContext_WatchCallback}@anchor{583c}
@deffn {C Τύπος} typedef int (*PyContext_WatchCallback)(@ref{583b,,PyContextEvent} event, @ref{19b,,PyObject} *obj)

Context object watcher callback function.  The object passed to the callback
is event-specific; see @ref{583b,,PyContextEvent} for details.

If the callback returns with an exception set, it must return @code{-1}; this
exception will be printed as an unraisable exception using
@ref{7e7,,PyErr_FormatUnraisable()}. 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.


Added in version 3.14.

@end deffn

Context variable functions:

@geindex PyContextVar_New (C function)
@anchor{c-api/contextvars c PyContextVar_New}@anchor{583d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyContextVar_New (const char *name, PyObject *def)
`Επιστρεφόμενη τιμή: New reference.'
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{583e}
@deffn {C Συνάρτηση} 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{583f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyContextVar_Set (PyObject *var, PyObject *value)
`Επιστρεφόμενη τιμή: New reference.'
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{5840}
@deffn {C Συνάρτηση} int PyContextVar_Reset (PyObject *var, PyObject *token)

Reset the state of the `var' context variable to that it was in before
@ref{583f,,PyContextVar_Set()} that returned the `token' was called.
This function returns @code{0} on success and @code{-1} on error.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Objects for Type Hinting,,Context Variables Objects,Other Objects
@anchor{c-api/typehints doc}@anchor{5841}@anchor{c-api/typehints objects-for-type-hinting}@anchor{5842}@anchor{c-api/typehints translation-repo}@anchor{5843}@anchor{c-api/typehints typehintobjects}@anchor{5844}
@subsubsection Objects for Type Hinting


Various built-in types for type hinting are provided.  Currently,
two types exist – @ref{a9f,,GenericAlias} and
@ref{ba2,,Union}.  Only @code{GenericAlias} is exposed to C.

@geindex Py_GenericAlias (C function)
@anchor{c-api/typehints c Py_GenericAlias}@anchor{546f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *Py_GenericAlias (PyObject *origin, PyObject *args)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.9.'
Create a @ref{a9f,,GenericAlias} object.
Equivalent to calling the Python class
@ref{bc7,,types.GenericAlias}.  The `origin' and `args' arguments set the
@code{GenericAlias}“s @code{__origin__} and @code{__args__} attributes respectively.
`origin' should be a @ref{e6b,,PyTypeObject}*, and `args' can be a
@ref{5580,,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 Δείτε επίσης


The data model method @ref{b21,,__class_getitem__()}.



Added in version 3.9.

@end deffn

@geindex Py_GenericAliasType (C var)
@anchor{c-api/typehints c Py_GenericAliasType}@anchor{5470}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} Py_GenericAliasType
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.9.'
The C type of the object returned by @ref{546f,,Py_GenericAlias()}. Equivalent to
@ref{bc7,,types.GenericAlias} in Python.


Added in version 3.9.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node C API for extension modules,,Other Objects,Concrete Objects Layer
@anchor{c-api/concrete c-api-for-extension-modules}@anchor{5845}
@subsection C API for extension modules


@menu
* Curses C API:: 
* Internal data:: 
* DateTime Objects: DateTime Objects<2>. 
* Internal data: Internal data<2>. 

@end menu

@node Curses C API,Internal data,,C API for extension modules
@anchor{c-api/curses doc}@anchor{5846}@anchor{c-api/curses curses-c-api}@anchor{5847}
@subsubsection Curses C API


@ref{2e,,curses} exposes a small C interface for extension modules.
Consumers must include the header file @code{py_curses.h} (which is not
included by default by @code{Python.h}) and @ref{5848,,import_curses()} must
be invoked, usually as part of the module initialisation function, to populate
@ref{5849,,PyCurses_API}.

@cartouche
@quotation Προειδοποίηση 
Neither the C API nor the pure Python @ref{2e,,curses} module are compatible
with subinterpreters.
@end quotation
@end cartouche

@geindex import_curses (C macro)
@anchor{c-api/curses c import_curses}@anchor{5848}
@deffn {C Μακροεντολή} import_curses ()

Import the curses C API. The macro does not need a semi-colon to be called.

On success, populate the @ref{5849,,PyCurses_API} pointer.

On failure, set @ref{5849,,PyCurses_API} to NULL and set an exception.
The caller must check if an error occurred via @ref{1ea5,,PyErr_Occurred()}:

@example
import_curses();  // semi-colon is optional but recommended
if (PyErr_Occurred()) @{ /* cleanup */ @}
@end example
@end deffn

@geindex PyCurses_API (C var)
@anchor{c-api/curses c PyCurses_API}@anchor{5849}
@deffn {C Μεταβλητή} void **PyCurses_API

Dynamically allocated object containing the curses C API.
This variable is only available once @ref{5848,,import_curses} succeeds.

@code{PyCurses_API[0]} corresponds to @ref{584a,,PyCursesWindow_Type}.

@code{PyCurses_API[1]}, @code{PyCurses_API[2]}, and @code{PyCurses_API[3]}
are pointers to predicate functions of type @code{int (*)(void)}.

When called, these predicates return whether @ref{36fb,,curses.setupterm()},
@ref{1a1b,,curses.initscr()}, and @ref{36fc,,curses.start_color()} have been called
respectively.

See also the convenience macros @ref{584b,,PyCursesSetupTermCalled},
@ref{584c,,PyCursesInitialised}, and @ref{584d,,PyCursesInitialisedColor}.

@cartouche
@quotation Σημείωση 
The number of entries in this structure is subject to changes.
Consider using @ref{584e,,PyCurses_API_pointers} to check if
new fields are available or not.
@end quotation
@end cartouche
@end deffn

@geindex PyCurses_API_pointers (C macro)
@anchor{c-api/curses c PyCurses_API_pointers}@anchor{584e}
@deffn {C Μακροεντολή} PyCurses_API_pointers

The number of accessible fields (@code{4}) in @ref{5849,,PyCurses_API}.
This number is incremented whenever new fields are added.
@end deffn

@geindex PyCursesWindow_Type (C var)
@anchor{c-api/curses c PyCursesWindow_Type}@anchor{584a}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyCursesWindow_Type

The @ref{d2f,,heap type} corresponding to @ref{1442,,curses.window}.
@end deffn

@geindex PyCursesWindow_Check (C function)
@anchor{c-api/curses c PyCursesWindow_Check}@anchor{584f}
@deffn {C Συνάρτηση} int PyCursesWindow_Check (PyObject *op)

Return true if `op' is a @ref{1442,,curses.window} instance, false otherwise.
@end deffn

The following macros are convenience macros expanding into C statements.
In particular, they can only be used as @code{macro;} or @code{macro}, but not
@code{macro()} or @code{macro();}.

@geindex PyCursesSetupTermCalled (C macro)
@anchor{c-api/curses c PyCursesSetupTermCalled}@anchor{584b}
@deffn {C Μακροεντολή} PyCursesSetupTermCalled

Macro checking if @ref{36fb,,curses.setupterm()} has been called.

The macro expansion is roughly equivalent to:

@example
@{
    typedef int (*predicate_t)(void);
    predicate_t was_setupterm_called = (predicate_t)PyCurses_API[1];
    if (!was_setupterm_called()) @{
        return NULL;
    @}
@}
@end example
@end deffn

@geindex PyCursesInitialised (C macro)
@anchor{c-api/curses c PyCursesInitialised}@anchor{584c}
@deffn {C Μακροεντολή} PyCursesInitialised

Macro checking if @ref{1a1b,,curses.initscr()} has been called.

The macro expansion is roughly equivalent to:

@example
@{
    typedef int (*predicate_t)(void);
    predicate_t was_initscr_called = (predicate_t)PyCurses_API[2];
    if (!was_initscr_called()) @{
        return NULL;
    @}
@}
@end example
@end deffn

@geindex PyCursesInitialisedColor (C macro)
@anchor{c-api/curses c PyCursesInitialisedColor}@anchor{584d}
@deffn {C Μακροεντολή} PyCursesInitialisedColor

Macro checking if @ref{36fc,,curses.start_color()} has been called.

The macro expansion is roughly equivalent to:

@example
@{
    typedef int (*predicate_t)(void);
    predicate_t was_start_color_called = (predicate_t)PyCurses_API[3];
    if (!was_start_color_called()) @{
        return NULL;
    @}
@}
@end example
@end deffn

@node Internal data,DateTime Objects<2>,Curses C API,C API for extension modules
@anchor{c-api/curses internal-data}@anchor{5850}
@subsubsection Internal data


The following objects are exposed by the C API but should be considered
internal-only.

@geindex PyCurses_CAPSULE_NAME (C macro)
@anchor{c-api/curses c PyCurses_CAPSULE_NAME}@anchor{5851}
@deffn {C Μακροεντολή} PyCurses_CAPSULE_NAME

Name of the curses capsule to pass to @ref{1e07,,PyCapsule_Import()}.

Internal usage only. Use @ref{5848,,import_curses} instead.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node DateTime Objects<2>,Internal data<2>,Internal data,C API for extension modules
@anchor{c-api/datetime doc}@anchor{5852}@anchor{c-api/datetime datetime-objects}@anchor{5853}@anchor{c-api/datetime datetimeobjects}@anchor{55cf}@anchor{c-api/datetime translation-repo}@anchor{5854}
@subsubsection DateTime Objects


Various date and time objects are supplied by the @ref{33,,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 @ref{39f,,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, @ref{5855,,PyDateTimeAPI}, that is used by the following
macros.

@geindex PyDateTime_IMPORT (C macro)
@anchor{c-api/datetime c PyDateTime_IMPORT}@anchor{39f}
@deffn {C Μακροεντολή} PyDateTime_IMPORT ()

Import the datetime C API.

On success, populate the @ref{5855,,PyDateTimeAPI} pointer.
On failure, set @code{PyDateTimeAPI} to @code{NULL} and set an exception.
The caller must check if an error occurred via @ref{1ea5,,PyErr_Occurred()}:

@example
PyDateTime_IMPORT;
if (PyErr_Occurred()) @{ /* cleanup */ @}
@end example

@cartouche
@quotation Προειδοποίηση 
This is not compatible with subinterpreters.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.15: This macro is now thread safe.

@end deffn

@geindex PyDateTime_CAPI (C type)
@anchor{c-api/datetime c PyDateTime_CAPI}@anchor{5856}
@deffn {C Τύπος} type PyDateTime_CAPI

Structure containing the fields for the datetime C API.

The fields of this structure are private and subject to change.

Do not use this directly; prefer @code{PyDateTime_*} APIs instead.
@end deffn

@geindex PyDateTimeAPI (C var)
@anchor{c-api/datetime c PyDateTimeAPI}@anchor{5855}
@deffn {C Μεταβλητή} @ref{5856,,PyDateTime_CAPI} *PyDateTimeAPI

Dynamically allocated object containing the datetime C API.

This variable is only available once @ref{39f,,PyDateTime_IMPORT} succeeds.


Άλλαξε στην έκδοση 3.15: This variable should not be accessed directly as direct access is not thread-safe.
Use @ref{39f,,PyDateTime_IMPORT()} instead.

@end deffn

@geindex PyDateTime_Date (C type)
@anchor{c-api/datetime c PyDateTime_Date}@anchor{5857}
@deffn {C Τύπος} type PyDateTime_Date

This subtype of @ref{19b,,PyObject} represents a Python date object.
@end deffn

@geindex PyDateTime_DateTime (C type)
@anchor{c-api/datetime c PyDateTime_DateTime}@anchor{5858}
@deffn {C Τύπος} type PyDateTime_DateTime

This subtype of @ref{19b,,PyObject} represents a Python datetime object.
@end deffn

@geindex PyDateTime_Time (C type)
@anchor{c-api/datetime c PyDateTime_Time}@anchor{5859}
@deffn {C Τύπος} type PyDateTime_Time

This subtype of @ref{19b,,PyObject} represents a Python time object.
@end deffn

@geindex PyDateTime_Delta (C type)
@anchor{c-api/datetime c PyDateTime_Delta}@anchor{585a}
@deffn {C Τύπος} type PyDateTime_Delta

This subtype of @ref{19b,,PyObject} represents the difference between two datetime values.
@end deffn

@geindex PyDateTime_DateType (C var)
@anchor{c-api/datetime c PyDateTime_DateType}@anchor{585b}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDateTime_DateType

This instance of @ref{e6b,,PyTypeObject} represents the Python date type;
it is the same object as @ref{48d,,datetime.date} in the Python layer.
@end deffn

@geindex PyDateTime_DateTimeType (C var)
@anchor{c-api/datetime c PyDateTime_DateTimeType}@anchor{585c}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDateTime_DateTimeType

This instance of @ref{e6b,,PyTypeObject} represents the Python datetime type;
it is the same object as @ref{6e7,,datetime.datetime} in the Python layer.
@end deffn

@geindex PyDateTime_TimeType (C var)
@anchor{c-api/datetime c PyDateTime_TimeType}@anchor{585d}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDateTime_TimeType

This instance of @ref{e6b,,PyTypeObject} represents the Python time type;
it is the same object as @ref{48e,,datetime.time} in the Python layer.
@end deffn

@geindex PyDateTime_DeltaType (C var)
@anchor{c-api/datetime c PyDateTime_DeltaType}@anchor{585e}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDateTime_DeltaType

This instance of @ref{e6b,,PyTypeObject} represents the Python type for
the difference between two datetime values;
it is the same object as @ref{d94,,datetime.timedelta} in the Python layer.
@end deffn

@geindex PyDateTime_TZInfoType (C var)
@anchor{c-api/datetime c PyDateTime_TZInfoType}@anchor{585f}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyDateTime_TZInfoType

This instance of @ref{e6b,,PyTypeObject} represents the Python time zone info type;
it is the same object as @ref{9d8,,datetime.tzinfo} in the Python layer.
@end deffn

Macro for access to the UTC singleton:

@geindex PyDateTime_TimeZone_UTC (C var)
@anchor{c-api/datetime c PyDateTime_TimeZone_UTC}@anchor{f81}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} *PyDateTime_TimeZone_UTC

Returns the time zone singleton representing UTC, the same object as
@ref{a07,,datetime.timezone.utc}.


Added in version 3.7.

@end deffn

Type-check macros:

@geindex PyDate_Check (C function)
@anchor{c-api/datetime c PyDate_Check}@anchor{5860}
@deffn {C Συνάρτηση} int PyDate_Check (PyObject *ob)

Return true if `ob' is of type @ref{585b,,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{5861}
@deffn {C Συνάρτηση} int PyDate_CheckExact (PyObject *ob)

Return true if `ob' is of type @ref{585b,,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{5862}
@deffn {C Συνάρτηση} int PyDateTime_Check (PyObject *ob)

Return true if `ob' is of type @ref{585c,,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{5863}
@deffn {C Συνάρτηση} int PyDateTime_CheckExact (PyObject *ob)

Return true if `ob' is of type @ref{585c,,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{5864}
@deffn {C Συνάρτηση} int PyTime_Check (PyObject *ob)

Return true if `ob' is of type @ref{585d,,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{5865}
@deffn {C Συνάρτηση} int PyTime_CheckExact (PyObject *ob)

Return true if `ob' is of type @ref{585d,,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{5866}
@deffn {C Συνάρτηση} int PyDelta_Check (PyObject *ob)

Return true if `ob' is of type @ref{585e,,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{5867}
@deffn {C Συνάρτηση} int PyDelta_CheckExact (PyObject *ob)

Return true if `ob' is of type @ref{585e,,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{5868}
@deffn {C Συνάρτηση} int PyTZInfo_Check (PyObject *ob)

Return true if `ob' is of type @ref{585f,,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{5869}
@deffn {C Συνάρτηση} int PyTZInfo_CheckExact (PyObject *ob)

Return true if `ob' is of type @ref{585f,,PyDateTime_TZInfoType}. `ob' must not be
@code{NULL}.  This function always succeeds.
@end deffn

Macros to create objects:

@geindex PyDate_FromDate (C function)
@anchor{c-api/datetime c PyDate_FromDate}@anchor{586a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDate_FromDate (int year, int month, int day)
`Επιστρεφόμενη τιμή: New reference.'
Return a @ref{48d,,datetime.date} object with the specified year, month and day.
@end deffn

@geindex PyDateTime_FromDateAndTime (C function)
@anchor{c-api/datetime c PyDateTime_FromDateAndTime}@anchor{586b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDateTime_FromDateAndTime (int year, int month, int day, int hour, int minute, int second, int usecond)
`Επιστρεφόμενη τιμή: New reference.'
Return a @ref{6e7,,datetime.datetime} object with the specified year, month, day, hour,
minute, second and microsecond.
@end deffn

@geindex PyDateTime_FromDateAndTimeAndFold (C function)
@anchor{c-api/datetime c PyDateTime_FromDateAndTimeAndFold}@anchor{586c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDateTime_FromDateAndTimeAndFold (int year, int month, int day, int hour, int minute, int second, int usecond, int fold)
`Επιστρεφόμενη τιμή: New reference.'
Return a @ref{6e7,,datetime.datetime} object with the specified year, month, day, hour,
minute, second, microsecond and fold.


Added in version 3.6.

@end deffn

@geindex PyTime_FromTime (C function)
@anchor{c-api/datetime c PyTime_FromTime}@anchor{586d}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyTime_FromTime (int hour, int minute, int second, int usecond)
`Επιστρεφόμενη τιμή: New reference.'
Return a @ref{48e,,datetime.time} object with the specified hour, minute, second and
microsecond.
@end deffn

@geindex PyTime_FromTimeAndFold (C function)
@anchor{c-api/datetime c PyTime_FromTimeAndFold}@anchor{586e}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyTime_FromTimeAndFold (int hour, int minute, int second, int usecond, int fold)
`Επιστρεφόμενη τιμή: New reference.'
Return a @ref{48e,,datetime.time} object with the specified hour, minute, second,
microsecond and fold.


Added in version 3.6.

@end deffn

@geindex PyDelta_FromDSU (C function)
@anchor{c-api/datetime c PyDelta_FromDSU}@anchor{586f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDelta_FromDSU (int days, int seconds, int useconds)
`Επιστρεφόμενη τιμή: New reference.'
Return a @ref{d94,,datetime.timedelta} object representing the given number
of days, seconds and microseconds.  Normalization is performed so that the
resulting number of microseconds and seconds lie in the ranges documented for
@code{datetime.timedelta} objects.
@end deffn

@geindex PyTimeZone_FromOffset (C function)
@anchor{c-api/datetime c PyTimeZone_FromOffset}@anchor{f7f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyTimeZone_FromOffset (PyObject *offset)
`Επιστρεφόμενη τιμή: New reference.'
Return a @ref{146c,,datetime.timezone} object with an unnamed fixed offset
represented by the `offset' argument.


Added in version 3.7.

@end deffn

@geindex PyTimeZone_FromOffsetAndName (C function)
@anchor{c-api/datetime c PyTimeZone_FromOffsetAndName}@anchor{f80}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyTimeZone_FromOffsetAndName (PyObject *offset, PyObject *name)
`Επιστρεφόμενη τιμή: New reference.'
Return a @ref{146c,,datetime.timezone} object with a fixed offset represented
by the `offset' argument and with tzname `name'.


Added in version 3.7.

@end deffn

Macros to extract fields from date objects.  The argument must be an instance of
@ref{5857,,PyDateTime_Date}, including subclasses (such as
@ref{5858,,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{5870}
@deffn {C Συνάρτηση} int PyDateTime_GET_YEAR (PyDateTime_Date *o)

Return the year, as a positive int.
@end deffn

@geindex PyDateTime_GET_MONTH (C function)
@anchor{c-api/datetime c PyDateTime_GET_MONTH}@anchor{5871}
@deffn {C Συνάρτηση} int PyDateTime_GET_MONTH (PyDateTime_Date *o)

Return the month, as an int from 1 through 12.
@end deffn

@geindex PyDateTime_GET_DAY (C function)
@anchor{c-api/datetime c PyDateTime_GET_DAY}@anchor{5872}
@deffn {C Συνάρτηση} int PyDateTime_GET_DAY (PyDateTime_Date *o)

Return the day, as an int from 1 through 31.
@end deffn

Macros to extract fields from datetime objects.  The argument must be an
instance of @ref{5858,,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{5873}
@deffn {C Συνάρτηση} int PyDateTime_DATE_GET_HOUR (PyDateTime_DateTime *o)

Return the hour, as an int from 0 through 23.
@end deffn

@geindex PyDateTime_DATE_GET_MINUTE (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_MINUTE}@anchor{5874}
@deffn {C Συνάρτηση} int PyDateTime_DATE_GET_MINUTE (PyDateTime_DateTime *o)

Return the minute, as an int from 0 through 59.
@end deffn

@geindex PyDateTime_DATE_GET_SECOND (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_SECOND}@anchor{5875}
@deffn {C Συνάρτηση} int PyDateTime_DATE_GET_SECOND (PyDateTime_DateTime *o)

Return the second, as an int from 0 through 59.
@end deffn

@geindex PyDateTime_DATE_GET_MICROSECOND (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_MICROSECOND}@anchor{5876}
@deffn {C Συνάρτηση} int PyDateTime_DATE_GET_MICROSECOND (PyDateTime_DateTime *o)

Return the microsecond, as an int from 0 through 999999.
@end deffn

@geindex PyDateTime_DATE_GET_FOLD (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_FOLD}@anchor{5877}
@deffn {C Συνάρτηση} int PyDateTime_DATE_GET_FOLD (PyDateTime_DateTime *o)

Return the fold, as an int from 0 through 1.


Added in version 3.6.

@end deffn

@geindex PyDateTime_DATE_GET_TZINFO (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_TZINFO}@anchor{c6b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDateTime_DATE_GET_TZINFO (PyDateTime_DateTime *o)

Return the tzinfo (which may be @code{None}).


Added in version 3.10.

@end deffn

Macros to extract fields from time objects.  The argument must be an instance of
@ref{5859,,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{5878}
@deffn {C Συνάρτηση} int PyDateTime_TIME_GET_HOUR (PyDateTime_Time *o)

Return the hour, as an int from 0 through 23.
@end deffn

@geindex PyDateTime_TIME_GET_MINUTE (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_MINUTE}@anchor{5879}
@deffn {C Συνάρτηση} int PyDateTime_TIME_GET_MINUTE (PyDateTime_Time *o)

Return the minute, as an int from 0 through 59.
@end deffn

@geindex PyDateTime_TIME_GET_SECOND (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_SECOND}@anchor{587a}
@deffn {C Συνάρτηση} int PyDateTime_TIME_GET_SECOND (PyDateTime_Time *o)

Return the second, as an int from 0 through 59.
@end deffn

@geindex PyDateTime_TIME_GET_MICROSECOND (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_MICROSECOND}@anchor{587b}
@deffn {C Συνάρτηση} int PyDateTime_TIME_GET_MICROSECOND (PyDateTime_Time *o)

Return the microsecond, as an int from 0 through 999999.
@end deffn

@geindex PyDateTime_TIME_GET_FOLD (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_FOLD}@anchor{587c}
@deffn {C Συνάρτηση} int PyDateTime_TIME_GET_FOLD (PyDateTime_Time *o)

Return the fold, as an int from 0 through 1.


Added in version 3.6.

@end deffn

@geindex PyDateTime_TIME_GET_TZINFO (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_TZINFO}@anchor{c6c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDateTime_TIME_GET_TZINFO (PyDateTime_Time *o)

Return the tzinfo (which may be @code{None}).


Added in version 3.10.

@end deffn

Macros to extract fields from time delta objects.  The argument must be an
instance of @ref{585a,,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{587d}
@deffn {C Συνάρτηση} int PyDateTime_DELTA_GET_DAYS (PyDateTime_Delta *o)

Return the number of days, as an int from -999999999 to 999999999.


Added in version 3.3.

@end deffn

@geindex PyDateTime_DELTA_GET_SECONDS (C function)
@anchor{c-api/datetime c PyDateTime_DELTA_GET_SECONDS}@anchor{587e}
@deffn {C Συνάρτηση} int PyDateTime_DELTA_GET_SECONDS (PyDateTime_Delta *o)

Return the number of seconds, as an int from 0 through 86399.


Added in version 3.3.

@end deffn

@geindex PyDateTime_DELTA_GET_MICROSECONDS (C function)
@anchor{c-api/datetime c PyDateTime_DELTA_GET_MICROSECONDS}@anchor{587f}
@deffn {C Συνάρτηση} int PyDateTime_DELTA_GET_MICROSECONDS (PyDateTime_Delta *o)

Return the number of microseconds, as an int from 0 through 999999.


Added in version 3.3.

@end deffn

Macros for the convenience of modules implementing the DB API:

@geindex PyDateTime_FromTimestamp (C function)
@anchor{c-api/datetime c PyDateTime_FromTimestamp}@anchor{5880}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDateTime_FromTimestamp (PyObject *args)
`Επιστρεφόμενη τιμή: New reference.'
Create and return a new @ref{6e7,,datetime.datetime} object given an argument
tuple suitable for passing to @ref{8fb,,datetime.datetime.fromtimestamp()}.
@end deffn

@geindex PyDate_FromTimestamp (C function)
@anchor{c-api/datetime c PyDate_FromTimestamp}@anchor{1fe0}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyDate_FromTimestamp (PyObject *args)
`Επιστρεφόμενη τιμή: New reference.'
Create and return a new @ref{48d,,datetime.date} object given an argument
tuple suitable for passing to @ref{f92,,datetime.date.fromtimestamp()}.
@end deffn

@node Internal data<2>,,DateTime Objects<2>,C API for extension modules
@anchor{c-api/datetime internal-data}@anchor{5881}
@subsubsection Internal data


The following symbols are exposed by the C API but should be considered
internal-only.

@geindex PyDateTime_CAPSULE_NAME (C macro)
@anchor{c-api/datetime c PyDateTime_CAPSULE_NAME}@anchor{5882}
@deffn {C Μακροεντολή} PyDateTime_CAPSULE_NAME

Name of the datetime capsule to pass to @ref{1e07,,PyCapsule_Import()}.

Internal usage only. Use @ref{39f,,PyDateTime_IMPORT} instead.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Interpreter initialization and finalization,Thread states and the global interpreter lock,Concrete Objects Layer,Python/C API reference manual
@anchor{c-api/interp-lifecycle doc}@anchor{5883}@anchor{c-api/interp-lifecycle initialization}@anchor{5884}@anchor{c-api/interp-lifecycle interpreter-initialization-and-finalization}@anchor{5885}@anchor{c-api/interp-lifecycle translation-repo}@anchor{5886}
@section Interpreter initialization and finalization


See @ref{837,,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:: 
* Cautions regarding interpreter finalization:: 
* Interpreter views:: 
* Process-wide parameters:: 

@end menu

@node Before Python initialization,Global configuration variables,,Interpreter initialization and finalization
@anchor{c-api/interp-lifecycle before-python-initialization}@anchor{5887}@anchor{c-api/interp-lifecycle pre-init-safe}@anchor{f83}
@subsection Before Python initialization


In an application embedding Python, the @ref{673,,Py_Initialize()} function must
be called before using any other Python/C API functions; with the exception of
a few functions and the @ref{5888,,global configuration variables}.

The following functions can be safely called before Python is initialized:


@itemize *

@item 
Functions that initialize the interpreter:


@itemize *

@item 
@ref{673,,Py_Initialize()}

@item 
@ref{5477,,Py_InitializeEx()}

@item 
@ref{60a,,Py_InitializeFromConfig()}

@item 
@ref{d89,,Py_BytesMain()}

@item 
@ref{fe2,,Py_Main()}

@item 
the runtime pre-initialization functions covered in @ref{837,,Python Initialization Configuration}
@end itemize

@item 
Configuration functions:


@itemize *

@item 
@ref{1d1a,,PyImport_AppendInittab()}

@item 
@ref{1d1b,,PyImport_ExtendInittab()}

@item 
@code{PyInitFrozenExtensions()}

@item 
@ref{98a,,PyMem_SetAllocator()}

@item 
@ref{1028,,PyMem_SetupDebugHooks()}

@item 
@ref{5889,,PyObject_SetArenaAllocator()}

@item 
@ref{1bc0,,Py_SetProgramName()}

@item 
@ref{1bbf,,Py_SetPythonHome()}

@item 
the configuration functions covered in @ref{837,,Python Initialization Configuration}
@end itemize

@item 
Informative functions:


@itemize *

@item 
@ref{191f,,Py_IsInitialized()}

@item 
@ref{588a,,PyMem_GetAllocator()}

@item 
@ref{588b,,PyObject_GetArenaAllocator()}

@item 
@ref{17d4,,Py_GetBuildInfo()}

@item 
@ref{5471,,Py_GetCompiler()}

@item 
@ref{5472,,Py_GetCopyright()}

@item 
@ref{5473,,Py_GetPlatform()}

@item 
@ref{5475,,Py_GetVersion()}

@item 
@ref{191f,,Py_IsInitialized()}
@end itemize

@item 
Utilities:


@itemize *

@item 
@ref{f85,,Py_DecodeLocale()}

@item 
the status reporting and utility functions covered in @ref{837,,Python Initialization Configuration}
@end itemize

@item 
Memory allocators:


@itemize *

@item 
@ref{2bf,,PyMem_RawMalloc()}

@item 
@ref{825,,PyMem_RawRealloc()}

@item 
@ref{824,,PyMem_RawCalloc()}

@item 
@ref{826,,PyMem_RawFree()}
@end itemize

@item 
Synchronization:


@itemize *

@item 
@ref{7c9,,PyMutex_Lock()}

@item 
@ref{7ca,,PyMutex_Unlock()}
@end itemize
@end itemize

@cartouche
@quotation Σημείωση 
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{f86,,Py_EncodeLocale()}, @ref{1bc3,,PyEval_InitThreads()}, and
@ref{d8d,,Py_RunMain()}.
@end quotation
@end cartouche

@node Global configuration variables,Initializing and finalizing the interpreter,Before Python initialization,Interpreter initialization and finalization
@anchor{c-api/interp-lifecycle global-conf-vars}@anchor{5888}@anchor{c-api/interp-lifecycle global-configuration-variables}@anchor{588c}
@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{230a,,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{61a,,Py_BytesWarningFlag}
to 1 and @code{-bb} sets @code{Py_BytesWarningFlag} to 2.

@geindex Py_BytesWarningFlag (C var)
@anchor{c-api/interp-lifecycle c Py_BytesWarningFlag}@anchor{61a}
@deffn {C Μεταβλητή} int Py_BytesWarningFlag

This API is kept for backward compatibility: setting
@ref{3c4,,PyConfig.bytes_warning} should be used instead, see @ref{837,,Python Initialization Configuration}.

Issue a warning when comparing @ref{1c7,,bytes} or @ref{1c6,,bytearray} with
@ref{1df,,str} or @code{bytes} with @ref{326,,int}.  Issue an error if greater
or equal to @code{2}.

Set by the @ref{2ed,,-b} option.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_DebugFlag (C var)
@anchor{c-api/interp-lifecycle c Py_DebugFlag}@anchor{60c}
@deffn {C Μεταβλητή} int Py_DebugFlag

This API is kept for backward compatibility: setting
@ref{60d,,PyConfig.parser_debug} should be used instead, see @ref{837,,Python Initialization Configuration}.

Turn on parser debugging output (for expert only, depending on compilation
options).

Set by the @ref{2312,,-d} option and the 
@geindex PYTHONDEBUG
@geindex μεταβλητή περιβάλλοντος; PYTHONDEBUG
@ref{2313,,PYTHONDEBUG} environment
variable.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_DontWriteBytecodeFlag (C var)
@anchor{c-api/interp-lifecycle c Py_DontWriteBytecodeFlag}@anchor{61f}
@deffn {C Μεταβλητή} int Py_DontWriteBytecodeFlag

This API is kept for backward compatibility: setting
@ref{620,,PyConfig.write_bytecode} should be used instead, see @ref{837,,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{1770,,-B} option and the 
@geindex PYTHONDONTWRITEBYTECODE
@geindex μεταβλητή περιβάλλοντος; PYTHONDONTWRITEBYTECODE
@ref{1771,,PYTHONDONTWRITEBYTECODE}
environment variable.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_FrozenFlag (C var)
@anchor{c-api/interp-lifecycle c Py_FrozenFlag}@anchor{61b}
@deffn {C Μεταβλητή} int Py_FrozenFlag

This API is kept for backward compatibility: setting
@ref{61c,,PyConfig.pathconfig_warnings} should be used instead, see
@ref{837,,Python Initialization Configuration}.

Private flag used by @code{_freeze_module} and @code{frozenmain} programs.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_HashRandomizationFlag (C var)
@anchor{c-api/interp-lifecycle c Py_HashRandomizationFlag}@anchor{625}
@deffn {C Μεταβλητή} int Py_HashRandomizationFlag

This API is kept for backward compatibility: setting
@ref{627,,PyConfig.hash_seed} and @ref{626,,PyConfig.use_hash_seed} should
be used instead, see @ref{837,,Python Initialization Configuration}.

Set to @code{1} if the 
@geindex PYTHONHASHSEED
@geindex μεταβλητή περιβάλλοντος; PYTHONHASHSEED
@ref{1425,,PYTHONHASHSEED} environment variable is set to
a non-empty string.

If the flag is non-zero, read the 
@geindex PYTHONHASHSEED
@geindex μεταβλητή περιβάλλοντος; PYTHONHASHSEED
@ref{1425,,PYTHONHASHSEED} environment
variable to initialize the secret hash seed.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_IgnoreEnvironmentFlag (C var)
@anchor{c-api/interp-lifecycle c Py_IgnoreEnvironmentFlag}@anchor{61d}
@deffn {C Μεταβλητή} int Py_IgnoreEnvironmentFlag

This API is kept for backward compatibility: setting
@ref{61e,,PyConfig.use_environment} should be used instead, see
@ref{837,,Python Initialization Configuration}.

Ignore all @code{PYTHON*} environment variables, e.g.
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} and 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME}, that might be set.

Set by the @ref{d27,,-E} and @ref{d28,,-I} options.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_InspectFlag (C var)
@anchor{c-api/interp-lifecycle c Py_InspectFlag}@anchor{614}
@deffn {C Μεταβλητή} int Py_InspectFlag

This API is kept for backward compatibility: setting
@ref{615,,PyConfig.inspect} should be used instead, see
@ref{837,,Python Initialization Configuration}.

When a script is passed as first argument or the @ref{445,,-c} option is used,
enter interactive mode after executing the script or the command, even when
@ref{94a,,sys.stdin} does not appear to be a terminal.

Set by the @ref{187d,,-i} option and the 
@geindex PYTHONINSPECT
@geindex μεταβλητή περιβάλλοντος; PYTHONINSPECT
@ref{187c,,PYTHONINSPECT} environment
variable.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_InteractiveFlag (C var)
@anchor{c-api/interp-lifecycle c Py_InteractiveFlag}@anchor{612}
@deffn {C Μεταβλητή} int Py_InteractiveFlag

This API is kept for backward compatibility: setting
@ref{613,,PyConfig.interactive} should be used instead, see
@ref{837,,Python Initialization Configuration}.

Set by the @ref{187d,,-i} option.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_IsolatedFlag (C var)
@anchor{c-api/interp-lifecycle c Py_IsolatedFlag}@anchor{628}
@deffn {C Μεταβλητή} int Py_IsolatedFlag

This API is kept for backward compatibility: setting
@ref{629,,PyConfig.isolated} should be used instead, see
@ref{837,,Python Initialization Configuration}.

Run Python in isolated mode. In isolated mode @ref{194,,sys.path} contains
neither the script’s directory nor the user’s site-packages directory.

Set by the @ref{d28,,-I} option.


Added in version 3.4.



Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_LegacyWindowsFSEncodingFlag (C var)
@anchor{c-api/interp-lifecycle c Py_LegacyWindowsFSEncodingFlag}@anchor{62a}
@deffn {C Μεταβλητή} int Py_LegacyWindowsFSEncodingFlag

This API is kept for backward compatibility: setting
@ref{62b,,PyPreConfig.legacy_windows_fs_encoding} should be used instead, see
@ref{837,,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{948,,filesystem encoding and error handler}.

Set to @code{1} if the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,PYTHONLEGACYWINDOWSFSENCODING} environment
variable is set to a non-empty string.

See 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} for more details.

@ref{232d,,Διαθεσιμότητα}: Windows.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_LegacyWindowsStdioFlag (C var)
@anchor{c-api/interp-lifecycle c Py_LegacyWindowsStdioFlag}@anchor{62c}
@deffn {C Μεταβλητή} int Py_LegacyWindowsStdioFlag

This API is kept for backward compatibility: setting
@ref{62d,,PyConfig.legacy_windows_stdio} should be used instead, see
@ref{837,,Python Initialization Configuration}.

If the flag is non-zero, use @ref{16b4,,io.FileIO} instead of
@code{io._WindowsConsoleIO} for @ref{e2,,sys} standard streams.

Set to @code{1} if the 
@geindex PYTHONLEGACYWINDOWSSTDIO
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSSTDIO
@ref{1019,,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{232d,,Διαθεσιμότητα}: Windows.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_NoSiteFlag (C var)
@anchor{c-api/interp-lifecycle c Py_NoSiteFlag}@anchor{618}
@deffn {C Μεταβλητή} int Py_NoSiteFlag

This API is kept for backward compatibility: setting
@ref{619,,PyConfig.site_import} should be used instead, see
@ref{837,,Python Initialization Configuration}.

Disable the import of the module @ref{cf,,site} and the site-dependent
manipulations of @ref{194,,sys.path} that it entails.  Also disable these
manipulations if @code{site} is explicitly imported later (call
@ref{2316,,site.main()} if you want them to be triggered).

Set by the @ref{1551,,-S} option.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_NoUserSiteDirectory (C var)
@anchor{c-api/interp-lifecycle c Py_NoUserSiteDirectory}@anchor{621}
@deffn {C Μεταβλητή} int Py_NoUserSiteDirectory

This API is kept for backward compatibility: setting
@ref{622,,PyConfig.user_site_directory} should be used instead, see
@ref{837,,Python Initialization Configuration}.

Don’t add the @ref{2315,,user site-packages directory} to
@ref{194,,sys.path}.

Set by the @ref{1732,,-s} and @ref{d28,,-I} options, and the
@geindex PYTHONNOUSERSITE
@geindex μεταβλητή περιβάλλοντος; PYTHONNOUSERSITE
@ref{1733,,PYTHONNOUSERSITE} environment variable.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_OptimizeFlag (C var)
@anchor{c-api/interp-lifecycle c Py_OptimizeFlag}@anchor{616}
@deffn {C Μεταβλητή} int Py_OptimizeFlag

This API is kept for backward compatibility: setting
@ref{617,,PyConfig.optimization_level} should be used instead, see
@ref{837,,Python Initialization Configuration}.

Set by the @ref{431,,-O} option and the 
@geindex PYTHONOPTIMIZE
@geindex μεταβλητή περιβάλλοντος; PYTHONOPTIMIZE
@ref{2314,,PYTHONOPTIMIZE} environment
variable.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_QuietFlag (C var)
@anchor{c-api/interp-lifecycle c Py_QuietFlag}@anchor{610}
@deffn {C Μεταβλητή} int Py_QuietFlag

This API is kept for backward compatibility: setting
@ref{611,,PyConfig.quiet} should be used instead, see @ref{837,,Python Initialization Configuration}.

Don’t display the copyright and version messages even in interactive mode.

Set by the @ref{1994,,-q} option.


Added in version 3.2.



Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_UnbufferedStdioFlag (C var)
@anchor{c-api/interp-lifecycle c Py_UnbufferedStdioFlag}@anchor{623}
@deffn {C Μεταβλητή} int Py_UnbufferedStdioFlag

This API is kept for backward compatibility: setting
@ref{624,,PyConfig.buffered_stdio} should be used instead, see @ref{837,,Python Initialization Configuration}.

Force the stdout and stderr streams to be unbuffered.

Set by the @ref{1f7f,,-u} option and the 
@geindex PYTHONUNBUFFERED
@geindex μεταβλητή περιβάλλοντος; PYTHONUNBUFFERED
@ref{1f80,,PYTHONUNBUFFERED}
environment variable.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_VerboseFlag (C var)
@anchor{c-api/interp-lifecycle c Py_VerboseFlag}@anchor{60e}
@deffn {C Μεταβλητή} int Py_VerboseFlag

This API is kept for backward compatibility: setting
@ref{60f,,PyConfig.verbose} should be used instead, see @ref{837,,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{17c7,,-v} option and the 
@geindex PYTHONVERBOSE
@geindex μεταβλητή περιβάλλοντος; PYTHONVERBOSE
@ref{2317,,PYTHONVERBOSE} environment
variable.


Καταργήθηκε από την έκδοση 3.12, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@node Initializing and finalizing the interpreter,Cautions regarding interpreter finalization,Global configuration variables,Interpreter initialization and finalization
@anchor{c-api/interp-lifecycle initializing-and-finalizing-the-interpreter}@anchor{588d}
@subsection Initializing and finalizing the interpreter


@geindex Py_Initialize (C function)
@anchor{c-api/interp-lifecycle c Py_Initialize}@anchor{673}
@deffn {C Συνάρτηση} void Py_Initialize ()
` Μέρος του @ref{95c,,Σταθερό 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{f83,,Before Python Initialization} for the few exceptions.

This initializes the table of loaded modules (@code{sys.modules}), and creates
the fundamental modules @ref{13,,builtins}, @ref{1,,__main__} and @ref{e2,,sys}.
It also initializes the module search path (@code{sys.path}). It does not set
@code{sys.argv}; use the @ref{837,,Python Initialization Configuration}
API for that. This is a no-op when called for a second time (without calling
@ref{10cf,,Py_FinalizeEx()} first).  There is no return value; it is a fatal
error if the initialization fails.

Use @ref{60a,,Py_InitializeFromConfig()} to customize the
@ref{837,,Python Initialization Configuration}.

@cartouche
@quotation Σημείωση 
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/interp-lifecycle c Py_InitializeEx}@anchor{5477}
@deffn {C Συνάρτηση} void Py_InitializeEx (int initsigs)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This function works like @ref{673,,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{60a,,Py_InitializeFromConfig()} to customize the
@ref{837,,Python Initialization Configuration}.
@end deffn

@geindex Py_InitializeFromConfig (C function)
@anchor{c-api/interp-lifecycle c Py_InitializeFromConfig}@anchor{60a}
@deffn {C Συνάρτηση} @ref{d75,,PyStatus} Py_InitializeFromConfig (const PyConfig *config)

Initialize Python from `config' configuration, as described in
@ref{588e,,Initialization with PyConfig}.

See the @ref{837,,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/interp-lifecycle c Py_IsInitialized}@anchor{191f}
@deffn {C Συνάρτηση} int Py_IsInitialized ()
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return true (nonzero) when the Python interpreter has been initialized, false
(zero) if not.  After @ref{10cf,,Py_FinalizeEx()} is called, this returns false until
@ref{673,,Py_Initialize()} is called again.


Άλλαξε στην έκδοση 3.15: This function no longer returns true until initialization has fully
completed, including import of the @ref{cf,,site} module.  Previously it
could return true while @ref{673,,Py_Initialize()} was still running.

@end deffn

@geindex Py_IsFinalizing (C function)
@anchor{c-api/interp-lifecycle c Py_IsFinalizing}@anchor{7f3}
@deffn {C Συνάρτηση} int Py_IsFinalizing ()
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Return true (non-zero) if the main Python interpreter is
@ref{1a0,,shutting down}. Return false (zero) otherwise.


Added in version 3.13.

@end deffn

@geindex Py_FinalizeEx (C function)
@anchor{c-api/interp-lifecycle c Py_FinalizeEx}@anchor{10cf}
@deffn {C Συνάρτηση} int Py_FinalizeEx ()
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.6.'
Undo all initializations made by @ref{673,,Py_Initialize()} and subsequent use of
Python/C API functions, and destroy all sub-interpreters (see
@ref{1d2f,,Py_NewInterpreter()} below) that were created and not yet destroyed since
the last call to @code{Py_Initialize()}.  This is a no-op when called for a second
time (without calling @code{Py_Initialize()} again first).

Since this is the reverse of @ref{673,,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{d8d,,Py_RunMain()} is running.

Normally the return value is @code{0}.
If there were errors during finalization (flushing buffered data),
@code{-1} is returned.

Note that Python will do a best effort at freeing all memory allocated by the Python
interpreter.  Therefore, any C-Extension should make sure to correctly clean up all
of the previously allocated PyObjects before using them in subsequent calls to
@ref{673,,Py_Initialize()}.  Otherwise it could introduce vulnerabilities and incorrect
behavior.

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{13a6,,__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.  Interned strings will all be deallocated regardless of their reference count.
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{673,,Py_Initialize()} and @ref{10cf,,Py_FinalizeEx()}
more than once.  @code{Py_FinalizeEx()} must not be called recursively from
within itself.  Therefore, it must not be called by any code that may be run
as part of the interpreter shutdown process, such as @ref{d,,atexit}
handlers, object finalizers, or any code that may be run while flushing the
stdout and stderr files.

Raises an @ref{1e65,,auditing event} @code{cpython._PySys_ClearAuditHooks} with no arguments.


Added in version 3.6.

@end deffn

@geindex Py_Finalize (C function)
@anchor{c-api/interp-lifecycle c Py_Finalize}@anchor{672}
@deffn {C Συνάρτηση} void Py_Finalize ()
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is a backwards-compatible version of @ref{10cf,,Py_FinalizeEx()} that
disregards the return value.
@end deffn

@geindex Py_BytesMain (C function)
@anchor{c-api/interp-lifecycle c Py_BytesMain}@anchor{d89}
@deffn {C Συνάρτηση} int Py_BytesMain (int argc, char **argv)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.8.'
Similar to @ref{fe2,,Py_Main()} but `argv' is an array of bytes strings,
allowing the calling application to delegate the text decoding step to
the CPython runtime.


Added in version 3.8.

@end deffn

@geindex Py_Main (C function)
@anchor{c-api/interp-lifecycle c Py_Main}@anchor{fe2}
@deffn {C Συνάρτηση} int Py_Main (int argc, wchar_t **argv)
` Μέρος του @ref{95c,,Σταθερό 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{13b0,,Command line}.

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{f85,,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 is @code{2} if the argument list does not represent a valid
Python command line, and otherwise the same as @ref{d8d,,Py_RunMain()}.

In terms of the CPython runtime configuration APIs documented in the
@ref{837,,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{673,,Py_Initialize()}, @ref{5477,,Py_InitializeEx()} or
@ref{60a,,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/interp-lifecycle c Py_RunMain}@anchor{d8d}
@deffn {C Συνάρτηση} int Py_RunMain (void)

Executes the main module in a fully configured CPython runtime.

Executes the command (@ref{588f,,PyConfig.run_command}), the script
(@ref{5890,,PyConfig.run_filename}) or the module
(@ref{5891,,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{615,,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), the exit status of an unhandled @ref{10f7,,SystemExit}, or @code{1}
for any other unhandled exception.

If @ref{615,,PyConfig.inspect} is set (such as when the @ref{187d,,-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: @code{0}, @code{1}, or
the status of a @ref{10f7,,SystemExit}, as specified above.

This function always finalizes the Python interpreter before it returns.

See @ref{5892,,Python Configuration} for an example of a
customized Python that always runs in isolated mode using
@ref{d8d,,Py_RunMain()}.
@end deffn

@geindex PyUnstable_AtExit (C function)
@anchor{c-api/interp-lifecycle c PyUnstable_AtExit}@anchor{1b19}
@deffn {C Συνάρτηση} int PyUnstable_AtExit (PyInterpreterState *interp, void (*func)(void*), void *data)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Register an @ref{d,,atexit} callback for the target interpreter `interp'.
This is similar to @ref{5468,,Py_AtExit()}, but takes an explicit interpreter and
data pointer for the callback.

There must be an @ref{1a1,,attached thread state} for `interp'.


Added in version 3.13.

@end deffn

@node Cautions regarding interpreter finalization,Interpreter views,Initializing and finalizing the interpreter,Interpreter initialization and finalization
@anchor{c-api/interp-lifecycle cautions-regarding-interpreter-finalization}@anchor{5893}@anchor{c-api/interp-lifecycle cautions-regarding-runtime-finalization}@anchor{5894}
@subsection Cautions regarding interpreter finalization


In the late stage of @ref{1a0,,interpreter shutdown}, after attempting to wait for
non-daemon threads to exit (though this can be interrupted by
@ref{d96,,KeyboardInterrupt}) and running the @ref{d,,atexit} functions, the runtime
is marked as finalizing, meaning that @ref{7f3,,Py_IsFinalizing()} and
@ref{e4f,,sys.is_finalizing()} return true.  At this point, only the finalization
thread (the thread that initiated finalization; this is typically the main thread)
is allowed to @ref{1a1,,attach} a thread state.

Other threads that attempt to attach during finalization, either explicitly
(such as via @ref{53fd,,PyThreadState_Ensure()} or @ref{e4e,,Py_END_ALLOW_THREADS})
or implicitly (such as in-between bytecode instructions), will enter a
`permanently blocked state'. Generally, this is harmless, but this can
result in deadlocks. For example, a thread may be permanently blocked while
holding a lock, meaning that the finalization thread can never acquire that
lock.

Prior to CPython 3.13, the thread would exit instead of hanging,
which led to other issues (see the warning note at
@ref{5407,,PyThread_exit_thread()}).

Gross? Yes. Starting in Python 3.15, there are a number of C APIs that make
it possible to avoid these issues by temporarily preventing finalization:
@anchor{c-api/interp-lifecycle interpreter-guards}@anchor{1a2}

@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 788
PEP 788@footnote{https://peps.python.org/pep-0788/} explains the design, motivation and rationale
for these APIs.


@geindex PyInterpreterGuard (C type)
@anchor{c-api/interp-lifecycle c PyInterpreterGuard}@anchor{5365}
@deffn {C Τύπος} type PyInterpreterGuard
` Μέρος του @ref{95c,,Σταθερό ABI} (ως μια αδιαφανής κατασκευή) από την έκδοση 3.15.'
An opaque interpreter guard structure.

By holding an interpreter guard, the caller can ensure that the interpreter
will not finalize until the guard is closed (through
@ref{5366,,PyInterpreterGuard_Close()}).

When a guard is held, a thread attempting to finalize the interpreter will
block until the guard is closed before starting finalization.
After finalization has started, threads are forever unable to acquire
guards for that interpreter. This means that if you forget to close an
interpreter guard, the process will `permanently hang' during
finalization!

Holding a guard for an interpreter is similar to holding a
@ref{7da,,strong reference} to a Python object, except finalization does not happen
automatically after all guards are released: it requires an explicit
@ref{1a6f,,Py_EndInterpreter()} call.


Added in version 3.15.

@end deffn

@geindex PyInterpreterGuard_FromCurrent (C function)
@anchor{c-api/interp-lifecycle c PyInterpreterGuard_FromCurrent}@anchor{5367}
@deffn {C Συνάρτηση} @ref{5365,,PyInterpreterGuard} *PyInterpreterGuard_FromCurrent (void)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Create a finalization guard for the current interpreter. This will prevent
finalization until the guard is closed.

For example:

@example
// Temporarily prevent finalization.
PyInterpreterGuard *guard = PyInterpreterGuard_FromCurrent();
if (guard == NULL) @{
   // Finalization has already started or we're out of memory.
   return NULL;
@}

Py_BEGIN_ALLOW_THREADS;
// Do some critical processing here. For example, we can safely acquire
// locks that might be acquired by the finalization thread.
Py_END_ALLOW_THREADS;

// Now that we're done with our critical processing, the interpreter is
// allowed to finalize again.
PyInterpreterGuard_Close(guard);
@end example

On success, this function returns a guard for the current interpreter;
on failure, it returns @code{NULL} with an exception set.

This function will fail only if the current interpreter has already started
finalizing, or if the process is out of memory.

The guard pointer returned by this function must be eventually closed
with @ref{5366,,PyInterpreterGuard_Close()}; failing to do so will result in
the Python process infinitely hanging.

The caller must hold an @ref{1a1,,attached thread state}.


Added in version 3.15.

@end deffn

@geindex PyInterpreterGuard_FromView (C function)
@anchor{c-api/interp-lifecycle c PyInterpreterGuard_FromView}@anchor{5368}
@deffn {C Συνάρτηση} @ref{5365,,PyInterpreterGuard} *PyInterpreterGuard_FromView (PyInterpreterView *view)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Create a finalization guard for an interpreter through a view.

On success, this function returns a guard to the interpreter
represented by `view'. The view is still valid after calling this
function. The guard must eventually be closed with
@ref{5366,,PyInterpreterGuard_Close()}.

If the interpreter no longer exists, is already finalizing, or out of memory,
then this function returns @code{NULL} without setting an exception.

The caller does not need to hold an @ref{1a1,,attached thread state}.


Added in version 3.15.

@end deffn

@geindex PyInterpreterGuard_Close (C function)
@anchor{c-api/interp-lifecycle c PyInterpreterGuard_Close}@anchor{5366}
@deffn {C Συνάρτηση} void PyInterpreterGuard_Close (PyInterpreterGuard *guard)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Close an interpreter guard, allowing the interpreter to start
finalization if no other guards remain. If an interpreter guard
is never closed, the interpreter will infinitely wait when trying
to enter finalization!

After an interpreter guard is closed, it may not be used in
@ref{53fd,,PyThreadState_Ensure()}. Doing so will result in undefined
behavior.

This function cannot fail, and the caller doesn’t need to hold an
@ref{1a1,,attached thread state}.


Added in version 3.15.

@end deffn

@node Interpreter views,Process-wide parameters,Cautions regarding interpreter finalization,Interpreter initialization and finalization
@anchor{c-api/interp-lifecycle id1}@anchor{5895}@anchor{c-api/interp-lifecycle interpreter-views}@anchor{1a3}
@subsection Interpreter views


In some cases, it may be necessary to access an interpreter that may have been
deleted. This can be done using interpreter views.

@geindex PyInterpreterView (C type)
@anchor{c-api/interp-lifecycle c PyInterpreterView}@anchor{536b}
@deffn {C Τύπος} type PyInterpreterView
` Μέρος του @ref{95c,,Σταθερό ABI} (ως μια αδιαφανής κατασκευή) από την έκδοση 3.15.'
An opaque view of an interpreter.

This is a thread-safe way to access an interpreter that may have be
finalizing or already destroyed.


Added in version 3.15.

@end deffn

@geindex PyInterpreterView_FromCurrent (C function)
@anchor{c-api/interp-lifecycle c PyInterpreterView_FromCurrent}@anchor{536d}
@deffn {C Συνάρτηση} @ref{536b,,PyInterpreterView} *PyInterpreterView_FromCurrent (void)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Create a view to the current interpreter.

This function is generally meant to be used alongside
@ref{5368,,PyInterpreterGuard_FromView()} or @ref{53fe,,PyThreadState_EnsureFromView()}.

On success, this function returns a view to the current interpreter; on
failure, it returns @code{NULL} with an exception set.

The caller must hold an @ref{1a1,,attached thread state}.


Added in version 3.15.

@end deffn

@geindex PyInterpreterView_Close (C function)
@anchor{c-api/interp-lifecycle c PyInterpreterView_Close}@anchor{536c}
@deffn {C Συνάρτηση} void PyInterpreterView_Close (PyInterpreterView *view)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Close an interpreter view.

If an interpreter view is never closed, the view’s memory will never be
freed, but there are no other consequences. (In contrast, forgetting to
close a guard will infinitely hang the main thread during finalization.)

This function cannot fail, and the caller doesn’t need to hold an
@ref{1a1,,attached thread state}.


Added in version 3.15.

@end deffn

@geindex PyInterpreterView_FromMain (C function)
@anchor{c-api/interp-lifecycle c PyInterpreterView_FromMain}@anchor{536e}
@deffn {C Συνάρτηση} @ref{536b,,PyInterpreterView} *PyInterpreterView_FromMain (void)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Create a view for the main interpreter (the first and default
interpreter in a Python process; see
@ref{5896,,PyInterpreterState_Main()}).

On success, this function returns a view to the main
interpreter; on failure, it returns @code{NULL} without an exception set.
Failure indicates that the process is out of memory.

Use this function when an interpreter pointer or view cannot be supplied
by the caller, such as when a native threading library does not provide a
@code{void *arg} parameter that could carry a @ref{5365,,PyInterpreterGuard} or
@ref{536b,,PyInterpreterView}. In code that supports subinterpreters, prefer
@ref{536d,,PyInterpreterView_FromCurrent()} so the guard tracks the calling
interpreter rather than the main one.

The caller does not need to hold an @ref{1a1,,attached thread state}.


Added in version 3.15.

@end deffn

@node Process-wide parameters,,Interpreter views,Interpreter initialization and finalization
@anchor{c-api/interp-lifecycle process-wide-parameters}@anchor{5897}
@subsection Process-wide parameters


@geindex Py_SetProgramName (C function)
@anchor{c-api/interp-lifecycle c Py_SetProgramName}@anchor{1bc0}
@deffn {C Συνάρτηση} void Py_SetProgramName (const wchar_t *name)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex Py_Initialize()
@geindex main()

This API is kept for backward compatibility: setting
@ref{608,,PyConfig.program_name} should be used instead, see @ref{837,,Python Initialization Configuration}.

This function should be called before @ref{673,,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 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{f85,,Py_DecodeLocale()} to decode a bytes string to get a
wchar_t* string.


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_GetVersion (C function)
@anchor{c-api/interp-lifecycle c Py_GetVersion}@anchor{5475}
@deffn {C Συνάρτηση} const char *Py_GetVersion ()
` Μέρος του @ref{95c,,Σταθερό 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{6a8,,sys.version}.

See also the @ref{5ae,,Py_Version} constant.
@end deffn

@geindex Py_GetPlatform (C function)
@anchor{c-api/interp-lifecycle c Py_GetPlatform}@anchor{5473}
@deffn {C Συνάρτηση} const char *Py_GetPlatform ()
` Μέρος του @ref{95c,,Σταθερό 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/interp-lifecycle c Py_GetCopyright}@anchor{5472}
@deffn {C Συνάρτηση} const char *Py_GetCopyright ()
` Μέρος του @ref{95c,,Σταθερό 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/interp-lifecycle c Py_GetCompiler}@anchor{5471}
@deffn {C Συνάρτηση} const char *Py_GetCompiler ()
` Μέρος του @ref{95c,,Σταθερό 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/interp-lifecycle c Py_GetBuildInfo}@anchor{17d4}
@deffn {C Συνάρτηση} const char *Py_GetBuildInfo ()
` Μέρος του @ref{95c,,Σταθερό 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/interp-lifecycle c PySys_SetArgvEx}@anchor{1bc1}
@deffn {C Συνάρτηση} void PySys_SetArgvEx (int argc, wchar_t **argv, int updatepath)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex main()
@geindex Py_FatalError()
@geindex argv (in module sys)

This API is kept for backward compatibility: setting
@ref{607,,PyConfig.argv}, @ref{1ee6,,PyConfig.parse_argv} and
@ref{b55,,PyConfig.safe_path} should be used instead, see @ref{837,,Python Initialization Configuration}.

Set @ref{1609,,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 @code{sys.argv}, a fatal
condition is signalled using @ref{d4b,,Py_FatalError()}.

If `updatepath' is zero, this is all the function does.  If `updatepath'
is non-zero, the function also modifies @ref{194,,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{194,,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{194,,sys.path}, which is the same as prepending the current working
directory (@code{"."}).
@end itemize

Use @ref{f85,,Py_DecodeLocale()} to decode a bytes string to get a
wchar_t* string.

See also @ref{c6a,,PyConfig.orig_argv} and @ref{607,,PyConfig.argv}
members of the @ref{837,,Python Initialization Configuration}.

@cartouche
@quotation Σημείωση 
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{194,,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{194,,sys.path} element after having called
@ref{1bc2,,PySys_SetArgv()}, for example using:

@example
PyRun_SimpleString("import sys; sys.path.pop(0)\n");
@end example
@end quotation
@end cartouche


Added in version 3.1.3.



Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex PySys_SetArgv (C function)
@anchor{c-api/interp-lifecycle c PySys_SetArgv}@anchor{1bc2}
@deffn {C Συνάρτηση} void PySys_SetArgv (int argc, wchar_t **argv)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This API is kept for backward compatibility: setting
@ref{607,,PyConfig.argv} and @ref{1ee6,,PyConfig.parse_argv} should be used
instead, see @ref{837,,Python Initialization Configuration}.

This function works like @ref{1bc1,,PySys_SetArgvEx()} with `updatepath' set
to @code{1} unless the @code{python} interpreter was started with the
@ref{d28,,-I}.

Use @ref{f85,,Py_DecodeLocale()} to decode a bytes string to get a
wchar_t* string.

See also @ref{c6a,,PyConfig.orig_argv} and @ref{607,,PyConfig.argv}
members of the @ref{837,,Python Initialization Configuration}.


Άλλαξε στην έκδοση 3.4: The `updatepath' value depends on @ref{d28,,-I}.



Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@geindex Py_SetPythonHome (C function)
@anchor{c-api/interp-lifecycle c Py_SetPythonHome}@anchor{1bbf}
@deffn {C Συνάρτηση} void Py_SetPythonHome (const wchar_t *home)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This API is kept for backward compatibility: setting
@ref{609,,PyConfig.home} should be used instead, see @ref{837,,Python Initialization Configuration}.

Set the default «home» directory, that is, the location of the standard
Python libraries.  See 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,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{f85,,Py_DecodeLocale()} to decode a bytes string to get a
wchar_t* string.


Καταργήθηκε από την έκδοση 3.11, αφαιρέθηκε στην έκδοση 3.15.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Thread states and the global interpreter lock,Asynchronous notifications,Interpreter initialization and finalization,Python/C API reference manual
@anchor{c-api/threads doc}@anchor{5898}@anchor{c-api/threads thread-states-and-the-global-interpreter-lock}@anchor{5899}@anchor{c-api/threads threads}@anchor{589a}@anchor{c-api/threads translation-repo}@anchor{589b}
@section Thread states and the global interpreter lock


@geindex global interpreter lock
@geindex interpreter lock
@geindex lock@comma{} interpreter

Unless on a @ref{198,,free-threaded build} of @ref{ae3,,CPython},
the Python interpreter is generally not thread-safe.  In order to support
multi-threaded Python programs, there’s a global lock, called the @ref{685,,global interpreter lock} or @ref{411,,GIL}, that must be held by a thread before
accessing 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.

As such, only a thread that holds the GIL may operate on Python objects or
invoke Python’s C API.

@geindex setswitchinterval (in module sys)

In order to emulate concurrency, the interpreter regularly tries to switch
threads between bytecode instructions (see @ref{d16,,sys.setswitchinterval()}).
This is why locks are also necessary for thread-safety in pure-Python code.

Additionally, the global interpreter lock is released around blocking I/O
operations, such as reading or writing to a file. From the C API, this is done
by @ref{589c,,detaching the thread state}.

@geindex PyThreadState (C type)

The Python interpreter keeps some thread-local information inside
a data structure called @ref{b6c,,PyThreadState}, known as a @ref{1a70,,thread state}.
Each thread has a thread-local pointer to a @code{PyThreadState}; a thread state
referenced by this pointer is considered to be @ref{1a1,,attached}.

A thread can only have one @ref{1a1,,attached thread state} at a time. An attached
thread state is typically analogous with holding the GIL, except on
free-threaded builds.  On builds with the GIL enabled, attaching a thread state
will block until the GIL can be acquired. However, even on builds with the GIL
disabled, it is still required to have an attached thread state, as the interpreter
needs to keep track of which threads may access Python objects.

@cartouche
@quotation Σημείωση 
Even on the free-threaded build, attaching a thread state may block, as the
GIL can be re-enabled or threads might be temporarily suspended (such as during
a garbage collection).
@end quotation
@end cartouche

Generally, there will always be an attached thread state when using Python’s
C API, including during embedding and when implementing methods, so it’s uncommon
to need to set up a thread state on your own. Only in some specific cases, such
as in a @ref{51d4,,Py_BEGIN_ALLOW_THREADS} block or in a fresh thread, will the
thread not have an attached thread state.
If uncertain, check if @ref{636,,PyThreadState_GetUnchecked()} returns @code{NULL}.

If it turns out that you do need to create a thread state, it is recommended to
use @ref{53fd,,PyThreadState_Ensure()} or @ref{53fe,,PyThreadState_EnsureFromView()},
which will manage the thread state for you.

@menu
* Detaching the thread state from extension code:: 
* Using the C API from foreign threads:: 
* GIL-state APIs:: 
* Cautions about fork(): Cautions about fork. 
* High-level APIs:: 
* Low-level APIs:: 

@end menu

@node Detaching the thread state from extension code,Using the C API from foreign threads,,Thread states and the global interpreter lock
@anchor{c-api/threads detaching-the-thread-state-from-extension-code}@anchor{589d}@anchor{c-api/threads detaching-thread-state}@anchor{589c}
@subsection Detaching the thread state from extension code


Most extension code manipulating the @ref{1a70,,thread state} has the following simple
structure:

@example
Save the thread state in a local variable.
... Do some blocking I/O operation ...
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{51d4,,Py_BEGIN_ALLOW_THREADS} macro opens a new block and declares a
hidden local variable; the @ref{e4e,,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 attached thread state implies that the GIL is held for the interpreter.
To detach it, @ref{838,,PyEval_SaveThread()} is called and the result is stored
in a local variable.

By detaching the thread state, the GIL is released, which allows other threads
to attach to the interpreter and execute while the current thread performs
blocking I/O. When the I/O operation is complete, the old thread state is
reattached by calling @ref{839,,PyEval_RestoreThread()}, which will wait until
the GIL can be acquired.

@cartouche
@quotation Σημείωση 
Performing blocking I/O is the most common use case for detaching
the thread state, but it is also useful to call it over long-running
native code that doesn’t need access to Python objects or Python’s C API.
For example, the standard @ref{13c,,zlib} and @ref{6b,,hashlib} modules detach the
@ref{1a1,,thread state} when compressing or hashing
data.
@end quotation
@end cartouche

On a @ref{198,,free-threaded build}, the @ref{411,,GIL} is usually out of the question,
but `detaching the thread state is still required', because the interpreter
periodically needs to block all threads to get a consistent view of Python objects
without the risk of race conditions.
For example, CPython currently suspends all threads for a short period of time
while running the garbage collector.

@cartouche
@quotation Προειδοποίηση 
Detaching the thread state can lead to unexpected behavior during interpreter
finalization. See @ref{5894,,Cautions regarding interpreter finalization} for more
details.
@end quotation
@end cartouche

@menu
* APIs:: 

@end menu

@node APIs,,,Detaching the thread state from extension code
@anchor{c-api/threads apis}@anchor{589e}
@subsubsection APIs


The following macros are normally used without a trailing semicolon; look for
example usage in the Python source distribution.

@cartouche
@quotation Σημείωση 
These macros are still necessary on the @ref{198,,free-threaded build} to prevent
deadlocks.
@end quotation
@end cartouche

@geindex Py_BEGIN_ALLOW_THREADS (C macro)
@anchor{c-api/threads c Py_BEGIN_ALLOW_THREADS}@anchor{51d4}
@deffn {C Μακροεντολή} Py_BEGIN_ALLOW_THREADS
` Μέρος του @ref{95c,,Σταθερό 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{e4e,,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/threads c Py_END_ALLOW_THREADS}@anchor{e4e}
@deffn {C Μακροεντολή} Py_END_ALLOW_THREADS
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This macro expands to @code{PyEval_RestoreThread(_save); @}}. Note that it contains
a closing brace; it must be matched with an earlier
@ref{51d4,,Py_BEGIN_ALLOW_THREADS} macro.  See above for further discussion of
this macro.
@end deffn

@geindex Py_BLOCK_THREADS (C macro)
@anchor{c-api/threads c Py_BLOCK_THREADS}@anchor{546b}
@deffn {C Μακροεντολή} Py_BLOCK_THREADS
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This macro expands to @code{PyEval_RestoreThread(_save);}: it is equivalent to
@ref{e4e,,Py_END_ALLOW_THREADS} without the closing brace.
@end deffn

@geindex Py_UNBLOCK_THREADS (C macro)
@anchor{c-api/threads c Py_UNBLOCK_THREADS}@anchor{548d}
@deffn {C Μακροεντολή} Py_UNBLOCK_THREADS
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This macro expands to @code{_save = PyEval_SaveThread();}: it is equivalent to
@ref{51d4,,Py_BEGIN_ALLOW_THREADS} without the opening brace and variable
declaration.
@end deffn
@anchor{c-api/threads non-python-created-threads}@anchor{589f}
@node Using the C API from foreign threads,GIL-state APIs,Detaching the thread state from extension code,Thread states and the global interpreter lock
@anchor{c-api/threads c-api-foreign-threads}@anchor{58a0}@anchor{c-api/threads using-the-c-api-from-foreign-threads}@anchor{58a1}
@subsection Using the C API from foreign threads


When threads are created using the dedicated Python APIs (such as the
@ref{f6,,threading} module), a thread state is automatically associated with them,
However, when a thread is created from native code (for example, by a
third-party library with its own thread management), it doesn’t hold an
attached thread state.

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 new thread state and attaching it.

The easiest way to do this is through @ref{53fd,,PyThreadState_Ensure()}
or @ref{53fe,,PyThreadState_EnsureFromView()}.

@cartouche
@quotation Σημείωση 
These functions require an argument pointing to the desired
interpreter; such a pointer can be acquired via a call to
@ref{5367,,PyInterpreterGuard_FromCurrent()} (for @code{PyThreadState_Ensure}) or
@ref{536d,,PyInterpreterView_FromCurrent()} (for @code{PyThreadState_EnsureFromView})
from the function that creates the thread. If no pointer is available (such
as when the given native thread library doesn’t provide a data argument),
@ref{536e,,PyInterpreterView_FromMain()} can be used to get a view for the main
interpreter, but note that this will make the code incompatible with
subinterpreters.
@end quotation
@end cartouche

For example:

@example
// The return value of PyInterpreterGuard_FromCurrent() from the
// function that created this thread.
PyInterpreterGuard *guard = thread_data->guard;

// Create a new thread state for the interpreter.
PyThreadStateToken *token = PyThreadState_Ensure(guard);
if (token == NULL) @{
   PyInterpreterGuard_Close(guard);
   return;
@}

// We have a valid thread state -- perform Python actions here.
result = CallSomeFunction();
// Evaluate result or handle exceptions.

// Release the thread state. No calls to the C API are allowed beyond this
// point.
PyThreadState_Release(token);
PyInterpreterGuard_Close(guard);
@end example

Keep in mind that calling @code{PyThreadState_Ensure} might not always create a new
thread state, and calling @code{PyThreadState_Release} might not always detach it.
These functions may reuse an existing attached thread state, or may re-attach
a thread state that was previously attached for the current thread.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 788
PEP 788@footnote{https://peps.python.org/pep-0788/}


@menu
* Attaching/detaching thread states:: 

@end menu

@node Attaching/detaching thread states,,,Using the C API from foreign threads
@anchor{c-api/threads attaching-detaching-thread-states}@anchor{58a2}@anchor{c-api/threads c-api-attach-detach}@anchor{1a4}
@subsubsection Attaching/detaching thread states


@geindex PyThreadState_Ensure (C function)
@anchor{c-api/threads c PyThreadState_Ensure}@anchor{53fd}
@deffn {C Συνάρτηση} @ref{53fc,,PyThreadStateToken} *PyThreadState_Ensure (PyInterpreterGuard *guard)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Ensure that the thread has an attached thread state for the
interpreter protected by `guard', and thus can safely invoke that
interpreter.

It is OK to call this function if the thread already has an
attached thread state, as long as there is a subsequent call to
@ref{5401,,PyThreadState_Release()} that matches this one (meaning that «nested»
calls to this function are permitted).

The function’s effect (if any) will be reversed by the matching call to
@ref{5401,,PyThreadState_Release()}.

On error, this function returns @code{NULL} `without' an exception set.
Do not call @code{PyThreadState_Release()} in this case.

On success, this function returns a pointer value that must be passed
to the matching call to @code{PyThreadState_Release()}.

The conditions in which this function creates a new @ref{1a70,,thread state} are
considered unstable and implementation-dependent. If you need to control the
exact lifetime of a thread state, consider using @ref{5400,,PyThreadState_New()}.
However, do not avoid this function solely on the basis that the lifetime
of the thread state may be inconsistent across versions; changes to this
function will be done with caution and in a backwards-compatible manner.
In particular, the saving of thread-local variables and similar state will
be retained across Python versions.

`Λεπτομέρεια υλοποίησης CPython:' The exact behavior of whether this function creates a new thread state is
described below, but be aware that this may change in the future.

First, this function checks if an attached thread state is present.
If there is, this function then checks if the interpreter of that
thread state matches the interpreter guarded by `guard'. If that is
the case, this function simply marks the thread state as being used
by a @code{PyThreadState_Ensure} call and returns.

If there is no attached thread state, then this function checks if any
thread state has been used by the current OS thread. (This is
returned by @ref{5357,,PyGILState_GetThisThreadState()}.)
If there was, then this function checks if that thread state’s interpreter
matches `guard'. If it does, it is re-attached and marked as used.

Otherwise, if both of the above cases fail, a new thread state is created
for `guard'. It is then attached and marked as owned by @code{PyThreadState_Ensure}.


Added in version 3.15.

@end deffn

@geindex PyThreadState_EnsureFromView (C function)
@anchor{c-api/threads c PyThreadState_EnsureFromView}@anchor{53fe}
@deffn {C Συνάρτηση} @ref{53fc,,PyThreadStateToken} *PyThreadState_EnsureFromView (PyInterpreterView *view)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Get an attached thread state for the interpreter referenced by `view'.

The behavior and return value are the same as for @ref{53fd,,PyThreadState_Ensure()};
additionally, if the function succeeds, the interpreter referenced by `view' will
be implicitly guarded. The guard will be released upon the corresponding
@ref{5401,,PyThreadState_Release()} call.


Added in version 3.15.

@end deffn

@geindex PyThreadState_Release (C function)
@anchor{c-api/threads c PyThreadState_Release}@anchor{5401}
@deffn {C Συνάρτηση} void PyThreadState_Release (PyThreadStateToken *token)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Undo a @ref{53fd,,PyThreadState_Ensure()} or
@ref{53fe,,PyThreadState_EnsureFromView()} call.

This must be called exactly once for each successful `Ensure' call, with
`token' set to that call’s return value.

The state that was attached before the corresponding `Ensure' call
(if any) will be attached when @ref{5401,,PyThreadState_Release()} returns.

The exact behavior of whether this function deletes a thread state is
considered unstable and implementation-dependent.

`Λεπτομέρεια υλοποίησης CPython:' Currently, this function will decrement an internal counter on the
attached thread state. If this counter ever reaches below zero, this
function emits a fatal error (via @ref{d4b,,Py_FatalError()}).

If the attached thread state is owned by @code{PyThreadState_Ensure}, then the
attached thread state will be deallocated and deleted upon the internal counter
reaching zero. Otherwise, nothing happens when the counter reaches zero.


Added in version 3.15.

@end deffn

@geindex PyThreadStateToken (C type)
@anchor{c-api/threads c PyThreadStateToken}@anchor{53fc}
@deffn {C Τύπος} type PyThreadStateToken
` Μέρος του @ref{95c,,Σταθερό ABI} (ως μια αδιαφανής κατασκευή) από την έκδοση 3.15.'
An opaque token retrieved from a @ref{53fd,,PyThreadState_Ensure()} call
and passed to a corresponding @ref{5401,,PyThreadState_Release()} call.
@end deffn
@anchor{c-api/threads legacy-api}@anchor{58a3}
@node GIL-state APIs,Cautions about fork,Using the C API from foreign threads,Thread states and the global interpreter lock
@anchor{c-api/threads gil-state-apis}@anchor{58a4}@anchor{c-api/threads gilstate}@anchor{58a5}
@subsection GIL-state APIs


The following APIs are generally not compatible with subinterpreters and
will hang the process during interpreter finalization (see
@ref{5894,,Cautions regarding interpreter finalization}). As such, these APIs were
@ref{1a7,,soft deprecated} in Python 3.15 in favor of the @ref{58a0,,new APIs}.

@geindex PyGILState_STATE (C type)
@anchor{c-api/threads c PyGILState_STATE}@anchor{5358}
@deffn {C Τύπος} type PyGILState_STATE
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type of the value returned by @ref{1a5,,PyGILState_Ensure()} and passed to
@ref{1a6,,PyGILState_Release()}.

@geindex PyGILState_STATE.PyGILState_LOCKED (C enumerator)
@anchor{c-api/threads c PyGILState_STATE PyGILState_LOCKED}@anchor{58a6}
@deffn {C Enumerator} enumerator PyGILState_LOCKED

The GIL was already held when @ref{1a5,,PyGILState_Ensure()} was called.
@end deffn

@geindex PyGILState_STATE.PyGILState_UNLOCKED (C enumerator)
@anchor{c-api/threads c PyGILState_STATE PyGILState_UNLOCKED}@anchor{58a7}
@deffn {C Enumerator} enumerator PyGILState_UNLOCKED

The GIL was not held when @ref{1a5,,PyGILState_Ensure()} was called.
@end deffn
@end deffn

@geindex PyGILState_Ensure (C function)
@anchor{c-api/threads c PyGILState_Ensure}@anchor{1a5}
@deffn {C Συνάρτηση} @ref{5358,,PyGILState_STATE} PyGILState_Ensure ()
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Ensure that the current thread is ready to call the Python C API regardless
of the current state of Python, or of the @ref{1a1,,attached thread state}. This may
be called as many times as desired by a thread as long as each call is
matched with a call to @ref{1a6,,PyGILState_Release()}. In general, other
thread-related APIs may be used between @ref{1a5,,PyGILState_Ensure()} and
@code{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{51d4,,Py_BEGIN_ALLOW_THREADS} and @ref{e4e,,Py_END_ALLOW_THREADS} macros is
acceptable.

The return value is an opaque «handle» to the @ref{1a1,,attached thread state} when
@ref{1a5,,PyGILState_Ensure()} was called, and must be passed to
@ref{1a6,,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 @code{PyGILState_Ensure()} must save the handle for its call
to @code{PyGILState_Release()}.

When the function returns, there will be an @ref{1a1,,attached thread state}
and the thread will be able to call arbitrary Python code.

This function has no way to return an error. As such, errors are either fatal
(that is, they send @code{SIGABRT} and crash the process; see
@ref{d4b,,Py_FatalError()}), or the thread will be permanently blocked (such as
during interpreter finalization).

@cartouche
@quotation Προειδοποίηση 
Calling this function when the interpreter is finalizing will
infinitely hang the thread, which may cause deadlocks.
@ref{5894,,Cautions regarding interpreter finalization} for more details.

In addition, this function generally does not work with subinterpreters
when used from foreign threads, because this function has no way of
knowing which interpreter created the thread (and as such, will implicitly
pick the main interpreter).
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.14: Hangs the current thread, rather than terminating it, if called while the
interpreter is finalizing.



@ref{1a7,,Soft deprecated} since version 3.15: Use @ref{53fd,,PyThreadState_Ensure()} or
@ref{53fe,,PyThreadState_EnsureFromView()} instead.

@end deffn

@geindex PyGILState_Release (C function)
@anchor{c-api/threads c PyGILState_Release}@anchor{1a6}
@deffn {C Συνάρτηση} void PyGILState_Release (PyGILState_STATE)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Release any resources previously acquired.  After this call, Python’s state will
be the same as it was prior to the corresponding @ref{1a5,,PyGILState_Ensure()} call
(but generally this state will be unknown to the caller, hence the use of the
GIL-state API).

Every call to @ref{1a5,,PyGILState_Ensure()} must be matched by a call to
@ref{1a6,,PyGILState_Release()} on the same thread.


@ref{1a7,,Soft deprecated} since version 3.15: Use @ref{5401,,PyThreadState_Release()} instead.

@end deffn

@geindex PyGILState_GetThisThreadState (C function)
@anchor{c-api/threads c PyGILState_GetThisThreadState}@anchor{5357}
@deffn {C Συνάρτηση} @ref{b6c,,PyThreadState} *PyGILState_GetThisThreadState ()
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Get the @ref{1a70,,thread state} that was most recently @ref{1a1,,attached} for this thread. (If the most recent thread state
has been deleted, this returns @code{NULL}.)

If the caller has an attached thread state, it is returned.

In other terms, this function returns the thread state that will be used by
@ref{1a5,,PyGILState_Ensure()}. If this returns @code{NULL}, then
@code{PyGILState_Ensure} will create a new thread state.

This function cannot fail.


@ref{1a7,,Soft deprecated} since version 3.15: Use @ref{809,,PyThreadState_Get()} or @ref{636,,PyThreadState_GetUnchecked()}
instead.

@end deffn

@geindex PyGILState_Check (C function)
@anchor{c-api/threads c PyGILState_Check}@anchor{58a8}
@deffn {C Συνάρτηση} int PyGILState_Check ()

Return @code{1} if the current thread has an @ref{1a1,,attached thread state}
that matches the thread state returned by
@ref{5357,,PyGILState_GetThisThreadState()}. If the caller has no attached thread
state or it otherwise doesn’t match, then this returns @code{0}.

If the current Python process has ever created a subinterpreter, this
function will `always' return @code{1}.

This is mainly a helper/diagnostic function.


Added in version 3.4.



@ref{1a7,,Soft deprecated} since version 3.15: Use @code{PyThreadState_GetUnchecked() != NULL} instead.

@end deffn

@node Cautions about fork,High-level APIs,GIL-state APIs,Thread states and the global interpreter lock
@anchor{c-api/threads cautions-about-fork}@anchor{58a9}@anchor{c-api/threads fork-and-threads}@anchor{557c}
@subsection 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{6bd,,os.fork()} by acquiring the locks it uses internally before
the fork, and releasing them afterwards. In addition, it resets any
@ref{386c,,Lock objects} 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 @code{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{643,,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{6bd,,os.fork()}
does.  This means finalizing all other @ref{b6c,,PyThreadState} objects
belonging to the current interpreter and all other
@ref{c90,,PyInterpreterState} objects.  Due to this and the special
nature of the @ref{410,,«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 APIs,Low-level APIs,Cautions about fork,Thread states and the global interpreter lock
@anchor{c-api/threads high-level-apis}@anchor{58aa}
@subsection High-level APIs


These are the most commonly used types and functions when writing multi-threaded
C extensions.

@geindex PyThreadState (C type)
@anchor{c-api/threads c PyThreadState}@anchor{b6c}
@deffn {C Τύπος} type PyThreadState
` Μέρος του @ref{95c,,Σταθερό ABI} (ως μια αδιαφανής κατασκευή).'
This data structure represents the state of a single thread.  The only public
data member is:

@geindex PyThreadState.interp (C member)
@anchor{c-api/threads c PyThreadState interp}@anchor{58ab}
@deffn {C Μέλος} @ref{c90,,PyInterpreterState} *interp

This thread’s interpreter state.
@end deffn
@end deffn

@geindex PyEval_InitThreads (C function)
@anchor{c-api/threads c PyEval_InitThreads}@anchor{1bc3}
@deffn {C Συνάρτηση} void PyEval_InitThreads ()
` Μέρος του @ref{95c,,Σταθερό 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.


Άλλαξε στην έκδοση 3.9: The function now does nothing.



Άλλαξε στην έκδοση 3.7: This function is now called by @ref{673,,Py_Initialize()}, so you don’t
have to call it yourself anymore.



Άλλαξε στην έκδοση 3.2: This function cannot be called before @ref{673,,Py_Initialize()} anymore.



Αποσύρθηκε στην έκδοση 3.9.


@geindex module; _thread
@end deffn

@geindex PyEval_SaveThread (C function)
@anchor{c-api/threads c PyEval_SaveThread}@anchor{838}
@deffn {C Συνάρτηση} @ref{b6c,,PyThreadState} *PyEval_SaveThread ()
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Detach the @ref{1a1,,attached thread state} and return it.
The thread will have no @ref{1a70,,thread state} upon returning.
@end deffn

@geindex PyEval_RestoreThread (C function)
@anchor{c-api/threads c PyEval_RestoreThread}@anchor{839}
@deffn {C Συνάρτηση} void PyEval_RestoreThread (PyThreadState *tstate)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Set the @ref{1a1,,attached thread state} to `tstate'.
The passed @ref{1a70,,thread state} `should not' be attached,
otherwise deadlock ensues. `tstate' will be attached upon returning.

@cartouche
@quotation Σημείωση 
Calling this function from a thread when the runtime is finalizing will
hang the thread until the program exits, even if the thread was not
created by Python.  Refer to
@ref{5894,,Cautions regarding interpreter finalization} for more details.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.14: Hangs the current thread, rather than terminating it, if called while the
interpreter is finalizing.

@end deffn

@geindex PyThreadState_Get (C function)
@anchor{c-api/threads c PyThreadState_Get}@anchor{809}
@deffn {C Συνάρτηση} @ref{b6c,,PyThreadState} *PyThreadState_Get ()
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the @ref{1a1,,attached thread state}. If the thread has no attached
thread state, (such as when inside of @ref{51d4,,Py_BEGIN_ALLOW_THREADS}
block), then this issues a fatal error (so that the caller needn’t check
for @code{NULL}).

See also @ref{636,,PyThreadState_GetUnchecked()}.
@end deffn

@geindex PyThreadState_GetUnchecked (C function)
@anchor{c-api/threads c PyThreadState_GetUnchecked}@anchor{636}
@deffn {C Συνάρτηση} @ref{b6c,,PyThreadState} *PyThreadState_GetUnchecked ()

Similar to @ref{809,,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.


Added in 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/threads c PyThreadState_Swap}@anchor{5402}
@deffn {C Συνάρτηση} @ref{b6c,,PyThreadState} *PyThreadState_Swap (PyThreadState *tstate)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Set the @ref{1a1,,attached thread state} to `tstate', and return the
@ref{1a70,,thread state} that was attached prior to calling.

This function is safe to call without an @ref{1a1,,attached thread state}; it
will simply return @code{NULL} indicating that there was no prior thread state.


@subsubheading Δείτε επίσης


@ref{5308,,PyEval_ReleaseThread()}


@cartouche
@quotation Σημείωση 
Similar to @ref{1a5,,PyGILState_Ensure()}, this function will hang the
thread if the runtime is finalizing.
@end quotation
@end cartouche
@end deffn

@node Low-level APIs,,High-level APIs,Thread states and the global interpreter lock
@anchor{c-api/threads low-level-apis}@anchor{58ac}
@subsection Low-level APIs


@geindex PyThreadState_New (C function)
@anchor{c-api/threads c PyThreadState_New}@anchor{5400}
@deffn {C Συνάρτηση} @ref{b6c,,PyThreadState} *PyThreadState_New (PyInterpreterState *interp)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a new thread state object belonging to the given interpreter object.
An @ref{1a1,,attached thread state} is not needed.
@end deffn

@geindex PyThreadState_Clear (C function)
@anchor{c-api/threads c PyThreadState_Clear}@anchor{1b9e}
@deffn {C Συνάρτηση} void PyThreadState_Clear (PyThreadState *tstate)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Reset all information in a @ref{1a70,,thread state} object.  `tstate'
must be @ref{1a1,,attached}


Άλλαξε στην έκδοση 3.9: This function now calls the @code{PyThreadState.on_delete} callback.
Previously, that happened in @ref{1f7b,,PyThreadState_Delete()}.



Άλλαξε στην έκδοση 3.13: The @code{PyThreadState.on_delete} callback was removed.

@end deffn

@geindex PyThreadState_Delete (C function)
@anchor{c-api/threads c PyThreadState_Delete}@anchor{1f7b}
@deffn {C Συνάρτηση} void PyThreadState_Delete (PyThreadState *tstate)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Destroy a @ref{1a70,,thread state} object.  `tstate' should not
be @ref{1a1,,attached} to any thread.
`tstate' must have been reset with a previous call to
@ref{1b9e,,PyThreadState_Clear()}.
@end deffn

@geindex PyThreadState_DeleteCurrent (C function)
@anchor{c-api/threads c PyThreadState_DeleteCurrent}@anchor{1fa8}
@deffn {C Συνάρτηση} void PyThreadState_DeleteCurrent (void)

Detach the @ref{1a1,,attached thread state} (which must have been reset
with a previous call to @ref{1b9e,,PyThreadState_Clear()}) and then destroy it.

No @ref{1a70,,thread state} will be @ref{1a1,,attached} upon
returning.
@end deffn

@geindex PyThreadState_GetFrame (C function)
@anchor{c-api/threads c PyThreadState_GetFrame}@anchor{b6d}
@deffn {C Συνάρτηση} @ref{b68,,PyFrameObject} *PyThreadState_GetFrame (PyThreadState *tstate)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Get the current frame of the Python thread state `tstate'.

Return a @ref{7da,,strong reference}. Return @code{NULL} if no frame is currently
executing.

See also @ref{1d37,,PyEval_GetFrame()}.

`tstate' must not be @code{NULL}, and must be @ref{1a1,,attached}.


Added in version 3.9.

@end deffn

@geindex PyThreadState_GetID (C function)
@anchor{c-api/threads c PyThreadState_GetID}@anchor{d3b}
@deffn {C Συνάρτηση} uint64_t PyThreadState_GetID (PyThreadState *tstate)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Get the unique @ref{1a70,,thread state} identifier of the Python thread state `tstate'.

`tstate' must not be @code{NULL}, and must be @ref{1a1,,attached}.


Added in version 3.9.

@end deffn

@geindex PyThreadState_GetInterpreter (C function)
@anchor{c-api/threads c PyThreadState_GetInterpreter}@anchor{d3a}
@deffn {C Συνάρτηση} @ref{c90,,PyInterpreterState} *PyThreadState_GetInterpreter (PyThreadState *tstate)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Get the interpreter of the Python thread state `tstate'.

`tstate' must not be @code{NULL}, and must be @ref{1a1,,attached}.


Added in version 3.9.

@end deffn

@geindex PyThreadState_EnterTracing (C function)
@anchor{c-api/threads c PyThreadState_EnterTracing}@anchor{b38}
@deffn {C Συνάρτηση} void PyThreadState_EnterTracing (PyThreadState *tstate)

Suspend tracing and profiling in the Python thread state `tstate'.

Resume them using the @ref{b39,,PyThreadState_LeaveTracing()} function.


Added in version 3.11.

@end deffn

@geindex PyThreadState_LeaveTracing (C function)
@anchor{c-api/threads c PyThreadState_LeaveTracing}@anchor{b39}
@deffn {C Συνάρτηση} void PyThreadState_LeaveTracing (PyThreadState *tstate)

Resume tracing and profiling in the Python thread state `tstate' suspended
by the @ref{b38,,PyThreadState_EnterTracing()} function.

See also @ref{850,,PyEval_SetTrace()} and @ref{189f,,PyEval_SetProfile()}
functions.


Added in version 3.11.

@end deffn

@geindex PyUnstable_ThreadState_SetStackProtection (C function)
@anchor{c-api/threads c PyUnstable_ThreadState_SetStackProtection}@anchor{395}
@deffn {C Συνάρτηση} int PyUnstable_ThreadState_SetStackProtection (PyThreadState *tstate, void *stack_start_addr, size_t stack_size)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Set the stack protection start address and stack protection size
of a Python thread state.

On success, return @code{0}.
On failure, set an exception and return @code{-1}.

CPython implements @ref{5549,,recursion control} for C code by raising
@ref{1121,,RecursionError} when it notices that the machine execution stack is close
to overflow. See for example the @ref{5fe,,Py_EnterRecursiveCall()} function.
For this, it needs to know the location of the current thread’s stack, which it
normally gets from the operating system.
When the stack is changed, for example using context switching techniques like the
Boost library’s @code{boost::context}, you must call
@ref{395,,PyUnstable_ThreadState_SetStackProtection()} to inform CPython of the change.

Call @ref{395,,PyUnstable_ThreadState_SetStackProtection()} either before
or after changing the stack.
Do not call any other Python C API between the call and the stack
change.

See @ref{396,,PyUnstable_ThreadState_ResetStackProtection()} for undoing this operation.


Added in version 3.15.

@end deffn

@geindex PyUnstable_ThreadState_ResetStackProtection (C function)
@anchor{c-api/threads c PyUnstable_ThreadState_ResetStackProtection}@anchor{396}
@deffn {C Συνάρτηση} void PyUnstable_ThreadState_ResetStackProtection (PyThreadState *tstate)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Reset the stack protection start address and stack protection size
of a Python thread state to the operating system defaults.

See @ref{395,,PyUnstable_ThreadState_SetStackProtection()} for an explanation.


Added in version 3.15.

@end deffn

@geindex PyThreadState_GetDict (C function)
@anchor{c-api/threads c PyThreadState_GetDict}@anchor{53ff}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyThreadState_GetDict ()
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό 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 @ref{1a70,,thread state}
is @ref{1a1,,attached}. If this function returns
@code{NULL}, no exception has been raised and the caller should assume no
thread state is attached.
@end deffn

@geindex PyEval_AcquireThread (C function)
@anchor{c-api/threads c PyEval_AcquireThread}@anchor{83a}
@deffn {C Συνάρτηση} void PyEval_AcquireThread (PyThreadState *tstate)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@ref{1a1,,Attach} `tstate' to the current thread,
which must not be @code{NULL} or already attached.

The calling thread must not already have an @ref{1a1,,attached thread state}.

@cartouche
@quotation Σημείωση 
Calling this function from a thread when the runtime is finalizing will
hang the thread until the program exits, even if the thread was not
created by Python.  Refer to
@ref{5894,,Cautions regarding interpreter finalization} for more details.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.8: Updated to be consistent with @ref{839,,PyEval_RestoreThread()},
@ref{e4e,,Py_END_ALLOW_THREADS()}, and @ref{1a5,,PyGILState_Ensure()},
and terminate the current thread if called while the interpreter is finalizing.



Άλλαξε στην έκδοση 3.14: Hangs the current thread, rather than terminating it, if called while the
interpreter is finalizing.


@ref{839,,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/threads c PyEval_ReleaseThread}@anchor{5308}
@deffn {C Συνάρτηση} void PyEval_ReleaseThread (PyThreadState *tstate)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Detach the @ref{1a1,,attached thread state}.
The `tstate' argument, which must not be @code{NULL}, is only used to check
that it represents the attached thread state — if it isn’t, a fatal error is
reported.

@ref{838,,PyEval_SaveThread()} is a higher-level function which is always
available (even when threads have not been initialized).
@end deffn

@node Asynchronous notifications,Operating system thread APIs,Thread states and the global interpreter lock,Python/C API reference manual
@anchor{c-api/threads asynchronous-notifications}@anchor{58ad}
@section 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/threads c Py_AddPendingCall}@anchor{d49}
@deffn {C Συνάρτηση} int Py_AddPendingCall (int (*func)(void*), void *arg)
` Μέρος του @ref{95c,,Σταθερό 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{6b3,,bytecode} boundary;

@item 
with the main thread holding an @ref{1a1,,attached thread state}
(`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 @ref{1a1,,thread state} is detached.

This function doesn’t need an @ref{1a1,,attached thread state}. However, to call this
function in a subinterpreter, the caller must have an attached thread state.
Otherwise, the function `func' can be scheduled to be called from the wrong interpreter.

@cartouche
@quotation Προειδοποίηση 
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 @ref{53fe,,PyThreadState_EnsureFromView()}.
@end quotation
@end cartouche


Added in version 3.1.



Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.12: This function now always schedules `func' to be run in the main
interpreter.

@end deffn

@geindex Py_MakePendingCalls (C function)
@anchor{c-api/threads c Py_MakePendingCalls}@anchor{5478}
@deffn {C Συνάρτηση} int Py_MakePendingCalls (void)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Execute all pending calls. This is usually executed automatically by the
interpreter.

This function returns @code{0} on success, and returns @code{-1} with an exception
set on failure.

If this is not called in the main thread of the main
interpreter, this function does nothing and returns @code{0}.
The caller must hold an @ref{1a1,,attached thread state}.


Added in version 3.1.



Άλλαξε στην έκδοση 3.12: This function only runs pending calls in the main interpreter.

@end deffn

@geindex PyThreadState_SetAsyncExc (C function)
@anchor{c-api/threads c PyThreadState_SetAsyncExc}@anchor{f82}
@deffn {C Συνάρτηση} int PyThreadState_SetAsyncExc (unsigned long id, PyObject *exc)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Schedule an exception to be raised asynchronously in a thread.
If the thread has a previously scheduled exception, it is overwritten.

The `id' argument is the thread id of the target thread, as returned by
@ref{540a,,PyThread_get_thread_ident()}.
`exc' is the class of the exception to be raised, or @code{NULL} to clear
the pending exception (if any).

Return the number of affected thread states.
This is normally @code{1} if `id' is found, even when no change was
made (the given `exc' was already pending, or `exc' is @code{NULL} but
no exception is pending).
If the thread id isn’t found, return @code{0}.  This raises no exceptions.

To prevent naive misuse, you must write your own C extension to call this.
This function must be called with an @ref{1a1,,attached thread state}.
This function does not steal any references to `exc'.
This function does not necessarily interrupt system calls such as
@ref{a8c,,sleep()}.


Άλλαξε στην έκδοση 3.7: The type of the `id' parameter changed from long to
unsigned long.

@end deffn

@node Operating system thread APIs,Synchronization primitives<2>,Asynchronous notifications,Python/C API reference manual
@anchor{c-api/threads operating-system-thread-apis}@anchor{58ae}
@section Operating system thread APIs


@geindex PYTHREAD_INVALID_THREAD_ID (C macro)
@anchor{c-api/threads c PYTHREAD_INVALID_THREAD_ID}@anchor{58af}
@deffn {C Μακροεντολή} PYTHREAD_INVALID_THREAD_ID

Sentinel value for an invalid thread ID.

This is currently equivalent to @code{(unsigned long)-1}.
@end deffn

@geindex PyThread_start_new_thread (C function)
@anchor{c-api/threads c PyThread_start_new_thread}@anchor{2018}
@deffn {C Συνάρτηση} unsigned long PyThread_start_new_thread (void (*func)(void*), void *arg)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Start function `func' in a new thread with argument `arg'.
The resulting thread is not intended to be joined.

`func' must not be @code{NULL}, but `arg' may be @code{NULL}.

On success, this function returns the identifier of the new thread; on failure,
this returns @ref{58af,,PYTHREAD_INVALID_THREAD_ID}.

The caller does not need to hold an @ref{1a1,,attached thread state}.
@end deffn

@geindex PyThread_get_thread_ident (C function)
@anchor{c-api/threads c PyThread_get_thread_ident}@anchor{540a}
@deffn {C Συνάρτηση} unsigned long PyThread_get_thread_ident (void)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the identifier of the current thread, which will never be zero.

This function cannot fail, and the caller does not need to hold an
@ref{1a1,,attached thread state}.


@subsubheading Δείτε επίσης


@ref{1505,,threading.get_ident()} and @ref{3390,,threading.Thread.ident}
expose this identifier to Python.

@end deffn

@geindex PyThread_GetInfo (C function)
@anchor{c-api/threads c PyThread_GetInfo}@anchor{5403}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyThread_GetInfo (void)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.3.'
Get general information about the current thread in the form of a
@ref{1568,,struct sequence} object. This information is
accessible as @ref{14fb,,sys.thread_info} in Python.

On success, this returns a new @ref{7da,,strong reference} to the thread
information; on failure, this returns @code{NULL} with an exception set.

The caller must hold an @ref{1a1,,attached thread state}.
@end deffn

@geindex PY_HAVE_THREAD_NATIVE_ID (C macro)
@anchor{c-api/threads c PY_HAVE_THREAD_NATIVE_ID}@anchor{58b0}
@deffn {C Μακροεντολή} PY_HAVE_THREAD_NATIVE_ID

This macro is defined when the system supports native thread IDs.
@end deffn

@geindex PyThread_get_thread_native_id (C function)
@anchor{c-api/threads c PyThread_get_thread_native_id}@anchor{1d9c}
@deffn {C Συνάρτηση} unsigned long PyThread_get_thread_native_id (void)
` Μέρος του @ref{95c,,Σταθερό ABI} on platforms with native thread IDs.'
Get the native identifier of the current thread as it was assigned by the operating
system’s kernel, which will never be less than zero.

This function is only available when @ref{58b0,,PY_HAVE_THREAD_NATIVE_ID} is
defined.

This function cannot fail, and the caller does not need to hold an
@ref{1a1,,attached thread state}.


@subsubheading Δείτε επίσης


@ref{e01,,threading.get_native_id()}

@end deffn

@geindex PyThread_exit_thread (C function)
@anchor{c-api/threads c PyThread_exit_thread}@anchor{5407}
@deffn {C Συνάρτηση} void PyThread_exit_thread (void)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Terminate the current thread. This function is generally considered unsafe
and should be avoided. It is kept solely for backwards compatibility.

This function is only safe to call if all functions in the full call
stack are written to safely allow it.

@cartouche
@quotation Προειδοποίηση 
If the current system uses POSIX threads (also known as «pthreads»),
this calls @code{pthread_exit(3)@footnote{https://manpages.debian.org/pthread_exit(3)}}, which attempts to unwind the stack
and call C++ destructors on some libc implementations. However, if a
@code{noexcept} function is reached, it may terminate the process.
Other systems, such as macOS, do unwinding.

On Windows, this function calls @code{_endthreadex()}, which kills the thread
without calling C++ destructors.

In any case, there is a risk of corruption on the thread’s stack.
@end quotation
@end cartouche


Αποσύρθηκε στην έκδοση 3.14.

@end deffn

@geindex PyThread_init_thread (C function)
@anchor{c-api/threads c PyThread_init_thread}@anchor{540b}
@deffn {C Συνάρτηση} void PyThread_init_thread (void)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Initialize @code{PyThread*} APIs. Python executes this function automatically,
so there’s little need to call it from an extension module.
@end deffn

@geindex PyThread_set_stacksize (C function)
@anchor{c-api/threads c PyThread_set_stacksize}@anchor{540d}
@deffn {C Συνάρτηση} int PyThread_set_stacksize (size_t size)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Set the stack size of the current thread to `size' bytes.

This function returns @code{0} on success, @code{-1} if `size' is invalid, or
@code{-2} if the system does not support changing the stack size. This function
does not set exceptions.

The caller does not need to hold an @ref{1a1,,attached thread state}.
@end deffn

@geindex PyThread_get_stacksize (C function)
@anchor{c-api/threads c PyThread_get_stacksize}@anchor{5409}
@deffn {C Συνάρτηση} size_t PyThread_get_stacksize (void)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the stack size of the current thread in bytes, or @code{0} if the system’s
default stack size is in use.

The caller does not need to hold an @ref{1a1,,attached thread state}.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Synchronization primitives<2>,Thread-local storage support,Operating system thread APIs,Python/C API reference manual
@anchor{c-api/synchronization doc}@anchor{58b1}@anchor{c-api/synchronization synchronization}@anchor{58b2}@anchor{c-api/synchronization synchronization-primitives}@anchor{58b3}@anchor{c-api/synchronization translation-repo}@anchor{58b4}
@section Synchronization primitives


The C-API provides a basic mutual exclusion lock.

@geindex PyMutex (C type)
@anchor{c-api/synchronization c PyMutex}@anchor{693}
@deffn {C Τύπος} 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 Σημείωση 
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


Added in version 3.13.

@end deffn

@geindex PyMutex_Lock (C function)
@anchor{c-api/synchronization c PyMutex_Lock}@anchor{7c9}
@deffn {C Συνάρτηση} void PyMutex_Lock (PyMutex *m)
` Thread safety: @ref{292b,,Atomic}.'
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 detach the @ref{1a1,,thread state} if one exists.


Added in version 3.13.

@end deffn

@geindex PyMutex_Unlock (C function)
@anchor{c-api/synchronization c PyMutex_Unlock}@anchor{7ca}
@deffn {C Συνάρτηση} void PyMutex_Unlock (PyMutex *m)
` Thread safety: @ref{292b,,Atomic}.'
Unlock mutex `m'. The mutex must be locked — otherwise, the function will
issue a fatal error.


Added in version 3.13.

@end deffn

@geindex PyMutex_IsLocked (C function)
@anchor{c-api/synchronization c PyMutex_IsLocked}@anchor{676}
@deffn {C Συνάρτηση} int PyMutex_IsLocked (PyMutex *m)
` Thread safety: @ref{292b,,Atomic}.'
Returns non-zero if the mutex `m' is currently locked, zero otherwise.

@cartouche
@quotation Σημείωση 
This function is intended for use in assertions and debugging only and
should not be used to make concurrency control decisions, as the lock
state may change immediately after the check.
@end quotation
@end cartouche


Added in version 3.14.

@end deffn

@menu
* Python critical section API:: 
* Legacy locking APIs:: 

@end menu

@node Python critical section API,Legacy locking APIs,,Synchronization primitives<2>
@anchor{c-api/synchronization id1}@anchor{58b5}@anchor{c-api/synchronization python-critical-section-api}@anchor{2928}
@subsection Python critical section API


The critical section API provides a deadlock avoidance layer on top of
per-object locks for @ref{487,,free-threaded} CPython.  They are
intended to replace reliance on the @ref{685,,global interpreter lock}, and are
no-ops in versions of Python with the global interpreter lock.

Critical sections are intended to be used for custom types implemented
in C-API extensions. They should generally not be used with built-in types like
@ref{4d9,,list} and @ref{188,,dict} because their public C-APIs
already use critical sections internally, with the notable
exception of @ref{1b9c,,PyDict_Next()}, which requires critical section
to be acquired externally.

Critical sections avoid deadlocks by implicitly suspending active critical
sections, hence, they do not provide exclusive access such as provided by
traditional locks like @ref{693,,PyMutex}.  When a critical section is started,
the per-object lock for the object is acquired. If the code executed inside the
critical section calls C-API functions then it can suspend the critical section thereby
releasing the per-object lock, so other threads can acquire the per-object lock
for the same object.

Variants that accept @ref{693,,PyMutex} pointers rather than Python objects are also
available. Use these variants to start a critical section in a situation where
there is no @ref{19b,,PyObject} – for example, when working with a C type that
does not extend or wrap @code{PyObject} but still needs to call into the C
API in a manner that might lead to deadlocks.

@cartouche
@quotation Σημείωση 
Operations that need to lock two objects at once must use
@ref{546a,,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

Example usage:

@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{97d,,Py_SETREF} calls @ref{975,,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{838,,PyEval_SaveThread()}.

@geindex Py_BEGIN_CRITICAL_SECTION (C macro)
@anchor{c-api/synchronization critical-section-macros}@anchor{58b6}@anchor{c-api/synchronization c Py_BEGIN_CRITICAL_SECTION}@anchor{5469}
@deffn {C Μακροεντολή} Py_BEGIN_CRITICAL_SECTION (op)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Acquires the per-object lock for the object `op' and begins a
critical section.

In the free-threaded build, and when building for the
@ref{197,,Stable ABI}, 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{@{}.


Added in version 3.13.

@end deffn

@geindex Py_BEGIN_CRITICAL_SECTION_MUTEX (C macro)
@anchor{c-api/synchronization c Py_BEGIN_CRITICAL_SECTION_MUTEX}@anchor{58b7}
@deffn {C Μακροεντολή} Py_BEGIN_CRITICAL_SECTION_MUTEX (m)

Locks the mutex `m' and begins a critical section.

In the free-threaded build, this macro expands to:

@example
@{
     PyCriticalSection _py_cs;
     PyCriticalSection_BeginMutex(&_py_cs, m)
@end example

Note that unlike @ref{5469,,Py_BEGIN_CRITICAL_SECTION}, there is no cast for
the argument of the macro - it must be a @ref{693,,PyMutex} pointer.

On the default build, this macro expands to @code{@{}.


Added in version 3.14.

@end deffn

@geindex Py_END_CRITICAL_SECTION (C macro)
@anchor{c-api/synchronization c Py_END_CRITICAL_SECTION}@anchor{546d}
@deffn {C Μακροεντολή} Py_END_CRITICAL_SECTION ()
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Ends the critical section and releases the per-object lock.

In the free-threaded build, and when building for the
@ref{197,,Stable ABI}, this macro expands to:

@example
    PyCriticalSection_End(&_py_cs);
@}
@end example

In the default build, this macro expands to @code{@}}.


Added in version 3.13.

@end deffn

@geindex Py_BEGIN_CRITICAL_SECTION2 (C macro)
@anchor{c-api/synchronization c Py_BEGIN_CRITICAL_SECTION2}@anchor{546a}
@deffn {C Μακροεντολή} Py_BEGIN_CRITICAL_SECTION2 (a, b)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Acquires the per-object 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{@{}.


Added in version 3.13.

@end deffn

@geindex Py_BEGIN_CRITICAL_SECTION2_MUTEX (C macro)
@anchor{c-api/synchronization c Py_BEGIN_CRITICAL_SECTION2_MUTEX}@anchor{58b8}
@deffn {C Μακροεντολή} Py_BEGIN_CRITICAL_SECTION2_MUTEX (m1, m2)

Locks the mutexes `m1' and `m2' and begins a critical section.

In the free-threaded build, and when building for the
@ref{197,,Stable ABI}, this macro expands to:

@example
@{
     PyCriticalSection2 _py_cs2;
     PyCriticalSection2_BeginMutex(&_py_cs2, m1, m2)
@end example

Note that unlike @ref{546a,,Py_BEGIN_CRITICAL_SECTION2}, there is no cast for
the arguments of the macro - they must be @ref{693,,PyMutex} pointers.

On the default build, this macro expands to @code{@{}.


Added in version 3.14.

@end deffn

@geindex Py_END_CRITICAL_SECTION2 (C macro)
@anchor{c-api/synchronization c Py_END_CRITICAL_SECTION2}@anchor{546e}
@deffn {C Μακροεντολή} Py_END_CRITICAL_SECTION2 ()
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Ends the critical section and releases the per-object locks.

In the free-threaded build, and when building for the
@ref{197,,Stable ABI}, this macro expands to:

@example
    PyCriticalSection2_End(&_py_cs2);
@}
@end example

In the default build, this macro expands to @code{@}}.


Added in version 3.13.

@end deffn

@menu
* Low-level critical section API:: 

@end menu

@node Low-level critical section API,,,Python critical section API
@anchor{c-api/synchronization low-level-critical-section-api}@anchor{58b9}
@subsubsection Low-level critical section API


The following functions and structs are exposed for cases where C macros
are not available.

@geindex PyCriticalSection_Begin (C function)
@geindex PyCriticalSection_End (C function)
@geindex PyCriticalSection2_Begin (C function)
@geindex PyCriticalSection2_End (C function)
@anchor{c-api/synchronization c PyCriticalSection_Begin}@anchor{52d7}
@deffn {C Συνάρτηση} void PyCriticalSection_Begin (PyCriticalSection *c, PyObject *op)
@anchor{c-api/synchronization c PyCriticalSection_End}@anchor{52d8}
@deffnx {C Συνάρτηση} void PyCriticalSection_End (PyCriticalSection *c)
@anchor{c-api/synchronization c PyCriticalSection2_Begin}@anchor{52d5}
@deffnx {C Συνάρτηση} void PyCriticalSection2_Begin (PyCriticalSection2 *c, PyObject *a, PyObject *b)
@anchor{c-api/synchronization c PyCriticalSection2_End}@anchor{52d6}
@deffnx {C Συνάρτηση} void PyCriticalSection2_End (PyCriticalSection2 *c);
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
To be used only as in the macro expansions
listed @ref{58b6,,earlier in this section}.

In non-@ref{487,,free-threaded} builds of CPython, these
functions do nothing.


Added in version 3.13.

@end deffn

@geindex PyCriticalSection (C type)
@geindex PyCriticalSection2 (C type)
@anchor{c-api/synchronization c PyCriticalSection}@anchor{368}
@deffn {C Τύπος} type PyCriticalSection
@anchor{c-api/synchronization c PyCriticalSection2}@anchor{52d4}
@deffnx {C Τύπος} type PyCriticalSection2
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών) από την έκδοση 3.15.'
To be used only as in the macro expansions
listed @ref{58b6,,earlier in this section}.
Note that the contents of the structures are private and their meaning may
change in future Python versions.


Added in version 3.13.

@end deffn

@geindex PyCriticalSection_BeginMutex (C function)
@geindex PyCriticalSection2_BeginMutex (C function)
@anchor{c-api/synchronization c PyCriticalSection_BeginMutex}@anchor{58ba}
@deffn {C Συνάρτηση} void PyCriticalSection_BeginMutex (PyCriticalSection *c, PyMutex *m);
@anchor{c-api/synchronization c PyCriticalSection2_BeginMutex}@anchor{58bb}
@deffnx {C Συνάρτηση} void PyCriticalSection2_BeginMutex (PyCriticalSection2 *c, PyMutex *m1, PyMutex *m2);

@c (These need to be in a separate section without a Stable ABI anotation.)

To be used only as in the macro expansions
listed @ref{58b6,,earlier in this section}.

In non-@ref{487,,free-threaded} builds of CPython, these
functions do nothing.


Added in version 3.14.

@end deffn

@node Legacy locking APIs,,Python critical section API,Synchronization primitives<2>
@anchor{c-api/synchronization legacy-locking-apis}@anchor{58bc}
@subsection Legacy locking APIs


These APIs are obsolete since Python 3.13 with the introduction of
@ref{693,,PyMutex}.


Άλλαξε στην έκδοση 3.15: These APIs are now a simple wrapper around @code{PyMutex}.


@geindex PyThread_type_lock (C type)
@anchor{c-api/synchronization c PyThread_type_lock}@anchor{58bd}
@deffn {C Τύπος} type PyThread_type_lock

A pointer to a mutual exclusion lock.
@end deffn

@geindex PyLockStatus (C type)
@anchor{c-api/synchronization c PyLockStatus}@anchor{58be}
@deffn {C Τύπος} type PyLockStatus

The result of acquiring a lock with a timeout.

@geindex PY_LOCK_FAILURE (C enumerator)
@anchor{c-api/synchronization c PY_LOCK_FAILURE}@anchor{58bf}
@deffn {C Enumerator} enumerator PY_LOCK_FAILURE

Failed to acquire the lock.
@end deffn

@geindex PY_LOCK_ACQUIRED (C enumerator)
@anchor{c-api/synchronization c PY_LOCK_ACQUIRED}@anchor{58c0}
@deffn {C Enumerator} enumerator PY_LOCK_ACQUIRED

The lock was successfully acquired.
@end deffn

@geindex PY_LOCK_INTR (C enumerator)
@anchor{c-api/synchronization c PY_LOCK_INTR}@anchor{58c1}
@deffn {C Enumerator} enumerator PY_LOCK_INTR

The lock was interrupted by a signal.
@end deffn
@end deffn

@geindex PyThread_allocate_lock (C function)
@anchor{c-api/synchronization c PyThread_allocate_lock}@anchor{5406}
@deffn {C Συνάρτηση} @ref{58bd,,PyThread_type_lock} PyThread_allocate_lock (void)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Allocate a new lock.

On success, this function returns a lock; on failure, this
function returns @code{0} without an exception set.

The caller does not need to hold an @ref{1a1,,attached thread state}.


Άλλαξε στην έκδοση 3.15: This function now always uses @ref{693,,PyMutex}. In prior versions, this
would use a lock provided by the operating system.

@end deffn

@geindex PyThread_free_lock (C function)
@anchor{c-api/synchronization c PyThread_free_lock}@anchor{5408}
@deffn {C Συνάρτηση} void PyThread_free_lock (PyThread_type_lock lock)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Destroy `lock'. The lock should not be held by any thread when calling
this.

The caller does not need to hold an @ref{1a1,,attached thread state}.
@end deffn

@geindex PyThread_acquire_lock_timed (C function)
@anchor{c-api/synchronization c PyThread_acquire_lock_timed}@anchor{5405}
@deffn {C Συνάρτηση} @ref{58be,,PyLockStatus} PyThread_acquire_lock_timed (PyThread_type_lock lock, long long microseconds, int intr_flag)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Acquire `lock' with a timeout.

This will wait for `microseconds' microseconds to acquire the lock. If the
timeout expires, this function returns @ref{58bf,,PY_LOCK_FAILURE}.
If `microseconds' is @code{-1}, this will wait indefinitely until the lock has
been released.

If `intr_flag' is @code{1}, acquiring the lock may be interrupted by a signal,
in which case this function returns @ref{58c1,,PY_LOCK_INTR}. Upon
interruption, it’s generally expected that the caller makes a call to
@ref{5478,,Py_MakePendingCalls()} to propagate an exception to Python code.

If the lock is successfully acquired, this function returns
@ref{58c0,,PY_LOCK_ACQUIRED}.

The caller does not need to hold an @ref{1a1,,attached thread state}.
@end deffn

@geindex PyThread_acquire_lock (C function)
@anchor{c-api/synchronization c PyThread_acquire_lock}@anchor{5404}
@deffn {C Συνάρτηση} int PyThread_acquire_lock (PyThread_type_lock lock, int waitflag)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Acquire `lock'.

If `waitflag' is @code{1} and another thread currently holds the lock, this
function will wait until the lock can be acquired and will always return
@code{1}.

If `waitflag' is @code{0} and another thread holds the lock, this function will
not wait and instead return @code{0}. If the lock is not held by any other
thread, then this function will acquire it and return @code{1}.

Unlike @ref{5405,,PyThread_acquire_lock_timed()}, acquiring the lock cannot be
interrupted by a signal.

The caller does not need to hold an @ref{1a1,,attached thread state}.
@end deffn

@geindex PyThread_release_lock (C function)
@anchor{c-api/synchronization c PyThread_release_lock}@anchor{540c}
@deffn {C Συνάρτηση} int PyThread_release_lock (PyThread_type_lock lock)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Release `lock'. If `lock' is not held, then this function issues a
fatal error.

The caller does not need to hold an @ref{1a1,,attached thread state}.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Thread-local storage support,Multiple interpreters in a Python process,Synchronization primitives<2>,Python/C API reference manual
@anchor{c-api/tls doc}@anchor{58c2}@anchor{c-api/tls thread-local-storage}@anchor{58c3}@anchor{c-api/tls thread-local-storage-support}@anchor{58c4}@anchor{c-api/tls translation-repo}@anchor{58c5}
@section 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{1a87,,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.

A @ref{1a70,,thread state} does `not' need to be @ref{1a1,,attached}
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 Σημείωση 
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{19b,,PyObject}*, these
functions don’t do refcount operations on them either.
@end quotation
@end cartouche

@menu
* Thread-specific storage API:: 
* Dynamic allocation:: 
* Methods:: 
* Legacy APIs:: 

@end menu

@node Thread-specific storage API,Dynamic allocation,,Thread-local storage support
@anchor{c-api/tls id1}@anchor{58c6}@anchor{c-api/tls thread-specific-storage-api}@anchor{ea3}
@subsection Thread-specific storage API


The thread-specific storage (TSS) API was introduced to supersede the use of the existing TLS API within the
CPython interpreter.  This API uses a new type @ref{ea4,,Py_tss_t} instead of
int to represent thread keys.


Added in version 3.7.



@subsubheading Δείτε επίσης


«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/tls c Py_tss_t}@anchor{ea4}
@deffn {C Τύπος} 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{95c,,Py_LIMITED_API} is not defined, static allocation of
this type by @ref{58c7,,Py_tss_NEEDS_INIT} is allowed.
@end deffn

@geindex Py_tss_NEEDS_INIT (C macro)
@anchor{c-api/tls c Py_tss_NEEDS_INIT}@anchor{58c7}
@deffn {C Μακροεντολή} Py_tss_NEEDS_INIT

This macro expands to the initializer for @ref{ea4,,Py_tss_t} variables.
Note that this macro won’t be defined with @ref{95c,,Py_LIMITED_API}.
@end deffn

@node Dynamic allocation,Methods,Thread-specific storage API,Thread-local storage support
@anchor{c-api/tls dynamic-allocation}@anchor{58c8}
@subsection Dynamic allocation


Dynamic allocation of the @ref{ea4,,Py_tss_t}, required in extension modules
built with @ref{95c,,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/tls c PyThread_tss_alloc}@anchor{64b}
@deffn {C Συνάρτηση} @ref{ea4,,Py_tss_t} *PyThread_tss_alloc ()
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Return a value which is the same state as a value initialized with
@ref{58c7,,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/tls c PyThread_tss_free}@anchor{64d}
@deffn {C Συνάρτηση} void PyThread_tss_free (Py_tss_t *key)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Free the given `key' allocated by @ref{64b,,PyThread_tss_alloc()}, after
first calling @ref{653,,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 Σημείωση 
A freed key becomes a dangling pointer. You should reset the key to
@code{NULL}.
@end quotation
@end cartouche
@end deffn

@node Methods,Legacy APIs,Dynamic allocation,Thread-local storage support
@anchor{c-api/tls methods}@anchor{58c9}
@subsection Methods


The parameter `key' of these functions must not be @code{NULL}.  Moreover, the
behaviors of @ref{64f,,PyThread_tss_set()} and @ref{651,,PyThread_tss_get()} are
undefined if the given @ref{ea4,,Py_tss_t} has not been initialized by
@ref{540e,,PyThread_tss_create()}.

@geindex PyThread_tss_is_created (C function)
@anchor{c-api/tls c PyThread_tss_is_created}@anchor{540f}
@deffn {C Συνάρτηση} int PyThread_tss_is_created (Py_tss_t *key)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Return a non-zero value if the given @ref{ea4,,Py_tss_t} has been initialized
by @ref{540e,,PyThread_tss_create()}.
@end deffn

@geindex PyThread_tss_create (C function)
@anchor{c-api/tls c PyThread_tss_create}@anchor{540e}
@deffn {C Συνάρτηση} int PyThread_tss_create (Py_tss_t *key)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{58c7,,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/tls c PyThread_tss_delete}@anchor{653}
@deffn {C Συνάρτηση} void PyThread_tss_delete (Py_tss_t *key)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{540e,,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/tls c PyThread_tss_set}@anchor{64f}
@deffn {C Συνάρτηση} int PyThread_tss_set (Py_tss_t *key, void *value)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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/tls c PyThread_tss_get}@anchor{651}
@deffn {C Συνάρτηση} void *PyThread_tss_get (Py_tss_t *key)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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 Legacy APIs,,Methods,Thread-local storage support
@anchor{c-api/tls legacy-apis}@anchor{58ca}@anchor{c-api/tls thread-local-storage-api}@anchor{ea2}
@subsection Legacy APIs



Αποσύρθηκε στην έκδοση 3.7: This API is superseded by the
@ref{ea3,,thread-specific storage (TSS) API}.


@cartouche
@quotation Σημείωση 
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{64a,,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/tls c PyThread_create_key}@anchor{64a}
@deffn {C Συνάρτηση} int PyThread_create_key ()
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyThread_delete_key (C function)
@anchor{c-api/tls c PyThread_delete_key}@anchor{64c}
@deffn {C Συνάρτηση} void PyThread_delete_key (int key)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyThread_set_key_value (C function)
@anchor{c-api/tls c PyThread_set_key_value}@anchor{64e}
@deffn {C Συνάρτηση} int PyThread_set_key_value (int key, void *value)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyThread_get_key_value (C function)
@anchor{c-api/tls c PyThread_get_key_value}@anchor{650}
@deffn {C Συνάρτηση} void *PyThread_get_key_value (int key)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyThread_delete_key_value (C function)
@anchor{c-api/tls c PyThread_delete_key_value}@anchor{652}
@deffn {C Συνάρτηση} void PyThread_delete_key_value (int key)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex PyThread_ReInitTLS (C function)
@anchor{c-api/tls c PyThread_ReInitTLS}@anchor{654}
@deffn {C Συνάρτηση} void PyThread_ReInitTLS ()
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Multiple interpreters in a Python process,Profiling and tracing,Thread-local storage support,Python/C API reference manual
@anchor{c-api/subinterpreters doc}@anchor{58cb}@anchor{c-api/subinterpreters multiple-interpreters-in-a-python-process}@anchor{58cc}@anchor{c-api/subinterpreters sub-interpreter-support}@anchor{410}@anchor{c-api/subinterpreters translation-repo}@anchor{58cd}
@section Multiple interpreters in a Python process


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{5896,,PyInterpreterState_Main()} function returns a pointer to its state.

You can switch between sub-interpreters using the @ref{5402,,PyThreadState_Swap()}
function. You can create and destroy them using the following functions:

@geindex PyInterpreterConfig (C type)
@anchor{c-api/subinterpreters c PyInterpreterConfig}@anchor{973}
@deffn {C Τύπος} type PyInterpreterConfig

Structure containing most parameters to configure a sub-interpreter.
Its values are used only in @ref{876,,Py_NewInterpreterFromConfig()} and
never modified by the runtime.


Added in version 3.12.


Structure fields:

@geindex PyInterpreterConfig.use_main_obmalloc (C member)
@anchor{c-api/subinterpreters c PyInterpreterConfig use_main_obmalloc}@anchor{4bfb}
@deffn {C Μέλος} 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{58ce,,check_multi_interp_extensions}
must be @code{1} (non-zero).
If this is @code{1} then @ref{58cf,,gil}
must not be @ref{58d0,,PyInterpreterConfig_OWN_GIL}.
@end deffn

@geindex PyInterpreterConfig.allow_fork (C member)
@anchor{c-api/subinterpreters c PyInterpreterConfig allow_fork}@anchor{58d1}
@deffn {C Μέλος} 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{df,,subprocess} module still works
when fork is disallowed.
@end deffn

@geindex PyInterpreterConfig.allow_exec (C member)
@anchor{c-api/subinterpreters c PyInterpreterConfig allow_exec}@anchor{58d2}
@deffn {C Μέλος} int allow_exec

If this is @code{0} then the runtime will not support replacing the
current process via exec (e.g. @ref{323e,,os.execv()}) in any thread
where the sub-interpreter is currently active.
Otherwise exec is unrestricted.

Note that the @ref{df,,subprocess} module still works
when exec is disallowed.
@end deffn

@geindex PyInterpreterConfig.allow_threads (C member)
@anchor{c-api/subinterpreters c PyInterpreterConfig allow_threads}@anchor{58d3}
@deffn {C Μέλος} int allow_threads

If this is @code{0} then the sub-interpreter’s @ref{f6,,threading} module
won’t create threads.
Otherwise threads are allowed.
@end deffn

@geindex PyInterpreterConfig.allow_daemon_threads (C member)
@anchor{c-api/subinterpreters c PyInterpreterConfig allow_daemon_threads}@anchor{58d4}
@deffn {C Μέλος} int allow_daemon_threads

If this is @code{0} then the sub-interpreter’s @ref{f6,,threading} module
won’t create daemon threads.
Otherwise daemon threads are allowed (as long as
@ref{58d3,,allow_threads} is non-zero).
@end deffn

@geindex PyInterpreterConfig.check_multi_interp_extensions (C member)
@anchor{c-api/subinterpreters c PyInterpreterConfig check_multi_interp_extensions}@anchor{58ce}
@deffn {C Μέλος} 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{5496,,Py_mod_multiple_interpreters}.)

This must be @code{1} (non-zero) if
@ref{4bfb,,use_main_obmalloc} is @code{0}.
@end deffn

@geindex PyInterpreterConfig.gil (C member)
@anchor{c-api/subinterpreters c PyInterpreterConfig gil}@anchor{58cf}
@deffn {C Μέλος} 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/subinterpreters c PyInterpreterConfig_DEFAULT_GIL}@anchor{58d5}
@deffn {C Μακροεντολή} PyInterpreterConfig_DEFAULT_GIL

Use the default selection (@ref{58d6,,PyInterpreterConfig_SHARED_GIL}).
@end deffn

@geindex PyInterpreterConfig_SHARED_GIL (C macro)
@anchor{c-api/subinterpreters c PyInterpreterConfig_SHARED_GIL}@anchor{58d6}
@deffn {C Μακροεντολή} PyInterpreterConfig_SHARED_GIL

Use (share) the main interpreter’s GIL.
@end deffn

@geindex PyInterpreterConfig_OWN_GIL (C macro)
@anchor{c-api/subinterpreters c PyInterpreterConfig_OWN_GIL}@anchor{58d0}
@deffn {C Μακροεντολή} PyInterpreterConfig_OWN_GIL

Use the sub-interpreter’s own GIL.
@end deffn

If this is @ref{58d0,,PyInterpreterConfig_OWN_GIL} then
@ref{4bfb,,PyInterpreterConfig.use_main_obmalloc} must be @code{0}.
@end deffn
@end deffn

@geindex Py_NewInterpreterFromConfig (C function)
@anchor{c-api/subinterpreters c Py_NewInterpreterFromConfig}@anchor{876}
@deffn {C Συνάρτηση} @ref{d75,,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{13,,builtins}, @ref{1,,__main__} and @ref{e2,,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 @ref{1a70,,thread state}
created in the new sub-interpreter.  This thread state is
@ref{1a1,,attached}.
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
attached thread state, which might not exist.

Like all other Python/C API functions, an @ref{1a1,,attached thread state}
must be present before calling this function, but it might be detached upon
returning. On success, the returned thread state will be attached.
If the sub-interpreter is created with its own @ref{411,,GIL} then the
attached thread state of the calling interpreter will be detached.
When the function returns, the new interpreter’s @ref{1a70,,thread state}
will be attached to the current thread and
the previous interpreter’s attached thread state will remain detached.


Added in 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{c90,,PyInterpreterState} values.  A read-only copy of the config
may be stored internally on the @code{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{392,,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 legacy
@ref{555c,,single-phase initialization},
e.g. @ref{5562,,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{58d7,,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{10cf,,Py_FinalizeEx()} and @ref{673,,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/subinterpreters c Py_NewInterpreter}@anchor{1d2f}
@deffn {C Συνάρτηση} @ref{b6c,,PyThreadState} *Py_NewInterpreter (void)
` Μέρος του @ref{95c,,Σταθερό 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{876,,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/subinterpreters c Py_EndInterpreter}@anchor{1a6f}
@deffn {C Συνάρτηση} void Py_EndInterpreter (PyThreadState *tstate)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@geindex Py_FinalizeEx (C function)

Destroy the (sub-)interpreter represented by the given @ref{1a70,,thread state}.
The given thread state must be @ref{1a1,,attached}.
When the call returns, there will be no attached thread state.
All thread states associated with this interpreter are destroyed.

@ref{10cf,,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:: 
* High-level APIs: High-level APIs<2>. 
* Low-level APIs: Low-level APIs<2>. 
* Advanced debugger support:: 

@end menu

@node A per-interpreter GIL,Bugs and caveats,,Multiple interpreters in a Python process
@anchor{c-api/subinterpreters a-per-interpreter-gil}@anchor{58d8}@anchor{c-api/subinterpreters per-interpreter-gil}@anchor{58d9}
@subsection A per-interpreter GIL



Added in version 3.12.


Using @ref{876,,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/} and 
@geindex Python Enhancement Proposals; PEP 684
PEP 684@footnote{https://peps.python.org/pep-0684/}.)

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{398,,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.

@node Bugs and caveats,High-level APIs<2>,A per-interpreter GIL,Multiple interpreters in a Python process
@anchor{c-api/subinterpreters bugs-and-caveats}@anchor{58d7}
@subsection 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{f31,,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{1a5,,PyGILState_Ensure()} and @ref{1a6,,PyGILState_Release()} calls.
Furthermore, extensions (such as @ref{2d,,ctypes}) using these APIs to allow calling
of Python code from non-Python created threads will probably be broken when using
sub-interpreters.

@node High-level APIs<2>,Low-level APIs<2>,Bugs and caveats,Multiple interpreters in a Python process
@anchor{c-api/subinterpreters high-level-apis}@anchor{58da}
@subsection High-level APIs


@geindex PyInterpreterState (C type)
@anchor{c-api/subinterpreters c PyInterpreterState}@anchor{c90}
@deffn {C Τύπος} type PyInterpreterState
` Μέρος του @ref{95c,,Σταθερό ABI} (ως μια αδιαφανής κατασκευή).'
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.


Άλλαξε στην έκδοση 3.12: 
@geindex Python Enhancement Proposals; PEP 684
PEP 684@footnote{https://peps.python.org/pep-0684/} introduced the possibility
of a @ref{58d9,,per-interpreter GIL}.
See @ref{876,,Py_NewInterpreterFromConfig()}.

@end deffn

@geindex PyInterpreterState_Get (C function)
@anchor{c-api/subinterpreters c PyInterpreterState_Get}@anchor{83b}
@deffn {C Συνάρτηση} @ref{c90,,PyInterpreterState} *PyInterpreterState_Get (void)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.9.'
Get the current interpreter.

Issue a fatal error if there is no @ref{1a1,,attached thread state}.
It cannot return NULL.


Added in version 3.9.

@end deffn

@geindex PyInterpreterState_GetID (C function)
@anchor{c-api/subinterpreters c PyInterpreterState_GetID}@anchor{f84}
@deffn {C Συνάρτηση} int64_t PyInterpreterState_GetID (PyInterpreterState *interp)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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 have an @ref{1a1,,attached thread state}.


Added in version 3.7.

@end deffn

@geindex PyInterpreterState_GetDict (C function)
@anchor{c-api/subinterpreters c PyInterpreterState_GetDict}@anchor{536a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyInterpreterState_GetDict (PyInterpreterState *interp)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{d48,,PyModule_GetState()}, which
extensions should use to store interpreter-specific state information.

The returned dictionary is borrowed from the interpreter and is valid until
interpreter shutdown.


Added in version 3.8.

@end deffn

@geindex _PyFrameEvalFunction (C type)
@anchor{c-api/subinterpreters c _PyFrameEvalFunction}@anchor{b58}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*_PyFrameEvalFunction)(@ref{b6c,,PyThreadState} *tstate, @ref{1b81,,_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.


Άλλαξε στην έκδοση 3.9: The function now takes a `tstate' parameter.



Άλλαξε στην έκδοση 3.11: The `frame' parameter changed from @code{PyFrameObject*} to @code{_PyInterpreterFrame*}.

@end deffn

@geindex _PyInterpreterState_GetEvalFrameFunc (C function)
@anchor{c-api/subinterpreters c _PyInterpreterState_GetEvalFrameFunc}@anchor{1f6b}
@deffn {C Συνάρτηση} @ref{b58,,_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».


Added in version 3.9.

@end deffn

@geindex _PyInterpreterState_SetEvalFrameFunc (C function)
@anchor{c-api/subinterpreters c _PyInterpreterState_SetEvalFrameFunc}@anchor{1f6c}
@deffn {C Συνάρτηση} 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».


Added in version 3.9.

@end deffn

@geindex _PyInterpreterState_SetEvalFrameAllowSpecialization (C function)
@anchor{c-api/subinterpreters c _PyInterpreterState_SetEvalFrameAllowSpecialization}@anchor{58db}
@deffn {C Συνάρτηση} void _PyInterpreterState_SetEvalFrameAllowSpecialization (PyInterpreterState *interp, int allow_specialization)

Enables or disables specialization why a custom frame evaluator is in place.

If `allow_specialization' is non-zero, the adaptive specializer will
continue to specialize bytecodes even though a custom eval frame function
is set. When `allow_specialization' is zero, setting a custom eval frame
disables specialization. The standard interpreter loop will continue to deopt
while a frame evaluation API is in place - the frame evaluation function needs
to handle the specialized opcodes to take advantage of this.


Added in version 3.15.

@end deffn

@geindex _PyInterpreterState_IsSpecializationEnabled (C function)
@anchor{c-api/subinterpreters c _PyInterpreterState_IsSpecializationEnabled}@anchor{58dc}
@deffn {C Συνάρτηση} int _PyInterpreterState_IsSpecializationEnabled (PyInterpreterState *interp)

Return non-zero if adaptive specialization is enabled for the interpreter.
Specialization is enabled when no custom eval frame function is set, or
when one is set with `allow_specialization' enabled.


Added in version 3.15.

@end deffn

@node Low-level APIs<2>,Advanced debugger support,High-level APIs<2>,Multiple interpreters in a Python process
@anchor{c-api/subinterpreters low-level-apis}@anchor{58dd}
@subsection Low-level APIs


All of the following functions must be called after @ref{673,,Py_Initialize()}.


Άλλαξε στην έκδοση 3.7: @ref{673,,Py_Initialize()} now initializes the @ref{411,,GIL}
and sets an @ref{1a1,,attached thread state}.


@geindex PyInterpreterState_New (C function)
@anchor{c-api/subinterpreters c PyInterpreterState_New}@anchor{49ab}
@deffn {C Συνάρτηση} @ref{c90,,PyInterpreterState} *PyInterpreterState_New ()
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Create a new interpreter state object.  An @ref{1a1,,attached thread state} is not needed,
but may optionally exist if it is necessary to serialize calls to this
function.

Raises an @ref{1e65,,auditing event} @code{cpython.PyInterpreterState_New} with no arguments.
@end deffn

@geindex PyInterpreterState_Clear (C function)
@anchor{c-api/subinterpreters c PyInterpreterState_Clear}@anchor{49aa}
@deffn {C Συνάρτηση} void PyInterpreterState_Clear (PyInterpreterState *interp)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Reset all information in an interpreter state object.  There must be
an @ref{1a1,,attached thread state} for the interpreter.

Raises an @ref{1e65,,auditing event} @code{cpython.PyInterpreterState_Clear} with no arguments.
@end deffn

@geindex PyInterpreterState_Delete (C function)
@anchor{c-api/subinterpreters c PyInterpreterState_Delete}@anchor{5369}
@deffn {C Συνάρτηση} void PyInterpreterState_Delete (PyInterpreterState *interp)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Destroy an interpreter state object.  There `should not' be an
@ref{1a1,,attached thread state} for the target interpreter. The interpreter
state must have been reset with a previous call to @ref{49aa,,PyInterpreterState_Clear()}.
@end deffn

@node Advanced debugger support,,Low-level APIs<2>,Multiple interpreters in a Python process
@anchor{c-api/subinterpreters advanced-debugger-support}@anchor{58de}@anchor{c-api/subinterpreters advanced-debugging}@anchor{58df}
@subsection Advanced debugger support


These functions are only intended to be used by advanced debugging tools.

@geindex PyInterpreterState_Head (C function)
@anchor{c-api/subinterpreters c PyInterpreterState_Head}@anchor{18a1}
@deffn {C Συνάρτηση} @ref{c90,,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/subinterpreters c PyInterpreterState_Main}@anchor{5896}
@deffn {C Συνάρτηση} @ref{c90,,PyInterpreterState} *PyInterpreterState_Main ()

Return the main interpreter state object.
@end deffn

@geindex PyInterpreterState_Next (C function)
@anchor{c-api/subinterpreters c PyInterpreterState_Next}@anchor{18a2}
@deffn {C Συνάρτηση} @ref{c90,,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/subinterpreters c PyInterpreterState_ThreadHead}@anchor{18a3}
@deffn {C Συνάρτηση} @ref{b6c,,PyThreadState} *PyInterpreterState_ThreadHead (PyInterpreterState *interp)

Return the pointer to the first @ref{b6c,,PyThreadState} object in the list of
threads associated with the interpreter `interp'.
@end deffn

@geindex PyThreadState_Next (C function)
@anchor{c-api/subinterpreters c PyThreadState_Next}@anchor{18a4}
@deffn {C Συνάρτηση} @ref{b6c,,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{c90,,PyInterpreterState} object.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Profiling and tracing,Reference tracing,Multiple interpreters in a Python process,Python/C API reference manual
@anchor{c-api/profiling doc}@anchor{58e0}@anchor{c-api/profiling profiling}@anchor{58e1}@anchor{c-api/profiling profiling-and-tracing}@anchor{58e2}@anchor{c-api/profiling translation-repo}@anchor{58e3}
@section 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/profiling c Py_tracefunc}@anchor{58e4}
@deffn {C Τύπος} typedef int (*Py_tracefunc)(@ref{19b,,PyObject} *obj, @ref{b68,,PyFrameObject} *frame, int what, @ref{19b,,PyObject} *arg)

The type of the trace function registered using @ref{189f,,PyEval_SetProfile()} and
@ref{850,,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{58e5,,PyTrace_CALL},
@ref{58e6,,PyTrace_EXCEPTION}, @ref{58e7,,PyTrace_LINE}, @ref{58e8,,PyTrace_RETURN},
@ref{58e9,,PyTrace_C_CALL}, @ref{58ea,,PyTrace_C_EXCEPTION}, @ref{58eb,,PyTrace_C_RETURN},
or @ref{58ec,,PyTrace_OPCODE}, and `arg' depends on the value of `what':


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Value of `what'

@tab

Meaning of `arg'

@item

@ref{58e5,,PyTrace_CALL}

@tab

Always @ref{5606,,Py_None}.

@item

@ref{58e6,,PyTrace_EXCEPTION}

@tab

Exception information as returned by
@ref{a7a,,sys.exc_info()}.

@item

@ref{58e7,,PyTrace_LINE}

@tab

Always @ref{5606,,Py_None}.

@item

@ref{58e8,,PyTrace_RETURN}

@tab

Value being returned to the caller,
or @code{NULL} if caused by an exception.

@item

@ref{58e9,,PyTrace_C_CALL}

@tab

Function object being called.

@item

@ref{58ea,,PyTrace_C_EXCEPTION}

@tab

Function object being called.

@item

@ref{58eb,,PyTrace_C_RETURN}

@tab

Function object being called.

@item

@ref{58ec,,PyTrace_OPCODE}

@tab

Always @ref{5606,,Py_None}.

@end multitable

@end deffn

@geindex PyTrace_CALL (C var)
@anchor{c-api/profiling c PyTrace_CALL}@anchor{58e5}
@deffn {C Μεταβλητή} int PyTrace_CALL

The value of the `what' parameter to a @ref{58e4,,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/profiling c PyTrace_EXCEPTION}@anchor{58e6}
@deffn {C Μεταβλητή} int PyTrace_EXCEPTION

The value of the `what' parameter to a @ref{58e4,,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 receive
these events; they are not needed by the profiler.
@end deffn

@geindex PyTrace_LINE (C var)
@anchor{c-api/profiling c PyTrace_LINE}@anchor{58e7}
@deffn {C Μεταβλητή} int PyTrace_LINE

The value passed as the `what' parameter to a @ref{58e4,,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{f9b,,f_trace_lines} to
`0' on that frame.
@end deffn

@geindex PyTrace_RETURN (C var)
@anchor{c-api/profiling c PyTrace_RETURN}@anchor{58e8}
@deffn {C Μεταβλητή} int PyTrace_RETURN

The value for the `what' parameter to @ref{58e4,,Py_tracefunc} functions when a
call is about to return.
@end deffn

@geindex PyTrace_C_CALL (C var)
@anchor{c-api/profiling c PyTrace_C_CALL}@anchor{58e9}
@deffn {C Μεταβλητή} int PyTrace_C_CALL

The value for the `what' parameter to @ref{58e4,,Py_tracefunc} functions when a C
function is about to be called.
@end deffn

@geindex PyTrace_C_EXCEPTION (C var)
@anchor{c-api/profiling c PyTrace_C_EXCEPTION}@anchor{58ea}
@deffn {C Μεταβλητή} int PyTrace_C_EXCEPTION

The value for the `what' parameter to @ref{58e4,,Py_tracefunc} functions when a C
function has raised an exception.
@end deffn

@geindex PyTrace_C_RETURN (C var)
@anchor{c-api/profiling c PyTrace_C_RETURN}@anchor{58eb}
@deffn {C Μεταβλητή} int PyTrace_C_RETURN

The value for the `what' parameter to @ref{58e4,,Py_tracefunc} functions when a C
function has returned.
@end deffn

@geindex PyTrace_OPCODE (C var)
@anchor{c-api/profiling c PyTrace_OPCODE}@anchor{58ec}
@deffn {C Μεταβλητή} int PyTrace_OPCODE

The value for the `what' parameter to @ref{58e4,,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{f9c,,f_trace_opcodes} to `1' on the frame.
@end deffn

@geindex PyEval_SetProfile (C function)
@anchor{c-api/profiling c PyEval_SetProfile}@anchor{189f}
@deffn {C Συνάρτηση} 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{58e7,,PyTrace_LINE}
@ref{58ec,,PyTrace_OPCODE} and @ref{58e6,,PyTrace_EXCEPTION}.

See also the @ref{18a0,,sys.setprofile()} function.

The caller must have an @ref{1a1,,attached thread state}.
@end deffn

@geindex PyEval_SetProfileAllThreads (C function)
@anchor{c-api/profiling c PyEval_SetProfileAllThreads}@anchor{966}
@deffn {C Συνάρτηση} void PyEval_SetProfileAllThreads (Py_tracefunc func, PyObject *obj)

Like @ref{189f,,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 have an @ref{1a1,,attached thread state}.

As @ref{189f,,PyEval_SetProfile()}, this function ignores any exceptions raised while
setting the profile functions in all threads.
@end deffn


Added in version 3.12.


@geindex PyEval_SetTrace (C function)
@anchor{c-api/profiling c PyEval_SetTrace}@anchor{850}
@deffn {C Συνάρτηση} void PyEval_SetTrace (Py_tracefunc func, PyObject *obj)

Set the tracing function to `func'.  This is similar to
@ref{189f,,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{850,,PyEval_SetTrace()}
will not receive @ref{58e9,,PyTrace_C_CALL}, @ref{58ea,,PyTrace_C_EXCEPTION} or
@ref{58eb,,PyTrace_C_RETURN} as a value for the `what' parameter.

See also the @ref{55c,,sys.settrace()} function.

The caller must have an @ref{1a1,,attached thread state}.
@end deffn

@geindex PyEval_SetTraceAllThreads (C function)
@anchor{c-api/profiling c PyEval_SetTraceAllThreads}@anchor{851}
@deffn {C Συνάρτηση} void PyEval_SetTraceAllThreads (Py_tracefunc func, PyObject *obj)

Like @ref{850,,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 have an @ref{1a1,,attached thread state}.

As @ref{850,,PyEval_SetTrace()}, this function ignores any exceptions raised while
setting the trace functions in all threads.
@end deffn


Added in version 3.12.


@node Reference tracing,Python Initialization Configuration,Profiling and tracing,Python/C API reference manual
@anchor{c-api/profiling reference-tracing}@anchor{58ed}
@section Reference tracing



Added in version 3.13.


@geindex PyRefTracer (C type)
@anchor{c-api/profiling c PyRefTracer}@anchor{58ee}
@deffn {C Τύπος} typedef int (*PyRefTracer)(@ref{19b,,PyObject}*, int event, void *data)

The type of the trace function registered using @ref{805,,PyRefTracer_SetTracer()}.
The first parameter is a Python object that has been just created (when `event'
is set to @ref{58ef,,PyRefTracer_CREATE}) or about to be destroyed (when `event'
is set to @ref{58f0,,PyRefTracer_DESTROY}). The `data' argument is the opaque pointer
that was provided when @code{PyRefTracer_SetTracer()} was called.

If a new tracing function is registered replacing the current one, a call to the
trace function will be made with the object set to `NULL' and `event' set to
@ref{1a4b,,PyRefTracer_TRACKER_REMOVED}. This will happen just before the new
function is registered.
@end deffn


Added in version 3.13.


@geindex PyRefTracer_CREATE (C var)
@anchor{c-api/profiling c PyRefTracer_CREATE}@anchor{58ef}
@deffn {C Μεταβλητή} int PyRefTracer_CREATE

The value for the `event' parameter to @ref{58ee,,PyRefTracer} functions when a Python
object has been created.
@end deffn

@geindex PyRefTracer_DESTROY (C var)
@anchor{c-api/profiling c PyRefTracer_DESTROY}@anchor{58f0}
@deffn {C Μεταβλητή} int PyRefTracer_DESTROY

The value for the `event' parameter to @ref{58ee,,PyRefTracer} functions when a Python
object has been destroyed.
@end deffn

@geindex PyRefTracer_TRACKER_REMOVED (C var)
@anchor{c-api/profiling c PyRefTracer_TRACKER_REMOVED}@anchor{1a4b}
@deffn {C Μεταβλητή} int PyRefTracer_TRACKER_REMOVED

The value for the `event' parameter to @ref{58ee,,PyRefTracer} functions when the
current tracer is about to be replaced by a new one.


Added in version 3.14.

@end deffn

@geindex PyRefTracer_SetTracer (C function)
@anchor{c-api/profiling c PyRefTracer_SetTracer}@anchor{805}
@deffn {C Συνάρτηση} int PyRefTracer_SetTracer (PyRefTracer tracer, void *data)

Register a reference tracer function. The function will be called when a new
Python object 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.

Note 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.  A @ref{1a70,,thread state} will be active
every time the tracer function is called.

There must be an @ref{1a1,,attached thread state} when calling this function.

If another tracer function was already registered, the old function will be
called with `event' set to @ref{1a4b,,PyRefTracer_TRACKER_REMOVED} just before
the new function is registered.
@end deffn


Added in version 3.13.


@geindex PyRefTracer_GetTracer (C function)
@anchor{c-api/profiling c PyRefTracer_GetTracer}@anchor{806}
@deffn {C Συνάρτηση} @ref{58ee,,PyRefTracer} PyRefTracer_GetTracer (void **data)

Get the registered reference tracer function and the value of the opaque data
pointer that was registered when @ref{805,,PyRefTracer_SetTracer()} was called.
If no tracer was registered this function will return NULL and will set the
`data' pointer to NULL.

There must be an @ref{1a1,,attached thread state} when calling this function.
@end deffn


Added in version 3.13.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python Initialization Configuration,Memory Management,Reference tracing,Python/C API reference manual
@anchor{c-api/init_config doc}@anchor{58f1}@anchor{c-api/init_config init-config}@anchor{837}@anchor{c-api/init_config python-initialization-configuration}@anchor{58f2}@anchor{c-api/init_config translation-repo}@anchor{58f3}
@section Python Initialization Configuration


@menu
* PyInitConfig C API:: 
* Configuration Options:: 
* Runtime Python configuration API:: 
* PyConfig C API:: 
* Py_GetArgcArgv(): Py_GetArgcArgv. 
* Multi-Phase Initialization Private Provisional API:: 

@end menu

@node PyInitConfig C API,Configuration Options,,Python Initialization Configuration
@anchor{c-api/init_config pyinitconfig-api}@anchor{5a7}@anchor{c-api/init_config pyinitconfig-c-api}@anchor{58f4}
@subsection PyInitConfig C API



Added in version 3.14.


Python can be initialized with @ref{5b3,,Py_InitializeFromInitConfig()}.

The @ref{d8d,,Py_RunMain()} function can be used to write a customized Python
program.

See also @ref{5884,,Initialization@comma{} Finalization@comma{} and Threads}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 741
PEP 741@footnote{https://peps.python.org/pep-0741/} «Python Configuration C API».


@menu
* Example: Example<15>. 
* Create Config:: 
* Error Handling:: 
* Get Options:: 
* Set Options:: 
* Module:: 
* Initialize Python:: 

@end menu

@node Example<15>,Create Config,,PyInitConfig C API
@anchor{c-api/init_config example}@anchor{58f5}
@subsubsection Example


Example of customized Python always running with the @ref{70d,,Python Development Mode} enabled; return @code{-1} on error:

@example
int init_python(void)
@{
    PyInitConfig *config = PyInitConfig_Create();
    if (config == NULL) @{
        printf("PYTHON INIT ERROR: memory allocation failed\n");
        return -1;
    @}

    // Enable the Python Development Mode
    if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) @{
        goto error;
    @}

    // Initialize Python with the configuration
    if (Py_InitializeFromInitConfig(config) < 0) @{
        goto error;
    @}
    PyInitConfig_Free(config);
    return 0;

error:
    @{
        // Display the error message.
        //
        // This uncommon braces style is used, because you cannot make
        // goto targets point to variable declarations.
        const char *err_msg;
        (void)PyInitConfig_GetError(config, &err_msg);
        printf("PYTHON INIT ERROR: %s\n", err_msg);
        PyInitConfig_Free(config);
        return -1;
    @}
@}
@end example

@node Create Config,Error Handling,Example<15>,PyInitConfig C API
@anchor{c-api/init_config create-config}@anchor{58f6}
@subsubsection Create Config


@geindex PyInitConfig (C struct)
@anchor{c-api/init_config c PyInitConfig}@anchor{58f7}
@deffn {C Struct} struct PyInitConfig

Opaque structure to configure the Python initialization.
@end deffn

@geindex PyInitConfig_Create (C function)
@anchor{c-api/init_config c PyInitConfig_Create}@anchor{5b4}
@deffn {C Συνάρτηση} @ref{58f7,,PyInitConfig} *PyInitConfig_Create (void)

Create a new initialization configuration using @ref{58f8,,Isolated Configuration} default values.

It must be freed by @ref{5b5,,PyInitConfig_Free()}.

Return @code{NULL} on memory allocation failure.
@end deffn

@geindex PyInitConfig_Free (C function)
@anchor{c-api/init_config c PyInitConfig_Free}@anchor{5b5}
@deffn {C Συνάρτηση} void PyInitConfig_Free (PyInitConfig *config)

Free memory of the initialization configuration `config'.

If `config' is @code{NULL}, no operation is performed.
@end deffn

@node Error Handling,Get Options,Create Config,PyInitConfig C API
@anchor{c-api/init_config error-handling}@anchor{58f9}
@subsubsection Error Handling


@geindex PyInitConfig_GetError (C function)
@anchor{c-api/init_config c PyInitConfig_GetError}@anchor{5b7}
@deffn {C Συνάρτηση} int PyInitConfig_GetError (PyInitConfig *config, const char **err_msg)

Get the `config' error message.


@itemize *

@item 
Set `*err_msg' and return @code{1} if an error is set.

@item 
Set `*err_msg' to @code{NULL} and return @code{0} otherwise.
@end itemize

An error message is a UTF-8 encoded string.

If `config' has an exit code, format the exit code as an error
message.

The error message remains valid until another @code{PyInitConfig}
function is called with `config'. The caller doesn’t have to free the
error message.
@end deffn

@geindex PyInitConfig_GetExitCode (C function)
@anchor{c-api/init_config c PyInitConfig_GetExitCode}@anchor{5b8}
@deffn {C Συνάρτηση} int PyInitConfig_GetExitCode (PyInitConfig *config, int *exitcode)

Get the `config' exit code.


@itemize *

@item 
Set `*exitcode' and return @code{1} if `config' has an exit code set.

@item 
Return @code{0} if `config' has no exit code set.
@end itemize

Only the @code{Py_InitializeFromInitConfig()} function can set an exit
code if the @code{parse_argv} option is non-zero.

An exit code can be set when parsing the command line failed (exit
code @code{2}) or when a command line option asks to display the command
line help (exit code @code{0}).
@end deffn

@node Get Options,Set Options,Error Handling,PyInitConfig C API
@anchor{c-api/init_config get-options}@anchor{58fa}
@subsubsection Get Options


The configuration option `name' parameter must be a non-NULL null-terminated
UTF-8 encoded string. See @ref{58fb,,Configuration Options}.

@geindex PyInitConfig_HasOption (C function)
@anchor{c-api/init_config c PyInitConfig_HasOption}@anchor{5bc}
@deffn {C Συνάρτηση} int PyInitConfig_HasOption (PyInitConfig *config, const char *name)

Test if the configuration has an option called `name'.

Return @code{1} if the option exists, or return @code{0} otherwise.
@end deffn

@geindex PyInitConfig_GetInt (C function)
@anchor{c-api/init_config c PyInitConfig_GetInt}@anchor{5b9}
@deffn {C Συνάρτηση} int PyInitConfig_GetInt (PyInitConfig *config, const char *name, int64_t *value)

Get an integer configuration option.


@itemize *

@item 
Set `*value', and return @code{0} on success.

@item 
Set an error in `config' and return @code{-1} on error.
@end itemize
@end deffn

@geindex PyInitConfig_GetStr (C function)
@anchor{c-api/init_config c PyInitConfig_GetStr}@anchor{5ba}
@deffn {C Συνάρτηση} int PyInitConfig_GetStr (PyInitConfig *config, const char *name, char **value)

Get a string configuration option as a null-terminated UTF-8
encoded string.


@itemize *

@item 
Set `*value', and return @code{0} on success.

@item 
Set an error in `config' and return @code{-1} on error.
@end itemize

`*value' can be set to @code{NULL} if the option is an optional string and the
option is unset.

On success, the string must be released with @code{free(value)} if it’s not
@code{NULL}.
@end deffn

@geindex PyInitConfig_GetStrList (C function)
@anchor{c-api/init_config c PyInitConfig_GetStrList}@anchor{5bb}
@deffn {C Συνάρτηση} int PyInitConfig_GetStrList (PyInitConfig *config, const char *name, size_t *length, char ***items)

Get a string list configuration option as an array of
null-terminated UTF-8 encoded strings.


@itemize *

@item 
Set `*length' and `*value', and return @code{0} on success.

@item 
Set an error in `config' and return @code{-1} on error.
@end itemize

On success, the string list must be released with
@code{PyInitConfig_FreeStrList(length, items)}.
@end deffn

@geindex PyInitConfig_FreeStrList (C function)
@anchor{c-api/init_config c PyInitConfig_FreeStrList}@anchor{5b6}
@deffn {C Συνάρτηση} void PyInitConfig_FreeStrList (size_t length, char **items)

Free memory of a string list created by
@code{PyInitConfig_GetStrList()}.
@end deffn

@node Set Options,Module,Get Options,PyInitConfig C API
@anchor{c-api/init_config set-options}@anchor{58fc}
@subsubsection Set Options


The configuration option `name' parameter must be a non-NULL null-terminated
UTF-8 encoded string. See @ref{58fb,,Configuration Options}.

Some configuration options have side effects on other options. This logic is
only implemented when @code{Py_InitializeFromInitConfig()} is called, not by the
«Set» functions below. For example, setting @code{dev_mode} to @code{1} does not set
@code{faulthandler} to @code{1}.

@geindex PyInitConfig_SetInt (C function)
@anchor{c-api/init_config c PyInitConfig_SetInt}@anchor{5bd}
@deffn {C Συνάρτηση} int PyInitConfig_SetInt (PyInitConfig *config, const char *name, int64_t value)

Set an integer configuration option.


@itemize *

@item 
Return @code{0} on success.

@item 
Set an error in `config' and return @code{-1} on error.
@end itemize
@end deffn

@geindex PyInitConfig_SetStr (C function)
@anchor{c-api/init_config c PyInitConfig_SetStr}@anchor{5be}
@deffn {C Συνάρτηση} int PyInitConfig_SetStr (PyInitConfig *config, const char *name, const char *value)

Set a string configuration option from a null-terminated UTF-8
encoded string. The string is copied.


@itemize *

@item 
Return @code{0} on success.

@item 
Set an error in `config' and return @code{-1} on error.
@end itemize
@end deffn

@geindex PyInitConfig_SetStrList (C function)
@anchor{c-api/init_config c PyInitConfig_SetStrList}@anchor{5bf}
@deffn {C Συνάρτηση} int PyInitConfig_SetStrList (PyInitConfig *config, const char *name, size_t length, char *const *items)

Set a string list configuration option from an array of
null-terminated UTF-8 encoded strings. The string list is copied.


@itemize *

@item 
Return @code{0} on success.

@item 
Set an error in `config' and return @code{-1} on error.
@end itemize
@end deffn

@node Module,Initialize Python,Set Options,PyInitConfig C API
@anchor{c-api/init_config module}@anchor{58fd}
@subsubsection Module


@geindex PyInitConfig_AddModule (C function)
@anchor{c-api/init_config c PyInitConfig_AddModule}@anchor{5a9}
@deffn {C Συνάρτηση} int PyInitConfig_AddModule (PyInitConfig *config, const char *name, PyObject *(*initfunc)(void))

Add a built-in extension module to the table of built-in modules.

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.


@itemize *

@item 
Return @code{0} on success.

@item 
Set an error in `config' and return @code{-1} on error.
@end itemize

If Python is initialized multiple times, @code{PyInitConfig_AddModule()} must
be called at each Python initialization.

Similar to the @ref{1d1a,,PyImport_AppendInittab()} function.
@end deffn

@node Initialize Python,,Module,PyInitConfig C API
@anchor{c-api/init_config initialize-python}@anchor{58fe}
@subsubsection Initialize Python


@geindex Py_InitializeFromInitConfig (C function)
@anchor{c-api/init_config c Py_InitializeFromInitConfig}@anchor{5b3}
@deffn {C Συνάρτηση} int Py_InitializeFromInitConfig (PyInitConfig *config)

Initialize Python from the initialization configuration.


@itemize *

@item 
Return @code{0} on success.

@item 
Set an error in `config' and return @code{-1} on error.

@item 
Set an exit code in `config' and return @code{-1} if Python wants to
exit.
@end itemize

See @code{PyInitConfig_GetExitcode()} for the exit code case.
@end deffn

@node Configuration Options,Runtime Python configuration API,PyInitConfig C API,Python Initialization Configuration
@anchor{c-api/init_config configuration-options}@anchor{58ff}@anchor{c-api/init_config pyinitconfig-opts}@anchor{58fb}
@subsection Configuration Options



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

PyConfig/PyPreConfig member

@tab

Type

@tab

Visibility

@item

@code{"allocator"}

@tab

@ref{5900,,allocator}

@tab

@code{int}

@tab

Read-only

@item

@code{"argv"}

@tab

@ref{607,,argv}

@tab

@code{list[str]}

@tab

Public

@item

@code{"base_exec_prefix"}

@tab

@ref{5901,,base_exec_prefix}

@tab

@code{str}

@tab

Public

@item

@code{"base_executable"}

@tab

@ref{5902,,base_executable}

@tab

@code{str}

@tab

Public

@item

@code{"base_prefix"}

@tab

@ref{5903,,base_prefix}

@tab

@code{str}

@tab

Public

@item

@code{"buffered_stdio"}

@tab

@ref{624,,buffered_stdio}

@tab

@code{bool}

@tab

Read-only

@item

@code{"bytes_warning"}

@tab

@ref{3c4,,bytes_warning}

@tab

@code{int}

@tab

Public

@item

@code{"check_hash_pycs_mode"}

@tab

@ref{5904,,check_hash_pycs_mode}

@tab

@code{str}

@tab

Read-only

@item

@code{"code_debug_ranges"}

@tab

@ref{5905,,code_debug_ranges}

@tab

@code{bool}

@tab

Read-only

@item

@code{"coerce_c_locale"}

@tab

@ref{5906,,coerce_c_locale}

@tab

@code{bool}

@tab

Read-only

@item

@code{"coerce_c_locale_warn"}

@tab

@ref{5907,,coerce_c_locale_warn}

@tab

@code{bool}

@tab

Read-only

@item

@code{"configure_c_stdio"}

@tab

@ref{5908,,configure_c_stdio}

@tab

@code{bool}

@tab

Read-only

@item

@code{"configure_locale"}

@tab

@ref{5909,,configure_locale}

@tab

@code{bool}

@tab

Read-only

@item

@code{"cpu_count"}

@tab

@ref{590a,,cpu_count}

@tab

@code{int}

@tab

Public

@item

@code{"dev_mode"}

@tab

@ref{590b,,dev_mode}

@tab

@code{bool}

@tab

Read-only

@item

@code{"dump_refs"}

@tab

@ref{590c,,dump_refs}

@tab

@code{bool}

@tab

Read-only

@item

@code{"dump_refs_file"}

@tab

@ref{590d,,dump_refs_file}

@tab

@code{str}

@tab

Read-only

@item

@code{"exec_prefix"}

@tab

@ref{590e,,exec_prefix}

@tab

@code{str}

@tab

Public

@item

@code{"executable"}

@tab

@ref{836,,executable}

@tab

@code{str}

@tab

Public

@item

@code{"faulthandler"}

@tab

@ref{590f,,faulthandler}

@tab

@code{bool}

@tab

Read-only

@item

@code{"filesystem_encoding"}

@tab

@ref{62e,,filesystem_encoding}

@tab

@code{str}

@tab

Read-only

@item

@code{"filesystem_errors"}

@tab

@ref{62f,,filesystem_errors}

@tab

@code{str}

@tab

Read-only

@item

@code{"hash_seed"}

@tab

@ref{627,,hash_seed}

@tab

@code{int}

@tab

Read-only

@item

@code{"home"}

@tab

@ref{609,,home}

@tab

@code{str}

@tab

Read-only

@item

@code{"import_time"}

@tab

@ref{5910,,import_time}

@tab

@code{int}

@tab

Read-only

@item

@code{"inspect"}

@tab

@ref{615,,inspect}

@tab

@code{bool}

@tab

Public

@item

@code{"install_signal_handlers"}

@tab

@ref{c91,,install_signal_handlers}

@tab

@code{bool}

@tab

Read-only

@item

@code{"int_max_str_digits"}

@tab

@ref{5911,,int_max_str_digits}

@tab

@code{int}

@tab

Public

@item

@code{"interactive"}

@tab

@ref{613,,interactive}

@tab

@code{bool}

@tab

Public

@item

@code{"isolated"}

@tab

@ref{629,,isolated}

@tab

@code{bool}

@tab

Read-only

@item

@code{"legacy_windows_fs_encoding"}

@tab

@ref{62b,,legacy_windows_fs_encoding}

@tab

@code{bool}

@tab

Read-only

@item

@code{"legacy_windows_stdio"}

@tab

@ref{62d,,legacy_windows_stdio}

@tab

@code{bool}

@tab

Read-only

@item

@code{"malloc_stats"}

@tab

@ref{5912,,malloc_stats}

@tab

@code{bool}

@tab

Read-only

@item

@code{"module_search_paths"}

@tab

@ref{834,,module_search_paths}

@tab

@code{list[str]}

@tab

Public

@item

@code{"optimization_level"}

@tab

@ref{617,,optimization_level}

@tab

@code{int}

@tab

Public

@item

@code{"orig_argv"}

@tab

@ref{c6a,,orig_argv}

@tab

@code{list[str]}

@tab

Read-only

@item

@code{"parse_argv"}

@tab

@ref{1ee6,,parse_argv}

@tab

@code{bool}

@tab

Read-only

@item

@code{"parser_debug"}

@tab

@ref{60d,,parser_debug}

@tab

@code{bool}

@tab

Public

@item

@code{"pathconfig_warnings"}

@tab

@ref{61c,,pathconfig_warnings}

@tab

@code{bool}

@tab

Read-only

@item

@code{"perf_profiling"}

@tab

@ref{5913,,perf_profiling}

@tab

@code{bool}

@tab

Read-only

@item

@code{"platlibdir"}

@tab

@ref{1f16,,platlibdir}

@tab

@code{str}

@tab

Public

@item

@code{"prefix"}

@tab

@ref{5914,,prefix}

@tab

@code{str}

@tab

Public

@item

@code{"program_name"}

@tab

@ref{608,,program_name}

@tab

@code{str}

@tab

Read-only

@item

@code{"pycache_prefix"}

@tab

@ref{5915,,pycache_prefix}

@tab

@code{str}

@tab

Public

@item

@code{"quiet"}

@tab

@ref{611,,quiet}

@tab

@code{bool}

@tab

Public

@item

@code{"run_command"}

@tab

@ref{588f,,run_command}

@tab

@code{str}

@tab

Read-only

@item

@code{"run_filename"}

@tab

@ref{5890,,run_filename}

@tab

@code{str}

@tab

Read-only

@item

@code{"run_module"}

@tab

@ref{5891,,run_module}

@tab

@code{str}

@tab

Read-only

@item

@code{"run_presite"}

@tab

@ref{5916,,run_presite}

@tab

@code{str}

@tab

Read-only

@item

@code{"safe_path"}

@tab

@ref{b55,,safe_path}

@tab

@code{bool}

@tab

Read-only

@item

@code{"show_ref_count"}

@tab

@ref{5917,,show_ref_count}

@tab

@code{bool}

@tab

Read-only

@item

@code{"site_import"}

@tab

@ref{619,,site_import}

@tab

@code{bool}

@tab

Read-only

@item

@code{"skip_source_first_line"}

@tab

@ref{5918,,skip_source_first_line}

@tab

@code{bool}

@tab

Read-only

@item

@code{"stdio_encoding"}

@tab

@ref{835,,stdio_encoding}

@tab

@code{str}

@tab

Read-only

@item

@code{"stdio_errors"}

@tab

@ref{4c0c,,stdio_errors}

@tab

@code{str}

@tab

Read-only

@item

@code{"stdlib_dir"}

@tab

@ref{5919,,stdlib_dir}

@tab

@code{str}

@tab

Public

@item

@code{"tracemalloc"}

@tab

@ref{591a,,tracemalloc}

@tab

@code{int}

@tab

Read-only

@item

@code{"use_environment"}

@tab

@ref{61e,,use_environment}

@tab

@code{bool}

@tab

Public

@item

@code{"use_frozen_modules"}

@tab

@ref{591b,,use_frozen_modules}

@tab

@code{bool}

@tab

Read-only

@item

@code{"use_hash_seed"}

@tab

@ref{626,,use_hash_seed}

@tab

@code{bool}

@tab

Read-only

@item

@code{"use_system_logger"}

@tab

@ref{2462,,use_system_logger}

@tab

@code{bool}

@tab

Read-only

@item

@code{"user_site_directory"}

@tab

@ref{622,,user_site_directory}

@tab

@code{bool}

@tab

Read-only

@item

@code{"utf8_mode"}

@tab

@ref{630,,utf8_mode}

@tab

@code{bool}

@tab

Read-only

@item

@code{"verbose"}

@tab

@ref{60f,,verbose}

@tab

@code{int}

@tab

Public

@item

@code{"warn_default_encoding"}

@tab

@ref{591c,,warn_default_encoding}

@tab

@code{bool}

@tab

Read-only

@item

@code{"warnoptions"}

@tab

@ref{832,,warnoptions}

@tab

@code{list[str]}

@tab

Public

@item

@code{"write_bytecode"}

@tab

@ref{620,,write_bytecode}

@tab

@code{bool}

@tab

Public

@item

@code{"xoptions"}

@tab

@ref{833,,xoptions}

@tab

@code{dict[str, str]}

@tab

Public

@item

@code{"_pystats"}

@tab

@ref{591d,,_pystats}

@tab

@code{bool}

@tab

Read-only

@end multitable


Visibility:


@itemize *

@item 
Public: Can be retrieved by @ref{3a6,,PyConfig_Get()} and set by
@ref{5aa,,PyConfig_Set()}.

@item 
Read-only: Can be retrieved by @ref{3a6,,PyConfig_Get()}, but cannot be set by
@ref{5aa,,PyConfig_Set()}.
@end itemize

@node Runtime Python configuration API,PyConfig C API,Configuration Options,Python Initialization Configuration
@anchor{c-api/init_config runtime-python-configuration-api}@anchor{591e}
@subsection Runtime Python configuration API


At runtime, it’s possible to get and set configuration options using
@ref{3a6,,PyConfig_Get()} and  @ref{5aa,,PyConfig_Set()} functions.

The configuration option `name' parameter must be a non-NULL null-terminated
UTF-8 encoded string. See @ref{58fb,,Configuration Options}.

Some options are read from the @ref{e2,,sys} attributes. For example, the option
@code{"argv"} is read from @ref{1609,,sys.argv}.

@geindex PyConfig_Get (C function)
@anchor{c-api/init_config c PyConfig_Get}@anchor{3a6}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyConfig_Get (const char *name)

Get the current runtime value of a configuration option as a Python object.


@itemize *

@item 
Return a new reference on success.

@item 
Set an exception and return @code{NULL} on error.
@end itemize

The object type depends on the configuration option. It can be:


@itemize *

@item 
@code{bool}

@item 
@code{int}

@item 
@code{str}

@item 
@code{list[str]}

@item 
@code{dict[str, str]}
@end itemize

The caller must have an @ref{1a1,,attached thread state}. The function cannot
be called before Python initialization nor after Python finalization.


Added in version 3.14.

@end deffn

@geindex PyConfig_GetInt (C function)
@anchor{c-api/init_config c PyConfig_GetInt}@anchor{5b1}
@deffn {C Συνάρτηση} int PyConfig_GetInt (const char *name, int *value)

Similar to @ref{3a6,,PyConfig_Get()}, but get the value as a C int.


@itemize *

@item 
Return @code{0} on success.

@item 
Set an exception and return @code{-1} on error.
@end itemize


Added in version 3.14.

@end deffn

@geindex PyConfig_Names (C function)
@anchor{c-api/init_config c PyConfig_Names}@anchor{5b2}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyConfig_Names (void)

Get all configuration option names as a @code{frozenset}.


@itemize *

@item 
Return a new reference on success.

@item 
Set an exception and return @code{NULL} on error.
@end itemize

The caller must have an @ref{1a1,,attached thread state}. The function cannot
be called before Python initialization nor after Python finalization.


Added in version 3.14.

@end deffn

@geindex PyConfig_Set (C function)
@anchor{c-api/init_config c PyConfig_Set}@anchor{5aa}
@deffn {C Συνάρτηση} int PyConfig_Set (const char *name, PyObject *value)

Set the current runtime value of a configuration option.


@itemize *

@item 
Raise a @ref{277,,ValueError} if there is no option `name'.

@item 
Raise a @ref{277,,ValueError} if `value' is an invalid value.

@item 
Raise a @ref{277,,ValueError} if the option is read-only (cannot be set).

@item 
Raise a @ref{291,,TypeError} if `value' has not the proper type.
@end itemize

The caller must have an @ref{1a1,,attached thread state}. The function cannot
be called before Python initialization nor after Python finalization.

Raises an @ref{1e65,,auditing event} @code{cpython.PyConfig_Set} with arguments @code{name}, @code{value}.


Added in version 3.14.

@end deffn

@node PyConfig C API,Py_GetArgcArgv,Runtime Python configuration API,Python Initialization Configuration
@anchor{c-api/init_config pyconfig-api}@anchor{5a8}@anchor{c-api/init_config pyconfig-c-api}@anchor{591f}
@subsection PyConfig C API



Added in version 3.8.


Python can be initialized with @ref{60a,,Py_InitializeFromConfig()} and the
@ref{60b,,PyConfig} structure. It can be preinitialized with
@ref{631,,Py_PreInitialize()} and the @ref{d74,,PyPreConfig} structure.

There are two kinds of configuration:


@itemize *

@item 
The @ref{5892,,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{58f8,,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{d8d,,Py_RunMain()} function can be used to write a customized Python
program.

See also @ref{5884,,Initialization@comma{} Finalization@comma{} and Threads}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/} «Python Initialization Configuration».


@menu
* Example: Example<16>. 
* PyWideStringList:: 
* PyStatus:: 
* PyPreConfig:: 
* Preinitialize Python with PyPreConfig:: 
* PyConfig:: 
* Initialization with PyConfig:: 
* Isolated Configuration:: 
* Python Configuration:: 
* Python Path Configuration:: 

@end menu

@node Example<16>,PyWideStringList,,PyConfig C API
@anchor{c-api/init_config id1}@anchor{5920}
@subsubsection 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<16>,PyConfig C API
@anchor{c-api/init_config pywidestringlist}@anchor{5921}
@subsubsection PyWideStringList


@geindex PyWideStringList (C type)
@anchor{c-api/init_config c PyWideStringList}@anchor{d76}
@deffn {C Τύπος} 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{d87}
@deffn {C Συνάρτηση} @ref{d75,,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{d88}
@deffn {C Συνάρτηση} @ref{d75,,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{5922}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} length

List length.
@end deffn

@geindex PyWideStringList.items (C member)
@anchor{c-api/init_config c PyWideStringList items}@anchor{5923}
@deffn {C Μέλος} wchar_t **items

List items.
@end deffn
@end deffn

@node PyStatus,PyPreConfig,PyWideStringList,PyConfig C API
@anchor{c-api/init_config pystatus}@anchor{5924}
@subsubsection PyStatus


@geindex PyStatus (C type)
@anchor{c-api/init_config c PyStatus}@anchor{d75}
@deffn {C Τύπος} 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{5925}
@deffn {C Μέλος} 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{5926}
@deffn {C Μέλος} const char *err_msg

Error message.
@end deffn

@geindex PyStatus.func (C member)
@anchor{c-api/init_config c PyStatus func}@anchor{5927}
@deffn {C Μέλος} 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{d86}
@deffn {C Συνάρτηση} @ref{d75,,PyStatus} PyStatus_Ok (void)

Success.
@end deffn

@geindex PyStatus_Error (C function)
@anchor{c-api/init_config c PyStatus_Error}@anchor{d80}
@deffn {C Συνάρτηση} @ref{d75,,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{d85}
@deffn {C Συνάρτηση} @ref{d75,,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{d82}
@deffn {C Συνάρτηση} @ref{d75,,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{d81}
@deffn {C Συνάρτηση} int PyStatus_Exception (PyStatus status)

Is the status an error or an exit? If true, the exception must be
handled; by calling @ref{d8a,,Py_ExitStatusException()} for example.
@end deffn

@geindex PyStatus_IsError (C function)
@anchor{c-api/init_config c PyStatus_IsError}@anchor{d83}
@deffn {C Συνάρτηση} 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{d84}
@deffn {C Συνάρτηση} 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{d8a}
@deffn {C Συνάρτηση} 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 Σημείωση 
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

Example:

@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,PyConfig C API
@anchor{c-api/init_config pypreconfig}@anchor{5928}
@subsubsection PyPreConfig


@geindex PyPreConfig (C type)
@anchor{c-api/init_config c PyPreConfig}@anchor{d74}
@deffn {C Τύπος} 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{d7f}
@deffn {C Συνάρτηση} void PyPreConfig_InitPythonConfig (PyPreConfig *preconfig)

Initialize the preconfiguration with @ref{5892,,Python Configuration}.
@end deffn

@geindex PyPreConfig_InitIsolatedConfig (C function)
@anchor{c-api/init_config c PyPreConfig_InitIsolatedConfig}@anchor{d7e}
@deffn {C Συνάρτηση} void PyPreConfig_InitIsolatedConfig (PyPreConfig *preconfig)

Initialize the preconfiguration with @ref{58f8,,Isolated Configuration}.
@end deffn

Structure fields:

@geindex PyPreConfig.allocator (C member)
@anchor{c-api/init_config c PyPreConfig allocator}@anchor{5900}
@deffn {C Μέλος} 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{2329,,default memory allocators}.

@item 
@code{PYMEM_ALLOCATOR_DEBUG} (@code{2}): @ref{2329,,default memory allocators} with @ref{232c,,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{232c,,debug hooks}.

@item 
@code{PYMEM_ALLOCATOR_PYMALLOC} (@code{5}): @ref{3da,,Python pymalloc memory allocator}.

@item 
@code{PYMEM_ALLOCATOR_PYMALLOC_DEBUG} (@code{6}): @ref{3da,,Python pymalloc memory allocator} with @ref{232c,,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{232c,,debug hooks}.
@end itemize

@code{PYMEM_ALLOCATOR_PYMALLOC} and @code{PYMEM_ALLOCATOR_PYMALLOC_DEBUG} are
not supported if Python is @ref{238d,,configured using --without-pymalloc}.

@code{PYMEM_ALLOCATOR_MIMALLOC} and @code{PYMEM_ALLOCATOR_MIMALLOC_DEBUG} are
not supported if Python is @ref{238c,,configured using --without-mimalloc} or if the underlying atomic support isn’t
available.

See @ref{5929,,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{5909}
@deffn {C Μέλος} int configure_locale

Set the LC_CTYPE locale to the user preferred locale.

If equals to @code{0}, set @ref{5906,,coerce_c_locale} and
@ref{5907,,coerce_c_locale_warn} members to @code{0}.

See the @ref{74d,,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{5906}
@deffn {C Μέλος} 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{74d,,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{5907}
@deffn {C Μέλος} 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{592a}
@deffn {C Μέλος} int dev_mode

@ref{70d,,Python Development Mode}: see
@ref{590b,,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{592b}
@deffn {C Μέλος} int isolated

Isolated mode: see @ref{629,,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{62b}
@deffn {C Μέλος} int legacy_windows_fs_encoding

If non-zero:


@itemize *

@item 
Set @ref{630,,PyPreConfig.utf8_mode} to @code{0},

@item 
Set @ref{62e,,PyConfig.filesystem_encoding} to @code{"mbcs"},

@item 
Set @ref{62f,,PyConfig.filesystem_errors} to @code{"replace"}.
@end itemize

Initialized from the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,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{592c}
@deffn {C Μέλος} int parse_argv

If non-zero, @ref{d8b,,Py_PreInitializeFromArgs()} and
@ref{d8c,,Py_PreInitializeFromBytesArgs()} parse their @code{argv} argument the
same way the regular Python parses command line arguments: see
@ref{13b0,,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{592d}
@deffn {C Μέλος} int use_environment

Use @ref{9e8,,environment variables}? See
@ref{61e,,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{630}
@deffn {C Μέλος} int utf8_mode

If non-zero, enable the @ref{a46,,Python UTF-8 Mode}.

Set to @code{0} or @code{1} by the @ref{178,,-X utf8} command line option
and the 
@geindex PYTHONUTF8
@geindex μεταβλητή περιβάλλοντος; PYTHONUTF8
@ref{1ad,,PYTHONUTF8} environment variable.

Default: @code{1}.
@end deffn
@end deffn

@node Preinitialize Python with PyPreConfig,PyConfig,PyPreConfig,PyConfig C API
@anchor{c-api/init_config c-preinit}@anchor{4516}@anchor{c-api/init_config preinitialize-python-with-pypreconfig}@anchor{592e}
@subsubsection Preinitialize Python with PyPreConfig


The preinitialization of Python:


@itemize *

@item 
Set the Python memory allocators (@ref{5900,,PyPreConfig.allocator})

@item 
Configure the LC_CTYPE locale (@ref{74d,,locale encoding})

@item 
Set the @ref{a46,,Python UTF-8 Mode}
(@ref{630,,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{631}
@deffn {C Συνάρτηση} @ref{d75,,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{d8c}
@deffn {C Συνάρτηση} @ref{d75,,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{592c,,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{d8b}
@deffn {C Συνάρτηση} @ref{d75,,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{592c,,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{d81,,PyStatus_Exception()} and @ref{d8a,,Py_ExitStatusException()}.

For @ref{5892,,Python Configuration}
(@ref{d7f,,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{178,,-X utf8} command line option
enables the @ref{a46,,Python UTF-8 Mode}.

@code{PyMem_SetAllocator()} can be called after @ref{631,,Py_PreInitialize()} and
before @ref{60a,,Py_InitializeFromConfig()} to install a custom memory allocator.
It can be called before @code{Py_PreInitialize()} if
@ref{5900,,PyPreConfig.allocator} is set to @code{PYMEM_ALLOCATOR_NOT_SET}.

Python memory allocation functions like @ref{2bf,,PyMem_RawMalloc()} must not be
used before the Python preinitialization, whereas calling directly @code{malloc()}
and @code{free()} is always safe. @ref{f85,,Py_DecodeLocale()} must not be called
before the Python preinitialization.

Example using the preinitialization to enable
the @ref{a46,,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,PyConfig C API
@anchor{c-api/init_config pyconfig}@anchor{592f}
@subsubsection PyConfig


@geindex PyConfig (C type)
@anchor{c-api/init_config c PyConfig}@anchor{60b}
@deffn {C Τύπος} type PyConfig

Structure containing most parameters to configure Python.

When done, the @ref{d77,,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{d79}
@deffn {C Συνάρτηση} void PyConfig_InitPythonConfig (PyConfig *config)

Initialize configuration with the @ref{5892,,Python Configuration}.
@end deffn

@geindex PyConfig_InitIsolatedConfig (C function)
@anchor{c-api/init_config c PyConfig_InitIsolatedConfig}@anchor{d78}
@deffn {C Συνάρτηση} void PyConfig_InitIsolatedConfig (PyConfig *config)

Initialize configuration with the @ref{58f8,,Isolated Configuration}.
@end deffn

@geindex PyConfig_SetString (C function)
@anchor{c-api/init_config c PyConfig_SetString}@anchor{d7d}
@deffn {C Συνάρτηση} @ref{d75,,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{4516,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_SetBytesString (C function)
@anchor{c-api/init_config c PyConfig_SetBytesString}@anchor{d7c}
@deffn {C Συνάρτηση} @ref{d75,,PyStatus} PyConfig_SetBytesString (PyConfig *config, wchar_t *const *config_str, const char *str)

Decode `str' using @ref{f85,,Py_DecodeLocale()} and set the result into
@code{*config_str}.

@ref{4516,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_SetArgv (C function)
@anchor{c-api/init_config c PyConfig_SetArgv}@anchor{d7a}
@deffn {C Συνάρτηση} @ref{d75,,PyStatus} PyConfig_SetArgv (PyConfig *config, int argc, wchar_t *const *argv)

Set command line arguments (@ref{607,,argv} member of
`config') from the `argv' list of wide character strings.

@ref{4516,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_SetBytesArgv (C function)
@anchor{c-api/init_config c PyConfig_SetBytesArgv}@anchor{d7b}
@deffn {C Συνάρτηση} @ref{d75,,PyStatus} PyConfig_SetBytesArgv (PyConfig *config, int argc, char *const *argv)

Set command line arguments (@ref{607,,argv} member of
`config') from the `argv' list of bytes strings. Decode bytes using
@ref{f85,,Py_DecodeLocale()}.

@ref{4516,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_SetWideStringList (C function)
@anchor{c-api/init_config c PyConfig_SetWideStringList}@anchor{1fb9}
@deffn {C Συνάρτηση} @ref{d75,,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{4516,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_Read (C function)
@anchor{c-api/init_config c PyConfig_Read}@anchor{b6f}
@deffn {C Συνάρτηση} @ref{d75,,PyStatus} PyConfig_Read (PyConfig *config)

Read all Python configuration.

Fields which are already initialized are left unchanged.

Fields for @ref{c80,,path configuration} are no longer
calculated or modified when calling this function, as of Python 3.11.

The @ref{b6f,,PyConfig_Read()} function only parses
@ref{607,,PyConfig.argv} arguments once: @ref{1ee6,,PyConfig.parse_argv}
is set to @code{2} after arguments are parsed. Since Python arguments are
stripped from @code{PyConfig.argv}, parsing arguments twice would
parse the application options as Python options.

@ref{4516,,Preinitialize Python} if needed.


Άλλαξε στην έκδοση 3.10: The @ref{607,,PyConfig.argv} arguments are now only parsed once,
@ref{1ee6,,PyConfig.parse_argv} is set to @code{2} after arguments are
parsed, and arguments are only parsed if
@code{PyConfig.parse_argv} equals @code{1}.



Άλλαξε στην έκδοση 3.11: @ref{b6f,,PyConfig_Read()} no longer calculates all paths, and so fields
listed under @ref{c80,,Python Path Configuration} may
no longer be updated until @ref{60a,,Py_InitializeFromConfig()} is
called.

@end deffn

@geindex PyConfig_Clear (C function)
@anchor{c-api/init_config c PyConfig_Clear}@anchor{d77}
@deffn {C Συνάρτηση} void PyConfig_Clear (PyConfig *config)

Release configuration memory.
@end deffn

Most @code{PyConfig} methods @ref{4516,,preinitialize Python} if needed.
In that case, the Python preinitialization configuration
(@ref{d74,,PyPreConfig}) is based on the @ref{60b,,PyConfig}. If configuration
fields which are in common with @code{PyPreConfig} are tuned, they must
be set before calling a @code{PyConfig} method:


@itemize *

@item 
@ref{590b,,PyConfig.dev_mode}

@item 
@ref{629,,PyConfig.isolated}

@item 
@ref{1ee6,,PyConfig.parse_argv}

@item 
@ref{61e,,PyConfig.use_environment}
@end itemize

Moreover, if @ref{d7a,,PyConfig_SetArgv()} or @ref{d7b,,PyConfig_SetBytesArgv()}
is used, this method must be called before other methods, since the
preinitialization configuration depends on command line arguments (if
@ref{1ee6,,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{607}
@deffn {C Μέλος} @ref{d76,,PyWideStringList} argv

@geindex main()
@geindex argv (in module sys)

Set @ref{1609,,sys.argv} command line arguments based on
@ref{607,,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 @code{argv} can be an
empty string.

Set @ref{1ee6,,parse_argv} to @code{1} to parse
@ref{607,,argv} the same way the regular Python parses Python
command line arguments and then to strip Python arguments from
@code{argv}.

If @ref{607,,argv} is empty, an empty string is added to
ensure that @ref{1609,,sys.argv} always exists and is never empty.

Default: @code{NULL}.

See also the @ref{c6a,,orig_argv} member.
@end deffn

@geindex PyConfig.safe_path (C member)
@anchor{c-api/init_config c PyConfig safe_path}@anchor{b55}
@deffn {C Μέλος} int safe_path

If equals to zero, @code{Py_RunMain()} prepends a potentially unsafe path to
@ref{194,,sys.path} at startup:


@itemize *

@item 
If @ref{607,,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{9a3,,-P} command line option and the
@geindex PYTHONSAFEPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONSAFEPATH
@ref{9a4,,PYTHONSAFEPATH} environment variable.

Default: @code{0} in Python config, @code{1} in isolated config.


Added in version 3.11.

@end deffn

@geindex PyConfig.base_exec_prefix (C member)
@anchor{c-api/init_config c PyConfig base_exec_prefix}@anchor{5901}
@deffn {C Μέλος} wchar_t *base_exec_prefix

@ref{3a7,,sys.base_exec_prefix}.

Default: @code{NULL}.

Part of the @ref{c80,,Python Path Configuration} output.

See also @ref{590e,,PyConfig.exec_prefix}.
@end deffn

@geindex PyConfig.base_executable (C member)
@anchor{c-api/init_config c PyConfig base_executable}@anchor{5902}
@deffn {C Μέλος} wchar_t *base_executable

Python base executable: @code{sys._base_executable}.

Set by the 
@geindex __PYVENV_LAUNCHER__
@geindex μεταβλητή περιβάλλοντος; __PYVENV_LAUNCHER__
@code{__PYVENV_LAUNCHER__} environment variable.

Set from @ref{836,,PyConfig.executable} if @code{NULL}.

Default: @code{NULL}.

Part of the @ref{c80,,Python Path Configuration} output.

See also @ref{836,,PyConfig.executable}.
@end deffn

@geindex PyConfig.base_prefix (C member)
@anchor{c-api/init_config c PyConfig base_prefix}@anchor{5903}
@deffn {C Μέλος} wchar_t *base_prefix

@ref{3aa,,sys.base_prefix}.

Default: @code{NULL}.

Part of the @ref{c80,,Python Path Configuration} output.

See also @ref{5914,,PyConfig.prefix}.
@end deffn

@geindex PyConfig.buffered_stdio (C member)
@anchor{c-api/init_config c PyConfig buffered_stdio}@anchor{624}
@deffn {C Μέλος} int buffered_stdio

If equals to @code{0} and @ref{5908,,configure_c_stdio} is non-zero,
disable buffering on the C streams stdout and stderr.

Set to @code{0} by the @ref{1f7f,,-u} command line option and the
@geindex PYTHONUNBUFFERED
@geindex μεταβλητή περιβάλλοντος; PYTHONUNBUFFERED
@ref{1f80,,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{3c4}
@deffn {C Μέλος} int bytes_warning

If equals to @code{1}, issue a warning when comparing @ref{1c7,,bytes} or
@ref{1c6,,bytearray} with @ref{1df,,str}, or comparing @code{bytes} with
@ref{326,,int}.

If equal or greater to @code{2}, raise a @ref{2ee,,BytesWarning} exception in these
cases.

Incremented by the @ref{2ed,,-b} command line option.

Default: @code{0}.


Καταργήθηκε από την έκδοση 3.15, θα αφαιρεθεί στην έκδοση 3.17: The @ref{2ed,,-b} and @code{-bb} options will become no-op in 3.17.
@ref{3c4,,bytes_warning} member will be removed in 3.17.

@end deffn

@geindex PyConfig.warn_default_encoding (C member)
@anchor{c-api/init_config c PyConfig warn_default_encoding}@anchor{591c}
@deffn {C Μέλος} int warn_default_encoding

If non-zero, emit a @ref{231d,,EncodingWarning} warning when @ref{b9c,,io.TextIOWrapper}
uses its default encoding. See @ref{1ac,,Opt-in EncodingWarning} for details.

Default: @code{0}.


Added in version 3.10.

@end deffn

@geindex PyConfig.code_debug_ranges (C member)
@anchor{c-api/init_config c PyConfig code_debug_ranges}@anchor{5905}
@deffn {C Μέλος} 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 μεταβλητή περιβάλλοντος; PYTHONNODEBUGRANGES
@ref{9b5,,PYTHONNODEBUGRANGES} environment variable
and by the @ref{178,,-X no_debug_ranges} command line option.

Default: @code{1}.


Added in 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{5904}
@deffn {C Μέλος} wchar_t *check_hash_pycs_mode

Control the validation behavior of hash-based @code{.pyc} files:
value of the @ref{2311,,--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{5908}
@deffn {C Μέλος} 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{624,,buffered_stdio} equals zero, disable buffering
of stdin, stdout and stderr streams.

@item 
If @ref{613,,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{590b}
@deffn {C Μέλος} int dev_mode

If non-zero, enable the @ref{70d,,Python Development Mode}.

Set to @code{1} by the @ref{178,,-X dev} option and the
@geindex PYTHONDEVMODE
@geindex μεταβλητή περιβάλλοντος; PYTHONDEVMODE
@ref{eb5,,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{590c}
@deffn {C Μέλος} 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 μεταβλητή περιβάλλοντος; PYTHONDUMPREFS
@ref{d6f,,PYTHONDUMPREFS} environment variable.

Needs a special build of Python with the @code{Py_TRACE_REFS} macro defined:
see the @ref{828,,configure --with-trace-refs option}.

Default: @code{0}.
@end deffn

@geindex PyConfig.dump_refs_file (C member)
@anchor{c-api/init_config c PyConfig dump_refs_file}@anchor{590d}
@deffn {C Μέλος} wchar_t *dump_refs_file

Filename where to dump Python references.

Set by the 
@geindex PYTHONDUMPREFSFILE
@geindex μεταβλητή περιβάλλοντος; PYTHONDUMPREFSFILE
@ref{1e36,,PYTHONDUMPREFSFILE} environment variable.

Default: @code{NULL}.


Added in version 3.11.

@end deffn

@geindex PyConfig.exec_prefix (C member)
@anchor{c-api/init_config c PyConfig exec_prefix}@anchor{590e}
@deffn {C Μέλος} wchar_t *exec_prefix

The site-specific directory prefix where the platform-dependent Python
files are installed: @ref{3a8,,sys.exec_prefix}.

Default: @code{NULL}.

Part of the @ref{c80,,Python Path Configuration} output.

See also @ref{5901,,PyConfig.base_exec_prefix}.
@end deffn

@geindex PyConfig.executable (C member)
@anchor{c-api/init_config c PyConfig executable}@anchor{836}
@deffn {C Μέλος} wchar_t *executable

The absolute path of the executable binary for the Python interpreter:
@ref{3ac,,sys.executable}.

Default: @code{NULL}.

Part of the @ref{c80,,Python Path Configuration} output.

See also @ref{5902,,PyConfig.base_executable}.
@end deffn

@geindex PyConfig.faulthandler (C member)
@anchor{c-api/init_config c PyConfig faulthandler}@anchor{590f}
@deffn {C Μέλος} int faulthandler

Enable faulthandler?

If non-zero, call @ref{219,,faulthandler.enable()} at startup.

Set to @code{1} by @ref{178,,-X faulthandler} and the
@geindex PYTHONFAULTHANDLER
@geindex μεταβλητή περιβάλλοντος; PYTHONFAULTHANDLER
@ref{142d,,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{62e}
@deffn {C Μέλος} wchar_t *filesystem_encoding

@ref{948,,Filesystem encoding}:
@ref{1017,,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{62b,,legacy_windows_fs_encoding} of
@ref{d74,,PyPreConfig} is non-zero.

Default encoding on other platforms:


@itemize *

@item 
@code{"utf-8"} if @ref{630,,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{74d,,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{62f,,filesystem_errors} member.
@end deffn

@geindex PyConfig.filesystem_errors (C member)
@anchor{c-api/init_config c PyConfig filesystem_errors}@anchor{62f}
@deffn {C Μέλος} wchar_t *filesystem_errors

@ref{948,,Filesystem error handler}:
@ref{10a3,,sys.getfilesystemencodeerrors()}.

On Windows: use @code{"surrogatepass"} by default, or @code{"replace"}  if
@ref{62b,,legacy_windows_fs_encoding} of
@ref{d74,,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{62e,,filesystem_encoding} member.
@end deffn

@geindex PyConfig.use_frozen_modules (C member)
@anchor{c-api/init_config c PyConfig use_frozen_modules}@anchor{591b}
@deffn {C Μέλος} int use_frozen_modules

If non-zero, use frozen modules.

Set by the 
@geindex PYTHON_FROZEN_MODULES
@geindex μεταβλητή περιβάλλοντος; PYTHON_FROZEN_MODULES
@ref{6b6,,PYTHON_FROZEN_MODULES} environment variable.

Default: @code{1} in a release build, or @code{0} in a @ref{3dc,,debug build}.
@end deffn

@geindex PyConfig.hash_seed (C member)
@anchor{c-api/init_config c PyConfig hash_seed}@anchor{627}
@deffn {C Μέλος} unsigned long hash_seed
@end deffn

@geindex PyConfig.use_hash_seed (C member)
@anchor{c-api/init_config c PyConfig use_hash_seed}@anchor{626}
@deffn {C Μέλος} int use_hash_seed

Randomized hash function seed.

If @ref{626,,use_hash_seed} is zero, a seed is chosen randomly
at Python startup, and @ref{627,,hash_seed} is ignored.

Set by the 
@geindex PYTHONHASHSEED
@geindex μεταβλητή περιβάλλοντος; PYTHONHASHSEED
@ref{1425,,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{609}
@deffn {C Μέλος} wchar_t *home

Set the default Python «home» directory, that is, the location of the
standard Python libraries (see 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME}).

Set by the 
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} environment variable.

Default: @code{NULL}.

Part of the @ref{c80,,Python Path Configuration} input.
@end deffn

@geindex PyConfig.import_time (C member)
@anchor{c-api/init_config c PyConfig import_time}@anchor{5910}
@deffn {C Μέλος} int import_time

@quotation

If @code{1}, profile import time.
If @code{2}, include additional output that indicates
when an imported module has already been loaded.

Set by the @ref{178,,-X importtime} option and the
@geindex PYTHONPROFILEIMPORTTIME
@geindex μεταβλητή περιβάλλοντος; PYTHONPROFILEIMPORTTIME
@ref{ebb,,PYTHONPROFILEIMPORTTIME} environment variable.

Default: @code{0}.
@end quotation


Άλλαξε στην έκδοση 3.14: Added support for @code{import_time = 2}

@end deffn

@geindex PyConfig.inspect (C member)
@anchor{c-api/init_config c PyConfig inspect}@anchor{615}
@deffn {C Μέλος} 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{94a,,sys.stdin} does not appear to
be a terminal.

Incremented by the @ref{187d,,-i} command line option. Set to @code{1} if the
@geindex PYTHONINSPECT
@geindex μεταβλητή περιβάλλοντος; PYTHONINSPECT
@ref{187c,,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{c91}
@deffn {C Μέλος} 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{613}
@deffn {C Μέλος} int interactive

If greater than @code{0}, enable the interactive mode (REPL).

Incremented by the @ref{187d,,-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{5911}
@deffn {C Μέλος} int int_max_str_digits

Configures the @ref{9ec,,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{28d8,,sys.int_info.default_max_str_digits}).  A value of @code{0}
disables the limitation.  Values greater than zero but less than 640
(@ref{4c08,,sys.int_info.str_digits_check_threshold}) are unsupported and
will produce an error.

Configured by the @ref{178,,-X int_max_str_digits} command line
flag or the 
@geindex PYTHONINTMAXSTRDIGITS
@geindex μεταβλητή περιβάλλοντος; PYTHONINTMAXSTRDIGITS
@ref{1d38,,PYTHONINTMAXSTRDIGITS} environment variable.

Default: @code{-1} in Python mode.  4300
(@ref{28d8,,sys.int_info.default_max_str_digits}) in isolated mode.


Added in version 3.12.

@end deffn

@geindex PyConfig.cpu_count (C member)
@anchor{c-api/init_config c PyConfig cpu_count}@anchor{590a}
@deffn {C Μέλος} int cpu_count

If the value of @ref{590a,,cpu_count} is not @code{-1} then it will
override the return values of @ref{6e1,,os.cpu_count()},
@ref{6e0,,os.process_cpu_count()}, and @ref{1319,,multiprocessing.cpu_count()}.

Configured by the @code{-X cpu_count=@var{n|default}} command line
flag or the 
@geindex PYTHON_CPU_COUNT
@geindex μεταβλητή περιβάλλοντος; PYTHON_CPU_COUNT
@ref{721,,PYTHON_CPU_COUNT} environment variable.

Default: @code{-1}.


Added in version 3.13.

@end deffn

@geindex PyConfig.isolated (C member)
@anchor{c-api/init_config c PyConfig isolated}@anchor{629}
@deffn {C Μέλος} int isolated

If greater than @code{0}, enable isolated mode:


@itemize *

@item 
Set @ref{b55,,safe_path} to @code{1}:
don’t prepend a potentially unsafe path to @ref{194,,sys.path} at Python
startup, such as the current directory, the script’s directory or an
empty string.

@item 
Set @ref{61e,,use_environment} to @code{0}: ignore @code{PYTHON}
environment variables.

@item 
Set @ref{622,,user_site_directory} to @code{0}: don’t add the user
site directory to @ref{194,,sys.path}.

@item 
Python REPL doesn’t import @ref{c2,,readline} nor enable default readline
configuration on interactive prompts.
@end itemize

Set to @code{1} by the @ref{d28,,-I} command line option.

Default: @code{0} in Python mode, @code{1} in isolated mode.

See also the @ref{58f8,,Isolated Configuration} and
@ref{592b,,PyPreConfig.isolated}.
@end deffn

@geindex PyConfig.legacy_windows_stdio (C member)
@anchor{c-api/init_config c PyConfig legacy_windows_stdio}@anchor{62d}
@deffn {C Μέλος} int legacy_windows_stdio

If non-zero, use @ref{16b4,,io.FileIO} instead of
@code{io._WindowsConsoleIO} for @ref{94a,,sys.stdin}, @ref{e9c,,sys.stdout}
and @ref{d05,,sys.stderr}.

Set to @code{1} if the 
@geindex PYTHONLEGACYWINDOWSSTDIO
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSSTDIO
@ref{1019,,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{5912}
@deffn {C Μέλος} int malloc_stats

If non-zero, dump statistics on @ref{3da,,Python pymalloc memory allocator} at exit.

Set to @code{1} by the 
@geindex PYTHONMALLOCSTATS
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOCSTATS
@ref{2124,,PYTHONMALLOCSTATS} environment variable.

The option is ignored if Python is @ref{238d,,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{1f16}
@deffn {C Μέλος} wchar_t *platlibdir

Platform library directory name: @ref{2a9,,sys.platlibdir}.

Set by the 
@geindex PYTHONPLATLIBDIR
@geindex μεταβλητή περιβάλλοντος; PYTHONPLATLIBDIR
@ref{1f18,,PYTHONPLATLIBDIR} environment variable.

Default: value of the @code{PLATLIBDIR} macro which is set by the
@ref{19bd,,configure --with-platlibdir option}
(default: @code{"lib"}, or @code{"DLLs"} on Windows).

Part of the @ref{c80,,Python Path Configuration} input.


Added in version 3.9.



Άλλαξε στην έκδοση 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{5930}
@deffn {C Μέλος} wchar_t *pythonpath_env

Module search paths (@ref{194,,sys.path}) as a string separated by @code{DELIM}
(@ref{2322,,os.pathsep}).

Set by the 
@geindex PYTHONPATH
@geindex μεταβλητή περιβάλλοντος; PYTHONPATH
@ref{13c6,,PYTHONPATH} environment variable.

Default: @code{NULL}.

Part of the @ref{c80,,Python Path Configuration} input.
@end deffn

@geindex PyConfig.module_search_paths (C member)
@anchor{c-api/init_config c PyConfig module_search_paths}@anchor{834}
@deffn {C Μέλος} @ref{d76,,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{9e6}
@deffn {C Μέλος} int module_search_paths_set

Module search paths: @ref{194,,sys.path}.

If @ref{9e6,,module_search_paths_set} is equal to @code{0},
@ref{60a,,Py_InitializeFromConfig()} will replace
@ref{834,,module_search_paths} and sets
@code{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{c80,,Python Path Configuration} output.
@end deffn

@geindex PyConfig.optimization_level (C member)
@anchor{c-api/init_config c PyConfig optimization_level}@anchor{617}
@deffn {C Μέλος} 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{431,,-O} command line option. Set to the
@geindex PYTHONOPTIMIZE
@geindex μεταβλητή περιβάλλοντος; PYTHONOPTIMIZE
@ref{2314,,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{c6a}
@deffn {C Μέλος} @ref{d76,,PyWideStringList} orig_argv

The list of the original command line arguments passed to the Python
executable: @ref{c19,,sys.orig_argv}.

If @ref{c6a,,orig_argv} list is empty and
@ref{607,,argv} is not a list only containing an empty
string, @ref{b6f,,PyConfig_Read()} copies @code{argv} into
@code{orig_argv} before modifying
@code{argv} (if @ref{1ee6,,parse_argv} is
non-zero).

See also the @ref{607,,argv} member and the
@ref{1f35,,Py_GetArgcArgv()} function.

Default: empty list.


Added in version 3.10.

@end deffn

@geindex PyConfig.parse_argv (C member)
@anchor{c-api/init_config c PyConfig parse_argv}@anchor{1ee6}
@deffn {C Μέλος} int parse_argv

Parse command line arguments?

If equals to @code{1}, parse @ref{607,,argv} the same way the regular
Python parses @ref{13b0,,command line arguments}, and strip
Python arguments from @code{argv}.

The @ref{b6f,,PyConfig_Read()} function only parses
@ref{607,,PyConfig.argv} arguments once: @ref{1ee6,,PyConfig.parse_argv}
is set to @code{2} after arguments are parsed. Since Python arguments are
stripped from @code{PyConfig.argv}, parsing arguments twice would
parse the application options as Python options.

Default: @code{1} in Python mode, @code{0} in isolated mode.


Άλλαξε στην έκδοση 3.10: The @ref{607,,PyConfig.argv} arguments are now only parsed if
@ref{1ee6,,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{60d}
@deffn {C Μέλος} 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{2312,,-d} command line option. Set to the
@geindex PYTHONDEBUG
@geindex μεταβλητή περιβάλλοντος; PYTHONDEBUG
@ref{2313,,PYTHONDEBUG} environment variable value.

Needs a @ref{3dc,,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{61c}
@deffn {C Μέλος} 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{c80,,Python Path Configuration} input.


Άλλαξε στην έκδοση 3.11: Now also applies on Windows.

@end deffn

@geindex PyConfig.prefix (C member)
@anchor{c-api/init_config c PyConfig prefix}@anchor{5914}
@deffn {C Μέλος} wchar_t *prefix

The site-specific directory prefix where the platform independent Python
files are installed: @ref{3ab,,sys.prefix}.

Default: @code{NULL}.

Part of the @ref{c80,,Python Path Configuration} output.

See also @ref{5903,,PyConfig.base_prefix}.
@end deffn

@geindex PyConfig.program_name (C member)
@anchor{c-api/init_config c PyConfig program_name}@anchor{608}
@deffn {C Μέλος} wchar_t *program_name

Program name used to initialize @ref{836,,executable} and in
early error messages during Python initialization.


@itemize *

@item 
On macOS, use 
@geindex PYTHONEXECUTABLE
@geindex μεταβλητή περιβάλλοντος; PYTHONEXECUTABLE
@ref{2326,,PYTHONEXECUTABLE} environment variable if set.

@item 
If the @code{WITH_NEXT_FRAMEWORK} macro is defined, use
@geindex __PYVENV_LAUNCHER__
@geindex μεταβλητή περιβάλλοντος; __PYVENV_LAUNCHER__
@code{__PYVENV_LAUNCHER__} environment variable if set.

@item 
Use @code{argv[0]} of @ref{607,,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{c80,,Python Path Configuration} input.
@end deffn

@geindex PyConfig.pycache_prefix (C member)
@anchor{c-api/init_config c PyConfig pycache_prefix}@anchor{5915}
@deffn {C Μέλος} wchar_t *pycache_prefix

Directory where cached @code{.pyc} files are written:
@ref{d6d,,sys.pycache_prefix}.

Set by the @ref{178,,-X pycache_prefix=PATH} command line option and
the 
@geindex PYTHONPYCACHEPREFIX
@geindex μεταβλητή περιβάλλοντος; PYTHONPYCACHEPREFIX
@ref{d6c,,PYTHONPYCACHEPREFIX} environment variable.
The command-line option takes precedence.

If @code{NULL}, @ref{d6d,,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{611}
@deffn {C Μέλος} 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{1994,,-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{588f}
@deffn {C Μέλος} wchar_t *run_command

Value of the @ref{445,,-c} command line option.

Used by @ref{d8d,,Py_RunMain()}.

Default: @code{NULL}.
@end deffn

@geindex PyConfig.run_filename (C member)
@anchor{c-api/init_config c PyConfig run_filename}@anchor{5890}
@deffn {C Μέλος} wchar_t *run_filename

Filename passed on the command line: trailing command line argument
without @ref{445,,-c} or @ref{4ca,,-m}. It is used by the
@ref{d8d,,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{5918,,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{5891}
@deffn {C Μέλος} wchar_t *run_module

Value of the @ref{4ca,,-m} command line option.

Used by @ref{d8d,,Py_RunMain()}.

Default: @code{NULL}.
@end deffn

@geindex PyConfig.run_presite (C member)
@anchor{c-api/init_config c PyConfig run_presite}@anchor{5916}
@deffn {C Μέλος} wchar_t *run_presite

@code{module} or @code{module:func} entry point that should be executed before
the @ref{cf,,site} module is imported.

Set by the @ref{178,,-X presite=module;func} command-line
option and the 
@geindex PYTHON_PRESITE
@geindex μεταβλητή περιβάλλοντος; PYTHON_PRESITE
@ref{18ff,,PYTHON_PRESITE} environment variable.
The command-line option takes precedence.

Needs a @ref{3dc,,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{5917}
@deffn {C Μέλος} int show_ref_count

Show total reference count at exit (excluding @ref{398,,immortal} objects)?

Set to @code{1} by @ref{178,,-X showrefcount} command line option.

Needs a @ref{3dc,,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{619}
@deffn {C Μέλος} int site_import

Import the @ref{cf,,site} module at startup?

If equal to zero, disable the import of the module site and the
site-dependent manipulations of @ref{194,,sys.path} that it entails.

Also disable these manipulations if the @ref{cf,,site} module is explicitly
imported later (call @ref{2316,,site.main()} if you want them to be triggered).

Set to @code{0} by the @ref{1551,,-S} command line option.

@ref{a7c,,sys.flags.no_site} is set to the inverted value of
@ref{619,,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{5918}
@deffn {C Μέλος} int skip_source_first_line

If non-zero, skip the first line of the @ref{5890,,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{231a,,-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{835}
@deffn {C Μέλος} wchar_t *stdio_encoding
@end deffn

@geindex PyConfig.stdio_errors (C member)
@anchor{c-api/init_config c PyConfig stdio_errors}@anchor{4c0c}
@deffn {C Μέλος} wchar_t *stdio_errors

Encoding and encoding errors of @ref{94a,,sys.stdin}, @ref{e9c,,sys.stdout} and
@ref{d05,,sys.stderr} (but @code{sys.stderr} always uses
@code{"backslashreplace"} error handler).

Use the 
@geindex PYTHONIOENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONIOENCODING
@ref{13b3,,PYTHONIOENCODING} environment variable if it is
non-empty.

Default encoding:


@itemize *

@item 
@code{"UTF-8"} if @ref{630,,PyPreConfig.utf8_mode} is non-zero.

@item 
Otherwise, use the @ref{74d,,locale encoding}.
@end itemize

Default error handler:


@itemize *

@item 
On Windows: use @code{"surrogateescape"}.

@item 
@code{"surrogateescape"} if @ref{630,,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{62d,,PyConfig.legacy_windows_stdio}.
@end deffn

@geindex PyConfig.tracemalloc (C member)
@anchor{c-api/init_config c PyConfig tracemalloc}@anchor{591a}
@deffn {C Μέλος} int tracemalloc

Enable tracemalloc?

If non-zero, call @ref{231b,,tracemalloc.start()} at startup.

Set by @ref{178,,-X tracemalloc=N} command line option and by the
@geindex PYTHONTRACEMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONTRACEMALLOC
@ref{231c,,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{5913}
@deffn {C Μέλος} int perf_profiling

Enable the Linux @code{perf} profiler support?

If equals to @code{1}, enable support for the Linux @code{perf} profiler.

If equals to @code{2}, enable support for the Linux @code{perf} profiler with
DWARF JIT support.

Set to @code{1} by @ref{178,,-X perf} command-line option and the
@geindex PYTHONPERFSUPPORT
@geindex μεταβλητή περιβάλλοντος; PYTHONPERFSUPPORT
@ref{884,,PYTHONPERFSUPPORT} environment variable.

Set to @code{2} by the @ref{178,,-X perf_jit} command-line option and
the 
@geindex PYTHON_PERF_JIT_SUPPORT
@geindex μεταβλητή περιβάλλοντος; PYTHON_PERF_JIT_SUPPORT
@ref{6b8,,PYTHON_PERF_JIT_SUPPORT} environment variable.

Default: @code{-1}.


@subsubheading Δείτε επίσης


See @ref{6b7,,Python support for the perf map compatible profilers} for more information.



Added in version 3.12.

@end deffn

@geindex PyConfig.stdlib_dir (C member)
@anchor{c-api/init_config c PyConfig stdlib_dir}@anchor{5919}
@deffn {C Μέλος} wchar_t *stdlib_dir

Directory of the Python standard library.

Default: @code{NULL}.


Added in version 3.11.

@end deffn

@geindex PyConfig.use_environment (C member)
@anchor{c-api/init_config c PyConfig use_environment}@anchor{61e}
@deffn {C Μέλος} int use_environment

Use @ref{9e8,,environment variables}?

If equals to zero, ignore the @ref{9e8,,environment variables}.

Set to @code{0} by the @ref{d27,,-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{2462}
@deffn {C Μέλος} 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 the system log) on macOS; @code{1} on iOS (use the
system log).


Added in version 3.14.

@end deffn

@geindex PyConfig.user_site_directory (C member)
@anchor{c-api/init_config c PyConfig user_site_directory}@anchor{622}
@deffn {C Μέλος} int user_site_directory

If non-zero, add the user site directory to @ref{194,,sys.path}.

Set to @code{0} by the @ref{1732,,-s} and @ref{d28,,-I} command line options.

Set to @code{0} by the 
@geindex PYTHONNOUSERSITE
@geindex μεταβλητή περιβάλλοντος; PYTHONNOUSERSITE
@ref{1733,,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{60f}
@deffn {C Μέλος} 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{17c7,,-v} command line option.

Set by the 
@geindex PYTHONVERBOSE
@geindex μεταβλητή περιβάλλοντος; PYTHONVERBOSE
@ref{2317,,PYTHONVERBOSE} environment variable value.

Default: @code{0}.
@end deffn

@geindex PyConfig.warnoptions (C member)
@anchor{c-api/init_config c PyConfig warnoptions}@anchor{832}
@deffn {C Μέλος} @ref{d76,,PyWideStringList} warnoptions

Options of the @ref{11b,,warnings} module to build warnings filters, lowest
to highest priority: @ref{3a5,,sys.warnoptions}.

The @ref{11b,,warnings} module adds @ref{3a5,,sys.warnoptions} in the reverse
order: the last @ref{832,,PyConfig.warnoptions} item becomes the first
item of @code{warnings.filters} which is checked first (highest
priority).

The @ref{1c0,,-W} command line options adds its value to
@ref{832,,warnoptions}, it can be used multiple times.

The 
@geindex PYTHONWARNINGS
@geindex μεταβλητή περιβάλλοντος; PYTHONWARNINGS
@ref{1c1,,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{620}
@deffn {C Μέλος} 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{1770,,-B} command line option and the
@geindex PYTHONDONTWRITEBYTECODE
@geindex μεταβλητή περιβάλλοντος; PYTHONDONTWRITEBYTECODE
@ref{1771,,PYTHONDONTWRITEBYTECODE} environment variable.

@ref{4bd5,,sys.dont_write_bytecode} is initialized to the inverted value of
@ref{620,,write_bytecode}.

Default: @code{1}.
@end deffn

@geindex PyConfig.xoptions (C member)
@anchor{c-api/init_config c PyConfig xoptions}@anchor{833}
@deffn {C Μέλος} @ref{d76,,PyWideStringList} xoptions

Values of the @ref{178,,-X} command line options: @ref{231f,,sys._xoptions}.

Default: empty list.
@end deffn

@geindex PyConfig._pystats (C member)
@anchor{c-api/init_config c PyConfig _pystats}@anchor{591d}
@deffn {C Μέλος} int _pystats

If non-zero, write performance statistics at Python exit.

Need a special build with the @code{Py_STATS} macro:
see @ref{1d36,,--enable-pystats}.

Default: @code{0}.
@end deffn
@end deffn

If @ref{1ee6,,parse_argv} is non-zero, @ref{607,,argv}
arguments are parsed the same way the regular Python parses @ref{13b0,,command line arguments}, and Python arguments are stripped from
@code{argv}.

The @ref{833,,xoptions} options are parsed to set other options: see
the @ref{178,,-X} command line option.


Άλλαξε στην έκδοση 3.9: The @code{show_alloc_count} field has been removed.


@node Initialization with PyConfig,Isolated Configuration,PyConfig,PyConfig C API
@anchor{c-api/init_config init-from-config}@anchor{588e}@anchor{c-api/init_config initialization-with-pyconfig}@anchor{5931}
@subsubsection Initialization with PyConfig


Initializing the interpreter from a populated configuration struct is handled
by calling @ref{60a,,Py_InitializeFromConfig()}.

The caller is responsible to handle exceptions (error or exit) using
@ref{d81,,PyStatus_Exception()} and @ref{d8a,,Py_ExitStatusException()}.

If @ref{3572,,PyImport_FrozenModules()}, @ref{1d1a,,PyImport_AppendInittab()} or
@ref{1d1b,,PyImport_ExtendInittab()} are used, they must be set or called after
Python preinitialization and before the Python initialization. If Python is
initialized multiple times, @code{PyImport_AppendInittab()} or
@code{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_GetAttrString("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,PyConfig C API
@anchor{c-api/init_config init-isolated-conf}@anchor{58f8}@anchor{c-api/init_config isolated-configuration}@anchor{5932}
@subsubsection Isolated Configuration


@ref{d7e,,PyPreConfig_InitIsolatedConfig()} and
@ref{d78,,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{607,,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{609,,PyConfig.home} is specified
to avoid computing the default path configuration.

@node Python Configuration,Python Path Configuration,Isolated Configuration,PyConfig C API
@anchor{c-api/init_config init-python-config}@anchor{5892}@anchor{c-api/init_config python-configuration}@anchor{5933}
@subsubsection Python Configuration


@ref{d7f,,PyPreConfig_InitPythonConfig()} and @ref{d79,,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{a46,,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 μεταβλητή περιβάλλοντος; PYTHONUTF8
@ref{1ad,,PYTHONUTF8} and
@geindex PYTHONCOERCECLOCALE
@geindex μεταβλητή περιβάλλοντος; PYTHONCOERCECLOCALE
@ref{e9b,,PYTHONCOERCECLOCALE} environment variables.

@node Python Path Configuration,,Python Configuration,PyConfig C API
@anchor{c-api/init_config init-path-config}@anchor{c80}@anchor{c-api/init_config python-path-configuration}@anchor{5934}
@subsubsection Python Path Configuration


@ref{60b,,PyConfig} contains multiple fields for the path configuration:


@itemize *

@item 
Path configuration inputs:


@itemize *

@item 
@ref{609,,PyConfig.home}

@item 
@ref{1f16,,PyConfig.platlibdir}

@item 
@ref{61c,,PyConfig.pathconfig_warnings}

@item 
@ref{608,,PyConfig.program_name}

@item 
@ref{5930,,PyConfig.pythonpath_env}

@item 
current working directory: to get absolute paths

@item 
@code{PATH} environment variable to get the program full path
(from @ref{608,,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{5901,,PyConfig.base_exec_prefix}

@item 
@ref{5902,,PyConfig.base_executable}

@item 
@ref{5903,,PyConfig.base_prefix}

@item 
@ref{590e,,PyConfig.exec_prefix}

@item 
@ref{836,,PyConfig.executable}

@item 
@ref{9e6,,PyConfig.module_search_paths_set},
@ref{834,,PyConfig.module_search_paths}

@item 
@ref{5914,,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{9e6,,module_search_paths_set} is equal to @code{0},
@ref{834,,module_search_paths} is overridden and
@code{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{61c,,pathconfig_warnings} to @code{0} to suppress warnings when
calculating the path configuration (Unix only, Windows does not log any warning).

If @ref{5903,,base_prefix} or @ref{5901,,base_exec_prefix}
fields are not set, they inherit their value from @ref{5914,,prefix}
and @ref{590e,,exec_prefix} respectively.

@ref{d8d,,Py_RunMain()} and @ref{fe2,,Py_Main()} modify @ref{194,,sys.path}:


@itemize *

@item 
If @ref{5890,,run_filename} is set and is a directory which contains a
@code{__main__.py} script, prepend @code{run_filename} to
@ref{194,,sys.path}.

@item 
If @ref{629,,isolated} is zero:


@itemize *

@item 
If @ref{5891,,run_module} is set, prepend the current directory
to @ref{194,,sys.path}. Do nothing if the current directory cannot be read.

@item 
If @ref{5890,,run_filename} is set, prepend the directory of the
filename to @ref{194,,sys.path}.

@item 
Otherwise, prepend an empty string to @ref{194,,sys.path}.
@end itemize
@end itemize

If @ref{619,,site_import} is non-zero, @ref{194,,sys.path} can be
modified by the @ref{cf,,site} module. If
@ref{622,,user_site_directory} is non-zero and the user’s
site-package directory exists, the @code{site} module appends the user’s
site-package directory to @code{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{629,,isolated} to @code{1}.

@item 
Set @ref{61e,,use_environment} to @code{0}.

@item 
Set @ref{619,,site_import} to @code{0}.

@item 
Set @ref{622,,user_site_directory} to @code{0} (since 3.15).

@item 
Set @ref{b55,,safe_path} to @code{1}.
@end itemize

If @ref{609,,home} is not set and a @code{pyvenv.cfg} file is present in
the same directory as @ref{836,,executable}, or its parent,
@ref{5914,,prefix} and @ref{590e,,exec_prefix} are set that
location. When this happens, @ref{5903,,base_prefix} and
@ref{5901,,base_exec_prefix} still keep their value, pointing to the
base installation. See @ref{4b93,,Virtual Environments} for more
information.

The @code{__PYVENV_LAUNCHER__} environment variable is used to set
@ref{5902,,PyConfig.base_executable}.


Άλλαξε στην έκδοση 3.14: @ref{5914,,prefix}, and @ref{590e,,exec_prefix}, are now
set to the @code{pyvenv.cfg} directory. This was previously done by @ref{cf,,site},
therefore affected by @ref{1551,,-S}.



Άλλαξε στην έκδοση 3.15: @ref{622,,user_site_directory} is now set to @code{0} when a
@code{._pth} file is present.


@node Py_GetArgcArgv,Multi-Phase Initialization Private Provisional API,PyConfig C API,Python Initialization Configuration
@anchor{c-api/init_config py-getargcargv}@anchor{5935}
@subsection Py_GetArgcArgv()


@geindex Py_GetArgcArgv (C function)
@anchor{c-api/init_config c Py_GetArgcArgv}@anchor{1f35}
@deffn {C Συνάρτηση} void Py_GetArgcArgv (int *argc, wchar_t ***argv)

Get the original command line arguments, before Python modified them.

See also @ref{c6a,,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{5936}
@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{e2,,sys} module is only partially initialized
(ex: @ref{194,,sys.path} doesn’t exist yet).
@end itemize

@item 
«Main» initialization phase, Python is fully initialized:


@itemize *

@item 
Install and configure @ref{7a,,importlib};

@item 
Apply the @ref{c80,,Path Configuration};

@item 
Install signal handlers;

@item 
Finish @ref{e2,,sys} module initialization (ex: create @ref{e9c,,sys.stdout}
and @ref{194,,sys.path});

@item 
Enable optional features like @ref{5b,,faulthandler} and @ref{108,,tracemalloc};

@item 
Import the @ref{cf,,site} module;

@item 
etc.
@end itemize
@end itemize

Private provisional API:

@geindex PyConfig._init_main (C member)
@anchor{c-api/init_config c PyConfig _init_main}@anchor{5937}
@deffn {C Μέλος} int @ref{60b,,PyConfig}._init_main

If set to @code{0}, @ref{60a,,Py_InitializeFromConfig()} stops at the «Core»
initialization phase.
@end deffn

@geindex _Py_InitializeMain (C function)
@anchor{c-api/init_config c _Py_InitializeMain}@anchor{5938}
@deffn {C Συνάρτηση} @ref{d75,,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{c80,,Path Configuration} is only
applied during the «Main» phase. It may allow to customize Python in Python to
override or tune the @ref{c80,,Path Configuration}, maybe
install a custom @ref{10e3,,sys.meta_path} importer or an import hook, etc.

It may become possible to calculate the @ref{c80,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Memory Management,Object Implementation Support,Python Initialization Configuration,Python/C API reference manual
@anchor{c-api/memory doc}@anchor{5939}@anchor{c-api/memory memory}@anchor{5929}@anchor{c-api/memory memory-management}@anchor{593a}@anchor{c-api/memory translation-repo}@anchor{593b}
@section Memory Management


@menu
* Overview: Overview<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:: 
* Examples: Examples<32>. 

@end menu

@node Overview<4>,Allocator Domains,,Memory Management
@anchor{c-api/memory memoryoverview}@anchor{593c}@anchor{c-api/memory overview}@anchor{593d}
@subsection Overview


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 Δείτε επίσης


The 
@geindex PYTHONMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,PYTHONMALLOC} environment variable can be used to configure
the memory allocators used by Python.

The 
@geindex PYTHONMALLOCSTATS
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOCSTATS
@ref{2124,,PYTHONMALLOCSTATS} environment variable can be used to print
statistics of the @ref{3da,,pymalloc memory allocator} every time a
new pymalloc object arena is created, and on shutdown.


@node Allocator Domains,Raw Memory Interface,Overview<4>,Memory Management
@anchor{c-api/memory allocator-domains}@anchor{593e}
@subsection Allocator Domains

@anchor{c-api/memory id1}@anchor{593f}
All allocating functions belong to one of three different «domains» (see also
@ref{5940,,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{2329,,Default Memory Allocators}.
The APIs used to allocate and free a block of memory must be from the same domain.
For example, @ref{17e4,,PyMem_Free()} must be used to free memory allocated using @ref{1024,,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 an @ref{1a1,,attached thread state}. The memory
is requested directly from the system. See @ref{5941,,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
an @ref{1a1,,attached thread state}. The memory is taken from the Python private heap.
See @ref{5942,,Memory Interface}.

@item 
Object domain: intended for allocating memory for Python objects. The
memory is taken from the Python private heap. See @ref{5943,,Object allocators}.
@end itemize

@cartouche
@quotation Σημείωση 
The @ref{487,,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{1024,,PyMem_Malloc()},
@ref{2bf,,PyMem_RawMalloc()}, or @code{malloc()}, but not @ref{1026,,PyObject_Malloc()}.

See @ref{5944,,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{5945}@anchor{c-api/memory raw-memoryinterface}@anchor{5941}
@subsection Raw Memory Interface


The following function sets are wrappers to the system allocator. These
functions are thread-safe, so a @ref{1a70,,thread state} does not
need to be @ref{1a1,,attached}.

The @ref{2329,,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.


Added in version 3.4.


@geindex PyMem_RawMalloc (C function)
@anchor{c-api/memory c PyMem_RawMalloc}@anchor{2bf}
@deffn {C Συνάρτηση} void *PyMem_RawMalloc (size_t n)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{824}
@deffn {C Συνάρτηση} void *PyMem_RawCalloc (size_t nelem, size_t elsize)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.


Added in version 3.5.

@end deffn

@geindex PyMem_RawRealloc (C function)
@anchor{c-api/memory c PyMem_RawRealloc}@anchor{825}
@deffn {C Συνάρτηση} void *PyMem_RawRealloc (void *p, size_t n)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{2bf,,PyMem_RawMalloc()}, @ref{825,,PyMem_RawRealloc()} or
@ref{824,,PyMem_RawCalloc()}.

If the request fails, @ref{825,,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{826}
@deffn {C Συνάρτηση} void PyMem_RawFree (void *p)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Frees the memory block pointed to by `p', which must have been returned by a
previous call to @ref{2bf,,PyMem_RawMalloc()}, @ref{825,,PyMem_RawRealloc()} or
@ref{824,,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{5946}@anchor{c-api/memory memoryinterface}@anchor{5942}
@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.

In the GIL-enabled build (default build) the
@ref{2329,,default memory allocator} uses the
@ref{3da,,pymalloc memory allocator}, whereas in the
@ref{198,,free-threaded build}, the default is the
@ref{232b,,mimalloc memory allocator} instead.

@cartouche
@quotation Προειδοποίηση 
There must be an @ref{1a1,,attached thread state} when using these functions.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.6: The default allocator is now pymalloc instead of system @code{malloc()}.



Άλλαξε στην έκδοση 3.13: In the @ref{487,,free-threaded} build, the default allocator
is now @ref{232b,,mimalloc}.


@geindex PyMem_Malloc (C function)
@anchor{c-api/memory c PyMem_Malloc}@anchor{1024}
@deffn {C Συνάρτηση} void *PyMem_Malloc (size_t n)
` Μέρος του @ref{95c,,Σταθερό 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{125e}
@deffn {C Συνάρτηση} void *PyMem_Calloc (size_t nelem, size_t elsize)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.


Added in version 3.5.

@end deffn

@geindex PyMem_Realloc (C function)
@anchor{c-api/memory c PyMem_Realloc}@anchor{13da}
@deffn {C Συνάρτηση} void *PyMem_Realloc (void *p, size_t n)
` Μέρος του @ref{95c,,Σταθερό 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{1024,,PyMem_Malloc()}, @ref{13da,,PyMem_Realloc()} or @ref{125e,,PyMem_Calloc()}.

If the request fails, @ref{13da,,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{17e4}
@deffn {C Συνάρτηση} void PyMem_Free (void *p)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Frees the memory block pointed to by `p', which must have been returned by a
previous call to @ref{1024,,PyMem_Malloc()}, @ref{13da,,PyMem_Realloc()} or
@ref{125e,,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{18c6}
@deffn {C Μακροεντολή} PyMem_New (TYPE, n)

Same as @ref{1024,,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{5947}
@deffn {C Μακροεντολή} PyMem_Resize (p, TYPE, n)

Same as @ref{13da,,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{18c7}
@deffn {C Συνάρτηση} void PyMem_Del (void *p)

Same as @ref{17e4,,PyMem_Free()}.
@end deffn

@menu
* Deprecated aliases: Deprecated aliases<2>. 

@end menu

@node Deprecated aliases<2>,,,Memory Interface
@anchor{c-api/memory deprecated-aliases}@anchor{5948}
@subsubsection Deprecated aliases


These are @ref{1a7,,soft deprecated} aliases to existing functions and macros.
They exist solely for backwards compatibility.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Deprecated alias

@tab

Corresponding function or macro

@item

@geindex PyMem_MALLOC (C macro)
@anchor{c-api/memory c PyMem_MALLOC}@anchor{5949}
@deffn {C Μακροεντολή} PyMem_MALLOC (size)
@end deffn

@tab

@ref{1024,,PyMem_Malloc()}

@item

@geindex PyMem_NEW (C macro)
@anchor{c-api/memory c PyMem_NEW}@anchor{594a}
@deffn {C Μακροεντολή} PyMem_NEW (type, size)
@end deffn

@tab

@ref{18c6,,PyMem_New}

@item

@geindex PyMem_REALLOC (C macro)
@anchor{c-api/memory c PyMem_REALLOC}@anchor{594b}
@deffn {C Μακροεντολή} PyMem_REALLOC (ptr, size)
@end deffn

@tab

@ref{13da,,PyMem_Realloc()}

@item

@geindex PyMem_RESIZE (C macro)
@anchor{c-api/memory c PyMem_RESIZE}@anchor{594c}
@deffn {C Μακροεντολή} PyMem_RESIZE (ptr, type, size)
@end deffn

@tab

@ref{5947,,PyMem_Resize}

@item

@geindex PyMem_FREE (C macro)
@anchor{c-api/memory c PyMem_FREE}@anchor{594d}
@deffn {C Μακροεντολή} PyMem_FREE (ptr)
@end deffn

@tab

@ref{17e4,,PyMem_Free()}

@item

@geindex PyMem_DEL (C macro)
@anchor{c-api/memory c PyMem_DEL}@anchor{594e}
@deffn {C Μακροεντολή} PyMem_DEL (ptr)
@end deffn

@tab

@ref{17e4,,PyMem_Free()}

@end multitable



Άλλαξε στην έκδοση 3.4: The macros are now aliases of the corresponding functions and macros.
Previously, their behavior was the same, but their use did not necessarily
preserve binary compatibility across Python versions.



Αποσύρθηκε στην έκδοση 2.0.


@node Object allocators,Default Memory Allocators,Memory Interface,Memory Management
@anchor{c-api/memory object-allocators}@anchor{594f}@anchor{c-api/memory objectinterface}@anchor{5943}
@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 Σημείωση 
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{5950,,Customize Memory Allocators} section.
@end quotation
@end cartouche

The @ref{2329,,default object allocator} uses the
@ref{3da,,pymalloc memory allocator}.  In the
@ref{487,,free-threaded} build, the default is the
@ref{232b,,mimalloc memory allocator} instead.

@cartouche
@quotation Προειδοποίηση 
There must be an @ref{1a1,,attached thread state} when using these functions.
@end quotation
@end cartouche

@geindex PyObject_Malloc (C function)
@anchor{c-api/memory c PyObject_Malloc}@anchor{1026}
@deffn {C Συνάρτηση} void *PyObject_Malloc (size_t n)
` Μέρος του @ref{95c,,Σταθερό 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{125f}
@deffn {C Συνάρτηση} void *PyObject_Calloc (size_t nelem, size_t elsize)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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.


Added in version 3.5.

@end deffn

@geindex PyObject_Realloc (C function)
@anchor{c-api/memory c PyObject_Realloc}@anchor{17e5}
@deffn {C Συνάρτηση} void *PyObject_Realloc (void *p, size_t n)
` Μέρος του @ref{95c,,Σταθερό 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{1026,,PyObject_Malloc()}, @ref{17e5,,PyObject_Realloc()} or @ref{125f,,PyObject_Calloc()}.

If the request fails, @ref{17e5,,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{1023}
@deffn {C Συνάρτηση} void PyObject_Free (void *p)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Frees the memory block pointed to by `p', which must have been returned by a
previous call to @ref{1026,,PyObject_Malloc()}, @ref{17e5,,PyObject_Realloc()} or
@ref{125f,,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.

Do not call this directly to free an object’s memory; call the type’s
@ref{51e5,,tp_free} slot instead.

Do not use this for memory allocated by @ref{e68,,PyObject_GC_New} or
@ref{e69,,PyObject_GC_NewVar}; use @ref{18a5,,PyObject_GC_Del()} instead.


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{18a5,,PyObject_GC_Del()} is the equivalent of this function for memory
allocated by types that support garbage collection.

@item 
@ref{1026,,PyObject_Malloc()}

@item 
@ref{17e5,,PyObject_Realloc()}

@item 
@ref{125f,,PyObject_Calloc()}

@item 
@ref{d4d,,PyObject_New}

@item 
@ref{d4e,,PyObject_NewVar}

@item 
@ref{e30,,PyType_GenericAlloc()}

@item 
@ref{51e5,,tp_free}
@end itemize

@end deffn

@node Default Memory Allocators,Customize Memory Allocators,Object allocators,Memory Management
@anchor{c-api/memory default-memory-allocators}@anchor{2329}@anchor{c-api/memory id2}@anchor{5951}
@subsection Default Memory Allocators


Default memory allocators:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Configuration

@tab

Name

@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

@item

Free-threaded build

@tab

@code{"mimalloc"}

@tab

@code{mimalloc}

@tab

@code{mimalloc}

@tab

@code{mimalloc}

@item

Free-threaded debug build

@tab

@code{"mimalloc_debug"}

@tab

@code{mimalloc} + debug

@tab

@code{mimalloc} + debug

@tab

@code{mimalloc} + debug

@end multitable


Legend:


@itemize *

@item 
Name: value for 
@geindex PYTHONMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,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{3da,,pymalloc memory allocator}.

@item 
@code{mimalloc}: @ref{232b,,mimalloc memory allocator}.

@item 
«+ debug»: with @ref{232c,,debug hooks on the Python memory allocators}.

@item 
«Debug build»: @ref{3dc,,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{5950}@anchor{c-api/memory id3}@anchor{5952}
@subsection Customize Memory Allocators



Added in version 3.4.


@geindex PyMemAllocatorEx (C type)
@anchor{c-api/memory c PyMemAllocatorEx}@anchor{127c}
@deffn {C Τύπος} type PyMemAllocatorEx

Structure used to describe a memory block allocator. The structure has
the following fields:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Field

@tab

Meaning

@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



Άλλαξε στην έκδοση 3.5: The @code{PyMemAllocator} structure was renamed to
@ref{127c,,PyMemAllocatorEx} and a new @code{calloc} field was added.

@end deffn

@geindex PyMemAllocatorDomain (C type)
@anchor{c-api/memory c PyMemAllocatorDomain}@anchor{5940}
@deffn {C Τύπος} 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{232a}
@deffn {C Μακροεντολή} PYMEM_DOMAIN_RAW

Functions:


@itemize *

@item 
@ref{2bf,,PyMem_RawMalloc()}

@item 
@ref{825,,PyMem_RawRealloc()}

@item 
@ref{824,,PyMem_RawCalloc()}

@item 
@ref{826,,PyMem_RawFree()}
@end itemize
@end deffn

@geindex PYMEM_DOMAIN_MEM (C macro)
@anchor{c-api/memory c PYMEM_DOMAIN_MEM}@anchor{1027}
@deffn {C Μακροεντολή} PYMEM_DOMAIN_MEM

Functions:


@itemize *

@item 
@ref{1024,,PyMem_Malloc()},

@item 
@ref{13da,,PyMem_Realloc()}

@item 
@ref{125e,,PyMem_Calloc()}

@item 
@ref{17e4,,PyMem_Free()}
@end itemize
@end deffn

@geindex PYMEM_DOMAIN_OBJ (C macro)
@anchor{c-api/memory c PYMEM_DOMAIN_OBJ}@anchor{1025}
@deffn {C Μακροεντολή} PYMEM_DOMAIN_OBJ

Functions:


@itemize *

@item 
@ref{1026,,PyObject_Malloc()}

@item 
@ref{17e5,,PyObject_Realloc()}

@item 
@ref{125f,,PyObject_Calloc()}

@item 
@ref{1023,,PyObject_Free()}
@end itemize
@end deffn
@end deffn

@geindex PyMem_GetAllocator (C function)
@anchor{c-api/memory c PyMem_GetAllocator}@anchor{588a}
@deffn {C Συνάρτηση} 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{98a}
@deffn {C Συνάρτηση} 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{232a,,PYMEM_DOMAIN_RAW} domain, the allocator must be
thread-safe: a @ref{1a70,,thread state} is not @ref{1a1,,attached}
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 @ref{411,,GIL}.

If the new allocator is not a hook (does not call the previous allocator),
the @ref{1028,,PyMem_SetupDebugHooks()} function must be called to reinstall the
debug hooks on top on the new allocator.

See also @ref{5900,,PyPreConfig.allocator} and @ref{4516,,Preinitialize Python with PyPreConfig}.

@cartouche
@quotation Προειδοποίηση 
@ref{98a,,PyMem_SetAllocator()} does have the following contract:


@itemize *

@item 
It can be called after @ref{631,,Py_PreInitialize()} and before
@ref{60a,,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 an @ref{1a1,,attached thread state}).
See @ref{593f,,the section on allocator domains} for more
information.

@item 
If called after Python has finish initializing (after
@ref{60a,,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


Άλλαξε στην έκδοση 3.12: All allocators must be thread-safe.

@end deffn

@geindex PyMem_SetupDebugHooks (C function)
@anchor{c-api/memory c PyMem_SetupDebugHooks}@anchor{1028}
@deffn {C Συνάρτηση} void PyMem_SetupDebugHooks (void)

Setup @ref{232c,,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{5953}@anchor{c-api/memory pymem-debug-hooks}@anchor{232c}
@subsection Debug hooks on the Python memory allocators


When @ref{3dc,,Python is built in debug mode}, the
@ref{1028,,PyMem_SetupDebugHooks()} function is called at the @ref{4516,,Python preinitialization} to setup debug hooks on Python memory allocators
to detect memory errors.

The 
@geindex PYTHONMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,PYTHONMALLOC} environment variable can be used to install debug
hooks on a Python compiled in release mode (ex: @code{PYTHONMALLOC=debug}).

The @ref{1028,,PyMem_SetupDebugHooks()} function can be used to set debug hooks
after calling @ref{98a,,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{1023,,PyObject_Free()} is
called on a memory block allocated by @ref{1024,,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 there is an @ref{1a1,,attached thread state} when
allocator functions of @ref{1025,,PYMEM_DOMAIN_OBJ} (ex:
@ref{1026,,PyObject_Malloc()}) and @ref{1027,,PYMEM_DOMAIN_MEM} (ex:
@ref{1024,,PyMem_Malloc()}) domains are called.
@end itemize

On error, the debug hooks use the @ref{108,,tracemalloc} module to get the
traceback where a memory block was allocated. The traceback is only displayed
if @code{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{232a,,PYMEM_DOMAIN_RAW}.

@item 
@code{'m'} for @ref{1027,,PYMEM_DOMAIN_MEM}.

@item 
@code{'o'} for @ref{1025,,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).


Άλλαξε στην έκδοση 3.6: The @ref{1028,,PyMem_SetupDebugHooks()} function now also works on Python
compiled in release mode.  On error, the debug hooks now use
@ref{108,,tracemalloc} to get the traceback where a memory block was allocated.
The debug hooks now also check if there is an @ref{1a1,,attached thread state} when
functions of @ref{1025,,PYMEM_DOMAIN_OBJ} and @ref{1027,,PYMEM_DOMAIN_MEM} domains are
called.



Άλλαξε στην έκδοση 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{3da}@anchor{c-api/memory the-pymalloc-allocator}@anchor{5954}
@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. When Python is configured with @ref{3d9,,--with-pymalloc-hugepages},
the arena size on 64-bit platforms is increased to 2 MiB to match the huge page
size, and arena allocation will attempt to use huge pages (@code{MAP_HUGETLB} on
Linux, @code{MEM_LARGE_PAGES} on Windows) with automatic fallback to regular pages.
It falls back to @ref{2bf,,PyMem_RawMalloc()} and
@ref{825,,PyMem_RawRealloc()} for allocations larger than 512 bytes.

`pymalloc' is the @ref{2329,,default allocator} of the
@ref{1027,,PYMEM_DOMAIN_MEM} (ex: @ref{1024,,PyMem_Malloc()}) and
@ref{1025,,PYMEM_DOMAIN_OBJ} (ex: @ref{1026,,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{238d,,--without-pymalloc} option. It can also be disabled at runtime using
the 
@geindex PYTHONMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,PYTHONMALLOC} environment variable (ex: @code{PYTHONMALLOC=malloc}).

Typically, it makes sense to disable the pymalloc allocator when building
Python with AddressSanitizer (@ref{2396,,--with-address-sanitizer}) which helps
uncover low level bugs within the C code.

@menu
* Customize pymalloc Arena Allocator:: 

@end menu

@node Customize pymalloc Arena Allocator,,,The pymalloc allocator
@anchor{c-api/memory customize-pymalloc-arena-allocator}@anchor{5955}
@subsubsection Customize pymalloc Arena Allocator



Added in version 3.4.


@geindex PyObjectArenaAllocator (C type)
@anchor{c-api/memory c PyObjectArenaAllocator}@anchor{5956}
@deffn {C Τύπος} type PyObjectArenaAllocator

Structure used to describe an arena allocator. The structure has
three fields:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Field

@tab

Meaning

@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{588b}
@deffn {C Συνάρτηση} void PyObject_GetArenaAllocator (PyObjectArenaAllocator *allocator)

Get the arena allocator.
@end deffn

@geindex PyObject_SetArenaAllocator (C function)
@anchor{c-api/memory c PyObject_SetArenaAllocator}@anchor{5889}
@deffn {C Συνάρτηση} 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{232b}@anchor{c-api/memory the-mimalloc-allocator}@anchor{5957}
@subsection The mimalloc allocator



Added in version 3.13.


Python supports the mimalloc@footnote{https://github.com/microsoft/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.

Unlike @ref{3da,,pymalloc}, which is optimized for small objects (512
bytes or fewer), mimalloc handles allocations of any size.

In the @ref{487,,free-threaded} build, mimalloc is the default
and `required' allocator for the @ref{1027,,PYMEM_DOMAIN_MEM} and
@ref{1025,,PYMEM_DOMAIN_OBJ} domains.  It cannot be disabled in free-threaded
builds.  The free-threaded build uses per-thread mimalloc heaps, which allows
allocation and deallocation to proceed without locking in most cases.

In the default (non-free-threaded) build, mimalloc is available but not the
default allocator.  It can be selected at runtime using
@geindex PYTHONMALLOC
@geindex μεταβλητή περιβάλλοντος; PYTHONMALLOC
@ref{1022,,PYTHONMALLOC}@code{=mimalloc} (or @code{mimalloc_debug} to include
@ref{232c,,debug hooks}).  It can be disabled at build time
using the @ref{238c,,--without-mimalloc} configure option, but this option
cannot be combined with @ref{6a5,,--disable-gil}.

@node tracemalloc C API,Examples<32>,The mimalloc allocator,Memory Management
@anchor{c-api/memory tracemalloc-c-api}@anchor{5958}
@subsection tracemalloc C API



Added in version 3.7.


@geindex PyTraceMalloc_Track (C function)
@anchor{c-api/memory c PyTraceMalloc_Track}@anchor{f74}
@deffn {C Συνάρτηση} int PyTraceMalloc_Track (unsigned int domain, uintptr_t ptr, size_t size)

Track an allocated memory block in the @ref{108,,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{f75}
@deffn {C Συνάρτηση} int PyTraceMalloc_Untrack (unsigned int domain, uintptr_t ptr)

Untrack an allocated memory block in the @ref{108,,tracemalloc} module.
Do nothing if the block was not tracked.

Return @code{-2} if tracemalloc is disabled, otherwise return @code{0}.
@end deffn

@node Examples<32>,,tracemalloc C API,Memory Management
@anchor{c-api/memory examples}@anchor{5959}@anchor{c-api/memory memoryexamples}@anchor{595a}
@subsection Examples


Here is the example from section @ref{593c,,Overview}, 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_Free(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_Free()  */
@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{d4d,,PyObject_New},
@ref{d4e,,PyObject_NewVar} and @ref{1023,,PyObject_Free()}.

These will be explained in the next chapter on defining and implementing new
object types in C.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Object Implementation Support,API and ABI Versioning,Memory Management,Python/C API reference manual
@anchor{c-api/objimpl doc}@anchor{595b}@anchor{c-api/objimpl newtypes}@anchor{595c}@anchor{c-api/objimpl object-implementation-support}@anchor{595d}@anchor{c-api/objimpl translation-repo}@anchor{595e}
@section Object Implementation Support


This chapter describes the functions, types, and macros used when defining new
object types.

@menu
* Allocating objects on the heap:: 
* Object Life Cycle:: 
* Common Object Structures:: 
* Type Object Structures:: 
* Supporting Cyclic Garbage Collection:: 

@end menu

@node Allocating objects on the heap,Object Life Cycle,,Object Implementation Support
@anchor{c-api/allocation doc}@anchor{595f}@anchor{c-api/allocation allocating-objects}@anchor{5960}@anchor{c-api/allocation allocating-objects-on-the-heap}@anchor{5961}
@subsection Allocating objects on the heap


@geindex _PyObject_New (C function)
@anchor{c-api/allocation c _PyObject_New}@anchor{5962}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *_PyObject_New (PyTypeObject *type)
`Επιστρεφόμενη τιμή: New reference.'
@end deffn

@geindex _PyObject_NewVar (C function)
@anchor{c-api/allocation c _PyObject_NewVar}@anchor{5963}
@deffn {C Συνάρτηση} @ref{492d,,PyVarObject} *_PyObject_NewVar (PyTypeObject *type, Py_ssize_t size)
`Επιστρεφόμενη τιμή: New reference.'
@end deffn

@geindex PyObject_Init (C function)
@anchor{c-api/allocation c PyObject_Init}@anchor{e2f}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyObject_Init (PyObject *op, PyTypeObject *type)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Initialize a newly allocated object `op' with its type and initial
reference.  Returns the initialized object.  Other fields of the object are
not initialized.  Despite its name, this function is unrelated to the
object’s @ref{2fa,,__init__()} method (@ref{983,,tp_init}
slot).  Specifically, this function does `not' call the object’s
@code{__init__()} method.

In general, consider this function to be a low-level routine. Use
@ref{51e6,,tp_alloc} where possible.
For implementing @code{tp_alloc} for your type, prefer
@ref{e30,,PyType_GenericAlloc()} or @ref{d4d,,PyObject_New()}.

@cartouche
@quotation Σημείωση 
This function only initializes the object’s memory corresponding to the
initial @ref{19b,,PyObject} structure.  It does not zero the rest.
@end quotation
@end cartouche
@end deffn

@geindex PyObject_InitVar (C function)
@anchor{c-api/allocation c PyObject_InitVar}@anchor{1f34}
@deffn {C Συνάρτηση} @ref{492d,,PyVarObject} *PyObject_InitVar (PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI}.'
Αυτό κάνει τα πάντα που κάνει η @ref{e2f,,PyObject_Init()}, και επίσης αρχικοποιεί τις πληροφορίες μήκους για ένα αντικείμενο μεταβλητού μεγέθους.

@cartouche
@quotation Σημείωση 
This function only initializes some of the object’s memory.  It does not
zero the rest.
@end quotation
@end cartouche
@end deffn

@geindex PyObject_New (C macro)
@anchor{c-api/allocation c PyObject_New}@anchor{d4d}
@deffn {C Μακροεντολή} PyObject_New (TYPE, typeobj)

Allocates a new Python object using the C structure type `TYPE' and the
Python type object `typeobj' (@code{PyTypeObject*}) by calling
@ref{1026,,PyObject_Malloc()} to allocate memory and initializing it like
@ref{e2f,,PyObject_Init()}.  The caller will own the only reference to the
object (i.e. its reference count will be one).

Avoid calling this directly to allocate memory for an object; call the type’s
@ref{51e6,,tp_alloc} slot instead.

When populating a type’s @ref{51e6,,tp_alloc} slot,
@ref{e30,,PyType_GenericAlloc()} is preferred over a custom function that
simply calls this macro.

This macro does not call @ref{51e6,,tp_alloc},
@ref{981,,tp_new} (@ref{982,,__new__()}), or
@ref{983,,tp_init} (@ref{2fa,,__init__()}).

This cannot be used for objects with @ref{39e,,Py_TPFLAGS_HAVE_GC} set in
@ref{1e68,,tp_flags}; use @ref{e68,,PyObject_GC_New} instead.

Memory allocated by this macro must be freed with @ref{1023,,PyObject_Free()}
(usually called via the object’s @ref{51e5,,tp_free} slot).

@cartouche
@quotation Σημείωση 
The returned memory is not guaranteed to have been completely zeroed
before it was initialized.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
This macro does not construct a fully initialized object of the given
type; it merely allocates memory and prepares it for further
initialization by @ref{983,,tp_init}.  To construct a
fully initialized object, call `typeobj' instead.  For example:

@example
PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);
@end example
@end quotation
@end cartouche


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{1023,,PyObject_Free()}

@item 
@ref{e68,,PyObject_GC_New}

@item 
@ref{e30,,PyType_GenericAlloc()}

@item 
@ref{51e6,,tp_alloc}
@end itemize

@end deffn

@geindex PyObject_NewVar (C macro)
@anchor{c-api/allocation c PyObject_NewVar}@anchor{d4e}
@deffn {C Μακροεντολή} PyObject_NewVar (TYPE, typeobj, size)

Like @ref{d4d,,PyObject_New} except:


@itemize *

@item 
It allocates enough memory for the `TYPE' structure plus `size'
(@code{Py_ssize_t}) fields of the size given by the
@ref{25b0,,tp_itemsize} field of `typeobj'.

@item 
The memory is initialized like @ref{1f34,,PyObject_InitVar()}.
@end itemize

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.

Avoid calling this directly to allocate memory for an object; call the type’s
@ref{51e6,,tp_alloc} slot instead.

When populating a type’s @ref{51e6,,tp_alloc} slot,
@ref{e30,,PyType_GenericAlloc()} is preferred over a custom function that
simply calls this macro.

This cannot be used for objects with @ref{39e,,Py_TPFLAGS_HAVE_GC} set in
@ref{1e68,,tp_flags}; use @ref{e69,,PyObject_GC_NewVar}
instead.

Memory allocated by this function must be freed with @ref{1023,,PyObject_Free()}
(usually called via the object’s @ref{51e5,,tp_free} slot).

@cartouche
@quotation Σημείωση 
The returned memory is not guaranteed to have been completely zeroed
before it was initialized.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
This macro does not construct a fully initialized object of the given
type; it merely allocates memory and prepares it for further
initialization by @ref{983,,tp_init}.  To construct a
fully initialized object, call `typeobj' instead.  For example:

@example
PyObject *list_instance = PyObject_CallNoArgs((PyObject *)&PyList_Type);
@end example
@end quotation
@end cartouche


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{1023,,PyObject_Free()}

@item 
@ref{e69,,PyObject_GC_NewVar}

@item 
@ref{e30,,PyType_GenericAlloc()}

@item 
@ref{51e6,,tp_alloc}
@end itemize

@end deffn

@geindex _Py_NoneStruct (C var)
@anchor{c-api/allocation c _Py_NoneStruct}@anchor{5964}
@deffn {C Μεταβλητή} @ref{19b,,PyObject} _Py_NoneStruct

Αντικείμενο που είναι ορατό στην Python ως @code{None}. Αυτό θα πρέπει να προσπελαύνεται μόνο χρησιμοποιώντας τη μακροεντολή @ref{5606,,Py_None}, η οποία αξιολογείται σε έναν δείκτη σε αυτό το αντικείμενο.
@end deffn


@subsubheading Δείτε επίσης



@table @asis

@item @ref{5566,,Module Objects}

Για να δεσμεύσετε και να δημιουργήσετε επεκτάσεις modules.
@end table


@menu
* Soft-deprecated aliases:: 

@end menu

@node Soft-deprecated aliases,,,Allocating objects on the heap
@anchor{c-api/allocation soft-deprecated-aliases}@anchor{5965}
@subsubsection Soft-deprecated aliases



@ref{1a7,,Soft deprecated} since version 3.15.


These are aliases to existing functions and macros.
They exist solely for backwards compatibility.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Soft-deprecated alias

@tab

Function

@item

@geindex PyObject_NEW (C macro)
@anchor{c-api/allocation c PyObject_NEW}@anchor{5966}
@deffn {C Μακροεντολή} PyObject_NEW (type, typeobj)
@end deffn

@tab

@ref{d4d,,PyObject_New}

@item

@geindex PyObject_NEW_VAR (C macro)
@anchor{c-api/allocation c PyObject_NEW_VAR}@anchor{5967}
@deffn {C Μακροεντολή} PyObject_NEW_VAR (type, typeobj, n)
@end deffn

@tab

@ref{d4e,,PyObject_NewVar}

@item

@geindex PyObject_INIT (C macro)
@anchor{c-api/allocation c PyObject_INIT}@anchor{1f32}
@deffn {C Μακροεντολή} PyObject_INIT (op, typeobj)
@end deffn

@tab

@ref{e2f,,PyObject_Init()}

@item

@geindex PyObject_INIT_VAR (C macro)
@anchor{c-api/allocation c PyObject_INIT_VAR}@anchor{1f33}
@deffn {C Μακροεντολή} PyObject_INIT_VAR (op, typeobj, n)
@end deffn

@tab

@ref{1f34,,PyObject_InitVar()}

@item

@geindex PyObject_MALLOC (C macro)
@anchor{c-api/allocation c PyObject_MALLOC}@anchor{5968}
@deffn {C Μακροεντολή} PyObject_MALLOC (n)
@end deffn

@tab

@ref{1026,,PyObject_Malloc()}

@item

@geindex PyObject_REALLOC (C macro)
@anchor{c-api/allocation c PyObject_REALLOC}@anchor{5969}
@deffn {C Μακροεντολή} PyObject_REALLOC (p, n)
@end deffn

@tab

@ref{17e5,,PyObject_Realloc()}

@item

@geindex PyObject_FREE (C macro)
@anchor{c-api/allocation c PyObject_FREE}@anchor{596a}
@deffn {C Μακροεντολή} PyObject_FREE (p)
@end deffn

@tab

@ref{1023,,PyObject_Free()}

@item

@geindex PyObject_DEL (C macro)
@anchor{c-api/allocation c PyObject_DEL}@anchor{596b}
@deffn {C Μακροεντολή} PyObject_DEL (p)
@end deffn

@tab

@ref{1023,,PyObject_Free()}

@item

@geindex PyObject_Del (C macro)
@anchor{c-api/allocation c PyObject_Del}@anchor{1873}
@deffn {C Μακροεντολή} PyObject_Del (p)
@end deffn

@tab

@ref{1023,,PyObject_Free()}

@end multitable


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Object Life Cycle,Common Object Structures,Allocating objects on the heap,Object Implementation Support
@anchor{c-api/lifecycle doc}@anchor{596c}@anchor{c-api/lifecycle life-cycle}@anchor{596d}@anchor{c-api/lifecycle object-life-cycle}@anchor{596e}@anchor{c-api/lifecycle translation-repo}@anchor{596f}
@subsection Object Life Cycle


This section explains how a type’s slots relate to each other throughout the
life of an object.  It is not intended to be a complete canonical reference for
the slots; instead, refer to the slot-specific documentation in
@ref{d55,,Type Object Structures} for details about a particular slot.

@menu
* Life Events:: 
* Cyclic Isolate Destruction:: 
* Functions: Functions<14>. 

@end menu

@node Life Events,Cyclic Isolate Destruction,,Object Life Cycle
@anchor{c-api/lifecycle life-events}@anchor{5970}
@subsubsection Life Events


The figure below illustrates the order of events that can occur throughout an
object’s life.  An arrow from `A' to `B' indicates that event `B' can occur
after event `A' has occurred, with the arrow’s label indicating the condition
that must be true for `B' to occur after `A'.


@image{python-figures/lifecycle.dot,,,Diagram showing events in an object's life. Explained in detail below.,svg}


Explanation:


@itemize *

@item 
When a new object is constructed by calling its type:


@enumerate 

@item 
@ref{981,,tp_new} is called to create a new object.

@item 
@ref{51e6,,tp_alloc} is directly called by
@ref{981,,tp_new} to allocate the memory for the new
object.

@item 
@ref{983,,tp_init} initializes the newly created object.
@code{tp_init} can be called again to re-initialize an object, if
desired. The @code{tp_init} call can also be skipped entirely,
for example by Python code calling @ref{982,,__new__()}.
@end enumerate

@item 
After @code{tp_init} completes, the object is ready to use.

@item 
Some time after the last reference to an object is removed:


@enumerate 

@item 
If an object is not marked as `finalized', it might be finalized by
marking it as `finalized' and calling its
@ref{e6c,,tp_finalize} function.  Python does
`not' finalize an object when the last reference to it is deleted; use
@ref{351,,PyObject_CallFinalizerFromDealloc()} to ensure that
@code{tp_finalize} is always called.

@item 
If the object is marked as finalized,
@ref{51f7,,tp_clear} might be called by the garbage collector
to clear references held by the object.  It is `not' called when the
object’s reference count reaches zero.

@item 
@ref{51d3,,tp_dealloc} is called to destroy the object.
To avoid code duplication, @code{tp_dealloc} typically
calls into @ref{51f7,,tp_clear} to free up the object’s
references.

@item 
When @ref{51d3,,tp_dealloc} finishes object destruction,
it directly calls @ref{51e5,,tp_free} (usually set to
@ref{1023,,PyObject_Free()} or @ref{18a5,,PyObject_GC_Del()} automatically as
appropriate for the type) to deallocate the memory.
@end enumerate

@item 
The @ref{e6c,,tp_finalize} function is permitted to add a
reference to the object if desired.  If it does, the object is
`resurrected', preventing its pending destruction.  (Only
@code{tp_finalize} is allowed to resurrect an object;
@ref{51f7,,tp_clear} and
@ref{51d3,,tp_dealloc} cannot without calling into
@code{tp_finalize}.)  Resurrecting an object may
or may not cause the object’s `finalized' mark to be removed.  Currently,
Python does not remove the `finalized' mark from a resurrected object if
it supports garbage collection (i.e., the @ref{39e,,Py_TPFLAGS_HAVE_GC}
flag is set) but does remove the mark if the object does not support
garbage collection; either or both of these behaviors may change in the
future.

@item 
@ref{51d3,,tp_dealloc} can optionally call
@ref{e6c,,tp_finalize} via
@ref{351,,PyObject_CallFinalizerFromDealloc()} if it wishes to reuse that
code to help with object destruction.  This is recommended because it
guarantees that @code{tp_finalize} is always called before
destruction.  See the @code{tp_dealloc} documentation
for example code.

@item 
If the object is a member of a @ref{5971,,cyclic isolate} and either
@ref{51f7,,tp_clear} fails to break the reference cycle or
the cyclic isolate is not detected (perhaps @ref{4cec,,gc.disable()} was called,
or the @ref{39e,,Py_TPFLAGS_HAVE_GC} flag was erroneously omitted in one
of the involved types), the objects remain indefinitely uncollectable
(they «leak»).  See @ref{156a,,gc.garbage}.
@end itemize

If the object is marked as supporting garbage collection (the
@ref{39e,,Py_TPFLAGS_HAVE_GC} flag is set in
@ref{1e68,,tp_flags}), the following events are also possible:


@itemize *

@item 
The garbage collector occasionally calls
@ref{36b,,tp_traverse} to identify @ref{5971,,cyclic isolates}.

@item 
When the garbage collector discovers a @ref{5971,,cyclic isolate}, it
finalizes one of the objects in the group by marking it as `finalized' and
calling its @ref{e6c,,tp_finalize} function, if it has one.
This repeats until the cyclic isolate doesn’t exist or all of the objects
have been finalized.

@item 
@ref{e6c,,tp_finalize} is permitted to resurrect the object
by adding a reference from outside the @ref{5971,,cyclic isolate}.  The new
reference causes the group of objects to no longer form a cyclic isolate
(the reference cycle may still exist, but if it does the objects are no
longer isolated).

@item 
When the garbage collector discovers a @ref{5971,,cyclic isolate} and all of
the objects in the group have already been marked as `finalized', the
garbage collector clears one or more of the uncleared objects in the group
(possibly concurrently) by calling each’s
@ref{51f7,,tp_clear} function.  This repeats as long as the
cyclic isolate still exists and not all of the objects have been cleared.
@end itemize

@node Cyclic Isolate Destruction,Functions<14>,Life Events,Object Life Cycle
@anchor{c-api/lifecycle cyclic-isolate-destruction}@anchor{5972}
@subsubsection Cyclic Isolate Destruction


Listed below are the stages of life of a hypothetical @ref{5971,,cyclic isolate}
that continues to exist after each member object is finalized or cleared.  It
is a memory leak if a cyclic isolate progresses through all of these stages; it should
vanish once all objects are cleared, if not sooner.  A cyclic isolate can
vanish either because the reference cycle is broken or because the objects are
no longer isolated due to finalizer resurrection (see
@ref{e6c,,tp_finalize}).


@enumerate 0

@item 
`Reachable' (not yet a cyclic isolate): All objects are in their normal,
reachable state.  A reference cycle could exist, but an external reference
means the objects are not yet isolated.

@item 
`Unreachable but consistent:' The final reference from outside the cyclic
group of objects has been removed, causing the objects to become isolated
(thus a cyclic isolate is born).  None of the group’s objects have been
finalized or cleared yet.  The cyclic isolate remains at this stage until
some future run of the garbage collector (not necessarily the next run
because the next run might not scan every object).

@item 
`Mix of finalized and not finalized:' Objects in a cyclic isolate are
finalized one at a time, which means that there is a period of time when the
cyclic isolate is composed of a mix of finalized and non-finalized objects.
Finalization order is unspecified, so it can appear random.  A finalized
object must behave in a sane manner when non-finalized objects interact with
it, and a non-finalized object must be able to tolerate the finalization of
an arbitrary subset of its referents.

@item 
`All finalized:' All objects in a cyclic isolate are finalized before any
of them are cleared.

@item 
`Mix of finalized and cleared:' The objects can be cleared serially or
concurrently (but with the @ref{411,,GIL} held); either way, some will finish
before others.  A finalized object must be able to tolerate the clearing of
a subset of its referents.  
@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/} calls this stage «cyclic trash».

@item 
`Leaked:' If a cyclic isolate still exists after all objects in the group
have been finalized and cleared, then the objects remain indefinitely
uncollectable (see @ref{156a,,gc.garbage}).  It is a bug if a cyclic isolate
reaches this stage—it means the @ref{51f7,,tp_clear} methods
of the participating objects have failed to break the reference cycle as
required.
@end enumerate

If @ref{51f7,,tp_clear} did not exist, then Python would have no
way to safely break a reference cycle.  Simply destroying an object in a cyclic
isolate would result in a dangling pointer, triggering undefined behavior when
an object referencing the destroyed object is itself destroyed.  The clearing
step makes object destruction a two-phase process: first
@code{tp_clear} is called to partially destroy the objects
enough to detangle them from each other, then
@ref{51d3,,tp_dealloc} is called to complete the destruction.

Unlike clearing, finalization is not a phase of destruction.  A finalized
object must still behave properly by continuing to fulfill its design
contracts.  An object’s finalizer is allowed to execute arbitrary Python code,
and is even allowed to prevent the impending destruction by adding a reference.
The finalizer is only related to destruction by call order—if it runs, it runs
before destruction, which starts with @ref{51f7,,tp_clear} (if
called) and concludes with @ref{51d3,,tp_dealloc}.

The finalization step is not necessary to safely reclaim the objects in a
cyclic isolate, but its existence makes it easier to design types that behave
in a sane manner when objects are cleared.  Clearing an object might
necessarily leave it in a broken, partially destroyed state—it might be
unsafe to call any of the cleared object’s methods or access any of its
attributes.  With finalization, only finalized objects can possibly interact
with cleared objects; non-finalized objects are guaranteed to interact with
only non-cleared (but potentially finalized) objects.

To summarize the possible interactions:


@itemize *

@item 
A non-finalized object might have references to or from non-finalized and
finalized objects, but not to or from cleared objects.

@item 
A finalized object might have references to or from non-finalized, finalized,
and cleared objects.

@item 
A cleared object might have references to or from finalized and cleared
objects, but not to or from non-finalized objects.
@end itemize

Without any reference cycles, an object can be simply destroyed once its last
reference is deleted; the finalization and clearing steps are not necessary to
safely reclaim unused objects.  However, it can be useful to automatically call
@ref{e6c,,tp_finalize} and @ref{51f7,,tp_clear}
before destruction anyway because type design is simplified when all objects
always experience the same series of events regardless of whether they
participated in a cyclic isolate.  Python currently only calls
@code{tp_finalize} and @code{tp_clear} as
needed to destroy a cyclic isolate; this may change in a future version.

@node Functions<14>,,Cyclic Isolate Destruction,Object Life Cycle
@anchor{c-api/lifecycle functions}@anchor{5973}
@subsubsection Functions


To allocate and free memory, see @ref{5960,,Allocating objects on the heap}.

@geindex PyObject_CallFinalizer (C function)
@anchor{c-api/lifecycle c PyObject_CallFinalizer}@anchor{5974}
@deffn {C Συνάρτηση} void PyObject_CallFinalizer (PyObject *op)

Finalizes the object as described in @ref{e6c,,tp_finalize}.
Call this function (or @ref{351,,PyObject_CallFinalizerFromDealloc()}) instead
of calling @code{tp_finalize} directly because this
function may deduplicate multiple calls to @code{tp_finalize}.
Currently, calls are only deduplicated if the type supports garbage
collection (i.e., the @ref{39e,,Py_TPFLAGS_HAVE_GC} flag is set); this may
change in the future.


Added in version 3.4.

@end deffn

@geindex PyObject_CallFinalizerFromDealloc (C function)
@anchor{c-api/lifecycle c PyObject_CallFinalizerFromDealloc}@anchor{351}
@deffn {C Συνάρτηση} int PyObject_CallFinalizerFromDealloc (PyObject *op)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Same as @ref{5974,,PyObject_CallFinalizer()} but meant to be called at the
beginning of the object’s destructor (@ref{51d3,,tp_dealloc}).
There must not be any references to the object.  If the object’s finalizer
resurrects the object, this function returns -1; no further destruction
should happen.  Otherwise, this function returns 0 and destruction can
continue normally.


Added in version 3.4.



@subsubheading Δείτε επίσης


@ref{51d3,,tp_dealloc} for example code.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Common Object Structures,Type Object Structures,Object Life Cycle,Object Implementation Support
@anchor{c-api/structures doc}@anchor{5975}@anchor{c-api/structures common-object-structures}@anchor{5976}@anchor{c-api/structures common-structs}@anchor{5977}@anchor{c-api/structures translation-repo}@anchor{5978}
@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{5979}
@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{19b,,PyObject} and @ref{492d,,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{5530,,reference counting}.

@geindex PyObject (C type)
@anchor{c-api/structures c PyObject}@anchor{19b}
@deffn {C Τύπος} type PyObject
` Μέρος του @ref{95c,,Σταθερό ABI} (see below).'
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{19b,,PyObject}, but every pointer
to a Python object can be cast to a @ref{19b,,PyObject}*.

The members must not be accessed directly; instead use macros such as
@ref{54b,,Py_REFCNT} and @ref{5f5,,Py_TYPE}.

In the @ref{197,,Stable ABI} for Free-Threaded Builds (@code{abi3t}),
this struct is opaque; its size and layout may change between
Python versions.
In Stable ABI for non-free-threaded builds (@code{abi3}), the
@code{ob_refcnt} and @code{ob_type} fields are available,
but using them directly is discouraged.

@geindex PyObject.ob_refcnt (C member)
@anchor{c-api/structures c PyObject ob_refcnt}@anchor{c75}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} ob_refcnt
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The object’s reference count, as returned by @ref{54b,,Py_REFCNT}.
Do not use this field directly; instead use functions and macros such as
@code{Py_REFCNT}, @ref{974,,Py_INCREF()} and @ref{546c,,Py_DecRef()}.

The field type may be different from @code{Py_ssize_t}, depending on
build configuration and platform.
@end deffn

@geindex PyObject.ob_type (C member)
@anchor{c-api/structures c PyObject ob_type}@anchor{51e3}
@deffn {C Μέλος} @ref{e6b,,PyTypeObject} *ob_type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The object’s type.
Do not use this field directly; use @ref{5f5,,Py_TYPE} and
@ref{b60,,Py_SET_TYPE()} instead.
@end deffn

@geindex PyObject.ob_mutex (C member)
@anchor{c-api/structures c PyObject ob_mutex}@anchor{597a}
@deffn {C Μέλος} @ref{693,,PyMutex} ob_mutex

A @ref{597b,,per-object lock}, present only in the @ref{487,,free-threaded}
build (when @ref{191e,,Py_GIL_DISABLED} is defined).

This field is `reserved for use by the critical section API'
(@ref{5469,,Py_BEGIN_CRITICAL_SECTION} / @ref{546d,,Py_END_CRITICAL_SECTION}).
Do `not' lock it directly with @code{PyMutex_Lock}; doing so can cause
deadlocks.  If you need your own lock, add a separate @ref{693,,PyMutex}
field to your object struct.


Added in version 3.13.

@end deffn
@end deffn

@geindex PyVarObject (C type)
@anchor{c-api/structures c PyVarObject}@anchor{492d}
@deffn {C Τύπος} type PyVarObject
` Μέρος του @ref{95c,,Σταθερό ABI} (see below).'
An extension of @ref{19b,,PyObject} that adds the
@ref{545c,,ob_size} field.
This is intended for objects that have some notion of `length'.

As with @code{PyObject}, the members must not be accessed directly;
instead use macros such as @ref{b61,,Py_SIZE}, @ref{54b,,Py_REFCNT} and
@ref{5f5,,Py_TYPE}.

In the @ref{197,,Stable ABI} for Free-Threaded Builds (@code{abi3t}),
this struct is opaque; its size and layout may change between
Python versions.
In Stable ABI for non-free-threaded builds (@code{abi3}), the
@code{ob_base} and @code{ob_size} fields are available,
but using them directly is discouraged.

@geindex PyVarObject.ob_base (C member)
@anchor{c-api/structures c PyVarObject ob_base}@anchor{545b}
@deffn {C Μέλος} @ref{19b,,PyObject} ob_base
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Common object header.
Typically, this field is not accessed directly; instead
@code{PyVarObject} can be cast to @ref{19b,,PyObject}.
@end deffn

@geindex PyVarObject.ob_size (C member)
@anchor{c-api/structures c PyVarObject ob_size}@anchor{545c}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} ob_size
` Μέρος του @ref{95c,,Σταθερό ABI}.'
A size field, whose contents should be considered an object’s internal
implementation detail.

Do not use this field directly; use @ref{b61,,Py_SIZE} instead.

Object creation functions such as @ref{d4e,,PyObject_NewVar()} will
generally set this field to the requested size (number of items).
After creation, arbitrary values can be stored in @code{ob_size}
using @ref{b62,,Py_SET_SIZE}.

To get an object’s publicly exposed length, as returned by
the Python function @ref{a1f,,len()}, use @ref{53cc,,PyObject_Length()}
instead.
@end deffn
@end deffn

@geindex PyObject_HEAD (C macro)
@anchor{c-api/structures c PyObject_HEAD}@anchor{1682}
@deffn {C Μακροεντολή} 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{19b,,PyObject} above.
@end deffn

@geindex PyObject_VAR_HEAD (C macro)
@anchor{c-api/structures c PyObject_VAR_HEAD}@anchor{597c}
@deffn {C Μακροεντολή} 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{492d,,PyVarObject} above.
@end deffn

@geindex PyBaseObject_Type (C var)
@anchor{c-api/structures c PyBaseObject_Type}@anchor{529a}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyBaseObject_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The base class of all other objects, the same as @ref{e4d,,object} in Python.
@end deffn

@geindex Py_Is (C function)
@anchor{c-api/structures c Py_Is}@anchor{c76}
@deffn {C Συνάρτηση} int Py_Is (PyObject *x, PyObject *y)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Test if the `x' object is the `y' object, the same as @code{x is y} in Python.


Added in version 3.10.

@end deffn

@geindex Py_IsNone (C function)
@anchor{c-api/structures c Py_IsNone}@anchor{c77}
@deffn {C Συνάρτηση} int Py_IsNone (PyObject *x)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Test if an object is the @code{None} singleton,
the same as @code{x is None} in Python.


Added in version 3.10.

@end deffn

@geindex Py_IsTrue (C function)
@anchor{c-api/structures c Py_IsTrue}@anchor{c78}
@deffn {C Συνάρτηση} int Py_IsTrue (PyObject *x)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Test if an object is the @code{True} singleton,
the same as @code{x is True} in Python.


Added in version 3.10.

@end deffn

@geindex Py_IsFalse (C function)
@anchor{c-api/structures c Py_IsFalse}@anchor{c79}
@deffn {C Συνάρτηση} int Py_IsFalse (PyObject *x)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Test if an object is the @code{False} singleton,
the same as @code{x is False} in Python.


Added in version 3.10.

@end deffn

@geindex Py_TYPE (C function)
@anchor{c-api/structures c Py_TYPE}@anchor{5f5}
@deffn {C Συνάρτηση} @ref{e6b,,PyTypeObject} *Py_TYPE (PyObject *o)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
Get the type of the Python object `o'.

The returned reference is @ref{603,,borrowed} from `o'.
Do not release it with @ref{975,,Py_DECREF()} or similar.


Άλλαξε στην έκδοση 3.11: @ref{5f5,,Py_TYPE()} is changed to an inline static function.
The parameter type is no longer const @ref{19b,,PyObject}*.

@end deffn

@geindex Py_IS_TYPE (C function)
@anchor{c-api/structures c Py_IS_TYPE}@anchor{19bb}
@deffn {C Συνάρτηση} int Py_IS_TYPE (PyObject *o, PyTypeObject *type)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Return non-zero if the object `o' type is `type'. Return zero otherwise.
Equivalent to: @code{Py_TYPE(o) == type}.


Added in version 3.9.

@end deffn

@geindex Py_SET_TYPE (C function)
@anchor{c-api/structures c Py_SET_TYPE}@anchor{b60}
@deffn {C Συνάρτηση} void Py_SET_TYPE (PyObject *o, PyTypeObject *type)

Set the type of object `o' to `type', without any checking or reference
counting.

This is a very low-level operation.
Consider instead setting the Python attribute @ref{184f,,__class__}
using @ref{1a6c,,PyObject_SetAttrString()} or similar.

Note that assigning an incompatible type can lead to undefined behavior.

If `type' is a @ref{d2f,,heap type}, the caller must create a
new reference to it.
Similarly, if the old type of `o' is a heap type, the caller must release
a reference to that type.


Added in version 3.9.

@end deffn

@geindex Py_SIZE (C function)
@anchor{c-api/structures c Py_SIZE}@anchor{b61}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} Py_SIZE (PyVarObject *o)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Get the @ref{545c,,ob_size} field of `o'.


Άλλαξε στην έκδοση 3.11: @ref{b61,,Py_SIZE()} is changed to an inline static function.
The parameter type is no longer const @ref{492d,,PyVarObject}*.

@end deffn

@geindex Py_SET_SIZE (C function)
@anchor{c-api/structures c Py_SET_SIZE}@anchor{b62}
@deffn {C Συνάρτηση} void Py_SET_SIZE (PyVarObject *o, Py_ssize_t size)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
Set the @ref{545c,,ob_size} field of `o' to `size'.


Added in version 3.9.

@end deffn

@geindex PyObject_HEAD_INIT (C macro)
@anchor{c-api/structures c PyObject_HEAD_INIT}@anchor{597d}
@deffn {C Μακροεντολή} PyObject_HEAD_INIT (type)

This is a macro which expands to initialization values for a new
@ref{19b,,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{597e}
@deffn {C Μακροεντολή} PyVarObject_HEAD_INIT (type, size)

This is a macro which expands to initialization values for a new
@ref{492d,,PyVarObject} type, including the @ref{545c,,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{597f}
@subsubsection Implementing functions and methods


@geindex PyCFunction (C type)
@anchor{c-api/structures c PyCFunction}@anchor{181a}
@deffn {C Τύπος} type PyCFunction
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Type of the functions used to implement most Python callables in C.
Functions of this type take two @ref{19b,,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{52b0}
@deffn {C Τύπος} type PyCFunctionWithKeywords
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Type of the functions used to implement Python callables in C
with signature @ref{5980,,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{52ae}
@deffn {C Τύπος} type PyCFunctionFast
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Type of the functions used to implement Python callables in C
with signature @ref{34b,,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{52af}
@deffn {C Τύπος} type PyCFunctionFastWithKeywords
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.13.'
Type of the functions used to implement Python callables in C
with signature @ref{5981,,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{b46}
@deffn {C Τύπος} type PyCMethod

Type of the functions used to implement Python callables in C
with signature @ref{1c11,,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


Added in version 3.9.

@end deffn

@geindex PyMethodDef (C type)
@anchor{c-api/structures c PyMethodDef}@anchor{1879}
@deffn {C Τύπος} type PyMethodDef
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών).'
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{51fe}
@deffn {C Μέλος} const char *ml_name

Name of the method.

A @code{NULL} `ml_name' marks the end of a @code{PyMethodDef} array.
@end deffn

@geindex PyMethodDef.ml_meth (C member)
@anchor{c-api/structures c PyMethodDef ml_meth}@anchor{5982}
@deffn {C Μέλος} @ref{181a,,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{51bf}
@deffn {C Μέλος} 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{5983}
@deffn {C Μέλος} const char *ml_doc

Points to the contents of the docstring.
@end deffn
@end deffn

The @ref{5982,,ml_meth} is a C function pointer.
The functions may be of different
types, but they always return @ref{19b,,PyObject}*.  If the function is not of
the @ref{181a,,PyCFunction}, the compiler will require a cast in the method table.
Even though @code{PyCFunction} defines the first parameter as
PyObject*, it is common that the method implementation uses the
specific C type of the `self' object.

The @ref{51bf,,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{18aa}
@deffn {C Μακροεντολή} METH_VARARGS
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This is the typical calling convention, where the methods have the type
@ref{181a,,PyCFunction}. The function expects two @ref{19b,,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{3b1,,PyArg_ParseTuple()} or @ref{18a8,,PyArg_UnpackTuple()}.
@end deffn

@geindex METH_KEYWORDS (C macro)
@anchor{c-api/structures c METH_KEYWORDS}@anchor{51c6}
@deffn {C Μακροεντολή} METH_KEYWORDS

Can only be used in certain combinations with other flags:
@ref{5980,,METH_VARARGS | METH_KEYWORDS},
@ref{5981,,METH_FASTCALL | METH_KEYWORDS} and
@ref{1c11,,METH_METHOD | METH_FASTCALL | METH_KEYWORDS}.
@end deffn
@anchor{c-api/structures meth-varargs-meth-keywords}@anchor{5980}

@table @asis

@item @ref{18aa,,METH_VARARGS} | @ref{51c6,,METH_KEYWORDS}

Methods with these flags must be of type @ref{52b0,,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{818,,PyArg_ParseTupleAndKeywords()}.
@end table

@geindex METH_FASTCALL (C macro)
@anchor{c-api/structures c METH_FASTCALL}@anchor{34b}
@deffn {C Μακροεντολή} METH_FASTCALL
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Fast calling convention supporting only positional arguments.
The methods have the type @ref{52ae,,PyCFunctionFast}.
The first parameter is `self', the second parameter is a C array
of @ref{19b,,PyObject}* values indicating the arguments and the third
parameter is the number of arguments (the length of the array).


Added in version 3.7.



Άλλαξε στην έκδοση 3.10: @code{METH_FASTCALL} is now part of the @ref{197,,stable ABI}.

@end deffn
@anchor{c-api/structures meth-fastcall-meth-keywords}@anchor{5981}

@table @asis

@item @ref{34b,,METH_FASTCALL} | @ref{51c6,,METH_KEYWORDS}

Extension of @ref{34b,,METH_FASTCALL} supporting also keyword arguments,
with methods of type @ref{52af,,PyCFunctionFastWithKeywords}.
Keyword arguments are passed the same way as in the
@ref{95b,,vectorcall protocol}:
there is an additional fourth @ref{19b,,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.


Added in version 3.7.

@end table

@geindex METH_METHOD (C macro)
@anchor{c-api/structures c METH_METHOD}@anchor{d39}
@deffn {C Μακροεντολή} METH_METHOD
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.7.'
Can only be used in the combination with other flags:
@ref{1c11,,METH_METHOD | METH_FASTCALL | METH_KEYWORDS}.
@end deffn
@anchor{c-api/structures meth-method-meth-fastcall-meth-keywords}@anchor{1c11}

@table @asis

@item @ref{d39,,METH_METHOD} | @ref{34b,,METH_FASTCALL} | @ref{51c6,,METH_KEYWORDS}

Extension of @ref{5981,,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{b46,,PyCMethod}, the same as for
@code{METH_FASTCALL | METH_KEYWORDS} with @code{defining_class} argument added after
@code{self}.


Added in version 3.9.

@end table

@geindex METH_NOARGS (C macro)
@anchor{c-api/structures c METH_NOARGS}@anchor{1876}
@deffn {C Μακροεντολή} METH_NOARGS
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Methods without parameters don’t need to check whether arguments are given if
they are listed with the @ref{1876,,METH_NOARGS} flag.  They need to be of type
@ref{181a,,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{1c90,,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{18a9}
@deffn {C Μακροεντολή} METH_O
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Methods with a single object argument can be listed with the @ref{18a9,,METH_O}
flag, instead of invoking @ref{3b1,,PyArg_ParseTuple()} with a @code{"O"} argument.
They have the type @ref{181a,,PyCFunction}, with the `self' parameter, and a
@ref{19b,,PyObject}* parameter representing the single argument.
@end deffn

These two constants are not used to indicate the calling convention but the
binding when used 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{1877}
@deffn {C Μακροεντολή} METH_CLASS
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@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{69a,,classmethod()} built-in
function.
@end deffn

@geindex METH_STATIC (C macro)
@anchor{c-api/structures c METH_STATIC}@anchor{1878}
@deffn {C Μακροεντολή} METH_STATIC
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@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{666,,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{1819}
@deffn {C Μακροεντολή} METH_COEXIST
` Μέρος του @ref{95c,,Σταθερό ABI}.'
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{175c,,__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_Type (C var)
@anchor{c-api/structures c PyCMethod_Type}@anchor{5984}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyCMethod_Type

The type object corresponding to Python C method objects. This is
available as @ref{2bfb,,types.BuiltinMethodType} in the Python layer.
@end deffn

@geindex PyCMethod_Check (C function)
@anchor{c-api/structures c PyCMethod_Check}@anchor{5985}
@deffn {C Συνάρτηση} int PyCMethod_Check (PyObject *op)

Return true if `op' is an instance of the @ref{5984,,PyCMethod_Type} type
or a subtype of it. This function always succeeds.
@end deffn

@geindex PyCMethod_CheckExact (C function)
@anchor{c-api/structures c PyCMethod_CheckExact}@anchor{5986}
@deffn {C Συνάρτηση} int PyCMethod_CheckExact (PyObject *op)

This is the same as @ref{5985,,PyCMethod_Check()}, but does not account for
subtypes.
@end deffn

@geindex PyCMethod_New (C function)
@anchor{c-api/structures c PyCMethod_New}@anchor{1ea1}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCMethod_New (PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.9.'
Turn `ml' into a Python @ref{2fa4,,callable} object.
The caller must ensure that `ml' outlives the 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{2fa4,,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{a65,,None} or @code{NULL}.


@subsubheading Δείτε επίσης


@ref{253b,,function.__module__}


The `cls' parameter will be passed as the `defining_class'
argument to the C function.
Must be set if @ref{d39,,METH_METHOD} is set on @code{ml->ml_flags}.


Added in version 3.9.

@end deffn

@geindex PyCFunction_Type (C var)
@anchor{c-api/structures c PyCFunction_Type}@anchor{52b4}
@deffn {C Μεταβλητή} @ref{e6b,,PyTypeObject} PyCFunction_Type
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The type object corresponding to Python C function objects. This is
available as @ref{2bfa,,types.BuiltinFunctionType} in the Python layer.
@end deffn

@geindex PyCFunction_Check (C function)
@anchor{c-api/structures c PyCFunction_Check}@anchor{5987}
@deffn {C Συνάρτηση} int PyCFunction_Check (PyObject *op)

Return true if `op' is an instance of the @ref{52b4,,PyCFunction_Type} type
or a subtype of it. This function always succeeds.
@end deffn

@geindex PyCFunction_CheckExact (C function)
@anchor{c-api/structures c PyCFunction_CheckExact}@anchor{5988}
@deffn {C Συνάρτηση} int PyCFunction_CheckExact (PyObject *op)

This is the same as @ref{5987,,PyCFunction_Check()}, but does not account for
subtypes.
@end deffn

@geindex PyCFunction_NewEx (C function)
@anchor{c-api/structures c PyCFunction_NewEx}@anchor{1f6a}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCFunction_NewEx (PyMethodDef *ml, PyObject *self, PyObject *module)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό 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{1ea7}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCFunction_New (PyMethodDef *ml, PyObject *self)
`Επιστρεφόμενη τιμή: New reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.4.'
Equivalent to @code{PyCMethod_New(ml, self, NULL, NULL)}.
@end deffn

@geindex PyCFunction_GetFlags (C function)
@anchor{c-api/structures c PyCFunction_GetFlags}@anchor{52b1}
@deffn {C Συνάρτηση} int PyCFunction_GetFlags (PyObject *func)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Get the function’s flags on `func' as they were passed to
@ref{51bf,,ml_flags}.

If `func' is not a C function object, this fails with an exception.
`func' must not be @code{NULL}.

This function returns the function’s flags on success, and @code{-1} with an
exception set on failure.
@end deffn

@geindex PyCFunction_GET_FLAGS (C function)
@anchor{c-api/structures c PyCFunction_GET_FLAGS}@anchor{5989}
@deffn {C Συνάρτηση} int PyCFunction_GET_FLAGS (PyObject *func)

This is the same as @ref{52b1,,PyCFunction_GetFlags()}, but without error
or type checking.
@end deffn

@geindex PyCFunction_GetFunction (C function)
@anchor{c-api/structures c PyCFunction_GetFunction}@anchor{52b2}
@deffn {C Συνάρτηση} @ref{181a,,PyCFunction} PyCFunction_GetFunction (PyObject *func)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Get the function pointer on `func' as it was passed to
@ref{5982,,ml_meth}.

If `func' is not a C function object, this fails with an exception.
`func' must not be @code{NULL}.

This function returns the function pointer on success, and @code{NULL} with an
exception set on failure.
@end deffn

@geindex PyCFunction_GET_FUNCTION (C function)
@anchor{c-api/structures c PyCFunction_GET_FUNCTION}@anchor{598a}
@deffn {C Συνάρτηση} int PyCFunction_GET_FUNCTION (PyObject *func)

This is the same as @ref{52b2,,PyCFunction_GetFunction()}, but without error
or type checking.
@end deffn

@geindex PyCFunction_GetSelf (C function)
@anchor{c-api/structures c PyCFunction_GetSelf}@anchor{52b3}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCFunction_GetSelf (PyObject *func)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Get the «self» object on `func'. This is the object that would be passed
to the first argument of a @ref{181a,,PyCFunction}. For C function objects
created through a @ref{1879,,PyMethodDef} on a @ref{d45,,PyModuleDef}, this
is the resulting module object.

If `func' is not a C function object, this fails with an exception.
`func' must not be @code{NULL}.

This function returns a @ref{603,,borrowed reference} to the «self» object
on success, and @code{NULL} with an exception set on failure.
@end deffn

@geindex PyCFunction_GET_SELF (C function)
@anchor{c-api/structures c PyCFunction_GET_SELF}@anchor{598b}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyCFunction_GET_SELF (PyObject *func)

This is the same as @ref{52b3,,PyCFunction_GetSelf()}, but without error or
type checking.
@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{598c}
@subsubsection Accessing attributes of extension types


@geindex PyMemberDef (C type)
@anchor{c-api/structures c PyMemberDef}@anchor{95a}
@deffn {C Τύπος} type PyMemberDef
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών).'
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{51e7,,tp_members} slot.

Its fields are, in order:

@geindex PyMemberDef.name (C member)
@anchor{c-api/structures c PyMemberDef name}@anchor{598d}
@deffn {C Μέλος} 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{51ff}
@deffn {C Μέλος} int type

The type of the member in the C struct.
See @ref{1bf9,,Member types} for the possible values.
@end deffn

@geindex PyMemberDef.offset (C member)
@anchor{c-api/structures c PyMemberDef offset}@anchor{598e}
@deffn {C Μέλος} @ref{e24,,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{5200}
@deffn {C Μέλος} int flags

Zero or more of the @ref{598f,,Member flags}, combined using bitwise OR.
@end deffn

@geindex PyMemberDef.doc (C member)
@anchor{c-api/structures c PyMemberDef doc}@anchor{5990}
@deffn {C Μέλος} const char *doc

The docstring, or NULL.
The string should be static, no copy is made of it.
Typically, it is defined using @ref{1d92,,PyDoc_STR}.
@end deffn

By default (when @ref{5200,,flags} is @code{0}), members allow
both read and write access.
Use the @ref{990,,Py_READONLY} flag for read-only access.
Certain types, like @ref{5486,,Py_T_STRING}, imply @code{Py_READONLY}.
Only @ref{993,,Py_T_OBJECT_EX} (and legacy @ref{992,,T_OBJECT}) members can
be deleted.
@anchor{c-api/structures pymemberdef-offsets}@anchor{564d}
For heap-allocated types (created using @ref{38e,,PyType_FromSpec()} or similar),
@code{PyMemberDef} may contain a definition for the special member
@code{"__vectorcalloffset__"}, corresponding to
@ref{55f8,,tp_vectorcall_offset} in type objects.
This member must be defined with @code{Py_T_PYSSIZET}, and either
@code{Py_READONLY} or @code{Py_READONLY | Py_RELATIVE_OFFSET}. 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{564c,,tp_dictoffset} and
@ref{d50,,tp_weaklistoffset} can be defined similarly using
@code{"__dictoffset__"} and @code{"__weaklistoffset__"} members, but extensions
are strongly encouraged to use @ref{39c,,Py_TPFLAGS_MANAGED_DICT} and
@ref{39d,,Py_TPFLAGS_MANAGED_WEAKREF} instead.


Άλλαξε στην έκδοση 3.12: @code{PyMemberDef} is always available.
Previously, it required including @code{"structmember.h"}.



Άλλαξε στην έκδοση 3.14: @ref{959,,Py_RELATIVE_OFFSET} is now allowed for
@code{"__vectorcalloffset__"}, @code{"__dictoffset__"} and
@code{"__weaklistoffset__"}.

@end deffn

@geindex PyMember_GetOne (C function)
@anchor{c-api/structures c PyMember_GetOne}@anchor{98c}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyMember_GetOne (const char *obj_addr, struct PyMemberDef *m)
` Μέρος του @ref{95c,,Σταθερό 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.


Άλλαξε στην έκδοση 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{98d}
@deffn {C Συνάρτηση} int PyMember_SetOne (char *obj_addr, struct PyMemberDef *m, PyObject *o)
` Μέρος του @ref{95c,,Σταθερό 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.


Άλλαξε στην έκδοση 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{5991}@anchor{c-api/structures pymemberdef-flags}@anchor{598f}
@subsubsection Member flags


The following flags can be used with @ref{5200,,PyMemberDef.flags}:

@geindex Py_READONLY (C macro)
@anchor{c-api/structures c Py_READONLY}@anchor{990}
@deffn {C Μακροεντολή} Py_READONLY
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
Not writable.
@end deffn

@geindex Py_AUDIT_READ (C macro)
@anchor{c-api/structures c Py_AUDIT_READ}@anchor{991}
@deffn {C Μακροεντολή} Py_AUDIT_READ
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
Emit an @code{object.__getattr__} @ref{1e0a,,audit event}
before reading.
@end deffn

@geindex Py_RELATIVE_OFFSET (C macro)
@anchor{c-api/structures c Py_RELATIVE_OFFSET}@anchor{959}
@deffn {C Μακροεντολή} Py_RELATIVE_OFFSET
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
Indicates that the @ref{598e,,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 the @ref{54de,,Py_tp_members}
@ref{541b,,slot} when creating a class using negative
@ref{199,,basicsize}.
It is mandatory in that case.
When setting @ref{51e7,,tp_members} from the slot during
class creation, Python clears the flag and sets
@ref{598e,,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)


Άλλαξε στην έκδοση 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{991,,Py_AUDIT_READ}; @code{WRITE_RESTRICTED} does nothing.


@geindex READONLY (C macro)


Άλλαξε στην έκδοση 3.12: The @code{READONLY} macro was renamed to @ref{990,,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{5992}@anchor{c-api/structures pymemberdef-types}@anchor{1bf9}
@subsubsection Member types


@ref{51ff,,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{291,,TypeError} or
@ref{277,,ValueError} is raised.

Unless marked (D), attributes defined this way cannot be deleted
using e.g. @ref{1d1d,,del} or @ref{1aa,,delattr()}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Macro name

@tab

C type

@tab

Python type

@item

@geindex Py_T_BYTE (C macro)
@anchor{c-api/structures c Py_T_BYTE}@anchor{547f}
@deffn {C Μακροεντολή} Py_T_BYTE
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

char

@tab

@ref{326,,int}

@item

@geindex Py_T_SHORT (C macro)
@anchor{c-api/structures c Py_T_SHORT}@anchor{5485}
@deffn {C Μακροεντολή} Py_T_SHORT
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

short

@tab

@ref{326,,int}

@item

@geindex Py_T_INT (C macro)
@anchor{c-api/structures c Py_T_INT}@anchor{98e}
@deffn {C Μακροεντολή} Py_T_INT
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

int

@tab

@ref{326,,int}

@item

@geindex Py_T_LONG (C macro)
@anchor{c-api/structures c Py_T_LONG}@anchor{5482}
@deffn {C Μακροεντολή} Py_T_LONG
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

long

@tab

@ref{326,,int}

@item

@geindex Py_T_LONGLONG (C macro)
@anchor{c-api/structures c Py_T_LONGLONG}@anchor{5483}
@deffn {C Μακροεντολή} Py_T_LONGLONG
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

long long

@tab

@ref{326,,int}

@item

@geindex Py_T_UBYTE (C macro)
@anchor{c-api/structures c Py_T_UBYTE}@anchor{5488}
@deffn {C Μακροεντολή} Py_T_UBYTE
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

unsigned char

@tab

@ref{326,,int}

@item

@geindex Py_T_UINT (C macro)
@anchor{c-api/structures c Py_T_UINT}@anchor{5489}
@deffn {C Μακροεντολή} Py_T_UINT
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

unsigned int

@tab

@ref{326,,int}

@item

@geindex Py_T_USHORT (C macro)
@anchor{c-api/structures c Py_T_USHORT}@anchor{548c}
@deffn {C Μακροεντολή} Py_T_USHORT
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

unsigned short

@tab

@ref{326,,int}

@item

@geindex Py_T_ULONG (C macro)
@anchor{c-api/structures c Py_T_ULONG}@anchor{548a}
@deffn {C Μακροεντολή} Py_T_ULONG
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

unsigned long

@tab

@ref{326,,int}

@item

@geindex Py_T_ULONGLONG (C macro)
@anchor{c-api/structures c Py_T_ULONGLONG}@anchor{548b}
@deffn {C Μακροεντολή} Py_T_ULONGLONG
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

unsigned long long

@tab

@ref{326,,int}

@item

@geindex Py_T_PYSSIZET (C macro)
@anchor{c-api/structures c Py_T_PYSSIZET}@anchor{5484}
@deffn {C Μακροεντολή} Py_T_PYSSIZET
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

@ref{e24,,Py_ssize_t}

@tab

@ref{326,,int}

@item

@geindex Py_T_FLOAT (C macro)
@anchor{c-api/structures c Py_T_FLOAT}@anchor{5481}
@deffn {C Μακροεντολή} Py_T_FLOAT
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

float

@tab

@ref{327,,float}

@item

@geindex Py_T_DOUBLE (C macro)
@anchor{c-api/structures c Py_T_DOUBLE}@anchor{98f}
@deffn {C Μακροεντολή} Py_T_DOUBLE
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

double

@tab

@ref{327,,float}

@item

@geindex Py_T_BOOL (C macro)
@anchor{c-api/structures c Py_T_BOOL}@anchor{547e}
@deffn {C Μακροεντολή} Py_T_BOOL
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

char
(written as 0 or 1)

@tab

@ref{5ef,,bool}

@item

@geindex Py_T_STRING (C macro)
@anchor{c-api/structures c Py_T_STRING}@anchor{5486}
@deffn {C Μακροεντολή} Py_T_STRING
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

const char* (*)

@tab

@ref{1df,,str} (RO)

@item

@geindex Py_T_STRING_INPLACE (C macro)
@anchor{c-api/structures c Py_T_STRING_INPLACE}@anchor{5487}
@deffn {C Μακροεντολή} Py_T_STRING_INPLACE
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

const char[] (*)

@tab

@ref{1df,,str} (RO)

@item

@geindex Py_T_CHAR (C macro)
@anchor{c-api/structures c Py_T_CHAR}@anchor{5480}
@deffn {C Μακροεντολή} Py_T_CHAR
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

char (0-127)

@tab

@ref{1df,,str} (**)

@item

@geindex Py_T_OBJECT_EX (C macro)
@anchor{c-api/structures c Py_T_OBJECT_EX}@anchor{993}
@deffn {C Μακροεντολή} Py_T_OBJECT_EX
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@tab

@ref{19b,,PyObject}*

@tab

@ref{e4d,,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{990,,Py_READONLY}.

(D): Can be deleted, in which case the pointer is set to @code{NULL}.
Reading a @code{NULL} pointer raises @ref{1a9,,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


Added in 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{992}
@deffn {C Μακροεντολή} 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{994}
@deffn {C Μακροεντολή} T_NONE

Always @code{None}. Must be used with @ref{990,,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{5993}
@subsubsection Defining Getters and Setters


@geindex PyGetSetDef (C type)
@anchor{c-api/structures c PyGetSetDef}@anchor{f77}
@deffn {C Τύπος} type PyGetSetDef
` Μέρος του @ref{95c,,Σταθερό ABI} (συμπεριλαμβανομένων όλων των μελών).'
Structure to define property-like access for a type. See also description of
the @ref{51ec,,PyTypeObject.tp_getset} slot.

@geindex PyGetSetDef.name (C member)
@anchor{c-api/structures c PyGetSetDef name}@anchor{5994}
@deffn {C Μέλος} const char *name

attribute name
@end deffn

@geindex PyGetSetDef.get (C member)
@anchor{c-api/structures c PyGetSetDef get}@anchor{5995}
@deffn {C Μέλος} @ref{54f1,,getter} get

C function to get the attribute.
@end deffn

@geindex PyGetSetDef.set (C member)
@anchor{c-api/structures c PyGetSetDef set}@anchor{5996}
@deffn {C Μέλος} @ref{54ff,,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{5997}
@deffn {C Μέλος} const char *doc

optional docstring
@end deffn

@geindex PyGetSetDef.closure (C member)
@anchor{c-api/structures c PyGetSetDef closure}@anchor{5998}
@deffn {C Μέλος} 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{54f1}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*getter)(@ref{19b,,PyObject}*, void*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
The @code{get} function takes one @ref{19b,,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{54ff}
@deffn {C Τύπος} typedef int (*setter)(@ref{19b,,PyObject}*, @ref{19b,,PyObject}*, void*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@code{set} functions take two @ref{19b,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Type Object Structures,Supporting Cyclic Garbage Collection,Common Object Structures,Object Implementation Support
@anchor{c-api/typeobj doc}@anchor{5999}@anchor{c-api/typeobj translation-repo}@anchor{599a}@anchor{c-api/typeobj type-object-structures}@anchor{599b}@anchor{c-api/typeobj type-structs}@anchor{d55}
@subsection Type Object Structures


Perhaps one of the most important structures of the Python object system is the
structure that defines a new type: the @ref{e6b,,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{599c,,Examples}
section provides at-a-glance insight into the meaning and use of
@ref{e6b,,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:: 
* Examples: Examples<33>. 

@end menu

@node Quick Reference,PyTypeObject Definition,,Type Object Structures
@anchor{c-api/typeobj quick-reference}@anchor{599d}
@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{599e}@anchor{c-api/typeobj tp-slots-table}@anchor{599f}
@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{59a0,,Type}

@tab

special
methods/attrs

@tab

Info @footnote{
Columns:

`«O»':  set on @ref{529a,,PyBaseObject_Type}

`«T»':  set on @ref{958,,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{1ea6,,tp_name}

@tab

const char *

@tab

__name__

@tab

X

@tab

X

@tab

@tab

@item

@ref{d4f,,tp_basicsize}

@tab

@ref{e24,,Py_ssize_t}

@tab

@tab

X

@tab

X

@tab

@tab

X

@item

@ref{25b0,,tp_itemsize}

@tab

@ref{e24,,Py_ssize_t}

@tab

@tab

@tab

X

@tab

@tab

X

@item

@ref{51d3,,tp_dealloc}

@tab

@ref{54ec,,destructor}

@tab

@tab

X

@tab

X

@tab

@tab

X

@item

@ref{55f8,,tp_vectorcall_offset}

@tab

@ref{e24,,Py_ssize_t}

@tab

@tab

@tab

X

@tab

@tab

X

@item

(@ref{5202,,tp_getattr})

@tab

@ref{54ed,,getattrfunc}

@tab

__getattribute__,
__getattr__

@tab

@tab

@tab

@tab

G

@item

(@ref{5203,,tp_setattr})

@tab

@ref{54fd,,setattrfunc}

@tab

__setattr__,
__delattr__

@tab

@tab

@tab

@tab

G

@item

@ref{127d,,tp_as_async}

@tab

@ref{564a,,PyAsyncMethods} *

@tab

@ref{59a1,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{51f9,,tp_repr}

@tab

@ref{54fb,,reprfunc}

@tab

__repr__

@tab

X

@tab

X

@tab

@tab

X

@item

@ref{d53,,tp_as_number}

@tab

@ref{17c0,,PyNumberMethods} *

@tab

@ref{59a1,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{59a2,,tp_as_sequence}

@tab

@ref{5209,,PySequenceMethods} *

@tab

@ref{59a1,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{59a3,,tp_as_mapping}

@tab

@ref{520a,,PyMappingMethods} *

@tab

@ref{59a1,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{520b,,tp_hash}

@tab

@ref{54f2,,hashfunc}

@tab

__hash__

@tab

X

@tab

@tab

@tab

G

@item

@ref{962,,tp_call}

@tab

@ref{5502,,ternaryfunc}

@tab

__call__

@tab

@tab

X

@tab

@tab

X

@item

@ref{51fa,,tp_str}

@tab

@ref{54fb,,reprfunc}

@tab

__str__

@tab

X

@tab

@tab

@tab

X

@item

@ref{1c6a,,tp_getattro}

@tab

@ref{54ee,,getattrofunc}

@tab

__getattribute__,
__getattr__

@tab

X

@tab

X

@tab

@tab

G

@item

@ref{51fd,,tp_setattro}

@tab

@ref{54fe,,setattrofunc}

@tab

__setattr__,
__delattr__

@tab

X

@tab

X

@tab

@tab

G

@item

@ref{d51,,tp_as_buffer}

@tab

@ref{5651,,PyBufferProcs} *

@tab

@ref{59a1,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{1e68,,tp_flags}

@tab

unsigned long

@tab

@tab

X

@tab

X

@tab

@tab

?

@item

@ref{51e1,,tp_doc}

@tab

const char *

@tab

__doc__

@tab

X

@tab

X

@tab

@tab

@item

@ref{36b,,tp_traverse}

@tab

@ref{5503,,traverseproc}

@tab

@tab

@tab

X

@tab

@tab

G

@item

@ref{51f7,,tp_clear}

@tab

@ref{54f4,,inquiry}

@tab

@tab

@tab

X

@tab

@tab

G

@item

@ref{5205,,tp_richcompare}

@tab

@ref{54fc,,richcmpfunc}

@tab

__lt__,
__le__,
__eq__,
__ne__,
__gt__,
__ge__

@tab

X

@tab

@tab

@tab

G

@item

(@ref{d50,,tp_weaklistoffset})

@tab

@ref{e24,,Py_ssize_t}

@tab

@tab

@tab

X

@tab

@tab

?

@item

@ref{1891,,tp_iter}

@tab

@ref{54f0,,getiterfunc}

@tab

__iter__

@tab

@tab

@tab

@tab

X

@item

@ref{1892,,tp_iternext}

@tab

@ref{54f5,,iternextfunc}

@tab

__next__

@tab

@tab

@tab

@tab

X

@item

@ref{51e9,,tp_methods}

@tab

@ref{1879,,PyMethodDef} []

@tab

@tab

X

@tab

X

@tab

@tab

@item

@ref{51e7,,tp_members}

@tab

@ref{95a,,PyMemberDef} []

@tab

@tab

@tab

X

@tab

@tab

@item

@ref{51ec,,tp_getset}

@tab

@ref{f77,,PyGetSetDef} []

@tab

@tab

X

@tab

X

@tab

@tab

@item

@ref{2567,,tp_base}

@tab

@ref{e6b,,PyTypeObject} *

@tab

__base__

@tab

@tab

@tab

X

@tab

@item

@ref{1c92,,tp_dict}

@tab

@ref{19b,,PyObject} *

@tab

__dict__

@tab

@tab

@tab

?

@tab

@item

@ref{57d6,,tp_descr_get}

@tab

@ref{54ea,,descrgetfunc}

@tab

__get__

@tab

@tab

@tab

@tab

X

@item

@ref{1eaa,,tp_descr_set}

@tab

@ref{54eb,,descrsetfunc}

@tab

__set__,
__delete__

@tab

@tab

@tab

@tab

X

@item

(@ref{564c,,tp_dictoffset})

@tab

@ref{e24,,Py_ssize_t}

@tab

@tab

@tab

X

@tab

@tab

?

@item

@ref{983,,tp_init}

@tab

@ref{54f3,,initproc}

@tab

__init__

@tab

X

@tab

X

@tab

@tab

X

@item

@ref{51e6,,tp_alloc}

@tab

@ref{54e8,,allocfunc}

@tab

@tab

X

@tab

@tab

?

@tab

?

@item

@ref{981,,tp_new}

@tab

@ref{54f7,,newfunc}

@tab

__new__

@tab

X

@tab

X

@tab

?

@tab

?

@item

@ref{51e5,,tp_free}

@tab

@ref{57bd,,freefunc}

@tab

@tab

X

@tab

X

@tab

?

@tab

?

@item

@ref{59a4,,tp_is_gc}

@tab

@ref{54f4,,inquiry}

@tab

@tab

@tab

X

@tab

@tab

X

@item

<@ref{59a5,,tp_bases}>

@tab

@ref{19b,,PyObject} *

@tab

__bases__

@tab

@tab

@tab

~

@tab

@item

<@ref{564e,,tp_mro}>

@tab

@ref{19b,,PyObject} *

@tab

__mro__

@tab

@tab

@tab

~

@tab

@item

[@ref{564f,,tp_cache}]

@tab

@ref{19b,,PyObject} *

@tab

@tab

@tab

@tab

@tab

@item

[@ref{977,,tp_subclasses}]

@tab

void *

@tab

__subclasses__

@tab

@tab

@tab

@tab

@item

[@ref{5650,,tp_weaklist}]

@tab

@ref{19b,,PyObject} *

@tab

@tab

@tab

@tab

@tab

@item

(@ref{59a6,,tp_del})

@tab

@ref{54ec,,destructor}

@tab

@tab

@tab

@tab

@tab

@item

[@ref{59a7,,tp_version_tag}]

@tab

unsigned int

@tab

@tab

@tab

@tab

@tab

@item

@ref{e6c,,tp_finalize}

@tab

@ref{54ec,,destructor}

@tab

__del__

@tab

@tab

@tab

@tab

X

@item

@ref{1b9a,,tp_vectorcall}

@tab

@ref{960,,vectorcallfunc}

@tab

@tab

@tab

@tab

@tab

@item

[@ref{59a8,,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{59a9}@anchor{c-api/typeobj sub-slots}@anchor{59a1}
@subsubsection sub-slots



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

Slot

@tab

@ref{59a0,,Type}

@tab

special
methods

@item

@ref{59aa,,am_await}

@tab

@ref{5504,,unaryfunc}

@tab

__await__

@item

@ref{59ab,,am_aiter}

@tab

@ref{5504,,unaryfunc}

@tab

__aiter__

@item

@ref{59ac,,am_anext}

@tab

@ref{5504,,unaryfunc}

@tab

__anext__

@item

@ref{59ad,,am_send}

@tab

@ref{59ae,,sendfunc}

@tab

@item

@tab

@tab

@item

@ref{5645,,nb_add}

@tab

@ref{54e9,,binaryfunc}

@tab

__add__
__radd__

@item

@ref{59af,,nb_inplace_add}

@tab

@ref{54e9,,binaryfunc}

@tab

__iadd__

@item

@ref{59b0,,nb_subtract}

@tab

@ref{54e9,,binaryfunc}

@tab

__sub__
__rsub__

@item

@ref{59b1,,nb_inplace_subtract}

@tab

@ref{54e9,,binaryfunc}

@tab

__isub__

@item

@ref{59b2,,nb_multiply}

@tab

@ref{54e9,,binaryfunc}

@tab

__mul__
__rmul__

@item

@ref{59b3,,nb_inplace_multiply}

@tab

@ref{54e9,,binaryfunc}

@tab

__imul__

@item

@ref{59b4,,nb_remainder}

@tab

@ref{54e9,,binaryfunc}

@tab

__mod__
__rmod__

@item

@ref{59b5,,nb_inplace_remainder}

@tab

@ref{54e9,,binaryfunc}

@tab

__imod__

@item

@ref{59b6,,nb_divmod}

@tab

@ref{54e9,,binaryfunc}

@tab

__divmod__
__rdivmod__

@item

@ref{59b7,,nb_power}

@tab

@ref{5502,,ternaryfunc}

@tab

__pow__
__rpow__

@item

@ref{59b8,,nb_inplace_power}

@tab

@ref{5502,,ternaryfunc}

@tab

__ipow__

@item

@ref{59b9,,nb_negative}

@tab

@ref{5504,,unaryfunc}

@tab

__neg__

@item

@ref{59ba,,nb_positive}

@tab

@ref{5504,,unaryfunc}

@tab

__pos__

@item

@ref{59bb,,nb_absolute}

@tab

@ref{5504,,unaryfunc}

@tab

__abs__

@item

@ref{59bc,,nb_bool}

@tab

@ref{54f4,,inquiry}

@tab

__bool__

@item

@ref{59bd,,nb_invert}

@tab

@ref{5504,,unaryfunc}

@tab

__invert__

@item

@ref{59be,,nb_lshift}

@tab

@ref{54e9,,binaryfunc}

@tab

__lshift__
__rlshift__

@item

@ref{59bf,,nb_inplace_lshift}

@tab

@ref{54e9,,binaryfunc}

@tab

__ilshift__

@item

@ref{59c0,,nb_rshift}

@tab

@ref{54e9,,binaryfunc}

@tab

__rshift__
__rrshift__

@item

@ref{59c1,,nb_inplace_rshift}

@tab

@ref{54e9,,binaryfunc}

@tab

__irshift__

@item

@ref{59c2,,nb_and}

@tab

@ref{54e9,,binaryfunc}

@tab

__and__
__rand__

@item

@ref{59c3,,nb_inplace_and}

@tab

@ref{54e9,,binaryfunc}

@tab

__iand__

@item

@ref{59c4,,nb_xor}

@tab

@ref{54e9,,binaryfunc}

@tab

__xor__
__rxor__

@item

@ref{59c5,,nb_inplace_xor}

@tab

@ref{54e9,,binaryfunc}

@tab

__ixor__

@item

@ref{59c6,,nb_or}

@tab

@ref{54e9,,binaryfunc}

@tab

__or__
__ror__

@item

@ref{59c7,,nb_inplace_or}

@tab

@ref{54e9,,binaryfunc}

@tab

__ior__

@item

@ref{59c8,,nb_int}

@tab

@ref{5504,,unaryfunc}

@tab

__int__

@item

@ref{59c9,,nb_reserved}

@tab

void *

@tab

@item

@ref{59ca,,nb_float}

@tab

@ref{5504,,unaryfunc}

@tab

__float__

@item

@ref{59cb,,nb_floor_divide}

@tab

@ref{54e9,,binaryfunc}

@tab

__floordiv__

@item

@ref{59cc,,nb_inplace_floor_divide}

@tab

@ref{54e9,,binaryfunc}

@tab

__ifloordiv__

@item

@ref{59cd,,nb_true_divide}

@tab

@ref{54e9,,binaryfunc}

@tab

__truediv__

@item

@ref{59ce,,nb_inplace_true_divide}

@tab

@ref{54e9,,binaryfunc}

@tab

__itruediv__

@item

@ref{17bf,,nb_index}

@tab

@ref{5504,,unaryfunc}

@tab

__index__

@item

@ref{59cf,,nb_matrix_multiply}

@tab

@ref{54e9,,binaryfunc}

@tab

__matmul__
__rmatmul__

@item

@ref{59d0,,nb_inplace_matrix_multiply}

@tab

@ref{54e9,,binaryfunc}

@tab

__imatmul__

@item

@tab

@tab

@item

@ref{59d1,,mp_length}

@tab

@ref{54f6,,lenfunc}

@tab

__len__

@item

@ref{1eeb,,mp_subscript}

@tab

@ref{54e9,,binaryfunc}

@tab

__getitem__

@item

@ref{59d2,,mp_ass_subscript}

@tab

@ref{54f8,,objobjargproc}

@tab

__setitem__,
__delitem__

@item

@tab

@tab

@item

@ref{564b,,sq_length}

@tab

@ref{54f6,,lenfunc}

@tab

__len__

@item

@ref{59d3,,sq_concat}

@tab

@ref{54e9,,binaryfunc}

@tab

__add__

@item

@ref{59d4,,sq_repeat}

@tab

@ref{5500,,ssizeargfunc}

@tab

__mul__

@item

@ref{1eea,,sq_item}

@tab

@ref{5500,,ssizeargfunc}

@tab

__getitem__

@item

@ref{59d5,,sq_ass_item}

@tab

@ref{5501,,ssizeobjargproc}

@tab

__setitem__
__delitem__

@item

@ref{59d6,,sq_contains}

@tab

@ref{54f9,,objobjproc}

@tab

__contains__

@item

@ref{59d7,,sq_inplace_concat}

@tab

@ref{54e9,,binaryfunc}

@tab

__iadd__

@item

@ref{59d8,,sq_inplace_repeat}

@tab

@ref{5500,,ssizeargfunc}

@tab

__imul__

@item

@tab

@tab

@item

@ref{b44,,bf_getbuffer}

@tab

@ref{54ef,,getbufferproc()}

@tab

__buffer__

@item

@ref{b45,,bf_releasebuffer}

@tab

@ref{54fa,,releasebufferproc()}

@tab

__release_buffer__

@end multitable


@node slot typedefs,,sub-slots,Quick Reference
@anchor{c-api/typeobj slot-typedefs}@anchor{59d9}@anchor{c-api/typeobj slot-typedefs-table}@anchor{59a0}
@subsubsection slot typedefs



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

typedef

@tab

Parameter Types

@tab

Return Type

@item

@ref{54e8,,allocfunc}

@tab


@display
@ref{e6b,,PyTypeObject} *@w{ }
@ref{e24,,Py_ssize_t}@w{ }
@end display



@tab

@ref{19b,,PyObject} *

@item

@ref{54ec,,destructor}

@tab

@ref{19b,,PyObject} *

@tab

void

@item

@ref{57bd,,freefunc}

@tab

void *

@tab

void

@item

@ref{5503,,traverseproc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{5505,,visitproc}@w{ }
void *@w{ }
@end display



@tab

int

@item

@ref{54f7,,newfunc}

@tab


@display
@ref{e6b,,PyTypeObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@end display



@tab

@ref{19b,,PyObject} *

@item

@ref{54f3,,initproc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@end display



@tab

int

@item

@ref{54fb,,reprfunc}

@tab

@ref{19b,,PyObject} *

@tab

@ref{19b,,PyObject} *

@item

@ref{54ed,,getattrfunc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
const char *@w{ }
@end display



@tab

@ref{19b,,PyObject} *

@item

@ref{54fd,,setattrfunc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
const char *@w{ }
@ref{19b,,PyObject} *@w{ }
@end display



@tab

int

@item

@ref{54ee,,getattrofunc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@end display



@tab

@ref{19b,,PyObject} *

@item

@ref{54fe,,setattrofunc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@end display



@tab

int

@item

@ref{54ea,,descrgetfunc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@end display



@tab

@ref{19b,,PyObject} *

@item

@ref{54eb,,descrsetfunc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@end display



@tab

int

@item

@ref{54f2,,hashfunc}

@tab

@ref{19b,,PyObject} *

@tab

Py_hash_t

@item

@ref{54fc,,richcmpfunc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
int@w{ }
@end display



@tab

@ref{19b,,PyObject} *

@item

@ref{54f0,,getiterfunc}

@tab

@ref{19b,,PyObject} *

@tab

@ref{19b,,PyObject} *

@item

@ref{54f5,,iternextfunc}

@tab

@ref{19b,,PyObject} *

@tab

@ref{19b,,PyObject} *

@item

@ref{54f6,,lenfunc}

@tab

@ref{19b,,PyObject} *

@tab

@ref{e24,,Py_ssize_t}

@item

@ref{54ef,,getbufferproc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{b3a,,Py_buffer} *@w{ }
int@w{ }
@end display



@tab

int

@item

@ref{54fa,,releasebufferproc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{b3a,,Py_buffer} *@w{ }
@end display



@tab

void

@item

@ref{54f4,,inquiry}

@tab

@ref{19b,,PyObject} *

@tab

int

@item

@ref{5504,,unaryfunc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@end display



@tab

@ref{19b,,PyObject} *

@item

@ref{54e9,,binaryfunc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@end display



@tab

@ref{19b,,PyObject} *

@item

@ref{5502,,ternaryfunc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@end display



@tab

@ref{19b,,PyObject} *

@item

@ref{5500,,ssizeargfunc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{e24,,Py_ssize_t}@w{ }
@end display



@tab

@ref{19b,,PyObject} *

@item

@ref{5501,,ssizeobjargproc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{e24,,Py_ssize_t}@w{ }
@ref{19b,,PyObject} *@w{ }
@end display



@tab

int

@item

@ref{54f9,,objobjproc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@end display



@tab

int

@item

@ref{54f8,,objobjargproc}

@tab


@display
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@ref{19b,,PyObject} *@w{ }
@end display



@tab

int

@end multitable


See @ref{59da,,Slot Type typedefs} below for more detail.

@node PyTypeObject Definition,PyObject Slots,Quick Reference,Type Object Structures
@anchor{c-api/typeobj pytypeobject-definition}@anchor{59db}
@subsubsection PyTypeObject Definition


The structure definition for @ref{e6b,,PyTypeObject} can be found in
@code{Include/cpython/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 */
    PyMethodDef *tp_methods;
    PyMemberDef *tp_members;
    PyGetSetDef *tp_getset;
    // Strong reference on a heap type, borrowed reference on a static type
    PyTypeObject *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; /* no longer used */
    void *tp_subclasses;  /* for static builtin types this is an index */
    PyObject *tp_weaklist; /* not used for static builtin types */
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6.
     * If zero, the cache is invalid and must be initialized.
     */
    unsigned int tp_version_tag;

    destructor tp_finalize;
    vectorcallfunc tp_vectorcall;

    /* bitset of which type-watchers care about this type */
    unsigned char tp_watched;

    /* Number of tp_version_tag values used.
     * Set to _Py_ATTR_CACHE_UNUSED if the attribute cache is
     * disabled for this type (e.g. due to custom MRO entries).
     * Otherwise, limited to MAX_VERSIONS_PER_CLASS (defined elsewhere).
     */
    uint16_t tp_versions_used;
@} PyTypeObject;
@end example

@node PyObject Slots,PyVarObject Slots,PyTypeObject Definition,Type Object Structures
@anchor{c-api/typeobj pyobject-slots}@anchor{59dc}
@subsubsection PyObject Slots


The type object structure extends the @ref{492d,,PyVarObject} structure. The
@ref{545c,,ob_size} field is used for dynamic types (created by @code{type_new()},
usually called from a class statement). Note that @ref{958,,PyType_Type} (the
metatype) initializes @ref{25b0,,tp_itemsize}, which means that its instances (i.e.
type objects) `must' have the @code{ob_size} field.

@ref{c75,,PyObject.ob_refcnt}

@quotation

The type object’s reference count is initialized to @code{1} by the
@code{PyObject_HEAD_INIT} macro.  Note that for @ref{b5f,,statically allocated type objects}, the type’s instances (objects whose @ref{51e3,,ob_type}
points back to the type) do `not' count as references.  But for
@ref{d2f,,dynamically allocated type objects}, the instances `do'
count as references.

`Inheritance:'

This field is not inherited by subtypes.
@end quotation

@ref{51e3,,PyObject.ob_type}

@quotation

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{b5e,,PyType_Ready()} checks if @ref{51e3,,ob_type} is @code{NULL}, and if so,
initializes it to the @code{ob_type} field of the base class.
@code{PyType_Ready()} will not change this field if it is non-zero.

`Inheritance:'

This field is inherited by subtypes.
@end quotation

@node PyVarObject Slots,PyTypeObject Slots,PyObject Slots,Type Object Structures
@anchor{c-api/typeobj pyvarobject-slots}@anchor{59dd}
@subsubsection PyVarObject Slots


@ref{545c,,PyVarObject.ob_size}

@quotation

For @ref{b5f,,statically allocated type objects}, this should be
initialized to zero. For @ref{d2f,,dynamically allocated type objects}, this field has a special internal meaning.

This field should be accessed using the @ref{b61,,Py_SIZE()} macro.

`Inheritance:'

This field is not inherited by subtypes.
@end quotation

@node PyTypeObject Slots,Static Types,PyVarObject Slots,Type Object Structures
@anchor{c-api/typeobj pytypeobject-slots}@anchor{59de}
@subsubsection PyTypeObject Slots


Each slot has a section describing inheritance.  If @ref{b5e,,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 @ref{529a,,PyBaseObject_Type}
and @ref{958,,PyType_Type} effectively act as defaults.)

@geindex PyTypeObject.tp_name (C member)
@anchor{c-api/typeobj c PyTypeObject tp_name}@anchor{1ea6}
@deffn {C Μέλος} const char *@ref{e6b,,PyTypeObject}.tp_name

See @ref{37c,,Py_tp_name} for the corresponding
@ref{5568,,Slot ID}.

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{1ea6,,tp_name} initializer @code{"P.Q.M.T"}.

For @ref{d2f,,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{b5f,,statically allocated type objects},
the `tp_name' field should contain a dot.
Everything before the last dot is made accessible as the @ref{80b,,__module__}
attribute, and everything after the last dot is made accessible as the
@ref{184d,,__name__} attribute.

If no dot is present, the entire @ref{1ea6,,tp_name} field is made accessible as the
@ref{184d,,__name__} attribute, and the @ref{80b,,__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{e6b,,PyTypeObject()} (other than potentially
@ref{25b0,,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{d4f}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} @ref{e6b,,PyTypeObject}.tp_basicsize
@anchor{c-api/typeobj c PyTypeObject tp_itemsize}@anchor{25b0}
@deffnx {C Μέλος} @ref{e24,,Py_ssize_t} @ref{e6b,,PyTypeObject}.tp_itemsize

These fields allow calculating the size in bytes of instances of the type.

See @ref{37d,,Py_tp_basicsize}, @ref{37e,,Py_tp_extra_basicsize} and
@ref{37f,,Py_tp_itemsize} for the corresponding
@ref{5568,,Slot IDs}.

There are two kinds of types: types with fixed-length instances have a zero
@code{tp_itemsize} field, types with variable-length instances have a non-zero
@code{tp_itemsize} field.  For a type with fixed-length instances, all
instances have the same size, given in @code{tp_basicsize}.
(Exceptions to this rule can be made using
@ref{1cab,,PyUnstable_Object_GC_NewWithExtraData()}.)

For a type with variable-length instances, the instances must have an
@ref{545c,,ob_size} field, and the instance size is
@code{tp_basicsize} plus N times @code{tp_itemsize},
where N is the «length» of the object.

Functions like @ref{d4e,,PyObject_NewVar()} will take the value of N as an
argument, and store in the instance’s @ref{545c,,ob_size} field.
Note that the @code{ob_size} field may later be used for
other purposes. For example, @ref{326,,int} instances use the bits of
@code{ob_size} in an implementation-defined
way; the underlying storage and its size should be accessed using
@ref{5d5,,PyLong_Export()}.

@cartouche
@quotation Σημείωση 
The @ref{545c,,ob_size} field should be accessed using
the @ref{b61,,Py_SIZE()} and @ref{b62,,Py_SET_SIZE()} macros.
@end quotation
@end cartouche

Also, the presence of an @ref{545c,,ob_size} field in the
instance layout doesn’t mean that the instance structure is variable-length.
For example, the @ref{4d9,,list} type has fixed-length instances, yet those
instances have a @code{ob_size} field.
(As with @ref{326,,int}, avoid reading lists” @code{ob_size} directly.
Call @ref{17bc,,PyList_Size()} instead.)

The @code{tp_basicsize} includes size needed for data of the type’s
@ref{2567,,tp_base}, plus any extra data needed
by each instance.

The  correct way to set @code{tp_basicsize} is to use the
@code{sizeof} operator on the struct used to declare the instance layout.
This struct must include the struct used to declare the base type.
In other words, @code{tp_basicsize} must be greater than or equal
to the base’s @code{tp_basicsize}.

Since every type is a subtype of @ref{e4d,,object}, this struct must
include @ref{19b,,PyObject} or @ref{492d,,PyVarObject} (depending on
whether @ref{545c,,ob_size} should be included). These are
usually defined by the macro @ref{1682,,PyObject_HEAD} or
@ref{597c,,PyObject_VAR_HEAD}, respectively.

The basic size does not include the GC header size, as that header is not
part of @ref{1682,,PyObject_HEAD}.

For cases where struct used to declare the base type is unknown,
see @ref{199,,PyType_Spec.basicsize} and @ref{391,,PyType_FromMetaclass()}.

Notes about alignment:


@itemize -

@item 
@code{tp_basicsize} must be a multiple of @code{_Alignof(PyObject)}.
When using @code{sizeof} on a @code{struct} that includes
@ref{1682,,PyObject_HEAD}, as recommended, the compiler ensures this.
When not using a C @code{struct}, or when using compiler
extensions like @code{__attribute__((packed))}, it is up to you.

@item 
If the variable items require a particular alignment,
@code{tp_basicsize} and @code{tp_itemsize} must each be a
multiple of that alignment.
For example, if a type’s variable part stores a @code{double}, it is
your responsibility that both fields are a multiple of
@code{_Alignof(double)}.
@end itemize

`Inheritance:'

These fields are inherited separately by subtypes.
(That is, if the field is set to zero, @ref{b5e,,PyType_Ready()} will copy
the value from the base type, indicating that the instances do not
need additional storage.)

If the base type has a non-zero @ref{25b0,,tp_itemsize}, it is generally not safe to set
@code{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{51d3}
@deffn {C Μέλος} @ref{54ec,,destructor} @ref{e6b,,PyTypeObject}.tp_dealloc

` The corresponding @ref{541b,,slot ID} @code{Py_tp_dealloc} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_dealloc (C macro)
@anchor{c-api/typeobj c Py_tp_dealloc}@anchor{54cf}

A pointer to the instance destructor function.  The function signature is:

@example
void tp_dealloc(PyObject *self);
@end example

The destructor function should remove all references which the instance owns
(e.g., call @ref{97c,,Py_CLEAR()}), free all memory buffers owned by the
instance, and call the type’s @ref{51e5,,tp_free} function to
free the object itself.

If you may call functions that may set the error indicator, you must use
@ref{63c,,PyErr_GetRaisedException()} and @ref{63f,,PyErr_SetRaisedException()}
to ensure you don’t clobber a preexisting error indicator (the deallocation
could have occurred while processing a different error):

@example
static void
foo_dealloc(foo_object *self)
@{
    PyObject *et, *ev, *etb;
    PyObject *exc = PyErr_GetRaisedException();
    ...
    PyErr_SetRaisedException(exc);
@}
@end example

The dealloc handler itself must not raise an exception; if it hits an error
case it should call @ref{7e7,,PyErr_FormatUnraisable()} to log (and clear) an
unraisable exception.

No guarantees are made about when an object is destroyed, except:


@itemize *

@item 
Python will destroy an object immediately or some time after the final
reference to the object is deleted, unless its finalizer
(@ref{e6c,,tp_finalize}) subsequently resurrects the
object.

@item 
An object will not be destroyed while it is being automatically finalized
(@ref{e6c,,tp_finalize}) or automatically cleared
(@ref{51f7,,tp_clear}).
@end itemize

CPython currently destroys an object immediately from @ref{975,,Py_DECREF()}
when the new reference count is zero, but this may change in a future
version.

It is recommended to call @ref{351,,PyObject_CallFinalizerFromDealloc()} at the
beginning of @code{tp_dealloc} to guarantee that the object is always
finalized before destruction.

If the type supports garbage collection (the @ref{39e,,Py_TPFLAGS_HAVE_GC}
flag is set), the destructor should call @ref{18a7,,PyObject_GC_UnTrack()}
before clearing any member fields.

It is permissible to call @ref{51f7,,tp_clear} from
@code{tp_dealloc} to reduce code duplication and to guarantee that the
object is always cleared before destruction.  Beware that
@code{tp_clear} might have already been called.

If the type is heap allocated (@ref{c82,,Py_TPFLAGS_HEAPTYPE}), the
deallocator should release the owned reference to its type object (via
@ref{975,,Py_DECREF()}) after calling the type deallocator.  See the example
code below.:

@example
static void
foo_dealloc(PyObject *op)
@{
   foo_object *self = (foo_object *) op;
   PyObject_GC_UnTrack(self);
   Py_CLEAR(self->ref);
   Py_TYPE(self)->tp_free(self);
@}
@end example

@code{tp_dealloc} must leave the exception status unchanged.  If it
needs to call something that might raise an exception, the exception state
must be backed up first and restored later (after logging any exceptions
with @ref{7e8,,PyErr_WriteUnraisable()}).

Example:

@example
static void
foo_dealloc(PyObject *self)
@{
    PyObject *exc = PyErr_GetRaisedException();

    if (PyObject_CallFinalizerFromDealloc(self) < 0) @{
        // self was resurrected.
        goto done;
    @}

    PyTypeObject *tp = Py_TYPE(self);

    if (tp->tp_flags & Py_TPFLAGS_HAVE_GC) @{
        PyObject_GC_UnTrack(self);
    @}

    // Optional, but convenient to avoid code duplication.
    if (tp->tp_clear && tp->tp_clear(self) < 0) @{
        PyErr_WriteUnraisable(self);
    @}

    // Any additional destruction goes here.

    tp->tp_free(self);
    self = NULL;  // In case PyErr_WriteUnraisable() is called below.

    if (tp->tp_flags & Py_TPFLAGS_HEAPTYPE) @{
        Py_CLEAR(tp);
    @}

done:
    // Optional, if something was called that might have raised an
    // exception.
    if (PyErr_Occurred()) @{
        PyErr_WriteUnraisable(self);
    @}
    PyErr_SetRaisedException(exc);
@}
@end example

@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
with an @ref{1a1,,attached thread state}.  However, if the object being
destroyed in turn destroys objects from some other 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.

`Inheritance:'

This field is inherited by subtypes.


@subsubheading Δείτε επίσης


@ref{596d,,Object Life Cycle} for details about how this slot relates to other slots.

@end deffn

@geindex PyTypeObject.tp_vectorcall_offset (C member)
@anchor{c-api/typeobj c PyTypeObject tp_vectorcall_offset}@anchor{55f8}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} @ref{e6b,,PyTypeObject}.tp_vectorcall_offset

An optional offset to a per-instance function that implements calling
the object using the @ref{95b,,vectorcall protocol},
a more efficient alternative
of the simpler @ref{962,,tp_call}.

This field is only used if the flag @ref{95d,,Py_TPFLAGS_HAVE_VECTORCALL}
is set. If so, this must be a positive integer containing the offset in the
instance of a @ref{960,,vectorcallfunc} pointer.

The `vectorcallfunc' pointer may be @code{NULL}, in which case the instance behaves
as if @ref{95d,,Py_TPFLAGS_HAVE_VECTORCALL} was not set: calling the instance
falls back to @ref{962,,tp_call}.

Any class that sets @code{Py_TPFLAGS_HAVE_VECTORCALL} must also set
@ref{962,,tp_call} and make sure its behaviour is consistent
with the `vectorcallfunc' function.
This can be done by setting `tp_call' to @ref{95f,,PyVectorcall_Call()}.


Άλλαξε στην έκδοση 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.



Άλλαξε στην έκδοση 3.12: Before version 3.12, it was not recommended for
@ref{d2f,,mutable heap types} to implement the vectorcall
protocol.
When a user sets @ref{961,,__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{95d,,Py_TPFLAGS_HAVE_VECTORCALL} flag.


`Inheritance:'

This field is always inherited.
However, the @ref{95d,,Py_TPFLAGS_HAVE_VECTORCALL} flag is not
always inherited. If it’s not set, then the subclass won’t use
@ref{95b,,vectorcall}, except when
@ref{95f,,PyVectorcall_Call()} is explicitly called.
@end deffn

@geindex PyTypeObject.tp_getattr (C member)
@anchor{c-api/typeobj c PyTypeObject tp_getattr}@anchor{5202}
@deffn {C Μέλος} @ref{54ed,,getattrfunc} @ref{e6b,,PyTypeObject}.tp_getattr

` The corresponding @ref{541b,,slot ID} @code{Py_tp_getattr} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_getattr (C macro)
@anchor{c-api/typeobj c Py_tp_getattr}@anchor{54d6}

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{1c6a,,tp_getattro} function, but taking a C string
instead of a Python string object to give the attribute name.

`Inheritance:'

Group: @ref{5202,,tp_getattr}, @ref{1c6a,,tp_getattro}

This field is inherited by subtypes together with @ref{1c6a,,tp_getattro}: a subtype
inherits both @ref{5202,,tp_getattr} and @code{tp_getattro} from its base type when
the subtype’s @code{tp_getattr} and @code{tp_getattro} are both @code{NULL}.
@end deffn

@geindex PyTypeObject.tp_setattr (C member)
@anchor{c-api/typeobj c PyTypeObject tp_setattr}@anchor{5203}
@deffn {C Μέλος} @ref{54fd,,setattrfunc} @ref{e6b,,PyTypeObject}.tp_setattr

` The corresponding @ref{541b,,slot ID} @code{Py_tp_setattr} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_setattr (C macro)
@anchor{c-api/typeobj c Py_tp_setattr}@anchor{54e3}

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{51fd,,tp_setattro} function, but taking a C string
instead of a Python string object to give the attribute name.

`Inheritance:'

Group: @ref{5203,,tp_setattr}, @ref{51fd,,tp_setattro}

This field is inherited by subtypes together with @ref{51fd,,tp_setattro}: a subtype
inherits both @ref{5203,,tp_setattr} and @code{tp_setattro} from its base type when
the subtype’s @code{tp_setattr} and @code{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{127d}
@deffn {C Μέλος} @ref{564a,,PyAsyncMethods} *@ref{e6b,,PyTypeObject}.tp_as_async

Pointer to an additional structure that contains fields relevant only to
objects which implement @ref{6cf,,awaitable} and @ref{6cd,,asynchronous iterator}
protocols at the C-level.  See @ref{59df,,Async Object Structures} for details.


Added in version 3.5: Formerly known as @code{tp_compare} and @code{tp_reserved}.


`Inheritance:'

The @ref{127d,,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{51f9}
@deffn {C Μέλος} @ref{54fb,,reprfunc} @ref{e6b,,PyTypeObject}.tp_repr

` The corresponding @ref{541b,,slot ID} @code{Py_tp_repr} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_repr (C macro)
@anchor{c-api/typeobj c Py_tp_repr}@anchor{54e1}

@geindex built-in function;repr

An optional pointer to a function that implements the built-in function
@ref{45b,,repr()}.

The signature is the same as for @ref{13d7,,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{184,,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{d53}
@deffn {C Μέλος} @ref{17c0,,PyNumberMethods} *@ref{e6b,,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{59e0,,Number Object Structures}.

`Inheritance:'

The @ref{d53,,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{59a2}
@deffn {C Μέλος} @ref{5209,,PySequenceMethods} *@ref{e6b,,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{59e1,,Sequence Object Structures}.

`Inheritance:'

The @ref{59a2,,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{59a3}
@deffn {C Μέλος} @ref{520a,,PyMappingMethods} *@ref{e6b,,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{59e2,,Mapping Object Structures}.

`Inheritance:'

The @ref{59a3,,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{520b}
@deffn {C Μέλος} @ref{54f2,,hashfunc} @ref{e6b,,PyTypeObject}.tp_hash

` The corresponding @ref{541b,,slot ID} @code{Py_tp_hash} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_hash (C macro)
@anchor{c-api/typeobj c Py_tp_hash}@anchor{54d9}

@geindex built-in function;hash

An optional pointer to a function that implements the built-in function
@ref{9e2,,hash()}.

The signature is the same as for @ref{649,,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{5205,,tp_richcompare} is not set),
an attempt to take the hash of the object raises @ref{291,,TypeError}.
This is the same as setting it to @ref{1769,,PyObject_HashNotImplemented()}.

This field can be set explicitly to @ref{1769,,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
@code{PyObject_HashNotImplemented()}.

`Inheritance:'

Group: @ref{520b,,tp_hash}, @ref{5205,,tp_richcompare}

This field is inherited by subtypes together with
@ref{5205,,tp_richcompare}: a subtype inherits both of
@code{tp_richcompare} and @ref{520b,,tp_hash}, when the subtype’s
@code{tp_richcompare} and @code{tp_hash} are both @code{NULL}.

`Default:'

@ref{529a,,PyBaseObject_Type} uses @ref{802,,PyObject_GenericHash()}.
@end deffn

@geindex PyTypeObject.tp_call (C member)
@anchor{c-api/typeobj c PyTypeObject tp_call}@anchor{962}
@deffn {C Μέλος} @ref{5502,,ternaryfunc} @ref{e6b,,PyTypeObject}.tp_call

` The corresponding @ref{541b,,slot ID} @code{Py_tp_call} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_call (C macro)
@anchor{c-api/typeobj c Py_tp_call}@anchor{54cd}

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{82f,,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{51fa}
@deffn {C Μέλος} @ref{54fb,,reprfunc} @ref{e6b,,PyTypeObject}.tp_str

` The corresponding @ref{541b,,slot ID} @code{Py_tp_str} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_str (C macro)
@anchor{c-api/typeobj c Py_tp_str}@anchor{54e5}

An optional pointer to a function that implements the built-in operation
@ref{1df,,str()}.  (Note that @ref{1df,,str} is a type now, and @code{str()} calls the
constructor for that type.  This constructor calls @ref{13d8,,PyObject_Str()} to do
the actual work, and @code{PyObject_Str()} will call this handler.)

The signature is the same as for @ref{13d8,,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{131f,,print()} function.

`Inheritance:'

This field is inherited by subtypes.

`Default:'

When this field is not set, @ref{13d7,,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{1c6a}
@deffn {C Μέλος} @ref{54ee,,getattrofunc} @ref{e6b,,PyTypeObject}.tp_getattro

` The corresponding @ref{541b,,slot ID} @code{Py_tp_getattro} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_getattro (C macro)
@anchor{c-api/typeobj c Py_tp_getattro}@anchor{54d7}

An optional pointer to the get-attribute function.

The signature is the same as for @ref{3b7,,PyObject_GetAttr()}:

@example
PyObject *tp_getattro(PyObject *self, PyObject *attr);
@end example

It is usually convenient to set this field to @ref{53c6,,PyObject_GenericGetAttr()},
which implements the normal way of looking for object attributes.

`Inheritance:'

Group: @ref{5202,,tp_getattr}, @ref{1c6a,,tp_getattro}

This field is inherited by subtypes together with @ref{5202,,tp_getattr}: a subtype
inherits both @code{tp_getattr} and @ref{1c6a,,tp_getattro} from its base type when
the subtype’s @code{tp_getattr} and @code{tp_getattro} are both @code{NULL}.

`Default:'

@ref{529a,,PyBaseObject_Type} uses @ref{53c6,,PyObject_GenericGetAttr()}.
@end deffn

@geindex PyTypeObject.tp_setattro (C member)
@anchor{c-api/typeobj c PyTypeObject tp_setattro}@anchor{51fd}
@deffn {C Μέλος} @ref{54fe,,setattrofunc} @ref{e6b,,PyTypeObject}.tp_setattro

` The corresponding @ref{541b,,slot ID} @code{Py_tp_setattro} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_setattro (C macro)
@anchor{c-api/typeobj c Py_tp_setattro}@anchor{54e4}

An optional pointer to the function for setting and deleting attributes.

The signature is the same as for @ref{1927,,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{53c7,,PyObject_GenericSetAttr()}, which implements the normal
way of setting object attributes.

`Inheritance:'

Group: @ref{5203,,tp_setattr}, @ref{51fd,,tp_setattro}

This field is inherited by subtypes together with @ref{5203,,tp_setattr}: a subtype
inherits both @code{tp_setattr} and @ref{51fd,,tp_setattro} from its base type when
the subtype’s @code{tp_setattr} and @code{tp_setattro} are both @code{NULL}.

`Default:'

@ref{529a,,PyBaseObject_Type} uses @ref{53c7,,PyObject_GenericSetAttr()}.
@end deffn

@geindex PyTypeObject.tp_as_buffer (C member)
@anchor{c-api/typeobj c PyTypeObject tp_as_buffer}@anchor{d51}
@deffn {C Μέλος} @ref{5651,,PyBufferProcs} *@ref{e6b,,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{561a,,Buffer Object Structures}.

`Inheritance:'

The @ref{d51,,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{1e68}
@deffn {C Μέλος} unsigned long @ref{e6b,,PyTypeObject}.tp_flags

See @ref{380,,Py_tp_flags} for the corresponding
@ref{5568,,Slot ID}.

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{d53,,tp_as_number}, @ref{59a2,,tp_as_sequence}, @ref{59a3,,tp_as_mapping}, and
@ref{d51,,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{39e,,Py_TPFLAGS_HAVE_GC} flag bit is inherited together with
the @ref{36b,,tp_traverse} and @ref{51f7,,tp_clear} fields, i.e. if the
@code{Py_TPFLAGS_HAVE_GC} flag bit is clear in the subtype and the
@code{tp_traverse} and @code{tp_clear} fields in the subtype exist and have
@code{NULL} values.

@c XXX are most flag bits *really* inherited individually?

`Default:'

@ref{529a,,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{1e68,,tp_flags} field.  The macro
@ref{1f30,,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{c82}
@deffn {C Μακροεντολή} Py_TPFLAGS_HEAPTYPE

This bit is set when the type object itself is allocated on the heap, for
example, types created dynamically using @ref{38e,,PyType_FromSpec()}.  In this
case, the @ref{51e3,,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{59e3,,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{51ea}
@deffn {C Μακροεντολή} Py_TPFLAGS_BASETYPE
` Μέρος του @ref{95c,,Σταθερό ABI}.'
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{59e4}
@deffn {C Μακροεντολή} Py_TPFLAGS_READY

This bit is set when the type object has been fully initialized by
@ref{b5e,,PyType_Ready()}.

`Inheritance:'

???
@end deffn

@geindex Py_TPFLAGS_READYING (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_READYING}@anchor{59e5}
@deffn {C Μακροεντολή} Py_TPFLAGS_READYING

This bit is set while @ref{b5e,,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{39e}
@deffn {C Μακροεντολή} Py_TPFLAGS_HAVE_GC
` Μέρος του @ref{95c,,Σταθερό ABI}.'
This bit is set when the object supports garbage collection.  If this bit
is set, memory for new instances (see @ref{51e6,,tp_alloc})
must be allocated using @ref{e68,,PyObject_GC_New} or
@ref{e30,,PyType_GenericAlloc()} and deallocated (see
@ref{51e5,,tp_free}) using @ref{18a5,,PyObject_GC_Del()}.  More
information in section @ref{59e3,,Supporting Cyclic Garbage Collection}.

`Inheritance:'

Group: @ref{39e,,Py_TPFLAGS_HAVE_GC}, @ref{36b,,tp_traverse}, @ref{51f7,,tp_clear}

The @ref{39e,,Py_TPFLAGS_HAVE_GC} flag bit is inherited
together with the @ref{36b,,tp_traverse} and @ref{51f7,,tp_clear}
fields, i.e.  if the @code{Py_TPFLAGS_HAVE_GC} flag bit is
clear in the subtype and the @code{tp_traverse} and
@code{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{51e0}
@deffn {C Μακροεντολή} Py_TPFLAGS_DEFAULT
` Μέρος του @ref{95c,,Σταθερό ABI}.'
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: @ref{59e6,,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{547c}
@deffn {C Μακροεντολή} Py_TPFLAGS_METHOD_DESCRIPTOR
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.8.'
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}.


Added in version 3.8.


`Inheritance:'

This flag is never inherited by types without the
@ref{5fb,,Py_TPFLAGS_IMMUTABLETYPE} flag set.  For extension types, it is
inherited whenever @ref{57d6,,tp_descr_get} is inherited.
@end deffn

@geindex Py_TPFLAGS_MANAGED_DICT (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_MANAGED_DICT}@anchor{39c}
@deffn {C Μακροεντολή} Py_TPFLAGS_MANAGED_DICT

This bit indicates that instances of the class have a @ref{1bf,,__dict__}
attribute, and that the space for the dictionary is managed by the VM.

If this flag is set, @ref{39e,,Py_TPFLAGS_HAVE_GC} must also be set.

The type traverse function must call @ref{803,,PyObject_VisitManagedDict()}
and its clear function must call @ref{804,,PyObject_ClearManagedDict()}.


Added in version 3.12.


`Inheritance:'

This flag is inherited unless the
@ref{564c,,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{39d}
@deffn {C Μακροεντολή} Py_TPFLAGS_MANAGED_WEAKREF

This bit indicates that instances of the class should be weakly
referenceable.

If this flag is set, @ref{39e,,Py_TPFLAGS_HAVE_GC} must also be set.


Added in version 3.12.


`Inheritance:'

This flag is inherited unless the
@ref{d50,,tp_weaklistoffset} field is set in a superclass.
@end deffn

@geindex Py_TPFLAGS_PREHEADER (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_PREHEADER}@anchor{59e7}
@deffn {C Μακροεντολή} Py_TPFLAGS_PREHEADER

These bits indicate that the VM will manage some fields by storing them
before the object. Currently, this macro is equivalent to
@ref{39c,,Py_TPFLAGS_MANAGED_DICT} | @ref{39d,,Py_TPFLAGS_MANAGED_WEAKREF}.

This macro value relies on the implementation of the VM, so its value is not
stable and may change in a future version. Prefer using individual
flags instead.


Added in version 3.12.

@end deffn

@geindex Py_TPFLAGS_ITEMS_AT_END (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_ITEMS_AT_END}@anchor{956}
@deffn {C Μακροεντολή} Py_TPFLAGS_ITEMS_AT_END
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
Only usable with variable-size types, i.e. ones with non-zero
@ref{25b0,,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.


Added in 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{5641}
@deffn {C Μακροεντολή} Py_TPFLAGS_LONG_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_LIST_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_LIST_SUBCLASS}@anchor{59e8}
@deffn {C Μακροεντολή} Py_TPFLAGS_LIST_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_TUPLE_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_TUPLE_SUBCLASS}@anchor{59e9}
@deffn {C Μακροεντολή} Py_TPFLAGS_TUPLE_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_BYTES_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_BYTES_SUBCLASS}@anchor{59ea}
@deffn {C Μακροεντολή} Py_TPFLAGS_BYTES_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_UNICODE_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_UNICODE_SUBCLASS}@anchor{59eb}
@deffn {C Μακροεντολή} Py_TPFLAGS_UNICODE_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_DICT_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_DICT_SUBCLASS}@anchor{59ec}
@deffn {C Μακροεντολή} 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{59ed}
@deffn {C Μακροεντολή} Py_TPFLAGS_BASE_EXC_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_TYPE_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_TYPE_SUBCLASS}@anchor{59ee}
@deffn {C Μακροεντολή} Py_TPFLAGS_TYPE_SUBCLASS

Functions such as @ref{5661,,PyLong_Check()} will call @ref{5640,,PyType_FastSubclass()}
with one of these flags 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{1257,,PyObject_IsInstance()}. Custom types that inherit
from built-ins should have their @ref{1e68,,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{63a}
@deffn {C Μακροεντολή} Py_TPFLAGS_HAVE_FINALIZE

This bit is set when the @ref{e6c,,tp_finalize} slot is present in the
type structure.


Added in version 3.4.



Αποσύρθηκε στην έκδοση 3.8: This flag isn’t necessary anymore, as the interpreter assumes the
@ref{e6c,,tp_finalize} slot is always present in the
type structure.

@end deffn

@geindex _Py_TPFLAGS_HAVE_VECTORCALL (C macro)

@geindex Py_TPFLAGS_HAVE_VECTORCALL (C macro)
@anchor{c-api/typeobj c _Py_TPFLAGS_HAVE_VECTORCALL}@anchor{59ef}@anchor{c-api/typeobj c Py_TPFLAGS_HAVE_VECTORCALL}@anchor{95d}
@deffn {C Μακροεντολή} Py_TPFLAGS_HAVE_VECTORCALL
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
This bit is set when the class implements
the @ref{95b,,vectorcall protocol}.
See @ref{55f8,,tp_vectorcall_offset} for details.

`Inheritance:'

This bit is inherited if @ref{962,,tp_call} is also
inherited.


Added in version 3.8: as @code{_Py_TPFLAGS_HAVE_VECTORCALL}



Άλλαξε στην έκδοση 3.9: Renamed to the current name, without the leading underscore.
The old provisional name is @ref{1a7,,soft deprecated}.



Άλλαξε στην έκδοση 3.12: This flag is now removed from a class when the class’s
@ref{961,,__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{5fb}
@deffn {C Μακροεντολή} Py_TPFLAGS_IMMUTABLETYPE

This bit is set for type objects that are immutable: type attributes cannot be set nor deleted.

@ref{b5e,,PyType_Ready()} automatically applies this flag to
@ref{b5f,,static types}.

`Inheritance:'

This flag is not inherited.


Added in version 3.10.

@end deffn

@geindex Py_TPFLAGS_DISALLOW_INSTANTIATION (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_DISALLOW_INSTANTIATION}@anchor{984}
@deffn {C Μακροεντολή} Py_TPFLAGS_DISALLOW_INSTANTIATION

Disallow creating instances of the type: set
@ref{981,,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{b5e,,PyType_Ready()} is called on the type.

The flag is set automatically on @ref{b5f,,static types} if
@ref{2567,,tp_base} is NULL or @code{&PyBaseObject_Type} and
@ref{981,,tp_new} is NULL.

`Inheritance:'

This flag is not inherited.
However, subclasses will not be instantiable unless they provide a
non-NULL @ref{981,,tp_new} (which is only possible
via the C API).

@cartouche
@quotation Σημείωση 
To disallow instantiating a class directly but allow instantiating
its subclasses (e.g. for an @ref{155f,,abstract base class}),
do not use this flag.
Instead, make @ref{981,,tp_new} only succeed for
subclasses.
@end quotation
@end cartouche


Added in version 3.10.

@end deffn

@geindex Py_TPFLAGS_MAPPING (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_MAPPING}@anchor{1e4f}
@deffn {C Μακροεντολή} Py_TPFLAGS_MAPPING

This bit indicates that instances of the class may match mapping patterns
when used as the subject of a @ref{1d4,,match} block. It is automatically
set when registering or subclassing @ref{c9c,,collections.abc.Mapping}, and
unset when registering @ref{156d,,collections.abc.Sequence}.

@cartouche
@quotation Σημείωση 
@ref{1e4f,,Py_TPFLAGS_MAPPING} and @ref{1e50,,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{1e50,,Py_TPFLAGS_SEQUENCE}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/} – Structural Pattern Matching: Specification



Added in version 3.10.

@end deffn

@geindex Py_TPFLAGS_SEQUENCE (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_SEQUENCE}@anchor{1e50}
@deffn {C Μακροεντολή} Py_TPFLAGS_SEQUENCE

This bit indicates that instances of the class may match sequence patterns
when used as the subject of a @ref{1d4,,match} block. It is automatically
set when registering or subclassing @ref{156d,,collections.abc.Sequence}, and
unset when registering @ref{c9c,,collections.abc.Mapping}.

@cartouche
@quotation Σημείωση 
@ref{1e4f,,Py_TPFLAGS_MAPPING} and @ref{1e50,,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{1e4f,,Py_TPFLAGS_MAPPING}.


@subsubheading Δείτε επίσης


@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/} – Structural Pattern Matching: Specification



Added in version 3.10.

@end deffn

@geindex Py_TPFLAGS_VALID_VERSION_TAG (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_VALID_VERSION_TAG}@anchor{59f0}
@deffn {C Μακροεντολή} Py_TPFLAGS_VALID_VERSION_TAG

Internal. Do not set or unset this flag.
To indicate that a class has changed call @ref{1d77,,PyType_Modified()}

@cartouche
@quotation Προειδοποίηση 
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

@geindex Py_TPFLAGS_HAVE_VERSION_TAG (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_HAVE_VERSION_TAG}@anchor{176d}
@deffn {C Μακροεντολή} Py_TPFLAGS_HAVE_VERSION_TAG

This macro does nothing.
Historically, this would indicate that the
@ref{59a7,,tp_version_tag} field was available and
initialized.


@ref{1a7,,Soft deprecated} since version 3.13.

@end deffn

@geindex Py_TPFLAGS_INLINE_VALUES (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_INLINE_VALUES}@anchor{59f1}
@deffn {C Μακροεντολή} Py_TPFLAGS_INLINE_VALUES

This bit indicates that instances of this type will have an «inline values»
array (containing the object’s attributes) placed directly after the end
of the object.

This requires that @ref{39e,,Py_TPFLAGS_HAVE_GC} is set.

`Inheritance:'

This flag is not inherited.


Added in version 3.13.

@end deffn

@geindex Py_TPFLAGS_IS_ABSTRACT (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_IS_ABSTRACT}@anchor{59f2}
@deffn {C Μακροεντολή} Py_TPFLAGS_IS_ABSTRACT

This bit indicates that this is an abstract type and therefore cannot
be instantiated.

`Inheritance:'

This flag is not inherited.


@subsubheading Δείτε επίσης


@ref{4,,abc}

@end deffn

@geindex Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_HAVE_STACKLESS_EXTENSION}@anchor{59e6}
@deffn {C Μακροεντολή} Py_TPFLAGS_HAVE_STACKLESS_EXTENSION

Internal. Do not set or unset this flag.
Historically, this was a reserved flag for use in Stackless Python.

@cartouche
@quotation Προειδοποίηση 
This flag is present in header files, but is not be used.
This may 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{51e1}
@deffn {C Μέλος} const char *@ref{e6b,,PyTypeObject}.tp_doc

` The corresponding @ref{541b,,slot ID} @code{Py_tp_doc} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_doc (C macro)
@anchor{c-api/typeobj c Py_tp_doc}@anchor{54d3}

An optional pointer to a NUL-terminated C string giving the docstring for this
type object.  This is exposed as the @ref{2284,,__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{36b}
@deffn {C Μέλος} @ref{5503,,traverseproc} @ref{e6b,,PyTypeObject}.tp_traverse

` The corresponding @ref{541b,,slot ID} @code{Py_tp_traverse} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_traverse (C macro)
@anchor{c-api/typeobj c Py_tp_traverse}@anchor{54e6}

An optional pointer to a traversal function for the garbage collector.  This is
only used if the @ref{39e,,Py_TPFLAGS_HAVE_GC} flag bit is set.

See @ref{59f3,,Traversal} for documentation.

`Inheritance:'

Group: @ref{39e,,Py_TPFLAGS_HAVE_GC}, @ref{36b,,tp_traverse}, @ref{51f7,,tp_clear}

This field is inherited by subtypes together with @ref{51f7,,tp_clear} and the
@ref{39e,,Py_TPFLAGS_HAVE_GC} flag bit: the flag bit, @ref{36b,,tp_traverse}, and
@code{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{51f7}
@deffn {C Μέλος} @ref{54f4,,inquiry} @ref{e6b,,PyTypeObject}.tp_clear

` The corresponding @ref{541b,,slot ID} @code{Py_tp_clear} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_clear (C macro)
@anchor{c-api/typeobj c Py_tp_clear}@anchor{54ce}

An optional pointer to a clear function.  The signature is:

@example
int tp_clear(PyObject *);
@end example

The purpose of this function is to break reference cycles that are causing a
@ref{5971,,cyclic isolate} so that the objects can be safely destroyed.  A
cleared object is a partially destroyed object; the object is not obligated
to satisfy design invariants held during normal use.

@code{tp_clear} does not need to delete references to objects that
can’t participate in reference cycles, such as Python strings or Python
integers.  However, it may be convenient to clear all references, and write
the type’s @ref{51d3,,tp_dealloc} function to invoke
@code{tp_clear} to avoid code duplication.  (Beware that
@code{tp_clear} might have already been called. Prefer calling
idempotent functions like @ref{97c,,Py_CLEAR()}.)

Any non-trivial cleanup should be performed in
@ref{e6c,,tp_finalize} instead of @code{tp_clear}.

@cartouche
@quotation Σημείωση 
If @code{tp_clear} fails to break a reference cycle then the
objects in the @ref{5971,,cyclic isolate} may remain indefinitely
uncollectable («leak»).  See @ref{156a,,gc.garbage}.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
Referents (direct and indirect) might have already been cleared; they are
not guaranteed to be in a consistent state.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
The @ref{51f7,,tp_clear} function can be called from any
thread.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
An object is not guaranteed to be automatically cleared before its
destructor (@ref{51d3,,tp_dealloc}) is called.
@end quotation
@end cartouche

This function differs from the destructor
(@ref{51d3,,tp_dealloc}) in the following ways:


@itemize *

@item 
The purpose of clearing an object is to remove references to other objects
that might participate in a reference cycle.  The purpose of the
destructor, on the other hand, is a superset: it must release `all'
resources it owns, including references to objects that cannot participate
in a reference cycle (e.g., integers) as well as the object’s own memory
(by calling @ref{51e5,,tp_free}).

@item 
When @code{tp_clear} is called, other objects might still hold
references to the object being cleared.  Because of this,
@code{tp_clear} must not deallocate the object’s own memory
(@ref{51e5,,tp_free}).  The destructor, on the other hand,
is only called when no (strong) references exist, and as such, must
safely destroy the object itself by deallocating it.

@item 
@code{tp_clear} might never be automatically called.  An object’s
destructor, on the other hand, will be automatically called some time
after the object becomes unreachable (i.e., either there are no references
to the object or the object is a member of a @ref{5971,,cyclic isolate}).
@end itemize

No guarantees are made about when, if, or how often Python automatically
clears an object, except:


@itemize *

@item 
Python will not automatically clear an object if it is reachable, i.e.,
there is a reference to it and it is not a member of a @ref{5971,,cyclic isolate}.

@item 
Python will not automatically clear an object if it has not been
automatically finalized (see @ref{e6c,,tp_finalize}).  (If
the finalizer resurrected the object, the object may or may not be
automatically finalized again before it is cleared.)

@item 
If an object is a member of a @ref{5971,,cyclic isolate}, Python will not
automatically clear it if any member of the cyclic isolate has not yet
been automatically finalized (@ref{e6c,,tp_finalize}).

@item 
Python will not destroy an object until after any automatic calls to its
@code{tp_clear} function have returned.  This ensures that the act
of breaking a reference cycle does not invalidate the @code{self} pointer
while @code{tp_clear} is still executing.

@item 
Python will not automatically call @code{tp_clear} multiple times
concurrently.
@end itemize

CPython currently only automatically clears objects as needed to break
reference cycles in a @ref{5971,,cyclic isolate}, but future versions might
clear objects regularly before their destruction.

Taken together, all @ref{51f7,,tp_clear} functions in the
system must combine to break all reference cycles.  This is subtle, and if
in any doubt supply a @code{tp_clear} function.  For
example, the tuple type does not implement a
@code{tp_clear} function, because it’s possible to prove
that no reference cycle can be composed entirely of tuples.  Therefore the
@code{tp_clear} functions of other types are responsible
for breaking any cycle containing a tuple.  This isn’t immediately obvious,
and there’s rarely a good reason to avoid implementing
@code{tp_clear}.

Implementations of @ref{51f7,,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(PyObject *op)
@{
    localobject *self = (localobject *) op;
    Py_CLEAR(self->key);
    Py_CLEAR(self->args);
    Py_CLEAR(self->kw);
    Py_CLEAR(self->dict);
    return 0;
@}
@end example

The @ref{97c,,Py_CLEAR()} macro should be used, because clearing references is
delicate:  the reference to the contained object must not be released
(via @ref{975,,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
@code{Py_CLEAR()} macro performs the operations in a safe order.

If the @ref{39c,,Py_TPFLAGS_MANAGED_DICT} bit is set in the
@ref{1e68,,tp_flags} field, the clear function must call
@ref{804,,PyObject_ClearManagedDict()} like this:

@example
PyObject_ClearManagedDict((PyObject*)self);
@end example

More information about Python’s garbage collection scheme can be found in
section @ref{59e3,,Supporting Cyclic Garbage Collection}.

`Inheritance:'

Group: @ref{39e,,Py_TPFLAGS_HAVE_GC}, @ref{36b,,tp_traverse}, @ref{51f7,,tp_clear}

This field is inherited by subtypes together with @ref{36b,,tp_traverse} and the
@ref{39e,,Py_TPFLAGS_HAVE_GC} flag bit: the flag bit, @code{tp_traverse}, and
@ref{51f7,,tp_clear} are all inherited from the base type if they are all zero in
the subtype.


@subsubheading Δείτε επίσης


@ref{596d,,Object Life Cycle} for details about how this slot relates to other slots.

@end deffn

@geindex PyTypeObject.tp_richcompare (C member)
@anchor{c-api/typeobj c PyTypeObject tp_richcompare}@anchor{5205}
@deffn {C Μέλος} @ref{54fc,,richcmpfunc} @ref{e6b,,PyTypeObject}.tp_richcompare

` The corresponding @ref{541b,,slot ID} @code{Py_tp_richcompare} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_richcompare (C macro)
@anchor{c-api/typeobj c Py_tp_richcompare}@anchor{54e2}

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{e6b,,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{5205,,tp_richcompare} and for @ref{5206,,PyObject_RichCompare()}:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

Constant

@tab

Comparison

@item

@geindex Py_LT (C macro)
@anchor{c-api/typeobj c Py_LT}@anchor{55eb}
@deffn {C Μακροεντολή} Py_LT
@end deffn

@tab

@code{<}

@item

@geindex Py_LE (C macro)
@anchor{c-api/typeobj c Py_LE}@anchor{55ec}
@deffn {C Μακροεντολή} Py_LE
@end deffn

@tab

@code{<=}

@item

@geindex Py_EQ (C macro)
@anchor{c-api/typeobj c Py_EQ}@anchor{55ed}
@deffn {C Μακροεντολή} Py_EQ
@end deffn

@tab

@code{==}

@item

@geindex Py_NE (C macro)
@anchor{c-api/typeobj c Py_NE}@anchor{55ee}
@deffn {C Μακροεντολή} Py_NE
@end deffn

@tab

@code{!=}

@item

@geindex Py_GT (C macro)
@anchor{c-api/typeobj c Py_GT}@anchor{55ef}
@deffn {C Μακροεντολή} Py_GT
@end deffn

@tab

@code{>}

@item

@geindex Py_GE (C macro)
@anchor{c-api/typeobj c Py_GE}@anchor{55f0}
@deffn {C Μακροεντολή} 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{f72}
@deffn {C Μακροεντολή} 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{5206,,PyObject_RichCompare()}.

The returned value is a new @ref{7da,,strong reference}.

On error, sets an exception and returns @code{NULL} from the function.


Added in version 3.7.

@end deffn

`Inheritance:'

Group: @ref{520b,,tp_hash}, @ref{5205,,tp_richcompare}

This field is inherited by subtypes together with @ref{520b,,tp_hash}:
a subtype inherits @ref{5205,,tp_richcompare} and @code{tp_hash} when
the subtype’s @code{tp_richcompare} and @code{tp_hash} are both
@code{NULL}.

`Default:'

@ref{529a,,PyBaseObject_Type} provides a @ref{5205,,tp_richcompare}
implementation, which may be inherited.  However, if only
@ref{520b,,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{d50}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} @ref{e6b,,PyTypeObject}.tp_weaklistoffset

While this field is still supported, @ref{39d,,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{97a,,PyObject_ClearWeakRefs()} and the @code{PyWeakref_*} functions.  The
instance structure needs to include a field of type @ref{19b,,PyObject}* which is
initialized to @code{NULL}.

Do not confuse this field with @ref{5650,,tp_weaklist}; that is the list head for
weak references to the type object itself.

It is an error to set both the @ref{39d,,Py_TPFLAGS_MANAGED_WEAKREF} bit and
@ref{d50,,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{d50,,tp_weaklistoffset}, this should not be a problem.

`Default:'

If the @ref{39d,,Py_TPFLAGS_MANAGED_WEAKREF} bit is set in the
@ref{1e68,,tp_flags} field, then
@ref{d50,,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{1891}
@deffn {C Μέλος} @ref{54f0,,getiterfunc} @ref{e6b,,PyTypeObject}.tp_iter

` The corresponding @ref{541b,,slot ID} @code{Py_tp_iter} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_iter (C macro)
@anchor{c-api/typeobj c Py_tp_iter}@anchor{54dc}

An optional pointer to a function that returns an @ref{6ce,,iterator} for the
object.  Its presence normally signals that the instances of this type are
@ref{15ce,,iterable} (although sequences may be iterable without this function).

This function has the same signature as @ref{53ca,,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{1892}
@deffn {C Μέλος} @ref{54f5,,iternextfunc} @ref{e6b,,PyTypeObject}.tp_iternext

` The corresponding @ref{541b,,slot ID} @code{Py_tp_iternext} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_iternext (C macro)
@anchor{c-api/typeobj c Py_tp_iternext}@anchor{54dd}

An optional pointer to a function that returns the next item in an
@ref{6ce,,iterator}. The signature is:

@example
PyObject *tp_iternext(PyObject *self);
@end example

When the iterator is exhausted, it must return @code{NULL}; a @ref{fba,,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{1891,,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{5c6,,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{51e9}
@deffn {C Μέλος} struct @ref{1879,,PyMethodDef} *@ref{e6b,,PyTypeObject}.tp_methods

` The corresponding @ref{541b,,slot ID} @code{Py_tp_methods} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_methods (C macro)
@anchor{c-api/typeobj c Py_tp_methods}@anchor{54df}

An optional pointer to a static @code{NULL}-terminated array of @ref{1879,,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{1c92,,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{51e7}
@deffn {C Μέλος} struct @ref{95a,,PyMemberDef} *@ref{e6b,,PyTypeObject}.tp_members

` The corresponding @ref{541b,,slot ID} @code{Py_tp_members} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_members (C macro)
@anchor{c-api/typeobj c Py_tp_members}@anchor{54de}

An optional pointer to a static @code{NULL}-terminated array of @ref{95a,,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{1c92,,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{51ec}
@deffn {C Μέλος} struct @ref{f77,,PyGetSetDef} *@ref{e6b,,PyTypeObject}.tp_getset

` The corresponding @ref{541b,,slot ID} @code{Py_tp_getset} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_getset (C macro)
@anchor{c-api/typeobj c Py_tp_getset}@anchor{54d8}

An optional pointer to a static @code{NULL}-terminated array of @ref{f77,,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{1c92,,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{2567}
@deffn {C Μέλος} @ref{e6b,,PyTypeObject} *@ref{e6b,,PyTypeObject}.tp_base

` The corresponding @ref{541b,,slot ID} @code{Py_tp_base} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_base (C macro)
@anchor{c-api/typeobj c Py_tp_base}@anchor{54cb}

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 Σημείωση 
@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{51e2,,PyType_GenericNew()}, with implicit conversion
to a pointer, are valid C99 address constants.

However, the unary “&” operator applied to a non-static variable
like @ref{529a,,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{2567,,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{e4d,,object}).
@end deffn

@geindex PyTypeObject.tp_dict (C member)
@anchor{c-api/typeobj c PyTypeObject tp_dict}@anchor{1c92}
@deffn {C Μέλος} @ref{19b,,PyObject} *@ref{e6b,,PyTypeObject}.tp_dict

The type’s dictionary is stored here by @ref{b5e,,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{b5e,,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{25d2,,__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{1c91,,PyType_GetDict()} to retrieve the dictionary for an arbitrary
type.


Άλλαξε στην έκδοση 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{1c91,,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{b5e,,PyType_Ready()} will assign a new
dictionary to it.

@cartouche
@quotation Προειδοποίηση 
It is not safe to use @ref{51d0,,PyDict_SetItem()} on or otherwise modify
@ref{1c92,,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{57d6}
@deffn {C Μέλος} @ref{54ea,,descrgetfunc} @ref{e6b,,PyTypeObject}.tp_descr_get

` The corresponding @ref{541b,,slot ID} @code{Py_tp_descr_get} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_descr_get (C macro)
@anchor{c-api/typeobj c Py_tp_descr_get}@anchor{54d1}

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{1eaa}
@deffn {C Μέλος} @ref{54eb,,descrsetfunc} @ref{e6b,,PyTypeObject}.tp_descr_set

` The corresponding @ref{541b,,slot ID} @code{Py_tp_descr_set} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_descr_set (C macro)
@anchor{c-api/typeobj c Py_tp_descr_set}@anchor{54d2}

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{564c}
@deffn {C Μέλος} @ref{e24,,Py_ssize_t} @ref{e6b,,PyTypeObject}.tp_dictoffset

While this field is still supported, @ref{39c,,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{53c6,,PyObject_GenericGetAttr()}.

Do not confuse this field with @ref{1c92,,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{564c,,tp_dictoffset} should be regarded as write-only.
To get the pointer to the dictionary call @ref{1efa,,PyObject_GenericGetDict()}.
Calling @code{PyObject_GenericGetDict()} may need to allocate memory for the
dictionary, so it is may be more efficient to call @ref{3b7,,PyObject_GetAttr()}
when accessing an attribute on the object.

It is an error to set both the @ref{39c,,Py_TPFLAGS_MANAGED_DICT} bit and
@ref{564c,,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{39c,,Py_TPFLAGS_MANAGED_DICT}.

`Default:'

This slot has no default.  For @ref{b5f,,static types}, if the
field is @code{NULL} then no @ref{1bf,,__dict__} gets created for instances.

If the @ref{39c,,Py_TPFLAGS_MANAGED_DICT} bit is set in the
@ref{1e68,,tp_flags} field, then
@ref{564c,,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{983}
@deffn {C Μέλος} @ref{54f3,,initproc} @ref{e6b,,PyTypeObject}.tp_init

` The corresponding @ref{541b,,slot ID} @code{Py_tp_init} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_init (C macro)
@anchor{c-api/typeobj c Py_tp_init}@anchor{54da}

An optional pointer to an instance initialization function.

This function corresponds to the @ref{2fa,,__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{2fa,,__init__()}.

The @ref{983,,tp_init} function, if not @code{NULL}, is called when an instance is
created normally by calling its type, after the type’s @ref{981,,tp_new} function
has returned an instance of the type.  If the @code{tp_new} function returns an
instance of some other type that is not a subtype of the original type, no
@code{tp_init} function is called; if @code{tp_new} returns an instance of a
subtype of the original type, the subtype’s @code{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{b5f,,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{51e6}
@deffn {C Μέλος} @ref{54e8,,allocfunc} @ref{e6b,,PyTypeObject}.tp_alloc

` The corresponding @ref{541b,,slot ID} @code{Py_tp_alloc} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_alloc (C macro)
@anchor{c-api/typeobj c Py_tp_alloc}@anchor{54ca}

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:'

Static subtypes inherit this slot, which will be
@ref{e30,,PyType_GenericAlloc()} if inherited from @ref{e4d,,object}.

@ref{d2f,,Heap subtypes} do not inherit this slot.

`Default:'

For heap subtypes, this field is always set to
@ref{e30,,PyType_GenericAlloc()}.

For static subtypes, this slot is inherited (see above).
@end deffn

@geindex PyTypeObject.tp_new (C member)
@anchor{c-api/typeobj c PyTypeObject tp_new}@anchor{981}
@deffn {C Μέλος} @ref{54f7,,newfunc} @ref{e6b,,PyTypeObject}.tp_new

` The corresponding @ref{541b,,slot ID} @code{Py_tp_new} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_new (C macro)
@anchor{c-api/typeobj c Py_tp_new}@anchor{54e0}

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{981,,tp_new}
function is called; it may be a subtype of that type (but not an unrelated
type).

The @ref{981,,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{983,,tp_init} handler.  A good
rule of thumb is that for immutable types, all initialization should take place
in @code{tp_new}, while for mutable types, most initialization should be
deferred to @code{tp_init}.

Set the @ref{984,,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{b5f,,static types} whose @ref{2567,,tp_base}
is @code{NULL} or @code{&PyBaseObject_Type}.

`Default:'

For @ref{b5f,,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{51e5}
@deffn {C Μέλος} @ref{57bd,,freefunc} @ref{e6b,,PyTypeObject}.tp_free

` The corresponding @ref{541b,,slot ID} @code{Py_tp_free} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_free (C macro)
@anchor{c-api/typeobj c Py_tp_free}@anchor{54d5}

An optional pointer to an instance deallocation function.  Its signature is:

@example
void tp_free(void *self);
@end example

This function must free the memory allocated by
@ref{51e6,,tp_alloc}.

`Inheritance:'

Static subtypes inherit this slot, which will be @ref{1023,,PyObject_Free()} if
inherited from @ref{e4d,,object}.  Exception: If the type supports garbage
collection (i.e., the @ref{39e,,Py_TPFLAGS_HAVE_GC} flag is set in
@ref{1e68,,tp_flags}) and it would inherit
@code{PyObject_Free()}, then this slot is not inherited but instead defaults
to @ref{18a5,,PyObject_GC_Del()}.

@ref{d2f,,Heap subtypes} do not inherit this slot.

`Default:'

For @ref{d2f,,heap subtypes}, this slot defaults to a deallocator suitable to match
@ref{e30,,PyType_GenericAlloc()} and the value of the
@ref{39e,,Py_TPFLAGS_HAVE_GC} flag.

For static subtypes, this slot is inherited (see above).
@end deffn

@geindex PyTypeObject.tp_is_gc (C member)
@anchor{c-api/typeobj c PyTypeObject tp_is_gc}@anchor{59a4}
@deffn {C Μέλος} @ref{54f4,,inquiry} @ref{e6b,,PyTypeObject}.tp_is_gc

` The corresponding @ref{541b,,slot ID} @code{Py_tp_is_gc} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_is_gc (C macro)
@anchor{c-api/typeobj c Py_tp_is_gc}@anchor{54db}

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{1e68,,tp_flags} field, and check the @ref{39e,,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{958,,PyType_Type}, defines this function to distinguish between statically
and @ref{d2f,,dynamically allocated types}.)

`Inheritance:'

This field is inherited by subtypes.

`Default:'

This slot has no default.  If this field is @code{NULL},
@ref{39e,,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{59a5}
@deffn {C Μέλος} @ref{19b,,PyObject} *@ref{e6b,,PyTypeObject}.tp_bases

` The corresponding @ref{541b,,slot ID} @code{Py_tp_bases} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_bases (C macro)
@anchor{c-api/typeobj c Py_tp_bases}@anchor{54cc}

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{b5e,,initialized}.

For dynamically created classes, the @ref{54cc,,Py_tp_bases}
@ref{541b,,slot} can be used instead of the `bases' argument
of @ref{38f,,PyType_FromSpecWithBases()}.
The argument form is preferred.

@cartouche
@quotation Προειδοποίηση 
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{564e}
@deffn {C Μέλος} @ref{19b,,PyObject} *@ref{e6b,,PyTypeObject}.tp_mro

Tuple containing the expanded set of base types, starting with the type itself
and ending with @ref{e4d,,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{b5e,,initialized}.

`Inheritance:'

This field is not inherited; it is calculated fresh by
@ref{b5e,,PyType_Ready()}.
@end deffn

@geindex PyTypeObject.tp_cache (C member)
@anchor{c-api/typeobj c PyTypeObject tp_cache}@anchor{564f}
@deffn {C Μέλος} @ref{19b,,PyObject} *@ref{e6b,,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{977}
@deffn {C Μέλος} void *@ref{e6b,,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{978,,__subclasses__()}.


Άλλαξε στην έκδοση 3.12: For some types, this field does not hold a valid @ref{19b,,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{5650}
@deffn {C Μέλος} @ref{19b,,PyObject} *@ref{e6b,,PyTypeObject}.tp_weaklist

Weak reference list head, for weak references to this type object.  Not
inherited.  Internal use only.


Άλλαξε στην έκδοση 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{59a6}
@deffn {C Μέλος} @ref{54ec,,destructor} @ref{e6b,,PyTypeObject}.tp_del

` The corresponding @ref{541b,,slot ID} @code{Py_tp_del} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_tp_del (C macro)
@anchor{c-api/typeobj c Py_tp_del}@anchor{54d0}

This field is deprecated.  Use @ref{e6c,,tp_finalize} instead.
@end deffn

@geindex PyTypeObject.tp_version_tag (C member)
@anchor{c-api/typeobj c PyTypeObject tp_version_tag}@anchor{59a7}
@deffn {C Μέλος} unsigned int @ref{e6b,,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{e6c}
@deffn {C Μέλος} @ref{54ec,,destructor} @ref{e6b,,PyTypeObject}.tp_finalize

` The corresponding @ref{541b,,slot ID} @code{Py_tp_finalize} is part of the @ref{95c,,Σταθερό ABI} από την έκδοση 3.5.'
@geindex Py_tp_finalize (C macro)
@anchor{c-api/typeobj c Py_tp_finalize}@anchor{54d4}

An optional pointer to an instance finalization function.  This is the C
implementation of the @ref{13a6,,__del__()} special method.  Its signature
is:

@example
void tp_finalize(PyObject *self);
@end example

The primary purpose of finalization is to perform any non-trivial cleanup
that must be performed before the object is destroyed, while the object and
any other objects it directly or indirectly references are still in a
consistent state.  The finalizer is allowed to execute
arbitrary Python code.

Before Python automatically finalizes an object, some of the object’s direct
or indirect referents might have themselves been automatically finalized.
However, none of the referents will have been automatically cleared
(@ref{51f7,,tp_clear}) yet.

Other non-finalized objects might still be using a finalized object, so the
finalizer must leave the object in a sane state (e.g., invariants are still
met).

@cartouche
@quotation Σημείωση 
After Python automatically finalizes an object, Python might start
automatically clearing (@ref{51f7,,tp_clear}) the object
and its referents (direct and indirect).  Cleared objects are not
guaranteed to be in a consistent state; a finalized object must be able
to tolerate cleared referents.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
An object is not guaranteed to be automatically finalized before its
destructor (@ref{51d3,,tp_dealloc}) is called.  It is
recommended to call @ref{351,,PyObject_CallFinalizerFromDealloc()} at the
beginning of @code{tp_dealloc} to guarantee that the object is
always finalized before destruction.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
The @ref{e6c,,tp_finalize} function can be called from any
thread, although the @ref{411,,GIL} will be held.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
The @code{tp_finalize} function can be called during shutdown,
after some global variables have been deleted.  See the documentation of
the @ref{13a6,,__del__()} method for details.
@end quotation
@end cartouche

When Python finalizes an object, it behaves like the following algorithm:


@enumerate 

@item 
Python might mark the object as `finalized'.  Currently, Python always
marks objects whose type supports garbage collection (i.e., the
@ref{39e,,Py_TPFLAGS_HAVE_GC} flag is set in
@ref{1e68,,tp_flags}) and never marks other types of
objects; this might change in a future version.

@item 
If the object is not marked as `finalized' and its
@code{tp_finalize} finalizer function is non-@code{NULL}, the
finalizer function is called.

@item 
If the finalizer function was called and the finalizer made the object
reachable (i.e., there is a reference to the object and it is not a
member of a @ref{5971,,cyclic isolate}), then the finalizer is said to have
`resurrected' the object.  It is unspecified whether the finalizer can
also resurrect the object by adding a new reference to the object that
does not make it reachable, i.e., the object is (still) a member of a
cyclic isolate.

@item 
If the finalizer resurrected the object, the object’s pending destruction
is canceled and the object’s `finalized' mark might be removed if
present.  Currently, Python never removes the `finalized' mark; this
might change in a future version.
@end enumerate

`Automatic finalization' refers to any finalization performed by Python
except via calls to @ref{5974,,PyObject_CallFinalizer()} or
@ref{351,,PyObject_CallFinalizerFromDealloc()}.  No guarantees are made about
when, if, or how often an object is automatically finalized, except:


@itemize *

@item 
Python will not automatically finalize an object if it is reachable, i.e.,
there is a reference to it and it is not a member of a @ref{5971,,cyclic isolate}.

@item 
Python will not automatically finalize an object if finalizing it would
not mark the object as `finalized'.  Currently, this applies to objects
whose type does not support garbage collection, i.e., the
@ref{39e,,Py_TPFLAGS_HAVE_GC} flag is not set.  Such objects can still be
manually finalized by calling @ref{5974,,PyObject_CallFinalizer()} or
@ref{351,,PyObject_CallFinalizerFromDealloc()}.

@item 
Python will not automatically finalize any two members of a @ref{5971,,cyclic isolate} concurrently.

@item 
Python will not automatically finalize an object after it has
automatically cleared (@ref{51f7,,tp_clear}) the object.

@item 
If an object is a member of a @ref{5971,,cyclic isolate}, Python will not
automatically finalize it after automatically clearing (see
@ref{51f7,,tp_clear}) any other member.

@item 
Python will automatically finalize every member of a @ref{5971,,cyclic isolate} before it automatically clears (see
@ref{51f7,,tp_clear}) any of them.

@item 
If Python is going to automatically clear an object
(@ref{51f7,,tp_clear}), it will automatically finalize the
object first.
@end itemize

Python currently only automatically finalizes objects that are members of a
@ref{5971,,cyclic isolate}, but future versions might finalize objects regularly
before their destruction.

To manually finalize an object, do not call this function directly; call
@ref{5974,,PyObject_CallFinalizer()} or
@ref{351,,PyObject_CallFinalizerFromDealloc()} instead.

@ref{e6c,,tp_finalize} should leave the current exception
status unchanged.  The recommended way to write a non-trivial finalizer is
to back up the exception at the beginning by calling
@ref{63c,,PyErr_GetRaisedException()} and restore the exception at the end by
calling @ref{63f,,PyErr_SetRaisedException()}.  If an exception is encountered
in the middle of the finalizer, log and clear it with
@ref{7e8,,PyErr_WriteUnraisable()} or @ref{7e7,,PyErr_FormatUnraisable()}.  For
example:

@example
static void
foo_finalize(PyObject *self)
@{
    // Save the current exception, if any.
    PyObject *exc = PyErr_GetRaisedException();

    // ...

    if (do_something_that_might_raise() != success_indicator) @{
        PyErr_WriteUnraisable(self);
        goto done;
    @}

done:
    // Restore the saved exception.  This silently discards any exception
    // raised above, so be sure to call PyErr_WriteUnraisable first if
    // necessary.
    PyErr_SetRaisedException(exc);
@}
@end example

`Inheritance:'

This field is inherited by subtypes.


Added in version 3.4.



Άλλαξε στην έκδοση 3.8: Before version 3.8 it was necessary to set the
@ref{63a,,Py_TPFLAGS_HAVE_FINALIZE} flags bit in order for this field to be
used.  This is no longer required.



@subsubheading Δείτε επίσης



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/}: «Safe object finalization»

@item 
@ref{596d,,Object Life Cycle} for details about how this slot relates to other
slots.

@item 
@ref{5974,,PyObject_CallFinalizer()}

@item 
@ref{351,,PyObject_CallFinalizerFromDealloc()}
@end itemize

@end deffn

@geindex PyTypeObject.tp_vectorcall (C member)
@anchor{c-api/typeobj c PyTypeObject tp_vectorcall}@anchor{1b9a}
@deffn {C Μέλος} @ref{960,,vectorcallfunc} @ref{e6b,,PyTypeObject}.tp_vectorcall

` The corresponding @ref{541b,,slot ID} @code{Py_tp_vectorcall} is part of the @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
@geindex Py_tp_vectorcall (C macro)
@anchor{c-api/typeobj c Py_tp_vectorcall}@anchor{54e7}

A @ref{95b,,vectorcall function} to use for calls of this type
object (rather than instances).
In other words, @code{tp_vectorcall} can be used to optimize @code{type.__call__},
which typically returns a new instance of `type'.

As with any vectorcall function, if @code{tp_vectorcall} is @code{NULL},
the `tp_call' protocol (@code{Py_TYPE(type)->tp_call}) is used instead.

@cartouche
@quotation Σημείωση 
The @ref{95b,,vectorcall protocol} requires that the vectorcall
function has the same behavior as the corresponding @code{tp_call}.
This means that @code{type->tp_vectorcall} must match the behavior of
@code{Py_TYPE(type)->tp_call}.

Specifically, if `type' uses the default metaclass,
@code{type->tp_vectorcall} must behave the same as
@ref{958,,PyType_Type}->tp_call, which:


@itemize -

@item 
calls @code{type->tp_new},

@item 
if the result is a subclass of `type', calls @code{type->tp_init}
on the result of @code{tp_new}, and

@item 
returns the result of @code{tp_new}.
@end itemize

Typically, @code{tp_vectorcall} is overridden to optimize this process
for specific @ref{981,,tp_new} and
@ref{983,,tp_init}.
When doing this for user-subclassable types, note that both can be
overridden (using @ref{982,,__new__()} and
@ref{2fa,,__init__()}, respectively).
@end quotation
@end cartouche

`Inheritance:'

This field is never inherited.


Added in 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{59a8}
@deffn {C Μέλος} unsigned char @ref{e6b,,PyTypeObject}.tp_watched

Internal. Do not use.


Added in version 3.12.

@end deffn

@node Static Types,Heap Types,PyTypeObject Slots,Type Object Structures
@anchor{c-api/typeobj id4}@anchor{59f4}@anchor{c-api/typeobj static-types}@anchor{b5f}
@subsubsection Static Types


Traditionally, types defined in C code are `static', that is,
a static @ref{e6b,,PyTypeObject} structure is defined directly in code
and initialized using @ref{b5e,,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{410,,sub-interpreters}, so they should not
include any subinterpreter-specific state.
@end itemize

Also, since @ref{e6b,,PyTypeObject} is only part of the @ref{829,,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,Type Object Structures
@anchor{c-api/typeobj heap-types}@anchor{d2f}@anchor{c-api/typeobj id5}@anchor{59f5}
@subsubsection Heap Types


An alternative to @ref{b5f,,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{c82,,Py_TPFLAGS_HEAPTYPE}
flag set.

This is done by filling a @ref{1c8f,,PyType_Spec} structure and calling
@ref{38e,,PyType_FromSpec()}, @ref{38f,,PyType_FromSpecWithBases()},
@ref{390,,PyType_FromModuleAndSpec()}, or @ref{391,,PyType_FromMetaclass()}.

@node Number Object Structures,Mapping Object Structures,Heap Types,Type Object Structures
@anchor{c-api/typeobj number-object-structures}@anchor{59f6}@anchor{c-api/typeobj number-structs}@anchor{59e0}
@subsubsection Number Object Structures


@geindex PyNumberMethods (C type)
@anchor{c-api/typeobj c PyNumberMethods}@anchor{17c0}
@deffn {C Τύπος} 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{5603,,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 Σημείωση 
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 Σημείωση 
The @ref{59c9,,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{5645}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_add

` The corresponding @ref{541b,,slot ID} @code{Py_nb_add} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_add (C macro)
@anchor{c-api/typeobj c Py_nb_add}@anchor{54a0}
@end deffn

@geindex PyNumberMethods.nb_subtract (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_subtract}@anchor{59b0}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_subtract

` The corresponding @ref{541b,,slot ID} @code{Py_nb_subtract} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_subtract (C macro)
@anchor{c-api/typeobj c Py_nb_subtract}@anchor{54bf}
@end deffn

@geindex PyNumberMethods.nb_multiply (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_multiply}@anchor{59b2}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_multiply

` The corresponding @ref{541b,,slot ID} @code{Py_nb_multiply} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_multiply (C macro)
@anchor{c-api/typeobj c Py_nb_multiply}@anchor{54b8}
@end deffn

@geindex PyNumberMethods.nb_remainder (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_remainder}@anchor{59b4}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_remainder

` The corresponding @ref{541b,,slot ID} @code{Py_nb_remainder} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_remainder (C macro)
@anchor{c-api/typeobj c Py_nb_remainder}@anchor{54bd}
@end deffn

@geindex PyNumberMethods.nb_divmod (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_divmod}@anchor{59b6}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_divmod

` The corresponding @ref{541b,,slot ID} @code{Py_nb_divmod} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_divmod (C macro)
@anchor{c-api/typeobj c Py_nb_divmod}@anchor{54a3}
@end deffn

@geindex PyNumberMethods.nb_power (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_power}@anchor{59b7}
@deffn {C Μέλος} @ref{5502,,ternaryfunc} @ref{17c0,,PyNumberMethods}.nb_power

` The corresponding @ref{541b,,slot ID} @code{Py_nb_power} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_power (C macro)
@anchor{c-api/typeobj c Py_nb_power}@anchor{54bc}
@end deffn

@geindex PyNumberMethods.nb_negative (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_negative}@anchor{59b9}
@deffn {C Μέλος} @ref{5504,,unaryfunc} @ref{17c0,,PyNumberMethods}.nb_negative

` The corresponding @ref{541b,,slot ID} @code{Py_nb_negative} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_negative (C macro)
@anchor{c-api/typeobj c Py_nb_negative}@anchor{54b9}
@end deffn

@geindex PyNumberMethods.nb_positive (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_positive}@anchor{59ba}
@deffn {C Μέλος} @ref{5504,,unaryfunc} @ref{17c0,,PyNumberMethods}.nb_positive

` The corresponding @ref{541b,,slot ID} @code{Py_nb_positive} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_positive (C macro)
@anchor{c-api/typeobj c Py_nb_positive}@anchor{54bb}
@end deffn

@geindex PyNumberMethods.nb_absolute (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_absolute}@anchor{59bb}
@deffn {C Μέλος} @ref{5504,,unaryfunc} @ref{17c0,,PyNumberMethods}.nb_absolute

` The corresponding @ref{541b,,slot ID} @code{Py_nb_absolute} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_absolute (C macro)
@anchor{c-api/typeobj c Py_nb_absolute}@anchor{549f}
@end deffn

@geindex PyNumberMethods.nb_bool (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_bool}@anchor{59bc}
@deffn {C Μέλος} @ref{54f4,,inquiry} @ref{17c0,,PyNumberMethods}.nb_bool

` The corresponding @ref{541b,,slot ID} @code{Py_nb_bool} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_bool (C macro)
@anchor{c-api/typeobj c Py_nb_bool}@anchor{54a2}
@end deffn

@geindex PyNumberMethods.nb_invert (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_invert}@anchor{59bd}
@deffn {C Μέλος} @ref{5504,,unaryfunc} @ref{17c0,,PyNumberMethods}.nb_invert

` The corresponding @ref{541b,,slot ID} @code{Py_nb_invert} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_invert (C macro)
@anchor{c-api/typeobj c Py_nb_invert}@anchor{54b5}
@end deffn

@geindex PyNumberMethods.nb_lshift (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_lshift}@anchor{59be}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_lshift

` The corresponding @ref{541b,,slot ID} @code{Py_nb_lshift} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_lshift (C macro)
@anchor{c-api/typeobj c Py_nb_lshift}@anchor{54b6}
@end deffn

@geindex PyNumberMethods.nb_rshift (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_rshift}@anchor{59c0}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_rshift

` The corresponding @ref{541b,,slot ID} @code{Py_nb_rshift} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_rshift (C macro)
@anchor{c-api/typeobj c Py_nb_rshift}@anchor{54be}
@end deffn

@geindex PyNumberMethods.nb_and (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_and}@anchor{59c2}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_and

` The corresponding @ref{541b,,slot ID} @code{Py_nb_and} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_and (C macro)
@anchor{c-api/typeobj c Py_nb_and}@anchor{54a1}
@end deffn

@geindex PyNumberMethods.nb_xor (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_xor}@anchor{59c4}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_xor

` The corresponding @ref{541b,,slot ID} @code{Py_nb_xor} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_xor (C macro)
@anchor{c-api/typeobj c Py_nb_xor}@anchor{54c1}
@end deffn

@geindex PyNumberMethods.nb_or (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_or}@anchor{59c6}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_or

` The corresponding @ref{541b,,slot ID} @code{Py_nb_or} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_or (C macro)
@anchor{c-api/typeobj c Py_nb_or}@anchor{54ba}
@end deffn

@geindex PyNumberMethods.nb_int (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_int}@anchor{59c8}
@deffn {C Μέλος} @ref{5504,,unaryfunc} @ref{17c0,,PyNumberMethods}.nb_int

` The corresponding @ref{541b,,slot ID} @code{Py_nb_int} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_int (C macro)
@anchor{c-api/typeobj c Py_nb_int}@anchor{54b4}
@end deffn

@geindex PyNumberMethods.nb_reserved (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_reserved}@anchor{59c9}
@deffn {C Μέλος} void *@ref{17c0,,PyNumberMethods}.nb_reserved
@end deffn

@geindex PyNumberMethods.nb_float (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_float}@anchor{59ca}
@deffn {C Μέλος} @ref{5504,,unaryfunc} @ref{17c0,,PyNumberMethods}.nb_float

` The corresponding @ref{541b,,slot ID} @code{Py_nb_float} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_float (C macro)
@anchor{c-api/typeobj c Py_nb_float}@anchor{54a4}
@end deffn

@geindex PyNumberMethods.nb_inplace_add (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_add}@anchor{59af}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_add

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_add} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_inplace_add (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_add}@anchor{54a7}
@end deffn

@geindex PyNumberMethods.nb_inplace_subtract (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_subtract}@anchor{59b1}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_subtract

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_subtract} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_inplace_subtract (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_subtract}@anchor{54b1}
@end deffn

@geindex PyNumberMethods.nb_inplace_multiply (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_multiply}@anchor{59b3}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_multiply

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_multiply} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_inplace_multiply (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_multiply}@anchor{54ac}
@end deffn

@geindex PyNumberMethods.nb_inplace_remainder (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_remainder}@anchor{59b5}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_remainder

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_remainder} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_inplace_remainder (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_remainder}@anchor{54af}
@end deffn

@geindex PyNumberMethods.nb_inplace_power (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_power}@anchor{59b8}
@deffn {C Μέλος} @ref{5502,,ternaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_power

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_power} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_inplace_power (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_power}@anchor{54ae}
@end deffn

@geindex PyNumberMethods.nb_inplace_lshift (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_lshift}@anchor{59bf}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_lshift

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_lshift} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_inplace_lshift (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_lshift}@anchor{54aa}
@end deffn

@geindex PyNumberMethods.nb_inplace_rshift (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_rshift}@anchor{59c1}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_rshift

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_rshift} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_inplace_rshift (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_rshift}@anchor{54b0}
@end deffn

@geindex PyNumberMethods.nb_inplace_and (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_and}@anchor{59c3}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_and

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_and} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_inplace_and (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_and}@anchor{54a8}
@end deffn

@geindex PyNumberMethods.nb_inplace_xor (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_xor}@anchor{59c5}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_xor

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_xor} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_inplace_xor (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_xor}@anchor{54b3}
@end deffn

@geindex PyNumberMethods.nb_inplace_or (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_or}@anchor{59c7}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_or

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_or} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_inplace_or (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_or}@anchor{54ad}
@end deffn

@geindex PyNumberMethods.nb_floor_divide (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_floor_divide}@anchor{59cb}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_floor_divide

` The corresponding @ref{541b,,slot ID} @code{Py_nb_floor_divide} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_floor_divide (C macro)
@anchor{c-api/typeobj c Py_nb_floor_divide}@anchor{54a5}
@end deffn

@geindex PyNumberMethods.nb_true_divide (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_true_divide}@anchor{59cd}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_true_divide

` The corresponding @ref{541b,,slot ID} @code{Py_nb_true_divide} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_true_divide (C macro)
@anchor{c-api/typeobj c Py_nb_true_divide}@anchor{54c0}
@end deffn

@geindex PyNumberMethods.nb_inplace_floor_divide (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_floor_divide}@anchor{59cc}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_floor_divide

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_floor_divide} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_inplace_floor_divide (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_floor_divide}@anchor{54a9}
@end deffn

@geindex PyNumberMethods.nb_inplace_true_divide (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_true_divide}@anchor{59ce}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_true_divide

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_true_divide} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_inplace_true_divide (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_true_divide}@anchor{54b2}
@end deffn

@geindex PyNumberMethods.nb_index (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_index}@anchor{17bf}
@deffn {C Μέλος} @ref{5504,,unaryfunc} @ref{17c0,,PyNumberMethods}.nb_index

` The corresponding @ref{541b,,slot ID} @code{Py_nb_index} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_nb_index (C macro)
@anchor{c-api/typeobj c Py_nb_index}@anchor{54a6}
@end deffn

@geindex PyNumberMethods.nb_matrix_multiply (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_matrix_multiply}@anchor{59cf}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_matrix_multiply

` The corresponding @ref{541b,,slot ID} @code{Py_nb_matrix_multiply} is part of the @ref{95c,,Σταθερό ABI} από την έκδοση 3.5.'
@geindex Py_nb_matrix_multiply (C macro)
@anchor{c-api/typeobj c Py_nb_matrix_multiply}@anchor{54b7}
@end deffn

@geindex PyNumberMethods.nb_inplace_matrix_multiply (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_matrix_multiply}@anchor{59d0}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{17c0,,PyNumberMethods}.nb_inplace_matrix_multiply

` The corresponding @ref{541b,,slot ID} @code{Py_nb_inplace_matrix_multiply} is part of the @ref{95c,,Σταθερό ABI} από την έκδοση 3.5.'
@geindex Py_nb_inplace_matrix_multiply (C macro)
@anchor{c-api/typeobj c Py_nb_inplace_matrix_multiply}@anchor{54ab}
@end deffn

@node Mapping Object Structures,Sequence Object Structures,Number Object Structures,Type Object Structures
@anchor{c-api/typeobj mapping-object-structures}@anchor{59f7}@anchor{c-api/typeobj mapping-structs}@anchor{59e2}
@subsubsection Mapping Object Structures


@geindex PyMappingMethods (C type)
@anchor{c-api/typeobj c PyMappingMethods}@anchor{520a}
@deffn {C Τύπος} 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{59d1}
@deffn {C Μέλος} @ref{54f6,,lenfunc} @ref{520a,,PyMappingMethods}.mp_length

` The corresponding @ref{541b,,slot ID} @code{Py_mp_length} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_mp_length (C macro)
@anchor{c-api/typeobj c Py_mp_length}@anchor{549d}

This function is used by @ref{2024,,PyMapping_Size()} and
@ref{53cf,,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{1eeb}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{520a,,PyMappingMethods}.mp_subscript

` The corresponding @ref{541b,,slot ID} @code{Py_mp_subscript} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_mp_subscript (C macro)
@anchor{c-api/typeobj c Py_mp_subscript}@anchor{549e}

This function is used by @ref{7e2,,PyObject_GetItem()} and
@ref{53db,,PySequence_GetSlice()}, and has the same signature as
@code{PyObject_GetItem()}.  This slot must be filled for the
@ref{5383,,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{59d2}
@deffn {C Μέλος} @ref{54f8,,objobjargproc} @ref{520a,,PyMappingMethods}.mp_ass_subscript

` The corresponding @ref{541b,,slot ID} @code{Py_mp_ass_subscript} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_mp_ass_subscript (C macro)
@anchor{c-api/typeobj c Py_mp_ass_subscript}@anchor{549c}

This function is used by @ref{525f,,PyObject_SetItem()},
@ref{53c2,,PyObject_DelItem()}, @ref{53e2,,PySequence_SetSlice()} and
@ref{53da,,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,Type Object Structures
@anchor{c-api/typeobj sequence-object-structures}@anchor{59f8}@anchor{c-api/typeobj sequence-structs}@anchor{59e1}
@subsubsection Sequence Object Structures


@geindex PySequenceMethods (C type)
@anchor{c-api/typeobj c PySequenceMethods}@anchor{5209}
@deffn {C Τύπος} 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{564b}
@deffn {C Μέλος} @ref{54f6,,lenfunc} @ref{5209,,PySequenceMethods}.sq_length

` The corresponding @ref{541b,,slot ID} @code{Py_sq_length} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_sq_length (C macro)
@anchor{c-api/typeobj c Py_sq_length}@anchor{54c8}

This function is used by @ref{2020,,PySequence_Size()} and
@ref{53cf,,PyObject_Size()}, and has the same signature.  It is also used for
handling negative indices via the @ref{1eea,,sq_item}
and the @ref{59d5,,sq_ass_item} slots.
@end deffn

@geindex PySequenceMethods.sq_concat (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_concat}@anchor{59d3}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{5209,,PySequenceMethods}.sq_concat

` The corresponding @ref{541b,,slot ID} @code{Py_sq_concat} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_sq_concat (C macro)
@anchor{c-api/typeobj c Py_sq_concat}@anchor{54c3}

This function is used by @ref{53d8,,PySequence_Concat()} and has the same
signature.  It is also used by the @code{+} operator, after trying the numeric
addition via the @ref{5645,,nb_add} slot.
@end deffn

@geindex PySequenceMethods.sq_repeat (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_repeat}@anchor{59d4}
@deffn {C Μέλος} @ref{5500,,ssizeargfunc} @ref{5209,,PySequenceMethods}.sq_repeat

` The corresponding @ref{541b,,slot ID} @code{Py_sq_repeat} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_sq_repeat (C macro)
@anchor{c-api/typeobj c Py_sq_repeat}@anchor{54c9}

This function is used by @ref{53e1,,PySequence_Repeat()} and has the same
signature.  It is also used by the @code{*} operator, after trying numeric
multiplication via the @ref{59b2,,nb_multiply} slot.
@end deffn

@geindex PySequenceMethods.sq_item (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_item}@anchor{1eea}
@deffn {C Μέλος} @ref{5500,,ssizeargfunc} @ref{5209,,PySequenceMethods}.sq_item

` The corresponding @ref{541b,,slot ID} @code{Py_sq_item} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_sq_item (C macro)
@anchor{c-api/typeobj c Py_sq_item}@anchor{54c7}

This function is used by @ref{2021,,PySequence_GetItem()} and has the same
signature.  It is also used by @ref{7e2,,PyObject_GetItem()}, after trying
the subscription via the @ref{1eeb,,mp_subscript} slot.
This slot must be filled for the @ref{53d7,,PySequence_Check()}
function to return @code{1}, it can be @code{NULL} otherwise.

Negative indexes are handled as follows: if the @ref{564b,,sq_length} slot is
filled, it is called and the sequence length is used to compute a positive
index which is passed to  @ref{1eea,,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{59d5}
@deffn {C Μέλος} @ref{5501,,ssizeobjargproc} @ref{5209,,PySequenceMethods}.sq_ass_item

` The corresponding @ref{541b,,slot ID} @code{Py_sq_ass_item} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_sq_ass_item (C macro)
@anchor{c-api/typeobj c Py_sq_ass_item}@anchor{54c2}

This function is used by @ref{2022,,PySequence_SetItem()} and has the same
signature.  It is also used by @ref{525f,,PyObject_SetItem()} and
@ref{53c2,,PyObject_DelItem()}, after trying the item assignment and deletion
via the @ref{59d2,,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{59d6}
@deffn {C Μέλος} @ref{54f9,,objobjproc} @ref{5209,,PySequenceMethods}.sq_contains

` The corresponding @ref{541b,,slot ID} @code{Py_sq_contains} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_sq_contains (C macro)
@anchor{c-api/typeobj c Py_sq_contains}@anchor{54c4}

This function may be used by @ref{605,,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{59d7}
@deffn {C Μέλος} @ref{54e9,,binaryfunc} @ref{5209,,PySequenceMethods}.sq_inplace_concat

` The corresponding @ref{541b,,slot ID} @code{Py_sq_inplace_concat} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_sq_inplace_concat (C macro)
@anchor{c-api/typeobj c Py_sq_inplace_concat}@anchor{54c5}

This function is used by @ref{53dc,,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{53d8,,PySequence_Concat()}.  It is also used by the
augmented assignment @code{+=}, after trying numeric in-place addition
via the @ref{59af,,nb_inplace_add} slot.
@end deffn

@geindex PySequenceMethods.sq_inplace_repeat (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_inplace_repeat}@anchor{59d8}
@deffn {C Μέλος} @ref{5500,,ssizeargfunc} @ref{5209,,PySequenceMethods}.sq_inplace_repeat

` The corresponding @ref{541b,,slot ID} @code{Py_sq_inplace_repeat} is part of the @ref{95c,,Σταθερό ABI}.'
@geindex Py_sq_inplace_repeat (C macro)
@anchor{c-api/typeobj c Py_sq_inplace_repeat}@anchor{54c6}

This function is used by @ref{53dd,,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{53e1,,PySequence_Repeat()}.  It is also used by the
augmented assignment @code{*=}, after trying numeric in-place multiplication
via the @ref{59b3,,nb_inplace_multiply} slot.
@end deffn

@node Buffer Object Structures,Async Object Structures,Sequence Object Structures,Type Object Structures
@anchor{c-api/typeobj buffer-object-structures}@anchor{59f9}@anchor{c-api/typeobj buffer-structs}@anchor{561a}
@subsubsection Buffer Object Structures


@geindex PyBufferProcs (C type)
@anchor{c-api/typeobj c PyBufferProcs}@anchor{5651}
@deffn {C Τύπος} type PyBufferProcs

This structure holds pointers to the functions required by the
@ref{311,,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{b44}
@deffn {C Μέλος} @ref{54ef,,getbufferproc} @ref{5651,,PyBufferProcs}.bf_getbuffer

` The corresponding @ref{541b,,slot ID} @code{Py_bf_getbuffer} is part of the @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@geindex Py_bf_getbuffer (C macro)
@anchor{c-api/typeobj c Py_bf_getbuffer}@anchor{5493}

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{1998,,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

`Thread safety:'

In the @ref{198,,free-threaded build}, implementations must ensure:


@itemize *

@item 
The export counter increment in step (3) is atomic.

@item 
The underlying buffer data remains valid and at a stable memory
location for the lifetime of all exports.

@item 
For objects that support resizing or reallocation (such as
@ref{1c6,,bytearray}), the export counter is checked atomically before
such operations, and @ref{1998,,BufferError} is raised if exports exist.

@item 
The function is safe to call concurrently from multiple threads.
@end itemize

See also @ref{2606,,Thread safety for memoryview objects} for the Python-level
thread safety guarantees of @ref{1d2,,memoryview} objects.

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{561b,,Buffer structure}, the rules how an exporter
must react to specific requests are in section
@ref{4d3b,,Buffer request types}.

All memory pointed to in the @ref{b3a,,Py_buffer} structure belongs to
the exporter and must remain valid until there are no consumers left.
@ref{5624,,format}, @ref{5625,,shape},
@ref{561f,,strides}, @ref{5627,,suboffsets}
and @ref{5629,,internal}
are read-only for the consumer.

@ref{b42,,PyBuffer_FillInfo()} provides an easy way of exposing a simple
bytes buffer while dealing correctly with all request types.

@ref{82c,,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{b45}
@deffn {C Μέλος} @ref{54fa,,releasebufferproc} @ref{5651,,PyBufferProcs}.bf_releasebuffer

` The corresponding @ref{541b,,slot ID} @code{Py_bf_releasebuffer} is part of the @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
@geindex Py_bf_releasebuffer (C macro)
@anchor{c-api/typeobj c Py_bf_releasebuffer}@anchor{5494}

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{b45,,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

`Thread safety:'

In the @ref{198,,free-threaded build}:


@itemize *

@item 
The export counter decrement in step (1) must be atomic.

@item 
Resource cleanup when the counter reaches zero must be done atomically,
as the final release may race with concurrent releases from other
threads and dellocation must only happen once.
@end itemize

The exporter MUST use the @ref{5629,,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{82d,,PyBuffer_Release()} (this scheme is
useful for breaking reference cycles).

@ref{82d,,PyBuffer_Release()} is the interface for the consumer that
wraps this function.
@end deffn

@node Async Object Structures,Slot Type typedefs,Buffer Object Structures,Type Object Structures
@anchor{c-api/typeobj async-object-structures}@anchor{59fa}@anchor{c-api/typeobj async-structs}@anchor{59df}
@subsubsection Async Object Structures



Added in version 3.5.


@geindex PyAsyncMethods (C type)
@anchor{c-api/typeobj c PyAsyncMethods}@anchor{564a}
@deffn {C Τύπος} type PyAsyncMethods

This structure holds pointers to the functions required to implement
@ref{6cf,,awaitable} and @ref{6cd,,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{59aa}
@deffn {C Μέλος} @ref{5504,,unaryfunc} @ref{564a,,PyAsyncMethods}.am_await

` The corresponding @ref{541b,,slot ID} @code{Py_am_await} is part of the @ref{95c,,Σταθερό ABI} από την έκδοση 3.5.'
@geindex Py_am_await (C macro)
@anchor{c-api/typeobj c Py_am_await}@anchor{5491}

The signature of this function is:

@example
PyObject *am_await(PyObject *self);
@end example

The returned object must be an @ref{6ce,,iterator}, i.e. @ref{1ea8,,PyIter_Check()}
must return @code{1} for it.

This slot may be set to @code{NULL} if an object is not an @ref{6cf,,awaitable}.
@end deffn

@geindex PyAsyncMethods.am_aiter (C member)
@anchor{c-api/typeobj c PyAsyncMethods am_aiter}@anchor{59ab}
@deffn {C Μέλος} @ref{5504,,unaryfunc} @ref{564a,,PyAsyncMethods}.am_aiter

` The corresponding @ref{541b,,slot ID} @code{Py_am_aiter} is part of the @ref{95c,,Σταθερό ABI} από την έκδοση 3.5.'
@geindex Py_am_aiter (C macro)
@anchor{c-api/typeobj c Py_am_aiter}@anchor{548f}

The signature of this function is:

@example
PyObject *am_aiter(PyObject *self);
@end example

Must return an @ref{6cd,,asynchronous iterator} object.
See @ref{1aa7,,__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{59ac}
@deffn {C Μέλος} @ref{5504,,unaryfunc} @ref{564a,,PyAsyncMethods}.am_anext

` The corresponding @ref{541b,,slot ID} @code{Py_am_anext} is part of the @ref{95c,,Σταθερό ABI} από την έκδοση 3.5.'
@geindex Py_am_anext (C macro)
@anchor{c-api/typeobj c Py_am_anext}@anchor{5490}

The signature of this function is:

@example
PyObject *am_anext(PyObject *self);
@end example

Must return an @ref{6cf,,awaitable} object.
See @ref{1aa7,,__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{59ad}
@deffn {C Μέλος} @ref{59ae,,sendfunc} @ref{564a,,PyAsyncMethods}.am_send

` The corresponding @ref{541b,,slot ID} @code{Py_am_send} is part of the @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
@geindex Py_am_send (C macro)
@anchor{c-api/typeobj c Py_am_send}@anchor{5492}

The signature of this function is:

@example
PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);
@end example

See @ref{c6e,,PyIter_Send()} for details.
This slot may be set to @code{NULL}.


Added in version 3.10.

@end deffn

@node Slot Type typedefs,Examples<33>,Async Object Structures,Type Object Structures
@anchor{c-api/typeobj id6}@anchor{59da}@anchor{c-api/typeobj slot-type-typedefs}@anchor{59fb}
@subsubsection Slot Type typedefs


@geindex allocfunc (C type)
@anchor{c-api/typeobj c allocfunc}@anchor{54e8}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*allocfunc)(@ref{e6b,,PyTypeObject} *cls, @ref{e24,,Py_ssize_t} nitems)
` Μέρος του @ref{95c,,Σταθερό 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{c75,,ob_refcnt} set to @code{1} and @ref{51e3,,ob_type} set to the type argument.  If
the type’s @ref{25b0,,tp_itemsize} is non-zero, the object’s @ref{545c,,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{d4f,,tp_basicsize}.

This function should not do any other instance initialization, not even to
allocate additional memory; that should be done by @ref{981,,tp_new}.
@end deffn

@geindex destructor (C type)
@anchor{c-api/typeobj c destructor}@anchor{54ec}
@deffn {C Τύπος} typedef void (*destructor)(@ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex freefunc (C type)
@anchor{c-api/typeobj c freefunc}@anchor{57bd}
@deffn {C Τύπος} typedef void (*freefunc)(void*)

See @ref{51e5,,tp_free}.
@end deffn

@geindex newfunc (C type)
@anchor{c-api/typeobj c newfunc}@anchor{54f7}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*newfunc)(@ref{e6b,,PyTypeObject}*, @ref{19b,,PyObject}*, @ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
See @ref{981,,tp_new}.
@end deffn

@geindex initproc (C type)
@anchor{c-api/typeobj c initproc}@anchor{54f3}
@deffn {C Τύπος} typedef int (*initproc)(@ref{19b,,PyObject}*, @ref{19b,,PyObject}*, @ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
See @ref{983,,tp_init}.
@end deffn

@geindex reprfunc (C type)
@anchor{c-api/typeobj c reprfunc}@anchor{54fb}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*reprfunc)(@ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
See @ref{51f9,,tp_repr}.
@end deffn

@geindex getattrfunc (C type)
@anchor{c-api/typeobj c getattrfunc}@anchor{54ed}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*getattrfunc)(@ref{19b,,PyObject} *self, char *attr)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the value of the named attribute for the object.
@end deffn

@geindex setattrfunc (C type)
@anchor{c-api/typeobj c setattrfunc}@anchor{54fd}
@deffn {C Τύπος} typedef int (*setattrfunc)(@ref{19b,,PyObject} *self, char *attr, @ref{19b,,PyObject} *value)
` Μέρος του @ref{95c,,Σταθερό 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{54ee}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*getattrofunc)(@ref{19b,,PyObject} *self, @ref{19b,,PyObject} *attr)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Return the value of the named attribute for the object.

See @ref{1c6a,,tp_getattro}.
@end deffn

@geindex setattrofunc (C type)
@anchor{c-api/typeobj c setattrofunc}@anchor{54fe}
@deffn {C Τύπος} typedef int (*setattrofunc)(@ref{19b,,PyObject} *self, @ref{19b,,PyObject} *attr, @ref{19b,,PyObject} *value)
` Μέρος του @ref{95c,,Σταθερό 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{51fd,,tp_setattro}.
@end deffn

@geindex descrgetfunc (C type)
@anchor{c-api/typeobj c descrgetfunc}@anchor{54ea}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*descrgetfunc)(@ref{19b,,PyObject}*, @ref{19b,,PyObject}*, @ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
See @ref{57d6,,tp_descr_get}.
@end deffn

@geindex descrsetfunc (C type)
@anchor{c-api/typeobj c descrsetfunc}@anchor{54eb}
@deffn {C Τύπος} typedef int (*descrsetfunc)(@ref{19b,,PyObject}*, @ref{19b,,PyObject}*, @ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
See @ref{1eaa,,tp_descr_set}.
@end deffn

@geindex hashfunc (C type)
@anchor{c-api/typeobj c hashfunc}@anchor{54f2}
@deffn {C Τύπος} typedef @ref{1608,,Py_hash_t} (*hashfunc)(@ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
See @ref{520b,,tp_hash}.
@end deffn

@geindex richcmpfunc (C type)
@anchor{c-api/typeobj c richcmpfunc}@anchor{54fc}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*richcmpfunc)(@ref{19b,,PyObject}*, @ref{19b,,PyObject}*, int)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
See @ref{5205,,tp_richcompare}.
@end deffn

@geindex getiterfunc (C type)
@anchor{c-api/typeobj c getiterfunc}@anchor{54f0}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*getiterfunc)(@ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
See @ref{1891,,tp_iter}.
@end deffn

@geindex iternextfunc (C type)
@anchor{c-api/typeobj c iternextfunc}@anchor{54f5}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*iternextfunc)(@ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
See @ref{1892,,tp_iternext}.
@end deffn

@geindex lenfunc (C type)
@anchor{c-api/typeobj c lenfunc}@anchor{54f6}
@deffn {C Τύπος} typedef @ref{e24,,Py_ssize_t} (*lenfunc)(@ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex getbufferproc (C type)
@anchor{c-api/typeobj c getbufferproc}@anchor{54ef}
@deffn {C Τύπος} typedef int (*getbufferproc)(@ref{19b,,PyObject}*, @ref{b3a,,Py_buffer}*, int)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@geindex releasebufferproc (C type)
@anchor{c-api/typeobj c releasebufferproc}@anchor{54fa}
@deffn {C Τύπος} typedef void (*releasebufferproc)(@ref{19b,,PyObject}*, @ref{b3a,,Py_buffer}*)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.12.'
@end deffn

@geindex unaryfunc (C type)
@anchor{c-api/typeobj c unaryfunc}@anchor{5504}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*unaryfunc)(@ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex binaryfunc (C type)
@anchor{c-api/typeobj c binaryfunc}@anchor{54e9}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*binaryfunc)(@ref{19b,,PyObject}*, @ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex sendfunc (C type)
@anchor{c-api/typeobj c sendfunc}@anchor{59ae}
@deffn {C Τύπος} typedef @ref{5616,,PySendResult} (*sendfunc)(@ref{19b,,PyObject}*, @ref{19b,,PyObject}*, @ref{19b,,PyObject}**)

See @ref{59ad,,am_send}.
@end deffn

@geindex ternaryfunc (C type)
@anchor{c-api/typeobj c ternaryfunc}@anchor{5502}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*ternaryfunc)(@ref{19b,,PyObject}*, @ref{19b,,PyObject}*, @ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex ssizeargfunc (C type)
@anchor{c-api/typeobj c ssizeargfunc}@anchor{5500}
@deffn {C Τύπος} typedef @ref{19b,,PyObject} *(*ssizeargfunc)(@ref{19b,,PyObject}*, @ref{e24,,Py_ssize_t})
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex ssizeobjargproc (C type)
@anchor{c-api/typeobj c ssizeobjargproc}@anchor{5501}
@deffn {C Τύπος} typedef int (*ssizeobjargproc)(@ref{19b,,PyObject}*, @ref{e24,,Py_ssize_t}, @ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex objobjproc (C type)
@anchor{c-api/typeobj c objobjproc}@anchor{54f9}
@deffn {C Τύπος} typedef int (*objobjproc)(@ref{19b,,PyObject}*, @ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@geindex objobjargproc (C type)
@anchor{c-api/typeobj c objobjargproc}@anchor{54f8}
@deffn {C Τύπος} typedef int (*objobjargproc)(@ref{19b,,PyObject}*, @ref{19b,,PyObject}*, @ref{19b,,PyObject}*)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
@end deffn

@node Examples<33>,,Slot Type typedefs,Type Object Structures
@anchor{c-api/typeobj examples}@anchor{59fc}@anchor{c-api/typeobj typedef-examples}@anchor{599c}
@subsubsection Examples


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{51dc,,Defining Extension Types; Tutorial} and @ref{51f3,,Defining Extension Types; Assorted Topics}.

A basic @ref{b5f,,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{984,,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{b5f,,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{b5f,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Supporting Cyclic Garbage Collection,,Type Object Structures,Object Implementation Support
@anchor{c-api/gcsupport doc}@anchor{59fd}@anchor{c-api/gcsupport supporting-cycle-detection}@anchor{59e3}@anchor{c-api/gcsupport supporting-cyclic-garbage-collection}@anchor{59fe}@anchor{c-api/gcsupport translation-repo}@anchor{59ff}
@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{1e68,,tp_flags} field of the type object must
include the @ref{39e,,Py_TPFLAGS_HAVE_GC} and provide an implementation of the
@ref{36b,,tp_traverse} handler.  If instances of the type are mutable, a
@ref{51f7,,tp_clear} implementation must also be provided.


@table @asis

@item @ref{39e,,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{e68,,PyObject_GC_New}
or @ref{e69,,PyObject_GC_NewVar}.

@item 
Once all the fields which may contain references to other containers are
initialized, it must call @ref{18a6,,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{18a7,,PyObject_GC_UnTrack()} must be called.

@item 
The object’s memory must be deallocated using @ref{18a5,,PyObject_GC_Del()}.

@cartouche
@quotation Προειδοποίηση 
If a type adds the Py_TPFLAGS_HAVE_GC, then it `must' implement at least
a @ref{36b,,tp_traverse} handler or explicitly use one
from its subclass or subclasses.

When calling @ref{b5e,,PyType_Ready()} or some of the APIs that indirectly
call it like @ref{38f,,PyType_FromSpecWithBases()} or
@ref{38e,,PyType_FromSpec()} the interpreter will automatically populate the
@ref{1e68,,tp_flags}, @ref{36b,,tp_traverse}
and @ref{51f7,,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{39e,,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{e68}
@deffn {C Μακροεντολή} PyObject_GC_New (TYPE, typeobj)

Analogous to @ref{d4d,,PyObject_New} but for container objects with the
@ref{39e,,Py_TPFLAGS_HAVE_GC} flag set.

Do not call this directly to allocate memory for an object; call the type’s
@ref{51e6,,tp_alloc} slot instead.

When populating a type’s @ref{51e6,,tp_alloc} slot,
@ref{e30,,PyType_GenericAlloc()} is preferred over a custom function that
simply calls this macro.

Memory allocated by this macro must be freed with
@ref{18a5,,PyObject_GC_Del()} (usually called via the object’s
@ref{51e5,,tp_free} slot).


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{18a5,,PyObject_GC_Del()}

@item 
@ref{d4d,,PyObject_New}

@item 
@ref{e30,,PyType_GenericAlloc()}

@item 
@ref{51e6,,tp_alloc}
@end itemize

@end deffn

@geindex PyObject_GC_NewVar (C macro)
@anchor{c-api/gcsupport c PyObject_GC_NewVar}@anchor{e69}
@deffn {C Μακροεντολή} PyObject_GC_NewVar (TYPE, typeobj, size)

Analogous to @ref{d4e,,PyObject_NewVar} but for container objects with the
@ref{39e,,Py_TPFLAGS_HAVE_GC} flag set.

Do not call this directly to allocate memory for an object; call the type’s
@ref{51e6,,tp_alloc} slot instead.

When populating a type’s @ref{51e6,,tp_alloc} slot,
@ref{e30,,PyType_GenericAlloc()} is preferred over a custom function that
simply calls this macro.

Memory allocated by this macro must be freed with
@ref{18a5,,PyObject_GC_Del()} (usually called via the object’s
@ref{51e5,,tp_free} slot).


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{18a5,,PyObject_GC_Del()}

@item 
@ref{d4e,,PyObject_NewVar}

@item 
@ref{e30,,PyType_GenericAlloc()}

@item 
@ref{51e6,,tp_alloc}
@end itemize

@end deffn

@geindex PyUnstable_Object_GC_NewWithExtraData (C function)
@anchor{c-api/gcsupport c PyUnstable_Object_GC_NewWithExtraData}@anchor{1cab}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyUnstable_Object_GC_NewWithExtraData (PyTypeObject *type, size_t extra_size)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Analogous to @ref{e68,,PyObject_GC_New} but allocates `extra_size'
bytes at the end of the object (at offset
@ref{d4f,,tp_basicsize}).
The allocated memory is initialized to zeros,
except for the @ref{19b,,Python object header}.

The extra data will be deallocated with the object, but otherwise it is
not managed by Python.

Memory allocated by this function must be freed with
@ref{18a5,,PyObject_GC_Del()} (usually called via the object’s
@ref{51e5,,tp_free} slot).

@cartouche
@quotation Προειδοποίηση 
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{492d,,PyVarObject} and @ref{25b0,,tp_itemsize}
instead.
@end quotation
@end cartouche


Added in version 3.12.

@end deffn

@geindex PyObject_GC_Resize (C macro)
@anchor{c-api/gcsupport c PyObject_GC_Resize}@anchor{1cb0}
@deffn {C Μακροεντολή} PyObject_GC_Resize (TYPE, op, newsize)

Resize an object allocated by @ref{d4e,,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{492d,,PyVarObject}*
and must not be tracked by the collector yet.
`newsize' must be of type @ref{e24,,Py_ssize_t}.
@end deffn

@geindex PyObject_GC_Track (C function)
@anchor{c-api/gcsupport c PyObject_GC_Track}@anchor{18a6}
@deffn {C Συνάρτηση} void PyObject_GC_Track (PyObject *op)
` Μέρος του @ref{95c,,Σταθερό 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{36b,,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{d4c}
@deffn {C Συνάρτηση} 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{d3e}
@deffn {C Συνάρτηση} int PyObject_GC_IsTracked (PyObject *op)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{16b2,,gc.is_tracked()}.


Added in version 3.9.

@end deffn

@geindex PyObject_GC_IsFinalized (C function)
@anchor{c-api/gcsupport c PyObject_GC_IsFinalized}@anchor{d3f}
@deffn {C Συνάρτηση} int PyObject_GC_IsFinalized (PyObject *op)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 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{ccd,,gc.is_finalized()}.


Added in version 3.9.

@end deffn

@geindex PyObject_GC_Del (C function)
@anchor{c-api/gcsupport c PyObject_GC_Del}@anchor{18a5}
@deffn {C Συνάρτηση} void PyObject_GC_Del (void *op)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Releases memory allocated to an object using @ref{e68,,PyObject_GC_New} or
@ref{e69,,PyObject_GC_NewVar}.

Do not call this directly to free an object’s memory; call the type’s
@ref{51e5,,tp_free} slot instead.

Do not use this for memory allocated by @ref{d4d,,PyObject_New},
@ref{d4e,,PyObject_NewVar}, or related allocation functions; use
@ref{1023,,PyObject_Free()} instead.


@subsubheading Δείτε επίσης



@itemize *

@item 
@ref{1023,,PyObject_Free()} is the non-GC equivalent of this function.

@item 
@ref{e68,,PyObject_GC_New}

@item 
@ref{e69,,PyObject_GC_NewVar}

@item 
@ref{e30,,PyType_GenericAlloc()}

@item 
@ref{51e5,,tp_free}
@end itemize

@end deffn

@geindex PyObject_GC_UnTrack (C function)
@anchor{c-api/gcsupport c PyObject_GC_UnTrack}@anchor{18a7}
@deffn {C Συνάρτηση} void PyObject_GC_UnTrack (void *op)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Remove the object `op' from the set of container objects tracked by the
collector.  Note that @ref{18a6,,PyObject_GC_Track()} can be called again on
this object to add it back to the set of tracked objects.  The deallocator
(@ref{51d3,,tp_dealloc} handler) should call this for the object before any of
the fields used by the @ref{36b,,tp_traverse} handler become invalid.
@end deffn


Άλλαξε στην έκδοση 3.8: The @code{_PyObject_GC_TRACK()} and @code{_PyObject_GC_UNTRACK()} macros
have been removed from the public C API.


The @ref{36b,,tp_traverse} handler accepts a function parameter of this type:

@geindex visitproc (C type)
@anchor{c-api/gcsupport c visitproc}@anchor{5505}
@deffn {C Τύπος} typedef int (*visitproc)(@ref{19b,,PyObject} *object, void *arg)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Type of the visitor function passed to the @ref{36b,,tp_traverse} handler.
The function should be called with an object to traverse as `object' and
the third parameter to the @code{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{51f7,,tp_clear} handler must be of the @ref{54f4,,inquiry} type, or @code{NULL}
if the object is immutable.

@geindex inquiry (C type)
@anchor{c-api/gcsupport c inquiry}@anchor{54f4}
@deffn {C Τύπος} typedef int (*inquiry)(@ref{19b,,PyObject} *self)
` Μέρος του @ref{95c,,Σταθερό 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{975,,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
* Traversal:: 
* Controlling the Garbage Collector State:: 
* Querying Garbage Collector State:: 

@end menu

@node Traversal,Controlling the Garbage Collector State,,Supporting Cyclic Garbage Collection
@anchor{c-api/gcsupport gc-traversal}@anchor{59f3}@anchor{c-api/gcsupport traversal}@anchor{5a00}
@subsubsection Traversal


The @ref{36b,,tp_traverse} handler must have the following type:

@geindex traverseproc (C type)
@anchor{c-api/gcsupport c traverseproc}@anchor{5503}
@deffn {C Τύπος} typedef int (*traverseproc)(@ref{19b,,PyObject} *self, @ref{5505,,visitproc} visit, void *arg)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Traversal function for a garbage-collected object, used by the garbage
collector to detect reference cycles.
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.

A typical @code{tp_traverse} function calls the @ref{51ee,,Py_VISIT()}
convenience macro on each of the instance’s members that are Python
objects that the instance owns.
For example, this is a (slightly outdated) traversal function for
the @ref{1a87,,threading.local} class:

@example
static int
local_traverse(PyObject *op, visitproc visit, void *arg)
@{
    localobject *self = (localobject *) op;
    Py_VISIT(Py_TYPE(self));
    Py_VISIT(self->args);
    Py_VISIT(self->kw);
    Py_VISIT(self->dict);
    return 0;
@}
@end example

@cartouche
@quotation Σημείωση 
@ref{51ee,,Py_VISIT()} requires the `visit' and `arg' parameters to
@code{local_traverse()} to have these specific names; don’t name them just
anything.
@end quotation
@end cartouche

Instances of @ref{d2f,,heap-allocated types} hold a reference to
their type. Their traversal function must therefore visit the type:

@example
Py_VISIT(Py_TYPE(self));
@end example

Alternately, the type may delegate this responsibility by
calling @code{tp_traverse} of a heap-allocated superclass (or another
heap-allocated type, if applicable).
If they do not, the type object may not be garbage-collected.

If the @ref{39c,,Py_TPFLAGS_MANAGED_DICT} bit is set in the
@ref{1e68,,tp_flags} field, the traverse function must call
@ref{803,,PyObject_VisitManagedDict()} like this:

@example
int err = PyObject_VisitManagedDict((PyObject*)self, visit, arg);
if (err) @{
    return err;
@}
@end example

Only the members that the instance `owns' (by having
@ref{7da,,strong references} to them) must be
visited. For instance, if an object supports weak references via the
@ref{5650,,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 traversal function has a limitation:

@cartouche
@quotation Προειδοποίηση 
The traversal function must not have any side effects.  Implementations
may not modify the reference counts of any Python objects nor create or
destroy any Python objects, directly or indirectly.
@end quotation
@end cartouche

This means that `most' Python C API functions may not be used, since
they can raise a new exception, return a new reference to a result object,
have internal logic that uses side effects.
Also, unless documented otherwise, functions that happen to not have side
effects may start having them in future versions, without warning.

For a list of safe functions, see a
@ref{5a01,,separate section} below.

@cartouche
@quotation Σημείωση 
The @ref{51ee,,Py_VISIT()} call may be skipped for those members that provably
cannot participate in reference cycles.
In the @code{local_traverse} example above, there is also a @code{self->key}
member, but 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{63,,gc}
module’s @ref{bdf,,get_referents()} function will include it.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
The @ref{36b,,tp_traverse} function can be called from any
thread.

`Λεπτομέρεια υλοποίησης CPython:' Garbage collection is a «stop-the-world» operation:
even in @ref{487,,free threading} builds, only one thread state is
@ref{1a1,,attached} when @code{tp_traverse}
handlers run.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 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.

@end deffn

To simplify writing @ref{36b,,tp_traverse} handlers,
a @ref{51ee,,Py_VISIT()} macro is provided.
In order to use this macro, the @code{tp_traverse}
implementation must name its arguments exactly `visit' and `arg':

@geindex Py_VISIT (C macro)
@anchor{c-api/gcsupport c Py_VISIT}@anchor{51ee}
@deffn {C Μακροεντολή} Py_VISIT (o)

If the @ref{19b,,PyObject}* `o' is not @code{NULL}, call the `visit'
callback, with arguments `o' and `arg'.
If `visit' returns a non-zero value, then return it.

This corresponds roughly to:

@example
#define Py_VISIT(o)                             \
   if (op) @{                                    \
      int visit_result = visit(o, arg);         \
      if (visit_result != 0) @{                  \
         return visit_result;                   \
      @}                                         \
   @}
@end example
@end deffn

@menu
* Traversal-safe functions:: 
* «DuringGC» functions:: 

@end menu

@node Traversal-safe functions,«DuringGC» functions,,Traversal
@anchor{c-api/gcsupport traversal-safe-functions}@anchor{5a02}
@subsubsection Traversal-safe functions


The following functions and macros are safe to use in a
@ref{36b,,tp_traverse} handler:


@itemize *

@item 
the `visit' function passed to @code{tp_traverse}

@item 
@ref{51ee,,Py_VISIT()}

@item 
@ref{b61,,Py_SIZE()}

@item 
@ref{5f5,,Py_TYPE()}: if called from a @code{tp_traverse} handler,
@code{Py_TYPE()}”s result will be valid for the duration of the handler call

@item 
@ref{803,,PyObject_VisitManagedDict()}

@item 
@ref{1eab,,PyObject_TypeCheck()}, @ref{541a,,PyType_IsSubtype()},
@ref{1f30,,PyType_HasFeature()}

@item 
@code{Py@var{<type>}_Check} and @code{Py@var{<type>}_CheckExact} – for example,
@ref{56ef,,PyTuple_Check()}

@item 
@ref{5a01,,«DuringGC» functions}
@end itemize

@node «DuringGC» functions,,Traversal-safe functions,Traversal
@anchor{c-api/gcsupport duringgc-functions}@anchor{5a01}@anchor{c-api/gcsupport id1}@anchor{5a03}
@subsubsection «DuringGC» functions


The following functions should `only' be used in a
@ref{36b,,tp_traverse} handler; calling them in other
contexts may have unintended consequences.

These functions act like their counterparts without the @code{_DuringGC} suffix,
but they are guaranteed to not have side effects, they do not set an exception
on failure, and they return/set @ref{603,,borrowed references}
as detailed in the individual documentation.

Note that these functions may fail (return @code{NULL} or @code{-1}),
but as they do not set an exception, no error information is available.
In some cases, failure is not distinguishable from a successful @code{NULL} result.

@geindex PyObject_GetTypeData_DuringGC (C function)
@geindex PyObject_GetItemData_DuringGC (C function)
@geindex PyType_GetModuleState_DuringGC (C function)
@geindex PyModule_GetState_DuringGC (C function)
@geindex PyModule_GetToken_DuringGC (C function)
@anchor{c-api/gcsupport c PyObject_GetTypeData_DuringGC}@anchor{36c}
@deffn {C Συνάρτηση} void *PyObject_GetTypeData_DuringGC (PyObject *o, PyTypeObject *cls)
@anchor{c-api/gcsupport c PyObject_GetItemData_DuringGC}@anchor{36d}
@deffnx {C Συνάρτηση} void *PyObject_GetItemData_DuringGC (PyObject *o)
@anchor{c-api/gcsupport c PyType_GetModuleState_DuringGC}@anchor{36e}
@deffnx {C Συνάρτηση} void *PyType_GetModuleState_DuringGC (PyTypeObject *type)
@anchor{c-api/gcsupport c PyModule_GetState_DuringGC}@anchor{36f}
@deffnx {C Συνάρτηση} void *PyModule_GetState_DuringGC (PyObject *module)
@anchor{c-api/gcsupport c PyModule_GetToken_DuringGC}@anchor{370}
@deffnx {C Συνάρτηση} int PyModule_GetToken_DuringGC (PyObject *module, void **result)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
See @ref{5a01,,«DuringGC» functions} for common information.


Added in version 3.15.



@subsubheading Δείτε επίσης


@ref{19a,,PyObject_GetTypeData()},
@ref{957,,PyObject_GetItemData()},
@ref{d38,,PyType_GetModuleState()},
@ref{d48,,PyModule_GetState()},
@ref{5397,,PyModule_GetToken()},
@ref{5dd,,PyType_GetBaseByToken()}

@end deffn

@geindex PyType_GetBaseByToken_DuringGC (C function)
@anchor{c-api/gcsupport c PyType_GetBaseByToken_DuringGC}@anchor{371}
@deffn {C Συνάρτηση} int PyType_GetBaseByToken_DuringGC (PyTypeObject *type, void *tp_token, PyTypeObject **result)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
See @ref{5a01,,«DuringGC» functions} for common information.

Sets `*result' to a @ref{603,,borrowed reference} rather than a strong one.
The reference is valid for the duration
of the @code{tp_traverse} handler call.


Added in version 3.15.



@subsubheading Δείτε επίσης


@ref{5dd,,PyType_GetBaseByToken()}

@end deffn

@geindex PyType_GetModule_DuringGC (C function)
@geindex PyType_GetModuleByToken_DuringGC (C function)
@anchor{c-api/gcsupport c PyType_GetModule_DuringGC}@anchor{372}
@deffn {C Συνάρτηση} @ref{19b,,PyObject} *PyType_GetModule_DuringGC (PyTypeObject *type)
@anchor{c-api/gcsupport c PyType_GetModuleByToken_DuringGC}@anchor{373}
@deffnx {C Συνάρτηση} @ref{19b,,PyObject} *PyType_GetModuleByToken_DuringGC (PyTypeObject *type, const void *mod_token)
`Επιστρεφόμενη τιμή: Borrowed reference.'` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.15.'
See @ref{5a01,,«DuringGC» functions} for common information.

These functions return a @ref{603,,borrowed reference}, which is
valid for the duration of the @code{tp_traverse} handler call.


Added in version 3.15.



@subsubheading Δείτε επίσης


@ref{d37,,PyType_GetModule()},
@ref{5419,,PyType_GetModuleByToken()}

@end deffn

@node Controlling the Garbage Collector State,Querying Garbage Collector State,Traversal,Supporting Cyclic Garbage Collection
@anchor{c-api/gcsupport controlling-the-garbage-collector-state}@anchor{5a04}
@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{d56}
@deffn {C Συνάρτηση} @ref{e24,,Py_ssize_t} PyGC_Collect (void)
` Μέρος του @ref{95c,,Σταθερό ABI}.'
Perform a full garbage collection, if the garbage collector is enabled.
(Note that @ref{44f,,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{70c,,sys.unraisablehook}.
This function does not raise exceptions.
@end deffn

@geindex PyGC_Enable (C function)
@anchor{c-api/gcsupport c PyGC_Enable}@anchor{c7a}
@deffn {C Συνάρτηση} int PyGC_Enable (void)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Enable the garbage collector: similar to @ref{4ceb,,gc.enable()}.
Returns the previous state, 0 for disabled and 1 for enabled.


Added in version 3.10.

@end deffn

@geindex PyGC_Disable (C function)
@anchor{c-api/gcsupport c PyGC_Disable}@anchor{c7b}
@deffn {C Συνάρτηση} int PyGC_Disable (void)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Disable the garbage collector: similar to @ref{4cec,,gc.disable()}.
Returns the previous state, 0 for disabled and 1 for enabled.


Added in version 3.10.

@end deffn

@geindex PyGC_IsEnabled (C function)
@anchor{c-api/gcsupport c PyGC_IsEnabled}@anchor{c7c}
@deffn {C Συνάρτηση} int PyGC_IsEnabled (void)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.10.'
Query the state of the garbage collector: similar to @ref{4ced,,gc.isenabled()}.
Returns the current state, 0 for disabled and 1 for enabled.


Added in 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{5a05}
@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{5a06}
@deffn {C Συνάρτηση} void PyUnstable_GC_VisitObjects (gcvisitobjects_t callback, void *arg)

@cartouche
@quotation Αυτό είναι Ασταθές API. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις. `Αυτό είναι @ref{954,,Ασταθές API}. Μπορεί να αλλάξει χωρίς προειδοποίηση σε μικρές εκδόσεις.'
@end quotation
@end cartouche

Run supplied `callback' on all live GC-capable objects. `arg' is passed through to
all invocations of `callback'.

@cartouche
@quotation Προειδοποίηση 
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


Added in version 3.12.

@end deffn

@geindex gcvisitobjects_t (C type)
@anchor{c-api/gcsupport c gcvisitobjects_t}@anchor{5a07}
@deffn {C Τύπος} typedef int (*gcvisitobjects_t)(@ref{19b,,PyObject} *object, void *arg)

Type of the visitor function to be passed to @ref{5a06,,PyUnstable_GC_VisitObjects()}.
`arg' is the same as the `arg' passed to @code{PyUnstable_GC_VisitObjects}.
Return @code{1} to continue iteration, return @code{0} to stop iteration. Other return
values are reserved for now so behavior on returning anything else is undefined.


Added in version 3.12.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node API and ABI Versioning,Monitoring C API,Object Implementation Support,Python/C API reference manual
@anchor{c-api/apiabiversion doc}@anchor{5a08}@anchor{c-api/apiabiversion api-and-abi-versioning}@anchor{5a09}@anchor{c-api/apiabiversion apiabiversion}@anchor{4c05}@anchor{c-api/apiabiversion translation-repo}@anchor{5a0a}
@section API and ABI Versioning


@menu
* Build-time version constants:: 
* Run-time version:: 
* Bit-packing macros:: 

@end menu

@node Build-time version constants,Run-time version,,API and ABI Versioning
@anchor{c-api/apiabiversion build-time-version-constants}@anchor{5a0b}
@subsection Build-time version constants


CPython exposes its version number in the following macros.
Note that these correspond to the version code is `built' with.
See @ref{5ae,,Py_Version} for the version used at `run time'.

See @ref{95c,,C API and ABI Stability} for a discussion of API and ABI stability across versions.

@geindex PY_MAJOR_VERSION (C macro)
@anchor{c-api/apiabiversion c PY_MAJOR_VERSION}@anchor{5a0c}
@deffn {C Μακροεντολή} PY_MAJOR_VERSION

The @code{3} in @code{3.4.1a2}.
@end deffn

@geindex PY_MINOR_VERSION (C macro)
@anchor{c-api/apiabiversion c PY_MINOR_VERSION}@anchor{5a0d}
@deffn {C Μακροεντολή} PY_MINOR_VERSION

The @code{4} in @code{3.4.1a2}.
@end deffn

@geindex PY_MICRO_VERSION (C macro)
@anchor{c-api/apiabiversion c PY_MICRO_VERSION}@anchor{5a0e}
@deffn {C Μακροεντολή} PY_MICRO_VERSION

The @code{1} in @code{3.4.1a2}.
@end deffn

@geindex PY_RELEASE_LEVEL (C macro)
@anchor{c-api/apiabiversion c PY_RELEASE_LEVEL}@anchor{5a0f}
@deffn {C Μακροεντολή} 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.

@geindex PY_RELEASE_LEVEL_ALPHA (C macro)

@geindex PY_RELEASE_LEVEL_BETA (C macro)

@geindex PY_RELEASE_LEVEL_GAMMA (C macro)

@geindex PY_RELEASE_LEVEL_FINAL (C macro)
@anchor{c-api/apiabiversion c PY_RELEASE_LEVEL_ALPHA}@anchor{5a10}@anchor{c-api/apiabiversion c PY_RELEASE_LEVEL_BETA}@anchor{5a11}@anchor{c-api/apiabiversion c PY_RELEASE_LEVEL_GAMMA}@anchor{5a12}@anchor{c-api/apiabiversion c PY_RELEASE_LEVEL_FINAL}@anchor{5a13}
For completeness, the values are available as macros:
@code{PY_RELEASE_LEVEL_ALPHA} (@code{0xA}),
@code{PY_RELEASE_LEVEL_BETA} (@code{0xB}),
@code{PY_RELEASE_LEVEL_GAMMA} (@code{0xC}), and
@code{PY_RELEASE_LEVEL_FINAL} (@code{0xF}).
@end deffn

@geindex PY_RELEASE_SERIAL (C macro)
@anchor{c-api/apiabiversion c PY_RELEASE_SERIAL}@anchor{5a14}
@deffn {C Μακροεντολή} PY_RELEASE_SERIAL

The @code{2} in @code{3.4.1a2}. Zero for final releases.
@end deffn

@geindex PY_VERSION_HEX (C macro)
@anchor{c-api/apiabiversion c PY_VERSION_HEX}@anchor{5af}
@deffn {C Μακροεντολή} PY_VERSION_HEX

The Python version number encoded in a single integer.
See @ref{5ad,,Py_PACK_FULL_VERSION()} for the encoding details.

Use this for numeric comparisons, for example,
@code{#if PY_VERSION_HEX >= ...}.
@end deffn

@geindex PY_VERSION (C macro)
@anchor{c-api/apiabiversion c PY_VERSION}@anchor{5a15}
@deffn {C Μακροεντολή} PY_VERSION

The Python version as a string, for example, @code{"3.4.1a2"}.
@end deffn

These macros are defined in Include/patchlevel.h@footnote{https://github.com/python/cpython/tree/main/Include/patchlevel.h}.

@node Run-time version,Bit-packing macros,Build-time version constants,API and ABI Versioning
@anchor{c-api/apiabiversion run-time-version}@anchor{5a16}
@subsection Run-time version


@geindex Py_Version (C var)
@anchor{c-api/apiabiversion c Py_Version}@anchor{5ae}
@deffn {C Μεταβλητή} const unsigned long Py_Version
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.11.'
The Python runtime version number encoded in a single constant integer.
See @ref{5ad,,Py_PACK_FULL_VERSION()} for the encoding details.
This contains the Python version used at run time.

Use this for numeric comparisons, for example, @code{if (Py_Version >= ...)}.


Added in version 3.11.

@end deffn

@node Bit-packing macros,,Run-time version,API and ABI Versioning
@anchor{c-api/apiabiversion bit-packing-macros}@anchor{5a17}
@subsection Bit-packing macros


@geindex Py_PACK_FULL_VERSION (C function)
@anchor{c-api/apiabiversion c Py_PACK_FULL_VERSION}@anchor{5ad}
@deffn {C Συνάρτηση} uint32_t Py_PACK_FULL_VERSION (int major, int minor, int micro, int release_level, int release_serial)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
Return the given version, encoded as a single 32-bit integer with
the following structure:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

Argument

@tab

No.
of
bits

@tab

Bit mask

@tab

Bit shift

@tab

Example values

@tab

@item

@code{3.4.1a2}

@tab

@code{3.10.0}

@item

`major'

@tab

8

@tab

@code{0xFF000000}

@tab

24

@tab

@code{0x03}

@tab

@code{0x03}

@item

`minor'

@tab

8

@tab

@code{0x00FF0000}

@tab

16

@tab

@code{0x04}

@tab

@code{0x0A}

@item

`micro'

@tab

8

@tab

@code{0x0000FF00}

@tab

8

@tab

@code{0x01}

@tab

@code{0x00}

@item

`release_level'

@tab

4

@tab

@code{0x000000F0}

@tab

4

@tab

@code{0xA}

@tab

@code{0xF}

@item

`release_serial'

@tab

4

@tab

@code{0x0000000F}

@tab

0

@tab

@code{0x2}

@tab

@code{0x0}

@end multitable


For example:


@multitable {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxx} 
@headitem

Version

@tab

@code{Py_PACK_FULL_VERSION} arguments

@tab

Encoded version

@item

@code{3.4.1a2}

@tab

@code{(3, 4, 1, 0xA, 2)}

@tab

@code{0x030401a2}

@item

@code{3.10.0}

@tab

@code{(3, 10, 0, 0xF, 0)}

@tab

@code{0x030a00f0}

@end multitable


Out-of range bits in the arguments are ignored.
That is, the macro can be defined as:

@example
#ifndef Py_PACK_FULL_VERSION
#define Py_PACK_FULL_VERSION(X, Y, Z, LEVEL, SERIAL) ( \
   (((X) & 0xff) << 24) |                              \
   (((Y) & 0xff) << 16) |                              \
   (((Z) & 0xff) << 8) |                               \
   (((LEVEL) & 0xf) << 4) |                            \
   (((SERIAL) & 0xf) << 0))
#endif
@end example

@code{Py_PACK_FULL_VERSION} is primarily a macro, intended for use in
@code{#if} directives, but it is also available as an exported function.


Added in version 3.14.

@end deffn

@geindex Py_PACK_VERSION (C function)
@anchor{c-api/apiabiversion c Py_PACK_VERSION}@anchor{5ac}
@deffn {C Συνάρτηση} uint32_t Py_PACK_VERSION (int major, int minor)
` Μέρος του @ref{95c,,Σταθερό ABI} από την έκδοση 3.14.'
Equivalent to @code{Py_PACK_FULL_VERSION(major, minor, 0, 0, 0)}.
The result does not correspond to any Python release, but is useful
in numeric comparisons.


Added in version 3.14.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Monitoring C API,Generating Execution Events,API and ABI Versioning,Python/C API reference manual
@anchor{c-api/monitoring doc}@anchor{5a18}@anchor{c-api/monitoring c-api-monitoring}@anchor{694}@anchor{c-api/monitoring monitoring-c-api}@anchor{5a19}@anchor{c-api/monitoring translation-repo}@anchor{5a1a}
@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{e3,,sys.monitoring}.

@node Generating Execution Events,,Monitoring C API,Python/C API reference manual
@anchor{c-api/monitoring generating-execution-events}@anchor{5a1b}
@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{e3,,sys.monitoring}
for details about the signatures of the different event callbacks).
The @code{codelike} argument should be an instance of @ref{2e1,,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{7b7}
@deffn {C Τύπος} 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{e3,,sys.monitoring} for descriptions of the events.

@geindex PyMonitoring_FirePyStartEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyStartEvent}@anchor{7b8}
@deffn {C Συνάρτηση} 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{7b9}
@deffn {C Συνάρτηση} 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{7ba}
@deffn {C Συνάρτηση} 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{7bb}
@deffn {C Συνάρτηση} 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{7bc}
@deffn {C Συνάρτηση} 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{7bd}
@deffn {C Συνάρτηση} 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{7be}
@deffn {C Συνάρτηση} int PyMonitoring_FireJumpEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

Fire a @code{JUMP} event.
@end deffn

@geindex PyMonitoring_FireBranchLeftEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireBranchLeftEvent}@anchor{5da}
@deffn {C Συνάρτηση} int PyMonitoring_FireBranchLeftEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

Fire a @code{BRANCH_LEFT} event.
@end deffn

@geindex PyMonitoring_FireBranchRightEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireBranchRightEvent}@anchor{5db}
@deffn {C Συνάρτηση} int PyMonitoring_FireBranchRightEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

Fire a @code{BRANCH_RIGHT} event.
@end deffn

@geindex PyMonitoring_FireCReturnEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireCReturnEvent}@anchor{7bf}
@deffn {C Συνάρτηση} 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{7c0}
@deffn {C Συνάρτηση} int PyMonitoring_FirePyThrowEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire a @code{PY_THROW} event with the current exception (as returned by
@ref{63c,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireRaiseEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireRaiseEvent}@anchor{7c1}
@deffn {C Συνάρτηση} int PyMonitoring_FireRaiseEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire a @code{RAISE} event with the current exception (as returned by
@ref{63c,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireCRaiseEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireCRaiseEvent}@anchor{7c2}
@deffn {C Συνάρτηση} int PyMonitoring_FireCRaiseEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire a @code{C_RAISE} event with the current exception (as returned by
@ref{63c,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireReraiseEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireReraiseEvent}@anchor{7c3}
@deffn {C Συνάρτηση} int PyMonitoring_FireReraiseEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire a @code{RERAISE} event with the current exception (as returned by
@ref{63c,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireExceptionHandledEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireExceptionHandledEvent}@anchor{7c4}
@deffn {C Συνάρτηση} int PyMonitoring_FireExceptionHandledEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire an @code{EXCEPTION_HANDLED} event with the current exception (as returned by
@ref{63c,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FirePyUnwindEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyUnwindEvent}@anchor{7c5}
@deffn {C Συνάρτηση} int PyMonitoring_FirePyUnwindEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire a @code{PY_UNWIND} event with the current exception (as returned by
@ref{63c,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireStopIterationEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireStopIterationEvent}@anchor{7c6}
@deffn {C Συνάρτηση} 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{fba,,StopIteration}, it is used. Otherwise,
a new @code{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{5a1c}
@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{7c7}
@deffn {C Συνάρτηση} 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

Event

@item

@geindex PY_MONITORING_EVENT_BRANCH_LEFT (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_BRANCH_LEFT}@anchor{5a1d}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_BRANCH_LEFT
@end deffn

@tab

@ref{51b,,BRANCH_LEFT}

@item

@geindex PY_MONITORING_EVENT_BRANCH_RIGHT (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_BRANCH_RIGHT}@anchor{5a1e}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_BRANCH_RIGHT
@end deffn

@tab

@ref{51c,,BRANCH_RIGHT}

@item

@geindex PY_MONITORING_EVENT_CALL (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_CALL}@anchor{5a1f}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_CALL
@end deffn

@tab

@ref{1bc7,,CALL}

@item

@geindex PY_MONITORING_EVENT_C_RAISE (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_C_RAISE}@anchor{5a20}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_C_RAISE
@end deffn

@tab

@ref{4c1e,,C_RAISE}

@item

@geindex PY_MONITORING_EVENT_C_RETURN (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_C_RETURN}@anchor{5a21}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_C_RETURN
@end deffn

@tab

@ref{4c1f,,C_RETURN}

@item

@geindex PY_MONITORING_EVENT_EXCEPTION_HANDLED (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_EXCEPTION_HANDLED}@anchor{5a22}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_EXCEPTION_HANDLED
@end deffn

@tab

@ref{274,,EXCEPTION_HANDLED}

@item

@geindex PY_MONITORING_EVENT_INSTRUCTION (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_INSTRUCTION}@anchor{5a23}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_INSTRUCTION
@end deffn

@tab

@ref{4c20,,INSTRUCTION}

@item

@geindex PY_MONITORING_EVENT_JUMP (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_JUMP}@anchor{5a24}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_JUMP
@end deffn

@tab

@ref{4c21,,JUMP}

@item

@geindex PY_MONITORING_EVENT_LINE (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_LINE}@anchor{5a25}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_LINE
@end deffn

@tab

@ref{4c22,,LINE}

@item

@geindex PY_MONITORING_EVENT_PY_RESUME (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_RESUME}@anchor{5a26}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_PY_RESUME
@end deffn

@tab

@ref{4c23,,PY_RESUME}

@item

@geindex PY_MONITORING_EVENT_PY_RETURN (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_RETURN}@anchor{5a27}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_PY_RETURN
@end deffn

@tab

@ref{4c24,,PY_RETURN}

@item

@geindex PY_MONITORING_EVENT_PY_START (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_START}@anchor{5a28}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_PY_START
@end deffn

@tab

@ref{4c25,,PY_START}

@item

@geindex PY_MONITORING_EVENT_PY_THROW (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_THROW}@anchor{5a29}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_PY_THROW
@end deffn

@tab

@ref{271,,PY_THROW}

@item

@geindex PY_MONITORING_EVENT_PY_UNWIND (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_UNWIND}@anchor{5a2a}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_PY_UNWIND
@end deffn

@tab

@ref{272,,PY_UNWIND}

@item

@geindex PY_MONITORING_EVENT_PY_YIELD (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_YIELD}@anchor{5a2b}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_PY_YIELD
@end deffn

@tab

@ref{4c26,,PY_YIELD}

@item

@geindex PY_MONITORING_EVENT_RAISE (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_RAISE}@anchor{5a2c}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_RAISE
@end deffn

@tab

@ref{273,,RAISE}

@item

@geindex PY_MONITORING_EVENT_RERAISE (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_RERAISE}@anchor{5a2d}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_RERAISE
@end deffn

@tab

@ref{275,,RERAISE}

@item

@geindex PY_MONITORING_EVENT_STOP_ITERATION (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_STOP_ITERATION}@anchor{5a2e}
@deffn {C Μακροεντολή} PY_MONITORING_EVENT_STOP_ITERATION
@end deffn

@tab

@ref{4c27,,STOP_ITERATION}

@end multitable

@end deffn

@geindex PyMonitoring_ExitScope (C function)
@anchor{c-api/monitoring c PyMonitoring_ExitScope}@anchor{7c8}
@deffn {C Συνάρτηση} int PyMonitoring_ExitScope (void)

Exit the last scope that was entered with @code{PyMonitoring_EnterScope()}.
@end deffn

@geindex PY_MONITORING_IS_INSTRUMENTED_EVENT (C function)
@anchor{c-api/monitoring c PY_MONITORING_IS_INSTRUMENTED_EVENT}@anchor{5a2f}
@deffn {C Συνάρτηση} int PY_MONITORING_IS_INSTRUMENTED_EVENT (uint8_t ev)

Return true if the event corresponding to the event ID `ev' is
a @ref{4c2b,,local event}.


Added in version 3.13.



@ref{1a7,,Soft deprecated} since version 3.14.

@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Installing Python modules,Python HOWTOs,Python/C API reference manual,Top
@anchor{installing/index doc}@anchor{5a30}@anchor{installing/index installing-index}@anchor{12a6}@anchor{installing/index installing-python-modules}@anchor{5a31}@anchor{installing/index translation-repo}@anchor{5a32}
@chapter Installing Python modules


As a popular open source development project, Python has an active
supporting community of contributors and users that also make their software
available for other Python developers to use under open-source license terms.

This allows Python users to share and collaborate effectively, benefiting
from the solutions others have already created to common (and sometimes
even rare!) problems, as well as potentially contributing their own
solutions to the common pool.

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 Σημείωση 
For corporate and other institutional users, be aware that many
organisations have their own policies around using and contributing to
open source software. Please take such policies into account when making
use of the distribution and installation tools provided with Python.
@end quotation
@end cartouche

@menu
* Key terms:: 
* Basic usage: Basic usage<2>. 
* How do I …?:: 
* Common installation issues:: 

@end menu

@node Key terms,Basic usage<2>,,Installing Python modules
@anchor{installing/index key-terms}@anchor{5a33}
@section Key terms



@itemize *

@item 
@code{pip} is the preferred installer program. It
is included by default with the Python binary installers.

@item 
A `virtual environment' is a semi-isolated Python environment that allows
packages to be installed for use by a particular application, rather than
being installed system wide.

@item 
@code{venv} is the standard tool for creating virtual environments.
It defaults to installing @code{pip} into all created virtual environments.

@item 
@code{virtualenv} is a third-party alternative (and predecessor) to
@code{venv}.

@item 
The Python Package Index (PyPI)@footnote{https://pypi.org} is a public
repository of open source licensed packages made available for use by
other Python users.

@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}.
@end itemize


Άλλαξε στην έκδοση 3.5: The use of @code{venv} is now recommended for creating virtual environments.



@subsubheading Δείτε επίσης


Python Packaging User Guide: Creating and using virtual environments@footnote{https://packaging.python.org/installing/#creating-virtual-environments}


@node Basic usage<2>,How do I …?,Key terms,Installing Python modules
@anchor{installing/index basic-usage}@anchor{5a34}
@section Basic usage


The standard packaging tools are all designed to be used from the command
line.

The following command will install the latest version of a module and its
dependencies from PyPI:

@example
python -m pip install SomePackage
@end example

@cartouche
@quotation Σημείωση 
For POSIX users (including macOS and Linux users), the examples in
this guide assume the use of a @ref{22dd,,virtual environment}.

For Windows users, the examples in this guide assume that the option to
adjust the system PATH environment variable was selected when installing
Python.
@end quotation
@end cartouche

It’s also possible to specify an exact or minimum version directly on the
command line. When using comparator operators such as @code{>}, @code{<} or some other
special character which get interpreted by shell, the package name and the
version should be enclosed within double quotes:

@example
python -m pip install SomePackage==1.0.4    # specific version
python -m pip install "SomePackage>=1.0.4"  # minimum version
@end example

Normally, if a suitable module is already installed, attempting to install
it again will have no effect. Upgrading existing modules must be requested
explicitly:

@example
python -m pip install --upgrade SomePackage
@end example

More information and resources regarding @code{pip} and its capabilities can be
found in the Python Packaging User Guide@footnote{https://packaging.python.org}.

Creation of virtual environments is done through the @ref{11a,,venv} module.
Installing packages into an active virtual environment uses the commands shown
above.


@subsubheading Δείτε επίσης


Python Packaging User Guide: Installing Python Distribution Packages@footnote{https://packaging.python.org/installing/}


@node How do I …?,Common installation issues,Basic usage<2>,Installing Python modules
@anchor{installing/index how-do-i}@anchor{5a35}
@section How do I …?


These are quick answers or links for some common tasks.

@c installing-per-user-installation:

@menu
* … install packages just for the current user?:: 
* … install scientific Python packages?:: 
* … work with multiple versions of Python installed in parallel?:: 

@end menu

@node … install packages just for the current user?,… install scientific Python packages?,,How do I …?
@anchor{installing/index install-packages-just-for-the-current-user}@anchor{5a36}
@subsection … install packages just for the current user?


Passing the @code{--user} option to @code{python -m pip install} will install a
package just for the current user, rather than for all users of the system.

@node … install scientific Python packages?,… work with multiple versions of Python installed in parallel?,… install packages just for the current user?,How do I …?
@anchor{installing/index install-scientific-python-packages}@anchor{5a37}
@subsection … install scientific Python packages?


A number of scientific Python packages have complex binary dependencies, and
aren’t currently easy to install using @code{pip} directly.
It will often be easier for users to install these packages by
other means@footnote{https://packaging.python.org/science/}
rather than attempting to install them with @code{pip}.


@subsubheading Δείτε επίσης


Python Packaging User Guide: Installing Scientific Packages@footnote{https://packaging.python.org/science/}


@node … work with multiple versions of Python installed in parallel?,,… install scientific Python packages?,How do I …?
@anchor{installing/index work-with-multiple-versions-of-python-installed-in-parallel}@anchor{5a38}
@subsection … work with multiple versions of Python installed in parallel?


On Linux, macOS, and other POSIX systems, use the versioned Python commands
in combination with the @code{-m} switch to run the appropriate copy of
@code{pip}:

@example
python3    -m pip install SomePackage  # default Python 3
python3.14 -m pip install SomePackage  # specifically Python 3.14
@end example

Appropriately versioned @code{pip} commands may also be available.

On Windows, use the @code{py} Python launcher in combination with the @code{-m}
switch:

@example
py -3    -m pip install SomePackage  # default Python 3
py -3.14 -m pip install SomePackage  # specifically Python 3.14
@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/guides/index-mirrors-and-caches/)

@node Common installation issues,,How do I …?,Installing Python modules
@anchor{installing/index common-installation-issues}@anchor{5a39}
@section Common installation issues


@menu
* Installing into the system Python on Linux:: 
* Pip not installed:: 
* Installing binary extensions:: 

@end menu

@node Installing into the system Python on Linux,Pip not installed,,Common installation issues
@anchor{installing/index installing-into-the-system-python-on-linux}@anchor{5a3a}
@subsection Installing into the system Python on Linux


On Linux systems, a Python installation will typically be included as part
of the distribution. Installing into this Python installation requires
root access to the system, and may interfere with the operation of the
system package manager and other components of the system if a component
is unexpectedly upgraded using @code{pip}.

On such systems, it is often better to use a virtual environment or a
per-user installation when installing packages with @code{pip}.

@node Pip not installed,Installing binary extensions,Installing into the system Python on Linux,Common installation issues
@anchor{installing/index pip-not-installed}@anchor{5a3b}
@subsection Pip not installed


It is possible that @code{pip} does not get installed by default. One potential fix is:

@example
python -m ensurepip --default-pip
@end example

There are also additional resources for installing pip@footnote{https://packaging.python.org/en/latest/tutorials/installing-packages/#ensure-pip-setuptools-and-wheel-are-up-to-date}.

@node Installing binary extensions,,Pip not installed,Common installation issues
@anchor{installing/index installing-binary-extensions}@anchor{5a3c}
@subsection Installing binary extensions


Python once relied heavily on source-based distribution, with end
users being expected to compile extension modules from source as part of
the installation process.

With the introduction of the binary wheel format, and the
ability to publish wheels through PyPI, this problem is diminishing,
as users are more regularly able to install pre-built extensions rather
than needing to build them themselves.

Some of the solutions for installing scientific software@footnote{https://packaging.python.org/science/}
that are not yet available as pre-built wheel files may also help with
obtaining other binary extensions without needing to build them locally.


@subsubheading Δείτε επίσης


Python Packaging User Guide: Binary Extensions@footnote{https://packaging.python.org/extensions/}


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python HOWTOs,Συχνές Ερωτήσεις για την Python,Installing Python modules,Top
@anchor{howto/index doc}@anchor{5a3d}@anchor{howto/index how-tos}@anchor{5a3e}@anchor{howto/index python-howtos}@anchor{5a3f}@anchor{howto/index translation-repo}@anchor{5a40}
@chapter Python HOWTOs


Τα HOWTOs της Python είναι έγγραφα που καλύπτουν ένα συγκεκριμένο θέμα σε βάθος. Με πρότυπο τη συλλογή HOWTO του Linux Documentation Project, αυτή η συλλογή είναι μια προσπάθεια να προωθηθεί η τεκμηρίωση που είναι πιο λεπτομερής από την Αναφορά της Βιβλιοθήκης Python.

@menu
* A conceptual overview of asyncio:: 
* Porting Extension Modules to Python 3:: 
* Curses Programming with Python:: 
* Descriptor Guide:: 
* Debugging C API extensions and CPython Internals with GDB:: 
* Enum HOWTO:: 
* Functional Programming HOWTO:: 
* Logging HOWTO:: 
* Logging Cookbook:: 
* Regular expression HOWTO:: 
* Socket Programming HOWTO:: 
* Sorting Techniques:: 
* Unicode HOWTO:: 
* HOWTO Fetch Internet Resources Using The urllib Package:: 
* An introduction to the ipaddress module:: 
* Instrumenting CPython with DTrace and SystemTap:: 
* Python support for the perf map compatible profilers:: 
* Annotations Best Practices:: 
* Isolating Extension Modules:: 
* timer file descriptor HOWTO:: 
* The Python 2.3 Method Resolution Order: The Python 2 3 Method Resolution Order. 
* Python support for free threading:: 
* C API Extension Support for Free Threading:: 
* Remote debugging attachment protocol:: 
* Permission requirements:: 
* Locating the PyRuntime structure:: 
* Reading _Py_DebugOffsets:: 
* Locating the interpreter and thread state:: 
* Writing control information:: 
* Summary:: 
* Security and threat model:: 

@end menu

@node A conceptual overview of asyncio,Porting Extension Modules to Python 3,,Python HOWTOs
@anchor{howto/a-conceptual-overview-of-asyncio doc}@anchor{5a41}@anchor{howto/a-conceptual-overview-of-asyncio a-conceptual-overview-of-asyncio}@anchor{39fd}@anchor{howto/a-conceptual-overview-of-asyncio id1}@anchor{5a42}
@section A conceptual overview of @code{asyncio}


This @ref{5a3e,,HOWTO} article seeks to help you build a sturdy mental
model of how @ref{b,,asyncio} fundamentally works, helping you understand the
how and why behind the recommended patterns.

You might be curious about some key @code{asyncio} concepts.
By the end of this article, you’ll be able to comfortably answer these questions:


@itemize -

@item 
What’s happening behind the scenes when an object is awaited?

@item 
How does @code{asyncio} differentiate between a task which doesn’t need
CPU time (such as a network request or file read) as opposed to a task that
does (such as computing n-factorial)?

@item 
How to write an asynchronous variant of an operation, such as
an async sleep or database request.
@end itemize


@subsubheading Δείτε επίσης



@itemize *

@item 
The guide@footnote{https://github.com/anordin95/a-conceptual-overview-of-asyncio/tree/main} that inspired this HOWTO article, by Alexander Nordin.

@item 
This in-depth YouTube tutorial series@footnote{https://www.youtube.com/watch?v=Xbl7XjFYsN4&list=PLhNSoGM2ik6SIkVGXWBwerucXjgP1rHmB} on
@code{asyncio} created by Python core team member, Łukasz Langa.

@item 
500 Lines or Less: A Web Crawler With asyncio Coroutines@footnote{https://aosabook.org/en/500L/a-web-crawler-with-asyncio-coroutines.html} by A.
Jesse Jiryu Davis and Guido van Rossum.
@end itemize


@menu
* A conceptual overview part 1; the high-level: A conceptual overview part 1 the high-level. 
* A conceptual overview part 2; the nuts and bolts: A conceptual overview part 2 the nuts and bolts. 

@end menu

@node A conceptual overview part 1 the high-level,A conceptual overview part 2 the nuts and bolts,,A conceptual overview of asyncio
@anchor{howto/a-conceptual-overview-of-asyncio a-conceptual-overview-part-1-the-high-level}@anchor{5a43}
@subsection A conceptual overview part 1: the high-level


In part 1, we’ll cover the main, high-level building blocks of @code{asyncio}:
the event loop, coroutine functions, coroutine objects, tasks, and @code{await}.

@menu
* Event loop: Event loop<2>. 
* Asynchronous functions and coroutines:: 
* Tasks: Tasks<2>. 
* await:: 

@end menu

@node Event loop<2>,Asynchronous functions and coroutines,,A conceptual overview part 1 the high-level
@anchor{howto/a-conceptual-overview-of-asyncio event-loop}@anchor{5a44}
@subsubsection Event loop


Everything in @code{asyncio} happens relative to the event loop.
It’s the star of the show, but prefers to work behind the scenes, managing
and coordinating resources.
It’s like an orchestra conductor.
Some power is explicitly granted to it, but a lot of its ability to get things
done comes from the respect and cooperation of its band members.

In more technical terms, the event loop contains a collection of jobs to be run.
Some jobs are added directly by you, and some indirectly by @code{asyncio}.
The event loop takes a job from its backlog of work and invokes it (or «gives
it control»), similar to calling a function, and then that job runs.
Once it pauses or completes, it returns control to the event loop.
The event loop will then select another job from its pool and invoke it.
You can `roughly' think of the collection of jobs as a queue: jobs are added and
then processed one at a time, generally (but not always) in order.
This process repeats indefinitely, with the event loop cycling endlessly
onwards.
If there are no more jobs pending execution, the event loop is smart enough to
rest and avoid needlessly wasting CPU cycles, and will come back when there’s
more work to be done, such as when I/O operations complete or timers expire.

Effective execution relies on jobs sharing well and cooperating; a greedy job
could hog control and leave the other jobs to starve, rendering the overall
event loop approach rather useless.

@example
import asyncio

# This creates an event loop and indefinitely cycles through
# its collection of jobs.
event_loop = asyncio.new_event_loop()
event_loop.run_forever()
@end example

@node Asynchronous functions and coroutines,Tasks<2>,Event loop<2>,A conceptual overview part 1 the high-level
@anchor{howto/a-conceptual-overview-of-asyncio asynchronous-functions-and-coroutines}@anchor{5a45}
@subsubsection Asynchronous functions and coroutines


This is a basic, boring Python function:

@example
def hello_printer():
    print(
        "Hi, I am a lowly, simple printer, though I have all I "
        "need in life -- \nfresh paper and my dearly beloved octopus "
        "partner in crime."
    )
@end example

Calling a regular function invokes its logic or body:

@example
>>> hello_printer()
Hi, I am a lowly, simple printer, though I have all I need in life --
fresh paper and my dearly beloved octopus partner in crime.
@end example

The @ref{9cf,,async def}, as opposed to just a plain @code{def}, makes
this an asynchronous function (or «coroutine function»).
Calling it creates and returns a @ref{39fe,,coroutine} object.

@example
async def loudmouth_penguin(magic_number: int):
    print(
     "I am a super special talking penguin. Far cooler than that printer. "
     f"By the way, my lucky number is: @{magic_number@}."
    )
@end example

Calling the async function, @code{loudmouth_penguin}, does not execute the print statement;
instead, it creates a coroutine object:

@example
>>> loudmouth_penguin(magic_number=3)
<coroutine object loudmouth_penguin at 0x104ed2740>
@end example

The terms «coroutine function» and «coroutine object» are often conflated
as coroutine.
That can be confusing!
In this article, coroutine specifically refers to a coroutine object, or more
precisely, an instance of @ref{123a,,types.CoroutineType} (native coroutine).
Note that coroutines can also exist as instances of
@ref{1195,,collections.abc.Coroutine} – a distinction that matters for type
checking.

A coroutine represents the function’s body or logic.
A coroutine has to be explicitly started; again, merely creating the coroutine
does not start it.
Notably, the coroutine can be paused and resumed at various points within the
function’s body.
That pausing and resuming ability is what allows for asynchronous behavior!

Coroutines and coroutine functions were built by leveraging the functionality
of @ref{f9e,,generators} and
@ref{1409,,generator functions}.
Recall, a generator function is a function that @ref{d93,,yield}s, like this
one:

@example
def get_random_number():
    # This would be a bad random number generator!
    print("Hi")
    yield 1
    print("Hello")
    yield 7
    print("Howdy")
    yield 4
    ...
@end example

Similar to a coroutine function, calling a generator function does not run it.
Instead, it creates a generator object:

@example
>>> get_random_number()
<generator object get_random_number at 0x1048671c0>
@end example

You can proceed to the next @code{yield} of a generator by using the
built-in function @ref{bb5,,next()}.
In other words, the generator runs, then pauses.
For example:

@example
>>> generator = get_random_number()
>>> next(generator)
Hi
1
>>> next(generator)
Hello
7
@end example

@node Tasks<2>,await,Asynchronous functions and coroutines,A conceptual overview part 1 the high-level
@anchor{howto/a-conceptual-overview-of-asyncio tasks}@anchor{5a46}
@subsubsection Tasks


Roughly speaking, @ref{3a2e,,tasks} are coroutines (not coroutine
functions) tied to an event loop.
A task also maintains a list of callback functions whose importance will become
clear in a moment when we discuss @ref{432,,await}.

Creating a task automatically schedules it for execution (by adding a
callback to run it in the event loop’s to-do list, that is, collection of jobs).
The recommended way to create tasks is via @ref{462,,asyncio.create_task()}.

@code{asyncio} automatically associates tasks with the event loop for you.
This automatic association was purposely designed into @code{asyncio} for
the sake of simplicity.
Without it, you’d have to keep track of the event loop object and pass it to
any coroutine function that wants to create tasks, adding redundant clutter
to your code.

@example
coroutine = loudmouth_penguin(magic_number=5)
# This creates a Task object and schedules its execution via the event loop.
task = asyncio.create_task(coroutine)
@end example

Earlier, we manually created the event loop and set it to run forever.
In practice, it’s recommended to use (and common to see) @ref{309,,asyncio.run()},
which takes care of managing the event loop and ensuring the provided
coroutine finishes before advancing.
For example, many async programs follow this setup:

@example
import asyncio

async def main():
    # Perform all sorts of wacky, wild asynchronous things...
    ...

if __name__ == "__main__":
    asyncio.run(main())
    # The program will not reach the following print statement until the
    # coroutine main() finishes.
    print("coroutine main() is done!")
@end example

It’s important to be aware that the task itself is not added to the event loop,
only a callback to the task is.
This matters if the task object you created is garbage collected before it’s
called by the event loop.
For example, consider this program:

@example
async def hello():
    print("hello!")

async def main():
    asyncio.create_task(hello())
    # Other asynchronous instructions which run for a while
    # and cede control to the event loop...
    ...

asyncio.run(main())
@end example

Because there’s no reference to the task object created on line 5, it `might'
be garbage collected before the event loop invokes it.
Later instructions in the coroutine @code{main()} hand control back to the event
loop so it can invoke other jobs.
When the event loop eventually tries to run the task, it might fail and
discover the task object does not exist!
This can also happen even if a coroutine keeps a reference to a task but
completes before that task finishes.
When the coroutine exits, local variables go out of scope and may be subject
to garbage collection.
In practice, @code{asyncio} and Python’s garbage collector work pretty hard to
ensure this sort of thing doesn’t happen.
But that’s no reason to be reckless!

@node await,,Tasks<2>,A conceptual overview part 1 the high-level
@anchor{howto/a-conceptual-overview-of-asyncio await}@anchor{5a47}
@subsubsection await


@ref{432,,await} is a Python keyword that’s commonly used in one of two
different ways:

@example
await task
await coroutine
@end example

In a crucial way, the behavior of @code{await} depends on the type of object
being awaited.

@menu
* Awaiting tasks:: 
* Awaiting coroutines:: 

@end menu

@node Awaiting tasks,Awaiting coroutines,,await
@anchor{howto/a-conceptual-overview-of-asyncio awaiting-tasks}@anchor{5a48}
@subsubsection Awaiting tasks


Awaiting a task will cede control from the current task or coroutine to
the event loop.
In the process of relinquishing control, a few important things happen.
We’ll use the following code example to illustrate:

@example
async def plant_a_tree():
    dig_the_hole_task = asyncio.create_task(dig_the_hole())
    await dig_the_hole_task

    # Other instructions associated with planting a tree.
    ...
@end example

In this example, imagine the event loop has passed control to the start of the
coroutine @code{plant_a_tree()}.
As seen above, the coroutine creates a task and then awaits it.
The @code{await dig_the_hole_task} instruction adds a callback (which will resume
@code{plant_a_tree()}) to the @code{dig_the_hole_task} object’s list of callbacks.
And then, the instruction cedes control to the event loop.
Some time later, the event loop will pass control to @code{dig_the_hole_task}
and the task will finish whatever it needs to do.
Once the task finishes, it will add its various callbacks to the event loop,
in this case, a call to resume @code{plant_a_tree()}.

Generally speaking, when the awaited task finishes (@code{dig_the_hole_task}),
the original task or coroutine (@code{plant_a_tree()}) is added back to the event
loop’s to-do list to be resumed.

This is a basic, yet reliable mental model.
In practice, the control handoffs are slightly more complex, but not by much.
In part 2, we’ll walk through the details that make this possible.

@node Awaiting coroutines,,Awaiting tasks,await
@anchor{howto/a-conceptual-overview-of-asyncio awaiting-coroutines}@anchor{5a49}
@subsubsection Awaiting coroutines


`Unlike tasks, awaiting a coroutine does not hand control back to the event
loop!'
Wrapping a coroutine in a task first, then awaiting that would cede
control.
The behavior of @code{await coroutine} is effectively the same as invoking a
regular, synchronous Python function.
Consider this program:

@example
import asyncio

async def coro_a():
   print("I am coro_a(). Hi!")

async def coro_b():
   print("I am coro_b(). I sure hope no one hogs the event loop...")

async def main():
   task_b = asyncio.create_task(coro_b())
   num_repeats = 3
   for _ in range(num_repeats):
      await coro_a()
   await task_b

asyncio.run(main())
@end example

The first statement in the coroutine @code{main()} creates @code{task_b} and schedules
it for execution via the event loop.
Then, @code{coro_a()} is repeatedly awaited. Control never cedes to the
event loop, which is why we see the output of all three @code{coro_a()}
invocations before @code{coro_b()}”s output:

@example
I am coro_a(). Hi!
I am coro_a(). Hi!
I am coro_a(). Hi!
I am coro_b(). I sure hope no one hogs the event loop...
@end example

If we change @code{await coro_a()} to @code{await asyncio.create_task(coro_a())}, the
behavior changes.
The coroutine @code{main()} cedes control to the event loop with that statement.
The event loop then proceeds through its backlog of work, calling @code{task_b}
and then the task which wraps @code{coro_a()} before resuming the coroutine
@code{main()}.

@example
I am coro_b(). I sure hope no one hogs the event loop...
I am coro_a(). Hi!
I am coro_a(). Hi!
I am coro_a(). Hi!
@end example

This behavior of @code{await coroutine} can trip a lot of people up!
That example highlights how using only @code{await coroutine} could
unintentionally hog control from other tasks and effectively stall the event
loop.
@ref{309,,asyncio.run()} can help you detect such occurrences via the
@code{debug=True} flag, which enables
@ref{2328,,debug mode}.
Among other things, it will log any coroutines that monopolize execution for
100ms or longer.

The design intentionally trades off some conceptual clarity around usage of
@code{await} for improved performance.
Each time a task is awaited, control needs to be passed all the way up the
call stack to the event loop.
Then, the event loop needs to manage its internal state and work through
its processing logic to resume the next job.
That might sound minor, but in a large program with many @code{await}s, that
overhead can add up to a non-negligible performance drag.

@node A conceptual overview part 2 the nuts and bolts,,A conceptual overview part 1 the high-level,A conceptual overview of asyncio
@anchor{howto/a-conceptual-overview-of-asyncio a-conceptual-overview-part-2-the-nuts-and-bolts}@anchor{5a4a}
@subsection A conceptual overview part 2: the nuts and bolts


Part 2 goes into detail on the mechanisms @code{asyncio} uses to manage
control flow.
This is where the magic happens.
You’ll come away from this section knowing what @code{await} does behind the scenes
and how to make your own asynchronous operators.

@menu
* The inner workings of coroutines:: 
* Futures: Futures<2>. 
* A homemade asyncio.sleep: A homemade asyncio sleep. 

@end menu

@node The inner workings of coroutines,Futures<2>,,A conceptual overview part 2 the nuts and bolts
@anchor{howto/a-conceptual-overview-of-asyncio the-inner-workings-of-coroutines}@anchor{5a4b}
@subsubsection The inner workings of coroutines


@code{asyncio} leverages four components of Python to pass
around control.

@ref{260f,,coroutine.send(arg)} is the method used to start or
resume a coroutine.
If the coroutine was paused and is now being resumed, the argument @code{arg}
will be sent in as the return value of the @code{yield} statement which originally
paused it.
If the coroutine is being used for the first time (as opposed to being resumed),
@code{arg} must be @code{None}.

@example
class Rock:
    def __await__(self):
        value_sent_in = yield 7
        print(f"Rock.__await__ resuming with value: @{value_sent_in@}.")
        return value_sent_in

async def main():
    print("Beginning coroutine main().")
    rock = Rock()
    print("Awaiting rock...")
    value_from_rock = await rock
    print(f"Coroutine received value: @{value_from_rock@} from rock.")
    return 23

coroutine = main()
intermediate_result = coroutine.send(None)
print(f"Coroutine paused and returned intermediate value: @{intermediate_result@}.")

print(f"Resuming coroutine and sending in value: 42.")
try:
    coroutine.send(42)
except StopIteration as e:
    returned_value = e.value
print(f"Coroutine main() finished and provided value: @{returned_value@}.")
@end example

@ref{268f,,yield}, as usual, pauses execution and returns control
to the caller.
In the example above, the @code{yield}, on line 3, is called by
@code{... = await rock} on line 11.
More broadly speaking, @code{await} calls the @ref{112e,,__await__()} method of
the given object.
@code{await} also does one more very special thing: it propagates (or «passes
along») any @code{yield}s it receives up the call chain.
In this case, that’s back to @code{... = coroutine.send(None)} on line 16.

The coroutine is resumed via the @code{coroutine.send(42)} call on line 21.
The coroutine picks back up from where it @code{yield}ed (or paused) on line 3
and executes the remaining statements in its body.
When a coroutine finishes, it raises a @ref{fba,,StopIteration} exception with the
return value attached in the @ref{260c,,value} attribute.

That snippet produces this output:

@example
Beginning coroutine main().
Awaiting rock...
Coroutine paused and returned intermediate value: 7.
Resuming coroutine and sending in value: 42.
Rock.__await__ resuming with value: 42.
Coroutine received value: 42 from rock.
Coroutine main() finished and provided value: 23.
@end example

It’s worth pausing for a moment here and making sure you followed the various
ways that control flow and values were passed. A lot of important ideas were
covered and it’s worth ensuring your understanding is firm.

The only way to yield (or effectively cede control) from a coroutine is to
@code{await} an object that @code{yield}s in its @code{__await__} method.
That might sound odd to you. You might be thinking:

@quotation

1. What about a @code{yield} directly within the coroutine function? The
coroutine function becomes an
@ref{2693,,async generator function}, a
different beast entirely.

2. What about a @ref{268f,,yield from} within the coroutine function to a (plain)
generator?
That causes the error: @code{SyntaxError: yield from not allowed in a coroutine.}
This was intentionally designed for the sake of simplicity – mandating only
one way of using coroutines.
Despite that, @code{yield from} and @code{await} effectively do the same thing.
Initially @code{yield} was barred as well, but was re-accepted to allow for
async generators.
@end quotation

@node Futures<2>,A homemade asyncio sleep,The inner workings of coroutines,A conceptual overview part 2 the nuts and bolts
@anchor{howto/a-conceptual-overview-of-asyncio futures}@anchor{5a4c}
@subsubsection Futures


A @ref{3b09,,future} is an object meant to represent a
computation’s status and result.
The term is a nod to the idea of something still to come or not yet happened,
and the object is a way to keep an eye on that something.

A future has a few important attributes. One is its state, which can be either
«pending», «cancelled», or «done».
Another is its result, which is set when the state transitions to done.
Unlike a coroutine, a future does not represent the actual computation to be
done; instead, it represents the status and result of that computation, kind of
like a status light (red, yellow, or green) or indicator.

@ref{460,,asyncio.Task} subclasses @ref{f8b,,asyncio.Future} in order to gain
these various capabilities.
The prior section said tasks store a list of callbacks, which wasn’t entirely
accurate.
It’s actually the @code{Future} class that implements this logic, which @code{Task}
inherits.

Futures may also be used directly (not via tasks).
Tasks mark themselves as done when their coroutine is complete.
Futures are much more versatile and will be marked as done when you say so.
In this way, they’re the flexible interface for you to make your own conditions
for waiting and resuming.

@node A homemade asyncio sleep,,Futures<2>,A conceptual overview part 2 the nuts and bolts
@anchor{howto/a-conceptual-overview-of-asyncio a-homemade-asyncio-sleep}@anchor{5a4d}
@subsubsection A homemade asyncio.sleep


We’ll go through an example of how you could leverage a future to create your
own variant of asynchronous sleep (@code{async_sleep}) which mimics
@ref{e33,,asyncio.sleep()}.

This snippet registers a few tasks with the event loop and then awaits the task
created by @code{asyncio.create_task}, which wraps the @code{async_sleep(3)} coroutine.
We want that task to finish only after three seconds have elapsed, but without
preventing other tasks from running.

@example
async def other_work():
    print("I like work. Work work.")

async def main():
    # Add a few other tasks to the event loop, so there's something
    # to do while asynchronously sleeping.
    work_tasks = [
        asyncio.create_task(other_work()),
        asyncio.create_task(other_work()),
        asyncio.create_task(other_work())
    ]
    print(
        "Beginning asynchronous sleep at time: "
        f"@{datetime.datetime.now().strftime("%H:%M:%S")@}."
    )
    await asyncio.create_task(async_sleep(3))
    print(
        "Done asynchronous sleep at time: "
        f"@{datetime.datetime.now().strftime("%H:%M:%S")@}."
    )
    # asyncio.gather effectively awaits each task in the collection.
    await asyncio.gather(*work_tasks)
@end example

Below, we use a future to enable custom control over when that task will be
marked as done.
If @ref{3a31,,future.set_result()} (the method
responsible for marking that future as done) is never called, then this task
will never finish.
We’ve also enlisted the help of another task, which we’ll see in a moment, that
will monitor how much time has elapsed and, accordingly, call
@code{future.set_result()}.

@example
async def async_sleep(seconds: float):
    future = asyncio.Future()
    time_to_wake = time.time() + seconds
    # Add the watcher-task to the event loop.
    watcher_task = asyncio.create_task(_sleep_watcher(future, time_to_wake))
    # Block until the future is marked as done.
    await future
@end example

Below, we use a rather bare @code{YieldToEventLoop()} object to @code{yield}
from its @code{__await__} method, ceding control to the event loop.
This is effectively the same as calling @code{asyncio.sleep(0)}, but this approach
offers more clarity, not to mention it’s somewhat cheating to use
@code{asyncio.sleep} when showcasing how to implement it!

As usual, the event loop cycles through its tasks, giving them control
and receiving control back when they pause or finish.
The @code{watcher_task}, which runs the coroutine @code{_sleep_watcher(...)}, will
be invoked once per full cycle of the event loop.
On each resumption, it’ll check the time and if not enough has elapsed, then
it’ll pause once again and hand control back to the event loop.
Once enough time has elapsed, @code{_sleep_watcher(...)}
marks the future as done and completes by exiting its
infinite @code{while} loop.
Given this helper task is only invoked once per cycle of the event loop,
you’d be correct to note that this asynchronous sleep will sleep `at least'
three seconds, rather than exactly three seconds.
Note this is also true of @code{asyncio.sleep}.

@example
class YieldToEventLoop:
    def __await__(self):
        yield

async def _sleep_watcher(future, time_to_wake):
    while True:
        if time.time() >= time_to_wake:
            # This marks the future as done.
            future.set_result(None)
            break
        else:
            await YieldToEventLoop()
@end example

Here is the full program’s output:

@example
$ python custom-async-sleep.py
Beginning asynchronous sleep at time: 14:52:22.
I like work. Work work.
I like work. Work work.
I like work. Work work.
Done asynchronous sleep at time: 14:52:25.
@end example

You might feel this implementation of asynchronous sleep was unnecessarily
convoluted.
And, well, it was.
The example was meant to showcase the versatility of futures with a simple
example that could be mimicked for more complex needs.
For reference, you could implement it without futures, like so:

@example
async def simpler_async_sleep(seconds):
    time_to_wake = time.time() + seconds
    while True:
        if time.time() >= time_to_wake:
            return
        else:
            await YieldToEventLoop()
@end example

But that’s all for now. Hopefully you’re ready to more confidently dive into
some async programming or check out advanced topics in the
@ref{b,,rest of the documentation}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Porting Extension Modules to Python 3,Curses Programming with Python,A conceptual overview of asyncio,Python HOWTOs
@anchor{howto/cporting doc}@anchor{5a4e}@anchor{howto/cporting cporting-howto}@anchor{1685}@anchor{howto/cporting porting-extension-modules-to-python-3}@anchor{5a4f}@anchor{howto/cporting translation-repo}@anchor{5a50}
@section Porting Extension Modules to Python 3


We recommend the following resources for porting extension modules to Python 3:


@itemize *

@item 
The Migrating C extensions@footnote{http://python3porting.com/cextensions.html} chapter from
`Supporting Python 3: An in-depth guide', a book on moving from Python 2
to Python 3 in general, guides the reader through porting an extension
module.

@item 
The Porting guide@footnote{https://py3c.readthedocs.io/en/latest/guide.html} from the `py3c' project provides opinionated
suggestions with supporting code.

@item 
@ref{5198,,Recommended third party tools} offer abstractions over
the Python’s C API.
Extensions generally need to be re-written to use one of them,
but the library then handles differences between various Python
versions and implementations.
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Curses Programming with Python,Descriptor Guide,Porting Extension Modules to Python 3,Python HOWTOs
@anchor{howto/curses doc}@anchor{5a51}@anchor{howto/curses curses-howto}@anchor{36bf}@anchor{howto/curses curses-programming-with-python}@anchor{5a52}@anchor{howto/curses translation-repo}@anchor{5a53}
@section Curses Programming with Python


@*Author: 
A.M. Kuchling, Eric S. Raymond


@*Release: 
2.04


@subsubheading Abstract



This document describes how to use the @ref{2e,,curses} extension
module to control text-mode displays.

@menu
* What is curses?:: 
* Starting and ending a curses application:: 
* Windows and Pads:: 
* Displaying Text:: 
* User Input:: 
* For More Information:: 

@end menu

@node What is curses?,Starting and ending a curses application,,Curses Programming with Python
@anchor{howto/curses what-is-curses}@anchor{5a54}
@subsection What is curses?


The curses library supplies a terminal-independent screen-painting and
keyboard-handling facility for text-based terminals; such terminals
include VT100s, the Linux console, and the simulated terminal provided
by various programs.  Display terminals support various control codes
to perform common operations such as moving the cursor, scrolling the
screen, and erasing areas.  Different terminals use widely differing
codes, and often have their own minor quirks.

In a world of graphical displays, one might ask «why bother»?  It’s
true that character-cell display terminals are an obsolete technology,
but there are niches in which being able to do fancy things with them
are still valuable.  One niche is on small-footprint or embedded
Unixes that don’t run an X server.  Another is tools such as OS
installers and kernel configurators that may have to run before any
graphical support is available.

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/}.

The curses library was originally written for BSD Unix; the later System V
versions of Unix from AT&T added many enhancements and new functions. BSD curses
is no longer maintained, having been replaced by ncurses, which is an
open-source implementation of the AT&T interface.  If you’re using an
open-source Unix such as Linux or FreeBSD, your system almost certainly uses
ncurses.  Since most current commercial Unix versions are based on System V
code, all the functions described here will probably be available.  The older
versions of curses carried by some proprietary Unixes may not support
everything, though.

The Windows version of Python doesn’t include the @ref{2e,,curses}
module.  A ported version called UniCurses@footnote{https://pypi.org/project/UniCurses/} is available.

@menu
* The Python curses module:: 

@end menu

@node The Python curses module,,,What is curses?
@anchor{howto/curses the-python-curses-module}@anchor{5a55}
@subsubsection The Python curses module


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{1a27,,addstr()} method.  You’ll see this covered in more
detail later.

This HOWTO is an introduction to writing text-mode programs with curses
and Python. It doesn’t attempt to be a complete guide to the curses API; for
that, see the Python library guide’s section on ncurses, and the C manual pages
for ncurses.  It will, however, give you the basic ideas.

@node Starting and ending a curses application,Windows and Pads,What is curses?,Curses Programming with Python
@anchor{howto/curses starting-and-ending-a-curses-application}@anchor{5a56}
@subsection Starting and ending a curses application


Before doing anything, curses must be initialized.  This is done by
calling the @ref{1a1b,,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

Usually curses applications turn off automatic echoing of keys to the
screen, in order to be able to read keys and only display them under
certain circumstances.  This requires calling the
@ref{36f2,,noecho()} function.

@example
curses.noecho()
@end example

Applications will also commonly need to react to keys instantly,
without requiring the Enter key to be pressed; this is called cbreak
mode, as opposed to the usual buffered input mode.

@example
curses.cbreak()
@end example

Terminals usually return special keys, such as the cursor keys or navigation
keys such as Page Up and Home, as a multibyte escape sequence.  While you could
write your application to expect such sequences and process them accordingly,
curses can do it for you, returning a special value such as
@ref{375d,,curses.KEY_LEFT}.  To get curses to do the job, you’ll have to enable
keypad mode.

@example
stdscr.keypad(True)
@end example

Terminating a curses application is much easier than starting one. You’ll need
to call:

@example
curses.nocbreak()
stdscr.keypad(False)
curses.echo()
@end example

to reverse the curses-friendly terminal settings. Then call the
@ref{36d0,,endwin()} function to restore the terminal to its original
operating mode.

@example
curses.endwin()
@end example

A common problem when debugging a curses application is to get your terminal
messed up when the application dies without restoring the terminal to its
previous state.  In Python this commonly happens when your code is buggy and
raises an uncaught exception.  Keys are no longer echoed to the screen when
you type them, for example, which makes using the shell difficult.

In Python you can avoid these complications and make debugging much easier by
importing the @ref{e42,,curses.wrapper()} function and using it like this:

@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{e42,,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{ad6,,try}…@ref{447,,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 Windows and Pads,Displaying Text,Starting and ending a curses application,Curses Programming with Python
@anchor{howto/curses id1}@anchor{5a57}@anchor{howto/curses windows-and-pads}@anchor{1a23}
@subsection Windows and Pads


Windows are the basic abstraction in curses.  A window object represents a
rectangular area of the screen, and supports methods to display text,
erase it, allow the user to input strings, and so forth.

The @code{stdscr} object returned by the @ref{1a1b,,initscr()} function is a
window object that covers the entire screen.  Many programs may need
only this single window, but you might wish to divide the screen into
smaller windows, in order to redraw or clear them separately. The
@ref{36f1,,newwin()} function creates a new window of a given size,
returning the new window object.

@example
begin_x = 20; begin_y = 7
height = 5; width = 40
win = curses.newwin(height, width, begin_y, begin_x)
@end example

Note that the coordinate system used in curses is unusual.
Coordinates are always passed in the order `y,x', and the top-left
corner of a window is coordinate (0,0).  This breaks the normal
convention for handling coordinates where the `x' coordinate comes
first.  This is an unfortunate difference from most other computer
applications, but it’s been part of curses since it was first written,
and it’s too late to change things now.

Your application can determine the size of the screen by using the
@ref{11a4,,curses.LINES} and @ref{11a5,,curses.COLS} variables to obtain the `y' and
`x' sizes.  Legal coordinates will then extend from @code{(0,0)} to
@code{(curses.LINES - 1, curses.COLS - 1)}.

When you call a method to display or erase text, the effect doesn’t
immediately show up on the display.  Instead you must call the
@ref{1a21,,refresh()} method of window objects to update the
screen.

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.

A pad is a special case of a window; it can be larger than the actual display
screen, and only a portion of the pad displayed at a time. Creating a pad
requires the pad’s height and width, while refreshing a pad requires giving the
coordinates of the on-screen area where a subsection of the pad will be
displayed.

@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 
Calls the @ref{1a22,,noutrefresh()} method of each window
to update an underlying data structure representing the desired
state of the screen.

@item 
Calls the function @ref{36cf,,doupdate()} function to change the
physical screen to match the desired state recorded in the data structure.
@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 Displaying Text,User Input,Windows and Pads,Curses Programming with Python
@anchor{howto/curses displaying-text}@anchor{5a58}
@subsection Displaying Text


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.

Fortunately the Python interface hides all these details.  @code{stdscr}
is a window object like any other, and methods such as
@ref{1a27,,addstr()} accept multiple argument forms.  Usually there
are four different forms.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Form

@tab

Description

@item

`str' or `ch'

@tab

Display the string `str' or character `ch' at
the current position

@item

`str' or `ch', `attr'

@tab

Display the string `str' or character `ch',
using attribute `attr' at the current
position

@item

`y', `x', `str' or `ch'

@tab

Move to position `y,x' within the window, and
display `str' or `ch'

@item

`y', `x', `str' or `ch', `attr'

@tab

Move to position `y,x' within the window, and
display `str' or `ch', using attribute `attr'

@end multitable


Attributes allow displaying text in highlighted forms such as boldface,
underline, reverse code, or in color.  They’ll be explained in more detail in
the next subsection.

The @ref{1a27,,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{1443,,encoding} attribute; this defaults to
the default system encoding as returned by @ref{a45,,locale.getencoding()}.

The @ref{1a25,,addch()} methods take a character, which can be
either a string of length 1, a bytestring of length 1, or an integer.

Constants are provided for extension characters; these constants are
integers greater than 255.  For example, @ref{37ca,,ACS_PLMINUS} is a +/-
symbol, and @ref{370f,,ACS_ULCORNER} is the upper left corner of a box
(handy for drawing borders).  You can also use the appropriate Unicode
character.

Windows remember where the cursor was left after the last operation, so if you
leave out the `y,x' coordinates, the string or character will be displayed
wherever the last operation left off.  You can also move the cursor with the
@code{move(y,x)} method.  Because some terminals always display a flashing cursor,
you may want to ensure that the cursor is positioned in some location where it
won’t be distracting; it can be confusing to have the cursor blinking at some
apparently random location.

If your application doesn’t need a blinking cursor at all, you can
call @code{curs_set(False)} to make it invisible.  For compatibility
with older curses versions, there’s a @code{leaveok(bool)} function
that’s a synonym for @ref{36c9,,curs_set()}.  When `bool' is true, the
curses library will attempt to suppress the flashing cursor, and you
won’t need to worry about leaving it in odd locations.

@menu
* Attributes and Color:: 

@end menu

@node Attributes and Color,,,Displaying Text
@anchor{howto/curses attributes-and-color}@anchor{5a59}
@subsubsection Attributes and Color


Characters can be displayed in different ways.  Status lines in a text-based
application are commonly shown in reverse video, or a text viewer may need to
highlight certain words.  curses supports this by allowing you to specify an
attribute for each cell on the screen.

An attribute is an integer, each bit representing a different
attribute.  You can try to display text with multiple attribute bits
set, but curses doesn’t guarantee that all the possible combinations
are available, or that they’re all visually distinct.  That depends on
the ability of the terminal being used, so it’s safest to stick to the
most commonly available attributes, listed here.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribute

@tab

Description

@item

@ref{3749,,A_BLINK}

@tab

Blinking text

@item

@ref{374a,,A_BOLD}

@tab

Extra bright or bold text

@item

@ref{374b,,A_DIM}

@tab

Half bright text

@item

@ref{36c7,,A_REVERSE}

@tab

Reverse-video text

@item

@ref{36c6,,A_STANDOUT}

@tab

The best highlighting mode available

@item

@ref{374f,,A_UNDERLINE}

@tab

Underlined text

@end multitable


So, to display a reverse-video status line on the top line of the screen, you
could code:

@example
stdscr.addstr(0, 0, "Current mode: Typing mode",
              curses.A_REVERSE)
stdscr.refresh()
@end example

The curses library also supports color on those terminals that provide it. The
most common such terminal is probably the Linux console, followed by color
xterms.

To use color, you must call the @ref{36fc,,start_color()} function soon
after calling @ref{1a1b,,initscr()}, to initialize the default color set
(the @ref{e42,,curses.wrapper()} function does this automatically).  Once that’s
done, the @ref{36e3,,has_colors()} function returns TRUE if the terminal
in use can
actually display color.  (Note: curses uses the American spelling “color”,
instead of the Canadian/British spelling “colour”.  If you’re used to the
British spelling, you’ll have to resign yourself to misspelling it for the sake
of these functions.)

The curses library maintains a finite number of color pairs, containing a
foreground (or text) color and a background color.  You can get the attribute
value corresponding to a color pair with the @ref{36c5,,color_pair()}
function; this can be bitwise-OR’ed with other attributes such as
@ref{36c7,,A_REVERSE}, but again, such combinations are not guaranteed to work
on all terminals.

An example, which displays a line of text using color pair 1:

@example
stdscr.addstr("Pretty text", curses.color_pair(1))
stdscr.refresh()
@end example

As I said before, a color pair consists of a foreground and background color.
The @code{init_pair(n, f, b)} function changes the definition of color pair `n', to
foreground color f and background color b.  Color pair 0 is hard-wired to white
on black, and cannot be changed.

Colors are numbered, and @ref{36fc,,start_color()} initializes 8 basic
colors when it activates color mode.  They are: 0:black, 1:red,
2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and 7:white.  The @ref{2e,,curses}
module defines named constants for each of these colors:
@ref{37dc,,curses.COLOR_BLACK}, @ref{37e1,,curses.COLOR_RED}, and so forth.

Let’s put all this together. To change color 1 to red text on a white
background, you would call:

@example
curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)
@end example

When you change a color pair, any text already displayed using that color pair
will change to the new colors.  You can also display new text in this color
with:

@example
stdscr.addstr(0,0, "RED ALERT!", curses.color_pair(1))
@end example

Very fancy terminals can change the definitions of the actual colors to a given
RGB value.  This lets you change color 1, which is usually red, to purple or
blue or any other color you like.  Unfortunately, the Linux console doesn’t
support this, so I’m unable to try it out, and can’t provide any examples.  You
can check if your terminal can do this by calling
@ref{36c4,,can_change_color()}, which returns @code{True} if the capability is
there.  If you’re lucky enough to have such a talented terminal, consult your
system’s man pages for more information.

@node User Input,For More Information,Displaying Text,Curses Programming with Python
@anchor{howto/curses user-input}@anchor{5a5a}
@subsection User Input


The C curses library offers only very simple input mechanisms. Python’s
@ref{2e,,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.)

There are two methods for getting input from a window:


@itemize *

@item 
@ref{1a30,,getch()} refreshes the screen and then waits for
the user to hit a key, displaying the key if @ref{1a19,,echo()} has been
called earlier.  You can optionally specify a coordinate to which
the cursor should be moved before pausing.

@item 
@ref{3720,,getkey()} does the same thing but converts the
integer to a string.  Individual characters are returned as
1-character strings, and special keys such as function keys return
longer strings containing a key name such as @code{KEY_UP} or @code{^G}.
@end itemize

It’s possible to not wait for the user using the
@ref{3731,,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{36e7,,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{376e,,curses.KEY_PPAGE},
@ref{375f,,curses.KEY_HOME}, or @ref{375d,,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

The @ref{2f,,curses.ascii} module supplies ASCII class membership functions that
take either integer or 1-character string arguments; these may be useful in
writing more readable tests for such loops.  It also supplies
conversion functions  that take either integer or 1-character-string arguments
and return the same type.  For example, @ref{3824,,curses.ascii.ctrl()} returns the
control character corresponding to its argument.

There’s also a method to retrieve an entire string,
@ref{1a34,,getstr()}.  It isn’t used very often, because its
functionality is quite limited; the only editing keys available are
the backspace key and the Enter key, which terminates the string.  It
can optionally be limited to a fixed number of characters.

@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

The @ref{31,,curses.textpad} module supplies a text box that supports an
Emacs-like set of keybindings.  Various methods of the
@ref{37e5,,Textbox} class support editing with input
validation and gathering the edit results either with or without
trailing spaces.  Here’s an example:

@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

See the library documentation on @ref{31,,curses.textpad} for more details.

@node For More Information,,User Input,Curses Programming with Python
@anchor{howto/curses for-more-information}@anchor{5a5b}
@subsection For More Information


This HOWTO doesn’t cover some advanced topics, such as reading the
contents of the screen or capturing mouse events from an xterm
instance, but the Python library page for the @ref{2e,,curses} module is now
reasonably complete.  You should browse it next.

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{37b6,,ACS_*} characters available to
you.

Because the curses API is so large, some functions aren’t supported in
the Python interface.  Often this isn’t because they’re difficult to
implement, but because no one has needed them yet.  Also, Python
doesn’t yet support the menu library associated with ncurses.
Patches adding support for these would be welcome; see
the Python Developer's Guide@footnote{https://devguide.python.org/} to
learn more about submitting patches to Python.


@itemize *

@item 
Writing Programs with NCURSES@footnote{https://invisible-island.net/ncurses/ncurses-intro.html}:
a lengthy tutorial for C programmers.

@item 
The ncurses man page@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}:
video of a PyCon 2013 talk on controlling terminals using curses or Urwid.

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Descriptor Guide,Debugging C API extensions and CPython Internals with GDB,Curses Programming with Python,Python HOWTOs
@anchor{howto/descriptor doc}@anchor{5a5c}@anchor{howto/descriptor descriptor-guide}@anchor{5a5d}@anchor{howto/descriptor descriptorhowto}@anchor{188f}@anchor{howto/descriptor translation-repo}@anchor{5a5e}
@section Descriptor Guide


@*Author: 
Raymond Hettinger


@*Contact: 
<python at rcn dot com>


@ref{21f,,Descriptors} let objects customize attribute lookup,
storage, and deletion.

This guide has four major sections:


@enumerate 

@item 
The «primer» gives a basic overview, moving gently from simple examples,
adding one feature at a time.  Start here if you’re new to descriptors.

@item 
The second section shows a complete, practical descriptor example.  If you
already know the basics, start there.

@item 
The third section provides a more technical tutorial that goes into the
detailed mechanics of how descriptors work.  Most people don’t need this
level of detail.

@item 
The last section has pure Python equivalents for built-in descriptors that
are written in C.  Read this if you’re curious about how functions turn
into bound methods or about the implementation of common tools like
@ref{69a,,classmethod()}, @ref{666,,staticmethod()}, @ref{6bb,,property()}, and
@ref{9d9,,__slots__}.
@end enumerate

@menu
* Primer:: 
* Complete Practical Example:: 
* Technical Tutorial:: 
* Pure Python Equivalents:: 

@end menu

@node Primer,Complete Practical Example,,Descriptor Guide
@anchor{howto/descriptor primer}@anchor{5a5f}
@subsection Primer


In this primer, we start with the most basic possible example and then we’ll
add new capabilities one by one.

@menu
* Simple example; A descriptor that returns a constant: Simple example A descriptor that returns a constant. 
* Dynamic lookups:: 
* Managed attributes:: 
* Customized names:: 
* Closing thoughts:: 

@end menu

@node Simple example A descriptor that returns a constant,Dynamic lookups,,Primer
@anchor{howto/descriptor simple-example-a-descriptor-that-returns-a-constant}@anchor{5a60}
@subsubsection Simple example: A descriptor that returns a constant


The @code{Ten} class is a descriptor whose @ref{188a,,__get__()} method always
returns the constant @code{10}:

@example
class Ten:
    def __get__(self, obj, objtype=None):
        return 10
@end example

To use the descriptor, it must be stored as a class variable in another class:

@example
class A:
    x = 5                       # Regular class attribute
    y = Ten()                   # Descriptor instance
@end example

An interactive session shows the difference between normal attribute lookup
and descriptor lookup:

@example
>>> a = A()                     # Make an instance of class A
>>> a.x                         # Normal attribute lookup
5
>>> a.y                         # Descriptor lookup
10
@end example

In the @code{a.x} attribute lookup, the dot operator finds @code{'x': 5}
in the class dictionary.  In the @code{a.y} lookup, the dot operator
finds a descriptor instance, recognized by its @code{__get__} method.
Calling that method returns @code{10}.

Note that the value @code{10} is not stored in either the class dictionary or the
instance dictionary.  Instead, the value @code{10} is computed on demand.

This example shows how a simple descriptor works, but it isn’t very useful.
For retrieving constants, normal attribute lookup would be better.

In the next section, we’ll create something more useful, a dynamic lookup.

@node Dynamic lookups,Managed attributes,Simple example A descriptor that returns a constant,Primer
@anchor{howto/descriptor dynamic-lookups}@anchor{5a61}
@subsubsection Dynamic lookups


Interesting descriptors typically run computations instead of returning
constants:

@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

An interactive session shows that the lookup is dynamic — it computes
different, updated answers each time:

@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{188a,,__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 @code{__get__()} method learn the target directory.  The `objtype'
parameter is the class `Directory'.

@node Managed attributes,Customized names,Dynamic lookups,Primer
@anchor{howto/descriptor managed-attributes}@anchor{5a62}
@subsubsection Managed attributes


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{188a,,__get__()} and @ref{25aa,,__set__()} methods are triggered when
the public attribute is accessed.

In the following example, `age' is the public attribute and `_age' is the
private attribute.  When the public attribute is accessed, the descriptor logs
the lookup or update:

@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

An interactive session shows that all access to the managed attribute `age' is
logged, but that the regular attribute `name' is not logged:

@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

One major issue with this example is that the private name `_age' is hardwired in
the `LoggedAgeAccess' class.  That means that each instance can only have one
logged attribute and that its name is unchangeable.  In the next example,
we’ll fix that problem.

@node Customized names,Closing thoughts,Managed attributes,Primer
@anchor{howto/descriptor customized-names}@anchor{5a63}
@subsubsection Customized names


When a class uses descriptors, it can inform each descriptor about which
variable name was used.

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{100c,,__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{100c,,__set_name__()} so that the field names would be recorded.  Here
we call @ref{2011,,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

The new class now logs access to both `name' and `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

The two `Person' instances contain only the private names:

@example
>>> vars(pete)
@{'_name': 'Peter P', '_age': 10@}
>>> vars(kate)
@{'_name': 'Catherine C', '_age': 20@}
@end example

@node Closing thoughts,,Customized names,Primer
@anchor{howto/descriptor closing-thoughts}@anchor{5a64}
@subsubsection Closing thoughts


A @ref{21f,,descriptor} is what we call any object that defines @ref{188a,,__get__()},
@ref{25aa,,__set__()}, or @ref{1b64,,__delete__()}.

Optionally, descriptors can have a @ref{100c,,__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.)

Descriptors get invoked by the dot operator during attribute lookup.  If a
descriptor is accessed indirectly with @code{vars(some_class)[descriptor_name]},
the descriptor instance is returned without invoking it.

Descriptors only work when used as class variables.  When put in instances,
they have no effect.

The main motivation for descriptors is to provide a hook allowing objects
stored in class variables to control what happens during attribute lookup.

Traditionally, the calling class controls what happens during lookup.
Descriptors invert that relationship and allow the data being looked-up to
have a say in the matter.

Descriptors are used throughout the language.  It is how functions turn into
bound methods.  Common tools like @ref{69a,,classmethod()}, @ref{666,,staticmethod()},
@ref{6bb,,property()}, and @ref{94e,,functools.cached_property()} are all implemented as
descriptors.

@node Complete Practical Example,Technical Tutorial,Primer,Descriptor Guide
@anchor{howto/descriptor complete-practical-example}@anchor{5a65}
@subsection Complete Practical Example


In this example, we create a practical and powerful tool for locating
notoriously hard to find data corruption bugs.

@menu
* Validator class:: 
* Custom validators:: 
* Practical application:: 

@end menu

@node Validator class,Custom validators,,Complete Practical Example
@anchor{howto/descriptor validator-class}@anchor{5a66}
@subsubsection Validator class


A validator is a descriptor for managed attribute access.  Prior to storing
any data, it verifies that the new value meets various type and range
restrictions.  If those restrictions aren’t met, it raises an exception to
prevent data corruption at its source.

This @code{Validator} class is both an @ref{155f,,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 Custom validators,Practical application,Validator class,Complete Practical Example
@anchor{howto/descriptor custom-validators}@anchor{5a67}
@subsubsection Custom validators


Here are three practical data validation utilities:


@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{326,,int} or
@ref{327,,float}.  Optionally, it verifies that a value is between a given
minimum or maximum.

@item 
@code{String} verifies that a value is a @ref{1df,,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 a 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 Practical application,,Custom validators,Complete Practical Example
@anchor{howto/descriptor practical-application}@anchor{5a68}
@subsubsection Practical application


Here’s how the data validators can be used in a real class:

@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

The descriptors prevent invalid instances from being created:

@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 Technical Tutorial,Pure Python Equivalents,Complete Practical Example,Descriptor Guide
@anchor{howto/descriptor technical-tutorial}@anchor{5a69}
@subsection Technical Tutorial


What follows is a more technical tutorial for the mechanics and details of how
descriptors work.

@menu
* Abstract:: 
* Definition and introduction:: 
* Descriptor protocol:: 
* Overview of descriptor invocation:: 
* Invocation from an instance:: 
* Invocation from a class:: 
* Invocation from super:: 
* Summary of invocation logic:: 
* Automatic name notification:: 
* ORM example:: 

@end menu

@node Abstract,Definition and introduction,,Technical Tutorial
@anchor{howto/descriptor abstract}@anchor{5a6a}
@subsubsection Abstract


Defines descriptors, summarizes the protocol, and shows how descriptors are
called.  Provides an example showing how object relational mappings work.

Learning about descriptors not only provides access to a larger toolset, it
creates a deeper understanding of how Python works.

@node Definition and introduction,Descriptor protocol,Abstract,Technical Tutorial
@anchor{howto/descriptor definition-and-introduction}@anchor{5a6b}
@subsubsection Definition and introduction


In general, a descriptor is an attribute value that has one of the methods in
the descriptor protocol.  Those methods are @ref{188a,,__get__()}, @ref{25aa,,__set__()},
and @ref{1b64,,__delete__()}.  If any of those methods are defined for an
attribute, it is said to be a @ref{21f,,descriptor}.

The default behavior for attribute access is to get, set, or delete the
attribute from an object’s dictionary.  For instance, @code{a.x} has a lookup chain
starting with @code{a.__dict__['x']}, then @code{type(a).__dict__['x']}, and
continuing through the method resolution order of @code{type(a)}. If the
looked-up value is an object defining one of the descriptor methods, then Python
may override the default behavior and invoke the descriptor method instead.
Where this occurs in the precedence chain depends on which descriptor methods
were defined.

Descriptors are a powerful, general purpose protocol.  They are the mechanism
behind properties, methods, static methods, class methods, and
@ref{443,,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 Descriptor protocol,Overview of descriptor invocation,Definition and introduction,Technical Tutorial
@anchor{howto/descriptor descriptor-protocol}@anchor{5a6c}
@subsubsection Descriptor protocol


@code{descr.__get__(self, obj, type=None)}

@code{descr.__set__(self, obj, value)}

@code{descr.__delete__(self, obj)}

That is all there is to it.  Define any of these methods and an object is
considered a descriptor and can override default behavior upon being looked up
as an attribute.

If an object defines @ref{25aa,,__set__()} or @ref{1b64,,__delete__()}, it is considered
a data descriptor.  Descriptors that only define @ref{188a,,__get__()} are called
non-data descriptors (they are often used for methods but other uses are
possible).

Data and non-data descriptors differ in how overrides are calculated with
respect to entries in an instance’s dictionary.  If an instance’s dictionary
has an entry with the same name as a data descriptor, the data descriptor
takes precedence.  If an instance’s dictionary has an entry with the same
name as a non-data descriptor, the dictionary entry takes precedence.

To make a read-only data descriptor, define both @ref{188a,,__get__()} and
@ref{25aa,,__set__()} with the @code{__set__()} raising an @ref{1a9,,AttributeError} when
called.  Defining the @code{__set__()} method with an exception raising
placeholder is enough to make it a data descriptor.

@node Overview of descriptor invocation,Invocation from an instance,Descriptor protocol,Technical Tutorial
@anchor{howto/descriptor overview-of-descriptor-invocation}@anchor{5a6d}
@subsubsection Overview of descriptor invocation


A descriptor can be called directly with @code{desc.__get__(obj)} or
@code{desc.__get__(None, cls)}.

But it is more common for a descriptor to be invoked automatically from
attribute access.

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{1bf,,__dict__}, its @ref{188a,,__get__()} method is
invoked according to the precedence rules listed below.

The details of invocation depend on whether @code{obj} is an object, class, or
instance of super.

@node Invocation from an instance,Invocation from a class,Overview of descriptor invocation,Technical Tutorial
@anchor{howto/descriptor invocation-from-an-instance}@anchor{5a6e}
@subsubsection Invocation from an 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{8e3,,__getattr__()} if it is
provided.

If a descriptor is found for @code{a.x}, then it is invoked with:
@code{desc.__get__(a, type(a))}.

The logic for a dotted lookup is in @ref{f90,,object.__getattribute__()}.  Here is
a pure Python equivalent:

@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 = sentinel('null')
    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{8e3,,__getattr__()} hook in the @ref{f90,,__getattribute__()}
code.  That is why calling @code{__getattribute__()} directly or with
@code{super().__getattribute__} will bypass @code{__getattr__()} entirely.

Instead, it is the dot operator and the @ref{f8f,,getattr()} function that are
responsible for invoking @ref{8e3,,__getattr__()} whenever @ref{f90,,__getattribute__()}
raises an @ref{1a9,,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 Invocation from a class,Invocation from super,Invocation from an instance,Technical Tutorial
@anchor{howto/descriptor invocation-from-a-class}@anchor{5a6f}
@subsubsection Invocation from a class


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{2784,,method resolution order}.

If a descriptor is found, it is invoked with @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/main/Objects/typeobject.c}.

@node Invocation from super,Summary of invocation logic,Invocation from a class,Technical Tutorial
@anchor{howto/descriptor invocation-from-super}@anchor{5a70}
@subsubsection Invocation from super


The logic for super’s dotted lookup is in the @ref{f90,,__getattribute__()} method for
object returned by @ref{443,,super()}.

A dotted lookup such as @code{super(A, obj).m} searches @code{obj.__class__.__mro__}
for the base class @code{B} immediately following @code{A} and then returns
@code{B.__dict__['m'].__get__(obj, A)}.  If not a descriptor, @code{m} is returned
unchanged.

The full C implementation can be found in @code{super_getattro()} in
Objects/typeobject.c@footnote{https://github.com/python/cpython/tree/main/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 Summary of invocation logic,Automatic name notification,Invocation from super,Technical Tutorial
@anchor{howto/descriptor summary-of-invocation-logic}@anchor{5a71}
@subsubsection Summary of invocation logic


The mechanism for descriptors is embedded in the @ref{f90,,__getattribute__()}
methods for @ref{e4d,,object}, @ref{186,,type}, and @ref{443,,super()}.

The important points to remember are:


@itemize *

@item 
Descriptors are invoked by the @ref{f90,,__getattribute__()} method.

@item 
Classes inherit this machinery from @ref{e4d,,object}, @ref{186,,type}, or
@ref{443,,super()}.

@item 
Overriding @ref{f90,,__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{188a,,__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 
Data descriptors always override instance dictionaries.

@item 
Non-data descriptors may be overridden by instance dictionaries.
@end itemize

@node Automatic name notification,ORM example,Summary of invocation logic,Technical Tutorial
@anchor{howto/descriptor automatic-name-notification}@anchor{5a72}
@subsubsection Automatic name notification


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{186,,type} metaclass
scans the dictionary of the new class.  If any of the entries are descriptors
and if they define @ref{100c,,__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/main/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{100c,,__set_name__()} will need to be called manually.

@node ORM example,,Automatic name notification,Technical Tutorial
@anchor{howto/descriptor orm-example}@anchor{5a73}
@subsubsection ORM example


The following code is a simplified skeleton showing how data descriptors could
be used to implement an object relational mapping@footnote{https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping}.

The essential idea is that the data is stored in an external database.  The
Python instances only hold keys to the database’s tables.  Descriptors take
care of lookups or updates:

@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

To use the models, first connect to the database:

@example
>>> import sqlite3
>>> conn = sqlite3.connect('entertainment.db')
@end example

An interactive session shows how data is retrieved from the database and how
it can be updated:

@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 Pure Python Equivalents,,Technical Tutorial,Descriptor Guide
@anchor{howto/descriptor pure-python-equivalents}@anchor{5a74}
@subsection Pure Python Equivalents


The descriptor protocol is simple and offers exciting possibilities.  Several
use cases are so common that they have been prepackaged into built-in tools.
Properties, bound methods, static methods, class methods, and __slots__ are
all based on the descriptor protocol.

@menu
* Properties:: 
* Functions and methods:: 
* Kinds of methods:: 
* Static methods:: 
* Class methods:: 
* Member objects and __slots__:: 

@end menu

@node Properties,Functions and methods,,Pure Python Equivalents
@anchor{howto/descriptor properties}@anchor{5a75}
@subsubsection Properties


Calling @ref{6bb,,property()} is a succinct way of building a data descriptor that
triggers a function call upon access to an attribute.  Its signature is:

@example
property(fget=None, fset=None, fdel=None, doc=None) -> property
@end example

The documentation shows a typical use to define a managed attribute @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{6bb,,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

The @ref{6bb,,property()} builtin helps whenever a user interface has granted
attribute access and then subsequent changes require the intervention of a
method.

For instance, a spreadsheet class may grant access to a cell value through
@code{Cell('b10').value}. Subsequent improvements to the program require the cell
to be recalculated on every access; however, the programmer does not want to
affect existing client code accessing the attribute directly.  The solution is
to wrap access to the value attribute in a property data descriptor:

@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{6bb,,property()} or our @code{Property()} equivalent would
work in this example.

@node Functions and methods,Kinds of methods,Properties,Pure Python Equivalents
@anchor{howto/descriptor functions-and-methods}@anchor{5a76}
@subsubsection Functions and methods


Python’s object oriented features are built upon a function based environment.
Using non-data descriptors, the two are merged seamlessly.

Functions stored in class dictionaries get turned into methods when invoked.
Methods only differ from regular functions in that the object instance is
prepended to the other arguments.  By convention, the instance is called
`self' but could be called `this' or any other variable name.

Methods can be created manually with @ref{1d7f,,types.MethodType} which is
roughly equivalent to:

@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{188a,,__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

Running the following class in the interpreter shows how the function
descriptor works in practice:

@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

The function has a @ref{1f19,,qualified name} attribute to support introspection:

@example
>>> D.f.__qualname__
'D.f'
@end example

Accessing the function through the class dictionary does not invoke
@ref{188a,,__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{188a,,__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{188a,,__get__()} which returns a bound method object:

@example
>>> d = D()
>>> d.f
<bound method D.f of <__main__.D object at 0x00B18C90>>
@end example

Internally, the bound method stores the underlying function and the bound
instance:

@example
>>> d.f.__func__
<function D.f at 0x00C45070>

>>> d.f.__self__
<__main__.D object at 0x00B18C90>
@end example

If you have ever wondered where `self' comes from in regular methods or where
`cls' comes from in class methods, this is it!

@node Kinds of methods,Static methods,Functions and methods,Pure Python Equivalents
@anchor{howto/descriptor kinds-of-methods}@anchor{5a77}
@subsubsection Kinds of methods


Non-data descriptors provide a simple mechanism for variations on the usual
patterns of binding functions into methods.

To recap, functions have a @ref{188a,,__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)}.

This chart summarizes the binding and its two most useful variants:

@quotation


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} 
@headitem

Transformation

@tab

Called from an
object

@tab

Called from a
class

@item

function

@tab

f(obj, *args)

@tab

f(*args)

@item

staticmethod

@tab

f(*args)

@tab

f(*args)

@item

classmethod

@tab

f(type(obj), *args)

@tab

f(cls, *args)

@end multitable

@end quotation

@node Static methods,Class methods,Kinds of methods,Pure Python Equivalents
@anchor{howto/descriptor static-methods}@anchor{5a78}
@subsubsection Static methods


Static methods return the underlying function without changes.  Calling either
@code{c.f} or @code{C.f} is the equivalent of a direct lookup into
@code{object.__getattribute__(c, "f")} or @code{object.__getattribute__(C, "f")}. As a
result, the function becomes identically accessible from either an object or a
class.

Good candidates for static methods are methods that do not reference the
@code{self} variable.

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}.

Since static methods return the underlying function with no changes, the
example calls are unexciting:

@example
class E:
    @@staticmethod
    def f(x):
        return x * 10
@end example

@example
>>> E.f(3)
30
>>> E().f(3)
30
@end example

Using the non-data descriptor protocol, a pure Python version of
@ref{666,,staticmethod()} would look like this:

@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)

    @@property
    def __annotations__(self):
        return self.f.__annotations__
@end example

The @ref{13cb,,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, including @ref{1679,,__name__}, @ref{253a,,__qualname__},
and @ref{1582,,__doc__}.

@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 Class methods,Member objects and __slots__,Static methods,Pure Python Equivalents
@anchor{howto/descriptor class-methods}@anchor{5a79}
@subsubsection Class methods


Unlike static methods, class methods prepend the class reference to the
argument list before calling the function.  This format is the same
for whether the caller is an object or a class:

@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

This behavior is useful whenever the method only needs to have a class
reference and does not rely on data stored in a specific instance.  One use for
class methods is to create alternate class constructors.  For example, the
classmethod @ref{4da,,dict.fromkeys()} creates a new dictionary from a list of
keys.  The pure Python equivalent is:

@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

Now a new dictionary of unique keys can be constructed like this:

@example
>>> d = Dict.fromkeys('abracadabra')
>>> type(d) is Dict
True
>>> d
@{'a': None, 'b': None, 'r': None, 'c': None, 'd': None@}
@end example

Using the non-data descriptor protocol, a pure Python version of
@ref{69a,,classmethod()} would look like this:

@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{13cb,,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{1679,,__name__},
@ref{253a,,__qualname__}, @ref{1582,,__doc__},
and @ref{1581,,__annotations__}.

@node Member objects and __slots__,,Class methods,Pure Python Equivalents
@anchor{howto/descriptor member-objects-and-slots}@anchor{5a7a}
@subsubsection Member objects and __slots__


When a class defines @code{__slots__}, it replaces instance dictionaries with a
fixed-length array of slot values.  From a user point of view that has
several effects:

1. Provides immediate detection of bugs due to misspelled attribute
assignments.  Only attribute names specified in @code{__slots__} are allowed:

@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. Helps create immutable objects where descriptors manage access to private
attributes stored in @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. Saves memory.  On a 64-bit Linux build, an instance with two attributes
takes 48 bytes with @code{__slots__} and 152 bytes without.  This flyweight design pattern@footnote{https://en.wikipedia.org/wiki/Flyweight_pattern} likely only
matters when a large number of instances are going to be created.

4. Improves speed.  Reading instance variables is 35% faster with
@code{__slots__} (as measured with Python 3.10 on an Apple M1 processor).

5. Blocks tools like @ref{94e,,functools.cached_property()} which require an
instance dictionary to function correctly:

@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

It is not possible to create an exact drop-in pure Python version of
@code{__slots__} because it requires direct access to C structures and control
over object memory allocation.  However, we can build a mostly faithful
simulation where the actual C structure for slots is emulated by a private
@code{_slotvalues} list.  Reads and writes to that private structure are managed
by member descriptors:

@example
null = sentinel('null')

class Member:

    def __init__(self, name, clsname, offset):
        'Emulate PyMemberDef in Include/descrobject.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

The @ref{982,,object.__new__()} method takes care of creating instances that have
slots instead of an instance dictionary.  Here is a rough simulation in pure
Python:

@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{25c5,,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

At this point, the metaclass has loaded member objects for `x' and `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

When instances are created, they have a @code{slot_values} list where the
attributes are stored:

@example
>>> h = H(10, 20)
>>> vars(h)
@{'_slotvalues': [10, 20]@}
>>> h.x = 55
>>> vars(h)
@{'_slotvalues': [55, 20]@}
@end example

Misspelled or unassigned attributes will raise an 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Debugging C API extensions and CPython Internals with GDB,Enum HOWTO,Descriptor Guide,Python HOWTOs
@anchor{howto/gdb_helpers doc}@anchor{5a7b}@anchor{howto/gdb_helpers debugging-c-api-extensions-and-cpython-internals-with-gdb}@anchor{5a7c}@anchor{howto/gdb_helpers gdb}@anchor{5a7d}@anchor{howto/gdb_helpers translation-repo}@anchor{5a7e}
@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{19b,,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 Σημείωση 
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{5a7f}
@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{5a80}
@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 Σημείωση 
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{5a81}
@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{5a82}
@subsection Using the Debug build and Development mode


For easier debugging, you might want to:


@itemize -

@item 
Use a @ref{3dc,,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{70d,,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{5a83}
@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{5a84}
@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@}, '__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{5cb,,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{5cb,,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{b73,,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{5a85}
@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{5a86}
@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.

For example:

@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{5a87}
@subsubsection @code{py-bt}


@quotation

The @code{py-bt} command attempts to display a Python-level backtrace of the
current thread.

For example:

@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{5a88}
@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{5a89}
@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{5a8a}
@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Enum HOWTO,Functional Programming HOWTO,Debugging C API extensions and CPython Internals with GDB,Python HOWTOs
@anchor{howto/enum doc}@anchor{5a8b}@anchor{howto/enum enum-howto}@anchor{5a8c}@anchor{howto/enum id1}@anchor{5a8d}@anchor{howto/enum translation-repo}@anchor{5a8e}
@section Enum HOWTO

@anchor{howto/enum enum-basic-tutorial}@anchor{2c37}
An @ref{a21,,Enum} is a set of symbolic names bound to unique values.  They are
similar to global variables, but they offer a more useful @ref{45b,,repr()},
grouping, type-safety, and a few other features.

They are most useful when you have a variable that can take one of a limited
selection of values.  For example, the days of the week:

@example
>>> from enum import Enum
>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7
@end example

Or perhaps the RGB primary colors:

@example
>>> from enum import Enum
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3
@end example

As you can see, creating an @ref{a21,,Enum} is as simple as writing a class that
inherits from @code{Enum} itself.

@cartouche
@quotation Σημείωση 
Case of Enum Members

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

Depending on the nature of the enum a member’s value may or may not be
important, but either way that value can be used to get the corresponding
member:

@example
>>> Weekday(3)
<Weekday.WEDNESDAY: 3>
@end example

As you can see, the @code{repr()} of a member shows the enum name, the member name,
and the value.  The @code{str()} of a member shows only the enum name and member
name:

@example
>>> print(Weekday.THURSDAY)
Weekday.THURSDAY
@end example

The `type' of an enumeration member is the enum it belongs to:

@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{48d,,datetime.date}
has two methods for returning the weekday:
@ref{2ad3,,weekday()} and @ref{2ad4,,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 @code{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

Now we can find out what today is!  Observe:

@example
>>> import datetime as dt
>>> Weekday.from_date(dt.date.today())
<Weekday.TUESDAY: 2>
@end example

Of course, if you’re reading this on some other day, you’ll see that day instead.

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{4d9,,list} – we could use a different type
of @ref{a21,,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

We’ve changed two things: we’re inherited from @ref{a14,,Flag}, and the values are
all powers of 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

But @ref{a14,,Flag} also allows us to combine several members into a single
variable:

@example
>>> weekend = Weekday.SATURDAY | Weekday.SUNDAY
>>> weekend
<Weekday.SATURDAY|SUNDAY: 96>
@end example

You can even iterate over a @ref{a14,,Flag} variable:

@example
>>> for day in weekend:
...     print(day)
Weekday.SATURDAY
Weekday.SUNDAY
@end example

Okay, let’s get some chores set up:

@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

And a function to display the chores for a given day:

@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{105e,,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
* Programmatic access to enumeration members and their attributes:: 
* Duplicating enum members and values:: 
* Ensuring unique enumeration values:: 
* Using automatic values:: 
* Iteration: Iteration<2>. 
* Comparisons: Comparisons<2>. 
* Allowed members and attributes of enumerations:: 
* Restricted Enum subclassing:: 
* Dataclass support:: 
* Pickling:: 
* Functional API: Functional API<2>. 
* Derived Enumerations:: 
* When to use __new__() vs. __init__(): When to use __new__ vs __init__. 
* Finer Points:: 
* How are Enums and Flags different?:: 
* Enum Cookbook:: 
* Subclassing EnumType:: 

@end menu

@node Programmatic access to enumeration members and their attributes,Duplicating enum members and values,,Enum HOWTO
@anchor{howto/enum enum-advanced-tutorial}@anchor{2c38}@anchor{howto/enum programmatic-access-to-enumeration-members-and-their-attributes}@anchor{5a8f}
@subsection Programmatic access to enumeration members and their attributes


Sometimes it’s useful to access members in enumerations programmatically (i.e.
situations where @code{Color.RED} won’t do because the exact color is not known
at program-writing time).  @code{Enum} allows such access:

@example
>>> Color(1)
<Color.RED: 1>
>>> Color(3)
<Color.BLUE: 3>
@end example

If you want to access enum members by `name', use item access:

@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 Duplicating enum members and values,Ensuring unique enumeration values,Programmatic access to enumeration members and their attributes,Enum HOWTO
@anchor{howto/enum duplicating-enum-members-and-values}@anchor{5a90}
@subsection Duplicating enum members and values


Having two enum members with the same name is invalid:

@example
>>> class Shape(Enum):
...     SQUARE = 2
...     SQUARE = 3
...
Traceback (most recent call last):
...
TypeError: 'SQUARE' already defined as 2
@end example

However, an enum member can have other names associated with it.  Given two
entries @code{A} and @code{B} with the same value (and @code{A} defined first), @code{B}
is an alias for the member @code{A}.  By-value lookup of the value of @code{A} will
return the member @code{A}.  By-name lookup of @code{A} will return the member @code{A}.
By-name lookup of @code{B} will also return the member @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 Σημείωση 
Attempting to create a member with the same name as an already
defined attribute (another member, a method, etc.) or attempting to create
an attribute with the same name as a member is not allowed.
@end quotation
@end cartouche

@node Ensuring unique enumeration values,Using automatic values,Duplicating enum members and values,Enum HOWTO
@anchor{howto/enum ensuring-unique-enumeration-values}@anchor{5a91}
@subsection Ensuring unique enumeration values


By default, enumerations allow multiple names as aliases for the same value.
When this behavior isn’t desired, you can use the @ref{2c3d,,unique()} decorator:

@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 Using automatic values,Iteration<2>,Ensuring unique enumeration values,Enum HOWTO
@anchor{howto/enum using-automatic-values}@anchor{5a92}
@subsection Using automatic values


If the exact value is unimportant you can use @ref{105e,,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{2c50,,_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 Σημείωση 
The @ref{2c50,,_generate_next_value_()} method must be defined before any members.
@end quotation
@end cartouche

@node Iteration<2>,Comparisons<2>,Using automatic values,Enum HOWTO
@anchor{howto/enum iteration}@anchor{5a93}
@subsection Iteration


Iterating over the members of an enum does not provide the aliases:

@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.

The special attribute @code{__members__} is a read-only ordered mapping of names
to members.  It includes all names defined in the enumeration, including the
aliases:

@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

The @code{__members__} attribute can be used for detailed programmatic access to
the enumeration members.  For example, finding all the aliases:

@example
>>> [name for name, member in Shape.__members__.items() if member.name != name]
['ALIAS_FOR_SQUARE']
@end example

@cartouche
@quotation Σημείωση 
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 Comparisons<2>,Allowed members and attributes of enumerations,Iteration<2>,Enum HOWTO
@anchor{howto/enum comparisons}@anchor{5a94}
@subsection Comparisons


Enumeration members are compared by identity:

@example
>>> Color.RED is Color.RED
True
>>> Color.RED is Color.BLUE
False
>>> Color.RED is not Color.BLUE
True
@end example

Ordered comparisons between enumeration values are `not' supported.  Enum
members are not integers (but see @ref{5a95,,IntEnum} below):

@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

Equality comparisons are defined though:

@example
>>> Color.BLUE == Color.RED
False
>>> Color.BLUE != Color.RED
True
>>> Color.BLUE == Color.BLUE
True
@end example

Equality comparisons against non-enumeration values will always return @code{False}
(again, @ref{109d,,IntEnum} was explicitly designed to behave differently, see
below):

@example
>>> Color.BLUE == 2
False
@end example

@cartouche
@quotation Προειδοποίηση 
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 Allowed members and attributes of enumerations,Restricted Enum subclassing,Comparisons<2>,Enum HOWTO
@anchor{howto/enum allowed-members-and-attributes-of-enumerations}@anchor{5a96}
@subsection Allowed members and attributes of enumerations


Most of the examples above use integers for enumeration values.  Using integers
is short and handy (and provided by default by the @ref{5a97,,Functional API}), but not
strictly enforced.  In the vast majority of use-cases, one doesn’t care what
the actual value of an enumeration is.  But if the value `is' important,
enumerations can have arbitrary values.

Enumerations are Python classes, and can have methods and special methods as
usual.  If we have this enumeration:

@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

Then:

@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{a0f,,__str__()},
@ref{25d2,,__add__()}, etc.), descriptors (methods are also descriptors), and
variable names listed in @ref{2c4e,,_ignore_}.

Note:  if your enumeration defines @ref{982,,__new__()} and/or @ref{2fa,,__init__()},
any value(s) given to the enum member will be passed into those methods.
See @ref{5a98,,Planet} for an example.

@cartouche
@quotation Σημείωση 
The @ref{982,,__new__()} method, if defined, is used during creation of the Enum
members; it is then replaced by Enum’s @code{__new__()} which is used after
class creation for lookup of existing members.  See @ref{5a99,,When to use __new__() vs. __init__()} for
more details.
@end quotation
@end cartouche

@node Restricted Enum subclassing,Dataclass support,Allowed members and attributes of enumerations,Enum HOWTO
@anchor{howto/enum restricted-enum-subclassing}@anchor{5a9a}
@subsection Restricted Enum subclassing


A new @ref{a21,,Enum} class must have one base enum class, up to one concrete
data type, and as many @ref{e4d,,object}-based mixin classes as needed.  The
order of these base classes is:

@example
class EnumName([mix-in, ...,] [data-type,] base-enum):
    pass
@end example

Also, subclassing an enumeration is allowed only if the enumeration does not define
any members.  So this is forbidden:

@example
>>> class MoreColor(Color):
...     PINK = 17
...
Traceback (most recent call last):
...
TypeError: <enum 'MoreColor'> cannot extend <enum 'Color'>
@end example

But this is allowed:

@example
>>> class Foo(Enum):
...     def some_behavior(self):
...         pass
...
>>> class Bar(Foo):
...     HAPPY = 1
...     SAD = 2
...
@end example

Allowing subclassing of enums that define members would lead to a violation of
some important invariants of types and instances.  On the other hand, it makes
sense to allow sharing some common behavior between a group of enumerations.
(See @ref{5a9b,,OrderedEnum} for an example.)

@node Dataclass support,Pickling,Restricted Enum subclassing,Enum HOWTO
@anchor{howto/enum dataclass-support}@anchor{5a9c}@anchor{howto/enum enum-dataclass-support}@anchor{1cf8}
@subsection Dataclass support


When inheriting from a @ref{6e6,,dataclass},
the @ref{1cf9,,__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{6e6,,dataclass()} argument @code{repr=False}
to use the standard @ref{45b,,repr()}.


Άλλαξε στην έκδοση 3.12: Only the dataclass fields are shown in the value area, not the dataclass”
name.


@cartouche
@quotation Σημείωση 
Adding @ref{6e6,,dataclass()} decorator to @ref{a21,,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 Pickling,Functional API<2>,Dataclass support,Enum HOWTO
@anchor{howto/enum pickling}@anchor{5a9d}
@subsection Pickling


Enumerations can be pickled and unpickled:

@example
>>> from test.test_enum import Fruit
>>> from pickle import dumps, loads
>>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))
True
@end example

The usual restrictions for pickling apply: picklable enums must be defined in
the top level of a module, since unpickling requires them to be importable
from that module.

@cartouche
@quotation Σημείωση 
With pickle protocol version 4 it is possible to easily pickle enums
nested in other classes.
@end quotation
@end cartouche

It is possible to modify how enum members are pickled/unpickled by defining
@ref{1b7e,,__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 Σημείωση 
Using by-name for flags is not recommended, as unnamed aliases will
not unpickle.
@end quotation
@end cartouche

@node Functional API<2>,Derived Enumerations,Pickling,Enum HOWTO
@anchor{howto/enum functional-api}@anchor{5a97}
@subsection Functional API


The @ref{a21,,Enum} class is callable, providing the following functional API:

@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

The semantics of this API resemble @ref{1cf,,namedtuple}. The first
argument of the call to @ref{a21,,Enum} is the name of the enumeration.

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{a21,,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

The reason for defaulting to @code{1} as the starting number and not @code{0} is
that @code{0} is @code{False} in a boolean sense, but by default enum members all
evaluate to @code{True}.

Pickling enums created with the functional API can be tricky as frame stack
implementation details are used to try and figure out which module the
enumeration is being created in (e.g. it will fail if you use a utility
function in a separate module, and also may not work on IronPython or Jython).
The solution is to specify the module name explicitly as follows:

@example
>>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)
@end example

@cartouche
@quotation Προειδοποίηση 
If @code{module} is not supplied, and Enum cannot determine what it is,
the new Enum members will not be unpicklable; to keep errors closer to
the source, pickling will be disabled.
@end quotation
@end cartouche

The new pickle protocol 4 also, in some circumstances, relies on
@ref{2565,,__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

The complete signature is:

@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

or an iterator of names:

@example
['RED', 'GREEN', 'BLUE']
@end example

or an iterator of (name, value) pairs:

@example
[('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]
@end example

or a mapping:

@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


Άλλαξε στην έκδοση 3.5: The `start' parameter was added.


@node Derived Enumerations,When to use __new__ vs __init__,Functional API<2>,Enum HOWTO
@anchor{howto/enum derived-enumerations}@anchor{5a9e}
@subsection Derived Enumerations


@menu
* IntEnum:: 
* StrEnum:: 
* IntFlag:: 
* Flag:: 
* Others: Others<2>. 

@end menu

@node IntEnum,StrEnum,,Derived Enumerations
@anchor{howto/enum intenum}@anchor{5a95}
@subsubsection IntEnum


The first variation of @ref{a21,,Enum} that is provided is also a subclass of
@ref{326,,int}.  Members of an @ref{109d,,IntEnum} can be compared to integers;
by extension, integer enumerations of different types can also be compared
to each other:

@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

However, they still can’t be compared to standard @ref{a21,,Enum} enumerations:

@example
>>> class Shape(IntEnum):
...     CIRCLE = 1
...     SQUARE = 2
...
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...
>>> Shape.CIRCLE == Color.RED
False
@end example

@ref{109d,,IntEnum} values behave like integers in other ways you’d expect:

@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,Derived Enumerations
@anchor{howto/enum strenum}@anchor{5a9f}
@subsubsection StrEnum


The second variation of @ref{a21,,Enum} that is provided is also a subclass of
@ref{1df,,str}.  Members of a @ref{a0d,,StrEnum} can be compared to strings;
by extension, string enumerations of different types can also be compared
to each other.


Added in version 3.11.


@node IntFlag,Flag,StrEnum,Derived Enumerations
@anchor{howto/enum intflag}@anchor{5aa0}
@subsubsection IntFlag


The next variation of @ref{a21,,Enum} provided, @ref{105d,,IntFlag}, is also based
on @ref{326,,int}.  The difference being @code{IntFlag} members can be combined
using the bitwise operators (&, |, ^, ~) and the result is still an
@code{IntFlag} member, if possible.  Like @ref{109d,,IntEnum}, @code{IntFlag}
members are also integers and can be used wherever an @code{int} is used.

@cartouche
@quotation Σημείωση 
Any operation on an @ref{105d,,IntFlag} member besides the bit-wise operations will
lose the @code{IntFlag} membership.

Bit-wise operations that result in invalid @ref{105d,,IntFlag} values will lose the
@code{IntFlag} membership.  See @ref{a15,,FlagBoundary} for
details.
@end quotation
@end cartouche


Added in version 3.6.



Άλλαξε στην έκδοση 3.11.


Sample @ref{105d,,IntFlag} class:

@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

It is also possible to name the combinations:

@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 Σημείωση 
Named combinations are considered aliases.  Aliases do not show up during
iteration, but can be returned from by-value lookups.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.11.


Another important difference between @ref{105d,,IntFlag} and @ref{a21,,Enum} is that
if no flags are set (the value is 0), its boolean evaluation is @ref{ef5,,False}:

@example
>>> Perm.R & Perm.X
<Perm: 0>
>>> bool(Perm.R & Perm.X)
False
@end example

Because @ref{105d,,IntFlag} members are also subclasses of @ref{326,,int} they can
be combined with them (but may lose @code{IntFlag} membership:

@example
>>> Perm.X | 4
<Perm.R|X: 5>

>>> Perm.X + 8
9
@end example

@cartouche
@quotation Σημείωση 
The negation operator, @code{~}, always returns an @ref{105d,,IntFlag} member with a
positive value:

@example
>>> (~Perm.X).value == (Perm.R|Perm.W).value == 6
True
@end example
@end quotation
@end cartouche

@ref{105d,,IntFlag} members can also be iterated over:

@example
>>> list(RW)
[<Perm.R: 4>, <Perm.W: 2>]
@end example


Added in version 3.11.


@node Flag,Others<2>,IntFlag,Derived Enumerations
@anchor{howto/enum flag}@anchor{5aa1}
@subsubsection Flag


The last variation is @ref{a14,,Flag}.  Like @ref{105d,,IntFlag}, @code{Flag}
members can be combined using the bitwise operators (&, |, ^, ~).  Unlike
@code{IntFlag}, they cannot be combined with, nor compared against, any
other @code{Flag} enumeration, nor @ref{326,,int}.  While it is possible to
specify the values directly it is recommended to use @ref{105e,,auto} as the
value and let @code{Flag} select an appropriate value.


Added in version 3.6.


Like @ref{105d,,IntFlag}, if a combination of @ref{a14,,Flag} members results in no
flags being set, the boolean evaluation is @ref{ef5,,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

Giving a name to the «no flags set» condition does not change its boolean
value:

@example
>>> class Color(Flag):
...     BLACK = 0
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.BLACK
<Color.BLACK: 0>
>>> bool(Color.BLACK)
False
@end example

@ref{a14,,Flag} members can also be iterated over:

@example
>>> purple = Color.RED | Color.BLUE
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 2>]
@end example


Added in version 3.11.


@cartouche
@quotation Σημείωση 
For the majority of new code, @ref{a21,,Enum} and @ref{a14,,Flag} are strongly
recommended, since @ref{109d,,IntEnum} and @ref{105d,,IntFlag} break some
semantic promises of an enumeration (by being comparable to integers, and
thus by transitivity to other unrelated enumerations).  @code{IntEnum}
and @code{IntFlag} should be used only in cases where @code{Enum} and
@code{Flag} will not do; for example, when integer constants are replaced
with enumerations, or for interoperability with other systems.
@end quotation
@end cartouche

@node Others<2>,,Flag,Derived Enumerations
@anchor{howto/enum others}@anchor{5aa2}
@subsubsection Others


While @ref{109d,,IntEnum} is part of the @ref{59,,enum} module, it would be very
simple to implement independently:

@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{327,,float} instead of @ref{326,,int}.

Some rules:


@enumerate 

@item 
When subclassing @ref{a21,,Enum}, mix-in types must appear before the
@code{Enum} class itself in the sequence of bases, as in the @ref{109d,,IntEnum}
example above.

@item 
Mix-in types must be subclassable. For example, @ref{5ef,,bool} and
@ref{d0f,,range} are not subclassable and will throw an error during Enum
creation if used as the mix-in type.

@item 
While @ref{a21,,Enum} can have members of any type, once you mix in an
additional type, all the members must have values of that type, e.g.
@ref{326,,int} above.  This restriction does not apply to mix-ins which only
add methods and don’t specify another type.

@item 
When another data type is mixed in, the @ref{2c49,,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{982,,__new__()}, or a
@ref{6e6,,dataclass}

@item 
%-style formatting:  @code{%s} and @code{%r} call the @ref{a21,,Enum} class’s
@ref{a0f,,__str__()} and @ref{1bc,,__repr__()} respectively; other codes (such as
@code{%i} or @code{%h} for IntEnum) treat the enum member as its mixed-in type.

@item 
@ref{43a,,Formatted string literals}, @ref{a12,,str.format()},
and @ref{439,,format()} will use the enum’s @ref{a0f,,__str__()} method.
@end enumerate

@cartouche
@quotation Σημείωση 
Because @ref{109d,,IntEnum}, @ref{105d,,IntFlag}, and @ref{a0d,,StrEnum} are
designed to be drop-in replacements for existing constants, their
@ref{a0f,,__str__()} method has been reset to their data types”
@code{__str__()} method.
@end quotation
@end cartouche

@node When to use __new__ vs __init__,Finer Points,Derived Enumerations,Enum HOWTO
@anchor{howto/enum new-vs-init}@anchor{5a99}@anchor{howto/enum when-to-use-new-vs-init}@anchor{5aa3}
@subsection When to use @code{__new__()} vs. @code{__init__()}


@ref{982,,__new__()} must be used whenever you want to customize the actual value of
the @ref{a21,,Enum} member.  Any other modifications may go in either
@code{__new__()} or @ref{2fa,,__init__()}, with @code{__init__()} being preferred.

For example, if you want to pass several items to the constructor, but only
want one of them to be the value:

@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 Προειδοποίηση 
`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

@node Finer Points,How are Enums and Flags different?,When to use __new__ vs __init__,Enum HOWTO
@anchor{howto/enum finer-points}@anchor{5aa4}
@subsection Finer Points


@menu
* Supported __dunder__ and _sunder_ names:: 
* _Private__names:: 
* Enum member type:: 
* Creating members that are mixed with other data types:: 
* Boolean value of Enum classes and members:: 
* Enum classes with methods:: 
* Combining members of Flag:: 
* Flag and IntFlag minutia:: 

@end menu

@node Supported __dunder__ and _sunder_ names,_Private__names,,Finer Points
@anchor{howto/enum supported-dunder-and-sunder-names}@anchor{5aa5}
@subsubsection Supported @code{__dunder__} and @code{_sunder_} names


The supported @code{__dunder__} and @code{_sunder_} names can be found in the @ref{2c64,,Enum API documentation}.

@node _Private__names,Enum member type,Supported __dunder__ and _sunder_ names,Finer Points
@anchor{howto/enum private-names}@anchor{5aa6}
@subsubsection _Private__names


@ref{2293,,Private names} are not converted to enum members,
but remain normal attributes.


Άλλαξε στην έκδοση 3.11.


@node Enum member type,Creating members that are mixed with other data types,_Private__names,Finer Points
@anchor{howto/enum enum-member-type}@anchor{5aa7}
@subsubsection @code{Enum} member type


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.


Άλλαξε στην έκδοση 3.5.


@node Creating members that are mixed with other data types,Boolean value of Enum classes and members,Enum member type,Finer Points
@anchor{howto/enum creating-members-that-are-mixed-with-other-data-types}@anchor{5aa8}
@subsubsection Creating members that are mixed with other data types


When subclassing other data types, such as @ref{326,,int} or @ref{1df,,str}, with
an @ref{a21,,Enum}, all values after the @code{=} are passed to that data type’s
constructor.  For example:

@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 Boolean value of Enum classes and members,Enum classes with methods,Creating members that are mixed with other data types,Finer Points
@anchor{howto/enum boolean-value-of-enum-classes-and-members}@anchor{5aa9}
@subsubsection Boolean value of @code{Enum} classes and members


Enum classes that are mixed with non-@ref{a21,,Enum} types (such as
@ref{326,,int}, @ref{1df,,str}, etc.) are evaluated according to the mixed-in
type’s rules; otherwise, all members evaluate as @ref{fcc,,True}.  To make your
own enum’s boolean evaluation depend on the member’s value add the following to
your class:

@example
def __bool__(self):
    return bool(self.value)
@end example

Plain @ref{a21,,Enum} classes always evaluate as @ref{fcc,,True}.

@node Enum classes with methods,Combining members of Flag,Boolean value of Enum classes and members,Finer Points
@anchor{howto/enum enum-classes-with-methods}@anchor{5aaa}
@subsubsection @code{Enum} classes with methods


If you give your enum subclass extra methods, like the @ref{5a98,,Planet}
class below, those methods will show up in a @ref{a23,,dir()} of the member,
but not of the class:

@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 Combining members of Flag,Flag and IntFlag minutia,Enum classes with methods,Finer Points
@anchor{howto/enum combining-members-of-flag}@anchor{5aab}
@subsubsection Combining members of @code{Flag}


Iterating over a combination of @ref{a14,,Flag} members will only return the members that
are comprised of a single bit:

@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 Flag and IntFlag minutia,,Combining members of Flag,Finer Points
@anchor{howto/enum flag-and-intflag-minutia}@anchor{5aac}
@subsubsection @code{Flag} and @code{IntFlag} minutia


Using the following snippet for our examples:

@example
>>> class Color(IntFlag):
...     BLACK = 0
...     RED = 1
...     GREEN = 2
...     BLUE = 4
...     PURPLE = RED | BLUE
...     WHITE = RED | GREEN | BLUE
...
@end example

the following are true:


@itemize -

@item 
single-bit flags are canonical

@item 
multi-bit and zero-bit flags are aliases

@item 
only canonical flags are returned during iteration:

@example
>>> list(Color.WHITE)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>]
@end example

@item 
negating a flag or flag set returns a new flag/flag set with the
corresponding positive integer value:

@example
>>> Color.BLUE
<Color.BLUE: 4>

>>> ~Color.BLUE
<Color.RED|GREEN: 3>
@end example

@item 
names of pseudo-flags are constructed from their members” names:

@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 
multi-bit flags, aka aliases, can be returned from operations:

@example
>>> Color.RED | Color.BLUE
<Color.PURPLE: 5>

>>> Color(7)  # or Color(-1)
<Color.WHITE: 7>

>>> Color(0)
<Color.BLACK: 0>
@end example

@item 
membership / containment checking: zero-valued flags are always considered
to be contained:

@example
>>> Color.BLACK in Color.WHITE
True
@end example

otherwise, only if all bits of one flag are in the other flag will True
be returned:

@example
>>> Color.PURPLE in Color.WHITE
True

>>> Color.GREEN in Color.PURPLE
False
@end example
@end itemize

There is a new boundary mechanism that controls how out-of-range / invalid
bits are handled: @code{STRICT}, @code{CONFORM}, @code{EJECT}, and @code{KEEP}:


@itemize *

@item 
STRICT –> raises an exception when presented with invalid values

@item 
CONFORM –> discards any invalid bits

@item 
EJECT –> lose Flag status and become a normal int with the given value

@item 
KEEP –> keep the extra bits


@itemize -

@item 
keeps Flag status and extra bits

@item 
extra bits do not show up in iteration

@item 
extra bits do show up in repr() and str()
@end itemize
@end itemize

The default for Flag is @code{STRICT}, the default for @code{IntFlag} is @code{EJECT},
and the default for @code{_convert_} is @code{KEEP} (see @code{ssl.Options} for an
example of when @code{KEEP} is needed).

@node How are Enums and Flags different?,Enum Cookbook,Finer Points,Enum HOWTO
@anchor{howto/enum enum-class-differences}@anchor{2c3a}@anchor{howto/enum how-are-enums-and-flags-different}@anchor{5aad}
@subsection How are Enums and Flags different?


Enums have a custom metaclass that affects many aspects of both derived @ref{a21,,Enum}
classes and their instances (members).

@menu
* Enum Classes:: 
* Flag Classes:: 
* Enum Members (aka instances): Enum Members aka instances. 
* Flag Members:: 

@end menu

@node Enum Classes,Flag Classes,,How are Enums and Flags different?
@anchor{howto/enum enum-classes}@anchor{5aae}
@subsubsection Enum Classes


The @ref{6fc,,EnumType} metaclass is responsible for providing the
@ref{175c,,__contains__()}, @ref{1935,,__dir__()}, @ref{102d,,__iter__()} and other methods that
allow one to do things with an @ref{a21,,Enum} class that fail on a typical
class, such as @code{list(Color)} or @code{some_enum_var in Color}.  @code{EnumType} is
responsible for ensuring that various other methods on the final @code{Enum}
class are correct (such as @ref{982,,__new__()}, @ref{118d,,__getnewargs__()},
@ref{a0f,,__str__()} and @ref{1bc,,__repr__()}).

@node Flag Classes,Enum Members aka instances,Enum Classes,How are Enums and Flags different?
@anchor{howto/enum flag-classes}@anchor{5aaf}
@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{a21,,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 Enum Members aka instances,Flag Members,Flag Classes,How are Enums and Flags different?
@anchor{howto/enum enum-members-aka-instances}@anchor{5ab0}
@subsubsection Enum Members (aka instances)


The most interesting thing about enum members is that they are singletons.
@ref{6fc,,EnumType} creates them all while it is creating the enum class itself,
and then puts a custom @ref{982,,__new__()} in place to ensure that no new ones are
ever instantiated by returning only the existing member instances.

@node Flag Members,,Enum Members aka instances,How are Enums and Flags different?
@anchor{howto/enum flag-members}@anchor{5ab1}
@subsubsection Flag Members


Flag members can be iterated over just like the @ref{a14,,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,Subclassing EnumType,How are Enums and Flags different?,Enum HOWTO
@anchor{howto/enum enum-cookbook}@anchor{2c39}@anchor{howto/enum id2}@anchor{5ab2}
@subsection Enum Cookbook


While @ref{a21,,Enum}, @ref{109d,,IntEnum}, @ref{a0d,,StrEnum}, @ref{a14,,Flag}, and
@ref{105d,,IntFlag} are expected to cover the majority of use-cases, they cannot
cover them all.  Here are recipes for some different types of enumerations
that can be used directly, or as examples for creating one’s own.

@menu
* Omitting values:: 
* OrderedEnum:: 
* DuplicateFreeEnum:: 
* MultiValueEnum:: 
* Planet:: 
* TimePeriod:: 

@end menu

@node Omitting values,OrderedEnum,,Enum Cookbook
@anchor{howto/enum omitting-values}@anchor{5ab3}
@subsubsection Omitting values


In many use-cases, one doesn’t care what the actual value of an enumeration
is. There are several ways to define this type of simple enumeration:


@itemize -

@item 
use instances of @ref{105e,,auto} for the value

@item 
use instances of @ref{e4d,,object} as the value

@item 
use a descriptive string as the value

@item 
use a tuple as the value and a custom @ref{982,,__new__()} to replace the
tuple with an @ref{326,,int} value
@end itemize

Using any of these methods signifies to the user that these values are not
important, and also enables one to add, remove, or reorder members without
having to renumber the remaining members.

@menu
* Using auto:: 
* Using object:: 
* Using a descriptive string:: 
* Using a custom __new__(): Using a custom __new__. 

@end menu

@node Using auto,Using object,,Omitting values
@anchor{howto/enum using-auto}@anchor{5ab4}
@subsubsection Using @code{auto}


Using @ref{105e,,auto} would look like:

@example
>>> class Color(Enum):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.GREEN
<Color.GREEN: 3>
@end example

@node Using object,Using a descriptive string,Using auto,Omitting values
@anchor{howto/enum using-object}@anchor{5ab5}
@subsubsection Using @code{object}


Using @ref{e4d,,object} would look like:

@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{1bc,,__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 Using a descriptive string,Using a custom __new__,Using object,Omitting values
@anchor{howto/enum using-a-descriptive-string}@anchor{5ab6}
@subsubsection Using a descriptive string


Using a string as the value would look like:

@example
>>> class Color(Enum):
...     RED = 'stop'
...     GREEN = 'go'
...     BLUE = 'too fast!'
...
>>> Color.GREEN
<Color.GREEN: 'go'>
@end example

@node Using a custom __new__,,Using a descriptive string,Omitting values
@anchor{howto/enum using-a-custom-new}@anchor{5ab7}
@subsubsection Using a custom @code{__new__()}


Using an auto-numbering @ref{982,,__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

To make a more general purpose @code{AutoNumber}, add @code{*args} to the 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

Then when you inherit from @code{AutoNumber} you can write your own @code{__init__}
to handle any extra arguments:

@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 Σημείωση 
The @ref{982,,__new__()} method, if defined, is used during creation of the Enum
members; it is then replaced by Enum’s @code{__new__()} which is used after
class creation for lookup of existing members.
@end quotation
@end cartouche

@cartouche
@quotation Προειδοποίηση 
`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 OrderedEnum,DuplicateFreeEnum,Omitting values,Enum Cookbook
@anchor{howto/enum orderedenum}@anchor{5a9b}
@subsubsection OrderedEnum


An ordered enumeration that is not based on @ref{109d,,IntEnum} and so maintains
the normal @ref{a21,,Enum} invariants (such as not being comparable to other
enumerations):

@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 DuplicateFreeEnum,MultiValueEnum,OrderedEnum,Enum Cookbook
@anchor{howto/enum duplicatefreeenum}@anchor{5ab8}
@subsubsection DuplicateFreeEnum


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 Σημείωση 
This is a useful example for subclassing Enum to add or change other
behaviors as well as disallowing aliases.  If the only desired change is
disallowing aliases, the @ref{2c3d,,unique()} decorator can be used instead.
@end quotation
@end cartouche

@node MultiValueEnum,Planet,DuplicateFreeEnum,Enum Cookbook
@anchor{howto/enum multi-value-enum}@anchor{2c56}@anchor{howto/enum multivalueenum}@anchor{5ab9}
@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 Planet,TimePeriod,MultiValueEnum,Enum Cookbook
@anchor{howto/enum planet}@anchor{5a98}
@subsubsection Planet


If @ref{982,,__new__()} or @ref{2fa,,__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 TimePeriod,,Planet,Enum Cookbook
@anchor{howto/enum enum-time-period}@anchor{2c4f}@anchor{howto/enum timeperiod}@anchor{5aba}
@subsubsection TimePeriod


An example to show the @ref{2c4e,,_ignore_} attribute in use:

@example
>>> import datetime as dt
>>> class Period(dt.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 Subclassing EnumType,,Enum Cookbook,Enum HOWTO
@anchor{howto/enum enumtype-examples}@anchor{2c3f}@anchor{howto/enum subclassing-enumtype}@anchor{5abb}
@subsection Subclassing EnumType


While most enum needs can be met by customizing @ref{a21,,Enum} subclasses,
either with class decorators or custom functions, @ref{6fc,,EnumType} can be
subclassed to provide a different Enum experience.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Functional Programming HOWTO,Logging HOWTO,Enum HOWTO,Python HOWTOs
@anchor{howto/functional doc}@anchor{5abc}@anchor{howto/functional functional-howto}@anchor{5abd}@anchor{howto/functional functional-programming-howto}@anchor{5abe}@anchor{howto/functional translation-repo}@anchor{5abf}
@section Functional Programming HOWTO


@*Author: 
A. M. Kuchling


@*Release: 
0.32


In this document, we’ll take a tour of Python’s features suitable for
implementing programs in a functional style.  After an introduction to the
concepts of functional programming, we’ll look at language features such as
@ref{6ce,,iterator}s and @ref{1409,,generator}s and relevant library modules such as
@ref{84,,itertools} and @ref{62,,functools}.

@menu
* Introduction: Introduction<13>. 
* Iterators:: 
* Generator expressions and list comprehensions:: 
* Generators:: 
* Built-in functions:: 
* The itertools module:: 
* The functools module:: 
* Small functions and the lambda expression:: 
* Revision History and Acknowledgements:: 
* References:: 

@end menu

@node Introduction<13>,Iterators,,Functional Programming HOWTO
@anchor{howto/functional introduction}@anchor{5ac0}
@subsection Introduction


This section explains the basic concept of functional programming; if
you’re just interested in learning about Python language features,
skip to the next section on @ref{5ac1,,Iterators}.

Programming languages support decomposing problems in several different ways:


@itemize *

@item 
Most programming languages are `procedural': programs are lists of
instructions that tell the computer what to do with the program’s input.  C,
Pascal, and even Unix shells are procedural languages.

@item 
In `declarative' languages, you write a specification that describes the
problem to be solved, and the language implementation figures out how to
perform the computation efficiently.  SQL is the declarative language you’re
most likely to be familiar with; a SQL query describes the data set you want
to retrieve, and the SQL engine decides whether to scan tables or use indexes,
which subclauses should be performed first, etc.

@item 
`Object-oriented' programs manipulate collections of objects.  Objects have
internal state and support methods that query or modify this internal state in
some way. Smalltalk and Java are object-oriented languages.  C++ and Python
are languages that support object-oriented programming, but don’t force the
use of object-oriented features.

@item 
`Functional' programming decomposes a problem into a set of functions.
Ideally, functions only take inputs and produce outputs, and don’t have any
internal state that affects the output produced for a given input.  Well-known
functional languages include the ML family (Standard ML, OCaml, and other
variants) and Haskell.
@end itemize

The designers of some computer languages choose to emphasize one
particular approach to programming.  This often makes it difficult to
write programs that use a different approach.  Other languages are
multi-paradigm languages that support several different approaches.
Lisp, C++, and Python are multi-paradigm; you can write programs or
libraries that are largely procedural, object-oriented, or functional
in all of these languages.  In a large program, different sections
might be written using different approaches; the GUI might be
object-oriented while the processing logic is procedural or
functional, for example.

In a functional program, input flows through a set of functions. Each function
operates on its input and produces some output.  Functional style discourages
functions with side effects that modify internal state or make other changes
that aren’t visible in the function’s return value.  Functions that have no side
effects at all are called `purely functional'.  Avoiding side effects means
not using data structures that get updated as a program runs; every function’s
output must only depend on its input.

Some languages are very strict about purity and don’t even have assignment
statements such as @code{a=3} or @code{c = a + b}, but it’s difficult to avoid all
side effects, such as printing to the screen or writing to a disk file. Another
example is a call to the @ref{131f,,print()} or @ref{a8c,,time.sleep()} function, neither
of which returns a useful value. Both are called only for their side effects
of sending some text to the screen or pausing execution for a second.

Python programs written in functional style usually won’t go to the extreme of
avoiding all I/O or all assignments; instead, they’ll provide a
functional-appearing interface but will use non-functional features internally.
For example, the implementation of a function will still use assignments to
local variables, but won’t modify global variables or have other side effects.

Functional programming can be considered the opposite of object-oriented
programming.  Objects are little capsules containing some internal state along
with a collection of method calls that let you modify this state, and programs
consist of making the right set of state changes.  Functional programming wants
to avoid state changes as much as possible and works with data flowing between
functions.  In Python you might combine the two approaches by writing functions
that take and return instances representing objects in your application (e-mail
messages, transactions, etc.).

Functional design may seem like an odd constraint to work under.  Why should you
avoid objects and side effects?  There are theoretical and practical advantages
to the functional style:


@itemize *

@item 
Formal provability.

@item 
Modularity.

@item 
Composability.

@item 
Ease of debugging and testing.
@end itemize

@menu
* Formal provability:: 
* Modularity:: 
* Ease of debugging and testing:: 
* Composability:: 

@end menu

@node Formal provability,Modularity,,Introduction<13>
@anchor{howto/functional formal-provability}@anchor{5ac2}
@subsubsection Formal provability


A theoretical benefit is that it’s easier to construct a mathematical proof that
a functional program is correct.

For a long time researchers have been interested in finding ways to
mathematically prove programs correct.  This is different from testing a program
on numerous inputs and concluding that its output is usually correct, or reading
a program’s source code and concluding that the code looks right; the goal is
instead a rigorous proof that a program produces the right result for all
possible inputs.

The technique used to prove programs correct is to write down `invariants',
properties of the input data and of the program’s variables that are always
true.  For each line of code, you then show that if invariants X and Y are true
`before' the line is executed, the slightly different invariants X” and Y” are
true `after' the line is executed.  This continues until you reach the end of
the program, at which point the invariants should match the desired conditions
on the program’s output.

Functional programming’s avoidance of assignments arose because assignments are
difficult to handle with this technique; assignments can break invariants that
were true before the assignment without producing any new invariants that can be
propagated onward.

Unfortunately, proving programs correct is largely impractical and not relevant
to Python software. Even trivial programs require proofs that are several pages
long; the proof of correctness for a moderately complicated program would be
enormous, and few or none of the programs you use daily (the Python interpreter,
your XML parser, your web browser) could be proven correct.  Even if you wrote
down or generated a proof, there would then be the question of verifying the
proof; maybe there’s an error in it, and you wrongly believe you’ve proved the
program correct.

@node Modularity,Ease of debugging and testing,Formal provability,Introduction<13>
@anchor{howto/functional modularity}@anchor{5ac3}
@subsubsection Modularity


A more practical benefit of functional programming is that it forces you to
break apart your problem into small pieces.  Programs are more modular as a
result.  It’s easier to specify and write a small function that does one thing
than a large function that performs a complicated transformation.  Small
functions are also easier to read and to check for errors.

@node Ease of debugging and testing,Composability,Modularity,Introduction<13>
@anchor{howto/functional ease-of-debugging-and-testing}@anchor{5ac4}
@subsubsection Ease of debugging and testing


Testing and debugging a functional-style program is easier.

Debugging is simplified because functions are generally small and clearly
specified.  When a program doesn’t work, each function is an interface point
where you can check that the data are correct.  You can look at the intermediate
inputs and outputs to quickly isolate the function that’s responsible for a bug.

Testing is easier because each function is a potential subject for a unit test.
Functions don’t depend on system state that needs to be replicated before
running a test; instead you only have to synthesize the right input and then
check that the output matches expectations.

@node Composability,,Ease of debugging and testing,Introduction<13>
@anchor{howto/functional composability}@anchor{5ac5}
@subsubsection Composability


As you work on a functional-style program, you’ll write a number of functions
with varying inputs and outputs.  Some of these functions will be unavoidably
specialized to a particular application, but others will be useful in a wide
variety of programs.  For example, a function that takes a directory path and
returns all the XML files in the directory, or a function that takes a filename
and returns its contents, can be applied to many different situations.

Over time you’ll form a personal library of utilities.  Often you’ll assemble
new programs by arranging existing functions in a new configuration and writing
a few functions specialized for the current task.

@node Iterators,Generator expressions and list comprehensions,Introduction<13>,Functional Programming HOWTO
@anchor{howto/functional functional-howto-iterators}@anchor{5ac1}@anchor{howto/functional iterators}@anchor{5ac6}
@subsection Iterators


I’ll start by looking at a Python language feature that’s an important
foundation for writing functional-style programs: iterators.

An iterator is an object representing a stream of data; this object returns the
data one element at a time.  A Python iterator must support a method called
@ref{1672,,__next__()} that takes no arguments and always returns the next
element of the stream.  If there are no more elements in the stream,
@code{__next__()} must raise the @ref{fba,,StopIteration} exception.
Iterators don’t have to be finite, though; it’s perfectly reasonable to write
an iterator that produces an infinite stream of data.

The built-in @ref{bb4,,iter()} function takes an arbitrary object and tries to return
an iterator that will return the object’s contents or elements, raising
@ref{291,,TypeError} if the object doesn’t support iteration.  Several of Python’s
built-in data types support iteration, the most common being lists and
dictionaries.  An object is called @ref{15ce,,iterable} if you can get an iterator
for it.

You can experiment with the iteration interface manually:

@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 expects iterable objects in several different contexts, the most
important being the @ref{321,,for} statement.  In the statement @code{for X in Y},
Y must be an iterator or some object for which @ref{bb4,,iter()} can create an
iterator.  These two statements are equivalent:

@example
for i in iter(obj):
    print(i)

for i in obj:
    print(i)
@end example

Iterators can be materialized as lists or tuples by using the @ref{4d9,,list()} or
@ref{1ce,,tuple()} constructor functions:

@example
>>> L = [1, 2, 3]
>>> iterator = iter(L)
>>> t = tuple(iterator)
>>> t
(1, 2, 3)
@end example

Sequence unpacking also supports iterators: if you know an iterator will return
N elements, you can unpack them into an N-tuple:

@example
>>> L = [1, 2, 3]
>>> iterator = iter(L)
>>> a, b, c = iterator
>>> a, b, c
(1, 2, 3)
@end example

Built-in functions such as @ref{12ba,,max()} and @ref{12b9,,min()} can take a single
iterator argument and will return the largest or smallest element.  The @code{"in"}
and @code{"not in"} operators also support iterators: @code{X in iterator} is true if
X is found in the stream returned by the iterator.  You’ll run into obvious
problems if the iterator is infinite; @code{max()}, @code{min()}
will never return, and if the element X never appears in the stream, the
@code{"in"} and @code{"not in"} operators won’t return either.

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.  Iterator objects
can optionally provide these additional capabilities, but the iterator protocol
only specifies the @ref{1672,,__next__()} method.  Functions may therefore
consume all of the iterator’s output, and if you need to do something different
with the same stream, you’ll have to create a new iterator.

@menu
* Data Types That Support Iterators:: 

@end menu

@node Data Types That Support Iterators,,,Iterators
@anchor{howto/functional data-types-that-support-iterators}@anchor{5ac7}
@subsubsection Data Types That Support Iterators


We’ve already seen how lists and tuples support iterators.  In fact, any Python
sequence type, such as strings, will automatically support creation of an
iterator.

Calling @ref{bb4,,iter()} on a dictionary returns an iterator that will loop over the
dictionary’s 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])
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

Note that starting with Python 3.7, dictionary iteration order is guaranteed
to be the same as the insertion order. In earlier versions, the behaviour was
unspecified and could vary between implementations.

Applying @ref{bb4,,iter()} to a dictionary always loops over the keys, but
dictionaries have methods that return other iterators.  If you want to iterate
over values or key/value pairs, you can explicitly call the
@ref{bae,,values()} or @ref{baf,,items()} methods to get an appropriate
iterator.

The @ref{188,,dict()} constructor can accept an iterator that returns a finite stream
of @code{(key, value)} tuples:

@example
>>> L = [('Italy', 'Rome'), ('France', 'Paris'), ('US', 'Washington DC')]
>>> dict(iter(L))
@{'Italy': 'Rome', 'France': 'Paris', 'US': 'Washington DC'@}
@end example

Files also support iteration by calling the @ref{2296,,readline()}
method until there are no more lines in the file.  This means you can read each
line of a file like this:

@example
for line in file:
    # do something for each line
    ...
@end example

Sets can take their contents from an iterable and let you iterate over the set’s
elements:

@example
>>> S = @{2, 3, 5, 7, 11, 13@}
>>> for i in S:
...     print(i)
2
3
5
7
11
13
@end example

@node Generator expressions and list comprehensions,Generators,Iterators,Functional Programming HOWTO
@anchor{howto/functional generator-expressions-and-list-comprehensions}@anchor{5ac8}
@subsection Generator expressions and list comprehensions


Two common operations on an iterator’s output are 1) performing some operation
for every element, 2) selecting a subset of elements that meet some condition.
For example, given a list of strings, you might want to strip off trailing
whitespace from each line or extract all the strings containing a given
substring.

List comprehensions and generator expressions (short form: «listcomps» and
«genexps») are a concise notation for such operations, borrowed from the
functional programming language Haskell (@indicateurl{https://www.haskell.org/}).  You can strip
all the whitespace from a stream of strings with the following code:

@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

You can select only certain elements by adding an @code{"if"} condition:

@example
>>> stripped_list = [line.strip() for line in line_list
...                  if line != ""]
@end example

With a list comprehension, you get back a Python list; @code{stripped_list} is a
list containing the resulting lines, not an iterator.  Generator expressions
return an iterator that computes the values as necessary, not needing to
materialize all the values at once.  This means that list comprehensions aren’t
useful if you’re working with iterators that return an infinite stream or a very
large amount of data.  Generator expressions are preferable in these situations.

Generator expressions are surrounded by parentheses («()») and list
comprehensions are surrounded by square brackets («[]»).  Generator expressions
have the form:

@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

Again, for a list comprehension only the outside brackets are different (square
brackets instead of parentheses).

The elements of the generated output will be the successive values of
@code{expression}.  The @code{if} clauses are all optional; if present, @code{expression}
is only evaluated and added to the result when @code{condition} is true.

Generator expressions always have to be written inside parentheses, but the
parentheses signalling a function call also count.  If you want to create an
iterator that will be immediately passed to a function you can write:

@example
obj_total = sum(obj.count for obj in list_all_objects())
@end example

The @code{for...in} clauses contain the sequences to be iterated over.  The
sequences do not have to be the same length, because they are iterated over from
left to right, `not' in parallel.  For each element in @code{sequence1},
@code{sequence2} is looped over from the beginning.  @code{sequence3} is then looped
over for each resulting pair of elements from @code{sequence1} and @code{sequence2}.

To put it another way, a list comprehension or generator expression is
equivalent to the following Python code:

@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

This means that when there are multiple @code{for...in} clauses but no @code{if}
clauses, the length of the resulting output will be equal to the product of the
lengths of all the sequences.  If you have two lists of length 3, the output
list is 9 elements long:

@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

To avoid introducing an ambiguity into Python’s grammar, if @code{expression} is
creating a tuple, it must be surrounded with parentheses.  The first list
comprehension below is a syntax error, while the second one is correct:

@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 Generators,Built-in functions,Generator expressions and list comprehensions,Functional Programming HOWTO
@anchor{howto/functional generators}@anchor{5ac9}
@subsection Generators


Generators are a special class of functions that simplify the task of writing
iterators.  Regular functions compute a value and return it, but generators
return an iterator that returns a stream of values.

You’re doubtless familiar with how regular 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 @code{return} statement, the local
variables are destroyed and the value is returned to the caller.  A later call
to the same function creates a new private namespace and a fresh 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

Any function containing a @ref{d93,,yield} keyword is a generator function;
this is detected by Python’s @ref{6b3,,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 @code{yield} expression, the generator outputs the value of @code{i}, similar to a
@code{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 @ref{229e,,__next__()} method, the function will resume
executing.

Here’s a sample usage of the @code{generate_ints()} generator:

@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

You could equally write @code{for i in generate_ints(5)}, or @code{a, b, c =
generate_ints(3)}.

Inside a generator function, @code{return value} causes @code{StopIteration(value)}
to be raised from the @ref{229e,,__next__()} method.  Once this happens, or
the bottom of the function is reached, the procession of values ends and the
generator cannot yield any further values.

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{1672,,__next__()} method increment @code{self.count} and
return it.
However, for a moderately complicated generator, writing a corresponding class
can be much messier.

The test suite included with Python’s library,
Lib/test/test_generators.py@footnote{https://github.com/python/cpython/tree/main/Lib/test/test_generators.py}, contains
a number of more interesting examples.  Here’s one generator that 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{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 (finding a route that takes a knight to every
square of an NxN chessboard without visiting any square twice).

@menu
* Passing values into a generator:: 

@end menu

@node Passing values into a generator,,,Generators
@anchor{howto/functional passing-values-into-a-generator}@anchor{5aca}
@subsubsection Passing values into a generator


In Python 2.4 and earlier, generators only produced 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.  You could hack
together this ability by making the generator look at a global variable or by
passing in some mutable object that callers then modify, but these approaches
are messy.

In Python 2.5 there’s a simple way to pass values into a generator.
@ref{d93,,yield} became 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 @code{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 @code{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 @ref{260f,,send(value)} method.  This method resumes the generator’s code and the
@code{yield} expression returns the specified value.  If the regular
@ref{229e,,__next__()} method is called, the @code{yield} returns @code{None}.

Here’s a simple counter that increments by 1 and allows 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)
>>> 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

Because @code{yield} will often be returning @code{None}, you should always check for
this case.  Don’t just use its value in expressions unless you’re sure that the
@ref{260f,,send()} method will be the only method used to resume your
generator function.

In addition to @ref{260f,,send()}, there are two other methods on
generators:


@itemize *

@item 
@ref{905,,throw(value)} is used to
raise an exception inside the generator; the exception is raised by the
@code{yield} expression where the generator’s execution is paused.

@item 
@ref{199e,,close()} sends a @ref{176a,,GeneratorExit} exception to the
generator to terminate the iteration.  On receiving this exception, the
generator’s code must either raise @code{GeneratorExit} or
@ref{fba,,StopIteration}; catching the exception and doing anything else is
illegal and will trigger a @ref{30d,,RuntimeError}.  @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{176a,,GeneratorExit} occurs, I suggest
using a @code{try: ... finally:} suite instead of catching @code{GeneratorExit}.
@end itemize

The cumulative effect of these changes is to turn generators from one-way
producers of information into both producers and consumers.

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 @code{return} statement), but coroutines can be entered, exited,
and resumed at many different points (the @code{yield} statements).

@node Built-in functions,The itertools module,Generators,Functional Programming HOWTO
@anchor{howto/functional built-in-functions}@anchor{5acb}
@subsection Built-in functions


Let’s look in more detail at built-in functions often used with iterators.

Two of Python’s built-in functions, @ref{43e,,map()} and @ref{c3b,,filter()} duplicate the
features of generator expressions:


@table @asis

@item @ref{43e,,map(f@comma{} iterA@comma{} iterB@comma{} ...)} returns an iterator over the sequence

@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

You can of course achieve the same effect with a list comprehension.

@ref{c3b,,filter(predicate@comma{} iter)} returns an iterator over all the
sequence elements that meet a certain condition, and is similarly duplicated by
list comprehensions.  A `predicate' is a function that returns the truth
value of some condition; for use with @code{filter()}, the predicate must take a
single value.

@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

This can also be written as a list comprehension:

@example
>>> list(x for x in range(10) if is_even(x))
[0, 2, 4, 6, 8]
@end example

@ref{1823,,enumerate(iter@comma{} start=0)} counts off the elements in the
iterable returning 2-tuples containing the count (from `start') and
each element.

@example
>>> for item in enumerate(['subject', 'verb', 'object']):
...     print(item)
(0, 'subject')
(1, 'verb')
(2, 'object')
@end example

@ref{1823,,enumerate()} is often used when looping through a list and recording the
indexes at which certain conditions are met:

@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{f8c,,sorted(iterable@comma{} key=None@comma{} reverse=False)} collects all the
elements of the iterable into a list, sorts the list, and returns the sorted
result.  The `key' and `reverse' arguments are passed through to the
constructed list’s @ref{f8d,,sort()} method.

@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

(For a more detailed discussion of sorting, see the @ref{27d9,,Sorting Techniques}.)

The @ref{17c3,,any(iter)} and @ref{17c4,,all(iter)} built-ins look at the
truth values of an iterable’s contents.  @code{any()} returns @code{True} if any element
in the iterable is a true value, and @code{all()} returns @code{True} if all of the
elements are true values:

@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{43f,,zip(iterA@comma{} iterB@comma{} ...)} takes one element from each iterable and
returns them in a tuple:

@example
zip(['a', 'b', 'c'], (1, 2, 3)) =>
  ('a', 1), ('b', 2), ('c', 3)
@end example

It doesn’t construct an in-memory list and exhaust all the input iterators
before returning; instead tuples are constructed and returned only if they’re
requested.  (The technical term for this behaviour is lazy evaluation@footnote{https://en.wikipedia.org/wiki/Lazy_evaluation}.)

This iterator is intended to be used with iterables that are all of the same
length.  If the iterables are of different lengths, the resulting stream will be
the same length as the shortest iterable.

@example
zip(['a', 'b'], (1, 2, 3)) =>
  ('a', 1), ('b', 2)
@end example

You should avoid doing this, though, because an element may be taken from the
longer iterators and discarded.  This means you can’t go on to use the iterators
further because you risk skipping a discarded element.

@node The itertools module,The functools module,Built-in functions,Functional Programming HOWTO
@anchor{howto/functional the-itertools-module}@anchor{5acc}
@subsection The itertools module


The @ref{84,,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.

The module’s functions fall into a few broad classes:


@itemize *

@item 
Functions that create a new iterator based on an existing iterator.

@item 
Functions for treating an iterator’s elements as function arguments.

@item 
Functions for selecting portions of an iterator’s output.

@item 
A function for grouping an iterator’s output.
@end itemize

@menu
* Creating new iterators:: 
* Calling functions on elements:: 
* Selecting elements:: 
* Combinatoric functions:: 
* Grouping elements:: 

@end menu

@node Creating new iterators,Calling functions on elements,,The itertools module
@anchor{howto/functional creating-new-iterators}@anchor{5acd}
@subsubsection Creating new iterators


@ref{1628,,itertools.count(start@comma{} step)} returns an infinite
stream of evenly spaced values.  You can optionally supply the starting number,
which defaults to 0, and the interval between numbers, which defaults to 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{1a41,,itertools.cycle(iter)} saves a copy of the contents of
a provided iterable and returns a new iterator that returns its elements from
first to last.  The new iterator will repeat these elements infinitely.

@example
itertools.cycle([1, 2, 3, 4, 5]) =>
  1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ...
@end example

@ref{1a81,,itertools.repeat(elem@comma{} [n])} returns the provided
element `n' times, or returns the element endlessly if `n' is not provided.

@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{190,,itertools.chain(iterA@comma{} iterB@comma{} ...)} takes an arbitrary
number of iterables as input, and returns all the elements of the first
iterator, then all the elements of the second, and so on, until all of the
iterables have been exhausted.

@example
itertools.chain(['a', 'b', 'c'], (1, 2, 3)) =>
  a, b, c, 1, 2, 3
@end example

@ref{f09,,itertools.islice(iter@comma{} [start]@comma{} stop@comma{} [step])} returns
a stream that’s a slice of the iterator.  With a single `stop' argument, it
will return the first `stop' elements.  If you supply a starting index, you’ll
get `stop-start' elements, and if you supply a value for `step', elements
will be skipped accordingly.  Unlike Python’s string and list slicing, you can’t
use negative values for `start', `stop', or `step'.

@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{2dc2,,itertools.tee(iter@comma{} [n])} replicates an iterator; it
returns `n' independent iterators that will all return the contents of the
source iterator.
If you don’t supply a value for `n', the default is 2.  Replicating iterators
requires saving some of the contents of the source iterator, so this can consume
significant memory if the iterator is large and one of the new iterators is
consumed more than the others.

@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 Calling functions on elements,Selecting elements,Creating new iterators,The itertools module
@anchor{howto/functional calling-functions-on-elements}@anchor{5ace}
@subsubsection Calling functions on elements


The @ref{a3,,operator} module contains a set of functions corresponding to Python’s
operators.  Some examples are @ref{2de9,,operator.add(a@comma{} b)} (adds
two values), @ref{2dd9,,operator.ne(a@comma{} b)} (same as @code{a != b}), and
@ref{11e6,,operator.attrgetter('id')}
(returns a callable that fetches the @code{.id} attribute).

@ref{1490,,itertools.starmap(func@comma{} iter)} assumes that the
iterable will return a stream of tuples, and calls `func' using these tuples as
the 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 Selecting elements,Combinatoric functions,Calling functions on elements,The itertools module
@anchor{howto/functional selecting-elements}@anchor{5acf}
@subsubsection Selecting elements


Another group of functions chooses a subset of an iterator’s elements based on a
predicate.

@ref{27c7,,itertools.filterfalse(predicate@comma{} iter)} is the
opposite of @ref{c3b,,filter()}, returning all elements for which the predicate
returns false:

@example
itertools.filterfalse(is_even, itertools.count()) =>
  1, 3, 5, 7, 9, 11, 13, 15, ...
@end example

@ref{2dc1,,itertools.takewhile(predicate@comma{} iter)} returns
elements for as long as the predicate returns true.  Once the predicate returns
false, the iterator will signal the end of its results.

@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{2dc0,,itertools.dropwhile(predicate@comma{} iter)} discards
elements while the predicate returns true, and then returns the rest of the
iterable’s results.

@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{1627,,itertools.compress(data@comma{} selectors)} takes two
iterators and returns only those elements of `data' for which the corresponding
element of `selectors' is true, stopping whenever either one is exhausted:

@example
itertools.compress([1, 2, 3, 4, 5], [True, True, False, False, True]) =>
   1, 2, 5
@end example

@node Combinatoric functions,Grouping elements,Selecting elements,The itertools module
@anchor{howto/functional combinatoric-functions}@anchor{5ad0}
@subsubsection Combinatoric functions


The @ref{16b6,,itertools.combinations(iterable@comma{} r)}
returns an iterator giving all possible `r'-tuple combinations of the
elements contained in `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

The elements within each tuple remain in the same order as
`iterable' returned them.  For example, the number 1 is always before
2, 3, 4, or 5 in the examples above.  A similar function,
@ref{1961,,itertools.permutations(iterable@comma{} r=None)},
removes this constraint on the order, returning all possible
arrangements of length `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

If you don’t supply a value for `r' the length of the iterable is used,
meaning that all the elements are permuted.

Note that these functions produce all of the possible combinations by
position and don’t require that the contents of `iterable' are unique:

@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

The identical tuple @code{('a', 'a', 'b')} occurs twice, but the two “a”
strings came from different positions.

The @ref{1626,,itertools.combinations_with_replacement(iterable@comma{} r)}
function relaxes a different constraint: elements can be repeated
within a single tuple.  Conceptually an element is selected for the
first position of each tuple and then is replaced before the second
element is selected.

@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 Grouping elements,,Combinatoric functions,The itertools module
@anchor{howto/functional grouping-elements}@anchor{5ad1}
@subsubsection Grouping elements


The last function I’ll discuss, @ref{192a,,itertools.groupby(iter@comma{} key_func=None)}, is the most complicated.  @code{key_func(elem)} is a function
that can compute a key value for each element returned by the iterable.  If you
don’t supply a key function, the key is simply each element itself.

@ref{192a,,groupby()} collects all the consecutive elements from the
underlying iterable that have the same key value, and returns a stream of
2-tuples containing a key value and an iterator for the elements with that key.

@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{192a,,groupby()} assumes that the underlying iterable’s contents will
already be sorted based on the key.  Note that the returned iterators also use
the underlying iterable, so you have to consume the results of iterator-1 before
requesting iterator-2 and its corresponding key.

@node The functools module,Small functions and the lambda expression,The itertools module,Functional Programming HOWTO
@anchor{howto/functional the-functools-module}@anchor{5ad2}
@subsection The functools module


The @ref{62,,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{4a6,,functools.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 may wish to create a new function
@code{g(b, c)} that’s equivalent to @code{f(1, b, c)}; you’re filling in a value for
one of @code{f()}”s parameters.  This is called «partial function application».

The constructor for @ref{4a6,,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 @code{function} with the
filled-in arguments.

Here’s a small but realistic example:

@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{153,,functools.reduce(func@comma{} iter@comma{} [initial_value])}
cumulatively performs an operation on all the iterable’s elements and,
therefore, can’t be applied to infinite iterables. `func' must be a function
that takes two elements and returns a single value.  @code{functools.reduce()}
takes the first two elements A and B returned by the iterator and calculates
@code{func(A, B)}.  It then requests the third element, C, calculates
@code{func(func(A, B), C)}, combines this result with the fourth element returned,
and continues until the iterable is exhausted.  If the iterable returns no
values at all, a @ref{291,,TypeError} exception is raised.  If the initial value is
supplied, it’s used as a starting point and @code{func(initial_value, A)} is the
first calculation.

@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

If you use @ref{2de9,,operator.add()} with @ref{153,,functools.reduce()}, you’ll add up all the
elements of the iterable.  This case is so common that there’s a special
built-in called @ref{881,,sum()} to compute it:

@example
>>> import functools, operator
>>> functools.reduce(operator.add, [1, 2, 3, 4], 0)
10
>>> sum([1, 2, 3, 4])
10
>>> sum([])
0
@end example

For many uses of @ref{153,,functools.reduce()}, though, it can be clearer to just
write the obvious @ref{321,,for} loop:

@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{dbf,,itertools.accumulate(iterable@comma{} func=operator.add)}.  It performs the same calculation, but instead of
returning only the final result, @code{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
* The operator module:: 

@end menu

@node The operator module,,,The functools module
@anchor{howto/functional the-operator-module}@anchor{5ad3}
@subsubsection The operator module


The @ref{a3,,operator} module was mentioned earlier.  It contains a set of
functions corresponding to Python’s operators.  These functions are often useful
in functional-style code because they save you from writing trivial functions
that perform a single operation.

Some of the functions in this module are:


@itemize *

@item 
Math operations: @code{add()}, @code{sub()}, @code{mul()}, @code{floordiv()}, @code{abs()}, …

@item 
Logical operations: @code{not_()}, @code{truth()}.

@item 
Bitwise operations: @code{and_()}, @code{or_()}, @code{invert()}.

@item 
Comparisons: @code{eq()}, @code{ne()}, @code{lt()}, @code{le()}, @code{gt()}, and @code{ge()}.

@item 
Object identity: @code{is_()}, @code{is_not()}.
@end itemize

Consult the operator module’s documentation for a complete list.

@node Small functions and the lambda expression,Revision History and Acknowledgements,The functools module,Functional Programming HOWTO
@anchor{howto/functional small-functions-and-the-lambda-expression}@anchor{5ad4}
@subsection Small functions and the lambda expression


When writing functional-style programs, you’ll often need little functions that
act as predicates or that combine elements in some way.

If there’s a Python built-in or a module function that’s suitable, you don’t
need to define a new function at all:

@example
stripped_lines = [line.strip() for line in lines]
existing_files = filter(os.path.exists, file_list)
@end example

If the function you need doesn’t exist, you need to write it.  One way to write
small functions is to use the @ref{1642,,lambda} expression.  @code{lambda} takes a
number of parameters and an expression combining these parameters, and creates
an anonymous function that returns the value of the expression:

@example
adder = lambda x, y: x+y

print_assign = lambda name, value: name + '=' + str(value)
@end example

An alternative is to just use the @code{def} statement and define a function in the
usual way:

@example
def adder(x, y):
    return x + y

def print_assign(name, value):
    return name + '=' + str(value)
@end example

Which alternative is preferable?  That’s a style question; my usual course is to
avoid using @code{lambda}.

One reason for my preference is that @code{lambda} is quite limited in the
functions it can define.  The result has to be computable as a single
expression, which means you can’t have multiway @code{if... elif... else}
comparisons or @code{try... except} statements.  If you try to do too much in a
@code{lambda} statement, you’ll end up with an overly complicated expression that’s
hard to read.  Quick, what’s the following code doing?

@example
import functools
total = functools.reduce(lambda a, b: (0, a[1] + b[1]), items)[1]
@end example

You can figure it out, but it takes time to disentangle the expression to figure
out what’s going on.  Using a short nested @code{def} statements makes things a
little bit better:

@example
import functools
def combine(a, b):
    return 0, a[1] + b[1]

total = functools.reduce(combine, items)[1]
@end example

But it would be best of all if I had simply used a @code{for} loop:

@example
total = 0
for a, b in items:
    total += b
@end example

Or the @ref{881,,sum()} built-in and a generator expression:

@example
total = sum(b for a, b in items)
@end example

Many uses of @ref{153,,functools.reduce()} are clearer when written as @code{for} loops.

Fredrik Lundh once suggested the following set of rules for refactoring uses of
@code{lambda}:


@enumerate 

@item 
Write a lambda function.

@item 
Write a comment explaining what the heck that lambda does.

@item 
Study the comment for a while, and think of a name that captures the essence
of the comment.

@item 
Convert the lambda to a def statement, using that name.

@item 
Remove the comment.
@end enumerate

I really like these rules, but you’re free to disagree
about whether this lambda-free style is better.

@node Revision History and Acknowledgements,References,Small functions and the lambda expression,Functional Programming HOWTO
@anchor{howto/functional revision-history-and-acknowledgements}@anchor{5ad5}
@subsection Revision History and Acknowledgements


The author would like to thank the following people for offering suggestions,
corrections and assistance with various drafts of this article: Ian Bicking,
Nick Coghlan, Nick Efford, Raymond Hettinger, Jim Jewett, Mike Krell, Leandro
Lameiro, Jussi Salmela, Collin Winter, Blake Winton.

Version 0.1: posted June 30 2006.

Version 0.11: posted July 1 2006.  Typo fixes.

Version 0.2: posted July 10 2006.  Merged genexp and listcomp sections into one.
Typo fixes.

Version 0.21: Added more references suggested on the tutor mailing list.

Version 0.30: Adds a section on the @code{functional} module written by Collin
Winter; adds short section on the operator module; a few other edits.

@node References,,Revision History and Acknowledgements,Functional Programming HOWTO
@anchor{howto/functional references}@anchor{5ad6}
@subsection References


@menu
* General:: 
* Python-specific:: 
* Python documentation:: 

@end menu

@node General,Python-specific,,References
@anchor{howto/functional general}@anchor{5ad7}
@subsubsection General


`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://defmacro.org/2006/06/19/fp.html}: A general introduction to functional
programming that uses Java examples and has a lengthy historical introduction.

@indicateurl{https://en.wikipedia.org/wiki/Functional_programming}: General Wikipedia entry
describing functional programming.

@indicateurl{https://en.wikipedia.org/wiki/Coroutine}: Entry for coroutines.

@indicateurl{https://en.wikipedia.org/wiki/Partial_application}: Entry for the concept of partial function application.

@indicateurl{https://en.wikipedia.org/wiki/Currying}: Entry for the concept of currying.

@node Python-specific,Python documentation,General,References
@anchor{howto/functional python-specific}@anchor{5ad8}
@subsubsection Python-specific


@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 also wrote a 3-part series of articles on functional programming
for IBM’s DeveloperWorks site; see
part 1@footnote{https://developer.ibm.com/articles/l-prog/},
part 2@footnote{https://developer.ibm.com/tutorials/l-prog2/}, and
part 3@footnote{https://developer.ibm.com/tutorials/l-prog3/},

@node Python documentation,,Python-specific,References
@anchor{howto/functional python-documentation}@anchor{5ad9}
@subsubsection Python documentation


Documentation for the @ref{84,,itertools} module.

Documentation for the @ref{62,,functools} module.

Documentation for the @ref{a3,,operator} module.

@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» describes the new generator
features in 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])

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Logging HOWTO,Logging Cookbook,Functional Programming HOWTO,Python HOWTOs
@anchor{howto/logging doc}@anchor{5ada}@anchor{howto/logging id1}@anchor{5adb}@anchor{howto/logging logging-howto}@anchor{5adc}@anchor{howto/logging translation-repo}@anchor{5add}
@section Logging HOWTO


@*Author: 
Vinay Sajip <vinay_sajip at red-dove dot com>

@anchor{howto/logging logging-basic-tutorial}@anchor{159e}
This page contains tutorial information. For links to reference information and a
logging cookbook, please see @ref{5ade,,Other resources}.

@menu
* Basic Logging Tutorial:: 
* Advanced Logging Tutorial:: 
* Logging Levels: Logging Levels<2>. 
* Useful Handlers:: 
* Exceptions raised during logging:: 
* Using arbitrary objects as messages:: 
* Optimization:: 
* Other resources:: 

@end menu

@node Basic Logging Tutorial,Advanced Logging Tutorial,,Logging HOWTO
@anchor{howto/logging basic-logging-tutorial}@anchor{5adf}
@subsection Basic Logging Tutorial


Logging is a means of tracking events that happen when some software runs. The
software’s developer adds logging calls to their code to indicate that certain
events have occurred. An event is described by a descriptive message which can
optionally contain variable data (i.e. data that is potentially different for
each occurrence of the event). Events also have an importance which the
developer ascribes to the event; the importance can also be called the `level'
or `severity'.

@menu
* When to use logging:: 
* A simple example:: 
* Logging to a file:: 
* Logging variable data:: 
* Changing the format of displayed messages:: 
* Displaying the date/time in messages:: 
* Next Steps:: 

@end menu

@node When to use logging,A simple example,,Basic Logging Tutorial
@anchor{howto/logging when-to-use-logging}@anchor{5ae0}
@subsubsection When to use logging


You can access logging functionality by creating a logger via @code{logger =
logging.getLogger(__name__)}, and then calling the logger’s @ref{11de,,debug()},
@ref{33b6,,info()}, @ref{1c7a,,warning()}, @ref{33b8,,error()} and
@ref{11dd,,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

Task you want to perform

@tab

The best tool for the task

@item

Display console output for ordinary
usage of a command line script or
program

@tab

@ref{131f,,print()}

@item

Report events that occur during
normal operation of a program (e.g.
for status monitoring or fault
investigation)

@tab

A logger’s @ref{33b6,,info()} (or
@ref{11de,,debug()} method for very
detailed output for diagnostic
purposes)

@item

Issue a warning regarding a
particular runtime event

@tab

@ref{18bb,,warnings.warn()} in library
code if the issue is avoidable and
the client application should be
modified to eliminate the warning

A logger’s @ref{1c7a,,warning()}
method if there is nothing the client
application can do about the
situation, but the event should still
be noted

@item

Report an error regarding a
particular runtime event

@tab

Raise an exception

@item

Report suppression of an error
without raising an exception (e.g.
error handler in a long-running
server process)

@tab

A logger’s @ref{33b8,,error()},
@ref{11dc,,exception()} or
@ref{11dd,,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

Level

@tab

When it’s used

@item

@code{DEBUG}

@tab

Detailed information, typically of interest
only when diagnosing problems.

@item

@code{INFO}

@tab

Confirmation that things are working as
expected.

@item

@code{WARNING}

@tab

An indication that something unexpected
happened, or indicative of some problem in
the near future (e.g. “disk space low”).
The software is still working as expected.

@item

@code{ERROR}

@tab

Due to a more serious problem, the software
has not been able to perform some function.

@item

@code{CRITICAL}

@tab

A serious error, indicating that the program
itself may be unable to continue running.

@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.

Events that are tracked can be handled in different ways. The simplest way of
handling tracked events is to print them to the console. Another common way
is to write them to a disk file.

@node A simple example,Logging to a file,When to use logging,Basic Logging Tutorial
@anchor{howto/logging a-simple-example}@anchor{5ae1}@anchor{howto/logging howto-minimal-example}@anchor{5ae2}
@subsubsection A simple example


A very simple example is:

@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

If you type these lines into a script and run it, you’ll see:

@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 operate on the root logger, but can be useful
as they will call @ref{dc2,,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 Logging to a file,Logging variable data,A simple example,Basic Logging Tutorial
@anchor{howto/logging logging-to-a-file}@anchor{5ae3}
@subsubsection Logging to a file


A very common situation is that of recording logging events in a file, so let’s
look at that next. Be sure to try the following in a newly started Python
interpreter, and don’t just continue from the session described above:

@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


Άλλαξε στην έκδοση 3.9: The `encoding' argument was added. In earlier Python versions, or if not
specified, the encoding used is the default value used by @ref{32b,,open()}. While
not shown in the above example, an `errors' argument can also now be passed,
which determines how encoding errors are handled. For available values and
the default, see the documentation for @code{open()}.


And now if we open the file and look at what we have, we should find the log
messages:

@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

This example also shows how you can set the logging level which acts as the
threshold for tracking. In this case, because we set the threshold to
@code{DEBUG}, all of the messages were printed.

If you want to set the logging level from a command-line option such as:

@example
--log=INFO
@end example

and you have the value of the parameter passed for @code{--log} in some variable
`loglevel', you can use:

@example
getattr(logging, loglevel.upper())
@end example

to get the value which you’ll pass to @ref{dc2,,basicConfig()} via the `level'
argument. You may want to error check any user input value, perhaps as in the
following example:

@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{dc2,,basicConfig()} should come `before' any calls to a logger’s
methods such as @ref{11de,,debug()}, @ref{33b6,,info()}, etc. Otherwise,
that logging event may not be handled in the desired manner.

If you run the above script several times, the messages from successive runs
are appended to the file `example.log'. If you want each run to start afresh,
not remembering the messages from earlier runs, you can specify the `filemode'
argument, by changing the call in the above example to:

@example
logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)
@end example

The output will be the same as before, but the log file is no longer appended
to, so the messages from earlier runs are lost.

@node Logging variable data,Changing the format of displayed messages,Logging to a file,Basic Logging Tutorial
@anchor{howto/logging logging-variable-data}@anchor{5ae4}
@subsubsection Logging variable data


To log variable data, use a format string for the event description message and
append the variable data as arguments. For example:

@example
import logging
logging.warning('%s before you %s', 'Look', 'leap!')
@end example

will display:

@example
WARNING:root:Look before you leap!
@end example

As you can see, merging of variable data into the event description message
uses the old, %-style of string formatting. This is for backwards
compatibility: the logging package pre-dates newer formatting options such as
@ref{a12,,str.format()} and @ref{a77,,string.Template}. These newer formatting
options `are' supported, but exploring them is outside the scope of this
tutorial: see @ref{33d5,,Using particular formatting styles throughout your application} for more information.

@node Changing the format of displayed messages,Displaying the date/time in messages,Logging variable data,Basic Logging Tutorial
@anchor{howto/logging changing-the-format-of-displayed-messages}@anchor{5ae5}
@subsubsection Changing the format of displayed messages


To change the format which is used to display messages, you need to
specify the format you want to use:

@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

which would print:

@example
DEBUG:This message should appear on the console
INFO:So should this
WARNING:And this, too
@end example

Notice that the “root” which appeared in earlier examples has disappeared. For
a full set of things that can appear in format strings, you can refer to the
documentation for @ref{33b5,,LogRecord attributes}, but for simple usage, you just
need the `levelname' (severity), `message' (event description, including
variable data) and perhaps to display when the event occurred. This is
described in the next section.

@node Displaying the date/time in messages,Next Steps,Changing the format of displayed messages,Basic Logging Tutorial
@anchor{howto/logging displaying-the-date-time-in-messages}@anchor{5ae6}
@subsubsection Displaying the date/time in messages


To display the date and time of an event, you would place “%(asctime)s” in
your format string:

@example
import logging
logging.basicConfig(format='%(asctime)s %(message)s')
logging.warning('is when this event was logged.')
@end example

which should print something like this:

@example
2010-12-12 11:41:42,612 is when this event was logged.
@end example

The default format for date/time display (shown above) is like ISO8601 or
@geindex RFC; RFC 3339
RFC 3339@footnote{https://datatracker.ietf.org/doc/html/rfc3339.html}. If you need more control over the formatting of the date/time, provide
a `datefmt' argument to @code{basicConfig}, as in this example:

@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

which would display something like this:

@example
12/12/2010 11:46:36 AM is when this event was logged.
@end example

The format of the `datefmt' argument is the same as supported by
@ref{1592,,time.strftime()}.

@node Next Steps,,Displaying the date/time in messages,Basic Logging Tutorial
@anchor{howto/logging next-steps}@anchor{5ae7}
@subsubsection Next Steps


That concludes the basic tutorial. It should be enough to get you up and
running with logging. There’s a lot more that the logging package offers, but
to get the best out of it, you’ll need to invest a little more of your time in
reading the following sections. If you’re ready for that, grab some of your
favourite beverage and carry on.

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 in the Help category of the Python discussion forum@footnote{https://discuss.python.org/c/help/7} and you should receive
help before too long.

Still here? You can carry on reading the next few sections, which provide a
slightly more advanced/in-depth tutorial than the basic one above. After that,
you can take a look at the @ref{15a0,,Logging Cookbook}.

@node Advanced Logging Tutorial,Logging Levels<2>,Basic Logging Tutorial,Logging HOWTO
@anchor{howto/logging advanced-logging-tutorial}@anchor{5ae8}@anchor{howto/logging logging-advanced-tutorial}@anchor{159f}
@subsection Advanced Logging Tutorial


The logging library takes a modular approach and offers several categories
of components: loggers, handlers, filters, and formatters.


@itemize *

@item 
Loggers expose the interface that application code directly uses.

@item 
Handlers send the log records (created by loggers) to the appropriate
destination.

@item 
Filters provide a finer grained facility for determining which log records
to output.

@item 
Formatters specify the layout of log records in the final output.
@end itemize

Log event information is passed between loggers, handlers, filters and
formatters in a @ref{138f,,LogRecord} instance.

Logging is performed by calling methods on instances of the @ref{f0c,,Logger}
class (hereafter called `loggers'). Each instance has a name, and they are
conceptually arranged in a namespace hierarchy using dots (periods) as
separators. For example, a logger named “scan” is the parent of loggers
“scan.text”, “scan.html” and “scan.pdf”. Logger names can be anything you want,
and indicate the area of an application in which a logged message originates.

A good convention to use when naming loggers is to use a module-level logger,
in each module which uses logging, named as follows:

@example
logger = logging.getLogger(__name__)
@end example

This means that logger names track the package/module hierarchy, and it’s
intuitively obvious where events are logged just from the logger name.

The root of the hierarchy of loggers is called the root logger. That’s the
logger used by the functions @ref{33b7,,debug()}, @ref{33e0,,info()}, @ref{331,,warning()},
@ref{33f4,,error()} and @ref{33f5,,critical()}, which just call the same-named method of
the root logger. The functions and the methods have the same signatures. The
root logger’s name is printed as “root” in the logged output.

It is, of course, possible to log messages to different destinations. Support
is included in the package for writing log messages to files, HTTP GET/POST
locations, email via SMTP, generic sockets, queues, or OS-specific logging
mechanisms such as syslog or the Windows NT event log. Destinations are served
by `handler' classes. You can create your own log destination class if
you have special requirements not met by any of the built-in handler classes.

By default, no destination is set for any logging messages. You can specify
a destination (such as console or file) by using @ref{dc2,,basicConfig()} as in the
tutorial examples. If you call the functions  @ref{33b7,,debug()}, @ref{33e0,,info()},
@ref{331,,warning()}, @ref{33f4,,error()} and @ref{33f5,,critical()}, they will check to see
if no destination is set; and if one is not set, they will set a destination
of the console (@code{sys.stderr}) and a default format for the displayed
message before delegating to the root logger to do the actual message output.

The default format set by @ref{dc2,,basicConfig()} for messages is:

@example
severity:logger name:message
@end example

You can change this by passing a format string to @ref{dc2,,basicConfig()} with the
`format' keyword argument. For all options regarding how a format string is
constructed, see @ref{33d2,,Formatter Objects}.

@menu
* Logging Flow:: 
* Loggers:: 
* Handlers:: 
* Formatters:: 
* Configuring Logging:: 
* What happens if no configuration is provided:: 
* Configuring Logging for a Library:: 

@end menu

@node Logging Flow,Loggers,,Advanced Logging Tutorial
@anchor{howto/logging logging-flow}@anchor{5ae9}
@subsubsection Logging Flow


The flow of log event information in loggers and handlers is illustrated in the
following diagram.

@image{python-figures/logging_flow,,,,png}

@node Loggers,Handlers,Logging Flow,Advanced Logging Tutorial
@anchor{howto/logging loggers}@anchor{5aea}
@subsubsection Loggers


@ref{f0c,,Logger} objects have a threefold job.  First, they expose several
methods to application code so that applications can log messages at runtime.
Second, logger objects determine which log messages to act upon based upon
severity (the default filtering facility) or filter objects.  Third, logger
objects pass along relevant log messages to all interested log handlers.

The most widely used methods on logger objects fall into two categories:
configuration and message sending.

These are the most common configuration methods:


@itemize *

@item 
@ref{1835,,Logger.setLevel()} specifies the lowest-severity log message a logger
will handle, where debug is the lowest built-in severity level and critical
is the highest built-in severity.  For example, if the severity level is
INFO, the logger will handle only INFO, WARNING, ERROR, and CRITICAL messages
and will ignore DEBUG messages.

@item 
@ref{33b0,,Logger.addHandler()} and @ref{33b1,,Logger.removeHandler()} add and remove
handler objects from the logger object.  Handlers are covered in more detail
in @ref{5aeb,,Handlers}.

@item 
@ref{33b9,,Logger.addFilter()} and @ref{33ba,,Logger.removeFilter()} add and remove filter
objects from the logger object.  Filters are covered in more detail in
@ref{33dd,,Filter Objects}.
@end itemize

You don’t need to always call these methods on every logger you create. See the
last two paragraphs in this section.

With the logger object configured, the following methods create log messages:


@itemize *

@item 
@ref{11de,,Logger.debug()}, @ref{33b6,,Logger.info()}, @ref{1c7a,,Logger.warning()},
@ref{33b8,,Logger.error()}, and @ref{11dd,,Logger.critical()} all create log records with
a message and a level that corresponds to their respective method names. The
message is actually a format string, which may contain the standard string
substitution syntax of @code{%s}, @code{%d}, @code{%f}, and so on.  The
rest of their arguments is a list of objects that correspond with the
substitution fields in the message.  With regard to @code{**kwargs}, the
logging methods care only about a keyword of @code{exc_info} and use it to
determine whether to log exception information.

@item 
@ref{11dc,,Logger.exception()} creates a log message similar to
@ref{33b8,,Logger.error()}.  The difference is that @code{Logger.exception()} dumps a
stack trace along with it.  Call this method only from an exception handler.

@item 
@ref{11db,,Logger.log()} takes a log level as an explicit argument.  This is a
little more verbose for logging messages than using the log level convenience
methods listed above, but this is how to log at custom log levels.
@end itemize

@ref{d2a,,getLogger()} returns a reference to a logger instance with the specified
name if it is provided, or @code{root} if not.  The names are period-separated
hierarchical structures.  Multiple calls to @code{getLogger()} with the same name
will return a reference to the same logger object.  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}.

Loggers have a concept of `effective level'. If a level is not explicitly set
on a logger, the level of its parent is used instead as its effective level.
If the parent has no explicit level set, `its' parent is examined, and so on -
all ancestors are searched until an explicitly set level is found. The root
logger always has an explicit level set (@code{WARNING} by default). When deciding
whether to process an event, the effective level of the logger is used to
determine whether the event is passed to the logger’s handlers.

Child loggers propagate messages up to the handlers associated with their
ancestor loggers. Because of this, it is unnecessary to define and configure
handlers for all the loggers an application uses. It is sufficient to
configure handlers for a top-level logger and create child loggers as needed.
(You can, however, turn off propagation by setting the `propagate'
attribute of a logger to @code{False}.)

@node Handlers,Formatters,Loggers,Advanced Logging Tutorial
@anchor{howto/logging handler-basic}@anchor{5aeb}@anchor{howto/logging handlers}@anchor{5aec}
@subsubsection Handlers


@ref{1838,,Handler} objects are responsible for dispatching the
appropriate log messages (based on the log messages” severity) to the handler’s
specified destination.  @ref{f0c,,Logger} objects can add zero or more handler
objects to themselves with an @ref{33b0,,addHandler()} method.  As an example
scenario, an application may want to send all log messages to a log file, all
log messages of error or higher to stdout, and all messages of critical to an
email address. This scenario requires three individual handlers where each
handler is responsible for sending messages of a specific severity to a specific
location.

The standard library includes quite a few handler types (see
@ref{5aed,,Useful Handlers}); the tutorials use mainly @ref{15a1,,StreamHandler} and
@ref{1e4a,,FileHandler} in its examples.

There are very few methods in a handler for application developers to concern
themselves with.  The only handler methods that seem relevant for application
developers who are using the built-in handler objects (that is, not creating
custom handlers) are the following configuration methods:


@itemize *

@item 
The @ref{33c7,,setLevel()} method, just as in logger objects, specifies the
lowest severity that will be dispatched to the appropriate destination.  Why
are there two @code{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{33c8,,setFormatter()} selects a Formatter object for this handler to
use.

@item 
@ref{33c9,,addFilter()} and @ref{33ca,,removeFilter()} respectively
configure and deconfigure filter objects on handlers.
@end itemize

Application code should not directly instantiate and use instances of
@ref{1838,,Handler}.  Instead, the @code{Handler} class is a base class that
defines the interface that all handlers should have and establishes some
default behavior that child classes can use (or override).

@node Formatters,Configuring Logging,Handlers,Advanced Logging Tutorial
@anchor{howto/logging formatters}@anchor{5aee}
@subsubsection Formatters


Formatter objects configure the final order, structure, and contents of the log
message.  Unlike the base @ref{1838,,logging.Handler} class, application code may
instantiate formatter classes, although you could likely subclass the formatter
if your application needs special behavior.  The constructor takes three
optional arguments – a message format string, a date format string and a style
indicator.

@geindex __init__() (μέθοδος της logging.logging.Formatter)
@anchor{howto/logging logging logging Formatter __init__}@anchor{5aef}
@deffn {Μέθοδος} logging.Formatter.__init__ (fmt=None, datefmt=None, style='%')
@end deffn

If there is no message format string, the default is to use the
raw message.  If there is no date format string, the default date format is:

@example
%Y-%m-%d %H:%M:%S
@end example

with the milliseconds tacked on at the end. The @code{style} is one of @code{'%'},
@code{'@{'}, or @code{'$'}. If one of these is not specified, then @code{'%'} will be used.

If the @code{style} is @code{'%'}, the message format string uses
@code{%(<dictionary key>)s} styled string substitution; the possible keys are
documented in @ref{33b5,,LogRecord attributes}. If the style is @code{'@{'}, the message
format string is assumed to be compatible with @ref{a12,,str.format()} (using
keyword arguments), while if the style is @code{'$'} then the message format string
should conform to what is expected by @ref{22c5,,string.Template.substitute()}.


Άλλαξε στην έκδοση 3.2: Added the @code{style} parameter.


The following message format string will log the time in a human-readable
format, the severity of the message, and the contents of the message, in that
order:

@example
'%(asctime)s - %(levelname)s - %(message)s'
@end example

Formatters use a user-configurable function to convert the creation time of a
record to a tuple. By default, @ref{189b,,time.localtime()} is used; to change this
for a particular formatter instance, set the @code{converter} attribute of the
instance to a function with the same signature as @code{time.localtime()} or
@ref{1569,,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
Formatter class (to @code{time.gmtime} for GMT display).

@node Configuring Logging,What happens if no configuration is provided,Formatters,Advanced Logging Tutorial
@anchor{howto/logging configuring-logging}@anchor{5af0}
@subsubsection Configuring Logging


Programmers can configure logging in three ways:


@enumerate 

@item 
Creating loggers, handlers, and formatters explicitly using Python
code that calls the configuration methods listed above.

@item 
Creating a logging config file and reading it using the @ref{f0e,,fileConfig()}
function.

@item 
Creating a dictionary of configuration information and passing it
to the @ref{1559,,dictConfig()} function.
@end enumerate

For the reference documentation on the last two options, see
@ref{1696,,Configuration functions}.  The following example configures a very simple
logger, a console handler, and a simple formatter using Python code:

@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

Running this module from the command line produces the following output:

@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

The following Python module creates a logger, handler, and formatter nearly
identical to those in the example listed above, with the only difference being
the names of the objects:

@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

Here is the logging.conf file:

@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

The output is nearly identical to that of the non-config-file-based example:

@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

You can see that the config file approach has a few advantages over the Python
code approach, mainly separation of configuration and code and the ability of
noncoders to easily modify the logging properties.

@cartouche
@quotation Προειδοποίηση 
The @ref{f0e,,fileConfig()} function takes a default parameter,
@code{disable_existing_loggers}, which defaults to @code{True} for reasons of
backward compatibility. This may or may not be what you want, since it
will cause any non-root loggers existing before the @code{fileConfig()}
call to be disabled unless they (or an ancestor) are explicitly named in
the configuration. Please refer to the reference documentation for more
information, and specify @code{False} for this parameter if you wish.

The dictionary passed to @ref{1559,,dictConfig()} can also specify a Boolean
value with key @code{disable_existing_loggers}, which if not specified
explicitly in the dictionary also defaults to being interpreted as
@code{True}. This leads to the logger-disabling behaviour described above,
which may not be what you want - in which case, provide the key
explicitly with a value of @code{False}.
@end quotation
@end cartouche

Note that the class names referenced in config files need to be either relative
to the logging module, or absolute values which can be resolved using normal
import mechanisms. Thus, you could use either
@ref{3434,,WatchedFileHandler} (relative to the logging module) or
@code{mypackage.mymodule.MyHandler} (for a class defined in package @code{mypackage}
and module @code{mymodule}, where @code{mypackage} is available on the Python import
path).

In Python 3.2, a new means of configuring logging has been introduced, using
dictionaries to hold configuration information. This provides a superset of the
functionality of the config-file-based approach outlined above, and is the
recommended configuration method for new applications and deployments. Because
a Python dictionary is used to hold configuration information, and since you
can populate that dictionary using different means, you have more options for
configuration. For example, you can use a configuration file in JSON format,
or, if you have access to YAML processing functionality, a file in YAML
format, to populate the configuration dictionary. Or, of course, you can
construct the dictionary in Python code, receive it in pickled form over a
socket, or use whatever approach makes sense for your application.

Here’s an example of the same configuration as above, in YAML format for
the new dictionary-based approach:

@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

For more information about logging using a dictionary, see
@ref{1696,,Configuration functions}.

@node What happens if no configuration is provided,Configuring Logging for a Library,Configuring Logging,Advanced Logging Tutorial
@anchor{howto/logging what-happens-if-no-configuration-is-provided}@anchor{5af1}
@subsubsection What happens if no configuration is provided


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{15a3,,lastResort}. This internal handler is not associated with any
logger, and acts like a @ref{15a1,,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.


Άλλαξε στην έκδοση 3.2: For versions of Python prior to 3.2, the behaviour is as follows:


@itemize *

@item 
If @ref{15a2,,raiseExceptions} is @code{False} (production mode), the event is
silently dropped.

@item 
If @ref{15a2,,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{15a3,,lastResort} can be set to @code{None}.


@node Configuring Logging for a Library,,What happens if no configuration is provided,Advanced Logging Tutorial
@anchor{howto/logging configuring-logging-for-a-library}@anchor{5af2}@anchor{howto/logging library-config}@anchor{3431}
@subsubsection Configuring Logging for a Library


When developing a library which uses logging, you should take care to
document how the library uses logging - for example, the names of loggers
used. Some consideration also needs to be given to its logging configuration.
If the using application does not use logging, and library code makes logging
calls, then (as described in the previous section) events of severity
@code{WARNING} and greater will be printed to @code{sys.stderr}. This is regarded as
the best default behaviour.

If for some reason you `don’t' want these messages printed in the absence of
any logging configuration, you can attach a do-nothing handler to the top-level
logger for your library. This avoids the message being printed, since a handler
will always be found for the library’s events: it just doesn’t produce any
output. If the library user configures logging for application use, presumably
that configuration will add some handlers, and if levels are suitably
configured then logging calls made in library code will send output to those
handlers, as normal.

A do-nothing handler is included in the logging package:
@ref{1629,,NullHandler} (since Python 3.1). An instance of this handler
could be added to the top-level logger of the logging namespace used by the
library (`if' you want to prevent your library’s logged events being output to
@code{sys.stderr} in the absence of logging configuration). If all logging by a
library `foo' is done using loggers with names matching “foo.x”, “foo.x.y”,
etc. then the code:

@example
import logging
logging.getLogger('foo').addHandler(logging.NullHandler())
@end example

should have the desired effect. If an organisation produces a number of
libraries, then the logger name specified can be “orgname.foo” rather than
just “foo”.

@cartouche
@quotation Σημείωση 
It is strongly advised that you `do not log to the root logger'
in your library. Instead, use a logger with a unique and easily
identifiable name, such as the @code{__name__} for your library’s top-level package
or module. Logging to the root logger will make it difficult or impossible for
the application developer to configure the logging verbosity or handlers of
your library as they wish.
@end quotation
@end cartouche

@cartouche
@quotation Σημείωση 
It is strongly advised that you `do not add any handlers other
than' @ref{1629,,NullHandler} `to your library’s loggers'. This is
because the configuration of handlers is the prerogative of the application
developer who uses your library. The application developer knows their
target audience and what handlers are most appropriate for their
application: if you add handlers “under the hood”, you might well interfere
with their ability to carry out unit tests and deliver logs which suit their
requirements.
@end quotation
@end cartouche

@node Logging Levels<2>,Useful Handlers,Advanced Logging Tutorial,Logging HOWTO
@anchor{howto/logging logging-levels}@anchor{5af3}
@subsection Logging Levels


The numeric values of logging levels are given in the following table. These are
primarily of interest if you want to define your own levels, and need them to
have specific values relative to the predefined levels. If you define a level
with the same numeric value, it overwrites the predefined value; the predefined
name is lost.


@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Level

@tab

Numeric value

@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


Levels can also be associated with loggers, being set either by the developer or
through loading a saved logging configuration. When a logging method is called
on a logger, the logger compares its own level with the level associated with
the method call. If the logger’s level is higher than the method call’s, no
logging message is actually generated. This is the basic mechanism controlling
the verbosity of logging output.

Logging messages are encoded as instances of the @ref{138f,,LogRecord}
class. When a logger decides to actually log an event, a
@code{LogRecord} instance is created from the logging message.

Logging messages are subjected to a dispatch mechanism through the use of
`handlers', which are instances of subclasses of the @ref{1838,,Handler}
class. Handlers are responsible for ensuring that a logged message (in the form
of a @ref{138f,,LogRecord}) ends up in a particular location (or set of locations)
which is useful for the target audience for that message (such as end users,
support desk staff, system administrators, developers). Handlers are passed
@code{LogRecord} instances intended for particular destinations. Each logger
can have zero, one or more handlers associated with it (via the
@ref{33b0,,addHandler()} method of @ref{f0c,,Logger}). In addition to any
handlers directly associated with a logger, `all handlers associated with all
ancestors of the logger' are called to dispatch the message (unless the
`propagate' flag for a logger is set to a false value, at which point the
passing to ancestor handlers stops).

Just as for loggers, handlers can have levels associated with them. A handler’s
level acts as a filter in the same way as a logger’s level does. If a handler
decides to actually dispatch an event, the @ref{33d0,,emit()} method is used
to send the message to its destination. Most user-defined subclasses of
@ref{1838,,Handler} will need to override this @code{emit()}.

@menu
* Custom Levels:: 

@end menu

@node Custom Levels,,,Logging Levels<2>
@anchor{howto/logging custom-levels}@anchor{33f9}@anchor{howto/logging id2}@anchor{5af4}
@subsubsection Custom Levels


Defining your own levels is possible, but should not be necessary, as the
existing levels have been chosen on the basis of practical experience.
However, if you are convinced that you need custom levels, great care should
be exercised when doing this, and it is possibly `a very bad idea to define
custom levels if you are developing a library'. That’s because if multiple
library authors all define their own custom levels, there is a chance that
the logging output from such multiple libraries used together will be
difficult for the using developer to control and/or interpret, because a
given numeric value might mean different things for different libraries.

@node Useful Handlers,Exceptions raised during logging,Logging Levels<2>,Logging HOWTO
@anchor{howto/logging id3}@anchor{5af5}@anchor{howto/logging useful-handlers}@anchor{5aed}
@subsection Useful Handlers


In addition to the base @ref{1838,,Handler} class, many useful subclasses are
provided:


@enumerate 

@item 
@ref{15a1,,StreamHandler} instances send messages to streams (file-like
objects).

@item 
@ref{1e4a,,FileHandler} instances send messages to disk files.

@item 
@ref{3438,,BaseRotatingHandler} is the base class for handlers that
rotate log files at a certain point. It is not meant to be  instantiated
directly. Instead, use @ref{1b59,,RotatingFileHandler} or
@ref{130b,,TimedRotatingFileHandler}.

@item 
@ref{1b59,,RotatingFileHandler} instances send messages to disk
files, with support for maximum log file sizes and log file rotation.

@item 
@ref{130b,,TimedRotatingFileHandler} instances send messages to
disk files, rotating the log file at certain timed intervals.

@item 
@ref{130c,,SocketHandler} instances send messages to TCP/IP
sockets. Since 3.4, Unix domain sockets are also supported.

@item 
@ref{130d,,DatagramHandler} instances send messages to UDP
sockets. Since 3.4, Unix domain sockets are also supported.

@item 
@ref{1ad3,,SMTPHandler} instances send messages to a designated
email address.

@item 
@ref{a4c,,SysLogHandler} instances send messages to a Unix
syslog daemon, possibly on a remote machine.

@item 
@ref{1985,,NTEventLogHandler} instances send messages to a
Windows NT/2000/XP event log.

@item 
@ref{3417,,MemoryHandler} instances send messages to a buffer
in memory, which is flushed whenever specific criteria are met.

@item 
@ref{11df,,HTTPHandler} instances send messages to an HTTP
server using either @code{GET} or @code{POST} semantics.

@item 
@ref{3434,,WatchedFileHandler} instances watch the file they are
logging to. If the file changes, it is closed and reopened using the file
name. This handler is only useful on Unix-like systems; Windows does not
support the underlying mechanism used.

@item 
@ref{1d5f,,QueueHandler} instances send messages to a queue, such as
those implemented in the @ref{be,,queue} or @ref{98,,multiprocessing} modules.

@item 
@ref{1629,,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{3431,,Configuring Logging for a Library} for
more information.
@end enumerate


Added in version 3.1: The @ref{1629,,NullHandler} class.



Added in version 3.2: The @ref{1d5f,,QueueHandler} class.


The @ref{1629,,NullHandler}, @ref{15a1,,StreamHandler} and @ref{1e4a,,FileHandler}
classes are defined in the core logging package. The other handlers are
defined in a sub-module, @ref{8c,,logging.handlers}. (There is also another
sub-module, @ref{8b,,logging.config}, for configuration functionality.)

Logged messages are formatted for presentation through instances of the
@ref{1839,,Formatter} class. They are initialized with a format string suitable for
use with the % operator and a dictionary.

For formatting multiple messages in a batch, instances of
@ref{33d9,,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.

When filtering based on logger level and/or handler level is not enough,
instances of @ref{15a4,,Filter} can be added to both @ref{f0c,,Logger} and
@ref{1838,,Handler} instances (through their @ref{33c9,,addFilter()} method).
Before deciding to process a message further, both loggers and handlers consult
all their filters for permission. If any filter returns a false value, the
message is not processed further.

The basic @ref{15a4,,Filter} functionality allows filtering by specific logger
name. If this feature is used, messages sent to the named logger and its
children are allowed through the filter, and all others dropped.

@node Exceptions raised during logging,Using arbitrary objects as messages,Useful Handlers,Logging HOWTO
@anchor{howto/logging exceptions-raised-during-logging}@anchor{5af6}@anchor{howto/logging logging-exceptions}@anchor{5af7}
@subsection Exceptions raised during logging


The logging package is designed to swallow exceptions which occur while logging
in production. This is so that errors which occur while handling logging events
- such as logging misconfiguration, network or other similar errors - do not
cause the application using logging to terminate prematurely.

@ref{10f7,,SystemExit} and @ref{d96,,KeyboardInterrupt} exceptions are never
swallowed. Other exceptions which occur during the @ref{33d0,,emit()} method
of a @ref{1838,,Handler} subclass are passed to its @ref{33cf,,handleError()}
method.

The default implementation of @ref{33cf,,handleError()} in @ref{1838,,Handler}
checks to see if a module-level variable, @ref{15a2,,raiseExceptions}, is set. If
set, a traceback is printed to @ref{d05,,sys.stderr}. If not set, the exception is
swallowed.

@cartouche
@quotation Σημείωση 
The default value of @ref{15a2,,raiseExceptions} is @code{True}. This is
because during development, you typically want to be notified of any
exceptions that occur. It’s advised that you set @code{raiseExceptions} to
@code{False} for production usage.
@end quotation
@end cartouche

@node Using arbitrary objects as messages,Optimization,Exceptions raised during logging,Logging HOWTO
@anchor{howto/logging arbitrary-object-messages}@anchor{33e5}@anchor{howto/logging using-arbitrary-objects-as-messages}@anchor{5af8}
@subsection Using arbitrary objects as messages


In the preceding sections and examples, it has been assumed that the message
passed when logging the event is a string. However, this is not the only
possibility. You can pass an arbitrary object as a message, and its
@ref{a0f,,__str__()} method will be called when the logging system needs to
convert it to a string representation. In fact, if you want to, you can avoid
computing a string representation altogether - for example, the
@ref{130c,,SocketHandler} emits an event by pickling it and sending it
over the wire.

@node Optimization,Other resources,Using arbitrary objects as messages,Logging HOWTO
@anchor{howto/logging optimization}@anchor{5af9}
@subsection Optimization


Formatting of message arguments is deferred until it cannot be avoided.
However, computing the arguments passed to the logging method can also be
expensive, and you may want to avoid doing it if the logger will just throw
away your event. To decide what to do, you can call the
@ref{169b,,isEnabledFor()} method which takes a level argument and returns
true if the event would be created by the Logger for that level of call.
You can write code like this:

@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 Σημείωση 
In some cases, @ref{169b,,isEnabledFor()} can itself be more
expensive than you’d like (e.g. for deeply nested loggers where an explicit
level is only set high up in the logger hierarchy). In such cases (or if you
want to avoid calling a method in tight loops), you can cache the result of a
call to @code{isEnabledFor()} in a local or instance variable, and use
that instead of calling the method each time. Such a cached value would only
need to be recomputed when the logging configuration changes dynamically
while the application is running (which is not all that common).
@end quotation
@end cartouche

There are other optimizations which can be made for specific applications which
need more precise control over what logging information is collected. Here’s a
list of things you can do to avoid processing during logging which you don’t
need:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

What you don’t want to collect

@tab

How to avoid collecting it

@item

Information about where calls were made from.

@tab

Set @code{logging._srcfile} to @code{None}.
This avoids calling @ref{ace,,sys._getframe()}, which
may help to speed up your code in environments
like PyPy (which can’t speed up code that uses
@code{sys._getframe()}).

@item

Threading information.

@tab

Set @code{logging.logThreads} to @code{False}.

@item

Current process ID (@ref{3226,,os.getpid()})

@tab

Set @code{logging.logProcesses} to @code{False}.

@item

Current process name when using @code{multiprocessing}
to manage multiple processes.

@tab

Set @code{logging.logMultiprocessing} to @code{False}.

@item

Current @ref{460,,asyncio.Task} name when using
@code{asyncio}.

@tab

Set @code{logging.logAsyncioTasks} to @code{False}.

@end multitable


Also note that the core logging module only includes the basic handlers. If
you don’t import @ref{8c,,logging.handlers} and @ref{8b,,logging.config}, they won’t
take up any memory.

@node Other resources,,Optimization,Logging HOWTO
@anchor{howto/logging other-resources}@anchor{5afa}@anchor{howto/logging tutorial-ref-links}@anchor{5ade}
@subsection Other resources



@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{8a,,logging}

API reference for the logging module.

@item Module @ref{8b,,logging.config}

Configuration API for the logging module.

@item Module @ref{8c,,logging.handlers}

Useful handlers included with the logging module.
@end table

@ref{15a0,,A logging cookbook}


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Logging Cookbook,Regular expression HOWTO,Logging HOWTO,Python HOWTOs
@anchor{howto/logging-cookbook doc}@anchor{5afb}@anchor{howto/logging-cookbook id1}@anchor{5afc}@anchor{howto/logging-cookbook logging-cookbook}@anchor{15a0}@anchor{howto/logging-cookbook translation-repo}@anchor{5afd}
@section Logging Cookbook


@*Author: 
Vinay Sajip <vinay_sajip at red-dove dot com>


This page contains a number of recipes related to logging, which have been found
useful in the past. For links to tutorial and reference information, please see
@ref{5afe,,Other resources}.

@menu
* Using logging in multiple modules:: 
* Logging from multiple threads:: 
* Multiple handlers and formatters:: 
* Logging to multiple destinations:: 
* Custom handling of levels:: 
* Configuration server example:: 
* Dealing with handlers that block:: 
* Sending and receiving logging events across a network:: 
* Adding contextual information to your logging output:: 
* Use of contextvars:: 
* Imparting contextual information in handlers:: 
* Logging to a single file from multiple processes:: 
* Using file rotation:: 
* Use of alternative formatting styles:: 
* Customizing LogRecord:: 
* Subclassing QueueHandler and QueueListener- a ZeroMQ example:: 
* Subclassing QueueHandler and QueueListener- a pynng example:: 
* An example dictionary-based configuration:: 
* Using a rotator and namer to customize log rotation processing:: 
* A more elaborate multiprocessing example:: 
* Inserting a BOM into messages sent to a SysLogHandler:: 
* Implementing structured logging:: 
* Customizing handlers with dictConfig(): Customizing handlers with 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:: 
* How to uniformly handle newlines in logging output:: 
* Patterns to avoid:: 
* Other resources: Other resources<2>. 

@end menu

@node Using logging in multiple modules,Logging from multiple threads,,Logging Cookbook
@anchor{howto/logging-cookbook using-logging-in-multiple-modules}@anchor{5aff}
@subsection Using logging in multiple modules


Multiple calls to @code{logging.getLogger('someLogger')} return a reference to the
same logger object.  This is true not only within the same module, but also
across modules as long as it is in the same Python interpreter process.  It is
true for references to the same object; additionally, application code can
define and configure a parent logger in one module and create (but not
configure) a child logger in a separate module, and all logger calls to the
child will pass up to the parent.  Here is a main module:

@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

Here is the auxiliary module:

@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

The output looks like this:

@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 Logging from multiple threads,Multiple handlers and formatters,Using logging in multiple modules,Logging Cookbook
@anchor{howto/logging-cookbook logging-from-multiple-threads}@anchor{5b00}
@subsection Logging from multiple threads


Logging from multiple threads requires no special effort. The following example
shows logging from the main (initial) thread and another thread:

@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

When run, the script should print something like the following:

@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

This shows the logging output interspersed as one might expect. This approach
works for more threads than shown here, of course.

@node Multiple handlers and formatters,Logging to multiple destinations,Logging from multiple threads,Logging Cookbook
@anchor{howto/logging-cookbook multiple-handlers-and-formatters}@anchor{5b01}
@subsection Multiple handlers and formatters


Loggers are plain Python objects.  The @ref{33b0,,addHandler()} method has no
minimum or maximum quota for the number of handlers you may add.  Sometimes it
will be beneficial for an application to log all messages of all severities to a
text file while simultaneously logging errors or above to the console.  To set
this up, simply configure the appropriate handlers.  The logging calls in the
application code will remain unchanged.  Here is a slight modification to the
previous simple module-based configuration example:

@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

Notice that the “application” code does not care about multiple handlers.  All
that changed was the addition and configuration of a new handler named `fh'.

The ability to create new handlers with higher- or lower-severity filters can be
very helpful when writing and testing an application.  Instead of using many
@code{print} statements for debugging, use @code{logger.debug}: Unlike the print
statements, which you will have to delete or comment out later, the logger.debug
statements can remain intact in the source code and remain dormant until you
need them again.  At that time, the only change that needs to happen is to
modify the severity level of the logger and/or handler to debug.

@node Logging to multiple destinations,Custom handling of levels,Multiple handlers and formatters,Logging Cookbook
@anchor{howto/logging-cookbook logging-to-multiple-destinations}@anchor{5b02}@anchor{howto/logging-cookbook multiple-destinations}@anchor{5b03}
@subsection Logging to multiple destinations


Let’s say you want to log to console and file with different message formats and
in differing circumstances. Say you want to log messages with levels of DEBUG
and higher to file, and those messages at level INFO and higher to the console.
Let’s also assume that the file should contain timestamps, but the console
messages should not. Here’s how you can achieve this:

@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().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

When you run this, on the console you will see

@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

and in the file you will see something like

@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

As you can see, the DEBUG message only shows up in the file. The other messages
are sent to both destinations.

This example uses console and file handlers, but you can use any number and
combination of handlers you choose.

Note that the above choice of log filename @code{/tmp/myapp.log} implies use of a
standard location for temporary files on POSIX systems. On Windows, you may need to
choose a different directory name for the log - just ensure that the directory exists
and that you have the permissions to create and update files in it.

@node Custom handling of levels,Configuration server example,Logging to multiple destinations,Logging Cookbook
@anchor{howto/logging-cookbook custom-handling-of-levels}@anchor{5b04}@anchor{howto/logging-cookbook custom-level-handling}@anchor{5b05}
@subsection Custom handling of levels


Sometimes, you might want to do something slightly different from the standard
handling of levels in handlers, where all levels above a threshold get
processed by a handler. To do this, you need to use filters. Let’s look at a
scenario where you want to arrange things as follows:


@itemize *

@item 
Send messages of severity @code{INFO} and @code{WARNING} to @code{sys.stdout}

@item 
Send messages of severity @code{ERROR} and above to @code{sys.stderr}

@item 
Send messages of severity @code{DEBUG} and above to file @code{app.log}
@end itemize

Suppose you configure logging with the following JSON:

@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

and changing the section on the @code{stdout} handler to add it:

@example
@{
    "stdout": @{
        "class": "logging.StreamHandler",
        "level": "INFO",
        "formatter": "simple",
        "stream": "ext://sys.stdout",
        "filters": ["warnings_and_below"]
    @}
@}
@end example

A filter is just a function, so we can define the @code{filter_maker} (a factory
function) as follows:

@example
def filter_maker(level):
    level = getattr(logging, level)

    def filter(record):
        return record.levelno <= level

    return filter
@end example

This converts the string argument passed in to a numeric level, and returns a
function which only returns @code{True} if the level of the passed in record is
at or below the specified level. Note that in this example I have defined the
@code{filter_maker} in a test script @code{main.py} that I run from the command line,
so its module will be @code{__main__} - hence the @code{__main__.filter_maker} in the
filter configuration. You will need to change that if you define it in a
different module.

With the filter added, we can run @code{main.py}, which in full is:

@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

And after running it like this:

@example
python main.py 2>stderr.log >stdout.log
@end example

We can see the results are as expected:

@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 Configuration server example,Dealing with handlers that block,Custom handling of levels,Logging Cookbook
@anchor{howto/logging-cookbook configuration-server-example}@anchor{5b06}
@subsection Configuration server example


Here is an example of a module using the logging configuration server:

@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

And here is a script that takes a filename and sends that file to the server,
properly preceded with the binary-encoded length, as the new logging
configuration:

@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 Dealing with handlers that block,Sending and receiving logging events across a network,Configuration server example,Logging Cookbook
@anchor{howto/logging-cookbook blocking-handlers}@anchor{3b81}@anchor{howto/logging-cookbook dealing-with-handlers-that-block}@anchor{5b07}
@subsection Dealing with handlers that block


Sometimes you have to get your logging handlers to do their work without
blocking the thread you’re logging from. This is common in web applications,
though of course it also occurs in other scenarios.

A common culprit which demonstrates sluggish behaviour is the
@ref{1ad3,,SMTPHandler}: sending emails can take a long time, for a
number of reasons outside the developer’s control (for example, a poorly
performing mail or network infrastructure). But almost any network-based
handler can block: Even a @ref{130c,,SocketHandler} operation may do a
DNS query under the hood which is too slow (and this query can be deep in the
socket library code, below the Python layer, and outside your control).

One solution is to use a two-part approach. For the first part, attach only a
@ref{1d5f,,QueueHandler} to those loggers which are accessed from
performance-critical threads. They simply write to their queue, which can be
sized to a large enough capacity or initialized with no upper bound to their
size. The write to the queue will typically be accepted quickly, though you
will probably need to catch the @ref{38b7,,queue.Full} exception as a precaution
in your code. If you are a library developer who has performance-critical
threads in their code, be sure to document this (together with a suggestion to
attach only @code{QueueHandlers} to your loggers) for the benefit of other
developers who will use your code.

The second part of the solution is @ref{4cf,,QueueListener}, which has been
designed as the counterpart to @ref{1d5f,,QueueHandler}.  A
@code{QueueListener} is very simple: it’s passed a queue and some handlers,
and it fires up an internal thread which listens to its queue for LogRecords
sent from @code{QueueHandlers} (or any other source of @code{LogRecords}, for that
matter). The @code{LogRecords} are removed from the queue and passed to the
handlers for processing.

The advantage of having a separate @ref{4cf,,QueueListener} class is that you
can use the same instance to service multiple @code{QueueHandlers}. This is more
resource-friendly than, say, having threaded versions of the existing handler
classes, which would eat up one thread per handler for no particular benefit.

An example of using these two classes follows (imports omitted):

@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

which, when run, will produce:

@example
MainThread: Look out!
@end example

@cartouche
@quotation Σημείωση 
Although the earlier discussion wasn’t specifically talking about
async code, but rather about slow logging handlers, it should be noted that
when logging from async code, network and even file handlers could lead to
problems (blocking the event loop) because some logging is done from
@ref{b,,asyncio} internals. It might be best, if any async code is used in an
application, to use the above approach for logging, so that any blocking code
runs only in the @code{QueueListener} thread.
@end quotation
@end cartouche


Άλλαξε στην έκδοση 3.5: Prior to Python 3.5, the @ref{4cf,,QueueListener} always passed every message
received from the queue to every handler it was initialized with. (This was
because it was assumed that level filtering was all done on the other side,
where the queue is filled.) From 3.5 onwards, this behaviour can be changed
by passing a keyword argument @code{respect_handler_level=True} to the
listener’s constructor. When this is done, the listener compares the level
of each message with the handler’s level, and only passes a message to a
handler if it’s appropriate to do so.



Άλλαξε στην έκδοση 3.14: The @ref{4cf,,QueueListener} can be started (and stopped) via the
@ref{20a,,with} statement. For example:

@example
with QueueListener(que, handler) as listener:
    # The queue listener automatically starts
    # when the 'with' block is entered.
    pass
# The queue listener automatically stops once
# the 'with' block is exited.
@end example


@node Sending and receiving logging events across a network,Adding contextual information to your logging output,Dealing with handlers that block,Logging Cookbook
@anchor{howto/logging-cookbook network-logging}@anchor{5b08}@anchor{howto/logging-cookbook sending-and-receiving-logging-events-across-a-network}@anchor{5b09}
@subsection Sending and receiving logging events across a network


Let’s say you want to send logging events across a network, and handle them at
the receiving end. A simple way of doing this is attaching a
@ref{130c,,SocketHandler} instance to the root logger at the sending end:

@example
import logging, logging.handlers

rootLogger = logging.getLogger()
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

At the receiving end, you can set up a receiver using the @ref{d5,,socketserver}
module. Here is a basic working example:

@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

First run the server, and then the client. On the client side, nothing is
printed on the console; on the server side, you should see something like:

@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{344f,,makePickle()} method and implementing your
alternative there, as well as adapting the above script to use your alternative
serialization.

@menu
* Running a logging socket listener in production:: 

@end menu

@node Running a logging socket listener in production,,,Sending and receiving logging events across a network
@anchor{howto/logging-cookbook running-a-logging-socket-listener-in-production}@anchor{5b0a}
@subsubsection Running a logging socket listener in production


To run a logging listener in production, you may need to use a
process-management tool such as Supervisor@footnote{http://supervisord.org/}.
Here is a Gist@footnote{https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b}
which provides the bare-bones files to run the above functionality using
Supervisor. It consists of the following files:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

File

@tab

Purpose

@item

@code{prepare.sh}

@tab

A Bash script to prepare the environment for
testing

@item

@code{supervisor.conf}

@tab

The Supervisor configuration file, which has
entries for the listener and a multi-process web
application

@item

@code{ensure_app.sh}

@tab

A Bash script to ensure that Supervisor is running
with the above configuration

@item

@code{log_listener.py}

@tab

The socket listener program which receives log
events and records them to a file

@item

@code{main.py}

@tab

A simple web application which performs logging
via a socket connected to the listener

@item

@code{webapp.json}

@tab

A JSON configuration file for the web application

@item

@code{client.py}

@tab

A Python script to exercise the web application

@end multitable


The web application uses Gunicorn@footnote{https://gunicorn.org/}, which is a
popular web application server that starts multiple worker processes to handle
requests. This example setup shows how the workers can write to the same log file
without conflicting with one another — they all go through the socket listener.

To test these files, do the following in a POSIX environment:


@enumerate 

@item 
Download the Gist@footnote{https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b}
as a ZIP archive using the Download ZIP button.

@item 
Unzip the above files from the archive into a scratch directory.

@item 
In the scratch directory, run @code{bash prepare.sh} to get things ready.
This creates a @code{run} subdirectory to contain Supervisor-related and
log files, and a @code{venv} subdirectory to contain a virtual environment
into which @code{bottle}, @code{gunicorn} and @code{supervisor} are installed.

@item 
Run @code{bash ensure_app.sh} to ensure that Supervisor is running with
the above configuration.

@item 
Run @code{venv/bin/python client.py} to exercise the web application,
which will lead to records being written to the log.

@item 
Inspect the log files in the @code{run} subdirectory. You should see the
most recent log lines in files matching the pattern @code{app.log*}. They
won’t be in any particular order, since they have been handled concurrently
by different worker processes in a non-deterministic way.

@item 
You can shut down the listener and the web application by running
@code{venv/bin/supervisorctl -c supervisor.conf shutdown}.
@end enumerate

You may need to tweak the configuration files in the unlikely event that the
configured ports clash with something else in your test environment.

The default configuration uses a TCP socket on port 9020. You can use a Unix
Domain socket instead of a TCP socket by doing the following:


@enumerate 

@item 
In @code{listener.json}, add a @code{socket} key with the path to the domain
socket you want to use. If this key is present, the listener listens on the
corresponding domain socket and not on a TCP socket (the @code{port} key is
ignored).

@item 
In @code{webapp.json}, change the socket handler configuration dictionary
so that the @code{host} value is the path to the domain socket, and set the
@code{port} value to @code{null}.
@end enumerate

@node Adding contextual information to your logging output,Use of contextvars,Sending and receiving logging events across a network,Logging Cookbook
@anchor{howto/logging-cookbook adding-contextual-information-to-your-logging-output}@anchor{5b0b}@anchor{howto/logging-cookbook context-info}@anchor{33ec}
@subsection Adding contextual information to your logging output


Sometimes you want logging output to contain contextual information in
addition to the parameters passed to the logging call. For example, in a
networked application, it may be desirable to log client-specific information
in the log (e.g. remote client’s username, or IP address). Although you could
use the `extra' parameter to achieve this, it’s not always convenient to pass
the information in this way. While it might be tempting to create
@ref{f0c,,Logger} instances on a per-connection basis, this is not a good idea
because these instances are not garbage collected. While this is not a problem
in practice, when the number of @code{Logger} instances is dependent on the
level of granularity you want to use in logging an application, it could
be hard to manage if the number of @code{Logger} instances becomes
effectively unbounded.

@menu
* Using LoggerAdapters to impart contextual information:: 
* Using Filters to impart contextual information:: 

@end menu

@node Using LoggerAdapters to impart contextual information,Using Filters to impart contextual information,,Adding contextual information to your logging output
@anchor{howto/logging-cookbook using-loggeradapters-to-impart-contextual-information}@anchor{5b0c}
@subsubsection Using LoggerAdapters to impart contextual information


An easy way in which you can pass contextual information to be output along
with logging event information is to use the @ref{169a,,LoggerAdapter} class.
This class is designed to look like a @ref{f0c,,Logger}, so that you can call
@ref{33b7,,debug()}, @ref{33e0,,info()}, @ref{331,,warning()}, @ref{33f4,,error()},
@ref{1836,,exception()}, @ref{33f5,,critical()} and @ref{33f6,,log()}. These methods have the
same signatures as their counterparts in @code{Logger}, so you can use the
two types of instances interchangeably.

When you create an instance of @ref{169a,,LoggerAdapter}, you pass it a
@ref{f0c,,Logger} instance and a dict-like object which contains your contextual
information. When you call one of the logging methods on an instance of
@code{LoggerAdapter}, it delegates the call to the underlying instance of
@code{Logger} passed to its constructor, and arranges to pass the contextual
information in the delegated call. Here’s a snippet from the code of
@code{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

The @ref{33ed,,process()} method of @ref{169a,,LoggerAdapter} is where the
contextual information is added to the logging output. It’s passed the message
and keyword arguments of the logging call, and it passes back (potentially)
modified versions of these to use in the call to the underlying logger. The
default implementation of this method leaves the message alone, but inserts
an “extra” key in the keyword argument whose value is the dict-like object
passed to the constructor. Of course, if you had passed an “extra” keyword
argument in the call to the adapter, it will be silently overwritten.

The advantage of using “extra” is that the values in the dict-like object are
merged into the @ref{138f,,LogRecord} instance’s __dict__, allowing you to use
customized strings with your @ref{1839,,Formatter} instances which know about
the keys of the dict-like object. If you need a different method, e.g. if you
want to prepend or append the contextual information to the message string,
you just need to subclass @ref{169a,,LoggerAdapter} and override
@ref{33ed,,process()} to do what you need. Here is a simple example:

@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

which you can use like this:

@example
logger = logging.getLogger(__name__)
adapter = CustomAdapter(logger, @{'connid': some_conn_id@})
@end example

Then any events that you log to the adapter will have the value of
@code{some_conn_id} prepended to the log messages.

@menu
* Using objects other than dicts to pass contextual information:: 

@end menu

@node Using objects other than dicts to pass contextual information,,,Using LoggerAdapters to impart contextual information
@anchor{howto/logging-cookbook using-objects-other-than-dicts-to-pass-contextual-information}@anchor{5b0d}
@subsubsection Using objects other than dicts to pass contextual information


You don’t need to pass an actual dict to a @ref{169a,,LoggerAdapter} - you could
pass an instance of a class which implements @code{__getitem__} and @code{__iter__} so
that it looks like a dict to logging. This would be useful if you want to
generate values dynamically (whereas the values in a dict would be constant).

@node Using Filters to impart contextual information,,Using LoggerAdapters to impart contextual information,Adding contextual information to your logging output
@anchor{howto/logging-cookbook filters-contextual}@anchor{33e1}@anchor{howto/logging-cookbook using-filters-to-impart-contextual-information}@anchor{5b0e}
@subsubsection Using Filters to impart contextual information


You can also add contextual information to log output using a user-defined
@ref{15a4,,Filter}. @code{Filter} instances are allowed to modify the @code{LogRecords}
passed to them, including adding additional attributes which can then be output
using a suitable format string, or if needed a custom @ref{1839,,Formatter}.

For example in a web application, the request being processed (or at least,
the interesting parts of it) can be stored in a threadlocal
(@ref{1a87,,threading.local}) variable, and then accessed from a @code{Filter} to
add, say, information from the request - say, the remote IP address and remote
user’s username - to the @code{LogRecord}, using the attribute names “ip” and
“user” as in the @code{LoggerAdapter} example above. In that case, the same format
string can be used to get similar output to that shown above. Here’s an example
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

which, when run, produces something like:

@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,Imparting contextual information in handlers,Adding contextual information to your logging output,Logging Cookbook
@anchor{howto/logging-cookbook use-of-contextvars}@anchor{5b0f}
@subsection Use of @code{contextvars}


Since Python 3.7, the @ref{28,,contextvars} module has provided context-local storage
which works for both @ref{f6,,threading} and @ref{b,,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 Imparting contextual information in handlers,Logging to a single file from multiple processes,Use of contextvars,Logging Cookbook
@anchor{howto/logging-cookbook imparting-contextual-information-in-handlers}@anchor{5b10}
@subsection Imparting contextual information in handlers


Each @ref{1838,,Handler} has its own chain of filters.
If you want to add contextual information to a @ref{138f,,LogRecord} without leaking
it to other handlers, you can use a filter that returns
a new @code{LogRecord} instead of modifying it in-place, as shown in the following script:

@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 Logging to a single file from multiple processes,Using file rotation,Imparting contextual information in handlers,Logging Cookbook
@anchor{howto/logging-cookbook logging-to-a-single-file-from-multiple-processes}@anchor{5b11}@anchor{howto/logging-cookbook multiple-processes}@anchor{5b12}
@subsection Logging to a single file from multiple processes


Although logging is thread-safe, and logging to a single file from multiple
threads in a single process `is' supported, logging to a single file from
`multiple processes' is `not' supported, because there is no standard way to
serialize access to a single file across multiple processes in Python. If you
need to log to a single file from multiple processes, one way of doing this is
to have all the processes log to a @ref{130c,,SocketHandler}, and have a
separate process which implements a socket server which reads from the socket
and logs to file. (If you prefer, you can dedicate one thread in one of the
existing processes to perform this function.)
@ref{5b08,,This section} documents this approach in more detail and
includes a working socket receiver which can be used as a starting point for you
to adapt in your own applications.

You could also write your own handler which uses the @ref{1a7c,,Lock}
class from the @ref{98,,multiprocessing} module to serialize access to the
file from your processes. The stdlib @ref{1e4a,,FileHandler} and subclasses do
not make use of @code{multiprocessing}.

Alternatively, you can use a @code{Queue} and a @ref{1d5f,,QueueHandler} to send
all logging events to one of the processes in your multi-process application.
The following example script demonstrates how you can do this; in the example
a separate listener process listens for events sent by other processes and logs
them according to its own logging configuration. Although the example only
demonstrates one way of doing it (for example, you may want to use a listener
thread rather than a separate listener process – the implementation would be
analogous) it does allow for completely different logging configurations for
the listener and the other processes in your application, and can be used as
the basis for code meeting your own specific requirements:

@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

A variant of the above script keeps the logging in the main process, in a
separate thread:

@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

This variant shows how you can e.g. apply configuration for particular loggers
- e.g. the @code{foo} logger has a special handler which stores all events in the
@code{foo} subsystem in a file @code{mplog-foo.log}. This will be used by the logging
machinery in the main process (even though the logging events are generated in
the worker processes) to direct the messages to the appropriate destinations.

@menu
* Using concurrent.futures.ProcessPoolExecutor: Using concurrent futures ProcessPoolExecutor. 
* Deploying web applications using Gunicorn and uWSGI:: 

@end menu

@node Using concurrent futures ProcessPoolExecutor,Deploying web applications using Gunicorn and uWSGI,,Logging to a single file from multiple processes
@anchor{howto/logging-cookbook using-concurrent-futures-processpoolexecutor}@anchor{5b13}
@subsubsection Using concurrent.futures.ProcessPoolExecutor


If you want to use @ref{206,,concurrent.futures.ProcessPoolExecutor} to start
your worker processes, you need to create the queue slightly differently.
Instead of

@example
queue = multiprocessing.Queue(-1)
@end example

you should use

@example
queue = multiprocessing.Manager().Queue(-1)  # also works with the examples above
@end example

and you can then replace the worker creation from this:

@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

to this (remembering to first import @ref{24,,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 Deploying web applications using Gunicorn and uWSGI,,Using concurrent futures ProcessPoolExecutor,Logging to a single file from multiple processes
@anchor{howto/logging-cookbook deploying-web-applications-using-gunicorn-and-uwsgi}@anchor{5b14}
@subsubsection Deploying web applications using Gunicorn and uWSGI


When deploying web applications using Gunicorn@footnote{https://gunicorn.org/} or uWSGI@footnote{https://uwsgi-docs.readthedocs.io/en/latest/} (or similar), multiple worker
processes are created to handle client requests. In such environments, avoid creating
file-based handlers directly in your web application. Instead, use a
@ref{130c,,SocketHandler} to log from the web application to a listener in a separate
process. This can be set up using a process management tool such as Supervisor - see
@ref{5b0a,,Running a logging socket listener in production} for more details.

@node Using file rotation,Use of alternative formatting styles,Logging to a single file from multiple processes,Logging Cookbook
@anchor{howto/logging-cookbook using-file-rotation}@anchor{5b15}
@subsection Using file rotation


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{1b59,,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

The result should be 6 separate files, each with part of the log history for the
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

The most current file is always @code{logging_rotatingfile_example.out},
and each time it reaches the size limit it is renamed with the suffix
@code{.1}. Each of the existing backup files is renamed to increment the suffix
(@code{.1} becomes @code{.2}, etc.)  and the @code{.6} file is erased.

Obviously this example sets the log length much too small as an extreme
example.  You would want to set `maxBytes' to an appropriate value.

@node Use of alternative formatting styles,Customizing LogRecord,Using file rotation,Logging Cookbook
@anchor{howto/logging-cookbook format-styles}@anchor{5b16}@anchor{howto/logging-cookbook use-of-alternative-formatting-styles}@anchor{5b17}
@subsection Use of alternative formatting styles


When logging was added to the Python standard library, the only way of
formatting messages with variable content was to use the %-formatting
method. Since then, Python has gained two new formatting approaches:
@ref{a77,,string.Template} (added in Python 2.4) and @ref{a12,,str.format()}
(added in Python 2.6).

Logging (as of 3.2) provides improved support for these two additional
formatting styles. The @ref{1839,,Formatter} class been enhanced to take an
additional, optional keyword parameter named @code{style}. This defaults to
@code{'%'}, but other possible values are @code{'@{'} and @code{'$'}, which correspond
to the other two formatting styles. Backwards compatibility is maintained by
default (as you would expect), but by explicitly specifying a style parameter,
you get the ability to specify format strings which work with
@ref{a12,,str.format()} or @ref{a77,,string.Template}. Here’s an example console
session to show the possibilities:

@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

Note that the formatting of logging messages for final output to logs is
completely independent of how an individual logging message is constructed.
That can still use %-formatting, as shown here:

@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

Logging calls (@code{logger.debug()}, @code{logger.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 actual
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{a12,,str.format()} or
@ref{a77,,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 is, however, a way that you can use @{@}- and $- formatting to construct
your individual log messages. Recall that for a message you can use an
arbitrary object as a message format string, and that the logging package will
call @code{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».
It’s a little unwieldy to use the class names whenever you want to log
something, but it’s quite palatable if you use an alias such as __ (double
underscore — not to be confused with _, the single underscore used as a
synonym/alias for @ref{180b,,gettext.gettext()} or its brethren).

The above classes are not included in Python, though they’re easy enough to
copy and paste into your own code. They can be used as follows (assuming that
they’re declared in a module called @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

While the above examples use @code{print()} to show how the formatting works, you
would of course use @code{logger.debug()} or similar to actually log using this
approach.

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.

If you prefer, you can use a @ref{169a,,LoggerAdapter} to achieve a similar effect
to the above, as in the following example:

@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 Customizing LogRecord,Subclassing QueueHandler and QueueListener- a ZeroMQ example,Use of alternative formatting styles,Logging Cookbook
@anchor{howto/logging-cookbook custom-logrecord}@anchor{5b18}@anchor{howto/logging-cookbook customizing-logrecord}@anchor{5b19}
@subsection Customizing @code{LogRecord}


Every logging event is represented by a @ref{138f,,LogRecord} instance.
When an event is logged and not filtered out by a logger’s level, a
@code{LogRecord} is created, populated with information about the event and
then passed to the handlers for that logger (and its ancestors, up to and
including the logger where further propagation up the hierarchy is disabled).
Before Python 3.2, there were only two places where this creation was done:


@itemize *

@item 
@ref{33be,,Logger.makeRecord()}, which is called in the normal process of
logging an event. This invoked @ref{138f,,LogRecord} directly to create an
instance.

@item 
@ref{33e4,,makeLogRecord()}, which is called with a dictionary containing
attributes to be added to the LogRecord. This is typically invoked when a
suitable dictionary has been received over the network (e.g. in pickle form
via a @ref{130c,,SocketHandler}, or in JSON form via an
@ref{11df,,HTTPHandler}).
@end itemize

This has usually meant that if you need to do anything special with a
@ref{138f,,LogRecord}, you’ve had to do one of the following.


@itemize *

@item 
Create your own @ref{f0c,,Logger} subclass, which overrides
@ref{33be,,Logger.makeRecord()}, and set it using @ref{33f3,,setLoggerClass()}
before any loggers that you care about are instantiated.

@item 
Add a @ref{15a4,,Filter} to a logger or handler, which does the
necessary special manipulation you need when its
@ref{33df,,filter()} method is called.
@end itemize

The first approach would be a little unwieldy in the scenario where (say)
several different libraries wanted to do different things. Each would attempt
to set its own @ref{f0c,,Logger} subclass, and the one which did this last would
win.

The second approach works reasonably well for many cases, but does not allow
you to e.g. use a specialized subclass of @ref{138f,,LogRecord}. Library
developers can set a suitable filter on their loggers, but they would have to
remember to do this every time they introduced a new logger (which they would
do simply by adding new packages or modules and doing

@example
logger = logging.getLogger(__name__)
@end example

at module level). It’s probably one too many things to think about. Developers
could also add the filter to a @ref{1629,,NullHandler} attached to their
top-level logger, but this would not be invoked if an application developer
attached a handler to a lower-level library logger — so output from that
handler would not reflect the intentions of the library developer.

In Python 3.2 and later, @ref{138f,,LogRecord} creation is done through a
factory, which you can specify. The factory is just a callable you can set with
@ref{33e8,,setLogRecordFactory()}, and interrogate with
@ref{33e7,,getLogRecordFactory()}. The factory is invoked with the same
signature as the @code{LogRecord} constructor, as @ref{138f,,LogRecord}
is the default setting for the factory.

This approach allows a custom factory to control all aspects of LogRecord
creation. For example, you could return a subclass, or just add some additional
attributes to the record once created, using a pattern similar to this:

@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

This pattern allows different libraries to chain factories together, and as
long as they don’t overwrite each other’s attributes or unintentionally
overwrite the attributes provided as standard, there should be no surprises.
However, it should be borne in mind that each link in the chain adds run-time
overhead to all logging operations, and the technique should only be used when
the use of a @ref{15a4,,Filter} does not provide the desired result.

@node Subclassing QueueHandler and QueueListener- a ZeroMQ example,Subclassing QueueHandler and QueueListener- a pynng example,Customizing LogRecord,Logging Cookbook
@anchor{howto/logging-cookbook subclassing-queuehandler-and-queuelistener-a-zeromq-example}@anchor{5b1a}@anchor{howto/logging-cookbook zeromq-handlers}@anchor{5b1b}
@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{5b1c}
@subsubsection Subclass @code{QueueHandler}


You can use a @ref{1d5f,,QueueHandler} subclass to send messages to other kinds
of queues, for example a ZeroMQ “publish” socket. In the example below,the
socket is created separately and passed to the handler (as its “queue”):

@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

Of course there are other ways of organizing this, for example passing in the
data needed by the handler to create the socket:

@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{5b1d}
@subsubsection Subclass @code{QueueListener}


You can also subclass @ref{4cf,,QueueListener} to get messages from other kinds
of queues, for example a ZeroMQ “subscribe” socket. Here’s an example:

@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,An example dictionary-based configuration,Subclassing QueueHandler and QueueListener- a ZeroMQ example,Logging Cookbook
@anchor{howto/logging-cookbook pynng-handlers}@anchor{5b1e}@anchor{howto/logging-cookbook subclassing-queuehandler-and-queuelistener-a-pynng-example}@anchor{5b1f}
@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{5b20}
@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{5b21}
@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 An example dictionary-based configuration,Using a rotator and namer to customize log rotation processing,Subclassing QueueHandler and QueueListener- a pynng example,Logging Cookbook
@anchor{howto/logging-cookbook an-example-dictionary-based-configuration}@anchor{5b22}
@subsection An example dictionary-based configuration


Below is an example of a logging configuration dictionary - it’s taken from
the documentation on the Django project@footnote{https://docs.djangoproject.com/en/stable/topics/logging/#configuring-logging}.
This dictionary is passed to @ref{1559,,dictConfig()} to put the configuration into effect:

@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

For more information about this configuration, you can see the relevant section@footnote{https://docs.djangoproject.com/en/stable/topics/logging/#configuring-logging}
of the Django documentation.

@node Using a rotator and namer to customize log rotation processing,A more elaborate multiprocessing example,An example dictionary-based configuration,Logging Cookbook
@anchor{howto/logging-cookbook cookbook-rotator-namer}@anchor{343e}@anchor{howto/logging-cookbook using-a-rotator-and-namer-to-customize-log-rotation-processing}@anchor{5b23}
@subsection Using a rotator and namer to customize log rotation processing


An example of how you can define a namer and rotator is given in the following
runnable script, which shows gzip compression of the log file:

@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

After running this, you will see six new files, five of which are compressed:

@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 A more elaborate multiprocessing example,Inserting a BOM into messages sent to a SysLogHandler,Using a rotator and namer to customize log rotation processing,Logging Cookbook
@anchor{howto/logging-cookbook a-more-elaborate-multiprocessing-example}@anchor{5b24}
@subsection A more elaborate multiprocessing example


The following working example shows how logging can be used with multiprocessing
using configuration files. The configurations are fairly simple, but serve to
illustrate how more complex ones could be implemented in a real multiprocessing
scenario.

In the example, the main process spawns a listener process and some worker
processes. Each of the main process, the listener and the workers have three
separate configurations (the workers all share the same configuration). We can
see logging in the main process, how the workers log to a QueueHandler and how
the listener implements a QueueListener and a more complex logging
configuration, and arranges to dispatch events received via the queue to the
handlers specified in the configuration. Note that these configurations are
purely illustrative, but you should be able to adapt this example to your own
scenario.

Here’s the script - the docstrings and the comments hopefully explain how it
works:

@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 Inserting a BOM into messages sent to a SysLogHandler,Implementing structured logging,A more elaborate multiprocessing example,Logging Cookbook
@anchor{howto/logging-cookbook inserting-a-bom-into-messages-sent-to-a-sysloghandler}@anchor{5b25}
@subsection Inserting a BOM into messages sent to a SysLogHandler


@geindex RFC; RFC 5424
RFC 5424@footnote{https://datatracker.ietf.org/doc/html/rfc5424.html} requires that a
Unicode message be sent to a syslog daemon as a set of bytes which have the
following structure: an optional pure-ASCII component, followed by a UTF-8 Byte
Order Mark (BOM), followed by Unicode encoded using UTF-8. (See the
@geindex RFC; RFC 5424 Section 6
relevant section of the specification@footnote{https://datatracker.ietf.org/doc/html/rfc5424.html#section-6}.)

In Python 3.1, code was added to
@ref{a4c,,SysLogHandler} to insert a BOM into the message, but
unfortunately, it was implemented incorrectly, with the BOM appearing at the
beginning of the message and hence not allowing any pure-ASCII component to
appear before it.

As this behaviour is broken, the incorrect BOM insertion code is being removed
from Python 3.2.4 and later. However, it is not being replaced, and if you
want to produce 
@geindex RFC; RFC 5424
RFC 5424@footnote{https://datatracker.ietf.org/doc/html/rfc5424.html}-compliant messages which include a BOM, an optional
pure-ASCII sequence before it and arbitrary Unicode after it, encoded using
UTF-8, then you need to do the following:


@enumerate 

@item 
Attach a @ref{1839,,Formatter} instance to your
@ref{a4c,,SysLogHandler} instance, with a format string
such as:

@example
'ASCII section\ufeffUnicode section'
@end example

The Unicode code point U+FEFF, when encoded using UTF-8, will be
encoded as a UTF-8 BOM – the byte-string @code{b'\xef\xbb\xbf'}.

@item 
Replace the ASCII section with whatever placeholders you like, but make sure
that the data that appears in there after substitution is always ASCII (that
way, it will remain unchanged after UTF-8 encoding).

@item 
Replace the Unicode section with whatever placeholders you like; if the data
which appears there after substitution contains characters outside the ASCII
range, that’s fine – it will be encoded using UTF-8.
@end enumerate

The formatted message `will' be encoded using UTF-8 encoding by
@code{SysLogHandler}. If you follow the above rules, you should be able to produce
@geindex RFC; RFC 5424
RFC 5424@footnote{https://datatracker.ietf.org/doc/html/rfc5424.html}-compliant messages. If you don’t, logging may not complain, but your
messages will not be RFC 5424-compliant, and your syslog daemon may complain.

@node Implementing structured logging,Customizing handlers with dictConfig,Inserting a BOM into messages sent to a SysLogHandler,Logging Cookbook
@anchor{howto/logging-cookbook implementing-structured-logging}@anchor{5b26}
@subsection Implementing structured logging


Although most logging messages are intended for reading by humans, and thus not
readily machine-parseable, there might be circumstances where you want to output
messages in a structured format which `is' capable of being parsed by a program
(without needing complex regular expressions to parse the log message). This is
straightforward to achieve using the logging package. There are a number of
ways in which this could be achieved, but the following is a simple approach
which uses JSON to serialise the event in a machine-parseable manner:

@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

If the above script is run, it prints:

@example
message 1 >>> @{"fnum": 123.456, "num": 123, "bar": "baz", "foo": "bar"@}
@end example

Note that the order of items might be different according to the version of
Python used.

If you need more specialised processing, you can use a custom JSON encoder,
as in the following complete example:

@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

When the above script is run, it prints:

@example
message 1 >>> @{"snowman": "\u2603", "set_value": [1, 2, 3]@}
@end example

Note that the order of items might be different according to the version of
Python used.

@node Customizing handlers with dictConfig,Using particular formatting styles throughout your application,Implementing structured logging,Logging Cookbook
@anchor{howto/logging-cookbook custom-handlers}@anchor{5b27}@anchor{howto/logging-cookbook customizing-handlers-with-dictconfig}@anchor{5b28}
@subsection Customizing handlers with @code{dictConfig()}


There are times when you want to customize logging handlers in particular ways,
and if you use @ref{1559,,dictConfig()} you may be able to do this without
subclassing. As an example, consider that you may want to set the ownership of a
log file. On POSIX, this is easily done using @ref{74b,,shutil.chown()}, but the file
handlers in the stdlib don’t offer built-in support. You can customize handler
creation using a plain function such as:

@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

You can then specify, in a logging configuration passed to @ref{1559,,dictConfig()},
that a logging handler be created by calling this function:

@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

In this example I am setting the ownership using the @code{pulse} user and group,
just for the purposes of illustration. Putting it together into a working
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

To run this, you will probably need to run as @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

Note that this example uses Python 3.3 because that’s where @ref{74b,,shutil.chown()}
makes an appearance. This approach should work with any Python version that
supports @ref{1559,,dictConfig()} - namely, Python 2.7, 3.2 or later. With pre-3.3
versions, you would need to implement the actual ownership change using e.g.
@ref{149a,,os.chown()}.

In practice, the handler-creating function may be in a utility module somewhere
in your project. Instead of the line in the configuration:

@example
'()': owned_file_handler,
@end example

you could use e.g.:

@example
'()': 'ext://project.util.owned_file_handler',
@end example

where @code{project.util} can be replaced with the actual name of the package
where the function resides. In the above working script, using
@code{'ext://__main__.owned_file_handler'} should work. Here, the actual callable
is resolved by @ref{1559,,dictConfig()} from the @code{ext://} specification.

This example hopefully also points the way to how you could implement other
types of file change - e.g. setting specific POSIX permission bits - in the
same way, using @ref{72c,,os.chmod()}.

Of course, the approach could also be extended to types of handler other than a
@ref{1e4a,,FileHandler} - for example, one of the rotating file handlers,
or a different type of handler altogether.

@node Using particular formatting styles throughout your application,Configuring filters with dictConfig,Customizing handlers with dictConfig,Logging Cookbook
@anchor{howto/logging-cookbook formatting-styles}@anchor{33d5}@anchor{howto/logging-cookbook using-particular-formatting-styles-throughout-your-application}@anchor{5b29}
@subsection Using particular formatting styles throughout your application


In Python 3.2, the @ref{1839,,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{a12,,str.format()} and @ref{a77,,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{11de,,debug()}, @ref{33b6,,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{a12,,str.format()} or @ref{a77,,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{5b2a}
@subsubsection Using LogRecord factories


In Python 3.2, along with the @ref{1839,,Formatter} changes mentioned
above, the logging package gained the ability to allow users to set their own
@ref{138f,,LogRecord} subclasses, using the @ref{33e8,,setLogRecordFactory()} function.
You can use this to set your own subclass of @code{LogRecord}, which does the
Right Thing by overriding the @ref{33e6,,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{33e8,,setLogRecordFactory()} and
@ref{138f,,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{5b2b}
@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{33e5,,Using arbitrary objects as messages}) that when logging you can use an arbitrary
object as a message format string, and that the logging package will call
@ref{1df,,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{a12,,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{a77,,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,Logging Cookbook
@anchor{howto/logging-cookbook configuring-filters-with-dictconfig}@anchor{5b2c}@anchor{howto/logging-cookbook filters-dictconfig}@anchor{5b2d}
@subsection Configuring filters with @code{dictConfig()}


You `can' configure filters using @ref{1559,,dictConfig()}, though it
might not be obvious at first glance how to do it (hence this recipe). Since
@ref{15a4,,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 @code{Filter}
subclass with an overridden @ref{33df,,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
@code{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{3414,,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{3408,,User-defined objects} for more
information on how logging supports using user-defined objects in its
configuration, and see the other cookbook recipe @ref{5b27,,Customizing handlers with dictConfig()} above.
@end itemize

@node Customized exception formatting,Speaking logging messages,Configuring filters with dictConfig,Logging Cookbook
@anchor{howto/logging-cookbook custom-format-exception}@anchor{5b2e}@anchor{howto/logging-cookbook customized-exception-formatting}@anchor{5b2f}
@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: division by zero|'Traceback (most recent call last):\n  File "logtest7.py", line 30, in main\n    x = 1 / 0\nZeroDivisionError: division 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{107,,traceback} module may be
helpful for more specialized needs.

@node Speaking logging messages,Buffering logging messages and outputting them conditionally,Customized exception formatting,Logging Cookbook
@anchor{howto/logging-cookbook speaking-logging-messages}@anchor{5b30}@anchor{howto/logging-cookbook spoken-messages}@anchor{5b31}
@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{df,,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,Logging Cookbook
@anchor{howto/logging-cookbook buffered-logging}@anchor{5b32}@anchor{howto/logging-cookbook buffering-logging-messages-and-outputting-them-conditionally}@anchor{5b33}
@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{3417,,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{15a1,,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,Logging Cookbook
@anchor{howto/logging-cookbook buffered-smtp}@anchor{5b34}@anchor{howto/logging-cookbook sending-logging-messages-to-email-with-buffering}@anchor{5b35}
@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{3469,,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,Logging Cookbook
@anchor{howto/logging-cookbook formatting-times-using-utc-gmt-via-configuration}@anchor{5b36}@anchor{howto/logging-cookbook utc-formatting}@anchor{5b37}
@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{1839,,Formatter}. If you want to do that via configuration, you can
use the @ref{1559,,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,Logging Cookbook
@anchor{howto/logging-cookbook context-manager}@anchor{5b38}@anchor{howto/logging-cookbook using-a-context-manager-for-selective-logging}@anchor{5b39}
@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,Logging Cookbook
@anchor{howto/logging-cookbook a-cli-application-starter-template}@anchor{5b3a}@anchor{howto/logging-cookbook starter-template}@anchor{5b3b}
@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,Logging Cookbook
@anchor{howto/logging-cookbook a-qt-gui-for-logging}@anchor{5b3c}@anchor{howto/logging-cookbook qt-gui}@anchor{5b3d}
@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{f6,,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 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,Logging Cookbook
@anchor{howto/logging-cookbook logging-to-syslog-with-rfc5424-support}@anchor{5b3e}
@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
RFC 5424 came out, as there has not been widespread deployment of it in syslog
servers, the @ref{a4c,,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 as dt
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 = dt.datetime.fromtimestamp(record.created).isoformat()
        m = self.tz_offset.prefixmatch(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,How to uniformly handle newlines in logging output,Logging to syslog with RFC5424 support,Logging Cookbook
@anchor{howto/logging-cookbook how-to-treat-a-logger-like-an-output-stream}@anchor{5b3f}
@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{dc2,,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{dc2,,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

@node How to uniformly handle newlines in logging output,Patterns to avoid,How to treat a logger like an output stream,Logging Cookbook
@anchor{howto/logging-cookbook how-to-uniformly-handle-newlines-in-logging-output}@anchor{5b40}
@subsection How to uniformly handle newlines in logging output


Usually, messages that are logged (say to console or file) consist of a single
line of text. However, sometimes there is a need to handle messages with
multiple lines - whether because a logging format string contains newlines, or
logged data contains newlines. If you want to handle such messages uniformly, so
that each line in the logged message appears uniformly formatted as if it was
logged separately, you can do this using a handler mixin, as in the following
snippet:

@example
# Assume this is in a module mymixins.py
import copy

class MultilineMixin:
    def emit(self, record):
        s = record.getMessage()
        if '\n' not in s:
            super().emit(record)
        else:
            lines = s.splitlines()
            rec = copy.copy(record)
            rec.args = None
            for line in lines:
                rec.msg = line
                super().emit(rec)
@end example

You can use the mixin as in the following script:

@example
import logging

from mymixins import MultilineMixin

logger = logging.getLogger(__name__)

class StreamHandler(MultilineMixin, logging.StreamHandler):
    pass

if __name__ == '__main__':
    logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %(levelname)-9s %(message)s',
                        handlers = [StreamHandler()])
    logger.debug('Single line')
    logger.debug('Multiple lines:\nfool me once ...')
    logger.debug('Another single line')
    logger.debug('Multiple lines:\n%s', 'fool me ...\ncan\'t get fooled again')
@end example

The script, when run, prints something like:

@example
2025-07-02 13:54:47,234 DEBUG     Single line
2025-07-02 13:54:47,234 DEBUG     Multiple lines:
2025-07-02 13:54:47,234 DEBUG     fool me once ...
2025-07-02 13:54:47,234 DEBUG     Another single line
2025-07-02 13:54:47,234 DEBUG     Multiple lines:
2025-07-02 13:54:47,234 DEBUG     fool me ...
2025-07-02 13:54:47,234 DEBUG     can't get fooled again
@end example

If, on the other hand, you are concerned about log injection@footnote{https://owasp.org/www-community/attacks/Log_Injection}, you can use a
formatter which escapes newlines, as per the following example:

@example
import logging

logger = logging.getLogger(__name__)

class EscapingFormatter(logging.Formatter):
    def format(self, record):
        s = super().format(record)
        return s.replace('\n', r'\n')

if __name__ == '__main__':
    h = logging.StreamHandler()
    h.setFormatter(EscapingFormatter('%(asctime)s %(levelname)-9s %(message)s'))
    logging.basicConfig(level=logging.DEBUG, handlers = [h])
    logger.debug('Single line')
    logger.debug('Multiple lines:\nfool me once ...')
    logger.debug('Another single line')
    logger.debug('Multiple lines:\n%s', 'fool me ...\ncan\'t get fooled again')
@end example

You can, of course, use whatever escaping scheme makes the most sense for you.
The script, when run, should produce output like this:

@example
2025-07-09 06:47:33,783 DEBUG     Single line
2025-07-09 06:47:33,783 DEBUG     Multiple lines:\nfool me once ...
2025-07-09 06:47:33,783 DEBUG     Another single line
2025-07-09 06:47:33,783 DEBUG     Multiple lines:\nfool me ...\ncan't get fooled again
@end example

Escaping behaviour can’t be the stdlib default , as it would break backwards
compatibility.

@c patterns-to-avoid:

@node Patterns to avoid,Other resources<2>,How to uniformly handle newlines in logging output,Logging Cookbook
@anchor{howto/logging-cookbook patterns-to-avoid}@anchor{5b41}
@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{5b42}
@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{98,,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{5b12,,Logging to a single file from multiple processes} 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{5b43}
@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{5b44}
@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{1629,,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{5b45}
@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{33ec,,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 Other resources<2>,,Patterns to avoid,Logging Cookbook
@anchor{howto/logging-cookbook cookbook-ref-links}@anchor{5afe}@anchor{howto/logging-cookbook other-resources}@anchor{5b46}
@subsection Other resources



@subsubheading Δείτε επίσης



@table @asis

@item Module @ref{8a,,logging}

API reference for the logging module.

@item Module @ref{8b,,logging.config}

Configuration API for the logging module.

@item Module @ref{8c,,logging.handlers}

Useful handlers included with the logging module.
@end table

@ref{159e,,Basic Tutorial}

@ref{159f,,Advanced Tutorial}


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Regular expression HOWTO,Socket Programming HOWTO,Logging Cookbook,Python HOWTOs
@anchor{howto/regex doc}@anchor{5b47}@anchor{howto/regex regex-howto}@anchor{297c}@anchor{howto/regex regular-expression-howto}@anchor{5b48}@anchor{howto/regex translation-repo}@anchor{5b49}
@section Regular expression HOWTO


@*Author: 
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 Abstract



This document is an introductory tutorial to using regular expressions in Python
with the @ref{c1,,re} module.  It provides a gentler introduction than the
corresponding section in the Library Reference.

@menu
* Introduction: Introduction<14>. 
* Simple patterns:: 
* Using regular expressions:: 
* More pattern power:: 
* Modifying strings:: 
* Common problems:: 
* Feedback:: 

@end menu

@node Introduction<14>,Simple patterns,,Regular expression HOWTO
@anchor{howto/regex introduction}@anchor{5b4a}
@subsection Introduction


Regular expressions (called REs, or regexes, or regex patterns) are essentially
a tiny, highly specialized programming language embedded inside Python and made
available through the @ref{c1,,re} module. Using this little language, you specify
the rules for the set of possible strings that you want to match; this set might
contain English sentences, or e-mail addresses, or TeX commands, or anything you
like.  You can then ask questions such as «Does this string match the pattern?»,
or «Is there a match for the pattern anywhere in this string?».  You can also
use REs to modify a string or to split it apart in various ways.

Regular expression patterns are compiled into a series of bytecodes which are
then executed by a matching engine written in C.  For advanced use, it may be
necessary to pay careful attention to how the engine will execute a given RE,
and write the RE in a certain way in order to produce bytecode that runs faster.
Optimization isn’t covered in this document, because it requires that you have a
good understanding of the matching engine’s internals.

The regular expression language is relatively small and restricted, so not all
possible string processing tasks can be done using regular expressions.  There
are also tasks that `can' be done with regular expressions, but the expressions
turn out to be very complicated.  In these cases, you may be better off writing
Python code to do the processing; while Python code will be slower than an
elaborate regular expression, it will also probably be more understandable.

@node Simple patterns,Using regular expressions,Introduction<14>,Regular expression HOWTO
@anchor{howto/regex simple-patterns}@anchor{5b4b}
@subsection Simple patterns


We’ll start by learning about the simplest possible regular expressions.  Since
regular expressions are used to operate on strings, we’ll begin with the most
common task: matching characters.

For a detailed explanation of the computer science underlying regular
expressions (deterministic and non-deterministic finite automata), you can refer
to almost any textbook on writing compilers.

@menu
* Matching characters:: 
* Repeating things:: 

@end menu

@node Matching characters,Repeating things,,Simple patterns
@anchor{howto/regex matching-characters}@anchor{5b4c}
@subsubsection Matching characters


Most letters and characters will simply match themselves.  For example, the
regular expression @code{test} will match the string @code{test} exactly.  (You can
enable a case-insensitive mode that would let this RE match @code{Test} or @code{TEST}
as well; more about this later.)

There are exceptions to this rule; some characters are special
`metacharacters', and don’t match themselves.  Instead, they signal that
some out-of-the-ordinary thing should be matched, or they affect other portions
of the RE by repeating them or changing their meaning.  Much of this document is
devoted to discussing various metacharacters and what they do.

Here’s a complete list of the metacharacters; their meanings will be discussed
in the rest of this HOWTO.

@example
. ^ $ * + ? @{ @} [ ] \ | ( )
@end example

The first metacharacters we’ll look at are @code{[} and @code{]}. They’re used for
specifying a character class, which is a set of characters that you wish to
match.  Characters can be listed individually, or a range of characters can be
indicated by giving two characters and separating them by a @code{'-'}.  For
example, @code{[abc]} will match any of the characters @code{a}, @code{b}, or @code{c}; this
is the same as @code{[a-c]}, which uses a range to express the same set of
characters.  If you wanted to match only lowercase letters, your RE would be
@code{[a-z]}.

Metacharacters (except @code{\}) are not active inside classes.  For example, @code{[akm$]} will
match any of the characters @code{'a'}, @code{'k'}, @code{'m'}, or @code{'$'}; @code{'$'} is
usually a metacharacter, but inside a character class it’s stripped of its
special nature.

You can match the characters not listed within the class by `complementing'
the set.  This is indicated by including a @code{'^'} as the first character of the
class. For example, @code{[^5]} will match any character except @code{'5'}.  If the
caret appears elsewhere in a character class, it does not have special meaning.
For example: @code{[5^]} will match either a @code{'5'} or a @code{'^'}.

Perhaps the most important metacharacter is the backslash, @code{\}.   As in Python
string literals, the backslash can be followed by various characters to signal
various special sequences.  It’s also used to escape all the metacharacters so
you can still match them in patterns; for example, if you need to match a @code{[}
or  @code{\}, you can precede them with a backslash to remove their special
meaning: @code{\[} or @code{\\}.

Some of the special sequences beginning with @code{'\'} represent
predefined sets of characters that are often useful, such as the set
of digits, the set of letters, or the set of anything that isn’t
whitespace.

Let’s take an example: @code{\w} matches any alphanumeric character.  If
the regex pattern is expressed in bytes, this is equivalent to the
class @code{[a-zA-Z0-9_]}.  If the regex pattern is a string, @code{\w} will
match all the characters marked as letters in the Unicode database
provided by the @ref{10e,,unicodedata} module.  You can use the more
restricted definition of @code{\w} in a string pattern by supplying the
@ref{a1d,,re.ASCII} flag when compiling the regular expression.

The following list of special sequences isn’t complete. For a complete
list of sequences and expanded class definitions for Unicode string
patterns, see the last part of @ref{b0c,,Regular Expression Syntax} in the Standard Library reference.  In general, the
Unicode versions match any character that’s in the appropriate
category in the Unicode database.


@table @asis

@item @code{\d}

Matches any decimal digit; this is equivalent to the class @code{[0-9]}.

@item @code{\D}

Matches any non-digit character; this is equivalent to the class @code{[^0-9]}.

@item @code{\s}

Matches any whitespace character; this is equivalent to the class @code{[
\t\n\r\f\v]}.

@item @code{\S}

Matches any non-whitespace character; this is equivalent to the class @code{[^
\t\n\r\f\v]}.

@item @code{\w}

Matches any alphanumeric character; this is equivalent to the class
@code{[a-zA-Z0-9_]}.

@item @code{\W}

Matches any non-alphanumeric character; this is equivalent to the class
@code{[^a-zA-Z0-9_]}.
@end table

These sequences can be included inside a character class.  For example,
@code{[\s,.]} is a character class that will match any whitespace character, or
@code{','} or @code{'.'}.

The final metacharacter in this section is @code{.}.  It matches anything except a
newline character, and there’s an alternate mode (@ref{297d,,re.DOTALL}) where it will
match even a newline.  @code{.} is often used where you want to match «any
character».

@node Repeating things,,Matching characters,Simple patterns
@anchor{howto/regex repeating-things}@anchor{5b4d}
@subsubsection Repeating things


Being able to match varying sets of characters is the first thing regular
expressions can do that isn’t already possible with the methods available on
strings.  However, if that was the only additional capability of regexes, they
wouldn’t be much of an advance. Another capability is that you can specify that
portions of the RE must be repeated a certain number of times.

The first metacharacter for repeating things that we’ll look at is @code{*}.  @code{*}
doesn’t match the literal character @code{'*'}; instead, it specifies that the
previous character can be matched zero or more times, instead of exactly once.

For example, @code{ca*t} will match @code{'ct'} (0 @code{'a'} characters), @code{'cat'} (1 @code{'a'}),
@code{'caaat'} (3 @code{'a'} characters), and so forth.

Repetitions such as @code{*} are `greedy'; when repeating a RE, the matching
engine will try to repeat it as many times as possible. If later portions of the
pattern don’t match, the matching engine will then back up and try again with
fewer repetitions.

A step-by-step example will make this more obvious.  Let’s consider the
expression @code{a[bcd]*b}.  This matches the letter @code{'a'}, zero or more letters
from the class @code{[bcd]}, and finally ends with a @code{'b'}.  Now imagine matching
this RE against the string @code{'abcbd'}.


@multitable {xxxxxxxx} {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Step

@tab

Matched

@tab

Explanation

@item

1

@tab

@code{a}

@tab

The @code{a} in the RE matches.

@item

2

@tab

@code{abcbd}

@tab

The engine matches @code{[bcd]*},
going as far as it can, which
is to the end of the string.

@item

3

@tab

`Failure'

@tab

The engine tries to match
@code{b}, but the current position
is at the end of the string, so
it fails.

@item

4

@tab

@code{abcb}

@tab

Back up, so that  @code{[bcd]*}
matches one less character.

@item

5

@tab

`Failure'

@tab

Try @code{b} again, but the
current position is at the last
character, which is a @code{'d'}.

@item

6

@tab

@code{abc}

@tab

Back up again, so that
@code{[bcd]*} is only matching
@code{bc}.

@item

7

@tab

@code{abcb}

@tab

Try @code{b} again.  This time
the character at the
current position is @code{'b'}, so
it succeeds.

@end multitable


The end of the RE has now been reached, and it has matched @code{'abcb'}.  This
demonstrates how the matching engine goes as far as it can at first, and if no
match is found it will then progressively back up and retry the rest of the RE
again and again.  It will back up until it has tried zero matches for
@code{[bcd]*}, and if that subsequently fails, the engine will conclude that the
string doesn’t match the RE at all.

Another repeating metacharacter is @code{+}, which matches one or more times.  Pay
careful attention to the difference between @code{*} and @code{+}; @code{*} matches
`zero' or more times, so whatever’s being repeated may not be present at all,
while @code{+} requires at least `one' occurrence.  To use a similar example,
@code{ca+t} will match @code{'cat'} (1 @code{'a'}), @code{'caaat'} (3 @code{'a'}s), but won’t
match @code{'ct'}.

There are two more repeating operators or quantifiers.  The question mark character, @code{?},
matches either once or zero times; you can think of it as marking something as
being optional.  For example, @code{home-?brew} matches either @code{'homebrew'} or
@code{'home-brew'}.

The most complicated quantifier is @code{@{m,n@}}, where `m' and `n' are
decimal integers.  This quantifier means there must be at least `m' repetitions,
and at most `n'.  For example, @code{a/@{1,3@}b} will match @code{'a/b'}, @code{'a//b'}, and
@code{'a///b'}.  It won’t match @code{'ab'}, which has no slashes, or @code{'a////b'}, which
has four.

You can omit either `m' or `n'; in that case, a reasonable value is assumed for
the missing value.  Omitting `m' is interpreted as a lower limit of 0, while
omitting `n' results in an upper bound of infinity.

The simplest case @code{@{m@}} matches the preceding item exactly `m' times.
For example, @code{a/@{2@}b} will only match @code{'a//b'}.

Readers of a reductionist bent may notice that the three other quantifiers can
all be expressed using this notation.  @code{@{0,@}} is the same as @code{*}, @code{@{1,@}}
is equivalent to @code{+}, and @code{@{0,1@}} is the same as @code{?}.  It’s better to use
@code{*}, @code{+}, or @code{?} when you can, simply because they’re shorter and easier
to read.

@node Using regular expressions,More pattern power,Simple patterns,Regular expression HOWTO
@anchor{howto/regex using-regular-expressions}@anchor{5b4e}
@subsection Using regular expressions


Now that we’ve looked at some simple regular expressions, how do we actually use
them in Python?  The @ref{c1,,re} module provides an interface to the regular
expression engine, allowing you to compile REs into objects and then perform
matches with them.

@menu
* Compiling regular expressions:: 
* The backslash plague:: 
* Performing matches:: 
* Module-level functions:: 
* Compilation flags:: 

@end menu

@node Compiling regular expressions,The backslash plague,,Using regular expressions
@anchor{howto/regex compiling-regular-expressions}@anchor{5b4f}
@subsubsection Compiling regular expressions


Regular expressions are compiled into pattern objects, which have
methods for various operations such as searching for pattern matches or
performing string substitutions.

@example
>>> import re
>>> p = re.compile('ab*')
>>> p
re.compile('ab*')
@end example

@ref{f93,,re.compile()} also accepts an optional `flags' argument, used to enable
various special features and syntax variations.  We’ll go over the available
settings later, but for now a single example will do:

@example
>>> p = re.compile('ab*', re.IGNORECASE)
@end example

The RE is passed to @ref{f93,,re.compile()} as a string.  REs are handled as strings
because regular expressions aren’t part of the core Python language, and no
special syntax was created for expressing them.  (There are applications that
don’t need REs at all, so there’s no need to bloat the language specification by
including them.) Instead, the @ref{c1,,re} module is simply a C extension module
included with Python, just like the @ref{d4,,socket} or @ref{13c,,zlib} modules.

Putting REs in strings keeps the Python language simpler, but has one
disadvantage which is the topic of the next section.

@node The backslash plague,Performing matches,Compiling regular expressions,Using regular expressions
@anchor{howto/regex id1}@anchor{5b50}@anchor{howto/regex the-backslash-plague}@anchor{5b51}
@subsubsection The backslash plague


As stated earlier, 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 conflicts with Python’s usage of the same
character for the same purpose in string literals.

Let’s say you want to write a RE that matches the string @code{\section}, which
might be found in a LaTeX file.  To figure out what to write in the program
code, start with the desired string to be matched.  Next, you must escape any
backslashes and other metacharacters by preceding them with a backslash,
resulting in the string @code{\\section}.  The resulting string that must be passed
to @ref{f93,,re.compile()} must be @code{\\section}.  However, to express this as a
Python string literal, both backslashes must be escaped `again'.


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Characters

@tab

Stage

@item

@code{\section}

@tab

Text string to be matched

@item

@code{\\section}

@tab

Escaped backslash for @ref{f93,,re.compile()}

@item

@code{"\\\\section"}

@tab

Escaped backslashes for a string literal

@end multitable


In short, to match a literal backslash, one has to write @code{'\\\\'} as the RE
string, because the regular expression must be @code{\\}, and each backslash must
be expressed as @code{\\} inside a regular Python string literal.  In REs that
feature backslashes repeatedly, this leads to lots of repeated backslashes and
makes the resulting strings difficult to understand.

The solution is to use Python’s raw string notation for regular expressions;
backslashes are not handled in any special way in a string literal prefixed with
@code{'r'}, so @code{r"\n"} is a two-character string containing @code{'\'} and @code{'n'},
while @code{"\n"} is a one-character string containing a newline. Regular
expressions will often be written in Python code using this raw string notation.

In addition, special escape sequences that are valid in regular expressions,
but not valid as Python string literals, now result in a
@ref{44a,,SyntaxWarning} and will eventually become a @ref{17e,,SyntaxError},
which means the sequences will be invalid if raw string notation or escaping
the backslashes isn’t used.


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} 
@headitem

Regular String

@tab

Raw string

@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 Performing matches,Module-level functions,The backslash plague,Using regular expressions
@anchor{howto/regex performing-matches}@anchor{5b52}
@subsubsection Performing matches


Once you have an object representing a compiled regular expression, what do you
do with it?  Pattern objects have several methods and attributes.
Only the most significant ones will be covered here; consult the @ref{c1,,re} docs
for a complete listing.


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Method/Attribute

@tab

Purpose

@item

@code{search()}

@tab

Scan through a string, looking for any
location where this RE matches.

@item

@code{prefixmatch()}

@tab

Determine if the RE matches at the beginning
of the string. Previously named @ref{2f9,,match()}.

@item

@code{findall()}

@tab

Find all substrings where the RE matches, and
return them as a list.

@item

@code{finditer()}

@tab

Find all substrings where the RE matches, and
return them as an @ref{6ce,,iterator}.

@end multitable


@ref{298e,,search()} and @ref{24b,,prefixmatch()} return @code{None} if no match can be found.  If
they’re successful, a @ref{1332,,match object} instance is returned,
containing information about the match: where it starts and ends, the substring
it matched, and more.

You can learn about this by interactively experimenting with the @ref{c1,,re}
module.

This HOWTO uses the standard Python interpreter for its examples. First, run the
Python interpreter, import the @ref{c1,,re} module, and compile a RE:

@example
>>> import re
>>> p = re.compile('[a-z]+')
>>> p
re.compile('[a-z]+')
@end example

Now, you can try matching various strings against the RE @code{[a-z]+}.  An empty
string shouldn’t match at all, since @code{+} means “one or more repetitions”.
@ref{298e,,search()} should return @code{None} in this case, which will cause the
interpreter to print no output.  You can explicitly print the result of
@code{search()} to make this clear.

@example
>>> p.search("")
>>> print(p.search(""))
None
@end example

Now, let’s try it on a string that it should match, such as @code{tempo}.  In this
case, @ref{298e,,search()} will return a @ref{1332,,match object}, so you
should store the result in a variable for later use.

@example
>>> m = p.search('tempo')
>>> m
<re.Match object; span=(0, 5), match='tempo'>
@end example

Now you can query the @ref{1332,,match object} for information
about the matching string.  Match object instances
also have several methods and attributes; the most important ones are:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Method/Attribute

@tab

Purpose

@item

@code{group()}

@tab

Return the string matched by the RE

@item

@code{start()}

@tab

Return the starting position of the match

@item

@code{end()}

@tab

Return the ending position of the match

@item

@code{span()}

@tab

Return a tuple containing the (start, end)
positions  of the match

@end multitable


Trying these methods will soon clarify their meaning:

@example
>>> m.group()
'tempo'
>>> m.start(), m.end()
(0, 5)
>>> m.span()
(0, 5)
@end example

@ref{13d3,,group()} returns the substring that was matched by the RE.  @ref{29a0,,start()}
and @ref{29a1,,end()} return the starting and ending index of the match. @ref{29a2,,span()}
returns both start and end indexes in a single tuple.
The @ref{298e,,search()} method of patterns
scans through the string, so the match may not start at zero.
However, the @ref{24b,,prefixmatch()}
method only checks if the RE matches at the start of a string, so @code{start()}
will always be zero in that case.

@example
>>> m = p.search('::: message'); print(m)
<re.Match object; span=(4, 11), match='message'>
>>> m.group()
'message'
>>> m.span()
(4, 11)
>>> print(p.prefixmatch('::: message'))
None
@end example

In actual programs, the most common style is to store the
@ref{1332,,match object} in a variable, and then check if it was
@code{None}.  This usually looks like:

@example
p = re.compile( ... )
m = p.search( 'string goes here' )
if m:
    print('Match found: ', m.group())
else:
    print('No match')
@end example

Two pattern methods return all of the matches for a pattern.
@ref{2994,,findall()} returns a list of matching strings:

@example
>>> p = re.compile(r'\d+')
>>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')
['12', '11', '10']
@end example

The @code{r} prefix, making the literal a raw string literal, is needed in this
example because escape sequences in a normal «cooked» string literal that are
not recognized by Python, as opposed to regular expressions, now result in a
@ref{44a,,SyntaxWarning} and will eventually become a @ref{17e,,SyntaxError}.  See
@ref{5b51,,The backslash plague}.

@ref{2994,,findall()} has to create the entire list before it can be returned as the
result.  The @ref{2995,,finditer()} method returns a sequence of
@ref{1332,,match object} instances as an @ref{6ce,,iterator}:

@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 Module-level functions,Compilation flags,Performing matches,Using regular expressions
@anchor{howto/regex module-level-functions}@anchor{5b53}
@subsubsection Module-level functions


You don’t have to create a pattern object and call its methods; the
@ref{c1,,re} module also provides top-level functions called @ref{15d3,,search()},
@ref{24a,,prefixmatch()}, @ref{13d2,,findall()}, @ref{7a1,,sub()}, and so forth.  These functions
take the same arguments as the corresponding pattern method with
the RE string added as the first argument, and still return either @code{None} or a
@ref{1332,,match object} instance.

@example
>>> print(re.prefixmatch(r'From\s+', 'Fromage amk'))
None
>>> re.prefixmatch(r'From\s+', 'From amk Thu May 14 19:12:10 1998')
<re.Match object; span=(0, 5), match='From '>
@end example

Under the hood, these functions simply create a pattern object for you
and call the appropriate method on it.  They also store the compiled
object in a cache, so future calls using the same RE won’t need to
parse the pattern again and again.

Should you use these module-level functions, or should you get the
pattern and call its methods yourself?  If you’re accessing a regex
within a loop, pre-compiling it will save a few function calls.
Outside of loops, there’s not much difference thanks to the internal
cache.

@node Compilation flags,,Module-level functions,Using regular expressions
@anchor{howto/regex compilation-flags}@anchor{5b54}
@subsubsection Compilation flags


Compilation flags let you modify some aspects of how regular expressions work.
Flags are available in the @ref{c1,,re} module under two names, a long name such as
@ref{1c9b,,IGNORECASE} and a short, one-letter form such as @ref{2980,,I}.  (If you’re
familiar with Perl’s pattern modifiers, the one-letter forms use the same
letters; the short form of @ref{298c,,re.VERBOSE} is @ref{2985,,re.X}, for example.)
Multiple flags can be specified by bitwise OR-ing them; @code{re.I | re.M} sets
both the @code{I} and @ref{2982,,M} flags, for example.

Here’s a table of the available flags, followed by a more detailed explanation
of each one.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Flag

@tab

Meaning

@item

@ref{a1d,,ASCII}, @ref{297f,,A}

@tab

Makes several escapes like @code{\w}, @code{\b},
@code{\s} and @code{\d} match only on ASCII
characters with the respective property.

@item

@ref{297d,,DOTALL}, @ref{2983,,S}

@tab

Make @code{.} match any character, including
newlines.

@item

@ref{1c9b,,IGNORECASE}, @ref{2980,,I}

@tab

Do case-insensitive matches.

@item

@ref{f29,,LOCALE}, @ref{2981,,L}

@tab

Do a locale-aware match.

@item

@ref{297e,,MULTILINE}, @ref{2982,,M}

@tab

Multi-line matching, affecting @code{^} and
@code{$}.

@item

@ref{298c,,VERBOSE}, @ref{2985,,X}
(for “extended”)

@tab

Enable verbose REs, which can be organized
more cleanly and understandably.

@end multitable



@deffn {Δεδομένα} re.I

@deffnx {Δεδομένα} 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{a1d,,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{1c9b,,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{f29,,LOCALE} flag.
@end deffn


@deffn {Δεδομένα} re.L

@deffnx {Δεδομένα} re.LOCALE

Make @code{\w}, @code{\W}, @code{\b}, @code{\B} and case-insensitive matching dependent
on the current locale instead of the Unicode database.

Locales are a feature of the C library intended to help in writing programs
that take account of language differences.  For example, if you’re
processing encoded French text, you’d want to be able to write @code{\w+} to
match words, but @code{\w} only matches the character class @code{[A-Za-z]} in
bytes patterns; it won’t match bytes corresponding to @code{é} or @code{ç}.
If your system is configured properly and a French locale is selected,
certain C functions will tell the program that the byte corresponding to
@code{é} should also be considered a letter.
Setting the @ref{f29,,LOCALE} flag when compiling a regular expression will cause
the resulting compiled object to use these C functions for @code{\w}; this is
slower, but also enables @code{\w+} to match French words as you’d expect.
The use of this flag is discouraged in Python 3 as the locale mechanism
is very unreliable, it only handles one «culture» at a time, and it only
works with 8-bit locales.  Unicode matching is already enabled by default
in Python 3 for Unicode (str) patterns, and it is able to handle different
locales/languages.
@end deffn


@deffn {Δεδομένα} re.M

@deffnx {Δεδομένα} re.MULTILINE

(@code{^} and @code{$} haven’t been explained yet;  they’ll be introduced in section
@ref{5b55,,More metacharacters}.)

Usually @code{^} matches only at the beginning of the string, and @code{$} matches
only at the end of the string and immediately before the newline (if any) at the
end of the string. When this flag is specified, @code{^} matches at the beginning
of the string and at the beginning of each line within the string, immediately
following each newline.  Similarly, the @code{$} metacharacter matches either at
the end of the string and at the end of each line (immediately preceding each
newline).
@end deffn


@deffn {Δεδομένα} re.S

@deffnx {Δεδομένα} re.DOTALL

Makes the @code{'.'} special character match any character at all, including a
newline; without this flag, @code{'.'} will match anything `except' a newline.
@end deffn


@deffn {Δεδομένα} re.A

@deffnx {Δεδομένα} re.ASCII

Make @code{\w}, @code{\W}, @code{\b}, @code{\B}, @code{\s} and @code{\S} perform ASCII-only
matching instead of full Unicode matching. This is only meaningful for
Unicode patterns, and is ignored for byte patterns.
@end deffn


@deffn {Δεδομένα} re.X

@deffnx {Δεδομένα} re.VERBOSE

This flag allows you to write regular expressions that are more readable by
granting you more flexibility in how you can format them.  When this flag has
been specified, whitespace within the RE string is ignored, except when the
whitespace is in a character class or preceded by an unescaped backslash; this
lets you organize and indent the RE more clearly.  This flag also lets you put
comments within a RE that will be ignored by the engine; comments are marked by
a @code{'#'} that’s neither in a character class nor preceded by an unescaped
backslash.

For example, here’s a RE that uses @ref{298c,,re.VERBOSE}; see how much easier it
is to read?

@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

Without the verbose setting, the RE would look like this:

@example
charref = re.compile("&#(0[0-7]+"
                     "|[0-9]+"
                     "|x[0-9a-fA-F]+);")
@end example

In the above example, Python’s automatic concatenation of string literals has
been used to break up the RE into smaller pieces, but it’s still more difficult
to understand than the version using @ref{298c,,re.VERBOSE}.
@end deffn

@node More pattern power,Modifying strings,Using regular expressions,Regular expression HOWTO
@anchor{howto/regex more-pattern-power}@anchor{5b56}
@subsection More pattern power


So far we’ve only covered a part of the features of regular expressions.  In
this section, we’ll cover some new metacharacters, and how to use groups to
retrieve portions of the text that was matched.

@menu
* More metacharacters:: 
* Grouping:: 
* Non-capturing and named groups:: 
* Lookahead assertions:: 

@end menu

@node More metacharacters,Grouping,,More pattern power
@anchor{howto/regex id2}@anchor{5b57}@anchor{howto/regex more-metacharacters}@anchor{5b55}
@subsubsection More metacharacters


There are some metacharacters that we haven’t covered yet.  Most of them will be
covered in this section.

Some of the remaining metacharacters to be discussed are `zero-width
assertions'.  They don’t cause the engine to advance through the string;
instead, they consume no characters at all, and simply succeed or fail.  For
example, @code{\b} is an assertion that the current position is located at a word
boundary; the position isn’t changed by the @code{\b} at all.  This means that
zero-width assertions should never be repeated, because if they match once at a
given location, they can obviously be matched an infinite number of times.


@table @asis

@item @code{|}

Alternation, or the «or» operator.   If `A' and `B' are regular expressions,
@code{A|B} will match any string that matches either `A' or `B'. @code{|} has very
low precedence in order to make it work reasonably when you’re alternating
multi-character strings. @code{Crow|Servo} will match either @code{'Crow'} or @code{'Servo'},
not @code{'Cro'}, a @code{'w'} or an @code{'S'}, and @code{'ervo'}.

To match a literal @code{'|'}, use @code{\|}, or enclose it inside a character class,
as in @code{[|]}.

@item @code{^}

Matches at the beginning of lines.  Unless the @ref{297e,,MULTILINE} flag has been
set, this will only match at the beginning of the string.  In @code{MULTILINE}
mode, this also matches immediately after each newline within the string.

For example, if you wish to match the word @code{From} only at the beginning of a
line, the RE to use is @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

To match a literal @code{'^'}, use @code{\^}.

@item @code{$}

Matches at the end of a line, which is defined as either the end of the string,
or any location followed by a newline character.

@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

To match a literal @code{'$'}, use @code{\$} or enclose it inside a character class,
as in  @code{[$]}.

@item @code{\A}

Matches only at the start of the string.  When not in @ref{297e,,MULTILINE} mode,
@code{\A} and @code{^} are effectively the same.  In @code{MULTILINE} mode, they’re
different: @code{\A} still matches only at the beginning of the string, but @code{^}
may match at any location inside the string that follows a newline character.

@item @code{\z}

Matches only at the end of the string.

@item @code{\Z}

The same as @code{\z}.  For compatibility with old Python versions.

@item @code{\b}

Word boundary.  This is a zero-width assertion that matches only at the
beginning or end of a word.  A word is defined as a sequence of alphanumeric
characters, so the end of a word is indicated by whitespace or a
non-alphanumeric character.

The following example matches @code{class} only when it’s a complete word; it won’t
match when it’s contained inside another word.

@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

There are two subtleties you should remember when using this special sequence.
First, this is the worst collision between Python’s string literals and regular
expression sequences.  In Python’s string literals, @code{\b} is the backspace
character, ASCII value 8.  If you’re not using raw strings, then Python will
convert the @code{\b} to a backspace, and your RE won’t match as you expect it to.
The following example looks the same as our previous RE, but omits the @code{'r'}
in front of the RE string.

@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

Second, inside a character class, where there’s no use for this assertion,
@code{\b} represents the backspace character, for compatibility with Python’s
string literals.

@item @code{\B}

Another zero-width assertion, this is the opposite of @code{\b}, only matching when
the current position is not at a word boundary.
@end table

@node Grouping,Non-capturing and named groups,More metacharacters,More pattern power
@anchor{howto/regex grouping}@anchor{5b58}
@subsubsection Grouping


Frequently you need to obtain more information than just whether the RE matched
or not.  Regular expressions are often used to dissect strings by writing a RE
divided into several subgroups which match different components of interest.
For example, an RFC-822 header line is divided into a header name and a value,
separated by a @code{':'}, like this:

@example
From: author@@example.com
User-Agent: Thunderbird 1.5.0.9 (X11/20061227)
MIME-Version: 1.0
To: editor@@example.com
@end example

This can be handled by writing a regular expression which matches an entire
header line, and has one group which matches the header name, and another group
which matches the header’s value.

Groups are marked by the @code{'('}, @code{')'} metacharacters. @code{'('} and @code{')'}
have much the same meaning as they do in mathematical expressions; they group
together the expressions contained inside them, and you can repeat the contents
of a group with a quantifier, such as @code{*}, @code{+}, @code{?}, or
@code{@{m,n@}}.  For example, @code{(ab)*} will match zero or more repetitions of
@code{ab}.

@example
>>> p = re.compile('(ab)*')
>>> print(p.search('ababababab').span())
(0, 10)
@end example

Groups indicated with @code{'('}, @code{')'} also capture the starting and ending
index of the text that they match; this can be retrieved by passing an argument
to @ref{13d3,,group()}, @ref{29a0,,start()}, @ref{29a1,,end()}, and
@ref{29a2,,span()}.  Groups are
numbered starting with 0.  Group 0 is always present; it’s the whole RE, so
@ref{1332,,match object} methods all have group 0 as their default
argument.  Later we’ll see how to express groups that don’t capture the span
of text that they match.

@example
>>> p = re.compile('(a)b')
>>> m = p.search('ab')
>>> m.group()
'ab'
>>> m.group(0)
'ab'
@end example

Subgroups are numbered from left to right, from 1 upward.  Groups can be nested;
to determine the number, just count the opening parenthesis characters, going
from left to right.

@example
>>> p = re.compile('(a(b)c)d')
>>> m = p.search('abcd')
>>> m.group(0)
'abcd'
>>> m.group(1)
'abc'
>>> m.group(2)
'b'
@end example

@ref{13d3,,group()} can be passed multiple group numbers at a time, in which case it
will return a tuple containing the corresponding values for those groups.

@example
>>> m.group(2,1,2)
('b', 'abc', 'b')
@end example

The @ref{13d4,,groups()} method returns a tuple containing the strings for all the
subgroups, from 1 up to however many there are.

@example
>>> m.groups()
('abc', 'b')
@end example

Backreferences in a pattern allow you to specify that the contents of an earlier
capturing group must also be found at the current location in the string.  For
example, @code{\1} will succeed if the exact contents of group 1 can be found at
the current position, and fails otherwise.  Remember that Python’s string
literals also use a backslash followed by numbers to allow including arbitrary
characters in a string, so be sure to use a raw string when incorporating
backreferences in a RE.

For example, the following RE detects doubled words in a string.

@example
>>> p = re.compile(r'\b(\w+)\s+\1\b')
>>> p.search('Paris in the the spring').group()
'the the'
@end example

Backreferences like this aren’t often useful for just searching through a string
— there are few text formats which repeat data in this way — but you’ll soon
find out that they’re `very' useful when performing string substitutions.

@node Non-capturing and named groups,Lookahead assertions,Grouping,More pattern power
@anchor{howto/regex non-capturing-and-named-groups}@anchor{5b59}
@subsubsection Non-capturing and named groups


Elaborate REs may use many groups, both to capture substrings of interest, and
to group and structure the RE itself.  In complex REs, it becomes difficult to
keep track of the group numbers.  There are two features which help with this
problem.  Both of them use a common syntax for regular expression extensions, so
we’ll look at that first.

Perl 5 is well known for its powerful additions to standard regular expressions.
For these new features the Perl developers couldn’t choose new single-keystroke metacharacters
or new special sequences beginning with @code{\} without making Perl’s regular
expressions confusingly different from standard REs.  If they chose @code{&} as a
new metacharacter, for example, old expressions would be assuming that @code{&} was
a regular character and wouldn’t have escaped it by writing @code{\&} or @code{[&]}.

The solution chosen by the Perl developers was to use @code{(?...)} as the
extension syntax.  @code{?} immediately after a parenthesis was a syntax error
because the @code{?} would have nothing to repeat, so this didn’t introduce any
compatibility problems.  The characters immediately after the @code{?}  indicate
what extension is being used, so @code{(?=foo)} is one thing (a positive lookahead
assertion) and @code{(?:foo)} is something else (a non-capturing group containing
the subexpression @code{foo}).

Python supports several of Perl’s extensions and adds an extension
syntax to Perl’s extension syntax.  If the first character after the
question mark is a @code{P}, you know that it’s an extension that’s
specific to Python.

Now that we’ve looked at the general extension syntax, we can return
to the features that simplify working with groups in complex REs.

Sometimes you’ll want to use a group to denote a part of a regular expression,
but aren’t interested in retrieving the group’s contents. You can make this fact
explicit by using a non-capturing group: @code{(?:...)}, where you can replace the
@code{...} with any other regular expression.

@example
>>> m = re.search("([abc])+", "abc")
>>> m.groups()
('c',)
>>> m = re.search("(?:[abc])+", "abc")
>>> m.groups()
()
@end example

Except for the fact that you can’t retrieve the contents of what the group
matched, a non-capturing group behaves exactly the same as a capturing group;
you can put anything inside it, repeat it with a repetition metacharacter such
as @code{*}, and nest it within other groups (capturing or non-capturing).
@code{(?:...)} is particularly useful when modifying an existing pattern, since you
can add new groups without changing how all the other groups are numbered.  It
should be mentioned that there’s no performance difference in searching between
capturing and non-capturing groups; neither form is any faster than the other.

A more significant feature is named groups: instead of referring to them by
numbers, groups can be referenced by a name.

The syntax for a named group is one of the Python-specific extensions:
@code{(?P<name>...)}.  `name' is, obviously, the name of the group.  Named groups
behave exactly like capturing groups, and additionally associate a name
with a group.  The @ref{1332,,match object} methods that deal with
capturing groups all accept either integers that refer to the group by number
or strings that contain the desired group’s name.  Named groups are still
given numbers, so you can retrieve information about a group in two ways:

@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

Additionally, you can retrieve named groups as a dictionary with
@ref{299f,,groupdict()}:

@example
>>> m = re.search(r'(?P<first>\w+) (?P<last>\w+)', 'Jane Doe')
>>> m.groupdict()
@{'first': 'Jane', 'last': 'Doe'@}
@end example

Named groups are handy because they let you use easily remembered names, instead
of having to remember numbers.  Here’s an example RE from the @ref{77,,imaplib}
module:

@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

It’s obviously much easier to retrieve @code{m.group('zonem')}, instead of having
to remember to retrieve group 9.

The syntax for backreferences in an expression such as @code{(...)\1} refers to the
number of the group.  There’s naturally a variant that uses the group name
instead of the number. This is another Python extension: @code{(?P=name)} indicates
that the contents of the group called `name' should again be matched at the
current point.  The regular expression for finding doubled words,
@code{\b(\w+)\s+\1\b} can also be written as @code{\b(?P<word>\w+)\s+(?P=word)\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 Lookahead assertions,,Non-capturing and named groups,More pattern power
@anchor{howto/regex lookahead-assertions}@anchor{5b5a}
@subsubsection Lookahead assertions


Another zero-width assertion is the lookahead assertion.  Lookahead assertions
are available in both positive and negative form, and  look like this:


@table @asis

@item @code{(?=...)}

Positive lookahead assertion.  This succeeds if the contained regular
expression, represented here by @code{...}, successfully matches at the current
location, and fails otherwise. But, once the contained expression has been
tried, the matching engine doesn’t advance at all; the rest of the pattern is
tried right where the assertion started.

@item @code{(?!...)}

Negative lookahead assertion.  This is the opposite of the positive assertion;
it succeeds if the contained expression `doesn’t' match at the current position
in the string.
@end table

To make this concrete, let’s look at a case where a lookahead is useful.
Consider a simple pattern to match a filename and split it apart into a base
name and an extension, separated by a @code{.}.  For example, in @code{news.rc},
@code{news} is the base name, and @code{rc} is the filename’s extension.

The pattern to match this is quite simple:

@code{.*[.].*$}

Notice that the @code{.} needs to be treated specially because it’s a
metacharacter, so it’s inside a character class to only match that
specific character.  Also notice the trailing @code{$}; this is added to
ensure that all the rest of the string must be included in the
extension.  This regular expression matches @code{foo.bar} and
@code{autoexec.bat} and @code{sendmail.cf} and @code{printers.conf}.

Now, consider complicating the problem a bit; what if you want to match
filenames where the extension is not @code{bat}? Some incorrect attempts:

@code{.*[.][^b].*$}

The first attempt above tries to exclude @code{bat} by requiring
that the first character of the extension is not a @code{b}.  This is wrong,
because the pattern also doesn’t match @code{foo.bar}.

@code{.*[.]([^b]..|.[^a].|..[^t])$}

The expression gets messier when you try to patch up the first solution by
requiring one of the following cases to match: the first character of the
extension isn’t @code{b}; the second character isn’t @code{a}; or the third character
isn’t @code{t}.  This accepts @code{foo.bar} and rejects @code{autoexec.bat}, but it
requires a three-letter extension and won’t accept a filename with a two-letter
extension such as @code{sendmail.cf}.  We’ll complicate the pattern again in an
effort to fix it.

@code{.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$}

In the third attempt, the second and third letters are all made optional in
order to allow matching extensions shorter than three characters, such as
@code{sendmail.cf}.

The pattern’s getting really complicated now, which makes it hard to read and
understand.  Worse, if the problem changes and you want to exclude both @code{bat}
and @code{exe} as extensions, the pattern would get even more complicated and
confusing.

A negative lookahead cuts through all this confusion:

@code{.*[.](?!bat$)[^.]*$}

The negative lookahead means: if the expression @code{bat}
doesn’t match at this point, try the rest of the pattern; if @code{bat$} does
match, the whole pattern will fail.  The trailing @code{$} is required to ensure
that something like @code{sample.batch}, where the extension only starts with
@code{bat}, will be allowed.  The @code{[^.]*} makes sure that the pattern works
when there are multiple dots in the filename.

Excluding another filename extension is now easy; simply add it as an
alternative inside the assertion.  The following pattern excludes filenames that
end in either @code{bat} or @code{exe}:

@code{.*[.](?!bat$|exe$)[^.]*$}

@node Modifying strings,Common problems,More pattern power,Regular expression HOWTO
@anchor{howto/regex modifying-strings}@anchor{5b5b}
@subsection Modifying strings


Up to this point, we’ve simply performed searches against a static string.
Regular expressions are also commonly used to modify strings in various ways,
using the following pattern methods:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Method/Attribute

@tab

Purpose

@item

@code{split()}

@tab

Split the string into a list, splitting it
wherever the RE matches

@item

@code{sub()}

@tab

Find all substrings where the RE matches, and
replace them with a different string

@item

@code{subn()}

@tab

Does the same thing as @code{sub()},  but
returns the new string and the number of
replacements

@end multitable


@menu
* Splitting strings:: 
* Search and replace:: 

@end menu

@node Splitting strings,Search and replace,,Modifying strings
@anchor{howto/regex splitting-strings}@anchor{5b5c}
@subsubsection Splitting strings


The @ref{2993,,split()} method of a pattern splits a string apart
wherever the RE matches, returning a list of the pieces. It’s similar to the
@ref{125b,,split()} method of strings but provides much more generality in the
delimiters that you can split by; string @code{split()} only supports splitting by
whitespace or by a fixed string.  As you’d expect, there’s a module-level
@ref{7a0,,re.split()} function, too.


@deffn {Μέθοδος} .split (string[, maxsplit=0])

Split `string' by the matches of the regular expression.  If capturing
parentheses are used in the RE, then their contents will also be returned as
part of the resulting list.  If `maxsplit' is nonzero, at most `maxsplit' splits
are performed.
@end deffn

You can limit the number of splits made, by passing a value for `maxsplit'.
When `maxsplit' is nonzero, at most `maxsplit' splits will be made, and the
remainder of the string is returned as the final element of the list.  In the
following example, the delimiter is any sequence of non-alphanumeric characters.

@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

Sometimes you’re not only interested in what the text between delimiters is, but
also need to know what the delimiter was.  If capturing parentheses are used in
the RE, then their values are also returned as part of the list.  Compare the
following calls:

@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

The module-level function @ref{7a0,,re.split()} adds the RE to be used as the first
argument, but is otherwise the same.

@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 Search and replace,,Splitting strings,Modifying strings
@anchor{howto/regex search-and-replace}@anchor{5b5d}
@subsubsection Search and replace


Another common task is to find all the matches for a pattern, and replace them
with a different string.  The @ref{2996,,sub()} method takes a replacement value,
which can be either a string or a function, and the string to be processed.


@deffn {Μέθοδος} .sub (replacement, string[, count=0])

Returns the string obtained by replacing the leftmost non-overlapping
occurrences of the RE in `string' by the replacement `replacement'.  If the
pattern isn’t found, `string' is returned unchanged.

The optional argument `count' is the maximum number of pattern occurrences to be
replaced; `count' must be a non-negative integer.  The default value of 0 means
to replace all occurrences.
@end deffn

Here’s a simple example of using the @ref{2996,,sub()} method.  It replaces colour
names with the word @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

The @ref{2997,,subn()} method does the same work, but returns a 2-tuple containing the
new string value and the number of replacements  that were performed:

@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

Empty matches are replaced only when they’re not adjacent to a previous empty match.

@example
>>> p = re.compile('x*')
>>> p.sub('-', 'abxd')
'-a-b--d-'
@end example

If `replacement' is a string, any backslash escapes in it are processed.  That
is, @code{\n} is converted to a single newline character, @code{\r} is converted to a
carriage return, and so forth. Unknown escapes such as @code{\&} are left alone.
Backreferences, such as @code{\6}, are replaced with the substring matched by the
corresponding group in the RE.  This lets you incorporate portions of the
original text in the resulting replacement string.

This example matches the word @code{section} followed by a string enclosed in
@code{@{}, @code{@}}, and changes @code{section} to @code{subsection}:

@example
>>> p = re.compile('section@{ ( [^@}]* ) @}', re.VERBOSE)
>>> p.sub(r'subsection@{\1@}','section@{First@} section@{second@}')
'subsection@{First@} subsection@{second@}'
@end example

There’s also a syntax for referring to named groups as defined by the
@code{(?P<name>...)} syntax.  @code{\g<name>} will use the substring matched by the
group named @code{name}, and  @code{\g<number>}  uses the corresponding group number.
@code{\g<2>} is therefore equivalent to @code{\2},  but isn’t ambiguous in a
replacement string such as @code{\g<2>0}.  (@code{\20} would be interpreted as a
reference to group 20, not a reference to group 2 followed by the literal
character @code{'0'}.)  The following substitutions are all equivalent, but use all
three variations of the replacement string.

@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' can also be a function, which gives you even more control.  If
`replacement' is a function, the function is called for every non-overlapping
occurrence of `pattern'.  On each call, the function is passed a
@ref{1332,,match object} argument for the match and can use this
information to compute the desired replacement string and return it.

In the following example, the replacement function translates decimals into
hexadecimal:

@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

When using the module-level @ref{7a1,,re.sub()} function, the pattern is passed as
the first argument.  The pattern may be provided as an object or as a string; if
you need to specify regular expression flags, you must either use a
pattern object as the first parameter, or use embedded modifiers in the
pattern string, e.g. @code{sub("(?i)b+", "x", "bbbb BBBB")} returns @code{'x x'}.

@node Common problems,Feedback,Modifying strings,Regular expression HOWTO
@anchor{howto/regex common-problems}@anchor{5b5e}
@subsection Common problems


Regular expressions are a powerful tool for some applications, but in some ways
their behaviour isn’t intuitive and at times they don’t behave the way you may
expect them to.  This section will point out some of the most common pitfalls.

@menu
* Use string methods:: 
* prefixmatch() (aka match) versus search(): prefixmatch aka match versus search. 
* Greedy versus non-greedy:: 
* Using re.VERBOSE: Using re VERBOSE. 

@end menu

@node Use string methods,prefixmatch aka match versus search,,Common problems
@anchor{howto/regex use-string-methods}@anchor{5b5f}
@subsubsection Use string methods


Sometimes using the @ref{c1,,re} module is a mistake.  If you’re matching a fixed
string, or a single character class, and you’re not using any @code{re} features
such as the @ref{1c9b,,IGNORECASE} flag, then the full power of regular expressions
may not be required. Strings have several methods for performing operations with
fixed strings and they’re usually much faster, because the implementation is a
single small C loop that’s been optimized for the purpose, instead of the large,
more generalized regular expression engine.

One example might be replacing a single fixed string with another one; for
example, you might replace @code{word} with @code{deed}.  @ref{7a1,,re.sub()} seems like the
function to use for this, but consider the @ref{6c0,,replace()} method.  Note that
@code{replace()} will also replace @code{word} inside words, turning @code{swordfish}
into @code{sdeedfish}, but the  naive RE @code{word} would have done that, too.  (To
avoid performing the substitution on parts of words, the pattern would have to
be @code{\bword\b}, in order to require that @code{word} have a word boundary on
either side.  This takes the job beyond  @code{replace()}”s abilities.)

Another common task is deleting every occurrence of a single character from a
string or replacing it with another single character.  You might do this with
something like @code{re.sub('\n', ' ', S)}, but @ref{1979,,translate()} is capable of
doing both tasks and will be faster than any regular expression operation can
be.

In short, before turning to the @ref{c1,,re} module, consider whether your problem
can be solved with a faster and simpler string method.

@node prefixmatch aka match versus search,Greedy versus non-greedy,Use string methods,Common problems
@anchor{howto/regex match-versus-search}@anchor{5b60}@anchor{howto/regex prefixmatch-aka-match-versus-search}@anchor{5b61}
@subsubsection prefixmatch() (aka match) versus search()


@ref{24a,,prefixmatch()} was added in Python 3.15 as the @ref{2f9,,preferred name} for @ref{24c,,match()}. Before this, it was only known
as @code{match()} and the distinction with @ref{15d3,,search()} was often
misunderstood.

@code{prefixmatch()} aka @code{match()} only checks if the RE matches at the
beginning of the string while @code{search()} scans forward through the
string for a match.

@example
>>> print(re.prefixmatch('super', 'superstition').span())
(0, 5)
>>> print(re.prefixmatch('super', 'insuperable'))
None
@end example

On the other hand, @ref{15d3,,search()} scans forward through the string,
reporting the first match it finds.

@example
>>> print(re.search('super', 'superstition').span())
(0, 5)
>>> print(re.search('super', 'insuperable').span())
(2, 7)
@end example

This distinction is important to remember when using the old @ref{24c,,match()}
name in code requiring compatibility with older Python versions.

@node Greedy versus non-greedy,Using re VERBOSE,prefixmatch aka match versus search,Common problems
@anchor{howto/regex greedy-versus-non-greedy}@anchor{5b62}
@subsubsection Greedy versus non-greedy


When repeating a regular expression, as in @code{a*}, the resulting action is to
consume as much of the pattern as possible.  This fact often bites you when
you’re trying to match a pair of balanced delimiters, such as the angle brackets
surrounding an HTML tag.  The naive pattern for matching a single HTML tag
doesn’t work because of the greedy nature of @code{.*}.

@example
>>> s = '<html><head><title>Title</title>'
>>> len(s)
32
>>> print(re.prefixmatch('<.*>', s).span())
(0, 32)
>>> print(re.prefixmatch('<.*>', s).group())
<html><head><title>Title</title>
@end example

The RE matches the @code{'<'} in @code{'<html>'}, and the @code{.*} consumes the rest of
the string.  There’s still more left in the RE, though, and the @code{>} can’t
match at the end of the string, so the regular expression engine has to
backtrack character by character until it finds a match for the @code{>}.   The
final match extends from the @code{'<'} in @code{'<html>'} to the @code{'>'} in
@code{'</title>'}, which isn’t what you want.

In this case, the solution is to use the non-greedy quantifiers @code{*?}, @code{+?},
@code{??}, or @code{@{m,n@}?}, which match as `little' text as possible.  In the above
example, the @code{'>'} is tried immediately after the first @code{'<'} matches, and
when it fails, the engine advances a character at a time, retrying the @code{'>'}
at every step.  This produces just the right result:

@example
>>> print(re.prefixmatch('<.*?>', s).group())
<html>
@end example

(Note that parsing HTML or XML with regular expressions is painful.
Quick-and-dirty patterns will handle common cases, but HTML and XML have special
cases that will break the obvious regular expression; by the time you’ve written
a regular expression that handles all of the possible cases, the patterns will
be `very' complicated.  Use an HTML or XML parser module for such tasks.)

@node Using re VERBOSE,,Greedy versus non-greedy,Common problems
@anchor{howto/regex using-re-verbose}@anchor{5b63}
@subsubsection Using re.VERBOSE


By now you’ve probably noticed that regular expressions are a very compact
notation, but they’re not terribly readable.  REs of moderate complexity can
become lengthy collections of backslashes, parentheses, and metacharacters,
making them difficult to read and understand.

For such REs, specifying the @ref{298c,,re.VERBOSE} flag when compiling the regular
expression can be helpful, because it allows you to format the regular
expression more clearly.

The @code{re.VERBOSE} flag has several effects.  Whitespace in the regular
expression that `isn’t' inside a character class is ignored.  This means that an
expression such as @code{dog | cat} is equivalent to the less readable @code{dog|cat},
but @code{[a b]} will still match the characters @code{'a'}, @code{'b'}, or a space.  In
addition, you can also put comments inside a RE; comments extend from a @code{#}
character to the next newline.  When used with triple-quoted strings, this
enables REs to be formatted more neatly:

@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

This is far more readable than:

@example
pat = re.compile(r"\s*(?P<header>[^:]+)\s*:(?P<value>.*?)\s*$")
@end example

@node Feedback,,Common problems,Regular expression HOWTO
@anchor{howto/regex feedback}@anchor{5b64}
@subsection Feedback


Regular expressions are a complicated topic.  Did this document help you
understand them?  Were there parts that were unclear, or problems you
encountered that weren’t covered here?  If so, please send suggestions for
improvements to the @ref{758,,issue tracker}.

The most complete book on regular expressions is almost certainly Jeffrey
Friedl’s Mastering Regular Expressions, published by O’Reilly.  Unfortunately,
it exclusively concentrates on Perl and Java’s flavours of regular expressions,
and doesn’t contain any Python material at all, so it won’t be useful as a
reference for programming in Python.  (The first edition covered Python’s
now-removed @code{regex} module, which won’t help you much.)  Consider checking
it out from your library.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Socket Programming HOWTO,Sorting Techniques,Regular expression HOWTO,Python HOWTOs
@anchor{howto/sockets doc}@anchor{5b65}@anchor{howto/sockets socket-howto}@anchor{3bea}@anchor{howto/sockets socket-programming-howto}@anchor{5b66}@anchor{howto/sockets translation-repo}@anchor{5b67}
@section Socket Programming HOWTO


@*Author: 
Gordon McMillan


@subsubheading Abstract



Sockets are used nearly everywhere, but are one of the most severely
misunderstood technologies around. This is a 10,000 foot overview of sockets.
It’s not really a tutorial - you’ll still have work to do in getting things
operational. It doesn’t cover the fine points (and there are a lot of them), but
I hope it will give you enough background to begin using them decently.

@menu
* Sockets:: 
* Creating a Socket:: 
* Using a Socket:: 
* Disconnecting:: 
* Non-blocking Sockets:: 

@end menu

@node Sockets,Creating a Socket,,Socket Programming HOWTO
@anchor{howto/sockets sockets}@anchor{5b68}
@subsection Sockets


I’m only going to talk about INET (i.e. IPv4) sockets, but they account for at least 99% of
the sockets in use. And I’ll only talk about STREAM (i.e. TCP) sockets - unless you really
know what you’re doing (in which case this HOWTO isn’t for you!), you’ll get
better behavior and performance from a STREAM socket than anything else. I will
try to clear up the mystery of what a socket is, as well as some hints on how to
work with blocking and non-blocking sockets. But I’ll start by talking about
blocking sockets. You’ll need to know how they work before dealing with
non-blocking sockets.

Part of the trouble with understanding these things is that «socket» can mean a
number of subtly different things, depending on context. So first, let’s make a
distinction between a «client» socket - an endpoint of a conversation, and a
«server» socket, which is more like a switchboard operator. The client
application (your browser, for example) uses «client» sockets exclusively; the
web server it’s talking to uses both «server» sockets and «client» sockets.

@menu
* History:: 

@end menu

@node History,,,Sockets
@anchor{howto/sockets history}@anchor{5b69}
@subsubsection History


Of the various forms of @abbr{IPC,Inter Process Communication},
sockets are by far the most popular.  On any given platform, there are
likely to be other forms of IPC that are faster, but for
cross-platform communication, sockets are about the only game in town.

They were invented in Berkeley as part of the BSD flavor of Unix. They spread
like wildfire with the internet. With good reason — the combination of sockets
with INET makes talking to arbitrary machines around the world unbelievably easy
(at least compared to other schemes).

@node Creating a Socket,Using a Socket,Sockets,Socket Programming HOWTO
@anchor{howto/sockets creating-a-socket}@anchor{5b6a}
@subsection Creating a Socket


Roughly speaking, when you clicked on the link that brought you to this page,
your browser did something like the following:

@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

When the @code{connect} completes, the socket @code{s} can be used to send
in a request for the text of the page. The same socket will read the
reply, and then be destroyed. That’s right, destroyed. Client sockets
are normally only used for one exchange (or a small set of sequential
exchanges).

What happens in the web server is a bit more complex. First, the web server
creates a «server socket»:

@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

A couple things to notice: we used @code{socket.gethostname()} so that the socket
would be visible to the outside world.  If we had used @code{s.bind(('localhost',
80))} or @code{s.bind(('127.0.0.1', 80))} we would still have a «server» socket,
but one that was only visible within the same machine.  @code{s.bind(('@w{'}, 80))}
specifies that the socket is reachable by any address the machine happens to
have.

A second thing to note: low number ports are usually reserved for «well known»
services (HTTP, SNMP etc). If you’re playing around, use a nice high number (4
digits).

Finally, the argument to @code{listen} tells the socket library that we want it to
queue up as many as 5 connect requests (the normal max) before refusing outside
connections. If the rest of the code is written properly, that should be plenty.

Now that we have a «server» socket, listening on port 80, we can enter the
mainloop of the web server:

@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 = make_client_thread(clientsocket)
    ct.start()
@end example

There’s actually 3 general ways in which this loop could work - dispatching a
thread to handle @code{clientsocket}, create a new process to handle
@code{clientsocket}, or restructure this app to use non-blocking sockets, and
multiplex between our «server» socket and any active @code{clientsocket}s using
@code{select}. More about that later. The important thing to understand now is
this: this is `all' a «server» socket does. It doesn’t send any data. It doesn’t
receive any data. It just produces «client» sockets. Each @code{clientsocket} is
created in response to some `other' «client» socket doing a @code{connect()} to the
host and port we’re bound to. As soon as we’ve created that @code{clientsocket}, we
go back to listening for more connections. The two «clients» are free to chat it
up - they are using some dynamically allocated port which will be recycled when
the conversation ends.

@menu
* IPC:: 

@end menu

@node IPC,,,Creating a Socket
@anchor{howto/sockets ipc}@anchor{5b6b}
@subsubsection IPC


If you need fast IPC between two processes on one machine, you should look into
pipes or shared memory.  If you do decide to use AF_INET sockets, bind the
«server» socket to @code{'localhost'}. On most platforms, this will take a
shortcut around a couple of layers of network code and be quite a bit faster.


@subsubheading Δείτε επίσης


The @ref{98,,multiprocessing} integrates cross-platform IPC into a higher-level
API.


@node Using a Socket,Disconnecting,Creating a Socket,Socket Programming HOWTO
@anchor{howto/sockets using-a-socket}@anchor{5b6c}
@subsection Using a Socket


The first thing to note, is that the web browser’s «client» socket and the web
server’s «client» socket are identical beasts. That is, this is a «peer to peer»
conversation. Or to put it another way, `as the designer, you will have to
decide what the rules of etiquette are for a conversation'. Normally, the
@code{connect}ing socket starts the conversation, by sending in a request, or
perhaps a signon. But that’s a design decision - it’s not a rule of sockets.

Now there are two sets of verbs to use for communication. You can use @code{send}
and @code{recv}, or you can transform your client socket into a file-like beast and
use @code{read} and @code{write}. The latter is the way Java presents its sockets.
I’m not going to talk about it here, except to warn you that you need to use
@code{flush} on sockets. These are buffered «files», and a common mistake is to
@code{write} something, and then @code{read} for a reply. Without a @code{flush} in
there, you may wait forever for the reply, because the request may still be in
your output buffer.

Now we come to the major stumbling block of sockets - @code{send} and @code{recv} operate
on the network buffers. They do not necessarily handle all the bytes you hand
them (or expect from them), because their major focus is handling the network
buffers. In general, they return when the associated network buffers have been
filled (@code{send}) or emptied (@code{recv}). They then tell you how many bytes they
handled. It is `your' responsibility to call them again until your message has
been completely dealt with.

When a @code{recv} returns 0 bytes, it means the other side has closed (or is in
the process of closing) the connection.  You will not receive any more data on
this connection. Ever.  You may be able to send data successfully; I’ll talk
more about this later.

A protocol like HTTP uses a socket for only one transfer. The client sends a
request, then reads a reply.  That’s it. The socket is discarded. This means that
a client can detect the end of the reply by receiving 0 bytes.

But if you plan to reuse your socket for further transfers, you need to realize
that `there is no' @abbr{EOT,End of Transfer} `on a socket.' I repeat: if a socket
@code{send} or @code{recv} returns after handling 0 bytes, the connection has been
broken.  If the connection has `not' been broken, you may wait on a @code{recv}
forever, because the socket will `not' tell you that there’s nothing more to
read (for now).  Now if you think about that a bit, you’ll come to realize a
fundamental truth of sockets: `messages must either be fixed length' (yuck), `or
be delimited' (shrug), `or indicate how long they are' (much better), `or end by
shutting down the connection'. The choice is entirely yours, (but some ways are
righter than others).

Assuming you don’t want to end the connection, the simplest solution is a fixed
length message:

@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

The sending code here is usable for almost any messaging scheme - in Python you
send strings, and you can use @code{len()} to determine its length (even if it has
embedded @code{\0} characters). It’s mostly the receiving code that gets more
complex. (And in C, it’s not much worse, except you can’t use @code{strlen} if the
message has embedded @code{\0}s.)

The easiest enhancement is to make the first character of the message an
indicator of message type, and have the type determine the length. Now you have
two @code{recv}s - the first to get (at least) that first character so you can
look up the length, and the second in a loop to get the rest. If you decide to
go the delimited route, you’ll be receiving in some arbitrary chunk size, (4096
or 8192 is frequently a good match for network buffer sizes), and scanning what
you’ve received for a delimiter.

One complication to be aware of: if your conversational protocol allows multiple
messages to be sent back to back (without some kind of reply), and you pass
@code{recv} an arbitrary chunk size, you may end up reading the start of a
following message. You’ll need to put that aside and hold onto it, until it’s
needed.

Prefixing the message with its length (say, as 5 numeric characters) gets more
complex, because (believe it or not), you may not get all 5 characters in one
@code{recv}. In playing around, you’ll get away with it; but in high network loads,
your code will very quickly break unless you use two @code{recv} loops - the first
to determine the length, the second to get the data part of the message. Nasty.
This is also when you’ll discover that @code{send} does not always manage to get
rid of everything in one pass. And despite having read this, you will eventually
get bit by it!

In the interests of space, building your character, (and preserving my
competitive position), these enhancements are left as an exercise for the
reader. Lets move on to cleaning up.

@menu
* Binary Data:: 

@end menu

@node Binary Data,,,Using a Socket
@anchor{howto/sockets binary-data}@anchor{5b6d}
@subsubsection Binary Data


It is perfectly possible to send binary data over a socket. The major problem is
that not all machines use the same formats for binary data. For example,
network byte order@footnote{https://en.wikipedia.org/wiki/Endianness#Networking}
is big-endian, with the most significant byte first,
so a 16 bit integer with the value @code{1} would be the two hex bytes @code{00 01}.
However, most common processors (x86/AMD64, ARM, RISC-V), are little-endian,
with the least significant byte first - that same @code{1} would be @code{01 00}.

Socket libraries have calls for converting 16 and 32 bit integers - @code{ntohl,
htonl, ntohs, htons} where «n» means `network' and «h» means `host', «s» means
`short' and «l» means `long'. Where network order is host order, these do
nothing, but where the machine is byte-reversed, these swap the bytes around
appropriately.

In these days of 64-bit machines, the ASCII representation of binary data is
frequently smaller than the binary representation. That’s because a surprising
amount of the time, most integers have the value 0, or maybe 1.
The string @code{"0"} would be two bytes, while a full 64-bit integer would be 8.
Of course, this doesn’t fit well with fixed-length messages.
Decisions, decisions.

@node Disconnecting,Non-blocking Sockets,Using a Socket,Socket Programming HOWTO
@anchor{howto/sockets disconnecting}@anchor{5b6e}
@subsection Disconnecting


Strictly speaking, you’re supposed to use @code{shutdown} on a socket before you
@code{close} it.  The @code{shutdown} is an advisory to the socket at the other end.
Depending on the argument you pass it, it can mean «I’m not going to send
anymore, but I’ll still listen», or «I’m not listening, good riddance!».  Most
socket libraries, however, are so used to programmers neglecting to use this
piece of etiquette that normally a @code{close} is the same as @code{shutdown();
close()}.  So in most situations, an explicit @code{shutdown} is not needed.

One way to use @code{shutdown} effectively is in an HTTP-like exchange. The client
sends a request and then does a @code{shutdown(1)}. This tells the server «This
client is done sending, but can still receive.»  The server can detect «EOF» by
a receive of 0 bytes. It can assume it has the complete request.  The server
sends a reply. If the @code{send} completes successfully then, indeed, the client
was still receiving.

Python takes the automatic shutdown a step further, and says that when a socket
is garbage collected, it will automatically do a @code{close} if it’s needed. But
relying on this is a very bad habit. If your socket just disappears without
doing a @code{close}, the socket at the other end may hang indefinitely, thinking
you’re just being slow. `Please' @code{close} your sockets when you’re done.

@menu
* When Sockets Die:: 

@end menu

@node When Sockets Die,,,Disconnecting
@anchor{howto/sockets when-sockets-die}@anchor{5b6f}
@subsubsection When Sockets Die


Probably the worst thing about using blocking sockets is what happens when the
other side comes down hard (without doing a @code{close}). Your socket is likely to
hang. TCP is a reliable protocol, and it will wait a long, long time
before giving up on a connection. If you’re using threads, the entire thread is
essentially dead. There’s not much you can do about it. As long as you aren’t
doing something dumb, like holding a lock while doing a blocking read, the
thread isn’t really consuming much in the way of resources. Do `not' try to kill
the thread - part of the reason that threads are more efficient than processes
is that they avoid the overhead associated with the automatic recycling of
resources. In other words, if you do manage to kill the thread, your whole
process is likely to be screwed up.

@node Non-blocking Sockets,,Disconnecting,Socket Programming HOWTO
@anchor{howto/sockets non-blocking-sockets}@anchor{5b70}
@subsection Non-blocking Sockets


If you’ve understood the preceding, you already know most of what you need to
know about the mechanics of using sockets. You’ll still use the same calls, in
much the same ways. It’s just that, if you do it right, your app will be almost
inside-out.

In Python, you use @code{socket.setblocking(False)} to make it non-blocking. In C, it’s
more complex, (for one thing, you’ll need to choose between the BSD flavor
@code{O_NONBLOCK} and the almost indistinguishable POSIX flavor @code{O_NDELAY}, which
is completely different from @code{TCP_NODELAY}), but it’s the exact same idea. You
do this after creating the socket, but before using it. (Actually, if you’re
nuts, you can switch back and forth.)

The major mechanical difference is that @code{send}, @code{recv}, @code{connect} and
@code{accept} can return without having done anything. You have (of course) a
number of choices. You can check return code and error codes and generally drive
yourself crazy. If you don’t believe me, try it sometime. Your app will grow
large, buggy and suck CPU. So let’s skip the brain-dead solutions and do it
right.

Use @code{select}.

In C, coding @code{select} is fairly complex. In Python, it’s a piece of cake, but
it’s close enough to the C version that if you understand @code{select} in Python,
you’ll have little trouble with it in C:

@example
ready_to_read, ready_to_write, in_error = \
               select.select(
                  potential_readers,
                  potential_writers,
                  potential_errs,
                  timeout)
@end example

You pass @code{select} three lists: the first contains all sockets that you might
want to try reading; the second all the sockets you might want to try writing
to, and the last (normally left empty) those that you want to check for errors.
You should note that a socket can go into more than one list. The @code{select}
call is blocking, but you can give it a timeout. This is generally a sensible
thing to do - give it a nice long timeout (say a minute) unless you have good
reason to do otherwise.

In return, you will get three lists. They contain the sockets that are actually
readable, writable and in error. Each of these lists is a subset (possibly
empty) of the corresponding list you passed in.

If a socket is in the output readable list, you can be
as-close-to-certain-as-we-ever-get-in-this-business that a @code{recv} on that
socket will return `something'. Same idea for the writable list. You’ll be able
to send `something'. Maybe not all you want to, but `something' is better than
nothing.  (Actually, any reasonably healthy socket will return as writable - it
just means outbound network buffer space is available.)

If you have a «server» socket, put it in the potential_readers list. If it comes
out in the readable list, your @code{accept} will (almost certainly) work. If you
have created a new socket to @code{connect} to someone else, put it in the
potential_writers list. If it shows up in the writable list, you have a decent
chance that it has connected.

Actually, @code{select} can be handy even with blocking sockets. It’s one way of
determining whether you will block - the socket returns as readable when there’s
something in the buffers.  However, this still doesn’t help with the problem of
determining whether the other end is done, or just busy with something else.

`Portability alert': On Unix, @code{select} works both with the sockets and
files. Don’t try this on Windows. On Windows, @code{select} works with sockets
only. Also note that in C, many of the more advanced socket options are done
differently on Windows. In fact, on Windows I usually use threads (which work
very, very well) with my sockets.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Sorting Techniques,Unicode HOWTO,Socket Programming HOWTO,Python HOWTOs
@anchor{howto/sorting doc}@anchor{5b71}@anchor{howto/sorting sorting-techniques}@anchor{5b72}@anchor{howto/sorting sortinghowto}@anchor{27d9}@anchor{howto/sorting translation-repo}@anchor{5b73}
@section Sorting Techniques


@*Author: 
Andrew Dalke and Raymond Hettinger


Python lists have a built-in @ref{f8d,,list.sort()} method that modifies the list
in-place.  There is also a @ref{f8c,,sorted()} built-in function that builds a new
sorted list from an iterable.

In this document, we explore the various techniques for sorting data using Python.

@menu
* Sorting Basics:: 
* Key Functions:: 
* Operator Module Functions and Partial Function Evaluation:: 
* Ascending and Descending:: 
* Sort Stability and Complex Sorts:: 
* Decorate-Sort-Undecorate:: 
* Comparison Functions:: 
* Strategies For Unorderable Types and Values:: 
* Odds and Ends:: 
* Partial Sorts:: 

@end menu

@node Sorting Basics,Key Functions,,Sorting Techniques
@anchor{howto/sorting sorting-basics}@anchor{5b74}
@subsection Sorting Basics


A simple ascending sort is very easy: just call the @ref{f8c,,sorted()} function. It
returns a new sorted list:

@example
>>> sorted([5, 2, 3, 1, 4])
[1, 2, 3, 4, 5]
@end example

You can also use the @ref{f8d,,list.sort()} method. It modifies the list
in-place (and returns @code{None} to avoid confusion). Usually it’s less convenient
than @ref{f8c,,sorted()} - but if you don’t need the original list, it’s slightly
more efficient.

@example
>>> a = [5, 2, 3, 1, 4]
>>> a.sort()
>>> a
[1, 2, 3, 4, 5]
@end example

Another difference is that the @ref{f8d,,list.sort()} method is only defined for
lists. In contrast, the @ref{f8c,,sorted()} function accepts any iterable.

@example
>>> sorted(@{1: 'D', 2: 'B', 3: 'B', 4: 'E', 5: 'A'@})
[1, 2, 3, 4, 5]
@end example

@node Key Functions,Operator Module Functions and Partial Function Evaluation,Sorting Basics,Sorting Techniques
@anchor{howto/sorting key-functions}@anchor{5b75}
@subsection Key Functions


The @ref{f8d,,list.sort()} method and the functions @ref{f8c,,sorted()},
@ref{12b9,,min()}, @ref{12ba,,max()}, @ref{2bb9,,heapq.nsmallest()}, and
@ref{2bb8,,heapq.nlargest()} have a `key' parameter to specify a function (or
other callable) to be called on each list element prior to making
comparisons.

For example, here’s a case-insensitive string comparison using
@ref{118f,,str.casefold()}:

@example
>>> sorted("This is a test string from Andrew".split(), key=str.casefold)
['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']
@end example

The value of the `key' parameter should be a function (or other callable) that
takes a single argument and returns a key to use for sorting purposes. This
technique is fast because the key function is called exactly once for each
input record.

A common pattern is to sort complex objects using some of the object’s indices
as keys. For example:

@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

The same technique works for objects with named attributes. For example:

@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{6e6,,dataclass} or
a @ref{a3d,,named tuple}.

@node Operator Module Functions and Partial Function Evaluation,Ascending and Descending,Key Functions,Sorting Techniques
@anchor{howto/sorting operator-module-functions-and-partial-function-evaluation}@anchor{5b76}
@subsection Operator Module Functions and Partial Function Evaluation


The @ref{11ba,,key function} patterns shown above are very common, so Python provides
convenience functions to make accessor functions easier and faster. The
@ref{a3,,operator} module has @ref{e26,,itemgetter()},
@ref{11e6,,attrgetter()}, and a @ref{11e7,,methodcaller()} function.

Using those functions, the above examples become simpler and faster:

@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

The operator module functions allow multiple levels of sorting. For example, to
sort by `grade' then by `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{62,,functools} module provides another helpful tool for making
key-functions.  The @ref{4a6,,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 Ascending and Descending,Sort Stability and Complex Sorts,Operator Module Functions and Partial Function Evaluation,Sorting Techniques
@anchor{howto/sorting ascending-and-descending}@anchor{5b77}
@subsection Ascending and Descending


Both @ref{f8d,,list.sort()} and @ref{f8c,,sorted()} accept a `reverse' parameter with a
boolean value. This is used to flag descending sorts. For example, to get the
student data in reverse `age' order:

@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 Sort Stability and Complex Sorts,Decorate-Sort-Undecorate,Ascending and Descending,Sorting Techniques
@anchor{howto/sorting sort-stability-and-complex-sorts}@anchor{5b78}
@subsection Sort Stability and Complex Sorts


Sorts are guaranteed to be stable@footnote{https://en.wikipedia.org/wiki/Sorting_algorithm#Stability}. That means that
when multiple records have the same key, their original order is preserved.

@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

Notice how the two records for `blue' retain their original order so that
@code{('blue', 1)} is guaranteed to precede @code{('blue', 2)}.

This wonderful property lets you build complex sorts in a series of sorting
steps. For example, to sort the student data by descending `grade' and then
ascending `age', do the `age' sort first and then sort again using `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

This can be abstracted out into a wrapper function that can take a list and
tuples of field and order to sort them on multiple 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

The Timsort@footnote{https://en.wikipedia.org/wiki/Timsort} algorithm used in Python
does multiple sorts efficiently because it can take advantage of any ordering
already present in a dataset.

@node Decorate-Sort-Undecorate,Comparison Functions,Sort Stability and Complex Sorts,Sorting Techniques
@anchor{howto/sorting decorate-sort-undecorate}@anchor{5b79}
@subsection Decorate-Sort-Undecorate


This idiom is called Decorate-Sort-Undecorate after its three steps:


@itemize *

@item 
First, the initial list is decorated with new values that control the sort order.

@item 
Second, the decorated list is sorted.

@item 
Finally, the decorations are removed, creating a list that contains only the
initial values in the new order.
@end itemize

For example, to sort the student data by `grade' using the DSU approach:

@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

This idiom works because tuples are compared lexicographically; the first items
are compared; if they are the same then the second items are compared, and so
on.

It is not strictly necessary in all cases to include the index `i' in the
decorated list, but including it gives two benefits:


@itemize *

@item 
The sort is stable – if two items have the same key, their order will be
preserved in the sorted list.

@item 
The original items do not have to be comparable because the ordering of the
decorated tuples will be determined by at most the first two items. So for
example the original list could contain complex numbers which cannot be sorted
directly.
@end itemize

Another name for this idiom is
Schwartzian transform@footnote{https://en.wikipedia.org/wiki/Schwartzian_transform},
after Randal L. Schwartz, who popularized it among Perl programmers.

Now that Python sorting provides key-functions, this technique is not often needed.

@node Comparison Functions,Strategies For Unorderable Types and Values,Decorate-Sort-Undecorate,Sorting Techniques
@anchor{howto/sorting comparison-functions}@anchor{5b7a}
@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{4518,,locale.strcoll()} is a comparison function.

To accommodate those situations, Python provides
@ref{1583,,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 Strategies For Unorderable Types and Values,Odds and Ends,Comparison Functions,Sorting Techniques
@anchor{howto/sorting strategies-for-unorderable-types-and-values}@anchor{5b7b}
@subsection Strategies For Unorderable Types and Values


A number of type and value issues can arise when sorting.
Here are some strategies that can help:


@itemize *

@item 
Convert non-comparable input types to strings prior to sorting:
@end itemize

@example
>>> data = ['twelve', '11', 10]
>>> sorted(map(str, data))
['10', '11', 'twelve']
@end example

This is needed because most cross-type comparisons raise a
@ref{291,,TypeError}.


@itemize *

@item 
Remove special values prior to sorting:
@end itemize

@example
>>> from math import isnan
>>> from itertools import filterfalse
>>> data = [3.3, float('nan'), 1.1, 2.2]
>>> sorted(filterfalse(isnan, data))
[1.1, 2.2, 3.3]
@end example

This is needed because the IEEE-754 standard@footnote{https://en.wikipedia.org/wiki/IEEE_754} specifies that, «Every NaN
shall compare unordered with everything, including itself.»

Likewise, @code{None} can be stripped from datasets as well:

@example
>>> data = [3.3, None, 1.1, 2.2]
>>> sorted(x for x in data if x is not None)
[1.1, 2.2, 3.3]
@end example

This is needed because @code{None} is not comparable to other types.


@itemize *

@item 
Convert mapping types into sorted item lists before sorting:
@end itemize

@example
>>> data = [@{'a': 1@}, @{'b': 2@}]
>>> sorted(data, key=lambda d: sorted(d.items()))
[@{'a': 1@}, @{'b': 2@}]
@end example

This is needed because dict-to-dict comparisons raise a
@ref{291,,TypeError}.


@itemize *

@item 
Convert set types into sorted lists before sorting:
@end itemize

@example
>>> data = [@{'a', 'b', 'c'@}, @{'b', 'c', 'd'@}]
>>> sorted(map(sorted, data))
[['a', 'b', 'c'], ['b', 'c', 'd']]
@end example

This is needed because the elements contained in set types do not have a
deterministic order.  For example, @code{list(@{'a', 'b'@})} may produce
either @code{['a', 'b']} or @code{['b', 'a']}.

@node Odds and Ends,Partial Sorts,Strategies For Unorderable Types and Values,Sorting Techniques
@anchor{howto/sorting odds-and-ends}@anchor{5b7c}
@subsection Odds and Ends



@itemize *

@item 
For locale aware sorting, use @ref{19f7,,locale.strxfrm()} for a key function or
@ref{4518,,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 
The `reverse' parameter still maintains sort stability (so that records with
equal keys retain the original order). Interestingly, that effect can be
simulated without the parameter by using the builtin @ref{c3c,,reversed()} function
twice:

@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{1645,,__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{16b0,,__gt__()} if
@ref{1645,,__lt__()} is not implemented (see @ref{1645,,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{12ed,,total_ordering()} decorator is provided to make that
task easier.

@item 
Key functions need not depend directly on the objects being sorted. A key
function can also access external resources. For instance, if the student grades
are stored in a dictionary, they can be used to sort a separate list of student
names:

@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,,Odds and Ends,Sorting Techniques
@anchor{howto/sorting partial-sorts}@anchor{5b7d}
@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{12b9,,min()} and @ref{12ba,,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{2bb9,,heapq.nsmallest()} and @ref{2bb8,,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{185e,,heapq.heappush()} and @ref{185f,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Unicode HOWTO,HOWTO Fetch Internet Resources Using The urllib Package,Sorting Techniques,Python HOWTOs
@anchor{howto/unicode doc}@anchor{5b7e}@anchor{howto/unicode id1}@anchor{5b7f}@anchor{howto/unicode translation-repo}@anchor{5b80}@anchor{howto/unicode unicode-howto}@anchor{1649}
@section Unicode HOWTO


@*Release: 
1.12


This HOWTO discusses Python’s support for the Unicode specification
for representing textual data, and explains various problems that
people commonly encounter when trying to work with Unicode.

@menu
* Introduction to Unicode:: 
* Python’s Unicode Support:: 
* Reading and Writing Unicode Data:: 
* Acknowledgements: Acknowledgements<10>. 

@end menu

@node Introduction to Unicode,Python’s Unicode Support,,Unicode HOWTO
@anchor{howto/unicode introduction-to-unicode}@anchor{5b81}
@subsection Introduction to Unicode


@menu
* Definitions:: 
* Encodings:: 
* References: References<2>. 

@end menu

@node Definitions,Encodings,,Introduction to Unicode
@anchor{howto/unicode definitions}@anchor{5b82}
@subsubsection Definitions


Today’s programs need to be able to handle a wide variety of
characters.  Applications are often internationalized to display
messages and output in a variety of user-selectable languages; the
same program might need to output an error message in English, French,
Japanese, Hebrew, or Russian.  Web content can be written in any of
these languages and can also include a variety of emoji symbols.
Python’s string type uses the Unicode Standard for representing
characters, which lets Python programs work with all these different
possible characters.

Unicode (@indicateurl{https://www.unicode.org/}) is a specification that aims to
list every character used by human languages and give each character
its own unique code.  The Unicode specifications are continually
revised and updated to add new languages and symbols.

A `character' is the smallest possible component of a text.  “A”, “B”, “C”,
etc., are all different characters.  So are “È” and “Í”.  Characters vary
depending on the language or context you’re talking
about.  For example, there’s a character for «Roman Numeral One», “Ⅰ”, that’s
separate from the uppercase letter “I”.  They’ll usually look the same,
but these are two different characters that have different meanings.

The Unicode standard describes how characters are represented by
`code points'.  A code point value is an integer in the range 0 to
0x10FFFF (about 1.1 million values, the
actual number assigned@footnote{https://www.unicode.org/versions/latest/#Summary}
is less than that). In the standard and in this document, a code point is written
using the notation @code{U+265E} to mean the character with value
@code{0x265e} (9,822 in decimal).

The Unicode standard contains a lot of tables listing characters and
their corresponding code points:

@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

Strictly, these definitions imply that it’s meaningless to say “this is
character @code{U+265E}”.  @code{U+265E} is a code point, which represents some particular
character; in this case, it represents the character “BLACK CHESS KNIGHT”,
“♞”.  In
informal contexts, this distinction between code points and characters will
sometimes be forgotten.

A character is represented on a screen or on paper by a set of graphical
elements that’s called a `glyph'.  The glyph for an uppercase A, for example,
is two diagonal strokes and a horizontal stroke, though the exact details will
depend on the font being used.  Most Python code doesn’t need to worry about
glyphs; figuring out the correct glyph to display is generally the job of a GUI
toolkit or a terminal’s font renderer.

@node Encodings,References<2>,Definitions,Introduction to Unicode
@anchor{howto/unicode encodings}@anchor{5b83}
@subsubsection Encodings


To summarize the previous section: a Unicode string is a sequence of
code points, which are numbers from 0 through @code{0x10FFFF} (1,114,111
decimal).  This sequence of code points needs to be represented in
memory as a set of `code units', and `code units' are then mapped
to 8-bit bytes.  The rules for translating a Unicode string into a
sequence of bytes are called a `character encoding', or just
an `encoding'.

The first encoding you might think of is using 32-bit integers as the
code unit, and then using the CPU’s representation of 32-bit integers.
In this representation, the string «Python» might look like this:

@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

This representation is straightforward but using it presents a number of
problems.


@enumerate 

@item 
It’s not portable; different processors order the bytes differently.

@item 
It’s very wasteful of space.  In most texts, the majority of the code points
are less than 127, or less than 255, so a lot of space is occupied by @code{0x00}
bytes.  The above string takes 24 bytes compared to the 6 bytes needed for an
ASCII representation.  Increased RAM usage doesn’t matter too much (desktop
computers have gigabytes of RAM, and strings aren’t usually that large), but
expanding our usage of disk and network bandwidth by a factor of 4 is
intolerable.

@item 
It’s not compatible with existing C functions such as @code{strlen()}, so a new
family of wide string functions would need to be used.
@end enumerate

Therefore this encoding isn’t used very much, and people instead choose other
encodings that are more efficient and convenient, such as UTF-8.

UTF-8 is one of the most commonly used encodings, and Python often
defaults to using it.  UTF stands for «Unicode Transformation Format»,
and the “8” means that 8-bit values are used in the encoding.  (There
are also UTF-16 and UTF-32 encodings, but they are less frequently
used than UTF-8.)  UTF-8 uses the following rules:


@enumerate 

@item 
If the code point is < 128, it’s represented by the corresponding byte value.

@item 
If the code point is >= 128, it’s turned into a sequence of two, three, or
four bytes, where each byte of the sequence is between 128 and 255.
@end enumerate

UTF-8 has several convenient properties:


@enumerate 

@item 
It can handle any Unicode code point.

@item 
A Unicode string is turned into a sequence of bytes that contains embedded
zero bytes only where they represent the null character (U+0000). This means
that UTF-8 strings can be processed by C functions such as @code{strcpy()} and sent
through protocols that can’t handle zero bytes for anything other than
end-of-string markers.

@item 
A string of ASCII text is also valid UTF-8 text.

@item 
UTF-8 is fairly compact; the majority of commonly used characters can be
represented with one or two bytes.

@item 
If bytes are corrupted or lost, it’s possible to determine the start of the
next UTF-8-encoded code point and resynchronize.  It’s also unlikely that
random 8-bit data will look like valid UTF-8.

@item 
UTF-8 is a byte oriented encoding. The encoding specifies that each
character is represented by a specific sequence of one or more bytes. This
avoids the byte-ordering issues that can occur with integer and word oriented
encodings, like UTF-16 and UTF-32, where the sequence of bytes varies depending
on the hardware on which the string was encoded.
@end enumerate

@node References<2>,,Encodings,Introduction to Unicode
@anchor{howto/unicode references}@anchor{5b84}
@subsubsection References


The Unicode Consortium site@footnote{https://www.unicode.org} has character charts, a
glossary, and PDF versions of the Unicode specification.  Be prepared for some
difficult reading.  A chronology@footnote{https://www.unicode.org/history/} of the
origin and development of Unicode is also available on the site.

On the Computerphile Youtube channel, Tom Scott briefly
discusses the history of Unicode and UTF-8@footnote{https://www.youtube.com/watch?v=MijmeoH9LT4}
(9 minutes 36 seconds).

To help understand the standard, Jukka Korpela has written an introductory guide@footnote{https://jkorpela.fi/unicode/guide.html} to reading the
Unicode character tables.

Another good introductory article@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/}
was written by Joel Spolsky.
If this introduction didn’t make things clear to you, you should try
reading this alternate article before continuing.

Wikipedia entries are often helpful; see the entries for «character encoding@footnote{https://en.wikipedia.org/wiki/Character_encoding}» and UTF-8@footnote{https://en.wikipedia.org/wiki/UTF-8}, for example.

@node Python’s Unicode Support,Reading and Writing Unicode Data,Introduction to Unicode,Unicode HOWTO
@anchor{howto/unicode python-s-unicode-support}@anchor{5b85}
@subsection Python’s Unicode Support


Now that you’ve learned the rudiments of Unicode, we can look at Python’s
Unicode features.

@menu
* The String Type:: 
* Converting to Bytes:: 
* Unicode Literals in Python Source Code:: 
* Unicode Properties:: 
* Comparing Strings:: 
* Unicode Regular Expressions:: 
* References: References<3>. 

@end menu

@node The String Type,Converting to Bytes,,Python’s Unicode Support
@anchor{howto/unicode the-string-type}@anchor{5b86}
@subsubsection The String Type


Since Python 3.0, the language’s @ref{1df,,str} type contains Unicode
characters, meaning any string created using @code{"unicode rocks!"}, @code{'unicode
rocks!'}, or the triple-quoted string syntax is stored as Unicode.

The default encoding for Python source code is UTF-8, so you can simply
include a Unicode character in a string literal:

@example
try:
    with open('/tmp/input.txt', 'r') as f:
        ...
except OSError:
    # 'File not found' error message.
    print("Fichier non trouvé")
@end example

Side note: Python 3 also supports using Unicode characters in identifiers:

@example
répertoire = "/tmp/records.log"
with open(répertoire, "w") as f:
    f.write("test\n")
@end example

If you can’t enter a particular character in your editor or want to
keep the source code ASCII-only for some reason, you can also use
escape sequences in string literals. (Depending on your system,
you may see the actual capital-delta glyph instead of a u escape.)

@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

In addition, one can create a string using the @ref{ca8,,decode()} method of
@ref{1c7,,bytes}.  This method takes an `encoding' argument, such as @code{UTF-8},
and optionally an `errors' argument.

The `errors' argument specifies the response when the input string can’t be
converted according to the encoding’s rules.  Legal values for this argument are
@code{'strict'} (raise a @ref{dd7,,UnicodeDecodeError} exception), @code{'replace'} (use
@code{U+FFFD}, @code{REPLACEMENT CHARACTER}), @code{'ignore'} (just leave the
character out of the Unicode result), or @code{'backslashreplace'} (inserts a
@code{\xNN} escape sequence).
The following examples show the differences:

@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

Encodings are specified as strings containing the encoding’s name.  Python
comes with roughly 100 different encodings; see the Python Library Reference at
@ref{1171,,Standard Encodings} for a list.  Some encodings have multiple names; for
example, @code{'latin-1'}, @code{'iso_8859_1'} and @code{'8859}” are all synonyms for
the same encoding.

One-character Unicode strings can also be created with the @ref{1bf8,,chr()}
built-in function, which takes integers and returns a Unicode string of length 1
that contains the corresponding code point.  The reverse operation is the
built-in @ref{252c,,ord()} function that takes a one-character Unicode string and
returns the code point value:

@example
>>> chr(57344)
'\ue000'
>>> ord('\ue000')
57344
@end example

@node Converting to Bytes,Unicode Literals in Python Source Code,The String Type,Python’s Unicode Support
@anchor{howto/unicode converting-to-bytes}@anchor{5b87}
@subsubsection Converting to Bytes


The opposite method of @ref{ca8,,bytes.decode()} is @ref{ca7,,str.encode()},
which returns a @ref{1c7,,bytes} representation of the Unicode string, encoded in the
requested `encoding'.

The `errors' parameter is the same as the parameter of the
@ref{ca8,,decode()} method but supports a few more possible handlers. As well as
@code{'strict'}, @code{'ignore'}, and @code{'replace'} (which in this case
inserts a question mark instead of the unencodable character), there is
also @code{'xmlcharrefreplace'} (inserts an XML character reference),
@code{backslashreplace} (inserts a @code{\uNNNN} escape sequence) and
@code{namereplace} (inserts a @code{\N@{...@}} escape sequence).

The following example shows the different results:

@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

The low-level routines for registering and accessing the available
encodings are found in the @ref{1c,,codecs} module.  Implementing new
encodings also requires understanding the @code{codecs} module.
However, the encoding and decoding functions returned by this module
are usually more low-level than is comfortable, and writing new encodings
is a specialized task, so the module won’t be covered in this HOWTO.

@node Unicode Literals in Python Source Code,Unicode Properties,Converting to Bytes,Python’s Unicode Support
@anchor{howto/unicode unicode-literals-in-python-source-code}@anchor{5b88}
@subsubsection Unicode Literals in Python Source Code


In Python source code, specific Unicode code points can be written using the
@code{\u} escape sequence, which is followed by four hex digits giving the code
point.  The @code{\U} escape sequence is similar, but expects eight hex digits,
not four:

@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

Using escape sequences for code points greater than 127 is fine in small doses,
but becomes an annoyance if you’re using many accented characters, as you would
in a program with messages in French or some other accent-using language.  You
can also assemble strings using the @ref{1bf8,,chr()} built-in function, but this is
even more tedious.

Ideally, you’d want to be able to write literals in your language’s natural
encoding.  You could then edit Python source code with your favorite editor
which would display the accented characters naturally, and have the right
characters used at runtime.

Python supports writing source code in UTF-8 by default, but you can use almost
any encoding if you declare the encoding being used.  This is done by including
a special comment as either the first or second line of the source file:

@example
#!/usr/bin/env python
# -*- coding: latin-1 -*-

u = 'abcdé'
print(ord(u[-1]))
@end example

The syntax is inspired by Emacs’s notation for specifying variables local to a
file.  Emacs supports many different variables, but Python only supports
“coding”.  The @code{-*-} symbols indicate to Emacs that the comment is special;
they have no significance to Python but are a convention.  Python looks for
@code{coding: name} or @code{coding=name} in the comment.

If you don’t include such a comment, the default encoding used will be UTF-8 as
already mentioned.  See also 
@geindex Python Enhancement Proposals; PEP 263
PEP 263@footnote{https://peps.python.org/pep-0263/} for more information.

@node Unicode Properties,Comparing Strings,Unicode Literals in Python Source Code,Python’s Unicode Support
@anchor{howto/unicode id2}@anchor{5b89}@anchor{howto/unicode unicode-properties}@anchor{2845}
@subsubsection Unicode Properties


The Unicode specification includes a database of information about
code points.  For each defined code point, the information includes
the character’s name, its category, the numeric value if applicable
(for characters representing numeric concepts such as the Roman
numerals, fractions such as one-third and four-fifths, etc.).  There
are also display-related properties, such as how to use the code point
in bidirectional text.

The following program displays some information about several characters, and
prints the numeric value of one particular character:

@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

When run, this prints:

@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

The category codes are abbreviations describing the nature of the character.
These are grouped into categories such as «Letter», «Number», «Punctuation», or
«Symbol», which in turn are broken up into subcategories.  To take the codes
from the above output, @code{'Ll'} means “Letter, lowercase”, @code{'No'} means
«Number, other», @code{'Mn'} is «Mark, nonspacing», and @code{'So'} is «Symbol,
other».  See
the General Category Values section of the Unicode Character Database documentation@footnote{https://www.unicode.org/reports/tr44/#General_Category_Values} for a
list of category codes.

@node Comparing Strings,Unicode Regular Expressions,Unicode Properties,Python’s Unicode Support
@anchor{howto/unicode comparing-strings}@anchor{5b8a}
@subsubsection Comparing Strings


Unicode adds some complication to comparing strings, because the same
set of characters can be represented by different sequences of code
points.  For example, a letter like “ê” can be represented as a single
code point U+00EA, or as U+0065 U+0302, which is the code point for
“e” followed by a code point for “COMBINING CIRCUMFLEX ACCENT”.  These
will produce the same output when printed, but one is a string of
length 1 and the other is of length 2.

One tool for a case-insensitive comparison is the
@ref{118f,,casefold()} string method that converts a string to a
case-insensitive form following an algorithm described by the Unicode
Standard.  This algorithm has special handling for characters such as
the German letter “ß” (code point U+00DF), which becomes the pair of
lowercase letters “ss”.

@example
>>> street = 'Gürzenichstraße'
>>> street.casefold()
'gürzenichstrasse'
@end example

A second tool is the @ref{10e,,unicodedata} module’s
@ref{ac2,,normalize()} function that converts strings to one
of several normal forms, where letters followed by a combining character are
replaced with single characters.  @code{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

When run, this outputs:

@example
$ python compare-strs.py
length of first string= 1
length of second string= 2
True
@end example

The first argument to the @ref{ac2,,normalize()} function is a
string giving the desired normalization form, which can be one of
“NFC”, “NFKC”, “NFD”, and “NFKD”.

The Unicode Standard also specifies how to do caseless comparisons:

@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{118f,,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 Unicode Regular Expressions,References<3>,Comparing Strings,Python’s Unicode Support
@anchor{howto/unicode unicode-regular-expressions}@anchor{5b8b}
@subsubsection Unicode Regular Expressions


The regular expressions supported by the @ref{c1,,re} module can be provided
either as bytes or strings.  Some of the special character sequences such as
@code{\d} and @code{\w} have different meanings depending on whether
the pattern is supplied as bytes or a string.  For example,
@code{\d} will match the characters @code{[0-9]} in bytes but
in strings will match any character that’s in the @code{'Nd'} category.

The string in this example has the number 57 written in both Thai and
Arabic numerals:

@example
import re
p = re.compile(r'\d+')

s = "Over \u0e55\u0e57 57 flavours"
m = p.search(s)
print(repr(m.group()))
@end example

When executed, @code{\d+} will match the Thai numerals and print them
out.  If you supply the @ref{a1d,,re.ASCII} flag to
@ref{f93,,compile()}, @code{\d+} will match the substring «57» instead.

Similarly, @code{\w} matches a wide variety of Unicode characters but
only @code{[a-zA-Z0-9_]} in bytes or if @ref{a1d,,re.ASCII} is supplied,
and @code{\s} will match either Unicode whitespace characters or
@code{[ \t\n\r\f\v]}.

@node References<3>,,Unicode Regular Expressions,Python’s Unicode Support
@anchor{howto/unicode id3}@anchor{5b8c}
@subsubsection References


@c comment should these be mentioned earlier, e.g. at the start of the "introduction to Unicode" first section?

Some good alternative discussions of Python’s Unicode support are:


@itemize *

@item 
Processing Text Files in Python 3@footnote{https://python-notes.curiousefficiency.org/en/latest/python3/text_file_processing.html}, by Nick Coghlan.

@item 
Pragmatic Unicode@footnote{https://nedbatchelder.com/text/unipain.html}, a PyCon 2012 presentation by Ned Batchelder.
@end itemize

The @ref{1df,,str} type is described in the Python library reference at
@ref{21cd,,Τύπος Ακολουθίας (Sequence) Κειμένου — str}.

The documentation for the @ref{10e,,unicodedata} module.

The documentation for the @ref{1c,,codecs} module.

Marc-André Lemburg gave a presentation titled "Python and Unicode" (PDF slides)@footnote{https://downloads.egenix.com/python/Unicode-EPC2002-Talk.pdf} at
EuroPython 2002.  The slides are an excellent overview of the design of Python
2’s Unicode features (where the Unicode string type is called @code{unicode} and
literals start with @code{u}).

@node Reading and Writing Unicode Data,Acknowledgements<10>,Python’s Unicode Support,Unicode HOWTO
@anchor{howto/unicode reading-and-writing-unicode-data}@anchor{5b8d}
@subsection Reading and Writing Unicode Data


Once you’ve written some code that works with Unicode data, the next problem is
input/output.  How do you get Unicode strings into your program, and how do you
convert Unicode into a form suitable for storage or transmission?

It’s possible that you may not need to do anything depending on your input
sources and output destinations; you should check whether the libraries used in
your application support Unicode natively.  XML parsers often return Unicode
data, for example.  Many relational databases also support Unicode-valued
columns and can return Unicode values from an SQL query.

Unicode data is usually converted to a particular encoding before it gets
written to disk or sent over a socket.  It’s possible to do all the work
yourself: open a file, read an 8-bit bytes object from it, and convert the bytes
with @code{bytes.decode(encoding)}.  However, the manual approach is not recommended.

One problem is the multi-byte nature of encodings; one Unicode character can be
represented by several bytes.  If you want to read the file in arbitrary-sized
chunks (say, 1024 or 4096 bytes), you need to write error-handling code to catch the case
where only part of the bytes encoding a single Unicode character are read at the
end of a chunk.  One solution would be to read the entire file into memory and
then perform the decoding, but that prevents you from working with files that
are extremely large; if you need to read a 2 GiB file, you need 2 GiB of RAM.
(More, really, since for at least a moment you’d need to have both the encoded
string and its Unicode version in memory.)

The solution would be to use the low-level decoding interface to catch the case
of partial coding sequences.  The work of implementing this has already been
done for you: the built-in @ref{32b,,open()} function can return a file-like object
that assumes the file’s contents are in a specified encoding and accepts Unicode
parameters for methods such as @ref{225b,,read()} and
@ref{224a,,write()}.  This works through @code{open()}'s `encoding' and
`errors' parameters which are interpreted just like those in @ref{ca7,,str.encode()}
and @ref{ca8,,bytes.decode()}.

Reading Unicode from a file is therefore simple:

@example
with open('unicode.txt', encoding='utf-8') as f:
    for line in f:
        print(repr(line))
@end example

It’s also possible to open files in update mode, allowing both reading and
writing:

@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

The Unicode character @code{U+FEFF} is used as a byte-order mark (BOM), and is often
written as the first character of a file in order to assist with autodetection
of the file’s byte ordering.  Some encodings, such as UTF-16, expect a BOM to be
present at the start of a file; when such an encoding is used, the BOM will be
automatically written as the first character and will be silently dropped when
the file is read.  There are variants of these encodings, such as “utf-16-le”
and “utf-16-be” for little-endian and big-endian encodings, that specify one
particular byte ordering and don’t skip the BOM.

In some areas, it is also convention to use a «BOM» at the start of UTF-8
encoded files; the name is misleading since UTF-8 is not byte-order dependent.
The mark simply announces that the file is encoded in UTF-8.  For reading such
files, use the “utf-8-sig” codec to automatically skip the mark if present.

@menu
* Unicode filenames:: 
* Tips for Writing Unicode-aware Programs:: 
* References: References<4>. 

@end menu

@node Unicode filenames,Tips for Writing Unicode-aware Programs,,Reading and Writing Unicode Data
@anchor{howto/unicode unicode-filenames}@anchor{5b8e}
@subsubsection Unicode filenames


Most of the operating systems in common use today support filenames
that contain arbitrary Unicode characters.  Usually this is
implemented by converting the Unicode string into some encoding that
varies depending on the system.  Today Python is converging on using
UTF-8: Python on MacOS has used UTF-8 for several versions, and Python
3.6 switched to using UTF-8 on Windows as well.  On Unix systems,
there will only be a @ref{948,,filesystem encoding}. if you’ve set the @code{LANG} or @code{LC_CTYPE} environment variables; if
you haven’t, the default encoding is again UTF-8.

The @ref{1017,,sys.getfilesystemencoding()} function returns the encoding to use on
your current system, in case you want to do the encoding manually, but there’s
not much reason to bother.  When opening a file for reading or writing, you can
usually just provide the Unicode string as the filename, and it will be
automatically converted to the right encoding for you:

@example
filename = 'filename\u4500abc'
with open(filename, 'w') as f:
    f.write('blah\n')
@end example

Functions in the @ref{a5,,os} module such as @ref{4f5,,os.stat()} will also accept Unicode
filenames.

The @ref{14a6,,os.listdir()} function returns filenames, which raises an issue: should it return
the Unicode version of filenames, or should it return bytes containing
the encoded versions?  @code{os.listdir()} can do both, depending on whether you
provided the directory path as bytes or a Unicode string.  If you pass a
Unicode string as the path, filenames will be decoded using the filesystem’s
encoding and a list of Unicode strings will be returned, while passing a byte
path will return the filenames as bytes.  For example,
assuming the default @ref{948,,filesystem encoding} is UTF-8, running the following program:

@example
fn = 'filename\u4500abc'
f = open(fn, 'w')
f.close()

import os
print(os.listdir(b'.'))
print(os.listdir('.'))
@end example

will produce the following output:

@example
$ python listdir-test.py
[b'filename\xe4\x94\x80abc', ...]
['filename\u4500abc', ...]
@end example

The first list contains UTF-8-encoded filenames, and the second list contains
the Unicode versions.

Note that on most occasions, you should can just stick with using
Unicode with these APIs.  The bytes APIs should only be used on
systems where undecodable file names can be present; that’s
pretty much only Unix systems now.

@node Tips for Writing Unicode-aware Programs,References<4>,Unicode filenames,Reading and Writing Unicode Data
@anchor{howto/unicode tips-for-writing-unicode-aware-programs}@anchor{5b8f}
@subsubsection Tips for Writing Unicode-aware Programs


This section provides some suggestions on writing software that deals with
Unicode.

The most important tip is:

@quotation

Software should only work with Unicode strings internally, decoding the input
data as soon as possible and encoding the output only at the end.
@end quotation

If you attempt to write processing functions that accept both Unicode and byte
strings, you will find your program vulnerable to bugs wherever you combine the
two different kinds of strings.  There is no automatic encoding or decoding: if
you do e.g. @code{str + bytes}, a @ref{291,,TypeError} will be raised.

When using data coming from a web browser or some other untrusted source, a
common technique is to check for illegal characters in a string before using the
string in a generated command line or storing it in a database.  If you’re doing
this, be careful to check the decoded string, not the encoded bytes data;
some encodings may have interesting properties, such as not being bijective
or not being fully ASCII-compatible.  This is especially true if the input
data also specifies the encoding, since the attacker can then choose a
clever way to hide malicious text in the encoded bytestream.

@menu
* Converting Between File Encodings:: 
* Files in an Unknown Encoding:: 

@end menu

@node Converting Between File Encodings,Files in an Unknown Encoding,,Tips for Writing Unicode-aware Programs
@anchor{howto/unicode converting-between-file-encodings}@anchor{5b90}
@subsubsection Converting Between File Encodings


The @ref{1fc3,,StreamRecoder} class can transparently convert between
encodings, taking a stream that returns data in encoding #1
and behaving like a stream returning data in encoding #2.

For example, if you have an input file `f' that’s in Latin-1, you
can wrap it with a @ref{1fc3,,StreamRecoder} to return bytes encoded in
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 Files in an Unknown Encoding,,Converting Between File Encodings,Tips for Writing Unicode-aware Programs
@anchor{howto/unicode files-in-an-unknown-encoding}@anchor{5b91}
@subsubsection Files in an Unknown Encoding


What can you do if you need to make a change to a file, but don’t know
the file’s encoding?  If you know the encoding is ASCII-compatible and
only want to examine or modify the ASCII parts, you can open the file
with the @code{surrogateescape} error handler:

@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

The @code{surrogateescape} error handler will decode any non-ASCII bytes
as code points in a special range running from U+DC80 to
U+DCFF.  These code points will then turn back into the
same bytes when the @code{surrogateescape} error handler is used to
encode the data and write it back out.

@node References<4>,,Tips for Writing Unicode-aware Programs,Reading and Writing Unicode Data
@anchor{howto/unicode id4}@anchor{5b92}
@subsubsection References


One section of Mastering Python 3 Input/Output@footnote{https://pyvideo.org/video/289/pycon-2010--mastering-python-3-i-o},
a PyCon 2010 talk by David Beazley, discusses text processing and binary data handling.

The PDF slides for Marc-André Lemburg's presentation "Writing Unicode-aware Applications in Python"@footnote{https://downloads.egenix.com/python/LSM2005-Developing-Unicode-aware-applications-in-Python.pdf}
discuss questions of character encodings as well as how to internationalize
and localize an application.  These slides cover Python 2.x only.

The Guts of Unicode in Python@footnote{https://pyvideo.org/video/1768/the-guts-of-unicode-in-python}
is a PyCon 2013 talk by Benjamin Peterson that discusses the internal Unicode
representation in Python 3.3.

@node Acknowledgements<10>,,Reading and Writing Unicode Data,Unicode HOWTO
@anchor{howto/unicode acknowledgements}@anchor{5b93}
@subsection Acknowledgements


The initial draft of this document was written by Andrew Kuchling.
It has since been revised further by Alexander Belopolsky, Georg Brandl,
Andrew Kuchling, and Ezio Melotti.

Thanks to the following people who have noted errors or offered
suggestions on this 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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node HOWTO Fetch Internet Resources Using The urllib Package,An introduction to the ipaddress module,Unicode HOWTO,Python HOWTOs
@anchor{howto/urllib2 doc}@anchor{5b94}@anchor{howto/urllib2 howto-fetch-internet-resources-using-the-urllib-package}@anchor{5b95}@anchor{howto/urllib2 translation-repo}@anchor{5b96}@anchor{howto/urllib2 urllib-howto}@anchor{41d3}
@section HOWTO Fetch Internet Resources Using The urllib Package


@*Author: 
Michael Foord@footnote{https://agileabstractions.com/}


@menu
* Introduction: Introduction<15>. 
* Fetching URLs:: 
* Handling Exceptions:: 
* info and geturl:: 
* Openers and Handlers:: 
* Basic Authentication:: 
* Proxies:: 
* Sockets and Layers:: 
* Footnotes:: 

@end menu

@node Introduction<15>,Fetching URLs,,HOWTO Fetch Internet Resources Using The urllib Package
@anchor{howto/urllib2 introduction}@anchor{5b97}
@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{114,,urllib.request} docs, but is supplementary to them.

@node Fetching URLs,Handling Exceptions,Introduction<15>,HOWTO Fetch Internet Resources Using The urllib Package
@anchor{howto/urllib2 fetching-urls}@anchor{5b98}
@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{e21,,shutil.copyfileobj()} and
@ref{8d6,,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{5b99}
@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{113,,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{5b9a}
@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{5b9b,,info and geturl}
which comes after we have a look at what happens when things go wrong.

@node Handling Exceptions,info and geturl,Fetching URLs,HOWTO Fetch Internet Resources Using The urllib Package
@anchor{howto/urllib2 handling-exceptions}@anchor{5b9c}
@subsection Handling Exceptions


`urlopen' raises @ref{53a,,URLError} when it cannot handle a response (though as
usual with Python APIs, built-in exceptions such as @ref{277,,ValueError},
@ref{291,,TypeError} etc. may also be raised).

@ref{1387,,HTTPError} is the subclass of @ref{53a,,URLError} raised in the specific case of
HTTP URLs.

The exception classes are exported from the @ref{112,,urllib.error} module.

@menu
* URLError:: 
* HTTPError:: 
* Wrapping it Up:: 

@end menu

@node URLError,HTTPError,,Handling Exceptions
@anchor{howto/urllib2 urlerror}@anchor{5b9d}
@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,Handling Exceptions
@anchor{howto/urllib2 httperror}@anchor{5b9e}
@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{1387,,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{1387,,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{5b9f}
@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{41f8,,http.server.BaseHTTPRequestHandler.responses} is a useful dictionary of
response codes that shows all the response codes used by 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html}.
An excerpt from the dictionary is shown below

@example
responses = @{
    ...
    <HTTPStatus.OK: 200>: ('OK', 'Request fulfilled, document follows'),
    ...
    <HTTPStatus.FORBIDDEN: 403>: ('Forbidden',
                                  'Request forbidden -- authorization will '
                                  'not help'),
    <HTTPStatus.NOT_FOUND: 404>: ('Not Found',
                                  'Nothing matches the given URI'),
    ...
    <HTTPStatus.IM_A_TEAPOT: 418>: ("I'm a Teapot",
                                    'Server refuses to brew coffee because '
                                    'it is a teapot'),
    ...
    <HTTPStatus.SERVICE_UNAVAILABLE: 503>: ('Service Unavailable',
                                            'The server cannot process the '
                                            'request due to a high load'),
    ...
    @}
@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{1387,,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,Handling Exceptions
@anchor{howto/urllib2 wrapping-it-up}@anchor{5ba0}
@subsubsection Wrapping it Up


So if you want to be prepared for @ref{1387,,HTTPError} `or' @ref{53a,,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{5ba1}
@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 Σημείωση 
The @code{except HTTPError} `must' come first, otherwise @code{except URLError}
will `also' catch an @ref{1387,,HTTPError}.
@end quotation
@end cartouche

@node Number 2,,Number 1,Wrapping it Up
@anchor{howto/urllib2 number-2}@anchor{5ba2}
@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,Handling Exceptions,HOWTO Fetch Internet Resources Using The urllib Package
@anchor{howto/urllib2 info-and-geturl}@anchor{5b9b}
@subsection info and geturl


The response returned by urlopen (or the @ref{1387,,HTTPError} instance) has two
useful methods @code{info()} and @code{geturl()} and is defined in the module
@ref{115,,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{4211,,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,HOWTO Fetch Internet Resources Using The urllib Package
@anchor{howto/urllib2 openers-and-handlers}@anchor{5ba3}
@subsection Openers and Handlers


When you fetch a URL you use an opener (an instance of the perhaps
confusingly named @ref{199b,,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,HOWTO Fetch Internet Resources Using The urllib Package
@anchor{howto/urllib2 basic-authentication}@anchor{5ba4}
@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 Σημείωση 
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,HOWTO Fetch Internet Resources Using The urllib Package
@anchor{howto/urllib2 proxies}@anchor{5ba5}
@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 @ref{5ba4,,Basic Authentication} handler:

@example
>>> proxy_support = urllib.request.ProxyHandler(@{@})
>>> opener = urllib.request.build_opener(proxy_support)
>>> urllib.request.install_opener(opener)
@end example

@cartouche
@quotation Σημείωση 
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 Σημείωση 
@code{HTTP_PROXY} will be ignored if a variable @code{REQUEST_METHOD} is set; see
the documentation on @ref{415f,,getproxies()}.
@end quotation
@end cartouche

@node Sockets and Layers,Footnotes,Proxies,HOWTO Fetch Internet Resources Using The urllib Package
@anchor{howto/urllib2 sockets-and-layers}@anchor{5ba6}
@subsection Sockets and Layers


The Python support for fetching resources from the web is layered.  urllib uses
the @ref{72,,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 Footnotes,,Sockets and Layers,HOWTO Fetch Internet Resources Using The urllib Package
@anchor{howto/urllib2 footnotes}@anchor{5ba7}
@subsection Footnotes


This document was reviewed and revised by John Lee.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c import ipaddress

@node An introduction to the ipaddress module,Instrumenting CPython with DTrace and SystemTap,HOWTO Fetch Internet Resources Using The urllib Package,Python HOWTOs
@anchor{howto/ipaddress doc}@anchor{5ba8}@anchor{howto/ipaddress an-introduction-to-the-ipaddress-module}@anchor{5ba9}@anchor{howto/ipaddress ipaddress-howto}@anchor{440f}@anchor{howto/ipaddress translation-repo}@anchor{5baa}
@section An introduction to the ipaddress module


@*author: 
Peter Moody


@*author: 
Nick Coghlan


@subsubheading Overview



This document aims to provide a gentle introduction to the
@ref{83,,ipaddress} module. It is aimed primarily at users that aren’t
already familiar with IP networking terminology, but may also be useful
to network engineers wanting an overview of how @code{ipaddress}
represents IP network addressing concepts.

@menu
* Creating Address/Network/Interface objects:: 
* Inspecting Address/Network/Interface Objects:: 
* Networks as lists of Addresses:: 
* Comparisons: Comparisons<3>. 
* Using IP Addresses with other modules:: 
* Getting more detail when instance creation fails:: 

@end menu

@node Creating Address/Network/Interface objects,Inspecting Address/Network/Interface Objects,,An introduction to the ipaddress module
@anchor{howto/ipaddress creating-address-network-interface-objects}@anchor{5bab}
@subsection Creating Address/Network/Interface objects


Since @ref{83,,ipaddress} is a module for inspecting and manipulating IP addresses,
the first thing you’ll want to do is create some objects.  You can use
@code{ipaddress} to create objects from strings and integers.

@menu
* A Note on IP Versions:: 
* IP Host Addresses:: 
* Defining Networks:: 
* Host Interfaces:: 

@end menu

@node A Note on IP Versions,IP Host Addresses,,Creating Address/Network/Interface objects
@anchor{howto/ipaddress a-note-on-ip-versions}@anchor{5bac}
@subsubsection A Note on IP Versions


For readers that aren’t particularly familiar with IP addressing, it’s
important to know that the Internet Protocol (IP) is currently in the process
of moving from version 4 of the protocol to version 6. This transition is
occurring largely because version 4 of the protocol doesn’t provide enough
addresses to handle the needs of the whole world, especially given the
increasing number of devices with direct connections to the internet.

Explaining the details of the differences between the two versions of the
protocol is beyond the scope of this introduction, but readers need to at
least be aware that these two versions exist, and it will sometimes be
necessary to force the use of one version or the other.

@node IP Host Addresses,Defining Networks,A Note on IP Versions,Creating Address/Network/Interface objects
@anchor{howto/ipaddress ip-host-addresses}@anchor{5bad}
@subsubsection IP Host Addresses


Addresses, often referred to as «host addresses» are the most basic unit
when working with IP addressing. The simplest way to create addresses is
to use the @ref{4411,,ipaddress.ip_address()} factory function, which automatically
determines whether to create an IPv4 or IPv6 address based on the passed in
value:

@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

Addresses can also be created directly from integers. Values that will
fit within 32 bits are assumed to be IPv4 addresses:

@example
>>> ipaddress.ip_address(3221225985)
IPv4Address('192.0.2.1')
>>> ipaddress.ip_address(42540766411282592856903984951653826561)
IPv6Address('2001:db8::1')
@end example

To force the use of IPv4 or IPv6 addresses, the relevant classes can be
invoked directly. This is particularly useful to force creation of IPv6
addresses for small integers:

@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 Defining Networks,Host Interfaces,IP Host Addresses,Creating Address/Network/Interface objects
@anchor{howto/ipaddress defining-networks}@anchor{5bae}
@subsubsection Defining Networks


Host addresses are usually grouped together into IP networks, so
@ref{83,,ipaddress} provides a way to create, inspect and manipulate network
definitions. IP network objects are constructed from strings that define the
range of host addresses that are part of that network. The simplest form
for that information is a «network address/network prefix» pair, where the
prefix defines the number of leading bits that are compared to determine
whether or not an address is part of the network and the network address
defines the expected value of those bits.

As for addresses, a factory function is provided that determines the correct
IP version automatically:

@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

Network objects cannot have any host bits set.  The practical effect of this
is that @code{192.0.2.1/24} does not describe a network.  Such definitions are
referred to as interface objects since the ip-on-a-network notation is
commonly used to describe network interfaces of a computer on a given network
and are described further in the next section.

By default, attempting to create a network object with host bits set will
result in @ref{277,,ValueError} being raised. To request that the
additional bits instead be coerced to zero, the flag @code{strict=False} can
be passed to the constructor:

@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

While the string form offers significantly more flexibility, networks can
also be defined with integers, just like host addresses. In this case, the
network is considered to contain only the single address identified by the
integer, so the network prefix includes the entire network address:

@example
>>> ipaddress.ip_network(3221225984)
IPv4Network('192.0.2.0/32')
>>> ipaddress.ip_network(42540766411282592856903984951653826560)
IPv6Network('2001:db8::/128')
@end example

As with addresses, creation of a particular kind of network can be forced
by calling the class constructor directly instead of using the factory
function.

@node Host Interfaces,,Defining Networks,Creating Address/Network/Interface objects
@anchor{howto/ipaddress host-interfaces}@anchor{5baf}
@subsubsection Host Interfaces


As mentioned just above, if you need to describe an address on a particular
network, neither the address nor the network classes are sufficient.
Notation like @code{192.0.2.1/24} is commonly used by network engineers and the
people who write tools for firewalls and routers as shorthand for «the host
@code{192.0.2.1} on the network @code{192.0.2.0/24}», Accordingly, @ref{83,,ipaddress}
provides a set of hybrid classes that associate an address with a particular
network. The interface for creation is identical to that for defining network
objects, except that the address portion isn’t constrained to being a network
address.

@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

Integer inputs are accepted (as with networks), and use of a particular IP
version can be forced by calling the relevant constructor directly.

@node Inspecting Address/Network/Interface Objects,Networks as lists of Addresses,Creating Address/Network/Interface objects,An introduction to the ipaddress module
@anchor{howto/ipaddress inspecting-address-network-interface-objects}@anchor{5bb0}
@subsection Inspecting Address/Network/Interface Objects


You’ve gone to the trouble of creating an IPv(4|6)(Address|Network|Interface)
object, so you probably want to get information about it.  @ref{83,,ipaddress}
tries to make doing this easy and intuitive.

Extracting the IP version:

@example
>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> addr6 = ipaddress.ip_address('2001:db8::1')
>>> addr6.version
6
>>> addr4.version
4
@end example

Obtaining the network from an 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

Finding out how many individual addresses are in a network:

@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

Iterating through the «usable» addresses on a network:

@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

Obtaining the netmask (i.e. set bits corresponding to the network prefix) or
the hostmask (any bits that are not part of the netmask):

@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

Exploding or compressing the address:

@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

While IPv4 doesn’t support explosion or compression, the associated objects
still provide the relevant properties so that version neutral code can
easily ensure the most concise or most verbose form is used for IPv6
addresses while still correctly handling IPv4 addresses.

@node Networks as lists of Addresses,Comparisons<3>,Inspecting Address/Network/Interface Objects,An introduction to the ipaddress module
@anchor{howto/ipaddress networks-as-lists-of-addresses}@anchor{5bb1}
@subsection Networks as lists of Addresses


It’s sometimes useful to treat networks as lists.  This means it is possible
to index them like this:

@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

It also means that network objects lend themselves to using the list
membership test syntax like this:

@example
if address in network:
    # do something
@end example

Containment testing is done efficiently based on the network prefix:

@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 Comparisons<3>,Using IP Addresses with other modules,Networks as lists of Addresses,An introduction to the ipaddress module
@anchor{howto/ipaddress comparisons}@anchor{5bb2}
@subsection Comparisons


@ref{83,,ipaddress} provides some simple, hopefully intuitive ways to compare
objects, where it makes sense:

@example
>>> ipaddress.ip_address('192.0.2.1') < ipaddress.ip_address('192.0.2.2')
True
@end example

A @ref{291,,TypeError} exception is raised if you try to compare objects of
different versions or different types.

@node Using IP Addresses with other modules,Getting more detail when instance creation fails,Comparisons<3>,An introduction to the ipaddress module
@anchor{howto/ipaddress using-ip-addresses-with-other-modules}@anchor{5bb3}
@subsection Using IP Addresses with other modules


Other modules that use IP addresses (such as @ref{d4,,socket}) usually won’t
accept objects from this module directly. Instead, they must be coerced to
an integer or string that the other module will accept:

@example
>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> str(addr4)
'192.0.2.1'
>>> int(addr4)
3221225985
@end example

@node Getting more detail when instance creation fails,,Using IP Addresses with other modules,An introduction to the ipaddress module
@anchor{howto/ipaddress getting-more-detail-when-instance-creation-fails}@anchor{5bb4}
@subsection Getting more detail when instance creation fails


When creating address/network/interface objects using the version-agnostic
factory functions, any errors will be reported as @ref{277,,ValueError} with
a generic error message that simply says the passed in value was not
recognized as an object of that type. The lack of a specific error is
because it’s necessary to know whether the value is `supposed' to be IPv4
or IPv6 in order to provide more detail on why it has been rejected.

To support use cases where it is useful to have access to this additional
detail, the individual class constructors actually raise the
@ref{277,,ValueError} subclasses @ref{4416,,ipaddress.AddressValueError} and
@ref{4437,,ipaddress.NetmaskValueError} to indicate exactly which part of
the definition failed to parse correctly.

The error messages are significantly more detailed when using the
class constructors directly. For example:

@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

However, both of the module specific exceptions have @ref{277,,ValueError} as their
parent class, so if you’re not concerned with the particular type of error,
you can still write code like the following:

@example
try:
    network = ipaddress.IPv4Network(address)
except ValueError:
    print('address/netmask is invalid for IPv4:', address)
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Instrumenting CPython with DTrace and SystemTap,Python support for the perf map compatible profilers,An introduction to the ipaddress module,Python HOWTOs
@anchor{howto/instrumentation doc}@anchor{5bb5}@anchor{howto/instrumentation instrumentation}@anchor{102a}@anchor{howto/instrumentation instrumenting-cpython-with-dtrace-and-systemtap}@anchor{5bb6}@anchor{howto/instrumentation translation-repo}@anchor{5bb7}
@section Instrumenting CPython with DTrace and SystemTap


@*author: 
David Malcolm


@*author: 
Łukasz Langa


DTrace and SystemTap are monitoring tools, each providing a way to inspect
what the processes on a computer system are doing.  They both use
domain-specific languages allowing a user to write scripts which:


@itemize -

@item 
filter which processes are to be observed

@item 
gather data from the processes of interest

@item 
generate reports on the data
@end itemize

As of Python 3.6, CPython can be built with embedded «markers», also
known as «probes», that can be observed by a DTrace or SystemTap script,
making it easier to monitor what the CPython processes on a system are
doing.

`Λεπτομέρεια υλοποίησης CPython:' DTrace markers are implementation details of the CPython interpreter.
No guarantees are made about probe compatibility between versions of
CPython. DTrace scripts can stop working or work incorrectly without
warning when changing CPython versions.

@menu
* Enabling the static markers:: 
* Static DTrace probes:: 
* Static SystemTap markers:: 
* Available static markers:: 
* SystemTap Tapsets:: 
* Examples: Examples<34>. 

@end menu

@node Enabling the static markers,Static DTrace probes,,Instrumenting CPython with DTrace and SystemTap
@anchor{howto/instrumentation enabling-the-static-markers}@anchor{5bb8}
@subsection Enabling the static markers


macOS comes with built-in support for DTrace.  On Linux, in order to
build CPython with the embedded markers for SystemTap, the SystemTap
development tools must be installed.

On a Linux machine, this can be done via:

@example
$ yum install systemtap-sdt-devel
@end example

or:

@example
$ sudo apt-get install systemtap-sdt-dev
@end example

CPython must then be @ref{2395,,configured with the --with-dtrace option}:

@example
checking for --with-dtrace... yes
@end example

On macOS, you can list available DTrace probes by running a Python
process in the background and listing all probes made available by the
Python provider:

@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

On Linux, you can verify if the SystemTap static markers are present in
the built binary by seeing if it contains a «.note.stapsdt» section.

@example
$ readelf -S ./python | grep .note.stapsdt
[30] .note.stapsdt        NOTE         0000000000000000 00308d78
@end example

If you’ve built Python as a shared library
(with the @ref{c3a,,--enable-shared} configure option), you
need to look instead within the shared library.  For example:

@example
$ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt
[29] .note.stapsdt        NOTE         0000000000000000 00365b68
@end example

Sufficiently modern readelf can print the metadata:

@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 Static DTrace probes,Static SystemTap markers,Enabling the static markers,Instrumenting CPython with DTrace and SystemTap
@anchor{howto/instrumentation static-dtrace-probes}@anchor{5bb9}
@subsection Static DTrace probes


The following example DTrace script can be used to show the call/return
hierarchy of a Python script, only tracing within the invocation of
a function called «start». In other words, import-time function
invocations are not going to be listed:

@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

It can be invoked like this:

@example
$ sudo dtrace -q -s call_stack.d -c "python3.6 script.py"
@end example

The output looks like this:

@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 Static SystemTap markers,Available static markers,Static DTrace probes,Instrumenting CPython with DTrace and SystemTap
@anchor{howto/instrumentation static-systemtap-markers}@anchor{5bba}
@subsection Static SystemTap markers


The low-level way to use the SystemTap integration is to use the static
markers directly.  This requires you to explicitly state the binary file
containing them.

For example, this SystemTap script can be used to show the call/return
hierarchy of a Python script:

@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

It can be invoked like this:

@example
$ stap \
  show-call-hierarchy.stp \
  -c "./python test.py"
@end example

The output looks like this:

@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

where the columns are:


@itemize -

@item 
time in microseconds since start of script

@item 
name of executable

@item 
PID of process
@end itemize

and the remainder indicates the call/return hierarchy as the script executes.

For a @ref{c3a,,--enable-shared} build of CPython, the markers are contained within the
libpython shared library, and the probe’s dotted path needs to reflect this. For
example, this line from the above example:

@example
probe process("python").mark("function__entry") @{
@end example

should instead read:

@example
probe process("python").library("libpython3.6dm.so.1.0").mark("function__entry") @{
@end example

(assuming a @ref{3dc,,debug build} of CPython 3.6)

@node Available static markers,SystemTap Tapsets,Static SystemTap markers,Instrumenting CPython with DTrace and SystemTap
@anchor{howto/instrumentation available-static-markers}@anchor{5bbb}@anchor{howto/instrumentation static-markers}@anchor{f76}
@subsection Available static markers



@deffn {Object} function__entry(str filename, str funcname, int lineno)

This marker indicates that execution of a Python function has begun.
It is only triggered for pure-Python (bytecode) functions.

The filename, function name, and line number are provided back to the
tracing script as positional arguments, which must be accessed using
@code{$arg1}, @code{$arg2}, @code{$arg3}:

@quotation


@itemize *

@item 
@code{$arg1} : @code{(const char *)} filename, accessible using @code{user_string($arg1)}

@item 
@code{$arg2} : @code{(const char *)} function name, accessible using
@code{user_string($arg2)}

@item 
@code{$arg3} : @code{int} line number
@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)

This marker indicates a Python line is about to be executed.  It is
the equivalent of line-by-line tracing with a Python profiler.  It is
not triggered within C functions.

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{44f,,gc.collect()}.
@end deffn


@deffn {Object} gc__done(long collected)

Fires when the Python interpreter finishes a garbage collection
cycle. @code{arg0} is the number of collected objects.
@end deffn


@deffn {Object} import__find__load__start(str modulename)

Fires before @ref{7a,,importlib} attempts to find and load the module.
@code{arg0} is the module name.


Added in version 3.7.

@end deffn


@deffn {Object} import__find__load__done(str modulename, int found)

Fires after @ref{7a,,importlib}’s find_and_load function is called.
@code{arg0} is the module name, @code{arg1} indicates if module was
successfully loaded.


Added in version 3.7.

@end deffn


@deffn {Object} audit(str event, void *tuple)

Fires when @ref{1b36,,sys.audit()} or @ref{808,,PySys_Audit()} is called.
@code{arg0} is the event name as C string, @code{arg1} is a @ref{19b,,PyObject}
pointer to a tuple object.


Added in version 3.8.

@end deffn

@menu
* C Entry Points:: 
* C Probing Checks:: 

@end menu

@node C Entry Points,C Probing Checks,,Available static markers
@anchor{howto/instrumentation c-entry-points}@anchor{5bbc}
@subsubsection C Entry Points


To simplify triggering of DTrace markers, Python’s C API comes with a number
of helper functions that mirror each static marker. On builds of Python without
DTrace enabled, these do nothing.

In general, it is not necessary to call these yourself, as Python will do
it for you.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

C API Function

@tab

Static Marker

@tab

Notes

@item

@geindex PyDTrace_LINE (C function)
@anchor{howto/instrumentation c PyDTrace_LINE}@anchor{5bbd}
@deffn {C Συνάρτηση} void PyDTrace_LINE (const char *arg0, const char *arg1, int arg2)
@end deffn

@tab

@code{line()}

@tab

@item

@geindex PyDTrace_FUNCTION_ENTRY (C function)
@anchor{howto/instrumentation c PyDTrace_FUNCTION_ENTRY}@anchor{5bbe}
@deffn {C Συνάρτηση} void PyDTrace_FUNCTION_ENTRY (const char *arg0, const char *arg1, int arg2)
@end deffn

@tab

@code{function__entry()}

@tab

@item

@geindex PyDTrace_FUNCTION_RETURN (C function)
@anchor{howto/instrumentation c PyDTrace_FUNCTION_RETURN}@anchor{5bbf}
@deffn {C Συνάρτηση} void PyDTrace_FUNCTION_RETURN (const char *arg0, const char *arg1, int arg2)
@end deffn

@tab

@code{function__return()}

@tab

@item

@geindex PyDTrace_GC_START (C function)
@anchor{howto/instrumentation c PyDTrace_GC_START}@anchor{5bc0}
@deffn {C Συνάρτηση} void PyDTrace_GC_START (int arg0)
@end deffn

@tab

@code{gc__start()}

@tab

@item

@geindex PyDTrace_GC_DONE (C function)
@anchor{howto/instrumentation c PyDTrace_GC_DONE}@anchor{5bc1}
@deffn {C Συνάρτηση} void PyDTrace_GC_DONE (Py_ssize_t arg0)
@end deffn

@tab

@code{gc__done()}

@tab

@item

@geindex PyDTrace_INSTANCE_NEW_START (C function)
@anchor{howto/instrumentation c PyDTrace_INSTANCE_NEW_START}@anchor{5bc2}
@deffn {C Συνάρτηση} void PyDTrace_INSTANCE_NEW_START (int arg0)
@end deffn

@tab

@code{instance__new__start()}

@tab

Not used by Python

@item

@geindex PyDTrace_INSTANCE_NEW_DONE (C function)
@anchor{howto/instrumentation c PyDTrace_INSTANCE_NEW_DONE}@anchor{5bc3}
@deffn {C Συνάρτηση} void PyDTrace_INSTANCE_NEW_DONE (int arg0)
@end deffn

@tab

@code{instance__new__done()}

@tab

Not used by Python

@item

@geindex PyDTrace_INSTANCE_DELETE_START (C function)
@anchor{howto/instrumentation c PyDTrace_INSTANCE_DELETE_START}@anchor{5bc4}
@deffn {C Συνάρτηση} void PyDTrace_INSTANCE_DELETE_START (int arg0)
@end deffn

@tab

@code{instance__delete__start()}

@tab

Not used by Python

@item

@geindex PyDTrace_INSTANCE_DELETE_DONE (C function)
@anchor{howto/instrumentation c PyDTrace_INSTANCE_DELETE_DONE}@anchor{5bc5}
@deffn {C Συνάρτηση} void PyDTrace_INSTANCE_DELETE_DONE (int arg0)
@end deffn

@tab

@code{instance__delete__done()}

@tab

Not used by Python

@item

@geindex PyDTrace_IMPORT_FIND_LOAD_START (C function)
@anchor{howto/instrumentation c PyDTrace_IMPORT_FIND_LOAD_START}@anchor{5bc6}
@deffn {C Συνάρτηση} void PyDTrace_IMPORT_FIND_LOAD_START (const char *arg0)
@end deffn

@tab

@code{import__find__load__start()}

@tab

@item

@geindex PyDTrace_IMPORT_FIND_LOAD_DONE (C function)
@anchor{howto/instrumentation c PyDTrace_IMPORT_FIND_LOAD_DONE}@anchor{5bc7}
@deffn {C Συνάρτηση} void PyDTrace_IMPORT_FIND_LOAD_DONE (const char *arg0, int arg1)
@end deffn

@tab

@code{import__find__load__done()}

@tab

@item

@geindex PyDTrace_AUDIT (C function)
@anchor{howto/instrumentation c PyDTrace_AUDIT}@anchor{5bc8}
@deffn {C Συνάρτηση} void PyDTrace_AUDIT (const char *arg0, void *arg1)
@end deffn

@tab

@code{audit()}

@tab

@end multitable


@node C Probing Checks,,C Entry Points,Available static markers
@anchor{howto/instrumentation c-probing-checks}@anchor{5bc9}
@subsubsection C Probing Checks


@geindex PyDTrace_LINE_ENABLED (C function)
@anchor{howto/instrumentation c PyDTrace_LINE_ENABLED}@anchor{5bca}
@deffn {C Συνάρτηση} int PyDTrace_LINE_ENABLED (void)
@end deffn

@geindex PyDTrace_FUNCTION_ENTRY_ENABLED (C function)
@anchor{howto/instrumentation c PyDTrace_FUNCTION_ENTRY_ENABLED}@anchor{5bcb}
@deffn {C Συνάρτηση} int PyDTrace_FUNCTION_ENTRY_ENABLED (void)
@end deffn

@geindex PyDTrace_FUNCTION_RETURN_ENABLED (C function)
@anchor{howto/instrumentation c PyDTrace_FUNCTION_RETURN_ENABLED}@anchor{5bcc}
@deffn {C Συνάρτηση} int PyDTrace_FUNCTION_RETURN_ENABLED (void)
@end deffn

@geindex PyDTrace_GC_START_ENABLED (C function)
@anchor{howto/instrumentation c PyDTrace_GC_START_ENABLED}@anchor{5bcd}
@deffn {C Συνάρτηση} int PyDTrace_GC_START_ENABLED (void)
@end deffn

@geindex PyDTrace_GC_DONE_ENABLED (C function)
@anchor{howto/instrumentation c PyDTrace_GC_DONE_ENABLED}@anchor{5bce}
@deffn {C Συνάρτηση} int PyDTrace_GC_DONE_ENABLED (void)
@end deffn

@geindex PyDTrace_INSTANCE_NEW_START_ENABLED (C function)
@anchor{howto/instrumentation c PyDTrace_INSTANCE_NEW_START_ENABLED}@anchor{5bcf}
@deffn {C Συνάρτηση} int PyDTrace_INSTANCE_NEW_START_ENABLED (void)
@end deffn

@geindex PyDTrace_INSTANCE_NEW_DONE_ENABLED (C function)
@anchor{howto/instrumentation c PyDTrace_INSTANCE_NEW_DONE_ENABLED}@anchor{5bd0}
@deffn {C Συνάρτηση} int PyDTrace_INSTANCE_NEW_DONE_ENABLED (void)
@end deffn

@geindex PyDTrace_INSTANCE_DELETE_START_ENABLED (C function)
@anchor{howto/instrumentation c PyDTrace_INSTANCE_DELETE_START_ENABLED}@anchor{5bd1}
@deffn {C Συνάρτηση} int PyDTrace_INSTANCE_DELETE_START_ENABLED (void)
@end deffn

@geindex PyDTrace_INSTANCE_DELETE_DONE_ENABLED (C function)
@anchor{howto/instrumentation c PyDTrace_INSTANCE_DELETE_DONE_ENABLED}@anchor{5bd2}
@deffn {C Συνάρτηση} int PyDTrace_INSTANCE_DELETE_DONE_ENABLED (void)
@end deffn

@geindex PyDTrace_IMPORT_FIND_LOAD_START_ENABLED (C function)
@anchor{howto/instrumentation c PyDTrace_IMPORT_FIND_LOAD_START_ENABLED}@anchor{5bd3}
@deffn {C Συνάρτηση} int PyDTrace_IMPORT_FIND_LOAD_START_ENABLED (void)
@end deffn

@geindex PyDTrace_IMPORT_FIND_LOAD_DONE_ENABLED (C function)
@anchor{howto/instrumentation c PyDTrace_IMPORT_FIND_LOAD_DONE_ENABLED}@anchor{5bd4}
@deffn {C Συνάρτηση} int PyDTrace_IMPORT_FIND_LOAD_DONE_ENABLED (void)
@end deffn

@geindex PyDTrace_AUDIT_ENABLED (C function)
@anchor{howto/instrumentation c PyDTrace_AUDIT_ENABLED}@anchor{5bd5}
@deffn {C Συνάρτηση} int PyDTrace_AUDIT_ENABLED (void)

All calls to @code{PyDTrace} functions must be guarded by a call to one
of these functions. This allows Python to minimize performance impact
when probing is disabled.

On builds without DTrace enabled, these functions do nothing and return
@code{0}.
@end deffn

@node SystemTap Tapsets,Examples<34>,Available static markers,Instrumenting CPython with DTrace and SystemTap
@anchor{howto/instrumentation systemtap-tapsets}@anchor{5bd6}
@subsection SystemTap Tapsets


The higher-level way to use the SystemTap integration is to use a «tapset»:
SystemTap’s equivalent of a library, which hides some of the lower-level
details of the static markers.

Here is a tapset file, based on a non-shared build of 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

If this file is installed in SystemTap’s tapset directory (e.g.
@code{/usr/share/systemtap/tapset}), then these additional probepoints become
available:


@deffn {Object} python.function.entry(str filename, str funcname, int lineno, frameptr)

This probe point indicates that execution of a Python function has begun.
It is only triggered for pure-Python (bytecode) functions.
@end deffn


@deffn {Object} python.function.return(str filename, str funcname, int lineno, frameptr)

This probe point is the converse of @code{python.function.return}, 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.
@end deffn

@node Examples<34>,,SystemTap Tapsets,Instrumenting CPython with DTrace and SystemTap
@anchor{howto/instrumentation examples}@anchor{5bd7}
@subsection Examples


This SystemTap script uses the tapset above to more cleanly implement the
example given above of tracing the Python function-call hierarchy, without
needing to directly name the static markers:

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python support for the perf map compatible profilers,Annotations Best Practices,Instrumenting CPython with DTrace and SystemTap,Python HOWTOs
@anchor{howto/perf_profiling doc}@anchor{1caf}@anchor{howto/perf_profiling perf-profiling}@anchor{6b7}@anchor{howto/perf_profiling python-support-for-the-perf-map-compatible-profilers}@anchor{5bd8}@anchor{howto/perf_profiling translation-repo}@anchor{5bd9}
@section Python support for the @code{perf map} compatible profilers


@*author: 
Pablo Galindo


The Linux perf profiler@footnote{https://perf.wiki.kernel.org} and
samply@footnote{https://github.com/mstange/samply} are powerful tools that allow you to
profile and obtain information about the performance of your application.
Both tools have vibrant ecosystems that aid with the analysis of the data they produce.

The main problem with using these profilers with Python applications is that
they only get 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 profiler output.

Since Python 3.12, the interpreter can run in a special mode that allows Python
functions to appear in the output of compatible profilers. 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 the profiler the
relationship between this piece of code and the associated Python function using
@ref{55d4,,perf map files}.

@cartouche
@quotation Σημείωση 
Support for profiling is available on Linux and macOS on select architectures.
Perf is available on Linux, while samply can be used on both Linux and macOS.
samply support on macOS is available starting from Python 3.15.
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%--_PyCompactLong_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%--_PyCompactLong_Add
                        |          |          |                     |          |          |
                        |          |          |                     |          |          |--3.26%--_PyObject_Malloc
@end example

@menu
* Using the samply profiler:: 
* How to enable perf profiling support:: 
* How to obtain the best results:: 
* How to work without frame pointers:: 

@end menu

@node Using the samply profiler,How to enable perf profiling support,,Python support for the perf map compatible profilers
@anchor{howto/perf_profiling using-the-samply-profiler}@anchor{5bda}
@subsection Using the samply profiler


samply is a modern profiler that can be used as an alternative to perf.
It uses the same perf map files that Python generates, making it compatible
with Python’s profiling support. samply is particularly useful on macOS
where perf is not available.

To use samply with Python, first install it following the instructions at
@indicateurl{https://github.com/mstange/samply}, then run:

@example
$ samply record PYTHONPERFSUPPORT=1 python my_script.py
@end example

This will open a web interface where you can analyze the profiling data
interactively. The advantage of samply is that it provides a modern
web-based interface for analyzing profiling data and works on both Linux
and macOS.

On macOS, samply support requires Python 3.15 or later. Also on macOS, samply
can’t profile signed Python executables due to restrictions by macOS. You can
profile with Python binaries that you’ve compiled yourself, or which are
unsigned or locally-signed (such as anything installed by Homebrew). In
order to attach to running processes on macOS, run @code{samply setup} once (and
every time samply is updated) to self-sign the samply binary.

@node How to enable perf profiling support,How to obtain the best results,Using the samply profiler,Python support for the perf map compatible profilers
@anchor{howto/perf_profiling how-to-enable-perf-profiling-support}@anchor{5bdb}
@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 μεταβλητή περιβάλλοντος; PYTHONPERFSUPPORT
@ref{884,,PYTHONPERFSUPPORT} or the
@ref{178,,-X perf} option,
or dynamically using @ref{885,,sys.activate_stack_trampoline()} and
@ref{886,,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 my_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 my_script.py
$ perf report -g -i perf.data
@end example

Example, using the @ref{e2,,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 perf map compatible profilers
@anchor{howto/perf_profiling how-to-obtain-the-best-results}@anchor{5bdc}
@subsection How to obtain the best results


For best results, keep frame pointers enabled. On supported GCC-compatible
toolchains, CPython builds itself with @code{-fno-omit-frame-pointer} and similar
flags (see @ref{3dd,,--without-frame-pointers} for details). These flags allow
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 perf map compatible profilers
@anchor{howto/perf_profiling how-to-work-without-frame-pointers}@anchor{5bdd}
@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 μεταβλητή περιβάλλοντος; PYTHON_PERF_JIT_SUPPORT
@ref{6b8,,PYTHON_PERF_JIT_SUPPORT} or the @ref{178,,-X perf_jit} option,
which will enable the JIT mode for the @code{perf} profiler.

@cartouche
@quotation Σημείωση 
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 -k 1 --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 Προειδοποίηση 
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 you can change the size by passing it after
a comma like @code{--call-graph dwarf,16384}.

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.

The stack size is particularly important when profiling Python code compiled
with low optimization levels (like @code{-O0}), as these builds tend to have
larger stack frames. If you are compiling Python with @code{-O0} and not seeing
Python functions in your profiling output, try increasing the stack dump
size to 65528 bytes (the maximum):

@example
$ perf record -F 9999 -g -k 1 --call-graph dwarf,65528 -o perf.data python -Xperf_jit my_script.py
@end example

Different compilation flags can significantly impact stack sizes:


@itemize -

@item 
Builds with @code{-O0} typically have much larger stack frames than those with @code{-O1} or higher

@item 
Adding optimizations (@code{-O1}, @code{-O2}, etc.) typically reduces stack size

@item 
Frame pointers (@code{-fno-omit-frame-pointer}) generally provide more reliable stack unwinding
@end itemize
@end quotation
@end cartouche

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Annotations Best Practices,Isolating Extension Modules,Python support for the perf map compatible profilers,Python HOWTOs
@anchor{howto/annotations doc}@anchor{5bde}@anchor{howto/annotations annotations-best-practices}@anchor{5bdf}@anchor{howto/annotations annotations-howto}@anchor{bb6}@anchor{howto/annotations translation-repo}@anchor{5be0}
@section Annotations Best Practices


@*author: 
Larry Hastings


@subsubheading Abstract



This document is designed to encapsulate the best practices
for working with annotations dicts.  If you write Python code
that examines @code{__annotations__} on Python objects, we
encourage you to follow the guidelines described below.

The document is organized into four sections:
best practices for accessing the annotations of an object
in Python versions 3.10 and newer,
best practices for accessing the annotations of an object
in Python versions 3.9 and older,
other best practices
for @code{__annotations__} that apply to any Python version,
and
quirks of @code{__annotations__}.

Note that this document is specifically about working with
@code{__annotations__}, not uses `for' annotations.
If you’re looking for information on how to use «type hints»
in your code, please see the @ref{10d,,typing} module.

@menu
* Accessing The Annotations Dict Of An Object In Python 3.10 And Newer: Accessing The Annotations Dict Of An Object In Python 3 10 And Newer. 
* Accessing The Annotations Dict Of An Object In Python 3.9 And Older: Accessing The Annotations Dict Of An Object In Python 3 9 And Older. 
* Manually Un-Stringizing Stringized Annotations:: 
* Best Practices For __annotations__ In Any Python Version:: 
* __annotations__ Quirks:: 

@end menu

@node Accessing The Annotations Dict Of An Object In Python 3 10 And Newer,Accessing The Annotations Dict Of An Object In Python 3 9 And Older,,Annotations Best Practices
@anchor{howto/annotations accessing-the-annotations-dict-of-an-object-in-python-3-10-and-newer}@anchor{5be1}
@subsection Accessing The Annotations Dict Of An Object In Python 3.10 And Newer


Python 3.10 adds a new function to the standard library:
@ref{bec,,inspect.get_annotations()}.  In Python versions 3.10
through 3.13, calling this function is the best practice for
accessing the annotations dict of any object that supports
annotations.  This function can also «un-stringize»
stringized annotations for you.

In Python 3.14, there is a new @ref{6,,annotationlib} module
with functionality for working with annotations. This
includes a @ref{66c,,annotationlib.get_annotations()} function,
which supersedes @ref{bec,,inspect.get_annotations()}.

If for some reason @ref{bec,,inspect.get_annotations()} isn’t
viable for your use case, you may access the
@code{__annotations__} data member manually.  Best practice
for this changed in Python 3.10 as well: as of Python 3.10,
@code{o.__annotations__} is guaranteed to `always' work
on Python functions, classes, and modules.  If you’re
certain the object you’re examining is one of these three
`specific' objects, you may simply use @code{o.__annotations__}
to get at the object’s annotations dict.

However, other types of callables–for example,
callables created by @ref{4a6,,functools.partial()}–may
not have an @code{__annotations__} attribute defined.  When
accessing the @code{__annotations__} of a possibly unknown
object,  best practice in Python versions 3.10 and
newer is to call @ref{f8f,,getattr()} with three arguments,
for example @code{getattr(o, '__annotations__', None)}.

Before Python 3.10, accessing @code{__annotations__} on a class that
defines no annotations but that has a parent class with
annotations would return the parent’s @code{__annotations__}.
In Python 3.10 and newer, the child class’s annotations
will be an empty dict instead.

@node Accessing The Annotations Dict Of An Object In Python 3 9 And Older,Manually Un-Stringizing Stringized Annotations,Accessing The Annotations Dict Of An Object In Python 3 10 And Newer,Annotations Best Practices
@anchor{howto/annotations accessing-the-annotations-dict-of-an-object-in-python-3-9-and-older}@anchor{5be2}
@subsection Accessing The Annotations Dict Of An Object In Python 3.9 And Older


In Python 3.9 and older, accessing the annotations dict
of an object is much more complicated than in newer versions.
The problem is a design flaw in these older versions of Python,
specifically to do with class annotations.

Best practice for accessing the annotations dict of other
objects–functions, other callables, and modules–is the same
as best practice for 3.10, assuming you aren’t calling
@ref{bec,,inspect.get_annotations()}: you should use three-argument
@ref{f8f,,getattr()} to access the object’s @code{__annotations__}
attribute.

Unfortunately, this isn’t best practice for classes.  The problem
is that, since @code{__annotations__} is optional on classes, and
because classes can inherit attributes from their base classes,
accessing the @code{__annotations__} attribute of a class may
inadvertently return the annotations dict of a `base class.'
As an example:

@example
class Base:
    a: int = 3
    b: str = 'abc'

class Derived(Base):
    pass

print(Derived.__annotations__)
@end example

This will print the annotations dict from @code{Base}, not
@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{101b,,__dict__} dictionary.  Since
the class may or may not have annotations defined, best practice
is to call the @ref{2223,,get()} method on the class dict.

To put it all together, here is some sample code that safely
accesses the @code{__annotations__} attribute on an arbitrary
object in Python 3.9 and before:

@example
if isinstance(o, type):
    ann = o.__dict__.get('__annotations__', None)
else:
    ann = getattr(o, '__annotations__', None)
@end example

After running this code, @code{ann} should be either a
dictionary or @code{None}.  You’re encouraged to double-check
the type of @code{ann} using @ref{2ef,,isinstance()} before further
examination.

Note that some exotic or malformed type objects may not have
a @ref{101b,,__dict__} attribute, so for extra safety you may also wish
to use @ref{f8f,,getattr()} to access @code{__dict__}.

@node Manually Un-Stringizing Stringized Annotations,Best Practices For __annotations__ In Any Python Version,Accessing The Annotations Dict Of An Object In Python 3 9 And Older,Annotations Best Practices
@anchor{howto/annotations manually-un-stringizing-stringized-annotations}@anchor{5be3}
@subsection Manually Un-Stringizing Stringized Annotations


In situations where some annotations may be «stringized»,
and you wish to evaluate those strings to produce the
Python values they represent, it really is best to
call @ref{bec,,inspect.get_annotations()} to do this work
for you.

If you’re using Python 3.9 or older, or if for some reason
you can’t use @ref{bec,,inspect.get_annotations()}, you’ll need
to duplicate its logic.  You’re encouraged to examine the
implementation of @code{inspect.get_annotations()} in the
current Python version and follow a similar approach.

In a nutshell, if you wish to evaluate a stringized annotation
on an arbitrary object @code{o}:


@itemize *

@item 
If @code{o} is a module, use @code{o.__dict__} as the
@code{globals} when calling @ref{184,,eval()}.

@item 
If @code{o} is a class, use @code{sys.modules[o.__module__].__dict__}
as the @code{globals}, and @code{dict(vars(o))} as the @code{locals},
when calling @ref{184,,eval()}.

@item 
If @code{o} is a wrapped callable using @ref{13cb,,functools.update_wrapper()},
@ref{1307,,functools.wraps()}, or @ref{4a6,,functools.partial()}, iteratively
unwrap it by accessing either @code{o.__wrapped__} or @code{o.func} as
appropriate, until you have found the root unwrapped function.

@item 
If @code{o} is a callable (but not a class), use
@ref{1678,,o.__globals__} as the globals when calling
@ref{184,,eval()}.
@end itemize

However, not all string values used as annotations can
be successfully turned into Python values by @ref{184,,eval()}.
String values could theoretically contain any valid string,
and in practice there are valid use cases for type hints that
require annotating with string values that specifically
`can’t' be evaluated.  For example:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/} union types using @code{|}, before support for this
was added to Python 3.10.

@item 
Definitions that aren’t needed at runtime, only imported
when @ref{10b0,,typing.TYPE_CHECKING} is true.
@end itemize

If @ref{184,,eval()} attempts to evaluate such values, it will
fail and raise an exception.  So, when designing a library
API that works with annotations, it’s recommended to only
attempt to evaluate string values when explicitly requested
to by the caller.

@node Best Practices For __annotations__ In Any Python Version,__annotations__ Quirks,Manually Un-Stringizing Stringized Annotations,Annotations Best Practices
@anchor{howto/annotations best-practices-for-annotations-in-any-python-version}@anchor{5be4}
@subsection Best Practices For @code{__annotations__} In Any Python Version



@itemize *

@item 
You should avoid assigning to the @code{__annotations__} member
of objects directly.  Let Python manage setting @code{__annotations__}.

@item 
If you do assign directly to the @code{__annotations__} member
of an object, you should always set it to a @code{dict} object.

@item 
You should avoid accessing @code{__annotations__} directly on any object.
Instead, use @ref{66c,,annotationlib.get_annotations()} (Python 3.14+)
or @ref{bec,,inspect.get_annotations()} (Python 3.10+).

@item 
If you do directly access the @code{__annotations__} member
of an object, you should ensure that it’s a
dictionary before attempting to examine its contents.

@item 
You should avoid modifying @code{__annotations__} dicts.

@item 
You should avoid deleting the @code{__annotations__} attribute
of an object.
@end itemize

@node __annotations__ Quirks,,Best Practices For __annotations__ In Any Python Version,Annotations Best Practices
@anchor{howto/annotations annotations-quirks}@anchor{5be5}
@subsection @code{__annotations__} Quirks


In all versions of Python 3, function
objects lazy-create an annotations dict if no annotations
are defined on that object.  You can delete the @code{__annotations__}
attribute using @code{del fn.__annotations__}, but if you then
access @code{fn.__annotations__} the object will create a new empty dict
that it will store and return as its annotations.  Deleting the
annotations on a function before it has lazily created its annotations
dict will throw an @code{AttributeError}; using @code{del fn.__annotations__}
twice in a row is guaranteed to always throw an @code{AttributeError}.

Everything in the above paragraph also applies to class and module
objects in Python 3.10 and newer.

In all versions of Python 3, you can set @code{__annotations__}
on a function object to @code{None}.  However, subsequently
accessing the annotations on that object using @code{fn.__annotations__}
will lazy-create an empty dictionary as per the first paragraph of
this section.  This is `not' true of modules and classes, in any Python
version; those objects permit setting @code{__annotations__} to any
Python value, and will retain whatever value is set.

If Python stringizes your annotations for you
(using @code{from __future__ import annotations}), and you
specify a string as an annotation, the string will
itself be quoted.  In effect the annotation is quoted
`twice.'  For example:

@example
from __future__ import annotations
def foo(a: "str"): pass

print(foo.__annotations__)
@end example

This prints @code{@{'a': "'str'"@}}.  This shouldn’t really be considered
a «quirk»; it’s mentioned here simply because it might be surprising.

If you use a class with a custom metaclass and access @code{__annotations__}
on the class, you may observe unexpected behavior; see
@geindex Python Enhancement Proposals; PEP 749#pep749-metaclasses
749@footnote{https://peps.python.org/pep-0749/#pep749-metaclasses} for some examples. You can avoid these
quirks by using @ref{66c,,annotationlib.get_annotations()} on Python 3.14+ or
@ref{bec,,inspect.get_annotations()} on Python 3.10+. On earlier versions of
Python, you can avoid these bugs by accessing the annotations from the
class’s @ref{101b,,__dict__}
(for example, @code{cls.__dict__.get('__annotations__', None)}).

In some versions of Python, instances of classes may have an @code{__annotations__}
attribute. However, this is not supported functionality. If you need the
annotations of an instance, you can use @ref{186,,type()} to access its class
(for example, @code{annotationlib.get_annotations(type(myinstance))} on Python 3.14+).

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Isolating Extension Modules,timer file descriptor HOWTO,Annotations Best Practices,Python HOWTOs
@anchor{howto/isolating-extensions doc}@anchor{5be6}@anchor{howto/isolating-extensions isolating-extension-modules}@anchor{5be7}@anchor{howto/isolating-extensions isolating-extensions-howto}@anchor{412}@anchor{howto/isolating-extensions translation-repo}@anchor{5be8}
@section Isolating Extension Modules


@subsubheading Abstract



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{5be9}
@subsection Who should read this


This guide is written for maintainers of @ref{21ab,,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{5bea}
@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{5477,,Py_InitializeEx()}/@ref{10cf,,Py_FinalizeEx()}
cycles, and

@item 
in parallel, managing «sub-interpreters» using
@ref{1d2f,,Py_NewInterpreter()}/@ref{1a6f,,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{5beb}
@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{19b,,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{5bec}
@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{5bed,,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{5bee}
@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{5bec,,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{5bef}
@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{5bed}
@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{555e,,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{5bf0}
@subsubsection Managing Per-Module State


To use per-module state, use
@ref{555b,,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{1d8d,,field_size_limit})
which the C code needs to function.

@cartouche
@quotation Σημείωση 
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 isolating-extensions-optout}@anchor{555e}@anchor{howto/isolating-extensions opt-out-limiting-to-one-module-object-per-process}@anchor{5bf1}
@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
// A process-wide flag
static int loaded = 0;

// Mutex to provide thread safety (only needed for free-threaded Python)
static PyMutex modinit_mutex = @{0@};

static int
exec_module(PyObject* module)
@{
    PyMutex_Lock(&modinit_mutex);
    if (loaded) @{
        PyMutex_Unlock(&modinit_mutex);
        PyErr_SetString(PyExc_ImportError,
                        "cannot load module more than once per process");
        return -1;
    @}
    loaded = 1;
    PyMutex_Unlock(&modinit_mutex);
    // ... rest of initialization
@}
@end example

If your module’s @ref{d43,,PyModuleDef.m_clear} function is able to prepare
for future re-initialization, it should clear the @code{loaded} flag.
In this case, your module won’t support multiple instances existing
`concurrently', but it will, for example, support being loaded after
Python runtime shutdown (@ref{10cf,,Py_FinalizeEx()}) and re-initialization
(@ref{673,,Py_Initialize()}).

@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{5bf2}
@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 Σημείωση 
@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{5bf3}
@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}.

`Λεπτομέρεια υλοποίησης 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{5bf4}
@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{5fb,,Py_TPFLAGS_IMMUTABLETYPE} flag to prevent mutability.

@item 
Heap types inherit @ref{981,,tp_new} by default,
so it may become possible to instantiate them from Python code.
You can prevent this with the @ref{984,,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{5bf5}
@subsubsection Defining Heap Types


Heap types can be created by filling a @ref{1c8f,,PyType_Spec} structure, a
description or «blueprint» of a class, and calling
@ref{390,,PyType_FromModuleAndSpec()} to construct a new class object.

@cartouche
@quotation Σημείωση 
Other functions, like @ref{38e,,PyType_FromSpec()}, can also create
heap types, but @ref{390,,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{5bf6}
@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{39e,,Py_TPFLAGS_HAVE_GC} flag.

@item 
Define a traverse function using @ref{54e6,,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{39e,,Py_TPFLAGS_HAVE_GC} and @ref{36b,,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{5bf7}
@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{5ae,,Py_Version} was only added in Python 3.11.
As a replacement, use:


@itemize *

@item 
@ref{5af,,PY_VERSION_HEX}, if not using the stable ABI, or

@item 
@ref{2fc,,sys.version_info} (via @ref{356,,PySys_GetObject()} and
@ref{3b1,,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{5bf8}
@subsubsection Delegating @code{tp_traverse}


If your traverse function delegates to the @ref{36b,,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{981,,tp_new} and @ref{51f7,,tp_clear}.

@node Defining tp_dealloc,Not overriding tp_free,Delegating tp_traverse,Garbage-Collection Protocol
@anchor{howto/isolating-extensions defining-tp-dealloc}@anchor{5bf9}
@subsubsection Defining @code{tp_dealloc}


If your type has a custom @ref{51d3,,tp_dealloc} function,
it needs to:


@itemize -

@item 
call @ref{18a7,,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{5bfa}
@subsubsection Not overriding @code{tp_free}


The @ref{51e5,,tp_free} slot of a heap type must be set to
@ref{18a5,,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{5bfb}
@subsubsection Avoiding @code{PyObject_New}


GC-tracked objects need to be allocated using GC-aware functions.

If you use @ref{d4d,,PyObject_New()} or @ref{d4e,,PyObject_NewVar()}:


@itemize -

@item 
Get and call type’s @ref{51e6,,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{e68,,PyObject_GC_New()} or @ref{e69,,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{5bfc}
@subsubsection Module State Access from Classes


If you have a type object defined with @ref{390,,PyType_FromModuleAndSpec()},
you can call @ref{d37,,PyType_GetModule()} to get the associated module, and then
@ref{d48,,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{d38,,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{5bfd}
@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 Σημείωση 
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{1c11,,METH_METHOD | METH_FASTCALL | METH_KEYWORDS}
@ref{1879,,calling convention}
and the corresponding @ref{b46,,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{d38,,PyType_GetModuleState()} to get
the state of its associated module.

For example:

@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{5bfe}
@subsubsection Module State Access from Slot Methods, Getters and Setters


@cartouche
@quotation Σημείωση 
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{5645,,nb_add} for @ref{25d2,,__add__} or
@ref{981,,tp_new} for initialization—have a very simple API that
doesn’t allow passing in the defining class, unlike with @ref{b46,,PyCMethod}.
The same goes for getters and setters defined with
@ref{f77,,PyGetSetDef}.

To access the module state in these cases, use the
@ref{827,,PyType_GetModuleByDef()} function, and pass in the module definition.
Once you have the module, call @ref{d48,,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{2784,,method resolution order} (i.e. all superclasses) for the first
superclass that has a corresponding module.

@cartouche
@quotation Σημείωση 
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{5bff}
@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{390,,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{5c00}
@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 discuss forum under c-api tag@footnote{https://discuss.python.org/c/core-dev/c-api/30}.

@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{5c01}
@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{5c02}
@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.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node timer file descriptor HOWTO,The Python 2 3 Method Resolution Order,Isolating Extension Modules,Python HOWTOs
@anchor{howto/timerfd doc}@anchor{5c03}@anchor{howto/timerfd timer-file-descriptor-howto}@anchor{5c04}@anchor{howto/timerfd timerfd-howto}@anchor{5c05}@anchor{howto/timerfd translation-repo}@anchor{5c06}
@section timer file descriptor HOWTO


@*Release: 
1.13


This HOWTO discusses Python’s support for the linux timer file descriptor.

@menu
* Examples: Examples<35>. 

@end menu

@node Examples<35>,,,timer file descriptor HOWTO
@anchor{howto/timerfd examples}@anchor{5c07}
@subsection Examples


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{327,,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{133d,,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{1159,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node The Python 2 3 Method Resolution Order,Python support for free threading,timer file descriptor HOWTO,Python HOWTOs
@anchor{howto/mro doc}@anchor{5c08}@anchor{howto/mro python-2-3-mro}@anchor{184c}@anchor{howto/mro the-python-2-3-method-resolution-order}@anchor{5c09}@anchor{howto/mro translation-repo}@anchor{5c0a}
@section The Python 2.3 Method Resolution Order


@cartouche
@quotation Σημείωση 
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/}.

@*Abstract: 
`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:: 
* Examples: Examples<36>. 
* 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{5c0b}
@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,Examples<36>,The beginning,The Python 2 3 Method Resolution Order
@anchor{howto/mro the-c3-method-resolution-order}@anchor{5c0c}
@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 Examples<36>,Bad Method Resolution Orders,The C3 Method Resolution Order,The Python 2 3 Method Resolution Order
@anchor{howto/mro examples}@anchor{5c0d}
@subsection Examples


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{256b,,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,Examples<36>,The Python 2 3 Method Resolution Order
@anchor{howto/mro bad-method-resolution-orders}@anchor{5c0e}
@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.remember2buy' 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{5c0f}
@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{5c10}
@subsection Resources


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python support for free threading,C API Extension Support for Free Threading,The Python 2 3 Method Resolution Order,Python HOWTOs
@anchor{howto/free-threading-python doc}@anchor{5c11}@anchor{howto/free-threading-python freethreading-python-howto}@anchor{2919}@anchor{howto/free-threading-python python-support-for-free-threading}@anchor{5c12}@anchor{howto/free-threading-python translation-repo}@anchor{5c13}
@section Python support for free threading


Starting with the 3.13 release, CPython has support for a build of
Python called @ref{487,,free threading} where the @ref{685,,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.

Some third-party packages, in particular ones
with an @ref{2442,,extension module}, may not be ready for use in a
free-threaded build, and will re-enable the @ref{411,,GIL}.

This document describes the implications of free threading
for Python code.  See @ref{5c14,,C API Extension Support for Free Threading} for information on
how to write C extensions that support the free-threaded build.


@subsubheading Δείτε επίσης


@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:: 
* Behavioral changes:: 

@end menu

@node Installation,Identifying free-threaded Python,,Python support for free threading
@anchor{howto/free-threading-python installation}@anchor{5c15}
@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{6a5,,--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 support for free threading
@anchor{howto/free-threading-python identifying-free-threaded-python}@anchor{5c16}
@subsection Identifying free-threaded Python


To check if the current interpreter supports free-threading, @ref{6a7,,python -VV}
and @ref{6a8,,sys.version} contain «free-threading build».
The new @ref{4c09,,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 support for free threading
@anchor{howto/free-threading-python the-global-interpreter-lock-in-free-threaded-python}@anchor{5c17}
@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 μεταβλητή περιβάλλοντος; PYTHON_GIL
@ref{6a6,,PYTHON_GIL} or
the command-line option @ref{178,,-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 support for free threading
@anchor{howto/free-threading-python thread-safety}@anchor{5c18}
@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{188,,dict}, @ref{4d9,,list}, and @ref{42b,,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 Σημείωση 
It’s recommended to use the @ref{1a10,,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,Behavioral changes,Thread safety,Python support for free threading
@anchor{howto/free-threading-python known-limitations}@anchor{5c19}
@subsection Known limitations


This section describes known limitations of the free-threaded CPython build.

@menu
* Immortalization:: 
* Frame objects: Frame objects<2>. 
* Iterators: Iterators<2>. 
* Single-threaded performance:: 

@end menu

@node Immortalization,Frame objects<2>,,Known limitations
@anchor{howto/free-threading-python immortalization}@anchor{5c1a}
@subsubsection Immortalization


In the free-threaded build, some objects are @ref{398,,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.

As of the 3.14 release, immortalization is limited to:


@itemize *

@item 
Code constants: numeric literals, string literals, and tuple literals
composed of other constants.

@item 
Strings interned by @ref{1680,,sys.intern()}.
@end itemize

@node Frame objects<2>,Iterators<2>,Immortalization,Known limitations
@anchor{howto/free-threading-python frame-objects}@anchor{5c1b}
@subsubsection Frame objects


It is not safe to access @ref{28d,,frame.f_locals} from a @ref{acd,,frame}
object if that frame is currently executing in another thread, and doing so may
crash the interpreter.

@node Iterators<2>,Single-threaded performance,Frame objects<2>,Known limitations
@anchor{howto/free-threading-python iterators}@anchor{5c1c}
@subsubsection Iterators


It is generally not thread-safe to access the same iterator object from
multiple threads concurrently, and threads may see duplicate or missing
elements.

@node Single-threaded performance,,Iterators<2>,Known limitations
@anchor{howto/free-threading-python single-threaded-performance}@anchor{5c1d}
@subsubsection Single-threaded performance


The free-threaded build has additional overhead when executing Python code
compared to the default GIL-enabled build.  The amount of overhead depends
on the workload and hardware.  On the pyperformance benchmark suite, the
average overhead ranges from about 1% on macOS aarch64 to 8% on x86-64 Linux
systems.

@node Behavioral changes,,Known limitations,Python support for free threading
@anchor{howto/free-threading-python behavioral-changes}@anchor{5c1e}
@subsection Behavioral changes


This section describes CPython behavioural changes with the free-threaded
build.

@menu
* Context variables:: 
* Warning filters:: 

@end menu

@node Context variables,Warning filters,,Behavioral changes
@anchor{howto/free-threading-python context-variables}@anchor{5c1f}
@subsubsection Context variables


In the free-threaded build, the flag @ref{41f,,thread_inherit_context}
is set to true by default which causes threads created with
@ref{420,,threading.Thread} to start with a copy of the
@ref{421,,Context()} of the caller of
@ref{422,,start()}.  In the default GIL-enabled build, the flag
defaults to false so threads start with an
empty @code{Context()}.

@node Warning filters,,Context variables,Behavioral changes
@anchor{howto/free-threading-python warning-filters}@anchor{5c20}
@subsubsection Warning filters


In the free-threaded build, the flag @ref{42f,,context_aware_warnings}
is set to true by default.  In the default GIL-enabled build, the flag defaults
to false.  If the flag is true then the @ref{423,,warnings.catch_warnings}
context manager uses a context variable for warning filters.  If the flag is
false then @code{catch_warnings} modifies the global filters list,
which is not thread-safe.  See the @ref{11b,,warnings} module for more details.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node C API Extension Support for Free Threading,Remote debugging attachment protocol,Python support for free threading,Python HOWTOs
@anchor{howto/free-threading-extensions doc}@anchor{5c21}@anchor{howto/free-threading-extensions c-api-extension-support-for-free-threading}@anchor{5c22}@anchor{howto/free-threading-extensions freethreading-extensions-howto}@anchor{5c14}@anchor{howto/free-threading-extensions translation-repo}@anchor{5c23}
@section C API Extension Support for Free Threading


Starting with the 3.13 release, CPython has support for running with
the @ref{685,,global interpreter lock} (GIL) disabled in a configuration
called @ref{487,,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:: 
* Critical Sections:: 
* 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{5c24}
@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

@cartouche
@quotation Σημείωση 
On Windows, this macro is not defined automatically, but must be specified
to the compiler when building. The @ref{41e,,sysconfig.get_config_var()} function
can be used to determine whether the current running interpreter had the
macro defined.
@end quotation
@end cartouche

@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{5c25}
@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{5c26}
@subsubsection Multi-Phase Initialization


Extensions that use @ref{555b,,multi-phase initialization}
(functions like @ref{538c,,PyModuleDef_Init()},
@ref{19c,,PyModExport_*} export hook,
@ref{38c,,PyModule_FromSlotsAndSpec()}) should add a
@ref{691,,Py_mod_gil} slot in the module definition.
If your extension supports older versions of CPython,
you should guard the slot with a @ref{5af,,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@}
@};
@end example

@node Single-Phase Initialization,,Multi-Phase Initialization,Module Initialization
@anchor{howto/free-threading-extensions single-phase-initialization}@anchor{5c27}
@subsubsection Single-Phase Initialization


Extensions that use legacy @ref{555c,,single-phase initialization}
(that is, @ref{5562,,PyModule_Create()}) should call @ref{6a9,,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{5c28}
@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{5275,,PyList_GET_ITEM},
@ref{822,,PyList_SET_ITEM}, and macros like
@ref{5f6,,PySequence_Fast_GET_SIZE} that use the object returned by
@ref{1ac6,,PySequence_Fast()} 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{603,,borrowed references} may not be thread-safe if
the containing object is modified concurrently.  See the section on
@ref{5c29,,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{5c2a}
@subsubsection Container Thread Safety


Containers like @ref{2929,,PyListObject},
@ref{83e,,PyDictObject}, and @ref{5728,,PySetObject} perform internal locking
in the free-threaded build.  For example, the @ref{5371,,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{5c2b}@anchor{howto/free-threading-extensions pydict-next}@anchor{5c2c}
@subsubsection @code{PyDict_Next}


A notable exception is @ref{1b9c,,PyDict_Next()}, which does not lock the
dictionary.  You should use @ref{5469,,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{5c2d}
@subsection Borrowed References

@anchor{howto/free-threading-extensions id2}@anchor{5c29}
Some C API functions return @ref{603,,borrowed references}.
These APIs are not thread-safe if the containing object is modified
concurrently.  For example, it’s not safe to use @ref{7f5,,PyList_GetItem()}
if the list may be modified concurrently.

The following table lists some borrowed reference APIs and their replacements
that return @ref{7da,,strong references}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Borrowed reference API

@tab

Strong reference API

@item

@ref{7f5,,PyList_GetItem()}

@tab

@ref{7f4,,PyList_GetItemRef()}

@item

@ref{5275,,PyList_GET_ITEM()}

@tab

@ref{7f4,,PyList_GetItemRef()}

@item

@ref{81c,,PyDict_GetItem()}

@tab

@ref{7d8,,PyDict_GetItemRef()}

@item

@ref{7d9,,PyDict_GetItemWithError()}

@tab

@ref{7d8,,PyDict_GetItemRef()}

@item

@ref{81d,,PyDict_GetItemString()}

@tab

@ref{634,,PyDict_GetItemStringRef()}

@item

@ref{7dc,,PyDict_SetDefault()}

@tab

@ref{7db,,PyDict_SetDefaultRef()}

@item

@ref{1b9c,,PyDict_Next()}

@tab

none (see @ref{5c2c,,PyDict_Next})

@item

@code{PyWeakref_GetObject()}

@tab

@ref{3a4,,PyWeakref_GetRef()}

@item

@code{PyWeakref_GET_OBJECT()}

@tab

@ref{3a4,,PyWeakref_GetRef()}

@item

@ref{7f2,,PyImport_AddModule()}

@tab

@ref{7f1,,PyImport_AddModuleRef()}

@item

@ref{5769,,PyCell_GET()}

@tab

@ref{5768,,PyCell_Get()}

@end multitable


Not all APIs that return borrowed references are problematic.  For
example, @ref{51ce,,PyTuple_GetItem()} is safe because tuples are immutable.
Similarly, not all uses of the above APIs are problematic.  For example,
@ref{81c,,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{5944}@anchor{howto/free-threading-extensions memory-allocation-apis}@anchor{5c2e}
@subsection Memory Allocation APIs


Python’s memory management C API provides functions in three different
@ref{593f,,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 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.

@cartouche
@quotation Σημείωση 
Search for uses of @ref{1026,,PyObject_Malloc()} in your
extension and check that the allocated memory is used for Python objects.
Use @ref{1024,,PyMem_Malloc()} to allocate buffers instead of
@code{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{5c2f}
@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{53fd,,PyThreadState_Ensure()}, @ref{53fe,,PyThreadState_EnsureFromView()},
and @ref{5401,,PyThreadState_Release()}

@item 
@ref{1a5,,PyGILState_Ensure()} and @ref{1a6,,PyGILState_Release()}

@item 
@ref{838,,PyEval_SaveThread()} and @ref{839,,PyEval_RestoreThread()}

@item 
@ref{51d4,,Py_BEGIN_ALLOW_THREADS} and @ref{e4e,,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{411,,GIL} is disabled.  For example, if you
create a thread outside of Python, you must call @ref{53fd,,PyThreadState_Ensure()}
before calling into the Python API to ensure that the thread has a valid
Python thread state.

You should continue to call @ref{838,,PyEval_SaveThread()} or
@ref{51d4,,Py_BEGIN_ALLOW_THREADS} around blocking operations, such as I/O or
lock acquisitions, to allow other threads to run the
@ref{19de,,cyclic garbage collector}.

@node Protecting Internal Extension State,Critical Sections,Thread State and GIL APIs,C API Extension Support for Free Threading
@anchor{howto/free-threading-extensions protecting-internal-extension-state}@anchor{5c30}
@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 Critical Sections,Building Extensions for the Free-Threaded Build,Protecting Internal Extension State,C API Extension Support for Free Threading
@anchor{howto/free-threading-extensions critical-sections}@anchor{5c31}
@subsection Critical Sections

@anchor{howto/free-threading-extensions id3}@anchor{5c32}
In the free-threaded build, CPython provides a mechanism called «critical
sections» to protect data that would otherwise be protected by the GIL.
While extension authors may not interact with the internal critical section
implementation directly, understanding their behavior is crucial when using
certain C API functions or managing shared state in the free-threaded build.

@menu
* What Are Critical Sections?:: 
* Using Critical Sections:: 
* How Critical Sections Work:: 
* Deadlock Avoidance:: 
* Important Considerations:: 
* Per-Object Locks (ob_mutex): Per-Object Locks ob_mutex. 

@end menu

@node What Are Critical Sections?,Using Critical Sections,,Critical Sections
@anchor{howto/free-threading-extensions what-are-critical-sections}@anchor{5c33}
@subsubsection What Are Critical Sections?


Conceptually, critical sections act as a deadlock avoidance layer built on
top of simple mutexes. Each thread maintains a stack of active critical
sections. When a thread needs to acquire a lock associated with a critical
section (e.g., implicitly when calling a thread-safe C API function like
@ref{51d0,,PyDict_SetItem()}, or explicitly using macros), it attempts to acquire
the underlying mutex.

@node Using Critical Sections,How Critical Sections Work,What Are Critical Sections?,Critical Sections
@anchor{howto/free-threading-extensions using-critical-sections}@anchor{5c34}
@subsubsection Using Critical Sections


The primary APIs for using critical sections are:


@itemize *

@item 
@ref{5469,,Py_BEGIN_CRITICAL_SECTION} and @ref{546d,,Py_END_CRITICAL_SECTION} -
For locking a single object

@item 
@ref{546a,,Py_BEGIN_CRITICAL_SECTION2} and @ref{546e,,Py_END_CRITICAL_SECTION2}
- For locking two objects simultaneously
@end itemize

These macros must be used in matching pairs and must appear in the same C
scope, since they establish a new local scope.  These macros are no-ops in
non-free-threaded builds, so they can be safely added to code that needs to
support both build types.

A common use of a critical section would be to lock an object while accessing
an internal attribute of it.  For example, if an extension type has an internal
count field, you could use a critical section while reading or writing that
field:

@example
// read the count, returns new reference to internal count value
PyObject *result;
Py_BEGIN_CRITICAL_SECTION(obj);
result = Py_NewRef(obj->count);
Py_END_CRITICAL_SECTION();
return result;

// write the count, consumes reference from new_count
Py_BEGIN_CRITICAL_SECTION(obj);
obj->count = new_count;
Py_END_CRITICAL_SECTION();
@end example

@node How Critical Sections Work,Deadlock Avoidance,Using Critical Sections,Critical Sections
@anchor{howto/free-threading-extensions how-critical-sections-work}@anchor{5c35}
@subsubsection How Critical Sections Work


Unlike traditional locks, critical sections do not guarantee exclusive access
throughout their entire duration. If a thread would block while holding a
critical section (e.g., by acquiring another lock or performing I/O), the
critical section is temporarily suspended—all locks are released—and then
resumed when the blocking operation completes.

This behavior is similar to what happens with the GIL when a thread makes a
blocking call. The key differences are:


@itemize *

@item 
Critical sections operate on a per-object basis rather than globally

@item 
Critical sections follow a stack discipline within each thread (the «begin» and
«end» macros enforce this since they must be paired and within the same scope)

@item 
Critical sections automatically release and reacquire locks around potential
blocking operations
@end itemize

@node Deadlock Avoidance,Important Considerations,How Critical Sections Work,Critical Sections
@anchor{howto/free-threading-extensions deadlock-avoidance}@anchor{5c36}
@subsubsection Deadlock Avoidance


Critical sections help avoid deadlocks in two ways:


@enumerate 

@item 
If a thread tries to acquire a lock that’s already held by another thread,
it first suspends all of its active critical sections, temporarily releasing
their locks

@item 
When the blocking operation completes, only the top-most critical section is
reacquired first
@end enumerate

This means you cannot rely on nested critical sections to lock multiple objects
at once, as the inner critical section may suspend the outer ones. Instead, use
@ref{546a,,Py_BEGIN_CRITICAL_SECTION2} to lock two objects simultaneously.

Note that the locks described above are only @ref{693,,PyMutex} based locks.
The critical section implementation does not know about or affect other locking
mechanisms that might be in use, like POSIX mutexes.  Also note that while
blocking on any @code{PyMutex} causes the critical sections to be
suspended, only the mutexes that are part of the critical sections are
released.  If @code{PyMutex} is used without a critical section, it will
not be released and therefore does not get the same deadlock avoidance.

@node Important Considerations,Per-Object Locks ob_mutex,Deadlock Avoidance,Critical Sections
@anchor{howto/free-threading-extensions important-considerations}@anchor{5c37}
@subsubsection Important Considerations



@itemize *

@item 
Critical sections may temporarily release their locks, allowing other threads
to modify the protected data. Be careful about making assumptions about the
state of the data after operations that might block.

@item 
Because locks can be temporarily released (suspended), entering a critical
section does not guarantee exclusive access to the protected resource
throughout the section’s duration. If code within a critical section calls
another function that blocks (e.g., acquires another lock, performs blocking
I/O), all locks held by the thread via critical sections will be released.
This is similar to how the GIL can be released during blocking calls.

@item 
Only the lock(s) associated with the most recently entered (top-most)
critical section are guaranteed to be held at any given time. Locks for
outer, nested critical sections might have been suspended.

@item 
You can lock at most two objects simultaneously with these APIs. If you need
to lock more objects, you’ll need to restructure your code.

@item 
While critical sections will not deadlock if you attempt to lock the same
object twice, they are less efficient than purpose-built reentrant locks for
this use case.

@item 
When using @ref{546a,,Py_BEGIN_CRITICAL_SECTION2}, the order of the objects
doesn’t affect correctness (the implementation handles deadlock avoidance),
but it’s good practice to always lock objects in a consistent order.

@item 
Remember that the critical section macros are primarily for protecting access
to `Python objects' that might be involved in internal CPython operations
susceptible to the deadlock scenarios described above. For protecting purely
internal extension state, standard mutexes or other synchronization
primitives might be more appropriate.
@end itemize

@node Per-Object Locks ob_mutex,,Important Considerations,Critical Sections
@anchor{howto/free-threading-extensions per-object-locks}@anchor{597b}@anchor{howto/free-threading-extensions per-object-locks-ob-mutex}@anchor{5c38}
@subsubsection Per-Object Locks (@code{ob_mutex})


In the free-threaded build, each Python object contains a @ref{597a,,ob_mutex}
field of type @ref{693,,PyMutex}.  This mutex is `reserved for use by the
critical section API' (@ref{5469,,Py_BEGIN_CRITICAL_SECTION} /
@ref{546d,,Py_END_CRITICAL_SECTION}).

@cartouche
@quotation Προειδοποίηση 
Do `not' lock @code{ob_mutex} directly with @code{PyMutex_Lock(&obj->ob_mutex)}.
Mixing direct @code{PyMutex_Lock} calls with the critical section API on the
same mutex can cause deadlocks.
@end quotation
@end cartouche

Even if your own code never uses critical sections on a particular object type,
`CPython internals may use the critical section API on any Python object'.

If your extension type needs its own lock, add a separate @ref{693,,PyMutex}
field (or another synchronization primitive) to your object struct.
@code{PyMutex} is very lightweight, so there is negligible cost to having
an additional one.

@node Building Extensions for the Free-Threaded Build,,Critical Sections,C API Extension Support for Free Threading
@anchor{howto/free-threading-extensions building-extensions-for-the-free-threaded-build}@anchor{5c39}
@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.14t}.

@item 
pypa/cibuildwheel@footnote{https://github.com/pypa/cibuildwheel} supports
building wheels for the free-threaded build of Python 3.14 and newer.
@end itemize

@menu
* Limited C API and Stable ABI:: 
* Windows: Windows<84>. 

@end menu

@node Limited C API and Stable ABI,Windows<84>,,Building Extensions for the Free-Threaded Build
@anchor{howto/free-threading-extensions limited-c-api-and-stable-abi}@anchor{5c3a}
@subsubsection Limited C API and Stable ABI


The free-threaded build does not currently support the
@ref{829,,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 Σημείωση 
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<84>,,Limited C API and Stable ABI,Building Extensions for the Free-Threaded Build
@anchor{howto/free-threading-extensions windows}@anchor{5c3b}
@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 Δείτε επίσης


Porting Extension Modules to Support Free-Threading@footnote{https://py-free-threading.github.io/porting/}:
A community-maintained porting guide for extension authors.


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Remote debugging attachment protocol,Permission requirements,C API Extension Support for Free Threading,Python HOWTOs
@anchor{howto/remote_debugging doc}@anchor{5c3c}@anchor{howto/remote_debugging remote-debugging}@anchor{4c0b}@anchor{howto/remote_debugging remote-debugging-attachment-protocol}@anchor{5c3d}@anchor{howto/remote_debugging translation-repo}@anchor{5c3e}
@section Remote debugging attachment protocol


This protocol enables external tools to attach to a running CPython process and
execute Python code remotely.

Most platforms require elevated privileges to attach to another Python process.

@menu
* Disabling remote debugging:: 

@end menu

@node Disabling remote debugging,,,Remote debugging attachment protocol
@anchor{howto/remote_debugging disabling-remote-debugging}@anchor{5c3f}
@subsection Disabling remote debugging


To disable remote debugging support, use any of the following:


@itemize *

@item 
Set the 
@geindex PYTHON_DISABLE_REMOTE_DEBUG
@geindex μεταβλητή περιβάλλοντος; PYTHON_DISABLE_REMOTE_DEBUG
@ref{419,,PYTHON_DISABLE_REMOTE_DEBUG} environment variable to @code{1} before
starting the interpreter.

@item 
Use the @ref{178,,-X disable_remote_debug} command-line option.

@item 
Compile Python with the @ref{41a,,--without-remote-debug} build flag.
@end itemize

@node Permission requirements,Locating the PyRuntime structure,Remote debugging attachment protocol,Python HOWTOs
@anchor{howto/remote_debugging id1}@anchor{5c40}@anchor{howto/remote_debugging permission-requirements}@anchor{5c41}
@section Permission requirements


Attaching to a running Python process for remote debugging requires elevated
privileges on most platforms. The specific requirements and troubleshooting
steps depend on your operating system:

@subsubheading Linux


The tracer process must have the @code{CAP_SYS_PTRACE} capability or equivalent
privileges. You can only trace processes you own and can signal. Tracing may
fail if the process is already being traced, or if it is running with
set-user-ID or set-group-ID. Security modules like Yama may further restrict
tracing.

To temporarily relax ptrace restrictions (until reboot), run:

@quotation

@code{echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope}
@end quotation

@cartouche
@quotation Σημείωση 
Disabling @code{ptrace_scope} reduces system hardening and should only be done
in trusted environments.
@end quotation
@end cartouche

If running inside a container, use @code{--cap-add=SYS_PTRACE} or
@code{--privileged}, and run as root if needed.

Try re-running the command with elevated privileges:

@quotation

@code{sudo -E !!}
@end quotation

@subsubheading macOS


To attach to another process, you typically need to run your debugging tool
with elevated privileges. This can be done by using @code{sudo} or running as
root.

Even when attaching to processes you own, macOS may block debugging unless
the debugger is run with root privileges due to system security restrictions.

@subsubheading Windows


To attach to another process, you usually need to run your debugging tool
with administrative privileges. Start the command prompt or terminal as
Administrator.

Some processes may still be inaccessible even with Administrator rights,
unless you have the @code{SeDebugPrivilege} privilege enabled.

To resolve file or folder access issues, adjust the security permissions:

@quotation


@enumerate 

@item 
Right-click the file or folder and select `Properties'.

@item 
Go to the `Security' tab to view users and groups with access.

@item 
Click `Edit' to modify permissions.

@item 
Select your user account.

@item 
In `Permissions', check `Read' or `Full control' as needed.

@item 
Click `Apply', then `OK' to confirm.
@end enumerate
@end quotation

@cartouche
@quotation Σημείωση 
Ensure you’ve satisfied all @ref{5c41,,Permission requirements} before proceeding.
@end quotation
@end cartouche

This section describes the low-level protocol that enables external tools to
inject and execute a Python script within a running CPython process.

This mechanism forms the basis of the @ref{418,,sys.remote_exec()} function, which
instructs a remote Python process to execute a @code{.py} file. However, this
section does not document the usage of that function. Instead, it provides a
detailed explanation of the underlying protocol, which takes as input the
@code{pid} of a target Python process and the path to a Python source file to be
executed. This information supports independent reimplementation of the
protocol, regardless of programming language.

@cartouche
@quotation Προειδοποίηση 
The execution of the injected script depends on the interpreter reaching a
safe evaluation point. As a result, execution may be delayed depending on
the runtime state of the target process.
@end quotation
@end cartouche

Once injected, the script is executed by the interpreter within the target
process the next time a safe evaluation point is reached. This approach enables
remote execution capabilities without modifying the behavior or structure of
the running Python application.

Subsequent sections provide a step-by-step description of the protocol,
including techniques for locating interpreter structures in memory, safely
accessing internal fields, and triggering code execution. Platform-specific
variations are noted where applicable, and example implementations are included
to clarify each operation.

@node Locating the PyRuntime structure,Reading _Py_DebugOffsets,Permission requirements,Python HOWTOs
@anchor{howto/remote_debugging locating-the-pyruntime-structure}@anchor{5c42}
@section Locating the PyRuntime structure


CPython places the @code{PyRuntime} structure in a dedicated binary section to
help external tools find it at runtime. The name and format of this section
vary by platform. For example, @code{.PyRuntime} is used on ELF systems, and
@code{__DATA,__PyRuntime} is used on macOS. Tools can find the offset of this
structure by examining the binary on disk.

The @code{PyRuntime} structure contains CPython’s global interpreter state and
provides access to other internal data, including the list of interpreters,
thread states, and debugger support fields.

To work with a remote Python process, a debugger must first find the memory
address of the @code{PyRuntime} structure in the target process. This address
can’t be hardcoded or calculated from a symbol name, because it depends on
where the operating system loaded the binary.

The method for finding @code{PyRuntime} depends on the platform, but the steps are
the same in general:


@enumerate 

@item 
Find the base address where the Python binary or shared library was loaded
in the target process.

@item 
Use the on-disk binary to locate the offset of the @code{.PyRuntime} section.

@item 
Add the section offset to the base address to compute the address in memory.
@end enumerate

The sections below explain how to do this on each supported platform and
include example code.

@subsubheading Linux (ELF)


To find the @code{PyRuntime} structure on Linux:


@enumerate 

@item 
Read the process’s memory map (for example, @code{/proc/<pid>/maps}) to find
the address where the Python executable or @code{libpython} was loaded.

@item 
Parse the ELF section headers in the binary to get the offset of the
@code{.PyRuntime} section.

@item 
Add that offset to the base address from step 1 to get the memory address of
@code{PyRuntime}.
@end enumerate

The following is an example implementation:

@example
def find_py_runtime_linux(pid: int) -> int:
    # Step 1: Try to find the Python executable in memory
    binary_path, base_address = find_mapped_binary(
        pid, name_contains="python"
    )

    # Step 2: Fallback to shared library if executable is not found
    if binary_path is None:
        binary_path, base_address = find_mapped_binary(
            pid, name_contains="libpython"
        )

    # Step 3: Parse ELF headers to get .PyRuntime section offset
    section_offset = parse_elf_section_offset(
        binary_path, ".PyRuntime"
    )

    # Step 4: Compute PyRuntime address in memory
    return base_address + section_offset
@end example

On Linux systems, there are two main approaches to read memory from another
process. The first is through the @code{/proc} filesystem, specifically by reading from
@code{/proc/[pid]/mem} which provides direct access to the process’s memory. This
requires appropriate permissions - either being the same user as the target
process or having root access. The second approach is using the
@code{process_vm_readv()} system call which provides a more efficient way to copy
memory between processes. While ptrace’s @code{PTRACE_PEEKTEXT} operation can also be
used to read memory, it is significantly slower as it only reads one word at a
time and requires multiple context switches between the tracer and tracee
processes.

For parsing ELF sections, the process involves reading and interpreting the ELF
file format structures from the binary file on disk. The ELF header contains a
pointer to the section header table. Each section header contains metadata about
a section including its name (stored in a separate string table), offset, and
size. To find a specific section like .PyRuntime, you need to walk through these
headers and match the section name. The section header then provides the offset
where that section exists in the file, which can be used to calculate its
runtime address when the binary is loaded into memory.

You can read more about the ELF file format in the ELF specification@footnote{https://en.wikipedia.org/wiki/Executable_and_Linkable_Format}.

@subsubheading macOS (Mach-O)


To find the @code{PyRuntime} structure on macOS:


@enumerate 

@item 
Call @code{task_for_pid()} to get the @code{mach_port_t} task port for the target
process. This handle is needed to read memory using APIs like
@code{mach_vm_read_overwrite} and @code{mach_vm_region}.

@item 
Scan the memory regions to find the one containing the Python executable or
@code{libpython}.

@item 
Load the binary file from disk and parse the Mach-O headers to find the
section named @code{PyRuntime} in the @code{__DATA} segment.  On macOS, symbol
names are automatically prefixed with an underscore, so the @code{PyRuntime}
symbol appears as @code{_PyRuntime} in the symbol table, but the section name
is not affected.
@end enumerate

The following is an example implementation:

@example
def find_py_runtime_macos(pid: int) -> int:
    # Step 1: Get access to the process's memory
    handle = get_memory_access_handle(pid)

    # Step 2: Try to find the Python executable in memory
    binary_path, base_address = find_mapped_binary(
        handle, name_contains="python"
    )

    # Step 3: Fallback to libpython if the executable is not found
    if binary_path is None:
        binary_path, base_address = find_mapped_binary(
            handle, name_contains="libpython"
        )

    # Step 4: Parse Mach-O headers to get __DATA,__PyRuntime section offset
    section_offset = parse_macho_section_offset(
        binary_path, "__DATA", "__PyRuntime"
    )

    # Step 5: Compute the PyRuntime address in memory
    return base_address + section_offset
@end example

On macOS, accessing another process’s memory requires using Mach-O specific APIs
and file formats. The first step is obtaining a @code{task_port} handle via
@code{task_for_pid()}, which provides access to the target process’s memory space.
This handle enables memory operations through APIs like
@code{mach_vm_read_overwrite()}.

The process memory can be examined using @code{mach_vm_region()} to scan through the
virtual memory space, while @code{proc_regionfilename()} helps identify which binary
files are loaded at each memory region. When the Python binary or library is
found, its Mach-O headers need to be parsed to locate the @code{PyRuntime} structure.

The Mach-O format organizes code and data into segments and sections. The
@code{PyRuntime} structure lives in a section named @code{__PyRuntime} within the
@code{__DATA} segment. The actual runtime address calculation involves finding the
@code{__TEXT} segment which serves as the binary’s base address, then locating the
@code{__DATA} segment containing our target section. The final address is computed by
combining the base address with the appropriate section offsets from the Mach-O
headers.

Note that accessing another process’s memory on macOS typically requires
elevated privileges - either root access or special security entitlements
granted to the debugging process.

@subsubheading Windows (PE)


To find the @code{PyRuntime} structure on Windows:


@enumerate 

@item 
Use the ToolHelp API to enumerate all modules loaded in the target process.
This is done using functions such as CreateToolhelp32Snapshot@footnote{https://learn.microsoft.com/en-us/windows/win32/api/tlhelp32/nf-tlhelp32-createtoolhelp32snapshot},
Module32First@footnote{https://learn.microsoft.com/en-us/windows/win32/api/tlhelp32/nf-tlhelp32-module32first},
and Module32Next@footnote{https://learn.microsoft.com/en-us/windows/win32/api/tlhelp32/nf-tlhelp32-module32next}.

@item 
Identify the module corresponding to @code{python.exe} or
@code{python`XY'.dll}, where @code{X} and @code{Y} are the major and minor
version numbers of the Python version, and record its base address.

@item 
Locate the @code{PyRuntim} section. Due to the PE format’s 8-character limit
on section names (defined as @code{IMAGE_SIZEOF_SHORT_NAME}), the original
name @code{PyRuntime} is truncated. This section contains the @code{PyRuntime}
structure.

@item 
Retrieve the section’s relative virtual address (RVA) and add it to the base
address of the module.
@end enumerate

The following is an example implementation:

@example
def find_py_runtime_windows(pid: int) -> int:
    # Step 1: Try to find the Python executable in memory
    binary_path, base_address = find_loaded_module(
        pid, name_contains="python"
    )

    # Step 2: Fallback to shared pythonXY.dll if the executable is not
    # found
    if binary_path is None:
        binary_path, base_address = find_loaded_module(
            pid, name_contains="python3"
        )

    # Step 3: Parse PE section headers to get the RVA of the PyRuntime
    # section. The section name appears as "PyRuntim" due to the
    # 8-character limit defined by the PE format (IMAGE_SIZEOF_SHORT_NAME).
    section_rva = parse_pe_section_offset(binary_path, "PyRuntim")

    # Step 4: Compute PyRuntime address in memory
    return base_address + section_rva
@end example

On Windows, accessing another process’s memory requires using the Windows API
functions like @code{CreateToolhelp32Snapshot()} and @code{Module32First()/Module32Next()}
to enumerate loaded modules. The @code{OpenProcess()} function provides a handle to
access the target process’s memory space, enabling memory operations through
@code{ReadProcessMemory()}.

The process memory can be examined by enumerating loaded modules to find the
Python binary or DLL. When found, its PE headers need to be parsed to locate the
@code{PyRuntime} structure.

The PE format organizes code and data into sections. The @code{PyRuntime} structure
lives in a section named «PyRuntim» (truncated from «PyRuntime» due to PE’s
8-character name limit). The actual runtime address calculation involves finding
the module’s base address from the module entry, then locating our target
section in the PE headers. The final address is computed by combining the base
address with the section’s virtual address from the PE section headers.

Note that accessing another process’s memory on Windows typically requires
appropriate privileges - either administrative access or the @code{SeDebugPrivilege}
privilege granted to the debugging process.

@node Reading _Py_DebugOffsets,Locating the interpreter and thread state,Locating the PyRuntime structure,Python HOWTOs
@anchor{howto/remote_debugging reading-py-debugoffsets}@anchor{5c43}
@section Reading _Py_DebugOffsets


Once the address of the @code{PyRuntime} structure has been determined, the next
step is to read the @code{_Py_DebugOffsets} structure located at the beginning of
the @code{PyRuntime} block.

This structure provides version-specific field offsets that are needed to
safely read interpreter and thread state memory. These offsets vary between
CPython versions and must be checked before use to ensure they are compatible.

To read and check the debug offsets, follow these steps:


@enumerate 

@item 
Read memory from the target process starting at the @code{PyRuntime} address,
covering the same number of bytes as the @code{_Py_DebugOffsets} structure.
This structure is located at the very start of the @code{PyRuntime} memory
block. Its layout is defined in CPython’s internal headers and stays the
same within a given minor version, but may change in major versions.

@item 
Check that the structure contains valid data:


@itemize -

@item 
The @code{cookie} field must match the expected debug marker.

@item 
The @code{version} field must match the version of the Python interpreter
used by the debugger.

@item 
If either the debugger or the target process is using a pre-release
version (for example, an alpha, beta, or release candidate), the versions
must match exactly.

@item 
The @code{free_threaded} field must have the same value in both the debugger
and the target process.
@end itemize

@item 
If the structure is valid, the offsets it contains can be used to locate
fields in memory. If any check fails, the debugger should stop the operation
to avoid reading memory in the wrong format.
@end enumerate

The following is an example implementation that reads and checks
@code{_Py_DebugOffsets}:

@example
def read_debug_offsets(pid: int, py_runtime_addr: int) -> DebugOffsets:
    # Step 1: Read memory from the target process at the PyRuntime address
    data = read_process_memory(
        pid, address=py_runtime_addr, size=DEBUG_OFFSETS_SIZE
    )

    # Step 2: Deserialize the raw bytes into a _Py_DebugOffsets structure
    debug_offsets = parse_debug_offsets(data)

    # Step 3: Validate the contents of the structure
    if debug_offsets.cookie != EXPECTED_COOKIE:
        raise RuntimeError("Invalid or missing debug cookie")
    if debug_offsets.version != LOCAL_PYTHON_VERSION:
        raise RuntimeError(
            "Mismatch between caller and target Python versions"
        )
    if debug_offsets.free_threaded != LOCAL_FREE_THREADED:
        raise RuntimeError("Mismatch in free-threaded configuration")

    return debug_offsets
@end example

@cartouche
@quotation Προειδοποίηση 
`Process suspension recommended'

To avoid race conditions and ensure memory consistency, it is strongly
recommended that the target process be suspended before performing any
operations that read or write internal interpreter state. The Python runtime
may concurrently mutate interpreter data structures—such as creating or
destroying threads—during normal execution. This can result in invalid
memory reads or writes.

A debugger may suspend execution by attaching to the process with @code{ptrace}
or by sending a @code{SIGSTOP} signal. Execution should only be resumed after
debugger-side memory operations are complete.

@cartouche
@quotation Σημείωση 
Some tools, such as profilers or sampling-based debuggers, may operate on
a running process without suspension. In such cases, tools must be
explicitly designed to handle partially updated or inconsistent memory.
For most debugger implementations, suspending the process remains the
safest and most robust approach.
@end quotation
@end cartouche
@end quotation
@end cartouche

@node Locating the interpreter and thread state,Writing control information,Reading _Py_DebugOffsets,Python HOWTOs
@anchor{howto/remote_debugging locating-the-interpreter-and-thread-state}@anchor{5c44}
@section Locating the interpreter and thread state


Before code can be injected and executed in a remote Python process, the
debugger must choose a thread in which to schedule execution. This is necessary
because the control fields used to perform remote code injection are located in
the @code{_PyRemoteDebuggerSupport} structure, which is embedded in a
@code{PyThreadState} object. These fields are modified by the debugger to request
execution of injected scripts.

The @code{PyThreadState} structure represents a thread running inside a Python
interpreter.  It maintains the thread’s evaluation context and contains the
fields required for debugger coordination.  Locating a valid @code{PyThreadState}
is therefore a key prerequisite for triggering execution remotely.

A thread is typically selected based on its role or ID. In most cases, the main
thread is used, but some tools may target a specific thread by its native
thread ID. Once the target thread is chosen, the debugger must locate both the
interpreter and the associated thread state structures in memory.

The relevant internal structures are defined as follows:


@itemize -

@item 
@code{PyInterpreterState} represents an isolated Python interpreter instance.
Each interpreter maintains its own set of imported modules, built-in state,
and thread state list. Although most Python applications use a single
interpreter, CPython supports multiple interpreters in the same process.

@item 
@code{PyThreadState} represents a thread running within an interpreter. It
contains execution state and the control fields used by the debugger.
@end itemize

To locate a thread:


@enumerate 

@item 
Use the offset @code{runtime_state.interpreters_head} to obtain the address of
the first interpreter in the @code{PyRuntime} structure. This is the entry point
to the linked list of active interpreters.

@item 
Use the offset @code{interpreter_state.threads_main} to access the main thread
state associated with the selected interpreter. This is typically the most
reliable thread to target.

@item 
Optionally, use the offset @code{interpreter_state.threads_head} to iterate
through the linked list of all thread states. Each @code{PyThreadState}
structure contains a @code{native_thread_id} field, which may be compared to
a target thread ID to find a specific thread.

@item 
Once a valid @code{PyThreadState} has been found, its address can be used in
later steps of the protocol, such as writing debugger control fields and
scheduling execution.
@end enumerate

The following is an example implementation that locates the main thread state:

@example
def find_main_thread_state(
    pid: int, py_runtime_addr: int, debug_offsets: DebugOffsets,
) -> int:
    # Step 1: Read interpreters_head from PyRuntime
    interp_head_ptr = (
        py_runtime_addr + debug_offsets.runtime_state.interpreters_head
    )
    interp_addr = read_pointer(pid, interp_head_ptr)
    if interp_addr == 0:
        raise RuntimeError("No interpreter found in the target process")

    # Step 2: Read the threads_main pointer from the interpreter
    threads_main_ptr = (
        interp_addr + debug_offsets.interpreter_state.threads_main
    )
    thread_state_addr = read_pointer(pid, threads_main_ptr)
    if thread_state_addr == 0:
        raise RuntimeError("Main thread state is not available")

    return thread_state_addr
@end example

The following example demonstrates how to locate a thread by its native thread
ID:

@example
def find_thread_by_id(
    pid: int,
    interp_addr: int,
    debug_offsets: DebugOffsets,
    target_tid: int,
) -> int:
    # Start at threads_head and walk the linked list
    thread_ptr = read_pointer(
        pid,
        interp_addr + debug_offsets.interpreter_state.threads_head
    )

    while thread_ptr:
        native_tid_ptr = (
            thread_ptr + debug_offsets.thread_state.native_thread_id
        )
        native_tid = read_int(pid, native_tid_ptr)
        if native_tid == target_tid:
            return thread_ptr
        thread_ptr = read_pointer(
            pid,
            thread_ptr + debug_offsets.thread_state.next
        )

    raise RuntimeError("Thread with the given ID was not found")
@end example

Once a valid thread state has been located, the debugger can proceed with
modifying its control fields and scheduling execution, as described in the next
section.

@node Writing control information,Summary,Locating the interpreter and thread state,Python HOWTOs
@anchor{howto/remote_debugging writing-control-information}@anchor{5c45}
@section Writing control information


Once a valid @code{PyThreadState} structure has been identified, the debugger may
modify control fields within it to schedule the execution of a specified Python
script. These control fields are checked periodically by the interpreter, and
when set correctly, they trigger the execution of remote code at a safe point
in the evaluation loop.

Each @code{PyThreadState} contains a @code{_PyRemoteDebuggerSupport} structure used
for communication between the debugger and the interpreter. The locations of
its fields are defined by the @code{_Py_DebugOffsets} structure and include the
following:


@itemize -

@item 
@code{debugger_script_path}: A fixed-size buffer that holds the full path to a
Python source file (@code{.py}).  This file must be accessible and readable by
the target process when execution is triggered.

@item 
@code{debugger_pending_call}: An integer flag. Setting this to @code{1} tells the
interpreter that a script is ready to be executed.

@item 
@code{eval_breaker}: A field checked by the interpreter during execution.
Setting bit 5 (@code{_PY_EVAL_PLEASE_STOP_BIT}, value @code{1U << 5}) in this
field causes the interpreter to pause and check for debugger activity.
@end itemize

To complete the injection, the debugger must perform the following steps:


@enumerate 

@item 
Write the full script path into the @code{debugger_script_path} buffer.

@item 
Set @code{debugger_pending_call} to @code{1}.

@item 
Read the current value of @code{eval_breaker}, set bit 5
(@code{_PY_EVAL_PLEASE_STOP_BIT}), and write the updated value back. This
signals the interpreter to check for debugger activity.
@end enumerate

The following is an example implementation:

@example
def inject_script(
    pid: int,
    thread_state_addr: int,
    debug_offsets: DebugOffsets,
    script_path: str
) -> None:
    # Compute the base offset of _PyRemoteDebuggerSupport
    support_base = (
        thread_state_addr +
        debug_offsets.debugger_support.remote_debugger_support
    )

    # Step 1: Write the script path into debugger_script_path
    script_path_ptr = (
        support_base +
        debug_offsets.debugger_support.debugger_script_path
    )
    write_string(pid, script_path_ptr, script_path)

    # Step 2: Set debugger_pending_call to 1
    pending_ptr = (
        support_base +
        debug_offsets.debugger_support.debugger_pending_call
    )
    write_int(pid, pending_ptr, 1)

    # Step 3: Set _PY_EVAL_PLEASE_STOP_BIT (bit 5, value 1 << 5) in
    # eval_breaker
    eval_breaker_ptr = (
        thread_state_addr +
        debug_offsets.debugger_support.eval_breaker
    )
    breaker = read_int(pid, eval_breaker_ptr)
    breaker |= (1 << 5)
    write_int(pid, eval_breaker_ptr, breaker)
@end example

Once these fields are set, the debugger may resume the process (if it was
suspended).  The interpreter will process the request at the next safe
evaluation point, load the script from disk, and execute it.

It is the responsibility of the debugger to ensure that the script file remains
present and accessible to the target process during execution.

@cartouche
@quotation Σημείωση 
Script execution is asynchronous. The script file cannot be deleted
immediately after injection. The debugger should wait until the injected
script has produced an observable effect before removing the file.
This effect depends on what the script is designed to do. For example,
a debugger might wait until the remote process connects back to a socket
before removing the script. Once such an effect is observed, it is safe to
assume the file is no longer needed.
@end quotation
@end cartouche

@node Summary,Security and threat model,Writing control information,Python HOWTOs
@anchor{howto/remote_debugging summary}@anchor{5c46}
@section Summary


To inject and execute a Python script in a remote process:


@enumerate 

@item 
Locate the @code{PyRuntime} structure in the target process’s memory.

@item 
Read and validate the @code{_Py_DebugOffsets} structure at the beginning of
@code{PyRuntime}.

@item 
Use the offsets to locate a valid @code{PyThreadState}.

@item 
Write the path to a Python script into @code{debugger_script_path}.

@item 
Set the @code{debugger_pending_call} flag to @code{1}.

@item 
Set @code{_PY_EVAL_PLEASE_STOP_BIT} in the @code{eval_breaker} field.

@item 
Resume the process (if suspended). The script will execute at the next safe
evaluation point.
@end enumerate

@node Security and threat model,,Summary,Python HOWTOs
@anchor{howto/remote_debugging remote-debugging-threat-model}@anchor{5c47}@anchor{howto/remote_debugging security-and-threat-model}@anchor{5c48}
@section Security and threat model


The remote debugging protocol relies on the same operating system primitives
used by native debuggers such as GDB and LLDB.  Attaching to a process
requires the `same privileges' that those debuggers require, for example
@code{ptrace} / Yama LSM on Linux, @code{task_for_pid} on macOS, and
@code{SeDebugPrivilege} on Windows.  Python does not introduce any new privilege
escalation path; if an attacker already possesses the permissions needed to
attach to a process, they could equally use GDB to read memory or inject
code.

The following principles define what is, and is not, considered a security
vulnerability in this feature:


@table @asis

@item Attaching requires OS-level privileges

On every supported platform the operating system gates cross-process
memory access behind privilege checks (@code{CAP_SYS_PTRACE}, root, or
administrator rights).  A report that demonstrates an issue only after
these privileges have already been obtained is `not' a vulnerability in
CPython, since the OS security boundary was already crossed.

@item Crashes or memory errors when reading a compromised process are not vulnerabilities

A tool that reads internal interpreter state from a target process must
trust that memory to be well-formed.  If the target process has been
corrupted or is controlled by an attacker, the debugger or profiler may
crash, produce garbage output, or behave unpredictably.  This is the same
risk accepted by every @code{ptrace}-based debugger.  Bugs in this category
(buffer overflows, segmentation faults, or undefined behaviour triggered
by reading corrupted state) are `not' treated as security issues, though
fixes that improve robustness are welcome.

@item Vulnerabilities in the target process are not in scope

If the Python process being debugged has already been compromised, the
attacker already controls execution in that process.  Demonstrating further
impact from that starting point does not constitute a vulnerability in the
remote debugging protocol.
@end table

@menu
* When to use PYTHON_DISABLE_REMOTE_DEBUG:: 

@end menu

@node When to use PYTHON_DISABLE_REMOTE_DEBUG,,,Security and threat model
@anchor{howto/remote_debugging when-to-use-python-disable-remote-debug}@anchor{5c49}
@subsection When to use @code{PYTHON_DISABLE_REMOTE_DEBUG}


The environment variable 
@geindex PYTHON_DISABLE_REMOTE_DEBUG
@geindex μεταβλητή περιβάλλοντος; PYTHON_DISABLE_REMOTE_DEBUG
@ref{419,,PYTHON_DISABLE_REMOTE_DEBUG} (and the
equivalent @ref{178,,-X disable_remote_debug} flag) allows operators to disable
the in-process side of the protocol as a `defence-in-depth' measure.  This
may be useful in hardened or sandboxed deployment environments where no
debugging or profiling of the process is expected and reducing attack surface
is a priority, even though the OS-level privilege checks already prevent
unprivileged access.

Setting this variable does `not' affect other OS-level debugging interfaces
(@code{ptrace}, @code{/proc}, @code{task_for_pid}, etc.), which remain available
according to their own permission models.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

Γενικά:


@itemize *

@item 
@ref{39fd,,A conceptual overview of asyncio}

@item 
@ref{bb6,,Annotations Best Practices}

@item 
@ref{35cb,,Argparse Tutorial}

@item 
@ref{188f,,Descriptor Guide}

@item 
@ref{5a8c,,Enum HOWTO}

@item 
@ref{5abd,,Functional Programming HOWTO}

@item 
@ref{440f,,An introduction to the ipaddress module}

@item 
@ref{5adc,,Logging HOWTO}

@item 
@ref{15a0,,Logging Cookbook}

@item 
@ref{297c,,Regular expression HOWTO}

@item 
@ref{27d9,,Sorting Techniques}

@item 
@ref{1649,,Unicode HOWTO}

@item 
@ref{41d3,,HOWTO Fetch Internet Resources Using The urllib Package}
@end itemize

Προχωρημένη ανάπτυξη:


@itemize *

@item 
@ref{36bf,,Curses Programming with Python}

@item 
@ref{2919,,Python support for free threading}

@item 
@ref{5c14,,C API Extension Support for Free Threading}

@item 
@ref{412,,Isolating Extension Modules}

@item 
@ref{184c,,The Python 2.3 Method Resolution Order}

@item 
@ref{3bea,,Socket Programming HOWTO}

@item 
@ref{5c05,,timer file descriptor HOWTO}

@item 
@ref{1685,,Porting Extension Modules to Python 3}
@end itemize

Αποσφαλμάτωση και σκιαγράφηση:


@itemize *

@item 
@ref{5a7d,,Debugging C API extensions and CPython Internals with GDB}

@item 
@ref{102a,,Instrumenting CPython with DTrace and SystemTap}

@item 
@ref{6b7,,Python support for the perf map compatible profilers}

@item 
@ref{4c0b,,Remote debugging attachment protocol}
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Συχνές Ερωτήσεις για την Python,Deprecations,Python HOWTOs,Top
@anchor{faq/index doc}@anchor{5c4a}@anchor{faq/index faq-index}@anchor{22e4}@anchor{faq/index python-frequently-asked-questions}@anchor{5c4b}@anchor{faq/index translation-repo}@anchor{5c4c}
@chapter Συχνές Ερωτήσεις για την Python


@menu
* General Python FAQ:: 
* FAQ Προγραμματισμού:: 
* Design and History FAQ:: 
* Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης:: 
* Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης:: 
* Python στα Windows FAQ:: 
* Graphic User Interface FAQ:: 
* «Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;» FAQ:: 

@end menu

@node General Python FAQ,FAQ Προγραμματισμού,,Συχνές Ερωτήσεις για την Python
@anchor{faq/general doc}@anchor{5c4d}@anchor{faq/general general-python-faq}@anchor{5c4e}
@section General Python FAQ



@menu
* General Information:: 
* Python in the real world:: 

@end menu

@node General Information,Python in the real world,,General Python FAQ
@anchor{faq/general general-information}@anchor{5c4f}
@subsection General Information


@menu
* What is Python?:: 
* What is the Python Software Foundation?:: 
* Are there copyright restrictions on the use of Python?:: 
* Why was Python created in the first place?:: 
* What is Python good for?:: 
* How does the Python version numbering scheme work?:: 
* How do I obtain a copy of the Python source?:: 
* How do I get documentation on Python?:: 
* I’ve never programmed before. Is there a Python tutorial?: I’ve never programmed before Is there a Python tutorial?. 
* Is there a newsgroup or mailing list devoted to Python?:: 
* How do I get a beta test version of Python?:: 
* How do I submit bug reports and patches for Python?:: 
* Are there any published articles about Python that I can reference?:: 
* Are there any books on Python?:: 
* Where in the world is www.python.org located?: Where in the world is www python org located?. 
* Why is it called Python?:: 
* Do I have to like «Monty Python’s Flying Circus»?:: 

@end menu

@node What is Python?,What is the Python Software Foundation?,,General Information
@anchor{faq/general what-is-python}@anchor{5c50}
@subsubsection What is Python?


Python is an interpreted, interactive, object-oriented programming language.  It
incorporates modules, exceptions, dynamic typing, very high level dynamic data
types, and classes.  It supports multiple programming paradigms beyond
object-oriented programming, such as procedural and functional programming.
Python combines remarkable power with very clear syntax. It has interfaces to
many system calls and libraries, as well as to various window systems, and is
extensible in C or C++.  It is also usable as an extension language for
applications that need a programmable interface. Finally, Python is portable:
it runs on many Unix variants including Linux and macOS, and on Windows.

To find out more, start with @ref{21a9,,Οδηγός εκμάθησης Python}.  The Beginner's Guide to Python@footnote{https://wiki.python.org/moin/BeginnersGuide} links to other
introductory tutorials and resources for learning Python.

@node What is the Python Software Foundation?,Are there copyright restrictions on the use of Python?,What is Python?,General Information
@anchor{faq/general what-is-the-python-software-foundation}@anchor{5c51}
@subsubsection What is the Python Software Foundation?


The Python Software Foundation is an independent non-profit organization that
holds the copyright on Python versions 2.1 and newer.  The PSF’s mission is to
advance open source technology related to the Python programming language and to
publicize the use of Python.  The PSF’s home page is at
@indicateurl{https://www.python.org/psf/}.

Donations to the PSF are tax-exempt in the US.  If you use Python and find it
helpful, please contribute via the PSF donation page@footnote{https://www.python.org/psf/donations/}.

@node Are there copyright restrictions on the use of Python?,Why was Python created in the first place?,What is the Python Software Foundation?,General Information
@anchor{faq/general are-there-copyright-restrictions-on-the-use-of-python}@anchor{5c52}
@subsubsection Are there copyright restrictions on the use of Python?


You can do anything you want with the source, as long as you leave the
copyrights in and display those copyrights in any documentation about Python
that you produce.  If you honor the copyright rules, it’s OK to use Python for
commercial use, to sell copies of Python in source or binary form (modified or
unmodified), or to sell products that incorporate Python in some form.  We would
still like to know about all commercial use of Python, of course.

See the license page@footnote{https://docs.python.org/3/license.html} to find further
explanations and the full text of the PSF License.

The Python logo is trademarked, and in certain cases permission is required to
use it.  Consult the Trademark Usage Policy@footnote{https://www.python.org/psf/trademarks/} for more information.

@node Why was Python created in the first place?,What is Python good for?,Are there copyright restrictions on the use of Python?,General Information
@anchor{faq/general why-was-python-created-in-the-first-place}@anchor{5c53}
@subsubsection Why was Python created in the first place?


Here’s a `very' brief summary of what started it all, written by Guido van
Rossum:

@quotation

I had extensive experience with implementing an interpreted language in the
ABC group at CWI, and from working with this group I had learned a lot about
language design.  This is the origin of many Python features, including the
use of indentation for statement grouping and the inclusion of
very-high-level data types (although the details are all different in
Python).

I had a number of gripes about the ABC language, but also liked many of its
features.  It was impossible to extend the ABC language (or its
implementation) to remedy my complaints – in fact its lack of extensibility
was one of its biggest problems.  I had some experience with using Modula-2+
and talked with the designers of Modula-3 and read the Modula-3 report.
Modula-3 is the origin of the syntax and semantics used for exceptions, and
some other Python features.

I was working in the Amoeba distributed operating system group at CWI.  We
needed a better way to do system administration than by writing either C
programs or Bourne shell scripts, since Amoeba had its own system call
interface which wasn’t easily accessible from the Bourne shell.  My
experience with error handling in Amoeba made me acutely aware of the
importance of exceptions as a programming language feature.

It occurred to me that a scripting language with a syntax like ABC but with
access to the Amoeba system calls would fill the need.  I realized that it
would be foolish to write an Amoeba-specific language, so I decided that I
needed a language that was generally extensible.

During the 1989 Christmas holidays, I had a lot of time on my hand, so I
decided to give it a try.  During the next year, while still mostly working
on it in my own time, Python was used in the Amoeba project with increasing
success, and the feedback from colleagues made me add many early
improvements.

In February 1991, after just over a year of development, I decided to post to
USENET.  The rest is in the @code{Misc/HISTORY} file.
@end quotation

@node What is Python good for?,How does the Python version numbering scheme work?,Why was Python created in the first place?,General Information
@anchor{faq/general what-is-python-good-for}@anchor{5c54}
@subsubsection What is Python good for?


Python is a high-level general-purpose programming language that can be applied
to many different classes of problems.

The language comes with a large standard library that covers areas such as
string processing (regular expressions, Unicode, calculating differences between
files), internet protocols (HTTP, FTP, SMTP, XML-RPC, POP, IMAP),
software engineering (unit testing, logging, profiling, parsing
Python code), and operating system interfaces (system calls, filesystems, TCP/IP
sockets).  Look at the table of contents for @ref{3f7,,The Python Standard Library} to get an idea
of what’s available.  A wide variety of third-party extensions are also
available.  Consult the Python Package Index@footnote{https://pypi.org} to
find packages of interest to you.

@node How does the Python version numbering scheme work?,How do I obtain a copy of the Python source?,What is Python good for?,General Information
@anchor{faq/general faq-version-numbering-scheme}@anchor{5c55}@anchor{faq/general how-does-the-python-version-numbering-scheme-work}@anchor{5c56}
@subsubsection How does the Python version numbering scheme work?


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.

You may also find version numbers with a «+» suffix, e.g. «2.2+».  These are
unreleased versions, built directly from the CPython development repository.  In
practice, after a final minor release is made, the version is incremented to the
next minor version, which becomes the «a0» version, e.g. «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{6a8,,sys.version}, @ref{4c04,,sys.hexversion}, and
@ref{2fc,,sys.version_info}.

@node How do I obtain a copy of the Python source?,How do I get documentation on Python?,How does the Python version numbering scheme work?,General Information
@anchor{faq/general how-do-i-obtain-a-copy-of-the-python-source}@anchor{5c57}
@subsubsection How do I obtain a copy of the Python source?


The latest Python source distribution is always available from python.org, at
@indicateurl{https://www.python.org/downloads/}.  The latest development sources can be obtained
at @indicateurl{https://github.com/python/cpython/}.

The source distribution is a gzipped tar file containing the complete C source,
Sphinx-formatted documentation, Python library modules, example programs, and
several useful pieces of freely distributable software.  The source will compile
and run out of the box on most UNIX platforms.

Consult the Getting Started section of the Python Developer's Guide@footnote{https://devguide.python.org/setup/} for more
information on getting the source code and compiling it.

@node How do I get documentation on Python?,I’ve never programmed before Is there a Python tutorial?,How do I obtain a copy of the Python source?,General Information
@anchor{faq/general how-do-i-get-documentation-on-python}@anchor{5c58}
@subsubsection How do I get documentation on Python?


The standard documentation for the current stable version of Python is available
at @indicateurl{https://docs.python.org/3/}.  EPUB, plain text, and downloadable HTML versions are
also available at @indicateurl{https://docs.python.org/3/download.html}.

The documentation is written in reStructuredText and processed by the Sphinx documentation tool@footnote{https://www.sphinx-doc.org/}.  The reStructuredText source for
the documentation is part of the Python source distribution.

@node I’ve never programmed before Is there a Python tutorial?,Is there a newsgroup or mailing list devoted to Python?,How do I get documentation on Python?,General Information
@anchor{faq/general i-ve-never-programmed-before-is-there-a-python-tutorial}@anchor{5c59}
@subsubsection I’ve never programmed before. Is there a Python tutorial?


There are numerous tutorials and books available.  The standard documentation
includes @ref{21a9,,Οδηγός εκμάθησης Python}.

Consult the Beginner's Guide@footnote{https://wiki.python.org/moin/BeginnersGuide} to
find information for beginning Python programmers, including lists of tutorials.

@node Is there a newsgroup or mailing list devoted to Python?,How do I get a beta test version of Python?,I’ve never programmed before Is there a Python tutorial?,General Information
@anchor{faq/general is-there-a-newsgroup-or-mailing-list-devoted-to-python}@anchor{5c5a}
@subsubsection Is there a newsgroup or mailing list devoted to Python?


There is a newsgroup, @code{comp.lang.python}, and a mailing list,
python-list@footnote{https://mail.python.org/mailman/listinfo/python-list}.  The
newsgroup and mailing list are gatewayed into each other – if you can read news
it’s unnecessary to subscribe to the mailing list.
@code{comp.lang.python} is high-traffic, receiving hundreds of postings
every day, and Usenet readers are often more able to cope with this 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/}.

More info about other mailing lists and newsgroups
can be found at @indicateurl{https://www.python.org/community/lists/}.

@node How do I get a beta test version of Python?,How do I submit bug reports and patches for Python?,Is there a newsgroup or mailing list devoted to Python?,General Information
@anchor{faq/general how-do-i-get-a-beta-test-version-of-python}@anchor{5c5b}
@subsubsection How do I get a beta test version of Python?


Alpha and beta releases are available from @indicateurl{https://www.python.org/downloads/}.  All
releases are announced on the comp.lang.python and comp.lang.python.announce
newsgroups and on the Python home page at @indicateurl{https://www.python.org/}; an RSS feed of
news is available.

You can also access the development version of Python through Git.  See
The Python Developer's Guide@footnote{https://devguide.python.org/} for details.

@node How do I submit bug reports and patches for Python?,Are there any published articles about Python that I can reference?,How do I get a beta test version of Python?,General Information
@anchor{faq/general how-do-i-submit-bug-reports-and-patches-for-python}@anchor{5c5c}
@subsubsection How do I submit bug reports and patches for Python?


To report a bug or submit a patch, use the issue tracker at
@indicateurl{https://github.com/python/cpython/issues}.

For more information on how Python is developed, consult the Python Developer's Guide@footnote{https://devguide.python.org/}.

@node Are there any published articles about Python that I can reference?,Are there any books on Python?,How do I submit bug reports and patches for Python?,General Information
@anchor{faq/general are-there-any-published-articles-about-python-that-i-can-reference}@anchor{5c5d}
@subsubsection Are there any published articles about Python that I can reference?


It’s probably best to cite your favorite book about Python.

The very first article@footnote{https://ir.cwi.nl/pub/18204} about Python was
written in 1991 and is now quite outdated.

@quotation

Guido van Rossum and 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 Are there any books on Python?,Where in the world is www python org located?,Are there any published articles about Python that I can reference?,General Information
@anchor{faq/general are-there-any-books-on-python}@anchor{5c5e}
@subsubsection Are there any books on Python?


Yes, there are many, and more are being published.  See the python.org wiki at
@indicateurl{https://wiki.python.org/moin/PythonBooks} for a list.

You can also search online bookstores for «Python» and filter out the Monty
Python references; or perhaps search for «Python» and «language».

@node Where in the world is www python org located?,Why is it called Python?,Are there any books on Python?,General Information
@anchor{faq/general where-in-the-world-is-www-python-org-located}@anchor{5c5f}
@subsubsection Where in the world is www.python.org located?


The Python project’s infrastructure is located all over the world and is managed
by the Python Infrastructure Team. Details here@footnote{https://infra.psf.io}.

@node Why is it called Python?,Do I have to like «Monty Python’s Flying Circus»?,Where in the world is www python org located?,General Information
@anchor{faq/general why-is-it-called-python}@anchor{5c60}
@subsubsection Why is it called Python?


When he began implementing Python, Guido van Rossum was also reading the
published scripts from "Monty Python's Flying Circus"@footnote{https://en.wikipedia.org/wiki/Monty_Python}, a BBC comedy series from the 1970s.  Van Rossum
thought he needed a name that was short, unique, and slightly mysterious, so he
decided to call the language Python.

@node Do I have to like «Monty Python’s Flying Circus»?,,Why is it called Python?,General Information
@anchor{faq/general do-i-have-to-like-monty-python-s-flying-circus}@anchor{5c61}
@subsubsection Do I have to like «Monty Python’s Flying Circus»?


No, but it helps.  :)

@node Python in the real world,,General Information,General Python FAQ
@anchor{faq/general python-in-the-real-world}@anchor{5c62}
@subsection Python in the real world


@menu
* How stable is Python?:: 
* How many people are using Python?:: 
* Have any significant projects been done in Python?:: 
* What new developments are expected for Python in the future?:: 
* Is it reasonable to propose incompatible changes to Python?:: 
* Is Python a good language for beginning programmers?:: 

@end menu

@node How stable is Python?,How many people are using Python?,,Python in the real world
@anchor{faq/general how-stable-is-python}@anchor{5c63}
@subsubsection How stable is 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 How many people are using Python?,Have any significant projects been done in Python?,How stable is Python?,Python in the real world
@anchor{faq/general how-many-people-are-using-python}@anchor{5c64}
@subsubsection How many people are using Python?


There are probably millions of users, though it’s difficult to obtain an exact
count.

Python is available for free download, so there are no sales figures, and it’s
available from many different sites and packaged with many Linux distributions,
so download statistics don’t tell the whole story either.

The comp.lang.python newsgroup is very active, but not all Python users post to
the group or even read it.

@node Have any significant projects been done in Python?,What new developments are expected for Python in the future?,How many people are using Python?,Python in the real world
@anchor{faq/general have-any-significant-projects-been-done-in-python}@anchor{5c65}
@subsubsection Have any significant projects been done in Python?


See @indicateurl{https://www.python.org/about/success} for a list of projects that use Python.
Consulting the proceedings for past Python conferences@footnote{https://www.python.org/community/workshops/} will reveal contributions from many
different companies and organizations.

High-profile Python projects include the Mailman mailing list manager@footnote{https://www.list.org} and the Zope application server@footnote{https://www.zope.dev}.  Several Linux distributions, most notably Red Hat@footnote{https://www.redhat.com}, have written part or all of their installer and
system administration software in Python.  Companies that use Python internally
include Google, Yahoo, and Lucasfilm Ltd.

@node What new developments are expected for Python in the future?,Is it reasonable to propose incompatible changes to Python?,Have any significant projects been done in Python?,Python in the real world
@anchor{faq/general what-new-developments-are-expected-for-python-in-the-future}@anchor{5c66}
@subsubsection What new developments are expected for Python in the future?


See @indicateurl{https://peps.python.org/} for the Python Enhancement Proposals
(PEPs). PEPs are design documents describing a suggested new feature for Python,
providing a concise technical specification and a rationale.  Look for a PEP
titled «Python X.Y Release Schedule», where X.Y is a version that hasn’t been
publicly released yet.

New development is discussed on the python-dev mailing list@footnote{https://mail.python.org/mailman3/lists/python-dev.python.org/}.

@node Is it reasonable to propose incompatible changes to Python?,Is Python a good language for beginning programmers?,What new developments are expected for Python in the future?,Python in the real world
@anchor{faq/general is-it-reasonable-to-propose-incompatible-changes-to-python}@anchor{5c67}
@subsubsection Is it reasonable to propose incompatible changes to Python?


In general, no.  There are already millions of lines of Python code around the
world, so any change in the language that invalidates more than a very small
fraction of existing programs has to be frowned upon.  Even if you can provide a
conversion program, there’s still the problem of updating all documentation;
many books have been written about Python, and we don’t want to invalidate them
all at a single stroke.

Providing a gradual upgrade path is necessary if a feature has to be changed.
@geindex Python Enhancement Proposals; PEP 5
PEP 5@footnote{https://peps.python.org/pep-0005/} describes the procedure followed for introducing backward-incompatible
changes while minimizing disruption for users.

@node Is Python a good language for beginning programmers?,,Is it reasonable to propose incompatible changes to Python?,Python in the real world
@anchor{faq/general is-python-a-good-language-for-beginning-programmers}@anchor{5c68}
@subsubsection Is Python a good language for beginning programmers?


Yes.

It is still common to start students with a procedural and statically typed
language such as Pascal, C, or a subset of C++ or Java.  Students may be better
served by learning Python as their first language.  Python has a very simple and
consistent syntax and a large standard library and, most importantly, using
Python in a beginning programming course lets students concentrate on important
programming skills such as problem decomposition and data type design.  With
Python, students can be quickly introduced to basic concepts such as loops and
procedures.  They can probably even work with user-defined objects in their very
first course.

For a student who has never programmed before, using a statically typed language
seems unnatural.  It presents additional complexity that the student must master
and slows the pace of the course.  The students are trying to learn to think
like a computer, decompose problems, design consistent interfaces, and
encapsulate data.  While learning to use a statically typed language is
important in the long term, it is not necessarily the best topic to address in
the students” first programming course.

Many other aspects of Python make it a good first language.  Like Java, Python
has a large standard library so that students can be assigned programming
projects very early in the course that `do' something.  Assignments aren’t
restricted to the standard four-function calculator and check balancing
programs.  By using the standard library, students can gain the satisfaction of
working on realistic applications as they learn the fundamentals of programming.
Using the standard library also teaches students about code reuse.  Third-party
modules such as PyGame are also helpful in extending the students” reach.

Python’s interactive interpreter enables students to test language features
while they’re programming.  They can keep a window with the interpreter running
while they enter their program’s source in another window.  If they can’t
remember the methods for a list, they can do something like this:

@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

With the interpreter, documentation is never far from the student as they are
programming.

There are also good IDEs for Python.  IDLE is a cross-platform IDE for Python
that is written in Python using Tkinter.
Emacs users will be happy to know that there is a very good Python mode for
Emacs.  All of these programming environments provide syntax highlighting,
auto-indenting, and access to the interactive interpreter while coding.  Consult
the Python wiki@footnote{https://wiki.python.org/moin/PythonEditors} for a full list
of Python editing environments.

If you want to discuss Python’s use in education, you may be interested in
joining the edu-sig mailing list@footnote{https://www.python.org/community/sigs/current/edu-sig}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node FAQ Προγραμματισμού,Design and History FAQ,General Python FAQ,Συχνές Ερωτήσεις για την Python
@anchor{faq/programming doc}@anchor{5c69}@anchor{faq/programming programming-faq}@anchor{5c6a}@anchor{faq/programming translation-repo}@anchor{5c6b}
@section FAQ Προγραμματισμού



@menu
* General questions:: 
* Core language:: 
* Αριθμοί και συμβολοσειρές:: 
* Απόδοση:: 
* Sequences (tuples/lists): Sequences tuples/lists. 
* Αντικείμενα:: 
* Modules: Modules<5>. 

@end menu

@node General questions,Core language,,FAQ Προγραμματισμού
@anchor{faq/programming general-questions}@anchor{5c6c}
@subsection General questions


@menu
* Is there a source code-level debugger with breakpoints and single-stepping?:: 
* Υπάρχουν εργαλεία που βοηθούν στην εύρεση σφαλμάτων ή στην εκτέλεση στατικής ανάλυσης;:: 
* Πως μπορώ να δημιουργήσω ένα stand-alone binary από ένα Python script;:: 
* Υπάρχουν πρότυπα κωδικοποίησης ή οδηγός στυλ για προγράμματα Python;:: 

@end menu

@node Is there a source code-level debugger with breakpoints and single-stepping?,Υπάρχουν εργαλεία που βοηθούν στην εύρεση σφαλμάτων ή στην εκτέλεση στατικής ανάλυσης;,,General questions
@anchor{faq/programming is-there-a-source-code-level-debugger-with-breakpoints-and-single-stepping}@anchor{5c6d}
@subsubsection Is there a source code-level debugger with breakpoints and single-stepping?


Ναι.

Πολλοί εντοπιστές σφαλμάτων για την Python περιγράφονται παρακάτω και η ενσωματωμένη συνάρτηση @ref{4f9,,breakpoint()} σάς επιτρέπει να μεταβείτε σε οποιοδήποτε από αυτά.

Το pdb module είναι ένα απλό αλλά επαρκές πρόγραμμα εντοπισμού σφαλμάτων σε λειτουργία κονσόλας για την Python. Είναι μέρος της τυπικής βιβλιοθήκης Python και είναι @ref{aa,,documented in the Library Reference Manual}. Μπορείτε επίσης να γράψετε το δικό σας πρόγραμμα σφαλμάτων χρησιμοποιώντας τον κώδικα για το pdb ως παράδειγμα.

The IDLE interactive development environment, which is part of the standard
Python distribution (normally available as @ref{76,,idlelib}),
includes a graphical debugger.

Το PythonWin είναι ένα Python IDE που περιλαμβάνει ένα πρόγραμμα εντοπισμού σφαλμάτων GUI που βασίζεται σε pdb. Το πρόγραμμα εντοπισμού σφαλμάτων PythonWin χρωματίζει τα σημεία διακοπής και έχει αρκετά ωραία χαρακτηριστικά, όπως τον εντοπισμό σφαλμάτων σε προγράμματα που δεν είναι PythonWin. Το PythonWin είναι διαθέσιμο ως μέρος του pywin32@footnote{https://github.com/mhammond/pywin32} έργου και ως μέρος της διανομής ActivePython@footnote{https://www.activestate.com/products/python/} .

Το Eric@footnote{https://eric-ide.python-projects.org/} είναι ένα IDE που βασίζεται στο PyQt και το component επεξεργασίας Scintilla.

Το trepan3k@footnote{https://github.com/rocky/python3-trepan/} είναι ένα πρόγραμμα εντοπισμού σφαλμάτων παρόμοιο με το gdb.

Το Visual Studio Code@footnote{https://code.visualstudio.com/} είναι ένας IDE με εργαλεία εντοπισμού σφαλμάτων που ενσωματώνεται με λογισμικό ελέγχου έκδοσης.

Υπάρχει ένας αριθμός εμπορικών Python IDEs που περιλαμβάνουν γραφικούς εντοπισμούς σφαλμάτων. Αυτά περιλαμβάνουν:


@itemize *

@item 
Wing IDE@footnote{https://wingware.com/}

@item 
PyCharm@footnote{https://www.jetbrains.com/pycharm/}
@end itemize

@node Υπάρχουν εργαλεία που βοηθούν στην εύρεση σφαλμάτων ή στην εκτέλεση στατικής ανάλυσης;,Πως μπορώ να δημιουργήσω ένα stand-alone binary από ένα Python script;,Is there a source code-level debugger with breakpoints and single-stepping?,General questions
@anchor{faq/programming are-there-tools-to-help-find-bugs-or-perform-static-analysis}@anchor{5c6e}
@subsubsection Υπάρχουν εργαλεία που βοηθούν στην εύρεση σφαλμάτων ή στην εκτέλεση στατικής ανάλυσης;


Ναι.

Ruff@footnote{https://docs.astral.sh/ruff/},
Pylint@footnote{https://pylint.readthedocs.io/} and
Pyflakes@footnote{https://github.com/PyCQA/pyflakes} do basic checking that will
help you catch bugs sooner.

Static type checkers such as mypy@footnote{https://mypy-lang.org/},
ty@footnote{https://docs.astral.sh/ty/},
Pyrefly@footnote{https://pyrefly.org/}, and
pytype@footnote{https://github.com/google/pytype} can check type hints in Python
source code.

@node Πως μπορώ να δημιουργήσω ένα stand-alone binary από ένα Python script;,Υπάρχουν πρότυπα κωδικοποίησης ή οδηγός στυλ για προγράμματα Python;,Υπάρχουν εργαλεία που βοηθούν στην εύρεση σφαλμάτων ή στην εκτέλεση στατικής ανάλυσης;,General questions
@anchor{faq/programming faq-create-standalone-binary}@anchor{5c6f}@anchor{faq/programming how-can-i-create-a-stand-alone-binary-from-a-python-script}@anchor{5c70}
@subsubsection Πως μπορώ να δημιουργήσω ένα stand-alone binary από ένα Python script;


Δεν χρειάζεστε την δυνατότητα μεταγλώττισης κώδικα Python σε C, εάν το μόνο που θέλετε είναι ένα stand-alone πρόγραμμα που οι χρήστες μπορούν να κατεβάσουν και να εκτελέσουν χωρίς να χρειάζεται να εγκαταστήσουν πρώτα την διανομή της Python.  Υπάρχει μια σειρά από εργαλεία που καθορίζουν το σύνολο των modules που απαιτούνται από ένα πρόγραμμα και συνδέουν αυτά τα modules μαζί με ένα δυαδικό αρχείο Python για να παραχθεί ένα μόνο εκτελέσιμο.

One is to use the freeze tool, which is included in the Python source tree as
Tools/freeze@footnote{https://github.com/python/cpython/tree/main/Tools/freeze}.
It converts Python byte code to C arrays; with a C compiler you can
embed all your modules into a new program, which is then linked with the
standard Python modules.

Λειτουργεί σαρώνοντας τον πηγαίο κώδικα αναδρομικά για δηλώσεις εισαγωγής (και στις δύο μορφές) και αναζητώντας τα modules στην τυπική διαδρομή Python καθώς και στον κατάλογο προέλευσης (για ενσωματωμένα modules).  Στην συνέχεια γυρίζει τα bytecode για modules που είναι γραμμένες σε Python σε κώδικα C (initializers πίνακα που μπορούν να μετατραπούν σε αντικείμενα κώδικα χρησιμοποιώντας το marshal module) και δημιουργεί ένα προσαρμοσμένο αρχείο διαμόρφωσης που περιέχει μόνο εκείνα τα ενσωματωμένα modules που χρησιμοποιούνται πραγματικά στο πρόγραμμα και το συνδέει με τον υπόλοιπο διερμηνέα Python για να σχηματίσει ένα αυτόνομο δυαδικό αρχείο που λειτουργεί ακριβώς όπως το σενάριο σας.

Τα παρακάτω πακέτα μπορούν να σας βοηθήσουν για την δημιουργία εκτελέσιμων κονσόλας και GUI:


@itemize *

@item 
Nuitka@footnote{https://nuitka.net/} (Cross-platform)

@item 
PyInstaller@footnote{https://pyinstaller.org/} (Cross-platform)

@item 
PyOxidizer@footnote{https://pyoxidizer.readthedocs.io/en/stable/} (Cross-platform)

@item 
cx_Freeze@footnote{https://marcelotduarte.github.io/cx_Freeze/} (Cross-platform)

@item 
py2app@footnote{https://github.com/ronaldoussoren/py2app} (macOS μόνο)

@item 
py2exe@footnote{https://www.py2exe.org/} (Windows μόνο)
@end itemize

@node Υπάρχουν πρότυπα κωδικοποίησης ή οδηγός στυλ για προγράμματα Python;,,Πως μπορώ να δημιουργήσω ένα stand-alone binary από ένα Python script;,General questions
@anchor{faq/programming are-there-coding-standards-or-a-style-guide-for-python-programs}@anchor{5c71}
@subsubsection Υπάρχουν πρότυπα κωδικοποίησης ή οδηγός στυλ για προγράμματα Python;


Ναι. Το στυλ κωδικοποίησης που απαιτείται για τα τυπικά modules βιβλιοθήκης τεκμηριώνεται ως 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/}.

@node Core language,Αριθμοί και συμβολοσειρές,General questions,FAQ Προγραμματισμού
@anchor{faq/programming core-language}@anchor{5c72}
@subsection Core language


@menu
* Γιατί λαμβάνω ένα UnboundLocalError όταν η μεταβλητή έχει μια τιμή;:: 
* Ποιοι είναι οι κανόνες για τις τοπικές και τις καθολικές μεταβλητές στην Python;:: 
* Γιατί τα lambdas που ορίζονται σε έναν βρόχο με διαφορετικές τιμές επιστρέφουν όλα το ίδιο αποτέλεσμα;:: 
* Πως μοιράζομαι καθολικές μεταβλητές σε modules;:: 
* Ποιες είναι οι «βέλτιστες πρακτικές» για τη χρήση import σε ένα module;:: 
* Γιατί μοιράζονται οι προεπιλεγμένες τιμές μεταξύ των αντικειμένων;:: 
* Πώς μπορώ να μεταβιβάσω προαιρετικές παραμέτρους ή παραμέτρους λέξεων-κλειδιών από τη μια συνάρτηση στην άλλη;:: 
* Ποια είναι η διαφορά μεταξύ ορισμάτων και παραμέτρων;:: 
* Γιατί η αλλαγή της λίστας “y” αλλάζει επίσης και τη λίστα “x”;:: 
* Πως μπορώ να γράψω μια συνάρτηση με παραμέτρους εξόδου (κλήση με αναφορά);: Πως μπορώ να γράψω μια συνάρτηση με παραμέτρους εξόδου κλήση με αναφορά ;. 
* Πως δημιουργείτε μια συνάρτηση υψηλότερης τάξης στην Python;:: 
* Πως μπορώ να αντιγράψω ένα αντικείμενο στην Python;:: 
* Πως μπορώ να βρω τις μεθόδους ή τα χαρακτηριστικά ενός αντικειμένου;:: 
* Πως μπορεί ο κώδικας μου να ανακαλύψει το όνομα ενός αντικειμένου;:: 
* Τι συμβαίνει με την προτεραιότητα του τελεστή κόμματος;:: 
* Υπάρχει ισοδύναμο του τριαδικού τελεστή «?;» της C;: Υπάρχει ισοδύναμο του τριαδικού τελεστή «? » της C;. 
* Είναι δυνατόν να γράψουμε ασαφή one-liners στην Python;:: 
* Τι σημαίνει η κάθετος(/) στη λίστα παραμέτρων μιας συνάρτησης;: Τι σημαίνει η κάθετος / στη λίστα παραμέτρων μιας συνάρτησης;. 

@end menu

@node Γιατί λαμβάνω ένα UnboundLocalError όταν η μεταβλητή έχει μια τιμή;,Ποιοι είναι οι κανόνες για τις τοπικές και τις καθολικές μεταβλητές στην Python;,,Core language
@anchor{faq/programming faq-unboundlocalerror}@anchor{2621}@anchor{faq/programming why-am-i-getting-an-unboundlocalerror-when-the-variable-has-a-value}@anchor{5c73}
@subsubsection Γιατί λαμβάνω ένα UnboundLocalError όταν η μεταβλητή έχει μια τιμή;


Μπορεί να είναι έκπληξη να λάβετε το @ref{18d8,,UnboundLocalError} σε κώδικα που λειτουργούσε προηγουμένως όταν τροποποιείται προσθέτοντας μια δήλωση εκχώρησης κάπου στο σώμα μιας συνάρτησης.

Αυτό ο κώδικας:

@example
>>> x = 10
>>> def bar():
...     print(x)
...
>>> bar()
10
@end example

δουλεύει, αλλά αυτός ο κώδικας:

@example
>>> x = 10
>>> def foo():
...     print(x)
...     x += 1
@end example

καταλήγει σε ένα @code{UnboundLocalError}:

@example
>>> foo()
Traceback (most recent call last):
  ...
UnboundLocalError: cannot access local variable 'x' where it is not associated with a value
@end example

Αυτό συμβαίνει επειδή όταν κάνετε μια ανάθεση σε μια μεταβλητή σε ένα εύρος, αυτή η μεταβλητή γίνεται τοπική σε αυτό το εύρος και σκιάζει οποιαδήποτε μεταβλητή με παρόμοιο όνομα στο εξωτερικό εύρος. Εφόσον η τελευταία πρόταση στο foo εκχωρεί μια νέα τιμή στο @code{x}, ο μεταγλωττιστής την αναγνωρίζει ως τοπική μεταβλητή. Κατά συνέπεια όταν η προηγούμενη @code{print(x)} επιχειρεί να εκτυπώσει την uninitialized τοπική μεταβλητή και προκύπτει σφάλμα.

Στο παραπάνω παράδειγμα, μπορείτε να αποκτήσετε πρόσβαση στη μεταβλητή εξωτερικού εύρους δηλώνοντας την ως καθολική:

@example
>>> x = 10
>>> def foobar():
...     global x
...     print(x)
...     x += 1
...
>>> foobar()
10
@end example

Αυτή η ρητή δήλωση απαιτείται για να σας υπενθυμίσει ότι (σε αντίθεση με την επιφανειακά ανάλογη κατάσταση με τις μεταβλητές κλάσης και στιγμιότυπου) στην πραγματικότητα τροποποιείτε την τιμή της μεταβλητής στο εξωτερικό πεδίο:

@example
>>> print(x)
11
@end example

Μπορείτε να κάνετε κάτι παρόμοιο σε ένα ένθετο πεδίο χρησιμοποιώντας τη λέξη κλειδί @ref{164c,,nonlocal}:

@example
>>> def foo():
...    x = 10
...    def bar():
...        nonlocal x
...        print(x)
...        x += 1
...    bar()
...    print(x)
...
>>> foo()
10
11
@end example

@node Ποιοι είναι οι κανόνες για τις τοπικές και τις καθολικές μεταβλητές στην Python;,Γιατί τα lambdas που ορίζονται σε έναν βρόχο με διαφορετικές τιμές επιστρέφουν όλα το ίδιο αποτέλεσμα;,Γιατί λαμβάνω ένα UnboundLocalError όταν η μεταβλητή έχει μια τιμή;,Core language
@anchor{faq/programming what-are-the-rules-for-local-and-global-variables-in-python}@anchor{5c74}
@subsubsection Ποιοι είναι οι κανόνες για τις τοπικές και τις καθολικές μεταβλητές στην Python;


Στην Python, οι μεταβλητές που αναφέρονται μόνο μέσα σε μια συνάρτηση είναι έμμεσα καθολικές. Εάν σε μια μεταβλητή εκχωρηθεί μια τιμή οπουδήποτε μέσα στο σώμα της συνάρτησης, θεωρείται ότι είναι τοπική, εκτός αν δηλωθεί ρητά ως καθολική.

Αν και είναι λίγο έκπληξη στην αρχή, αυτό το εξηγεί μια στιγμή. Από τη μία πλευρά η απαίτηση @ref{6b5,,global} για εκχωρημένες μεταβλητές παρέχει μια γραμμή έναντι ανεπιθύμητων παρενεργειών. Από την άλλη, εάν απαιτείται @code{global} για όλες τις καθολικές αναφορές, θα χρησιμοποιούσατε @code{global} όλη την ώρα. Θα έπρεπε να δηλώσετε ως καθολική κάθε αναφορά σε μια ενσωματωμένη λειτουργία ή σε ένα στοιχείο ενός εισαγόμενου module. Αυτή η ακαταστασία θα νικήσει την χρησιμότητα της δήλωσης @code{global} για τον εντοπισμό παρενεργειών.

@node Γιατί τα lambdas που ορίζονται σε έναν βρόχο με διαφορετικές τιμές επιστρέφουν όλα το ίδιο αποτέλεσμα;,Πως μοιράζομαι καθολικές μεταβλητές σε modules;,Ποιοι είναι οι κανόνες για τις τοπικές και τις καθολικές μεταβλητές στην Python;,Core language
@anchor{faq/programming why-do-lambdas-defined-in-a-loop-with-different-values-all-return-the-same-result}@anchor{5c75}
@subsubsection Γιατί τα lambdas που ορίζονται σε έναν βρόχο με διαφορετικές τιμές επιστρέφουν όλα το ίδιο αποτέλεσμα;


Assume you use a for loop to define a few different lambdas (or even plain
functions), for example:

@example
>>> squares = []
>>> for x in range(5):
...     squares.append(lambda: x**2)
@end example

Αυτό σας δίνει μια λίστα που περιέχει 5 lambdas που υπολογίζουν το @code{x**2}.  Μπορεί να περιμένετε ότι, όταν καλέσετε, θα επέστρεφαν, αντίστοιχα, @code{0}, @code{1}, @code{4}, @code{9} και @code{16}. Ωστόσο, όταν δοκιμάσετε πραγματικά θα δείτε ότι όλα επιστρέφουν @code{16}:

@example
>>> squares[2]()
16
>>> squares[4]()
16
@end example

This happens because @code{x} is not local to the lambdas, but is defined in
the outer scope, and it is accessed when the lambda is called — not when it
is defined.  At the end of the loop, the value of @code{x} is @code{4}, so all the
functions now return @code{4**2}, that is @code{16}.  You can also verify this by
changing the value of @code{x} and see how the results of the lambdas change:

@example
>>> x = 8
>>> squares[2]()
64
@end example

Για να το αποφύγετε αυτό, πρέπει να αποθηκεύσετε τις τιμές σε μεταβλητές τοπικές στο lambda, έτσι ώστε να μην βασίζονται στην τιμή του καθολικού @code{x}:

@example
>>> squares = []
>>> for x in range(5):
...     squares.append(lambda n=x: n**2)
@end example

Εδώ, το @code{n=x} δημιουργεί μια νέα μεταβλητή @code{n} τοπική στο lambda και υπολογίζεται όταν το lambda ορίζεται έτσι ώστε να έχει την ίδια τιμή που είχε το @code{x} σε εκείνο το σημείο βρόχου. Αυτό σημαίνει ότι η τιμή του @code{n} θα είναι @code{0} στο πρώτο lambda, @code{1} στο δεύτερο , @code{2} στο τρίτο και ούτω καθεξής. Επομένως κάθε lambda θα επιστρέψει τώρα το σωστό αποτέλεσμα:

@example
>>> squares[2]()
4
>>> squares[4]()
16
@end example

Σημειώστε ότι αυτή η συμπεριφορά δεν είναι ιδιόμορφη για το lambdas, αλλά ισχύει και για κανονικές λειτουργίες.

@node Πως μοιράζομαι καθολικές μεταβλητές σε modules;,Ποιες είναι οι «βέλτιστες πρακτικές» για τη χρήση import σε ένα module;,Γιατί τα lambdas που ορίζονται σε έναν βρόχο με διαφορετικές τιμές επιστρέφουν όλα το ίδιο αποτέλεσμα;,Core language
@anchor{faq/programming how-do-i-share-global-variables-across-modules}@anchor{5c76}
@subsubsection Πως μοιράζομαι καθολικές μεταβλητές σε modules;


Ο κανονικός τρόπος για να μοιράζεστε πληροφορίες μεταξύ των λειτουργικών μονάδων μέσα σε ένα μόνο πρόγραμμα είναι η δημιουργία ενός ειδικού module (συχνά ονομάζεται config ή cfg).  Απλώς εισαγάγετε το module διαμόρφωσης σε όλες τα modules της εφαρμογής σας∙ το module στην συνέχεια γίνεται διαθέσιμο ως παγκόσμιο όνομα.  Επειδή υπάρχει μόνο ένα παράδειγμα για κάθε module , οι αλλαγές που γίνονται στο αντικείμενο του module αντικατοπτρίζονται παντού.  Για παράδειγμα:

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

Λάβετε υπόψη ότι η χρήση ενός module είναι επίσης η βάση για την εφαρμογή του μοτίβου σχεδιασμού singleton, για τον ίδιο λόγο.

@node Ποιες είναι οι «βέλτιστες πρακτικές» για τη χρήση import σε ένα module;,Γιατί μοιράζονται οι προεπιλεγμένες τιμές μεταξύ των αντικειμένων;,Πως μοιράζομαι καθολικές μεταβλητές σε modules;,Core language
@anchor{faq/programming what-are-the-best-practices-for-using-import-in-a-module}@anchor{5c77}
@subsubsection Ποιες είναι οι «βέλτιστες πρακτικές» για τη χρήση import σε ένα module;


Γενικά, μην χρησιμοποιείτε @code{from modulename import *}. Κάτι τέτοιο δημιουργεί μια ακαταστασία στο importer’s namespace, και καθιστά πιο δύσκολο για τα linters να εντοπίσουν απροσδιόριστα ονόματα.

Εισαγωγή modules στην κορυφή ενός αρχείου. Με αυτόν τον τρόπο καθιστά σαφές ποια άλλα modules απαιτεί ο κώδικας σας και αποφεύγονται ερωτήσεις σχετικά με το αν το όνομα της μονάδας είναι εντός πεδίου. Χρησιμοποιώντας ένα import ανά γραμμή καθιστά εύκολη την προσθήκη και τη διαγραφή module imports, αλλά χρησιμοποιώντας πολλαπλά imports ανά γραμμής καταναλώνεται λιγότερος χώρος στην οθόνη.

Είναι καλή πρακτική εάν εισάγετε module με την ακόλουθη σειρά:


@enumerate 

@item 
standard library modules – such as @ref{e2,,sys}, @ref{a5,,os}, @ref{7,,argparse}, @ref{c1,,re}

@item 
third-party library modules (anything installed in Python’s site-packages
directory) – such as dateutil@footnote{https://pypi.org/project/dateutil/}, requests@footnote{https://pypi.org/project/requests/}, tzdata@footnote{https://pypi.org/project/tzdata/}

@item 
τοπικά αναπτυγμένα modules
@end enumerate

Μερικές φορές είναι απαραίτητο να μετακινηθούν οι εισαγωγές σε μια συνάρτηση ή κλάση για να αποφευχθούν προβλήματα με τις κυκλικές εισαγωγές. Ο Gordon McMillan λέει:

@quotation

Οι κυκλικές εισαγωγές είναι καλές όταν και τα δύο modules χρησιμοποιούν τη μορφή εισαγωγής «import <module>». Αποτυγχάνουν όταν το 2ο module θέλει να πάρει ένα όνομα από το πρώτο («from module import name») και η εισαγωγή είναι στο κορυφαίο επίπεδο.  Αυτό συμβαίνει επειδή το πρώτο module είναι απασχολημένο με την εισαγωγή του 2ου.
@end quotation

Σε αυτήν την περίπτωση, εάν το δεύτερο module χρησιμοποιείται μόνο σε μια συνάρτηση, τότε η εισαγωγή μπορεί εύκολα να μεταφερθεί μέσα σε αυτήν την συνάρτηση.  Από τη στιγμή που καλείται η εισαγωγή, το πρώτο module θα έχει ολοκληρώσει την αρχικοποίηση, και το δεύτερο module μπορεί να κάνει την εισαγωγή του.

Μπορεί επίσης να είναι απαραίτητο να μετακινήσετε τις εισαγωγές από το ανώτερο επίπεδο κώδικα, εάν ορισμένα από τα module είναι συγκεκριμένα για την πλατφόρμα.  Σε αυτήν την περίπτωση, ενδέχεται να μην είναι καν δυνατή η εισαγωγή όλων των modules στο επάνω μέρος του αρχείου. Σε αυτήν την περίπτωση, η εισαγωγή των σωστών modules στον αντίστοιχο κώδικα για συγκεκριμένη πλατφόρμα είναι μια καλή επιλογή.

Μετακινήστε τις εισαγωγές σε τοπικό πεδίο, όπως μέσα σε έναν ορισμό συνάρτησης, μόνο εάν είναι απαραίτητο να λυθεί ένα πρόβλημα όπως η αποφυγή μιας κυκλικής εισαγωγής ή εάν προσπαθείτε να μειώσετε τον χρόνο προετοιμασίας μιας μονάδας. Αυτή η τεχνική είναι ιδιαίτερα χρήσιμη εάν πολλές από τις εισαγωγές δεν είναι απαραίτητες ανάλογα με τον τρόπο εκτέλεσης του προγράμματος. Μπορείτε επίσης να θέλετε να μετακινήσετε τις εισαγωγές σε μια συνάρτηση εάν τα modules χρησιμοποιούνται μόνο σε αυτήν τη συνάρτηση.  Λάβετε υπόψη ότι η φόρτωση ενός module την πρώτη φορά μπορεί να είναι δαπανηρή λόγω της μιας φοράς της αρχικοποίησης του module, αλλά η φόρτωση ενός module πολλές φορές είναι σχεδόν δωρεάν, κοστίζοντας μόνο μερικές αναζητήσεις σε λεξικό.  Ακόμα και αν το όνομα του module έχει ξεφύγει από το πεδίο εφαρμογής του, το module είναι πιθανώς διαθέσιμο στο @ref{19ba,,sys.modules}.

@node Γιατί μοιράζονται οι προεπιλεγμένες τιμές μεταξύ των αντικειμένων;,Πώς μπορώ να μεταβιβάσω προαιρετικές παραμέτρους ή παραμέτρους λέξεων-κλειδιών από τη μια συνάρτηση στην άλλη;,Ποιες είναι οι «βέλτιστες πρακτικές» για τη χρήση import σε ένα module;,Core language
@anchor{faq/programming why-are-default-values-shared-between-objects}@anchor{5c78}
@subsubsection Γιατί μοιράζονται οι προεπιλεγμένες τιμές μεταξύ των αντικειμένων;


Αυτός ο τύπος σφάλματος συνήθως δαγκώνει νεοφυείς προγραμματιστές. Σκεφτείτε αυτήν τη συνάρτηση:

@example
def foo(mydict=@{@}):  # Danger: shared reference to one dict for all calls
    ... compute something ...
    mydict[key] = value
    return mydict
@end example

Την πρώτη φορά που καλείτε αυτήν την συνάρτηση, το @code{mydict} περιέχει ένα μεμονωμένο στοιχείο. Τη δεύτερη φορά, το @code{mydict} περιέχει δύο στοιχεία γιατί όταν το @code{foo()} ξεκινά την εκτέλεση, το @code{mydict} ξεκινά με ένα αντικείμενο ήδη μέσα.

Συχνά αναμένεται ότι μια κλήση συνάρτησης δημιουργεί νέα αντικείμενα για προεπιλεγμένες τιμές. Δεν συμβαίνει αυτό. Οι προεπιλεγμένες τιμές δημιουργούνται ακριβώς μία φορά, όταν ορίζεται η συνάρτηση. Εάν αυτό το αντικείμενο αλλάξει, όπως το λεξικό σε αυτό το παράδειγμα, επόμενες κλήσεις στην συνάρτηση θα αναφέρονται σε αυτό το αλλαγμένο αντικείμενο.

Εξ ορισμού, αμετάβλητα αντικείμενα όπως αριθμοί, συμβολοσειρές, πλειάδες και @code{None} , είναι ασφαλή από αλλαγές. Οι αλλαγές σε μεταβλητά αντικείμενα όπως λεξικά, λίστες και παρουσίες κλάσεων μπορεί να οδηγήσουν σε σύγχυση.

Λόγω αυτής της δυνατότητας, είναι καλή πρακτική προγραμματισμού να μην χρησιμοποιείτε μεταβλητά αντικείμενα ως προεπιλεγμένες τιμές. Αντίθετα, χρησιμοποιείστε @code{None} ως προεπιλεγμένη τιμή και μέσα στην συνάρτηση, ελέγξτε εάν η παράμετρος είναι @code{None} και δημιουργήστε μια νέα λίστα/λεξικά/ό,τι και αν είναι. Για παράδειγμα μην γράψετε:

@example
def foo(mydict=@{@}):
    ...
@end example

αλλά:

@example
def foo(mydict=None):
    if mydict is None:
        mydict = @{@}  # create a new dict for local namespace
@end example

Αυτή η δυνατότητα μπορεί να είναι χρήσιμη. Όταν έχετε μια συνάρτηση που είναι χρονοβόρα για τον υπολογισμό, μια κοινή τεχνική είναι να αποθηκεύσετε προσωρινά τις παραμέτρους και την επιστρεφόμενη τιμή κάθε κλήσης στη συνάρτηση και να επιστρέφετε την προσωρινά αποθηκευμένη τιμή εάν ζητηθεί ξανά η ίδια τιμή. Αυτό ονομάζεται «memoizing», και μπορεί να εφαρμοστεί ως εξής:

@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

Θα μπορούσατε να χρησιμοποιήσετε μια καθολική μεταβλητή που περιέχει ένα λεξικό αντί για την προεπιλεγμένη τιμή∙ Είναι θέμα γούστου.

@node Πώς μπορώ να μεταβιβάσω προαιρετικές παραμέτρους ή παραμέτρους λέξεων-κλειδιών από τη μια συνάρτηση στην άλλη;,Ποια είναι η διαφορά μεταξύ ορισμάτων και παραμέτρων;,Γιατί μοιράζονται οι προεπιλεγμένες τιμές μεταξύ των αντικειμένων;,Core language
@anchor{faq/programming how-can-i-pass-optional-or-keyword-parameters-from-one-function-to-another}@anchor{5c79}
@subsubsection Πώς μπορώ να μεταβιβάσω προαιρετικές παραμέτρους ή παραμέτρους λέξεων-κλειδιών από τη μια συνάρτηση στην άλλη;


Συλλέξτε τα ορίσματα χρησιμοποιώντας τους specifiers @code{*} και @code{**} στη λίστα παραμέτρων της συνάρτησης∙ Αυτό σας δίνει τα ορίσματα θέσης ως πλειάδα και τα ορίσματα λέξεων-κλειδιών ως λεξικό. Στη συνέχεια, μπορείτε να μεταβιβάσετε αυτά τα ορίσματα κατά την κλήση άλλης συνάρτησης με τη χρήση των @code{*} και @code{**}:

@example
def f(x, *args, **kwargs):
    ...
    kwargs['width'] = '14.3c'
    ...
    g(x, *args, **kwargs)
@end example

@geindex όρισμα;διαφορά από παράμετρο
@geindex παράμετρος;διαφορά από όρισμα

@node Ποια είναι η διαφορά μεταξύ ορισμάτων και παραμέτρων;,Γιατί η αλλαγή της λίστας “y” αλλάζει επίσης και τη λίστα “x”;,Πώς μπορώ να μεταβιβάσω προαιρετικές παραμέτρους ή παραμέτρους λέξεων-κλειδιών από τη μια συνάρτηση στην άλλη;,Core language
@anchor{faq/programming faq-argument-vs-parameter}@anchor{5c7a}@anchor{faq/programming what-is-the-difference-between-arguments-and-parameters}@anchor{5c7b}
@subsubsection Ποια είναι η διαφορά μεταξύ ορισμάτων και παραμέτρων;


@ref{253c,,Παράμετροι} ορίζονται από τα ονόματα που εμφανίζονται στον ορισμό μιας συνάρτησης, ενώ τα @ref{867,,ορίσματα} είναι οι τιμές που πραγματικά μεταβιβάζονται σε μια συνάρτηση κατά την κλήση της. Οι παράμετροι ορίζουν τι kind of arguments μπορεί να δεχτεί μια συνάρτηση.  Για παράδειγμα δεδομένου του ορισμού της συνάρτησης:

@example
def func(foo, bar=None, **kwargs):
    pass
@end example

`foo', `bar' και `kwargs' είναι παράμετροι της @code{func}.  Ωστόσο, όταν καλείται η @code{func}, για παράδειγμα:

@example
func(42, bar=314, extra=somevar)
@end example

οι τιμές @code{42}, @code{314}, και @code{somevar} είναι ορίσματα.

@node Γιατί η αλλαγή της λίστας “y” αλλάζει επίσης και τη λίστα “x”;,Πως μπορώ να γράψω μια συνάρτηση με παραμέτρους εξόδου κλήση με αναφορά ;,Ποια είναι η διαφορά μεταξύ ορισμάτων και παραμέτρων;,Core language
@anchor{faq/programming why-did-changing-list-y-also-change-list-x}@anchor{5c7c}
@subsubsection Γιατί η αλλαγή της λίστας “y” αλλάζει επίσης και τη λίστα “x”;


Αν γράψατε κώδικα όπως:

@example
>>> x = []
>>> y = x
>>> y.append(10)
>>> y
[10]
>>> x
[10]
@end example

μπορεί να αναρωτιέστε γιατί η προσθήκη ενός στοιχείου στο @code{y} άλλαξε επίσης το @code{x}.

Υπάρχουν δύο παράγοντες που παράγουν αυτό το αποτέλεσμα:


@enumerate 

@item 
Οι μεταβλητές είναι απλά ονόματα που αναφέρονται σε αντικείμενα.  Κανόνας @code{y = x} δεν δημιουργείται αντίγραφο της λίστας – δημιουργεί μια νέα μεταβλητή @code{y} που αναφέρεται στο ίδιο αντικείμενο που αναφέρεται το @code{x}.  Αυτό σημαίνει ότι υπάρχει μόνο ένα αντικείμενο  (η λίστα), και το @code{x} και το @code{y} αναφέρονται σε αυτό.

@item 
Οι λίστες είναι @ref{21d1,,mutable}, που σημαίνει ότι μπορείτε να αλλάξετε το περιεχόμενό τους.
@end enumerate

Μετά την κλήση στο @ref{25cb,,append()}, το περιεχόμενο του μεταβλητού αντικειμένου έχει αλλάξει από @code{[]} σε @code{[10]}.  Επειδή και οι δύο μεταβλητές αναφέρονται στο ίδιο αντικείμενο, χρησιμοποιώντας οποιοδήποτε όνομα αποκτά πρόσβαση στην τροποποιημένη τιμή @code{[10]}.

Αν αντιστοιχίσουμε ένα αμετάβλητο αντικείμενο σε @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

μπορούμε να δούμε ότι σε αυτήν την περίπτωση @code{x} και @code{y} δεν είναι πλέον ίσα.  Αυτό συμβαίνει επειδή οι ακέραιοι αριθμοί είναι @ref{181,,immutable}, και όταν κάνουμε @code{x = x + 1} δεν μεταλλάσσεται το int @code{5} αυξάνοντας την τιμή του∙ αντίθετα, δημιουργούμε ένα νέο αντικείμενο (το int @code{6}) και το εκχωρούμε στο @code{x} (δηλαδή, αλλάζοντας το αντικείμενο  στο οποίο αναφέρεται το @code{x}).  Μετά από αυτήν την ανάθεση έχουμε δύο αντικείμενα (τα ints @code{6} and @code{5}) και δύο μεταβλητές που αναφέρονται σε αυτά (@code{x} τώρα αναφέρεται σε @code{6} αλλά @code{y} ακόμα αναφέρεται στο @code{5}).

Ορισμένες λειτουργίες (για παράδειγμα @code{y.append(10)} και @code{y.sort()}) μεταλλάσσουν το αντικείμενο, ενώ επιφανειακά παρόμοιες πράξεις (για παράδειγμα @code{y = y + [10]} και @ref{f8c,,sorted(y)}) δημιουργούν ένα νέο αντικείμενο. Γενικά στην Python (και σε όλες τις περιπτώσεις στην τυπική βιβλιοθήκη) μια μέθοδος που μεταλλάσσει ένα αντικείμενο θα επιστρέψει @code{None} για να αποφύγει τη σύγχυση των δύο τύπων πράξεων. Επομένως, εάν γράψετε κατά λάθος @code{y.sort()} νομίζοντας ότι θα σας δώσει ένα ταξινομημένο αντίγραφο του @code{y}, θα καταλήξετε με @code{None}, το οποίο πιθανότατα θα προκαλέσει το πρόγραμμά σας να δημιουργήσει ένα λάθος το οποίο διαγιγνώσκεται εύκολα.

Ωστόσο, υπάρχει μία κατηγορία λειτουργιών όπου η ίδια πράξη έχει μερικές φορές διαφορετικές συμπεριφορές με διαφορετικούς τύπους: οι επαυξημένοι τελεστές ανάθεσης. Για παράδειγμα, @code{+=} μεταλλάσσει τις λίστες αλλά όχι τις πλειάδες ή τους ints (@code{a_list += [1, 2, 3]} είναι ίσο με @code{a_list.extend([1, 2, 3])} και μεταλλάσσει @code{a_list}, ενώ το @code{some_tuple += (1, 2, 3)} και @code{some_int += 1} δημιουργεί νέα αντικείμενα).

Με άλλα λόγια:


@itemize *

@item 
If we have a mutable object (such as @ref{4d9,,list}, @ref{188,,dict}, @ref{42b,,set}),
we can use some specific operations to mutate it and all the variables
that refer to it will see the change.

@item 
If we have an immutable object (such as @ref{1df,,str}, @ref{326,,int}, @ref{1ce,,tuple}),
all the variables that refer to it will always see the same value,
but operations that transform that value into a new value always return a new
object.
@end itemize

Εάν θέλετε να γνωρίζετε εάν δύο μεταβλητές αναφέρονται στο ίδιο αντικείμενο ή όχι, μπορείτε να χρησιμοποιήσετε τον @ref{324,,is} operator, ή την ενσωματωμένη συνάρτηση @ref{17c5,,id()}.

@node Πως μπορώ να γράψω μια συνάρτηση με παραμέτρους εξόδου κλήση με αναφορά ;,Πως δημιουργείτε μια συνάρτηση υψηλότερης τάξης στην Python;,Γιατί η αλλαγή της λίστας “y” αλλάζει επίσης και τη λίστα “x”;,Core language
@anchor{faq/programming how-do-i-write-a-function-with-output-parameters-call-by-reference}@anchor{5c7d}
@subsubsection Πως μπορώ να γράψω μια συνάρτηση με παραμέτρους εξόδου (κλήση με αναφορά);


Remember that arguments are passed by assignment in Python.  Since assignment
just creates references to objects, there’s no alias between an argument name in
the caller and callee, and consequently no call-by-reference.  You can achieve the
desired effect in a number of ways.


@enumerate 

@item 
Επιστρέφοντας μια πλειάδα των αποτελεσμάτων:

@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

Αυτή είναι σχεδόν πάντα η πιο ξεκάθαρη λύση.

@item 
Χρησιμοποιώντας καθολικές μεταβλητές.  Αυτό δεν είναι ασφαλές για νήμα και δεν συνίσταται.

@item 
Περνώντας ένα μεταβλητό (με δυνατότητα αλλαγής επί τόπου) αντικείμενο:

@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 
Περνώντας σε ένα λεξικό που μεταλλάσσεται:

@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 
Ή ομαδοποιήστε τιμές σε μια παρουσία κλάσης:

@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

Δεν υπάρχει σχεδόν ποτέ καλός λόγος να γίνει αυτό περίπλοκο.
@end enumerate

Η καλύτερη επιλογή σας είναι να επιστρέψετε μια πλειάδα που περιέχει πολλαπλά αποτελέσματα.

@node Πως δημιουργείτε μια συνάρτηση υψηλότερης τάξης στην Python;,Πως μπορώ να αντιγράψω ένα αντικείμενο στην Python;,Πως μπορώ να γράψω μια συνάρτηση με παραμέτρους εξόδου κλήση με αναφορά ;,Core language
@anchor{faq/programming how-do-you-make-a-higher-order-function-in-python}@anchor{5c7e}
@subsubsection Πως δημιουργείτε μια συνάρτηση υψηλότερης τάξης στην Python;


Έχετε δύο επιλογές: μπορείτε να χρησιμοποιήσετε ένθετα πεδία ή μπορείτε να χρησιμοποιήσετε callable αντικείμενα. Για παράδειγμα, ας υποθέσουμε ότι θέλετε να ορίσετε το @code{linear(a,b)} που επιστρέφει μια συνάρτηση @code{f(x)} που υπολογίζει την τιμή @code{a*x+b}.  Χρησιμοποιώντας ένθετα πεδία:

@example
def linear(a, b):
    def result(x):
        return a * x + b
    return result
@end example

Ή χρησιμοποιώντας ένα callable αντικείμενο:

@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

Και στις δύο περιπτώσεις:

@example
taxes = linear(0.3, 2)
@end example

δίνει ένα callable αντικείμενο όπου @code{taxes(10e6) == 0.3 * 10e6 + 2}.

Η προσέγγιση του callable αντικειμένου έχει το μειονέκτημα ότι είναι λίγο πιο αργή και οδηγεί σε ελαφρώς μεγαλύτερο κώδικα.  Ωστόσο, σημειώστε ότι μια συλλογή από callables μπορεί να μοιραστεί την υπογραφή τους μέσω κληρονομικότητας:

@example
class exponential(linear):
    # __init__ inherited
    def __call__(self, x):
        return self.a * (x ** self.b)
@end example

Το αντικείμενο μπορεί να ενθυλακώσει την κατάσταση για πολλές μεθόδους:

@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

Εδώ @code{inc()}, @code{dec()} και @code{reset()} λειτουργούν σαν συναρτήσεις που μοιράζονται την ίδια μεταβλητή μέτρησης.

@node Πως μπορώ να αντιγράψω ένα αντικείμενο στην Python;,Πως μπορώ να βρω τις μεθόδους ή τα χαρακτηριστικά ενός αντικειμένου;,Πως δημιουργείτε μια συνάρτηση υψηλότερης τάξης στην Python;,Core language
@anchor{faq/programming how-do-i-copy-an-object-in-python}@anchor{5c7f}
@subsubsection Πως μπορώ να αντιγράψω ένα αντικείμενο στην Python;


Γενικά, δοκιμάστε @ref{942,,copy.copy()} ή @ref{f2b,,copy.deepcopy()} για τη γενική περίπτωση. Δεν μπορούν να αντιγραφούν όλα τα αντικείμενα, αλλά τα περισσότερα μπορούν.

Ορισμένα αντικείμενα μπορούν να αντιγραφούν πιο εύκολα.  Τα λεξικά έχουν μία μέθοδο @ref{f8e,,copy()}:

@example
newdict = olddict.copy()
@end example

Οι ακολουθίες μπορούν να αντιγραφούν με τεμαχισμό:

@example
new_l = l[:]
@end example

@node Πως μπορώ να βρω τις μεθόδους ή τα χαρακτηριστικά ενός αντικειμένου;,Πως μπορεί ο κώδικας μου να ανακαλύψει το όνομα ενός αντικειμένου;,Πως μπορώ να αντιγράψω ένα αντικείμενο στην Python;,Core language
@anchor{faq/programming how-can-i-find-the-methods-or-attributes-of-an-object}@anchor{5c80}
@subsubsection Πως μπορώ να βρω τις μεθόδους ή τα χαρακτηριστικά ενός αντικειμένου;


Για παράδειγμα μια κλάση @code{x} που ορίζεται από το χρήστη, @ref{a23,,dir(x)} επιστρέφει μια αλφαβητική λίστα με τα ονόματα που περιέχει τα χαρακτηριστικά της οντότητας και τις μεθόδους και τα χαρακτηριστικά που ορίζονται από την κλάση του.

@node Πως μπορεί ο κώδικας μου να ανακαλύψει το όνομα ενός αντικειμένου;,Τι συμβαίνει με την προτεραιότητα του τελεστή κόμματος;,Πως μπορώ να βρω τις μεθόδους ή τα χαρακτηριστικά ενός αντικειμένου;,Core language
@anchor{faq/programming how-can-my-code-discover-the-name-of-an-object}@anchor{5c81}
@subsubsection Πως μπορεί ο κώδικας μου να ανακαλύψει το όνομα ενός αντικειμένου;


Γενικά μιλώντας, δεν μπορεί, επειδή τα αντικείμενα δεν έχουνε πραγματικά ονόματα. Ουσιαστικά, η εκχώρηση δεσμεύει πάντα ένα όνομα σε μια τιμή∙ το ίδιο ισχύει για τις δηλώσεις @code{def} και @code{class}, αλλά σε αυτή την περίπτωση η τιμή είναι callable. Λάβετε υπόψη τον ακόλουθο κώδικα:

@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

Αναμφισβήτητα η κλάση έχει ένα όνομα: παρόλο που είναι δεσμευμένη σε δύο ονόματα και καλείται μέσω του ονόματος @code{B} η δημιουργημένη οντότητα εξακολουθεί να αναφέρεται ως οντότητα της κλάσης @code{A}. Ωστόσο, είναι αδύνατο να πούμε είτε το όνομα της οντότητας είναι @code{a} ή @code{b}, καθώς και τα δύο  ονόματα συνδέονται με την ίδια τιμή.

Γενικά μιλώντας, δεν θα πρέπει να είναι απαραίτητο ο κώδικας σας να «γνωρίζει τα ονόματα» συγκεκριμένων τιμών. Αν δεν γράφετε εσκεμμένα ενδοσκοπικά (introspective) προγράμματα, αυτό είναι συνήθως μια ένδειξη ότι μια αλλαγή προσέγγισης μπορεί να είναι επωφελής.

Στο comp.lang.python, ο Fredrik Lundh έδωσε μια εξαιρετική αναλογία ως απάντηση σε αυτήν την ερώτηση:

@quotation

Με το ίδιο τρόπο που παίρνετε το όνομα αυτής της γάτας που βρήκατε στη βεράντα σας: ή ίδια γάτα (αντικείμενο) δεν μπορεί να σας πει το όνομά της και δεν την ενδιαφέρει πραγματικά - έτσι ο μόνος τρόπος για να μάθετε πως λέγεται είναι να ρωτήσετε όλους τους γείτονές σας (namespaces) αν είναι η γάτα τους (αντικείμενο)…

….και μην εκπλαγείτε αν διαπιστώσετε ότι είναι γνωστό με πολλά ονόματα, ή κανένα όνομα!
@end quotation

@node Τι συμβαίνει με την προτεραιότητα του τελεστή κόμματος;,Υπάρχει ισοδύναμο του τριαδικού τελεστή «? » της C;,Πως μπορεί ο κώδικας μου να ανακαλύψει το όνομα ενός αντικειμένου;,Core language
@anchor{faq/programming what-s-up-with-the-comma-operator-s-precedence}@anchor{5c82}
@subsubsection Τι συμβαίνει με την προτεραιότητα του τελεστή κόμματος;


Το κόμμα δεν είναι τελεστής στην Python.  Σκεφτείτε αυτήν την συνεδρία:

@example
>>> "a" in "b", "a"
(False, 'a')
@end example

Δεδομένου ότι το κόμμα δεν είναι τελεστής, αλλά διαχωριστικό μεταξύ των εκφράσεων, τα παραπάνω αξιολογούνται σαν να είχατε εισαγάγει:

@example
("a" in "b"), "a"
@end example

δεν:

@example
"a" in ("b", "a")
@end example

The same is true of the various assignment operators (@code{=}, @code{+=}, and so on).
They are not truly operators but syntactic delimiters in assignment statements.

@node Υπάρχει ισοδύναμο του τριαδικού τελεστή «? » της C;,Είναι δυνατόν να γράψουμε ασαφή one-liners στην Python;,Τι συμβαίνει με την προτεραιότητα του τελεστή κόμματος;,Core language
@anchor{faq/programming is-there-an-equivalent-of-c-s-ternary-operator}@anchor{5c83}
@subsubsection Υπάρχει ισοδύναμο του τριαδικού τελεστή «?:» της C;


Ναι υπάρχει, Η σύνταξη έχει ως εξής:

@example
[on_true] if [expression] else [on_false]

x, y = 50, 25
small = x if x < y else y
@end example

Πριν εισαχθεί αυτή η σύνταξη στην Python 2.5, ένα κοινό ιδίωμα ήταν η χρήση λογικών τελεστών:

@example
[έκφραση] and [αληθές] or [ψευδές]
@end example

Ωστόσο, αυτό το ιδίωμα δεν είναι ασφαλές, καθώς μπορεί να δώσει λανθασμένα αποτελέσματα όταν το `on_true' έχει ψευδή δυαδική τιμή. Επομένως, είναι πάντα καλύτερο να χρησιμοποιήσετε τη φόρμα @code{... if ... else ...}.

@node Είναι δυνατόν να γράψουμε ασαφή one-liners στην Python;,Τι σημαίνει η κάθετος / στη λίστα παραμέτρων μιας συνάρτησης;,Υπάρχει ισοδύναμο του τριαδικού τελεστή «? » της C;,Core language
@anchor{faq/programming is-it-possible-to-write-obfuscated-one-liners-in-python}@anchor{5c84}
@subsubsection Είναι δυνατόν να γράψουμε ασαφή one-liners στην Python;


Ναι.  Συνήθως αυτό γίνεται με ένθεση του @ref{1642,,lambda} εντός του @code{lambda}.  Δείτε τα ακόλουθα τρία παραδείγματα, ελαφρώς προσαρμοσμένα από τον 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

Μην το δοκιμάσετε στο σπίτι, παιδιά!

@node Τι σημαίνει η κάθετος / στη λίστα παραμέτρων μιας συνάρτησης;,,Είναι δυνατόν να γράψουμε ασαφή one-liners στην Python;,Core language
@anchor{faq/programming faq-positional-only-arguments}@anchor{27cf}@anchor{faq/programming what-does-the-slash-in-the-parameter-list-of-a-function-mean}@anchor{5c85}
@subsubsection Τι σημαίνει η κάθετος(/) στη λίστα παραμέτρων μιας συνάρτησης;


Μια κάθετος στη λίστα ορισμάτων μιας συνάρτησης υποδηλώνει ότι οι παράμετροι πριν από αυτήν είναι μόνο θέσης.  Οι παράμετροι μόνο θέσης είναι εκείνες χωρίς εξωτερικά χρησιμοποιήσιμο όνομα.  Κατά την κλήση μιας συνάρτησης που δέχεται παραμέτρους μόνο θέσης, τα ορίσματα αντιστοιχίζονται σε παραμέτρους που βασίζονται αποκλειστικά στη θέση τους. Για παράδειγμα η @ref{d6a,,divmod()} είναι μια συνάρτηση που δέχεται μόνο παραμέτρους θέσης. Η τεκμηρίωσή τους μοιάζει με αυτό:

@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

Η κάθετος στο τέλος της λίστας παραμέτρων σημαίνει ότι και οι δύο παράμετροι είναι μόνο θέσης. Επομένως, η κλήση της @ref{d6a,,divmod()} με ορίσματα λέξεων κλειδιών θα οδηγούσε σε σφάλμα:

@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 Αριθμοί και συμβολοσειρές,Απόδοση,Core language,FAQ Προγραμματισμού
@anchor{faq/programming numbers-and-strings}@anchor{5c86}
@subsection Αριθμοί και συμβολοσειρές


@menu
* Πώς προσδιορίζω δεκαεξαδικούς ή οκταδικούς ακέραιους αριθμούς;:: 
* Γιατί το -22 // 10 επιστρέφει -3;:: 
* Πώς μπορώ να πάρω το literal χαρακτηριστικό int αντί για το SyntaxError;:: 
* Πως μετατρέπω μια συμβολοσειρά σε έναν αριθμό;:: 
* Πως μετατρέπω έναν αριθμό σε συμβολοσειρά;:: 
* Πώς μπορώ να τροποποιήσω μια συμβολοσειρά στη θέση της;:: 
* Πως μπορώ να χρησιμοποιήσω συμβολοσειρές για να καλέσω συναρτήσεις/μεθόδους;:: 
* Υπάρχει ισοδύναμο με το Perl’s chomp() για την αφαίρεση των νέων γραμμών από τις συμβολοσειρές;: Υπάρχει ισοδύναμο με το Perl’s chomp για την αφαίρεση των νέων γραμμών από τις συμβολοσειρές;. 
* Υπάρχει αντίστοιχο scanf() ή sscanf();: Υπάρχει αντίστοιχο scanf ή sscanf ;. 
* Τι σημαίνει το σφάλμα UnicodeDecodeError ή UnicodeEncodeError;:: 
* Μπορώ να τερματίσω μια ακατέργαστη συμβολοσειρά με περιττό αριθμό backslashes;:: 

@end menu

@node Πώς προσδιορίζω δεκαεξαδικούς ή οκταδικούς ακέραιους αριθμούς;,Γιατί το -22 // 10 επιστρέφει -3;,,Αριθμοί και συμβολοσειρές
@anchor{faq/programming how-do-i-specify-hexadecimal-and-octal-integers}@anchor{5c87}
@subsubsection Πώς προσδιορίζω δεκαεξαδικούς ή οκταδικούς ακέραιους αριθμούς;


Για να καθορίσετε έναν οκταδικό ψηφίο, προηγείται την οκταδικής τιμής με ένα μηδέν, ¨και μετά ένα πεζό ή κεφαλαίο «o».  Για παράδειγμα, για να ορίσετε τη μεταβλητή «a» στην οκταδική τιμή «10» (8 σε δεκαδικό), πληκτρολογήστε:

@example
>>> a = 0o10
>>> a
8
@end example

Το δεκαεξαδικό είναι εξίσου εύκολο. Απλώς προηγείται του δεκαεξαδικού αριθμού με ένα μηδέν, και μετά ένα πεζό ή κεφαλαίο «x».  Τα δεκαεξαδικά ψηφία μπορούν να καθοριστούν με πεζά ή κεφαλαία. Για παράδειγμα, στον διερμηνέα Python:

@example
>>> a = 0xa5
>>> a
165
>>> b = 0XB2
>>> b
178
@end example

@node Γιατί το -22 // 10 επιστρέφει -3;,Πώς μπορώ να πάρω το literal χαρακτηριστικό int αντί για το SyntaxError;,Πώς προσδιορίζω δεκαεξαδικούς ή οκταδικούς ακέραιους αριθμούς;,Αριθμοί και συμβολοσειρές
@anchor{faq/programming why-does-22-10-return-3}@anchor{5c88}
@subsubsection Γιατί το -22 // 10 επιστρέφει -3;


Οφείλεται κυρίως στην επιθυμία που το @code{i % j} να έχει το ίδιο πρόσημο με το @code{j}. Εάν το θέλετε αυτό, και θέλετε επίσης:

@example
i == (i // j) * j + (i % j)
@end example

τότε η διαίρεση ακεραίου αριθμού πρέπει να επιστρέψει το υπόλοιπο.  Η C απαιτεί επίσης να διατηρείται αυτή η ταυτότητα και, στη συνέχεια, οι μεταγλωττιστές που περικόπτουν το @code{i // j} πρέπει να κάνουν το @code{i % j} να έχει το ίδιο πρόσημο με το @code{i}.

Υπάρχουν λίγες πραγματικές περιπτώσεις χρήσης για το @code{i % j} όταν το @code{j} είναι αρνητικό.  Όταν το @code{j} είναι θετικό, υπάρχουν πολλές, και σχεδόν όλες είναι πιο χρήσιμες για @code{i % j} να είναι @code{>= 0}. Εάν το ρολόι λέει 10 τι έλεγε πριν από 200 ώρες; @code{-190 % 12 == 2} είναι χρήσιμο∙ το @code{-190 % 12 == -10} είναι ένα σφάλμα που περιμένει να δαγκώσει.

@node Πώς μπορώ να πάρω το literal χαρακτηριστικό int αντί για το SyntaxError;,Πως μετατρέπω μια συμβολοσειρά σε έναν αριθμό;,Γιατί το -22 // 10 επιστρέφει -3;,Αριθμοί και συμβολοσειρές
@anchor{faq/programming how-do-i-get-int-literal-attribute-instead-of-syntaxerror}@anchor{5c89}
@subsubsection Πώς μπορώ να πάρω το literal χαρακτηριστικό int αντί για το SyntaxError;


Η προσπάθεια αναζήτησης ενός literal χαρακτηριστικού @code{int} με τον κανονικό τρόπο δίνει ένα @ref{17e,,SyntaxError} επειδή η περίοδος θεωρείται ως υποδιαστολή:

@example
>>> 1.__class__
  File "<stdin>", line 1
  1.__class__
   ^
SyntaxError: invalid decimal literal
@end example

Η λύση είναι να διαχωριστεί το literal από την τελεία είτε με κενό είτε με παρένθεση.

@example
>>> 1 .__class__
<class 'int'>
>>> (1).__class__
<class 'int'>
@end example

@node Πως μετατρέπω μια συμβολοσειρά σε έναν αριθμό;,Πως μετατρέπω έναν αριθμό σε συμβολοσειρά;,Πώς μπορώ να πάρω το literal χαρακτηριστικό int αντί για το SyntaxError;,Αριθμοί και συμβολοσειρές
@anchor{faq/programming how-do-i-convert-a-string-to-a-number}@anchor{5c8a}
@subsubsection Πως μετατρέπω μια συμβολοσειρά σε έναν αριθμό;


For integers, use the built-in @ref{326,,int()} type constructor, for example, @code{int('144')
== 144}.  Similarly, @ref{327,,float()} converts to a floating-point number,
for example, @code{float('144') == 144.0}.

Από προεπιλογή, αυτά ερμηνεύουν τον αριθμό ως δεκαδικό, έτσι ώστε @code{int('0144') == 144} να είναι αληθές, και το @code{int('0x144')} να εγείρει @ref{277,,ValueError}. Το @code{int(string, base)} παίρνει τη βάση για μετατροπή ως δεύτερο προαιρετικό όρισμα, οπότε το @code{int( '0x144', 16) == 324}.  Εάν η βάση έχει καθοριστεί ως 0, ο αριθμός ερμηνεύεται χρησιμοποιώντας κανόνες της Python: ένα αρχικό “0o” υποδηλώνει οκταδικό , και το “0x” δείχνει έναν δεκαεξαδικό αριθμό.

Μην χρησιμοποιείτε την ενσωματωμένη συνάρτηση @ref{184,,eval()} εάν το μόνο που χρειάζεστε είναι να μετατρέψετε συμβολοσειρές σε αριθμούς.  @code{eval()} θα είναι σημαντικά πιο αργή και παρουσιάζει κίνδυνο ασφαλείας: κάποιος θα μπορούσε να σας μεταβιβάσει μια έκφραση Python που μπορεί να έχει ανεπιθύμητες παρενέργειες.  Για παράδειγμα κάποιος θα μπορούσε να περάσει το @code{__import__('os').system("rm -rf $HOME")} το οποίο θα διαγράψει το home φάκελο.

@ref{184,,eval()} also has the effect of interpreting numbers as Python expressions,
so that, for example, @code{eval('09')} gives a syntax error because Python does not allow
leading “0” in a decimal number (except “0”).

@node Πως μετατρέπω έναν αριθμό σε συμβολοσειρά;,Πώς μπορώ να τροποποιήσω μια συμβολοσειρά στη θέση της;,Πως μετατρέπω μια συμβολοσειρά σε έναν αριθμό;,Αριθμοί και συμβολοσειρές
@anchor{faq/programming how-do-i-convert-a-number-to-a-string}@anchor{5c8b}
@subsubsection Πως μετατρέπω έναν αριθμό σε συμβολοσειρά;


For example, to convert the number @code{144} to the string @code{'144'}, use the built-in type
constructor @ref{1df,,str()}.  If you want a hexadecimal or octal representation, use
the built-in functions @ref{1674,,hex()} or @ref{1673,,oct()}.  For fancy formatting, see
the @ref{43a,,f-strings} and @ref{173f,,Format string syntax} sections.
For example, @code{"@{:04d@}".format(144)} yields
@code{'0144'} and @code{"@{:.3f@}".format(1.0/3.0)} yields @code{'0.333'}.

@node Πώς μπορώ να τροποποιήσω μια συμβολοσειρά στη θέση της;,Πως μπορώ να χρησιμοποιήσω συμβολοσειρές για να καλέσω συναρτήσεις/μεθόδους;,Πως μετατρέπω έναν αριθμό σε συμβολοσειρά;,Αριθμοί και συμβολοσειρές
@anchor{faq/programming how-do-i-modify-a-string-in-place}@anchor{5c8c}
@subsubsection Πώς μπορώ να τροποποιήσω μια συμβολοσειρά στη θέση της;


You can’t, because strings are immutable.  In most situations, you should
simply construct a new string from the various parts you want to assemble
it from.  However, if you need an object with the ability to modify in-place
Unicode data, try using an @ref{12d4,,io.StringIO} object or the @ref{8,,array}
module:

@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 Πως μπορώ να χρησιμοποιήσω συμβολοσειρές για να καλέσω συναρτήσεις/μεθόδους;,Υπάρχει ισοδύναμο με το Perl’s chomp για την αφαίρεση των νέων γραμμών από τις συμβολοσειρές;,Πώς μπορώ να τροποποιήσω μια συμβολοσειρά στη θέση της;,Αριθμοί και συμβολοσειρές
@anchor{faq/programming how-do-i-use-strings-to-call-functions-methods}@anchor{5c8d}
@subsubsection Πως μπορώ να χρησιμοποιήσω συμβολοσειρές για να καλέσω συναρτήσεις/μεθόδους;


Υπάρχουν διάφορες τεχνικές.


@itemize *

@item 
Το καλύτερο είναι να χρησιμοποιήσετε ένα λεξικό που αντιστοιχίζει συμβολοσειρές σε συναρτήσεις.  Το κύριο πλεονέκτημα αυτής της τεχνικής είναι ότι οι συμβολοσειρές δεν χρειάζεται να ταιριάζουν με τα ονόματα των συναρτήσεων.  Αυτή είναι επίσης η κύρια τεχνική που χρησιμοποιείται για την εξομοίωση μιας κατασκευής πεζών-κεφαλαίων:

@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 
Χρησιμοποιείστε την ενσωματωμένη συνάρτηση @ref{f8f,,getattr()}:

@example
import foo
getattr(foo, 'bar')()
@end example

Σημειώστε ότι το @ref{f8f,,getattr()} λειτουργεί σε οποιοδήποτε αντικείμενο, συμπεριλαμβανομένων κλάσεων, οντοτήτων κλάσεων, modules, και ούτω καθεξής.

Αυτό χρησιμοποιείται σε πολλά σημεία της τυπικής βιβλιοθήκης, όπως αυτό:

@example
class Foo:
    def do_foo(self):
        ...

    def do_bar(self):
        ...

f = getattr(foo_instance, 'do_' + opname)
f()
@end example

@item 
Χρησιμοποιήστε το @ref{28b,,locals()} για να επιλύσετε το όνομα της συνάρτησης:

@example
def myFunc():
    print("hello")

fname = "myFunc"

f = locals()[fname]
f()
@end example
@end itemize

@node Υπάρχει ισοδύναμο με το Perl’s chomp για την αφαίρεση των νέων γραμμών από τις συμβολοσειρές;,Υπάρχει αντίστοιχο scanf ή sscanf ;,Πως μπορώ να χρησιμοποιήσω συμβολοσειρές για να καλέσω συναρτήσεις/μεθόδους;,Αριθμοί και συμβολοσειρές
@anchor{faq/programming is-there-an-equivalent-to-perl-s-chomp-for-removing-trailing-newlines-from-strings}@anchor{5c8e}
@subsubsection Υπάρχει ισοδύναμο με το Perl’s @code{chomp()} για την αφαίρεση των νέων γραμμών από τις συμβολοσειρές;


Μπορείτε να χρησιμοποιήσετε το @code{S.rstrip("\r\n")} για να αφαιρέσετε όλες τις εμφανίσεις οποιουδήποτε terminator γραμμής από το τέλος της συμβολοσειράς @code{S} χωρίς να αφαιρέσετε άλλα κενά.  Η συμβολοσειρά @code{S} αντιπροσωπεύει περισσότερες από μία γραμμές στο τέλος, οι terminators γραμμής για όλες τις κενές γραμμές θα αφαιρεθούν:

@example
>>> lines = ("line 1 \r\n"
...          "\r\n"
...          "\r\n")
>>> lines.rstrip("\n\r")
'line 1 '
@end example

Δεδομένου ότι αυτό είναι συνήθως επιθυμητό μόνο κατά την ανάγνωση κειμένου μία γραμμή τη φορά, η χρήση του @code{S.rstrip()} λειτουργεί καλά.

@node Υπάρχει αντίστοιχο scanf ή sscanf ;,Τι σημαίνει το σφάλμα UnicodeDecodeError ή UnicodeEncodeError;,Υπάρχει ισοδύναμο με το Perl’s chomp για την αφαίρεση των νέων γραμμών από τις συμβολοσειρές;,Αριθμοί και συμβολοσειρές
@anchor{faq/programming is-there-a-scanf-or-sscanf-equivalent}@anchor{5c8f}
@subsubsection Υπάρχει αντίστοιχο @code{scanf()} ή @code{sscanf()};


Όχι ως τέτοιο.

Για απλή ανάλυση εισόδου, η ευκολότερη προσέγγιση είναι συνήθως ο διαχωρισμός της γραμμής σε λέξεις οριοθετημένες με κενά διαστήματα χρησιμοποιώντας τη μέθοδο @ref{125b,,split()} αντικειμένων συμβολοσειρών και στη συνέχεια μετατροπή δεκαδικών συμβολοσειρών σε αριθμητικές τιμές χρησιμοποιώντας @ref{326,,int()} ή @ref{327,,float()}.  @code{split()} υποστηρίζει μια προαιρετική παράμετρο «sep» που είναι χρήσιμη εάν η γραμμή χρησιμοποιεί κάτι διαφορετικό από κενό διάστημα ως διαχωριστικό.

Για πιο περίπλοκη ανάλυση εισόδου, τα regular expressions είναι πιο ισχυρά από τις @code{sscanf} της C και είναι πιο κατάλληλες για την εργασία.

@node Τι σημαίνει το σφάλμα UnicodeDecodeError ή UnicodeEncodeError;,Μπορώ να τερματίσω μια ακατέργαστη συμβολοσειρά με περιττό αριθμό backslashes;,Υπάρχει αντίστοιχο scanf ή sscanf ;,Αριθμοί και συμβολοσειρές
@anchor{faq/programming what-does-unicodedecodeerror-or-unicodeencodeerror-error-mean}@anchor{5c90}
@subsubsection Τι σημαίνει το σφάλμα @code{UnicodeDecodeError} ή @code{UnicodeEncodeError};


Βλ το @ref{1649,,Unicode HOWTO}.

@node Μπορώ να τερματίσω μια ακατέργαστη συμβολοσειρά με περιττό αριθμό backslashes;,,Τι σημαίνει το σφάλμα UnicodeDecodeError ή UnicodeEncodeError;,Αριθμοί και συμβολοσειρές
@anchor{faq/programming can-i-end-a-raw-string-with-an-odd-number-of-backslashes}@anchor{5c91}@anchor{faq/programming faq-programming-raw-string-backslash}@anchor{21cc}
@subsubsection Μπορώ να τερματίσω μια ακατέργαστη συμβολοσειρά με περιττό αριθμό backslashes;


Μια ακατέργαστη συμβολοσειρά που τελειώνει με περιττό αριθμό backslashes θα ξεφύγει από το απόσπασμα της συμβολοσειράς:

@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

Υπάρχουν αρκετές λύσεις για αυτό.  Ο ένας είναι να χρησιμοποιήσετε κανονικές συμβολοσειρές και να διπλασιάσετε τα backslashes:

@example
>>> 'C:\\this\\will\\work\\'
'C:\\this\\will\\work\\'
@end example

Ένα άλλο είναι να συνδέσετε μια κανονική συμβολοσειρά που περιέχει ένα escaped backslash στην ακατέργαστη συμβολοσειρά:

@example
>>> r'C:\this\will\work' '\\'
'C:\\this\\will\\work\\'
@end example

Είναι επίσης δυνατό να χρησιμοποιήσετε το @ref{1a42,,os.path.join()} για να προσθέσετε ένα backslash στα Windows:

@example
>>> os.path.join(r'C:\this\will\work', '@w{'})
'C:\\this\\will\\work\\'
@end example

Λάβετε υπόψη ότι ενώ ένα backslash θα «escape» από ένα εισαγωγικό για τον προσδιορισμό του σημείου που τελειώνει η ακατέργαστη συμβολοσειρά, δεν υπάρχει διαφυγή κατά την ερμηνεία της τιμής της ακατέργαστης συμβολοσειράς. Δηλαδή, το backslash παραμένει παρόν στην τιμή της ακατέργαστης συμβολοσειράς:

@example
>>> r'backslash\'preserved'
"backslash\\'preserved"
@end example

Δείτε επίσης την προδιαγραφή στην @ref{2490,,language reference}.

@node Απόδοση,Sequences tuples/lists,Αριθμοί και συμβολοσειρές,FAQ Προγραμματισμού
@anchor{faq/programming performance}@anchor{5c92}
@subsection Απόδοση


@menu
* Το πρόγραμμα μου είναι πολύ αργό. Πως μπορώ να το επιταχύνω;: Το πρόγραμμα μου είναι πολύ αργό Πως μπορώ να το επιταχύνω;. 
* Ποιος είναι ο πιο αποτελεσματικός τρόπος για να συνδέσετε πολλές συμβολοσειρές μεταξύ τους;:: 

@end menu

@node Το πρόγραμμα μου είναι πολύ αργό Πως μπορώ να το επιταχύνω;,Ποιος είναι ο πιο αποτελεσματικός τρόπος για να συνδέσετε πολλές συμβολοσειρές μεταξύ τους;,,Απόδοση
@anchor{faq/programming my-program-is-too-slow-how-do-i-speed-it-up}@anchor{5c93}
@subsubsection Το πρόγραμμα μου είναι πολύ αργό. Πως μπορώ να το επιταχύνω;


That’s a tough one, in general.  First, here is a list of things to
remember before diving further:


@itemize *

@item 
Τα χαρακτηριστικά απόδοσης διαφέρουν μεταξύ των υλοποιήσεων Python.  Αυτή η FAQ εστιάζει στο @ref{ae3,,CPython}.

@item 
Η συμπεριφορά μπορεί να διαφέρει μεταξύ των λειτουργικών συστημάτων, ειδικά όταν μιλάμε για I/O ή multi-threading.

@item 
Θα πρέπει πάντα να βρίσκετε τα hot spot στο πρόγραμμά σας `πριν' επιχειρήσετε να βελτιστοποιήσετε οποιονδήποτε κώδικα (βλ. το module @ref{b4,,profile}).

@item 
Η σύνταξη σεναρίων συγκριτικής αξιολόγησης θα σας επιτρέψει να κάνετε iterate γρήγορα κατά την αναζήτηση βελτιώσεων (βλ. το module @ref{f8,,timeit}).

@item 
Συνίσταται ανεπιφύλακτα να έχετε καλή κάλυψη κώδικα (μέσω unit testing ή οποιασδήποτε άλλης τεχνικής) πριν από την πιθανή εισαγωγή κρυμμένων παλινδρομήσεων (regressions) σε εξελιγμένες βελτιστοποιήσεις.
@end itemize

Τούτου λεχθέντος, υπάρχουν πολλά κόλπα για την επιτάχυνση του κώδικα Python.  Ακολουθούν ορισμένες γενικές αρχές που βοηθούν πολύ στην επίτευξη αποδεκτών επιπέδων απόδοσης:


@itemize *

@item 
Το να κάνετε τους αλγορίθμους σας πιο γρήγορους (ή να αλλάξετε σε ταχύτερους) μπορεί να αποφέρει πολύ μεγαλύτερα οφέλη από το να προσπαθείτε να σκορπίσετε κόλπα μικρό βελτιστοποίησης σε όλο τον κώδικά σας.

@item 
Χρησιμοποιήστε τις σωστές δομές δεδομένων. Μελετήστε την τεκμηρίωση για το @ref{27e3,,Τύποι Built-in} και το module @ref{1e,,collections}.

@item 
Όταν η τυπική βιβλιοθήκη παρέχει ένα πρωτόγονο για να κάνετε κάτι, είναι πιθανό (αν και δεν είναι εγγυημένο) να είναι πιο γρήγορο από οποιαδήποτε εναλλακτική λύση που μπορείτε να βρείτε. Αυτό ισχύει διπλά για πρωτόγονα γραμμένα σε C, όπως ενσωματωμένα και ορισμένους τύπους επεκτάσεων.  Για παράδειγμα, φροντίστε να χρησιμοποιήσετε είτε την ενσωματωμένη μέθοδο @ref{f8d,,list.sort()} είτε τη σχετική συνάρτηση @ref{f8c,,sorted()} για να κάνετε ταξινόμηση (και δείτε το @ref{27d9,,Sorting Techniques} για παραδείγματα μέτριος προηγμένης χρήσης).

@item 
Οι αφαιρέσεις τείνουν να δημιουργούν έμμεσες κατευθύνσεις και αναγκάζουν τον διερμηνέα να εργαστεί περισσότερο.  Εάν τα επίπεδα της έμμεσης κατεύθυνσης υπερτερούν του όγκου της χρήσιμης εργασίας που γίνεται, το πρόγραμμα σας θα είναι πιο αργό. Θα πρέπει να αποφύγετε την υπερβολική αφαίρεση, ειδικά με τη μορφή μικροσκοπικών συναρτήσεων ή μεθόδων (που είναι επίσης συχνά επιζήμια για την αναγνωσιμότητα).
@end itemize

Εάν έχετε φτάσει στο όριο του τι μπορεί να επιτρέπει η καθαρή Python, υπάρχουν εργαλεία που θα σας απομακρύνουν.  Για παράδειγμα, το Cython@footnote{https://cython.org} μπορεί να μεταγλωττίσει μια ελαφρώς τροποποιημένη έκδοση του κώδικα Python σε μια επέκταση C, και μπορεί να χρησιμοποιηθεί σε πολλές διαφορετικές πλατφόρμες. Η Cython μπορεί να εκμεταλλευτεί την μεταγλώττιση (και τους προαιρετικούς σχολιασμούς) για να κάνει τον κώδικα σας πολύ πιο γρήγορο από όταν ερμηνεύεται.  Εάν είστε σίγουροι για τις δεξιότητές σας στον προγραμματισμό C, μπορείτε επίσης να @ref{21aa,,write a C extension module} μόνοι σας.


@subsubheading Δείτε επίσης


Η σελίδα wiki που είναι αφιερωμένη σε συμβουλές απόδοσης@footnote{https://wiki.python.org/moin/PythonSpeed/PerformanceTips}.


@node Ποιος είναι ο πιο αποτελεσματικός τρόπος για να συνδέσετε πολλές συμβολοσειρές μεταξύ τους;,,Το πρόγραμμα μου είναι πολύ αργό Πως μπορώ να το επιταχύνω;,Απόδοση
@anchor{faq/programming efficient-string-concatenation}@anchor{5c94}@anchor{faq/programming what-is-the-most-efficient-way-to-concatenate-many-strings-together}@anchor{5c95}
@subsubsection Ποιος είναι ο πιο αποτελεσματικός τρόπος για να συνδέσετε πολλές συμβολοσειρές μεταξύ τους;


Τα αντικείμενα @ref{1df,,str} και @ref{1c7,,bytes} είναι αμετάβλητα, επομένως η σύνδεση πολλών συμβολοσειρών μεταξύ τους είναι αναποτελεσματική καθώς κάθε συνένωση δημιουργεί ένα νέο αντικείμενο.  Στη γενική περίπτωση, το συνολικό κόστος χρόνου εκτέλεσης είναι τετραγωνικό στο συνολικό μήκος συμβολοσειράς.

Για να συγκεντρώσετε πολλά αντικείμενα @ref{1df,,str}, το προτεινόμενο ιδίωμα είναι να τα τοποθετήσετε σε μια λίστα και να καλέσετε το στο @ref{2803,,str.join()} τέλος:

@example
chunks = []
for s in my_strings:
    chunks.append(s)
result = '@w{'}.join(chunks)
@end example

(Another reasonably efficient idiom is to use @ref{12d4,,io.StringIO}.)

Για τη συγκέντρωση πολλών αντικειμένων @ref{1c7,,bytes}, το συνιστώμενο ιδίωμα είναι η επέκταση ενός αντικειμένου @ref{1c6,,bytearray} χρησιμοποιώντας επιτόπια συνένωση (ο τελεστής @code{+=}):

@example
result = bytearray()
for b in my_bytes_objects:
    result += b
@end example

@node Sequences tuples/lists,Αντικείμενα,Απόδοση,FAQ Προγραμματισμού
@anchor{faq/programming sequences-tuples-lists}@anchor{5c96}
@subsection Sequences (tuples/lists)


@menu
* Πως μπορώ να κάνω μετατροπή μεταξύ πλειάδων και λιστών;:: 
* Τι είναι αρνητικός δείκτης;:: 
* Πώς μπορώ να επαναλάβω μια ακολουθία με αντίστροφη σειρά;:: 
* Πως αφαιρείτε διπλότυπα από μια λίστα;:: 
* How do you remove multiple items from a list?:: 
* Πως μπορείτε να φτιάξετε έναν πίνακα στην Python;:: 
* Πως φτιάχνω μια πολυδιάστατη λίστα;:: 
* Πώς μπορώ να εφαρμόσω μια μέθοδο ή μια συνάρτηση σε μια ακολουθία αντικειμένων;:: 
* Γιατί το a_tuple[i] += [“item”] δημιουργεί μια εξαίρεση όταν λειτουργεί η προσθήκη;:: 
* Θέλω να κάνω μια περίπλοκη ταξινόμηση; μπορείτε να κάνετε ένα Schwartzian Transform στην Python;: Θέλω να κάνω μια περίπλοκη ταξινόμηση μπορείτε να κάνετε ένα Schwartzian Transform στην Python;. 
* Πως μπορώ να ταξινομήσω μια λίστα με βάση τις τιμές από μια άλλη λίστα;:: 

@end menu

@node Πως μπορώ να κάνω μετατροπή μεταξύ πλειάδων και λιστών;,Τι είναι αρνητικός δείκτης;,,Sequences tuples/lists
@anchor{faq/programming how-do-i-convert-between-tuples-and-lists}@anchor{5c97}
@subsubsection Πως μπορώ να κάνω μετατροπή μεταξύ πλειάδων και λιστών;


Ο κατασκευαστής τύπου @code{tuple(seq)} μετατρέπει οποιαδήποτε ακολουθία (στην πραγματικότητα οποιοδήποτε iterable) σε πλειάδα με τα ίδια στοιχεία στην ίδια σειρά.

Για παράδειγμα, το @code{tuple([1, 2, 3])} αποδίδει @code{(1, 2, 3)} και το @code{tuple('abc')} αποδίδει @code{('a', 'b', 'c')}.  Εάν το όρισμα είναι πλειάδα, δεν δημιουργεί αντίγραφο αλλά επιστρέφει το ίδιο αντικείμενο, επομένως είναι φτηνό να καλέσετε το @ref{1ce,,tuple()} όταν δεν είστε σίγουροι ότι ένα αντικείμενο είναι ήδη πλειάδα.

Ο κατασκευαστής τύπων @code{list(seq)} μετατρέπει οποιαδήποτε ακολουθία ή iterable σε μια λίστα με τα ίδια στοιχεία στην ίδια σειρά. Για παράδειγμα, το @code{list((1, 2, 3))} αποδίδει @code{[1, 2, 3]} και @code{list('abc')} αποδίδει @code{['a', 'b', 'c']}.  Αν το όρισμα είναι λίστα, δημιουργεί απλώς ένα αντίγραφο όπως θα έκανε το @code{seq[:]}.

@node Τι είναι αρνητικός δείκτης;,Πώς μπορώ να επαναλάβω μια ακολουθία με αντίστροφη σειρά;,Πως μπορώ να κάνω μετατροπή μεταξύ πλειάδων και λιστών;,Sequences tuples/lists
@anchor{faq/programming what-s-a-negative-index}@anchor{5c98}
@subsubsection Τι είναι αρνητικός δείκτης;


Οι ακολουθίες Python indexed με θετικούς αριθμούς και αρνητικούς αριθμούς.  Για θετικούς αριθμούς το 0 είναι ο πρώτος δείκτης 1 είναι ο δεύτερος δείκτης και ούτω καθεξής.  Για αρνητικούς δείκτες το -1 είναι ο τελευταίος δείκτης και το -2 είναι ο προτελευταίος (δίπλα στο τελευταίο) δείκτης και ούτω καθεξής.  Σκεφτείτε το @code{seq[-n]} ως το ίδιο με το @code{seq[len(seq)-n]}.

Η χρήση αρνητικών δεικτών μπορεί ναι είναι πολύ βολική.  Για παράδειγμα @code{S[:-1]} είναι όλη η συμβολοσειρά εκτός από τον τελευταίο χαρακτήρα της, ο οποίος είναι χρήσιμος για την αφαίρεση της νέας γραμμής που ακολουθεί μια συμβολοσειρά.

@node Πώς μπορώ να επαναλάβω μια ακολουθία με αντίστροφη σειρά;,Πως αφαιρείτε διπλότυπα από μια λίστα;,Τι είναι αρνητικός δείκτης;,Sequences tuples/lists
@anchor{faq/programming how-do-i-iterate-over-a-sequence-in-reverse-order}@anchor{5c99}
@subsubsection Πώς μπορώ να επαναλάβω μια ακολουθία με αντίστροφη σειρά;


Χρησιμοποιείστε την ενσωματωμένη συνάρτηση @ref{c3c,,reversed()}:

@example
for x in reversed(sequence):
    ...  # do something with x ...
@end example

Αυτό δεν θα επηρεάσει την αρχική σας ακολουθία, αλλά δημιουργήστε ένα νέο αντίγραφο με αντίστροφη σειρά για επανάληψη.

@node Πως αφαιρείτε διπλότυπα από μια λίστα;,How do you remove multiple items from a list?,Πώς μπορώ να επαναλάβω μια ακολουθία με αντίστροφη σειρά;,Sequences tuples/lists
@anchor{faq/programming how-do-you-remove-duplicates-from-a-list}@anchor{5c9a}
@subsubsection Πως αφαιρείτε διπλότυπα από μια λίστα;


Δείτε το Python Cookbook για μια μακρά συζήτηση σχετικά με πολλούς τρόπους για να το κάνετε αυτό:

@quotation

@indicateurl{https://code.activestate.com/recipes/52560/}
@end quotation

Εάν δεν σας πειράζει να αναδιατάξετε τη λίστα, ταξινομήστε την και μετά σαρώστε από το τέλος της λίστας, διαγράφοντας τα διπλότυπα καθώς προχωράτε:

@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

If all elements of the list may be used as set keys (that is, they are all
@ref{183,,hashable}) this is often faster:

@example
mylist = list(set(mylist))
@end example

Αυτό μετατρέπει τη λίστα σε ένα σύνολο, αφαιρώντας έτσι τα διπλότυπα και στη συνέχεια ξανά σε λίστα.

@node How do you remove multiple items from a list?,Πως μπορείτε να φτιάξετε έναν πίνακα στην Python;,Πως αφαιρείτε διπλότυπα από μια λίστα;,Sequences tuples/lists
@anchor{faq/programming how-do-you-remove-multiple-items-from-a-list}@anchor{5c9b}
@subsubsection How do you remove multiple items from a list?


As with removing duplicates, explicitly iterating in reverse with a
delete condition is one possibility.  However, it is easier and faster
to use slice replacement with an implicit or explicit forward iteration.
Here are three variations:

@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

Το comprehension της λίστας μπορεί να είναι ταχύτερο.

@node Πως μπορείτε να φτιάξετε έναν πίνακα στην Python;,Πως φτιάχνω μια πολυδιάστατη λίστα;,How do you remove multiple items from a list?,Sequences tuples/lists
@anchor{faq/programming how-do-you-make-an-array-in-python}@anchor{5c9c}
@subsubsection Πως μπορείτε να φτιάξετε έναν πίνακα στην Python;


Χρησιμοποιήστε μια λίστα:

@example
["αυτή", 1, "είναι", "μια", "λίστα"]
@end example

Οι λίστες είναι ισοδύναμες με τους πίνακες της C ή Pascal στην χρονική τους πολυπλοκότητα∙ η κύρια διαφορά είναι ότι μια λίστα Python μπορεί να περιέχει αντικείμενα πολλών διαφορετικών τύπων.

The @code{array} module also provides methods for creating arrays of fixed types
with compact representations, but they are slower to index than lists.  Also
note that NumPy@footnote{https://numpy.org/}
and other third-party packages define array-like structures with
various characteristics as well.

Για να λάβετε συνδεδεμένες λίστες τύπου Lisp, μπορείτε να εξομοιώσετε `cons κελιά' χρησιμοποιώντας πλειάδες:

@example
lisp_list = ("όπως",  ("αυτό",  ("το παράδειγμα", None) ) )
@end example

Εάν είναι επιθυμητή η μεταβλητότητα, μπορείτε να χρησιμοποιήσετε λίστες αντί για πλειάδες.  Εδώ το ανάλογο ενός Lisp `car' είναι @code{lisp_list[0]} και το ανάλογο του `cdr' είναι @code{lisp_list[1]}.  Μόνο κάντε το αν είστε βέβαιοι ότι πραγματικά χρειάζεται, γιατί είναι συνήθως πιο αργό και από τη χρήση λιστών Python.

@node Πως φτιάχνω μια πολυδιάστατη λίστα;,Πώς μπορώ να εφαρμόσω μια μέθοδο ή μια συνάρτηση σε μια ακολουθία αντικειμένων;,Πως μπορείτε να φτιάξετε έναν πίνακα στην Python;,Sequences tuples/lists
@anchor{faq/programming faq-multidimensional-list}@anchor{2802}@anchor{faq/programming how-do-i-create-a-multidimensional-list}@anchor{5c9d}
@subsubsection Πως φτιάχνω μια πολυδιάστατη λίστα;


Μάλλον προσπαθήσατε να φτιάξετε έναν πολυδιάστατο πίνακα σαν αυτόν:

@example
>>> A = [[None] * 2] * 3
@end example

Αυτό φαίνεται σωστό αν το εκτυπώσετε:

@c A = [[None] * 2] * 3

@example
>>> A
[[None, None], [None, None], [None, None]]
@end example

Αλλά όταν εκχωρείτε μια τιμή, εμφανίζεται σε πολλά σημεία:

@c A = [[None] * 2] * 3

@example
>>> A[0][0] = 5
>>> A
[[5, None], [5, None], [5, None]]
@end example

Ο λόγος είναι ότι η αναπαραγωγή μιας λίστα με @code{*} δεν δημιουργεί αντίγραφα, δημιουργεί μόνο αναφορές στα υπάρχοντα αντικείμενα.  Το @code{*3} δημιουργεί μια λίστα που περιέχει 3 αναφορές στην ίδια λίστα μήκους δύο.  Οι αλλαγές σε μία σειρά θα εμφανίζονται σε όλες τις σειρές, κάτι που σχεδόν σίγουρα δεν είναι αυτό που θέλετε.

Η προτεινόμενη προσέγγιση είναι να δημιουργήσετε πρώτα μια λίστα με το επιθυμητό μήκος και στη συνέχεια να συμπληρώσετε κάθε στοιχείο με μια νέα λίστα:

@example
A = [None] * 3
for i in range(3):
    A[i] = [None] * 2
@end example

Αυτό δημιουργεί μια λίστα που περιέχει 3 διαφορετικές λίστες με μήκος δύο.  Μπορείτε επίσης να χρησιμοποιήσετε ένα comprehension λίστας:

@example
w, h = 2, 3
A = [[None] * w for i in range(h)]
@end example

Εναλλακτικά, μπορείτε να χρησιμοποιήσετε μια επέκταση που παρέχει έναν τύπο δεδομένων μήτρας (matrix)∙ Το NumPy@footnote{https://numpy.org/} είναι το πιο γνωστό.

@node Πώς μπορώ να εφαρμόσω μια μέθοδο ή μια συνάρτηση σε μια ακολουθία αντικειμένων;,Γιατί το a_tuple[i] += [“item”] δημιουργεί μια εξαίρεση όταν λειτουργεί η προσθήκη;,Πως φτιάχνω μια πολυδιάστατη λίστα;,Sequences tuples/lists
@anchor{faq/programming how-do-i-apply-a-method-or-function-to-a-sequence-of-objects}@anchor{5c9e}
@subsubsection Πώς μπορώ να εφαρμόσω μια μέθοδο ή μια συνάρτηση σε μια ακολουθία αντικειμένων;


To call a method or function and accumulate the return values in a list,
a @ref{abb,,list comprehension} is an elegant solution:

@example
result = [obj.method() for obj in mylist]

result = [function(obj) for obj in mylist]
@end example

Για να εκτελέσετε απλώς τη μέθοδο ή τη συνάρτηση χωρίς να αποθηκεύσετε τις επιστρεφόμενες τιμές, αρκεί ένας απλός βρόχος @ref{321,,for}:

@example
for obj in mylist:
    obj.method()

for obj in mylist:
    function(obj)
@end example

@node Γιατί το a_tuple[i] += [“item”] δημιουργεί μια εξαίρεση όταν λειτουργεί η προσθήκη;,Θέλω να κάνω μια περίπλοκη ταξινόμηση μπορείτε να κάνετε ένα Schwartzian Transform στην Python;,Πώς μπορώ να εφαρμόσω μια μέθοδο ή μια συνάρτηση σε μια ακολουθία αντικειμένων;,Sequences tuples/lists
@anchor{faq/programming faq-augmented-assignment-tuple-error}@anchor{25f7}@anchor{faq/programming why-does-a-tuple-i-item-raise-an-exception-when-the-addition-works}@anchor{5c9f}
@subsubsection Γιατί το a_tuple[i] += [“item”] δημιουργεί μια εξαίρεση όταν λειτουργεί η προσθήκη;


Αυτό οφείλεται σε έναν συνδυασμό του γεγονότος ότι οι επαυξημένοι τελεστές εκχώρησης είναι τελεστές `εκχώρησης' και της διαφοράς μεταξύ μεταβλητών και αμετάβλητων αντικειμένων στην Python.

Αυτή η συζήτηση ισχύει γενικά όταν οι επαυξημένοι τελεστές εκχώρησης εφαρμόζονται σε στοιχεία μιας πλειάδας που δείχνουν σε μεταβλητά αντικείμενα, αλλά θα χρησιμοποιήσουμε @code{list} και @code{+=} ως υπόδειγμά μας.

Εάν γράψετε:

@example
>>> a_tuple = (1, 2)
>>> a_tuple[0] += 1
Traceback (most recent call last):
   ...
TypeError: 'tuple' object does not support item assignment
@end example

Ο λόγος για την εξαίρεση θα πρέπει να είναι αμέσως σαφής:  το @code{1} προστίθεται στο αντικείμενο @code{a_tuple[0]} δείχνει στο (@code{1}), παράγοντας το αντικείμενο αποτελέσματος, @code{2}, αλλά όταν προσπαθούμε να αντιστοιχίσουμε το αποτέλεσμα του υπολογισμού, @code{2}, στο στοιχείο @code{0} της πλειάδας, λαμβάνουμε ένα σφάλμα επειδή δεν μπορούμε να αλλάξουμε αυτό που δείχνει ένα στοιχείο μιας πλειάδας.

Κάτω από τα καλύμματα, αυτό που κάνει αυτή η επαυξημένη δήλωση ανάθεσης είναι περίπου το εξής:

@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

Είναι το τμήμα ανάθεσης της λειτουργίας που παράγει το σφάλμα, αφού μια πλειάδα είναι αμετάβλητη.

Όταν γράφετε κάτι σαν:

@example
>>> a_tuple = (['foo'], 'bar')
>>> a_tuple[0] += ['item']
Traceback (most recent call last):
  ...
TypeError: 'tuple' object does not support item assignment
@end example

Η εξαίρεση είναι λίγο πιο εκπληκτική, και ακόμη πιο εκπληκτικό είναι το γεγονός ότι παρόλο που υπήρχε ένα σφάλμα, το παράρτημα λειτούργησε:

@example
>>> a_tuple[0]
['foo', 'item']
@end example

Για να δείτε γιατί συμβαίνει αυτό, πρέπει να γνωρίζετε ότι (α) εάν ένα αντικείμενο υλοποιεί μια μαγική μέθοδο @ref{25d4,,__iadd__()}, που καλείται όταν εκτελείται η επαυξημένη ανάθεση @code{+=} και η τιμή επιστροφής είναι αυτή που χρησιμοποιείται στη δήλωση εκχώρησης∙ και (β) για λίστες, @code{__iadd__()} ισοδυναμεί με την κλήση του @ref{25ce,,extend()} στη λίστα και επιστρέφει τη λίστα.  Για αυτό λέμε ότι για λίστες @code{+=} είναι μια «συντομογραφία» για @ref{7f8,,list.extend()}:

@example
>>> a_list = []
>>> a_list += [1]
>>> a_list
[1]
@end example

Αυτό ισοδυναμεί με:

@example
>>> result = a_list.__iadd__([1])
>>> a_list = result
@end example

Το αντικείμενο στο οποίο υποδεικνύεται από το a_list έχει μεταλλαχθεί και ο δείκτης στο μεταλλαγμένο αντικείμενο έχει εκχωρηθεί πίσω στο @code{a_list}.  Το τελικό αποτέλεσμα της ανάθεσης είναι ένα no-op, καθώς είναι ένας δείκτης στο ίδιο αντικείμενο που το @code{a_list} έδειχνε προηγουμένως, αλλά η ανάθεση εξακολουθεί να γίνεται.

Έτσι, στο παράδειγμά μας, αυτό που συμβαίνει είναι ισοδύναμο με:

@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

Το @code{__iadd__()} πετυχαίνει, και έτσι η λίστα επεκτείνεται, αλλά παρόλο που το @code{αποτέλεσμα} δείχνει στο ίδιο αντικείμενο που δείχνει ήδη το @code{a_tuple[0]}, αυτή η τελική ανάθεση εξακολουθεί να έχει ως αποτέλεσμα ένα λάθος, γιατί οι πλειάδες είναι αμετάβλητες.

@node Θέλω να κάνω μια περίπλοκη ταξινόμηση μπορείτε να κάνετε ένα Schwartzian Transform στην Python;,Πως μπορώ να ταξινομήσω μια λίστα με βάση τις τιμές από μια άλλη λίστα;,Γιατί το a_tuple[i] += [“item”] δημιουργεί μια εξαίρεση όταν λειτουργεί η προσθήκη;,Sequences tuples/lists
@anchor{faq/programming i-want-to-do-a-complicated-sort-can-you-do-a-schwartzian-transform-in-python}@anchor{5ca0}
@subsubsection Θέλω να κάνω μια περίπλοκη ταξινόμηση: μπορείτε να κάνετε ένα Schwartzian Transform στην Python;


Η τεχνική, που αποδίδεται στον Randal Schwartz της κοινότητας Perl, ταξινομεί τα στοιχεία μιας λίστας με βάση μια μέτρηση που αντιστοιχίζει κάθε στοιχείο στην « τιμή ταξινόμησης» του.  Στην Python, χρησιμοποιήστε το όρισμα @code{key} για τη μέθοδο @ref{f8d,,list.sort()}:

@example
Isorted = L[:]
Isorted.sort(key=lambda s: int(s[10:15]))
@end example

@node Πως μπορώ να ταξινομήσω μια λίστα με βάση τις τιμές από μια άλλη λίστα;,,Θέλω να κάνω μια περίπλοκη ταξινόμηση μπορείτε να κάνετε ένα Schwartzian Transform στην Python;,Sequences tuples/lists
@anchor{faq/programming how-can-i-sort-one-list-by-values-from-another-list}@anchor{5ca1}
@subsubsection Πως μπορώ να ταξινομήσω μια λίστα με βάση τις τιμές από μια άλλη λίστα;


Merge them into an iterator of tuples, sort the resulting list, and then pick
out the element you want.

@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 Αντικείμενα,Modules<5>,Sequences tuples/lists,FAQ Προγραμματισμού
@anchor{faq/programming objects}@anchor{5ca2}
@subsection Αντικείμενα


@menu
* Τι είναι μια κλάση;:: 
* Τι είναι μια μέθοδος;:: 
* Τι είναι το self;:: 
* Πώς μπορώ να ελέγξω εάν ένα αντικείμενο είναι μια οντότητα μιας δεδομένης κλάσης ή μιας υποκλάσης της;:: 
* Τι είναι το delegation;:: 
* Πώς μπορώ να καλέσω μια μέθοδο που ορίζεται σε μια βασική κλάση από μια παράγωγη κλάση που την επεκτείνει;:: 
* Πως μπορώ να οργανώσω τον κώδικα μου προκειμένου να διευκολύνω την αλλαγή της βασικής κλάσης;:: 
* Πως δημιουργώ δεδομένα στατικής κλάσης και μεθόδους στατικής κλάσης;:: 
* Πως μπορώ να υπερφορτώσω κατασκευαστές (ή μεθόδους) στην Python;: Πως μπορώ να υπερφορτώσω κατασκευαστές ή μεθόδους στην Python;. 
* Προσπαθώ να χρησιμοποιήσω __spam και λαμβάνω ένα σφάλμα σχετικά με το _SomeClassName__spam.: Προσπαθώ να χρησιμοποιήσω __spam και λαμβάνω ένα σφάλμα σχετικά με το _SomeClassName__spam. 
* Η κλάση μου ορίζει __del__ αλλά δεν καλείται όταν διαγράφω το αντικείμενο.: Η κλάση μου ορίζει __del__ αλλά δεν καλείται όταν διαγράφω το αντικείμενο. 
* Πως μπορώ να λάβω μια λίστα με όλες τις οντότητες μιας δεδομένης κλάσης;:: 
* Γιατί το αποτέλεσμα του id() φαίνεται να μην είναι μοναδικό;: Γιατί το αποτέλεσμα του id φαίνεται να μην είναι μοναδικό;. 
* Πότε μπορώ να βασιστώ σε δοκιμές ταυτότητας με τον τελεστή is;:: 
* Πώς μπορεί μια υποκλάση να ελέγξει ποια δεδομένα αποθηκεύονται σε μια αμετάβλητη παρουσία;:: 
* Πώς μπορώ να αποθηκεύσω τις κλήσεις μεθόδου στην κρυφή μνήμη;:: 

@end menu

@node Τι είναι μια κλάση;,Τι είναι μια μέθοδος;,,Αντικείμενα
@anchor{faq/programming what-is-a-class}@anchor{5ca3}
@subsubsection Τι είναι μια κλάση;


Μια κλάση είναι ο συγκεκριμένος τύπος αντικειμένου που δημιουργείται με την εκτέλεση μιας δήλωσης κλάσης. Τα αντικείμενα κλάσης χρησιμοποιούνται ως πρότυπα για τη δημιουργία αντικειμένων παρουσίας, τα οποία ενσωματώνουν τόσο τα δεδομένα (χαρακτηριστικά) όσο και τον κώδικα (μεθόδους) ειδικά για έναν τύπο δεδομένων.

Μια κλάση μπορεί να βασίζεται σε μία ή περισσότερες άλλες κλάσεις, που ονομάζονται βασικές κλάσεις της. Στη συνέχεια κληρονομεί τα χαρακτηριστικά και τις μεθόδους των βασικών κλάσεων. Αυτό επιτρέπει σε ένα μοντέλο αντικειμένου να βελτιωθεί διαδοχικά με κληρονομικότητα.  Μπορεί να έχετε μια γενική κλάση @code{Mailbox} που παρέχει βασικές μεθόδους πρόσβασης για ένα γραμματοκιβώτιο και υποκλάσεις όπως @code{MboxMailbox}, @code{MaildirMailbox}, @code{OutlookMailbox} που χειρίζονται διάφορες συγκεκριμένες μορφές γραμματοκιβωτίου.

@node Τι είναι μια μέθοδος;,Τι είναι το self;,Τι είναι μια κλάση;,Αντικείμενα
@anchor{faq/programming what-is-a-method}@anchor{5ca4}
@subsubsection Τι είναι μια μέθοδος;


Μια μέθοδος είναι μια συνάρτηση σε κάποιο αντικείμενο @code{x} που συνήθως καλείτε ως @code{x.name(ορίσματα...)}. Οι μέθοδοι ορίζονται ως συναρτήσεις εντός του ορισμού κλάσης:

@example
class C:
    def meth(self, arg):
        return arg * 2 + self.attribute
@end example

@node Τι είναι το self;,Πώς μπορώ να ελέγξω εάν ένα αντικείμενο είναι μια οντότητα μιας δεδομένης κλάσης ή μιας υποκλάσης της;,Τι είναι μια μέθοδος;,Αντικείμενα
@anchor{faq/programming what-is-self}@anchor{5ca5}
@subsubsection Τι είναι το self;


Το self είναι απλώς ένα συμβατικό όνομα για το πρώτο όρισμα μιας μεθόδου.  Μια μέθοδος που ορίζεται ως @code{meth(self, a, b, c)} πρέπει να ονομάζεται @code{x.meth(a, b, c)} για κάποιο παράδειγμα @code{x} της κλάσης στην οποία εμφανίζεται ο ορισμός∙ η καλούμενη μέθοδος θα ονομάζεται @code{meth(x, a, b, c)}.

Βλ. επίσης @ref{5ca6,,Why must “self” be used explicitly in method definitions and calls?}.

@node Πώς μπορώ να ελέγξω εάν ένα αντικείμενο είναι μια οντότητα μιας δεδομένης κλάσης ή μιας υποκλάσης της;,Τι είναι το delegation;,Τι είναι το self;,Αντικείμενα
@anchor{faq/programming how-do-i-check-if-an-object-is-an-instance-of-a-given-class-or-of-a-subclass-of-it}@anchor{5ca7}
@subsubsection Πώς μπορώ να ελέγξω εάν ένα αντικείμενο είναι μια οντότητα μιας δεδομένης κλάσης ή μιας υποκλάσης της;


Use the built-in function @ref{2ef,,isinstance(obj@comma{} cls)}.  You can
check if an object
is an instance of any of a number of classes by providing a tuple instead of a
single class, for example, @code{isinstance(obj, (class1, class2, ...))}, and can also
check whether an object is one of Python’s built-in types, for example,
@code{isinstance(obj, str)} or @code{isinstance(obj, (int, float, complex))}.

Note that @ref{2ef,,isinstance()} also checks for virtual inheritance from an
@ref{155f,,abstract base class}.  So, the test will return @code{True} for a
registered class even if hasn’t directly or indirectly inherited from it.  To
test for «true inheritance», scan the @ref{2784,,method resolution order} (MRO) of
the class:

@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__
@end example

Λάβετε υπόψη ότι τα περισσότερα προγράμματα δεν χρησιμοποιούν το @ref{2ef,,isinstance()} σε κλάσεις που ορίζονται από τη χρήστη πολύ συχνά.  Εάν αναπτύσσετε μόνοι σας τις κλάσεις, ένα πιο σωστό αντικειμενοστρεφής στυλ είναι να ορίζετε μεθόδους στις κλάσεις που ενσωματώνουν μια συγκεκριμένη συμπεριφορά, αντί να ελέγχετε την κλάση του αντικειμένου και να κάνετε κάτι διαφορετικό με βάση την κλάση που είναι, για παράδειγμα, εάν έχετε μια συνάρτηση που κάνει κάτι:

@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

Μια καλύτερη προσέγγιση είναι να ορίσετε μια μέθοδο @code{search()} σε όλες τις κλάσεις και απλώς να την καλέσετε:

@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 Τι είναι το delegation;,Πώς μπορώ να καλέσω μια μέθοδο που ορίζεται σε μια βασική κλάση από μια παράγωγη κλάση που την επεκτείνει;,Πώς μπορώ να ελέγξω εάν ένα αντικείμενο είναι μια οντότητα μιας δεδομένης κλάσης ή μιας υποκλάσης της;,Αντικείμενα
@anchor{faq/programming what-is-delegation}@anchor{5ca8}
@subsubsection Τι είναι το delegation;


Delegation is an object-oriented technique (also called a design pattern).
Let’s say you have an object @code{x} and want to change the behaviour of just one
of its methods.  You can create a new class that provides a new implementation
of the method you’re interested in changing and delegates all other methods to
the corresponding method of @code{x}.

Οι προγραμματιστές Python μπορούν εύκολα να υλοποιήσουν την ανάθεση.  Για παράδειγμα, η ακόλουθη κλάση υλοποιεί μια κλάση που συμπεριφέρεται σαν αρχείο αλλά μετατρέπει όλα τα γραπτά δεδομένα σε κεφαλαία:

@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

Εδώ η κλάση @code{UpperOut} επαναπροσδιορίζει τη μέθοδο @code{write()} για να μετατρέψει τη συμβολοσειρά ορίσματος σε κεφαλαία πριν καλέσει την υποκείμενη μέθοδο @code{self._outfile.write()}.  Όλες οι άλλες μέθοδοι εκχωρούνται στο υποκείμενο αντικείμενο @code{self._outfile}.  Το delegation ολοκληρώνεται μέσω της μεθόδου @ref{8e3,,__getattr__()}. Συμβουλευτείτε το @ref{25a4,,the language reference} για περισσότερες πληροφορίες σχετικά με τον έλεγχο της πρόσβασης.

Λάβετε υπόψη ότι για πιο γενικές περιπτώσεις η ανάθεση μπορεί να γίνει πιο δύσκολη. Όταν τα χαρακτηριστικά πρέπει να οριστούν καθώς και να ανακτηθούν, η κλάση πρέπει να ορίσει μια μέθοδο @ref{256d,,__setattr__()} επίσης, και πρέπει να το κάνει προσεκτικά.  Η βασική υλοποίηση του @code{__setattr__()} είναι περίπου ισοδύναμο με το εξής:

@example
class X:
    ...
    def __setattr__(self, name, value):
        self.__dict__[name] = value
    ...
@end example

Πολλές υλοποιήσεις @ref{256d,,__setattr__()} καλούν την :@code{object.__setattr__()} για να θέσουν μια μεταβλητή  στον εαυτό τους χωρίς να προκαλούν άπειρη αναδρομή.

@example
class X:
    def __setattr__(self, name, value):
        # Custom logic here...
        object.__setattr__(self, name, value)
@end example

Εναλλακτικά, είναι δυνατό να ορίσετε χαρακτηριστικά εισάγοντας καταχωρήσεις στο @ref{1bf,,self.__dict__} απευθείας.

@node Πώς μπορώ να καλέσω μια μέθοδο που ορίζεται σε μια βασική κλάση από μια παράγωγη κλάση που την επεκτείνει;,Πως μπορώ να οργανώσω τον κώδικα μου προκειμένου να διευκολύνω την αλλαγή της βασικής κλάσης;,Τι είναι το delegation;,Αντικείμενα
@anchor{faq/programming how-do-i-call-a-method-defined-in-a-base-class-from-a-derived-class-that-extends-it}@anchor{5ca9}
@subsubsection Πώς μπορώ να καλέσω μια μέθοδο που ορίζεται σε μια βασική κλάση από μια παράγωγη κλάση που την επεκτείνει;


Χρησιμοποιήστε την ενσωματωμένη συνάρτηση @ref{443,,super()}:

@example
class Derived(Base):
    def meth(self):
        super().meth()  # calls Base.meth
@end example

Στο παράδειγμα, το @ref{443,,super()} θα προσδιορίσει αυτόματα το στιγμιότυπο από το οποίο κλήθηκε (η τιμή @code{self}), αναζητήστε τη @ref{2784,,method resolution order} (MRO) με @code{type(self).__mro__}, και επιστρέψτε το επόμενο στη σειρά μετά το @code{Derived} στο MRO: @code{Base}.

@node Πως μπορώ να οργανώσω τον κώδικα μου προκειμένου να διευκολύνω την αλλαγή της βασικής κλάσης;,Πως δημιουργώ δεδομένα στατικής κλάσης και μεθόδους στατικής κλάσης;,Πώς μπορώ να καλέσω μια μέθοδο που ορίζεται σε μια βασική κλάση από μια παράγωγη κλάση που την επεκτείνει;,Αντικείμενα
@anchor{faq/programming how-can-i-organize-my-code-to-make-it-easier-to-change-the-base-class}@anchor{5caa}
@subsubsection Πως μπορώ να οργανώσω τον κώδικα μου προκειμένου να διευκολύνω την αλλαγή της βασικής κλάσης;


You could assign the base class to an alias and derive from the alias.  Then all
you have to change is the value assigned to the alias.  Incidentally, this trick
is also handy if you want to decide dynamically (such as depending on availability
of resources) which base class to use.  Example:

@example
class Base:
    ...

BaseAlias = Base

class Derived(BaseAlias):
    ...
@end example

@node Πως δημιουργώ δεδομένα στατικής κλάσης και μεθόδους στατικής κλάσης;,Πως μπορώ να υπερφορτώσω κατασκευαστές ή μεθόδους στην Python;,Πως μπορώ να οργανώσω τον κώδικα μου προκειμένου να διευκολύνω την αλλαγή της βασικής κλάσης;,Αντικείμενα
@anchor{faq/programming how-do-i-create-static-class-data-and-static-class-methods}@anchor{5cab}
@subsubsection Πως δημιουργώ δεδομένα στατικής κλάσης και μεθόδους στατικής κλάσης;


Τόσο τα στατιστικά δεδομένα όσο και οι στατικές μέθοδοι (με την έννοια της C++ ή της Java) υποστηρίζονται στην Python.

Για στατικά δεδομένα, απλώς ορίστε ένα χαρακτηριστικό κλάσης.  Για να εκχωρήσετε μια νέα τιμή στο χαρακτηριστικό, πρέπει να χρησιμοποιήσετε ρητά το όνομα κλάσης στην εκχώρηση:

@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} αναφέρεται επίσης στο @code{C.count} για οποιοδήποτε @code{c}, έτσι ώστε να ισχύει το @code{isinstance(c, C)}, εκτός εάν παρακαμφθεί από το ίδιο το @code{c} ή από κάποια κλάση στη διαδρομή αναζήτησης της βασικής κλάσης από το @code{c.__class__} πίσω στο @code{C}.

Προσοχή: σε μια μέθοδο του C, μια ανάθεση όπως @code{self.count = 42} δημιουργεί μια νέα και άσχετη παρουσία με το όνομα «count» στο δικό του dict του @code{self}.  Επανασύνδεση μιας κλάσης-στατικής όνομα δεδομένων πρέπει πάντα να προσδιορίζει την κλάση είτε βρίσκεται μέσα σε μια μέθοδο είτε όχι:

@example
C.count = 314
@end example

Οι στατικές μέθοδοι είναι δυνατές:

@example
class C:
    @@staticmethod
    def static(arg1, arg2, arg3):
        # No 'self' parameter!
        ...
@end example

Ωστόσο, ένας πολύ πιο απλός τρόπος για να λάβετε το αποτέλεσμα μιας στατικής μεθόδου είναι μέσω μιας απλής συνάρτησης σε επίπεδο μονάδας:

@example
def getcount():
    return C.count
@end example

Εάν ο κώδικας σας είναι δομημένος έτσι ώστε να ορίζει μία κλάση (ή στενά συνδεδεμένη ιεραρχίας κλάσεων) ανά module, αυτό παρέχει την επιθυμητή ενθυλάκωση.

@node Πως μπορώ να υπερφορτώσω κατασκευαστές ή μεθόδους στην Python;,Προσπαθώ να χρησιμοποιήσω __spam και λαμβάνω ένα σφάλμα σχετικά με το _SomeClassName__spam,Πως δημιουργώ δεδομένα στατικής κλάσης και μεθόδους στατικής κλάσης;,Αντικείμενα
@anchor{faq/programming how-can-i-overload-constructors-or-methods-in-python}@anchor{5cac}
@subsubsection Πως μπορώ να υπερφορτώσω κατασκευαστές (ή μεθόδους) στην Python;


Αυτή η απάντηση ισχύει στην πραγματικότητα για όλες τις μεθόδους, αλλά η ερώτηση συνήθως εμφανίζεται πρώτη στο πλαίσιο των κατασκευαστών.

In C++ you’d write:

@example
class C @{
    C() @{ cout << "No arguments\n"; @}
    C(int i) @{ cout << "Argument is " << i << "\n"; @}
@}
@end example

Στην Python πρέπει να γράψετε έναν μοναδικό κατασκευαστή που να πιάνει όλες τις περιπτώσεις χρησιμοποιώντας προεπιλεγμένα ορίσματα.  Για παράδειγμα:

@example
class C:
    def __init__(self, i=None):
        if i is None:
            print("No arguments")
        else:
            print("Argument is", i)
@end example

Αυτό δεν είναι εντελώς ισοδύναμο, αλλά αρκετά κοντά στην πράξη.

You could also try a variable-length argument list, for example:

@example
def __init__(self, *args):
    ...
@end example

Η ίδια προσέγγιση λειτουργεί για όλους τους ορισμούς μεθόδων.

@node Προσπαθώ να χρησιμοποιήσω __spam και λαμβάνω ένα σφάλμα σχετικά με το _SomeClassName__spam,Η κλάση μου ορίζει __del__ αλλά δεν καλείται όταν διαγράφω το αντικείμενο,Πως μπορώ να υπερφορτώσω κατασκευαστές ή μεθόδους στην Python;,Αντικείμενα
@anchor{faq/programming i-try-to-use-spam-and-i-get-an-error-about-someclassname-spam}@anchor{5cad}
@subsubsection Προσπαθώ να χρησιμοποιήσω __spam και λαμβάνω ένα σφάλμα σχετικά με το _SomeClassName__spam.


Τα ονόματα μεταβλητών με διπλή υπογράμμιση στην αρχή είναι «mangled» για να παρέχουν έναν απλό αλλά αποτελεσματικό τρόπο ορισμού των ιδιωτικών μεταβλητών κλάσης.  Οποιοδήποτε αναγνωριστικό της φόρμας @code{__spam} (τουλάχιστον δύο προπορευόμενες κάτω παύλες, το πολύ ένα τέλος υπογράμμισης) αντικαθίσταται μέσω κειμένου το @code{_classname__spam}, όπου το @code{classname} είναι το τρέχον όνομα κλάσης με απογυμνωμένες τυχόν προηγούμενες παύλες.

Το αναγνωριστικό μπορεί να χρησιμοποιηθεί αμετάβλητο εντός της κλάσης, αλλά για πρόσβαση σε αυτό εκτός της κλάσης, πρέπει να χρησιμοποιηθεί το παραμορφωμένο όνομα:

@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

Συγκεκριμένα, αυτό δεν εγγυάται το απόρρητο καθώς ένας εξωτερικός χρήστης μπορεί ακόμα να έχει σκόπιμα πρόσβαση στο ιδιωτικό χαρακτηριστικό∙ πολλοί προγραμματιστές Python δεν μπαίνουν ποτέ στον κόπο να χρησιμοποιήσουν ονόματα μεταβλητών.


@subsubheading Δείτε επίσης


Οι @ref{2293,,προδιαφραφές παραποίησης ιδιωτικού ονόματος} για λεπτομέρειες και ειδικές περιπτώσεις.”


@node Η κλάση μου ορίζει __del__ αλλά δεν καλείται όταν διαγράφω το αντικείμενο,Πως μπορώ να λάβω μια λίστα με όλες τις οντότητες μιας δεδομένης κλάσης;,Προσπαθώ να χρησιμοποιήσω __spam και λαμβάνω ένα σφάλμα σχετικά με το _SomeClassName__spam,Αντικείμενα
@anchor{faq/programming my-class-defines-del-but-it-is-not-called-when-i-delete-the-object}@anchor{5cae}
@subsubsection Η κλάση μου ορίζει __del__ αλλά δεν καλείται όταν διαγράφω το αντικείμενο.


Υπάρχουν διάφοροι πιθανοί λόγοι για αυτό.

Η πρόταση @ref{1d1d,,del} δεν καλεί απαραιτήτως το @ref{13a6,,__del__()} – απλώς μειώνει τον αριθμό αναφοράς του αντικειμένου, και αν αυτό φτάσει στο μηδέν καλείται το @code{__del__()}.

If your data structures contain circular links (for example, 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{44f,,gc.collect()} to force a
collection, but there `are' pathological cases where objects will never be
collected.

Παρά τον συλλέκτη κύκλου, εξακολουθεί να είναι καλή ιδέα να ορίσετε μια ρητή μέθοδο @code{close()} σε αντικείμενα που θα καλούνται κάθε φορά που τελειώνετε με αυτά.  Η μέθοδος @code{close()} μπορεί στη συνέχει να αφαιρέσει χαρακτηριστικά που αναφέρονται σε υποαντικείμενα. Μην καλείτε το @code{__del__()} απευθείας – @code{__del__()} θα πρέπει να καλείτε το @code{close()} και το @code{close()} θα πρέπει να βεβαιωθεί ότι μπορεί να κληθεί περισσότερες από μία φορές για το ίδιο αντικείμενο.

Ένα άλλος τρόπος για να αποφύγετε τις κυκλικές αναφορές είναι να χρησιμοποιήσετε το module @ref{11d,,weakref}, το οποίο σας επιτρέπει να αυξάνετε τον αριθμό των αναφορών τους.  Οι δομές δεδομένων δέντρων, για παράδειγμα, θα πρέπει να χρησιμοποιούν αδύναμες αναφορές για τις αναφορές γονέων και αδελφών ( αν τα χρειαστούν!).

@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.

Τέλος, εάν η μέθοδος @code{__del__()} εγείρει μια εξαίρεση, εκτυπώνεται ένα προειδοποιητικό μήνυμα στη διεύθυνση @ref{d05,,sys.stderr}.

@node Πως μπορώ να λάβω μια λίστα με όλες τις οντότητες μιας δεδομένης κλάσης;,Γιατί το αποτέλεσμα του id φαίνεται να μην είναι μοναδικό;,Η κλάση μου ορίζει __del__ αλλά δεν καλείται όταν διαγράφω το αντικείμενο,Αντικείμενα
@anchor{faq/programming how-do-i-get-a-list-of-all-instances-of-a-given-class}@anchor{5caf}
@subsubsection Πως μπορώ να λάβω μια λίστα με όλες τις οντότητες μιας δεδομένης κλάσης;


Η Python δεν παρακολουθεί όλες τις παρουσίες μιας κλάσης (ή ενός ενσωματωμένου τύπου).  Μπορείτε να προγραμματίσετε τον κατασκευαστή της κλάσης να παρακολουθεί όλες τις οντότητες διατηρώντας μια λίστα αδύναμων αναφορών σε κάθε παρουσία.

@node Γιατί το αποτέλεσμα του id φαίνεται να μην είναι μοναδικό;,Πότε μπορώ να βασιστώ σε δοκιμές ταυτότητας με τον τελεστή is;,Πως μπορώ να λάβω μια λίστα με όλες τις οντότητες μιας δεδομένης κλάσης;,Αντικείμενα
@anchor{faq/programming why-does-the-result-of-id-appear-to-be-not-unique}@anchor{5cb0}
@subsubsection Γιατί το αποτέλεσμα του @code{id()} φαίνεται να μην είναι μοναδικό;


Το ενσωματωμένο @ref{17c5,,id()} επιστρέφει έναν ακέραιο που είναι εγγυημένο ότι είναι μοναδικός κατά τη διάρκεια ζωής του αντικειμένου.  Εφόσον στο CPython, αυτή είναι διεύθυνση μνήμης του αντικειμένου, συμβαίνει συχνά ότι μετά τη διαγραφή ενός αντικειμένου από τη μνήμη, το επόμενο πρόσφατα δημιουργημένο αντικείμενο εκχωρείται στην ίδια θέση στη μνήμη.  Αυτό φαίνεται από αυτό το παράδειγμα:

@example
>>> id(1000)
13901272
>>> id(2000)
13901272
@end example

Τα δύο αναγνωριστικά ανήκουν σε διαφορετικά ακέραια αντικείμενα που δημιουργούνται πριν και διαγράφονται αμέσως μετά την εκτέλεση της κλήσης @code{id()}.  Για να βεβαιωθείτε ότι τα αντικείμενα των οποίων το αναγνωριστικό θέλετε να εξετάσετε είναι ακόμα ζωντανά, δημιουργήστε μια άλλη αναφορά στο αντικείμενο:

@example
>>> a = 1000; b = 2000
>>> id(a)
13901272
>>> id(b)
13891296
@end example

@node Πότε μπορώ να βασιστώ σε δοκιμές ταυτότητας με τον τελεστή is;,Πώς μπορεί μια υποκλάση να ελέγξει ποια δεδομένα αποθηκεύονται σε μια αμετάβλητη παρουσία;,Γιατί το αποτέλεσμα του id φαίνεται να μην είναι μοναδικό;,Αντικείμενα
@anchor{faq/programming faq-identity-with-is}@anchor{2676}@anchor{faq/programming when-can-i-rely-on-identity-tests-with-the-is-operator}@anchor{5cb1}
@subsubsection Πότε μπορώ να βασιστώ σε δοκιμές ταυτότητας με τον τελεστή `is';


Ο τελεστής @code{is} ελέγχει την ταυτότητα του αντικειμένου.  Η δοκιμή @code{a is b} ισοδυναμεί με @code{id(a) == id(b)}.

Η πιο σημαντική ιδιότητα ενός τεστ ταυτότητας είναι ότι ένα αντικείμενο είναι πάντα πανομοιότυπο με τον εαυτό του, το @code{a is a} επιστρέφει πάντα @code{True}.  Τα τεστ ταυτότητας είναι συνήθως ταχύτερα από τα τεστ ισότητας.  Και σε αντίθεση με τα τεστ ισότητας, τα τεστ ταυτότητας είναι εγγυημένα ότι θα επιστρέψουν ένα boolean @code{True} ή @code{False}.

Ωστόσο, τα τεστ ταυτότητας μπορούν μόνο να αντικαταστήσουν τα τεστ ισότητας όταν είναι εξασφαλισμένη η ταυτότητα αντικειμένου. Γενικά, υπάρχουν τρεις περιπτώσεις όπου η ταυτότητα είναι εγγυημένη:


@enumerate 

@item 
Οι εκχωρήσεις δημιουργούν νέα ονόματα αλλά δεν αλλάζουν την ταυτότητα αντικειμένου.  Μετά την ανάθεση @code{new = old}, είναι εγγυημένο ότι το @code{new is old}.

@item 
Η τοποθέτηση ενός αντικειμένου σε ένα κοντέινερ που αποθηκεύει αναφορές αντικειμένων δεν αλλάζει την ταυτότητα αντικειμένου.  Μετά την ανάθεση λίστας @code{s[0] = x}, είναι εγγυημένο ότι το @code{s[0] is x}.

@item 
Εάν ένα αντικείμενο είναι singleton, σημαίνει ότι μόνο ένα στιγμιότυπο αυτού του αντικειμένου μπορεί να υπάρχει.  Μετά τις εκχωρήσεις @code{a = None} και @code{b = None}, είναι εγγυημένο ότι το @code{a is b} επειδή το @code{None} είναι singleton.
@end enumerate

Στις περισσότερες άλλες περιπτώσεις, τα τεστ ταυτότητας δεν ενδείκνυνται και προτιμώνται τα τεστ ισότητας. Ειδικότερα, τα τεστ ταυτότητας δεν θα πρέπει να χρησιμοποιούνται για τον έλεγχο σταθερών όπως @ref{326,,int} και @ref{1df,,str} που δεν είναι εγγυημένα singletons:

@example
>>> a = 10_000_000
>>> b = 5_000_000
>>> c = b + 5_000_000
>>> a is c
False

>>> a = 'Python'
>>> b = 'Py'
>>> c = b + 'thon'
>>> a is c
False
@end example

Ομοίως, τα νέα στιγμιότυπα μεταβλητών κοντέινερ δεν είναι ποτέ πανομοιότυπα:

@example
>>> a = []
>>> b = []
>>> a is b
False
@end example

Στον τυπικό κώδικα βιβλιοθήκης, θα δείτε πολλά κοινά μοτίβα για τη σωστή χρήση των δοκιμών ταυτότητας:


@enumerate 

@item 
Όπως προτείνεται από το 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/}, ένας έλεγχος ταυτότητας είναι ο προτιμώμενος τρόπος για να ελέγξετε το @code{None}.  Αυτό είναι σαν απλά αγγλικά στον κώδικα και αποφεύγεται η σύγχυση με άλλα αντικείμενα που μπορεί να έχουν τιμές boolean που αξιολογούνται ως ψευδείς.

@item 
Ο εντοπισμός προαιρετικών ορισμάτων μπορεί να είναι δύσκολος όταν το @code{None} είναι μια έγκυρη τιμή εισόδου.  Σε αυτές τις περιπτώσεις, μπορείτε να δημιουργήσετε ένα αντικείμενο μεμονωμένου φρουρού που είναι εγγυημένο ότι θα διαφέρει από άλλα αντικείμενα.  Για παράδειγμα, δείτε πως μπορείτε να εφαρμόσετε μια μέθοδο που συμπεριφέρεται σαν @ref{7de,,dict.pop()}:

@example
_sentinel = sentinel('_sentinel')

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

@item 
Οι υλοποιήσεις κοντέινερ μερικές φορές χρειάζεται να αυξήσουν τα τεστ ισότητας με δοκιμές ταυτότητας.  Αυτό αποτρέπει τη σύγχυση του κώδικα από αντικείμενα όπως το @code{float('NaN')} που είναι ίσα με τα ίδια.
@end enumerate

Για παράδειγμα, εδώ είναι η υλοποίηση του @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 Πώς μπορεί μια υποκλάση να ελέγξει ποια δεδομένα αποθηκεύονται σε μια αμετάβλητη παρουσία;,Πώς μπορώ να αποθηκεύσω τις κλήσεις μεθόδου στην κρυφή μνήμη;,Πότε μπορώ να βασιστώ σε δοκιμές ταυτότητας με τον τελεστή is;,Αντικείμενα
@anchor{faq/programming how-can-a-subclass-control-what-data-is-stored-in-an-immutable-instance}@anchor{5cb2}
@subsubsection Πώς μπορεί μια υποκλάση να ελέγξει ποια δεδομένα αποθηκεύονται σε μια αμετάβλητη παρουσία;


Κατά την υποκλάση ενός αμετάβλητου τύπου, παρακάμψετε τη μέθοδο @ref{982,,__new__()} αντί για τη μέθοδο @ref{2fa,,__init__()}.  Η τελευταία εκτελείται μόνο αφού δημιουργηθεί μια παρουσία, η οποία είναι πολύ αργά για να αλλάζει δεδομένα σε μια αμετάβλητη περίπτωση.

Όλες αυτές οι αμετάβλητες κλάσεις έχουν διαφορετική υπογραφή από τη μητρική τους κλάση:

@example
import datetime as dt

class FirstOfMonthDate(dt.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

Οι κλάσεις μπορούν να χρησιμοποιηθούν έτσι:

@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 Πώς μπορώ να αποθηκεύσω τις κλήσεις μεθόδου στην κρυφή μνήμη;,,Πώς μπορεί μια υποκλάση να ελέγξει ποια δεδομένα αποθηκεύονται σε μια αμετάβλητη παρουσία;,Αντικείμενα
@anchor{faq/programming faq-cache-method-calls}@anchor{2dca}@anchor{faq/programming how-do-i-cache-method-calls}@anchor{5cb3}
@subsubsection Πώς μπορώ να αποθηκεύσω τις κλήσεις μεθόδου στην κρυφή μνήμη;


Τα δύο βασικά εργαλεία για τις μεθόδους αποθήκευσης στην προσωρινή μνήμη είναι τα @ref{94e,,functools.cached_property()} και @ref{db3,,functools.lru_cache()}.  Το πρώτο αποθηκεύει τα αποτελέσματα σε επίπεδο παρουσίας και το δεύτερο σε επίπεδο κλάσης.

The @code{cached_property} approach only works with methods that do not take
any arguments.  It does not create a reference to the instance.  The
cached method result will be kept only as long as the instance is alive.

Το πλεονέκτημα είναι ότι όταν ένα στιγμιότυπο δεν χρησιμοποιείται πλέον, το αποτέλεσμα της αποθηκευμένης μεθόδου θα απελευθερωθεί αμέσως.  Το μειονέκτημα είναι ότι εάν συσσωρευτούν στιγμιότυπα, θα είναι και τα αποτελέσματα της συσσωρευμένης μεθόδου.  Μπορούν να αναπτυχθούν χωρίς περιορισμούς.

The @code{lru_cache} approach works with methods that have @ref{183,,hashable}
arguments.  It creates a reference to the instance unless special
efforts are made to pass in weak references.

Το πλεονέκτημα του αλγορίθμου που χρησιμοποιήθηκε λιγότερο πρόσφατα είναι ότι η κρυφή μνήμη οριοθετείται από το καθορισμένο `maxsize'.  Το μειονέκτημα είναι ότι τα στιγμιότυπα διατηρούνται ζωντανά έως ότου παλαιώσουν από την κρυφή μνήμη ή μέχρι να διαγραφεί η κρυφή μνήμη.

Αυτό το παράδειγμα δείχνει τις διάφορες τεχνικές:

@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

The above example assumes that the `station_id' never changes.  If the
relevant instance attributes are mutable, the @code{cached_property} approach
can’t be made to work because it cannot detect changes to the
attributes.

To make the @code{lru_cache} approach work when the `station_id' is mutable,
the class needs to define the @ref{ec0,,__eq__()} and @ref{ec1,,__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>,,Αντικείμενα,FAQ Προγραμματισμού
@anchor{faq/programming modules}@anchor{5cb4}
@subsection Modules


@menu
* Πως δημιουργώ ένα .pyc αρχείο;: Πως δημιουργώ ένα pyc αρχείο;. 
* Πως μπορώ να βρω το όνομα του τρέχοντος module;:: 
* Πως μπορώ να έχω modules που εισάγουν αμοιβαία το ένα το άλλο;:: 
* __import__(“x.y.z”) επιστρέφει <module “x”>∙ πως μπορώ να πάρω το z?: __import__ “x y z” επιστρέφει <module “x”>∙ πως μπορώ να πάρω το z?. 
* Όταν επεξεργάζομαι ένα module που έχει εισαχθεί και την επανεισάγω@comma{} οι αλλαγές δεν εμφανίζονται. Γιατί συμβαίνει αυτό;: Όταν επεξεργάζομαι ένα module που έχει εισαχθεί και την επανεισάγω οι αλλαγές δεν εμφανίζονται Γιατί συμβαίνει αυτό;. 

@end menu

@node Πως δημιουργώ ένα pyc αρχείο;,Πως μπορώ να βρω το όνομα του τρέχοντος module;,,Modules<5>
@anchor{faq/programming how-do-i-create-a-pyc-file}@anchor{5cb5}
@subsubsection Πως δημιουργώ ένα .pyc αρχείο;


Όταν ένα module εισάγεται για πρώτη φορά (ή όταν το αρχείο προέλευσης έχει αλλάξει από τη δημιουργία του τρέχοντος μεταγλωττισμένου αρχείου), ένα αρχείο @code{.pyc} που παρέχει τον μεταγλωττισμένο κώδικα θα πρέπει να δημιουργηθεί σε έναν υποκατάλογο @code{__pycache__} ο κατάλογος που περιέχει το @code{.py}.  Το αρχείο @code{.pyc} θα έχει ένα όνομα αρχείου που ξεκινά με το ίδιο όνομα με το αρχείο @code{.py} και τελειώνει σε @code{.pyc}, με ένα μεσαίο στοιχείο που εξαρτάται από το συγκεκριμένο δυαδικό αρχείο @code{python} που το δημιούργησε.  (Βλ. 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} για λεπτομέρειες.)

Ένας λόγος για τον οποίο ενδέχεται να μην δημιουργηθεί ένα αρχείο @code{.pyc} είναι ένα πρόβλημα δικαιωμάτων στον κατάλογο που περιέχει το αρχείο προέλευσης, που σημαίνει ότι δεν μπορεί να δημιουργηθεί ο υποκατάλογος @code{__pycache__}.  Αυτό μπορεί να συμβεί, για παράδειγμα, εάν αναπτυχθεί ως ένας χρήστης αλλά εκτελείται ως άλλος, όπως εάν δοκιμάζετε με έναν διακομιστή ιστού.

Unless the 
@geindex PYTHONDONTWRITEBYTECODE
@geindex μεταβλητή περιβάλλοντος; PYTHONDONTWRITEBYTECODE
@ref{1771,,PYTHONDONTWRITEBYTECODE} environment variable is set,
creation of a .pyc file is automatic if you’re importing a module and Python
has the ability (permissions, free space, and so on) to create a @code{__pycache__}
subdirectory and write the compiled module to that subdirectory.

Running Python on a top-level script is not considered an import and no
@code{.pyc} will be created.  For example, if you have a top-level module
@code{foo.py} that imports another module @code{xyz.py}, when you run @code{foo} (by
typing @code{python foo.py} as a shell command), a @code{.pyc} will be created for
@code{xyz} because @code{xyz} is imported, but no @code{.pyc} file will be created for
@code{foo} since @code{foo.py} isn’t being imported.

Εάν χρειάζεται να δημιουργήσετε ένα αρχείο @code{.pyc} για το @code{foo} – δηλαδή, να δημιουργήσετε ένα αρχείο @code{.pyc} για ένα module που δεν έχει εισαχθεί – μπορείτε, χρησιμοποιώντας τα modules @ref{bb,,py_compile} και @ref{21,,compileall}.

Το module @ref{bb,,py_compile} μπορεί να μεταγλωττίσει χειροκίνητα οποιαδήποτε module.  Ένας τρόπος είναι να χρησιμοποιήσετε τη συνάρτηση @code{compile()} σε αυτήν την ενότητα διαδραστικά:

@example
>>> import py_compile
>>> py_compile.compile('foo.py')
@end example

This will write the @code{.pyc} to a @code{__pycache__} subdirectory in the same
location as @code{foo.py} (or you can override that with the optional parameter
`cfile').

Μπορείτε επίσης να μεταγλωττίσετε αυτόματα όλα τα αρχεία σε έναν κατάλογο ή καταλόγους χρησιμοποιώντας το module @ref{21,,compileall}.  Μπορείτε να κάνετε από το shell prompt εκτελώντας το @code{compileall.py} και παρέχοντας τη διαδρομή ενός καταλόγου που περιέχει αρχεία Python για μεταγλώττιση:

@example
python -m compileall .
@end example

@node Πως μπορώ να βρω το όνομα του τρέχοντος module;,Πως μπορώ να έχω modules που εισάγουν αμοιβαία το ένα το άλλο;,Πως δημιουργώ ένα pyc αρχείο;,Modules<5>
@anchor{faq/programming how-do-i-find-the-current-module-name}@anchor{5cb6}
@subsubsection Πως μπορώ να βρω το όνομα του τρέχοντος module;


Ένα module μπορεί να βρει το δικό του όνομα module κοιτάζοντας την προκαθορισμένη καθολική μεταβλητή @code{__name__}. Εάν αυτή έχει την τιμή @code{__main__}, το πρόγραμμα εκτελείται ως σενάριο.  Πολλά modules που χρησιμοποιούνται συνήθως με την εισαγωγή τους παρέχουν επίσης μια διεπαφή γραμμής εντολών ή έναν αυτοέλεγχο και εκτελέστε αυτόν τον κώδικα μόνο αφού ελέγξετε το @code{__name__}:

@example
def main():
    print('Running test...')
    ...

if __name__ == '__main__':
    main()
@end example

@node Πως μπορώ να έχω modules που εισάγουν αμοιβαία το ένα το άλλο;,__import__ “x y z” επιστρέφει <module “x”>∙ πως μπορώ να πάρω το z?,Πως μπορώ να βρω το όνομα του τρέχοντος module;,Modules<5>
@anchor{faq/programming how-can-i-have-modules-that-mutually-import-each-other}@anchor{5cb7}
@subsubsection Πως μπορώ να έχω modules που εισάγουν αμοιβαία το ένα το άλλο;


Υποθέστε ότι έχετε τα ακόλουθα modules:

@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

Το πρόβλημα είναι ότι ο διερμηνέας θα εκτελέσει τα ακόλουθα βήματα:


@itemize *

@item 
main εισάγει @code{foo}

@item 
Δημιουργούνται κενά καθολικά για το @code{foo}

@item 
Το @code{foo} μεταγλωττίζεται και ξεκινά η εκτέλεση

@item 
@code{foo} εισάγει @code{bar}

@item 
Δημιουργούνται κενά καθολικά για @code{bar}

@item 
Το @code{bar} μεταγλωττίζεται και αρχίζει να εκτελείται

@item 
Το @code{bar} εισάγει το @code{foo} (το οποίο είναι απαγορευτικό, καθώς υπάρχει ήδη ένα module με το όνομα @code{foo})

@item 
Ο μηχανισμός εισαγωγής προσπαθεί να διαβάσει το @code{foo_var} από τα παγκόσμια @code{foo}, για να ορίσει το @code{bar.foo_var = foo.foo_var}
@end itemize

Το τελευταίο βήμα αποτυγχάνει, επειδή η Python δεν έχει τελειώσει ακόμα με την ερμηνεία του @code{foo} και το global λεξικό συμβόλων για το @code{foo} είναι ακόμα κενό.

Το ίδιο συμβαίνει όταν χρησιμοποιείτε το @code{import foo} και, στη συνέχεια, προσπαθείτε να αποκτήσετε πρόσβαση στο @code{foo.foo_var} σε καθολικό κώδικα.

Υπάρχουν (τουλάχιστον) τρεις πιθανοί τρόποι αντιμετώπισης αυτού του προβλήματος.

Ο Guido van Rossum συνιστά την αποφυγή όλων των χρήσεων του @code{from <module> import ...} και την τοποθέτηση όλου του κώδικα μέσα σε συναρτήσεις.  Τα initializations καθολικών μεταβλητών και μεταβλητών κλάσης θα πρέπει να χρησιμοποιηθούν μόνο σταθερές ή ενσωματωμένες συναρτήσεις.  Αυτό σημαίνει ότι ένα εισαγόμενο module αναφέρεται ως @code{<module>.<name>}.

Ο Jim Roskind προτείνει να εκτελέσετε τα βήματα με την ακόλουθη σειρά σε κάθε module:


@itemize *

@item 
εξαγωγές (globals, συναρτήσεις, και κλάσεις που δεν χρειάζονται εισαγόμενες βασικές κλάσεις)

@item 
δηλώσεις @code{import}

@item 
ενεργός κώδικας (συμπεριλαμβανομένων των καθολικών που αρχικοποιούνται από εισαγόμενες τιμές).
@end itemize

Ο Van Rossum δεν αρέσει πολύ αυτή η προσέγγιση επειδή οι εισαγωγές εμφανίζονται σε ένα περίεργο μέρος, αλλά λειτουργεί.

Ο Matthias Urlichs συνιστά την αναδιάρθρωση του κώδικά σας έτσι ώστε η αναδρομική εισαγωγή να μην είναι απαραίτητη εξαρχής.

Αυτές οι λύσεις δεν αλληλοαποκλείονται.

@node __import__ “x y z” επιστρέφει <module “x”>∙ πως μπορώ να πάρω το z?,Όταν επεξεργάζομαι ένα module που έχει εισαχθεί και την επανεισάγω οι αλλαγές δεν εμφανίζονται Γιατί συμβαίνει αυτό;,Πως μπορώ να έχω modules που εισάγουν αμοιβαία το ένα το άλλο;,Modules<5>
@anchor{faq/programming import-x-y-z-returns-module-x-how-do-i-get-z}@anchor{5cb8}
@subsubsection __import__(“x.y.z”) επιστρέφει <module “x”>∙ πως μπορώ να πάρω το z?


Σκεφτείτε να χρησιμοποιήσετε τη συνάρτηση ευκολίας @ref{927,,import_module()} από το @ref{7a,,importlib} αντί:

@example
z = importlib.import_module('x.y.z')
@end example

@node Όταν επεξεργάζομαι ένα module που έχει εισαχθεί και την επανεισάγω οι αλλαγές δεν εμφανίζονται Γιατί συμβαίνει αυτό;,,__import__ “x y z” επιστρέφει <module “x”>∙ πως μπορώ να πάρω το 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{5cb9}
@subsubsection Όταν επεξεργάζομαι ένα module που έχει εισαχθεί και την επανεισάγω, οι αλλαγές δεν εμφανίζονται. Γιατί συμβαίνει αυτό;


Για λόγους αποτελεσματικότητας καθώς και συνέπειας, η Python διαβάζει το αρχείο της ενότητας μόνο την πρώτη φορά που εισάγεται μια λειτουργική μονάδα.  Εάν δεν το έκανε, σε ένα πρόγραμμα που αποτελείται από πολλές ενότητες όπου η καθεμία εισάγει το ίδιο βασικό module, το βασικό module θα αναλυθεί και θα αναλυθεί ξανά πολλές φορές.  Για να αναγκάσετε τη εκ νέου ανάγνωση μιας αλλαγμένης ενότητας , κάντε το εξής:

@example
import importlib
import modname
importlib.reload(modname)
@end example

Warning: this technique is not 100% fool-proof.  In particular, modules
containing statements like:

@example
from modname import some_objects
@end example

θα συνεχίσει να λειτουργεί με την παλιά έκδοση των εισαγόμενων αντικειμένων.  Εάν η λειτουργική μονάδα περιέχει ορισμούς κλάσεων, οι υπάρχουσες παρουσίες κλάσεων `δεν' θα ενημερωθούν για να χρησιμοποιούν τον ορισμό της νέας κλάσης.  Αυτό μπορεί να οδηγήσει στην ακόλουθη παράδοξη συμπεριφορά:

@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

Η φύση του προβλήματος καθίσταται σαφής εάν εκτυπώσετε την «ταυτότητα» των αντικειμένων κλάσης:

@example
>>> hex(id(c.__class__))
'0x7352a0'
>>> hex(id(cls.C))
'0x4198d0'
@end example

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Design and History FAQ,Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης,FAQ Προγραμματισμού,Συχνές Ερωτήσεις για την Python
@anchor{faq/design doc}@anchor{5cba}@anchor{faq/design design-and-history-faq}@anchor{5cbb}@anchor{faq/design translation-repo}@anchor{5cbc}
@section Design and History FAQ



@menu
* Why does Python use indentation for grouping of statements?:: 
* Why am I getting strange results with simple arithmetic operations?:: 
* Why are floating-point calculations so inaccurate?:: 
* Why are Python strings immutable?:: 
* Why must “self” be used explicitly in method definitions and calls?:: 
* Why can’t I use an assignment in an expression?:: 
* Why does Python use methods for some functionality (e.g. list.index()) but functions for other (e.g. len(list))?: Why does Python use methods for some functionality e g list index but functions for other e g len list ?. 
* Why is join() a string method instead of a list or tuple method?: Why is join a string method instead of a list or tuple method?. 
* How fast are exceptions?:: 
* Why isn’t there a switch or case statement in Python?:: 
* Can’t you emulate threads in the interpreter instead of relying on an OS-specific thread implementation?:: 
* Why can’t lambda expressions contain statements?:: 
* Can Python be compiled to machine code@comma{} C or some other language?: Can Python be compiled to machine code C or some other language?. 
* How does Python manage memory?:: 
* Why doesn’t CPython use a more traditional garbage collection scheme?:: 
* Why isn’t all memory freed when CPython exits?:: 
* Why are there separate tuple and list data types?:: 
* How are lists implemented in CPython?:: 
* How are dictionaries implemented in CPython?:: 
* Why must dictionary keys be immutable?:: 
* Why doesn’t list.sort() return the sorted list?: Why doesn’t list sort return the sorted list?. 
* How do you specify and enforce an interface spec in Python?:: 
* Why is there no goto?:: 
* Why can’t raw strings (r-strings) end with a backslash?: Why can’t raw strings r-strings end with a backslash?. 
* Why doesn’t Python have a «with» statement for attribute assignments?:: 
* Why don’t generators support the with statement?:: 
* Why are colons required for the if/while/def/class statements?:: 
* Why does Python allow commas at the end of lists and tuples?:: 

@end menu

@node Why does Python use indentation for grouping of statements?,Why am I getting strange results with simple arithmetic operations?,,Design and History FAQ
@anchor{faq/design why-does-python-use-indentation-for-grouping-of-statements}@anchor{5cbd}
@subsection Why does Python use indentation for grouping of statements?


Guido van Rossum believes that using indentation for grouping is extremely
elegant and contributes a lot to the clarity of the average Python program.
Most people learn to love this feature after a while.

Since there are no begin/end brackets there cannot be a disagreement between
grouping perceived by the parser and the human reader.  Occasionally C
programmers will encounter a fragment of code like this:

@example
if (x <= y)
        x++;
        y--;
z++;
@end example

Only the @code{x++} statement is executed if the condition is true, but the
indentation leads many to believe otherwise.  Even experienced C programmers will
sometimes stare at it a long time wondering as to why @code{y} is being decremented even
for @code{x > y}.

Because there are no begin/end brackets, Python is much less prone to
coding-style conflicts.  In C there are many different ways to place the braces.
After becoming used to reading and writing code using a particular style,
it is normal to feel somewhat uneasy when reading (or being required to write)
in a different one.

Many coding styles place begin/end brackets on a line by themselves.  This makes
programs considerably longer and wastes valuable screen space, making it harder
to get a good overview of a program.  Ideally, a function should fit on one
screen (say, 20–30 lines).  20 lines of Python can do a lot more work than 20
lines of C.  This is not solely due to the lack of begin/end brackets – the
lack of declarations and the high-level data types are also responsible – but
the indentation-based syntax certainly helps.

@node Why am I getting strange results with simple arithmetic operations?,Why are floating-point calculations so inaccurate?,Why does Python use indentation for grouping of statements?,Design and History FAQ
@anchor{faq/design why-am-i-getting-strange-results-with-simple-arithmetic-operations}@anchor{5cbe}
@subsection Why am I getting strange results with simple arithmetic operations?


See the next question.

@node Why are floating-point calculations so inaccurate?,Why are Python strings immutable?,Why am I getting strange results with simple arithmetic operations?,Design and History FAQ
@anchor{faq/design why-are-floating-point-calculations-so-inaccurate}@anchor{5cbf}
@subsection Why are floating-point calculations so inaccurate?


Users are often surprised by results like this:

@example
>>> 1.2 - 1.0
0.19999999999999996
@end example

and think it is a bug in Python.  It’s not.  This has little to do with Python,
and much more to do with how the underlying platform handles floating-point
numbers.

The @ref{327,,float} type in CPython uses a C @code{double} for storage.  A
@code{float} object’s value is stored in binary floating-point with a fixed
precision (typically 53 bits) and Python uses C operations, which in turn rely
on the hardware implementation in the processor, to perform floating-point
operations. This means that as far as floating-point operations are concerned,
Python behaves like many popular languages including C and 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

the value stored for @code{x} is a (very good) approximation to the decimal value
@code{1.2}, but is not exactly equal to it.  On a typical machine, the actual
stored value is:

@example
1.0011001100110011001100110011001100110011001100110011 (binary)
@end example

which is exactly:

@example
1.1999999999999999555910790149937383830547332763671875 (decimal)
@end example

The typical precision of 53 bits provides Python floats with 15–16
decimal digits of accuracy.

For a fuller explanation, please see the @ref{22f0,,floating-point arithmetic} chapter in the Python tutorial.

@node Why are Python strings immutable?,Why must “self” be used explicitly in method definitions and calls?,Why are floating-point calculations so inaccurate?,Design and History FAQ
@anchor{faq/design why-are-python-strings-immutable}@anchor{5cc0}
@subsection Why are Python strings immutable?


There are several advantages.

One is performance: knowing that a string is immutable means we can allocate
space for it at creation time, and the storage requirements are fixed and
unchanging.  This is also one of the reasons for the distinction between tuples
and lists.

Another advantage is that strings in Python are considered as «elemental» as
numbers.  No amount of activity will change the value 8 to anything else, and in
Python, no amount of activity will change the string «eight» to anything else.

@node Why must “self” be used explicitly in method definitions and calls?,Why can’t I use an assignment in an expression?,Why are Python strings immutable?,Design and History FAQ
@anchor{faq/design why-must-self-be-used-explicitly-in-method-definitions-and-calls}@anchor{5cc1}@anchor{faq/design why-self}@anchor{5ca6}
@subsection Why must “self” be used explicitly in method definitions and calls?


The idea was borrowed from Modula-3.  It turns out to be very useful, for a
variety of reasons.

First, it’s more obvious that you are using a method or instance attribute
instead of a local variable.  Reading @code{self.x} or @code{self.meth()} makes it
absolutely clear that an instance variable or method is used even if you don’t
know the class definition by heart.  In C++, you can sort of tell by the lack of
a local variable declaration (assuming globals are rare or easily recognizable)
– but in Python, there are no local variable declarations, so you’d have to
look up the class definition to be sure.  Some C++ and Java coding standards
call for instance attributes to have an @code{m_} prefix, so this explicitness is
still useful in those languages, too.

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{2fa,,__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.

Finally, for instance variables it solves a syntactic problem with assignment:
since local variables in Python are (by definition!) those variables to which a
value is assigned in a function body (and that aren’t explicitly declared
global), there has to be some way to tell the interpreter that an assignment was
meant to assign to an instance variable instead of to a local variable, and it
should preferably be syntactic (for efficiency reasons).  C++ does this through
declarations, but Python doesn’t have declarations and it would be a pity having
to introduce them just for this purpose.  Using the explicit @code{self.var} solves
this nicely.  Similarly, for using instance variables, having to write
@code{self.var} means that references to unqualified names inside a method don’t
have to search the instance’s directories.  To put it another way, local
variables and instance variables live in two different namespaces, and you need
to tell Python which namespace to use.

@node Why can’t I use an assignment in an expression?,Why does Python use methods for some functionality e g list index but functions for other e g len list ?,Why must “self” be used explicitly in method definitions and calls?,Design and History FAQ
@anchor{faq/design id1}@anchor{5cc2}@anchor{faq/design why-can-t-i-use-an-assignment-in-an-expression}@anchor{2227}
@subsection Why can’t I use an assignment in an expression?


Starting in Python 3.8, you can!

Assignment expressions using the walrus operator @code{:=} assign a variable in an
expression:

@example
while chunk := fp.read(200):
   print(chunk)
@end example

See 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/} for more information.

@node Why does Python use methods for some functionality e g list index but functions for other e g len list ?,Why is join a string method instead of a list or tuple method?,Why can’t I use an assignment in an expression?,Design and History FAQ
@anchor{faq/design why-does-python-use-methods-for-some-functionality-e-g-list-index-but-functions-for-other-e-g-len-list}@anchor{5cc3}
@subsection Why does Python use methods for some functionality (e.g. list.index()) but functions for other (e.g. len(list))?


As Guido said:

@quotation

(a) For some operations, prefix notation just reads better than
postfix – prefix (and infix!) operations have a long tradition in
mathematics which likes notations where the visuals help the
mathematician thinking about a problem. Compare the easy with which we
rewrite a formula like x*(a+b) into x*a + x*b to the clumsiness of
doing the same thing using a raw OO notation.

(b) When I read code that says len(x) I `know' that it is asking for
the length of something. This tells me two things: the result is an
integer, and the argument is some kind of container. To the contrary,
when I read x.len(), I have to already know that x is some kind of
container implementing an interface or inheriting from a class that
has a standard len(). Witness the confusion we occasionally have when
a class that is not implementing a mapping has a get() or keys()
method, or something that isn’t a file has a write() method.


@center --- @indicateurl{https://mail.python.org/pipermail/python-3000/2006-November/004643.html}

@end quotation

@node Why is join a string method instead of a list or tuple method?,How fast are exceptions?,Why does Python use methods for some functionality e g list index but functions for other e g len list ?,Design and History FAQ
@anchor{faq/design why-is-join-a-string-method-instead-of-a-list-or-tuple-method}@anchor{5cc4}
@subsection Why is join() a string method instead of a list or tuple method?


Strings became much more like other standard types starting in Python 1.6, when
methods were added which give the same functionality that has always been
available using the functions of the string module.  Most of these new methods
have been widely accepted, but the one which appears to make some programmers
feel uncomfortable is:

@example
", ".join(['1', '2', '4', '8', '16'])
@end example

which gives the result:

@example
"1, 2, 4, 8, 16"
@end example

There are two common arguments against this usage.

The first runs along the lines of: «It looks really ugly using a method of a
string literal (string constant)», to which the answer is that it might, but a
string literal is just a fixed value. If the methods are to be allowed on names
bound to strings there is no logical reason to make them unavailable on
literals.

The second objection is typically cast as: «I am really telling a sequence to
join its members together with a string constant».  Sadly, you aren’t.  For some
reason there seems to be much less difficulty with having @ref{125b,,split()} as
a string method, since in that case it is easy to see that

@example
"1, 2, 4, 8, 16".split(", ")
@end example

is an instruction to a string literal to return the substrings delimited by the
given separator (or, by default, arbitrary runs of white space).

@ref{2803,,join()} is a string method because in using it you are telling the
separator string to iterate over a sequence of strings and insert itself between
adjacent elements.  This method can be used with any argument which obeys the
rules for sequence objects, including any new classes you might define yourself.
Similar methods exist for bytes and bytearray objects.

@node How fast are exceptions?,Why isn’t there a switch or case statement in Python?,Why is join a string method instead of a list or tuple method?,Design and History FAQ
@anchor{faq/design how-fast-are-exceptions}@anchor{5cc5}
@subsection How fast are exceptions?


A @ref{ad6,,try}/@ref{447,,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

This only made sense when you expected the dict to have the key almost all the
time.  If that wasn’t the case, you coded it like this:

@example
if key in mydict:
    value = mydict[key]
else:
    value = mydict[key] = getvalue(key)
@end example

For this specific case, you could also use @code{value = dict.setdefault(key,
getvalue(key))}, but only if the @code{getvalue()} call is cheap enough because it
is evaluated in all cases.

@node Why isn’t there a switch or case statement in Python?,Can’t you emulate threads in the interpreter instead of relying on an OS-specific thread implementation?,How fast are exceptions?,Design and History FAQ
@anchor{faq/design why-isn-t-there-a-switch-or-case-statement-in-python}@anchor{5cc6}
@subsection Why isn’t there a switch or case statement in 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}.

For cases where you need to choose from a very large number of possibilities,
you can create a dictionary mapping case values to functions to call.  For
example:

@example
functions = @{'a': function_1,
             'b': function_2,
             'c': self.method_1@}

func = functions[value]
func()
@end example

For calling methods on objects, you can simplify yet further by using the
@ref{f8f,,getattr()} built-in to retrieve methods with a particular name:

@example
class MyVisitor:
    def visit_a(self):
        ...

    def dispatch(self, value):
        method_name = 'visit_' + str(value)
        method = getattr(self, method_name)
        method()
@end example

It’s suggested that you use a prefix for the method names, such as @code{visit_} in
this example.  Without such a prefix, if values are coming from an untrusted
source, an attacker would be able to call any method on your object.

Imitating switch with fallthrough, as with C’s switch-case-default,
is possible, much harder, and less needed.

@node Can’t you emulate threads in the interpreter instead of relying on an OS-specific thread implementation?,Why can’t lambda expressions contain statements?,Why isn’t there a switch or case statement in Python?,Design and History FAQ
@anchor{faq/design can-t-you-emulate-threads-in-the-interpreter-instead-of-relying-on-an-os-specific-thread-implementation}@anchor{5cc7}
@subsection Can’t you emulate threads in the interpreter instead of relying on an OS-specific thread implementation?


Answer 1: Unfortunately, the interpreter pushes at least one C stack frame for
each Python stack frame.  Also, extensions can call back into Python at almost
random moments.  Therefore, a complete threads implementation requires thread
support for C.

Answer 2: Fortunately, there is Stackless Python@footnote{https://github.com/stackless-dev/stackless/wiki},
which has a completely redesigned interpreter loop that avoids the C stack.

@node Why can’t lambda expressions contain statements?,Can Python be compiled to machine code C or some other language?,Can’t you emulate threads in the interpreter instead of relying on an OS-specific thread implementation?,Design and History FAQ
@anchor{faq/design why-can-t-lambda-expressions-contain-statements}@anchor{5cc8}
@subsection Why can’t lambda expressions contain statements?


Python lambda expressions cannot contain statements because Python’s syntactic
framework can’t handle statements nested inside expressions.  However, in
Python, this is not a serious problem.  Unlike lambda forms in other languages,
where they add functionality, Python lambdas are only a shorthand notation if
you’re too lazy to define a function.

Functions are already first class objects in Python, and can be declared in a
local scope.  Therefore the only advantage of using a lambda instead of a
locally defined function is that you don’t need to invent a name for the
function – but that’s just a local variable to which the function object (which
is exactly the same type of object that a lambda expression yields) is assigned!

@node Can Python be compiled to machine code C or some other language?,How does Python manage memory?,Why can’t lambda expressions contain statements?,Design and History FAQ
@anchor{faq/design can-python-be-compiled-to-machine-code-c-or-some-other-language}@anchor{5cc9}
@subsection Can Python be compiled to machine code, C or some other language?


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 How does Python manage memory?,Why doesn’t CPython use a more traditional garbage collection scheme?,Can Python be compiled to machine code C or some other language?,Design and History FAQ
@anchor{faq/design how-does-python-manage-memory}@anchor{5cca}
@subsection How does Python manage memory?


The details of Python memory management depend on the implementation.  The
standard implementation of Python, @ref{ae3,,CPython}, uses reference counting to
detect inaccessible objects, and another mechanism to collect reference cycles,
periodically executing a cycle detection algorithm which looks for inaccessible
cycles and deletes the objects involved. The @ref{63,,gc} module provides functions
to perform a garbage collection, obtain debugging statistics, and tune the
collector’s parameters.

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.

In some Python implementations, the following code (which is fine in CPython)
will probably run out of file descriptors:

@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.

If you want to write code that will work with any Python implementation,
you should explicitly close the file or use the @ref{20a,,with} statement;
this will work regardless of memory management scheme:

@example
for file in very_long_list_of_files:
    with open(file) as f:
        c = f.read(1)
@end example

@node Why doesn’t CPython use a more traditional garbage collection scheme?,Why isn’t all memory freed when CPython exits?,How does Python manage memory?,Design and History FAQ
@anchor{faq/design why-doesn-t-cpython-use-a-more-traditional-garbage-collection-scheme}@anchor{5ccb}
@subsection Why doesn’t CPython use a more traditional garbage collection scheme?


For one thing, this is not a C standard feature and hence it’s not portable.
(Yes, we know about the Boehm GC library.  It has bits of assembler code for
`most' common platforms, not for all of them, and although it is mostly
transparent, it isn’t completely transparent; patches are required to get
Python to work with it.)

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 Why isn’t all memory freed when CPython exits?,Why are there separate tuple and list data types?,Why doesn’t CPython use a more traditional garbage collection scheme?,Design and History FAQ
@anchor{faq/design why-isn-t-all-memory-freed-when-cpython-exits}@anchor{5ccc}
@subsection Why isn’t all memory freed when CPython exits?


Objects referenced from the global namespaces of Python modules are not always
deallocated when Python exits.  This may happen if there are circular
references.  There are also certain bits of memory that are allocated by the C
library that are impossible to free (e.g. a tool like Purify will complain about
these).  Python is, however, aggressive about cleaning up memory on exit and
does try to destroy every single object.

If you want to force Python to delete certain things on deallocation use the
@ref{d,,atexit} module to run a function that will force those deletions.

@node Why are there separate tuple and list data types?,How are lists implemented in CPython?,Why isn’t all memory freed when CPython exits?,Design and History FAQ
@anchor{faq/design why-are-there-separate-tuple-and-list-data-types}@anchor{5ccd}
@subsection Why are there separate tuple and list data types?


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{14a6,,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.

Tuples are @ref{181,,immutable}, meaning that once a tuple has been created, you can’t
replace any of its elements with a new value.  Lists are @ref{21d1,,mutable}, meaning that
you can always change a list’s elements.  Only @ref{183,,hashable} objects can
be used as dictionary keys. Most immutable types are hashable, which is why
tuples, but not lists, can be used as keys. Note, however, that a tuple is
only hashable if all of its elements are hashable.

@node How are lists implemented in CPython?,How are dictionaries implemented in CPython?,Why are there separate tuple and list data types?,Design and History FAQ
@anchor{faq/design how-are-lists-implemented-in-cpython}@anchor{5cce}
@subsection How are lists implemented in CPython?


CPython’s lists are really variable-length arrays, not Lisp-style linked lists.
The implementation uses a contiguous array of references to other objects, and
keeps a pointer to this array and the array’s length in a list head structure.

This makes indexing a list @code{a[i]} an operation whose cost is independent of
the size of the list or the value of the index.

When items are appended or inserted, the array of references is resized.  Some
cleverness is applied to improve the performance of appending items repeatedly;
when the array must be grown, some extra space is allocated so the next few
times don’t require an actual resize.

@node How are dictionaries implemented in CPython?,Why must dictionary keys be immutable?,How are lists implemented in CPython?,Design and History FAQ
@anchor{faq/design how-are-dictionaries-implemented-in-cpython}@anchor{5ccf}
@subsection How are dictionaries implemented in CPython?


CPython’s dictionaries are implemented as resizable hash tables.  Compared to
B-trees, this gives better performance for lookup (the most common operation by
far) under most circumstances, and the implementation is simpler.

Dictionaries work by computing a hash code for each key stored in the dictionary
using the @ref{9e2,,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 Why must dictionary keys be immutable?,Why doesn’t list sort return the sorted list?,How are dictionaries implemented in CPython?,Design and History FAQ
@anchor{faq/design why-must-dictionary-keys-be-immutable}@anchor{5cd0}
@subsection Why must dictionary keys be immutable?


The hash table implementation of dictionaries uses a hash value calculated from
the key value to find the key.  If the key were a mutable object, its value
could change, and thus its hash could also change.  But since whoever changes
the key object can’t tell that it was being used as a dictionary key, it can’t
move the entry around in the dictionary.  Then, when you try to look up the same
object in the dictionary it won’t be found because its hash value is different.
If you tried to look up the old value it wouldn’t be found either, because the
value of the object found in that hash bin would be different.

If you want a dictionary indexed with a list, simply convert the list to a tuple
first; the function @code{tuple(L)} creates a tuple with the same entries as the
list @code{L}.  Tuples are immutable and can therefore be used as dictionary keys.

Some unacceptable solutions that have been proposed:


@itemize -

@item 
Hash lists by their address (object ID).  This doesn’t work because if you
construct a new list with the same value it won’t be found; e.g.:

@example
mydict = @{[1, 2]: '12'@}
print(mydict[[1, 2]])
@end example

would raise a @ref{7df,,KeyError} exception because the id of the @code{[1, 2]} used in the
second line differs from that in the first line.  In other words, dictionary
keys should be compared using @code{==}, not using @ref{324,,is}.

@item 
Make a copy when using a list as a key.  This doesn’t work because the list,
being a mutable object, could contain a reference to itself, and then the
copying code would run into an infinite loop.

@item 
Allow lists as keys but tell the user not to modify them.  This would allow a
class of hard-to-track bugs in programs when you forgot or modified a list by
accident. It also invalidates an important invariant of dictionaries: every
value in @code{d.keys()} is usable as a key of the dictionary.

@item 
Mark lists as read-only once they are used as a dictionary key.  The problem
is that it’s not just the top-level object that could change its value; you
could use a tuple containing a list as a key.  Entering anything as a key into
a dictionary would require marking all objects reachable from there as
read-only – and again, self-referential objects could cause an infinite loop.
@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{ec0,,__eq__()} and a @ref{ec1,,__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

Note that the hash computation is complicated by the possibility that some
members of the list may be unhashable and also by the possibility of arithmetic
overflow.

Furthermore it must always be the case that if @code{o1 == o2} (ie @code{o1.__eq__(o2)
is True}) then @code{hash(o1) == hash(o2)} (ie, @code{o1.__hash__() == o2.__hash__()}),
regardless of whether the object is in a dictionary or not.  If you fail to meet
these restrictions dictionaries and other hash based structures will misbehave.

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 Why doesn’t list sort return the sorted list?,How do you specify and enforce an interface spec in Python?,Why must dictionary keys be immutable?,Design and History FAQ
@anchor{faq/design why-doesn-t-list-sort-return-the-sorted-list}@anchor{5cd1}
@subsection Why doesn’t list.sort() return the sorted list?


In situations where performance matters, making a copy of the list just to sort
it would be wasteful. Therefore, @ref{f8d,,list.sort()} sorts the list in place. In
order to remind you of that fact, it does not return the sorted list.  This way,
you won’t be fooled into accidentally overwriting a list when you need a sorted
copy but also need to keep the unsorted version around.

If you want to return a new list, use the built-in @ref{f8c,,sorted()} function
instead.  This function creates a new list from a provided iterable, sorts
it and returns it.  For example, here’s how to iterate over the keys of a
dictionary in sorted order:

@example
for key in sorted(mydict):
    ...  # do whatever with mydict[key]...
@end example

@node How do you specify and enforce an interface spec in Python?,Why is there no goto?,Why doesn’t list sort return the sorted list?,Design and History FAQ
@anchor{faq/design how-do-you-specify-and-enforce-an-interface-spec-in-python}@anchor{5cd2}
@subsection How do you specify and enforce an interface spec in Python?


An interface specification for a module as provided by languages such as C++ and
Java describes the prototypes for the methods and functions of the module.  Many
feel that compile-time enforcement of interface specifications helps in the
construction of large programs.

Python 2.6 adds an @ref{4,,abc} module that lets you define Abstract Base Classes
(ABCs).  You can then use @ref{2ef,,isinstance()} and @ref{2f0,,issubclass()} to check
whether an instance or a class implements a particular ABC.  The
@ref{1f,,collections.abc} module defines a set of useful ABCs such as
@ref{28aa,,Iterable}, @ref{28ac,,Container}, and
@ref{1459,,MutableMapping}.

For Python, many of the advantages of interface specifications can be obtained
by an appropriate test discipline for components.

A good test suite for a module can both provide a regression test and serve as a
module interface specification and a set of examples.  Many Python modules can
be run as a script to provide a simple «self test.»  Even modules which use
complex external interfaces can often be tested in isolation using trivial
«stub» emulations of the external interface.  The @ref{3d,,doctest} and
@ref{10f,,unittest} modules or third-party test frameworks can be used to construct
exhaustive test suites that exercise every line of code in a 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 @ref{aba,,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.

Writing test suites is very helpful, and you might want to design your code to
make it easily tested. One increasingly popular technique, test-driven
development, calls for writing parts of the test suite first, before you write
any of the actual code.  Of course Python allows you to be sloppy and not write
test cases at all.

@node Why is there no goto?,Why can’t raw strings r-strings end with a backslash?,How do you specify and enforce an interface spec in Python?,Design and History FAQ
@anchor{faq/design why-is-there-no-goto}@anchor{5cd3}
@subsection Why is there no goto?


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{322,,if} statements and @ref{325,,or},
@ref{31f,,and}, and @code{if}/@ref{320,,else} expressions) and loop (with @ref{1b86,,while}
and @ref{321,,for} statements, possibly containing @ref{429,,continue} and @ref{428,,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 Why can’t raw strings r-strings end with a backslash?,Why doesn’t Python have a «with» statement for attribute assignments?,Why is there no goto?,Design and History FAQ
@anchor{faq/design why-can-t-raw-strings-r-strings-end-with-a-backslash}@anchor{5cd4}
@subsection Why can’t raw strings (r-strings) end with a backslash?


More precisely, they can’t end with an odd number of backslashes: the unpaired
backslash at the end escapes the closing quote character, leaving an
unterminated string.

Raw strings were designed to ease creating input for processors (chiefly regular
expression engines) that want to do their own backslash escape processing. Such
processors consider an unmatched trailing backslash to be an error anyway, so
raw strings disallow that.  In return, they allow you to pass on the string
quote character by escaping it with a backslash.  These rules work well when
r-strings are used for their intended purpose.

If you’re trying to build Windows pathnames, note that all Windows system calls
accept forward slashes too:

@example
f = open("/mydir/file.txt")  # works fine!
@end example

If you’re trying to build a pathname for a DOS command, try e.g. one of

@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 Why doesn’t Python have a «with» statement for attribute assignments?,Why don’t generators support the with statement?,Why can’t raw strings r-strings end with a backslash?,Design and History FAQ
@anchor{faq/design why-doesn-t-python-have-a-with-statement-for-attribute-assignments}@anchor{5cd5}
@subsection Why doesn’t Python have a «with» statement for attribute assignments?


Python has a @ref{20a,,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

In Python, such a construct would be ambiguous.

Other languages, such as Object Pascal, Delphi, and C++, use static types, so
it’s possible to know, in an unambiguous way, what member is being assigned
to. This is the main point of static typing – the compiler `always' knows the
scope of every variable at compile time.

Python uses dynamic types. It is impossible to know in advance which attribute
will be referenced at runtime. Member attributes may be added or removed from
objects on the fly. This makes it impossible to know, from a simple reading,
what attribute is being referenced: a local one, a global one, or a member
attribute?

For instance, take the following incomplete snippet:

@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{20a,,with} block?  As you see, the dynamic nature of Python
makes such choices much harder.

The primary benefit of @ref{20a,,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

write this:

@example
ref = function(args).mydict[index][index]
ref.a = 21
ref.b = 42
ref.c = 63
@end example

This also has the side-effect of increasing execution speed because name
bindings are resolved at run-time in Python, and the second version only needs
to perform the resolution once.

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 Why don’t generators support the with statement?,Why are colons required for the if/while/def/class statements?,Why doesn’t Python have a «with» statement for attribute assignments?,Design and History FAQ
@anchor{faq/design why-don-t-generators-support-the-with-statement}@anchor{5cd6}
@subsection Why don’t generators support the with statement?


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{3ec,,contextlib.closing(generator)}
in the @ref{20a,,with} statement.

@node Why are colons required for the if/while/def/class statements?,Why does Python allow commas at the end of lists and tuples?,Why don’t generators support the with statement?,Design and History FAQ
@anchor{faq/design why-are-colons-required-for-the-if-while-def-class-statements}@anchor{5cd7}
@subsection Why are colons required for the if/while/def/class statements?


The colon is required primarily to enhance readability (one of the results of
the experimental ABC language).  Consider this:

@example
if a == b
    print(a)
@end example

versus

@example
if a == b:
    print(a)
@end example

Notice how the second one is slightly easier to read.  Notice further how a
colon sets off the example in this FAQ answer; it’s a standard usage in English.

Another minor reason is that the colon makes it easier for editors with syntax
highlighting; they can look for colons to decide when indentation needs to be
increased instead of having to do a more elaborate parsing of the program text.

@node Why does Python allow commas at the end of lists and tuples?,,Why are colons required for the if/while/def/class statements?,Design and History FAQ
@anchor{faq/design why-does-python-allow-commas-at-the-end-of-lists-and-tuples}@anchor{5cd8}
@subsection Why does Python allow commas at the end of lists and tuples?


Python lets you add a trailing comma at the end of lists, tuples, and
dictionaries:

@example
[1, 2, 3,]
('a', 'b', 'c',)
d = @{
    "A": [1, 5],
    "B": [6, 7],  # last trailing comma is optional but good style
@}
@end example

There are several reasons to allow this.

When you have a literal value for a list, tuple, or dictionary spread across
multiple lines, it’s easier to add more elements because you don’t have to
remember to add a comma to the previous line.  The lines can also be reordered
without creating a syntax error.

Accidentally omitting the comma can lead to errors that are hard to diagnose.
For example:

@example
x = [
  "fee",
  "fie"
  "foo",
  "fum"
]
@end example

This list looks like it has four elements, but it actually contains three:
«fee», «fiefoo» and «fum».  Always adding the comma avoids this source of error.

Allowing the trailing comma may also make programmatic code generation easier.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης,Design and History FAQ,Συχνές Ερωτήσεις για την Python
@anchor{faq/library doc}@anchor{5cd9}@anchor{faq/library library-and-extension-faq}@anchor{5cda}@anchor{faq/library translation-repo}@anchor{5cdb}
@section Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης



@menu
* Γενικές Ερωτήσεις Βιβλιοθήκης:: 
* Κοινές εργασίες:: 
* Νήματα (Threads): Νήματα Threads. 
* Είσοδος και Έξοδος: Είσοδος και Έξοδος<2>. 
* Προγραμματισμός Δικτύου/Διαδικτύου:: 
* Βάσεις Δεδομένων:: 
* Μαθηματικά και Αριθμητικά:: 

@end menu

@node Γενικές Ερωτήσεις Βιβλιοθήκης,Κοινές εργασίες,,Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης
@anchor{faq/library general-library-questions}@anchor{5cdc}
@subsection Γενικές Ερωτήσεις Βιβλιοθήκης


@menu
* Πως μπορώ να βρω ένα module ή μια εφαρμογή για να εκτελέσω την εργασία Χ;:: 
* Που βρίσκεται το πηγαίο αρχείο math.py (socket.py@comma{} regex.py@comma{} κ.λπ.);: Που βρίσκεται το πηγαίο αρχείο math py socket py regex py κ λπ ;. 
* Πως δημιουργώ ένα εκτελέσιμο Python script στο Unix;:: 
* Υπάρχει ένα curses/termcap πακέτο για την Python;:: 
* Υπάρχει κάτι ισοδύναμο με την onexit() της C στην Python;: Υπάρχει κάτι ισοδύναμο με την onexit της C στην Python;. 
* Γιατί δεν λειτουργούν οι χειριστές σήματος μου;:: 

@end menu

@node Πως μπορώ να βρω ένα module ή μια εφαρμογή για να εκτελέσω την εργασία Χ;,Που βρίσκεται το πηγαίο αρχείο math py socket py regex py κ λπ ;,,Γενικές Ερωτήσεις Βιβλιοθήκης
@anchor{faq/library how-do-i-find-a-module-or-application-to-perform-task-x}@anchor{5cdd}
@subsubsection Πως μπορώ να βρω ένα module ή μια εφαρμογή για να εκτελέσω την εργασία Χ;


Ελέγξτε την @ref{3f7,,the Library Reference} για να δείτε αν υπάρχει ένα σχετικό τυπικό module.  (Τελικά θα μάθετε τι υπάρχει στην τυπική βιβλιοθήκη και θα μπορείτε να παραλείψετε αυτό το βήμα.)

Για πακέτα τρίτων, πραγματοποιήστε αναζήτηση στο Python Package Index@footnote{https://pypi.org} ή δοκιμάστε στο Google@footnote{https://www.google.com} ή σε κάποια άλλη μηχανή αναζήτησης ιστού.  Η αναζήτηση με τον όρο «Python» μαζί με μια ή δύο λέξεις κλειδιά για το θέμα που σας ενδιαφέρει συνήθως θα βγάλει κάποιο χρήσιμο αποτέλεσμα.

@node Που βρίσκεται το πηγαίο αρχείο math py socket py regex py κ λπ ;,Πως δημιουργώ ένα εκτελέσιμο Python script στο Unix;,Πως μπορώ να βρω ένα module ή μια εφαρμογή για να εκτελέσω την εργασία Χ;,Γενικές Ερωτήσεις Βιβλιοθήκης
@anchor{faq/library where-is-the-math-py-socket-py-regex-py-etc-source-file}@anchor{5cde}
@subsubsection Που βρίσκεται το πηγαίο αρχείο math.py (socket.py, regex.py, κ.λπ.);


Εάν δεν μπορείτε να βρείτε ένα πηγαίο αρχείο για ένα module, μπορεί να είναι ένα ενσωματωμένο (built-in) module ή ένα module που φορτώνεται δυναμικά υλοποιημένο σε C, C++ ή άλλη μεταγλωττισμένη γλώσσα. Σε αυτή την περίπτωση μπορεί να μην έχετε το αρχείο προέλευσης ή μπορεί να είναι κάτι σαν @code{mathmodule.c}, κάπου σε έναν κατάλογο προέλευσης C (όχι στην διαδρομή της Python).

Υπάρχουν (το λιγότερο) τριών ειδών modules στην Python:


@enumerate 

@item 
modules γραμμένα σε Python (.py):

@item 
modules γραμμένα σε C και φορτώνονται δυναμικά (.dll, .pyd, .so, .sl, κ.λπ.):

@item 
modules γραμμένα σε C και συνδεδεμένα με τον διερμηνέα: για να λάβετε μια λίστα από αυτά, πληκτρολογήστε:

@example
import sys
print(sys.builtin_module_names)
@end example
@end enumerate

@node Πως δημιουργώ ένα εκτελέσιμο Python script στο Unix;,Υπάρχει ένα curses/termcap πακέτο για την Python;,Που βρίσκεται το πηγαίο αρχείο math py socket py regex py κ λπ ;,Γενικές Ερωτήσεις Βιβλιοθήκης
@anchor{faq/library how-do-i-make-a-python-script-executable-on-unix}@anchor{5cdf}
@subsubsection Πως δημιουργώ ένα εκτελέσιμο Python script στο Unix;


Θα πρέπει να κάνετε δύο πράγματα: η λειτουργία του script αρχείου πρέπει να είναι εκτελέσιμη και η πρώτη γραμμή θα πρέπει αν ξεκινά με @code{#!} ακολουθούμενη από τη διαδρομή του διερμηνέα της Python.

Το πρώτο γίνεται με την εκτέλεση του @code{chmod +x scriptfile} ή ίσως @code{chmod 755 scriptfile}.

Το δεύτερο μπορεί να γίνει με ποικίλους τρόπους.  Ο πιο απλός τρόπος είναι να γράψετε

@example
#!/usr/local/bin/python
@end example

ως η πρώτη γραμμή του αρχείου σας, χρησιμοποιώντας το pathname για το πού είναι εγκατεστημένος ο διερμηνέας Python στην πλατφόρμα σας.

Εάν θέλετε το script να είναι ανεξάρτητο, από το που ζει ο διερμηνέας της Python, μπορείτε να χρησιμοποιήσετε το πρόγραμμα @code{env}.  Σχεδόν όλες οι παραλλαγές Unix υποστηρίζουν τα ακόλουθα, υποθέτοντας ότι ο διερμηνέας Python βρίσκεται σε έναν κατάλογο στο 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} του χρήστη:

@example
#!/usr/bin/env python
@end example

`Μην' το κάνετε αυτό για CGI scripts.  Η μεταβλητή 
@geindex PATH
@geindex μεταβλητή περιβάλλοντος; PATH
@code{PATH} για τα CGI scripts είναι συχνά πολύ ελάχιστη, επομένως πρέπει να χρησιμοποιήσετε το πραγματικό απόλυτο όνομα διαδρομής του διερμηνέα.

Περιστασιακά, το περιβάλλον ενός χρήστη είναι τόσο γεμάτο που το πρόγραμμα @code{/usr/bin/env} αποτυγχάνει ή δεν υπάρχει καθόλου πρόγραμμα env.  Σε αυτήν την περίπτωση, μπορείτε να δοκιμάσετε το ακόλουθο hack (λόγω του Alex Rezinsky):

@example
#! /bin/sh
""":"
exec python $0 $@{1+"$@@"@}
"""
@end example

Το, ελάχιστης σημασίας, μειονέκτημα είναι ότι αυτό καθορίζει τη συμβολοσειρά __doc__ του script. Ωστόσο, μπορείτε να το διορθώσετε προσθέτοντας

@example
__doc__ = """...Οτιδήποτε..."""
@end example

@node Υπάρχει ένα curses/termcap πακέτο για την Python;,Υπάρχει κάτι ισοδύναμο με την onexit της C στην Python;,Πως δημιουργώ ένα εκτελέσιμο Python script στο Unix;,Γενικές Ερωτήσεις Βιβλιοθήκης
@anchor{faq/library is-there-a-curses-termcap-package-for-python}@anchor{5ce0}
@subsubsection Υπάρχει ένα curses/termcap πακέτο για την Python;


@c XXX curses *is* built by default, isn't it?

Για παραλλαγές Unix: Η τυπική διανομή του πηγαίου της Python συνοδεύεται από ένα curses module στον υποκατάλογο Modules@footnote{https://github.com/python/cpython/tree/main/Modules}, αν και δεν έχει μεταγλωττιστεί από προεπιλογή.  (Λάβετε υπόψη ότι αυτό δεν είναι διαθέσιμο στη διανομή των Windows – δεν υπάρχει curses module για Windows.)

Το module @ref{2e,,curses} υποστηρίζει βασικές curses λειτουργίες καθώς και πολλές πρόσθετες λειτουργίες από ncurses και SYSV curses, όπως χρώμα, υποστήριξη εναλλακτικού συνόλου χαρακτήρων, pads και υποστήριξη ποντικιού. Αυτό σημαίνει ότι το module δεν είναι συμβατό με λειτουργικά συστήματα που έχουνε μόνο BSD curses, αλλά δεν φαίνεται να υπάρχουν επί του παρόντος διατηρημένα λειτουργικά συστήματα που να εμπίπτουν σε αυτήν την κατηγορία.

@node Υπάρχει κάτι ισοδύναμο με την onexit της C στην Python;,Γιατί δεν λειτουργούν οι χειριστές σήματος μου;,Υπάρχει ένα curses/termcap πακέτο για την Python;,Γενικές Ερωτήσεις Βιβλιοθήκης
@anchor{faq/library is-there-an-equivalent-to-c-s-onexit-in-python}@anchor{5ce1}
@subsubsection Υπάρχει κάτι ισοδύναμο με την onexit() της C στην Python;


Το module @ref{d,,atexit} παρέχει μια συνάρτηση καταχωρητή παρόμοια με τη συνάρτηση @code{onexit()} της C.

@node Γιατί δεν λειτουργούν οι χειριστές σήματος μου;,,Υπάρχει κάτι ισοδύναμο με την onexit της C στην Python;,Γενικές Ερωτήσεις Βιβλιοθήκης
@anchor{faq/library why-don-t-my-signal-handlers-work}@anchor{5ce2}
@subsubsection Γιατί δεν λειτουργούν οι χειριστές σήματος μου;


Το πιο συνηθισμένο πρόβλημα είναι ότι ο χειριστής σήματος δηλώνεται με λάθος λίστα ορισμάτων.  Ονομάζεται ως

@example
handler(signum, frame)
@end example

οπότε θα πρέπει να δηλωθεί με δύο παραμέτρους:

@example
def handler(signum, frame):
    ...
@end example

@node Κοινές εργασίες,Νήματα Threads,Γενικές Ερωτήσεις Βιβλιοθήκης,Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης
@anchor{faq/library common-tasks}@anchor{5ce3}
@subsection Κοινές εργασίες


@menu
* Πως μπορώ να τεστάρω ένα Python πρόγραμμα ή ένα Python component;:: 
* Πως δημιουργώ τεκμηρίωση από doc strings;:: 
* Πως μπορώ να λάβω μόνο ένα πάτημα κουμπιού κάθε φορά;:: 

@end menu

@node Πως μπορώ να τεστάρω ένα Python πρόγραμμα ή ένα Python component;,Πως δημιουργώ τεκμηρίωση από doc strings;,,Κοινές εργασίες
@anchor{faq/library how-do-i-test-a-python-program-or-component}@anchor{5ce4}
@subsubsection Πως μπορώ να τεστάρω ένα Python πρόγραμμα ή ένα Python component;


Η Python συνοδεύεται από δύο frameworks για τεστ.  To module @ref{3d,,doctest} βρίσκει παραδείγματα στα docstrings για ένα module και τα εκτελεί, συγκρίνοντας την έξοδο με την αναμενόμενη έξοδο που δίνεται στο docstring.

Το module @ref{10f,,unittest} είναι ένα πιο εντυπωσιακό framework που έχει σχεδιαστεί με βάση τα frameworks για τεστ της Java και του Smalltalk.

Για να κάνετε τα τεστ σας ευκολότερα θα πρέπει να χρησιμοποιείτε μια καλή αρθρωτή σχεδίαση στο πρόγραμμα σας. Το πρόγραμμα σας θα πρέπει να έχει όλες σχεδόν τις λειτουργίες ενσωματωμένες είτε σε συναρτήσεις είτε σε μεθόδους κλάσης - και αυτό μερικές φορές έχει το εκπληκτικό και ευχάριστο αποτέλεσμα να κάνει το πρόγραμμα να τρέχει πιο γρήγορα (γιατί  οι τοπικές προσβάσεις μεταβλητών είναι πιο γρήγορες από τις καθολικές προσβάσεις).  Επιπλέον, το πρόγραμμα θα πρέπει να αποφεύγει την εξάρτηση από μεταλλάξεις παγκόσμιων μεταβλητών, καθώς αυτό κάνει τη δοκιμή πολύ πιο δύσκολη.

Η «παγκόσμια κύρια λογική» του προγράμματος σας μπορεί να είναι τόσο απλή όσο

@example
if __name__ == "__main__":
    main_logic()
@end example

στο κάτω μέρος του κύριου module του προγράμματος σας.

Από τη στιγμή που το πρόγραμμα σας οργανωθεί ως μια συλλογή από συναρτήσεις και κλάσεις που υλοποιούν μια διαδικασία, θα πρέπει να γράψετε τεστ συναρτήσεις που εκτελούν τις αντίστοιχες διαδικασίες.  Μια τεστ σουίτα που αυτοματοποιεί μια ακολουθία από tests μπορεί να συσχετιστεί με κάθε module. Αυτό ακούγεται σαν πολλή δουλειά, αλλά επειδή η Python είναι τόσο σύντομη και ευέλικτη, αυτό είναι εκπληκτικά εύκολο.  Μπορείτε να κάνετε την συγγραφή κώδικα πολύ πιο ευχάριστη και διασκεδαστική γράφοντας τις δοκιμαστικές συναρτήσεις σας παράλληλα με τον «κώδικα παραγωγής», καθώς αυτό διευκολύνει την εύρεση σφαλμάτων και ακόμη και ελαττώματα σχεδιασμού νωρίτερα.

«Modules υποστήριξης» που δεν προορίζονται να είναι το κύριο module ενός προγράμματος μπορεί να περιλαμβάνουν αυτοέλεγχο της ενότητας:

@example
if __name__ == "__main__":
    self_test()
@end example

Ακόμη και προγράμματα που αλληλεπιδρούν με πολύπλοκες εξωτερικές διεπαφές μπορούν να δοκιμαστούν όταν οι εξωτερικές διεπαφές δεν είναι διαθέσιμες χρησιμοποιώντας «τεχνητές» διεπαφές υλοποιημένες στην Python.

@node Πως δημιουργώ τεκμηρίωση από doc strings;,Πως μπορώ να λάβω μόνο ένα πάτημα κουμπιού κάθε φορά;,Πως μπορώ να τεστάρω ένα Python πρόγραμμα ή ένα Python component;,Κοινές εργασίες
@anchor{faq/library how-do-i-create-documentation-from-doc-strings}@anchor{5ce5}
@subsubsection Πως δημιουργώ τεκμηρίωση από doc strings;


Το module @ref{bd,,pydoc} μπορεί να δημιουργήσει HTML από τα doc strings στον πηγαίο κώδικα Python σας.  Μια εναλλακτική λύση για τη δημιουργία μιας τεκμηρίωσης API αποκλειστικά με docstrings είναι το epydoc@footnote{https://epydoc.sourceforge.net/}.  Sphinx@footnote{https://www.sphinx-doc.org} μπορεί επίσης να περιλαμβάνει docstring περιεχόμενο.

@node Πως μπορώ να λάβω μόνο ένα πάτημα κουμπιού κάθε φορά;,,Πως δημιουργώ τεκμηρίωση από doc strings;,Κοινές εργασίες
@anchor{faq/library how-do-i-get-a-single-keypress-at-a-time}@anchor{5ce6}
@subsubsection Πως μπορώ να λάβω μόνο ένα πάτημα κουμπιού κάθε φορά;


Για τις παραλλαγές του Unix υπάρχουν πολλές λύσεις.  Είναι απλό να κάνετε αυτό χρησιμοποιώντας curses, αλλά τα curses είναι ένα αρκετά μεγάλο module για εκμάθηση.

@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 Νήματα Threads,Είσοδος και Έξοδος<2>,Κοινές εργασίες,Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης
@anchor{faq/library threads}@anchor{5ce7}
@subsection Νήματα (Threads)


@menu
* Πώς μπορώ να προγραμματίσω χρησιμοποιώντας νήματα(threads);: Πώς μπορώ να προγραμματίσω χρησιμοποιώντας νήματα threads ;. 
* Κανένα από τα νήματα (threads) μου δεν φαίνεται να εκτελείται; γιατί;: Κανένα από τα νήματα threads μου δεν φαίνεται να εκτελείται γιατί;. 
* Πως μπορώ να μοιράσω την εργασία σε ένα σωρό από νήματα για αυτήν την εργασία;:: 
* Ποια είδη global μετάλλαξης τιμής είναι ασφαλή για νήμα(thread);: Ποια είδη global μετάλλαξης τιμής είναι ασφαλή για νήμα thread ;. 
* Μπορούμε να απαλλαγούμε από ένα Global Interpreter Lock;:: 

@end menu

@node Πώς μπορώ να προγραμματίσω χρησιμοποιώντας νήματα threads ;,Κανένα από τα νήματα threads μου δεν φαίνεται να εκτελείται γιατί;,,Νήματα Threads
@anchor{faq/library how-do-i-program-using-threads}@anchor{5ce8}
@subsubsection Πώς μπορώ να προγραμματίσω χρησιμοποιώντας νήματα(threads);


Βεβαιωθείτε ότι χρησιμοποιείτε το module @ref{f6,,threading} και όχι το module @ref{2,,_thread}. Το module @code{threading} παρέχει ένα πιο βολικό και υψηλού επιπέδου τρόπο διαχείρισης νημάτων, χτίζοντας πάνω στις βασικές λειτουργίες του module @code{_thread}.

@node Κανένα από τα νήματα threads μου δεν φαίνεται να εκτελείται γιατί;,Πως μπορώ να μοιράσω την εργασία σε ένα σωρό από νήματα για αυτήν την εργασία;,Πώς μπορώ να προγραμματίσω χρησιμοποιώντας νήματα threads ;,Νήματα Threads
@anchor{faq/library none-of-my-threads-seem-to-run-why}@anchor{5ce9}
@subsubsection Κανένα από τα νήματα (threads) μου δεν φαίνεται να εκτελείται: γιατί;


Μόλις γίνει έξοδος από το κύριο νήμα, τερματίζονται όλα τα νήματα.  Το κύριο νήμα τρέχει πολύ γρήγορα, χωρίς να δίνεται χρόνος στα νήματα να κάνουν οποιαδήποτε εργασία.

Μια απλή λύση είναι να προσθέσετε ένα sleep στο τέλος που προγράμματος που είναι αρκετό για να τερματιστούν όλα τα νήματα:

@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

Αλλά τώρα (σε πολλές πλατφόρμες) τα νήματα δεν εκτελούνται παράλληλα, αλλά φαίνεται να εκτελούνται διαδοχικά, ένα κάθε φορά!  Ο λόγος είναι ότι ο προγραμματιστής νημάτων του λειτουργικού συστήματος δεν ξεκινά ένα νέο νήμα μέχρι να αποκλειστεί το προηγούμενο νήμα.

Μια απλή λύση είναι να προσθέσετε ένα μικρό sleep στην αρχή της λειτουργίας εκτέλεσης:

@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

Αντί να προσπαθείτε να μαντέψετε μια καλή τιμή καθυστέρησης για την @ref{a8c,,time.sleep()}, είναι καλύτερα να χρησιμοποιείτε κάποιο είδος μηχανισμού σηματοφόρου.  Μια ιδέα είναι να χρησιμοποιήσετε το module @ref{be,,queue} για να δημιουργήσετε ένα αντικείμενο ουράς, αφήνοντας το κάθε νήμα να προσθέτει ένα token στην ουρά όταν ολοκληρωθεί, και να αφήνει στο κύριο νήμα να διαβάσει τόσα tokens από την ουρά όσα είναι και τα νήματα.

@node Πως μπορώ να μοιράσω την εργασία σε ένα σωρό από νήματα για αυτήν την εργασία;,Ποια είδη global μετάλλαξης τιμής είναι ασφαλή για νήμα thread ;,Κανένα από τα νήματα threads μου δεν φαίνεται να εκτελείται γιατί;,Νήματα Threads
@anchor{faq/library how-do-i-parcel-out-work-among-a-bunch-of-worker-threads}@anchor{5cea}
@subsubsection Πως μπορώ να μοιράσω την εργασία σε ένα σωρό από νήματα για αυτήν την εργασία;


Ο πιο εύκολος τρόπος είναι να χρησιμοποιήσετε το module @ref{24,,concurrent.futures}, ειδικά την κλάση @ref{b27,,ThreadPoolExecutor}.

Ή, ένα θέλετε καλό έλεγχο στον αλγόριθμο αποστολής, μπορείτε να γράψετε τη δική σας λογική με μη αυτόματο τρόπο.  Χρησιμοποιήστε το module @ref{be,,queue} για να δημιουργήσετε μια ουρά που περιέχει μια λίστα εργασιών.  Η κλάση @ref{1738,,Queue} διατηρεί μια λίστα αντικειμένων και έχει μια μέθοδο @code{.put(obj)} που προσθέτει στοιχεία στην ουρά και μια μέθοδο @code{.get()} για επιστροφή.  Η κλάση θα φροντίσει για το κλείδωμα που είναι απαραίτητο για να διασφαλίσει ότι κάθε εργασία θα παραδοθεί ακριβώς μία φορά.

Ένα απλό παράδειγμα:

@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

Κατά την εκτέλεση, αυτό θα παράγει την ακόλουθη έξοδο:

@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

Συμβουλευτείτε την τεκμηρίωση του module για περισσότερες λεπτομέρειες· η κλάση @ref{1738,,Queue} παρέχει μια χαρακτηριστική διεπαφή.

@node Ποια είδη global μετάλλαξης τιμής είναι ασφαλή για νήμα thread ;,Μπορούμε να απαλλαγούμε από ένα Global Interpreter Lock;,Πως μπορώ να μοιράσω την εργασία σε ένα σωρό από νήματα για αυτήν την εργασία;,Νήματα Threads
@anchor{faq/library what-kinds-of-global-value-mutation-are-thread-safe}@anchor{5ceb}
@subsubsection Ποια είδη global μετάλλαξης τιμής είναι ασφαλή για νήμα(thread);


Ένα @ref{685,,global interpreter lock} (GIL) χρησιμοποιείται εσωτερικά για να διασφαλιστεί ότι μόνο ένα νήμα εκτελείται στο Python VM κάθε φορά.  Γενικά, η Python προσφέρει εναλλαγή μεταξύ νημάτων μόνο μεταξύ εντολών bytecode· το πόσο συχνά γίνεται αυτή η εναλλαγή καθορίζεται από την @ref{d16,,sys.setswitchinterval()}.  Κάθε εντολή bytecode και επομένως όλος ο κώδικας υλοποίησης C που φτάνει από κάθε εντολή είναι επομένως ατομικός από την άποψη ενός προγράμματος Python.

Θεωρητικά, αυτό σημαίνει ότι μια ακριβώς λογιστική απαιτεί ακριβή κατανόηση της εφαρμογής bytecode PVM.  Στην πράξη, σημαίνει ότι οι λειτουργίες σε κοινόχρηστες μεταβλητές ενσωματωμένων δεδομένων (ακέραιοι, λίστες, λεξικά, κ.λπ.) που «φαίνονται ατομικά» πραγματικά είναι.

Για παράδειγμα, οι ακόλουθες πράξεις είναι όλες ατομικές (L, L1, L2 είναι λίστες, D, D1, D2 είναι λεξικά, x, y είναι αντικείμενα, i, j είναι ακέραιοι):

@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

Αυτά δεν είναι:

@example
i = i+1
L.append(L[-1])
L[i] = L[j]
D[x] = D[x] + 1
@end example

Οι λειτουργίες που αντικαθιστούν άλλα αντικείμενα ενδέχεται να καλέσουν αυτά τα άλλα αντικείμενα της @ref{13a6,,__del__()} όταν ο αριθμός αναφοράς τους φτάσει στο μηδέν και αυτό μπορεί να επηρεάσει πράγματα.  Αυτό ισχύει ιδιαίτερα για τις μαζικές ενημερώσεις σε λεξικά και λίστες.  Σε περίπτωση αμφιβολίας, χρησιμοποιήστε ένα mutex!

@node Μπορούμε να απαλλαγούμε από ένα Global Interpreter Lock;,,Ποια είδη global μετάλλαξης τιμής είναι ασφαλή για νήμα thread ;,Νήματα Threads
@anchor{faq/library can-t-we-get-rid-of-the-global-interpreter-lock}@anchor{5cec}
@subsubsection Μπορούμε να απαλλαγούμε από ένα Global Interpreter Lock;


Το @ref{685,,global interpreter lock} (GIL) θεωρείται συχνά ως εμπόδιο για την ανάπτυξη της Python σε υψηλής τεχνολογίας μηχανήματα διακομιστών με πολυεπεξεργαστές, επειδή ένα πρόγραμμα  Python με πολλά νήματα χρησιμοποιεί αποτελεσματικά μόνο μία CPU, λόγω της επιμονής ότι (σχεδόν) όλος ο κώδικας της Python μπορεί να εκτελεστεί μόνο όσο διατηρείται το GIL.

Με την έγκριση του 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/} έχει ξεκινήσει η εργασία για την αφαίρεση του GIL από την υλοποίηση CPython της Python.  Αρχικά θα υλοποιηθεί ως μια προαιρετική σημαία μεταγλωττιστή κατά την κατασκευή του διερμηνευτή, και έτσι θα είναι διαθέσιμες ξεχωριστές κατασκευές με και χωρίς το GIL.  Μακροπρόθεσμα, η ελπίδα είναι να καταλήξουμε σε μια ενιαία κατασκευή, μόλις οι επιπτώσεις στην απόδοση της αφαίρεσης του GIL να γίνουν πλήρως κατανοητές.  Η Python 3.13 είναι πιθανό να είναι η πρώτη έκδοση που θα περιέχει αυτήν την εργασία, αν και μπορεί να μην είναι πλήρως λειτουργική σε αυτήν την έκδοση.

Η τρέχουσα εργασία για την αφαίρεση του GIL βασίζεται σε ένα fork της Python 3.9 με το GIL αφαιρεμένο@footnote{https://github.com/colesbury/nogil} από τον Sam Gross. Πριν από αυτό, στις ημέρες της Python 1.5, ο Greg Stein υλοποίησε στην πραγματικότητα ένα ολοκληρωμένο σύνολο διορθώσεων (τα «free threading» patches) που αφαίρεσαν το GIL και το αντικατέστησαν με λεπτομερή κλείδωμα.  Ο Adam Olsen έκανε ένα παρόμοιο πείραμα στο έργο του python-safethread@footnote{https://code.google.com/archive/p/python-safethread}. Δυστυχώς, και τα δύο αυτά προηγούμενα πειράματα παρουσίασαν απότομη πτώση στην απόδοση ενός νήματος (τουλάχιστον 30% πιο αργά), λόγω της ποσότητας λεπτομερούς κλειδώματος που απαιτείται για να αντισταθμιστεί η αφαίρεση του GIL.  Το fork της Python 3.9 είναι η πρώτη προσπάθεια αφαίρεσης του GIL με αποδεκτή επίδραση στην απόδοση.

Η παρουσία του GIL στις τρέχουσες εκδόσεις της Python δεν σημαίνει ότι δεν μπορείτε να κάνετε καλή χρήση της Python σε μηχανές με πολλαπλές CPU! Απλώς πρέπει να είστε δημιουργικοί με τον διαχωρισμό της εργασίας μεταξύ πολλαπλών `processes' αντί για πολλαπλά `threads'.  Η κλάση @ref{206,,ProcessPoolExecutor} στο νέο module @ref{24,,concurrent.futures} παρέχει έναν εύκολο τρόπο για να το κάνετε αυτό· το module @ref{98,,multiprocessing} παρέχει μια χαμηλότερου επιπέδου API σε περίπτωση που θέλετε περισσότερο έλεγχο στην αποστολή εργασιών.

Η συνετή χρήση των επεκτάσεων C βοηθάει επίσης· εάν χρησιμοποιείτε μια επέκταση C για να εκτελέσετε μια χρονοβόρα εργασία, η επέκταση μπορεί να απελευθερώσει το GIL ενώ το νήμα εκτέλεσης βρίσκεται στον κώδικα C και να επιτρέψει σε άλλα νήματα να ολοκληρώσουν κάποια εργασία.  Ορισμένα τυπικά module βιβλιοθήκης όπως @ref{13c,,zlib} και @ref{6b,,hashlib} το κάνουν ήδη αυτό.

Μια εναλλακτική προσέγγιση για τη μείωση της επίδρασης του GIL είναι να γίνει το GIL ένα κλείδωμα ανά κατάσταση διερμηνευτή αντί για πραγματικά παγκόσμιο. Αυτό @ref{85d,,υλοποιήθηκε πρώτα στην Python 3.12} και είναι διαθέσιμο στο C API. Μια διεπαφή Python σε αυτό αναμένεται στην Python 3.13. Ο κύριος περιορισμός προς το παρόν είναι πιθανό να είναι τα 3rd party extension modules, καθώς αυτά πρέπει να γράφονται με πολλαπλούς διερμηνευτές στο μυαλό για να είναι χρησιμοποιήσιμα, οπότε πολλά παλαιότερα extension modules δεν θα είναι χρησιμοποιήσιμα.

@node Είσοδος και Έξοδος<2>,Προγραμματισμός Δικτύου/Διαδικτύου,Νήματα Threads,Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης
@anchor{faq/library input-and-output}@anchor{5ced}
@subsection Είσοδος και Έξοδος


@menu
* Πώς μπορώ να διαγράψω ένα αρχείο; (Και άλλες ερωτήσεις για το αρχείο…): Πώς μπορώ να διαγράψω ένα αρχείο; Και άλλες ερωτήσεις για το αρχείο…. 
* Πως αντιγράφω ένα αρχείο;:: 
* Πώς διαβάζω (ή γράφω) δυαδικά δεδομένα;: Πώς διαβάζω ή γράφω δυαδικά δεδομένα;. 
* Δεν μπορώ να χρησιμοποιήσω το os.read() σε ένα pipe που δημιουργήθηκε με το os.popen()∙ γιατί;: Δεν μπορώ να χρησιμοποιήσω το os read σε ένα pipe που δημιουργήθηκε με το os popen ∙ γιατί;. 
* Πώς μπορώ να αποκτήσω πρόσβαση στη σειριακή θύρα (RS232);: Πώς μπορώ να αποκτήσω πρόσβαση στη σειριακή θύρα RS232 ;. 
* Γιατί το κλείσιμο του sys.stdout (stdin@comma{} stderr) δεν το κλείνει πραγματικά;: Γιατί το κλείσιμο του sys stdout stdin stderr δεν το κλείνει πραγματικά;. 

@end menu

@node Πώς μπορώ να διαγράψω ένα αρχείο; Και άλλες ερωτήσεις για το αρχείο…,Πως αντιγράφω ένα αρχείο;,,Είσοδος και Έξοδος<2>
@anchor{faq/library how-do-i-delete-a-file-and-other-file-questions}@anchor{5cee}
@subsubsection Πώς μπορώ να διαγράψω ένα αρχείο; (Και άλλες ερωτήσεις για το αρχείο…)


Χρησιμοποιήστε τα @code{os.remove(filename)} ή @code{os.unlink(filename)} ∙ για τεκμηρίωση, ανατρέξτε στο module @ref{a5,,os}.  Οι δύο συναρτήσεις είναι ίδιες∙ η @ref{14a1,,unlink()} είναι απλώς το όνομα της κλήσης συστήματος Unix για αυτήν τη λειτουργία.

Για να καταργήσετε έναν κατάλογο, χρησιμοποιήστε τη @ref{149f,,os.rmdir()} ∙ χρησιμοποιήστε τη @ref{72e,,os.mkdir()} για να δημιουργήσετε έναν. Το @code{os.makedirs(path)} θα δημιουργήσει τυχόν ενδιάμεσους καταλόγους στο @code{path} που δεν υπάρχουν. Το @code{os.removedirs(path)} θα αφαιρέσει τους ενδιάμεσους καταλόγους εφόσον είναι κενοί∙ εάν θέλετε να διαγράψετε ολόκληρο δέντρο καταλόγου και τα περιεχόμενα του, χρησιμοποιήστε τη @ref{335,,shutil.rmtree()}.

Για να μετονομάσετε ένα αρχείο, χρησιμοποιήστε το @code{os.rename(old_path, new_path)}.

Για να περικόψετε ένα αρχείο, ανοίξτε το χρησιμοποιώντας @code{f = open(filename, "rb+")}, και χρησιμοποιήστε το @code{f.truncate(offset)} ∙ το offset προεπιλέγεται στη τρέχουσα θέση αναζήτησης.  Υπάρχει επίσης το @code{os.ftruncate(fd, offset)} για αρχεία που έχουν ανοιχτεί με @ref{114b,,os.open()}, όπου `fd' είναι ο περιγραφέας αρχείου (ένας μικρός ακέραιος).

Το module @ref{cd,,shutil} περιέχει επίσης έναν αριθμό λειτουργιών για εργασία σε αρχεία, όπως @ref{e1d,,copyfile()}, @ref{ded,,copytree()}, και @ref{335,,rmtree()}.

@node Πως αντιγράφω ένα αρχείο;,Πώς διαβάζω ή γράφω δυαδικά δεδομένα;,Πώς μπορώ να διαγράψω ένα αρχείο; Και άλλες ερωτήσεις για το αρχείο…,Είσοδος και Έξοδος<2>
@anchor{faq/library how-do-i-copy-a-file}@anchor{5cef}
@subsubsection Πως αντιγράφω ένα αρχείο;


Το module @ref{cd,,shutil} περιέχει μια συνάρτηση @ref{e1d,,copyfile()}. Σημειώστε ότι στους τόμους NTFS των Windows, δεν αντιγράφει alternate data streams@footnote{https://en.wikipedia.org/wiki/NTFS#Alternate_data_stream_(ADS)} ούτε resource forks@footnote{https://en.wikipedia.org/wiki/Resource_fork} σε τόμους macOS HFS+, αν και οι δύο χρησιμοποιούνται πλέον σπάνια. Επίσης δεν αντιγράφει δικαιώματα αρχείων και μεταδεδομένα, αν και η χρήση @ref{e1f,,shutil.copy2()} θα διατηρήσει το μεγαλύτερο μέρος (αν και όχι όλο) από αυτό.

@node Πώς διαβάζω ή γράφω δυαδικά δεδομένα;,Δεν μπορώ να χρησιμοποιήσω το os read σε ένα pipe που δημιουργήθηκε με το os popen ∙ γιατί;,Πως αντιγράφω ένα αρχείο;,Είσοδος και Έξοδος<2>
@anchor{faq/library how-do-i-read-or-write-binary-data}@anchor{5cf0}
@subsubsection Πώς διαβάζω (ή γράφω) δυαδικά δεδομένα;


Για να διαβάσετε ή να γράψετε σύνθετες μορφές δυαδικών δεδομένων, είναι καλύτερο να χρησιμοποιήσετε το module @ref{de,,struct}.  Σας επιτρέπει να πάρετε μια συμβολοσειρά που περιέχει δυαδικά δεδομένα (συνήθως αριθμούς) και να τη μετατρέψετε σε αντικείμενα Python και αντίστροφα.

Για παράδειγμα, ο παρακάτω κώδικας διαβάζει δύο ακέραιους αριθμούς 2 byte και έναν ακέραιο αριθμό 4 byte σε μορφή big-endian από ένα αρχείο:

@example
import struct

with open(filename, "rb") as f:
    s = f.read(8)
    x, y, z = struct.unpack(">hhl", s)
@end example

Το “>” στη συμβολοσειρά μορφής αναγκάζει δεδομένα big-endian∙ το γράμμα “h” διαβάζει έναν «short integer» (2 bytes), και το “l” διαβάζει έναν «long integer» (4 byte) από την συμβολοσειρά.

Για δεδομένα που είναι πιο κανονικά (π.χ. μια ομοιογενής λίστα ακεραίων ή αριθμούς με υποδιαστολή), μπορείτε επίσης να χρησιμοποιήσετε το module @ref{8,,array}.

@cartouche
@quotation Σημείωση 
Για να διαβάσετε και να γράψετε δυαδικά δεδομένα, είναι υποχρεωτικό να ανοίξετε το αρχείο σε δυαδική λειτουργία (εδώ, περνώντας το @code{"rb"} στη @ref{32b,,open()}).  Εάν χρησιμοποιήσετε το @code{"r"} αντί αυτού (προεπιλεγμένο) το αρχείο θα είναι ανοιχτό σε λειτουργία κειμένου και το @code{f.read()} θα επιστρέψει αντικείμενα @ref{1df,,str} αντί για αντικείμενα @ref{1c7,,bytes}.
@end quotation
@end cartouche

@node Δεν μπορώ να χρησιμοποιήσω το os read σε ένα pipe που δημιουργήθηκε με το os popen ∙ γιατί;,Πώς μπορώ να αποκτήσω πρόσβαση στη σειριακή θύρα RS232 ;,Πώς διαβάζω ή γράφω δυαδικά δεδομένα;,Είσοδος και Έξοδος<2>
@anchor{faq/library i-can-t-seem-to-use-os-read-on-a-pipe-created-with-os-popen-why}@anchor{5cf1}
@subsubsection Δεν μπορώ να χρησιμοποιήσω το os.read() σε ένα pipe που δημιουργήθηκε με το os.popen()∙ γιατί;


Η @ref{114e,,os.read()} είναι μια συνάρτηση χαμηλού επιπέδου που παίρνει έναν περιγραφέα αρχείου, έναν μικρό ακέραιο που αντιπροσωπεύει το ανοιχτό αρχείο.  Η @ref{585,,os.popen()} δημιουργεί ένα αντικείμενο αρχείου υψηλού επιπέδου, του ίδιου τύπου που επιστρέφεται από την ενσωματωμένη συνάρτηση @ref{32b,,open()}. Έτσι, για να διαβάσετε `n' byte από ένα pipe `p' που δημιουργήθηκε με τη @code{os.popen()}, πρέπει να χρησιμοποιήσετε το @code{p.read(n)}.

@node Πώς μπορώ να αποκτήσω πρόσβαση στη σειριακή θύρα RS232 ;,Γιατί το κλείσιμο του sys stdout stdin stderr δεν το κλείνει πραγματικά;,Δεν μπορώ να χρησιμοποιήσω το os read σε ένα pipe που δημιουργήθηκε με το os popen ∙ γιατί;,Είσοδος και Έξοδος<2>
@anchor{faq/library how-do-i-access-the-serial-rs232-port}@anchor{5cf2}
@subsubsection Πώς μπορώ να αποκτήσω πρόσβαση στη σειριακή θύρα (RS232);


Για Win32, OSX, Linux, BSD, Jython, IronPython:

@quotation

pyserial@footnote{https://pypi.org/project/pyserial/}
@end quotation

Για το Unix, δείτε μια ανάρτηση στο Usenet από τον Mitch Chapman:

@quotation

@indicateurl{https://groups.google.com/groups?selm=34A04430.CF9@@ohioee.com}
@end quotation

@node Γιατί το κλείσιμο του sys stdout stdin stderr δεν το κλείνει πραγματικά;,,Πώς μπορώ να αποκτήσω πρόσβαση στη σειριακή θύρα RS232 ;,Είσοδος και Έξοδος<2>
@anchor{faq/library why-doesn-t-closing-sys-stdout-stdin-stderr-really-close-it}@anchor{5cf3}
@subsubsection Γιατί το κλείσιμο του sys.stdout (stdin, stderr) δεν το κλείνει πραγματικά;


Το Python @ref{156c,,file objects} είναι ένα επίπεδο αφαίρεσης υψηλού επιπέδου σε χαμηλού επιπέδου περιγραφείς αρχείων C.

Για τα περισσότερα αντικείμενα αρχείων που δημιουργείτε στην Python μέσω της ενσωματωμένης συνάρτησης @ref{32b,,open()}, η @code{f.close()} επισημαίνει το αντικείμενο αρχείου Python ως κλειστό από την άποψη της Python και επίσης κανονίζει να κλείσει ο υποκείμενος περιγραφέας αρχείου C. Αυτό συμβαίνει επίσης αυτόματα στον καταστροφέα του @code{f}, όταν το @code{f} γίνεται σκουπίδια.

Αλλά τα stdin, stdout και stderr αντιμετωπίζονται ειδικά από την Python, λόγω της ειδικής κατάστασης που τους δίνεται επίσης από τη C.  Εκτελώντας το @code{sys.stdout.close()} επισημαίνει το αντικείμενο αρχείου σε επίπεδο Python ως κλειστό, αλλά `δεν' κλείνει το συσχετισμένο περιγραφικό αρχείου C.

Για να κλείσετε τον υποκείμενο περιγραφέα αρχείου C για ένα από αυτά τα τρία, θα πρέπει πρώτα να βεβαιωθείτε ότι αυτό θέλετε πραγματικά να κάνετε (π.χ., μπορείτε να μπερδέψετε τα modules επέκτασης που προσπαθούν να κάνουν I/O).  Εάν είναι, χρησιμοποιήστε τη @ref{f31,,os.close()}:

@example
os.close(stdin.fileno())
os.close(stdout.fileno())
os.close(stderr.fileno())
@end example

Ή μπορείτε να χρησιμοποιήσετε τις αριθμητικές σταθερές 0, 1 και 2, αντίστοιχα.

@node Προγραμματισμός Δικτύου/Διαδικτύου,Βάσεις Δεδομένων,Είσοδος και Έξοδος<2>,Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης
@anchor{faq/library network-internet-programming}@anchor{5cf4}
@subsection Προγραμματισμός Δικτύου/Διαδικτύου


@menu
* Ποια εργαλεία WWW υπάρχουν για την Python;:: 
* Τι module πρέπει να χρησιμοποιήσω για να βοηθήσω στην δημιουργία HTML;:: 
* Πώς μπορώ να στείλω αλληλογραφία από ένα Python script;:: 
* Πώς μπορώ να αποφύγω τον αποκλεισμό στη μέθοδο connect() ενός socket;: Πώς μπορώ να αποφύγω τον αποκλεισμό στη μέθοδο connect ενός socket;. 

@end menu

@node Ποια εργαλεία WWW υπάρχουν για την Python;,Τι module πρέπει να χρησιμοποιήσω για να βοηθήσω στην δημιουργία HTML;,,Προγραμματισμός Δικτύου/Διαδικτύου
@anchor{faq/library what-www-tools-are-there-for-python}@anchor{5cf5}
@subsubsection Ποια εργαλεία WWW υπάρχουν για την Python;


Δείτε τα κεφάλαια με τίτλο @ref{4107,,Πρωτόκολλα Internet και Υποστήριξη} και @ref{3cfc,,Internet Data Handling} στο Εγχειρίδιο Αναφοράς Βιβλιοθήκης.  Η Python έχει πολλά modules που θα σας βοηθήσουν να δημιουργήσετε συστήματα ιστού από την πλευρά του διακομιστή και του πελάτη.

@c XXX check if wiki page is still up to date

Μια σύνοψη των διαθέσιμων πλαισίων διατηρείται από τον Paul Boddie στη διεύθυνση @indicateurl{https://wiki.python.org/moin/WebProgramming}.

@node Τι module πρέπει να χρησιμοποιήσω για να βοηθήσω στην δημιουργία HTML;,Πώς μπορώ να στείλω αλληλογραφία από ένα Python script;,Ποια εργαλεία WWW υπάρχουν για την Python;,Προγραμματισμός Δικτύου/Διαδικτύου
@anchor{faq/library what-module-should-i-use-to-help-with-generating-html}@anchor{5cf6}
@subsubsection Τι module πρέπει να χρησιμοποιήσω για να βοηθήσω στην δημιουργία HTML;


@c XXX add modern template languages

Μπορείτε να βρείτε μια συλλογή από χρήσιμους συνδέσμους στη σελίδα Web Programming wiki page@footnote{https://wiki.python.org/moin/WebProgramming}.

@node Πώς μπορώ να στείλω αλληλογραφία από ένα Python script;,Πώς μπορώ να αποφύγω τον αποκλεισμό στη μέθοδο connect ενός socket;,Τι module πρέπει να χρησιμοποιήσω για να βοηθήσω στην δημιουργία HTML;,Προγραμματισμός Δικτύου/Διαδικτύου
@anchor{faq/library how-do-i-send-mail-from-a-python-script}@anchor{5cf7}
@subsubsection Πώς μπορώ να στείλω αλληλογραφία από ένα Python script;


Χρησιμοποιήστε την τυπική module βιβλιοθήκη @ref{d2,,smtplib}.

Εδώ είναι ένας πολύ απλός διαδραστικός αποστολέας αλληλογραφίας που τον χρησιμοποιεί.  Αυτή η μέθοδος θα λειτουργήσει σε οποιονδήποτε κεντρικό υπολογιστή υποστηρίζει το πρόγραμμα ακρόασης 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

Μια εναλλακτική λύση μόνο για Unix χρησιμοποιεί sendmail.  Η τοποθεσία του προγράμματος sendmail ποικίλλει μεταξύ των συστημάτων∙ μερικές φορές είναι @code{/usr/lib/sendmail}, μερικές φορές @code{/usr/sbin/sendmail}.  Η σελίδα εγχειριδίου sendmail θα σας βοηθήσει.  Ορίστε ένα δείγμα κώδικα:

@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 Πώς μπορώ να αποφύγω τον αποκλεισμό στη μέθοδο connect ενός socket;,,Πώς μπορώ να στείλω αλληλογραφία από ένα Python script;,Προγραμματισμός Δικτύου/Διαδικτύου
@anchor{faq/library how-do-i-avoid-blocking-in-the-connect-method-of-a-socket}@anchor{5cf8}
@subsubsection Πώς μπορώ να αποφύγω τον αποκλεισμό στη μέθοδο connect() ενός socket;


Το module @ref{c9,,select} χρησιμοποιείται συνήθως για να βοηθήσει με ασύγχρονες I/O σε sockets.

Για να αποτρέψετε τον αποκλεισμό της σύνδεσης TCP, μπορείτε να ρυθμίσετε την υποδοχή σε λειτουργία μη αποκλεισμού.  Στην συνέχεια, όταν κάνετε τη @ref{115c,,connect()}, είτε θα συνδεθείτε αμέσως (απίθανο), είτε θα λάβετε μια εξαίρεση που περιέχει τον αριθμό σφάλματος ως @code{.errno}. Το @code{errno.EINPROGRESS} υποδηλώνει ότι η σύνδεση είναι σε εξέλιξη, αλλά δεν έχει ολοκληρωθεί ακόμα.  Διαφορετικά λειτουργικά συστήματα θα επιστρέψουν διαφορετικές τιμές, επομένως θα πρέπει να ελέγξετε τι επιστρέφεται στο σύστημα σας.

Μπορείτε να χρησιμοποιήσετε τη μέθοδο @ref{18db,,connect_ex()} για να αποφύγετε τη δημιουργία εξαίρεσης. Απλώς θα επιστρέψει την τιμή errno. Για δημοσκόπηση, μπορείτε να καλέσετε το @code{connect_ex()} ξανά αργότερα – @code{0} ή @code{errno.EISCONN} υποδηλώνει ότι είστε συνδεδεμένοι – ή μπορείτε να περάσετε αυτό το socket στη @ref{1159,,select.select()} για να ελέγξτε αν είναι εγγράψιμο.

@cartouche
@quotation Σημείωση 
Το module @ref{b,,asyncio} παρέχει μια γενικού σκοπού απλή και ταυτόχρονη ασύγχρονη βιβλιοθήκη, η οποία μπορεί να χρησιμοποιηθεί για τη σύνταξη κώδικα δικτύου χωρίς αποκλεισμό.  Η βιβλιοθήκη Twisted@footnote{https://twisted.org/} είναι μια δημοφιλής και με πολλές λειτουργίες εναλλακτική λύση.
@end quotation
@end cartouche

@node Βάσεις Δεδομένων,Μαθηματικά και Αριθμητικά,Προγραμματισμός Δικτύου/Διαδικτύου,Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης
@anchor{faq/library databases}@anchor{5cf9}
@subsection Βάσεις Δεδομένων


@menu
* Υπάρχουν διεπαφές σε πακέτα βάσεων δεδομένων στην Python;:: 
* Πως υλοποιείτε persistent αντικείμενα στην Python;:: 

@end menu

@node Υπάρχουν διεπαφές σε πακέτα βάσεων δεδομένων στην Python;,Πως υλοποιείτε persistent αντικείμενα στην Python;,,Βάσεις Δεδομένων
@anchor{faq/library are-there-any-interfaces-to-database-packages-in-python}@anchor{5cfa}
@subsubsection Υπάρχουν διεπαφές σε πακέτα βάσεων δεδομένων στην Python;


Ναι.

Διεπαφές σε κατακερματισμούς που βασίζονται σε δίσκο, όπως @ref{37,,DBM} και @ref{36,,GDBM} περιλαμβάνονται επίσης στην τυπική Python.  Υπάρχει επίσης το module @ref{d7,,sqlite3}, το οποίο παρέχει μια ελαφριά σχεσιακή βάση δεδομένων που βασίζεται στο δίσκο.

Υποστήριξη για τις περισσότερες σχεσιακές βάσεις δεδομένων είναι διαθέσιμη.  Δείτε τη σελίδα DatabaseProgramming wiki page@footnote{https://wiki.python.org/moin/DatabaseProgramming} για λεπτομέρειες.

@node Πως υλοποιείτε persistent αντικείμενα στην Python;,,Υπάρχουν διεπαφές σε πακέτα βάσεων δεδομένων στην Python;,Βάσεις Δεδομένων
@anchor{faq/library how-do-you-implement-persistent-objects-in-python}@anchor{5cfb}
@subsubsection Πως υλοποιείτε persistent αντικείμενα στην Python;


To module βιβλιοθήκης @ref{ab,,pickle} το λύνει αυτό με πολύ γενικό τρόπο (αν και δεν μπορείτε ακόμα να αποθηκεύσετε πράγματα όπως ανοιχτά αρχεία, sockets ή παράθυρα), και το module βιβλιοθήκης @ref{cb,,shelve} χρησιμοποιεί pickle και (g)dbm για τη δημιουργία επίμονων αντιστοιχίσεων που περιέχουν αυθαίρετα αντικείμενα Python.

@node Μαθηματικά και Αριθμητικά,,Βάσεις Δεδομένων,Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης
@anchor{faq/library mathematics-and-numerics}@anchor{5cfc}
@subsection Μαθηματικά και Αριθμητικά


@menu
* Πως μπορώ να δημιουργήσω τυχαίους αριθμούς στην Python;:: 

@end menu

@node Πως μπορώ να δημιουργήσω τυχαίους αριθμούς στην Python;,,,Μαθηματικά και Αριθμητικά
@anchor{faq/library how-do-i-generate-random-numbers-in-python}@anchor{5cfd}
@subsubsection Πως μπορώ να δημιουργήσω τυχαίους αριθμούς στην Python;


Το τυπικό module @ref{c0,,random} υλοποιεί μια γεννήτρια τυχαίων αριθμών.  Η χρήση είναι απλή:

@example
import random
random.random()
@end example

Αυτό επιστρέφει έναν τυχαίο αριθμό κινητής υποδιαστολής στο εύρος [0, 1).

Υπάρχουν επίσης πολλές άλλες εξειδικευμένες γεννήτριες σε αυτό το module, όπως:


@itemize *

@item 
Το @code{randrange(a, b)} επιλέγει έναν ακέραιο στο εύρος [a, b).

@item 
Το @code{uniform(a, b)} επιλέγει έναν αριθμό κινητής υποδιαστολής στο εύρος [a, b).

@item 
Το @code{normalvariate(mean, sdev)} λαμβάνει δείγματα της κανονικής (Gaussian) κατανομής.
@end itemize

Ορισμένες συναρτήσεις υψηλότερου επιπέδου λειτουργούν απευθείας σε ακολουθίες, όπως:


@itemize *

@item 
To @code{choice(S)} επιλέγει ένα τυχαίο στοιχείο από μια δεδομένη ακολουθία.

@item 
Το @code{shuffle(L)} ανακατεύει μια λίστα επιτόπου, δηλαδή τη μεταθέτει τυχαία.
@end itemize

Υπάρχει επίσης μια κλάση @code{Random} που μπορείτε να επιβεβαιώσετε για να δημιουργήσετε ανεξάρτητες γεννήτριες πολλαπλών τυχαίων αριθμών.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης,Python στα Windows FAQ,Συχνές ερωτήσεις βιβλιοθήκης και επέκτασης,Συχνές Ερωτήσεις για την Python
@anchor{faq/extending doc}@anchor{5cfe}@anchor{faq/extending extending-embedding-faq}@anchor{5cff}@anchor{faq/extending translation-repo}@anchor{5d00}
@section Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης



@c XXX need review for Python 3.

@menu
* Μπορώ να δημιουργήσω τις δικές μου συναρτήσεις στη C;:: 
* Μπορώ να δημιουργήσω τις δικές μου συναρτήσεις στη C++;:: 
* Το να γράψει C κάποιος είναι δύσκολο· υπάρχουν άλλες εναλλακτικές;:: 
* Πως μπορώ να εκτελέσω αυθαίρετες δηλώσεις Python από το C;:: 
* Πώς μπορώ να αξιολογήσω μια αυθαίρετη έκφραση Python από τη C;:: 
* Πως μπορώ να εξάγω τιμές C από ένα αντικείμενο Python;:: 
* Πώς μπορώ να χρησιμοποιήσω την Py_BuildValue() για να δημιουργήσω μια πλειάδα (tuple) αυθαίρετου μήκους;: Πώς μπορώ να χρησιμοποιήσω την Py_BuildValue για να δημιουργήσω μια πλειάδα tuple αυθαίρετου μήκους;. 
* Πώς καλώ τη μέθοδο ενός αντικειμένου από τη C;:: 
* Πώς μπορώ να κάνω catch την έξοδο από την PyErr_Print() (ή οτιδήποτε εκτυπώνεται σε stdout/stderr);: Πώς μπορώ να κάνω catch την έξοδο από την PyErr_Print ή οτιδήποτε εκτυπώνεται σε stdout/stderr ;. 
* Πως μπορώ να αποκτήσω πρόσβαση σε ένα module γραμμένο σε Python από τη C;:: 
* Πως διασυνδέομαι με αντικείμενα C++ από την Python;:: 
* Πρόσθεσα ένα module χρησιμοποιώντας το αρχείο Setup και το make αποτυγχάνει· γιατί;:: 
* Πως κάνω debug μια επέκταση;:: 
* Θέλω να κάνω compile ένα Python module στο σύστημα Linux μου@comma{} αλλά λείπουν ορισμένα αρχεία. Γιατί;: Θέλω να κάνω compile ένα Python module στο σύστημα Linux μου αλλά λείπουν ορισμένα αρχεία Γιατί;. 
* Πώς μπορώ να ξεχωρίσω την «ελλιπή εισαγωγή» από την «έγκυρη εισαγωγή»;:: 
* Πώς μπορώ να βρω απροσδιόριστα σύμβολα g++ __builtin_new ή __pure_virtual;:: 
* Μπορώ να δημιουργήσω μια κλάση αντικειμένου με ορισμένες μεθόδους που υλοποιούνται στη C και άλλες στη Python (π.χ. μέσω κληρονομικότητας);: Μπορώ να δημιουργήσω μια κλάση αντικειμένου με ορισμένες μεθόδους που υλοποιούνται στη C και άλλες στη Python π χ μέσω κληρονομικότητας ;. 

@end menu

@node Μπορώ να δημιουργήσω τις δικές μου συναρτήσεις στη C;,Μπορώ να δημιουργήσω τις δικές μου συναρτήσεις στη C++;,,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending can-i-create-my-own-functions-in-c}@anchor{5d01}
@subsection Μπορώ να δημιουργήσω τις δικές μου συναρτήσεις στη C;


Ναι, μπορείτε να δημιουργήσετε ενσωματωμένα (built-in) modules που περιέχουν συναρτήσεις, μεταβλητές, εξαιρέσεις και ακόμη και νέους τύπους στην C.  Αυτό εξηγείται στο έγγραφο @ref{21aa,,Επέκταση και Ενσωμάτωση του Διερμηνέα της Python}.

Τα περισσότερα βιβλία μεσαίας ή προηγμένης Python θα καλύπτουν επίσης αυτό το θέμα.

@node Μπορώ να δημιουργήσω τις δικές μου συναρτήσεις στη C++;,Το να γράψει C κάποιος είναι δύσκολο· υπάρχουν άλλες εναλλακτικές;,Μπορώ να δημιουργήσω τις δικές μου συναρτήσεις στη C;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending id1}@anchor{5d02}
@subsection Μπορώ να δημιουργήσω τις δικές μου συναρτήσεις στη C++;


Ναι, χρησιμοποιώντας τις δυνατότητες συμβατότητας C που βρίσκονται στη C++.  Τοποθετήστε το @code{extern "C" @{ ... @}} γύρω από την Python να περιλαμβάνει αρχεία και τοποθετήστε το @code{extern "C"} πριν από κάθε συνάρτηση που πρόκειται να κληθεί από τον διερμηνέα της Python.  Τα καθολικά ή τα στατικά αντικείμενα C++ με constructors μάλλον δεν είναι καλή ιδέα.

@node Το να γράψει C κάποιος είναι δύσκολο· υπάρχουν άλλες εναλλακτικές;,Πως μπορώ να εκτελέσω αυθαίρετες δηλώσεις Python από το C;,Μπορώ να δημιουργήσω τις δικές μου συναρτήσεις στη C++;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending c-wrapper-software}@anchor{5d03}@anchor{faq/extending writing-c-is-hard-are-there-any-alternatives}@anchor{5d04}
@subsection Το να γράψει C κάποιος είναι δύσκολο· υπάρχουν άλλες εναλλακτικές;


Υπάρχουν αρκετές εναλλακτικές λύσεις για τη σύνταξη των δικών σας επεκτάσεων C, ανάλογα με το τι προσπαθείτε να κάνετε. Το @ref{5198,,Recommended third party tools} προσφέρουν απλούστερες και πιο εξελιγμένες προσεγγίσεις για τη δημιουργία επεκτάσεων C και C++ για Python.

@node Πως μπορώ να εκτελέσω αυθαίρετες δηλώσεις Python από το C;,Πώς μπορώ να αξιολογήσω μια αυθαίρετη έκφραση Python από τη C;,Το να γράψει C κάποιος είναι δύσκολο· υπάρχουν άλλες εναλλακτικές;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending how-can-i-execute-arbitrary-python-statements-from-c}@anchor{5d05}
@subsection Πως μπορώ να εκτελέσω αυθαίρετες δηλώσεις Python από το C;


Η συνάρτηση υψηλότερου επιπέδου για να γίνει αυτό είναι η @ref{5221,,PyRun_SimpleString()} η οποία εκτελεί ένα όρισμα συμβολοσειράς στο πλαίσιο της ενότητας @code{__main__} και επιστρέφει @code{0} για επιτυχία και @code{-1} όταν συμβαίνει μια εξαίρεση (συμπεριλαμβανομένου του @ref{17e,,SyntaxError}).  Εάν θέλετε περισσότερο έλεγχο, χρησιμοποιήστε @ref{1fb0,,PyRun_String()} · δείτε τον πηγαίο κώδικα @code{PyRun_SimpleString()} στο @code{Python/pythonrun.c}.

@node Πώς μπορώ να αξιολογήσω μια αυθαίρετη έκφραση Python από τη C;,Πως μπορώ να εξάγω τιμές C από ένα αντικείμενο Python;,Πως μπορώ να εκτελέσω αυθαίρετες δηλώσεις Python από το C;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending how-can-i-evaluate-an-arbitrary-python-expression-from-c}@anchor{5d06}
@subsection Πώς μπορώ να αξιολογήσω μια αυθαίρετη έκφραση Python από τη C;


Καλέστε τη συνάρτηση @ref{1fb0,,PyRun_String()} από την προηγούμενη ερώτηση με το σύμβολο έναρξης @ref{550a,,Py_eval_input}· αναλύει μια παράσταση, την αξιολογεί και επιστρέφει την τιμή της.

@node Πως μπορώ να εξάγω τιμές C από ένα αντικείμενο Python;,Πώς μπορώ να χρησιμοποιήσω την Py_BuildValue για να δημιουργήσω μια πλειάδα tuple αυθαίρετου μήκους;,Πώς μπορώ να αξιολογήσω μια αυθαίρετη έκφραση Python από τη C;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending how-do-i-extract-c-values-from-a-python-object}@anchor{5d07}
@subsection Πως μπορώ να εξάγω τιμές C από ένα αντικείμενο Python;


Αυτό εξαρτάται από τον τύπο του αντικειμένου.  Εάν είναι μια πλειάδα (tuple), @ref{5416,,PyTuple_Size()} επιστρέφει το μήκος του και το @ref{51ce,,PyTuple_GetItem()} επιστρέφει το στοιχείο σε ένα καθορισμένο index.  Οι λίστες έχουν παρόμοιες συναρτήσεις, @ref{17bc,,PyList_Size()} και @ref{7f5,,PyList_GetItem()}.

Για bytes, @ref{52ac,,PyBytes_Size()} επιστρέφει το μήκος του και το @ref{52a4,,PyBytes_AsStringAndSize()} παρέχει έναν δείκτη στην τιμή και το μήκος του.  Λάβετε υπόψη ότι τα αντικείμενα byte της Python μπορεί να περιέχουν null byte, επομένως η @code{strlen()} της C δεν πρέπει να χρησιμοποιείται.

Για να ελέγξετε τον τύπο ενός αντικειμένου, πρώτα βεβαιωθείτε ότι δεν είναι @code{NULL}, και μετά χρησιμοποιήστε τα @ref{1743,,PyBytes_Check()}, @ref{56ef,,PyTuple_Check()}, @ref{5700,,PyList_Check()}, κλπ.

Υπάρχει επίσης ένα API υψηλού επιπέδου για αντικείμενα Python που παρέχεται από τη λεγόμενη “abstract” διεπαφή (interface) – διαβάστε @code{Include/abstract.h} για περισσότερες λεπτομέρειες.  Επιτρέπει τη διασύνδεση με κάθε είδους ακολουθίας Python χρησιμοποιώντας κλήσεις όπως @ref{53df,,PySequence_Length()}, @ref{2021,,PySequence_GetItem()}, κλπ. καθώς και πολλά άλλα χρήσιμα πρωτόκολλα όπως αριθμοί (@ref{c69,,PyNumber_Index()} et al.) και αντιστοιχίσεις στον PyMapping APIs.

@node Πώς μπορώ να χρησιμοποιήσω την Py_BuildValue για να δημιουργήσω μια πλειάδα tuple αυθαίρετου μήκους;,Πώς καλώ τη μέθοδο ενός αντικειμένου από τη C;,Πως μπορώ να εξάγω τιμές C από ένα αντικείμενο Python;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending how-do-i-use-py-buildvalue-to-create-a-tuple-of-arbitrary-length}@anchor{5d08}
@subsection Πώς μπορώ να χρησιμοποιήσω την Py_BuildValue() για να δημιουργήσω μια πλειάδα (tuple) αυθαίρετου μήκους;


Δεν μπορείς.  Χρησιμοποιήστε το @ref{5415,,PyTuple_Pack()}.

@node Πώς καλώ τη μέθοδο ενός αντικειμένου από τη C;,Πώς μπορώ να κάνω catch την έξοδο από την PyErr_Print ή οτιδήποτε εκτυπώνεται σε stdout/stderr ;,Πώς μπορώ να χρησιμοποιήσω την Py_BuildValue για να δημιουργήσω μια πλειάδα tuple αυθαίρετου μήκους;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending how-do-i-call-an-object-s-method-from-c}@anchor{5d09}
@subsection Πώς καλώ τη μέθοδο ενός αντικειμένου από τη C;


Η συνάρτηση @ref{3b6,,PyObject_CallMethod()} μπορεί να χρησιμοποιηθεί για την κλήση μιας αυθαίρετης μεθόδου ενός αντικειμένου.  Οι παράμετροι είναι το αντικείμενο, το όνομα της μεθόδου προς κλήση, μια συμβολοσειρά μορφής όπως αυτή που χρησιμοποιείται με τη @ref{5ee,,Py_BuildValue()}, και τις τιμές ορίσματος:

@example
PyObject *
PyObject_CallMethod(PyObject *object, const char *method_name,
                    const char *arg_format, ...);
@end example

Αυτό λειτουργεί για κάθε αντικείμενο που έχει μεθόδους – είτε είναι ενσωματωμένες είτε καθορίζονται από το χρήστη. Είστε υπεύθυνοι εάν τελικά χρησιμοποιήσετε @ref{975,,Py_DECREF()} στην τιμή επιστροφής.

Για να καλέσετε, π.χ., τη μέθοδο «seek» ενός αντικειμένου αρχείου με ορίσματα 10, 0 (υποθέτοντας ότι ο δείκτης του αντικειμένου αρχείου είναι «f»):

@example
res = PyObject_CallMethod(f, "seek", "(ii)", 10, 0);
if (res == NULL) @{
        ... an exception occurred ...
@}
else @{
        Py_DECREF(res);
@}
@end example

Σημειώστε ότι επειδή το @ref{51c2,,PyObject_CallObject()} `πάντα' θέλει μια πλειάδα (tuple) για τη λίστα ορισμάτων, για να καλέσει μια συνάρτηση χωρίς ορίσματα, να περάσει «()» για τη μορφή και να καλέσει μια συνάρτηση με ένα όρισμα, περιβάλλουν το όρισμα σε παρένθεση, π.χ. «(i)».

@node Πώς μπορώ να κάνω catch την έξοδο από την PyErr_Print ή οτιδήποτε εκτυπώνεται σε stdout/stderr ;,Πως μπορώ να αποκτήσω πρόσβαση σε ένα module γραμμένο σε Python από τη C;,Πώς καλώ τη μέθοδο ενός αντικειμένου από τη C;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending how-do-i-catch-the-output-from-pyerr-print-or-anything-that-prints-to-stdout-stderr}@anchor{5d0a}
@subsection Πώς μπορώ να κάνω catch την έξοδο από την PyErr_Print() (ή οτιδήποτε εκτυπώνεται σε stdout/stderr);


Στον κώδικα Python, ορίστε ένα αντικείμενο που υποστηρίζει τη μέθοδο @code{write()}.  Αντιστοιχίστε αυτό το αντικείμενο στα @ref{e9c,,sys.stdout} και @ref{d05,,sys.stderr}.  Καλέστε το print_error, ή απλώς επιτρέψτε στον τυπικό μηχανισμό ανίχνευσης να λειτουργήσει. Στη συνέχεια, η έξοδος θα πάει οπουδήποτε την στείλει η μέθοδος @code{write()}.

Ο ευκολότερος τρόπος για να το κάνετε αυτό είναι να χρησιμοποιήσετε την κλάση @ref{12d4,,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

Ένα προσαρμοσμένο αντικείμενο για να κάνει το ίδιο θα μοιάζει με αυτό:

@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 Πως μπορώ να αποκτήσω πρόσβαση σε ένα module γραμμένο σε Python από τη C;,Πως διασυνδέομαι με αντικείμενα C++ από την Python;,Πώς μπορώ να κάνω catch την έξοδο από την PyErr_Print ή οτιδήποτε εκτυπώνεται σε stdout/stderr ;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending how-do-i-access-a-module-written-in-python-from-c}@anchor{5d0b}
@subsection Πως μπορώ να αποκτήσω πρόσβαση σε ένα module γραμμένο σε Python από τη C;


Μπορείτε να λάβετε έναν δείκτη στο αντικείμενο του module ως εξής:

@example
module = PyImport_ImportModule("<modulename>");
@end example

Εάν το module δεν έχει εισαχθεί ακόμα (δηλαδή δεν υπάρχει ακόμα στο @ref{19ba,,sys.modules}), αυτό αρχικοποιεί το module· διαφορετικά απλώς επιστρέφει την τιμή του @code{sys.modules["<modulename>"]}.  Σημειώστε ότι δεν εισάγει το module σε κανένα namespace – διασφαλίζει μόνο ότι έχει αρχικοποιηθεί και ότι είναι αποθηκευμένη στο @code{sys.modules}.

Μπορείτε στη συνέχεια να αποκτήσετε πρόσβαση στα χαρακτηριστικά του module (δηλαδή οποιοδήποτε όνομα ορίζεται στο module) ως εξής:

@example
attr = PyObject_GetAttrString(module, "<attrname>");
@end example

Η κλήση @ref{1a6c,,PyObject_SetAttrString()} για αντιστοίχιση σε μεταβλητές στο module λειτουργεί επίσης.

@node Πως διασυνδέομαι με αντικείμενα C++ από την Python;,Πρόσθεσα ένα module χρησιμοποιώντας το αρχείο Setup και το make αποτυγχάνει· γιατί;,Πως μπορώ να αποκτήσω πρόσβαση σε ένα module γραμμένο σε Python από τη C;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending how-do-i-interface-to-c-objects-from-python}@anchor{5d0c}
@subsection Πως διασυνδέομαι με αντικείμενα C++ από την Python;


Ανάλογα με τις απαιτήσεις σας, υπάρχουν πολλές προσεγγίσεις.  Για να το κάνετε αυτό χειροκίνητα, ξεκινήστε διαβάζοντας το @ref{21aa,,the «Extending and Embedding» document} .  Συνειδητοποιήστε ότι για το σύστημα χρόνου εκτελεστή Python, δεν υπάρχει μεγάλη διαφορά μεταξύ C και C++ – επομένως η στρατηγική της δημιουργίας ενός νέου τύπου Python γύρω από έναν τύπο δομής C (δείκτη) θα λειτουργήσει επίσης για αντικείμενα C++.

Για βιβλιοθήκες C++, δείτε @ref{5d03,,Το να γράψει C κάποιος είναι δύσκολο· υπάρχουν άλλες εναλλακτικές;}.

@node Πρόσθεσα ένα module χρησιμοποιώντας το αρχείο Setup και το make αποτυγχάνει· γιατί;,Πως κάνω debug μια επέκταση;,Πως διασυνδέομαι με αντικείμενα C++ από την Python;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending i-added-a-module-using-the-setup-file-and-the-make-fails-why}@anchor{5d0d}
@subsection Πρόσθεσα ένα module χρησιμοποιώντας το αρχείο Setup και το make αποτυγχάνει· γιατί;


Το setup πρέπει να τελειώνει σε μια νέα γραμμή, αν δεν υπάρχει νέα γραμμή, η διαδικασία build αποτυγχάνει.  (Για να διορθωθεί αυτό απαιτεί κάποιο κακόβουλο script shell, και αυτό το σφάλμα είναι τόσο μικρό που δεν φαίνεται να αξίζει τον κόπο.)

@node Πως κάνω debug μια επέκταση;,Θέλω να κάνω compile ένα Python module στο σύστημα Linux μου αλλά λείπουν ορισμένα αρχεία Γιατί;,Πρόσθεσα ένα module χρησιμοποιώντας το αρχείο Setup και το make αποτυγχάνει· γιατί;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending how-do-i-debug-an-extension}@anchor{5d0e}
@subsection Πως κάνω debug μια επέκταση;


Όταν χρησιμοποιείτε το GDB με δυναμικά φορτωμένες επεκτάσεις, δεν μπορείτε να ορίσετε σημείο διακοπής στην επέκταση σας μέχρι να φορτωθεί η επέκτασής σας.

Στο αρχείο σας @code{.gdbinit} (ή διαδραστικά), προσθέστε την εντολή:

@example
br _PyImport_LoadDynamicModule
@end example

Στη συνέχεια, όταν εκτελείτε το 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 Θέλω να κάνω compile ένα Python module στο σύστημα Linux μου αλλά λείπουν ορισμένα αρχεία Γιατί;,Πώς μπορώ να ξεχωρίσω την «ελλιπή εισαγωγή» από την «έγκυρη εισαγωγή»;,Πως κάνω debug μια επέκταση;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending i-want-to-compile-a-python-module-on-my-linux-system-but-some-files-are-missing-why}@anchor{5d0f}
@subsection Θέλω να κάνω compile ένα Python module στο σύστημα Linux μου, αλλά λείπουν ορισμένα αρχεία. Γιατί;


Οι περισσότερες συσκευασμένες εκδόσεις της Python παραλείπουν ορισμένα αρχεία που απαιτούνται για τη μεταγλώττιση των επεκτάσεων Python.

Για το Red Hat, εγκαταστήστε το RPM της python3-devel για να λάβετε τα απαραίτητα αρχεία.

Για το Debian, εκτελέστε το @code{apt-get install python3-dev}.

@node Πώς μπορώ να ξεχωρίσω την «ελλιπή εισαγωγή» από την «έγκυρη εισαγωγή»;,Πώς μπορώ να βρω απροσδιόριστα σύμβολα g++ __builtin_new ή __pure_virtual;,Θέλω να κάνω compile ένα Python module στο σύστημα Linux μου αλλά λείπουν ορισμένα αρχεία Γιατί;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending how-do-i-tell-incomplete-input-from-invalid-input}@anchor{5d10}
@subsection Πώς μπορώ να ξεχωρίσω την «ελλιπή εισαγωγή» από την «έγκυρη εισαγωγή»;


Μερικές φορές θέλετε να μιμηθείτε τη συμπεριφορά του διαδραστικού διερμηνέα Python, όπου σας δίνει ένα συνεχόμενο prompt όταν η είσοδος είναι ελλιπής (π.χ. πληκτρολογήσατε την αρχή μιας δήλωσης «if» ή δεν κλείσατε τις παρενθέσεις ή τα τριπλά εισαγωγικά συμβολοσειρών), αλλά σας δίνει ένα μήνυμα συντακτικού σφάλματος αμέσως όταν η εισαγωγή δεν είναι έγκυρη.

Στην Python μπορείτε να χρησιμοποιήσετε το module @ref{1d,,codeop}, η οποία προσεγγίζει επαρκώς τη συμπεριφορά του parser.  Το IDLE χρησιμοποιεί αυτό, για παράδειγμα.

Ο ευκολότερος τρόπος για να το κάνετε στη C είναι να καλέσετε τη @ref{5512,,PyRun_InteractiveLoop()} (ίσως σε ξεχωριστό νήμα (thread)) και να αφήσετε τον διερμηνέα Python να χειριστεί την είσοδο για εσάς. Μπορείτε επίσης να ορίσετε @ref{987,,PyOS_ReadlineFunctionPointer()} για να δείξετε την δικιάς προσαρμοσμένη συνάρτηση εισαγωγής. Δείτε τα @code{Modules/readline.c} και @code{Parser/myreadline.c} για περισσότερες συμβουλές.

@node Πώς μπορώ να βρω απροσδιόριστα σύμβολα g++ __builtin_new ή __pure_virtual;,Μπορώ να δημιουργήσω μια κλάση αντικειμένου με ορισμένες μεθόδους που υλοποιούνται στη C και άλλες στη Python π χ μέσω κληρονομικότητας ;,Πώς μπορώ να ξεχωρίσω την «ελλιπή εισαγωγή» από την «έγκυρη εισαγωγή»;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending how-do-i-find-undefined-g-symbols-builtin-new-or-pure-virtual}@anchor{5d11}
@subsection Πώς μπορώ να βρω απροσδιόριστα σύμβολα g++ __builtin_new ή __pure_virtual;


Για δυναμική φόρτωση module επέκτασης g++, πρέπει να κάνετε recompile την Python, να τη συνδέσετε ξανά χρησιμοποιώντας g++ (αλλάξτε το LINKCC στο Python Modules Makefile), και να συνδέσετε το module επέκτασης σας χρησιμοποιώντας g++ (π.χ. @code{g++ -shared -o mymodule.so mymodule.o}).

@node Μπορώ να δημιουργήσω μια κλάση αντικειμένου με ορισμένες μεθόδους που υλοποιούνται στη C και άλλες στη Python π χ μέσω κληρονομικότητας ;,,Πώς μπορώ να βρω απροσδιόριστα σύμβολα g++ __builtin_new ή __pure_virtual;,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης
@anchor{faq/extending can-i-create-an-object-class-with-some-methods-implemented-in-c-and-others-in-python-e-g-through-inheritance}@anchor{5d12}
@subsection Μπορώ να δημιουργήσω μια κλάση αντικειμένου με ορισμένες μεθόδους που υλοποιούνται στη C και άλλες στη Python (π.χ. μέσω κληρονομικότητας);


Ναι, μπορείτε να κληρονομήσετε από ενσωματωμένες (built-in) κλάσεις όπως @ref{326,,int}, @ref{4d9,,list}, @ref{188,,dict}, κ.λπ.

Η βιβλιοθήκη Boost Python Library (BPL, @indicateurl{https://www.boost.org/libs/python/doc/index.html}) παρέχει ένα τρόπο για να γίνει αυτό από την C++ (δηλαδή μπορείτε να κληρονομήσετε από μια κλάση επέκτασης γραμμένη σε C++ χρησιμοποιώντας το BPL).

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python στα Windows FAQ,Graphic User Interface FAQ,Συχνές ερωτήσεις επέκτασης/ενσωμάτωσης,Συχνές Ερωτήσεις για την Python
@anchor{faq/windows doc}@anchor{5d13}@anchor{faq/windows python-on-windows-faq}@anchor{5d14}@anchor{faq/windows translation-repo}@anchor{5d15}@anchor{faq/windows windows-faq}@anchor{5d16}
@section Python στα Windows FAQ



@c XXX need review for Python 3.
@c XXX need review for Windows Vista/Seven?

@menu
* Πως μπορώ να εκτελέσω ένα πρόγραμμα Python στα Windows;:: 
* Πως κάνω τα Python scripts εκτελέσιμα;:: 
* Γιατί μερικές φορές η Python αργεί τόσο πολύ να ξεκινήσει;:: 
* Πώς μπορώ να δημιουργήσω ένα εκτελέσιμο από ένα σενάριο Python;:: 
* Είναι ένα αρχείο *.pyd ίδιο με ένα αρχείο DLL;: Είναι ένα αρχείο * pyd ίδιο με ένα αρχείο DLL;. 
* Πώς μπορώ να ενσωματώσω την Python σε μια εφαρμογή Windows;:: 
* Πως μπορώ να εμποδίσω τους editors να εισάγουν tabs στον πηγαίο της Python μου;:: 
* Πώς μπορώ να ελέγξω για ένα πάτημα πλήκτρων χωρίς αποκλεισμό;:: 
* Πως μπορώ να διορθώσω το σφάλμα που λείπει το api-ms-win-crt-runtime-l1-1-0.dll;: Πως μπορώ να διορθώσω το σφάλμα που λείπει το api-ms-win-crt-runtime-l1-1-0 dll;. 

@end menu

@node Πως μπορώ να εκτελέσω ένα πρόγραμμα Python στα Windows;,Πως κάνω τα Python scripts εκτελέσιμα;,,Python στα Windows FAQ
@anchor{faq/windows faq-run-program-under-windows}@anchor{5d17}@anchor{faq/windows how-do-i-run-a-python-program-under-windows}@anchor{5d18}
@subsection Πως μπορώ να εκτελέσω ένα πρόγραμμα Python στα Windows;


Αυτό δεν είναι απαραίτητα μια απλή ερώτηση. Εάν είστε ήδη εξοικειωμένοι με την εκτέλεση προγραμμάτων από τη γραμμή εντολών των Windows τότε όλα θα φαίνονται προφανή” διαφορετικά, μπορεί να χρειαστεί λίγη περισσότερη καθοδήγηση.

Εκτός και αν χρησιμοποιείτε κάποιο είδος ενσωματωμένου περιβάλλοντος ανάπτυξης, θα καταλήξετε πληκτρολογώντας εντολές των Windows σε αυτό που αναφέρεται ως «Command prompt window».  Συνήθως μπορείτε να δημιουργήσετε ένα τέτοιο παράθυρο από τη γραμμή αναζήτησης σας κάνοντας αναζήτηση για @code{cmd}.  Θα πρέπει να μπορείτε να αναγνωρίσετε πότε έχετε ξεκινήσει ένα τέτοιο παράθυρο επειδή θα δείτε ένα «command prompt» των Windows, η οποία συνήθως μοιάζει με αυτό:

@example
C:\>
@end example

Το γράμμα μπορεί να είναι διαφορετικό, και μπορεί να υπάρχουνε άλλα πράγματα μετά από αυτό, έτσι μπορείτε να δείτε εξίσου εύκολα κάτι σαν:

@example
D:\YourName\Projects\Python>
@end example

ανάλογα με το πως έχει ρυθμιστεί ο υπολογιστής σας και τι άλλο έχετε κάνει με αυτόν.  Μόλις ξεκινήσετε ένα τέτοιο παράθυρο, είστε σε καλό δρόμο για την εκτέλεση προγραμμάτων Python.

Πρέπει να συνειδητοποιήσετε ότι τα Python σενάρια σας πρέπει να επεξεργαστούν από άλλο πρόγραμμα που ονομάζεται Python `interpreter'.  Ο interpreter διαβάζει το σενάριο σας, το κάνει compile σε bytecodes και στη συνέχεια εκτελεί τα bytecodes για να τρέξει το πρόγραμμά σας. Λοιπόν, πως ρυθμίζετε τον interpreter για να χειριστεί την Python σας;

Πρώτα από όλα, πρέπει να σιγουρευτείτε ότι το παράθυρο εντολών σας αναγνωρίζει την λέξη «py» ως οδηγία για την έναρξη του interpreter.  Εάν έχετε ανοίξει ένα παράθυρο εντολών, θα πρέπει να δοκιμάσετε να εισαγάγετε την εντολή @code{py} και να πατήσετε return:

@example
C:\Users\YourName> py
@end example

Στη συνέχεια, θα πρέπει να δείτε κάτι σαν:

@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

Έχετε ξεκινήσει τον interpreter σε «interactive mode». Αυτό σημαίνει ότι μπορείτε να εισάγετε δηλώσεις ή εκφράσεις Python διαδραστικά και να τις εκτελείτε ή να τις αξιολογείτε ενώ περιμένετε.  Αυτό είναι ένα από τα ισχυρότερα χαρακτηριστικά της Python.  Ελέγξτε το εισάγοντας μερικές εκφράσεις της επιλογή σας και βλέποντας τα αποτελέσματα:

@example
>>> print("Hello")
Hello
>>> "Hello" * 3
'HelloHelloHello'
@end example

Πολλοί άνθρωποι χρησιμοποιούν τη διαδραστική λειτουργία ως μια βολική αλλά εξαιρετικά προγραμματιζόμενη αριθμομηχανή.  Όταν θέλετε να τερματίσετε τη διαδραστική συνεδρία Python, καλέστε τη συνάρτηση @ref{27e1,,exit()} ή κρατήστε πατημένο το πλήκτρο @code{Ctrl} ενώ εισάγετε ένα @code{Z}, και μετά πατήστε το πλήκτρο «@code{Enter}» για να επιστρέψετε στο command prompt των Windows.

Μπορεί επίσης να διαπιστώσετε ότι έχετε μια καταχώρηση στο Start-menu όπως Start ‣ Programs ‣ Python 3.x ‣ Python (command line) που έχει ως αποτέλεσμα να βλέπετε το @code{>>>} σε ένα νέο παράθυρο, το παράθυρο θα εξαφανιστεί αφού καλέσετε τη συνάρτηση @ref{27e1,,exit()} ή εισαγάγετε τον χαρακτήρα @code{Ctrl}-@code{Z}” τα Windows εκτελούν μία μόνο εντολή «python» στο παράθυρο και την κλείνουν όταν τερματίζετε τον interpreter.

Τώρα που γνωρίζουμε ότι η εντολή @code{py} αναγνωρίζεται, μπορείτε να της δώσετε το σενάριο Python σας. Θα πρέπει να δώσετε είτε μια απόλυτη είτε μια σχετική διαδρομή προς στο σενάριο Python. Ας υποθέσουμε ότι το σενάριο Python σας βρίσκεται στην επιφάνεια εργασίας σας και ονομάζεται @code{hello.py}, και η γραμμή εντολών σας ανοίγει όμορφα στον αρχικό σας κατάλογο, ώστε να βλέπετε κάτι παρόμοιο με:

@example
C:\Users\YourName>
@end example

Λοιπόν τώρα θα ζητήσετε από την εντολή @code{py} να δώσει το σενάριο σας στην Python πληκτρολογώντας @code{py} ακολουθούμενη από τη διαδρομή του σεναρίου σας:

@example
C:\Users\YourName> py Desktop\hello.py
hello
@end example

@node Πως κάνω τα Python scripts εκτελέσιμα;,Γιατί μερικές φορές η Python αργεί τόσο πολύ να ξεκινήσει;,Πως μπορώ να εκτελέσω ένα πρόγραμμα Python στα Windows;,Python στα Windows FAQ
@anchor{faq/windows how-do-i-make-python-scripts-executable}@anchor{5d19}
@subsection Πως κάνω τα Python scripts εκτελέσιμα;


Στα Windows, το τυπικό πρόγραμμα εγκατάστασης Python ήδη συσχετίζει την επέκταση .py με έναν τύπο αρχείου μια ανοιχτή εντολή που εκτελεί τον διερμηνέα (@code{D:\Program Files\Python\python.exe "%1" %*}).  Αυτό είναι αρκετό για να κάνετε τα scripts εκτελέσιμα από τη γραμμή εντολών ως “foo.py”.  Εάν προτιμάτε να μπορείτε να εκτελέσετε το σενάριο πληκτρολογώντας απλά “foo” χωρίς επέκταση, πρέπει να προσθέσετε .py στη μεταβλητή περιβάλλοντος PATHTEXT.

@node Γιατί μερικές φορές η Python αργεί τόσο πολύ να ξεκινήσει;,Πώς μπορώ να δημιουργήσω ένα εκτελέσιμο από ένα σενάριο Python;,Πως κάνω τα Python scripts εκτελέσιμα;,Python στα Windows FAQ
@anchor{faq/windows why-does-python-sometimes-take-so-long-to-start}@anchor{5d1a}
@subsection Γιατί μερικές φορές η Python αργεί τόσο πολύ να ξεκινήσει;


Συνήθως η Python ξεκινά πολύ γρήγορα στα Windows, αλλά περιστασιακά υπάρχουν αναφορές σφαλμάτων ότι η Python αρχίζει ξαφνικά να παίρνει πολύ χρόνο για να ξεκινήσει.  Αυτό γίνεται ακόμα πιο αινιγματικό, επειδή η Python θα λειτουργεί καλά σε άλλα συστήματα Windows που φαίνεται να έχουν διαμορφωθεί με τον ίδιο τρόπο.

Το πρόβλημα μπορεί να οφείλεται σε εσφαλμένη διαμόρφωση του λογισμικού ελέγχου ιών στο προβληματικό μηχάνημα.  Ορισμένοι σαρωτές ιών είναι γνωστό ότι εισάγουν επιβάρυνση εκκίνησης δύο τάξεων μεγέθους όταν ο σαρωτής έχει ρυθμιστεί να παρακολουθεί όλες τις αναγνώσεις από το σύστημα αρχείων.  Δοκιμάστε να ελέγξετε τη διαμόρφωση του λογισμικού ιών στα συστήματά σας για να βεβαιωθείτε ότι έχουν όντως διαμορφωθεί πανομοιότυπα.  Το McAfee, όταν έχει ρυθμιστεί να σαρώνει όλη τη δραστηριότητα ανάγνωσης του συστήματος αρχείων , είναι ένας συγκεκριμένος φταίχτης.

@node Πώς μπορώ να δημιουργήσω ένα εκτελέσιμο από ένα σενάριο Python;,Είναι ένα αρχείο * pyd ίδιο με ένα αρχείο DLL;,Γιατί μερικές φορές η Python αργεί τόσο πολύ να ξεκινήσει;,Python στα Windows FAQ
@anchor{faq/windows how-do-i-make-an-executable-from-a-python-script}@anchor{5d1b}
@subsection Πώς μπορώ να δημιουργήσω ένα εκτελέσιμο από ένα σενάριο Python;


Βλ. @ref{5c6f,,Πως μπορώ να δημιουργήσω ένα stand-alone binary από ένα Python script;} για μια λίστα εργαλείων που μπορούν να χρησιμοποιηθούν για τη δημιουργία εκτελέσιμων αρχείων.

@node Είναι ένα αρχείο * pyd ίδιο με ένα αρχείο DLL;,Πώς μπορώ να ενσωματώσω την Python σε μια εφαρμογή Windows;,Πώς μπορώ να δημιουργήσω ένα εκτελέσιμο από ένα σενάριο Python;,Python στα Windows FAQ
@anchor{faq/windows is-a-pyd-file-the-same-as-a-dll}@anchor{5d1c}
@subsection Είναι ένα αρχείο @code{*.pyd} ίδιο με ένα αρχείο DLL;


Ναι, τα αρχεία .pyd είναι dll, αλλά υπάρχουν μερικές διαφορές.  Εάν έχετε ένα DLL με το όνομα @code{foo.pyd}, τότε πρέπει να έχει μια συνάρτηση @code{PyInit_foo()}.  Στη συνέχεια μπορείτε να γράψετε Python «import foo», και η Python θα αναζητήσει το foo.pyd (καθώς και το foo.py, foo.pyc) και να το βρει, θα προσπαθήσει να καλέσει το @code{PyInit_foo()} για να το αρχικοποιήσει.  Δεν συνδέετε το .exe σας με το foo.lib, καθώς αυτό θα έκανα τα Windows να απαιτήσουν την παρουσία DLL.

Λάβετε υπόψη ότι η διαδρομή αναζήτησης για το foo.pyd είναι το PYTHONPATH, δεν είναι ίδια με τη διαδρομή που χρησιμοποιούν τα Windows για την αναζήτηση του foo.dll.  Επίσης, το foo.pyd δεν χρειάζεται να υπάρχει για την εκτέλεση του προγράμματος σας, ενώ εάν συνδέσετε το πρόγραμμά σας με ένα dll, απαιτείται το dll.  Φυσικά, απαιτείται το foo.pyd εάν θέλετε να πείτε @code{import foo}.  Σε ένα DLL, η σύνδεση δηλώνεται στον πηγαίο κώδικα με το @code{__declspec(dllexport)}. Σε ένα .pyd, η σύνδεση ορίζεται σε μια λίστα διαθέσιμων συναρτήσεων.

@node Πώς μπορώ να ενσωματώσω την Python σε μια εφαρμογή Windows;,Πως μπορώ να εμποδίσω τους editors να εισάγουν tabs στον πηγαίο της Python μου;,Είναι ένα αρχείο * pyd ίδιο με ένα αρχείο DLL;,Python στα Windows FAQ
@anchor{faq/windows how-can-i-embed-python-into-a-windows-application}@anchor{5d1d}
@subsection Πώς μπορώ να ενσωματώσω την Python σε μια εφαρμογή Windows;


Η ενσωμάτωση του Python interpreter σε μια Windows εφαρμογή μπορεί να συνοψιστεί ως εξής:


@enumerate 

@item 
Να `μην' δημιουργείτε απευθείας την Python στο αρχείο σας .exe.  Στα Windows, η Python πρέπει να είναι DLL για να χειρίζεται την εισαγωγή λειτουργικών μονάδων που είναι τα ίδια DLL.  (Αυτό είναι το πρώτο κλειδί που δεν τεκμηριώνεται.)  Αντίθετα, συνδέστε το @code{python`NN'.dll}” είναι συνήθως εγκατεστημένο στο @code{C:\Windows\System}.  `NN' είναι η έκδοση Python, ένας αριθμός όπως «33» για Python 3.3.

Μπορείτε να συνδεθείτε με την Python με δύο διαφορετικούς τρόπους.  Σύνδεση χρόνου φόρτωσης σημαίνει σύνδεση ενάντια στο @code{python`NN'.lib}, ενώ η σύνδεση χρόνου εκτέλεσης σημαίνει σύνδεση ενάντια στο @code{python`NN'.dll}.  (Γενική σημείωση: @code{python`NN'.lib} είναι το λεγόμενο «import lib» που αντιστοιχεί στο @code{python`NN'.dll}.  Απλώς ορίζει σύμβολα για το σύνδεσμο.)

Η σύνδεση χρόνου εκτέλεσης απλοποιεί σημαντικά τις επιλογές συνδέσμων.  Όλα συμβαίνουν κατά την εκτέλεση.  Ο κώδικα σας πρέπει να φορτώσει @code{python`NN'.dll} χρησιμοποιώντας την ρουτίνα @code{LoadLibraryEx()} των Windows.  Ο κώδικας πρέπει επίσης να χρησιμοποιεί ρουτίνες πρόσβασης και δεδομένα στο @code{python`NN'.dll} (δηλαδή, το C API της Python) χρησιμοποιώντας δείκτες που λαμβάνονται από τη ρουτίνα των Windows @code{GetProcAddress()}.  Οι μακροεντολές μπορούν να κάνουν χρησιμοποιώντας αυτούς τους δείκτες διαφανείς σε οποιονδήποτε κώδικα C που καλεί ρουτίνες στο C API της Python.

@c XXX what about static linking?

@item 
Εάν χρησιμοποιείτε SWIG, είναι εύκολο να δημιουργήσετε ένα Python «extension module» που θα κάνει τα δεδομένα και τις μεθόδους της εφαρμογής διαθέσιμα στην Python.  Το SWIG θα χειριστεί σχεδόν όλες τις grungy λεπτομέρειες για εσάς.  Το αποτέλεσμα είναι ο κώδικας C που συνδέεστε `στο' αρχείο σας .exe (!)  `Δεν' χρειάζεται να δημιουργήσετε ένα αρχείο DLL και αυτό απλοποιεί επίσης τη σύνδεση.

@item 
Το SWIG θα δημιουργήσει μια συνάρτηση init (μια συνάρτηση C) της οποία το όνομα εξαρτάται από το όνομα της μονάδας επέκτασης.  Για παράδειγμα, εάν το όνομά του module είναι leo, η συνάρτησης init θα ονομάζεται initleo().  Εάν χρησιμοποιείτε τη σκιά SWIG κλάσεις, όπως θα έπρεπε, η συνάρτηση init θα ονομάζεται initleoc().  Αυτό εκκινεί μια κυρίως κρυφή βοηθητική κλάση που χρησιμοποιείται από την κλάση σκιά.

Ο λόγος για τον οποίο μπορείτε να συνδέσετε τον κώδικα C στο βήμα 2 στο αρχείο σας .exe είναι ότι η κλήση της συνάρτησης αρχικοποίησης ισοδυναμεί με την εισαγωγή του module στην Python! (Αυτό είναι το δεύτερο κλειδί που δεν τεκμηριώνεται.)

@item 
Με λίγα λόγια, μπορείτε να χρησιμοποιήσετε τον ακόλουθο κώδικα για να αρχικοποιήσετε τον Python interpreter με το module επέκτασης.

@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 
Υπάρχουν δύο προβλήματα με το C API της Python, τα οποία θα γίνουν εμφανή εάν χρησιμοποιήσετε έναν compiler διαφορετικό από τον MSVC, τον compiler που χρησιμοποιήθηκε για τη δημιουργία του pythonNN.dll.

Πρόβλημα 1: Οι λεγόμενες συναρτήσεις «Πολύ Υψηλού Επιπέδου» που λαμβάνουν ορίσματα @code{FILE *} δεν θα λειτουργούν σε multi-compiler περιβάλλον, επειδή η έννοια κάθε μεταγλωττιστή για ένα @code{struct FILE} θα είναι διαφορετική.  Από την άποψη της εφαρμογής, πρόκειται για λειτουργίες πολύ χαμηλού επιπέδου.

Πρόβλημα 2: Το SWIG δημιουργεί τον ακόλουθο κώδικα όταν δημιουργεί wrappers σε void συναρτήσεις:

@example
Py_INCREF(Py_None);
_resultobj = Py_None;
return _resultobj;
@end example

Δυστυχώς, το Py_None είναι μια μακροεντολή που επεκτείνεται σε μια αναφορά σε μια σύνθετη δομή δεδομένων που ονομάζεται _Py_NoneStruct μέσα στο pythonNN.dll.  Και πάλι, αυτός ο κώδικας θα αποτύχει σε ένα mult-compiler περιβάλλον.  Αντικαταστήστε αυτόν τον κώδικα με:

@example
return Py_BuildValue("");
@end example

Μπορεί να είναι δυνατή η χρήση της εντολής @code{%typemap} της SWIG για να γίνει αυτόματα η αλλαγή, αν και δεν κατάφερα να το κάνω αυτό να λειτουργήσει (είμαι εντελώς αρχάριος της SWIG).

@item 
Η χρήση ενός Python shell script για να δημιουργήσετε ένα Python interpreter παράθυρο μέσα από την εφαρμογή σας Windows δεν είναι καλή ιδέα” το παράθυρο που θα προκύψει θα είναι ανεξάρτητο από το σύστημα παραθύρου της εφαρμογής σας.  Αντίθετα, εσείς (ή η κλάση wxPythonWindow) θα πρέπει να δημιουργήσετε ένα «εγγενές» (native) interpreter παράθυρο.  Είναι εύκολο να συνδέσετε αυτό το παράθυρο με τον Python interpreter.  Μπορείτε να ανακατευθύνετε το i/o της Python στο _any_ αντικείμενο που υποστηρίζει ανάγνωση και εγγραφή, επομένως το μόνο που χρειάζεστε είναι ένα αντικείμενο Python (που ορίζεται στο module επέκτασης) που περιέχει τις μεθόδους read() και write().
@end enumerate

@node Πως μπορώ να εμποδίσω τους editors να εισάγουν tabs στον πηγαίο της Python μου;,Πώς μπορώ να ελέγξω για ένα πάτημα πλήκτρων χωρίς αποκλεισμό;,Πώς μπορώ να ενσωματώσω την Python σε μια εφαρμογή Windows;,Python στα Windows FAQ
@anchor{faq/windows how-do-i-keep-editors-from-inserting-tabs-into-my-python-source}@anchor{5d1e}
@subsection Πως μπορώ να εμποδίσω τους editors να εισάγουν tabs στον πηγαίο της Python μου;


Το FAQ δεν συνιστούν την χρήση καρτελών και ο οδηγός στυλ Python, 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/}, συνιστά 4 κενά για τον κατανεμημένο κώδικα Python” αυτή είναι επίσης η προεπιλεγμένη λειτουργία python του Emacs.

Σε οποιονδήποτε editor, η μίξη tabs και spaces είναι κακή ιδέα.  Το MSVC δεν διαφέρει από αυτή την άποψη και ρυθμίζεται εύκολα για να χρησιμοποιεί κενά:  Πάρτε Tools ‣ Options ‣ Tabs, και για τον τύπο αρχείου «Default» ορίστε το «Tab size» και το «Indent size» στο 4, και επιλέξτε το κουμπί επιλογής «Insert spaces».

Η Python εγείρει το @ref{b89,,IndentationError} ή @ref{950,,TabError} εάν τα μικτά tabs και spaces προκαλούν προβλήματα στο leading whitespace. Μπορείτε επίσης να εκτελέσετε το module @ref{e6,,tabnanny} για να ελέγξετε εάν δέντρο καταλόγου σε λειτουργία batch.

@node Πώς μπορώ να ελέγξω για ένα πάτημα πλήκτρων χωρίς αποκλεισμό;,Πως μπορώ να διορθώσω το σφάλμα που λείπει το api-ms-win-crt-runtime-l1-1-0 dll;,Πως μπορώ να εμποδίσω τους editors να εισάγουν tabs στον πηγαίο της Python μου;,Python στα Windows FAQ
@anchor{faq/windows how-do-i-check-for-a-keypress-without-blocking}@anchor{5d1f}
@subsection Πώς μπορώ να ελέγξω για ένα πάτημα πλήκτρων χωρίς αποκλεισμό;


Χρησιμοποιείστε το module @ref{97,,msvcrt}.  Αυτή είναι ένα τυπικό module επέκτασης ειδικά για τα Windows.  Ορίζει μια συνάρτηση @code{kbhit()} η οποία ελέγχει εάν υπάρχει ένα χτύπημα πληκτρολογίου, και το @code{getch()} παίρνει έναν χαρακτήρα χωρίς να τον επαναλαμβάνει.

@node Πως μπορώ να διορθώσω το σφάλμα που λείπει το api-ms-win-crt-runtime-l1-1-0 dll;,,Πώς μπορώ να ελέγξω για ένα πάτημα πλήκτρων χωρίς αποκλεισμό;,Python στα Windows FAQ
@anchor{faq/windows how-do-i-solve-the-missing-api-ms-win-crt-runtime-l1-1-0-dll-error}@anchor{5d20}
@subsection Πως μπορώ να διορθώσω το σφάλμα που λείπει το api-ms-win-crt-runtime-l1-1-0.dll;


Αυτό μπορεί να συμβεί σε Python 3.5 και νεότερες εκδόσεις όταν χρησιμοποιείτε Windows 8.1 ή νεότερη έκδοση χωρίς να έχουν εγκατασταθεί όλες οι ενημερώσεις.  Πρώτα βεβαιωθείτε ότι το λειτουργικό σας σύστημα υποστηρίζεται και είναι ενημερωμένο και εάν αυτό δεν επιλύσει το πρόβλημα, επισκεφθείτε τη σελίδα υποστήριξης της Microsoft@footnote{https://support.microsoft.com/en-us/help/3118401/} για καθοδήγηση σχετικά με τη μη αυτόματη εγκατάσταση της ενημέρωσης C Runtime.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Graphic User Interface FAQ,«Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;» FAQ,Python στα Windows FAQ,Συχνές Ερωτήσεις για την Python
@anchor{faq/gui doc}@anchor{5d21}@anchor{faq/gui graphic-user-interface-faq}@anchor{5d22}@anchor{faq/gui translation-repo}@anchor{5d23}
@section Graphic User Interface FAQ



@c XXX need review for Python 3.

@menu
* General GUI Questions:: 
* What GUI toolkits exist for Python?:: 
* Tkinter questions:: 

@end menu

@node General GUI Questions,What GUI toolkits exist for Python?,,Graphic User Interface FAQ
@anchor{faq/gui general-gui-questions}@anchor{5d24}
@subsection General GUI Questions


@node What GUI toolkits exist for Python?,Tkinter questions,General GUI Questions,Graphic User Interface FAQ
@anchor{faq/gui what-gui-toolkits-exist-for-python}@anchor{5d25}
@subsection What GUI toolkits exist for Python?


Standard builds of Python include an object-oriented interface to the Tcl/Tk
widget set, called @ref{452f,,tkinter}.  This is probably the easiest to
install (since it comes included with most
binary distributions@footnote{https://www.python.org/downloads/} of Python) and use.
For more info about Tk, including pointers to the source, see the
Tcl/Tk home page@footnote{https://www.tcl.tk}.  Tcl/Tk is fully portable to the
macOS, Windows, and Unix platforms.

Depending on what platform(s) you are aiming at, there are also several
alternatives. A list of cross-platform@footnote{https://wiki.python.org/moin/GuiProgramming#Cross-Platform_Frameworks} and
platform-specific@footnote{https://wiki.python.org/moin/GuiProgramming#Platform-specific_Frameworks} GUI
frameworks can be found on the python wiki.

@node Tkinter questions,,What GUI toolkits exist for Python?,Graphic User Interface FAQ
@anchor{faq/gui tkinter-questions}@anchor{5d26}
@subsection Tkinter questions


@menu
* How do I freeze Tkinter applications?:: 
* Can I have Tk events handled while waiting for I/O?:: 
* I can’t get key bindings to work in Tkinter; why?: I can’t get key bindings to work in Tkinter why?. 

@end menu

@node How do I freeze Tkinter applications?,Can I have Tk events handled while waiting for I/O?,,Tkinter questions
@anchor{faq/gui how-do-i-freeze-tkinter-applications}@anchor{5d27}
@subsubsection How do I freeze Tkinter applications?


Freeze is a tool to create stand-alone applications.  When freezing Tkinter
applications, the applications will not be truly stand-alone, as the application
will still need the Tcl and Tk libraries.

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 Can I have Tk events handled while waiting for I/O?,I can’t get key bindings to work in Tkinter why?,How do I freeze Tkinter applications?,Tkinter questions
@anchor{faq/gui can-i-have-tk-events-handled-while-waiting-for-i-o}@anchor{5d28}
@subsubsection Can I have Tk events handled while waiting for I/O?


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{454c,,File Handlers}.

@node I can’t get key bindings to work in Tkinter why?,,Can I have Tk events handled while waiting for I/O?,Tkinter questions
@anchor{faq/gui i-can-t-get-key-bindings-to-work-in-tkinter-why}@anchor{5d29}
@subsubsection I can’t get key bindings to work in Tkinter: why?


An often-heard complaint is that event handlers @ref{4547,,bound}
to events with the @code{bind()} method
don’t get handled even when the appropriate key is pressed.

The most common cause is that the widget to which the binding applies doesn’t
have «keyboard focus».  Check out the Tk documentation for the focus command.
Usually a widget is given the keyboard focus by clicking in it (but not for
labels; see the takefocus option).

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node «Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;» FAQ,,Graphic User Interface FAQ,Συχνές Ερωτήσεις για την Python
@anchor{faq/installed doc}@anchor{5d2a}@anchor{faq/installed translation-repo}@anchor{5d2b}@anchor{faq/installed why-is-python-installed-on-my-computer-faq}@anchor{5d2c}
@section «Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;» FAQ


@menu
* Τι είναι η Python;:: 
* Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;:: 
* Μπορώ να διαγράψω την Python;:: 

@end menu

@node Τι είναι η Python;,Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;,,«Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;» FAQ
@anchor{faq/installed what-is-python}@anchor{5d2d}
@subsection Τι είναι η Python;


Η Python είναι μια γλώσσα προγραμματισμού.  Χρησιμοποιείται για πολλές διαφορετικές εφαρμογές. Χρησιμοποιείται σε ορισμένα λύκεια και κολέγια ως εισαγωγική γλώσσα προγραμματισμού επειδή η Python είναι εύκολη στην εκμάθηση, αλλά χρησιμοποιείται επίσης από επαγγελματίες προγραμματιστές λογισμικού σε μέρη όπως στην Google, στην NASA και στην Lucasfilm Ltd.

Αν θέλετε να μάθετε περισσότερα για την Python, ξεκινήστε με τον Οδηγό για αρχάριους στην Python@footnote{https://wiki.python.org/moin/BeginnersGuide}.

@node Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;,Μπορώ να διαγράψω την Python;,Τι είναι η Python;,«Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;» FAQ
@anchor{faq/installed why-is-python-installed-on-my-machine}@anchor{5d2e}
@subsection Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;


Αν βρείτε την Python εγκατεστημένη στο σύστημά σας, αλλά δεν θυμάστε να την έχετε εγκαταστήσει υπάρχουν διάφοροι πιθανοί τρόποι με τους οποίους θα μπορούσε να έχει φτάσει εκεί.


@itemize *

@item 
Ίσως κάποιος άλλος χρήστης του υπολογιστή ήθελε να μάθει προγραμματισμό και το εγκατέστησε. Θα πρέπει να βρείτε ποιος χρησιμοποιούσε τον υπολογιστή και μπορεί να το εγκατέστησε.

@item 
Μια εφαρμογή τρίτου μέρους που έχει εγκατασταθεί στον υπολογιστή μπορεί να έχει γραφτεί σε Python και να περιελάμβανε μια εγκατάσταση της Python.  Υπάρχουν πολλές τέτοιες εφαρμογές, από προγράμματα GUI μέχρι διακομιστές δικτύου και διαχειριστικά scripts.

@item 
Ορισμένες συσκευές με Windows έχουν επίσης εγκατεστημένη την Python.  Αυτή τη στιγμή γνωρίζουμε υπολογιστές της Hewlett-Packard και της Compaq που περιλαμβάνουν την Python.  Προφανώς ορισμένα από τα εργαλεία διαχείρισης της HP/Compaq είναι γραμμένα σε Python.

@item 
Πολλά λειτουργικά συστήματα συμβατά με Unix, όπως το macOS και ορισμένες διανομές Linux, έχουν από προεπιλογή εγκατεστημένη την Python, η οποία περιλαμβάνεται στη βασική εγκατάσταση.
@end itemize

@node Μπορώ να διαγράψω την Python;,,Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;,«Γιατί είναι εγκατεστημένη η Python στον υπολογιστή μου;» FAQ
@anchor{faq/installed can-i-delete-python}@anchor{5d2f}
@subsection Μπορώ να διαγράψω την Python;


Αυτό εξαρτάται από το πού προήλθε η Python.

Αν κάποιος το εγκατέστησε σκόπιμα, μπορείτε να το αφαιρέσετε χωρίς να βλάψετε τίποτα.  Στα Windows, χρησιμοποιήστε το εικονίδιο Προσθήκη/Αφαίρεση προγραμμάτων στον Πίνακα Ελέγχου.

Αν η Python εγκαταστάθηκε από μια εφαρμογή τρίτου μέρους, μπορείτε επίσης να την αφαιρέσετε, αλλά η εφαρμογή αυτή δεν θα λειτουργεί πλέον.  Θα πρέπει να χρησιμοποιήσετε το πρόγραμμα  απεγκατάστασης αυτής της εφαρμογής αντί να αφαιρέσετε απευθείας την Python.

Εάν η Python περιλαμβάνεται στο λειτουργικό σας σύστημα, δεν συνιστάται η αφαίρεσή της.  Αν την αφαιρέσετε, όποια εργαλεία ήταν γραμμένα σε Python δεν θα λειτουργούν πλέον, και κάποια από αυτά μπορεί να είναι σημαντικά για εσάς.  Στη συνέχεια, θα απαιτηθεί επανεγκατάσταση ολόκληρου του συστήματος για να διορθώσετε ξανά τα πράγματα.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Deprecations,Γλωσσάρι,Συχνές Ερωτήσεις για την Python,Top
@anchor{deprecations/index doc}@anchor{5d30}@anchor{deprecations/index deprecations}@anchor{5d31}@anchor{deprecations/index translation-repo}@anchor{5d32}
@chapter Deprecations


@menu
* Pending removal in Python 3.15: Pending removal in Python 3 15<7>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<8>. 
* Pending removal in Python 3.17: Pending removal in Python 3 17<5>. 
* Pending removal in Python 3.18: Pending removal in Python 3 18<6>. 
* Pending removal in Python 3.19: Pending removal in Python 3 19<5>. 
* Pending removal in Python 3.20: Pending removal in Python 3 20<5>. 
* Pending removal in future versions: Pending removal in future versions<8>. 
* Soft deprecations: Soft deprecations<2>. 
* C API deprecations:: 

@end menu

@node Pending removal in Python 3 15<7>,Pending removal in Python 3 16<8>,,Deprecations
@anchor{deprecations/index pending-removal-in-python-3-15}@anchor{5d33}
@section Pending removal in Python 3.15



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @code{__cached__} on a module while
failing to set @ref{58b,,__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{58c,,__package__} on a module while
failing to set @ref{58d,,__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{2d,,ctypes}:


@itemize *

@item 
The undocumented @code{ctypes.SetPointerType()} function
has been deprecated since Python 3.13.
@end itemize

@item 
@ref{75,,http.server}:


@itemize *

@item 
The obsolete and rarely used @code{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{7a,,importlib}:


@itemize *

@item 
@code{load_module()} method: use @code{exec_module()} instead.
@end itemize

@item 
@ref{a8,,pathlib}:


@itemize *

@item 
@code{.PurePath.is_reserved()}
has been deprecated since Python 3.13.
Use @ref{2d9,,os.path.isreserved()} to detect reserved paths on Windows.
@end itemize

@item 
@ref{af,,platform}:


@itemize *

@item 
@code{platform.java_ver()} has been deprecated since Python 3.13.
This function is only useful for Jython support, has a confusing API,
and is largely untested.
@end itemize

@item 
@ref{e4,,sysconfig}:


@itemize *

@item 
The `check_home' argument of @ref{2dd,,sysconfig.is_python_build()} has been
deprecated since Python 3.12.
@end itemize

@item 
@ref{f6,,threading}:


@itemize *

@item 
@ref{2df,,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{10c,,types}:


@itemize *

@item 
@ref{2e1,,types.CodeType}: Accessing @code{codeobject.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{2c9,,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{10d,,typing}:


@itemize *

@item 
The undocumented keyword argument syntax for creating
@ref{2e4,,NamedTuple} classes
(for example, @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 
When using the functional syntax of @ref{290,,TypedDict}s, failing
to pass a value to the `fields' parameter (@code{TD = TypedDict("TD")}) or
passing @code{None} (@code{TD = TypedDict("TD", None)}) has been deprecated
since Python 3.13.
Use @code{class TD(TypedDict): pass} or @code{TD = TypedDict("TD", @{@})}
to create a TypedDict with zero field.

@item 
The @code{typing.no_type_check_decorator()} decorator function
has been deprecated since Python 3.13.
After eight years in the @ref{10d,,typing} module,
it has yet to be supported by any major type checker.
@end itemize

@item 
@code{sre_compile}, @code{sre_constants} and @code{sre_parse} modules.

@item 
@ref{11c,,wave}:


@itemize *

@item 
The @code{getmark()}, @code{setmark()} and @code{getmarkers()} methods of
the @ref{2e6,,Wave_read} and @ref{2e7,,Wave_write} classes
have been deprecated since Python 3.13.
@end itemize

@item 
@ref{13b,,zipimport}:


@itemize *

@item 
@code{zipimport.zipimporter.load_module()} has been deprecated since
Python 3.10. Use @ref{2e9,,exec_module()} instead.
(gh-125746@footnote{https://github.com/python/cpython/issues/125746}.)
@end itemize
@end itemize

@node Pending removal in Python 3 16<8>,Pending removal in Python 3 17<5>,Pending removal in Python 3 15<7>,Deprecations
@anchor{deprecations/index pending-removal-in-python-3-16}@anchor{5d34}
@section Pending removal in Python 3.16



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @ref{2ff,,__loader__} on a module while
failing to set @ref{300,,__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{8,,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{301,,Py_UCS4})
for Unicode characters instead.
@end itemize

@item 
@ref{b,,asyncio}:


@itemize *

@item 
@code{asyncio.iscoroutinefunction()} is deprecated
and will be removed in Python 3.16;
use @ref{302,,inspect.iscoroutinefunction()} instead.
(Contributed by Jiahao Li and Kumar Aditya in gh-122875@footnote{https://github.com/python/cpython/issues/122875}.)

@item 
@ref{b,,asyncio} policy system is deprecated and will be removed in Python 3.16.
In particular, the following classes and functions are deprecated:


@itemize *

@item 
@ref{303,,asyncio.AbstractEventLoopPolicy}

@item 
@ref{304,,asyncio.DefaultEventLoopPolicy}

@item 
@ref{305,,asyncio.WindowsSelectorEventLoopPolicy}

@item 
@ref{306,,asyncio.WindowsProactorEventLoopPolicy}

@item 
@ref{307,,asyncio.get_event_loop_policy()}

@item 
@ref{308,,asyncio.set_event_loop_policy()}
@end itemize

Users should use @ref{309,,asyncio.run()} or @ref{30a,,asyncio.Runner} with
`loop_factory' to use the desired event loop implementation.

For example, to use @ref{30b,,asyncio.SelectorEventLoop} on Windows:

@example
import asyncio

async def main():
    ...

asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
@end example

(Contributed by Kumar Aditya in gh-127949@footnote{https://github.com/python/cpython/issues/127949}.)
@end itemize

@item 
@ref{13,,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{62,,functools}:


@itemize *

@item 
Calling the Python implementation of @ref{153,,functools.reduce()} with `function'
or `sequence' as keyword arguments has been deprecated since Python 3.14.
@end itemize

@item 
@ref{8a,,logging}:


@itemize *

@item 
Support for custom logging handlers with the `strm' argument is deprecated
and scheduled for removal in Python 3.16. Define handlers with the `stream'
argument instead. (Contributed by Mariusz Felisiak in gh-115032@footnote{https://github.com/python/cpython/issues/115032}.)
@end itemize

@item 
@ref{93,,mimetypes}:


@itemize *

@item 
Valid extensions start with a “.” or are empty for
@ref{30c,,mimetypes.MimeTypes.add_type()}.
Undotted extensions are deprecated and will
raise a @ref{277,,ValueError} in Python 3.16.
(Contributed by Hugo van Kemenade in gh-75223@footnote{https://github.com/python/cpython/issues/75223}.)
@end itemize

@item 
@ref{cd,,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{30d,,RuntimeError}.
@end itemize

@item 
@ref{e1,,symtable}:


@itemize *

@item 
The @code{symtable.Class.get_methods()} method
has been deprecated since Python 3.14.
@end itemize

@item 
@ref{e2,,sys}:


@itemize *

@item 
The @ref{30e,,_enablelegacywindowsfsencoding()} function
has been deprecated since Python 3.13.
Use the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex μεταβλητή περιβάλλοντος; PYTHONLEGACYWINDOWSFSENCODING
@ref{30f,,PYTHONLEGACYWINDOWSFSENCODING} environment variable instead.
@end itemize

@item 
@ref{e4,,sysconfig}:


@itemize *

@item 
The @code{sysconfig.expand_makefile_vars()} function
has been deprecated since Python 3.14.
Use the @code{vars} argument of @ref{156,,sysconfig.get_paths()} instead.
@end itemize

@item 
@ref{e7,,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 Python 3 17<5>,Pending removal in Python 3 18<6>,Pending removal in Python 3 16<8>,Deprecations
@anchor{deprecations/index pending-removal-in-python-3-17}@anchor{5d35}
@section Pending removal in Python 3.17



@itemize *

@item 
@ref{33,,datetime}:


@itemize *

@item 
@ref{2d2,,strptime()} calls using a format string containing
@code{%e} (day of month) without a year.
This has been deprecated since Python 3.15.
(Contributed by Stan Ulbrych in gh-70647@footnote{https://github.com/python/cpython/issues/70647}.)
@end itemize

@item 
@ref{1f,,collections.abc}:


@itemize -

@item 
@ref{2cb,,collections.abc.ByteString} is scheduled for removal in Python 3.17.

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj}
implements the @ref{311,,buffer protocol} at runtime. For use
in type annotations, either use @ref{312,,Buffer} or a union
that explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} was originally intended to be an abstract class that
would serve as a supertype of both @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
However, since the ABC never had any methods, knowing that an object was an
instance of @code{ByteString} never actually told you anything useful
about the object. Other common buffer types such as @ref{1d2,,memoryview}
were also never understood as subtypes of @code{ByteString} (either at
runtime or by static type checkers).

See 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} for more details.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)
@end itemize

@item 
@ref{54,,encodings}:


@itemize -

@item 
Passing non-ascii `encoding' names to @ref{313,,encodings.normalize_encoding()}
is deprecated and scheduled for removal in Python 3.17.
(Contributed by Stan Ulbrych in gh-136702@footnote{https://github.com/python/cpython/issues/136702}.)
@end itemize

@item 
@ref{11e,,webbrowser}:


@itemize -

@item 
@code{webbrowser.MacOSXOSAScript} is deprecated in favour of
@code{webbrowser.MacOS}. (gh-137586@footnote{https://github.com/python/cpython/issues/137586})
@end itemize

@item 
@ref{10d,,typing}:


@itemize -

@item 
Before Python 3.14, old-style unions were implemented using the private class
@code{typing._UnionGenericAlias}. This class is no longer needed for the implementation,
but it has been retained for backward compatibility, with removal scheduled for Python
3.17. Users should use documented introspection helpers like @ref{314,,typing.get_origin()}
and @ref{315,,typing.get_args()} instead of relying on private implementation details.

@item 
@ref{2e3,,typing.ByteString}, deprecated since Python 3.9, is scheduled for removal in
Python 3.17.

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj}
implements the @ref{311,,buffer protocol} at runtime. For use
in type annotations, either use @ref{312,,Buffer} or a union
that explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} was originally intended to be an abstract class that
would serve as a supertype of both @ref{1c7,,bytes} and @ref{1c6,,bytearray}.
However, since the ABC never had any methods, knowing that an object was an
instance of @code{ByteString} never actually told you anything useful
about the object. Other common buffer types such as @ref{1d2,,memoryview}
were also never understood as subtypes of @code{ByteString} (either at
runtime or by static type checkers).

See 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options} for more details.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)
@end itemize
@end itemize

@node Pending removal in Python 3 18<6>,Pending removal in Python 3 19<5>,Pending removal in Python 3 17<5>,Deprecations
@anchor{deprecations/index pending-removal-in-python-3-18}@anchor{5d36}
@section Pending removal in Python 3.18



@itemize *

@item 
No longer accept a boolean value when a file descriptor is expected.
(Contributed by Serhiy Storchaka in gh-82626@footnote{https://github.com/python/cpython/issues/82626}.)

@item 
@ref{39,,decimal}:


@itemize *

@item 
The non-standard and undocumented @ref{1c2,,Decimal} format
specifier @code{'N'}, which is only supported in the @code{decimal} module’s
C implementation, has been deprecated since Python 3.13.
(Contributed by Serhiy Storchaka in gh-89902@footnote{https://github.com/python/cpython/issues/89902}.)
@end itemize

@item 
Deprecations defined by 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/}:


@itemize *

@item 
@code{import} lines in @code{`name'.pth} files are silently ignored.
@end itemize

(Contributed by Barry Warsaw in gh-148641@footnote{https://github.com/python/cpython/issues/148641}.)
@end itemize

@node Pending removal in Python 3 19<5>,Pending removal in Python 3 20<5>,Pending removal in Python 3 18<6>,Deprecations
@anchor{deprecations/index pending-removal-in-python-3-19}@anchor{5d37}
@section Pending removal in Python 3.19



@itemize *

@item 
@ref{2d,,ctypes}:


@itemize *

@item 
Implicitly switching to the MSVC-compatible struct layout by setting
@ref{318,,_pack_} but not @ref{319,,_layout_}
on non-Windows platforms.
@end itemize

@item 
@ref{6b,,hashlib}:


@itemize -

@item 
In hash function constructors such as @ref{2f1,,new()} or the
direct hash-named constructors such as @ref{2f2,,md5()} and
@ref{2f3,,sha256()}, their optional initial data parameter could
also be passed a keyword argument named @code{data=} or @code{string=} in
various @code{hashlib} implementations.

Support for the @code{string} keyword argument name is now deprecated
and slated for removal in Python 3.19.

Before Python 3.13, the @code{string} keyword parameter was not correctly
supported depending on the backend implementation of hash functions.
Prefer passing the initial data as a positional argument for maximum
backwards compatibility.
@end itemize

@item 
@ref{74,,http.cookies}:


@itemize *

@item 
@ref{2f4,,http.cookies.Morsel.js_output()} is deprecated and will be
removed in Python 3.19.

@item 
@ref{2f5,,http.cookies.BaseCookie.js_output()} is deprecated and will be
removed in Python 3.19.
@end itemize

@item 
@ref{77,,imaplib}:


@itemize *

@item 
Altering @ref{2f8,,IMAP4.file} is now deprecated
and slated for removal in Python 3.19. This property is now unused
and changing its value does not automatically close the current file.

Before Python 3.14, this property was used to implement the corresponding
@code{read()} and @code{readline()} methods for @ref{31a,,IMAP4} but this
is no longer the case since then.
@end itemize
@end itemize

@node Pending removal in Python 3 20<5>,Pending removal in future versions<8>,Pending removal in Python 3 19<5>,Deprecations
@anchor{deprecations/index pending-removal-in-python-3-20}@anchor{5d38}
@section Pending removal in Python 3.20



@itemize *

@item 
Calling the @code{__new__()} method of @ref{2fb,,struct.Struct} without the
`format' argument is deprecated and will be removed in Python 3.20.  Calling
@ref{2fa,,__init__()} method on initialized @code{Struct}
objects is deprecated and will be removed in Python 3.20.

(Contributed by Sergey B Kirpichev and Serhiy Storchaka in gh-143715@footnote{https://github.com/python/cpython/issues/143715}.)

@item 
The @code{__version__}, @code{version} and @code{VERSION} attributes have been
deprecated in these standard library modules and will be removed in
Python 3.20. Use @ref{2fc,,sys.version_info} instead.


@itemize -

@item 
@ref{7,,argparse}

@item 
@ref{2c,,csv}

@item 
@ref{2d,,ctypes}

@item 
@code{ctypes.macholib}

@item 
@ref{39,,decimal} (use @ref{2fd,,decimal.SPEC_VERSION} instead)

@item 
@ref{75,,http.server}

@item 
@ref{77,,imaplib}

@item 
@ref{83,,ipaddress}

@item 
@ref{85,,json}

@item 
@ref{8a,,logging} (@code{__date__} also deprecated)

@item 
@ref{a4,,optparse}

@item 
@ref{ab,,pickle}

@item 
@ref{af,,platform}

@item 
@ref{c1,,re}

@item 
@ref{d5,,socketserver}

@item 
@ref{e6,,tabnanny}

@item 
@ref{e7,,tarfile}

@item 
@ref{fe,,tkinter.font}

@item 
@ref{102,,tkinter.ttk}

@item 
@ref{124,,wsgiref.simple_server}

@item 
@ref{12e,,xml.etree.ElementTree}

@item 
@code{xml.sax.expatreader}

@item 
@ref{133,,xml.sax.handler}

@item 
@ref{13c,,zlib}
@end itemize

(Contributed by Hugo van Kemenade and Stan Ulbrych in gh-76007@footnote{https://github.com/python/cpython/issues/76007}.)

@item 
Deprecations defined by 
@geindex Python Enhancement Proposals; PEP 829
PEP 829@footnote{https://peps.python.org/pep-0829/}:


@itemize *

@item 
Warnings are produced for @code{import} lines found in @code{`name'.pth}
files.

@item 
@code{`name'.pth} files are no longer decoded in the locale encoding by
default.  They `MUST' be encoded in @code{utf-8-sig}.
@end itemize

(Contributed by Barry Warsaw in gh-148641@footnote{https://github.com/python/cpython/issues/148641}.)

@item 
@ref{9,,ast}:


@itemize *

@item 
Creating instances of abstract AST nodes (such as @ref{2ec,,ast.AST}
or @code{ast.expr}) is deprecated and will raise an error in Python 3.20.
@end itemize
@end itemize

@node Pending removal in future versions<8>,Soft deprecations<2>,Pending removal in Python 3 20<5>,Deprecations
@anchor{deprecations/index pending-removal-in-future-versions}@anchor{5d39}
@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{7,,argparse}:


@itemize *

@item 
Nesting argument groups and nesting mutually exclusive
groups are deprecated.

@item 
Passing the undocumented keyword argument `prefix_chars' to
@ref{31d,,add_argument_group()} is now
deprecated.

@item 
The @ref{31e,,argparse.FileType} type converter is deprecated.
@end itemize

@item 
@ref{13,,builtins}:


@itemize *

@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{31f,,and}, @ref{320,,else}, @ref{321,,for}, @ref{322,,if},
@ref{323,,in}, @ref{324,,is} and @ref{325,,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{326,,int}.

@item 
Support for @code{__float__()} method returning a strict subclass of
@ref{327,,float}: these methods will be required to return an instance of
@code{float}.

@item 
Support for @code{__complex__()} method returning a strict subclass of
@ref{328,,complex}: these methods will be required to return an instance of
@code{complex}.

@item 
Passing a complex number as the `real' or `imag' argument in the
@ref{328,,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{15,,calendar}: @code{calendar.January} and @code{calendar.February} constants are
deprecated and replaced by @ref{329,,calendar.JANUARY} and
@ref{32a,,calendar.FEBRUARY}.
(Contributed by Prince Roshan in gh-103636@footnote{https://github.com/python/cpython/issues/103636}.)

@item 
@ref{1c,,codecs}: use @ref{32b,,open()} instead of @ref{32c,,codecs.open()}. (gh-133038@footnote{https://github.com/python/cpython/issues/133038})

@item 
@code{codeobject.co_lnotab}: use the @ref{32d,,codeobject.co_lines()} method
instead.

@item 
@ref{33,,datetime}:


@itemize *

@item 
@ref{32e,,utcnow()}:
use @code{datetime.datetime.now(tz=datetime.UTC)}.

@item 
@ref{32f,,utcfromtimestamp()}:
use @code{datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)}.
@end itemize

@item 
@ref{66,,gettext}: Plural value must be an integer.

@item 
@ref{7a,,importlib}:


@itemize *

@item 
@ref{330,,cache_from_source()} `debug_override' parameter is
deprecated: use the `optimization' parameter instead.
@end itemize

@item 
@ref{7d,,importlib.metadata}:


@itemize *

@item 
@code{EntryPoints} tuple interface.

@item 
Implicit @code{None} on return values.
@end itemize

@item 
@ref{8a,,logging}: the @code{warn()} method has been deprecated
since Python 3.3, use @ref{331,,warning()} instead.

@item 
@ref{8e,,mailbox}: Use of StringIO input and text mode is deprecated, use
BytesIO and binary mode instead.

@item 
@ref{a5,,os}: Calling @ref{332,,os.register_at_fork()} in a multi-threaded process.

@item 
@ref{a6,,os.path}: @ref{333,,os.path.commonprefix()} is deprecated, use
@ref{334,,os.path.commonpath()} for path prefixes. The @code{os.path.commonprefix()}
function is being deprecated due to having a misleading name and module.
The function is not safe to use for path prefixes despite being included in a
module about path manipulation, meaning it is easy to accidentally
introduce path traversal vulnerabilities into Python programs by using this
function.

@item 
@code{pydoc.ErrorDuringImport}: A tuple value for `exc_info' parameter is
deprecated, use an exception instance.

@item 
@ref{c1,,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 
@ref{cd,,shutil}: @ref{335,,rmtree()}”s `onerror' parameter is deprecated in
Python 3.12; use the `onexc' parameter instead.

@item 
@ref{d8,,ssl} options and protocols:


@itemize *

@item 
@ref{336,,ssl.SSLContext} without protocol argument is deprecated.

@item 
@ref{336,,ssl.SSLContext}: @ref{337,,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{f6,,threading} methods:


@itemize *

@item 
@code{threading.Condition.notifyAll()}: use @ref{338,,notify_all()}.

@item 
@code{threading.Event.isSet()}: use @ref{339,,is_set()}.

@item 
@code{threading.Thread.isDaemon()}, @ref{33a,,threading.Thread.setDaemon()}:
use @ref{33b,,threading.Thread.daemon} attribute.

@item 
@code{threading.Thread.getName()}, @ref{33c,,threading.Thread.setName()}:
use @ref{33d,,threading.Thread.name} attribute.

@item 
@code{threading.currentThread()}: use @ref{33e,,threading.current_thread()}.

@item 
@code{threading.activeCount()}: use @ref{33f,,threading.active_count()}.
@end itemize

@item 
@ref{340,,typing.Text} (gh-92332@footnote{https://github.com/python/cpython/issues/92332}).

@item 
The internal class @code{typing._UnionGenericAlias} is no longer used to implement
@ref{341,,typing.Union}. To preserve compatibility with users using this private
class, a compatibility shim will be provided until at least Python 3.17. (Contributed by
Jelle Zijlstra in gh-105499@footnote{https://github.com/python/cpython/issues/105499}.)

@item 
@ref{342,,unittest.IsolatedAsyncioTestCase}: it is deprecated to return a value
that is not @code{None} from a test case.

@item 
@ref{113,,urllib.parse} deprecated functions: @ref{2a4,,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{121,,wsgiref}: @code{SimpleHandler.stdout.write()} should not do partial
writes.

@item 
@ref{12e,,xml.etree.ElementTree}: Testing the truth value of an
@ref{343,,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{344,,sys._clear_type_cache()} is deprecated:
use @ref{345,,sys._clear_internal_caches()} instead.
@end itemize

@node Soft deprecations<2>,C API deprecations,Pending removal in future versions<8>,Deprecations
@anchor{deprecations/index soft-deprecations}@anchor{5d3a}
@section Soft deprecations


There are no plans to remove @ref{1a7,,soft deprecated} APIs.


@itemize *

@item 
@ref{24c,,re.match()} and @ref{24d,,re.Pattern.match()} are now
@ref{1a7,,soft deprecated} in favor of the new @ref{24a,,re.prefixmatch()} and
@ref{24b,,re.Pattern.prefixmatch()} APIs, which have been added as alternate,
more explicit names. These are intended to be used to alleviate confusion
around what `match' means by following the Zen of Python’s `«Explicit is
better than implicit»' mantra. Most other language regular expression
libraries use an API named `match' to mean what Python has always called
`search'.

We `do not' plan to remove the older @code{match()} name, as it has been
used in code for over 30 years. Code supporting older versions of Python
should continue to use @code{match()}, while new code should prefer
@code{prefixmatch()}. See @ref{2f9,,prefixmatch() vs. match()}.

(Contributed by Gregory P. Smith in gh-86519@footnote{https://github.com/python/cpython/issues/86519} and
Hugo van Kemenade in gh-148100@footnote{https://github.com/python/cpython/issues/148100}.)
@end itemize

@node C API deprecations,,Soft deprecations<2>,Deprecations
@anchor{deprecations/index c-api-deprecations}@anchor{5d3b}
@section C API deprecations


@menu
* Pending removal in Python 3.15: Pending removal in Python 3 15<8>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<9>. 
* Pending removal in Python 3.18: Pending removal in Python 3 18<7>. 
* Pending removal in Python 3.19: Pending removal in Python 3 19<6>. 
* Pending removal in Python 3.20: Pending removal in Python 3 20<6>. 
* Pending removal in future versions: Pending removal in future versions<9>. 

@end menu

@node Pending removal in Python 3 15<8>,Pending removal in Python 3 16<9>,,C API deprecations
@anchor{deprecations/index id1}@anchor{5d3c}
@subsection Pending removal in Python 3.15



@itemize *

@item 
The @code{PyImport_ImportModuleNoBlock()}:
Use @ref{3a3,,PyImport_ImportModule()} instead.

@item 
@code{PyWeakref_GetObject()} and @code{PyWeakref_GET_OBJECT()}:
Use @ref{3a4,,PyWeakref_GetRef()} instead. The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
@code{PyWeakref_GetRef()} on Python 3.12 and older.

@item 
@code{PyUnicode_AsDecodedObject()}:
Use @ref{3a1,,PyCodec_Decode()} instead.

@item 
@code{PyUnicode_AsDecodedUnicode()}:
Use @ref{3a1,,PyCodec_Decode()} instead; Note that some codecs (for example, «base64»)
may return a type other than @ref{1df,,str}, such as @ref{1c7,,bytes}.

@item 
@code{PyUnicode_AsEncodedObject()}:
Use @ref{3a2,,PyCodec_Encode()} instead.

@item 
@code{PyUnicode_AsEncodedUnicode()}:
Use @ref{3a2,,PyCodec_Encode()} instead; Note that some codecs (for example, «base64»)
may return a type other than @ref{1c7,,bytes}, such as @ref{1df,,str}.

@item 
Python initialization functions, deprecated in Python 3.13:


@itemize *

@item 
@code{Py_GetPath()}:
Use @ref{3a6,,PyConfig_Get("module_search_paths")}
(@ref{194,,sys.path}) instead.

@item 
@code{Py_GetPrefix()}:
Use @ref{3a6,,PyConfig_Get("base_prefix")}
(@ref{3aa,,sys.base_prefix}) instead. Use @code{PyConfig_Get("prefix")} (@ref{3ab,,sys.prefix}) if @ref{3a9,,virtual environments} need to be handled.

@item 
@code{Py_GetExecPrefix()}:
Use @ref{3a6,,PyConfig_Get("base_exec_prefix")}
(@ref{3a7,,sys.base_exec_prefix}) instead. Use
@code{PyConfig_Get("exec_prefix")}
(@ref{3a8,,sys.exec_prefix}) if @ref{3a9,,virtual environments} need to
be handled.

@item 
@code{Py_GetProgramFullPath()}:
Use @ref{3a6,,PyConfig_Get("executable")}
(@ref{3ac,,sys.executable}) instead.

@item 
@code{Py_GetProgramName()}:
Use @ref{3a6,,PyConfig_Get("executable")}
(@ref{3ac,,sys.executable}) instead.

@item 
@code{Py_GetPythonHome()}:
Use @ref{3a6,,PyConfig_Get("home")} or the
@geindex PYTHONHOME
@geindex μεταβλητή περιβάλλοντος; PYTHONHOME
@ref{3ad,,PYTHONHOME} environment variable instead.
@end itemize

The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
@ref{3a6,,PyConfig_Get()} on Python 3.13 and older.

@item 
Functions to configure Python’s initialization, deprecated in Python 3.11:


@itemize *

@item 
@code{PySys_SetArgvEx()}:
Set @ref{607,,PyConfig.argv} instead.

@item 
@code{PySys_SetArgv()}:
Set @ref{607,,PyConfig.argv} instead.

@item 
@code{Py_SetProgramName()}:
Set @ref{608,,PyConfig.program_name} instead.

@item 
@code{Py_SetPythonHome()}:
Set @ref{609,,PyConfig.home} instead.

@item 
@code{PySys_ResetWarnOptions()}:
Clear @ref{3a5,,sys.warnoptions} and @code{warnings.filters} instead.
@end itemize

The @ref{60a,,Py_InitializeFromConfig()} API should be used with
@ref{60b,,PyConfig} instead.

@item 
Global configuration variables:


@itemize *

@item 
@ref{60c,,Py_DebugFlag}:
Use @ref{60d,,PyConfig.parser_debug} or
@ref{3a6,,PyConfig_Get("parser_debug")} instead.

@item 
@ref{60e,,Py_VerboseFlag}:
Use @ref{60f,,PyConfig.verbose} or
@ref{3a6,,PyConfig_Get("verbose")} instead.

@item 
@ref{610,,Py_QuietFlag}:
Use @ref{611,,PyConfig.quiet} or
@ref{3a6,,PyConfig_Get("quiet")} instead.

@item 
@ref{612,,Py_InteractiveFlag}:
Use @ref{613,,PyConfig.interactive} or
@ref{3a6,,PyConfig_Get("interactive")} instead.

@item 
@ref{614,,Py_InspectFlag}:
Use @ref{615,,PyConfig.inspect} or
@ref{3a6,,PyConfig_Get("inspect")} instead.

@item 
@ref{616,,Py_OptimizeFlag}:
Use @ref{617,,PyConfig.optimization_level} or
@ref{3a6,,PyConfig_Get("optimization_level")} instead.

@item 
@ref{618,,Py_NoSiteFlag}:
Use @ref{619,,PyConfig.site_import} or
@ref{3a6,,PyConfig_Get("site_import")} instead.

@item 
@ref{61a,,Py_BytesWarningFlag}:
Use @ref{3c4,,PyConfig.bytes_warning} or
@ref{3a6,,PyConfig_Get("bytes_warning")} instead.

@item 
@ref{61b,,Py_FrozenFlag}:
Use @ref{61c,,PyConfig.pathconfig_warnings} or
@ref{3a6,,PyConfig_Get("pathconfig_warnings")} instead.

@item 
@ref{61d,,Py_IgnoreEnvironmentFlag}:
Use @ref{61e,,PyConfig.use_environment} or
@ref{3a6,,PyConfig_Get("use_environment")} instead.

@item 
@ref{61f,,Py_DontWriteBytecodeFlag}:
Use @ref{620,,PyConfig.write_bytecode} or
@ref{3a6,,PyConfig_Get("write_bytecode")} instead.

@item 
@ref{621,,Py_NoUserSiteDirectory}:
Use @ref{622,,PyConfig.user_site_directory} or
@ref{3a6,,PyConfig_Get("user_site_directory")} instead.

@item 
@ref{623,,Py_UnbufferedStdioFlag}:
Use @ref{624,,PyConfig.buffered_stdio} or
@ref{3a6,,PyConfig_Get("buffered_stdio")} instead.

@item 
@ref{625,,Py_HashRandomizationFlag}:
Use @ref{626,,PyConfig.use_hash_seed}
and @ref{627,,PyConfig.hash_seed} or
@ref{3a6,,PyConfig_Get("hash_seed")} instead.

@item 
@ref{628,,Py_IsolatedFlag}:
Use @ref{629,,PyConfig.isolated} or
@ref{3a6,,PyConfig_Get("isolated")} instead.

@item 
@ref{62a,,Py_LegacyWindowsFSEncodingFlag}:
Use @ref{62b,,PyPreConfig.legacy_windows_fs_encoding} or
@ref{3a6,,PyConfig_Get("legacy_windows_fs_encoding")} instead.

@item 
@ref{62c,,Py_LegacyWindowsStdioFlag}:
Use @ref{62d,,PyConfig.legacy_windows_stdio} or
@ref{3a6,,PyConfig_Get("legacy_windows_stdio")} instead.

@item 
@code{Py_FileSystemDefaultEncoding}, @code{Py_HasFileSystemDefaultEncoding}:
Use @ref{62e,,PyConfig.filesystem_encoding} or
@ref{3a6,,PyConfig_Get("filesystem_encoding")} instead.

@item 
@code{Py_FileSystemDefaultEncodeErrors}:
Use @ref{62f,,PyConfig.filesystem_errors} or
@ref{3a6,,PyConfig_Get("filesystem_errors")} instead.

@item 
@code{Py_UTF8Mode}:
Use @ref{630,,PyPreConfig.utf8_mode} or
@ref{3a6,,PyConfig_Get("utf8_mode")} instead.
(see @ref{631,,Py_PreInitialize()})
@end itemize

The @ref{60a,,Py_InitializeFromConfig()} API should be used with
@ref{60b,,PyConfig} to set these options. Or @ref{3a6,,PyConfig_Get()} can be
used to get these options at runtime.
@end itemize

@node Pending removal in Python 3 16<9>,Pending removal in Python 3 18<7>,Pending removal in Python 3 15<8>,C API deprecations
@anchor{deprecations/index id2}@anchor{5d3d}
@subsection Pending removal in Python 3.16



@itemize *

@item 
The bundled copy of @code{libmpdec}.
@end itemize

@node Pending removal in Python 3 18<7>,Pending removal in Python 3 19<6>,Pending removal in Python 3 16<9>,C API deprecations
@anchor{deprecations/index id3}@anchor{5d3e}
@subsection Pending removal in Python 3.18



@itemize *

@item 
The following private functions are deprecated
and planned for removal in Python 3.18:


@itemize *

@item 
@code{_PyBytes_Join()}: use @ref{5b0,,PyBytes_Join()}.

@item 
@code{_PyDict_GetItemStringWithError()}: use @ref{634,,PyDict_GetItemStringRef()}.

@item 
@code{_PyDict_Pop()}: use @ref{635,,PyDict_Pop()}.

@item 
@code{_PyLong_Sign()}: use @ref{5c7,,PyLong_GetSign()}.

@item 
@code{_PyLong_FromDigits()} and @code{_PyLong_New()}:
use @ref{5d7,,PyLongWriter_Create()}.

@item 
@code{_PyThreadState_UncheckedGet()}: use @ref{636,,PyThreadState_GetUnchecked()}.

@item 
@code{_PyUnicode_AsString()}: use @ref{637,,PyUnicode_AsUTF8()}.

@item 
@code{_PyUnicodeWriter_Init()}:
replace @code{_PyUnicodeWriter_Init(&writer)} with
@ref{5e1,,writer = PyUnicodeWriter_Create(0)}.

@item 
@code{_PyUnicodeWriter_Finish()}:
replace @code{_PyUnicodeWriter_Finish(&writer)} with
@ref{5e4,,PyUnicodeWriter_Finish(writer)}.

@item 
@code{_PyUnicodeWriter_Dealloc()}:
replace @code{_PyUnicodeWriter_Dealloc(&writer)} with
@ref{5e3,,PyUnicodeWriter_Discard(writer)}.

@item 
@code{_PyUnicodeWriter_WriteChar()}:
replace @code{_PyUnicodeWriter_WriteChar(&writer, ch)} with
@ref{5e7,,PyUnicodeWriter_WriteChar(writer@comma{} ch)}.

@item 
@code{_PyUnicodeWriter_WriteStr()}:
replace @code{_PyUnicodeWriter_WriteStr(&writer, str)} with
@ref{5e9,,PyUnicodeWriter_WriteStr(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_WriteSubstring()}:
replace @code{_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)} with
@ref{5ea,,PyUnicodeWriter_WriteSubstring(writer@comma{} str@comma{} start@comma{} end)}.

@item 
@code{_PyUnicodeWriter_WriteASCIIString()}:
replace @code{_PyUnicodeWriter_WriteASCIIString(&writer, str)} with
@ref{5e6,,PyUnicodeWriter_WriteASCII(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_WriteLatin1String()}:
replace @code{_PyUnicodeWriter_WriteLatin1String(&writer, str)} with
@ref{5ec,,PyUnicodeWriter_WriteUTF8(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_Prepare()}: (no replacement).

@item 
@code{_PyUnicodeWriter_PrepareKind()}: (no replacement).

@item 
@code{_Py_HashPointer()}: use @ref{638,,Py_HashPointer()}.

@item 
@code{_Py_fopen_obj()}: use @ref{5c0,,Py_fopen()}.
@end itemize

The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
these new public functions on Python 3.13 and older.
(Contributed by Victor Stinner in gh-128863@footnote{https://github.com/python/cpython/issues/128863}.)
@end itemize

@node Pending removal in Python 3 19<6>,Pending removal in Python 3 20<6>,Pending removal in Python 3 18<7>,C API deprecations
@anchor{deprecations/index id4}@anchor{5d3f}
@subsection Pending removal in Python 3.19



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 456
PEP 456@footnote{https://peps.python.org/pep-0456/} embedders support for the string hashing scheme definition.
@end itemize

@node Pending removal in Python 3 20<6>,Pending removal in future versions<9>,Pending removal in Python 3 19<6>,C API deprecations
@anchor{deprecations/index id5}@anchor{5d40}
@subsection Pending removal in Python 3.20



@itemize *

@item 
@code{_PyObject_CallMethodId()}, @code{_PyObject_GetAttrId()} and
@code{_PyUnicode_FromId()} are deprecated since 3.15 and will be removed in
3.20. Instead, use @ref{3b5,,PyUnicode_InternFromString()} and cache the result in
the module state, then call @ref{3b6,,PyObject_CallMethod()} or
@ref{3b7,,PyObject_GetAttr()}.
(Contributed by Victor Stinner in gh-141049@footnote{https://github.com/python/cpython/issues/141049}.)

@item 
The @code{cval} field in @ref{3b9,,PyComplexObject} (gh-128813@footnote{https://github.com/python/cpython/issues/128813}).
Use @ref{3ba,,PyComplex_AsCComplex()} and @ref{3bb,,PyComplex_FromCComplex()}
to convert a Python complex number to/from the C @ref{3bc,,Py_complex}
representation.

@item 
Macros @code{Py_MATH_PIl} and @code{Py_MATH_El}.
@end itemize

@node Pending removal in future versions<9>,,Pending removal in Python 3 20<6>,C API deprecations
@anchor{deprecations/index id6}@anchor{5d41}
@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{63a,,Py_TPFLAGS_HAVE_FINALIZE}:
Unneeded since Python 3.8.

@item 
@ref{63b,,PyErr_Fetch()}:
Use @ref{63c,,PyErr_GetRaisedException()} instead.

@item 
@ref{63d,,PyErr_NormalizeException()}:
Use @ref{63c,,PyErr_GetRaisedException()} instead.

@item 
@ref{63e,,PyErr_Restore()}:
Use @ref{63f,,PyErr_SetRaisedException()} instead.

@item 
@ref{640,,PyModule_GetFilename()}:
Use @ref{641,,PyModule_GetFilenameObject()} instead.

@item 
@ref{642,,PyOS_AfterFork()}:
Use @ref{643,,PyOS_AfterFork_Child()} instead.

@item 
@ref{644,,PySlice_GetIndicesEx()}:
Use @ref{645,,PySlice_Unpack()} and @ref{646,,PySlice_AdjustIndices()} instead.

@item 
@ref{647,,PyUnicode_READY()}:
Unneeded since Python 3.12

@item 
@code{PyErr_Display()}:
Use @ref{648,,PyErr_DisplayException()} instead.

@item 
@code{_PyErr_ChainExceptions()}:
Use @code{_PyErr_ChainExceptions1()} instead.

@item 
@code{PyBytesObject.ob_shash} member:
call @ref{649,,PyObject_Hash()} instead.

@item 
Thread Local Storage (TLS) API:


@itemize *

@item 
@ref{64a,,PyThread_create_key()}:
Use @ref{64b,,PyThread_tss_alloc()} instead.

@item 
@ref{64c,,PyThread_delete_key()}:
Use @ref{64d,,PyThread_tss_free()} instead.

@item 
@ref{64e,,PyThread_set_key_value()}:
Use @ref{64f,,PyThread_tss_set()} instead.

@item 
@ref{650,,PyThread_get_key_value()}:
Use @ref{651,,PyThread_tss_get()} instead.

@item 
@ref{652,,PyThread_delete_key_value()}:
Use @ref{653,,PyThread_tss_delete()} instead.

@item 
@ref{654,,PyThread_ReInitTLS()}:
Unneeded since Python 3.7.
@end itemize
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Γλωσσάρι,Σχετικά με την τεκμηρίωση,Deprecations,Top
@anchor{glossary doc}@anchor{5d42}@anchor{glossary glossary}@anchor{21ac}@anchor{glossary id1}@anchor{5d43}@anchor{glossary translation-repo}@anchor{5d44}
@chapter Γλωσσάρι


@c if you add new entries, keep the alphabetical sorting!


@table @asis
@anchor{glossary term-0}@anchor{69e}
@geindex >>>

@item @code{>>>}

Η προεπιλεγμένη Python εντολή του @ref{451,,interactive} shell. Συχνά εμφανίζεται για παραδείγματα κώδικα που μπορούν να εκτελεστούν διαδραστικά στον interpreter.
@anchor{glossary term-}@anchor{69f}
@geindex ...

@item @code{...}

Μπορεί να αναφέρεται σε:


@itemize *

@item 
Η προεπιλεγμένη Python εντολή του @ref{451,,interactive} shell κατά την εισαγωγή του κώδικα για ένα μπλοκ κώδικα με εσοχή, όταν βρίσκεται μέσα σε ένα ζεύγος ταιριασμένων αριστερών και δεξιών delimiters (παρενθέσεις, αγκύλες, άγκιστρα ή τριπλά εισαγωγικά), ή μετά τον καθορισμό ενός decorator.
@end itemize

@geindex ...;ellipsis literal


@itemize *

@item 
Η μορφή με τις τρεις τελείες του αντικειμένου @ref{21ea,,Ellipsis}.
@end itemize
@anchor{glossary term-abstract-base-class}@anchor{155f}
@geindex αφηρημένη βασική κλάση

@item αφηρημένη βασική κλάση

Οι αφηρημένες βασικές κλάσεις συμπληρώνουν το @ref{5d45,,duck-typing} παρέχοντας έναν τρόπο ορισμού interfaces όταν άλλες τεχνικές όπως η @ref{8e2,,hasattr()} θα ήταν αδέξιες ή ανεπαίσθητα λανθασμένες (για παράδειγμα με @ref{25a6,,magic methods}). Τα ABC (abstract base class) εισάγουν εικονικές υποκλάσεις, οι οποίες είναι κλάσεις που δεν κληρονομούνται από μια κλάση, αλλά εξακολουθούν να αναγνωρίζονται από το @ref{2ef,,isinstance()} και από το @ref{2f0,,issubclass()}” βλ. την τεκμηρίωση του module @ref{4,,abc}. Η Python διαθέτει πολλά ενσωματωμένα ABC για δομές δεδομένων (στο module @ref{1f,,collections.abc}), αριθμούς (στο module @ref{a2,,numbers}), ροές (στο module μονάδα @ref{82,,io}), εισαγωγή finders και loaders (στο module @ref{7b,,importlib.abc}). Μπορείτε να δημιουργήσετε τα δικά σας ABC με το module @code{abc}.
@anchor{glossary term-annotate-function}@anchor{40a}
@geindex συνάρτηση annotate

@item συνάρτηση annotate

A callable that can be called to retrieve the @ref{409,,annotations} of
an object. Annotate functions are usually @ref{26ae,,functions},
automatically generated as the @ref{1b95,,__annotate__} attribute of functions,
classes, and modules. Annotate functions are a subset of
@ref{473c,,evaluate functions}.
@anchor{glossary term-annotation}@anchor{409}
@geindex annotation

@item annotation

Μια ετικέτα που σχετίζεται με μια μεταβλητή, ένα χαρακτηριστικό κλάσης ή μια παράμετρος συνάρτησης ή τιμή που επιστρέφεται, που χρησιμοποιείται κατά σύμβαση ως @ref{25c1,,type hint}.

Δεν είναι δυνατή η πρόσβαση στα annotations των τοπικών μεταβλητών κατά το χρόνο εκτέλεσης, αλλά τα annotations των global μεταβλητών, των χαρακτηριστικών κλάσης και των συναρτήσεων μπορούν να ανακτηθούν καλώντας την εντολή @ref{66c,,annotationlib.get_annotations()} σε modules, κλάσεις και συναρτήσεις, αντίστοιχα.

Βλ. τα @ref{110a,,variable annotation}, @ref{2207,,function annotation}, 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}, 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/} και 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/}, τα οποία περιγράφουν την λειτουργικότητα. Δείτε επίσης τα @ref{bb6,,Annotations Best Practices} για τις βέλτιστες πρακτικές δουλεύοντας με annotations.
@anchor{glossary term-argument}@anchor{867}
@geindex όρισμα

@item όρισμα

Μια τιμή μεταβιβάζεται σε μία @ref{26ae,,function} (ή @ref{1a8c,,method}) κατά την κλήση της συνάρτησης.  Υπάρχουν δύο είδη ορισμάτων:


@itemize *

@item 
`keyword argument': ένα όρισμα πριν από ένα αναγνωριστικό (π.χ. @code{name=}) σε μια κλήση συνάρτησης ή περνώντας το ως τιμή σε ένα λεξικό πριν από @code{**}. Για παράδειγμα, το @code{3} και το @code{5} αποτελούν ορίσματα λέξεων-κλειδιών στις ακόλουθες κλήσεις προς @ref{328,,complex()}:

@example
complex(real=3, imag=5)
complex(**@{'real': 3, 'imag': 5@})
@end example

@item 
`positional argument': ένα όρισμα που δεν είναι όρισμα keyword. Τα ορίσματα θέσης μπορούν να εμφανίζονται στην αρχής μιας λίστας ορισμάτων ή/και να μεταβιβάζονται ως στοιχεία ενός @ref{15ce,,iterable} πριν από @code{*}. Για παράδειγμα, το @code{3} και το @code{5} αποτελούν ορίσματα θέσης στις παρακάτω κλήσεις:

@example
complex(3, 5)
complex(*(3, 5))
@end example
@end itemize

Τα ορίσματα εκχωρούνται στις ονομασμένες τοπικές μεταβλητές στο σώμα μια συνάρτησης. Βλ. την ενότητα @ref{1136,,Calls} για τους κανόνες που διέπουν αυτήν την εκχώρηση. Συντακτικά, οποιαδήποτε έκφραση μπορεί να χρησιμοποιηθεί για να αναπαραστήσει ένα όρισμα” η αξιολογούμενη τιμή εκχωρείται σε μια τοπική μεταβλητή.

Βλ. επίσης την εγγραφή του γλωσσαρίου για το @ref{253c,,parameter}, την FAQ ερώτηση στο @ref{5c7a,,η διαφορά μεταξύ ορισμάτων και παραμέτρων}, και 
@geindex Python Enhancement Proposals; PEP 362
PEP 362@footnote{https://peps.python.org/pep-0362/}.
@anchor{glossary term-asynchronous-context-manager}@anchor{9d2}
@geindex ασύγχρονος διαχειριστής context

@item ασύγχρονος διαχειριστής context

Ένα αντικείμενο που ελέγχει το ορατό περιβάλλον σε μια δήλωση @ref{20b,,async with} ορίζοντας τις μεθόδους @ref{2613,,__aenter__()} και @ref{1bad,,__aexit__()}. Που εισήχθη από 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@anchor{glossary term-asynchronous-generator}@anchor{2692}
@geindex ασύγχρονος generator

@item ασύγχρονος generator

Μια συνάρτηση που επιστρέφει έναν @ref{3b87,,asynchronous generator iterator}. Μοιάζει με μια συνάρτηση coroutine που ορίζεται με @ref{9cf,,async def} εκτός από ότι περιέχει εκφράσεις @ref{d93,,yield} για την παραγωγή μιας σειράς τιμών που μπορούν να χρησιμοποιηθούν σε έναν @ref{e70,,async for} βρόχο.

Συνήθως αναφέρεται σε μια συνάρτηση ασύγχρονου generator, αλλά μπορεί να αναφέρεται σε έναν `ασύγχρονο generator iterator' σε ορισμένα contexts. Σε περιπτώσεις όπου το επιδιωκόμενο νόημα δεν είναι σαφές, με την χρήση των πλήρων όρων αποφεύγεται η ασάφεια.

Μια συνάρτηση ασύγχρονου generator μπορεί να περιέχει εκφράσεις @ref{432,,await} , καθώς και δηλώσεις @ref{e70,,async for}, και @ref{20b,,async with}.
@anchor{glossary term-asynchronous-generator-iterator}@anchor{3b87}
@geindex ασύγχρονος generator iterator

@item ασύγχρονος generator iterator

Ένα αντικείμενο που δημιουργήθηκε από μια συνάρτηση @ref{2692,,asynchronous generator}.

Αυτός είναι ένας @ref{6cd,,asynchronous iterator} που όταν καλείται χρησιμοποιώντας την μέθοδο @ref{1aa7,,__anext__()} επιστρέφει ένα αναμενόμενο αντικείμενο που θα εκτελέσει στο σώμα της συνάρτησης του ασύγχρονου generator μέχρι την επόμενη @ref{d93,,yield} έκφραση.

Κάθε @ref{d93,,yield} αναστέλλει προσωρινά την επεξεργασία, θυμάται την κατάσταση εκτέλεσης (συμπεριλαμβανομένων των τοπικών μεταβλητών και των δηλώσεων @cite{try} σε εκκρεμότητα). Όταν ο `ασύγχρονος generator iterator' συνεχίσει αποτελεσματικά με άλλο αναμενόμενο που επιστρέφεται από @ref{1aa7,,__anext__()}, συνεχίζει από εκεί που σταμάτησε. Βλ. 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} και 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/}.
@anchor{glossary term-asynchronous-iterable}@anchor{112d}
@geindex ασύγχρονος iterable

@item ασύγχρονος iterable

Ένα αντικείμενο, που μπορεί να χρησιμοποιηθεί σε μια δήλωση @ref{e70,,async for}. Πρέπει να επιστρέφει ένα @ref{6cd,,asynchronous iterator} από την μέθοδο @ref{fbb,,__aiter__()}. Που εισήχθη από 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@anchor{glossary term-asynchronous-iterator}@anchor{6cd}
@geindex ασύγχρονος iterator

@item ασύγχρονος iterator

Ένα αντικείμενο που υλοποιεί τις μεθόδους @ref{fbb,,__aiter__()} και @ref{1aa7,,__anext__()}. Η μέθοδος @code{__anext__()} πρέπει να επιστρέφει ένα @ref{6cf,,awaitable} αντικείμενο. Το @ref{e70,,async for} επιλύει τα αναμενόμενα που επιστρέφονται από τη μέθοδο @code{__anext__()} ενός ασύγχρονου iterator έως ότου εγείρει μια εξαίρεση @ref{1ffe,,StopAsyncIteration}. Εισήχθη από 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@anchor{glossary term-atomic-operation}@anchor{292c}
@geindex atomic operation

@item atomic operation

An operation that appears to execute as a single, indivisible step: no
other thread can observe it half-done, and its effects become visible all
at once.  Python does not guarantee that high-level statements are atomic
(for example, @code{x += 1} performs multiple bytecode operations and is not
atomic).  Atomicity is only guaranteed where explicitly documented.  See
also @ref{2921,,race condition} and @ref{2922,,data race}.
@anchor{glossary term-attached-thread-state}@anchor{1a1}
@geindex κατάσταση συνδεδεμένου νήματος

@item κατάσταση συνδεδεμένου νήματος

Ένα @ref{1a70,,thread state} που είναι ενεργή για το τρέχον νήμα του λειτουργικού συστήματος.

Όταν επισυνάπτεται ένας @ref{1a70,,thread state}, το νήμα του λειτουργικού συστήματος έχει πρόσβαση στο πλήρες Python C API και μπορεί να καλέσει με ασφάλεια τον διερμηνέα bytecode.

Εκτός εάν μια συνάρτηση αναφέρει ρητά το αντίθετο, η προσπάθεια κλήσης του C API χωρίς μια συνημμένη κατάσταση νήματος θα οδηγήσει ένα μοιραίο σφάλμα ή σε απροσδιόριστη συμπεριφορά.  Μια κατάσταση νήματος μπορεί να συνδεθεί και να αποσυνδεθεί ρητά από τον χρήση μέσω του C API ή έμμεσα από τον χρόνο εκτέλεσης, συμπεριλαμβανομένων των κλήσεων αποκλεισμού C και από τον διερμηνέα bytecode μεταξύ των κλήσεων.

On most builds of Python, having an attached thread state implies that the
caller holds the @ref{411,,GIL} for the current interpreter, so only
one OS thread can have an attached thread state at a given moment. In
@ref{198,,free-threaded builds} of Python, threads can
concurrently hold an attached thread state, allowing for true parallelism of
the bytecode interpreter.
@anchor{glossary term-attribute}@anchor{2b1e}
@geindex χαρακτηριστικό

@item χαρακτηριστικό

Μια τιμή που σχετίζεται με ένα αντικείμενο που συνήθως αναφέρεται με όνομα χρησιμοποιώντας εκφράσεις με κουκκίδες. Για παράδειγμα, εάν ένα αντικείμενο `o' έχει ένα χαρακτηριστικό `a' θα αναφέρεται ως `o.a'.

Είναι δυνατό να δώσουμε σε ένα αντικείμενο ένα χαρακτηριστικό που το όνομα του δεν είναι αναγνωριστικό όπως ορίζεται από @ref{2491,,Ονόματα (αναγνωριστικά και λέξεις-κλειδιά)}, για παράδειγμα χρησιμοποιώντας @ref{27b7,,setattr()}, αν επιτρέπεται από το αντικείμενο. Ένα τέτοιο χαρακτηριστικό δεν θα είναι προσβάσιμο χρησιμοποιώντας τις τελείες, και αντί αυτού θα πρέπει να ανακτηθεί χρησιμοποιώντας @ref{f8f,,getattr()}.
@anchor{glossary term-awaitable}@anchor{6cf}
@geindex awaitable

@item awaitable

Ένα αντικείμενο που μπορεί να χρησιμοποιηθεί στην έκφραση @ref{432,,await}. Μπορεί να είναι @ref{8a2,,coroutine} ή ένα αντικείμενο με μια @ref{112e,,__await__()} μέθοδο. Βλ. επίσης 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@anchor{glossary term-BDFL}@anchor{5d46}
@geindex BDFL

@item BDFL

Ακρωνύμιο του `Benevolent Dictator For Life', καλοκάγαθος δικτάτορας της ζωής, δηλαδή Guido van Rossum@footnote{https://gvanrossum.github.io/}, ο δημιουργός της Python.
@anchor{glossary term-binary-file}@anchor{225d}
@geindex δυαδικό αρχείο

@item δυαδικό αρχείο

Ένα @ref{156c,,file object} ικανό να διαβάζει και να γράφει @ref{436,,δυαδικού τύπου αντικείμενα}. Παραδείγματα δυαδικών αρχείων είναι αρχεία που ανοίγουν σε δυαδική λειτουργία (@code{'rb'}, @code{'wb'} ή @code{'rb+'}), @ref{94a,,sys.stdin.buffer}, @ref{e9c,,sys.stdout.buffer}, και στιγμιοτύπων των @ref{1255,,io.BytesIO} και @ref{849,,gzip.GzipFile}.

Βλ. επίσης @ref{225c,,text file} για ένα αντικείμενο τύπου αρχείο ικανό να διαβάσει και να γράψει @ref{1df,,str} αντικείμενα.
@anchor{glossary term-borrowed-reference}@anchor{603}
@geindex δανεική αναφορά

@item δανεική αναφορά

Στο C API της Python, μια δανεική αναφορά είναι μια αναφορά σε ένα αντικείμενο, όπου ο κώδικας που χρησιμοποιεί το αντικείμενο δεν κατέχει την αναφορά. Γίνεται ένας αχρησιμοποίητος δείκτης εάν το αντικείμενο καταστραφεί. Για παράδειγμα, μια διαδικασία garbage collection μπορεί να αφαιρέσει το τελευταίο @ref{7da,,strong reference} από το αντικείμενο και έτσι να το καταστρέψει.

Συνίσταται η κλήση του @ref{974,,Py_INCREF()} στο @ref{603,,δανεική αναφορά} με σκοπό να μετατραπεί σε ένα @ref{7da,,ισχυρή αναφορά} επιτόπου, εκτός όταν το αντικείμενο δεν μπορεί να καταστραφεί πριν από την τελευταία χρήση της δανεικής αναφοράς. Η συνάρτηση @ref{c70,,Py_NewRef()} μπορεί να χρησιμοποιηθεί ώστε να δημιουργηθεί ένα ισχυρή αναφορά.
@anchor{glossary term-bytes-like-object}@anchor{436}
@geindex bytes-like αντικείμενα

@item bytes-like αντικείμενα

Ένα αντικείμενο που υποστηρίζει το @ref{311,,Buffer Protocol} και μπορεί να εξάγει ένα C-@ref{287e,,contiguous} buffer. Αυτό περιλαμβάνει όλα τα αντικείμενα @ref{1c7,,bytes}, @ref{1c6,,bytearray}, και @ref{6c5,,array.array}, καθώς και πολλά κοινά @ref{1d2,,memoryview} αντικείμενα. Τα δυαδικού τύπου (bytes-like) αντικείμενα μπορούν να χρησιμοποιηθούν για διάφορες λειτουργίες που διαχειρίζονται δυαδικά δεδομένα” αυτά περιλαμβάνουν συμπίεση αποθήκευση σε δυαδικό αρχείο και αποστολή μέσω socket.

Ορισμένες λειτουργίες χρειάζονται τα δυαδικά δεδομένα να είναι μεταβλητά.  Η τεκμηρίωση συχνά αναφέρεται σε αυτά ως «δυαδικά αντικείμενα ανάγνωσης-εγγραφής» (read-write bytes-like objects). Παραδείγματα μεταβλητών αντικειμένων προσωρινής αποθήκευσης περιέχουν @ref{1c6,,bytearray} και ένα @ref{1d2,,memoryview} ενός @code{bytearray}. Άλλες λειτουργίες απαιτούν την αποθήκευσης των δυαδικών δεδομένα σε αμετάβλητα αντικείμενα («δυαδικά αντικείμενα μόνο ανάγνωσης»” (read-only bytes-like objects) παραδείγματα αυτών περιέχουν @ref{1c7,,bytes} και ένα @code{memoryview} ενός @code{bytes} αντικειμένου.
@anchor{glossary term-bytecode}@anchor{6b3}
@geindex bytecode

@item bytecode

Ο πηγαίος κώδικα της Python μεταγλωττίζεται σε `bytecode', η εσωτερική αναπαράσταση ενός προγράμματος Python στον διερμηνέα CPython. Το `bytecode' αποθηκεύεται επίσης προσωρινά ως @code{.pyc} αρχεία ώστε η εκτέλεση του ίδιου αρχείου να είναι γρηγορότερη την δεύτερη φορά εκτέλεσης (μπορεί να αποφευχθεί η εκ νέου μεταγλώττιση από τον πηγαίο κώδικα σε `bytcode'). Αυτή η «ενδιάμεση γλώσσα» λέγεται ότι τρέχει σε μια @ref{3ca3,,virtual machine} που εκτελεί τον κώδικα μηχανής που αντιστοιχεί σε κάθε `bytecode'. Λάβετε υπόψη ότι τα `bytecode' δεν αναμένεται να λειτουργούν μεταξύ διαφορετικών εικονικών μηχανών Python, ούτε να είναι σταθερά μεταξύ των εκδόσεων της Python.

Μια λίστα από οδηγίες σχετικά με τα bytecode μπορεί να βρεθεί στην τεκμηρίωση για @ref{9b1,,το module dis}.
@anchor{glossary term-callable}@anchor{2fa4}
@geindex callable

@item callable

Ένα callable είναι ένα αντικείμενο που μπορεί να καλεστεί, πιθανά με ένα σύνολο ορισμάτων (βλ. @ref{867,,argument}), με την παρακάτω σύνταξη:

@example
callable(argument1, argument2, argumentN)
@end example

Μια @ref{26ae,,function}, και κατ” επέκταση μια @ref{1a8c,,method} είναι callable. Ένα στιγμιότυπο μια κλάσης που υλοποιεί τη μέθοδο @ref{961,,__call__()} είναι επίσης callable.
@anchor{glossary term-callback}@anchor{2fc5}
@geindex callback

@item callback

Μια subroutine συνάρτηση η οποία μεταβιβάζεται ως όρισμα που θα εκτελεστεί κάποια στιγμή στο μέλλον.
@anchor{glossary term-class}@anchor{1ef2}
@geindex κλάση

@item κλάση

Ένα πρότυπο για τη δημιουργία αντικειμένων που ορίζονται από το χρήστη. Οι ορισμοί κλάσεων συνήθως περιέχουν ορισμούς μεθόδων που λειτουργούν σε στιγμιότυπα της κλάσης.
@anchor{glossary term-class-variable}@anchor{5d47}
@geindex μεταβλητή κλάσης

@item μεταβλητή κλάσης

Μια μεταβλητή που ορίζεται σε μια κλάση και προορίζεται να τροποποιηθεί μόνο σε επίπεδο κλάσης (δηλ. όχι σε ένα στιγμιότυπο μιας κλάσης).
@anchor{glossary term-closure-variable}@anchor{1ab7}
@geindex μεταβλητή κλεισίματος

@item μεταβλητή κλεισίματος

Ένας @ref{261e,,free variable} που αναφέρεται από ένα @ref{2581,,nested scope} και ορίζεται σε μια εξωτερική περιοχή, αντί να επιλύεται δυναμικά κατά την εκτέλεση από τα καθολικά ή ενσωματωμένα namespaces. Μπορεί να δηλωθεί ρητά με τη δεσμευμένη λέξη-κλειδί @ref{164c,,nonlocal} ώστε να επιτραπεί η εγγραφή, ή να θεωρηθεί ότι ορίζεται έμμεσα όταν η μεταβλητή χρησιμοποιείται μόνο για ανάγνωση.

Για παράδειγμα, η συνάρτηση @code{inner} του παρακάτω κώδικα, τόσο η @code{x} όσο και η @code{print} είναι @ref{261e,,free variables}, αλλά μόνο η @code{x} είναι μια `μεταβλητή κλεισίματος':

@example
def outer():
    x = 0
    def inner():
        nonlocal x
        x += 1
        print(x)
    return inner
@end example

Λόγο του χαρακτηριστικού @ref{2538,,codeobject.co_freevars} (το οποίο, παρά την ονομασία του, περιλαμβάνει μόνο τα ονόματα των μεταβλητών κλεισίματος και όχι όλες τις αναφερόμενες ελεύθερες μεταβλητές), χρησιμοποιείται μερικές φορές ο πιο γενικός όρος @ref{261e,,free variable} ακόμη και όταν γίνεται ειδική αναφορά σε μεταβλητές κλεισίματος.
@anchor{glossary term-complex-number}@anchor{5d48}
@geindex μιγαδικός αριθμός

@item μιγαδικός αριθμός

Μια επέκταση του γνωστού συστήματος πραγματικών αριθμών στο οποίο όλοι οι αριθμοί εκφράζονται ως άθροισμα ενός πραγματικού μέρους και ενός φανταστικού μέρους. Οι φανταστικοί αριθμοί είναι πραγματικά πολλαπλάσια της φανταστικής μονάδα (η τετραγωνική ρίζα του @code{-1}), που συχνά γράφονται @code{i} στα μαθηματικά ή @code{j} στη μηχανική. Η Python έχει ενσωματωμένη υποστήριξη για μιγαδικούς αριθμούς, οι οποίοι γράφονται με αυτόν τον τελευταίο συμβολισμό” το φανταστικό μέρος γράφεται με το επίθημα @code{j}, π.χ., @code{3+1j}. Για να αποκτήσετε πρόσβαση σε σύνθετα ισοδύναμα το module @ref{91,,math}, χρησιμοποιήστε το @ref{19,,cmath}. Η χρήση μιγαδικών αριθμών είναι ένα αρκετά προηγμένο μαθηματικό χαρακτηριστικό. εάν δεν γνωρίζετε την ανάγκη τους, είναι σχεδόν σίγουρο ότι μπορείτε να τα αγνοήσετε με ασφάλεια.
@anchor{glossary term-concurrency}@anchor{5d49}
@geindex concurrency

@item concurrency

The ability of a computer program to perform multiple tasks at the same
time.  Python provides libraries for writing programs that make use of
different forms of concurrency.  @ref{b,,asyncio} is a library for dealing
with asynchronous tasks and coroutines.  @ref{f6,,threading} provides
access to operating system threads and @ref{98,,multiprocessing} to
operating system processes. Multi-core processors can execute threads and
processes on different CPU cores at the same time (see
@ref{5d4a,,parallelism}).
@anchor{glossary term-concurrent-modification}@anchor{5d4b}
@geindex concurrent modification

@item concurrent modification

When multiple threads modify shared data at the same time.  Concurrent
modification without proper synchronization can cause
@ref{2921,,race conditions}, and might also trigger a
@ref{2922,,data race}, data corruption, or both.
@anchor{glossary term-context}@anchor{1b76}
@geindex context

@item context

Αυτό ο όρος έχει διαφορετικές σημασίες ανάλογα με το πού και πώς χρησιμοποιείται. Μερικές κοινές έννοιες:


@itemize *

@item 
Η προσωρινή κατάσταση ή το περιβάλλον που δημιουργείται από έναν @ref{478,,context manager} μέσω μιας δήλωσης @ref{20a,,with}.

@item 
Το σύνολο των δεσμευμένων κλειδιού-τιμής που σχετίζονται με ένα συγκεκριμένο αντικείμενο @ref{421,,contextvars.Context} και προσπελάζονται μέσω αντικειμένων @ref{1a9d,,ContextVar}.  Βλ. επίσης @ref{5d4c,,context variable}.

@item 
Ένα αντικείμενο @ref{421,,contextvars.Context}.  Βλ. επίσης @ref{1b77,,current context}.
@end itemize
@anchor{glossary term-context-management-protocol}@anchor{1b78}
@geindex πρωτόκολλο διαχείρισης περιβάλλοντος

@item πρωτόκολλο διαχείρισης περιβάλλοντος

Οι μέθοδοι @ref{9c6,,__enter__()} και @ref{16a5,,__exit__()}  καλούνται από τη δήλωση @ref{20a,,with}.  Βλ. 
@geindex Python Enhancement Proposals; PEP 343
PEP 343@footnote{https://peps.python.org/pep-0343/}.
@anchor{glossary term-context-manager}@anchor{478}
@geindex διαχειριστής context

@item διαχειριστής context

Ένα αντικείμενο που υλοποιεί το @ref{1b78,,context management protocol} και ελέγχει το περιβάλλον που είσαι ορατό μέσα σε μια δήλωση @ref{20a,,with}.  Βλ. 
@geindex Python Enhancement Proposals; PEP 343
PEP 343@footnote{https://peps.python.org/pep-0343/}.
@anchor{glossary term-context-variable}@anchor{5d4c}
@geindex context μεταβλητή

@item context μεταβλητή

Μια μεταβλητή της οποίας η τιμή εξαρτάται από το ποιο είναι το @ref{1b77,,current context}.  Οι τιμές προσπελάζονται μέσω των αντικειμένων @ref{1a9d,,contextvars.ContextVar}.  Οι μεταβλητές συμφραζόμενων χρησιμοποιούνται κυρίως για να απομονώσουν την κατάσταση μεταξύ ταυτόχρονων ασύγχρονων εργασιών.
@anchor{glossary term-contiguous}@anchor{287e}
@geindex contiguous

@item contiguous

@geindex C-contiguous
@geindex Fortran contiguous

Ένα buffer θεωρείται contiguous ακριβώς εάν είναι είτε `C-contiguous' είτε `Fortran contriguous'. Το buffer μηδενικών διαστάσεων είναι C και Fortran contiguous. Σε μονοδιάστατους πίνακες, τα στοιχεία πρέπει να τοποθετούνται στη μνήμη το ένα δίπλα στο άλλο, με σειρά αύξησης των δεικτών ξεκινώντας από το μηδέν. Σε πολυδιάστατους C-contiguous πίνακες, ο τελευταίος δείκτης μεταβάλλεται ταχύτερα όταν επισκέπτονται τα στοιχεία σε σειρά διεύθυνσης μνήμης. Ωστόσο, σε Fortran contiguous πίνακες, ο πρώτος δείκτης μεταβάλλεται πιο γρήγορα.
@anchor{glossary term-coroutine}@anchor{8a2}
@geindex coroutine

@item coroutine

Οι coroutines είναι μια πιο γενικευμένη μορφή subroutines. Οι subroutines εισάγονται σε ένα σημείο και εξάγονται σε άλλο σημείο. Οι coroutines μπορεί να εισαχθούν, να εξαχθούν και να συνεχιστούν σε πολλά διαφορετικά σημεία. Μπορούν να υλοποιήσουν με την δήλωση @ref{9cf,,async def}. Βλ. επίσης 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@anchor{glossary term-coroutine-function}@anchor{112c}
@geindex coroutine συνάρτηση

@item coroutine συνάρτηση

Μια συνάρτηση που επιστρέφει ένα @ref{8a2,,coroutine} αντικείμενο.  Μια συνάρτηση coroutine μπορεί να ορίζεται από τη δήλωση @ref{9cf,,async def}, και μπορεί να περιέχει @ref{432,,await}, @ref{e70,,async for}, και @ref{20b,,async with} λέξεις κλειδιά. Αυτές εισήχθησαν από το 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@anchor{glossary term-CPython}@anchor{ae3}
@geindex CPython

@item CPython

Η κανονική υλοποίηση της γλώσσας προγραμματισμού Python, όπως διανέμεται στο python.org@footnote{https://www.python.org}. Ο όρος «CPython» χρησιμοποιείται όταν είναι απαραίτητο για την διάκριση αυτής της υλοποίησης από άλλες όπως η `Jython' ή η `IronPython'.
@anchor{glossary term-current-context}@anchor{1b77}
@geindex τρέχον πλαίσιο

@item τρέχον πλαίσιο

Το @ref{1b76,,context} (@ref{421,,contextvars.Context} αντικείμενο) που χρησιμοποιείται αυτή τη στιγμή από τα αντικείμενα @ref{1a9d,,ContextVar} για να προσπελάσει (να πάρει ή να ορίσει) τις τιμές των @ref{5d4c,,context variables}.  Κάθε νήμα έχει το δικό του τρέχον συμφραζόμενο Τα πλαίσια για την εκτέλεση ασύγχρονων εργασιών (βλ. @ref{b,,asyncio}) συνδέουν κάθε εργασία με ένα συμφραζόμενο, το οποίο γίνεται το τρέχον συμφραζόμενο όποτε η εργασία ξεκινά ή συνεχίζει την εκτέλεση.
@anchor{glossary term-cyclic-isolate}@anchor{5971}
@geindex κυκλική απομόνωση

@item κυκλική απομόνωση

Μια υποομάδα ενός ή περισσότερων αντικειμένων που αναφέρονται μεταξύ τους σχηματίζοντας έναν  κύκλο αναφορών, αλλά δεν αναφέρονται από άλλα αντικείμενα εκτός της ομάδας.  Ο σκοπός του @ref{19de,,cyclic garbage collector} είναι να εντοπίζει αυτές τις ομάδες και να σπάει του κύκλος αναφορών ώστε να μπορεί να αποδεσμευτεί η μνήμη.
@anchor{glossary term-data-race}@anchor{2922}
@geindex data race

@item data race

A situation where multiple threads access the same memory location
concurrently, at least one of the accesses is a write, and the threads
do not use any synchronization to control their access.  Data races
lead to @ref{5d4d,,non-deterministic} behavior and can cause data corruption.
Proper use of @ref{2920,,locks} and other @ref{5d4e,,synchronization primitives} prevents data races.  Note that data races
can only happen in native code, but that @ref{5d4f,,native code} might be
exposed in a Python API.  See also @ref{2921,,race condition} and
@ref{5d50,,thread-safe}.
@anchor{glossary term-deadlock}@anchor{5d51}
@geindex deadlock

@item deadlock

A situation in which two or more tasks (threads, processes, or coroutines)
wait indefinitely for each other to release resources or complete actions,
preventing any from making progress.  For example, if thread A holds lock
1 and waits for lock 2, while thread B holds lock 2 and waits for lock 1,
both threads will wait indefinitely.  In Python this often arises from
acquiring multiple locks in conflicting orders or from circular
join/await dependencies.  Deadlocks can be avoided by always acquiring
multiple @ref{2920,,locks} in a consistent order.  See also
lock and @ref{5d52,,reentrant}.
@anchor{glossary term-decorator}@anchor{b18}
@geindex decorator

@item decorator

Μια συνάρτηση που επιστρέφει μια άλλη συνάρτηση, συνήθως εφαρμόζεται ως μετασχηματισμός συνάρτησης χρησιμοποιώντας την @code{@@wrapper} σύνταξη. Συνηθισμένα παραδείγματα για τους decorators είναι @ref{69a,,classmethod()} και @ref{666,,staticmethod()}.

Η σύνταξη του decorator είναι απλώς καλλωπιστική, οι ακόλουθοι δύο ορισμοί συναρτήσεων είναι σημασιολογικά ισοδύναμοι:

@example
def f(arg):
    ...
f = staticmethod(f)

@@staticmethod
def f(arg):
    ...
@end example

Η ίδια έννοια υπάρχει για τις κλάσεις, αλλά χρησιμοποιείται λιγότερο συχνά εκεί. Βλ. την τεκμηρίωση για @ref{2206,,function definitions} και @ref{167c,,class definitions} για περισσότερα σχετικά με τους decorators.
@anchor{glossary term-descriptor}@anchor{21f}
@geindex descriptor

@item descriptor

Κάθε αντικείμενο που ορίζει τις μεθόδους @ref{188a,,__get__()}, @ref{25aa,,__set__()}, ή @ref{1b64,,__delete__()}. Όταν ένα χαρακτηριστικό κλάσης είναι descriptor, η ειδική δεσμευτική του συμπεριφορά ενεργοποιείται κατά την αναζήτηση χαρακτηριστικών. Κανονικά, χρησιμοποιώντας `a.b' για να λάβετε, να ορίσετε ή να διαγράψετε ένα χαρακτηριστικό αναζητά το αντικείμενο με το όνομα `b' στο λεξικό της κλάσης για `a', αλλά εάν το `b' είναι descriptor, καλείται η αντίστοιχη μέθοδος descriptor. Η κατανόηση των descriptors είναι το κλειδί για την καλύτερη κατανόηση της Python γιατί αυτό αποτελεί την βάση για πολλά χαρακτηριστικά όπως συναρτήσεις, μεθόδους, ιδιότητες, μέθοδοι κλάσης στατικές μέθοδοι, και αναφορά σε σούπερ κλάσεις.

Για περισσότερες πληροφορίες αναφορικά με τις μεθόδους των descriptors, βλ. see @ref{100d,,Υλοποίηση Περιγραφέων} ή το @ref{188f,,Πρακτικός οδηγός για τη χρήση του Descriptor}.
@anchor{glossary term-dictionary}@anchor{25ca}
@geindex λεξικό

@item λεξικό

Ένα προσεταιριστικός πίνακα, όπου αυθαίρετα κλειδιά αντιστοιχίζονται σε τιμές. Τα κλειδιά μπορεί να είναι οποιοδήποτε αντικείμενο με μεθόδους @ref{ec1,,__hash__()} και @ref{ec0,,__eq__()}. Ονομάζεται ως hash στο Perl.
@anchor{glossary term-dictionary-comprehension}@anchor{5d53}
@geindex κατανόηση λεξικού

@item κατανόηση λεξικού

Ένα συμπαγής τρόπος για να επεξεργαστείτε όλα ή μέρος των στοιχείων σε ένα επαναληπτικό και να επιστραφεί ένα με λεξικό με τα αποτελέσματα. @code{results = @{n: n ** 2 for n in range(10)@}} δημιουργεί ένα λεξικό που περιέχει το κλειδί @code{n} που αντιστοιχίζεται με την τιμή @code{n ** 2}. Βλ. @ref{9ce,,Displays for lists@comma{} sets and dictionaries}.
@anchor{glossary term-dictionary-view}@anchor{2ba1}
@geindex όψη λεξικού

@item όψη λεξικού

Τα αντικείμενα που επιστρέφονται από @ref{bad,,dict.keys()}, @ref{bae,,dict.values()}, και @ref{baf,,dict.items()} καλούνται όψεις λεξικού. Αυτές παρέχουν μια δυναμική όψη των των εγγραφών του λεξικού, που σημαίνει ότι όταν το λεξικό μεταβάλλεται, η όψη αντικατοπτρίζει αυτές τις αλλαγές. Για να αναγκάσετε την όψη λεξικού να γίνει μια πλήρης λίστα χρησιμοποιήστε το @code{list(dictview)}.  Βλ. @ref{289e,,Αντικείμενα όψης λεξικού}.
@anchor{glossary term-docstring}@anchor{24dd}
@geindex docstring

@item docstring

Μια literal συμβολοσειρά που εμφανίζεται ως η πρώτη έκφραση σε μια κλάση, συνάρτηση ή module. Ενώ αγνοείται κατά την εκτέλεση της σουίτας, αναγνωρίζεται από τον μεταγλωττιστή και τοποθετείται στο χαρακτηριστικό @ref{cf4,,__doc__} της κλάσης, της συνάρτησης ή του module που περικλείει.  Δεδομένου ότι είναι διαθέσιμο μέσω ενδοσκόπησης, το κανονικό μέρος για την τεκμηρίωση του αντικειμένου.
@anchor{glossary term-duck-typing}@anchor{5d45}
@geindex duck-typing

@item duck-typing

Ένα στυλ προγραμματισμού που δεν εξετάζει τον τύπο ενός αντικειμένου για να προσδιορίσει αν έχει τη σωστή διεπαφή” αντίθετα, η μέθοδος ή το χαρακτηριστικό καλείται απλώς ή χρησιμοποιείται («If it looks like a duck and quacks like a duck, it must be a duck.») Δίνοντας έμφαση στις διεπαφές και όχι σε συγκεκριμένους τύπους, ο καλά σχεδιασμένος κώδικας βελτιώνει την ευελιξία του επιτρέποντας την πολυμορφική υποκατάσταση. Ο τύπος duck-typing αποφεύγει δοκιμές χρησιμοποιώντας @ref{186,,type()} ή @ref{2ef,,isinstance()}. (Σημείωση, ωστόσο, ότι ο τύπος πάπιας `duck-typing' μπορεί να συμπληρωθεί με @ref{155f,,abstract base classes}.) Αντί αυτού, συνήθως χρησιμοποιεί δοκιμές @ref{8e2,,hasattr()} ή προγραμματισμό @ref{329e,,EAFP}.
@anchor{glossary term-dunder}@anchor{5d54}
@geindex dunder

@item dunder

Ένας ανεπίσημος συντομογραφικός όρος για το «double underscore», που χρησιμοποιείται όταν μιλάμε για μια @ref{1e57,,special method}. Για παράδειγμα, @code{__init__} προφέρεται συχνά ως «dunder init».
@anchor{glossary term-EAFP}@anchor{329e}
@geindex EAFP

@item EAFP

Πιο εύκολο να ζητήσεις συγχώρεση παρά άδεια.  Αυτό το κοινό στυλ προγραμματισμού σε Python προϋποθέτει την ύπαρξη έγκυρων κλειδιών ή χαρακτηριστικών και συλλαμβάνει εξαιρέσεις εάν η υπόθεση αποδεχθεί εσφαλμένη. Αυτό το καθαρό και γρήγορο στυλ χαρακτηρίζεται από την παρουσία πολλών δηλώσεων @ref{ad6,,try} και @ref{447,,except}. Η τεχνική έρχεται σε αντίθεση με το στυλ που είναι @ref{5d55,,LBYL} κοινό σε πολλές άλλες γλώσσες, όπως η C.
@anchor{glossary term-evaluate-function}@anchor{473c}
@geindex αξιολόγηση συνάρτησης

@item αξιολόγηση συνάρτησης

Μια συνάρτηση που μπορεί να κληθεί για να αξιολογήσει ένα αδρανές χαρακτηριστικό ενός αντικειμένου, όπως η τιμή των ψευδωνύμων τύπου που δημιουργούνται με την πρόταση @ref{85a,,type}.
@anchor{glossary term-expression}@anchor{25c4}
@geindex έκφραση

@item έκφραση

Ένα κομμάτι σύνταξης που μπορεί να αξιολογηθεί σε κάποια τιμή. Με άλλα λόγια, μια έκφραση είναι μια συσσώρευση στοιχείων έκφρασης όπως κυριολεξία, ονόματα, πρόσβαση χαρακτηριστικών, τελεστές ή κλήσεις συναρτήσεων που όλες επιστρέφουν μια τιμή. Σε αντίθεση με πολλές άλλες γλώσσες, δεν είναι όλες οι γλωσσικές δομές εκφράσεις. Υπάρχουνε επίσης @ref{2e17,,statement}s που δεν μπορούν να χρησιμοποιηθούν ως εκφράσεις, όπως το @ref{1b86,,while}.  Οι αναθέσεις τιμών είναι επίσης δηλώσεις όχι εκφράσεις.
@anchor{glossary term-extension-module}@anchor{2442}
@geindex module επέκτασης

@item module επέκτασης

Ένα module γραμμένο σε C ή C++, που χρησιμοποιείται από το C API της Python για να αλληλεπιδράσουν με τον πυρήνα και με τον κώδικα του χρήστη.
@anchor{glossary term-f-string}@anchor{858}
@geindex f-string

@item f-string@anchor{glossary term-f-strings}@anchor{5d56}
@geindex f-strings

@itemx f-strings

Οι κυριολεκτικές συμβολοσειρές χρησιμοποιούνται με πρόθεμα @code{'f'} ή @code{'F'} ονομάζονται συνήθως «f-strings» που είναι συντομογραφία του @ref{43a,,formatted string literals}. Βλ. επίσης 
@geindex Python Enhancement Proposals; PEP 498
PEP 498@footnote{https://peps.python.org/pep-0498/}.
@anchor{glossary term-file-object}@anchor{156c}
@geindex αντικείμενο αρχείου

@item αντικείμενο αρχείου

Ένα αντικείμενο που εκθέτει ένα API προσανατολισμένο σε αρχείο (με μεθόδους όπως @code{read()} ή @code{write()}) σε έναν υποκείμενο πόρο. Ανάλογα με τον τρόπο που δημιουργήθηκε, ένα αντικείμενο αρχείου μπορεί να μεσολαβήσει στην πρόσβαση σε ένα πραγματικό αρχείο στο δίσκο ή σε άλλο τύπο συσκευής αποθήκευσης ή επικοινωνίας (για παράδειγμα τυπική είσοδος/ έξοδος, in-memory buffers, sockets, pipes, κλπ.). Αντικείμενο αρχείου ονομάζονται επίσης `file-like objects' ή `streams'.

Στην πραγματικότητα υπάρχουν τρεις κατηγορίες αντικειμένων αρχείου raw @ref{225d,,δυαδικά αρχεία}, buffered δυαδικά αρχεία και @ref{225c,,αρχεία κειμένου}. Οι διεπαφές τους ορίζονται στην ενότητα @ref{82,,io}. Ο κανονικός τρόπος για να δημιουργήσετε ένα αντικείμενο αρχείου είναι χρησιμοποιώντας την συνάρτηση @ref{32b,,open()}.
@anchor{glossary term-file-like-object}@anchor{19b1}
@geindex αντικείμενο που μοιάζει με αρχείο

@item αντικείμενο που μοιάζει με αρχείο

Ένα συνώνυμο με το @ref{156c,,file object}.
@anchor{glossary term-filesystem-encoding-and-error-handler}@anchor{948}
@geindex κωδικοποίηση συστήματος αρχείων και χειριστής σφαλμάτων

@item κωδικοποίηση συστήματος αρχείων και χειριστής σφαλμάτων

Η κωδικοποίηση και ο χειριστής σφαλμάτων χρησιμοποιείται από την Python για την αποκωδικοποίηση των bytes από το λειτουργικό σύστημα και την κωδικοποίηση σε Unicode για το λειτουργικό σύστημα.

Η κωδικοποίηση συστήματος αρχείων μπορεί να εγγυηθεί την επιτυχημένη αποκωδικοποίηση όλων των bytes κάτω από 128. Εάν η κωδικοποίηση συστήματος αρχείων δεν παρέχει αυτήν την εγγύηση, οι συναρτήσεις API μπορούν να εγείρουν ένα @ref{675,,UnicodeError}.

Οι συναρτήσεις @ref{1017,,sys.getfilesystemencoding()} και @ref{10a3,,sys.getfilesystemencodeerrors()} μπορούν να χρησιμοποιηθούν για να λάβετε την κωδικοποίηση του συστήματος αρχείων και του χειριστή σφαλμάτων.

Ο @ref{948,,filesystem encoding and error handler} διαμορφώνονται κατά την εκκίνηση της Python από τη συνάρτηση @ref{b6f,,PyConfig_Read()} βλ. @ref{62e,,filesystem_encoding} και @ref{62f,,filesystem_errors} μέλη του @ref{60b,,PyConfig}.

Βλ. επίσης το @ref{74d,,locale encoding}.
@anchor{glossary term-finder}@anchor{263e}
@geindex finder

@item finder

Ένα αντικείμενο που προσπαθεί να βρει το @ref{1c30,,loader} για ένα module που εισήχθη.

Υπάρχουν δύο τύποι finder: @ref{1418,,finders μετα διαδρομής} για χρήση με @ref{10e3,,sys.meta_path}, και @ref{1419,,finders εισόδου διαδρομής} για χρήση με @ref{13cd,,sys.path_hooks}.

Βλ. @ref{263c,,Finders και loaders} και @ref{7a,,importlib} για περισσότερες λεπτομέρειες.
@anchor{glossary term-floor-division}@anchor{d10}
@geindex ακέραια διαίρεση

@item ακέραια διαίρεση

Η μαθηματική διαίρεση που στρογγυλοποιεί προς τα κάτω στον κοντινότερο ακέραιο. Ο τελεστής ακέραιας διαίρεσης είναι @code{//}. Για παράδειγμα, η έκφραση @code{11 // 4} αξιολογείται σε @code{2} σε αντίθεση με την τιμή @code{2.75} που επιστρέφεται από την διαίρεση με υποδιαστολή. Σημείωση ότι @code{(-11) // 4} κάνει @code{-3} επειδή αυτή είναι η στρογγυλοποίηση `προς τα κάτω' του @code{-2.75}. Βλ. 
@geindex Python Enhancement Proposals; PEP 238
PEP 238@footnote{https://peps.python.org/pep-0238/}.
@anchor{glossary term-free-threading}@anchor{487}
@geindex δωρεάν νήμα

@item δωρεάν νήμα

Ένα μοντέλο νημάτων όπου πολλά νήματα μπορούν να εκτελούν Python bytecode ταυτόχρονα μέσα στον ίδιο διερμηνέα.  Αυτό έρχεται σε αντίθεση με το @ref{685,,global interpreter lock}, το οποίο επιτρέπει σε ένα μόνο νήμα να εκτελεί Python bytecode κάθε φορά.  Δείτε το 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}.
@anchor{glossary term-free-threaded-build}@anchor{198}
@geindex free-threaded build

@item free-threaded build

A build of @ref{ae3,,CPython} that supports @ref{487,,free threading},
configured using the @ref{6a5,,--disable-gil} option before compilation.

See @ref{2919,,Python support for free threading}.
@anchor{glossary term-free-variable}@anchor{261e}
@geindex δωρεάν μεταβλητή

@item δωρεάν μεταβλητή

Τυπικά, όπως ορίζεται στο @ref{261b,,language execution model}, μια ελεύθερη μεταβλητή είναι οποιαδήποτε μεταβλητή χρησιμοποιείται σε ένα namespace που δεν είναι τοπική μεταβλητή σε εκείνο το namespace. Δείτε το @ref{1ab7,,closure variable} για παράδειγμα. Πρακτικά, λόγω του ονόματος του χαρακτηριστικού @ref{2538,,codeobject.co_freevars}, ο όρος χρησιμοποιείται επίσης μερικές φορές ως συνώνυμο της closure variable.
@anchor{glossary term-function}@anchor{26ae}
@geindex συνάρτηση

@item συνάρτηση

Μια σειρά από δηλώσεις που επιστρέφουν κάποια τιμή σε αυτόν που την κάλεσε. Σε αυτές μπορούν να περαστούν κανένα ή περισσότερα @ref{867,,ορίσματα} που μπορεί να χρησιμοποιηθεί για την εκτέλεση. Βλ. επίσης τις ενότητες @ref{253c,,parameter}, @ref{1a8c,,method}, και the @ref{2206,,Function definitions}.
@anchor{glossary term-function-annotation}@anchor{2207}
@geindex συνάρτηση annotation

@item συνάρτηση annotation

Ένας @ref{409,,annotation} μιας παραμέτρου συνάρτησης ή μιας τιμής επιστροφής.

Οι συναρτήσεις annotations συχνά χρησιμοποιούνται για @ref{25c1,,υποδείξεις τύπου}: για παράδειγμα, αυτή η συνάρτηση αναμένεται να πάρει δύο ορίσματα @ref{326,,int} και επίσης αναμένεται να έχει μία επιστρεφόμενη τιμή @code{int}:

@example
def sum_two_numbers(a: int, b: int) -> int:
   return a + b
@end example

Η σύνταξη συνάρτησης annotation αναλύεται στην ενότητα @ref{2206,,Function definitions}.

Βλ. @ref{110a,,variable annotation} και 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}, που περιγράφει αυτή την λειτουργικότητα. Επίσης βλ. @ref{bb6,,Annotations Best Practices} για τις καλύτερες πρακτικές δουλεύοντας με annotations.
@anchor{glossary term-__future__}@anchor{1166}
@geindex __future__

@item __future__

Ένα @ref{670,,future statement}, @code{from __future__ import <feature>}, καθοδηγεί τον μεταγλωττιστή να μεταγλωττίσει το τρέχον module χρησιμοποιώντας σύνταξη ή σημασιολογία που θα γίνει η τυπική σε μελλοντική έκδοση της Python. Το module @ref{0,,__future__} τεκμηριώνει τις πιθανές τιμές του `feature'. Με την εισαγωγή αυτής της λειτουργικής μονάδας και την αξιολόγηση των μεταβλητών της, μπορείτε να δείτε πότε μια νέα δυνατότητα προστέθηκε για πρώτη φορά στην γλώσσα και πότε θα γίνει (ή έγινε) η προεπιλογή:

@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{19de}
@geindex συλλογή απορριμάτων

@item συλλογή απορριμάτων

Η διαδικασία απελευθέρωσης της μνήμης όταν δεν χρησιμοποιείται άλλο.  Η Python εκτελεί συλλογή απορριμάτων μέσω καταμέτρησης αναφορών και ενός κυκλικού συλλέκτη σκουπιδιών που είναι σε θέση να ανιχνεύει και να σπάει τους κύκλους αναφοράς. Ο συλλέκτης απορριμάτων μπορεί να ελεγχθεί χρησιμοποιώντας το module @ref{63,,gc}.

@geindex generator
@anchor{glossary term-generator}@anchor{1409}
@geindex generator

@item generator

Μια συνάρτηση που επιστρέφει ένα @ref{f9e,,generator iterator}.  Μοιάζει με μια κανονική συνάρτηση εκτός από το ότι περιέχει εκφράσεις @ref{d93,,yield} για την παραγωγή μιας σειράς τιμών που μπορούν να χρησιμοποιηθούν σε έναν βρόχο `for' ή που μπορούν να ανακτηθούν μία τη φορά με την συνάρτηση @ref{bb5,,next()} function.

Συνήθως αναφέρεται σε μια συνάρτηση generator, αλλά μπορεί να αναφέρεται σε έναν  `generator iterator' σε μερικά contexts. Σε περιπτώσεις όπου το επιδιωκόμενο νόημα δεν είναι σαφές, η χρήση των πλήρων όρων αποφεύγει την ασάφεια.
@anchor{glossary term-generator-iterator}@anchor{f9e}
@geindex generator iterator

@item generator iterator

Ένα αντικείμενο που δημιουργείται από μια συνάρτηση @ref{1409,,generator}.

Κάθε @ref{d93,,yield} αναστέλλει προσωρινά την επεξεργασία, θυμάται την κατάσταση εκτέλεσης (συμπεριλαμβανομένων των τοπικών μεταβλητών και των δηλώσεων δοκιμής σε εκκρεμότητα). Όταν ο `generator iterator' συνεχίσει, συνεχίζει από εκεί που σταμάτησε (σε αντίθεση με τις συναρτήσεις που ξεκινούν από την αρχή σε κάθε επίκληση).

@geindex generator έκφραση
@anchor{glossary term-generator-expression}@anchor{5d57}
@geindex generator έκφραση

@item generator έκφραση

Μια @ref{25c4,,expression} που επιστρέφει έναν @ref{6ce,,iterator}.  Μοιάζει με κανονική έκφραση που ακολουθείται από μια πρόταση @code{for} που ορίζει μια μεταβλητή βρόχου, ένα εύρος και μια προαιρετική πρόταση @code{if}. Η συνδυασμένη έκφραση δημιουργεί τιμές για μια συνάρτηση εγκλεισμού:

@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{db4}
@geindex γενική συνάρτηση

@item γενική συνάρτηση

Μια συνάρτηση που αποτελείται από πολλαπλές συναρτήσεις που υλοποιούν την ίδια λειτουργία για διαφορετικούς τύπους. Ποια υλοποίηση πρέπει να χρησιμοποιηθεί κατά τη διάρκεια μια κλήσης καθορίζεται από τον αλγόριθμο αποστολής.

Βλ. επίσης την καταχώρηση του @ref{db5,,single dispatch}, τον decorator @ref{a2a,,functools.singledispatch()} και 
@geindex Python Enhancement Proposals; PEP 443
PEP 443@footnote{https://peps.python.org/pep-0443/}.
@anchor{glossary term-generic-type}@anchor{1d1}
@geindex γενικός τύπος

@item γενικός τύπος

Ένας @ref{1ef3,,type} που μπορεί να παραμετροποιηθεί” συνήθως μια @ref{25c9,,container class}, όπως @ref{4d9,,list} ή @ref{188,,dict}. Χρησιμοποιείται για @ref{25c1,,type hints} και @ref{409,,annotations}.

Για περισσότερες λεπτομέρειες, βλ. @ref{a9f,,generic alias types} 
@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/}, 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/}, και το module @ref{10d,,typing}.
@anchor{glossary term-GIL}@anchor{411}
@geindex GIL

@item GIL

Βλ. @ref{685,,global interpreter lock}.
@anchor{glossary term-global-interpreter-lock}@anchor{685}
@geindex global interpreter lock

@item global interpreter lock

Ο μηχανισμός που χρησιμοποιείται από τον διερμηνέα @ref{ae3,,CPython} για να διασφαλίσει ότι μόνο ένα νήμα εκτελεί Python @ref{6b3,,bytecode} κάθε φορά. Αυτό απλοποιεί την υλοποίηση CPython δημιουργώντας το μοντέλο αντικειμένου (συμπεριλαμβανομένων κρίσιμων ενσωματωμένων τύπων όπως π.χ. @ref{188,,dict}) έμμεσα ασφαλές έναντι ταυτόχρονης πρόσβασης. Το κλείδωμα ολόκληρου του διερμηνέα διευκολύνει τον διερμηνέα να είναι πολλαπλών νημάτων, εις βάρος του μεγάλου μέρους του παραλληλισμού που παρέχουν οι μηχανές πολλαπλών επεξεργαστών.

Ωστόσο, ορισμένες λειτουργικές μονάδες επέκτασης, είτε τυπικές είτε τρίτων, έχουν σχεδιαστεί έτσι ώστε να απελευθερώνουν το GIL όταν εκτελούν εργασίες εντατικών υπολογισμών όπως συμπίεση ή κατακερματισμός. Επίσης, το GIL απελευθερώνεται πάντα όταν εκτελείτε I/O.

Από την έκδοση Python 3.13, ο GIL μπορεί να απενεργοποιηθεί χρησιμοποιώντας τη ρύθμιση @ref{6a5,,--disable-gil} κατά τη διαμόρφωση της κατασκευής. Μετά την κατασκευή της Python με αυτήν με αυτήν την επιλογή, ο κώδικας πρέπει να εκτελείται με την επιλογή @ref{178,,-X gil=0} ή αφού ρυθμιστεί η μεταβλητή περιβάλλοντος 
@geindex PYTHON_GIL
@geindex μεταβλητή περιβάλλοντος; PYTHON_GIL
@ref{6a6,,PYTHON_GIL=0}. Αυτή η δυνατότητα επιτρέπει βελτιωμένη απόδοση για εφαρμογές πολλαπλών νημάτων και διευκολύνει τη χρήση των επεξεργαστών πολλαπλών πυρήνων με αποδοτικό τρόπο. Για περισσότερες λεπτομέρειες, δείτε το 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}.

Σε προηγούμενες εκδόσεις του C API της Python, μια συνάρτηση μπορεί να δηλώνει ότι απαιτεί την τήρηση του GIL για να χρησιμοποιηθεί. Αυτό αναφέρεται στην ύπαρξη μιας κατάστασης @ref{1a1,,attached thread state}.
@anchor{glossary term-global-state}@anchor{5d58}
@geindex global state

@item global state

Data that is accessible throughout a program, such as module-level
variables, class variables, or C static variables in @ref{2442,,extension modules}.  In multi-threaded programs, global state shared
between threads typically requires synchronization to avoid
@ref{2921,,race conditions} and
@ref{2922,,data races}.
@anchor{glossary term-hash-based-pyc}@anchor{5d59}
@geindex hash-based pyc

@item hash-based pyc

Ένα αρχείο κρυφής μνήμης `bytecode' που χρησιμοποιεί τον κατακερματισμό και όχι τον χρόνο τροποποίησης του αντίστοιχου αρχείου προέλευσης για να προσδιορίσει την εγκυρότητα του. Βλ. @ref{9e3,,Ακύρωση cached bytecode}.
@anchor{glossary term-hashable}@anchor{183}
@geindex hashable

@item hashable

Ένα αντικείμενο είναι `hashable' εάν έχει μια τιμή κατακερματισμού που δεν αλλάζει ποτέ κατά τη διάρκεια της ζωής του (χρειάζεται μια μέθοδο @ref{ec1,,__hash__()}) , και μπορεί να συγκριθεί με άλλα αντικείμενα (χρειάζεται μια μέθοδο @ref{ec0,,__eq__()}) . Τα `hashable' αντικείμενα που συγκρίνονται ως προς την ισότητα τους πρέπει να έχουν την ίδια τιμή κατακερματισμού.

Η ύπαρξη `hashable' κάνει ένα αντικείμενο να μπορεί να χρησιμοποιηθεί ως κλειδί λεξικού και ως μέλος ενός συνόλου, επειδή αυτές οι δομές δεδομένων χρησιμοποιούν τιμές κατακερματισμού.

Τα περισσότερα από τα αμετάβλητα ενσωματωμένα αντικείμενα της Python μπορούν να κατακερματιστούν” τα μεταβλητά κοντέινερ (όπως οι λίστες ή τα λεξικά) δεν είναι” τα αμετάβλητα κοντέινερ (όπως πλειάδες και τα frozesets) μπορούν να κατακερματιστούν μόνο εάν τα στοιχεία τους είναι κατακερματισμένα. Τα αντικείμενα που είναι στιγμιότυπα κλάσεων που ορίζονται από το χρήστη μπορούν να κατακερματιστούν από προεπιλογή. Όλα συγκρίνονται άνισα εκτός από τον εαυτό τους) και η τιμή κατακερματισμού τους προέρχεται από το @ref{17c5,,id()}.
@anchor{glossary term-IDLE}@anchor{5d5a}
@geindex IDLE

@item IDLE

Ένα ολοκληρωμένο περιβάλλον ανάπτυξης και μάθησης για την Python. @ref{13be,,IDLE — Python editor and shell} είναι ένα βασικό περιβάλλον επεξεργασίας και διερμηνέα που συνοδεύεται από την τυπική διανομή της Python.
@anchor{glossary term-immortal}@anchor{398}
@geindex Αθάνατο

@item Αθάνατο

`Αθάνατα αντικείμενα' είναι μια λεπτομέρεια υλοποίησης της CPython που εισήχθη στην 
@geindex Python Enhancement Proposals; PEP 683
PEP 683@footnote{https://peps.python.org/pep-0683/}.

Εάν ένα αντικείμενο είναι αθάνατο, ο @ref{2c5,,reference count} του δεν τροποποιείται, και επομένως δεν εκχωρείται ποτέ ενώ εκτελείται ο διερμηνέας. Για παράδειγμα, @ref{fcc,,True} και @ref{a65,,None} είναι αθάνατα στην CPython.

Τα αθάνατα αντικείμενα μπορούν να αναγνωριστούν μέσω της @ref{517,,sys._is_immortal()}, ή μέσω της @ref{5f0,,PyUnstable_IsImmortal()} στο C API.
@anchor{glossary term-immutable}@anchor{181}
@geindex immutable

@item immutable

An object with a fixed value.  Immutable objects include numbers, strings and
tuples.  Such an object cannot be altered.  A new object has to
be created if a different value has to be stored.  They play an important
role in places where a constant hash value is needed, for example as a key
in a dictionary.  Immutable objects are inherently @ref{5d50,,thread-safe}
because their state cannot be modified after creation, eliminating concerns
about improperly synchronized @ref{5d4b,,concurrent modification}.
@anchor{glossary term-import-path}@anchor{2640}
@geindex εισαγόμενο path

@item εισαγόμενο path

Μια λίστα από τοποθεσίες (ή @ref{264e,,καταχωρίσεις διαδρομής}) που μπορούν να αναζητηθούν @ref{2643,,path based finder} για να εισαχθούν modules. Κατά την διαδικασία εισαγωγής, αυτή η λίστα με τοποθεσίες συνήθως έρχεται από @ref{194,,sys.path}, αλλά για τα υποπακέτα μπορεί επίσης να έρθει από το χαρακτηριστικό του πακέτου γονέα @code{__path__}.
@anchor{glossary term-importing}@anchor{2632}
@geindex εισαγωγή

@item εισαγωγή

Η διαδικασία κατά την οποία ο κώδικας της Python σε ένα module είναι διαθέσιμη στον κώδικα Python ενός άλλου module.
@anchor{glossary term-importer}@anchor{263f}
@geindex εισαγωγέας

@item εισαγωγέας

Ένα αντικείμενο μπορεί και να αναζητεί και να φορτώνει ένα module” και ένα @ref{263e,,finder} και @ref{1c30,,loader} αντικείμενο.
@anchor{glossary term-index}@anchor{25d8}
@geindex index

@item index

A numeric value that represents the position of an element in
a @ref{8ff,,sequence}.

In Python, indexing starts at zero.
For example, @code{things[0]} names the `first' element of @code{things};
@code{things[1]} names the second one.

In some contexts, Python allows negative indexes for counting from the
end of a sequence, and indexing using @ref{26a5,,slices}.

See also @ref{5d5b,,subscript}.
@anchor{glossary term-interactive}@anchor{451}
@geindex διαδραστικός

@item διαδραστικός

Η Python έχει έναν διαδραστικό διερμηνέα όπου σημαίνει ότι μπορείς να εισάγεις δηλώσεις και εκφράσεις στην εισαγωγή εντολών του διερμηνέα, εκτελώντας τες άμεσα και εμφανίζοντας τα αποτελέσματα. Απλώς εκκινήστε την @code{python} χωρίς ορίσματα (πιθανώς επιλέγοντας το από το κύριο μενού του υπολογιστή σας). Αποτελεί έναν αποδοτικό τρόπο για να δοκιμάστε νέες ιδέες ή να εξετάστε modules και πακέτα (θυμηθείτε @code{help(x)}). Για περισσότερα σχετικά με τη διαδραστική λειτουργία, δείτε @ref{6a0,,Διαδραστική Λειτουργία}.
@anchor{glossary term-interpreted}@anchor{5d5c}
@geindex interpreted

@item interpreted

Η Python είναι μια interpreted γλώσσα, σε αντίθεση με μια μεταγλωττισμένη, αν και η διάκριση μπορεί να είναι και θολή λόγω της παρουσία του bytecode μεταγλωττιστή. Αυτό σημαίνει ότι τα αρχεία προέλευσης μπορούν να εκτελεστούν απευθείας χωρίς να δημιουργηθεί ρητά ένα εκτελέσιμο αρχείο που στην συνέχεια εκτελείται. Οι interpreted γλώσσες συνήθως έχουν μικρότερο κύκλο ανάπτυξης/ εντοπισμού σφαλμάτων από τις μεταγλωττισμένες, αν και τα προγράμματά τους γενικά εκτελούνται πιο αργά. Βλ. επίσης @ref{451,,interactive}.
@anchor{glossary term-interpreter-shutdown}@anchor{1a0}
@geindex τερματισμός λειτουργίας διερμηνέα

@item τερματισμός λειτουργίας διερμηνέα

Όταν ζητείται τερματισμός λειτουργίας, ο διερμηνέας της Python εισέρχεται σε μια ειδική φάση όπου απελευθερώνει σταδιακά όλους τους διατιθέμενους πόρους, όπως λειτουργικές μονάδες και πολλαπλές κρίσιμες εσωτερικές δομές.  Επίσης πραγματοποιεί αρκετές κλήσεις στο @ref{19de,,συλλέκτης σκουπιδιών}. Αυτό μπορεί να ενεργοποιήσει την εκτέλεση κώδικα σε καταστροφείς που ορίζονται από το χρήστη ή σε callbacks ασθενούς ανταποκρίσεις. Ο κώδικας που εκτελείται κατά τη φάση τερματισμού λειτουργίας μπορεί να συναντήσει διάφορες εξαιρέσεις, καθώς οι πόροι στους οποίους βασίζεται ενδέχεται να μην λειτουργούν πλέον (συνήθη παραδείγματα είναι οι λειτουργικές μονάδες βιβλιοθήκης ή ο μηχανισμός ειδοποιήσεων).

Ο βασικός λόγος τερματισμού λειτουργίας του διερμηνέα είναι ότι το @code{__main__} module ή ολοκληρώθηκε η εκτέλεση του κώδικα που έτρεχε.
@anchor{glossary term-iterable}@anchor{15ce}
@geindex iterable

@item iterable

Ένα αντικείμενο ικανό να επιστρέψει τα μέλη του ένα κάθε φορά. Παραδείγματα iterables περιλαμβάνουν όλους του τύπους ακολουθιών (όπως @ref{4d9,,list}, @ref{1df,,str}, και @ref{1ce,,tuple}) και μερικούς τύπους μη ακολουθίας όπως @ref{188,,dict}, @ref{156c,,αντικείμενο αρχείου}, και αντικείμενα οποιονδήποτε κλάσεων που μπορούν να οριστούν με μια μέθοδο @ref{102d,,__iter__()} ή με μία μέθοδο @ref{787,,__getitem__()} που υλοποιεί τη σημασιολογία @ref{8ff,,sequence}.

Τα iterables μπορούν να χρησιμοποιηθούν σε ένα @ref{321,,for} βρόχο και σε πολλά άλλα σημεία όπου χρειάζεται μια ακολουθία (@ref{43f,,zip()}, @ref{43e,,map()}, …). Όταν ένα iterable αντικείμενο μεταβιβάζεται ως όρισμα στην ενσωματωμένη συνάρτηση @ref{bb4,,iter()}, επιστρέφει έναν iterator για αντικείμενο. Αυτός ο iterator είναι καλός για ένα πέρασμα από ένα σύνολο τιμών. Όταν χρησιμοποιείται επαναληπτικά, συνήθως δεν είναι απαραίτητο να καλέσετε το @code{iter()} ή να ασχοληθείτε μόνοι σας με αντικείμενα iterator. Η δήλωση @code{for} το κάνει αυτόματα για εσάς, δημιουργώντας μια προσωρινή μεταβλητή χωρίς όνομα για να κρατά τον iterator για την διάρκεια του βρόχου. Βλ. επίσης @ref{6ce,,iterator}, @ref{8ff,,sequence}, και @ref{1409,,generator}.
@anchor{glossary term-iterator}@anchor{6ce}
@geindex iterator

@item iterator

Ένα αντικείμενο που αντιπροσωπεύει μια ροή δεδομένων. Επαναλαμβανόμενες κλήσεις προς τη μέθοδο @ref{1672,,__next__()} του iterator (ή μεταβίβαση του στην ενσωματωμένη συνάρτηση @ref{bb5,,next()}) επιστρέφουν διαδοχικά στοιχεία στην ροή. Όταν όχι περισσότερα δεδομένα είναι διαθέσιμα εγείρεται μια εξαίρεση @ref{fba,,StopIteration}. Σε αυτό το σημείο, το αντικείμενο iterator εξαντλείται και τυχόν περαιτέρω κλήσεις στη μέθοδο @code{__next__()} απλώς απλά εγείρουν ξανά το @code{StopIteration}. Οι iterators πρέπει να έχουν μια μέθοδο @ref{229d,,__iter__()} που επιστρέφει το ίδιο το αντικείμενο iterator, έτσι ώστε κάθε iterator να είναι επίσης iterable και μπορεί να χρησιμοποιηθεί στα περισσότερα μέρη όπου γίνονται αποδεκτοί και άλλοι iterators. Μια αξιοσημείωτη εξαίρεση είναι ο κώδικας που επιχειρεί πολλαπλά περάσματα iteration. Ένα αντικείμενο κοντέινερ (όπως ένα @ref{4d9,,list}) παράγει έναν καθαρά νέο iterator κάθε φορά που κάθε φορά που μεταβιβάζεται στην συνάρτηση @ref{bb4,,iter()} ή τον χρησιμοποιείται σε έναν @ref{321,,for} βρόχο. Εάν επιχειρήσετε αυτό με έναν iterator απλώς θα επιστρέψετε το ίδιο εξαντλημένο αντικείμενο iterator που χρησιμοποιήθηκε στο προηγούμενο πέρασμα iteration , κάνοντας το να φαίνεται σαν ένα άδειο κοντέινερ.

Περισσότερες πληροφορίες μπορούν να βρεθούν στο @ref{27d0,,Τύποι Iterator}.

`Λεπτομέρεια υλοποίησης CPython:' CPython does not consistently apply the requirement that an iterator
define @ref{229d,,__iter__()}.
And also please note that @ref{487,,free-threaded}
CPython does not guarantee @ref{5d50,,thread-safe} behavior of iterator
operations.
@anchor{glossary term-key}@anchor{25d9}
@geindex key

@item key

A value that identifies an entry in a @ref{1564,,mapping}.
See also @ref{5d5b,,subscript}.
@anchor{glossary term-key-function}@anchor{11ba}
@geindex συνάρτηση key

@item συνάρτηση key

Μια συνάρτηση κλειδί ή μια συνάρτηση ταξινόμησης είναι μια δυνατότητα κλήσης που επιστρέφει μια τιμή που χρησιμοποιείται για ταξινόμηση ή διάταξη. Για παράδειγμα, @ref{19f7,,locale.strxfrm()} χρησιμοποιείται για την παραγωγή ενός κλειδιού ταξινόμησης που γνωρίζει τις συμβάσεις ταξινόμησης για συγκεκριμένες τοπικές ρυθμίσεις.

Ένα αριθμός εργαλείων στην Python δέχεται βασικές συναρτήσεις για τον έλεγχο του τρόπου με τον οποίο τα στοιχεία ταξινομούνται ή ομαδοποιούνται. Αυτά περιέχουν @ref{12b9,,min()}, @ref{12ba,,max()}, @ref{f8c,,sorted()}, @ref{f8d,,list.sort()}, @ref{11b9,,heapq.merge()}, @ref{2bb9,,heapq.nsmallest()}, @ref{2bb8,,heapq.nlargest()}, και @ref{192a,,itertools.groupby()}.

There are several ways to create a key function.  For example. the
@ref{118f,,str.casefold()} method can serve as a key function for case insensitive
sorts.  Alternatively, a key function can be built from a
@ref{1642,,lambda} expression such as @code{lambda r: (r[0], r[2])}.  Also,
@ref{11e6,,operator.attrgetter()}, @ref{e26,,operator.itemgetter()}, and
@ref{11e7,,operator.methodcaller()} are three key function constructors.  See the @ref{27d9,,Sorting HOW TO} for examples of how to create and use key functions.
@anchor{glossary term-keyword-argument}@anchor{10cc}
@geindex όρισμα keyword

@item όρισμα keyword

Βλ. @ref{867,,argument}.
@anchor{glossary term-lambda}@anchor{2dce}
@geindex lambda

@item lambda

Μια ανώνυμη ενσωματωμένη συνάρτηση που αποτελείται από μια μοναδική @ref{25c4,,expression} η οποία αξιολογείται όταν καλείται η συνάρτηση. Η σύνταξη για τη δημιουργία μιας συνάρτησης lambda είναι @code{lambda [parameters]: expression}
@anchor{glossary term-LBYL}@anchor{5d55}
@geindex LBYL

@item LBYL

Look before you leap.  Αυτό το στυλ κωδικοποίησης ελέγχει ρητά τις προϋποθέσεις πριν πραγματοποιήσει κλήσεις ή αναζητήσεις.  Αυτό το στυλ έρχεται σε αντίθεση με την προσέγγιση @ref{329e,,EAFP} και χαρακτηρίζεται από την παρουσία πολλών δηλώσεων @ref{322,,if}.

In a multi-threaded environment, the LBYL approach can risk introducing a
@ref{2921,,race condition} between «the looking» and «the leaping».  For example,
the code, @code{if key in mapping: return mapping[key]} can fail if another
thread removes `key' from `mapping' after the test, but before the lookup.
This issue can be solved with @ref{2920,,locks} or by using the
@ref{329e,,EAFP} approach.  See also @ref{5d50,,thread-safe}.
@anchor{glossary term-lexical-analyzer}@anchor{2483}
@geindex λεξικός αναλυτής

@item λεξικός αναλυτής

Επίσημη ονομασία για τον `tokenizer' · βλ. @ref{2479,,token}.
@anchor{glossary term-list}@anchor{5d5d}
@geindex λίστα

@item λίστα

Ένα ενσωματωμένο Python @ref{8ff,,sequence}.  Παρά το όνομα του, μοιάζει περισσότερο με έναν πίνακα σε άλλες γλώσσες παρά με μια συνδεδεμένη λίστα, καθώς η πρόσβαση στα στοιχεί είναι `O'(1).
@anchor{glossary term-list-comprehension}@anchor{abb}
@geindex list comprehension

@item list comprehension

Ένα συμπαγής τρόπος για να επεξεργαστείτε όλα ή μέρος των στοιχείων σε μια ακολουθία και να επιστρέψετε μια λίστα με τα αποτελέσματα. @code{result = ['@{:#04x@}'.format(x) for x in range(256) if x % 2 == 0]} δημιουργεί μια λίστα συμβολοσειρών που περιέχουν ζυγούς δεκαεξαδικούς αριθμούς (0x..) στο εύρος από 0 έως 255. Η πρόταση @ref{322,,if} είναι προαιρετική. Εάν παραλειφθεί, όλα τα στοιχεία στο @code{range(256)} υποβάλλονται σε επεξεργασία.
@anchor{glossary term-lock}@anchor{2920}
@geindex lock

@item lock

A @ref{5d4e,,synchronization primitive} that allows only one thread at a
time to access a shared resource.  A thread must acquire a lock before
accessing the protected resource and release it afterward.  If a thread
attempts to acquire a lock that is already held by another thread, it
will block until the lock becomes available.  Python’s @ref{f6,,threading}
module provides @ref{1a10,,Lock} (a basic lock) and
@ref{2df,,RLock} (a @ref{5d52,,reentrant} lock).  Locks are used
to prevent @ref{2921,,race conditions} and ensure
@ref{5d50,,thread-safe} access to shared data.  Alternative design patterns
to locks exist such as queues, producer/consumer patterns, and
thread-local state. See also @ref{5d51,,deadlock}, and reentrant.
@anchor{glossary term-lock-free}@anchor{292e}
@geindex lock-free

@item lock-free

An operation that does not acquire any @ref{2920,,lock} and uses atomic CPU
instructions to ensure correctness. Lock-free operations can execute
concurrently without blocking each other and cannot be blocked by
operations that hold locks. In @ref{487,,free-threaded}
Python, built-in types like @ref{188,,dict} and @ref{4d9,,list} provide
lock-free read operations, which means other threads may observe
intermediate states during multi-step modifications even when those
modifications hold the @ref{2927,,per-object lock}.
@anchor{glossary term-loader}@anchor{1c30}
@geindex loader

@item loader

Ένα αντικείμενο που φορτώνει ένα module. Πρέπει να ορίζει τις μεθόδους @code{exec_module()} και @code{create_module()} για την υλοποίηση της διεπαφής @ref{1275,,Loader}. Ένας loader συνήθως επιστρέφεται με ένα @ref{263e,,finder}. Δείτε επίσης:


@itemize *

@item 
@ref{263c,,Finders και loaders}

@item 
@ref{1275,,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{74d}
@geindex τοπική κωδικοποίηση

@item τοπική κωδικοποίηση

Στο Unix, είναι η κωδικοποίηση της τοπική ρύθμισης LC_CTYPE. Μπορεί να ρυθμιστεί με @ref{231,,locale.setlocale(locale.LC_CTYPE@comma{} new_locale)}.

Στα Windows, είναι η code page ANSI (π.χ. @code{"cp1252"}).

Στο Android και το VxWorks, η Python χρησιμοποιεί το @code{"utf-8"} ως τοπική κωδικοποίηση.

@ref{a45,,locale.getencoding()} μπορεί να χρησιμοποιηθεί για την ανάκτηση της τοπικής κωδικοποίησης.

Βλ. επίσης το @ref{948,,filesystem encoding and error handler}.
@anchor{glossary term-magic-method}@anchor{48be}
@geindex μαγική μέθοδος

@item μαγική μέθοδος

@geindex magic;μέθοδος

Ένα άτυπο συνώνυμο για @ref{1e57,,special method}.
@anchor{glossary term-mapping}@anchor{1564}
@geindex mapping

@item mapping

Ένα αντικείμενο κοντέινερ που υποστηρίζει αυθαίρετες αναζητήσεις κλειδιών και υλοποιεί τις μεθόδους που καθορίζονται στο @ref{c9c,,collections.abc.Mapping} ή @ref{1459,,collections.abc.MutableMapping} @ref{c4e,,abstract base classes}. Τα παραδείγματα περιλαμβάνουν @ref{188,,dict}, @ref{1565,,collections.defaultdict}, @ref{9d5,,collections.OrderedDict} και @ref{204,,collections.Counter}.
@anchor{glossary term-meta-path-finder}@anchor{1418}
@geindex meta path finder

@item meta path finder

Ένας @ref{263e,,finder} που επιστράφηκε με αναζήτηση στο @ref{10e3,,sys.meta_path}. Οι finders μετα-διαδρομής σχετίζονται, αλλά διαφέρουν από τα @ref{1419,,finders entry διαδρομής}.

Βλ. @ref{c44,,importlib.abc.MetaPathFinder} για τις μεθόδους που υλοποιούν οι meta path finders.
@anchor{glossary term-metaclass}@anchor{25c5}
@geindex μετα-κλάση

@item μετα-κλάση

Η κλάση μιας κλάσης. Οι ορισμοί κλάσης δημιουργούν ένα όνομα κλάσης, ένα λεξικό κλάσης και μια λίστα βασικών κλάσεων. Η μετα-κλάση είναι υπεύθυνη για την απόκτηση αυτών των τριών ορισμάτων και την δημιουργία της κλάσης. Οι περισσότερες αντικειμενοστρεφείς γλώσσες προγραμματισμού παρέχουν μια προεπιλεγμένη υλοποίηση. Αυτό που κάνει την Python ξεχωριστή είναι ότι είναι δυνατή η δημιουργία προσαρμοσμένων μετακλάσεων. Οι περισσότεροι χρήστες δεν χρειάζονται ποτέ αυτό το εργαλείο, αλλά όταν παραστεί ανάγκη, αυτό το εργαλείο, οι μετα-κλάσεις μπορούν να παρέχουν ισχυρές, κομψές λύσεις. Έχουν χρησιμοποιηθεί για την καταγραφή πρόσβασης χαρακτηριστικών, την προσθήκη ασφάλειας νημάτων, την παρακολούθηση δημιουργίας αντικειμένων, την υλοποίηση `singletons', και πολλές άλλες εργασίες.

Περισσότερες πληροφορίες μπορούν να βρεθούν στο @ref{25b3,,Μετα-κλάσεις}.
@anchor{glossary term-method}@anchor{1a8c}
@geindex μέθοδος

@item μέθοδος

Μια συνάρτηση που ορίζεται μέσα στο σώμα μιας κλάσης.  Εάν καλείται ως χαρακτηριστικό μιας περίπτωσης αυτής της κλάσης, η μέθοδος θα λάβει αντικείμενο περίπτωσης ως πρώτο της @ref{867,,argument} (το οποίο συνήθως ονομάζεται @code{self}). Βλ. @ref{26ae,,function} και @ref{2581,,nested scope}.
@anchor{glossary term-method-resolution-order}@anchor{2784}
@geindex σειρά ανάλυσης μεθόδων

@item σειρά ανάλυσης μεθόδων

Η Σειρά Ανάλυσης Μεθόδων είναι η σειρά με την οποία οι βασικές κλάσεις αναζητούνται για ένα μέλος κατά την αναζήτησης. Βλ. @ref{184c,,The Python 2.3 Method Resolution Order} για λεπτομέρειες του αλγορίθμου που χρησιμοποιείται από τον διερμηνέα της Python από την έκδοση 2.3.
@anchor{glossary term-module}@anchor{1be7}
@geindex module

@item module

Ένα αντικείμενο που χρησιμεύει ως οργανωτική μονάδα του κώδικα της Python.  Τα modules έχουν έναν χώρο ονομάτων που περιέχει αυθαίρετα αντικείμενα Python.  Τα modules φορτώνονται στην Python με την διαδικασία @ref{2632,,importing}.

Βλ. επίσης @ref{4c1,,package}.
@anchor{glossary term-module-spec}@anchor{2554}
@geindex τεχνικές προδιαγραφές module

@item τεχνικές προδιαγραφές module

Ένα namespace που περιέχει τις πληροφορίες που σχετίζονται με την εισαγωγή που χρησιμοποιούνται για την φόρτωση ενός module. Μια περίπτωση του @ref{245d,,importlib.machinery.ModuleSpec}.

Βλ. επίσης @ref{2557,,Module specs}.
@anchor{glossary term-MRO}@anchor{1afd}
@geindex MRO

@item MRO

Βλ. @ref{2784,,method resolution order}.
@anchor{glossary term-mutable}@anchor{21d1}
@geindex mutable

@item mutable

An @ref{5d5e,,object} with state that is allowed to change during the course
of the program.  In multi-threaded programs, mutable objects that are
shared between threads require careful synchronization to avoid
@ref{2921,,race conditions}.  See also @ref{181,,immutable},
@ref{5d50,,thread-safe}, and @ref{5d4b,,concurrent modification}.
@anchor{glossary term-named-tuple}@anchor{a3d}
@geindex named tuple

@item named tuple

Ο όρος «named tuple» εφαρμόζεται για οποιονδήποτε τύπο ή κλάση που κληρονομείται από την πλειάδα και των οποίων τα στοιχεία μπορούν να ευρετηριοποιηθούν είναι προσβάσιμα χρησιμοποιώντας επώνυμα χαρακτηριστικά.  Ο τύπος ή η κλάση μπορεί να έχει και άλλα χαρακτηριστικά.

Πολλοί ενσωματωμένοι τύποι είναι named tuples, συμπεριλαμβανομένων των τιμών που επιστρέφονται από @ref{189b,,time.localtime()} και @ref{4f5,,os.stat()}. Ένα άλλο παράδειγμα είναι το @ref{1fbf,,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

Ορισμένες αναγνωρισμένες πλειάδες είναι ενσωματωμένοι τύποι (όπως τα παραπάνω παραδείγματα). Εναλλακτικά, μια αναγνωρισμένη πλειάδα μπορεί να δημιουργηθεί από έναν ορισμό κανονικής κλάσης που κληρονομεί από @ref{1ce,,tuple} και που ορίζει έγκυρα πεδία. Μια τέτοια κλάση μπορεί να είναι γραμμένη με το χέρι ή μπορεί να δημιουργηθεί κληρονομώντας το @ref{2e4,,typing.NamedTuple}, ή με την factory συνάρτηση @ref{1cf,,collections.namedtuple()}. Οι τελευταίες τεχνικές προσθέτουν επίσης μερικές επιπλέον μεθόδους που μπορεί να μην βρεθούν σε χειρόγραφες ή ενσωματωμένες πλειάδες με όνομα.
@anchor{glossary term-namespace}@anchor{222e}
@geindex namespace

@item namespace

Το μέρος όπου αποθηκεύεται μια μεταβλητή.  Τα namespaces υλοποιούνται ως λεξικά. Υπάρχουν οι τοπικοί, οι καθολικοί και οι ενσωματωμένοι namespaces καθώς και οι ένθετοι namespaces σε αντικείμενα (σε μεθόδους).  Για παράδειγμα οι συναρτήσεις @ref{32b,,builtins.open} και @ref{114b,,os.open()} διακρίνονται από τους χώρους ονομάτων τους.  Οι χώροι ονομάτων βοηθούν επίσης την αναγνωσιμότητα και τη συντηρησιμότητα καθιστώντας σαφές ποιο module υλοποιεί μια λειτουργία. Για παράδειγμα, γράφοντας @ref{1618,,random.seed()} ή @ref{f09,,itertools.islice()} καθιστά σαφές ότι αυτές οι συναρτήσεις υλοποιούνται από τα module @ref{c0,,random} και @ref{84,,itertools}, αντίστοιχα.
@anchor{glossary term-namespace-package}@anchor{52e}
@geindex πακέτο namespace

@item πακέτο namespace

Ένα @ref{4c1,,package} που χρησιμεύει μόνο ως κοντέινερ για υποπακέτα. Τα πακέτα χώρου ονομάτων μπορεί να μην έχουν φυσική αναπαράσταση και συγκεκριμένα να μην είναι σαν ένα @ref{2636,,regular package} επειδή δεν έχουν το @code{__init__.py} αρχείο.

Τα πακέτα χώρου ονομάτων επιτρέπουν σε πολλά πακέτα με δυνατότητα εγκατάστασης μεμονωμένα να έχουν ένα κοινό γονικό πακέτο.  Διαφορετικά, συνίσταται η χρήση ενός @ref{2636,,regular package}.

Για περισσότερες πληροφορίες, δείτε το 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} και το @ref{2638,,Namespace πακέτα}.

Βλ. επίσης @ref{1be7,,module}.
@anchor{glossary term-native-code}@anchor{5d4f}
@geindex native code

@item native code

Code that is compiled to machine instructions and runs directly on the
processor, as opposed to code that is interpreted or runs in a virtual
machine.  In the context of Python, native code typically refers to
C, C++, Rust or Fortran code in @ref{2442,,extension modules}
that can be called from Python.  See also extension module.
@anchor{glossary term-nested-scope}@anchor{2581}
@geindex nested scope

@item nested scope

Η δυνατότητα αναφοράς σε μια μεταβλητή σε έναν περικλειόμενο ορισμό. Για παράδειγμα μια συνάρτηση που ορίζεται μέσα σε μια άλλη συνάρτηση μπορεί να αναφέρεται σε μεταβλητές στην εξωτερική συνάρτηση. Σημειώστε ότι τα ένθετα πεδία από προεπιλογή λειτουργούν μόνο για αναφορά και όχι για εκχώρηση. Οι τοπικές μεταβλητές διαβάζονται και γράφονται στο εσωτερικό πεδίο εφαρμογής. Ομοίως, οι καθολικές μεταβλητές διαβάζουν και γράφουν στον καθολικό χώρο ονομάτων. Το @ref{164c,,nonlocal} επιτρέπει την εγγραφή σε εξωτερικά πεδία.
@anchor{glossary term-new-style-class}@anchor{2f2f}
@geindex κλάση νέου στυλ

@item κλάση νέου στυλ

Το παλιό όνομα για το είδος των κλάσεων χρησιμοποιείται πλέον για όλα τα αντικείμενα.  Σε παλιότερες εκδόσεις της Python, μόνο οι κλάσεις νέου στυλ μπορούσαν να χρησιμοποιήσουν τις νεότερες, ευέλικτες δυνατότητες της Python όπως @ref{188d,,__slots__}, descriptors, ιδιότητες @ref{f90,,__getattribute__()}, μέθοδοι κλάσης, και στατικές μέθοδοι.
@anchor{glossary term-non-deterministic}@anchor{5d4d}
@geindex non-deterministic

@item non-deterministic

Behavior where the outcome of a program can vary between executions with
the same inputs.  In multi-threaded programs, non-deterministic behavior
often results from @ref{2921,,race conditions} where the
relative timing or interleaving of threads affects the result.
Proper synchronization using @ref{2920,,locks} and other
@ref{5d4e,,synchronization primitives} helps
ensure deterministic behavior.
@anchor{glossary term-object}@anchor{5d5e}
@geindex αντικείμενο

@item αντικείμενο

Οποιαδήποτε δεδομένα με κατάσταση (χαρακτηριστικά ή τιμή) και καθορισμένη συμπεριφορά (μέθοδοι). Επίσης, η τελική βασική κλάση οποιασδήποτε @ref{2f2f,,new-style class}.
@anchor{glossary term-optimized-scope}@anchor{6ad}
@geindex βελτιστοποιημένο πεδίο ορατότητας (scope)

@item βελτιστοποιημένο πεδίο ορατότητας (scope)

Ένα πεδίο ορατότητας (scope) όπου τα ονόματα των τοπικών μεταβλητών είναι γνωστό με βεβαιότητα στον μεταγλωττιστή κατά τη μεταγλώττιση του κώδικα, επιτρέποντας τη βελτιστοποίηση της πρόσβασης για ανάγνωση και εγγραφή σε αυτά τα ονόματα. Οι τοπικοί χώροι ονομάτων για συναρτήσεις, γεννήτριες, συναρτήσεις coroutine, συμπτύξεις (comprehensions) και εκφράσεις γεννητριών βελτιστοποιούνται με αυτόν τον τρόπο. Σημείωση: οι περισσότερες βελτιστοποιήσεις του διερμηνέα εφαρμόζονται σε όλα τα πεδία ορατότητας· μόνο εκείνες που βασίζονται σε γνωστό σύνολο τοπικών και μη τοπικών μεταβλητών περιορίζονται σε βελτιστοποιημένα πεδία ορατότητας.
@anchor{glossary term-optional-module}@anchor{2347}
@geindex προαιρετικό module

@item προαιρετικό module

Ένα @ref{2442,,extension module} που αποτελεί μέρος της @ref{3d8,,standard library}, αλλά μπορεί να απουσιάζει σε ορισμένες εκδόσεις του @ref{ae3,,CPython}, συνήθως λόγω απουσίας βιβλιοθηκών τρίτων ή επειδή το module δεν είναι διαθέσιμο για μια δεδομένη πλατφόρμα.

Δείτε το @ref{2345,,Requirements for optional modules} για μια λίστα με προαιρετικά modules που απαιτούν βιβλιοθήκες τρίτων.
@anchor{glossary term-package}@anchor{4c1}
@geindex πακέτο

@item πακέτο

Ένα Python @ref{1be7,,module} που μπορεί να περιέχει submodules ή αναδρομικά, υποπακέτα. Τεχνικά, ένα πακέτο είναι μια λειτουργική μονάδα Python με ένα @code{__path__} χαρακτηριστικό.

Βλ. επίσης @ref{2636,,regular package} και @ref{52e,,namespace package}.
@anchor{glossary term-parallelism}@anchor{5d4a}
@geindex parallelism

@item parallelism

Executing multiple operations at the same time (e.g. on multiple CPU
cores).  In Python builds with the
@ref{685,,global interpreter lock (GIL)}, only one
thread runs Python bytecode at a time, so taking advantage of multiple
CPU cores typically involves multiple processes
(e.g. @ref{98,,multiprocessing}) or native extensions that release the GIL.
In @ref{487,,free-threaded} Python, multiple Python threads
can run Python code simultaneously on different cores.
@anchor{glossary term-parameter}@anchor{253c}
@geindex παράμετρος

@item παράμετρος

Μια έγκυρη οντότητα σε έναν ορισμό @ref{26ae,,function} (ή μέθοδος) που καθορίζει ένα @ref{867,,argument} (ή σε ορισμένες περιπτώσεις, ορίσματα) που μπορεί να δεχθεί η συνάρτηση. Υπάρχουν πέντε είδη παραμέτρων:


@itemize *

@item 
`λέξη-κλειδί ή θέση': καθορίζει ένα όρισμα που μπορεί να μεταβιβαστεί είτε @ref{867,,θέσεως} ή ως όρισμα λέξης-κλειδιού.  Αυτό είναι το προεπιλεγμένο είδος παραμέτρου, για παράδειγμα `foo' και `bar' στα ακόλουθα:

@example
def func(foo, bar=None): ...
@end example
@end itemize
@anchor{glossary positional-only-parameter}@anchor{e47}

@itemize *

@item 
`θέσεως μόνο': καθορίζει ένα όρισμα που μπορεί να παρέχεται μόνο από τη θέση. Οι παράμετροι μόνο θέσης μπορούν να οριστούν συμπεριλαμβάνοντας έναν χαρακτήρα @code{/} στη λίστα παραμέτρων του ορισμού συνάρτησης μετά από αυτές, για παράδειγμα `posonly1' και `posonly2' στα εξής:

@example
def func(posonly1, posonly2, /, positional_or_keyword): ...
@end example
@end itemize
@anchor{glossary keyword-only-parameter}@anchor{7a3}

@itemize *

@item 
`λέξης-κλειδί μόνο': καθορίζει ένα όρισμα που μπορεί να παρέχεται μόνο με λέξη κλειδί. Οι παράμετροι μόνο για λέξη-κλειδί μπορούν να οριστούν συμπεριλαμβάνοντας μια παράμετρο θέσης ή σκέτο @code{*} στη λίστα παραμέτρων του ορισμού συνάρτησης πριν από αυτές, για παράδειγμα `kw_only1' και `kw_only2' στα ακόλουθα:

@example
def func(arg, *, kw_only1, kw_only2): ...
@end example

@item 
`μεταβλητή θέσης': καθορίζει ότι μπορεί να παρασχεθεί μια αυθαίρετη ακολουθία ορισμάτων θέσης (επιπλέον των ορισμάτων θέσης που είναι ήδη αποδεκτά από άλλες παραμέτρους). Μια τέτοια παράμετρος μπορεί να οριστεί προσαρτώντας το όνομα της παραμέτρου με @code{*}, για παράδειγμα `args' στα ακόλουθα:

@example
def func(*args, **kwargs): ...
@end example

@item 
`μεταβλητή λέξη-κλειδί': καθορίζει ότι μπορούν να παρέχονται αυθαίρετα πολλά ορίσματα λέξης-κλειδιού (επιπλέον των ορισμάτων λέξης κλειδιού που είναι αποδεκτά από άλλες παραμέτρους).  Μια τέτοια παράμετρος μπορεί να οριστεί προσαρτώντας το όνομα της παραμέτρου με @code{**}, για παράδειγμα `kwargs' όπως παραπάνω.
@end itemize

Οι παράμετροι μπορούν να καθορίσουν τόσο τα προαιρετικά όσο και τα απαιτούμενα ορίσματα , καθώς και προεπιλεγμένες τιμές για ορισμένα προαιρετικά ορίσματα.

Βλ. επίσης την @ref{867,,argument} καταχώριση ευρετηρίου, την ερώτηση FAQ σχετικά με @ref{5c7a,,η διαφορά μεταξύ ορισμάτων και παραμέτρων}, την κλάση @ref{6e9,,inspect.Parameter}, την ενότητα @ref{2206,,Function definitions} και 
@geindex Python Enhancement Proposals; PEP 362
PEP 362@footnote{https://peps.python.org/pep-0362/}.
@anchor{glossary term-per-object-lock}@anchor{2927}
@geindex per-object lock

@item per-object lock

A @ref{2920,,lock} associated with an individual object instance rather than
a global lock shared across all objects. In @ref{487,,free-threaded} Python, built-in types like @ref{188,,dict} and
@ref{4d9,,list} use per-object locks to allow concurrent operations on
different objects while serializing operations on the same object.
Operations that hold the per-object lock prevent other locking operations
on the same object from proceeding, but do not block @ref{292e,,lock-free}
operations.
@anchor{glossary term-path-entry}@anchor{264e}
@geindex path entry

@item path entry

Μια μεμονωμένη τοποθεσία στο @ref{2640,,import path} την οποία συμβουλεύεται ο @ref{2643,,path based finder} για να βρει modules για εισαγωγή.
@anchor{glossary term-path-entry-finder}@anchor{1419}
@geindex path entry finder

@item path entry finder

Ένας @ref{263e,,finder} που επιστρέφεται από έναν καλούμενο στο @ref{13cd,,sys.path_hooks} (δηλαδή ένα @ref{2650,,path entry hook}) που ξέρει πως να εντοπίζει modules με @ref{264e,,path entry}.

Βλ. @ref{c45,,importlib.abc.PathEntryFinder} για τις μεθόδους που ο entry finder διαδρομής υλοποιεί.
@anchor{glossary term-path-entry-hook}@anchor{2650}
@geindex path entry hook

@item path entry hook

Ένα καλούμενο στη λίστα @ref{13cd,,sys.path_hooks}, το οποίο επιστρέφει ένα @ref{1419,,path entry finder} εάν ξέρει πως να βρίσκει module σε μια συγκεκριμένη @ref{264e,,path entry}.
@anchor{glossary term-path-based-finder}@anchor{2643}
@geindex path based finder

@item path based finder

Ένα από τα προεπιλεγμένα @ref{1418,,meta path finders} που αναζητά ένα @ref{2640,,import path} για modules.
@anchor{glossary term-path-like-object}@anchor{79f}
@geindex path-like αντικείμενο

@item path-like αντικείμενο

Ένα αντικείμενο που αντιπροσωπεύει ένα path συστήματος αρχείων. Ένα αντικείμενο path είναι είτε ένα αντικείμενο @ref{1df,,str} ή @ref{1c7,,bytes} που αντιπροσωπεύει ένα path ή ένα αντικείμενο που υλοποιεί το πρωτόκολλο @ref{100f,,os.PathLike}. Ένα αντικείμενο που υποστηρίζει το πρωτόκολλο @code{os.PathLike} μπορεί να μετατραπεί σε path συστήματος αρχείων @code{str} ή @code{bytes} καλώντας την συνάρτηση @ref{1011,,os.fspath()}” τα @ref{1012,,os.fsdecode()} και @ref{1013,,os.fsencode()} μπορούν να χρησιμοποιηθούν για την εγγύηση ενός αποτελέσματος @code{str} ή @code{bytes}, αντίστοιχα. Εισήχθη από τον 
@geindex Python Enhancement Proposals; PEP 519
PEP 519@footnote{https://peps.python.org/pep-0519/}.
@anchor{glossary term-PEP}@anchor{5d5f}
@geindex PEP

@item PEP

Πρόταση Βελτίωσης Python. Ένα PEP είναι ένα έγγραφο σχεδιασμού που παρέχει πληροφορίες στην κοινότητα Python ή περιγράφει μια νέα δυνατότητα για την Python ή τις διαδικασίες ή το περιβάλλον της. Τα PEP θα πρέπει να παρέχουν μια συνοπτική τεχνική προδιαγραφή και μια λογική για τα προτεινόμενα χαρακτηριστικά.

Τα PEP προορίζονται να είναι οι κύριοι μηχανισμοί για την πρόταση σημαντικών νέων χαρακτηριστικών, για τη συλλογή πληροφοριών της κοινότητας για ένα ζήτημα και για την τεκμηρίωση των αποφάσεων σχεδιασμού που έχουν εισαχθεί στην Python. Ο συγγραφέας του PEP είναι υπεύθυνος για την οικοδόμηση συναίνεσης εντός της κοινότητας και την τεκμηρίωση αντίθετων απόψεων.

Βλ. 
@geindex Python Enhancement Proposals; PEP 1
PEP 1@footnote{https://peps.python.org/pep-0001/}.
@anchor{glossary term-portion}@anchor{2639}
@geindex τμήμα

@item τμήμα

Ένα σύνολο από αρχεία σε έναν μόνο κατάλογο (ενδεχομένως αποθηκευμένο σε αρχείο `zip') που συμβάλλουν σε ένα namespace πακέτο, όπως ορίζεται στο 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}.
@anchor{glossary term-positional-argument}@anchor{10cd}
@geindex όρισμα θέσης

@item όρισμα θέσης

Βλ. @ref{867,,argument}.
@anchor{glossary term-provisional-API}@anchor{5fd}
@geindex provisional API

@item provisional API

Ένα provisional API είναι αυτό που έχει εσκεμμένα εξαιρεθεί από τις backwards εγγυήσεις συμβατότητας της τυπικής βιβλιοθήκης. Αν και δεν αναμένονται σημαντικές αλλαγές σε τέτοιες διεπαφές, εφόσον επισημαίνονται ως προσωρινές, αλλαγές μη backwards συμβατότητας (μέχρι και κατάργηση της διεπαφής) μπορεί να προκύψουν εάν κριθεί απαραίτητο από τους βασικούς προγραμματιστές. Τέτοιες αλλαγές δεν θα γίνουν άσκοπα – θα συμβούν μόνο εάν αποκαλυφθούν σοβαρά θεμελιώδη ελαττώματα που παραλείφθηκαν πριν από τη συμπερίληψη του API.

Ακόμη και για provisional API, οι μη backwards συμβατές αλλαγές θεωρούνται «λύση έσχατης ανάγκης»- θα εξακολουθεί να γίνεται κάθε προσπάθεια για να βρεθεί μια λύση backwards συμβατή σε τυχόν εντοπισμένα προβλήματα.

Αυτή η διαδικασία επιτρέπει στην τυπική βιβλιοθήκη να συνεχίσει να εξελίσσεται με την πάροδο του χρόνου, χωρίς να κλειδώνει προβληματικά σφάλματα σχεδιασμού για εκτεταμένες χρονικές περιόδους. Βλ. 
@geindex Python Enhancement Proposals; PEP 411
PEP 411@footnote{https://peps.python.org/pep-0411/} για περισσότερες λεπτομέρειες.
@anchor{glossary term-provisional-package}@anchor{13ea}
@geindex provisional πακέτο

@item provisional πακέτο

Βλ. @ref{5fd,,provisional API}.
@anchor{glossary term-Python-3000}@anchor{5d60}
@geindex Python 3000

@item Python 3000

Ψευδώνυμο για το σύνολο εκδόσεων Python 3.x (επινοήθηκε πριν από πολύ καιρό όταν η κυκλοφορία της έκδοσης 3 ήταν κάτι στο μακρινό μέλλον.)  Αυτό ονομάζεται επίσης ως συντομογραφία «Py3k».
@anchor{glossary term-Pythonic}@anchor{5d61}
@geindex Pythonic

@item Pythonic

Μια ιδέα ή ένα κομμάτι κώδικα που ακολουθεί πιστά τα πιο κοινά ιδιώματα της γλώσσας Python, αντί να υλοποιεί κώδικα χρησιμοποιώντας έννοιες κοινές σε άλλες γλώσσες.  Για παράδειγμα, ένα κοινό ιδίωμα στην Python είναι να κάνει μια επανάληψη πάνω από όλα τα στοιχεία ενός iterable χρησιμοποιώντας μια δήλωση @ref{321,,for}.  Πολλές άλλες γλώσσες που δεν έχουν αυτόν τον τύπο κατασκευής, έτσι οι άνθρωποι που δεν είναι εξοικειωμένοι με την Python χρησιμοποιούν μερικές φορές έναν αριθμητικό μετρητή:

@example
for i in range(len(food)):
    print(food[i])
@end example

Αντίθετα, μια πιο καθαρή μέθοδος Pythonic:

@example
for piece in food:
    print(piece)
@end example
@anchor{glossary term-qualified-name}@anchor{1f19}
@geindex αναγνωρισμένο όνομα

@item αναγνωρισμένο όνομα

Ένα όνομα με κουκκίδες που δείχνει τη «διαδρομή» από το καθολικό εύρος ενός module σε μια κλάση, συνάρτηση ή μέθοδο που ορίζεται σε αυτήν την ενότητα, όπως ορίζεται στο 
@geindex Python Enhancement Proposals; PEP 3155
PEP 3155@footnote{https://peps.python.org/pep-3155/}. Για συναρτήσεις και κλάσεις ανώτατου επιπέδου, το αναγνωρισμένο όνομα είναι ίδιο με το όνομα του αντικειμένου:

@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

Όταν χρησιμοποιείται για αναφορά σε modules , το `πλήρως αναγνωρισμένο όνομα' σημαίνει ολόκληρο το διακεκομμένο path προς το module, συμπεριλαμβανομένων τυχόν γονικών πακέτων π.χ. @code{email.mime.text}:

@example
>>> import email.mime.text
>>> email.mime.text.__name__
'email.mime.text'
@end example
@anchor{glossary term-race-condition}@anchor{2921}
@geindex race condition

@item race condition

A condition of a program where the behavior
depends on the relative timing or ordering of events, particularly in
multi-threaded programs.  Race conditions can lead to
@ref{5d4d,,non-deterministic} behavior and bugs that are difficult to
reproduce.  A @ref{2922,,data race} is a specific type of race condition
involving unsynchronized access to shared memory.  The @ref{5d55,,LBYL}
coding style is particularly susceptible to race conditions in
multi-threaded code.  Using @ref{2920,,locks} and other
@ref{5d4e,,synchronization primitives}
helps prevent race conditions.
@anchor{glossary term-reference-count}@anchor{2c5}
@geindex πλήθος αναφοράς

@item πλήθος αναφοράς

Ο αριθμός των αναφορών σε ένα αντικείμενο.  Όταν το πλήθος αναφορών ενός αντικειμένου πέσει στο μηδέν, κατανέμεται. Μερικά αντικείμενα είναι @ref{398,,immortal} και έχουν πλήθος αναφορών που δεν τροποποιούνται ποτέ και επομένως τα αντικείμενα δεν κατανέμονται ποτέ. Η καταμέτρηση αναφορών γενικά δεν είναι ορατή στον κώδικα της Python, αλλά είναι βασικό στοιχείο της υλοποίησης @ref{ae3,,CPython}. Οι προγραμματιστές μπορούν να καλέσουν τη συνάρτηση @ref{54a,,sys.getrefcount()} για να επιστρέψουν το πλήθος αναφοράς για ένα συγκεκριμένο αντικείμενο.

Στο @ref{ae3,,CPython}, τα πλήθη αναφοράς δεν θεωρούνται σταθερές ή καλά ορισμένες τιμές· ο αριθμός των αναφορών σε ένα αντικείμενο και το πώς αυτός ο αριθμός επηρεάζεται από τον κώδικα Python, μπορεί να διαφέρει μεταξύ εκδόσεων.
@anchor{glossary term-regular-package}@anchor{2636}
@geindex κανονικό πακέτο

@item κανονικό πακέτο

Ένα παραδοσιακό @ref{4c1,,package}, όπως ένας κατάλογος που περιέχει ένα @code{__init__.py} αρχείο.

Βλ. επίσης @ref{52e,,namespace package}.
@anchor{glossary term-reentrant}@anchor{5d52}
@geindex reentrant

@item reentrant

A property of a function or @ref{2920,,lock} that allows it to be called or
acquired multiple times by the same thread without causing errors or a
@ref{5d51,,deadlock}.

For functions, reentrancy means the function can be safely called again
before a previous invocation has completed, which is important when
functions may be called recursively or from signal handlers. Thread-unsafe
functions may be @ref{5d4d,,non-deterministic} if they’re called reentrantly in a
multithreaded program.

For locks, Python’s @ref{2df,,threading.RLock} (reentrant lock) is
reentrant, meaning a thread that already holds the lock can acquire it
again without blocking.  In contrast, @ref{1a10,,threading.Lock} is not
reentrant - attempting to acquire it twice from the same thread will cause
a deadlock.

See also @ref{2920,,lock} and @ref{5d51,,deadlock}.
@anchor{glossary term-REPL}@anchor{69d}
@geindex REPL

@item REPL

Ακρωνύμιο του «read–eval–print loop», άλλη ονομασία για το @ref{451,,interactive} περιβάλλον του διερμηνέα.
@anchor{glossary term-__slots__}@anchor{9d9}
@geindex __slots__

@item __slots__

Μια δήλωση μέσα σε μια κλάση που εξοικονομεί μνήμη δηλώνοντας εκ των προτέρων χώρο για παράδειγμα χαρακτηριστικά και εξαλείφοντας λεξικά στιγμιοτύπων.  Αν και δημοφιλής, η τεχνική είναι κάπως δύσκολο να γίνει σωστή και προορίζεται καλύτερα για σπάνιες περιπτώσεις όπου υπάρχει μεγάλος αριθμός στιγμιοτύπων σε μια εφαρμογή κρίσιμης-μνήμης.
@anchor{glossary term-sequence}@anchor{8ff}
@geindex ακολουθία

@item ακολουθία

Ένας @ref{15ce,,iterable} που υποστηρίζει την αποτελεσματική πρόσβαση στο στοιχείο χρησιμοποιώντας ακέραιους δείκτες μέσω της ειδική μεθόδου @ref{787,,__getitem__()} και ορίζει μια μέθοδο @ref{1989,,__len__()} που επιστρέφει το μήκος της ακολουθίας. Ορισμένοι ενσωματωμένοι τύποι ακολουθιών είναι @ref{4d9,,list}, @ref{1df,,str}, @ref{1ce,,tuple}, και @ref{1c7,,bytes}. Σημειώστε ότι το @ref{188,,dict} υποστηρίζει επίσης @code{__getitem__()} και @code{__len__()}, αλλά θεωρείται αντιστοίχιση και όχι ακολουθία επειδή οι αναζητήσεις χρησιμοποιούν αυθαίρετα @ref{183,,hashable} κλειδιά παρά ακέραιοι.

Η αφηρημένη βασική κλάση @ref{156d,,collections.abc.Sequence} ορίζει μια πολύ πιο πλούσια διεπαφή που ξεπερνά τα απλά @ref{787,,__getitem__()} και @ref{1989,,__len__()}, adding @ref{25cd,,count()}, @ref{1b8b,,index()}, @ref{175c,,__contains__()}, και @ref{1049,,__reversed__()}. Οι τύποι που υλοποιούν αυτήν την διευρυμένη διεπαφή μπορούν να καταχωρηθούν ρητά χρησιμοποιώντας @ref{1436,,register()}. Για περισσότερη τεκμηρίωση σχετικά με τις μεθόδους ακολουθίας γενικά, ανατρέξτε στο @ref{2801,,Common Sequence Operations}.
@anchor{glossary term-set-comprehension}@anchor{5d62}
@geindex set comprehension

@item set comprehension

Ένας συμπαγής τρόπος για να επεξεργαστείτε όλα ή μέρος των στοιχείων σε ένα iterable και να επιστραφεί ένα σύνολο με τα αποτελέσματα. @code{results = @{c for c in 'abracadabra' if c not in 'abc'@}} δημιουργεί το σύνολο συμβολοσειρών @code{@{'r', 'd'@}}. Βλ. @ref{9ce,,Displays for lists@comma{} sets and dictionaries}.
@anchor{glossary term-single-dispatch}@anchor{db5}
@geindex μοναδικό dispatch

@item μοναδικό dispatch

Μια μορφή dispatch @ref{db4,,generic function} όπου η υλοποίηση επιλέγεται με βάση τον τύπο ενός μεμονωμένου ορίσματος.
@anchor{glossary term-slice}@anchor{26a5}
@geindex slice

@item slice

An object of type @ref{1d0,,slice}, used to describe a portion of
a @ref{8ff,,sequence}.
A slice object is created when using the @ref{26a4,,slicing} form
of @ref{2599,,subscript notation}, with colons inside square
brackets, such as in @code{variable_name[1:3:5]}.
@anchor{glossary term-soft-deprecated}@anchor{1a7}
@geindex απαρχαιωμένη με ήπιο τρόπο

@item απαρχαιωμένη με ήπιο τρόπο

Ένα απαρχαιωμένο με ήπιο τρόπο API δεν θα πρέπει να χρησιμοποιείται σε νέο κώδικα, αλλά είναι ασφαλές σε ήδη υπάρχοντα κώδικα να το χρησιμοποιεί. Το API παραμένει τεκμηριωμένο και δοκιμασμένο, αλλά δεν θα ενισχυθεί περαιτέρω.

Η κατάργηση με ήπιο τρόπο, σε αντίθεση με την κανονική κατάργηση, δεν σχεδιάζει την κατάργηση του API και δεν θα εκπέμπει ειδοποιήσεις

Δείτε PEP 387: Soft Deprecation@footnote{https://peps.python.org/pep-0387/#soft-deprecation}.
@anchor{glossary term-special-method}@anchor{1e57}
@geindex ειδική μέθοδος

@item ειδική μέθοδος

@geindex special;μέθοδος

Μια μέθοδος που καλείται σιωπηρά από την Python για να εκτελέσει μια συγκεκριμένη λειτουργία σε έναν τύπο, όπως η προσθήκη. Τέτοιες μέθοδοι έχουνε ονόματα που ξεκινούν και τελειώνουν με διπλές κάτω παύλες. Οι ειδικές μέθοδοι τεκμηριώνονται στο @ref{102c,,Ειδικά ονόματα μεθόδων}.
@anchor{glossary term-standard-library}@anchor{3d8}
@geindex τυπική βιβλιοθήκη

@item τυπική βιβλιοθήκη

Η συλλογή από @ref{4c1,,packages}, @ref{1be7,,modules} και @ref{2442,,extension modules} που διανέμεται ως μέρος του επίσημου πακέτου διερμηνέα Python. Η ακριβής συμμετοχή της συλλογής μπορεί να διαφέρει ανάλογα με την πλατφόρμα, τις διαθέσιμες βιβλιοθήκες συστήματος ή άλλα κριτήρια. Η τεκμηρίωση μπορεί να βρεθεί στο @ref{3f7,,The Python Standard Library}.

Βλ. επίσης @ref{c1a,,sys.stdlib_module_names} για μια λίστα με όλα τα πιθανά ονόματα module της τυπικής βιβλιοθήκης.
@anchor{glossary term-statement}@anchor{2e17}
@geindex δήλωση

@item δήλωση

Μια πρόταση είναι μέρος μιας σουίτας (ένα «μπλοκ» κώδικα). Μια πρόταση είναι είτε ένας @ref{25c4,,expression} είτε μια από πολλές δομές με μια λέξη-κλειδί όπως @ref{322,,if}, @ref{1b86,,while} ή @ref{321,,for}.
@anchor{glossary term-static-type-checker}@anchor{775}
@geindex ελεγκτής στατικού τύπου

@item ελεγκτής στατικού τύπου

Ένα εξωτερικό εργαλείο όπου διαβάζει τον Python κώδικα και τον αναλύει, αναζητώντας προβλήματα όπως λανθασμένοι τύποι. Βλ. επίσης @ref{25c1,,type hints} και το module @ref{10d,,typing}.
@anchor{glossary term-stdlib}@anchor{1bb}
@geindex stdlib

@item stdlib

Μια συντομογραφία του @ref{3d8,,standard library}.
@anchor{glossary term-strong-reference}@anchor{7da}
@geindex strong reference

@item strong reference

Στο C API της Python, μια ισχυρή αναφορά είναι μια αναφορά σε ένα αντικείμενο που ανήκει στον κώδικα που περιέχει την αναφορά. Η ισχυρή αναφορά λαμβάνεται καλώντας το @ref{974,,Py_INCREF()} όταν η αναφορά δημιουργείται και απελευθερώνεται με @ref{975,,Py_DECREF()} όταν διαγραφεί η αναφορά.

Η συνάρτηση @ref{c70,,Py_NewRef()} μπορεί να χρησιμοποιηθεί για τη δημιουργία ισχυρής αναφοράς σε ένα αντικείμενο. Συνήθως, η συνάρτηση @ref{975,,Py_DECREF()} πρέπει να καλείται στην ισχυρή αναφορά πριν βγει από το εύρος της ισχυρής αναφοράς, για να αποφευχθεί η διαρροή μιας αναφοράς.

Βλ. επίσης @ref{603,,borrowed reference}.
@anchor{glossary term-subscript}@anchor{5d5b}
@geindex subscript

@item subscript

The expression in square brackets of a
@ref{2599,,subscription expression}, for example,
the @code{3} in @code{items[3]}.
Usually used to select an element of a container.
Also called a @ref{25d9,,key} when subscripting a @ref{1564,,mapping},
or an @ref{25d8,,index} when subscripting a @ref{8ff,,sequence}.
@anchor{glossary term-synchronization-primitive}@anchor{5d4e}
@geindex synchronization primitive

@item synchronization primitive

A basic building block for coordinating (synchronizing) the execution of
multiple threads to ensure @ref{5d50,,thread-safe} access to shared resources.
Python’s @ref{f6,,threading} module provides several synchronization primitives
including @ref{1a10,,Lock}, @ref{2df,,RLock},
@ref{1501,,Semaphore}, @ref{1500,,Condition},
@ref{1503,,Event}, and @ref{158c,,Barrier}.  Additionally,
the @ref{be,,queue} module provides multi-producer, multi-consumer queues
that are especially useful in multithreaded programs. These
primitives help prevent @ref{2921,,race conditions} and
coordinate thread execution.  See also @ref{2920,,lock}.
@anchor{glossary term-t-string}@anchor{5d63}
@geindex t-string

@item t-string@anchor{glossary term-t-strings}@anchor{5d64}
@geindex t-strings

@itemx t-strings

Οι κυριολεκτικές συμβολοσειρές που χρησιμοποιούνται με πρόθεμα @code{t} or @code{T} ονομάζονται συνήθως «t-strings» που είναι συντομογραφία του @ref{1a50,,template string literals}.
@anchor{glossary term-text-encoding}@anchor{27d4}
@geindex κωδικοποίηση κειμένου

@item κωδικοποίηση κειμένου

Μια συμβολοσειρά στην Python είναι μια ακολουθία σημείων κώδικα Unicode (στο εύρος @code{U+0000}–@code{U+10FFFF}). Για να αποθηκεύσετε ή να μεταφέρετε μια συμβολοσειρά, πρέπει να σειριοποιηθεί ως δυαδική ακολουθία.

Η σειριοποίηση μιας συμβολοσειράς σε μια δυαδική ακολουθία είναι γνωστή ως «κωδικοποίηση» , και η αναδημιουργία της συμβολοσειράς από την δυαδική ακολουθία είναι γνωστή ως «αποκωδικοποίηση».

Υπάρχει μια ποικιλία διαφορετικής σειριοποίησης κειμένου @ref{1171,,codecs}, οι οποίοι συλλογικά αναφέρονται ως «κωδικοποιήσεις κειμένου».
@anchor{glossary term-text-file}@anchor{225c}
@geindex αρχείο κειμένου

@item αρχείο κειμένου

Ένα @ref{156c,,file object} ικανό να διαβάζει και να γράφει αντικείμενα @ref{1df,,str}. Συχνά, ένα αρχείο κειμένου αποκτά πραγματικά πρόσβαση σε μια ροή δυαδική ροή δεδομένων και χειρίζεται αυτόματα την @ref{27d4,,text encoding}. Παραδείγματα αρχείων κειμένου είναι αρχεία που ανοίγουν σε λειτουργία κειμένου (@code{'r'} ή @code{'w'}), @ref{94a,,sys.stdin}, @ref{e9c,,sys.stdout}, και στιγμιότυπα του @ref{12d4,,io.StringIO}.

Βλ. επίσης @ref{225d,,binary file} για ένα αντικείμενο αρχείου με δυνατότητα ανάγνωσης και εγγραφής @ref{436,,δυαδικά αντικείμενα}.
@anchor{glossary term-thread-state}@anchor{1a70}
@geindex κατάσταση νήματος

@item κατάσταση νήματος

Οι πληροφορίες που χρησιμοποιούνται από τη ροή εκτέλεσης της @ref{ae3,,CPython} για την εκτέλεση σε ένα νήμα λειτουργικού συστήματος. Για παράδειγμα, αυτό περιλαμβάνει την τρέχουσα εξαίρεση, εάν υπάρχει, και την κατάσταση του διερμηνέα bytecode.

Κάθε κατάσταση νήματος είναι συνδεδεμένη με ένα μόνο νήμα λειτουργικού συστήματος, αλλά τα νήματα μπορεί να έχουν πολλές διαθέσιμες καταστάσεις νήματος.  Το πολύ, μία από αυτές μπορεί να είναι @ref{1a1,,attached} ταυτόχρονα.

Απαιτείται ένα @ref{1a1,,attached thread state} για την κλήση του μεγαλύτερου μέρους του C API της Python, εκτός εάν μια συνάρτηση τεκμηριώνεται ρητά από το αντίθετο. Ο διερμηνέας bytecode εκτελείται μόνο υπό κατάσταση συνημμένου νήματος.

Κάθε κατάσταση νήματος ανήκει σε έναν μόνο διερμηνέα, αλλά κάθε διερμηνέα μπορεί να έχει πολλές καταστάσεις νήματος, συμπεριλαμβανομένων πολλαπλών για το ίδιο νήμα λειτουργικού συστήματος. Οι καταστάσεις νήματος από πολλαπλούς διερμηνείς μπορεί να είναι συνδεδεμένος με το ίδιο νήμα, αλλά μόνο μία μπορεί να είναι @ref{1a1,,attached} σε αυτό το νήμα σε οποιαδήποτε δεδομένη στιγμή.

Δείτε το @ref{589a,,Thread State and the Global Interpreter Lock} για περισσότερες πληροφορίες.
@anchor{glossary term-thread-safe}@anchor{5d50}
@geindex thread-safe

@item thread-safe

A module, function, or class that behaves correctly when used by multiple
threads concurrently.  Thread-safe code uses appropriate
@ref{5d4e,,synchronization primitives} like
@ref{2920,,locks} to protect shared mutable state, or is designed
to avoid shared mutable state entirely.  In the
@ref{487,,free-threaded} build, built-in types like
@ref{188,,dict}, @ref{4d9,,list}, and @ref{42b,,set} use internal locking
to make many operations thread-safe, although thread safety is not
necessarily guaranteed.  Code that is not thread-safe may experience
@ref{2921,,race conditions} and @ref{2922,,data races}
when used in multi-threaded programs.
@anchor{glossary term-token}@anchor{2479}
@geindex λεκτικό σύμβολο (token)

@item λεκτικό σύμβολο (token)

Μια μικρή μονάδα πηγαίου κώδικα, που παράγεται από τον @ref{2486,,lexical analyzer} (γνωστό και ως `αναλυτή (tokenizer)'). Ονόματα, αριθμοί, συμβολοσειρές, τελεστές αλλαγές γραμμής και παρόμοια στοιχεία αναπαρίστανται ως λεκτικά σύμβολα (tokens).

Το module @ref{104,,tokenize} εκθέτει τον λεξικό αναλυτή της Python. Το module @ref{103,,token} περιέχει πληροφορίες για τους διάφορους τύπους λεκτικών συμβόλων (tokens).
@anchor{glossary term-triple-quoted-string}@anchor{5d65}
@geindex συμβολοσειρά τριπλών εισαγωγικών

@item συμβολοσειρά τριπλών εισαγωγικών

Μια συμβολοσειρά που δεσμεύεται από τρεις περιπτώσεις είτε ενός εισαγωγικού (») ή μιας αποστρόφου (“). Αν και δεν παρέχουν καμία λειτουργικότητα που δεν είναι διαθέσιμη με συμβολοσειρές με μονά εισαγωγικά, είναι χρήσιμες για διαφόρους λόγους. Σας επιτρέπουν να συμπεριλάβετε μονά και διπλά εισαγωγικά χωρίς διαφυγή σε μια συμβολοσειρά και μπορούν να εκτείνονται σε πολλές γραμμές χωρίς τη χρήση του χαρακτήρα συνέχεια, καθιστώντας τα ιδιαίτερα χρήσιμα κατά τη σύνταξη εγγράφων με συμβολοσειρές.
@anchor{glossary term-type}@anchor{1ef3}
@geindex τύπος

@item τύπος

Ο τύπος ενός Python αντικειμένου καθορίζει τι είδους αντικείμενο είναι∙ κάθε αντικείμενο έχει έναν τύπο. Ο τύπος ενός αντικειμένου είναι προσβάσιμος ως το χαρακτηριστικό @ref{184f,,__class__} ή μπορεί να ανακτηθεί με @code{type(obj)}.
@anchor{glossary term-type-alias}@anchor{85b}
@geindex type alias

@item type alias

Ένα συνώνυμο για έναν τύπο, που δημιουργείται με την ανάθεση τύπου σε ένα αναγνωριστικό.

Τα type aliases είναι χρήσιμα για την απλοποίηση @ref{25c1,,type alias}. Για παράδειγμα:

@example
def remove_gray_shades(
        colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:
    pass
@end example

μπορεί να γίνει πιο ευανάγνωστο όπως:

@example
Color = tuple[int, int, int]

def remove_gray_shades(colors: list[Color]) -> list[Color]:
    pass
@end example

Βλ. @ref{10d,,typing} και 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}, που περιγράφει αυτήν την λειτουργικότητα.
@anchor{glossary term-type-hint}@anchor{25c1}
@geindex type hint

@item type hint

Ένας @ref{409,,annotation} που καθορίζει τον αναμενόμενο τύπο για μια μεταβλητή, ένα χαρακτηριστικό κλάσης ή μια παράμετρο συνάρτησης ή τιμή επιστροφής.

Οι υποδείξεις τύπων (type hints) είναι προαιρετικές και δεν επιβάλλονται από την Python, αλλά είναι χρήσιμες για @ref{775,,static type checkers}. Μπορούν επίσης να βοηθήσουν τους IDEs με τη συμπλήρωση και την αναδιαμόρφωση κώδικα.

Υποδείξεις τύπου (type hints) για καθολικές μεταβλητές, χαρακτηριστικά κλάσης και συναρτήσεις , αλλά όχι τοπικές μεταβλητές, μπορούν να προσπελαστούν χρησιμοποιώντας το @ref{a9e,,typing.get_type_hints()}.

Βλ. @ref{10d,,typing} και 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}, που περιγράφει αυτήν την λειτουργικότητα.
@anchor{glossary term-universal-newlines}@anchor{10f1}
@geindex καθολικές νέες γραμμές

@item καθολικές νέες γραμμές

Ένα τρόπος ερμηνείας ροών κειμένου στον οποίο όλα τα ακόλουθα αναγνωρίζονται ως λήξεις μιας γραμμής: η σύμβαση τέλους γραμμής του Unix @code{'\n'}, η σύμβαση των Windows @code{'\r\n'}, και την παλιά σύμβαση Macintosh @code{'\r'}. Βλ. 
@geindex Python Enhancement Proposals; PEP 278
PEP 278@footnote{https://peps.python.org/pep-0278/} και 
@geindex Python Enhancement Proposals; PEP 3116
PEP 3116@footnote{https://peps.python.org/pep-3116/}, καθώς και @ref{281c,,bytes.splitlines()} για πρόσθετη χρήση.
@anchor{glossary term-variable-annotation}@anchor{110a}
@geindex annotation μεταβλητής

@item annotation μεταβλητής

Ένας @ref{409,,annotation} μια μεταβλητής ή ενός χαρακτηριστικού κλάσης.

Όταν annotating μια μεταβλητή ή ένα χαρακτηριστικό κλάσης, η ανάθεση είναι προαιρετική:

@example
class C:
    field: 'annotation'
@end example

Τα annotations μεταβλητών χρησιμοποιούνται συνήθως για @ref{25c1,,type hints}: για παράδειγμα αυτή η μεταβλητή αναμένεται να λάβει τιμές @ref{326,,int}:

@example
count: int = 0
@end example

Η σύνταξη annotation μεταβλητής περιγράφεται στην ενότητα @ref{2701,,Εντολές ανάθεσης με σχολιασμό}.

Βλ. @ref{2207,,function annotation}, 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} και 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}, που περιγράφουν αυτή τη λειτουργία. Δείτε επίσης @ref{bb6,,Annotations Best Practices} για βέλτιστες πρακτικές σχετικά με την εργασία με σχολιασμούς.
@anchor{glossary term-virtual-environment}@anchor{22dd}
@geindex virtual environment

@item virtual environment

Ένα συνεργατικά απομονωμένο περιβάλλον χρόνου εκτέλεσης που επιτρέπει στους χρήστες και τις εφαρμογές της Python να εγκαταστήσουν και να αναβαθμίσουν πακέτα διανομής Python χωρίς να παρεμβαίνουν στη συμπεριφορά άλλων εφαρμογών Python που εκτελούνται στο ίδιο σύστημα.

Βλ. επίσης @ref{11a,,venv}.
@anchor{glossary term-virtual-machine}@anchor{3ca3}
@geindex virtual machine

@item virtual machine

Ένας υπολογιστής ορίζεται εξ ολοκλήρου από το λογισμικό. Η εικονική μηχανή της Python εκτελεί το @ref{6b3,,bytecode} που εκπέμπεται από τον μεταγλωττιστή bytecode.
@anchor{glossary term-walrus-operator}@anchor{5d66}
@geindex τελεστής walrus

@item τελεστής walrus

Μια ελαφρώς χιουμοριστική αναφορά στον @ref{26d4,,τελεστή εκχώρησης} @code{:=} επειδή μοιάζει λίγο με έναν θαλάσσιο ίππο αν γυρίσετε το κεφάλι σας.
@anchor{glossary term-Zen-of-Python}@anchor{5d67}
@geindex Zen της Python

@item Zen της Python

Κατάλογος σχεδιαστικών αρχών και φιλοσοφιών που είναι χρήσιμες για την κατανόηση και τη χρήση της γλώσσας. Ο κατάλογος μπορεί να βρεθεί πληκτρολογώντας «@code{import this}» στην διαδραστική κονσόλα.
@end table

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Σχετικά με την τεκμηρίωση,Αντιμετώπιση Σφαλμάτων,Γλωσσάρι,Top
@anchor{about doc}@anchor{5d68}@anchor{about about-this-documentation}@anchor{5d69}@anchor{about translation-repo}@anchor{5d6a}
@chapter Σχετικά με την τεκμηρίωση


Η τεκμηρίωση της Python έχει δημιουργηθεί από τα reStructuredText@footnote{https://docutils.sourceforge.io/rst.html} sources του Sphinx@footnote{https://www.sphinx-doc.org/}, έναν επεξεργαστή εγγράφων που έχει δημιουργηθεί ειδικά για τα έγγραφα της Python.

@c In the online version of these documents, you can submit comments and suggest
@c changes directly on the documentation pages.

Η ανάπτυξη των εγγράφων και των εργαλείων τους είναι εξ” ολοκλήρου εθελοντική προσπάθεια, όπως και η ίδια η Python. Εάν θέλετε να συνεισφέρετε, ρίξτε μια ματιά στη σελίδα @ref{522f,,Αντιμετώπιση Σφαλμάτων} για πληροφορίες σχετικές με το πως να το κάνετε. Καινούριοι εθελοντές είναι πάντα ευπρόσδεκτοι!

Πολλές ευχαριστίες πηγαίνουν στους:


@itemize *

@item 
Fred L. Drake, Jr., τον δημιουργό των αρχικών εργαλείων της τεκμηρίωσης της Python και συντάκτη αρκετού περιεχομένου·

@item 
το Docutils@footnote{https://docutils.sourceforge.io/} πρότζεκτ για την δημιουργία των εφαρμογών reStructuredText και Docutils·

@item 
Fredrik Lundh για το δικό του Alternative Python Reference πρότζεκτ από το οποίο το Sphinx πήρε πολύ καλές ιδέες.
@end itemize

@menu
* Συντελεστές στη τεκμηρίωση της Python:: 

@end menu

@node Συντελεστές στη τεκμηρίωση της Python,,,Σχετικά με την τεκμηρίωση
@anchor{about contributors-to-the-python-documentation}@anchor{5d6b}
@section Συντελεστές στη τεκμηρίωση της Python


Many people have contributed to the Python language, the Python standard
library, and the Python documentation.  See the CPython GitHub repository@footnote{https://github.com/python/cpython/graphs/contributors}
for a partial list of contributors.

Μόνο με τη συμβολή και τις συνεισφορές της κοινότητας της Python, η Python έχει τέτοια υπέροχα έγγραφα – Σας ευχαριστούμε!

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Αντιμετώπιση Σφαλμάτων,Copyright,Σχετικά με την τεκμηρίωση,Top
@anchor{bugs doc}@anchor{5d6c}@anchor{bugs dealing-with-bugs}@anchor{5d6d}@anchor{bugs reporting-bugs}@anchor{522f}@anchor{bugs translation-repo}@anchor{5d6e}
@chapter Αντιμετώπιση Σφαλμάτων


Η Python είναι μια ώριμη γλώσσα προγραμματισμού που έχει δημιουργήσει μια φήμη σταθερότητας. Για να διατηρήσουν αυτή τη φήμη, οι προγραμματιστές θα ήθελαν να γνωρίζουν τυχόν ελλείψεις που βρίσκετε στην Python.

It can be sometimes faster to fix bugs yourself and contribute patches to
Python as it streamlines the process and involves fewer people. Learn how to
@ref{5d6f,,contribute}.

@menu
* Σφάλματα Τεκμηρίωσης:: 
* Χρησιμοποιώντας τον Python issue tracker:: 
* Ξεκινήστε να συνεισφέρετε και εσείς στην Python:: 

@end menu

@node Σφάλματα Τεκμηρίωσης,Χρησιμοποιώντας τον Python issue tracker,,Αντιμετώπιση Σφαλμάτων
@anchor{bugs documentation-bugs}@anchor{5d70}
@section Σφάλματα Τεκμηρίωσης


Εάν βρείτε ένα σφάλμα σε αυτήν την τεκμηρίωση ή θέλετε να προτείνετε μια βελτίωση, υποβάλετε μια αναφορά σφάλματος στο @ref{758,,issue tracker}. Εάν έχετε μια πρόταση για το πώς να το διορθώσετε, συμπεριλάβετε και αυτήν.

Αν το σφάλμα ή η προτεινόμενη βελτίωση αφορά τη μετάφραση αυτή της τεκμηρίωσης, υποβάλετε την αναφορά στο translation’s repository@footnote{https://github.com/python/python-docs-el} αντί γι” αυτό.

Μπορείτε επίσης να ανοίξετε ένα θέμα συζήτησης στο Φόρουμ της συζήτησης για την τεκμηρίωση@footnote{https://discuss.python.org/c/documentation/26}.

Εάν εντοπίσετε ένα σφάλμα στο θέμα (HTML / CSS / JavaScript) της τεκμηρίωσης , υποβάλετε μια αναφορά σφαλμάτων σχετικά με το πρόγραμμα παρακολούθησης σφαλμάτων python-doc-theme bug tracker@footnote{https://github.com/python/python-docs-theme}.


@subsubheading Δείτε επίσης



@table @asis

@item Documentation bugs@footnote{https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocs}

Μια λίστα σφαλμάτων τεκμηρίωσης που έχουν υποβληθεί στον Python issue tracker.

@item Παρακολούθηση Issue@footnote{https://devguide.python.org/tracker/}

Επισκόπηση της διαδικασίας που περιλαμβάνει η αναφορά μιας βελτίωσης στον tracker.

@item Βοηθώντας με την Τεκμηρίωση@footnote{https://devguide.python.org/docquality/#helping-with-documentation}

Ολοκληρωμένος οδηγός για άτομα που ενδιαφέρονται να συνεισφέρουν στην Τεκμηρίωση της Python.

@item Documentation Translations@footnote{https://devguide.python.org/documentation/translations/translating/#translation-coordinators}

A list of GitHub pages for documentation translation and their coordination teams.
@end table


@node Χρησιμοποιώντας τον Python issue tracker,Ξεκινήστε να συνεισφέρετε και εσείς στην Python,Σφάλματα Τεκμηρίωσης,Αντιμετώπιση Σφαλμάτων
@anchor{bugs using-the-python-issue-tracker}@anchor{5d71}@anchor{bugs using-the-tracker}@anchor{758}
@section Χρησιμοποιώντας τον Python issue tracker


Οι αναφορές issues για την ίδια την Python θα πρέπει να υποβάλλονται μέσω του GitHub issues tracker (@indicateurl{https://github.com/python/cpython/issues}). Ο GitHub issues tracker προσφέρει μια web φόρμα που επιτρέπει την εισαγωγή και υποβολή σχετικών πληροφοριών στους προγραμματιστές.

Το πρώτο βήμα για την υποβολή αναφοράς είναι να προσδιοριστεί εάν το πρόβλημα έχει ήδη αναφερθεί. Το πλεονέκτημα με αυτόν τον τρόπο, εκτός από το ότι σώζει τον χρόνο των προγραμματιστών, είναι να μάθετε τι έχει γίνει για να το διορθώσετε” μπορεί να είναι ότι το πρόβλημα έχει ήδη επιδιορθωθεί για την επόμενη έκδοση ή επιπλέον απαιτούνται πληροφορίες (σε οποιαδήποτε περίπτωση μπορείτε να τις παρέχετε και εσείς!). Για να το κάνετε αυτό, αναζητήστε στον tracker χρησιμοποιώντας το πλαίσιο αναζήτησης στο επάνω μέρος της σελίδας.

Εάν το πρόβλημα που αναφέρετε δεν είναι ήδη στη λίστα, συνδεθείτε στο GitHub. Εάν δεν έχετε ήδη λογαριασμό GitHub, δημιουργήστε έναν νέο λογαριασμό χρησιμοποιώντας τον σύνδεσμο «Sign up». Δεν είναι δυνατή η υποβολή αναφοράς σφαλμάτων ανώνυμα.

Όταν πλέον είστε συνδεδεμένοι, μπορείτε να υποβάλετε ένα issue. Κάντε κλικ στο κουμπί «New issue» στην επάνω γραμμή για να αναφέρετε ένα νέο issue.

Η φόρμα υποβολής έχει δύο πεδία, «Title» και «Comment».

Για το πεδίο «Title», εισαγάγετε μια `πολύ' σύντομη περιγραφή του προβλήματος” λιγότερες από δέκα λέξεις είναι καλές.

Στο πεδίο «Comment», περιγράψτε το πρόβλημα λεπτομερώς, συμπεριλαμβανομένου αυτού που αναμενόταν να συμβεί και τι συνέβη. Φροντίστε να συμπεριλάβετε τυχόν extension modules τα οποία χρησιμοποιήσατε όπως και ποια πλατφόρμα υλικού και λογισμικού (συμπεριλαμβανομένων των πληροφοριών έκδοσης ανάλογα με την περίπτωση).

Κάθε αναφορά προβλήματος θα εξετάζεται από έναν προγραμματιστή που θα καθορίσει τι πρέπει να γίνει για να διορθωθεί το πρόβλημα. Θα λαμβάνετε μια ενημέρωση κάθε φορά που γίνεται κάποια ενέργεια για το πρόβλημα.


@subsubheading Δείτε επίσης



@table @asis

@item Πως να Αναφέρεται Σφάλματα Αποτελεσματικά@footnote{https://www.chiark.greenend.org.uk/~sgtatham/bugs.html}

Άρθρο που περιλαμβάνει κάποιες λεπτομέρειες σχετικά με τον τρόπο δημιουργίας μιας χρήσιμης αναφοράς σφάλματος. Περιγράφει τι είδους πληροφορίες είναι χρήσιμες και γιατί είναι χρήσιμες.

@item Οδηγίες Συγγραφής Αναφορών Σφαλμάτων@footnote{https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html}

Πληροφορίες σχετικά με τη σύνταξη μιας καλής αναφοράς σφαλμάτων. Κάποια από αυτά αφορούν ειδικά το πρότζεκτ Mozilla, αλλά περιγράφουν και γενικές καλές πρακτικές.
@end table


@node Ξεκινήστε να συνεισφέρετε και εσείς στην Python,,Χρησιμοποιώντας τον Python issue tracker,Αντιμετώπιση Σφαλμάτων
@anchor{bugs contributing-to-python}@anchor{5d6f}@anchor{bugs getting-started-contributing-to-python-yourself}@anchor{5d72}
@section Ξεκινήστε να συνεισφέρετε και εσείς στην Python


Πέρα από την απλή αναφορά σφαλμάτων που βρίσκετε, μπορείτε επίσης να υποβάλετε ενημερώσεις για να τα διορθώσετε. Μπορείτε να βρείτε περισσότερες πληροφορίες για το πώς να ξεκινήσετε μια ενημέρωση της Python στον Python Developer's Guide@footnote{https://devguide.python.org/}. Εάν έχετε ερωτήσεις, το core-mentorship mailing list@footnote{https://mail.python.org/mailman3/lists/core-mentorship.python.org/} είναι ένα φιλικό μέρος για να λάβετε απαντήσεις για οποιασδήποτε ή και όλες τις ερωτήσεις που σχετίζονται με τη διαδικασία επίλυσης προβλημάτων στην Python.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Copyright,Ιστορία και Άδεια,Αντιμετώπιση Σφαλμάτων,Top
@anchor{copyright doc}@anchor{5d73}@anchor{copyright copyright}@anchor{5d74}@anchor{copyright translation-repo}@anchor{5d75}
@chapter Copyright


Η Python και αυτή η τεκμηρίωση είναι:

Copyright © 2001 Python Software Foundation. All rights reserved.

Copyright © 2000 BeOpen.com. Όλα τα δικαιώματα διατηρούνται.

Copyright © 1995-2000 Corporation for National Research Initiatives. Όλα τα δικαιώματα διατηρούνται.

Copyright © 1991-1995 Stichting Mathematisch Centrum. Όλα τα δικαιώματα διατηρούνται.


__________________________________________________________________


Ανατρέξτε στο @ref{5d76,,Ιστορία και Άδεια} για πλήρης πληροφόρηση σχετικά με την άδεια χρήσης και τις εξουσιοδοτήσεις.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Ιστορία και Άδεια,Ευρετήριο Μονάδων της Python,Copyright,Top
@anchor{license doc}@anchor{5d77}@anchor{license history-and-license}@anchor{5d76}@anchor{license id1}@anchor{5d78}@anchor{license translation-repo}@anchor{5d79}
@chapter Ιστορία και Άδεια


@menu
* Η ιστορία του λογισμικού:: 
* Όροι και προϋποθέσεις για την πρόσβαση ή την χρήση της Python με άλλους τρόπους:: 
* Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό:: 

@end menu

@node Η ιστορία του λογισμικού,Όροι και προϋποθέσεις για την πρόσβαση ή την χρήση της Python με άλλους τρόπους,,Ιστορία και Άδεια
@anchor{license history-of-the-software}@anchor{5d7a}
@section Η ιστορία του λογισμικού


Η Python δημιουργήθηκε στις αρχές του 1990 από τον Guido van Rossum στο Stichting Mathematisch Centrum (CWI, βλ. @indicateurl{https://www.cwi.nl}) στην Ολλανδία ως διάδοχος μια γλώσσας που ονομάζεται ABC. Ο Guido παραμένει ο κύριος συγγραφέας της Python, παρόλα αυτά περιλαμβάνει συνεισφορές και από άλλα άτομα.

Το 1995, ο Guido συνέχισε το έργο του για την Python στο Corporation for National Research Initiatives (CNRI, βλ. @indicateurl{https://www.cnri.reston.va.us}) στο Reston της Virginia, όπου κυκλοφόρησε πολλές εκδόσεις του λογισμικού.

Τον Μάιο του 2000, ο Guido και η βασική ομάδα ανάπτυξης της Python μετακόμισαν στο BeOpen.com για να σχηματίσουν την ομάδα BeOpen PythonLabs. Τον Οκτώβριο του ίδιου έτους, η ομάδα του PythonLabs μετακόμισε στην Digital Creations, η οποία μετατράπηκε σε Zope Corporation.  Το 2001, το Python Software Foundation (PSF, βλ. @indicateurl{https://www.python.org/psf}) δημιουργήθηκε ως ένας μη κερδοσκοπικός οργανισμός με στόχο να κατέχει την πνευματική ιδιοκτησία που σχετίζεται με την Python. Η Zope Corporation ήταν μέλος-χορηγός του PSF.

Όλες οι εκδόσεις της Python είναι Ανοιχτού Κώδικα (βλ. @indicateurl{https://opensource.org} για τον ορισμό του Ανοιχτού Κώδικα). Ιστορικά οι περισσότερες, αλλά όχι όλες, εκδόσεις της Python ήταν επίσης συμβατές με την άδεια GPL: ο παρακάτω πίνακας συνοψίζει τις διάφορες εκδόσεις.


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Έκδοση

@tab

Προερχόμενη από

@tab

Έτος

@tab

Ιδιοκτησία

@tab

Συμβατότητα GPL; (1)

@item

0.9.0 έως 1.2

@tab

δ/υ

@tab

1991-1995

@tab

CWI

@tab

ναι

@item

1.3 έως 1.5.2

@tab

1.2

@tab

1995-1999

@tab

CNRI

@tab

ναι

@item

1.6

@tab

1.5.2

@tab

2000

@tab

CNRI

@tab

όχι

@item

2.0

@tab

1.6

@tab

2000

@tab

BeOpen.com

@tab

όχι

@item

1.6.1

@tab

1.6

@tab

2001

@tab

CNRI

@tab

ναι (2)

@item

2.1

@tab

2.0+1.6.1

@tab

2001

@tab

PSF

@tab

όχι

@item

2.0.1

@tab

2.0+1.6.1

@tab

2001

@tab

PSF

@tab

ναι

@item

2.1.1

@tab

2.1+2.0.1

@tab

2001

@tab

PSF

@tab

ναι

@item

2.1.2

@tab

2.1.1

@tab

2002

@tab

PSF

@tab

ναι

@item

2.1.3

@tab

2.1.2

@tab

2002

@tab

PSF

@tab

ναι

@item

2.2 και πάνω

@tab

2.1.1

@tab

2001-σήμερα

@tab

PSF

@tab

ναι

@end multitable


@cartouche
@quotation Σημείωση 

@enumerate 

@item 
Η συμβατότητα με GPL δεν σημαίνει ότι διανέμεται η Python κάτω από την άδεια GPL. Όλες οι άδειες της Python, σε αντίθεση με την GPL, σας επιτρέπουν να διανείμετε μια τροποποιημένη έκδοση χωρίς να κάνετε τις αλλαγές σας, ανοιχτού κώδικα. Οι άδειες με συμβατότητα GPL καθιστούν δυνατό τον συνδυασμό της Python με άλλο λογισμικό που κυκλοφορεί με βάσει της GPL, ενώ οι άλλες όχι.

@item 
Σύμφωνα με τον Richard Stallman, 1.6.1 δεν είναι συμβατή με την GPL, επειδή η άδεια της έχει νομική ρήτρα επιλογής, Σύμφωνα με το CNRI, ωστόσο, ο δικηγόρος του Stallman είπε στον δικηγόρο της CNRI ότι η 1.6.1 «δεν είναι συμβατή» με την GPL.
@end enumerate
@end quotation
@end cartouche

Χάρη, στους πολλούς εξωτερικούς εθελοντές που εργάστηκαν κάτω από τις οδηγίες του Guido, αυτές οι εκδόσεις έγιναν εφικτές.

@node Όροι και προϋποθέσεις για την πρόσβαση ή την χρήση της Python με άλλους τρόπους,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό,Η ιστορία του λογισμικού,Ιστορία και Άδεια
@anchor{license terms-and-conditions-for-accessing-or-otherwise-using-python}@anchor{5d7b}
@section Όροι και προϋποθέσεις για την πρόσβαση ή την χρήση της Python με άλλους τρόπους


Το λογισμικό της Python και η τεκμηρίωση αδειοδοτούνται σύμφωνα με την άδεια χρήσης Python Software Foundation Έκδοση 2.

Ξεκινώντας από την Python 3.8.6, παραδείγματα, συνταγές και ο άλλος κώδικας στην τεκμηρίωση έχουν διπλή άδεια χρήσης, σύμφωνα με την Άδεια PSF Έκδοση 2 και της @ref{5d7c,,Zero-Clause BSD άδεια}.

Κάποιο λογισμικό που είναι ενσωματωμένο στην Python είναι υπό διαφορετικές άδειες χρήσης. Οι άδειες παρατίθενται με κώδικα που εμπίπτει σε αυτήν την άδεια. Δείτε @ref{5d7d,,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό} για μια ελλιπή λίστα αυτών των αδειών.

@menu
* PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2:: 
* ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ BEOPEN.COM ΓΙΑ PYTHON 2.0: ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ BEOPEN COM ΓΙΑ PYTHON 2 0. 
* ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CNRI ΓΙΑ PYTHON 1.6.1: ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CNRI ΓΙΑ PYTHON 1 6 1. 
* ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CWI ΓΙΑ PYTHON 0.9.0 ΕΩΣ 1.2: ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CWI ΓΙΑ PYTHON 0 9 0 ΕΩΣ 1 2. 
* ZERO-CLAUSE BSD ΑΔΕΙΑ ΓΙΑ ΤΟΝ ΚΩΔΙΚΑ ΣΤΗΝ ΤΕΚΜΗΡΙΩΣΗ ΤΗΣ PYTHON:: 

@end menu

@node PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2,ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ BEOPEN COM ΓΙΑ PYTHON 2 0,,Όροι και προϋποθέσεις για την πρόσβαση ή την χρήση της Python με άλλους τρόπους
@anchor{license psf-license}@anchor{5d7e}@anchor{license python-software-foundation-license-version-2}@anchor{5d7f}
@subsection PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2


@example
1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and
   the Individual or Organization ("Licensee") accessing and otherwise using this
   software ("Python") 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 alone or in any derivative
   version, provided, however, that PSF's License Agreement and PSF's notice of
   copyright, i.e., "Copyright © 2001 Python Software Foundation; All Rights
   Reserved" are retained in Python 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 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.

4. PSF is making Python 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 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
   FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
   MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON, 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, Licensee agrees
   to be bound by the terms and conditions of this License Agreement.
@end example

@node ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ BEOPEN COM ΓΙΑ PYTHON 2 0,ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CNRI ΓΙΑ PYTHON 1 6 1,PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2,Όροι και προϋποθέσεις για την πρόσβαση ή την χρήση της Python με άλλους τρόπους
@anchor{license beopen-com-license-agreement-for-python-2-0}@anchor{5d80}
@subsection ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ BEOPEN.COM ΓΙΑ PYTHON 2.0


ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ ΑΝΟΙΧΤΟΥ ΚΩΔΙΚΑ BEOPEN PYTHON ΕΚΔΟΣΗ 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 ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CNRI ΓΙΑ PYTHON 1 6 1,ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CWI ΓΙΑ PYTHON 0 9 0 ΕΩΣ 1 2,ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ BEOPEN COM ΓΙΑ PYTHON 2 0,Όροι και προϋποθέσεις για την πρόσβαση ή την χρήση της Python με άλλους τρόπους
@anchor{license cnri-license-agreement-for-python-1-6-1}@anchor{5d81}
@subsection ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CNRI ΓΙΑ 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 ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CWI ΓΙΑ PYTHON 0 9 0 ΕΩΣ 1 2,ZERO-CLAUSE BSD ΑΔΕΙΑ ΓΙΑ ΤΟΝ ΚΩΔΙΚΑ ΣΤΗΝ ΤΕΚΜΗΡΙΩΣΗ ΤΗΣ PYTHON,ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CNRI ΓΙΑ PYTHON 1 6 1,Όροι και προϋποθέσεις για την πρόσβαση ή την χρήση της Python με άλλους τρόπους
@anchor{license cwi-license-agreement-for-python-0-9-0-through-1-2}@anchor{5d82}
@subsection ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CWI ΓΙΑ 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 ZERO-CLAUSE BSD ΑΔΕΙΑ ΓΙΑ ΤΟΝ ΚΩΔΙΚΑ ΣΤΗΝ ΤΕΚΜΗΡΙΩΣΗ ΤΗΣ PYTHON,,ΣΥΜΦΩΝΙΑ ΑΔΕΙΑΣ CWI ΓΙΑ PYTHON 0 9 0 ΕΩΣ 1 2,Όροι και προϋποθέσεις για την πρόσβαση ή την χρήση της Python με άλλους τρόπους
@anchor{license bsd0}@anchor{5d7c}@anchor{license zero-clause-bsd-license-for-code-in-the-python-documentation}@anchor{5d83}
@subsection ZERO-CLAUSE BSD ΑΔΕΙΑ ΓΙΑ ΤΟΝ ΚΩΔΙΚΑ ΣΤΗΝ ΤΕΚΜΗΡΙΩΣΗ ΤΗΣ PYTHON


@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 Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό,,Όροι και προϋποθέσεις για την πρόσβαση ή την χρήση της Python με άλλους τρόπους,Ιστορία και Άδεια
@anchor{license licenses-and-acknowledgements-for-incorporated-software}@anchor{5d84}@anchor{license otherlicenses}@anchor{5d7d}
@section Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό


Αυτή η ενότητα είναι μια ημιτελής, αλλά αυξανόμενη λίστα αδειών και ευχαριστιών για λογισμικό τρίτων, που ενσωματώνεται στην διανομή της Python.

@menu
* Mersenne Twister:: 
* Sockets: Sockets<2>. 
* Ασύγχρονες socket υπηρεσίες:: 
* Διαχείριση Cookie:: 
* Ανίχνευση εκτέλεσης:: 
* Συναρτήσεις UUencode και UUdecode:: 
* Κλήσεις Απομακρυσμένης Διαδικασίας XML:: 
* test_epoll:: 
* Επιλογή kqueue:: 
* SipHash24:: 
* strtod και dtoa:: 
* OpenSSL: OpenSSL<2>. 
* expat:: 
* libffi:: 
* zlib: zlib<5>. 
* cfuhash:: 
* libmpdec:: 
* W3C C14N σουίτα δοκιμής:: 
* mimalloc:: 
* asyncio: asyncio<16>. 
* Καθολικές Απεριόριστες Ακολουθίες (ΚΑΑ): Καθολικές Απεριόριστες Ακολουθίες ΚΑΑ. 
* Δεσμεύσεις Zstandard:: 
* Profiling module:: 
* Pixi packages:: 

@end menu

@node Mersenne Twister,Sockets<2>,,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license mersenne-twister}@anchor{5d85}
@subsection Mersenne Twister


Η επέκταση @code{_random} C που βρίσκεται κάτω από την ενότητα @ref{c0,,random} περιλαμβάνει έναν κώδικα με βάση μια λήψη από @indicateurl{http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/emt19937ar.html}. Ακολουθούν κατά λέξη τα σχόλια από το αρχικό κώδικα:

@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 Sockets<2>,Ασύγχρονες socket υπηρεσίες,Mersenne Twister,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license sockets}@anchor{5d86}
@subsection Sockets


Η ενότητα @ref{d4,,socket} χρησιμοποιεί τις συναρτήσεις, @code{getaddrinfo()}, και @code{getnameinfo()}, τα οποία έχουν υλοποιηθεί σε διαφορετικά αρχεία από το WIDE Έργο, @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 "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 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 Ασύγχρονες socket υπηρεσίες,Διαχείριση Cookie,Sockets<2>,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license asynchronous-socket-services}@anchor{5d87}
@subsection Ασύγχρονες socket υπηρεσίες


Οι ενότητες @code{test.support.asynchat} και @code{test.support.asyncore} περιέχουν την παρακάτω ειδοποίηση:

@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 Διαχείριση Cookie,Ανίχνευση εκτέλεσης,Ασύγχρονες socket υπηρεσίες,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license cookie-management}@anchor{5d88}
@subsection Διαχείριση Cookie


Η ενότητα @ref{74,,http.cookies} περιέχει την παρακάτω ειδοποίηση:

@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 Ανίχνευση εκτέλεσης,Συναρτήσεις UUencode και UUdecode,Διαχείριση Cookie,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license execution-tracing}@anchor{5d89}
@subsection Ανίχνευση εκτέλεσης


Η ενότητα @ref{106,,trace} περιέχει την παρακάτω ειδοποίηση:

@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 Συναρτήσεις UUencode και UUdecode,Κλήσεις Απομακρυσμένης Διαδικασίας XML,Ανίχνευση εκτέλεσης,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license uuencode-and-uudecode-functions}@anchor{5d8a}
@subsection Συναρτήσεις UUencode και UUdecode


Ο @code{uu} κωδικοποιητής περιέχει την παρακάτω ειδοποίηση:

@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 Κλήσεις Απομακρυσμένης Διαδικασίας XML,test_epoll,Συναρτήσεις UUencode και UUdecode,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license xml-remote-procedure-calls}@anchor{5d8b}
@subsection Κλήσεις Απομακρυσμένης Διαδικασίας XML


Η ενότητα @ref{137,,xmlrpc.client} περιέχει την παρακάτω ειδοποίηση:

@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,Επιλογή kqueue,Κλήσεις Απομακρυσμένης Διαδικασίας XML,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license test-epoll}@anchor{5d8c}
@subsection test_epoll


Η ενότητα @code{test.test_epoll} περιέχει την παρακάτω ειδοποίηση:

@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 Επιλογή kqueue,SipHash24,test_epoll,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license select-kqueue}@anchor{5d8d}
@subsection Επιλογή kqueue


Η ενότητα @ref{c9,,select} περιέχει την παρακάτω ειδοποίηση για την 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 "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 SipHash24,strtod και dtoa,Επιλογή kqueue,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license siphash24}@anchor{5d8e}
@subsection SipHash24


Το αρχείο @code{Python/pyhash.c} περιέχει την υλοποίηση του Marek Majkowski του αλγορίθμου τού Dan Bernstein, SipHash24. Αυτό περιέχει την παρακάτω σημείωση:

@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 και dtoa,OpenSSL<2>,SipHash24,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license strtod-and-dtoa}@anchor{5d8f}
@subsection strtod και dtoa


Το αρχείο @code{Python/dtoa.c}, που παρέχει τις συναρτήσεις dtoa και strtod της C για μετατροπή των C doubles προς και από strings, προέρχεται από το ομώνυμο αρχείο του David M. Gay, προς το παρόν διαθέσιμο από @indicateurl{https://web.archive.org/web/20220517033456/http://www.netlib.org/fp/dtoa.c}. Το αρχικό αρχείο, όπως ανακτήθηκε στις 16 Μαρτίου, 2009, περιέχει τα ακόλουθα πνευματικά δικαιώματα και την ειδοποίηση αδειοδότησης:

@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 και dtoa,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license openssl}@anchor{5d90}
@subsection OpenSSL


Οι μονάδες @ref{6b,,hashlib}, @ref{b2,,posix} και @ref{d8,,ssl} χρησιμοποιούν την βιβλιοθήκη OpenSSL για επιπλέον απόδοση, εάν διατίθενται από το λειτουργικό σύστημα. Επιπλέον, τα προγράμματα εγκατάστασης για την Python για Windows και macOS, ενδέχεται να περιλαμβάνουν ένα αντίγραφο των βιβλιοθηκών OpenSSL, επομένως συμπεριλαμβάνουμε ένα αντίγραφο της άδειας OpenSSL εδώ. Για την έκδοση OpenSSL 3.0 και για νεότερες εκδόσεις που προέρχονται από αυτή, ισχύει η άδεια Apache v2:

@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>,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license expat}@anchor{5d91}
@subsection expat


The @ref{12f,,pyexpat} extension is built using an included copy of the expat
sources unless the build is configured @ref{1d2b,,--with-system-expat}:

@example
Copyright (c) 1998-2000 Thai Open Source Software Center Ltd and Clark Cooper
Copyright (c) 2001-2025 Expat maintainers

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<5>,expat,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license libffi}@anchor{5d92}
@subsection libffi


Η επέκταση της C @code{_ctypes} που βρίσκεται κάτω από την ενότητα  @ref{2d,,ctypes} δημιουργείται χρησιμοποιώντας ένα συμπεριλαμβανόμενο αντίγραφο των πηγών libffi, εκτός εάν η έκδοση έχει την ρύθμιση @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
"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 zlib<5>,cfuhash,libffi,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license zlib}@anchor{5d93}
@subsection zlib


Η επέκταση @ref{13c,,zlib} δημιουργείται χρησιμοποιώντας ένα συμπεριλαμβανόμενου αντίγραφο των πηγών zlib, εάν η έκδοση του zlib που βρίσκεται στο σύστημα είναι πολύ παλιά για να χρησιμοποιηθεί για την κατασκευή:

@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<5>,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license cfuhash}@anchor{5d94}
@subsection cfuhash


Η υλοποίηση του πίνακα κατακερματισμού που χρησιμοποιείται από το @ref{108,,tracemalloc} βασίζεται στο έργο 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,W3C C14N σουίτα δοκιμής,cfuhash,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license libmpdec}@anchor{5d95}
@subsection libmpdec


Η επέκταση @code{_decimal} που βρίσκεται κάτω από την ενότητα @ref{39,,decimal} είναι φτιαγμένη χρησιμοποιώντας ένα συμπεριλαμβανόμενο αντίγραφο της βιβλιοθήκης libmpdec, εκτός αν ή έκδοση έχει ρύθμιση @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 W3C C14N σουίτα δοκιμής,mimalloc,libmpdec,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license w3c-c14n-test-suite}@anchor{5d96}
@subsection W3C C14N σουίτα δοκιμής


Η σουίτα δοκιμής C14N 2.0 στο πακέτο @ref{eb,,test} (@code{Lib/test/xmltestdata/c14n-20/}) ανακτήθηκε από τον ιστότοπο του W3C @indicateurl{https://www.w3.org/TR/xml-c14n2-testcases/} και διανέμεται με την άδεια 3 ρήτρων BSD:

@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<16>,W3C C14N σουίτα δοκιμής,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license mimalloc}@anchor{5d97}@anchor{license mimalloc-license}@anchor{845}
@subsection mimalloc


MIT Άδεια:

@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<16>,Καθολικές Απεριόριστες Ακολουθίες ΚΑΑ,mimalloc,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license asyncio}@anchor{5d98}
@subsection asyncio


Μέρη της ενότητας @ref{b,,asyncio} ενσωματώνονται από το uvloop 0.16@footnote{https://github.com/MagicStack/uvloop/tree/v0.16.0}, η οποία διανέμεται με άδεια MIT:

@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 Καθολικές Απεριόριστες Ακολουθίες ΚΑΑ,Δεσμεύσεις Zstandard,asyncio<16>,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license global-unbounded-sequences-gus}@anchor{5d99}
@subsection Καθολικές Απεριόριστες Ακολουθίες (ΚΑΑ)


Το αρχείο @code{Python/qsbr.c} είναι προσαρμοσμένο από το σύστημα ασφαλούς ανάκτησης μνήμης «Global Unbounded Sequences» του FreeBSD, που υλοποιείται στο subr_smr.c@footnote{https://github.com/freebsd/freebsd-src/blob/main/sys/kern/subr_smr.c}. Το αρχείο διανέμεται υπό την Άδεια 2-Clause BSD:

@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 "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 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 Δεσμεύσεις Zstandard,Profiling module,Καθολικές Απεριόριστες Ακολουθίες ΚΑΑ,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license zstandard-bindings}@anchor{5d9a}
@subsection Δεσμεύσεις Zstandard


Οι δεσμεύσεις Zstandard στα @code{Modules/_zstd} και @code{Lib/compression/zstd} βασίζονται σε κώδικα από τη βιβλιοθήκη pyzstd library@footnote{https://github.com/Rogdham/pyzstd/}, πνευματικής ιδιοκτησίας του Ma Lin και των συνεργατών του. Ο κώδικας της pyzstd διανέμεται υπό την άδεια 3-Clause BSD.

@example
Copyright (c) 2020-present, Ma Lin and contributors.
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 copyright holder 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 HOLDER 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 Profiling module,Pixi packages,Δεσμεύσεις Zstandard,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license profiling-module}@anchor{5d9b}
@subsection Profiling module


The @code{profiling} module includes vendored third-party libraries in
@code{Lib/profiling/sampling/_vendor/} with the following licenses:

`d3-flamegraph'

The d3-flamegraph library is distributed under the Apache License, Version 2.0.
See the OpenSSL section above for the full text of the Apache License Version 2.0.

`d3.js'

The d3.js library contains the following notice:

@example
Copyright 2010-2021 Mike Bostock

Permission to use, copy, modify, and/or distribute this software for any purpose
with or without fee is hereby granted, provided that the above copyright notice
and this permission notice appear in all copies.

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 Pixi packages,,Profiling module,Άδειες και Ευχαριστίες για Ενσωματωμένο Λογισμικό
@anchor{license pixi-packages}@anchor{5d9c}
@subsection Pixi packages


The Pixi package definitions found in @code{Tools/pixi-packages} are derived
from @indicateurl{https://github.com/conda-forge/python-feedstock} which contains the following
license:

@example
BSD-3-Clause license
Copyright (c) 2015-2026, conda-forge contributors
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 copyright holder 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 REGENTS 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Ευρετήριο Μονάδων της Python,Ευρετήριο,Ιστορία και Άδεια,Top
@unnumbered Ευρετήριο Μονάδων της 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.
* annotationlib: 6. Functionality for introspecting annotations
* argparse: 7. Command-line option and argument parsing library.
* array: 8. Space efficient arrays of uniformly typed numeric
                        values.
* ast: 9. Abstract Syntax Tree classes and manipulation.
* asynchat: a. Removed in 3.12.
* asyncio: b. Asynchronous I/O.
* asyncore: c. Removed in 3.12.
* atexit: d. Register and execute cleanup functions.
* audioop: e. Removed in 3.13.
* base64: f. RFC 4648: Base16@comma{} Base32@comma{} Base64 Data
                        Encodings; Base85 and Ascii85
* bdb: 10. Debugger framework.
* binascii: 11. Tools for converting between binary and various ASCII-
                        encoded binary representations.
* bisect: 12. Array bisection algorithms for binary searching.
* builtins: 13. The module that provides the built-in namespace.
* bz2: 14. Interfaces for bzip2 compression and decompression.
* calendar: 15. Functions for working with calendars@comma{} including
                        some emulation of the Unix cal program.
* cgi: 16. Removed in 3.13.
* cgitb: 17. Removed in 3.13.
* chunk: 18. Removed in 3.13.
* cmath: 19. Mathematical functions for complex numbers.
* cmd: 1a. Build line-oriented command interpreters.
* code: 1b. Facilities to implement read-eval-print loops.
* codecs: 1c. Encode and decode data and streams.
* codeop: 1d. Compile (possibly incomplete) Python code.
* collections: 1e. Container datatypes
* collections.abc: 1f. Abstract base classes for containers
* colorsys: 20. Conversion functions between RGB and other color
                        systems.
* compileall: 21. Tools for byte-compiling all Python source files in a
                        directory tree.
* compression: 22. 
* compression.zstd: 23. Low-level interface to compression and decompression
                        routines in the zstd library.
* concurrent.futures: 24. Execute computations concurrently using threads or
                        processes.
* concurrent.interpreters: 25. Multiple interpreters in the same process
* configparser: 26. Configuration file parser.
* contextlib: 27. Utilities for with-statement contexts.
* contextvars: 28. Context Variables
* copy: 29. Shallow and deep copy operations.
* copyreg: 2a. Register pickle support functions.
* crypt: 2b. Removed in 3.13.
* csv: 2c. Write and read tabular data to and from delimited
                        files.
* ctypes: 2d. A foreign function library for Python.
* curses: 2e. An interface to the curses library@comma{} providing
                        portable terminal handling.
* curses.ascii: 2f. Constants and set-membership functions for ASCII
                        characters.
* curses.panel: 30. A panel stack extension that adds depth to curses
                        windows.
* curses.textpad: 31. Emacs-like input editing in a curses window.
* dataclasses: 32. Generate special methods on user-defined classes.
* datetime: 33. Basic date and time types.
* dbm: 34. Interfaces to various Unix "database" formats.
* dbm.dumb: 35. Portable implementation of the simple DBM interface.
* dbm.gnu: 36. GNU database manager
* dbm.ndbm: 37. The New Database Manager
* dbm.sqlite3: 38. SQLite backend for dbm
* decimal: 39. Implementation of the General Decimal Arithmetic
                        Specification.
* difflib: 3a. Helpers for computing differences between objects.
* dis: 3b. Disassembler for Python bytecode.
* distutils: 3c. Removed in 3.12.
* doctest: 3d. Test pieces of code within docstrings.
* email: 3e. Package supporting the parsing@comma{}
                        manipulating@comma{} and generating email messages.
* email.charset: 3f. Character Sets
* email.contentmanager: 40. Storing and Retrieving Content from MIME Parts
* email.encoders: 41. Encoders for email message payloads.
* email.errors: 42. The exception classes used by the email package.
* email.generator: 43. Generate flat text email messages from a message
                        structure.
* email.header: 44. Representing non-ASCII headers
* email.headerregistry: 45. Automatic Parsing of headers based on the field name
* email.iterators: 46. Iterate over a message object tree.
* email.message: 47. The base class representing email messages.
* email.mime: 48. Build MIME messages.
* email.mime.application: 49. 
* email.mime.audio: 4a. 
* email.mime.base: 4b. 
* email.mime.image: 4c. 
* email.mime.message: 4d. 
* email.mime.multipart: 4e. 
* email.mime.nonmultipart: 4f. 
* email.mime.text: 50. 
* email.parser: 51. Parse flat text email messages to produce a message
                        object structure.
* email.policy: 52. Controlling the parsing and generating of messages
* email.utils: 53. Miscellaneous email package utilities.
* encodings: 54. Encodings package
* encodings.idna: 55. Internationalized Domain Names implementation
* encodings.mbcs: 56. Windows ANSI codepage
* encodings.utf_8_sig: 57. UTF-8 codec with BOM signature
* ensurepip: 58. Bootstrapping the "pip" installer into an existing
                        Python installation or virtual environment.
* enum: 59. Implementation of an enumeration class.
* errno: 5a. Standard errno system symbols.
* faulthandler: 5b. Dump the Python traceback.
* fcntl: 5c. The fcntl() and ioctl() system calls.
* filecmp: 5d. Compare files efficiently.
* fileinput: 5e. Loop over standard input or a list of files.
* fnmatch: 5f. Unix shell style filename pattern matching.
* fractions: 60. Rational numbers.
* ftplib: 61. FTP protocol client (requires sockets).
* functools: 62. Higher-order functions and operations on callable
                        objects.
* gc: 63. Interface to the cycle-detecting garbage collector.
* getopt: 64. Portable parser for command line options; support both
                        short and long option names.
* getpass: 65. Portable reading of passwords and retrieval of the
                        userid.
* gettext: 66. Multilingual internationalization services.
* glob: 67. Unix shell style pathname pattern expansion.
* graphlib: 68. Functionality to operate with graph-like structures
* grp: 69. The group database (getgrnam() and friends).
* gzip: 6a. Interfaces for gzip compression and decompression
                        using file objects.
* hashlib: 6b. Secure hash and message digest algorithms.
* heapq: 6c. Heap queue algorithm (a.k.a. priority queue).
* hmac: 6d. Keyed-Hashing for Message Authentication (HMAC)
                        implementation
* html: 6e. Helpers for manipulating HTML.
* html.entities: 6f. Definitions of HTML general entities.
* html.parser: 70. A simple parser that can handle HTML and XHTML.
* http: 71. HTTP status codes and messages
* http.client: 72. HTTP and HTTPS protocol client (requires sockets).
* http.cookiejar: 73. Classes for automatic handling of HTTP cookies.
* http.cookies: 74. Support for HTTP state management (cookies).
* http.server: 75. HTTP server and request handlers.
* idlelib: 76. Implementation package for the IDLE shell/editor.
* imaplib: 77. IMAP4 protocol client (requires sockets).
* imghdr: 78. Removed in 3.13.
* imp: 79. Removed in 3.12.
* importlib: 7a. The implementation of the import machinery.
* importlib.abc: 7b. Abstract base classes related to import
* importlib.machinery: 7c. Importers and path hooks
* importlib.metadata: 7d. Accessing package metadata
* importlib.resources: 7e. Package resource reading@comma{} opening@comma{} and
                        access
* importlib.resources.abc: 7f. Abstract base classes for resources
* importlib.util: 80. Utility code for importers
* inspect: 81. Extract information and source code from live objects.
* io: 82. Core tools for working with streams.
* ipaddress: 83. IPv4/IPv6 manipulation library.
* itertools: 84. Functions creating iterators for efficient looping.
* json: 85. Encode and decode the JSON format.
* json.tool: 86. A command-line interface to validate and pretty-print
                        JSON.
* keyword: 87. Test whether a string is a keyword in Python.
* linecache: 88. Provides random access to individual lines from text
                        files.
* locale: 89. Internationalization services.
* logging: 8a. Flexible event logging system for applications.
* logging.config: 8b. Configuration of the logging module.
* logging.handlers: 8c. Handlers for the logging module.
* lzma: 8d. A Python wrapper for the liblzma compression library.
* mailbox: 8e. Manipulate mailboxes in various formats
* mailcap: 8f. Removed in 3.13.
* marshal: 90. Convert Python objects to streams of bytes and back
                        (with different constraints).
* math: 91. Mathematical functions (sin() etc.).
* math.integer: 92. Integer-specific mathematics functions.
* mimetypes: 93. Mapping of filename extensions to MIME types.
* mmap: 94. Interface to memory-mapped files for Unix and Windows.
* modulefinder: 95. Find modules used by a script.
* msilib: 96. Removed in 3.13.
* msvcrt: 97. Miscellaneous useful routines from the MS VC++
                        runtime.
* multiprocessing: 98. Process-based parallelism.
* multiprocessing.connection: 99. API for dealing with sockets.
* multiprocessing.dummy: 9a. Dumb wrapper around threading.
* multiprocessing.managers: 9b. Share data between process with shared objects.
* multiprocessing.pool: 9c. Create pools of processes.
* multiprocessing.shared_memory: 9d. Provides shared memory for direct access
                                 across processes.
* multiprocessing.sharedctypes: 9e. Allocate ctypes objects from shared memory.
* netrc: 9f. Loading of .netrc files.
* nis: a0. Removed in 3.13.
* nntplib: a1. Removed in 3.13.
* numbers: a2. Numeric abstract base classes (Complex@comma{}
                        Real@comma{} Integral@comma{} etc.).
* operator: a3. Functions corresponding to the standard operators.
* optparse: a4. Command-line option parsing library.
* os: a5. Miscellaneous operating system interfaces.
* os.path: a6. Operations on pathnames.
* ossaudiodev: a7. Removed in 3.13.
* pathlib: a8. Object-oriented filesystem paths
* pathlib.types: a9. pathlib types for static type checking
* pdb: aa. The Python debugger for interactive interpreters.
* pickle: ab. Convert Python objects to streams of bytes and back.
* pickletools: ac. Contains extensive comments about the pickle protocols
                        and pickle-machine opcodes@comma{} as well as some
                        useful functions.
* pipes: ad. Removed in 3.13.
* pkgutil: ae. Utilities for the import system.
* platform: af. Retrieves as much platform identifying data as
                        possible.
* plistlib: b0. Generate and parse Apple plist files.
* poplib: b1. POP3 protocol client (requires sockets).
* posix: b2. The most common POSIX system calls (normally used via
                        module os).
* pprint: b3. Data pretty printer.
* profile: b4. Pure Python profiler (deprecated).
* profiling: b5. Python profiling tools for performance analysis.
* profiling.sampling: b6. Statistical sampling profiler for Python processes.
* profiling.tracing: b7. Deterministic tracing profiler for Python programs.
* pstats: b8. Statistics object for analyzing profiler output.
* pty: b9. Pseudo-Terminal Handling for Unix.
* pwd: ba. The password database (getpwnam() and friends).
* py_compile: bb. Generate byte-code files from Python source files.
* pyclbr: bc. Supports information extraction for a Python module
                        browser.
* pydoc: bd. Documentation generator and online help system.
* queue: be. A synchronized queue class.
* quopri: bf. Encode and decode files using the MIME quoted-
                        printable encoding.
* random: c0. Generate pseudo-random numbers with various common
                        distributions.
* re: c1. Regular expression operations.
* readline: c2. GNU readline support for Python.
* reprlib: c3. Alternate repr() implementation with size limits.
* resource: c4. An interface to provide resource usage information on
                        the current process.
* rlcompleter: c5. Python identifier completion@comma{} suitable for the
                        GNU readline library.
* runpy: c6. Locate and run Python modules without importing them
                        first.
* sched: c7. General purpose event scheduler.
* secrets: c8. Generate secure random numbers for managing secrets.
* select: c9. Wait for I/O completion on multiple streams.
* selectors: ca. High-level I/O multiplexing.
* shelve: cb. Python object persistence.
* shlex: cc. Simple lexical analysis for Unix shell-like languages.
* shutil: cd. High-level file operations@comma{} including copying.
* signal: ce. Set handlers for asynchronous events.
* site: cf. Module responsible for site-specific configuration.
* sitecustomize: d0. 
* smtpd: d1. Removed in 3.12.
* smtplib: d2. SMTP protocol client (requires sockets).
* sndhdr: d3. Removed in 3.13.
* socket: d4. Low-level networking interface.
* socketserver: d5. A framework for network servers.
* spwd: d6. Removed in 3.13.
* sqlite3: d7. A DB-API 2.0 implementation using SQLite 3.x.
* ssl: d8. TLS/SSL wrapper for socket objects
* stat: d9. Utilities for interpreting the results of
                        os.stat()@comma{} os.lstat() and os.fstat().
* statistics: da. Mathematical statistics functions
* string: db. Common string operations.
* string.templatelib: dc. Support for template string literals.
* stringprep: dd. String preparation@comma{} as per RFC 3453
* struct: de. Interpret bytes as packed binary data.
* subprocess: df. Subprocess management.
* sunau: e0. Removed in 3.13.
* symtable: e1. Interface to the compiler's internal symbol tables.
* sys: e2. Access system-specific parameters and functions.
* sys.monitoring: e3. Access and control event monitoring
* sysconfig: e4. Python's configuration information
* syslog: e5. An interface to the Unix syslog library routines.
* tabnanny: e6. Tool for detecting white space related problems in
                        Python source files in a directory tree.
* tarfile: e7. Read and write tar-format archive files.
* telnetlib: e8. Removed in 3.13.
* tempfile: e9. Generate temporary files and directories.
* termios: ea. POSIX style tty control.
* test: eb. Regression tests package containing the testing suite
                        for Python.
* test.regrtest: ec. Drives the regression test suite.
* test.support: ed. Support for Python's regression test suite.
* test.support.bytecode_helper: ee. Support tools for testing correct bytecode
                                generation.
* test.support.import_helper: ef. Support for import tests.
* test.support.os_helper: f0. Support for os tests.
* test.support.script_helper: f1. Support for Python's script execution tests.
* test.support.socket_helper: f2. Support for socket tests.
* test.support.threading_helper: f3. Support for threading tests.
* test.support.warnings_helper: f4. Support for warnings tests.
* textwrap: f5. Text wrapping and filling
* threading: f6. Thread-based parallelism.
* time: f7. Time access and conversions.
* timeit: f8. Measure the execution time of small code snippets.
* tkinter: f9. Interface to Tcl/Tk for graphical user interfaces
* tkinter.colorchooser: fa. Color choosing dialog
* tkinter.commondialog: fb. Tkinter base class for dialogs
* tkinter.dnd: fc. Tkinter drag-and-drop interface
* tkinter.filedialog: fd. Dialog classes for file selection
* tkinter.font: fe. Tkinter font-wrapping class
* tkinter.messagebox: ff. Various types of alert dialogs
* tkinter.scrolledtext: 100. Text widget with a vertical scroll bar.
* tkinter.simpledialog: 101. Simple dialog windows
* tkinter.ttk: 102. Tk themed widget set
* token: 103. Constants representing terminal nodes of the parse
                        tree.
* tokenize: 104. Lexical scanner for Python source code.
* tomllib: 105. Parse TOML files.
* trace: 106. Trace or track Python statement execution.
* traceback: 107. Print or retrieve a stack traceback.
* tracemalloc: 108. Trace memory allocations.
* tty: 109. Utility functions that perform common terminal control
                        operations.
* turtle: 10a. An educational framework for simple graphics
                        applications
* turtledemo: 10b. A viewer for example turtle scripts
* types: 10c. Names for built-in types.
* typing: 10d. Support for type hints (see :pep:`484`).
* unicodedata: 10e. Access the Unicode Database.
* unittest: 10f. Unit testing framework for Python.
* unittest.mock: 110. Mock object library.
* urllib: 111. 
* urllib.error: 112. Exception classes raised by urllib.request.
* urllib.parse: 113. Parse URLs into or assemble them from components.
* urllib.request: 114. Extensible library for opening URLs.
* urllib.response: 115. Response classes used by urllib.
* urllib.robotparser: 116. Load a robots.txt file and answer questions about
                        fetchability of other URLs.
* usercustomize: 117. 
* uu: 118. Removed in 3.13.
* uuid: 119. UUID objects (universally unique identifiers)
                        according to RFC 9562
* venv: 11a. Creation of virtual environments.
* warnings: 11b. Issue warning messages and control their disposition.
* wave: 11c. Provide an interface to the WAV sound format.
* weakref: 11d. Support for weak references and weak dictionaries.
* webbrowser: 11e. Easy-to-use controller for web browsers.
* winreg: 11f. Routines and objects for manipulating the Windows
                        registry.
* winsound: 120. Access to the sound-playing machinery for Windows.
* wsgiref: 121. WSGI Utilities and Reference Implementation.
* wsgiref.handlers: 122. WSGI server/gateway base classes.
* wsgiref.headers: 123. WSGI response header tools.
* wsgiref.simple_server: 124. A simple WSGI HTTP server.
* wsgiref.types: 125. WSGI types for static type checking
* wsgiref.util: 126. WSGI environment utilities.
* wsgiref.validate: 127. WSGI conformance checker.
* xdrlib: 128. Removed in 3.13.
* xml: 129. Package containing XML processing modules
* xml.dom: 12a. Document Object Model API for Python.
* xml.dom.minidom: 12b. Minimal Document Object Model (DOM) implementation.
* xml.dom.pulldom: 12c. Support for building partial DOM trees from SAX
                        events.
* xml.etree.ElementInclude: 12d. 
* xml.etree.ElementTree: 12e. Implementation of the ElementTree API.
* xml.parsers.expat: 12f. An interface to the Expat non-validating XML parser.
* xml.parsers.expat.errors: 130. 
* xml.parsers.expat.model: 131. 
* xml.sax: 132. Package containing SAX2 base classes and convenience
                        functions.
* xml.sax.handler: 133. Base classes for SAX event handlers.
* xml.sax.saxutils: 134. Convenience functions and classes for use with SAX.
* xml.sax.xmlreader: 135. Interface which SAX-compliant XML parsers must
                        implement.
* xmlrpc: 136. Server and client modules implementing XML-RPC.
* xmlrpc.client: 137. XML-RPC client access.
* xmlrpc.server: 138. Basic XML-RPC server implementations.
* zipapp: 139. Manage executable Python zip archives
* zipfile: 13a. Read and write ZIP-format archive files.
* zipimport: 13b. Support for importing Python modules from ZIP
                        archives.
* zlib: 13c. Low-level interface to compression and decompression
                        routines compatible with gzip.
* zoneinfo: 13d. IANA time zone support
@end menu


@node Ευρετήριο,,Ευρετήριο Μονάδων της Python,Top
@unnumbered Ευρετήριο


@printindex ge

@anchor{using/cmdline audit_event_cpython_run_stdin_1}@w{                              }
@anchor{library/stdtypes range index}@w{                              }
@anchor{library/stdtypes list insert}@w{                              }
@anchor{aba}@w{                              }
@anchor{library/stdtypes list pop}@w{                              }
@anchor{using/cmdline audit_event_cpython_run_stdin_0}@w{                              }
@anchor{library/stdtypes tuple count}@w{                              }
@anchor{library/stdtypes list remove}@w{                              }
@anchor{library/sys script_path}@w{                              }
@anchor{49b1}@w{                              }
@anchor{49ad}@w{                              }
@anchor{library/sys audit_event_cpython_remote_debugger_script_0}@w{                              }
@anchor{1765}@w{                              }
@anchor{7f9}@w{                              }
@anchor{1766}@w{                              }
@anchor{1541}@w{                              }
@anchor{2213}@w{                              }
@anchor{49ae}@w{                              }
@anchor{49b0}@w{                              }
@anchor{49a9}@w{                              }
@anchor{1b8a}@w{                              }
@anchor{library/stdtypes list clear}@w{                              }
@anchor{49ac}@w{                              }
@anchor{49b8}@w{                              }
@anchor{16db}@w{                              }
@anchor{library/time audit_event_time_sleep_0}@w{                              }
@anchor{using/cmdline audit_event_cpython_run_file_0}@w{                              }
@anchor{49af}@w{                              }
@anchor{1c61}@w{                              }
@anchor{49ba}@w{                              }
@anchor{library/unittest unittest tearDownModule}@w{                              }
@anchor{library/stdtypes tuple index}@w{                              }
@anchor{library/stdtypes list extend}@w{                              }
@anchor{library/ctypes audit_event_ctypes_memoryview_at_0}@w{                              }
@anchor{library/asyncio audit_event_cpython_run_stdin_2}@w{                              }
@anchor{library/stdtypes list append}@w{                              }
@anchor{library/_thread start_new_thread}@w{                              }
@anchor{7f8}@w{                              }

@c %**end of body
@bye
